` + +**2.4.3 Focus order (A)** +- Focus order matches visual and logical reading order + +**2.4.4 Link purpose in context (A)** +- Link purpose is clear from the link text alone, or from text + immediate surrounding context +- Avoid "click here," "read more," "learn more" without context + +**2.4.5 Multiple ways (AA)** +- Multiple ways to find content (sitemap, search, navigation menu) + +**2.4.6 Headings and labels (AA)** +- Headings and labels are descriptive + +**2.4.7 Focus visible (AA)** +- Keyboard focus indicator is visible +- Audit check: Tab through the page; can you always see where focus is? + +### 2.5 Input modalities + +**2.5.1 Pointer gestures (A)** +- Multipoint or path-based gestures have single-point alternative + +**2.5.2 Pointer cancellation (A)** +- Down-event does not trigger action; action triggers on up-event or has way to abort + +**2.5.3 Label in name (A)** +- Accessible name (for screen readers) contains the visible label text + +**2.5.4 Motion actuation (A)** +- Motion-triggered functionality has UI alternative and can be disabled + +--- + +## Principle 3: Understandable + +### 3.1 Readable + +**3.1.1 Language of page (A)** +- Page language declared in HTML: `<html lang="en">` + +**3.1.2 Language of parts (AA)** +- Inline foreign-language passages marked: `<span lang="fr">...</span>` + +### 3.2 Predictable + +**3.2.1 On focus (A)** +- Receiving focus does not change context (no auto-submit, no unexpected navigation) + +**3.2.2 On input (A)** +- Changing a setting does not automatically change context unless user is warned + +**3.2.3 Consistent navigation (AA)** +- Navigation appears in the same relative order across pages + +**3.2.4 Consistent identification (AA)** +- Components with the same function are identified consistently + +### 3.3 Input assistance + +**3.3.1 Error identification (A)** +- Errors are identified and described in text (not just color or icon) + +**3.3.2 Labels or instructions (A)** +- Labels or instructions provided for inputs requiring user input + +**3.3.3 Error suggestion (AA)** +- When errors occur and suggestions are known, suggestions are provided + +**3.3.4 Error prevention (legal, financial, data) (AA)** +- For pages causing legal commitments or financial transactions: submissions are reversible, checked for errors, OR confirmed before final submission + +--- + +## Principle 4: Robust + +### 4.1 Compatible + +**4.1.1 Parsing (A) [removed in 2.2 but still in 2.1]** +- Markup is well-formed (no duplicate IDs, properly nested elements) + +**4.1.2 Name, role, value (A)** +- For all UI components, name and role can be programmatically determined; states, properties, and values can be set +- Use semantic HTML, ARIA where needed + +**4.1.3 Status messages (AA)** +- Status messages can be programmatically determined through role or properties so they can be announced by assistive technology +- Use `role="status"`, `role="alert"`, or `aria-live` + +--- + +## Audit check summary + +For each criterion, the audit needs to: + +1. **Identify the requirement** (what does WCAG ask for?) +2. **Test against the site** (does the site meet it?) +3. **Document failures** (which pages, which elements, what's wrong) +4. **Specify the fix** (what specific change resolves it) +5. **Assign severity** (P0 critical, P1 important, P2 minor, P3 polish) +6. **Estimate effort** (small, medium, large) + +A complete audit covers all 30+ AA criteria. Most sites fail 5 to 15 of them on first audit. Don't try to fix all at once. Sequence by severity and impact. + +--- + +## What WCAG does NOT cover + +WCAG is a floor, not a ceiling. Some accessibility considerations are outside its scope: + +- **Cognitive accessibility nuances** (reading level, attention, memory) - some basics in 3.1, but limited +- **Audience-specific needs** (the cognitive support a user with dyslexia needs vs. a user with autism) +- **Mental models** (whether the navigation makes sense to your specific audience) + +For these, supplement WCAG with usability testing including users with disabilities, and with specific design patterns aimed at cognitive accessibility. diff --git a/dist/pi/.agents/skills/ads-creative-development/SKILL.md b/dist/pi/.agents/skills/ads-creative-development/SKILL.md new file mode 100644 index 0000000..7fb0a7b --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/SKILL.md @@ -0,0 +1,231 @@ +--- +name: ads-creative-development +description: "How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting." +category: marketing +catalog_summary: "Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter" +display_order: 2 +--- + +# Ads Creative Development + +A senior creative strategist's playbook for producing ad creative that performs. + +Performance creative is a different discipline from brand creative. Brand work optimizes for memorability, emotional resonance, and distinctive identity. Performance creative optimizes for stopping the scroll, communicating value in three seconds, and producing a click. Both matter. Mixing them up costs money. Brand creative running as performance ads bleeds budget; performance creative running as brand ads erodes equity. + +This skill is the discipline that produces performance creative without diluting brand. It assumes you know your audience and offer (see `paid-media-strategy`). It assumes you have brand-voice guidance (see `brand-voice`). The hard part is the systematic production of variations that test cleanly and ship without manual approval bottlenecks, and that is what is here. + +When to use this skill: producing ad creative for paid campaigns, planning a creative testing cycle, diagnosing creative fatigue, or auditing why creative is not converting. + +--- + +## What this skill is for + +This skill spans creative production, hook patterns, testing methodology, and fatigue diagnosis. It does not cover paid media strategy (use `paid-media-strategy`), result interpretation (use `ads-performance-analytics` once it ships), or brand voice authoring (use `brand-voice`). Pair this skill with the relevant integrations microsite for platform-specific MCP details and example prompts. + +The audience is an ad creative producer, a growth marketer responsible for creative testing, or an agency producing creative at scale. The voice is tactical. There is no "consider every option." Performance creative has shape, and a senior practitioner can map a brief to a production-ready variation matrix in an afternoon. + +--- + +## Performance vs brand creative + +The two disciplines optimize for different metrics. Brand creative optimizes for memorability, distinctiveness, and emotional resonance over months. Performance creative optimizes for scroll-stop in 1 second, value comprehension by 5 seconds, and click by 15. + +The shared layer. Both should reflect brand voice. Both should look like they came from the same brand. The difference is structure, pacing, and where the creative effort concentrates. + +The failure mode. Most agency creative tries to do both and does neither well. The brand video that runs as a 60-second performance ad has a strong narrative arc and zero CTR. The performance ad that ignores brand voice converts but trains the audience to not recognize the brand. The fix is not to compromise; it is to produce both, in their respective formats, with shared voice and divergent structure. + +A worked example. A premium coffee brand running a 60-second YouTube awareness ad gets to build the world: cinematography, the founder's hands, slow-pour rituals, music that sets a mood. That same brand running a 15-second Meta Reels performance ad gets 1 second to stop the scroll (a visual pattern interrupt: the steam rising from a cup, fast cut, brand logo dropping in), 4 seconds to clarify the offer (the new flavor, the price, the deal), 8 seconds for social proof (three customer-style testimonials, fast cuts), and 2 seconds for CTA (shop now, end card with logo). Same voice. Different structure. Different pacing. Different creative effort distribution. + +--- + +## Hook patterns: the first 3 seconds + +The biggest lever in performance creative. If the hook fails, no amount of body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. The hook is the whole game until the body justifies why the user kept watching. + +Twelve hook patterns work consistently. Detail in [`references/hook-pattern-library.md`](references/hook-pattern-library.md). + +1. **Problem-agitate-solve.** Open with the problem the audience feels. Agitate by naming the consequence. Solve with the offer. Works when the audience recognizes the pain. +2. **Direct callout to audience.** "If you are a B2B founder running paid ads..." Triggers self-identification. Works when the audience is narrow and self-aware. +3. **Contrarian claim.** "Stop using lookalike audiences." Hooks attention by violating expectation. Works when the audience has heard the conventional wisdom too often. +4. **Result-led.** "How we cut CAC 40% in 30 days." Specific number, specific timeframe. Works when the result is real and documented. +5. **Curiosity gap.** "The mistake 80% of marketers make..." Promises a payoff after the gap. Works when the gap is real; clickbait without payoff trains the audience to scroll past. +6. **Social proof at top.** "Used by 10,000+ teams." Validation before pitch. Works when the proof is impressive enough to do the heavy lifting. +7. **Visual pattern interrupt.** A surprising visual that does not match the platform's usual feed flow. Works on TikTok and Reels where the pattern is fast and the interrupt is louder. +8. **Question that hits intent.** "Tired of paying $400 for project management software?" The question pre-qualifies the audience. Works when the question matches a real search query the audience has typed. +9. **Number-led.** "3 changes that doubled our ROAS." Lists trigger the brain's pattern-completion instinct. Works for educational content; less so for product ads. +10. **Personal story open.** "Last year I was burning $50K a month on Meta ads with no return..." First-person specificity is hard to skip. Works when the story is real and the conclusion is action-relevant. +11. **Comparison.** "X vs Y: which actually works." Pits two options against each other. Works when the audience is in evaluation mode. +12. **Behind-the-scenes / process.** "How we onboard a new client in 7 days..." Demystifies the work. Works when the process is the differentiator. + +For each pattern, the anti-pattern is the same: a hook that does not actually hook. Generic openings ("In today's world...", brand-logo cards, slow zooms over title cards) train the audience to scroll past. The first second is for the hook. The brand can wait. + +--- + +## Format selection + +Different formats fit different combinations of audience, platform, and offer. + +- **Static image.** Best for simple value props, retargeting, and quick test cycles. Lowest production cost. Limited room for narrative. +- **Carousel.** Best for multi-feature products, educational content, and B2B SaaS. Each card carries one idea; users swipe through at their own pace. Strong for considered purchases. +- **Video (in-feed).** Best for demonstration, story, and broad audiences. Higher production cost. Performance correlates strongly with hook quality. +- **UGC-style video.** Best for trust building, social proof, and lower production cost. Looks like an ordinary user filmed it. Especially strong on TikTok and Reels. +- **Stories or Reels (vertical 9:16).** Best for TikTok, Instagram, and Snap. Native to the platform's primary surface. Skipping anything not vertical here is leaving performance on the table. +- **Spark Ads (boosted organic).** Best for TikTok. Promotes an existing organic post as an ad. Retains organic engagement signals; consistently outperforms pure paid creative on TikTok. + +The decision rule. Match format to platform native style and to audience consumption pattern. Detail in [`references/format-decision-matrix.md`](references/format-decision-matrix.md). + +--- + +## Video pacing + +Video performance correlates more with pacing than with production value. A well-paced phone-shot video outperforms a poorly-paced agency-produced spot. Specific guidance for the 15-second performance video. + +| Time window | Job | +|---|---| +| 0 to 1s | Hook. Visual pattern interrupt plus audio hook. | +| 1 to 3s | Clarify what this is. Brand and offer registered. | +| 3 to 7s | Value proposition. The problem-solution moment. | +| 7 to 12s | Social proof or demonstration. Show, do not just tell. | +| 12 to 15s | CTA. End card with logo and call to action. | + +Anything past 15 seconds in a performance video is awareness territory. Performance creative should resolve by 15s. + +Platform variations. TikTok performs at 15 to 30 seconds; the platform tolerates longer because the audience is in a longer dwell mode. Meta In-Feed performs at 15s. YouTube Shorts at 15 to 60s. Long-form YouTube at 30s+ for awareness, with the value prop still front-loaded. + +--- + +## Variation systems + +The systematic way to produce 20 to 50 ad variations from one core concept without manual creative authoring per variation. + +The decomposition. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. + +- 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. +- Most are not worth shipping. The matrix narrows to 20 to 40 variations the team will actually run. +- Asset library structure: organize by concept, not by date. `concepts/launch-2026/hooks/`, `concepts/launch-2026/bodies/`, etc. + +Naming convention. Use a structured naming system so the analyst can join performance data back to creative components. Example: `launch2026_meta-reel_hookA_bodyB_ctaC_v1`. The analyst pulls the report, joins on the naming components, and identifies which hook is winning across body and CTA combinations. + +Worked example in [`references/creative-variation-templates.md`](references/creative-variation-templates.md). A half-day production session produces 40 variations from one core concept by using the matrix. Without the matrix, the same 40 variations require five days of authoring overhead. + +--- + +## Sequential testing methodology + +The waterfall. Most teams test everything at once and lose the signal. Sequential testing isolates the variable that matters at each step. + +1. **Test hooks first.** 5 to 10 hook variants, same body, same CTA, same format. The hook is the biggest lever; isolate it first. +2. **Winners advance to body testing.** Top 2 to 3 hooks each get 5 to 10 body variants. Now you are testing what the audience watches after the hook lands. +3. **Winners advance to CTA testing.** Top hook plus body combinations each get 3 to 5 CTAs. Smaller search space at this stage; the differences are usually marginal. +4. **Winners advance to format testing.** Top combinations each render in 2 to 3 formats (vertical video, carousel, static). Catches format-specific drop-offs. +5. **Top combos go into evergreen rotation.** Two to four winners run on rotation. Refresh on the cadence below. + +The common mistake. Testing all variables at once. Variance compounds; the team cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential is slower but produces real learnings the team can apply to the next campaign. + +Detail in [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md). + +--- + +## Creative fatigue detection + +Fatigue is real. The same audience seeing the same creative six times a week tunes it out, or worse, develops negative associations. Five signals indicate fatigue. + +1. **Frequency above 4 to 5 per user per week.** Set explicit caps. Defaults are usually too high. +2. **CTR declining 30%+ week over week.** The creative is no longer fresh to the audience. +3. **CPM increasing without audience saturation explanation.** The platform is having to bid harder to deliver impressions because engagement signals are weakening. +4. **Negative comments increasing.** A direct user signal that the audience is irritated. +5. **Hide ratio increasing.** Meta exposes this as "negative feedback rate." TikTok exposes "not interested" rate. + +Refresh cadence. Weekly for high-spend campaigns ($50K+/month). Biweekly for medium spend. Monthly for low spend. The economics: producing a fresh variant is cheaper than running tired creative for one extra week. + +The decision tree. If a top performer's metrics are still strong but frequency is climbing, ship variants of the same concept (same hook structure, different copy and visuals). If the metrics are dropping, retire the concept and ship a new one. Detail in [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md). + +--- + +## Brand-voice alignment without conversion dilution + +The tension. Brand voice can feel off-brand when squeezed into 15-second ads. The fix is hierarchy, not compromise. + +Voice attributes that survive compression. Tone (playful, serious, expert, irreverent). Cadence (short sentences vs long-form). Vocabulary (industry-specific or accessible). Visual treatment (color, type, motion language). These survive in 15s because they live in the texture of every frame. + +Voice attributes that do not survive compression. Deep narrative arcs. Complex metaphors. Layered humor that requires setup. Long-form storytelling. These need 30s+ of runtime to land. Forcing them into 15s produces diluted versions that read as off-brand. + +The hierarchy. Brand voice in every frame; performance discipline in the structure. The brand voice shows up in tone, cadence, vocabulary, and visual treatment. The performance discipline shows up in pacing, hook strength, and CTA placement. + +A worked example. A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs three creatives. The 60-second YouTube awareness piece has the founder talking to camera, plain language, contrarian framing of the category. The 15-second Meta performance ad has fast cuts, plain language captions on screen, contrarian hook ("Stop overpaying for project management software"), specific value prop, CTA. The static carousel has 6 cards, plain language, contrarian opening card, value prop progression, CTA on the last card. Same voice. Different structure. None feels off-brand to a customer who has seen all three. + +Detail in [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md). + +--- + +## Platform-specific creative norms + +Each platform has native norms. Violating them tanks performance. The fix is producing platform-native, not repurposing. + +**Meta (Facebook plus Instagram).** In-feed visual hierarchy. Captions on by default (most users watch sound-off). Native-feeling production beats studio production for direct response. Vertical 9:16 for Reels and Stories; 1:1 or 4:5 for in-feed. CTAs above the fold or in first 2 lines of caption. + +**TikTok.** Vertical 9:16 only. Native-creator aesthetic; phone-shot is the default. Fast cuts every 1 to 2 seconds. Captions for accessibility. Music-driven; trending sounds compound reach but expire fast. Spark Ads (boost an existing organic post) consistently outperform pure paid because they retain organic engagement signal. + +**LinkedIn.** Professional tone. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. B2B vocabulary is fine; consumer-style copy reads as off-platform. Thought leadership angle works; product pitches feel salesy. + +**Google Search.** Text-only headlines plus descriptions. Character limits are real constraints (30-character headlines, 90-character descriptions). RSA (Responsive Search Ads) optimization rewards 15+ headline variations and 4+ descriptions; the platform mixes them. + +**Google Display and YouTube.** Depends on placement. YouTube allows longer narrative (15s to 6m); Display is fast banner-style. Skippable YouTube ads need to earn the next second of attention; non-skippable annoys. + +Detail in [`references/platform-creative-norms.md`](references/platform-creative-norms.md). + +--- + +## Common failures + +Eight patterns recur across creative production work. The short version. + +- "We made a beautiful brand video and ran it as performance." Wrong format and length for the channel. Brand video belongs in awareness; performance ads need the 15-second structure. +- "All our ads use the same hook." Saturation. Ship five to ten hook variants per concept and rotate. +- "Our ads stopped working after 3 days." Fatigue plus narrow audience. Either ship more variants or expand the audience; usually both. +- "We A/B tested 50 ad variations." Too many simultaneous variables. Run sequential tests instead. +- "Creative passes brand approval but underperforms." Brand discipline at the cost of performance discipline. The hierarchy is wrong; voice in every frame, performance in the structure. +- "TikTok ad uses Meta-style production." Platform norm violation. TikTok rejects polished ad creative; phone-shot native wins. +- "Our hooks all start with the brand logo." Kills the first-3-second hook. Brand logo belongs at second 1 to 3 (after the hook lands), not at second 0. +- "We never refresh creative because the old set still works ok." Incremental loss compounds. CTR decay is gradual; the team that does not refresh discovers a 40% performance gap when they finally check. + +--- + +## The framework: 10 considerations for sustainable creative production + +When designing or auditing ad creative, walk these 10 considerations. + +1. **Performance vs brand.** Name what this creative is optimizing for; do not mix. +2. **Hook strength.** First 3 seconds. Scroll-stopping. Specific. +3. **Format-platform fit.** Native to the channel. +4. **Pacing.** Value prop hits within 5 seconds; CTA by 15s. +5. **Variation system.** Matrix-based, not ad-hoc. +6. **Sequential testing.** Hooks, then bodies, then CTAs, then formats. +7. **Fatigue monitoring.** Frequency, CTR decay, CPM trend, negative feedback. +8. **Brand-voice alignment.** Voice that survives compression; performance in the structure. +9. **Platform creative norms.** Vertical for short-video platforms, captions on, native production. +10. **Refresh cadence.** Weekly to monthly by spend tier. + +The output of the framework is a production plan. A list of variations to ship in the next testing cycle, the testing waterfall to run, the fatigue thresholds that trigger refresh, and the platform-specific norms the variations respect. Three answers from the framework: ship as planned, revise the plan, or stop because a precondition is missing. + +--- + +## Reference files + +- [`references/hook-pattern-library.md`](references/hook-pattern-library.md) - Twelve hook patterns with worked examples and anti-patterns for each. +- [`references/format-decision-matrix.md`](references/format-decision-matrix.md) - Audience-objective context to recommended format with reasoning and common alternatives. +- [`references/creative-variation-templates.md`](references/creative-variation-templates.md) - Matrix-based production system, naming conventions, asset library structure, half-day worked example. +- [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md) - Sequential testing waterfall with per-stage variant counts, durations, and winner-advancement criteria. +- [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md) - Five fatigue signals with thresholds and refresh decision tree. +- [`references/platform-creative-norms.md`](references/platform-creative-norms.md) - Per-platform aspect ratios, lengths, audio expectations, caption norms, and native-aesthetic anti-patterns. +- [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md) - Voice attributes that survive 15-second compression vs those that do not, with a four-format worked example. + +--- + +## Closing: the hook is the whole game + +In performance creative, the hook is the whole game. If the hook fails, no body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. + +Spend the disproportionate creative effort on the first 3 seconds. The rest is delivery. The team that puts 60% of its creative effort into the hook and 40% into everything else outperforms the team that distributes effort evenly. The team that puts 90% of its effort into hooks and 10% into delivery beats both, as long as it ships enough variations for the testing waterfall to find which hooks actually work. + +When in doubt, ship the variant. A weak variant ships; a perfect variant never does. The sequential testing waterfall finds the winners; the variation system makes shipping cheap. The asymmetric cost of inaction is real; the asymmetric cost of shipping a marginal variant is small. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md b/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md new file mode 100644 index 0000000..2be0aa0 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md @@ -0,0 +1,101 @@ +# Brand voice plus performance balance + +How to keep brand voice intact at 15-second performance scale without diluting conversion. + +The tension. Brand voice often feels off-brand when squeezed into a 15-second ad. The instinct is to compromise: water down the voice for the format, or sacrifice the format for the voice. Both are wrong. The fix is hierarchy. + +--- + +## Voice attributes that survive compression + +Four attributes carry the brand voice in 15 seconds without consuming runtime. + +**Tone.** Playful, serious, expert, irreverent, warm, blunt. Tone lives in the texture of every frame; it does not need narrative space to land. A blunt brand can write blunt captions in 15 seconds. A warm brand can shoot warm faces. + +**Cadence.** Short sentences vs long-form. Short and punchy fits the 15-second frame; long sentences need 30+ seconds to land. The brand whose voice is short and punchy is naturally well-fit for performance creative. + +**Vocabulary.** Industry-specific or accessible. Plain or formal. The brand voice that uses certain words and not others can preserve that vocabulary in any format. + +**Visual treatment.** Color, type, motion language, photographic style. Visual identity survives in 1 second; it survives in 15. + +--- + +## Voice attributes that do not survive compression + +Three attributes need runtime to land. Forcing them into 15-second performance creates diluted versions that read as off-brand. + +**Deep narrative arcs.** Hero's journey, character development, story-with-resolution. These need 30 to 60 seconds minimum. A 15-second compression of a narrative is the trailer, not the story. + +**Complex metaphors.** A brand whose voice relies on extended metaphors needs runtime to set up the metaphor and pay it off. 15 seconds of metaphor is the setup with no payoff; the audience leaves confused. + +**Layered humor that requires setup.** Jokes that depend on a long setup work in long-form. In 15 seconds the joke is too rushed to land. Punchline-style humor works; setup-dependent humor does not. + +The implication. A brand whose voice is built on narrative depth or complex metaphor will struggle with performance creative. The fix is not to compromise the voice; the fix is to use the appropriate format for the voice. Long-form awareness ads carry the narrative; performance creative carries the tone, cadence, vocabulary, and visual treatment without trying to land the full narrative in 15 seconds. + +--- + +## The hierarchy + +Brand voice in every frame. Performance discipline in the structure. + +**Voice in every frame.** The tone, cadence, vocabulary, and visual treatment of every clip, caption, and CTA reflects the brand. The audience watching three different ad variations should recognize the same brand across all of them. + +**Performance in the structure.** The pacing, hook strength, value-prop placement, and CTA placement follow performance norms. Hook in 1 to 3 seconds. Value prop by 5 seconds. Social proof or demo by 7 to 12. CTA by 15. The structure is platform-driven, not voice-driven. + +The two layers do not compete. Voice operates at the texture level; structure operates at the timing level. A blunt brand can be blunt in 1 second (texture) and structured in performance pacing (timing). + +--- + +## Worked example: same voice, four formats + +A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs four creatives. + +### 60-second YouTube awareness piece + +The founder talks to camera. Plain language. Contrarian framing of the category. The opening question hooks; the middle 40 seconds tell the story of why the brand exists; the closing 10 seconds invite the audience to learn more. + +Voice carries because there is runtime. Structure is narrative-led. + +### 15-second Meta Reels performance ad + +Fast cuts. Plain language captions on screen. Contrarian hook in second 1 ("Stop overpaying for project management software"). Specific value prop in seconds 4 to 7 ("$10 per user per month, all features"). Social proof in seconds 8 to 12 ("Used by 10,000+ teams"). CTA in seconds 13 to 15 ("Start your free trial"). + +Voice carries through tone (direct, plain) and visual treatment (consistent typography). Structure is performance-led. + +### 15-second TikTok Spark Ad + +Phone-shot. Creator-style. Plain language captions. Contrarian opening line spoken to camera ("Most project management tools cost too much"). Demonstration in seconds 4 to 9 (creator showing the product on their laptop). CTA in seconds 12 to 15. + +Voice carries through tone and the conversational cadence. Production aesthetic is platform-native (phone-shot, not studio). + +### Static carousel (6 cards) + +Card 1: Contrarian opening ("Most PM tools cost too much"). Card 2: The number ($10/user). Card 3: The features. Card 4: The customer logos. Card 5: The story (one customer who switched). Card 6: CTA. + +Voice carries through plain-language copy and consistent visual treatment. Structure is card-by-card progression, not narrative. + +The check. A customer who has seen all four pieces should recognize them as the same brand. The voice is consistent. The structure is format-appropriate. None of the four feels off-brand. + +--- + +## When voice and performance genuinely conflict + +Two situations where the conflict is real, not solvable. + +**The brand voice is built on narrative depth.** Some brands (especially heritage brands, premium brands, brands with founders who write long-form) have voices that genuinely require runtime. Performance creative for these brands often works better as static or carousel (where the depth lives in the copy) than as 15-second video (where the runtime is too short for the voice). + +**The performance objective requires a tone the brand does not use.** Direct response often pushes toward urgency, scarcity, and aggressive CTAs. A brand whose voice is calm and considered will read as off-brand if the performance ad uses high-urgency CTAs. The fix is to push back on the performance team's CTA defaults; calm-and-considered brands can have calm-and-considered CTAs that still convert when the offer is right. + +The default. Resolve the conflict by adjusting the format choice (use static or carousel for narrative-deep brands; use longer awareness pieces alongside performance) or by adjusting the CTA register (calm CTAs for calm brands). Do not compromise the voice; the voice is the long-term asset. Do not compromise the performance; the performance is the short-term revenue. Find the format and register that keeps both intact. + +--- + +## Common mistakes + +**Watering down the voice for the format.** A brand whose voice is sharp produces a soft 15-second ad to "fit the format." The audience does not recognize the brand; the ad converts marginally; the brand erodes. + +**Sacrificing the format for the voice.** A brand whose voice is narrative-deep produces a 60-second performance ad with no hook. The audience scrolls past in 1 second; the voice never lands. + +**Treating voice and structure as the same axis.** Voice is texture; structure is timing. They do not compete unless the voice depends on structure (narrative-led brands), in which case the format choice is the lever, not the voice itself. + +**No brand-voice review on performance creative.** The performance team produces ads that convert but read as off-brand. A 5-minute brand-voice review on every variation catches the off-brand drift before it ships. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md b/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md new file mode 100644 index 0000000..01f6754 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md @@ -0,0 +1,123 @@ +# Creative variation templates + +The matrix-based production system. How to produce 20 to 50 ad variations from one core concept in a half-day session. + +The principle. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. The matrix lets you ship dozens of variations from minimal authoring overhead, which is what the sequential testing waterfall requires. + +--- + +## The decomposition + +A single creative is composed of independent components. + +| Component | Example | Authoring cost | +|---|---|---| +| Concept | Theme or message ("the project management tax") | High (the strategy work) | +| Hook | First 3 seconds, scroll-stop | Medium (per variant) | +| Body | The middle 5 to 10 seconds | Medium | +| CTA | The closing call to action | Low | +| Format | Vertical video, carousel, static, etc. | Medium (rendering) | + +The math. 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. Most are not worth shipping; the matrix typically narrows to 20 to 40 the team will actually run. The point is that authoring 5 hooks plus 4 bodies plus 3 CTAs equals 12 components total, which compose into 60 hook-body-CTA combinations. + +--- + +## Variation matrix template + +A simple spreadsheet that drives the production session. + +| Concept | Hook ID | Body ID | CTA ID | Format | Variant ID | Status | +|---|---|---|---|---|---|---| +| launch2026 | hook_a | body_a | cta_a | meta-reel | v001 | drafted | +| launch2026 | hook_b | body_a | cta_a | meta-reel | v002 | drafted | +| launch2026 | hook_c | body_a | cta_a | meta-reel | v003 | drafted | +| launch2026 | hook_a | body_b | cta_a | meta-reel | v004 | drafted | +| launch2026 | hook_a | body_a | cta_b | meta-reel | v005 | drafted | +| launch2026 | hook_a | body_a | cta_a | tiktok-vertical | v006 | drafted | +| launch2026 | hook_a | body_a | cta_a | static-1x1 | v007 | drafted | + +The status column tracks the production pipeline: drafted, rendered, approved, shipped, paused, retired. + +--- + +## Naming conventions + +Every variation has a structured name so the analyst can join performance data back to creative components. + +``` +{concept}_{platform-format}_{hook}_{body}_{cta}_v{n} +``` + +Examples: + +``` +launch2026_meta-reel_hookA_bodyB_ctaC_v1 +launch2026_tiktok-vertical_hookE_bodyA_ctaA_v3 +launch2026_static-1x1_hookA_bodyA_ctaB_v2 +``` + +The analyst pulls the report, splits the names on the underscore, joins to a master variant table, and reports performance by component. "Hook E is winning across body and CTA combinations on TikTok" becomes a query, not a manual review. + +--- + +## Asset library structure + +Organize files by concept, not by date. + +``` +concepts/ + launch2026/ + hooks/ + hookA-direct-callout.txt + hookB-contrarian-claim.txt + hookC-result-led.txt + hookD-curiosity-gap.txt + hookE-personal-story.txt + bodies/ + bodyA-feature-list.txt + bodyB-customer-story.txt + bodyC-comparison.txt + bodyD-process-walkthrough.txt + ctas/ + ctaA-shop-now.txt + ctaB-start-trial.txt + ctaC-book-demo.txt + visuals/ + hero-product-shot.png + ugc-customer-1.mp4 + founder-camera.mp4 + rendered/ + meta-reel/ + tiktok-vertical/ + static-1x1/ +``` + +Date-based organization rots fast. Concept-based organization composes; the team that runs three concepts a quarter has three folders, each with a clean inventory of components. Six months in, the library is searchable. + +--- + +## Half-day production session worked example + +The goal. Produce 40 variations of one core concept in 4 hours. The team: one creative strategist, one editor, one copywriter. + +**Hour 1: matrix planning.** Strategist drafts 5 hooks, 4 bodies, 3 CTAs against the concept brief. Copywriter refines language. Output: 12 component scripts. + +**Hour 2: visual asset prep.** Editor pulls the visual library (hero product shot, two UGC videos, two founder-to-camera takes). Copywriter writes captions per platform. Output: visual atoms ready to compose. + +**Hour 3: rendering.** Editor renders the matrix using a video editor's template feature (or a tool like Pencil, Vidico Forge, or in-house automation). The hook component swaps in; the body component swaps in; the CTA component swaps in; the format renders per platform. Output: 30 rendered variations. + +**Hour 4: review and final renders.** Team reviews the 30 outputs, kills the 5 to 10 that fail the smell test, renders the final 10 that need higher-quality cuts. Output: 20 to 25 production-ready variations. + +The math. 12 component scripts plus a half day of editor time produces 20 to 25 variations. Without the matrix, the same 20 to 25 variations require 5 days of independent authoring per variation. + +--- + +## When the matrix breaks down + +Two situations where the matrix is the wrong shape. + +**Concept-driven brand work.** Awareness creative often does not decompose cleanly. The 60-second YouTube spot is one creative, not a matrix. The hook, body, and CTA are integrated into the narrative. For brand work, drop the matrix and produce one strong piece. + +**Highly format-specific creative.** A behind-the-scenes TikTok is not a hook plus body plus CTA; it is a single creator's continuous take. Forcing the matrix produces stilted ads that read as agency-produced. For format-native creative, accept that one format produces one creative; do not try to render the same content into static. + +The rule. Use the matrix for performance creative where direct response is the goal. Drop the matrix for awareness, brand, or format-native creative where the integrity of the piece matters more than ship volume. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md b/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md new file mode 100644 index 0000000..c4b52d5 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md @@ -0,0 +1,110 @@ +# Fatigue detection checklist + +Five signals that creative is fatiguing, with thresholds and a refresh decision tree. + +The principle. Creative fatigue is a real economic cost. The tired ad still spends; it just does not convert. The team that monitors fatigue catches the decay early; the team that does not discovers a 30 to 50% performance gap when they finally check. + +--- + +## The five signals + +### 1. Frequency above 4 to 5 per user per week + +**Threshold.** Above 4 per user per week for performance ads. Above 5 for awareness ads. + +**Why it matters.** The same audience sees the same creative too many times. CTR drops, irritation rises, brand association erodes. + +**Where to check.** Meta Ads Manager: frequency report at the ad-set level. Google Ads: frequency at the campaign level. TikTok: less granular, but available at the ad group level. + +**Action.** If frequency is climbing past 4, ship variants of the same concept (different copy and visuals, same hook structure). If multiple concepts are all climbing, the audience is too narrow; expand. + +### 2. CTR declining 30%+ week over week + +**Threshold.** A 30% drop week over week is the alarm. A 10 to 15% drop is normal noise; 30% is a signal. + +**Why it matters.** The audience is no longer interested in the creative. Continuing to run it spends without producing the click. + +**Where to check.** Each platform's reporting at the ad level over a 4-week window. Look at the trendline, not just the latest week. + +**Action.** Refresh the creative within 7 days. If multiple ads in the same audience are dropping simultaneously, the audience is fatigued; rotate audiences as well as creative. + +### 3. CPM increasing without audience saturation explanation + +**Threshold.** A 25%+ increase over 14 days, with audience size and competition both stable. + +**Why it matters.** The platform's algorithm is having to bid harder to deliver impressions because engagement signals are weakening. The audience is still there but the platform sees the creative as less relevant. + +**Where to check.** Each platform's CPM trend. Cross-reference with audience overlap reports and competitor activity (Meta Ads Library, SimilarWeb, etc.). + +**Action.** Refresh creative. The CPM will recover within 7 to 14 days of fresh creative landing. + +### 4. Negative comments increasing + +**Threshold.** Comments containing "spam," "stop showing me this," "annoying," or platform-specific negative reactions exceeding 1% of impressions. + +**Why it matters.** Direct user signal of irritation. The audience is mad; the brand is paying for that anger. + +**Where to check.** Meta Ads Manager: comments section per ad. TikTok: comments per ad. Less visible on LinkedIn. + +**Action.** Pull the creative within 24 hours. Negative comments compound; the audience that complains often is the audience that complains to friends. + +### 5. Hide ratio (negative feedback) increasing + +**Threshold.** Meta exposes "negative feedback rate"; trigger refresh when it exceeds 1.5% of impressions or rises 50% week over week. + +**Why it matters.** Hide is a stronger signal than scroll-past. The audience is actively rejecting the ad. Platform algorithms penalize creatives with high hide ratios by reducing reach. + +**Where to check.** Meta Ads Manager: customize columns to expose negative feedback. Other platforms: less direct equivalents (TikTok "not interested" rate is similar). + +**Action.** Pull the creative immediately. The cost is real: the platform will deliver less of all your ads to that audience as it learns to weight negative signals. + +--- + +## Refresh cadence by spend tier + +| Monthly spend | Refresh cadence | Variants per refresh | +|---|---|---| +| Under $5K | Monthly | 2 to 3 | +| $5K to $25K | Biweekly | 3 to 5 | +| $25K to $100K | Weekly | 5 to 10 | +| Above $100K | Twice weekly | 10+ | + +The economics. Producing a fresh variant costs less than running tired creative for one extra week. At $100K per month, even one day of underperformance is meaningful. Higher spend justifies higher refresh investment. + +--- + +## Refresh decision tree + +When fatigue signals trigger, three options. Pick based on the diagnosis. + +**Option 1: variant of working concept.** The hook structure is still working but the specific creative is fatigued. Ship 3 to 5 variants of the same concept (different copy, different visuals, same hook structure). + +When. CTR drop with frequency above threshold, but the concept itself was strong (top performer in the testing waterfall). + +Cost. Half-day production session if the matrix is in place. Variants ship within 48 hours. + +**Option 2: replace concept entirely.** The concept is exhausted. Ship a fresh concept (different hook structure, different angle, different value prop emphasis). + +When. Multiple variants of the same concept are dropping simultaneously, or the concept has been in market for 6 to 12 weeks at high frequency. + +Cost. Full production cycle. Variants ship within 1 to 2 weeks. + +**Option 3: full creative rotation.** Multiple concepts are tired across the account. The audience is over-saturated. + +When. CPM rising across multiple campaigns, hide ratio climbing across the account, multiple concepts dropping in parallel. + +Cost. Quarterly creative refresh. Plan ahead; do not let the rotation be reactive. + +--- + +## Common mistakes + +**Watching only CTR.** CTR is a fatigue signal but not the only one. CPM and frequency lead CTR; the team watching only CTR is reactive when leading signals would have caught it 1 to 2 weeks earlier. + +**Refreshing too late.** Once CTR has dropped 50%, the audience has already developed negative associations. The next creative inherits that fatigue context. Refresh on leading signals (CPM, frequency). + +**Refreshing without analysis.** Producing fresh creative without understanding what worked about the previous creative. The team ships variants that miss what made the original successful and reverts to baseline performance. + +**Ignoring the platform algorithm's cooldown.** A new creative variant goes through a learning phase (3 to 7 days). Performance during the learning phase is not representative; do not kill a new variant in week 1. + +**Treating all fatigue the same.** Audience fatigue is different from creative fatigue. If multiple creatives are all fatigued, the audience is the problem. Rotate audiences, not just creative. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md b/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md new file mode 100644 index 0000000..12b3bf6 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md @@ -0,0 +1,48 @@ +# Format decision matrix + +Audience-objective context to recommended format. Read top to bottom; pick the row that matches your situation. + +--- + +## The matrix + +| Context | Primary format | Secondary format | Reasoning and what to avoid | +|---|---|---|---| +| B2C direct response, fast-scroll platforms (Meta, TikTok) | Vertical video 9:16, 15s | Static image (retargeting) | Native to the feed, scroll-stop in 1s. Avoid horizontal video; it gets letterboxed and ignored. | +| B2B SaaS demo or feature explainer | Carousel | Vertical video with captions | Carousel lets users self-pace; B2B audiences are in research mode. Avoid horizontal video for B2B feed placements. | +| DTC visual product | UGC-style vertical video | In-feed product carousel | UGC retains organic feel and beats studio production for direct response. Avoid heavily produced product shots; reads as "ad" and gets skipped. | +| Trust-led offer (financial, healthcare) | Static with social proof + carousel | UGC video with named customers | Trust requires repeat exposure to credible signals. Avoid moving cuts and music; reads as a pitch. | +| Founder-led B2B SaaS | Founder-to-camera video, 15 to 30s | Static quote card | First-person specificity is high-trust. Avoid voiceover with stock footage; reads as agency-produced. | +| Education-led content marketing | Long-form video (60s to 3m) | Carousel | Long-form rewards educational content. Use for awareness or top-funnel; not direct response. | +| App install | Vertical video with screen recording | Static screenshot grid | Screen recording shows the product in 5 seconds, faster than narration. Avoid feature lists; show the product. | +| Local services | Static image + lead form | UGC-style customer quote | Lead capture is the goal; minimize friction. Avoid long video; the audience is conversion-ready. | +| Enterprise B2B (>$50K ACV) | LinkedIn Sponsored Content with carousel or static | Long-form video for awareness | Professional tone, slower pacing. Avoid TikTok-style fast cuts; reads as off-platform. | +| Retargeting (warm audience) | Static image with offer | Short carousel with social proof | Audience already knows the brand; lead with the offer or social proof, not the brand intro. Avoid full hooks; the audience does not need them. | +| Black Friday or peak moment | Static with discount + countdown | Vertical video with offer + urgency | Speed matters in peak; the audience is decision-ready. Avoid long-form storytelling. | +| Pre-launch awareness | Long-form vertical video, 30 to 60s | Carousel for waitlist | The audience is curious, not converting. Reward attention with substance. Avoid short performance hooks; they undersell. | + +--- + +## Decision rules + +Three rules apply across the matrix. + +**Match the platform's native style.** A 1:1 video on TikTok performs worse than the same video as 9:16 vertical. A horizontal video on LinkedIn performs better than the same vertical, because LinkedIn audiences watch on desktop more than TikTok audiences do. Rules differ; produce per platform. + +**Match the audience's consumption mode.** Scroll mode (TikTok, Reels) needs hook in 1 second. Research mode (LinkedIn, B2B blogs) tolerates longer pacing. Decision mode (retargeting, peak moments) wants the offer up front and skips the hook. + +**Match the offer's complexity to the format's information density.** Simple offers (a discount, a free trial) work in static. Complex offers (a multi-feature product, a service with a process) need carousel or video. Forcing a complex offer into static fails because the audience cannot understand what is being offered in 1 second. + +--- + +## Common mistakes + +**One format across all platforms.** A 16:9 video produced for YouTube does not work on TikTok or Reels. The team that ships one format and adapts crops produces underperforming creative on every platform except the one the format was designed for. + +**Format chosen by what is easy to produce.** Static is fastest to make; teams default to it even when video would convert 3x better. The cost of one good vertical video is recouped in one strong campaign; the production overhead is real but worth it for high-spend campaigns. + +**Format chosen without testing.** Most teams pick a format and stick with it. The matrix gives a starting point; the testing waterfall (see `testing-cadence-playbook.md`) gives the real answer for the specific brand and audience. + +**Carousel without progression.** A carousel is a multi-card story. Each card should advance the narrative or value prop. Six cards of the same image with different text waste the format. + +**Vertical video without captions.** Most users watch sound-off. A vertical video without captions communicates only its visual; the value prop disappears. Captions are not optional on Meta and TikTok. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md b/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md new file mode 100644 index 0000000..cf7d559 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md @@ -0,0 +1,157 @@ +# Hook pattern library + +Twelve hook patterns that work consistently in performance creative. For each: what makes it work, when it fits, the anti-pattern, and one or two worked examples. + +A hook is the first 1 to 3 seconds of an ad. If the hook fails, the rest of the creative does not get watched. The hook carries 60% of the performance weight; the body and CTA carry 40%. Spend the creative effort accordingly. + +--- + +## 1. Problem-agitate-solve + +**What makes it work.** Names the audience's pain in their own language, then makes the consequence vivid, then offers the way out. The structure mirrors how the audience already thinks. + +**When it fits.** When the audience recognizes the pain and feels it as a real cost. Less effective when the pain is abstract. + +**Anti-pattern.** Skipping the agitate step. The audience hears the problem named and shrugs because the consequence is not vivid. + +**Example.** "Spending 4 hours a week on status updates? That is 200 hours a year. (Pause.) StatusBot writes them for you in 5 minutes." + +--- + +## 2. Direct callout to audience + +**What makes it work.** Triggers self-identification in the first second. The viewer thinks "that is me" and watches. + +**When it fits.** When the audience is narrow, self-aware, and proud of the identity. Founders, doctors, parents, runners, B2B SaaS PMs. + +**Anti-pattern.** Calling out an audience that is too broad. "If you are a person on the internet..." triggers nothing. + +**Example.** "If you are a B2B founder running paid ads with no in-house marketer, this is for you." + +--- + +## 3. Contrarian claim + +**What makes it work.** Violates expectation. The viewer's brain pauses on the contradiction. + +**When it fits.** When the audience has heard the conventional wisdom too many times and is exhausted by it. + +**Anti-pattern.** Contrarian for its own sake. The claim has to be defensible by the body of the ad; otherwise the audience disengages by second 5. + +**Example.** "Stop using lookalike audiences. Here is the audience strategy that actually scales." + +--- + +## 4. Result-led + +**What makes it work.** Specific number plus specific timeframe. The brain treats specificity as a credibility signal. + +**When it fits.** When the result is real and documented. Faked numbers train the audience to scroll past the entire account. + +**Anti-pattern.** Vague results. "We helped a client grow" produces no curiosity; "we cut their CAC 40% in 30 days" does. + +**Example.** "How we cut CAC 40% in 30 days for a Series B SaaS with no creative budget." + +--- + +## 5. Curiosity gap + +**What makes it work.** Promises a payoff after the gap. The viewer stays to find out. + +**When it fits.** When the gap is real and the payoff is on-topic. Clickbait without payoff trains the audience to scroll past. + +**Anti-pattern.** Gap without payoff. "The mistake 80% of marketers make..." with no actual mistake named in the body of the ad. Audience feels deceived. + +**Example.** "The mistake 80% of marketers make on Meta Ads is the one that costs them 30% of their budget every month." + +--- + +## 6. Social proof at top + +**What makes it work.** Validation before pitch. The audience trusts the offer because someone they trust trusts it. + +**When it fits.** When the proof is impressive enough to do the heavy lifting. Specific names beat generic numbers when the audience knows the names. + +**Anti-pattern.** Generic proof. "Trusted by thousands" is filler. "Used by Notion, Brex, and Figma" is signal. + +**Example.** "Used by 10,000+ teams including Notion, Brex, and Whatnot. Now available for solo founders too." + +--- + +## 7. Visual pattern interrupt + +**What makes it work.** A surprising visual that does not match the platform's usual feed flow. The eye snaps to it. + +**When it fits.** TikTok, Reels, Stories. Platforms with fast scroll and high pattern density. Less effective on slower platforms (LinkedIn). + +**Anti-pattern.** Overproduced visual interrupt that reads as ad. The interrupt has to feel native to the platform; a Hollywood-style pattern interrupt on TikTok reads as "ad" and gets skipped. + +**Example.** A creator-style cold open: a person on screen, looking confused at their phone, then turning the camera around to show the screen. Two-second hook before the first word. + +--- + +## 8. Question that hits intent + +**What makes it work.** The question pre-qualifies the audience. The audience that does not match disengages immediately, which is fine. + +**When it fits.** When the question matches a real search query the audience has typed. "Tired of paying $400 for project management software" works because that is what the audience googles. + +**Anti-pattern.** Generic questions. "Want to grow your business?" filters nothing. + +**Example.** "Tired of paying $400 a month for project management software you barely use?" + +--- + +## 9. Number-led + +**What makes it work.** Lists trigger the brain's pattern-completion instinct. The viewer wants to know all three (or five, or seven) reasons. + +**When it fits.** Educational content, list-style ads. Less effective for product ads where the offer should be specific. + +**Anti-pattern.** Too many items. "10 reasons" is too many for a 15-second ad; 3 to 5 is the sweet spot. + +**Example.** "3 changes that doubled our ROAS in Q4. Number 2 surprised our agency." + +--- + +## 10. Personal story open + +**What makes it work.** First-person specificity. The brain treats personal stories as data, not pitch. + +**When it fits.** When the story is real and the conclusion is action-relevant. Founder-led ads especially. + +**Anti-pattern.** Manufactured stories that read as fictional. The audience can usually tell. + +**Example.** "Last year I was burning $50K a month on Meta ads with no return. Here is what I changed in 30 days." + +--- + +## 11. Comparison + +**What makes it work.** Pits two options against each other. The audience in evaluation mode wants the comparison. + +**When it fits.** When the audience is actively comparing. "X vs Y" search queries are the tell. + +**Anti-pattern.** Unfair comparisons. The audience smells the spin and discounts the brand. + +**Example.** "Notion vs Linear: which actually works for engineering teams under 50." + +--- + +## 12. Behind-the-scenes / process + +**What makes it work.** Demystifies the work. The audience that wonders how something is done watches to find out. + +**When it fits.** When the process is the differentiator. Agencies, services businesses, niche craft. + +**Anti-pattern.** Process content that is actually a sales pitch in disguise. Audience disengages. + +**Example.** "How we onboard a new client in 7 days, end to end, with one PM and no kickoff meeting." + +--- + +## The pattern across all twelve + +Every working hook does the same thing: it makes the next second non-optional. The viewer cannot skip without losing something. Specificity, surprise, identification, curiosity, proof. Different mechanisms; same effect. + +The non-working hooks all do the same thing too: they let the viewer skip with no cost. Generic openings. Brand logo cards. Slow zooms over title text. "In today's world..." The first second is for the hook. The brand can wait. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md b/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md new file mode 100644 index 0000000..cfa0389 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md @@ -0,0 +1,111 @@ +# Platform creative norms + +Per-platform creative requirements and unwritten conventions. Each platform has native norms; violating them tanks performance. + +--- + +## Meta (Facebook plus Instagram) + +**Aspect ratios.** 9:16 for Reels and Stories. 4:5 for in-feed (preferred over 1:1; uses more vertical real estate). 1:1 acceptable. Avoid 16:9 horizontal in feed. + +**Length.** 15 seconds is the sweet spot for performance. 6-second bumpers work for awareness. Long-form (60s+) only for storytelling formats; performance ads should resolve by 15s. + +**Audio.** Sound-off is the default. Captions are mandatory. Music is helpful when matched to the platform's audio context (low-fi background, not stock library bombast). + +**Captions.** On-screen captions for spoken audio. Bold, high-contrast, animated to track delivery. Avoid tiny captions; they are unreadable at scroll speed. + +**Native aesthetic.** Phone-shot or polished both work. UGC-style outperforms studio for direct response; studio outperforms for awareness. The brand voice and the offer drive which fits. + +**Anti-patterns.** Horizontal video in feed (gets letterboxed). No captions on spoken audio. Brand logo at second 0 (kills the hook). Slow zoom over title cards. Stock music bombast. Overproduced agency-style cuts that signal "ad" before the value lands. + +**What feels native.** Real people on camera. Direct address. Specific value props. Social proof named with brand names. Pacing that respects the user's scroll velocity (cuts every 1 to 2 seconds in the first 5 seconds). + +--- + +## TikTok + +**Aspect ratios.** 9:16 vertical only. Anything else is rejected by the algorithm. + +**Length.** 15 to 30 seconds for performance. The platform tolerates and rewards longer dwell than Meta. + +**Audio.** Sound-on is default. Trending sounds compound reach but expire fast. Original audio works. Captions for accessibility, not just for sound-off viewers. + +**Native aesthetic.** Phone-shot, creator-style. Studio production reads as "ad" and gets skipped. Pencil-and-paper aesthetic, jump cuts, unfiltered backgrounds, daylight. + +**Spark Ads.** Boost an existing organic post. Retains organic engagement signal. Outperforms pure paid creative; if the brand has organic content performing, this is the format. The Pipeboard and Synter MCPs cover Spark Ad creation; the integrations microsite covers the tactical setup. + +**Anti-patterns.** Polished agency video. Brand logo at second 0. Voiceover with stock footage. Slow-paced narrative. Music that signals "ad" (cinematic stock library). Anything that does not look like a creator filmed it. + +**What feels native.** Direct-to-camera creator. Fast cuts (1 to 2 seconds). On-screen captions following the speaker. Trending sounds when they fit. Backgrounds that look like a kitchen or bedroom, not a studio. + +--- + +## LinkedIn + +**Aspect ratios.** 1:1 or 16:9 for feed. 9:16 vertical works for Stories but Stories has limited reach on LinkedIn relative to other platforms. + +**Length.** 15 to 60 seconds. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. 30 seconds is a strong default. + +**Audio.** Sound-off default but sound-on more common than Meta. Captions still recommended. Music optional; many high-performing LinkedIn ads use no music. + +**Voice.** Professional. B2B vocabulary fine; consumer-style copy reads as off-platform. Thought leadership framing works; product pitches feel salesy. + +**Native aesthetic.** Founder-to-camera, expert-to-camera, slide-deck style, screen-recording demos. Studio production fine for LinkedIn; the audience is more tolerant of polished production than TikTok. + +**Anti-patterns.** TikTok-style fast cuts. Bombastic music. Casual or irreverent tone for serious B2B categories. UGC-style production for high-trust offers (financial services, healthcare). Generic "let us help your business grow" copy. + +**What feels native.** Specific industry vocabulary. Named customers and case studies. Slower pacing. Captions over slides. Founder-led specificity beats agency-style polish. + +--- + +## Google Search + +**Format.** Text-only headlines plus descriptions plus extensions. + +**Character limits.** Headlines 30 characters; 15 headline variants for RSA. Descriptions 90 characters; 4 description variants. Path 1 and Path 2 in the display URL: 15 characters each. + +**RSA optimization.** Provide 15+ headline variants and 4 description variants. The platform mixes them. More variants give the platform more material to optimize against. + +**Voice.** Direct. Specific. Action-led. The search query is high-intent; the ad's job is to confirm the user is in the right place. + +**Anti-patterns.** Keyword stuffing in headlines. Generic "we do X" headlines. Same value prop in every headline (the platform cannot test variation). Caps lock entire headlines (rejected). Unsubstantiated superlatives. + +**What works.** Specific value props per headline ("Free 14-day trial", "Used by 10,000+ teams", "Deploy in 5 minutes"). Question headlines that match search intent. Geographic specificity for local. Price points where they are the differentiator. + +--- + +## Google Display and YouTube + +### Display + +**Format.** Static or short animated banners across the Google Display Network. + +**Anti-patterns.** Unhelpful targeting (broad display drives garbage clicks). Vague creative (the audience is not in search mode; they need the value prop fast). + +**What works.** Retargeting with specific offers. Contextual placements (publisher list filtering). Cart-abandonment creative. + +### YouTube + +**Format.** Skippable video ads (TrueView), non-skippable, bumper (6s), in-feed video. + +**Length.** Skippable: 15s to 6m. Non-skippable: 15s. Bumper: 6s. + +**Audio.** Sound-on default. Captions still recommended for accessibility. + +**Native aesthetic.** YouTube allows longer narrative; the audience is in dwell mode. Both phone-shot and studio production work depending on context. + +**Anti-patterns.** Saving the value prop for the unskippable end. Skippable ads need to earn the next second; the value prop has to land in 5 seconds even on skippable. + +**What works.** First 5 seconds earn the rest. Specific value props. Demonstrations. Skippable with strong hooks routinely outperform non-skippable because the audience self-selects into watching. + +--- + +## Cross-platform principles + +Three rules apply across the matrix. + +**Native production beats repurposing.** A 16:9 video produced for one platform and cropped for others performs worse than three platform-native pieces. Produce per platform; do not adapt. + +**Pacing matches the platform's scroll velocity.** TikTok scroll is fast; cuts every 1 to 2 seconds. LinkedIn scroll is slow; longer takes work. Meta is in between. + +**Captions everywhere.** Sound-off is the default on most platforms most of the time. Spoken audio without captions is wasted audio. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md b/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md new file mode 100644 index 0000000..664b7ac --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md @@ -0,0 +1,121 @@ +# Testing cadence playbook + +The sequential testing waterfall. How to find the winning creative without testing 50 things at once. + +The principle. Variance compounds. Testing all variables at once means you cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential testing isolates the variable that matters at each step. + +--- + +## The waterfall + +Five stages. Each stage isolates one variable and advances the winners. + +### Stage 1: Hook test + +**Goal.** Find which hooks stop the scroll. + +**Setup.** 5 to 10 hook variants, same body, same CTA, same format. Each variant gets equal budget initially. + +**Duration.** 7 to 14 days, or until each variant has 50+ conversions or 1M+ impressions, whichever comes first. + +**Winner criteria.** Top 2 to 3 hooks by CTR (the metric that isolates hook performance) plus conversion rate above the floor. Eliminate hooks with high CTR but low conversion (the click is generated by the hook but the ad does not deliver). + +**Output.** 2 to 3 winning hooks advance to Stage 2. + +### Stage 2: Body test + +**Goal.** Find which body copy or middle-section visuals convert best given the winning hooks. + +**Setup.** Winning hooks times 5 to 10 body variants. Same CTA, same format. If two hooks advanced, that is 2 hooks times 5 bodies equals 10 ad sets. + +**Duration.** 7 to 14 days, or until each combination has 50+ conversions. + +**Winner criteria.** Top 2 to 3 hook plus body combinations by conversion rate. CTR is no longer the primary metric; the body is what holds attention after the hook. + +**Output.** 2 to 3 hook plus body combinations advance to Stage 3. + +### Stage 3: CTA test + +**Goal.** Find which CTA produces the strongest action given the winning hook plus body. + +**Setup.** Winning hook plus body combinations times 3 to 5 CTAs. Same format. Differences at this stage are usually marginal; do not over-engineer. + +**Duration.** 5 to 10 days, or until each combination has 30+ conversions. + +**Winner criteria.** Top hook plus body plus CTA combinations by conversion rate plus AOV (if value matters). + +**Output.** 2 to 4 winning combinations advance to Stage 4. + +### Stage 4: Format test + +**Goal.** Find which format works best for the winning combinations. + +**Setup.** Winning combinations rendered in 2 to 3 formats (vertical video, carousel, static). + +**Duration.** 7 to 14 days. + +**Winner criteria.** Top combinations by conversion rate within each format. Different formats may have different winners; that is fine. Run the winning format per surface. + +**Output.** 2 to 4 production-ready creatives ready for evergreen rotation. + +### Stage 5: Evergreen rotation + +**Goal.** Run winners at scale; refresh on cadence. + +**Setup.** 2 to 4 winners running in rotation. Frequency capping per audience. + +**Duration.** Ongoing. Refresh creative on the cadence in `fatigue-detection-checklist.md`. + +--- + +## Statistical thresholds + +Two ways to call winners. Pick one and standardize across the team. + +**Statistical significance.** Run until the winner has 95% confidence (or whatever threshold the team agrees on). Some platforms expose a "significance" indicator; others do not. + +**Pre-commit duration plus minimum volume.** Decide before launching: "we will run for 14 days, each variant gets at least 50 conversions, top performer wins." This is the simpler, more honest approach for most performance work. The platform's algorithm will not run a clean test under your nose anyway, so trying for high-confidence statistical significance is often overkill. + +The trap. Calling winners on small samples. A variant with 5 conversions and 10% lift over the other looks impressive but is within margin of platform noise. Wait for volume before declaring. + +--- + +## Common mistakes + +**Testing too many variables at once.** The most common mistake. Six hooks times five bodies times three CTAs times two formats equals 180 ad sets. The platform cannot optimize against that many variants; the team cannot interpret the results. Sequential is slower but produces real learnings. + +**Killing variants too early.** A variant in the learning phase has not yet converged. The platform's first 3 days of delivery are not representative. Wait at least 7 days before killing. + +**Calling winners on CTR alone.** A hook can drive high CTR with no conversion follow-through. The hook is doing its job (stopping the scroll) but the body is failing. Use conversion rate as the primary winner criterion; CTR is a hook-quality signal, not a creative-quality signal. + +**No exclusion of recent converters from the test audience.** Recent converters click ads at higher rates because they are warm; mixing them into the test audience produces false-positive results. Exclude. + +**Ignoring fatigue during the test.** A variant that wins the test in week 1 because it is new can underperform in week 4 once frequency builds. Test results are read against frequency; high-frequency winners are unreliable. + +--- + +## Per-stage budget guidance + +Rough percentages for the testing budget within a campaign's total spend. + +| Stage | Share of testing budget | +|---|---| +| Hook test | 40% | +| Body test | 25% | +| CTA test | 10% | +| Format test | 15% | +| Buffer (re-tests, lift checks) | 10% | + +The hook test gets the biggest share because it filters the most variants. CTA and format tests are smaller because the differences are usually marginal. + +--- + +## When to break the waterfall + +Two situations. + +**Time pressure.** A peak moment (Black Friday, product launch) does not allow 6 weeks of sequential testing. Compress: run a hook test concurrently with format test using your best-guess body and CTA. Accept lower confidence in exchange for speed. + +**Discovery of an outlier.** A hook variant that is winning by 5x at the end of week 1 should not wait for the full 14-day stage. Promote early, but track the long-tail performance to confirm. + +The default is the waterfall. The exceptions are real but rare; do not let "we are on a tight timeline" become the default reason to skip the discipline. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md b/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md new file mode 100644 index 0000000..2bcadc2 --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md @@ -0,0 +1,275 @@ +--- +name: ads-performance-analytics +description: "How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue." +category: marketing +catalog_summary: "Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget" +display_order: 3 +--- + +# Ads Performance Analytics + +A data-team-mentor's playbook for interpreting paid media dashboards without fooling yourself. + +The dashboard is the moment of truth for paid media decisions. The numbers on it determine whether you scale, hold, or kill. They also expose every platform's self-attribution bias, every modeled-conversion shortcut, every cross-platform double-count. Most "scale this campaign" decisions trace back to misreading the dashboard. + +This skill is the discipline that prevents misreading. It assumes the campaign was strategically sound (see `paid-media-strategy`). It assumes the creative was tested properly (see `ads-creative-development`). The hard part is knowing what each number actually means, what it does not, and how to reconcile platform-reported metrics with the truth in your warehouse. + +When to use this skill: any time you are about to scale, kill, or rebudget a campaign based on platform metrics; reconciling platform reports with revenue data; evaluating an agency's reporting; or building a paid media dashboard that will not lie to you. + +--- + +## What this skill is for + +This skill spans paid media result interpretation. It does not cover paid media strategy (use `paid-media-strategy`), creative production (use `ads-creative-development`), or platform-specific tooling (covered in the integrations microsites). Pair this skill with the relevant integrations microsite for platform-specific MCP commands and example prompts. + +The audience is a marketer, growth analyst, agency analyst, or founder evaluating paid media reports. The voice is patient and clinical. There is no "trust the platform's number" or "ignore the platform entirely." Both are wrong. The discipline is knowing which numbers from which platform mean what, and what to reconcile against to make the actual decision. + +--- + +## The result panel: what every paid media platform should expose + +A trustworthy result panel exposes nine things. Anything missing is a signal to treat reported numbers with extra skepticism. + +1. **Spend, impressions, clicks.** Table-stakes metrics. Should match across platforms within rounding. +2. **Conversions with definition and window visible.** Not just a count; the definition of what counts as a conversion and the attribution window applied. Without this, the count is unreadable. +3. **Attribution breakdown.** Last-click vs view-through vs modeled. The mix of how the conversions were credited. +4. **Frequency.** Impressions per unique user. The fatigue early-warning system. +5. **Audience saturation.** Where the platform exposes it. A flat audience-saturation curve means there is room to scale; a steep curve means efficiency is dropping. +6. **Time series.** Daily breakdown to spot novelty effects, fatigue, day-of-week patterns, and exogenous variance. +7. **Cost metrics in clear currency.** CPC, CPM, CPA, ROAS with the math defined and the currency labeled. Do not assume USD. +8. **Conversion path data.** Touchpoints before conversion, where available. Tells you whether a campaign is a closer or an opener. +9. **Filters, segments, and exports.** Without these, the panel is a brochure, not a tool. + +Platforms hide what makes their reporting look weakest. Google PMax hides keyword-level and placement-level data. Meta hides the modeled-conversion share. LinkedIn hides cross-device click paths. Treat hidden metrics as the place to dig. + +--- + +## Platform-reported vs reality + +Every platform's dashboard is optimized to make the platform look effective. This is not a moral failing; it is a structural incentive. Platforms with rosier reporting attract more spend. + +**Conversion windows.** Meta defaults to 7-day click plus 1-day view. Google defaults to 30-day click plus 1-day view. Different windows, same activity, different reported numbers. If you compare Google's 30-day-click count against Meta's 7-day-click count, you are comparing different definitions and pretending they are the same. + +**View-through attribution.** Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Treat view-through as a signal of awareness contribution, not as a direct response measurement. The user might have converted from organic search anyway. + +**Modeled conversions.** When iOS users opt out of tracking, Meta and others statistically model what the conversion would have been. Modeled numbers are educated guesses, not measurements. They are useful for direction; they are not reliable for precision. + +**Self-attribution bias.** Every platform's pixel fires on conversion and the platform claims credit. If you ran Meta, Google, and TikTok in the same week, all three platforms report your conversions as theirs. Sum-of-platforms is always greater than 100% of actual conversions. + +The discipline. Never report platform-reported numbers as fact in board decks. Always reconcile against the single source of truth (warehouse, GA4, or unified analytics platform). Detail in [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md). + +--- + +## Attribution models in practice + +Six models and one anti-model. None is right. They are all approximations. The discipline is picking one, committing, and reading the others as sanity checks. + +**Last-click.** Simple, reproducible, undercredits awareness. The conversion is fully credited to the last click before the conversion event. Easy to compute; easy to compare across channels; bad for understanding upper-funnel contribution. + +**First-click.** Opposite bias. Fully credits the first touchpoint, undercredits closing channels. Useful as a sanity check against last-click; rarely the right primary view. + +**Linear.** Equal credit across all touchpoints. Gives every channel something. Defensible; not informative. Most useful for board reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. + +**Time-decay.** More credit to recent touchpoints. Reflects the intuition that recent ads are more influential. Hard to argue against; hard to verify. + +**U-shaped (position-based).** Heavy on first and last (40% each), light on middle (20% distributed). Honors both opener and closer roles. The default in many MTA tools. + +**Data-driven attribution (DDA, Google).** Machine-learning model that distributes credit based on observed conversion paths. Opaque; hard to audit. The closest to "right" for digital channels but a black box. + +**Marketing mix modeling (MMM).** Regression-based, top-down. Uses spend and revenue time series across channels to estimate channel contributions. Requires 2+ years of data. The strongest defense against platform self-attribution because it does not rely on platform-reported conversions at all. + +**The anti-model: trusting platform-reported attribution.** Each platform's "DDA" or "attributed conversions" is the platform's self-attribution. Sum across platforms exceeds reality. Use platform attribution for in-flight optimization within the platform; use a unified attribution model for cross-channel decisions. + +Practical guidance. + +- Early-stage. Use last-click plus a single guardrail metric (warehouse-attributed CAC). Sophisticated attribution requires data volume you do not have. +- Mid-stage. Data-driven attribution from Google plus GA4, with explicit awareness vs closing channel labeling. +- Mature. MMM as the canonical incremental reference. MTA for in-flight optimization. Last-click for channel-level decisions where ambiguity is acceptable. + +Detail and a decision matrix in [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md). + +--- + +## Multi-platform reconciliation + +The trap. Google says you spent $50K with 800 conversions. Meta says $30K with 600. LinkedIn says $20K with 200. Total reported equals 1,600 conversions. Your warehouse says 950. Where did 650 go? + +The answer. Nowhere. They never existed. Each platform claimed conversions other platforms also claimed. + +The reconciliation pattern. + +- Trust the warehouse for total conversions and total revenue. +- Trust platforms for relative ranking within platform (which campaign won, which audience won). +- Never trust platform sums. +- Compute blended CAC as (total ad spend across platforms) divided by (total new customers from warehouse). Not from platform reports. + +The board-deck pattern. Report warehouse-attributed conversion counts, never platform-summed. Report blended CAC, not channel-by-channel CAC unless explicitly noted as platform-self-attributed. Detail and templates in [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md). + +--- + +## ROAS vs LTV: the time horizon trap + +ROAS is short-term. Revenue from purchases attributed to a campaign in a fixed window, often 7 to 30 days. LTV is long-term. Total customer lifetime revenue. + +Decisions made on ROAS can be wrong if LTV varies by channel. A worked example. + +Meta drives 2.5x ROAS at $40 CAC with $80 LTV. The 7-day-click revenue covers 1.5x payback over the customer lifetime. + +Google drives 1.8x ROAS at $60 CAC with $200 LTV. The 7-day-click revenue covers 3.3x payback over the customer lifetime. + +Google looks worse on ROAS, better on LTV-adjusted return. Allocating budget to Meta because the ROAS is higher is the wrong move. + +The fix. Cohort-based LTV by acquisition channel, updated quarterly. Compare channels on payback period or LTV-CAC ratio, not raw ROAS. The 2x ROAS heuristic is a dangerous shortcut. Same ROAS at different LTVs equals different actual returns. + +The trap that compounds. Performance teams optimize for short-term ROAS because the metric refreshes weekly. Brand and high-LTV channels get cut because their short-term ROAS is lower. Six months later, the brand pipeline has eroded and short-term ROAS itself drops because the cheap channels are saturated. The metric that drove the decision was the wrong horizon. + +--- + +## Cohort analysis vs daily metrics + +Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. + +Three cohort cuts that matter for paid media. + +**By acquisition month.** Are users acquired in March retaining better than users acquired in January? A declining LTV over rolling acquisition cohorts means recent acquisition is lower quality; the daily metrics will show this two to three months later when the retention starts hurting. + +**By acquisition channel.** Are users from Meta retaining better than users from Google? Channel-level cohort divergence is the data behind the LTV-vs-ROAS argument. Meta might drive volume at lower LTV; Google might drive lower volume at higher LTV. The cohort tells the story the daily ROAS hides. + +**By acquisition campaign.** Campaign-level cohort signals. Useful for diagnosing why a campaign that "works" in week 1 produces no recurring revenue. + +The signal to act on. Declining cohort LTV over two consecutive months is the alarm. Pause the channel or campaign before the daily metrics force you to. Detail in [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md). + +--- + +## Statistical noise in performance metrics + +Most "the campaign improved 15% week over week" stories are noise. Real performance changes are 30% or more in metrics that vary 10 to 20% naturally. Below that threshold, you are looking at variance and calling it signal. + +Sources of noise in paid media metrics. + +- **Day-of-week effects.** B2C tends to weekend dips. B2B tends to weekend gains. A "Monday morning is better" hypothesis often dissolves when day-of-week is normalized. +- **Holiday and seasonal effects.** Q4 dwarfs most "optimization" effects. A campaign launched in Q4 looks great because of seasonality, not strategy. +- **Weather, news, competitor activity.** Real exogenous variance. Last week's news cycle can shift CPMs across an entire vertical. +- **Pixel fire and reporting delay.** Conversions reported on a 7-day click window arrive incrementally. Reading the panel on Monday for last week's performance undercounts. + +The fix. Pre-commit to test duration before drawing conclusions. Use the experimentation discipline from `experimentation-analytics` for any directional change you want to claim is real. The signal-to-noise problem in paid media metrics is the same as the signal-to-noise problem in product experiments; the framework transfers. + +This is where `experimentation-analytics` bridges in. The statistical patterns are the same; the application is different. Read both for the full picture. + +--- + +## Incrementality testing + +The honest test. If we had not run this ad, would we still have gotten the conversion? The number above zero is the incremental contribution. + +Most paid media is 30 to 70% incremental, not 100%. Some is zero. Branded search bidding is often 5 to 20% incremental (most converters would have found you organically). Retargeting is often 20 to 40% incremental (many of those users were going to convert anyway). Prospecting is often 50 to 90% incremental. + +Four methods. + +**Geo holdout.** Hold one region out from the campaign. Measure the difference in conversions between the holdout region and the matched test region. The cleanest causal test for paid media at scale. + +**Ghost bidding (Google).** Google's own incrementality tool. Bids on a holdout share of impressions but does not actually serve the ad. Reports incremental conversions. Honest signal; some teams find the math opaque. + +**Conversion lift studies (Meta).** Splits audiences into test and control. Test sees the ad; control does not. Reports incremental lift. The cleanest within-Meta test. + +**PSA tests.** Serve some users a public service announcement instead of your ad. Compare conversion rates. Useful for legacy brands with deep budget. + +Incremental rate ranges by channel type are in [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md). The discipline is to run incrementality tests at least quarterly on the highest-spend channels. Without them, you are optimizing against platform-reported attribution that systematically overcounts. + +--- + +## Geo experiments and holdouts + +For paid media specifically, geo-based testing is the most reliable causal method. + +**Geo holdout.** Turn off paid media in one region. Measure baseline organic conversions. The difference between expected and actual conversions in the holdout region is the incremental paid contribution. + +**Geo lift.** Scale spend in one region by 2x. See if conversions scale linearly. A linear scale means the channel has headroom. A sublinear scale means saturation; further spend is diminishing returns. + +**Switchback.** Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. Useful when geo splitting is not feasible. + +**Pre-and-post analysis.** Launch in a region; measure 30 days before vs 30 days after. Weak design because external factors confound the comparison. Use only when no other test is available. + +The right setup. Matched markets (similar demographics, similar baseline conversion rates). Statistical power calculation upfront (how big a difference can the test actually detect). Pre-committed analysis window (so you do not stop early when the data looks good or wait too long when it looks bad). + +The trap. Calling a geo test successful because of timing-correlated revenue lift. A campaign launched in October will see "lift" because Q4 is starting; without a control region, the lift is not attributable to the campaign. + +--- + +## Platform self-attribution bias + +A specific failure mode worth its own section. + +The mechanism. Platform's pixel fires on conversion. Platform claims credit. The user might have converted from any channel; the platform that loaded the pixel last gets the credit on the platform's own dashboard. + +Why platforms reward this design. More credit on the platform dashboard equals better-looking ROAS equals more advertiser spend. Platforms have no incentive to underreport their own contribution. + +Detection patterns. When platform-reported conversions exceed warehouse-attributed conversions for the same channel by more than 30%, you have heavy double-counting. When sum-of-platform-reports exceeds total conversions in the warehouse, you have cross-platform double-counting. + +The fix. Warehouse as canonical for board reporting. Platform reporting as in-flight signal only. Incrementality tests at least quarterly to keep the channel-attribution honest. + +A worked example. A retargeting campaign in Meta showed 3.5x ROAS for six months. The team scaled spend from $20K to $80K per month. A geo holdout test revealed that 65% of the "conversions" would have happened anyway from organic. Real ROAS adjusted for incrementality was 1.2x, not 3.5x. The campaign got cut and warehouse-attributed CAC dropped 18% in the next quarter. + +--- + +## Common interpretation failures + +Twelve patterns recur in paid media reporting work. Detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "ROAS dropped 20% week over week, kill the campaign." Could be noise. Pre-commit a test window before acting on weekly variance. +- "Meta says 500 conversions, my warehouse says 200, who is right?" Both are wrong; warehouse is closer to truth, Meta self-attributes. Reconcile, do not pick a winner. +- "We turned off Google PMax and conversions did not drop." PMax was harvesting branded search you would have gotten free. Audit branded queries inside PMax. +- "The new campaign hit 5x ROAS in week 1." Likely retargeting hot leads. Check the audience composition before declaring victory. +- "We A/B tested and one creative wins by 12%." Within margin of platform noise. Not significant. +- "Our LTV calculation says this channel is profitable." Check cohort age. Recent cohorts may not have hit LTV yet; the calculation is a projection, not a measurement. +- "The platform says high frequency is fine because conversions are still happening." Fatigue masked by free organic conversions. The campaign is taking credit for conversions that would have happened anyway. +- "Last-click attribution shows Meta at 60% credit." Last-click bias. First-click view of the same data shows different. Pick a model and stick. +- "We scaled spend 5x and conversions only doubled." Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher. +- "Brand campaigns underperform on direct ROAS." They do not have to. Brand impact shows up in other channels' efficiency. Measure brand against brand-search lift, not direct ROAS. +- "ROAS held steady but profit dropped." The mix shifted toward lower-margin products. Channel-level ROAS hides product-mix effects. +- "Agency reported a 4x ROAS month." Whose number? Platform-reported, warehouse-attributed, or model-adjusted? The unit of measurement matters more than the magnitude. + +--- + +## The framework: 12 considerations for trustworthy paid media interpretation + +When reading a paid media dashboard about to inform a decision, walk these 12 considerations. Skipping any of them is how teams ship the wrong call. + +1. **Result panel completeness.** What is the platform showing vs hiding. +2. **Platform-reported vs reality.** View-through, modeled conversions, conversion windows. +3. **Attribution model.** Pick one and read the others as sanity checks. +4. **Multi-platform reconciliation.** Sum-of-platforms is always inflated. +5. **ROAS vs LTV horizon.** Short-term metric, long-term impact. +6. **Cohort vs daily.** Cohort tells the quality story; daily tells the volume story. +7. **Statistical noise.** Weekly variance, day-of-week, seasonal, exogenous. +8. **Incrementality.** What would have happened without the spend. +9. **Geo and holdout testing.** The honest causal test. +10. **Self-attribution bias.** Platforms claim credit they do not deserve. +11. **Decision rule.** Pre-committed scale up, hold, or pull back. +12. **Single source of truth.** Warehouse over platform reporting for board metrics. + +The output of the framework is one of three answers. Scale (the campaign is incremental and unit economics work). Hold (data is ambiguous; gather more before deciding). Kill (the campaign is not incremental enough to justify the spend). + +--- + +## Reference files + +- [`references/metric-definitions-glossary.md`](references/metric-definitions-glossary.md) - CTR, CPC, CPM, CPA, ROAS, LTV, AOV, frequency, reach, impressions, conversion window, view-through, modeled conversion, blended CAC, MER. +- [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md) - Last-click, first-click, linear, time-decay, U-shaped, DDA, MMM. Decision matrix by business stage. +- [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md) - Google PMax black box, Meta iOS impact and Conversions API, LinkedIn 30-day click defaults, TikTok video-completion attribution, programmatic viewability gates. +- [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md) - Geo holdout, ghost bidding, conversion lift, PSA tests, switchback designs. Setup, duration, analysis pattern, expected incremental rates. +- [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md) - Warehouse as canonical, platform as in-flight signal, blended CAC formula, board-deck patterns, reconciliation cadence. +- [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md) - By acquisition month, channel, and campaign. Retention curves, when to act on cohort signals. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it incremental zero + +Most paid media spend is not 100% incremental. Some channels are 70% incremental. Some are 30%. Some are zero, paying for conversions you would have gotten anyway. + +The discipline of accepting that channels can be incremental zero, and pulling spend accordingly, is the single highest-impact skill in paid media analytics. Most accounts have at least one campaign that looks profitable in the platform but is incremental zero in the warehouse. Branded paid search at $4 CPC when the same users find you at position one organically. Retargeting at $0.30 CPC for users who already added items to cart. PMax cannibalizing free brand traffic. + +The discipline of finding those campaigns and killing them is the work. The platform will not tell you. The platform's incentive is the opposite. The warehouse, paired with quarterly incrementality tests, is the only honest source. + +When in doubt about whether a campaign is incremental, run a geo holdout. The two-week test is cheaper than a quarter of unincremental spend. The team that does not run incrementality tests is optimizing against numbers that are systematically wrong, and the size of the error is exactly the size of the budget waste. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md b/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md new file mode 100644 index 0000000..55d3e3f --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md @@ -0,0 +1,128 @@ +# Attribution model comparison + +For each major attribution model: definition, fit, bias direction, and a worked example showing how the same activity gets different attribution. + +The principle. No model is right. They are all approximations. The discipline is to pick one as the primary view, read the others as sanity checks, and report against the warehouse rather than against any single platform's view. + +--- + +## The models + +### Last-click + +**Definition.** Full credit to the last clickable touchpoint before conversion. + +**When it fits.** Early-stage measurement where simplicity matters more than precision. Final-stage decisions where the closer matters more than the opener. + +**When it does not fit.** Awareness-channel evaluation. Brands with multi-touch sales cycles. Anything upper-funnel. + +**Bias direction.** Undercredits awareness channels (display, video, top-of-funnel social). Overcredits closing channels (branded search, retargeting). + +### First-click + +**Definition.** Full credit to the first touchpoint in the conversion path. + +**When it fits.** Awareness-channel evaluation. Comparing top-of-funnel sources. + +**When it does not fit.** Closing-channel evaluation. Performance optimization at the bid level. + +**Bias direction.** Mirror image of last-click. Undercredits closing; overcredits opening. + +### Linear + +**Definition.** Equal credit across every touchpoint in the conversion path. + +**When it fits.** Board-deck reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. Defensible-by-default. + +**When it does not fit.** Decisions where the marginal contribution of each channel matters. Linear treats first-click and last-click the same; reality usually does not. + +**Bias direction.** Diffuses credit. Channels that touched the path always get something; channels that drove the conversion do not get more. + +### Time-decay + +**Definition.** More credit to recent touchpoints. Older touchpoints get progressively less. + +**When it fits.** When the intuition is that recent ads are more influential. Reasonable for short-cycle B2C. + +**When it does not fit.** Long sales cycles where the first touchpoint may have been months before the close. Decay underweights the opener. + +**Bias direction.** Skews toward the closer. Slightly less aggressive than last-click. + +### U-shaped (position-based) + +**Definition.** 40% credit to first touch. 40% credit to last touch. 20% distributed across middle touches. + +**When it fits.** When you want to honor both opener and closer roles without flattening to linear. Reasonable default for most B2C. + +**When it does not fit.** Single-touch paths (awards 80% to a single touchpoint, which is over-attributing). Long paths where the middle touchpoints matter as much as the ends. + +**Bias direction.** Balances the last-click and first-click views into one number. + +### Data-driven attribution (DDA, Google) + +**Definition.** Machine-learning model that distributes credit based on observed conversion paths. Compares paths that did and did not convert; assigns credit to touchpoints that correlate with conversion. + +**When it fits.** Mature accounts with sufficient conversion volume (Google requires 600+ conversions per month for DDA). Cross-channel optimization. + +**When it does not fit.** Sub-scale accounts. Accounts that need explainability for regulators or boards. The black-box nature is hard to audit. + +**Bias direction.** Best in class for digital channels where the data is clean. Still suffers from platform self-attribution bias because Google's DDA only sees Google touchpoints. + +### Marketing mix modeling (MMM) + +**Definition.** Regression-based, top-down. Models the relationship between spend across channels and revenue over time. Typically requires 2 to 3 years of data. + +**When it fits.** Mature accounts with cross-channel spend at scale. Brands where offline channels (TV, OOH, podcast) contribute. Anywhere platform self-attribution bias is a real concern. + +**When it does not fit.** Early-stage accounts without enough historical data. Fast-changing channel mixes where the historical data does not represent current reality. + +**Bias direction.** The strongest defense against platform self-attribution because MMM does not rely on platform-reported conversions. Limitations are statistical: confidence intervals are wide; granularity is low (channel-level, not campaign-level). + +--- + +## The same path under each model + +A worked example. A B2C SaaS user converts after this path: + +1. Sees a YouTube awareness ad (impression, not click). +2. Clicks a Meta retargeting ad three days later. +3. Searches for the brand on Google. Clicks a paid branded search ad. +4. Returns directly the next day. Converts. + +Attribution by model. + +| Model | YouTube | Meta | Branded Search | Direct | +|---|---|---|---|---| +| Last-click | 0% | 0% | 0% (depending on direct vs paid) | 100% | +| First-click | 0% (impressions excluded) | 100% | 0% | 0% | +| Linear | 0% | 33% | 33% | 33% | +| Time-decay | 0% | 15% | 35% | 50% | +| U-shaped | 0% | 40% | 20% | 40% | +| Google DDA | (only sees Google touchpoints) | (only sees Meta touchpoints if Conversions API integration) | varies | varies | +| MMM | partial credit (spend in YouTube correlates with conversions) | partial credit | partial credit | (organic, not modeled) | + +The takeaway. Same path. Five different attribution stories. None is right. Each tells you something different. + +--- + +## Decision matrix by business stage + +| Stage | Primary model | Secondary check | Why | +|---|---|---|---| +| Pre-PMF | Last-click + warehouse-attributed CAC | None; insufficient volume for sophisticated models | Sophisticated attribution needs volume you do not have | +| Series A or early growth | Last-click + GA4 data-driven | First-click as sanity check on awareness | Volume insufficient for MMM; DDA requires more conversions than most early-stage accounts have | +| Mid-stage (10K+ conversions per month) | Google DDA + GA4 path data | Last-click for channel decisions; first-click for awareness | DDA gets reliable here; cross-validate with simple models | +| Mature (100K+ conversions per month, 2+ years data) | MMM as canonical | Last-click for in-flight; DDA for cross-channel | MMM is the strongest defense against self-attribution at scale | +| Multi-channel including offline | MMM mandatory | DDA for digital | MMM is the only model that captures offline contribution | + +The progression. As volume grows and channel mix expands, the model that fits changes. Locking in last-click forever is fine if the business stays simple; the moment offline or upper-funnel channels matter, the model has to advance. + +--- + +## How to communicate which model produced which number + +Three rules for honest reporting. + +1. **Always label the model.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions on last-click attribution with a 7-day-click window" is honest. +2. **Report the same number under at least two models when stakes are high.** Board decks should show the conservative view (last-click) and the generous view (linear or DDA). The range tells stakeholders what they are not learning. +3. **Reconcile against the warehouse before reporting in dollars.** Dollar figures attached to platform-reported conversions inherit all the platform's attribution biases. Warehouse-attributed dollars are the only dollars that have been independently verified. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md b/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md new file mode 100644 index 0000000..dbd3fdb --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md @@ -0,0 +1,113 @@ +# Cohort analysis templates + +Three cohort cuts that matter for paid media. By acquisition month, by channel, by campaign. Plus retention curves and when to act. + +The principle. Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. The difference is the leading indicator that a channel or campaign is degrading; daily metrics catch the same problem two to three months later when it shows up in revenue. + +--- + +## Template 1: Cohort by acquisition month + +The standard rolling 12-month view of LTV growth. + +**Setup.** For each acquisition month over the last 12 months, compute the cumulative revenue per customer at month 1, month 3, month 6, and month 12 (where data is available). + +**Output.** + +| Acquisition month | M1 revenue/customer | M3 revenue/customer | M6 revenue/customer | M12 revenue/customer | +|---|---|---|---|---| +| 2025-05 | $42 | $86 | $128 | $185 | +| 2025-06 | $44 | $89 | $135 | $192 | +| 2025-07 | $40 | $82 | $122 | $178 | +| 2025-08 | $43 | $85 | $130 | (incomplete) | +| 2025-09 | $38 | $78 | (incomplete) | (incomplete) | +| 2025-10 | $35 | $72 | (incomplete) | (incomplete) | +| 2025-11 | $33 | $68 | (incomplete) | (incomplete) | +| 2025-12 | $34 | (incomplete) | (incomplete) | (incomplete) | + +**The signal.** The M3 revenue per customer dropped from $86 to $68 over six months. Recent acquisitions are lower-quality customers. The daily metrics will show this as ROAS deterioration in two to three months when the recent cohorts hit their declining LTV plateau. + +**Action.** Investigate which channels or campaigns shifted in the last six months. The drop usually correlates with a specific channel scaling into lower-quality audiences. + +--- + +## Template 2: Cohort by acquisition channel + +The channel-level LTV story that ROAS hides. + +**Setup.** For each channel, compute LTV at fixed time windows (30, 60, 90, 180, 365 days post-acquisition). Track the trend over multiple acquisition cohorts. + +**Output (cohort: 2025-Q3 acquisitions, measured at 90 days post-acquisition).** + +| Channel | New customers | CAC | 90-day revenue/customer | 90-day LTV/CAC | Verdict | +|---|---|---|---|---|---| +| Google brand search | 420 | $45 | $128 | 2.8x | Strong | +| Google generic search | 280 | $95 | $112 | 1.2x | Marginal | +| Meta prospecting | 540 | $72 | $84 | 1.2x | Marginal | +| Meta retargeting | 320 | $48 | $156 | 3.3x | Strong | +| LinkedIn Sponsored | 95 | $320 | $580 | 1.8x | Long payback; B2B-typical | +| TikTok In-Feed | 180 | $58 | $61 | 1.1x | Marginal | +| Direct (organic) | 1,200 | n/a | $145 | n/a | Reference baseline | + +**The signal.** Meta retargeting and Google brand search are the strong performers on LTV-CAC. Meta prospecting and TikTok In-Feed are marginal; the customer quality is lower than the platform-reported ROAS suggests. + +**Action.** The marginal channels need either CAC reduction or audience-quality improvement. Pulling back on the marginal channels and reallocating to the strong ones improves blended LTV-CAC. + +--- + +## Template 3: Cohort by acquisition campaign + +Campaign-level cohort signals. Use sparingly; sample sizes get small fast. + +**Setup.** For each campaign with sufficient acquisition volume (typically 100+ customers per cohort), compute LTV at 30 and 60 days. Compare against the channel average. + +**Output.** + +| Campaign | New customers | CAC | 60-day revenue/customer | vs channel average | +|---|---|---|---|---| +| Meta-Lookalike-1pct | 320 | $58 | $112 | +30% | +| Meta-Lookalike-5pct | 180 | $48 | $74 | -15% | +| Meta-Interest-SaaS | 90 | $72 | $86 | -5% | +| Meta-Retargeting-30day | 240 | $42 | $148 | +60% | + +**The signal.** The 5% lookalike is finding lower-quality customers than the 1% lookalike, even at lower CAC. The ROAS view favors the 5% lookalike (lower CAC, decent revenue); the cohort view shows the customer quality dropped. + +**Action.** Pull back the 5% lookalike. Concentrate spend on the 1% lookalike and the retargeting segments. Watch for next-cohort confirmation before a permanent reallocation. + +--- + +## Retention curves + +A retention curve plots customer activity over time. Three patterns to recognize. + +**Plateau curve.** Activity drops in the first 30 days, then stabilizes at a level it sustains long-term. The plateau height is the long-run user value. Healthy SaaS, subscription consumer, marketplace. + +**Smile curve.** Activity drops, plateaus, then trends upward (resurrection effect). Less common; characteristic of products with seasonal or lifecycle re-engagement. + +**Decay curve.** Activity drops continuously without stabilizing. The product is not retaining; the unit economics will not work no matter what CAC the channel produces. Common in low-engagement consumer apps. + +**The curve to watch by acquisition channel.** A channel whose retention curve plateaus higher than another is delivering higher-LTV customers, regardless of the CAC ratio. This is the data behind LTV-CAC channel comparisons. + +--- + +## When to act on cohort signals + +Three triggers. + +1. **Two consecutive months of LTV decline at the same time horizon.** A single month is noise; two is signal. Investigate which channels shifted. +2. **Channel-level LTV-CAC ratio falls below 2x for two consecutive cohorts.** Pause or reallocate the channel. The 2x threshold accounts for gross margin, payback period, and the variance in LTV measurement. +3. **A campaign-level cohort underperforms the channel average by 20%+ for two consecutive cohorts.** The campaign is bringing in lower-quality audiences than the rest of the channel. Pause or reallocate. + +The discipline. Watch cohort signals on a monthly cadence. Most teams over-index on weekly platform metrics and under-index on cohort signals; the cohort-watchers see the problems first. + +--- + +## Common cohort mistakes + +**Reading recent cohorts as final.** A 30-day cohort's "LTV" is actually 30-day revenue, not LTV. Naming matters. If the team treats 30-day revenue as LTV in spreadsheets, they will undercount channels with longer payback periods. + +**Comparing cohorts at different ages.** A January cohort measured at 12 months vs a November cohort measured at 2 months is comparing different things. Always compare at matched ages. + +**Ignoring seasonal cohorts.** Q4 cohorts often have higher first-purchase value but lower retention because Q4 acquisition includes one-time gifters. Account for the seasonal pattern; do not over-index on Q4 cohort numbers. + +**Not segmenting by channel.** Aggregate LTV trends hide channel-level shifts. The channel-segmented cohort is where the action signal lives. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md b/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..5b6e91d --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md @@ -0,0 +1,155 @@ +# Common interpretation failures + +Twelve failure patterns that recur in paid media reporting work. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. ROAS dropped 20% week-over-week, kill the campaign + +**Symptom.** Weekly ROAS chart shows a drop. Team wants to pause the campaign. + +**Root cause.** Could be noise. Day-of-week, holiday timing, conversion-window lag, exogenous variance. A 20% drop in a metric that varies 10 to 15% naturally is below the signal threshold. + +**Fix.** Pre-commit a test window before acting on weekly variance. For most campaigns, two consecutive weeks of decline below the threshold is the signal. Single-week swings are usually noise. + +**Prevention.** Establish baseline variance for each campaign before declaring "improvement" or "decline." Without the baseline, every weekly chart looks alarming. + +--- + +## 2. Meta says 500 conversions, my warehouse says 200, who is right + +**Symptom.** Platform-reported numbers do not match warehouse numbers. The team picks the more flattering one. + +**Root cause.** Both are wrong; warehouse is closer to truth. Meta self-attributes (claims credit for conversions other channels also touched). View-through and modeled conversions inflate Meta's count. + +**Fix.** Reconcile, do not pick a winner. Report the warehouse number as canonical for board metrics. Use Meta's number only for in-flight optimization within Meta. + +**Prevention.** Make the reconciliation cadence explicit. Weekly check, monthly deep dive, quarterly attribution review. The team that runs the reconciliation never has to "pick a winner." + +--- + +## 3. Turned off Google PMax, conversions did not drop + +**Symptom.** Paused PMax. Total account conversions held steady. + +**Root cause.** PMax was harvesting branded search conversions you would have gotten free from organic. The platform was claiming credit for traffic that was not incremental. + +**Fix.** Audit branded queries inside PMax. Add account-level negative keywords for branded queries. Restart PMax with branded excluded; the incremental contribution from non-branded inventory is the real value. + +**Prevention.** At PMax setup, exclude branded queries from the start. Audit PMax's spend distribution monthly to catch the cannibalization pattern early. + +--- + +## 4. New campaign hit 5x ROAS in week 1 + +**Symptom.** A fresh campaign's first-week ROAS is 5x. Team wants to scale immediately. + +**Root cause.** Likely retargeting hot leads or running on a small audience of warm prospects who would have converted anyway. The first week is unrepresentative. + +**Fix.** Check the audience composition. If retargeting or warm-list, the 5x is not the steady-state. Wait two to four weeks before scaling. + +**Prevention.** Define the success metric and the test window before launch. Do not let a strong first week change the plan; pre-commit to the four-week measurement. + +--- + +## 5. A/B tested and one creative wins by 12% + +**Symptom.** Two creatives tested. One wins by 12%. Team wants to ship the winner. + +**Root cause.** 12% is within margin of platform noise for a typical creative test. Variants compete with each other inside the platform's optimization; the platform's own decisions confound the test. + +**Fix.** Re-run the test with more volume, or accept that the difference is within noise and pick based on production cost or refresh ease. + +**Prevention.** Set the minimum detectable effect (MDE) before testing. A 12% threshold requires a specific volume; if you cannot reach it, the test cannot detect that effect cleanly. + +--- + +## 6. LTV calculation says this channel is profitable + +**Symptom.** A team's LTV-CAC analysis shows a channel as profitable. Spend is increased. + +**Root cause.** The "LTV" in the calculation may be a 60-day cumulative revenue projected forward, not actual lifetime value. Recent cohorts have not aged enough to confirm the LTV. + +**Fix.** Confirm the cohort age. If projecting forward, document the assumption and stress-test (what happens if actual LTV is 80% of projected). + +**Prevention.** Always pair LTV calculations with cohort age. A 30-day cohort has 30-day revenue, not LTV. Naming clearly prevents the substitution error. + +--- + +## 7. High frequency is fine because conversions are still happening + +**Symptom.** Frequency at 6 to 8 per week. Conversions on the platform are stable. Team concludes fatigue is not an issue. + +**Root cause.** Fatigue masked by conversions that would have happened anyway from organic, retargeting overlap, or recurring customers. The platform is taking credit for traffic the high frequency did not actually drive. + +**Fix.** Run an incrementality test on the high-frequency campaign. The likely finding is that incremental rate dropped substantially even as raw conversions held. + +**Prevention.** Watch frequency as a leading indicator. Above 4 to 5 per week is the alarm regardless of conversion levels. Refresh creative. + +--- + +## 8. Last-click attribution shows Meta at 60% credit + +**Symptom.** Last-click view of paid media shows Meta dominant. Team allocates budget accordingly. + +**Root cause.** Last-click bias. Meta may also be the closer because users who searched for the brand on Google clicked through, then later saw a Meta retargeting ad and converted. Last-click credits Meta; the conversion would have happened anyway. + +**Fix.** Read the same data under first-click and a multi-touch model. The picture changes. Allocate based on a balanced view, not the last-click view alone. + +**Prevention.** Always compare attribution under at least two models for budget decisions. The single-model view is reliable for in-flight only. + +--- + +## 9. Scaled spend 5x, conversions only doubled + +**Symptom.** Budget went from $20K to $100K per month. Conversions went from 800 to 1,600. + +**Root cause.** Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher than the average CAC the team was reporting. + +**Fix.** Calculate the marginal CAC, not just average CAC. The marginal CAC at the higher spend tier tells you whether more spend will produce more conversions or just spend more for the same conversions. + +**Prevention.** Project the saturation curve before scaling. If a 1.5x spend increase produced a 1.2x conversion increase, expect the next 1.5x to produce 1.0x or less. + +--- + +## 10. Brand campaigns underperform on direct ROAS + +**Symptom.** A brand campaign reports 0.8x ROAS. Team wants to cut it. + +**Root cause.** Brand campaigns affect downstream channel efficiency, not direct conversion. The direct ROAS is the wrong measurement for brand impact. + +**Fix.** Measure brand against brand-search lift, organic traffic growth, or direct-traffic growth. The brand campaign's effect shows up in cheaper performance acquisition over the next 60 to 90 days. + +**Prevention.** At brand campaign setup, define the success metric explicitly (brand search lift target, organic traffic target, awareness lift). Do not let direct ROAS become the unintended grading metric. + +--- + +## 11. ROAS held steady but profit dropped + +**Symptom.** Channel-level ROAS at 3x, stable. Profit on the same channel dropped 20% over the quarter. + +**Root cause.** The mix shifted toward lower-margin products. ROAS is a revenue metric; it does not see margin. The channel attracted bargain hunters at lower margin, holding ROAS but cutting profit. + +**Fix.** Track contribution-margin ROAS, not gross-revenue ROAS. The contribution-margin view catches the mix shift the gross view hides. + +**Prevention.** Build margin-aware reporting from the start. Most teams default to gross revenue; the move to contribution margin pays for itself within a quarter. + +--- + +## 12. Agency reported a 4x ROAS month + +**Symptom.** External agency claims a 4x ROAS for the month. Team accepts the number. + +**Root cause.** Whose number? Platform-reported, warehouse-attributed, or model-adjusted? Agencies often report the most generous number (their incentive). Without specifying the attribution methodology, the 4x ROAS is unreadable. + +**Fix.** Demand the attribution methodology in every agency report. Reconcile against the warehouse before presenting to leadership. + +**Prevention.** Build attribution-methodology specification into the agency contract. Reports must include the model, the window, and the source of conversion data. The contract that does not specify produces reports that cannot be evaluated. + +--- + +## The pattern across all twelve + +Most paid media interpretation failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale ROAS at the cost of LTV. Pause an underperformer at the cost of total volume. Trust platform-reported attribution at the cost of incremental truth. + +The fix at the meta level. Decide on the success metric (warehouse-attributed CAC, LTV-CAC ratio, contribution-margin ROAS) and the guardrails (volume, frequency, customer-cohort quality, brand metrics) before reading any dashboard. Pull back the moment a guardrail breaks, even if the success metric still looks fine. The dashboard is a tool, not the truth; the warehouse plus quarterly incrementality testing is closer to truth. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md b/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md new file mode 100644 index 0000000..1066402 --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md @@ -0,0 +1,114 @@ +# Dashboard reconciliation patterns + +The single-source-of-truth pattern for paid media reporting. Warehouse as canonical; platforms as in-flight signals. + +The principle. Sum-of-platform-reports is always greater than reality because every platform claims credit for conversions other platforms also touched. Reporting platform-summed numbers as fact in board decks is the most expensive error in paid media analytics. + +--- + +## The three-layer reporting model + +**Layer 1: platform metrics.** Use for in-flight optimization only. Ad-set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +**Layer 2: warehouse multi-touch attribution.** Use for cross-platform comparison and channel-level decisions. Each conversion gets attributed across all platforms that touched the path. Pick one model (last-click, first-click, linear, U-shaped, DDA) and standardize across the team. + +**Layer 3: marketing-mix modeling (MMM) at scale.** Use for budget allocation across channels. MMM treats spend as input and revenue as output; it does not rely on platform-reported attribution at all. The strongest defense against platform self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## Blended CAC + +The board-deck number. Resistant to attribution debates because it does not require choosing an attribution model. + +**Formula.** + +``` +Blended CAC = (total ad spend across platforms) / (total new customers from warehouse) +``` + +**Worked example.** + +In Q4, the team spent $200K total: $80K on Google Ads, $70K on Meta, $30K on LinkedIn, $20K on TikTok. The warehouse shows 1,250 new customers in Q4 from all sources (paid, organic, direct, referral). + +But the team needs to attribute the new customers to paid specifically. Two ways to do this: + +1. **Approximate.** Assume the proportion of paid-attributed customers in the warehouse roughly equals the proportion that paid contributed to traffic. If 60% of traffic in Q4 was paid-attributed, then 60% of 1,250 equals 750 paid-acquired customers. Blended paid CAC: $200K / 750 = $267. +2. **Precise.** Use the warehouse's multi-touch attribution to credit paid channels with a fraction of each conversion. Sum the paid-attributed share across all conversions; that becomes the denominator. + +The precise version is better when available. The approximate version works when the warehouse data is incomplete. Both produce a number that does not double-count across platforms. + +--- + +## The board-deck pattern + +Three rules for reporting paid media numbers to leadership. + +1. **Lead with blended CAC, not channel CAC.** Channel CAC depends on attribution model; blended CAC does not. Stakeholders not in the weeds on attribution find blended CAC easier to compare across quarters. +2. **Show the range.** Report the conservative view (last-click) and the generous view (linear or DDA) for any high-stakes channel decision. The range tells stakeholders what they are not learning. +3. **Always label the source.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions per Meta's 7-day-click attribution; warehouse-attributed: 540" is honest. + +A worked example board slide. + +``` +Q4 paid media performance + +Total spend: $200K (vs $185K Q3, +8%) +New customers from paid (warehouse-attributed): 750 (vs 680 Q3, +10%) +Blended paid CAC: $267 (vs $272 Q3, -2%) + +Channel CAC (warehouse-attributed, last-click): + Google: $240 (40% of new customers) + Meta: $290 (35% of new customers) + LinkedIn: $480 (15% of new customers) + TikTok: $180 (10% of new customers) + +Platform-reported CAC (for in-flight context, not board decision): + Google: $190 (Google reports 26% more attributed conversions than warehouse) + Meta: $210 (Meta reports 38% more) + LinkedIn: $475 (roughly aligned) + TikTok: $135 (TikTok reports 33% more) + +Quarterly incrementality test result (geo holdout, October): + Brand search: 12% incremental (95% CI: 6-18%). Reduced spend 30%; CAC dropped. + Meta retargeting: 31% incremental (95% CI: 22-40%). Maintained spend; CAC view adjusted. +``` + +The slide tells the truth: the warehouse number is the canonical CAC, the platform numbers are inflated, the incrementality test confirms which channels are real. + +--- + +## Reconciliation cadence + +**Weekly.** Pull platform-reported numbers and warehouse numbers. Confirm the sum-of-platforms vs warehouse ratio is in the expected range. A sudden divergence means a tracking break, an attribution-model change, or a platform reporting bug. Investigate. + +**Monthly.** Deeper reconciliation. Compare channel-level attribution across last-click, first-click, and the team's chosen model. Identify channels whose ranking changes by model. + +**Quarterly.** Run an incrementality test on the highest-spend channel. Update the channel-level CAC adjustment factor based on the test result. + +--- + +## Common reconciliation mistakes + +**Reporting platform-summed conversions to the board.** The most common error. The board sees "1,600 conversions across paid channels" when the warehouse says 950. The team gets caught when someone divides revenue by 1,600 and gets a CAC that does not match the P&L. + +**Comparing platforms on platform-reported CAC.** Each platform's CAC is computed against a different attribution window and a different set of self-attribution biases. Compare on warehouse-attributed CAC instead. + +**Treating "lift" as incrementality without a controlled test.** A campaign that ran during a period of overall conversion growth gets credit for "lift" that was actually seasonality or organic momentum. Lift requires a control group; otherwise it is correlation reported as causation. + +**Updating attribution models mid-quarter.** Switching from last-click to DDA mid-quarter makes the quarter's data uninterpretable. Pick a model for the quarter; switch only at quarter boundaries with a documented changelog. + +**Reporting blended CAC without naming the time window.** "$267 blended CAC" depends on whether you measured over 30, 60, or 90 days. Pin the window. + +--- + +## When the platforms agree more than usual + +A useful diagnostic. If platform-reported sums match warehouse total within 10%, something has changed. Possibilities: + +- The team set up Conversions API on Meta or server-side tagging on Google, which improved tracking precision. +- The mix shifted toward branded search, where attribution overlap is lower. +- One platform's conversion volume dropped significantly (saturation, fatigue, or campaign issue). + +Investigate any sudden alignment. The platforms diverging is the normal state; alignment usually has a cause worth understanding. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md b/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md new file mode 100644 index 0000000..a52ea6c --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md @@ -0,0 +1,139 @@ +# Incrementality testing playbook + +The honest test in paid media analytics. If we had not run this ad, would we still have gotten the conversion? The answer above zero is the incremental contribution. + +The principle. Most paid media is not 100% incremental. Branded search bidding is often 5 to 20% incremental. Retargeting is often 20 to 40% incremental. Prospecting is often 50 to 90% incremental. The number that matters for spend decisions is the incremental rate, not the platform-reported attribution rate. + +--- + +## Method 1: Geo holdout + +The cleanest causal test for paid media at scale. + +**Setup.** Pick two regions with similar baseline conversion rates and demographic profiles (matched markets). Run the campaign in one region (test); turn it off in the other (holdout). + +**Duration.** Two to four weeks minimum. Statistical power calculation upfront determines the right length given the spend scale and expected lift. + +**Analysis.** Compare conversions in test vs holdout, normalized by population. The difference is the incremental contribution. + +**Expected incremental rate ranges.** + +| Channel | Typical incremental rate | +|---|---| +| Branded search | 5 to 20% | +| Retargeting | 20 to 40% | +| Lookalike audiences | 40 to 70% | +| Cold prospecting | 50 to 90% | +| Awareness video | 30 to 60% | + +**Common pitfalls.** + +- Picking holdout regions with confounding factors (different competitive presence, weather event, retail launch). Confounded results are worse than no test. +- Stopping the test early when the data looks good. Pre-commit the duration and stick to it. +- Holding out for too long. A 6-week holdout in a small region is expensive in lost conversions; 2 to 4 weeks is usually enough at scale. + +--- + +## Method 2: Ghost bidding (Google) + +Google's own incrementality tool. The platform bids on a holdout share of impressions but does not actually serve the ad. The reported delta between served and ghost is incremental. + +**Setup.** Configure within Google Ads. Choose the campaigns and the holdout share (typically 5 to 20%). + +**Duration.** Two to four weeks. + +**Analysis.** Google reports incremental conversions directly. Cross-validate against your own warehouse measurement. + +**Pitfalls.** + +- The math is opaque to many teams. The output is a single incremental number; the underlying methodology is Google's. Trust but verify with a manual geo test on the same campaign. +- Only available within Google Ads, not cross-channel. + +--- + +## Method 3: Conversion lift studies (Meta) + +Meta's incrementality tool. Splits audiences into test (sees the ad) and control (does not). Measures lift. + +**Setup.** Configure within Meta Ads Manager. Specify the campaign and the test-control split. + +**Duration.** Three to four weeks. Meta requires a minimum spend per study. + +**Analysis.** Meta reports incremental lift. The reporting includes statistical significance bands. + +**Pitfalls.** + +- The minimum spend requirement makes it expensive for small accounts. +- Only available within Meta, not cross-channel. +- Meta's interpretation tilts toward generous (their incentive). Cross-validate with geo holdout when possible. + +--- + +## Method 4: PSA tests + +Serve some users a public service announcement instead of your ad. Compare conversion rates. + +**Setup.** Run two parallel campaigns: one with your ad, one with a PSA (typically a charity or public-interest message). Match audiences. + +**Duration.** Three to six weeks. + +**Analysis.** Compare conversion rate of the PSA-exposed audience against the ad-exposed audience. The difference is incremental. + +**Pitfalls.** + +- Ethically and brand-wise, choose PSAs that align with brand values. +- Setup overhead is high. Reserved for legacy brands with deep budgets and serious incrementality questions. + +--- + +## Method 5: Switchback designs + +Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. + +**Setup.** Run for at least 8 weeks. Alternate weekly: on, off, on, off. Or alternate by audience segment. + +**Duration.** Eight to twelve weeks. Shorter switchbacks have low statistical power. + +**Analysis.** Difference in conversions between on-weeks and off-weeks, normalized for week-of-year and external variance. + +**Pitfalls.** + +- Confounded by exogenous factors (news, competitor activity, seasonality). Best for steady-state campaigns where the external context is stable. +- Audience contamination: users who saw the ad in week 1 may convert in week 2 even when the campaign is off. The contamination dilutes the measured incremental rate. + +--- + +## Choosing the right method + +| Constraint | Recommended method | +|---|---| +| Single platform, want quick answer | Platform-native (ghost bidding for Google, conversion lift for Meta) | +| Cross-platform incremental test | Geo holdout | +| Small account, limited budget | Geo holdout in two small matched markets | +| Long campaign cycle, steady-state | Switchback | +| Brand or awareness channel | PSA test or geo holdout | +| Regulated industry, ethics concern | Geo holdout (no PSA) | + +The default. Geo holdout. It is the most honest causal test, works cross-channel, and produces results that are interpretable without trusting the platform's methodology. + +--- + +## How to run a geo holdout step by step + +1. **Pick matched markets.** Use designated market areas (DMAs) or postal-code-level regions with similar baseline conversion rates and demographic profiles. Aim for at least three test and three holdout regions for statistical power. +2. **Calculate statistical power.** Given the expected lift and the regional conversion volume, can the test detect the effect? If the regions are too small, the test is underpowered and inconclusive results are likely. +3. **Pre-commit the analysis window.** Define the start date and end date before the test begins. Do not adjust based on early results. +4. **Run the test.** Campaign on in test regions; off in holdout. No mid-test changes. +5. **Wait for the full window.** Analyzing early produces noise. +6. **Compute the delta.** Conversions in test minus conversions in holdout, normalized by population. The delta divided by spend is the incremental CPA. Compare against the platform-reported CPA; the gap is the over-attribution. +7. **Report incremental contribution.** Do not report platform-reported CAC alongside warehouse CAC and incremental CAC without labeling. The unit of measurement matters as much as the number. + +--- + +## Cadence + +For accounts spending $25K+ per month, run incrementality tests at least quarterly on the highest-spend channels. The cost of the test is small relative to the cost of running un-incremental spend at scale. + +For accounts under $25K per month, annual or semi-annual tests are typically enough. The test cost vs the spend savings does not pencil out as often. + +The discipline. Schedule the tests. Do not wait for a "we should test this" moment; the moment never comes voluntarily. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md b/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md new file mode 100644 index 0000000..ee569ff --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md @@ -0,0 +1,83 @@ +# Metric definitions glossary + +The paid media metrics that show up on every dashboard, with explicit definitions, formulas, and the common pitfalls in usage. + +The point of an explicit glossary. Two teams using the same metric name often compute different numbers. "Conversion rate" might mean clicks-to-conversion or impressions-to-conversion or unique-users-to-conversion. The team that does not pin definitions ends up arguing about numbers that are not the same number. + +--- + +## Volume metrics + +**Impressions.** Count of times an ad was displayed. Includes the same user seeing the ad multiple times. + +**Reach.** Count of unique users who saw the ad. Always less than or equal to impressions. + +**Frequency.** Impressions divided by reach. The average number of times a unique user saw the ad. Above 4 to 5 per week is the fatigue alarm. + +**Clicks.** Count of clicks on the ad. Some platforms count "outbound clicks" (which leave the platform) separately from "all clicks" (which include in-platform interactions like saves and shares). Use outbound for direct response. + +--- + +## Cost metrics + +**CPC (cost per click).** Spend divided by clicks. Formula: `spend / clicks`. The cost of one click; not the cost of one conversion. Conflating them is the most common reporting error. + +**CPM (cost per thousand impressions).** Spend divided by (impressions / 1000). Formula: `spend / (impressions / 1000)`. The cost of reach. Useful for comparing platforms on awareness efficiency. + +**CPA (cost per acquisition).** Spend divided by conversions. Formula: `spend / conversions`. The variant where "conversion" is defined matters; the same campaign reports different CPAs depending on whether the conversion is a click, a lead form submission, a purchase, or a paid customer. + +**ROAS (return on ad spend).** Revenue from ad-attributed conversions divided by spend. Formula: `attributed revenue / spend`. NOT profit-divided-by-spend. ROAS is a revenue metric, not a profit metric. A 3x ROAS at 30% margin is a 0.9x return on cost; the ROAS reading on its own is misleading. + +**MER (marketing efficiency ratio).** Total revenue divided by total marketing spend, across all channels. Formula: `total revenue / total marketing spend`. The most honest top-line number; resistant to per-channel attribution debates. + +**Blended CAC.** Total ad spend divided by total new customers from warehouse. Formula: `total ad spend / new customers from warehouse`. The board-deck number. Channel-level CAC depends on attribution; blended CAC does not. + +--- + +## Conversion metrics + +**Conversion.** The event the campaign optimizes for. Definition varies. Always document: which event, what window, which attribution model. Without these three, "conversions = 800" is unreadable. + +**Conversion rate.** Conversions divided by something. The denominator changes the meaning. Click-through conversion rate (`conversions / clicks`) is different from impression conversion rate (`conversions / impressions`) which is different from unique-user conversion rate (`conversions / reach`). Pin the denominator at every report. + +**Conversion window.** The maximum time between the ad event (click or view) and the conversion for which the platform takes credit. Meta default: 7-day click plus 1-day view. Google default: 30-day click plus 1-day view. Different windows mean different reported counts from the same activity. + +**View-through conversion.** A conversion attributed to an ad the user saw but did not click. Counted by Meta and Google. Often half the platform-reported conversions are view-through. Treat as a soft signal of awareness contribution, not as direct response measurement. + +**Modeled conversion.** A statistically estimated conversion when actual tracking is blocked (most commonly iOS users on Meta after ATT). The platform models what the conversion would have been based on aggregated data. Modeled is an estimate, not a measurement; precision is low. + +--- + +## Customer-value metrics + +**LTV (lifetime value).** Total revenue from a customer over their relationship with the brand. Many definitions; the right one for paid media analytics is gross revenue or contribution margin, not unit count. Pair with CAC for the LTV:CAC ratio. + +**LTV:CAC ratio.** LTV divided by CAC. Formula: `LTV / CAC`. The unit-economics test. 3:1 is the venture-capital benchmark; the right number for any specific business depends on payback period and gross margin. + +**Payback period.** Months until cumulative revenue from a customer equals the CAC to acquire them. The cash-flow companion to LTV:CAC. Investors care about payback; operators care about both. + +**AOV (average order value).** Revenue divided by order count. Formula: `revenue / orders`. Useful for e-commerce; less for subscription. The number that turns "increased conversion rate" into "increased revenue." + +--- + +## Engagement metrics (less direct) + +**CTR (click-through rate).** Clicks divided by impressions. Formula: `clicks / impressions`. Useful for hook quality. Less useful for conversion quality; high CTR with low conversion rate means the hook is too aggressive for the offer. + +**Hide ratio (negative feedback).** Count of users who explicitly hid or marked the ad as not-interested, divided by impressions. Above 1.5% is the alarm; the platform algorithm will throttle delivery to that audience. + +**Engagement rate.** Likes plus comments plus shares plus saves divided by impressions. Useful for organic-style content; less directly tied to performance for paid. + +--- + +## Common pitfalls + +**Treating ROAS as profit.** ROAS is revenue-divided-by-spend. Profit-divided-by-spend is "return on ad investment" or "ROI." Confusing the two leads to greenlit campaigns that lose money on every conversion. + +**Ignoring conversion window in cross-platform comparisons.** Meta's 7-day-click count is not comparable to Google's 30-day-click count without normalization. + +**Treating frequency as a vanity number.** Frequency above 4 to 5 per week is a fatigue signal. Many teams celebrate high frequency as proof of "audience saturation"; it is the inverse. + +**Using CPA when conversion definitions differ across campaigns.** A search campaign with a "lead-form-submission" conversion has a CPA in different units from a display campaign with a "purchase" conversion. Compare campaign-level CPA only when the conversion event matches. + +**Confusing modeled conversions with measured conversions.** Modeled is an estimate; measured is a count. Treating the two as interchangeable produces false confidence in the size of the effect. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md b/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md new file mode 100644 index 0000000..363477b --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md @@ -0,0 +1,108 @@ +# Platform reporting quirks + +Per-platform reporting behaviors that affect how to read the numbers. The platforms do not agree on what counts as a conversion or how to credit it; reading their dashboards as truth is the most expensive error in paid media analytics. + +--- + +## Google Ads + +**Default attribution model.** Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on machine learning. Single-touch attribution (last-click) is available but no longer the default. + +**Conversion windows.** Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA4 reports by default; this produces the typical 1.3 to 1.5x conversion overcount versus GA4 for the "Google Ads" channel. + +**Modeled conversions.** Google models conversions for users with consent restrictions or cross-device gaps. Modeled volume can be material in iOS-heavy traffic. Modeled is an estimate; do not treat with the precision you would treat directly observed conversions. + +**Performance Max black box.** PMax does not expose keyword-level, placement-level, or audience-level performance directly. The platform manages allocation across Search, Shopping, Display, YouTube, Discover, and Gmail. Levers you have: budget, asset groups (creative quality), audience signals (Customer Match seeds), and exclusions (account-level negatives). + +**Branded search cannibalization in PMax.** PMax includes Search by default. It will harvest branded queries you would have ranked for organically. Add account-level negative keywords for branded queries to prevent paid cannibalization. + +**Lost Impression Share metrics.** Search exposes "Lost IS (rank)" and "Lost IS (budget)" to indicate why your ad did not show. Lost IS rising is the leading indicator that competition increased or budget became constrained. + +**Search-term reports.** The list of actual queries that triggered your ad, vs your keyword targeting. Underused. Audit monthly to find irrelevant queries (negative keyword candidates) and high-performing queries you might want to add as exact-match keywords. + +--- + +## Meta (Facebook and Instagram) + +**Default attribution.** 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +**iOS 14.5+ impact.** App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated) and Conversions API (CAPI, server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +**Conversions API necessity.** CAPI sends server-side events directly from your backend to Meta, bypassing the browser-pixel restrictions. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. Without CAPI, the platform's optimization signal degrades significantly on iOS-heavy audiences. + +**View-through attribution overcount.** View-through counts impressions even when the user did not click. Often half the reported conversions on Meta are view-through. Useful as awareness signal; misleading for performance optimization. + +**Modeled conversions in iOS reports.** Meta reports modeled conversions inline with directly observed ones unless you filter explicitly. Use the breakdown view to disaggregate by attribution type (1-day click, 7-day click, 1-day view, modeled). + +**Frequency reporting at the ad set level.** Meta exposes frequency in the Ads Manager. Use it as the primary fatigue signal; CTR decay is downstream of frequency rising. + +**Negative feedback rate.** Meta exposes "negative feedback rate" as a customizable column. Above 1.5% is the alarm; the algorithm penalizes high-feedback creatives by reducing reach. + +--- + +## LinkedIn + +**Default attribution.** 30-day click and 7-day view-through. + +**Why the longer windows.** B2B buying cycles are longer than B2C. The 30-day-click window matches the typical B2B consideration cycle. Comparing LinkedIn's reported numbers against Meta's 7-day-click numbers without normalizing is comparing different definitions. + +**Cross-device gaps.** LinkedIn reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair LinkedIn paid reports with self-reported attribution surveys when the offer is high-consideration B2B. + +**Lead Gen Forms reporting.** Form submissions count as conversions regardless of downstream lead qualification. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. Many leads are accidental or low-quality. + +**Demographic insights.** LinkedIn's demographic reporting (industry, job seniority, company size, function) is unique to the platform. Use it for audience refinement; the data is not available cleanly on other platforms. + +**Cost insights.** LinkedIn's CPM tends to be 3 to 10x higher than B2C platforms because of the audience precision premium. The justification is B2B LTV; lower-LTV offers cannot make LinkedIn math work. + +--- + +## TikTok + +**Default attribution.** 7-day click and 1-day view-through, similar to Meta. + +**Video-completion-based attribution.** TikTok counts conversions even when the user did not click but watched the full video. This is unique among the platforms covered here. The signal is real for awareness; it inflates direct-response numbers. + +**iOS impact, less mature modeling.** TikTok faces similar ATT-driven tracking gaps as Meta. The modeling is less mature, which means iOS-heavy audiences see more under-reporting on TikTok than on Meta. + +**Spark Ads attribution overlap.** Spark Ads boost organic posts. Engagement on the boosted version shows up in both organic and paid surfaces. Be careful not to double-count when reconciling against organic engagement reports. + +**Spark Ads vs paid creative differential.** Spark Ads consistently outperform pure paid creative on TikTok because they retain organic engagement signals. A team comparing CPMs of Spark vs paid will see Spark consistently lower; the difference is real, not a reporting artifact. + +**Trend-based volatility.** TikTok performance is more sensitive to trending sounds and formats than other platforms. Reporting comparisons across long time periods are less reliable because the platform itself shifted. + +--- + +## Programmatic and Display + +**Viewability gates.** Programmatic display sells impressions, but only "viewable" impressions count toward billed performance. The Media Rating Council (MRC) standard is 50% of pixels in view for 1 second (display) or 2 seconds (video). Below this threshold, the impression should not be billed. + +**Fraud filters.** Programmatic exposes fraud-detection metrics. Without fraud filtering, 10 to 30% of programmatic impressions are bot or fraudulent traffic. Use vendors like DoubleVerify or IAS for filtering. + +**Attribution decay.** Programmatic display's incremental rate is usually 5 to 20%. Most clicks come from users who would have converted from other channels anyway. Treat programmatic as awareness; do not optimize for direct response unless the incrementality test confirms it. + +--- + +## Cross-platform interference + +A specific quirk worth a dedicated callout. + +**The mechanism.** Two platforms claim the same conversion. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). The same revenue event shows up twice in the platform totals. + +**The detection.** Sum-of-platforms exceeds total conversions in the warehouse. If platform-reported sum is 1.5 to 3x the warehouse total, you have heavy cross-platform double-counting. + +**The defense.** Warehouse as canonical for board reporting. Platform reports for in-flight tuning of the platform's own levers. MMM at scale to estimate true cross-channel contribution. + +--- + +## Reporting differences in numbers + +A typical mid-stage account has the following attribution gap pattern across platforms. + +- Google Ads reports: 1.3 to 1.5x what GA4 reports for the "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA4 reports for the "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA4 for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA4 reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/dist/pi/.agents/skills/after-action-report/SKILL.md b/dist/pi/.agents/skills/after-action-report/SKILL.md new file mode 100644 index 0000000..d1690cc --- /dev/null +++ b/dist/pi/.agents/skills/after-action-report/SKILL.md @@ -0,0 +1,282 @@ +--- +name: after-action-report +description: "Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings." +category: operations +catalog_summary: "Post-mortems, retros, learnings documentation" +display_order: 3 +--- + +# After-Action Report + +Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document. + +This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`. + +--- + +## When to use + +- After any incident (any severity) +- After every major launch +- At the end of a project (sprint retro, quarterly retro, project closeout) +- When a recurring issue has happened enough times to demand investigation +- When a decision didn't work out and the team wants to learn + +## When NOT to use + +- During an active incident (use `incident-response`) +- For pre-launch planning (use `launch-runbook`) +- For one-off bug fixes that don't merit broad analysis + +--- + +## Required inputs + +- The event being analyzed (incident, launch, project) +- A timeline reconstructed from logs, chat, tickets +- Participant accounts of what they observed and did +- Outcomes and impact (what actually happened to users, the business) + +--- + +## The framework: blameless analysis + +The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones. + +### What blameless means + +- Focus on systems, not individuals +- Assume everyone made reasonable decisions given what they knew at the time +- The question is "why was this decision reasonable to make?" not "who screwed up?" +- Fixing the system means the next person in that situation succeeds where this person didn't + +### What blameless does not mean + +- No accountability (action items still have owners) +- No hard truths (sometimes the system is broken in obvious ways) +- No standards (some patterns of failure are individual, not systemic) +- No discomfort (real reflection is uncomfortable) + +--- + +## The framework: 6 sections + +A complete AAR covers six sections. + +### 1. Summary + +A 2 to 3 paragraph overview. Captures: + +- What happened +- Impact (users, business, time) +- Root cause (in plain language) +- Top action items + +This is what executives read. Anyone who reads only this section should leave with the most important information. + +### 2. Timeline + +A reconstructed timeline of events. + +For incidents: +- T-0: Detection +- T+X: Acknowledgment +- T+Y: Severity assessed, IC assigned +- T+Z: Investigation began +- ... mitigation, communication, resolution events +- T+N: Resolution declared + +For launches: +- Pre-launch decisions and milestones +- Launch day events +- Post-launch monitoring observations + +For projects: +- Major milestones, decisions, pivots +- Both planned and emergent + +The timeline is the source of truth. Disagreements about what happened get resolved here. + +### 3. Root cause analysis + +What caused this, in plain language. + +Use one or both of: + +**Five whys.** Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology. + +Example: +- Why did the site go down? Database connection pool exhausted. +- Why was the pool exhausted? Background job opened too many connections. +- Why did the background job open too many connections? Connection cleanup code didn't run on errors. +- Why didn't cleanup run on errors? Original code review didn't cover error paths. +- Why didn't the review cover error paths? No checklist for error handling in our review process. + +The fifth why often reveals the system fix. In this case: improve the review process. + +**Causal chain.** Multiple contributing factors that combined. + +- Factor 1: Background job opened too many connections (technical) +- Factor 2: Connection limit was set too low for actual traffic (configuration) +- Factor 3: No alert on connection pool saturation (monitoring) +- Factor 4: Recent traffic doubled without infra capacity review (process) + +No single fix addresses the incident. Multiple gaps need attention. + +### 4. Contributing factors + +Factors that didn't cause the event but made it worse, or removed safety nets that would have caught it. + +- Monitoring gaps +- Documentation gaps +- Process gaps +- Tooling gaps +- Knowledge gaps + +A "would have been caught earlier if..." factor. + +### 5. What went well + +Real lessons require capturing successes, not just failures. + +- What detection worked? +- What response worked? +- What decisions were good? +- What tools or processes performed as expected? + +This is not consolation. It's calibration. Things that worked here should be reinforced and replicated. + +### 6. Action items + +Specific, owned, dated. + +| Action | Owner | Due | Type | +|---|---|---|---| +| Add alert on connection pool saturation | [name] | [date] | Monitoring | +| Add error handling checklist to PR template | [name] | [date] | Process | +| Audit other background jobs for similar issue | [name] | [date] | Code | + +**Action item criteria:** + +- **Specific.** "Improve monitoring" is not actionable. "Add alert on connection pool saturation, threshold 80%, page on-call" is. +- **Owned.** A name. Not "the team." +- **Dated.** A real date. Not "soon." +- **Sized.** Roughly hours, days, or weeks of effort. +- **Closeable.** Definition of done is clear. + +Action items that don't close in their committed timeframe should re-surface in the next AAR. Patterns of unclosed actions point to deeper organizational issues. + +--- + +## Workflow + +### 1. Schedule the AAR + +Within 1 to 2 weeks of the event. Long enough that emotions cooled and facts gathered. Short enough that memories are fresh. + +For incidents: pre-decided in the response procedure. +For launches: schedule on the runbook. +For projects: schedule at project closeout. + +### 2. Gather inputs + +Before the meeting: + +- Reconstructed timeline (often the scribe's notes if there was one) +- Logs, chat transcripts, tickets, incident updates +- Individual accounts from each participant (written, before the meeting) +- Impact data (users affected, duration, revenue impact, etc.) + +### 3. Run the meeting + +Typical agenda (60 to 90 minutes): + +- Read the summary as drafted (5 min) +- Walk the timeline together. Add corrections. Resolve disagreements. (20 to 30 min) +- Discuss root cause. Use five whys or causal chain. (15 to 20 min) +- Discuss contributing factors. (10 min) +- Discuss what went well. (10 min) +- Identify action items. Owners and dates. (10 min) + +A facilitator runs the meeting. Often the IC for an incident, or a project lead for a project. The facilitator is not the scribe. + +### 4. Write the document + +Within a few days of the meeting. The full AAR includes all 6 sections. + +### 5. Distribute + +Internal: post in a known location. Make searchable. Reference in onboarding. + +For high-severity incidents: external summary may be appropriate (status page, customer email, public blog). + +### 6. Track action items + +Every action item should be tracked to closure. The next AAR re-surfaces unclosed ones. + +--- + +## Failure patterns + +- **Skipping the AAR for "small" incidents.** Patterns get missed. +- **Naming and shaming.** Real lessons get hidden when people fear blame. +- **Generic action items.** "Improve testing" instead of specific testing change. +- **Action items that never close.** Filed, forgotten. Same incident recurs. +- **Theater retrospectives.** Going through the motions without genuine reflection. +- **Skipping "what went well."** Misses calibration on what's working. +- **Blame externalized.** "Our vendor failed." OK, what's our system for vendor risk? +- **Single-person AAR.** One person writes the whole thing. Misses other perspectives. +- **AAR only for failures.** Successful launches deserve AARs too. Lessons from success are valuable. +- **Long delays.** Memories fade. Conversations cool. Get it done within 2 weeks. + +--- + +## Output format + +A markdown document at `aar-[date]-[event-name].md`. + +Structure: + +```markdown +# AAR: [Event name] + +**Date of event:** [YYYY-MM-DD] +**AAR date:** [YYYY-MM-DD] +**Severity / scope:** [SEV-1 / Major launch / Project closeout] +**Facilitator:** [Name] +**Participants:** [Names] + +## Summary +[2 to 3 paragraphs] + +## Impact +- Users affected: [number, segment] +- Duration: [time] +- Revenue / business impact: [if applicable] + +## Timeline +[Timestamped events] + +## Root cause analysis +[Five whys or causal chain] + +## Contributing factors +[List] + +## What went well +[List] + +## Action items +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| | | | | | + +## Lessons +[Reflections that don't fit elsewhere. Often the most quotable section.] +``` + +--- + +## Reference files + +- [`references/aar-template.md`](references/aar-template.md) - Fillable AAR template covering incidents, launches, and projects. diff --git a/dist/pi/.agents/skills/after-action-report/references/aar-template.md b/dist/pi/.agents/skills/after-action-report/references/aar-template.md new file mode 100644 index 0000000..0d37d24 --- /dev/null +++ b/dist/pi/.agents/skills/after-action-report/references/aar-template.md @@ -0,0 +1,296 @@ +# AAR Template + +Fillable after-action report template. Three variations: incident AAR, launch AAR, project closeout AAR. The structure is similar; the inputs and emphasis differ. + +--- + +## Universal sections (used in all three variations) + +### Header + +```markdown +# AAR: [Event name] + +**Type:** [Incident / Launch / Project] +**Date of event:** [YYYY-MM-DD or range] +**AAR date:** [YYYY-MM-DD] +**Severity / scope:** [SEV-1 / Major launch / Project closeout] +**Facilitator:** [Name] +**Participants:** [Names] +**Distribution:** [Internal only / Internal + customers / Public] +``` + +--- + +## Variation 1: Incident AAR + +### Summary + +> [2 to 3 paragraphs. What happened, what was the impact, what was the root cause, what are the top action items. Should stand alone for executives who read only this section.] + +### Impact + +- **Users affected:** [Number and segment. "All US users" or "Approximately 12% of paid customers in EU."] +- **Duration:** [Detection to resolution] +- **Severity:** [SEV-1 / 2 / 3 / 4] +- **Revenue impact:** [If quantifiable] +- **Customer-facing communication:** [What was said, when] +- **Regulatory implications:** [If any] + +### Timeline + +| Time | Event | Notes | +|---|---|---| +| T-X | [Pre-incident state, recent deploy, etc.] | | +| T-0 | [Detection event] | | +| T+5min | [Acknowledgment] | | +| T+10min | [Severity assessed, IC assigned] | | +| T+Xmin | [Investigation milestone] | | +| T+Ymin | [Mitigation applied] | | +| T+Zmin | [Verification] | | +| T+Nmin | [Resolution declared] | | +| T+Hours | [Customer comms, post-incident] | | + +Timeline source: [Logs, chat, monitoring, IC notes] + +### Detection + +- **How was it detected?** [Alert / customer report / internal observation] +- **Time to detection:** [From event start to detection] +- **Was detection adequate?** [Should we have detected this faster? How?] + +### Response + +- **Time to acknowledgment:** [Detection to acknowledgment] +- **Time to mitigation:** [Detection to mitigation] +- **Time to resolution:** [Detection to resolution] +- **Were the right people involved?** [Yes / No, why] +- **Did the response procedure work?** [Yes / No, what gaps] + +### Root cause analysis + +**Surface symptom:** [What users experienced] + +**Five whys:** + +1. Why did [symptom] happen? [Answer] +2. Why did [Answer 1] happen? [Answer] +3. Why did [Answer 2] happen? [Answer] +4. Why did [Answer 3] happen? [Answer] +5. Why did [Answer 4] happen? [Answer - often the system fix] + +**Or, causal chain (multiple contributing factors):** + +- Factor 1 (technical): [Description] +- Factor 2 (configuration): [Description] +- Factor 3 (process): [Description] +- Factor 4 (monitoring): [Description] + +### Contributing factors + +What didn't cause this but made it worse, or removed safety nets: + +- [Factor] +- [Factor] +- [Factor] + +### What went well + +- [Detection mechanism that worked] +- [Decision that was correct] +- [Tool that performed as designed] +- [Communication that was effective] + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | [Name] | [Date] | Monitoring | Open | +| [Specific action] | [Name] | [Date] | Code | Open | +| [Specific action] | [Name] | [Date] | Process | Open | +| [Specific action] | [Name] | [Date] | Documentation | Open | +| [Specific action] | [Name] | [Date] | Training | Open | + +### Lessons + +[Reflections beyond the action items. Often the most-quoted section in the long term.] + +--- + +## Variation 2: Launch AAR + +### Summary + +> [2 to 3 paragraphs. What launched, did it go well, what surprised us, what should we do differently next time.] + +### Outcomes + +- **What launched:** [Specific scope] +- **Launch window:** [Planned vs actual] +- **Maintenance time:** [If applicable] +- **Issues during launch:** [Count and severity] +- **Rollback?:** [Yes / No] +- **Post-launch incidents:** [In the first 7 days] +- **Business outcomes:** [If measurable, e.g., conversion impact] + +### Timeline + +| Time | Event | Notes | +|---|---|---| +| Pre-launch | [Major decisions, milestones] | | +| Launch start | | | +| Cutover steps | [Each step with timing] | | +| Verification | | | +| Public announcement | | | +| First 24 hours | [Notable observations] | | +| First week | [Notable observations] | | + +### What went according to plan + +- [Step that worked exactly as runbook described] +- [Communication that was clear] +- [Decision that proved correct] + +### What deviated from plan + +- [Deviation, why, what we did] +- [Deviation, why, what we did] + +### What surprised us + +- [Unexpected observation] +- [Unexpected user behavior] +- [Unexpected technical behavior] + +### What we'd do differently + +- [Change to runbook for next launch] +- [Change to pre-launch QA] +- [Change to communication plan] + +### What we'd repeat + +- [Practice that worked, want to keep] + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | | | | | + +### Lessons + +[Reflections.] + +--- + +## Variation 3: Project closeout AAR + +### Summary + +> [2 to 3 paragraphs. What we set out to do, what we delivered, what we learned, what comes next.] + +### Goals vs outcomes + +| Goal | Outcome | Notes | +|---|---|---| +| [Original goal 1] | [Met / Partially met / Not met] | [Notes] | +| [Original goal 2] | [Met / Partially met / Not met] | [Notes] | +| [Original goal 3] | [Met / Partially met / Not met] | [Notes] | + +### Timeline + +| Phase | Planned | Actual | Variance | +|---|---|---|---| +| Discovery | | | | +| Design | | | | +| Build | | | | +| QA | | | | +| Launch | | | | + +### What went well + +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] + +### What didn't go well + +- [Pain point with system-level explanation] +- [Pain point with system-level explanation] + +### What surprised us + +- [Surprising input from users / market / internal] +- [Surprising scale / complexity / opportunity] + +### What we'd do differently + +For people working on similar projects in the future: + +- [Specific change] +- [Specific change] +- [Specific change] + +### Decisions in retrospect + +| Decision | Was it right? | Why or why not | +|---|---|---| +| [Major decision 1] | | | +| [Major decision 2] | | | +| [Major decision 3] | | | + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | | | | | + +### Lessons + +[Reflections.] + +### Recommendations for next phase + +[If the project continues. Otherwise, recommendations for what builds on this work.] + +--- + +## Universal facilitator guide + +### Before the meeting (pre-work) + +- Send the timeline draft to all participants +- Ask each participant to write their personal account of what they observed and did (1 to 2 paragraphs each) +- Compile contributing data: logs, metrics, ticket counts, customer feedback +- Send participants the agenda 24 hours in advance + +### During the meeting + +- Set the tone in the first 60 seconds: "This is blameless. Focus on systems, not individuals." +- Walk the timeline. Add corrections from participants. +- For root cause: ask "why" until the answers stop being substantive. Note when it shifts from technical to process. +- For action items: insist on specificity, owner, date. +- Don't let the meeting become a debugging session. Investigation happened before; this is for analysis. +- Capture the document live where possible. Edits in real time prevent recall errors. + +### After the meeting + +- Polish the document within 48 hours +- Distribute to broader audience +- File action items into a tracking system +- Schedule follow-up to verify action items closed (typically 30 days out) + +--- + +## Common AAR anti-patterns + +| Anti-pattern | What it looks like | Better | +|---|---|---| +| Naming and shaming | "Sarah deployed the bug" | "Our review process didn't catch the issue. Why? What checklist or test would have?" | +| Generic actions | "Improve testing" | "Add a test for X scenario to the existing test suite by [date]" | +| No follow-through | Action items filed, never tracked | Action item review at next AAR; pattern of unclosed items surfaces | +| Skipping success | Only failures discussed | Equal time to what went well | +| Sole authorship | One person writes the AAR | Group discussion + sole author for polish | +| Long delay | AAR happens 2 months later | AAR within 2 weeks of event | +| Skipping minor incidents | "Not worth the time" | Patterns hide in the minors | diff --git a/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md b/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md new file mode 100644 index 0000000..d04119e --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md @@ -0,0 +1,281 @@ +--- +name: ai-content-collaboration +description: "How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy." +category: content +catalog_summary: "How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production" +display_order: 8 +--- + +# AI Content Collaboration + +A senior editorial leader's playbook for how humans and AI compose in content workflows. Pragmatic, tool-agnostic, honest about both what AI in the loop enables and what it threatens. + +Most content programs in 2026 use AI somewhere in the workflow. Pretending otherwise is dishonest; treating AI as a magic content factory is the failure mode this skill exists to prevent. The discipline is in between: knowing where AI legitimately accelerates, where humans must own, what hybrid patterns produce work that earns reader trust, and what crosses the line into AI slop or intellectual dishonesty. + +This skill is the WORKFLOW layer that composes with every other content skill. Briefs can be AI-assisted; hub architectures can be AI-assisted; programmatic SEO is almost always AI-involved; editorial QA now includes AI-content audit by necessity. The collaboration discipline applies to all production stages, not to a single artifact type. + +The voice is pragmatic and tool-agnostic deliberately. The methodology applies whether the AI in your loop is one of the major commercial models, an open-source model, or whatever ships next quarter. What stays constant is the workflow shape, the participation boundaries, the voice ownership question, and the ethical frame. What changes is which specific tool you reach for, which is implementation work that varies by team and budget. + +When to use this skill: building or refining an AI-content workflow, calibrating a team on consistent AI usage, addressing the "we use AI but our work feels generic" problem, designing disclosure policies, or working through the ethics of AI-assisted content production for a regulated or trust-sensitive context. + +--- + +## What this skill is for + +This skill spans the workflow layer of AI-assisted content production. It composes with all six other content-suite skills as the cross-cutting discipline. + +- `content-strategy` is program scope: what to produce. Strategy decisions can be AI-assisted; the program-level judgment stays human. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. Hub architecture can be AI-suggested; the architectural commitment stays human. +- `content-brief-authoring` is per-piece scope: briefs each piece. Briefs can be AI-drafted from research; the contract decisions stay human. +- `content-and-copy` is execution scope: writes each piece. Drafts can be AI-produced; voice and editorial judgment stay human. +- `programmatic-seo` is scaled scope: generates pages from data. AI generation is the dominant production model; sampling QA is the human gate. +- `editorial-qa` is gate scope: verifies before publish. AI-content audit is now a load-bearing gate; the audit's judgment stays human. +- This skill is workflow scope: how the human and AI layers compose across all six stages above. + +The audience: editorial leaders, content directors, content ops managers, agencies running AI-assisted production, in-house teams calibrating AI usage across writers. The voice is senior editorial leader to junior editor or content marketer. Pragmatic, honest, tool-agnostic. + +What is not in scope: specific prompts (those are implementation; teams develop their own), specific tool endorsements (the methodology applies regardless of which tool is in the loop), specific integration code (varies by stack and team). Tool categories appear when they earn methodology relevance; specific tools appear only as illustrations of categories, never as recommendations. + +--- + +## Humans own, AI accelerates + +The keystone framing. + +The pathology to avoid is treating AI as either a magic content factory (cheap, fast, scaled, output quality optional) OR as a forbidden intruder (purity gospel that does not survive contact with deadlines). Both readings produce bad work. + +The discipline that produces durable work: humans own the content; AI accelerates the work. Specifically: + +**Humans own.** Editorial judgment, voice, distinctive POV, fact accuracy, ethical decisions, what to publish versus what to kill, brand voice, narrative arc, tone calibration, reader empathy, claim verification. + +**AI accelerates.** Research synthesis, draft generation against a brief, copy edit suggestions, alternative phrasings, summary, transcription, quality-control automation at scale. + +The line. AI does work that the human directs and verifies. AI does NOT make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +The litmus test. If your AI-assisted piece publishes without a human being able to defend every claim, every position, and every word, you have crossed the line. The piece is AI's work, dressed in your byline. Readers eventually notice. + +--- + +## Where AI legitimately participates + +A non-exhaustive list of stages where AI in the loop is fine and often improves the work. + +- **Research synthesis.** AI condenses long-form sources into briefs the writer reads. Saves hours; the writer still reads and verifies. +- **Outline generation against a brief.** AI proposes an H2 / H3 structure from a brief; the editor approves or restructures. +- **First-draft generation.** AI produces a draft against an explicit brief; the human edits substantially. +- **Alternative phrasings.** AI offers 3 versions of a sentence; the human picks one or rewrites. +- **Copy edit suggestions.** AI catches typos, awkward phrasings, repetition. +- **Summary and abstraction.** AI condenses long pieces into TL;DRs. +- **Transcription.** AI transcribes interview audio; the human verifies. +- **Translation drafts.** AI produces a translation draft; a native speaker reviews and corrects. +- **Quality-control automation at scale.** AI flags pages in a programmatic SEO set that need human review. +- **Idea generation.** AI proposes 30 angles; the human picks 3. + +In each case, AI accelerates work the human still owns. The acceleration is real; the ownership stays unchanged. + +Detail in [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md). + +--- + +## Where humans must own + +The boundary list. + +- **Editorial judgment.** What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. +- **Voice.** Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution. +- **Fact verification.** Every claim, every statistic, every quote, every named person. AI hallucinates; humans verify. +- **Ethical decisions.** What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. +- **Reader empathy.** What the reader actually needs from this piece, not what the algorithm scores well. +- **Quote attribution.** Real people who actually said the thing, with consent where relevant. +- **Tone calibration on hard topics.** Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. +- **Narrative arc.** How the piece unfolds, where the reader's attention goes. AI produces shapes; humans choose them. +- **Final approval.** The human who signs off is accountable for what shipped. + +The "human in the loop" framing is necessary but insufficient. A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. Ownership requires the human to have made the actual decisions the piece embodies. + +--- + +## Hybrid workflow patterns + +Five patterns that work, with tradeoffs. + +**1. AI-first draft, human-edit-heavy.** AI produces a 90% draft; the human spends 60% of the time editing. Output: efficient for high-volume editorial; risks generic voice if editing is light. + +**2. Human-first outline + research, AI-draft, human-rewrite.** Human builds the outline and gathers research; AI drafts within that scaffold; human rewrites in voice. Output: preserves voice better; slower than AI-first. + +**3. AI-as-research-assistant, human-writes.** AI condenses sources into a brief; human writes the entire piece from the brief. Output: highest voice fidelity; slowest. + +**4. Human-writes, AI-as-editor.** Human drafts; AI suggests edits, alternative phrasings, copy edits; human accepts or rejects. Output: writer voice preserved; AI catches details. + +**5. AI-generates-at-scale, human-samples.** For programmatic SEO. AI generates thousands of pages; human samples 50 to 200 with editorial-qa discipline. Output: scaled production; depends entirely on template quality and sampling discipline. + +The pattern that fits depends on volume, voice sensitivity, team skill, and time budget. No pattern is "the right one"; pattern selection is a real decision that should match the production context. + +Detail in [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md). + +--- + +## Voice ownership preservation + +Voice is the dominant casualty of careless AI workflows. The patterns that preserve voice. + +- **Voice guidelines as prompt input.** Every AI generation includes the brand voice guidelines as context. Generic AI defaults regress without this. +- **Sample text as voice anchor.** Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. +- **Mid-draft voice check.** At the halfway mark of a long piece, have a human or a separate AI pass read for voice drift. Long AI generations regress halfway through almost always. +- **Final pass in human voice.** The human edits the closing sections in their own voice; this is where the piece's emotional register often lands. +- **Reject the bland.** Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The honest framing. Voice is the hardest thing to preserve in AI-assisted work and the easiest thing to lose. Programs that do not actively preserve voice end up with content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +Detail in [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md). + +--- + +## The AI slop problem + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. Cross-reference `editorial-qa`'s ai-content-audit-patterns reference for the detection patterns; this section addresses prevention. + +**Patterns that produce slop.** + +- AI does too much of the work (no real human direction or rewriting) +- Generic prompts (no brand voice context, no audience specificity, no anti-pattern guidance) +- No editorial judgment in the loop (AI generates, human glances, ship) +- Volume prioritized over quality (10x more pages can mean 10x more slop, not 10x more value) +- No iteration (first draft ships; no rewrite for voice) + +**Patterns that prevent slop.** + +- Strong briefs (per `content-brief-authoring`) +- Voice guidelines as prompt context +- Heavy human editing pass +- Iteration: AI draft, then human rewrite, then AI suggestions, then human final +- Editorial judgment at every gate + +The reader-detection problem. Readers can often sense AI-flavored content even when they cannot articulate why. Generic openings, predictable structures, "perfect" grammar that is emotionally flat. Slop loses reader trust over time even when individual pieces are not penalized. + +Detail in [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) and cross-reference editorial-qa's audit patterns. + +--- + +## Disclosure and transparency + +When should AI usage be disclosed to readers? + +The tiered framework. + +- **Always disclose.** Journalism, news reporting, attributed expert opinion, content where AI tools are the subject. +- **Default disclosure (consider context).** Thought leadership where the byline is doing trust work, regulated industries, content that influences purchase decisions. +- **Generally not necessary.** Marketing copy, descriptive product content, programmatic data pages, copy edit assistance only. +- **Clearly fine without disclosure.** AI as research assistant only; AI for transcription; AI for spelling and grammar suggestions. + +The principle. Disclose when the reader's understanding of the content's origin would change their trust in it. A bylined opinion piece purportedly by a named expert that is substantially AI-drafted is a trust violation; a product description on an ecommerce site that was AI-drafted is not. + +**Disclosure language patterns (when used).** + +- "AI tools assisted in research and drafting; the author edited and verified all claims." +- "This piece was generated programmatically from [data source]; reviewed by [team] before publish." +- Avoid hedging language like "may have used AI" or "could have been AI-assisted"; be specific or omit. + +Industry-specific norms vary. Major journalism organizations have published explicit AI usage standards. Content marketing has weaker norms but is moving toward disclosure for high-trust pieces. + +Detail in [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md). + +--- + +## Team training and calibration + +Inconsistent AI usage across a team produces inconsistent output. The discipline. + +- **Documented AI policy.** Which uses are approved, which require explicit permission, which are prohibited. +- **Calibration sessions.** Editors review AI-assisted pieces from multiple writers, surface differences, agree on standards. +- **Voice library updates.** As voice evolves, the prompts and sample text fed to AI evolve with it. +- **Quality benchmarks.** What does "AI-assisted but on-voice" look like for your brand? Document it with examples. +- **Tool standardization or intentional pluralism.** Team uses one tool consistently OR documents which tools fit which tasks. +- **Forbidden patterns list.** This team does not use AI for X (whatever X is for your context). +- **Onboarding.** New writers learn the AI policy and calibration in their first 2 weeks. + +The pathology. AI usage emerges informally, every writer develops their own patterns, output drifts, editors cannot pinpoint why pieces feel off. The discipline is making AI usage explicit, calibrated, and documented. + +Detail in [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md). + +--- + +## Ethics: training data, attribution, intellectual honesty + +AI tools were trained on copyrighted material. That is the simple ethical reality of every major LLM in 2026. The catalog's position on this question is not "AI use is unethical" (that would render the catalog itself hypocritical) but "intellectual honesty about AI involvement is non-negotiable." + +The principles. + +- **Do not pass AI work as fully human-written.** Bylined content where the byline implies human craft requires substantial human craft. +- **Do not claim AI did not help when it did.** False denials are worse than disclosure. +- **Do not generate content that closely mirrors copyrighted source material.** AI tools can produce near-replicas of training data when prompted carelessly; humans verify originality. +- **Attribute when borrowing.** Ideas, frameworks, statistics that came from specific sources get cited. +- **Do not fabricate quotes or expertise.** Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. +- **Be honest about AI capabilities and limits.** Do not oversell AI as more capable than it is. + +The intellectual-honesty frame supersedes any specific policy debate. Teams that treat AI usage with intellectual honesty produce content readers can trust over time. Teams that hide, deny, or rationalize lose trust eventually. + +Detail in [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md). + +- "We used AI and the content feels generic." Voice not preserved; not enough human rewriting. +- "Hallucinated facts made it to publish." Fact-verification gate skipped or rushed. +- "Different writers produce wildly different AI-assisted output." No team calibration. +- "Our AI-assisted SEO content got penalized." Slop volume plus thin templates plus no QA discipline. +- "We cannot tell what was AI versus human." No AI usage tracking; teams should document at the workflow level. +- "Readers complained about AI-flavored content." Slop reaching audience; intensify human craft pass. +- "We disclosed AI usage and lost credibility." Depends on context; disclosure is sometimes a trust gain, sometimes a loss; calibrate to audience norms. +- "Our AI tools changed and our content shifted." Over-coupled to one tool's specific behavior; methodology should be tool-agnostic. +- "We are producing 10x more content but the same audience growth." Volume was not the constraint that was binding; quality was. +- "The team is using AI inconsistently." Calibration sessions overdue. +- "An expert byline turned out to be substantially AI-drafted." Ethics breach; correct, disclose, recalibrate. + +--- + +## The framework: 12 considerations for AI content collaboration + +When designing or auditing an AI-assisted content workflow, walk these 12 considerations. + +1. **Humans own; AI accelerates.** Make this explicit in your workflow, not implicit. +2. **Participation boundaries.** Document where AI legitimately helps, where humans must own. +3. **Hybrid pattern selection.** Match the pattern to volume, voice sensitivity, time budget. +4. **Voice guidelines as prompt input.** Every AI generation includes brand voice context. +5. **Voice drift sampling.** Long pieces drift mid-way; sample throughout. +6. **Fact verification gate.** Every claim, every quote, every stat verified before publish. +7. **AI slop prevention.** Heavy human editing, strong briefs, iteration. +8. **Disclosure tiering.** Disclose when origin would change reader trust; calibrate to audience. +9. **Team calibration.** Documented policy, calibration sessions, voice library. +10. **Tool-agnostic methodology.** Workflow shape stays constant as tools change. +11. **Ethical floor.** Intellectual honesty, no fabrication, no hidden AI in trust-sensitive work. +12. **Final accountability.** The human who signs off is accountable; AI does not sign off. + +The output of the framework is a workflow document the team can reference: AI participation rules named, hybrid pattern selected, voice preservation patterns specified, disclosure tier set, calibration cadence committed, ethical floor articulated, accountable signer named for each piece. + +--- + +## Reference files + +- [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md) - Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. +- [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md) - Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. +- [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md) - Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. +- [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) - What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. +- [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md) - Tiered disclosure framework, language patterns, industry norms. +- [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md) - Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. +- [`references/quality-calibration-with-ai-in-loop.md`](references/quality-calibration-with-ai-in-loop.md) - How editorial standards shift when AI is in the workflow. Same standards, different failure modes. +- [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md) - Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. +- [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: collaboration, not replacement + +AI in content workflows is neither magic nor menace. It is a category of tooling that, like every tooling category before it, rewards disciplined use and punishes careless use. The teams producing memorable AI-assisted content are the ones holding the line on human ownership, voice, fact accuracy, and intellectual honesty. The teams producing AI slop are the ones treating AI as a content factory. + +The discipline is not anti-AI; it is pro-craft. Craft was always what made content worth reading; AI does not change that, it just raises the cost of skipping it. + +When in doubt about whether an AI-assisted workflow is ready, ask: is human ownership specified, are participation boundaries documented, is voice preservation built into the prompt and review patterns, is fact verification a halt-condition, is disclosure tiered to audience trust, is the team calibrated, and is the ethical floor explicit? If yes to all of those, the workflow is ready. If no to any, the gap is where the program will produce slop and lose reader trust. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md new file mode 100644 index 0000000..0d6b20a --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md @@ -0,0 +1,131 @@ +# AI participation boundaries + +Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. + +The boundary list below is the operational expression of the keystone framing: humans own the content, AI accelerates the work. The list is not exhaustive; the principle is: AI does work the human directs and verifies, AI does not make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +--- + +## Where AI legitimately participates + +### Research synthesis + +AI condenses long-form sources (papers, interviews, prior reports, internal docs) into a research brief. The writer reads the brief, follows up on the citations the brief surfaced, and verifies anything that will become a load-bearing claim in the piece. + +The acceleration: hours of reading become minutes of reviewing. The retained ownership: the writer judges what is worth using, where the source is questionable, what additional research is needed. + +### Outline generation against a brief + +AI proposes an H2 / H3 structure based on the content brief and SERP analysis. The editor approves the outline, restructures it, or rejects it. + +The acceleration: the writer starts from a structure that fits the brief instead of from a blank page. The retained ownership: the editor decides whether the structure fits the audience and the publication. + +### First-draft generation + +AI produces a draft against an explicit brief. The human edits substantially. + +The acceleration: a 1,500-word draft in minutes that the human revises rather than composing from scratch. The retained ownership: the human chooses what to keep, what to rewrite, what to cut, what to add. A draft that ships unchanged is not collaboration; it is rubber-stamping. + +### Alternative phrasings + +AI offers 3 versions of a sentence, paragraph, or headline. The human picks one or rewrites. + +The acceleration: faster surfacing of options the writer might not have considered. The retained ownership: the writer chooses the option that fits the voice and the context. + +### Copy edit suggestions + +AI catches typos, awkward phrasings, repetition, weak connections between paragraphs. + +The acceleration: faster than a manual copy edit pass. The retained ownership: the editor decides which suggestions to accept; some of what AI flags as awkward is actually deliberate stylistic choice. + +### Summary and abstraction + +AI condenses long pieces into TL;DR summaries, executive summaries, or social media captions. + +The acceleration: faster TL;DR generation; useful for content systems that produce summaries at scale. The retained ownership: the human verifies the summary captures what matters and does not flatten the piece's distinctive points. + +### Transcription + +AI transcribes interview audio. The human verifies the transcription against the audio for accuracy, especially on names, technical terms, and quoted positions. + +The acceleration: hours of transcription become minutes of verification. The retained ownership: the human is responsible for what gets attributed; transcription errors that misquote sources are the human's accountability to catch. + +### Translation drafts + +AI produces a translation draft. A native speaker reviews and corrects. + +The acceleration: a translation starting point in seconds. The retained ownership: the native speaker is the source of truth on idiomatic correctness, cultural context, and brand-voice translation. + +### Quality-control automation at scale + +AI flags pages in a programmatic SEO set that need human review (per `editorial-qa`'s sampling discipline). + +The acceleration: automated check on every page; manual review focused on the flagged subset. The retained ownership: the editor decides what counts as a fail; the AI flags candidates, the human judges. + +### Idea generation + +AI proposes 30 angles on a topic; the human picks 3. + +The acceleration: faster brainstorm. The retained ownership: the human chooses which angles fit the brand and the audience. + +--- + +## Where humans must own + +### Editorial judgment + +What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. The judgment requires audience knowledge, brand context, and quality standards the AI does not have. + +### Voice + +Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution that the AI can mimic if shown samples but cannot originate. + +### Fact verification + +Every claim, every statistic, every quote, every named person. AI hallucinates plausible-but-fake claims; humans verify against authoritative sources. Fact verification is a halt-condition gate; pieces with unverified claims do not ship. + +### Ethical decisions + +What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. Ethics requires context, audience awareness, and accountability that the AI does not carry. + +### Reader empathy + +What the reader actually needs from this piece, not what the algorithm scores well. The reader's situation, knowledge, and emotional context shape the piece's job; the AI cannot model the specific reader the way a writer who has spent time with the audience can. + +### Quote attribution + +Real people who actually said the thing, with consent where relevant. AI hallucinates quotes; humans verify against the source. + +### Tone calibration on hard topics + +Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. A piece on bereavement should not read as if a chatbot wrote it. + +### Narrative arc + +How the piece unfolds, where the reader's attention goes, what the climax is, what the resolution is. AI produces shapes; humans choose them. + +### Final approval + +The human who signs off is accountable for what shipped. Accountability cannot be delegated to AI; the byline and the editorial chain stop at humans. + +--- + +## "Human in the loop" is not ownership + +The phrase "human in the loop" appears in many AI workflows. It is necessary but insufficient. + +A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. The piece's substance, voice, and judgment are still AI-produced; the human's role is signature only. + +Ownership requires the human to have made the actual decisions the piece embodies. Specifically: the human chose the angle, the human verified the facts, the human enforced the voice, the human made the editorial judgment calls that distinguish this piece from the AI's default output. + +The test. Could the human defend every claim, every position, and every word in the piece? If yes, the human owns it. If no, the human is rubber-stamping. + +--- + +## Methodology-level choices that stay in the public skill + +The list of where AI legitimately participates, the list of where humans must own, the "human-in-the-loop versus ownership" distinction, the verification-and-defense litmus test. + +## Implementation choices that stay internal + +The specific AI tools the team uses for each participation category (research synthesis tool, drafting tool, copy edit tool, transcription tool, translation tool, QC automation tool). The specific prompts the team has developed for each task category. The specific tracking system that records which AI participated in which piece. The specific review workflows that gate publish. These vary by team and stack. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md new file mode 100644 index 0000000..4e3df19 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md @@ -0,0 +1,134 @@ +# AI slop detection and avoidance + +What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. The detection patterns live in `editorial-qa/references/ai-content-audit-patterns.md`. This reference addresses prevention: what production patterns produce slop, what production patterns prevent it. + +--- + +## Patterns that produce slop + +### AI does too much of the work + +The pattern. The AI generates the entire piece; the human glances at it and ships. The piece reads as model-default because no human substantively rewrote it. + +The signal. Pieces ship in less time than they would take a human to write from scratch. Speed is not the problem; the problem is that the speed comes from skipped craft. + +### Generic prompts + +The pattern. The prompt is "write a 1,500-word blog post about X." No brand voice, no audience specificity, no anti-pattern guidance. The AI generates the most common kind of post about X, which is by definition generic. + +The signal. Prompts can fit in one sentence. Prompts that produce on-voice output are typically multi-paragraph, with voice guidelines, sample text, audience description, and anti-pattern lists. + +### No editorial judgment in the loop + +The pattern. The workflow is "AI generates, human reviews quickly, ship." The reviewer is not making editorial decisions; they are spell-checking. Whether the piece is good enough to publish, whether it answers the user's actual question, whether it reflects brand POV are not asked. + +The signal. The team cannot articulate the editorial judgments made on a piece because those judgments did not happen. Pieces ship with no halt-decisions, no rewrites, no "this piece does not work, kill it" calls. + +### Volume prioritized over quality + +The pattern. The team commits to publishing 50 pieces a month with the same headcount that previously produced 10. AI is the multiplier. Quality drops because the production line cannot sustain craft at the new volume. + +The signal. Publish targets defined in pieces-per-week or pages-per-month. Quality-controlled publish targets are defined differently: traffic earned, citations earned, leads converted, audience grown. Volume targets without quality targets produce slop volume. + +### No iteration + +The pattern. First draft (AI-generated) ships. No revision pass. No second draft. No "let us read this aloud and rewrite the bland sections." + +The signal. The workflow document does not include a rewrite step. Production is generation-then-publish, not generation-then-iteration-then-publish. + +--- + +## Patterns that prevent slop + +### Strong briefs + +Per `content-brief-authoring`. A brief that fills all 12 fields gives the AI enough context to produce a draft that respects audience, voice, structure, entity coverage, and success criteria. Vague briefs produce slop output regardless of how the AI is prompted. + +The discipline. Brief-adherence is the first QA gate per `editorial-qa`. AI drafts that fail brief-adherence get returned, not rubber-stamped. + +### Voice guidelines as prompt context + +Per `voice-ownership-preservation.md`. Every AI generation includes the brand voice guidelines and sample anchor text as prompt input. Without active voice prompting, AI defaults dominate. + +### Heavy human editing pass + +The discipline. The human spends substantial time editing AI drafts: rewriting flat sentences, replacing abstractions with specifics, restoring brand voice in mid-piece sections, replacing generic openings and closings with specific ones. + +The time investment. 50 to 60% of the piece's production time goes to human editing in Pattern 1 (AI-first draft, human-edit-heavy). Lower than that and the editing is light; the piece ships with AI defaults preserved. + +### Iteration + +The discipline. The workflow includes multiple revision passes: AI draft, then human rewrite, then AI suggestions for the rewrite, then human final pass. Each pass catches a different layer. + +- AI draft: structure, completeness, basic prose. +- Human rewrite: voice, specificity, claim verification, distinctive POV. +- AI suggestions: copy edit catches, alternative phrasings, repetition flagging. +- Human final: closing voice, emotional register, final polish. + +The pattern produces work that reads as human-crafted with AI assistance. Skip any pass and the piece moves toward AI default. + +### Editorial judgment at every gate + +The discipline. Each QA gate is a judgment moment, not a rubber stamp. Brief-adherence asks "did this piece execute the brief?" Voice consistency asks "does this sound like our brand?" Fact accuracy asks "is every claim verified?" Each question requires a human's actual judgment. + +The signal of editorial judgment in action. Halts happen. Pieces get sent back for revision. Some pieces get killed because they cannot be made to work. Programs that publish 100% of what they draft are not exercising editorial judgment; they are producing whatever the workflow ships. + +--- + +## The reader-detection problem + +Readers can often sense AI-flavored content even when they cannot articulate why. The signals. + +- Generic openings that could be the opening of any article on the topic +- Predictable structure (intro, three points, conclusion) +- Bullet-list overuse where prose would serve +- "Perfect" grammar that reads as emotionally flat +- Specific-but-fake details (named decimals, named sources that turn out to be fake) +- Hedge stacking that avoids commitment + +Slop loses reader trust over time even when individual pieces are not penalized by algorithm updates. Readers stop returning. Email open rates drop. Citation quality declines. The traffic numbers may hold for a year before the trust loss compounds visibly. + +The implication. Slop is not a search-engine problem; it is a reader-trust problem. Programs that optimize away from slop because of algorithm fear are missing the bigger reason: readers stop trusting the brand. + +--- + +## The slop avoidance audit + +For each AI-assisted piece, ask the following before publish. + +1. Could this piece have been published by any competitor using the same tools? If yes, the voice is not preserved. +2. Are the claims in this piece specific enough to verify? If no, the piece is hedging. +3. Does the piece take a position the reader will remember? If no, the piece is forgettable. +4. Did the human substantially rewrite, or is the AI draft mostly intact? If mostly intact, the piece is at slop risk. +5. Does the closing read as the writer's own voice? If no, the final pass was skipped. +6. Did the brief adhere to the 12-field discipline? If no, the failure is upstream. + +A piece that fails 3+ of these is slop-shaped. Halt and revise. + +--- + +## The "we are producing 10x more content but the same audience growth" pattern + +A common signal that slop has set in. The volume increased; the audience metric did not. The team often interprets this as "we need even more content"; the diagnosis is usually the opposite. + +The actual diagnosis. Volume was not the constraint. Quality was. The 10x content production has produced 10x slop, which earns less per piece and sometimes hurts the brand's overall trust signal. + +The fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## Cross-reference + +The detection patterns (AI tells, hallucination patterns, voice drift) live in `editorial-qa/references/ai-content-audit-patterns.md`. The avoidance patterns (production discipline) live here. The two skills compose: editorial-qa catches what reaches the gate; this skill prevents production patterns that produce slop in the first place. + +--- + +## Methodology-level choices that stay in the public skill + +The patterns that produce slop, the patterns that prevent slop, the reader-detection observation, the 6-question slop avoidance audit, the volume-vs-quality counter-intuition, the cross-reference to editorial-qa. + +## Implementation choices that stay internal + +The specific iteration loop the team runs (AI draft to human rewrite to AI suggestions to human final, or variations). The specific time-tracking that captures the editing-time-to-generation-time ratio. The specific prompt patterns that include voice guidelines and sample text. The specific reader-feedback channels that surface slop perception. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md b/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md new file mode 100644 index 0000000..cfabbca --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md @@ -0,0 +1,165 @@ +# Common collaboration failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: the team treated AI as either a magic content factory (producing slop at scale) or as a pure-replacement-or-nothing question (producing inconsistent output as writers privately negotiated their own AI usage). The discipline is in between: humans own, AI accelerates, the workflow is documented, the team is calibrated. + +--- + +## "We used AI and the content feels generic" + +**Symptom.** Pieces ship technically clean but feel indistinguishable from competitors using the same tools. Audience growth flat despite consistent publishing. + +**Diagnosis.** Voice not preserved. Editing was light; AI defaults reached publish. The pattern that produces this: AI-first drafts with a quick review pass that catches typos but does not rewrite for voice. + +**Fix.** Apply the voice ownership preservation patterns (`voice-ownership-preservation.md`): voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland audit. Increase editing intensity to 50-60% of production time. + +--- + +## "Hallucinated facts made it to publish" + +**Symptom.** A statistic, quote, citation, or product claim in a published piece turns out to be invented. + +**Diagnosis.** Fact-verification gate skipped or rushed. The team trusted AI output that read as authoritative. + +**Fix.** Fact-accuracy as halt-condition gate per `editorial-qa/references/fact-accuracy-and-citation-discipline.md`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +--- + +## "Different writers produce wildly different AI-assisted output" + +**Symptom.** Two writers given the same brief and the same AI tools produce pieces that read as if they came from two different programs. + +**Diagnosis.** No team calibration. Each writer developed their own AI patterns; the program drifted as different patterns produced different output shapes. + +**Fix.** Documented AI policy, calibration sessions, voice library, quality benchmarks per `team-training-and-calibration.md`. Onboarding for new writers includes calibration. + +--- + +## "Our AI-assisted SEO content got penalized" + +**Symptom.** A programmatic SEO set or a high-volume editorial program loses 60-90% of traffic in an algorithm update. + +**Diagnosis.** Slop volume plus thin templates plus no QA discipline. The set was generating filler pages with limited human direction; the algorithm update detected the scale-without-substance pattern. + +**Fix.** Halt new generation. Apply QA at scale per `editorial-qa/references/qa-at-scale-patterns.md`. Sampling discipline with 5% failure threshold. Noindex pages that fail the data-depth threshold. Possibly remove the entire pSEO surface and rebuild from a stronger data source. + +--- + +## "We can't tell what was AI vs human" + +**Symptom.** Asked to characterize AI usage on a specific piece, the team cannot answer. Workflow logs, CMS metadata, and writer recall all yield uncertain answers. + +**Diagnosis.** No AI usage tracking. The workflow does not capture which AI participated in which stage. + +**Fix.** Add AI involvement tracking to the production workflow. The metadata captures: which workflow pattern was used, which AI tools were involved, which stages, which prompts (or prompt template versions), which human made which decisions. The tracking is the input to retrospective audits and to disclosure decisions. + +--- + +## "Readers complained about AI-flavored content" + +**Symptom.** Direct audience feedback (comments, support tickets, social mentions) flags content as feeling AI-generated. + +**Diagnosis.** Slop reaching the audience. Reader detection is real even when the team's QA does not catch it. + +**Fix.** Intensify the human craft pass. Audit recent pieces against the slop avoidance audit (`ai-slop-detection-and-avoidance.md`). If multiple pieces fail the audit, the production patterns need to shift: heavier human editing, more rejection-of-bland, possibly pattern shift from AI-first to AI-as-editor for higher-trust content. + +--- + +## "We disclosed AI usage and lost credibility" + +**Symptom.** Team added AI disclosure to a piece; audience response shifted negative. + +**Diagnosis.** Could be either: + +- The disclosure was for content where audience norms expect human authorship (Tier 1 or Tier 2 content per the disclosure framework); disclosure was correct but audience trust calibration is moving slowly +- The disclosure language was hedging or defensive, signaling lower commitment than direct authorship would have +- The disclosure was for content where it was unnecessary (Tier 4); the disclosure created an issue where there was none + +**Fix.** Calibrate disclosure to audience norms per `disclosure-and-transparency-patterns.md`. Specific language matters; defensive language reads worse than no disclosure. Consider audience-research feedback to inform per-content-type disclosure tiering. + +--- + +## "Our AI tools changed and our content shifted" + +**Symptom.** Team updates the AI tool or model version. Output behavior changes. Content quality shifts before the team recalibrates. + +**Diagnosis.** Over-coupled to one tool's specific behavior. The methodology should be tool-agnostic; the team's prompts and patterns should produce similar output across tools. + +**Fix.** Methodology-first calibration. The voice library, prompt templates, and quality benchmarks should be portable across tools. After tool changes, run a calibration session against the new tool to verify the methodology still produces on-voice output. If the methodology no longer works, that is a signal the methodology was over-coupled to tool-specific behavior. + +--- + +## "We're producing 10x more content but the same audience growth" + +**Symptom.** Team committed to a 10x content target enabled by AI. Volume hit the target. Audience growth flat or declining. + +**Diagnosis.** Volume was not the constraint that was binding. Quality was. The 10x volume produced 10x slop, which earns less per piece. + +**Fix.** Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## "The team is using AI inconsistently" + +**Symptom.** Team members use different AI tools in different patterns for the same kind of work. Output varies by who picked up the assignment. + +**Diagnosis.** Calibration sessions overdue. Either the policy is informal (no documented standards) or the documented policy has not been reinforced through calibration. + +**Fix.** Quarterly calibration sessions. Tool standardization (or intentional pluralism with documented selection criteria). Onboarding refresh. The cadence is calendar-anchored. + +--- + +## "An expert byline turned out to be substantially AI-drafted" + +**Symptom.** A piece bylined by a named expert is publicly identified as substantially AI-drafted (sometimes by AI-detection tools, sometimes by readers familiar with the expert's actual voice). + +**Diagnosis.** Ethics breach. The byline implied human authorship; AI authorship was substantive; the gap between claim and reality reached the audience. + +**Fix.** Two parts. + +- **Immediate.** Correct the published piece (issue an editor's note clarifying the workflow, possibly retract and republish with appropriate disclosure). Apologize where appropriate. Recalibrate. +- **Process.** Restore the ethical floor: bylined expert content requires substantial human authorship. Recalibrate the team. Update the AI policy to document the floor explicitly. + +The fix is not "stop using AI." The fix is using AI consistently with the byline's implied authorship. + +--- + +## "Our AI policy is 18 months stale and references tools we no longer use" + +**Symptom.** Team consults the AI policy doc; the doc references tools the team migrated away from a year ago. The doc is treated as not authoritative because it is obviously dated. + +**Diagnosis.** Policy review cadence has slipped. The doc has not been updated as tools, capabilities, and team practices have evolved. + +**Fix.** Quarterly policy review. Each quarter the policy gets reviewed against current practice; updates ship; the team is briefed on the changes. The policy is a living document; staleness signals process failure. + +--- + +## "The team feels guilty about AI use but uses it anyway" + +**Symptom.** Team members use AI substantively but do not document, do not discuss in calibration sessions, do not include in retrospectives. AI usage is treated as something to hide. + +**Diagnosis.** The team has not articulated its AI ethics. Without articulation, individual writers privately negotiate their own ethics; the team accumulates ethical debt. + +**Fix.** Run an ethics conversation explicitly. Articulate the team's position on the six ethical floors per `ethics-and-intellectual-honesty.md`. Document where AI is used substantively. Make the workflow visible. Guilt is usually a signal of unresolved ethical questions; the resolution is articulation, not avoidance. + +--- + +## The pattern across all failures + +Most AI-collaboration failures reduce to two patterns. + +1. **The team treated AI as a magic content factory.** Outcome: slop, hallucinations, voice loss, audience trust decline. +2. **The team failed to articulate its AI workflow explicitly.** Outcome: drift, inconsistency, ethics debt, calibration failures. + +The fix in both cases is the same: explicit articulation of where AI participates, where humans own, what the discipline looks like in practice, and what the team's ethical floors are. The articulation is the work; once the work is done, individual failures become per-piece corrections rather than program-level breakdowns. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the cross-references to other reference files, the underlying-pattern observation about magic-factory thinking and unarticulated workflows. + +## Implementation choices that stay internal + +The specific tracking system the team uses for AI usage. The specific calibration session cadence. The specific ethics-policy doc and its review process. The specific tool selections and their rationale. These vary per team and brand. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md b/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md new file mode 100644 index 0000000..454370a --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md @@ -0,0 +1,170 @@ +# Disclosure and transparency patterns + +Tiered disclosure framework, language patterns, industry norms. + +When should AI usage be disclosed to readers? The answer is not "always" or "never"; it is "calibrate to context." The framework below tiers disclosure decisions by trust sensitivity. + +--- + +## The tiered framework + +Four tiers, ordered by disclosure obligation. + +### Tier 1: Always disclose + +AI usage is disclosed regardless of how light the involvement was. + +**Categories.** + +- Journalism and news reporting (any AI involvement, any extent) +- Bylined expert opinion (where the byline implies human authorship of the argument) +- Content where AI tools are themselves the subject (transparency about methodology is part of the topic) +- Regulated industries with explicit AI disclosure requirements (financial advice, medical content, legal content in some jurisdictions) + +**Reasoning.** In these categories, the reader's understanding of the content's origin is load-bearing for trust. A news story partially AI-drafted reads differently from a story fully reported and written by a journalist; readers have a right to that information. + +### Tier 2: Default disclosure (consider context) + +Disclosure is the default; opting out requires a specific reason. + +**Categories.** + +- Thought leadership pieces where the byline carries trust value +- Content that influences purchase decisions (reviews, comparisons, recommendations) +- Content for trust-sensitive audiences (academia, enterprise procurement, professional services) +- Long-form pieces where the audience has reasonable expectation of human craft + +**Reasoning.** Readers in these contexts often assume human authorship; AI involvement that is undisclosed becomes a trust violation if discovered. Disclosure is cheap; the trust hit from undisclosed-then-discovered AI involvement is expensive. + +### Tier 3: Generally not necessary + +Disclosure is allowed but not required by audience expectations. + +**Categories.** + +- Marketing copy (web pages, ad copy, email marketing copy) +- Descriptive product content (product descriptions, spec listings) +- Programmatic data pages (where the page is obviously data-generated) +- Internal team content (memos, internal reports) +- Copy edit assistance only (the human wrote the piece; AI suggested edits) + +**Reasoning.** In these categories, audience expectations do not assume specific authorship. Readers recognize the genre as functional content; AI involvement does not violate trust the way it would in a thought leadership piece. + +### Tier 4: Clearly fine without disclosure + +Disclosure is unnecessary and would feel weird if present. + +**Categories.** + +- AI as research assistant (the AI condensed sources; the human wrote) +- AI for transcription only (the human is the writer; the AI was a typist) +- AI for spelling and grammar suggestions (copy edit role only) +- AI as brainstorming partner where the human took the ideas and wrote independently + +**Reasoning.** The AI's role was so light that disclosure would imply more involvement than there was. Readers would interpret a disclosure as misleading. + +--- + +## Language patterns + +When disclosure is used, the language matters. + +### Patterns that work + +> "AI tools assisted in research and drafting; the author edited and verified all claims." + +> "This piece was generated programmatically from [data source]; reviewed by [team] before publish." + +> "The author drafted this piece; AI tools were used for copy edit suggestions." + +> "Research synthesis assisted by AI; all sources verified by the author." + +The patterns share three features: they specify what AI did, they specify what humans did, they identify the accountability party. + +### Patterns to avoid + +- **Hedge language.** "May have used AI" or "could have been AI-assisted" reads as covering legal bases without committing to honesty. Be specific or omit. +- **Disclosure that minimizes.** "AI was minimally involved" is hedging; either AI was substantively involved (disclose substantively) or it was not (no disclosure needed for Tier 4 use). +- **Disclosure that overstates.** "Fully written by AI" when humans rewrote 50% is dishonest in the other direction. The disclosure should match the actual AI involvement. + +### Where to place disclosure + +- **Footer or byline area.** Standard placement; readers find disclosure where they expect it. +- **Inline at relevant points.** When AI involvement varies across a piece, inline notes are clearer than a single footer note. +- **Methodology section.** Long pieces with substantial AI involvement benefit from a "How this piece was produced" section that explains the workflow. + +--- + +## Industry norms + +Disclosure norms vary by industry. The principle of intellectual honesty is constant; the specific expectations differ. + +**Journalism.** Major journalism organizations have published explicit AI usage standards. The norm is moving toward disclosure of AI involvement in any reported piece. Journalism trust depends on transparency; AI-related opacity is a fast trust violation in the audience. + +**Content marketing.** Norms are weaker but moving toward disclosure for high-trust pieces. Branded thought leadership is increasingly expected to disclose AI involvement; routine marketing copy is not. + +**Academic and research content.** AI involvement in research papers is a contested area; conferences and journals have varying policies. The conservative default is full disclosure, including which AI tools were used and at what stages. + +**Regulated industries.** Financial, medical, and legal content increasingly carries explicit AI disclosure requirements. The defaults here are tighter than in unregulated marketing content; consult the specific regulatory environment. + +**Ecommerce and product content.** Disclosure is generally not expected on product descriptions or spec listings. AI generation is genre-typical; readers do not interpret presence or absence of disclosure as meaningful. + +--- + +## When disclosure helps and when it hurts + +The honest framing. Disclosure is sometimes a trust gain, sometimes a trust loss; the calibration depends on audience norms. + +**Disclosure as trust gain.** + +- Audience expects human authorship; disclosure preempts trust loss from later discovery +- Brand positions itself on transparency +- Industry is moving toward disclosure as the new norm +- The piece's value is in research and verification, which AI assisted but did not replace + +**Disclosure as trust loss.** + +- Audience interprets AI involvement as quality reduction (sometimes a misreading, sometimes accurate) +- Disclosure language reads as defensive or hedging +- Audience expects routine content (where AI is genre-typical) + +The decision is not "always disclose" or "never disclose" but "calibrate." The calibration is best done by someone who knows the audience and the brand's positioning, not by a generic policy. + +--- + +## Disclosure policy at the program level + +The program-level discipline. Document the disclosure policy by content type. Editors and writers know which content types require disclosure; the disclosure language is templated; the policy is reviewed quarterly. + +**Template policy structure.** + +- Content type: [thought leadership]. Disclosure: [required]. Language template: [template]. +- Content type: [knowledge base article]. Disclosure: [optional]. Language template: [template if used]. +- Content type: [programmatic data page]. Disclosure: [not required]. +- Content type: [marketing landing page]. Disclosure: [not required]. + +The policy gets updated as norms evolve. AI disclosure norms in 2026 are looser than they will be in 2028; policy review keeps the program aligned with audience expectations. + +--- + +## When the disclosure decision is hard + +Edge cases. + +**Long-running expert byline.** A column under a named expert's byline, where some pieces are pure expert authorship and others are substantively AI-assisted. Disclosure on the AI-assisted pieces is the right call; the byline's trust value depends on it. + +**Pillar content with mixed authorship.** A pillar piece where the lede is human-written, the body is AI-drafted-then-rewritten, the closing is human-written. Disclosure language can specify the mix: "Research and core argument by the author; AI assisted in initial drafting of body sections; all claims verified." + +**Internal-only content that becomes external.** An internal report that gets externalized requires retroactive disclosure if the internal version was AI-assisted. Sometimes the externalization should include rewriting to bring the disclosure inline. + +The principle. When the disclosure decision is hard, default to disclosure. Trust is recoverable from over-disclosure; trust is not always recoverable from under-disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The four-tier framework, the disclosure language patterns, the industry norms summary, the trust-gain-vs-trust-loss calibration, the program-level policy structure, the edge-case handling. + +## Implementation choices that stay internal + +The specific disclosure language the team has developed for each content type. The specific tracking that records AI involvement per piece (workflow log, CMS metadata, byline annotation). The specific review cadence for the disclosure policy. The specific audience-research feedback that informs disclosure norms for the brand's specific audience. These vary by team, brand, and industry. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md new file mode 100644 index 0000000..d435d59 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md @@ -0,0 +1,154 @@ +# Ethics and intellectual honesty + +Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. + +This is the most ethically loaded reference in the catalog. The voice is honest, pragmatic, non-preachy. The catalog itself is produced with AI assistance; pretending otherwise would render any anti-AI position hypocritical. The position is not "AI use is unethical" but "intellectual honesty about AI involvement is non-negotiable." + +--- + +## Training data realities + +Every major LLM in 2026 was trained on copyrighted material. That is the simple ethical reality. + +The legal status of training-data copyright is contested in multiple jurisdictions and is being litigated. The position the catalog takes is not "AI training is ethical" or "AI training is unethical"; the position is "the question is unresolved, the tools exist, teams use them, the way to use them ethically is the question this skill addresses." + +What this skill does not relitigate. The training-data copyright question. The compute-intensity environmental question. The labor-displacement question. These are real ethical questions; this skill is not the place to resolve them. Teams reading this skill make their own choices about whether to use AI tools at all; the skill addresses how to use them with intellectual honesty when teams have made the use-AI choice. + +--- + +## Don't pass AI work as fully human-written + +The first ethical floor. + +Bylined content where the byline implies human craft requires substantial human craft. A column under a named expert's byline that is substantially AI-drafted is a trust violation regardless of whether disclosure was technically present somewhere on the page. The byline's value depends on the audience's understanding that the named human authored the piece; AI authorship that the byline obscures is dishonest. + +What "substantial human craft" requires. + +- The argument is the human's +- The voice is recognizable as the human's +- The judgments about what to include, what to cut, what to emphasize are the human's +- The fact verification is the human's +- The final approval is the human's + +What it does not require. Every word being typed by the human (research-assistant patterns are fine). Every sentence being unrewritten (copy edit assistance is fine). The human spending a specific time-on-task (the time matters less than the substance). + +--- + +## Don't claim AI didn't help when it did + +The second ethical floor. + +False denials are worse than disclosure. A team that uses AI substantially and then claims the work is fully human is staking trust on a falsifiable claim. Discovery of the AI involvement (which becomes more reliable each year as detection tools improve) compounds the trust violation: the audience now distrusts both the work and the team's honesty about the work. + +The honest pattern. If AI was used in any way that would matter to the audience, the team is honest about it. The disclosure tiering framework (per `disclosure-and-transparency-patterns.md`) addresses when disclosure is required; the no-false-denial floor is broader: even when disclosure is not required, false denial is not allowed. + +In practice. Most teams do not face direct denial questions; the issue comes up in interview contexts ("how do you produce your content?"), retrospectives, or conversations with clients and partners. The honest answer in those contexts is the truthful one, even when no public disclosure was attached to specific pieces. + +--- + +## Don't generate content that closely mirrors copyrighted source material + +The third ethical floor. + +AI tools can produce near-replicas of training data when prompted carelessly. The team's responsibility is to verify that AI-generated content is original work and not a paraphrase of a specific copyrighted source. + +The check. For each substantive section of AI-generated content, search for the unique phrasing in quoted form. If results come back to a specific copyrighted source that the AI was likely trained on, the section is too close to source material. Revise. + +The pattern. AI tools tend to mirror training data more closely on niche topics than on common topics. Common topics have many sources to blend; niche topics have fewer. Specialized content (academic topics, technical documentation, industry-specific niches) needs more careful mirroring checks. + +--- + +## Attribute when borrowing + +The fourth ethical floor. + +Ideas, frameworks, statistics, and specific phrasings that came from identifiable sources get cited. The principle is not changed by whether AI surfaced the source or whether the human did; attribution belongs to the source, not to the discovery method. + +The pattern. + +- Statistics with sources: cite the source. +- Frameworks attributed to specific thinkers: cite the thinker. +- Specific arguments traceable to a specific publication: cite the publication. +- Common knowledge: no citation needed, but verify it actually is common knowledge and not specialized knowledge that the AI surfaced from a specific source. + +The honesty test. If the team would feel uncomfortable having the source's author read the piece and recognize their work uncited, citation is required. + +--- + +## Don't fabricate quotes or expertise + +The fifth ethical floor. + +Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. The team is accountable for what gets attributed; the AI is not the accountable party. + +The pattern. AI generates plausible-but-fake quotes in 2026; that is a known limitation. The fact-accuracy gate per `editorial-qa` catches them before publish. The ethical position is broader than the QA position: even if a fabricated quote were never caught, generating it under attribution to a real person is dishonest. + +The same applies to expertise claims. AI-drafted "expert content" attributed to a named expert who did not draft it is fabricated expertise. The expert's name carries trust value; the trust depends on the expert having actually drafted the piece. + +--- + +## Be honest about AI capabilities and limits + +The sixth ethical floor. + +Do not oversell AI as more capable than it is. Do not undersell it as less capable than it is. Both produce decision-making errors in the team and in the audience. + +The pattern. AI in 2026 is genuinely useful for research synthesis, drafting against briefs, copy edit suggestions, transcription, summary, and quality-control automation at scale. AI in 2026 is genuinely limited at editorial judgment, fact verification (it is what gets fact-checked, not what does fact-checking), voice origination, ethical decisions, and reader empathy. + +Teams that get this right calibrate AI use to the limits. Teams that oversell AI ship work that exceeds AI's actual capabilities and produces hallucinations or voice failures. Teams that undersell AI miss productivity gains the technology offers. + +--- + +## The intellectual honesty frame + +The frame that supersedes specific policy debate. + +The question is not "is AI use ethical?" The question is "can the team be intellectually honest about AI use?" If yes, the team's ethics hold. If no, the team is rationalizing. + +What intellectual honesty looks like. + +- The team can articulate its AI-usage policy without defensiveness +- The team can name the specific patterns it does and does not use +- The team can defend each pattern on the merits, not just by precedent +- The team can engage with critiques of its policy without dismissing them +- The team updates its policy when reality changes (new tools, new evidence, new audience norms, new regulatory requirements) + +What intellectual dishonesty looks like. + +- Defensiveness when AI involvement is questioned +- Refusal to articulate the policy +- Dismissing critiques without engaging +- Hiding AI involvement that would be material to audiences +- Claiming AI does what it does not, or hiding that AI does what it does + +The honest team can withstand external scrutiny because its position holds up. The dishonest team eventually faces external scrutiny that surfaces the gap between claimed and actual practice. + +--- + +## When the ethical question is hard + +Edge cases. + +**Ghostwritten content historically allowed.** Industries where ghostwriting has always been the norm (executive thought leadership, celebrity book authorship, political speechwriting). AI assistance in ghostwriting workflows raises questions: is the ghost an AI? does the byline still mean what it meant? + +The conservative position. The byline implies human authorship; if the ghost is an AI rather than a human writer, that distinction is material to the audience and disclosure is appropriate. The aggressive position. Ghostwriting has always been a fiction the audience tolerates; AI ghostwriting is the same fiction with different tools. + +The catalog's position. Default to the conservative reading. The byline's trust value depends on audience understanding of authorship; AI ghostwriting under a named expert byline is more honest with disclosure than without. + +**Educational content with structured explanations.** Topics where the explanation has a canonical shape (math, basic programming, established science). AI-drafted explanations of canonical topics may closely mirror training data because the canonical shape is what the training data contains. + +The conservative position. Cite the canonical sources where they exist; rephrase substantively where citation is impractical. + +**Programmatic SEO at scale.** Hundreds of thousands of pages where individual disclosure is impractical and audience expectations differ from editorial content. + +The position. Programmatic content is genre-typically machine-generated; specific disclosure per page is unnecessary; transparency about the program's overall production model is appropriate at the brand level. + +--- + +## Methodology-level choices that stay in the public skill + +The training-data realities framing, the six ethical floors, the intellectual honesty frame, the edge-case handling, the conservative-vs-aggressive position taking on contested cases. + +## Implementation choices that stay internal + +The specific ethics policy the team has documented. The specific review process when an ethics question surfaces. The specific escalation pathway for ethics decisions. The specific tracking that records ethics-related decisions for retrospective review. These vary per team and brand. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md b/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md new file mode 100644 index 0000000..1f91b00 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md @@ -0,0 +1,121 @@ +# Hybrid workflow patterns + +Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. + +No pattern is "the right one." Pattern selection is a real decision that should match volume, voice sensitivity, team skill, and time budget. The wrong pattern produces predictable failures: AI-first drafts on voice-sensitive pieces produce slop; human-writes patterns on programmatic-scale work produce throughput failures. + +--- + +## Pattern 1: AI-first draft, human-edit-heavy + +The shape. AI produces a 90% draft against a brief. The human spends 60% of the production time editing: rewriting flat sentences, restructuring sections that miss the brief, adding voice and specificity, verifying facts. + +**Best for.** High-volume editorial where the brief is well-authored and the voice is moderately tolerant of AI defaults. SaaS blog posts, knowledge-base articles, secondary editorial pieces. + +**Risks.** Generic voice if editing is light. The pattern fails quietly; pieces ship with AI defaults preserved because the editor was rushed. + +**Time profile.** 30% AI generation, 60% human editing, 10% fact verification. Faster than human-writes for the same word count but slower than naive AI-only generation because editing time scales with the piece's length. + +**When this fits.** The team has clear brand voice and disciplined editors. The volume requirement is real (multiple pieces per day). The audience is tolerant of AI-assisted-but-edited content (most B2B, most consumer marketing). + +--- + +## Pattern 2: Human-first outline + research, AI-draft, human-rewrite + +The shape. Human builds the outline (or extends the brief's outline). Human gathers and verifies the research. AI drafts within that scaffold. Human rewrites in voice. + +**Best for.** Voice-sensitive editorial where the brand voice is distinctive enough that AI drafts need substantive rewriting anyway. The pattern formalizes the rewrite as the discipline rather than treating it as cleanup. + +**Risks.** Slower than AI-first drafts. If the rewrite is light, output is similar to Pattern 1. The discipline is in the rewrite intensity. + +**Time profile.** 20% human research and outline, 20% AI drafting, 50% human rewriting, 10% fact verification. + +**When this fits.** Brand voice is distinctive (provocative, opinionated, or emotionally specific). The audience would notice generic drafts. Time budget allows substantive rewrites. + +--- + +## Pattern 3: AI-as-research-assistant, human-writes + +The shape. AI condenses sources into research briefs. Human writes the entire piece from the brief in their own voice. + +**Best for.** Highest-trust editorial: thought leadership, contributed expert pieces, journalism, regulated content. Pieces where the byline is doing trust work and any AI involvement in drafting would compromise the byline's value. + +**Risks.** Slowest pattern. AI's role is small enough that the team may question whether AI is helping at all; the answer is usually yes (research time savings are real) but the gain is in time-to-research, not time-to-publish. + +**Time profile.** 40% human reading and outlining, 60% human writing, 10% fact verification (with AI sometimes assisting in flagging fact-check candidates). + +**When this fits.** The byline is named and trusted (a CEO, an expert, a journalist). The publication's positioning depends on human craft. Disclosure norms in the audience expect human authorship. + +--- + +## Pattern 4: Human-writes, AI-as-editor + +The shape. Human drafts the piece. AI suggests copy edits, alternative phrasings, structural improvements. Human accepts or rejects each suggestion. + +**Best for.** Senior writers whose voice is established and whose drafts are mostly clean. The AI's role is the second-pair-of-eyes that catches what fatigue or close reading missed. + +**Risks.** AI suggestions can pull voice toward AI defaults if the writer accepts too many. The discipline is rejecting the suggestions that would homogenize voice even when they read as "cleaner." + +**Time profile.** 80% human writing, 15% AI suggestion review, 5% fact verification. + +**When this fits.** The writer is experienced, the brand voice is well-developed, the piece is high-stakes. Pattern is over-kill for routine editorial; right-sized for thought leadership and named-byline pieces. + +--- + +## Pattern 5: AI-generates-at-scale, human-samples + +The shape. For programmatic SEO. AI generates thousands of pages from structured data and templates. Human samples 50 to 200 pages per cycle with editorial-qa sampling discipline. Failures above the 5% threshold halt new generation until template or data fixes ship. + +**Best for.** Programmatic SEO programs (per `programmatic-seo`). Volume scales the AI does not penalize the program because the underlying data is real and the template is strong; humans sample rather than fully review. + +**Risks.** Without sampling discipline, the program produces slop at scale. Without threshold gating, slop compounds invisibly until algorithm updates expose it. Pattern requires the editorial-qa scaling pattern to work; without QA scaling, the pattern is just AI-content-factory thinking with extra steps. + +**Time profile.** 5% template and data setup (one-time, deep), 0.5% per-page generation (mostly automated), 10% sampling QA (per cycle), 5% threshold response. + +**When this fits.** Data depth is real, query intent is queryable, QC headcount is budgeted. All five criteria from `programmatic-seo`'s when-pseo-works-decision must be met. + +--- + +## Selection criteria + +How to pick the pattern. + +**Voice sensitivity.** Distinctive voice → Pattern 2, 3, or 4. Generic-tolerant voice → Pattern 1 or 5. + +**Volume.** Single-piece-at-a-time editorial → Pattern 2, 3, or 4. High-volume editorial → Pattern 1. Programmatic scale → Pattern 5. + +**Trust requirement.** Named-byline trust work → Pattern 3 or 4. Standard branded content → Pattern 1, 2, or 5. + +**Time budget.** Tight (hours not days) → Pattern 1. Generous (days available) → Pattern 2, 3, or 4. One-time-deep then automated → Pattern 5. + +**Team skill.** Junior writers → Pattern 1 or 2 (more AI scaffolding). Senior writers → Pattern 3 or 4 (less AI, more craft). + +--- + +## Combining patterns within one program + +Most content programs run multiple patterns simultaneously. Common combinations. + +- **Editorial pillar + cluster**: Pattern 3 (AI as research assistant) for the pillar piece; Pattern 1 (AI-first draft, human-edit-heavy) for the cluster pieces. The pillar carries the trust; the cluster scales. +- **Editorial + programmatic**: Pattern 2 or 4 for editorial; Pattern 5 for programmatic. Same brand, different production model per content type. +- **Marketing copy + thought leadership**: Pattern 1 for marketing; Pattern 3 for thought leadership. Different trust requirements; different patterns. + +The discipline. Document which pattern the team uses for which content type. Without explicit documentation, the patterns drift; one writer uses Pattern 1 on a piece that should have been Pattern 3, and the trust value of the byline is compromised. + +--- + +## Anti-pattern: pattern drift mid-piece + +Sometimes a piece starts in Pattern 4 (human-writes, AI-as-editor) and drifts into Pattern 1 (AI-first, human-edits) when the writer falls behind on deadline. The piece publishes with AI default voice in sections the writer was supposed to draft. + +The fix. Recognize the drift as a process failure, not a writing failure. The writer was over-committed; the fix is workload management, not blame. Future pieces of this type either get more time (preserving Pattern 4) or get reassigned to Pattern 1 with the editing intensity that Pattern 1 requires. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns, the tradeoffs per pattern, the selection criteria framework, the multi-pattern combinations within a program, the pattern-drift anti-pattern. + +## Implementation choices that stay internal + +The specific AI tools used in each pattern (drafting model, editing model, research model). The specific prompts each pattern uses for the AI handoff. The specific time-tracking that captures pattern adherence per piece. The specific deadline-management workflow that prevents pattern drift mid-piece. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md b/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md new file mode 100644 index 0000000..e16cab8 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md @@ -0,0 +1,143 @@ +# Quality calibration with AI in the loop + +How editorial standards shift when AI is in the workflow. Same standards apply; the failure modes shift. + +The editorial standards from `editorial-qa` apply identically to AI-assisted work: brief adherence, voice consistency, fact accuracy, structure and clarity, AEO/SEO compliance, internal linking and schema validation. What shifts is the failure-mode profile. Programs that ship AI-assisted content with the same QA discipline as human-written content but without recognizing the new failure modes produce slop while believing they are calibrated. + +This reference connects the QA discipline to the AI workflow discipline. It surfaces the shifts. + +--- + +## Same standards, different failure modes + +For each editorial standard, the failure mode that dominates in AI-assisted production differs from the failure mode that dominated in human-only production. + +### Brief adherence + +**Human-only failure.** Writer skips a brief field because they think they know better, or misreads the brief. + +**AI-assisted failure.** AI ignores brief fields that were not in the prompt context. The brief is in one document; the AI prompt is in another. Brief fields that did not get pasted into the prompt do not get executed. + +**The fix.** Prompt templates that explicitly include all 12 brief fields. Brief-adherence QA gate runs against the brief, not against the prompt. + +### Voice consistency + +**Human-only failure.** Writer fatigue causes voice drift in section 4 of long pieces. Editorial style drift over months as writers absorb each other's tics. + +**AI-assisted failure.** AI default voice reasserts mid-piece. Long AI generations regress toward generic by section 4 reliably. The drift is faster than human drift and more consistent across pieces. + +**The fix.** Mid-piece voice sampling per `voice-ownership-preservation.md`. Voice anchor text in every prompt. Final pass in human voice on every long piece. + +### Fact accuracy + +**Human-only failure.** Lazy fact-checking. The writer "remembers reading" something but does not verify. Citations to publications without specific dates or page references. + +**AI-assisted failure.** AI hallucinations. Plausible-but-fake statistics with named sources that do not exist. Quotes attributed to real people who did not say them. Citations to URLs that 404. + +**The fix.** Fact-accuracy as halt-condition gate per `editorial-qa`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +### Structure and clarity + +**Human-only failure.** Buried lede, vague opening, history dump in section 1. Mismatched section lengths. + +**AI-assisted failure.** Generic opening that could open any article on the topic. Repetitive paragraph structure (every paragraph 2 to 3 sentences). Bullet-list overuse where prose would serve. Forced bilateral framing throughout. Wrap-up filler endings. + +**The fix.** AI-content audit per `editorial-qa/references/ai-content-audit-patterns.md`. Read-aloud audit catches what line-review misses. + +### AEO and SEO compliance + +**Human-only failure.** Writer forgets to include the target keyword in title and headings. Schema markup absent or invalid. + +**AI-assisted failure.** AI over-optimizes the surface (keyword in every heading, schema markup over-claimed) but under-optimizes the substance (the answer paragraph is generic, the entity coverage is thin, the POV is absent). + +**The fix.** AEO/SEO checks that go beyond surface compliance into substance: is the top-200-word answer self-contained, is the entity coverage what the brief specified, is the POV distinctive. + +### Internal linking and schema validation + +**Human-only failure.** Writer skips internal-link discipline because it feels mechanical. Anchor text uses "click here" or generic phrases. + +**AI-assisted failure.** AI-generated links to URLs that do not exist (hallucinated link targets). Anchor text repeats the same exact-match keyword across multiple links because the AI defaults to that pattern. + +**The fix.** Link-target liveness check on every published piece. Anchor text variation as a explicit QA item. + +--- + +## The "QA standards must be tighter" claim is wrong + +A common misreading. Teams shipping AI-assisted work decide their QA needs to be tighter, more checks, more thresholds. The misreading produces checkbox theater. + +The accurate reading. QA needs to be calibrated to the new failure modes, not tightened indiscriminately. The standards stay the same; the patterns to look for shift. + +The discipline. When a team starts AI-assisted production, the QA process gets reviewed against the new failure-mode profile. Some checks become more important (fact accuracy, voice consistency, AI-content audit). Some checks become less important (the writer's preferred typo patterns, since the AI does not have the same typo patterns). The QA shape adjusts. + +--- + +## Calibration sessions specific to AI-assisted work + +The calibration session methodology from `team-training-and-calibration.md` adapts for AI-assisted work specifically. + +**The AI-specific calibration session.** + +1. Three editors independently review the same 3 to 5 AI-assisted pieces. +2. Each editor's assessment includes the AI-content audit dimensions: AI tells, hallucination patterns, voice drift, slop signals. +3. The team reads all assessments together. +4. Differences in interpretation surface; reconcile. +5. Output: addendum to the AI policy doc capturing the calibration consensus on AI-specific QA dimensions. + +The cadence. Quarterly minimum. More frequent during program build or after AI tool changes that affect output behavior. + +--- + +## When the team is calibrated but the output still feels off + +Symptoms. + +- QA gates pass, individual pieces look fine, the program's overall feel is generic +- Readers complain about AI-flavored content despite QA passing +- Audience growth flat despite shipped quality being technically high + +Diagnosis. The QA discipline catches per-piece failures. It does not catch program-level patterns: every piece passing voice review individually but the cumulative output reading as homogenized. + +The fix. Add a program-level review to the calibration cadence. Read 10 published pieces in sequence. Do they sound like one publication with a distinctive voice, or do they sound like 10 separate AI-assisted pieces from different generic publications? The latter signals voice has been preserved at the per-piece level but lost at the program level. + +The intervention. Tighter voice library, more aggressive reject-the-bland discipline, possibly a return to a heavier human-writes pattern for trust-anchor pieces (pillars, thought leadership, named-author content) while keeping AI-assisted patterns for cluster work. + +--- + +## The "ship vs hold" calibration + +In AI-assisted production, the ship-vs-hold decision shifts. More pieces marginally pass QA; the question becomes whether marginal-pass pieces should ship. + +**Human-only mode.** Marginal pieces usually have specific fixes. The editor flags them; the writer fixes them; the piece ships. + +**AI-assisted mode.** Marginal pieces often have systemic AI-tells throughout that fixing one-by-one will not address. The editor's choice is between substantial rewrite (back to Pattern 2 or 3) or kill. + +The discipline. Some AI-assisted pieces are kill candidates, not revise candidates. The team should have explicit kill criteria: pieces that fail AI-content audit on 4+ dimensions, pieces where voice was lost beyond paragraph-level recovery, pieces where the underlying brief was thin enough that the AI draft has nothing to anchor to. + +Killing pieces is part of the discipline. Programs that publish 100% of what they draft are not exercising editorial judgment. + +--- + +## The calibration-with-AI checklist + +For each AI-assisted piece, beyond the standard QA gates. + +1. AI-content audit run per `editorial-qa/references/ai-content-audit-patterns.md`? +2. Voice anchor text was used in the prompt? +3. Mid-piece voice sample taken on long pieces? +4. Final pass in human voice for the closing? +5. Fact-accuracy gate ran with AI-hallucination patterns specifically in mind? +6. Disclosure decision made per the disclosure tier framework? +7. The piece passes the "could a competitor have shipped this with the same tools" test? + +If 2+ items fail, the piece is at slop risk. Halt and revise. + +--- + +## Methodology-level choices that stay in the public skill + +The same-standards-different-failure-modes mapping, the "QA standards must be tighter" misreading correction, the AI-specific calibration session adaptation, the program-level review pattern, the kill-criteria discipline, the calibration-with-AI checklist. + +## Implementation choices that stay internal + +The specific QA tooling that surfaces AI-specific failure patterns. The specific automation that flags potential AI tells before manual review. The specific calibration session cadence and team composition. The specific kill-criteria thresholds the team has settled on. These vary by team scale and content sensitivity. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md b/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md new file mode 100644 index 0000000..da21f15 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md @@ -0,0 +1,149 @@ +# Team training and calibration + +Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. + +Inconsistent AI usage across a team produces inconsistent output. The discipline below makes AI usage explicit, calibrated, and documented at the team level so the program ships consistent work regardless of which writer is assigned which piece. + +--- + +## Documented AI policy + +The starting point. Every team running AI-assisted content has a policy document, even if currently informal. + +**What the policy specifies.** + +- **Approved uses.** AI in research synthesis, AI in copy edit suggestions, AI in transcription, AI in alternative phrasings. The team uses these without per-piece approval. +- **Conditional uses.** AI in first-draft generation, AI in outline generation, AI in long-form drafting. Approved per content type (e.g., approved for cluster pieces, requires editor approval for pillar pieces). +- **Prohibited uses.** AI as the sole author of bylined expert content, AI for fact verification (the AI is what gets fact-checked, not what does fact-checking), AI for ethical decisions, AI for final approval. +- **Tool standards.** Either "the team uses [specific tool] for [specific task]" or "the team selects from this list of tools per task type." Documented either way. +- **Disclosure requirements.** By content type, per the disclosure framework. +- **Voice library reference.** Where the team's voice anchor texts and prompt templates live. + +**The discipline.** The policy is a document, not an oral tradition. Writers, editors, and contributors know where to find it; it is referenced in onboarding; it is updated quarterly. + +--- + +## Calibration sessions + +The discipline. Quarterly editor sessions where editors review the same AI-assisted pieces and surface differences in their judgment. + +**Session structure.** + +1. Three editors independently review the same 3 to 5 recently-published pieces. +2. Each editor writes a one-paragraph assessment per piece: voice, brief adherence, AI tells, fact accuracy, overall quality. +3. The team reads all assessments together. +4. Differences in interpretation surface; the team reconciles to a shared standard. +5. The session output is an addendum to the policy doc capturing the calibration consensus. + +**Why this matters.** Without calibration, individual editors apply individual taste. Some editors flag AI-tells aggressively; others ship the same piece without flagging. The inconsistency confuses writers and produces drift in published quality. + +**Cadence.** Quarterly minimum. More frequent during onboarding waves or after policy updates. + +--- + +## Voice library + +The team's collection of canonical brand-voice samples used as anchor text in AI prompts. + +**What goes in the library.** + +- 2 to 3 paragraphs of canonical brand voice per content type (blog, whitepaper, help doc, marketing copy, thought leadership) +- 2 to 3 paragraphs per writer voice (where the brand has multiple distinct contributor voices) +- 5 to 10 examples of AI-generated content that the team rewrote successfully (showing the before-and-after as a calibration aid) +- The vocabulary list: preferred terms, forbidden terms, term-specific usage rules + +**Update cadence.** Monthly during program build; quarterly once stable. + +**Why this matters.** The voice library is the operational expression of brand voice. Without a library, every AI prompt reinvents the voice context; the team produces inconsistent output. With a library, the prompt is templated and the voice context stays consistent. + +--- + +## Quality benchmarks + +The team's documented examples of "AI-assisted but on-voice" pieces. + +**What the benchmarks show.** + +- 5 to 10 published pieces where AI assistance was substantial but the output reads as on-voice +- For each benchmark: the pattern used (which workflow pattern), the editing intensity, the time profile, the quality outcome +- The benchmarks are calibration aids: writers and editors look at them when calibrating their own AI-assisted work + +**Why this matters.** "On-voice AI-assisted content" is an abstraction. Concrete examples make it tangible. New writers calibrate to the benchmarks; experienced writers reference them when their work feels off. + +**Anti-pattern.** Benchmarks that are aspirational rather than achieved. The benchmark library should be real published work, not "what we wish we shipped." Aspirational benchmarks set unrealistic expectations. + +--- + +## Tool standardization vs intentional pluralism + +Two valid models for AI tool selection at the team level. + +### Standardization + +The team uses one tool consistently for each task type. Drafting on tool A, editing on tool B, transcription on tool C. New writers learn the standard tools; the prompt templates and voice library are tool-specific. + +**When this fits.** Smaller teams. Predictable content types. Time-budget for tool learning is limited. Consistency matters more than per-task optimization. + +### Intentional pluralism + +The team documents which tools fit which tasks; writers select per-task. Tool A for tasks of type X, tool B for tasks of type Y, contributors choose between them as appropriate. + +**When this fits.** Larger teams. Diverse content types. Writers have time to learn multiple tools. Per-task optimization matters more than absolute consistency. + +The discipline either way. The choice is documented; tool selection is not arbitrary or per-writer. + +--- + +## Forbidden patterns list + +The patterns the team explicitly does not use AI for, even when AI could technically do them. + +**Common forbidden patterns.** + +- AI fabricating quotes (always; this is fabrication) +- AI generating content that names specific real people (consent and verification issues) +- AI as the sole author of bylined opinion (ethics) +- AI for content involving regulated topics where the team lacks AI-policy guidance (medical advice, legal advice, financial advice) +- AI for content the team would be ashamed to publish under their byline (slop test) + +**Why this matters.** The forbidden list is shorter than the approved list but more important. The forbidden list is what keeps the program out of ethics violations and trust failures. + +--- + +## Onboarding + +New writers learn the AI policy and calibration in their first 2 weeks. + +**Onboarding components.** + +- **Policy read.** The new writer reads the AI policy doc. +- **Voice library walkthrough.** The new writer reviews the voice samples and prompt templates. +- **Calibration session participation.** The new writer participates in the next calibration session as observer. +- **Shadow assignment.** The new writer's first piece is reviewed jointly with an experienced editor; the editor narrates the calibration in real-time. +- **Quality benchmark walkthrough.** The new writer reviews the quality benchmarks and identifies what makes each "on-voice." + +**Why this matters.** New writers without onboarding develop their own AI patterns. The program drifts as new writers join. Onboarding makes the team's discipline transferable. + +--- + +## When team calibration breaks + +Symptoms. + +- Different writers produce wildly different AI-assisted output (calibration overdue) +- Editors disagree on whether a piece is "AI-flavored" (calibration session needed) +- The AI policy doc is 6 months stale and references tools the team no longer uses (policy update overdue) +- New writers are using AI in ways that experienced writers do not (onboarding gap) +- Voice library has not been updated since the program launched (library refresh overdue) + +The fix. Quarterly calibration sessions, quarterly policy review, quarterly voice library updates, structured onboarding for every new writer. The cadences are calendar-anchored; skipping them is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +The documented-policy structure, the calibration session methodology, the voice library practice, the quality-benchmark library, the standardization-vs-pluralism choice, the forbidden-patterns discipline, the onboarding components, the calibration-breakdown signals. + +## Implementation choices that stay internal + +The specific format of the policy doc (Notion page, Markdown file, internal wiki). The specific tooling that hosts the voice library (database, Notion, Git repo of sample text). The specific calibration session cadence and team composition. The specific onboarding tracking system. The specific tool selections the team has standardized on. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md b/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md new file mode 100644 index 0000000..cbeb488 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md @@ -0,0 +1,133 @@ +# Voice ownership preservation + +Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. + +Voice is the dominant casualty of careless AI workflows. The patterns below are what programs do to keep voice through AI-assisted production. Programs that skip these patterns produce content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +--- + +## Voice guidelines as prompt input + +The principle. Every AI generation includes the brand voice guidelines as part of the prompt context. Without explicit voice context, AI defaults to a generic register that flattens distinctive brands into industry-standard prose. + +**What goes into the prompt.** + +- Voice attributes (3 to 5 attributes; e.g., "direct, confident, slightly skeptical") +- Sentence rhythm preference (short and punchy, measured and layered, conversational with asides) +- Stance pattern (opinionated, diplomatic, coach-style, peer-style) +- Register (formal, casual, register that matches the surface) +- Vocabulary preferences (preferred terms, forbidden terms list) +- Anti-patterns (specific phrases or structures to avoid) + +**The discipline.** The voice guidelines are an input to every AI run, not a one-time setup. Teams that paste the voice guidelines into a saved prompt template ensure consistency; teams that re-type them per session produce drift. + +**Why this works.** Generic AI defaults are stronger than the AI's training-era voice memory. Without active voice prompting, the AI regresses to the most common patterns in its training data, which are the most common patterns in published content, which are by definition not distinctive. + +--- + +## Sample text as voice anchor + +The principle. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. + +**What to use as anchor.** + +- The brand's strongest published piece in the relevant register +- A canonical opening from the brand's editorial doc +- A published piece from a writer whose voice the brand wants to maintain consistency with + +**The discipline.** Anchor text is updated as the brand voice evolves. Stale anchors produce stale-feeling content; the program treats anchors as living documents. + +**Why this works.** Description prompts ("write in a direct, skeptical voice") are abstract. AI mimics them generically. Sample text is concrete; AI mimics specific patterns: word choices, sentence shapes, transitional phrases, opening patterns. The mimicry is not perfect but it is closer to the brand voice than the abstract description. + +**The combination.** The strongest voice prompt combines voice guidelines (description) with sample text (concrete examples). Either alone produces drift; together they hold the line. + +--- + +## Mid-draft voice check + +The principle. Long pieces drift. At the halfway mark of a 3,000-word piece, AI generations regress toward generic. The check catches the drift before publish. + +**The check.** + +1. Sample paragraphs from the start (first 300 words), middle (1,200 to 1,800 words), and end (last 300 words). +2. Compare each sample to the brand voice doc. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. Send back for revision. + +**Detection patterns.** + +- Vocabulary regresses (words from the do-not-use list reappear; brand-specific terms drop out) +- Sentence rhythm uniforms (every paragraph 2 to 3 sentences, similar lengths) +- Stance softens (specific positions become "there are good arguments on all sides") +- Register drifts toward "professional neutral" regardless of the surface's intended register + +**Cross-reference.** This check is also covered in `editorial-qa/references/voice-consistency-patterns.md`. The two skills are aligned; the QA gate enforces what this skill prescribes. + +--- + +## Final pass in human voice + +The principle. The human edits the closing sections in their own voice. The closing is where the piece's emotional register often lands; AI defaults there reduce the piece to flat informational tone. + +**Why the closing matters.** + +- The reader's last impression +- The conversion or memory moment for the piece +- The signature moment where the brand voice is most recognizable + +**The discipline.** Even in Pattern 1 (AI-first draft, human-edit-heavy), the closing 100 to 300 words should be substantially or fully human-written. The opening can be AI-drafted with heavy editing; the closing benefits from being composed in the writer's own register. + +**Anti-pattern.** AI-drafted closing paragraphs that announce the piece is ending ("In summary," "By following these steps," "Now you have a comprehensive understanding"). These are AI tells; the human pass should replace them with specific endings: a question, an action, an observation, a direct call to action with concrete language. + +--- + +## Reject the bland + +The principle. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +**The audit.** Read the piece. For each sentence, ask: is this distinctively from this brand, or could it have come from any competitor? The interchangeable sentences are the bland ones. + +**The fix.** + +- **Replace abstractions with specifics.** "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research, do the research; if not, cut the claim. +- **Replace hedges with stances.** "It depends on your situation" becomes "for teams under 50 employees, [specific recommendation]; for teams over 200, [different specific recommendation]." +- **Replace generic openings with brand-specific openings.** Throat-clearing intros become specific entry-points tied to the piece's argument. + +**The discipline.** Bland sentences are not just "less interesting" sentences; they are voice-killers. A piece with 20% bland sentences reads as 80% diluted; the brand voice is present but watered down past distinction. + +--- + +## The voice library + +A program-level practice. The team maintains a library of canonical brand-voice samples that get used as anchor text in AI prompts. The library evolves as the brand voice evolves. + +**Library structure.** + +- Voice samples by register (formal whitepaper, casual blog post, conversational email, professional help doc) +- Voice samples by content type (pillar editorial, cluster piece, thought leadership, listicle) +- Voice samples by writer (where the brand has multiple distinct contributor voices) + +**Update cadence.** Quarterly. As new pieces ship that exemplify the voice, they go into the library. As old pieces feel stale, they come out. + +**Why this matters.** Teams without a voice library re-paste the same 3 paragraphs as anchor text for years. The voice ages; the AI mimicry ages with it; the content starts feeling dated. Library updates keep the anchor fresh. + +--- + +## When voice cannot be preserved + +Sometimes the voice is genuinely incompatible with AI assistance at the volume the program requires. Signals. + +- Brand voice is so distinctive that AI drafts always need 80% rewriting (Pattern 2 might fit; if even Pattern 2 fails, Pattern 3 or 4 are the only options) +- Audience is so trust-sensitive that any AI involvement compromises the byline (Pattern 3 only) +- Volume target requires AI involvement that voice cannot tolerate + +The honest answer in these cases. Reduce volume to match what voice tolerates, or accept voice trade-off as a strategic choice. The trade-off must be deliberate; "we did not realize voice was suffering" is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +Voice guidelines as prompt input, sample text as voice anchor, the mid-draft sampling discipline, the final-pass-in-human-voice discipline, the reject-the-bland audit, the voice library practice, the "when voice cannot be preserved" honest framing. + +## Implementation choices that stay internal + +The specific format of the brand voice doc (Notion page, Markdown file, internal wiki). The specific AI tool prompt templates that include voice guidelines and sample text. The specific voice library storage and access pattern. The specific calibration session cadence and team composition. These vary by brand and team. diff --git a/dist/pi/.agents/skills/analytics-strategy/SKILL.md b/dist/pi/.agents/skills/analytics-strategy/SKILL.md new file mode 100644 index 0000000..c67502c --- /dev/null +++ b/dist/pi/.agents/skills/analytics-strategy/SKILL.md @@ -0,0 +1,230 @@ +--- +name: analytics-strategy +description: "Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track." +category: growth +catalog_summary: "Measurement frameworks, dashboard design, event taxonomy" +display_order: 1 +--- + +# Analytics Strategy + +Design measurement frameworks that produce decisions, not just dashboards. Stack-agnostic. Tool-agnostic. + +This skill is for measurement planning. For conversion optimization, use `cro-optimization`. For SEO measurement specifically, use `seo-onpage` and adjacent SEO skills. + +--- + +## When to use + +- Setting up analytics on a new product or site +- Auditing existing analytics setup +- Designing dashboards for a team or business +- Defining KPIs and a north star metric +- Building event taxonomies for product analytics +- Designing attribution models for marketing +- Translating business questions into measurement plans + +## When NOT to use + +- Conversion testing or optimization (use `cro-optimization`) +- SEO performance measurement (use SEO skills) +- Pure data infrastructure decisions (different domain) + +--- + +## Required inputs + +- The business or product context (what does success look like) +- The audience for the analytics (who needs to make what decisions) +- The current measurement state (existing tools, tracking, gaps) +- The questions the team needs to answer + +--- + +## The framework: 4 layers + +A complete measurement strategy covers all four. Each layer feeds the next. + +### 1. North star and KPI hierarchy + +The single metric that captures the most important outcome, plus the supporting metrics. + +**North star metric:** + +- One metric. Singular. +- Captures customer-perceived value. +- Leads to revenue, but isn't revenue itself (revenue is too far downstream). +- Examples: weekly active users, completed jobs, revenue-generating sessions, hours of value delivered. + +**Underneath the north star, the KPI hierarchy:** + +``` +North star metric +├── Acquisition KPI (how new users enter) +├── Activation KPI (when new users get value) +├── Engagement KPI (how often users return) +├── Retention KPI (how many stick over time) +└── Monetization KPI (how value translates to revenue) +``` + +This is the "AARRR" or "pirate metrics" framework. It works because it covers the full lifecycle. + +### 2. Event taxonomy + +The vocabulary the product uses to describe what users do. + +**Event design principles:** + +- **Verb + noun.** `signed_up`, `created_project`, `completed_checkout`. Past tense, snake_case. +- **One event per discrete action.** Not "interacted_with_modal" - too vague. Specifically `opened_modal_X`, `closed_modal_X`, `confirmed_in_modal_X`. +- **Properties capture context.** Each event has properties (key-value pairs) for context. `signed_up` has properties like `signup_method`, `referrer`, `plan`. +- **Standardize property names.** `user_id` everywhere, not `userId` here and `id` there. +- **Document everything.** A tracking plan that lives nowhere is a tracking plan no one follows. + +**Event coverage:** + +- All key user actions tracked +- All conversion points tracked +- All errors tracked +- All page views tracked (with consistent properties) +- All button clicks that matter (not all button clicks - that's noise) + +**Anti-patterns:** + +- 500+ events with no documentation +- Inconsistent naming (`buttonClicked`, `Button Clicked`, `clicked_button`) +- Property keys that vary across events +- Events fired client-side that should be server-side (and vice versa) +- PII in event properties (privacy issue and tooling issue) + +### 3. Dashboards and reports + +The interface between data and decisions. + +**Dashboard design principles:** + +- **One audience per dashboard.** Executive dashboard != product team dashboard. Different metrics, different cadence. +- **One question per chart.** A chart should answer one question, not three. +- **Annotations matter.** Note launches, experiments, holidays, outages. A spike means nothing without context. +- **Context comparisons.** "10,000 signups this month" - compared to what? Last month, last year, target? +- **Lead with the action.** What does this dashboard help someone decide? + +**Common dashboard types:** + +| Dashboard | Audience | Metrics | Cadence | +|---|---|---|---| +| Executive | Leadership | North star, top 3 KPIs, big-picture trends | Weekly review | +| Product | Product team | Funnel metrics, feature adoption, retention | Daily / weekly | +| Marketing | Marketing team | Acquisition by channel, CAC, attribution | Daily / weekly | +| Operations | Ops / on-call | Performance, errors, capacity | Real-time | +| Custom (per team) | Specific team | Their specific KPIs | Their cadence | + +### 4. Attribution and segmentation + +How to connect cause and effect. + +**Attribution models:** + +- **First-touch.** Credit the first interaction. Useful for awareness understanding. +- **Last-touch.** Credit the final interaction before conversion. Default in many tools, often misleading. +- **Linear.** Spread credit equally across touches. Avoids over-crediting any single channel. +- **Time-decay.** Recent touches get more credit. Reasonable middle ground. +- **Position-based.** First and last get more credit, middle touches less. +- **Data-driven (algorithmic).** Tools like Google Analytics 4 use ML. Black box but increasingly the default. + +For most businesses: pick one primary attribution model, use multiple secondary models for validation. + +**Segmentation principles:** + +- Segment by what causes different behavior, not by what's easy to track +- Useful segments: source/channel, plan tier, geography, device, cohort (signup date) +- Less useful: demographic guesses without behavioral validation + +--- + +## The tracking plan document + +Output of the analytics strategy. A living document. + +**Structure:** + +1. **Goals and KPIs.** Business objectives, north star, KPI hierarchy. +2. **Event catalog.** Every event, with properties, when fired, why tracked. +3. **User properties.** Persistent attributes (plan, signup_date, role). +4. **Page taxonomy.** Page categories, page properties. +5. **Naming conventions.** Snake_case, verb_noun, etc. +6. **Implementation notes.** Client-side vs server-side, SDK details, sampling. +7. **Privacy and compliance.** PII rules, consent handling, data retention. +8. **Governance.** Who can add events, review process, change log. + +--- + +## Workflow + +1. **Define the questions.** What does the team need to answer? Working backward from questions to metrics works better than starting from metrics. +2. **Define the north star.** One metric. Tested against the criteria above. +3. **Build the KPI hierarchy.** Acquisition, activation, engagement, retention, monetization. +4. **Audit existing tracking.** What's there? What's broken? What's missing? +5. **Design the event taxonomy.** Cover the user journey. Document everything. +6. **Implement with care.** Test each event. Verify properties. Catch issues in staging. +7. **Build dashboards.** One per audience. Lead with action. +8. **Establish review cadence.** Weekly business review, monthly KPI review, quarterly strategy review. +9. **Govern.** Who adds events, who reviews, how changes propagate. + +--- + +## Failure patterns + +- **Tracking everything.** Noise overwhelms signal. +- **Tracking nothing strategic.** Page views and that's it. Cannot answer real questions. +- **No documentation.** Tracking plan lives in someone's head. +- **Inconsistent naming.** Same concept, three names. Reports become detective work. +- **Events fired but never reviewed.** Tracking debt accumulates. +- **Dashboards no one looks at.** Built for vanity, not decisions. +- **Single attribution model treated as truth.** All models lie. Some lie usefully. +- **PII in events.** Compliance and tooling problems. +- **Client-side only.** Critical business events should be server-side too. Ad blockers, network issues, edge cases lose client-side events. +- **No connection to business outcomes.** Metrics exist in a silo, never connected to revenue, retention, or strategic decisions. + +--- + +## Output format + +Default output: a markdown tracking plan at `analytics-tracking-plan.md` plus a dashboard inventory. + +Tracking plan structure: + +```markdown +# Tracking Plan + +## North star metric +[Definition, calculation, target] + +## KPI hierarchy +[Each KPI with definition, calculation, owner] + +## Event catalog +| Event | When fired | Properties | Owner | Status | +|---|---|---|---|---| +| user_signed_up | After successful signup form submit | source, plan, referrer | Marketing | Live | +| project_created | When user clicks Create Project | project_type, template_used | Product | Live | +| ... | | | | | + +## User properties +[List with definitions] + +## Naming conventions +[Rules] + +## Privacy and compliance +[Rules] + +## Governance +[Process] +``` + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Starter event catalog with patterns for common product types. diff --git a/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md b/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md new file mode 100644 index 0000000..69e22bb --- /dev/null +++ b/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md @@ -0,0 +1,407 @@ +# Event Taxonomy Template + +Starter event catalogs for common product types. Adapt to specific products. The patterns generalize. + +--- + +## Universal events (most products need these) + +### Lifecycle events + +| Event | When fired | Common properties | +|---|---|---| +| `user_signed_up` | New account created | signup_method, source, referrer, plan | +| `user_logged_in` | Successful login | login_method | +| `user_logged_out` | Session ended | session_duration | +| `user_deleted_account` | Account deletion | reason (if collected) | + +### Product/feature engagement + +| Event | When fired | Common properties | +|---|---|---| +| `feature_used` | Specific feature interaction | feature_name, feature_version | +| `setting_changed` | User changes a setting | setting_name, old_value, new_value | +| `notification_clicked` | User clicks a notification | notification_type, notification_id | + +### Errors + +| Event | When fired | Common properties | +|---|---|---| +| `error_occurred` | Anywhere an error is shown to user | error_type, error_message, page, action_attempted | +| `form_validation_failed` | Form submit blocked by validation | form_name, fields_with_errors | + +### Communication + +| Event | When fired | Common properties | +|---|---|---| +| `email_received` | Email delivered (server-side, via ESP webhook) | email_type, campaign_id | +| `email_opened` | Email opened (via tracking pixel) | email_type, campaign_id | +| `email_clicked` | Link in email clicked | email_type, campaign_id, link_text | +| `email_unsubscribed` | User unsubscribes | email_type | + +--- + +## SaaS / B2B product events + +``` +Acquisition +├── user_signed_up +├── trial_started +└── trial_extended + +Activation (the "aha" moment) +├── workspace_created +├── teammate_invited +├── first_project_created +├── first_integration_connected +└── first_value_action (product-specific - the moment user gets value) + +Engagement +├── session_started +├── project_opened +├── workflow_completed +└── feature_X_used (one per key feature) + +Conversion +├── plan_upgraded +├── seats_added +├── invoice_paid +└── annual_plan_purchased + +Retention +├── returned_after_inactivity +├── reactivated_from_email +└── usage_milestone_hit (e.g., crossed 100 actions) + +Risk signals +├── support_ticket_opened +├── billing_failure_occurred +├── trial_expiring_soon (calculated, server-side) +└── churn_risk_threshold_hit (calculated) +``` + +### Properties to capture across all events + +``` +user_id Persistent across sessions +session_id New per session +account_id For multi-user accounts +plan Current plan tier +days_since_signup +device_type +browser +os +geo_country +geo_region +referrer +utm_source / utm_medium / utm_campaign / utm_term / utm_content +``` + +--- + +## Ecommerce events + +``` +Discovery +├── page_viewed +├── search_performed +├── search_results_viewed +├── filter_applied +└── product_listing_viewed + +Consideration +├── product_viewed +├── product_image_zoomed +├── size_selected +├── color_selected +├── reviews_read +└── product_shared + +Cart +├── product_added_to_cart +├── product_removed_from_cart +├── cart_viewed +├── cart_quantity_changed +└── cart_abandoned (calculated, server-side) + +Checkout +├── checkout_started +├── shipping_info_entered +├── billing_info_entered +├── promo_code_applied +├── promo_code_failed +├── checkout_step_viewed (with step_name) +└── purchase_completed + +Post-purchase +├── order_shipped +├── order_delivered +├── product_returned +├── review_submitted +└── reorder_initiated +``` + +### Ecommerce-specific properties + +``` +For purchase_completed: + order_id + total_value + currency + shipping_method + payment_method + discount_applied + items: [ + { product_id, product_name, category, brand, variant, quantity, unit_price } + ] + +For product_viewed: + product_id + product_name + category + brand + price + in_stock + position (when viewed in a list) +``` + +--- + +## Content site / publisher events + +``` +Reading +├── page_viewed +├── article_started (when article body enters viewport) +├── article_25_percent_scrolled +├── article_50_percent_scrolled +├── article_75_percent_scrolled +├── article_100_percent_scrolled (read to end) +└── article_time_spent (calculated on page exit) + +Engagement +├── newsletter_signup_shown +├── newsletter_signup_completed +├── comment_posted +├── article_shared +├── article_bookmarked +└── related_article_clicked + +Subscription (if metered/paywalled) +├── paywall_hit +├── paywall_dismissed +├── subscribe_started +├── subscribe_completed +├── article_unlocked (free, registered, paid) +``` + +### Content-specific properties + +``` +For article events: + article_id + article_title + category + author + published_date + word_count + paywall_status (free, registered_only, paid_only) + is_premium +``` + +--- + +## Marketplace events + +Marketplaces have two-sided tracking: buyers and sellers/providers. + +``` +Buyer side +├── search_performed +├── listing_viewed +├── inquiry_sent +├── booking_started +├── booking_completed +├── review_left +└── repeat_booking_made + +Seller/provider side +├── listing_created +├── listing_published +├── listing_edited +├── inquiry_received +├── inquiry_responded +├── booking_received +├── booking_completed +├── payout_received +└── review_received +``` + +### Marketplace-specific properties + +``` +For listing_viewed: + listing_id + category + price + location + seller_id + position_in_search + +For booking_completed: + booking_id + listing_id + seller_id + buyer_id + total_value + fee_amount +``` + +--- + +## Mobile app events + +``` +App lifecycle +├── app_installed (server-side or attribution platform) +├── app_first_opened +├── app_opened (every launch) +├── app_backgrounded +├── app_foregrounded +└── app_uninstalled (often inferred, hard to track directly) + +Engagement +├── push_notification_received +├── push_notification_opened +├── deep_link_opened +└── share_extension_used + +Permissions +├── permission_requested (push, location, camera, etc.) +├── permission_granted +└── permission_denied +``` + +### Mobile-specific properties + +``` +app_version +app_build +device_model +os_version +network_type (wifi, cellular) +push_token +notification_permission_status +``` + +--- + +## Forms and surveys + +``` +Form lifecycle +├── form_viewed +├── form_started (first field interaction) +├── form_field_focused +├── form_field_completed +├── form_field_validation_failed +├── form_submitted +└── form_abandoned (left page without submit) +``` + +### Properties + +``` +form_name +form_id +fields_total +fields_completed +fields_with_errors +time_spent_seconds +``` + +--- + +## Naming convention rules + +### Verb_noun, past tense, snake_case + +✓ `user_signed_up` +✓ `product_added_to_cart` +✓ `article_50_percent_scrolled` +✗ `signupCompleted` +✗ `addProduct` +✗ `Article 50% Scrolled` + +### Properties: camelCase or snake_case (pick one and stay) + +snake_case is more common in SQL contexts (data warehouses). +camelCase is more common in JavaScript/TypeScript contexts. +The choice matters less than consistency. + +✓ `user_id`, `signup_method`, `email_type` (consistent snake_case) +✓ `userId`, `signupMethod`, `emailType` (consistent camelCase) +✗ `userId`, `signup_method`, `EmailType` (mixed) + +### Property values: standardize where possible + +Don't allow free-text where an enum should exist. + +✓ `signup_method: "email" | "google" | "github" | "sso"` +✗ `signup_method: "email", "Email", "EMAIL", "via email", "with email address"` + +### Reserved properties + +Most analytics tools have built-in properties. Don't override them. + +Common reserved names: +- `id`, `userId` (or system equivalent) +- `event`, `event_name` +- `timestamp`, `time` +- `session_id` +- `anonymous_id` +- `properties`, `traits` + +--- + +## What NOT to track + +- **PII in event properties.** Email, phone, full name, address. Privacy issue and tooling issue. +- **Every click.** Track meaningful clicks. Hover events. Mouse movements. Generic interactions are noise. +- **Server-side state churn.** Background jobs, cron runs, internal events. These belong in monitoring, not product analytics. +- **Anything you cannot define in one sentence.** If you can't describe what the event represents, you won't be able to use it. + +--- + +## Privacy and consent + +Common compliance patterns: + +- **Consent before tracking.** Cookie banner, opt-in flow. +- **Honor Do Not Track.** Browsers signal preferences. +- **Right to deletion.** User can request all their data deleted (GDPR, CCPA). +- **Right to export.** User can request their data in machine-readable format. +- **No cross-site tracking without consent.** Some jurisdictions require explicit opt-in. +- **Data residency.** EU user data may need to stay in EU. + +Standard compliance approaches: + +- Server-side tagging when available (more reliable, more controllable) +- Consent management platform (CMP) for cookie consent +- Clear privacy policy that lists what you collect +- A pseudonymous user ID separate from PII + +Compliance specifics vary by jurisdiction. Consult counsel for high-stakes decisions. + +--- + +## Governance and review + +Patterns that work: + +- New events require an RFC or short proposal +- Event catalog reviewed quarterly +- Deprecated events flagged and removed after a grace period +- Tracking plan version-controlled (in Git) +- Implementation tested in staging before production +- Monitoring on event volume (sudden drops = tracking break) diff --git a/dist/pi/.agents/skills/art-direction/SKILL.md b/dist/pi/.agents/skills/art-direction/SKILL.md new file mode 100644 index 0000000..65e9452 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/SKILL.md @@ -0,0 +1,198 @@ +--- +name: art-direction +description: "Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables." +category: design +catalog_summary: "Photography, illustration, and visual direction for campaigns" +display_order: 3 +--- + +# Art Direction + +Direct creative work that extends the brand into specific deliverables. Photography, illustration, video, motion, campaigns, environmental design. + +This skill assumes brand identity is approved (`brand-identity` complete). Art direction is about applying and extending it, not defining it. + +--- + +## When to use + +- Briefing photographers, illustrators, videographers +- Developing campaign creative concepts +- Directing in-house creative teams +- Writing creative direction documents for vendors +- Evaluating creative deliverables for brand fit +- Adapting brand visual identity to a new format or context + +## When NOT to use + +- Setting project-wide aesthetic direction across multiple downstream skills (use `creative-direction` instead). This skill briefs specific creative deliverables; `creative-direction` produces the structured aesthetic brief that this skill consumes. +- Defining brand visual identity from scratch (use `brand-identity`) +- Day-to-day component design (use `design-standards`) +- Writing copy for creative work (use `content-and-copy` or `landing-page-copy`) +- Building a design system (use `design-system`) + +--- + +## Required inputs + +- The deliverable (photo shoot, illustration set, video, campaign) +- The brand identity (visual system, voice, imagery direction) +- The audience for this specific work +- The goal (brand awareness, conversion, education, emotional connection) +- Budget and timeline +- Distribution context (where it will be seen) + +--- + +## The framework: 5 layers + +A creative brief covers five layers. Each must be clear before the brief leaves your hands. + +### 1. The story + +What this creative work is fundamentally about. + +- **The premise.** The core idea in one sentence. +- **The emotional through-line.** What the audience feels. +- **The role of the brand.** How the brand shows up in the story. +- **The takeaway.** What the audience walks away with. + +A weak premise produces work that's pretty but says nothing. Spend time here. + +### 2. The look + +The visual treatment. + +**For photography:** +- Subject and composition (close-up, environmental, candid, posed) +- Lighting (natural, studio, dramatic, soft) +- Color palette (true color, treated, monochrome) +- Locations (specific or general direction) +- Wardrobe and props +- Mood references (3 to 5 reference images) + +**For illustration:** +- Style (flat, dimensional, hand-drawn, geometric, abstract) +- Color use (full palette, restricted, brand-only) +- Line treatment +- Composition style +- Detail level +- Reference artists or works (with explicit "we want like X but NOT like Y") + +**For video / motion:** +- Pacing (slow, medium, fast cuts) +- Camera movement (static, handheld, sweeping) +- Color grading +- Transitions and effects +- Audio direction (music, voiceover, ambient) +- Reference work (3 to 5 examples) + +### 3. The execution + +Production-level direction. + +**Specifications:** +- Deliverable formats and sizes (web hero, social square, print full-page) +- Required shots or frames +- Optional shots if budget allows +- Wardrobe and prop list (for live action) +- Color and asset specs (RGB, CMYK, hex codes for matching) + +**Constraints:** +- Things to avoid (specific cliches, forbidden treatments, regulatory) +- Brand-system requirements (logo placement, color use, type rules) + +### 4. The variants + +How this creative scales across distribution. + +Most creative needs to live in multiple places. Plan the variants up front. + +**Common variant set for a campaign:** +- Hero web image (16:9 or wider) +- Mobile web hero (4:5 or 1:1) +- Social square (1:1) +- Social vertical (9:16) +- Email banner (3:1 typical) +- Display ad sizes (300x250, 728x90, etc.) +- Print sizes if applicable + +For each variant, note: how the composition adapts, what gets cropped or repositioned, what assets are required. + +### 5. The standards + +The quality bar. + +**Technical:** +- Resolution and format requirements +- Color profile +- File naming conventions +- Delivery format (raw + edited, layered files, exported variants) + +**Creative:** +- What "approved" looks like (specific examples of acceptable work) +- What "not approved" looks like (specific examples to avoid) +- Number of revision rounds budgeted + +--- + +## Workflow + +### For briefing external creative + +1. **Confirm the inputs.** Brand identity locked. Audience and goal clear. Budget and timeline known. +2. **Develop the concept.** Premise, emotional through-line, takeaway. +3. **Build the look.** Mood references. Specific direction on style elements. +4. **Write the spec.** Production-level direction. Variants. Constraints. +5. **Brief the vendor.** In writing. Walk through it live. Allow questions. +6. **Review milestones.** Treatment review, halfway review, final review. Don't skip the early reviews; corrections compound. +7. **Approve and document.** What was produced, what's licensed for what use. + +### For directing in-house creative + +1. **Same brief, lighter format.** In-house direction can be more iterative. Still document the brief. +2. **Co-create.** In-house teams know the brand. Use their judgment. Don't over-direct. +3. **Establish review rhythm.** Daily check-ins for fast work, weekly for longer projects. + +### For evaluating existing creative + +1. **Score against the brief.** Did the work hit the brief? Where did it deviate? +2. **Score against the brand.** Does this look like the brand? Could this be confused with a competitor? +3. **Score against the goal.** Will this drive the intended outcome? +4. **Identify fixes.** What can be improved? What's a deal-breaker vs. acceptable? + +--- + +## Failure patterns + +- **"Modern, clean, minimal" briefs.** Means nothing. Force specificity. Use specific reference brands, named artists, or visual examples. +- **No "what to avoid" direction.** Vendors interpret broadly. Tell them what's out of bounds explicitly. +- **Reference imagery that's actually competitor work.** You'll get something that looks like the competitor. Never use direct competitors as references. +- **Skipping early reviews.** Every revision late in the process is 5x more expensive than catching issues at treatment stage. +- **Too many cooks.** 6 stakeholders all giving creative feedback produces incoherent work. Concentrate creative authority. +- **Ignoring distribution.** Creative that doesn't work in the actual contexts where it will live is failed creative. +- **No variant planning.** Discovering at delivery that you need a square crop and the photographer composed for 16:9 only. +- **Approving creative that's "fine."** Fine is the enemy of distinctive. If it doesn't move you, it won't move the audience. + +--- + +## Output format + +Default output is a creative brief at `creative-brief-[project].md`. + +Structure: +1. The story (premise, through-line, role of brand, takeaway) +2. The look (visual treatment with references) +3. The execution (specs, variants, constraints) +4. The standards (quality bar, examples of acceptable and unacceptable) +5. The logistics (timeline, milestones, budget, deliverables) + +Plus a separate moodboard or visual reference doc with images. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Generic art direction brief template covering any production type (photo, illustration, video, animation, mixed). +- [`references/photo-shoot-brief.md`](references/photo-shoot-brief.md) - Detailed brief template for photography commissions. +- [`references/illustration-brief.md`](references/illustration-brief.md) - Brief template for illustration commissions. diff --git a/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md b/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md new file mode 100644 index 0000000..feb2406 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md @@ -0,0 +1,249 @@ +# Art Direction Brief Template + +A fillable brief for art direction projects. Fill every section before production begins. A short brief beats a generic brief; a generic brief produces generic work. + +--- + +## Project: [Name] + +**Project type:** [Photography / Illustration / Video / Animation / Mixed] +**Channel(s):** [Where this will live] +**Date briefed:** [YYYY-MM-DD] +**Production date:** [YYYY-MM-DD] +**Director:** [Name] +**Producer:** [Name] +**Budget:** [Range] + +--- + +## 1. Project context + +**Why this project exists:** +[1 to 2 paragraphs. The business reason this work needs to be made.] + +**What it must accomplish:** +[The specific outcome. Awareness, conversion, brand association, internal use, etc.] + +**How it will be measured:** +[Concrete success indicator. Engagement, completion rate, brand lift, internal feedback.] + +--- + +## 2. Concept + +**The big idea (one sentence):** +[The angle, insight, or opinion the creative work expresses.] + +**Why this concept now:** +[2 to 3 sentences. Why this idea fits the moment, the brand, and the audience.] + +**What this concept rejects:** +[The opposite or adjacent ideas this concept is not.] + +--- + +## 3. Audience + +**Primary audience:** +[Specific persona. "Mid-career operator at a B2B SaaS company evaluating tools for their team," not "B2B buyers."] + +**What they currently feel about the category:** +[1 to 2 sentences.] + +**What we want them to feel after seeing this:** +[1 to 2 sentences.] + +--- + +## 4. Subjects + +**People:** +- Cast: [Demographics, archetypes, specific casting direction] +- Wardrobe: [Direction] +- Expression: [What we want them showing] +- Diversity: [Explicit casting expectations] + +**Products:** +- What appears: [List] +- Staging: [How they're shown] +- Hierarchy: [Hero product vs supporting] + +**Settings:** +- Locations: [Specific or category] +- Environment: [Indoor/outdoor, real/built, public/private] +- Time of day: [If relevant] + +**Objects/props:** +- Required: [Specific items] +- Forbidden: [Things never to include] + +--- + +## 5. Composition + +**Formats and channels:** +| Channel | Aspect ratio | Resolution | Specific requirements | +|---|---|---|---| +| [e.g., Instagram feed] | 1:1 | [px] | [Crop-safe area for text overlay] | +| [e.g., Instagram stories] | 9:16 | [px] | [Top/bottom safe areas] | +| [e.g., Web hero] | 16:9 | [px] | [Subject must allow text overlay on left] | +| [e.g., Print] | [Specific] | [DPI] | | + +**Shot list:** +[Specific shots required. Include reference frame for each.] + +1. [Shot description]: [Reference image] +2. [Shot description]: [Reference image] +3. [Shot description]: [Reference image] + +**Framing direction:** +- Crop tendency: [Tight / medium / wide] +- Subject placement: [Centered / off-center / dynamic] +- Eye line: [To camera / away / unspecified] +- Depth: [Foreground emphasis / background environment / flat] +- Negative space: [Generous / minimal / variable] + +--- + +## 6. Lighting + +**Direction:** +[2 to 4 sentences describing the lighting approach.] + +**Specific qualities:** +- Source: [Natural / available / controlled] +- Direction: [Front / side / back / overhead] +- Quality: [Hard / soft] +- Color temperature: [Warm / neutral / cool] +- Time of day if natural: [Specific] + +**Lighting references:** +[3 to 5 reference images with annotations.] + +--- + +## 7. Color and treatment + +**Color palette:** +[Brand palette + any campaign-specific extensions] + +**Treatment direction:** +- Saturation: [True / muted / desaturated / heightened] +- Contrast: [Low / balanced / high] +- Color grade: [Specific look or signature] +- Film references: [Specific films, photographers, or art if relevant] + +**Treatment references:** +[3 to 5 reference images with annotations.] + +--- + +## 8. Tone + +**Adjectives (3 to 5):** +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] + +**Pacing (moving image):** +[If applicable: brisk / deliberate / breathless / languid] + +**Sound direction (moving image):** +[If applicable: score, sound design, voice, silence] + +--- + +## 9. Reference moodboard + +[Link to moodboard with 10 to 15 curated images.] + +Each reference labeled with what we are taking from it (composition, lighting, treatment, casting, etc.). Avoid using a single reference for everything; pull specific elements from different sources. + +--- + +## 10. What to avoid + +**Visual cliches in our category to reject:** +- [Specific cliche with example] +- [Specific cliche with example] +- [Specific cliche with example] + +**Treatments not aligned with our direction:** +- [Specific treatment] +- [Specific treatment] + +**Casting we will not use:** +- [Specific casting type and why] + +--- + +## 11. Deliverables + +**Final deliverables required:** + +| Asset | Format | Count | Specifications | +|---|---|---|---| +| [e.g., Hero image] | JPG, PNG | 5 | 16:9, 4K | +| [e.g., Story crops] | MP4 | 10 | 9:16, 1080p, 15s max | +| [e.g., Behind-the-scenes] | MP4 | 1 | 16:9, 60s | + +**Editing/retouching specifications:** +[Color grading approach, retouching rules, watermarking, captions] + +**File naming convention:** +[`project-asset-version-channel.format`] + +**Delivery method:** +[How files arrive. Drive, DAM, direct upload.] + +--- + +## 12. Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Pre-production complete | | | +| Production day(s) | | | +| Selects review | | | +| Edit v1 / first cut | | | +| Final delivery | | | + +--- + +## 13. Approvals + +**Approval path:** +1. [Person / role] - [What they approve] +2. [Person / role] - [What they approve] +3. [Final approver] + +**Maximum review rounds:** [Typically 2 to 3] +**Hard stop:** [Date after which changes are out of scope] + +--- + +## 14. Talent + +**Photographer / Illustrator / Director:** [Name and rate] +**Why we picked them:** [1 to 2 sentences linking their portfolio to this brief] +**Crew:** [Producer, stylist, lighting, etc.] +**Talent (on-camera):** [Casting decisions] + +--- + +## 15. Open questions + +[Anything unresolved at brief-writing time. Resolve before production day.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: +- [Name] [Date] +- [Name] [Date] + +Production day(s) confirmed: [Date] diff --git a/dist/pi/.agents/skills/art-direction/references/illustration-brief.md b/dist/pi/.agents/skills/art-direction/references/illustration-brief.md new file mode 100644 index 0000000..46bba36 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/illustration-brief.md @@ -0,0 +1,238 @@ +# Illustration Brief + +A complete brief for commissioning illustration work. Use as a starting template, fill out fully before sending to the illustrator. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a redo (and most illustrators charge for redos). + +--- + +## Project overview + +**Project name:** [Working title] +**Date of brief:** [YYYY-MM-DD] +**Delivery deadline:** [Final files due] +**Illustrator / studio:** [If selected] +**Producer / point of contact:** [Name and contact] +**Budget:** [Total or per-illustration rate] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is each illustration fundamentally about?] + +### Audience +[Who will see these illustrations. Their context, their state of mind.] + +### Goal +[What do these illustrations accomplish? Editorial illustration, brand storytelling, product visualization, instruction, decoration?] + +### Brand role +[How does the brand show up? Subtle (illustrations stand on their own), prominent (brand mark visible in scene), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Playful," "considered," "warm," "sharp," "optimistic."] + +--- + +## The look + +### Style references + +[5 to 10 reference illustrations. Source: illustrator portfolios (Behance, It's Nice That, Cargo), editorial illustration archives, ad campaigns. AVOID: direct competitor imagery, AI-generated images, copyrighted character work used out of context.] + +For each reference, note WHAT to take from it: +- "From this illustration: the loose hand-drawn line quality" +- "From this illustration: the limited color palette" +- "From this illustration: the flat geometric construction" + +NOT just dumping references with no commentary. The illustrator needs to know which qualities matter. + +### What to AVOID + +- [Specific style cliche to avoid, e.g., "Corporate Memphis / Alegria figures"] +- [Specific style cliche to avoid, e.g., "isometric tech-startup spot illustrations"] +- [Visual treatment that's been overused in the category] + +### Style and technique + +- **Medium:** [Vector / raster / mixed / hand-drawn scanned / 3D] +- **Line quality:** [Geometric and clean / loose and gestural / no line / variable] +- **Fill style:** [Flat / textured / gradients / cross-hatching / watercolor] +- **Detail level:** [Highly detailed / minimal / mid] +- **Perspective:** [Flat / isometric / one-point / loose / mixed] +- **Figure style** (if illustrating people): [Realistic / stylized / abstract / no figures] + +### Color + +- [Specific palette with hex codes if matching brand] +- [Number of colors: limited (2-3), moderate (4-6), full] +- [Treatment: brand-matched / shifted / monochrome / sepia / saturated / muted] + +### Composition + +- [Single subject focus / scene with multiple elements / pattern / decorative] +- [Negative space treatment] +- [Orientation defaults: square, landscape, portrait, mixed] + +--- + +## Illustration list + +A specific list of illustrations needed. Each entry is a deliverable. + +### Required illustrations (must-have) + +1. **[Illustration name]** + - Subject: [What's depicted] + - Concept: [What it should communicate or evoke] + - Use case: [Where it will appear, e.g., "blog post hero, 1200x675"] + - Variants: [Aspect ratios or color modes needed] + +2. **[Illustration name]** + - Subject: + - Concept: + - Use case: + - Variants: + +[Continue for all required illustrations] + +### Optional illustrations (if time and budget allow) + +1. **[Illustration name]** +2. **[Illustration name]** + +### Variants per illustration + +Most illustrations need to work in multiple contexts: + +- **Light mode and dark mode:** does the illustration need a dark-background variant? +- **Aspect ratios:** which crops are needed (16:9, 1:1, 9:16, banner)? +- **Resolution variants:** retina vs standard, social vs hero +- **Cropped vs full:** is a cropped detail of the same illustration also needed? +- **Animation:** is a static illustration plus a looping animated version needed? + +When briefing, note which variants each illustration must support. + +--- + +## Technical specs + +### Source files + +- **Format:** [AI / SVG / PSD / PNG layered / Procreate / Figma] +- **Layered structure required:** [Yes - so the brand can adjust colors, swap elements, or animate later. No - flat delivery only.] +- **Editability:** [Editable text and shapes preferred / OK to outline] + +### Export formats + +- **Web:** [SVG for vector, WebP / PNG for raster] +- **Print:** [If applicable: CMYK, 300 DPI, with bleed] +- **Resolution:** [Specific minimums per use case] +- **Color profile:** [sRGB for web, CMYK for print] + +### Delivery + +- **Format:** [Cloud delivery, file sharing, hard drive] +- **Naming convention:** [e.g., "ProjectName_IllustrationN_VariantX.svg"] +- **Asset management:** [Where the files live after delivery] + +### Licensing + +- **Usage:** [Where the illustrations can be used; web, print, paid media, all media, in perpetuity] +- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual] +- **Geography:** [Worldwide, US-only, etc.] +- **Exclusivity:** [Exclusive to brand, or illustrator can include in portfolio? Most illustrators want portfolio rights even on exclusive work.] +- **Modification rights:** [Can the brand modify the illustration in-house, or does any change require returning to the illustrator?] +- **NFT / generative AI training:** [Explicitly state whether the illustrator can use the work to train AI, and whether the brand can.] + +--- + +## Process and milestones + +### Stages and approvals + +A typical illustration commission moves through these stages. Define what each milestone delivers and who approves. + +| Stage | What is delivered | Who approves | +|---|---|---| +| Brief approved | This document, signed | Brand lead | +| Sketches / thumbnails | 2-3 rough directions per illustration | Brand lead + creative director | +| Refined sketch | Single chosen direction, more detail | Brand lead + creative director | +| Color and style test | One illustration finalized as reference | Brand lead + creative director | +| Final illustrations | All deliverables, in all variants | Brand lead | +| Files handed over | Source + exports, organized | Brand lead | + +### Revision rounds + +- **Sketch round 1:** [What is in scope. Typically composition and concept. Major changes are easier here.] +- **Sketch round 2:** [Refinement only. Style and composition are locked.] +- **Final art rounds:** [Typically 1 round of small adjustments. Beyond this, usually billed separately.] +- **Beyond included rounds:** [Cost or process for additional rounds.] + +### Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Brief approved | | | +| Sketches delivered | | | +| Sketch sign-off | | | +| First finished illustration | | | +| Style sign-off | | | +| Remaining illustrations delivered | | | +| Final files handed over | | | + +--- + +## Budget breakdown + +| Item | Cost | Notes | +|---|---|---| +| Illustrator fee (base) | | | +| Per-illustration rate | | | +| Style test / first finish | | | +| Revisions beyond included rounds | | | +| Rush fees (if applicable) | | | +| License fees (if separate from base) | | | +| Source file delivery (if separate) | | | +| **Total** | | | + +--- + +## Approval process + +### Who approves at each stage + +- **Brief:** [Name] +- **Sketches:** [Names] +- **Style test:** [Names] +- **Final illustrations:** [Name] +- **Final delivery:** [Name] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Illustrator credit: [Required / optional / no credit. Typical: credit required where editorial use, optional where commercial.] +- Promotion: [Illustrator can / cannot promote on their own portfolio. Typical: yes after the work is publicly launched.] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md b/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md new file mode 100644 index 0000000..c3efba1 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md @@ -0,0 +1,255 @@ +# Photo Shoot Brief + +A complete brief for commissioning a photo shoot. Use as a starting template, fill out fully before sending to the photographer. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a reshoot. + +--- + +## Project overview + +**Project name:** [Working title] +**Date of brief:** [YYYY-MM-DD] +**Shoot date(s):** [Target dates] +**Location(s):** [Specific or "TBD - photographer recommends"] +**Photographer / studio:** [If selected] +**Producer / point of contact:** [Name and contact] +**Budget:** [Total or range] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is this shoot fundamentally about?] + +### Audience +[Who will see these images. Be specific. Their context, their state of mind.] + +### Goal +[What do these images accomplish? Brand awareness? Conversion? Emotional connection? Editorial illustration?] + +### Brand role +[How does the brand show up? Subtle (it's about the people), prominent (the product is the hero), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Confident," "intimate," "celebratory," "considered," "energetic."] + +--- + +## The look + +### Visual references + +[5 to 10 reference images. Source: photographers' portfolios, ad campaigns, editorial work. AVOID: direct competitor imagery.] + +For each reference, note WHAT to take from it: +- "From this image: the soft natural light" +- "From this image: the close composition on hands" +- "From this image: the muted color palette" + +NOT just dumping references with no commentary. + +### What to AVOID + +- [Specific visual cliche to avoid, e.g., "Stock-photo-style smiling at camera"] +- [Specific visual cliche to avoid] +- [Visual treatment that's been overused in the category] + +### Lighting + +- [Natural / studio / mixed] +- [Soft and diffused / dramatic and directional / high-contrast / low-contrast] +- [Time of day if natural] + +### Color + +- [True color / treated / monochrome / desaturated] +- [Specific color palette or mood, with hex codes if matching brand] + +### Composition + +- [Tight crops vs. wide environments] +- [Symmetrical vs. asymmetrical] +- [Subject placement preferences] +- [Portrait vs. landscape orientation defaults] + +### Wardrobe and styling + +- [Casual / formal / specific style direction] +- [Color preferences for wardrobe] +- [Things to avoid (logos other than ours, distracting patterns, etc.)] + +### Subjects / talent + +- [Demographics and casting direction] +- [Specific talent if cast, or open call criteria] +- [Diversity considerations] +- [Number of subjects per shot] + +### Props and set + +- [Required props] +- [Set direction (clean, lived-in, organized, chaotic, etc.)] +- [Branded elements (yes / no / minimal)] + +--- + +## Shot list + +A specific list of shots needed. Each entry is a shot the photographer must deliver. + +### Required shots (must-have) + +1. **[Shot name]** + - Description: [What's in the frame] + - Composition: [Tight, wide, environmental] + - Use case: [Where this image will be used, e.g., "homepage hero, 16:9"] + - Quantity: [How many variations] + +2. **[Shot name]** + - Description: + - Composition: + - Use case: + - Quantity: + +[Continue for all required shots] + +### Optional shots (if time and budget allow) + +1. **[Shot name]** +2. **[Shot name]** + +### Variants per shot + +Most shots need to work in multiple aspect ratios. Specify: + +- **16:9 (wide):** for web hero, video thumbnails +- **4:5 (vertical):** for social, mobile hero +- **1:1 (square):** for Instagram, app icons, avatars +- **9:16 (vertical extreme):** for Stories, vertical video + +When briefing, note which aspect ratios each shot must support. Photographer composes accordingly (loose enough to crop multiple ways, OR shoots specifically for each crop). + +--- + +## Technical specs + +### Resolution and format + +- **Minimum resolution:** [e.g., 6000x4000] +- **File format:** [RAW + edited high-res JPG / TIFF] +- **Color profile:** [sRGB / Adobe RGB] +- **Color space:** [Web vs. print] + +### Editing + +- **Editing scope:** [Color correction only / full retouch / specific retouch needs] +- **Editing reference:** [Examples of approved final-look] + +### Delivery + +- **Format:** [Cloud delivery, file sharing, hard drive] +- **Naming convention:** [e.g., "ProjectName_ShotN_VariantX.jpg"] +- **Asset management:** [Where the files live after delivery] + +### Licensing + +- **Usage:** [Where the images can be used; web, print, paid media, all media, in perpetuity] +- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual] +- **Geography:** [Worldwide, US-only, etc.] +- **Exclusivity:** [Exclusive to brand, or photographer can include in portfolio?] + +--- + +## Logistics + +### Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Brief approved | | | +| Treatment / mood board sign-off | | | +| Casting / location finalized | | | +| Shoot day(s) | | | +| Selects delivered | | | +| Final edits delivered | | | + +### Budget breakdown + +| Item | Cost | Notes | +|---|---|---| +| Photographer fee | | | +| Talent | | | +| Wardrobe / styling | | | +| Hair / makeup | | | +| Location fee | | | +| Set / props | | | +| Equipment | | | +| Editing / retouching | | | +| Production / coordination | | | +| Contingency (10%) | | | +| **Total** | | | + +### Crew + +- Photographer: [Name] +- Photo assistant: [Name] +- Producer: [Name] +- Stylist: [Name] +- Hair / makeup: [Name] +- Talent: [Names] +- Brand reps on set: [Names] + +### Logistics day-of + +- Call time: [Time] +- Wrap time (target): [Time] +- Catering / craft services: [Plan] +- Wet weather plan: [If outdoor] +- Day-of contact list: [Names and numbers] + +--- + +## Approval process + +### Who approves at each stage + +- **Brief:** [Name] +- **Treatment / mood board:** [Names] +- **Day-of selects:** [Names on set or remote review] +- **Edited final selects:** [Name] +- **Final delivery:** [Name] + +### Revision rounds + +- **Edits round 1:** [What's in scope] +- **Edits round 2:** [What's in scope] +- **Beyond round 2:** [Cost or process for additional rounds] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Photographer credit: [Required / optional / no credit] +- Promotion: [Photographer can / cannot promote on their own portfolio] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md b/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md new file mode 100644 index 0000000..3a5c787 --- /dev/null +++ b/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md @@ -0,0 +1,268 @@ +--- +name: backup-and-disaster-recovery +description: "Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability." +category: operations +catalog_summary: "RPO/RTO targets, backup strategy, restoration drills" +display_order: 6 +--- + +# Backup and Disaster Recovery + +Plan for the worst case: the database is gone, the host is down for a week, the deploy was poisoned, ransomware encrypted everything. The skill is in advance preparation, not reaction. + +--- + +## When to use + +- Setting up backups for a new system +- Reviewing and validating backup architecture +- Defining RPO (recovery point objective) and RTO (recovery time objective) +- Running a disaster recovery drill +- Diagnosing gaps after an incident +- Planning for ransomware, data corruption, or insider threats +- Migrating to a new platform (DR planning belongs in the migration plan) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Routine deploy rollbacks (use `launch-runbook`) +- Code or content versioning (covered by Git, CMS revision history) +- Routine database snapshots (use this skill to set them up; routine review goes in monitoring) + +--- + +## Required inputs + +- The systems in scope (databases, file storage, code, configs, secrets) +- The hosting platforms and providers +- Existing backup tooling and what it covers +- Tolerance for data loss (in time) +- Tolerance for downtime (in time) +- Compliance requirements (some regulations mandate specific backup standards) + +--- + +## The framework: 4 questions + +Every disaster recovery plan answers four questions explicitly. + +### Question 1: What needs to be recoverable? + +List every system that holds state. Categorize by criticality. + +**Tier 1: must recover.** Without it, the business stops. (Customer database, transaction log, primary content store.) + +**Tier 2: should recover.** Loss is painful but not fatal. (Analytics, logs, secondary services.) + +**Tier 3: nice to recover.** Easy to rebuild. (Caches, derived data, temporary state.) + +The tier drives RPO, RTO, backup frequency, and storage spend. + +### Question 2: How much data loss is acceptable? (RPO) + +RPO is the maximum age of data that's acceptable to lose, measured in time. + +- RPO = 1 hour: hourly backups or continuous replication needed +- RPO = 1 day: daily backups acceptable +- RPO = 1 week: weekly backups acceptable + +For most production data, RPO of 1 hour or less is the target. For critical financial systems, near-zero RPO (continuous replication). + +For derived or rebuildable data, RPO of 1 day or longer is fine. + +### Question 3: How much downtime is acceptable? (RTO) + +RTO is the maximum time to restore service after a disaster. + +| RTO target | Implies | +|---|---| +| < 5 minutes | Hot standby with automatic failover | +| < 1 hour | Warm standby with manual failover or fast restore from recent snapshot | +| < 24 hours | Cold backup with documented restore process | +| Days to weeks | Best-effort, accept extended downtime | + +RTO drives architecture spend. Aggressive RTOs (< 1 hour) are expensive. Loose RTOs (days) are cheap. + +### Question 4: What's the disaster? + +Plan for specific scenarios. Each has different implications. + +**Hardware failure.** Disk dies. Standard backups solve this. Most modern hosts handle automatically. + +**Provider outage.** Region or vendor goes down. Cross-region or cross-provider redundancy needed for low RTO. + +**Data corruption.** Bad migration, bug, accidental delete. Point-in-time restore needed. The latest backup might be corrupted; you need history. + +**Ransomware or compromise.** Attacker encrypts or deletes. Backups must be immutable or air-gapped, otherwise the attacker takes them too. + +**Account compromise.** Attacker has admin credentials, deletes everything. Same defense as ransomware: immutable backups, separate access control. + +**Vendor lock-out.** Account suspended, billing dispute, vendor disappears. Backups outside the vendor needed. + +**Insider threat.** Disgruntled employee deletes or exfiltrates. Audit logs, separation of duties, immutable backups. + +A backup strategy that handles only hardware failure isn't a strategy. It's the easiest case. + +--- + +## Workflow + +### Step 1: Inventory state + +Every system that holds state goes on a list: + +| System | Data type | Tier | Current backup | Tested? | +|---|---|---|---|---| + +If you can't list it, you can't protect it. Often the inventory itself reveals gaps (the "we forgot about that database" moment). + +### Step 2: Set RPO and RTO per tier + +For each tier, agree on RPO and RTO. Get sign-off from the people who'd be impacted by a disaster. + +Push back on aspirational targets that aren't backed by infrastructure spend. RTO of 5 minutes for a system without a hot standby is not real. + +### Step 3: Verify or design backup architecture + +For each system, ensure: + +- **Frequency** matches RPO. +- **Retention** covers point-in-time recovery (typically 30+ days for production data). +- **Storage location** is separate from the source. Same disk, same account, same region: not enough. +- **Immutability or write-once storage** for at least some backup copies. Defends against ransomware. +- **Encryption at rest.** Standard for compliance. +- **Tested restore procedure.** Untested backups are not backups. + +The "3-2-1 rule" is a useful starting point: 3 copies of data, 2 different storage types, 1 offsite (or off-account, off-platform). + +### Step 4: Document the restore runbook + +For each system, write the runbook: + +1. How to detect the disaster (cross-reference monitoring) +2. How to decide to restore (decision criteria, who authorizes) +3. The exact restore steps (commands, screenshots, sequence) +4. How to verify the restore worked +5. How to switch traffic back +6. Communication template (status page, customer notice) + +The runbook is for the worst night of someone's career. Write it for tired, panicked you. + +### Step 5: Run a drill + +The first restore should never be during a real disaster. + +Drills can be: + +- **Tabletop:** walk through the runbook on paper. Useful for finding gaps in the plan. +- **Partial:** restore to a non-production environment. Verify the data, validate the steps. +- **Full:** simulate the disaster. Production failover or full restore. Maximum confidence, maximum risk. + +For most teams: quarterly tabletop, annual partial drill, full drill before major launches or after major architecture changes. + +### Step 6: Document drill results + +After each drill, document: +- What was tested +- What worked +- What broke +- What the actual RPO and RTO were (vs. targets) +- Action items + +If the actual RTO was 6 hours when the target was 1 hour, the target is fiction. Either fix the gap or revise the target. + +### Step 7: Schedule the next drill + +Calendar it. Assign an owner. Backups that aren't drilled drift toward useless. + +--- + +## Special topics + +### Database point-in-time recovery + +Many managed databases offer point-in-time recovery (PITR) within a retention window (often 7-35 days). This typically achieves RPO of seconds to minutes. + +For longer retention, schedule periodic exports to immutable storage. + +PITR alone isn't enough. If the database service itself is compromised, PITR is gone too. Always have at least one backup outside the source service. + +### File storage backups + +Object stores (S3, GCS, Azure Blob) usually offer: + +- Versioning (recover overwritten objects) +- Replication (cross-region) +- Object lock or immutability (defense against deletion) + +Set all three for production-critical buckets. Don't rely on the storage provider's default retention. + +### Code and config backups + +Code lives in Git. The Git host (GitHub, GitLab, etc.) is your backup, but a single host is a single point of failure. + +For high-criticality code: +- Mirror to a second host or your own server +- Periodic offline exports + +Configs and secrets need separate handling: +- Infrastructure-as-code: in Git, mirrored +- Runtime configs: backed up alongside the system +- Secrets: in a secret manager with its own backup story + +### Backups of backups + +The backup system itself can fail. Backup metadata, backup credentials, encryption keys: all must be backed up. + +If your backup is encrypted with a key you've lost, the backup is useless. + +### Compliance backups + +Some regulations require specific retention (e.g., 7 years for financial data). Comply with the highest applicable standard. + +Don't conflate compliance retention with operational backup. Compliance often allows much slower restore (just need to be able to produce the data eventually). + +--- + +## Failure patterns + +**Untested backups.** The single most common failure. Backups appear to work; restore fails. Test. + +**Backups in the same account or region as the source.** Account compromise or region outage takes both. + +**No immutability.** Ransomware encrypts the backups too. Use object lock or air-gapped storage. + +**RTO and RPO that aren't measured.** Target says "1 hour" but no one has verified the actual RTO. Assume the actual is longer than the target until proven otherwise. + +**Restore runbook only in someone's head.** Person leaves or is unavailable; runbook is gone. Document. + +**Backups but no DR plan.** "We have backups" isn't a plan. The plan is the runbook plus the architecture plus the drilling. + +**Optimism bias.** "It won't happen to us." It happens. Plan as if it will. + +**Backups too old or too new.** Want point-in-time history (in case corruption isn't immediately discovered). Daily snapshots with 30+ day retention. Or continuous replication with separate periodic snapshots for history. + +**Skipping drills "because we're busy."** Then you'll be busier during the disaster. + +**No communication plan.** Restoring data is half the job. Telling customers, stakeholders, and internal teams what's happening is the other half. + +--- + +## Output format + +A DR plan document includes: + +- **Inventory:** every stateful system +- **Tiering:** criticality per system +- **Targets:** RPO and RTO per tier +- **Architecture:** backup tooling, frequency, storage, immutability +- **Runbooks:** restore procedures per system +- **Drill schedule:** what gets tested when +- **Drill log:** results of past drills +- **Communication templates:** what to say during a real DR event + +--- + +## Reference files + +- [`references/restore-runbook-template.md`](references/restore-runbook-template.md): Fillable template for a restore runbook, covering detection, authorization, steps, verification, and rollback. diff --git a/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md b/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md new file mode 100644 index 0000000..6adf708 --- /dev/null +++ b/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md @@ -0,0 +1,231 @@ +# Restore Runbook Template + +Fill out one of these per system that needs to be restorable. The runbook is read by a tired, panicked person at 3am. Optimize for that reader. + +--- + +## System: [System name] + +**Owner team:** [Team name] +**On-call escalation:** [Who, how to reach] +**Last drill:** [YYYY-MM-DD] +**Last verified working:** [YYYY-MM-DD] + +--- + +## Tier and targets + +| | Target | Last measured | +|---|---|---| +| Tier | [1 / 2 / 3] | | +| RPO | [Time] | [Time] | +| RTO | [Time] | [Time] | + +If the last measured RTO is longer than the target, the target needs revision or the architecture needs investment. + +--- + +## What this system does + +[2-3 sentences describing what the system is and why it matters. The reader may not be familiar with this system in a panic.] + +--- + +## What "lost" looks like + +The triggers for using this runbook: + +- [ ] [Specific symptom, e.g., "Database returns errors on all queries"] +- [ ] [Specific symptom, e.g., "Data has been deleted or appears corrupted"] +- [ ] [Specific symptom, e.g., "Provider region is down per their status page"] +- [ ] [Specific symptom, e.g., "Account access is locked or suspended"] + +If none of these match, this might not be the right runbook. Pause and check `incident-response`. + +--- + +## Decision: should we restore? + +Restoring is destructive. Don't do it without authorization. + +**Authorize restoration if:** +- [Condition 1] +- [Condition 2] +- [Condition 3] + +**Do NOT restore if:** +- The system is recoverable through less destructive means (failover, replica promotion, partial fix) +- The data loss is recoverable through other channels (event replay, cache rebuild) +- We're not yet sure of the cause (restoring on top of an unknown cause can make things worse) + +**Authorization required from:** [Role] +**Backup authorization from:** [Role] + +Document the authorization in the incident channel before proceeding. + +--- + +## Pre-restore checklist + +- [ ] Authorization received and documented +- [ ] Communication sent: status page updated, internal notice posted +- [ ] Recent backup identified and validated +- [ ] Backup integrity verified (checksum, sample query, etc.) +- [ ] Target environment prepared (downtime accepted, traffic redirected) +- [ ] Rollback plan understood +- [ ] Timer started (track actual RTO) + +--- + +## Restore procedure + +### Step 1: Identify the backup to restore from + +[Specific instructions: which backup system, how to find the right one, how to verify it's the right one.] + +``` +[Example commands] +``` + +### Step 2: Prepare the target + +[Specific instructions: which environment, how to ensure no traffic, how to clear or prepare destination.] + +``` +[Example commands] +``` + +### Step 3: Run the restore + +[Specific instructions: the actual restore command(s), expected duration, what success looks like.] + +``` +[Example commands] +``` + +Expected duration: [Time] + +### Step 4: Verify + +[Specific instructions: how to know the restore worked. Sample queries, row counts, data spot-checks.] + +``` +[Example commands and queries] +``` + +Expected results: [What to look for] + +### Step 5: Re-enable traffic + +[Specific instructions: how to direct traffic back to the restored system.] + +``` +[Example commands] +``` + +### Step 6: Monitor + +For [time period] after the restore: + +- [ ] Watch error rates (link to dashboard) +- [ ] Watch latency (link to dashboard) +- [ ] Spot-check user-visible behavior +- [ ] Confirm no further data anomalies + +--- + +## Rollback + +If the restore makes things worse: + +[Specific instructions for reverting. This is rarely possible for data restores, but for failover-style restores, rollback is just the failover in reverse.] + +--- + +## Post-restore + +### Communication + +- [ ] Status page updated (resolved) +- [ ] Internal notice updated (system restored) +- [ ] Customer comms (if appropriate, who and what) +- [ ] Stakeholder summary + +### Documentation + +- [ ] Actual RTO recorded +- [ ] Actual RPO measured (latest data point preserved vs latest data point lost) +- [ ] Notes on any deviations from the runbook +- [ ] Items to fix in the runbook + +### After-action + +Schedule the after-action report within 5 business days. See `after-action-report` skill for the framework. + +--- + +## Backup details + +### Backup architecture + +| | Detail | +|---|---| +| Backup tool | [Tool name] | +| Frequency | [Cadence] | +| Retention | [Period] | +| Storage location | [Where, including account/region] | +| Immutable? | [Yes / No, details] | +| Encryption | [Method, key location] | + +### How backups are tested + +- [ ] [Test method 1] +- [ ] [Test method 2] +- [ ] [Test method 3] + +Last test: [YYYY-MM-DD] +Test cadence: [How often] + +--- + +## Dependencies + +This system depends on: +- [Dependency 1, what it provides] +- [Dependency 2, what it provides] + +If a dependency is also down, the restore may need to wait or proceed with workarounds. Document the workarounds: + +- [Dependency unavailable scenario 1]: [Workaround] +- [Dependency unavailable scenario 2]: [Workaround] + +--- + +## Drill log + +| Date | Type (tabletop / partial / full) | Outcome | Issues found | Fixes | +|---|---|---|---|---| +| YYYY-MM-DD | [Type] | [Pass / Partial / Fail] | [Issues] | [Fixes applied] | + +--- + +## Maintenance + +This runbook needs review: +- After every restore (real or drill) +- When the system architecture changes +- When backup tooling changes +- At least quarterly + +Last review: [YYYY-MM-DD] by [Name] +Next review: [YYYY-MM-DD] + +--- + +## Common gotchas + +[List of things that have surprised people during past restores or drills. Specific to this system.] + +- [Gotcha 1] +- [Gotcha 2] +- [Gotcha 3] diff --git a/dist/pi/.agents/skills/beta-program-management/SKILL.md b/dist/pi/.agents/skills/beta-program-management/SKILL.md new file mode 100644 index 0000000..30362a4 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/SKILL.md @@ -0,0 +1,312 @@ +--- +name: beta-program-management +description: "Running closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time." +category: product +catalog_summary: "Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops)" +display_order: 13 +--- + +# Beta Program Management + +A senior product leader's playbook for running betas that produce real signal. Closed and open betas, alpha programs, design partner programs, early access. Participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). + +Most betas underperform. Teams ship a beta because they think they should run a beta; participants are recruited loosely or open-flooded; feedback is collected ad-hoc through whatever channels exist; the decision to graduate to GA happens on calendar rather than on signal. The beta produced activity but not learning; the team launches with the same uncertainty they had before the beta. + +This skill is the discipline that turns betas into decision input. Calibrated cohorts who match the post-launch user profile. Structured feedback that captures what the team needs to know. Mid-beta triage that uses what is being learned. Graduation criteria that distinguish "ready" from "we are tired of running the beta." The discipline is not bureaucratic; it is the difference between a beta that informs the GA launch and a beta that produces noise. + +The voice is the senior product leader who has run betas with real signal and watched plenty of betas produce nothing. Concrete, opinionated about what produces signal, willing to call out where beta programs slide into ceremony. + +When to use this skill: planning a beta for an upcoming launch, auditing why prior betas have not produced actionable signal, designing the beta participant experience, or deciding whether a feature is ready to graduate from beta to GA. + +--- + +## What this skill is for + +This skill spans beta program design and execution. The PM and engineering distinction: + +- `feature-flagging` is rollout mechanics; the technical layer for controlling who gets which features. +- **`beta-program-management` (this skill)** is participant management and feedback discipline; the human layer. +- `feature-launch-playbook` is the full launch (post-GA); this skill is what happens BEFORE GA. +- `experiment-design` is rigorous A/B testing; betas are softer, qualitative-leaning, smaller-N. +- `user-feedback-aggregation` is ongoing feedback streams; beta feedback is bounded to the beta period. +- `discovery-research-synthesis` is one-off discovery research; betas are validation-stage rather than discovery-stage. + +The audience: senior PMs, product directors, engineering leads coordinating with product, customer success and support running beta cohorts, anyone planning a closed or open beta. + +What is not in scope: the broader feature launch (covered by `feature-launch-playbook`); the technical rollout mechanics (covered by `feature-flagging`); the rigorous experimentation methodology (covered by `experiment-design`); the discovery-stage research that informs whether to build the feature in the first place. + +--- + +## Soft-launch vs kitchen-sink vs structured-beta + +The keystone framing. + +**Soft-launch.** "We will just turn it on for some users." No structured participant selection, no defined feedback collection, no graduation criteria. The beta runs because the team wanted to ship the feature without the full launch ceremony. Output: the feature is in production for some users; the team has no organized way to learn from their experience; signal accumulates through whatever channels happen to surface it; mid-beta course-correction does not happen because there is no structure to surface what should be corrected. + +**Kitchen-sink.** Everyone gets in. The beta opens to whoever signs up. 5,000 beta users; 50 useful pieces of feedback; 4,950 silent users who provide no signal. Volume drowns signal. The team cannot tell which users matched the target post-launch profile. Feedback channels overflow; useful patterns get lost in noise; mid-beta triage cannot keep up. Output: a sense of "we ran a big beta" without the actionable feedback that smaller calibrated cohorts produce. + +**Structured-beta.** Calibrated cohort selected by participant criteria. Intentional feedback loops the cohort knows to use. Clear graduation criteria that distinguish "ready for GA" from "tired of the beta." Mid-beta triage that uses what is being learned. Output: the beta produces decision-grade signal; the GA launch ships with confidence; problems that would have surfaced in production get caught and addressed in beta. + +The litmus test. After the beta concludes, ask: what specifically did we learn from this beta that changed the GA launch? If the team can name 3-7 specific lessons, the beta was structured. If the team can only generally say "the beta went well," the beta was soft-launch or kitchen-sink. + +--- + +## Beta type decisions + +Several axes of beta-type choice. The right combination depends on the launch context. + +**Closed vs open.** + +- Closed: invite-only. Participants are selected by criteria. Cohort is bounded. +- Open: anyone can join. Cohort is self-selecting. +- Closed produces calibrated signal; open produces volume signal that may not match the target user profile. + +**Alpha vs beta vs RC.** + +- Alpha: very early, internal or trusted-partner only, expectation of bugs. +- Beta: more polished, broader cohort, expectation of feedback rather than crash discovery. +- RC (release candidate): essentially launch-ready, last validation, expectation of production-grade quality. + +**Internal vs external.** + +- Internal: only employees use the feature. +- External: real customers use the feature. +- Internal betas catch only what employees would experience; external betas catch the full user-context complexity. + +**Time-bounded vs open-ended.** + +- Time-bounded: 4-week beta, 8-week beta, with a defined end. +- Open-ended: beta runs until the team decides to graduate. +- Time-bounded forces the graduation decision; open-ended risks beta-purgatory. + +The combination decision. A typical structured beta might be closed + beta + external + 6-week time-bounded. A design partner program might be closed + alpha + external + open-ended. An open early access might be open + beta + external + time-bounded. The combination should match the kind of signal the team needs. + +Detail in [`references/beta-type-decisions.md`](references/beta-type-decisions.md). + +--- + +## Participant selection criteria + +The discipline that makes calibrated cohorts possible. + +**The criteria that work.** + +- **Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. The beta participant profile should resemble the target GA audience. +- **Variety across relevant dimensions.** Not all participants identical. If the feature has segment-specific behavior, the cohort spans segments. If usage volume varies, the cohort includes high-volume and low-volume users. +- **Feedback willingness.** Participants who agree to provide feedback through the structured channels. Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- **Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively. Customers in churn-risk are less likely to engage; their feedback may also be less representative. + +**The criteria that fail.** + +- **Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers; their feedback may not represent the broader target user. +- **Highest-paying customers only.** Skews toward enterprise patterns that may not generalize; misses smaller-team use cases. +- **Internal employees only.** Misses the customer-context complexity; signals "we tested" without "real users tested." + +**The cohort size question.** Calibrated cohorts are usually 20-200 participants for closed external betas. Smaller (5-20) for design partner programs. Larger (200-2,000) for open early access. Beyond 2,000 the program is a soft-launch with beta branding. + +Detail in [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md). + +--- + +## Beta cohort sizing + +How big is enough; when does signal saturate. + +**Saturation patterns.** + +- Critical feedback (bugs, crashes, broken flows) saturates quickly. 20-30 participants surface most critical issues in the first 2 weeks. +- Behavioral feedback (how users actually use the feature) saturates more slowly. 50-100 participants needed to see usage patterns clearly. +- Edge case feedback saturates slowly. 100+ participants needed; some edge cases never surface in beta. + +**Sizing decisions.** + +- For betas focused on bug discovery: 20-50 participants for 2-4 weeks. Beyond this, returns diminish. +- For betas focused on behavioral signal: 50-200 participants for 4-8 weeks. +- For betas focused on validating product-market fit assumptions: 100-500 participants over 8-12 weeks. +- For betas focused on at-scale infrastructure validation: 500-2,000 participants over 4-8 weeks. + +**The "beta size matches signal need" principle.** Cohort size follows from what the team needs to learn. Larger is not always better; calibrated is. + +Detail in [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md). + +--- + +## Onboarding beta participants + +How participants enter the beta and what they know going in. + +**The setup.** + +- Welcome communication that sets expectations: what the beta is, what feedback is expected, how long it runs, what happens at graduation. +- NDAs where relevant (for unannounced features, design partner programs). +- Feedback channel access: where participants give feedback, what format, what cadence. +- Support escalation path: who participants contact when things break. +- Compensation or incentive disclosure: free access to the feature post-GA, gift cards, swag, named recognition, etc. + +**The expectations contract.** + +- What the team commits to participants: communication cadence, response to feedback, transparent about graduation criteria. +- What participants commit to the team: feedback through the structured channels, not sharing externally during NDA, willingness to engage in interviews if requested. + +**Common onboarding failures.** + +- Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. +- No NDA where appropriate. Beta features get screenshotted on social before the team is ready. +- Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. +- No incentive clarity. Participants feel underrecognized; engagement decays. + +Detail in [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md). + +--- + +## Feedback collection patterns + +Structured channels that produce signal rather than noise. + +**Channels that work.** + +- **Structured surveys.** 5-15 question surveys at defined points (week 1, week 4, end of beta). Specific questions tied to the team's learning goals. +- **Async feedback forms.** Participants submit specific feedback through a defined form. Fields prompt for use case, severity, expected vs actual behavior. +- **Structured interviews.** 30-60 minute interviews with a subset of participants (5-15 per beta). Focused on usage patterns, decision moments, and qualitative depth. +- **In-product feedback widgets.** Contextualized to the moment. The feedback is timestamped to the user's actual experience. +- **Support tickets routed to beta-aware support.** Beta participants get faster, more contextualized support; the support interactions surface usage friction. + +**Channels that fail.** + +- **Slack channels for venting.** Beta participants vent in real time; signal mixes with noise; nobody synthesizes. +- **"Reply to this email with feedback."** Returns long unstructured emails; synthesis is hard; useful patterns get lost. +- **"Tell us what you think in the survey at the end."** End-of-beta surveys catch only what participants remember; in-the-moment friction is forgotten. + +**Channel mix discipline.** Most structured betas use 3-5 channels. Each channel surfaces different kinds of signal. The team synthesizes across channels. + +Detail in [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md). + +--- + +## Mid-beta triage and iteration + +How the team responds to feedback during the beta. + +**The principle.** Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. + +**The triage cadence.** + +- Weekly: review feedback across all channels. Categorize: critical bug, friction issue, feature request, positive signal, edge case. +- Bi-weekly: surface patterns. What recurring feedback are we seeing? What signal is converging? +- As-needed: critical issues get same-day response. Bugs that prevent core flows are not allowed to sit. + +**The iteration discipline.** + +- Critical bugs fixed during the beta. Beta participants experience the fixes; the post-fix experience informs the GA decision. +- Friction issues prioritized for fixes during the beta where feasible; documented for the GA decision where not. +- Feature requests captured for post-GA roadmap; not added during the beta unless they are graduation-blocking. +- Positive signal validated; surfaces what works, informs marketing copy and onboarding for GA. + +**The communication discipline.** Participants are kept informed: "We received your feedback on X; we are addressing it in next week's beta update." Silence makes participants feel ignored; over-communication signals overhead. Calibrate. + +Detail in [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md). + +--- + +## Beta-to-GA decision criteria + +Graduation gates that distinguish "ready" from "tired of running the beta." + +**The criteria.** + +- **Critical bugs cleared.** No known crashes, data loss, or core-flow failures. +- **Friction issues addressed or accepted.** Friction the team will not address by GA is documented and accepted as known limitation. +- **Behavioral validation.** Beta participants are using the feature in the patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). +- **Performance under load.** The feature performs adequately at the scale GA will produce. (For infrastructure betas, this is the central criterion.) +- **Documentation and support readiness.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work. +- **Positive signal sufficient.** Feedback is net-positive enough to launch with confidence. Not all participants delighted, but a substantial majority finding value. + +**The "we are tired of running the beta" anti-pattern.** Beta has run long enough that the team wants to graduate regardless of signal. The graduation decision happens on calendar rather than on criteria. Resist this; either the criteria are met (graduate) or they are not (extend or reset). + +**The "perpetual beta" anti-pattern.** Beta runs indefinitely because no firm graduation criteria were set. The team avoids the GA commitment by keeping the feature in beta. Force the graduation decision; if the feature is not ready for GA, identify what would make it ready or reconsider whether to ship at all. + +Detail in [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md). + +--- + +## Beta wind-down and participant communication + +How the beta ends. + +**The graduation announcement.** Participants are told the feature is graduating. Specific date. What changes for them: continued access (typically yes), pricing changes (often beta participants get free access for some period), feature stability commitments (the GA version is what they will use going forward). + +**The transition.** + +- For most participants: nothing changes operationally. The feature stays available; the "beta" label drops. +- Pricing transitions communicated explicitly if applicable. +- Beta-only features that did not make GA are flagged. Participants who relied on those features are given alternatives or transition timelines. + +**The thank-you.** Beta participants invested time providing feedback. Recognition matters: named in changelog (with consent), gift cards or swag, advance access to future betas. The recognition strengthens future-beta recruitment. + +**The postmortem.** Internal review of what the beta produced. What was learned, what changed in the GA launch, what would be done differently in future betas. This feeds the team's beta program practice. + +Detail in [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-beta-failures.md`](references/common-beta-failures.md). + +- "Our beta produced no signal." Soft-launch pattern; no structured selection or feedback collection. +- "Our beta has 5,000 users and we cannot synthesize feedback." Kitchen-sink; cohort too large for the structured signal the team needs. +- "Our beta participants never gave feedback." Onboarding contract was unclear or feedback channels were friction-laden. +- "We graduated to GA on schedule but launched with critical bugs." Graduation criteria not enforced; calendar-driven graduation. +- "Our beta has been running for 8 months with no graduation." Perpetual beta; no firm graduation criteria; graduation decision avoided. +- "Beta participants vented on Twitter before the launch." NDA missing or unclear; trust violation early erodes participant willingness. +- "The beta surfaced patterns we did not act on." Mid-beta triage missing; feedback collected but not used during the beta. +- "The GA launch surprised us." Beta was not actually validating the GA experience; cohort or feedback structure was wrong. +- "Beta participants felt ignored after providing feedback." Communication discipline missing; participants commit time and want to know it mattered. +- "We ran a closed beta that was effectively employees only." Internal-only beta; missed customer-context complexity. + +--- + +## The framework: 12 considerations for beta program management + +When designing or auditing a beta program, walk these 12 considerations. + +1. **Structured-beta, not soft-launch or kitchen-sink.** Calibrated cohort, intentional feedback, clear graduation. +2. **Beta type matches signal need.** Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. +3. **Participants match the post-launch profile.** Match the user the GA serves. +4. **Cohort size calibrated to signal need.** Smaller for bugs; larger for behavioral signal. +5. **Onboarding contract clear.** Expectations on both sides documented. +6. **Feedback channels structured.** 3-5 channels; signal not noise. +7. **Mid-beta triage active.** Feedback acted on during the beta. +8. **Communication keeps participants engaged.** Updates on what was heard and what is changing. +9. **Graduation criteria explicit.** Critical bugs cleared, friction addressed, behavioral validation, performance under load, support readiness, positive signal. +10. **Wind-down treats participants well.** Transition clarity, recognition, thank-you. +11. **Postmortem feeds practice.** Each beta improves the next. +12. **Honest decisions on graduation.** Either criteria met (graduate) or not (extend or reconsider). No tired-of-the-beta graduation. + +The output of the framework is a beta program that produces decision-grade signal, supports the GA launch, and treats participants well enough to recruit them for future betas. + +--- + +## Reference files + +- [`references/beta-type-decisions.md`](references/beta-type-decisions.md) - Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. +- [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md) - Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. +- [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md) - Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. +- [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md) - Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. +- [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md) - Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. +- [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md) - Triage cadence. Iteration discipline (what to fix during, what to defer). Communication with participants. +- [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md) - The six graduation criteria. The "tired of the beta" anti-pattern. Perpetual beta anti-pattern. +- [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md) - Graduation announcement, transition, recognition, postmortem. Treating participants well. +- [`references/common-beta-failures.md`](references/common-beta-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: betas earn their keep with structure + +A structured beta is one of the most useful product activities available. The cohort experiences the feature; the team learns from their experience; the GA launch ships with reduced uncertainty. The discipline pays back many times its cost. + +A soft-launch or kitchen-sink beta is one of the least useful. The team spends weeks running an activity that produces ambient activity without converting to learning. The GA launches with the same uncertainty the beta was supposed to address. + +The teams that earn returns on betas are the ones that take the structure seriously: cohorts calibrated to the GA profile, feedback channels designed for signal, mid-beta triage that uses what is being learned, graduation criteria that distinguish ready from tired, wind-down communication that treats participants well enough to recruit them again. + +When in doubt about whether a beta is ready, ask: are participants matched to the GA user, are feedback channels structured, is the team responding to feedback during the beta, are graduation criteria explicit and being applied honestly, will participants want to join the next beta? If yes to all of those, the beta is real. If no to any, the gap is where the beta will fail to convert participation into learning. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md b/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md new file mode 100644 index 0000000..a691d40 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md @@ -0,0 +1,230 @@ +# Beta onboarding templates + +Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. + +Onboarding sets the tone for the beta. Done well, participants enter with clear expectations and stay engaged through the program. Done badly, participants drop off, fail to provide feedback, or violate confidentiality unintentionally. + +--- + +## The welcome communication + +The first message participants receive after accepting the invitation. + +**What it covers.** + +- Welcome and thank-you for joining. +- What the beta is: the feature, the goals, what is being validated. +- Beta duration: start date, end date, what graduation looks like. +- What is expected of participants: feedback channels, cadence, format. +- What participants get: access to the feature, support, recognition or compensation, post-GA terms. +- NDA reminder where applicable. +- How to access the feature: links, accounts, configuration steps. +- Who to contact: support escalation path, beta program manager. +- First feedback prompt: what the team would like to hear about in the first week. + +**What it does not cover.** + +- A complete product manual. The participant should be able to use the feature; in-product guidance handles the detail. +- Internal team structure or politics. Participants do not need to know who reports to whom. +- Future roadmap. The beta is about this feature; future plans are separate communication. + +**Length.** 400-800 words for substantive features. Shorter for simpler features. The welcome should be readable in 3-5 minutes. + +**Tone.** Warm but professional. Beta participants are doing the team a favor; the welcome reflects that. Avoid corporate-stiff or overly casual. + +--- + +## The expectations contract + +Both sides commit to specific behaviors. + +**What the team commits to.** + +- Communication cadence: regular updates (weekly or bi-weekly). +- Response to feedback: critical issues addressed quickly; friction issues prioritized; feature requests captured. +- Transparency: participants are told what is being changed based on feedback and what is being deferred. +- Graduation criteria: explicit criteria, applied honestly. +- Post-GA continuity: participants know what their access looks like after graduation (typically continued access; sometimes special pricing). + +**What participants commit to.** + +- Feedback through the structured channels (specific channels named). +- Confidentiality where NDA applies (no public posts, screenshots, or sharing of beta features outside the participant's organization). +- Reasonable engagement: not required to use the feature daily, but expected to use it enough to provide informed feedback. +- Willingness to engage in interviews if requested (with the right to decline specific interviews). + +**The signed-or-implicit agreement.** + +- For substantial NDAs, participants sign an explicit agreement. +- For lighter beta agreements, the welcome communication may be the implicit acceptance (participation implies agreement to terms). +- The team should know which approach applies and apply it consistently. + +--- + +## NDA considerations + +When NDAs are appropriate. + +**NDA appropriate.** + +- Unannounced features (the beta is essentially confidential). +- Features that affect competitive positioning (the team does not want competitors to see the feature early). +- Design partner programs with deep collaboration on feature shaping. +- Enterprise features that touch sensitive customer data or workflows. + +**NDA not appropriate or unnecessary.** + +- Open public betas. +- Features that have already been announced. +- Features where the team welcomes public discussion (e.g., developer-tool launches that benefit from community feedback). + +**NDA enforcement reality.** + +- NDAs in open beta are essentially unenforceable. Pretending an open beta has NDA protection is theater. +- Closed-beta NDAs are enforceable but require trust; the team should not invite participants who are likely to violate confidentiality. +- For sensitive betas, the cohort selection itself is the primary control; NDAs are the legal backstop. + +**What an NDA covers.** + +- Confidentiality of the beta feature, its functionality, and the team's plans. +- Restrictions on screenshots, public posts, recordings. +- Term: typically until the feature is publicly announced or for a defined period. +- Exceptions: feedback to the team is allowed; discussion within the participant's organization is usually allowed. + +--- + +## Feedback channel access + +What participants need to know about how to give feedback. + +**Channel inventory.** + +- Structured surveys: when they will arrive, how long they take, how to access. +- Async feedback forms: link, instructions, what fields to fill. +- Interview signups: how to volunteer for interviews, what compensation if any. +- In-product feedback widget: how to use, what context it captures. +- Support routing: how beta participants flag issues to the support team. +- Slack or community: if a beta-only channel exists, how to join and what tone is expected. + +**Channel discipline.** + +- Each channel serves a different purpose. The welcome communication explains which channel is for which feedback type. +- Avoid duplicating channels (multiple Slack-like channels for the same feedback) or confusing channel mappings. + +--- + +## Support paths + +How participants escalate issues. + +**The escalation map.** + +- Bug reports: filed through the structured form or support ticketing system tagged "beta." +- Critical issues (crashes, data loss): escalation contact named explicitly; not buried in standard support queues. +- Feature questions and how-to: routed to in-product help or beta program manager. +- Account issues: standard support paths or beta-aware support reps. + +**Support team awareness.** + +- Support team should know the beta is running and how to handle beta-tagged tickets. +- Beta-tagged tickets often deserve faster response than standard tickets (the participant is doing the team a favor; long support waits damage the relationship). +- Common beta issues should be documented for the support team in advance. + +--- + +## Incentive disclosure + +What participants get for joining. + +**Common incentives.** + +- Free access to the feature post-GA for some period. +- Discounted pricing on the feature post-GA. +- Beta-only feature flags or capabilities preserved post-GA. +- Recognition (named in changelog, on website, in launch communications) with consent. +- Gift cards, swag, or other compensation. +- Direct access to product team during the beta (some participants value this most). + +**Disclosure discipline.** + +- The welcome communication names the incentives explicitly. No surprise reveals at the end. +- Different participants may have different incentive packages (design partners often get more); each participant knows their package. +- The incentives match the commitment level. Light betas have light incentives; design partner programs have substantive ones. + +**The "no incentive" pattern.** + +- Some betas offer no formal incentive beyond access to the feature. +- This works for high-engagement audiences (developers, enthusiasts) where access itself is the incentive. +- It does not work for audiences where the time investment is significant; participants need a reason to engage substantively. + +--- + +## First-week onboarding + +What happens after the welcome message. + +**The first week's actions.** + +- Day 1: welcome arrives; participants get access; first-day checklist (set up, access feature, complete profile if applicable). +- Day 2-3: first feedback prompt arrives. Could be an in-product widget triggered after first usage, or an email asking specifically about the first impression. +- End of week 1: brief check-in. Are participants able to access? Have they used the feature? Any friction with onboarding itself? + +**Onboarding-specific friction.** + +- Beta participants who cannot access the feature in the first 24-48 hours often disengage. Access friction is the most consequential onboarding failure. +- Documentation that does not match the actual experience (because the docs were written for a slightly different feature version) frustrates early. +- Missing context about what the feature is for. Participants who do not know what the feature is meant to accomplish use it tentatively or not at all. + +--- + +## Onboarding for different beta types + +Different beta types warrant different onboarding intensity. + +**Lightweight onboarding (open beta, RC validation).** + +- Email welcome with key information. +- Self-service access. +- In-product guidance handles most setup. + +**Standard onboarding (closed beta, structured cohort).** + +- More substantial welcome email. +- Optional onboarding call for participants who request it. +- Beta program manager available via direct channel. + +**Deep onboarding (design partner program, complex feature).** + +- Onboarding call with each participant or company. +- Custom configuration support. +- Direct channel to product team for ongoing collaboration. + +The onboarding intensity matches the beta type. Heavyweight onboarding for an open beta with 5,000 participants is impossible; lightweight onboarding for a 5-partner design program under-invests in the relationships. + +--- + +## Common onboarding failures + +**Vague expectations.** Participants do not know what feedback is wanted; ad-hoc venting fills the channels. + +**Missing NDA where appropriate.** Beta features get screenshotted on social before the team is ready. + +**Missing support path.** Participants hit issues, do not know who to contact, churn out of the beta. + +**No incentive clarity.** Participants feel underrecognized; engagement decays. + +**Welcome communication too long or too short.** Too long: participants do not read; too short: participants miss critical context. + +**Access friction in first 24-48 hours.** Participants cannot get into the feature; many disengage permanently. + +**Onboarding intensity mismatched to beta type.** Heavy onboarding for an open beta wastes effort; light onboarding for a design partner program under-invests. + +--- + +## Methodology-level choices that stay in the public skill + +The welcome communication structure. The expectations contract for both sides. NDA considerations. Feedback channel access. Support paths. Incentive disclosure. First-week onboarding. Onboarding by beta type. Common failures. + +## Implementation choices that stay internal + +Specific welcome email templates. Specific NDA boilerplate. Specific support routing automation. Specific incentive packages and approval workflows. The team's own conventions for onboarding intensity. These vary by team and beta type. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md b/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md new file mode 100644 index 0000000..e835ce5 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md @@ -0,0 +1,239 @@ +# Beta-to-GA graduation criteria + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. + +Graduation is the decision that distinguishes a structured beta from beta theater. Honest graduation criteria, applied honestly, separate "ready for GA" from "we are tired of running the beta." Defining the criteria explicitly upfront prevents calendar-driven graduation decisions later. + +--- + +## The six graduation criteria + +The criteria that should be met before graduating from beta to GA. + +### 1. Critical bugs cleared + +**The criterion.** No known crashes, data loss, or core-flow failures. + +**The validation.** Bug tracker shows no open critical issues. The beta cohort has not reported new critical issues in the past 1-2 weeks. + +**The exception.** Some critical issues may be acceptable if they affect a tiny segment that the GA can either exclude or address with documentation. Decisions to graduate with known issues should be explicit. + +### 2. Friction issues addressed or accepted + +**The criterion.** Friction issues are either fixed before GA or documented as known limitations the team is choosing not to address pre-GA. + +**The validation.** Each friction issue from the beta has a disposition: fixed, fix-in-progress (with timeline), accepted-for-now (with rationale), accepted-permanently (with rationale). + +**The honest disposition.** "Accepted for now" is honest if the team plans to address post-GA. "Accepted permanently" is honest if the team has decided the friction is not worth the engineering cost. Hidden friction that the team hopes nobody will notice is not honest. + +### 3. Behavioral validation + +**The criterion.** Beta participants are using the feature in patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). + +**The validation.** Usage data from the beta cohort shows the feature being used in the ways the design assumed. Significant deviations are investigated; either the design is adjusted, or the GA experience is modified to support the actual usage pattern. + +**The unexpected-pattern handling.** + +- Pattern A: most beta participants are using the feature in a different way than the design assumed. The design is wrong; iterate before GA. +- Pattern B: a subset of participants is using the feature in an unexpected way that suggests an additional use case. Capture for post-GA expansion; do not delay GA. +- Pattern C: participants are not using the feature much at all. The feature may not be solving a real problem; reconsider whether to ship. + +### 4. Performance under load + +**The criterion.** The feature performs adequately at the scale GA will produce. + +**The validation.** Performance testing under projected GA load. Beta cohort performance was acceptable; the GA scale projection has been tested. + +**The infrastructure-validation focus.** For features where scale is the primary concern (data-processing features, real-time features, multi-tenant features), this criterion is the central one. RC betas often exist primarily to validate this. + +### 5. Documentation and support readiness + +**The criterion.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work. + +**The validation.** + +- Help docs match the feature as it will ship at GA. +- Support team has been briefed and has handled at least the simulated beta-tier ticket volume. +- Common issues are documented for the support team's reference. +- Escalation paths from support to engineering are tested. + +**The skip risk.** Teams often graduate before docs and support are ready. The GA launch then catches the support team off-guard; tickets pile up; users have a worse experience than they would have with proper readiness. + +### 6. Positive signal sufficient + +**The criterion.** Beta feedback is net-positive enough to launch with confidence. + +**The validation.** + +- Survey signal shows positive sentiment among beta participants. +- Behavioral signal shows continued usage (participants are not just trying the feature once). +- Participants would recommend the feature to others. + +**The "sufficient" calibration.** Not all participants need to be delighted. A substantial majority finding value, with the dissenting voices understood (segment misfit, expectations mismatch, unfixable friction), is sufficient. A divided cohort with no clear majority signal is not. + +--- + +## The "tired of the beta" anti-pattern + +Graduation that happens because the team wants to be done with the beta. + +**The pattern.** + +- Beta has run for the planned duration. +- Some criteria are met; some are not. +- The team graduates anyway because "we have to ship at some point" or "the beta cannot run forever." + +**Why it fails.** + +- Unmet criteria mean the GA launches with known issues that are not yet addressed or acknowledged. +- Support, marketing, and customer success encounter problems the beta would have caught if extended. +- Trust degrades: customers experience friction the beta participants reported but the team did not fix. + +**The cure.** + +- Either extend the beta until criteria are met. +- Or graduate with explicit acknowledgment of the unmet criteria (known issues, deferred work). +- Or reset the beta if significant changes are needed. + +The discipline: the graduation decision is criteria-driven, not calendar-driven. Calendar pressure can inform whether to ship a smaller scope, but it should not produce graduation despite unmet criteria. + +--- + +## The perpetual beta anti-pattern + +Graduation that does not happen because the beta drifts indefinitely. + +**The pattern.** + +- Beta runs without firm graduation criteria. +- Issues keep surfacing; the team keeps fixing; the beta extends. +- 6 months later, the beta is still running. The "perpetual beta" branding becomes a strategic stance ("everything is always evolving"). +- The GA commitment is avoided. + +**Why it fails.** + +- Beta participants experience indefinite uncertainty about the feature's status. +- The team avoids the discipline of GA readiness; the feature stays in a less-mature state than it could be. +- Marketing, support, and customer success cannot operate around a beta-forever feature. +- Stakeholder trust degrades: the team is not shipping. + +**The cure.** + +- Force the graduation decision. Either the criteria are met (graduate) or they are not (decide what would make them met, set a timeline, commit). +- "Perpetual beta" as a strategic stance is rare and usually a rationalization. +- Some features genuinely need extended-beta status for valid reasons (regulatory complexity, unusual scale validation); these should be exceptions documented explicitly, not the default. + +--- + +## Honest graduation patterns + +When graduation criteria are mostly but not fully met. + +**Graduation with known issues.** + +- Some criteria fully met; one or two have known gaps. +- Graduate with explicit acknowledgment: "We are shipping with X known limitation; documented; will address in [timeline]." +- Communicate the known issues to support, marketing, customer success. +- Customers who hit the known issue are not surprised; they were warned. + +**Graduation with extended monitoring.** + +- Behavioral signal not fully validated due to cohort limitations. +- Graduate with monitoring infrastructure that surfaces issues at GA scale. +- Plan for fast iteration if monitoring catches issues post-GA. + +**Graduation with phased rollout.** + +- All criteria met for a subset of users; less certain for broader users. +- Graduate to the validated subset first; expand the rollout in phases. + +These patterns preserve graduation discipline while accommodating real-world constraints. + +--- + +## When NOT to graduate + +Conditions that warrant extending or resetting the beta. + +**Not to graduate.** + +- Critical bugs are unaddressed. +- Major friction issues affect mainline usage. +- Behavioral signal contradicts the design assumptions. +- Performance under projected load is inadequate. +- Documentation and support are not ready. +- Beta sentiment is divided without clear positive signal. + +**The honest extension.** + +- Acknowledge the gap explicitly. +- Define what would close the gap. +- Set a new timeline. +- Communicate to participants and stakeholders. + +**The reset.** + +- If the gap requires significant feature changes, end the current beta and start a new one with the changed feature. +- Do not blend "old beta" and "new feature" data. + +--- + +## Graduation decision-making + +Who decides graduation and how. + +**The decision-maker.** Typically the product manager who owns the feature, with input from engineering lead, design lead, and beta program manager. + +**The decision process.** + +- Beta program manager prepares a graduation review document: status against each criterion, known issues, recommendation. +- Decision meeting (60-90 minutes): review the document, discuss any open questions, make the decision. +- Decision recorded explicitly: graduate, extend, or reset. + +**Stakeholder visibility.** The decision is communicated to stakeholders (executives, marketing, sales, customer success) before participants are notified. + +**Graduation timing.** Once the decision is made, graduation typically takes 1-2 weeks to execute (final code, marketing prep, support readiness, participant communication). + +--- + +## Graduation criteria for different beta types + +The criteria adapt to the beta type. + +**Closed beta with calibrated cohort.** All six criteria apply. The cohort is small enough to validate behavioral signal directly. + +**Open beta with large volume.** Behavioral signal validates at scale. Critical bugs and performance criteria are more central. Documentation and support readiness scale with the open-beta visibility. + +**RC validation.** Performance under load is the central criterion. Other criteria should already have been met in prior alpha or beta stages. + +**Design partner program.** The criteria apply but graduation often happens incrementally (specific design partners moving to GA terms while the program continues with new partners). Less of a single graduation moment. + +**Internal beta.** Customer-context criteria (behavioral validation, support readiness for external) may need to be validated at GA rather than during beta. Honest disclosure: the beta did not fully validate the customer experience. + +--- + +## Common graduation failures + +**Calendar-driven graduation.** Graduate when the planned duration ends regardless of criteria. + +**Criteria not defined upfront.** Graduation decision happens without explicit criteria; subjective decision. + +**Hidden known issues.** Graduate with known issues that are not surfaced; customers and support discover them later. + +**Perpetual beta.** Indefinite extension; graduation decision avoided. + +**Premature graduation.** Graduate before behavioral signal has emerged or critical bugs are fully cleared. + +**No stakeholder notification.** Graduation happens; support, marketing, customer success encounter the GA launch unprepared. + +**No participant communication about graduation.** Beta participants are not told about graduation timing or what changes for them. + +--- + +## Methodology-level choices that stay in the public skill + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. Honest graduation patterns. When not to graduate. Graduation decision-making. Graduation criteria for different beta types. Common failures. + +## Implementation choices that stay internal + +Specific graduation review document templates. Specific decision-meeting formats. Specific stakeholder notification workflows. The team's own conventions for graduation timing. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md b/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md new file mode 100644 index 0000000..0995f48 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md @@ -0,0 +1,228 @@ +# Beta type decisions + +Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. + +Beta type is the upstream decision that constrains everything downstream: who participates, what feedback channels make sense, what graduation looks like. Getting the type wrong makes the rest of the program harder. + +--- + +## Closed vs open + +The cohort-control axis. + +**Closed beta.** Invite-only. Participants are selected by the team based on criteria. Cohort is bounded. + +**Strengths.** + +- Calibrated cohort: the team knows who is in the beta and can match participants to the GA user profile. +- Quality of feedback: invited participants typically engage more substantively than self-selected open-beta users. +- NDA enforceability: closed cohorts can sign NDAs; open cohorts usually cannot. +- Synthesis tractability: bounded cohort means feedback volume is manageable. + +**Weaknesses.** + +- Recruiting overhead: identifying and inviting participants is real work. +- Limited diversity: the cohort reflects the team's recruiting choices; gaps in selection produce gaps in feedback. +- Slower feedback volume: smaller cohorts produce less total feedback. + +**Open beta.** Anyone can join. Cohort is self-selecting. + +**Strengths.** + +- Volume: large numbers of participants quickly. +- No recruiting overhead: participants opt in. +- Marketing value: open betas can build pre-launch audience awareness. + +**Weaknesses.** + +- Self-selection bias: early adopters and enthusiasts skew the cohort; their feedback may not represent the broader target user. +- Signal-to-noise ratio: most participants do not provide actionable feedback; the team must mine signal from volume. +- NDA difficulty: open cohorts cannot reasonably enforce NDAs; the feature is essentially public. + +--- + +## Alpha vs beta vs RC + +The polish axis. + +**Alpha.** + +- Very early. Significant bugs expected. +- Internal users or trusted partners only. +- Goal: surface fundamental issues before broader exposure. +- Feedback orientation: bug discovery, fundamental flow validation. + +**Beta.** + +- More polished. Major bugs caught; remaining issues are friction or edge cases. +- Broader cohort. External customers in calibrated cohorts. +- Goal: validate the feature works for real users in real contexts. +- Feedback orientation: usage patterns, friction, behavioral signal, edge cases. + +**RC (release candidate).** + +- Essentially launch-ready. Production-grade quality expected. +- Cohort can be large (open beta or extended beta). +- Goal: last validation before GA, performance at scale, infrastructure readiness. +- Feedback orientation: scale issues, infrastructure issues, last-mile polish. + +**The progression.** Many features pass through all three (alpha → beta → RC) before GA. Some skip alpha (sufficient internal testing) or skip RC (the beta is the last validation). The decision depends on feature complexity and risk tolerance. + +--- + +## Internal vs external + +The audience axis. + +**Internal beta.** Only employees use the feature. + +**Strengths.** + +- Fast feedback: employees are easy to recruit and follow up with. +- High engagement: employees usually feel some ownership of company products. +- NDA simplicity: confidentiality is implicit. + +**Weaknesses.** + +- Missing customer context: employees experience features differently than customers (familiarity, infrastructure context, motivations). +- Bias toward team-known patterns: employees use products in ways the team designed for; customers often use products differently. +- Limited signal: internal-only cannot validate customer-context complexity. + +**External beta.** Real customers use the feature. + +**Strengths.** + +- Real customer experience: feedback reflects how customers actually use the product. +- Behavioral signal: usage patterns from real customers inform GA decisions. +- Trust building: customers who beta-test become advocates. + +**Weaknesses.** + +- Requires customer relationship: cannot just turn the feature on for employees. +- Recruiting overhead: identifying willing customers and managing the cohort. +- Risk: bugs reaching customers can damage trust if not handled well. + +**The combination.** Most strong betas pass through both: internal alpha, then external beta. Some skip internal (when internal use cases differ enough from customer use cases that internal validation is misleading). + +--- + +## Time-bounded vs open-ended + +The duration axis. + +**Time-bounded beta.** A defined end date. Common durations: 4 weeks, 6 weeks, 8 weeks, 12 weeks. + +**Strengths.** + +- Forces the graduation decision. The end date arrives; the team must decide ready or not. +- Clarity for participants: they know how long they are committing. +- Resource bounding: the team's beta-running effort is bounded. + +**Weaknesses.** + +- Calendar pressure can force premature graduation: "we are at the end date so we are graduating" regardless of signal. +- Some signals need longer to surface: behavioral patterns may not be visible in 4 weeks. + +**Open-ended beta.** No defined end. The beta runs until the team decides to graduate. + +**Strengths.** + +- Signal-driven graduation: the team graduates when the criteria are met, regardless of calendar. +- Allows long-running validation: behavioral signal can develop over months. +- Suits design partner programs: ongoing relationships rather than time-bounded cohorts. + +**Weaknesses.** + +- Beta-purgatory risk: beta runs indefinitely because nobody forces the graduation decision. +- Participant fatigue: open-ended commitments without clear duration drain engagement. +- Resource drain: the team's beta-running effort is open-ended. + +**The default.** Most betas should be time-bounded. Open-ended is appropriate for design partner programs and specific extended-validation scenarios. + +--- + +## The combination decision + +How to choose across the four axes. + +**Worked combinations.** + +**Standard structured beta:** closed + beta + external + time-bounded (6-8 weeks). + +- Use when: shipping a meaningful feature that needs validation before GA. Most common combination. + +**Alpha:** closed + alpha + internal + open-ended (typically 2-6 weeks of internal testing before external alpha). + +- Use when: very early feature; need to surface fundamental issues before exposing customers. + +**Design partner program:** closed + alpha or beta + external + open-ended. + +- Use when: building a feature with deep customer involvement; small set of partner customers (3-10) collaborating closely on shaping the feature. + +**Open early access:** open + beta or RC + external + time-bounded (4-12 weeks). + +- Use when: pre-GA marketing matters; the feature is sufficiently polished that early access can build audience; team can handle the volume. + +**RC validation:** open or closed + RC + external + time-bounded (2-4 weeks). + +- Use when: the feature is essentially launch-ready; need last validation at scale or in the production environment. + +**Internal-only RC:** closed + RC + internal + time-bounded. + +- Use when: the feature is for internal users (e.g., admin tools used by support team), or when external testing is impractical for the type of feature. + +--- + +## When the combination decision goes wrong + +Common mismatches. + +**Open + alpha.** Open cohorts on an alpha-stage feature exposes customers to bugs the team has not caught. Damages trust. Cure: alpha should be closed; open up at beta stage when the feature is more polished. + +**Closed + RC.** Closed RCs miss the at-scale validation that RCs are meant to provide. The cohort is too small to surface scale issues. Cure: RCs are usually open or large-closed. + +**External + alpha + open-ended.** External customers commit to an alpha that has no end date and many bugs. Engagement decays. Cure: alpha should be internal or trusted-partner only; external alpha should be time-bounded and limited. + +**Open + beta + open-ended.** Volume cohort with no end date. The beta runs forever; participants lose interest; the team cannot synthesize. Cure: time-bound the beta; force graduation decision. + +--- + +## Beta type for specific contexts + +Common contexts and the typical type combinations. + +**B2B SaaS feature launch.** Closed + beta + external + time-bounded. 20-200 participants from existing customer base, 6-8 weeks. + +**Consumer product launch.** Open + beta + external + time-bounded (or open + RC). 1,000-10,000+ participants, 4-8 weeks. Marketing value is part of the rationale. + +**Enterprise platform major release.** Closed + alpha + design-partner + open-ended initially, then closed + beta + extended cohort + time-bounded for validation. + +**Developer-tool launch.** Open + beta + external + time-bounded, with public roadmap and community feedback channels. + +**Internal tool launch.** Closed + alpha or beta + internal + time-bounded. The cohort is the internal users who will use the tool post-GA. + +**Compliance-impacting feature.** Closed + extended beta + external + carefully selected design partners. The validation needs to surface compliance edge cases before GA. + +--- + +## Common beta-type failures + +**Defaulting to soft-launch.** Skipping beta-type decisions and just turning the feature on for some users. Decide the type explicitly. + +**Defaulting to open beta for everything.** Open volume substituted for calibrated cohorts. Open is right for some contexts; not for all. + +**Mismatching alpha/beta/RC to feature polish.** Calling something "beta" when it is alpha (too many bugs); calling something "RC" when it is beta (not yet production-grade). + +**Internal-only when external context matters.** Validates an internal experience that does not match what customers will encounter. + +**Open-ended without graduation criteria.** Beta drifts into perpetual beta because no firm end was set. + +--- + +## Methodology-level choices that stay in the public skill + +The four axes (closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended). Strengths and weaknesses per axis. Worked combinations. Common mismatches. Beta type for specific contexts. Common failures. + +## Implementation choices that stay internal + +Specific platform feature-flagging configurations. Specific recruitment platforms and processes. Specific NDA templates. Specific time-bounding workflows. The team's own conventions for beta-type decisions in different contexts. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md b/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md new file mode 100644 index 0000000..8f77cc2 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md @@ -0,0 +1,231 @@ +# Beta wind-down communication + +Graduation announcement, transition, recognition, postmortem. Treating participants well. + +The beta's wind-down is its closing impression. Done well, participants leave the beta engaged and willing to participate in future betas. Done badly, participants feel discarded after providing significant feedback. + +--- + +## The graduation announcement + +Communication to participants when the beta graduates. + +**Timing.** 1-2 weeks before graduation, with confirmation at graduation. + +**Content.** + +- The feature is graduating to GA. Specific date. +- What changes for participants. +- What does not change. +- Recognition or thank-you for participation. +- Information about post-GA support, pricing, or special terms. +- Any beta-specific features or terms that will not carry to GA. + +**Tone.** Warm, appreciative. Participants invested time; the announcement reflects that. + +**Length.** 300-600 words. Long enough to cover the necessary information; short enough to be readable. + +--- + +## What changes for participants at graduation + +**Continued access.** Most beta participants retain access to the feature post-GA. The beta was their preview; GA continues their use. + +**Pricing transitions.** If the feature has paid tiers, participants need to know: + +- Does beta access include free use of the feature post-GA for some period? +- Does the feature require an upgraded plan for full access? +- Are there special pricing terms for beta participants (early-bird discount, lifetime grandfathering, etc.)? + +**Feature stability.** Communicate what level of stability participants should expect post-GA. Beta features sometimes have rough edges; GA implies stability commitments. + +**Support transition.** Beta-aware support routing typically ends at GA. Participants now use standard support channels. + +**Beta-only features.** Some features in the beta may not make GA (deprecated, simplified, removed). Participants who relied on those features need clear communication about alternatives. + +--- + +## Recognition + +Beta participants invested time providing feedback. Recognition matters. + +**Forms of recognition.** + +- **Named in changelog or launch communications** (with consent). +- **Gift cards or compensation** for substantial time investment. +- **Swag** for closed-beta participants. +- **Advance access to future betas.** +- **Direct thank-you from product team**, often via personal email. +- **Public acknowledgment** in marketing or community materials. + +**Calibration.** + +- Light betas: direct thank-you, possibly modest swag. +- Standard betas: thank-you, swag, post-GA continued access on favorable terms. +- Design partner programs: substantial recognition, sometimes including case studies, named partnerships, financial compensation. + +**The discipline.** Recognition matches the participant's investment. Light recognition for a heavy commitment feels dismissive; heavy recognition for a light commitment is unnecessary. + +--- + +## The post-beta survey + +A final feedback collection at graduation. + +**Purpose.** Capture overall reflections on the beta experience and the feature. + +**Content.** + +- Overall feature satisfaction. +- Likelihood to continue using post-GA. +- Likelihood to recommend. +- What worked well in the beta program (process feedback, not feature feedback). +- What could be improved in future betas. +- Optional open-ended reflections. + +**Length.** 5-10 questions, 5-10 minutes to complete. + +**Why it matters.** The post-beta survey closes the loop with participants and informs the team's beta-program practice. The process feedback is particularly valuable: future betas improve based on past feedback. + +--- + +## The beta postmortem + +Internal review of what the beta produced. + +**Timing.** Within 1-2 weeks of graduation. + +**Participants.** Beta program manager, product manager, engineering lead, design lead, customer success lead, support lead. + +**Content.** + +- What was learned from the beta? (Patterns, behavioral validation, friction discovery.) +- What changed in the GA launch as a result? +- What worked well in the beta program (process)? +- What did not work? What would the team do differently next time? +- What patterns recur across multiple betas? Are there lessons for the broader practice? + +**Output.** A short postmortem document. Surfaces lessons. Informs future betas. + +**Why it matters.** Beta programs improve through accumulated learning. Without postmortems, the team repeats the same mistakes; with postmortems, the practice gets sharper over time. + +--- + +## Recruiting for future betas + +The wind-down is a recruiting moment for future betas. + +**The pattern.** Participants who had a good beta experience are likely to participate in future ones. The wind-down communication can include an invitation: would they like to be considered for future betas? + +**The benefits.** + +- Builds a roster of engaged beta participants for future programs. +- Reduces recruiting overhead for future betas. +- Strengthens the participant relationship. + +**The discipline.** Do not over-commit; future betas should not be promised in ways that are not honored. The invitation is to be considered, not a guarantee. + +--- + +## Handling beta-only features that do not make GA + +Sometimes beta features include capabilities that are removed or simplified at GA. + +**Why it happens.** + +- The feature scope was reduced based on beta findings. +- Some capabilities did not perform well enough to ship at GA. +- The team learned the capability was not load-bearing. + +**The communication.** + +- Surface the change explicitly. Do not silently remove. +- Explain the reasoning where appropriate. +- Provide alternatives or workarounds for participants who relied on the removed capability. +- Acknowledge the impact on participants. + +**The participant impact.** Some participants may push back; their usage assumed the capability would persist. The team must decide whether to extend support, offer migration help, or accept the participant churn. + +--- + +## Special cases: extended beta + +Some betas extend beyond their planned duration. + +**Communication for extension.** + +- Tell participants when the extension is decided, not when the original end date passes. +- Explain why the extension is needed. +- Give a specific new end date. +- Acknowledge the participant impact (they committed to the original timeline). +- Provide an option to opt out if the extension is significant. + +**Avoid.** + +- Silent extensions where the planned end passes without acknowledgment. +- Multiple extensions that erode the timeline credibility. +- Extensions framed as "no big deal" when they affect participants' ongoing time investment. + +--- + +## Special cases: beta cancellation + +Sometimes the team decides not to graduate the feature to GA. + +**Why it happens.** + +- The beta revealed the feature does not work as intended. +- Strategic shift redirected resources. +- The feature would compete poorly at GA scale. + +**The communication.** + +- Be honest about the cancellation. +- Acknowledge the participants' time investment. +- Explain (at appropriate level of detail) why the cancellation. +- Discuss what happens to participants' beta data, configurations, etc. +- Recognize the participation despite the cancellation. + +**The participant impact.** Cancellation can frustrate participants who invested time. Honest communication and good recognition mitigate the impact. + +--- + +## Long-term participant relationships + +Beta participants represent ongoing relationships, not transactional interactions. + +**The relationship investment.** + +- Participants who had a good beta experience may become advocates, references, case study subjects. +- Future product strategy benefits from continued conversation with beta alumni. +- Customer success can use beta participation as relationship signal. + +**The maintenance.** Periodic check-ins with notable beta participants strengthen relationships even outside formal beta programs. Light-touch communication (annual newsletter, occasional product updates, personalized outreach for major launches) maintains the connection. + +--- + +## Common wind-down failures + +**Silent graduation.** Beta participants discover graduation through the public launch announcement rather than through advance communication. + +**Vague transition information.** Participants do not know what changes for them; uncertainty produces churn. + +**Insufficient recognition.** Heavy participation rewarded with thin thank-you; participants feel dismissed. + +**Missing post-beta survey.** Process feedback is lost; future betas do not improve. + +**No postmortem.** Internal lessons are lost; the team repeats mistakes. + +**Surprise feature removals.** Beta-only features removed without warning; participants discover at GA that capabilities they relied on are gone. + +**No invitation to future betas.** The relationship ends at graduation; future betas restart recruitment from scratch. + +--- + +## Methodology-level choices that stay in the public skill + +The graduation announcement structure. What changes for participants. Recognition forms and calibration. The post-beta survey. The beta postmortem. Recruiting for future betas. Handling beta-only feature removals. Extended betas. Beta cancellations. Long-term relationships. Common failures. + +## Implementation choices that stay internal + +Specific graduation announcement templates. Specific recognition packages and approval. Specific postmortem templates. Specific CRM tracking of beta alumni. The team's own conventions for relationship maintenance. These vary by team. diff --git a/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md b/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md new file mode 100644 index 0000000..1457a9e --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md @@ -0,0 +1,207 @@ +# Cohort sizing patterns + +Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. + +Cohort size is a calibration decision, not a maximize-volume decision. Each beta has a specific signal need; the right cohort size is the smallest that produces that signal reliably. + +--- + +## Saturation patterns by feedback type + +Different kinds of feedback saturate at different cohort sizes. + +**Critical bugs (crashes, data loss, broken core flows).** + +- Saturate fast: most surface in the first 1-2 weeks with 20-30 participants. +- Beyond ~50 participants, additional volume produces few new critical bugs. +- The cohort size for bug discovery: 20-50 participants is usually sufficient. + +**Friction issues (workflow interruptions, confusing flows, slow performance in specific cases).** + +- Saturate moderately: most surface in 2-4 weeks with 50-100 participants. +- Volume helps surface friction in less-common usage patterns. +- The cohort size for friction discovery: 50-200 participants typical. + +**Behavioral patterns (how users actually use the feature, what flows they follow, what features they ignore).** + +- Saturate slowly: 4-8 weeks with 100-500 participants needed for clear patterns. +- Patterns require usage volume; small cohorts may not generate enough usage to see patterns. +- The cohort size for behavioral signal: 100-500+ participants typical. + +**Edge cases (unusual configurations, rare usage contexts, specific environment combinations).** + +- Saturate very slowly: 500+ participants needed; some edge cases never surface in beta and are discovered post-GA. +- Volume is the only way to surface low-frequency edge cases. +- The cohort size for edge case discovery: 500-5,000+ participants; even at this scale, rare cases may slip through. + +**Performance under load (scale-related issues, infrastructure constraints, concurrent-use issues).** + +- Saturate when cohort exceeds the load threshold the issue requires. +- 1,000-10,000+ participants for at-scale validation. +- Often the central goal of RC betas. + +--- + +## Sizing decisions for different beta goals + +The cohort size matches what the team needs to learn. + +**Goal: Catch critical bugs before GA.** + +- Cohort size: 20-50 participants. +- Duration: 2-4 weeks. +- Closed cohort, calibrated to GA user profile. +- Most critical bugs surface fast; beyond this, returns diminish. + +**Goal: Validate behavioral assumptions about how users will use the feature.** + +- Cohort size: 100-300 participants. +- Duration: 4-8 weeks. +- Closed cohort with variety across usage patterns. +- Behavioral patterns need usage volume to emerge clearly. + +**Goal: Validate product-market fit assumptions for a major new feature.** + +- Cohort size: 200-500 participants. +- Duration: 8-12 weeks. +- Closed cohort spanning segments. +- Long enough duration to see retention and continued usage, not just initial engagement. + +**Goal: Validate at-scale infrastructure for a launch.** + +- Cohort size: 1,000-5,000+ participants. +- Duration: 4-8 weeks. +- Often open beta or large closed RC. +- Volume is the point; calibration is less important than scale. + +**Goal: Build a design partner program for ongoing collaboration.** + +- Cohort size: 3-10 partners. +- Duration: open-ended (months to years). +- Highly calibrated cohort with strong relationships. +- Depth over breadth; the program is qualitative collaboration, not at-scale validation. + +**Goal: Generate pre-launch marketing and audience.** + +- Cohort size: 1,000-10,000+ participants. +- Duration: 4-12 weeks. +- Open beta with marketing-driven recruitment. +- The cohort serves both validation and pre-launch buzz. + +--- + +## The size-matches-signal principle + +The cohort should be the smallest size that produces the signal the team needs. + +**Why "smaller is better when calibrated."** + +- Smaller cohorts produce more synthesizable feedback. The team can read every transcript, review every survey response, follow up with every participant who reports an issue. +- Smaller cohorts make participant relationships stronger. Each participant feels seen; engagement is higher. +- Larger cohorts produce volume that can drown signal. The team cannot synthesize 5,000 pieces of feedback as well as 50. + +**When larger is necessary.** + +- The team needs at-scale validation (load, concurrent users, edge cases). +- The team needs marketing reach. +- The team needs behavioral signal that requires substantial usage volume. + +**The discipline.** Default to the smallest cohort that produces the needed signal. Justify any larger size against specific signal needs. + +--- + +## Cohort size and feedback channel design + +Larger cohorts require different feedback channel design than smaller ones. + +**For cohorts of 5-50.** + +- Direct channels work: email, dedicated Slack, structured interviews. +- The team can engage with each participant individually. +- Synthesis can include reviewing all feedback. + +**For cohorts of 50-500.** + +- Mixed channels: structured surveys + sample interviews + in-product feedback widgets. +- Sampling required for synthesis: review all surveys, sample interviews and tickets. + +**For cohorts of 500-5,000.** + +- Aggregated channels: in-product feedback widgets, support ticket aggregation, automated surveys. +- Heavy sampling: review aggregate patterns, sample individual feedback. + +**For cohorts of 5,000+.** + +- Volume aggregation: NPS-style scoring, automated categorization, statistical analysis of usage patterns. +- Individual feedback rarely reviewed; patterns are the signal. + +The implication. Beta planning includes feedback channel design appropriate to cohort size. Mismatches (small cohort with aggregated channels, or large cohort with direct channels) produce friction. + +--- + +## Adjusting cohort size mid-beta + +Sometimes the team realizes mid-beta that the cohort is wrong-sized. + +**Cohort too small.** + +- Symptom: feedback volume is insufficient to see patterns. +- Cure: open recruitment for additional participants, applying the same selection criteria. +- Caution: late additions have less time in the beta; their feedback covers less of the beta period. + +**Cohort too large.** + +- Symptom: feedback volume overwhelms synthesis capacity; the team is reactive rather than analytical. +- Cure: usually do not reduce; instead, scale up synthesis capacity (more reviewers, more aggregation tooling). Reducing cohort feels like a betrayal to participants. +- Prevention: better sizing decision upstream. + +**Cohort skewed.** + +- Symptom: feedback patterns reflect skew (one segment over-represented). +- Cure: targeted recruitment to balance the cohort, or explicit acknowledgment of skew in synthesis. +- The cohort cannot always be re-balanced quickly; sometimes the synthesis adjusts for the skew rather than the cohort. + +--- + +## Cohort and beta duration + +Cohort size and duration interact. + +**Short beta (2-4 weeks).** Smaller cohort works because feedback saturates faster on critical issues. 20-100 participants typical. + +**Medium beta (4-8 weeks).** Mid-size cohort matches the duration. 50-300 participants typical. + +**Long beta (8+ weeks).** Larger cohort works because behavioral signal needs duration. 100-1,000+ participants. + +**The mismatch failures.** + +- Long beta with small cohort: insufficient volume; the duration produces no proportional signal. +- Short beta with very large cohort: insufficient time; the volume produces no proportional learning. + +The matching. Beta duration and cohort size both follow from signal need; they should be consistent. + +--- + +## Common cohort sizing failures + +**Defaulting to "more is better."** Large cohorts where small calibrated ones would produce stronger signal. + +**Sizing without reference to signal need.** Cohort size set arbitrarily; team cannot defend why this size. + +**Cohort size mismatched to duration.** Small cohort in a long beta produces sparse signal; large cohort in a short beta produces noise. + +**Cohort size mismatched to feedback channel design.** Direct channels with too many participants overwhelm; aggregated channels with too few participants under-utilize. + +**Mid-beta cohort changes without synthesis adjustment.** Cohort grows or shrinks; the synthesis approach does not adapt. + +**Confusing volume with signal.** Larger cohort numbers reported as success; the team did not actually learn proportionally more. + +--- + +## Methodology-level choices that stay in the public skill + +The saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. Cohort size and feedback channel design alignment. Adjusting cohort size mid-beta. Cohort and beta duration interaction. Common failures. + +## Implementation choices that stay internal + +Specific recruitment automation tooling. Specific aggregation tooling for large cohorts. Specific synthesis processes for different cohort sizes. The team's own conventions for sizing within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md b/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md new file mode 100644 index 0000000..204a1c2 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md @@ -0,0 +1,205 @@ +# Common beta failures + +Ten-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most beta failures share a single root, which is treating beta as ceremony rather than as decision input. + +--- + +## Failure 1: Our beta produced no signal + +**Symptom.** The beta ran. The team has nothing actionable to show for it. The GA launch will happen with the same uncertainty the beta was supposed to address. + +**Diagnosis.** Soft-launch pattern. No structured selection, no defined feedback collection, no graduation criteria. + +**Cure.** Restructure the beta. Define the cohort, channels, criteria, and triage cadence. If the current beta cannot be saved, plan a more structured beta for the next feature. + +**Prevention.** Plan beta structure at the start, not after the beta has been running. + +--- + +## Failure 2: Our beta has 5,000 users and we cannot synthesize + +**Symptom.** Open beta or large cohort. Volume is high. The team is reactive rather than analytical. Synthesis cannot keep up. + +**Diagnosis.** Kitchen-sink. Cohort too large for the structured signal the team needs. + +**Cure.** Two paths. Scale up synthesis capacity (more reviewers, aggregation tooling). Or reduce the active cohort by focusing structured channels on a calibrated subset (e.g., select 200 active participants for interviews; let the rest contribute through aggregated channels). + +**Prevention.** Size cohort to match synthesis capacity. Larger cohorts require aggregated feedback infrastructure. + +--- + +## Failure 3: Our beta participants never gave feedback + +**Symptom.** Few survey responses. Few in-product widget submissions. Few interview signups. The cohort is silent. + +**Diagnosis.** Onboarding contract was unclear or feedback channels were friction-laden. Participants did not know what was expected or could not easily give feedback. + +**Cure.** Re-engage. Send specific, prompted requests for feedback. Make the channels easier (in-product prompts, simpler forms). Communicate what is being heard from those who do respond. + +**Prevention.** Onboarding makes feedback expectations explicit. Channels are designed for low friction. + +--- + +## Failure 4: We graduated to GA on schedule but launched with critical bugs + +**Symptom.** The GA launches. Critical issues that the beta cohort would have surfaced (or did surface but were not addressed) appear post-GA. + +**Diagnosis.** Graduation criteria were not enforced. The decision was calendar-driven; the team graduated before the criteria were met. + +**Cure.** Damage control: address the bugs quickly, communicate transparently, reset support expectations. + +**Prevention.** Graduation criteria are enforced honestly. The decision is criteria-driven, not calendar-driven. If criteria are not met, extend the beta or graduate with explicit acknowledgment of unmet criteria. + +--- + +## Failure 5: Our beta has been running for 8 months with no graduation + +**Symptom.** Beta has run far longer than planned. No firm graduation date. The team has avoided the GA decision. + +**Diagnosis.** Perpetual beta. No firm graduation criteria; the team avoided commitment. + +**Cure.** Force the graduation decision. Define criteria explicitly. Decide: graduate now, graduate by a specific date, or reset the beta. + +**Prevention.** Time-bound the beta from the start. Define graduation criteria upfront. Force the decision when the criteria are met or when the time is up. + +--- + +## Failure 6: Beta participants vented on Twitter before the launch + +**Symptom.** Beta participants posted screenshots, mentioned the feature publicly, or discussed the beta outside the cohort. + +**Diagnosis.** NDA missing or unclear. Trust violation early erodes participant willingness; broader visibility may damage launch plans. + +**Cure.** Damage control depending on impact. Reach out to participants individually. Adjust the launch plan if the leaked information affects positioning. + +**Prevention.** NDAs in place where appropriate. Confidentiality expectations explicit in onboarding. Cohort selection includes trust assessment. + +--- + +## Failure 7: The beta surfaced patterns we did not act on + +**Symptom.** The beta produced clear feedback about specific issues. The GA launches without addressing them. Customers hit the same issues post-GA. + +**Diagnosis.** Mid-beta triage missing. Feedback was collected but not used during the beta. + +**Cure.** For the GA: address the issues quickly post-launch; communicate transparently. For future betas: implement the triage cadence and iteration discipline. + +**Prevention.** Weekly triage cadence. Categorization of feedback. Iteration on critical and high-impact items during the beta. + +--- + +## Failure 8: The GA launch surprised us + +**Symptom.** Issues emerge at GA that the team did not anticipate from the beta. The beta did not actually validate the GA experience. + +**Diagnosis.** Cohort or feedback structure was wrong. The cohort did not match the GA user; the channels did not surface the kinds of issues the GA exposed. + +**Cure.** Address the surprises post-GA. Investigate the gap between beta and GA experience. Apply lessons to future betas. + +**Prevention.** Cohort calibrated to GA user. Channels designed to surface the kinds of signal the GA decision needs. Validation of the cohort-GA match before the beta starts. + +--- + +## Failure 9: Beta participants felt ignored after providing feedback + +**Symptom.** Participants gave feedback. The team did not communicate what was heard or addressed. Participants disengaged. + +**Diagnosis.** Communication discipline missing. Participants commit time and want to know it mattered. + +**Cure.** Re-engage with appreciation and specific acknowledgment. For future participants, tighten the communication discipline. + +**Prevention.** Weekly or bi-weekly updates to participants. Updates reference specific feedback. Participants who give substantive feedback receive direct acknowledgment. + +--- + +## Failure 10: We ran a closed beta that was effectively employees only + +**Symptom.** The "external beta" included primarily employees, employees' family members, or very-friendly customers. Not actual representative customers. + +**Diagnosis.** Internal-only beta with external branding. Missed the customer-context complexity. + +**Cure.** Run a true external beta before GA, even if shorter. Apply lessons to future cohort selection. + +**Prevention.** Cohort selection includes "are these actually external customers using the product in real conditions?" Internal-leaning cohorts get flagged in cohort review. + +--- + +## Failure 11: Cohort and channels mismatched + +**Symptom.** Small cohort with aggregated channels (no signal extracted from the small volume). Or large cohort with direct channels (overwhelmed synthesis). + +**Diagnosis.** Cohort size and channel design did not align. + +**Cure.** Adjust mid-beta if possible: scale synthesis for large cohorts, deepen direct channels for small ones. + +**Prevention.** Cohort size and channel design decided together. Mismatches caught at planning. + +--- + +## Failure 12: Feedback collected but not synthesized + +**Symptom.** Surveys completed; widgets submitted; interviews recorded. The beta ends; the team has not synthesized the feedback into patterns or recommendations. + +**Diagnosis.** Synthesis was treated as optional or postponed. Without synthesis, the feedback never produced decisions. + +**Cure.** Allocate synthesis time post-beta. Apply discovery-research-synthesis discipline (see that skill). Produce the synthesis even if delayed. + +**Prevention.** Plan synthesis as part of the beta timeline. Allocate explicit time and ownership. + +--- + +## Failure 13: Wind-down treated participants poorly + +**Symptom.** Participants graduated to GA without clear transition information. Recognition was thin or missing. Future-beta recruitment is harder because alumni are unenthused. + +**Diagnosis.** Wind-down communication missed key elements. Recognition was insufficient for the time invested. + +**Cure.** Reach out individually to participants who feel underrecognized. Adjust future wind-down templates. + +**Prevention.** Wind-down communication template covers all elements (transition, recognition, post-survey, future beta invitation). + +--- + +## Failure 14: No postmortem + +**Symptom.** Beta ends; team moves on. Lessons from this beta do not inform future ones. Patterns recur across multiple betas because nobody surfaced them. + +**Diagnosis.** Postmortem was skipped. The beta program does not improve. + +**Cure.** Run a delayed postmortem if feasible. Establish postmortem as a non-negotiable step. + +**Prevention.** Postmortem on the timeline. Owner identified. Lessons documented and applied. + +--- + +## Failure 15: Beta scope crept + +**Symptom.** Mid-beta, additional capabilities were added based on participant requests. The beta validated a different feature than the original. + +**Diagnosis.** Scope creep during the beta. Feature requests were absorbed into the live beta. + +**Cure.** Reset the beta if the changes are significant. Capture for post-GA roadmap rather than addressing during the beta. + +**Prevention.** Triage discipline rejects scope-expanding feature requests during the beta. Capture for post-GA; do not add. + +--- + +## The cross-cutting pattern + +Most beta failures share a single root: treating beta as ceremony rather than as decision input. + +Ceremony focuses on running a beta because betas are expected: invite participants, collect feedback, ship the GA. The beta is a stage gate, not a learning loop. + +Decision input focuses on what the beta needs to inform: which decisions, what signal will inform them, what cohort and channels will produce that signal. The beta is structured around the decision it serves. + +The fix for almost any beta failure starts with the same question: what specifically did the team need to learn from this beta, and how is the beta structured to produce that learning? When the answers are clear, the beta becomes load-bearing. When the answers are vague, the beta becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-decision pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md b/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md new file mode 100644 index 0000000..49e1bbf --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md @@ -0,0 +1,295 @@ +# Feedback collection patterns + +Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. + +The feedback collection design is what determines whether the beta produces signal or noise. Structured channels capture usable data; ad-hoc venting channels produce volume that does not synthesize. + +--- + +## Structured surveys + +Surveys at defined points in the beta. + +**The structure.** + +- 5-15 questions per survey. +- Mix of structured questions (Likert scale, multiple choice) and 1-2 open-ended questions. +- Tied to specific learning goals: each question has a reason for being there. +- Sent at defined points: end of week 1, mid-beta, end of beta. + +**Strong survey questions.** + +- "On a scale of 1-7, how likely are you to use this feature daily?" (closed-ended; quantitative signal) +- "What's the most useful thing you've done with this feature so far?" (open-ended; surfaces use cases) +- "What was confusing or frustrating in your first week?" (open-ended; surfaces friction) +- "Compared to how you did this task before, is this feature better, worse, or about the same?" (specific comparison) + +**Weak survey questions.** + +- "Do you like the feature?" (binary; not actionable) +- "What features would you like next?" (out of beta scope; produces wishlist) +- "How can we improve?" (too open-ended; produces unfocused responses) + +**Why structured surveys work.** + +- Quantitative signal aggregates. Mid-beta NPS or satisfaction trend lines surface signal. +- Open-ended questions tied to specific topics produce focused qualitative data. +- Participants understand what is being asked; response rates are higher than for vague open-ended surveys. + +--- + +## Async feedback forms + +Forms participants fill when they encounter specific issues. + +**The structure.** + +- Always-available link or in-product entry point. +- Form fields prompt for specific information: use case, severity, expected vs actual behavior, screenshots if applicable. +- Auto-routes to the team's tracking system (issue tracker, feedback aggregation tool). + +**Strong form fields.** + +- "What were you trying to do?" (use case context) +- "What did you expect to happen?" (mental model) +- "What actually happened?" (observed behavior) +- "How blocking is this?" (severity) +- "Steps to reproduce" (when applicable) + +**Why async forms work.** + +- Captures issues at the moment they happen. +- Structured fields produce consistent data across submissions. +- Synthesis is easier when each submission has the same information shape. + +--- + +## Structured interviews + +30-60 minute interviews with a subset of participants. + +**The structure.** + +- 5-15 interviews per beta, depending on cohort size. +- Mid-beta or near end of beta. +- Discussion guide tied to the team's learning goals. +- Recorded with permission; transcribed for synthesis. + +**Strong interview prompts.** + +- "Walk me through the last time you used this feature. What were you trying to do?" +- "What was the most useful thing about it? What was the most frustrating?" +- "How did you decide to use this instead of [alternative]?" +- "Looking back, what do you wish was different?" + +**Why structured interviews work.** + +- Depth that surveys cannot capture. +- Specific moments and decisions surface in conversation that participants would not write into surveys. +- The qualitative data complements the quantitative survey data. + +**Cross-reference `discovery-research-synthesis`** for the broader interview discipline. Beta interviews are validation-stage; the interviewing methodology is similar. + +--- + +## In-product feedback widgets + +Feedback collection contextualized to the moment. + +**The structure.** + +- Trigger: button or prompt within the beta feature. +- Captures: what the user was doing (page or context), brief feedback text, optional rating. +- Routes to the team's tracking system. + +**Strong in-product widget design.** + +- Triggered after specific moments (completing the feature's primary action, abandoning a flow). +- Brief: 1-3 fields max. +- Optional severity or sentiment rating. +- Captures the page or context automatically. + +**Why in-product widgets work.** + +- Capture friction at the moment, not weeks later. +- Context is preserved automatically. +- Low friction encourages submissions. + +--- + +## Beta-aware support tickets + +Support tickets routed to a beta-aware support team. + +**The structure.** + +- Beta participants flagged in the support system. +- Tickets from beta participants get special handling: tagged "beta," routed to support reps trained on the feature, given priority response. +- Common beta issues documented for the support team in advance. + +**Strong beta-support practices.** + +- Faster response than standard tickets (the participant is doing the team a favor). +- Support reps escalate beta issues to product team where the issue affects beta program decisions. +- Patterns across tickets surface to the beta program manager. + +**Why beta-aware support works.** + +- Surfaces issues participants encounter "in the wild," not just the issues they choose to flag through formal channels. +- Captures the support burden of the feature, which informs GA support readiness. + +--- + +## Channels that fail + +Common feedback channels that produce noise rather than signal. + +**Beta-only Slack channels for venting.** + +- Participants vent in real time. +- Mixes critical signal with casual chat. +- Nobody synthesizes. +- High-engagement participants drown out quieter ones. +- Cure: structured channels instead, or use Slack for community building rather than feedback collection. + +**"Reply to this email with feedback."** + +- Returns long unstructured emails. +- Synthesis is hard; useful patterns get lost. +- Cure: structured forms or surveys. + +**End-of-beta survey only.** + +- Catches only what participants remember at the end. +- In-the-moment friction is forgotten. +- Cure: surveys at multiple points; in-product widgets for moment-of capture. + +**"Tell us anything."** + +- Unfocused open-ended prompts produce unfocused responses. +- Participants do not know what is wanted; many do not respond. +- Cure: specific prompts tied to what the team needs to learn. + +--- + +## Channel mix discipline + +Most structured betas use 3-5 channels. Each surfaces different signal. + +**Typical channel mix.** + +- 1 structured survey at end of week 1 (quantitative + first-impression qualitative). +- 1 structured survey at mid-beta (quantitative trend + behavior signal). +- Always-available async feedback form (specific issues as they arise). +- 5-10 structured interviews near end of beta (qualitative depth). +- In-product feedback widget (in-the-moment friction). +- Beta-aware support routing (issues participants choose to escalate). + +**The synthesis.** The team synthesizes across channels. Patterns that appear in multiple channels are stronger; signals from a single channel are weaker. + +**Channel mix calibration.** + +- Smaller cohorts (5-50): more interviews, less aggregation. +- Larger cohorts (100-500): more surveys and aggregation, fewer interviews. +- Largest cohorts (500+): heavy aggregation, sampling for interviews. + +--- + +## Feedback synthesis cadence + +How feedback gets reviewed during the beta. + +**Weekly synthesis.** + +- 1-2 hours weekly during the beta. +- Review feedback across all channels for the week. +- Categorize: critical bug, friction, feature request, positive signal, edge case. +- Surface patterns: what recurring feedback are we seeing? + +**Bi-weekly pattern review.** + +- 1-2 hours bi-weekly. +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening? +- Decide: what to fix during the beta vs what to defer to post-GA roadmap. + +**End-of-beta synthesis.** + +- Substantial work: 1-2 weeks of synthesis depending on cohort size. +- Apply discovery-research-synthesis discipline (see that skill). +- Output: beta synthesis document with patterns, implications, and graduation recommendation. + +--- + +## Feedback signal quality + +Not all feedback is equally valuable. + +**High-signal feedback.** + +- Specific moments of friction with reproducible context. +- Patterns across multiple participants. +- Behavioral data showing what users actually do (vs what they say). +- Comparison to alternatives (what users tried before, why they switched). + +**Lower-signal feedback.** + +- One-off complaints with no pattern. +- Hypothetical preferences ("it would be nice if..."). +- Wishlist features unrelated to the beta scope. +- Venting without specific context. + +**The discipline.** Synthesis weights higher-signal feedback. Lower-signal feedback gets noted but does not drive decisions. + +--- + +## Feedback volume management + +Managing the flow of feedback as the beta runs. + +**Volume signals.** + +- Critical issues surface fast: most appear in the first 2 weeks. +- Friction issues surface continuously through the beta. +- Behavioral signal accumulates; visible by mid-beta. + +**Volume management.** + +- The team's synthesis capacity bounds usable volume. Beyond that capacity, additional feedback produces less actionable signal. +- For larger cohorts, aggregate channels (surveys, in-product widgets) scale better than direct channels (Slack, email). + +**Burnout risk.** + +- Beta program managers reading 100+ feedback items per week burn out. +- Triage is the discipline: not all feedback gets equal attention. +- Critical and pattern feedback gets full attention; one-off venting gets noted briefly. + +--- + +## Common feedback collection failures + +**Single-channel reliance.** Only one feedback channel; misses signal that other channels would have caught. + +**Channels not tied to learning goals.** Feedback collected without clear purpose; synthesis cannot tell what to do with it. + +**Noisy channels (Slack venting).** High volume, low signal-to-noise ratio. + +**End-of-beta only.** Misses in-the-moment friction; relies on participant memory. + +**Vague prompts.** Open-ended questions without focus; produces unfocused responses. + +**No mid-beta synthesis.** Feedback collected but not reviewed until end; opportunities to address issues during the beta missed. + +**Feedback channels that conflict.** Multiple Slack channels for the same purpose; participants confused about where to post. + +**No closing the loop.** Participants give feedback; team never tells them what was heard or changed; engagement decays. + +--- + +## Methodology-level choices that stay in the public skill + +Channels that work (structured surveys, async forms, interviews, in-product widgets, beta-aware support). Channels that fail. Channel mix discipline. Feedback synthesis cadence. Signal quality discipline. Volume management. Common failures. + +## Implementation choices that stay internal + +Specific survey tools and templates. Specific feedback form integrations. Specific in-product widget implementations. Specific support ticketing systems. The team's own conventions for channel selection. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md b/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md new file mode 100644 index 0000000..aa2614c --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md @@ -0,0 +1,216 @@ +# Mid-beta triage and iteration + +Triage cadence. Iteration discipline (what to fix during the beta, what to defer). Communication with participants. + +Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. Mid-beta triage turns a static validation into an iterative one. + +--- + +## The triage cadence + +How the team reviews feedback during the beta. + +**Weekly triage (1-2 hours).** + +- Review feedback across all channels for the week. +- Categorize each piece: critical bug, friction issue, feature request, positive signal, edge case. +- Tag for action: fix this week, fix later in the beta, defer to post-GA, no action needed (one-off). +- Identify any critical issues warranting immediate response. + +**Bi-weekly pattern review (1-2 hours).** + +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening, which are not surfacing in volume? +- Surface decisions: what to address in the remaining beta period. + +**As-needed escalation.** + +- Critical issues (data loss, security, broken core flows) get same-day response regardless of cadence. +- The triage cadence does not delay critical-issue response. + +--- + +## Categorization + +Each piece of feedback gets categorized. + +**Categories.** + +- **Critical bug.** Crashes, data loss, broken core flows, security issues. Must be fixed before GA. +- **Friction issue.** Workflows that are confusing, slow, or sub-optimal but functional. Fix during beta where feasible; document otherwise. +- **Feature request.** Capability the participant wants that is outside beta scope. Capture for post-GA roadmap; do not add during beta. +- **Positive signal.** What is working well; what users find valuable. Surfaces what to preserve in GA and what to highlight in marketing. +- **Edge case.** Unusual configurations or contexts. Note for post-GA monitoring; address only if affecting many participants. +- **One-off.** Single observation without pattern. Note briefly; do not action. + +**Why categorization matters.** + +- Different categories have different action paths. Treating all feedback the same overwhelms triage. +- The categorization is the basis for the iteration decisions. + +--- + +## What to fix during the beta + +The team should fix some things during the beta and defer others. + +**Fix during the beta.** + +- Critical bugs that prevent participants from using the feature. The beta cannot validate the feature if participants cannot use it. +- Friction issues that are clearly addressable and significantly affect participant experience. Fixing them produces stronger end-of-beta signal. +- Issues that, if unfixed, will surface again post-GA at higher cost. +- Issues that participants are about to escalate publicly (if NDA-relevant) or that damage trust if left. + +**Defer to post-GA.** + +- Feature requests outside beta scope. +- Friction issues that affect a small subset of users in ways the team can document. +- Polish work that does not block the GA decision. +- Edge cases that do not affect mainline usage. + +**The "what changes the GA decision" test.** If fixing this issue affects whether the team can ship to GA, fix it. If it does not affect the GA decision, capture it for post-GA roadmap. + +--- + +## The iteration discipline + +Mid-beta iteration adds value but has constraints. + +**The discipline.** + +- Iterate on the feature, not the beta scope. Adding features to the beta mid-way confuses participants and dilutes signal. +- Fix critical and high-impact friction; capture rather than fix lower-impact issues. +- Communicate iteration to participants: when they see a fix or change, they know it came from their feedback. + +**The "do not redesign mid-beta" rule.** + +- Significant feature changes mid-beta produce two betas: the pre-change beta and the post-change beta. Neither is fully validated. +- If significant changes are needed, end the current beta, redesign, and start a new beta. Do not blend them. + +**The "no creep" discipline.** + +- Mid-beta is not the time to add capabilities outside the beta's original scope. +- Feature requests get captured for post-GA, not added to the beta. +- The beta's signal depends on consistency; scope creep undermines the validation. + +--- + +## Communication with participants + +Mid-beta communication keeps participants engaged. + +**The cadence.** + +- Weekly or bi-weekly updates to participants. +- Format: short email or in-product notification. +- Content: what was heard, what is being addressed, what is being deferred, what to expect next week. + +**Strong update content.** + +- "We heard your feedback about the configuration friction in step 3. We pushed a fix this week; please let us know if it is improved." +- "Several of you reported the dashboard load time is slow at scale. We are investigating; we expect a fix in the next 1-2 weeks." +- "We are seeing strong positive signal on the new export functionality. We will expand the format options in the next iteration." +- "Several of you requested integrations beyond the beta scope. We have captured these for post-GA roadmap." + +**Why communication matters.** + +- Participants who see their feedback acted on engage more substantively. +- Participants who feel ignored decay. +- Communication signals to participants that the team is listening. + +**Common communication failures.** + +- Silence between welcome and end of beta. Participants feel ignored. +- Generic updates that do not reference specific feedback. Feels performative. +- Over-communication. Daily updates are too much; participants tune out. +- Updates that promise more than the team will deliver. Erodes trust when promises are not kept. + +--- + +## The mid-beta health check + +A specific mid-beta milestone. + +**The milestone.** Roughly the midpoint of the beta. The team takes stock of where the beta is. + +**The questions.** + +- Is the feedback volume what was expected? If not, what is causing the difference? +- Are critical issues surfacing or has the team caught them all in the first part of the beta? +- Are behavioral patterns emerging? What do they suggest for the GA experience? +- Are participants engaged? Are some segments dropping off? +- Is the trajectory toward graduation criteria? Where are gaps? + +**The output.** + +- Adjustments to the beta operations: more triage, more communication, additional cohort recruitment if needed. +- Surfaced concerns about graduation: are the criteria reachable in the remaining beta time? +- Surfaced wins: what is going well that the team can build on for GA. + +--- + +## Mid-beta participant churn + +Some participants will drop off during the beta. + +**Why participants churn.** + +- The feature did not match their use case (they expected something different). +- They lost interest or got busy. +- They hit critical friction early and gave up. +- They felt ignored after providing feedback. + +**The response.** + +- Investigate churn. A subset of churn is normal; high churn is signal. +- For participants who churned because of friction: address the friction; possibly re-engage them. +- For participants who churned because of misfit: the cohort may have been miscalibrated; learn for future betas. +- For participants who felt ignored: tighten the communication discipline; thank them for prior feedback even if they have stopped engaging. + +**Replacement recruitment.** + +- For betas that need a specific cohort size for signal, replace churned participants if possible. +- Late-recruited replacements have less time in the beta; their feedback covers less of the beta period. +- Sometimes accepting churn and a smaller-than-planned cohort is the right call. + +--- + +## Triage anti-patterns + +Common ways triage decays. + +**Triage skipping.** No formal triage cadence; feedback accumulates without categorization or action. + +**Triage as logging.** Feedback gets categorized but never actioned. The categorization is documentation theater. + +**Triage by loudest voice.** Loudest participants get attention; quieter ones with similar feedback do not. Skews the synthesis. + +**Triage by easiness.** Easy fixes get prioritized regardless of impact. Important harder fixes get deferred indefinitely. + +**Triage without communication.** Internal triage happens but participants are not told. They feel ignored. + +**Triage that absorbs feature requests.** Participants request features outside scope; the team adds them mid-beta; scope creeps; signal dilutes. + +--- + +## Common iteration failures + +**No iteration during the beta.** Feedback is collected; the team waits for end of beta; opportunities to address issues during the beta are missed. + +**Excessive iteration.** Significant feature changes mid-beta. The beta becomes two different betas; neither validates the GA experience cleanly. + +**Iteration without communication.** The team fixes issues; participants do not know; engagement decays. + +**Iteration on participant requests outside scope.** Scope creep; the beta validates a different feature than the original. + +**No closing the loop.** Iterations happen; participants are not told their feedback drove the change; the connection between feedback and improvement is invisible. + +--- + +## Methodology-level choices that stay in the public skill + +The triage cadence. The categorization scheme. What to fix during the beta vs defer. The iteration discipline. The "do not redesign mid-beta" rule. Communication with participants. The mid-beta health check. Mid-beta churn handling. Common failures. + +## Implementation choices that stay internal + +Specific triage tools and trackers. Specific communication templates. Specific health-check formats. The team's own conventions for what counts as critical vs friction. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md b/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md new file mode 100644 index 0000000..b95bbcf --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md @@ -0,0 +1,212 @@ +# Participant selection criteria + +Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. + +Participant selection determines what the beta can produce. Calibrated cohorts produce decision-grade signal; misaligned cohorts produce noise that does not represent the GA user. Selection is upstream of every other beta decision. + +--- + +## Criteria that produce calibrated cohorts + +**Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. + +- Worked example: a feature for product managers at growth-stage SaaS companies. Beta participants should be PMs at growth-stage SaaS companies. Not designers, engineers, or PMs at very-early or very-late stage companies. +- The matching dimensions depend on the feature: role, company size, industry, usage volume, tenure, technical sophistication. + +**Variety across relevant dimensions.** Not all participants identical. + +- If the feature has segment-specific behavior, the cohort spans segments. +- If usage volume varies, the cohort includes high-volume and low-volume users. +- If geography matters (compliance, latency, language), the cohort spans relevant geographies. +- The variety should match the GA user diversity. + +**Feedback willingness.** Participants who agree to provide feedback through structured channels. + +- Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Recruiting should make the feedback expectation explicit. Participants who agree are more likely to engage; participants who decline are honest about their availability. + +**Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively. + +- Champion users, design partners, customers with active customer success relationships engage more. +- Customers in churn-risk are less likely to engage; their feedback may also be less representative (the relationship is already strained). + +**Real usage of the broader product.** Beta participants who use the broader product actively can give grounded feedback. Participants who signed up only for the beta and do not use the product otherwise often give surface-level feedback. + +--- + +## Criteria that produce miscalibrated cohorts + +**Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers. + +- Skews toward users who try every new feature; their feedback may not represent the broader target user. +- Misses users who would adopt at GA but who do not seek out beta sign-ups. + +**Highest-paying customers only.** Skews toward enterprise patterns. + +- Misses smaller-team and individual use cases. +- Enterprise feedback may emphasize features that smaller customers do not need. + +**Internal employees only.** Misses customer-context complexity. + +- Employees experience features differently than customers (familiarity, infrastructure, motivations). +- Internal-only validation produces "we tested" without "real customers tested." + +**Whoever happens to be available.** No selection criteria; the cohort is whoever the team can recruit quickly. + +- The cohort may not match the GA user; signal does not transfer to the GA decision. + +**Champion users only.** All beta participants are existing strong advocates. + +- Enthusiastic feedback may overstate readiness; missing the friction non-champion users would hit. + +--- + +## Variety calibration + +How to ensure the cohort spans the relevant dimensions. + +**The dimension audit.** + +- For the feature being beta'd, identify the dimensions that affect user experience. +- Common dimensions: role, company size, industry vertical, usage volume, geographic region, technical sophistication, tenure with the product. +- Decide which dimensions matter most for this feature. + +**Cohort composition.** + +- For each high-priority dimension, ensure the cohort includes representation across the values. +- If role matters: cohort includes participants in each relevant role. +- If usage volume matters: cohort includes high-volume, mid-volume, low-volume users. +- If industry varies meaningfully: cohort spans industries. + +**Worked example.** A feature for product managers using analytics tools. + +- Role dimension: cohort is all PMs (no other roles). +- Usage dimension: high-volume PMs (active daily users) + mid-volume PMs (weekly users). Skip low-volume because they likely will not use the feature meaningfully. +- Company size dimension: 10-50 employee, 50-200 employee, 200-500 employee. Skip enterprise (different feature priorities). +- Tenure dimension: PMs who have used the product 3+ months (so they have established workflows the new feature will integrate into). Skip new users. + +The cohort composition is intentional; each participant fits multiple criteria. + +--- + +## The cohort size question + +How many participants are enough. + +**The calibration is signal-need-driven.** + +- Bug discovery saturates fast: 20-30 participants surface most critical issues in 2-4 weeks. +- Behavioral signal saturates slower: 50-100 participants needed to see usage patterns clearly. +- Edge case discovery: 100-500+ participants needed; some edge cases never surface in beta. + +**Common cohort sizes by beta type.** + +- Design partner program: 3-10 participants. +- Closed alpha: 10-30 participants. +- Closed beta: 50-200 participants. +- Open beta: 500-5,000+ participants. +- RC validation: 1,000-10,000+ participants. + +**The "more is better" anti-pattern.** Teams default to large cohorts thinking volume produces signal. In practice, larger-than-needed cohorts produce volume without proportional signal increase, while making feedback synthesis harder. + +**The "smaller produces calibrated" principle.** A 50-person calibrated cohort often produces stronger signal than a 5,000-person uncalibrated one. Pick the smallest cohort that produces the signal needed. + +--- + +## The recruitment process + +How participants get selected. + +**Sources.** + +- Existing customer base: customer success identifies candidates matching the criteria. +- Sales pipeline: late-stage prospects who could become customers and provide feedback. +- Past beta participants: customers who participated in prior betas and proved engaged. +- Public sign-up forms (for open betas): with screening criteria applied to actual selection. +- Partner referrals: customers who recommend other customers fitting the profile. + +**The screening.** + +- Define the criteria explicitly (role, dimension values, feedback willingness). +- Apply the screening to candidates: who fits the criteria? +- For closed betas, decide which subset of fitting candidates to invite (cohort sizing). +- For open betas with screening, the sign-up form captures qualifying information; the team selects from sign-ups. + +**The invitation.** + +- Personalized invitations engage better than mass invitations. +- The invitation explains: what the beta is, what is expected, what participants get, how long it runs. +- Acceptance is opt-in; participants who decline are honest. + +**The capacity.** + +- Recruiting takes real time. A 50-participant closed beta may take 2-4 weeks of recruiting work depending on customer base and selection criteria. +- Plan recruiting time as part of the beta timeline. + +--- + +## The diversity-vs-control tradeoff + +Calibrated cohorts can over-control diversity in ways that miss valuable signal. + +**The tradeoff.** + +- Tightly-defined selection criteria produce a cohort that is uniform along the criteria. Reduces variety; may miss signal from users who differ. +- Loosely-defined criteria produce more diverse cohorts but make the cohort less calibrated to the GA user. + +**The middle path.** + +- Define the must-have criteria (role, key segment markers). +- Allow variety in the optional dimensions (industry, geography, tenure). +- The cohort is calibrated on what matters and varied on what does not. + +--- + +## When recruitment fails + +What to do when selection criteria cannot be met. + +**Insufficient candidates fitting criteria.** + +- Reconsider whether the criteria are too narrow. +- Extend recruiting time if feasible. +- Accept a smaller cohort that fully fits the criteria, rather than a larger cohort that includes mismatches. + +**Candidates fitting criteria decline to participate.** + +- Investigate why. Is the beta commitment too heavy? The compensation insufficient? The timing wrong? +- Adjust the offer; re-invite. +- If still insufficient, consider whether the beta plan is realistic given customer engagement willingness. + +**Cohort skew despite intentional selection.** + +- Some dimensions skew despite efforts (e.g., one industry over-represented because that industry is more receptive). +- Acknowledge the skew explicitly in synthesis. Patterns from the over-represented dimension may not generalize. + +--- + +## Common selection failures + +**No criteria.** Whoever happens to be available joins. Cohort does not represent GA user. + +**Self-selection only.** Open sign-ups skew the cohort. + +**Only champions.** Cohort over-represents enthusiasts; misses friction non-champions hit. + +**Internal employees only.** Misses customer-context complexity. + +**Single-dimension calibration.** Cohort uniform on one dimension (role) but mismatched on others (usage, segment). + +**Recruiting too late.** Beta starts before the cohort is calibrated; recruitment continues mid-beta; signal is muddled. + +**Enterprise-only.** Cohort over-represents large customers; misses smaller use cases. + +--- + +## Methodology-level choices that stay in the public skill + +The criteria for calibrated cohorts. The criteria for miscalibrated cohorts. Variety calibration with worked example. The cohort size question. The recruitment process. The diversity-vs-control tradeoff. When recruitment fails. Common selection failures. + +## Implementation choices that stay internal + +Specific recruiting tools and CRM integration. Specific screening surveys. Specific outreach templates. Specific tracking of cohort composition. The team's own conventions for selection criteria within different beta types. These vary by team and customer base. diff --git a/dist/pi/.agents/skills/brand-archetype-system/SKILL.md b/dist/pi/.agents/skills/brand-archetype-system/SKILL.md new file mode 100644 index 0000000..feb6c98 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/SKILL.md @@ -0,0 +1,143 @@ +--- +name: brand-archetype-system +description: "Apply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles." +category: brand +catalog_summary: "12 archetype defaults across 18 verticals: color, type, voice, imagery starters" +display_order: 5 +--- + +# Brand Archetype System + +Pre-composed aesthetic archetype defaults that jumpstart brand design work. Each archetype bundles color tendencies, type pairings, layout patterns, voice samples, and imagery direction for a recognizable aesthetic family. Stack-agnostic. Tool-agnostic. + +This is a starting-point library, not a methodology library. The agent applies archetype defaults to a specific brief; the archetypes themselves provide anchor points, not endpoints. + +--- + +## When to use + +- The user wants a starting point rather than designing from first principles +- The user references a brand or aesthetic family they want to design near +- Need to converge faster from many directions to one +- The user wants vertical-typical defaults (for example fintech consumer, B2B developer tools) +- The user wants to test what a brief would look like in a different archetype + +## When NOT to use + +- The user wants pure methodology guidance (use `brand-identity`) +- The user is in early ideation needing positioning territories (use `brand-ideation`) +- Defining voice for an existing brand (use `brand-voice`) +- Documenting a finished brand (use `brand-style-guide`) + +--- + +## How this composes with other skills + +This skill works upstream of `brand-identity` (provides starting defaults that brand-identity refines into a finished system) and parallel to `creative-direction` (archetypes can be located by position on the 4 creative-direction axes). + +Typical flow when this skill is invoked: +1. User provides a brief or references a target archetype +2. Agent picks the most relevant core archetype, or composes from 2 adjacent archetypes +3. Agent adapts the archetype's defaults to the brief (color tokens shift, type swaps to vertical-appropriate fonts, voice samples rewrite for the brand) +4. Agent flags adaptation choices made + +Direct verbatim copying of an archetype's default palette into a new brand is a failure mode. Archetypes constrain the design space; the brief specifies the point within that space. + +--- + +## The framework: 12 core archetypes plus 18 vertical applications + +Two layers of content in `references/`: + +### Core archetypes (12 files) + +Located in `references/core-archetypes/`. Each is an aesthetic family with: +- Aesthetic summary +- Position on the 4 `creative-direction` axes +- Color palette starter (4 to 6 hex values with token names and rationale) +- Type pairing starter (Google Fonts pairing with size scale) +- Layout and composition patterns +- Voice samples (5 to 10 representative lines) +- Component pattern descriptions (heroes, buttons, cards, tables) +- Imagery direction +- When to pick and when to avoid +- Adaptation guidance +- Exemplar brands with attribution language + +### Vertical applications (18 files) + +Located in `references/by-vertical/`. Each maps named brands to core archetypes in that vertical with: +- Vertical summary +- Common archetypes +- Brand-to-archetype mapping (5 to 10 brands per vertical) +- Vertical-specific adaptation notes +- Common archetype evolution patterns as brands mature + +### Two overview files + +- `00-archetype-system-overview.md`: how the system works, the taxonomy +- `01-how-to-apply-an-archetype.md`: the adaptation discipline, the failure modes + +--- + +## The 12 core archetypes + +| # | Archetype | Single-line summary | +|---|---|---| +| 01 | Editorial Restrained | Low-saturation, type-led, generous whitespace, considered | +| 02 | Technical Precise | Monospace and grid prominent, data-dense, system-feeling | +| 03 | Warm Conversational | Human imagery, mid-saturation, friendly type, approachable | +| 04 | Bold Confident | High-contrast, large display type, saturated, direct | +| 05 | Playful Energetic | Bright colors, illustration-led, dynamic, character-driven | +| 06 | Luxe Considered | Serif-led, generous spacing, restrained palette, premium | +| 07 | Clinical Trustworthy | Cool palette, sans-serif, clean medical or financial register | +| 08 | Rugged Utilitarian | Earth tones, workwear influence, no-nonsense type | +| 09 | Retro Nostalgic | Period-specific palette and type, intentional vintage reference | +| 10 | Minimal Essentialist | Black, white, single accent, sans-serif only, sparse | +| 11 | Vibrant Saturated | High-saturation across full palette, color as character | +| 12 | Documentary Honest | Photography-led, real people, low-touched imagery | + +## The 18 vertical applications + +- B2B SaaS: Developer Tools, Business Productivity, Marketing and Sales, Data and Analytics +- Fintech: Consumer, Enterprise +- DTC: Fashion, Beauty, Home and Lifestyle, Food and Beverage +- Consumer Health and Wellness +- Hospitality and Travel +- Media and Publishing +- EdTech +- Gaming and Entertainment +- Marketplace +- Crypto and Web3 +- Real Estate and Proptech + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands. "Editorial Restrained" not "Stripe-like." Brands are referenced as exemplars in description text using attribution language: "exemplified by [brands]", "common among [brands]", "characteristic of [brands]". + +This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## The four creative-direction axes (reference) + +Each archetype positions on the 4 axes defined in the `creative-direction` skill. Brief summary for cross-reference: + +- **Tone register**: Professional, Conversational, Playful +- **Aesthetic register**: Restrained, Considered, Expressive, Maximal +- **Audience relationship**: Authority, Peer, Companion, Performer +- **Sensory ambition**: Functional, Considered, Immersive, Theatrical + +Each core archetype file specifies its position on each axis. + +--- + +## Reference files + +- [`references/00-archetype-system-overview.md`](references/00-archetype-system-overview.md) - How the two-layer system fits together, entry patterns, when archetypes compose, and the recurring failure modes. +- [`references/01-how-to-apply-an-archetype.md`](references/01-how-to-apply-an-archetype.md) - The 5-step adaptation process: locate the design space, map the brief to adjustable dimensions, adapt color, adapt type, write voice samples. Includes the cross-archetype coherence check. + +The 12 core archetype files live in the `core-archetypes/` subdirectory under references, numbered 01 (Editorial Restrained) through 12 (Documentary Honest). The 18 vertical application files live in the `by-vertical/` subdirectory under references, numbered 01 (B2B SaaS Developer Tools) through 18 (Real Estate and Proptech). Load the relevant core archetype file plus the relevant vertical file together for any brief that names both an aesthetic family and an industry. + diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md b/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md new file mode 100644 index 0000000..b47a529 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md @@ -0,0 +1,40 @@ +# Archetype system overview + +This document explains the taxonomy and how the layers fit together. Read this first when working with the archetype system for the first time. + +## The two layers + +**Core archetypes** (12 files) are the aesthetic families themselves. They span verticals; an archetype like Editorial Restrained appears in B2B SaaS, in media publishing, in DTC fashion. The core archetype files describe the family in pure form: what makes it recognizable, the color tendencies, the type pairings, the voice character. + +**Vertical applications** (18 files) describe how the archetypes manifest in specific industries with named brands. They are discovery surfaces: a user working on a fintech brand should be able to find their vertical, see which archetypes are common, see specific brand-to-archetype mappings, and decide which core archetype to start from. + +## How the agent should use the system + +Two entry patterns: + +**Entry by archetype** (user references an aesthetic family): "I want something Editorial Restrained for my analytics product." Agent loads the Editorial Restrained core archetype file, plus the B2B SaaS Data and Analytics vertical file for context. Composes defaults adapted to the brief. + +**Entry by vertical** (user references their industry): "I'm designing a consumer fintech app, what archetypes work here?" Agent loads the Fintech Consumer vertical file first, sees the brand-to-archetype mappings, picks the most relevant core archetype, then loads that for full defaults. + +## What this system is and is not + +**It is**: a library of pre-composed defaults that accelerate brand work by providing known-good starting points with documented rationale. + +**It is not**: a substitute for design judgment. The defaults are anchor points; the brief specifies where to land within the archetype's design space. + +**It is not**: a comprehensive theory of brand aesthetics. The 12 archetypes capture the most recognizable contemporary Western brand aesthetics. They are not exhaustive. Regional, cultural, and historical archetypes are deferred to future expansions of the catalog. + +## When archetypes compose + +Two archetypes can blend. Linear is Editorial Restrained with Technical Precise undertones. Stripe is Technical Precise with Editorial Restrained surfaces. Glossier is Vibrant Saturated with Minimal Essentialist composition. + +When the brief calls for blending, the agent picks two core archetypes and notes which contributes which dimension (for example "Editorial Restrained for type and whitespace, Technical Precise for color and density"). + +## The failure modes + +1. **Verbatim copying**: pulling the exact starter palette into a new brand without adaptation. Produces generic output. +2. **Archetype mismatch with audience**: picking an archetype because the user likes its exemplars rather than because it fits the audience. +3. **Cross-archetype tokens**: pulling a color from one archetype and type from another without considering coherence. Often produces incoherent output. +4. **Stale exemplars**: assuming a brand still exemplifies an archetype after a redesign. The archetype is durable; the brand is not. + +Each core archetype file's "Adaptation guidance" section addresses these. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md b/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md new file mode 100644 index 0000000..02c6607 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md @@ -0,0 +1,69 @@ +# How to apply an archetype + +This document is the operating manual. Once an archetype is picked, follow this process to adapt it to the specific brief. + +## The 5-step adaptation process + +### Step 1: Locate the archetype's design space + +Read the core archetype file. Understand: +- Position on the 4 creative-direction axes +- The non-negotiable structural choices (for example "single accent" for Editorial Restrained, "monospace prominent" for Technical Precise) +- The adjustable dimensions (specific hue of the accent, specific serif, specific density) + +The structural choices are what make the archetype recognizable. The adjustable dimensions are where the brief lands. + +### Step 2: Map the brief to adjustable dimensions + +For each adjustable dimension, ask: what does the brief specify or imply? + +- **Audience character**: Younger audience usually wants warmer accent; older wants cooler. Technical audience tolerates more density; consumer audience needs more whitespace. +- **Category context**: Crowded categories need stronger contrast; quiet categories can be more restrained. +- **Emotional direction**: Trust-needing brands lean cooler; warmth-needing brands lean warmer. +- **Competitive position**: If the closest competitor is in the same archetype, shift one adjustable dimension hard to differentiate. + +### Step 3: Adapt the color palette + +The starter palette is a relationship between values, not absolute hex codes. Preserve the relationship; shift the values. + +Example with Editorial Restrained: +- Default: ink #0F1B2D (navy), accent #5B8B85 (muted teal) +- Adaptation for a finance brief: ink #1A1F2E (deeper navy), accent #4A5D6E (slate blue), reads more institutional +- Adaptation for a consumer wellness brief: ink #2A2520 (warm dark brown), accent #7A9B7C (sage green), reads more grounded and warm + +Preserve: low saturation, single accent, paper-not-white background, ink-not-black text. Shift: specific hues to match emotional direction. + +### Step 4: Adapt the type pairing + +The starter pairing is a relationship between display and body, not specific fonts. Preserve the relationship; shift the fonts. + +Example with Editorial Restrained: +- Default: IBM Plex Serif (display) plus Inter (body) +- Adaptation for luxe-leaning brief: Tiempos Display (display) plus Inter (body) preserves the pairing, shifts the serif character +- Adaptation for technical-leaning brief: IBM Plex Serif (display) plus IBM Plex Sans (body) keeps within one family, reads more system-like + +Preserve: serif display plus sans body, modular scale, single weight per role. Shift: specific font choices to match register. + +### Step 5: Write voice samples for the specific brand + +The voice samples in the core archetype show character; they are not copy to lift directly. Write 5 to 10 new voice samples for the specific brand using the archetype's cadence and register. + +## The cross-archetype check + +Before finalizing, verify the output reads as coherent within the archetype: + +- Color: matches the archetype's saturation and contrast character? +- Type: matches the archetype's display and body relationship? +- Voice: matches the archetype's cadence and register? +- Layout: matches the archetype's density and whitespace tendency? + +If two of the four diverge from the archetype, either pick a different archetype or accept that the brand is a blend (and document which archetype contributes which dimension). + +## When to abandon an archetype mid-flow + +The archetype is wrong if: +- Three or more dimensions resist adaptation to the brief +- The audience signals reject the archetype's defaults (for example picking Editorial Restrained for a children's app) +- Direct competitors all live in the same archetype and your brief needs differentiation + +When abandoning, return to the vertical file for that industry and pick a different starting archetype. Do not try to retrofit an archetype that does not fit. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md new file mode 100644 index 0000000..1241203 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md @@ -0,0 +1,44 @@ +# B2B SaaS: Developer Tools + +## Vertical summary + +Brands serving developers building software. Audience values: technical precision, documentation depth, time-to-first-API-call. Brands compete on developer experience, primitive quality, observability, and composition. The category is mature with established archetypes. + +## Common archetypes in this vertical + +The dominant archetype is **Technical Precise** (Stripe docs, Sentry, Datadog). **Editorial Restrained** is the rising adjacent archetype (Linear, Vercel, Resend). **Bold Confident** appears at the consumer-edge (Loom, formerly Heroku). Other archetypes are rare in this space; warmth and play do not read as credibility to developers building production systems. + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Stripe | Technical Precise with Editorial undertones | Best-in-category documentation aesthetic; navy and violet accents; serif display creeping into marketing | +| Linear | Editorial Restrained | Single-accent restraint; brutal type hierarchy; muted palette | +| Vercel | Editorial Restrained leaning Technical Precise | Black and white; Geist font system; minimal accents | +| Sentry | Technical Precise | Dark mode dominant; purple accent; data-dense | +| Datadog | Technical Precise | Cool palette; UI-led marketing; dense | +| Resend | Editorial Restrained | New entrant; serif display; warm paper background | +| Cloudflare | Bold Confident | Orange brand color; energetic; consumer-tilted | +| GitHub | Editorial Restrained adjacent | Octocat character softens the precision | +| Supabase | Bold Confident leaning Technical Precise | Green primary; recently more restrained | +| Cursor | Technical Precise | Dark-mode-first; tool-focused; understated | + +## Vertical-specific adaptation notes + +- **Documentation surfaces are first-class**: developer brands need documentation as part of the brand surface, not an afterthought. The type system must scale to long-form technical reading. +- **Code samples are brand assets**: how code renders (syntax highlighting palette, line numbers, copy buttons) is brand expression. +- **Dark mode is required**, not optional. Most developers spend their day in dark interfaces. +- **Performance signals as brand signals**: page load time, animation frame rate, perceived speed are part of how developers judge developer brands. +- **Density tolerance**: developers tolerate (and often prefer) higher information density than other B2B audiences. + +## Common archetype evolution + +Developer brands frequently start Technical Precise and add Editorial Restrained as they mature. Stripe's evolution from pure technical to editorial-influenced marketing is the canonical example. Conversely, brands that start Bold Confident (Cloudflare, Supabase) sometimes retreat toward restraint as they target enterprise. + +The early-stage developer brand archetype shift is almost always: drop the consumer-tinted color, add a serif, lean into restraint. The mature-stage shift is sometimes: re-introduce a careful illustration system to soften pure restraint (GitHub's Octocat-era is the canonical case). + +## Vertical anti-patterns + +- **Playful Energetic in developer tools**: reads as unserious. Developers building production systems do not want a mascot taking up screen real estate in their dashboard. +- **Luxe Considered in developer tools**: reads as out-of-touch. Developer tools differentiate on substance, not premium feel. +- **Vibrant Saturated in developer tools**: rare and risky; works only when the brand is consumer-tilted (Cloudflare manages it with discipline). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md new file mode 100644 index 0000000..76f81c5 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md @@ -0,0 +1,43 @@ +# B2B SaaS: Business Productivity + +## Vertical summary + +Brands serving teams getting work done across documents, projects, communications, and design. Audience is prosumer-tilted: knowledge workers who self-serve, evaluate based on demos and free trials, and bring tools into their organizations from the bottom up. Brands compete on approachability, integration depth, and brand likeability alongside functional differentiation. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Slack, Mailchimp, Figma in marketing) and **Bold Confident** (Notion, Linear in launches). **Playful Energetic** appears at the edges (Asana classic era). **Editorial Restrained** is rising (Coda, Notion's recent surfaces). The category rewards personality more than developer tools but less than consumer apps. + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Notion | Bold Confident leaning Warm Conversational | Black on white plus illustration character; emoji-rich; oversized type | +| Figma | Warm Conversational | Multi-hue creative palette; illustration-led; community-driven | +| Loom | Bold Confident | Recent rebrand bold-purple-and-black; high contrast | +| Slack | Warm Conversational | Multi-hue saturated brand colors; hands-and-objects illustration era | +| Airtable | Warm Conversational | Multi-color brand; spreadsheet-meets-database approachable | +| Coda | Editorial Restrained | Type-led; restrained palette; document-first feeling | +| Asana | Playful Energetic moving to Warm Conversational | Mascot-era to recent considered warmth | +| ClickUp | Vibrant Saturated | Multi-hue palette; expressive; consumer-tilted | +| Monday.com | Vibrant Saturated | Saturated multi-hue; bold UI; high energy | +| Dropbox | Vibrant Saturated leaning Editorial Restrained | 2017 rebrand era is the canonical example of the shift | + +## Vertical-specific adaptation notes + +- **Illustration budget matters**: brands without illustration capacity should pick Editorial Restrained or Bold Confident rather than Warm Conversational or Playful Energetic. Bad illustration kills the warm archetypes immediately. +- **Onboarding surface as brand surface**: in productivity, onboarding flows are heavily branded and high-impact. The archetype must extend cleanly into product chrome. +- **Self-serve discovery**: pricing pages, signup flows, and product tours carry brand weight. Restraint in these surfaces signals trust; warmth signals approachability. +- **Bottom-up adoption pattern**: brands are evaluated by individual users before procurement. The archetype should not require enterprise sign-off to feel right. + +## Common archetype evolution + +Productivity brands often start Warm Conversational with heavy illustration and pull back toward Editorial Restrained or Bold Confident as they scale into enterprise. Slack's evolution shows this: early Slack was warm-illustration-heavy; current Slack reads more restrained while retaining color personality. Notion's evolution is similar. + +The mature-stage shift is frequently: keep the personality in voice and color, remove decorative illustration from primary surfaces, lean into typographic hierarchy. + +## Vertical anti-patterns + +- **Pure Technical Precise in productivity**: reads as developer tool rather than productivity tool. Audience expects warmth. +- **Luxe Considered in productivity**: reads as enterprise theatre. Self-serve audiences read restraint as remote. +- **Rugged Utilitarian**: completely incompatible with the audience. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md new file mode 100644 index 0000000..ae51ddf --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md @@ -0,0 +1,43 @@ +# B2B SaaS: Marketing and Sales + +## Vertical summary + +Brands serving marketers, sales teams, growth professionals, and revenue operations. Audience is mixed prosumer and enterprise: bottom-up adoption among individual marketers, top-down evaluation by RevOps and procurement. Brands compete on platform breadth, integration ecosystems, attribution claims, and trust signals to budget-holders. + +## Common archetypes in this vertical + +The dominant archetypes split by audience tier. **Warm Conversational** dominates SMB and prosumer (Mailchimp, Intercom, ConvertKit). **Bold Confident** appears at the growth-energy edge (Drift, Mutiny). **Clinical Trustworthy** dominates enterprise (Salesforce, Marketo). **Editorial Restrained** is the rising adjacent archetype (Webflow's marketing surfaces). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Mailchimp | Warm Conversational | Multi-hue brand; mascot-era illustration; SMB-focused | +| Webflow | Editorial Restrained | Serif-led marketing; typographic hierarchy; designer audience | +| HubSpot | Warm Conversational | Orange and white; rounded illustration; inbound voice | +| Intercom | Warm Conversational | Friendly conversational brand; chat-first UX | +| Drift | Bold Confident | Bold colors; conversational-AI positioning | +| Marketo | Clinical Trustworthy | Cool palette; enterprise-trust signals; B2B authority | +| Salesforce | Clinical Trustworthy at enterprise edge | Cloud iconography; trust-blue; enterprise authority | +| ConvertKit (Kit) | Warm Conversational | Creator-focused warmth; muted palette | +| Mutiny | Bold Confident | Saturated personalization-as-brand | +| Apollo | Editorial Restrained leaning Bold Confident | Recent restrained typography redesign | + +## Vertical-specific adaptation notes + +- **Enterprise versus prosumer split is wide**: prosumer leans warm and friendly; enterprise leans clinical and authoritative. The brand should pick a lane and commit; trying to do both produces neither. +- **Trust signals matter**: customer logo strips, peer-reviewed comparison tables, security certifications carry brand weight in this vertical. +- **Demo and trial flows**: a high portion of brand perception forms during the demo or free trial. The archetype must extend cleanly into in-product surfaces. +- **AI-positioning surge**: many brands in this category have recent AI-features positioning that affects archetype choice; AI features tend to pull brands toward Technical Precise or Bold Confident. + +## Common archetype evolution + +Marketing and sales brands frequently start Warm Conversational at SMB and evolve toward Clinical Trustworthy or Editorial Restrained as they target upmarket. Mailchimp's evolution from playful-illustration to more restrained type-led marketing reflects this. HubSpot's evolution from friendly orange to a more institutional brand presence is another example. + +The mature-stage shift is frequently: drop heavy illustration, narrow the palette, lean into customer evidence rather than personality. + +## Vertical anti-patterns + +- **Playful Energetic in enterprise marketing tools**: reads as unserious to budget-holders. +- **Luxe Considered in mass-market marketing tools**: reads as out-of-touch with the SMB user base. +- **Pure Technical Precise**: works for some categories (analytics, attribution) but feels wrong for relationship-building tools (CRM, email). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md new file mode 100644 index 0000000..a1cff84 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md @@ -0,0 +1,43 @@ +# B2B SaaS: Data and Analytics + +## Vertical summary + +Brands serving data teams, analysts, product managers, and engineers working with data infrastructure, business intelligence, and product analytics. Audience values: query power, schema clarity, time-to-first-insight, and trust in numbers. The category overlaps with developer tools at the infrastructure end and with marketing analytics at the application end. + +## Common archetypes in this vertical + +The dominant archetypes are **Technical Precise** (Mixpanel, Amplitude, Snowflake) and **Editorial Restrained** (dbt, Hex, Threshold the fictional reference build). The category rewards precision; **Clinical Trustworthy** appears at the enterprise BI edge (Tableau historically); **Bold Confident** appears at the new-entrant edge (Hex at launch). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Mixpanel | Technical Precise | Cool palette; product analytics rigor; chart-as-hero | +| Amplitude | Technical Precise | Blue and white; data-density tolerant; PLG positioning | +| Looker | Technical Precise | Enterprise BI restraint; Google acquired | +| Snowflake | Editorial Restrained adjacent | Restrained type; cloud-native confidence | +| Tableau | Clinical Trustworthy historically, Editorial Restrained recently | Recent rebrand pulled toward typographic restraint | +| dbt | Editorial Restrained | Type-led; community-driven; restraint as differentiator | +| Hex | Bold Confident | Saturated brand; modern data workspace positioning | +| Census | Editorial Restrained | Recent shift toward type-led restraint | +| Hightouch | Bold Confident | Strong brand colors; reverse ETL positioning | +| Threshold (fictional reference) | Editorial Restrained | Catalog reference build; PLG onboarding analytics | + +## Vertical-specific adaptation notes + +- **Chart and table rendering as brand**: how a chart looks, how table cells align, how numbers format are core brand expression. The archetype must extend cleanly into data visualization conventions. +- **Documentation depth**: data tools live and die on documentation. Long-form technical reading is core to the brand surface, not auxiliary. +- **Trust through precision**: vague claims undermine the archetype. Specific numbers, specific schemas, specific examples carry the brand. +- **SQL and code as content**: query examples, schema definitions, and code samples are first-class brand assets. + +## Common archetype evolution + +Data brands frequently start Technical Precise and add Editorial Restrained as they mature into prosumer territory. Snowflake's evolution from pure technical to restrained editorial is the canonical case. Conversely, brands that start Bold Confident (Hex, Hightouch) often pull back toward restraint as they target enterprise. + +The early-stage shift is usually: keep the technical precision in product surfaces, add editorial restraint to marketing. + +## Vertical anti-patterns + +- **Playful Energetic in data tools**: reads as untrustworthy with numbers. Audiences expecting analytical rigor reject playful brand expression. +- **Luxe Considered in data tools**: reads as marketing rather than substance. +- **Rugged Utilitarian**: completely incompatible with the audience and the category. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md new file mode 100644 index 0000000..1050614 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md @@ -0,0 +1,43 @@ +# Fintech: Consumer + +## Vertical summary + +Brands serving individual consumers across banking, investing, payments, lending, and budgeting. Audience splits sharply by age and risk tolerance: younger audiences tolerate (and prefer) energy and playfulness; older audiences require clinical trust signals. Brands compete on trust, fee transparency, and emotional positioning around money. + +## Common archetypes in this vertical + +The dominant archetypes are **Bold Confident** (Cash App, Robinhood for younger audiences) and **Clinical Trustworthy** (Chime, SoFi, Wealthfront for trust-needing positions). **Warm Conversational** appears at the savings-and-budgeting edge (Acorns). **Playful Energetic** appears at the consumer-payments edge (Venmo historically). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Cash App | Bold Confident | Black plus saturated green; oversized type; consumer-payments register | +| Robinhood | Bold Confident | Saturated green plus black; recently more institutional | +| Chime | Clinical Trustworthy | Trust-blue palette; calm voice; banking-not-bank positioning | +| SoFi | Clinical Trustworthy | Multi-product trust signals; restrained palette | +| Venmo | Playful Energetic historically | Multi-color personality; payments-as-social positioning | +| Wealthfront | Editorial Restrained | Type-led; institutional confidence; long-term-investing register | +| Acorns | Warm Conversational | Warm palette; round-up framing; approachable savings | +| Mint | Clinical Trustworthy historically | Cool palette; budgeting-trust positioning | +| Current | Bold Confident | Saturated brand; younger-audience positioning | +| Step | Playful Energetic leaning Bold Confident | Teen-banking; character-driven | + +## Vertical-specific adaptation notes + +- **Trust versus energy is the central design tension**: every consumer fintech brand sits somewhere on this spectrum. Picking the archetype is picking the position. +- **Regulatory and compliance copy** affects voice. The brand's voice must accommodate disclosures, terms, and risk language without breaking the archetype. +- **Money is emotional**: the archetype carries emotional positioning about money (excitement, security, freedom, control). The visual must match the emotional position. +- **Mobile-first**: most consumer fintech brand exposure is on phone screens. The archetype must extend cleanly to small screens with reduced ornamentation. + +## Common archetype evolution + +Consumer fintech brands frequently shift archetype as they target older audiences. Robinhood's evolution from pure bold-energy to more institutional restraint as it added retirement and IRA products is the canonical case. Cash App's evolution into financial-products-beyond-payments shows similar restraint additions. + +The mature-stage shift is usually: keep the brand color, add restraint to type, dial back the swagger in voice, add trust signals. + +## Vertical anti-patterns + +- **Luxe Considered in mass-market fintech**: reads as out-of-touch. +- **Documentary Honest in payments and investing**: photography of real people does not communicate the right thing in this category; the value is the product, not the experience. +- **Rugged Utilitarian**: completely incompatible. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md new file mode 100644 index 0000000..eb6935b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md @@ -0,0 +1,43 @@ +# Fintech: Enterprise + +## Vertical summary + +Brands serving businesses with payments, treasury, banking, spend management, and financial infrastructure. Audience splits between developer-touching (payment infrastructure) and finance-touching (corporate cards, spend management, treasury). Brands compete on integration depth, control surfaces, and operational trust. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Editorial Restrained** with Technical Precise undertones dominates developer-touching fintech (Stripe, Modern Treasury). **Bold Confident** dominates finance-touching B2B (Ramp, Brex, recent Mercury). **Technical Precise** dominates pure infrastructure (Plaid). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Stripe | Editorial Restrained with Technical Precise undertones | Best-in-category fintech brand; serif marketing, technical product | +| Plaid | Technical Precise | Developer-first; cool palette; integration-as-product | +| Mercury | Bold Confident, recently shifting to Editorial Restrained | Recent rebrand pulled back toward restraint | +| Brex | Bold Confident | Bold colors; corporate-card energy; recent restraint additions | +| Ramp | Bold Confident | Saturated palette; spend-management-with-energy positioning | +| Modern Treasury | Editorial Restrained | Type-led; payments-infrastructure restraint | +| Adyen | Editorial Restrained leaning Clinical Trustworthy | Enterprise-payments authority | +| Square (now Block) | Bold Confident historically | Black plus accent; SMB-payments register | +| Bill.com | Clinical Trustworthy | Cool palette; finance-team-tool positioning | +| Carta | Editorial Restrained | Recent rebrand pulled toward editorial type-led | + +## Vertical-specific adaptation notes + +- **Developer-touching versus finance-touching split**: payment infrastructure (Stripe, Plaid) is evaluated by developers; spend management (Ramp, Brex) is evaluated by finance. The archetype must match the evaluator. +- **Compliance and trust copy** is heavier than in consumer fintech: SOC 2, PCI-DSS, certifications must appear above the fold and be visually weighty. +- **Documentation depth**: developer-facing fintech needs documentation as primary surface; finance-facing needs reporting and dashboards as primary surface. +- **Multi-product expansion**: many enterprise fintech brands expand from a single product (payments, cards, banking) into a platform. The archetype must extend to multiple product lines coherently. + +## Common archetype evolution + +Enterprise fintech brands frequently start Bold Confident as challengers and shift toward Editorial Restrained as they target larger customers. Mercury's recent rebrand from bold-pastel to restrained-serif is the canonical example. Carta's recent restraint shift follows the same pattern. + +The mature-stage shift is usually: dial back the saturated color, lean into typographic restraint, add institutional confidence to voice. + +## Vertical anti-patterns + +- **Playful Energetic in enterprise fintech**: reads as financially unserious. Finance buyers reject playful brand expression even in modern challenger brands. +- **Vibrant Saturated**: tolerated only when the brand is a category challenger; mature enterprise positions require restraint. +- **Documentary Honest**: incompatible with the category; product surfaces and dashboards carry the brand, not real photography. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md new file mode 100644 index 0000000..b98fed8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md @@ -0,0 +1,43 @@ +# DTC: Fashion + +## Vertical summary + +Brands selling apparel directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability or ethical positioning where relevant. The category is dominated by photography quality; brand archetypes ride on photo direction more than on type or color. Price point splits the vertical: above 80 dollars per piece favors Luxe Considered, mass-market favors Minimal Essentialist or Warm Conversational. + +## Common archetypes in this vertical + +The dominant archetypes are **Luxe Considered** (Aritzia, Reformation, COS at the premium end) and **Minimal Essentialist** (Everlane, Allbirds at launch, Cuyana). **Bold Confident** appears at streetwear and challenger brands (Stüssy digital, Kith). **Documentary Honest** appears in heritage and outdoor-adjacent fashion (Patagonia, Filson). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Aritzia | Luxe Considered | Editorial photography; serif type; mid-premium positioning | +| Reformation | Luxe Considered with sustainability voice | Cream and earthy palette; sustainability framing | +| Everlane | Minimal Essentialist | Black plus white; transparency narrative | +| Allbirds (launch era) | Minimal Essentialist | Warm white plus single accent; sustainable-essentials | +| Cuyana | Luxe Considered | Cream and warm-neutral; fewer-better-things positioning | +| Stüssy | Bold Confident at streetwear edge | High-contrast; oversized lockup; streetwear authority | +| COS | Minimal Essentialist | Black on white; architectural typography; H and M premium tier | +| Filson | Documentary Honest with Rugged Utilitarian | Heritage workwear; earned authenticity | +| Outdoor Voices (historical) | Vibrant Saturated leaning Warm Conversational | Multi-hue palette; recreation-not-sport positioning | +| Universal Standard | Editorial Restrained | Size-inclusive premium; serif-led type-first | + +## Vertical-specific adaptation notes + +- **Photography quality is the gating factor**: every archetype in this vertical depends on excellent product and lifestyle photography. Brands without photography budget should pick Minimal Essentialist (which can survive on product-on-white) over the other archetypes. +- **Model casting** is brand expression: who appears in the photography signals the audience the brand is speaking to. Casting decisions are archetype-relevant. +- **Sustainability framing** is increasingly default in this vertical: the archetype may need to accommodate sustainability narrative without leaning preachy. +- **Seasonal updates** affect archetype continuity: brands must be able to refresh imagery seasonally without breaking the brand system. + +## Common archetype evolution + +Fashion brands frequently start Minimal Essentialist at launch (low-cost archetype with high signal) and migrate toward Luxe Considered as they raise prices and add product lines. Allbirds' evolution shows this: launch era was pure Minimal Essentialist; recent surfaces lean warmer and more storied (Warm Conversational with Documentary Honest notes). + +Conversely, brands that start Luxe Considered sometimes pull back toward Minimal Essentialist when they target younger or more digitally-native audiences. + +## Vertical anti-patterns + +- **Technical Precise in fashion**: completely incompatible. +- **Playful Energetic in mass-market fashion**: reads as costume; works only at children's-or-novelty edge. +- **Bold Confident in heritage fashion**: undermines the heritage positioning. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md new file mode 100644 index 0000000..e007077 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md @@ -0,0 +1,43 @@ +# DTC: Beauty + +## Vertical summary + +Brands selling skincare, cosmetics, hair care, and personal care directly to consumers. Audience values: ingredient evidence (in clinical positions), aesthetic alignment (in aspirational positions), and category authority (in challenger positions). The vertical splits sharply across three lanes that map cleanly onto archetypes. + +## Common archetypes in this vertical + +Three clear lanes: **Vibrant Saturated** for personality-driven challenger brands (Glossier, Drunk Elephant); **Luxe Considered** for premium and aspirational (Aesop, Augustinus Bader); **Minimal Essentialist** for clinical-and-rational positioning (The Ordinary). **Documentary Honest** appears at the editorial-skincare edge (Topicals). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Glossier | Vibrant Saturated with restraint | Pink-and-white world; soft typography; community-as-brand | +| Drunk Elephant | Vibrant Saturated | Multi-hue saturated palette; clinical ingredient framing | +| Aesop | Luxe Considered | Apothecary aesthetic; restrained palette; editorial confidence | +| The Ordinary | Minimal Essentialist | Black on white; ingredient-as-name; clinical transparency | +| Fenty Beauty | Bold Confident | Saturated brand; inclusivity-as-positioning | +| Topicals | Vibrant Saturated with editorial photography | Saturated palette plus documentary photo direction | +| Sunday Riley | Luxe Considered | Premium clinical; warm palette; ingredient narrative | +| Augustinus Bader | Luxe Considered | Pure luxury skincare; serif-led; minimal product range | +| Tatcha | Luxe Considered | Japanese-influenced premium; cream palette; heritage narrative | +| Bubble | Vibrant Saturated leaning Playful Energetic | Gen-Z skincare; bright multi-hue; accessible price point | + +## Vertical-specific adaptation notes + +- **Three-lane decision is the central archetype choice**: Vibrant Saturated (personality), Luxe Considered (premium), Minimal Essentialist (clinical). Commit to one lane; trying to do two reads as confused. +- **Ingredient communication**: how ingredients are presented carries archetype weight. Clinical lane presents ingredients as data; premium lane treats ingredients as story; personality lane treats ingredients as character. +- **Packaging design** is integrated with the digital brand: the bottle, jar, or tube on the page is brand expression. Packaging design must match the archetype. +- **Photography conventions**: clinical lane uses product-on-white; premium lane uses editorial styled photography; personality lane uses saturated lifestyle and product-on-color. + +## Common archetype evolution + +Beauty brands frequently stay within their original archetype but refine over time. Glossier has stayed Vibrant Saturated with increasing restraint as the brand has matured. The Ordinary has stayed Minimal Essentialist with subtle additions for new product lines. Aesop has stayed Luxe Considered with consistent discipline since launch. + +Brands that try to switch archetypes (for example a clinical brand adding personality) usually undermine their original positioning. + +## Vertical anti-patterns + +- **Technical Precise in beauty**: incompatible; reads as cold and clinical without the trust signals to justify it. +- **Rugged Utilitarian**: completely incompatible. +- **Mixed clinical-and-personality**: a brand that tries to be both The Ordinary and Glossier ends up neither. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md new file mode 100644 index 0000000..5d47154 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md @@ -0,0 +1,43 @@ +# DTC: Home and Lifestyle + +## Vertical summary + +Brands selling bedding, furniture, kitchenware, home accessories, and lifestyle goods directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability framing where relevant. The vertical rides on lifestyle photography quality more than any other element; the archetype is downstream of how the brand photographs interiors and objects in use. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Brooklinen, Article, Floyd in marketing) and **Luxe Considered** (Parachute, West Elm, Pottery Barn premium tier). **Minimal Essentialist** appears at the design-purist edge (Floyd in product surfaces, Hem). **Bold Confident** appears at the challenger-mattress edge (Tuft and Needle historically, Casper historically). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Brooklinen | Warm Conversational | Friendly bedding brand; mid-saturation palette; clear value framing | +| Parachute | Luxe Considered | Cream and warm-neutral; aspirational bedding | +| Article | Warm Conversational | Mid-century furniture; muted palette; design-led | +| Floyd | Minimal Essentialist | Minimal modular furniture; clean type; restrained palette | +| West Elm | Luxe Considered | Premium home; serif type; lifestyle photography | +| Tuft and Needle (historical) | Bold Confident historical, Warm Conversational now | Direct-to-consumer mattress positioning | +| Casper (historical) | Bold Confident historical | Original sleep-better-everything campaign register | +| Hem | Minimal Essentialist | Scandinavian-influenced minimal; modular furniture | +| Quince | Minimal Essentialist leaning Luxe Considered | Premium-quality at accessible pricing; restraint as positioning | +| Snowe | Luxe Considered | Cream palette; minimal kitchenware aesthetic | + +## Vertical-specific adaptation notes + +- **Lifestyle photography is the foundation**: the archetype rides on environmental photography quality. Bad room photography kills any archetype in this vertical. +- **Product-in-context dominates**: the bedding on a real bed, the chair in a real room. Product-on-white works only for technical specifications, not for hero photography. +- **Material and craftsmanship narrative**: how the brand discusses what the product is made of carries archetype weight. Luxe Considered uses material story heavily; Warm Conversational uses it lightly. +- **Sustainability framing**: increasingly default in this vertical; the archetype must accommodate it without leaning preachy. + +## Common archetype evolution + +Home brands frequently start Warm Conversational at launch and pull toward Luxe Considered as they raise prices and add product lines. Parachute's evolution shows this: launch era was more Warm Conversational; current Parachute is firmly Luxe Considered. Brooklinen has stayed Warm Conversational by intentionally holding its accessibility positioning. + +The mature-stage shift is usually: dial back the brand color, lean into typography and photography, drop overt accessibility framing. + +## Vertical anti-patterns + +- **Technical Precise in home goods**: completely incompatible. +- **Vibrant Saturated in home goods**: works only at the kids and novelty edge; reads as cheap on premium furniture and bedding. +- **Rugged Utilitarian**: works only when the brand is genuinely heritage-craftsman (cast iron, woodworking); slips into costume on mainstream home goods. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md new file mode 100644 index 0000000..1677ab1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md @@ -0,0 +1,43 @@ +# DTC: Food and Beverage + +## Vertical summary + +Brands selling beverages, snacks, supplements, and packaged food directly to consumers. Audience values: ingredient transparency, taste promise, and category disruption framing. The vertical is dominated by challenger brands using nostalgic-or-bold positioning to break into commoditized categories (soda, water, snacks, protein, energy drinks). + +## Common archetypes in this vertical + +The dominant archetype right now is **Retro Nostalgic** (Olipop, Liquid Death, Poppi), differentiating by era pick more than by archetype switch. **Bold Confident** appears at the energy and functional drink edge (AG1, Athletic Brewing). **Minimal Essentialist** appears at the clean-label edge (RXBar). **Vibrant Saturated** appears at the wellness-with-personality edge (Recess). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Olipop | Retro Nostalgic (70s lean) | Wellness-soda category creator; 70s wellness palette and type | +| Liquid Death | Retro Nostalgic (80s metal lean) | Water with metal-band branding; saturated metal aesthetic | +| Poppi | Retro Nostalgic (90s lean) | Pastel 90s palette; gut-health soda | +| AG1 (Athletic Greens) | Bold Confident | Black plus saturated green; premium green-powder positioning | +| RXBar | Minimal Essentialist | Black on white; no-bullshit label as brand identity | +| Athletic Brewing | Bold Confident with retro undertones | Non-alcoholic beer; heritage type plus modern energy | +| Recess | Retro Nostalgic (70s wellness lean) | Pastel palette; CBD and adaptogens with chill positioning | +| Magic Spoon | Retro Nostalgic (90s cereal lean) | Adult cereal with 90s saturated palette | +| Olly | Retro Nostalgic with Playful Energetic notes | Mass-market vitamins with playful 70s wellness register | +| Bare Performance Nutrition | Bold Confident | Black plus saturated accent; performance-supplement register | + +## Vertical-specific adaptation notes + +- **Era pick is the differentiation strategy**: the F and B challenger category is dominated by Retro Nostalgic right now. Brands differentiate primarily by which era they reference, not by which archetype they pick. +- **Packaging design is integrated with digital**: the can, bottle, or box on the website is the brand. Packaging design must lead the digital brand expression. +- **Ingredient transparency is default**: nutrition facts, ingredient lists, and provenance stories must accommodate the archetype. +- **Subscription mechanics**: many F and B brands are subscription-driven; the archetype must extend cleanly into subscription management and unsubscribe surfaces. + +## Common archetype evolution + +F and B challenger brands frequently start strong in Retro Nostalgic and stay there. The brand identity is the era choice. Brands that try to evolve away from their original era reference usually lose differentiation. + +Mature brands sometimes dial back the era reference as they enter mass distribution: Olipop's recent surfaces are subtler about the 70s reference than its original launch. + +## Vertical anti-patterns + +- **Editorial Restrained in F and B**: works only at premium spirits and craft chocolate; reads as wrong-category for mass beverage and snack. +- **Technical Precise**: completely incompatible. +- **Generic minimalism**: F and B is so saturated with retro-and-bold brands that Minimal Essentialist works only when the brand has a sharp specific reason to be minimal (RXBar's no-bullshit label is the canonical case). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md new file mode 100644 index 0000000..3a97ae8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md @@ -0,0 +1,43 @@ +# Consumer Health and Wellness + +## Vertical summary + +Brands serving consumers across telehealth, mental wellness, fitness, supplements, and self-care. Audience values: trust signals, clinical credibility, and emotional positioning around health. The vertical splits between mental health (which leans warmer and softer) and physical health (which leans clinical and trust-led). + +## Common archetypes in this vertical + +The dominant archetypes split by mental versus physical: **Clinical Trustworthy** for telehealth and physical-meds (Hims, Ro, Cerebral, Care/of); **Warm Conversational** and **Playful Energetic** for mental wellness (Calm, Headspace); **Vibrant Saturated** at the gen-Z mental health edge (Bumble Health). **Editorial Restrained** appears at the longevity-clinic edge (Function Health). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Hims | Clinical Trustworthy with peach warmth | Mens-health telehealth; warm tone breaks pharmaceutical cold | +| Hers | Clinical Trustworthy with warm accent | Womens-health telehealth; same brand system, womens lens | +| Ro | Clinical Trustworthy | Trust-blue palette; multi-condition telehealth | +| Care/of | Clinical Trustworthy with Warm Conversational | Personalized supplements; warm trust register | +| Cerebral | Clinical Trustworthy | Mental-health telehealth; restraint signals seriousness | +| Calm | Vibrant Saturated with restraint | Sleep-and-meditation; gradient-rich; soft palette | +| Headspace | Playful Energetic | Orange brand; character-illustration-driven; meditation-with-personality | +| Talkspace | Clinical Trustworthy | Therapy access; cool palette; trust signals | +| Function Health | Editorial Restrained | Longevity testing; type-led restraint; institutional confidence | +| Whoop | Technical Precise | Performance health; data-density; athlete positioning | + +## Vertical-specific adaptation notes + +- **Mental versus physical health split**: mental health brands lean warmer (Calm, Headspace, Talkspace); physical health brands lean clinical (Hims, Ro). The audience signals differ; the archetype must match. +- **Regulatory copy** affects voice. FDA disclaimers, medical disclaimers, prescription-required notices must accommodate the archetype. +- **Trust through specificity**: vague claims undermine the archetype. Specific dosages, specific evidence, specific licensed-clinician credentials carry the brand. +- **Subscription-and-cancellation flows**: the archetype must extend into ongoing subscription management; brands often lose trust here when the archetype breaks. + +## Common archetype evolution + +Health and wellness brands frequently stay in their original archetype but refine. Hims has stayed Clinical Trustworthy with growing warmth as it expanded categories. Calm has stayed in its restrained-vibrant lane as it expanded from meditation to sleep to broader wellness. + +Mental wellness brands that try to add physical-health products (or vice versa) often struggle to extend the archetype; the brand may need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- **Bold Confident in clinical wellness**: reads as overpromising. Health categories punish overpromise heavily. +- **Rugged Utilitarian**: works only in performance-athletic wellness; reads wrong in mainstream health. +- **Vibrant Saturated in physical health**: works only at younger-audience edges (Bumble Health for college students); reads wrong in mainstream telehealth. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md new file mode 100644 index 0000000..8b0b68a --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md @@ -0,0 +1,43 @@ +# Hospitality and Travel + +## Vertical summary + +Brands across hotels, short-term rentals, travel platforms, and travel-adjacent services. Audience values: trust signals (especially for booking platforms), aesthetic alignment (for hotels and properties), and experiential promise. The vertical is photography-dominated; the archetype rides on photo direction. + +## Common archetypes in this vertical + +The dominant archetypes are **Documentary Honest** (Airbnb in marketing, Selina, Hostelworld) and **Luxe Considered** (Aman, Four Seasons, premium hotel collections). **Editorial Restrained** appears at the hotel-tech edge (Sonder). **Minimal Essentialist** appears at travel-product brands (Away). **Bold Confident** at the disruptor edge (Hopper). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Airbnb | Documentary Honest | Real-photography of real homes; experiential framing | +| Aman | Luxe Considered (extreme) | Pure luxury hospitality; serif-led; understated authority | +| Four Seasons | Luxe Considered | Premium hotel chain; institutional luxury aesthetic | +| Selina | Documentary Honest | Lifestyle hotels; real-photography; community framing | +| Sonder | Editorial Restrained | Boutique short-stay; type-led; quiet confidence | +| Away | Minimal Essentialist | Travel luggage; minimal product photography; restrained type | +| Marriott Bonvoy | Luxe Considered | Loyalty program brand; aspirational typography | +| Hopper | Bold Confident | Saturated brand; price-prediction positioning | +| Hostelworld | Playful Energetic | Backpacker positioning; multi-color; younger-audience | +| Tripadvisor | Warm Conversational | Trust-through-reviews; friendly approachable register | + +## Vertical-specific adaptation notes + +- **Photography defines the vertical**: the archetype is downstream of photo direction. Brands without exceptional photography cannot execute Documentary Honest or Luxe Considered. +- **Booking flow versus discovery flow**: the brand must extend across both surfaces. Booking flow leans toward trust signals (Clinical Trustworthy notes); discovery flow leans toward aspiration (the chosen archetype). +- **Trust signals matter**: reviews, ratings, cancellation policies must appear with archetype-appropriate weight. Luxe Considered makes trust signals understated; Documentary Honest puts them alongside imagery. +- **Multi-property versus single-property**: hotel chains (Marriott, Hilton) face different brand challenges than single-property luxury (Aman individual properties). The archetype must scale. + +## Common archetype evolution + +Hospitality brands frequently stay in their original archetype. Airbnb has stayed Documentary Honest through multiple rebrand iterations. Aman has stayed Luxe Considered since launch. Travel-product brands (Away) have stayed Minimal Essentialist. + +Brands that try to switch archetypes (for example a budget brand trying to feel premium without raising prices) usually fail to land. + +## Vertical anti-patterns + +- **Technical Precise in hospitality**: completely incompatible. +- **Rugged Utilitarian in mainstream hospitality**: works only at adventure-travel edges (REI Adventures); reads wrong in city hotels. +- **Vibrant Saturated in luxury hospitality**: undermines the premium positioning immediately. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md new file mode 100644 index 0000000..588967b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md @@ -0,0 +1,43 @@ +# Media and Publishing + +## Vertical summary + +Brands across digital publications, newsletters, books, podcasts, and editorial platforms. Audience values: editorial voice, intellectual rigor, and reading experience quality. The vertical is dominated by typography; the archetype rides on type system more than on color or photography. + +## Common archetypes in this vertical + +The dominant archetypes are **Editorial Restrained** (Substack, The Browser, Bloomberg, NYT Cooking) and **Luxe Considered** (Stripe Press, premium book design). **Minimal Essentialist** appears at the classic-publishing edge (Medium in its restrained era). **Documentary Honest** appears at journalism-as-brand (NYT visual journalism). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Substack | Editorial Restrained | Serif-led; cream paper; type-as-product | +| Stripe Press | Luxe Considered | Premium book design; typography excellence; collector-grade | +| The Browser | Editorial Restrained | Restrained newsletter; type-led; institutional reading register | +| NYT Cooking | Editorial Restrained | Recipe-focused; serif typography; brand-trust-through-restraint | +| Bloomberg | Editorial Restrained | Financial publishing; high-density information; institutional confidence | +| The Information | Editorial Restrained | Tech business journalism; type-led; subscriber-business model | +| Medium (classic) | Minimal Essentialist | Original era was pure restrained sans; recent evolution warmer | +| The New York Times | Editorial Restrained | Canonical example; serif-led; institutional journalism | +| Defector | Editorial Restrained with personality | Worker-owned sports; restrained with editorial voice | +| Lithub | Editorial Restrained | Literary publishing; serif throughout; reading-first | + +## Vertical-specific adaptation notes + +- **Type system carries the brand**: in media and publishing, the typography is the brand. Most archetype decisions are font-pair decisions. +- **Reading experience as primary surface**: the article page must lead the brand expression. Marketing surfaces follow the article-reading experience. +- **Long-form versus short-form**: long-form journalism brands lean Editorial Restrained or Documentary Honest; newsletter and short-form brands have more archetype range. +- **Subscription mechanics**: paywall surfaces, subscription management, and unsubscribe flows must extend the archetype. Brands often lose archetype coherence at these surfaces. + +## Common archetype evolution + +Media brands frequently stay in their original archetype. Substack has stayed Editorial Restrained since launch. The New York Times has stayed Editorial Restrained for over a century. Bloomberg has stayed Editorial Restrained through multiple redesigns. + +Brands that try to add personality to a restrained archetype (Medium's attempts to feel warmer over time) often produce confusion. The discipline is the brand. + +## Vertical anti-patterns + +- **Bold Confident in journalism**: undermines credibility; reads as opinion-blog rather than reporting. +- **Vibrant Saturated in publishing**: works only at children's-publishing and novelty edges. +- **Technical Precise in media**: works only at niche publications (tech-focused) and reads wrong elsewhere. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md new file mode 100644 index 0000000..7b3d29b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md @@ -0,0 +1,43 @@ +# EdTech + +## Vertical summary + +Brands across K-12 learning, higher education, professional development, and consumer learning apps. Audience splits sharply by age and learning context: children's apps lean playful; professional development leans clinical; consumer learning leans warm; technical education leans precise. The vertical rewards personality on the consumer side and authority on the institutional side. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Playful Energetic** for K-12 and habit-forming consumer learning (Duolingo, Khan Academy Kids). **Warm Conversational** for adult consumer learning (Khan Academy, Brilliant). **Clinical Trustworthy** for professional development (Coursera, edX). **Luxe Considered** for premium adult education (MasterClass). **Technical Precise** for technical education (Codecademy, Frontend Masters). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Duolingo | Playful Energetic (canonical) | Owl mascot; saturated green; character-driven habit formation | +| Khan Academy | Warm Conversational | Friendly approachable; muted palette; non-profit mission framing | +| Brilliant | Bold Confident leaning Warm Conversational | Math-and-science learning; saturated palette; problem-solving register | +| MasterClass | Luxe Considered | Premium adult education; editorial photography; celebrity-instructor positioning | +| Codecademy | Technical Precise | Developer education; dark mode; code-first | +| Coursera | Clinical Trustworthy | Higher-ed-credentialed; cool palette; institutional partnerships | +| edX | Clinical Trustworthy | University-courses-online; restrained academic register | +| Udemy | Warm Conversational | Mass-market courses; multi-hue palette; accessible pricing | +| Outschool | Playful Energetic with Warm Conversational | K-12 small-group learning; warm illustration; family register | +| Frontend Masters | Technical Precise | Developer-focused; dark mode; instructor-as-authority | + +## Vertical-specific adaptation notes + +- **Audience age determines archetype**: K-12 leans playful; teens lean bold; adults lean warm or clinical; technical learners lean precise. Pick the audience first. +- **Habit formation versus information transfer**: habit-formation products (language apps, daily-skill apps) lean playful. Information-transfer products (course platforms, lectures) lean restrained or clinical. +- **Credential signaling**: institutional partnerships, certifications, accreditation must appear with archetype-appropriate weight. Clinical Trustworthy makes them prominent; Playful Energetic makes them secondary. +- **Progress mechanics**: streaks, badges, leveling are core to many edtech products. The archetype must extend into gamification surfaces. + +## Common archetype evolution + +Edtech brands frequently start in their target audience archetype and stay. Duolingo has stayed Playful Energetic since launch (with increasing character development). Coursera has stayed Clinical Trustworthy. MasterClass has stayed Luxe Considered. + +Brands that try to switch (a K-12 brand attempting to add adult learning) usually need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- **Playful Energetic for adult professional development**: reads as unserious; adult learners reject playful brand expression for credential-building. +- **Clinical Trustworthy for K-12**: reads as cold and unfriendly to children and parents. +- **Rugged Utilitarian**: works only at outdoor-education edge (NOLS, Outward Bound); reads wrong elsewhere. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md new file mode 100644 index 0000000..86dba90 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md @@ -0,0 +1,43 @@ +# Gaming and Entertainment + +## Vertical summary + +Brands across gaming platforms, streaming services, game studios, and entertainment apps. Audience values: cultural alignment with the gaming or entertainment subculture, content discovery, and community signals. The vertical splits between platform brands (chrome that hosts content) and content brands (the games or shows themselves). Platforms tend toward restraint to let content carry; content brands lean toward expression. + +## Common archetypes in this vertical + +The dominant archetypes are **Bold Confident** (Epic Games, Riot, Discord) and **Vibrant Saturated** (Discord with character, Twitch). **Editorial Restrained** appears at the platform-chrome edge (Steam at category level). **Retro Nostalgic** appears at indie-gaming and arcade-revival brands. **Minimal Essentialist** appears at platform-distributor edges (Itch.io). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Discord | Vibrant Saturated with character | Multi-hue brand palette; community-focused; playful chrome | +| Steam | Editorial Restrained at category level | Platform chrome restrained to let games lead; dark mode dominant | +| Twitch | Vibrant Saturated | Saturated purple; live-streaming positioning | +| Epic Games | Bold Confident | Strong brand colors; platform energy | +| Riot Games | Bold Confident | Saturated brand; competitive-gaming positioning | +| Itch.io | Minimal Essentialist | Indie game platform; minimal chrome; lets games carry | +| Spotify (entertainment) | Vibrant Saturated | Saturated green; mood-based personalization | +| Netflix | Bold Confident | Black plus red; content-as-hero; minimal platform chrome | +| HBO Max (Max) | Editorial Restrained leaning Luxe Considered | Premium streaming positioning; restrained type | +| Roblox | Playful Energetic | Multi-color brand; family-friendly positioning | + +## Vertical-specific adaptation notes + +- **Platform versus content distinction**: platform brands (the place where games or shows live) lean toward restraint to avoid competing with content. Content brands (individual games, shows, studios) lean toward expression. +- **Dark mode dominance**: most gaming and entertainment surfaces lean dark-mode-first to support content viewing. +- **Subculture signaling**: gaming brands often signal subculture alignment (esports, indie, MMO, casual mobile). The archetype must extend to subculture-appropriate visual cues. +- **Live and real-time experiences**: many brands in this vertical have real-time surfaces (live streams, multiplayer lobbies) that affect archetype expression. + +## Common archetype evolution + +Gaming brands frequently choose archetypes orthogonal to their content. Discord is Vibrant Saturated despite hosting communities of every register. Steam is Editorial Restrained despite hosting saturated games. The platform chrome makes a brand decision separate from the content's character. + +Mature platforms sometimes pull back ornamentation to let content lead (Netflix's evolution toward minimalist chrome shows this). + +## Vertical anti-patterns + +- **Clinical Trustworthy in gaming**: incompatible; gaming audiences reject clinical framing. +- **Rugged Utilitarian**: works only at simulation-and-mil-sim edges; reads wrong on mainstream gaming. +- **Luxe Considered in mass gaming**: works only at premium subscription tiers (Max, Apple TV Plus); reads wrong on free-to-play and casual. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md new file mode 100644 index 0000000..2148be5 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md @@ -0,0 +1,43 @@ +# Marketplace + +## Vertical summary + +Brands operating two-sided platforms connecting buyers and sellers across categories: handmade goods, secondhand, niche-expert, livestream commerce, B2B wholesale. Audience values: trust signals, seller quality verification, and category authority. Marketplace brands face a unique brand challenge: the platform brand interacts with hundreds or thousands of seller brands, and the platform must hold an identity that does not compete with seller identities. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Etsy, Faire in marketing) and **Bold Confident** (StockX, Whatnot). **Editorial Restrained** appears at the niche-expert edge (Reverb). **Vibrant Saturated** appears at the gen-Z commerce edge (Depop). **Documentary Honest** at the artisan-commerce edge (Etsy's seller stories). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Etsy | Warm Conversational with craft emphasis | Handmade marketplace; warm palette; seller-story framing | +| Reverb | Editorial Restrained with niche-expert voice | Musical instruments; type-led; expertise-as-trust | +| Faire | Editorial Restrained | Wholesale marketplace; restrained type; B2B confidence | +| StockX | Bold Confident | Sneakers and streetwear; saturated brand; market-data positioning | +| Whatnot | Bold Confident | Livestream commerce; saturated palette; energy register | +| Depop | Vibrant Saturated | Gen-Z fashion resale; bright multi-hue palette | +| Vinted | Warm Conversational | European resale; cream palette; friendly approach | +| eBay | Bold Confident | Established marketplace; high-energy multi-color brand | +| Mercari | Warm Conversational | Resale marketplace; soft palette; approachable | +| Substack (creator marketplace) | Editorial Restrained | Newsletter marketplace; serif type; creator-economy framing | + +## Vertical-specific adaptation notes + +- **Platform brand versus seller brands**: the marketplace brand must hold an identity that does not compete with seller brands. Restraint often wins; let sellers carry visual energy. +- **Trust signals matter heavily**: ratings, reviews, return policies, seller verification carry brand weight. The archetype must give trust signals appropriate space. +- **Multi-category challenge**: marketplaces frequently span many product categories. The brand must work for fashion, electronics, home goods, and handmade simultaneously. +- **Buyer-side versus seller-side surfaces**: marketplace brands often have parallel surfaces for buyers (consumer-facing) and sellers (creator-or-merchant facing). The archetype must extend coherently to both. + +## Common archetype evolution + +Marketplace brands frequently start in their original archetype and stay. Etsy has stayed Warm Conversational since its early days (with refinements). StockX has stayed Bold Confident since launch. + +Brands that try to switch archetypes (Etsy's brief attempts at more polished marketing in the late 2010s) usually pull back to their original positioning. + +## Vertical anti-patterns + +- **Luxe Considered in mass-market marketplaces**: works only at curated-luxury marketplaces (1stDibs, Sotheby's); reads out-of-place elsewhere. +- **Technical Precise**: works only at B2B infrastructure marketplaces (Faire's developer-tools edge); reads wrong on consumer. +- **Clinical Trustworthy**: incompatible; reads as cold and corporate where marketplaces need community feeling. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md new file mode 100644 index 0000000..6a1e674 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md @@ -0,0 +1,43 @@ +# Crypto and Web3 + +## Vertical summary + +Brands across crypto exchanges, wallets, NFT platforms, DeFi protocols, and Web3 infrastructure. Audience splits between consumer (Coinbase-tier accessibility) and infrastructure (developer-and-builder-tier precision). The vertical has unusual archetype range because crypto culture spans speculative-energy to cypherpunk-minimal to artist-luxe. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Bold Confident** for consumer crypto (Coinbase, OpenSea, Rainbow). **Technical Precise** for protocol and infrastructure (Anchor, Alchemy). **Editorial Restrained** at the writing-and-publishing edge (Mirror). **Luxe Considered** at the NFT-art edge (Foundation, Async Art). **Vibrant Saturated** at the consumer-wallet edge (Rainbow). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Coinbase | Bold Confident with blue | Trust-blue palette; mainstream-consumer positioning | +| OpenSea | Bold Confident | Saturated palette; NFT marketplace energy | +| Mirror | Editorial Restrained | Decentralized publishing; serif-led; restrained confidence | +| Foundation | Luxe Considered | NFT art marketplace; cream palette; curated-gallery feeling | +| Rainbow | Vibrant Saturated | Multi-hue wallet brand; gradient-rich; consumer-friendly | +| Phantom | Bold Confident with purple | Solana wallet; saturated brand; consumer-tilted | +| Uniswap | Bold Confident with Vibrant Saturated | DeFi protocol; pink-and-saturated brand; consumer-DeFi | +| Alchemy | Technical Precise | Web3 infrastructure; developer-facing; cool palette | +| Polygon | Bold Confident | Layer-2 infrastructure; saturated purple; institutional positioning | +| Async Art | Luxe Considered | Programmable art; restrained gallery aesthetic | + +## Vertical-specific adaptation notes + +- **Consumer versus infrastructure split**: consumer brands (Coinbase, Rainbow, Phantom) lean energetic and friendly. Infrastructure brands (Alchemy, Anchor) lean toward Technical Precise. The archetype must match the audience. +- **Trust signals matter**: regulatory framing, audit reports, security signals must accommodate the archetype. Bold Confident makes them inline; Technical Precise gives them dedicated surfaces. +- **Cultural alignment**: crypto culture has subcultures (cypherpunk, DeFi-degen, NFT-collector, builder). Brands must signal which subculture they speak to. +- **Compliance copy**: increasing regulatory pressure (especially post-2024) affects brand voice; the archetype must accommodate disclaimers without breaking. + +## Common archetype evolution + +Crypto brands frequently shift archetype as the regulatory environment matures and as they target broader audiences. Coinbase has moved from more energetic to more institutional over its lifetime. Many crypto brands started Vibrant Saturated (matching crypto culture energy of 2021-2022) and pulled back toward Bold Confident or Editorial Restrained. + +The mature-stage shift is typically: dial back the saturation, add trust signals, lean into typographic restraint without losing the consumer accessibility. + +## Vertical anti-patterns + +- **Warm Conversational in crypto**: works only at extremely consumer-tilted onboarding products; reads wrong on most surfaces. +- **Rugged Utilitarian**: incompatible. +- **Clinical Trustworthy in pure DeFi**: reads as trying to be a bank; works only at the regulated-stablecoin edge. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md new file mode 100644 index 0000000..d04cc2f --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md @@ -0,0 +1,44 @@ +# Real Estate and Proptech + +## Vertical summary + +Brands across residential real estate platforms, premium real estate, proptech tools, and home-buying products. Audience splits sharply by price point: premium residential real estate leans Luxe Considered universally; mass-market platforms split between Warm Conversational, Bold Confident, and Clinical Trustworthy. The vertical rewards trust signals across every archetype because real estate transactions are high-value, high-friction, and infrequent. + +## Common archetypes in this vertical + +The dominant archetypes are **Luxe Considered** at the premium tier (Compass, Sotheby's International Realty, Pacaso). **Bold Confident** at the disruptor tier (Opendoor, Sundae). **Warm Conversational** at the consumer-information tier (Zillow). **Clinical Trustworthy** at the technology-platform tier (Redfin). **Editorial Restrained** at the proptech-software edge (some commercial real estate platforms). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Compass | Luxe Considered | Premium residential; serif typography; agent-network positioning | +| Zillow | Warm Conversational at consumer edge | Friendly approachable; muted palette; consumer-information register | +| Redfin | Clinical Trustworthy | Cool palette; technology-platform positioning; agent-as-employee model | +| Opendoor | Bold Confident | Saturated brand; instant-offer disruption framing | +| Sundae | Bold Confident | Saturated brand; off-market-property positioning | +| Pacaso | Luxe Considered | Co-ownership of vacation homes; premium photography; lifestyle framing | +| Sotheby's International Realty | Luxe Considered (extreme) | Pure premium real estate; serif throughout; institutional luxury | +| Cadre | Editorial Restrained | Commercial real estate investment platform; restrained type | +| Knock | Bold Confident | Home-trade-in services; saturated brand | +| Vacasa | Warm Conversational with Documentary Honest | Vacation rental management; real-photography of properties | + +## Vertical-specific adaptation notes + +- **Premium versus mass-market split is sharp**: premium real estate is universally Luxe Considered; mass-market splits into three or four archetypes based on positioning. +- **Photography is critical**: real estate brands depend on excellent property photography. The archetype rides on photo direction. +- **Trust signals across every archetype**: license info, agent credentials, customer reviews, third-party certifications must appear with appropriate weight. Premium archetypes make these understated; consumer archetypes make them prominent. +- **Local versus national**: many real estate brands operate hyper-locally (individual agents and small brokerages). The archetype must extend to local agent-branded surfaces. + +## Common archetype evolution + +Real estate brands frequently stay in their original archetype. Compass has stayed Luxe Considered since launch. Zillow has stayed Warm Conversational. Redfin has stayed Clinical Trustworthy. + +Brands that try to switch archetypes (a mass-market brand attempting to feel premium) usually struggle to convince either audience. Real estate is unusually punishing of inauthentic positioning. + +## Vertical anti-patterns + +- **Vibrant Saturated in real estate**: incompatible; reads as untrustworthy with high-value transactions. +- **Playful Energetic**: incompatible. +- **Rugged Utilitarian**: works only at vacation-property and recreational-land edges; reads wrong on mainstream residential. +- **Technical Precise**: works only at commercial real estate analytics platforms (CoStar tier); reads wrong on consumer. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md new file mode 100644 index 0000000..0af4a7c --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md @@ -0,0 +1,119 @@ +# Editorial Restrained + +## Aesthetic summary + +Low-saturation, type-led, generous whitespace. Considered rather than performed. The brand earns attention through restraint instead of demanding it through volume. Reads as institutional confidence without stiffness. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (warm but precise, comfortable with first person) +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0F1B2D | Primary text, body, anchors | +| ink-muted | #1F2D44 | Secondary text | +| paper | #FAF9F6 | Warm off-white background | +| paper-soft | #F3F1EC | Card surfaces, subtle elevation | +| accent | #5B8B85 | Single accent for links and key actions | +| accent-muted | #3F6E55 | Hover states, secondary accent applications | +| highlight | #C9A227 | Numeric callouts, display sizes only | +| highlight-body | #8E6E1A | Same hue at body-text contrast (WCAG AA) | +| line | #EDEFF2 | Borders, separators | + +Rationale: +- Ink at #0F1B2D not pure black. Pure black on warm paper feels harsh; navy ink reads as ink-on-paper. +- Paper at #FAF9F6 not pure white. Warm tint signals editorial register versus UI register. +- Accent restricted to one hue. Two-color systems read as institutional; multi-color reads as consumer. +- Highlight restricted to display sizes; the body-contrast variant (#8E6E1A) covers WCAG AA at smaller scales without losing the warm-gold character. + +## Type pairing starter + +- **Display**: IBM Plex Serif (Google Fonts, free). 700 for hero, 600 for sections. +- **Body**: Inter (Google Fonts, free). 400 for prose, 500 for UI labels. +- **Numerics**: JetBrains Mono (Google Fonts, free). 400 to 500 for KPIs and code. + +Size scale (modular, 1.2 ratio anchored at 16px): +- Hero: 56 to 72px serif +- H2: 32 to 40px serif +- H3: 22 to 26px serif +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Mono: 14 to 16px monospace + +Pairing rationale: serif display plus sans body is the classic editorial pairing (NYT, magazines). IBM Plex specifically has open apertures and modest contrast that reads as institutional but modern. JetBrains Mono for numbers communicates precision without being overtly technical. + +## Layout and composition + +- Generous whitespace. Sections separated by 96 to 128px vertical rhythm minimum. +- Single-column hero, content left-aligned, max-width around 720px for prose. +- Asymmetric grids on landing pages: 2-column with deliberate imbalance (40/60 or 60/40) more often than centered or 50/50. +- Density: low. The page should breathe. +- Cards: subtle elevation via 1px line border at line color, no drop shadows. + +## Imagery direction + +- Photography: editorial, low-touched, real environments, natural light. +- Illustration: rare. If used, line-only, single color, technical drawing register. +- Product UI: shown in stylized chrome with branded surfaces; rarely the actual app screenshot. +- Decorative imagery: avoided. Everything earns its place. + +## Voice samples + +- "Built around the question, not against the event stream." +- "Real components, real brand foundations, real working forms." +- "The measurement surface PLG teams actually need." +- "Onboarding metrics live in the cracks between general-purpose tools." +- "Focused, not just smaller." +- "Sample funnel, real benchmarks, your cohort." +- "Pre-built activation funnels. Time-to-first-value benchmarking." + +Cadence: complete sentences. Comma-separated qualifiers more often than dashed asides. Direct claims with built-in qualification. No exclamation marks. Numerals over written numbers. + +## Component pattern descriptions + +**Hero**: Eyebrow (uppercase, accent color, letterspaced 0.16em), then serif headline 56 to 72px, then sans subhead 18px paragraph, then 2 buttons (primary solid ink, secondary outline), optional KPI strip below. + +**Buttons**: Primary is solid ink, white text. Secondary is white surface, ink border 1px, ink text. No gradients. No drop shadows. Hover state shifts opacity to 0.9 or fills the secondary surface. + +**Cards**: Paper-soft background, 1px line border, 24 to 32px internal padding. Numerals top-left in mono. Title in serif. Body in sans. + +**Tables**: Paper-soft header row, line color separators between rows, monospace numerics aligned right. + +## When to pick this + +- B2B brand for a measured, considered audience (PMs, engineers, founders, finance) +- Category is loud and your differentiation is calm +- Product earns attention through depth rather than novelty +- Audience reads documentation and trusts restraint + +## When to avoid + +- Consumer brand for an audience that wants energy and warmth +- Product that needs to feel inviting at first touch +- Category where competitors are already restrained (you will disappear) +- Brand that needs to communicate playfulness or character + +## Adaptation guidance + +When applying this archetype to a specific brief: + +1. **Keep the structure** (whitespace, single-accent, restrained type pairing). Adapt specific values. +2. **Color**: shift accent hue to match emotional direction. Muted teal feels rational; muted plum feels considered; muted moss feels grounded; muted slate feels institutional. +3. **Type**: IBM Plex Serif is a starting point. Substitutes that fit: GT Sectra, Tiempos, Fraunces, Source Serif. +4. **Density**: dial up or down based on audience. Developers tolerate more density; founders prefer more whitespace. +5. **Highlight color**: optional. Brands without a numeric story do not need it. + +Direct copying of all defaults verbatim produces generic Editorial Restrained output. The brief should produce a meaningful variant. + +## Exemplar brands + +Editorial Restrained is exemplified by Linear, Vercel, Stripe Press, Resend, and the fictional Threshold reference build in this catalog. Earlier examples include Pentagram's institutional work and the early Medium publication system. + +These brands share: serif display, sans body, single accent, generous whitespace, editorial photography or stylized product UI, peer-relationship voice. + +The archetype overlaps with Technical Precise (Stripe docs, Sentry); blended brands typically use Editorial Restrained for marketing surfaces and Technical Precise for documentation surfaces. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md new file mode 100644 index 0000000..8180aea --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md @@ -0,0 +1,122 @@ +# Technical Precise + +## Aesthetic summary + +Monospace prominent in display and numerics. Grid visible in compositions. Data density tolerated and embraced. Dark mode often dominant. Cool palette with high precision feel. The brand communicates that it understands the technical substance of what it is selling, and that its audience does too. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (precise, low-affect, treats the reader as informed) +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Functional + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0A0E1A | Light-mode primary text | +| ink-muted | #1F2937 | Light-mode secondary text | +| paper | #FFFFFF | Light-mode background | +| paper-soft | #F6F8FA | Light-mode card surface | +| surface-dark | #0F1117 | Dark-mode primary background | +| surface-dark-elevated | #161922 | Dark-mode card surface | +| text-dark | #E6E9F2 | Dark-mode primary text | +| text-dark-muted | #9DA4B4 | Dark-mode secondary text | +| accent | #7C5CFF | Saturated single accent (violet shown) | +| accent-muted | #5B3FD6 | Active state | +| signal-success | #16A34A | Positive numeric signal | +| signal-warn | #F59E0B | Caution signal | +| signal-error | #DC2626 | Error signal | +| line | #2A2F3C | Dark-mode line, panel separators | + +Rationale: +- Dark mode is first-class; the palette is built dark-mode primary with light-mode adaptations. +- Single saturated accent (violet, electric blue, lime, or cyan) lets the rest of the palette stay neutral. +- Signal colors are functional, not decorative; reserved for status communication in dashboards and logs. +- Lines visible (#2A2F3C in dark, #E5E7EB in light) to reinforce the grid character. + +## Type pairing starter + +- **Display**: Geist Sans (Vercel, free) or Inter Display. 600 to 700 weight. +- **Body**: Geist Sans or Inter. 400 to 500. +- **Monospace**: Geist Mono or JetBrains Mono. Prominent in display, numerics, code samples, KPIs, badges, and labels. + +Size scale (modular, 1.25 ratio anchored at 15px for higher density): +- Hero: 48 to 64px sans +- Hero-mono: 36 to 48px mono (for technical brands using mono in display) +- H2: 28 to 36px sans +- Body: 15 to 16px sans +- Small: 13px sans +- Code: 14 to 15px mono + +Pairing rationale: Geist (and its mono variant) was designed specifically for technical product interfaces. Inter plus JetBrains Mono is the equivalent if Geist is not available. The mono should appear regularly enough that the reader registers the brand uses it deliberately. + +## Layout and composition + +- Higher density than Editorial Restrained. The reader expects information. +- Grids are visible: hairline borders on cards and tables, monospace coordinates in nav, table-of-contents sidebars. +- Code samples are treated as primary content, not supplementary. +- Hero often pairs a clean headline with a live-looking product surface (dashboard, terminal, code editor). +- Dark mode is the design target; light mode is the adaptation. + +## Imagery direction + +- Photography: rare. When used, abstract or product-context, not people. +- Illustration: technical diagrams, network graphs, architecture maps. Single accent color over neutral background. +- Product UI: shown as real screenshots or near-real chrome. The product surface itself is the brand asset. +- Decorative imagery: minimal. The information density is the visual. + +## Voice samples + +- "Latency p99: 47ms across 12 regions." +- "Idempotent by default. Versioned endpoints. Zero-downtime migrations." +- "Built for the request volume you actually have at 3am." +- "Error budgets, not vibes." +- "Your stack already speaks this protocol." +- "Run it locally. Deploy it globally. Same primitives." +- "Observability that does not require its own observability." + +Cadence: short. Often fragments. Numerals over words. Technical specificity over abstraction. Comfortable with industry vocabulary. + +## Component pattern descriptions + +**Hero**: Often split layout: left side is headline plus sub plus 2 CTAs, right side is a live product surface (terminal, dashboard, code editor). Or full-bleed dark with an oversized mono headline. + +**Buttons**: Primary is solid accent on dark, or solid ink on light. Secondary is bordered. Often a small mono prefix on labels ("$ deploy" pattern). + +**Cards**: Hairline border, dark-elevated background, monospace metadata in the header row, sans body. Often with a small status dot (signal color) in the corner. + +**Tables**: Dense. Hairline rows. Mono numerics, right-aligned. Hover state with a faint accent tint. Sortable columns marked. + +**Code blocks**: First-class. Syntax highlighting palette is part of the brand. Copy button. Language label. + +## When to pick this + +- Developer audience +- Observability, platform, infrastructure, or DX product +- Audience values data density and precise specification +- Brand needs to communicate "we built this, we run it, we understand it" + +## When to avoid + +- Consumer audience that wants warmth +- Product that is not technically substantive (the archetype will read as costume) +- Brand needs to communicate approachability over rigor +- Photography or human imagery is central to the brand story + +## Adaptation guidance + +1. **Accent hue**: violet for product-first brands, electric blue for infrastructure, lime or cyan for AI-adjacent, soft green for sustainability-leaning. +2. **Mono density**: dial up for developer brands (mono in hero, mono in nav, mono in labels) and dial down for prosumer brands wanting only the precision signal. +3. **Dark mode**: required. Skip this archetype if the brand cannot ship a dark mode. +4. **Photography**: if the brand needs human imagery, blend with Editorial Restrained or Warm Conversational instead of forcing it into Technical Precise. +5. **Voice density**: stay specific. Vague claims in this archetype read as worse than vague claims elsewhere, because the visual is promising specificity. + +## Exemplar brands + +Technical Precise is exemplified by Stripe (especially the documentation and developer surfaces), Sentry, Datadog, Vercel, Cursor, and Linear in its most technical surfaces. Adjacent older examples include the early Heroku CLI and the original GitHub UI before its consumer-tilted redesigns. + +These brands share: dark-mode-first, monospace prominent, code as first-class content, saturated single accent, dense tables and grids, low-affect voice. + +The archetype frequently blends with Editorial Restrained at the marketing surface level (Stripe's marketing pages, Vercel's announcements) while keeping the technical surface pure Technical Precise. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md new file mode 100644 index 0000000..82530ab --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md @@ -0,0 +1,114 @@ +# Warm Conversational + +## Aesthetic summary + +Human imagery, mid-saturation palette with warm undertones, approachable type, second-person voice. The brand reads as a colleague who genuinely wants to help rather than a vendor selling. Friendly without performance; honest without coldness. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational +- **Aesthetic register**: Considered +- **Audience relationship**: Companion +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1F2937 | Primary text | +| ink-muted | #4B5563 | Secondary text | +| paper | #FFFBF5 | Cream background | +| paper-soft | #FAF3E7 | Card surface | +| accent | #D97757 | Warm terracotta primary accent | +| accent-soft | #F3B690 | Tint of accent for backgrounds | +| accent-deep | #A75440 | Active state | +| support-green | #5A8A6E | Sage green secondary | +| support-blue | #5E8FA8 | Dusty blue secondary | +| line | #E8DFCF | Borders, separators on cream | + +Rationale: +- Cream background (not white) is the foundation; it signals warmth before any other element fires. +- Mid-saturation accent (terracotta shown) is warm and human; cooler accents (sage, dusty blue) appear as secondary tones rather than primaries. +- The palette is calibrated mid-saturation throughout; no value is below 35% or above 70% saturation. This is what produces the "considered warmth" reading instead of either pastel or vivid. +- Lines use a warm gray rather than neutral gray to keep coherence with the paper. + +## Type pairing starter + +- **Display**: Hubot Sans or Söhne or GT America. 600 to 700. +- **Body**: Same family for body, 400 to 500. Single-family systems read warmer than serif plus sans pairings. +- **Optional accent type**: a friendly humanist serif (Tiempos Text, Source Serif) for editorial moments inside otherwise sans content. + +Size scale (modular, 1.2 ratio anchored at 17px for comfortable reading): +- Hero: 48 to 64px sans +- H2: 30 to 38px sans +- H3: 22 to 26px sans +- Body: 17 to 19px sans (slightly larger than B2B default) +- Small: 14 to 15px sans + +Pairing rationale: single-family sans systems read warm and consistent. Humanist or geometric-humanist sans (Hubot, Söhne, GT America) have rounder shapes than neo-grotesques like Helvetica, which is what produces the "friendly" reading without sliding into childlike. Body sizes run slightly larger than other archetypes because the reader is expected to actually read. + +## Layout and composition + +- Comfortable density. Not as breathing as Editorial Restrained, not as dense as Technical Precise. +- Sections frequently use full-bleed photography or illustration as scene-setters. +- Hero often pairs a human photo (real customer, real team member) with a friendly headline. +- Generous interior padding inside cards and forms; the page feels welcoming rather than businesslike. +- Curved corners (8 to 16px) on cards and buttons; sharp corners read colder. + +## Imagery direction + +- Photography: real people, varied skin tones and body types, candid rather than posed, natural light, real environments (homes, coffee shops, offices that look lived-in). +- Illustration: custom illustration systems are common (Mailchimp's monkey era, Slack's hands-and-objects era). When used, illustration should have a consistent vocabulary rather than stock-feeling variety. +- Product UI: shown in real photo-context (laptop on a real desk) more often than stylized chrome. +- Stock photography pitfall: this archetype dies on bad stock photo selection. Curate hard or commission custom. + +## Voice samples + +- "Sign up takes about a minute. We will not ask for a credit card." +- "Here is what we tried, what worked, and what did not." +- "You probably do not need a meeting for this. But if you do, we can hop on one." +- "Made for teams who would rather get the work done than configure the tool that does the work." +- "Yes, we send fewer emails than other tools. On purpose." +- "We charge what we charge because that is what it costs to run the thing well." + +Cadence: complete sentences. Comfortable with first and second person. Contractions and hedging are fine; performed informality ("hey friend!") is not. Reads honest, not chummy. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 or 2 CTAs, often paired with a human photo or warm illustration. Background frequently cream (not white). Headline weight is mid-bold (600), not display-heavy. + +**Buttons**: Primary is solid accent, white text, 10 to 16px corner radius. Secondary is bordered or text-only. Hover states use a slight color deepening rather than opacity shift. + +**Cards**: Soft cream surfaces, 12 to 16px radius, generous padding (32 to 40px), shadow at low intensity (0 4px 12px rgba(0,0,0,0.04)). + +**Forms**: Generous field height (48 to 56px). Labels above inputs (not floating). Help text below fields. Pre-fill where possible. + +## When to pick this + +- Prosumer SaaS, team productivity, marketing tools at the consumer-leaning edge +- Brand needs to communicate "we get you" more than "we are best in class" +- Audience values approachability over rigor +- Brand wants to differentiate in a category of cold competitors + +## When to avoid + +- Audience that reads warmth as unserious (most developer infrastructure, most enterprise) +- Brand with limited photography or illustration budget (the archetype dies on bad imagery) +- Brand needs to communicate authority or expertise as the primary signal +- Category is already crowded with warm brands (you will disappear) + +## Adaptation guidance + +1. **Accent hue**: terracotta and warm orange feel grounded; sage green and dusty blue feel calm; coral and peach feel optimistic. Pick one primary based on emotional direction. +2. **Single-family vs paired type**: single-family sans is the default. If the brand needs editorial moments, add a humanist serif as the accent type, not as the body. +3. **Illustration vs photography**: pick one as primary. Brands trying to do both usually do neither well. +4. **Voice**: write honest first, friendly second. Performed friendliness without honest substance reads cheap. +5. **Density**: avoid over-roominess. The archetype tips into "marketing fluff" when the page is too breathing and the content is too thin. + +## Exemplar brands + +Warm Conversational is exemplified by Mailchimp (especially the illustration-driven era), Webflow, Slack, Notion in its marketing surfaces, Loom, Intercom, and Figma. Adjacent examples include Khan Academy and Mailchimp's earlier mascot work. + +These brands share: cream or warm-white surfaces, single-family sans, mid-saturation warm accent, human or custom-illustration imagery, second-person voice, comfortable density. + +The archetype frequently overlaps with Playful Energetic when the illustration system carries character; the difference is that Warm Conversational keeps the illustration in service of communication, while Playful Energetic lets the illustration become the dominant visual. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md new file mode 100644 index 0000000..f1710a6 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md @@ -0,0 +1,115 @@ +# Bold Confident + +## Aesthetic summary + +High-contrast color (often black plus one saturated accent). Oversized display type used as design element. Direct copy. Strong horizontal grids. The brand walks into the room and says what it is selling without flinching. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (direct, comfortable with first person) +- **Aesthetic register**: Expressive +- **Audience relationship**: Performer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0A0A0A | Near-black primary | +| paper | #FFFFFF | White surface | +| paper-soft | #F2F2F2 | Tinted surface | +| accent | #FF4D2E | Saturated single accent (vibrant orange shown) | +| accent-deep | #C13A20 | Active state | +| support | #18181B | Off-black for layered surfaces | +| line | #1F1F1F | Heavy line color (matches the bold register) | + +Alternative accent picks that fit this archetype (one only): +- Hot pink: #EC2877 +- Lime: #C7F11D +- Electric blue: #2563EB +- Saturated yellow: #FFD400 (use with extreme contrast) + +Rationale: +- Two-tone is the move: high-contrast black-and-white plus one saturated accent. Three or more colors dilute the boldness. +- Pure black (or near-black) and pure white reinforce the contrast register. Off-blacks or warm whites pull the archetype toward Editorial Restrained. +- The accent is loud enough that it has to be deployed sparingly. Used as background for one section, not as button color everywhere. + +## Type pairing starter + +- **Display**: Druk Wide, Söhne Breit, GT Sectra Display, Helvetica Now Display, or PP Editorial New (when leaning expressive editorial). Heavy weight (800 to 900) on display. +- **Body**: Söhne, Inter, or Helvetica Now. Mid-weight (500). + +Size scale (extreme contrast between hero and body): +- Hero: 80 to 140px display (the headline is the hero) +- H2: 48 to 72px display +- H3: 28 to 36px +- Body: 17 to 19px +- Small: 14 to 15px + +Pairing rationale: the archetype is built around extreme type contrast. Hero type runs huge (often 100px or more on desktop); body type is normal. The size ratio itself is the visual signature. Heavy display weights are non-negotiable; light or regular weights produce a different archetype entirely. + +## Layout and composition + +- Horizontal grids dominate. Heroes often full-bleed with the headline as the design element. +- Asymmetric layouts with intentional imbalance: text aligned hard-left, oversized headlines that extend past container edges. +- High contrast section transitions: black section, then white section, then accent section. The page reads as panels. +- Sharp corners more often than rounded. +- Minimal decorative imagery; the type IS the visual. + +## Imagery direction + +- Photography: high-contrast, often desaturated or single-color-tinted, real but stylized. +- Illustration: bold flat illustration when used, single accent color, no gradients. +- Product UI: shown in oversized chrome that mirrors the brand's contrast register. +- Decorative: type-as-image; the headline often becomes the visual. + +## Voice samples + +- "We do not negotiate with hidden fees." +- "Built for the people doing the actual work." +- "This is the version that works. The free trial is the version that works." +- "No setup call. No demo. Just sign up." +- "We charge once. You own the thing." +- "Our competitor's pricing page has a button to talk to sales. Ours has a price." + +Cadence: short sentences. Declarative. Contrasts and oppositions ("not X, just Y"). Comfortable with confrontation. Avoids hedging. + +## Component pattern descriptions + +**Hero**: Oversized headline as the dominant element (80 to 140px). Sub headline below at standard size. 1 to 2 buttons. Often a single bold visual or a horizontal divider in the accent color. + +**Buttons**: Primary is solid ink or accent on white. Often oversized (56 to 72px height) to match the bold register. Square or low-radius corners (0 to 4px). + +**Cards**: Sharp corners, heavy border (2 to 3px) or strong shadow, large internal padding. Often the card itself uses contrast (black card with white text, or accent card with black text). + +**Tables**: Heavy header (black background, white text). Large row height. Bold numerics. + +## When to pick this + +- Launch moments or rebrand moments where the brand needs to reset attention +- Category is full of timid competitors and your brief needs differentiation through volume +- Product confidence is high and the value prop is sharp +- Brand is comfortable being polarizing + +## When to avoid + +- Brand needs to communicate care, gentleness, or expertise-through-restraint +- Audience reads boldness as bro-culture or as insecurity +- Product value is technical and needs space to explain itself +- Brand will be embarrassed by the visual in 18 months (this archetype dates faster than restrained ones) + +## Adaptation guidance + +1. **Accent pick**: hot pink leans consumer, lime leans tech-edgy, electric blue leans fintech, orange leans general-purpose bold, yellow only with extreme contrast discipline. +2. **Display size**: do not pull this back to "reasonable." If the hero is 56px, you have made an Editorial Restrained brand instead. Commit to 100px+ or pick a different archetype. +3. **Voice**: easy to slip into bro-culture. Pull back the swagger by writing honest, not performed. The visual is bold; the voice is direct, not bombastic. +4. **Image strategy**: pick type-as-visual or one strong photo. Mixed imagery dilutes the impact. +5. **Use the contrast**: panel-by-panel section transitions are core. A single-color page is not Bold Confident. + +## Exemplar brands + +Bold Confident is exemplified by Loom (current era), Cash App, Robinhood, Mercury (in its recent rebrand), Notion (in product launches), Linear (in major launches), Cloudflare (consumer edge), and Brex. Adjacent older examples include the original Squarespace launch era and the original Mailchimp redesign. + +These brands share: high-contrast palette, oversized display type as visual element, direct voice, panel-based section transitions, one strong accent. + +The archetype often pairs with Technical Precise on developer-tilted brands (the marketing page is Bold Confident; the product surface is Technical Precise). It also overlaps with Vibrant Saturated when the accent is the brand color rather than a supporting note. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md new file mode 100644 index 0000000..3accaa3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md @@ -0,0 +1,114 @@ +# Playful Energetic + +## Aesthetic summary + +Bright multi-color palette. Illustration-led, frequently character-driven. Dynamic, sometimes literally animated. Chunky display type or rounded sans. The brand has a personality, often a recurring character or mascot, and that personality is the primary asset. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Companion +- **Sensory ambition**: Immersive + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1B1B2A | Soft-black text | +| paper | #FFFDF7 | Cream surface | +| paper-soft | #FFF4D6 | Pastel surface tint | +| accent-primary | #58CC02 | High-saturation primary (Duolingo green shown) | +| accent-secondary | #FF4B4B | Bright contrast accent | +| accent-tertiary | #FFC800 | Sunny yellow | +| accent-quaternary | #1CB0F6 | Bright sky blue | +| accent-quinary | #CE82FF | Bright purple | + +Rationale: +- Multi-hue palette is the signature. Single-accent palettes do not produce Playful Energetic. +- High saturation (often above 80%) across the full palette. Pastel-only is a different archetype (Vibrant Saturated pulled toward soft). +- The palette is calibrated so any two colors can sit next to each other without clashing. This is harder than it looks and requires hue and value discipline. +- Soft black for text (not pure black) keeps the warmth of the palette intact. + +## Type pairing starter + +- **Display**: Recoleta, Sofia Pro Black, Pangaia, or a chunky humanist serif. Heavy weight, rounded shapes. +- **Body**: Nunito, Inter, or a rounded humanist sans. 500 to 600. +- **Character lettering**: Many brands in this archetype use custom wordmark lettering for the brand name itself (Duolingo, Mailchimp, Headspace). The custom mark sits outside the type system. + +Size scale (energetic, with playful proportions): +- Hero: 56 to 80px display (heavy weight) +- H2: 32 to 44px display +- H3: 22 to 28px +- Body: 17 to 19px sans (rounded) +- Small: 14 to 15px + +Pairing rationale: rounded shapes communicate friendliness. Heavy weights communicate playfulness over preciousness. The pairing is "chunky and round" rather than "tall and narrow." + +## Layout and composition + +- Generous use of decorative elements (mascot illustrations, sparkles, shapes, patterns). +- Asymmetric layouts; intentional cheerful imbalance. +- Diagonal motion lines, jaunty rotations on key elements (cards rotated 2 to 4 degrees), bouncy interactions on hover. +- Heavy use of card-based sections with playful borders (heavy, often colored borders rather than hairlines). +- Rounded corners are aggressive (16 to 24px); sharp corners feel wrong in this archetype. + +## Imagery direction + +- Illustration: custom illustration system is the brand's primary visual asset. Often character-driven (mascot has a personality and shows up across surfaces). +- Animation: motion design is core. The mascot moves; cards bounce on hover; loading states have personality. +- Photography: rare. When used, candid and bright, never sterile. +- Stock imagery: forbidden. The archetype requires custom illustration capacity. + +## Voice samples + +- "Hi! It is time for your daily lesson." +- "You did the thing. We are very proud." +- "Skip a day, and the streak ends. We are watching." +- "Two minutes today is better than zero minutes today." +- "Surprise! You earned a badge." +- "Your friend just passed you. Are you going to let that stand?" + +Cadence: short, punchy. First and second person. Comfortable with exclamation marks (but not abuse). Frequent direct address. Humor as a primary tool. Occasional knowing winks at the reader. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 CTA, paired with a large illustration or animated mascot. The illustration is roughly equal weight to the headline rather than supplementary. + +**Buttons**: Heavily rounded (12 to 20px radius). Often with a 2 to 4px solid bottom border in a darker shade (the "neumorphic toy button" pattern). Bouncy hover animations. + +**Cards**: 16 to 24px radius, soft drop shadows, often slightly rotated. Sometimes with character illustrations integrated into the card itself. + +**Forms**: Inputs are oversized, friendly, with playful focus states. Validation errors are gentle ("Hmm, that does not look right" rather than "Invalid input"). + +**Loading states**: have personality. The mascot waves, bounces, makes a face. Default spinners are missed opportunities in this archetype. + +## When to pick this + +- Consumer apps targeting habit formation, learning, or wellness +- B2B brands intentionally breaking category convention with humor +- Audience appreciates personality over precision +- Brand has illustration budget and willingness to build a character system + +## When to avoid + +- Brand has no illustration budget (this archetype dies on poor illustration) +- Audience reads playfulness as unserious (most enterprise, most developer tools) +- Brand is selling to risk-averse buyers (finance, health, B2B procurement) +- Brand is in a category where competitors are already playful (you will not differentiate) + +## Adaptation guidance + +1. **Character commitment**: decide early whether the brand has a mascot. Mascot brands need ongoing illustration. Mascot-less playful brands rely on pattern and color systems. +2. **Palette discipline**: defining 4 to 6 saturated hues that compose together is the hardest part. Spend real time here; the rest of the archetype is downstream. +3. **Motion**: the archetype needs motion to feel right in product. Static-only execution reads as toy-without-charm. +4. **Voice**: write to one specific reader, not "users." The archetype falls apart when the voice tries to be funny without commitment. +5. **Restraint**: even Playful Energetic needs editorial moments. Pages that are 100% playful all the way through exhaust the reader. + +## Exemplar brands + +Playful Energetic is exemplified by Duolingo (the canonical example, with a full character system), Mailchimp in its monkey-mascot era, Headspace, Asana classic era, Liquid Death (visual side), Ben and Jerry's, and MoonPay. Adjacent examples include the Trello mascot era and the original Slackbot personality. + +These brands share: multi-hue saturated palette, custom illustration as primary asset, second-person voice with personality, heavy use of motion, rounded everything. + +The archetype overlaps with Warm Conversational when the illustration is friendly but not character-driven; the difference is that Playful Energetic lets the personality become the brand, while Warm Conversational keeps the human relationship in the foreground. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md new file mode 100644 index 0000000..d97188b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md @@ -0,0 +1,112 @@ +# Luxe Considered + +## Aesthetic summary + +Serif-led across display and body. Extreme whitespace. Restrained monochromatic palette plus one premium accent. Photography is editorial-grade. Voice is sparse and confident. The brand communicates premium not by saying premium but by behaving premium: in pacing, in spacing, in what it omits. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (formal but not stiff) +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Theatrical + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1A1614 | Warm near-black | +| ink-soft | #3A332E | Secondary text | +| paper | #F5F1EA | Cream off-white background | +| paper-warm | #EDE6D9 | Warmer cream surface | +| accent | #5C2A26 | Deep oxblood (alternative: forest #2D4A38, charcoal navy #1F2A40, champagne #C3A87C) | +| accent-soft | #8B4843 | Active states | +| line | #D9D0BC | Warm beige border | + +Rationale: +- Cream and warm-neutral palette is the foundation. Pure white feels cheap in this archetype; cool grays feel corporate. Warmth is the premium signal. +- Single deep accent (oxblood, forest, navy, champagne, deep emerald). Saturation is restrained; the depth of value carries the premium feel. +- No bright colors. Even subtle saturation reads as cheap in this archetype. +- Line color matches paper-warm; lines should be visible but not strong. + +## Type pairing starter + +- **Display**: Tiempos Headline, GT Super, Reckless, Reforma, or Saol Display. Light to regular weight (300 to 400). +- **Body**: Tiempos Text, GT Super Text, or Source Serif. Light weight (300 to 400) at comfortable reading size. +- **Optional sans**: Söhne or GT America at low weight (300) for UI labels and metadata only. + +Size scale (editorial proportions, smaller hero than Bold Confident, larger body than Technical Precise): +- Hero: 48 to 64px serif (light weight) +- H2: 32 to 42px serif +- H3: 22 to 26px serif +- Body: 18 to 20px serif (light weight, comfortable line height) +- Small: 14 to 15px sans + +Pairing rationale: editorial serifs throughout produce the "magazine" feeling. Light weights communicate confidence without aggression. The pairing is rare in B2B (which mostly uses serif display plus sans body) and that rarity is part of the premium signal. + +## Layout and composition + +- Extreme whitespace. Sections separated by 144 to 200px vertical rhythm. +- Often centered or left-aligned with massive horizontal margins on desktop (max content width can run 580 to 720px even on wide screens). +- Asymmetric compositions where the imbalance is intentional and editorial (a 70/30 split with text against a single dominant photograph). +- Minimal UI chrome. Buttons are often text-only with underlines, or thin-bordered, or absent entirely (the call to action is a single line of body copy with a link). +- Page transitions are slow and deliberate. Animations cross-fade rather than slide. + +## Imagery direction + +- Photography: editorial-grade, professionally lit, deliberately styled. Natural light is fine but composition is intentional. Real product, real environment, but elevated. +- Photography is large. Hero images are full-bleed or near-it. The image carries the page. +- Illustration: rare. When used, line-only, sometimes hand-drawn or engraved-feeling. +- Decorative imagery: none. The composition is the visual. +- This archetype requires real photography or excellent stock curation. Bad photo direction kills it instantly. + +## Voice samples + +- "Made from cashmere. From goats that live in places we visit." +- "One garment, one decision." +- "We do not chase trends. We do not need to." +- "Built in 1923. Refined since." +- "If it is not in this collection, it is because it was not ready." +- "The thing we changed was the thread." + +Cadence: short, often fragments. First-person plural ("we") more often than first-person singular. Comfortable with silence. Avoids superlatives ("the best," "the most"); the visual communicates premium without verbal claim. Numbers used sparingly, with deliberate weight when they appear. + +## Component pattern descriptions + +**Hero**: Single full-bleed photograph or a small serif headline against generous whitespace. No subhead. No CTAs in the visible hero region; the page expects the reader to scroll. + +**Buttons**: Often text-only with a serif underline, or thin-bordered with serif label. Solid buttons exist but are rare and reserved for primary purchase moments. Padding is generous (16 to 20px vertical). + +**Cards**: Often no card chrome at all; product is shown on a tinted surface with serif type alongside. When cards exist, they are bordered (1px line color) rather than shadowed, with sharp or low-radius corners (0 to 4px). + +**Navigation**: Minimal. Often horizontally centered with wide letter spacing. Logo small. The brand does not announce itself loudly. + +## When to pick this + +- Luxury or premium-priced products (above 50 dollars consumer, premium-tier B2B) +- Hospitality, fashion, beauty at price points where the visual must signal value +- Audience explicitly buys premium and is reassured by understated execution +- Brand has the production budget for premium photography + +## When to avoid + +- Brand is competing on price or accessibility +- Audience reads restraint as unfriendly +- Brand has no photography budget (the archetype dies immediately) +- Product is not actually premium (the visual will read as costume) + +## Adaptation guidance + +1. **Accent depth**: oxblood reads heritage, forest reads sustainability, deep navy reads institutional, champagne reads contemporary luxury. Pick based on brand position. +2. **Photography commitment**: this is a photography archetype before it is a type archetype. Lock photography direction first. +3. **Type weight discipline**: light weights (300 to 400) only. Bold serif display pulls the archetype toward Bold Confident. +4. **CTA restraint**: resist adding obvious buy buttons in hero positions. The archetype expects the reader to discover, not be sold to. +5. **Sans usage**: keep sans confined to UI labels and metadata. Sans body copy breaks the archetype. + +## Exemplar brands + +Luxe Considered is exemplified by Aesop, Aritzia, Reformation, La Marzocco, Loro Piana, Aman, Bottega Veneta digital, and Stripe Press (in the book design surface). Adjacent examples include the Apple mid-2010s premium product pages, Squarespace's recent rebrands, and the original Goop. + +These brands share: cream and neutral palette, serif-throughout type system, generous whitespace, editorial photography, sparse voice, premium pricing. + +The archetype overlaps with Editorial Restrained (which is the B2B-tilted cousin) and Minimal Essentialist (which strips out the serif entirely). The key difference: Luxe Considered uses the serif and warmth to signal premium; Minimal Essentialist uses absence of ornament to signal premium; Editorial Restrained uses considered ornament to signal trust. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md new file mode 100644 index 0000000..c3bac14 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md @@ -0,0 +1,115 @@ +# Clinical Trustworthy + +## Aesthetic summary + +Cool palette (blue, teal, soft greens) with optional warm accent for humanity. Sans-serif throughout. Clean compositions. Medical or financial register. Photography of products and clinical environments, occasionally real hands and real people in calm contexts. The brand communicates "trust us with something important" without sliding into cold or pharmaceutical. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (calm, knowledgeable, low-affect) +- **Aesthetic register**: Considered +- **Audience relationship**: Authority +- **Sensory ambition**: Functional + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0F2540 | Deep navy primary | +| ink-soft | #344C68 | Secondary text | +| paper | #FFFFFF | White surface | +| paper-soft | #F4F8FB | Cool tinted surface | +| accent-primary | #2D7FB8 | Trust blue | +| accent-secondary | #4CA8A0 | Soft teal | +| warm-tone | #F4B69B | Optional peach warm accent for humanity | +| signal-success | #2F8F5F | Calm success green | +| line | #DAE3EC | Cool gray border | + +Rationale: +- Cool palette communicates calm authority. Blues and teals are the trust signals; warm tones are optional humanizers, not primary brand colors. +- Trust blue (#2D7FB8) is calibrated to read confident without sliding into corporate cold. Bluer (toward #1976D2) reads more pharmaceutical; teal-shifted reads more wellness. +- The optional warm accent (peach, soft coral) is the single move that distinguishes contemporary Clinical Trustworthy from sterile pharma aesthetic. Without it, the brand reads dated. +- White surfaces. Off-whites and creams pull the archetype toward warmth and away from clinical. + +## Type pairing starter + +- **Display**: Avenir Next, Circular, Söhne, or GT America. 500 to 700 weight. +- **Body**: Same family, 400 to 500. Or paired with a soft humanist body (Inter, Source Sans). +- **Optional accent serif**: A clean serif (Source Serif, Tiempos Text) used sparingly for editorial moments or testimonials. + +Size scale (calm, generous, accessible): +- Hero: 48 to 60px sans +- H2: 30 to 38px sans +- H3: 22 to 24px sans +- Body: 17 to 19px sans (accessible default; this archetype frequently serves older audiences) +- Small: 14 to 15px + +Pairing rationale: geometric sans-serif communicates clinical without medical-sterile. Circular and Avenir specifically have open shapes that read calm rather than clinical. Body sizes run slightly larger because the audience may include older readers and the brand should not require strain. + +## Layout and composition + +- Comfortable density; not as dense as Technical Precise, not as breathing as Luxe Considered. +- Generous internal padding inside cards and forms. Trust is communicated partly through "we are not hurrying you." +- Hero often pairs a clean headline with a calm photograph (a real hand holding a product, a calm clinical environment, a portrait of a doctor or pharmacist). +- Comfortable line lengths (60 to 80 characters per line) and generous line height (1.6 to 1.8). +- Soft drop shadows on cards (gentle elevation, not floating). Rounded corners at moderate radius (8 to 12px). + +## Imagery direction + +- Photography: real hands, real products in real environments. Calm lighting (often natural). Real people who look like the audience. +- Product packaging: shown clearly, frequently against soft tinted backgrounds. +- Illustration: rare; when used, technical diagrams of how something works (a calm anatomical illustration, a process flow with annotations). +- Avoid: aggressive close-ups of medical procedures, stock photos of clinicians in lab coats with crossed arms, hands-only-on-keyboard generic stock. + +## Voice samples + +- "Reviewed by licensed clinicians." +- "Effective ingredients at evidence-backed doses." +- "Same medication. Less hassle." +- "Your doctor will see this report. So will you." +- "We do not bill you for what we do not provide." +- "If it is not safe for you, we will tell you." + +Cadence: complete sentences. Comfortable with first and second person. Calm, qualified, specific. Numbers used carefully (specific doses, specific time-to-response). Avoids superlatives. Compliance-aware writing without being legal-coded. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 to 2 CTAs, paired with a calm photograph. Trust signals (clinician endorsements, FDA mentions, peer-reviewed citations) appear above the fold but understated. + +**Buttons**: Primary is solid trust-blue or solid ink-navy, white text, 8 to 12px corner radius. Secondary is bordered. Hover states use a slight darkening rather than opacity shift. + +**Cards**: White or paper-soft surface, 8 to 12px radius, gentle shadow (0 2px 8px rgba(15,37,64,0.06)). Generous internal padding (32 to 40px). Trust signals (clinician credentials, certification marks) frequently appear in cards. + +**Forms**: Generous field height (48 to 56px). Labels above inputs. Help text below explaining why each piece of information is needed (trust signal: we explain why we ask). + +**Trust strip**: Common pattern. Logo strip of certifications, regulatory bodies, peer-reviewed citations, or major employers using the product. + +## When to pick this + +- Telehealth, digital health platforms +- Fintech, especially at the trust-needing edge (banking, insurance, investments for older audiences) +- Insurance, retirement, anything where the conversion driver is "trust us with this" +- Health-finance intersection (HSA, healthcare benefits, prescription savings) + +## When to avoid + +- Audience is young and reads clinical as boring or institutional +- Brand needs to communicate energy or excitement +- Category is already dominated by clinical-trustworthy brands (you will disappear) +- Product is not actually substantive enough to support the trust register (the visual will read as costume) + +## Adaptation guidance + +1. **Cool to warm balance**: pure clinical cool reads pharmaceutical. The optional warm accent (peach, soft coral, butter yellow) is what distinguishes contemporary from dated. +2. **Photography**: real hands and real environments are the move. Stock photos of "doctor with arms crossed" date the brand immediately. +3. **Voice density**: write specific. Vague claims in a clinical archetype read as worse than vague claims in a playful one, because the visual is promising specificity. +4. **Trust signals**: dedicate space to credentials, certifications, citations. Hide them and the archetype is half-built. +5. **Density**: keep it comfortable. Both too dense and too breathing read as untrustworthy in this archetype. + +## Exemplar brands + +Clinical Trustworthy is exemplified by Hims, Ro, Care/of, Cerebral, Mercury (in finance-trust context), and Stripe (in payment-trust context). Older or adjacent examples include early One Medical, the original Headspace landing surfaces before they leaned playful, and the original Robinhood when it was selling trust over excitement. + +These brands share: cool palette with optional warm humanizer, geometric or humanist sans throughout, real-hand photography, calm voice with specific evidence, generous form fields with help text. + +The archetype frequently splits brands by surface: Clinical Trustworthy for the marketing and conversion surface, with Warm Conversational notes in customer support and post-purchase. The hand-off matters: trust converts, warmth retains. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md new file mode 100644 index 0000000..6690a5f --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md @@ -0,0 +1,115 @@ +# Rugged Utilitarian + +## Aesthetic summary + +Earth tones (clay, olive, charcoal, raw paper). Workwear-influenced type (slab serifs, condensed sans, stencil). Photography of real conditions: outdoor, working, lived-in. Voice is direct and unadorned. The brand reads as built for use rather than for show, and the visual restraint communicates that the product earns its place through function. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (plain, direct, working-class register without affectation) +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #2C2A26 | Charcoal primary | +| paper | #F0EAD8 | Raw paper background | +| paper-soft | #E2DAC2 | Tinted surface | +| accent-clay | #B8543B | Clay red primary | +| accent-olive | #5C6B3D | Olive green secondary | +| accent-sand | #C29A60 | Warm sand tertiary | +| accent-charcoal | #2C2A26 | Heavy charcoal (alternative primary) | +| line | #A89B7F | Warm tan border | + +Rationale: +- Earth tones throughout. The palette is derived from natural pigments: oxide reds, military olives, sun-bleached tans, deep charcoals. +- Saturation is low to medium; nothing in the palette exceeds 60% saturation. Higher saturation pulls toward Bold Confident or Vibrant Saturated. +- The palette reads as outdoor and used. Pure white feels wrong; cool grays feel wrong. Warmth and weight are signature. +- Primary color is often the clay red or charcoal; olive functions as a secondary. The reverse also works. + +## Type pairing starter + +- **Display**: Druk Condensed, Bebas Neue, Roboto Slab, or a workwear-influenced slab (United Sans Slab, Sentinel). Heavy weight, condensed proportions. +- **Body**: Inter, Söhne, or a clean humanist sans. 400 to 500. +- **Optional accent type**: stencil or workshop-influenced display for product callouts and signage moments. + +Size scale (utilitarian, less extreme than Bold Confident): +- Hero: 56 to 80px display +- H2: 32 to 44px display +- H3: 22 to 26px sans +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Numeric mono: 14 to 16px (for spec sheets) + +Pairing rationale: condensed display type feels like signage on industrial equipment, on workwear labels, on shipping crates. Slab serifs feel like surveyor stamps and field guides. Clean humanist sans body keeps the page legible without dressing it up. + +## Layout and composition + +- Functional density. Information shown without softening. +- Heavy use of horizontal rules and labeled sections (the page reads like a spec sheet or field manual). +- Photography is large and full-bleed; the image carries the page. +- Cards are bordered (1 to 2px) rather than shadowed. Corners are sharp or low-radius (0 to 4px). +- Type often allCAPS for labels and section headers (reinforcing the signage register). + +## Imagery direction + +- Photography: real conditions. Real users in real environments. Dirt, sweat, weather, work. Not staged. Natural light dominant; flash photography rare. +- Photography subjects: products in use rather than products on white. The brand wants to show what the product looks like after a season of work, not what it looks like in a studio. +- Illustration: technical diagrams, exploded views, blueprints. Functional rather than decorative. +- Forbidden: pristine product-on-white shots (those belong to Minimal Essentialist or Luxe Considered), happy-family-lifestyle shots (those belong to Warm Conversational). + +## Voice samples + +- "Built to outlast you." +- "If it breaks, send it back. We will fix it." +- "Designed in Bozeman. Tested where it gets cold." +- "We made it heavier on purpose." +- "Spend it on the gear. Save it on the brand." +- "Lifetime guarantee. Read that again." + +Cadence: short. Direct. First-person plural ("we") when the brand speaks. Comfortable with imperative voice. No marketing jargon, no superlatives, no exclamation marks. Honest specifications over emotional appeals. + +## Component pattern descriptions + +**Hero**: Photograph (full-bleed, real-conditions) with overlaid type, or split layout with text left and photograph right. Headline in display, often condensed or slab. Buttons are direct. + +**Buttons**: Primary is solid charcoal or clay, white or cream text, sharp or low-radius corners (0 to 4px). Heavy and substantial; never floaty. Often labeled in all caps or with stencil-style lettering. + +**Cards**: Bordered (1 to 2px line), low-radius, generous internal padding. Often with a labeled header strip (uppercase, condensed) that reads like a product tag. + +**Tables**: Specification-sheet feel. Labeled rows. Mono numerics. Heavy horizontal rules between sections. + +**Product detail**: Honest. Materials listed. Construction methods explained. The reader is expected to care about how it is made. + +## When to pick this + +- Outdoor, gear, work-tool products +- Brands where durability and utility are the genuine value proposition +- Audience values function over fashion +- Brand has authentic claim to ruggedness (the brand actually serves people doing the work) + +## When to avoid + +- Brand is not actually utilitarian (the archetype reads as costume when applied to delicate products) +- Audience reads ruggedness as bro-culture or as anti-intellectual +- Brand needs to communicate softness, care, or gentleness +- Brand has no claim to outdoor or work-tool authenticity + +## Adaptation guidance + +1. **Authenticity test**: if the brand cannot show real photography of real use, this archetype is wrong. Switch to Documentary Honest if real photography is feasible at a different intensity. +2. **Palette pick**: clay-and-olive feels heritage outdoor (REI, Filson register). Charcoal-and-sand feels industrial workwear (Carhartt, Dickies register). Pick based on category position. +3. **Type weight**: heavy is non-negotiable. Light or regular weights pull the archetype toward Editorial Restrained. +4. **Voice**: avoid performed toughness ("BUILT FOR THE GRIND"). Real Rugged Utilitarian voice is matter-of-fact, not bombastic. +5. **Specification depth**: dedicate page real estate to materials, construction, warranty, repair policy. These are the trust signals. + +## Exemplar brands + +Rugged Utilitarian is exemplified by Patagonia, Carhartt, Yeti, Filson, Snow Peak, Best Made Co (historical), Topo Designs, REI in its product detail surfaces, Stanley (recently), and Hemlock Goods. Adjacent examples include Tom Bihn and Goruck. + +These brands share: earth-tone palette, condensed display or slab serif, real-conditions photography, plainspoken voice, specification depth, lifetime guarantee or repair offering. + +The archetype overlaps with Documentary Honest when photography is the dominant visual; the difference is that Rugged Utilitarian has explicit utility framing (this is for working) while Documentary Honest is about authentic representation more broadly (this is what real life looks like). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md new file mode 100644 index 0000000..72a07e7 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md @@ -0,0 +1,136 @@ +# Retro Nostalgic + +## Aesthetic summary + +Period-specific palette and type. Intentional vintage reference to a specific era (70s, 80s, 90s, or earlier). Often uses textured or grainy compositions. Voice references the era in cadence or vocabulary. The brand asks the audience to associate it with a felt period rather than with a category, and that association does most of the differentiation work. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Companion +- **Sensory ambition**: Theatrical + +## Color palette starter + +Three era-keyed palette options. Pick ONE era; do not blend. + +**70s palette** (warm, earthy, optimistic): + +| Token | Hex | Role | +|---|---|---| +| ink | #2A1810 | Deep brown primary | +| paper | #F4EAD0 | Cream ground | +| accent-orange | #D2602B | Burnt orange | +| accent-avocado | #6A7A3A | Avocado green | +| accent-mustard | #D4A02E | Harvest gold | +| accent-rust | #8E3F1E | Deep rust | + +**80s palette** (neon, geometric, bold): + +| Token | Hex | Role | +|---|---|---| +| ink | #0D0D2A | Deep navy primary | +| paper | #FAF5EF | Cream surface | +| accent-pink | #FF2D87 | Hot pink | +| accent-cyan | #18C2D9 | Electric cyan | +| accent-yellow | #FFD30F | Saturated yellow | +| accent-purple | #6A2EB8 | Bold purple | + +**90s palette** (muted, grunge-edged, prosumer): + +| Token | Hex | Role | +|---|---|---| +| ink | #1F1A14 | Warm dark brown | +| paper | #E8DEC8 | Aged cream | +| accent-rust | #9C4B2E | Muted rust | +| accent-teal | #3E7575 | Faded teal | +| accent-yellow | #C49A35 | Aged mustard | +| accent-purple | #654273 | Muted purple | + +Rationale: +- Each era has a recognizable palette signature. Mixed-era palettes read confused; the audience cannot place the reference. +- The 70s palette is warm and earth-toned, optimistic but not bright. The 80s palette is neon and geometric. The 90s palette is muted, with deliberate aged warmth. +- Pick the era based on the audience's nostalgia moment: 70s for late-30s and older, 80s for late-30s to mid-40s, 90s for late-20s to mid-30s, early 00s for current 20-somethings. + +## Type pairing starter + +Era-keyed type pairings. Pick ONE era. + +- **70s**: Cooper Black or VAG Rounded or ITC Bauhaus (display); Cooper or Avenir (body). +- **80s**: Eurostile, Avant Garde, or Compacta (display); a clean geometric sans (Avenir, Futura) for body. +- **90s**: Trade Gothic, a worn grunge serif (Bureau Grot, Knockout), or a digital-feeling sans (Eurostile) for display; classic sans for body. + +Size scale (varies by era, but generally expressive): +- Hero: 56 to 96px display +- H2: 36 to 48px display +- Body: 16 to 18px sans + +Pairing rationale: type is the era signature. Cooper Black is 70s consumer; Eurostile is 80s tech-future; Trade Gothic worn is 90s grunge. The reader recognizes the era through the type before recognizing it through the color. + +## Layout and composition + +- Era-specific composition styles. 70s leans toward soft asymmetric blocks and groovy curves. 80s leans toward hard geometric grids, oversized type, and Memphis-influenced shapes. 90s leans toward grunge collage, intentional rough edges, and zine-influenced layouts. +- Textures matter: grain, scan lines, paper-aged effects, halftone. Pure digital flat surfaces fight the archetype. +- Iconography is period-keyed: hand-drawn for 70s, geometric for 80s, photocopied-feeling for 90s. + +## Imagery direction + +- Era-keyed photography: warm-tinted and grainy for 70s, neon-lit and high-contrast for 80s, muted and slightly desaturated for 90s. +- Often pairs modern product photography with period-accurate styling (the product is contemporary, but the styling and framing reference the era). +- Pattern: era-accurate decorative elements (sunbursts, stripes, Memphis shapes, halftone dots) are common. + +## Voice samples + +(80s example for an energy drink brand) +- "Soda for people who remember what soda was." +- "From the era when caffeine had personality." +- "Yes, it tastes like that on purpose." +- "Made with cane sugar. Like before." + +(70s example for a wellness brand) +- "Roots, herbs, and a generally chill outlook." +- "Wellness from when wellness was just called feeling good." +- "Brewed the long way. Drunk the slow way." + +Cadence: era-keyed. 70s reads warm and unhurried. 80s reads punchy and confident. 90s reads ironic and self-aware. The voice should evoke the era without quoting it directly. + +## Component pattern descriptions + +**Hero**: Often centered with oversized era-keyed display type, paired with era-accurate decorative elements (sunburst, Memphis shapes, halftone, scan lines). Background frequently textured. + +**Buttons**: Era-keyed. 70s buttons are rounded and warm. 80s buttons are geometric and high-contrast. 90s buttons are flat with rough edges or grunge texture. + +**Cards**: Often with era-specific borders (chunky 70s borders, neon 80s outlines, distressed 90s edges). Background textures common. + +**Patterns**: Era-keyed pattern systems are common (gingham, paisley, geometric, Memphis, halftone). Used as section backgrounds, packaging, and brand accents. + +## When to pick this + +- F&B challenger brands in commoditized categories (soda, water, snacks) +- Lifestyle brands with a clear era-of-inspiration +- Brands wanting to differentiate in categories crowded with contemporary minimalist competitors +- Brand has clear position on which era and why + +## When to avoid + +- Brand has no genuine connection to the era (the archetype reads as costume) +- Brand needs to communicate forward-looking innovation +- Audience reads the chosen era as embarrassing or dated rather than nostalgic +- Brand cannot commit to the era at production cost (this archetype requires real photography styling and packaging design) + +## Adaptation guidance + +1. **Era commitment**: pick one era and commit. 70s plus 80s blend reads as confused; the audience cannot place the reference. +2. **Texture investment**: this archetype requires real textures (grain, halftone, paper aging). Flat digital versions read as contemporary-with-retro-fonts rather than genuinely retro. +3. **Voice**: avoid direct era quotation ("groovy," "rad," "totally tubular"). The voice should feel like the era, not parody it. +4. **Modern functionality**: the archetype is visual reference, not functional regression. The website should still work well in 2026; the visual reference is decorative. +5. **Photography**: era-styled photography is expensive. If budget is limited, lean harder into pattern and type as era carriers. + +## Exemplar brands + +Retro Nostalgic is exemplified by Olipop (70s wellness lean), Liquid Death (80s metal lean), Poppi (90s lean), Recess (70s wellness), Athletic Brewing (early 1900s heritage lean), Magic Spoon (90s cereal lean), and Olly (70s wellness lean). Adjacent examples include Brooklyn Brewery (heritage industrial), Hoxton Hotels (period-specific by property), and Howler Brothers. + +These brands share: era-keyed palette and type, period-specific decorative elements, texture-rich compositions, era-aware voice, packaging design that reads as the period. + +The archetype frequently anchors F&B challenger brands; the era pick is the differentiation strategy within a crowded category. Olipop and Poppi are both in the gut-health soda space; they differentiate primarily through 70s versus 90s era reference. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md new file mode 100644 index 0000000..7bcd522 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md @@ -0,0 +1,111 @@ +# Minimal Essentialist + +## Aesthetic summary + +Black, white, single accent maximum. Sans-serif only. Extreme whitespace. Type-led but at smaller scales than Luxe Considered. Compositions almost sparse to the point of empty. Voice is short and declarative. The brand earns attention by removing rather than adding, and the absence of ornament itself becomes the brand signal. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #000000 | True black primary | +| paper | #FFFFFF | Pure white | +| paper-soft | #F7F7F7 | Tinted gray surface (only when needed) | +| muted | #888888 | Mid-gray for secondary text | +| line | #E5E5E5 | Hairline separator | +| accent | #FF3B30 | Optional single accent (red shown; reserve for one use case) | + +Rationale: +- Pure black and pure white. Off-black or off-white pulls the archetype toward Luxe Considered or Editorial Restrained. +- Single accent if any. Many Minimal Essentialist brands use no accent at all. When used, the accent appears once per page (a single CTA, a single error state, a single quote). +- Gray is the secondary palette. Mid-gray for secondary text, hairline gray for borders. +- No gradients. No tints beyond the gray scale. No color washes. + +## Type pairing starter + +- **Display and body**: One sans-serif family across all surfaces. Helvetica Now, Söhne, GT America, Inter, or Suisse Int'l. Multiple weights (300 to 700) carry the hierarchy. +- **Optional secondary**: Sometimes the same family in a tightly-set condensed cut for labels or navigation. + +Size scale (modest contrast, hierarchy through weight more than size): +- Hero: 40 to 56px sans (smaller than Bold Confident; the hero does not need to shout) +- H2: 28 to 36px sans +- H3: 20 to 24px sans +- Body: 16 to 17px sans +- Small: 13 to 14px sans + +Pairing rationale: one family across the system reinforces the discipline. Hierarchy is communicated through weight, size, and color rather than through type pairing. Neo-grotesque sans (Helvetica, Söhne, Suisse) feel pure; geometric sans (Avenir, Circular) feel slightly warmer; humanist sans (GT America, Inter) feel slightly friendlier. Pick based on the temperature you want. + +## Layout and composition + +- Extreme whitespace, but at smaller scale than Luxe Considered. The page reads as efficient rather than ceremonial. +- Often a strict grid: 12-column desktop with deliberate column spans. Asymmetry less frequent than in Editorial Restrained. +- Type-led: type sits in space rather than being framed by photography or color blocks. +- Cards are rare. Content sits directly on the page surface with hairline separators rather than card containers. +- Sharp corners (0 to 2px). Curves feel wrong in this archetype. + +## Imagery direction + +- Photography: product on white. Studio-lit. Considered. No styling beyond the product itself. +- People photography: rare. When used, portraits against neutral backgrounds, minimal styling. +- Illustration: extremely rare. Diagrams in line-only black-on-white if at all. +- Decorative imagery: none. The whitespace is the decoration. + +## Voice samples + +- "One mattress. One price." +- "We make the product. We tell you how it works. You decide." +- "The product is described accurately on the product page." +- "Returns within 100 days. No questions." +- "There is no enterprise tier." +- "The cheapest plan is the only plan." + +Cadence: very short. Declarative. First-person plural ("we") common. Numbers when relevant; otherwise sparse. The voice is honest to the point of dryness. No salesmanship, no superlatives, no hedging. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus single CTA. Often centered or hard left-aligned. Sometimes paired with a single product photograph against white; often with no imagery at all. + +**Buttons**: Solid black, white text, or solid white with black border. Sharp corners or 2 to 4px radius. Single CTA per section. + +**Cards**: Rare. When present: hairline border (1px line gray), no shadow, sharp corners, minimal internal styling. + +**Tables**: Hairline rows. Sans body throughout (no mono). Left-aligned text, right-aligned numerics. + +**Navigation**: Minimal. Logo (often wordmark only), a small number of nav items, a single CTA. No mega-menus, no drawer animations, no decorative chrome. + +## When to pick this + +- Brand wants to communicate timelessness or rigor +- Product is design-focused and the audience appreciates restraint as a value signal +- Brand is competing in a category where every competitor is ornamented; restraint is the differentiator +- Brand can defend the discipline (saying no to internal requests to add color, illustration, ornament) + +## When to avoid + +- Brand has rich content that benefits from visual organization (the archetype's lack of cards and color makes dense content hard to scan) +- Audience reads minimalism as cold or unwelcoming +- Brand needs to communicate warmth, personality, or specific human values +- Brand will eventually be tempted to add ornament (better to start in a more flexible archetype) + +## Adaptation guidance + +1. **Discipline is the brand**: this archetype requires institutional commitment to saying no. Adding decoration over time degrades the archetype faster than other archetypes. +2. **Type family pick**: Helvetica reads neutral and Swiss; Söhne reads contemporary and sharp; Suisse reads precise and minimal; Inter reads accessible and modern. Pick based on temperature, not novelty. +3. **Color discipline**: black plus white plus one accent maximum. Brands that "just add one more color" frequently undermine the archetype. +4. **Photography**: product-on-white only. Lifestyle photography pulls toward Warm Conversational or Luxe Considered. +5. **Voice**: write honest, not poetic. Minimal Essentialist voice that tries to be evocative reads as Luxe Considered; minimal voice that is too plain reads as Editorial Restrained. + +## Exemplar brands + +Minimal Essentialist is exemplified by Apple at its most restrained (mid-2010s product pages), Allbirds at launch, Muji, Casper at launch, Everlane, Squarespace (in its minimal era), The Ordinary, and Aritzia in product detail pages. Adjacent examples include Dieter Rams' principles applied to digital and the early Medium publication system. + +These brands share: black-white-plus-accent, single sans family, extreme whitespace, product-on-white photography, terse declarative voice, no decorative ornament. + +The archetype differs from Editorial Restrained primarily in the absence of serif type and the absence of warm paper backgrounds. Editorial Restrained allows serif display and warm cream; Minimal Essentialist eliminates both. Brands frequently start Minimal Essentialist at launch and migrate toward Warm Conversational or Editorial Restrained as the audience matures and the brand needs more content depth. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md new file mode 100644 index 0000000..0484151 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md @@ -0,0 +1,112 @@ +# Vibrant Saturated + +## Aesthetic summary + +High saturation across the full palette. Color used as primary brand expression. Type often plays second to color. Compositions are color-blocked. Voice is energetic and personality-driven. The brand makes color the primary asset, and the audience remembers the brand by hue before they remember the wordmark. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Performer +- **Sensory ambition**: Immersive + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #181818 | Soft-black text | +| paper | #FFFFFF | White surface | +| accent-primary | #FE2D81 | Saturated brand pink | +| accent-secondary | #2BC8F4 | Bright cyan | +| accent-tertiary | #FFD426 | Saturated yellow | +| accent-quaternary | #8B3DFF | Vivid purple | +| accent-quinary | #21D17C | Bright green | +| signal | varies | Color-blocking accents derived from the palette | + +Rationale: +- Multi-hue saturated palette is the signature. Single-accent palettes do not produce Vibrant Saturated. +- Saturation generally above 70% across the palette. The discipline is that all colors are at similar saturation; this is what produces palette coherence despite hue variety. +- Pure white surfaces. Cream and warm-white pull the archetype toward Warm Conversational. +- The palette is calibrated so any two colors can sit next to each other. This requires hue and value discipline; brands that wing it produce chaos rather than coherent vibrancy. + +## Type pairing starter + +- **Display**: A clean geometric or neo-grotesque sans (Söhne, GT America, Helvetica Now, or a brand-custom face). 600 to 800 weight. +- **Body**: Same family, 400 to 500. +- **Optional serif**: A clean serif (Source Serif, Tiempos Text) for editorial moments. Used sparingly. + +Size scale (color carries the page; type is competent rather than expressive): +- Hero: 48 to 64px sans +- H2: 32 to 40px sans +- Body: 16 to 18px sans +- Small: 14 to 15px + +Pairing rationale: the type is intentionally calmer than the color. Going expressive on both type and color produces visual chaos; one element carries the personality while the other carries the functional load. In Vibrant Saturated, color carries personality and type carries function. + +## Layout and composition + +- Color-blocked compositions are signature. Sections alternate full-bleed background colors; the page reads as panels. +- Heavy use of color as section organizer. The brand may use 6 different colors across a single page, each demarcating a different content type. +- Type sits in color fields rather than on white. White-on-saturated and dark-on-light alternate. +- Rounded corners are common but not aggressive (8 to 16px). +- Motion design uses color transitions (sections fade between hues on scroll, hover states shift hue). + +## Imagery direction + +- Photography: high-saturation, often product-on-color-block, sometimes graphic-treated. +- Illustration: brand-custom illustration systems often appear, with the brand's color palette as the discipline. +- Pattern: bold pattern systems common, using the brand palette. +- Product UI: shown against brand-color backgrounds rather than neutral surfaces. The product takes on the brand's color identity. + +## Voice samples + +- "Music for whatever you're feeling. All of it. Right now." +- "The good news: this works. The better news: you do not have to figure it out." +- "Yes, we are different. That is the point." +- "Press play. We will handle the rest." +- "Built for people who pick a color and commit." + +Cadence: energetic. First and second person. Comfortable with personality. Direct address. Numbers used playfully ("100 percent honest, 0 percent boring"). The voice is the spoken version of the visual energy. + +## Component pattern descriptions + +**Hero**: Often a single dominant brand color as background, with white type and a contrasting accent CTA. Sometimes split between two brand colors. The hero is the color, not the photograph. + +**Buttons**: Solid brand color, contrast text. 8 to 16px radius. Buttons may use one of several brand colors depending on context (the CTA color signals the section's purpose). + +**Cards**: Often colored rather than white. Each card may use a different brand color, with the color carrying meaning (category, type, status). 12 to 16px radius. + +**Sections**: Strong color demarcation. Section A is pink-on-white; Section B is cyan-on-white; Section C is yellow-on-dark. The reader navigates by color. + +**Patterns and shapes**: Common as section dividers and decorative accents. Always within the brand palette. + +## When to pick this + +- Consumer apps with strong category brands +- B2B brands targeting prosumer or creator audiences +- Brands where memorability through color is the strategy +- Brand has color system design discipline (this archetype is harder than it looks) + +## When to avoid + +- B2B brand targeting risk-averse buyers +- Brand cannot commit to color system discipline (winging it produces chaos) +- Brand needs to communicate seriousness or rigor as primary signals +- Category is already crowded with vibrant brands + +## Adaptation guidance + +1. **Palette discipline first**: defining 4 to 6 saturated hues that compose together is the hardest part of this archetype. Spend real time here; the rest is downstream. +2. **Saturation calibration**: keep all colors at similar saturation. Mixed high-saturation and low-saturation produces incoherence. +3. **Type restraint**: the type should not also be expressive. Clean type plus expressive color is the formula; expressive type plus expressive color is chaos. +4. **Color carries meaning**: in the strongest applications of this archetype, color is functional (different colors signal different content types). Use this rather than decorative color. +5. **Accessibility**: contrast ratios must work despite saturated palette. Test every color combination against WCAG AA at minimum. + +## Exemplar brands + +Vibrant Saturated is exemplified by Glossier (with restraint), Spotify, Notion (in its color-era brand expressions), Headspace (overlaps with Playful Energetic), Wise, Klarna, Bumble, and Patreon. Adjacent examples include the Slack rebrand era and the early Stripe consumer-facing surfaces. + +These brands share: multi-hue saturated palette, clean sans type, color-blocked compositions, color as section organizer, expressive but not chaotic compositions. + +The archetype overlaps with Playful Energetic when illustration becomes the dominant element; the difference is that Vibrant Saturated is color-first while Playful Energetic is character-first. Spotify is Vibrant Saturated; Duolingo is Playful Energetic. Both are colorful; the dominance pattern is what distinguishes them. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md new file mode 100644 index 0000000..183c053 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md @@ -0,0 +1,111 @@ +# Documentary Honest + +## Aesthetic summary + +Photography-first. Real people in real conditions. Low touch on imagery. Type recedes to let imagery lead. Compositions are large and image-dominant. Voice is direct and journalistic. The brand uses honest representation as its primary asset, and the visual restraint signals that the product or experience is the real thing rather than the constructed thing. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1B1B1B | Near-black text | +| paper | #FAFAF8 | Off-white surface | +| paper-soft | #F0EFEB | Subtle tinted surface | +| accent | varies by imagery | Pulled from dominant photography tones | +| muted | #5C5C5A | Mid-gray for metadata | +| line | #E2E0DA | Soft line color | + +Rationale: +- The palette derives from photography rather than being imposed on photography. Each brand expression of this archetype has a distinct accent because the accent comes from the imagery world. +- Off-white surfaces with subtle warmth; the photography sits on the page rather than being framed by aggressive surfaces. +- Mid-gray secondary text reads as caption-feeling rather than UI-feeling. +- Saturation throughout the palette is low; photographs may be saturated, but the surrounding UI is muted to let imagery be the contrast. + +## Type pairing starter + +- **Display**: A clean serif (Tiempos Headline, Source Serif, GT Sectra) or a humanist sans (GT America, Söhne, Inter Display). 500 to 700. +- **Body**: Same family or matched body weight, 400 to 500. +- **Caption type**: A subtle italic or smaller weight for image captions and metadata, often in muted gray. + +Size scale (modest, deferential to imagery): +- Hero: 36 to 48px (smaller than most archetypes; the photograph carries hero weight, not type) +- H2: 26 to 32px +- Body: 17 to 19px (comfortable reading) +- Caption: 14 to 15px italic or in muted gray + +Pairing rationale: type sits in service of imagery. Restrained scale and weight let the photograph dominate. Italic captions read journalistic, evoking magazine and newspaper conventions. Either serif or sans works; the pairing should be calm. + +## Layout and composition + +- Photography is large and frequently full-bleed. The image occupies more page real estate than the type. +- Compositions reference editorial design: photograph with caption, photograph with pull quote, photograph plus body text. +- Asymmetric layouts where the image leads and text follows. Often 60/40 splits with photography dominant. +- Generous internal padding around text blocks. The text breathes within the layout. +- Hover states are subtle. The page reads as a document rather than as an interface. + +## Imagery direction + +- Real people, real environments, real conditions. Candid more often than posed. +- Natural light dominant. Studio lighting rare and intentional when used. +- Documentary photography conventions: telephoto compression for environmental portraits, wide-angle for context shots, intentional grain accepted. +- The archetype assumes investment in photography. Stock imagery undermines the archetype immediately. +- Photo direction matters more than photo quantity. A few exceptional images carry the archetype better than many adequate ones. + +## Voice samples + +- "She has been on the trail for six days. Today is the first day she has had warm feet." +- "We met him in the workshop where he learned the trade. He has worked there for 31 years." +- "Three thousand miles. Six time zones. One bag." +- "Built in Vermont. Tested in places where bad gear ends careers." +- "This is what we did. These are the people we did it with. These are the results." + +Cadence: journalistic. Third-person more often than first. Comfortable with specificity (real dates, real durations, real names where appropriate). The voice reads as reporting rather than selling. + +## Component pattern descriptions + +**Hero**: Large photograph (full-bleed or near-it) with overlaid restrained type, or photograph above type-only headline section. The photograph IS the hero. + +**Buttons**: Restrained. Often text-only with underlines, or thin-bordered with calm labels. The buttons recede; the photography leads. + +**Cards**: Often a card is a photograph plus caption plus body excerpt. The card structure mirrors editorial conventions (photo, caption, headline, dek). + +**Quotes**: Pulled quotes are a recurring pattern, set in restrained type with attribution beneath. + +**Sequences**: This archetype frequently uses image sequences (3 to 6 photographs telling a small story) where most archetypes use a single hero image. + +## When to pick this + +- Travel, hospitality, lifestyle brands where the experience IS the value proposition +- Journalism-adjacent brands (publications, archives, documentary work) +- Brands where real stories are the differentiation +- Brand has access to genuine documentary photography (either custom or excellently curated) + +## When to avoid + +- Brand has no real photography access or budget +- Product is functional rather than experiential +- Audience expects highly designed marketing rather than journalistic restraint +- Category is built on aspiration rather than reality (Documentary Honest fights aspirational positioning by definition) + +## Adaptation guidance + +1. **Photography commitment**: this is a photography archetype before it is anything else. If photography is going to be stock or poorly art-directed, switch archetypes. +2. **Voice register**: write journalistic, not marketing. Documentary Honest voice that slides into "we are passionate about" undermines the archetype. +3. **Restraint discipline**: resist adding decorative elements, color accents, or pattern. The photography is the visual; everything else should recede. +4. **Caption discipline**: captions are first-class content. They carry the story alongside the image. Treat them with the same care as headlines. +5. **Authenticity test**: the brand should be able to defend each photograph with a real story. Generic stock-feeling images destroy the archetype. + +## Exemplar brands + +Documentary Honest is exemplified by Airbnb (in its early marketing surfaces), Patagonia (overlaps with Rugged Utilitarian), Outside Magazine, The New York Times' visual journalism work, REI in its editorial content, Selina, and Yeti (in its long-form brand content). Adjacent examples include Field Mag, Topo Designs in long-form marketing, and Filson's historical archives. + +These brands share: real photography as primary visual, restrained type system, journalistic voice, image-plus-caption editorial conventions, low-saturation palette derived from imagery. + +The archetype overlaps with Rugged Utilitarian (both rely on real photography) and Editorial Restrained (both rely on restrained type). The difference: Rugged Utilitarian has utility framing (this is for working); Editorial Restrained is institutional confidence applied to B2B; Documentary Honest is honest representation applied to experience and story. diff --git a/dist/pi/.agents/skills/brand-discovery/SKILL.md b/dist/pi/.agents/skills/brand-discovery/SKILL.md new file mode 100644 index 0000000..3829f09 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/SKILL.md @@ -0,0 +1,197 @@ +--- +name: brand-discovery +description: "Run upstream brand discovery covering audience research, competitive landscape, category dynamics, problem space, and positioning territory exploration. Use this skill at the very start of a brand or website project when the user needs to understand who they're for, who they compete with, what the audience actually needs, and where the brand could plausibly stand. Triggers on brand discovery, audience research, market research, competitive scan, category research, customer research, who is this for, who are we, positioning research, intake, kickoff. Also triggers when a creative brief is requested but the upstream inputs (audience, competitors, problem space) are not yet clear." +category: strategy-and-discovery +catalog_summary: "Audience research, competitive scan, positioning territory exploration" +display_order: 1 +--- + +# Brand Discovery + +Upstream of every brief, identity, and content plan. Discovery answers four questions: who the brand is for, what they need, who else is competing for that need, and where the brand could plausibly stand that competitors do not. + +--- + +## When to use + +- The very first phase of a new brand or website project +- Understanding an audience before any creative work begins +- Mapping competitors and category dynamics +- Surfacing the problem space the brand will operate in +- Generating positioning territories before brief or ideation +- When a creative brief was requested but the inputs are missing + +## When NOT to use + +- The audience and category are already well-understood (jump to `creative-brief` or `brand-ideation`) +- Validating a specific design or feature with users (use `usability-testing`) +- Mapping the customer journey of an existing audience (use `journey-mapping`) +- Generating brand names or visual directions (use `brand-ideation`) + +--- + +## Required inputs + +- The product, service, or organization being branded +- Whatever is already known about the audience and category (often very little) +- Access to existing materials (sales calls, support tickets, reviews, analytics) +- Any constraints (parent brand, regulatory, geographic) +- A timeline (a 1-week discovery looks different than a 6-week one) + +--- + +## The framework: 4 dimensions + +Discovery covers four dimensions. Each has its own sources, methods, and outputs. + +### 1. Audience + +Who specifically does this serve? + +**Layers to surface:** + +- **Demographic:** Age range, geography, language, life stage, income (only if relevant; do not over-collect demographics) +- **Psychographic:** Values, motivations, beliefs, fears +- **Behavioral:** What they currently do to address the problem, what tools they use, where they spend time online and offline +- **Jobs-to-be-done:** The functional, emotional, and social jobs they hire a brand to perform + +**Sources:** + +- Existing customer interviews (5 to 8 ideal) +- Sales call recordings or transcripts +- Support ticket themes +- Review and forum analysis (Reddit, Trustpilot, App Store, niche communities) +- First-party analytics (search console queries, on-site search, top pages) +- Social listening (what they post about the category) + +**Output:** 1 to 3 named audience segments, each with a one-page profile. + +### 2. Competitors + +Who else competes for the same audience and need? + +**Three layers of competitor:** + +- **Direct:** Solves the same problem the same way (e.g., another SaaS in the category) +- **Indirect:** Solves the same problem a different way (e.g., a spreadsheet replacing a SaaS tool) +- **Status quo:** Doing nothing, doing it manually, or living with the problem + +The third is most often forgotten and most often the actual competitor. + +**Per competitor, document:** + +- Who they target (audience overlap with you) +- How they position (what they claim to be) +- What they actually deliver (often different from positioning) +- Pricing model and structure +- Strengths and weaknesses from the audience's perspective +- Recent moves (launches, pivots, hires, departures) + +**Sources:** + +- Their own website and marketing +- Reviews of their product or service +- Their content and SEO presence (use `seo-competitor` for the search angle) +- Social proof and customer voices + +Competitive scan benefits from quantitative grounding: not just "who are the competitors" but "how much traffic do they earn, where does it come from, who is the audience overlap." Similarweb is the standard for this kind of competitive landscape analysis; pair with Ahrefs for the SEO-specific overlap. + +**Output:** Competitor matrix (3 to 8 competitors deep), plus a one-line "what makes them dangerous" for each. + +### 3. Category and problem space + +What is the broader context this brand operates in? + +**Map:** + +- **The problem.** What is the actual user problem? Not the surface symptom, the underlying job to be done. +- **The category.** How is the category structured? Is it new, mature, fragmenting, consolidating? +- **The conventions.** What does every brand in the category do the same way? (These are the conventions you can break.) +- **The shifts.** What is changing in the category? Technology, regulation, audience behavior, distribution. +- **The moats.** What protects incumbents? Brand, distribution, network effects, switching costs? +- **The vocabulary.** What language does the category use? What is jargon, what is meaningful, what is empty? + +**Sources:** + +- Industry reports and analyst coverage +- Trade publications and conferences +- Adjacent category observations +- Customer language vs. category language (the gap is informative) + +**Output:** A category map and a list of conventions to consider breaking (or keeping deliberately). + +### 4. Positioning territory + +Given the audience, competitors, and category, where could this brand plausibly stand? + +This is not yet "the positioning." Discovery surfaces possible territories. `brand-ideation` narrows them and commits. + +**Generate territories from:** + +- Underserved audience segments (audiences others ignore) +- Underserved jobs (jobs the category does not do well) +- Category convention violations (what would happen if you broke the rules everyone follows) +- Honest brand truths (what is genuinely true about this brand that competitors cannot also claim) +- Category shifts (where the puck is going) + +**Per territory, document:** + +- The statement (one sentence) +- Why it could work (proof point) +- Who would resonate (the audience for this territory) +- Who is competing in this territory (often, no one good) +- Risk (what makes it fragile) + +**Output:** 3 to 5 distinct territories. Not yet committed. Inputs to `brand-ideation`. + +--- + +## Workflow + +1. **Define the discovery scope.** 1 week for a startup pre-launch. 4 to 6 weeks for a major rebrand. Set expectations. +2. **Audit existing inputs.** Sales calls, support tickets, reviews, analytics, internal docs. Often more is known than people think. +3. **Audience research.** 5 to 8 interviews if possible. Plus secondary research from review and forum analysis. +4. **Competitor mapping.** 3 to 8 competitors deep, including indirect and status-quo competitors. +5. **Category mapping.** Conventions, shifts, vocabulary, moats. +6. **Territory generation.** 3 to 5 plausible positioning territories. +7. **Write the discovery report.** Use the template in [`references/discovery-report-template.md`](references/discovery-report-template.md). +8. **Hand off to next phase.** Discovery feeds into `creative-brief`, `brand-ideation`, or `content-strategy` depending on where the project goes next. + +--- + +## Failure patterns + +- **Skipping discovery to "save time."** Every shortcut here costs 10x downstream when the brand fails to land. +- **Audience research that confirms what you already believe.** If your audience research validates every assumption, you did not actually research. Look for surprises. +- **Demographic-heavy audience profiles.** "Women aged 25 to 45" is not insight. Behavior, beliefs, and jobs-to-be-done are. +- **Listing every competitor as if equal.** Most competitors do not matter. Pick the 3 that are genuinely dangerous. +- **Forgetting status-quo as competition.** The biggest competitor is usually "doing nothing" or "doing it manually." +- **Outputting territories without rejection criteria.** A territory without a "what this rejects" is not a territory. +- **Treating discovery as a one-time event.** Categories shift. Audiences evolve. Re-run discovery at least every 3 years. + +--- + +## Output format + +Default output is a discovery report at `discovery-report.md` plus appendices. + +Structure: +1. Executive summary (5 to 10 bullets) +2. Audience (1 to 3 named segments with profiles) +3. Competitors (matrix and per-competitor analysis) +4. Category and problem space +5. Positioning territories (3 to 5 candidates) +6. Implications and recommendations +7. Open questions that require further research + +Appendices: +- Interview notes (sanitized) +- Competitor research data +- Source list + +--- + +## Reference files + +- [`references/discovery-report-template.md`](references/discovery-report-template.md) - Full discovery report template. +- [`references/interview-guide.md`](references/interview-guide.md) - Audience interview guide with question prompts. diff --git a/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md b/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md new file mode 100644 index 0000000..68844e7 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md @@ -0,0 +1,177 @@ +# Brand Discovery Report Template + +A fillable template for the discovery deliverable. The discovery report is what every later phase of brand work references. If a section is thin, later phases will be too. + +Fill every section. If a section is "N/A", say why explicitly. + +--- + +## Project metadata + +**Brand / project:** [Name] +**Phase:** [Initial discovery / refresh / repositioning] +**Date:** [YYYY-MM-DD] +**Lead:** [Name] +**Stakeholders interviewed:** [Names and roles] +**Customers interviewed:** [Number, segments] + +--- + +## Executive summary + +Three to five sentences. The single most important thing the discovery surfaced, the strongest opportunity, and the biggest risk. + +> [Summary] + +--- + +## Audience + +### Primary audience + +**Who they are:** [Demographic and behavioral picture. Not a persona archetype. Real, specific, current.] + +**What they want:** [The job they hire the category to do. Surface and underlying.] + +**What they fear or doubt:** [Objections, hesitations, alternative options being considered.] + +**Where they are:** [Channels, communities, sources of trust.] + +**Quotes (verbatim from interviews):** + +> "[Verbatim quote that reveals motivation or pain]" - [Segment] +> "[Verbatim quote]" - [Segment] +> "[Verbatim quote]" - [Segment] + +### Secondary audience(s) + +[Only include if they materially shape the work. Otherwise note "none material" and move on.] + +--- + +## Category and competition + +### The category as the audience sees it + +What the audience calls this category. What they group us with. (Often different from how the company sees it.) + +### Direct competitors + +| Competitor | Position they hold | Strength | Weakness | Opportunity for us | +|---|---|---|---|---| +| | | | | | +| | | | | | +| | | | | | + +### Indirect / adjacent + +[Substitutes the audience considers, even if not in the same product category.] + +### Reference brands (aspirational) + +[Brands the audience admires that we want to be associated with - same audience, different category.] + +--- + +## Positioning territory + +### What we found + +The discovery process should produce 2 to 4 candidate positioning territories. Each is a defensible space the brand could own. + +#### Territory 1: [Name] + +- **Core idea:** [One sentence] +- **Why it could work:** [Audience need it serves, gap in competition, asset we have] +- **Why it could fail:** [Risk, what would have to be true] +- **What it would look like:** [How marketing, product, copy would feel under this territory] +- **Evidence from research:** [Specific findings that support this] + +#### Territory 2: [Name] + +[Same structure] + +#### Territory 3: [Name] + +[Same structure] + +### Recommendation + +The discovery report is allowed to recommend one. Make the case. Or explicitly punt: "Run a positioning workshop with these four candidates." + +--- + +## Brand truths + +What the discovery surfaced about who this brand actually is, not what marketing has been saying. + +### What is true + +- [Fact about the company, founders, product, or community that is real and ownable] +- [Fact] +- [Fact] + +### What is aspirational (and that is OK) + +- [Thing we want to be that we are not yet, but are credibly working toward] +- [Thing] + +### What is not true (and stop saying) + +- [Claim the company makes that did not survive scrutiny] +- [Claim] + +--- + +## Strategic implications + +What the discovery means for the work ahead. + +### For brand identity + +- [Implication, e.g., "The visual direction should signal quietness, not loudness; the audience is exhausted by category noise."] + +### For brand voice + +- [Implication, e.g., "Voice should be confident without being clever; the audience equates cleverness with sales pressure."] + +### For product + +- [Implication if discovery surfaced product-level gaps or strengths] + +### For marketing + +- [Implication for channel strategy, content focus, message hierarchy] + +--- + +## Open questions + +Things discovery raised that it did not answer. These belong in the next phase. + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Methodology and sources + +- **Stakeholder interviews:** [Number, role mix, format] +- **Customer interviews:** [Number, segment mix, format] +- **Customer surveys:** [Sample size, response rate] +- **Competitive scan:** [Number of brands, depth of review] +- **Search and social listening:** [Sources, time window] +- **Internal docs reviewed:** [Strategy decks, prior research] +- **Caveats:** [What this discovery did not cover, sample limitations] + +--- + +## Sign-off + +Discovery accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand ideation / positioning workshop / direct to identity / etc.] diff --git a/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md b/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md new file mode 100644 index 0000000..340ee32 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md @@ -0,0 +1,193 @@ +# Audience Interview Guide + +A guide for conducting 30 to 45 minute interviews with current customers, prospects, or audience members during brand discovery. + +The goal of interviews is not to validate assumptions. It is to find surprises. Plan to be wrong about most of what you think you know. + +--- + +## Before the interview + +### Who to interview + +For a typical brand discovery, talk to 5 to 8 people across these segments: + +- **Active customers** who have been using the product for 3+ months (deep understanding) +- **Recent customers** who joined in the last 30 days (still remember the buying journey) +- **Lapsed customers** who churned (the most informative; understand why people leave) +- **Prospects who didn't buy** (understand objections) +- **Power users** in adjacent categories (understand alternatives and substitutes) + +If the project is for a new brand with no customers yet, interview members of the target audience using competitive products or substitutes. + +### Recruiting + +Recruit through: +- Customer email list with a thank-you incentive +- Sales team referrals +- LinkedIn outreach to titles matching the audience profile +- Existing user research panels +- Niche communities (Reddit, niche Slack groups, professional forums) + +Compensate participants. $50 to $100 in cash or product credit is reasonable for 30 minutes. + +### Logistics + +- 30 to 45 minutes is the right length. Longer fatigues both sides. +- Record (with consent). Take notes too in case the recording fails. +- Use a video tool that creates transcripts automatically. +- Send a calendar invite with a clear agenda. +- Confirm the day before. + +--- + +## Question framework + +Structure interviews in three sections: their world, the problem, and how they currently solve it. + +### Opening (3 to 5 minutes) + +Get them talking. Build rapport. Establish that there are no wrong answers. + +- "Tell me a bit about yourself and what you do." +- "Walk me through a typical day. What does work look like?" +- "How long have you been doing this kind of work?" + +These warm-up questions also surface context you'll need later. + +### Section 1: Their world (10 minutes) + +Understand the context the brand fits into. + +- "When you think about [the problem area or category], what comes to mind?" +- "What's the part of your work or life this connects to?" +- "How important is [the problem area] in the bigger picture of what you do?" +- "Who else is involved in [the problem area]? Coworkers? Family? Clients?" +- "What's the goal you're trying to hit in this area?" + +Listen for: priorities, stakeholders, vocabulary, time pressure. + +### Section 2: The problem (10 to 15 minutes) + +Surface the actual problem, not the surface symptom. + +- "Tell me about the last time you ran into [the problem]. Walk me through what happened." +- "What was frustrating about that?" +- "What did you try to do about it?" +- "What did you wish had happened instead?" +- "What's the cost of this problem? Time? Money? Stress? Relationships?" +- "Have you ever just decided to live with it instead of solving it? Why?" + +Listen for: emotional weight, the real cost, the workarounds people invent, the resignation. + +The key follow-up: **"Tell me more about that."** Use it relentlessly. Most insight is one or two layers below the first answer. + +### Section 3: How they solve it now (10 to 15 minutes) + +Understand the current toolkit and the alternatives considered. + +- "What do you currently use to address [the problem]?" +- "How did you start using [their current solution]? What were you using before?" +- "What did you consider but not pick? Why not?" +- "What do you wish [your current solution] did better?" +- "If you could wave a magic wand and have [the problem] solved perfectly, what would that look like?" +- "Imagine a tool came along that promised to solve [the problem]. What would it have to be true for you to switch?" + +Listen for: the switching cost, the unmet needs, the specific moments where current solutions fail. + +### Closing (3 to 5 minutes) + +- "Is there anything I should have asked but didn't?" +- "Is there anyone else you think I should talk to about this?" +- "Would you be open to a follow-up if questions come up later?" + +--- + +## Common interview pitfalls + +### Leading questions + +**Bad:** "Do you find it frustrating when [your assumption]?" + +**Better:** "Tell me about your last experience with [the activity]." + +The first question telegraphs the answer you want. The second lets them tell you what was actually frustrating, including things you didn't predict. + +### Asking for solutions + +**Bad:** "What features would you want in [the product]?" + +**Better:** "What's frustrating about how this works today?" + +Users are not product designers. They are the world's leading experts on their own frustrations. Mine the frustrations; you'll design the solutions. + +### Validating instead of investigating + +**Bad:** "Would you use [feature description]?" + +**Better:** "When was the last time you needed something like that? What did you do?" + +Hypothetical answers are useless. Past behavior is informative. + +### Closed questions + +**Bad:** "Was that frustrating?" + +**Better:** "How did you feel about that?" + +Yes/no questions kill the conversation. Open questions keep it going. + +### Talking too much + +If you're talking more than 20 percent of the time, you're talking too much. Your job is to listen, follow up, and get out of the way. + +--- + +## Synthesis + +After all interviews, synthesize across them. + +### Step 1: Tag the transcripts + +Read every transcript. Tag passages by theme: +- Pain points +- Workarounds +- Aspirations +- Vocabulary they use +- Emotional moments +- Surprising statements + +### Step 2: Identify recurring patterns + +A theme that appears in 3+ interviews is signal. A theme in 1 interview is interesting but anecdotal. + +### Step 3: Look for surprises + +The most valuable findings are things you didn't expect. List them explicitly. These often become the basis for distinctive positioning. + +### Step 4: Identify quotes + +The right quote captures more than a paragraph of synthesis. Pull 5 to 10 quotes that capture the core insights. + +### Step 5: Write the audience section of the discovery report + +For each segment: +- Who they are (with the specificity you've earned) +- What they're trying to do +- What's getting in the way +- How they currently solve it +- What they wish were different +- Anchor quote (one strong verbatim quote) + +--- + +## What to avoid + +- Treating the interview as a sales pitch +- Asking about your specific product or feature ideas (validation theater) +- Skipping interviews because "we already know our customer" (you don't) +- Interviewing only happy customers (lapsed customers are more informative) +- Doing 1 or 2 interviews and declaring "we did research" +- Skipping synthesis and going straight to "here's what we learned" without rigor + +5 interviews is the minimum to find patterns. 8 is comfortable. 12+ has diminishing returns for most projects. diff --git a/dist/pi/.agents/skills/brand-ideation/SKILL.md b/dist/pi/.agents/skills/brand-ideation/SKILL.md new file mode 100644 index 0000000..55ed7b3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/SKILL.md @@ -0,0 +1,175 @@ +--- +name: brand-ideation +description: "Generate, evaluate, and narrow brand concepts during early ideation including positioning territories, naming candidates, mood directions, and narrative angles. Use this skill whenever the user is in the early phase of brand creation, exploring brand directions, brainstorming names, building moodboards, generating positioning options, or trying to choose between multiple brand directions. Triggers on brand ideation, brand concept, naming, brand name, name candidates, positioning, brand positioning, mood board, brand directions, exploring brands, early brand work, brand exploration, brand brainstorm, brand options. Also triggers when the user has multiple half-formed brand ideas and needs help converging on one, even if they do not say 'ideation' explicitly." +category: brand +catalog_summary: "Naming, positioning territories, mood directions, narrative angles" +display_order: 1 +--- + +# Brand Ideation + +Generate and converge on brand directions before committing to identity work. This is upstream of `brand-identity` (the visual system) and `brand-style-guide` (the documentation). It is the divergent-then-convergent thinking phase where ideas are cheap and direction matters more than polish. + +--- + +## When to use + +- Generating naming options for a new brand or product +- Exploring positioning territories before committing +- Building moodboards and visual direction options +- Drafting narrative or origin-story angles +- Helping the user converge from many half-ideas to one direction +- Stress-testing an existing brand idea before investing in identity work + +## When NOT to use + +- The brand direction is already locked, the user wants logo and identity work (use `brand-identity`) +- Documenting an existing brand system (use `brand-style-guide`) +- Defining voice for an existing brand (use `brand-voice`) +- Initial discovery and audience research (use `brand-discovery`) + +--- + +## Required inputs + +- The category or product type +- The audience (at least roughly) +- The reason this brand exists (the problem it solves or the gap it fills) +- Constraints (existing brand assumptions, parent brand, regulatory limits) +- Number of directions desired (typically 3 to 5) + +If the audience is unclear, run `brand-discovery` first. + +--- + +## The framework: 4 stages + +Brand ideation moves through four stages. Each stage diverges (generate options) then converges (pick a direction). + +### Stage 1: Positioning territories + +A positioning territory is the strategic space the brand occupies. It is not a tagline. It is the answer to "what does this brand stand for that competitors do not?" + +Generate 3 to 5 territories using these angles: + +- **Functional benefit.** "The fastest way to X." (Risk: easy to copy.) +- **Emotional benefit.** "The brand that makes you feel Y." (Risk: vague if not earned.) +- **Identity.** "For people who are Z." (Risk: alienates non-Z customers.) +- **Antagonist.** "The opposite of [incumbent]." (Risk: defines you by them.) +- **Originator.** "The first or only one to do W." (Risk: must be defensible.) +- **Worldview.** "We believe V." (Risk: must be lived, not just stated.) + +For each territory, write: +- **Statement** (one sentence) +- **Why this is true** (the proof point) +- **What this rejects** (the territory we are NOT going to) +- **Risk** (what makes this fragile) + +### Stage 2: Naming directions + +Names cluster by approach. Generate names across multiple approaches, not just one. + +| Approach | Description | Examples | +|---|---|---| +| Descriptive | Says what it is | "General Electric," "American Airlines" | +| Evocative | Suggests a feeling or quality | "Patagonia," "Oasis," "Stripe" | +| Founder | Person's name | "Disney," "Ford," "Tesla" | +| Acronym | Letters from longer phrase | "IBM," "BMW," "AWS" | +| Coined | Made-up word | "Kodak," "Häagen-Dazs," "Asana" | +| Metaphor | Borrowed concept | "Apple," "Amazon," "Twitch" | +| Compound | Two words combined | "Facebook," "PayPal," "Spotify" | +| Suggestive | Hints at function without describing | "Tide," "Sprint," "Slack" | + +Generate 8 to 15 candidates per direction. Apply naming filters before short-listing: + +- **Pronounceable** in target languages +- **Spellable** without confusion +- **Available** as a domain (.com or relevant TLD), social handles, and trademark +- **Distinctive** in the category (search the name + category, see what comes up) +- **Stretchable** (does the name still work if the company expands?) +- **Free of negative associations** (run it past native speakers of any major target market) + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high. + +### Stage 3: Mood and visual direction + +Generate visual directions BEFORE designing anything. Each direction should be distinct enough that a designer would produce visibly different work for each. + +For each mood direction (typically 2 to 4): + +- **Mood adjectives** (3 to 5 words) +- **Color territory** (warm/cool, saturated/muted, light/dark - not specific hex yet) +- **Type territory** (serif/sans, modern/classical, geometric/humanist) +- **Imagery direction** (photography style, illustration style, iconography) +- **Reference brands or sites** (3 to 5 that exemplify the direction) +- **What this rejects** (the visual territory we are NOT going to) + +A mood direction is "Editorial sophistication: Warm cream paper backgrounds, classical serifs, archival photography. Think: The New York Times Magazine meets a literary journal." + +A bad mood direction is "Modern and clean." + +### Stage 4: Narrative and origin + +Every brand has a story. The narrative answers: how do we tell people why this exists? + +Common narrative shapes: + +- **Founder story.** A real person solved a real problem they had. +- **Mission story.** A bigger purpose drives every decision. +- **Discovery story.** We found something the world did not know. +- **Heritage story.** This has always been done a certain way; we honor or refresh it. +- **Frustration story.** The category was broken; we built the alternative. +- **Vision story.** Here is the future we are pulling toward. + +For each candidate narrative: + +- **One-sentence summary** +- **The opening line** (how the story starts when told for the first time) +- **The proof points** (what makes it true and not marketing puff) +- **The hero** (who the audience identifies with - the founder, the customer, the world) + +--- + +## Workflow + +1. **Confirm the inputs.** Category, audience, reason for being, constraints. +2. **Stage 1: Generate 3 to 5 positioning territories.** Use the 6 angles above. Name what each rejects. +3. **Pick 1 to 2 territories.** Move forward with the strongest. +4. **Stage 2: Generate 30 to 50 naming candidates** across at least 4 approaches. Filter to 8 to 12 that pass the six-criteria check. +5. **Stage 3: Generate 2 to 4 mood directions.** Each must be distinguishable enough to brief a designer. +6. **Stage 4: Generate 2 to 3 narrative shapes.** Pick the one that fits the founders, the audience, and the proof points. +7. **Converge.** Present the user with: 1 positioning, 8 to 12 naming finalists, 2 to 4 mood directions, 2 to 3 narrative shapes. Help them pick. +8. **Output.** Use the template in [`references/ideation-output-template.md`](references/ideation-output-template.md). + +--- + +## Failure patterns + +- **Generating one option and calling it "the answer."** The point of ideation is divergence. Without options, there is no real choice. +- **Skipping the rejection step.** A territory that does not name what it rejects is not a territory. Same for moods. +- **Naming before positioning.** Names without positioning end up arbitrary. Position first. +- **Falling in love with one name too early.** Run the full filter on every candidate. The clever name that fails the trademark check is not a candidate. +- **"Modern, clean, minimal" mood direction.** Means nothing. Always require specific reference brands. +- **Skipping pronunciation tests.** Especially for international brands. A name that confuses non-English speakers loses search volume forever. +- **Mistaking ideation for execution.** The output of this stage is direction, not finished assets. Resist the urge to design logos here. + +--- + +## Output format + +Default output is a markdown brief at `brand-ideation.md` in the project root. Includes: + +1. The chosen positioning territory (with what it rejects) +2. Naming finalists (8 to 12) with notes on each +3. Mood directions (2 to 4) with reference URLs +4. Narrative shape (chosen) with opening line and proof points +5. Open questions and decisions still needed before identity work begins + +Optional: a separate `naming-explorations.md` with the full list of 30 to 50 candidates (the "kill file") in case the chosen finalists fail later checks. + +--- + +## Reference files + +- [`references/ideation-output-template.md`](references/ideation-output-template.md) - Fillable template for the ideation deliverable. +- [`references/naming-evaluation-rubric.md`](references/naming-evaluation-rubric.md) - The 6-criteria filter applied with examples. diff --git a/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md b/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md new file mode 100644 index 0000000..e3d208c --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md @@ -0,0 +1,181 @@ +# Brand Ideation Output Template + +A fillable template for the ideation deliverable. Captures the candidate names, positioning territories, mood directions, and narrative angles produced during ideation. + +The deliverable is not a single answer. It is a structured set of options the team can evaluate, narrow, and combine. + +--- + +## Project metadata + +**Brand / project:** [Name] +**Ideation lead:** [Name] +**Date:** [YYYY-MM-DD] +**Inputs used:** [Discovery report, brief, prior decks - link them] + +--- + +## Recap: what we are ideating against + +Two to four sentences. Pull from the discovery report. Anyone reading this deliverable cold should know: + +- Who the audience is +- What position the brand is trying to take +- What the constraints are (legal, geographic, category) + +> [Recap] + +--- + +## Naming candidates + +Generate widely first. Filter later. Aim for 30-50 candidates per round before applying the rubric. + +### Round 1: divergent + +| # | Name | Type | Source / inspiration | +|---|---|---|---| +| 1 | | Coined / descriptive / metaphorical / founder / acronym / compound / portmanteau | | +| 2 | | | | +| 3 | | | | +| ... | | | | + +### Round 2: filtered shortlist + +After applying the 6-criteria rubric (`naming-evaluation-rubric.md`), the names that survive. + +| # | Name | Why it survived | Open concerns | +|---|---|---|---| +| 1 | | | | +| 2 | | | | +| 3 | | | | +| 4 | | | | +| 5 | | | | +| 6 | | | | + +### Round 3: top 3 with full case + +For each finalist, write a one-page case. + +#### Finalist 1: [Name] + +- **Pronunciation:** [How it is said] +- **Type:** [Coined, metaphor, etc.] +- **Meaning:** [What it evokes, intentionally or by association] +- **Why it works:** [Per the 6 criteria] +- **Risks:** [Domain availability, trademark, cultural concerns, audience misreading] +- **Domain status:** [.com / alternative TLDs / acquisition cost estimate] +- **Trademark status:** [Cleared by counsel / preliminary search clean / requires deeper search] +- **Visual potential:** [How it could render as a wordmark, monogram, icon] + +#### Finalist 2: [Name] + +[Same structure] + +#### Finalist 3: [Name] + +[Same structure] + +--- + +## Positioning territories + +The territories from discovery, sharpened into ideation directions. Each territory should produce a distinct creative direction. + +### Territory 1: [Name] + +- **One-sentence position:** [The territory in a sentence] +- **Voice direction:** [How it sounds] +- **Visual direction:** [How it looks] +- **Headline examples:** [3-5 sample headlines that could only come from this territory] +- **What it rules out:** [Names, treatments, or messages this territory disqualifies] + +### Territory 2: [Name] + +[Same structure] + +### Territory 3: [Name] + +[Same structure] + +### Territory 4: [Name] + +[Same structure] + +--- + +## Mood directions + +Three to five mood directions, each with reference imagery, color cues, and a one-line description. These are not final design - they are starting points for art direction. + +### Mood 1: [Name, e.g., "Quiet confidence"] + +- **Description:** [One line] +- **References:** [3-5 visual references with credit and one-line note on what to take from each] +- **Color cues:** [General feel, not exact palette] +- **Typography cues:** [General feel] +- **Photography or illustration direction:** [General feel] +- **Adjacent brands as reference:** [Not to copy, to triangulate] + +### Mood 2: [Name] + +[Same structure] + +### Mood 3: [Name] + +[Same structure] + +--- + +## Narrative angles + +Three to five candidate brand stories or origin narratives. Each is a different way of telling who this brand is and why it exists. + +### Angle 1: [Name, e.g., "Founder's journey"] + +- **Premise:** [The narrative angle in two sentences] +- **First page hero:** [What the homepage hero would say under this angle] +- **About page opening:** [The first paragraph of the about page] +- **Why it works:** [What it earns the brand] +- **Why it might fail:** [Risk] + +### Angle 2: [Name] + +[Same structure] + +### Angle 3: [Name] + +[Same structure] + +--- + +## Synthesis: provisional recommendation + +Even though ideation produces options, the team should leave with a provisional combination to test next. + +> **Provisional combination:** Name [X], territory [Y], mood [Z], narrative [W]. +> +> **Why this combination:** [Two sentences.] +> +> **What we test next:** [Concept board, name validation with audience, treatment exploration, etc.] + +--- + +## Open questions + +- [ ] [Trademark search needed for finalist names] +- [ ] [Domain acquisition feasibility] +- [ ] [Audience reaction test for top 2 names] +- [ ] [Stakeholder alignment session for territory selection] +- [ ] [Other] + +--- + +## Sign-off + +Ideation accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand identity / further name validation / board-level review / etc.] diff --git a/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md b/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md new file mode 100644 index 0000000..d34bbfa --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md @@ -0,0 +1,151 @@ +# Naming Evaluation Rubric + +A name has to clear six bars. This document walks through each, with examples of names that pass and fail. + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high because a name lives forever. + +--- + +## 1. Pronounceable + +A name people cannot say will not get said. + +**Pass:** +- "Stripe" - one syllable, unambiguous +- "Notion" - two syllables, common word, clear stress +- "Loom" - one syllable, common phoneme + +**Fail:** +- "Xobni" (the X is silent? before the b? unclear) +- Names with non-English diacritics for an English-speaking market that get stripped to ambiguity +- "Yext" - is it "yext" with a hard Y or "ekst"? People disagree + +**Test:** Read the name aloud to 5 people who have not seen it written. If 3 of 5 pronounce it differently, fail. + +--- + +## 2. Spellable + +A name people cannot spell will not get found. + +**Pass:** +- "Asana" - phonetic, spelled exactly as it sounds +- "Patagonia" - long but predictable +- "Slack" - one syllable, common word + +**Fail:** +- "Häagen-Dazs" - even the inventors made it hard to spell on purpose +- Names with silent letters that are not standard English +- Names with "ee" / "ea" / "ie" ambiguity +- Names with double letters in unexpected places + +**Test:** Read the name aloud to 5 people. Ask them to spell it. If 2 of 5 misspell it, fail. + +--- + +## 3. Available + +A name you cannot legally use is not a candidate. + +Check, in this order: + +1. **Trademark search** in the relevant jurisdictions. Class matters - you can have the same name as another brand if you operate in different categories, but check. +2. **Domain availability.** The .com (or category-relevant TLD) for the exact name. Adjacent TLDs (.io, .co, .app) are weaker; .com is still default for most categories. +3. **Social handles.** Check the major platforms. Inconsistent handles fragment the brand. +4. **Existing brands in the category.** Even if trademark is technically clear, a confusable competitor name is a problem. +5. **Negative associations.** Search the name in quotes. See what shows up. + +**Pass:** +- A name with .com available, no conflicting trademark, clean handles across major platforms + +**Fail:** +- A name where the .com is parked at $50,000 and no budget exists +- A name that conflicts with a registered trademark in the same class +- A name that someone notable already uses on social platforms + +--- + +## 4. Distinctive + +A name that gets confused with competitors loses every benefit of being a name. + +**Pass:** +- "Stripe" in payments - distinct from PayPal, Square, Adyen +- "Notion" in productivity tools - distinct from Asana, Monday, Trello +- "Loom" in async video - distinct from Zoom, Vimeo, YouTube + +**Fail:** +- A name one letter different from a major competitor +- A name that rhymes with a major competitor +- A name from the same conceptual family (e.g., another fruit name in a market dominated by Apple) +- A name with words common in the category (e.g., "Pay" in fintech, "Code" in dev tools, "AI" in AI products) that gets lost in search + +**Test:** Search the name + category. If your name is buried under unrelated content or competitor confusion, fail. + +--- + +## 5. Stretchable + +A name that locks you into one product or category will hurt as you grow. + +**Pass:** +- "Amazon" - was a bookstore. Now sells everything. +- "Apple" - was a computer company. Now does phones, music, services. +- "Stripe" - "stripe of code" implied developer tools. Now does broader fintech. + +**Fail:** +- "TomatoTracker" - locked to tomatoes +- "PDFMonkey" - locked to PDFs +- Names that explicitly describe a single product feature, when the company plans to be more than that single feature + +**Note:** Locked-in names can be the right choice IF the company is committed to staying narrowly focused. "PDFMonkey" works if you genuinely just want to be the best PDF tool. The failure is when you outgrow the name and have to rebrand at scale. + +**Test:** Imagine the company in 5 years, expanded into adjacent categories. Does the name still fit? If not, plan for it. + +--- + +## 6. Free of negative associations + +A name that means something embarrassing in another language, or that already carries cultural baggage, will hit a ceiling. + +Check: + +- **Translations.** Run the name through a few major target market languages. Native speakers should review (translation tools miss nuance). +- **Slang.** Especially Gen Z and online slang shifts fast. A name that was clean five years ago may not be clean today. +- **Acronyms.** Some names form embarrassing acronyms when written in caps or in initialisms. +- **Visual confusions.** When written in certain fonts, do letters create unfortunate combinations? (Famous example: "kidsexchange" spelled as one word.) +- **Existing pop culture.** Is the name a character in a recent TV show, a banned topic, or a meme? + +**Pass:** +- Cleared in target markets, no recent cultural collisions, no embarrassing acronyms + +**Fail:** +- Names that translate to insults or anatomical terms in target markets +- Names that match recent meme content (the meme will fade but the association sticks) +- Names with unfortunate acronyms (e.g., "Strategic Health Initiative Team") + +**Test:** Native speakers in each target market review. Plus a 5-minute search of the name in pop culture context. + +--- + +## Scoring + +For each candidate name, score 1 to 5 on each of the six criteria, where 5 is "passes cleanly" and 1 is "definite fail." + +A name is short-listable if it scores 4 or 5 on every criterion. A 3 anywhere is a yellow flag (proceed with eyes open). A 2 or 1 anywhere is disqualifying. + +--- + +## Pragmatic notes + +- **Domains:** .com is still default for most US/global brands. Category-specific TLDs (.app, .ai, .io) work in some categories but require more brand investment to teach the audience. +- **Trademark:** Get a real attorney to clear the trademark before launch. The cost of a TM search is dramatically less than a rebrand. +- **Generic names** (descriptive of the category) cannot be trademarked and will struggle with distinctiveness. +- **Made-up names** are easier to clear and trademark but require more marketing investment to load with meaning. +- **Founder names** carry heritage but can complicate equity and exits. + +--- + +## When to walk away + +If the top 3 candidates all fail at least 2 criteria, the naming exploration was not deep enough. Generate another 30 to 50 candidates before settling. The cost of a bad name is paid every day for the life of the brand. diff --git a/dist/pi/.agents/skills/brand-identity/SKILL.md b/dist/pi/.agents/skills/brand-identity/SKILL.md new file mode 100644 index 0000000..f3a8ef8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/SKILL.md @@ -0,0 +1,203 @@ +--- +name: brand-identity +description: "Design or evaluate a brand visual identity system covering logo, color, typography, imagery direction, iconography, and motion principles. Use this skill whenever the user wants to design a logo, build a visual identity, define brand colors, choose brand typography, develop iconography, plan brand imagery, or evaluate an existing identity for cohesion. Triggers on logo design, brand identity, visual identity, brand mark, wordmark, monogram, color palette, brand colors, brand typography, type system, iconography, brand imagery, motion design, brand system, identity system. Also triggers when the user has a brand direction approved and now needs the visual artifacts that express it." +category: brand +catalog_summary: "Logo system, color, typography, imagery, iconography, motion" +display_order: 2 +--- + +# Brand Identity + +Design or evaluate the visual artifacts that express a brand: logo system, color, typography, imagery, iconography, and motion. Stack-agnostic. Tool-agnostic. + +This skill assumes a brand direction is already approved (positioning, mood, name). If not, run `brand-ideation` first. + +--- + +## When to use + +- Designing a logo system +- Defining a brand color palette +- Choosing brand typography +- Developing iconography or illustration style +- Defining imagery direction (photography, illustration) +- Establishing motion principles +- Auditing an existing identity for cohesion or gaps + +## When NOT to use + +- Brand direction is not yet defined (use `brand-ideation`) +- Documenting a finished system (use `brand-style-guide`) +- Defining voice and tone (use `brand-voice`) +- Building UI components from an existing brand (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- The brand name and approved positioning +- The mood direction (from ideation, or supplied as references) +- Audience and category context +- Application contexts (web, print, packaging, motion - whatever applies) +- Constraints (parent brand requirements, regulatory marks, accessibility minimums) + +--- + +## The framework: 5 elements + +A complete identity has five elements. Each element should reinforce the others. Inconsistency between them is the most common identity failure. + +### 1. Logo system + +Most brands need not one logo but a system of marks for different contexts. + +**Components of a logo system:** + +- **Primary mark.** The main logo. Used wherever there is room. +- **Wordmark.** Just the typography, no symbol. Used in tight horizontal contexts. +- **Symbol or glyph.** Just the symbol, no type. Used in app icons, favicons, social avatars. +- **Lockup variations.** Horizontal, stacked, square - whichever apply. +- **Monogram.** The initial(s) styled as a mark. Optional but useful for small contexts. + +**Design principles:** + +- **Legible at 16 pixels.** Test the logo at favicon size. If it falls apart, redesign. +- **Reproducible in single-color.** If the logo only works in full color, it cannot be screen-printed, embroidered, or rendered in browser favicons. +- **Distinctive silhouette.** Squint at it. Can you still tell what it is? If it looks like every other logo in the category at silhouette, redesign. +- **Construction grid.** Every curve and angle is intentional. Document the construction. + +**Common failure:** +- Designing only the primary mark and discovering at launch that the wordmark, glyph, and small-size variants do not exist. + +### 2. Color system + +A color system is more than a palette. It is the rules for how color carries meaning. + +**Components:** + +- **Primary color.** The signature color most associated with the brand. +- **Secondary colors.** 1 to 3 supporting colors that extend the palette. +- **Neutrals.** The grays and tints that make up most of the surface area. +- **Semantic colors.** Success, warning, error, info - if the brand operates in product UI. +- **Accent colors.** Used sparingly for highlight and emphasis. + +**Per color, document:** +- Hex, RGB, HSL, CMYK (if print is in scope), and Pantone (if brand-critical print exists) +- WCAG AA contrast against the other colors in the system +- Allowed and disallowed pairings (some brand colors look terrible together) +- Usage notes (when to use, when not to use) + +**Design principles:** + +- **Test for accessibility.** WCAG AA requires 4.5:1 contrast for normal text, 3:1 for large text. If the brand color cannot pass either against white, you have a problem. +- **Test for color blindness.** Around 8 percent of men have some form of color blindness. Critical UI signals should not rely on color alone. +- **Define neutrals carefully.** Neutrals are 80 percent of the surface area in most brand applications. They carry more weight than the brand color. +- **Limit the palette.** A 30-color palette is unmanageable. 5 to 8 carefully chosen colors beats a sprawling system. + +### 3. Typography + +Type is the second-most-recognizable element of a brand after the logo. + +**Components of a type system:** + +- **Display typeface.** For headlines and brand moments. +- **Body typeface.** For long-form reading. Often the same as display, sometimes different. +- **Monospace typeface** (if applicable for technical brands). +- **Type scale.** The set of sizes used across applications. Typically 5 to 8 steps. +- **Type weights and styles.** Which weights and italics are part of the system. + +**Design principles:** + +- **Pairing.** If using two typefaces, they must work together at body and display sizes. Common pattern: serif display + sans body, or geometric sans display + humanist sans body. +- **Web licensing.** Confirm web licensing covers expected pageviews. Some popular typefaces have prohibitive web licenses. +- **Variable fonts** are increasingly the right call for performance and flexibility. +- **Fallback stack.** Specify system fallbacks for when the brand font fails to load. The fallback should be visually similar. +- **Open-source alternatives.** Document open-source equivalents for situations where licensing is impractical (third-party tools, embedded contexts). + +### 4. Imagery and illustration + +Imagery direction is often underspecified, leading to brand drift over time. + +**Photography direction:** + +- **Subject matter.** What does the brand show? +- **Composition style.** Tight crops, wide environments, candid, posed? +- **Lighting.** Bright and natural, dramatic and directional, soft and diffused? +- **Color treatment.** True color, warm shifted, desaturated, high-contrast? +- **What to reject.** Stock photo aesthetics, specific cliches in the category. + +**Illustration direction:** + +- **Style.** Flat, dimensional, hand-drawn, geometric, abstract, representational? +- **Color use.** Full palette, restricted palette, brand colors only? +- **Line treatment.** Bold and outlined, soft and shaded, no outlines? +- **Subject matter.** What gets illustrated and what does not? + +**Iconography:** + +- **Style.** Filled or outline. Rounded or sharp. Single weight or variable. +- **Grid.** Pixel-perfect grid (often 24x24 or 16x16 base). +- **Stroke weight.** Consistent across the icon set. +- **Set.** Which icons exist, and how new icons get added consistently. + +### 5. Motion + +If the brand lives in any digital product, marketing video, or animated touchpoint, motion is part of the identity. + +**Motion principles to define:** + +- **Easing curves.** Default easings used across animations. Linear, ease-in-out, custom. +- **Duration scale.** Fast (100ms), medium (200-300ms), slow (500ms+) and when each applies. +- **Choreography.** How elements enter, exit, and respond to interaction. +- **Brand moments.** Signature animations (logo build, page transitions, loaders). + +**Design principles:** + +- **Restraint.** Most motion in product UI should be quick and subtle. Reserve dramatic motion for brand moments. +- **Reduced motion.** Always provide a `prefers-reduced-motion` alternative for users with vestibular sensitivities. +- **Performance.** Animations must be 60fps on the target devices. Profile before shipping. + +--- + +## Workflow + +1. **Confirm brand direction.** Positioning, mood, audience. If unclear, return to `brand-ideation`. +2. **Audit applications.** List every place the brand will appear (web, print, packaging, app, social, signage, video). The application contexts drive what the system needs to handle. +3. **Element-by-element design.** Start with logo and color, since these constrain typography. Then type. Then imagery, iconography, motion. +4. **Stress-test.** Apply the system to 3 to 5 mock applications (homepage, social post, business card, product UI, signage). Where does it break? Iterate. +5. **Document.** Each element with rules, examples, and dos/don'ts. This becomes the input to `brand-style-guide`. +6. **Get sign-off** before broad rollout. Identity changes after rollout are 10x the cost of changes during design. + +--- + +## Failure patterns + +- **Designing logos in isolation from application.** A logo that looks great on a hi-res mockup but illegible at favicon size is a design failure. +- **Picking a brand color without contrast testing.** A brand color that fails WCAG AA against white means UI built on the brand will be inaccessible by default. +- **Specifying typography without checking web licensing.** Discovering at deploy that the foundry charges per-pageview for the chosen typeface is a budget-buster. +- **Skipping imagery direction.** Without it, the brand becomes whatever stock photos the next person picks. +- **Treating motion as decoration.** Inconsistent motion erodes brand cohesion as fast as inconsistent color. +- **Designing only primary states.** What does the brand look like in error? In dark mode? In a localization where the wordmark needs to flip direction? These are not edge cases; they are the brand. + +--- + +## Output format + +Default output is a structured set of files: + +- `identity/logo/` - All logo variants (SVG primary, plus PNG/JPG exports at common sizes) +- `identity/colors.md` - Color system with hex codes, contrast ratios, usage rules +- `identity/typography.md` - Type system with scale, weights, fallbacks +- `identity/imagery.md` - Imagery direction with reference examples +- `identity/iconography/` - Icon set or icon style spec +- `identity/motion.md` - Motion principles +- `identity/applications/` - 3 to 5 application mockups stress-testing the system + +These feed directly into `brand-style-guide`. + +--- + +## Reference files + +- [`references/identity-system-spec.md`](references/identity-system-spec.md) - Detailed spec template for documenting each element. +- [`references/contrast-and-accessibility.md`](references/contrast-and-accessibility.md) - Accessibility checks for color and type, with the math. diff --git a/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md b/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md new file mode 100644 index 0000000..d0f964e --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md @@ -0,0 +1,188 @@ +# Contrast and Accessibility for Brand Identity + +A brand color choice that fails accessibility is a design defect. Every product, page, button, and label using that color inherits the failure. + +This reference walks through the math, the standards, and the practical implications. + +--- + +## The standards + +**WCAG 2.1 AA** is the minimum bar for most professional brand work. + +| Element | Required contrast ratio | +|---|---| +| Normal body text | 4.5:1 | +| Large text (18pt regular or 14pt bold) | 3:1 | +| UI components and graphical elements | 3:1 | + +**WCAG 2.1 AAA** is stricter. Required for some accessibility-focused products, optional but admirable for most. + +| Element | Required contrast ratio | +|---|---| +| Normal body text | 7:1 | +| Large text | 4.5:1 | + +--- + +## The math + +Contrast ratio is calculated as: + +``` +(L1 + 0.05) / (L2 + 0.05) +``` + +Where L1 is the relative luminance of the lighter color and L2 of the darker. Relative luminance comes from a weighted formula on RGB values that accounts for human perception (green contributes more than blue). + +**Quick contrast checker (run in browser console):** + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + return ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2) + ':1'; +} + +// Example +contrast('#FFFFFF', '#4B5563'); // returns '6.40:1' +``` + +--- + +## Common brand color failures + +These are color choices that look great in a logo but fail WCAG when used for text or UI: + +| Pairing | Ratio | Status | +|---|---|---| +| Light gray (#9CA3AF) on white | 2.85:1 | Fails AA | +| Bright yellow on white | 1.07:1 | Fails AAA, AA, and basic legibility | +| Bright orange (#FF9900) on white | 2.14:1 | Fails AA | +| Sky blue (#3B82F6) on white | 4.57:1 | Passes AA for normal text | +| Most "vibrant" brand reds on white | 3-4.5:1 | Borderline; check exact values | +| White text on bright orange | 2.14:1 | Fails AA | + +When in doubt, darken the brand color for text contexts. Keep the original hue for non-text brand expressions (logos, large graphics, decorative elements). + +--- + +## The "darker variant" strategy + +For brand colors that fail AA contrast, define a darker variant for use in text and UI. + +``` +Brand orange (signature): #FF9900 (used in logos, illustrations, large graphics) +Brand orange (text/UI): #B86600 (passes AA against white) +``` + +Both are "the brand color." The signature version is what people associate with the brand. The text variant is what enables accessible UI without abandoning the identity. + +This is standard practice. Most major brands have both versions, even if only the signature version is publicized. + +--- + +## Color blindness considerations + +Around 8 percent of men and 0.5 percent of women have some form of color vision deficiency. The most common is red-green (deuteranopia and protanopia). + +**Tests to run:** + +- **Red-green confusion.** Greens and reds at similar luminance look the same to deuteranopes. If your success/error indicators rely on red-green distinction, add an icon or text label. +- **Tritan simulation.** Less common but worth checking. Blues and yellows. +- **Greyscale conversion.** Convert your palette to grayscale. If two brand colors look identical in greyscale, they will be hard to distinguish for people with severe color blindness. + +**Tools:** Stark plugin (Figma), Coblis (online simulator), Chrome DevTools rendering tab. + +**Practical rule:** Critical UI signals must communicate through more than just color. Use icons, labels, position, or shape as redundant signals. + +--- + +## Typography contrast + +Type contrast is not just about color. It includes: + +- **Color contrast** (per the standards above) +- **Weight contrast** (light text on a busy background fails even at high color contrast) +- **Size contrast** (very small text needs higher color contrast) + +**Practical rules:** + +- Body text: minimum 14px on web, ideally 16px. Below 14px is uncomfortable for most readers regardless of contrast. +- Body text on photographs or busy backgrounds: add a scrim, increase the type weight, or move the text. +- Light-weight fonts (Thin, Extra Light) for body text: avoid. They fail visual contrast even at passing color contrast. + +--- + +## Dark mode considerations + +Most brand colors that work on white do not work on dark backgrounds. + +**Common failure:** +- Brand color = dark navy. On white: 12:1 contrast (excellent). On near-black: 1.4:1 (terrible). + +**Solutions:** + +- Define light-mode AND dark-mode variants of every functional color in the system. +- Brand colors typically need to be lightened or desaturated in dark mode. +- Test the entire palette against both light and dark surfaces. + +``` +Brand navy: + Light mode (on white): #0F2A4A (12:1 contrast) + Dark mode (on #111): #6B9FE8 (5.2:1 contrast against #111) +``` + +Both are "the brand color." Both express the identity. They just live in different lighting conditions. + +--- + +## Icons and graphical elements + +WCAG requires 3:1 for UI components and graphical elements. This includes: + +- Icons used to convey meaning +- Form field borders +- Focus indicators +- Chart elements that distinguish data series +- Toggle and switch states + +**Common failure:** +- Light gray icon (#D1D5DB) on white background: 1.4:1. Invisible to users with low vision. +- Form field borders at #E5E7EB: 1.3:1. Borderline visible. + +**Fix:** +- Icons that convey meaning: minimum #6B7280 on white (3.9:1). +- Form field borders: minimum #9CA3AF on white (3.0:1) for default state. Stronger for focus. + +--- + +## Practical checklist for brand color decisions + +Before locking a brand color: + +- [ ] Tested against white at WCAG AA for body text (4.5:1) +- [ ] Tested against white at WCAG AA for large text (3:1) +- [ ] Tested against the brand's dark surface color (for dark mode) +- [ ] Tested for color blindness (deuteranopia simulation) +- [ ] A "darker variant" defined for text contexts if signature color fails AA +- [ ] White text on the brand color tested for 4.5:1 (for buttons and CTAs) +- [ ] All semantic colors (success, warning, error) pass AA on white and dark +- [ ] Neutrals scale tested across the full range + +If any check fails, document the failure and provide an alternative variant for the failing context. Do not just hope it will be fine in practice. It will not be fine. + +--- + +## Resources + +- WebAIM Contrast Checker (free, browser-based) +- Stark plugin for Figma +- Chrome DevTools accessibility panel +- Coblis color blindness simulator +- WCAG 2.1 specification at w3.org diff --git a/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md b/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md new file mode 100644 index 0000000..4b08849 --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md @@ -0,0 +1,212 @@ +# Identity System Spec + +A spec template for documenting each element of the brand identity system. This is the working document during identity build, before the polished style guide. It locks decisions and exposes gaps. + +Fill every section. The point of the spec is to surface what is undecided. + +--- + +## System metadata + +**Brand:** [Name] +**Version:** [v1.0, v1.1, etc.] +**Date:** [YYYY-MM-DD] +**Owner:** [Name] +**Status:** [Draft / In review / Approved] + +--- + +## 1. Logo system + +### Primary logo + +- **Form:** [Wordmark / lettermark / combination mark / pictorial / abstract] +- **Construction notes:** [Geometry, custom letterforms, optical adjustments] +- **Source files:** [SVG, AI, layered] +- **Color versions:** [Full color, single color, reversed (white on dark)] +- **Minimum size:** [Pixels for digital, inches/mm for print] +- **Clear space:** [Minimum margin around logo, defined as multiple of a logo element, e.g., "1x cap height"] + +### Logo variants + +| Variant | When to use | Source file | +|---|---|---| +| Horizontal | Default | | +| Stacked | Constrained widths, social avatars | | +| Mark only | Favicons, app icons, watermarks | | +| Wordmark only | Inline text contexts | | + +### Misuse rules + +What never to do with the logo. Ten short rules at most. + +- Do not stretch +- Do not rotate +- Do not recolor outside the approved palette +- Do not place on busy photography without a scrim +- (etc.) + +### Application examples + +Where the logo lives. Document the canonical placements. + +- Web header: [Position, size, color treatment] +- Email signature: [Position, size] +- Favicon: [Variant used, sizes generated] +- App icon: [Variant, background, padding] +- Print: [Letterhead, business card] +- Social: [Avatar variant, banner specs] + +--- + +## 2. Color + +### Primary palette + +| Token name | Hex | RGB | HSL | Usage | +|---|---|---|---|---| +| `color-brand-primary` | | | | Primary brand color, dominant in identity | +| `color-brand-secondary` | | | | Secondary brand color | +| `color-brand-tertiary` | | | | Optional accent | + +### Neutrals + +| Token name | Hex | Usage | +|---|---|---| +| `color-neutral-0` | #FFFFFF | Background, max contrast | +| `color-neutral-50` | | | +| `color-neutral-100` | | | +| `color-neutral-200` | | | +| ... | | | +| `color-neutral-900` | | | +| `color-neutral-1000` | #000000 | | + +### Semantic tokens + +| Token name | Resolves to | Usage | +|---|---|---| +| `color-text-primary` | | Body text | +| `color-text-secondary` | | Captions, less important text | +| `color-text-disabled` | | Disabled state | +| `color-text-inverse` | | Text on dark backgrounds | +| `color-bg-primary` | | Default background | +| `color-bg-elevated` | | Cards, modals | +| `color-border-default` | | Card borders, dividers | +| `color-success` | | | +| `color-warning` | | | +| `color-error` | | | +| `color-info` | | | + +### Color rules + +- Never invent a new color. If a use case is not covered, propose a new token. +- Brand color contrast against approved backgrounds must meet WCAG AA for text. See `contrast-and-accessibility.md`. +- Dark mode tokens defined separately or via theme switch logic. + +--- + +## 3. Typography + +### Type families + +| Role | Family | Weights used | License | +|---|---|---|---| +| Display | | | | +| Body | | | | +| Mono (code, data) | | | | + +### Type scale + +| Token | Size | Line height | Weight | Use case | +|---|---|---|---|---| +| `text-display-1` | | | | Hero headline | +| `text-display-2` | | | | Section headline | +| `text-h1` | | | | Page title | +| `text-h2` | | | | Section title | +| `text-h3` | | | | Sub-section | +| `text-body-lg` | | | | Lead paragraph | +| `text-body` | | | | Default body | +| `text-body-sm` | | | | Caption, supporting text | +| `text-label` | | | | UI labels | +| `text-overline` | | | | Eyebrow text | + +### Typography rules + +- Display weights only at display sizes. Do not use display weights for body. +- Body line height target 1.5 to 1.65 for readability. +- Line length target 50 to 75 characters per line. +- Avoid mixing more than two type families on a single page. + +--- + +## 4. Iconography + +- **Style:** [Outline / filled / mixed / two-tone] +- **Stroke weight:** [Specific px or em value] +- **Corner radius:** [Specific px] +- **Grid:** [24x24 default, with optional 16, 32, 48 sizes] +- **Source:** [Custom set / Lucide / Heroicons / Phosphor / Material] +- **Naming convention:** [`icon-[noun]-[modifier]`] +- **License:** [If using a third-party set] + +### Icon rules + +- Icons paired with labels by default. Icon-only buttons require an accessible label. +- Decorative icons get `aria-hidden="true"`. +- Functional icons inherit text color via `currentColor`. + +--- + +## 5. Imagery + +### Photography + +- **Style:** [Editorial / lifestyle / product / documentary / abstract] +- **Color treatment:** [Natural / treated / desaturated / signature filter] +- **Composition:** [Tight / wide / asymmetrical / symmetrical / negative space] +- **Subject direction:** [Demographics, environments, energy] + +### Illustration + +- **Style:** [If applicable - flat / textured / line / mixed] +- **Color usage:** [Limited palette / full palette] +- **Pattern library:** [Where it lives] + +### Stock and AI policy + +- **Stock photography:** [Allowed / banned / case-by-case with approval] +- **AI-generated imagery:** [Allowed / banned / case-by-case] +- **Sources approved:** [Specific platforms or studios] + +--- + +## 6. Motion + +- **Default duration:** [ms - typically 200-300] +- **Default easing:** [Standard easing curve, e.g., `cubic-bezier(0.4, 0, 0.2, 1)`] +- **Token naming:** [`motion-duration-fast`, `motion-easing-standard`] +- **Reduced motion:** [What animates becomes static when `prefers-reduced-motion: reduce`] + +--- + +## 7. Voice (cross-reference) + +Voice has its own deliverable. See the brand voice document. The identity spec only notes voice attributes that interact with visual identity (e.g., if voice is "quiet," typography should not be loud). + +--- + +## Open questions + +- [ ] [Token naming convention finalized?] +- [ ] [Dark mode strategy defined?] +- [ ] [Brand color WCAG contrast verified across approved backgrounds?] +- [ ] [Icon set licensed for production?] +- [ ] [Photography source defined?] + +--- + +## Sign-off + +- Design lead: [Name, date] +- Creative director: [Name, date] +- Engineering lead (for token implementability): [Name, date] diff --git a/dist/pi/.agents/skills/brand-style-guide/SKILL.md b/dist/pi/.agents/skills/brand-style-guide/SKILL.md new file mode 100644 index 0000000..a852bf3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/SKILL.md @@ -0,0 +1,202 @@ +--- +name: brand-style-guide +description: "Build or audit a comprehensive brand style guide that documents the full brand system including story, logo system, color, typography, imagery, voice, applications, and dos/don'ts. Use this skill whenever the user wants to create brand guidelines, document an existing brand, build a brand book, audit an existing style guide for completeness, or produce the artifact that other teams will reference for years. Triggers on style guide, brand guidelines, brand book, brand standards, brand manual, style sheet, brand documentation, brand reference. Also triggers when the brand identity is finished and needs to be documented for handoff to designers, developers, vendors, or future team members." +category: brand +catalog_summary: "The canonical reference document for the full brand system" +display_order: 3 +--- + +# Brand Style Guide + +Document the brand system so other people can use it without ambiguity. This is the artifact that lives longest. Designers, developers, agencies, and vendors will reference it for years. Build it like a reference manual, not a presentation. + +This skill assumes the brand identity is designed (run `brand-identity` first if not). The output of this skill is the canonical reference document. + +--- + +## When to use + +- Creating brand guidelines for a finished identity +- Documenting an existing brand that has no formal guide +- Auditing an existing style guide for gaps or inconsistencies +- Building a brand book to hand to vendors, partners, or new team members +- Updating a guide after a major brand evolution + +## When NOT to use + +- The brand identity is not yet designed (use `brand-identity`) +- Brand voice work specifically (use `brand-voice` for the voice doc, then integrate) +- Building UI components (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- Finished brand identity (logo, colors, typography, imagery direction, motion principles) +- Brand voice and tone documentation (or sufficient inputs to write a voice section) +- Application examples that show the brand in real contexts +- Decisions on what is mandatory vs flexible vs forbidden + +--- + +## The framework: 8 sections + +A complete style guide has eight sections. Most guides skip 2 or 3 of them and create downstream confusion. Build all 8 from the start. + +### 1. Story +The narrative behind the brand. Why it exists, what it stands for, what it rejects. + +- Origin / founding story +- Mission and vision +- Values (3 to 5, with what each means in practice) +- Positioning statement +- Audience (with the level of specificity from the brief) +- What we are not (the things we explicitly reject) + +### 2. Logo system +Every variant of every mark, with rules. + +- Primary logo (with construction grid showing relationships) +- Wordmark +- Symbol / glyph +- Lockup variations (horizontal, stacked, etc.) +- Monogram (if part of system) +- Clear space rules (minimum spacing around logo) +- Minimum sizes (smallest acceptable size for print and digital) +- Acceptable color treatments (full color, single color, knock-out, reverse) +- Forbidden treatments (stretching, rotating, recoloring, drop shadows, gradients - whatever is forbidden) +- File formats and where to find them + +### 3. Color +The full color system with rules. + +- Primary palette (signature colors) +- Secondary palette +- Neutrals scale +- Semantic colors (success, warning, error, info) +- Light mode and dark mode variants +- Per color: hex, RGB, HSL, CMYK, Pantone (if print-relevant) +- Contrast ratios documented +- Allowed pairings +- Forbidden pairings +- Usage hierarchy (primary first, secondary supporting, neutrals dominant) + +### 4. Typography +The full type system. + +- Display typeface (with sample sizes) +- Body typeface (with sample sizes) +- Monospace (if applicable) +- Type scale (specific sizes used) +- Weight and style usage (which weights for which contexts) +- Line height ratios +- Letter spacing standards +- Web fallback stacks +- Open-source alternatives for licensing-restricted contexts +- Forbidden treatments (all caps overuse, fake italics, etc.) + +### 5. Imagery and illustration +What pictures look like in this brand. + +- Photography direction with example library +- Illustration style with example library +- Iconography system with the full icon set (or rules for adding to it) +- Forbidden imagery (stock photo cliches, specific things never to show) +- Photo treatment rules (color treatment, crops, composition) + +### 6. Voice and tone +How the brand sounds. (Pulled from `brand-voice` work if done separately.) + +- Voice attributes (3 to 5 adjectives with "we are X, not Y" framing) +- Tone shifts by context (onboarding, error, marketing, support, legal) +- Vocabulary preferences (words we use, words we avoid) +- Grammar and style rules +- Examples (good and bad copy side by side) + +### 7. Applications +The brand applied to real contexts. + +- Web (homepage, product pages, blog template) +- Email (template, signature, transactional) +- Social (post templates, profile imagery, story formats) +- Print (business cards, letterhead, print ads) +- Packaging (if applicable) +- Signage (if applicable) +- Internal documents (slides, reports, proposals) +- Each with examples showing what good looks like + +### 8. Dos and don'ts +The boundaries, illustrated. + +- Logo dos and don'ts (visual examples of correct and incorrect use) +- Color dos and don'ts (combinations to use, combinations to avoid) +- Type dos and don'ts (treatments to use, treatments to avoid) +- Composition dos and don'ts (layout patterns that work, ones that do not) +- Voice dos and don'ts (phrases that fit, phrases that do not) + +The dos and don'ts section is what people actually reference in practice. Make it the easiest section to scan. + +--- + +## Workflow + +1. **Inventory the inputs.** What identity work is finished? What voice work is finished? What is missing? +2. **Confirm the format.** Is this a PDF, a web page, a Notion doc, a printed book, or all of the above? Different formats have different production requirements. +3. **Section by section, draft.** Use the template in [`references/style-guide-template.md`](references/style-guide-template.md). +4. **Stress-test with real examples.** For every rule, find a real application example. Rules without examples get ignored. +5. **Get review from the people who will use it.** Designers, developers, marketers. They will surface gaps. +6. **Version control.** Style guides evolve. Date the doc. Note what changed in each version. +7. **Publish in the format the team will actually open.** A 200-page PDF that lives on a shared drive is dead weight. A web page or Figma file with a clear URL gets used. + +--- + +## Failure patterns + +- **Skipping the "what we are not" sections.** Without rejection rules, anything becomes acceptable. +- **Document with no examples.** Rules without visual examples are abstract and ignored. +- **Document with only examples.** Examples without rules cannot be applied to new situations. +- **Static PDF that no one opens.** Ship the guide in the format the team uses daily (web page, Figma, Notion, etc.). +- **No version history.** When the brand evolves, no one knows which rules changed or when. +- **Aspirational rules.** Rules the brand does not actually follow get treated as suggestions. Document what is actually true, not what is wished. +- **Treating "dos and don'ts" as filler.** This section is what people use most. Invest in it. + +--- + +## Output format + +Default output is a multi-section markdown document or a structured set of files, plus a presentation-ready version (web page, PDF, or Figma) for sharing with stakeholders. + +Recommended structure: + +``` +brand/ + style-guide.md (the canonical document) + story.md (or as a section) + logo/ + construction.md + files/ (SVG, PNG, etc.) + colors.md + typography.md + imagery/ + photography.md + illustration.md + icons/ + icons.md + files/ + voice.md + applications/ + web.md + email.md + social.md + print.md + dos-and-donts.md +``` + +For consumer-facing presentation, build a web page version that imports from these source files. The source files are canonical. The presentation is a view of them. + +--- + +## Reference files + +- [`references/style-guide-template.md`](references/style-guide-template.md) - Fillable section-by-section template. +- [`references/maintenance-playbook.md`](references/maintenance-playbook.md) - How to keep the guide current after launch. diff --git a/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md b/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md new file mode 100644 index 0000000..33e208d --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md @@ -0,0 +1,251 @@ +# Brand Style Guide Maintenance Playbook + +A style guide that does not get maintained becomes a museum piece within a year. This playbook covers who owns it, when it gets updated, and how change requests get handled. + +--- + +## Why guides decay + +The common failure modes: + +- **No owner.** The guide was a project deliverable. The team disbanded. No one maintains it. +- **Drift.** Real work in market diverges from the guide. The guide stops reflecting reality. +- **Frozen in time.** The guide was right at launch. Markets, products, and audiences moved. +- **Locked away.** The guide lives in a tool nobody opens. Teams reinvent rather than reference. +- **Too rigid.** The guide bans variation that real work demands. Teams ignore it rather than challenge it. + +The maintenance playbook addresses each of these. + +--- + +## Ownership + +### The owner + +Every brand guide has one owner. Not a committee. The owner: + +- Is named in the guide itself +- Has explicit authority to approve changes +- Has time allocated (typically 5-10% of one role) for guide upkeep +- Reports to a stakeholder who cares about brand consistency + +If the role is vacant, the guide is at risk regardless of how good the content is. + +### The guidance council (optional) + +For larger organizations, a small council reviews proposed changes before the owner approves. Typically: + +- Brand lead (chair) +- Design lead +- Marketing lead +- Engineering lead (if guide includes design tokens / dev assets) +- One product representative + +The council meets quarterly to review the change queue. + +--- + +## Change types and authority + +Not every change needs the same review. Define tiers. + +### Tier 1: clarifications (owner approves directly) + +- Typo fixes +- Adding examples to existing rules +- Improving wording without changing meaning +- Adding missing assets that are already approved (new logo file format, etc.) + +**Process:** owner ships within a week. + +### Tier 2: extensions (owner consults, then approves) + +- New use cases for existing elements +- New approved color combinations +- New typographic patterns within the existing scale +- New illustration or photography patterns within existing direction + +**Process:** owner posts to a working channel for 5-day comment period, addresses feedback, ships. + +### Tier 3: changes (council reviews, owner ships) + +- Modifying or expanding the color palette +- Modifying the type scale +- Adding or removing approved photographic styles +- Updating logo construction or variants +- Voice tone adjustments + +**Process:** RFC document, council review at quarterly meeting (or async if time-sensitive), then owner ships. + +### Tier 4: shifts (executive approval required) + +- Logo redesign +- Brand voice repositioning +- Color palette overhaul +- Naming or positioning changes + +**Process:** full brand project. Treat as a separate engagement, not a maintenance ticket. + +--- + +## Update cadence + +Even without inbound change requests, schedule reviews. + +| Cadence | What happens | +|---|---| +| Monthly | Owner sweeps the change queue, ships Tier 1 fixes, queues Tier 2 for the comment period. | +| Quarterly | Council reviews Tier 3 RFCs, takes a sample-based audit (see below), updates roadmap. | +| Annually | Full audit (see audit playbook), refresh of examples, prune of stale content, version bump. | +| As-needed | Tier 4 shifts driven by business strategy. | + +--- + +## Change request process + +Anyone in the organization can propose a change. The process: + +1. **Submit** via the request channel (template below). +2. **Triage** by owner within 5 business days. Assigns tier. +3. **Comment / review** depending on tier. +4. **Decide.** Approve, decline (with reason), or revise. +5. **Ship.** Update the guide, update related assets, communicate. +6. **Communicate.** Announce in the brand channel. Note in the changelog. + +### Request template + +``` +**What is the change?** +[One paragraph] + +**Why is it needed?** +[Real use case that surfaced this] + +**What is affected?** +[Pages, assets, components] + +**Proposed solution** +[Specific change to the guide] + +**Alternatives considered** +[Other ways to solve this] + +**Requester** +[Name, team] +``` + +--- + +## Audit cadence + +### Monthly: surface scan + +Owner scans 5-10 randomly selected production touchpoints (web pages, ads, emails, social posts) and notes any guide violations or undocumented patterns. 30 minutes max. + +The output is a row in a tracking sheet, not a deliverable. Used to surface drift trends. + +### Quarterly: sample audit + +Owner (or council) audits 20-30 production touchpoints across channels. Categorize each: + +- Compliant +- Minor deviation (acceptable, document if recurring) +- Major deviation (followup required) +- Undocumented pattern (consider adding to guide) + +Output: a one-page summary with action items. + +### Annual: full audit + +Use the audit template (typically a separate audit deliverable, not part of the guide itself). Full review across: + +- Logo usage +- Color +- Typography +- Imagery +- Voice and copy +- Motion and interaction +- Adoption (which teams use the guide vs work around it) + +Output: a backlog for the next year. + +--- + +## Versioning + +Use semantic versioning for the guide. + +- **Major (1.0 → 2.0):** brand shift. Logo redesign, voice repositioning, palette overhaul. +- **Minor (1.1 → 1.2):** new sections, expanded color or type, new approved patterns. +- **Patch (1.1.1 → 1.1.2):** clarifications, typo fixes, new examples. + +Each version has a changelog entry: what changed, who approved, when, and migration notes if any. + +### Backward compatibility window + +When a Tier 3 or Tier 4 change ships, set a deprecation window: + +- **Tier 3:** 90 days. Old patterns acceptable in production, new patterns required for new work. +- **Tier 4:** 6-12 months depending on production cycle (print catalogs, manufactured goods, regulatory deliverables may need longer). + +Document deprecated patterns with a clear "Replaced by [new pattern], deprecated as of [date], removal date [date]" note. + +--- + +## Communication + +When the guide changes, people need to know. + +### Channels + +- **Brand channel:** standing channel for all updates, requests, questions. +- **Changelog page in the guide:** running list of versioned changes. +- **Quarterly digest email:** roundup of the past quarter's changes, plus the audit summary. +- **Annual review post:** the year's biggest changes, the audit findings, the next year's priorities. + +### When to push, when to publish + +- **Push** (announce, require attention) for Tier 3 and Tier 4 changes. +- **Publish** (update the guide and the changelog, no broadcast) for Tier 1 and Tier 2. + +--- + +## Adoption health metrics + +The guide is healthy when teams use it. Track: + +| Metric | Healthy | Warning | Failing | +|---|---|---|---| +| Average page views per month | Steady or growing | Declining | Near-zero | +| Change requests per quarter | 5-15 | <3 | 0 (or 50+) | +| Audit compliance score (Tier 3+) | >90% | 75-90% | <75% | +| Percent of new launches that referenced the guide pre-launch | >80% | 50-80% | <50% | +| Time to ship a clarification | <1 week | 1-4 weeks | >4 weeks | + +If multiple metrics are failing simultaneously, the guide needs a refresh, not just maintenance. + +--- + +## When to retire and rewrite + +Sometimes maintenance is not enough. Signs the guide needs a rewrite: + +- The brand has shifted enough that >30% of the guide no longer applies +- The audience or category has shifted enough that the brand position is dated +- A new owner cannot make sense of the structure +- The guide reads as if it was written for a different company +- Compliance has fallen below 60% across multiple audits + +Rewriting is not a maintenance task. It is a separate brand project. The maintenance playbook ends when the rewrite begins. + +--- + +## Sign-off + +Maintenance plan accepted by: + +- Brand owner: [Name, date] +- Council members: [Names, date] +- Executive sponsor: [Name, date] + +Next quarterly review: [Date] diff --git a/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md b/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md new file mode 100644 index 0000000..a55b540 --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md @@ -0,0 +1,407 @@ +# [Brand Name] Style Guide + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Maintained by:** [Team or person] +**Format:** This document is canonical. Other formats (PDF, web page, Figma) are views of this document. + +--- + +## How to use this guide + +[1 to 2 paragraphs explaining what the guide is for, who it serves, and where to go with questions.] + +**Quick links:** +- [Logo files](#logo-files) +- [Color values](#color-values) +- [Typography](#typography) +- [Voice cheat sheet](#voice) +- [Dos and don'ts](#dos-and-donts) + +--- + +## 1. Story + +### Origin +[1 to 3 paragraphs. Why this brand exists. The problem it solves. The moment it began.] + +### Mission +[One sentence. What we are trying to do in the world.] + +### Vision +[One sentence. The future we are pulling toward.] + +### Values + +We hold [N] values. + +**[Value 1]** +[What it means in practice. 2 to 3 sentences. Include a behavioral example.] + +**[Value 2]** +[Same structure.] + +**[Value 3]** +[Same structure.] + +### Positioning + +[The positioning statement. One paragraph. What we offer, to whom, and what makes us different.] + +### Audience + +**Primary:** [Who, with specificity] + +**Secondary:** [Who, briefly] + +**Anti-personas:** [Who we are not for] + +### What we are not + +- [Thing we explicitly reject] +- [Thing we explicitly reject] +- [Thing we explicitly reject] + +--- + +## 2. Logo system + +### Primary logo + +[Image of primary logo] + +[Description: what it is, what it represents, when to use it.] + +### Wordmark + +[Image of wordmark] + +[Description and usage.] + +### Symbol / glyph + +[Image of glyph] + +[Description and usage.] + +### Lockup variations + +[Images of horizontal, stacked, square variants.] + +### Construction + +[Image showing construction grid, proportions, key relationships.] + +### Clear space + +[Image showing minimum clear space around the logo.] + +The logo requires minimum clear space equal to [X] on all sides. + +### Minimum sizes + +| Format | Minimum size | +|---|---| +| Digital primary | [Xpx] wide | +| Print primary | [Xmm] wide | +| Favicon | [Xpx] | +| Mobile | [Xpx] | + +### Color treatments + +**Allowed:** +- Full color on white +- Full color on light backgrounds (with [contrast rule]) +- Single color on light backgrounds +- White (knockout) on dark backgrounds +- Single color black + +**Forbidden:** +- [Specific forbidden treatment with example image] +- [Specific forbidden treatment with example image] + +### Logo files + +| File | Use case | Path | +|---|---|---| +| logo-primary.svg | Web primary | /brand/logo/primary.svg | +| logo-wordmark.svg | Tight horizontal | /brand/logo/wordmark.svg | +| logo-symbol.svg | App icon, favicon | /brand/logo/symbol.svg | +| logo-monogram.svg | Tiny contexts | /brand/logo/monogram.svg | +| [more files] | | | + +--- + +## 3. Color + +### Primary palette + +| Name | Hex | RGB | Use | +|---|---|---|---| +| [Name] | #XXXXXX | (R,G,B) | [Use case] | +| [Name] | #XXXXXX | (R,G,B) | [Use case] | + +### Secondary palette + +[Same table structure] + +### Neutrals + +[Same table structure] + +### Semantic colors + +| Name | Hex | Use | +|---|---|---| +| Success | #XXXXXX | Positive states, confirmations | +| Warning | #XXXXXX | Caution, attention needed | +| Error | #XXXXXX | Errors, destructive actions | +| Info | #XXXXXX | Neutral information | + +### Dark mode variants + +| Color | Light mode | Dark mode | +|---|---|---| +| Brand primary | #XXXXXX | #XXXXXX | +| Body text | #XXXXXX | #XXXXXX | +| Surface | #FFFFFF | #XXXXXX | + +### Contrast ratios + +[For each meaningful pairing, document the ratio and pass/fail.] + +| Pairing | Ratio | WCAG | +|---|---|---| +| Brand primary on white | X.X:1 | Pass AA / Pass AAA | +| Body text on white | X.X:1 | Pass AA | + +### Allowed pairings + +[List or visual showing which colors work together.] + +### Forbidden pairings + +[List or visual showing combinations not to use.] + +--- + +## 4. Typography + +### Display typeface + +**[Typeface name]** + +[Sample at large size] + +Used for: [Headlines, hero copy, brand moments] + +Weights used: [list] + +### Body typeface + +**[Typeface name]** + +[Sample at body size] + +Used for: [Long-form reading, paragraphs] + +Weights used: [list] + +### Monospace (if applicable) + +**[Typeface name]** + +Used for: [Code, technical data] + +### Type scale + +| Step | Size | Weight | Line height | Letter spacing | Use | +|---|---|---|---|---|---| +| Display 1 | 64 | 700 | 1.0 | -0.02em | Hero headlines | +| Display 2 | 48 | 700 | 1.05 | -0.01em | Section headers | +| H1 | 36 | 700 | 1.1 | 0 | Page titles | +| H2 | 28 | 600 | 1.2 | 0 | Section titles | +| H3 | 22 | 600 | 1.3 | 0 | Sub-sections | +| Body Large | 18 | 400 | 1.5 | 0 | Lead paragraphs | +| Body | 16 | 400 | 1.6 | 0 | Default body | +| Small | 14 | 400 | 1.5 | 0 | Captions, metadata | +| Caption | 12 | 400 | 1.4 | 0.01em | Footnotes, labels | + +### Web fallback stack + +``` +font-family: '[Brand display]', '[OS fallback 1]', '[OS fallback 2]', sans-serif; +``` + +### Open-source alternatives + +For contexts where the licensed brand fonts are impractical (third-party tools, embeds), use: + +- Display alternative: [Open-source typeface name] +- Body alternative: [Open-source typeface name] + +### Forbidden treatments + +- [No fake italics] +- [No fake bold] +- [No all-caps body text] +- [Other forbidden treatments] + +--- + +## 5. Imagery and illustration + +### Photography + +**Subject matter:** [What we photograph] + +**Style:** [Composition, lighting, color treatment] + +**What we reject:** [Stock photo aesthetics, specific cliches] + +**Examples:** +[Include 4 to 6 example images] + +### Illustration + +**Style:** [Description] + +**Color use:** [Rules] + +**Examples:** +[Include 4 to 6 example illustrations] + +### Iconography + +**Style:** [Filled / outline / mixed] + +**Grid:** [Base grid size] + +**Stroke weight:** [Specification] + +**Set:** +[Include the icon set or rules for adding new icons] + +--- + +## 6. Voice and tone + +### Voice attributes + +We sound: [adjective], [adjective], [adjective], [adjective], [adjective]. + +We do not sound: [opposite], [opposite], [opposite], [opposite], [opposite]. + +| We are | We are NOT | +|---|---| +| [Adjective] | [What it could tip into] | +| [Adjective] | [What it could tip into] | +| [Adjective] | [What it could tip into] | + +### Tone shifts + +| Context | Tone | +|---|---| +| Onboarding | [Description] | +| Error states | [Description] | +| Success states | [Description] | +| Marketing | [Description] | +| Support | [Description] | +| Legal | [Description] | + +### Vocabulary preferences + +**Use:** [Words and phrases that fit] + +**Avoid:** [Words and phrases that do not fit] + +### Sample copy + +**Bad (off-voice):** +> [Example] + +**Good (on-voice):** +> [Example] + +--- + +## 7. Applications + +### Web + +[Show 2 to 3 example layouts: homepage, product page, blog template] + +### Email + +[Show template, signature, transactional examples] + +### Social + +[Show post templates, profile imagery, story formats] + +### Print (if applicable) + +[Show business cards, letterhead, print examples] + +### Packaging (if applicable) + +[Show packaging examples] + +### Internal documents + +[Show slide template, report template, proposal template] + +--- + +## 8. Dos and don'ts + +### Logo + +| Do | Don't | +|---|---| +| [Visual example with caption] | [Visual example with caption] | +| | | + +### Color + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Type + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Composition + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Voice + +| Do | Don't | +|---|---| +| "[Example phrase]" | "[Example phrase]" | +| | | + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial publication | + +--- + +## Contact + +Questions or requests for clarification: [contact info] + +To suggest changes: [process] diff --git a/dist/pi/.agents/skills/brand-voice/SKILL.md b/dist/pi/.agents/skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b5c55f1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/SKILL.md @@ -0,0 +1,193 @@ +--- +name: brand-voice +description: "Develop or document a complete brand voice and tone system covering voice attributes, tone shifts by context, vocabulary preferences, grammar rules, and copy examples. Use this skill whenever the user wants to define how a brand sounds, write a voice and tone document, audit existing copy for voice consistency, train a team or AI assistant on brand voice, or refine the personality of brand writing. Triggers on brand voice, voice and tone, tone of voice, writing voice, brand personality, copy voice, voice document, voice guidelines, how should we write, voice training, voice audit. Also triggers when the user has copy that 'feels off' and the underlying issue is voice, even if not stated explicitly." +category: brand +catalog_summary: "Voice attributes, tone shifts, vocabulary, paired-example library" +display_order: 4 +--- + +# Brand Voice + +Define how a brand sounds in writing. Document it in a way that anyone (writer, designer, founder, AI assistant) can apply it consistently. + +This skill produces a standalone voice document that can either live in the brand style guide or feed into it. + +--- + +## When to use + +- Defining brand voice for the first time +- Auditing existing copy for voice consistency +- Training a team, freelancer, or AI assistant on the brand voice +- Refining a voice that exists but is inconsistent across applications +- Adapting voice when a brand evolves (new audience, new positioning) + +## When NOT to use + +- Writing specific copy (use `content-and-copy`) +- Brand visual identity work (use `brand-identity`) +- Documenting a complete brand system (use `brand-style-guide`, which incorporates voice) +- Initial brand exploration (use `brand-ideation`) + +--- + +## Required inputs + +- The brand and its positioning +- The audience and what they need to hear +- 5 to 10 examples of existing brand writing (if any) +- 3 to 5 reference brands whose voice resonates with where this brand should go +- Any voice attributes already specified in the brief + +--- + +## The framework: 4 layers + +Voice has four layers, stacked. Each layer constrains the one below it. + +### Layer 1: Voice attributes + +The constants. The personality traits that define how the brand sounds across every context. + +Pick 3 to 5 attributes. Pair each with what it is NOT (the failure mode if overdone). + +Common attribute pairings (NOT a menu - generate your own): + +- Confident, not arrogant +- Direct, not blunt +- Warm, not saccharine +- Witty, not sarcastic +- Smart, not academic +- Honest, not harsh +- Playful, not silly +- Practical, not boring +- Bold, not loud +- Curious, not unfocused + +The "not" half is what saves writers from overshooting. "Confident" alone produces swagger. "Confident, not arrogant" tells writers where the line is. + +### Layer 2: Tone shifts + +Voice is constant. Tone adapts to context. + +Map the major contexts the brand writes in. For each, document how voice expresses differently. + +Common contexts: + +| Context | Tone shift | +|---|---| +| Onboarding | Warmer, more enthusiastic, slightly slower pace | +| Hero / marketing | Confident, signature voice fully on | +| Product copy / UX | Direct, helpful, brief | +| Error messages | Calm, matter-of-fact, no apology theater | +| Success states | Brief celebration, redirect to next action | +| Empty states | Helpful, slightly playful, suggest action | +| 404 / not found | Self-aware, light, points the way home | +| Account deletion / cancellation | Quiet, respectful, no jokes | +| Pricing | Direct, transparent, confidence-inspiring | +| Legal / TOS | Plain language version sits next to the legal version | +| Support / help center | Patient, thorough, no condescension | +| Crisis communication | Calm, factual, accountable | +| Product announcements | Excited but not breathless | +| Email subject lines | Specific, never click-bait | + +Voice stays consistent across all of these. Tone is what shifts. + +### Layer 3: Vocabulary and grammar + +The granular dial settings. + +**Vocabulary preferences:** + +- Words and phrases the brand uses +- Words and phrases the brand avoids +- Words the brand has redefined (if any) - e.g., a SaaS product calling its features "huddles" instead of "meetings" +- Industry jargon: keep it (signals expertise) or strip it (signals approachability) +- Sentence-opening preferences (some brands lean on imperatives, some on questions, some on statements) + +**Grammar and style:** + +- Contractions (use them = casual, avoid them = formal) +- Sentence length default (short = punchy, medium = considered, long = literary) +- Punctuation marks favored or avoided (em dash is famously polarizing) +- Pronouns ("we" / "you" / "I") +- Capitalization style (title case, sentence case, all-lowercase deliberate) +- Number formatting (spell out under ten, or always digits) +- Oxford comma (use or skip) +- Active vs passive voice (most brands prefer active) + +### Layer 4: Examples and patterns + +Voice is taught through examples, not rules. Build a library. + +For each major content type, show: + +- Bad example (off-voice) +- Good example (on-voice) +- Brief note on what changed + +Common content types to cover: + +- Headline +- Subheadline +- Hero CTA +- Feature description +- Testimonial intro +- Email subject line +- Email opening +- Push notification +- Error message +- Success message +- About page paragraph +- Social post +- Sales page paragraph + +Aim for 15 to 25 paired examples. This is the most-used part of the voice doc in practice. + +--- + +## Workflow + +1. **Audit existing copy** if it exists. Identify what is on-brand, what is off, what patterns recur. +2. **Layer 1: Voice attributes.** Generate 5 to 8 candidates with "we are X, not Y" framing. Pick 3 to 5. +3. **Layer 2: Tone shifts.** List 8 to 15 contexts the brand writes in. Note the tone shift for each. +4. **Layer 3: Vocabulary and grammar.** Define preferences. Skip default rules unless they actually distinguish the brand. +5. **Layer 4: Examples.** Build the paired-example library. 15 to 25 minimum. +6. **Stress-test.** Pick a fresh writing brief and apply the voice doc. Does it produce on-voice copy? If not, the doc is incomplete. +7. **Document.** Use the template in [`references/voice-document-template.md`](references/voice-document-template.md). +8. **Distribute.** Voice docs only work if they get used. Make the doc easy to reference inline (link to it from CMS templates, brief templates, AI assistant prompts). + +--- + +## Failure patterns + +- **Generic attributes ("friendly, professional, approachable").** Every brand says this. Means nothing. Pick attributes that genuinely distinguish. +- **No "we are NOT" pairings.** Without the rejection, attributes drift toward extremes. +- **Voice doc with no examples.** Rules without examples cannot be applied. +- **Examples that are obviously bad and obviously good.** Real voice work shows nuanced shifts, not cartoonish before/after. +- **Skipping tone shifts.** Treating voice as one-size-fits-all leads to a brand that sounds wrong in error states or legal contexts. +- **Documenting aspirational voice.** If the brand does not actually sound this way today and has no plan to shift, the doc is fiction. +- **Voice without distribution.** A perfect doc that no one references is worth nothing. + +--- + +## Output format + +Default output is a markdown document at `voice.md` in the brand folder. Sections: + +1. Voice attributes (with we-are-not pairings) +2. Tone shifts by context +3. Vocabulary preferences +4. Grammar and style rules +5. Paired examples library (the most-used section) +6. Anti-patterns (specific phrases or constructions to avoid) +7. References (the brands and writers we are inspired by) + +This doc can stand alone or feed into `brand-style-guide`. + +--- + +## Reference files + +- [`references/voice-document-template.md`](references/voice-document-template.md) - Fillable template. +- [`references/voice-frameworks.md`](references/voice-frameworks.md) - Detailed walkthrough of the Nielsen Norman 4 dimensions, Jung archetypes, and the "we are X not Y" approach. diff --git a/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md b/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md new file mode 100644 index 0000000..b0362e1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md @@ -0,0 +1,324 @@ +# [Brand Name] Voice and Tone + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Maintained by:** [Team or person] + +--- + +## How to use this doc + +[1 to 2 paragraphs. Who this is for, when to reference it, where to ask questions.] + +For most writers, the section that gets used most is the **paired examples library** at the end. When unsure how to write something, find the closest example and pattern-match. + +--- + +## Voice attributes + +We sound: + +- **[Adjective 1]**, not [opposite] +- **[Adjective 2]**, not [opposite] +- **[Adjective 3]**, not [opposite] +- **[Adjective 4]**, not [opposite] +- **[Adjective 5]**, not [opposite] + +### What each attribute means + +**[Adjective 1]** +[2 to 3 sentences. What this looks like in practice. Include one specific example phrase.] +Failure mode: when [Adjective 1] tips into [opposite], we sound [bad outcome]. + +**[Adjective 2]** +[Same structure.] + +**[Adjective 3]** +[Same structure.] + +**[Adjective 4]** +[Same structure.] + +**[Adjective 5]** +[Same structure.] + +--- + +## Tone shifts by context + +Voice stays constant. Tone adjusts based on what the user is doing and feeling. + +| Context | Tone | +|---|---| +| Hero / marketing | [How tone shifts] | +| Onboarding | [How tone shifts] | +| Product copy / UX labels | [How tone shifts] | +| Empty states | [How tone shifts] | +| Error messages | [How tone shifts] | +| Success states | [How tone shifts] | +| 404 / not found | [How tone shifts] | +| Account deletion / cancellation | [How tone shifts] | +| Pricing | [How tone shifts] | +| Legal / TOS | [How tone shifts] | +| Support / help center | [How tone shifts] | +| Crisis communication | [How tone shifts] | +| Email subject lines | [How tone shifts] | +| Social posts | [How tone shifts] | + +--- + +## Vocabulary preferences + +### Words and phrases we use + +[Bulleted list of vocabulary that fits the brand. Be specific.] + +- [Word or phrase] +- [Word or phrase] +- [Word or phrase] + +### Words and phrases we avoid + +[Bulleted list of vocabulary that does not fit. Often these are category cliches or fluff words.] + +- [Word or phrase] - [optional note on why] +- [Word or phrase] +- [Word or phrase] + +### Redefined words (if any) + +If the brand uses standard words in non-standard ways, document here. + +| Standard term | We say | Why | +|---|---|---| +| [Standard] | [Our term] | [Reasoning] | + +### Industry jargon + +We [keep / strip] industry jargon. [1 to 2 sentences explaining the call.] + +--- + +## Grammar and style + +| Decision | Our standard | +|---|---| +| Contractions | [Use / avoid] | +| Default sentence length | [Short / medium / long] | +| Em dashes | [Use / avoid] | +| Oxford comma | [Yes / no] | +| Pronouns | [we / you / I patterns] | +| Capitalization (headlines) | [Title / sentence / lowercase] | +| Numbers under 10 | [Spell out / digits] | +| Active vs passive | [Active default] | +| Hashtags (in social) | [In body / in comment / not used] | +| Exclamation points | [Frequency rule] | +| Emoji | [Use / avoid / context-specific] | + +--- + +## Paired examples library + +The most-used part of this doc. When in doubt, find the closest example and pattern-match. + +### Headlines + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +[Brief note on what changed and why.] + +--- + +### Subheadlines + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Hero CTA + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Feature description + +**Off-voice:** +> [Bad example, 2 to 3 sentences] + +**On-voice:** +> [Good example, 2 to 3 sentences] + +--- + +### Testimonial intro + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Email subject line + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Email opening + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Push notification + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Error message + +**Off-voice:** +> "An error has occurred. Please try again later." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### Success message + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Empty state + +**Off-voice:** +> "No items found." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### About page paragraph + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Social post + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Sales page paragraph + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### 404 page + +**Off-voice:** +> "404. Page not found." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### Cancellation flow copy + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +## Anti-patterns + +Specific phrases or constructions that NEVER appear in our writing: + +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] + +--- + +## References + +Brands and writers whose voice we admire and learn from: + +- **[Brand or writer]** - [What we learn from them] +- **[Brand or writer]** - [What we learn from them] +- **[Brand or writer]** - [What we learn from them] + +We are not copying these voices. We are calibrating against them. + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial publication | + +--- + +## How to evolve this doc + +[1 paragraph on how the team proposes voice updates, who reviews, who approves.] + +Voice should be reviewed: +- Annually as a minimum +- After any major audience shift +- After any major positioning change +- When it consistently fails the "stress test" (writing produced from this doc no longer feels right) diff --git a/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md b/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md new file mode 100644 index 0000000..8d57718 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md @@ -0,0 +1,188 @@ +# Voice Frameworks + +Three established frameworks for thinking about brand voice. Each emphasizes a different layer. Mix and match. None is "right." Each is a tool. + +--- + +## Framework 1: The "We are X, not Y" approach + +The most pragmatic framework. Start here if you have not done voice work before. + +### How it works + +Pick 3 to 5 voice attributes. For each, name what the attribute is NOT. The pairing is the framework. + +``` +We are confident, not arrogant. +We are direct, not blunt. +We are warm, not saccharine. +We are smart, not academic. +``` + +### Why the "not Y" matters + +Single-word attributes are aspirational. They float. Without a counterweight, writers (and AI assistants) overshoot. + +- "Confident" alone = swagger, bravado, dismissiveness +- "Direct" alone = curtness, coldness, rudeness +- "Warm" alone = mushy, performative, over-friendly +- "Smart" alone = jargon-heavy, exclusionary + +Each "not Y" tells the writer where the line is. It is the guardrail. + +### Picking attributes + +Avoid generic words every brand claims. "Friendly," "professional," "approachable," "trustworthy," "innovative" are filler. They do not distinguish. + +Better attributes are specific enough to make some other brand a bad fit. If you can imagine your competitor saying the same word, the word is too generic. + +A good list: +- Distinctive (no other brand in your category would put it the same way) +- Honest (you actually sound this way, or are committed to) +- Useful (writers can apply it to a real piece of copy) +- Limited (3 to 5 attributes; 8+ becomes unworkable) + +### Stress test + +Take a recent piece of copy. Score it 1 to 5 against each attribute. If it scores below 3 on any, the copy is off-voice. If it scores 5 across the board, the attributes might be too generous. + +Apply the test to a competitor's copy. If their copy scores high on your attributes, the attributes are not distinctive enough. + +--- + +## Framework 2: The Nielsen Norman 4 dimensions + +Nielsen Norman Group introduced a model that treats voice as four sliders rather than a list of adjectives. + +### The 4 sliders + +**1. Funny vs serious** +Where on the spectrum from playful to earnest does the brand sit? + +- Far funny: jokes are signature, even in support content +- Mid: occasional wit, mostly straightforward +- Far serious: humor is rare and only when context invites it + +**2. Formal vs casual** +How structured and decorous is the writing? + +- Far formal: full sentences, correct grammar, no contractions, professional register +- Mid: standard professional, occasional contractions +- Far casual: contractions, fragments, conversational rhythms, slang where appropriate + +**3. Respectful vs irreverent** +Does the brand treat its audience and category with deference, or does it poke fun? + +- Far respectful: customers are addressed with care, category is treated with seriousness +- Mid: respectful default, willing to be playful at edges +- Far irreverent: category cliches get punctured, the brand is willing to mock conventions (its own and competitors') + +**4. Matter-of-fact vs enthusiastic** +What is the energy level? + +- Far matter-of-fact: calm, even, measured +- Mid: warm but not effusive +- Far enthusiastic: animated, expressive, energetic + +### How to use + +Plot the brand on each of the four. The position is the brand's voice signature. + +Example: +- Funny vs serious: 30 (mostly serious, occasional dryness) +- Formal vs casual: 70 (mostly casual, contractions standard) +- Respectful vs irreverent: 40 (respectful default, willing to be playful) +- Matter-of-fact vs enthusiastic: 50 (warm but measured) + +This produces a recognizable signature distinct from competitors plotted on the same axes. + +### Why this framework + +It forces choices. Adjective lists let you claim "warm AND professional AND witty AND smart." The dimensions force you to commit to a position, which is what voice actually is. + +### When to use it + +Best as a complement to the "We are X, not Y" approach. Use the dimensions to plot the brand. Use the attributes to give writers actionable language. + +--- + +## Framework 3: Brand archetypes (the Jung-derived model) + +A model from depth psychology, applied to brands by Margaret Mark and Carol Pearson. Twelve archetypes, each with a recognizable voice pattern. + +### The 12 archetypes + +| Archetype | Voice signature | Example brands (illustrative, not endorsements) | +|---|---|---| +| Innocent | Pure, optimistic, simple | Wholesome consumer brands, family-oriented | +| Sage | Wise, considered, knowledgeable | Educational publishers, research institutions | +| Explorer | Adventurous, free, restless | Outdoor brands, travel platforms | +| Outlaw | Rebellious, defiant, anti-establishment | Disruptors, challenger brands | +| Magician | Visionary, transformative, mystical | Tech that "changes everything" | +| Hero | Brave, decisive, achievement-oriented | Athletic brands, ambitious tools | +| Lover | Sensual, intimate, devoted | Premium consumer goods, luxury | +| Jester | Playful, irreverent, lighthearted | Entertainment, fast food, fun-first | +| Everyman | Down-to-earth, relatable, fair | Mass market, "for everyone" | +| Caregiver | Compassionate, generous, protective | Healthcare, family services | +| Ruler | Authoritative, sophisticated, in-control | Premium brands, enterprise | +| Creator | Imaginative, expressive, original | Creative tools, artistic brands | + +### How to use + +Pick a primary archetype. Optionally a secondary. The combination is the voice signature. + +A brand might be primary Sage with secondary Caregiver. That voice is wise + protective. It would write differently than a Sage + Outlaw (wise + defiant). + +### Strengths + +- Forces a clear voice character rather than a list of adjectives +- The archetypes are recognizable, which helps writers visualize the voice +- Distinguishes brands that might otherwise sound similar + +### Weaknesses + +- Some archetypes are dated or culturally specific +- "Pick one" is harder than it sounds; brands often span 2 or 3 +- Easy to pick aspirational archetypes the brand does not actually live + +### When to use it + +When the brand has a distinctive personality you want to crystallize. Less useful for utilitarian or category-defining brands. + +--- + +## Combining frameworks + +The three frameworks are not mutually exclusive. They emphasize different layers. + +A useful combination: + +1. **Archetype** for the high-level character +2. **NN/g dimensions** for the calibration +3. **"We are X, not Y" attributes** for the daily writing guardrails + +Example for a fictional brand: + +- **Archetype:** Sage (primary) + Everyman (secondary) +- **Dimensions:** 30 funny / 60 casual / 50 respectful / 40 enthusiastic +- **Attributes:** + - Knowledgeable, not academic + - Plain-spoken, not basic + - Honest, not harsh + - Patient, not condescending + +Each layer adds resolution. The archetype gives character. The dimensions give calibration. The attributes give writers the daily tool. + +--- + +## Choosing a framework + +If you have done voice work before and know what you want, the "We are X, not Y" approach alone is enough. + +If the brand voice is undefined and you need to start from zero, begin with archetypes (high-level character), move to dimensions (calibration), then derive attributes (daily guardrails). + +If voice work has been done but is too vague, the dimensions framework is the best clarifier. + +If voice has been documented but writers do not know how to apply it, the attributes framework is the missing piece. + +The frameworks are tools. The output of voice work is consistent writing across the brand. If the writing is consistent, the framework worked. If it is not, no framework is the right one yet. diff --git a/dist/pi/.agents/skills/calculator-design/SKILL.md b/dist/pi/.agents/skills/calculator-design/SKILL.md new file mode 100644 index 0000000..a9be8c1 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/SKILL.md @@ -0,0 +1,296 @@ +--- +name: calculator-design +description: "Designing interactive calculators (ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments) that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. Honest about vanity-calculator (no real value), lead-trap (hides the answer behind email), and transparent-decision-tool (gives the result and earns the email through tiered value) patterns. Triggers on calculator, ROI calculator, pricing estimator, savings calculator, custom calculator, interactive tool, decision tool, financial calculator. Also triggers when an audience needs a calculation-driven lead magnet, when a vanity calculator is producing leads but no qualified ones, or when a calculator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive calculators that deliver decision-support value while qualifying leads. Distinguishes vanity-calculator (no real value) from lead-trap (hides answer behind email) from transparent-decision-tool (gives genuine value, captures leads honestly)" +display_order: 2 +--- + +# Calculator Design + +A senior growth practitioner's playbook for designing interactive calculators that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments. The discipline of building a tool the audience actually trusts. + +Most calculators on the web are bait. Random multipliers behind official-looking math; an "Industry Average" number that does not cite a source; the result hidden behind a contact-sales form. The calculator captures emails because the format implies calculation; the leads are unqualified because the calculator did not actually help anyone decide anything. + +The calculators that work as compounding assets do something different. They give the audience a result they can defend to a stakeholder. They show the methodology so the result is interrogatable. They capture leads through value (a PDF report, a save-and-compare account, a custom analysis) rather than through manipulation. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the calculator-specific methodology (calculation transparency, tiered value, methodology disclosure) lives here. + +The voice is the senior growth practitioner who has watched calculators earn long-term credibility and watched them burn it within weeks of launch. Practical, opinionated about transparency, willing to say when a calculator is the wrong investment for the goal. + +When to use this skill: scoping a calculator for the first time, auditing a calculator that converts but does not qualify, designing the methodology disclosure that earns audience trust, or deciding which features warrant the email gate. + +--- + +## What this skill covers + +This skill spans calculator design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology (when to invest in any magnet, format selection, audience-fit, follow-up sequence). Calculators are one specific lead-magnet type. +- **`calculator-design` (this skill)** is calculator-specific methodology (calculation transparency, tiered value, methodology disclosure, input design). +- `quiz-and-assessment-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `landing-page-copy` is the calculator landing page (downstream of calculator design). +- `pm-spec-writing` is writing the spec for engineers building the calculator. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: growth marketers, product marketers, marketing teams building lead-magnet calculators, agencies running growth-tooling work for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the calculator (handed off via `pm-spec-writing`). + +--- + +## The calculator decision: when calculators earn investment + +Before designing the calculator, decide whether a calculator is the right tool for the audience and the goal. + +**Calculators earn investment when:** + +- The audience faces a specific calculation as part of a decision. ROI on a software purchase, savings from a refinance, monthly cost of an expense, sizing for a service tier. Without a real calculation in the audience's actual workflow, the calculator becomes a vanity tool. +- The calculation is non-trivial. Multiplying two numbers does not need a calculator; calibrating across 5-10 inputs with branching logic does. +- The brand has methodology authority. The calculator's output has to be defensible. Brands without methodology authority (or unwilling to disclose methodology) often produce calculators audiences do not trust. +- The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation); the sequence has to use that signal. + +**Calculators do NOT earn investment when:** + +- The audience does not actually run this calculation. A calculator solving a problem the audience does not have produces low usage. +- The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" does not earn its build. +- The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend, the calculator becomes a vanity tool by necessity. +- A simpler magnet would serve the same audience and goal. Templates and checklists are cheaper to build and maintain than calculators; choose the calculator only when the calculation is the value. + +The decision is not "should we have a calculator"; it is "is the calculator the right next investment for this specific audience and goal." + +Detail in [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md). + +--- + +## Vanity-calculator vs lead-trap vs transparent-decision-tool + +The keystone framing. + +**Vanity-calculator.** Inputs and outputs that do not actually help anyone decide anything. "Calculate your marketing ROI" with random multipliers; "estimate your savings" with no defensible methodology. Looks impressive in a screenshot; helps nothing in a real decision. Cost: leads downloaded the result, found it useless, and remember the brand as the source of the useless tool. + +**Lead-trap.** Genuine calculation logic but the result is hidden behind an email gate. The user inputs 8 fields, hits "Calculate," and sees "enter your email to see your result." Manipulative; reader resents the friction; conversion drops below baseline because the audience can tell when the gate is bait rather than value-add. + +**Transparent-decision-tool.** Genuine calculation that gives the result immediately. Email gate for advanced features (PDF report, custom analysis, save-and-compare across scenarios) where the additional value justifies the ask. The reader gets the answer they came for; the brand gets the email through demonstrated generosity. + +The litmus test. After running the calculator, can a stranger in the target audience defend the result to a stakeholder? Can they cite the methodology behind the number? If yes, the calculator is a transparent-decision-tool. If they got a number with no defensible source, the calculator is vanity. If they could not see the result without giving an email, the calculator is a lead-trap. + +--- + +## Input design + +The calculator's inputs are the audience's first interaction. Bad input design loses the user before the calculation runs. + +**The principle.** Each input should be necessary for the calculation, easy for the user to provide, and respectful of the user's time. + +**Necessary.** If an input does not affect the output meaningfully, do not ask for it. Calculators that ask 18 inputs but only use 5 in the actual math signal that the form is collecting data for sales rather than for the calculation. The audience can tell. + +**Easy to provide.** Use defaults from honest assumptions. "Average company size" preset to a reasonable industry baseline. "Typical conversion rate" preset to a defensible number. Defaults reduce the cognitive load and let the user adjust where their context differs. + +**Respectful of time.** Group related inputs visually. Show only the fields the user is currently working through (progressive disclosure where it helps). Indicate progress so the user knows how many steps remain. + +**Input types.** + +- Numeric (revenue, customer count, monthly cost). The most common. Often warrants tooltip explaining what the number represents. +- Slider (percentage estimates, conversion rates). Good for ranges where exact values are not knowable. +- Dropdown (industry, company size, region). Good for predefined categories. +- Toggle (feature on/off, scenario A vs B). Good for binary choices. +- Free text (only when the value is genuinely user-specific and cannot be calculated). Use sparingly; free text is friction. + +Detail in [`references/input-design-patterns.md`](references/input-design-patterns.md). + +--- + +## Calculation logic transparency + +The defensibility of the result is the calculator's credibility currency. + +**The principle.** The audience should be able to inspect the methodology. Either the calculation is shown openly, or a methodology link explains it, or the team is willing to share the spec on request. + +**Methodology disclosure options.** + +- **Inline formulas.** "Your savings = (current cost x 12) - (our cost x 12) + implementation savings of $X." Explicit and verifiable. +- **Methodology page.** A link from the calculator to a page explaining the assumptions, sources, and formulas. The audience can read if they care; defaults are good for those who do not. +- **Source citations.** When inputs come from external benchmarks ("Industry Average: 14 percent"), cite the source. Uncited benchmarks erode trust. +- **Assumption list.** A list of the calculator's assumptions, plain-language. "We assume you are comparing month-over-month after a 3-month implementation period." + +**The vanity-calculator failure.** Assumptions hidden, sources missing, formulas opaque. The audience uses the tool, gets a number, and cannot defend it. The brand is invisible in their next conversation about the decision because the calculator did not earn the credibility. + +**The transparent-tool win.** Assumptions visible, sources cited, formulas inspectable. The audience uses the tool, gets a number, and can defend it. The brand is in the conversation because the audience cites the calculator as their source. + +Detail in [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md). + +--- + +## Result presentation + +The result is the calculator's product. Bad result presentation wastes the calculation work. + +**The principle.** The result should be specific, contextualized, and actionable. + +**Specific.** A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." + +**Contextualized.** Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." The context makes the number interpretable. + +**Actionable.** What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step is the calculator's bridge from result to action. + +**Result-presentation patterns.** + +- **Headline number.** The single most important output, large and prominent. +- **Breakdown.** Sub-results that explain how the headline number was calculated. +- **Visualization.** Bar chart, comparison table, or simple graphic that helps the user see the relationship. +- **Scenario comparison.** "Your current state vs the optimized state." Useful when the calculator is illustrating a delta. + +**Avoid.** + +- Burying the result. The result should be visible immediately, not after a scroll. +- Result followed by 5 paragraphs of marketing. The result is what the user came for; marketing belongs after, not before. +- Result that requires re-entering all inputs to view. Persist inputs and results within the session. + +Detail in [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md). + +--- + +## Email-capture decision + +What to gate, what to give freely. + +**The principle.** Give the audience the result they came for. Gate the additional value (PDF report, custom analysis, save-and-compare, saved scenarios across visits). + +**What to give freely.** + +- The headline result. +- The breakdown of how the result was calculated. +- A visualization of the result. +- The methodology disclosure. + +**What to gate (with email or account creation).** + +- A formatted PDF report the user can share or save. +- A saved scenario the user can revisit and compare against alternatives. +- A custom analysis (a deeper version of the calculation, often delivered later). +- Email-based notifications when assumptions change or new benchmarks emerge. + +**The lead-trap failure.** The headline result is gated. The user inputs 8 fields, hits Calculate, sees "enter your email to see your result." Conversion drops because the audience perceives the manipulation. The lead-trap pattern is short-term thinking. + +**The transparent-tool win.** The result is free; the additional value is gated. Conversion is honest; lead quality is high because the lead opted in for the additional value, which signals real interest. + +Detail in [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md). + +--- + +## Tiered-value structures + +The architecture that lets calculators capture leads honestly. + +**The principle.** The calculator delivers tiered value: free immediate result + gated advanced features. + +**Tier 1 (free, no gate):** the headline result, the breakdown, the methodology, basic visualization. + +**Tier 2 (email-gated):** a formatted PDF, a saved scenario, an emailed copy of the result. + +**Tier 3 (account or sign-up gated):** save-and-compare across multiple scenarios over time, advanced analysis, integration with the brand's product or service. + +**The tier-design discipline.** + +- Each tier should add real value over the previous. If Tier 2 is just "the same result in a PDF," the tier does not justify the email ask. +- The gate at each tier should be matched to the value. Email for Tier 2; account creation only for Tier 3. +- The tier transitions should feel natural. The user gets the free result, sees the additional value visibly, and chooses whether to opt in for it. + +**Worked example.** + +A B2B SaaS pricing calculator. + +- Tier 1 (free): the user enters team size and use case, sees the recommended plan and the estimated monthly cost. Methodology link explains tier breakpoints. +- Tier 2 (email-gated): a PDF showing the recommended plan, the calculation, and a comparison to alternative plans the user might consider. +- Tier 3 (account-gated): a saved scenario the user can revisit; ability to compare against historical pricing if the calculator is used periodically; option to receive notifications if pricing or recommended plans change. + +Each tier earns its gate. + +Detail in [`references/tiered-value-structures.md`](references/tiered-value-structures.md). + +--- + +## Calculator anti-patterns + +Patterns that look like calculators but degrade trust. + +**The lead-trap.** Result hidden behind email. Detail in keystone framing. + +**The vanity output.** A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? + +**The hidden-methodology calculator.** No way to see the math; no methodology page; no assumption list. The audience uses the tool, gets a number, and cannot defend it. + +**The interrogation form disguised as calculator.** 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +**The misleading-baseline calculator.** "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. The audience that knows the industry sees the gap. + +**The misaligned-units calculator.** "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +**The static-assumption calculator.** Assumptions hardcoded in 2022 that have not been updated. The calculator's outputs are stale. + +**The mobile-broken calculator.** Calculator works fine on desktop, breaks on mobile. The mobile audience either bounces or gets a worse experience that misrepresents the brand. + +Detail in [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-calculator-failures.md`](references/common-calculator-failures.md). + +- "Conversion rate is high; downstream conversion is near zero." Lead-trap or vanity-output pattern; the audience captured did not get value, did not engage with the follow-up, did not convert. +- "Audience visits the calculator, runs it once, never returns." Calculator does not produce a save-worthy or share-worthy result; no reason to come back. +- "Sales team says the calculator-sourced leads are unqualified." Calculator's audience-fit weak; the calculation does not match the buyer's actual decision. +- "We get questions about how the calculator works; we have no answer." Methodology not documented; the team cannot defend the calculator's outputs. +- "We updated the product; the calculator outputs are now wrong." No update cadence; the calculator drifted out of sync with the actual offering. +- "The calculator works; nobody uses it." Calculator hidden in the site; no distribution; the audience does not know it exists. +- "Our calculator looks like our competitor's." Generic calculator-template patterns produce generic calculators; the brand differentiation absent. +- "The form has 12 fields and 4 percent conversion." Interrogation-form pattern; the calculator is collecting data, not delivering value. +- "Audience trusts our brand; the calculator outputs feel arbitrary." Methodology disclosure missing; the brand's credibility does not transfer to the tool because the tool does not show its work. + +--- + +## The framework: 12 considerations for calculator design + +When designing or auditing a calculator, walk these 12 considerations. + +1. **The calculator decision.** Is a calculator the right investment, or would a simpler magnet serve? +2. **Transparent-decision-tool, not vanity or lead-trap.** Result is free; methodology is visible; gate is on additional value, not on the result. +3. **Inputs are necessary, easy, respectful of time.** Each input affects the math; defaults reduce friction; progressive disclosure where it helps. +4. **Calculation methodology disclosed.** Inline formulas, methodology page, source citations, or assumption list. +5. **Result is specific, contextualized, actionable.** Number with units; baseline for interpretation; clear next step. +6. **Tiered value structure.** Free immediate result; gated advanced features; each tier earns its gate. +7. **Email-capture decision honest.** Gate on real value-add (PDF, save-and-compare, custom analysis), not on the result the user came for. +8. **Source attribution clear.** Industry averages, benchmarks, and assumptions all cited or explained. +9. **Mobile experience tested.** Calculator works on the device the audience uses. +10. **Update cadence defined.** When inputs, benchmarks, or product details change, the calculator gets updated. +11. **Distribution planned.** The calculator's audience knows it exists. Landing page, navigation, content references all include the calculator. +12. **Lead quality measured.** Downstream conversion from calculator-sourced leads is the real metric, not surface conversion. + +The output of the framework is a calculator that delivers real decision-support value, earns the email through demonstrated generosity, and produces leads the team can convert downstream. + +--- + +## Reference files + +- [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md) - When a calculator is the right tool for the audience and goal, and when a simpler magnet would serve. +- [`references/input-design-patterns.md`](references/input-design-patterns.md) - Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. +- [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md) - Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. +- [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md) - Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. +- [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md) - What to give freely, what to gate. The lead-trap failure and the transparent-tool win. +- [`references/tiered-value-structures.md`](references/tiered-value-structures.md) - Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. +- [`references/methodology-disclosure-templates.md`](references/methodology-disclosure-templates.md) - Templates for assumption lists, methodology pages, source citations, formula explanations. +- [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md) - The patterns that look like calculators but degrade trust. +- [`references/common-calculator-failures.md`](references/common-calculator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: calculators earn the email when they would have been worth paying for + +The calculators that work as compounding assets are the ones the audience trusts. Not impressive screenshots. Not high conversion rates. Trust. The audience runs the calculator, gets a result they can defend, and remembers the brand as the source of the result they used in their actual decision. + +That is the bar. Below the bar are vanity-calculators (no real result) and lead-traps (result hidden until you pay with an email). Above the bar are transparent-decision-tools that give the audience the answer freely and capture leads through additional value the audience opts in for. + +The discipline is in the design choices. The methodology disclosure that earns credibility. The input design that respects the audience's time. The tiered value structure that makes the email-capture honest. The result presentation that makes the calculator's output usable in the audience's real conversation. The update cadence that keeps the calculator in sync with the offering it represents. + +When in doubt, ask: would the audience pay for this calculator if it were not free, and can they defend the result to a stakeholder after they use it? If yes to both, the calculator earns the email. If no to either, redesign or do not ship. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md b/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md new file mode 100644 index 0000000..8afc216 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md @@ -0,0 +1,200 @@ +# Calculation logic transparency + +Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. The defensibility of the result is the calculator's credibility currency. + +A calculator's output is only as trustworthy as the audience's ability to inspect how it was computed. Calculators that hide methodology produce numbers; calculators that disclose methodology produce defensible numbers. The difference shows up in whether the audience cites the calculator in stakeholder conversations. + +--- + +## The transparency principle + +The audience should be able to inspect the methodology if they care. + +Three levels of transparency, in increasing depth. + +**Level 1: Inline.** The methodology appears in the calculator itself, near the result. "Your annual savings: $14,200 = (current cost x 12) - (estimated new cost x 12) + first-year implementation savings of $X." + +**Level 2: Methodology page.** A linked page explaining the formulas, assumptions, and sources in detail. The result page links to it; users who want depth find it. + +**Level 3: Spec on request.** The team is willing to share the underlying spec, customer-data sources, or formula derivations on request. Useful for analytical or enterprise audiences who want full inspection. + +A calculator should at minimum support Level 1 or Level 2. Level 3 is optional and signals analytical credibility. + +--- + +## Inline formulas + +Show the math near the result. + +**The pattern.** Below or alongside the headline result, show the formula that produced it. + +**Example: ROI calculator inline formula.** + +``` +Annual savings: $14,200 + +Calculation: + Current annual cost: $36,000 ($3,000 / month x 12) + Estimated new annual cost: $24,000 ($2,000 / month x 12) + Annual savings: $36,000 - $24,000 = $12,000 + + First-year implementation savings: $2,200 + Total: $14,200 +``` + +**The win.** The audience can verify the math. They can adjust their inputs and predict how the result will change. They can defend the result to a stakeholder by citing the formula. + +**When to use inline formulas.** When the calculation is straightforward enough to display in a few lines. Most ROI, savings, and pricing calculators fit this pattern. + +**When inline formulas hurt.** When the calculation is so complex (multi-stage, with branching) that the formula display overwhelms the result. In those cases, link to a methodology page instead. + +--- + +## Methodology page + +A linked page explaining the calculation in depth. + +**The pattern.** The result page includes a "How this is calculated" or "Methodology" link. The link opens a page with formulas, assumptions, and sources. + +**What a methodology page should include.** + +- The central formulas in plain text (not just images). +- Each variable defined. +- Each assumption listed plainly. "We assume a 3-month implementation period." "We assume the user is comparing month-over-month." +- Sources for any external benchmarks. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025]." +- Worked example. A specific scenario with input values and the resulting calculation. +- Caveats. "This calculator does not account for [X]; for that, see [other resource]." + +**The methodology page test.** A skeptical reader of the methodology page should come away thinking "this is reasonable" or "I disagree with assumption Y, here is why." Either response is a sign the methodology is real and the audience can engage with it. + +**Methodology pages and SEO.** Methodology pages can themselves rank for search terms ("how is X calculated"), bringing additional traffic to the calculator. The page is not just transparency; it is also a content asset. + +--- + +## Source citations + +When the calculator uses external benchmarks or data, cite the source. + +**The pattern.** "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025, page 23]." + +**Why source citations matter.** They signal that the benchmark is real, not invented. They let the skeptical user verify. They protect the brand if the benchmark is later disputed. + +**Citation discipline.** + +- Cite the most authoritative source available (industry report, academic paper, published study). +- Date the source. Benchmarks decay; an undated source could be from any year. +- Link to the source where possible. Inaccessible sources (paywalled reports cited from memory) are weaker than linked sources. +- If the source is internal customer data, say so. "Source: [Brand]'s customer cohort, n=200, 2024-2025." Internal sources are valid; honesty about their origin matters. + +**The uncited-benchmark failure.** "Industry Average: 14 percent" with no source. The audience that knows the industry sees the gap; the audience that does not know rolls the dice on whether to trust. Either way, credibility leaks. + +--- + +## Assumption lists + +A plain-language list of what the calculator assumes. + +**The pattern.** Either inline (near the result) or on the methodology page, list the assumptions in plain English. + +**Example assumption list for a SaaS pricing calculator.** + +- "We assume your team will use the platform daily." +- "We assume implementation takes 4-6 weeks." +- "We assume the productivity gains compound through year 1 and stabilize in year 2." +- "We assume your current solution costs include licenses, hosting, and 1 FTE for maintenance." +- "We do not account for [specific factors] in this estimate." + +**Why assumption lists matter.** They make the calculator's worldview visible. The audience can see whether the assumptions match their situation. If the assumptions diverge, the audience knows to discount the result accordingly. + +**Honest assumptions vs flattering assumptions.** Honest assumptions reflect the typical case; flattering assumptions reflect the case that produces the most attractive output. Audiences that catch flattering assumptions stop trusting the calculator. + +**The assumption-decay problem.** Assumptions need updating as the world changes. A calculator with assumptions from 2022 may have outdated benchmarks; review quarterly. + +--- + +## The methodology-authority spectrum + +Calculators sit on a spectrum from "fully transparent" to "fully opaque." Each position has tradeoffs. + +**Fully transparent.** All formulas, all assumptions, all sources visible. The audience can fully reconstruct the calculation. Trust is maximum; competitive risk (others copying the methodology) is highest. + +**Largely transparent.** Major formulas visible; minor weighting or proprietary elements glossed. The audience trusts the result; the brand keeps some IP. Common middle ground. + +**Methodology-page transparent.** The result is shown without inline formulas; the methodology page has the depth. The audience that cares finds the depth; the audience that does not, does not have to. + +**Opaque.** No methodology shown. The audience either trusts the brand or not; there is no inspection path. High competitive protection; low audience trust. + +The right position depends on the audience and the goal. Analytical audiences (engineers, finance teams, technical buyers) need transparency to trust. Less-analytical audiences may accept opacity if the brand has earned trust through other means. Most calculators benefit from at least Level 2 (methodology page) transparency. + +--- + +## When the calculation cannot be fully disclosed + +Some calculations include proprietary IP. Honest framing matters. + +**The honest framing.** "The output combines public benchmark data with proprietary insights from our customer cohort. Public elements are detailed in the methodology page; the proprietary weighting reflects our own data and is not detailed here." + +**The dishonest framing.** Hiding the proprietary nature; presenting opaque outputs as if they came from public methodology. + +**The audience's reaction.** Honest framing about proprietary IP is usually accepted. The audience understands that some IP is protected; they appreciate the honesty about what is shown and what is not. Dishonest framing breaks trust when the audience tries to interrogate and finds nothing. + +**The discipline.** Disclose what can be disclosed. Honestly label what cannot. The combination earns more trust than full opacity or false transparency. + +--- + +## Methodology display patterns + +How to integrate methodology into the calculator's UI. + +**Pattern A: Always-visible inline formulas.** The result and the formula appear together. Best for short calculations where the formula is digestible. + +**Pattern B: Expandable methodology details.** The result appears prominently; "How this was calculated" is an expandable section below. The user opens it if they want depth. + +**Pattern C: Methodology link to a separate page.** The result is shown; the methodology page is linked. Good for complex calculations that need full discussion. + +**Pattern D: Hover-revealed assumption tooltips.** Each variable in the result has a tooltip explaining how it was derived. Useful when the calculation has many components. + +**Pattern E: Methodology in PDF report.** The free result shows the headline; the gated PDF contains the full methodology. This pattern works when the PDF is genuinely the value-add and the headline result is enough for free users. + +The choice depends on calculator complexity, audience analytical depth, and the brand's transparency posture. + +--- + +## Common transparency failures + +**No methodology shown.** Result is a number; user has no way to verify or defend it. + +**Hidden assumptions.** Inputs and outputs visible; assumptions baked into the math without disclosure. + +**Uncited benchmarks.** "Industry Average: 14 percent" with no source. + +**Stale assumptions.** Methodology written in 2022, never reviewed. + +**Flattering defaults.** Defaults set to produce favorable outputs; the audience that catches the bias stops trusting. + +**Methodology page that hides more than it reveals.** Marketing copy disguised as methodology; no actual formulas or sources. + +**Inconsistent precision.** Result shown as "$14,237" when the inputs justify only "$14,000 (estimated)." False precision erodes trust. + +**No version history on methodology.** Methodology page changed over time without record; users who relied on previous outputs cannot tell what changed. + +--- + +## The credibility compounding effect + +Transparent calculators compound credibility. + +**The mechanism.** The audience uses the calculator, gets a defensible result, cites it in their decision-making conversation. The brand is in the conversation. The audience returns to the calculator for related decisions. The brand's authority on the topic deepens. + +**The opposite.** Opaque calculators do not compound. The audience uses the calculator, gets a number they cannot defend, leaves it out of their stakeholder conversation. The brand is invisible. The audience does not return. + +**The metric.** Track whether the calculator is being cited. Mentions in customer conversations, references in industry discussions, backlinks from other content all signal compounding credibility. + +--- + +## Methodology-level choices that stay in the public skill + +The transparency principle and the three levels. Inline formulas, methodology pages, source citations, assumption lists. The methodology-authority spectrum. Honest framing for proprietary calculations. Methodology display patterns. Common transparency failures. The credibility compounding effect. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source citations and benchmark relationships. Specific tooling for methodology display. Specific brand-voice methodology copy. The team's update calendars and version control for methodology. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md b/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md new file mode 100644 index 0000000..430a9c9 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md @@ -0,0 +1,211 @@ +# Calculator anti-patterns + +The patterns that look like calculators but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The lead-trap + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +The signal. Conversion-rate metric on the email form looks fine; downstream conversion is near zero; the audience that recognizes the pattern bounces immediately. + +The cost. The leads captured are unqualified or actively annoyed. The brand earns "lead-trap" reputation; trust erodes across all future interactions. + +The cure. Restructure so the result is free and the additional value (PDF, save-and-compare, custom analysis) is gated. Detail in `references/email-capture-decision-tree.md`. + +--- + +## The vanity output + +The pattern. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? Compared to what? + +The signal. Audiences run the calculator out of curiosity; do not return; do not cite the result anywhere; do not engage with the follow-up sequence. + +The cost. The calculator's build cost was wasted. The audience does not associate the brand with useful analysis. + +The cure. Anchor the result to a decision the audience actually makes. The output should be a number with units, contextualized against a baseline, with a clear next step. + +--- + +## The hidden-methodology calculator + +The pattern. No way to see the math. No methodology page. No assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The signal. Sales-team friction; prospects who used the calculator cannot bring its outputs into stakeholder conversations. + +The cost. The calculator does not compound credibility. Each user runs it once and does not return; the brand stays invisible in the audience's actual decision conversations. + +The cure. Disclose methodology. Detail in `references/calculation-logic-transparency.md`. + +--- + +## The interrogation form disguised as calculator + +The pattern. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The signal. Conversion rate on the form is poor. The audience self-selects out at the form length. + +The cost. The calculator's reach drops dramatically. The leads that do convert are over-disclosed and may resent the friction; the audience the calculator could have served does not get to use it. + +The cure. Audit the input set. Remove fields that do not affect the calculation. Capture additional data later in the relationship, not at the form. + +--- + +## The misleading-baseline calculator + +The pattern. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. + +The signal. Audiences with industry knowledge notice the gap. Those audiences do not return; they may post about the bias publicly. + +The cost. Trust damage that can be hard to recover. Brand earns "spin" reputation. + +The cure. Source the baselines honestly. Use defensible benchmarks; if the brand's data is favorable, disclose that the data comes from the brand's own customer cohort and acknowledge the bias. + +--- + +## The misaligned-units calculator + +The pattern. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The signal. Audiences cannot interpret the result; cannot use it in their decision; do not return. + +The cost. The calculator's outputs are uninterpretable; the calculator does not produce decision-grade signal. + +The cure. Numbers with units. Percentages with bases. Multipliers with reference values. Contextualization that makes the result interpretable. + +--- + +## The static-assumption calculator + +The pattern. Assumptions hardcoded in 2022 that have not been updated. Industry benchmarks from 2 years ago. Tooling references to products that have been deprecated. + +The signal. Audiences with current knowledge see the staleness; trust drops; some users may report the inaccuracy. + +The cost. The calculator's outputs are unreliable. The brand looks careless or out of touch. + +The cure. Quarterly maintenance review. Update assumptions, refresh benchmarks, prune stale references. + +--- + +## The mobile-broken calculator + +The pattern. Calculator works fine on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; result hidden below the fold. + +The signal. High mobile bounce rate; mobile conversion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic; this failure is significant. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. Detail in `references/input-design-patterns.md` (mobile section). + +--- + +## The over-precise calculator + +The pattern. Result shown as "$14,237.42" when the inputs justify only "$14,000 (estimated)." False precision suggests the calculator knows more than it does. + +The signal. Analytical audiences see the false precision and discount the result. The calculator earns "fake math" reputation among the audience that matters most. + +The cost. Trust erosion specifically among the audience the calculator was designed to serve. + +The cure. Round to honest precision. Use "estimated" or "approximately" framing. Disclose the precision the inputs support. + +--- + +## The marketing-disguised-as-methodology calculator + +The pattern. The methodology page exists but contains marketing copy ("our proprietary algorithm draws on industry-leading data") rather than actual formulas, sources, or assumptions. + +The signal. Audiences who click through to verify find no real verification; trust drops. + +The cost. The calculator's credibility is performative rather than real; the audience that interrogates discovers the gap. + +The cure. Real methodology. Formulas, assumptions, sources. Brand voice can frame the methodology page; brand voice cannot replace the methodology itself. + +--- + +## The orphan-result calculator + +The pattern. The result loads; no next step is offered. The user gets the number and leaves. + +The signal. Conversion to next step (PDF, save, contact, demo) is near zero because no next step is offered. + +The cost. The calculator captures attention without converting it. The brand has the audience's moment of intent and does nothing with it. + +The cure. Offer a clear next step at the result. PDF, save scenario, talk to team, related resource. Detail in `references/result-presentation-patterns.md` (result-to-action transitions). + +--- + +## The popup-interrupted calculator + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. The user's flow breaks. + +The signal. Bounce rate spikes at the popup moment; users complain about the interruption. + +The cost. The calculator's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. Detail in `references/result-presentation-patterns.md`. + +--- + +## The cookie-cutter calculator + +The pattern. The calculator looks and behaves like every other calculator from a template platform. Generic UI, generic assumption set, generic output styling. + +The signal. The calculator does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The calculator becomes commodity; the brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## The pessimistic-default calculator + +The pattern. Defaults set to make the brand's outputs look favorable through pessimistic baselines. "Current cost" defaults to the high end; "savings" defaults to the optimistic end. + +The signal. Audiences who notice (often analytical audiences) discount the result. The audience the calculator was built for stops trusting it. + +The cost. Same as misleading-baseline. Trust damage; brand earns "spin" reputation. + +The cure. Honest defaults sourced from data; let the user adjust to their actual context. + +--- + +## The form-without-calculator + +The pattern. A "calculator" that is actually a form. No real calculation; the result is generic ("based on your inputs, our team will reach out") or static ("your estimated savings: 30 percent"). + +The signal. Audiences expecting a real calculation get a sales form; bounce rate spikes; the audience perceives bait-and-switch. + +The cost. The calculator's framing was a lie; trust collapses. + +The cure. Either build a real calculator with real math, or do not call the form a calculator. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active calculator, looking specifically for these anti-patterns. + +**Audit questions per calculator.** + +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Is the methodology disclosed in a way the audience can verify (anti-pattern check: hidden-methodology)? +- Are the inputs all necessary for the calculation (anti-pattern check: interrogation-form)? +- Are the baselines and benchmarks sourced and current (anti-pattern check: misleading-baseline, static-assumption)? +- Does the calculator work on mobile (anti-pattern check: mobile-broken)? +- Is the result actionable, with a clear next step (anti-pattern check: orphan-result)? +- Does the calculator differentiate from other calculators on similar topics (anti-pattern check: cookie-cutter)? + +**The retire decision.** Anti-pattern calculators often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-tool plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md b/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md new file mode 100644 index 0000000..b0673aa --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md @@ -0,0 +1,144 @@ +# Calculator investment criteria + +When a calculator is the right tool for the audience and the goal, and when a simpler magnet would serve. The conditions that warrant the calculator's build cost. + +A calculator is one of the highest-build-cost magnet formats. Engineering, design, methodology research, and ongoing maintenance all add up. The calculator earns this investment only when specific conditions are present. + +--- + +## When a calculator earns the build + +Five conditions that, when present, make a calculator a strong investment. + +**The audience faces a specific calculation as part of a real decision.** ROI on a software purchase, savings from a refinance, monthly cost projection, sizing for a service tier, time-to-payback estimate. The calculation has to be one the audience actually runs in their workflow. Without a real calculation, the calculator becomes vanity. + +**The calculation is non-trivial.** Multiplying two numbers does not need a calculator; the audience can do that in their head. Calibrating across 5-10 inputs with branching logic, applying industry benchmarks, or running a multi-scenario comparison earns the format. + +**The brand has methodology authority.** The output has to be defensible. Brands with research, customer data, or industry expertise that informs the calculation can disclose methodology credibly. Brands without that authority often produce calculators audiences cannot trust. + +**The follow-up sequence has a real purpose for the lead.** Calculators capture a specific signal (the inputs reveal the lead's situation: company size, current configuration, projected savings). The sequence has to use that signal. A generic sequence wastes the input data. + +**The success metric is defined.** What does "the calculator works" look like? Lead volume, lead quality, downstream conversion, the audience citing the calculator in stakeholder conversations. Without the success metric defined, evaluation is impossible. + +When all five are present, the calculator is a strong investment. When two or fewer are present, a simpler magnet (template, checklist, or worked example) often serves better. + +--- + +## When a calculator does NOT earn the build + +Funnels where the calculator is the wrong tool. + +**The audience does not actually run this calculation.** The team imagines the audience would benefit from the calculation; the audience does not actually face this decision. Usage is low; the build cost was wasted. + +**The calculation is trivial.** A "savings calculator" that computes "monthly cost x 12" is not a calculator; it is a multiplication. The audience can do this without a tool. + +**The brand cannot disclose methodology honestly.** If the math depends on assumptions the brand cannot defend ("we estimate 60 percent improvement based on internal data we cannot share"), the calculator becomes a vanity tool by necessity. The audience that would benefit from a defensible calculator gets a brand-flattering one instead. + +**A simpler magnet would serve the same audience and goal.** A pricing PDF that shows worked examples and methodology might serve the same audience as a pricing calculator at one-tenth the build cost. Choose the simpler magnet when it would serve. + +**The audience is too small to justify the build.** A calculator for a niche of 200 prospects is hard to justify against the build cost. Direct outreach or a simpler resource may be more efficient. + +**The team cannot maintain the calculator.** Calculators decay as benchmarks change, product details evolve, and tooling updates. Without maintenance commitment, the calculator becomes a stale liability. + +The honest assessment matters more than the default. "Should we have a calculator" is not the question. "Is the calculator the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A calculator's cost is significant. Account for it honestly. + +**The build cost.** Methodology research, formula design, input UX, result UX, calculation engine, methodology disclosure, mobile responsiveness, edge-case handling. A meaningful calculator often takes 60-200 engineering hours plus design and copy. + +**The maintenance cost.** Benchmarks change; product details change; assumptions shift. Quarterly review and updates run 4-12 hours per active calculator. + +**The sequence cost.** The follow-up sequence using the input data is itself a build. 10-30 hours upfront. + +**The opportunity cost.** What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The calculator's success has to clear the bar of those alternatives. + +The decision frame. The calculator earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The methodology-authority precondition + +Without methodology authority, the calculator cannot be defensible. + +The audience's question. After running the calculator: "Where does this number come from?" + +If the team can answer with sources (industry benchmarks, customer data, public research, defensible assumptions), the calculator has methodology authority. The audience can trust the result and use it in their decision. + +If the team cannot answer ("our model just produces this number"), the calculator does not have methodology authority. The audience either does not trust the result or trusts it without understanding it (which is worse for the audience and ultimately for the brand). + +**How to assess methodology authority.** + +- Does the team have direct customer data on the calculation's central variables? +- Does the team have access to defensible industry benchmarks? +- Is the team willing to publish the methodology, or does the methodology have to stay proprietary? +- Can the team defend the methodology to a sophisticated stakeholder? + +If the answer to most of these is yes, the calculator has methodology authority. If the answer is no, the calculator is being built on assumptions that will not survive interrogation. + +--- + +## The decision worked example + +A SaaS analytics platform considering a "ROI of moving from spreadsheets" calculator. + +**Conditions check.** + +- Specific calculation: yes. Prospects evaluating the platform run an internal estimate of switching value. +- Non-trivial: yes. The calculation involves time-saved-per-week, hourly cost of analyst time, error-rate reduction, decision-speed lift, and implementation cost. +- Methodology authority: yes. The team has customer data on time saved, error reduction, and decision speed across 200+ deployed customers. +- Sequence has purpose: yes. Calculator inputs reveal company size, analytics maturity, and current tooling. Sequence can match the lead's profile. +- Success metric defined: yes. Lead volume from the calculator, lead quality (audience-fit at SaaS companies above 50 employees), downstream conversion to demo within 90 days. + +**Decision.** Build the calculator. The conditions warrant it. + +**Tier design.** Tier 1 (free): the headline annual savings number, the breakdown across time-saved, error-reduction, and decision-speed components, methodology disclosure linked. Tier 2 (email-gated): a PDF the prospect can share with their stakeholders showing the calculation in defensible form. Tier 3 (account-gated, optional): saved scenarios across multiple analyst counts and use-case configurations. + +**Maintenance commitment.** Quarterly review of the customer-data benchmarks. Update assumptions when the customer base shifts. + +The decision was not "should we have a calculator" but "given these conditions, this is the calculator to build." + +--- + +## When to choose a simpler magnet instead + +The calculator is the wrong tool. What works. + +**Pricing one-pager template.** When the calculation is "what would my pricing look like," a worked-example one-pager often serves better than a calculator. The prospect adapts the example; the team avoids building. + +**ROI worked-example PDF.** When the calculation is "what would I save," a PDF showing 3-5 worked-example customer scenarios often serves better. The prospect identifies which scenario matches them; the team gets a downloadable resource without engineering overhead. + +**Sizing checklist.** When the calculation is "what tier do I need," a checklist of features and team-size signals can guide the prospect to the right tier without a calculator. + +**Comparison table.** When the calculation is "is this better than the alternative," a static comparison table often serves better than a dynamic calculator. + +The pattern. Many "we need a calculator" intuitions are actually "we need a clear way to communicate this calculation to prospects." Often the simpler format works as well or better, at one-tenth the build cost. + +--- + +## When to retire a calculator + +Calculators decay. Retiring them is part of the discipline. + +**Retire when:** + +- Lead volume has dropped below baseline for two consecutive quarters. +- The product or pricing has changed enough that the calculator's calculations no longer reflect the offering. +- The benchmarks the calculator relies on are stale and the team cannot update them. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. A portfolio of stale calculators costs maintenance attention without producing results. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a calculator. The opportunity-cost frame. The methodology-authority precondition. The decision worked example. When to choose a simpler magnet. The retirement discipline. + +## Implementation choices that stay internal + +Specific calculator topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence. Specific tooling for calculator engineering, hosting, and integration. Specific methodology sources and update calendars. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md b/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md new file mode 100644 index 0000000..badb9cc --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md @@ -0,0 +1,179 @@ +# Common calculator failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the calculator did not work" or "the leads are unqualified" or "we cannot tell what the calculator is producing." + +--- + +## "Conversion rate is high; downstream conversion is near zero." + +**The diagnosis.** Lead-trap or vanity-output pattern. The audience captured did not get value; did not engage with the follow-up; did not convert downstream. + +**The cure.** Audit for lead-trap (`references/email-capture-decision-tree.md`). Audit for vanity-output (`references/result-presentation-patterns.md`). The result has to be specific, contextualized, and actionable; the email gate has to be on additional value, not on the result itself. + +--- + +## "Audience visits the calculator, runs it once, never returns." + +**The diagnosis.** The calculator does not produce a save-worthy or share-worthy result. No reason to come back. + +**The cure.** Add tier-2 value (PDF, saved scenario) that gives the user something to bring back to. Audit the result presentation (`references/result-presentation-patterns.md`); a result the user cannot share with stakeholders rarely produces return visits. + +--- + +## "Sales team says the calculator-sourced leads are unqualified." + +**The diagnosis.** Calculator's audience-fit is weak. The calculation does not match the buyer's actual decision; the audience captured is curious-but-not-buying. + +**The cure.** Audit the calculator's audience-fit. Does the calculation map to a real decision the buyer faces? If not, the calculator may be capturing wrong-segment leads. Detail also in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "We get questions about how the calculator works; we have no answer." + +**The diagnosis.** Methodology not documented. The team cannot defend the calculator's outputs. + +**The cure.** Document the methodology (`references/calculation-logic-transparency.md`, `references/methodology-disclosure-templates.md`). The methodology page should answer the audience's interrogation questions before they ask. + +--- + +## "We updated the product; the calculator outputs are now wrong." + +**The diagnosis.** No update cadence. The calculator drifted out of sync with the actual offering. + +**The cure.** Maintenance discipline. Quarterly review of every active calculator. Update inputs, recommendations, and pricing as the offering evolves. + +--- + +## "The calculator works; nobody uses it." + +**The diagnosis.** Calculator hidden in the site; no distribution; the audience does not know it exists. + +**The cure.** Distribution. Link to the calculator from related landing pages, blog posts, and navigation. Promote it in newsletter and social channels. Cite it in sales conversations. The calculator's existence is not enough; the audience has to know about it. + +--- + +## "Our calculator looks like our competitor's." + +**The diagnosis.** Generic calculator-template patterns produce generic calculators. Brand differentiation is absent. + +**The cure.** Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## "The form has 12 fields and 4 percent conversion." + +**The diagnosis.** Interrogation-form pattern. The calculator is collecting data, not delivering value. + +**The cure.** Audit the input set (`references/input-design-patterns.md`). Each input should affect the calculation. Remove fields that do not. + +--- + +## "Audience trusts our brand; the calculator outputs feel arbitrary." + +**The diagnosis.** Methodology disclosure missing. The brand's credibility does not transfer to the tool because the tool does not show its work. + +**The cure.** Disclose methodology (`references/calculation-logic-transparency.md`). The brand-trust is one part of credibility; the tool's transparency is a separate part. Both have to be present. + +--- + +## "Our pricing changed; the calculator was not updated for 6 months." + +**The diagnosis.** Maintenance lapse. The calculator's outputs were misleading for half a year. + +**The cure.** Set a maintenance trigger: when pricing or product details change, the calculator update is part of the change. Otherwise, set a calendar review at minimum quarterly. + +--- + +## "The calculator was great at launch; conversion has dropped 40 percent over a year." + +**The diagnosis.** Decay. Stale benchmarks; outdated references; methodology that no longer reflects the brand's offering. + +**The cure.** Audit and refresh. If the calculator is still relevant, update it. If it is not, retire it. + +--- + +## "The free result is just 'estimated savings: significant.'" + +**The diagnosis.** Vanity output. The free tier is a teaser rather than a substantive result. + +**The cure.** The free tier has to be substantive. "Estimated annual savings: $14,200" with breakdown and methodology beats "significant savings" with email gate. + +--- + +## "Audiences complete the inputs but do not opt for the PDF." + +**The diagnosis.** The PDF does not justify the email exchange. Either the PDF is the same content as the free result (no value-add) or the audience does not perceive the PDF as worth the email. + +**The cure.** Make the PDF genuinely better. Add comparison tables, case studies, or additional analysis. Frame the PDF as "what you can share with your CFO" so the audience sees the use case. + +--- + +## "We get traffic; we get email signups; the sales team never hears about the leads." + +**The diagnosis.** Sequence missing or poorly designed. The leads sit on the list without being routed to sales. + +**The cure.** Design the post-conversion flow. Calculator-sourced leads should be tagged, routed, and sequenced. Sales should know which leads came from the calculator and what the leads' inputs revealed. + +--- + +## "We added a calculator; our other lead magnets stopped converting." + +**The diagnosis.** Cannibalization. The calculator absorbed the audience that previously converted via other magnets. + +**The cure.** This may not be a failure. If the calculator-sourced leads are higher quality than the previous magnets, the cannibalization is a portfolio improvement. If the calculator absorbed leads but produced no incremental value, the calculator may have replaced a working magnet with a worse one. + +--- + +## "The calculator works on Chrome desktop; it breaks on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The calculator was tested on the team's primary platform; the audience's actual devices were not covered. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use; the calculator has to work there. + +--- + +## "The calculator estimates 60 percent savings; our actual customers see 35 percent." + +**The diagnosis.** The calculator's assumptions are flattering rather than accurate. The customers who used the calculator's projections are now disappointed. + +**The cure.** Recalibrate. Use actual customer cohort data to set the assumptions. The honest result may be less impressive on the marketing screen but earns more trust over time. + +--- + +## "We want to A/B test the calculator's email gate placement." + +**The diagnosis.** This is fine, but the test should be designed carefully. Moving the email gate is a gating-decision change that affects both conversion and lead quality. + +**The cure.** Test gate placement with both conversion-rate and downstream-conversion metrics. A change that lifts conversion but tanks downstream is a regression, not an improvement. + +--- + +## "The calculator's methodology page got 200 visits and 50 unsubscribes." + +**The diagnosis.** Likely the audience interrogated the methodology and found it wanting. Either the methodology has a real flaw, or the methodology page is unclear. + +**The cure.** Audit the methodology page. Either fix the methodology (if there is a real flaw) or clarify the page (if the issue is presentation). + +--- + +## The pattern across failures + +Most calculator failures fall into one of three patterns. + +**Pattern 1: The calculator does not deliver real value.** Vanity output, hidden methodology, lead-trap. The fix is to deliver real, defensible, accessible results. + +**Pattern 2: The calculator does not match the audience or decision.** Audience-fit weak, calculation-decision mismatch, interrogation-form. The fix is to align the calculator to the audience the brand serves and the decision the audience faces. + +**Pattern 3: The calculator decays.** Stale assumptions, outdated benchmarks, broken integration. The fix is maintenance discipline. + +The metric pattern: calculator failures often look fine on conversion rate. The signal is in lead quality, downstream conversion, and audience interrogation behavior. Programs that track only conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md b/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md new file mode 100644 index 0000000..f1fb4fc --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md @@ -0,0 +1,205 @@ +# Email-capture decision tree + +What to give freely, what to gate. The lead-trap failure and the transparent-tool win. + +The single most consequential decision in calculator design is what gets shown freely and what requires an email. Get this wrong and the calculator is either a lead-trap (gating the result the user came for) or a missed opportunity (giving away everything with no capture mechanism). + +--- + +## The honest principle + +Give the audience the result they came for. Gate the additional value. + +The audience showed up to run a calculation. They want the answer. Gating the answer is bait-and-switch: the calculator promised a result, the user provided inputs, and the result is held hostage until they trade an email. + +The transparent alternative: give the result freely. The audience gets what they came for. The brand offers additional value (a PDF report, a saved scenario, a custom analysis) that the audience can opt in for. The email exchange is then for additional value, not for the result the calculator promised. + +--- + +## What to give freely + +Tier 1, no gate. + +**The headline result.** The number the user came for. "Your annual savings: $14,200" or "Recommended plan: Growth." + +**The breakdown.** The components that explain how the headline number was calculated. Necessary for the audience to defend the result. + +**A basic visualization.** A chart or comparison that helps the user see the relationship. + +**The methodology disclosure.** Either inline formulas or a methodology link. Necessary for the audience to trust the result. + +**Source citations.** Where the calculator's benchmarks come from. + +**The assumption list.** What the calculator assumes about the user's situation. + +This set is what the audience needs to use the calculator's output in their decision. Holding any of it hostage is the lead-trap pattern. + +--- + +## What to gate (with email) + +Tier 2, email-required. + +**A formatted PDF report.** The result, breakdown, methodology, and assumptions in a shareable format. The user can send this to their stakeholders. The PDF has to be genuinely better than a screenshot of the result; otherwise the gate is not justified. + +**A saved scenario the user can revisit.** Persistence across visits. The user adjusts inputs over time, returns to compare, sees how the result has changed. Email-required to identify the user. + +**A custom or deeper analysis.** A second-pass calculation that uses the user's inputs as a starting point and adds more depth (more variables, more scenarios, more methodology). Often delivered later (by email) rather than immediately. + +**Email-based notifications.** When the calculator's benchmarks change or new versions launch, the user can be notified. + +The discipline. Each gated tier has to add real value over the free tier. If the PDF is just "the same result in a PDF," the gate is not earning the email. + +--- + +## What to gate (with account or sign-up) + +Tier 3, account-required. + +**Save-and-compare across multiple scenarios.** The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +**Integration with the brand's product or service.** The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +**Historical comparison.** When the calculator is used periodically (monthly cost projection, quarterly review), the user's historical inputs and results are tracked. + +**Collaboration features.** Multiple users on the same account can model scenarios together. + +These features warrant the higher friction of account creation. Email alone is insufficient; the user needs persistent identity for these to work. + +--- + +## The lead-trap failure + +The pattern that destroys conversion. + +**The pattern.** The user enters inputs, hits Calculate, sees "enter your email to see your result." + +**Why it fails.** + +- The audience perceives the manipulation. The calculator promised a result; the result is hidden. +- Conversion drops. Many users abandon at the gate; some enter throwaway emails. +- The leads that do convert are unqualified or actively annoyed; downstream conversion is poor. +- The brand earns "lead-trap" reputation; future users who recognize the pattern bounce immediately. + +**Why teams build lead-traps.** Short-term thinking. The team optimizes for capture rate without measuring downstream conversion. The lead-trap looks like it works because the form-fill rate is high; the lead-trap fails because the leads do not convert. + +**The cure.** Restructure the calculator so the result is free and the additional value is gated. Conversion to the email gate may drop in absolute terms, but the leads that do opt in are higher-quality. + +--- + +## The transparent-tool win + +The pattern that compounds credibility. + +**The pattern.** The user enters inputs, sees the result immediately, and is offered a "Get this as a PDF" or "Save this scenario" option that requires email. + +**Why it works.** + +- The audience trusts the brand. The calculator delivered on its promise. +- The email opt-in is for additional value, not for the result. Users who opt in are signaling real interest in the topic. +- Lead quality is higher because the lead opted in for value-add, which signals genuine interest. +- The brand earns "honest" reputation; word-of-mouth and referral grow. + +**The metrics that matter.** + +- Free-tier completion rate (how many users finish the calculation and see the result). +- Email-tier conversion rate (of those who see the result, how many opt in for the additional value). +- Downstream conversion (of those who opted in, how many engage with the follow-up sequence and convert to the next step). + +The transparent-tool optimizes for downstream conversion, which is the metric that matters for the program. + +--- + +## The decision tree + +Walk through this for each gating decision. + +**Question 1: Is this the result the user came for?** + +- If yes: do not gate. Holding the user-promised result hostage is lead-trap. +- If no: continue. + +**Question 2: Is this additional value the user might want?** + +- If yes: gating is potentially appropriate. +- If no: do not gate; the user does not want it badly enough for the email exchange to be worthwhile. + +**Question 3: Is the additional value substantial enough to justify the email?** + +- If yes: gate it. The user gets real value; the brand gets the email; the exchange is honest. +- If no: do not gate; the gate is not earning its friction. + +**Question 4: Could the additional value be delivered better as a follow-up after the email?** + +- If yes: gate it as a follow-up offer in the post-result flow, not as a barrier to the result. +- If no: gate it as a clear "get this additional value" offer near the result. + +This decision tree separates honest gating from manipulative gating. + +--- + +## Worked examples + +**Example 1: SaaS pricing calculator.** + +- Free: recommended plan, monthly cost estimate, breakdown by component, methodology link. +- Email-gated: a PDF showing the recommendation, alternative plans considered, and a printable comparison table. +- Account-gated: ability to save the scenario and adjust over time as the team's needs change. + +The free tier delivers what the prospect came for. The email gate delivers a shareable artifact for the prospect's internal stakeholders. The account gate enables ongoing use. + +**Example 2: ROI calculator for a B2B service.** + +- Free: estimated annual savings, breakdown across cost reduction and productivity gains, methodology disclosure. +- Email-gated: PDF analysis with industry-comparison context and worked-example case study. +- Account-gated: not offered. The calculator is single-use; account creation is unnecessary friction. + +The free tier serves the audience. The email gate serves the prospect's internal stakeholders by providing a shareable analysis. + +**Example 3: Mortgage calculator.** + +- Free: estimated monthly payment, breakdown across principal, interest, taxes, insurance, methodology link. +- Email-gated: a personalized rate quote (which requires the bank to underwrite based on user inputs). +- Not offered: account creation. The calculator is a one-shot tool; account creation does not match the use case. + +The email gate is justified by genuine value-add (personalized rate quote requires underwriting). The free tier delivers the calculator's promise. + +--- + +## When the email gate is the wrong tool + +Sometimes no gating is the right answer. + +**Calculators built primarily for SEO or brand authority.** A widely-shared, well-ranked calculator can be a strong brand asset even without lead capture. The audience that uses it associates the brand with the topic; the SEO ranking compounds traffic. + +**Calculators where lead-capture friction destroys the value proposition.** A simple, quick-use calculator may be best as a no-gate tool. The audience uses it, gets value, returns; the brand becomes the source of the tool. + +**Calculators in regulated industries.** Some sectors have specific privacy or regulatory constraints on email capture. The calculator may need to operate without standard lead-capture flows. + +The decision depends on the program's goals. Not every calculator needs to be a lead magnet. Some calculators serve other purposes (SEO, brand, audience-building) better without gates. + +--- + +## Common gating failures + +**Result hidden behind email.** The lead-trap. Conversion drops; downstream metrics drop further. + +**Gate without value.** Email required to access something that should have been free; no real additional value behind the gate. + +**Gate that lies about what is gated.** "Get the full analysis" suggests the free version was incomplete; the user expects more depth, gets the same content reformatted, feels deceived. + +**Multiple gates in sequence.** Email for one tier, account for another, phone number for a third. Each step adds friction; cumulative drop-off destroys the audience. + +**Gate copy that is manipulative.** "Don't lose your result, give us your email" is hostile. "Want this as a PDF? Enter your email" is honest. + +**Gate placement that interrupts the result viewing.** The result loads; the user starts reading; a popup appears asking for email. The user's flow breaks; trust drops. + +--- + +## Methodology-level choices that stay in the public skill + +The honest principle. What to give freely. What to gate at email and at account level. The lead-trap failure pattern. The transparent-tool win pattern. The decision tree. Worked examples. When the email gate is the wrong tool. Common gating failures. + +## Implementation choices that stay internal + +Specific gating decisions for the team's calculators. Specific PDF templates and follow-up flows. Specific account-creation flows and integration patterns. Specific gate copy in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md b/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md new file mode 100644 index 0000000..4f8cf5d --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md @@ -0,0 +1,218 @@ +# Input design patterns + +Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. + +The calculator's inputs are the audience's first interaction with the tool. Bad input design loses users before the calculation runs. Good input design respects the user's time and produces inputs that genuinely affect the math. + +--- + +## The necessity principle + +Each input should be necessary for the calculation. Inputs that do not affect the output meaningfully should not be asked for. + +**The test.** For each input, ask: does removing this input change the result by a meaningful amount? If no, the input is not necessary; remove it. + +**The interrogation-form failure.** Calculators that ask 18 inputs but only use 5 in the math are signaling that the form is collecting sales-qualification data. The audience can tell. Conversion drops; trust drops. + +**The honest input set.** Most calculators need 4-10 inputs. Tools asking 15+ inputs almost always have non-essential fields that should move to a separate (later, optional) interaction. + +**The exception: meaningful customization.** When inputs do affect the result and the audience values the customization, more inputs are warranted. A pricing calculator that customizes to industry, team size, use case, and feature needs may need 8-12 inputs because each input affects the output. + +The discipline. Audit the input set against the actual math. Remove fields that do not affect the result. + +--- + +## Default discipline + +Defaults reduce cognitive load. Bad defaults bias the result. + +**Honest defaults.** Set defaults to honest, sourced values. "Average company size: 50" if 50 is the median across the audience. "Typical conversion rate: 14 percent" if 14 percent is a defensible benchmark. + +**Sourced defaults.** When defaults come from external benchmarks, source them. A footnote or tooltip explaining the default's origin earns trust. + +**Adjustable defaults.** The user should be able to override the default with their actual value. Defaults that look hardcoded reduce trust; defaults the user can edit signal that the calculator respects the user's situation. + +**Bias-flattering defaults.** Defaults set to flatter the brand's outputs (high savings, low costs) destroy credibility when the user notices. The audience that catches the bias remembers it. + +**Default decay.** Defaults need updating as benchmarks shift. A default set in 2022 that has not been touched is stale; the audience that knows the current benchmark sees the gap. + +--- + +## Input types + +Choose the right input control for each variable. + +**Numeric input.** Free-form number entry. Use for variables that are user-specific and where exact values matter (revenue, customer count, monthly cost). Often warrants a tooltip explaining what the number represents. + +**Slider.** Visual range control. Use for percentage estimates and ranges where exact values are not knowable (conversion rate, growth rate, retention). Sliders communicate the range and reduce cognitive load on choosing a precise number. + +**Dropdown.** Select from predefined categories. Use for variables that are categorical (industry, region, company size band). Dropdowns prevent invalid inputs and group similar audiences. + +**Toggle.** Binary on/off. Use for feature inclusion/exclusion or scenario switching (with implementation / without implementation). + +**Stepper.** Increment/decrement controls. Use for small whole-number variables (number of users, number of locations) where the range is bounded. + +**Free text.** Open-ended text input. Use sparingly. Free text adds friction and rarely affects calculation; if the calculator needs free text to function, the calculation may be the wrong format. + +The choice depends on the variable's nature. The wrong control type adds friction; the right control type makes the input feel natural. + +--- + +## Progressive disclosure + +Show only the inputs the user is currently working through. + +**The pattern.** The calculator presents 2-4 inputs at a time. The user completes those, the next set appears. Each step builds on the previous. + +**When progressive disclosure helps.** When the calculator has 8+ inputs, when input groups are conceptually distinct (company info, then current state, then desired state), or when later inputs depend on earlier choices. + +**When progressive disclosure hurts.** When the calculator has 4-6 inputs that the user could complete in 30 seconds, hiding any of them adds friction. Single-page calculators are fine for short input sets. + +**Progress indicators.** When the calculator is multi-step, show progress ("Step 2 of 4") so the user knows the time commitment. + +**Back navigation.** The user should be able to go back and adjust earlier inputs without losing later ones. + +--- + +## Input grouping and visual flow + +Group related inputs visually. The user processes related inputs as a unit. + +**Logical groups.** + +- Company info (name, size, industry). +- Current state (current cost, current process, current tools). +- Desired state (target outcome, target timeline). +- Configuration choices (tier, options, add-ons). + +**Visual cues.** + +- Section headers for each group. +- Spacing between groups. +- Consistent input styles within a group. + +**Avoid.** + +- Mixing unrelated inputs in one section. +- Inconsistent label patterns across the form. +- Required-vs-optional ambiguity (mark required inputs explicitly). + +--- + +## Tooltips and explanations + +Inputs that are not self-explanatory need explanation. Inputs that are self-explanatory do not need it. + +**When tooltips help.** When the input requires context the user may not have ("Customer Acquisition Cost: the marketing and sales spend per new customer"), when the input has a specific definition that varies by interpretation, or when the default needs sourcing ("Industry average from [source]"). + +**When tooltips hurt.** When the input is obvious (no tooltip needed for "Number of users"), when the tooltip is marketing rather than explanation, or when the tooltip overwhelms the form visually. + +**Tooltip placement.** Inline (right next to the field label) or hover-triggered. Hover-triggered keeps the form clean for users who do not need explanation. + +**Tooltip discipline.** Each tooltip should answer one question. Multiple paragraphs in a tooltip signal that the input itself needs redesign. + +--- + +## Validation and error handling + +Inputs need validation. Errors need helpful messages. + +**Inline validation.** Validate as the user types or after they leave the field. Catch errors at the point of input, not at submission. + +**Helpful error messages.** "Number must be greater than 0" beats "Invalid input." "Try a value between 1 and 1000" beats "Out of range." + +**Avoid friction.** Validation that rejects too aggressively (rejecting all special characters when only a few cause problems) frustrates users. Error messages that scold ("You must enter...") signal a hostile form. + +**Required vs optional.** Mark required inputs explicitly. Optional inputs should be obvious (and rare; if it is not used, why ask). + +--- + +## Mobile input design + +Many calculator users are on mobile. The input experience has to work there. + +**Mobile-specific considerations.** + +- Touch-friendly input sizes (minimum 44x44 pixel touch targets). +- Numeric keyboards for numeric inputs (use input type="number" or appropriate inputmode). +- Sliders sized for thumb interaction. +- Dropdowns that work with native mobile selection. +- Sufficient spacing between inputs to prevent accidental taps. + +**Mobile testing.** Test the calculator on actual mobile devices, not just browser dev tools. Real-device behavior often differs. + +**Mobile-broken calculator failure.** Calculator works on desktop, breaks on mobile. The mobile audience either bounces or has a worse experience. This failure is common; mobile testing prevents it. + +--- + +## Input examples and worked patterns + +**Pattern: company info input set.** + +- Company size (dropdown: 1-10, 11-50, 51-200, 201-500, 501-2000, 2000+) +- Industry (dropdown of 8-12 categories) +- Current annual revenue (numeric, optional, with tooltip explaining how it affects calculation) + +3 inputs, 30 seconds to complete, all affect the calculation. + +**Pattern: current state input set.** + +- Current monthly cost (numeric, with tooltip) +- Current team size on the relevant function (numeric) +- Current process (dropdown: manual, partially automated, fully automated) + +3 inputs, sets the baseline for the calculation. + +**Pattern: desired state input set.** + +- Target outcome (dropdown: cost reduction, time savings, revenue lift, all of the above) +- Target timeline (slider: 3 months to 24 months) + +2 inputs, sets the goal for the calculation. + +Total: 8 inputs across 3 logical groups. Each input affects the math. Defaults reduce friction. Progressive disclosure presents groups one at a time. + +--- + +## Input decay + +Inputs need maintenance. + +**What decays.** + +- Defaults based on benchmarks that have shifted. +- Tooltips referencing tools or terms that have changed. +- Dropdown options that are no longer accurate (industry categories, product tiers). +- Sources cited in tooltips that no longer exist or have moved. + +**Maintenance cadence.** Quarterly review of every active calculator's inputs. Update defaults, refresh tooltips, prune stale options. + +**The decay-trust connection.** Stale defaults erode trust. The audience notices when "Industry Average: 14 percent (2022)" appears in a 2026 tool. + +--- + +## Common input failures + +**Too many inputs.** 15+ inputs signal interrogation rather than calculation. Audit for non-essential fields. + +**Bias-flattering defaults.** Defaults that produce favorable outputs for the brand. Audiences notice; trust drops. + +**Hardcoded defaults that cannot be changed.** The audience cannot adjust to their actual situation. The calculator feels generic. + +**Wrong input type for the variable.** Free text where dropdown would be better; dropdown where slider would be better. Adds friction. + +**Missing tooltips on non-obvious inputs.** The audience does not know what the input means; they guess; the result is meaningless. + +**Mobile-broken inputs.** Sliders impossible to grab on mobile; dropdowns that overflow; numeric keyboards not triggered. + +**Stale defaults.** Benchmarks from years ago; tooltips referencing deprecated tools; dropdown options that no longer match reality. + +--- + +## Methodology-level choices that stay in the public skill + +The necessity principle. Default discipline. Input type guidance. Progressive disclosure. Input grouping and visual flow. Tooltip discipline. Validation and error handling. Mobile input design. Input decay and maintenance. + +## Implementation choices that stay internal + +Specific input sets for specific calculators. Specific default values from the team's data sources. Specific tooltip copy in brand voice. Specific input components and styling. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md b/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md new file mode 100644 index 0000000..170bf18 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md @@ -0,0 +1,321 @@ +# Methodology disclosure templates + +Templates for assumption lists, methodology pages, source citations, formula explanations. Patterns for disclosing calculation logic in ways the audience can use to defend the result. + +A methodology disclosure is not a marketing document. It is a technical document that lets the audience interrogate the calculator. The templates here cover the patterns that hold up to interrogation. + +--- + +## Methodology page template + +A standalone page that explains the calculator's calculations in detail. + +**Structure.** + +``` +# How the [calculator name] is calculated + +## What this calculator does +[2-3 sentences describing the calculation in plain language] + +## The formulas +[Plain-text formulas with each variable defined] + +## Assumptions +[Plain-language list of what the calculator assumes] + +## Sources +[Citations for any external benchmarks or data] + +## Worked example +[A specific scenario with input values and resulting calculation] + +## Caveats +[What the calculator does not account for; when to seek additional analysis] + +## Updates +[Date of last methodology review; how often the calculator is updated] +``` + +--- + +## Assumption list template + +A plain-language list of assumptions, formatted for scan-ability. + +**Structure.** + +``` +## What this calculator assumes + +- [Assumption 1: stated plainly] +- [Assumption 2: stated plainly] +- [Assumption 3: stated plainly] + +## What this calculator does NOT account for + +- [Excluded factor 1] +- [Excluded factor 2] + +If your situation differs significantly from these assumptions, the result is an estimate; consider [additional resource] for more precise analysis. +``` + +**Example assumption list for a SaaS pricing calculator.** + +``` +## What this calculator assumes + +- Your team will use the platform daily across business hours. +- Implementation takes 4-6 weeks for teams in the 50-200 employee range. +- The recommended plan is based on typical usage patterns from our customer base. +- Productivity gains compound through year 1 and stabilize in year 2. + +## What this calculator does NOT account for + +- Custom integrations or enterprise SSO requirements. +- Volume discounts available for annual contracts above $50K. +- Migration cost from your current platform. + +If your situation involves enterprise SSO, custom integrations, or migration costs, talk to our team for a tailored estimate. +``` + +--- + +## Source citation template + +How to cite external benchmarks or data. + +**Inline citation pattern.** + +``` +Industry Average: 14 percent (Source: [Industry Benchmark Report 2025], page 23) +``` + +**Footnote pattern.** + +``` +Industry Average: 14 percent [^1] + +[^1]: Industry Benchmark Report 2025. Available at [URL]. Accessed [Date]. +``` + +**Multi-source pattern.** + +``` +The conversion-rate benchmark we use combines: +- Industry Benchmark Report 2025 (Source A) +- Our customer cohort data (n=200, 2024-2025) +- Public conversion-rate studies from [Source C] + +The composite benchmark is 14 percent. +``` + +**Internal-source pattern.** + +``` +Source: [Brand]'s customer cohort data, n=200, 2024-2025. The cohort represents customers in the 50-500 employee range across SaaS, e-commerce, and B2B services. +``` + +--- + +## Formula explanation template + +How to display formulas in ways the audience can verify. + +**Plain-text formula pattern.** + +``` +Annual savings = (current annual cost) - (estimated new annual cost) + first-year implementation savings + +Where: + current annual cost = current monthly cost x 12 + estimated new annual cost = recommended plan price x 12 + first-year implementation savings = $500 if migrating from a manual process, otherwise $0 +``` + +**Step-by-step calculation pattern.** + +``` +1. Calculate current annual cost: $3,000 / month x 12 = $36,000 +2. Calculate estimated new annual cost: $2,000 / month x 12 = $24,000 +3. Calculate cost reduction: $36,000 - $24,000 = $12,000 +4. Add first-year implementation savings: $12,000 + $2,200 = $14,200 + +Annual savings: $14,200 +``` + +**Conditional logic pattern.** + +``` +The recommended plan is determined by: + +If team size is 1-10: Starter plan ($X / month) +If team size is 11-50: Growth plan ($Y / month) +If team size is 51-200: Business plan ($Z / month) +If team size is 201+: Enterprise (contact for pricing) + +Plan recommendations may shift based on use case (e.g., teams with heavy data needs may benefit from a higher tier even at a lower seat count). +``` + +--- + +## Worked-example template + +A concrete scenario the audience can read end-to-end. + +**Structure.** + +``` +## Worked example: [scenario description] + +Inputs: +- [Input 1]: [value] +- [Input 2]: [value] +- [Input 3]: [value] + +Calculation: +[Step-by-step formula application] + +Result: +[Final output with units] + +Interpretation: +[1-2 sentences explaining what the result means and how the audience would use it] +``` + +**Example for a SaaS pricing calculator.** + +``` +## Worked example: 75-person B2B SaaS team + +Inputs: +- Team size: 75 +- Use case: Customer support +- Current solution: Manual spreadsheets + +Calculation: +- Recommended plan: Business ($45 / user / month) +- Monthly cost: 75 users x $45 = $3,375 +- Annual cost: $3,375 x 12 = $40,500 +- Estimated time savings: 8 hours / week / agent x 75 agents x $40 / hour x 50 weeks = $1.2M +- Net annual value: $1.2M - $40,500 = $1.16M + +Result: +- Recommended plan: Business +- Monthly investment: $3,375 +- Estimated annual time-savings value: $1.2M +- Net annual value: $1.16M + +Interpretation: +A 75-person customer-support team migrating from manual spreadsheets to the Business plan would invest $40,500 annually and save approximately $1.16M in time-equivalent value. The largest contributor is hours saved per agent per week. +``` + +--- + +## Caveats template + +What the calculator does not do, stated honestly. + +**Structure.** + +``` +## What this calculator does not account for + +- [Excluded factor 1]: why it is excluded and what to do if it matters +- [Excluded factor 2]: why it is excluded and what to do if it matters + +For situations involving [specific complex case], the calculator's estimate may not apply; consider [additional resource or contact] for more precise analysis. +``` + +**Why caveats matter.** Caveats signal the calculator's honesty. The audience that knows the caveats can use the result with appropriate confidence; the audience that does not know the caveats may apply the result to a situation it does not fit. + +**Common caveats to include.** + +- The calculator does not account for taxes, regulations, or jurisdiction-specific factors. +- The calculator does not account for one-time setup or migration costs. +- The calculator's benchmarks reflect the typical case; outliers may differ significantly. +- The calculator's projections are estimates, not guarantees. + +--- + +## Update-history template + +How to track methodology changes over time. + +**Structure.** + +``` +## Updates + +This calculator's methodology was last reviewed on [date]. + +Recent updates: +- [Date]: Updated industry-benchmark source from [old] to [new]. +- [Date]: Adjusted productivity-gains assumption based on cohort data through [year]. +- [Date]: Added consideration for [new factor]. + +Major version history: +- v1.0 ([date]): Initial release. +- v1.1 ([date]): Added [feature]. +- v2.0 ([date]): Refactored methodology to include [new dimension]. +``` + +**Why update history matters.** Audiences who relied on previous outputs can see what changed. The transparency about updates signals that the calculator is maintained, not abandoned. + +--- + +## Methodology integration patterns + +How to integrate the methodology disclosure into the calculator UI. + +**Pattern A: Inline disclosure.** The methodology appears alongside the result. Best for short calculations where the formula is digestible. + +**Pattern B: Expandable section.** "How this is calculated" expandable below the result. The user opens it if they want depth. + +**Pattern C: Linked methodology page.** A "How this is calculated" link to a separate page. Best for complex calculations. + +**Pattern D: Hover-revealed detail.** Each result component has a tooltip explaining how it was derived. Useful for multi-component results. + +**Pattern E: Methodology-in-PDF.** The free result shows the headline; the gated PDF contains full methodology. Works when the PDF is genuine value-add. + +--- + +## Audience-specific methodology depth + +Calibrate methodology depth to the audience's analytical sophistication. + +**Highly analytical audiences (engineers, finance, data scientists).** Detailed formulas, source citations, version history. The audience expects depth and rewards transparency. + +**Moderately analytical audiences (PMs, marketers, operations).** Plain-language formulas, key assumptions, summary citations. The audience wants to verify but does not need every variable. + +**Less analytical audiences (executives, generalists).** Plain-language summary of the methodology, key assumptions, "talk to us if you want depth" option. The audience trusts based on the summary; depth is available if needed. + +The discipline. Match the methodology depth to the audience that uses the calculator. Too thin loses analytical audiences; too dense loses generalist audiences. + +--- + +## Common methodology disclosure failures + +**No methodology shown.** Result without explanation; audience cannot verify or defend. + +**Methodology hidden behind email.** Lead-trap pattern applied to methodology; audience that wants to verify must opt in first. + +**Methodology in marketing language.** "Our proprietary algorithm draws on industry-leading data" is not methodology; it is brand copy. + +**Methodology that hides the assumptions.** Formulas shown; assumptions not stated; audience cannot tell what the calculator assumes about their situation. + +**Methodology that hides the sources.** Industry averages cited without attribution. + +**Methodology that does not match the calculation.** Stated methodology and actual implementation drift apart over time. + +**Methodology with no update history.** Calculator changes silently; audience that relied on previous outputs cannot see what changed. + +--- + +## Methodology-level choices that stay in the public skill + +The methodology page template. The assumption list template. The source citation patterns. Formula explanation patterns. Worked-example template. Caveats template. Update-history template. Methodology integration patterns. Audience-specific methodology depth. Common disclosure failures. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source-citation conventions and benchmark relationships. Specific formula-display tooling and styling. Specific worked-example libraries. The team's methodology update calendars and version control. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md b/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md new file mode 100644 index 0000000..5cd614b --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md @@ -0,0 +1,247 @@ +# Result presentation patterns + +Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. The result is the calculator's product; bad presentation wastes the calculation work. + +A calculator that runs the right math and presents the result poorly fails as completely as a calculator that runs the wrong math. Result presentation is half the user experience. Get it wrong and the audience does not know what to do with the number they computed. + +--- + +## The presentation principle + +The result should be specific, contextualized, and actionable. + +**Specific.** A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." Precision matters; the audience uses the result in their actual decision. + +**Contextualized.** Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." Without the baseline, the number is just a number; with the baseline, it becomes meaningful. + +**Actionable.** What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step bridges from result to action. + +A result that hits all three is one the audience can use in their actual decision. A result that misses any of the three leaves the audience with an unanswered "so what." + +--- + +## The headline number + +The single most important output, large and prominent. + +**The pattern.** One number, one label, large type, central placement. The audience sees the headline number first. + +**Example headline outputs.** + +- "Estimated annual savings: $14,200" +- "Recommended plan: Growth (37 users, 3 admins)" +- "Time to payback: 8 months" +- "Estimated monthly cost: $2,400" + +**The discipline.** + +- One headline number, not five. Multiple competing headlines fragment the user's attention. +- Number with units. "$14,200" beats "14200." "8 months" beats "8." +- Honest framing. "Estimated" or "Projected" is honest; "Guaranteed" is overstatement. +- Visual hierarchy. The headline is the largest text on the result screen. + +**Headline number antipatterns.** + +- "Up to $50,000" (range with no specific value). +- "Significant savings" (no number). +- "X% improvement" (no base). +- Multiple competing numbers (user does not know which to focus on). + +--- + +## The breakdown + +Sub-results that explain how the headline number was calculated. + +**The pattern.** Below the headline, show the components that make up the result. + +**Example breakdown for an ROI calculator.** + +``` +Annual savings: $14,200 + + Cost reduction: $9,200 + Current cost: $36,000 + New cost: $26,800 + + Productivity gains: $4,000 + Hours saved per week: 8 + Hourly cost: $50 + Weeks per year: 50 + + Implementation savings: $1,000 (first year only) +``` + +**Why the breakdown matters.** + +- It makes the headline number defensible. The user can cite the components. +- It helps the user understand how their inputs influenced the result. Adjusting inputs becomes meaningful. +- It surfaces the assumptions implicitly. The user sees what the calculator weighted. + +**Breakdown display options.** + +- Stacked text (as above). +- Expandable section (compact by default; user opens for detail). +- Visual breakdown (stacked bar chart, pie chart for components). + +--- + +## Visualization + +Charts and graphics that help the user see the relationship. + +**When visualization helps.** + +- Comparing the result against a baseline ("current vs new"). +- Showing components contributing to a total ("savings breakdown"). +- Showing change over time ("month-by-month savings projection"). +- Showing thresholds ("you fall in the 'mid-market' band based on your inputs"). + +**When visualization hurts.** + +- When the data does not warrant a chart (a single number does not need a pie chart). +- When the chart obscures rather than clarifies (3D pie charts, gratuitous animation). +- When the chart cannot be interpreted on mobile. + +**Visualization patterns.** + +- **Bar comparison.** Current state vs new state. Easy to read; instant relative comparison. +- **Stacked bar (component breakdown).** Total height = headline; segments = components. +- **Line chart (time series).** Monthly cost projection over 12-24 months. +- **Threshold indicator.** Position the user's result on a scale ("you are at the 73rd percentile"). + +**Visualization quality discipline.** + +- Charts should be readable at the size displayed. +- Labels should be present and legible. +- Color should reinforce, not decorate (different colors for different components, not random palette). +- Mobile rendering should preserve readability; charts that work on desktop and break on mobile fail half the audience. + +--- + +## Scenario comparison + +Useful when the calculator is illustrating a delta between two states. + +**The pattern.** Show the user's current state and the projected state side-by-side, with the delta highlighted. + +**Example: SaaS migration calculator.** + +``` + Current New Change +Annual cost $36,000 $24,000 -$12,000 +Hours/week 12 hrs/wk 4 hrs/wk -8 hrs/wk +Errors/month 14 3 -11 +``` + +**Why scenario comparison works.** + +- The delta is the value proposition; showing both states makes the delta concrete. +- The user can see what they are giving up (if anything) alongside what they are gaining. +- The comparison format is familiar from spreadsheets and decision tools. + +**When scenario comparison applies.** Calculators that compare a current state to a proposed state (migrations, refinances, configurations). Less applicable to calculators that produce a single recommendation without an explicit baseline. + +--- + +## Result-presentation antipatterns + +Patterns that waste the calculation. + +**Buried result.** The result requires scrolling past 5 paragraphs of marketing. The user came for the result; serve it first. + +**Vague output.** "Significant" or "Up to" framing without specific values. The audience cannot use vague results in real decisions. + +**Result followed by 5 paragraphs of marketing.** The result is what the user came for; the brand pitch belongs after, not before. + +**Result that requires re-entering inputs to view.** Persist inputs and results within the session. Forcing re-entry is a friction the user did not consent to. + +**False precision.** "$14,237.42" when the inputs justify only "$14,000 (estimated)." Precision the math does not support erodes trust. + +**Multiple competing headlines.** Five "important" numbers; the user does not know what to focus on. + +**Disconnected result and breakdown.** The headline number does not obviously add up from the breakdown components. The user does the mental math, finds the gap, loses trust. + +**Result without a next step.** The user gets the number, then what? Without a next step, the calculator does not bridge to action. + +--- + +## Mobile result presentation + +The result should work on mobile. + +**Mobile-specific considerations.** + +- Headline number readable without zoom. +- Breakdown components stack vertically rather than spread horizontally. +- Visualizations sized for mobile screens; complex multi-axis charts often do not translate. +- Scroll position lands on the result, not the inputs. + +**Common mobile failures.** + +- Headline number tiny on mobile because it was sized for desktop. +- Breakdown table requires horizontal scroll. +- Charts illegible at mobile size. +- Result hidden below the fold; user does not know it loaded. + +--- + +## Result-to-action transitions + +The result should lead naturally to a next step. + +**Patterns.** + +- **CTA below the result.** "Get a PDF of this analysis" or "Save this scenario" or "Talk to our team about implementing this." +- **Multiple CTAs ranked.** Primary action prominent; secondary action visible but smaller; tertiary action available but not pushy. +- **Email-capture in context.** When the gated tier (PDF, save) is offered, the form appears in context with the result, not in a popup that breaks flow. + +**The discipline.** + +- The next step should match the audience's likely intent. After a savings calculator, "talk to sales" may be premature; "get a PDF I can share" may match. +- Multiple CTAs should not compete; rank them by likely user intent. +- The next step should be honest. Promising "instant analysis from a specialist" and delivering "we will email you in 5 days" breaks trust. + +--- + +## Result update behavior + +When the user adjusts inputs, the result updates. + +**Real-time updates.** As the user changes a slider, the result recalculates. Useful for exploration; the audience sees the relationship between inputs and result. + +**On-submit updates.** The user adjusts inputs, hits Calculate, sees the new result. Useful for calculators with many inputs where real-time updates would be distracting. + +**Hybrid.** Real-time for sliders and toggles; on-submit for full input changes. Common middle ground. + +**The choice.** Depends on calculator complexity and the value of input exploration. Calculators that benefit from "what if" exploration favor real-time; calculators that produce a definitive recommendation favor on-submit. + +--- + +## Result-context for share-ability + +When users share the result with stakeholders, the result has to be self-contained. + +**The principle.** The shared result (PDF, email, screenshot, link) should be interpretable by someone who did not run the calculator. + +**What share-able results need.** + +- The headline number and what it represents. +- The breakdown so the recipient can verify the math. +- The methodology so the recipient can interrogate the assumptions. +- The inputs so the recipient knows what scenario was modeled. +- Brand attribution so the recipient knows the source. + +**The non-shareable result.** "Your savings: $14,200" with no inputs, no methodology, no breakdown. The recipient cannot use this; they ignore it or come back to ask follow-up questions that should not have been necessary. + +The shareable result extends the calculator's reach. The audience that shares is bringing the brand into a conversation; make the result strong enough to carry that weight. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation principle (specific, contextualized, actionable). Headline number discipline. Breakdown patterns. Visualization patterns and discipline. Scenario comparison. Result-presentation antipatterns. Mobile result presentation. Result-to-action transitions. Result update behavior. Share-ability discipline. + +## Implementation choices that stay internal + +Specific result-page layouts for specific calculators. Specific visualization libraries and styling. Specific PDF templates for share-able results. Specific brand-voice copy for next-step CTAs. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md b/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md new file mode 100644 index 0000000..ce17cf8 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md @@ -0,0 +1,236 @@ +# Tiered value structures + +Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. + +The architecture that lets calculators capture leads honestly. The user gets immediate value (free tier) and is offered progressively richer value at each tier with proportional friction. Each tier earns its gate. + +--- + +## The tier-design principle + +Each tier should add real value over the previous. Tiers that gate the same content at higher friction destroy trust. + +**Tier 1 (no gate).** Immediate, complete result. The audience gets what they came for. The free tier is not a teaser; it is the substantive output of the calculator. + +**Tier 2 (email-gated).** Additional value the user might want for sharing, persistence, or depth. Email is the appropriate friction level for this value. + +**Tier 3 (account-gated).** Persistent, multi-session, collaborative, or product-integrated value. Account creation is the appropriate friction level for this value. + +Each tier's friction matches its value-add. Tiers that ask for more friction than they justify destroy conversion. + +--- + +## Tier 1: free immediate result + +What lives at Tier 1. + +**The calculator's primary output.** The headline result the user came for. Annual savings, recommended plan, monthly cost, time to payback. + +**The breakdown.** Components that show how the headline was calculated. + +**Basic visualization.** A chart or comparison that helps the user see the relationship. + +**Methodology disclosure.** Either inline formulas or a methodology link. + +**Assumption list.** What the calculator assumes about the user's situation. + +**Source citations.** Where the calculator's benchmarks come from. + +The Tier 1 set is complete. A user who never opts into Tier 2 still got the calculator's full value. The brand still earns trust; the audience still associates the brand with the topic. + +**What Tier 1 should NOT include.** + +- A teaser version of the result that withholds the actual answer. +- A "preview" of the analysis that requires email to see in full. +- Marketing copy that displaces the result itself. + +--- + +## Tier 2: email-gated additional value + +What lives at Tier 2. + +**A formatted PDF report.** The Tier 1 content packaged in a shareable format. The PDF has to be genuinely better than a screenshot, or the gate is not justified. + +**A saved scenario.** The user's inputs and result persist; they can return to the calculator and see their previous calculation. + +**A custom analysis.** A deeper second-pass calculation, often delivered by email after submission. + +**Notification opt-in.** Updates when benchmarks change, when new calculator versions launch, or when the brand publishes related content. + +**Tier 2 design discipline.** + +- Each Tier 2 offering must clearly justify the email exchange. "Get a PDF that you can share with your CFO" is justifiable; "Get the same content in a PDF" is not. +- The email-capture form should appear in context with the offer, not as an interruption to the Tier 1 viewing. +- The follow-up email should deliver the promised value immediately, not delay it. + +--- + +## Tier 3: account-gated persistent value + +What lives at Tier 3. + +**Save-and-compare across multiple scenarios.** The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +**Historical tracking.** When the calculator is used periodically (monthly projection, quarterly review), the user's historical inputs and results are tracked over time. + +**Collaboration features.** Multiple users on the same account can model scenarios together. + +**Product integration.** The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +**Tier 3 design discipline.** + +- Account creation is significant friction. Tier 3 features must justify it. +- Tier 3 is often unnecessary. Many calculators serve their purpose with Tier 1 and Tier 2 alone; do not add Tier 3 unless the use case warrants it. +- Account-creation friction can be reduced (social login, magic link) but not eliminated. + +--- + +## Worked example: SaaS pricing calculator + +A B2B SaaS platform considering a tiered pricing calculator. + +**Tier 1 (free).** + +- The user enters team size, role distribution, and use case. +- Sees the recommended plan and the estimated monthly cost. +- Sees a breakdown showing per-seat cost, included features, and any add-ons. +- Sees a comparison against the next-tier-up plan with a brief explanation of when it would be worth it. +- Sees a methodology link explaining how recommendations are made. + +**Tier 2 (email-gated).** + +- A PDF showing the recommended plan, the breakdown, the next-tier comparison, and 2-3 customer case studies of similar teams using similar plans. +- The PDF is shareable and contains enough context for an internal stakeholder to evaluate. + +**Tier 3 (account-gated).** + +- The user can save the scenario and adjust inputs over time as the team grows. +- The user can model alternative scenarios (different team size, different use case) and compare side-by-side. +- The user can receive an email when their team size threshold suggests a tier change. + +Each tier earns its gate. The user can stop at Tier 1 and still get value. Tier 2 is offered as a way to share with stakeholders. Tier 3 is offered for users who want ongoing tracking. + +--- + +## Worked example: ROI calculator for a B2B service + +A B2B service company considering an ROI calculator. + +**Tier 1 (free).** + +- The user enters current cost, team size, and process maturity. +- Sees estimated annual savings. +- Sees a breakdown across cost reduction, productivity gains, and implementation savings. +- Sees the methodology disclosed inline. + +**Tier 2 (email-gated).** + +- A PDF showing the calculation in defensible form, with industry-context comparison and a worked-example case study from a similar customer. + +**Tier 3.** Not offered. The calculator is single-use; account creation would be unnecessary friction. + +The two-tier structure fits the use case. Adding Tier 3 would add friction without value. + +--- + +## Worked example: financial calculator (mortgage, refinance, savings) + +A financial services company considering a savings calculator. + +**Tier 1 (free).** + +- The user enters current loan details, target rate, and timeline. +- Sees estimated monthly savings, total savings over the loan term, and break-even point on closing costs. +- Sees the breakdown and methodology. + +**Tier 2 (email-gated).** + +- A PDF analysis with comparison across multiple lender scenarios. +- A personalized rate quote (which requires underwriting based on user inputs). + +**Tier 3.** Optional. An account that tracks the user's loan over time and notifies them when refinance opportunities emerge as rates change. + +The Tier 2 includes genuine value-add (personalized quote requires underwriting). The Tier 3 is optional for users who want ongoing monitoring. + +--- + +## Tier-design failures + +Patterns that look like tiered value but degrade trust. + +**Teaser-tier-as-Tier-1.** The free tier shows a partial result; the email tier shows the full result. This is lead-trap dressed as tiered value. + +**Same-content-different-format.** Tier 1 is the result on screen; Tier 2 is the same result in a PDF. The PDF is not value-add; the gate is not justified. + +**Inverted tiers.** Tier 1 is thin; Tier 2 is what should have been Tier 1; Tier 3 is what should have been Tier 2. The audience that gets Tier 1 sees nothing useful; conversion drops. + +**Tier-3 friction without Tier-3 value.** Account creation required for features that could have been email-only or free. Friction without value-add destroys the gate. + +**Surprise upsells.** The user opts into Tier 2; the email follow-up reveals additional gates the user did not anticipate. Trust drops. + +--- + +## The flat-tier alternative + +Some calculators do not need tiers. + +**When flat is right.** + +- Simple calculators where the result is the only output worth offering. +- Calculators built for SEO or brand authority where lead capture is secondary. +- Calculators where account creation does not match the use case. + +**The flat structure.** Tier 1 (free, complete result). Optional email opt-in for newsletter or related content (no gate, no friction). + +This structure works when the calculator's primary value is the calculation itself and the lead-capture motion is secondary or absent. + +--- + +## Tier transitions + +How the user moves from tier to tier. + +**Tier 1 to Tier 2.** The user sees the free result. Below or alongside, an offer: "Want this as a PDF you can share?" or "Save this scenario for later." Email-capture in context. + +**Tier 2 to Tier 3.** After the user has engaged with Tier 2 (downloaded the PDF, returned to the saved scenario), an offer: "Want to track this over time? Create an account." The friction increase is justified by the additional value. + +**The discipline.** Tier transitions should feel natural, not pushy. The user gets value at each tier; the next tier is offered, not demanded. + +--- + +## Tier maintenance + +Tiers decay along with the calculator. + +**Tier 1 maintenance.** Update defaults, refresh sources, update methodology as benchmarks shift. + +**Tier 2 maintenance.** Update PDF templates as the brand evolves; refresh case studies; update comparison data. + +**Tier 3 maintenance.** Maintain the account-side functionality; ensure persistence works; update integrations. + +**The retire-tier decision.** Tier 3 features that are not used can be retired. Tier 2 PDFs that no one downloads can be simplified. Periodic audit of tier usage informs maintenance. + +--- + +## Common tier failures + +**Tier 1 is a teaser.** Lead-trap pattern. + +**Tier 2 does not justify the email.** Same content, repackaged. + +**Tier 3 is offered but unused.** Friction without payoff; sometimes the right answer is to retire Tier 3. + +**Tier transitions are pushy.** Aggressive popups at each transition; the user feels pressured. + +**Tier maintenance lapses.** Stale PDFs, broken account features, outdated comparison data. + +--- + +## Methodology-level choices that stay in the public skill + +The tier-design principle. What lives at each tier. Tier-design discipline at each level. Worked examples across calculator types. The flat-tier alternative. Tier transitions. Tier maintenance. Common failures. + +## Implementation choices that stay internal + +Specific tier structures for specific calculators. Specific PDF templates and account-creation flows. Specific tooling for tier transitions. The team's tier-usage measurement and audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md b/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md new file mode 100644 index 0000000..0cdffe9 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md @@ -0,0 +1,266 @@ +--- +name: chatbot-flow-design +description: "Designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. Honest about scripted-bot (rigid trees, fail edge cases), hallucinating-bot (LLM without structure, makes things up), and structured-guided-conversation (LLM-powered with intent architecture and fallback discipline) patterns. Distinguishes chatbot DESIGN (this skill) from chatbot IMPLEMENTATION (engineering and platform work). Triggers on chatbot, conversational AI, AI agent, chat widget, intent design, conversational flow, bot escalation, LLM grounding. Also triggers when a chatbot is hallucinating, when a scripted bot is failing edge cases, or when a chatbot is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing conversational flows for chatbots and AI agents on websites. Distinguishes scripted-bot (rigid trees, fail edge cases) from hallucinating-bot (LLM without structure, makes things up) from structured-guided-conversation (LLM-powered with intent architecture and fallback discipline)" +display_order: 5 +--- + +# Chatbot Flow Design + +A senior growth practitioner's playbook for designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. The discipline of building a bot that knows what it knows and routes appropriately when it does not. + +Most chatbots on the web fail in one of two ways. Scripted bots break the moment a user phrases something the script did not anticipate; the user gets pushed through a decision tree that does not fit their situation. LLM-powered bots without structure hallucinate; they confidently answer questions about pricing, policy, or capabilities and frequently make up answers, creating support burden and trust damage. + +The chatbots that work do something different. They have an intent architecture that defines what the bot can and cannot handle. They ground their responses in a knowledge base so they do not invent facts. They have explicit fallback paths for unclear or out-of-scope intents. They escalate to humans cleanly when the bot's job is done. The audience trusts the bot because the bot is honest about its scope. + +The voice is the senior growth practitioner who has watched chatbots become trusted brand surfaces and watched them become liability risks. Practical, opinionated about the architecture that distinguishes the two outcomes, willing to call out when a chatbot is the wrong investment or when an existing chatbot needs to be redesigned rather than tuned. + +When to use this skill: scoping a chatbot for the first time, auditing a chatbot that hallucinates or fails edge cases, designing the intent architecture and fallback patterns, or deciding when to escalate to humans. + +--- + +## What this skill covers + +This skill spans chatbot design as conversational flow architecture, not chatbot implementation. The growth-tooling distinctions: + +- `ai-content-collaboration` covers AI in content workflows. This skill covers AI in customer-facing conversations. +- `integration-orchestrator` covers cross-team coordination for chatbot deployment. This skill is the conversational design itself. +- `pm-spec-writing` covers the spec for engineers building the bot. This skill is about WHAT the conversation should be; pm-spec-writing is about communicating it. +- `discovery-research-synthesis` covers customer research that informs intent architecture. Input to this skill, not part of it. +- **`chatbot-flow-design` (this skill)** is intent architecture, knowledge-base grounding, fallback patterns, and escalation discipline. + +The audience: growth marketers and product marketers shipping chatbot growth tooling, in-house teams designing conversational flows for marketing or support contexts, agencies running chatbot work for clients. + +Out of scope: AI in content workflows (covered by `ai-content-collaboration`); the engineering implementation of chatbots (handed off via `pm-spec-writing`); platform-specific bot configurations (those stay implementation-side); voice agents and IVR flows (different methodology though related principles apply). + +--- + +## The chatbot decision: when chatbots earn deployment + +Before designing the chatbot, decide whether a chatbot is the right tool. + +**Chatbots earn deployment when:** + +- The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. +- The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. +- The bot can ground its answers in real knowledge (documentation, product specs, pricing pages). Without grounding, the bot's answers are at best generic and at worst fabricated. +- The team can maintain the bot. Chatbots decay; intents drift; knowledge bases need updating. Without maintenance commitment, the bot becomes stale liability. + +**Chatbots do NOT earn deployment when:** + +- The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. +- The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates or stays so generic it adds no value. +- The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. +- The audience is small enough that direct human conversation is more efficient. +- The team cannot maintain the bot. Stale bots produce wrong answers. + +The decision is not "should we have a chatbot"; it is "is the chatbot the right tool for this specific audience and conversation." + +Detail in [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md). + +--- + +## Scripted-bot vs hallucinating-bot vs structured-guided-conversation + +The keystone framing. + +**Scripted-bot.** Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. The chatbot equivalent of an automated phone tree. Cost: the user's actual question goes unanswered; the bot pushes the user through paths that do not fit; the audience leaves with a worse experience than no bot. + +**Hallucinating-bot.** LLM-powered with no structure. Will confidently answer questions about pricing, policy, capabilities, and frequently make up answers. Liability risk; trust-eroding; support burden when wrong answers reach customers. Cost: the bot's confident wrong answers damage the brand more than no bot would; the team learns about the hallucinations through customer complaints. + +**Structured-guided-conversation.** LLM-powered with intent architecture, knowledge-base grounding, defined fallback paths, and explicit escalation to humans. The bot knows what it knows, knows what it does not, and routes appropriately. Cost: the design effort upfront is significant; the maintenance is real; the audience trusts the bot because the bot is honest about its scope. + +The litmus test. Ask the bot a question outside its intended scope. Does it confidently make up an answer (hallucinating), refuse rigidly (scripted), or honestly route the user to a human or alternative resource (structured-guided)? The third response is the goal. + +--- + +## Intent architecture + +Defining what the bot can and cannot handle. + +**The principle.** The bot has a defined set of intents it can handle. Each intent maps to a conversation pattern (questions to ask, knowledge to ground in, response to provide). Anything outside the intent set falls to fallback. + +**Intent design patterns.** + +- **Named intents.** "Pricing question," "feature comparison," "integration question," "support escalation," "demo request." Each intent is explicit. +- **Intent hierarchy.** Top-level categories with sub-intents. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question." +- **Intent boundaries.** Each intent has clear scope. Out-of-scope topics route to fallback. + +**Intent coverage.** The bot's intents should cover 70-90 percent of expected conversations. The remaining percentage falls to fallback. Trying to cover 100 percent often produces bloated intent sets that the bot cannot handle reliably. + +**Intent maintenance.** Intents drift as products evolve, audiences shift, and conversations change. Periodic review surfaces which intents are useful and which need refining. + +Detail in [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md). + +--- + +## Knowledge-base grounding + +The bot's responses must come from real knowledge, not made-up confidence. + +**The principle.** The bot's response generation should reference a structured knowledge base (documentation, product specs, pricing pages, support articles). The bot does not invent answers; it retrieves and presents. + +**Grounding patterns.** + +- **Retrieval-augmented generation (RAG).** The bot searches a knowledge base for relevant content before generating a response. The response is grounded in retrieved content. +- **Source-of-truth design.** The knowledge base is the canonical source. When the bot answers, the underlying source is identified. +- **Citation discipline.** The bot can cite the source ("based on our pricing page, ..."). Audiences benefit from knowing where the answer came from. +- **Knowledge-base maintenance.** The knowledge base is maintained as the product evolves; the bot's answers stay current. + +**The hallucinating-bot failure.** No grounding. The LLM generates confident-sounding answers from nothing. The team discovers wrong answers through customer complaints. + +**The structured-guided win.** Grounded answers. The bot's responses match the source-of-truth. Customer-facing accuracy is maintained. + +Detail in [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md). + +--- + +## Branching and conditional logic + +How the bot adapts the conversation based on user input. + +**The principle.** The bot's conversation can branch based on user inputs (intent recognized, prior answers, user attributes). Branching makes the conversation feel adaptive. + +**Branching patterns.** + +- **Intent-driven branching.** Different intents lead to different conversation flows. +- **Context-driven branching.** "Are you asking about plan A or plan B?" routes to plan-specific information. +- **User-attribute branching.** Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB. +- **Multi-turn branching.** The conversation deepens over turns; later turns build on earlier context. + +**Branching discipline.** Each branch should add value. Decorative branching (asking for confirmation when none is needed) adds friction. + +**Branching limits.** Bots that branch too deeply lose users. 3-5 turns is often the practical limit before the user wants resolution. + +Detail in [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md). + +--- + +## Fallback patterns + +What happens when intent is unclear or out-of-scope. + +**The principle.** Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." + +**Fallback patterns.** + +- **Clarifying question.** "Can you tell me more about what you are looking for?" Asks the user to refine; sometimes recovers. +- **Suggested intents.** "I can help with X, Y, or Z. Were you asking about one of those?" Surfaces what the bot can do. +- **Resource handoff.** "I cannot answer that, but here is our [documentation page] that covers it." +- **Human escalation.** "Let me connect you with a human who can help." + +**Fallback discipline.** Multiple fallback layers. First, try clarification. If unclear after one round, suggest alternatives or escalate. Do not loop the user through 5 clarification attempts. + +**The fallback-as-honesty principle.** A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers they were given confidently. + +Detail in [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md). + +--- + +## Escalation to human + +When, how, with what context handoff. + +**The principle.** Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. + +**Escalation triggers.** + +- **User-initiated.** "Talk to a human." The bot escalates immediately. +- **Out-of-scope intent.** The bot recognizes the user's intent is outside its scope; escalates with the intent context. +- **Repeated fallback.** After 2-3 unclear exchanges, the bot escalates rather than loop. +- **Sentiment-driven.** The user's sentiment indicates frustration; the bot escalates rather than persist. +- **High-stakes topic.** Sensitive topics (cancellations, complaints, security) escalate by default. + +**Escalation context handoff.** When escalating, the bot passes the conversation history and recognized intent to the human. The human does not start from scratch; they pick up where the bot left off. + +**The escalation-quality test.** Does the human pick up the context smoothly, or do they have to ask the user to repeat everything? The latter signals broken handoff. + +Detail in [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md). + +--- + +## Conversation analytics + +Measuring what the bot is and is not doing well. + +**The principle.** Track the bot's performance per intent, per fallback, per escalation. The data informs maintenance and design improvements. + +**Conversation metrics.** + +- **Intent recognition rate.** What percentage of conversations are correctly classified into intents? +- **Resolution rate per intent.** What percentage of conversations starting with intent X resolve successfully (user gets the answer they needed)? +- **Fallback rate.** What percentage of conversations hit fallback? High fallback rates signal intent gaps. +- **Escalation rate per intent.** What percentage of conversations within each intent escalate? High escalation may signal the intent should not be bot-handled. +- **User satisfaction.** Post-conversation surveys when feasible. Useful but limited; many users do not respond. + +**Diagnostic uses.** + +- High fallback rate: intents missing or unclear; expand or refine intent set. +- Low resolution rate per intent: knowledge base inadequate; improve grounding. +- High escalation rate per intent: the intent may not be appropriate for bot handling. +- High repeat-fallback within conversations: clarifying questions not landing; redesign clarification. + +Detail in [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md). + +- "Bot makes up answers about pricing." Hallucinating-bot pattern; no grounding to pricing source-of-truth. +- "Users say the bot is rigid and unhelpful." Scripted-bot pattern; intents do not cover real questions. +- "Sales is angry that the bot is qualifying leads wrong." Intent recognition or routing logic broken; audit qualification flow. +- "Support tickets increase after chatbot launch." Bot is producing wrong answers that send users to support; audit grounding and resolution. +- "Users abandon mid-conversation." Bot loops or fallback patterns are inadequate. +- "We cannot tell what the bot is actually doing." Analytics missing; instrument before further changes. +- "Bot was great at launch; quality has degraded." Maintenance lapse; knowledge base or intent set out of date. +- "Bot escalates to humans for everything." Escalation logic too permissive; bot should handle more. +- "Bot tries to handle everything itself." Escalation logic too restrictive; bot should escalate more. +- "Users complain the bot does not know what they asked five minutes ago." Conversation context not preserved across turns. + +--- + +## The framework: 12 considerations for chatbot flow design + +When designing or auditing a chatbot, walk these 12 considerations. + +1. **The chatbot decision.** Is a chatbot the right tool for this audience and conversation, or would a different channel serve? +2. **Structured-guided-conversation, not scripted or hallucinating.** Intent architecture; knowledge-base grounding; fallback discipline. +3. **Intent architecture sound.** Named intents with clear scope; coverage targets 70-90 percent of expected conversations. +4. **Knowledge-base grounded.** Responses retrieved from source-of-truth; the bot does not invent answers. +5. **Branching adds value.** Each branch serves a real need; depth limited to 3-5 turns. +6. **Fallback patterns multi-layered.** Clarification, suggested intents, resource handoff, human escalation. +7. **Escalation triggers defined.** User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. +8. **Escalation context handoff clean.** Humans pick up where the bot left off. +9. **Analytics instrumented.** Per-intent recognition, resolution, fallback, escalation rates. +10. **Maintenance cadence defined.** Knowledge base refreshed; intent set audited; bot quality verified. +11. **Brand voice consistent.** The bot sounds like the brand it represents. +12. **Audience-fit honest.** The bot serves the audience it can actually help; out-of-fit audiences get escalated quickly. + +The output of the framework is a chatbot that knows what it knows, grounds its answers in real knowledge, escalates appropriately, and earns trust by being honest about its scope. + +--- + +## Reference files + +- [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md) - When chatbots earn deployment and when they do not. The conditions that warrant the build. +- [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md) - Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. +- [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md) - Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. +- [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md) - How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. +- [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md) - What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. +- [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md) - When, how, with what context. Escalation triggers and handoff quality. +- [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md) - Per-intent metrics. Diagnostic uses. The data that informs maintenance. +- [`references/chatbot-anti-patterns.md`](references/chatbot-anti-patterns.md) - The patterns that look like chatbots but degrade trust. +- [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: chatbots earn deployment when they know what they don't know + +The chatbots that work as compounding assets are the ones the audience trusts. Not because they answer every question. Not because they are infinitely capable. Because they are honest about their scope, ground their answers in real knowledge, and escalate to humans when the bot's job is done. + +That is the bar. Below the bar are scripted-bots (rigid trees that fail edge cases) and hallucinating-bots (LLMs without structure that make things up). Above the bar are structured-guided-conversations where the bot's intent architecture, knowledge-base grounding, fallback discipline, and escalation patterns combine into a tool the audience can rely on. + +The discipline is in the design choices. The intents that define what the bot can do. The knowledge-base grounding that prevents hallucination. The fallback patterns that handle the unknown gracefully. The escalation logic that knows when to step aside. The analytics that surface what is working and what is not. The maintenance discipline that keeps the bot in sync with the brand it represents. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md b/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md new file mode 100644 index 0000000..7ca9f24 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md @@ -0,0 +1,269 @@ +# Branching and conditional logic + +How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. + +The bot's conversation can branch based on user inputs. Branching makes the conversation feel adaptive; over-branching makes it feel labyrinthine. + +--- + +## The adaptive principle + +The bot adapts the conversation to the user's situation. Branching is the mechanism. + +**The win.** A user asks about pricing; the bot recognizes the user is on the enterprise track (from earlier inputs or context); the response includes enterprise-specific information rather than starter-tier information. + +**The fail (no branching).** Every user gets the same response regardless of context. The pricing question gets a generic answer that helps no one specifically. + +**The fail (over-branching).** The conversation branches at every turn; the user feels stuck in a labyrinth; resolution recedes. + +The discipline. Branch when branching adds value. Avoid branching when it adds friction. + +--- + +## Pattern A: Intent-driven branching + +Different intents lead to different conversation flows. + +**How it works.** + +- The bot recognizes the user's intent. +- The conversation flow for that intent kicks in. +- Each intent has its own scripted or templated response pattern. + +**Example.** + +User: "How much does the Pro plan cost?" +Bot recognizes "pricing question" intent. +Bot routes to pricing-conversation flow: +- Retrieves pricing. +- Presents Pro plan pricing. +- Offers follow-up: "Would you like to compare with other tiers, or talk to sales for a custom quote?" + +**Strengths.** + +- Each intent gets a dedicated, optimized flow. +- Easy to maintain (changes to one intent do not affect others). + +**Weaknesses.** + +- Requires intent recognition to work reliably. +- Cross-intent topics may not fit any single flow. + +**When to use.** Default for most chatbots. Intent-driven branching is the foundation. + +--- + +## Pattern B: Context-driven branching + +Branching within an intent based on context. + +**How it works.** + +- Within an intent's flow, the bot asks clarifying questions or branches based on context. +- "Are you asking about plan A or plan B?" routes the rest of the conversation to plan-specific information. + +**Example.** + +User: "How does the API work?" +Bot recognizes "integration question" intent. +Within the integration flow, the bot asks: "Are you looking at REST or GraphQL?" +User: "REST." +Bot routes to REST-specific information. + +**Strengths.** + +- Within-intent precision. +- The user feels heard; the response addresses their specific situation. + +**Weaknesses.** + +- Each clarifying question adds a turn; can frustrate users who want quick answers. + +**The discipline.** Use context-driven branching only when the context genuinely affects the response. Decorative clarifications add friction. + +--- + +## Pattern C: User-attribute branching + +Branching based on user attributes (logged-in status, role, segment). + +**How it works.** + +- The bot accesses user attributes (often from a CRM or session data). +- Responses adapt to those attributes. +- "Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB." + +**Example.** + +User: "Tell me about your pricing." +Bot detects the user is from a domain associated with an enterprise account. +Bot routes to enterprise-specific pricing conversation: "For teams of 200+, we offer a custom Enterprise plan. Here are the typical components..." + +**Strengths.** + +- Highly personalized. +- The right information for the right audience. + +**Weaknesses.** + +- Requires attribute infrastructure (CRM integration, session data). +- Privacy considerations (the bot is using data the user may not have explicitly shared). +- Risk of getting attributes wrong (a freelancer with a corporate domain treated as enterprise). + +**When to use.** When the attribute infrastructure exists and the personalization genuinely improves the experience. + +--- + +## Pattern D: Multi-turn branching + +The conversation deepens over turns. Later turns build on earlier context. + +**How it works.** + +- The bot maintains conversation state across turns. +- Each turn's response considers what was said in previous turns. +- The conversation can pivot, deepen, or refocus based on the cumulative context. + +**Example.** + +Turn 1. +User: "I am evaluating CRMs." +Bot: "What size is your team?" +User: "We have 25 sales reps." + +Turn 2. +Bot: "For a team of 25, our Growth plan often fits. Are you looking at any specific features?" +User: "We need integration with HubSpot." + +Turn 3. +Bot: "Our HubSpot integration supports two-way sync, lead routing, and custom fields. Would you like to see a demo focused on this integration?" + +The conversation deepens. Each turn builds on the previous. + +**Strengths.** + +- Conversation feels natural. +- Bot can handle complex inquiries that require multiple inputs. + +**Weaknesses.** + +- Conversation state management is complex. +- Long conversations risk losing context. +- Users may want resolution faster than multi-turn allows. + +**The discipline.** Limit multi-turn conversations to 3-5 turns before either resolving, escalating, or offering a summary handoff. Beyond that, users abandon. + +--- + +## Branching depth limits + +Bots that branch too deeply lose users. + +**The 3-5 turn principle.** Most users want resolution within 3-5 turns. Beyond that, the bot's value declines. + +**When 3-5 turns is enough.** Most marketing-site Q&A, simple support, qualification. + +**When more turns are needed.** Complex troubleshooting, detailed product configuration. In these cases, the bot should consider escalating to a human or offering a richer interface (form, video walkthrough). + +**Branching as turn-cost.** Each branch adds a turn. Branches that do not resolve within the turn budget should be reconsidered. + +--- + +## Branching design patterns + +How to structure branches. + +**Linear branching.** A then B then C. Simple; fits intent-driven patterns. + +**Tree branching.** A leads to B or C; each leads to further options. Common; fits context-driven and user-attribute patterns. + +**Loop-back branching.** Conversation can return to earlier turns. Useful when users want to compare options. + +**Open-ended branching.** Conversation can take multiple paths from any point. Most flexible; hardest to maintain. + +The choice depends on conversation complexity. Most chatbots benefit from tree branching with limited depth. + +--- + +## Branching and brand voice + +The bot's voice should stay consistent across branches. + +**The principle.** Branching changes the conversation's content; the brand voice stays consistent. + +**Voice failures across branches.** + +- One intent's flow is formal; another is casual. Inconsistent. +- Bot voice shifts based on user attributes in ways that feel performative. +- Branches that adopt different personas confuse the user. + +The discipline. Voice consistent; content adaptive. + +--- + +## Conversation state management + +What the bot remembers across turns. + +**Within-conversation state.** + +- Recognized intent and sub-intent. +- Captured user inputs (company size, role, specific interests). +- Conversation history. +- Pending follow-up actions. + +**Across-conversation state.** When the user returns later (in the same session or a new session), what does the bot remember? + +- Logged-in users: bot may remember previous conversations. +- Anonymous users: bot typically starts fresh; some implementations use cookies for limited memory. +- Privacy considerations: cross-session memory should be transparent and opt-in where appropriate. + +The discipline. State management should serve the user. State that improves the experience is good; state that surprises or feels invasive is bad. + +--- + +## Branching testing + +Test the bot across branching paths. + +**The challenge.** A bot with multiple branching points has many paths through any given conversation. Testing all paths is infeasible; testing critical paths is the discipline. + +**Critical paths.** + +- The most common conversation patterns (most-frequent intents). +- Each major branch point (one path that takes each branch). +- Edge cases (unusual user inputs that could break branching). + +**Testing methods.** + +- Manual testing of critical paths. +- Automated testing where feasible. +- Sampling production conversations to verify branching behavior. + +--- + +## Common branching failures + +**Decorative branching.** Clarifying questions that do not change the response; user feels stuck. + +**Branching without resolution.** Conversation branches but never resolves; user gives up. + +**Branching depth too deep.** 8+ turns without resolution; user abandons. + +**Inconsistent voice across branches.** Different intents speak differently. + +**State loss across turns.** Bot forgets earlier context; conversation feels disjointed. + +**Privacy-violating attribute branching.** Bot uses attributes the user did not consent to share. + +**Untested edge-case branches.** Specific paths break in production. + +--- + +## Methodology-level choices that stay in the public skill + +The adaptive principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Branching depth limits. Branching design patterns. Branching and brand voice. Conversation state management. Branching testing. Common failures. + +## Implementation choices that stay internal + +Specific branching designs for specific bots. Specific state management implementations. Specific tooling for branching and testing. The team's testing protocols. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md new file mode 100644 index 0000000..52d7dda --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md @@ -0,0 +1,224 @@ +# Chatbot anti-patterns + +The patterns that look like chatbots but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The scripted-bot + +The pattern. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. + +The signal. Users complain the bot is rigid; bot fails any conversation that does not match the predefined paths. + +The cost. The user's actual question goes unanswered. The bot pushes the user through paths that do not fit. Audience leaves with a worse experience than no bot. + +The cure. Move from rigid trees to LLM-powered intent recognition with grounded responses. Detail in `references/intent-architecture-patterns.md` and `references/knowledge-base-grounding-patterns.md`. + +--- + +## The hallucinating-bot + +The pattern. LLM-powered with no structure. Confidently answers questions about pricing, policy, capabilities, and frequently makes up answers. + +The signal. Customer complaints about wrong information from the bot; sales or support hearing audiences cite incorrect bot answers. + +The cost. Liability risk. Trust damage. Support burden when wrong answers reach customers. + +The cure. Add intent architecture and knowledge-base grounding. The bot retrieves from sources-of-truth rather than generating from training data. + +--- + +## The bot-that-tries-to-handle-everything + +The pattern. Bot scope is "anything the user asks." No defined intents; no fallback discipline. + +The signal. High hallucination rate; high resolution-rate variability across topics; users get inconsistent experiences. + +The cost. The bot is unreliable. Some conversations work; many do not. Users cannot predict what they will get. + +The cure. Define explicit intent scope. Honest fallback for everything outside scope. Detail in `references/intent-architecture-patterns.md`. + +--- + +## The bot-that-handles-nothing + +The pattern. Bot's intent set is so narrow that most conversations fall to fallback or escalation. + +The signal. High fallback rate; high escalation rate; bot adds little value over a contact form. + +The cost. The build cost was significant; the value delivered is small. + +The cure. Expand the intent set to cover the conversations the audience actually has. Detail in `references/intent-architecture-patterns.md` (intent coverage section). + +--- + +## The bot-that-loops + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. Detail in `references/fallback-pattern-design.md` (fallback loop section). + +--- + +## The bot-that-refuses-rigidly + +The pattern. Bot says "I cannot help with that" without offering paths forward. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer alternatives. Resource handoff or human escalation. The bot's "I cannot help" should be followed by "but here is what might." + +--- + +## The bot-with-no-escalation + +The pattern. Bot tries to handle everything itself; rarely escalates; users get stuck with bot for conversations needing humans. + +The signal. Specific intents have high abandonment; users complaining they could not reach a human; sensitive topics handled poorly by the bot. + +The cost. The user's frustration compounds. The brand earns "you cannot reach a human" reputation. + +The cure. Define escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## The bot-that-escalates-everything + +The pattern. Bot escalates almost every conversation; the bot is not really doing its job. + +The signal. Escalation rate near 100 percent; bot adds friction without value. + +The cost. The bot is decorative. The team built a chatbot when they needed staffing. + +The cure. Either expand the bot's intent handling capability or reconsider whether the chatbot is the right tool. Sometimes the answer is to invest in human chat instead. + +--- + +## The bot-with-broken-handoff + +The pattern. Bot escalates; human picks up; the human starts from scratch because the context was not passed. + +The signal. Users complain about repeating themselves; humans report not knowing what the bot was discussing. + +The cost. The escalation experience is broken. Users feel the bot was wasted effort. + +The cure. Test the handoff. Ensure the human sees the conversation history and recognized intent. Detail in `references/escalation-to-human-patterns.md` (context handoff section). + +--- + +## The bot-with-stale-knowledge + +The pattern. Knowledge base not updated; bot answers reflect outdated reality. + +The signal. Bot answers contradict current product; users notice; sales hears about wrong information. + +The cost. Trust damage. Each wrong answer is a moment the brand lost credibility. + +The cure. Knowledge-base maintenance discipline. Quarterly review at minimum. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## The bot-with-no-citation + +The pattern. Bot generates answers without citing sources. Users cannot verify. + +The signal. Hallucination goes undetected because there is no verification path; users with deeper questions abandon because they cannot follow up. + +The cost. Trust does not compound. Each answer is taken on faith; some are wrong. + +The cure. Citation discipline. Bot cites sources; users can verify. Detail in `references/knowledge-base-grounding-patterns.md` (citation discipline section). + +--- + +## The bot-with-inconsistent-voice + +The pattern. Different intents speak in different voices. Bot voice does not match brand voice elsewhere. + +The signal. Users report the bot feels disjointed; brand voice is fragmented. + +The cost. Brand consistency suffers. The bot is a brand surface that is undermining the brand. + +The cure. Brand voice document including bot examples. Test conversations across intents. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The bot-with-no-analytics + +The pattern. Bot launched without per-intent tracking. Quality is invisible. + +The signal. Cannot diagnose issues; cannot track decay; remediation is guesswork. + +The cost. Quality decays unnoticed. Maintenance happens only when customers complain (too late). + +The cure. Instrument before launch. Per-intent recognition, resolution, fallback, escalation rates. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## The bot-that-pretends-to-be-human + +The pattern. Bot does not disclose it is a bot; users think they are talking to a human. + +The signal. Users feel deceived when they realize; complaints about hidden automation; trust collapse. + +The cost. Trust damage that can be hard to recover. Brand earns "deceptive" descriptors. + +The cure. Disclose that the user is talking to a bot. Modern AI chatbots can be disclosed openly without losing engagement; users often appreciate the honesty. + +--- + +## The bot-with-mobile-broken-UI + +The pattern. Bot works on desktop; UI breaks on mobile. Conversation cramped; input field hidden; responses overflow. + +The signal. Mobile conversation completion is significantly lower than desktop. + +The cost. Mobile audience underserved. Mobile is often the majority of traffic. + +The cure. Mobile-first chatbot UI design. Test on actual devices. + +--- + +## The bot-without-availability-disclosure + +The pattern. Bot escalates to humans without communicating that humans may not be available. + +The signal. Users wait indefinitely for a human; abandonment after escalation; frustration. + +The cost. Escalation creates expectation that is not met. Worse than no escalation. + +The cure. Communicate availability honestly. "Our team is available [hours]." Or offer async alternatives. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active bot, looking specifically for these anti-patterns. + +**Audit questions per bot.** + +- Does the bot have explicit intents (anti-pattern check: bot-that-tries-to-handle-everything, hallucinating-bot)? +- Are responses grounded in source-of-truth (anti-pattern check: hallucinating-bot, bot-with-no-citation)? +- Does fallback have multiple layers including escalation (anti-pattern check: bot-with-no-escalation, bot-that-loops)? +- Does escalation pass context (anti-pattern check: bot-with-broken-handoff)? +- Is the knowledge base maintained (anti-pattern check: bot-with-stale-knowledge)? +- Is brand voice consistent across intents (anti-pattern check: bot-with-inconsistent-voice)? +- Are analytics in place (anti-pattern check: bot-with-no-analytics)? +- Does the bot disclose its nature and human availability (anti-pattern check: bot-that-pretends-to-be-human, bot-without-availability-disclosure)? + +**The retire decision.** Anti-pattern bots often warrant retirement or significant redesign. Patching anti-patterns rarely produces a good bot. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md new file mode 100644 index 0000000..501d77a --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md @@ -0,0 +1,163 @@ +# Chatbot decision criteria + +When chatbots earn deployment and when they do not. The conditions that warrant the build, and the funnels where a chatbot adds friction without lift. + +A chatbot is a meaningful build. Intent architecture, knowledge-base grounding, fallback patterns, escalation logic, ongoing maintenance. The chatbot earns this investment only when specific conditions are present. + +--- + +## When chatbots earn deployment + +Five conditions that, when present, make a chatbot a strong investment. + +**The audience asks the same questions repeatedly.** FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. Without recurring question patterns, the bot has nothing to handle reliably. + +**The audience is on the site at hours when humans cannot respond.** Coverage gap that the bot fills meaningfully. Off-hours visitors get something instead of nothing. + +**The bot can ground its answers in real knowledge.** Documentation, product specs, pricing pages, support articles. Without grounding, the bot's answers are at best generic and at worst fabricated. + +**The team can maintain the bot.** Intents drift; knowledge bases need updating; conversation patterns shift. Without maintenance commitment, the bot becomes stale liability. + +**The success metric is defined.** Resolution rate, fallback rate, escalation rate, user satisfaction, downstream conversion. Without the success metric defined, evaluation is impossible. + +When all five are present, the chatbot is a strong investment. When two or fewer are present, a different channel (human chat, structured FAQ, contact form) often serves better. + +--- + +## When chatbots do NOT earn deployment + +Funnels where the chatbot is the wrong tool. + +**The audience expects human conversation.** Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. A chatbot in these contexts may be perceived as an obstacle to the human conversation the audience wants. + +**The team cannot ground the bot in real knowledge.** A bot without grounding either hallucinates (confident wrong answers) or stays so generic it adds no value (vague responses to specific questions). + +**The bot would replace working human channels.** Replacing a high-quality sales chat with a low-quality bot degrades the experience. The bot might be cheaper to operate but more expensive in lost conversions. + +**The audience is small enough that direct human conversation is more efficient.** Niche audiences with low conversation volume often work better with human-first channels; the chatbot's overhead is not justified. + +**The team cannot maintain the bot.** Stale bots produce wrong answers. Without quarterly maintenance commitment, the bot becomes a liability over time. + +**The conversation pattern is too varied to model.** Some audiences ask wildly different questions; the intent architecture cannot meaningfully cover the conversation space; the bot mostly fallbacks anyway. + +The honest assessment matters more than the default. "Should we have a chatbot" is not the question. "Is the chatbot the right tool for this audience and conversation pattern" is. + +--- + +## The opportunity-cost frame + +A chatbot is significant work. Account for the cost honestly. + +**The build cost.** Intent architecture, knowledge-base preparation, RAG pipeline, fallback design, escalation logic, conversation UI, brand-voice tuning, mobile responsiveness, analytics instrumentation. A meaningful chatbot often takes 80-300 engineering hours plus design and content for the knowledge base. + +**The maintenance cost.** Knowledge base updates, intent refinement, hallucination detection, conversation analytics review. Quarterly maintenance often runs 8-20 hours per active bot. + +**The escalation infrastructure cost.** Human handoff requires staffing or routing infrastructure. The bot does not eliminate the need for humans; it changes when humans are involved. + +**The opportunity cost.** What else could the team have built? A better support documentation site, a self-serve help center, a different growth-tooling investment. The chatbot's success has to clear the bar of those alternatives. + +The decision frame. The chatbot earns investment when it produces more value than the alternatives, accounting for build plus maintenance plus escalation infrastructure. + +--- + +## The grounding precondition + +Without knowledge-base grounding, the chatbot is the wrong tool. + +**The check.** Does the team have or can the team build a knowledge base that covers the conversation patterns the bot will handle? + +If yes, the chatbot can be grounded. The bot's responses retrieve from the knowledge base; hallucination risk is contained. + +If no (the team's knowledge is in people's heads, not documented), the chatbot will hallucinate or stay generic. The bot is the wrong tool until the knowledge base exists. + +**Building the knowledge base.** Sometimes the right move is to build the knowledge base first (which itself is valuable as documentation) before deploying the bot. The knowledge base serves users directly even before the bot accesses it. + +--- + +## The decision worked example + +A B2B SaaS company considering a chatbot for the marketing site. + +**Conditions check.** + +- Recurring questions: yes. Visitors ask about pricing, integrations, security, and demo requests recurringly. +- Off-hours coverage gap: yes. The team handles US business hours; international visitors get nothing in their evening hours. +- Knowledge-base grounding possible: yes. Pricing, integrations, security details all documented; FAQ exists; product specs are detailed. +- Maintenance commitment: yes. Marketing operations has capacity for quarterly bot review. +- Success metric defined: yes. Resolution rate per intent, escalation rate, downstream conversion to demo within 14 days. + +**Decision.** Build the chatbot. The conditions warrant it. + +**Intent architecture.** 7 named intents: pricing, integrations, security, demo request, support escalation, integration troubleshooting, account access. + +**Knowledge-base grounding.** RAG pipeline pulling from docs, pricing page, security page, integration catalog. + +**Fallback strategy.** Clarification on first unclear; suggested intents on second unclear; escalation to human on third or sentiment-driven. + +**Escalation handoff.** Bot passes conversation history and recognized intent to the human; the human picks up where the bot left off. + +The decision was not "should we have a chatbot" but "given these conditions, this is the chatbot to build." + +--- + +## The decision worked example: when to choose differently + +The same company considering a chatbot for sales conversations. + +**Conditions check.** + +- Recurring questions: partially. Sales conversations vary widely; while some patterns recur, the conversation often needs nuance. +- Off-hours coverage: not relevant; sales conversations work async via demo bookings already. +- Knowledge-base grounding possible: yes for product info; less so for personalized recommendations. +- Maintenance commitment: yes. +- Success metric: hard to define. Sales conversion is the goal; the bot's contribution is hard to attribute. + +**Decision.** Do not build a sales-focused chatbot. The audience expects human sales conversation; the bot would add friction. Use the bot for marketing-site Q&A and demo qualification; route demo requests to human sales. + +The decision was "is this chatbot right for this conversation" and the answer was "for some conversations yes, for others no." The bot's scope was constrained accordingly. + +--- + +## The audience-fit precondition + +The chatbot's audience must be willing to interact with chatbots. + +**Audiences that engage with chatbots well.** + +- Self-service-oriented users who want quick answers without human contact. +- Off-hours visitors who would otherwise get nothing. +- Users with specific factual questions (pricing, hours, policies). + +**Audiences that resist chatbots.** + +- Users who explicitly want to talk to a human (often signaled in the conversation opening). +- Sales-focused enterprise buyers expecting white-glove human attention. +- Users in distress (frustration, urgency) who need empathy not automation. + +**The discipline.** The chatbot should serve the audiences who engage well and escalate the audiences who do not. Trying to serve everyone with the bot fails both groups. + +--- + +## When to retire a chatbot + +Chatbots can be wrong even after being right initially. + +**Retire when:** + +- Resolution rate has dropped below an acceptable threshold consistently. +- Escalation rate climbs as intents fail to keep pace with audience evolution. +- The knowledge base maintenance burden exceeds the bot's value. +- A redesigned support model (better docs, expanded human team, different tooling) makes the bot unnecessary. +- The team can no longer commit to maintenance. + +The retiring discipline is part of the program. Stale bots produce wrong answers; honest retirement protects the brand. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant chatbot deployment. The conditions that argue against. The opportunity-cost frame. The grounding precondition. The audience-fit precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific chatbot scope decisions for specific audiences. The team's capacity benchmarks. Specific tooling for chatbot platforms, RAG pipelines, and analytics. Specific success-metric baselines. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md b/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md new file mode 100644 index 0000000..35d1c67 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md @@ -0,0 +1,187 @@ +# Common chatbot failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the bot is hallucinating" or "users complain the bot is unhelpful" or "we cannot tell what the bot is doing." + +--- + +## "Bot makes up answers about pricing." + +**The diagnosis.** Hallucinating-bot pattern. No grounding to pricing source-of-truth. + +**The cure.** Add knowledge-base grounding for pricing. The bot retrieves from the pricing page or pricing knowledge base; answers reflect the source. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## "Users say the bot is rigid and unhelpful." + +**The diagnosis.** Scripted-bot pattern. Intents do not cover real questions; bot fails when users phrase things unexpectedly. + +**The cure.** Move from rigid trees to LLM-powered intent recognition. Define more flexible intents. Add fallback that handles unexpected phrasings. Detail in `references/intent-architecture-patterns.md`. + +--- + +## "Sales is angry that the bot is qualifying leads wrong." + +**The diagnosis.** Intent recognition or routing logic broken. The bot is recognizing leads as one type when they should be another. + +**The cure.** Audit the qualification flow. Verify intent recognition with realistic test cases. Tighten routing logic. Add human review for edge cases. + +--- + +## "Support tickets increase after chatbot launch." + +**The diagnosis.** Bot is producing wrong answers that send users to support after the fact. Worse than no bot. + +**The cure.** Audit grounding and resolution. Identify the intents producing bad answers. Either improve grounding or escalate those intents to humans. Detail in `references/knowledge-base-grounding-patterns.md` and `references/escalation-to-human-patterns.md`. + +--- + +## "Users abandon mid-conversation." + +**The diagnosis.** Bot loops or fallback patterns are inadequate. Users get stuck without resolution path. + +**The cure.** Review fallback patterns. Limit clarification rounds. Add multi-layered fallback ending in human escalation. Detail in `references/fallback-pattern-design.md`. + +--- + +## "We cannot tell what the bot is actually doing." + +**The diagnosis.** Analytics missing. Without instrumentation, quality is invisible. + +**The cure.** Instrument per-intent recognition, resolution, fallback, and escalation rates before any further changes. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot was great at launch; quality has degraded." + +**The diagnosis.** Maintenance lapse. Knowledge base or intent set out of date. + +**The cure.** Quarterly maintenance review. Update knowledge base; refine intents; verify grounding. Set the maintenance trigger so updates happen alongside product changes. + +--- + +## "Bot escalates to humans for everything." + +**The diagnosis.** Escalation logic too permissive, or the bot's intent handling is so weak that everything ends up at humans. + +**The cure.** Audit which intents escalate most. If the bot can handle them with better grounding, fix that. If the bot truly cannot handle them, reconsider whether they should be in scope. + +--- + +## "Bot tries to handle everything itself." + +**The diagnosis.** Escalation logic too restrictive. Bot stays with conversations it should not. + +**The cure.** Add escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Users complain the bot does not know what they asked five minutes ago." + +**The diagnosis.** Conversation context not preserved across turns. Bot treats each message as standalone. + +**The cure.** Implement conversation state management. Bot remembers earlier turns within the same conversation; later responses build on that context. Detail in `references/branching-and-conditional-logic.md` (conversation state management section). + +--- + +## "Bot gives different answers to the same question." + +**The diagnosis.** Either grounding is inconsistent (different retrievals for similar queries), or the LLM generation has variability that produces different answers. + +**The cure.** Review grounding pipeline. Verify retrieval consistency. Tune generation parameters for consistency. Audit specific cases. + +--- + +## "We tried the bot in our pricing page; conversion went down." + +**The diagnosis.** Bot may be adding friction to a flow that worked. Some pages benefit from chatbots; some do not. + +**The cure.** A/B test bot presence vs absence on the affected pages. The data informs whether the bot is the right tool there. + +--- + +## "Bot ignores the user when sentiment is negative." + +**The diagnosis.** No sentiment-driven escalation. Bot continues handling conversations where the user is frustrated. + +**The cure.** Add sentiment-driven escalation. Recognize frustration signals; escalate to human. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Sales team finds qualification bot data unreliable." + +**The diagnosis.** Bot's qualification logic does not match sales-team criteria, or recognition is misclassifying leads. + +**The cure.** Align bot qualification with sales criteria. Audit recognition with sales feedback. Update intents and routing. + +--- + +## "We added a chatbot; our overall site conversion dropped." + +**The diagnosis.** Bot may be displacing higher-converting paths (direct CTAs, contact forms). Bot is the wrong tool for this audience or page. + +**The cure.** A/B test bot presence vs absence at the funnel level. If the bot reduces conversion, reconsider its placement or scope. + +--- + +## "Bot answers correctly but conversation never closes." + +**The diagnosis.** No clear conversation-end pattern. Bot keeps offering more help; user does not know when to stop. + +**The cure.** Add explicit conversation closing. "Anything else I can help with?" "If not, [next step option]." Detail in fallback patterns. + +--- + +## "We migrated platforms; the bot quality dropped." + +**The diagnosis.** Platform migration may have broken intent recognition, knowledge base integration, or escalation routing. + +**The cure.** Test the migrated bot end-to-end before declaring it ready. Critical paths first. Roll back if quality dropped significantly. + +--- + +## "Mobile conversations end with no resolution." + +**The diagnosis.** Mobile UI may be breaking; or the bot's responses may be too long for mobile screens. + +**The cure.** Mobile UI testing. Audit response lengths. Mobile-specific UI adjustments. + +--- + +## "We cannot tell which intents need work." + +**The diagnosis.** Analytics aggregated rather than per-intent. The intent-level signal is hidden. + +**The cure.** Per-intent analytics. Recognition rate, resolution rate, escalation rate, hallucination rate per intent. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot's voice does not sound like our brand." + +**The diagnosis.** Bot is using generic LLM voice; brand voice was not specifically tuned. + +**The cure.** Brand voice document including bot examples. Tune bot prompts and response patterns to match. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The pattern across failures + +Most chatbot failures fall into one of three patterns. + +**Pattern 1: The bot does not have proper architecture.** Hallucinating, scripted, no grounding, no fallback discipline. The fix is structural. + +**Pattern 2: The bot does not match the audience or context.** Bot in wrong context, wrong voice, wrong scope for audience. The fix is matching the bot to where it serves. + +**Pattern 3: The bot decays.** Knowledge base stale, intent set frozen, no maintenance. The fix is maintenance discipline. + +The metric pattern: chatbot failures often look fine on conversation count alone. The signal is in resolution rate per intent, hallucination rate, escalation quality, downstream conversion. Programs that track only conversation counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (architecture, audience-context match, decay). The principle that conversation count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md new file mode 100644 index 0000000..5775305 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md @@ -0,0 +1,272 @@ +# Conversation analytics patterns + +Per-intent metrics. Diagnostic uses. The data that informs maintenance. + +Conversation analytics is the bot's diagnostic system. Without analytics, maintenance is guesswork; intent gaps go unnoticed; hallucination patterns persist; the bot's quality decays without anyone seeing the decay. + +--- + +## The instrumentation principle + +Track the bot's performance per intent, per fallback, per escalation. The data informs every maintenance decision. + +**The minimum tracking.** + +- Conversation start (a user opens the bot). +- Intent recognition (which intent the bot classified). +- Conversation outcome (resolved, fallback, escalation, abandoned). +- Per-turn data (each user message, each bot response). + +**The derived metrics.** + +- Intent recognition rate. +- Resolution rate per intent. +- Fallback rate. +- Escalation rate per intent. +- Abandonment rate. + +Without instrumentation, none of this data exists. Set up tracking before launch. + +--- + +## Intent recognition rate + +What percentage of conversations are correctly classified. + +**The metric.** Of conversations where the user expressed intent, what percentage did the bot recognize correctly? + +**Measurement methods.** + +- **Sample auditing.** Periodically sample conversations and verify intent classification manually. +- **User feedback signals.** Conversations where users complain or escalate often correlate with misrecognized intent. +- **Conversation outcome correlation.** Conversations resolved successfully often had correct intent recognition. + +**Diagnostic uses.** + +- Low recognition rate: intent set may not cover real conversations; recognition logic may be brittle. +- Specific intents misrecognized: those intents may be poorly defined or overlap with others. + +**Target ranges.** 80-90 percent recognition is achievable for well-designed chatbots. Below 70 percent suggests significant intent or recognition issues. + +--- + +## Resolution rate per intent + +What percentage of conversations starting with intent X resolve successfully. + +**Resolution definition.** The user got the answer they needed and the conversation ended successfully (no escalation, no abandonment, no follow-up indicating frustration). + +**Measurement methods.** + +- **Conversation completion plus user signal.** User explicitly says "thanks" or rates the conversation positively. +- **No follow-up issues.** User does not return with the same question or escalate later. +- **Direct survey.** Post-conversation survey asking if the user got what they needed. + +**Diagnostic uses.** + +- Low resolution per intent: the bot's grounding or response pattern for that intent is weak. +- Some intents have higher resolution than others: variation may signal intent design quality differences. + +**Target ranges.** 70-85 percent resolution per intent is reasonable. Lower for complex intents; higher for simple intents. + +--- + +## Fallback rate + +What percentage of conversations hit fallback at any point. + +**The metric.** Conversations where the bot's intent recognition failed or the bot's response did not address the user's need, requiring fallback. + +**Diagnostic uses.** + +- High fallback rate (above 25-30 percent): intent set may be missing common conversations. +- Specific fallback layers triggered disproportionately: that layer needs review. +- Fallback rate trending up: audience evolving away from current intent set. + +**Per-layer breakdown.** Track which fallback layers (clarification, suggested intents, resource handoff, human escalation) trigger most. Each tells a different story. + +--- + +## Escalation rate per intent + +What percentage of conversations within each intent escalate to humans. + +**The metric.** Of conversations classified as intent X, what percentage ended with human escalation? + +**Diagnostic uses.** + +- High escalation rate per intent: the intent may not be appropriate for bot handling; consider removing from bot scope. +- Low escalation rate per intent: bot may be over-handling; some conversations may benefit from earlier escalation. +- Specific intents with rising escalation: maintenance lapse or audience evolution. + +**The 100-percent-escalation intent.** An intent where the bot always escalates is not a bot intent; it should be a "tell me about [topic]; we will get back to you" intent or removed entirely. + +--- + +## Abandonment rate + +What percentage of conversations end without resolution or escalation (the user just leaves). + +**The metric.** Conversations where the user stops responding without indicating resolution. + +**Diagnostic uses.** + +- High abandonment: bot is failing to satisfy users; review fallback patterns and conversation flows. +- Abandonment concentrated at specific turn or intent: that point in the flow is breaking. +- Mid-conversation abandonment vs first-turn abandonment: different diagnostic implications. + +--- + +## User satisfaction + +When measurable, satisfaction is the highest-value metric. + +**Measurement methods.** + +- **Post-conversation rating.** "How was that conversation?" with 1-5 stars or thumbs up/down. +- **Post-conversation survey.** Brief survey after the conversation ends. +- **Sentiment analysis.** Programmatic analysis of conversation sentiment. + +**Diagnostic uses.** + +- Low satisfaction: bot is failing the user even when conversations technically complete. +- Satisfaction-resolution mismatch: bot resolves but users are unhappy; quality of resolution is poor. + +**Limitations.** + +- Many users do not respond to satisfaction surveys. +- Satisfaction can be biased (frustrated users more likely to respond than satisfied ones). +- Sentiment analysis can miss nuance. + +The metric is valuable but not the only signal. + +--- + +## Conversation length distribution + +How many turns the average conversation takes. + +**The metric.** Distribution of conversation turn count. + +**Diagnostic uses.** + +- Long average length: bot may be over-clarifying; conversations should resolve faster. +- Bimodal distribution (very short or very long): some conversations resolve quickly; others get stuck. +- Increasing trend: bot quality may be declining; users having to work harder. + +**Target ranges.** 2-5 turns for typical resolution. Longer for complex intents; shorter for simple ones. + +--- + +## Response time + +How quickly the bot responds. + +**The metric.** Time between user message and bot response. + +**Diagnostic uses.** + +- Slow response: user perceives the bot as sluggish; abandonment may climb. +- Variable response time: inconsistent experience; users unsure what to expect. + +**Target ranges.** Under 2 seconds for most responses. Longer responses (when retrieving or generating) should show typing indicators. + +--- + +## Hallucination tracking + +Specifically tracking when the bot generates wrong answers. + +**Detection methods.** + +- Sample auditing of bot responses against source-of-truth. +- User reports ("the bot said X; that is not right"). +- Citation verification (programmatic check that cited sources contain the cited content). + +**Diagnostic uses.** + +- Specific intents with hallucination rate: those intents need grounding review. +- Specific topics within intents: knowledge base may have gaps. +- Hallucination trend: if rate is rising, model or grounding may be drifting. + +**The honesty discipline.** Track hallucination explicitly. Teams that hide hallucination from themselves ship worse bots. + +--- + +## Conversation funnel + +Track conversations as a funnel from start to resolution. + +**The funnel.** + +- Conversation started. +- Intent recognized. +- First response delivered. +- User continued. +- Resolution achieved (or escalation, or abandonment). + +**Diagnostic uses.** Drop-off at each stage points to specific issues. + +- Drop-off after intent recognition: bot's first response is not engaging or is wrong. +- Drop-off mid-conversation: branching or follow-ups are not landing. +- Drop-off near resolution: closing or call-to-action is weak. + +--- + +## Per-segment analytics + +Different audience segments may experience the bot differently. + +**Segments.** + +- New visitors vs returning. +- Logged-in vs anonymous. +- Mobile vs desktop. +- Source of arrival (paid, organic, referral). + +**Diagnostic uses.** + +- Segments with worse outcomes signal segment-specific issues. +- Sometimes the right answer is segment-specific bot behavior. + +--- + +## Analytics review cadence + +How often to look at the data. + +**Weekly review.** For high-volume bots or recently launched bots. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable bots. Tracks trends and surfaces gradual decay. + +**Quarterly review.** For all active bots as part of the broader bot audit. + +**Triggered review.** When intent set changes, when knowledge base updates, when team escalation patterns shift. Ad-hoc reviews catch specific issues. + +--- + +## Common analytics failures + +**No instrumentation.** Bot launched without per-intent tracking; quality is invisible. + +**Vanity metrics.** Tracking conversation count without tracking outcome quality. + +**Aggregate-only tracking.** Conversation rate tracked but not per-intent; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; intent renames or schema changes broke the tracking. + +**Confounded data.** Multiple changes deployed simultaneously; cannot attribute changes to any one update. + +**No segment-level data.** Aggregate hides segment-specific issues. + +**No hallucination tracking.** Bot wrongness goes unnoticed until customers complain. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation principle. Intent recognition rate. Resolution rate per intent. Fallback rate. Escalation rate per intent. Abandonment rate. User satisfaction. Conversation length distribution. Response time. Hallucination tracking. Conversation funnel. Per-segment analytics. Analytics review cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific bots. Specific tooling for analytics implementation. Specific target ranges for the team's audience. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md new file mode 100644 index 0000000..429ba8d --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md @@ -0,0 +1,209 @@ +# Escalation to human patterns + +When, how, with what context. Escalation triggers and handoff quality. + +Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. Escalation done well preserves the conversation's momentum; escalation done poorly resets the user. + +--- + +## The escalation principle + +Escalation is part of the bot's job. A bot that knows when to step aside earns more trust than a bot that tries to handle everything. + +**The win.** The bot recognizes its scope is exceeded; escalates with the conversation context; the human picks up where the bot left off. + +**The fail (no escalation).** The bot tries to handle everything; produces wrong answers; the user has to start over with a human eventually. + +**The fail (broken escalation).** The bot escalates but the human starts from scratch; the user has to repeat everything. + +The discipline. Escalation triggers defined; context handoff clean. + +--- + +## Escalation triggers + +When the bot escalates. + +**User-initiated.** "Talk to a human." "I need to speak with someone." "Get me a person." + +The bot escalates immediately. Do not try to handle the request first; the user has been explicit. + +**Out-of-scope intent.** The bot recognizes the user's intent is outside its scope. + +The bot escalates with the intent context. "Looks like you have a [intent type] question; let me connect you with the team." + +**Repeated fallback.** After 2-3 unclear exchanges, the bot escalates rather than loop. + +The bot acknowledges: "I am having trouble understanding your question; let me get a human who can help." + +**Sentiment-driven.** The user's sentiment indicates frustration. + +The bot recognizes frustration signals (negative phrasing, repeated complaints, exclamation patterns) and escalates. + +**High-stakes topic.** Sensitive topics escalate by default. + +Account security, cancellations, complaints, signs of distress. The bot does not try to handle these; immediate escalation. + +**Complexity-driven.** The user's question requires deep customization or analysis the bot cannot provide. + +The bot acknowledges: "This needs a more detailed look; let me connect you with our team." + +--- + +## The context handoff + +When escalating, the bot passes context to the human. + +**What to pass.** + +- The conversation history (full transcript). +- The recognized intent (what the bot thought the user wanted). +- The user's situation (any captured attributes: company, role, source). +- The reason for escalation (user-initiated, out-of-scope, sentiment, etc.). +- Any pending follow-up actions. + +**The handoff format.** + +- Visible to the human in their tool of choice (CRM, support ticket system, chat panel). +- Structured so the human can scan it quickly. +- Accurate (the recognized intent matches what the user actually said). + +**The handoff failure.** The human picks up the conversation but does not see the context; they ask the user to repeat everything; the user feels the escalation was for nothing. + +The discipline. Test the handoff. The human should pick up the context smoothly. The user should feel the escalation moved them forward, not backward. + +--- + +## Escalation user experience + +What the user sees during escalation. + +**The pattern.** + +- Bot acknowledges the escalation: "Let me connect you with someone who can help." +- Bot provides expectation: "Someone from our team will be with you in [timeframe]." +- If the wait will be long, bot offers alternatives: "If you do not want to wait, you can [book a call / email us / submit a ticket]." +- Conversation transitions to human cleanly when the human joins. + +**The escalation-as-transition principle.** The user should feel the conversation continued, not started over. The transition from bot to human is part of the experience. + +--- + +## Escalation and human availability + +What happens when no human is available. + +**During business hours.** The bot escalates; a human picks up within the expected response time. + +**Off-hours.** The bot acknowledges: "Our team is available [hours]. I can take your information and have someone respond when they are back." + +**During high-volume.** The bot acknowledges the wait: "We are seeing high volume right now; expected wait is about [time]." + +**The honest framing.** The bot communicates availability honestly. Pretending humans are available when they are not creates frustrated users. + +**Asynchronous escalation.** When the user is willing, async escalation (email, ticket) is often better than waiting in chat. The bot can offer this option proactively. + +--- + +## Escalation routing + +Which human gets the conversation. + +**Routing patterns.** + +- **Single team.** All escalations go to one team (often support). Simple but may not match all conversation types. +- **Intent-based routing.** Different intents route to different teams (sales escalations to sales; support to support). +- **Tier-based routing.** Different user tiers route to different teams (enterprise to enterprise account managers; SMB to general support). +- **Context-based routing.** Routing combines intent, tier, and other attributes. + +**Routing failures.** + +- Wrong team gets the escalation; they have to re-route; user waits longer. +- Routing logic stale; teams have changed but the bot has not. +- Round-robin without consideration of expertise; users get inconsistent quality. + +**Routing maintenance.** Quarterly review of routing logic alongside team structure changes. + +--- + +## Escalation measurement + +Track escalation rate and quality. + +**Metrics.** + +- **Escalation rate.** What percentage of conversations escalate? +- **Escalation rate per intent.** Some intents may escalate more often than others. +- **Time-to-human-pickup.** How quickly does the human respond after escalation? +- **Resolution after escalation.** What percentage of escalated conversations resolve? +- **User satisfaction post-escalation.** When measurable. + +**Diagnostic uses.** + +- High escalation rate per intent: that intent may not be appropriate for bot handling. +- Long time-to-human: staffing or routing issues. +- Low resolution after escalation: handoff quality may be poor or the team may not have the resources. + +The data informs both bot maintenance and human team capacity planning. + +--- + +## Bot-to-human transition design + +The moment the human joins the conversation. + +**Pattern A: Visible transition.** The user sees a message: "Hi, I am [name] from the team. I see you were asking about [topic]; how can I help?" + +The transition is explicit; the user knows they are now with a human. + +**Pattern B: Continuous transition.** The conversation continues without explicit handoff; the bot's voice fades; the human's voice picks up. + +Less common; can confuse users about who they are talking to. + +**Pattern C: Bot stays available.** The bot remains in the conversation alongside the human; can be called on for specific information retrieval while the human leads. + +Useful for complex conversations; rare in simple chatbot deployments. + +**Pattern A is the default.** Explicit transitions reduce confusion. + +--- + +## Escalation back to bot + +Sometimes the conversation can return to the bot after a human handoff. + +**When this works.** The human resolves the immediate issue; the user has a follow-up question that is bot-handlable; the bot can pick back up. + +**When this fails.** The user expected human attention; returning to the bot feels like demotion. + +**The discipline.** Bot-after-human transitions need user consent. "Is there anything else? I can connect you with our chatbot for quick questions, or keep you with me." Let the user choose. + +--- + +## Common escalation failures + +**No escalation logic.** Bot tries to handle everything; produces wrong answers; users escalate to support after the fact (worse than escalating upfront). + +**Escalation without context handoff.** Human starts from scratch; user repeats everything. + +**Escalation to unavailable humans.** Bot creates expectation that is not met; user waits indefinitely or abandons. + +**Wrong-team routing.** Escalation goes to a team that cannot help; rerouting adds friction. + +**Sensitive topics not escalated.** Bot tries to handle account security, cancellations, complaints; makes things worse. + +**Escalation triggers too restrictive.** Bot rarely escalates; users get stuck. + +**Escalation triggers too permissive.** Bot escalates everything; the bot is not really doing its job. + +**No escalation user experience.** Transition to human is jarring; user is confused about whether they are still with the bot. + +--- + +## Methodology-level choices that stay in the public skill + +The escalation principle. Escalation triggers (6 patterns). Context handoff discipline. Escalation user experience. Escalation and human availability. Escalation routing. Escalation measurement. Bot-to-human transition design (3 patterns). Escalation back to bot. Common failures. + +## Implementation choices that stay internal + +Specific escalation routing for specific teams. Specific handoff formats and integration with CRM or support tools. Specific brand-voice transition copy. The team's staffing and SLA decisions. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md b/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md new file mode 100644 index 0000000..32163d1 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md @@ -0,0 +1,257 @@ +# Fallback pattern design + +What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. + +Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." Done well, fallback earns trust through honesty; done poorly, fallback frustrates users into abandonment. + +--- + +## The honesty principle + +A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers given confidently. + +**The win.** A user asks about a topic outside the bot's scope. The bot says "I cannot help with that, but [here is the right resource or human contact]." The user gets routed to value; the brand earns trust. + +**The fail (faked confidence).** The bot generates an answer from training data because it has no scope discipline. The answer is wrong; the user finds out later; the brand earns "lying bot" reputation. + +**The fail (rigid refusal).** The bot says "I cannot help with that" and offers no alternative. The user has nowhere to go. + +The discipline. Honest about limits; helpful about alternatives. + +--- + +## Multi-layered fallback + +Multiple fallback patterns, sequenced. + +**Layer 1: Clarifying question.** "Can you tell me more about what you are looking for?" + +When to use: when the user's intent is unclear and clarification might resolve. + +When it fails: when the user has already been clear; clarification feels patronizing. + +The discipline: ask clarification once, not repeatedly. + +**Layer 2: Suggested intents.** "I can help with X, Y, or Z. Were you asking about one of those?" + +When to use: when clarification did not work, or when the user asked something the bot can almost handle. + +When it fails: when the suggestions do not match what the user wanted. + +The discipline: suggest the bot's actual capabilities, not generic options. + +**Layer 3: Resource handoff.** "I cannot answer that, but here is our [documentation page] that covers it." + +When to use: when the bot cannot help but a self-serve resource exists. + +When it fails: when the resource is not actually relevant. + +The discipline: route to genuinely relevant resources; do not deflect to generic help. + +**Layer 4: Human escalation.** "Let me connect you with a human who can help." + +When to use: when self-serve will not work or the user has expressed frustration. + +When it fails: when no human is available; the escalation creates an expectation that does not get met. + +The discipline: escalate to humans only when humans are available; otherwise communicate the wait. + +--- + +## Layer sequencing + +The order matters. + +**Standard sequence.** + +1. Recognize intent. If recognized, handle. +2. If not recognized, try clarification (Layer 1). +3. If clarification fails, suggest intents (Layer 2). +4. If suggestions fail, offer resources (Layer 3). +5. If resources do not match, escalate (Layer 4). + +**Sequence variations.** + +- High-stakes topics may skip to Layer 4 immediately. +- User-initiated escalation ("talk to a human") goes to Layer 4 immediately. +- Frustrated sentiment may trigger Layer 4 sooner. + +--- + +## Anti-pattern: fallback loop + +Multiple clarification attempts that go nowhere. + +**The pattern.** Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again; loop. + +**The signal.** Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +**The cost.** The user feels stuck. The brand earns "frustrating bot" reputation. + +**The cure.** Limit clarification to one round. After that, escalate or offer alternatives. The bot's job is to resolve or hand off, not to keep asking the same question. + +--- + +## Anti-pattern: rigid refusal + +Bot says "I cannot help" and offers no path forward. + +**The pattern.** User asks something out of scope; bot says "I cannot help with that"; conversation ends. + +**The signal.** Users complain that the bot is unhelpful; abandonment. + +**The cost.** The bot fails the user without offering recovery. + +**The cure.** Always offer an alternative. Resource handoff or human escalation. The bot's "I cannot help" should be followed immediately by "but here is what might." + +--- + +## Fallback copy discipline + +What the fallback messages say. + +**Helpful fallback copy.** + +- "I am not sure I caught that. Are you asking about [option 1] or [option 2]?" +- "I can answer questions about pricing, integrations, or features. Was your question about one of those?" +- "I cannot answer that specifically. Our team can help; would you like me to connect you?" + +**Unhelpful fallback copy.** + +- "I do not understand." +- "Please rephrase." +- "Sorry, I cannot help with that." + +**The voice discipline.** Fallback copy should sound like the brand. Apologetic but not groveling; honest but not curt; helpful but not desperate. + +--- + +## Fallback for sensitive topics + +Some topics warrant immediate escalation regardless of bot capability. + +**Sensitive triggers.** + +- Account security ("my account was hacked," "I think I was charged wrong"). +- Cancellation ("I want to cancel my subscription"). +- Complaints ("I want to speak to a manager"). +- Crises (any indication of user distress). + +**The pattern.** The bot recognizes the sensitive topic and escalates immediately rather than attempting to handle. + +**Why this matters.** Sensitive topics need human empathy. A bot trying to handle them often makes things worse. Immediate escalation protects the user and the brand. + +--- + +## Fallback during human unavailability + +What happens when the user wants a human but no human is available. + +**The honest options.** + +- "Our team is available [hours]. Can I take a message they can respond to when they are back?" +- "We are not available right now. You can [submit a ticket / book a call / email us]." +- "I can help with [list of topics]; for [out-of-scope topic], please reach out to [channel] directly." + +**The dishonest option.** + +- Pretending a human is available when they are not. The user waits, gets frustrated, abandons. + +The discipline. Communicate availability honestly. Set the expectation upfront if humans cannot respond immediately. + +--- + +## Fallback measurement + +Track fallback rate as a key metric. + +**The metric.** What percentage of conversations hit fallback at any point? + +**Diagnostic uses.** + +- High fallback rate (above 25-30 percent): intents are missing or recognition is poor. +- Specific fallback layers triggered disproportionately: that layer needs design review. +- Fallback escalation rate (what percentage of fallbacks lead to human escalation): high rates may signal the bot is doing less than it should; low rates may signal users abandoning rather than escalating. + +**The fallback-as-signal principle.** Fallback is not failure; it is the bot honestly recognizing limits. The signal is in the fallback patterns and what they reveal about intent gaps. + +--- + +## Fallback maintenance + +Fallback decays. + +**What decays.** + +- Suggested intents that no longer reflect the bot's actual capabilities. +- Resource links that have moved or broken. +- Escalation routing that no longer matches the team structure. + +**Maintenance cadence.** Quarterly review of fallback messages, suggested intents, resource links, and escalation routing. + +**The drift indicator.** User feedback about unhelpful fallback responses; broken links in the fallback flow; escalations going to wrong teams. + +--- + +## Fallback and brand voice + +Fallback responses are an opportunity for brand voice. + +**The principle.** Fallback is when the bot is most likely to lose the user. Brand voice in fallback can recover the moment. + +**Voice in fallback.** + +- Acknowledge the limitation honestly. +- Maintain warmth (do not become cold or robotic when failing to help). +- Offer the path forward with the same voice as the rest of the conversation. + +**The voice failure.** Fallback messages that sound generic; bot loses voice exactly when voice matters most. + +--- + +## Fallback testing + +Test the fallback flow as carefully as the success flow. + +**Test cases.** + +- User asks something clearly out of scope. +- User asks something on the edge of scope. +- User asks something within scope but phrased unusually. +- User explicitly asks for a human. +- User shows frustration in their messages. +- User asks during off-hours. + +**The testing discipline.** Each fallback layer should be tested with realistic triggers. + +--- + +## Common fallback failures + +**No fallback patterns.** Bot has no rehearsed responses for unknown intents; generates whatever the LLM produces. + +**Single-layer fallback.** Only "I do not understand" without alternatives. + +**Fallback loops.** Bot keeps asking clarification; user gets stuck. + +**Rigid refusal.** Bot says "I cannot help" without offering paths. + +**Generic fallback copy.** Fallback messages do not match brand voice. + +**Stale resource links.** Resource handoff points to broken URLs. + +**Wrong escalation routing.** Bot escalates to teams that are not appropriate. + +**Hidden human availability.** Bot does not communicate when humans are or are not available. + +**Sensitive topics not escalated.** Bot tries to handle topics that need human empathy. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Multi-layered fallback (4 layers with when to use). Layer sequencing. Anti-patterns (fallback loop, rigid refusal). Fallback copy discipline. Fallback for sensitive topics. Fallback during human unavailability. Fallback measurement. Fallback maintenance. Fallback and brand voice. Fallback testing. Common failures. + +## Implementation choices that stay internal + +Specific fallback messages for specific bots. Specific suggested intents and resource links. Specific escalation routing logic. The team's brand-voice fallback templates. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md new file mode 100644 index 0000000..2733529 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md @@ -0,0 +1,238 @@ +# Intent architecture patterns + +Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. + +The intent architecture is the bot's scope definition. Bad architecture produces bots that try to handle everything (and hallucinate) or bots that handle so little they fail audience expectations. Good architecture defines explicit scope and routes the rest to fallback. + +--- + +## The named-intent principle + +The bot has a defined set of intents it can handle. Each intent has a name, a scope, and a conversation pattern. + +**The win.** A user asks "what does the Pro plan include?" The bot recognizes this as the "pricing question" intent. The conversation pattern for that intent retrieves from the pricing knowledge base, generates a response, and offers follow-up. + +**The fail (no named intents).** The bot tries to handle every question with the same generic flow. Some questions get good answers; some get hallucinated answers; the bot cannot reason about its own scope. + +The discipline. Define the intents explicitly. The bot's behavior at each intent is intentional; behavior outside the intents is fallback. + +--- + +## Common intent patterns + +Patterns that recur across marketing-site and support chatbots. + +**Pricing question.** "How much does the Pro plan cost?" "What is included in the Enterprise tier?" "Do you offer discounts for nonprofits?" + +Conversation pattern: retrieve from pricing knowledge base, present the relevant tier or comparison, offer follow-up (talk to sales, see comparison, view full pricing page). + +**Feature comparison.** "What is the difference between A and B?" "Does feature X include Y?" + +Conversation pattern: retrieve from feature documentation, present comparison or specific feature details, offer follow-up. + +**Integration question.** "Do you integrate with Salesforce?" "How does the API work?" + +Conversation pattern: retrieve from integration catalog or API docs, present specific integration or API details, offer follow-up. + +**Support escalation.** "I need help with my account." "Something is broken." + +Conversation pattern: capture the issue context, escalate to human support with the captured context. + +**Demo request.** "Can I see a demo?" "I want to talk to sales." + +Conversation pattern: qualify the request (capture company size, use case, timeline), route to sales with the qualified context. + +**Account access.** "I forgot my password." "How do I access my account?" + +Conversation pattern: route to account-recovery flow or self-serve help. + +**General question.** "Tell me more about [topic]." "What can you help with?" + +Conversation pattern: present overview of bot capabilities; ask what specifically the user wants. + +--- + +## Intent hierarchy + +Top-level categories with sub-intents. + +**The pattern.** "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question," "annual vs monthly." + +**Strengths.** + +- Hierarchy mirrors how audiences think. +- Each sub-intent can have specific knowledge-base grounding and conversation pattern. +- Easier to maintain than flat intent set. + +**Weaknesses.** + +- More complex to build. +- Risk of over-decomposition (sub-intents that nobody triggers). + +**When to use.** When the bot's scope is broad enough that a flat intent set becomes unwieldy. Most production chatbots benefit from hierarchy. + +--- + +## Intent boundaries + +Each intent has clear scope. Out-of-scope topics route to fallback. + +**The principle.** The intent definition specifies what the intent covers and what it does not. + +**Example: "Pricing question" intent.** + +In scope: tier prices, plan inclusions, discount inquiries, billing-cycle questions. + +Out of scope: sales-specific negotiations (escalate to sales), custom pricing requests (escalate to sales), historical pricing (out-of-scope, fallback). + +**The boundary discipline.** Without clear boundaries, the bot tries to handle topics it should not. Boundaries are part of the intent definition. + +--- + +## Intent coverage + +The bot's intents should cover 70-90 percent of expected conversations. + +**The principle.** Trying to cover 100 percent often produces bloated intent sets the bot cannot handle reliably. Aiming for 70-90 percent leaves room for honest fallback on the remaining edge cases. + +**Coverage measurement.** + +- After launch, sample conversations and classify them by intent. +- The percentage classified into named intents is coverage. +- The percentage falling to fallback is the gap. + +**Coverage targets by use case.** + +- Marketing-site Q&A: 80-90 percent coverage achievable. +- Support: 60-80 percent coverage typical; support questions are more varied. +- Sales qualification: 70-85 percent coverage; depending on audience. + +**The over-coverage trap.** Pursuing 100 percent coverage often means adding intents that fire rarely. The maintenance overhead is significant; the value is low. Honest fallback for rare cases is often better than rarely-triggered intents. + +--- + +## Intent design discipline + +Designing each intent. + +**Step 1: Name the intent.** Specific name that reflects the conversation pattern. + +**Step 2: Scope the intent.** What topics in, what topics out. + +**Step 3: Identify the knowledge base.** What knowledge sources the intent grounds in. + +**Step 4: Design the conversation pattern.** Opening response, possible follow-ups, success state, escalation conditions. + +**Step 5: Define the success criterion.** What does success look like for this intent? User got the answer? User clicked through to a relevant page? User completed a follow-up action? + +**Step 6: Define escalation triggers.** When does this intent escalate to a human? + +The discipline. Each intent is designed deliberately. Generic conversation patterns produce generic results. + +--- + +## Intent recognition + +How the bot determines which intent the user is in. + +**LLM-based intent recognition.** The LLM classifies the user's message into one of the named intents. Common in modern chatbots. + +**Rule-based intent recognition.** Keywords or patterns trigger intent assignment. Older approach; brittle but predictable. + +**Hybrid.** LLM as primary; rules for high-confidence overrides. Common middle ground. + +**The recognition challenge.** Users phrase the same intent in many ways. "How much?" "What does it cost?" "Is there a free tier?" all map to "pricing question." The intent recognition has to handle the variety. + +**Recognition failure modes.** + +- Misclassification (intent A treated as intent B). +- Over-classification (too many intents recognized; conversation gets confusing). +- Under-classification (intents go unrecognized; conversations fall to fallback). + +The discipline. Test intent recognition with realistic user messages. Tune until the classification matches user intent reliably. + +--- + +## Intent maintenance + +Intents drift. Audiences shift; products evolve; conversation patterns change. + +**Maintenance signals.** + +- Specific intents see declining resolution rates. +- New conversation patterns emerge that no intent covers. +- Sub-intents become more or less common over time. + +**Maintenance cadence.** Quarterly review of intent performance. Add new intents when new patterns emerge consistently; retire intents that fire rarely. + +**The intent-maintenance audit.** + +- For each intent: trigger rate, resolution rate, escalation rate. +- Identify intents that are over-triggering (capture too much) or under-triggering (rarely fire). +- Identify gaps (conversations that should have an intent but do not). + +--- + +## Intent and brand voice + +Each intent's conversation pattern should sound like the brand. + +**The principle.** The bot's voice in each intent matches the brand voice. Consistent across intents; consistent with the brand's other surfaces. + +**Brand-voice failures.** + +- Different intents speaking in different voices. +- Bot voice that does not match the brand's other surfaces. +- Generic LLM voice (no brand personality). + +**The cure.** Voice guidance specific to the bot. Brand voice document that includes bot-specific examples. Test conversations to verify voice consistency. + +--- + +## Intent-architecture worked example + +A B2B SaaS chatbot for a project management tool. + +**Top-level intents.** + +1. Pricing question (sub-intents: tier comparison, discount inquiry, billing question, annual vs monthly) +2. Feature inquiry (sub-intents: specific feature, comparison to competitor, roadmap question) +3. Integration question (sub-intents: specific integration, API question, custom integration) +4. Demo request (sub-intents: standard demo, enterprise demo, technical deep-dive) +5. Support escalation (sub-intents: bug report, account issue, billing problem, general help) +6. Account access (sub-intents: password reset, account login, organization-level access) +7. General overview (sub-intent: introductory tour) + +**Coverage estimate.** 80-85 percent of expected conversations. + +**Fallback for the remaining 15-20 percent.** Multi-layered fallback (clarification, suggested intents, resource handoff, human escalation). + +The architecture is explicit. Each intent has scope, knowledge-base grounding, conversation pattern, and escalation triggers. + +--- + +## Common intent failures + +**Too few intents.** Bot tries to handle everything with generic flow; hallucinates or stays generic. + +**Too many intents.** Intents that rarely fire; maintenance overhead with no value. + +**Overlapping intents.** Two intents claiming the same conversations; recognition becomes ambiguous. + +**Unclear intent boundaries.** Bot handles topics out of scope; quality drops. + +**Intent recognition unreliable.** Misclassification rate high; users get wrong responses. + +**No intent maintenance.** Intent set frozen at launch; audiences evolve away from it. + +**Brand voice inconsistent.** Each intent speaks differently; bot feels disjointed. + +--- + +## Methodology-level choices that stay in the public skill + +The named-intent principle. Common intent patterns. Intent hierarchy. Intent boundaries. Intent coverage. Intent design discipline. Intent recognition approaches. Intent maintenance. Intent and brand voice. Worked example. Common failures. + +## Implementation choices that stay internal + +Specific intent sets for specific bots. Specific conversation patterns and copy. Specific recognition implementations. Specific knowledge-base mappings per intent. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md new file mode 100644 index 0000000..4ba9fb1 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md @@ -0,0 +1,263 @@ +# Knowledge-base grounding patterns + +Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. The bot's responses must come from real knowledge, not made-up confidence. + +Without grounding, the bot hallucinates. With grounding, the bot retrieves and presents. The difference is the gap between hallucinating-bot and structured-guided-conversation. + +--- + +## The grounding principle + +The bot's response generation should reference a structured knowledge base. The bot does not invent answers; it retrieves and presents. + +**The win.** A user asks "what is included in the Pro plan?" The bot retrieves the current pricing page, extracts the Pro plan inclusions, and presents them. The answer matches the source-of-truth. + +**The fail (hallucinating).** A user asks the same question. The bot has no grounding; the LLM generates a response from training data or pattern-matching. The response sounds confident but may be wrong (outdated, fabricated, partially correct). + +The discipline. Every response that could be wrong if invented must be grounded. + +--- + +## Pattern A: Retrieval-augmented generation (RAG) + +The bot searches a knowledge base for relevant content before generating a response. + +**How it works.** + +- The user's message is converted to a query. +- The query searches the knowledge base (often via vector embedding similarity). +- Relevant content chunks are retrieved. +- The LLM generates a response grounded in the retrieved content. + +**Strengths.** + +- Responses reflect current knowledge base content. +- Bot answers questions about specific topics it has been trained on. +- Easier to update than retraining a model; updating the knowledge base updates the bot. + +**Weaknesses.** + +- Retrieval quality depends on knowledge-base structure and embedding quality. +- Bot may still hallucinate if retrieval returns nothing or if generation strays from retrieved content. +- Latency increases (retrieval + generation). + +**When to use.** Default pattern for grounded chatbots. Most production bots use some form of RAG. + +--- + +## Pattern B: Source-of-truth design + +Defining the knowledge base as the canonical source. + +**The principle.** The knowledge base is the canonical source for the bot's responses. When the source-of-truth changes, the bot's answers change. + +**Source-of-truth examples.** + +- Pricing page = source for pricing answers. +- Documentation = source for feature and integration answers. +- Support knowledge base = source for support answers. +- Security and compliance docs = source for security answers. + +**Source-of-truth discipline.** + +- Each topic has a single source-of-truth. +- The bot retrieves from that source. +- When the source updates, the bot's answers update automatically (depending on the RAG pipeline). + +**The fragmented-source failure.** Multiple sources for the same topic produce inconsistent answers. The bot might cite one source; the user might rely on another. Confusion. + +The cure. Single source-of-truth per topic. If multiple documents cover the same topic, designate one as canonical and reference the others. + +--- + +## Pattern C: Citation discipline + +The bot can cite the source of its answer. + +**The principle.** Audiences benefit from knowing where the answer came from. Citation builds trust and lets the user verify. + +**Citation patterns.** + +- **Inline citation.** "Based on our pricing page, the Pro plan is $X per user per month." +- **Source link.** "You can see the full plan comparison [here]." +- **Source attribution at end.** "Source: [document name or link]" + +**Why citation matters.** + +- Trust-building. Users can verify the answer. +- Hallucination protection. If the bot cannot cite, the answer may be fabricated. +- User self-service. Users with deeper questions can follow the link. + +**Citation failures.** + +- Bot generates an answer without citation; the user cannot verify. +- Bot cites a source that does not actually contain the answer (citation hallucination). +- Bot cites a moved or deleted source; the link breaks. + +The discipline. Citations must point to real sources that contain the cited content. + +--- + +## Pattern D: Boundary disclosure + +The bot tells the user when it is operating outside its grounding. + +**The principle.** When the bot's response is not grounded (the question is outside the knowledge base), the bot says so explicitly. + +**Disclosure patterns.** + +- "I do not have information on that specific topic; would you like me to connect you with our team?" +- "Our pricing details are on the [pricing page]; the specific scenario you are asking about may need a custom quote from sales." +- "I can answer questions about our integrations; for product roadmap, you may want to contact our team." + +**The disclosure-as-honesty principle.** A bot that admits limitations earns more trust than a bot that fakes confidence on out-of-scope questions. + +--- + +## Knowledge-base structure + +How the knowledge base is organized affects retrieval quality. + +**Chunking.** Knowledge base content is broken into chunks for retrieval. Chunk size affects retrieval precision and context. + +- **Too small chunks.** Retrieval returns isolated facts without context. The bot may miss surrounding nuance. +- **Too large chunks.** Retrieval returns too much; relevant content is buried; generation may stray. +- **Right chunks.** Topically coherent units (a pricing tier description, a feature explanation, a support article section). + +**Metadata.** Each chunk has metadata (source document, section, last-updated date, topic tags). Metadata supports filtering and citation. + +**Embeddings.** Chunks are embedded for similarity search. Embedding quality affects retrieval relevance. + +**Index updates.** When the source-of-truth changes, the index must update. Stale index produces stale answers. + +--- + +## Knowledge-base scope + +What goes into the knowledge base. + +**In scope.** + +- Pricing and plan details. +- Feature and capability documentation. +- Integration catalog and API documentation. +- Support FAQs. +- Security and compliance information. +- Company overview, team, contact information. + +**Out of scope.** + +- Confidential information (internal-only docs, sensitive data). +- Information that changes too rapidly to keep current (real-time inventory, live availability). +- Information that requires personalization the bot cannot do (account-specific data). + +**Boundary discipline.** Sensitive or personalization-required topics should not be in the bot's knowledge base. The bot should escalate or route to authenticated channels for those. + +--- + +## Knowledge-base maintenance + +The knowledge base decays. Maintenance is part of the bot's lifecycle. + +**What decays.** + +- Pricing changes that did not propagate to the knowledge base. +- Features added or removed without docs being updated. +- Integration partners changing names or capabilities. +- Support articles that became outdated. + +**Maintenance cadence.** + +- Monthly review of high-traffic content (pricing, features). +- Quarterly review of broader knowledge base. +- Triggered review when the product or pricing changes (the change includes a knowledge-base update task). + +**Maintenance ownership.** Someone owns the knowledge base. Without owner, it decays. + +**Decay indicators.** + +- Bot answers that contradict current product reality. +- User complaints about wrong information from the bot. +- Sales or support hearing audiences cite outdated bot information. + +--- + +## Hallucination detection + +Even with grounding, bots can hallucinate. Detection is part of the discipline. + +**Detection methods.** + +- **Sample auditing.** Periodically sample bot conversations and verify the responses against source-of-truth. +- **User feedback signals.** "This response was not helpful" feedback often correlates with hallucination. +- **Citation verification.** Programmatic checks that cited sources actually contain the cited content. +- **Anomaly detection.** Conversations where the bot's response diverges significantly from retrieved content. + +**Remediation.** + +- Hallucinated content reported promptly. +- Knowledge base or grounding logic updated to prevent recurrence. +- Specific intent or topic may need re-design. + +**The honesty discipline.** Acknowledge hallucination when it happens. The team that hides hallucination from itself ships worse bots over time. + +--- + +## Knowledge-base and brand voice + +The knowledge base content informs the bot's voice. + +**The principle.** Source documents written in brand voice produce bot responses in brand voice. Source documents written generically produce generic bot responses. + +**The discipline.** When preparing source documents for the knowledge base, write in the brand voice. The bot will reflect what it retrieves. + +**Brand-voice editing.** Some teams edit retrieved content for the bot's response. This adds brand voice but risks drifting from the source-of-truth. Trade-off worth considering. + +--- + +## Multi-source grounding + +When the bot needs to combine information from multiple sources. + +**The pattern.** The bot retrieves from multiple sources and synthesizes a response. + +**Strengths.** + +- Bot can answer questions that span topics. +- Richer responses possible. + +**Weaknesses.** + +- Synthesis can introduce hallucination. +- Citation becomes more complex (multiple sources). +- Quality control harder. + +**The discipline.** Use multi-source grounding sparingly. When used, ensure the synthesis is grounded in retrieved content, not generated from training data. + +--- + +## Common grounding failures + +**No grounding.** Bot generates from training data; hallucinations are routine. + +**Stale grounding.** Knowledge base not updated; bot answers reflect outdated reality. + +**Fragmented grounding.** Multiple sources for same topic; bot answers are inconsistent. + +**Citation hallucination.** Bot cites sources that do not contain the cited content. + +**Generic content in knowledge base.** Source documents are not in brand voice; bot responses are generic. + +**Out-of-scope grounding.** Bot retrieves from sources that should not be in scope (confidential, personalized). + +**Boundary blur.** Bot answers questions outside its grounding without disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The grounding principle. Patterns A through D (RAG, source-of-truth, citation, boundary disclosure). Knowledge-base structure. Knowledge-base scope. Knowledge-base maintenance. Hallucination detection. Knowledge-base and brand voice. Multi-source grounding. Common grounding failures. + +## Implementation choices that stay internal + +Specific knowledge bases for specific bots. Specific RAG pipelines and embedding choices. Specific chunking and indexing approaches. Specific tooling for hallucination detection. The team's maintenance calendars. These vary by team. diff --git a/dist/pi/.agents/skills/code-review-web/SKILL.md b/dist/pi/.agents/skills/code-review-web/SKILL.md new file mode 100644 index 0000000..0edae47 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/SKILL.md @@ -0,0 +1,213 @@ +--- +name: code-review-web +description: "Review web application code for bugs, security issues, performance problems, and stack-specific anti-patterns. Use this skill whenever the user wants to review code, debug a production issue, investigate a build failure, audit security, or check a PR before merging. Triggers on code review, review my code, debug, build error, broken, not working, why is X failing, check this code, security check, PR review, audit code, refactor. Also triggers when investigating 4xx or 5xx errors, deploy failures, environment variable issues, and CMS integration problems." +category: development +catalog_summary: "PR review, build error diagnosis, security and quality checks" +display_order: 1 +--- + +# Code Review for Web + +Review and debug web application code with a focus on the patterns that actually break production. Stack-agnostic principles in SKILL.md. Stack-specific patterns in references. + +--- + +## When to use + +- Reviewing a pull request before merging +- Debugging a production issue +- Investigating a build failure +- Auditing security or performance of existing code +- Investigating environment variable or configuration issues +- Triaging a "the site is broken" report + +## When NOT to use + +- Writing a new feature spec (use `pm-spec-writing`) +- Pre-launch QA against the running site (use `qa-testing`) +- Performance deep-dive on Core Web Vitals (use `performance-optimization`) +- Deep accessibility compliance review (use `accessibility-audit`) + +--- + +## Required inputs + +- The code, PR, error message, or symptom under review +- Access to logs (build logs, function logs, server logs) if debugging +- The stack (framework, hosting, database) - even at high level + +If just a symptom is provided ("the site is broken"), the workflow's first step is gathering enough context to investigate. + +--- + +## The framework: 5 review dimensions + +Every code review covers five dimensions. Pick the depth based on the situation. + +### 1. Correctness + +Does the code do what it claims to do? + +- Logic matches the intent stated in the spec or PR description +- Edge cases handled (empty states, error states, network failures) +- Off-by-one errors, null/undefined handling, async race conditions +- Tests exist for the change, or there's a reason they don't +- The change does not break existing functionality (regression risk) + +### 2. Security + +Does the code expose anything sensitive or open an attack surface? + +- **Secrets handling.** No secrets, API keys, or service-role credentials in client-side code or version control +- **Auth checks.** Every mutation endpoint validates the caller before acting +- **Input validation.** User input sanitized before use in queries, file paths, or HTML +- **External requests.** Outbound URLs validated; no SSRF on user-controlled inputs +- **CSRF protection.** State-changing requests require a token or same-origin policy +- **Rate limiting.** Public-facing mutation endpoints have rate limits +- **HTTPS-only.** No HTTP in production code paths +- **Cookies.** Session cookies have `Secure`, `HttpOnly`, `SameSite` attributes set +- **Environment variables.** Server-only secrets are not prefixed with anything that exposes them to the client bundle + +### 3. Performance + +Will this code scale and stay fast? + +- **Database queries.** No N+1 patterns. Joins or batch fetches preferred over loops with queries. +- **Pagination.** Large result sets paginated, never loaded entirely. +- **Caching.** Appropriate cache strategy for the data freshness needs. +- **Bundle size.** Client-side dependencies justified. Tree-shaking working. +- **Image handling.** Modern formats, lazy loading, explicit dimensions. +- **Background work.** Slow operations moved off the request path. +- **Cold start sensitivity.** Cold paths optimized if frequently triggered. + +### 4. Reliability + +What happens when this fails? + +- **Error handling.** Caught and handled, not swallowed. Errors logged with context. +- **Retries.** Network calls have retry logic for transient failures. +- **Timeouts.** External calls have explicit timeouts (no infinite waits). +- **Graceful degradation.** Failure of non-critical paths does not crash the page. +- **Idempotency.** Mutations that might be retried are safe to retry. +- **Logging.** Enough context in logs to diagnose without reproducing. + +### 5. Maintainability + +Will the next person (or future you) understand this in six months? + +- **Naming.** Functions and variables named for what they do, not how. +- **Comments.** Explain why, not what. The code says what. +- **Complexity.** Functions do one thing. If a function takes 200 lines, it's doing too much. +- **Duplication.** Same logic in multiple places gets extracted. +- **Dependencies.** New dependencies justified. Each one is a maintenance burden. +- **Magic values.** No literal `60000` in code. Use named constants. + +--- + +## Common bug patterns (stack-agnostic) + +Patterns that recur across stacks and are worth checking on every review. + +### Build and deploy + +- **Build-time data fetches that timeout.** Routes that query a database during static generation can fail at scale. Mark them as runtime-rendered if the data must be fresh. +- **Environment variables not propagating.** A var that works locally but breaks in production usually means it was not added to the production environment. +- **Mismatched env between preview and production.** Deploys that work in preview but break on the production domain often have stack-specific URLs hardcoded. + +### URL and domain issues + +- **Canonical pointing at staging or preview URL.** Caused by client-exposed environment variables that pick up the wrong domain. Canonical domain should come from a server-only environment variable. +- **API URL pointing at the main domain that loops back.** After a DNS cutover, the main domain may now serve a different application. APIs should live on dedicated subdomains. +- **HTTPS upgrade issues.** Mixed content (HTTP resources loaded into HTTPS pages) breaks browsers' security model. + +### Cache invalidation + +- **Stale content after deploy.** Either the cache was not invalidated, or the invalidation requires a manual trigger that did not run. +- **CDN serving old asset under same filename.** Always use a new filename or cache-bust query string when replacing assets. +- **Cache headers too aggressive.** Long max-age on resources that change frequently leads to users seeing stale content for hours or days. + +### Database and data + +- **N+1 queries.** Loop with a query inside the loop. Replace with batch fetch or join. +- **Missing limits on table scans.** Forgetting `LIMIT` on queries that hit large tables. +- **Connection pool exhaustion.** Too many concurrent connections, often from build-time fetches in parallel routes. +- **Schema migration without backfill.** Adding a NOT NULL column without populating it for existing rows. + +### Image handling + +- **Image not loading after upload.** CDN cached the previous filename. Use new filenames for replacements. +- **Layout shift from images.** Missing width/height attributes. Always specify both. +- **Slow LCP from large images.** Hero images not optimized for size or format. + +### External integrations + +- **Bot mitigation blocking server-to-server calls.** CDN or firewall is challenging legitimate automated traffic. Whitelist server IPs or disable challenges for API endpoints. +- **API rate limit triggered in production.** Worked locally where traffic was tiny. Add backoff and rate limiting awareness. + +### Security + +- **Unprotected revalidation or admin endpoints.** Always require a secret token. +- **PII in URLs.** Visible in server logs, browser history, referrer headers. +- **Secrets exposed in client bundle.** Anything that gets sent to the browser is public. + +--- + +## Workflow + +1. **Gather context.** What stack? What's broken or under review? Logs available? +2. **Pick the depth.** Quick scan for a small PR. Full review for a major change. Deep dive for a production incident. +3. **Run through the 5 dimensions.** Note issues by severity (blocker, important, minor). +4. **Check stack-specific patterns.** Reference the appropriate stack guide. +5. **For incidents:** identify the smallest hypothesis-driven fix. Reproduce locally if possible. +6. **Write the review.** Use the template in [`references/review-template.md`](references/review-template.md) for formal reviews. + +--- + +## Failure patterns + +- **"Looks good to me" on a 500-line PR.** If the review takes 5 minutes on a large PR, the review didn't happen. +- **Reviewing without running the code.** Some bugs only surface at runtime. Pull the branch and run it. +- **Over-indexing on style.** Bikeshedding on formatting while missing logic bugs. +- **Skipping security review on "internal" features.** Internal becomes external faster than expected. +- **Treating warnings as decoration.** Build warnings often become production errors after a dependency update. +- **Debugging without reading the full error message.** First line of the stack trace is often not the actual cause. Read all of it. + +--- + +## Debugging workflow + +When a production issue is reported: + +1. **Read the full error message.** Including the stack trace. +2. **Check hosting build and function logs.** The exact failing line is usually here. +3. **Identify the last working version.** `git log --oneline` and check recent commits. +4. **Reproduce locally.** Confirms it's a code issue and not an environment issue. +5. **Check environment variables.** Especially after deploys or DNS changes. +6. **Check cache state.** Force a cache invalidation before concluding it's a code bug. +7. **Make the minimal fix.** Big refactors during incidents create more incidents. +8. **Verify in production.** Check the actual fix worked, not just that the deploy succeeded. +9. **Document.** What was the root cause? What would have prevented it? File the learnings. + +--- + +## Output format + +For PR reviews: comments inline on the PR, plus a summary if needed. + +For formal code reviews: a markdown document at `code-review-[date].md` with: +1. Scope (what was reviewed) +2. Summary (overall assessment) +3. Critical issues (blockers) +4. Important issues +5. Minor issues +6. Suggestions for follow-up + +For incidents: a postmortem document. See `after-action-report` for that format. + +--- + +## Reference files + +- [`references/review-template.md`](references/review-template.md) - Markdown template for formal code reviews. +- [`references/nextjs-patterns.md`](references/nextjs-patterns.md) - Stack-specific patterns for Next.js (App Router, ISR, Server Components, common bugs). +- [`references/wordpress-headless-patterns.md`](references/wordpress-headless-patterns.md) - Stack-specific patterns for headless WordPress integrations. diff --git a/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md b/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md new file mode 100644 index 0000000..0989e7c --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md @@ -0,0 +1,360 @@ +# Next.js Patterns + +Stack-specific patterns and anti-patterns for Next.js projects. Covers App Router and Pages Router. Stack-agnostic principles live in [SKILL.md](../SKILL.md). + +--- + +## App Router specific + +### Server vs client components + +**Default to server components.** Reach for `"use client"` only when interactivity, browser APIs, or React state hooks are required. + +```typescript +// Server component (default) - runs on server, no hydration cost +// app/page.tsx +export default async function Page() { + const data = await fetchData(); + return <Article data={data} />; +} + +// Client component - hydrates in browser +// app/components/InteractiveButton.tsx +"use client"; +export default function InteractiveButton() { + const [count, setCount] = useState(0); + return <button onClick={() => setCount(c => c + 1)}>{count}</button>; +} +``` + +**Anti-pattern:** Marking parent components as `"use client"` when only a leaf component needs it. This pulls everything below into the client bundle. + +### ISR and revalidation + +Pick the right rendering strategy per route: + +```typescript +// Static (default) - rendered at build, served from CDN +export default async function Page() { ... } + +// ISR (revalidate periodically) - rendered at build, regenerated on schedule +export const revalidate = 3600; // 1 hour + +// Dynamic (rendered on every request) - never cached +export const dynamic = "force-dynamic"; + +// Common combination: dynamic with cache hint for downstream +export const dynamic = "force-dynamic"; +export const revalidate = 3600; +``` + +### Build timeout failures + +Common error: +``` +Failed to build /route after 3 attempts because it took more than 60 seconds +``` + +**Cause:** A static route that queries a database or external API at build time, and the call exceeds the build timeout. + +**Fix:** Add `dynamic = "force-dynamic"` to defer rendering to request time: + +```typescript +export const dynamic = "force-dynamic"; +export const revalidate = 3600; + +export async function GET() { + try { + const data = await dbQuery(); + return generateResponse(data); + } catch (e) { + console.error("Route error:", e); + return new Response("", { status: 200 }); // empty but valid + } +} +``` + +### TypeScript errors in scripts directory + +If you have a `scripts/` folder with one-off scripts, exclude it from the build: + +```json +// tsconfig.json +{ + "exclude": ["node_modules", "scripts"] +} +``` + +### Canonical URL configuration + +The canonical domain must come from a server-only environment variable. Never expose with `NEXT_PUBLIC_` prefix. + +```typescript +// next.config.ts +const config = { + env: { + SITE_URL: process.env.SITE_URL ?? "https://yourdomain.com", + }, +}; +export default config; +``` + +```typescript +// Where the canonical is set +const url = process.env.SITE_URL; // server-only, never exposed to browser +``` + +**Anti-pattern:** Using `NEXT_PUBLIC_SITE_URL`. Vercel preview deploys will pick up the preview URL and pollute production canonicals. + +--- + +## Pages Router specific + +### getStaticProps timeouts + +Same fundamental issue as App Router build timeouts. Solution is `getServerSideProps` for routes that need fresh data: + +```typescript +// pages/dynamic-page.tsx +export async function getServerSideProps(context) { + const data = await dbQuery(); + return { props: { data } }; +} +``` + +Or ISR: + +```typescript +export async function getStaticProps() { + const data = await dbQuery(); + return { + props: { data }, + revalidate: 3600, + }; +} +``` + +--- + +## Common patterns across both routers + +### API routes / route handlers + +**Authentication on mutations:** + +```typescript +// app/api/protected/route.ts (App Router) +export async function POST(req: Request) { + const secret = req.headers.get("authorization"); + if (secret !== `Bearer ${process.env.API_SECRET}`) { + return new Response("Unauthorized", { status: 401 }); + } + // ... handle the request +} +``` + +**Revalidation endpoint protection:** + +```typescript +// app/api/revalidate/route.ts +import { revalidatePath } from "next/cache"; + +export async function POST(req: Request) { + const url = new URL(req.url); + const secret = url.searchParams.get("secret"); + + if (secret !== process.env.REVALIDATE_SECRET) { + return Response.json({ error: "Unauthorized" }, { status: 401 }); + } + + const path = url.searchParams.get("path") ?? "/"; + revalidatePath(path); + + return Response.json({ revalidated: true, path }); +} +``` + +### Image optimization + +Use the framework's built-in image component for proper optimization: + +```typescript +import Image from "next/image"; + +<Image + src="/photo.jpg" + alt="Descriptive alt text" + width={800} + height={600} + loading="lazy" // explicit even though lazy is default for below-fold +/> +``` + +For external image domains, configure `next.config.ts`: + +```typescript +const config = { + images: { + remotePatterns: [ + { protocol: "https", hostname: "cms.yourdomain.com" }, + ], + }, +}; +``` + +### Environment variables + +Three categories. Be explicit about which is which. + +``` +Server-only secrets (never prefix with NEXT_PUBLIC_): + DATABASE_URL + API_SECRET + STRIPE_SECRET_KEY + REVALIDATE_SECRET + SITE_URL (use server-only even for canonical, despite being a "public" value) + +Client-safe variables (NEXT_PUBLIC_ prefix exposes to browser): + NEXT_PUBLIC_GA_ID + NEXT_PUBLIC_DEFAULT_LANGUAGE + NEXT_PUBLIC_FEATURE_FLAGS + +Build-time only: + ANALYZE_BUNDLE + NODE_ENV (set automatically) +``` + +**Red flags during review:** +- Any secret with `NEXT_PUBLIC_` prefix +- Canonical or site URL set to a preview/staging URL in production +- Service role keys exposed to the browser + +--- + +## Common bugs and fixes + +### Page renders partially after deploy + +**Symptom:** Hero loads but content below is missing or stale. + +**Cause:** Stale ISR cache from before the deploy. + +**Fix:** Force revalidation: + +```bash +curl -X POST "https://yourdomain.com/api/revalidate?path=/&secret=$REVALIDATE_SECRET" +``` + +If the issue persists, check server logs for rendering errors during regeneration. + +### CMS API redirects to main domain after DNS cutover + +**Symptom:** API calls to the CMS return 302 redirects or 403 errors. + +**Cause:** API URL points at the main domain, which now serves the Next.js app instead of the CMS. + +**Fix:** Use a dedicated CMS subdomain: + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json # correct +WP_API_URL=https://yourdomain.com/wp-json # loops back to Next.js +``` + +### Images return 502 after domain change + +**Cause:** Image optimizer fetching from a domain that no longer hosts the source images. + +**Fix:** Update `images.remotePatterns` in `next.config.ts` to match the new image origin. Rewrite media URLs in data fetches to point at the correct origin. + +### Client component re-renders excessively + +**Cause:** Inline object or function as prop. New reference on every render triggers re-render in the child. + +**Fix:** Memoize: + +```typescript +// Before (creates new object each render) +<Child config={{ foo: "bar" }} /> + +// After +const config = useMemo(() => ({ foo: "bar" }), []); +<Child config={config} /> +``` + +--- + +## Performance patterns + +### Avoid request waterfalls + +```typescript +// Bad: sequential fetches +const user = await getUser(); +const posts = await getPostsByUser(user.id); +const comments = await getCommentsForPosts(posts.map(p => p.id)); + +// Good: parallel where possible +const user = await getUser(); +const [posts, settings] = await Promise.all([ + getPostsByUser(user.id), + getSettingsForUser(user.id), +]); +``` + +### Database query patterns + +```typescript +// Bad: N+1 +for (const post of posts) { + const author = await db.user.findUnique({ where: { id: post.authorId } }); +} + +// Good: batch fetch with relation +const posts = await db.post.findMany({ + include: { author: true }, +}); + +// Always limit large scans +const data = await db.post.findMany({ + where: { ... }, + take: 100, +}); +``` + +### Streaming with Suspense + +For App Router, stream slow content to improve perceived performance: + +```typescript +// app/page.tsx +import { Suspense } from "react"; +import FastContent from "./FastContent"; +import SlowContent from "./SlowContent"; + +export default function Page() { + return ( + <> + <FastContent /> + <Suspense fallback={<Loading />}> + <SlowContent /> + </Suspense> + </> + ); +} +``` + +--- + +## Code review checklist for Next.js + +- [ ] Server components default; `"use client"` only where needed +- [ ] ISR routes have appropriate `revalidate` value +- [ ] Database-querying routes have `force-dynamic` if they can timeout at build +- [ ] Canonical/site URL uses server-only env var +- [ ] No secrets in `NEXT_PUBLIC_` variables +- [ ] API routes have auth checks on mutations +- [ ] Revalidation endpoint protected with secret +- [ ] Images use the `Image` component, with explicit width/height +- [ ] External image domains in `images.remotePatterns` +- [ ] Scripts directory excluded from tsconfig if causing type errors +- [ ] Suspense boundaries for slow content where streaming helps diff --git a/dist/pi/.agents/skills/code-review-web/references/review-template.md b/dist/pi/.agents/skills/code-review-web/references/review-template.md new file mode 100644 index 0000000..35bcea4 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/review-template.md @@ -0,0 +1,141 @@ +# Code Review: [PR Title or Scope] + +**Reviewer:** [Name] +**Date:** [YYYY-MM-DD] +**PR or commit:** [Link or hash] +**Author:** [Name] +**Scope:** [Files reviewed, lines changed] + +--- + +## Summary + +[2 to 3 sentences. Overall assessment. Recommend merge, request changes, or block.] + +**Recommendation:** [Approve / Approve with comments / Request changes / Block] + +**Critical issues:** [N] +**Important issues:** [N] +**Minor issues:** [N] +**Suggestions:** [N] + +--- + +## Critical issues (blockers) + +[Issues that must be fixed before merge.] + +### 1. [Issue title] +- **File:** [path/to/file.ext] +- **Line:** [Line number or range] +- **Issue:** [What's wrong] +- **Why critical:** [Impact if shipped] +- **Suggested fix:** [Specific recommendation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Issues that should be addressed but might not block merge.] + +### 1. [Issue title] +- **File:** +- **Line:** +- **Issue:** +- **Suggested fix:** + +--- + +## Minor issues + +[Polish items, style consistency, naming.] + +- **[file:line]** [Description and suggestion] +- **[file:line]** [Description and suggestion] +- **[file:line]** [Description and suggestion] + +--- + +## Suggestions for follow-up + +[Things worth doing in a follow-up PR, not in this one.] + +- [Suggestion] +- [Suggestion] + +--- + +## Dimension scorecard + +| Dimension | Pass | Issues | +|---|---|---| +| Correctness | ☐ | [Notes] | +| Security | ☐ | [Notes] | +| Performance | ☐ | [Notes] | +| Reliability | ☐ | [Notes] | +| Maintainability | ☐ | [Notes] | + +--- + +## Specific checks + +### Correctness +- [ ] Logic matches PR description +- [ ] Edge cases handled (empty, null, error) +- [ ] No off-by-one or async race conditions +- [ ] Tests exist or are not needed (with reason) +- [ ] No regressions in existing functionality + +### Security +- [ ] No secrets in client-side code +- [ ] Auth checks on mutations +- [ ] Input validated before use +- [ ] No new SSRF surface +- [ ] Cookies have appropriate attributes +- [ ] Server-only env vars not exposed to client + +### Performance +- [ ] No N+1 queries +- [ ] Pagination on large result sets +- [ ] Cache strategy appropriate +- [ ] Bundle size impact reasonable +- [ ] Images handled correctly + +### Reliability +- [ ] Errors caught and handled +- [ ] Network calls have timeouts +- [ ] Graceful degradation for non-critical paths +- [ ] Mutations idempotent if retried +- [ ] Sufficient logging for diagnosis + +### Maintainability +- [ ] Naming clear +- [ ] Functions focused (one thing well) +- [ ] No unjustified duplication +- [ ] No magic values (use constants) +- [ ] Comments explain why, not what + +--- + +## Stack-specific checks (if applicable) + +[Reference the stack-specific guide for the project. Note any stack-specific patterns or anti-patterns worth flagging.] + +--- + +## Notes for the author + +[Encouraging or contextual notes. What was done well. What's a learning opportunity.] + +--- + +## Sign-off + +**Approval status:** [Approved / Approved with comments / Changes requested / Blocked] +**Date:** [YYYY-MM-DD] + +If changes were requested, link to the follow-up PR or commit when resolved: +- [Link or hash] diff --git a/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md b/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md new file mode 100644 index 0000000..cddd929 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md @@ -0,0 +1,265 @@ +# WordPress Headless Patterns + +Stack-specific patterns for WordPress as a headless CMS, integrated with a separate frontend (Next.js, Astro, Eleventy, custom, etc.). + +The principles in [SKILL.md](../SKILL.md) apply universally. This file covers the WordPress-specific patterns that recur in headless setups. + +--- + +## Architecture + +A headless WordPress setup typically looks like: + +``` +cms.yourdomain.com → WordPress backend (admin, REST API, media) +yourdomain.com → Frontend (renders content fetched from CMS API) +``` + +WordPress serves the data and admin. The frontend serves the user-facing site. The two are decoupled. + +This separation matters for several patterns below. + +--- + +## Always use a CMS subdomain + +**Pattern:** All API calls go to a dedicated subdomain. + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json +``` + +**Anti-pattern:** API calls to the main domain. + +``` +WP_API_URL=https://yourdomain.com/wp-json # this will break after DNS cutover +``` + +**Why:** When the main domain points to the frontend (post-DNS cutover), API calls to the main domain hit the frontend instead of WordPress. The frontend has no `/wp-json` route, so calls fail. + +The CMS subdomain remains a stable, dedicated endpoint regardless of where the main domain points. + +--- + +## Site URL configuration in WordPress + +After moving to a subdomain, WordPress needs to know its real URL. Otherwise the admin redirects to the main domain. + +In `wp-config.php`: + +```php +define("WP_HOME", "https://cms.yourdomain.com"); +define("WP_SITEURL", "https://cms.yourdomain.com"); +``` + +**Symptom if missing:** Logging into `cms.yourdomain.com/wp-admin` redirects to `yourdomain.com/wp-admin`, which hits the frontend (no admin), returning a 403 or 404. + +--- + +## Media URL handling + +WordPress generates media URLs based on the configured site URL. When fetched through the API, they will reference the CMS subdomain. The frontend needs to handle these correctly. + +### Pattern 1: Reference media at the CMS subdomain (simplest) + +The frontend renders images directly from the CMS subdomain: + +```html +<img src="https://cms.yourdomain.com/wp-content/uploads/photo.jpg" alt="..." /> +``` + +**Pros:** Simple. No URL rewriting. +**Cons:** Browser makes requests to a different origin. Need to allow that origin in image optimizer config. + +### Pattern 2: Rewrite media URLs to the frontend domain + +Strip the CMS prefix and serve media via the frontend's image optimizer: + +```typescript +// Convert CMS media URL to a pattern the frontend image optimizer accepts +function rewriteMediaUrl(url: string): string { + return url.replace("https://cms.yourdomain.com", ""); +} +``` + +Configure the frontend image optimizer to allow the CMS subdomain as a remote source. + +### Anti-pattern: Hardcoded media URLs in content + +If editors paste full URLs into the content (`<img src="https://cms.yourdomain.com/...">`), changing the CMS subdomain later breaks every reference. Use relative paths or template-rendered URLs instead. + +--- + +## Permalinks and post URLs + +WordPress posts have a `link` field in the API response that returns the WordPress-rendered URL (e.g., `https://cms.yourdomain.com/post-slug/`). This is wrong for the public-facing site. + +**Anti-pattern:** Using the `link` field directly. + +```typescript +// Wrong - shows the CMS URL +<a href={post.link}>{post.title}</a> +``` + +**Pattern:** Construct the public URL from the slug. + +```typescript +// Right - build the URL the frontend serves +<a href={`/blog/${post.slug}`}>{post.title}</a> +``` + +--- + +## Caching and revalidation + +The frontend caches API responses. When content changes in WordPress, the cache must be invalidated. + +### Pattern 1: Time-based revalidation + +Cache responses for a fixed period. Simple but content can be stale up to that period. + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { revalidate: 3600 }, // 1 hour +}); +``` + +### Pattern 2: On-demand revalidation via webhook + +WordPress fires a webhook on save. The webhook calls a frontend endpoint that invalidates the cache. + +WordPress side (mu-plugin or theme function): + +```php +add_action('save_post', function ($post_id) { + $post = get_post($post_id); + if ($post->post_status !== 'publish') return; + + wp_remote_post('https://yourdomain.com/api/revalidate', [ + 'body' => json_encode([ + 'secret' => REVALIDATE_SECRET, + 'path' => '/blog/' . $post->post_name, + ]), + 'headers' => ['Content-Type' => 'application/json'], + ]); +}); +``` + +Frontend side: an endpoint that invalidates the cache for the given path. + +### Pattern 3: Tag-based invalidation + +Tag fetches with semantic identifiers, then invalidate by tag when relevant content changes. + +```typescript +const posts = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { tags: ["posts"] }, +}); + +// Later, invalidate +revalidateTag("posts"); +``` + +--- + +## Authentication for the API + +For private content or write operations, the API requires authentication. + +### Application passwords (built into WordPress) + +WordPress supports application passwords for API authentication. Generate one in the admin under user profile. + +```typescript +const auth = btoa(`${username}:${appPassword}`); + +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + headers: { + Authorization: `Basic ${auth}`, + }, +}); +``` + +**Anti-pattern:** Hardcoding credentials in client-side code. Application passwords go in server-only environment variables. + +### JWT (via plugin) + +JWT plugins offer a more standard auth flow but add a plugin dependency. + +--- + +## Common bugs and fixes + +### "API returns 403 from server-side fetch" + +**Cause 1:** A bot mitigation service (Cloudflare's "Attack Challenge Mode" or similar) is challenging the server-to-server request. + +**Fix:** Disable bot mitigation challenges for the CMS API path, or whitelist the frontend's server IPs. + +**Cause 2:** The API requires authentication and the request is unauthenticated. + +**Fix:** Add an `Authorization` header with application password or JWT. + +### "Posts list is paginated and we're only getting 10" + +**Cause:** WordPress default per-page is 10. + +**Fix:** Use `per_page` parameter and handle pagination: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?per_page=100`); +const total = parseInt(res.headers.get('x-wp-total') ?? '0'); +const totalPages = parseInt(res.headers.get('x-wp-totalpages') ?? '0'); +``` + +For very large content sets, paginate explicitly rather than fetching all at once. + +### "Custom fields are missing from the API response" + +**Cause:** Advanced Custom Fields (ACF) or custom post meta is not exposed by default. + +**Fix:** Use the ACF to REST API plugin, or register custom fields with `register_rest_field`: + +```php +add_action('rest_api_init', function () { + register_rest_field('post', 'custom_field_name', [ + 'get_callback' => function ($post) { + return get_post_meta($post['id'], 'custom_field_name', true); + }, + ]); +}); +``` + +### "Featured image is missing from the API response" + +**Cause:** The API returns the image ID, not the full media object. + +**Fix:** Use `_embed=true` to inline media: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?_embed=true`); +// Now post._embedded["wp:featuredmedia"][0] has the full image data +``` + +### "Slug-only URLs return wrong content after rename" + +**Cause:** WordPress slug changes don't redirect the old slug. Frontend caches lock to the old slug. + +**Fix:** +1. WordPress: install a redirection plugin or maintain a redirects table +2. Frontend: handle 404s on slug routes by falling back to a search-by-title + +--- + +## Code review checklist for headless WordPress + +- [ ] All API calls use the CMS subdomain (no main domain references) +- [ ] WP_HOME and WP_SITEURL set in wp-config.php +- [ ] Media URLs handled correctly (either CMS-direct or rewritten) +- [ ] Post URLs constructed from slug, not the WordPress `link` field +- [ ] Cache invalidation strategy in place (time-based, webhook, or tag) +- [ ] Authentication credentials in server-only env vars +- [ ] API responses include needed embedded data (`_embed=true` where relevant) +- [ ] Pagination handled for large post lists +- [ ] Error handling for API failures (CMS down should not crash the frontend) +- [ ] Custom fields exposed via REST API where needed diff --git a/dist/pi/.agents/skills/comparison-tool-design/SKILL.md b/dist/pi/.agents/skills/comparison-tool-design/SKILL.md new file mode 100644 index 0000000..051888d --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/SKILL.md @@ -0,0 +1,261 @@ +--- +name: comparison-tool-design +description: "Designing side-by-side comparison tools (plan-compare, product-compare, alternative-compare) that help users decide rather than just listing features. Axis selection, default-comparison logic, recommendation discipline. Honest about feature-list-dump (every feature in a row, no decision support), hidden-recommendation (biased comparison pretending to be neutral), and honest-comparison-with-guidance (genuine comparison plus opinionated recommendation) patterns. Triggers on comparison tool, plan compare, product compare, alternative compare, vs page, decision support tool. Also triggers when conversion through comparison stages is poor, when users are abandoning at the comparison step, or when a comparison tool is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing comparison tools that help users decide. Distinguishes feature-list-dump (every feature in a row, no decision support) from hidden-recommendation (biased comparison pretending to be neutral) from honest-comparison-with-guidance (genuine comparison plus opinionated recommendation)" +display_order: 11 +--- + +# Comparison Tool Design + +A senior product marketing director's playbook for designing side-by-side comparison tools that help users decide rather than just listing features. Plan-compare, product-compare, alternative-compare. Axis selection, default-comparison logic, recommendation discipline. The discipline of building a comparison tool that earns the user's trust. + +Most comparison tools fail in one of two ways. They dump every feature into a giant grid (4 options × 40 features = 160 cells) and ask the user to weigh everything against everything. The user leaves without choosing. Or they pretend to be neutral comparisons but are actually sales pitches with biased defaults and weighted framing; the user catches the bias and trust collapses. + +The comparison tools that work do something different. Genuine like-for-like comparison plus an explicit opinionated recommendation. "For X audience, choose Y." The recommendation is visible, defended, and not the only path; users can override. The tool helps the user decide rather than asking them to decide alone. + +The voice is the senior product marketing director who has watched comparison tools double conversion when redesigned with honest recommendations and watched them collapse when feature grids grew without decision support. Practical, opinionated about which axes matter, willing to call out when the comparison is decoration. + +When to use this skill: scoping a comparison tool for the first time, auditing a feature-grid comparison that produces no conversion lift, designing recommendation logic that is honest about the recommendation, or deciding which axes earn placement in a comparison tool. + +--- + +## What this skill covers + +This skill spans side-by-side comparison tools. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number. This skill is comparing known options. +- `quiz-and-assessment-design` is quizzes that give a category. This skill is comparing options the user already knows about. +- **`comparison-tool-design` (this skill)** is axis selection, default-comparison logic, recommendation engine, filter-and-toggle UX. +- `landing-page-copy` is pricing-page copy; one specific application of comparison tools is the pricing page. +- `content-strategy` is upstream; what topics warrant comparison content. + +The audience: product marketers, growth marketers, content marketers running vs-pages and decision-support tooling, agencies running comparison work for clients. + +Out of scope: calculator design (covered by `calculator-design`); quiz design (covered by `quiz-and-assessment-design`); the engineering implementation; specific Webflow/Framer/CMS configurations (those stay implementation-side). + +--- + +## The comparison-tool decision: when comparison tools earn investment + +Before designing the tool, decide whether a comparison tool is the right answer. + +**Comparison tools earn investment when:** + +- The audience is at a decision moment between known options (vs unknown options where a quiz or recommendation tool fits better). +- The options have meaningful differences that warrant side-by-side analysis. +- The brand can articulate honest distinctions between options without becoming sales pitch. +- The audience benefits from decision support, not just feature listing. + +**Comparison tools do NOT earn investment when:** + +- Options are too similar to compare meaningfully. +- The brand cannot make honest distinctions without creating sales-pitch dynamics. +- A simple comparison table or written content would serve. +- The audience does not actually face this decision (manufactured comparisons). + +The decision is not "should we have a comparison tool"; it is "is the comparison tool the right tool for this decision." + +Detail in [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md). + +--- + +## Feature-list-dump vs hidden-recommendation vs honest-comparison-with-guidance + +The keystone framing. + +**Feature-list-dump.** Every option's every feature in a giant grid. No decision support. The user is asked to weigh 40 cells against each other; most leave without choosing. Cost: design effort wasted on a grid that does not produce decisions; the audience perceives the grid as overwhelming. + +**Hidden-recommendation.** "Comparison" tool that is actually a sales pitch. Defaults favor one option; framing weights the answer; the recommendation is invisible but baked in. Trust erodes when users notice the bias. Cost: short-term conversion may look fine; long-term brand damage from "manipulative" reputation. + +**Honest-comparison-with-guidance.** Genuine like-for-like comparison plus an explicit opinionated recommendation ("For X audience, choose Y"). The recommendation is visible, defended, and not the only path; users can override. Cost: design effort upfront is significant; conversion typically improves because users feel respected and helped. + +The litmus test. Does the tool tell the user what to choose for their specific situation, with reasoning? If yes, honest-comparison-with-guidance. If it dumps features without guidance, feature-list-dump. If it says "the right answer is obviously [our preferred option]" without acknowledgment, hidden-recommendation. + +--- + +## Axis selection: which dimensions matter, which are noise + +The single most consequential decision in comparison tool design. + +**The principle.** Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision, not every feature available. + +**Strong axes.** + +- **Decision-relevant capabilities.** Features that materially affect the audience's outcome. +- **Cost dimensions.** Price, total cost of ownership, hidden costs. +- **Constraint dimensions.** Capacity, scale, integration support. +- **Service dimensions.** Support quality, onboarding, SLA. +- **Risk dimensions.** Vendor stability, security, compliance. + +**Weak axes.** + +- **Marketing checkboxes.** Features that exist on every option; checkmarks across the row. +- **Nice-to-haves.** Features the audience does not actually weigh. +- **Vendor-specific terminology.** Features named differently by each vendor; comparison becomes label confusion. +- **Decoration features.** Features added to the grid because the brand has them and competitors do not. + +**The 8-12 axis rule.** Most production comparison tools work well with 8-12 axes. Beyond that, decision paralysis sets in. + +Detail in [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md). + +--- + +## Default-comparison logic + +Which options compare by default, and why. + +**The principle.** Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; biased defaults shape conclusions. + +**Default options.** + +- Audience-fit defaults. The options the audience most commonly considers. +- Stage-fit defaults. The options that match the audience's stage of decision. +- Inferred defaults. Based on referral source, query, or prior interaction. + +**Default axes.** + +- The axes most relevant to the typical audience. +- Audience can expand to additional axes if interested. + +**Bias-flattering defaults.** + +- Defaults set so brand always wins on visible axes. +- Defaults that hide axes where competitors win. +- Defaults that frame in brand's terminology. + +The discipline. Defaults serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +Detail in [`references/default-comparison-logic.md`](references/default-comparison-logic.md). + +--- + +## Recommendation engine design + +When to recommend, how to defend the recommendation. + +**The principle.** Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible. + +**Recommendation patterns.** + +- **Single recommendation.** "For [audience], choose [option] because [reasons]." Clear; opinionated. +- **Multi-segment recommendation.** "If you are [A], choose X. If you are [B], choose Y." Honest about audience-fit. +- **Conditional recommendation.** "If [factor] matters most, X. If [other factor] matters most, Y." Helps the user decide based on priorities. + +**Recommendation defense.** + +- The reasoning shown. +- The audience for the recommendation explicit. +- The override path visible. + +**Anti-pattern: hidden recommendation.** Tool that defaults to one option's victory through axis selection and framing, without explicit recommendation. Users feel manipulated when they catch the pattern. + +Detail in [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) and [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md). + +--- + +## Filter and toggle UX + +What users can adjust, what should stay fixed. + +**Filterable elements.** + +- Which options to compare (user adds or removes options). +- Which axes to show (user filters to relevant dimensions). +- Audience or use case (user signals their context; tool adapts). + +**Fixed elements.** + +- Methodology disclosure (always visible). +- Recommendation reasoning (always findable). +- Source citations (always linkable). + +**The filter-fatigue trap.** Too many filters; user paralyzed. + +**The under-filtered trap.** Tool too rigid; user cannot match their context. + +The discipline. Filters that materially help; not filters for the sake of customization. + +Detail in [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md). + +--- + +## Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +**Pattern 1: Too many cells.** 40 features × 5 options = 200 cells; cognitive overload. + +**Pattern 2: All-checkmarks rows.** Every option has the feature; the row produces no signal. + +**Pattern 3: Inconsistent axis terminology.** Each vendor names features differently; user confused. + +**Pattern 4: Hidden costs.** Pricing visible; fees, overage, integrations not surfaced. + +**Pattern 5: Apples-to-oranges options.** Comparing genuinely different things; no axis applies cleanly. + +**Pattern 6: No recommendation.** Tool lists; user must decide; user does not. + +The cumulative effect. The tool produces no decision; users default to the brand they already heard of. + +Detail in [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-comparison-failures.md`](references/common-comparison-failures.md). + +- "Tool gets traffic; conversion is unchanged." Likely feature-list-dump; no decision support. +- "Sales says competitor leads cite our tool as biased." Hidden-recommendation pattern; trust damage. +- "Mobile users do not engage with the tool." Comparison grids do not work well on mobile; design for it. +- "Power users criticize axis selection." Audience knows these features; tool may have used easy axes rather than decision-relevant. +- "Tool was great at launch; conversion declined over time." Features changed; comparison stale. +- "Audience says 'this is helpful' but does not convert." Recommendation absent or weak; users get information without decision support. +- "Comparison shows every option as 'good' for something." Dilution; no clear recommendation. +- "Adding more features to the comparison reduced conversion." Crossed the cell-count threshold; cognitive overload. + +--- + +## The framework: 12 considerations for comparison tool design + +When designing or auditing a comparison tool, walk these 12 considerations. + +1. **The comparison-tool decision.** Is a tool the right answer, or does written content serve? +2. **Honest-comparison-with-guidance, not feature-list-dump or hidden-recommendation.** Genuine compare plus opinionated rec. +3. **Axis selection.** 8-12 decision-relevant axes; cut decoration features. +4. **Default-comparison logic.** Honest defaults; not bias-flattering. +5. **Recommendation engine designed.** Visible; defended; not the only path. +6. **Filter and toggle UX.** Filters that help; not filters for customization theater. +7. **Methodology disclosed.** Source data, axis weighting, audience definition. +8. **Mobile parity.** Tool works on the devices the audience uses. +9. **Maintenance discipline.** Comparison stays current as options change. +10. **Honest about competitor strengths.** When competitors win on an axis, say so. +11. **Audience-fit measured.** Per-segment conversion through the tool. +12. **Conversion as success metric.** Not just engagement; downstream choice and retention. + +The output of the framework is a comparison tool that earns the user's trust by helping them decide, with recommendation that is honest and defensible. + +--- + +## Reference files + +- [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md) - When comparison tools earn the build vs when written content serves. +- [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md) - Strong axes, weak axes, the 8-12 rule. +- [`references/default-comparison-logic.md`](references/default-comparison-logic.md) - Honest defaults vs bias-flattering defaults. +- [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) - When to recommend, how to defend, override path. +- [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md) - Filterable vs fixed elements; filter-fatigue trap. +- [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md) - Why most comparisons fail to produce decisions. +- [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md) - The discipline that distinguishes hidden from honest recommendations. +- [`references/comparison-anti-patterns.md`](references/comparison-anti-patterns.md) - The patterns that look like comparisons but degrade trust. +- [`references/common-comparison-failures.md`](references/common-comparison-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: comparison tools earn the choice when they earn the user's trust + +The comparison tools that work as compounding assets are the ones the audience trusts to help them decide. Not because the tool flatters the brand. Not because the tool dumps features. Because the tool genuinely helps the user pick the option that fits their situation, and is honest about which option that is. + +That is the bar. Below the bar are feature-list-dump (no decision support; user leaves without choosing) and hidden-recommendation (biased pretending to be neutral; trust collapses when caught). Above the bar are honest-comparison-with-guidance tools where axis selection, default logic, recommendation engine, and filter UX work together to produce decisions the audience trusts. + +The discipline is in the design choices. The decision to build a comparison at all. The axes that earn placement. The defaults that serve the audience. The recommendation that is visible and defended. The filters that help the user match their context. The methodology that is disclosed. The maintenance that keeps the comparison current. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md new file mode 100644 index 0000000..299644d --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md @@ -0,0 +1,185 @@ +# Axis selection patterns + +Strong axes, weak axes, the 8-12 rule. + +Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision. Done well, axes produce decisions; done poorly, they produce overwhelm. + +--- + +## The decision-relevance principle + +Each axis should affect the audience's decision. Axes that do not are decoration. + +**The win.** A comparison tool with 10 axes covering capability, pricing, integration, support quality. Each axis materially affects whether the audience would choose. + +**The fail.** Same tool with 35 axes including marketing-checkbox features. User overwhelmed; many cells provide no signal. + +The discipline. Axes earn placement through decision relevance. + +--- + +## Strong axes + +Patterns that earn placement. + +**Decision-relevant capabilities.** The 5-7 capabilities the audience explicitly evaluates. + +**Cost dimensions.** Price, total cost of ownership, hidden costs. + +**Constraint dimensions.** Capacity, scale ceilings, integrations, geography. + +**Service dimensions.** Support quality, onboarding, SLA. + +**Risk dimensions.** Vendor stability, security, compliance. + +**Time dimensions.** Time to value, implementation timeline. + +**The selection discipline.** Each axis answers "will this matter to the audience?" If no, cut. + +--- + +## Weak axes + +Patterns that fail. + +**Marketing checkboxes.** Features on every option; checkmarks across the row. No signal. + +**Nice-to-haves.** Features the audience does not weigh. + +**Vendor-specific terminology.** Features named differently by each vendor; label confusion. + +**Decoration features.** Added because brand has them. + +**Generic checkmarks.** "Customer support: yes/yes/yes." Not differentiating. + +--- + +## The 8-12 axis rule + +Most production comparison tools work well with 8-12 axes. + +**Why 8-12.** + +- Below 8: comparison thin. +- Above 12: cognitive overload. + +**Exceptions.** + +- Highly technical audiences may absorb 15-20. +- Consumer audiences may tolerate 6-8. + +**The over-12 trap.** Each axis beyond 12 reduces engagement. + +--- + +## Axis ordering + +Within the comparison, order matters. + +**Strong order.** Most decision-relevant first. + +**Weak order.** Random; alphabetical; feature-category without importance weighting. + +**The first-axis discipline.** First axis should be one of the most important; users may skim past later axes. + +--- + +## Axis grouping + +When axes group naturally. + +**Grouping patterns.** Capability axes together; cost together; service together; risk together. + +**Strengths.** Easier to scan. + +**Weaknesses.** Group dividers add visual complexity. + +**When to use.** When axis count justifies (10+ axes). + +--- + +## Axis content per cell + +What each cell shows. + +**Beyond checkmarks.** "Yes/no" rarely produces decisions. Numbers, descriptions, comparisons add depth. + +**Examples.** + +- Cost: "$X/month" not just "Yes" to "has pricing." +- Capacity: "Up to 1000 users" not just "Yes" to "scales." +- Support: "24/7 chat plus phone" not just "Yes" to "support." + +The cell content discipline. Depth where decisions need it. + +--- + +## Axis defaults + +Which axes show by default; which behind toggle. + +**Default-shown axes.** The 8-12 most decision-relevant. + +**Toggle-shown axes.** Less critical; audience can expand. + +**The hide-bias trap.** Hiding axes where brand loses; detection eventual. + +**The honest-default principle.** Defaults reflect audience importance; not brand strength. + +--- + +## Axis updates + +Axes decay. + +**What decays.** + +- Axes that lost relevance. +- Axes that gained relevance. +- Axis content stale. + +**Maintenance cadence.** Quarterly review. + +--- + +## Axis testing + +Validate axes with the audience. + +**Methods.** + +- User research: which axes do they consider? +- A/B test: different axis sets. +- Sales-call mining: which axes do prospects ask about? + +The validation discipline. Axes are hypotheses; validate. + +--- + +## Common axis failures + +**Too many axes.** Cognitive overload. + +**Too few axes.** Comparison thin. + +**Wrong axes.** Audience does not weigh them. + +**Marketing-checkbox axes.** No signal. + +**Vendor-specific terminology.** Label confusion. + +**Hidden axes where brand loses.** Bias detected. + +**Stale axis content.** Pricing or features outdated. + +**Axis ordering ignores importance.** First axes are not most critical. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relevance principle. Strong axes (6 patterns). Weak axes (5 patterns). The 8-12 rule. Axis ordering. Axis grouping. Cell content. Axis defaults. Updates. Testing. Common failures. + +## Implementation choices that stay internal + +Specific axes for specific tools. Specific cell content. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md b/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md new file mode 100644 index 0000000..6dafdbb --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md @@ -0,0 +1,179 @@ +# Common comparison failures + +8+ failure patterns with diagnoses and cures. + +--- + +## "Tool gets traffic; conversion is unchanged." + +**The diagnosis.** Likely feature-list-dump; no decision support. + +**The cure.** Add recommendation. Cut decoration axes. Detail in `references/recommendation-engine-design.md`. + +--- + +## "Sales says competitor leads cite our tool as biased." + +**The diagnosis.** Hidden-recommendation pattern; trust damage. + +**The cure.** Honest recommendation discipline (`references/honest-recommendation-discipline.md`). Acknowledge competitor strengths. + +--- + +## "Mobile users do not engage with the tool." + +**The diagnosis.** Comparison grids do not work well on mobile. + +**The cure.** Mobile-first design. Stacked layout. Reduced axis count for mobile. + +--- + +## "Power users criticize axis selection." + +**The diagnosis.** Audience knows these features; tool may have used easy axes rather than decision-relevant. + +**The cure.** Audit axes against real audience decisions. Replace marketing-checkbox axes with decision-relevant ones. + +--- + +## "Tool was great at launch; conversion declined over time." + +**The diagnosis.** Features changed; comparison stale. + +**The cure.** Quarterly maintenance. + +--- + +## "Audience says 'this is helpful' but does not convert." + +**The diagnosis.** Recommendation absent or weak. + +**The cure.** Add recommendation with reasoning and clear next-step CTA. + +--- + +## "Comparison shows every option as 'good' for something." + +**The diagnosis.** Dilution; no clear recommendation. + +**The cure.** Take a stand. Recommendation should be opinionated; tradeoffs acknowledged. + +--- + +## "Adding more features to the comparison reduced conversion." + +**The diagnosis.** Crossed the cell-count threshold; cognitive overload. + +**The cure.** Cut back. 8-12 axes is the working range. + +--- + +## "Sales says many leads come through the tool but bounce on demo." + +**The diagnosis.** Tool's framing oversells; reality on demo does not match. + +**The cure.** Honest tool produces honest leads. Audit framing for sales-pitch dynamics. + +--- + +## "Audience-segment recommendations feel stereotyped." + +**The diagnosis.** Segment definitions based on assumptions rather than research. + +**The cure.** Validate audience segments with research. Refine recommendations based on real needs. + +--- + +## "Specific competitor is missing; users ask why." + +**The diagnosis.** Competitor omitted from comparison. + +**The cure.** Include relevant competitors. If intentionally excluded, disclose why ("we focus on X category; competitor Y is in different category"). + +--- + +## "Tool methodology questioned by analyst or journalist." + +**The diagnosis.** Methodology hidden or weakly defended. + +**The cure.** Detailed methodology disclosure. Be ready to defend specific axis choices and weights. + +--- + +## "Tool conversion is fine; sales conversion does not match." + +**The diagnosis.** Tool optimizes for tool-conversion; downstream not aligned. + +**The cure.** Track downstream metrics. Optimize for downstream conversion, not just tool engagement. + +--- + +## "Filter use is low; users see default comparison only." + +**The diagnosis.** Filters added but not promoted; users do not realize they exist. + +**The cure.** Promote filters; or accept that defaults serve and reduce filter complexity. + +--- + +## "Filters produce empty result combinations." + +**The diagnosis.** Filter logic does not constrain combinations to those producing comparable options. + +**The cure.** Smart filter logic. When filters would produce empty result, surface alternatives. + +--- + +## "Recommendation fires for one option always." + +**The diagnosis.** Hidden-recommendation; bias-flattering logic. + +**The cure.** Test the recommendation engine across audience scenarios. Ensure competitors win when fit warrants. + +--- + +## "Audience tells us the comparison feels accurate but the recommendation feels off." + +**The diagnosis.** Comparison data accurate; recommendation engine logic does not match audience priorities. + +**The cure.** Validate recommendation logic. Audience research on what they weigh vs what the tool weights. + +--- + +## "We A/B tested adding axes; conversion went down." + +**The diagnosis.** Crossed the cell-count threshold. + +**The cure.** Maintain axis discipline. More is not always better. + +--- + +## "Tool produces good conversion for new visitors; returning visitors do not engage." + +**The diagnosis.** Tool optimized for first-time-decision audience; returning visitors have other needs. + +**The cure.** Different surfaces for different stages. Returning visitors may want simpler reference rather than full tool. + +--- + +## The pattern across failures + +Most comparison tool failures fall into one of three patterns. + +**Pattern 1: No decision support.** Feature-list-dump, no-recommendation, dilution. The fix is clear, defensible recommendation. + +**Pattern 2: Bias damages trust.** Hidden-recommendation, contradiction, omitted competitors, stereotypes. The fix is honest recommendation discipline. + +**Pattern 3: Friction.** Over-filtered, mobile-broken, fatigue patterns. The fix is reducing cognitive load and matching audience use. + +The metric pattern: comparison failures often look fine on engagement alone. The signal is in conversion, downstream metrics, audience trust. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (no-decision-support, bias, friction). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md new file mode 100644 index 0000000..35ec8f0 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md @@ -0,0 +1,218 @@ +# Comparison anti-patterns + +The patterns that look like comparisons but degrade trust. Easy to ship; cost shows up in conversion, brand reputation, and audience trust. + +--- + +## The feature-list-dump comparison + +The pattern. Every feature × every option. No decision support. + +The signal. Users skim; do not choose; tool produces no conversion lift. + +The cure. Cut to 8-12 decision-relevant axes. Add recommendation. + +--- + +## The hidden-recommendation comparison + +The pattern. Defaults bias toward brand without disclosure. + +The signal. Sophisticated audiences notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest defaults; explicit recommendation; acknowledge competitor strengths. + +--- + +## The all-checkmarks comparison + +The pattern. Every option has every feature; checkmarks across the rows. + +The signal. Rows produce no signal; users skim. + +The cure. Cut generic-checkmark rows. Replace with specifics that differentiate. + +--- + +## The terminology-confused comparison + +The pattern. Each vendor's terminology used in their column; user cannot tell if features match. + +The signal. Users confused; comparison breaks semantically. + +The cure. Normalize terminology. Vendor names in subtext; functional descriptions in main label. + +--- + +## The hidden-cost comparison + +The pattern. Headline pricing visible; overage, fees, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cure. Total cost of ownership surfaced. + +--- + +## The apples-to-oranges comparison + +The pattern. Options compared that are genuinely different things. + +The signal. Comparison feels strained; axes do not apply cleanly. + +The cure. Compare options the audience actually considers together. Separate tools for separate categories if needed. + +--- + +## The no-recommendation comparison + +The pattern. Tool lists; user decides alone. + +The signal. High abandonment; conversion lift absent. + +The cure. Add recommendation with reasoning. + +--- + +## The contradicts-itself comparison + +The pattern. Comparison shows competitor winning on most axes; tool recommends brand anyway. + +The signal. Users notice the contradiction; trust collapses. + +The cure. Recommendation aligns with comparison; or recommendation defends the contradiction explicitly. + +--- + +## The stale comparison + +The pattern. Information from 6+ months ago. + +The signal. Users notice; trust drops. + +The cure. Quarterly maintenance. + +--- + +## The over-filtered comparison + +The pattern. 12+ filters; user paralysis at filter step. + +The signal. High drop-off before the comparison loads. + +The cure. Reduce filter count; default-heavy. + +--- + +## The under-filtered comparison + +The pattern. Tool too rigid; one fixed view. + +The signal. Specific segments convert poorly. + +The cure. Add filters where audiences split. + +--- + +## The mobile-broken comparison + +The pattern. Grid designed for desktop; mobile cramped or scroll-required. + +The signal. Mobile conversion much lower. + +The cure. Mobile-first design. + +--- + +## The methodology-hidden comparison + +The pattern. Tool shown without explaining how comparison was built. + +The signal. Sophisticated users question the tool. + +The cure. Methodology disclosure. + +--- + +## The audience-stereotype comparison + +The pattern. Audience-segment recommendations rely on stereotypes ("enterprise = big and slow"). + +The signal. Users in those segments feel mis-served. + +The cure. Audience-segment recommendations based on real needs, not assumptions. + +--- + +## The over-recommend comparison + +The pattern. Tool recommends in cases where genuine differentiator does not exist. + +The signal. Users notice the recommendation feels arbitrary. + +The cure. "We cannot rank these for you" is sometimes the honest answer. + +--- + +## The competitor-omission comparison + +The pattern. Important competitor missing from the comparison. + +The signal. Users ask "where is X?" or feel comparison is incomplete. + +The cure. Include relevant competitors. If a competitor is omitted intentionally, disclose why. + +--- + +## The bias-flattering-axis-selection comparison + +The pattern. Axes chosen where brand wins; axes hidden where brand loses. + +The signal. Sophisticated audiences notice axis selection. + +The cure. Honest axis selection. Detail in `references/axis-selection-patterns.md`. + +--- + +## The marketing-checkbox comparison + +The pattern. Every option's marketing checkboxes laid out as comparison. + +The signal. Comparison reads like marketing brochures rather than analysis. + +The cure. Replace marketing checkboxes with specific functional capabilities. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +**Audit questions per tool.** + +- Is the tool feature-list-dump (anti-pattern check)? +- Does the recommendation acknowledge competitor strengths (anti-pattern check: hidden-recommendation)? +- Are rows differentiating (anti-pattern check: all-checkmarks)? +- Is terminology normalized (anti-pattern check: terminology-confused)? +- Are total costs surfaced (anti-pattern check: hidden-cost)? +- Are options apples-to-apples (anti-pattern check: apples-to-oranges)? +- Is recommendation present (anti-pattern check: no-recommendation)? +- Does recommendation align with comparison (anti-pattern check: contradicts-itself)? +- Is information current (anti-pattern check: stale)? +- Are filters calibrated (anti-pattern check: over-filtered, under-filtered)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Is methodology disclosed (anti-pattern check: methodology-hidden)? + +**The retire decision.** Tools failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md new file mode 100644 index 0000000..10e5a0f --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md @@ -0,0 +1,190 @@ +# Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Most comparison tools accumulate cognitive load until users abandon without choosing. Comparison-fatigue patterns are the failure modes that make this happen. + +--- + +## Pattern 1: Too many cells + +The pattern. 40 features × 5 options = 200 cells. + +The signal. Users skim; pick the brand they already heard of; tool produces no decision. + +The cost. Comparison work is invisible because users cannot process the volume. + +The cure. Reduce cells. 8-12 axes × 3-5 options = 24-60 cells. The comparison density is comprehensible. + +--- + +## Pattern 2: All-checkmarks rows + +The pattern. Every option has the feature; the row produces checkmarks across. + +The signal. Users skim past; row provides no signal. + +The cost. Row earns space without earning attention. + +The cure. Cut the row, or replace generic checkmarks with specifics that differentiate. + +--- + +## Pattern 3: Inconsistent axis terminology + +The pattern. Each vendor names features differently; comparison becomes label confusion. + +The signal. User confusion; cannot tell if "Pro Workspace" and "Premium Studio" are the same thing. + +The cost. Comparison breaks at semantic level; users cannot weigh. + +The cure. Normalize terminology. Use functional descriptions; vendor labels in subtext. + +--- + +## Pattern 4: Hidden costs + +The pattern. Pricing visible; fees, overage, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cost. Trust damage when discovered. + +The cure. Surface total cost of ownership. Acknowledge fees, overage, expected add-ons. + +--- + +## Pattern 5: Apples-to-oranges options + +The pattern. Comparing genuinely different things; no axis applies cleanly. + +The signal. Comparison feels strained; users cannot tell why these options are being compared. + +The cost. Tool exists but produces no useful decision support. + +The cure. Compare options the audience would actually consider together. If options are too different, separate tools may serve better. + +--- + +## Pattern 6: No recommendation + +The pattern. Tool lists; user must decide; user does not. + +The signal. High abandonment; conversion rate low. + +The cost. The tool's information work does not produce decisions. + +The cure. Add explicit recommendation with reasoning. Detail in `references/recommendation-engine-design.md`. + +--- + +## Pattern 7: Stale information + +The pattern. Comparison content from 6+ months ago; competitors have updated; brand has updated. + +The signal. Users notice the staleness; trust drops. + +The cost. Tool produces decisions based on outdated information. + +The cure. Quarterly maintenance. Triggered updates when major competitor or brand changes happen. + +--- + +## Pattern 8: Bias-flattering framing + +The pattern. Comparison content frames in brand's favor (showing brand's most expensive plan vs competitors' cheap; using brand's terminology for axes). + +The signal. Sophisticated users notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest framing. Acknowledge competitor strengths. Use neutral terminology where possible. + +--- + +## Pattern 9: Decision paralysis at filter step + +The pattern. Tool requires extensive filter setup before showing comparison; users abandon at filter step. + +The signal. High drop-off before the comparison loads. + +The cost. Comparison work is invisible; users never see it. + +The cure. Default-heavy. Show comparison immediately; filters available but optional. + +--- + +## Pattern 10: Mobile illegibility + +The pattern. Comparison grid designed for desktop; on mobile, cells cramped or scroll-required. + +The signal. Mobile conversion much lower than desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design. Stacked layout for mobile; reduced axis count. + +--- + +## Pattern 11: No methodology disclosure + +The pattern. Comparison shown without explaining how it was assembled. Users do not know if it is honest. + +The signal. Users question the comparison; sales hears about doubts. + +The cost. Trust degrades; comparison's authority unclear. + +The cure. Disclose methodology. Where data came from; how axes were chosen; when last updated. + +--- + +## Pattern 12: Recommendation contradicts comparison + +The pattern. Comparison shows option B winning on most axes; tool recommends option A. + +The signal. Users notice the contradiction; trust collapses. + +The cost. Tool internally inconsistent; users cannot rely on it. + +The cure. Recommendation aligns with comparison. If recommendation favors A despite axis losses, defend explicitly ("Option A wins despite [losses] because [audience-specific reasoning]"). + +--- + +## The cumulative effect + +Most comparison tools fail at multiple of these patterns simultaneously. The cumulative effect: tool produces no decisions; users default to the brand they already heard of; comparison work is wasted. + +The cure. Audit each pattern. Each pattern fixed reduces cumulative friction. + +--- + +## How to audit comparison fatigue + +Quarterly review. + +**Audit questions per tool.** + +- Cell count: is it under 100? +- Are any rows all-checkmarks? +- Is terminology normalized across options? +- Are total costs surfaced? +- Are options apples-to-apples? +- Is recommendation present and visible? +- Is information current? +- Is framing honest? +- Is filter step lightweight? +- Does mobile work? +- Is methodology disclosed? +- Does recommendation match comparison? + +**The retire decision.** Tools failing multiple patterns warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 fatigue patterns. Signal-pattern-cost framing. Cures. The cumulative effect. Audit questions. + +## Implementation choices that stay internal + +Specific fatigue patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md new file mode 100644 index 0000000..527087f --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md @@ -0,0 +1,132 @@ +# Comparison-tool decision criteria + +When comparison tools earn the build vs when written content serves. + +A comparison tool is meaningful work. Axis selection, default logic, recommendation engine, filter UX, ongoing maintenance. The tool earns this investment only when specific conditions are present. + +--- + +## When comparison tools earn the build + +Five conditions that, when present, make a comparison tool a strong investment. + +**The audience is at a decision moment between known options.** They know the options exist; they need help choosing. Audiences who do not yet know the options need different tools (quizzes, recommendations). + +**The options have meaningful differences.** Comparing two options that differ only in branding produces nothing useful. + +**The brand can articulate honest distinctions.** Without becoming sales pitch. + +**The audience benefits from decision support.** Some audiences want a tool that helps them decide rather than weigh tradeoffs themselves. + +**The success metric is defined.** Conversion through the tool, downstream conversion, choice quality. + +When all five are present, a comparison tool is strong investment. When two or fewer are present, written content often serves better. + +--- + +## When comparison tools do NOT earn the build + +Funnels where comparison tools add cost without lift. + +**Options too similar.** Comparing genuinely interchangeable options produces no decision support. + +**Options apples-to-oranges.** Comparison axes do not apply across both. + +**Brand cannot make honest distinctions.** Tool will become hidden-recommendation; trust suffers. + +**A simple table or article would serve.** Static comparison content is cheaper. + +**The audience does not face this decision.** Manufactured comparisons feel forced. + +--- + +## Comparison tools vs written vs-pages + +Both compare options; differ in interactivity. + +**Written vs-pages strengths.** Cheap; SEO-friendly; easy to update. + +**Written vs-pages weaknesses.** Static; no recommendation logic. + +**Comparison tool strengths.** Adaptive; surfaces recommendations dynamically; lets users explore. + +**Comparison tool weaknesses.** Build cost; maintenance burden. + +**The combined approach.** Many production teams use both: vs-pages for SEO; tools for decision support. + +--- + +## The opportunity-cost frame + +Comparison tools are significant work. + +**Build cost.** Axis curation, recommendation logic, filter UX, methodology disclosure, mobile responsiveness. 30-100 engineering hours plus design and content. + +**Maintenance cost.** Quarterly updates run 4-8 hours. + +**Opportunity cost.** What else could the team have built? Better vs-pages, calculator, quiz. The tool has to clear those alternatives. + +The decision frame. Comparison tools earn investment when they produce more decision lift than alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering a comparison tool against 3 named competitors. + +**Conditions check.** + +- Decision moment: yes. +- Meaningful differences: yes; pricing, features, integration vary. +- Brand can articulate honest distinctions: yes. +- Audience benefits: yes. +- Success metric defined: yes. + +**Decision.** Build the comparison tool. + +**Architecture.** 10 axes; 4 options; honest recommendation per audience segment. + +The decision was deliberate. + +--- + +## Decision worked example: when written serves + +A consumer-facing financial product considering a comparison tool against generic bank accounts. + +**Conditions check.** + +- Decision moment: yes. +- Meaningful differences: somewhat; many banks similar. +- Brand articulate distinctions: yes for specific competitors. +- Audience benefits: somewhat. +- Success metric: signup; harder to attribute. + +**Decision.** Written vs-pages plus a brief comparison table. Full tool not warranted. + +The decision was right-sized. + +--- + +## When to retire a comparison tool + +Tools can become wrong over time. + +**Retire when:** + +- Conversion declined consistently. +- Options changed enough that comparison is misleading. +- Competitors deprecated. +- A redesigned vs-page produces equivalent results. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant comparison tools. The five conditions that argue against. Comparison tools vs written vs-pages. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tool decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md b/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md new file mode 100644 index 0000000..07c542a --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md @@ -0,0 +1,169 @@ +# Default-comparison logic + +Honest defaults vs bias-flattering defaults. + +Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; bias-flattering defaults shape conclusions in ways that erode trust when caught. + +--- + +## The honest-default principle + +Defaults should serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +**The win.** Default comparison shows the brand alongside 2-3 commonly-considered competitors. Default axes are the 8-12 most decision-relevant. Default audience profile (if pre-selected) reflects the visitor's likely segment. + +**The fail.** Default comparison shows the brand alongside the 2 weakest competitors. Default axes are the ones where the brand wins. Audience defaults assume the brand's ideal customer. + +The discipline. Defaults make the comparison fair as a starting point; users can adjust. + +--- + +## Default options + +Which options compare by default. + +**Audience-fit defaults.** The options the audience most commonly considers. + +How to determine. Sales-call mining (which competitors do prospects mention?), referral analysis, user research. + +**Stage-fit defaults.** The options that match the audience's stage. + +How. Awareness audiences may compare against generic categories; decision audiences against specific products. + +**Inferred defaults.** Based on referral source or query. + +How. Visitor from "X vs Y" search query gets X and Y as defaults; visitor from generic landing gets default comparison set. + +--- + +## Default axes + +Which axes show by default. + +**The most-critical-axes default.** Top 8-12 axes by decision relevance. + +**Audience-relevant axes.** Default to axes most relevant to the inferred or stated audience. + +**The hide-where-we-lose anti-pattern.** Defaulting to axes where the brand wins; hiding where it loses. Detection by analytical audiences eventual; trust damage permanent. + +The cure. Defaults reflect audience importance, not brand strength. Honest about competitor strengths. + +--- + +## Default audience or use case + +When the tool asks (or infers) the audience. + +**Pattern A: Pre-selected.** Tool selects an audience based on referrer or query. + +Strengths. Lower friction; tool seems intelligent. + +Weaknesses. Inference can be wrong. + +**Pattern B: Asked upfront.** Tool asks "what is your role?" or "what is your team size?" + +Strengths. Accurate; user controls. + +Weaknesses. Adds friction; some audiences skip. + +**Pattern C: No audience selection.** Tool shows comparison; user can filter. + +Strengths. Lowest friction; works for all audiences. + +Weaknesses. Generic; no per-audience recommendation. + +The choice depends on the tool's complexity and the audience's diversity. + +--- + +## Default recommendation + +What the tool recommends by default. + +**Pattern A: Single default recommendation.** "For most teams, [option] is the best choice." + +Strengths. Clear; opinionated. + +Weaknesses. May not fit all visitors. + +**Pattern B: Audience-conditional default.** Recommendation changes based on audience selection. + +Strengths. Fits different audiences. + +Weaknesses. More complex. + +**Pattern C: No default recommendation.** Tool requires user to specify before recommending. + +Strengths. User commits; recommendation is matched. + +Weaknesses. Higher friction. + +The discipline. Whatever default, the recommendation is honest about who it is for. + +--- + +## Bias-flattering defaults: the failure + +Patterns that destroy trust. + +**Defaults set for brand victory.** Comparison tool defaults to axes where the brand wins, hides where it loses. + +**Defaults that frame in brand's terminology.** Other options compared in vocabulary that favors the brand's positioning. + +**Defaults that misrepresent competitor pricing.** Showing competitor's most expensive plan vs brand's mid-tier. + +**Defaults that show outdated competitor info.** Listing features competitors have updated. + +**The audience reaction.** Sophisticated audiences notice; trust collapses; brand earns "manipulative" reputation. + +--- + +## Honest defaults with disclosure + +When the brand legitimately stands out, honest framing matters. + +**The pattern.** "Default view shows the comparison most relevant to teams of [size]. Your situation may differ; use filters to adjust." + +**Disclosure where defaults are brand-favorable.** "We are highlighting [axis] because we think it matters most for [audience]. Let us know if you weigh things differently." + +The honest framing earns trust where bias-flattering loses it. + +--- + +## Default maintenance + +Defaults decay. + +**What decays.** + +- Default options no longer match audience consideration. +- Default axes no longer the most relevant. +- Default audiences shifted. + +**Maintenance cadence.** Quarterly review. Update as competitive landscape and audience composition shift. + +--- + +## Common default failures + +**Hide-where-we-lose.** Bias detected; trust collapses. + +**Stale defaults.** Competitor info outdated. + +**Wrong default audience.** Inference produces unfit comparison for visitor. + +**No default at all.** Tool requires extensive setup before showing comparison. + +**Default obscures methodology.** Defaults look like neutral; methodology is biased. + +**Default ignores recent competitor changes.** Defaults from 6 months ago. + +--- + +## Methodology-level choices that stay in the public skill + +The honest-default principle. Default options. Default axes. Default audience or use case. Default recommendation. The bias-flattering failure pattern. Honest defaults with disclosure. Default maintenance. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific comparison tools. Specific audience inference logic. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md new file mode 100644 index 0000000..2d5addb --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md @@ -0,0 +1,225 @@ +# Filter and toggle patterns + +What users can adjust, what should stay fixed. The filter-fatigue trap. + +Filters and toggles let users adapt the comparison to their context. Done well, filters help users match the tool to their situation; done poorly, filters become customization theater that adds complexity without value. + +--- + +## The help-don't-customize principle + +Filters earn placement when they help users match the comparison to their context. Filters for the sake of customization options add complexity without lift. + +**The win.** Tool offers 3 filters: audience size, use case, must-have integrations. Each filter materially adapts the recommendation. Users find their context quickly. + +**The fail.** Tool offers 15 filters across multiple dimensions. Decision paralysis at the filter step; users abandon before reaching the comparison. + +The discipline. Filters that help; not filters for theater. + +--- + +## Filterable elements + +What users can adjust. + +**Options to compare.** User adds or removes options. + +**Axes to show.** User filters to relevant dimensions. + +**Audience or use case.** User signals their context; tool adapts. + +**Pricing model preference.** User selects monthly vs annual; per-seat vs flat. + +**Region or geography.** User selects where they operate; tool adapts to applicable options. + +--- + +## Fixed elements + +What should not be filterable. + +**Methodology disclosure.** Always visible. + +**Recommendation reasoning.** Always findable. + +**Source citations.** Always linkable. + +**Honest framing.** Tool is honest about its biases regardless of filter state. + +--- + +## Filter UI patterns + +How filters appear. + +**Pattern A: Top-of-page filters.** + +How it works. Filter row at top; user adjusts; comparison below updates. + +Strengths. Visible; familiar. + +Weaknesses. Takes screen space; mobile-challenging. + +**Pattern B: Sidebar filters.** + +How it works. Filter panel on the side; comparison main area. + +Strengths. Persistent; works on desktop. + +Weaknesses. Mobile-broken; takes space. + +**Pattern C: Inline filters.** + +How it works. Filters appear within the comparison (per-axis filtering, per-option toggling). + +Strengths. Contextual. + +Weaknesses. Visual complexity. + +**Pattern D: Wizard-style.** + +How it works. Tool asks 2-3 filter questions; then shows comparison. + +Strengths. Less overwhelming. + +Weaknesses. Adds friction upfront. + +The choice depends on filter complexity and audience preferences. + +--- + +## Filter count + +How many filters earn placement. + +**3-5 filters.** Sweet spot. Each filter helps; cumulative friction manageable. + +**6-8 filters.** Acceptable for complex tools; require strong UX. + +**10+ filters.** Almost always too many. Decision paralysis at filter step. + +**1-2 filters.** Often too few; tool feels rigid. + +--- + +## Filter defaults + +What filters are pre-set. + +**Honest defaults.** Reflect typical audience. + +**Audience-detected defaults.** Inferred from referral or context. + +**No defaults (user must select).** Adds friction but ensures intentionality. + +The default discipline. Defaults reflect audience importance; not brand strength. + +--- + +## Filter combinations + +When filters interact. + +**Independent filters.** Each filter changes one dimension; combinations multiply. + +**Conditional filters.** Some filters appear only after others are set. + +**Smart filters.** Tool suggests filters based on earlier selections. + +The discipline. Combinations should produce meaningful comparisons; not empty cells. + +--- + +## The filter-fatigue trap + +Too many filters; user paralyzed. + +**The pattern.** Tool offers 12 filters. User feels they need to set them all to get meaningful comparison. User leaves before completing. + +**The signal.** Drop-off at the filter step; users do not reach the comparison. + +**The cost.** Comparison tool's main value (the comparison) is invisible. + +**The cure.** Reduce filter count. Default-heavy. Optional filters behind a "more options" toggle. + +--- + +## The under-filtered trap + +Tool too rigid; user cannot match context. + +**The pattern.** Tool shows one fixed comparison; no way to adapt. + +**The signal.** Users complain the tool does not fit them; specific segments convert poorly. + +**The cost.** Tool serves only the audience the default fits. + +**The cure.** Add filters where audience genuinely splits. + +--- + +## Filter mobile design + +Filters on mobile have specific considerations. + +**Mobile-specific patterns.** + +- Filters in a collapsible drawer rather than always-visible panel. +- Reduced filter count on mobile (defer non-critical filters). +- Touch-friendly toggles. + +**Mobile-broken patterns.** + +- Sidebar filters cramping the comparison. +- Top-of-page filters that scroll off and require scrolling back. +- Filter modals that take over the screen. + +The mobile discipline. Filters work on mobile or do not exist there. + +--- + +## Filter analytics + +Track filter use. + +**Metrics.** + +- Per-filter use rate. +- Filter abandonment (started filtering; left without completing). +- Filter combinations that produce no results. + +**Diagnostic uses.** + +- Filter rarely used: it may not earn placement. +- Filter abandonment high: too many filters or bad defaults. +- No-result combinations: filter logic may have gaps. + +--- + +## Common filter failures + +**Too many filters.** Filter fatigue. + +**Too few filters.** Tool too rigid. + +**Filters with no value.** Filters that do not change anything meaningful. + +**Filters that produce empty results.** Combinations show no options. + +**Mobile-broken filters.** Filters work on desktop, fail mobile. + +**Filter UX inconsistent.** Mix of patterns; users confused. + +**Default filters bias-flattering.** Defaults make brand look better than reality. + +**No filter analytics.** Cannot tell which filters earn their place. + +--- + +## Methodology-level choices that stay in the public skill + +The help-don't-customize principle. Filterable vs fixed elements. Filter UI patterns A through D. Filter count. Filter defaults. Filter combinations. The filter-fatigue and under-filtered traps. Filter mobile design. Filter analytics. Common failures. + +## Implementation choices that stay internal + +Specific filters for specific tools. Specific filter UI implementations. Specific defaults. The team's mobile testing benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md b/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md new file mode 100644 index 0000000..37df188 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md @@ -0,0 +1,201 @@ +# Honest recommendation discipline + +The discipline that distinguishes hidden from honest recommendations. + +Recommendations are powerful. Honest ones earn trust; hidden ones erode it. The discipline is to know which kind your tool produces. + +--- + +## The litmus test + +A sophisticated user from the target audience tests the tool by selecting a clearly wrong-fit scenario for the brand. Does the tool recommend a competitor when fit warrants? + +**The win.** Tool recommends competitor X for the wrong-fit scenario, with reasoning. The sophisticated user trusts the tool because it is willing to recommend against the brand. + +**The fail.** Tool always recommends the brand regardless of scenario. The sophisticated user catches the pattern; trust collapses. + +The discipline. The tool's willingness to recommend competitors when warranted is the trust marker. + +--- + +## What honest recommendation looks like + +Five marks of honesty. + +**Mark 1: Brand does not always win.** When competitors fit better, tool says so. + +**Mark 2: Reasoning is specific and verifiable.** "Option B has X capability that Option A lacks" rather than "B is better." + +**Mark 3: Audience-fit is articulated.** "For [audience] with [needs], choose X. For different audience, choose Y." + +**Mark 4: Tradeoffs acknowledged.** "Option X wins on capability A but loses on capability B." + +**Mark 5: Methodology disclosed.** Users can see how the recommendation was generated. + +When all five are present, the recommendation is honest. When any are absent, hidden-recommendation dynamics creep in. + +--- + +## What hidden recommendation looks like + +Five marks of hidden bias. + +**Mark 1: Brand always wins regardless of scenario.** + +**Mark 2: Reasoning is generic ("best in class") without specifics.** + +**Mark 3: Audience-fit not articulated; one recommendation for all.** + +**Mark 4: Tradeoffs not acknowledged; brand presented as superior on all axes.** + +**Mark 5: Methodology hidden or vague.** + +When these patterns combine, the tool is hidden-recommendation regardless of whether the team intended bias. + +--- + +## The acknowledge-competitor-strengths principle + +Honest recommendation tools acknowledge where competitors are stronger. + +**The pattern.** "Competitor X has the strongest [capability]. We win on [different capability]. For audiences prioritizing [first], X. For audiences prioritizing [second], us." + +**Why it works.** Acknowledging strengths signals honesty. Audiences trust the recommendation more because the tool is willing to lose on specific axes. + +**The reluctant-acknowledgment failure.** Acknowledging competitor strengths only when forced; minimizing them where possible. Detection by sophisticated audiences eventual. + +--- + +## The recommendation-defense quality + +How well the tool defends its recommendation. + +**Strong defense.** + +- Specific to audience. +- Tied to specific axes where the recommended option wins. +- Includes tradeoffs. +- Cites data or sources. + +**Example.** + +"For mid-market teams (50-200 users): Option B. Reasons: B's pricing scales better at 200+ users, B's [specific feature] is unmatched, B's support response time is fastest. Tradeoff: B's onboarding is longer than Option A's. For under-50-user teams, Option A may serve better." + +**Weak defense.** + +- "B is the best choice." +- "Most teams choose B." +- Generic claims. + +The defense earns trust through specificity and acknowledged tradeoffs. + +--- + +## Audience-segment recommendations + +Different audiences may warrant different recommendations. + +**Patterns.** + +- "Solo and small teams: choose A." +- "Mid-market: choose B." +- "Enterprise: choose C." + +**Why this works.** Audiences self-identify; tool serves each. + +**The single-recommendation-fits-all failure.** One recommendation for diverse audiences misses fit. + +The discipline. When audiences differ, recommendations differ. + +--- + +## When the recommendation should be no-recommendation + +Sometimes "we cannot tell which is best for you" is the honest answer. + +**Patterns.** + +- "Both options fit teams in your situation; differentiator is [factor] you should weigh personally." +- "If [criterion] matters most to you, X. If [criterion] matters most, Y. We cannot rank for you." + +**Why this works.** Honest about the limits of recommendation; respects user agency. + +**The over-recommend failure.** Recommending in cases where genuine differentiator does not exist; trust suffers when users notice. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +**Disclosure patterns.** + +- "We weight [axes] heavily because [reasons]." +- "If you weigh different axes, your recommendation may differ." +- "Our methodology is described here." + +**The audience that questions.** Some users will dig. Methodology should hold up. + +--- + +## The recommendation-audit pattern + +Periodically test the tool's honesty. + +**Audit method.** + +- Test scenarios where competitors should win. +- Test scenarios where brand should win. +- Test edge cases. + +**Audit findings.** + +- Tool always recommends brand: hidden-recommendation; redesign. +- Tool sometimes recommends competitors: honest; verify the recommendations make sense. +- Tool refuses to recommend: may be appropriate for genuine ties; should not be default. + +The audit catches drift. Honest tools at launch can become hidden-recommendation through small changes over time. + +--- + +## Honest recommendation maintenance + +Honest recommendations decay. + +**What decays.** + +- Reasoning based on outdated capabilities. +- Audience-segment definitions that no longer fit. +- Methodology that no longer matches the tool's logic. + +**Maintenance cadence.** Quarterly review. Verify reasoning still holds; verify methodology matches implementation. + +--- + +## Common honest-recommendation failures + +**Brand always wins.** Hidden-recommendation; trust risk. + +**No defense.** Recommendations without reasoning. + +**Generic recommendations.** "Best for most teams" without specificity. + +**Single recommendation for diverse audiences.** Missed fit. + +**Tradeoffs hidden.** Brand presented as superior on all axes. + +**Methodology vague.** Users cannot inspect. + +**No competitor-strength acknowledgment.** Trust suffers. + +**Stale recommendation.** Reasoning based on outdated info. + +--- + +## Methodology-level choices that stay in the public skill + +The litmus test. Five marks of honest recommendation. Five marks of hidden recommendation. The acknowledge-competitor-strengths principle. Recommendation defense quality. Audience-segment recommendations. When no-recommendation is honest. Recommendation transparency. The audit pattern. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific recommendation logic for specific tools. Specific audience-segment mappings. Specific methodology copy. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md b/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md new file mode 100644 index 0000000..28b7c77 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md @@ -0,0 +1,172 @@ +# Recommendation engine design + +When to recommend, how to defend, override path. + +Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible, visible, and not the only path. + +--- + +## The visible-defended-overridable principle + +Recommendations are most useful when: + +- Visible. Users can see what the tool recommends. +- Defended. Reasoning is explicit. +- Overridable. Users who weigh things differently can choose otherwise. + +**The win.** Tool recommends "Option B for mid-market teams prioritizing scale." Recommendation prominent; reasoning shown; user can switch audience or pick differently. + +**The fail.** Tool dumps features; user must decide alone. + +The discipline. Recommend with reasoning; respect override. + +--- + +## Recommendation patterns + +Common patterns. + +**Pattern A: Single recommendation.** "For [audience], choose [option] because [reasons]." Clear; opinionated. + +**Pattern B: Multi-segment recommendation.** "If [A], choose X. If [B], choose Y." + +**Pattern C: Conditional recommendation.** "If [factor] matters most, X. If [other], Y." + +**Pattern D: Recommendation with caveat.** "We think X fits most teams in your situation, with these caveats." + +**Pattern E: No recommendation.** Rarely the right choice. + +--- + +## Defending the recommendation + +The reasoning shown. + +**Strong defense.** Specific reasons tied to recommended option's strengths; audience-fit articulated; tradeoffs acknowledged. + +**Example.** "For mid-market teams: Option B. B's pricing scales better at 200+ users (X% vs Y%), B's integration with [tool] is faster, B's support response is shortest in this tier. Tradeoff: B's interface is less polished than Option A; A wins for teams under 50." + +**Weak defense.** "B is our recommendation"; "B is best for most teams"; generic claims. + +The defense earns trust through specificity. + +--- + +## The override path + +How users can choose otherwise. + +**Visible alternative paths.** + +- Toggle to switch recommended audience. +- Filter to weight axes differently. +- Direct selection of different option. + +**Friction balance.** + +- Override findable in 1-2 clicks. +- Override does not require restart. +- Override preserves user context. + +The discipline. Override is honest; users who disagree are not punished. + +--- + +## Recommendation framing + +How recommendations are worded. + +**Strong framing.** Specific to audience; tied to reasoning; acknowledges tradeoffs; inviting override. + +**Weak framing.** "Obviously X is best"; "most experts agree X"; "X is the only choice for serious teams." + +What works. Specificity, humility, agency for the user. + +--- + +## Audience-fit recommendations + +Different audiences may warrant different recommendations. + +**The pattern.** Tool detects or asks about audience; recommendation adapts. + +**Detection methods.** + +- Referrer or query. +- Stated input. +- Inferred from context. + +The discipline. Audience signals inform recommendation; do not stereotype. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +**Methodology disclosure.** + +- "We weight [axes] heavily because [reasons]." +- "If you weigh [factor] differently, your recommendation may differ." + +The audience that questions. Some users will dig; methodology should hold up. + +--- + +## The recommendation-bias risk + +Recommendations are powerful; biased ones damage trust. + +**Common biases.** + +- Recommending brand in all cases. +- Recommendations always benefit recommender. +- Hidden weighting toward brand strengths. + +**The trust-collapse.** When users catch bias, they stop trusting entirely. + +**The cure.** Acknowledge competitor strengths. Recommend competitors when fit warrants. Honest about who is recommending whom. + +--- + +## Recommendation testing + +Validate. + +**Methods.** + +- User research: do recommendations match what audiences would have chosen with full information? +- Cohort analysis: do recommendation-followers retain better? +- Sales feedback: do recommended-option leads convert at higher rates? + +The discipline. Recommendation is hypothesis until validated. + +--- + +## Common recommendation failures + +**No recommendation.** Tool lists; users decide alone. + +**Hidden recommendation.** Tool defaults bias toward one option without disclosure. + +**Generic recommendation.** "Best for most teams" without specificity. + +**Single recommendation for diverse audiences.** Missed fit. + +**Recommendation without defense.** Authoritative without reasoning. + +**No override path.** Users who disagree have no clear alternative. + +**Recommendation always favors brand.** Trust collapses. + +**Stale recommendation.** Reasoning based on outdated capabilities. + +--- + +## Methodology-level choices that stay in the public skill + +The visible-defended-overridable principle. Patterns A through E. Defending the recommendation. The override path. Framing. Audience-fit recommendations. Transparency. The bias risk. Testing. Common failures. + +## Implementation choices that stay internal + +Specific recommendation engines for specific tools. Specific audience-segment mappings. Specific reasoning copy. The team's validation processes. These vary by team. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md b/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md new file mode 100644 index 0000000..0eee8fd --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md @@ -0,0 +1,191 @@ +--- +name: competitor-experience-audit +description: "Audit the brand, UX, and site design of the leading sites in a vertical as a set of observable cross-site patterns, producing the experience bar a new build must meet or beat. Use this skill whenever the user wants to assess the competitive design field, capture vertical conventions, identify the design and UX bar of a category, or set the experience standard before a build. Triggers on competitor experience audit, UX audit, site design audit, brand audit, design conventions, what makes these sites good, vertical conventions, storefront patterns, merchandising patterns, layout density, primary task, design bar, category conventions, retail vs marketing register, what does the field do. Also triggers when an audit of the competitive field has captured technical signals (SEO, accessibility) but never named the brand, UX, or design conventions, and the build downstream will read as off-vertical without that bar." +category: research +catalog_summary: "Cross-site experience patterns and gaps across a vertical" +display_order: 6 +--- + +# Competitor Experience Audit + +Capture the brand, UX, and site design that the leading sites in a vertical observably share, and where they fall short. The output is the experience bar a new build must meet or beat, grounded in cross-site patterns rather than aesthetic opinion. + +Stack-agnostic. Works on any SiteShape (ecommerce-catalog, inventory-listing, hospitality-food, b2b-manufacturer, and so on). Auto-parts catalogs are the first test case, not the only target. + +This skill is the brand / UX / design counterpart to a technical audit like `seo-onpage` or `accessibility-audit`. Technical findings are objective (a missing canonical is missing). Design is more subjective, so this skill is deliberately written to make the subjective assessable: every dimension is judged by observable questions about what the leading sites actually do, reported as patterns and gaps, and marked `not_assessable` whenever the evidence does not support a judgment. + +--- + +## When to use + +- Setting the experience bar for a new build in a vertical you have not built in before +- Capturing the design and UX conventions a credible site in the category is expected to carry +- Auditing the competitive field for a critic or strategy review where SEO and accessibility have been covered but design and experience have not +- Naming the positioning opportunity that recurs across the leaders (the gap even the leaders share) +- Pairing with a technical audit (SEO, accessibility) so the competitor review captures both axes + +## When NOT to use + +- Rating a single page or one brand's design taste in isolation (use `design-standards` or `brand-style-guide` for production design decisions on a known build) +- Backlink, keyword, or SERP-overlap competitive analysis (use `seo-competitor`) +- Generating a creative direction from scratch for a new brand (use `creative-direction` and `brand-discovery`) +- User research with real participants on your own product (use `ux-research`, `usability-testing`) +- Auditing a single page's on-page SEO or accessibility against the audit suite (use `seo-onpage`, `accessibility-audit`) + +--- + +## Required inputs + +- The vertical and a list of the leading sites in it (3 to 6 sites; more than 6 stops surfacing new patterns) +- Access to the rendered sites (a real browser view, not just static HTML; see "Static vs rendered" below) +- The site shape the audit feeds, if known (ecommerce-catalog, inventory-listing, etc.); this scopes which dimensions to weight +- Any explicit constraint on the build downstream (the brand voice, the audience, the conversion the build will own) + +If the list of leading sites is unknown, ask. Picking the wrong field produces an experience bar against the wrong vertical. + +### Static vs rendered + +Some dimensions can be partially assessed from static HTML (primary navigation, the catalog/category surface count, the presence of search). Most cannot. Layout density, brand register, motion, trust-signal prominence, and the rendered hierarchy of the first viewport all need the rendered page to judge honestly. If you only have static HTML for a site, mark every rendered-only dimension `not_assessable` for that site rather than guessing. + +--- + +## The framework: 7 experience dimensions + +Each dimension is judged by observable questions across the leading sites in the field, then reported as a cross-site pattern plus the gap (where the leaders converge, and where even they fall short). + +Score each dimension as `Pattern present` (the field converges on a recognizable convention), `Mixed` (the field splits across two or three approaches), or `Gap` (no convention emerges, or every leader misses it). Mark `not_assessable` when the evidence cannot support a judgment. + +Never write `Good design` or `Bad design` or any aesthetic verdict. The dimensions are about what the field observably does, not whether you like it. + +### 1. Primary-task prominence + +Does the site lead with the visitor's primary job, or bury it? + +- What is the largest, earliest interactive element on the first viewport? (For auto-parts: typically a fitment selector. For hospitality-food: a menu or reservation entry.) +- How many clicks or scrolls to the core task? +- Does the site protect the primary task from competing CTAs in the hero? + +Observable signal: count the elements that compete for first attention, identify which one the layout actually privileges, name what the field converges on as the primary task. + +### 2. Layout register and density + +Is the layout retail-dense, editorial, or marketing-airy? Cross-reference `creative-direction` aesthetic positions (editorial restrained, polished standard, controlled maximalist, expressive maximalist) for vocabulary; do not redefine that here. + +- How many distinct modules appear above the fold? +- What is the content-per-viewport ratio (dense storefront, calm editorial, generous marketing)? +- Does the page read as a storefront, a catalog, a landing page, or a brochure? + +Observable signal: count modules above the fold across the field; describe the register the leaders share, not whether you find it attractive. + +### 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape? + +- How many category, collection, or entry-point modules appear before scroll? +- How is depth signaled (mega-menu, grid, side rail, faceted search)? +- Is the surface flat (one tier visible) or hierarchical (parent plus child categories shown together)? + +Observable signal: count the category entry points and describe the navigation depth pattern the field uses. + +### 4. Primary navigation and search paths + +Do the sites serve both the know-what-I-want path and the browse path? + +- Is search prominent and primary, secondary, or absent? +- What paths are offered (by category, by brand, by attribute, by vehicle, by location, by occasion)? +- Where does the primary nav sit (top, side, sticky, mega-menu)? + +Observable signal: list the paths the field offers, score whether each path is primary, secondary, or missing. + +### 5. Brand register and conviction + +What brand posture do the leading sites take, and is it consistent across the page? + +- Color, type, imagery: utilitarian, premium, friendly, institutional, technical, expressive? +- Voice in headings and microcopy: direct, persuasive, technical, warm, plain? +- Trust signals: institutional (long-standing, association badges), social (reviews, community), or operational (in-stock, warranty, fitment confirmation)? + +Cross-reference the `creative-direction` and `brand-archetype-system` skills for the vocabulary. Report the register the field converges on. Do not rate the taste; describe what posture the leaders take. + +### 6. Trust and conversion signals + +What recurring trust and conversion conventions does the field use? + +- Reviews, guarantees, social proof, badges +- Pricing transparency (price visible, no surprises, total cost surfaced) +- Stock and availability signals +- Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it) +- Return, shipping, or service-level promises + +Observable signal: which signals appear across the field, where they appear, and which the leaders share. + +### 7. Recurring vertical conventions (the synthesis) + +The patterns that recur across the leaders and define what a credible site in this vertical is expected to have. This is the synthesis of dimensions 1 through 6 into a short list of "if your build does not do this, it will read as off-vertical." + +Observable signal: which conventions recur on 3 of N or more of the leading sites; which are absent across the field (the gap that a positioning opportunity exploits). + +--- + +## The honesty guardrail (load-bearing) + +This is not negotiable. The credibility of an experience audit erodes the moment it slides into taste: + +- Report what the leading sites observably do and where they observably fall short, as cross-site patterns. Do not render personal aesthetic judgments ("this is ugly", "good design", "the typography is clean"). Aesthetic verdicts belong in `art-direction` or `design-standards`, not here. +- When the evidence does not support a judgment, say so plainly and mark the dimension `not_assessable` for that site or that pattern. Common cases: layout and density cannot be judged from un-rendered static HTML; motion and animation cannot be judged from a screenshot; brand voice cannot be judged from a single page. +- Do not name a convention from one site. A pattern is a recurrence across the field (3 of N or more); one site doing something distinctive is a single-site observation, not a convention. +- The output is a grounded experience bar: the conventions and gaps of the field, usable as a standard a build must meet. It is not an opinion piece. + +If the user asks "is this design good", redirect to observable patterns ("the leading sites in the field share X, Y, Z; this build does X and W but not Y or Z; that is the gap"). If the user asks for an aesthetic call, point them at `design-standards` or `art-direction`. + +--- + +## Workflow + +1. **Confirm the vertical and the leading sites.** Ask if either is unclear; an audit against the wrong field is worse than no audit. +2. **Render and view each site as a user would.** Open in a real browser, on the device class the field's visitors use (desktop and mobile for ecommerce; mobile-first for hospitality-food; etc.). Do not work from static HTML alone for any dimension marked rendered-only. +3. **Assess each dimension across the field.** Use [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) to score each site on each dimension. Mark `not_assessable` wherever the evidence is thin. +4. **Synthesize cross-site patterns.** For each dimension, name the recurring convention (or the split, or the gap). Distinguish patterns the field converges on from single-site moves. +5. **Name the gap (the positioning opportunity).** Where do even the leaders fall short? That is where a new build's positioning can exploit the field. +6. **Write the bar.** Use the template in [`references/audit-template.md`](references/audit-template.md). Default output is a markdown experience bar, generalized to pattern-level if it will feed a public showcase workup (no named competitors in the public version). +7. **Hand the bar to the build skills.** The output is the standard `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill (`landing-page-copy`, `frontend-component-build`) read as the experience bar to meet. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Rate the design of these sites."** Vague. Redirect to observable patterns: what the leading sites in the field do across the seven dimensions, not whether you like it. +- **Judging un-rendered pages for layout, density, or motion.** Mark `not_assessable` and get the rendered view. Static HTML supports only partial assessment; do not guess at design quality you cannot see. +- **Naming a convention from one site.** A pattern is a recurrence across the field. One site doing something distinctive is a single-site observation; flag it that way, not as a convention. +- **Substituting personal taste for field patterns.** "I think the colors are good" is not an audit finding. "The field converges on a navy-and-rust register; this site uses it" is. +- **Aesthetic verdicts dressed as observations.** Watch for "clean", "modern", "professional", "premium-feeling" with no observable signal underneath. If you cannot point at a specific observable thing, you are giving taste, not a pattern. +- **Skipping the gap.** An audit that names only what the leaders do well is half the value. The recurring weakness across the field is where a positioning opportunity lives; name it. +- **Generalizing too soon.** A 2-site sample is not the field. If you can only render 2 of 5 leaders, mark the audit `partial` and call out what is assessed vs what is not. + +--- + +## Output format + +Default output is a markdown experience bar at `experience-audit-[vertical-slug].md` in the project root. Structure: + +1. Vertical and the field surveyed (sites assessed, what could not be rendered) +2. Score per dimension across the field +3. Cross-site patterns (the conventions the leaders converge on) +4. Gaps (where the field falls short, the positioning opportunity) +5. The experience bar (the synthesis: what a credible build in this vertical must do) +6. `Not_assessable` items (what could not be judged and why) + +Keep the bar under 1500 words. If a dimension needs deeper treatment, link to a deeper appendix rather than expanding inline. + +### Scrub for showcase use + +If the audit will feed a public showcase workup, scrub for named competitors before publishing. The named version stays operated-side; the public workup carries the patterns and the gaps in generalized form. This mirrors how Basano's competitor review already handles named sites in its model-backed audit. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable experience-audit template, copy and use. Generalized and named variants both present. +- [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) - The observable questions per dimension, in scoring order. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md b/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md new file mode 100644 index 0000000..d244e9a --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md @@ -0,0 +1,136 @@ +# Competitor Experience Audit: [Vertical] + +**Site shape:** [ecommerce-catalog / inventory-listing / directory-marketplace / local-service-booking / subscription-app / hospitality-food / institution-mission / b2b-manufacturer / ecommerce-standout / hospitality-experience] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Field assessed:** [N sites] +**Rendered:** [N of N] **Static-only:** [N of N] + +--- + +## Field surveyed + +| Site | Rendered | Notes | +|---|---|---| +| [Site 1] | [yes/no] | [any access caveat] | +| [Site 2] | [yes/no] | | +| [Site 3] | [yes/no] | | +| [Site 4] | [yes/no] | | +| [Site 5] | [yes/no] | | + +If publishing the audit publicly, prepare a generalized version that drops the named column; the named version stays operated-side. + +--- + +## Summary + +[Two to three sentences. The cross-site picture: what the field converges on, where it falls short, what the positioning opportunity is. Generalized; no aesthetic verdicts.] + +| Dimension | Score | One-line pattern | +|---|---|---| +| Primary-task prominence | [Pattern present / Mixed / Gap / Not assessable] | | +| Layout register and density | | | +| Merchandising and category surface | | | +| Primary navigation and search paths | | | +| Brand register and conviction | | | +| Trust and conversion signals | | | +| Recurring vertical conventions | | | + +--- + +## Cross-site patterns + +### 1. Primary-task prominence + +[What the field converges on as the primary task; what element carries it; how protected the task is from competing CTAs. Observable signal: what is the largest, earliest interactive element, and what is the click count to the core task.] + +**Pattern:** [The field's convention] +**Outliers:** [Any leader that breaks the pattern, and what they do instead] + +### 2. Layout register and density + +[The register the field shares (retail-dense, editorial, marketing-airy, hybrid). Cross-reference `creative-direction` aesthetic positions for vocabulary.] + +**Pattern:** [The field's register] +**Outliers:** [Any leader that uses a different register] + +### 3. Merchandising and category surface + +[How much of the offering is surfaced before scroll; the navigation depth pattern; mega-menu vs grid vs side rail.] + +**Pattern:** +**Outliers:** + +### 4. Primary navigation and search paths + +[Which paths the field offers (search-first, by-category, by-brand, by-attribute, by-vehicle, by-location). Score each path as primary / secondary / absent.] + +**Pattern:** +**Outliers:** + +### 5. Brand register and conviction + +[The brand posture the leaders converge on. Cross-reference `creative-direction` and `brand-archetype-system`.] + +**Pattern:** +**Outliers:** + +### 6. Trust and conversion signals + +[Which signals appear across the field (reviews, guarantees, pricing transparency, stock, fitment confirmation, return policy). Where they appear.] + +**Pattern:** +**Outliers:** + +### 7. Recurring vertical conventions + +[The synthesis. The conventions a credible site in this vertical is expected to have, named explicitly. A build that ignores these will read as off-vertical.] + +**Conventions:** +- [Convention 1] +- [Convention 2] +- [Convention 3] +- ... + +--- + +## Gaps (the positioning opportunity) + +[Where even the leaders fall short. The recurring weakness across the field. This is the wedge a new build's positioning can exploit. Observable, not speculative.] + +- **[Gap 1]:** [The weakness the field shares; how it shows up across N of the N leaders; what a build that fixes it would look like.] +- **[Gap 2]:** +- **[Gap 3]:** + +--- + +## The experience bar (the build standard) + +A credible build in this vertical, against this field, must: + +- [Bar item 1 - usually maps to a recurring convention from dimension 7] +- [Bar item 2] +- [Bar item 3] +- ... + +Optional positioning move: + +- [The build's wedge - exploit one or more of the gaps above] + +Hand this bar to `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill so they read as the standard to meet, not as suggestions. + +--- + +## Not assessable + +[Dimensions or sites that could not be judged honestly. Common reasons: site not renderable, motion not capturable, brand voice not derivable from a single page, depth of the category surface only visible after authentication.] + +- **[Dimension or site]:** [Why it cannot be judged from the evidence available. What evidence would be needed to assess it.] +- **[Dimension or site]:** +- ... + +--- + +## Generalized version (for showcase / public use) + +If this audit will feed a public showcase workup or a published critique, copy the sections above into a generalized form that drops the named-competitor column and the Outliers callouts. Patterns and gaps are publishable; named-and-rated competitor breakdowns are not. The named version stays operated-side. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md b/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md new file mode 100644 index 0000000..8313356 --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md @@ -0,0 +1,134 @@ +# Experience Dimensions Checklist + +Score each leading site on each dimension using the observable questions below. Mark `not_assessable` whenever the evidence does not support a judgment; do not guess. The audit's value rests on honest observation. + +The rule for every dimension: name what is observably true across the field, not whether you like it. If you cannot point at a specific observable thing, you are giving taste, not a pattern. + +--- + +## 1. Primary-task prominence + +The visitor arrives with a primary job. The leading sites either lead with that job or bury it. + +- [ ] What is the largest, earliest interactive element on the first viewport? +- [ ] Does that element correspond to the visitor's primary task in the vertical? (Auto-parts: a fitment selector. Hospitality-food: a menu or reservation entry. Inventory-listing: a search or filter. Local-service-booking: a "book now" or service picker.) +- [ ] How many clicks or scrolls from arrival to completing the core task? +- [ ] How many competing CTAs share the hero with the primary task? +- [ ] Is the primary task reachable from a sticky element on scroll? + +Rendered required: **partial.** The primary task can usually be identified from a static fetch (it is in the markup), but its visual dominance and protection from competitors requires the rendered view. + +--- + +## 2. Layout register and density + +Storefront, editorial, marketing-airy, hybrid. Cross-reference `creative-direction` aesthetic positions (editorial-restrained, polished-standard, controlled-maximalist, expressive-maximalist) for vocabulary. + +- [ ] How many distinct modules appear above the fold on a standard desktop viewport? +- [ ] How many on a mobile viewport? +- [ ] What is the content-per-viewport ratio: dense (a catalog or storefront), calm (an editorial), generous (a landing page or brochure)? +- [ ] Where does the page read as a storefront vs a marketing page? +- [ ] Does the whitespace ratio match a retail or a publication register? + +Rendered required: **yes.** Static HTML cannot tell you what users see in the first viewport. + +--- + +## 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape. + +- [ ] How many category, collection, or entry-point modules appear before scroll? +- [ ] How is depth signaled (mega-menu hover, fly-out, side rail, faceted search, breadcrumb expansion)? +- [ ] Is the surface flat (one tier visible) or hierarchical (parent plus child)? +- [ ] Are the categories shown as text, icon, image, or hybrid? +- [ ] Is a search-first path offered alongside the category-first path? + +Rendered required: **partial.** Counts and structure show up in static markup; visual emphasis and reveal patterns need rendering. + +--- + +## 4. Primary navigation and search paths + +The know-what-I-want path and the browse path. Both, or only one. + +- [ ] Is a search input prominent (in the header, large input), secondary (small, in a side panel), or absent? +- [ ] Which paths does the primary nav offer (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience)? +- [ ] Score each available path: primary / secondary / absent. +- [ ] Where does the primary nav sit (top bar, side drawer, mega-menu, sticky)? +- [ ] On mobile, does the primary nav collapse into a hamburger or stay flat? + +Rendered required: **partial.** Path inventory is in the static markup; visual prominence and primary-vs-secondary judgment needs the rendered view. + +--- + +## 5. Brand register and conviction + +The posture the leading sites take and whether they hold it across the page. + +- [ ] Color palette: muted / saturated; warm / cool; monochrome / multi-hue. +- [ ] Typography: humanist / geometric / serif-led / display-led; one face or paired. +- [ ] Imagery: photographic (studio, lifestyle, editorial); illustrated; abstract; none. +- [ ] Voice in headings: direct, persuasive, technical, warm, plain, institutional. +- [ ] Voice in microcopy and CTAs: matches the heading voice or breaks from it. +- [ ] Brand posture: utilitarian / premium / friendly / institutional / technical / expressive. + +Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; use those terms rather than inventing new ones. + +Rendered required: **yes.** Brand register is a visual judgment; static HTML alone cannot support it. + +--- + +## 6. Trust and conversion signals + +The recurring conventions a credible commercial page in this vertical carries. + +- [ ] Reviews / ratings present (where, how prominent, count or average shown). +- [ ] Guarantees (return policy, money-back, warranty) surfaced or hidden. +- [ ] Pricing transparency: price visible without interaction; total cost surfaced before checkout; "starting at" or full? +- [ ] Stock or availability signals (in stock, low stock, lead time). +- [ ] Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it). +- [ ] Shipping or service-level promises (ETA, free over $X, same-day). +- [ ] Institutional trust signals (years in business, association badges, certifications). +- [ ] Social proof (logos of customers, press mentions, testimonials). + +Rendered required: **partial.** Many trust signals are visible in markup; placement and emphasis are rendered judgments. + +--- + +## 7. Recurring vertical conventions (synthesis) + +The patterns that recur across the field define what a credible site in this vertical is expected to have. This is not a new measurement; it is the synthesis of dimensions 1 through 6. + +- [ ] Which conventions appear on 3 of N or more of the leaders? +- [ ] Which appear on fewer than 3 (single-site moves, not conventions)? +- [ ] Which are absent across the field (the gap a positioning opportunity exploits)? + +The output of this dimension is a short list: "If your build does not do X, Y, Z, it will read as off-vertical." That list is what goes into the experience bar. + +--- + +## Scoring rubric + +For each dimension, score the field (not a single site): + +- **Pattern present.** 3 of N or more leaders converge on a recognizable convention. Name it. +- **Mixed.** The field splits across two or three distinct approaches. Name each, and note which the new build should adopt. +- **Gap.** No convention emerges, or every leader misses the dimension. Often this is the positioning opportunity. +- **Not assessable.** The evidence does not support a judgment. Name what evidence would be needed. + +For each site (operated-side only; the public version drops named scores): + +- Mark each dimension `pattern-aligned`, `outlier`, or `not assessable`. + +--- + +## What this checklist will not do + +- Rate a single site's design taste. Use `design-standards` for production design review. +- Tell you which vertical your build belongs in. The vertical and field are inputs to this skill, not outputs. +- Replace user research. Use `ux-research` and `usability-testing` for real-user assessment. +- Generate creative direction from scratch. Use `creative-direction` and `brand-discovery` for that. +- Produce a SERP or backlink competitive analysis. Use `seo-competitor`. + +This checklist names patterns and gaps so a downstream build has a real bar to meet. Everything else is out of scope. diff --git a/dist/pi/.agents/skills/content-and-copy/SKILL.md b/dist/pi/.agents/skills/content-and-copy/SKILL.md new file mode 100644 index 0000000..e8a1f80 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: content-and-copy +description: "Write or edit website copy, blog content, and editorial pieces with attention to voice, structure, and goal. Use this skill whenever the user wants to write an article, draft website copy, edit existing content for clarity or voice, write a blog post, or produce general editorial content. Triggers on write a blog post, draft an article, write copy for, edit this, rewrite this, write content, write a guide, draft a how-to, write web copy. Also triggers when content has been outlined and now needs to be written, or when existing content needs voice or clarity edits." +category: content +catalog_summary: "Website copy, blog content, content production frameworks" +display_order: 3 +--- + +# Content and Copy + +Write or edit content that serves a specific reader and goal. Stack-agnostic. This skill is for general content production. Specialized skills exist for landing pages (`landing-page-copy`) and email (`email-sequences`). + +--- + +## When to use + +- Writing a blog post or article +- Drafting website copy (homepage sections, about, services) +- Editing existing content for voice or clarity +- Writing how-to guides, listicles, or explainers +- Producing knowledge base or help center articles +- Adapting brand voice to a specific piece + +## When NOT to use + +- Landing pages with conversion goals (use `landing-page-copy`) +- Email campaigns or sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- SEO keyword research (use `seo-keyword`) +- Content strategy and planning (use `content-strategy`) + +--- + +## Required inputs + +- The piece to be written or edited +- The target reader (specific audience segment) +- The goal of the piece (inform, convert, rank, retain, entertain) +- The brand voice (or willingness to define it) +- Length target and any structural constraints + +If brand voice is undefined, run `brand-voice` first or use a working voice and document it as you go. + +--- + +## The framework: 5 dimensions + +Strong content is strong on all five. Weakness on any one drags the rest down. + +### 1. Hook + +The opening earns the read. Most readers decide whether to continue within 3 to 5 seconds. + +**Strong hooks do one of:** + +- **Promise specific value.** "By the end, you'll know exactly which X to pick for your situation." +- **Surface a tension.** "Most advice on X is wrong. Here's why." +- **Open a loop.** A question or scenario the rest of the piece resolves. +- **State a contrarian point.** Provided you can defend it. +- **Show, don't summarize.** A specific moment or scenario the reader recognizes. + +**Weak hooks:** + +- Throat-clearing ("In today's fast-paced world...") +- Dictionary-definition openers ("X is a type of Y that...") +- Stating the obvious ("Many people struggle with X.") +- Vague promises ("This article will explore X.") + +### 2. Structure + +The reader follows the flow without effort. + +**Common structures:** + +- **Problem → Solution → Proof.** Most non-fiction. +- **List + reasoning.** Listicles with substance, not filler. +- **How-to (numbered steps).** Procedural content. +- **Compare → Contrast → Recommend.** Comparison and review content. +- **Story → Lesson.** Narrative non-fiction. +- **Question → Answer → Implication.** Explainers and analysis. + +Pick a structure. Stick to it. Most weak content fails because the writer drifted between structures. + +### 3. Voice + +The piece sounds like the brand. + +- Voice attributes consistent throughout (per `brand-voice` definition) +- Tone shifts appropriately for context (a serious topic gets a serious tone, even from a playful brand) +- Vocabulary preferences honored +- Grammar and style standards followed (contractions, em dashes, sentence length) +- Reads aloud like the brand would actually talk + +**Test:** Read a paragraph aloud. Does it sound like the brand? If it sounds like AI, generic marketing, or someone else's voice, edit until it doesn't. + +### 4. Substance + +The piece earns its length. Every paragraph adds something. + +**Substance comes from:** + +- **Specifics.** "Roughly 40 percent" beats "many." Names, numbers, examples, data. +- **Original perspective.** Your take, not a summary of everyone else's. +- **Actionable detail.** What the reader does with this information. +- **Honest tradeoffs.** What's NOT true, what doesn't work, what's overhyped. +- **Real examples.** Specific scenarios, real customers, real failures. + +**Lack of substance shows up as:** + +- Padding ("It's important to note that...") +- Restating the same point in three different paragraphs +- Generalities that anyone in the category could write +- Word counts hit by stretching, not depth + +### 5. Closing + +The piece ends with intention. + +**Strong closings:** + +- **Resolve the loop opened in the hook.** +- **Issue a specific next action.** What does the reader do now? +- **Land a memorable line.** Something quotable. +- **Return to the opening.** Echo or invert the first line. + +**Weak closings:** + +- Summary that restates the article +- "Hope this helps!" or equivalent +- A wall of CTAs from unrelated programs +- Trailing off with no clear ending + +--- + +## Workflow + +### For new pieces + +1. **Confirm the brief.** Reader, goal, length, voice. If the brief is vague, do not write yet. +2. **Outline.** Structure first. Headlines and section purposes only. Skip prose until the structure is sound. +3. **Open with the hook.** Write the opening before anything else. If the hook isn't working, the rest won't either. +4. **Draft for substance.** First draft is about getting the substance down. Voice comes in editing. +5. **Edit for voice.** Read aloud. Tighten sentences. Cut padding. Apply brand voice. +6. **Edit for clarity.** Each paragraph: does it earn its place? Each sentence: is the meaning unambiguous? +7. **Pre-publish checks.** Headers in order, no skipped levels, internal links present, image alt text written, SEO basics applied (title, meta, slug). + +### For editing existing content + +1. **Read the whole piece first.** Do not edit on first read. Understand it before changing it. +2. **Identify what's working.** Note the strong sections so you don't damage them. +3. **Identify what's broken.** Voice mismatches, weak structure, vague claims, padding. +4. **Edit by priority.** Structure first (move sections, cut sections). Then substance (strengthen claims). Then voice. Then sentence-level polish. +5. **Read aloud.** Catch awkward phrasing the eye misses. + +--- + +## Failure patterns + +- **Writing without a brief.** Without reader, goal, and voice defined, the piece drifts. +- **Burying the lead.** The most important thing is in paragraph 8 because the writer "got there." +- **Padding to hit word count.** Length should serve the reader, not the production schedule. +- **Generic voice.** Sounds like every other article in the category. Brand voice neutralized. +- **Weak transitions.** Sections feel disconnected. Reader has to do the work the writer should have done. +- **No closing.** The piece runs out instead of ending. +- **Edit by adding.** Fixing weak content by piling on more words. Strong editing usually cuts. +- **Ignoring the headers.** Headers carry navigation weight. Bad headers fail readers who scan. + +--- + +## Output format + +Default output is a markdown document at `[content-slug].md` ready to import into the CMS. + +Structure: +```markdown +# [H1: matches the title or tightly paraphrases] + +[Hook paragraph. Earns the read in 3 to 5 seconds.] + +[Body content with H2 sections, H3 subsections where useful.] + +## [H2 section heading - descriptive, not clever] + +[Section content.] + +### [H3 if needed] + +[Subsection content.] + +## [H2 section heading] + +[Section content.] + +## [Closing section] + +[Closing that resolves and points to next action.] +``` + +Front-matter for SEO and CMS: +```yaml +--- +title: [SEO title, 50 to 60 chars] +description: [Meta description, 120 to 160 chars] +slug: [url-slug] +author: [author] +date: [YYYY-MM-DD] +last_updated: [YYYY-MM-DD] +tags: [tag1, tag2] +category: [category] +--- +``` + +--- + +## Reference files + +- [`references/content-brief-template.md`](references/content-brief-template.md) - The brief that should exist before any content is written. +- [`references/content-edit-checklist.md`](references/content-edit-checklist.md) - Pre-publish editing checklist. diff --git a/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md b/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md new file mode 100644 index 0000000..d1bc428 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md @@ -0,0 +1,242 @@ +# Content Brief Template + +Every piece of content needs a brief before writing. Without one, the piece will drift, miss the audience, or fail the goal. + +A brief takes 15 minutes to write. Saves hours of rewrites later. + +--- + +## Template + +```markdown +# Brief: [Working title] + +## Reader + +Who specifically is this for? Be precise. + +- Primary audience segment: [from content strategy] +- What they currently know: [their starting point] +- What they want to know: [the question they're bringing] +- What they need to do after: [the action this enables] + +## Goal + +What does this piece accomplish? + +- Primary goal: [Inform / Convert / Rank / Retain / Entertain] +- Specific outcome: [What measurable thing should happen] +- Success metric: [How we know it worked] + +## Pillar / Strategy fit + +- Content pillar this serves: [from content strategy] +- Cornerstone or supporting: [Cornerstone / Supporting] +- Internal links to / from: [related pieces] + +## Angle + +What's the take? Why does this piece exist when others on the topic already do? + +- The angle: [One sentence] +- Why ours is different: [Specific differentiator] +- The contrarian or surprising element: [If any] + +## Format + +- Type: [Article / Guide / Listicle / Comparison / Case study / How-to / Tutorial / Explainer] +- Length: [Word count or range] +- Reading level: [Beginner / Intermediate / Advanced] +- Required elements: [Images, tables, video, downloads, code blocks] + +## Structure + +Section-by-section outline. Headlines + 1 sentence on what each section does. + +### [H1: Working title] + +[Hook approach: how the piece will earn the read in 3 to 5 seconds] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Closing section] +[How the piece resolves and what action it points to] + +## Voice + +- Apply: [Brand voice attributes] +- Tone for this piece: [How tone adjusts for the topic] +- Specific cues: [Anything to lean into or avoid for this topic] + +## Sources and citations + +- Required sources: [Specific data, studies, or experts to cite] +- Internal data: [Anything we have that competitors don't] +- Quotes from: [SMEs, customers, founders to include] + +## SEO + +- Primary keyword: [from keyword research] +- Secondary keywords: [supporting terms] +- Search intent: [Informational / Commercial / Transactional / Navigational] +- Target SERP feature (if any): [Featured snippet / People also ask / etc.] +- Title tag (50-60 chars): [Draft] +- Meta description (120-160 chars): [Draft] +- URL slug: [Draft] + +## Distribution + +Where and how this piece gets seen after publishing. + +- Newsletter inclusion: [Yes/No] +- Social posts: [Number of variations and channels] +- Outreach: [Specific people or sites to ping] +- Internal links to add from: [Existing pieces that should link to this] + +## Constraints and notes + +- Deadline: [Date] +- Word count: [Target] +- Required approvals: [Who needs to sign off] +- Things to avoid: [Anything off-limits for this piece] + +## Out of scope + +What this piece is explicitly NOT about. Prevents scope creep during writing. + +- [Topic not in this piece] +- [Topic not in this piece] +``` + +--- + +## Filled example + +```markdown +# Brief: How to choose between SQL and NoSQL for a startup + +## Reader + +- Primary audience segment: Technical founders or first engineers at early-stage startups (under 20 employees) +- What they currently know: Basics of databases, used both SQL and NoSQL casually +- What they want to know: Which to pick for their specific situation, what they'll regret in 18 months +- What they need to do after: Make the database choice and feel confident enough to commit + +## Goal + +- Primary goal: Inform (with rank as a secondary) +- Specific outcome: Reader makes the decision and references this piece when others ask +- Success metric: Top 3 ranking on "SQL vs NoSQL for startups" within 6 months; 5+ minute average read time + +## Pillar / Strategy fit + +- Content pillar: Startup engineering decisions +- Cornerstone or supporting: Cornerstone for the pillar +- Internal links: from "Founder's guide to technical debt" and to "When to migrate your database" + +## Angle + +- The angle: Most articles compare SQL and NoSQL on technical features. We compare on regret-likelihood at 18 months in production. +- Why ours is different: Built around real failure modes, not theoretical capabilities +- Surprising element: Most startups regret choosing NoSQL for the wrong reasons, not the right ones + +## Format + +- Type: Long-form decision guide +- Length: 2,500 to 3,500 words +- Reading level: Intermediate +- Required elements: Decision flowchart, 2-3 case examples, comparison table + +## Structure + +### H1: How to choose between SQL and NoSQL for a startup + +Hook: Open with a specific founder's regret moment from a real conversation. + +### H2: The wrong question (and the right one) +Most teams ask "which is faster" or "which scales." Reframe to "what will I regret in 18 months." + +### H2: When SQL is the right call +Specific scenarios with examples. + +### H2: When NoSQL is the right call +Narrower scenarios than most articles claim. + +### H2: The hybrid that works +Real-world pattern: SQL primary, targeted NoSQL for specific use cases. + +### H2: A decision flowchart +The actionable diagram. The piece's main asset. + +### H2: What to do if you've already chosen wrong +Migration realism, with specific signals it's time to switch. + +### H2: Closing +Return to the opening founder. Where they ended up. The decision framework as the takeaway. + +## Voice + +- Apply: Direct, experienced, not-academic +- Tone: Slightly weary about industry overcomplication +- Specific cues: First-person plural ("we"), war-story examples preferred over textbook explanations + +## Sources + +- Internal: Conversations with [N] startup CTOs +- External: [List of specific studies, posts, papers] +- Quotes: [Names if any] + +## SEO + +- Primary keyword: SQL vs NoSQL startup +- Secondary: SQL vs NoSQL for small teams, when to use NoSQL, NoSQL mistakes startups +- Search intent: Informational with commercial undertone +- Target SERP feature: Featured snippet for "when to use NoSQL" +- Title tag: SQL vs NoSQL for Startups: How to Avoid 18-Month Regret +- Meta: A practical guide to picking a database when you're 5 engineers, deciding fast, and don't want to migrate twice. Includes a decision flowchart. +- URL slug: sql-vs-nosql-startup + +## Distribution + +- Newsletter: Feature in next issue +- Social: 3 LinkedIn variations, 1 X thread +- Outreach: Email to 5 startup engineering newsletter writers +- Internal links: Add from /resources/cto-decisions and /technical-debt-guide + +## Constraints + +- Deadline: [Date] +- Word count: 3,000 target +- Approvals: Editorial lead and one technical SME +- Avoid: Vendor-specific recommendations (we're not selling a product) + +## Out of scope + +- Specific NoSQL database comparisons (CouchDB vs MongoDB) - separate piece +- Schema design tutorials - separate piece +- ORM choice - separate piece +``` + +--- + +## When to skip the brief + +The brief is required for: +- Cornerstone content +- Anything over 1500 words +- Anything with a conversion goal +- Anything written by someone other than the editorial lead + +The brief can be lighter for: +- Short newsletter blurbs +- Social posts +- Pieces written by the editorial lead with the strategy fully internalized + +But "lighter" is not "absent." Even a 100-word note covering reader / goal / angle saves time. diff --git a/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md b/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md new file mode 100644 index 0000000..4e1f906 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md @@ -0,0 +1,147 @@ +# Content Edit Checklist + +A pre-publish checklist for editing content. Run it line by line before any piece of content goes live. + +The checklist catches the regular mistakes. Editing for substance is a separate pass. + +--- + +## Pass 1: substance + +Before sweating commas, confirm the piece does its job. + +- [ ] **The brief is satisfied.** Re-read the content brief. Does this piece deliver against every objective? +- [ ] **The audience is the right one.** Who is the reader? Are they assumed correctly? +- [ ] **The single takeaway is clear.** If a reader skims and remembers one thing, what is it? Is it what we wanted? +- [ ] **The first 50 words earn the next 50.** Cut throat-clearing intros. Get to the point. +- [ ] **Every paragraph earns its place.** If a paragraph could be removed without loss, remove it. +- [ ] **The structure serves the reader.** Headers form a meaningful outline. Skim test passes. +- [ ] **There is one CTA per piece, and it is unmissable.** Or zero, if the piece is purely informational. +- [ ] **No claim is unsupported.** Every fact, statistic, or assertion has a source or is hedged. +- [ ] **Examples are concrete.** Specific numbers, named scenarios, real artifacts beat vague "many users" generalizations. + +--- + +## Pass 2: voice and tone + +- [ ] **Voice matches the brand voice document.** Read aloud. If a stranger could not place this as our brand, voice is too generic. +- [ ] **Tone matches the context.** Promotional vs editorial vs technical vs support. Different content, different tone shifts. +- [ ] **Pronouns are consistent.** "You" / "we" / "our" stay stable across the piece. +- [ ] **No internal voice leaked into customer-facing copy.** Jargon, project names, internal team names removed. +- [ ] **No first-person commentary in instructional content.** ("I think you should..." → "Do this because...") + +--- + +## Pass 3: structure and scannability + +- [ ] **Headings are descriptive, not clever.** "How to add a payment method" beats "Money matters." +- [ ] **Heading hierarchy is correct.** One H1, then H2s for top-level sections, H3s under H2s. No skipping levels. +- [ ] **Paragraphs are tight.** Default 2-4 sentences per paragraph for web. One-sentence paragraphs are allowed for emphasis. +- [ ] **Lists are used where they fit.** Bullets for parallel items, numbered for sequenced steps. +- [ ] **Bold and italic used sparingly.** Bold for the term being defined, italic for emphasis. Not both. Not often. +- [ ] **Code blocks for code.** Inline code for short references. +- [ ] **Tables for tabular data.** Not for layout. + +--- + +## Pass 4: clarity at the sentence level + +- [ ] **Active voice by default.** Passive voice for specific reasons (focus on object, unknown actor, polite distancing). +- [ ] **Concrete nouns and verbs.** "We process" beats "processing is performed by us." +- [ ] **Average sentence length under 20 words.** Vary the rhythm with shorter sentences for emphasis. +- [ ] **No nominalizations.** "Decide" beats "make a decision." "Implement" beats "carry out the implementation of." +- [ ] **No throat-clearing phrases.** Cut "It is important to note that," "In order to," "At the end of the day." +- [ ] **No filler intensifiers.** Cut "very," "really," "quite," "actually," "basically." Each weakens the word it modifies. +- [ ] **No hedge words where you mean something specific.** "May," "might," "could" are honest when uncertain, weak when specific. + +--- + +## Pass 5: jargon and accessibility + +- [ ] **Jargon defined on first use.** Or replaced if the audience would not know it. +- [ ] **Acronyms spelled out on first use.** Then acronym is fine. +- [ ] **No insider language.** Project codenames, internal team references, deprecated product names. +- [ ] **Idioms checked for global audiences.** "Hit it out of the park" reads strange to non-US English readers. +- [ ] **Reading level appropriate.** Use a tool (Hemingway, Readable) to spot-check. For most audiences, target Grade 8-10. +- [ ] **No ableist or exclusionary language.** "Crazy" → "wild," "blacklist" → "blocklist," gendered defaults checked. + +--- + +## Pass 6: SEO basics + +If the piece is for organic search: + +- [ ] **Primary query target identified.** One phrase per piece. +- [ ] **Title tag drafted.** Distinct from H1, 50-60 characters, primary query near front. +- [ ] **Meta description drafted.** 140-160 characters, value-led, includes primary query naturally. +- [ ] **H1 is unique on the site and includes the primary query.** +- [ ] **Internal links added.** 2-5 contextual links to related content on the site. +- [ ] **External links added.** Link out where it adds value or substantiates a claim. +- [ ] **Images have descriptive alt text.** Decorative images get `alt=""`. +- [ ] **URL slug is short, lowercase, hyphenated, includes primary query.** +- [ ] **Schema considered.** Article, FAQ, HowTo, etc. - whichever fits the format. + +--- + +## Pass 7: facts and claims + +- [ ] **Numbers verified.** Especially statistics, dates, prices, version numbers. +- [ ] **Names spelled correctly.** People, products, companies, places. +- [ ] **Quotes verified verbatim.** Speaker name, attribution, context correct. +- [ ] **Dates checked.** "Last updated" reflects the actual edit date. +- [ ] **Links work and go where they say.** No 404s, no redirect chains, no link rot to dead resources. +- [ ] **Screenshots are current.** Older screenshots show outdated UI; refresh or remove. +- [ ] **Claims about competitors are fair and current.** Or removed. + +--- + +## Pass 8: legal and compliance + +- [ ] **Trademarked terms used correctly.** Capitalization, ™ or ® where required by license. +- [ ] **Disclaimers present where needed.** Affiliate disclosures, regulated industry disclaimers, advisory caveats. +- [ ] **Customer permissions secured for testimonials.** Case studies, quotes, photos. +- [ ] **No confidential or pre-announcement information.** Product roadmaps, unannounced pricing, internal team names. +- [ ] **Image rights clear.** Licensed stock, original photography, or in-house illustration. + +--- + +## Pass 9: cross-channel consistency + +If the piece appears in more than one place: + +- [ ] **Web vs email vs social variants align in message.** Tone may shift; substance does not contradict. +- [ ] **Excerpts and meta descriptions match the piece.** No bait-and-switch. +- [ ] **CTAs point to current destinations.** Landing page is live, has matching messaging, is not stale. + +--- + +## Pass 10: final mechanical sweep + +- [ ] **Spellcheck.** Twice. Once with autocorrect off so it does not silently fix names. +- [ ] **Grammar check.** Tool-assisted, then human-verified. +- [ ] **Punctuation consistent.** Oxford comma, smart quotes, dashes - per the style guide. +- [ ] **No double spaces.** Find-and-replace. +- [ ] **No trailing whitespace at line ends.** +- [ ] **No placeholder text left in.** "Lorem ipsum," "TBD," "[INSERT QUOTE]," "TKTK." +- [ ] **No commented-out drafts in the source.** Especially in CMS HTML view. + +--- + +## Sign-off + +| Pass | Editor | Date | +|---|---|---| +| Substance | | | +| Voice and tone | | | +| Structure | | | +| Sentence-level | | | +| Jargon and accessibility | | | +| SEO | | | +| Facts and claims | | | +| Legal and compliance | | | +| Cross-channel | | | +| Mechanical | | | + +Final approval: [Name, date] + +Ready to publish: [ ] diff --git a/dist/pi/.agents/skills/content-brief-authoring/SKILL.md b/dist/pi/.agents/skills/content-brief-authoring/SKILL.md new file mode 100644 index 0000000..85733df --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/SKILL.md @@ -0,0 +1,252 @@ +--- +name: content-brief-authoring +description: "How to author a content brief that actually guides a writer (human or AI) to produce a piece that ranks, converts, or both. Per-piece editorial brief: target keyword and cluster, search intent, audience and JTBD, heading structure, entity coverage for AEO/GEO, internal linking strategy, success criteria. The middle path between thin briefs (a keyword and a deadline) and thick briefs (a 4-page document nobody reads). Triggers on content brief, brief the writer, brief the article, brief authoring, content brief template, brief audit, per-piece brief, editorial brief, target keyword brief, search intent brief. Also triggers when briefing a human writer or an AI agent on a single content piece." +category: content +catalog_summary: "Per-piece editorial brief: target keyword, intent, audience, outline, entity coverage, internal linking, success criteria, and the discipline that distinguishes useful briefs from bloat" +display_order: 2 +--- + +# Content Brief Authoring + +A senior content strategist's playbook for authoring per-piece content briefs that actually guide writers to produce content worth publishing. + +Most content briefs are some flavor of broken. The thin version is a keyword, a word count, and a deadline; the writer fills in everything else from scratch and the output is generic. The thick version is a 4-page document nobody reads, that the writer skims for the headline and the outline and ignores the rest. Either way, the brief failed at its job: making the writer's work easier and the output more predictable. + +This skill is the middle path. It defines the 12 fields that earn their keep in a content brief, the fields that bloat without helping, and the discipline of writing briefs that route a writer (human or AI) toward a content piece that ranks for its target keyword, gets cited by AI engines, converts the right reader, or whatever the success criteria say. It assumes you have decided what to write (see `content-strategy` for program-level decisions) and now you are briefing each piece. The piece itself gets written separately (see `content-and-copy`). + +When to use this skill: briefing a writer (human or AI) on an individual content piece, auditing existing briefs that are not producing good content, building a brief template for a content program, or running a brief-generation pipeline through Frase, AirOps, or another tool. + +--- + +## What this skill is for + +This skill spans the per-piece editorial brief discipline. It composes with three sister skills, and the distinction between them is what keeps each one sharp. + +- `creative-brief` is a project brief. It bridges discovery to execution at the project level: a new website, app, brand, or campaign. Audience, goals, scope, success at project scope. +- `content-strategy` is a program-level editorial strategy. Pillars, calendar, topic clusters, governance. What to produce across a quarter or a year. +- `content-and-copy` is the writing itself. Voice, structure, edit pass, tone calibration. Execution scope for general editorial. +- This skill is the per-piece brief between `content-strategy` (program decided) and `content-and-copy` (piece gets written). It briefs a single content artifact: keyword, intent, audience, outline, entities, success criteria. + +The clean reading order: `content-strategy` decides what to produce; this skill briefs each piece; `content-and-copy` writes it. If the team is briefing a redesign or a new brand build, that is `creative-brief`, not this skill. + +The audience: content strategists, SEO content marketers, editorial leads, content ops managers, agencies running content programs at scale, and any PM or marketer briefing a writer (human or AI). The voice is senior content strategist to junior content marketer. Specific, opinionated, honest about what makes a brief useful versus useless. + +--- + +## Thin vs thick vs effective briefs + +The keystone distinction. Three concrete shapes. + +**Thin brief.** Keyword, word count target, deadline. Maybe a one-line summary of the angle. The writer fills in everything else from scratch. Output is generic, drifts off-topic, does not rank, and does not convert. The cost is the rewrite cycle: editor spends two hours rewriting because the writer chose the wrong intent, the wrong audience, or the wrong outline. + +**Thick brief.** A 4-page document with executive summary, brand-guidelines refresher, comprehensive competitive analysis, voice guidelines, plus the actual brief somewhere in the middle. The writer skims for the outline, ignores the rest. Output is not materially better than from a thin brief because the writer never read most of the document. The cost is the authoring time: the strategist spends three hours producing pages of context the writer will never absorb. + +**Effective brief.** One to two pages. Every field earns its keep. Writer reads all of it because there is no fluff. Output is predictable enough that the editor does not have to rewrite the lede. The cost is the discipline of cutting fields that do not change writer behavior. + +The discipline. Every field in the brief has a job. If you can remove the field without degrading the output, remove it. The brief is the contract between editorial leader and writer; vague contracts produce vague output, overstuffed contracts produce output that reflects only the parts the writer read. + +Most briefs that are not working are thin, not thick. The instinct to add more usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +--- + +## The 12 fields of an effective brief + +A useful brief has 12 fields. Skip any of them and the writer fills the gap from priors; the gap is where output drifts. + +1. **Target keyword + supporting cluster.** Primary keyword plus 3 to 5 supporting keywords from the same cluster. The cluster is what tells the writer the topic has range; the primary is what the piece optimizes for. +2. **Search intent classification.** Informational, navigational, commercial, or transactional. Plus the dominant SERP format check (article, listicle, comparison, video, tool). The intent decides what kind of piece this is; the format decides the shape. +3. **Target audience.** Specific role and sophistication level. Not "anyone interested in X." A senior data engineer at a 500-person SaaS company is a target; "data people" is not. +4. **Job to be done.** The problem the reader is trying to solve when they land on the piece. One sentence. Specific. +5. **Word count / depth target.** Calibrated to the SERP, not to a content quota. If the top 10 are all 1,200 words, briefing 3,000 wastes effort; if the top 10 are all 4,000 words, briefing 1,500 produces a piece that cannot rank. +6. **Heading structure outline.** H2s and H3s explicit, ordered logically. The outline is where the writer reads the brief most carefully; spend time here. +7. **Required entities, statistics, citations.** For AEO and GEO, the named tools, methods, experts, and statistics the piece must cover. The entity gap is the agent's prioritization signal. +8. **Internal linking strategy.** 3 to 5 pages this piece should link out to with anchor text; 1 to 3 existing pages that should link back to this piece after publish. +9. **External proof points.** Required citations, sources, expert quotes. Not optional. +10. **Anti-patterns.** What not to do. Off-topic tangents the writer might wander into, off-brand voice, AI clichés the brief explicitly forbids by listing them in a do-not-use list (the standard set of overused corporate-speak adjectives, throat-clearing openers, and verbs that signal AI generation). +11. **Success criteria.** What good looks like. Rank for the target keyword in 90 days. Get cited by ChatGPT for the cluster within 60 days. Drive 50 trial signups in the first 30 days. Measurable, time-bound, tied to the program goal. +12. **Author voice and tone reference.** Link to the brand-voice guide. If the piece needs a tone shift from the default voice, note it here in one sentence. + +The fields that do not earn their keep, and should be omitted from briefs unless the writer is brand new to the program: + +- Long executive summary (the brief itself is the executive summary) +- Brand-guidelines refresher (link to it; do not repeat) +- Comprehensive competitive landscape (link to research; do not dump) +- Brief history of the publication, company, or brand (irrelevant to this piece) + +Detail and templates per content type in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## Search intent classification + +The four standard intents: + +- **Informational.** The reader wants to learn. SERP usually shows articles, guides, explainers. +- **Navigational.** The reader wants a specific brand or page. SERP usually shows the brand site at #1; ranking against navigational intent is mostly impossible unless you are the brand. +- **Commercial.** The reader is researching a purchase. SERP usually shows comparisons, reviews, "best X" listicles. +- **Transactional.** The reader is ready to buy. SERP usually shows product pages, pricing pages, signup flows. + +The dominant SERP format check. After classifying intent, scan the SERP top 10 and tag the dominant format: article, listicle, comparison, video, tool, hybrid. The dominant format tells you the shape of the piece, which is more decisive than the intent label. + +The override pattern. When the intent feels informational but the SERP shows mostly listicles, write the listicle. When the intent feels commercial but the SERP shows mostly long-form articles, write the article. The SERP is the source of truth, not your priors. Rankings come from matching the SERP's accepted shape; deviating costs ranking. + +The AEO/GEO consideration. AI engines tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. Mismatched format is a citation risk in addition to a ranking risk. + +Detail in [`references/search-intent-classification.md`](references/search-intent-classification.md). + +--- + +## Heading structure design + +Heading hierarchy patterns the brief should specify: + +- H2 sections that match common follow-up questions for the keyword. The reader's mental model is a series of questions; the H2s answer them in order. +- H3s under H2s only when they add navigational value. No orphan H3s. No H2-H3-H4 cascades that nobody scrolls through. +- Featured snippet bait pattern: a 40 to 60 word answer paragraph immediately following an H2 question. Google often pulls this paragraph as the snippet; AI engines often quote it as the citation. +- H2 ordering that matches the reader's mental model, not the writer's enthusiasm. Put the obvious answer first; the writer's clever angle goes in H2 #4, not H2 #1. + +Anti-patterns the brief should explicitly forbid: + +- H2s that all start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. +- Buried lede: H2 #4 has the actual answer. The reader bounced at H2 #2. +- Section length wildly uneven: H2 #1 is 1,500 words, H2 #2 is 80 words. The 80-word section reads as a placeholder. + +Detail in [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md). + +--- + +## Entity coverage for AEO and GEO + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that mentions the entities the SERP top-ranking pages mention, includes specific statistics with sources, contains citation-formatted proof points, and demonstrates topical depth via entity coverage. + +The entity discovery pattern, run before briefing the piece: + +1. Pull SERP top 10 for the target keyword. +2. Identify entities mentioned across multiple pages: named tools, named methods, named experts, named data sources, named statistics. +3. Identify entities mentioned by 1 to 2 pages but not in your existing content. This is the entity gap. +4. Add the gap entities to the brief as required coverage. + +The brief lists the entities the writer must mention, with light context on why each matters. The writer is not expected to research each entity from scratch; the brief includes a one-line note ("CUPED is the variance-reduction technique used by data-warehouse-experimentation teams; mention in the methodology section") so the writer can integrate without breaking flow. + +Tools that automate this: Frase has entity-gap analysis built in; AirOps composes the same analysis through its workflow builder; Surfer SEO ships entity coverage scoring. The skill is tool-agnostic; the workflow is what matters. + +Detail in [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md). + +--- + +## Internal linking strategy + +The brief should specify two link directions: + +- **Outbound from this piece.** 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer should not be deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. +- **Inbound to this piece, post-publish.** 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +The orphan-content failure mode: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. Prevented by upstream-link planning in the brief. + +The self-cannibalization check: if this piece would compete with an existing piece for the same keyword cluster, the brief flags it explicitly. The options are consolidate (merge into the existing piece), differentiate (the brief sharpens the angle so the two do not compete), or kill one. Flagging late, after the piece is written, costs more than flagging in the brief. + +Detail in [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md). + +--- + +## Brief templates by content type + +Different content types call for different brief shapes. The 12 fields are constant; the weight of each field shifts. + +- **Pillar piece.** Comprehensive coverage of a topic, 3,000 words plus, anchors a topic cluster. Brief emphasizes structure, comprehensiveness, internal links to and from supporting pieces. +- **Supporting / cluster piece.** Narrower topic, 1,000 to 2,000 words, links up to the pillar. Brief emphasizes specificity, single-question scope. +- **Comparison piece (X vs Y).** Commercial intent, structured comparison, decision framework. Brief emphasizes objectivity (or honest positioning if the brand is one of X or Y), table structure, "when X wins" / "when Y wins" framing. +- **Listicle.** Informational or commercial intent, scannable, ranked or unranked. Brief emphasizes selection criteria, ordering rationale, depth-per-item. +- **How-to guide.** Informational, step-by-step, screenshots. Brief emphasizes step granularity, prerequisites, troubleshooting section. +- **Thought leadership / opinion.** Commercial or branding, distinctive POV, signal of expertise. Brief emphasizes thesis, supporting arguments, anticipated counter-arguments. + +Each template gets a worked example in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## The brief-to-writer handoff + +Whether the writer is human or AI, the handoff has the same shape. + +- Brief delivered with all 12 fields populated. +- Writer asks clarifying questions before drafting (or the AI agent surfaces ambiguities in the brief as the first response). +- Writer or agent acknowledges the success criteria explicitly. +- First draft references the brief: "this draft hits 4 of the 5 required entities; the 5th is missing because the SERP coverage was thin and I could not find a reliable source." +- Editor reviews against the brief, not against personal taste. "The brief said X; the draft did Y" is the review framing. + +For AI handoff specifically, the brief becomes a structured prompt or a tool input. Frase, AirOps, and similar tools structure briefs as YAML or JSON for machine consumption; the same 12 fields apply. The structured format is the only difference; the contract is the same. + +Detail in [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md). + +--- + +## Brief governance + +Versioning. Every brief has a version. Significant changes (target keyword change, audience shift, scope expansion) bump the version; cosmetic edits do not. The writer always works from the current version, not a stale draft pasted into Slack three weeks ago. + +Approval. The brief approver is the editorial owner of the content program. Single approver, not a committee. The approver is also the editor on the back end, so the same person is responsible for both the contract and the review. Splitting these roles is how briefs and reviews drift apart. + +Archival. After publish, the brief is archived alongside the content piece (Notion database row, dbt model, content management system metadata, whatever the team's source of truth is). Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, a content audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +Detail in [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses and fixes in [`references/common-brief-failures.md`](references/common-brief-failures.md). + +- "The brief was too thin." Fill all 12 fields or accept generic output. +- "The brief was too thick." Every field needs a job; remove the rest. +- "The writer ignored the brief." Anchor success criteria to the brief; review against the brief. +- "The brief had the wrong target keyword." SERP-validate before briefing. +- "The piece does not match the SERP intent." SERP intent override applies; do not write an article when the SERP wants a listicle. +- "The piece has no internal links." Internal linking belongs in the brief, not as an afterthought. +- "The piece is generic; could have been written about anything." Entity coverage and POV missing from brief. +- "The brief is comprehensive but the piece does not rank." Brief was right; SERP was harder than expected; iterate based on real performance, not by adding fields to the brief. +- "We never went back to evaluate." Success criteria measured 30 / 60 / 90 days post-publish. +- "Different writers produce wildly different output from the same brief." Brief was actually too vague; tighten anti-patterns and voice notes. + +--- + +## The framework: 12 considerations for brief authoring + +When authoring or auditing a content brief, walk these 12 considerations. + +1. **Target keyword + cluster.** Primary plus 3 to 5 supporting. +2. **Search intent + dominant SERP format.** Match the SERP, not your priors. +3. **Target audience + JTBD.** Specific role and problem, not "anyone interested in X." +4. **Word count calibrated to SERP.** Not to a content quota. +5. **Heading structure.** Explicit H2s and H3s, ordered to match reader mental model. +6. **Entity coverage.** Entities the SERP top 10 mention; gap entities added explicitly. +7. **Internal linking.** 3 to 5 outbound links specified; 1 to 3 inbound updates queued. +8. **External proof points.** Citations and sources required. +9. **Anti-patterns.** What not to do, including AI clichés and off-brand voice. +10. **Success criteria.** Measurable, time-bound, tied to original program goals. +11. **Brief versioning + approval.** Single approver; version bumps for material changes. +12. **Brief stays under 2 pages.** Every field earns its keep; remove fields that do not. + +The output of the framework is a brief document the writer can absorb in 5 minutes and execute against in the next 5 hours. + +--- + +## Reference files + +- [`references/brief-templates.md`](references/brief-templates.md) - Pillar, supporting, comparison, listicle, how-to, and thought-leadership brief templates with field-weight notes per type. +- [`references/search-intent-classification.md`](references/search-intent-classification.md) - Four-intent framework, SERP format check, override patterns. +- [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md) - H2 and H3 patterns, featured snippet bait, anti-patterns. +- [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md) - Entity discovery from SERP, gap analysis, AEO/GEO citation drivers. +- [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md) - Outbound and inbound linking patterns, orphan prevention, self-cannibalization check. +- [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md) - Human-writer handoff, AI-agent handoff, success-criteria anchoring. +- [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md) - Versioning, approval, archival, audit trail. +- [`references/common-brief-failures.md`](references/common-brief-failures.md) - Ten-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: the brief is the contract + +A content brief is the contract between editorial leader and writer. If the contract is vague, the output is vague. If the contract is overstuffed, the output reflects only the parts the writer read. The discipline is writing contracts the writer can absorb in 5 minutes and execute against in the next 5 hours; that is the entire job. + +Most briefs that are not working are thin, not thick. The instinct to add more pages usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +When in doubt about whether a brief is ready, ask: are all 12 fields populated, do they each earn their keep, is the SERP intent matched, are the entities listed, are the internal links specified, is the success criteria measurable, and is the document under 2 pages? If yes to all of those, ship the brief and let the writer work. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md b/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md new file mode 100644 index 0000000..725b669 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md @@ -0,0 +1,104 @@ +# Brief governance patterns + +Versioning, single-approver, archival alongside the published piece, audit trail. + +--- + +## Versioning + +Every brief has a version. Significant changes bump the version; cosmetic edits do not. + +**Version-bump triggers:** +- Target keyword change (the piece is now optimizing for a different keyword) +- Audience shift (the JTBD has changed) +- Scope expansion or contraction (word count target moves by 50%+; new H2s added or removed) +- Success criteria change (the metric the piece is being measured against shifts) + +**No version bump for:** +- Typo fixes +- Anchor text adjustments on internal links +- Adding a sentence of clarification to an existing field +- Reformatting + +The writer always works from the current version. If a writer is mid-draft when the brief bumps from v2 to v3, the strategist tells the writer immediately and decides whether to restart, integrate the changes, or freeze the v2 draft. + +The brief has a version field at the top: `brief_version: 3`. The version is the contract identifier. + +--- + +## Single approver + +The brief approver is the editorial owner of the content program. Single approver, not a committee. + +**Why single approver:** +- A committee bog dilutes the brief. Each member adds a field; nobody removes fields. The brief grows from 1 page to 4 pages and stops being readable. +- A committee splits accountability. When the published piece misses, no single person owns the brief that produced it. +- A single approver enforces taste. The program has a consistent editorial voice because one person is gatekeeping. + +**The approver is also the editor.** The same person who approves the brief reviews the draft. This prevents the gap between "what the brief asked for" and "what the editor wants"; the same person owns both sides. + +Splitting these roles is how briefs and reviews drift apart. The strategist who briefed the piece sees the gap; an external editor reads the draft and changes the lede because of personal taste, not because of the brief. + +**The exception:** for high-stakes pieces (pillar content, thought leadership with named author, comparison pieces involving competitors), a second reader is useful. The second reader provides input but does not approve. The single approver still decides. + +--- + +## Archival + +After publish, the brief is archived alongside the content piece. + +**Common archival patterns:** +- **Notion database row.** Brief and published-piece URL on the same row. Custom fields for brief version, approver, publish date, success-criteria results. +- **dbt model with content metadata.** For warehouse-native content tracking; brief stored as JSON in the model's seed data. +- **CMS metadata fields.** Contentful, Sanity, and similar CMSs allow custom metadata fields; the brief lives in a "brief" field on the content entry. +- **Git repo.** For docs sites and developer-facing content programs; brief in a sibling markdown file to the published piece. + +**Why archival matters.** Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, an audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +The audit question is "did we ship what we briefed, and did the briefed piece achieve its success criteria?" Both halves need source-of-truth records: the brief for what was asked, the published piece for what was delivered, the metrics for what the piece achieved. + +--- + +## Audit trail + +A content program that runs at scale needs an audit trail. The audit trail answers four questions per piece: + +1. **What did we brief?** The archived brief, with version history. +2. **What did we publish?** The published URL, with publish date and last-update date. +3. **How did the piece perform against the success criteria?** Rank position at 30 / 60 / 90 days; AI citation count if measured (Profound, Frase, AirOps); conversion data from the analytics stack. +4. **What did we learn?** A short post-publish note: what worked, what did not, what to brief differently next time. + +The audit trail compounds. After 50 pieces, the program can see patterns: pillar pieces with comprehensive outlines outperform pieces with thin outlines; comparison pieces with explicit "when X wins" / "when Y wins" framing outperform pieces with implicit positioning; entity-coverage scores above 80 correlate with citation count. + +The audit trail is what turns content production from a per-piece activity into a learning system. Without the trail, every piece is a one-off; with the trail, the program improves quarter over quarter. + +--- + +## The "post-mortem on a failed piece" pattern + +When a piece misses its success criteria, the post-mortem walks the brief. + +1. Read the brief. Was it complete? Were the 12 fields populated? +2. Read the published piece. Did it follow the brief? +3. Identify the gap. Was the brief wrong (target keyword too competitive, intent misclassified)? Was the execution off (writer drifted from outline, entities missed)? Was the SERP harder than expected (well-executed brief, well-written piece, still no rank)? +4. Update the brief template if the failure is systemic (next time, run a deeper SERP check before briefing). +5. Update the writer-handoff if the failure is communication (next time, the brief is read aloud at handoff). +6. Accept the failure if the failure is variance (some pieces miss; the program does not chase every miss). + +The post-mortem is short, half a page. It feeds the audit trail and informs the next brief. It does not turn into a multi-page analysis that nobody reads. + +--- + +## Brief field: governance metadata + +The brief carries governance metadata at the top: + +> **Brief metadata** +> - Brief version: 3 +> - Approver: editorial-lead@team.com +> - Approval date: 2026-04-22 +> - Writer assigned: J. Smith (or AI agent: Frase v4) +> - Target publish date: 2026-05-15 +> - Archive location: Notion content-pipeline database, row #847 + +The metadata is six lines, not a paragraph. It identifies the contract; the rest of the brief is the contract terms. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md b/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md new file mode 100644 index 0000000..5f9c94a --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md @@ -0,0 +1,87 @@ +# Brief templates by content type + +Six templates. The 12 fields are constant; the weight of each field shifts based on the content type. Each template names the fields that lean heavier and the fields that lean lighter for that type. + +--- + +## Pillar piece + +Comprehensive coverage of a topic, 3,000+ words, anchors a topic cluster. The piece other content links up to. + +**Heavier fields:** heading structure (the outline is the spine), entity coverage (a pillar that misses entities loses credibility), internal linking (links to and from the supporting cluster pieces), word count (calibrated to top SERPs, often long). + +**Lighter fields:** anti-patterns (the writer assigned to a pillar usually knows the topic), tone reference (default brand voice; tone shifts are rare for pillars). + +**Brief shape:** 2 pages. The H2 outline takes ~40% of the brief because pillar structure is decisive. Entity list is long (15 to 25 entities). Internal-link section names every cluster piece that should link in or out. + +**Worked example.** Target keyword: "experimentation analytics dashboards." Cluster: experimentation methodology. Intent: commercial-investigation. SERP format: long-form articles plus comparison tables. Word count target: 2,800 to 3,400. Outline: H2 #1 "what an experimentation dashboard does," H2 #2 "platform-native vs warehouse-native," H2 #3 "the metrics that earn their keep," H2 #4 "build vs buy," H2 #5 "common dashboards that ship trusted results." Entities: lift, p-value, MDE, CUPED, sequential testing, Statsig, PostHog, Optimizely, dbt, Mixpanel, Snowflake. Internal links: 5 supporting pieces queued. + +--- + +## Supporting / cluster piece + +Narrower topic, 1,000 to 2,000 words, links up to the pillar. One question, one answer. + +**Heavier fields:** target keyword (specific long-tail), search intent (cluster pieces have to match SERP precisely), JTBD (one specific reader problem), internal linking (must link up to pillar with anchor text matching the pillar's target). + +**Lighter fields:** entity coverage (smaller scope, fewer entities required), thought-leadership POV (cluster pieces serve the cluster, not the writer's opinion). + +**Brief shape:** 1 page. JTBD in one sentence. H2 outline is 3 to 5 sections. Entity list is short (5 to 10). The "links up to pillar" specification is mandatory; an orphan cluster piece is a wasted slot. + +**Worked example.** Target keyword: "CUPED variance reduction." Pillar: experimentation analytics dashboards. Intent: informational. JTBD: data analyst wants to apply CUPED in a dbt model and needs the formula plus the gotchas. Outline: H2 "what CUPED does," H2 "the formula," H2 "implementing in dbt," H2 "common pitfalls." Internal link up to pillar with anchor "experimentation analytics dashboards." + +--- + +## Comparison piece (X vs Y) + +Commercial intent, structured comparison, decision framework. The reader wants help choosing. + +**Heavier fields:** anti-patterns (snark and trash-talk are the failure mode), heading structure (table-style comparison plus "when X wins" / "when Y wins" sections), success criteria (commercial intent piece; the metric is signups or sales-qualified leads, not traffic alone). + +**Lighter fields:** word count flex (top-ranking comparison pieces vary widely; SERP-calibrate). + +**Brief shape:** 1 to 2 pages. The comparison criteria are listed in the brief, not invented by the writer. If the brand is one of X or Y, the brief specifies honest positioning: what the brand wins on, what the competitor wins on. The brief explicitly forbids "X is the worst, Y is the best" framing. + +**Worked example.** Target keyword: "Statsig vs PostHog." Intent: commercial. SERP format: comparison tables plus prose. Comparison criteria: pricing model, MAU thresholds, MCP support, custom-metric depth, frontend visual editor, mobile SDK. "When Statsig wins": teams with strong custom-metric needs, teams that already pay for Snowflake. "When PostHog wins": product analytics-led teams, teams that want session replay alongside experimentation. Anti-pattern explicitly listed: do not write "PostHog is the clear winner" or "Statsig is overpriced." Honest comparison or do not write the piece. + +--- + +## Listicle + +Informational or commercial intent, scannable, ranked or unranked list. "10 best X" or "7 ways to Y." + +**Heavier fields:** selection criteria (why are these 10 the chosen ones; the writer needs to defend the list), ordering rationale (why is item #1 first; explicit ranking criteria), depth-per-item (how many words per item; even depth is the discipline). + +**Lighter fields:** narrative arc (listicles have minimal narrative; the list itself is the structure). + +**Brief shape:** 1 page. The selection criteria are listed in the brief. The order is suggested in the brief, with note that the writer can reorder if the research warrants. Depth-per-item is specified (e.g., 150 words each for 10 items, plus 200-word intro and 150-word conclusion = ~1,850 words). + +**Worked example.** Target keyword: "best feature flag tools 2026." Intent: commercial. Selection criteria: official MCP support, free tier exists, hosting model. The 10 items pre-listed in the brief: LaunchDarkly, Statsig, PostHog, GrowthBook, Optimizely, VWO FME, Split.io, Kameleoon, Flagsmith, Unleash. Depth: 150 words per tool covering pricing, MCP status, when this tool wins. + +--- + +## How-to guide + +Informational intent, step-by-step, screenshots, prerequisites, troubleshooting. The reader wants to do something specific. + +**Heavier fields:** step granularity (each step is one action, not three), prerequisites (what the reader needs before starting), troubleshooting section (common failure modes the reader will hit). + +**Lighter fields:** thought-leadership POV (how-to guides serve the task, not the writer's perspective on it). + +**Brief shape:** 1 to 2 pages. The brief lists the steps in outline form so the writer can spot missing prerequisites or merged steps before drafting. The screenshot list is queued (which screens, in what state). Troubleshooting bullets are listed; the writer expands each into a paragraph. + +**Worked example.** Target keyword: "how to set up a Statsig experiment." Prerequisites: Statsig account, SDK installed, exposure events instrumented. Steps: H2 "create the experiment in the console," H2 "define the assignment unit," H2 "configure the metrics," H2 "set the duration and MDE," H2 "launch and monitor." Troubleshooting: SRM check failure, exposure events not firing, metric definition mismatch. + +--- + +## Thought leadership / opinion + +Commercial or branding intent, distinctive POV, signal of expertise. The piece exists to differentiate the brand voice in the category. + +**Heavier fields:** thesis (one sentence; the whole piece defends it), anticipated counter-arguments (what would a smart skeptic say; the piece must address them), tone reference (often a sharper voice than default; the brief specifies the shift). + +**Lighter fields:** SERP entity coverage (thought leadership often deliberately diverges from SERP consensus; entity coverage is a softer requirement). + +**Brief shape:** 1 page. The thesis is one sentence at the top. The supporting arguments are listed (3 to 5). The anticipated counter-arguments are listed with notes on how the piece responds to each. The brief explicitly names the writer or contributor; thought leadership has authorship, not anonymous editorial. + +**Worked example.** Thesis: "warehouse-native experimentation is the right default for any team running 50+ experiments per quarter." Supporting arguments: cost crossover at scale, custom metric flexibility, audit trail, data-team integration. Counter-arguments to address: setup cost, time-to-first-experiment, missing UI tooling. Tone shift: sharper, more declarative than default brand voice. Author: named senior data leader. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md b/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md new file mode 100644 index 0000000..b9c2cf9 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md @@ -0,0 +1,123 @@ +# Common brief failures + +Ten-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "The brief was too thin" + +**Symptom.** Brief contains target keyword, word count, deadline, maybe a one-line angle. Writer fills in everything else from priors. Output is generic, drifts off-topic, does not rank. + +**Diagnosis.** The strategist treated the brief as a task assignment instead of a contract. The 12 fields were not populated; the writer's defaults filled the gaps; the defaults were not aligned with the program's intent. + +**Fix.** Populate all 12 fields. If a field cannot be populated (the success criteria is genuinely unknown, the SERP is too volatile to call), name the gap explicitly and flag it as "writer's call, defend the choice in the first draft." + +--- + +## "The brief was too thick" + +**Symptom.** Brief is 4 pages with executive summary, brand-voice refresher, comprehensive competitive landscape, plus the actual brief. Writer skims for the outline. Output is not better than from a thin brief. + +**Diagnosis.** Strategist optimized for brief authorship instead of brief consumption. Each field added felt important; nobody asked "would the writer behave differently if this field were missing?" + +**Fix.** Cut fields that do not change writer behavior. Brand-voice refresher: link, do not repeat. Competitive landscape: link to research, do not summarize. Executive summary: the brief is the executive summary. Target: 1 to 2 pages. + +--- + +## "The writer ignored the brief" + +**Symptom.** The published piece misses the SERP intent, drops required entities, ignores internal-link guidance. Editor's review surfaces the gap. + +**Diagnosis.** No success-criteria acknowledgment at handoff. The writer read the brief once at the start, drafted from memory plus priors, never re-read. + +**Fix.** Require acknowledgment at handoff (see `writer-handoff-protocols.md`). The acknowledgment restates the success criteria in the writer's voice. Saying it is what keeps it load-bearing. + +--- + +## "The brief had the wrong target keyword" + +**Symptom.** The piece publishes; the target keyword turns out to have search volume of 50/month, or to be navigational (a brand wins position 1 forever), or to have a SERP the team cannot win. The piece does not rank. + +**Diagnosis.** SERP not validated before briefing. The strategist assumed the keyword was good without pulling the SERP and the volume. + +**Fix.** SERP-validate before briefing. Pull the keyword volume (Ahrefs, Semrush, GSC). Pull the SERP top 10. If the SERP looks unwinnable for the brand at current authority, pick a different keyword. + +--- + +## "The piece does not match the SERP intent" + +**Symptom.** SERP shows mostly listicles; the briefed piece is a long-form article. Or SERP shows long-form articles; the briefed piece is a listicle. Either way, the piece does not rank. + +**Diagnosis.** SERP intent override was not applied. The strategist's priors about what the keyword "should" look like overrode what the SERP actually shows. + +**Fix.** Apply the SERP override pattern (see `search-intent-classification.md`). The format choice line in the brief must match the dominant SERP format. + +--- + +## "The piece has no internal links" + +**Symptom.** Piece publishes with zero internal links to other pages on the site. Or with one or two links that the writer added arbitrarily. + +**Diagnosis.** Internal linking was treated as an afterthought. The brief did not specify outbound links; the writer added some at the end without strategic intent. + +**Fix.** Specify 3 to 5 outbound links in the brief, with anchor text and target page. Queue 1 to 3 inbound updates as post-publish tasks (see `internal-linking-strategy.md`). + +--- + +## "The piece is generic; could have been written about anything" + +**Symptom.** Reading the piece, you cannot tell what brand it came from, what makes it different from the SERP top 10, or why this piece exists. The piece reads as AI-generated even when a human wrote it. + +**Diagnosis.** Entity coverage and POV were missing from the brief. The writer hit the target keyword but did not differentiate; the piece blends into SERP consensus. + +**Fix.** Specify gap entities (entities mentioned by 1 to 2 SERP pages but not by the rest). Specify a POV for the piece: what the brand argues that the rest of SERP does not. Generic content has no POV; effective content makes a specific claim. + +--- + +## "The brief is comprehensive but the piece does not rank" + +**Symptom.** Brief had all 12 fields. Writer followed the brief. Piece is well-written, hits the entities, follows the outline. Three months post-publish: position 47. + +**Diagnosis.** The SERP was harder than expected. The brief was right; the keyword was over-competitive at the brand's current authority. This is variance, not failure. + +**Fix.** Do not iterate by adding fields to the brief. Iterate by SERP-validating more carefully next time, by accepting that some keywords are out of reach until the brand earns more authority, or by pivoting to a less-competitive long-tail variant. + +--- + +## "We never went back to evaluate" + +**Symptom.** Pieces publish; nobody checks performance at 30 / 60 / 90 days. The program runs without feedback. + +**Diagnosis.** Success criteria were defined in the brief but no measurement task was queued at publish time. + +**Fix.** Make 30 / 60 / 90 day check-ins part of the publish checklist. The check-in is a 5-minute task: read the rank, the citation count, the conversion data; update the audit trail (see `brief-governance-patterns.md`). Not optional. + +--- + +## "Different writers produce wildly different output from the same brief" + +**Symptom.** Two writers given the same brief produce pieces that read like they came from two different programs. The brief was supposedly identical; the output is not. + +**Diagnosis.** The brief was actually too vague. Different writers filled gaps with their own priors; the gaps were where the divergence lives. + +**Fix.** Tighten the anti-patterns and the voice notes. The brief explicitly forbids common writer drifts (off-topic tangents, off-brand tone, AI clichés). The voice reference is specific (not "use brand voice" but "use the voice of section 3 of the voice guide; default tone, no sharper"). + +--- + +## "The piece succeeded but we cannot tell why" + +**Symptom.** A piece outperforms expectations: top-3 rank, high citation count, conversion above target. The team cannot explain what made it work. + +**Diagnosis.** The brief and the published piece have multiple distinguishing features (specific outline, gap entities, sharp POV); without controlled comparison, the team cannot isolate the cause. + +**Fix.** Document hypotheses about why the piece worked in the post-publish note. Test the hypotheses by briefing the next 3 pieces with the same pattern. If the pattern replicates, it is the cause; if not, the success was variance. The audit trail compounds (see `brief-governance-patterns.md`); patterns emerge over 20+ pieces. + +--- + +## "We approved the brief but the writer wrote a different piece" + +**Symptom.** The brief was for a comparison piece; the writer delivered a thought-leadership piece. The brief was for 1,800 words; the writer delivered 3,400 words. The brief was for a senior data engineer audience; the writer wrote for a non-technical CMO. + +**Diagnosis.** The handoff acknowledgment was skipped. The writer read the brief, drafted from a different mental model, and did not surface the divergence early. + +**Fix.** Require acknowledgment that restates the brief's parameters: word count, audience, format. If the writer's acknowledgment misstates anything, the strategist catches it before drafting starts. After 1,500 words of writing, restarting is expensive; before drafting, restating is cheap. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md b/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md new file mode 100644 index 0000000..54ada43 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md @@ -0,0 +1,91 @@ +# Entity coverage checklist + +Entity discovery from SERP, gap analysis, AEO and GEO citation drivers. + +--- + +## Why entity coverage matters + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that: + +- Mentions the entities the SERP top-ranking pages mention +- Includes specific statistics with sources +- Contains citation-formatted proof points +- Demonstrates topical depth via entity coverage + +Entities are the named things the topic depends on: tools, methods, experts, datasets, statistics, brands, frameworks, standards, organizations. A piece on "experimentation analytics" that does not mention CUPED, sequential testing, p-values, or named platforms (Statsig, PostHog, Optimizely) reads as thin both to humans and to ranking systems. + +Traditional SEO has known about entity coverage for years (Google's Hummingbird and BERT updates emphasized it). AEO and GEO double the stakes: AI engines explicitly use entity coverage as a citation signal because they can extract the entity graph from the page and assess topical depth at retrieval time. + +--- + +## The entity discovery workflow + +Run before authoring the brief; do not delegate to the writer. + +**Step 1.** Pull the SERP top 10 for the target keyword. + +**Step 2.** For each top-10 page, extract the named entities. Tools that automate this: Frase (built-in entity gap analysis), AirOps (workflow builder runs the same analysis), Surfer SEO (entity coverage scoring), or manual extraction with a structured prompt. + +**Step 3.** Tag each entity by frequency: +- Mentioned by 7+ of 10 pages: required coverage. The brief lists these. +- Mentioned by 3 to 6 pages: standard coverage. The brief lists these with shorter notes. +- Mentioned by 1 to 2 pages: gap entities. The brief includes these as differentiation opportunities. +- Mentioned by 0 pages but relevant: brand-owned entities the team knows matter even if SERP misses them. + +**Step 4.** For each required and standard entity, write a one-line note in the brief explaining why it matters and where to mention it. Example: + +> **CUPED.** Variance-reduction technique mentioned by 9 of 10 SERP pages. Mention in the methodology H2 with the formula. Required. + +**Step 5.** Add the gap entities (1 to 2 page mentions) as differentiation opportunities. The writer can choose to include them; they add depth without crowding the required entities. + +--- + +## AEO and GEO citation drivers + +Beyond entity coverage, AI engines weight several other signals when deciding what to cite. + +**Specific statistics with sources.** "Statsig charges per MAU starting at 100K MAU" cites better than "Statsig is expensive at scale." Numbers with sources are higher-citation; vague qualifiers are lower-citation. + +**Named experts or quotes.** "As Ronny Kohavi noted in his book Trustworthy Online Controlled Experiments, the most common SRM diagnosis is..." cites better than "experts agree that SRM diagnoses are common." Named attribution earns citation; anonymous attribution does not. + +**Direct definitions.** "CUPED stands for Controlled-experiment Using Pre-Existing Data" cites better than a passage that uses CUPED without defining it. AI engines extract definitions and use them as the canonical answer when users ask "what is CUPED." + +**Comparison tables.** Tables with explicit columns and rows cite better than prose comparisons. AI engines extract structured data preferentially. + +**Specific tool names with version numbers.** "dbt Cloud (v1.7+)" cites better than "dbt." Specificity is the citation signal. + +--- + +## Brief field: how to populate entity coverage + +The brief lists the required entities, the standard entities, and the gap entities, with one-line notes per entity. + +> **Required entities (mention all)** +> +> - **CUPED:** variance-reduction technique (9/10 SERP pages). Mention in methodology H2 with formula. +> - **Sequential testing:** confidence-adjustment for peeking (8/10). Mention in pitfalls H2. +> - **MDE (minimum detectable effect):** power-calculation input (10/10). Mention in setup H2. +> - **Statsig, PostHog, Optimizely:** named platforms (10/10 mention at least one). Brief should mention all three with one-sentence positioning. +> +> **Standard entities (mention if relevant)** +> +> - **A/A test:** sanity check (5/10). Mention in pitfalls H2. +> - **Bonferroni correction:** multiple-testing adjustment (4/10). Mention in pitfalls H2. +> +> **Gap entities (differentiation opportunity)** +> +> - **CUPAC:** successor to CUPED (1/10). Mention in methodology H2 as the next-generation technique. Differentiates the piece from SERP consensus. +> - **Bayesian inference:** alternative to frequentist hypothesis testing (1/10; mentioned occasionally in advanced experimentation content). Mention in advanced section if word budget allows. + +The "Bayesian inference" entity is the example: it is a specific technical concept that some advanced experimentation content covers, where most SERP top-10 pieces stop at frequentist hypothesis testing. Adding the gap entity differentiates the piece without crowding the required-coverage list. + +--- + +## The entity-coverage failure mode + +The most common failure: the writer mentions all the required entities once each, in passing, without weight. The piece passes the entity-coverage check on a string-match basis but does not actually demonstrate topical depth. + +The fix in the brief: specify weight per entity. "Mention CUPED in passing in H2 #2; develop CUPED with formula and example in H2 #4." The brief is not just a list of entities to include; it is a placement plan. + +The writer's draft references the brief's entity placement plan. The editor reviews against placement, not just against presence. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md b/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md new file mode 100644 index 0000000..e89841b --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md @@ -0,0 +1,102 @@ +# Heading structure patterns + +H2 patterns, H3 sub-section patterns, featured-snippet bait, and the anti-patterns the brief should explicitly forbid. + +--- + +## H2 patterns that work + +**Question-style H2s.** "What is CUPED?" "How does CUPED reduce variance?" "When should I use CUPED?" These match how readers think and how Google's "People Also Ask" box surfaces queries. They are also the easiest format for AI engines to extract as citation candidates. + +**Declarative H2s.** "CUPED reduces variance by adjusting for pre-experiment covariates." "The formula uses a regression coefficient computed before assignment." Declarative H2s work for pieces that have a strong thesis or that summarize before they explain. + +**Comparison H2s.** "Platform-native: faster, narrower, opinionated." "Warehouse-native: slower, broader, custom-metric capable." Symmetrical H2s pair to set up a comparison; the reader sees the structure on the table of contents alone. + +**Imperative H2s.** "Configure the assignment unit." "Define the metrics." "Set the duration and MDE." Common for how-to guides; each H2 is one action. + +The discipline: pick one pattern and use it consistently within a piece. Mixing question + declarative + imperative reads as inconsistent and signals AI generation when the mixing is random. + +--- + +## H3 patterns under H2s + +H3s should add navigational value, not just structure for its own sake. + +**When to add H3s:** +- The H2 covers a topic with 3 to 5 sub-topics that the reader might want to jump to +- The H2 section is long enough (700+ words) that scanning needs sub-anchors +- The piece has a table of contents that benefits from sub-entries + +**When not to add H3s:** +- The H2 is short (under 400 words) +- The H3s would be a cosmetic enumeration that does not add navigation +- The piece is short overall (under 1,200 words); H3s are usually unnecessary + +**No orphan H3s.** Every H2 either has zero H3s or 2+ H3s. A single H3 under an H2 reads as a typo or an aborted edit. + +**No H2-H3-H4 cascades.** If a section needs H4s, the structure is wrong. Either the H2 is too broad and should split into two H2s, or the H4 is decoration that should be a paragraph. + +--- + +## The featured snippet bait pattern + +Place a 40 to 60 word answer paragraph immediately following the H2 question. Google often pulls this paragraph as the featured snippet; AI engines often quote it as the citation. + +**Example.** + +> ## What is CUPED? +> +> CUPED (Controlled-experiment Using Pre-Existing Data) is a variance-reduction technique that adjusts experimental measurements using pre-treatment covariates. The covariate's regression coefficient against the outcome is computed before assignment, then used to subtract baseline variance from the experiment's measurement, increasing statistical power without changing the experiment's design. + +The paragraph is self-contained: read alone, it answers the H2 question completely. The rest of the section expands on the answer with examples, formulas, edge cases. + +The discipline: the snippet paragraph is the most important paragraph in the section. Write it first; expand the section around it. + +--- + +## H2 ordering + +H2s should match the reader's mental model, not the writer's enthusiasm. + +**The standard order for informational pieces:** +1. What is it (definition, plain language) +2. Why does it matter (why the reader cares) +3. How does it work (mechanism, technical depth) +4. When to use it (decision criteria) +5. Common pitfalls (what goes wrong) +6. Wrap-up or call-to-action + +**The buried-lede anti-pattern.** H2 #4 has the actual answer the reader came for. The reader bounced at H2 #2. + +**The fix.** Put the obvious answer first. The writer's clever angle goes in H2 #4 or H2 #5, not H2 #1. + +--- + +## Anti-patterns the brief should forbid explicitly + +**Repetitive H2 structure.** All H2s start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. Vary the patterns within a piece, but keep one dominant pattern. + +**Buried lede.** The actual answer is in H2 #4. The brief specifies which H2 carries the keystone answer; usually H2 #1 or H2 #2. + +**Section length unevenness.** H2 #1 is 1,500 words; H2 #2 is 80 words. The 80-word section reads as a placeholder. Briefs should specify approximate word counts per H2 to enforce balance. + +**H3-only enumeration.** A section that is just an H2 plus a list of H3s with one paragraph each. Either the H2 should hold all the content, or the H3s deserve more depth. The half-and-half shape is a sign of incomplete thinking. + +**Misnumbered H2s in numbered series.** "5 ways to Y" with 6 H2s, or with 4. The mismatch reads as careless. + +--- + +## Brief field: how to populate the heading structure + +The brief lists the H2s in order with one-line notes. H3s only when they earn their keep. + +> **Heading structure outline** +> +> - H2 #1: "What is X?" (snippet paragraph mandatory; ~250 words section) +> - H2 #2: "Why X matters" (~300 words; one specific reader scenario) +> - H2 #3: "How X works" (~600 words; H3s: "the formula," "the assumption," "the implementation"; show the math) +> - H2 #4: "When to use X" (~400 words; decision-criteria list) +> - H2 #5: "Common pitfalls" (~400 words; 3 to 5 specific pitfalls with diagnoses) +> - H2 #6: "Wrap-up" (~150 words; call-to-action to related cluster piece) + +The writer follows the outline; deviations are flagged in the first draft for editor review. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md b/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md new file mode 100644 index 0000000..85918ae --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md @@ -0,0 +1,97 @@ +# Internal linking strategy + +Outbound and inbound linking patterns, orphan-content prevention, self-cannibalization check. + +--- + +## Two link directions to specify + +Every brief specifies links in two directions. + +**Outbound from this piece.** 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer is not deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. + +**Inbound to this piece, post-publish.** 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +--- + +## Outbound link selection + +The cluster pieces. The brief lists the supporting cluster pieces this piece should link to, with anchor text that matches each target's primary keyword. + +**Example for a pillar piece on "experimentation analytics dashboards":** + +> **Outbound links (writer integrates)** +> +> 1. Link to "CUPED variance reduction" (cluster piece) using anchor "CUPED" or "variance reduction with CUPED" in the methodology H2. +> 2. Link to "warehouse-native experimentation" (sister pillar) using anchor "warehouse-native experimentation" in the platform-vs-warehouse comparison H2. +> 3. Link to "feature flag tools comparison" (commercial-intent piece) using anchor "feature flag tools" in the deployment H2. +> 4. Link to "data warehouse setup" (foundation piece) using anchor "data warehouse" in the prerequisites H2. + +The discipline: anchor text matches the target's primary keyword. Generic anchors ("click here," "this article") do not pass ranking signals; keyword anchors do. + +--- + +## Inbound link queue + +The brief queues 1 to 3 existing pages that should add a link to the new piece after it publishes. The strategist updates these as part of the publish checklist. + +**Example continuing the same pillar:** + +> **Inbound link updates (post-publish task)** +> +> 1. Update "feature flagging" pillar to link to the new piece in the "measuring feature impact" section using anchor "experimentation analytics dashboards." +> 2. Update "PostHog vs Statsig" comparison to link to the new piece in the analytics-comparison H2. +> 3. Update homepage "Resources" section to add the new piece to the "Pillars" list. + +The inbound queue prevents the orphan-content failure mode. + +--- + +## The orphan-content failure mode + +Symptom: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. + +Cause: internal linking was an afterthought, handled by the writer or by SEO at publish time without strategic intent. The writer linked out to 3 pages because the brief said to; nobody linked back in because nobody owned that task. + +Fix: the brief queues the inbound updates explicitly. The publish checklist includes the inbound updates as a tracked task. Without a tracked task, the inbound updates do not happen; without inbound links, the piece is an orphan. + +The "5-link rule" diagnostic. Every published piece should have at least 5 internal links pointing to it within 30 days of publish. If a piece has fewer than 5 inbound links at the 30-day check, audit the inbound queue and add the missing links. + +--- + +## The self-cannibalization check + +Before briefing a new piece, check whether it would compete with an existing piece for the same keyword cluster. + +**The check.** Search the site for the target keyword. If an existing piece is in the top 5 of internal search results, flag it. + +**Three options when self-cannibalization is detected:** + +1. **Consolidate.** Merge the planned piece into the existing piece. Update the existing piece with the new angle, the new entities, the new examples. Keep one URL ranking; do not split ranking authority across two URLs. +2. **Differentiate.** Sharpen the angle of the new piece so it does not compete. The existing piece covers "what is feature flagging"; the new piece covers "feature flag rollout strategies for enterprise teams." Different intent, different audience, different SERP target. +3. **Kill one.** Determine which piece serves the cluster better. Redirect the loser to the winner. This is rare and usually signals the program does not have clear pillar structure. + +The discipline: flag self-cannibalization in the brief, not after the piece is written. Late detection is the expensive failure mode; the writer has already invested hours that now have to be either rewritten or thrown away. + +--- + +## Brief field: how to populate internal linking + +> **Internal linking** +> +> **Outbound (3 specified, 2 optional)** +> - Required: link to "CUPED variance reduction" with anchor "CUPED" in methodology H2 +> - Required: link to "warehouse-native experimentation" with anchor "warehouse-native" in comparison H2 +> - Required: link to "feature flag tools 2026" with anchor "feature flag tools" in deployment H2 +> - Optional: link to "data warehouse setup" with anchor "data warehouse" in prerequisites H2 (writer's call based on flow) +> - Optional: link to "experiment-design skill" with anchor "experiment design" in introduction (writer's call) +> +> **Inbound (post-publish, queued)** +> - Update "feature flagging" pillar (insert link in section 4) +> - Update "PostHog vs Statsig" comparison (insert link in analytics-comparison H2) +> +> **Self-cannibalization check** +> - Existing pieces on adjacent keywords: "experiment dashboards introduction" (different angle, no conflict) +> - No conflict; proceed with brief + +The brief is explicit about what is required, what is optional (writer chooses), and what is queued for post-publish. Three layers of discipline. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md b/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md new file mode 100644 index 0000000..eeaf7ce --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md @@ -0,0 +1,68 @@ +# Search intent classification + +Four-intent framework, dominant SERP format check, override patterns when intent and format mismatch. + +--- + +## The four standard intents + +**Informational.** The reader wants to learn. Queries: "what is CUPED," "how does feature flagging work," "experimentation analytics explained." SERP usually shows articles, guides, explainers, sometimes videos. Conversion is downstream (the reader signs up for the newsletter or returns to the site weeks later); ranking is the immediate goal. + +**Navigational.** The reader wants a specific brand, product, or page. Queries: "Statsig pricing," "LaunchDarkly login," "PostHog docs." SERP usually shows the brand site at #1 and a sitelinks block. Ranking against navigational intent is mostly impossible unless you are the brand. The exception: the reader-bypass pattern where adjacent brands rank for "competitor X login" by writing comparison content; play this carefully because it can read as bait. + +**Commercial.** The reader is researching a purchase. Queries: "best feature flag tools," "Statsig vs LaunchDarkly," "Optimizely review." SERP usually shows comparisons, reviews, "best X" listicles, sometimes detailed guides. The reader is in active evaluation; this is the highest-conversion intent for B2B SaaS content. + +**Transactional.** The reader is ready to buy. Queries: "Statsig signup," "buy LaunchDarkly," "PostHog free trial." SERP usually shows product pages, pricing pages, signup flows. Editorial content does not rank here; brand-owned commercial pages do. + +--- + +## The dominant SERP format check + +After classifying intent, scan the SERP top 10 and tag the dominant format. + +- **Article.** Long-form prose, single-author voice. Common for informational intent. +- **Listicle.** "10 best X," "7 ways to Y." Common for commercial-investigation intent. +- **Comparison.** Side-by-side X vs Y, table-heavy, decision frameworks. Common for high-funnel commercial intent. +- **Video.** YouTube embeds dominate the top of SERP. Common for how-to and tutorial queries. +- **Tool.** Calculator, generator, interactive tool. Common for "X calculator" or "X generator" queries. +- **Hybrid.** SERP shows a mix; usually tells you the keyword is contested or the intent is split. + +The dominant format tells you the shape of the piece, which is more decisive than the intent label. An informational keyword whose SERP is mostly listicles wants a listicle, not a long-form article. + +--- + +## The override pattern + +When intent and format mismatch, the format wins. + +**Case 1.** The intent feels informational ("how to design an A/B test") but the SERP shows mostly listicles ("7 steps to designing an A/B test"). Write the listicle. The SERP is the source of truth, not your priors about what the intent "should" look like. + +**Case 2.** The intent feels commercial ("best feature flag tools") but the SERP shows mostly long-form articles that mention many tools without ranking them. Write the long-form article. Listicle format would feel out of place against the SERP. + +**Case 3.** The SERP is genuinely split: half listicles, half long-form articles. Either format can rank. Pick based on the brand's voice and the piece's role in the cluster. + +The reason. Rankings come from matching the SERP's accepted shape; deviating costs ranking. Google's ranking algorithm is partly trained on what users click and stay on, which is selected from existing top-ranking content. Existing top-ranking content sets the shape; new content has to match the shape to compete. + +--- + +## The AEO and GEO consideration + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. + +A piece that mismatches the SERP format faces two problems: it is harder to rank in traditional search, and it is less likely to be cited by AI engines. The mismatch is a double cost. + +The exception: thought leadership that deliberately diverges. A piece arguing "the listicle format is misleading for this category; here is why" can rank by drawing traffic on the controversy and earning citations on the contrarian thesis. This is rare and risky; do not default to it. + +--- + +## Brief field: how to populate intent + format + +The brief field reads like this: + +> **Search intent + SERP format** +> Intent: commercial-investigation +> Dominant SERP format: long-form article + comparison table hybrid (top 5 are articles with embedded comparison tables; positions 6 to 10 are pure listicles) +> Format choice for this piece: long-form article with one comparison table at the midpoint +> SERP intent override: none (format choice matches dominant) + +The "format choice" line is decisive. The writer reads this line first and shapes the piece around it. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md b/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md new file mode 100644 index 0000000..ca3be09 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md @@ -0,0 +1,101 @@ +# Writer handoff protocols + +Human-writer handoff, AI-agent handoff, success-criteria anchoring. + +--- + +## The handoff has the same shape regardless of writer + +Whether the writer is a human freelancer, a staff editor, an internal SME, or an AI agent (Claude, ChatGPT, a Frase brief-runner, an AirOps workflow), the brief-to-writer handoff has the same five-step shape. + +1. Brief delivered with all 12 fields populated. +2. Writer asks clarifying questions before drafting (or the agent surfaces ambiguities as the first response). +3. Writer or agent acknowledges the success criteria explicitly. +4. First draft references the brief: which fields the draft addresses, which fields it could not address, why. +5. Editor reviews against the brief, not against personal taste. + +The shape is the same; the medium differs. Human writers acknowledge in Slack or email; AI agents acknowledge in the first message of the agent thread. Both cases: the acknowledgment is required, not optional. + +--- + +## Human-writer handoff + +**Step 1: brief delivery.** The brief is delivered as a single document (Notion page, Google Doc, dbt-style markdown file in the repo). The writer can read it in 5 minutes; if reading takes longer, the brief is too thick and should be cut. + +**Step 2: clarifying questions.** Before drafting, the writer asks clarifying questions. Common ones: + +- Is the target audience right? Is the JTBD specific enough to write to? +- Is the SERP intent classification right? Do I write a listicle or an article? +- Are these entities really required, or are some optional? +- Is the success criteria measurable from my side, or is it a downstream-only metric? + +The strategist answers questions in the same document; clarifications are versioned with the brief, not pasted into Slack and lost. + +**Step 3: acknowledgment.** The writer acknowledges in writing: "I have read the brief. I am writing to the success criteria of [X]. I will hit all required entities. I am clear on the SERP format choice." Acknowledgment is a 3-line message, not a treatise. + +**Step 4: first draft with reference.** The first draft is delivered with a reference note: "Hit 4 of 5 required entities; the 5th (CUPAC) was not in the SERP coverage I could find sources for, so I substituted the standard CUPED treatment per the brief's gap-entity guidance." The reference note tells the editor what to focus on in review. + +**Step 5: editor review against brief.** The editor reads the brief first, the draft second. The review framing is "the brief said X; the draft did Y; gap is Z." Personal taste comes after brief review, not before. + +--- + +## AI-agent handoff + +The shape is the same; the medium is structured. + +**Step 1: brief delivery as structured input.** The brief becomes a YAML or JSON object the agent ingests. Frase, AirOps, and similar tools structure briefs in their own schema; the same 12 fields appear regardless. Example minimal YAML structure: + +```yaml +target_keyword: experimentation analytics dashboards +supporting_cluster: + - CUPED variance reduction + - sequential testing + - feature flag rollout +search_intent: commercial-investigation +serp_format: long-form-article-with-comparison-table +target_audience: senior data engineer at 500-person SaaS +jtbd: choose between platform-native and warehouse-native experimentation +word_count_target: 2800 +heading_outline: + - { level: 2, text: "What an experimentation dashboard does" } + - { level: 2, text: "Platform-native vs warehouse-native" } + - { level: 2, text: "Metrics that earn their keep" } + - { level: 2, text: "Build vs buy" } + - { level: 2, text: "Common dashboards that ship trusted results" } +required_entities: + - { name: "CUPED", note: "mention with formula in methodology H2" } + - { name: "Statsig, PostHog, Optimizely", note: "mention all three" } +internal_links: + outbound: + - { target: /skills/cuped, anchor: "CUPED" } + - { target: /skills/warehouse-native, anchor: "warehouse-native experimentation" } + inbound_queued: + - { source: /pillars/feature-flagging, anchor: "experimentation analytics dashboards" } +anti_patterns: + - "do not use the team's do-not-use word list (see brand voice guide)" + - "do not write a listicle; SERP wants long-form" +success_criteria: + - "rank top 10 for target keyword in 90 days" + - "cited by ChatGPT for 'experimentation dashboard' queries within 60 days" +voice_reference: /brand/voice-guide +brief_version: 2 +brief_approver: editorial-lead@team.com +``` + +**Step 2: ambiguity surfacing.** The agent's first response surfaces ambiguities. "The brief lists CUPED as required, but the SERP top 10 only mention CUPED in 6 of 10 results; should I emphasize it or treat it as standard coverage?" The strategist answers; the brief gets versioned with the answer. + +**Step 3: acknowledgment.** The agent acknowledges in structured output: "Reading brief version 2. Target: 2,800 words. Format: long-form with comparison table. Will hit 4 required entities; need clarification on CUPED weight." Single message, machine-readable. + +**Step 4: first draft with reference.** The agent's draft is delivered with a structured note: which fields the draft addressed, which entities are present and where, what success criteria the draft is targeting. + +**Step 5: editor review.** The editor reviews the agent's draft using the same brief-first framing. Tools like Frase highlight which entities are present in the draft; the editor scans the highlights to confirm coverage. + +--- + +## Success-criteria anchoring + +The most-skipped handoff step is success-criteria acknowledgment. The writer or agent reads the brief, drafts the piece, delivers it; the success criteria sit in the brief unread. + +The fix: every handoff acknowledgment includes the success criteria verbatim. "I am writing to the success criteria: rank top 10 for 'experimentation analytics dashboards' in 90 days; get cited by ChatGPT for the topic within 60 days; drive 50 trial signups in the first 30 days." + +The acknowledgment is the contract restated in the writer's voice. Saying it out loud is what keeps it load-bearing during drafting. diff --git a/dist/pi/.agents/skills/content-distribution/SKILL.md b/dist/pi/.agents/skills/content-distribution/SKILL.md new file mode 100644 index 0000000..eeb09a6 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/SKILL.md @@ -0,0 +1,307 @@ +--- +name: content-distribution +description: "Content distribution as a discipline. Owned channels (newsletter, blog, social), earned channels (PR, syndication, mentions), paid channels (boosted posts, syndication networks), and the channel-fit decisions that distinguish strategic distribution from spam-everywhere. Audience-channel matching, content-channel matching, distribution cadence. Triggers on content distribution, channel strategy for content, owned earned paid channels, content amplification, content promotion, audience-channel matching, content-channel matching, distribution cadence, syndication strategy, organic distribution. Also triggers when content is publishing but reach is low, when the team is distributing on every channel without strategy, or when the content program needs a distribution discipline rather than just publication." +category: content +catalog_summary: "Content distribution discipline: owned, earned, and paid channels matched to audience and content type. Channel-fit decisions, distribution cadence, the strategic alternative to spam-everywhere or hope-and-pray" +display_order: 12 +--- + +# Content Distribution + +A senior editorial leader's playbook for content distribution as a discipline. Owned, earned, and paid channels matched to audience and content type, with the channel-fit decisions that distinguish strategic distribution from spam-everywhere or hope-and-pray. + +Content distribution is half the work and gets a fraction of the attention. Most programs spend 90% of capacity on production and 10% on distribution; the resulting ratio of effort-to-reach is consistently poor. The teams producing content that reaches audiences are the ones who treat distribution as a real discipline: channels chosen for fit, cadence calibrated to audience attention, owned-earned-paid balance set by program strategy, and effectiveness measured per channel. + +This skill is the channel discipline. Different from `content-repurposing` (which turns one piece into many formats), this skill is about getting content TO audiences via the right channels. The two skills compose: repurpose first, then distribute the right format on the right channel. + +The voice is the senior editorial leader who has watched programs underperform because distribution was treated as posting-after-publishing rather than as the equal half of the work. + +When to use this skill: building a distribution discipline for a content program, auditing why content publishes consistently but reach is low, calibrating owned-earned-paid balance, designing channel-fit decisions for a multi-format program. + +--- + +## What this skill is for + +This skill spans channel selection, audience-channel matching, content-channel matching, and distribution cadence. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes pieces. +- `editorial-qa` verifies before publish. +- `content-repurposing` turns one piece into many formats (transformation). +- **`content-distribution` (this skill)** gets content TO audiences via channels (channel work). + +The distinction from `content-repurposing` is load-bearing. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. Distribution is channel work: getting content to audiences via the right channels. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content programs that need reach, agencies running distribution for clients. + +What is not in scope: paid acquisition for purposes other than content amplification (covered by `paid-media-strategy`), the specific email channel discipline (covered by `email-sequences`), the AI-search optimization layer that sits across distribution channels (covered partially by `seo-aeo-geo`). + +--- + +## Hope-and-pray vs spam-everywhere vs channel-fit + +The keystone framing. + +**Hope-and-pray.** Publish and assume readers will find it. The piece goes live; the team links it on the blog homepage; maybe shares it once on social; assumes search and word of mouth will carry it. Output: most pieces reach a fraction of their potential audience because no deliberate distribution work was done. The program produces good content that nobody encounters. + +**Spam-everywhere.** Blast every piece on every channel regardless of fit. Every piece on LinkedIn, Twitter/X, Facebook, Threads, Mastodon, Bluesky, plus 5 emails to the full list, plus paid promotion on every platform. Audience tunes out; channels deprioritize the program; trust degrades. AI tooling has made spam-everywhere cheap and increasingly common, which makes the audience reaction sharper. + +**Channel-fit.** Distribute through channels matched to audience and content type. Specific channels chosen for specific pieces. Cadence calibrated to each channel's audience attention rhythm. Owned-earned-paid balance set by program strategy. Output: each distribution choice produces engagement from audiences who actually want the content; the program's distribution capacity is concentrated where it produces value. + +The litmus test. Ask of any distribution decision: which audience is this piece for, where does that audience consume content, does the piece's format fit that channel's conventions, and at what cadence does the channel reward presence? If the answers are specific, the distribution is channel-fit. If the answers are "everyone, everywhere, every channel, all the time," the distribution is spam-everywhere. + +--- + +## Channel taxonomy + +Three categories with sub-types within each. + +**Owned channels.** Channels the program owns and controls. + +- **Newsletter and email.** Direct relationship with subscribers. High control over reach (every subscriber receives the email); lower scale than social. +- **Blog and content site.** Owned property where pieces live. Search and direct traffic; the canonical version of pieces. +- **Social channels owned by the program.** LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account. Owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. +- **Communities and forums owned by the program.** Slack communities, Discord servers, dedicated discussion forums. Direct relationship with members. + +**Earned channels.** Channels where content reaches audiences via third-party amplification, not paid placement. + +- **PR and press coverage.** Journalists, podcasters, newsletter operators who cover the program's content because it is newsworthy or insightful. +- **Syndication.** Other publications republishing or excerpting the program's content (with appropriate attribution and canonical signaling). +- **Mentions and citations.** Other content marketing programs, industry analysts, AI search engines citing the program's content. +- **Word of mouth and shares.** Audiences sharing pieces with their networks; the program's content becoming part of conversations. + +**Paid channels.** Channels where paid spending amplifies content. + +- **Boosted social posts.** Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. +- **Promoted newsletter sends.** Sponsored placements in third-party newsletters. +- **Syndication networks.** Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. +- **Search advertising for content.** Paying for clicks on content pieces (less common; usually content is the organic side and paid is the conversion side). +- **Sponsored podcast or content placements.** Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Detail in [`references/channel-taxonomy.md`](references/channel-taxonomy.md). + +--- + +## Audience-channel matching + +Where the target audience actually consumes content. The distribution decision starts here. + +**The audit.** + +- Identify the audience for the program (or for the specific piece). +- Map where that audience spends time in their professional or consumer life. +- Identify the channels in that audience map where the audience is genuinely engaged (not just present). +- Match content distribution to those channels. + +**Common audience-channel maps.** + +- **B2B technical audiences.** LinkedIn high engagement; X moderate engagement (specific communities); industry newsletters; specific industry forums; podcasts in their domain. +- **B2B executive audiences.** LinkedIn high engagement; specific executive newsletters and podcasts; conferences and analyst-influence channels. +- **Consumer mass audiences.** Instagram, TikTok, YouTube, Facebook depending on demographic; broad email if subscribed. +- **Niche specialist audiences.** Specific subreddits, Discord servers, specialized newsletters, niche podcasts. Often higher engagement on smaller channels than on broad social. +- **Developer audiences.** GitHub, Hacker News, specific subreddits, dev-focused podcasts and newsletters, Twitter/X for parts of the community. + +**The mismatch failure.** Distributing on channels where the audience is present but not engaged produces low reach and low engagement. A B2B technical program publishing TikToks may technically reach audiences on TikTok but engage few of them; the audience is on TikTok for entertainment, not for technical learning. + +Detail in [`references/audience-channel-matching.md`](references/audience-channel-matching.md). + +--- + +## Content-channel matching + +Which formats fit which channels. Beyond audience match, the format must fit the channel's conventions. + +**Format-channel fit examples.** + +- Long-form analytical text fits blog, newsletter, LinkedIn long posts, X threads (for the right communities). Does not fit TikTok, Instagram Reels, or short-form video platforms. +- Short-form video fits TikTok, Reels, Shorts, increasingly LinkedIn video. Does not fit newsletter (where text leads) or owned blog (where written long-form leads). +- Statistic-driven content fits social with quote-graphics, AI search snippets, podcast mentions. Does not fit (as primary format) newsletter where context develops the stat. +- Conversational expert content fits podcasts, video interviews, possibly long social threads. Does not fit short-form video or single-post-format social. + +**The mismatch failure.** Distributing a format on a channel where the format does not fit produces low engagement. A 5,000-word whitepaper on TikTok (even repurposed) may not fit the format expectations of TikTok audiences regardless of audience overlap. + +**The compose-with-repurposing pattern.** When the audience is on a channel but the format does not fit, the right answer is often to repurpose into a format that does fit (see `content-repurposing`), then distribute. The composition is "repurpose for fit, distribute on channel." + +Detail in [`references/content-channel-matching.md`](references/content-channel-matching.md). + +--- + +## Distribution cadence + +How often, what mix, sustaining vs campaign rhythm. + +**Cadence axes.** + +- **Frequency per channel.** How often the program posts to each channel. +- **Mix.** What proportion of distribution is owned vs earned vs paid; what proportion is original vs derivative. +- **Rhythm.** Sustaining baseline cadence vs campaign spikes around flagship launches. + +**Common cadence patterns.** + +- **B2B program with content-led demand generation.** Newsletter weekly. Blog 2-4 posts per week. LinkedIn 3-5 posts per week. X 5-10 posts per week. Quarterly campaign spikes for flagship launches. +- **Consumer brand with broad-audience reach goals.** Daily Instagram content. Weekly newsletter. TikTok 2-4 posts per week. Owned blog 1-2 posts per week. Continuous paid amplification. +- **Niche specialist program with concentrated audience.** Newsletter weekly or bi-weekly. Owned blog 1-2 posts per month. Social on specific platforms 2-3 posts per week. Earned channels prioritized over paid. + +**Sustaining vs campaign.** + +- **Sustaining cadence.** The baseline rhythm. Audiences expect this cadence; deviation (long pauses or sudden spikes) affects engagement. +- **Campaign rhythm.** Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +**The cadence audit.** Programs that publish in fits and starts (3 posts in one week, then nothing for 3 weeks) underperform programs with steady cadence. Audience attention rewards predictability. + +Detail in [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md). + +--- + +## Owned-channel discipline + +Owned channels are the program's most reliable distribution. The discipline keeps them effective. + +**Newsletter.** Direct subscriber relationship; near-100% delivery to inboxes (modulo spam filtering). Cadence consistency matters: weekly is the most common cadence for B2B; bi-weekly works for higher-investment formats. Each send earns the next; sloppy sends lose subscribers. + +**Blog.** Canonical home for long-form content. SEO compounds over time; internal linking earns authority. The blog is where pieces persist; social and email send audiences to the blog. + +**Social channels owned by the program.** LinkedIn, X, Instagram, etc. Reach is platform-controlled (not the program's), but the program controls what publishes and when. Algorithmic favor varies; content that the platform's algorithm rewards gets reach beyond the follower base. + +**Podcast.** Owned distribution is the show feed; subscribers receive new episodes. Episodes also live on the blog with show notes; the show notes are an SEO asset. + +**Communities.** Slack, Discord, forums where the program facilitates discussion. The community is the audience the program is most directly engaged with; distribution to the community is the most reliable engagement signal. + +**The owned-channel anti-pattern: starvation.** Programs that under-invest in owned channels become dependent on third-party distribution. When platforms change algorithms, when paid costs rise, when earned channels go quiet, the program's reach collapses. Owned-channel investment is the durable foundation. + +Detail in [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md). + +--- + +## Earned-channel work + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real. + +**PR and press.** Pitching journalists, podcasters, newsletter operators on the program's content. Effective when the content is genuinely newsworthy or insightful; ineffective when pitches feel like blast emails. + +**Syndication.** Negotiating with other publications to republish or excerpt the program's content with appropriate attribution and canonical signaling. The syndication earns reach; the canonical link preserves SEO value. + +**Mentions and citations.** Earning mentions in other programs' content. Often happens when the program's pieces are genuinely useful as references; pieces that are generic or surface-level rarely get cited. + +**AI search citation.** Earning citations from AI search engines. Increasingly important as AI search grows; pieces designed for citation (see `content-repurposing`'s AEO extraction patterns) get cited at higher rates. + +**Word of mouth and shares.** Audiences sharing pieces with their networks. The hardest to earn deliberately; pieces that are genuinely valuable get shared. + +**The earned-channel investment.** Earned channels require relationship-building, pitch quality, and content quality. Programs that try to "do PR" with mass-blast pitches earn nothing; programs that invest in genuine relationships earn ongoing channel access. + +Detail in [`references/earned-channel-work.md`](references/earned-channel-work.md). + +--- + +## Paid promotion of organic content + +When boosting organic content earns its keep. + +**The pattern.** A piece publishes organically; some pieces show strong engagement signals; the program boosts those pieces with paid spend to extend reach. The paid spend is on content that the audience has already validated. + +**When boosting fits.** + +- The piece has demonstrated organic engagement (high CTR, high time-on-page, organic shares). +- The audience addressable through paid amplification overlaps with the program's target audience. +- The piece's value is clear enough that paid amplification produces engagement, not just impressions. + +**When boosting fails.** + +- Boosting low-engagement pieces because the calendar said so. Paid spend on content the audience does not engage with produces wasted budget. +- Boosting pieces that drive volume but not value. Pieces that produce clicks but not engagement may be drawing the wrong audience; paid amplification compounds the wrong-audience problem. +- Treating paid content amplification as a substitute for organic distribution. Paid amplifies what organic validated; paid alone produces transactional reach without the audience relationship organic builds. + +**The mix.** Most strong programs allocate 0-20% of distribution capacity to paid content amplification. Programs heavily dependent on paid promotion are usually programs that have not yet built owned and earned distribution. + +Detail in [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md). + +--- + +## Distribution measurement + +Which channels actually drive value. The discipline that prevents distribution-theater. + +**Per-channel metrics.** + +- **Reach.** How many people the channel surfaces the content to. +- **Engagement.** Click-through, time-on-page, scroll depth, completion rate (varies by format). +- **Conversion.** Newsletter signups, content downloads, qualified-lead actions, sales-cycle progression. +- **Attribution.** Which channels drove the audience members who eventually converted. + +**Channel-level analysis.** + +- Which channels produce the highest engagement-per-distribution-effort? Some channels look impressive (high reach) but produce low engagement. +- Which channels produce the highest conversion? Reach without conversion is vanity; conversion is value. +- Which channels' performance is changing over time? Algorithm shifts, audience migrations, and competitive landscape changes affect channel effectiveness. + +**Cross-channel attribution.** The same audience member encounters the program on multiple channels before converting. Single-touch attribution misrepresents which channels matter; multi-touch attribution is more accurate but harder to implement. + +**The measurement-honest program.** Cuts channels that consistently underperform. Increases investment in channels that consistently produce. Adjusts cadence based on engagement patterns, not on arbitrary publishing schedules. + +Detail in [`references/distribution-measurement.md`](references/distribution-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-distribution-failures.md`](references/common-distribution-failures.md). + +- "We publish but reach is low." Hope-and-pray pattern; no deliberate distribution work happening. +- "We post on every channel and engagement is flat." Spam-everywhere pattern; distribution capacity diluted across channels where the audience is not engaged. +- "Newsletter open rates are dropping." Cadence may be wrong, or list quality declining, or content not earning the open. Investigate. +- "Our LinkedIn engagement keeps falling." Possible algorithm shift; possible content-channel mismatch; possible cadence issue. +- "Our PR pitches are getting ignored." Mass-blast pitching; relationships not built; pitches not specific to recipient. +- "We invest heavily in paid but engagement is low." Paid amplifying low-organic-engagement content; paid as substitute for owned development. +- "We do not know which channels are working." Measurement absent; program operating on channel-presence rather than channel-effectiveness. +- "Content publishes but audiences do not see it." Distribution treated as posting; cadence wrong; channels mismatched to audience. +- "We launched campaign distribution but it landed quietly." Campaign rhythm not earned by sustaining cadence; audiences not primed to attention-spike. +- "Our owned audience is small." Long-term investment in owned channels skipped; program dependent on third-party distribution. +- "Earned channels are not producing." Treating earned as automatic; relationships not built; pitches not earning. +- "Paid distribution costs are rising." Auction dynamics on paid platforms; programs heavily dependent on paid see costs rise without offsetting owned/earned investment. + +--- + +## The framework: 12 considerations for content distribution + +When designing or auditing a distribution program, walk these 12 considerations. + +1. **Channel-fit, not hope-and-pray or spam-everywhere.** Specific channels for specific audiences and formats. +2. **Channel taxonomy understood.** Owned, earned, paid; sub-types within each; which channels the program actually uses. +3. **Audience-channel matching.** Where the target audience actually engages, not just where they are present. +4. **Content-channel matching.** Format fits the channel's conventions and audience expectations. +5. **Distribution cadence calibrated.** Per-channel frequency, owned-earned-paid mix, sustaining-vs-campaign rhythm. +6. **Owned-channel discipline.** Newsletter, blog, social channels owned by the program, possibly podcast and community. Long-term investment. +7. **Earned-channel work.** PR, syndication, mentions, AI-search citation. Relationship investment. +8. **Paid promotion of organic content.** Boost pieces that have organic engagement; do not substitute paid for owned. +9. **Cross-channel attribution.** How audiences encounter the program across channels before converting. +10. **Per-channel measurement.** Reach, engagement, conversion. Channels that underperform get cut. +11. **Sustaining-vs-campaign rhythm.** Baseline cadence plus campaign spikes for flagship launches. +12. **Distribution capacity allocation.** Real budget; not done in the cracks. + +The output of the framework is a distribution program where each channel choice is deliberate, each cadence decision matches audience attention, each measurement informs the next decision, and the program's reach grows because the work is concentrated where it produces value. + +--- + +## Reference files + +- [`references/channel-taxonomy.md`](references/channel-taxonomy.md) - Owned, earned, paid with sub-types. Newsletter, blog, social, communities, PR, syndication, mentions, boosted social, syndication networks, sponsored placements. +- [`references/audience-channel-matching.md`](references/audience-channel-matching.md) - Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction. +- [`references/content-channel-matching.md`](references/content-channel-matching.md) - Format-channel fit. The compose-with-repurposing pattern. The format-mismatch failure mode. +- [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md) - Frequency, mix, rhythm. Sustaining vs campaign. Common cadence patterns by program type. +- [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md) - Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. +- [`references/earned-channel-work.md`](references/earned-channel-work.md) - PR, syndication, mentions, AI-search citation, word of mouth. Relationship investment. +- [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md) - Boosting organic content. When paid amplification fits and when it fails. The paid-as-substitute anti-pattern. +- [`references/distribution-measurement.md`](references/distribution-measurement.md) - Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. +- [`references/common-distribution-failures.md`](references/common-distribution-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: distribution is half the work + +Most content programs are production-heavy and distribution-light. The teams producing flagship pieces typically spend 90% of capacity producing and 10% distributing; the resulting reach matches the inverse ratio. Pieces that took 60 hours to produce reach a fraction of their potential audience because the 6 hours allocated to distribution were not enough to do the channel work. + +The discipline is not "distribute more"; it is "distribute deliberately." Channel-fit decisions concentrate distribution work where it produces value. Owned-channel investment builds durable foundations. Earned-channel relationships accumulate over years. Paid promotion amplifies what organic validated. Measurement informs what to keep and what to cut. + +When in doubt about whether a distribution program is ready, ask: are channels chosen for fit, is audience-channel matching deliberate, do formats fit channels, is cadence calibrated, is owned-channel investment in place, are earned-channel relationships being built, is paid amplification on organically-validated pieces, is measurement informing the next decisions? If yes to all of those, the program is real. If no to any, the gap is where reach will fall short of what the production work earned. diff --git a/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md b/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md new file mode 100644 index 0000000..c1d5753 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md @@ -0,0 +1,172 @@ +# Audience-channel matching + +Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction that prevents distributing on channels where the audience is technically present but not actually paying attention. + +The first and most consequential distribution decision is which channels to invest in. Most programs over-invest in channels with high audience presence but low audience engagement, and under-invest in smaller channels where the audience is genuinely paying attention. The audit shifts capacity to where engagement happens. + +--- + +## The presence-vs-engagement distinction + +A channel where the audience is present is not necessarily a channel where the audience is engaging. + +**Presence.** Members of the target audience have accounts on the platform. They could see the program's content if they encountered it. + +**Engagement.** Members of the target audience are actively using the platform for the kind of content the program produces. They click; they comment; they share; they convert. + +**The mismatch failure mode.** A B2B technical program publishing TikTok content. The audience may have TikTok accounts (presence), but the audience is on TikTok for entertainment, not for B2B technical learning (low engagement for the program's content). The presence creates a false signal that the channel might work; the engagement reality is that distribution capacity goes to a low-return channel. + +**The audit question.** Not "is the audience on this channel?" but "is the audience consuming this kind of content on this channel?" + +--- + +## Common audience-channel maps + +Mappings that show up repeatedly across program types. Programs should still validate against their own audience research; the maps below are starting points. + +### B2B technical audiences + +Engineers, technical decision-makers, developer-influencers, technical product managers. + +**High engagement.** LinkedIn (especially long-form posts and articles); X/Twitter (specific technical communities); industry-specific newsletters; specialized podcasts; specific subreddits and Discord servers; GitHub for code-adjacent content; technical conferences and analyst-influenced channels. + +**Moderate engagement.** YouTube for tutorial and conference-talk content; Hacker News for specific topics; vendor-platform community sites (AWS, Azure, GCP forums; specific tool communities). + +**Low engagement.** TikTok, Instagram, Facebook for the program's primary content. Some technical professionals consume these for entertainment but rarely for technical content. + +### B2B executive audiences + +C-suite, VPs, senior strategy leaders. + +**High engagement.** LinkedIn (long-form posts, articles, sometimes video); specific executive newsletters and podcasts; analyst-influence channels (Gartner, Forrester); event-driven media (high-quality conferences, executive roundtables). + +**Moderate engagement.** Industry-specific publications; some podcasts; X/Twitter for specific topics with executive commentary. + +**Low engagement.** Most consumer-focused social platforms. Executives often have low time for content consumption; the channels where they engage are concentrated. + +### Consumer mass audiences + +Broad consumer demographics for B2C brands. + +**High engagement.** Instagram, TikTok, YouTube, Facebook (varies by demographic age and interest). Email newsletter for engaged subscribers. Pinterest for visual-product categories. Specific subreddits for interest-driven topics. + +**Moderate engagement.** X/Twitter (declining for many consumer demographics). LinkedIn (low for most consumer use cases). + +**Low engagement.** Most B2B-oriented channels. + +### Niche specialist audiences + +Concentrated audiences within specific domains (cybersecurity professionals, fertility-tracking enthusiasts, specific hobby communities). + +**High engagement.** Specific subreddits, Discord servers, specialized newsletters and podcasts. Often higher engagement on smaller channels than on broad platforms. + +**Moderate engagement.** Domain-specific Twitter/X communities; some LinkedIn; YouTube for educational content. + +**Low engagement.** Broad social platforms where the audience is small fraction of total platform population. + +### Developer audiences + +Software developers across stacks and seniority levels. + +**High engagement.** GitHub (code-adjacent content); Hacker News (specific topics); specific subreddits; Twitter/X for parts of the dev community; dev-focused podcasts and newsletters; YouTube for tutorial content. + +**Moderate engagement.** LinkedIn for senior developers; Stack Overflow for Q&A-driven content (different distribution model than programs typically use); Discord servers for specific tools. + +**Low engagement.** TikTok, Instagram, Facebook, Pinterest for primary content. + +### Founder and startup audiences + +Founders, startup operators, early-stage investors. + +**High engagement.** Twitter/X (the founder community has historically been engaged here); LinkedIn for some segments; specific newsletters (Lenny's, Substack-based founder newsletters); specific podcasts; YC-adjacent forums. + +**Moderate engagement.** YouTube for some long-form content; specific subreddits. + +**Low engagement.** Most mass-consumer platforms. + +--- + +## The audience-channel audit + +A short framework for matching audience to channels. + +1. **Define the target audience specifically.** Not "marketers" but "B2B SaaS marketing leaders at companies with 50-500 employees, primarily in North America and Western Europe." Specificity unlocks the matching. +2. **Map where this audience spends time professionally.** Where do they get news, learn new ideas, hear from peers, encounter products? +3. **Map where this audience spends time consuming the kind of content the program produces.** Different from professional time generally; specific to the content type. +4. **Identify channels where the audience engages.** Not just where they have accounts. Engagement signals: comments, shares, conversion behaviors. +5. **Score channels by engagement potential.** High, moderate, low. The high-engagement channels get primary distribution capacity. + +--- + +## Audience-research methods for the audit + +How to actually identify where audiences engage. + +**Customer interviews.** Ask existing customers where they consume content related to the program's topic. The answers are the audience's revealed-preference distribution map. + +**Audience surveys.** Quantitative confirmation of channel-engagement patterns. Surveys can over-represent platforms respondents feel they should use; the customer interviews ground-truth the survey data. + +**Existing program data.** Where does the program's existing audience come from? Referral data, UTM analysis, conversion attribution. Channels that produce existing audience are channels where the audience is engaging with the program. + +**Competitive analysis.** Where do competing programs distribute? Where do they appear to earn engagement (visible signals: comments, shares, mentions)? Competitive distribution patterns inform but should not dictate the program's choices. + +**Industry research.** Some industry research firms publish channel-engagement data by audience segment. Useful as starting points; should be triangulated with the program's own data. + +--- + +## The audience-channel mismatch failure mode + +The pattern when audience-channel matching is skipped. + +**The symptom.** The program publishes consistently on multiple channels. Engagement is flat or declining. Distribution capacity is spread thin. The team cannot identify which channels are working because none of them are working clearly. + +**The diagnosis.** Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +**The cure.** Run the audience-channel audit. Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. The total distribution capacity stays the same; the allocation shifts. + +**Recovery time.** Cutting underperforming channels and concentrating capacity on engaging channels typically produces visible engagement improvements within 4-8 weeks. + +--- + +## When audience-channel maps shift + +Audiences move across channels over time. Maps that fit a program 3 years ago may not fit now. + +**Common shifts.** + +- Twitter/X engagement has declined for many B2B audiences as the platform has changed; LinkedIn has absorbed some of the shifted attention. +- TikTok has expanded into demographics it did not initially serve. +- Newsletter consumption has grown across most audience types as inbox-based content consumption has become more accepted. +- AI-search citation has emerged as a distribution channel that did not exist meaningfully before 2024. + +**The audit cadence.** Run the audience-channel audit at least annually. Maps that have not been refreshed for 18+ months are likely outdated. + +--- + +## The audience-channel-content-type triangle + +Audience-channel matching is one of three matching decisions; content-channel matching is another (see `content-channel-matching.md`); the third is content-audience matching (the source piece is for the right audience in the first place). + +**The triangle.** + +- Audience matches channel. +- Content matches channel. +- Content matches audience. + +**The failure modes.** + +- Audience-channel mismatch: distribution where the audience is not engaged. +- Content-channel mismatch: format does not fit the channel's conventions. +- Content-audience mismatch: the piece is not actually for the channel's audience even if both fit individually. + +The triangle is what produces channel-fit distribution. All three matchings need to hold for distribution to produce engagement. + +--- + +## Methodology-level choices that stay in the public skill + +The presence-vs-engagement distinction, the common audience-channel maps, the audience-channel audit, audience-research methods, the mismatch failure mode, the map-shift recognition, the audience-channel-content-type triangle. + +## Implementation choices that stay internal + +Specific audience-research surveys and interview templates. Specific UTM tracking and attribution conventions. Specific competitive analysis tooling. Specific channel-engagement scoring rubrics. The team's own audience-segment definitions. These vary by team, audience, and tooling. diff --git a/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md b/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md new file mode 100644 index 0000000..c826a25 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md @@ -0,0 +1,215 @@ +# Channel taxonomy + +Owned, earned, paid with sub-types. The full taxonomy that grounds channel-fit decisions. + +Programs that distribute well think in terms of the taxonomy. Programs that distribute poorly think in terms of "social media" or "content marketing" without distinguishing the categories. The distinction matters because owned, earned, and paid channels have different cost structures, different reach characteristics, and different roles in a program's distribution mix. + +--- + +## Owned channels + +Channels the program owns and controls. + +### Newsletter and email + +The most direct owned distribution. + +**Characteristics.** Direct relationship with subscribers. The program controls what sends, when, and to whom. Near-100% delivery to inboxes (modulo spam filtering and engagement-based deliverability adjustments). + +**Strengths.** No platform algorithm between the program and the audience. Engagement is cleanly measured. Audience commitment signal is strong (people who subscribe and stay subscribed are valuable signal). + +**Weaknesses.** Slow to grow vs broad-reach social channels. Each subscriber is real work to acquire and retain. + +**The newsletter discipline.** Cadence consistency, content quality matching subscriber expectations, single-CTA-per-send, deliverability hygiene. See `email-sequences` for the email-specific discipline. + +### Blog and content site + +The program's content home. + +**Characteristics.** Owned property where pieces live as canonical versions. Search traffic compounds over years. Internal linking earns authority. Direct traffic from audiences who know the property. + +**Strengths.** Compounding asset. Content that earns search position keeps producing traffic indefinitely. Full design and presentation control. + +**Weaknesses.** Slow to start producing meaningful traffic. SEO investment is multi-year. Without distribution to the blog, pieces sit unread. + +**The blog discipline.** Architecture and technical SEO foundations (see `seo-technical`); pillar and cluster organization (see `pillar-content-architecture`); refresh discipline (see `content-refresh-system`); on-page optimization (see `seo-onpage`). + +### Social channels owned by the program + +LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account, etc. + +**Characteristics.** The program runs the account; the platform controls reach via algorithms. Reach varies by platform algorithm changes, audience size, content engagement signals. + +**Strengths.** Larger potential audience than newsletter. Algorithmic favor can produce reach beyond follower base when content earns engagement signals. + +**Weaknesses.** Platform-controlled reach. Algorithm shifts can dramatically reduce reach without warning. Audiences are renting the platform; the program does not own the relationship the way newsletter signals ownership. + +**The owned-social discipline.** Per-platform conventions; cadence calibrated to platform attention rhythm; content adapted for platform; engagement-signal optimization; account-health hygiene. + +### Podcast + +Owned audio distribution. + +**Characteristics.** The show feed is owned; subscribers receive new episodes through their podcast app. Episodes also live on the blog with show notes; cross-platform distribution (Spotify, Apple Podcasts, YouTube) extends reach. + +**Strengths.** Intimate audience relationship. High engagement when audience is loyal. Long-form context for substantive content. Show notes are SEO assets. + +**Weaknesses.** Production cost is real (audio quality, editing, hosting). Discoverability depends on platform algorithms and word-of-mouth. + +**The podcast discipline.** See podcast-specific format conventions; show notes as derivative format; consistent episode cadence; cross-platform distribution for reach. + +### Communities + +Slack communities, Discord servers, dedicated discussion forums. + +**Characteristics.** Direct relationship with members. The program facilitates discussion; members engage with each other and with program content. + +**Strengths.** Highest-engagement audience the program has. Community feedback informs content and product. Members become advocates. + +**Weaknesses.** Community management is meaningful work. Communities require continuous facilitation; abandoned communities decay and signal decline. + +**The community discipline.** Active moderation; sustained value-delivery to members; integration with the broader content program (members get access; program content is shared in community). + +--- + +## Earned channels + +Channels where content reaches audiences via third-party amplification, not paid placement. + +### PR and press coverage + +Journalists, podcasters, newsletter operators who cover the program's content. + +**Characteristics.** Third parties cover the program's content because it is newsworthy, insightful, or fits their editorial agenda. The program does not pay for coverage; the value exchange is editorial fit. + +**Strengths.** External authority signal. Reach into audiences the program does not have direct relationships with. Often higher trust signal than program's own distribution. + +**Weaknesses.** Hard to predict; relationship-dependent; pitches that miss editorial fit produce nothing. + +**The PR discipline.** Genuine relationship-building with relevant journalists. Pitches specific to recipient and to actual newsworthy content. Quality over quantity; mass-blast pitches earn no coverage and damage future relationship potential. + +### Syndication + +Other publications republishing or excerpting the program's content. + +**Characteristics.** Programs negotiate with other publications to republish or excerpt their content. Canonical link signaling preserves SEO value. Attribution is mandatory. + +**Strengths.** Reach into the syndication partner's audience. Some pieces reach more readers via syndication than via owned distribution. + +**Weaknesses.** Negotiation overhead. Risk of authority dilution if canonical signaling is wrong. Partners may discontinue syndication; the program cannot rely on syndication as primary distribution. + +**The syndication discipline.** Canonical link tags; clear attribution; partner relationship management; selective syndication (not every piece warrants syndication). + +### Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +**Characteristics.** External programs reference the program's content as a source. The program's authority signal compounds with each citation. + +**Strengths.** Compounding authority. Long-term backlink and citation profile that informs SEO and AI-search positioning. + +**Weaknesses.** Largely outside the program's direct control. The program can produce citation-worthy content (specific data, framework introductions, primary research) but cannot force citation. + +**The citation-earning discipline.** Produce content with citation hooks: original data, named frameworks, primary research, contrarian-but-defensible positions. Pieces that are generic rarely get cited; pieces that are specifically valuable do. + +### Word of mouth and shares + +Audiences sharing pieces with their networks. + +**Characteristics.** The program's content becomes part of conversations beyond the program's distribution. Most valuable when sharing happens in private channels (DMs, Slack channels, internal corporate emails) where the program cannot directly track. + +**Strengths.** Highest-trust distribution. A piece shared by a colleague carries more weight than the same piece in a feed. + +**Weaknesses.** Hard to measure; hard to engineer deliberately. Pieces that earn word-of-mouth are pieces that are genuinely valuable to the audience. + +**The word-of-mouth discipline.** Produce content that audiences want to share. Specific, useful, citation-worthy. Avoid generic content that nobody bothers to share even if they read it. + +--- + +## Paid channels + +Channels where paid spending amplifies content. + +### Boosted social posts + +Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. + +**Characteristics.** The program pays the platform to show the post to additional audiences (often defined by audience targeting parameters). The post still appears as an owned post; the paid spend extends its reach. + +**Strengths.** Quick to deploy; extends reach of pieces that have demonstrated organic engagement; measurable. + +**Weaknesses.** Costs accumulate; auction dynamics drive prices up over time; pieces that performed organically may not maintain engagement at scaled paid reach. + +**The boost discipline.** Boost pieces with strong organic engagement signals; do not boost pieces that did not earn engagement organically; treat boost spend as amplification of validation, not as substitute for organic. + +### Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +**Characteristics.** The program pays a third-party newsletter to feature its content. The newsletter audience sees the program's content alongside the newsletter's editorial content. + +**Strengths.** Reach into newsletter audiences with strong attention rhythms. Often higher engagement than broad social paid amplification. + +**Weaknesses.** Requires negotiation; sponsorship feels different from editorial; price-per-send varies. + +**The sponsored-newsletter discipline.** Match the newsletter's audience and tone; sponsored content that fits the newsletter feels like value; sponsored content that clashes feels like an ad. + +### Syndication networks + +Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. + +**Characteristics.** Programs pay per click; content appears on third-party sites in "you may also like" or "recommended for you" placements. + +**Strengths.** Volume reach at variable cost; geographic and audience targeting. + +**Weaknesses.** Quality of audience varies; engagement often low; reputation challenges (some networks have brand-safety concerns). + +**The syndication-network discipline.** Test cautiously; measure beyond clicks (engagement, time-on-page); some networks fit some programs and not others. + +### Search advertising for content + +Paying for clicks on content pieces. + +**Characteristics.** Less common; usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +**Strengths.** High-intent audiences; quick reach for high-value content. + +**Weaknesses.** Cost-per-click on competitive queries; content that converts via paid clicks usually has clear conversion signals. + +**The content-search-ads discipline.** Reserve for content with clear conversion or lead-capture goals; measure paid traffic against owned-traffic comparison; high-value content only. + +### Sponsored podcast or content placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +**Characteristics.** The program pays to be featured in a third-party podcast or newsletter, often via host-read endorsement. + +**Strengths.** Host-read endorsements carry strong trust signal. Audiences of niche podcasts and newsletters are highly engaged. + +**Weaknesses.** Cost varies; production quality matters; mismatched host-program fit damages both. + +**The sponsored-placement discipline.** Match host audience to program audience; provide hosts with substantive talking points; measure on engagement signals beyond impressions. + +--- + +## Channel mix evolution over program maturity + +Programs at different stages have different channel mixes. + +**Early-stage programs.** Heavy owned-channel investment (newsletter, blog). Limited earned (relationships not yet built). Limited paid (budget often constrained). The early program is building the foundation. + +**Mid-stage programs.** Owned channels producing reliable distribution. Earned channels developing (PR relationships, syndication, mentions accumulating). Paid amplification of best organic pieces. + +**Mature programs.** Owned channels are reliable foundations. Earned channels are significant traffic and authority sources. Paid amplification is strategic, not load-bearing. + +**The maturity audit.** Programs heavily dependent on paid distribution often have under-invested in owned and earned. The dependency is visible: when paid budgets cut, reach collapses; when paid costs rise (as they do over time on auction-based platforms), program effectiveness degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The owned/earned/paid taxonomy with sub-types, the characteristics and disciplines per sub-type, the channel mix evolution by program maturity, the maturity audit. + +## Implementation choices that stay internal + +Specific platform tooling per channel. Specific community management software. Specific PR-relationship CRMs. Specific paid-platform configurations and bidding strategies. Specific syndication-network vendor selections. The team's own conventions for channel-mix targets at different program stages. These vary by team, budget, and program shape. diff --git a/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md b/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md new file mode 100644 index 0000000..92119ff --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md @@ -0,0 +1,193 @@ +# Common distribution failures + +Twelve-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most distribution failures share a single root, which is treating distribution as posting-after-publishing rather than as the equal half of the work. + +--- + +## Failure 1: Hope-and-pray (publish and wait) + +**Symptom.** The program publishes consistently. Reach is low. The team is unclear why; the content seems strong. + +**Diagnosis.** No deliberate distribution work. Publishing is treated as the end of the work; audiences are expected to find the content via search, social, and word of mouth without proactive distribution. + +**Cure.** Apply the channel-fit discipline. Identify which channels the audience engages on; distribute deliberately on those channels with appropriate format adaptation. Treat distribution as half the work. + +**Capacity recovery.** Programs that shift from hope-and-pray to deliberate distribution typically see 2-5x reach improvements within 8-12 weeks. + +--- + +## Failure 2: Spam-everywhere + +**Symptom.** The program posts on every channel: LinkedIn, X, Facebook, Threads, Bluesky, Instagram, TikTok, plus 5 emails per week, plus paid promotion on every platform. Engagement is flat across all channels. + +**Diagnosis.** Distribution capacity diluted across channels where the audience is not engaged. Each channel gets cursory attention; none gets enough to produce real engagement. + +**Cure.** Apply the audience-channel matching discipline. Cut channels where the audience is present but not engaged. Concentrate capacity on channels that produce engagement. + +**Recovery time.** Cutting underperforming channels and concentrating capacity typically produces visible engagement improvements within 4-8 weeks. + +--- + +## Failure 3: Newsletter open rates declining + +**Symptom.** The newsletter open rate has declined from 35% to 22% over 6 months. Subscribers are not opening sends. + +**Diagnosis.** Multiple possible causes. Cadence may be wrong (too aggressive or too sparse). List quality may be declining (lapsed subscribers depressing engagement signal). Subject lines may not be earning the open. Content may not be matching subscriber expectations. + +**Cure.** Diagnose first. Pull cohort data: are recent subscribers opening at higher rates than long-term subscribers (suggests content fit decline)? Are sends with specific subject-line patterns performing better (suggests subject line issue)? Is open rate consistent across send-times (rules out timing)? + +Apply the relevant fix: list pruning for lapsed subscribers; subject-line improvement; cadence adjustment; content recalibration. + +--- + +## Failure 4: LinkedIn engagement falling + +**Symptom.** LinkedIn engagement on the program's posts has declined. Comments, shares, and reach signals all lower than 6 months ago. + +**Diagnosis.** Multiple possible causes. Algorithm shift; content-channel mismatch; cadence issue; account-health degradation. LinkedIn algorithm changes have affected many programs over the past several years. + +**Cure.** Audit content quality (does it match what worked previously?). Audit cadence (within platform-rewarded range?). Check account-health signals (engagement on others' content, not just own posts; profile completeness; consistent branding). If algorithm shifts are the cause, content patterns may need recalibration to fit current algorithmic preferences. + +--- + +## Failure 5: PR pitches ignored + +**Symptom.** The program pitches journalists for coverage. Most pitches get ignored. Coverage is rare. + +**Diagnosis.** Mass-blast pitching, or relationships not built before pitching, or pitches not specific to recipient. + +**Cure.** Apply the relationship-first PR principle (see `earned-channel-work.md`). Build relationships with relevant journalists over months before pitching. Pitch specific to recipient with reference to their recent work. Reduce pitch volume; increase pitch quality. + +**Timeline.** PR relationships build over 1-3 years. Programs in mass-blast mode cannot fix this in a quarter; the cure is multi-year. + +--- + +## Failure 6: Heavy paid investment, low engagement + +**Symptom.** The program spends significantly on paid amplification. Engagement metrics are low. Cost-per-engagement keeps rising. + +**Diagnosis.** Paid amplification is amplifying low-organic-engagement content. Or paid is substituting for owned-channel investment. Or both. + +**Cure.** Apply the boost-organic pattern. Only boost pieces that have demonstrated organic engagement. Reduce paid spend on pieces without organic validation. Reallocate capacity toward owned-channel investment for long-term durability. + +--- + +## Failure 7: No measurement + +**Symptom.** The team operates on intuition about which channels are working. Different team members have different intuitions. Decisions about cadence, channel mix, and capacity are not informed by data. + +**Diagnosis.** No measurement infrastructure or no measurement-to-decision discipline. + +**Cure.** Establish per-channel metrics; channel-level analysis; cross-channel attribution. Quarterly measurement reviews that produce specific decision changes. See `distribution-measurement.md` for the discipline. + +--- + +## Failure 8: Posting without distribution + +**Symptom.** Content publishes. The piece appears on the blog and is shared once on social. The team considers distribution complete. + +**Diagnosis.** Distribution is treated as the act of posting. The work of getting content TO audiences is not happening. + +**Cure.** Plan distribution at production time. Each piece has a distribution plan: which channels, what cadence, what cross-channel co-promotion. Distribution is part of the production work, not an afterthought. + +--- + +## Failure 9: Campaign launches landing quietly + +**Symptom.** The team prepared a flagship launch with significant cross-format coordination. Launch day arrives. Engagement is muted. + +**Diagnosis.** Sustaining cadence was insufficient before the launch. Audiences were not warm; the campaign moment did not feel like a campaign moment because no audience habit primed it. + +**Cure.** Build sustaining cadence first. Campaign rhythm is earned by sustaining cadence. Programs that try to spike attention without sustaining baseline produce limited campaign engagement. + +--- + +## Failure 10: Owned audience small after years + +**Symptom.** After 2-3 years of program operation, the newsletter has 800 subscribers; the blog gets 5,000 monthly visits; the community is small. + +**Diagnosis.** Long-term investment in owned channels was skipped. Program reach (if there is reach) is rented from third parties. + +**Cure.** Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +--- + +## Failure 11: Earned channels not producing + +**Symptom.** The program has occasional coverage from third parties but no reliable earned-channel reach. Mentions are rare; syndication is informal; AI-search citation rates are low. + +**Diagnosis.** Earned channels are being treated as automatic. Relationship investment, pitching discipline, and citation-hook content design are not in place. + +**Cure.** Apply the earned-channel investment discipline. Specific capacity to relationship-building, pitching, syndication, citation tracking. Investment compounds over years. + +--- + +## Failure 12: Paid distribution costs rising + +**Symptom.** Paid amplification was producing acceptable cost-per-engagement 12-18 months ago. Costs have risen 50-100% since then. Engagement is similar; costs are higher. + +**Diagnosis.** Auction dynamics on paid platforms. Programs heavily dependent on paid see costs rise without offsetting owned/earned investment that would reduce paid dependence. + +**Cure.** Build owned and earned channels to reduce paid dependence. Within paid, focus on the highest-ROI placements; cut lower-performing paid spend. Recognize that paid costs typically rise over time on auction-based platforms; budget assumptions should account for this. + +--- + +## Failure 13: Channels mismatched to audience + +**Symptom.** The program is present on multiple channels. Engagement is low across most of them. The team is confused because the channels seemed obvious choices. + +**Diagnosis.** Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +**Cure.** Run the audience-channel audit (see `audience-channel-matching.md`). Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. + +--- + +## Failure 14: Cadence too aggressive + +**Symptom.** Email subscribers are unsubscribing at higher rates. Social engagement is declining despite increased posting volume. The team is producing more content per week than ever; reception is worse. + +**Diagnosis.** Cadence has exceeded audience attention norms. The team is over-publishing. + +**Cure.** Reduce cadence to channel norms. Test reduced frequency for 6-8 weeks; observe whether engagement improves and unsubscribes slow. Most programs benefit from disciplined cadence rather than maximal cadence. + +--- + +## Failure 15: Cadence inconsistent + +**Symptom.** The program publishes 3 times in a week, then nothing for 3 weeks, then 5 times in 4 days. Audiences cannot develop habit. + +**Diagnosis.** No cadence discipline. Production happens when capacity allows; distribution follows production rather than following audience-attention rhythm. + +**Cure.** Establish cadence targets per channel. Build content calendars that smooth publication across the period. Capacity that produces content unevenly should distribute the publication evenly even if production was uneven (held pieces release on schedule). + +--- + +## Failure 16: No campaign rhythm + +**Symptom.** The program runs sustained cadence consistently. Flagship launches happen. The launches receive routine treatment; no campaign coordination produces outsized attention. + +**Diagnosis.** Campaign rhythm has not been built. The program has sustained cadence but no concentrated moments. + +**Cure.** Plan 4-12 campaign moments per year. Each campaign concentrates cross-format distribution for 4-6 weeks. The campaigns are earned by the sustaining cadence; together they produce the rhythm strong programs use. + +--- + +## The cross-cutting pattern + +Most distribution failures share a single root: treating distribution as posting-after-publishing rather than as the equal half of the work. + +Posting-after-publishing thinking treats publication as the end of the work. The piece goes live; minimal distribution work follows; reach is whatever happens organically. Output: most pieces reach a fraction of their potential audience. + +Distribution-as-half-the-work thinking treats distribution as a discipline equal to production. Channel choices are deliberate; cadence is calibrated; owned-earned-paid mix is strategic; measurement informs decisions. Output: pieces reach engaged audiences because the distribution work earned the reach. + +The fix for almost any distribution failure is the same: treat distribution as a real discipline, not as posting. Allocate capacity proportionate to its importance. The capacity required is significant; the value extracted is also significant. + +--- + +## Methodology-level choices that stay in the public skill + +The sixteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the distribution-as-half-the-work framing. + +## Implementation choices that stay internal + +Specific tooling for distribution tracking. Specific reporting templates for distribution outcomes. Specific reviewer training on per-channel conventions. Specific automation that flags distribution gaps. The team's own conventions for failure-pattern detection in their distribution program. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md b/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md new file mode 100644 index 0000000..6fcbf13 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md @@ -0,0 +1,181 @@ +# Content-channel matching + +Format-channel fit decisions. The compose-with-repurposing pattern. The format-mismatch failure mode that produces low engagement even when audience and channel match. + +Audience-channel matching answers "where is the audience?" Content-channel matching answers "does this format fit this channel?" Both must hold for distribution to produce engagement. + +--- + +## Format-channel fit examples + +How specific formats land on specific channels. + +### Long-form analytical text + +**Strong fit.** Newsletter (long-form-tolerant subscribers expect depth). Owned blog (long-form is the blog's native register). LinkedIn long posts (the platform rewards substantive long content). X threads (when the community fits and the thread is well-paced). + +**Weak fit.** Instagram (the format does not support text-driven content as primary). TikTok (audiences come for short-form video, not long text). Most podcast platforms (audio is the format; long-form text is not what audiences came for). + +### Short-form video + +**Strong fit.** TikTok, Reels, YouTube Shorts (the platforms' native formats). Increasingly LinkedIn video (the platform has invested in video). Twitter/X video for some communities. + +**Weak fit.** Newsletter (where text leads and video is a supplement). Owned blog (where written long-form leads). Most podcast platforms (audio-only consumption). + +### Statistic-driven content + +**Strong fit.** Social with quote-graphic visual treatment (LinkedIn, X, Instagram with the right design). AI search snippets (search engines weight statistics with named sources). Podcast mentions (host-read statistic + source citation works well). + +**Weak fit.** As primary format on owned blog (where context develops the stat; the stat alone is thin). Newsletter as the entire content (the stat without development underdelivers). + +### Conversational expert content + +**Strong fit.** Podcasts (the format is conversational by design). Video interviews (long-form video supports the conversational depth). Long social threads on platforms where substantive content is rewarded. + +**Weak fit.** Short-form video (the conversational depth does not fit 60-second windows). Newsletter (where edited prose fits better than conversational transcript). + +### Reference content (definitions, glossaries, FAQs) + +**Strong fit.** Owned blog and FAQ pages (canonical home). AI search snippets (citation-ready). Documentation sites (where reference is the format). + +**Weak fit.** Most social channels (reference content does not earn engagement on attention-driven feeds). Podcasts (reference content does not work in audio). + +### Visual narrative content (case studies with custom visuals, illustrated guides) + +**Strong fit.** Instagram (visual-first). Pinterest (visual reference). Owned blog with strong design treatment. + +**Weak fit.** Podcast (audio cannot carry visual content). Newsletter (most newsletters do not support rich visual treatment). + +--- + +## The compose-with-repurposing pattern + +When the audience is on a channel but the source format does not fit, the right answer is often to repurpose into a format that does fit. + +**The pattern.** + +- Source piece: 5,000-word whitepaper. +- Audience: present and engaged on TikTok (consumer-oriented program; younger demographic). +- Direct distribution: 5,000-word whitepaper does not fit TikTok. +- Compose-with-repurposing: produce 60-second video derivatives from the whitepaper's key claims, framed for TikTok conventions. Distribute the derivatives on TikTok; keep the whitepaper as the source for audiences who want depth. + +**The discipline.** Distribution is downstream of repurposing. A program with strong audience-channel matching but weak content-channel matching solves it through repurposing, not through distributing inappropriate formats. + +**See `content-repurposing`** for the cross-format adaptation discipline. The two skills compose: repurpose first to fit the channel; then distribute on the channel. + +--- + +## The format-mismatch failure mode + +The pattern when content-channel matching is skipped. + +**The symptom.** The program is present on the right channels (audience-channel matching held). Engagement is still low. The team is confused because the channels seem right but the content is not landing. + +**The diagnosis.** The format does not fit the channel even though the audience is there. The audience is on the channel for a different kind of content; the program's content does not match the channel's content expectations. + +**The cure.** Identify the format-channel mismatches. For channels with strong audience-channel match but weak content-channel match, repurpose to fit. For channels where neither matching holds, cut the channel. + +**Recovery time.** Format-mismatch fixes through repurposing typically produce visible engagement improvements within 4-12 weeks as the new format derivatives accumulate. + +--- + +## Format conventions per channel + +Beyond the strong/weak fit, each channel has specific conventions that distinguish good fit from forced fit. + +### LinkedIn long-form posts + +- 800-2,500 character body. +- First 1-3 lines must hook (truncation point). +- Short paragraphs, white space, occasional emphasis. +- Specific argument or position; vague observations underperform. +- Engagement-earning closes (questions, polarizing claims, specific examples). + +### X/Twitter threads + +- 5-15 posts typical for substantive threads. +- First post must hook; the thread is read sequentially. +- Each post is a complete thought, not a 280-character split of a longer thought. +- Conclusion specific. + +### Newsletter (substantive content) + +- 200-800 words for typical sends; 1,500-3,000 for engaged-audience long-form newsletters. +- Subject line and preheader bear most engagement load. +- Plain prose paragraphs render reliably. +- Single clear CTA per send. + +### Podcast + +- Spoken-language sentence structure. +- Conversational pacing with examples and asides. +- Show notes with links and structured summary. +- Consistent episode length; audiences develop expectations. + +### Owned blog + +- Format depends on the source-piece type; long-form articles, listicles, definitive guides, case studies, etc. +- SEO conventions: target keyword in title and headings, internal linking, schema markup. +- Visual rhythm appropriate to length. + +### TikTok / Reels / Shorts + +- 60-90 seconds typical. +- Hook in first 1-2 seconds. +- Captions essential. +- Single specific point. +- Visual variation, motion, or text-on-screen design. + +### Instagram (feed posts) + +- Visual-first; images carry the post's immediate impact. +- Caption supplements; not all viewers expand caption. +- Conventions vary by subgenre (educational carousels, product photography, lifestyle imagery). + +### YouTube (long-form) + +- 8-30 minutes typical for substantive content. +- Pacing for spoken delivery. +- Visual variation. +- Audio quality matters more than video quality. +- Thumbnail and title bear most click-through load. + +### AI-search snippets + +- 40-80 words for FAQ-style; 100-200 words for paragraph-style. +- Standalone meaning. +- Named-source citations. +- Specific framings. +- Schema markup where applicable. + +--- + +## Format adaptation per channel within a single source + +A worked example: a research report that distributes across multiple channels. + +**Source.** 8,000-word research report on B2B paid media benchmarks. + +**Distribution by channel with content adaptation.** + +- **Owned blog.** Full report as the canonical version. Schema-marked. Internal-linked from related pieces. Sections support deep linking. +- **Newsletter (substantive subscribers).** A 1,200-word digest sending the report's key findings, with a clear CTA to read the full report. +- **LinkedIn long posts.** 4-6 long-form posts, each developing one finding from the report. Each post includes the report's most relevant statistic with named-source attribution. +- **X threads.** 2-3 threads from the report, each focused on a specific finding. Threads link to the report. +- **Podcast.** One episode interviewing a practitioner who has applied the report's findings, with the report as the show's spine. +- **TikTok / Reels.** Statistic-driven 60-second videos, one per key statistic. Custom graphic treatment for each. +- **AI-search snippets.** 15-20 FAQ extractions from the report. Schema-marked FAQ page on the owned property. +- **Promoted newsletter.** Sponsored placement in 1-2 industry newsletters whose audience overlaps with the report's target. +- **Boosted social.** Boost the LinkedIn posts that earn the highest organic engagement. + +The example shows the compose-with-repurposing pattern in practice. The source is one piece; the distribution adapts per channel. The cross-format set composes with the channel choices to produce engagement appropriate to each channel's conventions. + +--- + +## Methodology-level choices that stay in the public skill + +The format-channel fit examples, the compose-with-repurposing pattern, the format-mismatch failure mode, the format conventions per channel, the worked example of multi-channel distribution from one source. + +## Implementation choices that stay internal + +Specific platform tooling for format-specific publishing. Specific design templates per channel-format combination. Specific automation for cross-channel scheduling. The team's own conventions for format-fit decisions when ambiguous. These vary by team, tooling, and brand voice. diff --git a/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md b/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md new file mode 100644 index 0000000..cc20c8b --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md @@ -0,0 +1,183 @@ +# Distribution cadence patterns + +Frequency, mix, rhythm. Sustaining vs campaign rhythm. Common cadence patterns by program type. The audit that catches cadence mismatches. + +Cadence is the rhythm of a program's distribution: how often each channel publishes, what mix of owned-earned-paid, and how steady-state baseline relates to campaign spikes. The wrong cadence produces predictable engagement decline: too aggressive exhausts audiences; too sparse loses connection; mismatched to channel attention rhythm produces underperformance at any frequency. + +--- + +## Cadence axes + +Three axes that together define a program's distribution cadence. + +**Frequency per channel.** How often the program publishes to each channel. Newsletter weekly vs bi-weekly. LinkedIn 3 posts per week vs 1 per week. X 5-10 posts per week vs occasional. The frequency per channel is calibrated to the channel's audience attention rhythm. + +**Mix.** What proportion of distribution is owned vs earned vs paid. What proportion of pieces are original vs derivative. The mix reflects program strategy: owned-heavy programs invest in long-term audience-building; paid-heavy programs prioritize immediate reach. + +**Rhythm.** Sustaining baseline cadence vs campaign spikes. Most programs have a steady-state rhythm punctuated by occasional campaign moments around flagship launches. The rhythm shape determines how audiences experience the program. + +--- + +## Common cadence patterns by program type + +Cadences that show up repeatedly across program shapes. + +### B2B program with content-led demand generation + +**Newsletter.** Weekly. Substantive sends; subscribers expect depth. + +**Blog.** 2-4 posts per week. Mix of new pieces, refresh updates, and cross-format derivatives. + +**LinkedIn.** 3-5 posts per week. Mix of long-form posts, link drops to blog content, occasional video. + +**X/Twitter.** 5-10 posts per week. Higher cadence than LinkedIn; mix of original observations, links, and replies. + +**Podcast.** Bi-weekly or weekly episodes. + +**Earned channels.** Pitches and PR work continuous; coverage when earned. + +**Paid amplification.** Boost of best-performing organic pieces; occasional sponsored newsletter sends. + +**Campaign rhythm.** Quarterly spikes around flagship launches: cross-format wave for 4-6 weeks per launch. + +### Consumer brand with broad-audience reach goals + +**Newsletter.** Weekly or 2x weekly depending on subscriber engagement. + +**Blog or content site.** 1-2 posts per week. + +**Instagram.** Daily content (often a mix of feed posts, stories, and reels). + +**TikTok.** 2-4 posts per week. + +**YouTube.** Weekly long-form video plus shorts. + +**Earned channels.** PR for major moments; influencer relationships continuous. + +**Paid amplification.** Continuous; brands often run paid amplification on most major content as part of standard practice. + +**Campaign rhythm.** Heavier campaign spikes around product launches, seasonal moments, and brand events. + +### Niche specialist program with concentrated audience + +**Newsletter.** Weekly or bi-weekly. Substantive sends; the audience is concentrated and engaged. + +**Blog.** 1-2 posts per month. Quality-focused; depth over volume. + +**Specific platforms (one or two).** 2-3 posts per week on the platforms where the niche audience engages. + +**Podcast (if applicable).** Bi-weekly or monthly episodes. + +**Earned channels.** High prioritization; relationships with niche publications and influencers compound. + +**Paid amplification.** Selective; most niche programs benefit more from earned-channel investment than from paid amplification. + +**Campaign rhythm.** Less pronounced than broader programs; sustaining cadence is the dominant rhythm. + +### Founder-led brand with personal-brand element + +**Newsletter.** Weekly; founder-voice register; personal insight alongside program content. + +**LinkedIn.** Daily posts (or near-daily). Founder voice; personal observations alongside program content. + +**X/Twitter.** Daily posts with conversation engagement. + +**Podcast.** Often the founder hosts; weekly episodes. + +**Earned channels.** Founder builds relationships personally; PR coverage often person-driven. + +**Paid amplification.** Selective; the program builds on organic reach earned by founder authority. + +**Campaign rhythm.** Less formal campaigns; the program reads more as continuous founder voice than as discrete campaign moments. + +--- + +## Sustaining vs campaign rhythm + +The relationship between baseline cadence and campaign spikes. + +**Sustaining cadence.** The baseline rhythm. Audiences expect this cadence; deviations affect engagement. Sustaining cadence builds audience habit (subscribers who expect a Tuesday send keep paying attention; subscribers who get inconsistent sends start ignoring even the good ones). + +**Campaign rhythm.** Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +**The relationship.** Campaign rhythm is earned by sustaining cadence. Programs without sustaining cadence cannot run effective campaigns; the audiences are not warm. Campaigns that spike out of nowhere produce limited engagement because no audience habit primes the moment. + +**The balance.** Strong programs run mostly sustaining cadence with occasional campaign spikes. The campaign spikes are 4-6 weeks total, 4-12 times per year. Programs running continuous "campaign" rhythm exhaust audiences; programs running only sustaining without campaigns miss the moments where flagship work could earn outsized attention. + +--- + +## Per-channel cadence tuning + +Each channel rewards different cadences. Cadence tuning matches channel-specific norms. + +**Newsletter.** Weekly is the most common B2B cadence. Bi-weekly works for higher-investment formats. Daily works for highly-engaged subscriber bases. The cadence should be predictable: subscribers should know roughly when to expect sends. + +**LinkedIn.** Algorithmic favor rewards 1-2 posts per day for individual accounts; company pages typically post less frequently (2-5 posts per week). Lower cadences (1-2 per week) work but limit reach. + +**X/Twitter.** The platform rewards higher cadence than other platforms. 5-15 posts per day is normal for engaged accounts; less can work but limits reach. + +**Instagram.** 1 post per day is common for engaged consumer accounts; 3-5 per week works for B2B and niche programs. Stories and reels often have higher cadence than feed posts. + +**TikTok.** Algorithmic recommendation rewards higher cadence; 1+ posts per day typical for accounts trying to grow. + +**YouTube.** Weekly long-form video is the upper-frequency norm; many channels publish less frequently. Shorts can publish more often (multiple per week). + +**Podcast.** Weekly is the most common cadence; bi-weekly works for higher-investment shows; daily works for high-volume formats (news-style podcasts). + +**Owned blog.** SEO programs benefit from regular publishing (2-4 posts per week typical for active programs); less frequent publishing limits the program's compounding traffic potential. + +--- + +## The cadence audit + +A short framework for auditing a program's cadence. + +1. **Pull current cadence per channel over the last 90 days.** What is the program actually doing? Often differs from the program's stated cadence target. +2. **Compare to channel-specific norms.** Are channel cadences within the engagement-rewarding range, or are they too sparse or too aggressive? +3. **Identify cadence inconsistencies.** Are there gaps where the program goes silent for weeks, then spikes? Inconsistency damages audience habit even when total volume is similar. +4. **Match cadence to capacity.** Is the program able to sustain the current cadences, or is it running unsustainably? +5. **Identify the campaign rhythm.** When were the last 3 flagship launches? Did sustaining cadence support them? Did campaigns earn outsized attention? + +The audit produces a calibration plan: which cadences to maintain, which to adjust, where the program is over-investing or under-investing. + +--- + +## Cadence anti-patterns + +**Inconsistent cadence.** 3 posts in one week, then nothing for 3 weeks. Audiences cannot develop habit; the program disappears between bursts. + +**Volume-driven cadence.** "We need to post X times per week" without reference to channel norms or audience attention. Volume without engagement is presence; presence without engagement is wasted capacity. + +**Identical cadence across channels.** Treating LinkedIn, X, TikTok, and newsletter all on the same cadence ignores channel-specific norms. Each channel has a different attention rhythm. + +**No campaign rhythm.** Pure sustaining cadence with no spikes. Flagship launches receive routine treatment; the moments where the program could earn outsized attention pass without the campaign coordination they warrant. + +**Continuous campaign rhythm.** Pure campaign rhythm with no sustaining baseline. Audiences never develop habit; every "launch" feels like another launch in a continuous stream of launches. + +**Cadence beyond capacity.** The team commits to LinkedIn daily, X 10x per day, newsletter twice weekly. Capacity cannot sustain; cadence drifts; audiences notice the drift. + +--- + +## When to adjust cadence + +Signals that cadence needs change. + +**Engagement declining steadily on a channel.** May indicate cadence too aggressive (audience fatigue) or too sparse (audience disengagement) or content-fit issues (different problem). Investigate. + +**Subscriber unsubscribes spiking on newsletter.** Cadence too aggressive, or content quality declining, or both. Cure depends on diagnosis. + +**Algorithm changes on a platform.** Some platform algorithm shifts reward different cadences. Adjust based on observed engagement signals. + +**Capacity changes.** Team grows or shrinks; cadence should match sustainable capacity. Programs with shrinking teams that maintain prior cadence often produce drift in quality. + +**Audience-research findings.** New data about audience attention rhythms. Adjust cadence to fit revealed audience patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The cadence axes, common cadence patterns by program type, sustaining-vs-campaign rhythm, per-channel cadence tuning, the cadence audit, the cadence anti-patterns, the signals for cadence adjustment. + +## Implementation choices that stay internal + +Specific scheduling tools the team uses. Specific cadence-tracking dashboards. Specific cadence-by-channel calendars. The team's own conventions for cadence-vs-quality tradeoffs when capacity is constrained. These vary by team, tooling, and program shape. diff --git a/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md b/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md new file mode 100644 index 0000000..c1d73f9 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md @@ -0,0 +1,203 @@ +# Distribution measurement + +Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. The discipline that prevents distribution-theater and turns distribution into a learning system. + +Distribution without measurement runs on assumption. Channels stay in the mix because they have always been in the mix; cadence stays at current levels because nobody has asked whether it is right; paid spend continues because budget exists. Measurement is the discipline that surfaces what is actually working and what is not. + +--- + +## Per-channel metrics + +Metrics organized by what they reveal about a channel's effectiveness. + +**Reach metrics.** + +- Impressions: how many times the content was shown. +- Unique reach: how many unique people saw the content. +- Audience growth: how the channel's owned audience size is changing. + +**Engagement metrics.** + +- Click-through rate (CTR): clicks divided by impressions. +- Time-on-page: how long visitors stay on the linked content. +- Scroll depth: how far down the content visitors scroll. +- Completion rate: for video and audio, what percentage finishes. +- Comment, share, and reaction signals on social. +- Reply rate on email. + +**Conversion metrics.** + +- Newsletter signups attributed to the channel. +- Content downloads attributed to the channel. +- Qualified-lead actions (form submissions, demo requests, free-trial starts). +- Sales-cycle progression for B2B programs. +- Attributed revenue for revenue-tracked programs. + +**Channel-health metrics.** + +- Audience retention rate (subscribers staying vs unsubscribing). +- Engagement-rate trend over time (rising, stable, falling). +- Algorithm-favor signals (for platform-controlled channels). +- Deliverability rate (for email). + +--- + +## Channel-level analysis + +Aggregating metrics into channel effectiveness assessments. + +**Engagement-per-distribution-effort.** + +- Some channels look impressive (high reach numbers) but produce low engagement. +- Some channels produce moderate reach but very high engagement. +- The channels that compound value are usually the engagement-heavy ones, not the reach-heavy ones. + +**Conversion-per-channel.** + +- Reach without conversion is vanity. Conversion is value. +- Channels driving conversion at favorable cost (whether owned-channel investment cost or paid-channel spend) earn their place in the mix. +- Channels driving impressive reach but no conversion may be building brand awareness (which is real value) or producing nothing of value (which is wasted capacity). + +**Trend over time.** + +- Channels' performance changes. Algorithm shifts, audience migrations, competitive landscape changes affect channel effectiveness. +- A channel that was effective 18 months ago may be underperforming now. +- A channel that was marginal 18 months ago may be the program's strongest now. +- Quarterly review of channel-level trends catches these shifts. + +**The relative-effectiveness audit.** + +Rank channels by engagement-per-effort and by conversion-per-effort. Channels at the top of both rankings are the program's strongest; channels at the bottom of both are candidates for cutting or restructuring. + +--- + +## Cross-channel attribution + +The audience member encounters the program on multiple channels before converting. Attribution should reflect this reality. + +**Single-touch attribution failures.** + +- **Last-touch attribution.** Credits the last channel before conversion. Misrepresents which channels actually drove the audience relationship; usually overweights the conversion channel (often newsletter or direct site visit) and underweights the discovery channels. +- **First-touch attribution.** Credits the first channel of contact. Misrepresents the role of nurturing channels; usually overweights discovery channels and underweights nurturing channels. + +**Multi-touch attribution patterns.** + +- **Linear attribution.** Equal weight to all touchpoints. Simple; usually a step up from single-touch. +- **Time-decay attribution.** More weight to touchpoints closer to conversion. Reflects the commonsense intuition that recent touches matter more than distant ones. +- **Position-based attribution.** Significant weight to first and last touch; remaining weight distributed across middle touches. Reflects the importance of discovery and conversion moments. +- **Data-driven attribution.** Algorithmic weighting based on observed conversion patterns. Most accurate; requires sufficient data and tooling. + +**The attribution honesty discipline.** + +- Attribution models are simplifications. None is "correct"; all are useful approximations. +- Programs should pick an attribution model and stay consistent. Switching attribution models produces apparent performance changes that are not real. +- Cross-reference attribution data with other signals (subscriber surveys, sales conversation reports). Triangulation is more honest than relying on attribution data alone. + +--- + +## The measurement-honest program + +Discipline that turns measurement into a decision-making input rather than into reporting theater. + +**Cuts channels that consistently underperform.** + +- A channel underperforming for 2-3 quarters is a real signal, not noise. +- Cutting underperforming channels reallocates capacity to channels that produce. +- The decision is hard because cutting feels like admitting failure; programs that cut decisively outperform programs that maintain everything indefinitely. + +**Increases investment in channels that consistently produce.** + +- Strong channels deserve disproportionate investment. +- Programs often spread investment evenly across channels regardless of performance; the measurement-honest discipline allocates investment to where return is highest. + +**Adjusts cadence based on engagement patterns.** + +- Cadence that is too aggressive shows up in declining engagement and rising unsubscribes. +- Cadence that is too sparse shows up in audience-habit decay. +- Engagement patterns inform cadence adjustments. + +**Calibrates paid spend based on organic validation.** + +- Boost what organic validates. +- Reduce or eliminate paid spend on content that does not earn organic engagement. +- Paid spend should be a function of organic signal, not a function of available budget. + +--- + +## The measurement-theater anti-pattern + +When measurement is performed without informing decisions. + +**The pattern.** The team produces quarterly reports with channel-level metrics. Reports are presented to leadership. Decisions are not changed based on the reports. Underperforming channels stay in the mix; over-performing channels do not get additional investment. The program continues as it would have continued without the measurement. + +**Why it happens.** + +- Measurement is treated as performance theater rather than as decision input. +- Leadership signals that all channels should continue (political pressure, sunk cost, brand reasons). +- The team has measurement capacity but lacks decision-authority over distribution. + +**The cure.** Tie measurement to specific decisions. Each quarter, the measurement review produces a list of changes: cuts, additions, cadence adjustments, capacity reallocations. Reviews without decisions are theater. + +--- + +## Common measurement failures + +**No measurement.** Distribution runs on assumption. Channels stay in the mix because they always have. Cadence and capacity allocation persist regardless of effectiveness. + +**Measurement without action.** Measurement is performed; decisions are not changed. The program runs as if no measurement happened. + +**Vanity metrics.** Reach and impressions reported as primary success metrics. Engagement and conversion underreported. The program looks like it is working when it may not be. + +**Single-touch attribution dominance.** All attribution analysis runs on last-touch or first-touch. The realities of multi-touch journeys are missed. + +**No trend analysis.** Channel performance reported in quarterly snapshots; trends across quarters are not surfaced. Channel decay is detected late. + +**Cross-program comparison failures.** The program compares itself to industry benchmarks without context. Benchmark numbers from other industries or audience segments may not apply; comparison produces false signals. + +--- + +## Measurement infrastructure + +The tooling and processes that support measurement. + +**Analytics platform.** Web analytics that tracks per-channel traffic, engagement, and conversion. Standard requirement for any program with a content site. + +**Email analytics.** Open rates, click-through rates, unsubscribe rates, deliverability rates. Standard for any program with a newsletter. + +**Social analytics.** Per-platform analytics from each social platform; supplemented by social-listening tools where the program tracks mentions and shares beyond direct posts. + +**Attribution tooling.** From simple UTM tracking and Google Analytics multi-touch reports to sophisticated attribution platforms (depending on program scale and complexity). + +**Channel-specific dashboards.** Programs often build per-channel dashboards that surface the metrics most relevant to that channel's optimization. + +**Cross-channel rollup.** A program-level dashboard that aggregates channel-level data into a coherent view of distribution effectiveness. + +The infrastructure cost is real; the alternative (running distribution without measurement) is more expensive over time because capacity gets allocated to wrong places. + +--- + +## Measurement cadence + +When to measure what. + +**Continuous.** Some metrics update daily or weekly: website traffic, social engagement, email opens. The team monitors these continuously. + +**Weekly.** Per-channel summaries of recent performance. Catches sharp decay or sharp improvements early. + +**Monthly.** Channel-level rollup. Detects trends developing across multiple weeks. + +**Quarterly.** Strategic measurement review. Decisions about channel cuts, additions, cadence adjustments, capacity reallocations. + +**Annual.** Program-level measurement review. Strategic shifts in channel mix, attribution-model adjustments, capacity reallocations across the program. + +The cadence should match the decision cadence. Programs with monthly capacity-allocation decisions need monthly measurement; programs with quarterly decisions need quarterly measurement. + +--- + +## Methodology-level choices that stay in the public skill + +The per-channel metric categories, channel-level analysis approaches, cross-channel attribution patterns, the measurement-honest discipline, the measurement-theater anti-pattern, common measurement failures, infrastructure requirements, measurement cadence. + +## Implementation choices that stay internal + +Specific analytics platforms (the team's chosen GA configuration, alternative platforms, attribution tools). Specific dashboard designs and reporting templates. Specific UTM tagging conventions. Specific attribution-model parameters tuned for the program. The team's own conventions for benchmark comparisons. These vary by team, tooling, and program scale. diff --git a/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md b/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md new file mode 100644 index 0000000..690d86b --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md @@ -0,0 +1,172 @@ +# Earned-channel work + +PR, syndication, mentions, AI-search citation, word of mouth. The relationship investment that compounds over years. The pitching discipline that earns coverage rather than burning relationships. + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real: relationships built over years, pitches that demonstrate the program's value, content that earns citation. Programs treating earned channels as automatic produce nothing; programs investing in the relationships earn ongoing channel access. + +--- + +## PR and press + +Journalists, podcasters, newsletter operators who cover the program's content. + +**The relationship-first principle.** Coverage follows relationships. Cold pitches from unknown senders get ignored at high rates; warm pitches from known senders get read. Programs that build relationships before they need coverage are the programs that earn coverage when they have flagship work to share. + +**Building relationships.** + +- Read the journalists, podcasters, and operators in the program's space. Know what they cover, what their angles are, what they have written or aired recently. +- Engage substantively before pitching. Comment thoughtfully on their work; share their pieces with attribution; respond if they ask for input. +- Build the relationship to a level of mutual recognition before the first pitch. + +**Pitching when the relationship exists.** + +- Pitch specific to the recipient. Reference their recent work; explain why the program's content fits their angle. +- Lead with the angle, not with the company. Recipients care about the story, not about the program's brand. +- Provide everything the recipient needs: the source piece, key statistics, possible quotes, a clear point of contact. +- Make it easy to say yes; make it easy to say no. + +**The mass-blast pitching anti-pattern.** + +- Identical pitches sent to dozens of recipients. Recipients detect mass-blast quickly; relationships are damaged not built. +- Pitches focused on the program rather than on the story. Recipients filter these as ads. +- Follow-up pressure. Excessive follow-ups damage future relationship potential. + +**The PR investment timeline.** Real PR relationships build over 1-3 years. Programs without prior PR investment cannot generate coverage on a deadline; programs with sustained investment have relationships that produce ongoing coverage. + +--- + +## Syndication + +Other publications republishing or excerpting the program's content with appropriate attribution. + +**The syndication exchange.** The program provides quality content; the partner provides reach into their audience. Both parties win when the exchange is fair. + +**Negotiation patterns.** + +- **Republishing with canonical link.** The partner runs the full piece; canonical link tag points to the program's version for SEO. Reach extends; SEO authority preserves. +- **Excerpt with link.** The partner runs an excerpt with a link to the full piece on the program's site. Less full reach but stronger funnel back to the program. +- **Republishing without canonical.** Less common; risks SEO duplication issues; should be avoided unless specifically negotiated with the partner about which version is canonical. + +**Common syndication failures.** + +- Canonical link mishandling. The piece appears on the partner's site as the canonical version; the program's version drops in rankings. +- Partner relationships not maintained. Syndication partners that stop running the program's content; the channel goes silent. +- Indiscriminate syndication. Every piece syndicated regardless of fit; partner audiences see content that does not match their interests; partner removes the program from rotation. + +**The selective-syndication discipline.** Not every piece warrants syndication. Match piece-to-partner: which pieces fit which partners; which partners' audiences will engage with which pieces. Selective syndication produces stronger partner relationships than blanket syndication. + +--- + +## Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +**Citation as compounding authority.** Each citation increases the program's authority signal. Citations from authoritative sources weight more than citations from less authoritative ones. Citation accumulation over years is one of the most durable signals of program quality. + +**Earning citations.** + +- Produce content with citation hooks. Original data; named frameworks; primary research; contrarian-but-defensible positions. +- Build identifiable phrasings or term coinages. If the program names a concept, others citing the concept cite the program. +- Make content discoverable when others are researching the topic. SEO and AI-search visibility matter for citation discoverability. + +**The generic-content-no-citation problem.** Pieces that do not have specific citation hooks rarely get cited even if they are well-written. The hook is what other writers reach for. + +**AI-search citation specifically.** AI engines cite content that matches their retrieval criteria. See `content-repurposing`'s AEO extraction patterns for the discipline of producing AI-citation-friendly content. Programs that design for AI citation earn more citations than programs that publish without that consideration. + +--- + +## Word of mouth and shares + +Audiences sharing pieces with their networks. + +**The hardest channel to engineer.** Word of mouth follows from genuine usefulness. Pieces that audiences want to share are pieces that are genuinely valuable; pieces that are generic do not get shared even if they are read. + +**Patterns that earn shares.** + +- Specific, useful content. Audiences share pieces that help them or that they think will help others. +- Citation-worthy content. Audiences share pieces they want to point to as references. +- Provocative-but-defensible content. Audiences share pieces that take a position they want to amplify. +- Memorable framings. Audiences share pieces that introduce concepts or framings they find useful. + +**Patterns that do not earn shares.** + +- Generic content. Pieces that say what every other piece on the topic says do not earn the share. +- Surface-level coverage. Pieces that scratch the surface without substantive depth do not feel worth sharing. +- Defensive content. Pieces that hedge every position do not earn the share because they do not say anything specific. + +**The measurement challenge.** Word-of-mouth sharing often happens in private channels (DMs, internal Slack, work emails) where the program cannot directly measure. Indirect signals: referral traffic from unknown sources, audience members reporting "a colleague sent me this," conversion-without-tracked-attribution. + +--- + +## Earned-channel investment + +The capacity allocation question. + +**Programs without earned-channel investment.** Treat earned channels as automatic. Coverage that happens, happens; coverage that does not happen, does not. Output: limited earned reach; the program is dependent on owned and paid distribution. + +**Programs with strategic earned-channel investment.** Allocate specific capacity to relationship-building, pitching, syndication negotiation, citation tracking. Output: earned channels become reliable distribution over years. + +**The investment shape.** + +- **PR work.** A specific person owns relationships and pitching. Investment level varies by program: from 5% of one person's time at smaller programs to dedicated PR roles at larger programs. +- **Syndication negotiation.** Periodic outreach to potential partners; relationship maintenance; canonical-link verification. +- **Citation tracking.** Monitoring where the program is being cited; engaging with those citations (thanking citers; building relationships with frequent citers). +- **AI-search citation.** Tracking AI engine citation rates; iterating on AEO extraction patterns based on what gets cited. + +**The investment payoff timeline.** Earned-channel investment compounds over 2-5 years. Year 1 produces limited returns; years 3-5 produce significant returns if the investment was sustained. + +--- + +## Common earned-channel failures + +**Mass-blast pitching.** Pitches sent to dozens of recipients identical or near-identical. Recipients detect; relationships damaged; future coverage potential reduced. + +**No relationship investment.** The program tries to "do PR" only when it has flagship work to share. Without prior relationship investment, pitches go cold even when the content is genuinely strong. + +**Syndication mishandled.** Canonical-link issues; partner relationships not maintained; SEO authority drained to partner sites. + +**No citation hooks.** Pieces produced without elements that earn citation. Mentions and AI-search citation rates stay low because nothing in the content prompts citation. + +**Earned channel as automatic.** Treating earned channels as if they happen on their own. Without investment, they do not. + +**Limited PR scope.** Pitching only the same 3-5 trade publications repeatedly. The relationship gets over-extended; coverage drops; broader earned-channel work is not happening. + +--- + +## Earned-channel measurement + +Earned channels are harder to measure than owned or paid, but measurement is still possible. + +**PR coverage.** + +- Volume: how many pieces of coverage per quarter. +- Quality: which publications, which authors, what reach those publications have. +- Sentiment: positive coverage, neutral, critical. +- Attribution: traffic and conversions sourced from coverage moments. + +**Syndication.** + +- Reach via partner: traffic and engagement on partner-published versions. +- Funnel back: traffic from partner content to program's own site. +- Authority preservation: SEO position holding given canonical link signaling. + +**Mentions and citations.** + +- Citation count over time. Tools that track mentions across the web help here. +- Citing-source quality. Citations from high-authority sources weight more. +- AI-search citation rates. Tools that track AI engine citations are emerging; the measurement infrastructure is improving. + +**Word of mouth.** + +- Indirect signals: referral traffic from unknown sources, audience reports, sustained organic growth without proportional paid amplification. +- Survey data: when audience members are asked how they discovered the program, word-of-mouth signals appear. + +--- + +## Methodology-level choices that stay in the public skill + +The relationship-first PR principle, the syndication exchange and selective-syndication discipline, the citation-earning patterns, the word-of-mouth observations, the earned-channel investment shape and timeline, the common failures, the measurement approaches. + +## Implementation choices that stay internal + +Specific PR-relationship CRM tooling. Specific pitching templates and tracking. Specific syndication negotiation conventions. Specific citation tracking software. Specific AI-search citation tracking infrastructure. The team's own conventions for relationship-investment cadence. These vary by team, budget, and program scope. diff --git a/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md b/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md new file mode 100644 index 0000000..3b3adbb --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md @@ -0,0 +1,156 @@ +# Owned-channel discipline + +Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. The patterns that turn owned channels from posting infrastructure into durable distribution foundations. + +Owned channels are the most reliable distribution a program has. The newsletter delivers to every subscriber's inbox; the blog persists indefinitely; the owned social accounts run on the program's terms (within platform constraints). Programs that under-invest in owned channels become dependent on third-party distribution; when platforms change, when paid costs rise, when earned channels go quiet, the dependent program's reach collapses. + +--- + +## Newsletter discipline + +The most direct owned distribution. + +**The discipline shape.** + +- **Cadence consistency.** Subscribers develop expectations. Weekly send on Tuesdays gets opened more reliably than weekly send that drifts to Thursday or Wednesday or Friday. +- **Content quality matching subscriber expectations.** What subscribers signed up for; the program delivers it. Drift in quality (or in topic) produces unsubscribes. +- **Single CTA per send.** Multi-CTA emails dilute. Subscribers process one action; competing actions reduce all of them. +- **Deliverability hygiene.** Spam-trigger words, unbalanced text-to-image ratios, technical configuration (SPF, DKIM, DMARC) all affect deliverability. Programs that ignore deliverability watch open rates decline. +- **List health.** Engaged subscribers vs lapsed subscribers; pruning lapsed segments improves overall deliverability and engagement metrics. + +**Common newsletter failures.** + +- Cadence drift. The "weekly" newsletter that becomes bi-weekly, then monthly, then sporadic. Subscribers stop expecting; engagement decays. +- Subject lines that announce instead of earning the open. "Newsletter for week of November 14" performs worse than specific subject lines tied to the email's content. +- Multi-topic emails that try to cover everything the program produced this week. Single-topic focus produces stronger engagement. +- No segmentation. The same email goes to every subscriber regardless of interest patterns. Programs with multiple distinct content streams benefit from segmented sends. + +**See `email-sequences`** for the email-specific discipline including subject-line patterns, sequence design, and lifecycle campaigns. + +--- + +## Blog discipline + +The owned content home. + +**The discipline shape.** + +- **Architecture and technical SEO foundations.** Crawlability, indexability, page speed, schema markup. Without these, the blog cannot earn search traffic regardless of content quality. +- **Pillar and cluster organization.** Topical hubs that compound authority over years. See `pillar-content-architecture`. +- **Refresh discipline.** Library does not decay into staleness. See `content-refresh-system`. +- **Internal linking.** Strong internal-link graph that distributes authority and earns rankings. +- **On-page optimization.** Per-page SEO discipline. See `seo-onpage`. + +**Common blog failures.** + +- Publishing without distribution to the blog. The blog is the destination; if no traffic flows to it from owned and earned distribution, only the slowly-compounding search traffic builds. +- Architectural neglect. The blog's information architecture rots; URL structures change without redirects; old content drags down newer pages' authority. +- Refresh starvation. The library accumulates stale pieces; new pieces have to compete with the team's own decaying content for rankings. +- No design investment. The blog reads as a content dump rather than as a property; visitors do not return. + +**The blog as compounding asset.** A well-disciplined blog produces traffic for years. Programs that invest in blog foundations early earn compounding returns; programs that under-invest never earn the compounding effect. + +--- + +## Owned social discipline + +LinkedIn company page, X account, YouTube channel, Instagram account, etc. + +**The discipline shape.** + +- **Per-platform conventions.** Each platform rewards different content shapes. LinkedIn rewards substantive long-form posts; X rewards conversation; YouTube rewards specific topic and audio quality; Instagram rewards visuals. +- **Cadence calibrated to platform attention rhythm.** Daily on platforms that reward daily; weekly on platforms that work weekly. Mismatch reduces reach regardless of content quality. +- **Engagement-signal optimization.** Algorithmic recommendation rewards content that earns engagement signals (comments, shares, time-watched, click-through). Content designed for these signals reaches more. +- **Account-health hygiene.** Posting consistency; authentic engagement (not spam-replies); profile completeness; consistent branding. + +**Common owned-social failures.** + +- Cross-posting identical content across platforms. Each platform has different conventions; identical posts perform poorly on all platforms. +- Generic posting templates. Audiences detect template-driven posting; engagement decays. +- No engagement with the audience. Posting without responding to comments or engaging with industry conversations reduces algorithmic favor over time. +- Reliance on a single platform. Platform algorithms shift; programs dependent on one platform's reach are exposed to algorithm risk. + +**Owned vs platform-controlled.** Owned-social channels are owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. The distinction matters for risk: programs treating owned-social as fully owned underestimate platform-algorithm risk. + +--- + +## Podcast discipline + +Owned audio distribution. + +**The discipline shape.** + +- **Audio quality.** Listeners tolerate uneven video far more than uneven audio. Audio investment returns more than video investment up to a point. +- **Consistent episode cadence.** Weekly is most common; bi-weekly works for higher-investment shows. Drift undermines listener habit. +- **Show notes as derivative format.** Show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as their own derivative format with quality discipline. +- **Cross-platform distribution.** Apple Podcasts, Spotify, YouTube, Google Podcasts. Each is a discoverability surface. +- **Format consistency within the show.** Listeners develop expectations; format changes can lose listeners. + +**Common podcast failures.** + +- Production quality drift. The first 10 episodes are well-produced; episodes 30+ show production decay. +- No cross-platform distribution. The show lives on one platform; potential listeners on other platforms cannot find it. +- Show notes treated as afterthought. Thin show notes reduce SEO value and listener navigation. +- Cadence inconsistency. Drift between episodes undermines listener habit. + +**The podcast as relationship channel.** Engaged listeners feel connected to the host(s); the audience relationship is intimate. Podcasts produce trust signal that other channels often cannot match. + +--- + +## Community discipline + +Slack communities, Discord servers, dedicated discussion forums. + +**The discipline shape.** + +- **Active moderation.** Communities require continuous facilitation. Spam, off-topic content, and unaddressed conflict damage community health. +- **Sustained value-delivery.** Members come and stay because the community delivers value. Value can be peer connection, expert access, content access, or product feedback. +- **Integration with the broader content program.** Members get early access; program content is shared in the community; community feedback informs program decisions. +- **Member-driven content.** Strong communities have member-to-member interaction beyond program-to-member broadcasting. + +**Common community failures.** + +- Abandonment. Communities launched with fanfare and then under-staffed. Members leave; the community decays into a ghost town signaling the program's decline. +- Broadcast-only. The program posts to the community as if it were another social channel; no facilitation of member interaction. +- Membership-quality drift. Open communities accumulate members who do not contribute; the signal-to-noise ratio degrades. +- No moderation policy. Conflict, spam, or off-brand content erodes the community's character. + +**Community as audience-relationship multiplier.** The community is often the program's most engaged audience segment. Investment in the community returns at multiple points: feedback, advocacy, product input, content participation. + +--- + +## The starvation anti-pattern + +Programs that under-invest in owned channels become dependent on third-party distribution. + +**The pattern.** The program invests heavily in paid acquisition or in social platforms it does not own. Reach grows on those channels. The program does not build newsletter, blog, or community in proportion. When platforms change algorithms or paid costs rise, reach collapses; the program has no owned channels to fall back on. + +**The visibility.** Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscribes, account creations, community memberships). The reach is rented, not owned. + +**The cure.** Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +**Prevention.** Programs in early stages should over-invest in owned channels relative to the reach those channels initially produce. The investment compounds over years; the alternative is decade-long dependency on third-party distribution. + +--- + +## The owned-channel investment timeline + +Owned channels reward long investment. + +**Year 1.** Newsletter and blog established; cadence consistent; subscriber count and traffic both small. The investment feels like it is producing little; the cadence is the foundation. + +**Year 2-3.** Newsletter list grows; blog accumulates SEO traffic; community starts to form (if part of the strategy). The investment starts to compound; engagement signals improve. + +**Year 4+.** Owned channels are reliable distribution. Newsletter sends produce predictable engagement; blog earns substantial organic traffic; community is a meaningful audience asset. The early investment compounds. + +**The patience cost.** Owned-channel investment is multi-year; the visible returns lag the investment. Programs that abandon owned-channel investment in years 1-2 because returns feel small often regret it in years 3-5 when peers who sustained the investment are reaping the compounding effect. + +--- + +## Methodology-level choices that stay in the public skill + +The owned-channel disciplines (newsletter, blog, social, podcast, community), the common failures per channel type, the starvation anti-pattern, the investment timeline. + +## Implementation choices that stay internal + +Specific newsletter platforms and templates. Specific blog CMS and design systems. Specific social-publishing tools. Specific podcast hosting and editing tools. Specific community-management software (Slack, Discord, custom forums). The team's own conventions for cadence and quality thresholds. These vary by team, budget, and program scope. diff --git a/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md b/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md new file mode 100644 index 0000000..43dbd94 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md @@ -0,0 +1,181 @@ +# Paid promotion patterns + +When boosting organic content earns its keep. The paid-as-substitute anti-pattern. The disciplines that distinguish strategic paid amplification from spending budget on content that did not validate organically. + +Paid promotion of organic content is an amplification layer. The pattern works when paid spend extends the reach of content that organic engagement has already validated; the pattern fails when paid spend substitutes for organic validation or for owned-channel investment. + +--- + +## The boost-organic pattern + +The most common and effective form of paid content amplification. + +**The shape.** A piece publishes organically. Some pieces show strong engagement signals: high CTR, high time-on-page, organic shares, comment engagement. The program boosts those validated pieces with paid spend to extend reach. + +**Why it works.** The content has audience validation. Audiences engage with the boosted content because it is genuinely engaging. The paid spend amplifies what already worked rather than gambling on what might work. + +**Implementation patterns.** + +- **Engagement-threshold boosting.** Pieces that exceed defined engagement thresholds in the first 24-48 hours get boosted. The thresholds (CTR, share rate, comment volume) vary by program. +- **Editorial-judgment boosting.** Editorial reviews recent organic pieces and selects which ones merit boost spend based on broader strategic fit, not just engagement metrics. +- **Hybrid.** Engagement-threshold boost for tactical amplification; editorial-judgment boost for strategic amplification of pieces that align with program goals beyond engagement metrics. + +**Capacity allocation.** Most strong programs allocate 5-20% of distribution capacity to paid amplification of organic content. Higher allocations often signal under-investment in owned channels. + +--- + +## Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +**The shape.** The program pays a third-party newsletter to feature its content. The newsletter's audience sees the program's content alongside the newsletter's editorial content. + +**Why it works.** Newsletter audiences have strong attention rhythms; sponsored content placed in a newsletter the audience reads gets meaningful attention. + +**Implementation patterns.** + +- **Single-send sponsorship.** The program pays for one prominent placement in a single send. Strongest engagement; highest cost per send. +- **Multi-send package.** The program pays for placements across multiple sends. Weaker per-send engagement; lower cost per send. +- **Co-marketing.** The program partners with the newsletter on a co-produced piece; both parties benefit. Often the most effective format when it fits both audiences. + +**Selection criteria.** + +- Audience overlap with target audience. +- Newsletter editorial fit (content tone matches the program's voice). +- Engagement metrics (open rates, click-through rates, sponsor performance history). +- Cost relative to alternative paid options. + +**Common newsletter-sponsorship failures.** + +- Mismatched audience. The newsletter has reach but does not match the program's target audience. +- Mismatched tone. Sponsored content clashes with the newsletter's voice; readers tune out. +- Generic sponsored content. Sponsored placements that read as ads underperform sponsorships that read as editorial fit. + +--- + +## Syndication networks (Outbrain, Taboola, native networks) + +Paid placement on third-party sites via "you may also like" or "recommended for you" units. + +**The shape.** Programs pay per click; content appears on third-party sites in recommendation units. + +**Implementation patterns.** + +- **Bid management.** Per-piece bidding; cost-per-click optimization. +- **Geographic and audience targeting.** Some networks support targeting; others are broader. +- **Brand-safety controls.** Choose where the content appears; some networks have brand-safety concerns about co-placement. + +**Effectiveness.** Variable. Some programs see meaningful traffic with reasonable cost-per-engagement; others see high traffic numbers but low engagement once visitors land on the program's content. The audience quality varies significantly across networks. + +**Common syndication-network failures.** + +- Click optimization without engagement measurement. The program optimizes for cost-per-click; clicks arrive; engagement is low; the audience is the wrong audience. +- Brand-safety incidents. Content appears in unwanted contexts; brand association damaged. +- Treating syndication networks as primary distribution. The networks supplement; they do not substitute for owned and earned channels. + +**The cautious-test discipline.** Test syndication networks at small budget; measure beyond clicks (engagement, time-on-page, conversion); expand only if the audience quality matches expectations. + +--- + +## Search advertising for content + +Paying for clicks on content pieces via search ads. + +**The shape.** Less common than other paid content amplification. Usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +**When it fits.** + +- High-value content with clear conversion or lead-capture goals. +- Pieces targeting queries where organic ranking is hard to achieve. +- Time-sensitive content where waiting for organic ranking is not an option. + +**When it fails.** + +- Routine blog posts boosted via search ads. Cost-per-click usually exceeds the value of the click. +- Content that does not have clear conversion paths. Paid traffic without conversion produces sunk cost. +- Competitive queries where ad costs are high. Programs may be unable to justify cost-per-click in highly contested categories. + +**The selective-discipline.** Reserve search ads for content with clear conversion goals; measure paid traffic against owned-traffic comparison; high-value content only. + +--- + +## Sponsored podcast placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts. + +**The shape.** Programs pay to be featured in third-party podcasts. Often via host-read endorsement; sometimes via produced ads. + +**Why host-read works.** The podcast host's voice carries trust signal; audiences hearing the host endorse content engage at higher rates than they engage with produced ads. Host-read endorsements are often the highest-engagement paid content amplification available. + +**Selection criteria.** + +- Host audience alignment with the program's target. +- Host content alignment with the program's voice. +- Per-episode reach and download numbers (with verification; some self-reported numbers are inflated). +- Cost relative to expected engagement. + +**Common podcast-sponsorship failures.** + +- Mismatched host. The host's audience does not match the program's audience. +- Mismatched content. The host reads the program's pitch awkwardly because the content does not fit the host's editorial voice. +- Production quality issues. Poorly produced sponsored segments damage the host's show; future sponsorship opportunities reduce. + +**The host-collaboration discipline.** Provide the host with substantive talking points, not scripted ad copy. Hosts read better when they have material they can adapt to their voice. The collaboration produces stronger sponsorships than rigid scripts. + +--- + +## The paid-as-substitute anti-pattern + +When paid promotion substitutes for organic validation or for owned-channel investment. + +**The pattern.** The program does not invest in newsletter, blog, community, or earned channels. Paid amplification produces visible reach; the program looks like it is working. Underlying owned-channel growth is minimal; the program is rented reach without owned-audience growth. + +**Why it fails over time.** + +- Paid costs rise. Auction dynamics on paid platforms drive prices up; the program's cost-per-engagement increases. +- Algorithm shifts. Paid platforms change targeting; previously-effective audiences become harder to reach or more expensive. +- Audience saturation. Audiences encountering the program's paid content develop ad-blindness; engagement decays. +- No compounding effect. Each paid impression is paid for separately; nothing compounds the way newsletter or blog growth compounds. + +**The visibility.** Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscriptions, account creations, community memberships). The reach is rented, not owned. + +**The cure.** Reallocate capacity. Reduce paid spend; increase newsletter, blog, and community investment. Recovery is multi-year; programs in paid-substitute state cannot rebuild quickly. + +--- + +## Paid amplification of low-organic-engagement content + +Boosting pieces that did not earn engagement organically. + +**The pattern.** A piece publishes organically. Engagement is low. The team boosts the piece anyway, reasoning that more reach will produce more engagement. + +**Why it fails.** Audiences who did not engage organically rarely engage when shown the same content via paid amplification. The piece's value proposition is not landing; paid amplification compounds the problem. + +**The cure.** Boost organically-validated content; do not substitute paid for organic validation. Pieces that did not engage organically should be evaluated for whether they should be refreshed (see `content-refresh-system`) or whether they were the wrong piece for the audience. + +**Exception cases.** Some content may be specifically targeted at audiences who do not see the organic version (different geographic markets, different audience segments). In those cases, paid amplification to specific audiences may be appropriate even without organic validation in the original audience. The rule is "validate within the addressable audience"; not necessarily "validate organically before any paid spend." + +--- + +## Capacity allocation for paid promotion + +Most programs benefit from a clear capacity allocation. + +**Capacity guidelines.** + +- **0-5% of distribution capacity to paid.** Programs with strong owned and earned channels; paid is selective amplification of best organic pieces. +- **5-20% of distribution capacity to paid.** Programs balancing organic-first with strategic paid amplification. +- **20-50% of distribution capacity to paid.** Programs with explicit paid-amplification strategy; usually B2C brands or programs with strong conversion-funnel logic. +- **50%+ of distribution capacity to paid.** Often signals under-investment in owned and earned; should be reviewed against the paid-as-substitute anti-pattern. + +**The allocation review.** Quarterly, review actual spend allocation. Programs drifting toward paid-heavy allocation should consider whether the drift reflects strategy or under-investment in alternatives. + +--- + +## Methodology-level choices that stay in the public skill + +The boost-organic pattern, sponsored newsletter discipline, syndication network cautious-test discipline, search advertising selective discipline, sponsored podcast host-collaboration discipline, paid-as-substitute anti-pattern, paid amplification of low-organic-engagement failure, capacity allocation guidelines. + +## Implementation choices that stay internal + +Specific paid platform configurations and bidding strategies. Specific engagement-threshold values for boost decisions. Specific newsletter sponsorship vendor selections. Specific syndication network testing protocols. Specific podcast sponsorship measurement infrastructure. The team's own conventions for paid-vs-organic capacity tradeoffs. These vary by team, budget, and platform mix. diff --git a/dist/pi/.agents/skills/content-migration/SKILL.md b/dist/pi/.agents/skills/content-migration/SKILL.md new file mode 100644 index 0000000..6f19225 --- /dev/null +++ b/dist/pi/.agents/skills/content-migration/SKILL.md @@ -0,0 +1,259 @@ +--- +name: content-migration +description: "Move content between platforms, domains, or URL structures while preserving SEO equity, user bookmarks, and integrations. Use this skill when planning a CMS migration, replatforming, consolidating sites, changing URL structures, or merging content from multiple sources. Triggers on content migration, replatform, CMS migration, domain migration, URL restructure, redirect map, site merge, content consolidation, migration plan, post-migration drop. Also triggers when planning a launch that involves moving existing content." +category: cross-cutting +catalog_summary: "Platform migrations with SEO equity preservation" +display_order: 2 +--- + +# Content Migration + +Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic. + +--- + +## When to use + +- Migrating from one CMS to another (e.g., WordPress to a headless setup) +- Consolidating multiple sites into one +- Splitting one site into multiple +- Changing URL structures +- Domain migration (one brand to another, mergers, rebrands) +- Migrating from a custom build to a platform (or vice versa) +- Content audit-driven cleanup as part of a larger move + +## When NOT to use + +- A net-new site with no existing content (no migration needed) +- Single-page edits or content updates within an existing site (use `content-and-copy`) +- Performance or technical SEO improvements without URL changes (use `seo-technical`) +- Routine content audits (use `seo-content-audit`) + +--- + +## Required inputs + +- The source: current platform, current URL structure, current content inventory +- The destination: target platform, target URL structure, target capabilities +- The reason for migration (drives priority of what to preserve) +- Constraints (timeline, budget, downtime tolerance) +- Stakeholders (SEO, content, dev, comms, support) + +--- + +## The framework: 6 phases + +Every content migration follows the same arc. Skipping a phase is how migrations go badly. + +### Phase 1: Inventory + +You can't migrate what you don't know. Build a complete map of what exists. + +For each piece of content: +- URL +- Title +- Content type (article, landing page, product, doc, etc.) +- Status (live, draft, archived, scheduled) +- Last modified +- Author or owner +- Traffic (last 12 months) +- Backlinks (top external referrers) +- Internal links pointing to it +- Embedded assets (images, video, downloads) + +Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool. + +The inventory is a spreadsheet. It's the source of truth for the rest of the migration. + +### Phase 2: Audit and decide + +For each piece of content, decide: + +- **Keep:** migrate as-is +- **Update:** migrate with edits (refresh, expand, fix) +- **Merge:** combine with another piece, redirect both old URLs to the new +- **Redirect:** don't migrate; redirect to a related page +- **Delete:** don't migrate, no redirect (use sparingly; only for clearly low-value pages) + +This is `seo-content-audit` work. The migration is the time to do it; not the time to skip it. + +For each "Update" or "Merge," document the specific changes. + +### Phase 3: Map URLs + +The URL map is the most important migration artifact. + +| Old URL | New URL | Status code | Reason | +|---|---|---|---| +| /old/path | /new/path | 301 | Direct equivalent | +| /old/page-1, /old/page-2 | /new/merged | 301 | Merged content | +| /old/deprecated | /related/replacement | 301 | Closest replacement | +| /old/junk | (none) | 410 | Intentionally gone | + +Rules: +- 301 (permanent redirect) for content that has a new home +- 410 (gone) for intentionally deleted content +- Avoid 404 (not found) where 410 is more accurate +- Never redirect everything to the homepage; specific is always better +- Map every URL with traffic or backlinks; lower-priority URLs can be patterned + +For domain migrations, use a 1:1 path mapping by default (`old.com/page` → `new.com/page`) with specific overrides where structure changes. + +### Phase 4: Build and stage + +Build the destination. Don't skip a staging environment. + +- Set up the new platform with the new content +- Implement the URL map (most platforms support a redirect file or rule) +- Verify a representative sample of redirects work +- Test critical user flows (signup, purchase, contact) +- Validate analytics, monitoring, and integrations +- Test from search engine perspective: robots.txt, sitemap, canonicals + +If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip. + +### Phase 5: Cut over + +The actual switch. Plan it like a launch (and use `launch-runbook` alongside this skill). + +Pre-cutover: +- Comms to stakeholders (date, expected impact) +- Comms to users if downtime expected +- Support team prepped for likely questions +- Lower DNS TTL the day before (1-3 days for safety) +- Backup of source platform (in case rollback is needed) + +Cutover: +- Redirect rules go live +- DNS changes go live +- New sitemap submitted to search engines +- Old sitemap removed or updated +- Internal links audited and updated to point to new URLs (where possible) +- Status page or banner if user-visible disruption + +Immediately post-cutover: +- Smoke test top 50 pages from the inventory +- Verify redirects are 301 (not 302) +- Verify search console for errors +- Watch real-time traffic for unexpected drops +- Watch error logs for missing assets, broken integrations + +### Phase 6: Monitor and recover + +The migration isn't done at cutover. The next 30-90 days reveal problems. + +Watch: +- **Traffic:** expect a temporary drop (10-30% is common); should recover in 4-8 weeks. A persistent drop beyond that is a problem. +- **Indexing:** new URLs should be crawled and indexed. Check coverage in search console. +- **Rankings:** track top keywords. A position drop is normal; a position cliff is a sign of a redirect or canonical problem. +- **Backlinks:** check that linked-from-elsewhere pages still resolve to the right destination. +- **404s:** any URL getting 404s that should have been redirected? Add to the map. +- **User reports:** support tickets, social media. Are users finding their old links? + +Common 30-day fixes: +- Add missed redirects from 404 patterns +- Update internal links you missed +- Re-submit sitemap if indexing stalls +- Investigate and fix any crawl errors + +--- + +## Workflow + +### Step 1: Set the scope + +What's in scope? What's out? Write it down. Migrations expand if not bounded. + +### Step 2: Build the inventory + +Pull every URL, traffic, backlinks, internal links. The spreadsheet is the artifact. + +### Step 3: Decide per piece + +Keep, update, merge, redirect, delete. Document decisions. + +### Step 4: Map URLs + +The complete redirect map. Reviewed by SEO and content stakeholders. + +### Step 5: Build the destination + +In a staging environment. Real content (or representative content). Real redirects. + +### Step 6: Test + +- Sample of redirects (top 20 by traffic, top 20 by backlinks, edge cases) +- Critical flows (signup, checkout, contact) +- Analytics and monitoring +- Search-engine perspective (robots.txt, sitemap, canonicals) + +### Step 7: Cut over + +Following the cutover checklist. Have rollback ready. + +### Step 8: Monitor + +Daily for the first week. Weekly for the first month. Monthly through 90 days. + +### Step 9: Document the result + +What worked. What didn't. Lessons. (See `after-action-report`.) + +--- + +## Failure patterns + +**No URL inventory.** Migration team thinks they have everything. They don't. Old PDFs, archived posts, marketing landing pages with backlinks. Build the inventory. + +**302 redirects instead of 301.** 302 is temporary. SEO equity doesn't reliably pass. Use 301 unless you have a specific reason. + +**Redirecting everything to the homepage.** "We'll let users find their way." They won't. They'll bounce. Map specifically. + +**Long redirect chains.** /a → /b → /c → /d. Each hop loses a little equity and adds latency. Collapse to /a → /d. + +**Forgetting non-HTML URLs.** PDFs, images, downloads. They have URLs too. They have backlinks too. Include in the map. + +**Forgetting query strings.** `/page?id=123` is a different URL than `/page`. Patterns or specific maps for query string variants. + +**Ignoring trailing slashes.** `/page` and `/page/` are different to most servers. Pick one canonical form. Redirect the other. + +**No staging.** The first time the migration runs is in production. Things break. Stage and test. + +**Stage that's too different from production.** Different DNS, different CDN, different platform. Tests pass on staging, fail on production. Stage as close to prod as feasible. + +**Leaving the source live.** Two sites serving the same content. Duplicate content, split equity, user confusion. Take down the source after confirming the destination is solid. + +**Leaving the source domain unrenewed.** Domain expires, redirects break, traffic dies. Renew the source domain for a long time, even if you're not using it. + +**Big-bang migration with no rollback plan.** Something goes wrong. Now what? Plan rollback before cutover. + +**Cutover during a busy period.** End of quarter, holiday season, big campaign. Bad timing. Pick a quiet period. + +**No comms.** Users find their bookmarks broken with no warning. Some won't come back. Communicate. + +**Migration as a one-time event.** It's not done at cutover. Monitor for 30-90 days. Fix what surfaces. + +**Treating migration as just a dev project.** SEO, content, support, comms all need to be involved. Cross-functional from day one. + +--- + +## Output format + +A migration plan document includes: + +- **Scope:** what's in, what's out +- **Inventory:** the URL spreadsheet +- **Audit decisions:** keep, update, merge, redirect, delete +- **URL map:** old to new, with status codes +- **Architecture:** new platform setup, redirect implementation +- **Cutover plan:** the runbook for switch day +- **Rollback plan:** if it goes wrong +- **Monitoring plan:** what's watched, for how long +- **Comms plan:** internal and external +- **Owners and timeline:** who does what when + +--- + +## Reference files + +- [`references/migration-runbook.md`](references/migration-runbook.md): Step-by-step runbook for cutover day, including pre-flight checks, the actual switch, immediate verification, and the first 24 hours of monitoring. diff --git a/dist/pi/.agents/skills/content-migration/references/migration-runbook.md b/dist/pi/.agents/skills/content-migration/references/migration-runbook.md new file mode 100644 index 0000000..c63c24e --- /dev/null +++ b/dist/pi/.agents/skills/content-migration/references/migration-runbook.md @@ -0,0 +1,351 @@ +# Migration Cutover Runbook + +A step-by-step runbook for the day of a content migration cutover. Pair this with `launch-runbook` for general launch protocol. + +The runbook is read by tense people watching the clock. Optimize for clarity. + +--- + +## Roles + +Assign these before the day: + +| Role | Responsibility | Person | +|---|---|---| +| Migration lead | Calls the cutover, makes go/no-go decisions | | +| Tech lead | Executes DNS and redirect changes | | +| QA lead | Runs verification scripts and manual checks | | +| SEO lead | Monitors search and indexing | | +| Comms lead | Sends notifications, updates status page | | +| Support lead | Watches tickets, escalates user reports | | +| Backup decision maker | Authorizes rollback if needed | | + +--- + +## T-7 days: prep + +- [ ] Inventory verified complete +- [ ] URL map signed off by SEO and content +- [ ] Destination tested in staging +- [ ] Sample of 50 redirects verified +- [ ] Rollback plan documented and rehearsed +- [ ] Cutover date and window communicated to all stakeholders +- [ ] Support team briefed on common questions +- [ ] DNS TTL lowered to 300 seconds (5 minutes) +- [ ] Monitoring dashboards built and tested +- [ ] Search console verified for both old and new domains (if domain change) + +--- + +## T-1 day + +- [ ] Final inventory pull (any new content added since the freeze?) +- [ ] Final URL map review +- [ ] Backup of source platform (full, restorable) +- [ ] Test rollback procedure in staging +- [ ] Confirm everyone on the team is available during the window +- [ ] Status page draft prepared +- [ ] Internal comms draft prepared +- [ ] Customer comms draft prepared (if applicable) + +--- + +## T-2 hours + +- [ ] All stakeholders in the cutover channel (chat or call) +- [ ] Status: source platform writeable lock (no new content during cutover) +- [ ] Final smoke test on staging +- [ ] Final confirmation: GO or NO-GO + +NO-GO triggers: +- Critical bug found in destination +- Key person unavailable +- Source data integrity issue +- External factors (e.g., source platform outage) + +If NO-GO, reschedule. Don't push through. + +--- + +## T-0: cutover + +Time-box each step. If a step takes 2x its expected duration, pause and assess. + +### Step 1: Final source backup + +Time: 5-15 minutes depending on volume. + +``` +[Specific backup commands or steps] +``` + +Verify backup integrity. Continue only on success. + +### Step 2: Deploy destination to production + +If the destination has been on staging only: + +``` +[Deploy commands] +``` + +Verify the destination is responding correctly on its production address (which may not yet have DNS pointed at it). + +### Step 3: Deploy redirect rules + +The redirect rules go on whatever the source platform uses to redirect (htaccess, edge worker, CDN rule, server config). + +``` +[Deploy redirect rules] +``` + +Test 5 redirects manually: + +```bash +curl -I https://oldhost.com/path1 +curl -I https://oldhost.com/path2 +# Expected: 301 to https://newhost.com/path1 +``` + +### Step 4: DNS cutover (if domain change) + +Update DNS to point the new domain to the destination. + +``` +[DNS update steps] +``` + +Verify resolution from multiple regions: + +```bash +dig +short newhost.com @8.8.8.8 +dig +short newhost.com @1.1.1.1 +``` + +DNS propagation usually completes within minutes (with the TTL lowered earlier). Some resolvers may lag. + +### Step 5: Submit new sitemap + +``` +[Submit to search engines] +``` + +For Google: search console → sitemaps → submit. +For Bing: webmaster tools → sitemaps → submit. + +### Step 6: Update internal references + +If the source has links to itself (or hardcoded references), update the source to point at the new URLs (helps tools that haven't picked up the redirects yet). + +If the source is being decommissioned entirely, this step is moot. + +### Step 7: Update integrations + +External integrations that reference URLs: +- Email templates with absolute URLs +- Social profiles with bio links +- Partner sites with deep links +- Marketing automation +- Analytics goals (URL-based goals may break) +- Saved CRM links + +Update each. Document in the comms plan. + +--- + +## T+15 minutes: smoke test + +- [ ] Top 50 URLs from inventory each return correct status +- [ ] Redirects return 301 (not 302) +- [ ] Critical user flows work (signup, contact form, checkout if applicable) +- [ ] Search engines can crawl (robots.txt, sitemap) +- [ ] Analytics is firing on new pages +- [ ] Monitoring is showing the new endpoints + +If any check fails: triage. Fix forward if simple; rollback if complex. + +--- + +## T+1 hour: stakeholder check-in + +- [ ] Status page updated +- [ ] Internal comms sent +- [ ] Customer comms sent (if applicable) +- [ ] Support has not seen unusual ticket volume +- [ ] Real-time analytics shows expected traffic patterns + +--- + +## T+24 hours + +- [ ] Search console shows crawls of new URLs +- [ ] Search console "Indexing" tab not showing major issues +- [ ] No spike in 404s or 5xx errors in logs +- [ ] Backlink-bearing pages confirmed to redirect correctly +- [ ] Monitoring dashboards normal +- [ ] No major customer reports + +--- + +## Rollback decision criteria + +Rollback if: +- Critical functionality broken on the destination +- Significant data corruption discovered +- Security issue introduced by the migration +- Search indexing catastrophically failing (rare; usually fixable forward) + +Do NOT rollback for: +- Normal traffic dip (expected, recovers) +- Individual broken redirects (fix forward) +- Minor visual issues (fix forward) +- Slow pages (fix forward) + +Rollback procedure: + +### Step R1: Reverse DNS (if domain change) + +``` +[Revert DNS] +``` + +### Step R2: Disable redirect rules + +Take redirects offline so source URLs serve source content again. + +``` +[Disable redirects] +``` + +### Step R3: Unlock source platform + +Remove the writeable lock on the source. + +### Step R4: Restore from backup if needed + +If data corruption: restore. See `backup-and-disaster-recovery`. + +### Step R5: Comms + +- [ ] Status page updated (rolled back) +- [ ] Internal comms (rolled back, next steps) +- [ ] Customer comms if applicable (apology, next steps) + +### Step R6: Schedule retrospective + +Within 5 business days. See `after-action-report`. + +--- + +## First-week monitoring + +Daily checks: + +| Metric | Target | Action if off | +|---|---|---| +| Top-10 page traffic | Within 80% of baseline | Investigate redirects, check indexing | +| Conversion rate | Within 90% of baseline | Investigate UX changes, check analytics implementation | +| 404 rate | Below 1% of requests | Add missing redirects | +| Crawl errors | Decreasing | Check robots.txt, sitemap, canonicals | +| Indexing rate | Increasing toward old volume | Submit URLs manually if stalled | +| Search rankings (top 20 keywords) | No cliff drops | Investigate canonicals, redirects, content parity | + +--- + +## First-month monitoring + +Weekly checks: + +| Metric | Target | +|---|---| +| Total organic traffic | Recovering toward baseline (typically 4-8 weeks) | +| Indexed pages | At or above pre-migration count | +| Backlink-pointed-to pages | All resolving correctly | +| 410 vs 404 ratio | Pages that should be gone return 410, not 404 | + +--- + +## After 90 days + +- [ ] Full performance review vs pre-migration baselines +- [ ] Document what worked, what didn't (after-action report) +- [ ] Decommission source platform if not already done +- [ ] Renew source domain (long-term, even if not in use, to preserve redirects) +- [ ] Archive the migration documentation for future reference + +--- + +## Common surprises + +**Backlinks pointing to URLs not in inventory.** Old marketing pages, archived posts, removed-but-still-linked content. Add to the map after cutover. + +**Trailing slash inconsistencies.** Server treats `/page` and `/page/` differently. One redirects, the other 404s. Fix with a normalizing redirect. + +**Search engines slow to update.** Old URLs still appear in search for weeks. Normal. Don't redirect to homepage to "speed it up." + +**Analytics goals broken.** URL-based goals don't match new URLs. Update the goals; backfill if possible. + +**Hardcoded absolute URLs in email templates.** Old links in transactional emails. Update templates. + +**Schema.org or canonical tags pointing wrong.** Crawlers follow canonical even after redirects. Verify canonical tags on the destination point to the destination. + +**Sitemap caching.** Some platforms cache sitemaps aggressively. Force a refresh. + +**robots.txt forgot the new sitemap.** Add the new sitemap to robots.txt. + +--- + +## Post-cutover comms template + +### Internal (to team) + +Subject: Migration cutover complete + +``` +The migration to [new platform/URL/etc.] is complete as of [time]. + +Status: +- [N] redirects in place +- All critical flows verified +- Monitoring shows expected traffic patterns + +We'll watch closely over the next 24 hours and the first week. Report any issues in [channel]. + +Next steps: +- [Specific monitoring action] +- [Specific follow-up] + +Thanks to everyone who made this happen. +``` + +### External (to users, if applicable) + +Subject: We've moved [or rebranded, or restructured] + +``` +Hi [name], + +[Brief reason for the change.] + +What this means for you: +- [Specific user-facing change 1] +- [Specific user-facing change 2] + +Old links should redirect automatically. If you find a broken link, please let us know at [contact]. + +Thanks for your patience as we make this transition. +``` + +--- + +## Document the result + +Within a week of cutover, write up: + +- What was migrated +- What worked +- What broke and how it was fixed +- What we'd do differently +- Lessons for the next migration + +This becomes input to `after-action-report` and to future migration playbooks. diff --git a/dist/pi/.agents/skills/content-refresh-system/SKILL.md b/dist/pi/.agents/skills/content-refresh-system/SKILL.md new file mode 100644 index 0000000..a7f8fa1 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/SKILL.md @@ -0,0 +1,255 @@ +--- +name: content-refresh-system +description: "Systematic content refresh discipline. Quarterly audits, refresh prioritization (which pieces, when, how deep), refresh-vs-merge-vs-delete decisions, the lifecycle that distinguishes intentional refresh from set-and-forget decay. Builds on the refresh sections of pillar-content-architecture and editorial-qa with a program-level discipline. Triggers on content refresh, content decay, content audit, refresh prioritization, content lifecycle, refresh strategy, traffic decay, ranking drop, content freshness, evergreen content, content maintenance. Also triggers when traffic is eroding silently across an aging content library, when teams cannot decide which pieces to refresh, or when refresh work is happening but the impact is unclear." +category: content +catalog_summary: "Systematic content refresh: quarterly audits, refresh prioritization, refresh-vs-merge-vs-delete decisions, the lifecycle discipline that distinguishes intentional programs from set-and-forget decay" +display_order: 10 +--- + +# Content Refresh System + +A senior editorial leader's playbook for systematic content refresh. The discipline that distinguishes intentional refresh programs from set-and-forget decay, and the prioritization framework that prevents both over-refresh (refresh-everything-on-calendar) and under-refresh (refresh-nothing-until-traffic-collapses). + +Content decays. Search behavior shifts; SERP intent reshapes; facts go stale; competitors publish stronger pieces; the brand's own positioning evolves past what older pieces represent. Programs that ignore this reality watch traffic erode silently across the library. Programs that overreact (rewriting everything on calendar) burn editorial capacity that should be producing new flagship work. The discipline is in the middle: refresh what matters when signals say so, and document the decisions so the program is auditable. + +This skill is the program-level refresh discipline across the whole content library. It builds on `pillar-content-architecture`'s hub-level refresh consideration (refresh as ONE consideration in hub design) and `editorial-qa`'s pre-publish quality gate (this skill is post-publish lifecycle, not pre-publish QA). Together those skills cover content quality at the moments quality decisions get made; this skill covers the moments between, when content is in the field and decaying or holding. + +The voice is the senior editorial leader who has watched refresh programs fail in both directions and who has shipped the systems that produced durable refresh discipline. + +When to use this skill: building a refresh program from scratch, auditing why refresh work is happening but traffic is not responding, designing the prioritization that keeps refresh tractable across a 200-piece or 2,000-piece library, or fixing a refresh program that is eating editorial capacity without clear results. + +--- + +## What this skill covers + +This skill spans the post-publish lifecycle of content. The content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is HUB scope; refresh appears as ONE consideration in hub design. +- `content-brief-authoring` is per-piece scope at production time. +- `content-and-copy` is execution scope at production time. +- `editorial-qa` is gate scope: pre-publish verification. +- **`content-refresh-system` (this skill)** is lifecycle scope: program-level refresh discipline across the whole content library, after pieces are in the field. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content libraries of 50-5,000+ pieces, agencies maintaining client content programs across years. + +What is not in scope: writing the refreshed pieces themselves (that is `content-and-copy`), the brief that drives the refresh (that is `content-brief-authoring`), the pre-publish gate on the refreshed piece (that is `editorial-qa`). This skill is the prioritization and lifecycle discipline; the actual content work plugs into the existing skills. + +--- + +## Refresh-everything vs refresh-nothing vs triaged-refresh + +The keystone framing. Two failure modes plus the discipline. + +**Refresh-everything.** Full rewrites on calendar. Every piece gets a refresh on a 12-month or 18-month rotation regardless of signals. Output: editorial capacity consumed by maintenance work that often was not needed, while strong pieces are touched into worse versions and weak pieces consume the same effort as flagship pieces. Cost: opportunity cost on new flagship production; maintenance fatigue in the editorial team; some pieces that were performing well get diluted by unnecessary edits. + +**Refresh-nothing.** Set-and-forget. Pieces ship and never get touched again. Output: traffic decays silently across the library as facts go stale, competitors publish stronger pieces, and SERP intent shifts away from the piece's framing. The library's compounding value erodes invisibly until an algorithm update or a competitor's flagship piece exposes the rot. Cost: cumulative traffic loss that nobody attributes to refresh failure because the loss is gradual; trust loss when readers find stale facts in pieces they expected to be current. + +**Triaged-refresh.** Refresh what matters when signals say so. Audit cadence catches decay early; prioritization concentrates effort on high-value-decaying pieces; weak pieces get refresh-vs-merge-vs-delete dispositions instead of automatic refresh; the program is auditable because every refresh decision was a deliberate response to specific signals. Output: editorial capacity preserved for new production; the library's compounding value protected; refresh work is seen, understood, and measured. + +The litmus test. Ask of any refresh decision: what signal triggered this refresh, what depth of refresh did the signal warrant, what outcome do we expect, and how will we measure whether the refresh worked? If the answer is "it was scheduled" or "we always refresh after 12 months," the program is on calendar rather than on signal. + +--- + +## Refresh signals + +Five categories of signal that trigger refresh consideration. Pieces that show no signals do not need refresh; pieces that show multiple signals are higher priority. + +**Traffic decay.** Organic traffic to the piece is trending down over a 90+ day window beyond the seasonal baseline. The decay can be slow (5-10% over a year) or sharp (40%+ in a month after an algorithm update). Slow decay typically indicates content drift; sharp decay typically indicates external change. + +**Ranking drops.** The piece is losing position on its target keywords. Drops from page 1 to page 2-3 are particularly consequential; drops within page 1 (position 3 to position 7) are less so but still tracked. Persistent ranking drops over 30+ days indicate a real shift, not search-result volatility. + +**Factual staleness.** The piece contains statistics, references, examples, or claims that are dated. A 2018 stat in a 2026 piece on a fast-moving topic is staleness; a piece that references defunct products or platforms is staleness; a piece that uses pre-shift framings ("AI is starting to influence search" in 2026) is staleness. + +**SERP intent shift.** The dominant SERP format for the target keyword has changed. The piece was written when articles ranked for the keyword; now the SERP wants product comparisons, video, or AI-overview-style answers. The piece may still rank but increasingly for the wrong reason. + +**Content drift.** The piece's positioning no longer matches the brand's current positioning. Voice has evolved; the brand's POV on the topic has sharpened or shifted; the piece reads as the brand-of-three-years-ago. Internal signal more than external; readers may not notice but the team will. + +The audit. Every piece in the library can be characterized by which signals it shows. Pieces with zero signals are stable; pieces with one or two signals warrant attention; pieces with three or more signals are typically in active decay. + +Detail in [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md). + +--- + +## The audit cadence + +How often to look. Two cadences with different tradeoffs. + +**Quarterly audit.** A formal review of the content library every 90 days. The team pulls traffic, ranking, and recency data; reviews each piece against the signals; assigns dispositions (refresh, merge, delete, or leave alone). Output: a refresh queue with priorities and a backlog of merge/delete decisions. + +- Strength: predictable, auditable, fits naturally into editorial calendar planning. +- Weakness: 90-day delay in detecting sharp decay; piece that lost 40% traffic in week 2 of a quarter is in decay for 75 days before the audit catches it. + +**Continuous monitoring.** Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. Pieces that lose more than X% traffic in Y days trigger a review. + +- Strength: catches sharp decay early; allows fast response to algorithm updates. +- Weakness: requires monitoring infrastructure; can produce alert fatigue if thresholds are too tight; misses slow decay that does not cross thresholds. + +**The hybrid pattern.** Most strong refresh programs run both. Quarterly audits catch slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. The two cadences cover different failure modes. + +Detail in [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md). + +--- + +## Refresh prioritization + +Prioritization is the discipline. Most libraries have more pieces showing signals than the team has capacity to refresh. Prioritization concentrates effort on the pieces where refresh produces the most value. + +The 2x2 matrix: piece value (high vs low) crossed with traffic state (decaying vs stable). + +**High-value, decaying.** Top priority. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. Refresh these first; the traffic loss compounds and the lost equity is hard to recover. + +**High-value, stable.** Monitor; do not refresh proactively. Pieces that are performing should not be touched without clear signal; refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. + +**Low-value, decaying.** Audit for merge or delete. Pieces with low traffic that are decaying further are usually candidates for merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling). Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. + +**Low-value, stable.** Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. Detail in [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md). + +--- + +## Refresh depth options + +Not every refresh is the same kind of work. Four depth levels. + +**Light edit.** Update statistics, replace dead links, fix factual errors, swap dated examples. Keeps the piece's structure and argument intact. Time investment: 30-90 minutes per piece. Use when the piece is structurally sound and only the surface details have aged. + +**Substantial revision.** Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that emerged after the piece was written. Time investment: 2-4 hours per piece. Use when the piece's structure is sound but specific sections have become weak. + +**Full rewrite.** Keep the URL and topic; rewrite the piece end-to-end. Time investment: similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. Use when the piece's structure no longer fits the current SERP intent or the brand's positioning has shifted enough that the piece needs to be re-conceived. + +**Structural redesign.** Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Time investment: a multi-piece project. Use when refresh is part of a larger structural change in the content library (a hub being rebuilt, a category being consolidated). + +The depth-decision discipline. Match depth to signal strength. Sharp decay or major SERP intent shift may warrant full rewrite; slow decay with stale stats may warrant only a light edit. Treating every refresh as a full rewrite is refresh-everything energy in a different shape. + +Detail in [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md). + +--- + +## Refresh vs merge vs delete decisions + +Not every piece in decay should be refreshed. Three dispositions. + +**Refresh.** The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +**Merge.** Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +**Delete.** The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. Delete and redirect to the closest sibling or, if no sibling exists, to the relevant hub or category page. + +The decision criteria. Refresh when the piece has demand and a path back. Merge when authority is being split. Delete when there is no path forward and the piece is not worth maintaining. + +The under-recognized failure mode: refreshing pieces that should have been merged or deleted. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. + +Detail in [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md). + +--- + +## Refresh execution patterns + +Who does the work, how it ships. + +**Ownership.** A single owner per refresh, not a committee. The owner is accountable for the outcome and runs the work through to ship. Refreshes that pass through multiple hands without an accountable owner often get partially done and then stall. + +**Editorial integration.** Refreshes typically run through the same editorial workflow as new pieces (brief, draft, edit, QA gate, publish), scaled to the depth chosen. A light edit may skip the brief and go straight to edit; a full rewrite goes through every step. + +**Capacity allocation.** Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff: a team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. The split varies by program maturity (older libraries often need 30-40% refresh allocation; newer libraries may need 5-10%). + +**Refresh batching.** Some teams batch refresh work into dedicated weeks or sprints; others integrate one refresh per week into the steady-state production cadence. Batching produces focus but interrupts new production; integration sustains new production but slows refresh velocity. Either works; the failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence. + +Detail in [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md). + +--- + +## Re-promotion after refresh + +Refreshed pieces need to signal to search engines and audiences that they have been updated. + +**To search engines.** Update the modified date in schema markup. Update the published-or-modified-date in the visible metadata. Submit the URL for re-crawl through Search Console. Some teams update the URL minimally (e.g., adding a year to the slug for evergreen pieces), but URL changes carry redirect risk and should be reserved for substantial-revision or full-rewrite refreshes. + +**To audiences.** Re-share the refreshed piece on the channels where the original landed: newsletter, social, syndication partners. Treat the refresh as a publication event, not as silent maintenance. The re-promotion is part of the refresh's value proposition: the piece earns new attention as well as preserved search position. + +**Internal linking refresh.** Pieces that link to the refreshed piece may benefit from anchor-text updates if the refreshed piece's positioning shifted. Sister pieces that should now link to the refreshed piece can be updated to do so. + +**The refresh that nobody tells anyone about.** A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement. + +Detail in [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md). + +--- + +## Refresh tracking and effectiveness measurement + +The discipline that prevents refresh-theater: tracking which refreshes worked, which did not, and what the patterns reveal. + +**Per-refresh tracking.** Each refresh is logged with: the signals that triggered it, the depth chosen, the date shipped, the predicted outcome, the actual outcome at 30 days and 90 days post-refresh. The log is the refresh program's evidence base. + +**Effectiveness metrics.** The primary metrics depend on the refresh's purpose. Traffic-decay refreshes track post-refresh traffic recovery; ranking-drop refreshes track post-refresh ranking position; content-drift refreshes track post-refresh engagement metrics (time on page, return visits) more than search metrics. + +**Pattern detection.** The log reveals patterns over time. Some signal types produce reliable recovery; others rarely produce recovery and indicate a deeper problem (the topic itself is dying; the brand's positioning on the topic is wrong; competitors are too strong to displace). The patterns inform program-level decisions. + +**The refresh-that-did-not-work review.** Refreshes that did not produce the expected recovery should get a structured review. Was the depth wrong? Was the merge or delete decision the right disposition that we did not take? Did the underlying problem turn out to be something refresh cannot fix? + +Detail in [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-refresh-failures.md`](references/common-refresh-failures.md). + +- "We refresh every piece annually and traffic is still declining." Refresh-everything pattern; the calendar-based work is not catching the actual decay signals. +- "We have not touched the library in 18 months and traffic has eroded 30%." Refresh-nothing pattern; the decay went uncaught. +- "We refresh pieces but the traffic does not come back." Wrong disposition; the pieces were merge or delete candidates, not refresh candidates. +- "Our refresh queue is 200 pieces deep and growing." No prioritization; everything that shows any signal goes in the queue regardless of value. +- "We refreshed a flagship piece and traffic dropped." Refresh damaged a piece that was performing; the refresh was triggered by calendar rather than signal. +- "The team is exhausted from refresh work." Capacity allocation is wrong; either refresh ratio is too high, or new production is suffering, or the depth choices are over-investing. +- "We do not know if our refreshes are working." No tracking; refresh work happens but its effectiveness is invisible. +- "Some pieces always get refreshed; others never do." The signal triage is informal and inconsistent; some pieces are getting attention because they are visible, not because they are most decayed. +- "We refreshed a piece and forgot to re-promote it." Refresh-without-re-promotion; the piece's modified date updated but no audience or channel re-engagement happened. +- "Our quarterly audit catches things 75 days late." Quarterly cadence alone is missing sharp decay; add continuous monitoring for traffic-loss thresholds. +- "We refresh sister pieces but the hub orchestration is unchanged." Pieces refreshed in isolation when the hub-level architecture also needed updating; coordinate with `pillar-content-architecture` discipline. + +--- + +## The framework: 12 considerations for content refresh + +When designing or auditing a refresh program, walk these 12 considerations. + +1. **Triaged-refresh, not refresh-everything or refresh-nothing.** Refresh on signal, not on calendar. +2. **Signal categories named.** Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. +3. **Audit cadence committed.** Quarterly audit plus continuous monitoring; both running. +4. **Prioritization matrix applied.** High-value-decaying first; low-value-decaying audited for merge or delete. +5. **Depth matched to signal.** Light edit, substantial revision, full rewrite, structural redesign. +6. **Disposition decided per piece.** Refresh, merge, or delete; not all decay warrants refresh. +7. **Single ownership per refresh.** Accountable owner runs the work to ship. +8. **Capacity allocation explicit.** Refresh ratio of editorial capacity is a real number, planned. +9. **Re-promotion built into the workflow.** Schema, visible date, search-engine resubmit, audience re-share. +10. **Per-refresh tracking.** Signals, depth, outcomes logged for pattern detection. +11. **Effectiveness measurement.** Recovery tracked at 30 and 90 days; patterns inform program decisions. +12. **The-refresh-that-did-not-work review.** Failed refreshes get structured review; lessons compound. + +The output of the framework is a refresh program that is auditable, capacity-respecting, and producing visible value for the library's compounding equity. + +--- + +## Reference files + +- [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md) - Five signal categories with detection patterns. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. The audit pattern that surfaces signals across the library. +- [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md) - Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, alert-threshold design. +- [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md) - 2x2 matrix with quadrant strategies. High-value-decaying as top priority; low-value-decaying audited for merge or delete; the discipline of NOT refreshing the high-value-stable quadrant. +- [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md) - Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, depth-creep anti-pattern. +- [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md) - Disposition criteria. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged. +- [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md) - Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. +- [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md) - Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. +- [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md) - Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. +- [`references/common-refresh-failures.md`](references/common-refresh-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: refresh is content's immune system + +A content library is a long-running system. The pieces in it interact with search algorithms that change, audiences that shift, brands that evolve, and competitors that publish. Set-and-forget treats the library as a static asset and watches it decay. Refresh-everything treats it as a maintenance project and burns capacity that should be producing new flagship work. + +The discipline is the immune system: signals are detected early, prioritization concentrates effort where the value is highest, depth matches signal strength, dispositions include merge and delete (not just refresh), and the work is tracked so the program learns. Programs that run this discipline preserve the library's compounding value. Programs that do not watch the library erode and discover the loss only when an algorithm update or a competitor's flagship piece exposes how far the rot has spread. + +When in doubt about whether a refresh program is ready, ask: does the program detect signals, prioritize on value, match depth to signal, decide between refresh and merge and delete, allocate capacity explicitly, re-promote the refreshed pieces, and track effectiveness? If yes to all of those, the program is real. If no to any, the gap is where decay will compound. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md b/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md new file mode 100644 index 0000000..4667597 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md @@ -0,0 +1,162 @@ +# Audit cadence patterns + +Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, and alert-threshold design. + +The audit cadence determines how quickly decay signals turn into refresh decisions. Programs that audit annually catch decay 9-12 months late; programs that monitor continuously without an audit layer catch sharp decay early but miss the slow-drift and content-drift signals that need human review. The hybrid pattern is the standard for mature programs. + +--- + +## The quarterly audit + +A formal review of the content library every 90 days. + +**The mechanics.** + +- The team blocks 1-3 days per quarter for the audit. +- Pull data: traffic per URL over the last 90 and 180 days, rankings on target keywords, last-modified dates, target-keyword SERP samples. +- Run each piece through the five-signal checklist (see `refresh-signals-checklist.md`). +- Assign each piece a disposition: refresh (with depth), merge, delete, monitor, no action. +- Output a refresh queue prioritized by the prioritization matrix. + +**Strengths.** + +- Predictable. The team knows when audit work happens and can plan around it. +- Auditable. Each quarter's decisions are documented; patterns over multiple quarters become visible. +- Comprehensive. The signal types that need human judgment (content drift, SERP intent shift) get reviewed; continuous monitoring cannot detect these without human eyes. +- Capacity-aware. Audit work happens at known times; new production schedules can flex around it. + +**Weaknesses.** + +- 90-day delay in detecting sharp decay. A piece that lost 40% traffic in week 2 of the quarter is in decay for 75 days before the audit catches it. +- Heavy lift. Auditing 200-2,000 pieces in 1-3 days requires structured tooling; teams without tooling burn out. +- Focus on the audit moment can crowd out continuous attention. "We will catch it next quarter" becomes the answer to issues that warrant immediate response. + +--- + +## Continuous monitoring + +Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. + +**The mechanics.** + +- Define thresholds for sharp decay: e.g., traffic drop of 25%+ in 14 days, ranking drop of 5+ positions in 14 days. +- Automated monitoring runs daily or weekly, comparing current data to baseline. +- Alerts route to the editorial owner of the affected piece (or to a refresh queue triage owner if pieces do not have individual owners). +- Triage decides whether the alert warrants immediate refresh, addition to the next quarterly audit's queue, or dismissal as noise. + +**Strengths.** + +- Catches sharp decay early. Algorithm-update fallout, technical regressions, and dramatic SERP intent shifts get attention within days, not 75-90 days. +- Allows fast response. A piece that lost 50% traffic on a specific date can be investigated while the cause is fresh. +- Reduces audit-day exhaustion. Sharp signals are handled in real time; the quarterly audit focuses on the slower signals. + +**Weaknesses.** + +- Requires monitoring infrastructure. Teams need rank tracking, traffic monitoring, and alerting that can route to specific URL owners. +- Alert fatigue if thresholds are too tight. Daily alerts on minor fluctuations train the team to ignore the alerts; thresholds need calibration. +- Misses slow decay. Pieces declining 5-8% per quarter never cross thresholds; they accumulate decay invisibly. The quarterly audit is what catches these. +- Misses non-traffic signals. Continuous monitoring on traffic and rankings cannot detect content drift or factual staleness. + +--- + +## The hybrid pattern + +Most strong refresh programs run both. The quarterly audit catches slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. + +**Integration shape.** + +- Continuous monitoring runs daily or weekly with a small set of well-calibrated thresholds. +- Quarterly audit runs the full signal checklist on the whole library. +- Pieces that triggered continuous-monitoring alerts during the quarter get fast-track disposition; the quarterly audit reviews the rest. +- The continuous-monitoring log feeds into the quarterly audit so the team can see whether thresholds are calibrated correctly (too many false alerts, too few real ones). + +**Capacity split.** A typical hybrid pattern might allocate 5-10% of editorial capacity to continuous-monitoring response (a few hours per week) and a concentrated 1-3 days per quarter to the audit. The split scales with library size and decay rates. + +--- + +## Alert-threshold design + +Calibrating continuous-monitoring thresholds is its own discipline. + +**Threshold goals.** + +- High precision: when the threshold is crossed, the alert is usually a real signal, not noise. +- Reasonable recall: catches the sharp-decay events that matter; does not need to catch every minor fluctuation (the audit catches those). +- Sustainable cadence: alerts arrive at a frequency the team can triage without fatigue. + +**Threshold patterns that work.** + +- Traffic: 25%+ drop in 14 days, sustained over 21 days. The sustainment requirement filters volatility. +- Ranking: 5+ position drop on a tracked keyword, sustained over 14 days. Single-day drops are noise; sustained drops are signal. +- Indexing: any unexpected change in indexed status (200 to non-200 status, sudden noindex tag, sudden disappearance from index). These are usually technical regressions and warrant immediate attention. +- Schema validation: schema breaking or warnings appearing on a piece that previously validated cleanly. Often indicates a CMS update or template change. + +**Threshold patterns that fail.** + +- 10% traffic drop alerts produce far too many false positives; teams stop reading the alerts. +- Single-day rank drop alerts produce noise; SERP volatility within a few positions is normal. +- Aggregate-traffic alerts on whole categories rather than per-URL alerts hide which specific pieces are decaying. + +**Threshold tuning.** Run alerts in shadow mode for 4-6 weeks before committing. Track whether alerts correspond to real signals on review. Adjust thresholds based on the precision-recall observed. + +--- + +## When to audit more frequently + +Some programs warrant more than quarterly audits. + +**Programs in active rebuild.** Content libraries undergoing structural redesign or hub reorganization benefit from monthly audits during the rebuild phase. The signal volume is higher and the decisions need faster cycle time. + +**Post-algorithm-update period.** In the 30-90 days after a major algorithm update, signal volume spikes. Some teams run a special audit at the 30-day post-update mark in addition to the regular quarterly cadence. + +**Programs with rapid topic evolution.** Topics that move quickly (AI tools, evolving regulatory environments, tactical playbooks in fast-moving fields) may benefit from monthly factual-staleness checks even when traffic and ranking signals are stable. + +--- + +## When to audit less frequently + +Some programs can run on lighter cadence. + +**Small libraries (under 50 pieces) with stable performance.** Bi-annual audits may be sufficient if continuous monitoring is in place and the library has shown stable decay rates over multiple cycles. + +**Libraries dominated by evergreen pieces.** When the topical mix is heavily evergreen (foundational concepts that move slowly), quarterly audits may produce limited signal volume. Combine with continuous monitoring; reduce audit frequency. + +The discipline. Cadence should match decay rate, not be fixed by convention. Programs that decay quickly need faster cadence; programs that decay slowly can run longer audit cycles. + +--- + +## Audit anti-patterns + +**Annual audit as the only cadence.** Catches decay 9-12 months late; the library is in significant erosion before the audit runs. + +**Continuous monitoring without quarterly audit.** Catches sharp decay; misses slow decay, content drift, and SERP intent shifts that need human review. + +**Audit happening but no follow-through.** The team runs the audit, produces a queue, then loses momentum on actually executing the refreshes. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +**Audit without prioritization.** The output is a list of every piece showing any signal, with no value-weighted prioritization. The team does the cheapest refreshes first regardless of value, leaving high-value-decaying pieces in the backlog. + +**Audit without depth assignment.** Pieces are tagged "refresh" without specifying depth. Refresh execution defaults to whatever depth the team has time for, which is often light edit even when substantial revision is needed. + +--- + +## Audit governance + +Who runs the audit, who approves dispositions, how the queue routes to execution. + +**Single audit owner.** A specific person runs the audit each quarter, accountable for signal quality and disposition recommendations. + +**Disposition review.** Refresh, merge, and delete dispositions are reviewed by a content lead or director. Delete dispositions in particular need approval because they are irreversible (pieces deleted and not redirected can lose authority that did not need to be lost). + +**Queue routing.** The refresh queue routes to specific editorial owners based on capacity, expertise, and the depth of work required. Light edits route to anyone with capacity; full rewrites route to the writer or editor best matched to the topic. + +**Audit log.** Each quarter's audit, dispositions, and outcomes are logged. The log feeds the next quarter's review (which dispositions actually shipped, which produced recovery, which patterns are emerging). + +--- + +## Methodology-level choices that stay in the public skill + +The quarterly audit mechanics, continuous monitoring mechanics, hybrid pattern, alert-threshold design principles, audit-cadence variations, audit governance shape, and the anti-patterns. + +## Implementation choices that stay internal + +Specific monitoring tools the team uses (rank trackers, analytics platforms, alerting systems). Specific threshold values calibrated to the team's data. Specific dashboards and reporting templates. Specific ticketing or queue systems for refresh routing. Specific automation scripts that pull data into audit-ready formats. The team's own audit-day rituals and tooling. These vary by team, tooling, and library size. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md b/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md new file mode 100644 index 0000000..df86203 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md @@ -0,0 +1,169 @@ +# Common refresh failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear across programs of different sizes, library ages, and editorial team compositions; the underlying causes are rarely about people and almost always about discipline, prioritization, or measurement gaps. + +--- + +## Failure 1: Refresh-everything-on-calendar + +**Symptom.** Every piece gets refreshed on a 12-month or 18-month rotation regardless of signals. Editorial capacity is consumed by maintenance work that often was not needed. + +**Diagnosis.** The program treats refresh as a calendar event rather than as a signal-driven decision. Pieces that were performing get touched into worse versions; pieces that were decaying are scheduled for refresh whenever their rotation comes up rather than when the decay signals warrant. + +**Cure.** Replace calendar-driven refresh with the prioritization matrix and the signal-driven audit cadence. Refresh on signals; leave stable pieces alone. + +**Capacity recovery.** Programs that abandon refresh-everything typically recover 30-50% of their refresh capacity for higher-value work or for new production. + +--- + +## Failure 2: Set-and-forget + +**Symptom.** The team has not touched the library in 18+ months. Traffic has eroded across the library; the team is uncertain how much loss is from refresh failure vs other causes. + +**Diagnosis.** The program lacks both audit cadence and continuous monitoring. Decay accumulates silently because no system is detecting it. + +**Cure.** Establish the hybrid audit pattern: quarterly audit plus continuous monitoring. The first audit will surface a large queue (typical when starting from set-and-forget); the queue should be triaged by the prioritization matrix and worked through over multiple quarters rather than tackled all at once. + +--- + +## Failure 3: Refresh that should have been merge or delete + +**Symptom.** The team spends hours refreshing pieces that even at their best will not produce meaningful recovery. The same pieces appear in queue across multiple audits. + +**Diagnosis.** The disposition decision was wrong. Refresh was the default disposition because it felt less destructive than merge or delete; the actual right disposition was merge into a stronger sibling or delete with redirect. + +**Cure.** Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. Train the audit owner on the disposition decision flow (see `refresh-vs-merge-vs-delete.md`). + +--- + +## Failure 4: Unprioritized refresh queue + +**Symptom.** The refresh queue is 200 pieces deep and growing. The team works through the queue in order of arrival or in order of "easiest first" rather than by value. + +**Diagnosis.** No prioritization matrix is being applied. Every piece showing any signal goes in the queue regardless of value. + +**Cure.** Apply the 2x2 matrix (value × traffic state). Queue entries get tagged by quadrant. Work focuses on high-value-decaying first; low-value-decaying gets disposition decisions (often merge or delete) rather than refresh; stable quadrants get monitor or no action. + +--- + +## Failure 5: Refresh-on-stable-piece regression + +**Symptom.** A flagship piece was performing well. The team refreshed it because it was the next piece in the rotation. After the refresh, traffic dropped 30% and rankings dropped 5 positions. + +**Diagnosis.** Refresh-everything-on-calendar damaged a stable piece. The refresh introduced changes that shifted the SERP signals or the piece's structural fit; the new version performs worse than the original. + +**Cure.** Stop refreshing high-value-stable pieces by default. Pieces in this quadrant get monitor disposition unless content drift is severe enough to warrant the regression risk. When refreshing a stable piece is genuinely warranted, plan for fast revert if regression occurs. + +**Recovery.** Some refresh regressions can be partially reversed by going back to a closer-to-original version of the piece. Some cannot. The lesson informs future stable-piece refresh decisions. + +--- + +## Failure 6: Capacity overcommitment + +**Symptom.** The team is exhausted from refresh work. New-piece production is suffering. The team complains of refresh fatigue. + +**Diagnosis.** Capacity allocation to refresh is too high (or new-production commitments are too high; the result is the same). The team is being asked to do more total work than capacity allows. + +**Cure.** Right-size the allocation. Reduce refresh queue intake by tightening prioritization (only highest-value items enter the queue); or reduce new-production commitments; or temporarily increase capacity. The status quo is unsustainable. + +**Sustainability check.** Capacity is real. Programs that pretend capacity is infinite produce burnout, quality drift, and team turnover. The capacity audit (see `refresh-execution-patterns.md`) is what catches this before burnout. + +--- + +## Failure 7: Effectiveness invisible + +**Symptom.** "We do not know if our refreshes are working." Refresh work happens but its effectiveness is not tracked or reviewed. + +**Diagnosis.** No per-refresh tracking is in place. The program runs without learning data. + +**Cure.** Establish the minimum log (see `effectiveness-measurement.md`). Backfill the log for recent refreshes if possible. Establish 30-day and 90-day measurement windows. Run quarterly pattern-detection reviews. + +**Adoption.** Logging adds overhead. Programs that resist logging often discover later that the program's effectiveness has been declining for quarters and they cannot tell why because the data was not captured. The overhead of logging is small compared to the cost of running the program blind. + +--- + +## Failure 8: Inconsistent refresh attention + +**Symptom.** Some pieces always get refreshed; others never do. The pattern correlates with which writers prefer which topics, not with which pieces need refresh most. + +**Diagnosis.** The signal triage is informal and inconsistent. Pieces are getting attention because they are visible to certain people, not because they are most decayed. + +**Cure.** Formalize the audit so signal detection is data-driven rather than memory-driven. The matrix and the audit log force visibility on the whole library, not just on the pieces individual team members happen to think of. + +--- + +## Failure 9: Refresh-without-re-promotion + +**Symptom.** Refreshes ship. Modified dates update. The team waits for traffic recovery. Recovery is marginal at best. The team concludes refresh does not work. + +**Diagnosis.** Re-promotion was skipped. Search engines saw the modified date but audiences did not engage; the recovery curve that re-promotion typically produces did not happen. + +**Cure.** Build re-promotion into the workflow as a non-skippable step. Match re-promotion intensity to refresh depth (see `re-promotion-after-refresh.md`). The refresh is not "done" when published; the refresh is "done" when re-promotion has executed. + +--- + +## Failure 10: Audit without follow-through + +**Symptom.** The team runs the quarterly audit; produces a queue; the queue largely sits unworked; the next quarter's audit shows the same pieces in queue. + +**Diagnosis.** No owner-of-owners is keeping the queue moving. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +**Cure.** Assign an owner-of-owners role for the refresh program as a whole. Their job is queue movement, escalation of stalled refreshes, and program-level reporting. Without this role, even good audits do not produce execution. + +--- + +## Failure 11: Quarterly cadence too slow for sharp decay + +**Symptom.** The quarterly audit catches a piece in significant decay. The traffic loss has been accumulating for 75 days before the audit caught it. The recovery is harder because the decay has compounded. + +**Diagnosis.** Quarterly cadence alone is missing sharp decay. The lag between decay and detection is too long. + +**Cure.** Add continuous monitoring for traffic-decay and ranking-drop thresholds. Sharp decay alerts route to fast-track triage; the quarterly audit focuses on slower signals that continuous monitoring cannot detect (content drift, factual staleness, SERP intent shift). + +--- + +## Failure 12: Refresh in isolation when hub orchestration changed + +**Symptom.** Pieces are refreshed individually but the hub-level architecture also needed updating. The refreshes ship; the hub-level decay continues because the architecture problem was unaddressed. + +**Diagnosis.** Piece-level refresh is being done without coordination with hub-level architecture. Some refresh queues need to escalate to structural-redesign disposition rather than be addressed at piece level. + +**Cure.** Coordinate with `pillar-content-architecture` discipline. When piece-level refresh is bumping against architecture-level issues, escalate to a structural-redesign project. Some refresh attempts cannot succeed without the hub-level work. + +--- + +## Failure 13: Stalled refreshes accumulating + +**Symptom.** The refresh queue contains zombie items: pieces assigned months ago that have not shipped and are not progressing. Everyone knows they are stalled; nobody is removing them. + +**Diagnosis.** No stalled-refresh recovery process. Refreshes that get stuck stay stuck because there is no review mechanism to escalate or reassign. + +**Cure.** Build stalled-refresh review into each quarterly audit. Refreshes that have been in queue more than two cycles get reviewed: reassign owners, re-scope depth, or remove from queue if the disposition was wrong. The review prevents zombie accumulation. + +--- + +## Failure 14: Light-edit-as-default + +**Symptom.** Most refreshes are light edits regardless of signal strength. The light edits do not move the needle on pieces that needed substantial revision; the team concludes "refresh does not work" when the actual issue is depth mismatch. + +**Diagnosis.** Depth assignment is defaulting to light edit because light edits are the easiest to schedule. Substantial revision and full rewrite are being skipped because they are harder to fit into capacity. + +**Cure.** Match depth to signal strength explicitly. Depth-light when signals support light edit; depth-deeper when signals warrant. Capacity allocation should account for depth distribution; if the team consistently has capacity only for light edits, the allocation needs adjustment, not the depth assignment. + +--- + +## The cross-cutting pattern + +Most refresh failures share a single root: shortcuts in discipline. Calendar-refresh shortcuts the signal analysis. No-measurement shortcuts the learning. Refresh-as-default shortcuts the disposition decision. Light-edit-as-default shortcuts the depth decision. No-re-promotion shortcuts the audience-engagement work. Each shortcut feels like it is saving capacity; each shortcut is actually shifting capacity to lower-value work. + +The fix for almost any refresh failure is the same: surface the discipline that was being shortcutted, and pay the cost of running the discipline. The capacity recovered from eliminating low-value refreshes typically more than pays for the discipline overhead. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the discipline-as-cure observation. + +## Implementation choices that stay internal + +Specific tooling for stalled-refresh detection. Specific reporting templates for owner-of-owners updates. Specific reviewer training on disposition decisions. Specific automation that catches refresh-without-re-promotion. The team's own conventions for capacity recalibration when overcommitment is detected. These vary by team, tooling, and program structure. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md b/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md new file mode 100644 index 0000000..7e6d0d3 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md @@ -0,0 +1,150 @@ +# Effectiveness measurement + +Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. The discipline that prevents refresh-theater and turns the refresh program into a learning system. + +Refresh effectiveness measurement is the difference between a program that learns and a program that runs. Programs without measurement run the same patterns indefinitely, including the patterns that do not work; programs with measurement see which refreshes produce recovery, which do not, and what the patterns reveal about depth, signal interpretation, and disposition decisions. + +--- + +## Per-refresh tracking + +Each refresh is logged with the data needed to evaluate it. + +**The minimum log.** + +- **URL.** The refreshed piece. +- **Date shipped.** When the refresh published. +- **Signals that triggered the refresh.** Which of the five signal categories were active; signal severity. +- **Disposition.** Refresh, merge, delete (with target URLs for merge). +- **Depth.** Light edit, substantial revision, full rewrite, structural redesign. +- **Owner.** Who shipped the refresh. +- **Capacity spent.** Hours of editorial time invested. +- **Predicted outcome.** What the team expected the refresh to produce (recovery within X% in Y days, or qualitative expectation). +- **Actual outcome at 30 days.** Traffic, ranking, engagement metrics post-refresh vs pre-refresh. +- **Actual outcome at 90 days.** Same metrics extended to 90 days. +- **Notes.** Qualitative observations on what happened, surprising patterns, questions raised. + +**Why the minimum log.** Each field is load-bearing for pattern detection. Without signals, you cannot tell whether decay-driven refreshes recover differently from drift-driven refreshes. Without depth, you cannot tell whether full rewrites outperform substantial revisions. Without capacity, you cannot evaluate ROI. + +**The log as program memory.** Across years, the log becomes the program's accumulated learning. A team that has logged 200 refreshes can answer questions like "what is the typical recovery curve for substantial-revision refreshes on traffic-decayed pieces?" with data; a team without the log answers the same question with anecdote. + +--- + +## 30-day recovery measurement + +The first measurement window post-refresh. + +**What the 30-day window shows.** + +- **Schema and indexing recognition.** Search engines have crawled the updated piece and registered the modified date. +- **Initial ranking response.** Some ranking shifts happen within days as the search engine re-evaluates; others take longer. +- **Audience engagement spike.** Re-promotion produces traffic from newsletter, social, and syndication. The 30-day window captures the immediate engagement. +- **Quick wins or regressions.** If the refresh broke something (regressions in indexing, schema, or ranking), the 30-day window catches it. + +**What the 30-day window does not show.** + +- **Sustained recovery.** Initial spikes from re-promotion fade; the 30-day window cannot distinguish sustained recovery from re-promotion afterglow. +- **Algorithm-update response.** If an algorithm update happens after the refresh, the 30-day measurement may be confounded. +- **Long-tail keyword recovery.** Some long-tail rankings move slowly; the 30-day window may show only head-term response. + +**The 30-day pattern.** Most refreshes that will produce sustained recovery show some signal at 30 days: ranking improvement, traffic uptick, engagement spike. Refreshes that show no signal at 30 days are not necessarily failures, but they warrant attention; the 90-day measurement will resolve the question. + +--- + +## 90-day recovery measurement + +The longer-window measurement that confirms or refutes the 30-day signal. + +**What the 90-day window shows.** + +- **Sustained recovery.** Initial spikes have faded; what remains is the refresh's durable contribution. +- **Algorithm-update integration.** Most algorithm updates have been digested; the 90-day data reflects the new state. +- **Long-tail keyword response.** Slower-moving rankings have settled. +- **Engagement-based metrics.** Time on page, return visits, scroll depth post-refresh vs pre-refresh. + +**The 90-day pattern.** + +- **Strong recovery.** Traffic and rankings are above pre-refresh baseline by 20%+. The refresh worked. +- **Modest recovery.** Traffic and rankings are 5-20% above pre-refresh baseline. The refresh helped but did not produce dramatic improvement. +- **No recovery.** Traffic and rankings are within 5% of pre-refresh baseline. The refresh was not effective. +- **Regression.** Traffic or rankings are below pre-refresh baseline. The refresh damaged the piece. + +The 90-day measurement is the primary effectiveness measurement. The 30-day is the early-warning; the 90-day is the verdict. + +--- + +## Pattern detection across refreshes + +Individual refresh measurements are noisy. Patterns across refreshes are signal. + +**Patterns the log reveals.** + +- **Depth-effectiveness.** Are full rewrites producing better recovery than substantial revisions on similar signals? If yes, the team should consider deeper depth on similar future cases. +- **Signal-effectiveness.** Are traffic-decay refreshes recovering more reliably than content-drift refreshes? If yes, the program may benefit from prioritizing traffic-decay queue and being more selective about content-drift refresh. +- **Disposition-effectiveness.** Are pieces in the high-value-decaying quadrant recovering when refreshed, or are they continuing to decay? If continuing decay, the disposition may be wrong (merge or delete may have been better) or the underlying cause is structural (the topic is dying; competitors too strong). +- **Owner-effectiveness.** Are some owners producing better recovery than others on similar refreshes? Possibly skill differential, possibly capacity issues, possibly random variation that needs more data. +- **Topic-effectiveness.** Are refreshes on some topics recovering reliably while others do not? Some topics may be in structural decline; the program may need to reduce investment in those topics rather than increase refresh effort. + +**Pattern detection cadence.** Quarterly review of accumulated refresh data. Year-over-year reviews on multi-year programs. The patterns inform program-level decisions about allocation, prioritization, and disposition defaults. + +--- + +## The refresh-that-did-not-work review + +Refreshes that did not produce recovery are the program's most valuable learning data. + +**The review questions.** + +- **Was the depth wrong?** Did the refresh need more depth than was applied? Light edit when substantial revision was needed produces no recovery on substantial-decay signals. +- **Was the disposition wrong?** Should the piece have been merged or deleted instead of refreshed? Refreshing a piece that should have been merged produces ongoing decay because the underlying authority-splitting was not addressed. +- **Was the signal interpretation wrong?** Did the team read decay as content-drift when it was actually competitor-displacement? Refresh on the wrong cause does not produce recovery. +- **Is the topic in structural decline?** Some topics decline structurally; refresh cannot recover what the topic itself has lost. The right disposition may be to reduce investment in the topic and reallocate capacity. +- **Did re-promotion happen?** Refresh-without-re-promotion underperforms; some "did not work" cases are actually "did not get re-promoted." + +**The review output.** Each non-recovery refresh produces either: a re-disposition (try merge or delete), a depth re-attempt (next quarter try the deeper depth), or an acknowledgment that the topic is in decline and the program should reduce investment. + +**The review's program impact.** Without the review, non-recovery refreshes accumulate as silent program failures. With the review, the patterns surface and the program adjusts. + +--- + +## Effectiveness metrics by refresh purpose + +Different refresh purposes warrant different primary metrics. + +**Traffic-decay refreshes.** Primary metric: post-refresh traffic recovery vs pre-refresh baseline at 90 days. Secondary: ranking position recovery on target keywords. + +**Ranking-drop refreshes.** Primary metric: ranking position recovery on target keywords at 90 days. Secondary: traffic recovery (rankings without traffic recovery suggest CTR issues that ranking alone does not capture). + +**Factual-staleness refreshes.** Primary metric: less straightforward; the refresh's purpose is correctness, not recovery. Track that the staleness was caught before reader-detected errors compound. Secondary: any traffic recovery is bonus. + +**SERP-intent-shift refreshes.** Primary metric: ranking on target keywords (rankings reflect format-fit). Secondary: engagement metrics (the refresh changed format; does the new format engage better?). + +**Content-drift refreshes.** Primary metric: engagement metrics (time on page, return visits, conversions). Secondary: voice consistency review (qualitative; the refresh purpose was alignment with current brand positioning). + +The metric should match the purpose. Programs that measure every refresh by traffic recovery miss the value of refreshes whose purpose was correctness or alignment rather than recovery. + +--- + +## Common measurement failures + +**No measurement at all.** Refreshes ship; outcomes are not tracked; the program runs without learning. Each refresh is a fresh prediction with no accumulated evidence. + +**Measurement at the wrong window.** Measuring at 7 days captures only re-promotion afterglow; measuring at 6 months conflates many other variables. 30 and 90 days are the workable windows. + +**Single-metric measurement.** Measuring only traffic ignores ranking, engagement, and conversion metrics. Different refresh purposes warrant different metrics. + +**Measurement without context.** Comparing post-refresh metrics to pre-refresh metrics without accounting for seasonality, algorithm updates, or competitor activity produces noisy attribution. + +**No pattern detection.** Per-refresh measurement happens but never gets aggregated into pattern review; the program does not learn across refreshes. + +**No non-recovery review.** Successful refreshes get celebrated; failed refreshes get forgotten. The asymmetry hides the program's most valuable learning. + +--- + +## Methodology-level choices that stay in the public skill + +The minimum per-refresh log fields, the 30-day and 90-day measurement windows, the pattern-detection cadence, the refresh-that-did-not-work review, the metric-by-purpose mapping, the common measurement failures. + +## Implementation choices that stay internal + +Specific analytics dashboards that pull refresh metrics. Specific log structure in the team's project-management or content system. Specific seasonality models the team uses to baseline. Specific competitor-activity tracking that contextualizes attribution. Specific reviewer workflow for non-recovery refreshes. The team's own pattern-detection rituals. These vary by team, tooling, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md b/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md new file mode 100644 index 0000000..1f20605 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md @@ -0,0 +1,159 @@ +# Re-promotion after refresh + +Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. The patterns that signal a refresh to search engines and audiences. + +A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement that re-promotion produces. Programs that ship refreshes silently leave value on the table. + +--- + +## Signal to search engines + +What the search engine needs to see to recognize the refresh. + +**Modified-date in schema markup.** Schema.org Article (and related types) include a `dateModified` field. Update this when the refresh ships. Many CMS platforms update this automatically on save; verify the automation is working. Schemas with stale modified dates signal that the refresh is technical rather than substantive. + +**Visible modified-date on the page.** The page should display "Updated [date]" or similar visible signal. Some templates show "Published [date]" without an updated date; these should be updated to surface the refresh date. + +**Sitemap update.** The XML sitemap's `lastmod` field for the URL should reflect the refresh date. Most sitemap generators handle this automatically; verify after the refresh ships. + +**Search Console URL inspection and resubmission.** For high-priority refreshes, use Search Console's URL inspection tool and request indexing. This signals the refresh to the index without waiting for the next crawl. Use sparingly; bulk resubmission of every refresh can throttle. + +**Internal-link-graph signals.** When sister pieces add or update links to the refreshed piece, the additional internal-link signals reinforce that the URL is current and load-bearing. Refresh that updates internal linking from sister pieces sends stronger signals than refresh that does not. + +--- + +## Substantive vs cosmetic modifications + +Search engines distinguish between substantive content changes and cosmetic touch-ups. + +**Substantive changes.** Body content edits, section additions or removals, lede or closing rewrites, factual updates, restructuring. The refresh has changed what the piece says. + +**Cosmetic changes.** Date stamp updates without content changes. CSS or template changes. Whitespace edits. These do not constitute refresh; updating the modified date without substantive change is signaling a refresh that did not happen. + +**Why the distinction matters.** Search engines that detect the modified-date signal as cosmetic rather than substantive can devalue the signal. Programs that bump modified dates without substantive change to chase the refresh signal are running a tactic that has been increasingly detected and discounted. The honest signal is a real refresh; the tactic of date-bumping without change is short-lived value at best. + +**The audit.** Refreshes should produce diff'able content changes. If the refresh ships without diff'able changes, it is not a refresh. + +--- + +## Signal to audiences + +The other half of re-promotion: re-engaging the audiences who saw the original. + +**Newsletter re-share.** For pieces that originally went to the newsletter, a refreshed piece deserves a re-share. The framing is "we updated this with [specific updates]," not "here is a piece you may have seen before." Specificity earns re-engagement; vague re-shares feel like filler. + +**Social re-share.** For pieces that originally landed on social channels, the refresh is a social moment. New angle, new pull-quote, new visual, framing the refresh as the news the piece now carries. + +**Syndication partner update.** For pieces syndicated to partner platforms, the refresh may warrant communication with syndication partners about the updated version. Some partners pull the latest content automatically; some do not. The refresh communication closes the loop. + +**Email-list segmentation.** For programs with sophisticated email-list segmentation, refreshed pieces can be sent to segments that did not see the original or that engaged with the original and may benefit from the updated version. + +**Re-share cadence discipline.** Not every refresh deserves the same re-share intensity. Light edits typically do not warrant social re-share; substantial revisions or full rewrites do. Calibrate re-share to depth. + +--- + +## Internal linking refresh + +Pieces that link to the refreshed piece may benefit from anchor-text updates. + +**When anchor-text update fits.** The refreshed piece's positioning shifted, and the anchor text on sister pieces should now describe the piece differently. A piece that linked to the refreshed piece as "our guide to programmatic SEO" may now want to link as "our guide to programmatic SEO durability" if the refreshed piece's framing is now durability-focused. + +**When sister pieces should now link to the refreshed piece.** Some refreshes add coverage of topics that sister pieces discuss. Pieces discussing those topics that did not previously link to the refreshed piece may now warrant new internal links. + +**The internal-link-refresh pass.** Some programs run a quick pass after each substantial refresh: search the library for pieces mentioning the refreshed piece's topic, audit whether the existing anchor text and link presence are correct, update where warranted. + +**The over-linking failure.** Refreshes that trigger 30 internal-link updates across the library can create maintenance overhead disproportionate to value. The internal-link refresh should be targeted, not exhaustive. + +--- + +## URL preservation vs URL change + +Most refreshes preserve the URL. Some warrant URL change. + +**Preserve the URL when:** + +- The refresh is light edit, substantial revision, or most full rewrites. +- The existing URL has authority worth preserving (rankings, backlinks, internal-link references). +- The URL slug fits the refreshed piece's framing reasonably well even if not perfectly. + +**Change the URL when:** + +- The refresh is a structural redesign and the URL slug no longer fits. +- The piece is being merged with a sibling and the consolidated piece needs a new URL. +- The original URL was a structural mistake (wrong category, awkward slug) that the refresh is correcting. + +**The URL-change cost.** Even with 301 redirects, URL changes incur authority transfer cost; some authority does not survive the redirect. URL changes should be earned by structural rationale, not chosen for cosmetic reasons. + +**The URL-preservation discipline.** Most refreshes should preserve URLs. The default disposition is preserve; URL change is the exception requiring rationale. + +--- + +## The refresh that nobody told anyone about + +The pattern when re-promotion is skipped. + +**The symptom.** A refresh ships. Modified date updates. Schema validates. The piece sits in the library with the refresh complete on paper. Traffic recovers marginally if at all. The team concludes refresh does not work. + +**The actual cause.** Re-promotion was skipped. The refresh signaled to the search engine but did not signal to audiences. New-piece-style audience engagement (newsletter, social, syndication) did not happen. The refresh produced search-engine recognition without the audience-engagement spike that often drives broader recovery. + +**The cure.** Build re-promotion into the refresh workflow as a non-skippable step. The refresh is not "done" when the piece is published; the refresh is "done" when the re-promotion has been executed. Define re-promotion intensity per depth (light edit may need only modified-date and schema; substantial revision needs newsletter and social re-share; full rewrite needs full re-promotion treatment). + +--- + +## Re-promotion checklist by depth + +A short framework matching re-promotion to refresh depth. + +**Light edit re-promotion.** + +- Modified date in schema and visible. +- Sitemap lastmod. +- No audience re-share required for routine light edits. +- Internal-link audit only if specific anchor text changes warranted. + +**Substantial revision re-promotion.** + +- Modified date and visible date. +- Sitemap lastmod. +- Newsletter re-share with framing on what was updated. +- Social re-share to channels that originally promoted the piece. +- Internal-link audit on sister pieces with relevant topics. + +**Full rewrite re-promotion.** + +- All of the above. +- Search Console URL inspection and resubmission. +- Syndication partner update where applicable. +- Email-list segment send to engaged segments. +- Visual asset refresh for social and newsletter (new pull-quote graphics, new hero image if applicable). + +**Structural redesign re-promotion.** + +- All of the above. +- Coordination with the broader hub or category being redesigned (see `pillar-content-architecture`). +- Cross-piece internal-link audit across the affected hub or category. +- Possible launch communication if the redesign represents a major program milestone. + +--- + +## Re-promotion failure modes + +**Skipping re-promotion entirely.** The refresh produces marginal recovery; the team concludes refresh does not work; the program loses momentum. + +**Bulk-resubmitting every refresh URL to Search Console.** Search Console's URL submission has implicit rate limits; bulk submission of low-value refreshes throttles the team's submission capacity for the cases that warrant it. + +**Re-share without specificity.** "We refreshed this piece; here it is" lacks the specific framing that earns re-engagement. Specific framing ("we added the 2026 data and a new section on X") earns clicks; vague re-shares get ignored. + +**Anchor-text updates that proliferate.** Internal-link refresh that touches every mention of the topic across the library is over-investment. Target specifically; touch sparingly. + +**Modified-date bumping without content change.** The signal that gets discounted by search engines and signals to careful auditors that the team is gaming the metric rather than producing substantive refresh. + +--- + +## Methodology-level choices that stay in the public skill + +The signal-to-search-engine patterns, the substantive-vs-cosmetic distinction, the audience re-promotion patterns, the internal-link refresh discipline, the URL-preservation default, the re-promotion checklist by depth, the re-promotion failure modes. + +## Implementation choices that stay internal + +Specific schema markup automation in the team's CMS. Specific newsletter and social-publishing tooling and templates. Specific Search Console workflow conventions. Specific internal-link-audit automation. Specific syndication-partner communication channels. The team's own depth-to-re-promotion-intensity mappings. These vary by team, stack, and channel mix. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md new file mode 100644 index 0000000..4e55045 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md @@ -0,0 +1,174 @@ +# Refresh depth decision + +Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, the depth-creep anti-pattern. + +Refresh depth is one of the most consequential decisions in the program. The wrong depth produces predictable failure: light edits on pieces that needed substantial revision produce no recovery; full rewrites on pieces that only needed factual updates burn capacity. The discipline is matching depth to signal strength. + +--- + +## Depth 1: Light edit + +**The work.** Update statistics. Replace dead links. Fix factual errors. Swap dated examples. Update product or platform references. Verify external links still resolve and still go where they should. + +**Time investment.** 30-90 minutes per piece for typical pieces. Longer for research-heavy pieces with many external citations. + +**The piece's structure stays intact.** Section weights, lede, closing, archetype, voice, claims-and-arguments are all preserved. The light edit is surface maintenance. + +**Use when.** + +- Factual staleness is the only or dominant signal. +- Traffic is stable or only slightly decayed. +- The piece's structural framing still fits current SERP intent and brand positioning. +- The piece is performing well enough that significant changes would risk performance. + +**Common failures.** + +- Light-editing when substantial revision is warranted. Surface fixes do not address the structural reasons for decay; the piece continues to decay after the light edit ships. +- Light edits that touch more than they should. A "light edit" that becomes 4 hours of work because the editor kept finding things has lost the depth discipline; either commit to substantial revision or stop at the originally scoped scope. + +--- + +## Depth 2: Substantial revision + +**The work.** Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that have emerged since the piece was written. Restructure 1-3 H2 sections without redesigning the piece's overall shape. + +**Time investment.** 2-4 hours per piece for typical pieces. Longer for pieces with extensive new sections to add. + +**The piece's spine stays intact.** The archetype, the central thesis, and most sections survive. Specific sections are rewritten or added. + +**Use when.** + +- Traffic has decayed moderately but not catastrophically. +- Specific sections of the piece have aged badly (often the introduction, closing, or a section on a topic that has shifted). +- New topics have emerged that the piece needs to cover to stay current. +- The piece's structural framing is mostly fine but needs targeted updates. + +**Common failures.** + +- Substantial revision drifting into full rewrite. The "substantial revision" that becomes 8 hours of work has crossed into full-rewrite territory; either commit to full rewrite or scope back to the original substantial-revision plan. +- Substantial revision that rewrites the introduction without rewriting the closing, leaving the piece structurally inconsistent (the introduction promises one shape; the closing delivers a different one). +- Rewriting sections without auditing whether the rewrites match each other in voice and density. + +--- + +## Depth 3: Full rewrite + +**The work.** Keep the URL and topic; rewrite the piece end-to-end. New lede, new structure (possibly new archetype), new closing. The new piece occupies the old piece's URL and connects to the existing internal-link graph. + +**Time investment.** Similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. 8-16 hours for typical long-form rewrites. + +**The piece's spine changes.** New archetype possible. New positioning possible. The connection to the URL and the existing topical authority is what is being preserved; everything else can change. + +**Use when.** + +- Traffic has decayed sharply or persistently. +- The piece's structural framing no longer fits current SERP intent. +- The brand's positioning has shifted enough that the piece needs to be re-conceived. +- Light edit and substantial revision have already been tried and did not produce recovery. + +**Common failures.** + +- Full rewrite that loses what worked. The original piece had specific strengths (a memorable lede, a particular section that drew links). The rewrite that does not preserve those strengths can perform worse than the original even if the rewrite is technically stronger. +- Full rewrite that breaks internal linking. Section IDs change, anchor links from sister pieces break, the internal-link graph that supported the piece's authority is disrupted. +- Full rewrite that ignores the URL constraint. The team rewrites as if writing a new piece, then realizes the URL is locked and the new framing does not fit the existing slug. Either accept the slug mismatch (suboptimal) or change the URL (incurring redirect cost). + +--- + +## Depth 4: Structural redesign + +**The work.** Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Often part of a larger structural change in the content library: a hub being rebuilt, a category being consolidated, a topic cluster being reorganized. + +**Time investment.** A multi-piece project. 1-3 weeks for a hub-level restructure involving multiple pieces. + +**Multiple URLs and pieces are affected.** The piece being refreshed is one node in a graph that is being reshaped. + +**Use when.** + +- Refresh of an individual piece is bumping against architecture-level issues that cannot be addressed at the piece level. +- A hub is being redesigned and pieces within the hub need to be reconceived as part of the redesign. +- Multiple pieces are competing for the same query and a consolidated piece would produce stronger authority than any of the individual pieces. + +**Common failures.** + +- Treating structural redesign as a refresh exercise rather than as a project. The work scope is project-scope; treating it as a refresh queue item leads to under-resourcing. +- Structural redesign without coordination with `pillar-content-architecture` discipline. The hub-level work and the piece-level work need to compose; doing them separately produces friction. +- Redirect plans that do not account for all the URLs being consolidated. Some authority is lost in transit because some redirects were missed. + +--- + +## Signal-to-depth matching + +A short framework for choosing depth from the signals. + +**Light edit when:** + +- Factual staleness is the dominant signal. +- Traffic stable or only slightly decayed (under 10%). +- Rankings stable or only slightly drifted. +- No SERP intent shift detected. +- No content drift detected. + +**Substantial revision when:** + +- Multiple signal types present (factual + content drift, or traffic decay + ranking drops). +- Traffic decayed moderately (10-25%). +- Rankings drifted but still on page 1. +- Specific sections have aged badly while others are sound. +- SERP intent has not shifted dramatically. + +**Full rewrite when:** + +- Traffic decayed sharply (25%+). +- Rankings dropped from page 1 to page 2 or beyond. +- SERP intent has shifted substantially (the dominant SERP format has changed). +- Brand positioning has shifted enough that the piece reads as the brand-of-multiple-years-ago. +- Light edit or substantial revision already attempted without recovery. + +**Structural redesign when:** + +- The piece's issues are architecture-level rather than piece-level. +- A hub or category is being reorganized. +- Multiple sibling pieces are competing for the same query and consolidation would produce stronger authority. + +--- + +## The depth-creep anti-pattern + +Refreshes that grow during execution from their planned depth into a deeper depth that was not budgeted. + +**The pattern.** A refresh planned as a light edit becomes substantial revision because the editor "kept finding things." The substantial revision becomes a full rewrite because once you are restructuring two sections you might as well restructure the rest. The piece ships 6 weeks after planned, having consumed 4x the planned capacity. + +**Why it happens.** Editors and writers are pattern-matchers; once they start working on a piece, they see all its problems and want to fix all of them. The discipline of staying at the planned depth is not natural to editorial work. + +**The cure.** Two options. + +1. **Stop at scope.** When the editor finds work beyond the planned depth, log it but do not do it. The next quarter's audit can decide whether the piece needs deeper work; this refresh ships at the planned depth. +2. **Re-scope explicitly.** When the editor discovers the planned depth is wrong, halt the refresh and re-scope formally. The capacity allocation gets adjusted; the timing gets adjusted; the team is aware the refresh became a bigger project. + +The failure mode is the third option: keep going at deeper depth without explicit re-scoping. That produces capacity overruns and missed timelines that affect other work. + +--- + +## Multi-depth refresh sequences + +Some pieces benefit from a sequence of refreshes at different depths over time. + +**The pattern.** + +- Light edit ships first to address factual staleness while broader investigation continues. +- Substantial revision follows in the next quarter once SERP intent shift has been analyzed and the right structural changes are clear. +- Full rewrite follows in 2-3 quarters if the substantial revision did not produce recovery. + +**When this pattern fits.** High-value-decaying pieces where the right disposition is unclear and the team wants to avoid premature commitment to a full rewrite. Light-edit-first preserves what works while buying time for analysis. + +**When this pattern fails.** Programs that always start with light edit on high-value-decaying pieces, regardless of signal strength, because light edit is the easiest depth to schedule. The light edit does not move the needle, and the next quarter's audit shows the same piece in the same queue. + +--- + +## Methodology-level choices that stay in the public skill + +The four depth levels with their work, time investment, and use cases. The signal-to-depth matching framework. The depth-creep anti-pattern with its cure. The multi-depth refresh sequence pattern. + +## Implementation choices that stay internal + +Specific time-tracking that captures actual depth per refresh. Specific scope-confirmation tooling that flags depth-creep. Specific writer or editor assignment patterns by depth (some writers are stronger at light edits; some at full rewrites). Specific brief templates per depth in the team's writing system. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md new file mode 100644 index 0000000..9cee5bb --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md @@ -0,0 +1,154 @@ +# Refresh execution patterns + +Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. The execution patterns that turn audit queues into shipped refreshes. + +The audit produces a queue. The execution patterns turn the queue into shipped work. Programs that produce strong audits but weak execution end up with documentation of what should have been refreshed rather than refreshed pieces. + +--- + +## Single owner per refresh + +Each refresh has one owner accountable for shipping it. + +**The pattern.** When a refresh is assigned, one person is named as the owner. The owner runs the work end-to-end: confirming the depth, doing or coordinating the actual editorial work, running the QA gate, shipping, re-promoting, logging the outcome. + +**Why single ownership matters.** Refreshes that pass through multiple hands without a clear owner often get partially done and then stall. One person believes another is finishing the work; the work sits between them; the audit's next pass shows the piece still in queue. The accountability gap is the failure mode. + +**Owner selection.** Typically the writer or editor best matched to the topic. For light edits, the owner can be anyone with capacity; for substantial revision and full rewrite, ownership matches expertise. For structural redesign, ownership often sits with a content lead because the work spans multiple pieces. + +**Owner-of-owners.** A single person owns the refresh program as a whole. Their job is keeping the queue moving, escalating stalled refreshes, ensuring effectiveness measurement is happening, and reporting on the program's health to leadership. Without this role, the program drifts even if individual refreshes have owners. + +--- + +## Editorial-workflow integration + +Refreshes typically run through the same editorial workflow as new pieces, scaled to the chosen depth. + +**Light edit workflow.** May skip the brief and go straight to edit. The editor pulls the piece, identifies the specific updates, makes them, runs a QA pass, and ships. 30-90 minutes of editorial time; minimal coordination. + +**Substantial revision workflow.** Brief, draft, edit, QA gate, publish. The brief covers the targeted sections being rewritten; the draft is partial-rewrite; the edit and QA gate match new-piece discipline. 2-4 hours of editorial time; coordination similar to a short blog post. + +**Full rewrite workflow.** Brief, draft, edit, QA gate, publish. Full new-piece workflow with the additional constraint of preserving the URL and existing internal-link integration. 8-16 hours of editorial time; coordination at long-form-piece scale. + +**Structural redesign workflow.** Project-scope coordination. Multiple briefs, multiple drafts, redirect plans, internal-link audits. Multi-week timeline; coordination at flagship-project scale. + +The integration discipline. Refreshes are not a separate workflow; they plug into the existing editorial workflow at the appropriate depth. Teams that build a parallel refresh workflow create coordination overhead and quality drift; teams that integrate refresh into the standard workflow benefit from the workflow's existing discipline. + +--- + +## Capacity allocation + +Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff. + +**Allocation patterns.** + +- **Newer libraries (under 100 pieces, under 2 years old):** 5-15% of capacity to refresh. Most pieces are still relatively current; signals are limited. +- **Mid-stage libraries (100-500 pieces, 2-5 years old):** 15-30% of capacity to refresh. Decay rates have built up; high-value-decaying queue is meaningful. +- **Mature libraries (500+ pieces, 5+ years old):** 25-40% of capacity to refresh. Cumulative decay is significant; without sustained refresh capacity, the library erodes. + +**The capacity-vs-new-production tradeoff.** + +A team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. Or 8 to refresh, 12 to new. The split affects program shape: heavy-refresh programs preserve existing equity; heavy-new-production programs build new topical authority. + +**Right-sizing the allocation.** + +- If refresh queues are growing quarter-over-quarter, allocation is too low. +- If new-production output is dropping or the team complains of refresh fatigue, allocation may be too high. +- If high-value-decaying pieces stay in queue across multiple audits, allocation is misallocated (volume of work, not allocation share, may be the issue, but allocation review is the first step). + +**The capacity audit.** Quarterly, review the actual refresh time spent vs the planned allocation. Programs that consistently exceed their allocation are signaling that the queue's growth rate exceeds the allocation; either grow allocation, narrow the prioritization, or accept slower queue cycle times. + +--- + +## Batching vs integration + +Two patterns for how refresh work fits into the cadence. + +**Batching.** Dedicated weeks or sprints for refresh work. The team blocks 1-2 weeks per quarter for concentrated refresh execution. + +- **Strength.** Focus. The team is in refresh mode; context-switching costs are low; throughput on refresh work is high. +- **Weakness.** Interrupts new production. New-piece workflows pause during refresh sprints; pieces in the new-production pipeline stall. +- **Fits.** Mid-stage libraries with manageable refresh queues; teams that prefer focused work blocks; programs with predictable seasonality where new production has natural pauses. + +**Integration.** One refresh per week (or similar steady cadence) integrated into the regular production cadence. + +- **Strength.** Sustains new production. New-piece work continues without pauses. +- **Weakness.** Slower refresh velocity per piece; context-switching costs are higher; refresh work can get deprioritized in favor of "more urgent" new-piece work. +- **Fits.** Mature libraries with continuous refresh queues; teams that prefer sustained pacing; programs where new production has tight commitments. + +**Hybrid.** A baseline integration cadence plus periodic batching for the high-priority queue. + +- **Strength.** Sustained refresh on lower-priority work; periodic concentration on high-value-decaying queues. +- **Weakness.** Coordination overhead; the team manages both modes. +- **Fits.** Mature programs with sophisticated capacity planning. + +The discipline. Pick a pattern. The failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence and a queue that never clears. + +--- + +## The refresh that needs to happen now + +Some refreshes cannot wait for the next allocation slot. + +**Trigger conditions.** + +- Sharp decay (40%+ traffic loss in 30 days) on a high-value piece. +- Algorithm-update fallout affecting a high-value piece. +- Factual error producing reputational risk. +- Broken page state (indexing failure, schema regression, redirect loop). + +**The fast-track pattern.** + +- Continuous monitoring detects the issue. +- The owner-of-owners decides whether the issue warrants fast-track. +- Fast-track refreshes get pulled out of the queue and shipped within days. +- The refresh skips some workflow steps if necessary (briefer brief, faster QA) but does not skip the QA gate; pieces that ship without QA produce regressions that compound. + +**Fast-track capacity.** Teams need a small reserve for fast-track work. The reserve is typically 5-10% of total capacity. Without reserve, fast-track work pushes other work out and produces cascade delays. + +--- + +## Stalled refresh recovery + +Refreshes that have been in queue for more than two audit cycles need intervention. + +**Common causes.** + +- Owner is over-committed; the refresh is not the highest priority on their plate. +- The refresh's depth was wrong (planned as light edit, actually needed substantial revision); the owner stalled rather than escalate. +- The refresh's disposition was wrong (planned as refresh, should have been merge); the owner is uncertain how to proceed. + +**The recovery pattern.** + +- Owner-of-owners reviews stalled refreshes at each audit. +- Reassign owners where capacity is the issue. +- Re-scope where depth was wrong; re-disposition where the disposition was wrong. +- For refreshes stalled because the analysis revealed a deeper issue, escalate to a content lead for decision. + +The stalled-refresh review prevents the queue from accumulating zombie items that everyone knows are not getting done but nobody is removing. + +--- + +## Common execution failures + +**No single owner.** Refreshes are assigned to "the team"; nobody is accountable; the refresh stalls. + +**Workflow shortcuts.** The refresh skips the QA gate or the brief. Quality drifts; regressions compound. + +**Capacity overcommitment.** The team plans 20% capacity for refresh; actual refresh work consumes 35%; new production suffers; team burns out. + +**Refresh queue without owner-of-owners.** The queue grows; nobody is reporting on its health; the program drifts toward set-and-forget within the formal-program shape. + +**Fast-track without reserve.** Urgent refreshes push planned work out; cascade delays affect downstream pieces. + +**Stalled refreshes accumulating.** The queue has zombie items in it; the queue's reported health does not match the queue's actual state. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner discipline, editorial-workflow integration shapes by depth, capacity allocation patterns by library stage, batching vs integration vs hybrid tradeoffs, the refresh-that-needs-to-happen-now pattern, the stalled-refresh recovery pattern. + +## Implementation choices that stay internal + +Specific project-management tooling for the refresh queue. Specific notification systems for refresh assignments. Specific time-tracking for capacity audits. Specific reserves and fast-track triage workflows. The team's own conventions for owner reassignment. These vary by team, tooling, and program shape. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md new file mode 100644 index 0000000..8b4649b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md @@ -0,0 +1,148 @@ +# Refresh prioritization matrix + +The 2x2 prioritization matrix with quadrant strategies. The discipline of NOT refreshing the high-value-stable quadrant. The under-recognized failure of treating low-value-decaying as automatic refresh candidates. + +Most libraries have more pieces showing signals than the team has capacity to refresh. Without prioritization, refresh work happens on the cheapest pieces or the most visible pieces, leaving high-value-decaying pieces in the backlog while editorial capacity goes to pieces that would not have produced recovery worth the effort. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. + +--- + +## The two axes + +**Piece value.** A composite of business value, traffic value, and strategic role. + +- **Business value.** Pieces that drive conversions, qualified leads, or specific business outcomes. Sometimes measurable directly (pieces that close a defined funnel step), sometimes attributed (pieces that influence subsequent conversions). +- **Traffic value.** Pieces that drive meaningful organic traffic, especially on commercial-intent keywords or topical-authority-building queries. +- **Strategic role.** Pieces that anchor a hub, that establish the brand's POV on a flagship topic, or that earn external citations and links. Strategic role can outweigh raw traffic; a 500-traffic flagship piece is high-value if it is the canonical statement of the brand's position. + +Pieces are classified as high-value (HV) or low-value (LV). The line between HV and LV is judgment-driven; teams typically settle the criteria by establishing tiers (top 10% by value, next 30%, bottom 60%, or similar). + +**Traffic state.** A composite of recent and trending traffic. + +- **Stable.** Traffic over the last 90 days is within 10-15% of the prior 90-day baseline, accounting for seasonality. +- **Decaying.** Traffic over the last 90 days is down meaningfully (15%+ beyond seasonal baseline), or trending consistently down over multiple quarters. + +Pieces are classified as stable or decaying. The classification is the easier of the two axes because traffic data is cleanly measurable. + +--- + +## Quadrant 1: High-value, decaying + +**Top priority.** + +**The pieces.** Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. + +**The strategy.** Refresh first; the traffic loss compounds and the lost equity is hard to recover. These pieces are usually worth substantial-revision or full-rewrite refresh depth because the value at stake justifies the work. + +**The disposition decision.** Almost always refresh. Merge candidates in this quadrant exist (a high-value piece that is decaying because a sister piece is competing for the same query) but are uncommon. Delete is essentially never the right disposition for a high-value piece. + +**Capacity allocation.** This quadrant gets the largest share of refresh capacity. Many programs allocate 60-70% of total refresh capacity to high-value-decaying pieces. + +**Expected outcomes.** Recovery measured at 30 and 90 days. Strong refreshes on this quadrant typically produce 20-50% traffic recovery within 90 days; full rewrites can produce more. + +**Common failures.** + +- Treating this quadrant as "save for later" because the work is heavy. The traffic loss continues during the delay. +- Light-editing high-value-decaying pieces when substantial revision is warranted. The light edit does not move the needle and the team concludes refresh does not work. +- Not investigating the cause. A piece that is decaying because a competitor published a better resource needs different work than a piece decaying because of SERP intent shift. + +--- + +## Quadrant 2: High-value, stable + +**Monitor; do not refresh proactively.** + +**The pieces.** Pieces that are performing strongly and showing no decay signals. + +**The strategy.** Leave alone. Refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. Pieces that are working should not be touched without clear signal. + +**The disposition decision.** No action; monitor through continuous monitoring for emerging decay; review at quarterly audits for content drift signals. + +**The discipline.** This is the quadrant that calendar-refresh programs damage most. A piece ranking position 2 with stable traffic gets refreshed because it is the next piece in the rotation; the refresh introduces minor changes that shift the SERP signals; ranking drops to position 5; traffic drops 30%. The refresh that was meant as maintenance was actually destruction. + +**When to revisit.** Monitor for emerging signals. If traffic starts decaying or rankings drop, the piece moves to high-value-decaying. If content drift becomes pronounced (the piece is performing but the team sees positioning misalignment), substantial revision may be warranted but only if the team is willing to risk the performance. + +**Common failures.** + +- Refresh-on-calendar damaging stable pieces. +- Treating stable rankings as a refresh target because the team wants to "improve" the piece. Improvement on stable pieces is a high-risk operation. +- Touching the URL, schema, or core copy of a stable piece without strong rationale. + +--- + +## Quadrant 3: Low-value, decaying + +**Audit for merge or delete.** + +**The pieces.** Pieces with low traffic that are decaying further. Pieces that never had strong demand and are now losing what little they had. + +**The strategy.** The default disposition is NOT refresh. Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. The actual disposition is usually merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling or relevant hub). + +**The disposition decision.** + +- **Merge** when a sibling piece on a related topic is performing better and could absorb the failing piece's content. Merging consolidates authority and produces a stronger consolidated piece. The merged URLs redirect to the survivor. +- **Delete** when no merge candidate exists, the topic is not load-bearing for the program, and the piece's residual value (small as it is) does not justify maintenance. Delete and redirect to the closest sibling piece or hub. +- **Refresh** is occasionally warranted: when the piece has clear strategic role (anchors a small but important sub-topic) and the decay is recoverable. Rare in this quadrant. + +**Capacity allocation.** This quadrant gets the smallest share of refresh capacity but a meaningful share of disposition work (merges and deletes are real work, less than full rewrites but more than light edits). + +**Common failures.** + +- Refreshing pieces in this quadrant by default. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. +- Skipping the merge analysis. Pieces that should have been merged get refreshed in isolation, leaving the authority-splitting problem intact. +- Avoiding deletes because deleting feels destructive. Maintaining a library of low-value pieces forever costs ongoing audit attention and dilutes overall library quality. + +--- + +## Quadrant 4: Low-value, stable + +**Leave alone.** + +**The pieces.** Pieces with low traffic that are not actively decaying. They are at the floor. + +**The strategy.** Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +**The disposition decision.** No action. Pieces that have been low-traffic-stable for multiple audits are candidates for batch consideration: do they collectively represent a topic that is no longer load-bearing for the program? If yes, a structural decision (delete the topic cluster, merge into a hub, archive) may be warranted at program level. If no, leave alone. + +**When the strategy fails.** If a low-value-stable piece starts decaying further (moves to low-value-decaying), the disposition is reconsidered. Usually merge or delete. + +**Common failures.** + +- Refresh-on-calendar touching this quadrant. Pure capacity waste. +- Treating low-traffic as a problem to be solved. Low traffic on a low-value piece is the right outcome; not every piece needs to drive significant traffic. Some pieces serve narrow but real strategic roles at low volume. + +--- + +## Capacity allocation by quadrant + +A typical refresh program's capacity might split as: + +- **High-value, decaying:** 60-70% of refresh capacity. The largest share, on the highest-value work. +- **Low-value, decaying:** 15-20% of capacity, mostly on merge and delete dispositions, occasional refresh on strategically important pieces. +- **High-value, stable:** 5-10% of capacity, on the rare cases where content drift warrants substantial revision despite stable performance. +- **Low-value, stable:** 0-5% of capacity. Mostly batch reviews to identify topic-level decisions. + +The allocation varies by library age and decay rates. Newer libraries with limited decay have less work in the decaying quadrants and may invest more in continuous-monitoring infrastructure. Older libraries with significant decay have more work to do across quadrants. + +--- + +## Common matrix failures + +**The "every piece is high-value" trap.** Teams that classify too many pieces as high-value lose the prioritization signal. A library where 60% of pieces are "high-value" is essentially unprioritized; the matrix fails to discriminate. + +**The traffic-only value classification.** Classifying value purely by traffic misses strategic-role pieces that have lower traffic but high importance. A flagship manifesto that earns 800 visits a month but drives external citations and brand recognition is high-value despite lower traffic. + +**The "refresh = recovery" assumption.** Some pieces in the high-value-decaying quadrant cannot be recovered through refresh. The topic is genuinely declining; competitors are too strong; SERP intent has shifted away from any format the brand can produce. The matrix prioritizes refresh; it does not promise refresh will work. The effectiveness measurement (see `effectiveness-measurement.md`) catches the cases where refresh is not producing recovery. + +**Static classification.** Value and traffic state both shift over time. A piece in low-value-stable that suddenly draws traffic from an emerging keyword moves to high-value-stable; a piece in high-value-decaying that fully recovers moves to high-value-stable. The matrix is not a one-time classification; it is the framework run at each audit. + +--- + +## Methodology-level choices that stay in the public skill + +The two axes (value, traffic state), the four quadrants with strategies, the capacity allocation guidance, the common matrix failures, the dynamic-classification discipline. + +## Implementation choices that stay internal + +Specific value-classification rubrics the team uses (revenue attribution models, strategic-role tagging, traffic-tier definitions). Specific scripts that classify pieces into quadrants from data pulls. Specific dashboards that visualize the matrix at audit time. The team's own conventions for high-value-stable refresh decisions when content drift is pronounced. These vary by team, business model, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md new file mode 100644 index 0000000..bddf11b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md @@ -0,0 +1,164 @@ +# Refresh signals checklist + +Five signal categories that trigger refresh consideration, with detection patterns and the audit shape that surfaces signals across the library. + +Pieces that show no signals do not need refresh. Pieces that show one or two signals warrant attention. Pieces that show three or more signals are typically in active decay and should be high in the prioritization queue. The signal taxonomy below is what distinguishes triaged refresh from calendar refresh. + +--- + +## Signal 1: Traffic decay + +Organic traffic to the piece is trending down over a 90+ day window beyond seasonal baseline. + +**Detection patterns.** + +- Pull traffic data per URL over rolling 90-day windows. +- Compare current 90 days to prior 90 days, accounting for known seasonality. +- A drop of more than 15-20% beyond seasonality on a piece that previously had stable traffic is a real signal. +- A drop of more than 40% in a 30-day window is a sharp signal warranting urgent review. + +**What the signal usually means.** + +- **Slow decay (5-10% over a year):** content drift. The piece is gradually losing relevance as the topic evolves or the brand's voice shifts. +- **Moderate decay (15-30% in a quarter):** ranking position drift, or SERP intent shifting, or competitor publication. +- **Sharp decay (40%+ in a month):** algorithm update, indexing issue, dramatic SERP intent shift, or technical regression on the URL. + +**Diagnostic next steps.** When traffic decay is detected, check ranking positions for the piece's target keywords (signal 2 may also be active), check for technical issues (indexability, page speed, broken redirects), and check the SERP for intent shift (signal 4). + +**Anti-patterns in detection.** + +- Comparing month-over-month rather than 90-day windows over-attributes seasonal noise to decay. +- Ignoring known seasonality (holiday traffic, B2B dropping in late December) produces false positives. +- Looking only at total traffic instead of organic specifically blurs the signal with referral or paid changes. + +--- + +## Signal 2: Ranking drops + +The piece is losing position on its target keywords. + +**Detection patterns.** + +- Track each piece's primary 3-10 target keywords with rank tracking. +- Drops from page 1 to page 2-3 are particularly consequential because click-through rates fall sharply at the page-1-to-page-2 boundary. +- Drops within page 1 (position 3 to position 7) reduce clicks but are less existential. +- Persistent drops over 30+ days are real shifts; week-over-week volatility within a few positions is normal. + +**What the signal usually means.** + +- A piece that was at position 3 and is now at position 8 has been displaced by stronger competing pieces. The displacement is informative; review what is now ranking and what those pieces have that this piece does not. +- A piece that was at position 5 and is now at position 35 has likely been algorithm-affected, indexing-affected, or technically regressed. Investigate before refresh; refreshing a piece with an indexing issue does not solve the indexing issue. +- Drops on long-tail keywords with simultaneous gains on broader head terms can indicate the piece's focus has broadened beneficially. Not always a refresh signal. + +**Diagnostic next steps.** Pull the SERP for each target keyword. Examine what is ranking. Identify whether the new rankings are stronger pieces (refresh signal: improve the piece) or different SERP intent (signal 4: SERP intent shift, possibly different format needed). + +**Anti-patterns in detection.** + +- Treating any rank movement as a refresh signal produces refresh-on-noise; require persistence over 30+ days. +- Tracking only branded keywords misses the meaningful organic ranking signal. +- Ignoring keyword cannibalization (multiple pieces competing for same keyword) treats split rankings as a refresh signal when the actual disposition is merge. + +--- + +## Signal 3: Factual staleness + +The piece contains statistics, references, examples, or claims that are dated. + +**Detection patterns.** + +- Annual review of statistics in the piece. Any stat older than 3 years on a fast-moving topic is a candidate for staleness flagging. +- Reference checks for defunct products, platforms, services, or companies named in the piece. +- Example checks for examples that have aged poorly (a 2019 case study of a company that has since gone bankrupt or changed direction). +- Framing checks for claims that no longer match current reality ("AI is starting to influence search" in 2026 is anachronistic). + +**What the signal usually means.** + +- Factual staleness alone is often a light-edit signal: update the stats, replace dead links, swap dated examples. The piece's structure may be sound. +- Factual staleness combined with traffic decay or ranking drops is a stronger signal that the piece's broader framing has aged, not just the surface details. +- Factual staleness on a flagship piece is more urgent than on a low-traffic piece because flagship pieces are read by more people who notice the staleness. + +**Diagnostic next steps.** List the specific stale facts, references, and examples. Estimate the light-edit time required to refresh them. If the structural framing is also stale, the depth required is substantial revision rather than light edit. + +**Anti-patterns in detection.** + +- Treating every old stat as stale when the stat may still be current (some stats genuinely have not changed in 3 years) produces unnecessary refresh. +- Ignoring framing-level staleness while updating individual stats produces pieces that are technically current in stats but feel old in voice. + +--- + +## Signal 4: SERP intent shift + +The dominant SERP format for the target keyword has changed. + +**Detection patterns.** + +- Pull the current SERP for each target keyword. What format is dominating? Articles? Listicles? Videos? Product comparisons? AI overviews? +- Compare to the piece's format. If the piece is an article and the SERP wants product comparisons, intent has shifted. +- Watch for new SERP features that did not exist when the piece was written: AI overviews, generative answers, knowledge panels, featured-snippet shifts. + +**What the signal usually means.** + +- The piece may still rank but increasingly for the wrong reasons. Click-through rates fall as the SERP signals the piece is not the dominant intent match. +- The piece may need format restructuring (full rewrite or substantial revision rather than light edit) to fit the new dominant intent. +- Sometimes the right disposition is to write a NEW piece in the new dominant format and either consolidate the old piece into it or keep the old piece for the residual intent it still serves. + +**Diagnostic next steps.** Read the top-ranking pieces for the target keyword. What format are they? What questions do they answer that the piece does not? Decide whether refresh in the new format will recover the position, or whether a new piece in the new format is the better disposition. + +**Anti-patterns in detection.** + +- Ignoring AI-overview presence on the SERP. AI overviews change click-through rates substantially and may indicate the piece needs restructuring for AI search citation. +- Assuming SERP intent is stable. Some keywords have stable intent for years; others shift quarterly. The audit should be active. + +--- + +## Signal 5: Content drift + +The piece's positioning no longer matches the brand's current positioning. + +**Detection patterns.** + +- The piece's voice reads as the brand-of-three-years-ago. Vocabulary, tone, level of conviction. +- The piece's POV on the topic has not kept up with how the brand now thinks. The brand has sharpened a position the piece treats with old hedging. +- The piece's framing fits the audience the brand had then, not the audience the brand has now. +- The piece's calls-to-action, internal linking, and product references reflect older brand offerings that have since changed. + +**What the signal usually means.** + +- Content drift is internal signal. Readers may not consciously notice, but the team will, and over time the library's voice incoherence weakens the brand. +- Content drift is often paired with the team's discomfort about which pieces in the library represent the brand best when sharing externally. +- Content drift is rarely the sole driver of a refresh decision (because traffic and rankings may be fine), but it determines depth: a content-drift refresh is usually substantial revision or full rewrite, not light edit. + +**Diagnostic next steps.** Identify which sections drift hardest from current positioning. If drift is concentrated in introduction, closing, and CTAs, substantial revision can address it. If drift is throughout, full rewrite is the cleaner disposition. + +**Anti-patterns in detection.** + +- Treating every voice evolution as drift triggers calendar refresh of pieces that are still serving readers. +- Ignoring drift because the piece is performing in search produces a library that performs but no longer represents the brand. + +--- + +## The library audit + +Running the signal taxonomy across the whole library. + +**Audit shape.** + +- Pull a per-URL data set: traffic over time, rankings, last-modified date, target keywords, business-value tag (high/medium/low). +- For each URL, run the five signal checks. Mark each signal as present or absent. +- Pieces with zero signals: stable; no action. +- Pieces with one or two signals: candidate queue; review individually for disposition. +- Pieces with three or more signals: active-decay queue; high priority for disposition decision. + +**Output.** A spreadsheet or database of pieces with their signals and the resulting disposition (refresh, merge, delete, monitor). The output feeds the prioritization matrix and the refresh queue. + +**Cadence.** Full audit quarterly. Continuous monitoring for traffic-decay and ranking-drop signals; manual signal checks (factual staleness, SERP intent shift, content drift) at quarterly cadence. + +--- + +## Methodology-level choices that stay in the public skill + +The five signal categories with detection patterns and what each signal means; the audit shape across the library; the cadence; the anti-patterns in detection. The signal-to-disposition mapping that informs prioritization. + +## Implementation choices that stay internal + +Specific data pulls from the team's analytics platform. Specific rank-tracking thresholds. Specific automation that runs continuous monitoring. Specific reviewer dashboards that surface signals. Specific seasonality models the team uses to baseline traffic. The team's own tags for business-value classification. These vary by team, tooling, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md new file mode 100644 index 0000000..e1b242b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md @@ -0,0 +1,137 @@ +# Refresh vs merge vs delete + +The disposition decision. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged or deleted. + +Most refresh programs default to refresh as the disposition. The default is wrong. Some pieces should be merged into stronger siblings; some should be deleted and redirected. The disposition decision is upstream of the depth decision: a piece getting deleted does not need depth, and a piece being merged is doing a different kind of work than refresh. + +--- + +## Refresh + +The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +**Criteria for refresh disposition.** + +- The piece has demonstrated demand: it draws meaningful traffic now or did historically. +- The topic is one the brand wants to own; the piece's existence is strategically warranted. +- A path to recovery exists: refresh of the right depth has a reasonable chance of producing improvement. +- No sister piece is competing for the same query in a way that splits authority. +- The piece's URL has accumulated authority worth preserving. + +**When refresh fits but might not.** + +- Sometimes a refresh-eligible piece is also a merge candidate. A high-value-decaying piece that is decaying because a sister piece is stronger may produce more value through merge than through refresh of either piece alone. +- Sometimes refresh has been tried and did not produce recovery. The first failed refresh shifts disposition consideration toward merge or full-rewrite-with-new-positioning rather than another refresh attempt. + +**Refresh failure modes.** + +- Refreshing pieces that are not recoverable. The topic is dying; the brand cannot win against the competition; the SERP intent has shifted to a format the brand does not produce. Refresh in these cases is theater. +- Refreshing without resolving the underlying issue. If a piece is decaying because a sister piece is competing for the same query, refresh of the original piece does not solve the cannibalization. Both pieces continue to underperform. + +--- + +## Merge + +Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +**Criteria for merge disposition.** + +- Two or more pieces target the same primary query or a closely overlapping query cluster. +- Combined authority across the pieces is meaningful; merging would produce a piece with stronger authority than any individual piece has. +- The pieces' coverage overlaps enough that consolidation produces a coherent piece, not a Frankenstein of mismatched sections. +- The team can identify which URL the survivor occupies (typically the one with strongest existing authority) and which URLs redirect to the survivor. + +**The merge decision in detail.** + +- **Identify the survivor URL.** Usually the URL with strongest existing rankings, traffic, and backlinks. The survivor inherits the consolidated content; other URLs redirect to it. +- **Plan the consolidated content.** Outline the merged piece. Decide which sections come from which source piece. Plan the gaps where new content will fill what neither piece had. +- **Author the consolidated piece.** Write or rewrite as needed. The consolidated piece is usually stronger than any of the source pieces because it is built from the strongest components plus targeted new content. +- **Implement redirects.** 301 redirects from the merged URLs to the survivor. Redirects need to be implemented at publish time, not after; the merged URLs going to 404 or 410 produces traffic loss that did not need to happen. +- **Update internal links.** Pieces that linked to the merged URLs should be updated to link to the survivor. + +**Merge failure modes.** + +- Merging without redirects. The merged URLs go to 404; the consolidated authority does not transfer; traffic is lost. +- Merging pieces that did not actually compete. If two pieces target different intents, merging them produces a piece that does neither well. +- Frankenstein merges. The consolidated piece reads as multiple pieces stitched together rather than as a unified piece. Cure: rewrite the consolidated piece as a piece in its own right, using the source pieces as input rather than as components. + +--- + +## Delete + +The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. + +**Criteria for delete disposition.** + +- The piece draws minimal traffic and has minimal residual authority. +- The topic is not load-bearing for the program; the brand does not need to own it. +- No merge candidate exists; the piece's content does not consolidate cleanly into any stronger piece. +- Maintaining the piece costs ongoing audit attention without proportional return. + +**The delete decision in detail.** + +- **Identify the redirect target.** The deleted URL should redirect to the closest sibling piece, or to the relevant hub or category page, or to the homepage if no other target fits. Deleting without redirect (returning 404 or 410) is correct only when the piece's residual authority is genuinely zero, which is rare. +- **Implement the redirect.** 301 redirect to the chosen target. +- **Update internal links.** Pieces that linked to the deleted URL should be updated to link to the redirect target directly. The redirect chain still works but direct links are cleaner. +- **Document the deletion.** The audit log should capture the delete decision, the rationale, and the redirect target. Future audits can reference the log if a question arises about the URL. + +**Delete failure modes.** + +- Avoiding delete because deleting feels destructive. The library accumulates low-value pieces forever, costing ongoing audit attention and diluting overall library quality. +- Delete without redirect. The URL returns 404; whatever residual authority existed is lost; users who linked to the URL or bookmarked it find a dead link. +- Delete of pieces that should have been merged. The piece's content had value the team did not recognize; merging would have preserved it. Delete is appropriate when no merge candidate exists, not as the easy path to avoid the merge analysis. + +--- + +## The disposition decision flow + +A short framework for choosing. + +1. **Does the piece have demonstrated demand?** Traffic, rankings, conversions, or strategic role. If yes, continue. If no, the disposition is likely delete (or merge if there is a candidate). +2. **Is there a sibling piece competing for the same query?** If yes, evaluate merge. The merged piece has a strong chance of outperforming both original pieces. +3. **Is the topic load-bearing for the brand?** If no, refresh disposition is unlikely to be the right answer; consider merge into a stronger sibling or delete. +4. **Has refresh been tried recently without recovery?** If yes, the next disposition should be merge or full-rewrite-with-new-positioning, not another refresh attempt. +5. **What is the cheapest disposition that addresses the actual problem?** Refresh is often defaulted to because it feels less destructive; merge and delete are sometimes the cheaper paths to the actual outcome. + +--- + +## The under-recognized failure: refreshing what should have been merged or deleted + +The pattern that costs refresh programs the most capacity. + +**How it shows up.** The team spends 4 hours refreshing a low-value-decaying piece that even at its best will not draw meaningful traffic. The refresh ships. The piece ranks slightly better for two weeks, then drifts back down. Three months later the piece is in the same audit queue. + +**Why it happens.** + +- Refresh feels less destructive than merge or delete. +- The merge analysis takes time; refresh feels like the immediate action. +- Delete requires team agreement; refresh can be done by a single owner. +- The team has not internalized that some pieces should not be refreshed. + +**The cure.** Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. The audit is not "which pieces to refresh"; it is "what disposition each piece should get." Refresh becomes one option among several rather than the default. + +**The capacity recovery.** Programs that adopt the merge-and-delete-as-first-class-dispositions discipline typically recover 20-40% of refresh capacity for higher-value work. The pieces that were getting refreshed but should have been merged or deleted stop consuming capacity; the freed capacity goes to high-value-decaying pieces that produce real recovery. + +--- + +## Disposition decisions that need approval + +Some dispositions are higher-risk than others and warrant approval beyond the audit owner. + +**Delete dispositions.** Always need approval. Deletes are essentially irreversible without significant work to undelete; the redirect strategy is consequential; the team should be aligned on the decision. + +**Merge dispositions involving high-value pieces.** Need approval. Merging into a survivor URL means the non-survivor URLs lose their identity. If the non-survivor pieces had high-value characteristics, the merge needs review. + +**Refresh dispositions on stable high-value pieces.** Need approval. Touching a stable high-value piece is a high-risk operation; the audit owner should not unilaterally decide to refresh. + +**Light edit and substantial revision on decaying pieces.** Usually do not need approval beyond the audit owner. The risk-reward is straightforward. + +--- + +## Methodology-level choices that stay in the public skill + +The three dispositions and their criteria, the disposition decision flow, the under-recognized failure of refreshing what should have been merged or deleted, the merge and delete mechanics, the dispositions that need approval. + +## Implementation choices that stay internal + +Specific redirect implementation in the team's CMS or hosting layer. Specific internal-link update automation that catches links to merged or deleted URLs. Specific approval workflows for high-risk dispositions. Specific audit-log templates that capture disposition rationale. These vary by team, tooling, and CMS. diff --git a/dist/pi/.agents/skills/content-repurposing/SKILL.md b/dist/pi/.agents/skills/content-repurposing/SKILL.md new file mode 100644 index 0000000..be7ced8 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/SKILL.md @@ -0,0 +1,298 @@ +--- +name: content-repurposing +description: "Cross-format content adaptation. Turning one substantial piece into many derivative formats (blog series, email sequences, social posts, webinars, podcasts, video shorts) without losing the original's value or producing AI-slop variants. The discipline of adaptation per medium rather than mass-blast distribution. Triggers on content repurposing, content adaptation, cross-format content, content atomization, content multiplication, content distribution across formats, source-piece-to-derivative, video shorts from blog, email from whitepaper, podcast from article, blog series from research. Also triggers when a flagship piece is shipping but the team has not planned how to extend it across formats, when repurposing is happening but the derivatives feel mass-produced, or when AI-assisted repurposing is producing slop variants of strong source pieces." +category: content +catalog_summary: "Cross-format content adaptation: one piece becomes many (blog series, email, social, webinar, podcast, video) with per-format adaptation rather than mass-blast that ignores medium constraints" +display_order: 11 +--- + +# Content Repurposing + +A senior editorial leader's playbook for cross-format content adaptation. The discipline of turning one substantial piece into many derivative formats without losing the original's value or producing slop variants. + +Most content programs underspend on repurposing. A flagship piece costs 40-80 hours to produce; the program publishes it once, shares it on three channels, and moves on. The same piece could have produced a blog series, an email sequence, a webinar, a podcast episode, a dozen social posts, video shorts, and FAQ extractions for AI search visibility. The work to extend the source piece across formats is small relative to the value extracted; programs that skip repurposing leave most of the value unrealized. + +The failure mode in the other direction is mass-blast: the same content reposted across channels without adaptation. A blog post pasted into LinkedIn as a long-text post; the email newsletter is the blog's first three paragraphs with "read more" tacked on; the YouTube video is a slideshow of the article text read aloud. Mass-blast respects neither the medium nor the audience. AI-assisted repurposing has made mass-blast cheap; the result is a wave of derivative content that performs poorly across every channel because it was adapted to none of them. + +This skill is the discipline of adaptation per medium. Each format has constraints, conventions, and reader expectations the source piece does not have. Repurposing that respects those constraints produces work that earns engagement on the new format; repurposing that ignores them produces filler. + +When to use this skill: planning the extension of a flagship piece across formats, auditing a repurposing pipeline that is producing low-engagement derivatives, calibrating an AI-assisted repurposing workflow that is producing slop, or designing the cross-format adaptation conventions for a content program. + +--- + +## What this skill is for + +This skill spans cross-format adaptation work after a source piece has been produced. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes the original piece in any single format. +- **`content-repurposing` (this skill)** turns one piece INTO many formats. +- `content-distribution` gets content TO audiences via channels. +- `editorial-qa` verifies pre-publish, including derivatives. +- `ai-content-collaboration` is the workflow layer; AI participation rules apply within repurposing. + +The distinction from `content-distribution` is load-bearing. Distribution is channel work: getting content to audiences via the right channels. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running multi-format programs, agencies producing derivative content for clients, anyone planning to extend a flagship piece across formats. + +What is not in scope: the original piece's production (covered by `content-and-copy` and the long-form skills), the channels themselves (covered by `content-distribution`), the editorial QA on derivatives (covered by `editorial-qa`). + +--- + +## One-and-done vs mass-blast vs adapt-by-format + +The keystone framing. + +**One-and-done.** Publish once on the source format; never reuse. The piece took 60 hours to produce; it generates traffic for 90 days; it gets shared three times; it goes silent. The team treats publication as the end of the piece's life. Output: most of the source piece's value goes unrealized; the team is always producing new flagship work because old flagship work is not being extended. + +**Mass-blast.** Same content reposted across channels without adaptation. Blog post text pasted into LinkedIn as a long post. Email newsletter is the blog's first three paragraphs. The YouTube version is a slideshow of the text read by AI voice. Output: low engagement on every channel because nothing was adapted to any channel's conventions. Audiences perceive the cross-channel sameness as low-effort filler. AI-assisted repurposing has made this pattern cheap and common. + +**Adapt-by-format.** Per-medium adaptation that respects each format's constraints and conventions. The blog series breaks the source piece into chapters with new ledes and closings per chapter. The email sequence builds on the source's framework with sender-voice adjustments. Social posts use platform-native conventions. The webinar adds Q&A and live elements. Output: each derivative earns engagement on its medium because it was made for that medium; the source piece's value compounds across formats. + +The litmus test. Read each derivative as if you had not seen the source piece. Does it stand on its own? Does it use the medium's conventions? Would it earn engagement if it were the only thing the audience saw of this work? If yes to all three, the adaptation succeeded. If the derivative reads as "I should have read the original instead," the adaptation failed. + +--- + +## Source-piece selection + +Not every piece is worth repurposing. Selection is the first discipline. + +**Strong source-piece characteristics.** + +- The source has a clear central argument or framework that travels across formats. +- The source has standalone sections, examples, or sub-arguments that work as derivative pieces. +- The source's audience overlaps with the audiences on the target formats. +- The source's voice is distinctive enough that derivative voice can stay coherent. +- The source has accumulated demand: traffic, links, mentions, social shares. + +**Weak source-piece characteristics.** + +- The source is a tightly-integrated argument where every section depends on context. +- The source is a list-style piece where the items do not have standalone weight. +- The source's value depended on being read end-to-end (a narrative arc, a layered argument with payoff). +- The source's audience does not exist on most target formats. +- The source's voice is generic; derivative voice has nothing to anchor. + +**The selection audit.** Run candidate pieces through these questions before committing to repurposing. Pieces that fail the audit may still be valuable but as one-and-done; programs that try to repurpose unsuitable pieces produce derivatives that feel forced. + +Detail in [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md). + +--- + +## Format adaptation patterns + +Eight common source-to-derivative adaptations with worked examples. + +**Long-form to blog series.** A 6,000-word whitepaper becomes 4-6 standalone blog posts, each developing one of the whitepaper's sub-arguments with new ledes and closings. + +**Blog post to email sequence.** A 1,500-word blog post on a multi-step framework becomes a 5-email sequence, one email per step, with sender-voice adaptation and per-email engagement hooks. + +**Whitepaper to webinar.** Substantive whitepaper becomes a 30-45 minute webinar with the whitepaper's framework as the spine, plus live Q&A, plus interactive elements that print do not support. + +**Long-form to social posts.** Pull-quote-style posts, framework summaries, key-question posts, contrarian-claim posts. Each social post is one moment from the source, framed for the platform's conventions. + +**Article to podcast episode.** Article becomes the episode's spine; the host adds context, examples, and conversational elaboration; sometimes a guest interview drives the episode while the article is the show notes. + +**Long-form to video shorts.** 60-90 second video clips on individual claims, examples, or framework elements from the source. Each short is a standalone unit; series-of-shorts can extend the source over weeks of social posting. + +**Research report to FAQ extractions.** Specific Q&A extractions from the source piece, formatted for AI search citation and snippet capture. + +**Multi-piece source to ebook.** Several related pieces (blog posts, articles, even social threads) consolidated into an ebook, with new connective tissue, an introduction that frames the body, and a conclusion that synthesizes. + +Detail in [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md). + +--- + +## Per-format constraints + +Each medium demands and forbids specific things. Repurposing that ignores the constraints produces derivatives that fail the medium. + +**Email.** + +- Subject line and preheader bear most of the engagement load. +- Plain prose paragraphs work; complex formatting often breaks across email clients. +- Length tolerance varies by audience; 200-800 words common. +- Single clear CTA per email; multiple competing CTAs underperform. + +**Social posts (text-driven platforms).** + +- Hook in the first 1-2 lines; readers decide to expand or scroll. +- Platform-specific conventions (LinkedIn long-post structure differs from X/Twitter thread structure). +- Visual or quote-graphic options to break up text. +- One specific point per post; multi-point posts dilute. + +**Video (long-form).** + +- Pacing differs from print; spoken delivery requires different sentence structure. +- Visuals carry information print does not need; talking-head video alone for 30+ minutes underperforms. +- Audio quality matters more than video quality up to a point; bad audio kills retention. + +**Video (short-form).** + +- 60-90 second window for most platforms; 15-30 seconds for some. +- Captions essential; many viewers watch without sound. +- Hook in the first 1-2 seconds; algorithmic recommendation rewards retention from second 1. +- One specific point or moment per short. + +**Podcast.** + +- Spoken-language sentence structure; print-style sentences read aloud sound stilted. +- Conversational pacing rewards examples and asides; tightly-argued print sections feel stiff. +- Show notes do the print work the audio cannot; treat show notes as a derivative format too. + +**Webinar.** + +- Live element: Q&A, polls, interactive moments. Static webinar is a video; interactive webinar earns the format. +- Slide design matters; text-heavy slides fail. +- Length: 30-60 minutes typical; longer requires high engagement design. + +Detail in [`references/per-format-constraints.md`](references/per-format-constraints.md). + +--- + +## Voice consistency across formats + +The source piece's voice anchors the derivatives. The discipline is staying recognizable through the format shifts. + +**What stays constant.** + +- The brand's POV on the topic. +- Distinctive vocabulary, specific framings, recognizable phrasings. +- The level of conviction or hedging the brand uses. +- The audience-respect register (talking up to, down to, alongside the audience). + +**What adapts per format.** + +- Sentence length and structure (spoken voice differs from written). +- Density (visual formats can carry less per minute than text). +- Conversational vs declarative register (podcasts are conversational; whitepapers declarative). +- Direct-address frequency ("you" usage varies by format). + +**The voice audit per derivative.** Read or watch the derivative. Does it sound like the brand? Could a reader who knows the source piece tell the derivative is from the same source? If voice has drifted to AI-default or to the platform's default register, the adaptation lost the voice. + +**The AI-repurposing voice problem.** AI-assisted repurposing is particularly prone to voice drift. The source piece may have specific voice characteristics; AI generation of derivatives without strong voice prompts produces derivatives that sound more generic than the source. See `ai-content-collaboration` for the voice-preservation discipline that applies to repurposing workflows. + +Detail in [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md). + +--- + +## Sequencing and cadence + +When to release derivatives relative to the source, and at what pace. + +**Sequencing patterns.** + +- **Source-first, derivatives following.** Source publishes; derivatives roll out over the following 2-12 weeks. The source carries authority; derivatives extend reach. +- **Derivatives-first, source as anchor.** Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship. Less common; works for built-up audiences who follow the program. +- **Simultaneous launch.** Source and a wave of derivatives publish on the same day. Maximum splash; risks audience fatigue if every channel is firing the same day. + +**Cadence within the rollout.** + +- **Concentrated.** Most derivatives ship within 4-6 weeks of source. Maximum momentum from the source's authority; minimum time for individual derivatives to land. +- **Distributed.** Derivatives ship over 3-6 months. Each derivative has space to land; the program is extracting value over a longer window; risks losing connection to source if the gap grows too long. +- **Indefinite.** Derivatives keep being created from the source as long as the source remains relevant. Common for evergreen flagship pieces; rare otherwise. + +**The pacing audit.** Match cadence to the source's traffic curve. Pieces with sharp early traffic (trending topics) benefit from concentrated rollout; pieces with sustained evergreen traffic can support distributed rollout over many months. + +Detail in [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md). + +--- + +## Cross-promotion across derivatives + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. + +**Linking patterns.** + +- **Derivative back to source.** Each derivative includes a link or reference to the source piece for readers who want depth. The source's traffic compounds. +- **Source forward to derivatives.** The source piece is updated to include links to derivatives as they ship. The source becomes the hub for the cross-format extension. +- **Derivatives across.** Where appropriate, derivatives link to other derivatives in the cross-format set. The series feeling helps audiences engage with multiple pieces. + +**Attribution within derivatives.** When a derivative is clearly drawn from a source piece, acknowledge: "This is adapted from our recent piece on X." Attribution earns reader trust; uncredited derivatives can feel like the same work being recycled without acknowledgment. + +**Co-promotion across channels.** A blog post derivative can be re-shared on social where the original blog post was; a social post derivative can be promoted in the email newsletter. Cross-channel flow extends each derivative's reach. + +Detail in [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md). + +--- + +## Repurposing for AI search visibility + +A specific repurposing pattern worth its own treatment. + +**FAQ extraction.** Pull specific question-answer pairs from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries that can be cited by AI search engines. + +**Snippet design.** Identify standalone paragraphs in the source that answer specific queries cleanly. These paragraphs can be quoted, schema-marked, and presented in derivative pieces or in dedicated FAQ pages. + +**Statistic extractions.** AI engines weight statistics with named sources. Extract specific stats from the source (with citations to the underlying primary research) into format that AI can cite cleanly. + +**Definition and entity extractions.** Source pieces often define specific terms or describe specific entities authoritatively. Extract these as standalone definitions in glossaries, FAQ pages, or knowledge-base entries. + +**The AI-search-derivative discipline.** Treat AI-search optimization as a derivative format with its own conventions: specific question framings, named-source citations, standalone-paragraph design. Pieces that do this well earn AI citations; pieces that do not still get cited but at lower rates and with less control over framing. + +Detail in [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md). + +- "Our derivatives feel like AI slop." Mass-blast pattern; AI-assisted repurposing without per-format adaptation. Cure: add adaptation discipline, voice prompts, per-format review. +- "We repurposed but engagement is low." Format constraints ignored. Cure: audit each derivative against per-format conventions. +- "The blog post derivative outperforms the source." Either the source was the wrong format for the topic (the derivative format fits better), or the derivative cannibalizes the source. Investigate. +- "We never reuse pieces." One-and-done pattern; the program is leaving 70-90% of source-piece value unrealized. +- "Our LinkedIn posts are blog-post text dumps." Mass-blast on a platform with specific conventions. Cure: rewrite for platform-native structure. +- "The email newsletter is the blog's first paragraphs with 'read more' tacked on." Mass-blast email pattern. Cure: rewrite as a standalone email with engagement hooks. +- "Our podcast episodes are articles read aloud." Print-to-audio without spoken-language adaptation. Cure: rewrite for spoken delivery; add conversational pacing. +- "We extracted FAQ pages but they are not getting cited by AI search." Format may be wrong (snippets not standalone) or content may not be authoritative enough; audit against AI-search norms. +- "Our voice drifts across derivatives." AI-repurposing voice failure. Cure: stronger voice prompts; per-derivative voice audit. +- "We launched 12 derivatives in a week and audiences were exhausted." Concentrated cadence too aggressive. Cure: distributed cadence with engagement-driven sequencing. +- "Our derivatives compete with the source for the same query." Cannibalization. Cure: clear primary-keyword assignment per piece; consolidate or restructure. + +--- + +## The framework: 12 considerations for content repurposing + +When designing or auditing a repurposing program, walk these 12 considerations. + +1. **Adapt-by-format, not mass-blast or one-and-done.** Each derivative respects its medium. +2. **Source-piece selection.** Strong sources have travelable arguments and standalone sections. +3. **Format adaptation patterns chosen.** Match source-piece characteristics to derivative formats. +4. **Per-format constraints respected.** Each medium's conventions, length norms, and reader expectations. +5. **Voice consistency across formats.** Brand POV stays; sentence structure adapts. +6. **Sequencing and cadence planned.** Source-first vs simultaneous; concentrated vs distributed. +7. **Cross-promotion across derivatives.** Linking, attribution, co-promotion. +8. **AI-search extraction.** FAQ, snippet, statistic, entity extractions designed deliberately. +9. **Cannibalization avoided.** Derivatives complement the source; do not compete for the same query. +10. **Engagement-per-format measured.** Derivatives evaluated on each medium's metrics. +11. **AI-assisted repurposing with voice discipline.** Voice prompts, per-derivative review, slop prevention. +12. **Capacity allocation explicit.** Repurposing is real work; budgeted, not done in the cracks. + +The output of the framework is a repurposing program that turns each strong source piece into a coherent multi-format extension, with each derivative earning engagement on its medium. + +--- + +## Reference files + +- [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md) - Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. +- [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md) - Eight source-to-derivative adaptations with worked examples. Long-form to blog series, blog to email, whitepaper to webinar, etc. +- [`references/per-format-constraints.md`](references/per-format-constraints.md) - What each medium demands and forbids. Email, social, video, podcast, webinar, AI search. Length norms, conventions, hooks. +- [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md) - What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem. +- [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md) - Source-first vs simultaneous vs derivative-first. Concentrated vs distributed cadence. Pacing audits. +- [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md) - Linking patterns, attribution, co-promotion across channels. +- [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md) - FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. +- [`references/repurposing-pipeline-templates.md`](references/repurposing-pipeline-templates.md) - Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. +- [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: adaptation is craft, not duplication + +Repurposing is widely treated as a content multiplication problem to be solved with AI: feed the source into a tool, get derivatives out. The output of that approach is mass-blast, slop, and audiences that learn to ignore the program. The teams producing repurposing that earns engagement are the ones treating each derivative as a piece in its own right, adapted for its medium, written with the source's voice but the format's craft. + +Adaptation is craft, not duplication. The source piece is the starting material; the derivative is its own work. Programs that hold this discipline get value compounding across formats; programs that skip it produce a wall of derivative content that performs worse, not better, than publishing only the source. + +When in doubt about whether a repurposing program is ready, ask: does each derivative respect its medium's conventions, does voice stay consistent across the set, are derivatives cross-promoting and linking back to the source, is AI-search extraction part of the plan, is cannibalization being managed, is the cadence pacing earning engagement? If yes to all of those, the program is real. If no to any, the gap is where the derivatives will read as filler and audiences will tune out. diff --git a/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md new file mode 100644 index 0000000..3ec2330 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md @@ -0,0 +1,205 @@ +# AEO extraction patterns + +FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. The repurposing pattern that turns long-form content into AI-search-ready derivatives. + +AI search engines (the citation-driven generative answer engines) cite content in specific shapes. Pieces that are designed for citation get cited at higher rates and with better framing control; pieces that are not designed for citation still get cited but at lower rates and with less control over how the citation appears. + +The AEO (answer engine optimization) extraction is its own derivative format with its own conventions. Treating it as a derivative is the discipline. + +--- + +## The AEO extraction frame + +AI engines retrieve and cite content paragraph-by-paragraph or snippet-by-snippet. They favor content that: + +- Has standalone meaning (the snippet works without surrounding context). +- Cites named sources within the snippet (specific authority). +- Uses specific phrasings (queryable framings). +- Has structural signals (FAQ schema, headings, lists where appropriate). + +Source pieces written without these properties may have the same content but in shapes the engines do not cite cleanly. AEO extraction restructures the content into citation-ready shape. + +--- + +## Pattern 1: FAQ extraction + +The most common AEO extraction pattern. + +**The shape.** Specific question-answer pairs derived from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries. + +**Question framing.** + +- Use phrasings users actually search. "What is X?" "How does X work?" "Why does X matter?" "When should I use X?" +- Avoid phrasings users do not search. "What are the considerations around X?" rarely matches search intent. +- Specific is better than generic. "How long should a B2B sales email be?" performs better than "What length should sales emails be?" + +**Answer framing.** + +- Standalone meaning. The answer works as a paragraph; no pronoun references that depend on outside context. +- Named source within the answer where applicable. "According to a 2025 Forrester study, B2B sales emails between 75 and 150 words have the highest reply rates" performs better than "Studies show shorter emails work better." +- Specific framings, not hedged. "The strongest length is 75-150 words" performs better than "Generally, shorter tends to be better." +- Length: 40-80 words typical. Longer answers get truncated or cited partially; shorter answers may not have enough substance to cite. + +**Where the FAQ lives.** + +- A dedicated FAQ section at the bottom of the source piece, schema-marked with FAQPage. +- A standalone FAQ page that aggregates multiple FAQs across topics, deeply linked to source pieces. +- Inline within the source piece as a callout box, surfacing the Q&A while the surrounding prose develops the topic. + +--- + +## Pattern 2: Snippet design + +Standalone paragraphs in the source piece designed to be citation-ready. + +**The shape.** A paragraph (100-200 words typical) that answers a specific query cleanly and can be cited as a unit. + +**Snippet framing.** + +- Opens with a specific claim or definition. Snippets that open with throat-clearing rarely get cited cleanly. +- Includes named source citations where the claims need authority. +- Uses specific framings. "B2B sales emails between 75 and 150 words have a 32% reply rate, compared to 18% for emails over 250 words" is citation-ready; "shorter emails tend to do better" is not. +- Stands alone. The paragraph's meaning does not depend on the prior or following paragraphs. + +**Where snippets live.** + +- Throughout the source piece as load-bearing paragraphs that incidentally meet snippet criteria. +- As deliberately-designed snippets in specific positions (often after each H2 question for AEO-optimized pieces; see `editorial-qa`'s SEO/AEO compliance for the answer-paragraph discipline). +- As standalone snippets in derivative pieces (FAQ pages, glossaries, knowledge-base entries). + +--- + +## Pattern 3: Statistic extractions + +AI engines weight statistics with named sources at high citation rates. + +**The shape.** Specific statistic with named source, framed for citation. + +**Statistic framing.** + +- The number is specific. "32% of B2B buyers" performs better than "around a third of buyers." +- The source is named. "According to the 2025 Salesforce State of Marketing report" performs better than "according to a recent study." +- The context is clear. "Among B2B SaaS buyers in the $50M-500M revenue band" rather than just "among buyers." +- The currency is specified. The stat's date matters for AI engines deciding which sources to cite as current. + +**Where statistic extractions live.** + +- Throughout the source piece where data supports claims. +- In dedicated "key statistics" callouts that schema-mark the stats. +- As standalone tweet-graphic-style social derivatives (the stat on its own with the source citation). +- In FAQ-style answers that frame "what does the data say about X?" + +**The citation-laundering avoidance.** Statistic extractions that cite secondary sources (other content marketing pieces) rather than primary sources reduce citation rates. AI engines increasingly detect citation laundering and discount it. + +--- + +## Pattern 4: Definition and entity extractions + +Source pieces often define specific terms or describe specific entities authoritatively. + +**The shape.** Standalone definitions or entity descriptions that can serve as canonical references. + +**Definition framing.** + +- "X is [definition], typically [characterization], distinguished from [related concept] by [distinction]." +- 50-150 words for substantive definitions. +- Specific authority signals: who developed the concept, when, in what context. + +**Entity framing.** + +- For products, companies, frameworks: who, what, when, why, where used. +- Specific dates, named people, named organizations. +- Source attribution where the entity claim depends on authority. + +**Where definition and entity extractions live.** + +- Glossary pages. Many programs underuse glossaries; they are AI-search valuable real estate. +- Knowledge-base entries. +- Schema-marked definitions within source pieces (Article schema with appropriate sub-types). +- Wikipedia and similar entity authorities where the entity is significant enough to warrant external listings (different from on-property AEO but related; AI engines weight cross-source consistency). + +--- + +## Pattern 5: Comparison extractions + +Source pieces that compare options, frameworks, or approaches produce comparison-extraction derivatives. + +**The shape.** Side-by-side or table comparisons with specific axes, citation-ready. + +**Comparison framing.** + +- Defined axes (price, feature set, fit, scale). +- Specific values per axis per option. +- Tradeoff summary that AI can quote. +- Recommendation framing where the source piece commits a position. + +**Where comparison extractions live.** + +- Tables within the source piece, schema-marked where appropriate. +- Standalone comparison pages. +- FAQ-style answers framing "How does X compare to Y?" +- Decision-guide derivatives that walk readers through the comparison. + +--- + +## Pattern 6: How-to extractions + +Source pieces with sequential instructions produce how-to extractions. + +**The shape.** Step-by-step instructions that AI can cite as a procedure. + +**How-to framing.** + +- Numbered steps in a clear sequence. +- Each step is a complete instruction (not "do this, then that" run together). +- Schema-marked with HowTo where the source is an instructional piece. + +**Where how-to extractions live.** + +- Within source pieces as schema-marked procedures. +- Standalone how-to pages on specific tasks. +- Tutorial derivatives in video format. + +--- + +## AEO extraction failures + +**Generic FAQs.** Questions that do not match user search phrasings get little citation. Cure: query research; phrase questions in user voice. + +**Context-dependent answers.** Answers that reference "this approach" or "the method described above" do not cite cleanly. Cure: each answer is rewritten to stand alone with full context. + +**Hedged answers.** "Generally, in some cases, depending on context, X might work" rarely gets cited. AI engines prefer specific framings. Cure: where the source piece is genuinely uncertain, scope the answer to the specific case where the answer is specific. + +**Missing schema.** FAQs and snippets without schema markup do not signal cleanly to engines. Cure: add appropriate schema (FAQPage, HowTo, Article) where formats fit. + +**No source citations within answers.** Statistics and specific claims without named sources within the answer paragraph get cited at lower rates. Cure: include source citations within the answer body, not just in surrounding context. + +**Citation laundering.** FAQs citing other content marketing pieces rather than primary sources. Cure: trace claims to primary sources; cite the primary. + +**Over-extraction.** Producing 50 FAQs from a 5,000-word source piece dilutes; not every question deserves a standalone FAQ. Cure: extract the 10-15 highest-value questions; let the rest live within the source's prose. + +--- + +## AEO extraction integration with the cross-format set + +AEO extractions integrate with other derivatives. + +**FAQ pages link to the source.** The FAQ page is a derivative; the source piece is the canonical version. Cross-promotion follows the standard pattern. + +**Statistic extractions appear in social posts.** Each stat with its source citation can become a social post (often with quote-graphic visual treatment). + +**Definition extractions appear in glossaries that the source piece links to.** The glossary entry serves as the canonical definition for the term across the program. + +**Comparison extractions appear in decision-guide derivatives.** The comparison from the source becomes the spine of a separate decision-guide piece. + +**The integration discipline.** AEO extraction is one derivative type among several; the cross-format set's coordination includes the AEO extractions, not as a separate workflow but as part of the rollout plan. + +--- + +## Methodology-level choices that stay in the public skill + +The six AEO extraction patterns, the question/answer/snippet framing principles, the schema markup integration, the AEO extraction failures, the integration with the broader cross-format set. + +## Implementation choices that stay internal + +Specific schema markup automation. Specific FAQ-page templates in the team's CMS. Specific glossary-page architecture. Specific statistic-extraction tooling. Specific monitoring of AI citation rates per piece. The team's own conventions for FAQ length within the bands. These vary by team, CMS, and AI-citation tracking infrastructure. diff --git a/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md b/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md new file mode 100644 index 0000000..63412eb --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md @@ -0,0 +1,175 @@ +# Common repurposing failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most repurposing failures share a single root, which is treating repurposing as content multiplication rather than as cross-format craft. + +--- + +## Failure 1: Mass-blast (same content reposted across channels) + +**Symptom.** Blog post text pasted into LinkedIn as a long post. Email is the blog's first three paragraphs with "read more." YouTube version is a slideshow of the article text read aloud. + +**Diagnosis.** Repurposing without per-format adaptation. The team is treating "more channels" as the goal rather than treating each derivative as a piece adapted for its medium. + +**Cure.** Apply the per-format constraints discipline (see `per-format-constraints.md`). Each derivative gets rewritten for the target format. AI-assisted repurposing without strong format prompts produces this failure; the cure includes voice prompts and per-format instructions. + +--- + +## Failure 2: AI-slop derivatives + +**Symptom.** Derivatives feel like AI slop. Generic, derivative, signal-less. Voice has drifted from the source. + +**Diagnosis.** AI-assisted repurposing without voice discipline. AI generation regresses to model defaults; multiple derivatives generated without voice anchor compound the drift. + +**Cure.** Apply the voice-consistency-across-formats discipline (see `voice-consistency-across-formats.md`). Voice prompts including sample text from the source. Per-derivative voice review. Reject the bland; rewrite generic sentences in voice. See also `ai-content-collaboration` for the broader voice-preservation discipline. + +--- + +## Failure 3: One-and-done + +**Symptom.** Source pieces publish; never get repurposed. The team produces new flagship work continuously while older flagship work sits unused. + +**Diagnosis.** No repurposing discipline; the team treats publication as the end of the piece's life. Most of the source-piece value goes unrealized. + +**Cure.** Establish source-piece tiering (see `source-piece-selection-criteria.md`). Tier 1 and Tier 2 pieces get cross-format extension plans at production time. Capacity allocation for repurposing becomes a real budget line. + +--- + +## Failure 4: Repurposing the wrong pieces + +**Symptom.** Repurposing capacity goes to pieces that resist extension. The derivatives feel forced; engagement is low. + +**Diagnosis.** Source-piece selection is choosing pieces by availability rather than by suitability. Pieces with tightly-integrated arguments, list-style structure, or no demand signal are being repurposed when they should stay one-and-done. + +**Cure.** Apply the selection audit. Run candidates through the strong vs weak source-piece characteristics. Some pieces stay one-and-done; that is the right disposition for them. + +--- + +## Failure 5: Format constraints ignored + +**Symptom.** Derivatives feel awkward on their target formats. Engagement is low. Audiences scroll past or unsubscribe. + +**Diagnosis.** Each medium has constraints; the derivatives violate them. LinkedIn long posts as walls of text; emails as image-only layouts; podcasts as articles read aloud. + +**Cure.** Apply the per-format constraints discipline. Each format has demand-and-forbid lists. Derivatives must respect them, even at cost of departing from the source's surface. + +--- + +## Failure 6: Derivative outperforms source (cannibalization) + +**Symptom.** A blog-post derivative outperforms the source whitepaper for the source's target keyword. Authority is splitting between the two pieces. + +**Diagnosis.** Either the source was the wrong format for the topic (the derivative format fits SERP intent better), or the derivative is targeting the same keyword as the source and cannibalizing. + +**Cure.** Two options. If the source was the wrong format, consider whether the derivative should become the canonical piece (with the source decommissioned or repositioned). If the derivative is cannibalizing, reassign primary keywords: the source keeps the high-value head term; the derivative gets a long-tail variant. + +--- + +## Failure 7: Voice drift across the cross-format set + +**Symptom.** Each derivative is fine alone but the cross-format set reads as voice variants. Audiences who follow the program notice the inconsistency. + +**Diagnosis.** Multiple writers or AI generators produced derivatives without voice coordination. Voice drifted across producers. + +**Cure.** Single voice owner across the cross-format set. Voice library with examples. Calibration sessions where multiple writers reconcile voice expectations. AI tools include the same voice prompts across all derivative generations. + +--- + +## Failure 8: Cadence too aggressive + +**Symptom.** Cross-format set ships a wave of 12 derivatives in one week. Audiences disengage by day 3. Most derivatives produce minimal engagement. + +**Diagnosis.** Concentrated cadence too tight for the audience attention rhythm. The cross-format presence on a single week exhausts rather than reinforces. + +**Cure.** Apply the sequencing-and-cadence discipline. Match cadence to source's traffic curve and audience attention norms. Most cross-format sets benefit from concentrated-but-not-collapsed pacing (4-6 weeks rather than 1 week). + +--- + +## Failure 9: No cross-promotion + +**Symptom.** Derivatives ship in isolation. No links to source. No links between derivatives. No mention of the cross-format set on the channels where audiences could discover it. + +**Diagnosis.** Cross-promotion was treated as optional or as an afterthought. The compounding effects of cross-linking and co-promotion are missing. + +**Cure.** Apply the cross-promotion discipline (see `cross-promotion-patterns.md`). Every derivative includes a derivative-to-source link. The source piece is updated to reference derivatives. Co-promotion across channels is planned at rollout time. + +--- + +## Failure 10: AEO extraction skipped or generic + +**Symptom.** The cross-format set ships without FAQ extractions or with generic FAQ extractions. AI-search citation rates are low. + +**Diagnosis.** AEO extraction was not part of the plan, or the FAQ questions do not match user search phrasings, or the answers are context-dependent rather than standalone. + +**Cure.** Apply the AEO extraction patterns. Treat FAQ extraction, snippet design, and statistic extractions as derivative formats with their own conventions. Schema-mark where appropriate. + +--- + +## Failure 11: No source-piece updating after rollout + +**Symptom.** The source piece publishes; derivatives ship; the source piece is never updated to reference the derivatives. The source remains static. + +**Diagnosis.** The forward-promotion from source to derivatives was skipped. The source's role as cross-format hub is wasted. + +**Cure.** Plan source-piece updates as part of the rollout. As each derivative ships, the source's "related" or "see also" section gets updated. The source becomes a navigation hub for the cross-format set. + +--- + +## Failure 12: Capacity underestimation + +**Symptom.** The team planned 30 hours for a whitepaper repurposing pipeline; actual cost is 70 hours. New production suffers; team burns out. + +**Diagnosis.** Capacity estimates were based on optimistic assumptions or on prior pipelines that were not as substantial. + +**Cure.** Track actual capacity per pipeline (see `repurposing-pipeline-templates.md`). Calibrate estimates over time. Some pipelines genuinely cost more than the team has budget for; the right answer may be to reduce scope rather than to overrun. + +--- + +## Failure 13: No measurement + +**Symptom.** Cross-format sets ship; the team has a vague sense some perform better than others; the program does not learn. + +**Diagnosis.** No per-pipeline or per-derivative tracking. Outcomes are anecdotal rather than data-driven. + +**Cure.** Establish a minimum log per pipeline run: source piece, derivatives planned vs delivered, capacity spent, outcomes per derivative, lessons learned. Pattern-detect across pipelines to inform future ones. + +--- + +## Failure 14: Pipeline dogmatism + +**Symptom.** The team applies the same pipeline template to every source piece regardless of the source's characteristics or the audience overlap. Some derivatives consistently underperform; the team keeps producing them anyway. + +**Diagnosis.** Treating templates as fixed shapes rather than as starting points to customize. + +**Cure.** Customize pipelines per source piece. Audience characteristics, source characteristics, and capacity should adjust the cross-format set. Drop derivatives that consistently underperform for the program's audience mix. + +--- + +## Failure 15: AI repurposing as the strategy + +**Symptom.** "We use AI to repurpose, so we can scale." The output is a wave of low-engagement derivatives across many channels. The team is producing more derivative content than ever; engagement is flat or declining. + +**Diagnosis.** AI is being treated as a substitute for the craft of cross-format adaptation. Volume is being prioritized over quality. + +**Cure.** AI is a tool within the workflow, not the workflow itself. The discipline of adaptation per medium is still the work; AI accelerates parts of it. See `ai-content-collaboration` for the workflow discipline that prevents AI-assisted repurposing from drifting into mass-blast and slop. + +--- + +## The cross-cutting pattern + +Most repurposing failures share a single root: treating repurposing as content multiplication rather than as cross-format craft. + +Multiplication thinking treats each derivative as another item in a quota: more channels, more pieces, more reach. The output is mass-blast and slop because adaptation is skipped. + +Craft thinking treats each derivative as a piece in its own right, adapted for its medium, holding the source's voice while respecting the format's conventions. The output is a coherent cross-format set where each derivative earns engagement on its medium. + +The fix for almost any repurposing failure is the same: stop multiplying, start adapting. The capacity required for craft-driven repurposing is higher than multiplication-driven repurposing; the value extracted is also higher, often by an order of magnitude. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the multiplication-vs-craft framing. + +## Implementation choices that stay internal + +Specific tooling for derivative tracking. Specific reporting templates for cross-format outcomes. Specific reviewer training on per-format conventions. Specific automation that flags voice drift across derivatives. The team's own conventions for failure-pattern detection in their pipelines. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md new file mode 100644 index 0000000..e775ee6 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md @@ -0,0 +1,170 @@ +# Cross-promotion patterns + +Linking patterns, attribution, and co-promotion across channels. The mechanics that turn a cross-format set into a coordinated extension rather than scattered derivatives. + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. The cross-promotion discipline is small per-derivative but compounds significantly across the set. + +--- + +## Derivative back to source + +Each derivative includes a link or reference to the source piece for readers who want depth. + +**The pattern.** + +- Blog-post derivative includes "This is one of six pieces drawing from our recent whitepaper on X. Read the full whitepaper here." +- Email derivative ends with "Want the full framework? Read the original piece here." +- Social-post derivative includes a link to the source in profile, in comments, or as part of a multi-post thread. +- Podcast episode show notes link to the source article. +- Video description links to the source. + +**Why it works.** The source's traffic compounds. Audiences who engage with a derivative and want depth click through; the source piece earns continued traffic from the cross-format set. The source's authority benefits from the inbound links from derivative pieces. + +**The discipline.** Every derivative includes a derivative-to-source link as a non-negotiable element of the format adaptation. The link is not buried; it is positioned where readers who want more naturally find it. + +--- + +## Source forward to derivatives + +The source piece is updated to include links to derivatives as they ship. + +**The pattern.** + +- A "related" or "see also" section at the end of the source piece, updated as derivatives ship. +- Inline links from specific source sections to corresponding derivatives that develop those sections. +- A dedicated "this piece's extensions" callout linking to the cross-format set. + +**Why it works.** The source becomes the hub for the cross-format extension. Audiences who land on the source can navigate to derivatives that match their preferred format. The source's role as canonical anchor strengthens. + +**The discipline.** Update the source piece as the cross-format set rolls out. Stale source pieces that do not reference their derivatives miss the cross-promotion opportunity. + +--- + +## Derivatives across + +Where appropriate, derivatives link to other derivatives in the cross-format set. + +**The pattern.** + +- Blog post 3 in a series links to blog posts 1, 2, 4, 5, 6 either inline or in a "more in this series" footer. +- Email 5 in a sequence references email 4's framework or previews email 6. +- Podcast episode show notes link to a related video, blog series, or webinar. +- Webinar registration page links to the relevant blog series and the underlying source piece. + +**Why it works.** The series feeling helps audiences engage with multiple pieces. Internal linking compounds across the set. SEO benefits accrue when derivatives strengthen each other's authority. + +**The discipline.** Plan the cross-derivative link graph at production time. Each derivative's link plan is part of the production work, not an afterthought. + +--- + +## Attribution within derivatives + +When a derivative is clearly drawn from a source piece, acknowledge. + +**The pattern.** + +- "This is adapted from our recent piece on X." +- "Drawing from our research on [topic]." +- "Originally published as [source piece title]." +- For social posts: "From our recent whitepaper on X, [insight]." + +**Why it works.** Attribution earns reader trust. Uncredited derivatives can feel like the same work being recycled without acknowledgment; audiences notice and discount the program's perceived effort. + +**The discipline.** Attribution is honest about the derivative status. The format adaptation is the value-add; pretending the derivative is independent work overstates the production effort and reads as low-trust positioning. + +**Anti-pattern: hiding derivatives.** Some teams treat derivatives as if they were independent pieces, with no acknowledgment that they draw from a source. Audiences who follow the program detect the recycling and the cross-format coherence is lost. + +--- + +## Co-promotion across channels + +Derivatives can be promoted on channels other than the channel where they natively live. + +**The pattern.** + +- A blog post derivative gets re-shared on social where the original blog post might not have been re-shared without the derivative pretext. +- A social post derivative gets mentioned in the email newsletter as "our latest LinkedIn post on X." +- A podcast episode gets promoted on social, in the email, and on the blog. +- A video derivative gets embedded in a blog post or shared via email. + +**Why it works.** Each derivative's reach extends beyond its native channel. Audiences encountering a derivative through cross-channel promotion discover both the derivative and the channel where it lives. + +**The discipline.** Plan cross-channel promotion as part of the rollout. Each derivative has a primary channel (where it lives natively) and a secondary channel set (where it gets promoted from). The plan is explicit, not improvised. + +--- + +## Internal linking refresh on related pieces + +Pieces in the library that are related to the source's topic may benefit from updated internal linking when the source's cross-format set rolls out. + +**The pattern.** + +- Sister pieces that mention the source's topic get updated to link to the source piece (if they did not already) and possibly to the most relevant derivative. +- Pieces in the same hub or category get updated where the cross-format set makes new linking opportunities sensible. +- Anchor text on existing internal links may benefit from refresh if the source's positioning shifted. + +**Why it works.** The source's authority benefits from internal links across the library. Derivatives benefit from being part of the link graph rather than orphaned. + +**The discipline.** Run a brief internal-linking audit when the cross-format set rolls out. The audit catches obvious linking opportunities; over-investing in this pass is the failure mode (touching too many pieces, producing diminishing returns). + +--- + +## The cross-promotion graph + +Visualizing the cross-promotion structure as a graph helps catch gaps. + +**Nodes.** The source piece and each derivative. + +**Edges.** + +- Source-to-derivative links. +- Derivative-to-source links. +- Derivative-to-derivative links. +- Cross-channel co-promotion (each channel promoting each piece). + +**Audit.** Each derivative should connect to the source. Each derivative should connect to at least one other derivative where format-appropriate. Each derivative should be co-promoted on at least one secondary channel where audience overlap exists. + +**Output of the audit.** A planned link and promotion graph for the cross-format set, with the gaps identified before the rollout begins. + +--- + +## Common cross-promotion failures + +**Derivatives shipping in isolation.** Each derivative ships without links to source or to other derivatives. The cross-format set reads as scattered pieces; the compounding effect of cross-linking is lost. + +**Source piece not updated.** Source publishes; derivatives ship; the source piece is never updated to reference the derivatives. The hub function of the source is wasted. + +**Attribution skipped.** Derivatives ship without acknowledging the source. Audiences detect the recycling; trust degrades. + +**Cross-channel co-promotion skipped.** Each derivative stays on its native channel. Reach is limited to the audiences who happen to be on each channel. + +**Internal-linking refresh skipped.** Existing pieces in the library do not get linked to the new source piece. The library's internal-link graph stays static; the source piece's authority does not benefit. + +**Over-investment in cross-promotion.** Internal-link refresh that touches 50+ pieces in the library produces diminishing returns and maintenance overhead. Cure: target the highest-value linking opportunities; skip the marginal ones. + +--- + +## Cross-promotion in mature programs + +Programs with established cross-promotion discipline accumulate compounding effects over time. + +**The pattern in mature programs.** + +- Every flagship piece has an established cross-format extension plan. +- Every derivative has documented linking and promotion structure. +- The library's internal-link graph reflects accumulated cross-promotion across multiple cross-format sets over years. +- Audiences trust that pieces from the program connect; navigation between pieces feels intuitive. + +**The compounding effect.** Older flagship pieces continue to draw traffic because their cross-format sets extended their reach; their derivatives continue to draw traffic because their cross-promotion brought audiences in. The library's traffic profile reflects accumulated cross-format work, not just individual-piece performance. + +**The maturity audit.** Do new flagship pieces' cross-format sets connect to older flagship pieces' cross-format sets where topics overlap? Mature programs cross-promote across time; immature programs treat each cross-format set as isolated. + +--- + +## Methodology-level choices that stay in the public skill + +The cross-promotion link patterns, attribution discipline, co-promotion across channels, internal linking refresh, the cross-promotion graph, the common failures, the maturity-audit pattern. + +## Implementation choices that stay internal + +Specific link-graph tooling. Specific automation that surfaces missing cross-format links. Specific channel-promotion calendars. Specific internal-link audit tools. The team's own conventions for attribution language. These vary by team, CMS, and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md new file mode 100644 index 0000000..18b376f --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md @@ -0,0 +1,202 @@ +# Format adaptation patterns + +Eight source-to-derivative adaptations with worked examples. The patterns that distinguish thoughtful adaptation from mass-blast. + +Each pattern below is a recurring shape: a particular source-piece type adapting into a particular derivative format. The patterns are not the only adaptations; they are the most common, with the most predictable success and failure modes. + +--- + +## Pattern 1: Long-form to blog series + +**Source.** A 4,000-8,000 word whitepaper, definitive guide, or research report. + +**Derivatives.** 4-6 standalone blog posts. Each post takes one of the source's H2 sections (or one of its sub-arguments) and develops it as a piece in its own right. + +**Adaptation work.** + +- New lede per post. The source's lede establishes the whole piece's thesis; each derivative needs its own lede that establishes its standalone scope. +- New closing per post. Source closing addresses the whole piece's argument; derivative closings address the post's specific argument. +- Connective tissue. Each derivative briefly references the source piece ("This is one of six pieces drawing from our recent whitepaper on X") and links forward to other derivatives in the series and back to the source. +- SEO targeting per derivative. The source piece may target one primary keyword cluster; each derivative can target a more specific long-tail keyword. + +**Example.** A whitepaper "The complete framework for content distribution" with H2 sections on owned, earned, paid channels, audience-channel matching, content-channel matching, and distribution measurement. Derivatives: 6 blog posts, one per section, each developing the section into a standalone piece (typically 1,200-1,800 words each). + +**Common failures.** + +- Derivative posts that are paste-ins of source sections without rewriting. Reads as duplicate content; SEO penalty risk; voice flatness. +- Derivative posts that compete with the source for the same keyword (cannibalization). Cure: explicit primary-keyword assignment per piece, with derivatives on long-tail variants. +- Derivative posts that drop the source's voice. Cure: voice prompts and review per derivative. + +--- + +## Pattern 2: Blog post to email sequence + +**Source.** A 1,200-2,500 word blog post on a multi-step framework, methodology, or process. + +**Derivatives.** 3-7 emails delivered over 1-3 weeks. Each email develops one step or section of the source's framework with sender-voice adaptation. + +**Adaptation work.** + +- Sender voice. Email voice is more direct and conversational than blog voice. Sentences shorter; "you" usage higher; more direct address. +- Engagement hooks per email. Subject line and preheader carry most of the email's open-rate burden. Hooks need to be earned per email. +- One CTA per email. Email format rewards single clear CTAs; multi-CTA emails underperform. +- Sequential building. Each email assumes the prior emails have been read; the sequence builds; the final email synthesizes. + +**Example.** A blog post on "the 5-step framework for product launches" becomes a 6-email sequence: introduction email, one email per step, synthesis email. Each email is 200-500 words with a single CTA. + +**Common failures.** + +- Emails that are blog paragraphs with "read more" links. Mass-blast pattern. +- Emails that lose voice consistency. Cure: voice anchored to source's distinctive register; per-email review. +- Sequences that are too long. 12-email sequences from a 1,500-word source are over-extension; audiences disengage. Cure: match sequence length to source's actual content depth. + +--- + +## Pattern 3: Whitepaper to webinar + +**Source.** A substantive whitepaper or research report. + +**Derivatives.** A 30-45 minute webinar with the whitepaper's framework as the spine, plus live elements that print does not support: Q&A, polls, interactive moments, possibly guest appearances. + +**Adaptation work.** + +- Spine selection. The webinar typically takes the whitepaper's 3-5 most load-bearing sections as its spine. Lower-priority sections from the source become spoken asides or get cut. +- Spoken-language adaptation. Print-style sentences read aloud sound stilted. The webinar script (or speaker notes) is rewritten in spoken voice. +- Interactive design. Polls, Q&A, audience prompts. Webinar without interactivity is a video; webinar with interactivity earns the format. +- Slide design. Text-heavy slides fail; the visual layer carries the audience's attention while the speaker delivers the content. +- Recording and follow-up. Most webinars become video derivatives after the live session; the recording extends value indefinitely. + +**Example.** A 6,000-word research report on B2B paid media benchmarks becomes a 40-minute webinar: 25-minute walkthrough of the report's framework with the speaker's commentary, 10-minute Q&A, 5-minute conclusion with specific recommendations. The recording is later cut into derivative video clips. + +**Common failures.** + +- Webinars that read the whitepaper aloud. The whitepaper is published; the webinar adds nothing. +- No interactivity. Live audiences disengage when the format is one-way. +- Text-heavy slides that compete with the speaker. Cure: visuals carry the design; speaker carries the content. + +--- + +## Pattern 4: Long-form to social posts + +**Source.** A long-form piece (whitepaper, definitive guide, research report). + +**Derivatives.** 8-30 social posts across the platforms where the audience exists. Each post is one specific moment from the source: a pull quote, a framework summary, a key statistic, a contrarian claim. + +**Adaptation work.** + +- Platform-specific structure. LinkedIn long-post structure differs from X/Twitter thread structure differs from Threads structure. Adaptation is per platform. +- Hook in the first 1-2 lines. Social readers decide to expand or scroll within seconds; the hook earns expansion. +- Visual or quote-graphic options. Many social posts benefit from accompanying visuals (quote graphics, statistic graphics, framework diagrams). +- One specific point per post. Multi-point social posts dilute; one clear point earns engagement. +- Series cadence. Posts shipped over weeks rather than dumped in one day; audiences engage with each post if they are spaced. + +**Example.** A whitepaper on AI search optimization becomes 18 social posts: 6 framework-summary posts, 4 statistic posts (with custom graphics), 4 contrarian-claim posts, 4 question-prompt posts. Distributed over 6 weeks across LinkedIn and X. + +**Common failures.** + +- Posts that are quote graphics with no context. The graphic is decoration; the post needs text that earns engagement. +- Posts that read as blog-text paste-ins. Mass-blast on social. +- Cadence too aggressive. 18 posts in one week exhausts audiences; distributed cadence performs better. + +--- + +## Pattern 5: Article to podcast episode + +**Source.** A substantive article (1,500-3,500 words). + +**Derivatives.** A podcast episode with the article as spine, plus host commentary, examples, and possibly guest interviews. + +**Adaptation work.** + +- Spoken-language adaptation. Article sentences read aloud sound stiff. The episode script (or talking-points outline) is in spoken voice. +- Conversational pacing. Examples and asides that print would cut earn their place in audio because the conversation needs space to breathe. +- Show notes as derivative format. The show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as a derivative in their own right. +- Guest dynamics where applicable. Some podcast episodes pair the article's framework with guest perspective; the article is the show's structured input, the guest adds expert commentary. + +**Example.** An article on programmatic SEO durability becomes a podcast episode: 5-minute introduction by the host, 30-minute interview with a practitioner who has run programmatic operations, 10-minute synthesis by the host. Show notes link to the source article and to several mentioned references. + +**Common failures.** + +- Episodes that read the article aloud. The article is published; the episode adds nothing. +- Episodes without spoken-language adaptation. Stilted delivery; low completion rates. +- Show notes that are afterthoughts. Show notes that fail their own format reduce the episode's discoverability and value. + +--- + +## Pattern 6: Long-form to video shorts + +**Source.** A long-form piece with travelable elements (specific examples, framework moments, contrarian claims). + +**Derivatives.** 6-20 short-form video clips, 30-90 seconds each. Each short is one standalone moment. + +**Adaptation work.** + +- Hook in seconds 1-2. Algorithmic recommendation rewards retention from second 1; openings must earn continued viewing. +- Captions essential. Many viewers watch without sound; captions carry the message. +- Visual presence. Talking-head shorts work for some audiences; many short-form platforms reward visual variation, motion, or text-on-screen design. +- Single specific point per short. Short-form does not support multi-point delivery; one moment per clip. +- Platform-specific aspect ratios and conventions. TikTok shorts, Instagram Reels, YouTube Shorts each have specific norms. + +**Example.** A research report becomes 12 video shorts: 4 statistic shorts (text-on-screen with audio narration), 4 framework moment shorts (whiteboard-style explanation), 4 contrarian-claim shorts (talking head). Distributed across LinkedIn video, YouTube Shorts, Instagram Reels. + +**Common failures.** + +- Shorts without strong opening hooks. Algorithmic feed deprioritizes; reach is minimal. +- Shorts without captions. 50%+ of audience cannot consume the content. +- Shorts that try to cover too much in 60 seconds. Cure: one moment, one point, one short. + +--- + +## Pattern 7: Research report to FAQ extractions + +**Source.** A research report or definitive guide with specific Q&A-able material. + +**Derivatives.** Standalone FAQ entries (40-80 words each), formatted for AI search citation, possibly aggregated into FAQ pages or schema-marked snippets within the source piece. + +**Adaptation work.** + +- Question framing. AI search engines cite content that matches likely user-query phrasings. FAQ questions need to use the phrasings users actually search. +- Standalone answer paragraphs. Each FAQ answer must work as a standalone paragraph; AI engines cite paragraphs, not contextual passages. +- Source attribution within the answer. Statistics and specific claims need named sources within the answer paragraph; AI engines weight named-source claims at higher rates. +- Schema markup. FAQPage schema where the FAQ aggregates as a dedicated page; structured data signals the format to search engines. + +**Example.** A research report on content distribution effectiveness becomes 15 FAQ extractions: "What channels produce highest engagement for B2B content?" "How does audience size affect channel selection?" "What is the typical engagement rate decay across channel types?" Each Q&A is 40-80 words with named-source citations. + +**Common failures.** + +- Questions that do not match how users phrase queries. Cure: query research; phrase questions in user voice. +- Answers that depend on context outside the answer paragraph. AI engines may not cite cleanly; paragraphs need to stand alone. +- Missing schema markup. The FAQ format does not signal cleanly to search engines without schema. + +--- + +## Pattern 8: Multi-piece source to ebook + +**Source.** Several related pieces (blog posts, articles, social threads) that together cover a topic. + +**Derivatives.** An ebook with the multi-piece content as the bulk, plus new connective tissue: introduction, chapter framings, conclusions, and possibly new chapters that fill gaps the source pieces did not cover. + +**Adaptation work.** + +- Topic synthesis. The multi-piece source covers the topic in scattered ways; the ebook needs to organize the content into a coherent sequence. +- New connective tissue. Introductions, chapter prefaces, transitions, conclusion. Often 20-30% of the ebook is new content not present in the source pieces. +- Voice consolidation. Pieces written over months may have voice variation; the ebook needs to read as one unified work, which often means rewriting passages to match a target voice. +- Design and production. Ebook format expectations: chapter design, table of contents, possibly downloadable PDF. Higher production cost than other repurposing patterns. + +**Example.** Twelve blog posts on a topical theme, written over 18 months, are consolidated into a 22,000-word ebook. New material includes a 1,500-word introduction, chapter framings totaling 3,000 words, a 1,500-word conclusion, and a 2,500-word new chapter that fills a gap the original posts did not address. + +**Common failures.** + +- Ebook that reads as posts stitched together. Cure: rewrite for unity; the ebook is a piece in its own right. +- No new connective tissue. The ebook adds no value over reading the source pieces. +- Voice inconsistency. Voice drift across pieces becomes visible when consolidated; cure: unified voice editing pass. + +--- + +## Methodology-level choices that stay in the public skill + +The eight adaptation patterns with their work, examples, and common failures. The recurring lesson: adaptation is per-format craft, not source-text recycling. + +## Implementation choices that stay internal + +Specific platform automation tooling. Specific design templates per derivative format. Specific tooling for video clip extraction from longer videos. Specific show-notes templates. Specific schema markup patterns the team uses for FAQ extractions. The team's own conventions for connective-tissue length in ebook consolidation. These vary by team, stack, and platform mix. diff --git a/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md b/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md new file mode 100644 index 0000000..df75a32 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md @@ -0,0 +1,192 @@ +# Per-format constraints + +What each medium demands and forbids. Length norms, conventions, hooks, and the underlying observation: derivatives that ignore the medium's constraints fail the medium even when the source content was strong. + +Each format below has specific reader expectations. Pieces that meet expectations earn engagement; pieces that violate expectations get scrolled past or ignored regardless of content quality. Repurposing capacity goes to waste when derivatives fail the format-specific tax. + +--- + +## Email + +**Length norms.** 200-800 words per email for most B2B and consumer audiences. Newsletter-style emails can run longer (1,500-3,000 words) for engaged audiences but shorter is generally safer. + +**What email demands.** + +- A subject line that earns the open. Most engagement happens or fails at the subject-line level. +- A preheader that supports the subject line. The preheader is the second-most-read element of the email and most templates underuse it. +- Plain prose paragraphs that render reliably. Many email clients break complex formatting; tables, columns, and rich layouts can fail. +- A single clear CTA. Multi-CTA emails dilute; readers process one action at a time. +- Mobile-first design. 60-70% of email opens are on mobile; readability on small screens is essential. + +**What email forbids.** + +- Image-only emails. Many clients block images by default; image-only emails arrive blank. +- Link-laden text dumps. More than 3-4 links in body text dilutes attention. +- Multi-CTA layouts that compete for the click. +- Subject lines that announce the topic without earning the open ("Newsletter for week of X"). + +**Adaptation discipline.** Email derivatives need new ledes (the source's lede does not transfer); spoken-direct voice (more "you" usage; shorter sentences than blog voice); a single CTA per email even when the source piece had multiple potential actions. + +--- + +## LinkedIn (long-form text post) + +**Length norms.** 800-2,500 characters typical; long-form posts up to ~3,000 characters. The character count matters because the platform truncates with "see more"; the truncation point is the hook. + +**What LinkedIn demands.** + +- A first line that earns the "see more" click. The first 1-3 lines determine whether readers expand the post. +- Clear structure: short paragraphs, white space, occasional emphasis. Walls of text get scrolled past. +- A specific point or argument. Narrative-style posts that take time to land work; vague observations do not. +- Engagement hooks: questions, polarizing claims, specific examples that invite comment. +- Original perspective. Repurposed content marked clearly as such; uncredited recycling reads as low effort. + +**What LinkedIn forbids.** + +- Walls of text without paragraph breaks. +- Generic motivational content; the platform has decreasing tolerance for this. +- Posts that read as ads with no substantive content. +- Heavy use of emoji decoration without purpose. + +**Adaptation discipline.** Source content needs to be restructured for LinkedIn rhythm: short opening hook, body with paragraph breaks every 2-3 sentences, specific examples or stakes, possibly a question at the close that invites comment. + +--- + +## X/Twitter (single post and threads) + +**Length norms.** Single post: 280 characters (or up to 4,000 for premium accounts; conventions vary). Thread: 5-15 posts typical for substantive threads. + +**What X demands (single post).** + +- Tight phrasing. Each character matters; specific framings that fit the format earn engagement. +- Stand-alone meaning. Tweets that depend on context outside the tweet often fail. +- Specific points or claims. Vague observations underperform. + +**What X demands (threads).** + +- A first post that earns the next click. Threads are read sequentially; the first post must hook. +- One coherent argument across the thread. Threads that wander get abandoned mid-way. +- Reasonable length. Threads longer than 15-20 posts often lose readers; very long threads may be better as a blog post linked from a shorter thread. + +**What X forbids.** + +- Threads that read as a blog post split into 280-character chunks. The platform's conversational rhythm is different. +- Hashtags-as-content. Heavy hashtag usage signals SEO chasing rather than communication. + +**Adaptation discipline.** Source content for threads needs to be re-paced: each post a complete thought, the thread building, the conclusion specific. + +--- + +## Long-form video (YouTube, in-depth content) + +**Length norms.** 8-30 minutes typical for substantive content. Some categories support longer (45-90 minutes for deep technical content); the algorithm rewards retention over duration. + +**What long-form video demands.** + +- Pacing for spoken delivery. Print-style sentences read aloud sound stilted; video scripts need spoken voice. +- Visual variation. Talking-head video alone for 30+ minutes underperforms; cuts, b-roll, on-screen text, illustrations carry attention. +- Audio quality. Bad audio kills retention faster than bad video; audio investment usually returns more than video investment. +- A specific topic. The video's title and thumbnail need to communicate scope; vague titles underperform in algorithmic recommendation. + +**What long-form video forbids.** + +- Slideshows of text read aloud. Mass-blast pattern in video form. +- No editing. Filler words, long pauses, and unedited rambling reduce retention. +- Talking head only with no visual variation across long durations. + +**Adaptation discipline.** Source content for video needs scripting in spoken voice (or talking-points for unscripted delivery), visual planning per segment, and an opening that earns the next 30 seconds of viewing. + +--- + +## Short-form video (TikTok, Reels, Shorts) + +**Length norms.** 60-90 seconds typical; 15-30 seconds for some platforms. Algorithmic recommendation typically rewards retention from second 1. + +**What short-form demands.** + +- Hook in seconds 1-2. Viewers scroll past the opening if it does not earn the next 5 seconds. +- Captions. Many viewers watch without sound; captions carry the message. +- A single specific point. Short-form does not support multi-point delivery. +- Visual presence. Motion, text-on-screen, or visual variation within the short. Static talking heads underperform. + +**What short-form forbids.** + +- Content that takes 10+ seconds to land. Viewers leave before the point. +- Long-form video clipped without re-pacing. The pacing assumed in the source piece does not match short-form expectations. +- Captions that lag the audio. Mistimed captions distract. + +**Adaptation discipline.** Source content for shorts needs extreme compression: one moment, one point, one short. Each short is a standalone unit. + +--- + +## Podcast + +**Length norms.** 20-90 minutes typical for substantive content. Daily-news-style podcasts can be shorter (8-15 minutes); deep-interview podcasts can run 90-180 minutes. + +**What podcast demands.** + +- Spoken-language sentence structure. Print-style sentences read aloud sound stiff. +- Conversational pacing. Examples, asides, and natural speech earn engagement; tightly-argued print sections feel cold. +- Audio quality. Listening is intimate; bad audio breaks the connection. Better audio than video matters here. +- Show notes that do the print work the audio cannot. Links, structured summary, citations, references. + +**What podcast forbids.** + +- Reading articles aloud without adaptation. +- Scripts that sound scripted (over-rehearsed delivery, no conversational rhythm). +- Episodes without show notes or with thin show notes. +- Inconsistent episode length within a series; audiences develop expectations. + +**Adaptation discipline.** Source content for podcasts becomes the show's spine; the host adds context, examples, and conversational elaboration. Show notes are a distinct derivative format with their own constraints. + +--- + +## Webinar + +**Length norms.** 30-60 minutes typical. Longer webinars (90+ minutes) require very high engagement design or strong specific draws (like premiere announcements). + +**What webinars demand.** + +- A live element. Q&A, polls, interactive moments. Static webinars are videos; interactive webinars earn the format. +- Slide design that supports rather than competes with delivery. Text-heavy slides distract; visual slides with the speaker carrying the content work. +- Pacing for live audience attention. Audience attention dips in the middle; engagement design needs to address the dip. +- Recording strategy. Most webinars become video assets after the live session; the recording extends value indefinitely. + +**What webinars forbid.** + +- Reading slides aloud. The audience can read; the speaker should add the value the slides cannot carry. +- No engagement design. Audiences disengage in pure one-way webinars. +- Webinars that try to cover too much in 30 minutes. Cure: narrow the topic to what 30 minutes can deliver. + +**Adaptation discipline.** Source content for webinars typically takes the source's 3-5 most load-bearing sections as the spine, plus interactive moments, plus Q&A. + +--- + +## AI-search snippet (for citation by AI engines) + +**Length norms.** 40-80 words per snippet for FAQ-style extractions; 100-200 words for paragraph-style extractions. + +**What AI-search snippets demand.** + +- Standalone meaning. The snippet works without the surrounding context; AI engines extract paragraphs, not full pieces. +- Named-source citations within the snippet. AI engines weight named-source claims; "according to a 2025 Forrester study" performs better than "studies show." +- Specific framings. Vague phrasings rarely get cited; specific phrasings do. +- Schema markup where applicable. FAQPage and similar schemas signal the format. + +**What AI-search snippets forbid.** + +- Floating claims without sources. +- Pronoun references that depend on outside context ("This is why..." with no clear referent within the snippet). +- Hedged language on claims that can be specific. + +**Adaptation discipline.** Source content for AI snippets needs to be extractable as standalone paragraphs with internal citations and specific framings. Often the source piece needs additions specifically designed for snippet citation. + +--- + +## Methodology-level choices that stay in the public skill + +The format constraints by medium, the length norms, the demand-and-forbid lists, the adaptation discipline per format. The underlying observation: medium constraints are non-negotiable. + +## Implementation choices that stay internal + +Specific platform automation. Specific design templates per format. Specific captioning workflows. Specific schema markup patterns. Specific A/B testing of format-specific elements (subject lines, hooks, opening lines). The team's own conventions on length within the bands. These vary by team and platform mix. diff --git a/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md b/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md new file mode 100644 index 0000000..9325d2f --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md @@ -0,0 +1,237 @@ +# Repurposing pipeline templates + +Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. The repeatable shapes that turn ad-hoc repurposing into a predictable program. + +Repurposing without templates produces ad-hoc workflows: each cross-format extension is invented from scratch, capacity estimates are unreliable, quality varies. Templates make repurposing a known production shape, with predictable capacity and predictable quality. + +The templates below are recurring shapes; teams adapt them to specific source pieces and program contexts. + +--- + +## Pipeline 1: Whitepaper + +**Source.** A 4,000-8,000 word whitepaper or definitive guide. + +**Cross-format set (typical).** + +- 4-6 blog posts (one per major section). +- 5-7 email sequence. +- 1 webinar. +- 12-18 social posts across LinkedIn, X, possibly Instagram or Threads. +- 6-12 video shorts. +- 10-15 FAQ extractions for AI search. +- Possibly 1 podcast episode. + +**Production sequence.** + +- Week 0: Source piece publishes. +- Week 1: First social posts ship; email teaser sends. FAQ extractions ship as part of the source piece (or as an immediately-following FAQ page). +- Weeks 2-6: Blog posts ship at 1-per-week cadence. Email sequence sends in parallel. More social posts ship from each blog post's release. +- Weeks 4-8: Webinar runs. Webinar recording becomes additional video derivatives. +- Weeks 6-10: Video shorts ship. Podcast episode (if applicable) records and releases. + +**Capacity.** Typical whitepaper pipeline costs 30-60 hours of editorial and production work across 8-10 weeks, on top of the source piece's production cost. + +**Owner structure.** Single owner-of-extensions for the whitepaper. Specific derivative owners by format (blog series owner, email sequence owner, social owner, video owner). The owner-of-extensions coordinates timing and ensures cross-promotion happens. + +--- + +## Pipeline 2: Blog post (substantive) + +**Source.** A 1,500-2,500 word substantive blog post on a multi-step framework or substantive topic. + +**Cross-format set (typical).** + +- 5-7 email sequence (if the source has a multi-step framework). +- 4-8 social posts. +- 2-4 video shorts. +- 3-5 FAQ extractions. +- Possibly 1 podcast episode segment (not full episode). + +**Production sequence.** + +- Week 0: Blog post publishes. +- Week 1: First social posts ship; email teaser if part of a sequence; FAQ extractions added to the post. +- Weeks 2-4: Email sequence sends. Additional social posts. Video shorts ship. +- Weeks 4-6: Long-tail social and AI-search-snippet refinement. + +**Capacity.** Typical substantive blog post pipeline costs 8-15 hours of additional work across 4-6 weeks. + +**Owner structure.** Often one owner runs the full extension for blog-post-tier sources because the work is small enough to coordinate in one head. + +--- + +## Pipeline 3: Research report + +**Source.** A 4,000-12,000 word research report with primary data. + +**Cross-format set (typical).** + +- 5-8 blog posts (one per major finding or section). +- 7-10 email sequence. +- 1-2 webinars (often a launch webinar plus a deeper-dive webinar). +- 20-30 social posts (research reports produce many statistic-driven social derivatives). +- 8-15 video shorts (statistic-focused). +- 15-25 FAQ extractions. +- 1-2 podcast episodes. +- Possibly an interactive data visualization or microsite. + +**Production sequence.** + +- Week -2 to Week 0: Pre-launch promotion teasers (research findings preview). +- Week 0: Source report publishes; launch webinar announces; first wave of statistic-focused social ships. +- Weeks 1-4: Heavy email sequence; blog posts ship; webinars run; social posts continue. +- Weeks 4-12: Video shorts roll out; podcast episodes record and release; FAQ extractions get refined as AI-search citations are tracked; second webinar runs for deeper-dive audience. +- Indefinitely: Statistics from the report continue to be cited in subsequent program pieces; the report becomes a reference asset. + +**Capacity.** Research report pipelines are the highest-investment repurposing efforts. Typical cost: 60-150 hours of additional work across 8-16 weeks, on top of the report's production cost. + +**Owner structure.** Owner-of-extensions plus dedicated derivative owners. Often a research report's cross-format extension is treated as a project with its own project manager rather than as a routine repurposing pipeline. + +--- + +## Pipeline 4: Multi-piece consolidation (ebook) + +**Source.** Multiple existing pieces (blog posts, articles, social threads) on a related topic. + +**Cross-format set (typical).** + +- 1 ebook (the primary consolidation). +- New introduction, chapter framings, conclusion within the ebook (often 20-30% new content). +- 4-7 promotional blog posts (potentially excerpting chapters or introducing the ebook). +- 5-8 email sequence promoting the ebook. +- 1 webinar based on the ebook's framework. +- 8-15 social posts promoting the ebook and its chapters. +- 3-6 video shorts. + +**Production sequence.** + +- Months 1-3: Source-piece selection and consolidation. Identify which existing pieces fit; outline the ebook; write new connective tissue; consolidate and edit for unified voice. +- Month 3-4: Production: design, layout, possibly PDF generation, gating setup if applicable. +- Month 4: Ebook launches. First promotional blog posts and emails ship. Webinar runs. +- Months 5-8: Promotional cadence continues. Video shorts and social posts roll out. + +**Capacity.** Multi-piece consolidation pipelines often cost 60-120 hours of consolidation and production work, plus the standard derivative production. Total: 80-180 hours across 4-8 months. + +**Owner structure.** A consolidation lead drives the editorial work; standard derivative owners run the promotional set. The consolidation lead often is a senior editor because the unified-voice editing is substantial. + +--- + +## Pipeline 5: Trending topic editorial + +**Source.** A 1,000-2,500 word editorial piece on a trending or news-driven topic. + +**Cross-format set (typical, lighter than evergreen).** + +- 4-7 social posts (concentrated in the first week to ride the trend). +- 1-2 video shorts. +- 1-2 FAQ extractions if the topic supports it. +- Often no email sequence (trending topics may not justify a multi-email investment). +- Often no webinar (production cycle is too long for trending topics). + +**Production sequence.** + +- Day 0: Source piece publishes. +- Days 1-7: Social posts ship rapidly to ride the trend. Video shorts ship if production cycle allows. +- Weeks 2-4: Long-tail social and AI-search-snippet refinement if the topic has staying power. +- After 4 weeks: Pipeline typically winds down as the trend fades. + +**Capacity.** Trending topic pipelines are deliberately light: 4-10 hours of additional work across 1-2 weeks. + +**Owner structure.** Often one owner runs the full extension because timeliness matters more than coordinated multi-format depth. + +--- + +## Pipeline 6: Case study + +**Source.** A 2,000-4,000 word case study with real specifics. + +**Cross-format set (typical).** + +- 3-5 blog posts pulling specific lessons or framework moments from the case. +- 3-5 email sequence (if the case study has clear teachable steps). +- 6-10 social posts (often statistic-driven from the case's outcomes). +- 1-3 video shorts (often featuring the case's customer if available, with their consent). +- 3-5 FAQ extractions. +- Possibly 1 webinar featuring the customer. + +**Production sequence.** + +- Week 0: Case study publishes. +- Week 1: First social posts ship; FAQ extractions added. +- Weeks 2-6: Blog posts and emails ship. Webinar runs (if part of the plan, often with customer participation). +- Weeks 4-10: Video shorts and additional social. + +**Capacity.** Typical case study pipeline costs 15-30 hours of additional work, plus customer coordination time for any derivatives featuring the customer. + +**Owner structure.** Customer-coordination owner plus standard derivative owners. The customer-coordination owner manages the relationship; derivative owners produce the work; the customer reviews customer-facing derivatives before they ship. + +--- + +## Pipeline customization + +Templates are starting points; programs adapt them. + +**Customization based on audience.** + +- B2B technical audiences: more LinkedIn, more whitepaper-driven; less TikTok and Instagram. +- Consumer audiences: more video and visual social; less long-form. +- Vertical-specific audiences: platform mix may differ (YouTube heavy in some industries; Twitter/X heavy in others). + +**Customization based on capacity.** + +- Smaller teams may execute Pipeline 1 with reduced scope (3 blog posts instead of 6, 6 social posts instead of 18). +- Larger teams may extend pipelines with additional derivatives the templates do not include (interactive tools, microsites, dedicated landing pages). + +**Customization based on source characteristics.** + +- Highly visual source pieces benefit from heavier video and visual-social investment. +- Voice-distinctive source pieces benefit from heavier email and podcast investment (where voice carries). +- Citation-rich source pieces benefit from heavier AEO-extraction investment. + +--- + +## Pipeline tracking + +Each pipeline run produces data that informs future pipelines. + +**The minimum log per pipeline.** + +- Source piece title, type, length, traffic at launch. +- Cross-format set planned vs delivered. +- Capacity spent (hours per derivative type). +- Outcomes per derivative (engagement, traffic, conversion, citation rates). +- Lessons learned (what worked, what failed, what to change next time). + +**Pattern detection across pipelines.** + +- Are some pipeline templates outperforming others on similar source types? +- Are some derivative types consistently outperforming others? +- Are capacity estimates accurate, or do certain pipelines consistently overrun? +- Are some channels consistently underperforming for the program's audience mix? + +The log informs program-level decisions: which pipelines to invest in more deeply, which to drop, which to redesign. + +--- + +## Common pipeline failures + +**Pipeline-as-checklist.** The team treats the pipeline as a checklist to complete rather than as a coordinated plan. Each derivative gets produced; nothing connects to the others; cross-promotion is missing. + +**Capacity underestimation.** Teams plan a Pipeline 1 expecting 30 hours; actual cost is 70 hours; new production suffers. Cure: track actual capacity per pipeline; calibrate estimates. + +**Pipeline dogmatism.** Treating the template as a fixed shape regardless of source-piece characteristics. Some source pieces fit the template; some need customization. Cure: customize pipelines per source. + +**No tracking.** Pipelines run; outcomes are not measured; the program does not learn. Cure: minimum log per pipeline. + +**No owner-of-extensions.** Pipelines run with derivative owners but no overall coordination. Cross-promotion gaps; cadence drift; no single accountable person. Cure: assign an owner-of-extensions per pipeline. + +--- + +## Methodology-level choices that stay in the public skill + +The six pipeline templates with cross-format set, sequencing, capacity, and ownership structures. The pipeline customization framework. The pipeline tracking log. The common pipeline failures. + +## Implementation choices that stay internal + +Specific project-management templates per pipeline. Specific calendar tooling for cross-format scheduling. Specific time-tracking that captures pipeline capacity. Specific reporting templates for pipeline outcomes. The team's own conventions for which pipelines apply to which source-piece tiers. These vary by team, tooling, and program scale. diff --git a/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md new file mode 100644 index 0000000..0678d1e --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md @@ -0,0 +1,198 @@ +# Sequencing and cadence patterns + +When to release derivatives relative to the source. Concentrated vs distributed cadence. Pacing audits. The patterns that match cadence to the source's traffic curve and audience attention. + +The release sequence and cadence determine how the cross-format set lands. The wrong sequencing can produce a wave of derivatives that exhausts audiences, or a trickle that loses connection to the source's authority. The right sequencing matches the source's traffic curve and the audiences' attention rhythm. + +--- + +## Sequencing patterns + +Three patterns for how derivatives sequence relative to the source. + +### Source-first, derivatives following + +**The pattern.** The source piece publishes; derivatives roll out over the following 2-12 weeks. The source carries the initial authority and traffic spike; derivatives extend reach and re-engage audiences over time. + +**Strengths.** + +- The source piece's launch is concentrated, earning the full attention of the program's audiences. The launch is a moment. +- Derivatives reference the source's authority. Each derivative can link back to the source as the canonical version; the source's ranking and authority compounds. +- Audiences who engaged with the source are primed for derivatives; the first derivative often performs well because the audience is warm. + +**Weaknesses.** + +- The source needs to support the launch with strong promotion. If the source publishes quietly, the launch moment is muted. +- Audiences who missed the source see derivatives without context; the derivatives need to stand alone. + +**Fits.** Most programs. The default sequencing pattern. + +### Simultaneous launch + +**The pattern.** Source and a wave of derivatives publish on the same day. Multiple channels fire at once. + +**Strengths.** + +- Maximum splash. The cross-format presence on a single day signals significance to audiences. +- Cross-channel reinforcement. Audiences encountering the program on multiple channels in one day register the significance more strongly than serial encounters. + +**Weaknesses.** + +- Risks audience fatigue. If every channel is firing the same day, audiences may tune out before they engage with any individual piece. +- Heavy production load on launch day. All derivatives must be ready simultaneously, which can compress quality. +- Less time for individual derivatives to land. Each derivative competes for attention with every other derivative on the same day. + +**Fits.** Major flagship launches where the moment itself is part of the value (annual research reports, ebook releases, manifesto-style pieces). Tier 1 source pieces. + +### Derivatives-first, source as anchor + +**The pattern.** Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship after the buildup. + +**Strengths.** + +- Builds anticipation. Audiences who engage with the early derivatives expect the source piece. +- The source piece publishes into a primed audience. + +**Weaknesses.** + +- Less common; works only for built-up audiences who follow the program closely. +- Risks giving away too much before the source. If the early derivatives expose the source's argument, the source publishes into an audience that feels they have already read it. +- Coordination overhead. The cross-format buildup needs to land at the right cadence to support the source's launch. + +**Fits.** Programs with engaged audiences and strong social presence. Less common than source-first; specific to programs that have earned anticipation. + +--- + +## Cadence within the rollout + +Three pacing patterns within the chosen sequencing. + +### Concentrated cadence + +**The pattern.** Most derivatives ship within 4-6 weeks of source. + +**Strengths.** + +- Maximum momentum from the source's authority. The source's traffic curve is highest in the first 2-4 weeks; derivatives launching during that window benefit from the source's freshness. +- The cross-format set feels coherent. Audiences see the program everywhere within a short window; the campaign feeling earns engagement. +- Easier to coordinate. Production and scheduling concentrate; the team is in launch mode for a defined period. + +**Weaknesses.** + +- Limited time for individual derivatives to land. A derivative in week 5 has less attention available than the source did in week 1. +- Audience fatigue risk. Audiences may disengage before week 4-6 if the cadence feels relentless. +- Less long-tail value. After week 6, the cross-format set largely stops producing new touchpoints. + +**Fits.** Tier 1 and Tier 2 source pieces. Programs running flagship launches where the campaign nature is part of the strategy. + +### Distributed cadence + +**The pattern.** Derivatives ship over 3-6 months. + +**Strengths.** + +- Each derivative has space to land. No internal competition for audience attention. +- Long-tail value. The program continues to produce touchpoints over a longer window. +- Sustainable. The team is not in launch mode for months; production fits steady-state cadence. + +**Weaknesses.** + +- Risk of losing connection to source. By month 3, the source piece may be background context rather than the active reference. +- Less momentum. The campaign feeling fades; each derivative is a standalone moment rather than part of a coherent push. +- Coordination overhead extended. Owners and producers need to maintain focus across months. + +**Fits.** Evergreen flagship pieces with sustained traffic curves. Programs with smaller production capacity that cannot sustain concentrated cadence. + +### Indefinite cadence + +**The pattern.** Derivatives keep being created from the source as long as the source remains relevant. + +**Strengths.** + +- Maximum long-term value extraction. +- Adapts to audience response. Derivatives that perform well inform what to produce next; the program learns from the cross-format set's reception. + +**Weaknesses.** + +- Most programs cannot sustain indefinite attention to a single source. Discipline tends to decay. +- Risk of voice drift. Derivatives produced 12 months apart may have voice variation that the original launch cadence avoided. +- Less coherent campaign feel. Audiences see scattered derivatives over a long window without a clear narrative. + +**Fits.** Truly evergreen sources whose value compounds for years. Rare; usually reserved for major flagship pieces (defining manifestos, definitive research reports). + +--- + +## Pacing audits + +Match cadence to the source's traffic curve and the audience's attention rhythm. + +**The source's traffic curve.** + +- **Sharp early traffic, fast decay.** Trending-topic pieces, news-driven analysis. Concentrated cadence; the audience is paying attention for a short window. +- **Sustained high traffic for weeks.** Flagship reports on hot topics. Concentrated to mid-distributed cadence; the audience attention extends but eventually fades. +- **Slow build, sustained traffic for months.** Evergreen flagship pieces, definitive guides. Distributed cadence; the audience encounter is continuous over time. +- **Sustained low traffic with occasional spikes.** Reference pieces that get rediscovered. Indefinite cadence works if the production capacity supports it. + +**The audience's attention rhythm.** + +- **Email subscribers.** Engagement varies; sequences spaced 5-7 days work for most B2B; daily for high-engagement consumer audiences. +- **Social audiences.** Platform-specific. LinkedIn rewards 1-2 posts per week from program accounts; X rewards higher frequency; Instagram somewhere in between. +- **Podcast audiences.** Episodic; weekly cadence common; bi-weekly works for higher-production-effort shows. +- **YouTube audiences.** 1-2 videos per week typical for active channels; long-form video can be less frequent. + +**The pacing decision.** Match the source's traffic curve and the audiences' attention rhythm. If they conflict, the source's curve usually wins; the cross-format set's coherence depends on the source's authority window. + +--- + +## Sequencing and cadence per derivative type + +Some derivatives have natural sequencing within the rollout. + +**Derivatives that should ship early.** + +- Email teaser or preview email. Sets up the source's launch with the email audience. +- Social posts that announce the source. Visibility on launch day. +- Short-form video that introduces the topic. Algorithmic recommendation responds best when the content is fresh. + +**Derivatives that should ship 1-3 weeks in.** + +- First blog post in a series. The source piece is still drawing traffic; the blog post benefits from internal linking and the audience's continued interest. +- Webinar based on the source. Allows time for audience registration and promotion. +- First batch of social pull-quote posts. The source's themes are familiar; the pull quotes resonate. + +**Derivatives that should ship 1-3 months in.** + +- Podcast episode. Production cycle is longer; podcast audience overlap with source audience may be partial. +- Subsequent blog posts in a series. Distributed cadence; each post earns its own attention. +- Email sequence (if not the immediate teaser). The sequence develops the source's framework over time. + +**Derivatives with flexible timing.** + +- FAQ extractions and AI-search snippets. These can ship at source-launch or any time after; AI search citation accumulates over months. +- Ebook consolidation. Often ships 6-12 months after source pieces accumulate; the consolidation work itself takes time. + +--- + +## Common sequencing and cadence failures + +**All-at-once dumping.** A wave of 12 derivatives in 5 days. Audiences disengage by day 3; most derivatives produce little engagement. Cure: distributed cadence with audience-attention spacing. + +**Source quietly publishing while derivatives ship loudly.** The derivatives carry the launch but the source piece itself launches without the attention it deserves. Cure: source-first launch with promotion focused on the source; derivatives follow. + +**Source publishing months after promised derivatives.** Derivatives that previewed a coming source piece ship; the source publishes 4 months later. Audiences have lost connection. Cure: tighten production schedule or flip the sequencing to source-first. + +**Cadence too aggressive for the audience.** Email subscribers receiving daily emails for 2 weeks unsubscribe. Cure: match cadence to audience attention norms; email audiences typically tolerate 1-2 sends per week from a program. + +**Cadence too slow.** Distributed cadence stretched too long; by month 4, audiences have forgotten the source. Cure: bring cadence closer to source's traffic curve; consider indefinite cadence only when the source genuinely supports it. + +**No sequencing plan.** Derivatives ship as they happen to be ready, with no coordination. Cross-format set feels random; audiences see scattered touchpoints with no coherent narrative. Cure: even rough sequencing planning at production time produces better outcomes than no plan. + +--- + +## Methodology-level choices that stay in the public skill + +The three sequencing patterns, the three cadence patterns, the pacing audit, the per-derivative-type sequencing, the common failures. + +## Implementation choices that stay internal + +Specific calendar tooling. Specific automation that schedules derivatives across channels. Specific coordination workflows between producers and channel owners. Specific A/B testing of cadence variants. The team's own conventions for fast-track vs queued derivatives. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md b/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md new file mode 100644 index 0000000..70e61ac --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md @@ -0,0 +1,125 @@ +# Source-piece selection criteria + +Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. The discipline that prevents repurposing capacity from being spent on pieces that will not extend cleanly across formats. + +Not every piece is worth repurposing. Selection is the first decision, and getting it wrong produces derivative work that feels forced, fails to engage on the new formats, and consumes capacity that would have produced better return on stronger source pieces. + +--- + +## Strong source-piece characteristics + +A piece that extends cleanly across formats usually has several of the following. + +**Clear central argument or framework.** The piece has a thesis, a framework, or a structured set of positions that survives translation. The reader of any derivative can extract the argument; the reader of the source can recognize it. + +**Standalone sections.** The piece's H2 sections work as standalone units. A reader who only sees one section can still get value; the section does not depend on the cumulative context of preceding sections to make sense. Pieces with this property produce blog-series and social-post derivatives easily. + +**Travelable examples and case studies.** The piece contains specific examples, case studies, or worked illustrations that can stand alone. These travel into video shorts, social posts, and podcast episodes as natural anchors. + +**Audience overlap with target formats.** The source's audience exists on the platforms where derivatives will live. A B2B technical whitepaper extends well into LinkedIn long-form posts and into podcast episodes; less well into TikTok shorts. + +**Distinctive voice.** The piece has voice characteristics specific enough that derivative voice can stay coherent. Pieces in generic voice produce derivatives that sound like AI-default; pieces in distinctive voice anchor derivatives to recognizable register. + +**Accumulated demand.** The source has demonstrated reader interest: traffic, links, mentions, shares, citations. Pieces with traction support derivatives because the demand is real; pieces without traction produce derivatives that draw on no underlying interest. + +**Multi-angle topic.** The topic has multiple angles, sub-questions, or applications. Pieces on narrow single-angle topics produce few derivatives; pieces on broader topics with sub-questions produce more. + +--- + +## Weak source-piece characteristics + +Pieces that resist repurposing usually have several of the following. + +**Tightly-integrated argument.** The piece is a layered argument where every section depends on the cumulative context. Extract any section and it loses meaning. Whitepapers with this structure (high-rigor analytical pieces) often resist clean derivative extraction; the value is in reading end-to-end. + +**List-style without standalone weight.** The piece is a list of items where individual items are not substantial enough to support derivatives. "Top 10 marketing tips" with one-paragraph items per tip cannot produce strong derivatives because no single item justifies a derivative piece. + +**Narrative-arc dependence.** The piece's value comes from the unfolding narrative; reading any segment alone misses the arc. Some narrative case studies and feature-style longform have this property. Derivatives can summarize but cannot replace. + +**Audience-format mismatch.** The source's audience does not exist (or exists thinly) on most target formats. A regulatory-technical whitepaper for compliance officers extends poorly to TikTok; the audience is not there. + +**Generic voice.** The source piece reads in default-AI or generic-content-marketing voice. Derivatives generated from a generic source compound the genericness. Without a distinctive source voice, derivatives drift further from any recognizable register. + +**No demand signal.** The source piece has not earned traffic, links, or shares. Repurposing rarely creates demand that did not exist; pieces without demand should be evaluated for whether they should have been published in the first place. + +**Highly time-bound.** The source piece is about a specific event, news cycle, or moment that will not be relevant in the cadence's timeframe. Derivatives that ship 4-6 weeks after the source may already be out of date. + +--- + +## The selection audit + +A short framework for evaluating a candidate source piece. + +1. **Read the piece's central argument or framework.** Can you state it in one sentence? If not, the piece may not extend cleanly. If yes, the argument is the spine that derivatives will extend. +2. **Identify standalone sections.** Which H2 sections work alone? If most sections work alone, blog-series and social derivatives are natural. If only one section works alone, fewer derivative formats fit. +3. **List travelable elements.** Specific examples, case studies, statistics, or claims that could anchor derivatives. Pieces with 5-10 travelable elements support multi-format extension; pieces with 0-2 do not. +4. **Check audience-format overlap.** For each candidate derivative format, is the source's audience present on the format? If most candidate formats fail this check, the source may not be a multi-format candidate. +5. **Audit voice distinctiveness.** Read three paragraphs from different sections. Could a reader who knows the brand identify this as the brand's work? If yes, derivatives have voice anchor. If no, derivatives will drift. +6. **Check demand signal.** Has the source earned traffic, links, mentions, or shares? Pieces without demand signal do not transmit demand to derivatives. +7. **Estimate extraction yield.** Given the above, how many derivative pieces could the source plausibly support? Pieces yielding 1-2 derivatives may not be worth a formal repurposing plan; pieces yielding 6-12 are clear repurposing candidates. + +--- + +## Pieces that should stay one-and-done + +Some pieces are valuable but resist repurposing. Recognizing them prevents wasted effort. + +**Tightly-argued analytical whitepapers.** Pieces whose value is in the cumulative argument. Often valuable as flagship content but produce few clean derivatives. The right disposition: ship the source piece; create one or two derivative pieces (a summary blog post, an email teaser); accept that most of the value is in the source itself. + +**Highly specific case studies.** Pieces about a single specific situation that does not generalize cleanly. The case is valuable; abstraction loses the specifics that gave the case its weight. The right disposition: ship the case study; create derivative pieces only where the case has clear teachable moments that travel. + +**Time-bound editorial.** Pieces about a specific event, news cycle, or moment. The piece may be valuable in the moment but the moment passes. The right disposition: ship; minimal repurposing during the moment; archive after. + +**Highly visual source pieces.** Pieces whose value is primarily in custom visuals (data dashboards, illustrated guides, complex diagrams). Text derivatives often cannot carry the visual value. The right disposition: derivative video and visual-format extensions only; text derivatives often underperform. + +**Niche-audience pieces.** Pieces for a small specific audience that does not exist on most other formats. The right disposition: minimal repurposing; the audience is concentrated where the source already published. + +--- + +## Tier-based selection + +Programs with regular flagship production benefit from explicit tiering of source pieces by repurposing intensity. + +**Tier 1: Major flagship (1-3 per year).** The source piece is treated as the spine of a multi-month repurposing campaign. 8-15 derivative pieces planned. Cross-format extension covers blog series, email sequence, webinar, podcast, social waves, video shorts, AI-search extractions. Capacity allocation is significant; the source's value is being maximally extracted. + +**Tier 2: Standard flagship (4-12 per year).** Source piece supports 4-8 derivative pieces. Cross-format extension covers a subset of formats: blog series or email sequence (not both), social posts, FAQ extractions for AI search. Capacity allocation is moderate. + +**Tier 3: Routine substantive piece (12-50 per year).** Source piece supports 1-3 derivative pieces. Often a social-post wave, an email mention, an internal-link refresh on related pieces. Minimal additional capacity. + +**Tier 4: One-and-done (the majority of pieces).** Source piece publishes; appears in newsletter once; shares on social once; no derivative pieces planned. Capacity allocation only on the source. + +The tiering discipline. Most programs have too few Tier 1 and Tier 2 pieces and too many Tier 3 and Tier 4 pieces masquerading as flagship work. The audit shifts capacity allocation toward the few pieces that genuinely warrant multi-format extension. + +--- + +## When a piece grows into stronger source-piece status + +Some pieces start as Tier 4 and earn promotion based on performance. + +**The signal.** A piece that was published as routine starts drawing significant traffic, earning links, getting mentioned externally, or producing reader engagement disproportionate to its production tier. + +**The response.** Promote the piece into a higher tier. Plan derivatives. Some of the strongest source pieces in mature programs are pieces that performed unexpectedly well after publication; recognizing them quickly extracts the additional value. + +**The audit.** Quarterly review of pieces' performance. Pieces showing strong demand that have not been repurposed are candidates for retroactive extraction; pieces showing weak demand that were originally tiered as flagship may need their derivative plans reduced or canceled. + +--- + +## Common selection failures + +**Repurposing every piece.** Treating all pieces as repurposing candidates spreads capacity thin. Most programs benefit from concentrating capacity on 10-20% of pieces and accepting one-and-done for the rest. + +**Repurposing the wrong pieces.** Selecting source pieces because they are easy (recent, fresh in mind) rather than because they are strong source-piece candidates. The selection audit catches this. + +**Ignoring weak-source-piece signals.** Pushing through repurposing on pieces with tightly-integrated argument, list-style structure, or no demand signal produces derivatives that fail. + +**Static tiering.** Pieces tiered at production never get re-tiered based on performance. Strong sleeper pieces never get repurposed; weak flagship pieces consume planned derivative capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The strong vs weak source-piece characteristics, the selection audit, the one-and-done dispositions, the tiering framework, the dynamic-tiering discipline, the common selection failures. + +## Implementation choices that stay internal + +Specific scoring rubrics the team uses to score source pieces. Specific dashboards that surface high-performing pieces for retroactive promotion. Specific calendar templates that allocate repurposing capacity by tier. The team's own thresholds for when a routine piece warrants Tier 2 promotion. These vary by team and program shape. diff --git a/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md b/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md new file mode 100644 index 0000000..8435836 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md @@ -0,0 +1,146 @@ +# Voice consistency across formats + +What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem and the discipline that prevents it. + +Voice is the most visible casualty of careless repurposing. The source piece may have specific voice characteristics; derivatives generated without strong voice discipline drift toward AI-default or platform-default register. Audiences detect the drift even when they cannot articulate it; the cross-format set reads as work from different brands rather than as a coherent program. + +--- + +## What stays constant + +The brand-voice elements that should survive every format adaptation. + +**The brand's POV on the topic.** If the source piece argues a specific position, the derivatives carry the same position. A derivative that hedges where the source committed, or that takes a different angle than the source, breaks the cross-format coherence. + +**Distinctive vocabulary.** Brand-specific terms, framings, and phrasings that signal "this is from this brand." If the source uses a particular word for a concept, derivatives use the same word. If the source has a recognizable phrase, derivatives carry the phrase. + +**Level of conviction or hedging.** Brands have characteristic stance positions. Some brands commit; some hedge thoughtfully; some are confrontational. The derivatives carry the brand's stance pattern even when format conventions might pull toward different stance defaults. + +**Audience-respect register.** Brands address audiences in specific ways: peer-to-peer, expert-to-novice, alongside-the-reader. The register stays consistent across formats; derivatives that suddenly talk down to the audience break voice coherence. + +**Anti-patterns the brand avoids.** If the brand does not use particular framings (motivational filler, generic-content-marketing voice, hype-driven language), derivatives also avoid them. Anti-pattern adherence is part of voice. + +--- + +## What adapts per format + +Voice elements that should adjust to the medium. + +**Sentence length and structure.** Spoken voice differs from written. Email voice differs from blog voice. Social-post voice differs from email voice. The brand's voice characteristics survive through these adaptations, but the surface-level sentence patterns change. + +- Print: medium sentences with occasional layered constructions. +- Email: shorter sentences, more direct address. +- Spoken (podcast, video): conversational rhythm with natural pauses and asides. +- Social: tight phrasing in first lines, paragraph breaks frequent. + +**Density.** Visual formats can carry less per minute than text formats. A short video cannot fit the density of a paragraph; the same point in video form has more breathing room. + +**Conversational vs declarative register.** Podcasts are conversational; whitepapers are declarative. The brand's POV stays the same in both; the framing register adapts. + +**Direct-address frequency.** "You" usage varies by format. Emails often use "you" frequently; whitepapers may use "the reader" or "marketers" more often. The shift is appropriate; pulling email voice into a whitepaper or vice versa would feel off. + +**Visual element usage.** Some formats use visuals heavily (social, video); others rely on text (email, long-form). Voice adapts to whether visuals are doing some of the work. + +--- + +## The voice audit per derivative + +A short framework for verifying voice consistency. + +1. **Read or watch the derivative as if encountering it cold.** Could a reader who knows the brand identify this as the brand's work? If yes, voice is working. +2. **Compare to the source piece.** Does the derivative carry the source's POV, vocabulary, and stance? Where it differs, is the difference appropriate format adaptation or unwanted drift? +3. **Check against the brand's voice anti-patterns.** Is the derivative slipping into framings the brand normally avoids? AI-default voice often slips in through derivatives. +4. **Check sentence-level patterns.** Sentence length, paragraph length, direct-address frequency, vocabulary. Are they format-appropriate but brand-recognizable? +5. **Read aloud (for written derivatives) or read the script (for spoken derivatives).** Does it sound like the brand's voice as the brand would speak it? + +The voice audit is one of the easiest to skip and one of the most consequential. Pieces that pass everything else but fail voice audit damage the cross-format coherence. + +--- + +## The AI-repurposing voice problem + +AI-assisted repurposing is particularly prone to voice drift. + +**The pattern.** The source piece has specific voice characteristics. AI generation of derivatives is asked to "summarize this for LinkedIn" or "turn this into emails." The AI produces derivatives that are technically related to the source but written in AI-default voice rather than the source's distinctive voice. + +**Why it happens.** AI generation regresses to model defaults unless the writer actively pulls it back. Without strong voice prompts, the derivatives sound like the AI's voice using the source's content. Multiple derivatives generated without voice anchor compound the drift; by the tenth derivative the cross-format set has lost the source's voice entirely. + +**The cure.** + +- **Voice guidelines as prompt input.** Every AI generation includes the brand voice guidelines as context. Generic prompts produce generic outputs. +- **Sample text as voice anchor.** Feed the AI 2-3 paragraphs of the source piece in their original voice. AI mimics what it sees more than what it is told. +- **Per-derivative voice review.** Each derivative gets a voice audit. Drift detected gets revision. The audit is non-negotiable. +- **Rewrite the bland.** Any sentence that could appear in any other piece on the topic gets rewritten in voice. Voice lives in the specific. + +See `ai-content-collaboration` for the broader voice-preservation discipline that applies across AI-assisted content workflows. The repurposing-specific application is that voice drift compounds across multiple derivatives in ways that single-piece AI generation does not. + +--- + +## When format conventions pull against brand voice + +Sometimes a format's conventions push toward voice that does not match the brand. + +**LinkedIn motivational tone.** LinkedIn rewards a particular kind of motivational and personal-narrative content. Brands with crisp analytical voice may resist the convention; the right answer is usually to maintain voice rather than to drift into LinkedIn-default motivational tone, even at cost of platform-specific engagement. + +**TikTok's high-energy delivery.** TikTok rewards high-energy short-form delivery. Brands with measured analytical voice may not fit naturally; the right answer may be to skip TikTok rather than to produce content that sounds wrong for the brand. + +**Podcast-host conversational warmth.** Some podcast styles reward warm conversational delivery; a brand with confrontational analytical voice may struggle to produce derivatives that fit. The right answer may be to format-fit (use a different format) or to produce derivatives that hold the brand's voice even at engagement cost. + +**The discipline.** Format-fit decisions are upstream of voice-adaptation decisions. If a format genuinely cannot accommodate the brand's voice, skipping the format is sometimes the right answer; voice integrity matters more than universal cross-format presence. + +--- + +## Voice prompts for AI-assisted repurposing + +When AI generates derivatives, the prompts should carry voice instructions. + +**Components of a voice prompt.** + +- 2-3 paragraphs of the source piece in original voice as anchor. +- A short voice description (3-5 specific characteristics). +- A short anti-pattern list (3-5 framings the brand avoids). +- Per-format adjustments (sentence length, register, direct-address frequency). + +**A worked prompt example pattern.** "The source piece below is in the brand's voice. Convert it into [target format]. The voice characteristics to preserve: [specific characteristics]. The anti-patterns to avoid: [specific anti-patterns]. The format adaptations: [format-specific]. Source piece: [text]." + +The discipline is including the voice instructions in every derivative generation, not assuming the AI will infer voice from the source alone. AI tools differ in how well they infer voice from samples; the safest discipline is explicit voice instruction. + +--- + +## Voice consistency across multiple writers or AI generators + +Programs with multiple writers or AI generators producing derivatives have a multi-source voice drift problem. + +**The risk.** Writer A produces three derivatives in slightly different voice from writer B's four derivatives, plus AI generates two more in default voice. The cross-format set has three voice variants, none of them quite the source's voice. + +**The discipline.** + +- **Single voice owner.** One person reviews all derivatives in the cross-format set for voice consistency. Catches drift across writers. +- **Voice library.** Documented brand voice with examples; all writers and AI generators reference the same library. +- **Calibration sessions.** Periodically, multiple writers (or writers plus the editorial lead) review derivatives together and reconcile voice expectations. + +Programs with sophisticated voice discipline can run multi-writer derivative production without losing voice; programs without discipline produce voice variants that audiences notice. + +--- + +## Common voice failures in repurposing + +**AI-default drift.** Derivatives sound like the AI's voice rather than the brand's voice. Cure: stronger voice prompts; per-derivative review. + +**Platform-default drift.** Derivatives sound like the platform's default register rather than the brand's voice. Cure: voice-over-platform-fit discipline; sometimes skip the platform. + +**Cross-derivative drift.** Each derivative is fine alone but the cross-format set reads as voice variants. Cure: single voice owner across the set. + +**Source-voice loss.** Derivatives carry the source's content but not the source's voice characteristics. Cure: voice anchor with sample text from the source. + +**Voice-only-on-source.** The source piece has voice; the derivatives default to generic. Cure: voice discipline applies to derivatives, not just to the source. + +--- + +## Methodology-level choices that stay in the public skill + +The constant-vs-adapting voice elements, the voice audit, the AI-repurposing voice problem and its cure, the format-vs-voice tension, the multi-writer voice discipline, the common voice failures. + +## Implementation choices that stay internal + +Specific voice-prompt templates per AI tool. Specific voice-library documentation in the team's writing system. Specific calibration session formats. Specific reviewer dashboards that surface cross-derivative voice variation. The team's own conventions for voice-vs-format tradeoffs. These vary by team, AI tooling, and brand voice maturity. diff --git a/dist/pi/.agents/skills/content-strategy/SKILL.md b/dist/pi/.agents/skills/content-strategy/SKILL.md new file mode 100644 index 0000000..dce5d9e --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/SKILL.md @@ -0,0 +1,211 @@ +--- +name: content-strategy +description: "Develop a content strategy covering editorial positioning, content pillars, formats, calendar, governance, and topical authority planning. Use this skill whenever the user wants to plan a content program, define content pillars, build an editorial calendar, structure topic clusters, set up content governance, or align content production with broader brand and SEO goals. Triggers on content strategy, content plan, editorial strategy, content pillars, content calendar, editorial calendar, topical authority, topic clusters, content governance, content roadmap, content production. Also triggers when the user is about to start producing content without a strategic plan." +category: strategy-and-discovery +catalog_summary: "Editorial strategy, content calendar, topical authority planning" +display_order: 5 +--- + +# Content Strategy + +Plan what content to produce, why, when, and how. Stack-agnostic. Works for blogs, knowledge bases, marketing sites, newsletters, and product content surfaces. + +This skill is the strategic layer. Tactical execution sits in `content-and-copy`, `landing-page-copy`, and `email-sequences`. SEO-driven content planning sits in `seo-keyword`. This skill stitches those together into a coherent program. + +--- + +## When to use + +- Planning a new content program or relaunching an existing one +- Defining editorial positioning and content pillars +- Building an editorial calendar +- Structuring topic clusters and content hubs +- Establishing content governance (review, approval, lifecycle) +- Aligning content with broader brand and revenue goals + +## When NOT to use + +- Writing specific content pieces (use `content-and-copy`) +- Writing landing pages or sales copy (use `landing-page-copy`) +- Writing email sequences (use `email-sequences`) +- Pure keyword research (use `seo-keyword`, then return here for strategic planning) +- Auditing existing content for keep/update/delete decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- Brand positioning and audience (from `brand-discovery` or `creative-brief`) +- Business goals the content needs to serve (traffic, leads, brand authority, retention) +- Existing content inventory (if any) +- Keyword research output (from `seo-keyword`) if SEO-driven +- Production capacity (writers, budget, cadence) + +If brand positioning is unclear, run `brand-discovery` first. If audience is undefined, do that work before strategy. + +--- + +## The framework: 5 layers + +A content strategy has five layers. Skip layers and the program drifts. + +### 1. Editorial positioning + +What this content program stands for. The "why we write" statement. + +**Components:** +- **Mission.** Why this content exists. One sentence. +- **Audience.** Who it serves. Specific. +- **Promise.** What readers get from us they cannot get elsewhere. +- **Distinction.** What makes this content different from the 50 other publications in the same space. + +**Example structure:** + +> We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +A strong editorial positioning forces choices. If you cannot complete the sentence, the positioning is too vague. + +### 2. Content pillars + +The 3 to 5 themes the program owns. Every piece of content belongs to a pillar. + +**Per pillar, define:** +- **Theme.** One sentence describing the topic territory. +- **Why we own it.** Audience need + brand authority + competitive opportunity. +- **Sub-topics.** 5 to 15 sub-topics that fit under the pillar. +- **Cornerstone content.** The 1 to 2 pieces that anchor the pillar (long-form, comprehensive, link-worthy). +- **Supporting content.** Articles, videos, tools, comparisons that reinforce and link to the cornerstone. + +**Pillar selection criteria:** +- Audience cares about it (research-backed, not assumed) +- Brand has credibility or can earn it +- Topical authority is achievable (you can plausibly become a top-3 source) +- Connects to revenue (directly or indirectly) +- Distinguishes you from competitors + +3 to 5 pillars is the sweet spot. Fewer than 3 risks brittleness. More than 5 dilutes focus. + +### 3. Content formats and types + +The shapes the content takes. + +**Format dimensions:** + +- **Length.** Short (under 500 words), medium (500 to 1500), long (1500 to 3000), epic (3000+) +- **Depth.** Surface (overview) vs. deep (comprehensive) +- **Type.** Article, guide, comparison, listicle, case study, interview, data study, tool, video, podcast, newsletter, social +- **Originality.** Aggregation (summarizing existing knowledge) vs. original research (new data or insight) +- **Evergreen vs. timely.** Lasting value vs. moment-driven + +**Format selection criteria:** + +- Match the audience's preferred consumption (do they read, watch, listen?) +- Match the topic (some topics demand depth; others demand brevity) +- Match production capacity +- Match distribution channels (LinkedIn favors short; YouTube favors video; SEO favors long evergreen) + +A content program typically has 3 to 5 formats it returns to consistently. More than that fragments production and brand recognition. + +### 4. Editorial calendar + +When content publishes. + +**Cadence options:** + +- **High frequency** (3+ pieces per week): builds momentum, requires significant production capacity +- **Medium frequency** (1 to 2 per week): sustainable for most teams, builds steady audience +- **Low frequency** (1 to 4 per month): each piece must be high-impact; longer production cycles +- **Burst-then-pause** (10 pieces in a month, then 3 months off): launches and campaigns + +**Calendar structure:** + +- **Pillar rotation.** If you have 4 pillars and publish weekly, each pillar gets one piece per month. +- **Content type mix.** Within a month, blend types (e.g., 2 articles + 1 case study + 1 video). +- **Timely opportunities.** Reserve flex slots for newsjacking, seasonal content, launches. +- **Updates and refreshes.** Plan time for updating existing high-performing content. + +**Common failure:** publishing whatever happens to get written. Without a calendar, the program drifts toward the topics easiest to write, not the ones the audience needs most. + +### 5. Governance and lifecycle + +How content gets made, reviewed, published, measured, and retired. + +**Production workflow:** + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +**Per stage, define:** + +- Who owns it +- What inputs they need +- What outputs they produce +- What the quality bar is +- How long it should take + +**Roles:** + +- **Editorial lead.** Owns positioning, calendar, quality bar. +- **Writers.** Produce drafts. May be in-house, freelance, or AI-assisted. +- **Subject matter experts.** Provide expertise, review for accuracy. +- **Editors.** Polish, ensure voice consistency, fact-check. +- **SEO lead.** Keyword optimization, internal linking, schema. +- **Publishers.** Ship the content (CMS, scheduling, distribution). + +**Lifecycle decisions:** + +- **Update cadence.** Top-performing evergreen content reviewed every 6 to 12 months. +- **Retire criteria.** Content that no longer serves the audience or hurts the site (use `seo-content-audit`). +- **Republishing.** Updated content republished as fresh, not buried as an update. + +--- + +## Workflow + +1. **Confirm inputs.** Brand positioning, audience, business goals, capacity. If any are missing, surface that first. +2. **Draft editorial positioning.** Mission, audience, promise, distinction. Stress-test the positioning by trying to complete the "We help X" sentence. +3. **Define content pillars.** 3 to 5. Each with a theme, justification, sub-topics, and planned cornerstone content. +4. **Choose formats.** 3 to 5 formats the program returns to consistently. +5. **Build the calendar.** Cadence, pillar rotation, format mix, flex slots. +6. **Set up governance.** Roles, workflow, quality bar, lifecycle rules. +7. **Document.** Use the template in [`references/content-strategy-template.md`](references/content-strategy-template.md). +8. **Operationalize.** Set up the editorial calendar in whatever tool the team uses (CMS, Notion, Airtable, etc.). + +--- + +## Failure patterns + +- **Strategy without capacity.** A 3-piece-per-week plan with one part-time writer fails. Match strategy to actual production capacity. +- **Pillars chosen for SEO alone.** Pillars must serve the audience and the brand, not just keyword opportunity. SEO is a downstream filter, not the strategy itself. +- **Too many pillars.** 7 pillars dilute the brand. The audience cannot remember what you stand for. +- **Calendar without governance.** Content gets produced but quality drifts. Without a quality bar, the program loses authority. +- **No update plan.** Top-performing content goes stale. Competitors with fresher versions overtake. +- **Vanity metrics.** Pageviews and follower counts without conversion tracking. Define what success looks like in business terms. +- **Strategy that lives in a doc.** A strategy document that doesn't translate to the editorial calendar and the production workflow is decoration. Operationalize or it doesn't exist. + +--- + +## Output format + +Default output is a strategy document at `content-strategy.md` plus an editorial calendar in whatever tool the team uses. + +Strategy document structure: +1. Editorial positioning +2. Content pillars (3 to 5, each detailed) +3. Formats +4. Calendar (cadence and structure, not the specific items) +5. Governance (roles, workflow, lifecycle) +6. Measurement plan (metrics, review cadence) +7. Production capacity and budget + +Editorial calendar (separate, ongoing): +- One row per planned content piece +- Columns for: title, pillar, format, target keyword (if SEO-driven), publish date, owner, status + +--- + +## Reference files + +- [`references/content-strategy-template.md`](references/content-strategy-template.md) - Strategy document template. +- [`references/editorial-calendar-template.md`](references/editorial-calendar-template.md) - Spreadsheet column definitions and calendar structure. diff --git a/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md b/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md new file mode 100644 index 0000000..2cee093 --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md @@ -0,0 +1,259 @@ +# Content Strategy: [Brand or Site Name] + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Owner:** [Editorial lead] +**Review cadence:** [Quarterly / Annually] + +--- + +## Editorial positioning + +### Mission + +[One sentence. Why this content program exists.] + +### Audience + +**Primary:** +[Specific audience segment with the depth of detail your discovery work earned.] + +**Secondary:** +[Additional segments, if any.] + +**Anti-personas:** +[Who this content is NOT for.] + +### Promise + +[What readers get from us that they cannot get elsewhere. One paragraph.] + +### Distinction + +We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +--- + +## Content pillars + +### Pillar 1: [Pillar name] + +- **Theme:** [One sentence] +- **Why we own it:** + - Audience need: [Specific need] + - Brand authority: [Why we're credible] + - Competitive opportunity: [Why this is winnable] +- **Sub-topics** (5 to 15): + - [Sub-topic] + - [Sub-topic] + - [Sub-topic] +- **Cornerstone content** (the 1 to 2 pieces that anchor this pillar): + - [Title or working title] + - [Title or working title] +- **Supporting content** (article types that link back to cornerstone): + - [Type and quantity, e.g., "5 deep-dive articles per quarter"] + +### Pillar 2: [Pillar name] +[Same structure] + +### Pillar 3: [Pillar name] +[Same structure] + +[Continue for all pillars; aim for 3 to 5] + +--- + +## Formats + +The program returns to these formats consistently. + +### Format 1: [Name, e.g., "In-depth guides"] +- **Description:** [What it is] +- **Length:** [Word count or duration range] +- **Cadence:** [How often we produce one] +- **Use case:** [When this format wins] + +### Format 2: [Name] +[Same structure] + +### Format 3: [Name] +[Same structure] + +[Continue for all formats; aim for 3 to 5] + +--- + +## Editorial calendar structure + +### Cadence + +**Frequency:** [N pieces per week/month] + +**Reasoning:** [Why this cadence; what it can sustainably support] + +### Pillar rotation + +[How pillars rotate through the calendar. Example: 4 pillars, weekly publishing, each pillar gets one piece per month.] + +### Format mix + +[Within a typical month, what's the format breakdown?] + +Example: +- 2 articles +- 1 case study or interview +- 1 longer guide or data study +- Plus: 1 newsletter (ongoing, separate cadence) + +### Flex slots + +[How much of the calendar is reserved for timely content, news jacking, or campaign launches?] + +Typical: 70% planned, 20% flex, 10% updates to existing content. + +### Updates and refreshes + +[Plan for refreshing top-performing content. Typically every 6 to 12 months for evergreen pillars.] + +--- + +## Governance + +### Roles + +| Role | Owner | Responsibility | +|---|---|---| +| Editorial lead | [Name] | Strategy, calendar, quality bar | +| Writer (in-house or freelance) | [Name(s) or agency] | Drafts | +| Subject matter expert | [Name(s)] | Expertise, accuracy review | +| Editor | [Name] | Polish, voice consistency, fact-check | +| SEO lead | [Name] | Keyword optimization, internal linking, schema | +| Publisher | [Name] | CMS publication, scheduling, distribution | + +### Production workflow + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +| Stage | Owner | Inputs | Outputs | Quality bar | Time estimate | +|---|---|---|---|---|---| +| Idea | | | | | | +| Brief | | | | | | +| Outline | | | | | | +| Draft | | | | | | +| Edit | | | | | | +| Review | | | | | | +| Publish | | | | | | +| Measure | | | | | | +| Update or retire | | | | | | + +### Quality bar + +Every piece of published content meets these standards: +- [ ] Aligned with a defined content pillar +- [ ] Targets a specific audience need +- [ ] Voice and tone consistent with brand standards +- [ ] Factually accurate (sources cited where appropriate) +- [ ] SEO basics handled (title, meta, headers, internal links) +- [ ] Schema applied for the content type +- [ ] Edited by someone other than the writer +- [ ] Reviewed by the editorial lead + +### Lifecycle rules + +- **Update trigger:** A top-performing evergreen piece reviewed when [trigger, e.g., "stats are 12 months old" or "competitive landscape shifts"] +- **Retire trigger:** A piece is retired (deleted, redirected, or merged) when [trigger, e.g., "no traffic for 12 months and no backlinks"] +- **See also:** `seo-content-audit` for the keep/update/merge/redirect/delete framework + +--- + +## Measurement plan + +### Primary metrics + +| Metric | Target | Reporting cadence | +|---|---|---| +| Organic traffic | | Monthly | +| Email subscribers | | Monthly | +| Conversions from content | | Monthly | +| [Custom metric] | | | + +### Secondary metrics (signals) + +- Engaged sessions (sessions over 60 seconds) +- Scroll depth on long-form content +- Internal click-through from articles to commercial pages +- Backlinks earned per piece +- Time on page distribution +- Returning reader rate + +### Review cadence + +- **Weekly:** Calendar status check +- **Monthly:** Performance metrics review, calendar adjustments +- **Quarterly:** Strategy review, pillar performance, capacity check +- **Annually:** Full strategy refresh, audience research re-validation + +--- + +## Production capacity and budget + +### Capacity + +- Writers: [number, FTE or freelance, hours per week] +- Editors: [number, hours per week] +- Subject matter experts: [availability] +- Designers/illustrators (if needed): [availability] + +### Budget + +- Internal labor: [budget] +- Freelance writers: [per piece or per month] +- Subject matter expert honoraria (if external): [per piece] +- Imagery, illustration, video: [per piece or monthly] +- Tools and platforms: [monthly] + +### Output capacity at this budget + +[Realistic monthly output given the budget. Better to plan conservatively and exceed it than over-promise and under-deliver.] + +--- + +## Distribution + +Content does not earn its audience by being published. List the distribution channels and the standard process for promoting each piece. + +### Channels + +- Owned: site, email, social profiles +- Earned: PR, partnerships, expert mentions +- Paid (if budget): boosted social, sponsored newsletter slots + +### Per-piece distribution checklist + +When a new piece publishes: + +- [ ] Posted to social channels with [N] variations +- [ ] Included in next newsletter +- [ ] Sent to relevant internal stakeholders for sharing +- [ ] Outreach to [N] external mentions or backlink targets +- [ ] Submitted to relevant communities (forums, niche aggregators) +- [ ] Internal link added from [related cornerstone content] + +--- + +## Open questions + +[Things that still need to be decided before this strategy is fully operational.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial strategy | diff --git a/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md b/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md new file mode 100644 index 0000000..15509c3 --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md @@ -0,0 +1,214 @@ +# Editorial Calendar Template + +A spreadsheet column definition and calendar structure for content planning. Use as a setup spec for a new editorial calendar in any tool (Sheets, Airtable, Notion, Linear, Asana). + +The calendar is not the strategy. The calendar is the strategy made operational. If a strategy decision is missing, the calendar will reveal it. + +--- + +## Calendar structure + +### Single source of truth + +The editorial calendar is one document. Not five. If the team uses multiple tools (writing in Notion, scheduling in Buffer, etc.), one tool is the source of truth and the others mirror it. + +The source of truth answers, at a glance: + +- What is being published this week? +- What is in production right now? +- What is committed for the next quarter? +- What is the backlog? +- Who owns each piece? + +--- + +## Required columns + +Every row is one piece of content. Every column below is required. + +| Column | Type | Description | +|---|---|---| +| **ID** | Text or auto-number | Unique identifier per piece. Used in cross-references. | +| **Title (working)** | Text | Working title. Final title can change at publish. | +| **Type** | Pick list | Article / guide / case study / video / podcast / email / social series / landing page / etc. | +| **Topic cluster** | Pick list | Which content cluster this piece belongs to (from the strategy doc). | +| **Stage of funnel** | Pick list | Awareness / Consideration / Decision / Retention / Advocacy. | +| **Primary audience** | Pick list | Maps to defined segments. | +| **Primary keyword** | Text | The query target if SEO-relevant. | +| **Search intent** | Pick list | Informational / commercial / navigational / transactional. (See `seo-keyword/references/intent-classification-guide.md`.) | +| **Primary CTA** | Text | What action should the reader take? | +| **Channels** | Multi-select | Web, email, organic social, paid, partnerships. | +| **Owner (writer)** | Person | Who drafts. | +| **Editor** | Person | Who reviews. | +| **Reviewer (SME)** | Person | Subject matter expert if needed. | +| **Approver** | Person | Who signs off before publish. | +| **Status** | Pick list | See status workflow below. | +| **Brief due date** | Date | When the brief should be ready. | +| **Draft due date** | Date | When the draft should be ready. | +| **Edit due date** | Date | When edits should be done. | +| **Publish date (target)** | Date | The intended publish date. | +| **Publish date (actual)** | Date | When it actually went live. | +| **Brief link** | URL | Link to the content brief document. | +| **Draft link** | URL | Link to the working draft. | +| **Final link** | URL | Live URL after publish. | +| **Performance notes** | Text | Updated 30 / 60 / 90 days post-publish. | + +--- + +## Optional but recommended columns + +| Column | Description | +|---|---| +| **Estimated effort (hours)** | For capacity planning. | +| **Tag(s)** | Cross-cutting tags beyond cluster (e.g., "originals research," "thought leadership," "evergreen"). | +| **Related pieces** | IDs of companion pieces (series, follow-ups, redirects). | +| **Distribution plan link** | Specific plan for how this piece is amplified post-publish. | +| **Repurpose plan** | What this becomes downstream (newsletter, social cuts, video). | +| **Source / inspiration** | Where the idea came from (data, customer ask, competitor gap, etc.). | +| **Cost** | If freelance or paid placement. | + +--- + +## Status workflow + +Every piece moves through these statuses, in this order. + +| # | Status | Meaning | Exit criteria | +|---|---|---|---| +| 1 | **Idea** | Captured but not committed. | Idea passes the prioritization screen. | +| 2 | **Backlog** | Committed for some future quarter. | Scheduled for a specific quarter. | +| 3 | **Scheduled** | Targeted for a publish week. | Brief assigned. | +| 4 | **In brief** | Brief being written. | Brief approved. | +| 5 | **In draft** | Writer is drafting. | Draft submitted to editor. | +| 6 | **In edit** | Editor reviewing. | Edits accepted by writer. | +| 7 | **In review** | SME and approver reviewing. | All approvals received. | +| 8 | **Ready to publish** | Final, scheduled in CMS. | Publish date arrives. | +| 9 | **Published** | Live. | (Terminal) | +| 10 | **Killed** | Decided not to ship. | (Terminal, with reason recorded) | + +### Why this matters + +If 30 pieces are sitting in "In draft" for 6 weeks, the bottleneck is writers. If 20 are in "In review," the bottleneck is approvers. The calendar exposes pipeline health, not just publish dates. + +--- + +## Calendar views + +The same data, sliced different ways. Each view answers a different question. + +### Calendar view (by week) + +Columns: weeks. Rows: channels (web, email, social). + +Used for: planning rhythm, spotting overlap and gaps. + +### Pipeline view (by status) + +Columns: status. Rows: pieces. + +Used for: identifying bottlenecks. + +### Owner view (by writer / editor) + +Columns: people. Rows: pieces. + +Used for: workload balancing. + +### Cluster view (by topic cluster) + +Columns: clusters. Rows: pieces in pipeline + already published. + +Used for: ensuring topical authority is being built coherently. + +### Funnel view (by funnel stage) + +Columns: stage. Rows: pieces. + +Used for: ensuring balance across funnel. + +### Performance view (post-publish) + +Columns: traffic, conversions, time on page, social shares. Rows: published pieces. + +Used for: retrospective and topic prioritization for next cycle. + +--- + +## Cadence rituals + +The calendar is reviewed on a rhythm. + +| Ritual | Cadence | Attendees | Purpose | +|---|---|---|---| +| **Daily standup** | Daily, 15 min | Editorial team | What is shipping today, blockers. | +| **Weekly editorial planning** | Weekly | Content lead + writers | Confirm next 2 weeks, surface blockers, accept new ideas. | +| **Monthly review** | Monthly | Content team + marketing lead | Look at last month's pipeline, performance, and adjust the next month. | +| **Quarterly planning** | Quarterly | Content team + cross-functional | Plan the next quarter's content based on strategy and last quarter's data. | +| **Annual review** | Annually | All stakeholders | Review the year's themes, performance, and rebuild the strategy. | + +--- + +## Capacity planning + +Use the calendar to plan capacity, not just track output. + +### Throughput math + +- **Available writer time per week:** writers × hours allocated to writing +- **Average effort per piece:** hours from "Idea" to "Ready to publish" +- **Throughput:** available time ÷ effort + +If planned output exceeds throughput, the calendar will reveal it as drift (slipped dates, deferred backlog). + +### Buffer + +Real teams hit 70-80% of planned throughput. Plan to 70%. Treat the remaining 30% as buffer for inevitable surprises (priority shifts, sick days, longer-than-expected reviews). + +--- + +## Backlog management + +The backlog is not a wishlist. It is a curated set of committed-but-not-scheduled ideas. + +- Cap the backlog at 3-6 months of throughput. Beyond that, ideas go stale. +- Re-rank quarterly using the strategy doc's prioritization criteria. +- Kill backlog items that no longer match the strategy. Killing is a feature, not a failure. + +--- + +## Killed pieces + +When a piece is killed, record: + +- Date +- Reason (strategy shifted, owner left, evidence the piece would not perform, redundant with another piece) +- What happens to the brief or partial draft (archive, salvage for another piece, delete) + +Killed pieces inform future filtering. + +--- + +## Performance review + +For every published piece, update the calendar with performance at 30 / 60 / 90 days. Capture: + +- Sessions / pageviews +- Conversion events (CTAs clicked, signups, purchases) +- Time on page or read depth +- Social shares +- Backlinks earned +- Notes on what worked or did not + +Aggregate quarterly to inform the next quarter's plan. + +--- + +## Sign-off + +Calendar setup approved by: + +- Content lead: [Name, date] +- Marketing lead: [Name, date] +- Tooling owner: [Name, date] + +Calendar lives at: [URL] diff --git a/dist/pi/.agents/skills/cost-optimization/SKILL.md b/dist/pi/.agents/skills/cost-optimization/SKILL.md new file mode 100644 index 0000000..2f44efb --- /dev/null +++ b/dist/pi/.agents/skills/cost-optimization/SKILL.md @@ -0,0 +1,339 @@ +--- +name: cost-optimization +description: "Audit and reduce infrastructure and tooling costs without sacrificing reliability or velocity. Use this skill when reviewing monthly cloud or SaaS spend, finding unused resources, rightsizing infrastructure, negotiating vendor contracts, deciding what to consolidate, or planning for budget cuts. Triggers on cost optimization, cloud spend, SaaS spend, rightsizing, unused resources, FinOps, infrastructure audit, vendor consolidation, budget cut, cost review. Also triggers when finance flags rising costs or when a contract renewal is up." +category: cross-cutting +catalog_summary: "Infrastructure spend audits, rightsizing, contract negotiation" +display_order: 5 +--- + +# Cost Optimization + +Audit cloud, SaaS, and infrastructure spend. Cut what's not earning its keep. Rightsize what's oversized. Negotiate what's negotiable. Without breaking what works. + +--- + +## When to use + +- Quarterly or annual cost review +- Finance flags rising spend +- Vendor contract renewal coming up +- Budget cut required +- New leadership wants the numbers +- Migrating between providers (cost is part of the case) +- Audit before scaling significantly (catch waste before it scales) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Performance issues that happen to involve infrastructure (use `performance-optimization`) +- Vendor evaluation for a new purchase (use `vendor-evaluation`) +- Personnel or org costs (out of scope for this skill) + +--- + +## Required inputs + +- Current cost (monthly, ideally for the last 12 months) +- Cost broken down by service or vendor +- Inventory of cloud resources (instances, databases, storage, etc.) +- Inventory of SaaS subscriptions +- Owners per cost line (who decided to spend this, who uses it) +- Constraints (compliance, performance, contract terms) + +--- + +## The framework: 5 levers + +Every cost optimization opportunity falls into one of these levers. + +### Lever 1: Eliminate + +Stop paying for things that aren't used. + +- Idle resources (instances, databases, environments running but unused) +- Subscriptions where no one logs in +- Duplicate tools (multiple tools doing the same job) +- Old projects still incurring cost +- Test environments that should have been torn down +- Forgotten domains, backups, snapshots, logs + +This is usually the largest opportunity in the first audit. Often 10-30% of spend. + +### Lever 2: Rightsize + +Pay for what you actually use, not what you provisioned for the worst case three years ago. + +- Oversized instances (CPU and memory utilization low) +- Over-provisioned databases (storage and throughput far above usage) +- Over-purchased SaaS seats +- Premium plans where standard would suffice +- High-availability setups for non-critical systems + +Rightsizing requires real usage data, not theoretical needs. + +### Lever 3: Restructure + +Use cheaper structures for the same workload. + +- Reserved or committed-use pricing (1-3 year commitments at 30-70% discount) +- Spot or preemptible instances for fault-tolerant work +- Cold storage for data accessed rarely +- Tiered storage (hot/warm/cold) by access pattern +- CDN caching to reduce origin load +- Compression and deduplication +- Serverless for spiky workloads +- Reserved instances for steady workloads + +The right structure depends on the access pattern. Mismatch costs money. + +### Lever 4: Negotiate + +Pay less for the same thing. + +- Annual contracts at lower rates than monthly +- Volume discounts at higher tiers +- Multi-year commitments for predictable workloads +- Bundle deals (consolidating services with one vendor) +- Renewal negotiation (vendors expect you to ask) +- RFP / competitive bid (using alternatives as leverage) + +Most enterprise vendors negotiate. Most SaaS vendors don't, except at higher tiers. Consumer-tier services usually don't. + +### Lever 5: Reframe + +Change the question. + +- Build vs buy: maybe in-house is cheaper at scale +- Buy vs build: maybe outsourcing is cheaper at small scale +- Different architecture (e.g., monolith vs microservices) has different cost profiles +- Different audience (do all customers need the same tier?) +- Different stack (open source vs commercial) + +Reframe is the longest-lead lever. Worth thinking about even if not actionable now. + +--- + +## Workflow + +### Step 1: Pull the spend data + +Get monthly costs by service, vendor, and (where possible) team or project. + +For cloud (AWS, GCP, Azure): the billing console and cost-explorer tools. +For SaaS: each vendor's billing portal, plus an SaaS-management tool if available. +For everything else: bank statements and accounting export. + +12 months minimum. Trends matter as much as absolute numbers. + +### Step 2: Categorize + +Organize spend into categories: + +- **Hosting / compute** +- **Storage** +- **Database** +- **Networking / CDN** +- **Monitoring / observability** +- **Email** +- **CMS / hosting platforms** +- **Analytics / marketing** +- **Productivity / collaboration** +- **Development tools** +- **Security / compliance** +- **Other** + +The categories vary by business. The point is: similar costs grouped, easy to compare. + +### Step 3: Identify the biggest line items + +80/20 rule. Usually 20% of vendors account for 80% of spend. + +Focus the audit on the top 80%. The long tail can be cleaned up but rarely yields big savings per item. + +### Step 4: Apply the 5 levers + +For each major line item, walk the levers: + +| Lever | Question | +|---|---| +| Eliminate | Is it used? Could we stop using it? | +| Rightsize | Are we paying for capacity we don't use? | +| Restructure | Is there a cheaper pricing model or service tier? | +| Negotiate | When was the last renewal? Did we negotiate? | +| Reframe | Is this even the right approach? | + +Document the opportunity, the effort, the risk, and the savings estimate. + +### Step 5: Prioritize + +Plot opportunities on a 2x2: +- Y axis: savings +- X axis: effort + +Quadrants: +- High savings, low effort: do first +- High savings, high effort: plan +- Low savings, low effort: do as time allows +- Low savings, high effort: skip + +Also consider risk: +- Eliminate something used by no one: low risk +- Rightsize a database: medium risk (test in staging first) +- Replace a critical dependency: high risk (plan carefully) + +### Step 6: Execute the easy wins + +For each easy-win opportunity: +- Document the change +- Get owner approval +- Make the change +- Monitor for unexpected impact +- Confirm cost reduction in next billing cycle + +Easy wins typically include: +- Canceling unused subscriptions +- Tearing down idle resources +- Switching off dev environments outside business hours +- Moving cold data to cheaper storage tiers + +### Step 7: Plan the larger work + +For higher-effort opportunities: +- Spec the change (use `pm-spec-writing` for the plan) +- Test in staging +- Roll out incrementally +- Validate cost impact + +Examples: +- Migrating to reserved instances +- Consolidating monitoring vendors +- Migrating from one CMS to another with cost benefit + +### Step 8: Set up ongoing visibility + +Optimization isn't one-time. Costs creep back up. + +- Monthly cost review (at least) +- Cost dashboard (current, trend, by category) +- Alerts on cost spikes (e.g., daily spend exceeds threshold) +- Tagging or labeling on cloud resources (cost by team or project) +- Quarterly deeper review + +### Step 9: Negotiate at renewal + +For vendor contracts up for renewal: +- Start the conversation 60-90 days before renewal +- Have alternatives identified (even if you don't switch) +- Ask for a multi-year discount +- Ask about volume tiers +- Ask if usage rightsizing is possible +- Be willing to walk (most vendors find a way to keep you) + +Pre-pandemic, many vendors auto-renewed at increases. Post-pandemic, many are hungry for retention. Ask. + +### Step 10: Document the policy + +Going forward: +- New vendor evaluation requires cost justification +- Resource provisioning has approval thresholds +- Tagging and labeling are required for cloud resources +- Quarterly review is calendared +- Cost attribution is clear + +Without policy, costs creep. + +--- + +## Common opportunities by category + +### Hosting and compute + +- Reserved or committed-use pricing for predictable workloads (30-70% off) +- Spot or preemptible for fault-tolerant batch +- Auto-scaling for variable loads +- Right instance family (compute-optimized, memory-optimized, etc.) +- Dev/staging instances stopped outside business hours + +### Storage + +- Lifecycle policies to move old data to cheaper tiers +- Delete old logs, backups, snapshots +- Compression for archival +- Object versioning costs (every version is a stored object) + +### Database + +- Right size based on actual CPU/memory usage +- Reserved capacity for predictable workloads +- Read replicas for read-heavy workloads (cheaper than scaling primary) +- Drop unused indexes (indexes cost storage and write performance) +- Old data archived or deleted + +### Networking and CDN + +- CDN reduces origin egress costs (often the biggest cost category) +- Compression on the wire +- Image and video optimization +- Region-aware routing + +### Monitoring and observability + +- Sample logs (don't ingest 100% of high-volume sources) +- Retention policies (do you need 90 days or 30?) +- Consolidate tools where possible +- Free or open-source tooling for non-critical needs + +### SaaS + +- Audit logins per seat (inactive users on $X/seat = $X waste) +- Renegotiate at renewal +- Move to annual billing for the discount +- Consolidate overlapping tools + +--- + +## Failure patterns + +**Cost-cutting that breaks something.** Aggressive rightsizing without testing causes outages. The cost of an outage is usually larger than the savings. + +**Optimization that takes more time than it saves.** A team spends a quarter saving $5K/year. Math doesn't work. Focus on opportunities where savings exceed effort. + +**Renewal autopilot.** Annual renewals go through without review. Calendar them. + +**No tagging.** Cloud spend grows; no one knows whose. Tag everything from day one. + +**Free tier overruns.** "It's on the free tier." Then it's not, and bills surprise. Set alerts on free-tier services. + +**No environment differentiation.** Production-grade staging "to match prod." Costs as much as prod. Often unnecessary. + +**Untouched legacy.** "The old project still runs." Why? Often: nothing actually uses it. Audit and shut down. + +**Premium tiers for non-premium needs.** Enterprise plan because someone wanted a feature that's been since added to lower tiers. Recheck. + +**Vendor lock-in justifying cost.** "We can't switch." That's not a reason to overpay; it's a strategic problem to plan around. + +**Optimizing the small stuff while ignoring the big stuff.** Saving $50/month on tools while $5K/month sits in oversized infrastructure. Top-down first. + +**Penny-wise, pound-foolish.** Cutting a useful tool to save $20/month, then losing hours to manual work. Tools that pay for themselves shouldn't be cut. + +**No reinvestment.** Every dollar saved goes to bottom line; nothing reinvested in upgrades or capacity. Saved costs and improved capability aren't either/or. + +--- + +## Output format + +A cost optimization document includes: + +- **Current state:** total spend, by category, trended +- **Top line items:** the biggest costs +- **Opportunities:** by lever (eliminate / rightsize / restructure / negotiate / reframe) +- **Prioritized list:** with savings, effort, risk +- **Action plan:** owners, dates +- **Easy wins executed:** what's already done, results +- **Ongoing governance:** dashboard, review cadence, tagging, approval thresholds + +--- + +## Reference files + +- [`references/cloud-audit-checklist.md`](references/cloud-audit-checklist.md): A practical walkthrough for auditing a cloud account (compute, storage, database, network, monitoring) for waste and rightsizing opportunities. diff --git a/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md b/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md new file mode 100644 index 0000000..1265c60 --- /dev/null +++ b/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md @@ -0,0 +1,292 @@ +# Cloud Audit Checklist + +A practical walkthrough for auditing a cloud account for waste and rightsizing opportunities. Stack-agnostic in principle; the categories apply across AWS, GCP, Azure, and others. + +Allow about a half-day for a first audit. Subsequent audits go faster. + +--- + +## Setup + +- [ ] Pull the last 12 months of billing data +- [ ] Pull current resource inventory (compute, storage, database, networking) +- [ ] Identify owners per service or project +- [ ] Note any compliance or contractual constraints + +--- + +## Compute + +### Identify idle and underused + +- [ ] Instances with CPU utilization below 10% over 30 days +- [ ] Instances stopped but still incurring some charges (storage, IPs, etc.) +- [ ] Instances running 24/7 that only need business hours +- [ ] Instances forgotten from old projects +- [ ] Instances spun up for a one-time task and never deleted + +For each: identify owner. Confirm it's not needed. Stop or delete. + +### Rightsize active instances + +- [ ] Instances with CPU peaks under 40% (probably oversized) +- [ ] Instances with memory underused +- [ ] Instances of older generation (newer generations often cheaper for same performance) +- [ ] Instances of wrong family (compute-optimized when memory-optimized would be cheaper) + +For each: test smaller size in staging. Roll out gradually. + +### Pricing structure + +- [ ] On-demand instances with stable load (candidates for reserved or savings plans) +- [ ] Workloads that could tolerate interruption (candidates for spot/preemptible) +- [ ] Long-running workloads with no commitment (candidate for committed-use discounts) + +Reserved/committed: 30-70% discount for 1-3 year commitment. +Spot/preemptible: 60-90% discount, can be terminated by provider. + +### Auto-scaling + +- [ ] Auto-scaling configured for variable workloads (vs always-on at peak size) +- [ ] Scaling policies actually scale down (some only scale up) +- [ ] Min size set appropriately (not over-provisioned) + +--- + +## Storage + +### Identify unused + +- [ ] Snapshots not used in 6+ months +- [ ] Disks unattached to any instance +- [ ] Buckets accessed never or rarely (per access logs) +- [ ] Old log archives no one queries +- [ ] Old backups beyond retention requirements + +For each: confirm it's not needed. Delete or archive. + +### Lifecycle policies + +- [ ] Hot data only for recent access +- [ ] Move data to warm tier after [N] days +- [ ] Move to cold/archive tier after [M] days +- [ ] Delete after [P] days (if compliant) + +Lifecycle policies are set-once, save-forever. High ROI for the time invested. + +### Storage class + +- [ ] Verify storage class matches access pattern + - Frequently accessed: standard + - Infrequent: IA / nearline + - Rarely: cold / archive + - Compliance-only: deep archive + +Mismatched storage class is a common waste category. + +### Versioning + +- [ ] Object versioning is on intentionally (not accidentally) +- [ ] Old versions cleaned up via lifecycle policy +- [ ] Soft-delete retention is finite (not indefinite) + +Versioned buckets can accumulate massive cost from old versions. + +--- + +## Database + +### Identify underused + +- [ ] Databases with low CPU/memory usage over 30 days +- [ ] Databases with low connection counts +- [ ] Databases that could be smaller instance class +- [ ] Read replicas no longer needed +- [ ] Databases for old projects + +### Rightsize storage + +- [ ] Storage allocated far above used +- [ ] Auto-scaling on for storage (avoid manual oversizing) +- [ ] Old logs and audit data cleaned up + +### Backup retention + +- [ ] Backup retention matches RPO (not aspirational, not excessive) +- [ ] Manual snapshots cleaned up (often outlive their purpose) + +### Pricing structure + +- [ ] Reserved capacity for steady workloads +- [ ] Spot/preemptible for non-critical analytics + +### Indexes + +- [ ] Unused indexes dropped (each index costs storage and write performance) +- [ ] Indexes match query patterns (use database tooling to identify) + +--- + +## Networking + +### Egress + +Egress (data leaving the cloud or moving across regions) is often the most surprising cost. + +- [ ] Egress to internet (largely user traffic; CDN can reduce) +- [ ] Egress between regions (often unintended; check architecture) +- [ ] Egress between availability zones (matters at scale) +- [ ] NAT gateway charges (per-GB; can be huge for high-traffic egress) + +Reduce egress with: +- CDN caching (origin egress drops dramatically) +- Compression +- Multi-region only when needed (single-region egress is often cheaper) +- VPC endpoints for cloud-internal traffic (avoid going out and back in) + +### Load balancers + +- [ ] Idle or unused load balancers +- [ ] Load balancer count appropriate (don't run 5 when 1 works) +- [ ] Load balancer type matches use (application LB vs network LB; pricing differs) + +### Public IPs + +- [ ] Idle elastic IPs (charged when not attached) +- [ ] Public IPs that should be private + +### CDN + +- [ ] CDN in front of high-traffic origin +- [ ] Cache hit rate measured (low cache hit = wasted CDN, untrained origin) +- [ ] Compression and image optimization on at the CDN + +--- + +## Monitoring and logs + +### Log volume + +- [ ] Logs ingested but never queried +- [ ] Verbose logging in production (debug level by accident) +- [ ] Logs from low-importance services at full volume + +Sample or filter where possible. High-volume logs can dominate observability bills. + +### Retention + +- [ ] Retention matches need (do you query 90-day-old logs?) +- [ ] Compliance retention separate from operational retention (compliance can use cheaper storage) +- [ ] Aggregated metrics retained longer than raw logs (cheaper, often sufficient) + +### Tooling + +- [ ] Multiple monitoring tools doing the same job +- [ ] Premium tier when standard would suffice +- [ ] Per-host pricing on tools where utilization is low + +--- + +## Specialty services + +### Search (Elasticsearch, Algolia, etc.) + +- [ ] Indexes for old data still queried? +- [ ] Replicas appropriate for traffic +- [ ] Tier matches need + +### Cache (Redis, Memcached) + +- [ ] Cache hit rate measured (low hit = expensive cache delivering little value) +- [ ] Cache size appropriate +- [ ] TTLs reasonable + +### Queue / streaming (Kafka, Kinesis, SQS) + +- [ ] Throughput matches actual load +- [ ] Retention matches need +- [ ] Idle streams or topics cleaned up + +### Email / SMS / push + +- [ ] Volume matches projection +- [ ] Per-message pricing tier appropriate +- [ ] Old or low-engagement contacts removed (don't pay to send to non-recipients) + +--- + +## Account-level + +### Multiple accounts + +- [ ] Account count matches need (separation of concerns is good; sprawl is wasteful) +- [ ] Consolidated billing enabled (volume discounts across accounts) +- [ ] Inactive accounts decommissioned + +### Tagging + +- [ ] Tags applied to all resources +- [ ] Tags consistent (team, project, environment, cost center) +- [ ] Untagged resources have owners identified + +### Budgets and alerts + +- [ ] Budget alerts configured (e.g., alert at 80% of monthly target) +- [ ] Anomaly detection enabled (alert on unusual cost spikes) +- [ ] Per-team or per-project budgets where possible + +--- + +## Findings document + +For each finding, capture: + +| Field | Example | +|---|---| +| Description | "Production database is 8xlarge; CPU peaks at 25%" | +| Category | Compute / storage / database / network / etc. | +| Lever | Eliminate / rightsize / restructure / negotiate / reframe | +| Estimated savings | $/month | +| Effort | Hours/days | +| Risk | Low / medium / high | +| Owner | Person or team | +| Action | Specific next step | + +--- + +## Prioritization + +After all findings: + +| Priority | Description | +|---|---| +| P0 | Easy, high savings, low risk: do this week | +| P1 | Medium effort, high savings: plan this quarter | +| P2 | Easy, low savings: do as time allows | +| P3 | High effort, low savings: deprioritize | + +Reserved instances and committed-use discounts often appear as P0/P1: high savings, structured effort. + +--- + +## Tracking + +After acting, track: +- Savings achieved (compare next billing cycle to baseline) +- Issues caused (any rollbacks needed?) +- Time spent +- Lessons for next audit + +Cost reductions sometimes appear gradually (e.g., reserved purchase smooths in). Track over 2-3 billing cycles. + +--- + +## Maintenance + +- [ ] Set monthly cost review (15-30 min, look at trends) +- [ ] Set quarterly deeper audit (this checklist, abbreviated) +- [ ] Set annual full audit (this checklist, full) +- [ ] Set renewal calendar (each major contract, with reminder 90 days out) +- [ ] Tag governance (new resources require tags, untagged flagged) + +Cost optimization is ongoing, not one-time. Without maintenance, savings reverse. diff --git a/dist/pi/.agents/skills/creative-brief-selector/SKILL.md b/dist/pi/.agents/skills/creative-brief-selector/SKILL.md new file mode 100644 index 0000000..64d4a99 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/SKILL.md @@ -0,0 +1,112 @@ +--- +name: creative-brief-selector +description: "Produce a creative brief grounded in live reference sites and deliberately distinct from existing demos, for any new brand build. Composes with brand-archetype-system and creative-direction. Use this skill at the start of any brand or microsite build when the result needs to land in a specific aesthetic position and not drift into a default house style. Triggers on creative brief, design brief, build brief, brand direction, where should this brand sit, what should this site look like, reference sites for, archetype for, distinct from our other brands, divergence from prior, not the same as. Also triggers when prior builds have come out as siblings and a systematic divergence approach is needed." +category: brand +catalog_summary: "Live-reference-grounded creative briefs with divergence check against prior builds" +display_order: 6 +--- + +# Creative Brief Selector + +A starting-point selector for brand and microsite builds. Given a business spec (name, vertical, shape, one-line vibe, optional list of shipped demos), produces a creative brief grounded in three things: + +1. An archetype position from `brand-archetype-system`, picked or composed to be deliberately distinct from the shipped demos. +2. A small set of live reference sites for that archetype-and-vertical combination, drawn from a curated bank plus optional per-build discovery. +3. A divergence check against the shipped demos that flags palette, voice, structural pattern, and section-shape overlap before the brief is handed off. + +The brief output is concrete tokens, not abstract families, including explicit section-shape choices (hero shape and footer shape) as first-class outputs alongside palette and voice. It is meant to be loaded by downstream build skills as the single creative artifact for the build. + +--- + +## When to use + +- Starting any new brand or microsite build that should land in a specific aesthetic position. +- The first build in a portfolio (no prior builds to diverge from yet, but the divergence schema can be seeded for the next one). +- The second through nth build in a portfolio, where the risk of sibling output is real. +- After a portfolio audit that surfaced sibling builds: this skill is the systemic fix for the pattern. +- When a build's creative direction is being chosen between two adjacent archetypes and the call needs a reference-grounded reason. + +## When NOT to use + +- The user wants pure aesthetic methodology guidance (use `creative-direction`). +- The user has a finished archetype and a finished brief and is asking for execution (skip to the downstream build skills). +- The user wants a logo or a finished identity (use `logo-design`, `brand-identity`). +- The user wants to define voice for an existing brand (use `brand-voice`). +- Defining brand strategy from zero positioning (use `brand-ideation` first, then return to this skill). + +--- + +## How this composes with other skills + +This skill works upstream of build-time skills and parallel to the aesthetic methodology layer: + +- **`brand-archetype-system`** (upstream input). The archetype catalog this skill picks from. The skill names the archetype in the rendered brief; it does not redefine the archetype's defaults. +- **`creative-direction`** (parallel input). The four-axis vocabulary the archetypes reference. If the consumer needs the full axis brief, run `creative-direction` first; this skill's brief consumes its outputs. +- **`brand-identity`** (downstream). Once the brief is approved, brand-identity turns it into a finished identity system. +- **`landing-page-copy`, `content-and-copy`, `art-direction`** (downstream). Every downstream skill that produces aesthetic output references this skill's brief. + +Direct verbatim copying of an archetype's default palette into a new brand is the failure mode this skill exists to prevent. The brief shifts the archetype's defaults toward the business spec's specifics. + +--- + +## The framework: five steps, three rules, one hybrid bank + +1. **Locate the design space.** Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. +2. **Run input-side divergence.** Read the shipped-demos signatures. Discard candidates that would land sibling to anything shipped. Record what was rejected and why. +3. **Pull references.** From the curated reference bank under `references/reference-bank/`, load the file(s) matching the chosen archetype-and-vertical. Augment with one to two discovered live references if the bank is sparse. Add discovered references back to the bank in the build PR. +4. **Adapt.** Shift the chosen archetype's defaults (palette, type, voice, layout, imagery direction) toward the business spec. The brief lands as concrete tokens, not abstract families. +5. **Render and verify.** Render the brief using the template in [`references/02-brief-template.md`](references/02-brief-template.md). Run output-side divergence. Output the brief plus the references list plus the divergence-check result. + +Full step-by-step in [`references/01-process.md`](references/01-process.md). The divergence schema and its three overlap rules are in [`references/03-divergence-check.md`](references/03-divergence-check.md). + +--- + +## The hybrid references model + +A curated bank that grows with each build. Each file under `references/reference-bank/` covers one archetype-and-vertical combination and holds three to six live reference URLs, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations covering western-boot maker, heritage barbershop, and balloon-ride experience. + +When a build draws from a sparse combination, the build is expected to commit the live references it discovered back to the bank as part of its build PR. The bank gets denser with use. + +--- + +## The divergence schema + +Each shipped demo carries a signature with seven fields: + +- `slug` +- `archetype` (the canonical archetype name from `brand-archetype-system`) +- `dominant_hue_family` (the recognizable colour family, e.g. leather-bone-saddle, dawn-navy-coral, dark-linen-amber) +- `voice_register` (e.g. story-forward third-person, atmospheric second-person, fitment-first technical) +- `primary_structural_pattern` (e.g. shoppable-grid-product-forward, arc-timeline-hero, fitment-selector-then-rails) +- `hero_shape` (e.g. dual-column-image-and-text, wide-photograph-with-band-below, full-bleed-image-with-overlay; canonical vocabulary in `references/05-section-shapes-vocabulary.md`) +- `footer_shape` (e.g. single-line-strip, multi-column-sitemap, type-only-no-links; same vocabulary file) + +Overlap rules (full set in [`references/03-divergence-check.md`](references/03-divergence-check.md)): + +- Two demos share archetype AND share dominant_hue_family => **SIBLING (block)**. +- Two demos share archetype AND share voice_register AND share primary_structural_pattern => **SIBLING (block)**. +- Two demos share only dominant_hue_family across different archetypes => **WARN**. +- The candidate's hero_shape matches the hero_shape of two or more shipped demos => **WARN**. +- The candidate's hero_shape matches three or more shipped demos AND any share an archetype family => **BLOCK**. +- The candidate's footer_shape matches three or more shipped demos => **WARN**. + +A worked example file of seven signatures lives at [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) for illustration; the live signatures file for any consuming project lives in that project, not in this skill. + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands, following the convention of `brand-archetype-system`. Live reference sites are cited as exemplars using nominative attribution language: "exemplified by [URL]", "characteristic of", "in the register of". This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## Reference files + +- [`references/00-overview.md`](references/00-overview.md) - The case for the skill, the hybrid references model, the two-direction divergence, the trademark posture. +- [`references/01-process.md`](references/01-process.md) - The five-step process, each step concrete enough to execute. +- [`references/02-brief-template.md`](references/02-brief-template.md) - The fillable brief template with section-by-section guidance. +- [`references/03-divergence-check.md`](references/03-divergence-check.md) - The signature schema and the overlap rules. +- [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) - Worked example signatures file with seven demos. +- [`references/05-section-shapes-vocabulary.md`](references/05-section-shapes-vocabulary.md) - Canonical open vocabulary of hero and footer section shapes plus archetype affinities. + +The curated reference bank lives in a `reference-bank/` subdirectory under `references/`. The bank ships with a README plus three seed archetype-and-vertical files: `premium-dtc-maker-western-boots.md`, `heritage-local-service-barbershop.md`, and `hospitality-experience-balloon-ride.md`. The bank's purpose and extension procedure are documented in its README; the seed files each carry three to four positive live references and one to two negative references for the chosen position. Load the bank file matching the build's archetype-and-vertical at step 3 of the process. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md b/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md new file mode 100644 index 0000000..337ea91 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md @@ -0,0 +1,79 @@ +# Overview + +The case for the skill, the references model, and the trademark posture. + +--- + +## The problem this skill exists for + +Portfolios of brand work drift toward house style. The first demo establishes a default; the second demo borrows it; the third has the same skeleton with a different name. Without a deliberate intervention at brief time, every new build leans on the same palette, the same micro-label tracking, the same hero gradient, the same voice register. The output is competent and sibling. + +This pattern is observable in any portfolio that has shipped more than two builds. The symptoms show up at the imagery stage, when a stone-and-amber palette that worked for one shape suddenly reads as the brand's signature across three shapes that should not share a signature. The fix is upstream: pick the position before the build starts, and verify it stays distinct as the build renders. + +This skill is the deliberate creative direction at brief time. + +--- + +## The hybrid references model + +Two parts: + +### The curated bank + +Files under `reference-bank/`, one per archetype-and-vertical combination. Each file holds three to six live reference URLs that exemplify the position, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations and grows as new combinations are built against. + +The bank is the institutional memory of the portfolio. A new build for an archetype-and-vertical combination that has been done before loads the existing references and adapts. A new build for a sparse combination supplies new references during discovery and commits them back as part of its build PR. + +### Per-build discovery + +When the bank is sparse for a chosen combination, the build's first pass searches the live web for three to six exemplars. Curation rules are in [`reference-bank/README.md`](reference-bank/README.md). The discovered references serve the current build and seed the bank for future builds in the same combination. + +This is not a static reference list. The bank is supposed to drift over time as the portfolio grows; the discipline is that the bank reflects what was actually used in real builds. + +--- + +## The two-direction divergence check + +The skill runs divergence twice: once on input, once on output. + +### Input-side divergence + +Before any references are pulled, the skill loads the shipped-demos signatures file (a project artifact, not part of this skill; see [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md) for the illustrative format). Candidate archetypes are checked against the signatures. If a candidate would land sibling to a shipped demo, it is discarded and the rejection is recorded. + +The rejection record is itself useful output: it documents what the build was deliberately NOT. + +### Output-side divergence + +After the brief is rendered, the skill computes the brief's own signature (archetype, dominant hue family, voice register, primary structural pattern) and compares against the shipped signatures one more time. This catches adaptations that drifted back toward sibling territory during step 4 (the adapt step). + +The check produces one of three outcomes: `passed`, `warn-with-reasons`, or `block-with-reasons`. A `block` result means the brief cannot ship in its current form and needs adaptation before the next attempt. + +--- + +## Why two directions + +Input-side alone catches the obvious overlaps: picking an archetype that another demo already uses with the same palette family. Output-side catches the subtle drift: an archetype was picked clean of any sibling demo, but during adaptation the palette quietly converged on the recurring house family. + +The recurring stone-and-amber family is the worked example of this drift. The first build picked it intentionally; the second build adopted it because it was in the air; the third build adopted it because it felt like the brand. Without an output-side check, the brief itself becomes the carrier of the drift. + +--- + +## Trademark and attribution + +This skill follows the `brand-archetype-system` convention. Archetypes are named for aesthetic families ("Premium DTC Maker," "Heritage Local Service") not for brands. Live reference sites are cited as exemplars using nominative attribution language: + +- "exemplified by [URL]" +- "characteristic of [URLs]" +- "in the register of [URL]" + +This is descriptive and nominative fair use. A reference that pivots its identity does not invalidate the archetype it once exemplified, but it should be removed from the bank when the URL no longer shows what it was cited for. + +--- + +## What this skill is not + +- **Not a logo designer.** The brief includes a logo direction note ("type-led wordmark with a saddle-tan rule," "graphic mark in the dawn palette") but does not produce the mark itself. +- **Not an identity system.** The brief is the input to `brand-identity`, which produces the system. +- **Not a finished design.** The brief describes tokens; it does not lay them out into a finished page. +- **Not a positioning exercise.** The business spec is assumed to have positioning already. If positioning is open, run `brand-ideation` first. +- **Not a taste machine.** A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. Taste is upstream of this skill. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md b/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md new file mode 100644 index 0000000..95c441e --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md @@ -0,0 +1,143 @@ +# The five-step process + +Each step concrete enough to execute. Run in order. Do not skip the divergence steps. + +--- + +## Inputs + +The skill takes a business spec: + +- **Name** (the brand name to be used in the brief) +- **Vertical** (e.g. western-boot maker, neighborhood barbershop, balloon-ride operator) +- **Shape** (the site shape: ecommerce-catalog, ecommerce-standout, local-service-booking, hospitality-experience, hospitality-food, institution-mission, inventory-listing, subscription-app, b2b-manufacturer, directory-marketplace) +- **One-line vibe** (a sentence describing what the brand wants to feel like) +- **Shipped-demos signatures file** (optional; the project artifact listing prior builds' signatures) + +If the shipped-demos file is absent, the build is the first in the portfolio. Run the divergence steps anyway and seed the signatures file with the rendered brief's signature. + +--- + +## Step 1. Locate the design space + +Read the business spec. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. + +**How to pick:** + +- Read the vertical and shape against the 12 core archetypes. Most verticals have two or three plausible candidates; the shape narrows it. +- A western-boot maker maps plausibly to Luxe Considered (heritage premium), Rugged Utilitarian (workwear and craft), or Editorial Restrained (boutique editorial). The shape (ecommerce-standout, with a small editorial collection) narrows toward Luxe Considered with a Rugged Utilitarian secondary. +- A neighborhood barbershop maps plausibly to Warm Conversational (everyday-craft), Retro Nostalgic (period-specific), or Documentary Honest (real-people-real-work). The shape (local-service-booking, with a booking action) narrows toward Warm Conversational with a Retro Nostalgic secondary. +- A balloon-ride operator maps plausibly to Documentary Honest (landscape-and-light), Luxe Considered (aspirational-experience), or Warm Conversational (small-operator-warm). The shape (hospitality-experience, with a named arc and a booking flow) narrows toward Documentary Honest with a Luxe Considered secondary. + +**Output of this step:** + +- Primary candidate archetype (name) +- Optional secondary candidate archetype (name) with a note on which leads +- Two-sentence rationale tying each candidate to the vertical and shape + +--- + +## Step 2. Run input-side divergence + +Read the shipped-demos signatures file. Compare each candidate against every shipped demo using the rules in [`03-divergence-check.md`](03-divergence-check.md). + +**Procedure:** + +- For each candidate (primary, then secondary if present): + - For each shipped demo: + - If archetype matches AND dominant_hue_family matches => discard the candidate as SIBLING. + - If archetype matches AND voice_register matches AND primary_structural_pattern matches => discard the candidate as SIBLING. +- If all candidates are discarded, return to step 1 and pick fresh candidates from a different position on the four creative-direction axes. + +**Output of this step:** + +- The surviving candidate (the chosen archetype) +- A rejection log listing any discarded candidates with the reason (which shipped demo collided and on which fields) + +The rejection log is part of the brief output. It documents what the build was deliberately NOT. + +--- + +## Step 3. Pull references + +From `reference-bank/`, load the file matching the chosen archetype-and-vertical. Read the positive references and the negative references. + +**If the bank has the combination:** + +- Pull three to four positive references from the bank's list. Prefer the ones marked as canonical or most-recent. +- Read the negative references; they tell the build what register to avoid. + +**If the bank is sparse for the combination:** + +- Pull whatever positive references are available (one or two if that is all the bank has). +- Augment with one to two discovered live references that exemplify the position. Search the web for the vertical with the archetype's signal terms (e.g. for Luxe Considered DTC western boots: "premium western boot maker editorial photography prices visible"). +- Note the discovered references with the same format as the bank (URL plus one-line why). Add them back to the bank as part of the build PR. + +**Output of this step:** + +- A list of three to four live reference URLs, each with a one-line why +- A note on which references came from the bank versus which were discovered +- A list of negative references (registers to avoid) + +--- + +## Step 4. Adapt + +Take the chosen archetype's defaults from `brand-archetype-system` (palette, type, voice, layout, imagery direction). Shift them toward the business spec's specifics. + +**Adaptations to document:** + +- **Palette.** Pick 6 to 8 specific hex values that fit the brand. Name each with a token name (e.g. `Bone cream #f5ecd7`, `Saddle tan #a8753a`, `Pre-dawn navy #1a1f3a`). Each token gets a role (page background, primary text, primary CTA, accent, etc.). +- **Type system.** Pick the display family (often a serif from the archetype), the body family (often Inter or similar), and the micro-label treatment (tracking, casing, weight). Document the explicit differentiators from shipped demos (e.g. "tight uppercase tracking 0.04em on micro-labels, distinct from the loose 0.18em tracking the hospitality-experience build uses"). +- **Voice.** Pick the voice register (e.g. story-forward third-person; atmospheric second-person; fitment-first technical). Write five to ten voice samples in this voice using the brand name. +- **Layout.** Pick the structural pattern (e.g. shoppable-grid-product-forward; arc-timeline-hero; fitment-selector-then-rails). Describe the spine moves the homepage will run (four to six numbered moves). +- **Section shapes.** Pick a `hero_shape` and a `footer_shape` from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). The hero shape carries the most visual weight on the page; pick it deliberately based on archetype, audience, and the shapes already shipped in the portfolio. Document the rejected shapes in the brief with one-line reasons. Skipping this step means the engine inherits the most recently built hero shape regardless of brief specification, which is the drift signal this skill exists to catch. +- **CTA grammar.** Pick the verb register (e.g. "Shop the collection," "Book a dawn," "See the morning"). Verb-first, shape-appropriate. +- **Imagery direction.** Describe the shoot's register (e.g. "warm-bone studio seamless, three-quarter angle, soft overhead, products fill 70 percent of frame"). Specify aspect ratios per page slot. + +**Each adaptation choice gets a sentence of why.** The brief is a referenceable artifact; it should explain itself. + +**Output of this step:** + +- The full adaptation set, ready to render into the brief template. + +--- + +## Step 5. Render and verify + +Render the brief using the template in [`02-brief-template.md`](02-brief-template.md). + +After rendering, compute the brief's own signature and run output-side divergence: + +- `archetype`: the chosen archetype (from step 1) +- `dominant_hue_family`: derived from the palette tokens +- `voice_register`: from the voice section +- `primary_structural_pattern`: from the spine moves +- `hero_shape`: from the section-shapes choice in step 4 +- `footer_shape`: from the section-shapes choice in step 4 + +Compare this signature against every shipped demo using the full rule set in [`03-divergence-check.md`](03-divergence-check.md). The check now runs seven rules: the original three pairwise rules (archetype/hue, archetype/voice/pattern, recurring hue across archetypes) plus the three aggregate shape rules (hero shape collision warn at two matches, hero shape archetype-collision block at three matches with shared family, footer shape warn at three matches). + +**Possible outcomes:** + +- **passed.** No overlaps. The brief is ready to hand off. +- **warn-with-reasons.** The brief shares a single field (most commonly dominant_hue_family) with a shipped demo, but not enough to be sibling. Surface the warn with the matched fields so the consumer can make a deliberate call. +- **block-with-reasons.** The brief is sibling to a shipped demo. Return to step 4 and adapt further before re-rendering. Common fixes: swap the dominant accent colour, restructure one of the spine moves, shift the voice register. + +**Output of this step:** + +- The rendered brief +- The references list (from step 3) +- The divergence-check result with all matched fields if any +- A one-line summary suitable for the build PR's description + +--- + +## Failure modes + +- **Skipping step 2.** Picking the archetype that "feels right" without checking against shipped demos is how the portfolio drifts toward house style. +- **Skipping step 5.** Adapting in step 4 without re-checking on output is how the brief itself becomes the carrier of drift. +- **Verbatim copying from the archetype's default palette.** The archetypes provide anchor points, not endpoints. If the brief's palette is the archetype's palette unchanged, the brief is the archetype, not a build. +- **Citing references without why-lines.** A reference URL without a one-line why is decoration. The why is what makes the reference usable in step 4. +- **Hand-waving the divergence check.** The check is not a vibe call. It is a mechanical comparison against the schema. If it produces a block, the adaptation is incomplete. +- **Treating the rejection log as overhead.** The rejection log is part of the deliverable. It tells the next build what is already taken. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md b/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md new file mode 100644 index 0000000..96ac397 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md @@ -0,0 +1,190 @@ +# The brief template + +A fillable markdown skeleton. Fill every section. A section left blank is a section the build will fill with the house default, which is exactly the drift this skill exists to prevent. + +The template is modeled on the structure proven by real shipped builds. The worked example link at the bottom of this file shows the structure rendered against a real build. + +--- + +## Template + +```markdown +# Creative direction: <Brand Name> as <archetype position> + +A reusable brief for the <Brand Name> build. <One-sentence purpose: what shape is this, what position is this, why this brief>. + +Use this brief for: + +- <Specific use case 1> +- <Specific use case 2> + +Do NOT use this brief for: + +- <Adjacent shape that should NOT use this brief> +- <Adjacent position that should NOT use this brief> + +## The <N> spine moves + +1. **<Move 1 name>.** <One paragraph describing the move, specific to the shape>. +2. **<Move 2 name>.** <One paragraph>. +3. **<Move 3 name>.** <One paragraph>. +4. **<Move 4 name>.** <One paragraph>. +<continue 5, 6 if the shape calls for them> + +## Register + +- **Positive reference frame**: <one sentence describing what the brand IS, with named exemplars in nominative attribution> +- **Negative reference frame**: <one sentence describing what the brand is NOT, with named non-exemplars> + +## Live reference sites + +The references this brief draws from. Each is a real site exemplifying the chosen position. + +- [<URL 1>] - <one-line why; what specifically this site does that the brief inherits> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional> + +Negative references (do NOT pull from): + +- [<URL>] - <one-line why this register is the wrong one> + +## Section shapes (hero and footer; first-class brief outputs) + +Pick a `hero_shape` and a `footer_shape` from [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Document the choice with rationale; the choice is not optional and a brief without these fields does not pass the divergence check. + +### `hero_shape`: <chosen shape label, e.g. `wide-photograph-with-band-below`> + +<One paragraph: why this shape, what the chosen shape signals to the visitor that the alternatives do not, what shapes were rejected and why. Reference the section-shapes vocabulary by label.> + +Rejected shapes: + +- `<rejected shape 1>` - <one-line why this shape was wrong for this brief> +- `<rejected shape 2>` - <one-line why this shape was wrong for this brief> + +### `footer_shape`: <chosen shape label, e.g. `single-line-strip`> + +<One paragraph: why this footer shape, what it does for the page that alternatives do not.> + +Rejected shapes: + +- `<rejected shape>` - <one-line why> + +## Palette token shape (specific to this brand; do not reuse across brands) + +| Token | Hex | Role | +|---|---|---| +| <Token 1 name> | `#hex` | <Role> | +| <Token 2 name> | `#hex` | <Role> | +| <Token 3 name> | `#hex` | <Role> | +| <Token 4 name> | `#hex` | <Role> | +| <Token 5 name> | `#hex` | <Role> | +| <Token 6 name> | `#hex` | <Role> | +| <Token 7 name> | `#hex` | <Role, optional> | +| <Token 8 name> | `#hex` | <Role, optional> | + +Do NOT re-use <named hue family from a shipped demo, e.g. "stone-50 + amber-300 (the hospitality-experience default from the X build)">. + +## Type system + +- **Display.** <Family choice with stack notation>, <weight>, <tracking>. +- **Body.** <Family choice>, <weight>. +- **Brand wordmark.** <Family, case, tracking>. Distinct from <named shipped demo's wordmark treatment, e.g. "the loose 0.22em tracking used on the hospitality build">. +- **Micro-labels.** <Family, case, tracking>. <One-line on the explicit differentiator from shipped demos>. +- **Numerics.** <Family, tabular-nums or proportional, treatment for prices>. + +## CTA grammar + +- **Primary on home.** "<Verb-first label>". <One-line on why this verb>. +- **Secondary on home.** "<Verb-first label>". <One-line on why this verb>. +- **On product or detail page.** "<Label>". Verb-shape-appropriate. +- **On craft or about page.** "<Label>". Should close back to the primary action. + +## Image-ready spine + +The structure must be image-ready before any imagery pass runs. Per page slot: + +| Page | Aspect | Count | Source | +|---|---|---|---| +| <Page slot 1> | <e.g. 5:6 portrait> | 1 | <e.g. the signature product> | +| <Page slot 2> | <e.g. 4:5 portrait> | <e.g. one per product> | <e.g. each product, on its own card> | +| <Page slot 3> | <e.g. 16:9 wide> | 1 | <e.g. one lifestyle scene supporting the craft band> | +| <continue for every page> | | | | + +Each slot uses a placeholder during Phase A and is filled by the imagery pass in Phase B. Placeholders carry the alt text the final image will carry, so the swap is structurally drop-in. + +## Voice samples + +Five to ten lines in the brand's voice, used downstream by content-and-copy and landing-page-copy. + +- <Sample 1> +- <Sample 2> +- <Sample 3> +- <Sample 4> +- <Sample 5> +- <Sample 6, optional> +- <Sample 7, optional> + +## Honesty contract (unchanging across the portfolio) + +- <Functional element, e.g. cart, booking form> is real client-side, <demo surface, e.g. checkout, payment> is a clearly labelled demo that processes nothing. +- Fictitious brand disclosure in the footer and in any JSON-LD `description` field. +- Demo-only labelling on any demo surface in the brand's primary accent colour. +- All prices and figures fictitious. No promotional cadence, no fabricated reviews, no fabricated press quotes. +- No real brand mark. The logo pass, if any, is a separate later run. + +## Acceptance checklist (Phase A criteria) + +A build matches this brief if: + +- [ ] <Move 1 acceptance criterion> +- [ ] <Move 2 acceptance criterion> +- [ ] <Move 3 acceptance criterion> +- [ ] <Move 4 acceptance criterion> +- [ ] Palette is documentable as <N> tokens, distinct from any shipped demo's tokens. +- [ ] Type micro-labels have a distinct treatment from <named shipped demo's treatment>. +- [ ] Per-page image slots are wired with descriptive alt text, ready for a Phase B drop-in. +- [ ] Honesty contract intact. + +## Divergence-check result + +- **Archetype**: <chosen archetype name from brand-archetype-system> +- **Dominant hue family**: <derived from palette, e.g. "leather-bone-saddle"> +- **Voice register**: <e.g. "story-forward third-person"> +- **Primary structural pattern**: <e.g. "shoppable-grid-product-forward"> +- **Hero shape**: <chosen label from 05-section-shapes-vocabulary.md> +- **Footer shape**: <chosen label from 05-section-shapes-vocabulary.md> + +**Input-side divergence**: <passed | warn-with-reasons | block-with-reasons>. <If anything was rejected at step 2, list it here: rejected <archetype> because it collided with <shipped demo slug> on <field>>. + +**Output-side divergence**: <passed | warn-with-reasons | block-with-reasons>. <If warn or block, list the matched fields and the colliding demo. Rules 4 and 6 surface as warns; Rule 5 surfaces as a block; Rules 1, 2, 3 surface per their definitions in 03-divergence-check.md.> + +--- +``` + +--- + +## Worked example + +The Pinto Mesa Boots store-spine brief at `rampstackco-app/progress/ecommerce-standout-store-spine-brief.md` is a faithful render of this template against a real shipped build (ecommerce-standout shape; Luxe Considered with Rugged Utilitarian influence). It demonstrates: + +- The five spine moves (product-forward hero, shoppable grid, honest wayfinding, craft as supporting band, premium trust signals). +- The leather-forward palette with explicit do-not-reuse against the prior hospitality build's stone-and-amber. +- The type differentiation (tight uppercase microlabel tracking, distinct from the prior hospitality build's loose tracking). +- The image-ready spine with per-page aspect / count / source. +- The acceptance checklist as Phase-A criteria. + +Use the worked example as a structural reference when rendering new briefs. + +--- + +## Common section failures + +- **Skipping the "Do NOT use this brief for" section.** The negative-use section is what keeps the brief from being mis-applied to an adjacent shape. +- **Spine moves that are abstract.** "Lead with the product" is not a spine move. "Lead with the signature product shown large at 5:6 with one primary CTA and price-forward entry" is. +- **Palette without explicit do-not-reuse lines.** The do-not-reuse line is what makes the divergence check checkable. +- **Type system without the explicit differentiator from shipped demos.** This is the single field most likely to drift if not pinned. +- **CTA grammar in mood words.** "Welcoming" is not CTA grammar. "Shop the collection" is. +- **Image-ready spine without aspect ratios.** Without the aspect ratios the imagery pass cannot generate to the right shape. +- **Honesty contract treated as boilerplate.** The contract is part of what makes the brand demo-honest; cut and paste it but verify each line still applies to the specific build. +- **Acceptance checklist as motivational language.** The checklist is the build's pass/fail criteria, not a vibe statement. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md b/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md new file mode 100644 index 0000000..8374b0f --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md @@ -0,0 +1,229 @@ +# The divergence check + +The signature schema, the overlap rules, and the comparison procedure. + +--- + +## Signature schema + +Each shipped demo carries a signature with seven fields. The schema is small on purpose: any field that takes judgment to populate gets argued about; a small mechanical schema gets used. + +```yaml +- slug: <kebab-case slug, e.g. pinto-mesa-boots> + archetype: <canonical archetype name from brand-archetype-system, e.g. luxe-considered> + dominant_hue_family: <named hue family, e.g. leather-bone-saddle> + voice_register: <named register, e.g. story-forward-third-person> + primary_structural_pattern: <named pattern, e.g. shoppable-grid-product-forward> + hero_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. dual-column-image-and-text> + footer_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. single-line-strip> +``` + +The last two fields (`hero_shape` and `footer_shape`) are the latest schema additions. The canonical vocabulary for both lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +### slug + +The kebab-case slug for the shipped build. Used to identify the demo in rejection logs and warn or block reasons. + +### archetype + +The canonical archetype name from `brand-archetype-system`. Use the file slug from `references/core-archetypes/` (e.g. `luxe-considered`, `documentary-honest`, `warm-conversational`). If the demo composes two archetypes, record both as a hyphenated pair with the lead first (e.g. `luxe-considered-rugged-utilitarian`). + +### dominant_hue_family + +The recognizable colour family the demo reads as, in three to four words. Examples: + +- `leather-bone-saddle` (Pinto Mesa Boots v2) +- `dawn-navy-coral` (Drift & Dawn after the dawn retune) +- `dark-linen-amber` (Pho Heights) +- `warm-walnut-brass` (Iron & Rye) +- `forest-green-cream` (Clearflow Initiative) +- `slate-and-amber` (the original Drift & Dawn pre-retune, kept for historical reference) +- `stone-and-amber` (the recurring family the imagery passes surfaced as the drift signal) + +The naming convention: two to four colour terms separated by hyphens, lowercase. The terms should be specific enough that two demos with materially different palettes get different families even if they share an undertone. + +### voice_register + +The brand's voice in three to four words. Examples: + +- `story-forward-third-person` +- `atmospheric-second-person` +- `fitment-first-technical` +- `evidence-and-mission-first` +- `restrained-citation-bearing` +- `warm-everyday-craft` + +The naming convention: hyphenated phrase that names the register the voice samples in the brief operate in. + +### primary_structural_pattern + +The structural pattern the homepage runs, in three to five words. Examples: + +- `shoppable-grid-product-forward` +- `arc-timeline-hero-with-packages-strip` +- `fitment-selector-then-rails` +- `editorial-hero-then-courses-grid` +- `barber-roster-then-services-menu` +- `theory-of-change-hero-then-evidence-band` + +The naming convention: name the homepage's primary spine in a way another build can recognize from the rendered page. + +### hero_shape + +The shape of the hero section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `dual-column-image-and-text` +- `wide-photograph-with-band-below` +- `full-bleed-image-with-overlay` +- `type-led-prose` +- `centered-single-column` +- `asymmetric-large-image-small-text` +- `grid-of-elements` +- `data-table-or-spec-led` + +A build that needs a shape not in the vocabulary documents and proposes a new label per the extension procedure in `05-section-shapes-vocabulary.md`. + +### footer_shape + +The shape of the footer section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `single-line-strip` +- `multi-column-sitemap` +- `type-only-no-links` +- `editorial-colophon-with-masthead` +- `newsletter-band-with-credits` +- `dark-cta-then-credits` + +--- + +## Overlap rules + +The comparison is mechanical. The skill applies these rules in order; the first rule that fires determines the outcome for that pair. + +### Rule 1: Same archetype + same dominant_hue_family + +If two demos share `archetype` AND share `dominant_hue_family`, they are **SIBLING (block)**. + +Two demos in the same archetype with the same hue family will read as the same brand at a glance. The block forces an adaptation in either archetype or palette before the brief can ship. + +### Rule 2: Same archetype + same voice_register + same primary_structural_pattern + +If two demos share `archetype` AND share `voice_register` AND share `primary_structural_pattern`, they are **SIBLING (block)**. + +This catches the case where the palettes diverge but the underlying skeleton is identical. The build will look different on first glance and identical on the second. + +### Rule 3: Same dominant_hue_family across different archetypes + +If two demos share `dominant_hue_family` but their `archetype` differs, the outcome is **WARN**. + +A recurring hue family across different archetypes is the most common drift signal in a portfolio. The warn surfaces the recurrence so the consumer can choose to break the pattern or accept it as the portfolio's signature. + +### Rule 4: Hero shape collision (warn) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of two or more shipped demos, the outcome is **WARN**. + +The warn surfaces a deliberation note listing every shipped demo using the same shape. The brief author either justifies the repeat (and records that justification in the brief's section-shapes rationale) or picks a different shape from the vocabulary. Two demos sharing a hero shape is acceptable for a portfolio of nine to twelve demos; three or more is the point where the shape starts reading as the engine's house default. + +### Rule 5: Hero shape archetype-collision (block) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of three or more shipped demos AND any of those matching demos share an archetype family with the proposed brief, the outcome is **BLOCK**. + +This catches the case where the brief is heading toward the strongest sibling result possible: the same hero shape AND a related archetype. The block forces the brief to choose differently on at least one dimension (a different hero shape, or a different archetype lead, or a documented justification that escalates to the deliberation notes with explicit reasoning). + +Archetype-family overlap is computed by comparing the lead archetype tokens. Composed archetypes share a family if either of their tokens matches. For example, `editorial-restrained` and `editorial-restrained-documentary-honest` share the `editorial-restrained` family; `documentary-honest-luxe-considered` and `rugged-utilitarian-documentary-honest` share the `documentary-honest` family. + +### Rule 6: Footer shape collision (warn) + +If the candidate's proposed `footer_shape` matches the `footer_shape` of three or more shipped demos, the outcome is **WARN**. + +Footers tolerate more repetition than heroes since they carry less visual weight and are more functional than expressive. The threshold (three matching demos for a warn, not two) is correspondingly higher. There is no block-level rule for footer shapes at this scope; if a portfolio-wide footer shape emerges as the house default, it becomes part of the portfolio's signature rather than a per-build distinctness failure. + +### Rule 7: Anything else + +If no rule above fires, the outcome is **PASSED**. + +--- + +## Why shapes carry weight + +Heroes carry the most visual weight on a page and the most signal to the visitor. Hero-shape repetition across a portfolio compresses the perceived distance between builds even when palette, voice, and structural pattern diverge. The early showcase portfolio surfaced this drift signal: most builds shipped a `dual-column-image-and-text` or `full-bleed-image-with-overlay` hero regardless of brief specification, because the engine pattern-matched the most recently built shape. + +Footers carry less weight and are typically more functional than expressive. They tolerate more repetition before the repetition becomes a distinctness cost. + +Rules 4, 5, and 6 exist to make hero-shape and footer-shape choice an explicit selection at brief time rather than an implicit inheritance from the most recently built demo. + +--- + +## Comparison procedure + +``` +# Pairwise rules (run on every candidate-shipped pair): +for candidate in candidates: + for shipped in shipped_demos: + if rule_1(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'dominant_hue_family']) + continue + if rule_2(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'voice_register', 'primary_structural_pattern']) + continue + if rule_3(candidate, shipped): + record_warn(candidate, shipped, fields=['dominant_hue_family']) + continue + +# Aggregate rules (run once per candidate against the full set): +for candidate in candidates: + hero_matches = [s for s in shipped_demos if s.hero_shape == candidate.hero_shape] + if len(hero_matches) >= 3 and any(shares_archetype_family(candidate, s) for s in hero_matches): + record_block(candidate, hero_matches, fields=['hero_shape', 'archetype']) # rule 5 + elif len(hero_matches) >= 2: + record_warn(candidate, hero_matches, fields=['hero_shape']) # rule 4 + + footer_matches = [s for s in shipped_demos if s.footer_shape == candidate.footer_shape] + if len(footer_matches) >= 3: + record_warn(candidate, footer_matches, fields=['footer_shape']) # rule 6 +``` + +The check produces three lists: blocks, warns, and a passed flag (true iff blocks and warns are both empty). + +### Input-side outcome + +- If any block was recorded against the primary candidate, discard it. If the secondary candidate also blocks, return to step 1 and pick fresh candidates. +- Warns at input-side are surfaced in the rejection log but do not discard the candidate. + +### Output-side outcome + +After the brief is rendered, the brief's own signature is checked against every shipped demo using the same rules. The outcome is one of: + +- **passed**: no blocks, no warns. The brief is ready to hand off. +- **warn-with-reasons**: warns only. The brief shares a single field (most commonly `dominant_hue_family`) with a shipped demo. Surface the warn with the matched fields so the consumer can make a deliberate call. +- **block-with-reasons**: at least one block. The brief is sibling to a shipped demo. Return to step 4 of the process and adapt further before re-rendering. + +--- + +## What changes a block to a warn or a pass + +Concretely: + +- **Shift the dominant_hue_family.** Swap the dominant accent colour, change the page background's temperature, or change the accent colour family (saddle to oxblood to navy). Recompute the family. +- **Shift the primary_structural_pattern.** Change which move leads the page. A "product-forward" pattern becomes "story-forward" by reordering the spine moves. Recompute the pattern. +- **Shift the voice_register.** Change the voice from third-person to second-person, or from atmospheric to technical. Recompute the register. +- **Compose a different archetype pair.** If the chosen archetype is locked, change the secondary archetype to shift the brief's centre of mass. + +Each adaptation should be a deliberate choice, recorded in the brief's adaptation notes (step 4 of the process). + +--- + +## The signatures file + +The signatures file is a project artifact, not part of this skill. The consuming project maintains it (typically as `progress/shipped-demos-signatures.yml` or similar). The illustrative format is in [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md). + +Whenever a new build ships, append its signature to the file. The signatures grow with the portfolio; the divergence check stays current. + +--- + +## Failure modes + +- **Filling fields with vibe words.** "vibrant-modern" is not a hue family; "saddle-bone-walnut" is. The schema works because the field values are specific. Vague values produce vague checks. +- **Re-using the same family across builds without recomputing.** When a build's palette shifts during step 4, the dominant_hue_family must shift with it. A stale signature is worse than a missing signature. +- **Treating warns as ignorable.** A warn is the portfolio's drift early-warning. Three consecutive warns on the same hue family is the portfolio adopting a house signature, which is the failure mode this skill exists to prevent. +- **Hand-waving the rules.** The rules are mechanical. If a candidate blocks under rule 1, it blocks; the answer is to adapt, not to argue with the rule. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md b/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md new file mode 100644 index 0000000..b770582 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md @@ -0,0 +1,141 @@ +# Shipped-demos signatures: worked example + +An illustrative signatures file with seven worked entries. This file is example-only; the live signatures file for any consuming project lives in that project (typically at `progress/shipped-demos-signatures.yml`), not in this skill. + +The schema is defined in [`03-divergence-check.md`](03-divergence-check.md). Each entry has seven fields: `slug`, `archetype`, `dominant_hue_family`, `voice_register`, `primary_structural_pattern`, `hero_shape`, `footer_shape`. The last two (`hero_shape`, `footer_shape`) are the latest additions; their canonical vocabulary lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +The seven entries below are illustrative records of seven sibling-shape demos a portfolio might ship. They are written here as a worked example of what the file looks like in practice. The archetype values reference the canonical names from `brand-archetype-system`. + +--- + +## Example signatures + +```yaml +demos: + - slug: fitfirst-parts + archetype: technical-precise + dominant_hue_family: slate-and-amber + voice_register: fitment-first-technical + primary_structural_pattern: fitment-selector-then-rails + hero_shape: dual-column-image-and-text + footer_shape: multi-column-sitemap + + - slug: iron-and-rye-barbershop + archetype: warm-conversational-retro-nostalgic + dominant_hue_family: warm-walnut-brass + voice_register: warm-everyday-craft + primary_structural_pattern: barber-roster-then-services-menu + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: pho-heights + archetype: documentary-honest-luxe-considered + dominant_hue_family: dark-linen-amber + voice_register: chef-essay-first-person + primary_structural_pattern: editorial-hero-then-signatures-menu + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: volta-robotics + archetype: technical-precise + dominant_hue_family: graphite-and-signal-orange + voice_register: spec-forward-technical + primary_structural_pattern: product-strip-then-spec-table + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: clearflow-initiative + archetype: editorial-restrained + dominant_hue_family: forest-green-cream + voice_register: restrained-citation-bearing + primary_structural_pattern: theory-of-change-hero-then-evidence-band + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: pinto-mesa-boots + archetype: luxe-considered-rugged-utilitarian + dominant_hue_family: leather-bone-saddle + voice_register: story-forward-third-person + primary_structural_pattern: shoppable-grid-product-forward + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: drift-and-dawn + archetype: documentary-honest-luxe-considered + dominant_hue_family: dawn-navy-coral + voice_register: atmospheric-second-person + primary_structural_pattern: arc-timeline-hero-with-packages-strip + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip +``` + +--- + +## Why each field is what it is + +### fitfirst-parts (ecommerce-catalog) + +- **archetype**: `technical-precise`. The build leads with a YMM (year-make-model) fitment selector. Grids, monospace numerics, system-feeling. +- **dominant_hue_family**: `slate-and-amber`. Cool slate ground with warm amber accents on safety and action surfaces. +- **voice_register**: `fitment-first-technical`. The voice asks "does it fit your vehicle" before anything else. +- **primary_structural_pattern**: `fitment-selector-then-rails`. The home leads with the selector, then rails of parts filtered by the confirmed vehicle. + +### iron-and-rye-barbershop (local-service-booking) + +- **archetype**: `warm-conversational-retro-nostalgic`. Heritage barbershop register; walnut and brass; period-specific cues. +- **dominant_hue_family**: `warm-walnut-brass`. Walnut wood and brass hardware are the recognizable palette. +- **voice_register**: `warm-everyday-craft`. The voice is the shop talking about its work in plain terms. +- **primary_structural_pattern**: `barber-roster-then-services-menu`. Roster (initials) leads, services menu follows, atmosphere gallery threads the page. + +### pho-heights (hospitality-food) + +- **archetype**: `documentary-honest-luxe-considered`. Dark linen photography, real-food register, premium restraint. +- **dominant_hue_family**: `dark-linen-amber`. Dark linen background dominates; amber surfaces as the accent. +- **voice_register**: `chef-essay-first-person`. The chef-partner essay is the page's voice. +- **primary_structural_pattern**: `editorial-hero-then-signatures-menu`. Edge-to-edge hero, chef essay, signatures section with image-led cards. + +### volta-robotics (b2b-manufacturer) + +- **archetype**: `technical-precise`. Industrial spec-table register. Same archetype as fitfirst-parts but a different hue family and a different structural pattern (so rule 1 does not fire on this pair). +- **dominant_hue_family**: `graphite-and-signal-orange`. Industrial graphite with hazard-orange accents on action surfaces. +- **voice_register**: `spec-forward-technical`. Specs lead, narrative supports. +- **primary_structural_pattern**: `product-strip-then-spec-table`. Product strip up top, deep spec tables follow. + +### clearflow-initiative (institution-mission) + +- **archetype**: `editorial-restrained`. Counsel-restrained register; numbers before adjectives; citation-bearing voice. +- **dominant_hue_family**: `forest-green-cream`. Deep forest green sections with warm cream surfaces. +- **voice_register**: `restrained-citation-bearing`. Third-person about the org, low-register confidence, numbers leading. +- **primary_structural_pattern**: `theory-of-change-hero-then-evidence-band`. Theory of change in the hero, evidence band (lives reached, water systems built) follows. + +### pinto-mesa-boots (ecommerce-standout) + +- **archetype**: `luxe-considered-rugged-utilitarian`. Premium DTC maker register with workwear and craft secondary. +- **dominant_hue_family**: `leather-bone-saddle`. Bone cream ground with saddle tan and walnut accents; oxblood as the demo-only chip. +- **voice_register**: `story-forward-third-person`. The brand talks about itself in the third person, with material before adjectives. +- **primary_structural_pattern**: `shoppable-grid-product-forward`. Product-forward hero, six-boot shoppable grid on the home, by-last wayfinding. + +### drift-and-dawn (hospitality-experience) + +- **archetype**: `documentary-honest-luxe-considered`. Photography-led, atmospheric, aspirational. Same composed archetype as pho-heights but a different vertical and a different hue family (so rule 1 does not fire on this pair). +- **dominant_hue_family**: `dawn-navy-coral`. Pre-dawn navy with coral and pale-gold accents, deliberately distinct from the hospitality-experience stone-and-amber default the original build used. +- **voice_register**: `atmospheric-second-person`. The brand walks the visitor through the morning in second person. +- **primary_structural_pattern**: `arc-timeline-hero-with-packages-strip`. Hero with arc preview, packages strip with named prices, six-moment timeline on the experience page. + +--- + +## What this example exercises + +The seven entries are constructed to exercise the divergence rules: + +- **Rule 1 not firing**: `fitfirst-parts` and `volta-robotics` share `archetype: technical-precise` but differ on `dominant_hue_family` (`slate-and-amber` vs `graphite-and-signal-orange`). No block. +- **Rule 1 not firing**: `pho-heights` and `drift-and-dawn` share `archetype: documentary-honest-luxe-considered` but differ on `dominant_hue_family` (`dark-linen-amber` vs `dawn-navy-coral`). No block. The deliberate retune from the original `slate-and-amber` to `dawn-navy-coral` is what kept this pair from blocking. +- **Rule 3 historical case**: the original `drift-and-dawn` (pre-retune, hue family `slate-and-amber`) would have triggered rule 3 against `fitfirst-parts` (also `slate-and-amber`) across different archetypes. The retune resolved the recurring family. + +--- + +## How to use this example + +Copy the YAML block to a `progress/shipped-demos-signatures.yml` file in the consuming project. Edit the entries to match the actual shipped builds. Append new entries as builds ship. The divergence check in [`03-divergence-check.md`](03-divergence-check.md) reads from this file. + +This file is example-only. The skill does not parse this example file at runtime; it parses the consuming project's signatures file. The example exists to show what the file should look like. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md b/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md new file mode 100644 index 0000000..0195584 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md @@ -0,0 +1,151 @@ +# Section shapes vocabulary + +A canonical, open vocabulary of section shapes the brief picks from for the hero and footer sections (with optional later extension to trust-strip, CTA-close, and how-it-works sections). The vocabulary is a starting point, not a closed enum. Builds can document and propose a new shape if none of the listed labels fits. + +Section shapes are first-class brief outputs. The brief picks a shape per section explicitly and records the rationale next to palette and voice rationale. Two new fields per signature record (`hero_shape` and `footer_shape`) let the divergence check fire against shape collision across shipped demos. + +The divergence rules for shapes are in [`03-divergence-check.md`](03-divergence-check.md) (Rules 4, 5, 6). + +--- + +## Hero shapes (open list, starting set) + +### `dual-column-image-and-text` + +Image on one side of the hero, heading and lede and CTAs on the other. CSS grid with two columns (often around 1.1fr / 1fr). The engine's house default and the shape most prone to overuse in a portfolio that grows without explicit shape selection. + +- **When it fits**: brands where the photograph and the type carry roughly equal weight and the eye is meant to ricochet between them. Premium DTC product hero is the canonical fit; a single product on the image side and a price-and-CTA on the type side. +- **References**: [allbirds.com](https://allbirds.com), [tecovas.com](https://tecovas.com). +- **Archetype affinities**: Luxe Considered, Warm Conversational, Editorial Restrained (mild). + +### `wide-photograph-with-band-below` + +Single full-width hero photograph (aspect 16:9 or wider) spanning the content width, with structured content (search rail, CTA pair, lede, filter chips) stacked vertically below the photograph. The photograph carries the page; the band below carries the affordances. + +- **When it fits**: inventory marketplaces, regional specialists, sites where the photograph signals what the marketplace is for and the band carries the controls. Also fits magazine-style editorial registers where one strong image opens an article. +- **References**: [bringatrailer.com](https://bringatrailer.com), [icon4x4.com](https://icon4x4.com). +- **Archetype affinities**: Rugged Utilitarian, Documentary Honest, Editorial Restrained. + +### `full-bleed-image-with-overlay` + +Image fills the section (or near-fills, often at `object-cover` with `absolute inset-0`), with type overlaid via a gradient. Dramatic, cinema-poster register. Strongest visual signal of all hero shapes; correspondingly the easiest to over-saturate. + +- **When it fits**: hospitality experiences where the place is the product (balloon ride, restaurant, hotel), mission-driven nonprofits where the documentary photograph is the evidence, premium B2B where the product is photographed at scale. Atmospheric and cinematic. +- **References**: [bombasses.com](https://bombasses.com) (hospitality), [charitywater.org](https://charitywater.org) (institution-mission). +- **Archetype affinities**: Documentary Honest, Luxe Considered (composed with Documentary Honest), Editorial Restrained. + +### `type-led-prose` + +No image in the hero. The H1 and lede do the work; image (if any) appears below the hero as a supporting element. Editorial publication register. The whitespace and the type carry the page. + +- **When it fits**: editorial publications, ideas-led brands, B2B SaaS where the proposition is conceptual, premium consultancies, law and finance where understated credibility is the play. +- **References**: [nytimes.com](https://nytimes.com), [stripe.com](https://stripe.com) (mild type-led, with type leading and a subtle product render below). +- **Archetype affinities**: Editorial Restrained, Technical Precise (mild). + +### `centered-single-column` + +Narrow content column centered on the page, H1 and lede only, minimal. Often paired with atmospheric brand registers where the centered alignment signals "considered, not loud." + +- **When it fits**: portfolio brands, atmospheric or contemplative registers, single-product brands where the page is essentially a long-scroll story and the hero is just the opening line. +- **References**: [linear.app](https://linear.app), [framer.com](https://framer.com) (both run centered single-column heroes at times). +- **Archetype affinities**: Editorial Restrained, Luxe Considered. + +### `asymmetric-large-image-small-text` + +One element dominates the hero (usually an image at 70 to 80 percent of width), the other is caption-scale beside or below it. Distinct from `dual-column-image-and-text` by the imbalance: the dual-column is roughly balanced, the asymmetric leans heavily. + +- **When it fits**: magazine cover style, photography portfolios, single-product hero where the product carries everything and the type is a caption-scale credit line. +- **References**: [magnum.com](https://magnum.com), [aesop.com](https://aesop.com) (varies; some pages use asymmetric layouts). +- **Archetype affinities**: Luxe Considered, Documentary Honest, Editorial Restrained. + +### `grid-of-elements` + +The hero IS a grid: product tiles, listing cards, directory entries, no single anchor image. The inventory or directory itself is the hero. Distinct from `wide-photograph-with-band-below` by having no single dominant image; the grid carries the meaning. + +- **When it fits**: directory and marketplace shapes where the breadth of the catalog is the value, ecommerce catalog shapes where shoppability above the fold is the conversion lever. +- **References**: [airbnb.com](https://airbnb.com) (search results hero is the grid), [unsplash.com](https://unsplash.com). +- **Archetype affinities**: Technical Precise, Editorial Restrained (with restraint), Rugged Utilitarian (if the directory is the working catalog). + +### `data-table-or-spec-led` + +A data table or spec block is the hero element. The numbers and the comparison carry the page. Technical Precise register, B2B engineering context, comparison-led purchase decisions. + +- **When it fits**: B2B engineering procurement, hardware comparison sites, financial product comparison, anywhere the buyer is data-anchored before they care about photography. +- **References**: [parametric-portfolios.com](https://parametric-portfolios.com), [substack.com/pricing](https://substack.com/pricing) (pricing-table-as-hero variants). +- **Archetype affinities**: Technical Precise, Editorial Restrained. + +--- + +## Footer shapes (open list, starting set) + +### `single-line-strip` + +One row carrying the brand disclosure paragraph and the footer nav, no multi-column structure. Mobile and desktop render the same content reflowed. The default across most demos in the showcase portfolio. + +- **When it fits**: small-collection brands, single-purpose microsites, demo and showcase contexts, brands where the footer is meant to be functional chrome rather than navigation in its own right. +- **References**: most editorial brand sites with a small surface area. +- **Archetype affinities**: any; this is the chrome default. + +### `multi-column-sitemap` + +Three to six columns of links plus brand info. Common on larger commerce sites where the footer carries category navigation, popular searches, account shortcuts, customer service, about-the-company, and resources. + +- **When it fits**: ecommerce catalog with deep category trees, multi-tenant marketplaces with seller-side and buyer-side links, B2B sites with documentation libraries. +- **References**: [amazon.com](https://amazon.com), [shopify.com](https://shopify.com), most large retailers. +- **Archetype affinities**: Technical Precise, Rugged Utilitarian (if functional), any commerce-heavy archetype. + +### `type-only-no-links` + +Minimal editorial footer, copyright and disclosure only, no nav. The footer is essentially a colophon. + +- **When it fits**: ideas-led brands, single-page narratives, publications where the nav lives in the top chrome and the bottom is just the credit line. +- **References**: [pitchfork.com](https://pitchfork.com) (varies; minimal footer), portfolio sites. +- **Archetype affinities**: Editorial Restrained, Luxe Considered. + +### `editorial-colophon-with-masthead` + +Masthead-style footer naming the editorial team or contributors. Fits publication register where the footer credits the people behind the work. + +- **When it fits**: publications, magazine sites, editorial collectives, organizations where the people are the brand. +- **References**: [theatlantic.com](https://theatlantic.com), [theverge.com](https://theverge.com). +- **Archetype affinities**: Editorial Restrained, Documentary Honest. + +### `newsletter-band-with-credits` + +Newsletter signup as the dominant footer element, with credits below. The newsletter is the conversion goal; the footer is the conversion surface. + +- **When it fits**: content sites, newsletter-first publications, brands where the newsletter is the customer-relationship channel. +- **References**: [substack.com](https://substack.com), most content sites operating newsletter-led growth. +- **Archetype affinities**: Editorial Restrained, Warm Conversational. + +### `dark-cta-then-credits` + +Two-row footer with a dark CTA band on top and a credits strip below. The CTA band acts as the page-bottom conversion surface; the credits strip is the actual footer. + +- **When it fits**: conversion-led sites where the bottom of the page is the second-most-attended surface (after the hero), marketing sites, B2B with a sign-up funnel. +- **References**: [vercel.com](https://vercel.com), [linear.app](https://linear.app). +- **Archetype affinities**: Technical Precise, any conversion-led register. + +--- + +## Optional extensions (not formally checked at this dispatch's scope) + +The framework can grow to cover additional section shapes as the portfolio surfaces them. Currently documented loosely; not part of the divergence check fields. + +- **Trust-strip shapes**: four-signal block, two-paragraph narrative band, logo wall, citation row. +- **CTA-close shapes**: dark band with single CTA, gradient band with pair of CTAs, image-backed close, newsletter close. +- **How-it-works shapes**: three-card strip, numbered list with images, flow diagram, timeline. + +When a brief's shape choice for one of these sections proves load-bearing for the build's distinctness, a future framework dispatch can promote the section to a checked field. + +--- + +## How to extend the vocabulary + +A build that discovers a section shape not present in the vocabulary: + +1. Documents the shape in the brief with a name (kebab-case), a one-paragraph description, and one or two real-world references. +2. Adds the shape to this file under the appropriate section (hero or footer) with the same format the existing shapes use. +3. Commits the vocabulary addition in the build PR. + +The vocabulary grows with the portfolio. Stale shapes (no demo uses them, no live references remain) can be retired in subsequent dispatches. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md new file mode 100644 index 0000000..dbaf928 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md @@ -0,0 +1,114 @@ +# Reference bank + +The bank holds curated live reference sites for archetype-and-vertical combinations the portfolio has built against. Each file covers one combination, with positive references (sites that exemplify the position) and negative references (sites in the same vertical but in the WRONG register). + +The bank is the institutional memory of the portfolio. A new build for a combination that has been done before loads the existing file and adapts. A new build for a sparse combination supplies discovered references and commits them back to the bank as part of its build PR. + +--- + +## File naming convention + +`<archetype>-<vertical-specific-tag>.md` + +Examples: + +- `premium-dtc-maker-western-boots.md` +- `heritage-local-service-barbershop.md` +- `hospitality-experience-balloon-ride.md` + +The archetype prefix is the canonical name from `brand-archetype-system` (composed archetypes are hyphenated with the lead first). The vertical-specific tag is the narrowest description of the vertical the file covers (not the broad shape; the specific category within it). + +--- + +## File structure + +Each file has the same structure: + +```markdown +# <Archetype>, <Vertical> + +- **Archetype**: <Canonical archetype name, with composition note if any>. +- **Vertical**: <Broad shape> (specifically <narrow category>). +- **Position summary**: <One-line position the references collectively exemplify>. + +## Positive references + +- [<URL 1>] - <one-line why; what specifically this site does that a build in this position should inherit> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional but encouraged> + +## Negative references + +- [<URL or named category>] - <one-line why this register is the wrong one for this position> + +## Extension note + +- <When was this file last updated and against which build> +``` + +--- + +## Adding references + +A build that uses this skill on a combination that has a file already: + +1. Loads three to four references from the existing file in step 3 of the process. +2. If the build discovered any new live references in addition (because the bank's references were stale or the build needed more breadth), append them to the positive references list in the same file with a one-line why. +3. Commit the file edit as part of the build PR. + +A build that uses this skill on a combination with no existing file: + +1. Creates a new file under `reference-bank/` named per the convention above. +2. Fills the file with three to six positive references discovered during the build's step 3. +3. Fills negative references with one to two categories or named sites that the build should not pull from. +4. Commits the file as part of the build PR. + +--- + +## Reference quality bar + +Each positive reference should be a real live site that: + +- Exemplifies the chosen position observably (palette, layout, voice, imagery, or all four). +- Is operating at a quality level the build can credibly aspire to. +- Has been live recently (within the past year if possible; older references are acceptable if they remain the canonical example). + +Each negative reference should be a real live site or a named category that: + +- Sits in the same vertical but in a different register. +- Helps the build understand what to NOT pull from. + +The one-line why for each reference is what makes the reference usable in step 4 of the process. A URL without a why is decoration; the why is what tells the next build what specifically to inherit or avoid. + +--- + +## When to retire a reference + +A reference should be removed from the bank when: + +- The URL stops showing what it was cited for (brand redesign, site shutdown, paywall changed the visible register). +- A more canonical example for the same position emerges. +- The build that originally cited the reference has been superseded and the new build uses different references. + +Retirement is a normal part of bank maintenance. The bank reflects what is currently usable, not what was once usable. + +--- + +## Seeded combinations + +Eleven combinations live in the bank: + +- [`premium-dtc-maker-western-boots.md`](premium-dtc-maker-western-boots.md) - Premium DTC maker register applied to a small-collection western-boot maker. +- [`heritage-local-service-barbershop.md`](heritage-local-service-barbershop.md) - Heritage local-service register applied to a neighborhood barbershop. +- [`hospitality-experience-balloon-ride.md`](hospitality-experience-balloon-ride.md) - Documentary-honest hospitality-experience register applied to a scenic-flight operator. +- [`editorial-restrained-documentary-honest-specialty-coffee-subscription.md`](editorial-restrained-documentary-honest-specialty-coffee-subscription.md) - Editorial-restrained subscription-app register applied to a single-origin specialty coffee subscription. +- [`rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md`](rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md) - Rugged-utilitarian inventory-listing register applied to a regional used-truck-and-SUV marketplace. +- [`editorial-restrained-literary-quarterly.md`](editorial-restrained-literary-quarterly.md) - Editorial-restrained editorial-publication register applied to a themed literary and ideas quarterly. +- [`luxe-considered-editorial-restrained-residential-architectural-brokerage.md`](luxe-considered-editorial-restrained-residential-architectural-brokerage.md) - Luxe-considered-editorial-restrained inventory-listing register applied to a residential brokerage of architecturally significant homes (the first same-shape divergence test against the rugged-utilitarian regional-used-vehicle-marketplace entry). +- [`bold-confident-editorial-restrained-aaa-game-studio.md`](bold-confident-editorial-restrained-aaa-game-studio.md) - Bold-confident-editorial-restrained corporate-portfolio register applied to a AAA-adjacent action game studio (the first portfolio entry in Bold Confident; the gentler entry into the bold register before a game-title demo). +- [`bold-confident-vibrant-saturated-single-ip-game-title.md`](bold-confident-vibrant-saturated-single-ip-game-title.md) - Bold-confident-vibrant-saturated single-IP marketing register applied to a post-launch AAA action game title (the first single-IP marketing entry; the title side of the game-studio pair, claiming the saturated leap the studio brief reserved). +- [`minimal-essentialist-documentary-honest-trades-directory.md`](minimal-essentialist-documentary-honest-trades-directory.md) - Minimal-essentialist-documentary-honest directory-marketplace register applied to a homeowner-facing local-trades directory (the first directory-marketplace shape and the first multi-provider entry; encodes the multi-provider conventions and the no-fabricated-reviews resolution). +- [`luxe-considered-curated-stays-directory.md`](luxe-considered-curated-stays-directory.md) - Pure-luxe-considered directory-marketplace register applied to an aspirational curated short-term-stays marketplace (the second directory-marketplace entry; the same-shape divergence partner to the trades directory, showing the shape across two opposite registers; reframes the multi-provider conventions for hosts and stays). + +Each seed file was built against a real shipped demo or shipped brief and reflects the references that build drew from. As the portfolio grows, the bank grows with it. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md new file mode 100644 index 0000000..3717ecd --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md @@ -0,0 +1,23 @@ +# Bold-confident-editorial-restrained, AAA-adjacent action game studio + +- **Archetype**: `bold-confident` with `editorial-restrained` as the composition secondary. The lead is the cinematic-confident register of AAA-adjacent action studios; the secondary is chrome restraint (the platform-versus-content distinction from the gaming and entertainment vertical file: a studio is the chrome around its games, so the chrome composes while the game key art carries the saturation). The composition is the explicit chrome-restraint dial: pure Bold Confident or composed-with-Vibrant-Saturated is reserved for single-game-title demos. +- **Vertical**: Corporate-portfolio (specifically AAA-adjacent action game studio: a content-creator studio that builds large-scale action games and presents itself as a serious craft-and-scale shop). +- **Position summary**: A studio whose chrome is composed and dark-mode-first, where each fictitious title's key art carries the saturation and energy. Cinematic full-bleed hero, titles portfolio strip, type-led studio band, careers band as the load-bearing conversion surface, dark CTA close. + +## Positive references + +- [bungie.net](https://bungie.net) - The canonical AAA-action studio chrome register: cinematic full-bleed key-art hero, dark-mode-first ground, restrained type chrome that lets the game art carry. Inherit the cinematic hero treatment, the dark ground, and the chrome restraint. +- [insomniac.com](https://insomniac.com) - Insomniac Games. The studio chrome at composed-cinematic; the titles portfolio surfaced with care. Inherit the titles-portfolio anatomy and the craft-proud-without-arrogance voice. +- [naughtydog.com](https://naughtydog.com) - Naughty Dog. The restrained-cinematic studio register; type-led studio band with the team presented at masthead density. Inherit the studio-band convention and the restrained-cinematic chrome. +- [remedygames.com](https://remedygames.com) - Remedy Entertainment. The composed-cinematic register at the studio level, with a smaller portfolio presented with editorial discipline. Inherit the title-detail-page-as-small-monograph anatomy. + +## Negative references + +- [steampowered.com](https://steampowered.com) - Steam. Platform chrome that hosts third-party content. Wrong vertical (platform, not studio); the platform chrome reads totally different from a studio's content-creator brand. +- [itch.io](https://itch.io) - Itch.io. Indie game platform; minimal chrome; wrong register and wrong vertical. +- Mobile and casual free-to-play studio sites (the bright-saturated multi-hue cartoon register of casual-mobile studio brands). Wrong register; a AAA-adjacent action studio is not casual-mobile. +- Streaming-service sites (netflix.com, hbomax.com). Adjacent Bold-Confident-leaning register but wrong vertical (streaming distribution vs studio creation). Netflix's content-as-hero treatment is a useful inheritance for the cinematic hero; the rest of Netflix's chrome is platform-distributor, not studio. + +## Extension note + +- Seeded from the Ironhold AAA-adjacent action studio brief (first portfolio entry in Bold Confident; first portfolio entry in the corporate-portfolio shape applied to a game studio). The brief is the gentler entry into Bold Confident in the showcase portfolio; the upcoming game-title demo is the leap into the saturated single-IP register. The studio composes with Editorial Restrained as the chrome-restraint dial so the title-demo can pull saturation further without colliding. The brief documents a Rule 4 WARN override on the full-bleed-image-with-overlay hero (the canonical AAA-studio cinematic treatment, four shipped matches but no archetype-family share so Rule 5 does not block; the override is justified by the new archetype carrying the shape into a completely different visual reading). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md new file mode 100644 index 0000000..a3e23c8 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md @@ -0,0 +1,24 @@ +# Bold-confident-vibrant-saturated, single-IP game-title marketing site + +- **Archetype**: `bold-confident` with `vibrant-saturated` as the composition secondary. The lead is the cinematic-confident register of AAA action titles; the secondary is the saturated leap (palette depth, type at title-card scale, key art as the load-bearing surface). This is the expressive content-brand end of the gaming and entertainment vertical, distinct from the studio-portfolio chrome that publishes the title. The pair to `bold-confident-editorial-restrained-aaa-game-studio`: the studio composes with Editorial Restrained chrome restraint, the single title composes with Vibrant Saturated to claim the saturation the studio reserved. +- **Vertical**: Single-IP marketing (specifically a post-launch AAA action game title: the marketing site where one shipped game lives, distinct from the studio portfolio that publishes it). The shape generalizes to any single published work (a single film, album, book, or show); the references here are the game-title instance. +- **Position summary**: A single published title's own brand, dark-mode-first, world-forward, where the world's own palette and the key art carry the saturation. Cinematic launch-poster hero, a trailer or curated key-art sequence, a world-immersion surface, a systems surface, a media gallery, and a follow-or-storefront conversion close. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (dark-mode-first, world-forward, saturated, cinematic) and pulls NO trade dress, layout, scroll behavior, font choice, or animation language from any specific real-game marketing site. Marketing-site mimicry is as off-limits as in-game resemblance. + +- [marathonthegame.com](https://marathonthegame.com) - The saturated single-IP marketing register at its most committed: a published title's own brand, dark-mode-first, with the title's palette and art carrying the saturation rather than the publisher's chrome. Inherit the world-forward saturated register; do NOT pull the flat-graphic identity or layout. +- [deathstranding.com](https://deathstranding.com) - Single-IP world-immersion marketing: the site immerses the visitor in one world (the setting, the lore) in the game's own voice rather than the studio's. Inherit the world-as-protagonist surface; do NOT pull the atmospheric scroll, type, or identity. +- [cyberpunk.net](https://cyberpunk.net) - Saturated single-IP launch register: type at title-card scale, palette depth carrying the world's own tones. Inherit the type-at-scale and palette-depth treatment; do NOT pull the neon-magenta identity. +- [eldenring.bandainamcoent.com](https://eldenring.bandainamcoent.com) - Single-IP lore-immersion marketing: a world page that treats the world as the protagonist with deep lore in the title's voice. Inherit the lore-immersion surface; do NOT pull the dark-fantasy identity. + +## Negative references + +- Studio and publisher portfolio sites ([bungie.net](https://bungie.net), [naughtydog.com](https://naughtydog.com), and the paired `bold-confident-editorial-restrained-aaa-game-studio` register) - The studio chrome composes and recedes to let many titles share a body of work. The single-IP title's register is the saturated content brand, distinct from the publisher's chrome; a single title is not a portfolio. +- Platform-chrome sites ([steampowered.com](https://steampowered.com), [store.epicgames.com](https://store.epicgames.com), [itch.io](https://itch.io)) - Platforms host third-party content and lean restrained to let the content carry. A single-IP marketing site is the content's own brand, not the platform that distributes it. +- Casual and mobile single-game marketing sites (the bright multi-hue cartoon register of casual-mobile single-game brands) - Wrong register; an AAA cinematic title is dark-mode-first and world-forward, not bright-cartoon. + +## Extension note + +- Seeded from the Mariner's Gauntlet single-IP marketing brief (first portfolio entry in the single-IP marketing shape; the title side of the Ironhold pair; the first portfolio entry composing with Vibrant Saturated). The title claims the saturated single-IP register that the paired studio brief (`bold-confident-editorial-restrained-aaa-game-studio`) deliberately reserved as forward-divergence headroom. The brief documents the framework's first Rule 5 BLOCK against a same-pair shipped demo: `full-bleed-image-with-overlay` is blocked (five shipped matches plus a shared Bold Confident family with the publisher Ironhold), so the title selects `centered-single-column` as a cinematic launch-poster hero, the intended divergence-within-the-pair. Footer is `newsletter-band-with-credits` (the follow-the-title conversion). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md new file mode 100644 index 0000000..6e98079 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md @@ -0,0 +1,22 @@ +# Editorial-restrained, documentary-honest, specialty coffee subscription + +- **Archetype**: `editorial-restrained` with `documentary-honest` as the composition secondary. The lead is editorial type-led restraint (low-saturation, generous whitespace, considered typography); the secondary is documentary farm and bean photography that grounds the single-origin claim. Premium but approachable; not luxury, not mass-market. +- **Vertical**: DTC food and beverage (specifically specialty coffee subscriptions; the references generalise to tea and other consumable single-origin subscriptions in adjacent registers). +- **Position summary**: A specialty single-origin coffee subscription in the editorial-restrained register. Subscriber-first commerce (cadence picker, pause and swap surfaced as features, not buried in account settings). Named farms, named processes, named roast dates. Documentary farm photography supports the type rather than leads. + +## Positive references + +- [drinktrade.com](https://drinktrade.com) - Subscriber-first commerce explicit: cadence picker on the home, match-quiz to find your roast, pause and swap surfaced as features rather than buried in account settings. Editorial-restrained type-led layout with documentary product photography. +- [counterculturecoffee.com](https://counterculturecoffee.com) - Specialty roaster with subscription surfaced; documentary photography of farms and farmers carries the page; editorial type. The canonical reference for "farm-direct specialty roaster with a subscription option." +- [onyxcoffeelab.com](https://onyxcoffeelab.com) - Editorial-restrained register at its most refined: type-led, considered photography, premium-but-approachable. Useful as the type-system reference (small-caps, restrained tracking, editorial serifs). +- [atlascoffeeclub.com](https://atlascoffeeclub.com) - Subscriber-first explicitly with a world-coffee-journey narrative. The closest match to the "one origin a month, named farm, named process" positioning. Useful for how to surface the rotation as the value prop. + +## Negative references + +- [starbucks.com](https://starbucks.com) - Mass-market grocery register; frappuccino lifestyle photography; promotional cadence dominates the homepage. The register a specialty roaster must not pull from. +- [folgers.com](https://folgers.com) - Commodity grocery brand; blue-can heritage but no specialty register. The bottom of the grocery shelf, conceptually. +- Generic lifestyle-influencer subscription boxes (BarkBox, FabFitFun, Allure Beauty Box and similar) - Lifestyle-spectacle subscription register where the unboxing is the product; the box itself is supposed to be a surprise. Wrong register entirely for a specialty-coffee subscription where the named farm and the roast date are the value, not the unboxing reveal. + +## Extension note + +- Seeded by the Northbound Coffee Co. brief (Phase 2 live pressure-test of the creative-brief-selector skill, rampstack/rampstackco-app PR #131). The brief was the first live invocation of the selector and discovered these references during step 3 because the bank had no seed for the specialty-coffee-subscription combination. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md new file mode 100644 index 0000000..a6c7c02 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md @@ -0,0 +1,25 @@ +# Editorial-restrained, literary quarterly + +- **Archetype**: `editorial-restrained` (pure, no composition secondary). The lead is the literary quarterly tradition: typography carries the page, the considered editorial register, the restrained accent, and the absence of marketing inflation. +- **Vertical**: Editorial publication (specifically themed literary and ideas quarterly with multi-author masthead, each issue organized around a single question or theme). +- **Position summary**: A themed literary quarterly where each issue is a single question, the table of contents reads as variations on the question across disciplines, the design is restrained-considered with one literary accent colour. Not politically situated, not generationally branded, not topical, not single-author. The audience is literary readers across disciplines. + +## Positive references + +- [aeon.co](https://aeon.co) - Multidisciplinary ideas register. Considered design, restrained palette (warm-grey ground with deep type and a single accent), essays at substantial length, multiple disciplines per surface. Inherit the ideas-led register, the considered-but-not-luxe typography, the absence of marketing inflation. +- [thepointmag.com](https://thepointmag.com) - Themed multi-author essay structure at length. The closest peer on the audience axis (broadly literary readers across disciplines). Inherit the multi-author themed-issue treatment and the essay-length expectation. +- [cabinetmagazine.org](https://cabinetmagazine.org) - The closest structural anchor in the field: each issue is organized around a single thematic question rendered with editorial restraint. Inherit the single-theme-per-issue structure and the question-as-masthead treatment. +- [canopycanopycanopy.com](https://canopycanopycanopy.com) - Triple Canopy. Themed digital-first sequenced issues with editorial restraint. Inherit the digital-first design discipline and the sequenced-issue numbering. + +## Negative references + +- [thedriftmag.com](https://thedriftmag.com) - Politically situated, generationally branded, identity-forward. A considered quarterly must avoid the political-statement register on conversion architecture, palette, and voice. +- [nplusonemag.com](https://nplusonemag.com) - Institutional NY cultural authority register. A considered quarterly should not borrow the geographic or generational positioning. +- [laphamsquarterly.org](https://laphamsquarterly.org) - Historical-source-driven format (passages from historical writing assembled around a theme). A different format entirely; canonical to that publication and not transferable. +- [believermag.com](https://believermag.com) - McSweeney's-adjacent geometric illustration identity. A type-led quarterly should not borrow the illustration-led visual treatment. +- [atavist.com](https://atavist.com) - Single-essay-per-issue reportage register. A multi-essay themed quarterly is a different shape. +- [themarginalian.org](https://themarginalian.org) - Single-author blog register. A multi-author themed quarterly is a different shape. + +## Extension note + +- Seeded from the Caesura editorial-publication brief (the first portfolio entry in the editorial-publication shape, using the extended creative-brief-selector framework with hero_shape and footer_shape as first-class outputs). The pure `editorial-restrained` archetype combined with the type-led-prose hero and editorial-colophon-with-masthead footer renders as the natural literary-publication fit; the framework's extended rules align with the register's tradition rather than fighting it. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md new file mode 100644 index 0000000..ec9fae5 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md @@ -0,0 +1,20 @@ +# Heritage local service, barbershop + +- **Archetype**: `warm-conversational` with `retro-nostalgic` as the composition secondary. The lead is warm-everyday-craft (real-room atmosphere, social proof from genuine reviews, real-team page); the secondary is period-specific cues (walnut wood, brass fittings, marble counters, restrained palette). +- **Vertical**: Hospitality and local service (specifically neighborhood barbershops). +- **Position summary**: A heritage neighborhood shop with craft-and-space-led atmosphere, real-people-real-work proof, social proof drawn from review aggregates rather than fabricated testimonials. Initials over fabricated portraits when fictitious-brand demos cannot ethically render faces. + +## Positive references + +- [therosemontbarbers.com](https://therosemontbarbers.com) - Cuts gallery, interior atmosphere, social-proof badge, real team page in the heritage register. +- [speakeasybarberlounge.com](https://speakeasybarberlounge.com) - Atmosphere-led, period-specific cues (lounge fittings, warm interior), interior photography carries the page. +- [franksdenver.com](https://franksdenver.com) - Heritage register at a higher-end price point; restrained palette, considered editorial layout. +- [alfanisbarbershop.com](https://alfanisbarbershop.com) - Small-operator heritage, atmosphere-forward, real-team page. + +## Negative references + +- The chain barbershop register (Great Clips, Supercuts, Sport Clips and the like) - High-volume operational chains in the same vertical but in a fundamentally different register: utility-led, promotion-driven, no atmosphere. A heritage maker pulling from this register loses the position. + +## Extension note + +- Seeded from the Iron and Rye Barbershop atmosphere imagery pass. The seed positive references were used as register cross-checks during the build's still-life and interior shots. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md new file mode 100644 index 0000000..3b4fced --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md @@ -0,0 +1,20 @@ +# Hospitality experience, balloon ride + +- **Archetype**: `documentary-honest` with `luxe-considered` as the composition secondary. The lead is photography-led documentary realism (real landscape, real light, the morning as it actually looks); the secondary is aspirational-experience polish (named arc, named prices, named safety signals). +- **Vertical**: Hospitality experience (specifically scenic flight or ride experiences, with the balloon ride as the worked example). +- **Position summary**: A photography-led experience operator with the morning arc surfaced explicitly, named packages with named prices above the fold, four trust signals (FAA certification, lead pilot hours, weather posture, cancellation) surfaced as the booking-confidence layer. No fabricated identifiable faces; environmental imagery only. + +## Positive references + +- [napavalleyaloft.com](https://napavalleyaloft.com) - Regional operator, atmosphere-forward, dawn-palette imagery. +- [aerogelichotairballooning.com](https://aerogelichotairballooning.com) - Atmosphere-led, ride arc surfaced, photography drives the page. +- [rainbowryders.com](https://rainbowryders.com) - Multi-region operator, photography-led, named packages with prices. +- [sundanceballoons.com](https://sundanceballoons.com) - Multi-region operator, considered-warm register, ride-arc framing. + +## Negative references + +- Generic adventure-tour aggregators (Viator, GetYourGuide, and similar) - Stock photography pile, undifferentiated palette, transactional layout. A photography-led operator pulling from this register loses the atmosphere that justifies the price. + +## Extension note + +- Seeded from the Drift and Dawn imagery pass and the audited-field competitor set used during that build's Stage 1. The dawn-palette retune was driven by the gap between the original stone-and-amber default and the actual dawn light these references carry. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md new file mode 100644 index 0000000..52aff00 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md @@ -0,0 +1,33 @@ +# Luxe-considered, curated short-term-stays directory-marketplace + +- **Archetype**: `luxe-considered` (pure; no composition secondary). The aspirational curated-stays register the hospitality vertical file names as Aman and Four Seasons: serif-led, understated authority, image-forward, the stay as a designed object. The escapist warmth is carried by a warm palette and a host-voice convention, not by a second archetype. Documentary Honest (the mass-market Airbnb register and a recurring portfolio secondary), Editorial Restrained (another build's exact luxe composition string), and Warm Conversational (the review-platform register) were each considered and rejected as secondaries; pure Luxe is the fit. +- **Vertical**: Directory-marketplace (specifically an aspirational curated short-term-rental marketplace of many independent hosts' standout stays). The second directory-marketplace entry in the bank; with the trades-directory entry it shows the shape across two opposite registers (functional-tool versus escapist-aspirational). +- **Position summary**: A small, curated marketplace a traveler dreams through, where the property photography carries the page and the stay is the product. Image-forward, escapist, design-forward; inventory grouped into curated collections; trust built on a stated verification claim rather than a fabricated-metric arms race. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (curated collections, image-forward discovery, the property-as-monograph, restrained booking affordances) and pulls NO palette, type, trade dress, photography style, or grid treatment from any specific real platform. + +- [plumguide.com](https://plumguide.com) - The curated-design short-term-stay register: a small vetted collection rather than the long tail, each stay presented with editorial care. Inherit the curated-collection posture and the property-as-monograph anatomy; do NOT pull the palette, type, or the specific listing-grid treatment. +- [boutique-homes.com](https://boutique-homes.com) - The design-led curated-stays register: architecturally distinctive properties grouped by design feeling. Inherit the design-forward collection grouping and the generous property gallery; do NOT pull the trade dress. +- [onefinestay.com](https://onefinestay.com) - The upper-curated hospitality register: a small set of standout homes with a hotel-grade presentation. Inherit the restrained-confident chrome and the aspirational photo direction; do NOT pull the palette or the brand identity. + +## Negative references + +- Functional-tool consumer directories (the trustworthy-direct-functional trades-directory neighbourhood; the same directory-marketplace shape in the opposite register). The functional tool a user controls is the deliberate opposite of the escapist marketplace a traveler dreams through; the shape and the multi-provider conventions are shared, the register is inverted. +- Single-operator hospitality-experience brands (one operator selling its own arc). The count axis differs: a curated-stays marketplace lists many independent hosts, not one operator's owned experience. +- Mass-market transactional rental platforms (the high-volume long-tail booking engines with urgency banners, opaque ranking, and dense result grids). Wrong register: a curated marketplace presents a small standout set as a publication, not the whole inventory as a funnel. + +## Multi-provider conventions (reframed for hosts and stays) + +The directory-marketplace shape's multi-provider conventions (first encoded by the trades-directory entry) carry forward, reframed from providers to hosts and stays: + +- **Brand versus host voice.** The marketplace brand's voice is the site voice throughout; each property carries a short host voice (a one-line note on why the place is worth the trip) only inside its card and detail, set with a typographic voice-shift. The brand never speaks as a host; hosts never speak as the brand. +- **Discoverability is the spine, image-forward.** The home is a search-and-browse surface where the property photography carries the page (the aspirational counterpart to the functional-categorical discovery of a trades directory). The hero is image-forward, not a functional tile grid. +- **Listing density, organized as collections.** Curated themed collections (coastal escapes, design landmarks, mountain retreats) rather than flat categories; roughly 4 to 6 collections with 4 to 8 properties each (24 to 40 properties). The collection is itself an editorial act. +- **Comparison surface.** Properties comparable within a collection on a small honest set (location, sleeps, stay-type, a demo-only rate band), with a within-collection compare view. +- **Reviews-and-ratings honesty resolution.** A demo-only Verified Host badge with its meaning stated plainly, plus an explicit "Demo: no reviews shown" placeholder slot and an aggregate-rating placeholder. The full trust UX is visible without fabricating a single review, rating, or superhost-style metric. Hosts are represented by their properties and a one-line voice, NOT by fabricated headshots; properties are set in fictitious locations; no real platform is named, even in negation. + +## Extension note + +- Seeded from the Lodestar curated-stays marketplace brief (the fifteenth and final showcase demo; the second directory-marketplace shape and the same-shape divergence partner to the trades-directory entry, running maximal-distance mode within the shape). Anchored to the hospitality and travel vertical file (`12-hospitality-travel.md`), which names pure Luxe Considered as the aspirational-hospitality register and Documentary Honest as the mass-market Airbnb register. The styled-aspirational property photography carries a real drift profile for the imagery pass: real-listing-platform aesthetic mimicry and fabricated-location-resemblance, both flagged for the build's NEGATIVE_GUARDRAILS, plus no real brand marks in any property image. The palette must read warm-aspirational (a design-hotel sandstone-clay-brass family) and must not reuse the trades-directory's cool functional family or any shipped warm-hospitality family. Last updated: 2026-05-29. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md new file mode 100644 index 0000000..aaf9c53 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md @@ -0,0 +1,23 @@ +# Luxe-considered-editorial-restrained, residential architectural brokerage + +- **Archetype**: `luxe-considered` with `editorial-restrained` as the composition secondary. The lead is the gallery-monograph register: premium, considered, type-and-photography-led, design-literate. The secondary is design-publication restraint: listings rendered as small monographs, the architect-and-year credit at byline weight, the brokerage represented as a practice rather than as a roster of agents. +- **Vertical**: Inventory-listing (specifically residential brokerage of architecturally significant homes: modernist, mid-century, architect-designed new builds, design-forward renovations). +- **Position summary**: A luxe residential brokerage that treats each architecturally significant home as a small monograph. The architect, the design year, the materials, the siting, and the light are first-class fields on every listing. The brokerage speaks as a design-literate practice rather than as a roster of individual agents. + +## Positive references + +- [themodernhouse.com](https://themodernhouse.com) - The canonical reference for the design-led residential brokerage register at editorial-restrained tier. Each listing reads as a small monograph; the architect is named in the listing card; the photography is disciplined. Inherit the listing-as-monograph anatomy and the considered-restraint voice. (Cited as a register anchor, not for trade dress copy; the negative-reference frame governs which brokerages a build must not pull trade dress from.) +- [phillips.com](https://phillips.com/design) - Phillips's design auction catalog register. The monograph treatment per lot (designer, year, materials, provenance) transfers cleanly to a residential listing. Inherit the per-lot monograph anatomy. +- [dezeen.com](https://dezeen.com) - The architectural press register. Listing-style architecture coverage with architect credits, year, materials, photography. Inherit the architecture-press literacy and the credit-line convention. +- [architecturaldigest.com](https://architecturaldigest.com) - The design-publication register with residential homes covered as design objects. Inherit the photography sensibility and the design-publication restraint. + +## Negative references + +- [zillow.com](https://zillow.com) - Mass-market portal; algorithmic listing presentation, estimated-value overlays, financing-first conversion. The register a luxe-considered brokerage must avoid on conversion architecture, palette, and voice. +- [realtor.com](https://realtor.com) - Same mass-market portal register; broker-listing-syndication shape, generic photography presentation. +- [redfin.com](https://redfin.com) - Mass-market portal with light brokerage layer; price-anxiety scoring, financing partnerships surfaced as primary CTAs. +- High-volume luxury brokerages whose primary surface is personality-led agent funnels. The architectural-monograph register is a practice, not a personal brand; the no-fabricated-agent-headshots line in the honesty contract is the structural rationale. + +## Extension note + +- Seeded from the Datum residential-brokerage brief (the first portfolio entry in luxe-residential-architectural-brokerage and the first same-shape divergence test in the portfolio; second inventory-listing build, the first being the rugged-utilitarian Treeline Motors marketplace). The brief documents the Section Shapes Rule 5 block on the two obvious luxe-architectural defaults (full-bleed-image-with-overlay and dual-column-image-and-text) and the resulting selection of asymmetric-large-image-small-text as the hero shape. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md new file mode 100644 index 0000000..5083d66 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md @@ -0,0 +1,34 @@ +# Minimal-essentialist-documentary-honest, local-trades directory + +- **Archetype**: `minimal-essentialist` with `documentary-honest` as the composition secondary. The lead is the functional-tool register (clean, organized, content-forward, reduced chrome; the page is the directory and the chrome recedes to let the listings carry). The secondary is honest-transparency trust (a stated verification claim, honest placeholders where reviews would render, real-context provider photography). The marketplace platform-versus-provider principle is the structural rationale: the directory brand must not compete with the provider identities, so restraint wins. +- **Vertical**: Directory-marketplace (specifically a homeowner-facing local-trades directory of many independent providers across real trade categories: plumbing, electrical, HVAC, carpentry, painting, roofing). The first multi-provider entry in the bank. +- **Position summary**: A clean, trustworthy directory tool the homeowner controls, light-mode-first, where the categories and the providers are the page. Discoverability is the spine, comparison is core, and the trust is built on honest transparency rather than on warmth or on clinical authority. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (search-first discovery, category browse, provider listings, a comparison surface, a verification claim) and pulls NO palette, trade dress, logo language, or conversion-funnel pattern from any specific real directory. + +- [angi.com](https://angi.com) - The modern consolidated home-services directory register: category-and-location search, provider listings, the lead-handoff conversion. Inherit the search-first discovery spine and the category structure; do NOT pull the orange-and-green palette, the match-now funnel, or any trade dress. +- [thumbtack.com](https://thumbtack.com) - The matched-services register: structured by trade and location, provider profiles with comparable fields. Inherit the comparable-provider-profile anatomy; do NOT pull the blue palette or the get-matched interstitial funnel. +- [houzz.com](https://houzz.com) - The visual-services-directory register: real work photography carrying the provider listings. Inherit the documentary work-in-context photography direction (a trade in progress, a finished job), not glamour shots; do NOT pull the green-and-orange palette or the social-feed product framing. + +## Negative references + +- Warm-conversational single-provider service brands (a neighbourhood barbershop, a single local shop's site; the heritage-local-service register). Wrong register and wrong count: that is a single provider speaking warmly about itself, not a directory of many providers in a functional-trust tool. A trades directory must not read as one warm shop with extras. +- Magazine-editorial services-content sites (a home-improvement publication, a services-advice editorial). Wrong register: a directory is a functional tool, not a magazine pretending to be a directory; the editorial-publication register buries the listing density behind a narrative. +- Bold-cinematic or saturated AAA visual registers (a cinematic full-bleed experiential hero). Wrong register entirely: a directory reads functional, not experiential; an image-and-overlay cinema-poster hero is the opposite of the page-is-the-directory discovery spine. + +## Multi-provider conventions (new ground; inherited by future directory-marketplace briefs) + +The directory-marketplace shape is the first multi-provider register in the portfolio. These conventions are first-class and carry forward: + +- **Brand versus provider voice.** The directory brand's voice is the site voice throughout; each provider has its own short voice only inside its listing card (a one-line how-we-work statement). The directory speaks as the trustworthy tool; the providers speak as themselves inside their cards. (Single-provider builds never had to navigate this distinction.) +- **Discoverability is the spine.** The home page is a search-and-browse surface (category-and-location search, category tiles, provider cards), not a hero-and-essay narrative. A `grid-of-elements` hero fits naturally; a type-led or image-and-overlay hero does not. +- **Listing density.** A meaningful directory reads as real only at sufficient density: roughly 4 to 6 categories with 4 to 8 providers each (16 to 48 total). Fewer reads as a single-provider demo with extras; more risks bloat. +- **Comparison surface.** Providers within a category are comparable on a small honest set of dimensions (service area, specialties, years in business), not on an opaque ranking score. Comparison is core to the pattern. +- **Reviews and ratings are the canonical fabrication risk, and the resolution is honest UX without fabricated content.** A directory conventionally shows aggregate ratings, review counts, and written reviews; a demo cannot fabricate any of them. The resolution: an explicit "Demo: no reviews shown" placeholder slot where review content and an aggregate rating would render, plus a demo-only "Verified Pro" badge (the directory's own badge, meaning stated, not a real accreditation) where earned. The directory's full trust UX is visible without a single fabricated review, rating, license number, or certification. +- **Real categories, fictitious providers.** The trade categories are real; the providers within them are demo-fictitious, with names vetted against recognizable businesses (a proprietor-surname-plus-trade format), set in a fictitious city, with schematic service-area maps and no fabricated license numbers, certifications, or accreditation marks. + +## Extension note + +- Seeded from the Tradepost local-trades directory brief (the first directory-marketplace shape and the first multi-provider demo in the portfolio; the seventh selector-led build). The brand-archetype-system has no dedicated home-services, local-services, or trades vertical file; this build used `16-marketplace.md` (the two-sided-platform register) as the closest anchor, and the gap is flagged for a future skill-extension dispatch to add a dedicated local-services-and-trades vertical file. Tradepost runs maximal-distance mode; it is the same-shape divergence partner to a forthcoming vacation rental marketplace (the Browse-AI attended capstone), and the two diverge naturally because the verticals differ. The palette deliberately avoids the recognizable real-brand directory colours (Angi orange-and-green, Thumbtack blue, HomeAdvisor orange, Yelp red, Houzz green-and-orange, Yellow Pages yellow-and-black). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md new file mode 100644 index 0000000..8a7d341 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md @@ -0,0 +1,22 @@ +# Premium DTC maker, western boots + +- **Archetype**: `luxe-considered` with `rugged-utilitarian` as the composition secondary. The lead is premium-considered (editorial layout, prices visible, restrained merchandising); the secondary is workwear-and-craft (heritage materials, hand-welt construction, made-to-last positioning). +- **Vertical**: DTC fashion (specifically western boots). +- **Position summary**: A premium small-collection western-boot maker, leather-forward, product-photographed, prices visible, no discount cadence, no SKU-strip-above-the-fold. Confident, not promotional. + +## Positive references + +- [tecovas.com](https://tecovas.com) - The elevated-DTC reference: product-forward hero, named prices visible, restrained merchandising. No discount banners above the fold. +- [lucchese.com](https://lucchese.com) - Heritage register; serif-led, craft narrative as a supporting band rather than the lead. +- [oldgringoboots.com](https://oldgringoboots.com) - Smaller-maker, leather-forward photography, restrained editorial set instead of catalog density. +- [ranchroadboots.com](https://ranchroadboots.com) - Small-operator boutique competing in the same position; useful for cross-checking how a peer maker handles wayfinding on a small collection. + +## Negative references + +- [durangoboots.com](https://durangoboots.com) - Catalog-dense big-box texture; discount cadence, SKU-strip-above-the-fold, sale-badge pile. Not the register a premium small maker should pull from. +- [justinboots.com](https://justinboots.com) - Same big-box texture in a different brand; promotional banners and grid density dominate. +- [bootbarn.com](https://bootbarn.com) - Multi-brand retailer rather than a maker; merchandising-led rather than craft-led. + +## Extension note + +- Seeded from the Pinto Mesa Boots store-spine brief (the worked example of the brief template). Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md new file mode 100644 index 0000000..b260e05 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md @@ -0,0 +1,24 @@ +# Rugged-utilitarian-documentary-honest, regional used-vehicle marketplace + +- **Archetype**: `rugged-utilitarian` with `documentary-honest` as the composition secondary. The lead is workwear-and-craft (Mountain West heritage utility register); the secondary is data-forward documentary (transparency-first listings, real photography, real source attribution). +- **Vertical**: Inventory-listing (specifically regional used-truck-and-SUV marketplace serving working-vehicle buyers, not full passenger-car market). +- **Position summary**: A regional working-vehicle specialist marketplace, transparency-first on every listing, documentary photography of vehicles in working context, plain-direct voice that speaks with familiarity of the terrain its audience drives. Specialist, not generalist; transparent, not promotional; regional, not national. + +## Positive references + +- [bringatrailer.com](https://bringatrailer.com) - The canonical listing-detail transparency reference: full ownership history, mileage timeline, photograph density (forty to one hundred photographs per lot is typical), a comments thread that adds provenance. Inherit the listing-detail anatomy and the source-attributed transparency posture. Diverge from the auction format; a fixed-price marketplace borrows the transparency without the closing-clock. +- [icon4x4.com](https://icon4x4.com) - Editorial documentary register applied to working vehicles. Inherit the photography direction (vehicles photographed in landscape and at work, not glamour shots on a studio seamless), the considered editorial type, and the absence of promotional banners. +- [filson.com](https://filson.com) - Mountain West heritage workwear register. Inherit the palette tendency (granite, evergreen, oxblood, aspen gold; cool ground with restrained accents), the documentary photography that supports the type rather than fighting it, and the plain-direct voice. +- [patagonia.com](https://patagonia.com) - The adjacent outdoor-utility register, useful as the second positive on voice (plain-direct, no marketing inflation, the audience treated as competent). + +## Negative references + +- [cargurus.com](https://cargurus.com) - Mass-market national passenger-car register; price-anxiety scoring as the hero, financing-first conversion architecture. The register a specialist regional marketplace must avoid on conversion architecture, palette, and voice. +- [cars.com](https://cars.com) - Same mass-market national register; promotional banner cadence, broad-inventory generalist posture. +- [carvana.com](https://carvana.com) - DTC mass-market with vending-machine theatrics, financing-first. The register to avoid on theatrics and on conversion-flow priority. +- [autotempest.com](https://autotempest.com) - Meta-aggregator with no editorial voice; utility-only search-across-the-others. A specialist marketplace must not read as utility-only. +- [edmunds.com](https://edmunds.com) - Research-led advisory; content-heavy editorial sitting adjacent to a marketplace. A specialist marketplace must not read as a magazine pretending to be a marketplace. + +## Extension note + +- Seeded from the Treeline Motors inventory-listing brief (the second batch-two build using the creative-brief-selector skill end to end). The Bring a Trailer reference is dual-positioned: positive on listing-detail transparency, negative on format (auction vs fixed-price marketplace). Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief/SKILL.md b/dist/pi/.agents/skills/creative-brief/SKILL.md new file mode 100644 index 0000000..8e18b1c --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/SKILL.md @@ -0,0 +1,158 @@ +--- +name: creative-brief +description: "Create or refine a creative brief that bridges discovery and execution. Use this skill whenever the user is starting a new project, kicking off a website, beginning a brand build or redesign, briefing a designer or developer or AI agent, or trying to align a team before building. Triggers on creative brief, design brief, brand brief, project kickoff, kicking off, briefing the team, project intake, design direction, brief the designer, brief the dev, where do we start, how do we start, write a brief, project overview, scope this project, align on direction. Also triggers when the user has a vague idea and needs to make it concrete enough to hand off, even if they do not say 'brief' explicitly." +category: strategy-and-discovery +catalog_summary: "Project briefs that align stakeholders before work starts" +display_order: 2 +--- + +# Creative Brief + +Bridges discovery and execution. Translates "we want a website" into a brief a designer, developer, or AI agent can actually run with. + +--- + +## When to use + +- Starting a new project (website, app, brand, campaign) +- Kicking off a redesign or rebrand +- Handing work to a designer, developer, or AI agent +- Aligning a team that has drifted off course +- Turning a vague idea into something buildable + +## When NOT to use + +- The user is asking a one-off design question (use `design-standards`) +- The user wants a PRD or dev ticket (use `pm-spec-writing`) +- The user is doing initial research and has not decided what they are building (use `brand-discovery` first) +- The user just wants you to write copy (use `content-and-copy`) +- The user already has scope and constraints settled and needs deeper aesthetic direction specifically (use `creative-direction` for the structured aesthetic axes) + +--- + +## Required inputs + +A brief needs answers to ten questions. Before writing, confirm you have answers (or can elicit them) for: + +1. What is the project? +2. Why does it exist? What problem does it solve? +3. Who is the audience? +4. What do you want them to do, feel, or know? +5. What is the personality? How does it sound? +6. What is the visual direction? How does it look? +7. What is in scope? What is out? +8. What are the constraints (time, budget, technical, brand)? +9. What does success look like? +10. Who approves? + +If you have fewer than five of these, run a quick intake first. See "Eliciting missing info" below. + +--- + +## The framework: brief structure + +Output a markdown brief with these ten sections. Keep each section tight. A good brief is two pages, not ten. + +### 1. Snapshot +One paragraph answering: what, who, why, when. The kind of thing you would say at a kickoff in thirty seconds. + +### 2. Audience +Primary audience first. Include who they are, what they are trying to do, what is blocking them today, and where you reach them. Add secondary audiences only if they materially change the work. + +### 3. Objectives +What success looks like. Pair every objective with a measurable signal. + +> Objective: drive trial signups. +> Signal: 3 percent conversion from homepage to signup within 30 days of launch. + +### 4. Key message +The one thing you want a visitor to walk away knowing. If they see only the homepage hero and bounce, what should they remember? One sentence. + +### 5. Voice and tone +Pick three to five adjectives. Pair each with what you are NOT (e.g. "confident, not arrogant"). See [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) for frameworks and worked examples. + +### 6. Visual direction +Mood, palette, type, and imagery direction. Three to five reference URLs are worth more than 500 words. Note what you like AND what you would reject. + +### 7. Scope and deliverables +A bulleted list of what is being made. Be specific. "Homepage" is not a deliverable. "Homepage with hero, three feature blocks, testimonial carousel, and contact CTA" is. + +### 8. Constraints +Time. Budget. Technical (existing stack, required integrations, hosting). Brand (logo, colors, fonts that must be used). Legal (compliance, accessibility level required). + +### 9. Inspiration and competitors +Three to five sites or brands you want to feel like, three to five you want to feel different from. Note WHY for each. + +### 10. Approval +Who signs off. What artifact triggers sign-off (a Figma file, a staging URL, a PDF). What happens if there is no sign-off by a deadline. + +--- + +## Eliciting missing info + +If the user comes with a partial answer (e.g., "I want a website for my coffee shop"), do not just write a generic brief. Ask. Use these prompts. + +**For audience** +- Who is the single most likely person to land on this site? Walk me through their day. +- If you could pick one type of customer to fill your inbox, who? +- Who do you NOT want to attract? + +**For objectives** +- Pretend it is six months after launch. What number tells you it worked? +- What is the one action you most want a visitor to take? + +**For voice** +- Pick three brands or people whose tone you would want to borrow. +- If your site were a person at a dinner party, what would they sound like? + +**For visuals** +- Show me three sites you love. What do you love about them? +- Show me one site you hate. Why? + +**For scope** +- If you only got one page, which one? +- What would you cut if the budget were halved? + +Do not ask all of these. Pick the ones that fill the actual gaps. + +--- + +## Workflow + +1. **Read the conversation.** Pull every fact already given. Do not ask questions you can answer from context. +2. **Identify gaps.** Which of the ten required inputs are missing or thin? +3. **Run intake.** Ask three to five targeted questions to fill the gaps. Group related questions to keep the conversation tight. +4. **Draft the brief.** Use [`references/creative-brief-template.md`](references/creative-brief-template.md) as the structure. Keep it under 1500 words. +5. **Stress-test.** Before delivering, check the brief against the failure patterns below. If any apply, revise before showing the user. +6. **Deliver.** Save as `creative-brief.md` in the project root. Offer to make it a Word doc or PDF if the user wants something to share with stakeholders. +7. **Hand off for aesthetic depth (optional).** For projects where sections 5 (voice and tone) and 6 (visual direction) need more rigor than this brief surfaces, run `creative-direction` next. It produces a structured aesthetic brief using four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) that content, copy, and art-direction skills consume directly. + +--- + +## Failure patterns + +When the user's input matches one of these patterns, push back before writing. + +- **"We want to be the [giant brand] of [our niche]."** Ask what specifically about that brand they want to borrow. Probably one or two things, not the whole thing. +- **Audience as "men and women 18-65."** This is not an audience. Ask for the single most valuable customer type and start there. +- **"Increase awareness" with no metric.** Awareness of what, by whom, measured how? Push for a number. +- **"Modern, clean, minimalist."** These words are meaningless. Ask for three specific URLs they think look right. +- **Twenty pages of context, no clear ask.** Ask: "If a designer reads only one paragraph, what should it be?" Then make that the snapshot. + +--- + +## Output format + +Default output is a markdown file at `creative-brief.md` in the project root. Structure follows the template exactly. + +If the project is large, split: keep the main brief under 1500 words and put detail in linked appendices (`audience-research.md`, `brand-guidelines.md`, etc.). Briefs that try to be everything end up read by no one. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Fillable template. Copy and use as the starting point. +- [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) - Voice frameworks, brand archetypes, and worked patterns. +- [`references/example-brief.md`](references/example-brief.md) - A worked example for a fictional B2B SaaS, showing what a "good" filled brief looks like. + +Read the template before drafting. Read the voice guide if the user has not already specified a voice. Read the example if you are unsure how filled-out a section should be. diff --git a/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md b/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md new file mode 100644 index 0000000..7d57fc3 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md @@ -0,0 +1,185 @@ +# Creative Brief: [Project Name] + +**Date:** [YYYY-MM-DD] +**Author:** [Who wrote this brief] +**Stakeholders:** [Who needs to sign off] +**Status:** Draft / In review / Approved + +--- + +## 1. Snapshot + +[One paragraph. What is this project, who is it for, why does it exist, and when does it need to be done? Aim for 3 to 5 sentences.] + +**Quick facts** +- Project type: [Website / app / brand / campaign / other] +- Launch target: [Date or quarter] +- Budget tier: [Range or "to be confirmed"] +- Stack constraints: [Required tech or "open"] + +--- + +## 2. Audience + +**Primary audience** + +Who: [One specific persona, not a demographic range] + +What they are trying to do: [The job they are hiring this product to do] + +What is blocking them today: [The friction they are experiencing now] + +Where you reach them: [Channels: search, social, referral, paid, etc.] + +**Secondary audience** (only if it changes the work) + +[Same structure, briefer.] + +**Anti-personas** + +- [Type of customer you do NOT want to attract, and why] + +--- + +## 3. Objectives + +| Objective | Measurable signal | Timeframe | +|---|---|---| +| [What you want to achieve] | [How you know it worked, with a number] | [When you measure] | +| | | | +| | | | + +--- + +## 4. Key message + +[One sentence. If a visitor saw only the hero and bounced, what should they remember?] + +--- + +## 5. Voice and tone + +**We sound:** [3 to 5 adjectives] + +**We do not sound:** [The mirror image of each adjective] + +| We are | We are NOT | +|---|---| +| [Adjective] | [What it could tip into if overdone] | +| | | +| | | + +**Examples of our voice in the wild** + +- [Brand or writer 1, and what specifically about them] +- [Brand or writer 2, and what specifically about them] + +--- + +## 6. Visual direction + +**Mood:** [3 to 5 words] + +**Palette direction:** [Light/dark, warm/cool, saturated/muted, plus any required brand colors] + +**Type direction:** [Serif/sans, display vs body, formal vs casual] + +**Imagery direction:** [Photography style, illustration style, iconography] + +**Reference sites we want to feel like** + +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] + +**Reference sites we want to feel different from** + +- [URL]: [What we are rejecting] +- [URL]: [What we are rejecting] + +--- + +## 7. Scope and deliverables + +**In scope** + +- [Specific deliverable 1, with detail] +- [Specific deliverable 2, with detail] +- [Specific deliverable 3, with detail] + +**Out of scope** + +- [Things explicitly not being built in this project] + +--- + +## 8. Constraints + +**Timeline** + +- [Milestone 1]: [Date] +- [Milestone 2]: [Date] +- [Launch]: [Date] + +**Budget** + +- [Range or specific number, plus what it covers] + +**Technical** + +- Existing stack: [What is already in place] +- Required integrations: [Analytics, CRM, payment, etc.] +- Hosting: [If specified] + +**Brand** + +- Required: [Logo, colors, fonts, marks that must be used] +- Available: [Brand assets the team can pull from] + +**Legal and compliance** + +- Accessibility level: [WCAG AA / AA+ / AAA] +- Privacy: [GDPR / CCPA / other] +- Industry: [Any sector-specific requirements] + +--- + +## 9. Inspiration and competitors + +**Inspiration (the feel we want)** + +| Site / brand | What we love | +|---|---| +| [URL] | [Specific element] | +| [URL] | [Specific element] | +| [URL] | [Specific element] | + +**Competitors (in our category)** + +| Site / brand | How we differ | +|---|---| +| [URL] | [Where we want to position differently] | +| [URL] | [Where we want to position differently] | + +--- + +## 10. Approval + +**Sign-off owner:** [Name, role] + +**Sign-off artifact:** [What needs to be approved: brief, comps, staging URL, etc.] + +**Sign-off deadline:** [Date] + +**If no sign-off by deadline:** [Default action: ship anyway, escalate, pause, etc.] + +--- + +## Appendix (optional) + +Link out to anything that would otherwise bloat the brief. + +- [Audience research] [link] +- [Competitive analysis] [link] +- [Brand guidelines] [link] +- [Technical requirements] [link] diff --git a/dist/pi/.agents/skills/creative-brief/references/example-brief.md b/dist/pi/.agents/skills/creative-brief/references/example-brief.md new file mode 100644 index 0000000..cef9a7f --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/example-brief.md @@ -0,0 +1,206 @@ +# Creative Brief: Plumb + +**Date:** 2026-04-15 +**Author:** Maria Chen, Founder +**Stakeholders:** Maria Chen (sign-off), Devon Park (engineering), Sasha Williams (design lead) +**Status:** Approved + +--- + +## 1. Snapshot + +Plumb is infrastructure observability built for small DevOps teams. We are launching a marketing site and product trial flow to support our public beta in Q3 2026. The site needs to convert technical buyers from a homepage visit to a trial signup, and clearly position us as the "right-sized" option against the heavy enterprise incumbents. Target launch: July 15, 2026. + +**Quick facts** +- Project type: Marketing website + trial signup flow +- Launch target: July 15, 2026 +- Budget tier: $25K design + dev, plus internal team time +- Stack constraints: Next.js + Vercel, with Supabase for the trial flow + +--- + +## 2. Audience + +**Primary audience** + +Who: A staff or principal engineer at a 20 to 200 person startup, currently the unofficial owner of the team's monitoring stack. They got handed Datadog two years ago, the bill is now embarrassing, and they want a defensible alternative they can sell internally. + +What they are trying to do: Cut the monitoring bill by at least 40 percent without taking on a tool that requires a dedicated SRE to operate. + +What is blocking them today: Datadog is too expensive and too sprawling. Grafana is technically free but burns engineering time on maintenance. Both feel built for someone three sizes bigger. + +Where you reach them: Hacker News, the changelog blog, lobste.rs, technical Twitter, dev-focused podcasts (Changelog, Software Engineering Daily), and search ("alternative to datadog", "self-hosted monitoring small team"). + +**Secondary audience** + +Engineering managers and CTOs at the same companies, who sign the invoice. They land later in the journey but need the pricing page and the ROI math to be airtight. + +**Anti-personas** + +- Enterprise procurement teams. We do not want to attract Fortune 500 inbound. The product is not built for that scale and we do not want to spend cycles on RFPs. +- Hobbyists who want a free forever tier. We have a generous trial but no free tier. Bargain hunters churn. + +--- + +## 3. Objectives + +| Objective | Measurable signal | Timeframe | +|---|---|---| +| Drive trial signups from organic and content channels | 200 trial signups per month within 90 days of launch | By Oct 15, 2026 | +| Convert trials to paid | 12 percent trial-to-paid conversion | By end of Q4 2026 | +| Establish technical credibility | 50+ inbound mentions on HN, lobste.rs, or dev Twitter referencing the site or docs | By end of Q3 2026 | +| Reduce sales cycle for inbound | Pricing page transparent enough that 80 percent of inbound deals close without a sales call | Ongoing | + +--- + +## 4. Key message + +Plumb is observability that fits a 50-person engineering team, priced for a 50-person engineering team. + +--- + +## 5. Voice and tone + +**We sound:** Direct, technical, confident, dry-witted, practical. + +**We do not sound:** Cute, hand-wavy, salesy, corporate, or condescending. + +| We are | We are NOT | +|---|---| +| Direct | Blunt or rude | +| Technical | Inaccessible to a non-expert reader | +| Confident | Boastful | +| Dry-witted | Trying to be funny | +| Practical | Boring | + +**Examples of our voice in the wild** + +- Stripe docs, for the rhythm and the way they assume reader competence without showing off. +- Tailscale's blog, for the dry technical wit and willingness to admit tradeoffs. +- 37signals' product copy, for short sentences that earn their place. + +--- + +## 6. Visual direction + +**Mood:** Calm, confident, technical, slightly opinionated. A senior engineer's notebook, not a stadium. + +**Palette direction:** Predominantly light with strong dark-mode parity. Single accent color (deep teal). Charts and diagrams in muted, accessible color ramps. No gradients, no glow effects. + +**Type direction:** Geometric sans for display (Inter or similar), monospace for code and metrics (JetBrains Mono or similar). Generous line height. Comfortable for long-form reading. + +**Imagery direction:** Real screenshots of the product, annotated. Architecture diagrams drawn in a consistent simple style. No stock photos. No abstract 3D illustrations. No people in headsets pointing at laptops. + +**Reference sites we want to feel like** + +- linear.app: For the calm density and how every pixel feels intentional. +- planetscale.com: For technical credibility without enterprise stuffiness. +- fly.io: For the dry voice and the unapologetic technical depth on the homepage. + +**Reference sites we want to feel different from** + +- datadoghq.com: Too dense, too many product lines, screams "we will sell you everything." +- newrelic.com: Too corporate, too gradient-heavy, feels like 2018. + +--- + +## 7. Scope and deliverables + +**In scope** + +- Homepage with hero, three feature blocks, social proof, pricing teaser, footer CTA +- Pricing page with transparent tiers, calculator, and FAQ +- Product page with annotated screenshots and one short demo video +- About page (founder story, team, hiring CTA) +- Trial signup flow (3 steps: email + workspace name + first project setup) +- Docs index page that links into the existing docs site (separate property) +- Blog index and post template (engineering writing, changelog posts) +- 404 and other error pages + +**Out of scope** + +- Customer logos page (we do not have permissioned logos yet) +- Comparison pages (Datadog vs Plumb, etc.) - saved for Q4 once we have data +- Localization (English only at launch) +- Marketing automation integrations beyond a single newsletter capture + +--- + +## 8. Constraints + +**Timeline** + +- Brief approved: April 15, 2026 +- Wireframes: April 30 +- High-fi design: May 20 +- Dev complete: June 30 +- QA and content load: July 1 to July 12 +- Launch: July 15 + +**Budget** + +- $25K total: $15K design, $10K dev contractor for trial flow integration. Internal team handles content, brand assets, deploy. + +**Technical** + +- Next.js App Router on Vercel +- Trial flow writes to Supabase (existing project) +- Plausible for analytics (no Google Analytics) +- All pages must score 95+ on Lighthouse performance and accessibility +- Mobile baseline: 375px + +**Brand** + +- Logo: existing wordmark + glyph (provided) +- Colors: deep teal (#0F4C5C), slate gray scale, white. Single accent only. +- Type: Inter for display, JetBrains Mono for code + +**Legal and compliance** + +- Accessibility: WCAG 2.1 AA +- Privacy: GDPR compliant. EU users get a banner. Data residency in US-East. +- No customer testimonials with full names without written consent + +--- + +## 9. Inspiration and competitors + +**Inspiration** + +| Site / brand | What we love | +|---|---| +| linear.app | Density without clutter; type system; restraint | +| planetscale.com | How they explain technical concepts in the hero | +| fly.io | Voice, blog rhythm, code samples on the homepage | +| stripe.com/docs | The annotated examples pattern (we want to borrow this for the product page) | + +**Competitors** + +| Site / brand | How we differ | +|---|---| +| datadoghq.com | We are smaller, opinionated, and priced for teams under 200 | +| newrelic.com | We avoid enterprise sprawl. Single product, clear pricing | +| grafana.com | We are managed and easier to operate. We charge for the time savings | + +--- + +## 10. Approval + +**Sign-off owner:** Maria Chen + +**Sign-off artifacts:** +- Wireframes: review by April 30, async approval in Figma +- High-fi design: review by May 20, in-person review meeting + 48-hour async window +- Pre-launch site (staging URL): review by July 10, all stakeholders sign off in writing + +**Sign-off deadline:** Each stage above has a 48-hour async window after the review meeting. After 48 hours of no objection, the stage is approved and we proceed. + +**If no sign-off by deadline:** Default to ship. Maria has final say on any post-launch revision. + +--- + +## Appendix + +- [Audience research notes](./audience-research.md) +- [Competitive teardown](./competitive-analysis.md) +- [Brand guidelines](./brand-guidelines.md) diff --git a/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md b/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md new file mode 100644 index 0000000..a8fb49d --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md @@ -0,0 +1,200 @@ +# Voice and Tone Guide + +Voice is who you are. Tone is how you sound right now. Voice stays constant. Tone shifts with context (a 404 page sounds different from an onboarding email, even if the voice is the same). + +This guide gives you frameworks for picking a voice and adapting tone, plus worked examples. + +--- + +## Framework 1: Four dimensions (Nielsen Norman) + +Pick a position on each axis. Together they describe the voice. + +| Dimension | One end | Other end | +|---|---|---| +| Formality | Formal | Casual | +| Seriousness | Serious | Funny | +| Respectfulness | Respectful | Irreverent | +| Enthusiasm | Matter-of-fact | Enthusiastic | + +A bank: formal, serious, respectful, matter-of-fact. +A craft soda brand: casual, funny, irreverent, enthusiastic. +A premium watch brand: formal, serious, respectful, matter-of-fact. +A coding bootcamp: casual, serious, respectful, enthusiastic. + +If you cannot pick a position on each axis, the voice is not defined yet. + +--- + +## Framework 2: Brand archetypes + +Twelve archetypes from Jung-derived brand theory. Pick one primary and one secondary. + +| Archetype | Promise | Voice notes | Example brands | +|---|---|---|---| +| Innocent | Safety, simplicity | Warm, plain, reassuring | Dove, Coca-Cola | +| Sage | Truth, wisdom | Authoritative, considered, measured | Google, BBC, The Economist | +| Explorer | Freedom, discovery | Adventurous, restless, vivid | Patagonia, Jeep, Subaru | +| Outlaw | Disruption | Rebellious, blunt, anti-establishment | Harley-Davidson, Liquid Death | +| Magician | Transformation | Visionary, mysterious, evocative | Apple, Tesla | +| Hero | Mastery, courage | Bold, confident, action-driving | Nike, FedEx | +| Lover | Intimacy, beauty | Sensual, warm, indulgent | Chanel, Godiva | +| Jester | Joy, fun | Playful, irreverent, witty | Old Spice, Mailchimp, Slack | +| Everyman | Belonging | Friendly, plain, relatable | IKEA, Target | +| Caregiver | Service, compassion | Nurturing, warm, supportive | Johnson & Johnson, Volvo | +| Ruler | Control, prestige | Commanding, polished, exclusive | Rolex, Mercedes | +| Creator | Self-expression | Imaginative, articulate, craft-focused | Lego, Adobe | + +Two archetypes give you range. A primary "Sage" with secondary "Hero" is authoritative AND action-driving. A primary "Caregiver" with secondary "Sage" is supportive AND wise. + +--- + +## Framework 3: We are X, not Y + +The fastest voice exercise. Pick three to five adjectives. For each, name what it could tip into if overdone. + +> **Confident**, not arrogant. +> **Direct**, not blunt. +> **Warm**, not saccharine. +> **Witty**, not sarcastic. +> **Smart**, not condescending. + +The "not" half is what saves you. "Confident" alone leads writers to swagger. "Confident, not arrogant" tells them where the line is. + +--- + +## Tone shifts by context + +Voice stays. Tone shifts. Map the high-frequency moments and decide how each one sounds. + +| Moment | Tone shift | +|---|---| +| Onboarding | Warmer, more enthusiastic | +| Error message | Calmer, more matter-of-fact | +| Success state | Brief celebration, quickly redirect to next action | +| Empty state | Helpful, slightly playful, suggests action | +| 404 / not found | Self-aware, light, points the way home | +| Account deletion | Quiet, respectful, no jokes | +| Pricing page | Direct, clear, confidence-inspiring | +| Legal copy | Plain language version of the legal copy, sitting next to the legal copy | + +--- + +## Practical patterns + +Voice shows up in concrete choices. These are the dials. + +**Sentence length** + +- Short sentences = punchy, confident. (Apple, Stripe, Liquid Death.) +- Medium sentences = considered, professional. (Most B2B SaaS.) +- Long sentences = literary, premium, slow. (The New Yorker, premium watch brands.) + +**Vocabulary** + +- Plain (most words 1-2 syllables) = approachable, mass-market. +- Domain-specific = signals expertise to insiders, alienates outsiders. +- Coined or invented = builds a worldview but high risk if not earned (Apple's "Retina", Slack's "huddle"). + +**Pronouns** + +- "We" = the company speaking. +- "You" = the customer being addressed. +- "I" = a person speaking, not a company. Strong on personal brands and creator products. Weird on enterprise. + +**Contractions** + +- Use them = casual. +- Avoid them = formal. + +**Punctuation** + +- Em dashes = literary, breath-taking pauses. +- Semicolons = considered, formal, slightly old-school. +- Periods only = punchy, confident. +- Exclamation points = exuberant; lose credibility past one or two. +- Em dashes are popular but polarizing. Many writers and brands ban them outright; some lean on them. Pick a side. + +**Rhythm** + +Read your copy out loud. If you stumble, the rhythm is off. Vary sentence length. A page of all-short sentences feels staccato. A page of all-long sentences feels lecture-y. + +--- + +## Worked example: B2B SaaS + +**Voice** + +> **Direct**, not blunt. +> **Confident**, not cocky. +> **Practical**, not boring. +> **Smart**, not academic. + +**Archetype** + +Primary: Sage. Secondary: Hero. + +**Patterns** + +- Sentence length: short to medium. Lead with the headline, deliver the proof, exit. +- Vocabulary: plain, with domain terms when precision earns its keep. +- Pronouns: "we" for the company, "you" for the reader. Avoid "users." +- Contractions: yes. +- Em dashes: no. + +**Tone shifts** + +- Onboarding: warmer. Lean into "you can do this." +- Error: matter-of-fact. State what happened, what to do, no apology theater. +- Pricing: direct. List the number, list what's included, stop. + +**Sample** + +Bad (vague, hedged, overwrought): +> Our innovative platform leverages cutting-edge technology to revolutionize how teams collaborate on data-driven workflows. + +Good (direct, plain, confident): +> Move data between tools without writing code. Connect your stack in minutes. Built for teams that have outgrown spreadsheets. + +--- + +## Worked example: D2C food brand + +**Voice** + +> **Playful**, not goofy. +> **Honest**, not blunt. +> **Crave-worthy**, not gluttonous. +> **Curious**, not academic. + +**Archetype** + +Primary: Jester. Secondary: Everyman. + +**Patterns** + +- Sentence length: short. Hit the joke, get out. +- Vocabulary: plain. Sensory words land. +- Pronouns: "we" and "you," very conversational. +- Contractions: always. +- Punctuation: light. Periods do the work. + +**Sample** + +Bad (corporate, distant): +> We are committed to providing high-quality artisanal granola made with the finest organic ingredients sourced from trusted partners. + +Good (playful, sensory, confident): +> Crunchy. Honey-roasted. Made with oats from one farm in Wisconsin. We tried adding more stuff. It got worse. So we stopped. + +--- + +## When voice is locked + +A voice is locked when you can: + +1. State it in one sentence ("We sound like a senior engineer explaining something to a junior, with patience.") +2. Cite three brands or writers it borrows from, and what specifically. +3. Show a piece of copy and a critic could say "that does/does not sound like us" without arguing. + +If you cannot do all three, keep working on the voice. diff --git a/dist/pi/.agents/skills/creative-direction/SKILL.md b/dist/pi/.agents/skills/creative-direction/SKILL.md new file mode 100644 index 0000000..0545b60 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/SKILL.md @@ -0,0 +1,153 @@ +--- +name: creative-direction +description: "Walk the user through four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) and produce a structured aesthetic brief that downstream content, copy, design, and art-direction skills consume as required input. The aesthetic depth layer, distinct from `creative-brief` (operational kickoff: scope, audience, deliverables, constraints). Use when a project needs aesthetic coherence across many small decisions and the user has only a vague feeling, or when multiple downstream aesthetic-producing skills need a shared brief. Triggers on creative direction, aesthetic direction, set the aesthetic, define the visual direction, what's the vibe, what's the tone, the four axes. Does NOT fire for a general kickoff brief (use `creative-brief`), tactical single-piece work, already-documented direction, purely functional output, or locked production-stage work." +category: strategy-and-discovery +catalog_summary: "Four-axis aesthetic brief (tone, aesthetic, audience, sensory ambition) for cross-skill coherence" +display_order: 3 +--- + +# Creative Direction + +Frameworks produce competent output. Coherent output requires a brief. + +This skill turns vague creative intent into a structured brief that downstream skills can reference. It does not generate taste. It captures direction, so the dozens of small decisions a project requires (word choice, image selection, white space, sequencing, what to leave out) all answer to the same question. + +--- + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## When to use + +- The start of a multi-touchpoint project (website, brand, campaign, product launch) where aesthetic coherence matters +- Before running multiple downstream skills that need to share a unified voice and look +- When inheriting a project that has competent execution but feels generic or incoherent +- Recalibrating an existing project that has drifted aesthetically over time +- When the user is a non-curator who knows what feeling they want but cannot articulate the decisions that produce it + +## When NOT to use + +- Use `creative-brief` instead when the user needs a general kickoff brief covering scope, audience, deliverables, and constraints. This skill goes deeper on aesthetic axes specifically, not on the operational layer. +- Use `art-direction` instead when briefing a specific creative deliverable (photo shoot, illustration set, video, campaign). This skill produces project-wide aesthetic direction; `art-direction` extends that direction into specific creative work. +- Tactical single-piece work (one tweet, one error message, one button label) +- Projects where the user has complete aesthetic direction documented already (skip to downstream skills) +- Purely functional output (data tables, form labels, system status text) +- Production-stage execution where direction is already locked +- When the goal is to develop taste; this skill codifies intent, it does not develop judgment + +--- + +## Required inputs + +- Project name and one-paragraph description +- Target audience (rough is fine; full audience profiles come from `brand-discovery`) +- Business goal (what changes if this project works) +- Optional but high-value: 2 to 4 reference URLs (sites, brands, or pieces) the user admires, with a sentence on what specifically resonates +- Optional: existing brand assets if the project is a refresh, not greenfield +- Constraints worth declaring (parent brand voice, regulatory tone requirements, accessibility floors) + +--- + +## The framework: 4 directional axes + +A creative brief sits at the intersection of four axes. Each axis is a spectrum, not a binary. The user picks a position on each, knowing that the choice excludes adjacent positions for this project. + +### 1. Tone Register + +How formal is the work? How much heat does the language carry? + +**Positions:** + +- **Professional.** Measured, precise, low-register. Trusts the reader to do work. Restraint is the signal. +- **Conversational.** Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking. +- **Playful.** Wit, surprise, willingness to break form for effect. Risks the reader missing the point if not earned. +- **Provocative.** Pointed, opinionated, willing to take a position other brands will not. Risks alienating people who do not share the position. + +**How to choose:** What does the audience already get too much of, and what too little? If the category is dry, conversational or playful is differentiation. If the category is loud, professional restraint is differentiation. + +### 2. Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +**Positions:** + +- **Editorial Restrained.** Generous white space, single definitive image instead of grids, considered typography, low color count. Signals confidence and patience. +- **Polished Standard.** Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions. Signals competence and professionalism. +- **Controlled Maximalist.** High visual density where every element is intentional. Loud but engineered. Signals craft and conviction. +- **Expressive Maximalist.** Visual abundance, willingness to be loud, willing to clash. Signals energy and ambition. Hardest to execute well. + +**How to choose:** What is the project saying about the brand's relationship to attention? Restrained earns attention by deserving it. Maximalist captures attention by not letting it leave. + +### 3. Audience Relationship + +How does the brand position itself relative to the reader? + +**Positions:** + +- **Authority.** We tell you what is true. Implicit hierarchy, expertise on display, reader is the learner. +- **Peer.** We are figuring this out together. Equal footing, shared vocabulary, reader is the co-thinker. +- **Companion.** We walk with you. Lower hierarchy than authority, more presence than peer, reader is the protagonist of their own work. +- **Coach.** We challenge you. The brand pushes the reader toward something they would not push themselves toward alone, reader is the trainee. + +**How to choose:** What does the audience need most? Audiences who feel lost want authority or coach. Audiences who feel patronized want peer or companion. The wrong choice patronizes or abandons the reader. + +### 4. Sensory Ambition + +How much is the work asking of the reader emotionally? + +**Positions:** + +- **Functional.** Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity. Most utility tools live here. +- **Considered.** Reader notices the craft. Aesthetic choices are visible without being the point. Most premium brands live here. +- **Resonant.** Reader feels something specific the brand architected. Aesthetics carry meaning. Hardest to produce. Most editorial and narrative brands aspire here. + +**How to choose:** What does the audience deserve from this experience? Functional respects time. Resonant respects feeling. The wrong choice either wastes attention or fails to deliver utility. + +--- + +## Workflow + +1. **Gather inputs.** Project name, description, audience, goal, references. +2. **Walk through each axis as a question.** One axis at a time. For each, present the positions, surface tradeoffs, and capture the user's selection plus reasoning. +3. **Capture inspiration references.** For each provided reference URL, ask what specifically resonates. The answer often clarifies which axis position fits better than abstract description does. +4. **Surface tensions.** Some combinations are difficult to execute well. Functional + Provocative is rare since provocation usually requires emotional engagement that pure functional work resists. Authority + Functional often slides into preachy without warming up at least slightly. Flag tensions and ask the user to confirm or reconsider. +5. **Synthesize.** Write a one-paragraph synthesis describing what this combination produces in practice. +6. **Output the brief.** Markdown format using the structure in [`references/brief-template.md`](references/brief-template.md). The brief becomes a project artifact (typically saved as `BRIEF.md` at the project root). +7. **Hand off.** Reference the brief in any downstream skill that produces aesthetic output. Required reading before `landing-page-copy`, `art-direction`, `content-and-copy`, `brand-style-guide`, or any other skill where coherence matters. + +--- + +## Failure patterns + +- **Using this to develop taste.** This skill codifies intent. It does not produce judgment. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. +- **Skipping inspiration references.** The references calibrate what the axis positions mean in practice. A user picking "Editorial Restrained" without examples often means something different than what an art director means by it. +- **Treating positions as absolute.** A project at "Conversational" still has moments of authority and play. Position is the gravitational center, not a fence. +- **Brief drift mid-project.** The most common failure. The brief gets written, then ignored. Discipline: every downstream skill checks the brief before producing output. If a skill wants to violate the brief, the violation is a decision the user makes consciously, not an accident. +- **Picking incompatible combinations without flagging.** Functional + Provocative is technically valid but very hard. The skill should surface that the combination is rare and ask the user to confirm. +- **Producing a brief no one references.** A brief that does not change downstream output is decoration. The test of a good brief is whether the output would be different if a different brief were used. + +--- + +## Output format + +Default output is a markdown brief, typically saved as `BRIEF.md` at the project root. + +Structure: + +1. **Project header.** Name, one-paragraph description, target audience, business goal. +2. **The four axis selections.** Each axis with the position selected and a one-sentence rationale. +3. **Synthesis paragraph.** What this combination produces in practice. Written in present tense, not aspirational ("This brief produces work that..." not "This brief will help us..."). +4. **Inspiration references.** The provided URLs with notes on what specifically each one demonstrates. +5. **Rejection list.** What this brief explicitly says no to. Often the most useful section. Examples: "No testimonial walls. No stock photography. No exclamation marks." +6. **Open questions.** Anything still unresolved that downstream skills will need to know. + +The brief is reference material for the project's life, not a one-time deliverable. Update it when the project's direction genuinely changes. Resist the urge to update it when execution is hard; usually that means execute harder, not loosen the brief. + +--- + +## Reference files + +- [`references/axes-explained.md`](references/axes-explained.md) - The four axes in depth, with positions, signals, and short brand examples per position to calibrate the user's eye. +- [`references/brief-template.md`](references/brief-template.md) - Blank template for the brief output. +- [`references/example-aesthetic-brief.md`](references/example-aesthetic-brief.md) - A fully completed brief from a representative project, showing how the abstract axes translate into concrete creative direction. diff --git a/dist/pi/.agents/skills/creative-direction/references/axes-explained.md b/dist/pi/.agents/skills/creative-direction/references/axes-explained.md new file mode 100644 index 0000000..b49c833 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/axes-explained.md @@ -0,0 +1,235 @@ +# The Four Axes Explained + +Each axis is a spectrum. Pick a position knowing it excludes adjacent positions for this project. Reference brands are illustrative, not prescriptive. + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## Axis 1: Tone Register + +How formal is the language? How much heat does it carry? + +### Professional + +Measured, precise, low-register. Trusts the reader to do the work of meaning. Restraint is the signal. + +**What this signals:** Seriousness, expertise, established status. The brand does not need to perform to be taken seriously. + +**Reference examples:** Stripe's documentation. The Economist. McKinsey's published thinking. Bloomberg's editorial style. + +**When to pick this:** The audience is making high-stakes decisions and needs to feel they are dealing with peers, not pitchpeople. Or, the category is loud and your differentiation is calm. + +**Common failure:** Sliding into stiffness. Professional is not robotic. It is restrained and warm, not cold. + +### Conversational + +Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking, not an institution speaking. + +**What this signals:** Approachability without sacrificing competence. A brand that respects the reader as a person, not a target. + +**Reference examples:** Linear's product copy. Vercel's marketing voice. Notion's onboarding. MailChimp's voice in their early years. + +**When to pick this:** Default for most modern B2B and prosumer brands. The audience appreciates human voice but still needs to trust the brand's competence. + +**Common failure:** Sliding into casual. Conversational is still considered. "Hey friend!" is not conversational, it is performed informality. + +### Playful + +Wit, surprise, willingness to break form for effect. Visible craft in the language itself. + +**What this signals:** Confidence, creative ambition, willingness to risk being misread. The brand is having fun and inviting the reader to as well. + +**Reference examples:** Slack's early voice. Old Spice campaigns. Bumble. Mailchimp at its peak. + +**When to pick this:** The audience expects beige and wants color. The category is mature and differentiation through craft is available. The brand has the cultural permission to be funny without it reading as forced. + +**Common failure:** Forcing humor that does not earn its place. Playful only works when it is actually funny. Otherwise it reads as desperate. + +### Provocative + +Pointed, opinionated, willing to take a position other brands will not. Says what others soften. + +**What this signals:** Conviction. The brand stands for something specific and is willing to lose the audience that disagrees in order to bond more deeply with the audience that agrees. + +**Reference examples:** Patagonia's political voice. Liquid Death's entire premise. Oatly's category-baiting copy. The early Apple "Think Different" era. + +**When to pick this:** Strong opinion exists and hiding it is more expensive than expressing it. The brand can defend the position over the long term, not just at launch. + +**Common failure:** Performing provocation without conviction. Audiences detect this in seconds. Either the position is real or the voice fails. + +--- + +## Axis 2: Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +### Editorial Restrained + +Generous white space, single definitive image instead of grids, considered typography, low color count, deliberate slowness. + +**What this signals:** Confidence and patience. The brand is willing to under-fill space because it trusts the reader to fill it with attention. + +**Reference examples:** Aesop's website. Apple's product pages in their classic era. Jacquemus. Phaidon's editorial work. Most luxury fashion houses. + +**When to pick this:** The audience is fatigued by visual noise. The brand is premium or aspirational. The product or work itself benefits from being viewed slowly. + +**Common failure:** Restraint that reads as absence. Restraint earns its place when every remaining element is exquisite. Strip too much and the page reads as unfinished. + +### Polished Standard + +Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions, conventional component patterns. + +**What this signals:** Competence, professionalism, current. The brand belongs in its category without standing out. + +**Reference examples:** Most modern B2B SaaS sites. Stripe's marketing pages. Linear. Notion's marketing. Vercel. + +**When to pick this:** The audience expects the category's visual conventions and the brand's differentiation is in the product, not the wrapper. Default for most B2B work. + +**Common failure:** Producing work indistinguishable from competitors. Polished Standard is safe. Safe is forgettable. + +### Controlled Maximalist + +High visual density where every element is intentional. Loud, but engineered. The page is full because each thing earns its place. + +**What this signals:** Craft and conviction. The brand has thought about every pixel and chose density on purpose. + +**Reference examples:** BUCK's portfolio site. Ueno's work. Pentagram's case study pages. Many top-tier creative agency sites. Some Nike campaign work. + +**When to pick this:** The audience expects boring and the brand wants to demonstrate creative ambition. Differentiation through visible craft is available. The team has the design capacity to execute it. + +**Common failure:** Density without intent. Controlled Maximalist requires every element to defend its existence. Lazy density reads as cluttered, not crafted. + +### Expressive Maximalist + +Visual abundance, willingness to be loud, willing to clash. Energy over restraint. + +**What this signals:** Energy, ambition, irreverence. The brand is having a moment and the work is the moment. + +**Reference examples:** Adult Swim. Cards Against Humanity. Some Heinz creative work. Liquid Death's loudest moments. Music festival branding. + +**When to pick this:** The audience is energetic and seeks brands that match. Cultural permission for loudness is high in the category. The brand can sustain the energy over time. + +**Common failure:** This is the hardest position to execute well. Expressive Maximalism that lacks craft reads as chaotic, not exciting. Most attempts fail. + +--- + +## Axis 3: Audience Relationship + +How does the brand position itself relative to the reader? + +### Authority + +We tell you what is true. Expertise on display. Hierarchy implicit and accepted. + +**What this signals:** Earned expertise. The reader came here to learn from someone who knows more than they do. + +**Reference examples:** Bloomberg. McKinsey's published frameworks. Bain's reports. The Economist. Some of Apple's product copy. + +**When to pick this:** The audience explicitly came for expertise. The brand has the credibility to back the position. The category rewards authoritative voice. + +**Common failure:** Authority without earned credibility reads as arrogance. The brand needs to actually know more than the reader. + +### Peer + +We are figuring this out together. Equal footing, shared vocabulary. + +**What this signals:** Mutual respect. The reader is treated as a co-thinker, not a learner. + +**Reference examples:** Linear. Most developer-focused brands. GitHub. Some of Notion's voice. Most modern B2B SaaS. + +**When to pick this:** The audience is sophisticated and reacts badly to being talked down to. The work is genuinely collaborative and acknowledging the reader's expertise serves the relationship. + +**Common failure:** False peering. If the brand actually does know more, hiding that to seem peer-like reads as condescending. + +### Companion + +We walk with you. Lower hierarchy than authority, more presence than peer. + +**What this signals:** Sustained accompaniment. The brand is here for the long arc, not just the transaction. + +**Reference examples:** Headspace. Calm. Stitch Fix. Some healthcare brands. Anthropic's voice in some moments. + +**When to pick this:** The audience is going through something difficult, ongoing, or uncertain. They need presence more than expertise. The relationship is about being with them, not directing them. + +**Common failure:** Companion without substance reads as performative warmth. The brand needs to actually do something useful to earn the relationship. + +### Coach + +We challenge you. The brand pushes the reader toward something they would not push themselves toward alone. + +**What this signals:** Productive friction. The brand assumes the reader wants growth and is willing to be pushed. + +**Reference examples:** Strava. Whoop. Crossfit's brand voice. Apple Fitness+. Some founder-focused programs. + +**When to pick this:** The audience explicitly wants to be challenged. The brand has the credibility to push without being dismissed. The product or service requires effort that the brand is asking of the reader. + +**Common failure:** Coaching without permission. The brand needs to be invited into that role. Pushing readers who did not ask to be pushed reads as preachy. + +--- + +## Axis 4: Sensory Ambition + +How much is the work asking of the reader emotionally? + +### Functional + +Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity, not feeling. + +**What this signals:** Respect for time. The brand assumes the reader has somewhere else to be. + +**Reference examples:** Wikipedia. Craigslist. Most documentation sites. Government services that work well. IRS forms when they are well-designed. + +**When to pick this:** The reader is in transactional mode. The work's value is utility, not feeling. Asking for emotional engagement would be presumptuous. + +**Common failure:** Confusing functional with bare. Functional work is still well-designed. It is just designed for clarity over resonance. + +### Considered + +Reader notices the craft. Aesthetic choices are visible without being the point. + +**What this signals:** Attention to detail without flexing it. The brand cares, and the reader can tell. + +**Reference examples:** Apple's product pages. Notion's marketing. Linear's interface. Aesop's product photography. Most premium SaaS. + +**When to pick this:** The audience appreciates craft when they encounter it but does not require an emotional payoff. The work needs to feel premium without demanding emotion. + +**Common failure:** Considered work that drifts toward decorative. If the craft is visible without earning its place, it reads as fussy. + +### Resonant + +Reader feels something specific the brand architected. Aesthetics carry meaning. The work is asking the reader to feel. + +**What this signals:** Ambition. The brand is trying to do more than communicate. It is trying to move. + +**Reference examples:** Hermes. Patagonia at their narrative best. Some Apple campaigns ("Think Different," "Shot on iPhone"). Aesop's editorial work. Most editorial publications. + +**When to pick this:** The audience came for feeling, not utility. The brand has the craft to deliver it. The work is significant enough to warrant the emotional ask. + +**Common failure:** This is the hardest position. Resonance that is forced reads as manipulation. Resonance that is mistargeted reads as melodrama. Resonance that is vague reads as pretentious. Most attempts fail. + +--- + +## Combinations to flag + +Some combinations are common, some are rare-but-doable, some are contradictory. + +**Common combinations:** + +- Conversational / Polished Standard / Peer / Considered = the modern B2B SaaS default +- Professional / Editorial Restrained / Authority / Considered = premium consultancy default +- Conversational / Polished Standard / Companion / Considered = wellness or healthcare default + +**Rare but powerful:** + +- Provocative / Editorial Restrained / Coach / Resonant = the "Patagonia at full conviction" register +- Conversational / Controlled Maximalist / Peer / Resonant = the "top creative agency" register +- Provocative / Controlled Maximalist / Coach / Resonant = the "high-stakes brand revival" register + +**Difficult combinations to flag:** + +- Functional + Provocative = rare. Provocation usually requires emotional engagement that pure functional work resists. +- Editorial Restrained + Expressive Maximalist = unreachable by selection. These are both positions on Axis 2 (Aesthetic Philosophy), so the user picks one or the other, not both. +- Authority + Functional = possible but flat. Often slides into "we are right and you should know that," which is hard to hold without warming up at least slightly. + +When the user picks a difficult combination, surface the difficulty. Ask them to confirm or reconsider. Sometimes the difficulty is the point. diff --git a/dist/pi/.agents/skills/creative-direction/references/brief-template.md b/dist/pi/.agents/skills/creative-direction/references/brief-template.md new file mode 100644 index 0000000..ffdd108 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/brief-template.md @@ -0,0 +1,74 @@ +# Brief Template + +Save this as `BRIEF.md` at the project root. Update when direction genuinely changes; otherwise hold the line. + +--- + +# [Project Name] Brief + +## Project + +**Name:** [Project name] + +**Description:** [One paragraph describing what the project is, what it produces, who it serves.] + +**Target audience:** [Rough description. A full audience profile from `brand-discovery` is a separate document.] + +**Business goal:** [What changes if this project works. The actual outcome that defines success.] + +--- + +## The four axes + +### Tone Register: [Position] + +[One sentence rationale for why this position fits this audience and goal.] + +### Aesthetic Philosophy: [Position] + +[One sentence rationale.] + +### Audience Relationship: [Position] + +[One sentence rationale.] + +### Sensory Ambition: [Position] + +[One sentence rationale.] + +--- + +## Synthesis + +[One to two paragraphs describing what this combination produces in practice. Written in present tense. "This brief produces work that..." not "This brief will help us...". Concrete enough that downstream skills can check their output against it.] + +--- + +## Inspiration references + +[For each reference URL or brand the user provided, document what specifically resonates and which axis it informs.] + +- **[Reference 1]** - [What this demonstrates and which axis it calibrates.] +- **[Reference 2]** - [What this demonstrates and which axis it calibrates.] +- **[Reference 3]** - [What this demonstrates and which axis it calibrates.] + +--- + +## Rejection list + +This brief explicitly says no to: + +- [Specific decision the brief rejects, e.g. "No testimonial walls."] +- [Another specific decision, e.g. "No stock photography of people."] +- [Another, e.g. "No exclamation marks in body copy."] + +The rejection list is often the most useful section. The choices a brief excludes are as important as the choices it commits to. + +--- + +## Open questions + +[Anything still unresolved that downstream skills will need to know. Better to surface uncertainty than to leave it implicit.] + +- [Question 1] +- [Question 2] diff --git a/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md b/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md new file mode 100644 index 0000000..6e52131 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md @@ -0,0 +1,83 @@ +# Example Aesthetic Brief + +A representative completed brief, modeled on a realistic project. Showing how the abstract axes translate into concrete creative direction. + +> The brief below is a worked example for "Conversational + Editorial Restrained + Peer + Considered" applied to a developer-tool marketing site. Compare it against any rendered marketing site that hits these axis positions to see how the abstract axes translate into concrete decisions: copy register, typographic restraint, image treatment, page density, and rejection list. + +--- + +# Observatory Marketing Site Brief + +## Project + +**Name:** Observatory marketing site redesign + +**Description:** Rebuild the marketing site for an open-source observability tool aimed at senior infrastructure engineers. The current site reads like every other developer SaaS site (gradient hero, "trusted by" logo wall, three-column feature grid, code snippet, testimonials, signup CTA). The new site needs to feel like the team behind it actually understands the problem space, not like a marketing team built a site about a tool they have not used. + +**Target audience:** Senior platform engineers, infrastructure leads, and SRE managers at companies with 50 to 500 engineers. They evaluate observability tools for their team. They are skeptical of marketing claims and value technical depth. They will read documentation before they evaluate the product. + +**Business goal:** Increase qualified evaluation requests from engineering decision-makers, where "qualified" means the requester has authority to influence vendor selection and is in active evaluation. Volume of low-intent signups is not the goal. Quality and intent are. + +--- + +## The four axes + +### Tone Register: Conversational + +The audience is fatigued by both stiff vendor copy ("enterprise-grade reliability") and aggressive performance copy ("10x your observability"). Conversational treats the reader as a peer engineer who can read between the lines. + +### Aesthetic Philosophy: Editorial Restrained + +The category is visually loud. Dashboards, gradient heroes, neon accents, animated charts. The differentiation is opposite: low color count, generous white space, considered typography, single definitive image instead of dashboard screenshots above the fold. The site reads like documentation that decided to be a marketing site, not the other way around. + +### Audience Relationship: Peer + +These engineers do not need to be educated on observability. They need to be respected as practitioners. Authority voice would be condescending. Companion voice would be saccharine. Peer voice acknowledges that we and they are figuring out the same hard problems. + +### Sensory Ambition: Considered + +Functional would underdeliver; the audience expects a marketing site to be more than a feature list. Resonant is too much; this is not a brand campaign, it is a tool evaluation. Considered means the craft is visible (typography, restraint, the right photograph in the right place) without the site asking for an emotional response. + +--- + +## Synthesis + +This brief produces a marketing site that reads like a thoughtful engineering blog post the team happened to design well. Body copy is in first-person plural, contractions are fine, and technical terms appear without quotation marks (the audience uses them naturally, the site should too). Visual density is intentionally low, with a single hero image instead of a product screenshot grid, and pages that breathe rather than fill. There is no logo wall above the fold. There are no testimonials styled as ad copy. The product makes its case through clear documentation links, an honest comparison page, and a "how this differs from what you are already using" section that is willing to say what the tool is not for. + +The site refuses several conventions of the category. No animated dashboard hero. No "trusted by" logos as the second module. No three-column feature grid with checkmarks. No popup. No newsletter modal. The site assumes the reader will find the product if it is genuinely useful, and that the marketing's job is to be clear, not to be loud. + +--- + +## Inspiration references + +- **Linear's marketing site (linear.app)** - Demonstrates Conversational + Polished Standard + Peer well. The Observatory site borrows the calm density and the willingness to write in first person, but pushes further toward Editorial Restrained on the aesthetic axis. +- **Vercel's marketing pages** - Useful for how they handle technical depth without overwhelming. The product surfaces in code, not in dashboard mockups. +- **Stripe's documentation** - The reference for how documentation can be a marketing asset. Observatory's marketing site borrows the sense that good docs are a brand decision, not just a product decision. +- **The Economist's editorial design** - Aesthetic reference for restraint, considered typography, and the use of a single editorial photograph as a hero treatment instead of a dashboard screenshot. + +--- + +## Rejection list + +This brief explicitly says no to: + +- No "trusted by" logo wall, especially above the fold +- No gradient hero. Solid color or a single restrained photograph instead +- No three-column feature grid with checkmark icons +- No product dashboard mockup as the hero image +- No animated chart components scattered through the page +- No exit-intent modal, newsletter popup, or any popup of any kind +- No testimonials with headshots arranged in a grid +- No marketing-speak: "enterprise-grade," "blazing fast," "world-class," "industry-leading" +- No "AI-powered" framing. The product uses ML; that is not the lead +- No corporate stock photography of people in offices +- No vague "join the future" CTAs. Specific verbs only + +--- + +## Open questions + +- The comparison page is committed to but the comparators are not yet selected. Decision needed before `landing-page-copy` runs on that page. +- The hero image needs custom photography or commissioned illustration. Considered Restrained does not support stock. Budget question for the team. +- The pricing page is not yet scoped. Brief should be confirmed before that page is built; pricing pages have their own conventions. +- Author bylines are part of the documentation but not the marketing site yet. Worth deciding whether marketing pieces carry author attribution. diff --git a/dist/pi/.agents/skills/cro-optimization/SKILL.md b/dist/pi/.agents/skills/cro-optimization/SKILL.md new file mode 100644 index 0000000..d1ea82f --- /dev/null +++ b/dist/pi/.agents/skills/cro-optimization/SKILL.md @@ -0,0 +1,271 @@ +--- +name: cro-optimization +description: "Run conversion rate optimization through hypothesis-driven testing including audit, hypothesis generation, test design, statistical analysis, and rollout decisions. Use this skill whenever the user wants to optimize conversion, run A/B tests, audit a funnel, generate test hypotheses, design experiments, or analyze test results. Triggers on conversion optimization, CRO, A/B test, split test, multivariate test, hypothesis, conversion funnel, funnel audit, experiment design, statistical significance, lift, optimization. Also triggers when the user has a conversion problem and isn't sure where to start, or when test results are ambiguous and need interpretation." +category: growth +catalog_summary: "Hypothesis-driven testing, conversion optimization" +display_order: 2 +--- + +# CRO Optimization + +Run conversion rate optimization as a structured discipline: audit → hypothesize → test → decide. Stack-agnostic. Tool-agnostic. + +This skill is for running tests against existing pages and flows. For writing landing page copy from scratch, use `landing-page-copy`. For setting up the analytics that make CRO possible, use `analytics-strategy`. + +--- + +## When to use + +- Converting traffic at lower rate than expected +- Specific funnel step has high drop-off +- Pages with high traffic that could move the needle if optimized +- A/B testing infrastructure exists (or can be set up) +- Statistical significance and sample size questions + +## When NOT to use + +- Without sufficient traffic to test (under ~5,000 monthly conversions per variant) +- Pre-launch (no users to test on yet) +- Strategy or messaging-level questions that need qualitative research first +- Brand-defining choices (CRO can't optimize a fundamentally wrong brand) + +--- + +## Required inputs + +- The page or flow under optimization +- Current conversion rate and traffic volume +- Access to analytics (event tracking, funnel data) +- An A/B testing tool (or willingness to set one up) +- Time and budget for testing (typically 2 to 8 weeks per test) + +--- + +## The framework: 4 phases + +### 1. Audit + +Diagnose before treating. + +**Quantitative audit:** + +- **Funnel data.** Where are users dropping off? The biggest drop is the biggest opportunity. +- **Segmentation.** Does the funnel perform differently by source, device, geography, audience type? +- **Performance data.** Are slow pages dragging conversions? +- **Search Console / on-site search.** What are users looking for that they can't find? + +**Qualitative audit:** + +- **Session replay.** Watch 20+ sessions of users on the target flow. Note friction, confusion, hesitation. +- **Heatmaps.** Where do users click? Where do they scroll? Where do they not? +- **User interviews / surveys.** Why did users not convert? Survey people who started but abandoned. +- **Form analytics.** Which fields cause abandonment? Which cause errors? +- **Customer support tickets.** What conversion-related questions come in? + +**Heuristic audit:** + +- Apply CRO heuristics to the flow: + - Is the value proposition clear in 5 seconds? + - Is there a single primary CTA per page? + - Is the form length appropriate to the offer? + - Is the trust/social proof present? + - Are objections handled? + - Is the page accessible? (Accessibility issues hurt conversion silently.) + +The audit produces a list of suspected friction points. Each becomes a hypothesis candidate. + +### 2. Hypothesis + +A testable statement. + +**Hypothesis structure:** + +> Because [observation from audit], we believe that [change] will produce [predicted outcome] for [user segment], because [reason]. + +**Example:** + +> Because session replays show users abandoning at the shipping step (audit), we believe that adding visible shipping cost to the product page (change) will increase add-to-cart conversion by 5 percent (outcome) for desktop users (segment), because users are surprised by shipping cost and abandon (reason). + +**Hypothesis quality criteria:** + +- Specific change (not "improve the design") +- Measurable outcome (with a target) +- Grounded in evidence (audit, research, prior tests) +- Tied to a known mechanism (why would this work?) + +**Hypothesis prioritization (ICE or PIE):** + +- **Impact:** How much could this move the metric? +- **Confidence:** How likely is the hypothesis to be right? +- **Ease:** How easy to test? (Time, complexity, risk) + +Score each 1 to 10. Highest combined scores test first. + +### 3. Test design + +A test that produces an unambiguous answer. + +**Sample size and duration:** + +Use a sample size calculator (most A/B tools have one) before launching. Inputs: + +- Baseline conversion rate +- Minimum detectable effect (the smallest lift you'd care about) +- Statistical power (typically 80%) +- Significance level (typically 95%) + +This produces required sample size per variant. Run the test until that sample is reached, OR for a minimum duration that captures full business cycle (typically 2 weeks minimum, to cover weekends and weekly patterns). + +**Common test setup mistakes:** + +- Stopping the test the moment significance is hit (peeking) +- Running tests for too short to capture a full business cycle +- Running multiple overlapping tests on the same flow +- Testing during atypical periods (Black Friday, holidays, major campaigns) +- Excluding mobile when 50%+ of traffic is mobile (or vice versa) +- Testing on too small a slice of traffic (low statistical power) +- Not segmenting analysis (overall lift can hide negative impact on a segment) + +**Test parameters to define before launch:** + +- Primary metric (one) +- Guardrail metrics (do not go down) +- Sample size +- Duration (minimum and maximum) +- Decision criteria (when to ship, when to kill, when to extend) +- Segments to analyze in addition to overall + +### 4. Decide + +After the test concludes. + +**Decision framework:** + +| Outcome | Decision | +|---|---| +| Variant clearly wins (>95% significance, exceeds minimum effect) | Ship variant. Document. Continue testing. | +| Variant clearly loses | Kill. Capture the lesson. Iterate hypothesis. | +| Inconclusive (neither significant) | Larger test, different angle, or move on. Don't ship "tied" variants. | +| Small lift, lots of variance | Probably not worth shipping. Even if "winner," may not replicate. | +| Wins overall, loses for important segment | Investigate segment. Consider segment-specific solution. | + +**Anti-patterns:** + +- "It looks like it's winning, ship it" before reaching significance +- Shipping a variant because the team wants to (HiPPO - highest paid person's opinion) +- Killing tests too early because they look bad +- Re-running tests until they "win" (false positive risk) +- Not capturing the learning when a test loses + +--- + +## Statistical foundations + +### Significance and confidence + +A 95% significance level means: if there were truly no difference between variants, there's only a 5% chance you'd see results this extreme by chance. + +That's not the same as "95% chance the variant wins." + +Most CRO tools report Bayesian probabilities ("95% chance of being best"). Read the methodology your tool uses. + +### Sample size + +Conversion testing needs more sample than people intuit. Quick reference: + +| Baseline rate | Minimum detectable effect | Sample per variant | +|---|---|---| +| 2% | 10% relative lift | ~75,000 | +| 2% | 20% relative lift | ~19,000 | +| 5% | 10% relative lift | ~30,000 | +| 5% | 20% relative lift | ~7,500 | +| 10% | 10% relative lift | ~14,000 | +| 10% | 20% relative lift | ~3,500 | + +(Approximate. Use a calculator.) + +If your monthly conversions per variant don't reach these numbers, A/B testing won't produce reliable results. Iterate via design and qualitative research instead. + +### Multiple testing + +The more variants and metrics tested simultaneously, the more false positives. Adjust significance thresholds for multiple comparisons (Bonferroni or similar). + +--- + +## Workflow + +1. **Audit.** Quantitative + qualitative + heuristic. +2. **Generate hypotheses.** From audit findings. Apply hypothesis structure. +3. **Prioritize.** ICE or PIE. Top 3 to 5 to test next. +4. **Design the test.** Sample size, duration, primary and guardrail metrics, decision criteria. +5. **Implement.** Build variants. QA carefully (broken variants invalidate tests). +6. **Run.** Don't peek. Don't stop early. +7. **Analyze.** Overall and by segment. Note interesting patterns regardless of significance. +8. **Decide.** Ship, kill, or extend. +9. **Document.** Hypothesis, design, results, decision, lesson. +10. **Compound.** Apply lessons to next round of hypotheses. + +--- + +## Failure patterns + +- **Testing without audit.** Random changes, random results. +- **Vague hypotheses.** "Make it better" is not a hypothesis. +- **Peeking and early stopping.** Bias toward false positives. +- **Underpowered tests.** Not enough sample for a real conclusion. +- **HiPPO override.** Highest paid person's opinion overrides the data. +- **Testing during atypical periods.** Holidays distort results. +- **Single metric obsession.** Conversion ups but average order value craters. Net loss. +- **No guardrail metrics.** Testing for one outcome, missing damage to others. +- **Documentation gap.** Wins captured, losses forgotten. Same hypothesis re-tested 3 times. +- **Treating each test in isolation.** Compounding learning across tests is where CRO programs really win. + +--- + +## Output format + +Default output: a markdown test plan at `cro-test-[hypothesis-slug].md` per test. After the test runs, append the results section. + +Structure: + +```markdown +# Test: [Hypothesis short name] + +## Hypothesis +Because [observation], we believe that [change] will produce [outcome] for [segment], because [reason]. + +## Audit evidence +[What evidence supports this hypothesis] + +## Test design +- Primary metric: +- Guardrail metrics: +- Sample size required: +- Duration: minimum X, maximum Y +- Variant traffic split: +- Segments to analyze: + +## Decision criteria +- Ship if: [conditions] +- Kill if: [conditions] +- Extend if: [conditions] + +## Results (filled after test) +- Sample reached: +- Duration actual: +- Primary metric: [variant vs control + significance] +- Guardrail metrics: [results] +- Segment analysis: [findings] + +## Decision +[Ship / Kill / Extend / Iterate] - [Why] + +## Lesson +[What this teaches us, regardless of outcome] +``` + +--- + +## Reference files + +- [`references/hypothesis-library.md`](references/hypothesis-library.md) - Common high-impact hypothesis patterns by funnel stage. diff --git a/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md b/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md new file mode 100644 index 0000000..89fbae6 --- /dev/null +++ b/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md @@ -0,0 +1,313 @@ +# Hypothesis Library + +Common high-impact CRO hypothesis patterns by funnel stage. Use as starting points; adapt to the specific product and audience. Each pattern includes the typical evidence that supports it and the typical mechanism behind why it works. + +--- + +## Top of funnel: hero and value proposition + +### H1: Outcome-led headline beats feature-led + +**Hypothesis:** Replacing a feature-led headline ("Advanced workflow automation") with an outcome-led headline ("Ship 30% faster") will increase scroll-past-hero rate and CTA clicks. + +**Evidence to look for:** +- Session replays show users bouncing within 3 seconds +- Heatmaps show low engagement below the hero +- The current headline names a feature, not a benefit + +**Mechanism:** Users grant 3 to 5 seconds to decide whether to continue. Outcome language is processed faster than feature language. + +**Test design:** Hero-only swap. Control vs variant. Primary metric: scroll past hero + CTA click. + +--- + +### H2: Specific number beats vague claim + +**Hypothesis:** Replacing "Save time on month-end close" with "Close in 3 days, not 2 weeks" will increase signup rate. + +**Mechanism:** Specific numbers are more credible and more memorable than vague claims. + +--- + +### H3: Customer-facing ID over jargon + +**Hypothesis:** Replacing internal/industry jargon ("ETL pipeline orchestration") with customer language ("Move data between your tools without engineering") will improve hero engagement. + +**Mechanism:** Industry insiders use jargon. Most prospects are not industry insiders. + +--- + +### H4: Real customer photo beats stock + +**Hypothesis:** Replacing stock-photo hero imagery with photos of actual customers using the product will increase signup rate. + +**Mechanism:** Stock photos are pattern-recognized as marketing fluff. Real customer photos signal authenticity. + +--- + +## Mid-funnel: feature blocks and social proof + +### H5: Specific named customer logos beat unnamed + +**Hypothesis:** Replacing "Trusted by 1,000+ companies" with named logos will improve trust and conversion. + +**Evidence:** Heatmaps show users hovering near social proof but not converting. + +**Mechanism:** Named logos provide verifiable trust. Numbers without names are easily fabricated and users know it. + +--- + +### H6: Specific outcome quote beats generic praise + +**Hypothesis:** Replacing "We love this product!" with "Reduced our onboarding time by 40 percent in three months" will increase trust score and conversion. + +**Mechanism:** Specific outcomes are credible because they're quantifiable. Generic praise is dismissed as cherry-picked. + +--- + +### H7: Founder quote at scale stage + +**Hypothesis:** Adding a founder quote and photo on the homepage will increase early-stage trust signals. + +**Evidence:** Brand is unknown. No major customer logos to display yet. + +**Mechanism:** Personal accountability from a named person beats anonymous brand voice when trust signals are scarce. + +--- + +### H8: Comparison table for competitive categories + +**Hypothesis:** Adding a comparison table against named competitors will increase conversion for prospects in active evaluation. + +**Mechanism:** Users in evaluation mode are comparing anyway. Honest comparison reduces objection-handling work. + +**Risks:** Can backfire if comparison feels biased or if competitors are smaller than you (gives them oxygen). + +--- + +## Form and signup + +### H9: Fewer form fields wins + +**Hypothesis:** Reducing signup fields from 7 to 3 will increase signup conversion. + +**Evidence:** Form analytics show high abandonment, especially on optional fields. + +**Mechanism:** Each form field is friction. Optional fields without value to the user feel like data collection for company benefit. + +--- + +### H10: Progressive profiling beats upfront fields + +**Hypothesis:** Moving non-essential signup fields to a post-signup onboarding flow will increase initial signup conversion without hurting profile completion. + +**Mechanism:** Users commit incrementally. The hardest "yes" is the first one. + +--- + +### H11: Social signup options reduce friction + +**Hypothesis:** Adding "Sign up with Google" alongside email signup will increase signup rate. + +**Risks:** OAuth providers can also reduce signups for users uncomfortable with social login. Test, don't assume. + +--- + +### H12: Visible password requirements reduce errors + +**Hypothesis:** Showing password requirements (8 chars, etc.) above the field instead of as error messages will reduce form errors and abandonment. + +**Mechanism:** Errors after submission feel like punishment. Pre-emptive guidance feels like assistance. + +--- + +### H13: Trust signals near form + +**Hypothesis:** Adding "Free for 14 days. No credit card." adjacent to the CTA will increase form completion. + +**Mechanism:** Reduces perceived risk at the point of commitment. + +--- + +## Pricing page + +### H14: Annotated tiers beat unannotated + +**Hypothesis:** Adding "Best for" labels on each pricing tier ("Best for solo founders," "Best for teams of 10+") will increase plan selection clarity. + +**Mechanism:** Users self-select faster when given decision shortcuts. + +--- + +### H15: Annual emphasis beats monthly default + +**Hypothesis:** Defaulting the pricing toggle to annual (with savings highlighted) will increase annual plan adoption. + +**Mechanism:** Defaults stick. Loss-framed savings ("Save $X") are more compelling than gain-framed. + +--- + +### H16: Clear "what's included" reduces confusion + +**Hypothesis:** Adding a checkmark feature comparison below the pricing tiers will reduce sales-assist requests and improve self-service conversion. + +**Mechanism:** Many prospects abandon when they can't quickly verify a needed feature is in their tier. + +--- + +### H17: Social proof on pricing page + +**Hypothesis:** Adding tier-specific customer testimonials ("Why we picked Team plan") will increase plan upgrade rate. + +**Mechanism:** Tier-specific proof reduces fear of overpaying or under-buying. + +--- + +## Checkout / cart + +### H18: Free shipping threshold visible + +**Hypothesis:** Adding a "$X away from free shipping" message in the cart will increase average order value. + +**Evidence:** Cart abandonment correlated with sub-threshold orders. + +**Mechanism:** Goal gradient. Users near a goal accelerate toward it. + +--- + +### H19: Guest checkout option + +**Hypothesis:** Adding a guest checkout option will increase conversion of first-time buyers. + +**Mechanism:** Account creation is friction at the worst possible moment (when the user has just decided to buy). + +--- + +### H20: Multiple payment methods + +**Hypothesis:** Adding [PayPal / Apple Pay / Google Pay / etc.] at checkout will increase mobile conversion. + +**Mechanism:** Saved payment methods reduce friction. Mobile typing is painful. + +--- + +### H21: Visible total throughout checkout + +**Hypothesis:** Showing the running total persistently in the checkout flow will reduce abandonment. + +**Evidence:** Step-by-step abandonment shows users dropping after seeing fees. + +**Mechanism:** Surprise cost is the #1 cause of cart abandonment. + +--- + +### H22: Trust badges at checkout + +**Hypothesis:** Adding security badges (SSL, PCI, money-back guarantee) at the payment step will increase completion. + +**Mechanism:** Security concerns peak at payment entry. + +--- + +## Onboarding (post-signup) + +### H23: Single first action vs feature tour + +**Hypothesis:** Replacing a feature tour with a single guided first action will increase activation. + +**Mechanism:** Feature tours teach. First actions deliver value. Users who experience value retain better than users who learn features. + +--- + +### H24: Sample data on first login + +**Hypothesis:** Pre-loading the new user's account with sample data will increase first-week retention. + +**Mechanism:** Empty states are demotivating. Pre-populated data shows "what good looks like." + +--- + +### H25: Time-to-value reduction + +**Hypothesis:** Reducing the steps from signup to first valuable action from 12 to 4 will increase activation rate. + +**Evidence:** Funnel analysis shows huge drops in the middle of the onboarding flow. + +**Mechanism:** Each step is a chance to bounce. Fewer steps = more activations. + +--- + +## Email and notifications + +### H26: Subject line specificity + +**Hypothesis:** Replacing "Update from [Brand]" with a specific benefit-led subject ("Your invoice is ready" or "Save 20% this week") will increase open rate. + +**Mechanism:** Inbox is competitive. Specificity earns the open. + +--- + +### H27: Single CTA per email + +**Hypothesis:** Reducing email CTAs from 3 to 1 will increase click-through to primary action. + +**Mechanism:** Choice paralysis. Multiple CTAs dilute the primary action. + +--- + +### H28: Personalization beyond name + +**Hypothesis:** Personalizing email body content based on user behavior (last action, product viewed) will increase reactivation rate. + +**Mechanism:** Generic emails feel like spam. Behaviorally relevant emails feel like service. + +--- + +## Mobile-specific + +### H29: Tap target sizing + +**Hypothesis:** Increasing tap targets to meet 44x44 minimum will reduce mobile bounce rate. + +**Evidence:** Mobile heatmaps show mis-taps and rage clicks. + +**Mechanism:** Small targets fail more often than large ones. + +--- + +### H30: Sticky CTA on mobile + +**Hypothesis:** Adding a sticky bottom CTA on mobile pages will increase conversion. + +**Mechanism:** Long mobile pages bury CTAs. Sticky keeps the action available. + +**Risks:** Can cover content. Test for accessibility issues. + +--- + +### H31: Mobile-specific headlines + +**Hypothesis:** Shortening headlines for mobile viewports (vs desktop) will reduce bounce rate. + +**Mechanism:** Long headlines on mobile become walls of text. Short headlines preserve hierarchy. + +--- + +## Compounding tests + +The biggest CRO wins come from compounding learnings. After running 5 to 10 tests, you should know: + +- What kind of headlines win in your category +- How long your forms should be +- Which trust signals move your audience +- Which features matter to your buyer +- What price framing converts + +These insights compound across tests. Document each test's lesson, even when the test loses. + +A pattern to watch: +- **Test #1:** Outcome-led headline wins +- **Test #5:** Outcome-led email subject wins +- **Test #10:** Outcome-led ad copy wins + +You haven't just run 10 tests. You've discovered that "outcome-led messaging" is your audience's preference, broadly. That insight is worth more than any single test. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md b/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md new file mode 100644 index 0000000..f4a424f --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md @@ -0,0 +1,389 @@ +--- +name: data-warehouse-experimentation +description: "Running experiments out of the data warehouse instead of via dedicated experiment platforms. SQL-based assignment, exposure logging discipline, metric definitions in dbt models, statistical analysis in SQL or Python, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms like Statsig and Optimizely. Triggers on warehouse-native experimentation, run experiments in BigQuery, run experiments in Snowflake, dbt experiments, SQL t-test, CUPED variance reduction, exposure log, sample ratio mismatch, sequential testing, mSPRT, doubly robust estimation, build vs buy experimentation. Also triggers when the team is choosing between platform and warehouse, building warehouse-native experiment infrastructure, auditing one, or running an experiment with a custom metric the platform cannot handle." +category: product +catalog_summary: "Run experiments out of the warehouse: SQL assignment, exposure logs, dbt metric definitions, statistical analysis, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms" +display_order: 9 +--- + +# Data Warehouse Experimentation + +A senior data scientist's playbook for running experiments natively out of BigQuery, Snowflake, or any modern data warehouse, with metric definitions in dbt and statistical analysis in SQL or Python. + +Most companies that run experiments at scale use a dedicated platform. Statsig, Optimizely, LaunchDarkly with experimentation, PostHog, Amplitude Experiment. The platforms are good. They handle assignment, instrumentation, and analysis in one product, and the SQL-savvy data team does not have to reinvent the variance reduction wheel. + +There is a different operational model that mature data teams increasingly choose: warehouse-native experimentation. Assignment happens in code or via feature flags. Exposure events fire to the warehouse like any other event. Metrics are defined as dbt models. Statistical analysis runs as SQL or in a Python notebook against warehouse data. The "experiment platform" is just your existing data stack. + +This skill covers when warehouse-native is the right call, the architecture, and the specific techniques that make it work: assignment patterns, exposure logging discipline, metric definitions in dbt, t-tests and CUPED in SQL, sequential testing, and the pitfalls that take down homegrown setups. + +When to use this skill: deciding between platform vs warehouse-native, building a warehouse-native experiment infrastructure, auditing an existing one, or running a specific experiment when the platform of record cannot handle a custom metric or segmentation. + +--- + +## What this skill is for + +This skill spans the operational execution model for warehouse-native experimentation. It does not replace the methodology and interpretation skills; it composes with them. + +- `experiment-design` covers methodology: hypotheses, sample size, randomization unit, primary metric. Tool-agnostic. Read it first to design the experiment correctly regardless of where it runs. +- `experimentation-analytics` covers interpretation: confidence intervals, p-values, effect size, decision frameworks. Tool-agnostic. Read it when results land. +- `experimentation-platform-orchestrator` covers the platform-vs-warehouse decision in detail. Read it to decide whether to use a platform or this skill. +- `feature-flagging` covers assignment infrastructure when not running through a platform. Read it for the flag-management discipline that this skill assumes. +- This skill (`data-warehouse-experimentation`) covers the operational execution: SQL-based assignment, exposure logging, metric definitions in dbt, statistical analysis in SQL or Python, variance reduction, sequential testing. + +The distinction is between "what to do" (the methodology and interpretation skills) and "how to do it without a vendor platform" (this skill). Read this skill after you have decided warehouse-native is the right call. If you are still deciding, start with `experimentation-platform-orchestrator`. + +--- + +## When warehouse-native is the right call + +Six factors push the decision toward warehouse-native. + +1. **Cost at volume.** Platforms charge per MAU or per event. At 10K MAU the platform is cheap; at 1M MAU the bill becomes a real budget item. Warehouse-native runs on infrastructure you already pay for. +2. **Custom metrics.** If your primary metric is a complex business metric (revenue with refund-aware logic, cohort LTV, retention bracket, multi-event composites), platforms can struggle. Warehouse-native expresses any metric you can write in SQL. +3. **Custom segmentation.** Enterprise customers, account-tier crosscuts, complex behavioral segments. Platforms have segmentation features; the depth varies. dbt models compose without limit. +4. **Trust requirements.** Regulated industries (healthcare, finance, government) need full transparency into the math. Warehouse-native gives you every step of the calculation auditable in SQL. +5. **Existing data team strength.** If you have data engineers and data scientists, you have most of the infrastructure. Adding experimentation discipline on top costs less than adopting a new platform. +6. **Iteration on metric definitions.** Platforms ship metric updates on their own cadence. Warehouse-native iterates as fast as your dbt deployments. + +Five factors push toward platform. + +1. **Frontend visual experiments.** Optimizely's bread and butter. Variant code injected via a script tag, with WYSIWYG editing. +2. **Sub-week iteration speed.** Some platforms set up an experiment in 30 minutes; warehouse-native often takes a day or more for the first run of a new metric pattern. +3. **Teams without strong data infrastructure.** If you do not have a warehouse, dbt, and analysts, do not start with warehouse-native. The platform is the right call. +4. **Mobile experimentation.** SDK-based assignment with offline support is the platform's job, not the warehouse's. +5. **Out-of-the-box sequential testing with strict guarantees.** Statsig and Eppo ship mSPRT with calibrated alpha-spending. Building this in-house is real work. + +Detail and a decision tree in [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md). Many mature teams use both; warehouse-native for the hard cases, platform for fast iteration on standard experiments. + +--- + +## The architecture + +Four components, in order of data flow. + +1. **Assignment.** How users get bucketed into variants. Hash function, feature flag, or randomized assignment table. +2. **Exposure logging.** A discrete event fired the first time a user is exposed to the experiment, written to the warehouse like any other event. +3. **Metric definitions.** SQL queries (or dbt models) that compute the primary and secondary metrics from warehouse events. +4. **Analysis.** Statistical computation in SQL or Python that joins exposure to metrics and produces effect estimates with confidence intervals. + +The flow. User visits the product. Assignment determines the bucket (control or treatment). If the user is exposed to the variant (sees the treatment-specific behavior), an exposure event fires to the warehouse. The user takes actions, generating metric events to the same warehouse. At analysis time, exposure joins to metrics on the assignment unit (typically `user_id`); the analysis computes lift and produces a decision. + +The exposure-event pattern is critical. Without it you can compute only an "intent-to-treat" analysis (everyone assigned, regardless of whether they saw the variant). With it you compute the "exposed" analysis on the population that actually experienced the variant. The latter is usually what you want, especially when the variant only affects a subset of the assigned users (e.g., users who reached a specific page). + +--- + +## Assignment patterns + +Three approaches. + +**Deterministic hash assignment.** The default for warehouse-native. + +```sql +MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 +``` + +The salt (`'exp_button_color_v1'`) ensures different experiments produce uncorrelated assignments for the same user. Reproducible (same input always produces the same bucket), no service dependency, salt isolation across experiments. The assignment can be computed inline in any SQL query. + +**Feature flag assignment.** Rely on a feature flag service (LaunchDarkly, Statsig flags, Unleash, internal) to do bucketing; the warehouse just records the assignment that the flag service chose. + +```sql +-- Read assignment from the flag service's logs +SELECT user_id, variant_id, assigned_at +FROM flag_service.assignments +WHERE flag_key = 'exp_button_color_v1' +``` + +This works when the flag service is the source of truth for assignment and the warehouse mirrors the assignment table. Useful when assignment must respect flag-service rules (e.g., percentage rollouts, targeting rules) that are inconvenient to replicate in SQL. + +**Randomized assignment table.** Pre-randomize users into a table at experiment start. + +```sql +CREATE TABLE exp_button_color_v1_assignments AS +SELECT + user_id, + CASE WHEN RAND() < 0.5 THEN 'control' ELSE 'treatment' END AS variant_id +FROM dim_users +WHERE eligible = true; +``` + +Less common; useful when the eligibility set is fixed at experiment start and you want assignment to be deterministic and explicit (e.g., for compliance audit). The downside: new users joining mid-experiment are not in the table; either skip them or fall back to hash assignment. + +The deterministic hash approach is the default for warehouse-native because it requires no service dependency and produces stable, auditable assignments. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## The exposure log + +The single most important discipline in warehouse-native experimentation. + +Required exposure event schema: + +| Field | Type | Notes | +|---|---|---| +| `experiment_id` | string | Unique identifier per experiment. | +| `variant_id` | string | The variant the user was bucketed into. | +| `user_id` | string | The assignment unit. | +| `exposed_at` | timestamp | ISO 8601 UTC. The moment exposure fired. | +| `context_*` | various | Optional context properties: device, page, account_id. | + +Fire exposure exactly when the user has seen the variant-specific behavior. Not at page load. Not at session start. Not at app open. + +The "delayed exposure" trap. If the variant only matters at button click and you fire exposure at page load, every page-load user enters the analysis whether or not they ever saw the variant. The control group includes users who never reached the button; the treatment group does too. The analysis dilutes the real effect. + +Worked example. The treatment shows a new pricing page; the control shows the old one. Fire exposure when the pricing page loads, not when the user lands on the homepage. Users who never reach the pricing page are not exposed to either variant; they should not be in the analysis. + +The "always-fire" trap. Some implementations fire exposure on every variant-specific interaction. The user clicks the button five times; exposure fires five times. The exposure log is now five times larger than it should be, and analysis tools that count distinct user_ids in exposure handle this correctly while tools that count rows do not. + +The discipline. Fire exactly one exposure event per user per experiment, at the moment of first variant-specific exposure. Use a deterministic flag in the client (or a server-side cache) to enforce single-fire. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## Metric definitions in dbt models + +Defining metrics as dbt models gives you four things. + +1. **Version control on metric definitions.** Every change to a metric is a git commit. The history is queryable. +2. **Testability.** dbt tests on the metric output catch regressions. +3. **Composability.** The same `fct_orders` model feeds the board dashboard, the experiment analysis, and the executive report. Aligned definitions, no drift. +4. **Single source of truth.** When the experiment says X and the board says Y, the answer is in the dbt model, not in two unrelated SQL files. + +Pattern. + +```sql +-- models/experiments/exp_metrics_revenue.sql +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + MIN(occurred_at) AS first_purchase_at +FROM {{ ref('fct_orders') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' +GROUP BY user_id +``` + +The experiment analysis joins this to the exposure log on `user_id` and computes group means. + +The variance discipline. The same metric definition is used in board dashboards AND in experiment analysis. No "experiment-specific revenue calculation" that is slightly different. Otherwise you get the "the experiment said the revenue lifted but the board did not move" problem, which is almost always a metric-definition mismatch. + +The namespace pattern. Use `exp_metrics_*` for experiment-shaped models that group by `user_id` and produce one row per user. Use `fct_*` for the underlying fact tables that feed both metric models and dashboards. Detail in [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md). + +--- + +## Statistical analysis in SQL + +The basic two-sample Welch's t-test in SQL. + +```sql +WITH metric_by_variant AS ( + SELECT + e.variant_id, + COUNT(*) AS n, + AVG(m.net_revenue_cents) AS mean, + VAR_SAMP(m.net_revenue_cents) AS variance + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' + GROUP BY e.variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic +FROM + (SELECT * FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment +``` + +Convert the t-statistic to a p-value or confidence interval using a SQL function (BigQuery: a UDF; Snowflake: native or a stored procedure) or compute in Python on the result of the SQL query. + +The SQL pattern is fine for simple t-tests on continuous metrics. For proportions tests, swap variance for `p * (1 - p)`. For non-parametric tests (Mann-Whitney), the SQL gets ugly fast; switch to Python. + +Anything more complex than a simple t-test (CUPED, bootstrap, doubly robust estimation, sequential testing) is easier in Python. Use SQL for the SUM-and-AVG aggregations; ship the result to Python for the statistical math. Detail in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Statistical analysis in Python + +The Python pattern, typically in a Jupyter or Hex notebook. + +```python +import pandas as pd +import numpy as np +from scipy import stats + +# Pull aggregated data from the warehouse +df = warehouse.query(""" + SELECT user_id, variant_id, net_revenue_cents + FROM exp_results + WHERE experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].net_revenue_cents +treatment = df[df.variant_id == 'treatment'].net_revenue_cents + +# Welch's t-test +t, p = stats.ttest_ind(treatment, control, equal_var=False) + +# Confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} cents (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"p-value: {p:.4f}") +``` + +Python gives you access to the full statistical ecosystem (`scipy`, `statsmodels`, `numpy`) for techniques SQL cannot easily express. + +The notebook pattern. One notebook per experiment, parameterized by `experiment_id`. Version-controlled in git or as Hex projects. Each notebook produces a written-up decision document at the end, archived in a queryable repository (Notion, GitHub markdown, or a dedicated experiment-results table in the warehouse). + +Detail and bootstrap templates in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Variance reduction: CUPED and beyond + +The most powerful variance reduction technique for warehouse-native experimentation: **CUPED** (Controlled-experiment Using Pre-Experiment Data). Originally from Microsoft. + +The intuition. If you can predict a user's metric behavior from pre-experiment data, you can subtract out that predicted variance, leaving a smaller residual to test on. + +```python +# Pre-experiment metric for each user (e.g., last 28 days revenue) +pre = pre_period_revenue(user_id) + +# Theta is the regression coefficient of the metric on the pre-period +theta = np.cov(metric, pre)[0, 1] / np.var(pre) + +# Adjusted metric +adjusted_metric = metric - theta * (pre - pre.mean()) +``` + +Run the t-test on the adjusted metric instead of the raw metric. The mean is preserved (CUPED does not change the point estimate) but the variance is smaller, so the confidence interval is narrower. + +CUPED typically reduces variance by 30 to 50 percent on engagement metrics. That is equivalent to running an experiment 1.5x to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +Other variance reduction techniques. + +- **Stratification.** Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. +- **Regression adjustment.** Fit an OLS regression with covariates; the residual analysis has lower variance. Generalizes CUPED to multiple covariates. +- **Doubly robust estimation.** Combines outcome modeling and propensity-score weighting. Useful in observational and quasi-experimental settings where randomization was imperfect. Outside the scope of typical A/B tests; pointer to academic references in the variance-reduction reference file. + +Detail with worked examples in [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md). + +--- + +## Pre-experiment power analysis + +Before running, compute required sample size. + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Solve for sample size given desired MDE +n_per_arm = tt_ind_solve_power( + effect_size=0.05, # Cohen's d + nobs1=None, + alpha=0.05, + power=0.8 +) + +# Or solve for MDE given sample size +mde = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8 +) +``` + +The "we need 10x more users than we thought" lesson. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10% lift; the actual effect is 1%, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. + +The fix. Use the historical distribution of past experiments' observed effects to set realistic MDE expectations. If the median observed effect across the last 30 experiments is 0.5%, plan for a 0.5% MDE on new experiments. The optimism asymmetry is real; correcting it requires looking at the actual distribution of effects, not the wished-for distribution. + +Detail in [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md). + +--- + +## Sequential testing patterns + +The "peeking" problem. Looking at experiment results before completion inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. + +Three approaches. + +- **mSPRT** (mixture Sequential Probability Ratio Test). Used by Optimizely and Statsig. Provides an always-valid p-value that survives peeking. Implementation in Python via `statsmodels` or custom code; not natively in SQL. +- **Always-Valid Inference** with confidence sequences. Howard et al. Confidence intervals that are valid at any sample size. Implementation requires careful Python; not for the data team that has not read the paper. +- **Group sequential designs** (O'Brien-Fleming boundaries). Pre-specified interim analysis points with calibrated alpha-spending. The classic frequentist approach. + +For warehouse-native, the practical recommendation is mSPRT in Python. Document the alpha-spending function used. Train one team member on the math; do not rely on a black-box implementation. + +The honest version. If you do not have someone on the team who understands sequential testing math, just do not peek. Pre-register sample size, run to completion, analyze once. Sequential testing is statistically correct only when implemented correctly; an incorrect implementation is worse than no peeking discipline at all. + +Detail in [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md). + +--- + +## Common pitfalls + +Eleven patterns recur in warehouse-native experimentation. Detail in [`references/common-pitfalls.md`](references/common-pitfalls.md). + +- "Our exposure log fires at page load." Should fire when the variant-specific behavior is shown, not at page load. The "delayed exposure" trap dilutes the effect. +- "We see lift in control, not treatment." Assignment-hash collision or salt reuse. Audit the salt; check that different experiments produce different bucket assignments for the same user. +- "P-value is 0.04, we are shipping." Probably underpowered plus multiple comparisons plus peeking. Compute the test at the planned sample size only; correct for multiple secondary metrics. +- "Experiment shows 30% lift." Almost certainly a bug. Effects that big rarely exist; first action is to audit the exposure log and metric definitions before celebrating. +- "Treatment users are different." Sample ratio mismatch (SRM). The assignment hash is broken or the exposure log is biased. Check the SRM before computing any metric. +- "We cannot reproduce yesterday's number." Non-deterministic queries (window functions without explicit ORDER BY, sampling without a seed) or floating-point issues in aggregations. Make queries deterministic; document the random seed if any. +- "Custom metric definition disagrees with the board metric." Bad. Align them by using the same dbt model. Otherwise nobody trusts either number. +- "We never finished the experiment." Pre-register stop criteria; honor them. Experiments that drift indefinitely waste team time and produce ambiguous decisions. +- "iOS users converted 3x in treatment." Segment effect or instrumentation bug. Check if iOS instrumentation differs from the rest. Beware over-claiming on small segments. +- "It worked on phase 1, broke on phase 2." Simpson's paradox from cohort mix shift. The aggregate trend reverses when the underlying segments are weighted differently across phases. +- "Statistical significance but tiny effect." Large sample inflated power. The p-value is below 0.05 but the effect is 0.3%. Consider practical significance: is 0.3% worth shipping? + +--- + +## The framework: 12 considerations for warehouse-native experimentation + +When designing or running a warehouse-native experiment, walk these 12 considerations. + +1. **Platform vs warehouse decision.** Cost, custom metrics, segmentation, trust, team strength. Read `experimentation-platform-orchestrator` if undecided. +2. **Assignment unit.** User, account, session, device. Pick once at experiment start and stick to it. +3. **Assignment salt.** Unique per experiment to prevent correlation with prior experiments. Document the salt convention. +4. **Exposure logging discipline.** Fire when the variant matters, not at page load. One exposure event per user per experiment. +5. **SRM check.** Sample ratio mismatch indicates assignment bugs. Check before computing any metric. +6. **Metric definition reuse.** Same dbt model for board and experiment. No experiment-specific calculations that drift from canonical metrics. +7. **Pre-experiment power analysis.** Realistic MDE based on the historical distribution of past observed effects. +8. **Variance reduction.** CUPED for engagement metrics. 30 to 50 percent variance reduction is worth the engineering for any team running 5+ experiments per quarter. +9. **Statistical method.** Welch's t-test as default. Bootstrap for skewed distributions. Doubly robust estimation for quasi-experiments. +10. **Sequential testing.** mSPRT or stop-at-N. Document alpha-spending. If you cannot implement correctly, do not peek. +11. **Multiple comparisons.** Bonferroni or Benjamini-Hochberg correction across secondary metrics. +12. **Decision documentation.** Write the result up. Archive in a queryable repository. The next experiment will benefit from the institutional memory. + +The output of the framework is an experiment record. Pre-registered sample size and stop criteria, the assignment salt, the exposure log specification, the dbt metric model, the analysis notebook, and a written-up decision. The record lives in version control or in a dedicated experiment-tracking system; the analysis is reproducible from the record. + +--- + +## Reference files + +- [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md) - When each operational model is the right call. Cost considerations at different scales. Hybrid patterns. Migration patterns. +- [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md) - Hash assignment SQL templates for BigQuery and Snowflake. Salt naming conventions. Exposure event schema. SRM check SQL. +- [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md) - dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. +- [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md) - SQL and Python templates for Welch's t-test, proportions test, Mann-Whitney, bootstrap. Notebook structure. +- [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md) - CUPED math and Python implementation with worked example. Stratification. Regression adjustment. Doubly robust estimation primer. +- [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md) - MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. +- [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md) - mSPRT, confidence sequences, group sequential designs. Honest framing on when to peek. +- [`references/common-pitfalls.md`](references/common-pitfalls.md) - Eleven failure patterns with diagnoses and fixes. + +--- + +## Closing: the build-vs-buy decision is real + +Warehouse-native experimentation is powerful but expensive in engineering time. A first-year experimentation team should almost always start with a platform; the platform handles 90 percent of cases and lets you focus on hypotheses, not infrastructure. The team that graduates to warehouse-native does so because their volume, custom metric needs, or trust requirements outgrew what platforms offer. + +If you are building warehouse-native because "platforms cost too much" without first running the math: you are underestimating the cost of your team's engineering time. The platform fee that looks expensive on a procurement form is often cheaper than three months of a data engineer's time spent reinventing CUPED. + +If you are building it because the platform cannot handle your specific needs: you are probably right and the investment will pay back. Platforms are general; your business is specific. The custom metric the platform cannot express is often the metric that matters most for your decisions. + +Honest middle ground: many mature teams use both. The platform for fast iteration on standard experiments where time-to-result matters more than custom depth. Warehouse-native for the hard cases where the platform's metric library or segmentation cannot reach. The hybrid is operationally complex; document the rule for which experiments go where, and revisit annually. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md new file mode 100644 index 0000000..a043446 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md @@ -0,0 +1,230 @@ +# Assignment and exposure patterns + +Hash assignment SQL templates. Salt naming conventions. Exposure event schema. The delayed-exposure trap. Sample ratio mismatch (SRM) check. + +--- + +## Hash assignment SQL templates + +### BigQuery + +```sql +-- 50/50 split for experiment exp_button_color_v1 +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Snowflake + +```sql +-- 50/50 split using SHA1 hash and modulo +SELECT + user_id, + CASE + WHEN MOD(ABS(HASH(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Postgres + +```sql +-- 50/50 split using md5 hash; convert hex to integer +SELECT + user_id, + CASE + WHEN ('x' || SUBSTRING(MD5(user_id || 'exp_button_color_v1'), 1, 8))::bit(32)::int % 100 < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Three-arm split + +```sql +-- 33/33/34 split (control / variant_a / variant_b) +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 33 + THEN 'control' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 66 + THEN 'variant_a' + ELSE 'variant_b' + END AS variant_id +FROM dim_users; +``` + +### Sub-sampling for opt-in experiments + +```sql +-- 10% of users in the experiment, 50/50 split among them +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_eligibility'))), 100) >= 10 + THEN 'not_in_experiment' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +Note the two different salts: one for eligibility, one for assignment. This ensures the eligibility decision is independent of the variant decision. + +--- + +## Salt naming conventions + +Three rules. + +1. **Unique per experiment.** Reuse the same salt across experiments and you correlate assignments. A user in control of experiment A is more likely to be in control of experiment B; the experiments interfere. +2. **Stable across the experiment lifecycle.** Do not change the salt mid-experiment. Changing the salt re-randomizes existing users; the analysis becomes uninterpretable. +3. **Versioned.** When semantics change, append `_v2`. The old experiment data remains queryable; the new salt produces independent assignments. + +Convention. + +``` +{prefix}_{descriptor}_{version} +``` + +Examples. + +- `exp_button_color_v1` +- `exp_pricing_test_v1` (eligibility salt) +- `exp_pricing_test_assign_v1` (assignment salt within eligible) +- `exp_recommendation_model_v2` (version 2 of an existing experiment) + +Document the salt convention. Add it to the experiment record. + +--- + +## Exposure event schema + +The required fields. + +| Field | Type | Required | Notes | +|---|---|---|---| +| `experiment_id` | string | Required | Unique identifier per experiment. | +| `variant_id` | string | Required | The variant the user was bucketed into. | +| `user_id` | string | Required | The assignment unit. | +| `exposed_at` | timestamp | Required | ISO 8601 UTC. Server-stamped. | +| `assigned_at` | timestamp | Optional | When the user was first assigned (may differ from exposed). | +| `device_type` | string | Optional | mobile, web, desktop. | +| `app_version` | string | Optional | For change-tracking when version-specific bugs surface. | +| `account_id` | string | Optional | For B2B; the account context. | +| `session_id` | string | Optional | For session-level path analysis. | + +The minimum schema is the four required fields. Optional fields support segmentation and debugging. + +### Storage pattern + +Either as a dedicated `experiment_exposures` table or as an event in the main events table with `event_name = 'experiment_exposed'`. + +Dedicated table is cleaner for analysis. Main events table is simpler for instrumentation. Pick one and stick to it. + +--- + +## The delayed-exposure trap + +The single most common warehouse-native experimentation bug. + +**The setup.** The treatment shows a new pricing page; the control shows the old one. The team fires exposure at homepage load. + +**The problem.** Many users land on the homepage but never click through to the pricing page. They are counted as "exposed" to the experiment but never saw the variant. The control group includes users who never reached the pricing page; the treatment group does too. + +**The result.** The analysis dilutes the real effect. The treatment may have produced a 20 percent lift among users who actually saw the pricing page, but the analysis shows a 2 percent lift because 90 percent of "exposed" users never reached the variant. + +**The fix.** Fire exposure exactly when the user has seen the variant-specific behavior. + +```javascript +// Wrong: fires at every page load +function onHomepageLoad(user) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: getVariant(user), + user_id: user.id, + }); +} + +// Right: fires when the pricing page renders the variant-specific UI +function onPricingPageLoad(user) { + const variant = getVariant(user); + if (variant === 'treatment') { + renderNewPricingPage(); + } else { + renderOldPricingPage(); + } + // Fire once per user per experiment + if (!hasExposureFired(user, 'exp_pricing_v1')) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: variant, + user_id: user.id, + }); + markExposureFired(user, 'exp_pricing_v1'); + } +} +``` + +The discipline. Fire exposure when the variant-specific UI renders or the variant-specific code path executes. Use a single-fire flag (client-side cache or server-side state) to ensure exposure fires exactly once per user per experiment. + +--- + +## Sample ratio mismatch (SRM) check + +Before computing any metric, check that the assignment is balanced. + +```sql +-- For a 50/50 split, expect roughly equal counts in control and treatment +SELECT + variant_id, + COUNT(*) AS n, + COUNT(*) * 1.0 / SUM(COUNT(*)) OVER () AS share +FROM exposures +WHERE experiment_id = 'exp_button_color_v1' +GROUP BY variant_id; +``` + +Expected output. + +| variant_id | n | share | +|------------|--------|-------| +| control | 50,123 | 0.501 | +| treatment | 49,877 | 0.499 | + +If the share deviates from the expected 50 percent by more than 1 percentage point at large samples, you have an SRM. The chi-squared test detects this formally. + +```python +from scipy.stats import chi2_contingency + +observed = [50123, 49877] # control, treatment +expected_ratio = [0.5, 0.5] +chi2, p, dof, _ = chi2_contingency([observed, [sum(observed) * r for r in expected_ratio]]) +print(f"SRM chi-squared p-value: {p:.4f}") +# p < 0.001 indicates SRM +``` + +If you have an SRM. Do not analyze the experiment. The assignment is broken (hash collision, biased exposure logging, instrumentation that fires for one variant but not the other). Fix the bug; restart the experiment. + +The honest pattern. Run an SRM check at the top of every experiment analysis notebook. If SRM is detected, abort with a clear error message; do not let the analysis proceed. + +--- + +## Common assignment and exposure mistakes + +- **Salt reuse across experiments.** A user in control of experiment A is correlated with control of experiment B. Use unique salts per experiment. +- **Changing the salt mid-experiment.** Re-randomizes existing users. The analysis becomes a mix of two different assignment functions. Pre-register the salt; freeze it at experiment start. +- **Firing exposure on every event.** Inflates the exposure log by 10 to 100x. Use single-fire enforcement. +- **Server-side fire when only client renders the variant.** Server-side fires for every API call; client-side fires only when the user reaches the variant-specific UI. Match exposure to where the variant matters. +- **Eligibility check in the wrong place.** Eligibility (e.g., paid users only) checked client-side after assignment produces biased exposure (only paid users in the log). Check eligibility before assignment, server-side. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md new file mode 100644 index 0000000..5e96609 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md @@ -0,0 +1,143 @@ +# Common pitfalls + +Eleven failure patterns that recur in warehouse-native experimentation. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Exposure log fires at page load + +**Symptom.** The experiment shows a 1 percent lift; the team expected 10 percent. The lift is real but diluted because most exposed users never saw the variant. + +**Root cause.** Exposure fires at page load (or session start) regardless of whether the user reaches the variant-specific code path. The control group includes users who never saw the variant; the treatment group does too. + +**Fix.** Move exposure firing to the moment the variant-specific UI renders or the variant-specific code path executes. Re-run the experiment with corrected logging. + +**Prevention.** Document the exposure-firing rule in the experiment record. Code review the implementation. Check the exposure-to-metric ratio (if exposure count is much higher than expected metric count, exposure is firing too broadly). + +--- + +## 2. Lift in control, not treatment + +**Symptom.** The control group has a higher mean than the treatment group. The team is confused because the variant-specific changes should have increased the metric. + +**Root cause.** Assignment hash collision or salt reuse with a prior experiment. Users in control of the new experiment are correlated with users in treatment of an old experiment that also affected the metric. + +**Fix.** Audit the salt. Use a unique salt per experiment. Re-run with corrected assignment. + +**Prevention.** Salt naming convention with version suffix. Code review for new experiments. Run a chi-squared test of independence between the new experiment's assignment and recent prior experiments' assignments before launching. + +--- + +## 3. P-value is 0.04, we are shipping + +**Symptom.** The primary metric p-value is 0.04. The team declares victory and ships. Three months later the metric in production has not moved. + +**Root cause.** Some combination of underpowered experiment, multiple comparisons without correction, and peeking. Each of these inflates the false-positive rate; together they make a 0.04 p-value uninformative. + +**Fix.** Re-run with a pre-registered sample size, single primary metric, no peeking. If the lift is real, the second experiment will confirm it. If not, the first result was a false positive. + +**Prevention.** Pre-register the sample size, the primary metric, and the analysis method. Do not peek. Apply Bonferroni or BH correction across secondary metrics. Treat 0.04 with much more skepticism than 0.001. + +--- + +## 4. Experiment shows 30 percent lift + +**Symptom.** The treatment shows a 30 percent lift on the primary metric. The team is excited. + +**Root cause.** Almost certainly a bug. Effects that big rarely exist outside truly novel features. Common bugs: exposure log fires only for treatment users (control is missing); metric model has a join error that double-counts treatment events; assignment is non-random and treatment is over-represented in heavy users. + +**Fix.** Audit the exposure log balance, the assignment ratio, and the metric model. Compare metric values to the historical baseline; if the treatment metric is higher than the all-users historical metric, something is wrong. + +**Prevention.** Skepticism about large effects. Run an SRM check before any analysis. Compare exposed-treatment metric to the historical baseline as a sanity check. + +--- + +## 5. Treatment users are different (sample ratio mismatch) + +**Symptom.** The exposure log shows 52,000 control users and 48,000 treatment users for a planned 50/50 split. The chi-squared test rejects the null at p < 0.001. + +**Root cause.** Assignment is not balanced. Possible causes: hash function bug, biased exposure logging, instrumentation that fires for one variant but not the other, eligibility check that runs differently across variants. + +**Fix.** Do not analyze the experiment. Find and fix the assignment bug. Restart. + +**Prevention.** Run the SRM check at the top of every analysis notebook. Abort with a clear error message if SRM is detected. Code review the exposure logging for both variants. + +--- + +## 6. Cannot reproduce yesterday's number + +**Symptom.** Yesterday's analysis showed 5.2 percent lift; today's shows 4.8 percent. Same query, same data, same notebook. The team cannot tell which is "the" answer. + +**Root cause.** Non-deterministic queries. Window functions without explicit `ORDER BY` produce different results on different runs. Sampling without a seed produces different samples. Floating-point aggregations on large datasets produce slight numeric differences depending on the order of summation. + +**Fix.** Make queries deterministic. Add explicit `ORDER BY` to window functions. Set a seed for any sampling. For floating-point precision, sum integers (cents) instead of floats; convert to dollars only at display time. + +**Prevention.** Code review for non-determinism. Save the query plan or the result set; compare across runs to detect drift early. + +--- + +## 7. Custom metric definition disagrees with board metric + +**Symptom.** The experiment says revenue lifted 5 percent; the board's revenue dashboard shows revenue flat. The team cannot tell which is right. + +**Root cause.** Two different SQL queries computing "revenue" with subtly different rules. The experiment query may include or exclude refunds, internal users, test orders, or specific time windows in different ways than the board. + +**Fix.** Align via shared dbt models. The board's revenue dashboard and the experiment's revenue metric reference the same `fct_orders` model with the same filters. + +**Prevention.** Schema discipline. Every metric used in an experiment is also used somewhere in the board or weekly review. Drift between the two is a code smell that should be caught at code review. + +--- + +## 8. We never finished the experiment + +**Symptom.** The experiment has been running for 8 weeks. The team has looked at the dashboard three times. Each time the result was inconclusive. The team keeps running it hoping for a clear answer. + +**Root cause.** No pre-registered stop criteria. The experiment was launched without a clear "we will stop when X" rule. The team is implicitly peeking and refusing to call it. + +**Fix.** Set a stop date and honor it. Analyze once on the stop date; report the result (which may be inconclusive). Document the inconclusive result and the design improvements needed for the next attempt. + +**Prevention.** Pre-register the sample size, the stop date, and the decision rule. Honor them. + +--- + +## 9. iOS users converted 3x in treatment + +**Symptom.** The aggregate treatment lift is small (1 percent), but the iOS segment shows a 3x lift. The team wants to ship the variant for iOS specifically. + +**Root cause.** Three possibilities. (a) Real segment effect: iOS users genuinely prefer the variant. (b) Instrumentation bug: iOS metric tracking differs from the rest. (c) Multiple comparisons: among many segments, one shows a large effect by chance. + +**Fix.** Investigate. Compare iOS metric tracking to other platforms (is the same event firing the same way?). Check the iOS sample size (if small, the 3x is high variance). Re-run the experiment with iOS as the primary segment if the team genuinely wants iOS-specific results. + +**Prevention.** Pre-register segments of interest. Apply multiple-comparisons correction across segments. Treat unexpected segment effects as hypotheses to confirm in a follow-up experiment, not as ship signals. + +--- + +## 10. Worked on phase 1, broke on phase 2 + +**Symptom.** Phase 1 of a staged rollout showed a clear positive lift. Phase 2 (broader audience) shows a much smaller or negative lift. The team is confused. + +**Root cause.** Simpson's paradox from cohort mix shift. Phase 1's audience is enriched in a segment where the treatment works well; phase 2 includes more of a segment where the treatment works poorly. The aggregate result reverses. + +**Fix.** Decompose by segment. The phase 2 result is the truer estimate (broader audience), but the phase 1 result tells you which segments respond. Consider a segment-specific rollout if the segment-level economics support it. + +**Prevention.** Run the experiment on the full target audience from the start, not on a phase-1 sub-audience. If staged rollout is operationally required, plan for the cohort mix shift in the analysis. + +--- + +## 11. Statistical significance but tiny effect + +**Symptom.** The p-value is 0.001. The lift is 0.3 percent. The experiment is statistically significant but the team is unsure whether to ship. + +**Root cause.** Large sample inflated the test's power. The test detects effects much smaller than the team's practical significance threshold. + +**Fix.** Apply the practical-significance check. If the team's threshold is "ship at 1 percent or larger," 0.3 percent does not meet the bar regardless of the p-value. Document the result; do not ship. + +**Prevention.** Pre-register the practical-significance threshold (the MDE) at experiment design time. Treat statistical significance below the MDE as inconclusive, not as a ship signal. + +--- + +## The pattern across all eleven + +Most warehouse-native experimentation failures share one root cause: the team did not pre-register enough discipline before the experiment started. Pre-registered sample size prevents underpowered analysis. Pre-registered exposure rule prevents the delayed-exposure trap. Pre-registered primary metric prevents multiple-comparisons fishing. Pre-registered stop criteria prevent the experiment-runs-forever pattern. + +The fix at the meta level. Treat each experiment as a contract. Before launching, write down the assignment unit, the salt, the exposure rule, the primary metric, the secondary metrics with multiple-comparisons correction, the sample size, the stop criteria, the practical-significance threshold. The contract is reviewed at launch. Deviations from the contract during the experiment require explicit re-registration. The discipline is the only thing that scales as the team runs more experiments. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md new file mode 100644 index 0000000..7ecfb76 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md @@ -0,0 +1,229 @@ +# Metric definitions in dbt + +dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. Aligning with board metrics. + +The principle. Define experiment metrics as dbt models so they are version-controlled, testable, and aligned with board metrics. The same source of truth for both surfaces eliminates the "experiment said X but the board says Y" problem. + +--- + +## The namespace pattern + +Three layers in a typical dbt project. + +- `stg_*`: staging models. Light cleanup of source data. One per source table. +- `fct_*` and `dim_*`: marts models. Business-logic transformations. Joined and enriched data ready for consumption. +- `exp_metrics_*`: experiment-shaped models. One row per assignment unit (typically `user_id`) with the metrics needed for analysis. + +Example structure. + +``` +models/ + staging/ + stg_orders.sql + stg_users.sql + stg_events.sql + marts/ + fct_orders.sql + fct_sessions.sql + dim_users.sql + experiments/ + exp_metrics_revenue.sql + exp_metrics_engagement.sql + exp_metrics_retention.sql +``` + +The `fct_*` models feed both the board dashboard and the experiment metrics. The `exp_metrics_*` models pivot to one row per user with the metrics joined or aggregated. + +--- + +## Pattern 1: revenue metric + +```sql +-- models/experiments/exp_metrics_revenue.sql +{{ config(materialized='table') }} + +WITH order_data AS ( + SELECT + user_id, + occurred_at, + amount_cents, + refunded + FROM {{ ref('fct_orders') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +) +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + SUM(amount_cents) AS gross_revenue_cents, + COUNT(*) AS order_count, + MIN(occurred_at) AS first_order_at +FROM order_data +GROUP BY user_id; +``` + +Note the `var()` references for experiment start and end dates. The variables come from the dbt project's variables file or are passed at run time. + +The same `fct_orders` model feeds the board's revenue dashboard. Aligned definitions. + +--- + +## Pattern 2: engagement metric + +```sql +-- models/experiments/exp_metrics_engagement.sql +{{ config(materialized='table') }} + +WITH event_data AS ( + SELECT + user_id, + occurred_at, + event_name + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' + AND event_name IN ('content_created', 'content_edited', 'content_shared') +) +SELECT + user_id, + COUNT(*) AS engagement_event_count, + COUNT(DISTINCT DATE(occurred_at)) AS active_day_count, + SUM(CASE WHEN event_name = 'content_shared' THEN 1 ELSE 0 END) AS shares_count +FROM event_data +GROUP BY user_id; +``` + +The metric definition specifies exactly which events count as engagement. The board's "weekly active users" dashboard uses the same event filter via the same `fct_events` model. + +--- + +## Pattern 3: retention metric (bracket retention) + +```sql +-- models/experiments/exp_metrics_retention_w2.sql +{{ config(materialized='table') }} + +WITH user_first_activity AS ( + SELECT user_id, MIN(occurred_at) AS first_active_at + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + GROUP BY user_id +), +week2_activity AS ( + SELECT DISTINCT u.user_id + FROM user_first_activity u + JOIN {{ ref('fct_events') }} e ON e.user_id = u.user_id + WHERE e.occurred_at >= u.first_active_at + INTERVAL '7 days' + AND e.occurred_at < u.first_active_at + INTERVAL '14 days' +) +SELECT + u.user_id, + CASE WHEN w2.user_id IS NOT NULL THEN 1 ELSE 0 END AS retained_w2 +FROM user_first_activity u +LEFT JOIN week2_activity w2 USING (user_id); +``` + +Bracket retention (week 2 = days 7 to 13 from first activity) is more stable than N-day retention. The metric is binary: 1 if retained, 0 if not. + +--- + +## Pattern 4: ratio metric (delta method required) + +Some metrics are ratios (conversion rate, click-through rate). They require the delta method for correct variance estimation. + +```sql +-- models/experiments/exp_metrics_conversion.sql +{{ config(materialized='table') }} + +SELECT + user_id, + COUNT(*) AS impressions, + SUM(CASE WHEN converted THEN 1 ELSE 0 END) AS conversions +FROM {{ ref('fct_funnel_events') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +GROUP BY user_id; +``` + +The model produces numerator and denominator per user. The analysis layer (Python) computes the ratio and applies the delta method for variance. + +```python +# Per-user numerator and denominator +df = warehouse.query("SELECT * FROM exp_metrics_conversion") + +# Group means +control = df[df.variant_id == 'control'] +treatment = df[df.variant_id == 'treatment'] + +# Conversion rate per group +control_rate = control.conversions.sum() / control.impressions.sum() +treatment_rate = treatment.conversions.sum() / treatment.impressions.sum() + +# Delta method variance (skipping the math here; see statistical-analysis-templates.md) +# ... +``` + +Do not compute the ratio per user and average it. That undercounts heavy users; the delta method is the correct treatment. + +--- + +## Versioning metric definitions + +Same versioning pattern as elsewhere. When the metric definition changes meaningfully, append `_v2`. + +``` +exp_metrics_revenue.sql <- v1, fires alongside v2 during transition +exp_metrics_revenue_v2.sql <- new semantics +``` + +The transition is the same: ship v2 alongside v1, migrate experiments to v2 over 90 days, deprecate v1. + +dbt's built-in versioning (the `models:` config with `versions:`) is also useful here; lets you serve both versions from the same model name with explicit version selection. + +--- + +## Aligning experiment metrics with board metrics + +The variance discipline. The same dbt model feeds both surfaces. + +If the board reports "monthly revenue" by summing `amount_cents` from `fct_orders` and excluding refunded orders, the experiment's revenue metric does the same. No special "experiment revenue" calculation that subtly differs. + +The mechanism. Both the board dashboard's SQL and the `exp_metrics_revenue` model reference the same `fct_orders` table with the same filters. dbt tests verify the table contains the expected rows. + +The check. When an experiment lands and the team reports "revenue lifted 5 percent in treatment," the team can pull the same numbers from the board and compare. If the board's revenue is flat or the experiment's lift is much larger than the board's revenue trend, the metric definitions disagree somewhere. Investigate. + +--- + +## Testing experiment metrics + +dbt tests on the metric models catch regressions. + +```yaml +# models/experiments/_experiments.yml +version: 2 + +models: + - name: exp_metrics_revenue + columns: + - name: user_id + tests: + - not_null + - unique + - name: net_revenue_cents + tests: + - not_null + - dbt_utils.expression_is_true: + expression: ">= 0" +``` + +The `unique` test on `user_id` confirms the model produces one row per user (no accidental duplicates from a bad join). The `>= 0` test confirms revenue is non-negative (refunds are subtracted, never additive). + +--- + +## Common metric-definition mistakes + +- **Drift between board and experiment.** "Experiment revenue" is computed differently from "board revenue." Align via shared dbt models. +- **Wrong time window.** The experiment runs for 14 days but the metric model includes 30 days of data. The control and treatment numbers are similar because the variant signal is diluted. +- **One row per event instead of one row per user.** Joining the metric to exposure on `user_id` produces a row explosion. Always aggregate to one row per user before joining. +- **Forgetting to handle nulls.** Users with no activity should appear with metric = 0, not be missing from the model. Use `LEFT JOIN` from exposure or include all eligible users in the metric model. +- **Non-deterministic queries.** Window functions without explicit `ORDER BY`, sampling without a random seed. The same query produces different numbers on different days. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md new file mode 100644 index 0000000..c7008f5 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md @@ -0,0 +1,169 @@ +# Power analysis calculations + +Pre-experiment power analysis. MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. + +The principle. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10 percent lift; the actual effect is 1 percent, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. Power analysis prevents this by forcing a concrete decision about how big the lift needs to be before the experiment starts. + +--- + +## The four parameters + +Power analysis ties together four numbers. Fix any three; the fourth is determined. + +1. **Effect size (or MDE, minimum detectable effect).** The smallest lift the experiment can reliably detect. Expressed as a relative percentage, an absolute difference, or Cohen's d (effect size in standard deviations). +2. **Sample size per arm.** Number of users in each variant. +3. **Alpha (significance level).** Default 0.05. The false-positive rate. +4. **Power.** Default 0.8. One minus the false-negative rate. The probability of detecting a real effect. + +The standard practice. Fix alpha at 0.05, power at 0.8, decide on either the MDE (and solve for sample size) or the sample size (and solve for MDE). + +--- + +## Solving for sample size given MDE + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Continuous metric, two-sample t-test +# Cohen's d = (mean_treatment - mean_control) / pooled_std + +cohens_d = 0.05 # 5 percent of one standard deviation + +n_per_arm = tt_ind_solve_power( + effect_size=cohens_d, + nobs1=None, + alpha=0.05, + power=0.8, + ratio=1.0 # equal sample sizes per arm +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a Cohen's d of 0.05 (small effect), expect roughly 6,300 users per arm. For 0.1 (still small), roughly 1,600 per arm. For 0.2 (medium), roughly 400 per arm. + +### Solving for proportions + +```python +from statsmodels.stats.power import zt_ind_solve_power + +# Binary metric, proportions test +# baseline conversion rate = 5 percent; target lift = 5 percent relative +baseline_p = 0.05 +relative_lift = 0.05 +treatment_p = baseline_p * (1 + relative_lift) + +# Cohen's h for proportions +import numpy as np +def cohens_h(p1, p2): + return 2 * np.arcsin(np.sqrt(p1)) - 2 * np.arcsin(np.sqrt(p2)) + +h = cohens_h(treatment_p, baseline_p) + +n_per_arm = zt_ind_solve_power( + effect_size=h, + nobs1=None, + alpha=0.05, + power=0.8 +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a 5 percent relative lift on a 5 percent baseline conversion rate, expect roughly 60,000 users per arm. Small relative lifts on small baselines need very large samples. + +--- + +## Solving for MDE given sample size + +The reverse calculation. Given the available sample (e.g., 8,000 users per arm), what is the smallest effect the experiment can detect? + +```python +from statsmodels.stats.power import tt_ind_solve_power + +mde_cohens_d = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8, + ratio=1.0 +) +print(f"MDE in Cohen's d: {mde_cohens_d:.4f}") + +# Convert to relative MDE assuming the metric's standard deviation +metric_std = 50.0 # in cents, for example +metric_mean = 200.0 +mde_absolute = mde_cohens_d * metric_std +mde_relative = mde_absolute / metric_mean +print(f"MDE absolute: {mde_absolute:.2f}") +print(f"MDE relative: {mde_relative:.2%}") +``` + +If the available sample yields an MDE of 8 percent and the team expects only a 2 percent lift, the experiment is underpowered. Either secure more sample (run longer or expand the audience) or accept that the experiment will produce an inconclusive result. + +--- + +## Calibrating effect-size assumptions from historical experiments + +The most common power-analysis mistake is over-optimistic effect-size estimates. Three patterns help calibrate. + +### Pattern 1: pull the historical distribution + +For the last 30 (or however many) experiments, pull the observed lifts. Compute the median, 25th percentile, and 75th percentile. + +```python +df = warehouse.query(""" + SELECT experiment_id, observed_relative_lift + FROM experiment_results + WHERE shipped = true + ORDER BY ended_at DESC + LIMIT 30 +""") + +print(f"Median observed lift: {df.observed_relative_lift.median():.2%}") +print(f"P25: {df.observed_relative_lift.quantile(0.25):.2%}") +print(f"P75: {df.observed_relative_lift.quantile(0.75):.2%}") +``` + +The median observed lift is the realistic expectation for the next experiment. If past experiments show a median lift of 1 percent, planning for a 5 percent lift on the next experiment is optimistic. + +### Pattern 2: stratify by experiment type + +Pricing experiments often produce larger lifts than UI experiments. Onboarding experiments often produce larger lifts than feature-discovery experiments. Pull the distribution by experiment type to set type-specific expectations. + +### Pattern 3: ask the team about prior experiments they remember + +The "we usually see X" estimate from team members is anchored on memorable experiments (the wins, the disasters). Compare against the actual distribution; the memorable estimate is usually too high. + +The honest conversation. "Our last 30 experiments had a median observed lift of 0.5 percent. We are planning this experiment for a 5 percent MDE. Either the experiment is going to produce an inconclusive result, or we are expecting an unusually large effect. Which is it?" + +--- + +## When the math says "we cannot run this" + +Three escalation paths when the available sample is insufficient. + +1. **Run longer.** The default. If the experiment needs 60,000 users per arm and you have 10,000 per week, plan for a 6-week run. Document the duration before starting. +2. **Expand the audience.** If the experiment is targeting only paid users (10 percent of the user base), consider running on all users. The result is generalizable to a broader population, but the intervention may need to work for the broader population too. +3. **Accept inconclusive.** Some experiments cannot be powered with the available sample. Document the MDE; design the experiment to detect a larger effect or accept that it will be inconclusive. The discipline of saying "we cannot reliably answer this with our sample" is hard but honest. + +--- + +## The underpowered-experiment cost + +A team running 12 experiments per quarter, 4 of which are underpowered. The cost. + +- Underpowered experiments produce inconclusive results. The team learns nothing. +- Engineering and design effort spent on the experiment is wasted. +- Stakeholders treat inconclusive as "no effect"; later experiments that would have shown the same effect at a larger sample also produce inconclusive, reinforcing the false belief that no effect exists. +- The team's experimentation discipline degrades because the visible track record looks bad. + +Power analysis at the design stage prevents most of this. The cost is 30 minutes of work; the benefit is avoiding multi-week runs of experiments that cannot answer the question. + +--- + +## Common power-analysis mistakes + +- **Optimistic effect-size assumption.** Plan for a 10 percent lift; observe a 1 percent lift. The experiment is 100x underpowered. +- **Forgetting variance from the historical metric.** Power calculations use Cohen's d, which depends on the metric's standard deviation. A high-variance metric requires a larger sample for the same MDE than a low-variance metric. +- **Computing power on aggregate when the assignment unit is something else.** If the assignment unit is user but the metric is per-event, the per-event variance includes within-user correlation. Use the user-level variance for the calculation. +- **Skipping the calculation for "small" experiments.** "We will just see what happens" is the path to a quarter of inconclusive experiments. +- **Confusing statistical significance with practical significance.** A p-value below 0.05 with a 0.3 percent effect on a 100,000-user experiment is statistically significant but may not be worth shipping. Use the MDE as the practical-significance threshold; a 0.3 percent effect is below most teams' MDE. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md new file mode 100644 index 0000000..401eb49 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md @@ -0,0 +1,148 @@ +# Sequential testing patterns + +mSPRT, confidence sequences, group sequential designs. Plus an honest framing on when to peek. + +The principle. Looking at experiment results before completion (peeking) inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. The honest middle ground: if you do not understand the math, do not peek. + +--- + +## The peeking problem + +The standard t-test assumes a fixed sample size pre-registered before the experiment runs. When the team peeks early, the test is implicitly running multiple times; some of those peeks will hit p < 0.05 by chance even when no effect exists. + +A team that peeks daily on a 4-week experiment runs the test roughly 28 times. The implicit false-positive rate becomes much higher than the nominal 5 percent. Estimates suggest 30 percent or more in this case; the experiment is more likely to show a fake significant result than a real one. + +The four solutions. + +1. **Do not peek.** Pre-register the sample size; analyze once. +2. **mSPRT.** Always-valid p-values that survive peeking. +3. **Confidence sequences.** Always-valid confidence intervals via the Howard et al construction. +4. **Group sequential designs.** Pre-specified interim analyses with calibrated alpha-spending. + +Each solution requires implementation discipline. Incorrect implementation is worse than no peeking solution at all (the team thinks the math is correct and ships based on inflated false-positives). + +--- + +## mSPRT (mixture Sequential Probability Ratio Test) + +The most commonly deployed sequential testing method. Used by Optimizely, Statsig. + +The intuition. Compute a Bayes-factor-like statistic that updates as data arrives. The statistic crosses a fixed threshold when the evidence is strong enough to reject the null; it never crosses by chance under the null (with the correct calibration). + +### Python implementation sketch + +```python +import numpy as np + +def mSPRT(treatment, control, prior_var=1.0, alpha=0.05): + """ + Mixture SPRT for two-sample mean difference. + Returns the always-valid p-value at the current sample. + """ + n_t = len(treatment) + n_c = len(control) + diff = treatment.mean() - control.mean() + pooled_var = (treatment.var() / n_t + control.var() / n_c) + se = np.sqrt(pooled_var) + + # Test statistic + z = diff / se + + # Mixture prior with variance prior_var + # Always-valid p-value via the mixture-likelihood ratio + n_eff = (n_t * n_c) / (n_t + n_c) + weight = np.sqrt(prior_var / (prior_var + 1.0 / n_eff)) + log_lr = 0.5 * z**2 * (1 - weight**2) - 0.5 * np.log(1.0 / weight**2) + p_always_valid = min(1.0, np.exp(-log_lr)) + + return p_always_valid +``` + +Note: the implementation above is a sketch for illustration. Production implementations should use a peer-reviewed library or expert review. Do not deploy this verbatim. + +The honest version. Use a maintained library (`sequential` in R, custom Python adapted from peer-reviewed papers like Johari et al 2017). Have a statistician on the team review the implementation. + +--- + +## Confidence sequences (Always-Valid Inference) + +The Howard et al construction. Confidence intervals that are valid at any sample size; the team can peek arbitrarily often without inflating the false-positive rate. + +The math is more involved than mSPRT. Useful when the team needs not just always-valid p-values but always-valid confidence intervals (effect size with uncertainty). + +References. + +- Howard, Ramdas, McAuliffe, Sekhon (2021), "Time-uniform, nonparametric, nonasymptotic confidence sequences." +- Code: `sequential` package in R, or custom Python. + +For most warehouse-native teams, mSPRT is enough. Confidence sequences are for teams with a statistician who has read the paper and validated the implementation. + +--- + +## Group sequential designs + +The classical frequentist approach. Pre-specified interim analysis points (e.g., at 25 percent, 50 percent, 75 percent of the planned sample) with calibrated alpha-spending boundaries. + +The most common boundary is **O'Brien-Fleming**. Conservative early (high effect size required to stop early); lenient late (lower effect size required to stop at the final analysis). + +```python +# Hypothetical O'Brien-Fleming boundaries for 4 interim analyses +# Z-values; if observed Z exceeds, reject the null and stop +boundaries = { + 0.25: 4.05, + 0.50: 2.86, + 0.75: 2.34, + 1.00: 2.02, +} +``` + +The discipline. + +1. Pre-register the interim analysis points and the boundary values. +2. At each interim point, compute the test statistic. +3. If the statistic exceeds the boundary, stop the experiment and reject the null. +4. If the statistic does not exceed any boundary by the final analysis, fail to reject (treat as inconclusive or as "no effect detected"). + +Group sequential designs require commitment up front. Adding interim analyses after the experiment starts is post-hoc peeking and inflates the false-positive rate. + +--- + +## When to peek and when not to + +Three scenarios. + +### Scenario 1: small team, no statistician, simple experiments + +Do not peek. Pre-register the sample size; analyze once at completion. The discipline is simpler than implementing sequential testing correctly, and the cost (running for the full pre-registered duration) is usually small. + +### Scenario 2: high-volume team running many experiments, has a statistician + +Implement mSPRT. The peeking is operationally useful (early stops free up the testing infrastructure for the next experiment) and the math is well-understood. Train the team on the implementation; review periodically. + +### Scenario 3: regulated industry, strong audit requirements + +Group sequential design. Pre-registered interim analyses with calibrated boundaries. The audit trail is clean: every interim analysis was specified before the experiment started; the boundaries are reproducible from the design document. + +--- + +## Common sequential testing mistakes + +- **Implementing mSPRT without understanding the math.** A wrong implementation produces inflated false-positives that the team trusts. Worse than no peeking. +- **Adding interim analyses after the experiment starts.** Group sequential designs require pre-registration. Post-hoc interim analyses are just peeking. +- **Mixing methods.** Compute mSPRT for some peeks and a standard t-test for others. The latter inflates false-positives; the former does not. Pick one method per experiment and stick to it. +- **Using mSPRT but reporting the standard p-value.** The mSPRT p-value is always-valid; the standard p-value is not. Reporting the standard p-value while peeking is the same as not using mSPRT at all. +- **Stopping early on a tiny effect.** mSPRT may show "significant" before the team has enough evidence on practical significance. The effect is real but small; shipping it may not be worth the engineering complexity. + +--- + +## The honest recommendation + +For most warehouse-native experimentation teams, the right answer is "do not peek." + +- Pre-register the sample size based on power analysis. +- Run to the pre-registered sample. +- Analyze once at completion. + +The cost is some early stops the team would have liked. The benefit is no implementation risk in sequential testing math, no false-positives from mis-implemented peeking, and a clean audit trail. + +Move to sequential testing when the team has the statistical expertise to implement correctly and the operational pressure to peek (high-volume infrastructure where early stops materially affect the next experiment's timeline). diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md new file mode 100644 index 0000000..c1b1137 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md @@ -0,0 +1,241 @@ +# Statistical analysis templates + +SQL and Python templates for the most common warehouse-native analyses. t-test, proportions test, Mann-Whitney, bootstrap. Plus the recommended notebook structure. + +--- + +## Welch's t-test (continuous metrics) + +The default for continuous metrics where group variances may differ. + +### SQL + +```sql +WITH joined AS ( + SELECT e.variant_id, m.net_revenue_cents + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +), +metric_by_variant AS ( + SELECT + variant_id, + COUNT(*) AS n, + AVG(COALESCE(net_revenue_cents, 0)) AS mean, + VAR_SAMP(COALESCE(net_revenue_cents, 0)) AS variance + FROM joined + GROUP BY variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic, + -- Standard error of the mean difference + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS se, + control.n AS control_n, + treatment.n AS treatment_n +FROM + (SELECT * FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment; +``` + +The query returns the t-statistic and standard error. Convert to p-value and confidence interval via a UDF or in Python. + +### Python + +```python +import pandas as pd +from scipy import stats +import numpy as np + +df = warehouse.query(""" + SELECT e.variant_id, COALESCE(m.net_revenue_cents, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +t_stat, p_value = stats.ttest_ind(treatment, control, equal_var=False) + +# 95 percent confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"t = {t_stat:.3f}, p = {p_value:.4f}") +``` + +--- + +## Proportions test (binary metrics) + +For binary outcomes (converted vs not, retained vs not). + +### Python + +```python +from statsmodels.stats.proportion import proportions_ztest, proportion_confint + +# Counts and totals per variant +control_conv = 1240 +control_n = 25000 +treatment_conv = 1390 +treatment_n = 25000 + +# Z-test +z_stat, p_value = proportions_ztest( + [control_conv, treatment_conv], + [control_n, treatment_n] +) + +# Confidence intervals on each proportion +control_ci = proportion_confint(control_conv, control_n, method='wilson') +treatment_ci = proportion_confint(treatment_conv, treatment_n, method='wilson') + +# Lift +control_rate = control_conv / control_n +treatment_rate = treatment_conv / treatment_n +relative_lift = (treatment_rate - control_rate) / control_rate + +print(f"Control: {control_rate:.4f}, CI: {control_ci}") +print(f"Treatment: {treatment_rate:.4f}, CI: {treatment_ci}") +print(f"Relative lift: {relative_lift:.2%}") +print(f"z = {z_stat:.3f}, p = {p_value:.4f}") +``` + +The Wilson score interval is more accurate than the normal approximation for small samples or extreme proportions. + +--- + +## Mann-Whitney U test (non-parametric) + +For metrics with skewed distributions (revenue, time-on-site) where the t-test's normal-distribution assumption is violated. + +```python +from scipy.stats import mannwhitneyu + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +u_stat, p_value = mannwhitneyu(treatment, control, alternative='two-sided') + +# Mann-Whitney tests stochastic dominance, not the mean. +# Report median lift alongside. +median_lift = treatment.median() - control.median() +print(f"Median lift: {median_lift:.2f}") +print(f"U = {u_stat:.0f}, p = {p_value:.4f}") +``` + +The Mann-Whitney U test is the standard non-parametric alternative. Use when the metric distribution is skewed and the t-test's assumption fails. + +--- + +## Bootstrap confidence interval + +For metrics where the analytic distribution is unclear or unusual (e.g., retention bracket, complex composite metrics). + +```python +import numpy as np + +def bootstrap_ci(treatment, control, n_iterations=10000, alpha=0.05): + diffs = [] + for _ in range(n_iterations): + t_sample = treatment.sample(n=len(treatment), replace=True) + c_sample = control.sample(n=len(control), replace=True) + diffs.append(t_sample.mean() - c_sample.mean()) + diffs = np.array(diffs) + return np.quantile(diffs, [alpha / 2, 1 - alpha / 2]) + +ci_low, ci_high = bootstrap_ci(treatment, control) +diff = treatment.mean() - control.mean() +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +``` + +10,000 bootstrap iterations is the standard. More iterations produce tighter intervals at the cost of compute time. + +--- + +## Notebook structure + +The recommended structure for an experiment analysis notebook. + +### Cell 1: parameters + +```python +EXPERIMENT_ID = 'exp_button_color_v1' +EXPERIMENT_START = '2026-04-01' +EXPERIMENT_END = '2026-04-15' +PRIMARY_METRIC = 'net_revenue_cents' +SECONDARY_METRICS = ['order_count', 'session_count'] +ALPHA = 0.05 +``` + +Parameters at the top. Parametrize the notebook so the same template runs for any experiment. + +### Cell 2: SRM check + +```python +df_exposures = warehouse.query(f""" + SELECT variant_id, COUNT(*) AS n + FROM exposures + WHERE experiment_id = '{EXPERIMENT_ID}' + GROUP BY variant_id +""") + +# Chi-squared test against expected ratio +from scipy.stats import chi2_contingency +observed = df_exposures.n.values +expected = [observed.sum() / len(observed)] * len(observed) +chi2, p, _, _ = chi2_contingency([observed, expected]) +assert p > 0.01, f"SRM detected (p = {p:.4f}). Aborting analysis." +print(f"SRM check passed (p = {p:.4f})") +``` + +Abort the notebook if SRM is detected. Do not proceed to metric analysis with broken assignment. + +### Cell 3: pull data + +```python +df = warehouse.query(f""" + SELECT + e.variant_id, + e.user_id, + COALESCE(m.{PRIMARY_METRIC}, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = '{EXPERIMENT_ID}' +""") +``` + +### Cell 4: primary analysis + +t-test, proportions test, or bootstrap depending on the metric. + +### Cell 5: secondary metrics + +Loop over secondary metrics; apply Bonferroni correction for multiple comparisons. + +### Cell 6: written-up decision + +A markdown cell with the conclusion. Ship, kill, or inconclusive. Include the lift, the CI, the p-value, the SRM result, and any caveats. This cell is the deliverable. + +--- + +## Common analysis mistakes + +- **No SRM check.** Analyzing an experiment with broken assignment produces meaningless numbers. +- **Equal-variance t-test on unequal-variance data.** Use Welch's (`equal_var=False`) by default. +- **t-test on heavily skewed metrics.** Use bootstrap or Mann-Whitney instead. +- **Per-user ratios for ratio metrics.** Heavy users get under-weighted. Use the delta method. +- **Multiple secondary metrics without correction.** With 5 secondary metrics at alpha 0.05, expect a 25 percent chance of a false positive somewhere. Bonferroni or BH correction. +- **Stop-on-significance peeking.** Inflates the false-positive rate. Either pre-register the sample size or use a sequential testing method correctly. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md new file mode 100644 index 0000000..daa2693 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md @@ -0,0 +1,179 @@ +# Variance reduction techniques + +CUPED is the most powerful variance reduction technique for warehouse-native experimentation. Stratification, regression adjustment, and doubly robust estimation cover specific cases. + +The principle. Variance reduction makes confidence intervals narrower at the same sample size. A 30 to 50 percent variance reduction (typical with CUPED on engagement metrics) is equivalent to running the experiment 1.5 to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +--- + +## CUPED: the workhorse + +**CUPED** stands for Controlled-experiment Using Pre-Experiment Data. Originally from Microsoft (Deng et al, 2013). + +The intuition. If you can predict a user's metric behavior from pre-experiment data (their behavior before the experiment started), you can subtract that prediction from the metric, leaving a smaller residual to test on. The mean is preserved (CUPED does not change the point estimate of the lift), but the variance shrinks because predictable variance has been removed. + +### The math + +For each user, compute a pre-experiment covariate (e.g., revenue in the 28 days before the experiment started). Call this `pre_metric`. The CUPED-adjusted metric is: + +``` +adjusted_metric = metric - theta * (pre_metric - mean(pre_metric)) +``` + +where `theta` is the regression coefficient of `metric` on `pre_metric`: + +``` +theta = cov(metric, pre_metric) / var(pre_metric) +``` + +Run the t-test on `adjusted_metric` instead of `metric`. The mean difference between treatment and control is preserved; the variance is reduced. + +### Python implementation + +```python +import pandas as pd +import numpy as np + +# df has columns: user_id, variant_id, metric, pre_metric +df = warehouse.query(""" + SELECT + e.user_id, + e.variant_id, + COALESCE(m.net_revenue_cents, 0) AS metric, + COALESCE(p.pre_net_revenue_cents, 0) AS pre_metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + LEFT JOIN pre_experiment_revenue p USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +# Compute theta from the entire dataset (control and treatment combined) +theta = np.cov(df.metric, df.pre_metric)[0, 1] / np.var(df.pre_metric) + +# CUPED-adjusted metric +df['adjusted_metric'] = df.metric - theta * (df.pre_metric - df.pre_metric.mean()) + +# Run t-test on the adjusted metric +from scipy import stats +control_adj = df[df.variant_id == 'control'].adjusted_metric +treatment_adj = df[df.variant_id == 'treatment'].adjusted_metric +t_stat, p_value = stats.ttest_ind(treatment_adj, control_adj, equal_var=False) + +# Compare to unadjusted variance +unadjusted_var = df.metric.var() +adjusted_var = df.adjusted_metric.var() +variance_reduction = 1 - adjusted_var / unadjusted_var +print(f"Variance reduction: {variance_reduction:.1%}") +``` + +### When CUPED works well + +- Engagement metrics with strong autocorrelation. Pre-experiment activity strongly predicts in-experiment activity. +- Revenue metrics on consumer products with repeat customers. +- Retention metrics where past retention predicts future retention. + +### When CUPED works poorly + +- New users (no pre-experiment data). They drop out of the analysis or are imputed. +- Metrics with weak temporal autocorrelation. The pre-period does not predict the in-period. +- Metrics that are zero for most users (highly skewed binary outcomes). The t-test's normal-distribution assumption fails; CUPED on top inherits the failure. + +### Pre-experiment window length + +A 28-day pre-experiment window is the typical default. Longer windows (60 to 90 days) capture more of the user's behavior pattern and may reduce variance more, but also reduce eligibility (users who joined within the window have no pre-period). + +The discipline. Pre-register the pre-period length when designing the experiment. Do not change it after looking at results. + +--- + +## Stratification + +Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. + +```python +# Stratify by device +strata = df.device_type.unique() +stratum_estimates = [] +for s in strata: + sub = df[df.device_type == s] + diff = sub[sub.variant_id == 'treatment'].metric.mean() - sub[sub.variant_id == 'control'].metric.mean() + stratum_estimates.append({ + 'stratum': s, + 'n': len(sub), + 'diff': diff, + }) + +# Pool: weighted average by stratum size +total_n = sum(s['n'] for s in stratum_estimates) +pooled_diff = sum(s['diff'] * s['n'] / total_n for s in stratum_estimates) +``` + +The variance of the pooled estimate is lower than the unpooled t-test when the strata have different baseline metrics (the across-stratum variance is removed). + +The downside. Stratification by too many covariates produces small per-stratum samples, which inflates per-stratum variance. Use stratification on one or two strong predictors, not on every covariate available. + +--- + +## Regression adjustment (covariate adjustment via OLS) + +A generalization of CUPED to multiple covariates. + +```python +import statsmodels.api as sm + +# X: covariates (pre_metric, device_type encoded, region encoded) +X = pd.get_dummies(df[['pre_metric', 'device_type', 'region']], drop_first=True) +X['variant_treatment'] = (df.variant_id == 'treatment').astype(int) +X = sm.add_constant(X) +y = df.metric + +# OLS regression +model = sm.OLS(y, X).fit() +print(model.summary()) + +# The coefficient on 'variant_treatment' is the adjusted effect estimate. +# Its standard error is typically smaller than the unadjusted t-test SE. +``` + +Regression adjustment is more flexible than CUPED but requires more care: collinearity among covariates, model misspecification, and overfitting on small samples are all possible failure modes. + +For most warehouse-native experiments, CUPED with a single pre-period covariate is enough. Regression adjustment with multiple covariates is for edge cases. + +--- + +## Doubly robust estimation + +Useful in observational and quasi-experimental settings where randomization was imperfect (geo experiments, switchback designs, natural experiments). + +The intuition. Combine an outcome model (predict the metric from covariates) with a propensity-score model (predict the probability of treatment from covariates). The combined estimator is unbiased if either of the two models is correct (hence "doubly robust estimation"). + +For the standard A/B test where assignment is random, doubly robust estimation does not help. The benefit is in observational settings where the assignment mechanism may be confounded. + +The implementation requires `causalml`, `dowhy`, or a custom implementation. Outside the scope of the typical experiment notebook; pointer to the academic literature for full treatment. + +References. + +- Bang and Robins (2005), "Doubly Robust Estimation in Missing Data and Causal Inference Models." +- Funk et al. (2011), "Doubly Robust Estimation of Causal Effects." + +--- + +## When to invest in variance reduction + +Three signals. + +1. **Running 5+ experiments per quarter.** The amortized engineering investment in CUPED pays back across many experiments. +2. **The team is power-constrained.** Experiments routinely run too long or hit inconclusive results because of insufficient sample size. CUPED extends the effective sample size by 30 to 50 percent. +3. **The team has data scientists who understand the math.** CUPED is straightforward but easy to implement incorrectly (theta computed on the wrong subset, pre-period window misaligned, regression diagnostics ignored). Without someone on the team who can audit the implementation, the variance reduction may not be real. + +The order of investment. CUPED first; it is the highest ROI. Stratification second; useful for one or two strong predictors. Regression adjustment third; for edge cases where multiple covariates matter. Doubly robust estimation last; for genuine quasi-experiments. + +--- + +## Common variance reduction mistakes + +- **Computing theta on treatment data only.** Theta should be computed on the combined dataset (control plus treatment) for unbiased estimation. Computing on treatment alone re-introduces the bias CUPED is trying to remove. +- **Pre-period contamination.** The pre-period overlaps with the experiment period. Users in the experiment have already been exposed when their "pre-period" metric is measured. The pre-metric is not actually pre. +- **CUPED on heavily skewed binary metrics.** CUPED reduces variance but does not change the metric's distribution. A binary metric where 99 percent of users are 0 is still skewed after CUPED; the t-test is still misspecified. +- **Stratification on a post-experiment covariate.** The covariate must be measured before the experiment, otherwise the stratification creates selection bias. Use only pre-experiment covariates for stratification. +- **Forgetting to validate that variance actually decreased.** Run both adjusted and unadjusted analyses; verify the adjusted variance is smaller. If it is not, CUPED is not helping for this metric and pre-period. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md new file mode 100644 index 0000000..21e0222 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md @@ -0,0 +1,145 @@ +# Warehouse vs platform decision + +Side-by-side comparison. Cost considerations at scale. Hybrid patterns. Migration patterns. Decision tree. + +The principle. Both operational models are valid. The right choice depends on team strength, volume, custom-metric needs, and how much engineering time you are willing to invest in experimentation infrastructure. + +--- + +## Side-by-side comparison + +| Dimension | Platform (Statsig, Optimizely, etc.) | Warehouse-native | +|---|---|---| +| Time to first experiment | Hours to days | Days to weeks | +| Custom metric depth | Limited to platform's metric library | Anything you can write in SQL | +| Custom segmentation | Platform-specific filters | dbt models compose without limit | +| Cost shape | Per-MAU or per-event subscription | Existing warehouse compute | +| Engineering investment | Low | Medium to high | +| Sequential testing | Out of the box | Build it yourself or skip | +| Frontend visual editing | Optimizely, VWO ship this | Not applicable | +| Mobile SDK assignment | Out of the box | Build it yourself | +| Trust and audit | Platform's math is a black box | Every step is auditable SQL | +| Iteration speed on metric definitions | Platform release cadence | dbt deploy cadence | +| Ecosystem integration | Platform's connectors | Warehouse already has the data | + +--- + +## Cost considerations at scale + +Approximate costs as of 2025-2026. Verify with vendor pricing. + +### 10K MAU + +- Platform (mid-tier): $0 to $500 per month. Free tiers from PostHog, Statsig, Amplitude cover this. +- Warehouse-native: warehouse compute already paid for. Engineering time cost: 1 to 2 weeks of a data engineer's time to set up infrastructure. + +Recommendation. Platform. The engineering time on warehouse-native at this scale does not pay back. + +### 100K MAU + +- Platform (mid-tier): $1K to $10K per month. Statsig, PostHog paid tiers; Optimizely contract. +- Warehouse-native: same warehouse compute; engineering time amortized over more experiments. + +Recommendation. Either. Depends on team strength and custom-metric needs. Many teams stay on a platform; some graduate to warehouse-native. + +### 1M MAU + +- Platform: $10K to $80K per month, often more for enterprise contracts. Optimizely Enterprise can hit $200K+ per year. +- Warehouse-native: same warehouse compute. The engineering investment pays back at this scale. + +Recommendation. Warehouse-native is increasingly attractive. Many enterprise data teams run warehouse-native primary, with a platform for specific use cases (frontend visual experiments). + +### 10M+ MAU + +- Platform: enterprise contracts at $200K to $1M+ per year. +- Warehouse-native: dominant pattern at this scale. Custom infrastructure plus dbt plus Python notebooks. + +Recommendation. Warehouse-native, often with a thin platform for fast frontend iteration. + +--- + +## Hybrid patterns + +Three common hybrid patterns. + +### Pattern 1: platform for product, warehouse-native for analytics + +The platform handles assignment and exposure for product experiments. The warehouse handles analysis for the same experiments by reading the platform's exposure data. + +Why. The platform's analysis is fine for standard cases; warehouse-native analysis allows custom metrics and segmentation the platform cannot express. + +Operational shape. The platform's exposure events flow to the warehouse (typically via webhook or scheduled export). dbt models compute custom metrics; the analyst runs the t-test in Python against the joined data. + +### Pattern 2: warehouse-native for backend, platform for frontend + +Warehouse-native handles backend experiments where assignment is server-side (pricing, recommendations, ML model variants). The platform handles frontend visual experiments (button colors, copy, layout). + +Why. Frontend visual experiments benefit from the platform's WYSIWYG editor and script-tag injection. Backend experiments benefit from warehouse-native's metric flexibility. + +Operational shape. Two separate experiment registries. Each team picks the right tool for the experiment type. + +### Pattern 3: platform for fast iteration, warehouse-native for hard cases + +The platform handles experiments where time-to-result matters more than custom depth. Warehouse-native handles experiments where the platform cannot express the metric. + +Why. Most experiments are standard; the platform is faster. The 10 percent that are not standard need the warehouse. + +Operational shape. Default to platform; escalate to warehouse-native when the platform fails to support the experiment design. + +--- + +## Migration patterns + +### Platform to warehouse-native + +Triggered by cost (the platform bill became a budget item) or capability (the platform cannot handle a specific experiment design that matters). Typical effort: 6 to 12 engineer-weeks for the first warehouse-native experiment with full infrastructure; later experiments amortize the investment. + +Steps. Build the assignment hash function. Build the exposure logging discipline. Define the first metric in dbt. Run a parallel experiment on the platform and warehouse-native; verify results match within statistical noise. Migrate experiments one at a time; retire the platform when the last in-flight experiment completes. + +### Warehouse-native to platform + +Triggered by team contraction (the data engineer who built the infrastructure left) or by velocity needs (experiments are taking too long to set up). Typical effort: 2 to 4 engineer-weeks; the platform handles the heavy lifting. + +Steps. Pick the platform. Wire up assignment and exposure. Migrate the metric library to the platform's format. Run the first experiment on the platform; verify results align with what warehouse-native would have produced. + +The frequent reverse migration. Companies that move to warehouse-native and discover the engineering investment is too much. The migration back is usually faster than the migration out. + +--- + +## Decision tree + +``` +Is your team running 5+ experiments per quarter? +├── No → Platform. Warehouse-native does not pay back at low volume. +└── Yes → Continue. + │ + Do you have a data engineer and a data scientist? + ├── No → Platform. Warehouse-native requires both roles. + └── Yes → Continue. + │ + Are your experiments primarily frontend visual? + ├── Yes → Platform (Optimizely, VWO). Warehouse-native cannot match. + └── No → Continue. + │ + Do you need custom metrics the platform cannot express? + ├── Yes → Warehouse-native. The custom metric is the use case. + └── No → Continue. + │ + Is the platform bill exceeding 10x the cost of the engineering time? + ├── Yes → Warehouse-native. The math justifies it. + └── No → Platform. The simplicity is worth the cost. +``` + +The defaults. New teams: platform. Mature teams with strong data infrastructure and high volume: hybrid or warehouse-native primary. The decision is never permanent; revisit annually. + +--- + +## When the math is wrong + +Two situations where teams misjudge the build-vs-buy. + +**Underestimating engineering cost.** "We can build this in a week" rarely holds. The first experiment takes weeks; the second takes days; the long tail of pitfalls (CUPED, sequential testing, SRM checks, dashboard reconciliation) adds up to months of engineering investment. Budget realistically. + +**Overestimating platform limitations.** "The platform cannot handle our metric" is sometimes true and sometimes a workflow problem. Verify with the vendor; many platforms have advanced features (Cortex Analyst on Snowflake, custom SQL metrics on Statsig) that solve the apparent limitation. + +The honest test. Run a 30-day proof of concept on the platform with the actual experiment you say it cannot handle. If the platform truly fails, warehouse-native is justified. If the platform works (even if imperfectly), the cost-benefit shifts back toward the platform. diff --git a/dist/pi/.agents/skills/dependency-management/SKILL.md b/dist/pi/.agents/skills/dependency-management/SKILL.md new file mode 100644 index 0000000..4ea6220 --- /dev/null +++ b/dist/pi/.agents/skills/dependency-management/SKILL.md @@ -0,0 +1,326 @@ +--- +name: dependency-management +description: "Manage third-party libraries, runtimes, and SaaS dependencies. Use this skill when setting an update cadence, responding to security advisories, dealing with deprecated dependencies, evaluating new dependencies, auditing what's installed, or unblocking a dependency upgrade. Triggers on dependency, package update, security patch, lockfile, deprecated, breaking change, supply chain, dependency audit, npm audit, dependabot, renovate. Also triggers when a build breaks after an update or when an advisory is published for a used package." +category: cross-cutting +catalog_summary: "Package updates, security patches, lockfile hygiene" +display_order: 4 +--- + +# Dependency Management + +Decide what to depend on, keep dependencies current, respond to advisories, and reduce supply chain risk. Stack-agnostic principles; specifics vary by package manager. + +--- + +## When to use + +- Setting up dependency hygiene for a new or existing project +- Responding to a security advisory +- Major version upgrade of a key dependency +- Adding a new dependency (evaluation, decision) +- Removing a dependency (cleanup) +- Audit of what's installed and what's actually used +- Setting an update cadence and policy +- Diagnosing a broken build after an update + +## When NOT to use + +- General code review (use `code-review-web`) +- Vulnerability scanning of infrastructure (use `security-baseline`) +- Pinning vendor or service contracts (use `vendor-evaluation`) +- Performance impact of dependencies (use `performance-optimization`) + +--- + +## Required inputs + +- Package manager and lockfile in use (npm, yarn, pnpm, pip, gem, composer, etc.) +- Current dependency list (production and dev) +- Current advisories (run audit; check service like Snyk, Dependabot) +- Update history (when were major dependencies last updated) +- Risk profile (production criticality, change tolerance) + +--- + +## The framework: 4 categories of dependency + +Every dependency falls into one of these. The category drives the policy. + +### Category 1: Critical runtime + +Code that runs in production and would break the system if it failed. + +Examples: framework, database driver, payment SDK, authentication library. + +Policy: +- **Update cadence:** monthly minor, quarterly major (with planning) +- **Security:** patch within 24-72 hours of advisory, 24h for critical +- **Pinning:** exact version pins or narrow ranges +- **Vetting:** thoroughly evaluated before adoption + +### Category 2: Supporting runtime + +Code that runs in production but is replaceable or non-critical. + +Examples: utility libraries, formatting, non-core integrations. + +Policy: +- **Update cadence:** monthly together with critical +- **Security:** patch within a week of advisory +- **Pinning:** narrow ranges acceptable (e.g., `^1.2.3`) +- **Vetting:** moderate evaluation; alternatives considered + +### Category 3: Dev/build + +Code that runs only during development or build, not in production. + +Examples: bundlers, linters, test frameworks, type checkers. + +Policy: +- **Update cadence:** quarterly +- **Security:** patch within a week (still matters; supply chain attacks target build tools) +- **Pinning:** ranges acceptable +- **Vetting:** lighter; broken dev tools surface fast + +### Category 4: Optional/dev-only-personal + +Tools individual developers use that aren't part of shared dev environment. + +Not really managed at the project level. Mentioned for completeness. + +--- + +## The framework: 5 risk dimensions + +When evaluating a dependency, consider: + +### Dimension 1: Maintenance health + +- Last commit date (months ago is concerning) +- Open issue count and age +- Number of maintainers +- Sponsorship or commercial backing +- Roadmap visibility + +A dependency abandoned a year ago is a liability waiting to surface. + +### Dimension 2: Surface area + +- Size of the package +- Number of transitive dependencies +- Footprint in the bundle (for client-side) +- Privileges required (file system, network, etc.) + +A small dependency that pulls in 50 transitive packages has the surface area of all 50. + +### Dimension 3: Replaceability + +- How hard would it be to remove? +- Are there alternatives? +- Could the functionality be implemented in-house? +- Is the API standard or idiomatic? + +A dependency you can't replace is leverage you've granted to its maintainer. + +### Dimension 4: Trust + +- Reputation of the maintainer or organization +- Code quality (skim the source) +- License (GPL, MIT, BSD, proprietary, none) +- History of security issues +- Supply chain practices (signed releases, 2FA on publishes) + +### Dimension 5: Cost + +- Time to evaluate, integrate, maintain +- Risk of breaking changes +- Lockfile entropy +- Potential security exposure +- Bundle size impact (for client-side) + +Every dependency has a cost. Free packages aren't free. + +--- + +## Workflow + +### Step 1: Inventory + +Run a dependency listing: + +```bash +# npm/yarn/pnpm +npm ls --all --json + +# pip +pip list + +# gem +bundle list +``` + +For each top-level dependency, categorize (critical / supporting / dev). For transitives, you generally don't manage individually unless one becomes a problem. + +### Step 2: Audit + +Run the security audit: + +```bash +npm audit +yarn audit +pip-audit +bundle audit +``` + +For each finding: +- Severity (critical, high, medium, low) +- Package and version +- Fix available? +- Used directly or transitively? + +### Step 3: Categorize and prioritize + +| Severity | Direct dep | Indirect dep | +|---|---|---| +| Critical | Patch today | Patch this week (if a fix exists; track if not) | +| High | Patch this week | Patch this month | +| Medium | Patch this month | Track; patch with next round | +| Low | Track | Track | + +Critical and high in production code are emergencies. Low and medium are scheduled work. + +### Step 4: Test before merging fixes + +Even patch-level updates can break things. For critical dependencies: +- Run the full test suite +- Smoke-test in staging +- Watch the monitoring after rollout + +For supporting and dev: +- Run the test suite +- A failed test is OK to investigate; don't merge a known-broken update + +### Step 5: Plan major version upgrades + +Major versions break things. Plan rather than rush. + +For each major upgrade: +- Read the changelog and migration guide +- Estimate the migration effort +- Schedule the work (don't do it under deadline pressure) +- Branch and test thoroughly +- Plan a staged rollout if it's a critical dependency + +Don't sit on major versions indefinitely. The longer you wait, the more painful the upgrade. + +### Step 6: Set the policy + +Document: +- Update cadence (e.g., monthly review, quarterly upgrades) +- Security response SLA (e.g., critical within 24h) +- Approval for new dependencies (who signs off) +- Removal criteria (when do we drop a dependency) +- Pinning strategy (exact, narrow range, broad range) + +The policy is what survives team turnover. Without it, dependency management becomes chaotic ad hoc work. + +### Step 7: Automate + +- **Renovate** or **Dependabot** for automatic update PRs +- CI runs audit on every PR +- Block merges on critical advisories (with override path for false positives) +- Notify on advisories for installed packages +- Lockfile diff in PR review + +Automation reduces toil. Manual checking doesn't scale. + +### Step 8: Audit usage periodically + +Quarterly: +- Dependencies installed but not imported anywhere (run a tool like `depcheck`) +- Major versions behind (more than 1-2 majors behind = upgrade plan needed) +- Unmaintained packages (last commit over a year ago = consider replacing) +- License audit (anything that's changed terms?) + +Remove what's not used. Replace what's unmaintained. + +--- + +## New dependency evaluation + +Before adding a new dependency, answer: + +- [ ] What problem does this solve? +- [ ] Could we solve it without a dependency? (Often yes for small problems.) +- [ ] What alternatives exist? +- [ ] Is the package actively maintained? +- [ ] What's the install size and bundle impact? +- [ ] What are the transitive dependencies? (Worth a quick scan.) +- [ ] What's the license? +- [ ] What's the security history? +- [ ] How replaceable is it? + +Default: don't add. Add only when the value clearly exceeds the cost. The cost includes ongoing maintenance, not just installation. + +--- + +## Dependency removal + +When removing a dependency: + +- [ ] Identify all usages (search the codebase) +- [ ] Replace each usage (with native code, another dependency, or a no-op) +- [ ] Remove from package.json or equivalent +- [ ] Update lockfile (run install) +- [ ] Verify tests pass +- [ ] Verify build size went down (or stayed the same) +- [ ] Document the removal in the changelog + +Removed dependencies sometimes leave config files, CI hooks, or imports behind. Search broadly. + +--- + +## Failure patterns + +**No update cadence.** Dependencies drift. When you finally upgrade, it's painful. Set a cadence. + +**Audit disabled in CI.** "Too noisy." Tune the audit, don't disable it. Whitelist known false positives explicitly. + +**Pinning everything to exact versions.** Stops automatic patches. Misses security fixes. Use narrow ranges with a lockfile. + +**Unpinned floating versions.** `latest` in production. Builds aren't reproducible. Lockfile required. + +**Adding dependencies without review.** "I just needed a quick utility." Now there are 50 unused dependencies. Require review for new dependencies. + +**Ignoring transitive dependencies.** A direct dependency pulls in 50 indirect ones. Each is supply chain surface. Audit the tree, not just the top level. + +**Patching with major version bumps.** "Updating to fix a bug" but the update is a major version. Now you have unrelated breaking changes too. Be deliberate about the version of the fix. + +**Vendor-bundled libraries.** Some dependencies vendor copies of other dependencies. They're not visible to the audit. Periodically check. + +**Build-time dependencies treated as zero-risk.** Build tools have access to your code and credentials. Supply chain attacks target them. Treat with appropriate care. + +**Fork without rebase plan.** Forking a dependency to fix something. Then you own it. Plan how to rebase or merge upstream changes, or commit to maintaining the fork. + +**No license audit.** Project ships with a GPL dependency in a commercial product. Compliance issue. Audit licenses on add and quarterly. + +**Update PRs piling up.** Dependabot PRs go unmerged for months. Either tune to fewer PRs or commit time to merging them. + +--- + +## Output format + +A dependency policy document includes: + +- **Inventory:** current dependencies by category +- **Audit status:** open advisories, severity, plan +- **Policies:** cadence, SLA, pinning, approval +- **Tooling:** what's automated (Renovate, Dependabot, audit in CI) +- **License audit:** any concerns +- **Quarterly review schedule:** when this gets revisited + +--- + +## Reference files + +- [`references/upgrade-checklist.md`](references/upgrade-checklist.md): Step-by-step checklist for performing a major version upgrade of a critical dependency, from changelog reading to staged rollout. diff --git a/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md b/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md new file mode 100644 index 0000000..f9e6929 --- /dev/null +++ b/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md @@ -0,0 +1,290 @@ +# Major Version Upgrade Checklist + +Step-by-step checklist for upgrading a critical dependency to a new major version. The work is in the prep, not the install. + +--- + +## Phase 1: Decide whether to upgrade + +- [ ] Read the changelog from current version to target version +- [ ] Read the migration guide (most major libraries publish one) +- [ ] Skim issues filed against the new version (early adopters surface problems) +- [ ] Note any other dependencies that may need to upgrade in tandem +- [ ] Estimate effort (hours, days, weeks?) +- [ ] Estimate risk (low/medium/high) +- [ ] Estimate value (security fix, new features, ecosystem support, etc.) + +Decision: GO, DEFER, or SKIP. + +**GO triggers:** +- Security fix only available in new major +- Current version losing support +- New version unblocks a needed feature +- Effort and risk are manageable + +**DEFER triggers:** +- New version released within last 30 days (let early adopters surface bugs) +- Conflicts with active development +- No urgent driver + +**SKIP triggers:** +- Maintenance discontinued; replace the dependency instead +- Migration effort exceeds the value +- A different replacement is the better path + +--- + +## Phase 2: Prepare + +### Branch + +- [ ] Create a feature branch named for the upgrade (e.g., `upgrade/library-v3`) +- [ ] Don't mix the upgrade with other work; isolate it + +### Read the changelog carefully + +- [ ] List every breaking change between current and target version +- [ ] Note deprecations that affect your code +- [ ] Note new patterns or APIs you'll use after the upgrade + +For each breaking change: +- Where does this affect our code? +- What's the migration path? +- Is there a codemod available? + +### Search for usages + +- [ ] Grep for every API surface used (function names, import paths) +- [ ] Identify call sites that need attention +- [ ] Identify tests that may break + +For complex libraries, this can be the longest step. Be thorough. + +### Check the ecosystem + +- [ ] Plugins or related packages that depend on the library: do they support the new version? +- [ ] TypeScript types: are they updated? +- [ ] Documentation and examples in the wild: have they caught up? + +--- + +## Phase 3: Upgrade + +### Install + +- [ ] Update the version in package.json (or equivalent) +- [ ] Update related packages (plugins, types, etc.) to compatible versions +- [ ] Run install, generate fresh lockfile +- [ ] Verify the install completes without errors + +```bash +# Example +npm install library@^3.0.0 +``` + +### Initial build + +- [ ] Run the build +- [ ] Note every error and warning +- [ ] Don't fix anything yet; just inventory + +### Inventory the breakage + +Categorize each error: +- **Type errors:** API signatures changed +- **Import errors:** module structure changed +- **Runtime errors:** behavior changed +- **Test failures:** assumed behavior changed +- **Lint warnings:** patterns deprecated + +This list is your work plan. + +--- + +## Phase 4: Migrate + +### Apply codemods first + +If the library publishes codemods: + +```bash +npx codemod-name path/to/code +``` + +Codemods handle the mechanical parts (renamed APIs, restructured imports). They're not perfect, but they reduce toil. + +- [ ] Run codemods +- [ ] Review the diff (codemods can over-apply or under-apply) +- [ ] Commit the codemod changes separately + +### Fix manual issues + +For each remaining issue: +- [ ] Identify the root cause (what changed in the new version?) +- [ ] Apply the fix per the migration guide +- [ ] Verify tests pass for that area +- [ ] Commit incrementally (small commits, easy to revert) + +### Update tests + +- [ ] Tests using deprecated patterns: update to new patterns +- [ ] Tests that fail because behavior is different: investigate. Is the new behavior correct? +- [ ] Add tests for any new behavior you depend on + +### Update documentation + +- [ ] README references to the old version +- [ ] Internal docs and runbooks +- [ ] Comments referencing the old behavior + +--- + +## Phase 5: Verify + +### Local + +- [ ] All tests pass (unit, integration, E2E) +- [ ] Build succeeds without warnings (or with only acceptable warnings) +- [ ] Lint passes +- [ ] Type check passes (if typed) +- [ ] No console warnings in dev mode that weren't there before + +### Visual + +For UI-affecting libraries: +- [ ] Visual regression tests (Chromatic, Percy, or similar) clean +- [ ] Manual smoke test of key user flows +- [ ] Check on multiple browsers/devices + +### Performance + +- [ ] Bundle size: comparable or better +- [ ] Build time: comparable +- [ ] Runtime performance: comparable on key paths + +If bundle size or performance regresses meaningfully, investigate before merging. + +### Compatibility + +- [ ] Browser compatibility (if relevant) maintained +- [ ] Node version compatibility (if relevant) maintained +- [ ] Other dependencies still work with the new version + +--- + +## Phase 6: Stage + +For critical dependencies, don't go straight to production. + +- [ ] Deploy to a staging environment +- [ ] Run automated tests against staging +- [ ] Smoke-test critical flows manually +- [ ] Watch monitoring for new errors +- [ ] Watch performance metrics for regressions +- [ ] Let it bake for at least 24 hours (longer for critical systems) + +--- + +## Phase 7: Roll out + +Strategy depends on the dependency and the risk: + +### Low risk: standard deploy + +- [ ] Merge the PR +- [ ] Deploy to production +- [ ] Watch monitoring for the next few hours +- [ ] Be ready to rollback + +### Medium risk: feature flag or canary + +- [ ] Behind a feature flag if applicable +- [ ] Deploy with traffic splitting (1% to new, 99% to old, if infrastructure supports) +- [ ] Gradually increase traffic +- [ ] Watch metrics at each step + +### High risk: parallel run + +- [ ] Run old and new side by side +- [ ] Compare outputs +- [ ] Switch over only when confident + +--- + +## Phase 8: Monitor + +For at least one week post-rollout: + +- [ ] Error rates (compare to pre-upgrade baseline) +- [ ] Performance metrics +- [ ] User-reported issues +- [ ] Any unexpected behavior + +If issues appear: +- [ ] Triage by severity +- [ ] Fix forward (most common) +- [ ] Or rollback (if severe) +- [ ] Document the issues for the next upgrade + +--- + +## Phase 9: Document + +After the upgrade is stable: + +- [ ] Note the upgrade in the changelog +- [ ] Document any non-obvious migrations for future reference +- [ ] Update internal docs that referenced the old version +- [ ] If the upgrade was painful, write a note for next time +- [ ] Thank anyone who helped (especially open-source maintainers if they helped) + +--- + +## Common gotchas + +**Bundle size grows unexpectedly.** New version pulls in additional code or dependencies. Check the bundle analysis. + +**Tests that "passed but didn't actually run."** Test infrastructure breaks silently in some upgrades. Verify tests are running, not just exiting clean. + +**TypeScript types don't match runtime.** Sometimes types are updated but runtime isn't (or vice versa). Test runtime behavior, not just types. + +**Server-side rendering breaks.** New version uses browser-only APIs. Check SSR if applicable. + +**Tree-shaking changes.** Bundle includes more or different code. Verify what's actually shipped. + +**Peer dependency conflicts.** Library A wants version X, library B wants version Y. Resolve carefully; sometimes requires upgrading multiple in tandem. + +**Breaking changes in transitive dependencies.** The upgrade pulls in a new major of a transitive. The transitive's breaking changes affect you indirectly. + +**API changes that compile but behave differently.** Same function name, different default behavior. Read the changelog. + +**Migration guide assumes specific framework or stack.** If you use the library in a non-standard way, the guide may not cover your case. Adapt. + +--- + +## When to abort + +It's OK to abort an upgrade. Better to abort than ship a broken version. + +Abort triggers: +- Migration effort blowing past estimate by 5x+ +- Discovering critical incompatibilities mid-migration +- Finding that the new version has bugs blocking your use case +- Realizing the dependency itself is the problem (consider replacement) + +After aborting: +- Keep the branch around for reference +- Document what you learned +- Schedule a retry when conditions are better, or pivot to replacement + +--- + +## Reference for next time + +After every major upgrade, capture: +- Total effort (hours) +- Surprises encountered +- Things that worked well +- Things to do differently + +This becomes input to estimating the next major upgrade. Major upgrades happen periodically; the team gets better at them with practice and notes. diff --git a/dist/pi/.agents/skills/design-standards/SKILL.md b/dist/pi/.agents/skills/design-standards/SKILL.md new file mode 100644 index 0000000..ee3d5dd --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/SKILL.md @@ -0,0 +1,213 @@ +--- +name: design-standards +description: "Apply production-grade design standards when building or reviewing pages, components, or UI. Use this skill whenever the user asks to build a page, design a component, lay out a section, review the UI, fix the layout, or check design quality. Triggers on build a page, create a component, design a section, hero, card, CTA, layout, review the UI, fix the design, design system, design tokens, spacing, typography scale, button standards, mobile design. Also triggers for any production design decision where contrast, accessibility, spacing, or visual hierarchy matters." +category: design +catalog_summary: "Production-grade page and component design standards" +display_order: 2 +--- + +# Design Standards + +Production design standards for any web project. Stack-agnostic. Tool-agnostic. Covers tokens, contrast, hierarchy, spacing, mobile rules, and the pre-ship checklist. + +This skill complements `brand-identity` (which defines the visual system) and `brand-style-guide` (which documents it). This skill is for the day-to-day work of applying those standards in real components and pages. + +--- + +## When to use + +- Building a new page, section, or component +- Reviewing UI for quality, accessibility, or consistency +- Setting up design tokens for a new project +- Fixing layout, contrast, or hierarchy issues +- Establishing a button or form standard +- Pre-ship design review + +## When NOT to use + +- Defining a brand identity from scratch (use `brand-identity`) +- Documenting a finished brand system (use `brand-style-guide`) +- Building a formal component library (use `design-system`) +- Frontend code architecture (use `frontend-component-build`) +- Accessibility-only audits with WCAG remediation (use `accessibility-audit`) + +--- + +## Required inputs + +- The page or component being built or reviewed +- The brand's design tokens (colors, type, spacing) - or willingness to define them +- The target devices and viewports + +If brand tokens are undefined, define a working set first using the template in [`references/design-tokens-template.md`](references/design-tokens-template.md). + +--- + +## The framework: 6 standards + +Six standards apply to every piece of UI. Hold the line on these and most design problems disappear. + +### 1. Design tokens + +Every project needs tokens defined before any UI gets built. Tokens are the source of truth. + +**Color tokens** (minimum): +- Primary brand color +- Primary hover (typically 15 to 25 percent darker) +- Background variants (surface, alt-section, hero/dark, footer) +- Text scale (heading, body, muted, on-dark) +- Semantic (success, warning, error, info) + +**Spacing tokens:** +- A consistent scale (e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96) +- Page max-width +- Section vertical padding (large, medium, small) +- Card padding +- Grid gaps + +**Type tokens:** +- Display, H1 through H4, body large, body, small, caption +- Each with size, weight, line height, letter spacing +- Font fallback stacks + +**Radius tokens:** +- Tight (cards, badges) +- Standard (buttons, inputs) +- Round (avatars, pill buttons) + +Document the tokens once. Reference them everywhere. Hardcoded values are technical debt. + +### 2. WCAG AA contrast (non-negotiable) + +Contrast is not a preference. It is a baseline. A design that fails AA is broken, regardless of how it looks to designers with full vision. + +| Element | Required ratio | +|---|---| +| Normal body text | 4.5:1 | +| Large text (18pt regular or 14pt bold) | 3:1 | +| UI components and graphical elements | 3:1 | + +Common failures to avoid: +- Light gray body text on white that calculates to 2 to 4:1 +- Brand color used for body text without a darker variant +- Light borders on form fields that compute under 3:1 +- Bright orange or yellow on white at small sizes + +For the math, the contrast checker, and brand-color strategies, see `brand-identity/references/contrast-and-accessibility.md`. + +### 3. Visual hierarchy + +A well-designed page has a clear scan order. Hierarchy comes from: + +- **Size.** The largest element gets noticed first. +- **Weight.** Bold beats regular at the same size. +- **Color.** Saturated beats neutral. High-contrast beats low. +- **Spacing.** What sits alone gets emphasis. What gets crowded recedes. +- **Position.** Top-left and center get weight. Edges and corners recede. + +Apply hierarchy intentionally. Every visual element should be reachable through the hierarchy. If three things compete for primary attention, none of them wins. + +**Common failures:** +- Multiple elements styled as the "primary" CTA (creates ambiguity) +- Body text and headlines too close in size +- Hero image fighting the hero text for attention +- Icon, headline, and image at similar visual weight + +### 4. Spacing and rhythm + +Spacing is what separates a polished layout from a cluttered one. + +**Rules:** +- Use the spacing scale, not arbitrary values +- Related elements sit closer together than unrelated ones (proximity principle) +- Section breathing room: minimum 64px desktop, 48px mobile +- Card padding: minimum 24px desktop, 16px mobile +- Form field spacing: minimum 16px between fields +- Touch targets: minimum 44 by 44 pixels + +**Common failures:** +- Inconsistent spacing within similar contexts (one card has 24px padding, the next has 32px) +- Cramped sections that bleed into each other +- Touch targets under 44 pixels on mobile +- Headline butted directly against subheadline with no rhythm + +### 5. Mobile rules + +Most users are on mobile. Designing for desktop first guarantees mobile failures. + +**Standards:** +- Test on a 375 to 390 pixel viewport before declaring complete +- All interactive elements minimum 44 by 44 pixels +- Sticky bottom bars: page wrapper needs bottom padding equal to bar height +- No fixed pixel widths without max-width constraint +- Text never smaller than 14 pixels for body content +- Tap targets get 8 pixels of spacing minimum on all sides +- Modal and popover content scrolls; body locks +- Form inputs: at least 16px text size to prevent iOS auto-zoom + +**Common failures:** +- Designs that work in browser dev tools but break on real devices +- Sticky navigation eating 80px of viewport without compensation +- Horizontal scroll appearing because of one over-wide element +- Tap targets that are visually fine but impossibly close to other tap targets + +### 6. Component consistency + +The same thing should look the same everywhere. Variations should be intentional. + +**Common consistency principles:** +- Buttons: one primary style, one secondary style, one ghost style. Not five. +- Cards: one base card pattern with variants. Not bespoke cards per page. +- Icons: one stroke weight, one corner style across the icon set +- Avatars and brand marks: one shape rule (rounded-lg or fully round, pick one and stick to it) +- Form inputs: one set of input states (default, focus, error, disabled) used everywhere + +**Common failures:** +- Three different "primary buttons" used inconsistently across pages +- Some cards with rounded-2xl corners, others with rounded-xl +- Iconography style drifting between sections +- Brand avatar that switches between square and round depending on the page + +--- + +## Workflow + +1. **Confirm tokens.** If tokens are not yet defined, define a working set first. Document them. +2. **Sketch hierarchy.** Before writing markup, identify the primary action, secondary actions, and supporting content. Confirm the scan order makes sense. +3. **Build mobile-first.** Lay out for the smallest target viewport before scaling up. +4. **Apply tokens.** All values come from the token set. No hardcoded colors, sizes, or spacing. +5. **Run contrast checks.** Every text-on-background combination passes AA. Every UI element passes 3:1. +6. **Test at viewport breakpoints.** 375, 768, 1024, 1440 minimum. Confirm nothing breaks. +7. **Run the pre-ship checklist** in [`references/preship-checklist.md`](references/preship-checklist.md). + +--- + +## Failure patterns + +- **Designing without tokens.** Hardcoded colors and spacing. Hard to maintain. Inconsistent at scale. +- **Skipping contrast checks.** Especially on brand colors used for text. Most brand colors fail AA. +- **Designing only for desktop.** Mobile reveals every layout sin. Test mobile first or last, but always. +- **Rounded-everything.** Treating "modern" as "rounded all the things." Rounded corners are a tool, not a default. +- **Visual hierarchy mush.** Three things competing as primary. Reader does not know where to look. +- **Touch target violations.** Visually nice 32px buttons that fail finger ergonomics on real devices. +- **Component drift.** Each page rebuilds the card or button from scratch. Design system erodes. + +--- + +## Output format + +This skill produces design decisions and review notes more than artifacts. Outputs include: + +- **Design tokens file** (when starting a project): `design-tokens.md` or equivalent +- **Component or page review**: markdown notes scored against the 6 standards, with specific fixes +- **Pre-ship checklist results**: pass/fail across the checklist with notes + +When generating component code (HTML, CSS, framework-specific markup), the SKILL.md remains stack-agnostic. Stack-specific patterns live in reference files. + +--- + +## Reference files + +- [`references/design-tokens-template.md`](references/design-tokens-template.md) - Template for setting up tokens for any project. +- [`references/preship-checklist.md`](references/preship-checklist.md) - Final design review checklist before shipping. +- [`references/tailwind-patterns.md`](references/tailwind-patterns.md) - Optional. Tailwind-specific component patterns (hero, cards, buttons, data rows) for projects on that stack. diff --git a/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md b/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md new file mode 100644 index 0000000..7e96765 --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md @@ -0,0 +1,248 @@ +# Design Tokens Template + +Tokens are the source of truth for color, spacing, typography, and other design decisions. Define them once at the start of the project. Reference them everywhere. + +This template is stack-agnostic. Adapt the syntax to your project: CSS custom properties, Tailwind config, design system JSON, Style Dictionary, Figma variables - the values stay the same. + +--- + +## Color tokens + +### Primary (brand) + +``` +brand/primary #XXXXXX /* signature brand color */ +brand/primary-hover #XXXXXX /* 15-25% darker, for hover states */ +brand/primary-text #XXXXXX /* darker variant if primary fails AA on white */ +``` + +### Background + +``` +bg/surface #FFFFFF /* default page background */ +bg/surface-alt #F9FAFB /* alternating section background */ +bg/hero #1A1D23 /* dark section for heroes, footers */ +bg/footer #111827 /* footer specifically */ +``` + +### Text scale + +Document each with the contrast ratio against the background it sits on. + +``` +text/heading #111827 /* heading on white = 16.9:1 */ +text/body #374151 /* body on white = 10.3:1 */ +text/muted #4B5563 /* muted on white = 7.6:1 PASS AA */ +text/subtle #6B7280 /* subtle on white = 5.1:1 PASS AA */ +text/on-dark #FFFFFF /* white on hero bg = 15.8:1 */ +text/on-dark-muted #D1D5DB /* on hero bg = 11.4:1 */ +``` + +Avoid going lighter than the muted/subtle colors above on white. Lighter grays fail AA. + +### Semantic + +``` +semantic/success #059669 /* on white = 4.5:1 PASS AA */ +semantic/warning #D97706 /* on white = 4.5:1 PASS AA */ +semantic/error #DC2626 /* on white = 4.7:1 PASS AA */ +semantic/info #2563EB /* on white = 5.6:1 PASS AA */ +``` + +For each semantic color, also define a tinted background and a darker text variant for badges and alert blocks. + +### Border and divider + +``` +border/default #E5E7EB /* default borders, subtle dividers */ +border/strong #D1D5DB /* form fields, interactive borders */ +border/focus #2563EB /* focus rings */ +``` + +--- + +## Spacing tokens + +A consistent scale prevents arbitrary values. + +``` +space/0 0 +space/1 4px +space/2 8px +space/3 12px +space/4 16px +space/5 20px +space/6 24px +space/8 32px +space/10 40px +space/12 48px +space/16 64px +space/20 80px +space/24 96px +space/32 128px +``` + +### Layout-specific spacing + +``` +layout/page-max-width 1280px (or 1440px for spacious designs) +layout/page-padding-x 16px mobile / 24px tablet / 32px desktop +layout/section-py-large 80px desktop / 64px mobile +layout/section-py-medium 48px desktop / 32px mobile +layout/section-py-small 32px desktop / 24px mobile +layout/card-padding 24px to 32px +layout/grid-gap 24px to 32px +``` + +--- + +## Typography tokens + +### Font families + +``` +font/display "[Display typeface]", system-ui, sans-serif +font/body "[Body typeface]", system-ui, sans-serif +font/mono "[Mono typeface]", ui-monospace, monospace +``` + +### Type scale + +| Token | Size | Weight | Line height | Letter spacing | Use | +|---|---|---|---|---|---| +| type/display-1 | 64px | 700 | 1.0 | -0.02em | Hero headlines | +| type/display-2 | 48px | 700 | 1.05 | -0.01em | Section heroes | +| type/h1 | 36px | 700 | 1.1 | 0 | Page titles | +| type/h2 | 28px | 600 | 1.2 | 0 | Section titles | +| type/h3 | 22px | 600 | 1.3 | 0 | Sub-sections | +| type/h4 | 18px | 600 | 1.4 | 0 | Component titles | +| type/body-large | 18px | 400 | 1.5 | 0 | Lead paragraphs | +| type/body | 16px | 400 | 1.6 | 0 | Default body | +| type/body-small | 14px | 400 | 1.5 | 0 | Captions, metadata | +| type/caption | 12px | 400 | 1.4 | 0.01em | Footnotes, labels | +| type/eyebrow | 12px | 600 | 1.4 | 0.08em | Uppercase eyebrows | + +### Mobile adjustments + +Mobile typography is typically 1 to 2 steps smaller for display sizes: + +``` +display-1: 64px desktop → 40px mobile +display-2: 48px desktop → 32px mobile +h1: 36px desktop → 28px mobile +``` + +Body sizes stay the same on mobile; never go below 14px. + +--- + +## Radius tokens + +``` +radius/none 0 +radius/sm 4px /* small badges, tags */ +radius/md 8px /* default for inputs */ +radius/lg 12px /* buttons, alerts */ +radius/xl 16px /* cards (small) */ +radius/2xl 20px /* cards (default) */ +radius/3xl 24px /* cards (prominent), modals */ +radius/full 9999px /* pill buttons, fully rounded */ +``` + +### Conventions for shapes + +``` +buttons (default): radius/full (pill) OR radius/lg (rounded rect) +buttons (form/utility): radius/md +inputs: radius/md or radius/lg +cards: radius/2xl +icon containers: radius/xl (NOT radius/full unless avatar) +avatars (people): radius/full +brand avatars/logos: radius/lg (matches favicon convention) +modals: radius/3xl (top corners on mobile sheets) +``` + +Pick the conventions, document them, and stick to them. Inconsistent radius is one of the most common visual drift patterns. + +--- + +## Shadow tokens + +``` +shadow/none none +shadow/sm 0 1px 2px rgba(0,0,0,0.05) +shadow/md 0 4px 6px rgba(0,0,0,0.08) +shadow/lg 0 10px 15px rgba(0,0,0,0.10) +shadow/xl 0 20px 25px rgba(0,0,0,0.10) +shadow/2xl 0 25px 50px rgba(0,0,0,0.15) +``` + +### Shadow conventions + +``` +default cards: shadow/sm +hover state cards: shadow/md +elevated content: shadow/lg +modals/dropdowns: shadow/xl +``` + +--- + +## Z-index tokens + +A documented z-index scale prevents the "9999 wars." + +``` +z/below -1 +z/base 0 +z/raised 10 /* sticky elements, fixed nav */ +z/dropdown 20 /* popovers, dropdowns */ +z/overlay 30 /* page-level overlays, scrims */ +z/modal 40 /* modals, dialogs */ +z/toast 50 /* toasts, top-of-everything notifications */ +``` + +--- + +## Motion tokens + +``` +motion/duration-fast 100ms /* hover state, simple feedback */ +motion/duration-base 200ms /* most UI transitions */ +motion/duration-slow 300ms /* enter/exit animations */ +motion/duration-slower 500ms+ /* dramatic brand moments */ + +motion/ease-default cubic-bezier(0.4, 0, 0.2, 1) +motion/ease-in cubic-bezier(0.4, 0, 1, 1) +motion/ease-out cubic-bezier(0, 0, 0.2, 1) +motion/ease-bounce cubic-bezier(0.68, -0.55, 0.27, 1.55) +``` + +Always provide `prefers-reduced-motion` alternatives that disable or shorten animations for users who request it. + +--- + +## Breakpoints + +``` +breakpoint/sm 640px +breakpoint/md 768px +breakpoint/lg 1024px +breakpoint/xl 1280px +breakpoint/2xl 1536px +``` + +Test the design at viewport widths matching each breakpoint, and at 375px (smaller phone), 390px (default iPhone), and 1440px (default laptop). + +--- + +## How to use this template + +1. **Copy** the structure into your project. +2. **Fill in values** per the brand identity. +3. **Verify contrast** for every text/background combination using a contrast checker. +4. **Document edge cases** (e.g., the darker brand variant for text contexts). +5. **Reference everywhere.** No hardcoded values in components. +6. **Update once.** When tokens change, the whole product reflects the change. + +The token file is canonical. Anything in the codebase using a hardcoded value instead of a token is technical debt waiting to surface. diff --git a/dist/pi/.agents/skills/design-standards/references/preship-checklist.md b/dist/pi/.agents/skills/design-standards/references/preship-checklist.md new file mode 100644 index 0000000..14cd7fd --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/preship-checklist.md @@ -0,0 +1,180 @@ +# Pre-Ship Design Checklist + +Run before declaring any page or component complete. Most production design defects come from skipping these. + +--- + +## Tokens and consistency + +- [ ] All colors come from the token set (no hardcoded hex values) +- [ ] All spacing comes from the spacing scale (no arbitrary px values) +- [ ] All typography uses defined type tokens +- [ ] All radii use the defined radius tokens +- [ ] Shadows use defined shadow tokens +- [ ] No more than one variant per component type (e.g., one primary button style across the page) + +--- + +## Contrast (WCAG AA) + +- [ ] All body text passes 4.5:1 against its background +- [ ] All large text passes 3:1 +- [ ] All UI elements (icons, borders, focus rings) pass 3:1 +- [ ] Brand colors used for text use the darker text variant if the signature color fails +- [ ] No light gray text under #6B7280 on white backgrounds +- [ ] Dark mode (if implemented) tested against dark surfaces, not just light + +Use a contrast checker for every pairing. Visual judgment is unreliable. + +--- + +## Visual hierarchy + +- [ ] One clear primary action per page (one primary CTA) +- [ ] Secondary actions visually subordinate to primary +- [ ] Headline larger and heavier than body text by enough to be unambiguous +- [ ] Section breaks visible without effort (spacing or background change) +- [ ] Images do not visually compete with primary content + +--- + +## Typography + +- [ ] Exactly one H1 per page +- [ ] No skipped header levels (H2 followed by H4) +- [ ] Body text minimum 14px (16px preferred) +- [ ] Line length controlled (45 to 75 characters per line for body text) +- [ ] Line height appropriate (1.4 to 1.6 for body, 1.0 to 1.2 for display) +- [ ] No fake italics or fake bold (use real font weights) + +--- + +## Spacing and rhythm + +- [ ] Consistent padding inside same-type containers (all cards, all sections) +- [ ] Section breathing room: 64px+ desktop, 48px+ mobile +- [ ] Form fields spaced minimum 16px apart vertically +- [ ] Related elements visually grouped (proximity principle) +- [ ] No cramped sections that bleed into each other + +--- + +## Buttons and CTAs + +- [ ] Primary button uses brand primary color +- [ ] Hover state visible and distinct +- [ ] Focus state visible (focus ring or equivalent) +- [ ] Disabled state visible and accessible +- [ ] Touch target minimum 44 by 44 pixels +- [ ] Button text descriptive (not "click here" or "submit") + +--- + +## Forms + +- [ ] Every input has a visible label (placeholder is not a label) +- [ ] Required fields marked clearly +- [ ] Error states have text descriptions, not just color +- [ ] Help text positioned below or beside the field, not as placeholder +- [ ] Input height accommodates touch (minimum 44px) +- [ ] Form inputs use 16px+ text on iOS to prevent zoom + +--- + +## Images and media + +- [ ] All meaningful images have descriptive alt text +- [ ] Decorative images have empty alt (`alt=""`) +- [ ] Images have explicit width and height to prevent layout shift +- [ ] Modern formats used where supported (WebP, AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] No images stretched or pixelated due to wrong sizing + +--- + +## Interactive elements + +- [ ] All interactive elements have hover states (where pointer is supported) +- [ ] Focus rings visible (do not use `outline: none` without a replacement) +- [ ] Tap targets minimum 44 by 44 pixels +- [ ] Tap targets at least 8 pixels of spacing on all sides from other tap targets +- [ ] Cursor styles correct (`pointer` for clickable, `text` for inputs, etc.) + +--- + +## Mobile (375 to 390 pixel viewport) + +- [ ] Tested on real device or device-mode in browser +- [ ] No horizontal scroll +- [ ] No fixed-width elements breaking layout +- [ ] Sticky bottom bars do not overlap content (page wrapper has bottom padding) +- [ ] Sticky top bars do not eat critical content +- [ ] Mobile menu works on touch +- [ ] All text remains readable (no truncated headlines) +- [ ] Tap targets remain 44px minimum + +--- + +## Tablet (768 to 1024 pixel viewport) + +- [ ] Layout transitions cleanly between mobile and desktop breakpoints +- [ ] No awkward in-between sizing +- [ ] Multi-column layouts adapt sensibly + +--- + +## Desktop (1280+ pixel viewport) + +- [ ] Page max-width prevents content from stretching too wide +- [ ] Typography does not break (line lengths still controlled) +- [ ] Whitespace remains balanced + +--- + +## Performance signals (visual) + +- [ ] No visible layout shift after initial render +- [ ] Images load progressively (no blank-then-pop) +- [ ] No flash of unstyled text (FOUT) for primary fonts +- [ ] No render-blocking elements above the fold + +(For deep performance audits, use `performance-optimization`.) + +--- + +## Brand and consistency + +- [ ] Logo placed correctly (per brand-style-guide rules) +- [ ] Brand colors used per brand-style-guide rules +- [ ] Imagery direction matches brand-style-guide +- [ ] Voice (in any UI text) matches brand-voice +- [ ] No off-brand stock photography or generic illustrations + +--- + +## Accessibility (basic checks; for deeper audits use `accessibility-audit`) + +- [ ] Page operable by keyboard alone +- [ ] Logical tab order +- [ ] Form fields have associated labels (`for`/`id` or `aria-labelledby`) +- [ ] Buttons and links use semantic elements (not `<div onClick>`) +- [ ] Skip links present for long pages +- [ ] Page language declared (`<html lang="...">`) + +--- + +## Pre-launch sanity + +- [ ] No placeholder text remaining ("Lorem ipsum," "TODO," "[Replace this]") +- [ ] No broken images +- [ ] No broken links (test 5 random links) +- [ ] No console errors in browser dev tools +- [ ] No accessibility errors in browser audit tools + +--- + +## Sign-off + +When all boxes check, the design is ready to ship. If any box fails, document the failure, decide whether it is a launch blocker, and either fix or file a known-issue ticket before shipping. + +The checklist is the floor, not the ceiling. Great design exceeds it. diff --git a/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md b/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md new file mode 100644 index 0000000..7b8b004 --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md @@ -0,0 +1,287 @@ +# Tailwind Component Patterns + +Optional reference. Tailwind-specific component patterns for projects on that stack. The principles in [`SKILL.md`](../SKILL.md) are stack-agnostic; this file translates them into Tailwind utilities. + +If you are not using Tailwind, skip this file. The patterns translate to any utility framework or CSS approach with minor changes. + +--- + +## Page wrapper + +The standard container pattern: + +```jsx +<main className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> + {/* page content */} +</main> +``` + +Token equivalents: +- `max-w-7xl` = page max width (1280px) +- `mx-auto` = horizontal centering +- `px-4 sm:px-6 lg:px-8` = responsive horizontal padding + +For wider designs, swap `max-w-7xl` for `max-w-[1440px]`. + +--- + +## Section spacing + +```jsx +{/* Large section (heroes, major content) */} +<section className="py-20 md:py-28"> + +{/* Medium section (most content) */} +<section className="py-12 md:py-16"> + +{/* Small section (compact content) */} +<section className="py-8 md:py-12"> +``` + +Always include the mobile-first variant. Mobile sections use shorter padding to preserve viewport efficiency. + +--- + +## Dark hero + +```jsx +<section className="bg-gray-900 py-20 md:py-28"> + <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center"> + {/* Breadcrumb - text-gray-300 minimum on dark for AA */} + <nav className="text-sm text-gray-300 mb-6" aria-label="Breadcrumb"> + <a href="/" className="hover:text-white transition-colors">Home</a> + <span className="mx-2" aria-hidden="true">/</span> + <span className="text-white">Current Page</span> + </nav> + + {/* Eyebrow */} + <p className="text-xs font-semibold uppercase tracking-wider text-blue-400 mb-3"> + Section Label + </p> + + {/* H1 - exactly one per page */} + <h1 className="text-4xl md:text-6xl font-extrabold tracking-tight text-white mb-4"> + Main <span className="text-blue-400">Headline</span> + </h1> + + {/* Supporting */} + <p className="text-lg text-gray-300 max-w-2xl mx-auto"> + Supporting description that gives context. + </p> + </div> +</section> +``` + +Contrast notes: +- White on `bg-gray-900` = 17.4:1 PASS +- `text-gray-300` on `bg-gray-900` = 11.2:1 PASS AA +- `text-gray-400` on `bg-gray-900` = 7.6:1 PASS AA (still readable) +- `text-gray-500` on `bg-gray-900` = 5.5:1 PASS AA borderline; prefer 300 or 400 for body on dark + +--- + +## Feature card grid + +```jsx +<div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6"> + <div className="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm hover:shadow-md transition-shadow"> + {/* Icon container - rounded-xl, NOT rounded-full unless avatar */} + <div className="w-10 h-10 rounded-xl bg-blue-50 text-blue-600 flex items-center justify-center mb-4"> + <Icon className="w-5 h-5" /> + </div> + <h3 className="font-semibold text-gray-900 mb-2">Card Title</h3> + <p className="text-sm text-gray-600">Card description that explains the feature.</p> + </div> + {/* repeat */} +</div> +``` + +Conventions: +- `rounded-2xl` for cards (consistent radius across all cards on the site) +- `rounded-xl` for icon containers (not `rounded-full` unless it's an avatar) +- `text-gray-600` is the muted-text floor on white (passes AA at 7.6:1) + +--- + +## Data row (key-value display) + +```jsx +<div className="flex justify-between items-center rounded-xl bg-gray-50 px-4 py-3 text-sm"> + <span className="text-gray-600 font-medium">Label</span> + <span className="font-semibold text-gray-900">Value</span> +</div> +``` + +Stack rows in a `space-y-2` container for vertically grouped data. + +--- + +## Inline CTA banner + +```jsx +<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 rounded-xl border border-blue-100 bg-blue-50 px-5 py-4"> + <div> + <p className="font-semibold text-gray-900">CTA Headline</p> + <p className="text-sm text-gray-600 mt-0.5">Supporting context</p> + </div> + <a + href="#" + className="shrink-0 bg-blue-600 hover:bg-blue-700 text-white text-sm font-semibold px-4 py-2.5 rounded-full transition-colors whitespace-nowrap" + > + Action Text + </a> +</div> +``` + +The `flex-col sm:flex-row` pattern stacks on mobile, sits side-by-side on tablet+. Standard across all banner-style CTAs. + +--- + +## Author byline + +```jsx +<div className="flex items-center gap-3"> + {/* Brand/author avatar - rounded-lg matches favicon shape */} + <div className="w-9 h-9 rounded-lg bg-blue-600 flex items-center justify-center text-white text-sm font-bold flex-shrink-0"> + {authorInitial} + </div> + <div className="min-w-0"> + <a + href={`/author/${slug}`} + className="text-sm font-medium text-gray-900 hover:text-blue-700 transition-colors block truncate" + > + {authorName} + </a> + <p className="text-xs text-gray-600 truncate">{authorRole}</p> + </div> +</div> +``` + +Convention: brand and author identifiers use `rounded-lg`, not `rounded-full`. Reserve `rounded-full` for actual person photographs (people-photo avatars). + +--- + +## Buttons + +```jsx +{/* Primary - pill shape, brand color */} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold transition-colors"> + Primary Action +</a> + +{/* Secondary - outline */} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full border border-blue-600 text-blue-600 hover:bg-blue-50 font-semibold transition-colors"> + Secondary Action +</a> + +{/* Ghost - text only */} +<a className="inline-flex items-center gap-2 px-4 py-2 text-blue-600 hover:text-blue-700 font-semibold transition-colors"> + Ghost Action +</a> + +{/* Disabled state */} +<button + disabled + className="px-6 py-3 rounded-full bg-gray-200 text-gray-500 font-semibold cursor-not-allowed" +> + Disabled +</button> +``` + +Pick pill (`rounded-full`) or rounded-rect (`rounded-lg`) for buttons. Use one consistently across the entire site. + +--- + +## Form inputs + +```jsx +{/* Input with label */} +<div className="space-y-1.5"> + <label htmlFor="email" className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + id="email" + type="email" + className="w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-base shadow-sm focus:border-blue-600 focus:ring-2 focus:ring-blue-600/20 focus:outline-none" + placeholder="you@example.com" + /> + <p className="text-xs text-gray-600">We'll never share your email.</p> +</div> + +{/* Error state */} +<div className="space-y-1.5"> + <label className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + type="email" + aria-invalid="true" + aria-describedby="email-error" + className="w-full rounded-lg border border-red-500 px-3.5 py-2.5 text-base shadow-sm focus:border-red-600 focus:ring-2 focus:ring-red-600/20 focus:outline-none" + /> + <p id="email-error" className="text-xs text-red-600"> + Please enter a valid email address. + </p> +</div> +``` + +Notes: +- Always use `text-base` (16px) on inputs to prevent iOS zoom on focus +- `py-2.5` gives ~44px height with text, hitting the touch target minimum +- Error states need text, not just color (color blindness consideration) + +--- + +## Mobile sticky bar + +```jsx +<> + {/* Page wrapper needs bottom padding to compensate for the bar */} + <main className="pb-20 md:pb-0"> + {/* page content */} + </main> + + {/* Sticky bar - mobile only */} + <div className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-200 px-4 py-3 md:hidden z-30"> + <a + href="#" + className="block w-full text-center px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold" + > + Mobile CTA + </a> + </div> +</> +``` + +The `pb-20 md:pb-0` on the wrapper is critical. Without it, the sticky bar covers the bottom of the page content. + +--- + +## Common Tailwind contrast values + +Quick reference for which gray text colors pass AA on white: + +| Class | Hex | Contrast on white | AA pass | +|---|---|---|---| +| `text-gray-300` | #D1D5DB | 1.6:1 | FAIL (decorative only) | +| `text-gray-400` | #9CA3AF | 2.85:1 | FAIL | +| `text-gray-500` | #6B7280 | 4.6:1 | PASS (borderline; prefer 600) | +| `text-gray-600` | #4B5563 | 7.6:1 | PASS | +| `text-gray-700` | #374151 | 10.3:1 | PASS | +| `text-gray-800` | #1F2937 | 14.6:1 | PASS | +| `text-gray-900` | #111827 | 16.9:1 | PASS | + +Use `text-gray-600` as the floor for body text on white. Anything lighter requires verification against the specific background. + +For dark backgrounds: + +| Class | Hex | Contrast on `bg-gray-900` | AA pass | +|---|---|---|---| +| `text-white` | #FFFFFF | 17.4:1 | PASS | +| `text-gray-300` | #D1D5DB | 11.2:1 | PASS | +| `text-gray-400` | #9CA3AF | 7.6:1 | PASS | +| `text-gray-500` | #6B7280 | 5.5:1 | PASS borderline | +| `text-gray-600` | #4B5563 | 3.8:1 | FAIL for body | + +Use `text-gray-300` as the floor for body text on `bg-gray-900`. Reserve lighter grays for headlines and primary content. diff --git a/dist/pi/.agents/skills/design-system/SKILL.md b/dist/pi/.agents/skills/design-system/SKILL.md new file mode 100644 index 0000000..9ae0401 --- /dev/null +++ b/dist/pi/.agents/skills/design-system/SKILL.md @@ -0,0 +1,202 @@ +--- +name: design-system +description: "Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer." +category: design +catalog_summary: "Component library, design tokens, design system documentation" +display_order: 1 +--- + +# Design System + +Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer. + +This skill is for building the system. For applying a system to specific pages or components, use `design-standards`. For brand visual identity, use `brand-identity`. + +--- + +## When to use + +- Building a design system from scratch +- Auditing an existing system for gaps or fragmentation +- Defining design tokens at the system level +- Structuring a component library +- Establishing contribution and governance models +- Migrating from ad-hoc components to a documented system + +## When NOT to use + +- Designing a single page or component (use `design-standards`) +- Brand identity work (use `brand-identity`) +- Component-level frontend implementation (use `frontend-component-build`) +- Pure design documentation for marketing (use `brand-style-guide`) + +--- + +## Required inputs + +- The brand identity (tokens, voice, imagery direction) +- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools) +- The team and its working tools (Figma, code framework, doc platform) +- Existing components, even if undocumented +- Constraints (accessibility requirements, performance targets, browser support) + +If brand identity is undefined, run `brand-identity` first. + +--- + +## The framework: 5 layers + +A complete design system has five layers, stacked. Each layer feeds the layer above. + +### 1. Foundations (tokens) + +The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints. + +**Why this layer matters:** +- Tokens are the source of truth for everything above +- Token changes propagate everywhere automatically +- Without tokens, the system has no foundation + +**Output:** +- A documented token set (see `design-standards/references/design-tokens-template.md`) +- Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.) +- Token implementation in Figma (variables and styles) +- A primer doc explaining what tokens to use when + +**Common patterns:** +- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: `color-blue-600` (base) + `color-text-link` (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base. + +### 2. Elements (atoms) + +The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers. + +**Per element, document:** +- Visual variants (primary, secondary, ghost, etc.) +- Size variants (small, medium, large) +- States (default, hover, focus, active, disabled, error, loading) +- Anatomy (the parts that make up the element) +- Spacing and proportions +- Accessibility (keyboard support, screen reader behavior, ARIA) +- Code usage (props, examples) + +**Output:** +- Element library in Figma +- Element components in code +- Per-element documentation + +### 3. Components (molecules + organisms) + +Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers. + +**Per component:** +- Composition (which elements it uses) +- Variants and configurations +- Use cases (when to reach for this vs. an alternative) +- Layout behavior (responsive, contained, full-bleed) +- Anti-patterns (when NOT to use it) + +**Output:** +- Component library +- Per-component documentation with usage guidance + +### 4. Patterns (templates) + +Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections. + +**Per pattern:** +- The structure and components used +- The user journey it supports +- Layout grid and spacing +- Responsive behavior +- Variants (e.g., "with sidebar," "fullscreen," "modal") + +**Output:** +- Pattern library or page templates +- Documentation showing complete examples + +### 5. Documentation and governance + +How the system gets used, contributed to, and maintained. + +**Documentation includes:** +- Getting started guide for new team members +- How to use vs. how to extend +- Contribution model +- Versioning policy +- Migration paths when breaking changes happen +- Decision log for major system choices + +**Governance includes:** +- Who owns the system (a team or rotation) +- How new components get proposed and approved +- How conflicts get resolved +- How the system evolves vs. stays stable +- Cadence of review and updates + +--- + +## Workflow + +### For a new design system + +1. **Inventory the existing UI.** Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope. +2. **Identify the duplicates.** Same component built 5 different ways across the product. These are your high-value consolidation targets. +3. **Define foundations.** Token set, with both base and semantic layers. Document each. +4. **Audit elements.** From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set. +5. **Build the element library.** Figma + code. Document each element. +6. **Identify priority components.** The 10 to 15 components that appear most often. Build those first. +7. **Document patterns.** Page-level templates that show the system in use. +8. **Establish governance.** Owner, contribution model, review cadence. +9. **Roll out.** Migrate existing surfaces to the system progressively. + +### For an existing design system audit + +1. **Inventory what exists.** What's documented, what's in Figma, what's in code, what's actually used in production. +2. **Map gaps.** Where the system is incomplete. Where teams build outside the system because the system can't serve their need. +3. **Map fragmentation.** Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams). +4. **Identify decay.** Components that have drifted from the documented standard. +5. **Prioritize fixes.** Foundation gaps first. High-use component drift second. Rarely-used component cleanup last. +6. **Plan rollout.** Major changes need migration paths. + +--- + +## Failure patterns + +- **Building the system before the brand is set.** Tokens depend on brand. Set brand first. +- **Atoms-up extreme.** Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively. +- **One-person system.** A system without governance fails as soon as the original designer leaves. Establish ownership early. +- **Stale documentation.** A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs. +- **Versioning everything.** Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes. +- **Adopting "atomic design" dogmatically.** Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism. +- **Building in a vacuum.** A system designed without input from the teams using it gets ignored. Co-design with consumers. +- **No deprecation path.** Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly. +- **Token explosion.** Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have. + +--- + +## Output format + +A design system has multiple deliverables. Typically: + +- **Documentation site** (Notion, dedicated site, GitHub Pages, Storybook addon, etc.) +- **Figma library** (or equivalent design tool) +- **Code library** (npm package, monorepo workspace, copy-paste components) +- **Decision log** (system-level decisions and the reasoning) +- **Roadmap and changelog** + +For a design system audit, output is a markdown report at `design-system-audit.md`: + +1. Inventory of what exists (foundations, elements, components, patterns) +2. Gap analysis +3. Fragmentation analysis +4. Drift analysis +5. Prioritized remediation plan +6. Governance recommendations + +--- + +## Reference files + +- [`references/system-architecture.md`](references/system-architecture.md) - The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs. +- [`references/system-audit-template.md`](references/system-audit-template.md) - Template for auditing an existing design system. +- [`references/governance-playbook.md`](references/governance-playbook.md) - Contribution model, ownership, and decision process for an active system. diff --git a/dist/pi/.agents/skills/design-system/references/governance-playbook.md b/dist/pi/.agents/skills/design-system/references/governance-playbook.md new file mode 100644 index 0000000..8d72e3b --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/governance-playbook.md @@ -0,0 +1,303 @@ +# Design System Governance Playbook + +A design system without governance decays. This playbook covers the operating model: who owns it, how changes happen, and how the system stays alive. + +--- + +## Ownership models + +Three common models. Pick based on team size and maturity. + +### Model 1: Dedicated team + +A standing team owns the system full-time. 2 to 5 people typically: a lead designer, a lead engineer, and supporting roles. + +**Strengths:** +- Highest velocity for system improvements +- Clear ownership, fast decisions +- Can take on big system-level initiatives + +**Weaknesses:** +- Expensive +- Risk of disconnection from product teams +- Risk of building what the team finds interesting vs. what consumers need + +**When to use:** Organizations with 10+ designers and 50+ engineers, where system inconsistency is a real cost. + +### Model 2: Federated / contribution model + +System is maintained by multiple teams contributing changes. A small core team (or one lead) reviews contributions and maintains the foundation. + +**Strengths:** +- Distributed effort +- Component owners are the people closest to the use case +- Prevents the "system team builds for itself" problem + +**Weaknesses:** +- Coordination overhead +- Inconsistent velocity +- Requires strong contribution norms or quality drifts + +**When to use:** Mid-sized teams (5 to 15 designers, 20 to 100 engineers), where multiple teams need a shared system but no single team can dedicate full-time effort. + +### Model 3: Single owner / part-time + +One person owns the system as part of their broader role. Common in startups and small teams. + +**Strengths:** +- No coordination cost +- Decisions happen instantly +- Cheap + +**Weaknesses:** +- System decays when owner is busy +- Bus factor of one +- Hard to scale + +**When to use:** Early-stage teams. Plan to migrate to Model 1 or 2 as the team grows. + +--- + +## Contribution model + +How new components, variants, or changes get added to the system. + +### Stages + +1. **Proposal.** A team that needs a new component or variant proposes it. Proposal includes: the use case, examples in the wild, why existing components don't suffice. + +2. **Triage.** System owner(s) decide: + - **Accept:** add to the system. Assign owner. + - **Adapt existing:** existing component should grow to cover this use case. + - **Defer:** valid request but not prioritized now. + - **Reject:** doesn't fit the system. Solve in a one-off way. + +3. **Design.** Component is designed in the system's style. Includes all states, variants, and accessibility requirements. + +4. **Review.** System owner reviews against system standards. Iterate. + +5. **Build.** Component is built in code (and Figma if not built there first). + +6. **Document.** Usage doc, API doc, examples, anti-patterns. + +7. **Release.** Versioned release. Changelog entry. Announcement to consumers. + +### Proposal template + +```markdown +# Component Proposal: [Name] + +## Use case +[What we're building. The user problem this UI element solves.] + +## Examples in the wild +[3 to 5 places where teams have built ad-hoc versions of this. Screenshots.] + +## Why existing components don't fit +[Specific reasons existing components are insufficient.] + +## Proposed component +[Sketch or description of the proposed component, variants, states.] + +## Owner +[Who will design, build, and maintain this component.] + +## Timeline +[When this is needed. Hard deadlines vs. nice-to-have.] +``` + +--- + +## Decision-making + +### Type 1: Reversible decisions + +Most component-level decisions. Made by the component owner with light input from the system team. + +Examples: a new variant, a tweak to a state, an additional prop on an existing component. + +Process: lightweight. Propose in the team channel, get one or two reactions, ship. + +### Type 2: One-way doors + +Decisions that affect the foundation or ripple across many components. + +Examples: changing a base token, deprecating a component, changing the naming convention. + +Process: written proposal, formal review, broader stakeholder input, documented decision in the decision log. + +### Decision log + +Every Type 2 decision gets logged: + +```markdown +# DSDR-001: [Decision title] + +**Date:** YYYY-MM-DD +**Status:** [Proposed / Approved / Rejected / Implemented] +**Author:** [Name] + +## Context +[What situation led to this decision.] + +## Options considered +1. [Option] - pros, cons +2. [Option] - pros, cons +3. [Option] - pros, cons + +## Decision +[What was decided.] + +## Reasoning +[Why this option won.] + +## Consequences +[What changes as a result. What new constraints exist.] + +## Revisit when +[Trigger condition that would warrant reopening this decision.] +``` + +This log becomes the institutional memory. Future system owners can understand why things are the way they are. + +--- + +## Versioning + +### Semantic versioning + +For systems shipped as code packages, semver works well: + +- **Major (1.0.0 → 2.0.0):** breaking changes. API changes. Visual changes that consumers must adapt to. +- **Minor (1.0.0 → 1.1.0):** new components or variants. Backward-compatible. +- **Patch (1.0.0 → 1.0.1):** bug fixes. Backward-compatible. + +### Release cadence + +Three patterns: + +- **Continuous:** ship as ready. Best for teams that can absorb frequent updates. +- **Periodic:** weekly or biweekly batched releases. Best for systems with many consumers. +- **Major releases:** quarterly major versions, with weekly patches between. Best for systems with breaking changes that need migration time. + +### Communication + +For each release: +- Changelog entry (what changed, why) +- Migration guide for breaking changes +- Internal announcement (Slack, email, internal newsletter) +- Demo or office hours for major changes + +--- + +## Deprecation + +Components get retired. Manage retirement explicitly. + +### Deprecation stages + +1. **Warning.** Component is marked deprecated. Documentation gains a deprecation notice. Build emits a console warning. + +2. **Migration period.** Defined window (typically 1 to 2 quarters) for consumers to migrate. Migration guide published. + +3. **Removal.** Component removed. Code deleted. Documentation archived (not deleted, for historical reference). + +### Deprecation notice template + +```markdown +> ⚠️ Deprecated: [Component] is deprecated as of [version]. +> Replacement: [link to replacement component] +> Removal: scheduled for [version / date] +> Migration guide: [link] +``` + +--- + +## Quality bar + +Every component or change must meet the bar before merging. + +### Functional +- [ ] Works at the documented breakpoints +- [ ] All variants and states implemented +- [ ] Keyboard navigation works +- [ ] Screen reader announces correctly +- [ ] Focus indicators visible +- [ ] Touch targets at least 44px +- [ ] Color contrast passes AA + +### Documentation +- [ ] Usage doc (when to use, when not to) +- [ ] API doc (props, types, defaults) +- [ ] Examples (basic, advanced, edge cases) +- [ ] Anti-patterns (what to avoid) + +### Consistency +- [ ] Uses tokens (no hardcoded values) +- [ ] Follows naming conventions +- [ ] Visual style matches the system +- [ ] Behavior matches similar components + +### Test +- [ ] Unit tests for component logic +- [ ] Visual regression test +- [ ] Accessibility test + +--- + +## Metrics + +Track the health of the system. + +### Adoption + +- Percentage of product UI built from system components vs. one-offs +- Per-team adoption rate +- Component usage frequency + +### Velocity + +- Time from proposal to release +- Number of accepted contributions per month +- Open proposals in queue + +### Quality + +- Open bugs against system components +- Accessibility issues count +- Drift incidents (components used in unsupported ways) + +### Consumer satisfaction + +- Internal survey: how useful is the system? +- What's missing? What blocks adoption? + +Run satisfaction survey at least annually. Use results to guide system priorities. + +--- + +## Sustaining the system + +A design system is a living thing. Without maintenance, it dies. + +### Weekly +- Triage incoming proposals +- Review consumer questions and feedback +- Address bugs + +### Monthly +- Release notes for any changes +- Office hours for consumer teams +- Component audit (one or two components reviewed in depth) + +### Quarterly +- Roadmap review +- Foundation review (token health, naming consistency) +- Adoption metrics review + +### Annually +- Strategic review (is the system serving its purpose?) +- Consumer satisfaction survey +- Major version planning + +The system is never finished. It evolves with the product, the team, and the brand. diff --git a/dist/pi/.agents/skills/design-system/references/system-architecture.md b/dist/pi/.agents/skills/design-system/references/system-architecture.md new file mode 100644 index 0000000..113081c --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/system-architecture.md @@ -0,0 +1,275 @@ +# System Architecture + +How the four layers of a design system relate, and how to decide where new things belong. + +--- + +## The four layers, top to bottom + +``` +┌──────────────────────────────────────────────────────────────┐ +│ TEMPLATES (full screens, complete flows) │ +│ Optional layer. Use when the same screen pattern recurs. │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PATTERNS (composed components solving a UI problem) │ +│ Examples: form layouts, modal dialogs, navigation, tables │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PRIMITIVES (smallest reusable elements) │ +│ Examples: button, input, checkbox, badge, icon, link │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ TOKENS (atomic named values) │ +│ Examples: color-text-primary, space-md, radius-card │ +└──────────────────────────────────────────────────────────────┘ +``` + +Higher layers consume lower layers. A primitive uses tokens. A pattern composes primitives (and tokens). A template assembles patterns. + +A token never references a primitive. A primitive never references a pattern. The dependency direction is one-way. + +--- + +## When to add at each layer + +### Add a token when: +- A value appears in 3+ places +- The value has a clear semantic purpose +- Changing the value should propagate everywhere it appears + +**Example:** "Card border radius" - if 12 components use 12px corner radius, that's a token. + +**Counter-example:** A one-off radius for a single decorative element. Hard-code it. + +### Add a primitive when: +- The same combination of HTML/JSX/View elements recurs in 3+ places +- The element has an internal state machine (open/closed, default/hover/disabled) +- Centralized accessibility logic helps consumers + +**Example:** Button. Recurs everywhere. Has states. Accessibility (focus, keyboard, ARIA) is non-trivial. + +**Counter-example:** A specific marketing hero block that only appears on the homepage. Not a primitive. Build it inline. + +### Add a pattern when: +- Multiple teams keep building the same composition +- The composition involves non-obvious decisions (z-index, focus management, scroll behavior, animation) +- A central pattern reduces accessibility risk + +**Example:** Modal dialog. Hard to get right (focus trap, escape, scroll lock). Pattern centralizes the hard parts. + +**Counter-example:** A specific dashboard layout used only on the analytics page. Not a pattern. Build it inline as a screen. + +### Add a template when: +- A full screen recurs across products or sections +- New product features want a starting point that already follows system rules + +**Example:** Settings page layout (left nav, content area, save bar). If the team builds 5 settings sections, the template saves time. + +**Counter-example:** A unique landing page. Not a template. + +--- + +## Decision tree: where does this belong? + +``` +Is it a value? ────── Yes ────── Token + │ + └── No + +Is it a single element? ── Yes ── Primitive + │ + └── No + +Is it composed of primitives? ─ Yes ─ Pattern + │ + └── No + +Is it a full screen? ──────── Yes ── Template +``` + +--- + +## Token tiering + +Most systems benefit from at least two tiers. Three is the maximum without diminishing returns. + +### Tier 1: Primitives + +Raw values, no semantic meaning attached. + +``` +color-blue-50 = #EFF6FF +color-blue-100 = #DBEAFE +color-blue-500 = #3B82F6 +color-blue-900 = #1E3A8A + +space-1 = 4px +space-2 = 8px +space-4 = 16px +space-8 = 32px + +radius-sm = 4px +radius-md = 8px +radius-lg = 12px +``` + +### Tier 2: Semantic + +Purpose-named, mapped to primitives. + +``` +color-text-primary = color-gray-900 +color-text-secondary = color-gray-600 +color-text-link = color-blue-700 +color-bg-surface = color-white +color-bg-elevated = color-white +color-border-default = color-gray-200 + +space-stack-tight = space-2 +space-stack-default = space-4 +space-stack-loose = space-6 +``` + +### Tier 3 (optional): Component-specific + +Component-tied, mapped to semantic tokens. + +``` +button-padding-x = space-stack-default +button-padding-y = space-stack-tight +button-radius = radius-md +button-bg-primary = color-bg-action-primary +``` + +**Rule of thumb:** Stop at Tier 2 unless the system is large enough to justify Tier 3 maintenance. Tier 3 adds clarity but multiplies token count. + +--- + +## Naming conventions + +Pick one and stay. The most common patterns: + +### Pattern A: Hierarchical with hyphens +``` +color-text-primary +color-text-secondary +color-bg-surface +space-stack-md +``` + +### Pattern B: Object/dot notation (often in JSON or JS) +``` +color.text.primary +color.bg.surface +space.stack.md +``` + +### Pattern C: Flat with prefix +``` +text-color-primary +bg-color-surface +stack-space-md +``` + +Hierarchical-with-hyphens (Pattern A) is the most common for CSS variable contexts. Pick once, document, never deviate. + +--- + +## Naming for the semantic layer + +Names should describe purpose, not appearance. "Color is what it is, name is what it does." + +**Good:** +- `color-text-primary` (what role does it play?) +- `color-bg-action-destructive` (what action is this for?) +- `space-stack-section` (where does it apply?) + +**Bad:** +- `color-blue-medium` (semantic name should not encode the value; that's the primitive layer's job) +- `color-pretty-blue` (subjective, not purpose) +- `color-button-text` (OK at component layer; too specific for semantic layer) + +--- + +## Versioning + +Use semantic versioning: `major.minor.patch`. + +- **Patch:** Bug fixes, no API changes. Bump for any defect fix. +- **Minor:** Additive changes. New tokens, new components, non-breaking API additions. +- **Major:** Breaking changes. Removed tokens, renamed APIs, behavioral changes consumers must adapt to. + +For breaking changes, provide: + +1. Deprecation warning in the previous minor version +2. Migration guide +3. Codemod or scripted migration path where possible +4. A timeline for sunset (typically 1 to 2 quarters) + +--- + +## Anti-patterns + +### Color sprawl +- 200 named colors instead of a tight palette of 30 to 50. +- Symptom: every designer adds the color they need. +- Fix: enforce primitive layer review before new colors land. + +### Spacing chaos +- 17 different spacing values, half of them within 2px of each other. +- Symptom: each design uses unconstrained spacing. +- Fix: a defined scale. New spacing values require a real reason. + +### Naming inconsistency +- `colorPrimary`, `color-primary`, `primary-color`, `primaryColor` all in the same system. +- Symptom: tokens added by different people without convention. +- Fix: pick one convention, document, automate validation. + +### Tokens without consumers +- 200 tokens defined, 50 actually used. +- Symptom: aspirational tokens added "for the future." +- Fix: only add tokens with current or near-future consumers. + +### Components without docs +- 30 components in the library, 5 have docs. +- Symptom: docs treated as separate work, deprioritized. +- Fix: docs blocking the merge of new components. + +### Patterns over-built +- A "DataTable" pattern with 47 props supporting every imaginable variation. +- Symptom: Trying to anticipate every use. +- Fix: ship narrow first. Expand based on real demand. Hard to remove options once shipped; easy to add. + +--- + +## Dependency directions + +A healthy system has these dependency rules: + +- Tokens depend on nothing. +- Primitives depend on tokens. +- Patterns depend on primitives and tokens. +- Templates depend on patterns, primitives, and tokens. +- Application code depends on any layer. + +Violations to flag: + +- A token referencing another token at a different tier (sometimes OK, often a smell). +- A primitive referencing a pattern. Wrong direction. +- A pattern not using primitives, building from raw HTML. Bypasses the system. +- Application code defining its own colors instead of using tokens. Bypasses the system. + +--- + +## How to introduce a system to an existing codebase + +If the codebase has no system today: + +1. **Audit.** Inventory existing UI. Find duplicates and inconsistencies. +2. **Tokens first.** Establish the token foundation. Migrate hard-coded values gradually. +3. **Primitives second.** Replace ad-hoc components with system primitives. Highest-impact ones first (button, input, modal). +4. **Patterns third.** Once primitives are established, codify patterns. +5. **Migrate over multiple quarters.** Rip-and-replace fails. Coexistence with gradual migration succeeds. + +Plan for the system to take 2 to 4 quarters to fully replace ad-hoc UI in a medium-sized product. Plan for it to never be "done" - it evolves with the product. diff --git a/dist/pi/.agents/skills/design-system/references/system-audit-template.md b/dist/pi/.agents/skills/design-system/references/system-audit-template.md new file mode 100644 index 0000000..625f9f5 --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/system-audit-template.md @@ -0,0 +1,258 @@ +# Design System Audit Template + +A template for auditing an existing design system. Use this to take stock of what exists, what is missing, what is duplicated, and what is silently broken. + +The output is an honest report, not a grade. The goal is a backlog the team can act on. + +--- + +## When to use this template + +- Before a major redesign or rebrand (knowing the starting state shapes the plan). +- When the system feels heavy or inconsistent and no one can articulate why. +- When a new owner takes over and needs ground truth. +- Quarterly, as a regular health check. + +--- + +## Audit scope + +Decide upfront what is in and out of scope. A full audit covers all four layers (tokens, primitives, patterns, templates) plus governance and adoption. A focused audit covers one or two. + +| Layer / area | In scope | Out of scope | +|---|---|---| +| Tokens | | | +| Primitives | | | +| Patterns | | | +| Templates | | | +| Documentation | | | +| Governance | | | +| Adoption | | | + +--- + +## Layer 1: Tokens + +### Inventory + +List every token category in the system. For each, count, source of truth, and platforms supported. + +| Category | Count | Source of truth | Platforms supported | +|---|---|---|---| +| Color | | | | +| Typography (font, size, weight, line-height) | | | | +| Spacing | | | | +| Radius | | | | +| Shadow | | | | +| Motion (duration, easing) | | | | +| Z-index | | | | +| Breakpoints | | | | +| Other | | | | + +### Findings + +- [ ] Are tokens named by role (`color-text-primary`) or by value (`gray-900`)? Role-based scales better. +- [ ] Is there a single source of truth (one file, one tool) or multiple sources that drift? +- [ ] Are tokens versioned? How are breaking token changes communicated? +- [ ] Are there duplicate tokens (`color-blue-primary` and `color-action`)? List them. +- [ ] Are there orphan tokens (defined but unused)? List them. +- [ ] Are dark mode / theme variants modeled at the token layer or elsewhere? + +### Token risks + +- **Hardcoded values in code:** grep the codebase for raw hex, raw px values, raw font sizes. Note where tokens were skipped. +- **Token sprawl:** more than 20 named colors, more than 8 spacing values, or more than 6 font sizes is usually a smell. +- **Naming inconsistency:** `color-text` vs `text-color` vs `textColor` across categories. + +--- + +## Layer 2: Primitives + +### Inventory + +List every primitive component the system ships. For each, status and consumer count. + +| Primitive | Status (Production / Beta / Deprecated) | Consumers (rough count) | Notes | +|---|---|---|---| +| Button | | | | +| Input | | | | +| Checkbox | | | | +| Radio | | | | +| Select | | | | +| Textarea | | | | +| Badge | | | | +| Avatar | | | | +| Icon | | | | +| Link | | | | +| (etc.) | | | | + +### Findings + +- [ ] Are primitives accessible (keyboard, screen reader, focus management)? List failures. +- [ ] Are all primitives token-driven, or do some hardcode values? +- [ ] Are there duplicate primitives that do almost the same thing (`Button` and `IconButton` and `LinkButton`)? Could they consolidate? +- [ ] Are primitives documented (props, states, variants, accessibility)? +- [ ] Are there one-off primitives in product code that should be promoted to the system? + +--- + +## Layer 3: Patterns + +Patterns are composed components solving a specific UI problem. + +### Inventory + +| Pattern | Status | Used by (rough page or feature count) | Notes | +|---|---|---|---| +| Form layout | | | | +| Modal dialog | | | | +| Toast / notification | | | | +| Navigation (top, side) | | | | +| Empty state | | | | +| Pagination | | | | +| Data table | | | | +| Card | | | | +| (etc.) | | | | + +### Findings + +- [ ] Are patterns built from primitives, or do they reach around the primitives layer? +- [ ] Do multiple patterns solve the same problem with different APIs? +- [ ] Are patterns flexible enough for real product needs, or are teams forking them? + +--- + +## Layer 4: Templates + +Templates are full screens or flows. Optional layer. + +### Inventory + +| Template | Status | Used by | Notes | +|---|---|---|---| +| Marketing landing | | | | +| App shell | | | | +| Settings page | | | | +| Onboarding flow | | | | +| Empty product state | | | | +| (etc.) | | | | + +### Findings + +- [ ] Do templates exist at all? Many systems skip this layer. +- [ ] Are templates a starting scaffold or a rigid spec? +- [ ] Are template layouts responsive, or do teams reimplement responsive behavior each time? + +--- + +## Documentation + +### Inventory + +- **Documentation site:** [URL or "none"] +- **Last meaningful update:** [Date] +- **Component coverage:** [What % of shipped components are documented?] +- **Code examples for every component:** [Yes / partial / no] +- **Accessibility notes for every interactive component:** [Yes / partial / no] +- **Migration / changelog:** [Yes / no] + +### Findings + +- [ ] Is the documentation in sync with the shipped code, or has it drifted? +- [ ] Can a new engineer onboard from the docs alone, or do they need tribal knowledge? +- [ ] Is there a "do / do not" pattern with examples for each component? +- [ ] Are deprecated components clearly marked, with a migration path? + +--- + +## Governance + +- **Ownership model:** [Dedicated team / federated / single owner / unowned] +- **Contribution process:** [Documented / informal / nonexistent] +- **Review cadence:** [How often do owners look at incoming requests, bugs, drift?] +- **Decision log:** [Where are major design system decisions recorded? Or are they not?] +- **Communication channel:** [Slack channel / mailing list / standing meeting / none] + +### Findings + +- [ ] Who decides when a new component enters the system? +- [ ] Who decides when a component is deprecated? +- [ ] Who handles requests from product teams? What is the SLA? +- [ ] What happens when a product team needs something the system does not provide? + +--- + +## Adoption + +### Measurement + +| Measure | Today | Target | +|---|---|---| +| % of UI built with system components | | | +| % of new features using system | | | +| Number of one-off components in product code | | | +| Number of token overrides in product code | | | +| Number of open issues against the system | | | + +### Findings + +- [ ] Where is adoption strongest? Why? +- [ ] Where is adoption weakest? Why? (Often: missing components, too rigid, undocumented, or onboarding gap.) +- [ ] Are there teams actively forking or working around the system? + +--- + +## Risk register + +List the top 5 risks the audit surfaced. For each: severity (high / medium / low), affected area, and a one-line recommendation. + +| # | Risk | Severity | Affected area | Recommendation | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | +| 3 | | | | | +| 4 | | | | | +| 5 | | | | | + +--- + +## Backlog + +Translate findings into a prioritized backlog. Keep items concrete and assignable. + +### Critical (block adoption or accessibility) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### High (consistent friction or duplication) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Medium (improvement, not blocking) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Low (polish) + +- [ ] [Item, owner, target date] + +--- + +## Audit summary + +Three sentences. What is the overall state, what is the single most important thing to fix, and what should the team start now. + +> [State summary] +> [Most important fix] +> [Start now] + +--- + +## Sign-off + +Audit conducted by: [Name(s), date] +Reviewed with: [Stakeholders] +Next audit scheduled: [Date] diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md b/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md new file mode 100644 index 0000000..be007e8 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md @@ -0,0 +1,265 @@ +--- +name: discovery-research-synthesis +description: "Turning research artifacts into actionable PM insight. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the decisions they are meant to inform. The discipline of moving from raw discovery data to clear product direction without losing signal in the synthesis or fabricating insight that was not actually there. Triggers on research synthesis, customer interview synthesis, user research analysis, discovery readout, research insights, sales call analysis, support ticket analysis, qualitative data analysis. Also triggers when a team has done research but cannot turn it into decisions, when synthesis is producing pretty decks but no roadmap movement, or when an upcoming PM decision needs to be grounded in research already conducted." +category: research +catalog_summary: "Synthesizing customer interviews, research notes, and support tickets into actionable PM decisions. Distinguishes data-dump (no synthesis) from insight-theater (overpolished narrative) from actionable synthesis (decision-grade clarity)" +display_order: 4 +--- + +# Discovery Research Synthesis + +A senior PM's playbook for turning research artifacts into decisions. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the product direction they are meant to inform. + +Most discovery research never produces decisions. The team conducts interviews; the transcripts pile up; a researcher hands product the raw artifacts (data-dump) or builds a polished readout deck (insight-theater); the deck gets a 30-minute review meeting and is never referenced again. Two months later the team is making the same product decisions that the research was supposed to inform, with the same gut-feel inputs the research was supposed to displace. + +The discipline is in the synthesis. Synthesis is where research earns its keep: where transcripts become tagged observations, observations cluster into patterns, patterns get named, named patterns surface product implications, and implications drive specific decisions. Without that sequence, research is performance art. + +This skill covers one-off discovery research projects: a 12-week customer development sprint, a sales-call review for an onboarding redesign, a support-ticket audit informing a roadmap quarter. Different from `user-feedback-aggregation`, which covers ongoing feedback streams; different from `jtbd-framing`, which is a specific framing technique often applied within synthesis but narrower in scope. + +The voice is the senior PM or staff product researcher who has run synthesis well and seen plenty of teams fail at it. Honest about where polish becomes performance and where pattern-naming slides into pattern-fabrication. + +When to use this skill: synthesizing a recent batch of customer interviews, auditing why prior research has not produced product decisions, designing the synthesis output for a multi-week discovery sprint, or establishing the synthesis discipline a team currently lacks. + +--- + +## What this skill is for + +This skill spans research-to-decision synthesis. The PM-skill distinction: + +- **`discovery-research-synthesis` (this skill)** is one-off research synthesis: turning a discrete batch of artifacts into a discrete set of decisions. +- `user-feedback-aggregation` is ongoing feedback streams: continuous synthesis across always-on channels (support, NPS, in-app, sales). +- `jtbd-framing` is a framing technique often applied during synthesis; this skill is broader. +- `pm-spec-writing` is downstream: specs use synthesized insights as input. +- `roadmap-planning` is downstream: roadmap uses synthesized priorities as input. +- `experiment-design` is the quantitative-validation discipline that often follows qualitative synthesis. + +The audience: senior PMs, product directors, in-house product teams, agencies running discovery work for clients, researchers handing off to product teams. + +What is not in scope: conducting the research itself (interview design, recruiting, moderation), the broader discovery strategy that decides which research to commission, or the long-running feedback channels that user-feedback-aggregation covers. + +--- + +## Data-dump vs insight-theater vs actionable-synthesis + +The keystone framing. Two failure modes plus the discipline. + +**Data-dump.** Research artifacts handed to the product team raw. "Here are 47 transcripts and a spreadsheet of tags; figure it out." No synthesis, no signal-finding, no implications drawn. The product team either does the synthesis itself (often badly, often months later) or skips it (the most common outcome). Output: a research investment that produced artifacts but not insight. + +**Insight-theater.** Overpolished synthesis dressed as insight. Pretty quote walls, designed personas, branded readout decks, no decision-driving conclusions. The research deck that gets a 30-minute review and never gets referenced. Synthesis that performed for the executive audience but did not inform the product audience. Cost: real research budget converted into a slide deck; the organization "did the research" without doing the research. + +**Actionable-synthesis.** Synthesis that drives decisions. Each pattern has a "so what" attached; each finding leads to a product implication; the document gets referenced in roadmap discussions, spec drafts, prioritization debates. The synthesis is short, opinionated, and load-bearing. Six months later, team members can quote the patterns that shaped what shipped and what got cut. + +The litmus test. Three months after a synthesis ships, can team members name the decisions the synthesis informed? If yes, the synthesis was actionable. If team members remember the deck but cannot name the decisions, it was insight-theater. If nobody remembers anything because the synthesis never happened, it was data-dump. + +--- + +## Discovery research types + +Five common research types, each with different artifacts and synthesis needs. + +**Customer interviews.** 30-90 minute structured or semi-structured conversations. Transcripts plus moderator notes plus recordings. Highest-quality qualitative data; most expensive to collect; most rewarding to synthesize when done well. Typical batch: 8-15 interviews per discovery cycle. + +**Support ticket reviews.** Auditing recent support tickets for patterns. Lower per-artifact richness than interviews; higher volume; surfaces the friction users actually hit (not just what they say in interviews). Typical batch: 100-500 tickets per audit. + +**Sales call analysis.** Recording or transcript review of recent sales calls. Surfaces objections, pricing-conversation patterns, competitive mentions, and the gap between marketing positioning and what sales actually leads with. Typical batch: 15-30 calls per audit. + +**Survey data.** Quantitative responses with optional qualitative comments. Best for validating qualitative patterns at scale; weak as primary discovery (surveys reveal what users say, not what they do). Typical batch: 100-2,000 responses. + +**In-app feedback.** Users submitting feedback through in-product channels. Volume is high; quality varies; signal lives in patterns across many low-effort submissions. Typical batch: ongoing; synthesized in periodic audits. + +Different research types compose. A discovery cycle often pairs interviews (depth) with support ticket review (volume) with survey data (validation at scale). The synthesis combines them. + +Detail in [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md). + +--- + +## The synthesis sequence + +Six stages from raw artifacts to decisions. Skipping stages is where synthesis fails. + +**1. Transcribe and prepare.** Convert artifacts into a synthesizable format. Interview recordings to transcripts; sales calls to summaries; support tickets to a tagged dataset. The prep work is unglamorous; teams that skip it never reach the later stages. + +**2. Tag at the artifact level.** Read each transcript or ticket and tag it with the topics, problems, and quotes that surface. First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. Tags are messy; that is fine. + +**3. Cluster across artifacts.** Group tags into themes. Multiple users mentioned the same friction; multiple tickets reference the same workflow; multiple interviews returned to the same struggling moment. The clusters surface the patterns. + +**4. Name patterns.** Each cluster becomes a named pattern. The naming is the work: a pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references. "Onboarding configuration friction" is a pattern name; "users had trouble" is not. + +**5. Infer product implications.** For each pattern, what does this imply for the product? Implications are the bridge from observation to decision. A pattern without an implication is a finding; a pattern with an implication is actionable input. + +**6. Name the so-what.** For each implication, the specific decision it informs. "Should we prioritize the onboarding redesign in Q2?" The so-what is what makes the synthesis decision-grade. + +The sequence is non-negotiable. Teams that skip tagging and jump to pattern naming hallucinate patterns; teams that skip implications produce findings without product direction; teams that skip so-what produce documentation, not synthesis. + +Detail in [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md). + +--- + +## Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. + +**Tag at the artifact level first; do not pre-design the taxonomy.** Tags emerge from the artifacts. Teams that arrive with a pre-built tag taxonomy ("we will tag for usability, performance, pricing, support") force artifacts into categories that may not fit the data, and miss patterns the taxonomy did not anticipate. + +**Allow tag proliferation; collapse later.** Early tagging may produce 80-150 tags across a batch. That is correct. The clustering stage collapses them. Premature consolidation ("we had 4 onboarding tags; let me merge them") loses distinctions that turn out to matter. + +**Cluster on patterns, not on tag overlap.** Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation: are these the same struggling moment, or do they share a tag because the tag was loose? + +**Name the cluster after clustering, not before.** The cluster name comes from the data, not from a hypothesis. Teams that arrive with named clusters and slot data into them produce confirmation; teams that name clusters from the data produce discovery. + +**Tag dissent and contradictions explicitly.** Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. Tag the dissent so the synthesis can address it. + +Detail in [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md). + +--- + +## Pattern naming + +The work that distinguishes synthesis from documentation. + +**A pattern name is not a category label.** "Onboarding" is a category. "Users abandon configuration before reaching the success state because the third configuration step requires data they do not have on hand" is a pattern. The pattern names the specific behavior the data reveals. + +**The name should make the implication legible.** A reader who sees only the pattern name should be able to guess the product implication. If the name is too abstract, the reader cannot reach the implication; if the name is too concrete, the synthesis becomes a list of micro-observations. + +**Avoid category bloat.** Synthesis with 30 named patterns is usually under-clustered: many of those patterns are variations on a smaller number of underlying patterns. Synthesis with 4 named patterns is often the right number; 6-8 is common; more than 12 is usually category bloat. + +**Avoid naming the obvious.** "Users want fast performance" is not a pattern; it is a truism. A pattern is a specific observation that the product team did not already know. If the pattern name reads as something everyone could have said before the research, the pattern is not a pattern. + +**Name with conviction.** Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly; they invite challenge and produce decisions. + +Detail in [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md). + +--- + +## From pattern to product implication + +The bridge from observation to decision. + +**Pattern-to-implication is the writer's analytical work, not what the user said.** Users do not state product implications; they describe their experience. The PM doing synthesis interprets the pattern and proposes the implication. The interpretation is where synthesis adds value beyond transcription. + +**Each pattern can have multiple implications.** A pattern about onboarding friction might imply a redesign of the configuration flow, or default-data pre-population, or staged onboarding. The synthesis surfaces the options; the prioritization decision picks one. + +**Implications should be falsifiable.** A vague implication ("we should improve onboarding") is not actionable. A specific implication ("staged onboarding that defers the third configuration step until after the user reaches the first success state") is. Specific implications can be debated, scoped, prioritized. + +**Implications should acknowledge cost.** Patterns suggest solutions; solutions cost product capacity. Synthesis that implies 30 product changes without acknowledging that delivering them all is impossible is not synthesis; it is a wishlist. + +**Some patterns imply not-acting.** Sometimes the pattern reveals friction the team should not address: it affects too few users, it represents segment misfit, addressing it would compromise other priorities. Naming the not-act implication is honest synthesis. + +Detail in [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md). + +--- + +## Writing for decisions, not deck performance + +Synthesis output should be optimized for decision use, not for presentation. + +**Document, not deck.** Deck format is poor for synthesis: slides cannot carry argument density; readers cannot reference slides later; decks decay into icons and bullet points. A short document (4-12 pages) carries more usable synthesis than a 60-slide deck. + +**Lead with patterns and implications; relegate evidence to appendix.** A reader scanning for decision input wants the patterns and implications first. Evidence (quotes, ticket excerpts, data tables) supports the patterns but does not lead. Decks that lead with quote walls have inverted the reader's needs. + +**One section per pattern.** Each pattern gets a short section: pattern name, evidence summary (2-3 sentences with link to full evidence in appendix), implication, so-what decision input. + +**Be opinionated.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. Synthesis that commits positions invites challenge and produces decisions. The PM doing synthesis is making a recommendation; readers can disagree, but disagreement is the point. + +**Include a decision-input section.** What does this synthesis recommend the team do? Where should priorities shift? Which roadmap items does this validate, which does it challenge? The decision-input section is the synthesis's reason for existing. + +Detail in [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md). + +--- + +## The synthesis review and validation loop + +How the synthesis gets pressure-tested before it drives decisions. + +**Internal review with the research participants where possible.** Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? Misrecognition signals the synthesis fabricated patterns or projected interpretations the data did not support. + +**Adjacent-team review.** Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? Adjacent teams catch synthesis errors that the research team missed. + +**Quantitative validation where possible.** Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. The pattern says X; does the data confirm X happens at the frequency and severity the pattern implies? See `experiment-design` and `product-analytics-setup` for the quantitative methodology. + +**The "challenge the synthesis" session.** A specific session where adjacent teams try to find the patterns the synthesis missed, the implications the synthesis overstated, the decisions the synthesis is railroading. Productive disagreement strengthens the synthesis. + +**Iterate before publishing.** Synthesis goes through revision based on the review loop. Synthesis that ships in the first draft state usually carries unacknowledged blind spots. + +Detail in [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md). + +--- + +## When to halt and gather more data + +Synthesis sometimes reveals that the research did not collect enough. + +**Pattern thinness.** A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. Either name the pattern as tentative pending more data, or pause synthesis and gather more research. + +**Segment under-representation.** The research overrepresents one user segment and underrepresents another that matters for the decision. Patterns from the represented segment may not apply to the underrepresented one. + +**Contradictory clusters.** Two clusters point in opposite directions and the data does not resolve the contradiction. Often signals a sub-segment difference that the research did not investigate enough. + +**Decision time pressure.** Synthesis revealing data gaps but the decision has to ship before more research can happen. Honest path: name the data gap explicitly in the synthesis, make the recommendation with the gap acknowledged, plan the follow-up research that would validate or revise. + +**The "we have enough" trap.** Teams that have invested in research often want to declare the data sufficient even when the synthesis reveals gaps. The discipline is naming gaps even when uncomfortable. + +Detail in [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md). + +- "We did the research but never made decisions from it." Data-dump or insight-theater; synthesis sequence skipped or stopped at findings. +- "Our synthesis deck got a polite review and was never referenced again." Insight-theater; output was performative rather than load-bearing. +- "We have 30 named patterns and no clear priorities." Category bloat; under-clustering; cure: re-cluster to 4-8 underlying patterns. +- "Every pattern reads as something we already knew." The synthesis named truisms, not patterns. Re-examine the data for what was actually surprising. +- "The patterns contradict each other and we cannot reconcile them." Often segment misfit; consider whether the contradictions reveal sub-segments with different needs. +- "Research participants did not recognize themselves in our synthesis." Synthesis fabricated patterns or projected interpretations not in the data. Restart with closer evidence-tracking. +- "The synthesis is detailed but the team cannot tell what to do." Implications missing or vague; cure: each pattern gets a specific falsifiable implication. +- "We hedged every pattern and the synthesis reads as wishy-washy." Hedge stacking; the synthesis avoided commitment. Rewrite with conviction. +- "Our quote walls were impressive but the deck was 60 slides." Insight-theater; cure: 8-page document with quotes in appendix. +- "The synthesis recommended 20 product changes; we shipped one." Wishlist synthesis; did not acknowledge cost; cure: prioritize within the synthesis. +- "Adjacent teams disagreed with our patterns and we did not engage." Review loop skipped; cure: make adjacent-team review non-negotiable before shipping. + +--- + +## The framework: 12 considerations for discovery synthesis + +When designing or auditing a synthesis output, walk these 12 considerations. + +1. **Actionable-synthesis, not data-dump or insight-theater.** Synthesis that drives decisions. +2. **Research types matched to questions.** Interviews, support, sales calls, surveys, in-app combined deliberately. +3. **The synthesis sequence: transcribe, tag, cluster, name, imply, so-what.** No stage skipped. +4. **Tags emerge from artifacts; taxonomy not pre-designed.** +5. **Tag proliferation allowed; clustering collapses.** +6. **Patterns named with conviction; not categories or truisms.** +7. **Each pattern produces a specific falsifiable product implication.** +8. **Each implication has a so-what tied to a real decision.** +9. **Output is a document, not a deck.** Patterns lead; evidence in appendix. +10. **Synthesis is opinionated.** Hedges flagged; conviction shown. +11. **Review loop before publish.** Participants, adjacent teams, quantitative validation where available. +12. **Data gaps named, not buried.** Where research did not support a position, the synthesis says so. + +The output of the framework is a synthesis the team can act on: short, opinionated, evidence-grounded, decision-driving, accountable to challenge. + +--- + +## Reference files + +- [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md) - Five research types with synthesis implications. Composition patterns across types within a discovery cycle. +- [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md) - The six-stage sequence with worked example. Stage outputs, common skip-failures, time investment per stage. +- [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md) - Tag-at-artifact-level discipline, allow tag proliferation, cluster on patterns not overlap, name after clustering, tag dissent. +- [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md) - Pattern names that work and fail. Avoiding category bloat, naming-with-conviction, the implication-legibility test. +- [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md) - The bridge from pattern to implication. Falsifiability, multi-implication patterns, cost acknowledgment, the not-act implication. +- [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md) - Document over deck, patterns lead, evidence appendix, opinionated voice, decision-input section. +- [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md) - Participant review, adjacent-team review, quantitative validation, the challenge-the-synthesis session, iteration before publish. +- [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md) - Pattern thinness, segment under-representation, contradictory clusters, decision time pressure, the we-have-enough trap. +- [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: synthesis is where research earns its keep + +Discovery research is one of the most expensive activities a product team commissions. The expense is mostly hidden: customer time, researcher time, the opportunity cost of the discovery cycle itself, the management overhead of recruiting and scheduling. Most of that expense gets spent before synthesis even begins. + +The teams that earn returns on the research investment are the teams that take synthesis seriously: the sequence is run end-to-end, the patterns are named with conviction, the implications are falsifiable, the so-what ties to specific decisions, the output is a load-bearing document the team references for months. The teams that do not earn returns produce data-dumps or insight-theater; their research becomes documentation of work done rather than the input to work to come. + +When in doubt about whether a synthesis is ready, ask: are the patterns named with conviction, do they reach product implications, do the implications tie to specific decisions, has the synthesis been reviewed by participants and adjacent teams, are the data gaps named honestly? If yes to all of those, the synthesis is real. If no to any, the gap is where the research investment will fail to convert into decisions. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md new file mode 100644 index 0000000..a7b35c6 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md @@ -0,0 +1,193 @@ +# Common discovery synthesis failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most synthesis failures share a single root, which is treating synthesis as documentation work rather than as decision work. + +--- + +## Failure 1: We did the research but never made decisions from it + +**Symptom.** Discovery cycle completed; transcripts and notes filed; the team's roadmap discussions in the following months never reference the research. + +**Diagnosis.** Data-dump or insight-theater pattern. Synthesis sequence either skipped entirely (data-dump) or stopped at findings without reaching decisions (insight-theater). + +**Cure.** Run the synthesis sequence end-to-end on the existing artifacts. Even months after the original research, retroactive synthesis can produce decisions the original research was meant to inform. + +**Prevention.** Before commissioning the next research cycle, name the decisions the research is intended to inform. Build the synthesis sequence into the discovery plan, not as an afterthought. + +--- + +## Failure 2: Our synthesis deck got a polite review and was never referenced again + +**Symptom.** A polished readout deck. A 30-minute presentation. Positive feedback in the meeting. Six months later nobody references the synthesis in product decisions. + +**Diagnosis.** Insight-theater. Output was performative rather than load-bearing. Optimized for the presentation moment, not for reference use. + +**Cure.** Convert the deck content into a document with patterns leading, evidence in appendix, decision-input section. Recirculate as a reference document. + +**Prevention.** Future synthesis ships as documents, not decks. The presentation is a deck if needed; the synthesis is the document. + +--- + +## Failure 3: We have 30 named patterns and no clear priorities + +**Symptom.** The synthesis lists many patterns. The team agrees they are interesting but cannot prioritize. The synthesis fails to drive a roadmap shift. + +**Diagnosis.** Category bloat. Under-clustering produced inflation. Many of the 30 patterns are variations on a smaller number of underlying patterns. + +**Cure.** Re-cluster. Take the pattern list back to the clustering stage and look for the 4-8 underlying patterns the data actually supports. Synthesize from the consolidated list. + +**Prevention.** Cap pattern count at 4-8 for typical synthesis. When more than 8 patterns emerge, that is a signal to recluster, not to ship with bloat. + +--- + +## Failure 4: Every pattern reads as something we already knew + +**Symptom.** The synthesis names patterns that read as truisms. Team members who attended the readout could have produced the patterns without the research. + +**Diagnosis.** Pattern names captured truisms rather than the specific observations the research surfaced. The analytical work of pattern naming was skipped. + +**Cure.** Re-examine the data for what was actually surprising. Often the strongest patterns surface in the contradictions, the unexpected sub-segments, the workarounds users built. Pattern names should commit positions the team would not have committed before the research. + +**Prevention.** During pattern naming, apply the "what the team did not know" test. Patterns that read as common-knowledge are probably under-named. + +--- + +## Failure 5: The patterns contradict each other and we cannot reconcile them + +**Symptom.** Two patterns point in opposite directions. The synthesis is silent on the contradiction or hand-waves it. + +**Diagnosis.** Often segment misfit: different segments have different needs, and the synthesis did not surface the segment distinction. Sometimes context misfit: different use contexts produce different patterns. + +**Cure.** Re-examine the data for the segment or context dimension that explains the contradiction. The contradiction often becomes the most valuable finding once explained. + +**Prevention.** Tag dissent and contradictions explicitly during the tagging stage. Surface them through clustering. Address them in synthesis rather than burying them. + +--- + +## Failure 6: Research participants did not recognize themselves in our synthesis + +**Symptom.** When shown the synthesis, participants say "I did not say that" or "this does not match my experience." + +**Diagnosis.** Synthesis fabricated patterns or projected interpretations not in the data. The pattern naming reached for what the team wanted to find rather than what the participants actually said. + +**Cure.** Restart with closer evidence-tracking. Each pattern should be traceable to specific moments in specific artifacts. Patterns that cannot be traced are projections, not observations. + +**Prevention.** Build participant review into the synthesis process. Synthesis that participants do not recognize fails the validation; revise before publishing. + +--- + +## Failure 7: The synthesis is detailed but the team cannot tell what to do + +**Symptom.** Patterns are clear and well-supported. The team agrees on the patterns. The team cannot derive the product implications. + +**Diagnosis.** Implications missing or vague. The synthesis stopped at observations without bridging to product responses. + +**Cure.** Add implications to each pattern. Each implication should be specific, falsifiable, cost-acknowledged, and tied to a specific decision. + +**Prevention.** The synthesis sequence's implication stage is non-negotiable. Synthesis that ships without implications is incomplete. + +--- + +## Failure 8: We hedged every pattern and the synthesis reads as wishy-washy + +**Symptom.** "Users may sometimes occasionally seem to indicate." Every claim caveated. The synthesis avoids commitment. + +**Diagnosis.** Hedge stacking. The researcher did not commit to what the data showed. + +**Cure.** Rewrite with conviction. Name patterns as if the data supports them. If the data does not support the position, name a smaller position the data does support; do not hedge an oversized claim. + +**Prevention.** During pattern naming, apply the conviction test. Hedge stacking signals a pattern that should either be sharpened or dropped. + +--- + +## Failure 9: Our quote walls were impressive but the deck was 60 slides + +**Symptom.** Beautiful quote pulls; designed personas; 60 slides. Readers admired the deck. Few remember the patterns. + +**Diagnosis.** Insight-theater. Evidence dominated; analysis receded. Quote walls without analytical bridge. + +**Cure.** Restructure as a document. Patterns lead; evidence in appendix. Quote walls converted into evidence-summary paragraphs supporting each pattern. + +**Prevention.** The format choice is upstream. Default to documents; reserve decks for short executive summaries paired with substantive documents. + +--- + +## Failure 10: The synthesis recommended 20 product changes; we shipped one + +**Symptom.** Synthesis presents many implications. Team picks the easiest or most-vocal one to ship. The rest sit in the synthesis document unaddressed. + +**Diagnosis.** Wishlist synthesis. Implications did not acknowledge cost or prioritize within themselves. The synthesis offloaded prioritization to the team without giving them a starting point. + +**Cure.** Re-prioritize within the synthesis. Each implication gets a cost note. The synthesis recommends a sequence: which implications to address now, which to defer, which to drop. The team has a starting point for prioritization. + +**Prevention.** During implication writing, surface cost. The synthesis owner uses available context to estimate cost; pairs with engineering for harder estimates. Cost-blind synthesis is incomplete. + +--- + +## Failure 11: Adjacent teams disagreed with our patterns and we did not engage + +**Symptom.** Synthesis ships. Support team says "this does not match what we see in tickets." Sales team says "our prospects say something different." The synthesis fails to align with the teams closest to the customer. + +**Diagnosis.** Adjacent-team review skipped or compressed. The synthesis reached publication without surfacing perspectives the research team did not have. + +**Cure.** Pause publication. Run the adjacent-team review even after the fact. Revise based on inputs. + +**Prevention.** Build adjacent-team review into the synthesis workflow. Make it non-negotiable. The teams closest to the customer have ground-truth observations the research team needs. + +--- + +## Failure 12: Data gaps buried in the synthesis + +**Symptom.** Synthesis presents conclusions where the data did not support them. The recommendations sound confident; the data is thin in places the synthesis did not name. + +**Diagnosis.** The we-have-enough trap. Sunk-cost reasoning suppressed honest gap-naming. + +**Cure.** Audit each pattern for data sufficiency. Where gaps exist, name them explicitly. Where recommendations rest on under-supported patterns, downgrade or hedge them honestly. + +**Prevention.** The synthesis owner's job is to be honest about what the data can and cannot support. The team relies on the synthesis owner for this honesty. + +--- + +## Failure 13: Synthesis sequence stages skipped + +**Symptom.** Synthesis arrives at "patterns" without going through the tagging and clustering stages. Patterns feel imposed on the data rather than emerging from it. + +**Diagnosis.** Stages skipped. Researcher jumped to pattern-naming based on impressions from reading transcripts. + +**Cure.** Restart the sequence from tagging. Patterns from skipped sequences are usually projections; tagging-grounded patterns are observations. + +**Prevention.** The sequence is non-negotiable. Every synthesis runs through transcribe, tag, cluster, name, imply, so-what. + +--- + +## Failure 14: Synthesis owner became defensive in the review + +**Symptom.** Adjacent teams raise concerns; synthesis owner argues against each one; the review session produces no revisions; synthesis ships unchanged. + +**Diagnosis.** Defensive review posture. The owner treated review as defense of the synthesis rather than as input to it. + +**Cure.** Owner takes notes; does not defend in the moment; revises based on inputs over the following days. Reviewer concerns surface in the revision; the synthesis improves. + +**Prevention.** Establish the review session's purpose explicitly: input, not approval. The synthesis owner's job in the session is to listen. + +--- + +## The cross-cutting pattern + +Most synthesis failures share a single root: treating synthesis as documentation work rather than as decision work. + +Documentation work prioritizes capturing the research; producing a deliverable; performing for an audience. Output: artifacts that look like synthesis but do not drive decisions. + +Decision work prioritizes producing direction; committing positions; informing prioritization. Output: synthesis that team members reference for months, that drives roadmap shifts, that earns the research investment. + +The fix for almost any synthesis failure starts with the same question: what decision is this synthesis supposed to inform? When the answer is clear, the synthesis becomes load-bearing. When the answer is "we should document the research," the synthesis fails as decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting documentation-vs-decision pattern. + +## Implementation choices that stay internal + +Specific reviewer training on synthesis-failure detection. Specific automation that flags synthesis structures (e.g., document length checks, hedge-frequency analysis). Specific reviewer dashboards. The team's own conventions for catching synthesis failures pre-publish. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md new file mode 100644 index 0000000..1ed2d6b --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md @@ -0,0 +1,192 @@ +# From pattern to product implication + +The bridge from observation to decision. Implications are where synthesis adds value beyond transcription. + +A pattern without an implication is a finding. A finding describes the world; an implication proposes action. Synthesis stops at findings; actionable synthesis reaches implications. + +--- + +## Implications are the writer's analytical work, not what the user said + +**The principle.** Users describe their experience; PMs interpret what experience implies for the product. + +**Why this matters.** A common synthesis failure is presenting implications as if they came from users. "Users want X" treated as an implication. But users do not always know what would actually solve their problem; they describe symptoms, not solutions. + +**Worked example.** A pattern: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +- What users said: "I had to stop and find my credit card." +- What users want (per their own description): "Make signup not require credit card details." +- What the implication actually is (PM analytical work): defer the credit-card-requiring step to after first success state, OR remove the credit card requirement at signup, OR allow signup without credit card and request it before paid features. + +The implication options surface from analytical interpretation, not from user prescription. Users said the symptom; the PM proposes the system response. + +**The discipline.** Frame implications as the team's analytical position grounded in the pattern, not as user requests. "The pattern implies X" rather than "Users want X." + +--- + +## Each pattern can have multiple implications + +**The principle.** Synthesis surfaces options; the prioritization decision picks one. + +**Worked example.** A pattern: "Free users hit the upgrade prompt before experiencing paid value." + +Possible implications: + +- Delay the upgrade prompt until after the user has experienced the value-realization moment. +- Show the upgrade prompt earlier but reframe it as exploratory rather than transactional. +- Add a value-realization moment earlier in the free experience to align with the existing prompt timing. +- Remove the upgrade prompt entirely; let users discover paid features through usage. + +Each implication is a different product response. The synthesis presents the options; the team's prioritization debate picks one (or sequences several). + +**Why multi-implication matters.** Single-implication synthesis presents the synthesizer's preferred solution as if it were the only solution. Multi-implication synthesis surfaces options the team can debate. + +**The presentation.** Per pattern, surface 2-4 candidate implications. Acknowledge tradeoffs between them. Recommend if the data supports a recommendation; otherwise present the options for prioritization. + +--- + +## Implications should be falsifiable + +**The principle.** A vague implication cannot be acted on or debated. A specific implication can. + +**Vague implications.** + +- "We should improve onboarding." +- "Pricing should be reconsidered." +- "Mobile experience needs attention." + +These are too vague to drive decisions. The team agrees to "improve onboarding" without committing to any specific change. + +**Falsifiable implications.** + +- "Defer configuration step 3 to after first success state." +- "Add a value-realization moment within the first 90 seconds of signup." +- "Make the homepage hero copy lead with B2B use cases." + +These commit specific positions. The team can debate them, scope them, kill them, prioritize them. + +**The test.** For each implication, ask: could the team disagree with this and explain why? If the implication is vague enough that disagreement is impossible, the implication is too vague to be useful. + +--- + +## Implications should acknowledge cost + +**The principle.** Patterns suggest solutions; solutions cost product capacity. Synthesis that ignores cost produces wishlists. + +**The pattern that fails.** Synthesis recommends 30 product changes without acknowledging that delivering them all is impossible. The team takes one or two; the rest sit. The synthesis produced no actionable input because the team had no help prioritizing. + +**The pattern that works.** Each implication includes an estimated cost dimension and a recommendation about whether the cost is justified. + +- "Defer configuration step 3 (medium engineering cost; high expected impact on signup conversion)." +- "Pre-populate step 3 with sensible defaults (low engineering cost; medium expected impact)." +- "Remove credit card requirement entirely (high cost across systems; uncertain impact)." + +The cost annotations help the team prioritize without re-doing the synthesis work. + +**The discipline.** PMs doing synthesis usually have enough context to estimate cost roughly. If they do not, they can pair with engineering to estimate. Cost-blind synthesis is incomplete. + +--- + +## Some patterns imply not-acting + +**The principle.** Sometimes the pattern reveals friction the team should not address. + +**When not-acting is honest.** + +- The friction affects too few users to justify the engineering cost. +- The friction reveals segment misfit; the affected users are not the team's target. +- Addressing the friction would compromise other priorities or product positioning. +- The friction is real but the proposed solutions are worse than the problem. + +**Worked example.** A pattern: "Enterprise users want admin controls that small-team users do not need." + +Implications: + +- Build the admin controls (high cost, expands target market). +- Build the admin controls only for the enterprise tier (medium cost, segment-specific). +- Do not build (acknowledges enterprise as not the target segment). + +If the team is committed to small-team users as the target market, the not-act implication is honest; building enterprise admin controls would dilute focus. + +**The naming discipline.** When the synthesis recommends not-acting, name it explicitly. "The pattern is real but the recommended response is to not address it because [reason]." Buried not-act implications get overlooked; the team adds the unaddressed friction to the next quarter's roadmap because nobody surfaced the not-act case. + +--- + +## Implications that bridge to specific decisions + +**The principle.** The strongest implications point to a specific decision the team is making. + +**Implication-to-decision mapping.** + +- Implication: "Defer configuration step 3." + - Decision input: should the Q2 roadmap include the onboarding redesign? (Yes, with this approach.) +- Implication: "Add B2B-leading homepage hero." + - Decision input: should the homepage redesign be prioritized this quarter? (Yes, with positioning shift.) +- Implication: "Do not address enterprise admin controls." + - Decision input: should enterprise tier be in this year's roadmap? (No; small-team focus continues.) + +**Why decision-mapping matters.** Implications floating free of decisions produce a list the team must connect to its prioritization work themselves. Implications mapped to decisions produce direct input. + +--- + +## Implication strength and confidence + +**The principle.** Not all implications are equally well-supported. + +**Strong implications.** + +- Pattern is supported by multiple research types (interviews + tickets + survey). +- Implication has a clear analytical bridge from the pattern. +- Cost is reasonable relative to expected impact. +- Decision input is clear. + +**Weaker implications.** + +- Pattern is supported by limited evidence (3 interviews; thin volume). +- Implication is one of several plausible options without clear analytical bridge. +- Cost is uncertain. +- Decision input is hedged. + +**The discipline.** Synthesis labels implications by strength. Strong ones get presented as recommendations; weaker ones as options for further investigation. The team can prioritize confidently when it knows which implications carry weight. + +--- + +## Common pattern-to-implication failures + +**Implications that restate the pattern.** "The pattern shows X. The implication is X." No analytical bridge; no value added. + +**Wishlist implications.** Synthesis recommends 30 changes; the team cannot prioritize; one or two ship; the rest sit. + +**Implications buried in narrative.** The synthesis discusses the pattern at length; the implication is one sentence at the end. Readers miss it. + +**No cost acknowledgment.** Implications presented as if all are equal cost; team has to do the cost analysis itself. + +**Skipping the not-act implication.** Synthesis recommends action on every pattern; some patterns warrant not-acting; the synthesis fails to surface this honestly. + +**Implications that prescribe specific designs.** Implications should propose product responses, not detailed designs. Detailed designs are for spec writing; implications are the upstream input. + +--- + +## The implication-quality audit + +A short framework for auditing implications. + +1. Is each implication an analytical proposition, not a user request? +2. Are multiple candidate implications surfaced where appropriate? +3. Is each implication specific enough to be falsifiable? +4. Does each implication acknowledge cost? +5. Where the data supports not-acting, is that surfaced honestly? +6. Does each implication map to a specific decision? +7. Is implication strength labeled? + +Synthesis that passes this audit converts research into decisions. Synthesis that fails it produces findings that look like decisions but do not drive them. + +--- + +## Methodology-level choices that stay in the public skill + +The implication-as-analytical-work principle. Multi-implication patterns. Falsifiability. Cost acknowledgment. The not-act implication. Decision mapping. Implication strength. Common failures. The audit. + +## Implementation choices that stay internal + +Specific document templates that surface implications. Specific cost-estimation conventions. Specific cross-functional review patterns for cost validation. The team's own conventions for implication-strength labeling. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md new file mode 100644 index 0000000..26d6aac --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md @@ -0,0 +1,178 @@ +# Pattern naming patterns + +Pattern naming is the work that distinguishes synthesis from documentation. A pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references for months. + +The naming is not formatting. It is analytical work that surfaces what the data actually shows. Most synthesis underperforms because the pattern names did not do this work. + +--- + +## A pattern name is not a category label + +**The principle.** Categories describe topics; patterns describe specific observations the data reveals. + +**Examples.** + +- Category: "Onboarding." +- Pattern: "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." + +- Category: "Pricing." +- Pattern: "Free users hit the upgrade prompt before they have experienced the paid value, producing churn instead of conversion." + +- Category: "Mobile." +- Pattern: "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +**Why categories fail as pattern names.** Categories are containers. The synthesis with category-named patterns is a list of containers, not a list of observations. Readers cannot tell what the data showed; only what topic it concerned. + +**The test.** Does the pattern name commit a position about what the data reveals, or does it merely name a topic the data covered? Position-committing names are patterns; topic-naming labels are categories. + +--- + +## The name should make the implication legible + +**The principle.** A reader who sees only the pattern name should be able to guess the product implication. + +**Examples that pass the test.** + +- "Users abandon configuration step 3 because credit card details are not accessible during signup." + - Implication a reader can guess: defer configuration step 3 to after first success state, or remove credit card requirement at signup. +- "Sales prospects assume the product is for B2C because the homepage hero shows consumer use cases." + - Implication a reader can guess: revise homepage positioning to lead with B2B use cases. + +**Examples that fail the test.** + +- "Onboarding has issues." +- "Users have feedback about pricing." +- "There is mobile-related friction." + +**Why implication-legibility matters.** Synthesis exists to drive decisions. Pattern names that obscure implications force readers to do the analytical work themselves; many readers will not, and the synthesis fails to inform decisions. + +--- + +## Avoid category bloat + +**The principle.** Strong synthesis has 4-8 named patterns. Synthesis with 30 patterns is usually under-clustered: many of those are variations on a smaller number of underlying patterns. + +**Diagnosis of bloat.** + +- Look at the pattern list. Are some patterns sub-cases of others? If yes, the under-cluster is producing inflation. +- Are there patterns that always co-occur with other patterns? If yes, they may be the same pattern viewed from different angles. +- Are there patterns supported by 1-2 artifacts only? If yes, they may be noise being elevated to pattern status. + +**The cure.** Re-cluster. Take the 30-pattern list back to clustering and look for the 4-8 underlying patterns the data actually supports. + +**Why bloat fails.** Synthesis with 30 patterns produces no decision direction: the team cannot prioritize 30 things. Synthesis with 4-8 patterns surfaces what to focus on. + +--- + +## Avoid naming the obvious + +**The principle.** A pattern is a specific observation that the product team did not already know. Pattern names that read as truisms ("users want fast performance") are not patterns. + +**The truism trap.** + +- "Users want better performance." +- "Users find some aspects confusing." +- "Pricing is a consideration in the decision." +- "Mobile usage is increasing." + +These are descriptive of the universe; they do not describe what the research revealed. + +**The cure.** For each pattern name, ask: would this name have been just as accurate without the research? If yes, the pattern is a truism. The research must have surfaced something more specific; rewrite the name to capture it. + +**The "what the team did not know" test.** Strong pattern names commit a position the team would not have made before the research. Weak pattern names commit positions the team already held. + +--- + +## Name with conviction + +**The principle.** Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly. + +**Hedging vs precision.** + +- Hedged: "Some users may experience occasional difficulty in some configuration steps." +- Precise: "Users abandon configuration step 3 in 40% of signup attempts." + +The precise name is also commitment-bearing: it claims a specific behavior at a specific frequency. If the data does not support 40%, the name is wrong; the researcher should restate. The hedged name avoids being wrong by avoiding being specific. + +**Why conviction matters.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. Readers cannot debate hedged patterns; they cannot prioritize them; they cannot act on them. Conviction-named patterns invite challenge, which strengthens synthesis. + +**The discipline.** Name as if the data fully supports the position. If it does not, name a smaller position the data does support. Do not pad an under-supported position with hedging. + +--- + +## Pattern naming structures that work + +Several structures recur across strong synthesis. + +**The behavioral observation: "Users [do specific action] because [specific cause]."** + +Example: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +This structure forces specificity in both behavior and cause. + +**The contradiction: "Users [say X] but [do Y]."** + +Example: "Users in interviews report wanting more configuration options, but in support tickets request defaults that match their actual usage." + +This structure surfaces the gap between stated preference and revealed preference. + +**The segment difference: "[Segment A] [does X], while [Segment B] [does Y]."** + +Example: "Free users hit the upgrade prompt before experiencing paid value, while paid users encounter it after the value-realization moment." + +This structure surfaces sub-segment patterns the research revealed. + +**The mismatch: "[Team's framing] does not match [user's framing]."** + +Example: "Marketing positions the product as B2C-friendly; sales prospects evaluating for B2B use assume the product is consumer-only based on the homepage." + +This structure surfaces positioning gaps. + +**The frequency-specific: "[Specific behavior happens at frequency X across segment Y]."** + +Example: "30% of new users hit the configuration friction within 5 minutes of signup; the friction correlates with day-7 churn." + +This structure pairs qualitative observation with quantitative validation. + +--- + +## The pattern-name editing pass + +Strong synthesis runs a final editing pass focused only on pattern names. + +**For each pattern name, the editing questions.** + +1. Is this a category or a pattern? +2. Can a reader guess the implication from the name alone? +3. Is this a truism or a specific observation? +4. Does the name commit a position with conviction? +5. Does the name match what the data actually shows (no overstatement)? +6. Could this be split into multiple patterns or merged with another? + +**The editing investment.** 1-2 hours of focused name-editing on a 4-8 pattern set. The investment pays off in synthesis usability. + +--- + +## Common pattern-naming failures + +**Categories disguised as patterns.** "Onboarding patterns" as a section heading; nothing in the section actually names a pattern. + +**Patterns that hedge into nothing.** "Users may sometimes experience difficulty"; the name commits no position. + +**Truism patterns.** "Users want fast performance"; the name describes the universe, not the data. + +**Vague specificity.** "Configuration step 3 is problematic"; specific enough to seem like a pattern, vague enough to not be one. + +**Pattern bloat.** 30 named patterns; the synthesis loses focus and produces no priorities. + +**Patterns named without evidence ties.** Synthesis where readers cannot trace each pattern to specific artifacts and quotes. Patterns become assertions rather than observations. + +--- + +## Methodology-level choices that stay in the public skill + +The category-vs-pattern distinction. The implication-legibility test. The avoid-bloat principle. The avoid-truism principle. The conviction principle. The pattern-name structures that work. The editing pass. Common naming failures. + +## Implementation choices that stay internal + +Specific document templates that surface pattern names prominently. Specific reviewer rubrics for editing pattern names. Specific A/B testing of pattern name variants for clarity. The team's own conventions for pattern count within the bands. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md new file mode 100644 index 0000000..341f05f --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md @@ -0,0 +1,221 @@ +# Research types and when each fits + +Five common discovery research types, what each surfaces, what synthesis they support, and how to compose them within a single discovery cycle. + +Research-type selection is upstream of synthesis. The wrong types collected for the question produce data that synthesis cannot rescue. The right types collected, even at modest scale, produce synthesis that drives decisions. + +--- + +## Customer interviews + +**Format.** 30-90 minute conversations, structured or semi-structured. Often one-on-one, sometimes in pairs or small groups for specific contexts. + +**Artifacts.** Recordings, transcripts, moderator notes, sometimes follow-up email exchanges. + +**What this surfaces.** + +- Why users do what they do (motivation, context, constraints). +- The struggling moments and workarounds users have built. +- The mental model behind user behavior. +- The trade-offs users are weighing that the team did not anticipate. +- The vocabulary users actually use (often different from internal product language). + +**What this does not surface.** + +- What users actually do in practice (interview self-report differs from behavioral data). +- Patterns that emerge only at scale (a single interview is one data point). +- Pricing willingness to pay (interview answers about price are notoriously unreliable). + +**Synthesis implications.** + +- Highest per-artifact richness; warrants careful per-transcript tagging. +- Best paired with other research types that quantify the qualitative patterns. +- Pattern thinness risk: 8-15 interviews surfaces patterns; 3-5 surfaces hypotheses that need more validation. + +**Typical batch size.** 8-15 interviews per discovery cycle. Larger batches saturate (most patterns emerge by interview 8-10 in a focused topic). + +--- + +## Support ticket reviews + +**Format.** Audit of recent support tickets, often spanning a defined time window or a defined product area. + +**Artifacts.** Tagged ticket dataset, agent-conversation transcripts, sometimes recorded support calls. + +**What this surfaces.** + +- The friction users actually hit (revealed by ticket volume). +- The vocabulary users use to describe broken experiences. +- The disconnect between intended user flow and actual user behavior. +- Repeated workflows that produce confusion or errors. +- Documentation and onboarding gaps. + +**What this does not surface.** + +- Why users got there (the ticket starts at the problem; the path before is not visible). +- The experience of users who did not contact support (silent struggling). +- Users who succeed without friction. + +**Synthesis implications.** + +- Lower per-artifact richness; higher volume; signal lives in patterns across many tickets. +- Best for surfacing concrete friction points; weak for understanding motivation. +- Often pairs with interviews (interviews explain why; tickets document where). + +**Typical batch size.** 100-500 tickets per audit, often filtered by topic or product area. + +--- + +## Sales call analysis + +**Format.** Recording or transcript review of recent sales calls. Often pairs with sales team feedback on patterns they hear repeatedly. + +**Artifacts.** Call recordings, sales notes, CRM-tagged objections, deal-stage data. + +**What this surfaces.** + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Use cases prospects describe (sometimes different from how marketing describes the product). +- Words prospects use to describe their situation (vocabulary signal). + +**What this does not surface.** + +- Existing-customer experience (sales calls are pre-purchase). +- Why prospects who did not buy did not buy (lost-deal analysis is a separate research mode). + +**Synthesis implications.** + +- Pairs well with positioning and pricing decisions. +- Useful for marketing-product alignment work. +- Sales teams often have synthesis hypotheses already; the research either confirms or challenges those. + +**Typical batch size.** 15-30 calls per audit. + +--- + +## Survey data + +**Format.** Quantitative responses to structured questions, often with optional qualitative comments. + +**Artifacts.** Response dataset, segmented by audience attributes. + +**What this surfaces.** + +- The frequency and severity of patterns identified through other research. +- Segment differences (do Pro users and Free users have different needs). +- Quantitative validation of qualitative hypotheses. +- Aggregate satisfaction or NPS-style sentiment. + +**What this does not surface.** + +- Why users responded the way they did (closed-ended responses do not explain). +- Patterns that the survey questions did not anticipate (surveys cannot find what they did not ask about). +- Behavior (surveys reveal what users say, not what they do). + +**Synthesis implications.** + +- Best as validation of qualitative patterns at scale, not as primary discovery. +- Survey design biases (leading questions, response order effects, satisficing) compromise data; treat with skepticism. +- Open-ended comments are often the highest-value section of a survey. + +**Typical batch size.** 100-2,000 responses, depending on segment specificity. + +--- + +## In-app feedback + +**Format.** Users submitting feedback through in-product channels (feedback widgets, NPS prompts, post-task surveys, error-state feedback forms). + +**Artifacts.** Submitted feedback corpus, often timestamped and contextualized by where in the product the feedback was triggered. + +**What this surfaces.** + +- Friction at the moment users encounter it (high context fidelity). +- Patterns across many low-effort submissions. +- Feature requests grounded in specific usage moments. +- Bugs and broken experiences not captured by support. + +**What this does not surface.** + +- Users who did not bother to submit feedback (silent majority). +- Why users hit the friction (the feedback names the problem; not always the cause). +- Patterns from users who do not actively use the feedback channels. + +**Synthesis implications.** + +- Volume varies widely; some products see high in-app feedback volume, others minimal. +- Often pairs with support tickets (similar surface area; different submission channels). +- Useful as ongoing signal; this skill is more about the periodic-audit case (`user-feedback-aggregation` covers continuous synthesis). + +**Typical batch size.** Ongoing; synthesized in periodic audits over defined windows. + +--- + +## Composition across types + +Strong discovery cycles combine research types deliberately. + +**The pair-and-validate pattern.** + +- Interviews (depth, ~12 conversations) provide qualitative patterns. +- Support tickets (volume, ~300 tickets) document where friction surfaces in practice. +- Survey (validation, ~500 responses) quantifies the patterns at scale. +- Synthesis weaves all three: interview patterns ground the why, tickets ground the where, survey grounds the how-many. + +**The triangulate-the-decision pattern.** + +- A specific decision (should we redesign onboarding) gets evidence from three sources. +- Interviews surface the experience of recent signups. +- Sales calls surface what prospects say onboarding will look like. +- Support tickets surface what new users actually hit. +- Synthesis converges three perspectives on the same decision. + +**The single-type sufficiency pattern.** + +- Some discovery questions only need one type. A pricing review might need only sales call analysis. A support-volume reduction effort might need only ticket analysis. +- Discipline: do not commission research types that will not contribute to the decision. + +**The wrong-pairs to avoid.** + +- Interviews + survey only, with no behavioral data: both are self-report; both can be wrong in the same direction. +- Survey only, no qualitative: the survey assumes the questions are right. +- Sales calls only, no customer voice: the prospect view is one segment; existing-customer voice may differ. + +--- + +## Research-type pitfalls per type + +**Interview pitfalls.** Recruiting bias (the easiest-to-recruit users are not always representative). Leading questions. Confirming the team's prior hypothesis rather than challenging it. Small-batch over-generalization. + +**Support ticket pitfalls.** Survivorship bias (only users who contacted support are visible; users who silently churned are not). Tag quality (poor tagging compounds in synthesis). Time-window choice (a window that misses recent product changes can mislead). + +**Sales call pitfalls.** Stage selection (early-stage discovery calls and late-stage closing calls reveal different things). Sales-team interpretation (sales reps' framings can color how calls are tagged). Anonymization vs detail (privacy needs can erase the specifics that matter). + +**Survey pitfalls.** Response bias (who responds is not representative of who is asked). Question wording. Ordering effects. Satisficing (respondents click through without engaging). Falsely-precise quantitative output from low-quality data. + +**In-app feedback pitfalls.** Channel bias (the kinds of users who submit in-app feedback differ from those who do not). Volume-driven prioritization (loudest categories get attention; quieter ones get missed). + +--- + +## When to commission what + +A short framework. + +1. **Decision driving the research.** What product decision is this research meant to inform? +2. **Best research type for that decision.** Discovery (interviews lead), validation (survey or quantitative leads), friction-mapping (support and in-app feedback lead), positioning (sales call analysis leads). +3. **Composition.** Which secondary types triangulate the primary? +4. **Capacity.** What can be collected within the time and budget the decision allows? +5. **Existing data check.** Has the team already collected research that would answer the question? Mining existing artifacts often produces value before commissioning new research. + +--- + +## Methodology-level choices that stay in the public skill + +The five research types and what each surfaces. The composition patterns. The wrong-pairs to avoid. The pitfalls per type. The when-to-commission framework. The principle that research-type selection is upstream of synthesis quality. + +## Implementation choices that stay internal + +Specific recruiting platforms and incentive structures. Specific transcription tooling. Specific support-ticket platforms and their tagging schemas. Specific survey tools and statistical-significance configurations. Specific in-app feedback widgets and integration patterns. The team's own conventions for sample sizes within the bands. These vary by team, budget, and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md new file mode 100644 index 0000000..4043285 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md @@ -0,0 +1,177 @@ +# Synthesis review and validation + +How synthesis gets pressure-tested before it drives decisions. Review and validation surface synthesis errors that the research team missed: fabricated patterns, projected interpretations, missing dissent, segment misreads. + +The discipline is making review non-negotiable. Synthesis that ships without review carries unacknowledged blind spots; review compresses those blind spots before the synthesis becomes the team's working document. + +--- + +## Internal review with research participants where possible + +**The principle.** Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? + +**Why participant review matters.** + +- Participants are the only authoritative source on whether the synthesis represents their experience. +- Misrecognition signals fabrication: the synthesis projected interpretations the data did not support, or named patterns that did not match what participants actually said. +- Recognition validates the synthesis: participants endorse the patterns as accurate representations. + +**The mechanics.** + +- Send the synthesis (or relevant excerpts) to 3-5 research participants for review. +- Ask: "Do these patterns reflect your experience? Anything missing? Anything the synthesis got wrong?" +- Build participant recognition into the research design from the start (with consent for follow-up review). + +**The exception.** Some research types (large-scale survey, anonymous in-app feedback) do not support participant review at the individual level. For those, validation depends on aggregate quantitative checks (the next section). + +**The honest disclosure.** When participant review surfaces misrecognition, the synthesis revises rather than dismissing the feedback. Synthesis that dismisses participant pushback is reverting to confirmation bias. + +--- + +## Adjacent-team review + +**The principle.** Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? + +**Why adjacent-team review matters.** + +- Adjacent teams have ground-truth observations the research did not access. Support sees the friction users hit every day; sales hears prospect objections; engineering knows which problems are technically tractable. +- Adjacent teams catch synthesis errors that the research team missed: patterns that contradict what support handles daily, implications that ignore engineering constraints. +- Adjacent teams' alignment with synthesis affects whether the synthesis drives decisions: if support disagrees with the support-related patterns, the synthesis loses authority. + +**The mechanics.** + +- Share the synthesis with relevant adjacent-team leads for review. +- Hold a structured review session where adjacent teams can challenge, validate, or extend the patterns. +- Capture adjacent-team observations as inputs to synthesis revision. + +**Common adjacent-team feedback patterns.** + +- Support: "Your synthesis names X as a pattern, but support tickets show Y is also load-bearing and not in the synthesis." +- Sales: "Prospects do say what your synthesis claims, but the patterns you missed are the pricing-conversation friction." +- Engineering: "The implication you propose has a constraint the synthesis did not account for." + +The synthesis revises in light of these inputs. + +--- + +## Quantitative validation where possible + +**The principle.** Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. + +**The validation pattern.** + +- Synthesis says: "Users abandon configuration step 3 because credit card details are not accessible at signup." +- Quantitative validation: pull analytics on configuration step 3 abandonment rate. Does the data confirm 40% abandonment that the pattern implies? Does abandonment correlate with the credit card requirement (versus other possible causes)? +- If the data confirms: the pattern is strongly supported. +- If the data does not confirm: the pattern needs revision; the qualitative signal may not generalize. + +**Why validation matters.** + +- Qualitative patterns can overstate frequency; small-sample interview signal does not always match large-sample reality. +- Quantitative validation grounds synthesis in scaled data without requiring the synthesis to be quantitative-only. +- Validation reveals which patterns are strong enough to act on and which need more investigation. + +**See `experiment-design`** for rigorous A/B testing as quantitative validation. **See `product-analytics-setup`** for the instrumentation that makes validation possible. + +**The honest disclosure.** When quantitative validation contradicts qualitative patterns, the synthesis adjusts. Patterns the analytics does not support get downgraded or removed. Synthesis that ignores quantitative pushback in favor of qualitative claims is unrigorous. + +--- + +## The "challenge the synthesis" session + +**The principle.** A specific session where adjacent teams try to find what the synthesis missed, overstated, or railroaded. + +**The session structure.** + +- Synthesis owner presents the patterns and implications (15-30 minutes). +- Adjacent-team participants challenge: "What patterns did the research miss? What implications overstate the data? What decisions is the synthesis trying to railroad?" +- Synthesis owner takes notes; does not defend; the session is for surfacing concerns, not for resolution in the moment. +- Synthesis owner revises based on the inputs over the following days; revised synthesis circulates back. + +**Why this works.** + +- Productive disagreement strengthens synthesis. The team that surfaces concerns is contributing to better synthesis, not undermining the research investment. +- The session creates space for honest pushback that quieter review formats sometimes suppress. +- The session signals that synthesis is open to challenge, which strengthens the team's trust in the synthesis once it ships. + +**The anti-pattern.** Synthesis owners who treat the session as defense of the synthesis rather than as input to the synthesis. The owner pushes back on every challenge; adjacent teams disengage; synthesis ships unrevised. + +**The discipline.** The synthesis owner's job in the session is to listen and capture, not to defend. Defense happens in the revision; pushback happens later, after considering the input. + +--- + +## Iterate before publishing + +**The principle.** Synthesis goes through revision based on the review loop. Synthesis that ships in first-draft state usually carries unacknowledged blind spots. + +**The iteration cycle.** + +- First draft from the synthesis owner. +- Participant review (where possible). +- Adjacent-team review (always). +- Challenge-the-synthesis session. +- Revision based on inputs. +- Final review by senior product leader for clarity and quality. +- Publication. + +**Time investment.** The review-and-iteration loop adds 1-2 weeks to the synthesis timeline. That investment is small relative to the cost of publishing synthesis with blind spots that produce wrong decisions. + +**Common iteration outputs.** + +- Patterns split (the original pattern was actually two patterns adjacent teams distinguished). +- Patterns merged (the original separation was not load-bearing). +- Patterns revised (the framing did not match the data on closer review). +- Implications expanded (additional implications surfaced during review). +- Implications narrowed (some implications overstepped what the data supports). +- Decision input refined (the original was too vague to drive decisions). + +--- + +## When the review loop reveals the synthesis cannot be saved + +**The honest case.** Sometimes review surfaces synthesis problems too deep to fix in revision: patterns built on insufficient data, projections the data did not support, framing that adjacent teams flatly contradict. + +**The response.** + +- Stop. Do not publish synthesis with known significant problems. +- Re-examine: was the underlying research adequate? Was the synthesis sequence run completely? Were the patterns named with conviction or projected? +- Restart from where the breakdown happened. Often returns to clustering or pattern-naming. +- Sometimes returns to gathering more research. The honest case is acknowledging that the discovery cycle did not produce sufficient input for reliable synthesis. + +**The cost calibration.** Restarting synthesis costs PM time. Publishing flawed synthesis costs the team's trust in research output, plus the wrong decisions the flawed synthesis drives. The latter is usually more expensive. + +--- + +## What review does not do + +**Review does not validate every synthesis.** Some synthesis fails review and should not ship; some passes with revision; some passes with minor adjustment. Review is the discipline that distinguishes the cases. + +**Review does not eliminate disagreement.** Adjacent teams may continue to disagree even after review. The synthesis owner makes the final call after considering inputs. Disagreement preserved in the published synthesis is fine and honest; pretended consensus is not. + +**Review does not slow shipping artificially.** A 1-2 week review loop on substantive synthesis is appropriate. Quick-turn synthesis (short audits, focused interview batches) can run a lighter review (asynchronous comments from 2-3 reviewers; adjacent-team check; ship). + +--- + +## Common review-and-validation failures + +**Skipping participant review.** Synthesis ships without participants ever seeing the patterns; participants would have caught misrecognitions; the synthesis carries projection. + +**Skipping adjacent-team review.** The team most likely to know the data is wrong did not see the synthesis before publication. + +**Defensive review sessions.** The synthesis owner argues against challenges instead of capturing them; the session produces defense rather than input. + +**Quantitative validation skipped.** The qualitative patterns went unchallenged by available analytics data; the synthesis overstates patterns the data does not support. + +**Iteration compressed to one round.** First draft + one review + ship. Most synthesis benefits from two rounds of revision: first round on substance, second round on presentation. + +**Review feedback dismissed.** Adjacent teams raise concerns; synthesis owner notes them but does not revise. Synthesis ships as if the feedback did not happen. + +--- + +## Methodology-level choices that stay in the public skill + +The participant review pattern. The adjacent-team review pattern. Quantitative validation. The challenge-the-synthesis session. Iteration discipline. The cannot-be-saved escalation. What review does and does not do. Common review failures. + +## Implementation choices that stay internal + +Specific reviewer pairings and roles. Specific session formats and facilitation. Specific revision tracking. Specific publication conventions. Specific quantitative validation pipelines. The team's own conventions for review-loop length. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md new file mode 100644 index 0000000..5a9b6f3 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md @@ -0,0 +1,229 @@ +# Synthesis sequence walkthrough + +The six-stage synthesis sequence with worked example. Stage outputs, common skip-failures, time investment per stage. + +The sequence is non-negotiable. Teams that skip stages produce findings that look like synthesis but are not: untagged transcripts, unclustered tags, unnamed patterns, patterns without implications, implications without decisions. Each stage builds on the previous; skipping any stage breaks the chain. + +--- + +## The six stages + +1. **Transcribe and prepare.** Convert artifacts into a synthesizable format. +2. **Tag at the artifact level.** First-pass descriptive tagging. +3. **Cluster across artifacts.** Group tags into themes. +4. **Name patterns.** Each cluster becomes a named pattern. +5. **Infer product implications.** What does each pattern imply. +6. **Name the so-what.** The decision input. + +--- + +## Stage 1: Transcribe and prepare + +**The work.** Convert artifacts into a format you can read, mark up, and search. + +**Outputs.** + +- Interview transcripts, time-stamped, speaker-labeled. +- Support ticket dataset, exported to a workable format with relevant fields (subject, body, resolution, tags, dates). +- Sales call summaries or transcripts. +- Survey data with open-ended responses extracted into a reviewable format. + +**Time investment.** Often underestimated. A 60-minute interview takes 60-90 minutes to transcribe (with AI tools) plus 30-60 minutes to clean. Eight interviews: 12-20 hours of prep before tagging starts. + +**Common skip-failures.** + +- Skipping transcription on the assumption that the recordings are sufficient. Reality: tagging from audio is impractical at any meaningful batch size. +- Cleaning to the point of distortion (removing the messy parts that contain signal). +- Skipping speaker labels (collapsed dialog loses critical context). + +**The unglamorous-but-essential principle.** Teams that skip prep work never reach the later stages because the artifacts are not workable. The investment in prep pays back across every later stage. + +--- + +## Stage 2: Tag at the artifact level + +**The work.** Read each transcript or ticket and tag it with topics, problems, quotes, and observations. + +**Outputs.** + +- Tagged artifacts (transcripts, tickets, etc.) with descriptive tags inline. +- A tag list (often 80-150 tags per batch by the end of this stage). +- Quote pulls (specific sentences worth referencing later). + +**Approach.** + +- First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. +- Allow tag proliferation. Do not force consolidation in this stage; that is for clustering. +- Tag dissent and contradictions explicitly. "User reports liking the onboarding" alongside other users reporting friction is signal; tag it. +- Mark quotes worth pulling. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. + +**Time investment.** Per artifact: 30-90 minutes for an interview transcript, 1-3 minutes per support ticket, 15-30 minutes per sales call. A typical batch (12 interviews + 200 tickets + 20 sales calls) might run 25-40 hours of focused tagging work. + +**Common skip-failures.** + +- Pre-designing the tag taxonomy and forcing artifacts into it. +- Tagging from memory after reading the transcript rather than during reading. +- Premature consolidation (collapsing tags during this stage instead of later). +- Skipping the contradictions (only tagging the dominant pattern). + +**The artifact-level discipline.** Each tag is grounded in a specific moment in a specific artifact. Tags floating free of evidence are a stage-2 failure that compounds in later stages. + +--- + +## Stage 3: Cluster across artifacts + +**The work.** Group tags into themes that surface the patterns the data reveals. + +**Outputs.** + +- A cluster list (often 6-15 clusters from the 80-150 tags). +- Per-cluster tag membership. +- Per-cluster artifact source list (which artifacts contributed to this cluster). + +**Approach.** + +- Cluster on the underlying observation, not on tag overlap. Two tags that co-occur may not be the same pattern. +- Iterate: first-pass clustering will reveal that some tags belong in multiple clusters; some clusters are too broad; some need to split. +- Use the artifact-source list to test cluster strength. A cluster with 8 supporting artifacts is stronger than one with 2. +- Track the dissent: which clusters have countervailing evidence the synthesis must address. + +**Time investment.** 4-8 hours of clustering work for a batch this size. Often done collaboratively with another reviewer to surface alternative groupings. + +**Common skip-failures.** + +- Clustering on assumed categories rather than emergent themes. +- Stopping at first-pass clustering without iterating. +- Ignoring artifact-source counts (clusters with thin support get weighted equally with strong ones). +- Forcing every tag into a cluster (some tags are noise; that is fine). + +--- + +## Stage 4: Name patterns + +**The work.** Each cluster becomes a named pattern that captures what the underlying observation actually is. + +**Outputs.** + +- A pattern list (typically 4-8 patterns from a strong synthesis). +- Per-pattern name, evidence summary, and source-artifact list. + +**Approach.** + +- Pattern name is specific enough that a reader can guess the implication. +- Pattern names commit a position: name what the data shows, not a category the data sits in. +- Avoid truisms: pattern names that read as something everyone could have said before the research are not patterns. +- Limit pattern count: 4-8 strong patterns serve synthesis better than 15 weak ones. + +**Time investment.** 2-4 hours of pattern-naming work. Often the highest-impact stage; investment in good pattern names pays off in implications and decisions. + +**Common skip-failures.** + +- Pattern names that are category labels (Onboarding, Pricing, Support). +- Pattern names that are truisms (Users want fast performance). +- Hedge-stacked pattern names (Users sometimes seem to occasionally maybe). +- Too many patterns (under-clustering manifests as pattern bloat). + +See `pattern-naming-patterns.md` for detail. + +--- + +## Stage 5: Infer product implications + +**The work.** For each pattern, name what this implies for the product. + +**Outputs.** + +- Per-pattern implication list (often 1-3 implications per pattern). +- Per-implication: specific, falsifiable, cost-acknowledged. + +**Approach.** + +- Each pattern can have multiple implications. Surface the options; do not pre-prioritize. +- Implications are the writer's analytical work, not what users said. Users describe experience; PMs interpret what experience implies. +- Make implications falsifiable. "We should improve onboarding" is not an implication; "Move the third configuration step to after first success state" is. +- Acknowledge cost. Implications that ignore implementation cost produce wishlists. +- Some patterns imply not-acting. Naming the not-act implication is honest synthesis. + +**Time investment.** 3-6 hours of implication work. + +**Common skip-failures.** + +- Vague implications that cannot be acted on or debated. +- Wishlist implications that do not acknowledge cost. +- Skipping the not-act implication when it would be honest. +- Implications that are restatements of the pattern (no analytical bridge). + +See `from-pattern-to-product-implication.md` for detail. + +--- + +## Stage 6: Name the so-what + +**The work.** For each implication, the specific decision it informs. + +**Outputs.** + +- Per-implication so-what statement tied to a real decision. +- An overall recommendation section: what should change as a result of this synthesis. + +**Approach.** + +- Map each implication to a decision the team is making (or should make). +- Be specific: "Should the Q2 roadmap include the onboarding redesign?" rather than "Onboarding should be considered." +- Surface the synthesis's overall recommendation: where to invest, where to deprioritize, where to gather more data before deciding. +- Acknowledge the decisions the synthesis cannot resolve: data gaps, contested patterns, decisions outside the synthesis's scope. + +**Time investment.** 2-4 hours of so-what work. + +**Common skip-failures.** + +- So-whats that are too abstract to drive decisions. +- Skipping the overall recommendation section (each pattern stands alone; the synthesis does not aggregate). +- Buried data gaps (the synthesis presents conclusions where the data did not support them). + +--- + +## Worked example + +A discovery cycle with 12 customer interviews + 250 support tickets + a sales call audit, focused on a possible onboarding redesign. + +**Stage 1 (prep).** 18 hours. Interview transcripts cleaned; ticket dataset extracted; sales call transcripts pulled. + +**Stage 2 (tagging).** 32 hours. 110 tags emerged across the artifacts. Quote pulls captured. + +**Stage 3 (clustering).** 6 hours. Clusters emerged: configuration-step friction, value-state delay, onboarding length, mobile-context onboarding, role-based mismatch, support-deflectable confusion. Six clusters with varying artifact support. + +**Stage 4 (pattern naming).** 3 hours. Six patterns named, including: + +- "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." +- "Free users reach the success state at half the rate of paid users because the configuration burden is the same but the value reveal is gated." +- "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +**Stage 5 (implications).** 4 hours. Per-pattern implications. Example for the configuration-step pattern: + +- Implication: defer configuration step 3 to after first success state, with a "complete your setup" prompt later. +- Cost: medium engineering investment; affects existing flows for users who completed step 3 historically. +- Alternative implication: pre-populate step 3 with sensible defaults from step 2 data where possible. +- Not-act implication: keep the current flow but improve docs (probably insufficient given the friction severity). + +**Stage 6 (so-what).** 3 hours. Decision input: yes, prioritize onboarding redesign in Q2; staged-onboarding approach; mobile parity is a sub-track within the redesign; configuration-step deferral is the headline change. + +**Total synthesis time.** 66 hours over the six stages. Roughly 1.5-2 weeks of focused synthesis work for one PM. + +--- + +## Time-investment patterns + +Synthesis sequences that go shorter than this are usually skipping stages. Sequences that go longer are usually over-investing in tagging or under-deciding in implications. The 60-80 hour range for a substantial discovery synthesis is typical. + +Programs that have not budgeted synthesis time often discover it after research ships and the synthesis stalls. The discipline is budgeting synthesis at the start of the discovery cycle, not as an afterthought. + +--- + +## Methodology-level choices that stay in the public skill + +The six-stage sequence with stage outputs and time investments. The worked example. The non-negotiability of the sequence. Common skip-failures per stage. + +## Implementation choices that stay internal + +Specific transcription tools. Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific document templates per output. Specific time-tracking conventions for synthesis budgeting. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md new file mode 100644 index 0000000..b09da20 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md @@ -0,0 +1,140 @@ +# Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. Tagging and clustering done badly produces bad patterns; tagging and clustering done well produces patterns that drive decisions. + +The discipline is in five principles that apply across both stages. + +--- + +## Principle 1: Tag at the artifact level first; do not pre-design the taxonomy + +**The pattern.** Tags emerge from the artifacts. The researcher reads each transcript and tags what is actually there. + +**The anti-pattern.** Researchers arrive at tagging with a pre-built taxonomy: "we will tag for usability, performance, pricing, support." Artifacts get forced into the categories. Patterns the taxonomy did not anticipate get missed. + +**Why pre-built taxonomies fail.** + +- The taxonomy reflects what the team already thinks; tagging confirms what the team already thinks; synthesis does not reveal anything new. +- Artifacts that do not fit the taxonomy categories get skipped or shoehorned in. +- Tags that emerge in the data but were not in the taxonomy do not get captured. + +**The exception.** Some categorical metadata is fine to apply consistently (user segment, source channel, recency). The semantic tagging that drives synthesis should still emerge from the data. + +**The recovery.** Mid-tagging, if the team realizes the pre-built taxonomy is constraining, it can be discarded and tagging restarted with descriptive tags emerging from artifacts. Better to restart than to publish synthesis grounded in a constraining taxonomy. + +--- + +## Principle 2: Allow tag proliferation; collapse later + +**The pattern.** First-pass tagging produces 80-150 tags across a batch. That is correct. Premature consolidation loses distinctions that turn out to matter. + +**The anti-pattern.** Researchers consolidating tags during the tagging stage. "We had four onboarding tags; let me merge them into one." The merge happens before the researcher has seen whether the four tags actually represent different patterns. + +**Why proliferation matters.** + +- Some distinctions only become visible after seeing many artifacts. Two tags that seem similar at artifact 3 may turn out to be different patterns by artifact 12. +- Granular tags can always be collapsed in the clustering stage; collapsed tags cannot be unmerged once the tagging is done. +- Proliferation supports the discovery posture; consolidation supports the confirmation posture. + +**The volume calibration.** A batch of 12 interviews + 250 tickets + 20 sales calls might end with 80-150 tags. Fewer than that often signals premature consolidation; more than that may signal undisciplined tagging. + +--- + +## Principle 3: Cluster on patterns, not on tag overlap + +**The pattern.** Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation, not on statistical co-occurrence. + +**The anti-pattern.** Tools that auto-cluster by co-occurrence. They produce statistical groupings that do not always match the patterns the researcher needs. + +**Why pattern-clustering matters.** + +- "Slow onboarding" and "configuration friction" might co-occur because both are common; that does not mean they are the same pattern. They might be the same (configuration is what makes onboarding feel slow) or different (there is friction in configuration AND there is a perception of length independent of configuration). +- The researcher's interpretation of the artifact-level tags is what surfaces the pattern; tools can suggest groupings but cannot determine them. + +**The work.** For each candidate cluster, ask: are the underlying observations the same, or do they share a tag because the tag was loose? If the latter, split the cluster. + +--- + +## Principle 4: Name the cluster after clustering, not before + +**The pattern.** The cluster name comes from the data after the clustering work is done. + +**The anti-pattern.** Researchers arriving with named clusters and slotting data into them. The clusters become hypothesis-confirmation rather than discovery. + +**Why post-cluster naming matters.** + +- Pre-named clusters bias the clustering: tags get assigned to clusters they fit linguistically rather than substantively. +- Post-cluster naming reveals patterns the team did not anticipate (the highest-value patterns). +- The naming itself is part of the synthesis work; rushing the naming compresses the analytical work into a label without thought. + +**The discipline.** First-pass clustering produces unnamed clusters. The researcher then names each cluster based on what the underlying observations actually show. Names emerge after the clustering, not before. + +--- + +## Principle 5: Tag dissent and contradictions explicitly + +**The pattern.** Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. + +**The anti-pattern.** Tagging only the dominant pattern; ignoring the contradictions; or tagging contradictions but not following them through to clustering and synthesis. + +**Why dissent matters.** + +- Contradictions reveal sub-segments. "Most users find configuration confusing; experienced users find it efficient" might mean the pattern is segment-specific, not universal. +- Contradictions reveal pattern strength. A pattern with no countervailing evidence is suspicious; a pattern with some dissent that the synthesis can explain is stronger. +- Synthesis that ignores dissent reads as researcher confirmation bias. + +**The discipline.** Each major pattern in synthesis has a "but consider" section: contradictions in the data, segment differences, edge cases. The synthesis is more honest with these sections; readers trust patterns that engage their counterevidence. + +--- + +## Tagging tactics that work + +A short list of tactics that improve tagging quality. + +**Read the artifact end-to-end before tagging.** Tagging while reading on first pass produces fragmentary tags. Reading first, then tagging on a second pass, produces tags grounded in the artifact's full context. + +**Tag specific moments, not summaries.** "User struggles" is a summary. "User abandons configuration step 3 because credit card details are not accessible during signup" is a specific moment. Specific moments support stronger pattern naming later. + +**Pull quotes during tagging.** Synthesis output includes evidence; the evidence comes from quotes selected during tagging. Marking quote-worthy moments during tagging prevents re-reading later. + +**Tag motivation alongside behavior.** "User clicked X" is behavior; "User clicked X because they thought it would Y" is motivation. Motivation tags surface what users were trying to accomplish, which informs implications more than behavior alone. + +**Tag emotional valence sparingly.** "User was frustrated" is fine; tagging every artifact for emotional state produces noise. + +--- + +## Clustering tactics that work + +**Iterate clustering at least twice.** First-pass clustering is rough; second-pass clustering refines; third-pass clustering catches what the first two missed. + +**Use artifact-source counts.** A cluster supported by 8 artifacts is stronger than one supported by 2. The source count does not determine pattern importance, but it informs synthesis weighting. + +**Test cluster boundaries.** Take a tag from one cluster and ask: could this fit in another cluster instead? If yes, the cluster boundaries are unclear; refine. + +**Surface the leftovers.** Tags that do not fit any cluster are signal. They might be noise (one-off observations not generalizing). They might be edge-case patterns worth naming separately. They might point to a cluster the researcher missed. + +**Cluster collaboratively where possible.** A second reviewer surfaces alternative groupings the first reviewer did not see. Two reviewers usually produces better clustering than one. + +--- + +## Common tagging-and-clustering failures + +**Tagging by memory, not by reading.** Researchers reading transcripts and then tagging from recall. Loses specifics; produces general tags that cluster poorly. + +**Tag exhaustion.** Researchers running through too many artifacts in one session, tag quality decaying as fatigue sets in. Reduce session length; pace the tagging across days. + +**Confirming the team's prior hypothesis.** Researchers entering tagging with a hypothesis the research is meant to confirm. Tags get assigned to support the hypothesis; counterevidence gets minimized. + +**Cluster collapsing to fit a target count.** Researchers feeling they should have N clusters and forcing the data to that count. Either over-collapsing (losing distinctions) or under-collapsing (preserving noise as signal). + +**Skipping the dissent.** Tagging only the dominant pattern; clustering only the supporting tags. Synthesis publishes patterns without their counterevidence; reviewers later catch the gap. + +--- + +## Methodology-level choices that stay in the public skill + +The five principles (tag at artifact level, allow proliferation, cluster on patterns, name after clustering, tag dissent). The tagging tactics. The clustering tactics. The common failures. + +## Implementation choices that stay internal + +Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific session-length conventions for tagging. Specific reviewer pairings. The team's own conventions for tag-count thresholds. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md new file mode 100644 index 0000000..5ba1b81 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md @@ -0,0 +1,212 @@ +# When to gather more data + +Synthesis sometimes reveals that the research did not collect enough. The discipline is naming gaps explicitly and deciding whether to halt synthesis, ship with named gaps, or restart with more research. + +The discomfort of acknowledging gaps is the source of bad synthesis. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals it was not. The discipline is honesty about what the research can and cannot support. + +--- + +## Pattern thinness + +**The signal.** A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. + +**Why it happens.** + +- The discovery cycle had a defined batch size; some patterns emerged with limited support. +- The pattern is real but rare; the research did not encounter enough cases to characterize it. +- The pattern is segment-specific; the research overrepresented other segments. + +**The honest options.** + +- Name the pattern as tentative pending more data. Synthesis ships with this pattern flagged as preliminary; the team treats it as a hypothesis rather than a finding. +- Pause synthesis to gather more research. If the pattern is decision-load-bearing, the additional research investment may be worthwhile. +- Drop the pattern. If the pattern is not decision-relevant or the data is too thin to be useful, do not include it. Inflating thin patterns to fill space is a synthesis failure. + +**The dishonest option to avoid.** Naming the thin pattern as if it had full support. Readers cannot distinguish well-supported from thinly-supported patterns; decisions get made as if all patterns are equal weight; the team gets surprised when the thin-pattern decisions do not pan out. + +--- + +## Segment under-representation + +**The signal.** The research overrepresents one user segment and underrepresents another that matters for the decision. + +**Why it happens.** + +- Recruiting bias produces segment skew (the easiest-to-recruit users are usually a specific segment). +- The research was scoped before the team realized which segments mattered most for the decision. +- Available research artifacts (existing tickets, prior interviews) skew toward certain segments. + +**The honest options.** + +- Synthesize for the represented segment; flag explicitly that the patterns may not apply to underrepresented segments. +- Pause to recruit and conduct research with the underrepresented segment. +- Use existing data sources (analytics, support data) to validate patterns in the underrepresented segment indirectly. + +**Worked example.** A discovery cycle on B2B onboarding interviews 12 users, all from companies of 50-500 employees. The synthesis surfaces strong patterns for that segment. The product team is also considering enterprise (1000+ employees) and small business (1-50). The synthesis should: + +- Name patterns for the 50-500 segment with confidence. +- Acknowledge that enterprise and small business patterns are not represented. +- Recommend either separate research for the missing segments or scoping the decision to the segment the data covered. + +--- + +## Contradictory clusters + +**The signal.** Two clusters point in opposite directions and the data does not resolve the contradiction. + +**Why it happens.** + +- Sub-segment differences the research did not investigate explicitly. +- Different use contexts producing different needs (mobile vs desktop, new vs returning users). +- One cluster reflects what users say; the other reflects what users do; the contradiction is real and revealing. + +**The honest options.** + +- Investigate the contradiction. Often the contradiction itself becomes the most valuable finding: it surfaces a sub-segment or context distinction the team did not anticipate. +- Pause synthesis to gather targeted research that resolves the contradiction. +- Ship synthesis with the contradiction named and the recommendation to gather more data before committing decisions in this area. + +**Worked example.** Interviews with new users surface that they want simpler onboarding. Support tickets from new users in the same week surface frequent requests for more configuration options during onboarding. The contradiction may reveal: + +- New users say "simpler" but mean "fewer required steps before value"; configuration options are fine if not blocking. +- The interview sample skewed casual users; the support tickets came from power users. +- The contradiction needs more investigation before driving onboarding redesign. + +--- + +## Decision time pressure + +**The signal.** Synthesis revealing data gaps but the decision has to ship before more research can happen. + +**Why it happens.** + +- Roadmap commitments do not flex for data gaps. +- The decision is upstream of work that has already been committed. +- The cost of waiting exceeds the value of additional data. + +**The honest path.** + +- Name the data gap explicitly in the synthesis. Do not pretend the gap does not exist. +- Make the recommendation with the gap acknowledged. "Given current data, we recommend X. The gap that may revise this recommendation is Y." +- Plan the follow-up research that would validate or revise the recommendation. +- Build instrumentation that will validate the recommendation post-launch (so the team can detect if the recommendation was wrong). + +**The path to avoid.** Pretending the data is sufficient when it is not. Synthesis under time pressure that treats partial data as complete data produces decisions the team will not be able to recover from cleanly when the gap surfaces later. + +--- + +## The "we have enough" trap + +**The pattern.** Teams that have invested in research want to declare the data sufficient even when the synthesis reveals gaps. + +**Why it happens.** + +- Sunk-cost reasoning: the team has spent the research budget; restarting feels like waste. +- Timeline pressure: the research was scheduled before synthesis; more research means schedule slip. +- Status concerns: declaring the research insufficient feels like admitting the discovery work was inadequate. + +**Why it produces bad synthesis.** + +- The data gaps still exist whether or not the team acknowledges them. Decisions made on incomplete data still suffer from the incompleteness. +- Synthesis that papers over gaps trains the team to treat synthesis as performative rather than load-bearing. +- The next discovery cycle will repeat the same scoping mistakes because the team did not name them honestly. + +**The discipline.** + +- Naming gaps is the synthesis owner's job. The team relies on the synthesis owner to be honest about what the research can and cannot support. +- The cost of naming gaps is short-term discomfort; the cost of pretending they do not exist is bad decisions. +- "We have enough" should be the conclusion of synthesis review, not the assumption. + +--- + +## When more research is the right call + +**The criteria.** + +- The decision is load-bearing for product direction. +- The gap is large enough that synthesis would be misleading without addressing it. +- The cost of additional research is bounded and feasible. +- The cost of deciding now and being wrong is high. + +**Examples that warrant more research.** + +- A pricing decision where current research underrepresents the segment that drives revenue. +- An onboarding redesign where the synthesis cannot distinguish what new users want from what they need. +- A positioning shift where existing-customer voice is in the data but prospect voice is missing. + +**Examples that do not warrant more research.** + +- Minor decisions where the gap's resolution would not change the recommendation materially. +- Decisions where the cost of waiting exceeds the value of additional data. +- Decisions that can be reversed easily based on post-launch data. + +--- + +## When to ship synthesis with named gaps + +**The criteria.** + +- Decision time pressure makes more research infeasible. +- The gap is named honestly so the team can weigh the recommendation accordingly. +- Post-launch instrumentation will detect if the recommendation was wrong. + +**The discipline.** + +- The named gap is in the synthesis prominently, not buried. +- The recommendation acknowledges what the gap might change. +- The follow-up research plan is specific and committed. + +**Worked example.** "Recommendation: prioritize the onboarding redesign in Q2. Caveat: our research underrepresents enterprise users; if enterprise represents a significant share of new signups, the redesign should include enterprise-specific paths we have not validated. Follow-up: enterprise-specific user research in Q1 to validate the redesign approach for that segment before Q2 ships." + +--- + +## When to drop the pattern entirely + +**The criteria.** + +- The supporting data is too thin to commit a position even tentatively. +- The pattern, if false, would mislead the team in directions hard to recover from. +- The pattern is not load-bearing for the synthesis's primary recommendations. + +**The discipline.** + +- Some thin patterns warrant dropping rather than flagging. Not every observation needs to make it into the synthesis. +- Dropping is honest synthesis; inflating is not. + +--- + +## Common gather-more-data failures + +**Inflating thin patterns.** Patterns supported by 2 artifacts presented as if supported by 12. Readers cannot distinguish strength. + +**Hiding segment gaps.** Synthesis presents recommendations as universal when they apply only to the segment researched. + +**Pretending contradictions resolved.** Synthesis writes around the contradiction rather than naming it; readers later discover it on their own. + +**Decision-pressure denial.** Synthesis treats time pressure as if it makes data complete. The decision is made; the wrong-decision cost is paid later. + +**The "we have enough" trap.** Sunk cost and status protect the synthesis from honest gap-naming. + +**Endless research.** The opposite failure: every gap triggers more research; synthesis never ships; the team paralyzes on data-gathering. + +--- + +## The data-sufficiency calibration + +A short framework. + +1. **Is the gap load-bearing for the recommendations?** If yes, address it. If no, name and proceed. +2. **Is more research feasible within the decision timeline?** If yes, gather. If no, ship with named gaps. +3. **Can post-launch instrumentation catch wrong decisions?** If yes, ship-with-instrumentation is reasonable. If no, more caution warranted. +4. **What is the cost of being wrong vs cost of waiting?** Compare; choose the lower-cost path. +5. **Is the team's commitment to follow-up research credible?** If named gaps will trigger real follow-up, ship-with-gaps works. If named gaps will be ignored, gather now. + +--- + +## Methodology-level choices that stay in the public skill + +The pattern thinness signal. Segment under-representation. Contradictory clusters. Decision time pressure. The we-have-enough trap. When more research is and is not the right call. When to ship with named gaps. When to drop patterns. Common gather-more-data failures. The data-sufficiency calibration. + +## Implementation choices that stay internal + +Specific recruiting pipelines for follow-up research. Specific instrumentation for post-launch validation. Specific synthesis-revision workflows when gaps are named. The team's own conventions for "thin pattern" thresholds. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md new file mode 100644 index 0000000..6291907 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md @@ -0,0 +1,207 @@ +# Writing for decisions, not decks + +Synthesis output should be optimized for decision use, not for presentation. The format choice (document vs deck), the structure (patterns lead, evidence appendix), the voice (opinionated), and the closing (decision input section) compose to produce synthesis the team actually references. + +--- + +## Document, not deck + +**The principle.** Deck format is poor for synthesis. + +**Why decks fail.** + +- Slides cannot carry argument density. A pattern, its evidence summary, its implications, and its decision input do not fit on one slide; spreading them across slides loses coherence. +- Readers cannot reference slides later. A pattern needs to be findable; decks decay into icons and bullet points that are hard to search and cite. +- Decks are presentation artifacts; synthesis needs to be a reference artifact that the team uses for months. +- The deck format encourages summarization that loses precision. + +**Why documents work.** + +- A 4-12 page document can carry the pattern, evidence, implications, and decision input in connected prose. +- Documents are searchable, linkable, and citable. +- Documents accommodate density without overwhelming; readers can scan headings and dive into sections. +- Documents read as load-bearing analytical work; decks read as presentation. + +**The exception.** A short executive summary deck (5-8 slides) can pair with a substantive document. The deck summarizes; the document carries the work. + +**The discipline.** If the synthesis is being optimized for a single 30-minute readout meeting, the format will fail when the team needs to reference the synthesis in week 6 of execution. Optimize for the reference use, not the presentation moment. + +--- + +## Lead with patterns and implications; relegate evidence to appendix + +**The principle.** Readers scanning for decision input want patterns and implications first. + +**The reader's question.** "What does this synthesis tell me to do?" Patterns and implications answer it. Evidence supports the answer but is not the answer. + +**The structure that works.** + +- Executive summary (1 page): the patterns, the recommendations, the decision input. +- Pattern sections (1-3 pages per pattern): pattern name, evidence summary in 2-3 sentences, implications, decision input. +- Recommendations section (1 page): overall synthesis recommendation; what should change. +- Appendix: detailed evidence, quote pulls, methodology notes, full transcripts or links to them. + +**The structure that fails.** + +- Decks that lead with quote walls. Readers admire the quotes; they do not extract decisions. +- Documents that bury the patterns under methodology and background. Readers stop reading before reaching the patterns. +- Synthesis that mixes evidence and analysis throughout. Readers cannot tell where observation ends and recommendation begins. + +**The discipline.** Each pattern section is short (2-4 paragraphs of synthesis text); evidence linked or summarized briefly; the appendix is where evidence depth lives. Readers who want depth follow the link; readers who want decisions stay in the body. + +--- + +## One section per pattern, parallel structure + +**The principle.** Synthesis with 4-8 patterns has 4-8 parallel sections, each with the same structure. + +**Per-section structure.** + +- Pattern name (the heading). +- Evidence summary (2-3 sentences naming the artifacts and the dominant signals). +- Implication (1-3 implications with cost notes). +- Decision input (specific decision the implication informs). + +**Why parallel structure works.** + +- Readers learn the structure from the first section and can scan subsequent ones. +- Comparison across patterns is easier when each is presented the same way. +- Editing for completeness is easier (each section either has the elements or it does not). + +**The variation.** Some patterns warrant longer treatment (richer evidence, more complex implications); some are shorter. Length variation is fine; structural variation is not. + +--- + +## Be opinionated + +**The principle.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. + +**Hedged synthesis.** + +- "Users may sometimes occasionally seem to indicate possible difficulty." +- "It might be considered to potentially explore some adjustments." +- "There could be benefits to investigating opportunities." + +These commit nothing. Readers cannot debate or decide on hedged synthesis. + +**Opinionated synthesis.** + +- "Users abandon configuration step 3 in 40% of signup attempts because credit card details are not accessible at signup." +- "The Q2 roadmap should prioritize the onboarding redesign over the dashboard expansion." +- "The not-act recommendation is to defer enterprise admin controls until small-team segment growth stabilizes." + +These commit positions. Readers can disagree; disagreement produces decisions. + +**The discipline.** Write synthesis as a recommendation. The PM doing synthesis is making analytical claims; readers may push back, but pushback is the point. Hedging avoids pushback by avoiding claim. + +**The exception for honest uncertainty.** When the data genuinely does not support a position, name the uncertainty explicitly: "The evidence supports two possible interpretations; we recommend gathering more data before deciding." This is honest uncertainty, not hedging. Hedging is dressing up uncertainty as if it were synthesis. + +--- + +## Include a decision-input section + +**The principle.** What does this synthesis recommend the team do? + +**The section's role.** The decision-input section connects the synthesis to the team's prioritization work. Without it, the synthesis presents patterns and implications but does not aggregate them into recommendations. + +**What the section addresses.** + +- Where should priorities shift based on this synthesis? +- Which roadmap items does the synthesis validate? Which does it challenge? +- Which decisions can the team make now with this synthesis as input? +- Which decisions need more research before making? +- What is the synthesis's overall view of where the product should focus? + +**The section's voice.** Direct, specific, opinionated. The team can disagree, but the section should commit a recommendation. + +**The discipline.** Without this section, synthesis is a collection of patterns; with this section, synthesis is decision input. The section is what makes the synthesis load-bearing for the team's strategic work. + +--- + +## Length calibration + +**The principle.** Synthesis should be as short as possible without losing the load-bearing content. + +**Typical lengths.** + +- Discovery cycle synthesis from a meaningful research batch: 6-12 pages. +- Smaller-scale synthesis from a single research type (e.g., support audit alone): 3-6 pages. +- Quick-turn synthesis from a focused interview batch: 2-4 pages. + +**Length anti-patterns.** + +- Synthesis padded to 30+ pages. Readers stop reading; the load-bearing content gets lost. +- Synthesis compressed to 1 page. Density too high; specifics get lost. +- Synthesis stretched across multiple documents without clear primacy. Readers do not know which document is the synthesis. + +**The discipline.** Edit for length. Each pattern section should be tight; each implication should be specific; the recommendation should be concise. Readers will engage with a 6-page synthesis they can finish in 20 minutes; readers will skim a 30-page synthesis and miss the recommendations. + +--- + +## The reference-after-shipping test + +**The principle.** Synthesis that gets referenced months after publication has earned its keep. + +**The test.** Six months after a synthesis ships, can the team: + +- Name the patterns the synthesis surfaced? +- Cite the synthesis in roadmap discussions? +- Use the synthesis as input for related decisions that came up after publication? + +**Failures the test reveals.** + +- Synthesis nobody can name suggests insight-theater (presented but not absorbed). +- Synthesis nobody references suggests document-shelf-syndrome (filed away after readout). +- Synthesis the team contradicts in later decisions suggests the synthesis was not load-bearing in their actual prioritization work. + +**Recovery.** When prior synthesis fails the test, the next synthesis should adjust: shorter, more opinionated, more directly tied to specific decisions. Each round of synthesis should be more usable than the prior. + +--- + +## Visual elements in synthesis documents + +**The discipline.** Visuals should carry argumentative load the prose alone cannot. + +**Visuals that work.** + +- A pattern-to-implication-to-decision diagram showing how the synthesis connects to product work. +- A frequency chart for patterns supported by quantitative data. +- A segment comparison table where patterns differ across segments. +- An evidence map showing artifact-source distribution per pattern. + +**Visuals that fail.** + +- Stock images decorating section breaks. +- Quote walls without context. +- Word clouds (rarely informative). +- Persona illustrations (decorative; not synthesis output). + +**The frequency.** Visual elements every 2-3 pages of synthesis is typical. More than that risks decoration; fewer is fine if the prose carries the work. + +--- + +## Common synthesis-writing failures + +**Format choice.** Deck instead of document; the synthesis decays into bullets that lose precision. + +**Buried recommendations.** Patterns are clear; the recommendation is one sentence on page 11. Readers miss it. + +**Hedge-stacking.** Every claim caveated; readers cannot extract a position. + +**No decision-input section.** Synthesis presents patterns; team has to aggregate them into decisions on their own; usually does not. + +**Length excess.** 30 pages of synthesis where 8 would have served. Readers skim; load-bearing content gets lost. + +**Length compression.** 1 page of synthesis where 6 were needed. Density too high; specifics lost. + +**Quote-wall presentation.** Evidence dominates; analysis recedes; readers admire the quotes and miss the synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The document-not-deck principle. The patterns-lead-evidence-appendix structure. The parallel-section discipline. The opinionated voice. The decision-input section. Length calibration. The reference-after-shipping test. Visual element discipline. Common failures. + +## Implementation choices that stay internal + +Specific document templates and styles. Specific document hosting (Notion, Coda, Google Docs, Confluence). Specific link conventions for evidence. Specific reviewer workflows. Specific archive practices. The team's own conventions for synthesis length within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/documentation-strategy/SKILL.md b/dist/pi/.agents/skills/documentation-strategy/SKILL.md new file mode 100644 index 0000000..1b65361 --- /dev/null +++ b/dist/pi/.agents/skills/documentation-strategy/SKILL.md @@ -0,0 +1,428 @@ +--- +name: documentation-strategy +description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long." +category: process-and-team +catalog_summary: "Documentation systems, what to document, maintenance cadence" +display_order: 2 +--- + +# Documentation Strategy + +Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases. + +--- + +## When to use + +- Setting up documentation for a new team or product +- Auditing existing documentation +- Fixing stale or scattered docs +- Choosing a documentation tool or platform +- Defining what gets documented and what doesn't +- Establishing maintenance cadence +- Scoping technical writing work +- Designing onboarding documentation (use alongside `team-onboarding-playbook`) + +## When NOT to use + +- Writing the actual content of a single document (use `content-and-copy`) +- Customer-facing knowledge base copy (use `content-strategy`) +- Code comments and inline documentation (covered by `code-review-web`) +- One-off blog posts or articles (use `content-and-copy`) + +--- + +## Required inputs + +- The audience (internal, external, customer, dev, exec) +- Existing docs and their state (where, what shape, last updated) +- Team size and growth trajectory +- The kinds of work that produce documentation (engineering, product, ops, support) +- Tools currently in use + +--- + +## The framework: 4 categories of documentation + +Different categories of doc serve different purposes. Conflating them is how docs get bad. + +### Category 1: Reference + +What things are. Looked up when needed. + +Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries. + +Properties: +- Comprehensive +- Fact-checked, kept accurate +- Searchable +- Stable structure (links don't break) +- Version-aware where relevant + +### Category 2: How-to + +How to do specific tasks. Procedural. + +Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill." + +Properties: +- Step-by-step +- Tested by someone who didn't write it +- Includes the prerequisites +- Includes troubleshooting +- Versioned to the system it documents + +### Category 3: Explanation + +Why things are the way they are. Conceptual. + +Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents. + +Properties: +- Narrative +- Captures context (the why) +- Often historical (why we built it this way) +- Links to evidence + +### Category 4: Tutorial + +Learning-oriented. Walks someone from zero to capable. + +Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways. + +Properties: +- Sequenced from simple to complex +- Hands-on +- Doesn't assume prior knowledge in scope +- Has clear completion criteria + +(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.) + +--- + +## The framework: 5 tiers of doc + +Different docs serve different audiences with different stakes. + +### Tier 1: Customer-facing + +Public docs, customer KBs, API references. High visibility, slow change. + +Standards: +- Editorial review +- Version control +- Clear ownership +- High freshness bar +- Tied to release + +### Tier 2: Cross-team / shared + +Docs used across teams: shared APIs, common services, company-wide processes. + +Standards: +- Cross-team ownership clear +- Update obligations on changes +- Mid-to-high freshness bar + +### Tier 3: Team-internal + +Docs for the team that owns them: how the team works, runbooks, decisions. + +Standards: +- Team-owned, team-maintained +- Mid freshness bar +- Useful for the next person joining + +### Tier 4: Personal scratchpad + +Notes, drafts, work-in-progress. Not for others. + +Standards: +- Low maintenance +- Don't link from official docs +- Promote to higher tier when valuable + +### Tier 5: Auto-generated + +Docs derived from code: API references generated from comments, schemas, etc. + +Standards: +- Generation is automated, runs in CI +- Single source of truth (the code) +- Reviewed for usability, not freshness (that's automatic) + +The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable. + +--- + +## Workflow + +### Step 1: Audit current state + +- What docs exist? +- Where do they live? (often: scattered) +- Who owns each? +- How fresh are they? +- Are they actually used? (check page views or referrals if measurable) + +The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize. + +### Step 2: Categorize and tier + +For each doc: +- Category (reference / how-to / explanation / tutorial) +- Tier (customer / shared / team / scratchpad / generated) + +Some docs are mixed. Note the dominant category. + +### Step 3: Identify gaps + +What documentation does the team need that doesn't exist? + +Common gaps: +- "How does X actually work?" no answer +- Onboarding for the role no one's onboarded recently +- Runbook for a system that's never broken (yet) +- Decision rationale for "why are we doing it this way" + +Ask people what they wish were documented. They know. + +### Step 4: Identify dead weight + +Docs that are: +- Out of date and not getting updated +- Duplicated across places (one is canonical, others should redirect or be deleted) +- About things that no longer exist +- Drafts abandoned long ago + +Delete or archive. Stale docs are worse than missing docs (people might trust them). + +### Step 5: Pick the home(s) + +Where docs live affects whether they're maintained. + +Common locations: +- **Code repo (markdown):** for docs tightly coupled to code (READMEs, ADRs, runbooks for the service) +- **Wiki / Notion / Confluence:** for cross-team and team-internal +- **Docs site (Docusaurus, Mintlify, custom):** for customer-facing +- **Tickets / decision logs:** for ephemeral records + +Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?" + +### Step 6: Establish ownership + +Every doc has an owner. Without an owner, it goes stale. + +Owner can be: +- A team +- A role (the on-call rotation, the PM, the EM) +- A person, with a backup + +If an owner isn't obvious, the doc may not deserve to exist. + +### Step 7: Establish maintenance cadence + +Per tier: + +| Tier | Review cadence | +|---|---| +| Customer-facing | Per release, plus quarterly | +| Cross-team | Quarterly | +| Team-internal | Quarterly | +| Personal scratchpad | None | +| Auto-generated | On every change | + +Maintenance includes: +- Verify accuracy +- Update for changed systems +- Archive what's no longer relevant +- Address user feedback + +### Step 8: Make doc updates part of work + +Documentation isn't a separate project. It's part of the work that produces it. + +- New feature: docs are part of the feature +- New process: doc is part of the rollout +- Decision made: ADR or decision-log entry filed +- Bug postmortem: runbook updated +- New hire: onboarding doc updated based on their experience + +The team that ships features without docs has less than they think they have. + +### Step 9: Make docs discoverable + +Even great docs are useless if no one finds them. + +- Search that actually works (most platforms; some better than others) +- Index pages for major topics +- Cross-links between related docs +- Search aliases for common alternative phrasings +- Pinning the most-used docs + +### Step 10: Measure + +What's measurable depends on the platform: +- Page views +- Search queries (and zero-result queries) +- "Was this helpful?" feedback +- Time on page +- Referral patterns + +For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear). + +--- + +## Specific patterns + +### README per project + +Every code repo has a README that answers: +- What is this? +- How do I run it? +- How do I contribute? +- Where do I find more info? + +Five sentences each, often. Length isn't the goal. The READ-it-ME promise is. + +### ADR (Architecture Decision Record) + +Per significant decision: + +``` +# ADR-NNN: [Title] + +Status: [Proposed / Accepted / Deprecated / Superseded] +Date: [Date] + +## Context +[What's the situation? What forces are at play?] + +## Decision +[What was decided?] + +## Consequences +[What happens because of this decision? Both good and bad.] +``` + +ADRs accumulate. They become the explanation layer for "why are we doing it this way." + +### Runbook + +Per system: +- What it is +- How to access it +- Common operations (with commands) +- Common failure modes +- Restore from backup procedure +- Escalation contacts + +See `incident-response` and `backup-and-disaster-recovery` for runbook standards. + +### Onboarding pathway + +Per role: +- Day 1 +- Week 1 +- Month 1 +- 90 days + +See `team-onboarding-playbook`. + +### Decision log + +Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony. + +### Glossary + +Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later). + +--- + +## Tooling + +The tool is less important than the discipline. That said: + +| Tool category | Examples | Best for | +|---|---|---| +| Wiki | Notion, Confluence, GitBook | Cross-team, internal | +| Markdown in code | GitHub, GitLab, Bitbucket | READMEs, ADRs, technical | +| Docs sites | Docusaurus, Mintlify, ReadMe | Customer-facing, public docs | +| Internal sites | MkDocs, custom | Team-specific patterns | + +Considerations: +- Search quality (a poor search makes everything worse) +- Editor quality (people won't write in painful editors) +- Version control (can you see history?) +- Permissions (right people can read and write) +- API and integration (for automation) +- Cost at your scale + +For small teams: a single wiki tool is plenty. For larger: tiered tools. + +--- + +## AI-related notes + +LLMs and AI assistants increasingly read documentation. Some considerations: + +- Clear, consistent structure helps both humans and AI +- A glossary of terms helps both +- File-level metadata (front matter) helps tools +- Public docs may be read by AI crawlers; consider an `llms.txt` if relevant +- AI-generated drafts are a starting point, not a final answer; humans review + +--- + +## Failure patterns + +**Documentation as a "later" task.** Always written later. Later means never. Make docs part of the work. + +**One mega-doc for everything.** Wiki page that's 8,000 words. No one reads it. Break by category and topic. + +**Stale docs that nobody trusts.** "Probably out of date" is the thought that kills documentation. Either keep current or archive. + +**Docs everyone agrees should exist but no one writes.** The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific. + +**Wikis that are graveyards.** Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set. + +**Docs separated from code.** API docs in a wiki, code in a repo. They drift. Co-locate. + +**Docs without examples.** Reference without examples is hard to use. Examples make it concrete. + +**Examples that don't run.** Code examples that worked once, drifted. Test examples in CI where possible. + +**Long-form when reference would do.** A 2,000-word doc explaining what a 30-row table would. Use the right form. + +**Multiple sources of truth.** Same info in three places, all slightly different. Pick canonical, redirect others. + +**Doc tools no one uses.** Adopted because of a feature; team doesn't actually use it. Pick tools the team will use. + +**Doc style guide that's longer than the docs.** Process beats product. Guide should be short. + +**No way to mark docs as deprecated.** Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status. + +**No analytics.** No idea what's being used or what's missing. Even basic page views inform priorities. + +**Docs that read like specifications.** Dense, formal, hard to scan. Write for the reader. + +--- + +## Output format + +A documentation strategy document includes: + +- **Audit:** what exists, where, in what state +- **Tiering and categorization:** the framework applied to existing docs +- **Gap list:** what should exist but doesn't +- **Tool decisions:** where each kind of doc lives +- **Ownership map:** who owns what +- **Maintenance cadence:** what's reviewed when +- **Style guide (brief):** consistency standards +- **Roadmap:** prioritized work to fill gaps and close out dead weight + +--- + +## Reference files + +- [`references/doc-types-guide.md`](references/doc-types-guide.md): Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each. diff --git a/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md b/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md new file mode 100644 index 0000000..badadbf --- /dev/null +++ b/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md @@ -0,0 +1,451 @@ +# Doc Types Guide + +The four categories of documentation, what each is for, and a template for each. Based on the Diátaxis framework (well-known in technical writing). + +The categories aren't interchangeable. Mixing them is the most common failure in documentation: a "tutorial" that's actually reference, a "how-to" that's secretly explanation, a "reference" that meanders into tutorial territory. + +--- + +## The four types + +| Type | Purpose | Reader needs | Style | +|---|---|---|---| +| Reference | Look up facts | "What is the value of X?" | Comprehensive, terse | +| How-to | Solve a specific problem | "How do I do Y?" | Step-by-step, focused | +| Explanation | Understand the why | "Why does Z work this way?" | Discursive, narrative | +| Tutorial | Learn from zero | "How do I get started?" | Hands-on, sequenced | + +A useful diagram of how they relate: + +``` + Practical (action) + | + HOW-TO ───────────|─────────── REFERENCE + | + | + Theoretical (understanding) + | + TUTORIAL ───────────|─────────── EXPLANATION + | + Study (acquiring skill) Work (applying skill) +``` + +- Tutorial and how-to are practical (the reader is doing something) +- Reference and explanation are theoretical (the reader is understanding something) +- Tutorial and explanation are study-oriented (acquiring skill or understanding) +- How-to and reference are work-oriented (applying skill) + +--- + +## Reference + +### What it is + +The complete catalog of facts about something. Looked up when needed. + +### Examples + +- API reference (every endpoint, every parameter, every response) +- Configuration options (every flag, every default, every effect) +- Glossary (every term, definition) +- Error code catalog +- Component library docs + +### What makes it good + +- Comprehensive (covers everything) +- Accurate (verified against the actual system) +- Consistently structured (each entry follows the same pattern) +- Searchable (people find what they need quickly) +- Stable links (entries don't move or disappear without redirects) + +### What makes it bad + +- Editorializing ("This is the best way...") +- Tutorials interleaved (reader looking up a fact gets a wall of explanation) +- Inconsistent depth (some entries thorough, others sparse) +- Out of date (single most common reference failure) + +### Template + +``` +# [Function / Endpoint / Setting / Term] + +**Type:** [function / endpoint / configuration / etc.] +**Since:** [version introduced] +**Status:** [stable / beta / deprecated] + +## Description + +[1-2 sentences. What this is.] + +## [Parameters / Inputs / Properties] + +| Name | Type | Default | Description | +|---|---|---|---| +| [name] | [type] | [default] | [description] | + +## [Returns / Output] + +[Description of return value or output.] + +## Examples + +[Minimum useful example.] + +## Notes + +- [Edge case] +- [Gotcha] +- [Related: link to related reference] +``` + +--- + +## How-to + +### What it is + +A guide to accomplishing a specific task. The reader has a problem; the how-to gives the solution. + +### Examples + +- "How to deploy to production" +- "How to reset a forgotten password" +- "How to add a new locale" +- "How to migrate data from system A to system B" + +### What makes it good + +- Goal-oriented (solves a specific problem) +- Sequential (steps in order) +- Tested (someone other than the author followed it) +- Includes prerequisites +- Includes troubleshooting for known issues +- Realistic (uses real values, not placeholders that confuse) + +### What makes it bad + +- Mixed with explanation (the reader wants to act, not understand the design) +- Too generic (steps don't apply cleanly to the actual situation) +- Out of date (commands no longer work) +- Missing prerequisites (reader gets stuck on step 2 because of an unstated dependency) +- Too many branches ("If X then..., else if Y then..."; usually means it should be split into multiple how-tos) + +### Template + +``` +# How to [Specific Task] + +## Goal + +[1 sentence: what the reader will accomplish.] + +## Before you start + +- [Prerequisite 1] +- [Prerequisite 2] +- [Prerequisite 3] + +## Steps + +### 1. [First step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 2. [Second step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 3. [Third step] + +[...] + +## Verify + +[How to confirm the task succeeded.] + +## Troubleshooting + +**Problem: [Common issue]** + +[Cause and resolution.] + +**Problem: [Common issue]** + +[Cause and resolution.] + +## See also + +- [Related how-to] +- [Related reference] +``` + +--- + +## Explanation + +### What it is + +The why. Discursive. Helps the reader understand the design, the rationale, the tradeoffs. + +### Examples + +- Architecture documents +- Design rationale +- Decision records (ADRs) +- "Why we don't support feature X" +- Strategy documents +- Conceptual overviews + +### What makes it good + +- Captures the why (not just the what) +- Honest about tradeoffs (every design choice has a cost) +- Includes alternatives considered +- Time-stamped (so readers know when this was true) +- Connects to other concepts + +### What makes it bad + +- Lecture-y (reader feels talked down to) +- Ahistorical (no context of why decisions were made) +- Marketing voice (everything is "great" and "exciting") +- Buried in how-to (reader is trying to do something; explanation slows them down) + +### Template (ADR specifically) + +``` +# ADR-NNN: [Title of decision] + +**Status:** [Proposed / Accepted / Deprecated / Superseded by ADR-MMM] +**Date:** [YYYY-MM-DD] +**Deciders:** [Who was involved] + +## Context + +[What's the situation? What's the problem? What forces are at play?] + +[Include enough context that a reader new to this can understand. Don't assume the present-day context will be obvious in the future.] + +## Decision + +[What was decided. State it clearly.] + +## Alternatives considered + +### Alternative A: [Name] + +[Description, why not chosen.] + +### Alternative B: [Name] + +[Description, why not chosen.] + +## Consequences + +### Positive + +- [What's better as a result] +- [What's better as a result] + +### Negative + +- [What's worse or constrained as a result] +- [What's worse or constrained as a result] + +### Neutral / mixed + +- [Tradeoffs that aren't clearly good or bad] + +## Notes + +[Anything else relevant. Links to discussion threads, prototypes, related decisions.] +``` + +### Template (general explanation doc) + +``` +# [Topic] + +## What this is + +[2-3 sentences orienting the reader.] + +## Background + +[The context. What was true before. Why this came up.] + +## How it works + +[The substance. Walk through the design, the model, the structure. Use diagrams.] + +## Why this approach + +[The rationale. What we considered. What we chose and why.] + +## Tradeoffs + +[Honest accounting of what's good and bad about this approach.] + +## See also + +[Related explanation, related decisions, related reference.] +``` + +--- + +## Tutorial + +### What it is + +Learning by doing. The reader starts with no knowledge of the topic and finishes capable of using it. + +### Examples + +- "Getting started with our SDK" +- "Your first deployment" +- Onboarding pathways for new team members +- "Building your first integration" + +### What makes it good + +- Sequenced from simple to complex +- Hands-on (the reader does things, not just reads) +- Concrete (real values, real commands, real outcomes) +- Has clear completion criteria +- Builds on a single thread (one project, one example) +- Acknowledges where the reader is (beginner) + +### What makes it bad + +- Reference dressed up as tutorial (no thread, no completion) +- Skips steps "for brevity" (reader gets stuck) +- Uses placeholders like `<your-value-here>` without making them concrete +- Assumes prior knowledge that wasn't stated as prerequisite +- Branches early ("if you want X, do this; if Y, do this") instead of staying focused + +### Template + +``` +# Getting started with [Thing] + +## What you'll build + +[1-2 sentences describing the end state. Maybe a screenshot or example output.] + +## Time required + +[Realistic estimate, e.g. "30-45 minutes"] + +## Before you start + +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] + +## Step 1: [First milestone] + +[Plain-English description of what we're doing in this step.] + +[Concrete instructions:] + +``` +[Specific command] +``` + +[What you should see:] + +``` +[Expected output] +``` + +If something different happens, see [Troubleshooting section]. + +## Step 2: [Second milestone] + +[Same pattern.] + +## Step 3: [Third milestone] + +[Same pattern.] + +[...] + +## What you've built + +[Recap. The reader should feel: I get it now.] + +## Where to go next + +- [Next tutorial] +- [Reference for what you just used] +- [How-to for related task] + +## Troubleshooting + +**[Specific problem someone might hit]** + +[Cause and resolution.] +``` + +--- + +## How to use this in practice + +### When writing new docs + +Identify which type before starting. Don't mix. + +If a doc has tutorial sections AND reference sections AND explanation sections, it's three docs. Split. + +### When auditing existing docs + +For each existing doc, ask: which type is this trying to be? + +If it's mixed, split. The split is usually: keep the dominant type in the original, link to the other types. + +### When linking between types + +The four types reinforce each other: +- Tutorials link to reference for the things they introduce +- How-tos link to reference for the commands they use +- Reference links to explanation for the why +- Explanation links to how-to for "to do this, see..." + +A connected web of all four serves the reader well. + +### When choosing the type for a need + +| Reader is asking | Type | +|---|---| +| "What does X mean?" | Reference | +| "What's the syntax for X?" | Reference | +| "How do I do Y?" | How-to | +| "How do I solve [specific problem]?" | How-to | +| "Why does Z work this way?" | Explanation | +| "What did we decide about W?" | Explanation (ADR) | +| "I'm new; where do I start?" | Tutorial | + +If the answer is "all of the above," the reader actually needs multiple docs, not one mega-doc. + +--- + +## Anti-patterns to recognize + +- **The "everything" doc:** tries to be all four types. Reads like all four poorly. +- **The "guide" doc:** vague title, vague purpose. Often a how-to that lost focus. +- **The "manual" doc:** monolithic. Unmaintainable. Split. +- **The "wiki page that became sacred:** historical accumulation. Past usefulness. Audit and split or archive. diff --git a/dist/pi/.agents/skills/domain-strategy/SKILL.md b/dist/pi/.agents/skills/domain-strategy/SKILL.md new file mode 100644 index 0000000..568e44d --- /dev/null +++ b/dist/pi/.agents/skills/domain-strategy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: domain-strategy +description: "Plan, manage, and optimize a domain portfolio. Use this skill for DNS architecture decisions, redirect strategies, registrar choice, parking unused domains, multi-site setups, and domain consolidation or split planning. Triggers on DNS, domain, registrar, redirect, parking, subdomain, apex, www vs non-www, multi-site, portfolio, hreflang setup, domain migration. Also triggers when planning a new site that needs domain decisions made before launch." +category: operations +catalog_summary: "DNS architecture, redirects, registrars, multi-domain portfolios" +display_order: 4 +--- + +# Domain Strategy + +Decide how domains, subdomains, and DNS work across a portfolio. Stack-agnostic. Works for one site or one hundred. + +--- + +## When to use + +- Setting up DNS for a new site (apex vs www, primary vs aliases) +- Choosing or switching registrars +- Planning redirects across multiple domains (parked, retired, consolidated) +- Deciding subdomain vs subfolder vs separate domain for a new product line +- Consolidating multiple sites into one +- Splitting one site into multiple +- Setting up DNS for email, security records, third-party services + +## When NOT to use + +- Migrating content between platforms with URL changes (use `content-migration`) +- Email authentication setup specifically (use `email-deliverability`) +- Security headers or HTTPS config (use `security-baseline`) +- Internationalization domain choices (use `internationalization`) + +--- + +## Required inputs + +- Current domain inventory (every domain you own or operate) +- Status of each (live, parked, redirected, retired) +- Strategic role of each (primary brand, sub-brand, defensive registration, campaign) +- Current DNS provider and registrar for each +- Email and third-party service dependencies + +--- + +## The framework: 5 decisions + +Every domain decision falls into one of these buckets. Address them in order. + +### Decision 1: Apex vs www as canonical + +Pick one. Redirect the other to it. Pick before launch. Changing later is painful. + +- **Apex (example.com):** cleaner, more memorable, the modern default. +- **www (www.example.com):** historically standard, easier to add CDN-level CNAME records (apex CNAME is technically forbidden but most providers offer ALIAS or ANAME). + +Whichever you pick, the other must 301 to it. Both serving content is duplicate content and a soft signal of poor setup. + +### Decision 2: Subdomain vs subfolder vs separate domain + +For a new product, blog, or content section: + +| Pattern | Use when | +|---|---| +| Subfolder (`example.com/blog`) | Same brand, want SEO equity to flow, default choice | +| Subdomain (`blog.example.com`) | Different stack or platform, organizationally separate but related | +| Separate domain (`exampleblog.com`) | Different brand, different audience, intentional separation | + +Default to subfolder. The case for subdomain or separate domain has to be made. + +### Decision 3: Registrar strategy + +The registrar is where the domain is registered. The DNS provider is where DNS records live. They can be the same or different. + +Decisions: +- **Single registrar vs multiple:** single is simpler. Multiple makes sense for redundancy at scale. +- **Lock and 2FA:** non-negotiable. Domain hijacking is real and costly. +- **Auto-renew:** on for everything you care about. Off only for intentional drops. +- **WHOIS privacy:** on by default. Free at most modern registrars. +- **Transfer lock:** on except during planned transfers. + +### Decision 4: DNS provider + +The DNS provider controls how domains resolve. Critical for performance, reliability, and security. + +Pick a provider that gives you: +- Fast global resolution (anycast network) +- DNSSEC support +- API access for automation +- Reasonable record limits +- Good audit logs + +Default DNS records every domain needs: +- A or AAAA records (or CNAME) for the apex and www +- MX records (even just nullified if no email) +- TXT for domain verification, SPF +- CAA records (locks down which certificate authorities can issue certs for the domain) + +### Decision 5: Parked domain strategy + +Domains you own but aren't actively using. Three valid strategies: + +1. **Redirect to a primary site.** Best for defensively registered domains close to your main brand. 301 every path to the primary's homepage or matching path. +2. **Hold blank.** A simple page or DNS NXDOMAIN. Acceptable for domains you may use later. +3. **Park with a landing page.** Generic "coming soon" page. Lowest value. Avoid registrar default parking pages (often serve ads against your brand). + +Anti-pattern: letting parked domains serve duplicate or near-duplicate content from your main site. This is an SEO liability. + +--- + +## Workflow + +### Step 1: Inventory + +Pull every domain you own from every registrar. Build a single sheet: + +| Domain | Registrar | DNS provider | Status | Role | Renewal date | Notes | +|---|---|---|---|---|---|---| + +If you can't account for every domain, the strategy can't be accurate. + +### Step 2: Classify by role + +Each domain gets one role: +- **Primary** (the main site for a brand) +- **Alias** (redirects to a primary) +- **Defensive** (registered to prevent others from getting it; usually parked) +- **Campaign** (short-term, specific use) +- **Retired** (no longer active; either drop at expiry or redirect permanently) + +The classification drives the configuration. + +### Step 3: Audit current configuration + +For each domain check: +- Is the canonical (apex vs www) consistent with the strategy? +- Are redirects 301 (permanent) where intended? +- Is HTTPS enforced on every variant? +- Are DNS records minimal and intentional? +- Is the registrar locked? +- Is auto-renew on? +- Is 2FA on the registrar account? + +Document gaps. Each gap is a ticket. + +### Step 4: Set the canonical pattern + +For new domains and any that need fixing: + +- Pick apex or www as canonical +- Configure 301 redirect for the non-canonical +- Force HTTPS for both +- Verify with curl: `curl -I http://example.com`, `curl -I http://www.example.com`, `curl -I https://www.example.com`. All should chain to a single 200 on the canonical. + +### Step 5: Document the redirect map + +Across the portfolio, document every redirect: + +| Source | Destination | Type | Reason | Date set | +|---|---|---|---|---| + +This is invaluable when something breaks or when planning consolidations. + +### Step 6: Set up monitoring + +Monitor: +- DNS resolution (alert on NXDOMAIN or wrong IP) +- HTTPS certificate expiration (alert at 30, 14, 7 days out) +- Redirect chains (alert if a 301 starts returning 200 or 404) +- Renewal dates (alert at 90, 30, 7 days out) + +This is the bridge between domain strategy and `monitoring-and-alerting`. + +### Step 7: Document and revisit + +Domain strategy is a quarterly review topic. Renewals, consolidations, and new launches change the picture. Without scheduled review, the portfolio drifts. + +--- + +## Failure patterns + +**Both apex and www serve content.** Duplicate content. Pick one, redirect the other. + +**302 redirects where 301 was intended.** 302 is temporary. 301 is permanent. SEO equity passes through 301, not (reliably) through 302. + +**HTTPS not enforced.** HTTP variant serving content alongside HTTPS. Force HTTPS at the edge or the load balancer. + +**Registrar default parking pages.** Parked domains serving registrar ads. Free for the registrar, bad for you. Replace with a redirect or your own page. + +**Domains in multiple registrars by accident.** Migrations that didn't fully complete. Consolidate. + +**No CAA records.** Anyone with a misconfigured ACME client can issue a cert for your domain. CAA limits which CAs can issue. Add it. + +**Auto-renew off "to save money."** Domain accidentally drops, gets snapped up, costs ten times more (or is unrecoverable). Auto-renew is cheap insurance. + +**Subdomains used where subfolders would have been better.** SEO equity gets fragmented across hostnames. The case for a subdomain has to be made; the default is subfolder. + +**Parked domains with thin content "for SEO."** Search engines don't reward this. They penalize doorway pages. Either redirect or leave blank. + +--- + +## Output format + +A domain strategy document includes: + +- **Inventory:** the spreadsheet of every domain +- **Classification:** the role of each +- **Canonical decisions:** apex vs www, locked +- **Redirect map:** every redirect in the portfolio +- **DNS standards:** the default record set +- **Registrar standards:** locked, 2FA, auto-renew +- **Monitoring:** what's watched, where alerts go +- **Renewal calendar:** the next 12 months +- **Review cadence:** when this gets revisited + +--- + +## Reference files + +- [`references/dns-record-reference.md`](references/dns-record-reference.md): Common DNS records explained, with the syntax for the most useful ones (A, AAAA, CNAME, MX, TXT, CAA, SRV, etc.) and when each is needed. diff --git a/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md b/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md new file mode 100644 index 0000000..62edfff --- /dev/null +++ b/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md @@ -0,0 +1,252 @@ +# DNS Record Reference + +A quick reference to the DNS records every domain operator should understand. Stack-agnostic. The syntax is the same across DNS providers. + +--- + +## Address records + +### A record + +Maps a name to an IPv4 address. + +``` +example.com. 300 IN A 192.0.2.1 +www.example.com. 300 IN A 192.0.2.1 +``` + +Use for the apex and any subdomain that resolves to a specific IPv4. + +### AAAA record + +Maps a name to an IPv6 address. + +``` +example.com. 300 IN AAAA 2001:db8::1 +``` + +If your infrastructure supports IPv6, set AAAA records alongside A records. Many ISPs prefer IPv6. + +### CNAME record + +Maps a name to another name (which must resolve to A or AAAA). + +``` +www.example.com. 300 IN CNAME example.com. +shop.example.com. 300 IN CNAME shopify-store.myshopify.com. +``` + +CNAME cannot be used at the apex (e.g., `example.com.` cannot be a CNAME). Most providers offer ALIAS or ANAME records as a workaround for apex. + +CNAME at a name conflicts with any other record at the same name. You can't have both a CNAME and an MX at the same name, for example. + +--- + +## Mail records + +### MX record + +Specifies mail servers for the domain. Priority is the first number; lower wins. + +``` +example.com. 300 IN MX 10 mx1.mailprovider.com. +example.com. 300 IN MX 20 mx2.mailprovider.com. +``` + +Even if the domain doesn't send or receive email, set a "null MX" to prevent spoofing: + +``` +example.com. 300 IN MX 0 . +``` + +This is the "this domain doesn't accept mail" signal, defined in RFC 7505. + +### TXT record (for SPF, DKIM, DMARC) + +TXT records hold arbitrary text. The most common use is email authentication. + +**SPF (Sender Policy Framework):** declares which servers can send mail for the domain. + +``` +example.com. 300 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +``` + +Only one SPF record per domain. Multiple SPF records break SPF entirely. + +**DKIM (DomainKeys Identified Mail):** publishes the public key for signing outgoing email. + +``` +selector1._domainkey.example.com. 300 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +The selector is set by your mail provider. Different providers use different selectors. + +**DMARC (Domain-based Message Authentication):** tells receivers what to do with mail that fails SPF or DKIM. + +``` +_dmarc.example.com. 300 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +``` + +Start with `p=none` for monitoring, then move to `p=quarantine` and finally `p=reject` once aligned. See `email-deliverability` skill for the full progression. + +--- + +## Security records + +### CAA record + +Certificate Authority Authorization. Restricts which CAs can issue certificates for the domain. + +``` +example.com. 300 IN CAA 0 issue "letsencrypt.org" +example.com. 300 IN CAA 0 issuewild "letsencrypt.org" +example.com. 300 IN CAA 0 iodef "mailto:security@example.com" +``` + +Without CAA, any public CA can issue a cert for your domain. With CAA, only the listed CAs can. Add CAA for any domain you care about. + +The `iodef` directive specifies where to email reports of unauthorized issuance attempts. + +### TLSA record + +Used with DNSSEC for DANE (DNS-based Authentication of Named Entities). Pins the TLS certificate or public key in DNS. + +``` +_443._tcp.example.com. 300 IN TLSA 3 1 1 abc123def456... +``` + +Niche. Most operators won't need TLSA. Useful for high-security applications. + +### DNSKEY, DS, RRSIG (DNSSEC) + +DNSSEC signs DNS responses cryptographically, preventing spoofing. Setup is provider-specific. Most modern DNS providers offer one-click DNSSEC. Enable it if available. + +--- + +## Service discovery + +### SRV record + +Specifies the location of services (priority, weight, port, target). + +``` +_sip._tcp.example.com. 300 IN SRV 10 60 5060 sip-server.example.com. +``` + +Used for SIP, XMPP, and similar. Most websites don't need SRV records. + +### NS record + +Specifies authoritative name servers for the domain (or a delegated subdomain). + +``` +example.com. 300 IN NS ns1.dns-provider.com. +example.com. 300 IN NS ns2.dns-provider.com. +``` + +NS records are usually managed by the registrar (for the apex) or by you (for delegated subdomains). + +### SOA record + +Start of Authority. Contains administrative info about the zone. + +``` +example.com. 300 IN SOA ns1.dns-provider.com. admin.example.com. 2024010101 7200 3600 1209600 300 +``` + +Auto-managed by most DNS providers. The serial number (2024010101) increments on every zone change. + +--- + +## TTL guidance + +TTL is how long a record can be cached by resolvers, in seconds. + +| Record type | Recommended TTL | Reason | +|---|---|---| +| A, AAAA on stable infrastructure | 3600 (1 hour) to 86400 (1 day) | Reduces lookup load | +| A, AAAA during a migration | 300 (5 min) | Fast cutover | +| CNAME | 3600 to 86400 | Stable mappings | +| MX | 86400 (1 day) | Mail rarely changes | +| TXT (SPF, DMARC) | 3600 | Quick to update if needed | +| CAA | 86400 | Rarely changes | + +Lower TTL during migrations. Raise it back after. + +--- + +## Common record patterns + +### A new website, single domain + +``` +example.com. 3600 IN A 192.0.2.1 +example.com. 3600 IN AAAA 2001:db8::1 +www.example.com. 3600 IN CNAME example.com. +example.com. 3600 IN MX 10 mx.mailprovider.com. +example.com. 3600 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +_dmarc.example.com. 3600 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +example.com. 86400 IN CAA 0 issue "letsencrypt.org" +example.com. 86400 IN CAA 0 iodef "mailto:security@example.com" +``` + +### A domain that doesn't send mail + +Same as above but replace MX records with the null MX: + +``` +example.com. 86400 IN MX 0 . +``` + +And the SPF can be: + +``` +example.com. 3600 IN TXT "v=spf1 -all" +``` + +### A redirect-only domain + +For a parked or alias domain that only redirects to a primary: + +``` +parked-example.com. 3600 IN A 192.0.2.10 +parked-example.com. 86400 IN MX 0 . +parked-example.com. 3600 IN TXT "v=spf1 -all" +parked-example.com. 86400 IN CAA 0 issue "letsencrypt.org" +``` + +The A record points to whatever serves the redirect. The null MX and SPF prevent the domain from being used for email spoofing. + +--- + +## Common mistakes + +**Multiple SPF records.** Only one SPF record per domain is allowed. Two or more break SPF entirely. To "include" multiple senders, combine them in a single `v=spf1` record. + +**CNAME at the apex.** Forbidden by the DNS spec. Use ALIAS or ANAME (provider-specific) or just use an A record. + +**TTL too low long-term.** Sub-300 TTLs cause unnecessary DNS query load. Use low TTLs only during migrations. + +**Forgotten CAA record after switching CAs.** If you switch from Let's Encrypt to another CA but the CAA record only lists Let's Encrypt, the new CA can't issue. Update CAA before issuing. + +**No null MX on non-mail domains.** Domain becomes a target for spoofing. Cheap to add the null MX. + +**Manual records that should be provider-managed.** Many providers manage records for their services automatically (e.g., Vercel, Cloudflare). Manual records can drift and conflict. + +--- + +## Tooling + +For testing DNS: +- `dig` (command line, the standard) +- `nslookup` (older but widespread) +- Online tools: dnschecker.org, mxtoolbox.com, intodns.com (good for sanity-checking a fresh setup) + +For testing email auth specifically: +- mail-tester.com +- dmarcian.com +- mxtoolbox.com (deliverability tab) + +For monitoring DNS in production: +- Most monitoring services include DNS checks (uptime providers, observability platforms) +- See `monitoring-and-alerting` skill for setting these up. diff --git a/dist/pi/.agents/skills/editorial-qa/SKILL.md b/dist/pi/.agents/skills/editorial-qa/SKILL.md new file mode 100644 index 0000000..0f99207 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/SKILL.md @@ -0,0 +1,334 @@ +--- +name: editorial-qa +description: "Pre-publish QA framework for content. Brief adherence, voice consistency, fact accuracy, structure and clarity, AI-content audit, SEO and AEO compliance, internal linking and schema validation, QA at scale via sampling, the QA workflow, and the discipline that distinguishes catch-problems QA from checkbox QA. Triggers on editorial QA, content review, pre-publish review, content audit, content QA process, AI-content audit, hallucination check, content sampling, programmatic QA, voice consistency check, brief adherence check. Also triggers when a content team is shipping sloppy work, when AI-co-authored content is reaching publish unaudited, when a QA process burns reviewers out, or when a programmatic SEO set needs sampling discipline." +category: content +catalog_summary: "Pre-publish QA framework: brief adherence, voice consistency, fact accuracy, AI-content audit, AEO/SEO compliance, sampling at scale, and the workflow that distinguishes catch-problems QA from process theater" +display_order: 7 +--- + +# Editorial QA + +A senior editor's playbook for pre-publish content QA. The discipline that catches problems BEFORE content ships, not after. + +Most content QA is broken in one of two directions. The thin version is "did I read it once and is the spelling OK," which catches typos but misses brief drift, voice inconsistency, hallucinated facts, AI tells, and structural problems that reach readers as "this is fine but not memorable." The thick version is a 47-item checklist that nobody completes honestly because it is process theater: checkboxes nobody actually believes catch problems. + +This skill is the discipline of catch-problems QA. Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Checks the production volume cannot sustain get redesigned (sampling instead of full audit, automated instead of manual). The QA framework is what is left when you remove the theater. + +The skill covers three production shapes: single editorial pieces (one at a time, full QA), AI-generated drafts (with the AI-content audit that did not exist as prominently 2 years ago), and programmatic SEO sets at scale (sampling discipline, threshold gating). Each needs its own QA shape; the underlying methodology composes across all three. + +When to use this skill: building a content QA process from scratch, auditing an existing QA process that ships sloppy work or burns out the team, designing QA gates for an AI-assisted workflow, or building sampling discipline for programmatic SEO sets. + +--- + +## What this skill is for + +This skill spans pre-publish quality control. It plugs in at the END of every other content skill's output. The six-skill content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. +- `content-brief-authoring` is per-piece scope: briefs each piece. +- `content-and-copy` is execution scope: writes each piece. +- `programmatic-seo` is scaled scope: generates many pages from data. +- This skill is gate scope: verifies before publish. + +Every skill above produces a draft. This skill is what gets drafts to publishable. It is the gate where quality is actually enforced. + +The audience: editorial leads, content directors, in-house content QA, agencies with production lines, content ops managers, anyone running a writer (human or AI) and accountable for what ships. The voice is senior editor to junior editor or content marketer. Specific, opinionated, honest about where QA earns its keep versus where it becomes process theater. + +--- + +## Catch-problems QA vs checkbox QA + +The keystone distinction. Two failure modes plus the discipline. + +**Thin QA (typo-checking dressed as quality control).** "I read it once, it is fine." Catches obvious mistakes; misses brief drift, voice inconsistency, hallucinated facts, structural problems, AI tells. Output: shipped content that is "fine but not memorable." Cost: invisible until a brand misstep, a hallucinated statistic, or a competitor's content compounds and the thin set falls behind. + +**Thick QA (47-item checklist nobody completes honestly).** Every conceivable check listed; no triage. Reviewers either skim and check boxes (theater) or burn out under the cognitive load. Output: shipped content slightly more polished than thin QA produces, but the team's review velocity collapses. Cost: throughput drops; reviewers leave; the checklist atrophies into a few checks that actually run. + +**Catch-problems QA (the discipline).** Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Production volume drives sampling versus full-audit decisions. Reviewers are accountable for what they caught, not for box-completion. + +The litmus test. If the team can name the last 3 problems each QA check caught, the check earns its keep. If a check has not caught anything in 6 months, it is theater. Cut it; reallocate the attention to checks that catch real problems. + +--- + +## Brief adherence check + +Did the writer execute the brief? The check is straightforward when the brief is well-authored (see `content-brief-authoring`). + +The brief-adherence checks: + +- **Target keyword and cluster.** Present in title, first paragraph, headings. +- **Search intent and SERP format.** Piece matches the dominant SERP format (article when SERP wants article, listicle when SERP wants listicle). +- **Target audience.** Piece reads as written FOR the named audience, not for a generic reader. +- **Heading structure.** Piece follows the H2 / H3 outline in the brief, or has a documented reason for deviation. +- **Required entities.** Every entity flagged in the brief appears in the piece. +- **Internal links.** Outbound links specified in the brief are present with the right anchor text. +- **Anti-patterns.** Piece avoids the off-limits language and structures named in the brief. +- **Success criteria acknowledged.** Piece is shaped to MEASURE against the success criteria. + +The brief-adherence check is the cheapest, fastest, highest-value QA gate. It runs first in the QA sequence because catching a brief-adherence failure early saves the editor from spending time on voice and structure on a piece that will need to restart. + +If briefs are vague, this check is impossible. Fix briefs first; the QA process cannot enforce a contract that does not exist. + +Detail in [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md). + +--- + +## Voice consistency check + +Does the piece sound like the brand? + +- **Vocabulary.** Brand-specific terms used correctly; off-brand terms absent. +- **Sentence rhythm.** Matches brand voice (short and punchy versus measured and layered versus colloquial). +- **Stance.** The piece takes positions consistent with brand POV. +- **Register.** Formal or casual matches the surface (blog versus whitepaper versus help doc). +- **Voice drift in long pieces.** 3,000-word pieces often start in brand voice and drift to generic by section 4. Sample paragraphs from start, middle, end. + +For AI-co-authored pieces, voice drift is the dominant failure mode. AI assistants regress to a model-default voice unless the writer actively pulls them back. The QA check needs to read for the brand voice as much as for the words. + +Detail in [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md). + +--- + +## Fact accuracy and citation discipline + +Every claim in the piece needs to be true. The check: + +- **Statistics.** Every number sourced or removed if no source. +- **Quotes.** Every quote attributed to a real person who actually said it. +- **Case studies.** Every example refers to a real company or scenario, or labeled clearly as hypothetical. +- **Dates and timelines.** Verified, not approximate. +- **Named experts.** Real people who consented to attribution. +- **Product claims.** Matches actual product behavior, not future-tense roadmap or marketing aspiration. + +Hallucination is the dominant failure mode in AI-assisted writing. AI assistants generate plausible statistics, plausible quotes, plausible case studies, none of which are real. The fact-accuracy check is the gate that catches them. If you skip this gate on AI-generated content, you ship hallucinations. + +Citation discipline: + +- Inline citations link to authoritative sources (academic papers, industry reports, primary sources). +- Avoid citing other content marketing pages (citation laundering). +- Date the source; sources older than 3 years for fast-moving topics need refresh. + +Detail in [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md). + +--- + +## Structure and clarity check + +Does the piece work as a piece? + +- **Lede.** First 200 words answer the user's likely query (for SEO/AEO pieces) OR establish the thesis (for thought leadership). +- **Sectioning.** H2s map to user mental model, not writer enthusiasm. +- **Section length.** Even-ish across H2s. One massive section plus four 80-word sections signals broken structure. +- **Reading flow.** Paragraphs connect, sentences vary in length. +- **Specificity vs abstraction.** Claims are concrete, not vague. +- **Endings.** Piece concludes with something specific (action, question, idea), not throat-clearing filler. + +Detail in [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md). + +--- + +## AI-content audit + +The QA check that did not exist as prominently 2 years ago. AI-co-authored content has detectable patterns even when written by a competent human editor. + +**AI tells (pattern recognition).** + +- Excessive em-dashes (model-default punctuation) +- Predictable opening phrasings (throat-clearing openers that announce what the piece is about to do; the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener) +- Predictable concluding paragraphs (throat-clearing wrap-ups, "By following these steps") +- Bullet-list overuse where prose would serve +- "On the other hand" / "However" overuse +- Forced bilateral framing (always "two sides" even when one side is right) +- Sentence-end filler ("...and more.", "...among other things.", "...for example.") +- Repetitive sentence-rhythm (every paragraph 2-3 sentences, similar lengths) +- Generic openings (descriptive paragraphs that could open any article on the topic) +- Bridging fluff ("That said", "With that in mind", "Moving on") +- Hedge stacking ("typically", "generally", "often") on claims that should be specific + +**Hallucination patterns (factual errors).** + +- Statistics that look authoritative (specific decimal places, named source) but the source does not exist or does not say that +- Quotes attributed to real people who did not say it +- Case studies about companies that do not exist +- Citations to URLs that 404 or never existed +- "Studies show" claims with no actual study behind them +- Made-up product features + +**Voice drift.** + +- Piece starts in brand voice, drifts to generic by section 4 +- Vocabulary regresses to model defaults +- Stance becomes diplomatic ("there are good arguments on all sides") when brand stance was clear + +The audit shape. Read with these patterns top-of-mind. Flag any match. The bar is not "AI was used" (it almost always is now); the bar is "would a careful human editor have shipped this." If the patterns above are present, the piece needs another revision pass with the patterns called out. + +Detail in [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md). + +--- + +## SEO and AEO compliance check + +Does the piece serve search engines AND answer engines? + +**SEO checks.** + +- Target keyword in title, H1, first paragraph, slug +- Heading hierarchy clean (no orphan H3s, no H4 without H3) +- Image alt text descriptive +- Meta description compelling and keyword-aware +- Internal links specified in brief are present +- External links open in new tab (typically) and have rel attributes appropriate +- URL slug short and descriptive + +**AEO checks.** + +- 40 to 60 word answer paragraph immediately following each H2 question +- TL;DR section present (for pillar pieces) +- FAQ section with FAQPage schema (for pieces where Q and A format applies) +- Specific statistics with cited sources (AI engines weight statistics with sources) +- Named entities (experts, methods, tools) consistently mentioned (entity coverage signals) +- Distinctive POV that is attributable to the brand + +Detail in [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md). + +--- + +## Internal linking and schema validation + +**Internal linking.** + +- Outbound links specified in brief are present with correct anchor text +- Anchor text varies (avoid every link being "click here" or every link being the exact-match target keyword) +- Link targets are live (no 404s, no links to deprecated pages) +- Internal link count appropriate to length (3 to 7 for typical 1,500-word piece, 8 to 15 for pillars) +- Self-cannibalization check: piece does not compete with existing pieces for same target keyword + +**Schema validation.** + +- Article schema present on most pieces; HowTo schema on instructional pieces; FAQPage schema where Q and A applies +- Schema validates against schema.org definitions (no missing required fields, no malformed JSON-LD) +- Schema is consistent with on-page content (do not claim 5-star rating in schema if no rating on page) + +Detail in [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md). + +--- + +## QA at scale + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. Sampling discipline replaces it. + +**Sampling strategy.** + +- Random sample 50 to 200 pages per audit cycle +- Balance the sample across data shape (sparse versus dense records, recent versus old generation, popular versus niche categories) +- Fixed sample percentage as set grows; absolute count plateaus around 200 once the set is large + +**Automated checks at scale.** + +- Heading structure validation +- Schema markup validation +- Word count (flag pages below the floor, e.g. 600 words) +- Duplicate content check (compare each page against the rest of the set) +- Broken-link check +- Image-presence check (where templates expect images) + +**Manual checks on sampled pages.** + +- Brief-adherence equivalent (template-adherence check: does the page execute the template?) +- Top-200-word answer quality +- Whether the page would satisfy a human user's likely query +- Whether the page reads as distinctive versus templated +- Spot-check for AI hallucination if AI was in the loop + +**Threshold gating.** + +- If more than 5% of sampled pages fail the manual review, halt new generation +- Fix the template OR data quality issue before resuming +- Document the threshold breach in the QA log so patterns become visible + +Detail in [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md). + +--- + +## The QA workflow + +Ownership and sequencing. + +**Single QA owner per piece**, not a committee. The owner is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +**Sequencing.** Brief-adherence, then fact-accuracy, then structure, then AI-content audit, then voice, then SEO/AEO, then internal linking, then schema. Brief-adherence first because it is the cheapest gate; SEO/AEO checks last because they are easiest to fix and rarely halt-conditions. + +**Halt vs flag vs auto-fix.** + +- Brief-adherence and fact-accuracy can HALT (return to writer). +- Voice and structure FLAG with suggestions; editor judgment decides whether to halt or revise inline. +- SEO/AEO and schema typically auto-fix (slug, meta description, schema markup are mechanical edits the editor or a script can ship without writer involvement). + +**Escalation.** When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +Detail in [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-qa-failures.md`](references/common-qa-failures.md). + +- "Our QA process is a 47-item checklist nobody completes." Checkbox theater; cut to the checks that earned their keep. +- "We caught zero problems in QA last quarter." Either the process is broken or the writers are extraordinary; investigate. +- "Editor and writer disagree on voice." Voice guidelines are vague; document brand voice with concrete examples. +- "AI hallucinations made it to publish." Fact-accuracy gate skipped or rushed; reinstate as halt-condition. +- "Our pSEO set is shipping thin pages." Sampling discipline missing or thresholds not honored. +- "QA takes longer than the writing." Wrong sequencing; brief-adherence early catches problems before voice/structure investment. +- "Reviewers burn out." Checks that do not catch problems are taxing reviewer attention; cut them. +- "Voice drifts halfway through long pieces." Sample mid-piece paragraphs, not just open and close. +- "We never go back to evaluate." QA log archives feed pattern detection; quarterly review. +- "Different editors apply different standards." Calibration sessions where editors review the same piece independently and reconcile. +- "We ship and discover problems on social." QA was not catching the problem class that is reaching readers; add a check for that class. + +--- + +## The framework: 12 considerations for editorial QA + +When designing or auditing a QA process, walk these 12 considerations. + +1. **Catch-problems vs checkbox.** Every check earns its keep by catching a class of failure. +2. **Brief-adherence first.** Cheapest, fastest, highest-value gate. +3. **Fact-accuracy as halt-condition.** AI hallucinations do not ship to readers. +4. **Voice consistency including mid-piece sampling.** Long pieces drift; sample throughout. +5. **AI-content audit.** Pattern recognition for AI tells, hallucinations, voice drift. +6. **Structure and clarity.** Lede, sectioning, even-ish length, specific endings. +7. **SEO and AEO compliance.** Answer paragraphs, schema, entity coverage. +8. **Internal linking and schema validation.** Outbound links live, anchor text varies, schema validates. +9. **Sampling at scale.** Programmatic and high-volume sets need sampling, not full-audit. +10. **Threshold gating.** Failure rate above threshold halts generation; document breaches. +11. **Single QA owner per piece.** Accountability not diffused across committee. +12. **Sequencing.** Brief-adherence to fact-accuracy to structure to AI-audit to voice to SEO/AEO to linking to schema. + +The output of the framework is a QA process the team can run repeatably: each check named, each owner named, each halt-condition documented, each sampling rule specified for programmatic surfaces. + +--- + +## Reference files + +- [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md) - Every brief field as a QA check, with how to verify and what failure looks like. +- [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md) - Vocabulary, rhythm, stance, register, mid-piece sampling discipline for long pieces. +- [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md) - Verification methodology, hallucination detection, citation rules, source-age guidelines. +- [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md) - Lede patterns, sectioning principles, endings, structural anti-patterns. +- [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md) - 11 AI tells, 6 hallucination patterns, voice drift detection, worked example with revision. +- [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md) - SEO and AEO checks combined into one workflow. +- [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md) - Link discipline, anchor text variation, schema patterns and validation. +- [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md) - Sampling strategy, automated checks, manual review at scale, threshold gating. +- [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md) - Ownership, sequencing, halt versus flag versus auto-fix, escalation patterns. +- [`references/common-qa-failures.md`](references/common-qa-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: QA is where quality gets enforced + +Every other skill in the content suite produces drafts. QA is the discipline that turns drafts into publishable work. It is also where every previous decision (brief shape, voice guidelines, hub architecture, programmatic template) gets tested against actual output. Skipping QA is not "moving fast"; it is shipping the failure modes of every upstream decision unfiltered. + +The QA process is the immune system of the content program: invisible when it is working, catastrophic in its absence. + +When in doubt about whether a QA process is ready, ask: does each check name a class of failure it catches, has each check actually caught something in the last 6 months, is brief-adherence first in the sequence, is fact-accuracy a halt-condition, is the AI-content audit included, does sampling discipline apply to scaled surfaces? If yes to all of those, the process is real. If no to any, the gap is where readers will encounter the failure that QA did not catch. diff --git a/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md new file mode 100644 index 0000000..57337e9 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md @@ -0,0 +1,119 @@ +# AI-content audit patterns + +The 11 AI tells, the 6 hallucination patterns, voice drift detection, a worked example. The QA check that did not exist as prominently 2 years ago and is now load-bearing for any program with AI in the loop. + +--- + +## The 11 AI tells + +Pattern recognition. Read with these top-of-mind; flag any match. + +**1. Excessive em-dashes.** Model-default punctuation. A piece with 8 em-dashes per 1,000 words is almost certainly AI-drafted. The fix: replace with periods, semicolons, or rephrase the sentence. + +**2. Predictable opening phrasings.** Throat-clearing openers that announce what the piece is about to do (the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener). These openings appear in AI output across topics; pattern-match against the team's curated do-not-use list and cut. + +**3. Predictable concluding paragraphs.** Throat-clearing wrap-ups. "By following these steps." "By implementing these strategies." "Now you have a comprehensive understanding of." All cut. + +**4. Bullet-list overuse.** AI defaults to bullets when prose would serve. Bullets fragment reading flow and signal AI drafting. Convert to prose where prose makes the connection between items clearer. + +**5. "On the other hand" / "However" overuse.** Forced bilateral framing pattern. Used 4+ times in 1,500 words is the AI tell. + +**6. Forced bilateral framing.** "While X has its advantages, Y also has merits." Always two sides given equal weight even when one side is right. The fix: pick a position; defend it; let the contrary view get one short acknowledgment. + +**7. Sentence-end filler.** "...and more." "...among other things." "...for example." All padding. Cut. + +**8. Repetitive sentence-rhythm.** Every paragraph 2 or 3 sentences of similar length. Read aloud: monotonous. The fix: deliberate variation in sentence length and paragraph shape. + +**9. Generic openings.** Descriptive paragraphs that could open any article on the topic. "Customer experience is more important than ever in today's competitive landscape." Cut; replace with a specific opening tied to the piece's thesis or the reader's specific query. + +**10. Bridging fluff.** "That said." "With that in mind." "Moving on." Throat-clearing transitions; cut. + +**11. Hedge stacking.** "Typically," "generally," "often" stacked on claims that should be specific. AI hedges to avoid being wrong; the result is content that says nothing definite. Replace hedges with specifics or cut the hedge. + +--- + +## The 6 hallucination patterns + +Factual errors that AI assistants generate and how to detect each. + +**1. Specific decimal places, named source, source does not exist.** "According to a 2024 Forrester report, 67.3% of B2B buyers..." The decimal place plus named source is the AI tell. Detection: search the source. If it does not exist or does not say that, cut the claim. + +**2. Quotes attributed to real people the person did not say.** "As Marc Benioff said in his 2024 keynote..." Plausible because Benioff gives keynotes. Detection: search for the quote in actual transcripts; verify against original source. If the quote does not match a real source, cut. + +**3. Case studies about companies that do not exist.** "Acme Innovations reduced their cycle time 40% using..." Detection: search the company name. If it does not appear in business directories, news coverage, or LinkedIn, the case study is fake. + +**4. Citations to URLs that 404 or never existed.** Detection: click every external link. 404s and dead links are signals; multiple dead links signal multiple unverified claims. + +**5. "Studies show" claims with no actual study.** "Studies show that 45% of marketers..." with no link, no journal, no year. Detection: ask for the study. If the writer cannot produce it, cut the claim. + +**6. Made-up product features.** "Product X now supports automatic Y" when the product does not. Detection: verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Voice drift detection + +The mid-piece drift pattern in AI-co-authored content. + +**The pattern.** Piece starts in brand voice (because the writer set up the opening prompt with brand voice cues). By section 4, the voice has drifted to model-default. The drift is gradual; the start and end pass voice review while the middle fails. + +**Detection methodology.** + +1. Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. +2. Compare each sample to the brand voice doc's vocabulary, rhythm, stance, register. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. + +**The fix.** Send back with the drifted sections highlighted. Specific note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes from the voice doc]." + +--- + +## Worked example: AI tells in a 4-paragraph excerpt + +Original AI-drafted excerpt (with AI tells in bold for the audit): + +> **In today's fast-paced digital landscape**, content marketing has become more important than ever. **Whether you're a small business owner or a Fortune 500 executive**, understanding the nuances of effective content strategy is crucial for success. +> +> There are many factors to consider when developing a content strategy. **On one hand**, you need to focus on creating high-quality content that resonates with your audience. **On the other hand**, you also need to ensure that your content is optimized for search engines, social media platforms, **and more**. +> +> **It's important to note** that successful content marketing requires a balance between creativity and analytics. **Studies show** that companies that prioritize data-driven decision-making see significant improvements in their content performance metrics. +> +> **By following these steps**, you'll be well on your way to creating a content strategy that drives results. Remember that consistency is key, and that great content takes time to produce. + +The audit tags 9 AI tells in 4 paragraphs (more than 2 per paragraph). + +Revised excerpt (AI tells removed, voice tightened, specifics added): + +> Content marketing produces results when the strategy answers two questions: who are we writing for, and what do they need to do after reading. The B2B SaaS team writing for senior data engineers asks different questions than the consumer brand writing for first-time buyers. Both work; conflating them does not. +> +> The trade-off most teams get wrong is craft against measurement. Pieces optimized for search rankings often read as templated; pieces optimized for craft often miss the structural patterns that earn rankings. The fix is not balance; it is sequencing. Brief the structural patterns first; write to craft within them. +> +> Companies that ship measurable content programs share three patterns: a brief discipline that survives writer changes, a voice doc specific enough to enforce, and a fact-check gate that does not compromise under deadline pressure. Companies that miss any of the three produce inconsistent output regardless of writer talent. +> +> The next step is auditing your current process against those three patterns. If the brief is vague, fix the brief. If the voice doc is aspirational, tighten it with concrete examples. If the fact-check gate is optional, make it a halt-condition. + +The revision removed AI tells, added specifics (the two audience examples, the three patterns), and replaced the closing throat-clearing with a concrete next-step. + +--- + +## The audit checklist + +For each AI-co-authored draft, walk this checklist. + +1. Read the first 200 words. Does the opening match any of the 11 AI tells? Flag. +2. Sample 2 paragraphs from the middle. Does either match AI tells? Does the voice match the brand voice doc? Flag. +3. Read the last 200 words. Does the closing match any of the 11 AI tells? Flag. +4. Search the piece for em-dashes; count. More than 5 in a 1,500-word piece is suspicious. +5. Search for forced bilateral framing patterns. Count. +6. Verify every statistic, quote, case study, citation, and product claim per the fact-accuracy methodology. +7. Sample 3 to 5 internal links; verify they go where the brief specified and the targets exist. + +If 3+ items flag, halt the piece and return for revision with the specific items called out. + +--- + +## Methodology-level choices that stay in the public skill + +The 11 AI tells, the 6 hallucination patterns, voice drift detection methodology, the worked example revision pattern, the 7-step audit checklist. + +## Implementation choices that stay internal + +The specific tooling for automated AI-tell detection (regex patterns, classifier models, prompt-based audits). The specific brand voice doc that drives voice-drift comparison. The specific archive of past AI-tell catches that informs ongoing pattern recognition. The specific revision workflow when AI tells are detected (writer's editing tool, AI assistant configured for revision-not-drafting, human-only revision). These vary by team and tooling preferences. diff --git a/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md b/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md new file mode 100644 index 0000000..3f711e9 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md @@ -0,0 +1,137 @@ +# Brief adherence checklist + +Every brief field as a QA check, with how to verify and what failure looks like. + +The brief-adherence check is the first QA gate in sequence. It is the cheapest gate to run and the highest-value gate to pass: catching a brief-adherence failure early saves the editor from spending review time on voice, structure, and fact-accuracy on a piece that will need to restart. + +This check assumes the brief was authored under the discipline of `content-brief-authoring`. If briefs are vague or thin, fix briefs first; the brief-adherence check enforces a contract that has to exist. + +--- + +## The checklist + +For each piece, walk these 8 fields. + +### 1. Target keyword and cluster + +**Verify.** Pull the brief's primary keyword and 3 to 5 supporting cluster keywords. Search the piece for each. + +**Pass.** Primary keyword appears in title, H1 (if separate), first paragraph, and at least one H2. Supporting keywords appear naturally across the piece without stuffing. + +**Fail patterns.** + +- Primary keyword missing from title or first paragraph +- Cluster keywords absent (piece read like a generic article on the topic) +- Keyword stuffing: same exact-match phrase repeated 8+ times in 1,500 words + +### 2. Search intent and SERP format + +**Verify.** Pull the brief's intent classification and dominant SERP format. Compare to the piece's shape. + +**Pass.** Piece shape matches the format the brief specified: long-form article when SERP wants long-form, listicle when SERP wants listicle, comparison when SERP wants comparison. + +**Fail patterns.** + +- Brief specified listicle; piece is long-form prose +- Brief specified commercial-investigation intent; piece reads as informational with no purchase decision support +- Brief flagged the SERP intent override; piece ignored the override + +### 3. Target audience + +**Verify.** Read the first 200 words and the closing 200 words with the brief's audience description in mind. + +**Pass.** Piece reads as written FOR the named audience: vocabulary, examples, and assumed knowledge match the audience's level. + +**Fail patterns.** + +- Brief specified senior data engineers; piece explains "what is a database" in the introduction +- Brief specified non-technical CMOs; piece uses unexplained jargon +- Piece reads as written for a generic reader rather than the named audience + +### 4. Heading structure + +**Verify.** Compare the piece's H2 / H3 outline to the brief's specified outline. + +**Pass.** Piece follows the brief's outline. Where the writer deviated, the brief's deviation note explains why or the writer's first-draft note flags the deviation for editor review. + +**Fail patterns.** + +- Brief specified 6 H2s; piece has 4 or 9 with no documented reason +- H2 order changed without explanation +- Sections from the outline missing entirely + +### 5. Required entities + +**Verify.** Pull the brief's required-entity list. Search the piece for each. + +**Pass.** Every required entity appears in the piece, ideally in the section the brief specified. Standard entities are covered. Gap entities (the differentiation opportunity) are present where the brief committed to them. + +**Fail patterns.** + +- Brief required mentioning CUPED in the methodology section; CUPED is not in the piece +- Required entities mentioned in passing once each; depth-of-coverage requirements not met +- Gap entities skipped because they were "optional" (they were not; the brief committed to them) + +### 6. Internal links + +**Verify.** Pull the brief's outbound internal-link list with anchor text. Check the piece for each link. + +**Pass.** Every required outbound link is present with the specified anchor text. Optional outbound links are either present or noted as skipped with reason. + +**Fail patterns.** + +- Brief specified 4 required outbound links; piece has 2 +- Anchor text differs from the specified anchor text without reason +- Links to deprecated pages (the writer copied old anchor links from a stale draft) + +### 7. Anti-patterns + +**Verify.** Pull the brief's anti-pattern list. Read the piece looking for each pattern. + +**Pass.** Piece avoids every named anti-pattern. The do-not-use word list, off-brand voice, off-topic tangents, AI clichés, and structural patterns the brief explicitly forbade are absent. + +**Fail patterns.** + +- Anti-pattern words from the do-not-use list present (e.g., the writer slipped into corporate-speak adjectives) +- Off-topic tangents the brief warned against (the writer wandered into adjacent facets the cluster covers separately) +- Voice drifted toward a register the brief excluded + +### 8. Success criteria acknowledged + +**Verify.** Read the piece with the brief's success criteria in mind. Does the piece's shape support the criteria? + +**Pass.** Piece is shaped to MEASURE against the success criteria: ranking-targeted pieces have keyword-aware structure, citation-targeted pieces have answer paragraphs and statistics, conversion-targeted pieces have CTAs and decision-support content. + +**Fail patterns.** + +- Brief said "rank top 10 for [keyword]"; piece misses the structural patterns that earn ranking (no answer paragraphs, no entity coverage, no internal-link plan) +- Brief said "drive 50 trial signups in 30 days"; piece has no clear CTA path to signup +- Success criteria treated as an afterthought rather than a design parameter + +--- + +## What halt-condition looks like + +Brief-adherence failures are halt-conditions: return the piece to the writer with the specific failures named. + +The return note is short. "This piece misses the brief in 3 places: [field 1], [field 2], [field 3]. The brief specified [X]; the piece does [Y]. Please revise and return for round 2." + +Editors who try to fix brief-adherence failures themselves end up rewriting the piece. Better to halt cleanly, return to the writer, and let the writer execute the contract that already existed in the brief. + +--- + +## When briefs are too vague to enforce + +Sometimes the brief itself is the problem. The brief specified "engineers" without naming the seniority level. The brief specified "informational intent" without checking the SERP. The brief specified entities without depth-of-coverage requirements. + +When the brief is too vague, brief-adherence cannot enforce anything. The fix is upstream: tighten brief authoring discipline (see `content-brief-authoring`). The brief is the contract; vague contracts produce vague output regardless of writer skill. + +--- + +## Methodology-level choices that stay in the public skill + +The 8-field checklist, the halt-condition discipline, the upstream-fix observation when briefs are vague. + +## Implementation choices that stay internal + +The specific format the team uses for return notes (Slack message template, Notion row, ticketing system field structure). The specific tooling that stores brief metadata for diff-checking against pieces. The specific automation (if any) that surfaces brief-adherence failures before manual review. These vary by team and stack. diff --git a/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md b/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md new file mode 100644 index 0000000..9f97eac --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md @@ -0,0 +1,168 @@ +# Common QA failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: QA either drifted into theater (checks that do not catch problems but cost reviewer attention) or skipped the gates that catch the problems readers actually encounter. The fix is upstream: cut theater checks, reinstate gates that actually catch problems. + +--- + +## "Our QA process is a 47-item checklist nobody completes" + +**Symptom.** The checklist exists. Nobody completes it honestly. Reviewers either skim and check boxes or burn out under the cognitive load. + +**Diagnosis.** Checkbox theater. The checklist accumulated over time as new failures appeared and got added; nothing was ever removed. The list grew past what reviewer attention can sustain. + +**Fix.** Audit the checklist. For each item, ask: when did this last catch a problem? If the answer is "never" or "more than 6 months ago," cut it. The remaining items are the catch-problems checks; the cut items were theater. + +**Prevention.** Quarterly review of the checklist. Each new check earns its keep by catching at least one problem within 90 days; checks that do not catch problems get cut. + +--- + +## "We caught zero problems in QA last quarter" + +**Symptom.** No QA returns. No halt-conditions. No revision rounds. Pieces ship clean every time. + +**Diagnosis.** Either the writers are extraordinary or the process is broken. Almost always the latter. + +**Fix.** Audit recently-shipped pieces independently of the original QA. Find the problems QA missed: hallucinated statistics, voice drift in long pieces, broken links, schema validation failures. Document each. Reinstate the QA gate that should have caught the failure. + +**The pattern.** When QA catches nothing for a quarter, reviewers have stopped reading carefully. The fix is not "trust the writers"; it is reinstating the discipline that was nominally still running. + +--- + +## "Editor and writer disagree on voice" + +**Symptom.** Editor returns the piece with voice notes; writer pushes back; edits go back and forth without convergence. + +**Diagnosis.** Voice guidelines are vague. Both editor and writer are interpreting the brand voice doc differently because the doc does not specify enough. + +**Fix.** Update the voice doc with concrete examples of the disputed dimension. If the dispute was about sentence rhythm, add 5 paired examples (the rhythm we want, the rhythm we do not want). The voice doc gets sharper; future disputes resolve by reference to the examples. + +**Prevention.** Quarterly voice calibration sessions (see `voice-consistency-patterns.md`) where editors review the same piece independently and reconcile. + +--- + +## "AI hallucinations made it to publish" + +**Symptom.** A statistic, quote, citation, or product claim in a published piece turns out to be invented. Reader (or competitor) flags it. + +**Diagnosis.** The fact-accuracy gate was skipped or rushed. + +**Fix.** Two parts. + +- Immediate: correct the published piece, document the failure in the QA log. +- Process: reinstate fact-accuracy as a halt-condition. AI hallucinations do not progress past this gate. If the gate is too slow, automate the easy parts (named-entity extraction, statistic detection) so manual verification focuses on the hard parts. + +**Prevention.** Fact-accuracy gate runs second in the QA sequence (after brief-adherence). Detail in `fact-accuracy-and-citation-discipline.md`. + +--- + +## "Our pSEO set is shipping thin pages" + +**Symptom.** Programmatic pSEO set is producing pages with insufficient data; pages render at 200 to 400 words of templated boilerplate; algorithm risk compounds. + +**Diagnosis.** Sampling discipline missing or thresholds not honored. The set was generating pages without QC checking the quality at the data-shape level. + +**Fix.** Implement the sampling discipline (see `qa-at-scale-patterns.md`). Set the 5% failure threshold; halt new generation when breached. Audit the existing set; noindex or remove pages below the data depth threshold. + +**Prevention.** Sampling and threshold gating built into the program at design time, not retrofitted. + +--- + +## "QA takes longer than the writing" + +**Symptom.** The team's writers ship drafts in 4 hours; QA cycle takes 6 hours. The bottleneck is review. + +**Diagnosis.** Wrong sequencing. The team is running expensive checks (voice, structure) before cheap checks (brief-adherence, fact-accuracy). When a piece fails at gate 1, the time spent on gates 5 to 8 is wasted. + +**Fix.** Reorder the sequence. Brief-adherence first; fact-accuracy second; halt-conditions short-circuit the rest of the gates. Voice and SEO checks last because they are easiest to fix and rarely halt-conditions. + +**Prevention.** The sequencing discipline is documented in `qa-workflow-templates.md`; new editors get the sequence in their onboarding. + +--- + +## "Reviewers burn out" + +**Symptom.** Editors who used to review carefully now skim. The catch rate drops. Editors leave the team. + +**Diagnosis.** The QA load exceeds reviewer capacity. Often because checks that do not catch problems are taxing reviewer attention. + +**Fix.** Cut theater checks (the same fix as the 47-item checklist failure). Burn-out reduces with the cognitive load. + +**Also.** Verify that production volume matches reviewer capacity. If the team is shipping 30 pieces a week with 1 editor, the volume is wrong. Either reduce volume, add reviewers, or accept lower quality with eyes open. + +--- + +## "Voice drifts halfway through long pieces" + +**Symptom.** 3,000-word pillar pieces start in brand voice; by section 4 they read generic. + +**Diagnosis.** Voice review only sampled the start and end. Mid-piece drift went undetected. + +**Fix.** Mid-piece sampling discipline (see `voice-consistency-patterns.md`). Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. AI-co-authored pieces especially need this. + +**Prevention.** Voice review template explicitly requires mid-piece sampling. + +--- + +## "We never go back to evaluate" + +**Symptom.** QA process exists. QA log accumulates. Nobody reviews the log. + +**Diagnosis.** The log is an artifact, not a feedback mechanism. Patterns the log surfaces never reach the editorial process owner. + +**Fix.** Quarterly QA log review. The owner reads the log; pattern observations get translated into process changes (brief tweaks, writer feedback, workflow adjustments, automation additions). + +**Prevention.** The quarterly review is calendar-anchored. Skipping it is the failure mode. + +--- + +## "Different editors apply different standards" + +**Symptom.** A piece shipped under editor A would be returned under editor B (or vice versa). Writers receive inconsistent feedback. Quality varies by which editor caught the piece. + +**Diagnosis.** Voice and structural standards have drifted between editors. Without calibration, individual editors apply individual taste. + +**Fix.** Calibration sessions. Three editors review the same piece independently; the team reads the three assessments together and reconciles. The consensus updates the voice doc and the QA process; future reviews stay consistent. + +**Prevention.** Calibration sessions quarterly minimum. Onboarding new editors includes a calibration round before they review live pieces solo. + +--- + +## "We ship and discover problems on social" + +**Symptom.** Readers (or competitors, or critics on social) flag problems that QA did not catch. + +**Diagnosis.** QA was not catching the problem class that is reaching readers. The class might be hallucinations, voice drift, structural problems, factual errors, or off-brand tone. + +**Fix.** Identify the class of failure that reached readers. Add a QA check that catches that class. Document the addition in the QA log so the pattern becomes visible. + +**Prevention.** The QA process evolves with feedback from shipped pieces. New failure classes that reach readers feed new QA checks. + +--- + +## "AI tells slipped through" + +**Symptom.** Published piece reads as AI-generated despite a human editor reviewing it. Readers or AI-detection tools flag it. + +**Diagnosis.** The AI-content audit either was not run or ran without the pattern recognition the editor needed. + +**Fix.** Add the AI-content audit as a named gate in the QA sequence (see `ai-content-audit-patterns.md`). Train the editor on the 11 AI tells; provide the worked example as reference. The audit becomes a 5-minute discipline rather than an unstructured "does this read OK" check. + +**Prevention.** Every AI-co-authored piece runs through the audit. The audit is a named gate, not an implicit step. + +--- + +## The pattern across most failures + +Most QA failures are designed-in. The process either drifted into theater (cuts needed) or skipped gates that should have been there (gates needed). The discipline is upstream: design the QA process around catch-problems, not around process appearance, and the operational discipline at scale becomes manageable. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the prevention guidance, the upstream-discipline observation. + +## Implementation choices that stay internal + +The specific QA log format and tooling. The specific calibration session cadence and team composition. The specific automation that supports each gate (statistic detection, hallucination flagging, schema validation, link audit). The specific escalation pathways within the team's structure. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md b/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md new file mode 100644 index 0000000..17d8d83 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md @@ -0,0 +1,113 @@ +# Fact accuracy and citation discipline + +Verification methodology, hallucination detection, citation rules, source-age guidelines. + +Fact accuracy is a halt-condition QA gate. Hallucinations from AI-assisted writing reach readers if the gate is skipped or rushed. The discipline below is what makes the gate work at production speed without becoming the bottleneck. + +--- + +## What gets fact-checked + +Every claim that could be wrong. The categories. + +**Statistics.** Every number in the piece needs a source. "23% of feature flag rollouts include a kill switch" needs a source link to the survey, report, or dataset that produced the 23%. Without a source, the number is either removed or replaced with sourced equivalent. + +**Quotes.** Every quote attributed to a real person needs verification: the person said it, the quote is verbatim or correctly paraphrased, the attribution is accurate, the person consents to attribution. + +**Case studies.** Every example refers to a real company or scenario, OR is labeled clearly as hypothetical. "Acme Corp reduced churn by 40% using this method" needs verification that Acme exists, the method was used, the 40% is real. If the example is hypothetical, the piece labels it: "Imagine a SaaS company..." + +**Dates and timelines.** Verified, not approximate. "Google launched feature X in March 2025" needs verification of the exact month and year. + +**Named experts.** Real people who consented to being attributed. The piece should not attribute claims to "Ronny Kohavi" without verifying the attribution traces to actual published work or direct consent. + +**Product claims.** Match actual product behavior. The product does what the piece says it does, in the way the piece says it does, today, in production. Future-tense roadmap items get clearly labeled as roadmap; marketing aspirations get cut. + +--- + +## The verification methodology + +For each claim in the piece, the editor follows one of three paths. + +**Path 1: in-line citation present.** Click through the citation. Does the source exist? Does the source actually say the claimed thing? Is the source the original (not a citation-of-citation)? + +**Path 2: claim has no citation but is a known fact.** Editor verifies via authoritative source (academic paper, primary government data, official company announcement). Add the citation; do not let the piece ship with uncited claims. + +**Path 3: claim has no citation and is not a known fact.** Halt. Return to writer with the claim flagged. Either the writer adds verification, or the claim gets removed. + +The discipline. No claim ships without verification. "I'm pretty sure I read this somewhere" is not verification. + +--- + +## Hallucination detection + +AI-assisted writing produces plausible-but-fake claims at scale. The patterns to recognize. + +**Pattern 1: specific decimal places, named source, source does not exist.** "According to a 2024 Forrester report, 67.3% of B2B buyers prefer..." Sounds authoritative. The Forrester report does not exist, or exists but does not say that. The decimal place is the AI tell; AI assistants generate false precision to sound credible. + +**Pattern 2: quotes attributed to real people the person did not say.** "As Marc Benioff said in his keynote..." Plausible because Benioff gives keynotes. The specific quote is fabricated. Verify quotes against the actual recording, transcript, or primary source. + +**Pattern 3: case studies about companies that do not exist.** "Acme Innovations reduced their cycle time 40% using..." The company does not appear in any business directory; the case study is invented. Search the company name; if it does not surface in legitimate sources, the case study is fake. + +**Pattern 4: citations to URLs that 404 or never existed.** Click every external link. 404s and dead links are signals; a piece with multiple dead links has multiple unverified claims. + +**Pattern 5: "Studies show" claims with no actual study.** "Studies show that..." with no link, no journal, no year. Either the writer provides the study or the claim gets cut. + +**Pattern 6: made-up product features.** "[Product] now supports automatic X" when the product does not. Verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Citation discipline + +When citations are present, they need to be the right kind. + +**Authoritative sources.** + +- Academic papers (peer-reviewed journals) +- Industry reports from established research firms (Forrester, Gartner, McKinsey, IDC) when verified +- Primary government data (BLS, Census, SEC filings) +- Original company announcements (the company's own blog, press release, official documentation) +- First-party data the brand owns and has published + +**Avoid citation laundering.** + +Citing another content marketing page that itself cites a primary source is laundering. The chain of attribution gets murky; the claim's accuracy degrades through each hop. Cite the primary source directly. + +**Date the source.** + +Sources older than 3 years for fast-moving topics need refresh. "According to a 2018 Gartner report" is a yellow flag for content about a 2026 topic; the data might still be true but probably is not. Either find a more recent source or note the date and explain why the older source still applies. + +--- + +## When the writer disputes the fact-check + +Sometimes the editor flags a claim and the writer pushes back. "I read it in the original source; here's the link." Two outcomes. + +**Outcome 1: writer's source verifies the claim.** Add the citation; ship the piece. The QA process worked. + +**Outcome 2: writer's source does not verify the claim.** This is where the conversation gets uncomfortable. The writer thought they had a source; the source does not say what they thought. The fix is the same: cut the claim or find a verifying source. Do not ship the unverified claim because the writer is sure it is true. + +--- + +## Fact-check log + +Maintain a log of fact-check failures across pieces. Patterns surface over time. + +**Log fields.** Piece, claim, failure type (hallucination / wrong citation / outdated source / unverifiable), writer (if naming patterns), resolution (cut / re-sourced / verified). + +**Patterns the log surfaces.** + +- One writer repeatedly produces hallucinations: writer needs feedback or different work +- One topic area produces frequent hallucinations: that topic needs more verification time built in +- AI-co-authored pieces fail at higher rates than human-authored: AI workflow needs additional guardrails + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The verification methodology, the 6 hallucination patterns, the citation discipline rules, the fact-check log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing the fact-check log (spreadsheet, database, Notion). The specific automation (if any) for surfacing claims that need verification (named-entity extractors, statistic detectors). The specific verification workflow when the editor does not have the bandwidth to fact-check personally (assistant-powered verification, fact-checking service integration). These vary by team scale and tooling preferences. diff --git a/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md b/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md new file mode 100644 index 0000000..bce4dd4 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md @@ -0,0 +1,125 @@ +# Internal linking and schema validation + +Link discipline, anchor text variation, schema patterns and validation. + +The internal-linking and schema layer is where SEO compounds. Each piece's link contribution and schema contribution feeds the program's overall ranking and citation signal. QA enforces the discipline so individual pieces do not drift from the program's link graph and schema standards. + +--- + +## Internal linking + +### Outbound links specified in brief + +- **The brief named X outbound links.** Verify each is present in the piece. +- **Anchor text matches the brief's specification.** "Click here" is dead anchor text; the brief should specify keyword-aware anchor text per link. +- **Links go where the brief said.** The link target is the page the brief specified, not a deprecated alternate or a different page that happens to share the topic. + +### Anchor text variation + +The "every link has the same anchor text" anti-pattern. + +**Pattern.** A piece links to the pillar 3 times. All 3 links use the exact-match keyword as anchor. This signals manipulation to ranking systems and dilutes the anchor's signal. + +**Fix.** Vary the anchor across the 3 links. One uses the exact-match keyword; one uses a descriptive natural-language phrase; one uses a brand-mention anchor or a context-driven phrase. + +**The audit.** For each piece, count the outbound links to the same target. If multiple links to the same target use identical anchor text, vary at least one. + +### Link-target liveness + +- **Every internal link target exists.** No 404s. The link goes to a live page on the site. +- **No links to deprecated pages.** If a target page was retired, the link should redirect (via 301) or the link itself should be replaced. +- **External links work.** Click them; verify they resolve and lead to the intended source. + +The external-link audit catches hallucinated citations (see `fact-accuracy-and-citation-discipline.md`) and link rot. + +### Internal link count + +- **3 to 7 internal links for a typical 1,500-word piece.** Below 3 signals under-linked (orphan-shaped). Above 10 signals link-stuffing. +- **8 to 15 for a pillar piece.** Pillars carry more outbound links to their cluster. +- **The link count should be by design, not by accident.** The brief specifies the link count; the writer should hit it; QA verifies. + +### Self-cannibalization check + +- **The piece does not compete with an existing piece for the same target keyword.** Search the site for the primary keyword. If an existing piece is in the top 5 internal results, flag the new piece. + +The flag triggers a decision: consolidate, differentiate, or kill one. Detail in `pillar-content-architecture/references/internal-linking-architecture.md` for the broader internal linking discipline. + +--- + +## Schema validation + +### Schema type matches content + +- **Article schema for editorial pieces.** Default for blog posts, long-form articles, thought leadership. +- **HowTo schema for instructional pieces.** Step-by-step guides with explicit steps that the schema can structure. +- **Product schema for product pages.** Programmatic pSEO pages rendering products usually use Product schema. +- **LocalBusiness schema for location-based pages.** Programmatic pSEO for geographic categories. +- **FAQPage schema for genuine FAQ sections.** As an embedded schema within the page, not as the page's primary schema (unless the page is FAQ-shaped throughout). +- **BreadcrumbList schema for navigation context.** Most pages benefit; pillar pages especially. + +### Schema validates + +- **Schema validates against schema.org definitions.** No missing required fields. No malformed JSON-LD. No invalid field types. +- **Validation method.** Run the schema through a validator (Google's Structured Data Testing Tool, schema.org's validator, or equivalent). Failures appear as errors with field-specific messages. + +### Schema is consistent with on-page content + +- **Schema reflects what the page actually shows.** Do not claim 5-star rating in schema if there is no rating on the page. Do not claim a HowTo with 7 steps if the page only walks through 4. Mismatch between schema and content can trigger manual penalties. + +### Optional schema fields earn their keep + +- **Populated optional schema fields signal depth.** Programmatic pages with comprehensive schema (`aggregateRating`, `additionalProperty`, `areaServed`, etc.) score higher with AI engines than pages with bare-minimum schema. +- **The trade-off.** Filling optional fields requires data. If the data does not exist, do not fabricate it; either populate genuinely or leave the field absent. + +--- + +## The link audit pattern + +For each piece in QA: + +1. **Outbound links present.** Match against brief. +2. **Anchor text variation.** Same-target links use varied anchor text. +3. **Targets live.** No 404s, no deprecated pages. +4. **Link count in band.** 3 to 7 for typical, 8 to 15 for pillar. +5. **Self-cannibalization.** No competition with existing pieces. +6. **Inbound links queued for post-publish update.** The brief queued 1 to 3 existing pages that should add links to this piece after publish; the QA log queues those updates. + +The 6-step audit takes 5 minutes per piece. Worth the time; under-linked or stuffed pieces fail to compound. + +--- + +## The schema audit pattern + +For each piece in QA: + +1. **Schema type appropriate.** Article, HowTo, Product, LocalBusiness, FAQPage, or BreadcrumbList per content shape. +2. **Schema validates.** Run through a validator; resolve errors before publish. +3. **Schema matches content.** No false claims (false ratings, false step counts). +4. **Optional fields populated.** Where data exists, fields populate; the page signals depth. +5. **Multiple schema types when appropriate.** Article + FAQPage + BreadcrumbList is common for pillar pieces with FAQ sections. + +The schema audit takes 3 to 5 minutes per piece (less with automation; more on first-pass for new content types). + +--- + +## Common failures + +**Brief specified link, writer skipped it.** Halt and return; brief-adherence catches this earlier in the QA sequence. + +**Anchor text identical across links.** Auto-fix in the editor pass; vary the anchor on at least 2 of every 3 same-target links. + +**Schema fails validation.** Auto-fix; the editor or a script ships the corrected schema. + +**Schema claims rating that is not on the page.** Halt and return; this is the manual-penalty risk. + +**Internal link count below brief.** Flag and return for the writer to add the missing links per the brief's specification. + +--- + +## Methodology-level choices that stay in the public skill + +The 6-step link audit, the 5-step schema audit, the anchor variation rule, the schema-content consistency rule, the optional-field discipline. + +## Implementation choices that stay internal + +The specific schema validation tooling (Google's tool, schema.org's tool, custom CI integration). The specific link checker (Screaming Frog, custom Puppeteer script, headless browser audit). The specific CMS integration that auto-populates schema from page metadata. The specific deployment pipeline that runs schema validation on every publish. These vary by stack and team. diff --git a/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md new file mode 100644 index 0000000..cd443d8 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md @@ -0,0 +1,184 @@ +# QA at scale patterns + +Sampling strategy, automated checks, manual review at scale, threshold gating. + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. The discipline below is sampling plus automated checks plus threshold gating. It is the same shape as the QA section in `programmatic-seo` but applied to the editorial QA gate specifically. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle. The sample is stratified. + +**Stratification dimensions.** + +- **Sparse vs dense data.** Sample some records with minimum-required fields; sample some with most-fields-populated. Sparse pages fail differently from dense pages; the sample needs both. +- **Recent vs old.** Sample some pages generated in the last 30 days; sample some generated 12+ months ago. Recent pages catch template drift; old pages catch data drift. +- **Popular vs niche categories.** Sample some pages from high-traffic parent categories; sample some from low-traffic ones. The popular categories carry the program's traffic; the niche ones surface long-tail-specific failures. +- **Different cohort versions.** If the template has shipped revisions, sample some pages from each cohort. Cohort-specific failures only surface if the sample includes the cohort. + +**Sample size by set size.** + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +**Cycle frequency.** Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks at scale + +Run on every page on a cadence; surface failures as a queue. + +### Heading-structure validation + +- One H1 per page, in the right place +- H2 sequence reasonable (not orphan H3s, not H4 without H3) +- Heading text length within bounds (no 200-character H2s) + +### Schema markup validation + +- Schema type present and matches the page's content type +- Required fields populated +- JSON-LD parses without errors +- Schema does not claim things absent from the page + +### Word count + +- Pages below the floor (typically 600 words for editorial; varies for programmatic templates) get flagged +- Pages above an upper bound (typically 8,000+ words on programmatic templates) get flagged for review + +### Duplicate content + +- Hash-similarity comparison across the set +- Pages with >80% content overlap with another page in the set get flagged +- Common cause: comparison-pivot pages (X vs Y inverse) without canonicalization + +### Broken links + +- Crawl outbound and internal links +- 404s and 5xx responses get flagged +- Both internal links to deleted pages and external links to dead URLs surface + +### Image presence + +- Pages where the template expects images but the image slot is empty +- Programmatic pages with missing image fields render visibly broken + +--- + +## Manual checks on sampled pages + +For sampled pages, the human review covers what automation misses. + +### Brief or template adherence + +- For editorial pages: did the writer execute the brief? +- For programmatic pages: did the page execute the template? + +### Top-200-word answer quality + +- Read the first 200 words. Does the page answer the user's likely query? +- Is the answer self-contained (could be cited as the canonical answer to the query)? + +### Distinctive vs templated + +- Compare the sampled page to two siblings in the same template cohort. Could you tell them apart on substance, not just on identifiers? +- Templated pages that look identical signal weak data depth or weak template variable density. + +### User-intent satisfaction + +- If a real user landed on this page from the target SERP, would they stay or bounce? +- The bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +### AI hallucination spot-check + +- For pages that involved AI in drafting or generation, spot-check 3 to 5 statistics, citations, or factual claims per sampled page. +- Hallucination patterns surface in patterns; one bad page often signals a template-level or pipeline-level issue. + +### AI-tell pattern check + +- Sample a paragraph from the middle of the sampled page. +- Does it match the AI tells from `ai-content-audit-patterns.md`? +- Mid-page drift in programmatic pages signals the generation pipeline's output drifted; investigate. + +--- + +## Threshold gating + +If more than 5% of sampled pages fail the manual review, halt new generation. Fix the template OR data quality issue before resuming. + +**The 5% threshold is empirical.** Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +**What "halt" means.** + +- New page generation stops. +- The template or data fix is shipped. +- The next sample audit confirms the fix improved the failure rate before generation resumes. + +**Why halt instead of "fix as you go."** Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +**The threshold is not negotiable.** "Just ship the next batch and we will fix later" is the failure mode. The pattern produces sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another. That signals a template change or data quality drift; investigate. + +**Cohort cuts.** + +- Pages from a given month +- Pages from a given template version +- Pages from a given data-source version + +**Drift signals.** + +- **Cohort A pages rank top 10; cohort B pages rank position 30.** Template or data changed between cohorts; identify the change. +- **Cohort A pages get cited; cohort B pages do not.** Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- **Cohort A pages have stable engagement; cohort B pages have decaying engagement.** Cohort B may have a data freshness problem. + +Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically. + +--- + +## QA log + +Document each cycle's audit. The log compounds into pattern detection. + +**Log fields.** Cycle date, sample size, failure count, failure types, cohort distribution, threshold breach if any, halt action if triggered, fix shipped if applicable. + +**The patterns the log surfaces over time.** + +- Recurrent failure types (always the answer paragraph; always the schema; always the data freshness) +- Cohort-specific patterns (cohort B always fails harder than cohort A) +- Template versions that solved one problem and introduced another +- Data sources that drift faster than expected + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## When the sample reveals the program is broken + +Sometimes QC at scale reveals the underlying program is wrong, not just that individual pages need fixes. + +**Signals.** + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole there; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. + +--- + +## Methodology-level choices that stay in the public skill + +The stratified sampling strategy, the 5% threshold, the automated check categories, the manual review checklist, the cohort tracking discipline, the QA log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing and querying the QA log (database table, Notion, dbt model, BI tool). The specific automated check pipeline (CI integration, scheduled crawls, data warehouse queries). The specific sampling implementation (random ID selection script, weighted sampling logic). The specific dashboard or visualization for surfacing cohort patterns. These vary per team scale and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md b/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md new file mode 100644 index 0000000..ad175af --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md @@ -0,0 +1,153 @@ +# QA workflow templates + +Ownership, sequencing, halt vs flag vs auto-fix, escalation patterns. + +The QA workflow is the operational shape of how QA actually runs. Templates below name the patterns; teams adapt the implementation to their own tooling. + +--- + +## Ownership: single QA owner per piece + +The principle. One person is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +**Common ownership models.** + +- **Editor-owns-piece.** The editor who reviews the piece is also accountable for what shipped. The same person sees the brief, reads the draft, runs QA checks, ships. +- **Editor + dedicated QA.** Editor reviews voice and structure; dedicated QA runs fact-checks, link audits, schema validation. The editor is still the single point of accountability for ship-decision. +- **Rotating editor pool.** Larger teams have multiple editors; each piece gets one named owner from the pool. The pool is calibrated quarterly so individual editors apply consistent standards. + +**Anti-pattern.** Committee review where 4 reviewers comment, nobody decides, the writer revises against contradictory feedback. The fix: name the decision-maker; treat other input as advisory. + +--- + +## The sequencing template + +Run QA gates in this order. Each gate is cheaper than the next; running them in order saves the editor's time on pieces that should restart. + +1. **Brief-adherence.** First. Cheapest to run. Catches the largest class of failures. +2. **Fact-accuracy.** Second. Halt-condition; AI hallucinations do not progress past this gate. +3. **Structure and clarity.** Third. Identifies pieces that need structural revision before voice and SEO checks make sense. +4. **AI-content audit.** Fourth. Catches AI tells, hallucinations not caught at gate 2, voice drift. +5. **Voice consistency.** Fifth. Mid-piece sampling for long pieces. +6. **SEO and AEO compliance.** Sixth. Most failures here are auto-fixable; rarely halt-conditions. +7. **Internal linking and schema validation.** Seventh. Mostly auto-fix or flag. +8. **Final read.** The last full read before publish. Catches anything the gate-by-gate review missed. + +The early gates (brief, fact, structure) save the most time; running them first means a piece that fails brief-adherence does not consume voice/SEO review time. + +--- + +## Halt vs flag vs auto-fix taxonomy + +Each QA gate has a default action when failures appear. + +**Halt-conditions (return to writer).** + +- Brief-adherence failures. The contract was not executed. +- Fact-accuracy failures (hallucinations, unverifiable claims). Cannot ship false claims. +- Structural failures that require rewriting (buried lede, mismatched intent, missing facets). Cannot fix in editor pass. +- Voice drift that requires rewriting sections. Cannot fix inline. + +**Flag-and-revise (editor flags; writer or editor revises).** + +- Voice consistency issues that are correctable inline. +- Structural issues that need paragraph-level revision (sentence variety, transition smoothing). +- AI tells that need targeted rewriting. +- Specificity gaps where the writer needs to add the missing concrete claim. + +**Auto-fix (editor or script ships the correction without writer involvement).** + +- Slug, meta description, image alt text. +- Schema markup formatting issues. +- Anchor text variation when same-target links share identical anchors. +- Heading structure mechanical fixes (closing orphan H3s). +- Typos and minor grammar. + +The discipline. Most pieces have a mix: some auto-fix items, some flag-and-revise items, sometimes a halt-condition. The editor processes them in the right order: handle auto-fixes inline, batch flag-and-revise items into one return note, halt early if a halt-condition appears. + +--- + +## Escalation patterns + +When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +### Brief-level patterns + +- Multiple writers fail brief-adherence on the same brief field. The brief is unclear about that field; tighten the brief template. +- Multiple briefs surface the same gap (always missing the audience specification, always missing the success criteria). The brief authoring process needs feedback. + +### Writer-level patterns + +- One writer repeatedly produces pieces that fail at the same gate. The writer needs targeted feedback or different work. +- One writer's pieces consistently need substantial revision. Either the briefs the writer receives need to be tighter, or the writer-fit is wrong for the work. + +### Process-level patterns + +- AI-content audit catches similar tells across pieces. The AI workflow needs additional guardrails. +- Fact-accuracy gates catch repeated hallucinations on the same topic. The verification step for that topic needs more time. +- Schema validation fails consistently on the same content type. The CMS template for that type needs updating. + +The escalation. Pattern goes to the editorial process owner with a short summary: "Across the last 12 pieces, 5 failed at [gate] for [reason]. Recommend [action]." The owner decides whether to update the brief template, retrain a writer, change the workflow, or document the pattern as known and accepted. + +--- + +## QA review templates + +Common formats for capturing QA findings. + +### Halt-condition return note + +Short. The note specifies what failed and what needs to change. + +> "This piece needs revision before round 2. Three failures: [field 1] missing the brief specification of [X], [field 2] contains an unverified statistic on line [N], [field 3] reads as model-default voice in section 4. Revise per the brief and the voice doc." + +### Flag-and-revise inline review + +Inline comments in the editing tool. Each comment is short and actionable. + +- "[Brief required] Add internal link to [X] with anchor '[Y]' here." +- "[Voice drift] This paragraph reads generic; pull back to brand voice." +- "[Specificity] 'Many companies' is vague; add the source or remove the claim." + +### Auto-fix log entry + +The editor logs what was auto-fixed for the writer's awareness without requiring writer action. + +> "Auto-fixed during review: meta description tightened, schema markup field [X] added, anchor text varied on 2 links to [target]. No writer action required." + +### Escalation note + +Short summary to the editorial process owner. + +> "Pattern: 5 of 12 recent pieces have failed AI-content audit on em-dash count. The writer using AI assistance is shipping mid-stage drafts without final em-dash cleanup. Recommend a final-pass revision guideline added to the AI-co-author workflow doc." + +--- + +## QA cycle time + +The discipline keeps QA cycle time tractable. + +**Typical times for a 1,500-word piece.** + +- Brief-adherence: 5 minutes +- Fact-accuracy: 10 to 30 minutes (depending on claim density) +- Structure and clarity: 10 minutes +- AI-content audit: 5 minutes +- Voice consistency: 5 minutes +- SEO and AEO compliance: 10 minutes +- Internal linking and schema: 5 minutes +- Final read: 5 minutes + +**Total.** 55 to 75 minutes for a healthy piece. Pieces that halt at gate 1 or gate 2 take less editor time because the early gates short-circuit the rest. + +**The "QA takes longer than the writing" failure.** Usually means the wrong sequencing (running expensive checks before cheap ones). Fix the sequence; the cycle time drops. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner principle, the gate sequencing, the halt/flag/auto-fix taxonomy, the escalation patterns, the review templates, the cycle-time targets. + +## Implementation choices that stay internal + +The specific editing tool the team uses (Google Docs, Notion, Markdown PRs, headless CMS draft mode). The specific commenting and review workflow within that tool. The specific tracking system for QA logs and escalations (Notion, Linear, Jira, custom database). The specific reporting cadence and format for editorial process owners. These vary per team and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md b/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md new file mode 100644 index 0000000..e3e31e6 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md @@ -0,0 +1,113 @@ +# SEO and AEO compliance checklist + +SEO and AEO checks combined into one workflow. The two-engine optimization principle holds: pieces that earn search rankings are largely the same pieces that earn AI citations. + +This checklist runs late in the QA sequence (after brief-adherence, fact-accuracy, structure, AI-content audit, voice). SEO and AEO failures are mostly auto-fixable; halting on them is rarely the right call. + +--- + +## SEO checks + +### Title and headings + +- **Target keyword in title.** The brief's primary keyword appears in the page title; the title is 50 to 65 characters; the title reads naturally rather than keyword-stuffed. +- **H1 present and matches title intent.** Some CMSs use the title as H1; some have separate H1. Either way, one H1 per page that establishes the topic. +- **Heading hierarchy clean.** No orphan H3s (every H3 sits under an H2). No H4 without H3. The hierarchy is tree-shaped, not arbitrary. +- **H2 keyword variation.** Supporting cluster keywords appear naturally across H2s without forcing. + +### Meta and URL + +- **Meta description compelling and keyword-aware.** 140 to 160 characters; includes the primary keyword without stuffing; reads as a benefit-statement that earns the click from SERP. +- **URL slug short and descriptive.** Hyphens, lowercase, keyword-aware, date-free, under 60 characters. Generic example: `/feature-flag-rollout/kill-switches/`. +- **Canonical URL set.** The piece has a canonical URL pointing to itself (or to the canonical version if this piece is a duplicate-by-design like an X vs Y comparison page). + +### On-page + +- **Image alt text descriptive.** Every image has alt text that describes the image's content, not "image of [thing]" or generic placeholders. +- **External links open appropriately.** Most external links open in a new tab; rel attributes (`noopener`, `noreferrer`, `sponsored`, `nofollow`) match the link's purpose. +- **Internal link count appropriate.** 3 to 7 internal links for a 1,500-word piece; 8 to 15 for a pillar piece. Below the floor signals under-linked; well above signals link-stuffing. + +--- + +## AEO checks + +The AEO surface complements the SEO surface. AI engines weight different patterns; the checks below catch what AI engines specifically reward. + +### Answer paragraphs at H2 level + +- **40 to 60 word answer paragraph immediately following each H2 question.** AI engines extract these as citation candidates. The paragraph is self-contained: read alone, it answers the H2's specific question completely. +- **Snippet-bait pattern repeats throughout.** Not just the top of the piece. Every H2 gets one. + +### TL;DR section + +- **Pillar pieces include a TL;DR section near the top.** 150 to 250 words. Self-contained. The most-cited section by AI engines for pillar-shaped content. +- **TL;DR placement.** After the hero, before the table of contents. The reader sees TL;DR within the first scroll. + +### FAQ schema + +- **FAQ section with FAQPage schema.** Pieces that contain FAQ-shaped content (genuine reader questions with answers) mark the FAQ section with FAQPage structured data. Perplexity especially cites FAQPage content heavily. +- **Genuine FAQs only.** Do not mark fake FAQs (questions nobody actually asks) with FAQPage schema. Search engines and AI engines detect fabricated FAQs and deprioritize. + +### Statistics with sources + +- **Specific statistics with cited sources.** AI engines weight statistics with sources higher than vague qualifiers. "23% of B2B buyers cite [specific source]" beats "many B2B buyers." +- **The numbers are real.** Verify in the fact-accuracy gate; do not let hallucinated statistics ship just because they would help SEO/AEO. + +### Named entities + +- **Entity coverage matches brief.** The required entities from the brief are present; the standard entities are present where relevant; the gap entities are present where the brief committed to them. +- **Entities mentioned with weight.** Pass the brief's depth-of-coverage requirement: not just "CUPED is mentioned in passing" but "CUPED is developed in the methodology H2 with the formula and an example." + +### Distinctive POV + +- **The piece takes a position.** AI engines preferentially cite content with attributable claims. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. +- **The POV is consistent with brand stance.** Voice doc specified the brand stance; the piece's POV aligns. + +--- + +## Auto-fix vs flag vs halt + +Most SEO/AEO failures are auto-fixable: the editor or a script can fix slug, meta description, image alt text, schema markup without writer involvement. + +Some require flag-and-revise: heading structure, internal link count, answer paragraph patterns. The editor flags; the writer revises. + +Halt-conditions are rare for SEO/AEO. The typical case where halt makes sense: the piece is structurally wrong for the target SERP (brief specified listicle; piece is long-form prose). That is a brief-adherence failure that surfaced late; route back to the brief-adherence gate. + +--- + +## The combined SEO/AEO audit + +Run as one pass. The checks overlap (both reward heading structure, both reward depth, both reward freshness). Treating SEO and AEO as separate workflows doubles the audit time without doubling the catch rate. + +The discipline. One audit, one checklist, two-engine optimization mindset. The piece serves both surfaces or it serves neither well. + +--- + +## Pillar-specific extensions + +Pillar pieces have additional SEO/AEO requirements. + +- **TL;DR section** (covered above) +- **Comprehensive entity coverage.** Pillar pieces should mention 15 to 25 entities across the topic; cluster pieces have lower bars. +- **Internal links to cluster pieces.** Pillar links out to each cluster piece via contextual anchors, not via a footer dump. +- **Schema includes BreadcrumbList.** Tells crawlers and AI engines that this is the hub of a topical cluster. + +--- + +## Programmatic-page-specific extensions + +For programmatic SEO pages, SEO/AEO checks adapt. + +- **Top-200-word answer.** First 200 words answer the user's specific query directly. AI engines cite programmatic data pages for factual queries primarily. +- **Schema population at scale.** Every page has Article, Product, LocalBusiness, or other type-appropriate schema; schema fields populate from the same data that renders the visible page. +- **Sampling discipline.** Full-audit SEO/AEO checks are infeasible at scale; sample 50 to 200 pages per cycle (see `qa-at-scale-patterns.md`). + +--- + +## Methodology-level choices that stay in the public skill + +The combined SEO/AEO check sequence, the auto-fix/flag/halt taxonomy, the pillar-specific extensions, the programmatic-specific extensions. + +## Implementation choices that stay internal + +The specific tooling for automated SEO/AEO checks (Lighthouse audits, schema validators, headless-CMS-specific plugins). The specific schema-validation library or service. The specific staging environment where pre-publish checks run. The specific deployment pipeline that gates publish on SEO/AEO compliance. These vary by stack and team. diff --git a/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md b/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md new file mode 100644 index 0000000..aebad76 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md @@ -0,0 +1,128 @@ +# Structure and clarity review + +Lede patterns, sectioning principles, endings, structural anti-patterns. + +Structure determines whether the piece works as a piece. The discipline below is about making structure visible enough to QA repeatably without becoming process theater. + +--- + +## The lede + +The first 200 words. Two valid patterns depending on intent. + +**For SEO/AEO pieces.** The lede answers the user's likely query directly. The reader landed from a SERP looking for a specific answer; the lede provides it within the first 200 words. The rest of the piece develops the answer with depth. + +**For thought leadership.** The lede establishes the thesis. The reader is investing attention; the lede tells them the argument the piece will defend. The rest of the piece builds the case. + +**Lede failure patterns.** + +- **Welcome-to-our-blog throat-clearing.** The lede announces what the piece is about to do instead of doing it. +- **Buried lede.** The actual answer or thesis appears in section 4. The reader bounced at section 2. +- **Vague opening.** Generic descriptive paragraph that could open any article on the topic. +- **History dump.** "Since the dawn of [topic]..." Cuts the throat-clearing; ledes do not need a history. + +--- + +## Sectioning + +**The check.** H2s map to user mental model, not writer enthusiasm. + +**User mental model.** What questions does the reader bring? What questions follow naturally from the first answer? What does the reader want to know next? The H2 sequence answers these in order. + +**Writer enthusiasm.** What does the writer find interesting? Where does the writer want to dig deep? Writer enthusiasm produces sections that are well-written but mistargeted; the reader did not come for that section and skips it. + +**The audit.** Read the H2 list as a sequence of questions or topics. Does the sequence match what the reader's mind would ask in order? If H2 #4 has the answer the reader landed for, the structure has buried lede; promote H2 #4 to H2 #1. + +--- + +## Section length + +**The check.** Even-ish across H2s. + +**Why even-ish matters.** One massive section followed by four 80-word sections signals broken structure. The massive section is doing real work; the 80-word sections are placeholders or filler. + +**The fix.** + +- If the 80-word sections are placeholders: cut them or expand them to the section's natural depth. +- If the massive section is two facets bundled: split it into two H2s. +- If the structure is genuinely uneven (one section needs to be twice as long for substantive reasons): document the rationale; ship with the imbalance acknowledged rather than hidden. + +--- + +## Reading flow + +**The check.** Paragraphs connect; sentences vary in length. + +**Paragraph flow.** Each paragraph extends the previous one or pivots intentionally. Disconnected paragraphs read as bullet-points-pretending-to-be-prose. The fix: explicit connective tissue between paragraphs (the connection is implicit in the sequence, or the writer adds a one-sentence transition that does the work). + +**Sentence variety.** Reading aloud is the audit. Do all the sentences run the same length? That is a tell of AI-assisted writing or rushed drafting. Vary sentence length across the paragraph; mix short declarative sentences with longer ones that build through clauses. + +--- + +## Specificity vs abstraction + +**The check.** Claims are concrete, not vague. + +**Concrete.** Named tools, named methods, named statistics with sources, named experts, named scenarios. Concrete claims earn citations from AI engines and trust from readers. + +**Abstract.** "Many companies struggle with X." "Studies show Y." "Industry leaders agree Z." Vague claims read as content marketing filler; AI engines and readers both deprioritize. + +**The fix.** Replace each abstract claim with a specific one. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research the writer did not do, halt and request the research before shipping. + +--- + +## Endings + +**The check.** Piece concludes with something specific. + +**Specific endings.** + +- An action the reader can take now +- A specific question that frames the next step +- A concrete idea that lands as the takeaway +- A direct call to action with a specific destination + +**Filler endings to cut.** + +- Wrap-up paragraphs that summarize what the piece just said +- Wrap-up frames that announce the ending instead of arriving at it (the conclusion should land as a conclusion, not declare itself) +- Vague "join us as we explore" closings +- Marketing-tone CTAs that do not match the piece's voice + +The ending is the last thing the reader reads; it is the moment of conversion or memory. Filler endings waste the moment. + +--- + +## Structural anti-patterns + +The patterns that surface in QA, with the fix for each. + +**Bullet-list overuse.** When prose would serve, the writer used bullets. Bullets fragment the reading flow and signal AI-assisted drafting. Convert bullets to prose where prose makes the connection between items clearer. + +**Subheading-fest.** Every paragraph has its own H3 subheading. Reads as outline-converted-to-content rather than written content. Cut subheadings to the structural ones; let prose carry between subheadings. + +**Repetitive paragraph structure.** Every paragraph is 2 or 3 sentences of similar length. Vary the structure: some paragraphs are one long sentence; some are 4 short sentences; some are a sentence and a fragment. + +**Forced bilateral framing.** "On one hand X, on the other hand Y" pattern repeated throughout. AI-tell. Pick a position; defend it; let the contrary position get one sentence rather than equal weight when the position is genuinely strong. + +**Throat-clearing transitions.** "That said," "With that in mind," "Moving on," "Now let us look at..." All filler. Cut them; the section heading does the transition work. + +--- + +## The read-aloud audit + +The fastest structure check. Read the piece aloud (or silently with attention to rhythm). + +**Signals.** Where does the rhythm break? Where do you stumble? Where does the reading energy drop? Each break is a structural signal. Sometimes the fix is sentence-level; sometimes it is structural. + +**The discipline.** The read-aloud audit takes 10 minutes for a 1,500-word piece. It catches problems that line-by-line review misses. Build it into the QA workflow. + +--- + +## Methodology-level choices that stay in the public skill + +The lede patterns, the sectioning principles, the section-length discipline, the reading-flow audit, the specificity rule, the endings discipline, the structural anti-patterns, the read-aloud audit. + +## Implementation choices that stay internal + +The specific format the team uses for structural feedback (inline comments versus written summary versus structural diff). The specific tooling for documenting structural decisions on a piece (CMS metadata, brief addendum, separate review doc). The specific surface conventions per content type (the team's own blog vs help doc vs landing page structural patterns). These vary by team and stack. diff --git a/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md new file mode 100644 index 0000000..3a0ba06 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md @@ -0,0 +1,108 @@ +# Voice consistency patterns + +Vocabulary, rhythm, stance, register. Mid-piece sampling discipline for long pieces. The voice-drift failure mode in AI-co-authored content. + +Voice is the most subjective QA dimension and often the easiest one to skip. The discipline below makes voice-consistency checking concrete enough to run repeatably. + +--- + +## Vocabulary + +**The check.** Brand-specific vocabulary used correctly; off-brand vocabulary absent. + +**Brand vocabulary.** Each brand has a set of terms it uses (or refuses) consistently. Apple says "Mac," not "PC." Stripe says "developers," not "engineers." A B2B SaaS company might say "customers," not "users." A consumer brand might say "members," not "subscribers." + +**The audit.** Pull the brand voice doc's vocabulary section. Check the piece for each preferred term and each forbidden term. Failures: off-brand terms slipped in (the writer or AI assistant defaulted to industry-standard vocabulary instead of brand-specific). + +**Forbidden terms list.** Every brand has a list. Common patterns: corporate-speak adjectives, throat-clearing phrases, generic descriptors that flatten distinctive voice. The list is short (10 to 30 terms typically); reviewers should know it cold. + +--- + +## Sentence rhythm + +**The check.** Sentence rhythm matches brand voice. + +**Three common rhythms.** + +- **Short and punchy.** Short sentences. Frequent paragraph breaks. Dramatic emphasis through structural choices. +- **Measured and layered.** Longer sentences with subordinate clauses. Paragraphs build through accumulation. Conversational but considered. +- **Colloquial.** Conversational rhythm with mid-sentence asides, contractions, and direct reader address. Reads like a smart person talking. + +**The audit.** Read 3 paragraphs aloud. Does the rhythm match the brand's voice doc? Common drift: AI-assisted pieces regress to a uniform medium-length sentence rhythm regardless of the brand's specified rhythm. + +--- + +## Stance + +**The check.** The piece takes positions consistent with brand POV. + +**Brand stance varies.** Some brands are diplomatic and surface multiple sides without endorsing one. Others are opinionated and take clear positions. Others are coach-style and challenge the reader directly. + +**The audit.** Pick 3 to 5 places in the piece where the writer made a stance choice (a recommendation, a warning, an evaluation). Does each match the brand's stance pattern? + +**Voice drift signal.** AI-assisted pieces regress toward "diplomatic" stance even when the brand stance is opinionated. "There are good arguments on all sides" is the AI default; opinionated brands need to push the AI back toward conviction explicitly. + +--- + +## Register + +**The check.** Formal versus casual matches the surface. + +**Surface determines register.** A whitepaper takes one register; a blog post takes another; a help doc takes a third. The brand voice doc usually specifies registers per surface type. + +**The audit.** Identify the surface this piece will publish on (blog, knowledge base, whitepaper, marketing page, product help). Check the piece's register against the surface-appropriate register. + +**Common drift.** Blog pieces drift formal (they read like watered-down whitepapers). Whitepapers drift casual (they read like long blog posts). Help docs drift either direction. The brand voice doc establishes register expectations; the QA check enforces them. + +--- + +## Mid-piece sampling + +**The discipline.** Long pieces drift; sample throughout, not just at start and end. + +**Why drift happens.** Writers (human or AI) start in brand voice because that is what the brief, the opening prompt, and the recent context established. By section 4 of a 3,000-word piece, the writer's working memory has shifted to the topic at hand and the voice has drifted toward a generic baseline. AI-assisted pieces drift faster because the model's defaults reassert without continuous reinforcement. + +**The sampling pattern.** + +- **Start sample.** First 200 words. Voice should be strongest here. +- **Middle samples.** Two paragraphs from the middle 60% of the piece. Voice should hold. +- **End sample.** Last 200 words. Voice should match the start. + +If the start and end samples show brand voice and the middle samples show generic voice, the piece has voice drift. Send it back with the drifted sections highlighted. + +--- + +## The voice-drift signal in AI-co-authored content + +Voice drift is the dominant voice failure in 2025-2026 content. AI assistants produce drafts that pass the start-and-end check (because the writer set up the opening prompt with brand voice cues) but fail the mid-piece check (because the model defaults reasserted in the middle). + +**The detection pattern.** + +- Mid-piece paragraphs use vocabulary not in the brand voice doc +- Mid-piece sentence rhythm regresses to medium-length uniformity +- Mid-piece stance becomes diplomatic where brand stance was opinionated +- Mid-piece register drifts toward "professional neutral" regardless of the surface's intended register + +**The fix.** When mid-piece drift is detected, the revision pass needs to explicitly pull the voice back. The editor's note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes]." + +--- + +## Voice calibration sessions + +Different editors apply voice judgment differently. Quarterly calibration sessions reduce the drift between editors. + +**The session.** Three editors review the same piece independently. Each writes a one-paragraph voice assessment. The team reads the three assessments together; differences in interpretation surface; the team reconciles to a shared standard. + +**The output.** A short addendum to the brand voice doc capturing the calibration consensus on whatever was contested. Over time the addenda accumulate into a sharper, more specific voice doc. + +**Why calibration matters.** Without it, voice judgment varies by editor; writers receive inconsistent feedback; voice drift compounds across the program. The calibration session is preventative; once the team is calibrated, individual reviews stay consistent. + +--- + +## Methodology-level choices that stay in the public skill + +The 4-dimension voice check (vocabulary, rhythm, stance, register), the mid-piece sampling discipline, the AI voice-drift detection pattern, the calibration session methodology. + +## Implementation choices that stay internal + +The specific brand voice doc format (Notion page, Markdown file, internal wiki page). The specific vocabulary list and the specific forbidden-term list (these are brand-specific and live in the brand's own documentation). The specific calibration session cadence and team composition. The specific tooling for archiving voice assessments. These vary per brand and team. diff --git a/dist/pi/.agents/skills/email-deliverability/SKILL.md b/dist/pi/.agents/skills/email-deliverability/SKILL.md new file mode 100644 index 0000000..aca68b1 --- /dev/null +++ b/dist/pi/.agents/skills/email-deliverability/SKILL.md @@ -0,0 +1,283 @@ +--- +name: email-deliverability +description: "Make sure email actually reaches inboxes. Use this skill when setting up email authentication (SPF, DKIM, DMARC), diagnosing emails landing in spam, planning a domain reputation strategy, monitoring sender reputation, or hardening against email spoofing. Triggers on email deliverability, SPF, DKIM, DMARC, spam folder, sender reputation, mailbox provider, soft bounces, bounce rate, BIMI, MTA-STS, deliverability audit. Also triggers when a marketing or transactional email isn't reaching users." +category: operations +catalog_summary: "DMARC, SPF, DKIM, sender reputation, deliverability monitoring" +display_order: 8 +--- + +# Email Deliverability + +Get email into inboxes, not spam folders. Set up authentication. Monitor reputation. Diagnose problems before they hurt the business. + +--- + +## When to use + +- Setting up email for a new domain +- A meaningful percentage of email is going to spam +- Customers report they're not receiving emails +- Setting up DMARC, SPF, or DKIM +- Hardening against domain spoofing +- Migrating email service providers +- Sender reputation has dropped +- Pre-launch audit before sending volume increases + +## When NOT to use + +- Writing the email content itself (use `email-sequences`) +- Designing the email program strategy (use `email-sequences`) +- DNS records in general (use `domain-strategy`) +- Outbound spam coming FROM your account (different problem; investigate compromised credentials) + +--- + +## Required inputs + +- The sending domain(s) +- The email service provider (ESP, transactional service, mail server) +- Current DNS records (or access to them) +- Email volume (transactional vs marketing, daily volume) +- Current deliverability state (if known: bounce rate, spam complaints) + +--- + +## The framework: 3 pillars + +Email deliverability rests on three pillars. Weakness in any one limits the others. + +### Pillar 1: Authentication + +Mailbox providers verify email is actually from who it claims to be from. Three records. + +**SPF (Sender Policy Framework)** + +Lists which servers are authorized to send mail for the domain. Published as a TXT record at the apex. + +``` +v=spf1 include:_spf.mailprovider.com -all +``` + +- `include:` adds another sender's authorized list +- `-all` (hard fail): mail from unlisted senders fails authentication +- `~all` (soft fail): unlisted senders are suspicious but pass; useful during rollout +- `+all`: never use; allows anyone to send + +Only one SPF record per domain. Multiple SPF records break SPF entirely. Combine senders into a single record. + +SPF has a 10-DNS-lookup limit. Each `include:` may use multiple lookups. Hit the limit and SPF stops working. Watch this carefully. + +**DKIM (DomainKeys Identified Mail)** + +A cryptographic signature on each outgoing email. The mail server signs with a private key; the public key is published in DNS. + +``` +selector1._domainkey.example.com TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +Selectors differ by ESP. Some use `default._domainkey`, some use unique selectors per service. Most ESPs walk you through publishing the records. + +DKIM proves the message wasn't modified in transit and that the sender controls the domain. + +**DMARC (Domain-based Message Authentication, Reporting, and Conformance)** + +The policy layer. Tells receivers what to do when SPF or DKIM fails, and where to send reports. + +``` +_dmarc.example.com TXT "v=DMARC1; p=reject; rua=mailto:dmarc-aggregate@example.com; ruf=mailto:dmarc-forensic@example.com; pct=100; adkim=s; aspf=s" +``` + +Components: +- `p=`: policy. `none`, `quarantine`, or `reject`. +- `rua=`: aggregate reports (daily, summary). Always set this. +- `ruf=`: forensic reports (per-message). Optional, can be high volume. +- `pct=`: percentage of failing mail subject to the policy. Useful for gradual rollout. +- `adkim=`, `aspf=`: alignment mode. `s` (strict), `r` (relaxed). Strict means From: domain must match exactly. + +DMARC is the most important record. It's what makes spoofing your domain hard. + +### Pillar 2: Reputation + +Mailbox providers (Gmail, Outlook, Yahoo) score every sender. Reputation drives delivery. + +Reputation factors: +- **Authentication pass rates** (SPF, DKIM, DMARC) +- **Engagement signals** (opens, replies, marking as not-spam) +- **Negative signals** (spam complaints, deletions without opens, blocking) +- **List hygiene** (low bounce rates, no spam traps) +- **Volume consistency** (sudden spikes look like spam) +- **Content patterns** (link reputation, attachment patterns) +- **IP and domain history** + +Reputation is per (sending domain × mailbox provider). Gmail's view of you is independent of Outlook's. + +### Pillar 3: List quality and engagement + +Authentication and reputation rest on list quality. Bad list = bad reputation eventually. + +- Only send to people who explicitly opted in +- Confirmed (double) opt-in for marketing wherever feasible +- Honor unsubscribes immediately and reliably +- Remove hard bounces immediately +- Sunset disengaged contacts (no opens in 6 months: reduce frequency or remove) +- Avoid third-party lists, scraped emails, or "purchased opt-ins" + +The single biggest deliverability lever for most senders is list hygiene. + +--- + +## Workflow + +### Step 1: Audit current state + +Check the current DNS records: + +```bash +dig +short txt example.com +dig +short txt selector1._domainkey.example.com +dig +short txt _dmarc.example.com +``` + +Also check: +- Current bounce rate (target: under 2%) +- Current spam complaint rate (target: under 0.1%) +- Current open rate (varies by industry; falling trend is a warning) +- Current sending volume + +Tools: mxtoolbox.com, dmarcian.com, mail-tester.com (for individual messages). + +### Step 2: Fix authentication + +If any of SPF, DKIM, DMARC is missing or misconfigured, fix first. + +**SPF fix order:** +1. Identify all legitimate senders (transactional ESP, marketing ESP, support tools, etc.) +2. Get the `include:` value or IP for each +3. Combine into a single SPF record +4. Verify lookup count is under 10 +5. Use `-all` for hard fail (or `~all` if rolling out gradually) + +**DKIM fix order:** +1. Generate a new selector per sending service +2. Publish the public key in DNS +3. Configure the ESP to sign with the private key +4. Verify with a test send (check headers for `dkim=pass`) + +**DMARC fix order:** +1. Publish DMARC with `p=none` initially (monitoring mode) +2. Set up an aggregate report endpoint (use a DMARC analytics service or your own) +3. Watch reports for at least 2-4 weeks +4. Identify any legitimate senders failing alignment; fix them +5. Move to `p=quarantine` with `pct=10`, gradually increase +6. Move to `p=reject` once confidence is high + +The full progression typically takes 2-3 months. Rushing causes legitimate mail to bounce. + +### Step 3: Set up monitoring + +Ongoing visibility: + +- **DMARC aggregate reports**: parsed daily. Watch for new sources, alignment failures, volume changes. +- **Bounce rate**: per ESP dashboard. Target under 2% for transactional, under 5% for marketing. +- **Spam complaint rate**: target under 0.1%. +- **Reputation tools**: Google Postmaster Tools (free), Microsoft SNDS, Talos, Sender Score. +- **Blacklist monitoring**: most ESPs include this; otherwise mxtoolbox.com or hetrixtools.com. + +### Step 4: Address list hygiene + +- Remove hard bounces from your sending lists immediately (most ESPs do this; verify) +- Set up suppression lists (unsubscribes, manual blocks, deliverability sinkholes) +- Sunset disengaged contacts (re-engagement campaigns or just remove) +- Review opt-in flows: do people know what they're signing up for? + +### Step 5: Content and pattern audit + +If reputation is good and authentication passes, check content: + +- HTML-only emails (no plain-text alternative) raise flags +- Heavy image-to-text ratios raise flags +- Suspicious link patterns (bare IPs, URL shorteners, hijacked domains) +- Specific spam-trigger words in subject lines (less important than it used to be, still real) +- Lots of mismatched domains in URLs +- Generic from-name like "info@" rather than a real-sounding sender + +### Step 6: Plan for growth + +Email volume affects reputation. Sudden spikes look like spam. + +- Warm up new sending IPs gradually (start at 50/day, 2x daily) +- Warm up new domains gradually (similar pattern) +- Spread sends throughout the day +- Don't switch ESPs the week before a big launch + +### Step 7: Set up BIMI (optional but valuable) + +BIMI (Brand Indicators for Message Identification) shows your logo next to authenticated emails in supporting clients (Gmail, Apple Mail, Yahoo, others). + +Requires: +- DMARC at `p=quarantine` or `p=reject` (so this comes after the DMARC progression) +- A trademarked logo as an SVG (specific format requirements) +- A Verified Mark Certificate (VMC) from a CA, for Gmail and others +- A `_bimi` DNS record pointing to the SVG and VMC + +BIMI improves trust signals and engagement. Worth doing once DMARC enforcement is in place. + +### Step 8: Document and revisit + +Document the email architecture: +- Sending domains and subdomains +- Each ESP and what it sends +- DNS records for each +- Monitoring setup +- Escalation if deliverability degrades + +Revisit quarterly or when a new ESP is added. + +--- + +## Failure patterns + +**Multiple SPF records.** Two or more SPF records on the same domain breaks SPF. Combine into one. + +**SPF DNS lookup limit exceeded.** Too many `include:` directives or chained includes. Flatten or simplify. + +**DMARC at `p=none` forever.** Monitoring without enforcement. Spoofing remains easy. Move to enforcement. + +**DMARC at `p=reject` too quickly.** Legitimate mail bounces because alignment wasn't verified. Use the gradual rollout. + +**Sending from a different domain than the From: address.** Causes alignment failures. Fix the From: domain or ensure proper alignment. + +**Using a shared ESP IP without ESP-specific configuration.** Some ESPs don't sign with your DKIM by default; the signature is the ESP's, not yours. Configure custom DKIM. + +**Sending from a domain that also sends marketing.** A spam complaint on a marketing email hurts transactional deliverability. Use a subdomain for transactional (`transactional.example.com`) or marketing (`mail.example.com`). + +**No bounce monitoring.** Hard bounces accumulate, reputation tanks, deliverability cliff-falls. Monitor. + +**Bought lists or scraped contacts.** Spam traps in those lists destroy reputation. Don't. + +**No double opt-in for marketing.** Single opt-in lets bots and typos onto the list. Bots generate spam complaints, destroy reputation. + +**Ignoring DMARC reports.** Reports show problems early. Set up a parser. Look weekly. + +**Treating "marked as not-spam" as the goal.** The goal is to never land in spam in the first place. Once reputation is bad, recovery takes months. + +--- + +## Output format + +A deliverability audit document includes: + +- **Domain inventory:** every sending domain +- **Authentication status:** SPF, DKIM, DMARC per domain +- **Sender inventory:** every ESP or service that sends mail, what's configured +- **Reputation status:** per major mailbox provider where measurable +- **List hygiene:** bounce rate, complaint rate, opt-in process +- **Findings:** prioritized issues +- **Roadmap:** SPF/DKIM/DMARC fixes, BIMI plan, monitoring plan +- **Monitoring setup:** what's watched, where alerts go + +--- + +## Reference files + +- [`references/dmarc-rollout-playbook.md`](references/dmarc-rollout-playbook.md): Step-by-step for moving from no DMARC to `p=reject`, with timing, monitoring, and how to handle problems found along the way. diff --git a/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md b/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md new file mode 100644 index 0000000..bc3d319 --- /dev/null +++ b/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md @@ -0,0 +1,294 @@ +# DMARC Rollout Playbook + +A staged, low-risk path from no DMARC to full `p=reject` enforcement. Typical duration: 2-3 months. Rushing breaks things. + +--- + +## Why DMARC matters + +Without DMARC at enforcement, anyone can send email claiming to be from your domain. Phishing campaigns can spoof your brand to your customers, your investors, your own employees. + +DMARC at `p=reject` means mailbox providers will reject mail that fails authentication. The spoofing attacks fail. + +The goal of this playbook: get to `p=reject` without losing legitimate mail. + +--- + +## Prerequisites + +Before starting: + +- [ ] SPF is published, single record, under 10 lookups +- [ ] DKIM is published, every legitimate sender signs with your domain's key +- [ ] You have a DMARC report destination (a parsing service or your own endpoint) +- [ ] You have access to make DNS changes +- [ ] You know who is responsible for fixing email-related issues + +If any of these are missing, fix them first. DMARC enforcement on top of broken SPF or DKIM means losing legitimate mail. + +--- + +## Stage 1: Monitor (Week 1-2) + +### Goal +Discover every legitimate sender of mail from your domain. Many will be unexpected. + +### Action + +Publish DMARC at `p=none`: + +``` +v=DMARC1; p=none; rua=mailto:dmarc-aggregate@example.com; pct=100; adkim=r; aspf=r +``` + +Notes: +- `p=none`: no enforcement; mailbox providers report but take no action +- `rua=`: where aggregate reports go. Use a DMARC analytics service or your own endpoint +- `adkim=r`, `aspf=r`: relaxed alignment (less strict; eases initial rollout) + +### What to watch + +Aggregate reports start arriving from major mailbox providers within 24-48 hours. Reports are XML, daily, summarized. + +Look for: +- Every IP and sender sending mail "From: yourdomain" +- Pass/fail rates for SPF and DKIM +- Volume per sender +- Unexpected senders (often: a marketing tool, a customer support tool, a forgotten old service) + +### Common discoveries + +- Marketing ESP signing with their domain, not yours +- Internal tools sending email through unauthorized servers +- Help desk forwarding mail in a way that breaks alignment +- A SaaS notification service no one remembered +- Compromised accounts (rare but real) +- Spoofers trying to phish + +### Exit criteria + +- All legitimate senders identified +- All legitimate senders pass SPF or DKIM (ideally both) +- The volume of failing legitimate mail is well understood + +--- + +## Stage 2: Quarantine 10% (Week 3-4) + +### Goal +Begin enforcement on a small percentage. Watch for legitimate mail being affected. + +### Action + +Update DMARC to: + +``` +v=DMARC1; p=quarantine; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +Now 10% of failing mail goes to spam at supporting providers. 90% still passes through. + +### What to watch + +- Aggregate reports continuing to flow +- Customer reports of legitimate mail in spam +- Internal complaints (your own team is often the canary) + +### What to do if problems + +If a known-legitimate sender starts having mail quarantined: + +1. Identify the sender and the failure (SPF? DKIM? Alignment?) +2. Fix the sender (add to SPF, configure DKIM, fix alignment) +3. Verify the fix in subsequent reports +4. Continue + +If an unknown legitimate sender starts having mail quarantined: + +1. Investigate. Is this real legitimate use? (Internal tool? New SaaS?) +2. If yes, fix the authentication for it +3. If no, this is the spoofing DMARC is meant to stop + +### Exit criteria + +- Reports show no legitimate mail being quarantined +- Sustained for at least one week with no surprises + +--- + +## Stage 3: Quarantine 100% (Week 5-6) + +### Goal +Enforce quarantine for all failing mail. Build confidence before reject. + +### Action + +``` +v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 2 but expect higher volume of spam-foldered mail. Most should be illegitimate. + +### Exit criteria + +- No legitimate mail quarantined for at least one week +- Spoofing volume in reports is clearly visible (this is what DMARC is catching) + +--- + +## Stage 4: Reject 10% (Week 7-8) + +### Goal +Start rejecting failing mail. Fail-mode is harder than quarantine; legitimate mail that fails is bounced, not delivered to spam. + +### Action + +``` +v=DMARC1; p=reject; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +10% of failing mail is rejected. The other 90% goes to quarantine (the previous policy applies). + +### What to watch + +- Bounce rates from your sending tools (transactional and marketing) +- Customer reports of "I never got the email" +- Reports of legitimate mail being rejected + +If bounces spike, something legitimate is failing. Investigate immediately and consider rolling back. + +### Exit criteria + +- No spike in bounces or "didn't receive email" reports +- Sustained for at least one week + +--- + +## Stage 5: Reject 50% (Week 9-10) + +### Action + +``` +v=DMARC1; p=reject; pct=50; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 4. Legitimate failures will be more visible at higher percentage. + +### Exit criteria + +Same as Stage 4. No spike in legitimate mail rejection. + +--- + +## Stage 6: Reject 100% (Week 11+) + +### Goal +Full enforcement. Spoofing is now blocked. + +### Action + +``` +v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Continue monitoring reports. New senders, configuration drift, and changes in the email infrastructure can introduce new failures over time. + +### Maintenance + +- Review reports at least weekly +- Audit sender list quarterly +- Re-verify SPF and DKIM after any infrastructure change + +--- + +## Optional: Strict alignment + +After `p=reject` is stable, consider tightening alignment: + +``` +v=DMARC1; p=reject; pct=100; rua=...; adkim=s; aspf=s +``` + +Strict alignment requires the From: domain to match exactly (not just a parent domain). This catches subdomain spoofing too. + +Verify in monitoring mode (back to `p=none` with `adkim=s; aspf=s`) before enforcing. + +--- + +## Subdomain policy + +DMARC includes `sp=` for subdomain policy. Without it, subdomains inherit the main policy. + +For high-security applications: + +``` +v=DMARC1; p=reject; sp=reject; ... +``` + +This rejects spoofs on subdomains too. Important for parked or unused subdomains; an attacker can pick any subdomain by default. + +--- + +## Edge cases + +### Forwarders and mailing lists + +When mail is forwarded (e.g., user@oldcompany.com forwards to user@newcompany.com), SPF often fails (the forwarder is now the sender from SPF's view). + +DKIM survives forwarding if the message body isn't modified. Mailing lists that modify headers or add footers can break DKIM. + +Solutions: +- ARC (Authenticated Received Chain): restores authentication across forwards. Major providers support it. +- DKIM only (don't rely on SPF for DMARC alignment): if DKIM passes, DMARC passes regardless of SPF +- Mailing list software that's DMARC-aware + +### Bulk transactional providers + +Some providers (notification services, password reset emails) have hundreds of customers sharing IP space. Authentication usually requires custom domain setup; the default shared sending often fails alignment. + +Solution: configure the provider to use your domain for DKIM and From: address. Most providers offer "custom domain" or "sender authentication" features. + +### Email-on-acid testing services + +If you use email testing services that "send on your behalf" but don't authenticate, those will fail. Either configure them or accept the failure (they're not user-facing). + +--- + +## What can go wrong + +**Legitimate mail starts bouncing.** Roll back to the previous stage immediately. Investigate the failure. Fix. Try again. + +**Spoofing complaints rise.** Counterintuitively, after DMARC enforcement, you may see a temporary rise in complaints because spoofing that was previously delivered (silently spoofed your customers) now bounces (and the spoofer gets a bounce notification, then sometimes complains to the wrong place). This usually settles within a week. + +**Volume of reports overwhelms.** Reports are voluminous from large mailbox providers. Use a DMARC analytics service rather than parsing manually. + +**Forensic reports (`ruf=`) flooding.** Forensic reports include full message content of failures and can be high volume. Many use `rua=` (aggregate) only, especially after Stage 1. + +--- + +## Tools + +- **Reporting/Analytics:** Postmark, dmarcian, EasyDMARC, Valimail, Cloudflare Email Routing (free for some scenarios), or roll your own with a DMARC parser library. +- **Testing:** mxtoolbox.com, mail-tester.com, dmarcian.com. +- **Lookups:** `dig +short txt _dmarc.example.com`. + +--- + +## Timing summary + +| Stage | Policy | Duration | What you're doing | +|---|---|---|---| +| 1 | `p=none` | 1-2 weeks | Discovery | +| 2 | `p=quarantine; pct=10` | 1-2 weeks | Initial enforcement | +| 3 | `p=quarantine; pct=100` | 1-2 weeks | Full quarantine | +| 4 | `p=reject; pct=10` | 1-2 weeks | Initial rejection | +| 5 | `p=reject; pct=50` | 1-2 weeks | Half rejection | +| 6 | `p=reject; pct=100` | Ongoing | Full enforcement | + +Total: 6-12 weeks. Don't shortcut. The cost of moving slowly is low; the cost of breaking legitimate mail is high. diff --git a/dist/pi/.agents/skills/email-sequences/SKILL.md b/dist/pi/.agents/skills/email-sequences/SKILL.md new file mode 100644 index 0000000..e735886 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/SKILL.md @@ -0,0 +1,282 @@ +--- +name: email-sequences +description: "Design and write email campaigns and sequences including onboarding flows, lifecycle campaigns, transactional emails, newsletters, broadcast sends, and launch and announcement emails. Use this skill whenever the user wants to write email copy, plan an email sequence, design an onboarding drip, or set up lifecycle email campaigns. Triggers on email sequence, drip campaign, onboarding email, lifecycle email, welcome email, transactional email, newsletter, email broadcast, launch email, announcement email, nurture sequence, abandoned cart, re-engagement, win-back. Also triggers when planning email automation flows or writing email subject lines for campaigns." +category: content +catalog_summary: "Onboarding flows, lifecycle campaigns, transactional copy" +display_order: 5 +--- + +# Email Sequences + +Plan and write email campaigns. Sequences (multi-message flows triggered by events) and broadcasts (one-off sends). Stack-agnostic. Works with any email service provider. + +--- + +## When to use + +- Writing welcome and onboarding email sequences +- Planning lifecycle campaigns (activation, retention, win-back) +- Writing transactional emails (receipts, password resets, notifications) +- Newsletter design and writing +- Abandoned-cart or re-engagement flows +- Writing a one-off broadcast, launch announcement, or news email +- Drafting email subject lines and preview text for any send + +## When NOT to use + +- Landing pages and conversion pages (use `landing-page-copy`) +- Long-form articles (use `content-and-copy`) +- Brand voice work (use `brand-voice`) +- Analytics setup for email (use `analytics-strategy`) + +--- + +## Required inputs + +- The audience (segment or list) +- The trigger or context (signup, purchase, abandonment, time-based, manual) +- The goal of the email or sequence +- Brand voice +- Any technical constraints (provider, deliverability requirements) + +If the audience is undefined, define it before writing. Generic emails to "everyone" perform worse than targeted ones. + +--- + +## The framework: 6 sequence types + +Most email programs run a handful of standard sequence patterns. Each has its own goals, structure, and pitfalls. + +### 1. Welcome / onboarding + +Triggered by signup. Goal: get the user to first value. + +**Typical structure (5 emails over 14 days):** + +- **Email 1 (immediate):** Welcome. Confirm they're in. State what happens next. Single CTA: the next obvious action. +- **Email 2 (day 1 or 2):** First-value step. Help them get to a quick win or core action. +- **Email 3 (day 4 or 5):** Education. Show them something they probably haven't discovered yet. +- **Email 4 (day 8):** Social proof. Customer story or use case relevant to their segment. +- **Email 5 (day 14):** Outcome reminder. Where they could be in 30/60/90 days. Soft commercial cue. + +**Common failure:** Front-loading product features. Users don't care about features yet; they care about getting to value. + +### 2. Lifecycle / activation + +Time- or behavior-triggered. Goal: move users from signup to engaged user. + +**Patterns:** +- Sent when a user completes a milestone (first project, first invite, first export) +- Or sent when a user has NOT completed a milestone after N days +- Each email targets a specific next step + +**Best practice:** Trigger on behavior, not just time. A user who has done 3 onboarding steps doesn't need an email telling them to get started. + +### 3. Retention / engagement + +Ongoing. Goal: keep active users engaged. + +**Patterns:** +- Newsletter (weekly or monthly) +- Product updates +- Tips and tutorials +- Customer-only content (community, behind-the-scenes) + +**Cadence rule:** Frequency that earns the read, not frequency that fills the calendar. Weekly newsletter that is genuinely useful beats daily newsletter that gets archived. + +### 4. Re-engagement / win-back + +Triggered by inactivity. Goal: pull a lapsed user back. + +**Typical structure (3 emails):** + +- **Email 1:** "We miss you" framing or value reminder. What's new since they were last active. +- **Email 2:** Specific incentive (discount, feature unlock, content offer). +- **Email 3:** "Last call" or list-cleaning email. "We'll stop emailing you unless you click this." + +**Best practice:** Honor the unsubscribe. Aggressive win-back damages deliverability. A clean list of engaged subscribers beats a large list of inactive ones. + +### 5. Transactional + +Triggered by actions: receipts, password resets, notifications, order confirmations, shipping updates. + +**Best practices:** +- Confirm the action that triggered the email at the top +- Include all relevant detail without padding +- Use plain language ("Your order shipped" not "Your shipment notification") +- One primary CTA (track package, view receipt, view account) +- Subject line states the action ("Your receipt for order #12345") + +**Highest open rates** of any email type. Use sparingly for marketing nudges; over-marketing transactional emails damages trust. + +### 6. Broadcast + +One-off sends. Announcements, launches, news, time-sensitive campaigns. + +**Best practices:** +- Subject line earns the open +- Single clear message per send +- Specific audience targeting (do not blast the entire list for narrow announcements) +- Clear CTA in the first screen-height +- Mobile-optimized (most opens are mobile) + +--- + +## The 5 components of every email + +Regardless of sequence type, every email has the same components. + +### 1. Subject line + +The deciding factor for whether the email gets opened. + +**Patterns:** +- **Specific** ("Your week 1 progress: 3 of 5 steps done") +- **Curiosity** ("The mistake most teams make in week 2") +- **Direct** ("Your invoice #12345") +- **Personal** ("Quick question, [name]") +- **Urgency** ("Last day for the team plan discount") - use sparingly + +**Avoid:** +- ALL CAPS +- Excessive punctuation (!!!) +- Click-bait that doesn't deliver +- Generic ("Newsletter #23") + +**Length:** 30 to 50 characters. Mobile clients truncate longer. + +### 2. Preview text (preheader) + +The line that appears below or beside the subject in most email clients. + +**Best practice:** +- Treat as the subject's wingman +- Add what the subject line couldn't fit +- Avoid wasting it on "View this email in browser" +- 50 to 90 characters + +### 3. Opening + +The first line of the email body. The reader is deciding whether to keep reading. + +**Strong openings:** +- Reference the trigger ("You signed up yesterday for...") +- Get to the point ("Here's what changed this week...") +- Personal ("Saw your team just hit milestone X. Nice work.") + +**Weak openings:** +- "I hope this email finds you well." +- "Welcome to our amazing platform." +- Long throat-clearing before the actual content + +### 4. Body + +The substance. + +**Length guide:** +- Welcome and transactional: under 100 words +- Lifecycle and activation: 100 to 250 words +- Newsletter: 200 to 800 words depending on format +- Sales sequences: 250 to 500 words + +**Structure:** +- One core message per email (avoid "while we have you...") +- Short paragraphs (2 to 3 lines) +- Bullets or lists when content is enumerable +- Mobile-first formatting + +### 5. CTA + +The action the email is asking for. + +**Best practices:** +- One primary CTA per email (multiple CTAs split attention) +- Button or clearly-styled link, not buried in prose +- Action verb + specific outcome ("See your dashboard" not "Click here") +- Above the fold AND repeated at the end of longer emails +- Plain text link as a fallback for users who block buttons + +--- + +## Workflow + +### For a new sequence + +1. **Define the trigger.** What event starts this sequence? (Signup, purchase, abandonment, manual.) +2. **Define the goal.** What does success look like at the end of the sequence? +3. **Map the journey.** What does the recipient need to know, do, or feel between trigger and goal? +4. **Outline emails.** One purpose per email. Sequence them across appropriate timing. +5. **Draft email 1.** Subject, preview, opening, body, CTA. +6. **Draft remaining emails.** Each builds on the previous. +7. **Test the sequence.** Send to yourself. Read on mobile. Time the gaps. +8. **Set up triggers.** Configure in the email service provider. +9. **Measure.** Open rate, click rate, completion rate per email. Sequence completion rate. + +### For a single broadcast + +1. **Define the audience.** Specific segment, not the whole list. +2. **Define the goal.** One thing this email accomplishes. +3. **Draft subject + preview.** Generate 5 to 10 variations. +4. **Draft body.** Single message, clear CTA. +5. **Test on mobile.** Most opens are mobile. +6. **Schedule.** Day and time matched to audience behavior. +7. **Measure.** Open rate, click rate, downstream conversions. + +--- + +## Failure patterns + +- **Sending to "everyone."** Generic broadcasts to the full list have lower engagement than targeted segments. +- **Too many CTAs in one email.** Splits attention. Pick one. +- **Subject line clickbait that doesn't deliver.** Crashes the trust the email program is trying to build. +- **Sequences that ignore behavior.** Sending day-3 onboarding email to a user who already activated wastes the touch. +- **Mobile-broken layouts.** 60 to 70 percent of opens are on mobile. Test there first. +- **Long pre-text.** Burying the message under "I hope this email finds you well" wastes the read. +- **Aggressive win-back.** Emailing dormant users 5 times damages deliverability and brand trust. +- **No measurement.** Without tracking opens, clicks, and downstream conversion, you can't iterate. +- **Ignoring deliverability.** Sender reputation, authentication (SPF, DKIM, DMARC), list hygiene. Skip these and emails go to spam regardless of how good the content is. + +--- + +## Output format + +Default output is a markdown document per email or sequence: + +```markdown +# Sequence: [Name] + +**Trigger:** [What starts this sequence] +**Goal:** [Outcome at completion] +**Audience:** [Specific segment] +**Length:** [N emails over X days] + +## Email 1 - [Subject working title] + +**Send:** [Trigger / Day N] +**Subject:** [text] +**Preview:** [text] + +[Body] + +**Primary CTA:** [text] +**CTA URL:** [destination] + +--- + +## Email 2 - [Subject working title] + +[Same structure] + +--- + +[etc.] +``` + +For a single broadcast, just one email block. + +--- + +## Reference files + +- [`references/subject-line-patterns.md`](references/subject-line-patterns.md) - Subject line patterns with examples for each sequence type. +- [`references/sequence-templates.md`](references/sequence-templates.md) - Skeleton templates for the 6 sequence types. diff --git a/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md b/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md new file mode 100644 index 0000000..ac0ca87 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md @@ -0,0 +1,252 @@ +# Sequence Templates + +Starter outlines for the 5 standard sequence types. These are scaffolds. Adapt the cadence, voice, and content to the specific brand and audience. + +--- + +## Onboarding sequence (SaaS, 7 emails over 14 days) + +### Email 1 - Welcome +**Send:** Immediately on signup +**Subject:** Welcome to [Product]. Here's your first step. +**Body skeleton:** +- One-line welcome +- Restate the outcome they signed up for +- ONE clear next step +- Optional: founder note for early-stage products + +### Email 2 - First action tutorial +**Send:** T+1 day +**Subject:** [Specific first task] in 5 minutes +**Body skeleton:** +- Hook: Why this first task matters +- 3 to 5 numbered steps +- Visual or screenshot +- CTA back to the product + +### Email 3 - Build on first +**Send:** T+3 days +**Subject:** Now that [first task done], try [second task] +**Body skeleton:** +- Acknowledge progress (works even if user hasn't done first task; it primes them) +- Introduce next capability +- Show what it unlocks +- CTA + +### Email 4 - Use case spotlight +**Send:** T+5 days +**Subject:** How [persona] uses [Product] to [outcome] +**Body skeleton:** +- Specific persona description +- Their workflow with the product +- Specific result +- "Try this approach" CTA + +### Email 5 - Common questions +**Send:** T+7 days +**Subject:** Quick answers to questions new users ask +**Body skeleton:** +- 3 to 5 FAQs with brief answers +- Links to fuller help docs +- CTA: open help center or chat with support + +### Email 6 - Re-engagement check +**Send:** T+10 days (only if user is dormant) +**Subject:** Need a hand getting started? +**Body skeleton:** +- Acknowledge they may be busy +- Offer a 10-minute call or specific resource +- One simple action they can take in <2 minutes + +### Email 7 - Hand-off to ongoing comms +**Send:** T+14 days +**Subject:** You're set up. Here's what to expect from us. +**Body skeleton:** +- Confirm onboarding complete +- Set expectations for future emails (frequency, content type) +- Offer preferences center +- Light next-step CTA + +--- + +## Lifecycle (triggered, individual emails) + +### Anniversary (annual) +**Subject:** Hard to believe - it's been a year +**Body:** Celebrate the milestone, surface specific achievements ("You shipped X projects this year"), suggest next-level use case. + +### Plan upgrade nudge +**Subject:** You're hitting your [Plan] limits +**Body:** Specific data showing usage approaching limits, value of next tier, painless upgrade path. + +### Inactivity check (30 days dormant) +**Subject:** We haven't seen you for a bit +**Body:** Light touch, restate value, surface a recent improvement, easy way to come back. + +### Power user celebration (Y key actions) +**Subject:** You've crossed [Y] [actions]. Nice. +**Body:** Acknowledge the milestone, share advanced tips, invite to community or beta. + +### Feature announcement (when relevant feature ships) +**Subject:** New: [feature] +**Body:** What it does, why we built it, how to start using it. Brief. + +--- + +## Sales nurture (B2B, 9 emails over 28 days) + +### Email 1 - Deliver the asset +**Send:** Immediately on opt-in +**Subject:** Your [asset name] +**Body:** Direct download link, brief intro to what's inside. + +### Email 2 - Educational angle +**Send:** T+2 days +**Subject:** [Specific question the audience asks] +**Body:** Useful content piece tied to their problem. No pitch. + +### Email 3 - Educational angle (different facet) +**Send:** T+4 days +**Subject:** [Adjacent question] +**Body:** Different angle on the same problem space. + +### Email 4 - Customer story +**Send:** T+7 days +**Subject:** How [Customer] [achieved specific outcome] +**Body:** Specific company, specific outcome, specific approach. Their story, with brand as supporting role. + +### Email 5 - Objection handling +**Send:** T+10 days +**Subject:** "I'm not sure [common objection]" +**Body:** Address the most common reason this audience hesitates. Honest, non-defensive. + +### Email 6 - Demo invitation +**Send:** T+14 days +**Subject:** Want to see [Product] in action? +**Body:** 20-minute personalized demo offer. Specific outcome the demo will show. + +### Email 7 - Strong proof + soft pitch +**Send:** T+18 days +**Subject:** [Specific result] in [specific time] +**Body:** Strongest case study, direct invitation to start a trial or call. + +### Email 8 - Urgency +**Send:** T+21 days +**Subject:** [Deadline or limited offer] +**Body:** Clear offer with deadline. Real urgency only - manufactured urgency damages trust. + +### Email 9 - Goodbye +**Send:** T+28 days +**Subject:** Last note from us +**Body:** Acknowledge the silence. Offer one last resource or chance to opt back in. Then suppress or move to long-term nurture list. + +--- + +## Transactional templates + +### Order confirmation +**Subject:** Your order #[number] is confirmed +**Body:** +- Order summary (items, totals, shipping address) +- Estimated delivery +- Order tracking link +- Support contact + +Keep marketing minimal. People are looking for specific info. + +### Password reset +**Subject:** Reset your password +**Body:** +- Brief acknowledgment of the request +- Reset link (with expiration time stated) +- "Did not request this?" instruction +- Support contact + +No marketing in transactional. Keep it clean. + +### Email verification +**Subject:** Verify your email +**Body:** +- One-line ask +- Big verify button +- "If you did not sign up..." opt-out +- Expiration time + +### Abandoned cart +**Subject:** You left these in your cart +**Body:** +- Items left in cart with images +- Quick-resume link +- Optional: incentive (free shipping, small discount) +- Support contact + +Send 1 email at T+1 hour, optional second at T+24 hours, NO third email (annoyance penalty exceeds recovery). + +--- + +## Win-back (5 emails over 20 days) + +### Email 1 - We miss you +**Subject:** Hey, it's been a while +**Body:** Acknowledge the lapse, brief reminder of what's possible, soft re-engage CTA. + +### Email 2 - What's new +**Subject:** A few things have changed since you were last here +**Body:** Updates, new features, recent improvements. Specific. + +### Email 3 - Specific incentive +**Subject:** Come back: [specific offer] +**Body:** Concrete incentive (discount, bonus, free month). Deadline. + +### Email 4 - Last chance +**Subject:** Last call: [offer ends X] +**Body:** Final reminder of the offer. Clear deadline. + +### Email 5 - Sunset +**Subject:** We'll miss you +**Body:** Acknowledge they're not coming back, confirm we're stepping down sends, leave the door open. + +After this email: suppress from active sends. Optional: move to a quarterly "big news only" list. + +--- + +## Cadence rules across all sequence types + +- **Default time of day:** 8 to 10 AM in the recipient's timezone for non-time-sensitive sends. +- **Avoid send fatigue:** Cap at 2 emails per week from the same brand to the same person across all programs. +- **Respect engagement:** If a user has opened zero of the last 5 emails, throttle frequency or sunset. +- **Honor unsubscribes immediately:** Same-day, all programs, no exceptions. +- **Test sending:** Send tests to 5+ devices before any sequence goes live. + +--- + +## Subject line patterns that work + +- **Specific question:** "Why your churn rate isn't moving" +- **Specific number:** "47% of B2B buyers do this before purchasing" +- **Personal/conversational:** "Quick question about [topic]" +- **Curiosity gap:** "The mistake we see in 80% of pricing pages" +- **Negative framing (sparingly):** "Don't make this mistake on your next launch" +- **Direct value:** "Free template: 90-day onboarding checklist" + +Avoid: + +- Subject lines that look like spam (all caps, multiple exclamations) +- Misleading subject lines (mentions in subject that aren't in body) +- Tricks ("Re:" or "Fwd:" on cold sends) +- Subject lines longer than 50 characters where avoidable + +--- + +## Metrics to track per sequence + +| Metric | Target benchmark (rough) | +|---|---| +| Open rate | 20 to 35% (varies wildly by industry) | +| Click-through rate | 2 to 5% | +| Conversion to goal | Sequence-specific | +| Unsubscribe rate per email | <0.5% | +| Spam complaint rate | <0.1% | +| Reply rate (for cold/B2B) | 1 to 3% | + +Below benchmark: investigate the weakest emails in the sequence first. Above: capture what worked and apply to other sequences. diff --git a/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md b/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md new file mode 100644 index 0000000..2df7648 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md @@ -0,0 +1,298 @@ +# Subject Line Patterns + +Subject lines are the deciding factor for opens. A great email with a weak subject gets archived unread. + +These patterns are tools, not formulas. Apply them, then make them sound like the brand. + +--- + +## Universal rules + +- **Length:** 30 to 50 characters. Mobile clients truncate longer. +- **No ALL CAPS.** Reads as shouting and triggers spam filters. +- **No excessive punctuation.** "!!!" reads as desperate. +- **Match the body.** A subject that doesn't deliver in the body kills trust. +- **Sentence case** is more readable than Title Case in inboxes. +- **Skip the prefix conventions** ("Newsletter #23"). Subscribers ignore them. + +--- + +## Pattern 1: Specific outcome + +Names what the reader gets. + +**Examples:** +- "The 5 questions to ask before hiring a designer" +- "Your team's productivity numbers for September" +- "How to cut your invoicing time in half" +- "What changed in your competitor's pricing this month" + +**Strengths:** Clear value. Easy to evaluate whether to open. + +**When to use:** Newsletters, content emails, value-driven sends. + +--- + +## Pattern 2: Curiosity gap + +Opens a loop the email body closes. + +**Examples:** +- "The mistake most teams make in week 2" +- "Why your best customers are leaving" +- "The one habit your top performers share" +- "What I wish I'd known before scaling to 50 people" + +**Strengths:** High open rates when the gap is genuine. + +**Risks:** Becomes click-bait if the body doesn't deliver. Erodes trust over time. + +**When to use:** Sparingly. The body must deliver real insight. + +--- + +## Pattern 3: Personal / direct + +Speaks as if to a friend. + +**Examples:** +- "Quick question, [name]" +- "Saw this and thought of you" +- "Got 5 minutes?" +- "Are you still using [tool]?" + +**Strengths:** Feels human. Cuts through marketing-speak. + +**Risks:** Used by every spam email. Authentic context required for it to work. + +**When to use:** 1:1 sends, personalized cold outreach, founder-to-customer emails. + +--- + +## Pattern 4: Direct / no-mystery + +States exactly what the email is about. + +**Examples:** +- "Your receipt for order #12345" +- "Password reset link" +- "Invoice for September" +- "Meeting confirmation: Tuesday 2pm" + +**Strengths:** High trust. High open rates for transactional content. + +**When to use:** Transactional emails. Always be direct. + +--- + +## Pattern 5: Question + +Poses the question the reader is asking. + +**Examples:** +- "Should you hire a generalist or specialist first?" +- "Is your pricing too cheap?" +- "What's the ROI of customer service?" +- "Are you measuring the wrong KPIs?" + +**Strengths:** Aligns with the reader's mental state. Strong for educational content. + +**When to use:** Newsletters and educational sequences. + +--- + +## Pattern 6: Number / list + +Promises a specific quantity of items. + +**Examples:** +- "3 things to do this week to retain customers" +- "7 signs your team is about to burn out" +- "The 4-step checklist for a clean handoff" + +**Strengths:** Sets clear expectations. Easy to scan. + +**Risks:** Overused. Can read as listicle filler. + +**When to use:** When the content genuinely is a list and the count matters. + +--- + +## Pattern 7: Time-bound / urgency + +Signals the email is time-sensitive. + +**Examples:** +- "Last day: free shipping on your order" +- "Webinar starts in 2 hours" +- "Pricing changes Thursday" + +**Strengths:** Drives immediate action. + +**Risks:** Overuse trains subscribers to ignore urgency cues. Reserve for genuine deadlines. + +**When to use:** Real time-sensitive sends only. Never fake urgency. + +--- + +## Pattern 8: News / update + +States what's new. + +**Examples:** +- "New: instant export to spreadsheets" +- "Just launched: team mode" +- "Update on the integration you asked for" + +**Strengths:** Useful for product update emails. + +**When to use:** Real product announcements that the recipient signed up to hear about. + +--- + +## Pattern 9: Personal anecdote / story + +Hints at a story. + +**Examples:** +- "I almost didn't ship this" +- "What happened when we tried [thing]" +- "The phone call that changed our hiring process" + +**Strengths:** Strong for narrative-driven brand newsletters. + +**When to use:** When the brand voice supports storytelling. + +--- + +## Pattern 10: Reference to recipient's behavior + +Acknowledges what they did. + +**Examples:** +- "Saw you tried [feature] - here's what's next" +- "Welcome back. Here's what you missed." +- "You completed week 1. Here's week 2." + +**Strengths:** Personalization that actually feels personal. + +**When to use:** Behavior-triggered emails. Lifecycle and onboarding sequences. + +--- + +## Subject lines by sequence type + +### Welcome / onboarding + +``` +Email 1: Welcome to [Brand], [name] +Email 2: The first thing to do in [Brand] +Email 3: How [audience] use [Brand] (3 examples) +Email 4: Did this happen for you? +Email 5: 30 days in: where you could be +``` + +### Lifecycle / activation + +``` +Trigger: completed milestone +"Nice work hitting [milestone]. Here's what's next." + +Trigger: stalled on a step +"Quick question about your setup" +``` + +### Re-engagement / win-back + +``` +Email 1: Hey [name], we miss you +Email 2: Here's [specific incentive] +Email 3: Last email - should we say goodbye? +``` + +### Newsletter + +``` +Curiosity: "The metric most teams ignore" +Specific: "September wrap: what we shipped, what we learned" +Question: "Should you raise your prices?" +Number: "3 reads from this week" +``` + +### Transactional + +``` +"Your order is on the way (#12345)" +"Receipt for your subscription" +"Your password was changed" +"Action required: confirm your email" +``` + +### Broadcast + +``` +Launch: "Just shipped: [feature]" +Event: "Live this Thursday: [topic]" +Update: "Our pricing changed today. Here's what it means for you." +``` + +--- + +## A/B test ideas + +Subject lines are the easiest thing to test. For any meaningful send, generate 2 to 4 variations along these axes: + +- **Specific vs. curiosity:** Does the audience prefer to know what they're getting, or to be intrigued? +- **Personal vs. direct:** Does first-person ("I just shipped this") work better than third-person ("Just launched")? +- **Length:** Short (under 30 chars) vs. medium (30 to 50 chars). +- **Punctuation:** Question vs. statement. +- **Personalization:** With name vs. without. + +Track open rates and click-through rates. Open alone is incomplete; some subject patterns get opened but discarded. + +--- + +## What to avoid + +### "Just checking in" +Empty. Adds no value. Reads as nag. + +### "Following up" +Same problem. The reader knows you're following up. Tell them why. + +### "Thoughts?" +A request without context. Comes across as lazy. + +### "Hi" +Just don't. Even from someone you know. + +### Excessive emojis +🎉🚀✨ does not signal value. Often signals spam to filters. + +### Re: when it's not actually a reply +Deceptive. Damages trust. + +### Personalization gone wrong +"{first_name} wanted to chat" with the variable un-rendered. Test send before broadcast. + +--- + +## Preview text (preheader) + +The line that appears next to or below the subject. Often more important than the subject for engagement. + +**Best practice:** +- Use it as the subject's continuation +- 50 to 90 characters +- Don't waste it on "View in browser" or boilerplate +- Add the detail the subject didn't fit + +**Examples of subject + preview pairs:** + +| Subject | Preview | +|---|---| +| "Your week 1 progress" | "3 of 5 steps complete. Here's what's next." | +| "The mistake most teams make" | "(It's not the obvious one)" | +| "Just shipped: team mode" | "Invite up to 50 teammates and assign roles." | + +A weak preview wastes prime real estate. A strong preview can save a mediocre subject. diff --git a/dist/pi/.agents/skills/experiment-design/SKILL.md b/dist/pi/.agents/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..c858add --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/SKILL.md @@ -0,0 +1,255 @@ +--- +name: experiment-design +description: A discipline for designing experiments (A/B tests, multivariate, holdouts) so the results actually answer the question you asked. Hypothesis writing, sample size, duration, segment analysis, interpretation, decision-making, and the common failure modes that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Hypothesis to decision: sample size, duration, segment analysis, interpretation, and the failure modes that produce wrong shipping calls" +display_order: 4 +--- + +# Experiment Design + +A senior product manager's playbook for running experiments that produce trustworthy decisions. + +The default state of experimentation in most companies is sloppy. PMs run tests against vague hypotheses, look at results too early, ignore guardrails, stratify into noise, and ship features whose lift is mostly measurement error. The cost is real: ship the wrong thing, kill the right thing, learn the wrong lesson, repeat. + +This skill is the discipline that prevents most of those mistakes. It assumes you have a working experimentation platform (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon; the platform does not matter for the principles). It assumes you have product-design and engineering pipelines that can deliver real treatment changes. The hard part is the thinking, and that is what is here. + +When to use this skill: any time you are about to design or interpret an experiment. Read the relevant section before you start, not after the test is running. + +--- + +## What this skill covers + +The skill spans the full experiment lifecycle. Pre-experiment readiness (is this thing even worth testing). Hypothesis design (cause, effect, magnitude, mechanism). Sample size and minimum detectable effect (do you have enough traffic to learn anything). Duration (how long is long enough, when does the cycle bias the result). Running discipline (no peeking, guardrails, sequential testing). Interpretation (the three buckets and the inconclusive case). Decision-making (matching the result to a pre-committed rule). + +The skill does not cover feature flag operational mechanics; those live in the `feature-flagging` skill, which handles flag taxonomy, environment management, and stale-flag cleanup as a separate discipline. The skill does not cover statistical analysis depth; for delta methods, variance reduction techniques like CUPED, and Bayesian alternatives, see the `experimentation-analytics` skill. The skill does not cover platform-specific tooling; for MCP commands, auth models, and platform-specific configuration, consult the chosen platform's official documentation. This skill produces the experiment design; the platform implements it. + +For the orchestration layer above (which experiments to run, in what order, with what cadence), see the forthcoming `experimentation-platform-orchestrator` skill. That skill schedules; this skill designs. + +--- + +## The framework: 12 considerations for trustworthy experiment results + +A defensible experiment design sits at the intersection of twelve considerations. Each is covered in detail in its own section below. + +1. **Hypothesis discipline.** Cause, effect, magnitude, and mechanism. The hypothesis names what is being tested, what should move, by how much, and why. +2. **Sample size and minimum detectable effect (MDE).** Whether the test has enough traffic to detect the effect at the chosen power. Refuse to run underpowered tests. +3. **Test duration.** Longer of the sample-size-hit duration and a full weekly cycle. UI/UX changes need at least 14 days regardless. +4. **What NOT to A/B test.** UX bugs, legal-required changes, brand-philosophy questions, decisions already made, designs whose randomization cannot be clean. +5. **Segment analysis.** Pre-registered segments are evidence; post-hoc segments are noise mining. The multiple comparisons problem is real. +6. **Interaction effects.** Concurrent tests on the same surface can interfere. Mutex enforcement or coordination required. +7. **Ratio metrics and variance estimation.** Naive variance estimators on ratios understate uncertainty. Confirm the platform uses a ratio-aware estimator. +8. **Network effects and two-sided markets.** Treatment can leak into control via interference. Cluster randomization, switchback, or geographic isolation when needed. +9. **Sequential testing and the peeking problem.** Daily peeking inflates false positive rates. Use sequential testing methods when available; pre-commit otherwise. +10. **Pre-commitment vs p-hacking.** Write down the primary metric, MDE, duration, segments, and decision rule before launch. Apply mechanically when results come in. +11. **Reading results and making the call.** Three buckets: clear win, clear loss, inconclusive. The inconclusive bucket exists for a reason; resist the pull to ship anyway. +12. **Common failures and fixes.** A short rapid-fire pattern catalog, expanded in [`references/common-failures.md`](references/common-failures.md). + +The sections below cover each consideration in turn. Read the relevant section before running the experiment, not after. + +--- + +## Hypothesis discipline + +The most important section in the skill. Most experiment failures trace back to a vague hypothesis. + +A real hypothesis has four parts: cause, effect, magnitude, mechanism. Cause is the change you are making. Effect is the metric you expect to move. Magnitude is how much you expect it to move and from what baseline. Mechanism is why you expect this change to produce this effect. + +Bad hypothesis, common shape: "We think the new pricing page will increase conversions." What is wrong with it: no magnitude (how much), no mechanism (why), and the metric is "conversions" rather than a specific event with a clear definition. The team will run this test, look at the result, and argue about what counts as a win. Pre-commitment is impossible because nothing was committed. + +Good hypothesis, same domain: "Replacing the three-tier pricing comparison with a single recommended tier will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe." Cause is the tier replacement. Effect is signup-to-paid conversion, defined as the user reaches the paywall and completes payment within seven days. Magnitude is 8 percent relative lift, taking the rate from 12 to 13 percent absolute. Mechanism is decision friction reduction. Now the team has something to test, a number to hit, and a story to falsify. + +Primary metric vs guardrails. The primary metric is the thing you are trying to move. Guardrails are the things that must not break: revenue, retention, support ticket volume, page load time, error rates. Pick exactly one primary metric. Pick three to five guardrails. Multiple primary metrics destroy the discipline because they let you cherry-pick the favorable one when results come in. + +Falsifiability test. Before launching the experiment, write down what would make you NOT ship this. If the answer is "nothing, we are committed to the change regardless," the hypothesis is not real and the experiment is theater. Skip the test, save the engineering time, and just ship the change. + +Directional vs magnitude distinction. Knowing the change moves the needle is different from knowing it moves the needle enough to matter. A 0.3 percent absolute lift on signup conversion may be statistically significant with enough traffic and still not justify the engineering cost of maintaining the change. Magnitude matters as much as direction; the hypothesis names the magnitude that would justify shipping. + +For templates and worked examples across common metric types, see [`references/hypothesis-templates.md`](references/hypothesis-templates.md). + +--- + +## Sample size and minimum detectable effect + +Sample size grows with the inverse square of the effect you want to detect. Detecting a 1 percent lift requires roughly one hundred times the sample needed to detect a 10 percent lift. Most PMs underestimate this. + +The basic decision rule: if your minimum detectable effect (MDE) at current traffic and a reasonable test duration is greater than 5 percent absolute lift, you probably need a bigger MDE. Tiny changes that need huge samples to detect are usually not worth shipping anyway. The change is small either because the underlying mechanism is weak or because the implementation is timid. A weak mechanism is not worth a launch. A timid implementation should be made bolder before testing. + +The "we do not have enough traffic" trap. Real for very small products. Lazy for everyone else. If you have ten thousand users a week and you are trying to detect a half-percent absolute lift, you are not running an experiment, you are sampling noise. Pick changes whose expected effect is large enough to detect at your traffic level. If the change is genuinely small, ship it without a test (small upside, small downside, low cost) or do not ship it at all. + +Power. The test's ability to detect an effect that is actually present. The conventional floor is 80 percent. Below that, you are rolling dice; the test will frequently miss real effects. Higher power costs more sample. Most platforms default to 80; if you change it, document why. + +One-sided vs two-sided. Most PM tests are two-sided despite the temptation to claim otherwise. A one-sided test says "I only care about the positive direction; if the change makes things worse, I do not need to detect it." That is rarely true. If the new pricing page tanks conversion, you want to know. Default to two-sided. If you genuinely want one-sided, document the asymmetry before running. + +For pre-calculated sample size tables across common conversion rate baselines and MDEs, see [`references/sample-size-tables.md`](references/sample-size-tables.md). The tables are starting points, not substitutes for running the math against your specific traffic and metric. + +--- + +## Test duration + +Minimum duration is the longer of two constraints. Constraint one: the sample size hits the calculated requirement. Constraint two: the test runs at least one full weekly cycle. Testing only Monday through Wednesday misses weekend behavior, which on most consumer products differs meaningfully from weekday behavior. + +Novelty effects. New things attract attention. The first few days of a winning test often overstate the lift. Users notice the change, click it, and produce a temporary effect that fades as the novelty wears off. Run long enough to see if the lift survives the novelty period. Two weeks is the conventional minimum for any UI/UX experiment, even if the sample size hits faster. + +Primacy effects. The opposite problem. Existing users may resist the change in week one and adapt by week three. Common in UI rearrangement tests. Killing the test in week one because the result looks negative misses the point that primacy is bigger than the underlying effect at that timescale. + +Holdout periods. If the experiment changes a permanent feature (notification frequency, default settings, search ranking), keep a holdout group OFF the new behavior for at least a month after launch. The holdout measures long-term effect, not just the day-1 lift. Long-term effects are often different from short-term effects: a notification change that increases day-1 engagement may decrease month-three retention. + +Maximum duration. Usually four to six weeks. Beyond that, the world changes around the test. Seasonality shifts. Marketing campaigns launch. The product evolves. The comparison between treatment and control stops being clean because the underlying user population is no longer comparable across the test window. If the test needs to run longer than six weeks to hit power, the MDE is probably wrong; the change is too small to detect cleanly. + +--- + +## What NOT to A/B test + +This is a section many discussions of experimentation skip. Worth being direct about. + +UX bug fixes. If the current behavior is objectively broken (button does not work, copy says the wrong thing, accessibility fails), fix it. A/B testing it is theater. The right answer is not "let's see if our users prefer a working button"; the right answer is to ship the working button. + +Legal-required changes. GDPR consent flows, accessibility compliance, regulatory disclaimers. Ship them. The lift is irrelevant; the compliance is the point. A/B testing whether to comply with the law is not a serious question. + +Strategic or philosophical brand questions. "Should our voice be playful or serious?" is not an A/B test question; it is a brand strategy question that needs to be made by humans with context, weighed against brand equity, audience expectation, and long-term positioning. Picking the variant with the higher click-through rate does not answer it because click-through rate was not the brand decision. Use the experiment data as one input to the brand decision, not as the decision itself. + +Things you have already decided. If leadership has committed to a direction regardless of test result, do not run an experiment. A/B testing as theater (running tests where the outcome does not change the decision) corrodes trust in the experimentation discipline overall. Other PMs see the test, see the result ignored, and conclude that experiment results do not matter at this company. Then they stop pre-committing. Then the discipline collapses. + +Things where the test design is impossible. Cross-device experiences, network effects, internal tooling for a ten-person ops team, anything where the sample size is fundamentally too small or the randomization is fundamentally contaminated. Sometimes the right answer is qualitative research, longitudinal cohort analysis, or just shipping and watching. An experiment that cannot be designed cleanly will not produce a clean answer. + +--- + +## Segment analysis + +Pre-registered segments versus post-hoc segments. Declaring before the test runs that "we will look at the result for new users versus returning users" is fine. Discovering after the test that "users from California who signed up on Tuesdays via mobile" had a huge lift is almost always noise mining. + +The multiple comparisons problem. Every additional segment you analyze increases the probability of finding a "significant" result by chance. With twenty independent segments at p equals 0.05, you expect one false positive purely by chance. With fifty segments, two or three. Do not analyze fifty segments and report the one that hit significance. + +When stratification helps versus misleads. Stratification is useful when three things are true. The segment was pre-registered. There is a real prior reason to expect different behavior in this segment. There is enough sample within the segment to detect the effect at the chosen power. If any of the three is missing, stratification is noise mining. The default posture should be: report the overall result. Report pre-registered segments as additional context. Do not report unplanned segments. + +The "weighted average" reframe. If a treatment is positive for one segment and negative for another, the right question is "what is the weighted average effect across the population we will actually ship to" not "let's just ship to the segment where it works." Shipping to a segment usually requires UI complexity, audience targeting infrastructure, and ongoing maintenance that the segment-specific lift does not justify. The bias against segment-specific shipping is healthy. + +--- + +## Interaction effects + +The classic problem: you are running five concurrent A/B tests on the checkout flow. Each test individually shows a small lift. Together, the combinations may not multiply cleanly. They may not even sum cleanly. They may interfere in ways the individual tests cannot reveal. + +Pre-experiment hygiene. Before launching a new experiment, check what other experiments are running on the same surface. Ask the other PM owners. Coordinate on which tests are mutually exclusive and which can overlap. + +Mutex (mutually exclusive) experiment groups. Most platforms support exclusion rules so users in test A are not also in test B. Use them when interactions are likely. The cost is sample size; the benefit is interpretable results. For a small set of high-stakes tests, mutex is the right call. For dozens of lower-stakes tests, full mutex is impractical; coordinate and document overlap instead. + +The "we will analyze it later" fallacy. Post-hoc detangling of overlapping experiments is hard, expensive, and usually inconclusive. The factorial design that would isolate interaction effects requires sample sizes most products do not have. Coordinate up front rather than untangle afterwards. + +--- + +## Ratio metrics and the delta method + +The trap. Conversion rate is a ratio: conversions divided by users. Standard deviation calculations for raw counts do not apply directly to ratios. A naive variance estimate on a ratio metric tends to be too narrow, leading to overstated confidence and false-positive ship decisions. + +Why it matters. Many experimentation platforms quietly use the delta method (or bootstrap, or some other ratio-aware estimator) for ratio metrics. If yours does not, your confidence intervals are wrong. Wrong in the direction that matters: you ship things that look significant but are not. + +How to check. Ask your platform vendor: "What is your variance estimator for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (converted yes or no, with one row per user). If the answer is "delta method" or "bootstrap with re-sampling at the user level" or "linearization with Taylor expansion," that is correct. Other reasonable answers exist; the test is whether the platform team can articulate a ratio-aware estimator at all. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. RPU lift estimates that do not use a ratio-aware estimator tend to overstate confidence. A 5 percent reported lift with p equals 0.04 might actually be a 5 percent point estimate with no statistical significance once the variance is computed correctly. Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production. + +For deeper coverage of variance reduction (CUPED, stratified sampling, control variates), see the `experimentation-analytics` skill when it ships. + +--- + +## Network effects and two-sided markets + +The interference problem. In a two-sided marketplace (Uber, Airbnb, eBay, DoorDash, any platform with buyers and sellers), a treatment for buyers may affect sellers regardless of which group is in the test. A treatment that increases buyer demand changes seller behavior. The "control" buyers, who are competing for the same sellers, see different supply because of treatment buyers' actions. The test no longer measures the treatment effect cleanly; it measures treatment effect plus interference. + +Common pattern. Marketplace experiments where the control group is contaminated. The test reports a small effect because half the effect leaked into the control. The team underestimates the true effect, kills a winning idea, and learns the wrong lesson. + +Mitigations, none perfect. Cluster randomization assigns whole markets (cities, regions, market segments) to treatment or control rather than individual users. Eliminates within-cluster interference but reduces effective sample size by orders of magnitude. Switchback experiments alternate the entire population between treatment and control across time windows (week 1 treatment, week 2 control, week 3 treatment, etc.). Eliminates cross-user interference but requires careful temporal modeling. Geographic isolation runs the experiment in one city while keeping the rest of the network on the original behavior. Eliminates interference but is expensive and slow. + +When to call qualitative. If interference is severe and randomization cannot isolate it, the test will not tell you what you want to know. Switch to user research, longitudinal cohort analysis, or a phased rollout with careful instrumentation. The decision is "do we believe this works enough to invest in the rollout monitoring" rather than "did the lift hit significance." + +--- + +## Sequential testing and the peeking problem + +The peeking problem. If you check results every day and stop the test as soon as you see significance, your false positive rate is much higher than the nominal 5 percent. Standard statistical tests assume one analysis at the end of the test. Multiple analyses inflate alpha. + +The math. With one analysis, false positive rate is 5 percent (at alpha equals 0.05). With three analyses spread across the test, false positive rate climbs toward 14 percent. With daily peeking on a 28-day test, false positive rate can exceed 30 percent. You will see "significant" results that are not real, ship them, and watch them fail to replicate in production. + +Sequential testing methods. Most modern platforms (Statsig, Eppo, parts of PostHog, GrowthBook with mSPRT) support sequential testing that adjusts the math to allow daily peeking without inflating alpha. The methods include sequential probability ratio tests, group sequential designs, and always-valid p-values via mixture sequential probability ratio tests (mSPRT). Use them when the platform offers them. They cost some statistical power in exchange for valid mid-test inference. + +Pre-registered stopping rules. If the platform does not support sequential testing, declare the planned analysis date before the test runs. Save the pre-commitment. Do not look at results until that date. If you must look (some platforms make it hard not to), do not make decisions based on what you see. The decision happens at the pre-committed analysis date, not when the early peek looks favorable. + +The "ship early because results look great" trap. Results almost always look more dramatic on day 3 than they do at day 14. Regression to the mean kicks in. Novelty fades. The metric stabilizes. The tests that survive the full window and still look great are the ones worth shipping. The ones that "looked great early" and were shipped early are disproportionately the ones that disappointed in production. + +--- + +## Pre-commitment vs p-hacking + +The p-hacking inventory. Things people do, often unconsciously, when results do not come out the way they hoped: + +- Run additional segments until something hits significance +- Drop "outliers" until the headline result moves +- Switch the primary metric mid-flight +- Extend the test duration "just a bit longer" +- Reframe the hypothesis to match what the data showed +- Combine multiple inconclusive tests into a "directional pattern" that justifies shipping + +Each individually feels like a small judgment call. Cumulatively they destroy the discipline. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +The pre-commitment fix. Before the test runs, write down: the primary metric and how it is computed; the MDE you are powered to detect; the duration in calendar days; the segments you will analyze (if any); the decision rule that maps each possible result to a ship or kill. Save the pre-commitment somewhere with a timestamp. The PR description that ships the experiment configuration. A signed Slack message. A pinned ticket. Anywhere that makes it immutable. + +When the results come in, follow the pre-commitment. If the result was clean and you want to ship, file the launch. If the result was bad and you want to kill, kill. If the result was inconclusive, follow the inconclusive resolution path described below; do not invent new analyses. + +The "we learned so much" trap. If the test ran and produced an inconclusive result, the answer is "inconclusive." Not "we learned that the underlying mechanism is more nuanced than expected" or "we discovered a fascinating segment dynamic." Inconclusive is inconclusive. The lesson, if there is one, is for the next hypothesis, not retrofitted onto this one. + +--- + +## Reading results and making the call + +Three buckets. Clear win: ship. Clear loss: kill. Inconclusive: the hardest case. + +Inconclusive resolution paths, ranked from most acceptable to least: + +1. Ship anyway because the change is cheap and reversible (defensible only if guardrails are clean and you genuinely have no information that the change is harmful). The bar here is high; "the directional movement was favorable" is not enough. +2. Run a bigger version: more traffic, longer duration, larger MDE if the change can be made bolder. Use the inconclusive result as evidence that the original was underpowered or the effect is smaller than expected. +3. Kill the idea. The most common right answer; the hardest to do because PMs have invested in the hypothesis. +4. Iterate the hypothesis and re-test. Use the inconclusive result to refine the mechanism. The new test is a new test, not a continuation; pre-commit again. + +Bayesian thinking layer. If your prior was strong (this should obviously work, given everything we know about user behavior), an inconclusive result should still update your belief somewhat. The prior was wrong, or the effect is smaller than expected, or the implementation was too timid to capture it. If your prior was weak (we genuinely had no idea what would happen), an inconclusive result means inconclusive; the prior was already uncertain and the result did not narrow it. + +The hardest version. Positive primary metric, ambiguous guardrail. Revenue went up but support tickets ticked up. Conversion went up but session length went down. Use the pre-committed decision rule. If you did not pre-commit on the guardrail trade-off, default to "do not ship." The guardrails exist because you cared about them before you saw the result. Do not lower the bar after the fact. + +For a step-by-step results-reading checklist, see [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). + +--- + +## Common failures and fixes + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-failures.md`](references/common-failures.md). + +- "We did not have enough traffic" means the MDE was too small. Pick bigger changes worth detecting. +- "The lift disappeared after launch" means the test ran for 5 days and caught a novelty effect. Run longer next time; minimum two weeks for UI changes. +- "It worked for new users but not returning users" means the segment was post-hoc, probably noise. Ship to all or kill, do not ship to the segment. +- "The p-value crept up to 0.04 after 12 days of peeking" means the false-positive rate is much higher than nominal. Pre-commit and use sequential testing. +- "Revenue went up but retention went down" means a guardrail was violated. Do not ship. +- "We cannot replicate the result" means the original was probably noise or platform-bug. Investigate before re-running. +- "Conversion went up but only because of the bot traffic from the new ad campaign" means the result was confounded by an external event. Pause campaigns during sensitive tests, or stratify by acquisition source. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped" means you ignored your own discipline. The inconclusive bucket exists for a reason; do not let directional patterns substitute for evidence. + +--- + +## Reference files + +- [`references/hypothesis-templates.md`](references/hypothesis-templates.md). Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test, with worked examples across conversion, engagement, revenue, retention, and funnel-step metric types. +- [`references/sample-size-tables.md`](references/sample-size-tables.md). Pre-calculated sample size tables for the most common conversion-rate experiments, with how-to-use guidance and the common pitfalls in sample-size planning. +- [`references/common-failures.md`](references/common-failures.md). Fifteen anti-patterns that produce wrong shipping decisions, each with symptom, root cause, fix, and prevention. +- [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). Step-by-step checklist for reading results, the three-bucket decision matrix (win, loss, inconclusive), and the post-launch monitoring discipline. +- [`references/platform-comparison.md`](references/platform-comparison.md). Profiles of the major experimentation platforms (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon) with strengths, gotchas, and a decision matrix for choosing. +- [`references/pre-experiment-readiness-checklist.md`](references/pre-experiment-readiness-checklist.md). Ten-item go/no-go checklist run through before launch. +- [`references/post-experiment-decision-framework.md`](references/post-experiment-decision-framework.md). The moment-of-decision framework: confirm pre-commitment, apply rule mechanically, route to ship/kill/inconclusive paths, write the post-mortem within a week. + +--- + +## Closing: when in doubt + +Default conservative posture. When results are unclear, do not ship. The cost of a false negative (you did not ship a real win) is usually smaller than the cost of a false positive (you shipped something that does not actually work and now you have to maintain it forever). The maintenance cost compounds; the missed-opportunity cost does not, because you can always test again. + +The discipline of experiment design is the discipline of saying "I do not know" out loud when you do not know. Saying it is often the most consequential thing a PM does in a given week. The instinct is to pretend the result is more conclusive than it is, ship to look decisive, and absorb the failure quietly when the change does not work in production. The discipline is to say "the test was inconclusive, here is what I would change to get a real answer, here is the new test plan." Saying that is professional. Pretending otherwise is theater. + +For platform-specific patterns (which platform handles which experiment type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the operational layer below this skill (managing flags, retiring stale ones, coordinating environments), see the `feature-flagging` skill. For the analytical layer above this skill (variance reduction, Bayesian alternatives, sequential testing math), see the `experimentation-analytics` skill. diff --git a/dist/pi/.agents/skills/experiment-design/references/common-failures.md b/dist/pi/.agents/skills/experiment-design/references/common-failures.md new file mode 100644 index 0000000..ba75be0 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/common-failures.md @@ -0,0 +1,183 @@ +# Common failures and fixes + +Anti-patterns that produce confidently wrong shipping decisions, with the symptom you observe, the root cause, the fix that resolves it, and the prevention that stops it from recurring. + +--- + +## 1. The vague hypothesis + +**Symptom.** "We think the new pricing page will increase conversions." The team runs the test, the result is ambiguous, and a heated meeting follows about whether to ship. + +**Root cause.** The hypothesis lacks magnitude and mechanism. When the result comes in, there is no pre-committed bar to compare against, so the decision becomes political. + +**Fix.** Rewrite the hypothesis with the cause-effect-magnitude-mechanism format from [SKILL.md](../SKILL.md). Save it before launching. + +**Prevention.** Make hypothesis review part of the experiment kickoff. A peer reads the hypothesis and confirms all four parts are present before the test launches. + +--- + +## 2. The novelty effect ship + +**Symptom.** Test ran for 5 days, lift looked great, the team shipped, and the lift disappeared in production within two weeks. + +**Root cause.** Users notice new things and click them disproportionately during the novelty window. The early lift was novelty, not durable preference. + +**Fix.** Re-test the change with at least a two-week test window. Most novelty effects fade in 7-10 days. If the lift survives 14 days, it is likely durable. + +**Prevention.** Set minimum test duration of 14 days for any UI/UX change, regardless of how fast sample size hits. Document the rule and enforce it. + +--- + +## 3. The post-hoc segment win + +**Symptom.** Test was inconclusive overall, but "users from California who signed up via mobile on Tuesdays" had a huge lift. The team wants to ship to that segment. + +**Root cause.** Multiple comparisons. With enough segments analyzed, one will hit "significance" by chance. The California-mobile-Tuesday segment is almost certainly noise. + +**Fix.** Do not ship to the segment. Either ship to all (if guardrails hold), or kill, or re-test with the segment pre-registered as a hypothesis. + +**Prevention.** Pre-register the segments to be analyzed. Limit to three to five segments per test, each with a real prior reason to differ from the population. + +--- + +## 4. The peeking creep + +**Symptom.** P-value drifted around 0.06 for the first week, then crept to 0.04 on day 12, the team called it significant and shipped. + +**Root cause.** The platform did not use sequential testing. Daily peeking inflated the false positive rate. The "significance" on day 12 was a peeking artifact. + +**Fix.** Either use a platform with sequential testing, or pre-commit to a single end-of-test analysis. If you peeked and the test is over, treat the result as inconclusive and consider rerunning. + +**Prevention.** If your platform supports sequential testing (mSPRT, group sequential), enable it. If not, set up the test with calendar reminders for the analysis date, not before. + +--- + +## 5. The guardrail violation overlook + +**Symptom.** Primary metric (revenue) went up. Retention dropped. The team shipped because revenue was the headline metric. + +**Root cause.** Guardrails were defined but not treated as binding. When the primary metric looked favorable, the team rationalized the guardrail violation as acceptable. + +**Fix.** Do not ship. Investigate the retention drop. The change may be capturing short-term revenue at the cost of long-term value, which is a worse trade than no change at all. + +**Prevention.** Pre-commit on the guardrail trade-off. Write down explicitly: "We will not ship if retention drops by more than X." If you cannot specify the bar in advance, you do not understand the trade-off well enough to test it. + +--- + +## 6. The non-replicable result + +**Symptom.** Test reported a 5 percent lift. The team shipped. A month later the same change tested with a holdout group shows no effect. + +**Root cause.** Could be many things: original test was a false positive, platform bug, external event during the test window, contamination. Without investigation, you do not know which. + +**Fix.** Stop, investigate, find the cause. Possible findings: the metric was computed differently in the test versus production; the test exposure was lower than reported; an unrelated change confounded the result. Do not "just rerun and hope." + +**Prevention.** Schedule a post-launch holdout test for any change with a reported lift greater than 3 percent. Confirm the production behavior matches the test before declaring the win. + +--- + +## 7. The campaign confound + +**Symptom.** Test launched the same week as a major marketing campaign. Test reported a huge lift. The team shipped. The lift was the campaign's traffic mix, not the treatment. + +**Root cause.** The campaign brought a different user mix into the test population: higher-intent visitors, different geographies, different device types. Treatment and control both saw the campaign traffic, but the campaign-driven users may have responded differently to the variants than the baseline population would. + +**Fix.** Pause campaigns during sensitive tests, or stratify the analysis by acquisition source so campaign traffic is analyzed separately from baseline traffic. + +**Prevention.** Coordinate with the marketing team before launching tests. Maintain a calendar of upcoming campaigns and avoid launching experiments on the same surfaces during major pushes. + +--- + +## 8. The directional ship + +**Symptom.** Test was inconclusive. Primary metric trended up but did not hit significance. The team shipped because "the trend was directional." + +**Root cause.** Directional trend without significance is noise that happens to point in a flattering direction. Treating it as evidence is exactly the discipline failure that erodes experimentation rigor. + +**Fix.** Do not ship based on directional trends. Either run a bigger test (more traffic, longer duration), kill, or accept inconclusive as the answer. + +**Prevention.** Pre-commit to the decision rule. "Inconclusive" as a category requires acceptance, not creative reframing. + +--- + +## 9. The interaction effect blind spot + +**Symptom.** Five concurrent tests on the checkout flow. Each individually reported a small lift. Combined, total checkout conversion did not move. + +**Root cause.** Interactions between concurrent tests. The lifts did not multiply or even sum. Some may have canceled out, some may have interfered with each other. + +**Fix.** Roll back, run tests with mutex enforcement, or run them sequentially. Re-test the combination as a multivariate. + +**Prevention.** Maintain an experiment registry per surface. Before launching a new test, check which others are running on the same surface and coordinate. Use mutex when interactions are likely. + +--- + +## 10. The selection bias ship + +**Symptom.** ARPU went up. The team shipped. After launch, MAU dropped because the lowest-revenue users churned. + +**Root cause.** The treatment caused selection: lower-value users left, higher-value users stayed. ARPU went up arithmetically because the denominator shrank, not because anyone made more money. + +**Fix.** Pair ARPU primary metrics with retention or MAU guardrails. Investigate the source of the lift before shipping. + +**Prevention.** When the primary metric is a ratio, always pair with absolute count guardrails. ARPU plus revenue. Conversion rate plus conversion count. Engagement rate plus DAU. + +--- + +## 11. The internal traffic contamination + +**Symptom.** Test reported strong lift in the first week. Investigation showed half the test users were internal employees clicking around the new feature. + +**Root cause.** Internal traffic was not excluded from the test population. Employees behave differently from real users. + +**Fix.** Re-bucket the test excluding internal IPs and employee accounts. Re-analyze. + +**Prevention.** Maintain an internal-traffic exclusion list at the platform level. Apply it to all experiments by default. Audit the user counts on test launch to confirm internal traffic is excluded. + +--- + +## 12. The metric definition mismatch + +**Symptom.** Test reported a 5 percent lift in "conversion." Production analytics reported a 0.5 percent lift. The team blamed the platform. + +**Root cause.** The conversion event was defined differently in the test platform versus production analytics. Different conversion windows, different deduplication rules, different user-identity logic. + +**Fix.** Reconcile the metric definitions before re-running. Document the canonical definition and confirm both systems produce matching numbers on a known historical period. + +**Prevention.** Maintain a metric dictionary. Before adding a metric to an experimentation platform, document the canonical definition and validate against production analytics. Treat the metric definition as a versioned artifact. + +--- + +## 13. The ratio metric variance error + +**Symptom.** Test reported a "significant" lift in revenue per user with p equals 0.04. Production rollout produced no measurable change. + +**Root cause.** The platform used a naive variance estimator on a ratio metric. Confidence interval was too narrow; the "significance" was an artifact of bad math. + +**Fix.** Switch to a platform that uses a ratio-aware estimator (delta method, bootstrap). Re-run the test or confirm via holdout. + +**Prevention.** Audit your platform's variance estimator. Ask the vendor what they use for ratio metrics. If the answer is "standard t-test on proportions" for anything other than simple binary conversion, plan a workaround. + +--- + +## 14. The "we will fix it later" rollout + +**Symptom.** Test was inconclusive but engineering had already deployed the change. Rolling back was hard. The team shipped because the cost of rollback was higher than the expected cost of shipping. + +**Root cause.** The rollout was not gated on the experiment result. Engineering shipped to production before the test had concluded. + +**Fix.** Roll back if possible. If not, accept the change is shipped and instrument production carefully to confirm whether it actually works. + +**Prevention.** Gate rollouts behind experiment conclusions. Use feature flags so the change can be toggled off without a code revert. Coordinate engineering schedules with experiment timelines. + +--- + +## 15. The retroactive hypothesis + +**Symptom.** Test was set up to validate "the new homepage increases signups." Result showed signups flat but engagement up. The team rewrote the hypothesis as "the new homepage drives engagement" and shipped. + +**Root cause.** Hypothesis was changed after the result was visible. This is p-hacking even if no statistical math was changed. + +**Fix.** The original hypothesis was inconclusive on signups. Either kill, or run a new test with the engagement hypothesis pre-registered. + +**Prevention.** Pre-commit the primary metric and stick with it. If the data suggests a different metric is more interesting, treat that as the hypothesis for the next test, not a rewrite of the current one. diff --git a/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md b/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md new file mode 100644 index 0000000..18e3584 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md @@ -0,0 +1,95 @@ +# Hypothesis templates + +Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test from [SKILL.md](../SKILL.md). Each template names the right shape, shows two or three worked examples in different domains, and calls out the most common mistakes specific to that template type. + +The unifying format across all templates: replace [bracketed slots] with concrete project-specific values. If a slot reads as a vague phrase after replacement, the hypothesis is not specific enough. + +--- + +## Template 1: Conversion rate change + +**Format.** Replacing [current treatment] with [new treatment] will increase [conversion event] by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +**Worked example, e-commerce.** Replacing the multi-step shipping selector with an inline shipping summary on the cart page will increase cart-to-purchase conversion by 6 percent (currently 14.2 percent, target 15.1 percent) by reducing the cognitive load at the moment users are deciding whether to complete checkout. + +**Worked example, SaaS.** Replacing the three-tier pricing comparison with a single recommended tier on the pricing page will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe. + +**Worked example, marketplace.** Replacing the "browse all categories" landing page with a personalized recommendation grid will increase landing-to-listing-click conversion by 12 percent (currently 18 percent, target 20.2 percent) by surfacing relevant inventory before users have to specify intent. + +**Common mistakes specific to this template.** +- Naming the metric as "conversions" without specifying the conversion event. "Conversion" alone is ambiguous; cart-to-purchase, signup-to-paid, and landing-to-listing-click are different metrics with different baselines and different relevant timescales. +- Stating relative lift without absolute. "10 percent lift" sounds bigger than "1 percent absolute lift on a 10 percent baseline" but is the same thing; state both so the reader knows what is being claimed. +- Skipping the mechanism. "Will increase conversion by 8 percent" is a target, not a hypothesis. The why is what makes it falsifiable. + +--- + +## Template 2: Engagement metric change (DAU, sessions, time-on-task) + +**Format.** Adding [new feature or affordance] will increase [engagement metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, content product.** Adding a "save for later" button to article cards will increase weekly active users by 5 percent (currently 1.2 million, target 1.26 million) by giving users a reason to return to articles they have started reading. + +**Worked example, productivity tool.** Adding inline comments on document blocks will increase sessions per week per active team by 15 percent (currently 4.2, target 4.8) by enabling asynchronous collaboration that previously required separate communication channels. + +**Common mistakes specific to this template.** +- Engagement metrics are not always good. A feature that increases sessions but decreases task completion is making the product worse, not better. Pair engagement primary metrics with task-completion guardrails. +- "Time on task" is ambiguous. More time can mean engagement or confusion. Specify whether longer or shorter is the desired direction and why. +- Treating engagement lift as a leading indicator without evidence that it is. Increased DAU does not always lead to increased revenue; sometimes it lags it, sometimes it has no relationship. + +--- + +## Template 3: Revenue metric change (ARPU, AOV, RPU) + +**Format.** Implementing [new pricing or merchandising change] will increase [revenue metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, subscription product.** Adding an annual prepay option at 10 percent discount will increase average revenue per user by 4 percent (currently $87, target $90.50) by shifting price-sensitive users from monthly to annual billing, which has lower churn. + +**Worked example, e-commerce.** Adding a "frequently bought together" bundle on product detail pages will increase average order value by 8 percent (currently $42, target $45.40) by surfacing relevant add-on items at the moment of purchase decision. + +**Common mistakes specific to this template.** +- Revenue is a ratio metric (revenue divided by users or orders). Naive variance estimators understate the variance and overstate confidence. Confirm your platform uses the delta method or an equivalent ratio-aware estimator. +- ARPU lifts can come from selection effects: if the treatment moves the lowest-revenue users away (they churn), ARPU goes up without anyone making more money. Pair ARPU primary metrics with retention guardrails. +- Revenue lifts can be driven by a small number of high-value users. Confidence intervals are wide. Run longer than you think you need to. + +--- + +## Template 4: Retention metric change + +**Format.** Changing [interaction or feature] will increase [retention metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, mobile app.** Changing the day-3 push notification copy from generic to personalized recommendations will increase day-7 retention by 3 percent (currently 38 percent, target 39.1 percent) by reminding users of specific value they can return to. + +**Worked example, SaaS onboarding.** Replacing the static onboarding checklist with a guided in-product tour will increase day-30 active retention by 5 percent (currently 22 percent, target 23.1 percent) by getting more users to the activation event during their first session. + +**Common mistakes specific to this template.** +- Retention takes time to measure. A test of day-30 retention requires at least 30 days of treatment exposure plus the test duration. Plan accordingly. +- Day-N retention is a moving definition. Day-7 active means different things in different products; specify the activity that defines "active" before running. +- Retention lifts often shrink over time. A treatment that improves day-7 retention may have no effect on day-90 retention. Decide which timescale matters for the business and measure that, not just the convenient short one. + +--- + +## Template 5: Funnel-step abandonment reduction + +**Format.** Modifying [specific funnel step] will reduce abandonment at that step by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +**Worked example, signup funnel.** Removing the phone number field from the signup form will reduce signup-form abandonment by 20 percent (currently 35 percent, target 28 percent) by removing a high-friction field that is not required for account creation. + +**Worked example, checkout funnel.** Adding guest checkout above the account creation prompt will reduce account-creation-step abandonment by 25 percent (currently 18 percent, target 13.5 percent) by giving purchase-intent users a path that does not require account creation. + +**Common mistakes specific to this template.** +- Reducing abandonment at one step often shifts abandonment to the next step. The right metric is downstream conversion, not just step-level abandonment. Pair step-level primary metrics with full-funnel guardrails. +- Signup abandonment can be measured noisily; users who abandon the form may return later. Define the conversion window (5 minutes, 24 hours, 7 days) before testing. +- Reducing friction is not always good. A signup form that is too short produces low-quality signups: trial users who never return, fake accounts, support load. Pair friction-reduction tests with downstream-quality guardrails. + +--- + +## Anti-templates: hypotheses that should be rejected + +Examples of hypotheses that fail the format and should be rewritten before launching: + +- "We think the new pricing page will increase conversions." Missing magnitude, mechanism, and a specific conversion event. Rewrite using Template 1. +- "Users will love the redesign." Missing everything. Not testable. Pick a metric. +- "The new flow is faster, so more people will complete it." Missing baseline, target, and a defined "complete" event. The mechanism (faster) is plausible but not specific. +- "We want to see if dark mode improves engagement." Vague metric (engagement), no magnitude, and dark mode is binary not a multivariate. Pick a specific engagement metric and pre-register the segments where dark mode users are likely to differ from light-mode users (mobile evening sessions, for example). + +If your draft hypothesis sounds like one of the anti-templates, rewrite it using one of the five templates above before running the test. diff --git a/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md b/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md new file mode 100644 index 0000000..f435e29 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md @@ -0,0 +1,133 @@ +# Platform comparison + +A practical guide to choosing an experimentation platform. Each platform has a distinct profile (statistical defaults, primary audience, integration model, pricing shape). Picking well saves quarters of friction; picking badly creates ongoing pain. + +This reference assumes the team is in the position of choosing or reconsidering. For platform-specific MCP commands, auth models, and example prompts, consult the chosen platform's official documentation. + +--- + +## Statsig + +**Profile.** Modern feature management plus experimentation platform. Built CUPED-first, holdouts as a first-class concept, warehouse-native with optional event ingestion. Fast-growing customer base including OpenAI, Notion, Brex, Whatnot. + +**Strengths.** CUPED variance reduction is the default, not an opt-in. Strong holdout analysis with built-in long-term measurement. Mature MCP exposing full CRUD across experiments, gates, dynamic configs, layers, and segments. Setup guides for ChatGPT, Cursor, Claude Code, Codex. + +**Best for.** Fast-growing companies that want one platform for both feature flags and experiments. Engineering-led teams comfortable with code-first configuration. Teams that need to run many concurrent experiments and care about variance reduction. + +**Gotchas.** Pricing scales with events, which can compound for high-traffic products. The breadth of the MCP can crowd context windows on smaller models; scoping helps. Best-in-class statistical defaults are nice but require the team to actually understand them. + +**MCP setup.** Statsig publishes setup guides for ChatGPT, Cursor, Claude Code, and Codex; consult the Statsig docs for the current MCP server URL and auth model. + +--- + +## PostHog + +**Profile.** Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics in one platform. Self-host or cloud. Customer base skews toward PLG products and developer tools. + +**Strengths.** Combines analytics and experimentation in one platform, eliminating the metric-definition mismatch between systems. Full event-level data in the warehouse. 200+ MCP tools across the entire product, the largest surface of any vendor in this list. + +**Best for.** Product-led growth products that benefit from full-funnel context across analytics, experiments, and session replays. Teams that want one platform for everything rather than a stack of specialized tools. + +**Gotchas.** The breadth of the MCP requires scoping with `?features=` query parameters; without scoping, the agent gets 200+ tools and tool selection accuracy degrades on smaller models. Self-host adds operational complexity. Some experiment features lag behind specialized platforms. + +**MCP setup.** PostHog's MCP scopes via `?features=` query parameters; without scoping, the agent gets 200+ tools and tool-selection accuracy degrades on smaller models. Consult the PostHog docs for current scoping syntax. + +--- + +## GrowthBook + +**Profile.** Open-source warehouse-native experimentation. Runs SQL on the team's existing data warehouse. Customer base skews data-mature: Dropbox, Khan Academy, Mistral. Claims the first open-source production MCP for experimentation. + +**Strengths.** Data stays in the team's warehouse; no event ingestion to a vendor. Strong cost control because the math runs on infrastructure the team already pays for. 100 percent open source under MIT, with self-host or cloud options. + +**Best for.** Data-mature teams that already own a warehouse (Snowflake, BigQuery, Redshift, ClickHouse, Postgres). Regulated industries where data residency matters. Teams that want full control over the statistical math. + +**Gotchas.** More setup overhead than hosted platforms. Requires SQL fluency for advanced analyses. Smaller community than the bigger commercial vendors. + +**MCP setup.** GrowthBook ships an open-source MCP for self-host or cloud; consult the GrowthBook docs for the current binary and auth model. + +--- + +## Optimizely + +**Profile.** Long-time enterprise leader in personalization and experimentation. Web Experimentation and Feature Experimentation as separate but linked products. Customer base skews enterprise marketing and e-commerce. + +**Strengths.** Deep targeting, audience management, multivariate testing. Visual editor accessible to non-technical users (marketers can build variants without engineering). Mature personalization and recommendation engine. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth. + +**Best for.** Marketing-led organizations where non-technical teams need to author variants. Enterprises with deep personalization needs. E-commerce sites with established A/B testing programs. + +**Gotchas.** Expensive at the enterprise tier. Visual editor produces JS that ships at runtime, which can affect page performance. Less ergonomic for engineering-led teams that prefer code-first configuration. + +**MCP setup.** Optimizely's hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth; consult Optimizely docs for the current server URL. + +--- + +## Amplitude + +**Profile.** Behavioral analytics platform with experiments and feature flags layered on top. Customer base skews product analytics teams that adopted Amplitude before adding experimentation. + +**Strengths.** Deep cohort analysis and behavioral segmentation. Native ChatGPT connector. Hosted MCP available to all customers including the free tier. Integrates tightly with the analytics layer that PMs already use. + +**Best for.** Teams that already use Amplitude for analytics and want to add experiments without introducing a new platform. Product analytics teams that need behavioral cohort segmentation as part of the experiment workflow. + +**Gotchas.** Experiments are a secondary feature, not the platform's center of gravity. Variance reduction options are more limited than dedicated experimentation platforms. Beta status of the MCP means the API surface may evolve. + +**MCP setup.** Amplitude's hosted MCP is available to all customers including the free tier and ships a native ChatGPT connector; consult the Amplitude docs for the current setup steps. + +--- + +## Eppo + +**Profile.** Warehouse-native experimentation platform with strong statistical defaults. Customer base skews data-team-led organizations: Twitch, DraftKings, Perplexity. Best-in-class statistical rigor. + +**Strengths.** Best-in-class statistical defaults: variance reduction, sequential testing, contextual bandits, lifecycle experimentation. Warehouse-native means data stays in the team's stack. Strong explainability features for tracing reported lifts back to underlying SQL. + +**Best for.** Data-team-led organizations where data scientists own the experimentation discipline. Companies with mature warehouses and strict statistical rigor requirements. Teams running contextual bandits or other advanced experiment designs. + +**Gotchas.** No first-party MCP server as of May 2026. Programmatic access is REST API only; teams that want agentic workflows today need to build a custom MCP adapter or wait. Pricing reflects the data-science-focused product positioning. + +**MCP setup.** No first-party MCP server as of mid-2026; teams that want agentic workflows today either build a custom MCP adapter on top of Eppo's REST API or wait for the official server. Consult Eppo's docs and roadmap for current status. + +--- + +## Kameleoon + +**Profile.** AI-driven personalization platform with a specialized MCP focused on the convert-and-promote workflow. The MCP pulls raw variation code from winning experiments and helps refactor it into production-ready React components. + +**Strengths.** Sharp, narrow MCP (seven specialized tools) focused on a specific job: take a winning marketing-site variation and ship it as permanent product code. Hosted MCP via OAuth. Avoids the broad-CRUD complexity that crowds context windows on other platforms. + +**Best for.** Teams that test on the marketing site and need to convert wins into permanent React components. Hybrid marketing-and-product setups where the experiment lives in JS/CSS and the win needs to ship as a product feature. + +**Gotchas.** The narrow MCP scope is intentional but limits broader CRUD work. For everyday flag management, teams use the Kameleoon dashboard or REST API rather than the MCP. + +**MCP setup.** Kameleoon's hosted MCP via OAuth ships a narrow seven-tool surface focused on the convert-and-promote workflow; consult Kameleoon's docs for the current server URL. + +--- + +## Decision matrix + +A short matrix for the first-pass platform decision. Tradeoffs are oversimplified; verify against the team's specific constraints. + +| Situation | Pick | +|---|---| +| Pure SaaS, fast-growing, want one platform for flags + experiments | Statsig or PostHog | +| Open-source preference, warehouse-native | GrowthBook or Eppo | +| Enterprise, marketing-led, non-technical variant authoring | Optimizely | +| Already using Amplitude for analytics, want experiments without new platform | Amplitude | +| Convert marketing-site experiment wins into permanent product code | Kameleoon | +| Data-team-led, statistical rigor is non-negotiable, can wait for MCP | Eppo | +| Open-source AND warehouse-native AND need MCP today | GrowthBook | + +Beyond these defaults, the right choice depends on the team's existing stack, the experimentation maturity, and the budget. The "best" platform for one team is wrong for another; pick based on the team's actual constraints, not the platform's marketing. + +--- + +## Switching costs + +Once a team has adopted a platform, switching is expensive. Existing experiments need to be re-run on the new platform. The metric definitions need to be reconciled. The team needs to retrain on a new tool. Plan accordingly: + +- **Easy switches.** Visual A/B testing tools that ship JS at runtime (Optimizely Web, AB Tasty, VWO classic). Switching is mostly tag-replacement. +- **Medium switches.** Warehouse-native to warehouse-native (GrowthBook to Eppo, or vice versa). The data layer is shared; the configuration migrates. +- **Hard switches.** Anything to or from event-ingestion platforms (Statsig, Amplitude). The historical event data does not transfer cleanly; the team starts fresh on metric history. + +If the team is choosing now and might need to switch later, lean toward warehouse-native options. Data ownership is the most expensive thing to switch. diff --git a/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md b/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md new file mode 100644 index 0000000..6354a66 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md @@ -0,0 +1,91 @@ +# Post-experiment decision framework + +The moment-of-decision framework for what to do when a test ends. Each step builds on the prior; do not skip ahead. The discipline at this stage is what separates teams that learn from experiments from teams that confirm their priors. + +--- + +## Step 1: Confirm pre-commitment was followed + +Before reading the results, pull up the pre-commitment document. Verify: +- The test ran for the pre-committed duration (not stopped early, not extended). +- The primary metric was the one pre-committed (not silently swapped). +- The segments analyzed were the ones pre-committed (not new ones discovered post-hoc). +- The guardrails are the ones pre-committed (not narrowed or widened after the fact). + +If any item failed the check, the result is compromised. Treat as inconclusive at minimum; consider re-running. + +--- + +## Step 2: Apply the pre-committed decision rule mechanically + +The pre-commitment mapped each possible result to a ship-or-kill decision. Find the bucket the result falls into. Apply the rule. + +Resist the temptation to add new analysis "just to be sure." If new analysis is required to make a decision, the pre-commitment was inadequate; the lesson is for next time, not a license to dig until the answer feels right. + +The mechanical-application discipline is the most important habit at this step. Teams that deliberate about whether to follow their own pre-commitment have already lost the discipline. Apply the rule. Document any second-guessing as feedback for the next pre-commitment. + +--- + +## Step 3a: If decision is "ship" + +1. File the launch ticket. Include: the test ID, the primary metric lift, confidence interval, guardrails status, segments status, and a link to the pre-commitment. +2. Schedule post-launch monitoring at +7 days, +30 days, +60 days. Calendar reminders, not "I'll check it later." +3. Confirm the launch removes the experiment infrastructure (the flag, the variant code paths) on the schedule the team has for stale-flag cleanup. See the `feature-flagging` skill for the cleanup discipline. +4. Post a brief launch summary to the team's experiment log. + +--- + +## Step 3b: If decision is "kill" + +1. Document the learning. What did the team predict? What happened? What is the most likely reason for the gap? +2. Propose a follow-up hypothesis if applicable. The hypothesis can be "we should not test this idea again" if the test was definitive in the negative direction. It can be "let's iterate the mechanism" if the test was inconclusive and the team has a clearer story now. +3. Archive the experiment infrastructure: remove the flag, clean up the variant code, remove instrumentation that was specific to this test. +4. Post the kill summary to the team's experiment log. Killed experiments are as valuable as winning experiments; they prevent the team from repeating the mistake. + +--- + +## Step 3c: If decision is "inconclusive" + +The inconclusive path is the hardest. The temptation is to ship anyway because the team has invested in the hypothesis. Resist it. + +Run through the resolution paths in order: + +1. **Was the MDE realistic?** If the test was underpowered (you needed a 5 percent lift to be detectable, and you got a 2 percent point estimate with a confidence interval crossing zero), the right answer may be to redesign the test with a bolder change and rerun. Do not extend the existing test; that produces a peeking artifact. Plan a new test, pre-commit, run. +2. **Was the test contaminated?** If a confounder (campaign, outage, instrumentation bug) is identifiable, fix and rerun. Do not handwave the confounder. +3. **Is the change cheap and reversible?** If the change is small, easy to maintain, and easy to roll back, shipping despite an inconclusive result is defensible. The bar is high; the change has to be genuinely cheap, and the guardrails have to be clean. If the change is expensive to maintain (additional UI complexity, additional code paths, additional analytics surface), ship is the wrong call. +4. **Otherwise: kill, document, move on.** The discipline of accepting inconclusive results as inconclusive is what makes experimentation a learning system. Treating every inconclusive result as a "we just need more data" justification destroys the discipline. + +--- + +## Step 4: Write the post-mortem within one week + +Regardless of the decision, write a short post-mortem within one week. The post-mortem covers: + +- The hypothesis (cause, effect, magnitude, mechanism) +- The pre-commitment (primary metric, MDE, duration, decision rule) +- The result (lift, CI, guardrails, segments) +- The decision (ship / kill / inconclusive) +- The action taken (launch, archive, redesign) +- The learning (what would the team do differently next time) + +Keep post-mortems short: half a page is plenty. Long post-mortems do not get written; short ones do. The compounding value of a written experiment log over years is enormous; the compounding value of a vague memory of past tests is zero. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. + +Schedule a review at: + +- **Day 7.** Production metric matches the experiment lift within reasonable tolerance. If it does not, investigate before declaring the launch successful. +- **Day 14.** Lift has not decayed (which would suggest novelty effect that the test underweighted) or amplified (which would suggest the change interacts with something the test could not capture). +- **Day 30.** Long-term metrics (retention, downstream conversion, support load) are not eroding. The change continues to deliver value, not just an initial bump. + +If the production behavior diverges materially from the test behavior at any review: + +1. Quantify the divergence. Is it within statistical noise, or is it a real effect? +2. Investigate the cause. Common ones: novelty wore off, segment distribution shifted, instrumentation bug, interaction with another concurrent change. +3. Decide: roll back, hot-fix, or accept and document. Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. + +The 30-day rule prevents the "we shipped, it worked, then it stopped working but nobody noticed" failure mode. Most teams skip post-launch monitoring; the ones that do it consistently learn faster. diff --git a/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md b/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md new file mode 100644 index 0000000..5a0e44a --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md @@ -0,0 +1,108 @@ +# Pre-experiment readiness checklist + +A go/no-go decision checklist to run through before launching any experiment. If any item is "no," delay the launch until it is "yes." Running an experiment without these in place produces results that cannot be defended, decisions that get second-guessed, and a long-term erosion of trust in the experimentation discipline. + +The checklist takes ten to fifteen minutes per experiment. The cost of skipping it is much higher. + +--- + +## 1. Hypothesis written in cause-effect-magnitude-mechanism format + +The hypothesis names: what change is being made (cause), what metric will move (effect), how much you expect it to move with what baseline and target (magnitude), and why you expect this change to produce this effect (mechanism). + +If the draft hypothesis is missing any of the four parts, rewrite using one of the templates from `hypothesis-templates.md` before launch. + +--- + +## 2. Primary metric defined with success threshold + +Exactly one primary metric. Specified with the same precision the platform's metric configuration requires (event name, deduplication window, user identity logic). Success threshold pre-committed: the lift you would consider sufficient to ship. + +If multiple metrics feel "primary," collapse to one and demote the others to guardrails. + +--- + +## 3. Guardrails defined (3 to 5) + +Three to five guardrail metrics that must not break: revenue, retention, support tickets, page load time, error rate, satisfaction scores. Each with a tolerance threshold pre-committed. + +Avoid: more than five guardrails (creates analysis paralysis), or zero guardrails (the test cannot detect collateral damage), or vague guardrails like "user happiness" (not measurable). + +--- + +## 4. Sample size calculated for chosen MDE + +The required sample size for the chosen minimum detectable effect, at standard alpha (0.05) and power (0.80), through your platform's calculator or via a stats library. Documented in the pre-commitment. + +If the math says "you need 200,000 users to detect this lift and you have 5,000 a week," accept a larger MDE or do not run the test. Do not run an underpowered test and hope for the best. + +--- + +## 5. Duration committed (longer of sample-size-hit and full weekly cycle) + +Calendar duration committed in advance. The longer of: time to hit the calculated sample size at expected daily traffic, or one full weekly cycle (typically 7 days). UI/UX changes get a 14-day minimum regardless. + +If the duration is "we will see how long it takes," that is not a duration. Pick a date. + +--- + +## 6. Segments pre-registered (if any) + +If you plan to analyze segment-level results, name the segments before launch. Three to five maximum, each with a real prior reason to expect different behavior in that segment. + +If you do not plan to analyze segments, write that down too. The pre-commitment to "no segment analysis" is itself a defense against post-hoc segment mining. + +--- + +## 7. Decision rule pre-committed (saved with timestamp) + +Map each possible result to a decision: +- Result above target threshold + guardrails clean: ship +- Result below MDE: kill +- Result inconclusive (point above zero, CI crosses zero): default to do not ship; document next-step options +- Guardrail violation: do not ship regardless of primary + +Save the decision rule somewhere immutable: the PR description, a pinned ticket, a signed Slack message, anywhere with a timestamp. + +--- + +## 8. No conflicting concurrent experiments on the same surface + +Check the experiment registry for what else is running on the same surface (checkout flow, signup form, pricing page). If there are interactions, set up mutex enforcement so users in this test are not also in the others. + +If you cannot enforce mutex (sample size constraints), document the overlap and accept the interpretability cost. Do not pretend there is no overlap. + +--- + +## 9. Instrumentation tested with a small canary + +Before launching to the full population, expose a small canary group (5 to 10 percent) and confirm: +- Treatment users actually see the treatment +- Events fire correctly for both groups +- The platform reports the right exposure counts +- Internal traffic is excluded +- The metric definitions match between the platform and production analytics + +Catching instrumentation bugs in canary saves a wasted full test run. + +--- + +## 10. Stakeholders aligned on what each outcome means + +The PM, the engineering lead, the design lead, and any other decision-maker have all agreed: if the test wins, we ship; if it loses, we kill; if it is inconclusive, we follow the inconclusive path documented in the decision rule. + +If a stakeholder is going to dispute the result regardless of what it shows, the experiment is theater. Resolve the strategic question first; run the experiment only if the result genuinely changes the decision. + +--- + +## Decision + +If all ten items are "yes," launch. + +If any item is "no": +- Items 1, 2, 3 (hypothesis, metric, guardrails): blocking. Fix before launch. +- Items 4, 5, 7 (math, duration, decision rule): blocking. Fix before launch. +- Items 6, 8, 9 (segments, mutex, canary): worth fixing but launch can proceed if the fix is impractical and the team accepts the risk. +- Item 10 (stakeholder alignment): blocking. An experiment that cannot change the decision is theater. + +The cost of delaying a launch by a day to fix a checklist item is small. The cost of running a test that produces an indefensible result is much higher. diff --git a/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md b/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md new file mode 100644 index 0000000..32d3006 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md @@ -0,0 +1,112 @@ +# Results interpretation checklist + +A step-by-step checklist for reading experiment results and arriving at a defensible decision. Run through it in order. Do not skip steps because the result "looks obvious"; the obvious-looking results are often the ones that fail in production. + +--- + +## Step 1: Did the test run for the pre-committed duration? + +**What to look for.** The test ended on the date pre-committed at launch, with the planned analysis happening on that date. + +**Red flags.** The test was stopped early because results "looked great." The test was extended past the pre-commitment because results "had not stabilized." The test ran for an arbitrary duration not tied to the pre-commitment. + +**When to escalate.** If the duration was changed after launch without documented rationale, the result is compromised. Treat as inconclusive and consider re-running. + +--- + +## Step 2: Did all guardrails stay within tolerance? + +**What to look for.** Each pre-defined guardrail (revenue, retention, support tickets, page load time, error rate) within its acceptable range. Confidence intervals around guardrail metrics that exclude the threshold of concern. + +**Red flags.** A guardrail moved in the wrong direction even if the change was not "significant." Wide confidence intervals on guardrails (the test was underpowered for the guardrail). A guardrail you did not pre-define being raised post-hoc. + +**When to escalate.** A guardrail violation should be treated as binding. The fix is "do not ship," not "the primary metric was good enough to outweigh the guardrail." If the guardrail was poorly chosen, that is a lesson for next time, not a license to ignore it on this test. + +--- + +## Step 3: Did the primary metric move beyond the MDE? + +**What to look for.** The point estimate of the primary metric exceeds the pre-committed minimum detectable effect, and the confidence interval excludes zero (or excludes the no-effect threshold for one-sided tests). + +**Red flags.** Point estimate is above MDE but the confidence interval crosses zero. The "significance" comes from a peeking artifact (interim analysis that became the headline). The lift comes from a small number of outlier users. + +**When to escalate.** If the primary metric is significant but the lift is below MDE, the test was overpowered for the question; the result is technically real but practically too small to matter. Do not ship a 0.3 percent lift just because p equals 0.001. + +--- + +## Step 4: Was the confidence interval clean? + +**What to look for.** A confidence interval around the lift estimate that is well-bounded and not crossing zero. Symmetric (or appropriately skewed for the metric type). + +**Red flags.** Very wide CI (test was underpowered). Skewed CI hinting at distributional weirdness (a few outliers drove the result). CI computed without ratio-aware variance for ratio metrics. + +**When to escalate.** If the CI is wide enough that the practical lift could be anywhere from "not worth shipping" to "amazing," the test does not support a confident ship decision. Run longer or accept inconclusive. + +--- + +## Step 5: Are the results consistent across pre-registered segments? + +**What to look for.** The pre-registered segments show effects in the same direction as the overall result. Magnitude can vary; direction should not flip. + +**Red flags.** Some segments show effects opposite to the overall result. The overall lift comes from one segment and the rest are flat or negative. + +**When to escalate.** If one segment is driving the entire effect and others are negative, the right ship decision is "ship to the segment where it works" only if the targeting infrastructure exists and is worth the maintenance cost. More often the right answer is to redesign the change so it works for the whole population. + +Reminder: this step covers PRE-REGISTERED segments only. Post-hoc segments are noise mining; do not re-analyze the data through new segments looking for an interpretation. + +--- + +## Step 6: Did any external events potentially confound the results? + +**What to look for.** A timeline of events during the test window: marketing campaigns, product launches, outages, news cycles, holidays, seasonality shifts. + +**Red flags.** A campaign launched mid-test that brought a different user mix. A product release mid-test that changed user behavior. An outage during the test that affected one variant differently from the other. + +**When to escalate.** If a confounder is identified, isolate it. Stratify the analysis by acquisition source (excludes campaign-driven users), or by date (excludes the outage day), or rerun. Do not handwave the confounder; either fix it or accept that the result is tainted. + +--- + +## Step 7: Is the magnitude practically significant, not just statistically significant? + +**What to look for.** The lift is large enough to matter for the business. A 0.3 percent absolute lift on a 30 percent baseline is statistically significant with enough sample but may not justify the engineering cost of maintaining the change. + +**Red flags.** "Statistically significant" being used as the only justification. No conversation about whether the lift is large enough to be worth the implementation, maintenance, and complexity cost. + +**When to escalate.** If the magnitude is small, ask: "Is this worth the code surface area, the testing surface area, and the cognitive load on the team?" Often the answer is no. Do not ship marginal lifts unless the change is also cheap to maintain. + +--- + +## Step 8: Does the decision match the pre-committed rule? + +**What to look for.** The pre-commitment document mapped each possible result to a ship-or-kill decision. The result fits clearly into one of those buckets. + +**Red flags.** The result does not fit cleanly. The team is debating which bucket applies. Someone is proposing a new analytical knob to clarify the bucket. + +**When to escalate.** If the result is genuinely ambiguous, default to "do not ship" and document why. Inconclusive is a valid outcome; treating it as one is the discipline. + +--- + +## Decision matrix + +After running through the checklist, the result fits one of three buckets: + +| Bucket | Conditions | Action | +|---|---|---| +| Clear win | Primary moved past MDE, CI excludes zero, guardrails clean, segments consistent, no confounders | Ship. File launch. Schedule post-launch monitoring at +30 and +60 days. | +| Clear loss | Primary moved against expected direction with significance, OR guardrail violated | Kill. Document the learning. Propose follow-up hypothesis if applicable. | +| Inconclusive | Anything else | Default to do not ship. Run a bigger version, kill, or iterate the hypothesis. | + +The inconclusive bucket is the most common and the hardest. The discipline is to recognize it and resist the pull to ship anyway. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. Schedule a review at day 7, day 14, and day 30. + +What to check at each review: +- Day 7: Production metric matches the experiment lift within reasonable tolerance. +- Day 14: Lift has not decayed (novelty effect) or amplified (the change interacts with something the test could not capture). +- Day 30: Long-term metrics (retention, downstream conversion) are not eroding. + +If the production behavior diverges materially from the test behavior, the right call is to roll back and investigate, not to "wait and see." Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. diff --git a/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md b/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md new file mode 100644 index 0000000..5a74eea --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md @@ -0,0 +1,88 @@ +# Sample size tables + +Pre-calculated sample size tables for the most common experimentation scenarios. These tables are starting points, not substitutes for running the math against your specific traffic and metric. The math depends on the variance of the metric, the desired power, the alpha threshold, and the test design (one-sided, two-sided, sequential). + +Use these tables to: +- Sanity-check a sample size estimate from your platform's calculator +- Decide whether the planned test is feasible given your traffic +- Choose an MDE that is realistic for your traffic level + +For exact figures, run the math through your platform's calculator (most experimentation platforms expose one) or use a stats library (`scipy.stats`, R's `pwr` package, or an online calculator). + +--- + +## How to use these tables + +Each table assumes: +- Two-sided test (the standard default for PM experiments) +- Alpha equals 0.05 (5 percent false positive rate) +- Power equals 0.80 (80 percent chance of detecting an effect that is really there) +- Equal group sizes (50/50 split) + +Total sample size is the sum across both groups. Per-group sample is half the total. + +If you change any of those assumptions, multiply by the indicated factor: +- Power 0.90 instead of 0.80: multiply sample size by ~1.34 +- Alpha 0.01 instead of 0.05: multiply sample size by ~1.49 +- One-sided test: multiply by ~0.79 + +Worked example for using Table 1: a product has a baseline conversion rate of 10 percent and wants to detect a 1 percent absolute lift (target 11 percent). Total sample size required is roughly 31,400 users. With 1,000 daily new users in the test population, the test needs about 31 days plus one full weekly cycle. If you can only run it for 14 days, the MDE you can detect at this traffic is closer to 1.5 percent absolute. Pick the change you can detect; do not run an underpowered test. + +--- + +## Table 1: Conversion rate experiments + +Total sample size required (across both groups) for a two-sided test, alpha 0.05, power 0.80. + +| Baseline rate | MDE 1% abs | MDE 2% abs | MDE 5% abs | MDE 10% abs | +|---|---|---|---|---| +| 5% | 14,800 | 4,400 | 1,000 | 360 | +| 10% | 31,400 | 8,400 | 1,700 | 540 | +| 20% | 51,800 | 13,400 | 2,500 | 720 | +| 30% | 65,600 | 16,600 | 3,000 | 800 | +| 50% | 78,400 | 19,600 | 3,200 | 800 | + +**Reading the table.** A product with 30 percent baseline conversion that wants to detect a 2 percent absolute lift (target 32 percent) needs ~16,600 users total, ~8,300 per group. Numbers are approximate and rounded. + +**Choosing an MDE that matches traffic.** If you have 5,000 weekly users in the test population: +- One week of traffic supports detection of ~5 percent absolute lift on a 30 percent baseline (3,000 users, MDE 5 percent matches) +- Two weeks supports ~3 percent absolute lift +- Four weeks supports ~2 percent absolute lift +- Six weeks supports ~1.5 percent absolute lift + +Beyond six weeks the test runs into seasonality and product-evolution problems described in [SKILL.md](../SKILL.md). If the change you want to test would only produce a 1 percent absolute lift and your traffic supports 5 percent MDE in a reasonable window, the test is not worth running. Pick a bigger change. + +--- + +## Table 2: Mean comparison experiments (continuous metrics) + +For continuous metrics like time-on-task, session length, page views per session, the math depends on the metric's standard deviation, which varies by product. The table below shows sample sizes assuming a coefficient of variation (standard deviation divided by mean) of 1.0, which is typical for engagement metrics. + +| Baseline mean | MDE 5% rel | MDE 10% rel | MDE 20% rel | +|---|---|---|---| +| Any (CoV ~1.0) | 12,600 | 3,200 | 800 | +| Any (CoV ~2.0) | 50,400 | 12,600 | 3,200 | + +For revenue metrics the CoV is often higher (2.0 to 3.0) because revenue is concentrated in a small fraction of users. Run your variance through the platform calculator before committing to a sample size; the table is illustrative, not authoritative. + +--- + +## Common pitfalls in sample size planning + +- **Forgetting to count exposure, not allocation.** If 1,000 users see the experiment per day but only 200 reach the surface where the variant is rendered, your effective sample is 200 per day. Use exposure counts, not bucketing counts. +- **Treating session-level and user-level differently.** Some metrics are evaluated per session (page views per session), others per user (day-7 retention). Sample size requirements differ. Specify which level the metric is evaluated at and use the matching count. +- **Forgetting variance reduction.** Methods like CUPED, stratified sampling, and control variates can reduce required sample size by 30 to 50 percent for the same power. If your platform supports them, use them. Sample size tables ignoring variance reduction overstate what you actually need. +- **Underestimating the weekly cycle requirement.** A test that hits sample size in three days still needs to run a full week to capture cycle effects. Sample size hit is necessary but not sufficient. +- **Assuming traffic is stable.** If a marketing campaign launches mid-test, the user mix changes and the test may no longer be a clean comparison. Coordinate with marketing before launching tests on user-acquisition-sensitive surfaces. + +--- + +## When the math says "you cannot detect this" + +Sometimes the table reads "you need 200,000 users to detect this lift and you have 5,000 a week." Three options: + +1. **Accept a larger MDE.** Pick a bigger change worth detecting. A 3 percent absolute lift may be detectable in two weeks; a 0.3 percent lift may take a year. Test the bigger change. +2. **Find a more sensitive metric.** Sometimes the metric is the constraint, not the change. Switching from "purchases" to "add-to-cart" gives you a higher-frequency event with more sample. The trade-off is that ATC is less directly tied to revenue; pair the more-sensitive primary with a revenue guardrail. +3. **Skip the test.** If the change is small but cheap and reversible, ship without testing. If it is small and expensive to maintain, do not ship. Running an underpowered test produces noise dressed up as evidence; that is worse than no test. + +The discipline is to refuse to run tests that cannot answer the question. An underpowered test is not "better than nothing"; it is worse than nothing because it produces a result that feels meaningful but is not. diff --git a/dist/pi/.agents/skills/experimentation-analytics/SKILL.md b/dist/pi/.agents/skills/experimentation-analytics/SKILL.md new file mode 100644 index 0000000..eb34627 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/SKILL.md @@ -0,0 +1,333 @@ +--- +name: experimentation-analytics +description: How to read experiment results without fooling yourself. Confidence intervals, p-values, multiple testing, sequential testing, CUPED, heterogeneous treatment effects, ratio metrics, network effects, dashboard reconciliation, and the interpretation failures that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Read result panels without fooling yourself: confidence intervals, p-values, multiple testing, sequential testing, CUPED, ratio metrics, network effects, dashboard reconciliation" +display_order: 6 +--- + +# Experimentation Analytics + +A data-team-mentor's playbook for interpreting experiment results without fooling yourself. + +The result panel is the moment-of-truth for an experiment. The numbers on it determine whether you ship, kill, or iterate. They also expose every shortcut taken in the design phase: an underpowered test produces wide confidence intervals; a peeked test produces a too-narrow p-value; a ratio metric without delta-method correction produces overconfident lift estimates. Most ship-the-wrong-thing decisions trace back to misreading the result panel. + +This skill is the discipline that prevents misreading. It assumes the experiment was designed well (see the `experiment-design` skill). It assumes the platform's results panel is technically correct (most modern platforms are; some older ones are not). It assumes you can read a number off a screen. The hard part is knowing what each number actually means and what it does not, and that is what is here. + +When to use this skill: any time you are reading an experiment result panel and about to make a ship, kill, or iterate decision. + +--- + +## What this skill is for + +This skill covers result interpretation, the statistical concepts that make the numbers trustworthy, and the dashboard reconciliation work that prevents executive-level confusion when the experiment number does not match the BI number. The audience is product managers and data analysts who read experiment results together and need a shared vocabulary that does not paper over the dangerous parts of statistics. + +Companion skills cover the adjacent territory. The `experiment-design` skill covers pre-experiment thinking: hypothesis, sample size, MDE, segments, what NOT to test. Read it before designing the test; read this skill when reading the result. The `feature-flagging` skill covers the operational mechanics of flag management, environment promotion, and stale-flag cleanup. Together the three skills span the experimentation lifecycle from intent through interpretation. For platform-specific MCP commands, consult the chosen platform's docs; Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, and Kameleoon all expose rich analytics surfaces that this skill informs how to read. + +--- + +## The result panel: what every modern platform should expose + +A result panel that omits any of the following is a black box. Treat results from black-box platforms with extra skepticism, and consider exporting raw assignment and event data into a notebook where you can compute the missing pieces yourself. + +What a competent platform exposes: + +- Variants and traffic allocation (e.g., 50/50, 33/33/33). Allocation drift across the test window indicates assignment bugs. +- Per-variant primary metric: point estimate, confidence interval (or credible interval for Bayesian), sample size at the variant level. +- Lift: variant minus control, expressed as both absolute change and relative percent. Both numbers matter; relative is intuitive, absolute is what shows up in revenue calculations. +- Statistical significance: p-value (frequentist) or probability of being best (Bayesian). The methodology should be labeled clearly so you know which interpretation rules apply. +- Variance reduction technique applied: CUPED, post-stratification, regression adjustment. If the platform applies these silently, ask which. +- Guardrail metric statuses: each guardrail labeled green, amber, or red against its tolerance. The tolerance was set at design time; the panel just enforces it. +- Per-segment results for pre-registered segments only. Post-hoc segment slicers are tempting and dangerous. +- Test status: running, ended, decision filed. +- A time series of the lift across the test window. This is where novelty effects, primacy effects, and assignment bugs become visible. + +If you are looking at a result panel that hides any of these, the first move is to surface them, not to ship. + +--- + +## Confidence intervals: the most important number + +The single most important number on the result panel is the confidence interval (CI) on the lift. More important than the point estimate. More important than the p-value. The CI tells you what you actually know. + +What a 95% CI of [+2%, +6%] means: under repeated sampling, the true effect would fall in this range 95% of the time. The true effect is most likely somewhere near the middle, but the extremes are entirely consistent with the data. + +What it does not mean: it does not literally mean "there is a 95% chance the true effect is between +2% and +6%." That is the Bayesian credible interval, which often gives similar numerical answers but is conceptually different. PMs can usually live with the loose intuition; analysts should know the precise version when defending a number to a skeptic. + +The width of the CI matters more than the center for most ship decisions. A wide CI means you do not know much yet. A narrow CI means you know with precision. The point estimate is your best guess; the width is your humility. + +Practical decision rules, in order of importance: + +1. If the CI includes zero AND a meaningful positive number (say [-1%, +5%]), you do not have enough data to ship. Period. The point estimate may look favorable, but the data is consistent with no effect and consistent with a meaningful win. You cannot tell which. +2. If the CI is all-positive (lower bound greater than zero, e.g., [+1%, +4%]), there is a real effect. Now evaluate magnitude: is the lower bound large enough to be worth the implementation cost? +3. If the CI is all-negative (upper bound less than zero, e.g., [-5%, -1%]), there is real harm. Kill the test. +4. If the CI straddles zero but is narrow (e.g., [-0.5%, +0.5%]), this is a real null result. The effect is small enough to call essentially zero. Useful information; do not ship the change for "lift" reasons (you found none) but do not panic about harm either. +5. If the CI straddles zero and is wide (e.g., [-5%, +8%]), the test is inconclusive. The data is consistent with a moderate win, no effect, or a moderate loss. Run longer, run bigger, or accept that the question cannot be answered at the available traffic. + +For a worked-example cheatsheet, see [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). + +--- + +## P-values: what they mean and what they do not + +The p-value is the probability of observing the lift you saw (or a larger one) IF the true effect were zero. A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. + +What the p-value does not mean, despite frequent abuse: + +- It does not mean "there is a 96% chance the treatment works." That sentence has no defensible interpretation; the p-value is computed under the assumption that the treatment does NOT work, so it cannot tell you the probability that it does. +- It does not mean "the effect is large." A tiny effect tested against a huge sample can produce a vanishingly small p-value. The p-value is about the strength of evidence against the null, not the size of the effect. +- It does not mean "the result will replicate." A p-value of 0.04 is associated with replication rates well below 50% in most published research; statistical significance is not reproducibility. + +The 0.05 cutoff is convention, not law. If you pre-committed to alpha equals 0.05, follow it; the discipline of pre-commitment is more valuable than the specific threshold. If you did not pre-commit, p equals 0.06 is not categorically different from p equals 0.04, and treating it as such is theater. + +Always read the CI alongside the p-value. The p-value tells you about the null hypothesis; the CI tells you about the magnitude. Both matter; neither is sufficient alone. A p-value of 0.001 with a CI of [+0.1%, +0.3%] is a real but practically tiny effect; a p-value of 0.08 with a CI of [-1%, +12%] is a noisy estimate that could be huge or zero. The former is technically significant and not worth shipping; the latter is technically not significant and you might still want to dig deeper. + +The peeking problem applies to p-values directly. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Modern platforms with sequential testing report "always-valid" or "anytime-valid" p-values that survive peeking; older platforms do not. Know which you are looking at. See [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md) for deeper coverage. + +--- + +## Multiple testing corrections + +The problem in one sentence: with twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty comparisons, two or three. With a hundred, five. + +Where multiple testing creeps in unintentionally: + +- Multiple variants: A vs B vs C vs D is three pairwise comparisons against control, not one. +- Multiple metrics: tracking primary plus six guardrails plus three secondary metrics is ten chances to find significance somewhere. +- Multiple segments: ten segments times three metrics is thirty chances. +- Multiple time windows: looking at week 1, week 2, week 3, and the full test is four chances per metric per segment. + +Two correction methods you should know: + +- Bonferroni correction. Divide alpha by the number of comparisons. Conservative; controls the family-wise error rate (the probability of even one false positive across the family of tests). Use when false positives are catastrophic. +- Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (the expected proportion of false positives among the things called significant). Better for exploratory analysis. + +Most modern platforms support these natively as a configuration option. Configure them, or know which the platform applies by default. Some platforms apply corrections silently to the displayed p-values; others report uncorrected numbers and expect you to do the math. + +The PM-friendly heuristic: pre-register your primary metric and primary segment. Treat everything else as exploratory. Findings in non-primary metrics or non-primary segments require larger effects, replication in a follow-up test, or both before they justify shipping. The discipline of designating primary up front protects you from the multiple-testing trap better than any correction formula. + +--- + +## Sequential testing math + +The peeking problem revisited from the analytics side. Classical t-tests, z-tests, and proportion tests assume one analysis at the end of a test. If you analyze the data five times during the test and stop the moment you see significance, your false positive rate is much higher than the nominal 5%. With daily peeking on a four-week test, false positive rate can climb above 30%. + +Sequential testing methods adjust the math to allow continuous monitoring without inflating false positives. The names you will encounter: + +- mSPRT (mixture sequential probability ratio test). Produces "always-valid" p-values: you can look any time, and the false positive rate stays at the nominal alpha. Common in modern platforms. +- Group sequential designs. Plan a fixed set of interim analyses (say, three) with adjusted significance thresholds at each. Less flexible than mSPRT but well-understood. +- Anytime-valid confidence intervals. The CI version of always-valid p-values. Wider than fixed-horizon CIs by design; the cost of peek-safety is some statistical efficiency. + +Modern platforms with sequential testing built in: Statsig (always-valid by default), Eppo (sequential CIs as a configuration), parts of PostHog (depending on the experiment type), GrowthBook (mSPRT supported). If your panel says "always-valid p-value" or "anytime-valid CI," that is sequential. If it says "p-value" with no qualifier, it is probably fixed-horizon and peeking inflates false positives. + +If your platform does not support sequential testing, the discipline is: pre-commit to a single analysis date at launch, do not peek, and if you must peek, do not make decisions based on the peek. Save the decision-making for the pre-committed date. This is hard. Sequential testing makes it easier. + +The trade-off: sequential tests have wider CIs and less aggressive p-values than fixed-horizon tests at the same sample size. The cost is real but usually worth it for PM contexts where the discipline of not peeking is impractical. + +--- + +## CUPED variance reduction + +CUPED (Controlled-experiment Using Pre-Experiment Data) uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. The result is the same point estimate with a much narrower confidence interval, often 30% to 50% narrower, which is equivalent to roughly doubling your effective sample size for free. + +When CUPED helps: + +- Metrics with high pre-experiment baseline variance: revenue per user, sessions per user, engagement minutes, content consumption. +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When CUPED does not help: + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline (a user either signs up or does not; there is nothing to subtract). +- Tests where pre-experiment behavior is essentially uncorrelated with the metric being moved. + +How to read CUPED-adjusted results: the point estimate is roughly the same as the unadjusted estimate; the CI is narrower. If a result switched from "significant with CUPED" to "not significant without CUPED," that is normal and the CUPED-adjusted version is the more powerful test. If a result went the other way (significant without CUPED, not significant with), the unadjusted result was probably noise that CUPED correctly removed. + +A common confusion: "CUPED made our lift smaller, so we should ship the unadjusted version." This is wrong. CUPED reduces variance, not point estimates. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. Trust the adjusted version. + +Platform support: Statsig, Eppo, GrowthBook, parts of PostHog, Amplitude (Experiment product). Optimizely has equivalent variance reduction. If your platform offers CUPED, turn it on for any metric where pre-experiment data exists. + +For deeper coverage of CUPED, the delta method, and other statistical methods, see [`references/statistical-method-reference.md`](references/statistical-method-reference.md). + +--- + +## Heterogeneous treatment effects (HTE) and segments + +A heterogeneous treatment effect is when the treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. This is common, often interesting, and easy to over-read. + +Why HTE is tempting: "let us just ship to new users." Why it is dangerous: post-hoc segment discovery is often noise; targeting infrastructure costs are real; UI complexity from per-segment behavior compounds over time. + +The right way to handle HTE: + +- Pre-register the segments you care about before launching. Two or three is plenty; ten is overfitting waiting to happen. +- If a pre-registered segment shows a meaningfully different effect, treat it as evidence worth following up. Not as a green light to ship to that segment alone. +- Before shipping segment-only behavior, ask: is the segment large enough to matter, is the effect large enough to justify the targeting work, and can we build the targeting cleanly in production? +- If the segment was discovered post-hoc by slicing the data many ways, treat the finding as a hypothesis for a follow-up test. Do not ship based on one observation. + +HTE versus simple averaging: when segments have meaningfully different effects, the average underrepresents both. A treatment that is +10% for half the population and -5% for the other half averages to +2.5%, which understates the win for half and ignores the loss for the other. The average is still the right number for "ship to everyone" decisions; per-segment numbers are the right inputs for "should we invest in segment-specific targeting" decisions. + +Practical heuristic: if pre-registered segments show meaningfully different effects, write a follow-up hypothesis. Run a follow-up test that confirms the segment behavior with appropriate power. Then decide on segment-specific shipping. The cost of the follow-up test is much smaller than the cost of shipping segment-targeted behavior that does not actually work. + +--- + +## Ratio metrics and the delta method + +Most "rate" metrics are ratios. Conversion rate equals conversions divided by users. Click-through rate equals clicks divided by impressions. Revenue per user equals revenue divided by users. Average order value equals revenue divided by orders. + +Why this matters for analytics: standard variance estimation for sums does not apply directly to ratios. Naive variance estimation on ratios produces incorrectly narrow confidence intervals and inflated false positive rates. You ship things that look significant but are not, because the math under the hood was wrong. + +Two correct approaches: + +- Delta method. A calculus-based correction (Taylor expansion linearization) that produces correct CIs and p-values for ratio metrics. Fast, well-understood, what most modern platforms use. +- Bootstrap. A simulation-based alternative: resample users with replacement many times, compute the ratio each time, and read off the empirical distribution. Distribution-free and intuitive; slower than delta method. + +How to verify your platform: ask "what variance estimator do you use for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (one row per user, converted yes or no). If the answer is "delta method," "linearization," or "bootstrap," correct. + +Most modern platforms (Statsig, Eppo, PostHog, Optimizely, GrowthBook) handle this correctly. Older or homegrown platforms often do not. The risk is silent: the panel shows confidence intervals that look reasonable but are too narrow, and you ship changes that do not produce the claimed effect. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. Suppose treatment shows a 5% lift with a CI that excludes zero under the wrong (naive) variance estimator. Under the correct delta-method estimator, the same point estimate has a CI that includes zero. The wrong math says "significant, ship." The correct math says "inconclusive, run longer or accept noise." Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production, then puzzling over why the launch did not move the dashboard. + +--- + +## Bayesian vs frequentist results panels + +Frequentist panels (most older platforms, parts of most modern ones) show p-values, confidence intervals, and "statistically significant" labels. Bayesian panels (Eppo by default, Statsig as an option, parts of PostHog) show probability of being best, credible intervals, and posterior distributions. + +For most PM contexts, both approaches produce similar ship-or-kill decisions when the experiment was designed correctly. The vocabulary differs; the underlying judgment is similar. + +Bayesian advantages: + +- Natural multi-variant comparison: "variant B has 87% probability of being best" reads more naturally than the equivalent Bonferroni-corrected p-value soup. +- Peek-safe by construction: posterior probabilities are valid at any time without sequential corrections. +- More intuitive for stakeholders unfamiliar with hypothesis testing. +- Allows informative priors when you have prior knowledge (rare in practice for shipping decisions). + +Frequentist advantages: + +- Better-understood: most analytics teams have stronger frequentist training. +- Clearer pre-registration semantics: "alpha equals 0.05, MDE equals 5%, decision rule X" is unambiguous. +- Longer track record in regulated contexts. + +Mixing them within a single experiment is fine. Most platforms (Eppo, Statsig) let you toggle. Pick one per experiment and stick with it; do not switch mid-flight to chase a more favorable interpretation. That is the Bayesian-frequentist version of p-hacking and corrodes the discipline. + +--- + +## Network effects and SUTVA violation + +SUTVA (Stable Unit Treatment Value Assumption) is the technical name for "one user's treatment does not affect another user's outcome." When SUTVA holds, standard A/B test math works. When it is violated, the math systematically understates or overstates the true effect. + +When SUTVA is violated: + +- Two-sided marketplaces. Changes to buyers shift seller behavior, which affects control buyers competing for the same supply. Treatment buyers' actions leak into the control group's experience. +- Social products. A treatment user's changed behavior affects the experience of users they interact with, regardless of which group those friends are in. +- Supply-constrained features. When supply is limited, treatment users compete with control users for the same scarce resource, and the test cannot cleanly separate treatment effect from substitution. +- Notification systems. A treatment that increases notification volume changes user behavior across the whole platform, not just in the treatment cell. + +The "interference dampens lift" pattern is the most common version. In marketplace experiments, if your treatment looks small, the true effect (in the absence of interference) may be 2x to 3x larger than what the standard A/B test reports. Killing a winning test because the leaked-into-control lift looked small is a common mistake. + +Detection methods: + +- Switchback experiments. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control, etc.). Eliminates cross-user interference within each window; requires careful temporal modeling. +- Cluster randomization. Assign whole units (cities, markets, friend groups) rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. +- Geographic experiments. Launch in some regions, hold others. Slow and expensive but interference-clean. + +When in doubt about whether interference is present, run a small cluster-randomized version as a check. If the cluster-randomized lift is much larger than the user-randomized lift, you have evidence of interference and should rerun the main test as cluster-randomized. + +--- + +## Dashboard metric vs experiment metric reconciliation + +The scenario: your business intelligence dashboard shows revenue grew 8% last week. Your experiment platform shows the treatment lifted revenue 2%. How can both be true? + +Likely answers, ranked by frequency: + +- Different denominators. The dashboard shows all users; the experiment shows just enrolled users. Most experiments enroll a subset; the lift only applies to that subset. +- Different time windows. The dashboard is rolling 7 days; the experiment is fixed start to end. The two windows can move independently. +- External effects. Marketing campaigns, seasonality, competitor activity, news cycles. The experiment correctly excludes these by random assignment; the dashboard reflects them. +- Selection effects. Who gets enrolled in the experiment matters. New users only? Logged-in users only? Users who passed a feature flag check? Each filter changes the population the lift applies to. +- Different metric definitions. "Revenue" might be gross in one place and net of refunds in another. "Conversions" might count differently across systems. + +Reconciliation discipline: never report experiment results as "the feature drove $X in revenue this week." Always report as "the feature lifted enrolled-user revenue Y% during the test period." The first phrasing implies a company-wide impact that the experiment cannot measure; the second phrasing is precise about what the experiment actually showed. + +The "blended attribution" trap is the most common reconciliation failure. PM takes the experiment lift (say +2% revenue per user) and multiplies by the total user base for a company-wide impact estimate ("$10M in incremental revenue"). This is wrong twice over. The lift only applies to enrolled users (typically 10% to 50% of the base). Even within the enrolled group, the lift was measured during the test conditions; long-term and at full scale, the effect can be different. The right phrasing is "during the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control." Then leadership can do the careful arithmetic of how that translates at full launch. + +For deeper reconciliation patterns and stakeholder-facing language, see [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). + +--- + +## Long-term effect estimation + +Most A/B tests run for two to four weeks. Many feature decisions need a thirty- to ninety-day understanding because behavior changes over longer windows: novelty fades, primacy fades, retention impacts emerge, network effects compound. + +Three patterns for long-term measurement: + +- Holdout groups. Keep a percentage of users (often 5% to 10%) on the control treatment for thirty or more days post-launch. Compare their long-term behavior to the launched-to users. The comparison measures the long-term effect cleanly because the holdout was randomized at the same time as the original test. +- Geo experiments. Launch the change in some markets and hold others. Measure long-term differences across market pairs. Slow, expensive, and the markets need to be comparable, but interference-clean and capable of measuring effects that user-randomization cannot. +- Difference-in-differences (diff-in-diff). Pre-launch versus post-launch measurement in a treated market versus a control market. Useful when you cannot randomize at all (regulatory rollouts, partner-specific changes). Weaker than randomized methods but defensible when randomization is impossible. + +Practical heuristic: any feature with novelty risk (new UI, new mechanic, new pricing, new notification cadence) deserves a thirty-day holdout. Set it up at launch, not later; setting it up later requires unwinding the launch and is rarely done in practice. The cost of the holdout is small (a small percentage of users on the old experience for a month); the value is the ability to detect long-term degradation before it compounds. + +--- + +## Common interpretation failures + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "P equals 0.04, ship it." No consideration of CI width, magnitude, or guardrails. Significance is a necessary condition, not a sufficient one. +- "We saw +5% on day 3, ending early." Peeking, novelty effect, or both. Day-3 lifts are routinely larger than day-14 lifts; ending early ships noise. +- "The new flow worked for power users (post-hoc segment)." Noise mining. The segment was found by slicing the data multiple ways; the apparent lift will not replicate. +- "Our experiment said +2%, but launch only delivered +0.5%." Often the experiment was correct: the lift applied to enrolled users in test conditions, and at full launch the effect is diluted by non-enrolled users, novelty fade, or interference effects the test could not capture. +- "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail violation that was reframed as "no signal." If retention is a guardrail, the guardrail is binding; "we did not see a clear signal" is not the same as "we have evidence of safety." +- "We CUPED-adjusted away a real treatment effect." CUPED reduces variance, not the point estimate. If the lift looked smaller after CUPED, the unadjusted lift was probably noise that CUPED correctly removed. Trust the adjusted version. +- "Two segments showed opposite effects; we shipped to the better segment." Likely overfitting unless both segments were pre-registered and the targeting infrastructure exists. Re-test before shipping. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped." Inconclusive is inconclusive. Directional patterns are not evidence; they are wishful reading of noise. + +--- + +## The framework: 14 considerations for trustworthy experiment interpretation + +Trustworthy interpretation sits at the intersection of fourteen considerations. Each is covered in detail in its own section above. + +1. **Result panel completeness.** The panel exposes variants, allocation, per-variant metrics, lifts, significance, variance reduction, guardrails, segments, time series, and status. Missing pieces are red flags. +2. **Confidence interval reading.** Width matters more than center. Five practical decision rules cover the cases where CI excludes zero, includes zero narrowly, and includes zero widely. +3. **P-value semantics.** The probability of seeing the lift if the null is true. Not the probability that the treatment works. Always read alongside the CI. +4. **Multiple testing corrections.** Bonferroni for family-wise control, BH for false discovery rate. Pre-register primary metrics and segments; treat the rest as exploratory. +5. **Sequential testing math.** Always-valid p-values and anytime-valid CIs survive peeking. Fixed-horizon p-values inflate false positives under daily monitoring. +6. **CUPED variance reduction.** Same point estimate, narrower CI. Use whenever pre-experiment data is available and informative. +7. **Heterogeneous treatment effects.** Pre-register segments. Treat post-hoc segment effects as hypotheses for follow-up tests, not as ship signals. +8. **Ratio metrics.** Use delta method or bootstrap. Naive proportion estimators understate variance and inflate false positives. +9. **Bayesian vs frequentist.** Pick one per experiment and stick with it. Both produce similar ship decisions when the experiment was designed correctly. +10. **Network effects and SUTVA.** Marketplace and social products often violate SUTVA. Cluster randomization, switchback, or geographic experiments when interference is suspected. +11. **Dashboard reconciliation.** Different denominators, time windows, external effects, and metric definitions explain most disagreements between BI dashboards and experiment panels. +12. **Long-term effect estimation.** Holdouts, geo experiments, and diff-in-diff for effects that emerge over thirty to ninety days. +13. **Common interpretation failures.** A pattern catalog of the most frequent ways smart teams ship wrong things. +14. **The discipline of inconclusive.** The hardest call is "we do not have enough signal to ship." It is often the right call. + +The sections above expand each consideration in turn. Read the relevant section before making the decision, not after. + +--- + +## Reference files + +- [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). How to read a CI, what to ignore, the five decision rules with worked examples for each. +- [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md). What it means, what people pretend it means, the 0.05 convention, the peeking problem, and the multiple-testing context. +- [`references/statistical-method-reference.md`](references/statistical-method-reference.md). CUPED, the delta method, sequential testing methods (mSPRT, group sequential, anytime-valid), HTE handling, multiple testing corrections, cluster randomization. The technical reference for analysts. +- [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). Why the BI number does not match the experiment number, the blended-attribution trap, and how to communicate the difference to non-statistical stakeholders. +- [`references/result-presentation-templates.md`](references/result-presentation-templates.md). Five templates for stakeholder communication: clear win, clear loss, inconclusive (the most common, hardest), mixed (positive primary with ambiguous guardrail), and long-term holdout report. +- [`references/analytics-platform-comparison.md`](references/analytics-platform-comparison.md). Profiles of seven major platforms (Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, Kameleoon) covering what each exposes, what each hides, and the gotchas in each. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). Fifteen-plus failure patterns: name, symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it inconclusive + +Most experiment results are not clear ship-or-kill. They are inconclusive: lift exists but the CI straddles zero; lift is real but does not justify the implementation cost; lift is significant but a guardrail is concerning; lift looks great in one segment but the segment is small or the targeting infrastructure does not exist. + +The hardest decision a PM makes in a given week is often "we do not have enough signal to ship." The temptation to lower the bar after seeing the result is enormous. The discipline of saying "inconclusive" is the discipline of caring about being right more than being decisive. + +The same discipline applies to analysts. The temptation to slice the data one more way until something looks significant, to apply one more variance reduction technique, to switch from frequentist to Bayesian mid-test, is constant. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +Inconclusive is a valid outcome. The lesson, if there is one, is for the next hypothesis: the effect is smaller than expected, the segment matters, the test was underpowered, the metric was the wrong one. Use the inconclusive result to design a better next test. Do not retrofit a story onto the current one. + +For pre-experiment design discipline, see the `experiment-design` skill. For the operational mechanics of feature flags that deliver the variants, see the `feature-flagging` skill. For platform-specific MCP commands and example prompts, consult the chosen platform's documentation. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md b/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md new file mode 100644 index 0000000..a8c3504 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md @@ -0,0 +1,147 @@ +# Analytics platform comparison + +Profiles of seven major experimentation platforms covering what each exposes, what each hides, and the gotchas in each. For MCP setup, auth, and example prompts, consult each platform's official documentation. + +The categorization below is for analytics surface area specifically. All seven platforms are competent at running experiments; the difference is what they expose on the result panel and how the math under the hood handles edge cases. + +--- + +## Statsig + +**Statistical defaults.** Among the most rigorous in the category. Always-valid p-values (sequential testing) by default. CUPED variance reduction available and easy to enable. Delta method for ratio metrics. Comprehensive HTE analysis with pre-registered and exploratory modes. + +**What is exposed.** Per-variant metrics with CIs, lift point estimate, always-valid p-value, sample size, variance reduction technique applied, guardrail status, segment results for pre-registered segments, time series of the lift across the test window. + +**What can be hidden by default.** Some advanced configuration is buried in the UI; defaults are sensible but worth confirming. The "topline metrics" view simplifies away the CI in some contexts. + +**Gotchas.** + +- Always-valid p-values are wider than fixed-horizon by design. Teams new to sequential testing sometimes interpret "less significant" as "weaker effect" rather than "peek-safe math." +- The auto-generated guardrail metrics catch some categories well (latency, error rate) and miss others (business-critical metrics specific to your product). Augment with custom guardrails. +- The "experiment hub" view groups results across multiple experiments and can mask single-experiment subtlety. + +**Where it shines.** Mid-stage to late-stage product teams running many concurrent experiments where peek-safety and variance reduction matter. The default rigor saves teams from common mistakes without requiring statistical expertise. + +--- + +## PostHog + +**Statistical defaults.** Solid for the open-source experimentation category. Frequentist by default; Bayesian available. Variance reduction via "stats engine" configuration. Sequential testing in some experiment types. + +**What is exposed.** Per-variant metrics, CIs, p-values, sample size, time series, segment results. + +**What can be hidden.** The newer "stats engine" updates change defaults across versions; what you see depends on the deployment version. Older deployments may use less-rigorous defaults. + +**Gotchas.** + +- Self-hosted vs cloud can differ in stats engine version. Confirm the version when interpreting numbers. +- The "winner" badge can appear on results that are technically significant but practically tiny. Always read the CI. +- Bayesian and frequentist views can coexist for the same experiment; use one consistently per experiment. + +**Where it shines.** Teams that want experimentation embedded in their analytics platform rather than separate. PostHog's strength is the integration of feature flags, experiments, session recording, and product analytics in one place. + +--- + +## Optimizely + +**Statistical defaults.** Enterprise-grade rigor. Stats Engine includes sequential testing, ratio-aware variance estimation, and configurable significance thresholds. Long track record in the category. + +**What is exposed.** Comprehensive per-variant statistics, configurable significance thresholds, sequential testing labels, sample size, segment analysis with pre-registration. + +**What can be hidden.** Configuration depth means defaults vary by account setup. Confirm with the platform admin which defaults are in play for your project. + +**Gotchas.** + +- The classic Optimizely product (Web Experimentation) and the newer products (Feature Experimentation, Personalization) have different stats engines. Know which product your team is on. +- Enterprise pricing can mean limited license seats; non-statistician PMs sometimes work from screenshots taken by analysts, which loses interactive panel context. +- The "lift" display can default to relative percent without the absolute number; both matter. + +**Where it shines.** Larger organizations with established experimentation practices, regulated contexts where the rigorous track record matters, and teams that need extensive personalization alongside experimentation. + +--- + +## GrowthBook + +**Statistical defaults.** Open-source-first, warehouse-native. Explicit choice between Bayesian and frequentist. Sequential testing via mSPRT. CUPED supported. + +**What is exposed.** Per-variant metrics with CIs, lift, significance, variance reduction, guardrails, segment results. + +**What can be hidden.** Because GrowthBook runs on top of your data warehouse, the metric definitions live in your SQL; verify them when reading results. A subtle metric query change can shift results without anyone noticing. + +**Gotchas.** + +- Warehouse latency affects how fresh the result panel is. A daily batch is common; treat panel data as up to one day stale. +- Custom metrics defined in SQL can drift from dashboard definitions of the same metric. Reconcile carefully. +- The "experiment health checks" surface assignment imbalance and other quality issues; pay attention when they fire. + +**Where it shines.** Engineering-led teams that want experimentation tied directly to the warehouse and version-controlled metric definitions. The open-source core means full transparency on the math. + +--- + +## Eppo + +**Statistical defaults.** Best-in-class statistical defaults among the platforms. Bayesian and frequentist supported, with Bayesian as the default for most use cases. Sequential CIs available. CUPED supported. Delta method for ratio metrics. Strong HTE analysis. + +**What is exposed.** Per-variant metrics with credible intervals (Bayesian) or CIs (frequentist), probability of being best, posterior distributions, lift, guardrails, segments. + +**What can be hidden.** The Bayesian default produces "probability variant B is best" rather than a p-value, which can confuse stakeholders trained on frequentist conventions. Switch to frequentist if your team's vocabulary is p-value-based; do not switch mid-experiment. + +**Gotchas.** + +- Bayesian probabilities and frequentist p-values answer different questions; do not translate one into the other naively. +- Eppo's "decision support" feature recommends actions based on the result; treat the recommendation as input, not as the decision. +- Warehouse-native like GrowthBook; same caveats about metric definition drift. + +**Where it shines.** Data-team-led organizations that want statistical rigor as a default. Eppo's design philosophy is "make it hard to do the wrong thing"; the defaults reflect that. + +--- + +## Amplitude (Experiment) + +**Statistical defaults.** Behavioral analytics first, experimentation second. Frequentist defaults; sequential testing available. Variance reduction supported. + +**What is exposed.** Per-variant metrics with CIs, p-values, sample size, segment analysis, guardrails. Tightly integrated with Amplitude's behavioral analytics surface. + +**What can be hidden.** Some statistical configuration options are less prominent than in Statsig or Eppo; defaults are reasonable but worth confirming. + +**Gotchas.** + +- Strength is the integration with behavioral analytics, not the rigor of the experimentation engine. For teams that prioritize statistical sophistication, the engine is competent but not the strongest. +- Amplitude's "insights" auto-generate from event data; the same flexibility that makes them useful makes it easy to slice into noise. +- Experiment results can be viewed alongside cohort and funnel analyses; this is powerful and risky (post-hoc cohort definitions are noise mining). + +**Where it shines.** Product teams already invested in Amplitude for behavioral analytics. The integration of experiment results with the broader product analytics is the differentiator. + +--- + +## Kameleoon + +**Statistical defaults.** Frequentist with Bayesian options. CUPED and sequential testing supported. Strong personalization and AI-driven optimization features. + +**What is exposed.** Per-variant metrics with CIs, p-values, lift, segments, guardrails. + +**What can be hidden.** The personalization and AI optimization features can take experiment results and apply them automatically; verify which of your "experiments" are actually fully randomized A/B tests vs personalization rollouts. + +**Gotchas.** + +- The boundary between experiment and personalization can blur. Personalization decisions made by an AI engine are not the same as ship decisions made from a randomized A/B test. +- Less common in the US than the European market; documentation and community resources are more limited than for Statsig, PostHog, or Optimizely. +- Some advanced statistical features require specific subscription tiers. + +**Where it shines.** Teams running heavy personalization alongside experimentation, particularly in the European market. The personalization features are differentiated; the experimentation engine is competent. + +--- + +## Quick comparison + +| Platform | Sequential testing | CUPED | Delta method | Bayesian option | Strongest for | +|---|---|---|---|---|---| +| Statsig | Default | Yes | Yes | Yes | Multi-team experimentation rigor | +| PostHog | Some types | Configurable | Yes | Yes | Embedded analytics + experiments | +| Optimizely | Yes | Yes | Yes | No (frequentist Stats Engine) | Enterprise + personalization | +| GrowthBook | Yes (mSPRT) | Yes | Yes | Yes | Warehouse-native, open source | +| Eppo | Yes | Yes | Yes | Default | Statistical rigor by default | +| Amplitude | Yes | Yes | Yes | Yes | Behavioral analytics integration | +| Kameleoon | Yes | Yes | Yes | Yes | Personalization-heavy contexts | + +The platform choice is rarely the bottleneck on getting experimentation right. All seven are competent. The bottleneck is the design discipline (covered in the `experiment-design` skill), the interpretation discipline (covered in this skill), and the operational discipline of the flag layer (covered in the `feature-flagging` skill). Pick the platform that fits the team's existing stack and skill mix; spend the effort on the disciplines. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md b/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..86c27fb --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md @@ -0,0 +1,203 @@ +# Common interpretation failures + +Fifteen-plus failure patterns that produce confidently wrong shipping decisions. Each pattern is described as: name, symptom (what it looks like in the panel or the discussion), root cause (why it happens), fix (what to do this time), prevention (how to avoid it next time). + +--- + +## Pattern 1: P-value worship + +**Symptom.** "P equals 0.04, ship it." No discussion of CI width, magnitude, or guardrails. + +**Root cause.** Treating statistical significance as a binary truth. The p-value answers one specific question (how surprising is this data under the null) and people use it to answer all questions. + +**Fix.** Always pair the p-value with the CI on the lift and the guardrail status. A significant p-value with a wide CI that includes practically tiny effects is not a ship signal. + +**Prevention.** Pre-commitment includes the MDE, not just the alpha. The decision rule should reference the lift magnitude relative to the MDE, not just the p-value. + +--- + +## Pattern 2: Early stop on a peek + +**Symptom.** Test ended on day 3 or day 5 because the result "looked great." Headline lift is 5% to 10%; later analysis shows the effect was much smaller. + +**Root cause.** Standard p-values inflate under peeking. Early-test lifts are systematically larger than late-test lifts due to regression to the mean and novelty effects. + +**Fix.** Re-run the test to the pre-committed end date. Treat the early result as suggestive only. If the platform supports always-valid p-values, those are peek-safe; otherwise, do not stop early. + +**Prevention.** Pre-commit the analysis date at launch. If the platform offers sequential testing, enable it. If not, do not look at intermediate results. + +--- + +## Pattern 3: Post-hoc segment mining + +**Symptom.** "The new flow worked for power users on Android in the EU on weekends." The segment was discovered by slicing the data many ways looking for an effect. + +**Root cause.** Multiple comparisons. With enough segments, some will show a "significant" effect purely by chance. The pattern is real for the test data; it does not replicate. + +**Fix.** Treat the post-hoc segment finding as a hypothesis for a follow-up test, not as a ship signal. Pre-register the segment in the new test and run it cleanly. + +**Prevention.** Pre-register segments at design time. Two or three is plenty; ten is overfitting waiting to happen. Treat any segment not in the pre-registration list as exploratory. + +--- + +## Pattern 4: Launch dilution misread + +**Symptom.** "Our experiment said +2%, but launch only delivered +0.5%. The experiment was wrong." + +**Root cause.** The experiment lift applied to enrolled users in test conditions. Launch dilution from non-enrolled users, novelty fade, and interference effects routinely produce smaller production effects than test effects. The experiment was usually correct; the production measurement is correctly capturing the diluted effect. + +**Fix.** Compare apples to apples: the launch effect on the same enrolled-user population, in the same conditions. If the launch effect on enrolled users matches the test, the experiment was right; the dashboard sees a smaller number because the dashboard includes everyone. + +**Prevention.** Communicate experiment results in enrolled-user terms, not extrapolated to the full base. The blended-attribution trap is the source of most "experiment wrong" complaints. + +--- + +## Pattern 5: Guardrail reframing + +**Symptom.** "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail movement that was reframed as "no signal" rather than treated as binding. + +**Root cause.** The guardrail was pre-committed but the team did not pre-commit a clear rule for "what counts as a guardrail violation." A wide CI on the guardrail leaves room for interpretation; the interpretation usually favors shipping. + +**Fix.** If retention is a guardrail, the guardrail binds. "We did not see a clear signal" is not the same as "we have evidence of safety." A wide guardrail CI means the test was underpowered for the guardrail; the right answer is more sample, not "ship anyway." + +**Prevention.** At pre-commitment, define guardrail rules as: "ship only if the CI on the guardrail clearly excludes a [X percent] degradation." Then apply the rule mechanically when results come in. + +--- + +## Pattern 6: CUPED misinterpretation + +**Symptom.** "We CUPED-adjusted away a real treatment effect. Let us report the unadjusted version." OR "The unadjusted lift is bigger; CUPED is hiding our win." + +**Root cause.** Misunderstanding what CUPED does. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior. + +**Fix.** Trust the CUPED-adjusted estimate. If the estimate is smaller and the CI is narrower, the CUPED estimate is closer to the true effect. + +**Prevention.** Educate the team on what CUPED does before enabling it. The first time the unadjusted and adjusted numbers diverge, walk through why. + +--- + +## Pattern 7: Opposite-segment shipping + +**Symptom.** "Two segments showed opposite effects; we shipped to the better segment." Often without re-testing or without infrastructure to support segment-specific behavior. + +**Root cause.** Post-hoc segment discovery (most common) or pre-registered segments where the targeting infrastructure does not exist. Either way, segment-only shipping is a significant commitment that requires more evidence than a single observation. + +**Fix.** Treat the segment finding as a hypothesis for a follow-up test. Confirm the effect with an appropriately powered re-test. Build the targeting infrastructure with eyes open about ongoing maintenance cost. + +**Prevention.** Pre-register segments. Build the targeting infrastructure separately, before any segment-specific shipping decision; do not let the decision force the infrastructure into existence under deadline pressure. + +--- + +## Pattern 8: Directional ship + +**Symptom.** "The result was technically inconclusive, but the trend was directional so we shipped." + +**Root cause.** Inconclusive is hard to communicate; directional language sounds more decisive. The team substitutes the appearance of evidence for actual evidence. + +**Fix.** Inconclusive is inconclusive. The directional pattern is wishful reading of noise. Do not ship; either run a bigger test or kill the hypothesis. + +**Prevention.** Pre-commit decision rules that map each possible result to a ship-or-kill decision. The inconclusive case should map to "do not ship" by default. Discussions of "directional" outcomes are a sign that pre-commitment was incomplete or is being ignored. + +--- + +## Pattern 9: Mid-test methodology switch + +**Symptom.** Test was running with frequentist analysis; results were ambiguous; team switched to Bayesian (or vice versa) and the new view "shows we should ship." + +**Root cause.** Different methodologies can produce different ship recommendations on the same data, particularly near the significance threshold. Switching mid-flight to find the more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +**Fix.** Stick with the methodology pre-committed at launch. If the result is ambiguous under the pre-committed method, that is the result. + +**Prevention.** Pre-commit the methodology along with the metric and the alpha. Document the choice in the experiment configuration so the change is visible if anyone tries. + +--- + +## Pattern 10: Ratio metric without delta method + +**Symptom.** Conversion rate or revenue per user with a CI that looks suspiciously narrow. The result panel shows significance that does not replicate at launch. + +**Root cause.** Naive variance estimation on ratio metrics produces incorrectly narrow CIs and inflated false positive rates. The platform did not use delta method, bootstrap, or another ratio-aware estimator. + +**Fix.** Re-analyze with a ratio-aware estimator. If the platform does not support one, export raw data and compute correctly in a notebook. + +**Prevention.** Verify your platform's variance estimator for ratio metrics during onboarding. If the answer is "standard t-test on proportions," consider migrating or implementing the correction yourself. + +--- + +## Pattern 11: Marketplace interference undercount + +**Symptom.** Marketplace experiment shows a small lift; team kills the test as not worth the effort. Later, a feature implemented for other reasons shows a much larger effect on the same metric. + +**Root cause.** SUTVA violation. In two-sided marketplaces, treatment users compete with control users for the same supply; the lift "leaks" into control. The standard A/B test undercounts the true effect, often by a factor of 2x to 3x. + +**Fix.** Re-run as cluster randomized (whole markets to treatment or control) or switchback. Compare the results to the user-randomized version to estimate the interference factor. + +**Prevention.** Identify SUTVA violation risk at design time. For marketplace, social, and supply-constrained features, default to cluster randomization or switchback unless interference is demonstrably negligible. + +--- + +## Pattern 12: Definition drift between systems + +**Symptom.** Experiment result shows +X% on conversion. Dashboard shows the launch having no effect on conversion. Investigation reveals the two systems define "conversion" differently. + +**Root cause.** Metric definitions live in different places (experiment platform, BI dashboard, data warehouse) and drift over time. Each definition individually makes sense; the comparison is meaningless. + +**Fix.** Reconcile the definitions before the next post-launch report. Pick one canonical definition and align both systems. + +**Prevention.** Centralize metric definitions (semantic layer, dbt model, shared SQL library). Audit all "the same metric" usages quarterly. + +--- + +## Pattern 13: Confounded test window + +**Symptom.** Test ran during a marketing campaign, a product launch, an outage, or a holiday. The result is reported without acknowledging the external event. + +**Root cause.** Random assignment usually handles external events (treatment and control are equally affected). But if the external event affects the metric definition (campaign brings different user mix), the populations stop being comparable. + +**Fix.** Stratify the analysis by the relevant covariate (acquisition source for campaigns, date for outages). If the stratified analysis differs meaningfully from the pooled analysis, report the stratified version and explain. + +**Prevention.** Maintain a calendar of marketing campaigns, product launches, and known external events. Avoid scheduling sensitive tests during these windows. If unavoidable, plan the stratification at design time. + +--- + +## Pattern 14: Long-tail metric overweighted by outliers + +**Symptom.** Revenue per user shows a large lift driven by a few high-value users. The lift is "significant" but unstable across re-samples. + +**Root cause.** Long-tailed distributions (revenue, session length, content engagement) have a few users contributing disproportionately. Random assignment of those users to treatment or control can drive large apparent effects that do not represent the underlying treatment effect. + +**Fix.** Winsorize the metric (cap extreme values at the 99th percentile, for example) and re-analyze. If the winsorized result is materially different from the raw result, the outliers were driving the effect. + +**Prevention.** Pre-commit to a winsorization threshold for long-tailed metrics. Apply the same threshold across treatment and control. Document the choice. + +--- + +## Pattern 15: Significance from sample size, not effect + +**Symptom.** "P equals 0.001, very significant." CI on the lift is [+0.1%, +0.3%]. Magnitude is tiny. + +**Root cause.** With enough sample, even tiny effects produce small p-values. Significance is not the same as magnitude. Shipping a 0.2% lift because "p was tiny" is a misuse of the framework. + +**Fix.** Read the CI alongside the p-value. If the practical lift is too small to matter, do not ship regardless of significance. + +**Prevention.** Pre-commit to an MDE (minimum detectable effect) as part of the design. If the observed lift is below the MDE, the test was overpowered and the result, while real, is not actionable. + +--- + +## Pattern 16: Overcorrection panic + +**Symptom.** Result shows a clean lift on the primary metric. Team adds five new metrics post-hoc and applies Bonferroni correction across all of them. Now the primary metric is "not significant." + +**Root cause.** Multiple testing corrections apply to pre-registered comparisons, not to post-hoc analyses meant to "stress-test" the result. Adding metrics after seeing the result and then correcting is statistically incoherent. + +**Fix.** Apply corrections only to the pre-registered comparison set. Post-hoc metrics are exploratory and should be reported as such, without claiming to update the primary inference. + +**Prevention.** Pre-register the metric set at design time. Treat any metric not on the list as exploratory. + +--- + +## The pattern behind the patterns + +Most of these failures share a common shape: the team had a hypothesis they wanted to confirm, the result was less clean than hoped, and the team applied an analytical knob (slice, switch methodology, drop outliers, reframe the guardrail, peek early) to make the result look cleaner. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. + +The defense against this pattern is pre-commitment. The defense against pre-commitment being weakened over time is documenting the pre-commitment somewhere immutable (PR description, signed Slack message, pinned ticket) and applying it mechanically when results come in. The pre-commitment is not the team's enemy; it is the team's protection from its own future motivated reasoning. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md b/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md new file mode 100644 index 0000000..1f3e1ec --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md @@ -0,0 +1,107 @@ +# Confidence interval cheatsheet + +The CI on the lift is the single most important number on the result panel. This cheatsheet covers what it means, what to ignore, and the five decision rules that map a CI to a ship, kill, or wait decision. + +--- + +## What the CI is + +A 95% confidence interval (CI) on a lift estimate is a range of values that, under repeated sampling of the experiment, would contain the true effect 95% of the time. The point estimate (the center) is your best single guess at the true effect. The width is your humility about how much you actually know. + +Three common CI shapes you will see on result panels: + +- Symmetric. Lift estimate +3% with CI [+1%, +5%]. The middle is the best guess; the bounds are equidistant. +- Skewed. Lift estimate +3% with CI [-0.5%, +8%]. Common with small samples or distributions with long tails. The point estimate is still the best guess; the asymmetry tells you the data is consistent with a wider range on the upside than the downside. +- Always-valid (sequential). Same shape as a normal CI but wider by design. Survives daily peeking. If your panel says "anytime-valid CI," that is what you are looking at. + +--- + +## What to read first + +Width before center. A narrow CI tells you a lot about the true effect; a wide CI tells you very little, regardless of where it is centered. A point estimate of +5% with CI [+4.5%, +5.5%] is a precise estimate of a real lift. A point estimate of +5% with CI [-3%, +13%] is essentially "we have no idea, somewhere between a meaningful loss and a huge win." + +The position of zero relative to the CI. If zero is well outside the CI on the positive side, you have a real positive effect. If zero is well outside on the negative side, you have a real harm. If zero is inside the CI, you cannot rule out "no effect." + +--- + +## What to ignore + +The point estimate alone. Without the CI, the point estimate is a single number with no honesty about how much it could move under different sampling. Reading "lift was +3%" without the CI is reading half the result. + +The p-value alone. P-values tell you about the strength of evidence against the null; CIs tell you about the magnitude of the effect. Both matter. A tiny lift with p equals 0.001 is technically significant and not worth shipping. A big lift with p equals 0.10 is technically inconclusive and worth a follow-up test. + +The "statistically significant" label as a binary. Most platforms color-code significance as a green check or a red X. The label is fine as a heuristic; the underlying CI is what you should defend the decision on. + +--- + +## The five decision rules + +### Rule 1: CI all-positive, lift above MDE. Ship. + +**Example.** MDE was 2%; CI is [+3%, +6%]. + +The lower bound of the CI exceeds the MDE you committed to detect. The data is inconsistent with no effect AND inconsistent with a trivial effect. Confidence is high, magnitude is meaningful. Ship. + +Confirm guardrails are clean before filing the launch. + +### Rule 2: CI all-positive, lift below MDE. Probably do not ship. + +**Example.** MDE was 5%; CI is [+0.5%, +1.2%]. + +The lift is real (CI excludes zero) but small (entire CI is below the MDE). The test was overpowered for the question, or the effect is smaller than expected. Real but tiny lifts are rarely worth shipping; the engineering, testing, and cognitive surface area exceeds the gain. + +The exception: changes that are essentially free to ship and maintain. A copy tweak with a +0.5% lift might be worth shipping; a feature requiring ongoing infrastructure with the same lift is not. + +### Rule 3: CI all-negative. Kill. + +**Example.** CI is [-4%, -1%]. + +The data is inconsistent with no effect and inconsistent with a positive effect. The change made things worse with high confidence. Kill the test. Document the lesson if the result is surprising; sometimes the lesson is "users wanted what we already had." + +### Rule 4: CI straddles zero, narrow. Real null result. + +**Example.** CI is [-0.5%, +0.8%]. + +Zero is inside the CI, but so is everything else within a small range. The data is consistent with no effect and inconsistent with any meaningful positive or negative effect. This is a real "we tested and it does not move the metric" result. Useful information; do not ship for "lift" reasons (you found none) but do not panic about harm either. + +The product question becomes: does the change have value beyond the metric we measured (brand consistency, code maintainability, accessibility)? If yes, ship for those reasons. If no, do not ship. + +### Rule 5: CI straddles zero, wide. Inconclusive. + +**Example.** CI is [-5%, +8%]. + +Zero is inside the CI and so is a wide range of meaningful effects in both directions. The data does not distinguish "moderate win" from "no effect" from "moderate loss." The test was underpowered for the question. + +Three follow-up paths: + +- Run longer or run bigger to narrow the CI. +- Make the treatment bolder so the expected effect is larger and detectable at the available traffic. +- Accept that the question cannot be answered cleanly and move on. + +The temptation is to ship anyway because "the point estimate was favorable." The point estimate is not evidence when the CI is this wide. Resist. + +--- + +## Pairing the CI with guardrails + +The CI on the primary metric is where the ship decision lives. The CI on each guardrail is where the safety check lives. Read both. + +A guardrail CI that excludes the threshold of concern is clean. For example, if retention is a guardrail and you require it to not drop more than 1%, a guardrail CI of [-0.3%, +0.4%] is clean. A CI of [-2%, +0.5%] is not clean even though it includes zero, because the lower bound exceeds the threshold. + +Wide guardrail CIs mean the test was underpowered for the guardrail. That is a real problem: you cannot claim safety on a metric you did not measure precisely. The fix is more sample, not "the point estimate looked fine." + +--- + +## Worked example: the "looks great" trap + +**Setup.** PM running a checkout redesign. Pre-committed primary: revenue per visitor. MDE: 3%. Guardrail: refund rate not increasing by more than 0.5%. + +**Day 5.** Result panel shows revenue per visitor +6%, p equals 0.03, CI [+0.5%, +11.5%]. Refund rate +0.3%, CI [-0.4%, +1.0%]. + +**The temptation.** Both metrics moved favorably; the headline is significant. PM proposes ending the test early. + +**The CI read.** Revenue CI [+0.5%, +11.5%] has a lower bound (+0.5%) below the MDE (+3%). The data is consistent with a real but tiny lift, not just the headline +6%. The guardrail CI [-0.4%, +1.0%] has an upper bound (+1.0%) that exceeds the threshold (+0.5%); the test cannot rule out a guardrail violation. + +**The right call.** Do not ship yet. Run to the pre-committed end date. Both CIs need to narrow before the ship case is defensible. The day-5 read is suggestive but not decisive; it is exactly the case the pre-commitment discipline was designed to handle. + +**Common variant.** PM ships anyway because "the trend is positive." Three weeks later the launch shows a refund rate increase that wipes out the revenue gain. The day-5 CI was warning of this exact possibility; the team did not read the width. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md b/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md new file mode 100644 index 0000000..072b959 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md @@ -0,0 +1,87 @@ +# Dashboard vs experiment reconciliation + +The scenario: the BI dashboard shows revenue grew 8% last week, the experiment platform shows the treatment lifted revenue 2%, and an executive asks how both can be true. This reference covers the common reasons numbers disagree, the blended-attribution trap, and how to communicate the difference. + +--- + +## Why numbers disagree (in order of frequency) + +**Different denominators.** The dashboard is computed across all users (or all sessions, or all transactions). The experiment is computed across enrolled users only. If 30% of users are enrolled in the experiment, the experiment lift applies to roughly 30% of the metric base; the dashboard sees the entire base. A 2% lift on the enrolled 30% looks like roughly 0.6% on the dashboard, even if everything is working perfectly. + +**Different time windows.** The dashboard shows rolling seven days; the experiment shows fixed start to end. Comparing a moving window to a fixed window is comparing two different summaries of overlapping but distinct data. + +**External effects.** Marketing campaigns, seasonality, news cycles, competitor moves, weather. The experiment correctly excludes these by random assignment (treatment and control see the same external effects, so they cancel in the lift estimate). The dashboard reflects them in full. The dashboard moving up has nothing to do with the experiment moving up. + +**Selection effects in enrollment.** Who is enrolled matters. New users only? Logged-in only? Users who passed a feature flag check? Each filter changes the population the experiment lift applies to, and changes how that population's behavior compares to the dashboard total. + +**Different metric definitions.** "Revenue" might be gross in the dashboard and net of refunds in the experiment. "Conversions" might count differently across systems (does a re-purchase count? a subscription renewal? a free trial activation?). Definitional drift between systems is common and almost always under-investigated. + +**Pipeline lag.** The dashboard is real-time or near-real-time. The experiment is computed on a daily batch with attribution windows that delay the metric by hours or days. Comparing a real-time number to a batched-and-attributed number is comparing two different versions of the truth. + +**Different attribution models.** First-touch vs last-touch vs multi-touch attribution can produce wildly different "revenue" numbers from the same underlying events. The dashboard and the experiment might use different models without anyone realizing. + +--- + +## The blended attribution trap + +The most common reconciliation failure: take the experiment lift and multiply by the total user base for company-wide impact. + +**The wrong calculation.** Experiment shows +2% revenue per user. Total active users: 5 million. "The feature drove $X million in incremental revenue." + +**Why it is wrong, twice over.** + +- The lift only applies to enrolled users, not the total base. If 30% of users are enrolled, the in-test impact is roughly 30% of what the multiplication suggests. +- Even within enrolled users, the lift was measured during the test conditions. Long-term and at full scale, the effect can be smaller (novelty fade, interference effects, market saturation) or sometimes larger (network effects that compound, learning effects). + +**The right framing.** "During the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control. Extrapolating to a full launch requires assumptions about how the effect translates at scale; the simple multiplication ignores those assumptions." + +The right framing is longer. Stakeholders sometimes push back on the precision. The precision is the point: the simple version is wrong, and shipping based on the simple version produces forecasts that do not materialize. + +--- + +## How to communicate to non-statistical stakeholders + +The temptation is to translate the experiment result into a single number that sounds like the dashboard. The translation is usually wrong because the two numbers are answering different questions. + +**Better framings:** + +- "The experiment is asking 'does this change move the metric for users who see it?' The dashboard is asking 'how is the metric trending overall?' Both can move independently and both can be true at the same time." +- "The experiment lift applies to enrolled users, in test conditions, during the test window. Translating to a launch forecast requires assumptions about scale, novelty, and interference." +- "If we ship to everyone, we expect the dashboard to move by roughly [X percent of the lift], plus or minus [a wide range], because of [specific assumptions]." + +**Worse framings to avoid:** + +- "The feature drove $X million in revenue this week." (Conflates the experiment lift with the dashboard movement.) +- "We hit our target." (When the target was set against the dashboard but the result is from the experiment.) +- "The lift was bigger in production than in the test." (Usually a sign of confounding, not vindication.) + +--- + +## When to dig into discrepancies vs accept them + +**Dig in when:** + +- The experiment shows a big effect and the dashboard shows nothing. The experiment is making a claim that the launch did not deliver. Either the experiment was wrong (selection effect, pipeline bug, confounder) or the launch is being measured wrong. +- The experiment shows nothing and the dashboard shows a big effect. The experiment is missing a real movement. Either the test was underpowered, the wrong population was enrolled, or the dashboard movement is from external factors. +- The directions disagree (experiment positive, dashboard negative). Almost always indicates a definitional drift or pipeline issue that needs investigation. + +**Accept the discrepancy when:** + +- The magnitudes are different but the directions agree. Usually a denominator or selection issue; document the explanation and move on. +- The dashboard is volatile and the experiment is stable. The dashboard reflects external noise the experiment correctly excludes. +- The dashboard is stable and the experiment showed a small effect. The launch effect is too small to detect in the dashboard's noise. + +--- + +## A reconciliation checklist for the moment of confusion + +When a stakeholder asks "why do these numbers not match?", run through this: + +1. **Same metric definition?** Confirm the experiment and dashboard are computing the metric the same way. Check the definitional doc for both. Ask the data team if there is no doc. +2. **Same denominator?** Confirm the experiment population and the dashboard population. Often they differ. +3. **Same time window?** Confirm the experiment window and the dashboard window are aligned (or explain why they are not). +4. **Any external events?** List campaigns, launches, outages, holidays during the test window. The dashboard reflects them; the experiment cancels them. +5. **Any pipeline lag?** Confirm both numbers are using the same attribution and the same data freshness. +6. **Any selection effects?** Who got enrolled and how? If enrollment was non-random (by feature flag check, by cohort), the experiment population is not representative of the dashboard population. + +If all six check out and the numbers still disagree by a meaningful amount, escalate to data engineering. There is probably a pipeline bug in one of the two systems. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md b/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md new file mode 100644 index 0000000..55e87f5 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md @@ -0,0 +1,118 @@ +# P-value interpretation guide + +The p-value is the most-mentioned and most-misunderstood number on the result panel. This guide covers what it actually means, what people pretend it means, when the 0.05 cutoff binds and when it does not, and how to read p-values alongside the CI. + +--- + +## What the p-value is + +The p-value is the probability of observing the lift you saw (or one larger in magnitude), IF the true effect were zero. It is computed under the assumption that the treatment had no effect; the value tells you how surprised you should be by the observed data under that assumption. + +A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. A p-value of 0.001 means it would happen 0.1% of the time. Smaller p-values are stronger evidence against the null; larger p-values are weaker evidence. + +That is the whole technical definition. Everything else is interpretation, and most of it is wrong. + +--- + +## What the p-value is not + +These are the most common misinterpretations. Each one is wrong for a specific reason. + +**"P equals 0.04 means 96% chance the treatment works."** No. The p-value is computed under the assumption that the treatment does NOT work; it cannot tell you the probability that it does. The Bayesian probability of the alternative depends on the prior, which the p-value does not contain. + +**"P equals 0.001 means the effect is huge."** No. P-values are about the strength of evidence against the null, not the size of the effect. A tiny effect tested against a very large sample produces a tiny p-value. The CI tells you the size; the p-value tells you the certainty. + +**"A significant result will replicate."** Not necessarily. A p-value of 0.05 is associated with replication rates well below 50% in most published research. Statistical significance is one piece of evidence; reproducibility requires confirmation. + +**"P greater than 0.05 means there is no effect."** No. P-values cannot prove the null. A non-significant result means "we do not have enough evidence to reject no-effect," which is weaker than "no-effect is true." The CI tells you the practical conclusion: a wide CI straddling zero is "we do not know," while a narrow CI around zero is "the effect is small enough to call zero." + +**"P equals 0.06 is much worse than p equals 0.04."** No. The 0.05 cutoff is convention; the underlying evidence is roughly the same. Treating 0.06 as categorically different from 0.04 is theater unless you pre-committed to the cutoff. + +--- + +## The 0.05 convention + +Alpha equals 0.05 is the standard significance threshold by historical convention, not because the math says 0.05 is special. The convention is useful because it provides a shared reference point, and pre-committing to a threshold prevents post-hoc rationalization. + +Two valid uses of the threshold: + +- **Pre-committed alpha.** You declared at design time that you would ship if p was less than 0.05 and the CI excluded zero. Now apply the rule mechanically. If the result hit 0.04, follow the pre-commitment. +- **Convention reference point.** When communicating with stakeholders, "significant at the conventional 5% threshold" is a familiar phrasing. Use it as long as the underlying CI is also reported. + +Two invalid uses: + +- **Post-hoc threshold games.** Result is p equals 0.06; you decide that 0.10 is "good enough this time." This is p-hacking. +- **Treating the threshold as a binary truth.** Result is p equals 0.04; you ship without reading the CI. The threshold is necessary but not sufficient evidence to ship. + +--- + +## Always read the CI alongside the p-value + +The p-value tells you about the null hypothesis. The CI tells you about the magnitude. They answer different questions, and decisions need both answers. + +| Scenario | P-value | CI on lift | Decision | +|---|---|---|---| +| Real, meaningful effect | 0.001 | [+3%, +6%] | Ship if guardrails clean | +| Real but tiny effect | 0.001 | [+0.2%, +0.4%] | Probably do not ship; magnitude too small | +| Suggestive but uncertain | 0.08 | [-0.5%, +12%] | Inconclusive; run longer or kill | +| Inconclusive null | 0.30 | [-1%, +1%] | Real null result; do not ship for lift reasons | +| Inconclusive wide | 0.30 | [-7%, +9%] | Underpowered; not enough information | + +Reading just the p-value loses the magnitude. Reading just the CI loses the certainty calibration. Both are routine on every result panel; both deserve attention. + +--- + +## The peeking problem + +Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. + +The math: at one analysis, alpha equals 5% means 5% false positive rate. At three analyses, it climbs toward 14%. At daily peeking on a four-week test, it can exceed 30%. The "significant" results you find by peeking are disproportionately false positives that will not replicate. + +Two fixes: + +- **Sequential testing methods.** Modern platforms (Statsig, Eppo, GrowthBook with mSPRT, parts of PostHog) report "always-valid" or "anytime-valid" p-values that survive peeking. The math is wider by design; the cost of peek-safety is some statistical efficiency. +- **Pre-commitment.** If your platform does not support sequential testing, declare the analysis date at launch and do not peek. If you must peek (some platforms make it hard not to), do not make decisions on intermediate peeks. + +If your panel says "p-value" without a qualifier, assume fixed-horizon. Treat early-peek results as suggestive only. + +--- + +## Multiple testing context + +A p-value of 0.05 means a 5% false positive rate per comparison. With twenty comparisons, you expect one false positive purely by chance. + +Where this matters: + +- Multiple variants (A vs B vs C vs D is three pairwise tests). +- Multiple metrics (primary plus six guardrails plus three secondary is ten chances). +- Multiple segments (ten segments times three metrics is thirty chances). + +Pre-register the primary metric and primary segment. Treat the rest as exploratory. A "significant" finding in a non-primary metric or non-primary segment requires either a larger effect, a follow-up test, or both before it justifies shipping. The discipline of pre-registration protects you from the multiple-testing trap better than any correction formula. + +When the platform applies a correction (Bonferroni, Benjamini-Hochberg) silently, the p-values you see have already been adjusted. Know which the platform applies by default; otherwise you may double-correct in your interpretation. + +--- + +## Bayesian alternatives + +Some platforms (Eppo by default, Statsig as a configuration option) report Bayesian probabilities rather than frequentist p-values. The vocabulary differs: + +- "Probability variant B is best": the Bayesian equivalent of multi-variant frequentist comparison. +- "Probability of beating control by at least X%": directly answers the magnitude question that frequentist p-values dance around. +- "Posterior credible interval": the Bayesian analogue of the confidence interval, with an interpretation closer to lay intuition ("there is a 95% chance the true effect is in this range"). + +For most PM contexts, both approaches produce similar ship decisions when the experiment was designed correctly. Pick one per experiment and stick with it. Switching mid-flight to chase a more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +--- + +## Communicating p-values to non-technical stakeholders + +Stakeholders often want a one-sentence summary. The temptation is "p equals 0.04, so we should ship." The temptation is wrong because it loses the magnitude. + +Better one-liners: + +- "We saw a 4% lift in revenue per visitor; the data rules out no-effect and is consistent with a 2% to 6% true lift." +- "The test was inconclusive: the lift could be anywhere from a small loss to a moderate win." +- "We measured a small but real effect: about 0.5% lift, which is statistically detectable but probably not worth shipping." + +Each names the magnitude, the uncertainty, and the decision implication. None reduces the question to a p-value threshold check. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md b/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md new file mode 100644 index 0000000..a89bd8e --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md @@ -0,0 +1,123 @@ +# Result presentation templates + +Five templates for stakeholder communication on experiment results. Each names the structure, the vocabulary, what to emphasize, and what to omit. Use the right template for the result you have, not the one that flatters the team. + +--- + +## Template 1: Clear win + +**When to use.** Primary metric moved past MDE, CI on lift excludes zero, all guardrails clean, pre-registered segments consistent. + +**Structure.** + +1. **Headline.** "We are shipping [feature]. The test showed a [X percent] lift in [primary metric] with [Y percent] confidence. Guardrails are clean." +2. **The number.** Point estimate of the lift, with the CI in parentheses. "Revenue per visitor lifted 4.2% (CI [+2.8%, +5.6%])." +3. **Magnitude in business terms.** "At our enrolled traffic, that is roughly [$Z] in incremental [period] revenue from this cohort. Full-launch impact depends on rollout assumptions." +4. **Guardrails.** One line per guardrail confirming it stayed within tolerance. +5. **Decision and timing.** "Filing the launch this week. Post-launch monitoring at days 7, 14, and 30." + +**Vocabulary to use.** "Real lift," "high confidence," "exceeds the threshold we committed to," "shipping." + +**Vocabulary to avoid.** Superlatives ("dramatic," "unprecedented," "transformative"). The number speaks; superlatives do not add to it. + +**What to omit.** Long discussion of why the test worked, deep statistical detail, exhaustive caveats. The headline result is clean; the writeup should be too. + +--- + +## Template 2: Clear loss + +**When to use.** Primary metric moved against expected direction with significance, OR a guardrail was violated. + +**Structure.** + +1. **Headline.** "We are not shipping [feature]. The test showed [a negative effect / a guardrail violation]." +2. **The number.** Point estimate and CI. Be precise about which metric showed the issue. +3. **Likely cause, if known.** Brief diagnosis: "Conversion dropped because users did not understand the new flow. Session recordings confirm confusion at step three." +4. **What we learned.** One or two sentences naming the lesson for the next hypothesis. +5. **Decision and follow-up.** "Killing the test. Filing the learning in the team retrospective. Considering [follow-up direction] as a next test." + +**Vocabulary to use.** "The test showed," "killing," "the change made things worse on [metric]," "we learned." + +**Vocabulary to avoid.** "Failed" applied to the team. "Setback." Defensive language. The test produced a clear answer; the team did its job. + +**What to omit.** Speculation about what would have happened with a different design. Excessive postmortem detail. The kill is the right decision; do not over-justify it. + +--- + +## Template 3: Inconclusive (the most common, hardest) + +**When to use.** Primary metric did not clearly move past MDE, CI is wide, OR guardrails are clean but signal is weak. The most frequent real outcome and the hardest to communicate without slipping into "we should ship anyway." + +**Structure.** + +1. **Headline.** "The test was inconclusive. We do not have enough signal to ship and we do not have enough signal to kill." +2. **The number.** Point estimate and the wide CI. Name the width: "Lift was +1.8%, but the CI is [-2.1%, +5.7%]; the data is consistent with a moderate win, no effect, or a moderate loss." +3. **What we know vs what we do not.** "We can rule out a large negative effect. We cannot distinguish a small positive effect from no effect. We cannot say whether shipping would help or hurt." +4. **The three resolution paths.** + + - Run bigger or longer: extend the test to narrow the CI. Cost: [time and traffic]. Benefit: a clearer answer. + - Make the treatment bolder: redesign with a larger expected effect, then re-test. Cost: design and engineering effort. Benefit: addresses the underlying mechanism rather than the measurement. + - Kill the idea: accept that the change does not produce a meaningfully detectable effect at our traffic. Cost: closing the hypothesis. Benefit: team time freed for higher-signal work. +5. **Recommendation.** Pick one path and explain why. +6. **Decision.** "Going with [path]. Re-evaluating in [timeframe]." + +**Vocabulary to use.** "Inconclusive," "the data does not distinguish," "we cannot confidently say," "the right call is to [chosen path]." + +**Vocabulary to avoid.** "Trending positive," "directional improvement," "looks promising." These are the phrases that get teams to ship inconclusive tests; they are wishful reading of noise. + +**What to omit.** Pleas to ship "since we are already here." Optimistic projections of what the lift "would be" with more sample. Alternative analyses that conveniently show significance. + +The hardest version of this template is the case where the team has invested in the hypothesis and the result is inconclusive. The temptation is to find a way to justify shipping. The discipline is to use the structure above and let the inconclusive result be inconclusive. + +--- + +## Template 4: Mixed result (positive primary, ambiguous guardrail) + +**When to use.** Primary metric moved past MDE with clean significance, but a guardrail metric showed concerning movement that did not clearly violate tolerance. + +**Structure.** + +1. **Headline.** "The primary metric moved as expected. A guardrail showed concerning movement; we are [shipping with monitoring / holding for further investigation]." +2. **Primary metric result.** Point estimate and CI. "Conversion lifted 5.1% (CI [+3.4%, +6.8%])." +3. **Guardrail concern.** Specific. "Refund rate point estimate moved +0.4%, with CI [-0.1%, +0.9%]. Pre-committed tolerance was no more than +0.5%. The CI does not clearly violate tolerance, but the upper bound is right at the threshold." +4. **The interpretation question.** "Pre-committed decision rule was 'do not ship if the guardrail CI excludes safe behavior.' The CI does not exclude safe behavior, but it does not exclude a violation either." +5. **Recommendation with reasoning.** Two valid paths: + + - Ship with extra monitoring: production behavior at +1, +2, +4 weeks specifically watching the guardrail. Roll back if it crosses tolerance in production. Acceptable when the primary lift is large and the guardrail risk is reversible. + - Hold and re-test: extend the test to narrow the guardrail CI. Acceptable when the primary lift is marginal or the guardrail is hard to monitor in production. +6. **Decision.** Pick the path. Document the guardrail-specific monitoring or the re-test plan. + +**Vocabulary to use.** "The guardrail CI does not clearly exclude tolerance," "shipping with intensified monitoring," "the pre-committed rule was." + +**Vocabulary to avoid.** "The guardrail did not move significantly" (when the CI does not exclude movement, do not pretend it did). "The primary lift outweighs the guardrail concern" (the guardrail was set as binding for a reason). + +**What to omit.** Reframing the guardrail as a "secondary metric" that does not need to bind. The guardrail was set during pre-commitment; it binds. + +--- + +## Template 5: Long-term holdout report (30 / 60 / 90 days post-launch) + +**When to use.** Reporting back on a feature that shipped with a holdout group, after the holdout period has elapsed. + +**Structure.** + +1. **Headline.** "[Feature] post-launch holdout report at [day count]. Long-term effect [confirms / diverges from / disconfirms] the test result." +2. **Test result reminder.** What the test showed at launch. "At launch, the test measured a +4% lift in [metric]." +3. **Long-term result.** What the holdout shows now. "At day 30, the launched cohort shows a +3.2% lift over the holdout (CI [+1.8%, +4.6%])." +4. **Comparison.** Direct: "The long-term effect is [in line with / smaller than / larger than] the test estimate. [If smaller: the difference is consistent with novelty fade / interference / dilution. If larger: the difference is consistent with network effects / learning effects.]" +5. **Decision implications.** "[Continue the launch as is / revisit the design / consider rollback]." +6. **Holdout disposition.** "[Releasing the holdout into the launched cohort / extending the holdout for another 30 days]." + +**Vocabulary to use.** "Long-term effect," "confirms / diverges from," "novelty fade," "we observe." + +**Vocabulary to avoid.** "Vindication" or "we were right." Long-term reports are about updating the prior, not declaring victory. + +**What to omit.** Excessive celebration of a confirmed lift. Excessive panic about a divergent lift. The report is information for the next decision; let the information drive it. + +--- + +## A note on the "we should report this differently" temptation + +When a result is inconclusive or mixed, there is always a way to slice the data, frame the writeup, or pick the chart that makes the result look more decisive. Resist. + +The cost of overstating an inconclusive result is shipping changes that do not work, eroding trust in the experimentation discipline, and accumulating production complexity for no gain. The cost of accurately reporting an inconclusive result is one round of disappointment from stakeholders who wanted a cleaner answer. The first cost compounds; the second does not. Use the right template for the actual result. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md b/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md new file mode 100644 index 0000000..bb11a4f --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md @@ -0,0 +1,150 @@ +# Statistical method reference + +The technical reference for analysts. Covers the methods named in the [SKILL.md](../SKILL.md) with enough depth to verify a platform's implementation, recognize when a method is needed, and explain the choice to a skeptical reviewer. + +--- + +## CUPED (Controlled-experiment Using Pre-Experiment Data) + +**What it does.** Uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. Same point estimate as the unadjusted analysis; narrower CI. + +**The math, in one paragraph.** For each user, take their in-experiment metric value Y and their pre-experiment metric value X. Compute the regression coefficient theta that relates X to Y in the control group. Replace Y with Y minus theta times (X minus X-bar) for every user. Run the analysis on the adjusted Y. The variance of the adjusted Y is lower than the variance of Y by a factor proportional to the squared correlation between X and Y, which directly narrows the CI. + +**Variance reduction in practice.** Typical reduction is 30% to 50% for engagement metrics, 20% to 40% for revenue metrics, near zero for one-time conversions. Effective sample size roughly doubles when variance halves. + +**When to use.** + +- Metrics with high pre-experiment baseline variance (revenue per user, sessions per user, engagement minutes). +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +**When NOT to use.** + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline. +- Tests where pre-experiment behavior is uncorrelated with the metric being moved (a notification redesign rarely correlates with prior revenue, for example). + +**How to verify your platform implements it correctly.** Ask: "Do you compute theta on control only, or on the pooled population?" Pooled is technically wrong (induces bias). Control-only is correct. "What pre-experiment window do you use?" Common defaults are 14 to 28 days; the choice should be documented. + +**Common confusion.** "CUPED made our lift smaller, so we should report the unadjusted version." Wrong. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. + +--- + +## The delta method + +**What it does.** Provides correct variance estimation for ratio metrics. Naive variance estimation on ratios produces incorrectly narrow CIs and inflated false positive rates. + +**Why ratios are special.** Standard variance formulas assume sums of independent observations. Ratios are functions of two correlated sums (numerator and denominator). The variance of a ratio depends on the variance of the numerator, the variance of the denominator, AND the covariance between them. Naive estimators ignore the denominator variance and the covariance. + +**The math, in one paragraph.** For a ratio R equals N divided by D, the delta method approximates the variance of R using a first-order Taylor expansion around the means of N and D. The result expresses Var(R) as a function of Var(N), Var(D), Cov(N, D), and the means. The approximation is excellent when the sample size is moderate to large, which it is for almost any A/B test. + +**When to use.** + +- Conversion rate (conversions per user, when users can have multiple events). +- Click-through rate (clicks per impression). +- Revenue per user. +- Average order value. +- Any metric expressible as numerator divided by denominator where users can contribute multiple values. + +**When the simple formula is fine.** + +- Per-user binary conversion (one row per user, converted yes or no). The standard proportion variance formula is correct here. + +**Bootstrap as an alternative.** Resample users with replacement many times, compute the ratio each time, read off the empirical CI. Distribution-free; slower than delta method. Both produce similar CIs for typical A/B test sizes. + +**How to verify your platform.** Ask "what variance estimator do you use for ratio metrics?" Acceptable answers: delta method, linearization, bootstrap with user-level resampling. Unacceptable: standard t-test on proportions (wrong for non-binary ratios), bootstrap with row-level resampling (ignores within-user correlation). + +--- + +## Sequential testing methods + +**The peeking problem.** Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Daily peeking on a four-week test can push false positive rate above 30%. + +**Group sequential designs (GSD).** Plan a fixed set of interim analyses (often three) with adjusted significance thresholds at each. The thresholds are computed so the overall false positive rate stays at the nominal alpha. Well-understood; less flexible than always-valid methods. + +**Mixture sequential probability ratio test (mSPRT).** Produces "always-valid" p-values: the false positive rate stays at nominal alpha regardless of how many times you analyze. Common in modern platforms. The math: define a likelihood ratio between the alternative and null hypotheses, integrated over a prior on the effect size. The test rejects when the ratio exceeds 1/alpha. + +**Anytime-valid confidence intervals.** The CI version of always-valid p-values. Produced by taking the inverse of the always-valid test family. Wider than fixed-horizon CIs; the cost of peek-safety is some statistical efficiency, typically 10% to 30% wider. + +**Implementation across platforms.** + +- Statsig: always-valid by default for sequential metrics. +- Eppo: sequential CIs available as a configuration. +- GrowthBook: mSPRT supported. +- PostHog: depends on the experiment type and configuration. +- Optimizely: supports sequential via Stats Engine. +- Amplitude (Experiment): supports sequential testing. + +**How to read the panel.** "Always-valid p-value" or "anytime-valid CI" labels indicate sequential. "P-value" with no qualifier is fixed-horizon; treat early peeks as suggestive only. + +--- + +## Heterogeneous treatment effects (HTE) + +**What HTE is.** The treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. + +**Pre-registered vs post-hoc.** Pre-registered HTE analysis is one of the segment definitions you committed to at design time, with sample size budgeted for the segment. Post-hoc HTE discovery is finding a segment whose effect is large by mining the data; this is noise mining and the apparent lift will not replicate. + +**When to ship segment-only.** Three conditions must all hold: + +- The segment was pre-registered. +- The effect within the segment is large enough to justify shipping. +- The targeting infrastructure exists (or is cheap to build) and the maintenance cost is acceptable. + +If any condition fails, do not ship segment-only. Either ship to everyone (taking the average effect) or do not ship. + +**Methods for principled HTE detection.** + +- Causal forests: machine learning method for estimating heterogeneous treatment effects across many features. +- Conditional average treatment effects (CATE) with regression: model the effect as a function of covariates. +- Pre-registered segment analysis: simpler, more defensible, and sufficient for most PM contexts. + +For most A/B tests, pre-registered segment analysis is the right level of sophistication. Causal forests are useful for marketplace and personalization research where the effect is genuinely expected to vary across many dimensions. + +--- + +## Multiple testing corrections + +**The problem.** With twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty, two or three. + +**Bonferroni correction.** Divide alpha by the number of comparisons. With 20 comparisons, use alpha equals 0.0025 per comparison. Conservative; controls the family-wise error rate (probability of any false positive across the family). + +**Benjamini-Hochberg (BH) correction.** Less conservative; controls the false discovery rate (expected proportion of false positives among the things called significant). Better for exploratory analysis where some false positives are tolerable. + +**When to use which.** + +- Small number of pre-registered comparisons with high stakes: Bonferroni. +- Larger exploratory analysis where some false positives are acceptable: BH. +- Single pre-registered primary metric: no correction needed (one comparison). + +**How platforms apply corrections.** Some platforms apply corrections silently to displayed p-values; others report uncorrected numbers. Know which your platform does. The "5 of 12 metrics significant" headline means very different things depending on whether the p-values were corrected. + +--- + +## Cluster randomization + +**When SUTVA is violated.** SUTVA (Stable Unit Treatment Value Assumption) says one user's treatment does not affect another user's outcome. Violated in two-sided marketplaces, social products, supply-constrained features, and notification systems. + +**Cluster randomization as a fix.** Assign whole units (cities, markets, friend groups, sessions) to treatment or control rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. + +**Trade-off.** A cluster of 1000 users behaves more like one observation than 1000 independent observations. Effective sample size is roughly the number of clusters times the within-cluster correlation factor. Cluster randomization with 50 clusters has roughly the power of a user-randomized test with 200 to 500 users, even if the clusters contain millions of users total. + +**Designing for cluster randomization.** Choose the cluster boundary so that interference happens within clusters but not across them. Cities work for marketplace experiments. Friend groups work for social products. Sessions work for some notification studies. + +**Switchback experiments as an alternative.** Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control). Eliminates cross-user interference within each window. Requires careful temporal modeling because the windows are not independent (carryover effects, day-of-week effects). + +**Detection of SUTVA violation without redesign.** Compare a small cluster-randomized version to the user-randomized version. If the cluster-randomized lift is much larger than the user-randomized lift, the user-randomized test is leaking treatment into control via interference. The user-randomized test is undercounting the effect. + +--- + +## Variance reduction beyond CUPED + +**Stratified sampling.** Pre-stratify users by a known covariate (geography, segment, signup cohort) and randomize within strata. Reduces variance from imbalanced randomization at the cost of slightly more complex analysis. + +**Post-stratification.** Run normal randomization, then adjust the analysis for known covariates after the fact. Similar variance reduction to CUPED for the right covariates. + +**Regression adjustment.** Include covariates as controls in the regression that estimates the treatment effect. Equivalent to post-stratification for one covariate; generalizes to multiple. + +**Doubly robust estimation.** Combines regression adjustment with inverse-probability weighting. Robust to misspecification of either the outcome model or the propensity model. Overkill for most A/B tests; useful for observational analysis and some quasi-experiments. + +For most PM contexts, CUPED plus pre-registered segment analysis covers the variance reduction needs. The methods above are the next step up when the standard tools are insufficient. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md new file mode 100644 index 0000000..ea765c9 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md @@ -0,0 +1,286 @@ +--- +name: experimentation-platform-orchestrator +description: "A platform decision framework for experimentation. When to use Statsig vs PostHog vs GrowthBook vs Optimizely vs Amplitude vs Eppo vs Kameleoon. How to migrate between them. How to coordinate when multi-platform is genuinely warranted. The decisions that compound for years and the ones you can defer. Triggers on which experimentation platform, choose Statsig vs PostHog, evaluate experimentation tools, switch experimentation platform, migrate from Optimizely, consolidate experimentation tools, multi-platform experimentation, experimentation platform decision, ab test platform selection, feature flag platform vs experiment platform, warehouse-native experiments, vendor lock-in experimentation. Also triggers when a team is asking about cost, governance, or migration cost across experimentation tools, or when an evaluation is starting." +category: product +catalog_summary: "Pick the right experimentation platform, migrate when wrong, coordinate when multi-platform: a decision framework for Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon" +display_order: 7 +--- + +# Experimentation Platform Orchestrator + +A senior product and engineering leader's playbook for making the experimentation platform decision and recovering from making it wrong. + +Picking an experimentation platform is one of those decisions that looks easy at the start and compounds for years afterward. The wrong choice costs you in lost experiments (because the team avoids the painful workflow), in cost (because the wrong pricing model penalizes your usage shape), in vendor lock-in (because migration is real engineering work, not a config change), and in cultural drift (because the platform's defaults shape what your team thinks experimentation is). + +This skill is the discipline that makes the decision well the first time and the migration plan when you didn't. + +When to use this skill: choosing a platform from scratch, evaluating whether to switch, deciding whether to consolidate from multi-platform to single, or planning a migration that has already been approved. + +--- + +## What this skill is for + +This skill spans platform selection, multi-platform decisions, migration planning, and governance setup. It does not cover experiment design (use `experiment-design`), result interpretation (use `experimentation-analytics`), or feature flag operations (use `feature-flagging`). Pair this skill with the relevant integrations microsite when you need platform-specific MCP details. + +The audience is a PM, engineering leader, or data lead who is making the decision or recovering from a previous one. The voice is decisive. There is no "it depends, evaluate them all yourself." The decision space has real shape, and a senior advisor can map your situation to a defensible answer in an afternoon. + +--- + +## The 7 considerations for the platform decision + +Every platform evaluation walks the same seven questions. Answer them honestly first, then read the per-platform profiles, then consult the decision matrix. The order matters: data architecture and statistical rigor are foundational; the rest are layered on top. + +1. **Data architecture.** Where does experiment data live? Three patterns. Vendor-native (Statsig, Optimizely) keeps the data in the vendor's storage. Product-suite (PostHog, Amplitude) combines analytics and experiments behind one event pipeline. Warehouse-native (GrowthBook, Eppo) runs SQL on your existing data warehouse. The pattern dictates security review depth, residency, statistical depth, and cost shape. + +2. **Statistical rigor.** Does the platform implement CUPED, sequential testing, the delta method for ratio metrics, and multiple testing corrections? Cheap to verify in a sales call: ask "what variance estimator do you use for ratio metrics?" and "do you support always-valid p-values?" Modern platforms (Statsig, Eppo, parts of PostHog) have these. Older or homegrown platforms often do not. + +3. **MCP availability.** All seven platforms covered here have a first-party or hosted MCP except Eppo (as of May 2026). MCP availability matters more for agentic workflows where AI agents create and read experiments end to end. It matters less for traditional human-driven experimentation. Worth weighting if your team is AI-forward. + +4. **Feature flag integration.** Do experiments and feature flags live in the same platform? Statsig, Optimizely, GrowthBook, and PostHog all unify them. Eppo is experiment-only. Kameleoon is creative-personalization-focused. If you also need feature flag operations as production infrastructure, check `feature-flagging` for the operational discipline; the platform choice has to support both surfaces or you accept a second tool. + +5. **Analytics depth.** Can you see funnels, retention, and cohorts in the same surface as experiment results? PostHog and Amplitude are strongest here (analytics-first products). Statsig has a strong analytics overlay. Optimizely and GrowthBook are experiment-first, with analytics as a supplementary feature. + +6. **Governance and audit.** Who can change targeting in production, who can ship experiments, who can read sensitive metrics? Enterprise tiers (Optimizely, LaunchDarkly Federal) handle this with maturity. Open-source platforms (GrowthBook, PostHog self-hosted) require self-built governance. For regulated industries (healthcare, finance, public sector), this question is the deciding factor. + +7. **Cost shape.** Vendor-native scales with events. Warehouse-native scales with seats and warehouse compute. Product-suite scales with combined event volume across all features. Match the pricing shape to your actual usage shape. A high-traffic startup pays vendor-native pricing differently from a lower-traffic enterprise; pick the shape that is friendly to your trajectory, not just your current month. + +--- + +## Statsig + +Modern experimentation and feature management combined in one platform. CUPED and sequential testing built in. Strong PM-led ergonomics. Used by OpenAI, Notion, Brex, Figma. + +**Strengths.** Fast time to first experiment. Combined experiments and feature flags eliminate the second-tool tax. Statistical rigor is current with the literature. The MCP exposes full CRUD across experiments, gates, dynamic configs, and metrics. + +**Gotchas.** Pricing scales with events, which can become expensive at high scale. The platform has strong opinions about how experiments should run; teams that want a custom statistical workflow will fight the defaults. Self-host is not a first-class option. + +**Ideal customer.** Fast-growing SaaS that wants one platform for flags and experiments, values out-of-the-box statistical depth, and is comfortable with vendor-native data architecture. + +--- + +## PostHog + +Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics. Free tier available. + +**Strengths.** Full-funnel context. Experiments live next to the analytics that contextualize them. The MCP exposes 200+ tools (use scoping like `?features=` to keep the agent context tight). Self-host option is mature. Open-source license keeps you outside the vendor lock-in trap. + +**Gotchas.** Combined event volume across all features can make pricing surprising at scale. The breadth of features can make onboarding feel busy. Statistical depth in experiments is good but a step behind dedicated experiment platforms (Statsig, Eppo) on advanced features like CUPED defaults. + +**Ideal customer.** Product-led-growth SaaS that wants analytics, experiments, and feature flags in one surface, values open-source flexibility, and is comfortable with the breadth. + +--- + +## GrowthBook + +Open-source warehouse-native experimentation. Data stays in your warehouse (Snowflake, BigQuery, Redshift, Postgres). Self-host or cloud. + +**Strengths.** Data sovereignty. Cost control at scale because the warehouse is already paid for. First open-source production MCP for experimentation per their announcement. Mature statistical defaults including Bayesian and frequentist toggles. Bring-your-own metrics from the warehouse means experiment metrics match analytics metrics by definition. + +**Gotchas.** Setup overhead is higher than vendor-native. You own the warehouse compute cost (this is usually a feature, not a bug, but it shows up in different finance line items). Smaller community than Statsig or PostHog. UI polish lags vendor platforms by half a step. + +**Ideal customer.** Data-mature teams that already run a warehouse, regulated industries that need data residency, and teams that prefer open-source for the exit option. + +--- + +## Optimizely + +Long-time enterprise leader. Web Experimentation plus Feature Experimentation. Strong personalization and visual editing for non-technical users. + +**Strengths.** Enterprise governance is mature. Visual editing lets marketers ship experiments without engineer help. Strong customer success organization. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai. + +**Gotchas.** Expensive. Pricing targets marketing budgets, not engineering budgets. The product has decades of accumulated features; navigating it takes time. Statistical defaults are conservative but the platform is not the place to look for the latest variance reduction techniques. + +**Ideal customer.** Marketing-led organizations, enterprises with mature experimentation programs, and teams where non-technical experiment creation is a hard requirement. + +--- + +## Amplitude + +Behavioral analytics platform with experiments and feature flags as additional features. Hosted MCP available to all customers including the free tier. + +**Strengths.** If your team already lives in Amplitude for analytics, adding experiments is the path of least resistance. Cohort and behavioral segmentation are excellent. Free tier (10M events/month) is generous. + +**Gotchas.** Experiments are a secondary feature, not the headline. Statistical depth is moderate. If experimentation is your team's primary discipline, Amplitude is rarely the right choice; if experimentation is a supporting capability and analytics is the headline, it works. + +**Ideal customer.** Analytics-first teams that need experiments as a supplementary capability, not the centerpiece. Pre-PMF teams that want a free tier with analytics and experiments together. + +--- + +## Eppo + +Warehouse-native, statistically rigorous, used by Twitch, DraftKings, Perplexity. Strong statistical defaults including Bayesian and frequentist toggles, sequential testing, and CUPED. + +**Strengths.** Statistical correctness is the headline. The team is heavy on data scientists and statisticians, and it shows in the defaults. Warehouse-native architecture matches the pattern data-mature teams already run. Reporting is clear and oriented to decisions. + +**Gotchas.** No first-party MCP as of May 2026. REST API only. If your workflow depends on AI agents reading and writing experiments, Eppo is currently a gap. Track for a future MCP release. Pricing is enterprise; no meaningful free tier. + +**Ideal customer.** Data-team-led organizations where statistical correctness is paramount, the warehouse is already the system of record, and AI agent workflows are a future concern rather than a current requirement. + +--- + +## Kameleoon + +Specialty platform focused on the winning-experiment-to-production-code workflow. AI-driven personalization. Hosted MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. + +**Strengths.** Converts marketing-site experiment wins into permanent React components, which is a real workflow that other platforms force teams to handle manually. AI-driven personalization for content sites. The MCP is purpose-built for the win-to-code path. + +**Gotchas.** Narrower than the others. Not a replacement for Statsig or Optimizely on product experiments. Often shows up alongside another platform rather than as the primary. + +**Ideal customer.** Teams running experiments on marketing or content sites that need the winning variant to become permanent code. Almost always layered with a primary product-experiment platform. + +--- + +## Decision matrix: which platform for which context + +The matrix lives in [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) with worked examples. The summary: + +- Pure SaaS, fast-growing, want one platform for flags and experiments. Choose Statsig. Choose PostHog if you also want analytics. +- Open-source preference, want data sovereignty, warehouse-native. Choose GrowthBook or Eppo. +- Enterprise, marketing-led, deep personalization. Choose Optimizely. +- Already deeply on Amplitude for analytics. Stay on Amplitude unless statistical depth becomes the bottleneck. +- Data-team-led, statistical correctness paramount, MCP not yet required. Choose Eppo. +- Need to convert marketing-site wins into production code. Add Kameleoon alongside your primary platform. +- Regulated industry (HIPAA, FedRAMP), self-hosting required. Choose GrowthBook self-hosted. PostHog self-hosted is also viable. +- Pre-PMF startup, low traffic, need a free tier. Use PostHog free tier or Statsig free tier; defer the real decision until traffic justifies the cost calculation. +- 100M+ events per month, cost control is the headline constraint. Choose GrowthBook or Eppo. Warehouse-native pricing scales better at this volume. +- AI-forward team, MCP-first workflow. Choose Statsig, PostHog, or Optimizely. Defer Eppo until its MCP ships. + +--- + +## Multi-platform: when warranted, when a mess + +Multi-platform is warranted when the surfaces are genuinely different and the platforms overlap zero. Marketing site personalization on Kameleoon plus product experiments on Statsig is a clean split: different surface, different audience, different metric set, no overlap. The cost of the second tool is justified because the workflows do not collide. + +Multi-platform is a mess when the surfaces overlap. Running both Statsig and Optimizely for product experiments creates duplicate cost, split data, and a "which one is the source of truth" problem that surfaces in the worst possible moment, which is when a leadership disagreement needs an answer. + +The 80/20 rule. Eighty percent of teams should pick one platform and consolidate. The 20% with genuine multi-surface needs (marketing site plus product app plus content site) can justify multi-platform with clear ownership boundaries. + +When multi-platform is genuine, three coordination patterns are non-negotiable. An ownership matrix names which platform owns which surface. Shared metric definitions ensure that "activation rate" computes the same way in both platforms (this is hard, and it is the reason most multi-platform setups quietly drift). Reconcilable dashboards let you see the same metric across both platforms with the same definitions. Detail in [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md). + +--- + +## Migration patterns + +Migration is the unglamorous engineering work that makes the platform decision recoverable. Five common paths. + +**Statsig to PostHog.** Typical when a company outgrows pure experimentation and wants analytics plus experiments combined. Effort: 3 to 5 engineer-weeks. Parallel-run for 4 to 8 weeks, validate experiments produce the same results on both, cut over once trust is established. + +**Optimizely to Statsig.** Typical under budget pressure or modernization. Effort: 4 to 8 engineer-weeks. Audit for feature parity first (Optimizely has personalization features Statsig does not). Migrate experiments before flags. Retire Optimizely only after all in-flight experiments complete on the old platform. + +**PostHog to Eppo.** Typical when statistical rigor becomes the binding constraint and the warehouse is already the system of record. Effort: 6 to 10 engineer-weeks. Often results in PostHog staying for analytics and Eppo running experiments. Plan for the dual-platform end state, not a clean replacement. + +**GrowthBook to Eppo.** Typical when commercial support and deeper statistical features become worth the price. Effort: 2 to 4 engineer-weeks because both are warehouse-native; the data already lives in your stack. + +**Any to Statsig.** Typical consolidation move from multi-platform mess. Effort scales with the number of platforms and in-flight experiments; a clean consolidation can run 6 to 12 engineer-weeks. + +The migration discipline is in [`references/migration-playbook.md`](references/migration-playbook.md). Three rules apply to every migration: do not parallel-run forever, do not big-bang switch, and do not retire the old platform before all in-flight experiments complete. + +--- + +## The cost reality + +Plain talk. Vendor-native (Statsig, Optimizely) bills on events, typically $0.10 to $0.50 per million events. Easy to predict at small scale, painful at very high scale. Warehouse-native (Eppo, GrowthBook paid) bills on seats and warehouse compute; $5K to $50K per year is the typical range for paid tiers, with warehouse compute showing up on a different finance line. Product-suite (PostHog, Amplitude) bills on combined event volume across all features; often the most cost-effective when used heavily and the most expensive when only experiments are needed. + +Free tiers. PostHog gives 1M events per month free. Statsig gives 1M events free. Amplitude gives 10M events per month free with basic features. GrowthBook is free open-source. Optimizely and Eppo do not have meaningful free tiers. + +The trap. Optimizing for sticker price ignores total cost. Total cost includes engineer time, statistical correctness (a wrong-result experiment can cost more than a year of platform fees), governance overhead, and migration risk. Sticker price matters for finance; total cost matters for product velocity. Detail and finance conversation patterns in [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md). + +--- + +## Governance and team fit + +Permission tiers, approval workflows, audit trails, and environment promotion are the four pillars of governance. Who creates experiments, who modifies targeting in production, who reads sensitive metrics, who approves a rollout. Enterprise tiers handle these out of the box. Open-source self-hosted requires you to build them, which is fine if you have the engineering capacity and a dealbreaker if you do not. + +Team fit shapes the decision more than most evaluations admit. PostHog and GrowthBook suit engineer-led and PLG teams. Optimizely suits marketing-led teams. Eppo and GrowthBook suit data-team-led teams. Statsig suits PM-led teams. The platform's defaults will pull your team's experimentation culture in the direction of its primary user; pick the alignment that matches who you actually want running experiments. + +Onboarding cost. How long until a new PM can ship their first experiment? Statsig and PostHog: hours to days. Optimizely: days to weeks. Eppo and GrowthBook: depends on whether the warehouse and metrics are already wired in (days if yes, weeks if no). Detail in [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md). + +--- + +## The MCP capability layer + +For AI-forward teams, the MCP capability layer is becoming the deciding factor. The current state as of May 2026: + +- All seven covered platforms have first-party or hosted MCPs, with the exception of Eppo. Eppo offers REST API only. +- Capability differs by an order of magnitude. PostHog exposes 200+ tools; Kameleoon exposes 7. More is not better; the right size depends on your workflow. +- For agentic workflows where AI agents run experiments end to end, prefer platforms with full CRUD via MCP: Statsig, PostHog, GrowthBook, Optimizely. +- For human-driven workflows where MCP supplements human action, any of the seven works (Eppo via the REST path). + +MCP availability is evolving fast. Check the current state of any platform before committing. Eppo is worth tracking for a future MCP release that would close its current gap. Side-by-side capability matrix in [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md). + +--- + +## When to defer the decision + +Sometimes the right answer is "not now." Four cases. + +Pre-PMF. Experimentation infrastructure is premature. Use a free tier (PostHog or Statsig) to remove blockers, defer the real decision until you have enough traffic to make any platform meaningful. + +Single-experiment validation. Do not pick a platform for one experiment. Use whatever is free and easy. The platform decision is for the team that runs experiments as a discipline, not the team running its first. + +No experimentation culture yet. Tooling does not fix culture. If your team is not running experiments, picking a fancy platform will not change that. Build the culture first; the platform decision becomes obvious once experiments are flowing. + +Pending acquisition or major pivot. Defer until the dust settles. The acquirer will likely have a preferred platform anyway. + +--- + +## Common mistakes + +Twelve patterns recur across platform decisions. The short version: + +- Picked the cheapest. Total cost dominates sticker price. +- Picked the most-featured. Features you do not use are technical debt. +- Tried multi-platform first. Almost always becomes a consolidation project later. +- Outgrew the platform but stayed for migration cost. The platform tax compounds; migration cost is fixed. +- Picked based on a demo. Demos optimize for the show; real usage reveals real tradeoffs. +- Did not check governance. Discovered after rollout that anyone can modify production targeting. +- Picked a platform that does not fit team type. PM-led team on a marketing-led platform is constant friction. +- Underestimated the warehouse setup. Warehouse-native platforms expect the warehouse to already be there. +- Skipped statistical depth review. Then a critical experiment surfaced a wrong-result decision. +- Ignored MCP trajectory. Picked a platform without MCP for an AI-forward team. +- Locked the brief on the demo, not the trial. Brief assumptions did not survive contact with real usage. +- Renewed without re-evaluating. The market changed; the brief did not. + +Detail in [`references/common-mistakes.md`](references/common-mistakes.md) with symptoms, root causes, fixes, and prevention. + +--- + +## The framework: 11 considerations for sustainable platform choice + +When choosing or evaluating an experimentation platform, walk these 11 considerations. Answer each one before reaching a recommendation. Skipping any of them is how teams end up in a migration project a year later. + +1. **Data architecture.** Vendor-native, product-suite, or warehouse-native. The pattern is downstream of every other decision. +2. **Statistical rigor.** CUPED, sequential testing, delta method for ratio metrics, multiple testing corrections. Verify at the sales-call level; do not assume. +3. **MCP availability.** Current capability and trajectory. Weight higher if your team is AI-forward. +4. **Feature flag integration.** Same platform or separate. Decide once and live with the implications. +5. **Analytics depth.** Funnels, retention, cohorts in the same surface. Decides whether you need a second tool for the analytics layer. +6. **Governance.** Permissions, audit, approval workflows, environment promotion. Non-negotiable for regulated industries. +7. **Cost shape.** Events vs seats vs warehouse compute. Match the shape to your usage trajectory. +8. **Team fit.** PM-led, engineer-led, data-led, marketing-led. The platform's defaults will pull your culture in the direction of its primary user. +9. **Onboarding cost.** Time to first experiment for a new team member. Faster is better; varies wildly across platforms. +10. **Migration cost.** What is the exit plan if you choose wrong. Higher migration cost means higher confidence required at decision time. +11. **Multi-platform fit.** Does this layer cleanly with platforms you already have, or does it create overlap. + +The output of this framework is one of three answers. A primary recommendation with reasoning. A short list of two if the situation is genuinely ambiguous. A "defer" if a precondition is not met (no traffic, no culture, pending pivot). + +--- + +## Reference files + +- [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) - Context-to-platform matrix with worked examples for the most common decision contexts. +- [`references/migration-playbook.md`](references/migration-playbook.md) - Step-by-step migration patterns for the five common migrations including effort estimates and validation approaches. +- [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md) - Side-by-side MCP capability matrix across the seven platforms. +- [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md) - Ownership boundaries, shared metric definitions, and reconciliation dashboards for genuine multi-platform setups. +- [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md) - Pricing shapes, real-world cost ranges at different traffic tiers, and finance conversation patterns. +- [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md) - Permission tiers, audit trail requirements, environment promotion rules, and team fit assessment. +- [`references/common-mistakes.md`](references/common-mistakes.md) - Twelve failure patterns with symptom, root cause, fix, and prevention for each. + +--- + +## Closing: when in doubt, pick boring + +When the analysis is genuinely ambiguous, pick the boring choice. Boring means mature, well-documented, large user base, and a recoverable migration if you turn out to be wrong. Statsig is boring for SaaS. PostHog is boring for product-led growth. Optimizely is boring for enterprise. GrowthBook is boring for warehouse-native. + +Boring is not the optimum, but it is almost never wrong. The optimum can come later, when the situation has clarified and the team has the experience to know what it actually needs. The cost of picking boring is a small efficiency tax. The cost of picking exotic and being wrong is a migration project that interrupts a year of product work. + +If the team disagrees on which boring choice is the right one, that is a data signal: the situation is not yet clear enough for any answer to be obviously correct. Run a 30-day trial on the top two, evaluate against the 11-consideration framework with real usage data, and pick. Do not skip the trial; demos lie about real usage in ways that only the trial reveals. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md new file mode 100644 index 0000000..bbf1200 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md @@ -0,0 +1,155 @@ +# Common mistakes + +Twelve failure patterns that recur in platform decisions. For each: name, symptom, root cause, fix, and prevention. + +--- + +## 1. Picked the cheapest + +**Symptom.** Six months in, the team is paying more in engineer time than they saved on the platform fee. Velocity is below the pre-decision projection. + +**Root cause.** Sticker-price optimization without a total-cost frame. Engineer time, statistical correctness, and migration risk were not priced in. + +**Fix.** Run a total-cost-of-ownership review. If TCO is materially worse, plan a migration to a better-fit platform. Counter-intuitively, paying more in platform fees can save more in engineer time. + +**Prevention.** Use the total cost frame at decision time. The cheapest sticker price is rarely the cheapest TCO. See `cost-and-pricing-models.md` for the framing. + +--- + +## 2. Picked the most-featured + +**Symptom.** The team uses 20% of the platform's features. The other 80% are noise that complicates onboarding and inflates the bill. + +**Root cause.** Demo-driven feature comparison. The platform's depth was impressive in the demo and translated into a "more features means more value" assumption. + +**Fix.** Audit feature usage. If 80% of the platform is unused, evaluate whether a simpler platform serves the team better. Migrating to a smaller-surface platform reduces operational complexity. + +**Prevention.** Build a "features needed" list before evaluating platforms. Use the list to filter out features you do not need; do not let demo-time enthusiasm expand it. + +--- + +## 3. Tried multi-platform first + +**Symptom.** Two platforms running, both partially used, neither fully embraced. Stakeholders cannot tell which one is the source of truth. + +**Root cause.** "Best of both worlds" thinking. The team picked two platforms hoping to combine their strengths, but the integration cost exceeded the combined benefit. + +**Fix.** Plan a consolidation. See `multi-platform-orchestration.md` for when consolidation is the right answer (almost always for teams in this state). + +**Prevention.** Default to single-platform unless the surfaces genuinely do not overlap. Multi-platform is a 20% case, not the default. + +--- + +## 4. Outgrew the platform but stayed for migration cost + +**Symptom.** The team is hitting limits the platform cannot serve (statistical depth, governance, scale). They know it. They have not migrated because the migration project feels expensive. + +**Root cause.** Migration cost is overweighted relative to the ongoing platform tax. The platform tax compounds; migration cost is fixed. + +**Fix.** Run the migration. Set a 90-day window. Use the migration playbook. + +**Prevention.** Do an annual platform fit review. If the platform is not the right fit, the answer is to migrate, not to defer. Deferral makes the migration harder, not easier. + +--- + +## 5. Picked based on a demo + +**Symptom.** Real usage reveals workflows that did not show up in the demo. Team velocity is below expectations. Frustration is mounting. + +**Root cause.** Demos optimize for the show. Real usage reveals real tradeoffs. The decision was made before the team had data on actual workflows. + +**Fix.** Run a 30-day trial on the next-best alternative. Compare real-usage friction. If the alternative is materially better, plan the migration. + +**Prevention.** Always run a real trial, never just a demo. The trial should ship at least one experiment end to end on each platform under evaluation. + +--- + +## 6. Did not check governance + +**Symptom.** Discovered after rollout that anyone with platform access can modify production targeting. A bad change shipped because no review was required. + +**Root cause.** Governance was not part of the evaluation. The team assumed defaults would be acceptable; they were not. + +**Fix.** Build the governance layer immediately. Permission tiers, approval workflows, audit trails, environment promotion. See `governance-and-team-setup.md`. + +**Prevention.** Make governance a non-negotiable evaluation criterion. For any platform under consideration, document the permission model, audit capabilities, and approval workflow before signing. + +--- + +## 7. Picked a platform that does not fit team type + +**Symptom.** Constant friction in experiment authoring. The team that should be shipping experiments is instead filing tickets. Experiment volume is below target. + +**Root cause.** Team-fit mismatch. A PM-led team on a marketing-led platform, or vice versa. The platform's defaults pull the workflow in a direction the team cannot follow. + +**Fix.** Either change the team's workflow to match the platform, or migrate to a platform that matches the team. The migration is usually the right answer because team workflow is hard to change quickly. + +**Prevention.** Assess team fit explicitly. See the team-fit framework in `governance-and-team-setup.md`. + +--- + +## 8. Underestimated the warehouse setup + +**Symptom.** Picked a warehouse-native platform. Three months in, still not running experiments because the warehouse layer is not ready. + +**Root cause.** Warehouse-native platforms expect the warehouse to already be the system of record with metrics defined and refresh cadences in place. The team did not have that foundation. + +**Fix.** Either complete the warehouse setup (real engineering project) or migrate to a vendor-native platform that does not require it. + +**Prevention.** Verify warehouse readiness before committing to warehouse-native. The platform decision should follow the warehouse decision, not lead it. + +--- + +## 9. Skipped statistical depth review + +**Symptom.** A critical experiment surfaced a wrong-result decision. The platform's defaults did not catch the issue (peeking, ratio metric, multiple testing, network effects). + +**Root cause.** Statistical depth was not part of the evaluation. The team assumed all platforms compute the same numbers correctly; they do not. + +**Fix.** Add the missing rigor. Either configure the current platform's advanced features (sequential testing, CUPED, delta method) or migrate to a platform with stronger defaults. Pair with the `experimentation-analytics` skill to interpret results going forward. + +**Prevention.** Verify statistical depth at evaluation time. Ask specifically about CUPED, sequential testing, delta method for ratio metrics, and multiple testing corrections. Do not accept "we have statistical features" without specifics. + +--- + +## 10. Ignored MCP trajectory + +**Symptom.** AI-forward team picked a platform without MCP. Six months later, the team is hitting the limit of agent-driven workflows and the platform is the bottleneck. + +**Root cause.** MCP trajectory was not weighted in the decision. The platform's strengths in other areas were assumed to make up for the gap. + +**Fix.** Either wait for the platform to ship an MCP (uncertain timeline) or migrate to a platform with mature MCP. Eppo specifically is worth tracking for a future MCP release. + +**Prevention.** For AI-forward teams, MCP availability is a primary criterion, not a tiebreaker. See `mcp-capability-comparison.md` for current state. + +--- + +## 11. Locked the brief on the demo, not the trial + +**Symptom.** Brief-time assumptions did not survive contact with real usage. The platform is technically capable but operationally uncomfortable in ways the demo did not reveal. + +**Root cause.** The decision was made on the strength of the demo, with the trial running as a formality afterward. Real-usage signals were not weighted. + +**Fix.** Do another trial of the next-best alternative. If the alternative removes the operational discomfort, migrate. + +**Prevention.** Run the trial first. Use trial outcomes to update the brief, not the other way around. Demos are useful for screening; trials are required for committing. + +--- + +## 12. Renewed without re-evaluating + +**Symptom.** Renewal cycle came up. The team renewed because the platform was working "well enough." Six months later, an alternative shipped a feature that would have changed the decision. + +**Root cause.** Renewal treated as a status-quo extension. The platform market changes faster than annual contracts, and a yearly renewal without re-evaluation drifts away from the optimal choice. + +**Fix.** Run the platform decision framework at every renewal. If the answer is the same platform, renew with confidence. If the answer is different, plan a migration. + +**Prevention.** Build the annual platform review into the team's calendar. Tie it to the renewal date so the review informs the renewal decision rather than competing with it. + +--- + +## The pattern across all twelve + +Most platform mistakes share one root cause: under-investment in the decision itself. A two-week evaluation that catches all twelve patterns is cheaper than a year on the wrong platform. + +The fix at the meta level. Treat the platform decision as a real engineering project. Allocate time. Run trials. Audit governance. Verify statistical depth. Check MCP trajectory. Document the decision and the reasoning. Review annually. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md new file mode 100644 index 0000000..146f835 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md @@ -0,0 +1,125 @@ +# Cost and pricing models + +Pricing shapes per platform, real-world cost ranges at different traffic tiers, the total cost frame, and finance conversation patterns. + +Pricing on experimentation platforms is rarely transparent on the public site for paid tiers. The numbers below are typical ranges from real customer conversations as of May 2026. Verify with each vendor before committing. + +--- + +## The three pricing shapes + +**Vendor-native (event-based).** Statsig, Optimizely. Billing scales with the number of events sent to the platform. Easy to predict at small scale: events per month times rate per million. Painful at very high scale because the rate per million does not always decrease quickly. + +**Warehouse-native (seat plus warehouse compute).** GrowthBook (paid), Eppo. Billing scales with the number of seats and the warehouse compute the platform consumes. Warehouse compute is your existing line item, so the marginal cost of more experiments is small once the platform is paid for. Less elastic on team size, more elastic on experiment volume. + +**Product-suite (combined event volume).** PostHog, Amplitude. Billing scales with combined event volume across all features (analytics, experiments, replays, error tracking, surveys). Often the most cost-effective when used heavily; can be the most expensive when only one feature is needed. + +--- + +## Free tiers + +Free tiers exist for the early-stage and pre-PMF cases. The numbers below are current as of May 2026. + +| Platform | Free tier shape | +|---|---| +| PostHog | 1M events per month free across all features | +| Statsig | 1M events per month free; full feature access | +| Amplitude | 10M events per month free with basic features (some advanced features paid) | +| GrowthBook | Free open-source self-hosted; cloud has a free tier with 3 users and 5 active experiments | +| Optimizely | No meaningful free tier | +| Eppo | No meaningful free tier | +| Kameleoon | No meaningful free tier; free trial only | + +For pre-PMF and early-stage teams, the free-tier choice is between PostHog and Statsig. Both work. Pick the one whose product surface matches your needs (PostHog if you also want analytics; Statsig if you want experiments and flags primarily). The decision is reversible at low cost while you are still on the free tier. + +--- + +## Real-world cost ranges + +Approximate ranges for paid tiers. Bands are wide because pricing varies by contract size, sales discount, and feature mix. + +### Vendor-native (events per month) + +| Volume | Statsig (typical) | Optimizely (typical) | +|---|---|---| +| 1M to 10M | $0 (free) to $1K/month | Custom contract; rarely under $30K/year | +| 10M to 100M | $1K to $8K/month | $30K to $100K/year | +| 100M to 1B | $8K to $40K/month | $100K to $400K/year | +| 1B+ | $40K+/month with custom negotiation | $400K+/year with custom negotiation | + +Optimizely consistently sits at a higher absolute price point than Statsig for the same volume. The premium pays for the marketing-led ergonomics, the visual editor, and the personalization features. Whether the premium is justified is a per-team judgment. + +### Warehouse-native (seats and compute) + +| Team size | Eppo (typical) | GrowthBook paid (typical) | +|---|---|---| +| 5 to 10 seats | $20K to $40K/year | $5K to $15K/year | +| 10 to 30 seats | $40K to $120K/year | $15K to $50K/year | +| 30+ seats | Custom contract | Custom contract | + +Plus warehouse compute. For a Snowflake-based setup running 100 to 300 active experiments per year, expect $2K to $20K/year of additional warehouse compute attributable to experimentation queries. The exact number depends on metric complexity and refresh cadence. + +### Product-suite (combined events) + +| Volume | PostHog (typical) | Amplitude (typical) | +|---|---|---| +| 1M to 10M | $0 (free) to $500/month | $0 (free) to $2K/month | +| 10M to 100M | $500 to $5K/month | $2K to $20K/month | +| 100M to 1B | $5K to $30K/month | $20K to $100K/month | +| 1B+ | Custom negotiation | Custom negotiation | + +PostHog is consistently more cost-effective for combined product analytics plus experiments. Amplitude charges a premium for the depth of its behavioral analytics; if experiments are the primary use, PostHog is hard to justify against. + +--- + +## The total cost frame + +Sticker price is one input to the cost decision. Total cost is the right frame. + +**Engineer time.** Wiring, maintenance, dashboard upkeep, debugging integration issues. Ranges from 5% to 30% of an engineer's time depending on platform and team size. Vendor-native is usually lower; warehouse-native is usually higher (more setup); multi-platform is usually highest. + +**Statistical correctness.** A single wrong-result experiment can cost more than a year of platform fees. If a platform's defaults produce confidently-wrong recommendations, the cost is the experiment that shipped wrong, not the platform fee. Worth a real review at platform decision time. + +**Governance overhead.** Self-hosted open-source platforms require self-built governance (audit, permissions, approval workflows). For regulated industries, this is hours of compliance review per quarter. Enterprise tiers absorb this overhead in their pricing. + +**Migration risk.** What is the cost if you choose wrong and need to migrate? See `migration-playbook.md` for engineer-week ranges. Multiply by the probability you will need to migrate, and that is the migration risk component of total cost. + +**Cultural drift.** The platform's defaults shape what the team thinks experimentation is. PM-led platforms produce PM-led cultures. Marketing-led platforms produce marketing-led cultures. The drift is hard to price but real. + +--- + +## Finance conversation patterns + +Three patterns that work when justifying a platform decision to finance. + +### Pattern 1: cost per experiment + +Compute the all-in cost per experiment shipped: platform fees plus engineer time amortized across experiments per year. This converts platform cost into a unit that finance understands. A team running 50 experiments per year on a $40K platform fee is paying $800 per experiment in platform alone, plus engineer time. A team running 200 experiments on the same fee is paying $200 per experiment. + +The frame: more experiments per year reduces unit cost. Justify investment by showing a path to higher experiment throughput. + +### Pattern 2: avoided wrong-result experiments + +Estimate the cost of a wrong-result decision. For revenue experiments, this is often $50K to $500K (the value of the experiment shipped wrong). Multiply by the rate of wrong-result decisions before and after a platform change. + +The frame: a more rigorous platform avoids wrong-result decisions. A few avoided wrong-results per year easily justify the platform premium. + +### Pattern 3: total cost of ownership across alternatives + +Build a 3-year TCO model for the top two or three candidates. Include platform fees, engineer time, migration costs, and governance overhead. Show the comparison. + +The frame: the cheapest sticker price is rarely the cheapest TCO. The platform that minimizes engineer time often wins on TCO even if it costs more per month. + +Use whichever pattern matches finance's mental model. Pattern 1 works for ROI-focused finance leaders. Pattern 2 works for risk-focused leaders. Pattern 3 works for procurement-focused leaders. + +--- + +## Negotiation tips + +Three patterns work in vendor negotiations. + +1. **Multi-year commits unlock 15 to 30% discounts.** If the team is confident in the platform, lock in the discount. +2. **Event volume tiers are negotiable.** The published pricing is the starting position. Custom contracts at scale always run below it. +3. **Bundle features for unit-cost reduction.** Combining experiments and feature flags in one contract often costs less than the same features separately. + +Do not negotiate from desperation. If the team is in a "we have to migrate this quarter" position, the vendor knows and the discount evaporates. Negotiate from a position of optionality: keep the trial of the alternative platform live until the contract closes. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md new file mode 100644 index 0000000..f7db5ca --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md @@ -0,0 +1,133 @@ +# Governance and team setup + +Permission tiers, approval workflows, audit trail requirements, environment promotion, team fit assessment, and onboarding playbooks. + +Governance is the unglamorous discipline that prevents the worst outcomes. A team that ships fast without governance will eventually have an "anyone can modify production targeting" incident. This reference is the structure that prevents it. + +--- + +## The four governance pillars + +### Permission tiers + +A typical permission model has four tiers. + +1. **Read.** See experiments, flags, and results. Default for analysts, partners, and read-only stakeholders. +2. **Author.** Create and modify experiments and flags in non-production environments. Default for PMs and engineers shipping experiments. +3. **Production.** Modify production targeting. Reserved for senior engineers, leads, or designated experiment owners. +4. **Admin.** Manage users, billing, integrations. Reserved for engineering leadership and platform owners. + +Map roles to tiers. Document who has which tier. Review quarterly. Remove access proactively when someone changes roles. + +For platforms that do not natively support fine-grained permissions (some open-source self-hosted setups), build the permission model in the deployment process. For example, only certain CI/CD pipelines can push to production targeting. + +### Approval workflows + +Production-impacting changes go through review. The minimum approval workflow has three steps. + +1. The author proposes the change (new experiment, modified targeting, rollout to higher percentage). +2. A second person reviews. The reviewer is not the author. +3. The change is logged with actor, timestamp, before-and-after, and reason. + +Lighter approval is acceptable for low-risk experiments (5% rollout to internal users). Stricter approval applies to high-risk experiments (revenue, billing, security-adjacent). + +Some platforms (Optimizely Enterprise, Statsig Enterprise) build the approval workflow into the platform. Others require self-built workflows in your deployment process or change management tool. + +### Audit trails + +Every change logged. The log includes actor, timestamp, before state, after state, and reason. The log is immutable and queryable. + +Audit trails matter for two reasons. The first is compliance: regulated industries require them. The second is post-incident analysis: when a wrong-result decision ships, the audit trail tells you exactly when and why the experiment was modified. + +For platforms that do not natively log every change (smaller open-source setups), build the audit at the deployment-pipeline level. Every push to the experimentation platform's API runs through a logging proxy. + +### Environment promotion + +Experiments and flags promoted through environments: dev, staging, production. The promotion is not automatic. Each promotion is a deliberate decision. + +The minimum environment model is dev plus production. The fuller model is dev, staging, production. Larger organizations add a pre-production environment that mirrors production traffic for risk-free smoke testing. + +Promotion rules. Experiments are tested in dev first. The experiment definition (targeting, variants, metrics) is identical across environments. Only the user population differs. Promotion to production requires approval. + +--- + +## Team fit assessment + +The platform's defaults shape the team's experimentation culture. Pick the alignment that matches who you actually want running experiments. + +**PM-led culture.** PMs author and own experiments. Engineers wire metrics and SDK changes. The platform should have a low-overhead experiment authoring surface, clear analytics, and good metric documentation. + +Best fit: Statsig, PostHog. Both have PM-friendly authoring surfaces. + +**Engineer-led culture.** Engineers author and own experiments. PMs review and prioritize. The platform should have a code-first authoring surface and good SDK ergonomics. + +Best fit: PostHog, GrowthBook. Both have strong code-first paths. + +**Data-team-led culture.** Analysts and data scientists author experiments. The platform should have warehouse-native architecture, deep statistical defaults, and SQL-first metric definitions. + +Best fit: Eppo, GrowthBook. Both are warehouse-native. + +**Marketing-led culture.** Marketing teams author experiments without engineer involvement. The platform should have a visual editor and non-technical experiment authoring. + +Best fit: Optimizely, Kameleoon. Both have mature visual editors. + +The wrong fit is constant friction. A PM-led team on a marketing-led platform will struggle with the visual-editor-first authoring surface. A marketing-led team on an engineer-led platform will not be able to ship without filing engineering tickets. + +--- + +## Onboarding cost + +Time to first experiment for a new team member is a real metric. Track it after platform decisions. + +**Statsig and PostHog.** Hours to days. The authoring surfaces are PM-friendly; new team members can ship a low-risk experiment in a single afternoon with documentation. + +**Optimizely.** Days to weeks. The visual editor is approachable for non-engineers, but the platform's depth means navigation takes time. New marketing team members can ship faster than new engineering team members. + +**Eppo and GrowthBook.** Days if the warehouse and metrics are already wired in. Weeks if not. The setup overhead is in the warehouse layer, not the platform itself. + +**Amplitude.** Hours if the team is already using Amplitude for analytics. The experiments surface is a small extension of the analytics surface. New team members already familiar with Amplitude pick it up quickly. + +**Kameleoon.** Hours for the visual editor. Days for the win-to-code workflow. The specialty workflow has its own learning curve. + +--- + +## Onboarding playbook + +A repeatable onboarding playbook for a new PM or engineer joining an experimentation discipline. + +### Day 1: orientation + +- Read the platform documentation overview (1 hour). +- Walk through one completed experiment in the platform with the team owner (30 minutes). +- Review the team's metric definitions and ownership matrix (30 minutes). +- Get permissions provisioned at the Author tier (varies; aim for same day). + +### Day 2 to 5: shadow + +- Sit in on one experiment review meeting. +- Read the last 3 to 5 experiment writeups. +- Pair with a senior team member on a low-risk experiment. + +### Week 2: ship + +- Author and ship a low-risk internal experiment (5% rollout to internal users). +- Write up results. +- Get feedback from a senior team member. + +### Week 3 to 4: own + +- Take ownership of a backlogged experiment. +- Ship it end to end. +- Present results to stakeholders. + +After week 4, the new team member is fully onboarded. Track the time to first experiment as a metric. Investigate when it exceeds two weeks; that is a signal of either platform friction or onboarding-process drift. + +--- + +## Common governance failures + +Three patterns recur. + +1. **Permission creep.** Everyone gets Production tier "for convenience." Six months later, no one knows who can modify production targeting. The fix is quarterly access reviews and a strict default to Read or Author tier. +2. **Approval theater.** Changes go through an approval workflow but reviewers do not actually review. The fix is to require a substantive comment on every approval, not just a click. +3. **Audit log drift.** The audit log exists but no one reads it. The fix is to surface audit log highlights (high-risk changes, unusual targeting modifications) in a weekly digest. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md new file mode 100644 index 0000000..2c25bfc --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md @@ -0,0 +1,97 @@ +# MCP capability comparison + +Side-by-side capability matrix across the seven covered platforms. Current as of May 2026. MCP capability evolves quickly; verify before committing. + +The matrix is organized by capability category. Read it as "if my workflow needs X, which platforms support it." If your workflow needs every capability across the board, the answer is Statsig, PostHog, or Optimizely (the most mature MCPs). If your workflow needs a specific subset, smaller MCPs may be a better fit. + +--- + +## Capability matrix + +| Capability | Statsig | PostHog | GrowthBook | Optimizely | Amplitude | Eppo | Kameleoon | +|---|---|---|---|---|---|---|---| +| Read feature flags | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Create or update feature flags | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Read experiments | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Create or update experiments | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Read experiment results | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Query analytics or events | Yes | Yes (200+ tools) | Limited | Limited | Yes | No (REST) | No | +| Manage segments and audiences | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Governance actions (permissions, audit) | Partial | Partial | No | Yes | Partial | No | No | +| Code generation (variant to component) | No | No | No | No | No | No | Yes | +| Hosting model | First-party (managed) | First-party + self-host | First-party + OSS self-host | Hosted Remote | Hosted | n/a (REST) | Hosted Remote | +| Auth method | API key | API key | API key | OAuth | API key | n/a | OAuth | +| Approximate tool count | ~30 | 200+ | ~25 | ~20 | ~15 | n/a | 7 | +| Recommended scoping | Default | `?features=` to scope | Default | Default | Default | n/a | Default | + +--- + +## Notes per platform + +### Statsig + +The MCP is mature and covers the full Statsig surface (gates, dynamic configs, experiments, holdouts, layers). The tool count is moderate, which keeps the agent context window tight without sacrificing capability. Authentication is API-key based; provision a service account for agent workflows so the audit trail is clean. + +Recommended for AI-forward teams that want full CRUD without context window concerns. + +### PostHog + +The MCP is the most expansive of any platform here. 200+ tools cover analytics, experiments, flags, surveys, replays, and more. The breadth comes with a cost: without scoping, the agent's context window fills with tool definitions before it can do useful work. + +Use the `?features=` scoping parameter to load only the surfaces you need. For an experimentation-focused workflow, scope to flags, experiments, and analytics; skip replays, surveys, and error tracking unless they are part of the workflow. + +Recommended for AI-forward teams that need broad coverage and are willing to invest in scoping discipline. + +### GrowthBook + +The MCP is the first open-source production MCP for experimentation. It covers the GrowthBook surface (experiments, flags, metrics, segments). Tool count is moderate. Self-host means you can run the MCP inside your network for data sovereignty. + +Recommended for OSS-preferring teams and regulated industries that need the MCP inside their VPC. + +### Optimizely + +The hosted Remote MCP works in browser-based ChatGPT and Claude.ai. Authentication is OAuth, which integrates cleanly with enterprise SSO. Tool count is moderate. Coverage is solid on Web Experimentation and Feature Experimentation; Personalization features are accessed via the same surface. + +Recommended for enterprise teams that need OAuth and SSO compatibility for compliance. + +### Amplitude + +The hosted MCP is available to all customers including the free tier. Tool count is smaller than Statsig or PostHog. Coverage is strongest on analytics queries (cohorts, funnels, retention) and adequate on experiments and flags. + +Recommended for teams that primarily need analytics queries and use experiments as a supplementary capability. + +### Eppo + +No first-party MCP as of May 2026. REST API is the integration path. Workflows that depend on agent-driven experiment creation need a custom adapter or a wait until Eppo ships an MCP. + +Track for a future MCP release. The platform has the underlying API; an MCP wrapper is a likely future development. + +### Kameleoon + +Hosted Remote MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. The tool surface is purpose-built for the win-to-code workflow. The smallest MCP in this matrix and the most opinionated. + +Recommended for teams running the marketing-site-to-product-code workflow. Layer with another MCP if your needs go beyond that scope. + +--- + +## Choosing by workflow + +**Agent-driven full experiment lifecycle (create, run, monitor, conclude).** Statsig, PostHog, GrowthBook, or Optimizely. All four support full CRUD via MCP. + +**Agent-driven analytics queries plus light experiment work.** PostHog (with scoping) or Amplitude. Both have strong analytics MCP coverage. + +**Agent-driven win-to-code conversion.** Kameleoon. The only platform with this workflow as a primary feature. + +**Human-driven workflow where MCP is supplementary.** Any of the seven. Eppo via REST works for the supplementary case. + +**Compliance-sensitive workflow (SSO, audit, data residency).** Optimizely (OAuth, hosted) or GrowthBook self-hosted (data residency, OSS auditable). + +--- + +## Things to check before committing + +1. **Tool count and scoping.** Verify the agent context window is comfortable with the platform's tool surface. PostHog without scoping fills the window fast. +2. **Auth model.** API key is faster to provision; OAuth is required for compliance-sensitive deployments. +3. **CRUD coverage.** Read-only MCPs limit your workflow. Verify create and update are supported for your target objects. +4. **Hosting model.** Hosted is faster to start; self-host is required for data sovereignty. +5. **Trajectory.** MCP capability evolves monthly. Check the platform's changelog before committing for a future-sensitive workflow. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md new file mode 100644 index 0000000..94c8ec8 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md @@ -0,0 +1,139 @@ +# Migration playbook + +Five common migration paths with effort estimates, the first 30 days plan, the 30-90 day cutover plan, and what NOT to do. + +The discipline applies to every migration. Three rules are non-negotiable: + +1. Do not parallel-run forever. Set a cutover date and hold to it. +2. Do not big-bang switch. The risk of a silent miscount is too high; you cannot tell whether the new platform is computing correctly without overlap. +3. Do not retire the old platform before all in-flight experiments complete. + +--- + +## Statsig to PostHog + +Trigger. Company has outgrown a pure experimentation platform and wants analytics, experiments, and feature flags in one surface. Often coincides with consolidating away from a separate analytics tool. + +Effort. 3 to 5 engineer-weeks. Add 2 to 4 weeks if you are also consolidating analytics. + +First 30 days plan. +- Week 1: Provision PostHog. Wire the SDK alongside Statsig. Verify event volume matches. +- Week 2: Recreate the top 5 metrics in PostHog. Compare totals against Statsig over a 7-day window. Investigate any variance over 1%. +- Week 3: Recreate 1 active experiment in PostHog as a parallel experiment. Run both for 7 to 14 days. Confirm results agree within statistical noise. +- Week 4: Decision review. Either commit to migration or roll back to Statsig only. Document the decision. + +30-90 day cutover plan. +- Migrate experiments one at a time. New experiments start in PostHog. Existing experiments complete in Statsig. +- Migrate feature flags by service. Highest-risk services move last. +- Build dashboards in PostHog before retiring Statsig dashboards. +- Final week: retire Statsig SDK from the codebase. Remove credentials. + +What NOT to do. +- Parallel-run the SDKs for more than 90 days. The dual cost compounds; the integration tax distracts. +- Migrate flags before experiments. Flags are operational; experiments are time-bound. Flag migration creates production risk that overshadows the migration value. +- Skip the metric reconciliation. Discovering a metric definition mismatch a month into the migration is the worst possible time. + +--- + +## Optimizely to Statsig + +Trigger. Budget pressure or modernization push. Often coincides with a CFO-led cost review. + +Effort. 4 to 8 engineer-weeks. Add weeks proportional to how heavily personalization features are used (Optimizely has personalization that Statsig does not match). + +First 30 days plan. +- Week 1: Feature parity audit. List every Optimizely feature in active use. Mark which ones Statsig covers, which it does not, and which need a workaround. +- Week 2: Migrate the simplest 3 experiments. Validate results match. +- Week 3: Address the personalization gap. If personalization is heavy, plan a hybrid (Statsig for product experiments, Optimizely retained for personalization, with a retirement date in 6 to 12 months). +- Week 4: Decision review. Commit to full migration or hybrid. + +30-90 day cutover plan. +- Migrate experiments first, flags second. Personalization last (or retain in Optimizely). +- Communicate clearly with non-engineering experiment authors. The visual editor change is the friction point. +- Train non-engineering authors on Statsig's experiment definition format. +- Final phase: cancel Optimizely contract on its renewal date. Do not cancel mid-term; the savings rarely justify the early-termination friction. + +What NOT to do. +- Underestimate the non-engineering author retraining. Marketing-led teams will resist the platform change harder than engineering-led teams. +- Force personalization into Statsig if the use case does not fit. A hybrid setup is cheaper than a forced consolidation that the team cannot use. +- Cancel the Optimizely contract before all in-flight experiments complete on the old platform. + +--- + +## PostHog to Eppo + +Trigger. Statistical rigor becomes the binding constraint. A data team has joined or grown, and a critical experiment surfaced a wrong-result decision that PostHog's defaults did not catch. + +Effort. 6 to 10 engineer-weeks. The migration is harder because PostHog includes session replay, error tracking, and analytics that Eppo does not replace. Plan for a dual-platform end state. + +First 30 days plan. +- Week 1: Define the scope. Eppo replaces experiments. PostHog stays for analytics, replay, and tracking. Document which surface owns what. +- Week 2: Wire Eppo SDK alongside PostHog. Configure metric definitions in the warehouse. +- Week 3: Run one parallel experiment. Compare statistical conclusions. Investigate any disagreement; this is where the rigor difference shows up. +- Week 4: Decision review. Commit to the dual-platform end state or rethink scope. + +30-90 day cutover plan. +- New experiments start in Eppo. Existing experiments complete in PostHog. +- Build the metric definition layer in the warehouse so both platforms can agree on what "activation" means. +- Set up reconciliation dashboards. The two platforms will disagree on edge metrics; surface those proactively rather than letting stakeholders find them. + +What NOT to do. +- Try to retire PostHog. The non-experiment features (replay, tracking, analytics) do not have a clean Eppo replacement. +- Skip the warehouse metric layer. Without it, the two platforms compute metrics differently and stakeholders lose trust in both. +- Use Eppo for the small experiments where statistical depth is overkill. The analyst overhead per experiment is higher in Eppo than in PostHog. + +--- + +## GrowthBook to Eppo + +Trigger. Team growth and a desire for commercial support, deeper Bayesian and sequential testing features, and decision-oriented reporting. + +Effort. 2 to 4 engineer-weeks. This is the easiest migration in the playbook because both platforms are warehouse-native; the data already lives in your stack. + +First 30 days plan. +- Week 1: Provision Eppo. Reuse the warehouse connection. +- Week 2: Recreate metric definitions. Most translate cleanly. +- Week 3: Run 1 to 2 parallel experiments to validate. +- Week 4: Cutover. New experiments in Eppo. In-flight in GrowthBook complete on GrowthBook. + +30-90 day cutover plan. +- Migrate active flag rollouts to Eppo if Eppo's flag features are sufficient. +- Retire GrowthBook 30 to 60 days after the last in-flight experiment completes. + +What NOT to do. +- Migrate flags if Eppo's flag features do not match. Run a separate flag platform if needed. +- Cancel GrowthBook before all dashboards are recreated. + +--- + +## Any to Statsig (consolidation) + +Trigger. Multi-platform mess. Common when a company has accumulated 2 to 3 platforms over time and wants to consolidate. + +Effort. 6 to 12 engineer-weeks, scaling with the number of platforms and in-flight experiments. + +First 30 days plan. +- Week 1: Inventory. List every experiment, flag, and dashboard across all platforms. Identify the canonical source of truth where they disagree. +- Week 2: Statsig provisioning. Configure metrics. Validate event volume matches. +- Week 3: Migrate the simplest 5 experiments. Validate results. +- Week 4: Migration plan with explicit retirement dates per old platform. + +30-90 day cutover plan. +- Per-platform retirement. Pick one of the old platforms to retire first (usually the smallest user base). +- Communicate retirement dates clearly. Stakeholders need 30 days of warning per platform. +- Build dashboards before retiring; never after. + +What NOT to do. +- Try to retire all old platforms at once. Sequential retirement is slower but lower risk. +- Skip the inventory step. Discovering a forgotten experiment in production after retirement is the failure mode. +- Underestimate the team training cost. Multi-platform teams have built workflow muscle memory across all of them; consolidation requires retraining. + +--- + +## Validation: how to know the migration succeeded + +Three signals that the migration is complete and successful. + +1. **All in-flight experiments completed on the original platform.** No experiment was stranded mid-test. +2. **Metric values match within statistical noise on the new platform** for at least 30 days post-cutover. Variance over 1 to 2% needs investigation. +3. **The team is shipping experiments at the pre-migration rate or faster** within 60 days of cutover. If velocity has not recovered, retraining or workflow changes are still needed. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md new file mode 100644 index 0000000..9553bc5 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md @@ -0,0 +1,99 @@ +# Multi-platform orchestration + +When multi-platform is genuine, three coordination patterns are non-negotiable: an ownership matrix, shared metric definitions, and reconciliable dashboards. + +This reference is for the 20% of teams whose surfaces genuinely warrant more than one platform. The 80% should consolidate. If you are not sure which group you are in, the test is whether the platforms overlap. Zero overlap is a candidate for multi-platform; any overlap is a candidate for consolidation. + +--- + +## When multi-platform is warranted + +The pattern is: different surface, different audience, different metric set, no overlap. + +**Marketing site plus product app.** Kameleoon for personalization on the marketing site. Statsig for product experiments. The marketing site's metrics (conversion to signup, page-level engagement) do not collide with the product app's metrics (activation, retention, revenue). The two surfaces are run by different teams with different cadences. + +**Content site plus product app.** Optimizely or Kameleoon for content experiments. PostHog or Statsig for product. Same pattern: different surface, different audience. + +**Pre-acquisition multi-tool reality.** Two products from two acquired companies on different platforms. Multi-platform is the temporary reality; consolidation is the eventual answer. Plan a retirement date during the integration project. + +**Specialized statistical needs.** A core product on Statsig plus a specialized statistical workload (causal inference, network effects analysis) running on a separate tool. Rare but legitimate when the specialty platform has capabilities the primary platform lacks. + +--- + +## When multi-platform is a mess + +Three signals that the multi-platform setup has drifted into a consolidation candidate: + +1. **The same experiment can be defined on more than one platform.** Stakeholders ask "which one are we using?" and the answer is unclear. +2. **Metrics differ between platforms.** "Activation rate" computes one way in Statsig and another way in PostHog. Stakeholders see two numbers and trust neither. +3. **Operational overhead exceeds the value of platform diversity.** Engineers spend more time keeping platforms in sync than they save by using each platform's strengths. + +If two of three apply, plan a consolidation. + +--- + +## The ownership matrix + +The first artifact of a multi-platform setup is an explicit ownership matrix. It names which platform owns which surface, which metrics, and which experiments. Disagreements between platforms are resolved against the matrix. + +| Surface | Primary platform | Secondary platform (if any) | Owner | +|---|---|---|---| +| Marketing site | Kameleoon | None | Marketing team | +| Product app | Statsig | None | Product team | +| Mobile app | Statsig | None | Mobile team | +| Email | None | None | n/a | +| Pricing page | Kameleoon | Statsig (revenue metrics) | Marketing team primary, product team consulted | + +Where two platforms touch the same surface (the pricing page row), name a primary and clarify what the secondary is responsible for. Ambiguity here is the source of every multi-platform drift. + +The ownership matrix lives in a single document, version-controlled, reviewed quarterly. Stakeholders refer to it instead of arguing. + +--- + +## Shared metric definitions + +The second artifact is a shared metric definitions document. The same metric should compute the same way across platforms. + +Example. "Activation rate" might be defined as: percentage of users who completed onboarding within 7 days of signup. The definition includes the event name, the time window, the denominator population, and any exclusions. Both platforms reference the same definition. + +In practice, sharing definitions across platforms is hard. Three approaches. + +**Single source warehouse layer.** Define metrics in your warehouse using a metrics layer (dbt, Cube, Metricflow). Both platforms query the warehouse. This is the strongest pattern. It works if both platforms support warehouse-native metrics (GrowthBook, Eppo) or have warehouse integration paths. + +**Documented definitions with periodic reconciliation.** Each platform has its own metric. The definitions document records what each is supposed to compute. A weekly or monthly reconciliation job compares the two and surfaces variance. This works for vendor-native platforms that do not share a warehouse. + +**Tolerance for variance.** Accept that the two platforms compute slightly differently and document the expected variance range. Over 1 to 2% triggers an investigation. Under 1% is treated as noise. This works when the platforms are used for different surfaces and the metrics are not directly compared across them. + +The wrong approach is no approach. Without one of these three patterns, the platforms drift, and a leadership disagreement surfaces in the worst possible moment. + +--- + +## Reconciliable dashboards + +The third artifact is dashboards that surface the same metrics from both platforms side by side. The point is not that the numbers always agree (they will not). The point is that disagreements are visible and explainable. + +A reconciliation dashboard has three columns per metric: the value from platform A, the value from platform B, and the variance with a threshold. Variance over the threshold triggers a notification. Owners investigate and either explain the variance or fix the underlying definition mismatch. + +Reconciliation runs daily for high-stakes metrics, weekly for everything else. Outputs go to a shared channel where the team sees them; do not let reconciliation reports live in a folder no one reads. + +--- + +## The "primary platform" rule + +In every multi-platform setup, one platform is canonical. If the platforms disagree, the canonical answer wins. Pick the canonical platform once, document it, and stop arguing. + +The canonical platform is usually the one that owns the surface where the metric originates. Revenue metrics: the warehouse is canonical. Product engagement: the product analytics platform is canonical. Marketing-site conversion: the marketing experiment platform is canonical. + +Without a canonical, every disagreement becomes a debate. With a canonical, disagreements become investigations into why the non-canonical platform diverged. + +--- + +## When to consolidate + +Three signals that consolidation is overdue: + +1. **The reconciliation dashboard reports variance more often than not.** The platforms drift faster than the team can reconcile. The cost of staying multi-platform exceeds the cost of consolidating. +2. **A leadership disagreement surfaces a "which one is the source of truth" debate.** Multi-platform is meant to support different surfaces, not different versions of the same answer. If the same answer has two values, consolidation is the fix. +3. **The team is spending more than 10% of its experimentation operational time on platform coordination.** That time should be on experiments, not platform plumbing. + +When consolidation is the right answer, see `migration-playbook.md` for the patterns. The consolidation move is almost always to whichever platform is closest to the canonical for the highest-stakes surface. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md new file mode 100644 index 0000000..1025a1f --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md @@ -0,0 +1,61 @@ +# Platform decision matrix + +A context-to-platform map. The left column is the situation. The center column is the recommendation. The right column is the reasoning and the common alternative. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. The remaining rows are useful as cross-checks rather than primary picks. + +--- + +## The matrix + +| Situation | Primary recommendation | Reasoning and common alternative | +|---|---|---| +| Pure SaaS, fast-growing, want one platform for flags and experiments | Statsig | Combined feature flags and experiments, modern statistical defaults, fast time to first experiment. Alternative: PostHog if you also want analytics. | +| Product-led growth, want analytics and experiments together | PostHog | Full-funnel context, free tier covers early growth, mature MCP for AI workflows. Alternative: Amplitude if analytics depth matters more than experiment depth. | +| Open-source preference, data sovereignty, warehouse-native | GrowthBook | Data stays in your warehouse, OSS license avoids vendor lock-in, mature statistical defaults. Alternative: PostHog self-hosted if you also need analytics. | +| Enterprise, marketing-led, deep personalization | Optimizely | Visual editing for non-engineers, mature governance, decades of features. Alternative: Adobe Target if you are already on the Adobe stack. | +| Already deep on Amplitude for analytics | Amplitude | Adding experiments is the path of least resistance. Alternative: layer Statsig or Eppo only if statistical depth becomes the binding constraint. | +| Data-team-led, statistical correctness paramount, MCP not yet required | Eppo | Strongest statistical defaults among warehouse-native platforms, decision-oriented reporting. Alternative: GrowthBook if open-source is non-negotiable. | +| Convert marketing-site wins into permanent code | Kameleoon | Purpose-built for the win-to-code path; the only platform with this workflow as a primary feature. Use alongside a primary product-experiment platform. | +| Regulated industry (HIPAA, FedRAMP, healthcare), self-hosting required | GrowthBook self-hosted | Full data residency, audit-friendly, OSS auditable. Alternative: PostHog self-hosted if you also need analytics. | +| Pre-PMF, low traffic, need free tier | PostHog free or Statsig free | Both free tiers cover the early phase. Defer the real platform decision until you have the traffic to make any platform meaningful. | +| 100M+ events per month, cost control is the binding constraint | GrowthBook or Eppo | Warehouse-native pricing scales better than vendor-native at this volume. Alternative: negotiate a custom contract with Statsig or PostHog; only worth it if vendor-native features justify the premium. | +| AI-forward team, MCP-first workflow important | Statsig, PostHog, GrowthBook, or Optimizely | All four have mature MCPs with full CRUD coverage. Avoid Eppo for now (REST only). | +| Mid-market SaaS, governance important, single tool preference | Statsig | Enterprise governance is mature, combined flags and experiments simplify the operational surface. Alternative: Optimizely if marketing-led, GrowthBook if open-source preferred. | +| Web-only personalization, content site, no product app | Kameleoon or Optimizely | Both are strong on visual editing and personalization. Kameleoon for the win-to-code workflow; Optimizely for enterprise governance. | +| Data warehouse already in place (Snowflake, BigQuery), small data team | Eppo | Statistical defaults are decision-grade, warehouse compute is already a line item, low operational burden. Alternative: GrowthBook if commercial support is not required. | +| Solo founder or pre-seed startup | PostHog free or Statsig free | Both work, both are free at this stage. Pick whichever you are more familiar with; the decision is reversible. | + +--- + +## Worked examples + +### Example 1: Series B SaaS, 5M events/month, PM-led, considering Statsig vs PostHog + +The team has feature flags in LaunchDarkly already, has analytics in Amplitude, and is considering experiments. The PM-led culture wants experiments shipped weekly with low engineer overhead. + +**Recommendation.** Statsig. The PM-led culture matches Statsig's defaults. The 5M event volume is comfortably in the free tier or a small paid contract. Combined flags and experiments will likely cause a LaunchDarkly migration in 12 to 18 months, but that is a future decision, not a current one. PostHog is the alternative if the team also wants to consolidate analytics, but Amplitude is already paid for and migrating analytics is a bigger project than starting experiments. + +### Example 2: 50-person fintech, regulated industry, need data residency + +The team needs HIPAA-equivalent controls (financial regulations), data must stay in their VPC, and the engineering team is comfortable with a more hands-on platform. + +**Recommendation.** GrowthBook self-hosted. Data residency is a hard requirement and rules out all vendor-native options. The engineering team has the capacity to operate self-hosted. PostHog self-hosted is the alternative if analytics is also needed. + +### Example 3: Marketing-led brand, want non-engineer-shipped experiments + +The team is a marketing organization with a small engineering function. The marketing leads want to ship experiments without filing engineering tickets. + +**Recommendation.** Optimizely. Visual editing for non-engineers is a hard requirement. Statsig and PostHog can be used by non-engineers but require more comfort with structured experiment definitions. Kameleoon is the alternative if the win-to-code workflow is important. + +### Example 4: Data-team-led, 100M events/month, statistical depth required + +The data science team owns experimentation, runs the warehouse, and has been burned by misleading results from a less rigorous platform. + +**Recommendation.** Eppo. Statistical correctness is the headline. The 100M event volume makes warehouse-native pricing more attractive. The lack of MCP is acceptable because the team's workflow is data-scientist-driven, not agent-driven. GrowthBook is the alternative if open-source is required. + +### Example 5: Pre-PMF startup, 200K events/month + +The team has a product but no product-market fit. They want to start experimenting to find the wedge. + +**Recommendation.** PostHog free tier. Free covers the volume. Analytics plus experiments in one place lets the team learn. Defer the real platform decision until traffic is 10x higher and the platform tax becomes a real number. diff --git a/dist/pi/.agents/skills/feature-flagging/SKILL.md b/dist/pi/.agents/skills/feature-flagging/SKILL.md new file mode 100644 index 0000000..c0fa267 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/SKILL.md @@ -0,0 +1,281 @@ +--- +name: feature-flagging +description: Operational discipline for feature flags as production infrastructure. Flag types, naming, targeting rules, rollout strategy, lifecycle, governance, stale flag management, and the technical debt patterns that bite teams who weren't deliberate about it. +category: product +catalog_summary: "Flags as production infrastructure: types, naming, lifecycle, targeting, rollout, stale flag cleanup, governance" +display_order: 5 +--- + +# Feature Flagging + +A senior engineer's playbook for using feature flags well, not just frequently. + +Feature flags are infrastructure. Treated as such, they enable kill switches, gradual rollouts, A/B experiments, permission gates, and operational toggles without redeploys. Treated casually, they become the largest accumulating technical debt in your codebase: thousands of dead flags, conflicting evaluation logic, brittle targeting, and a permission surface no one fully understands. + +This skill is the discipline that prevents the second outcome. It assumes you have a feature flag platform (LaunchDarkly, Flagsmith, Split.io, VWO FME, GrowthBook, Statsig, PostHog, Optimizely; the platform does not matter for the principles). It assumes your engineering team can implement targeting rules and SDK integration. The hard part is the operational discipline, and that is what is here. + +When to use this skill: any time you are about to introduce a flag, modify a flag, audit existing flags, or design a flag-related governance policy. + +--- + +## What this skill is for + +The skill spans the operational lifecycle of a flag from creation through retirement. Flag types and the discipline of not mixing them. Naming conventions that survive code review. Lifecycle expectations baked in at creation, not bolted on later. Targeting rules that compose without fragility. Rollout strategies that match the risk profile of the launch. Stale flag management on a quarterly cadence. Governance and permissions that balance access with audit. Performance considerations so flags do not become a latency tax. Testing patterns that cover both branches. Rollback discipline. Observability across rollouts. + +The skill does not cover experiment design; for hypothesis writing, sample size, MDE, and the discipline of arriving at a defensible decision, see the `experiment-design` skill. It does not cover statistical analysis or variance reduction; those live in the `experimentation-analytics` skill. It does not cover platform-specific tooling; for MCP commands, auth, and platform-specific configuration, consult the chosen platform's documentation. This skill produces the operational shape; the platform implements it. + +--- + +## The five flag types + +Mixing flag types is the root cause of most flag mess. A flag is one of five things; commit at creation and do not let it drift. + +**Release flag.** Code is in production but disabled. The new feature ships dark, gets toggled on for a percentage, then ramps to 100. Lifetime: short, days to weeks. Lifecycle: clean removal after launch. Common name prefix: `release_`. + +**Experiment flag.** Users are randomly assigned to variants; conversion is measured. The flag controls which variant a user sees. Lifetime: medium, one to six weeks. Lifecycle: variant chosen, code paths consolidated, flag removed. Common name prefix: `exp_`. + +**Operational flag.** A kill switch or circuit breaker that lets ops disable a misbehaving feature without a redeploy. Lifetime: long-lived, often years. Lifecycle: usually never removed; remains as standby. Common name prefix: `ops_`. + +**Permission flag.** Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. Lifetime: long-lived. Lifecycle: managed alongside billing and access infrastructure. Common name prefix: `perm_`. + +**Configuration flag.** Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account. Lifetime: long-lived. Lifecycle: governed by sales and product agreements. Common name prefix: `cfg_`. + +Each type has different lifecycle, governance, and removal expectations. Mixing them in one flag (the flag is both a kill switch AND a permission gate AND now we are using it for an experiment) is the most common source of flag mess. When the flag's purpose changes, create a new flag and migrate. Do not overload an existing one. + +--- + +## Flag naming conventions + +A flag name encodes type, owner, and purpose. Without that encoding, a flag list at month nine is unreadable and the cleanup playbook from [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md) cannot tell what is safe to remove. + +The convention this skill recommends is `<type>_<owner>_<semantic_name>_<version_or_date>`: + +- `release_checkout_redesign_2026q2` +- `exp_billing_pricing_v2` +- `ops_search_circuit_breaker` +- `perm_enterprise_audit_log` +- `cfg_tenant_acme_custom_dashboard` + +Pick snake_case or kebab-case once, organization-wide, and stick with it. Mixing both in the same platform produces typo-driven bugs that bite at 3 AM. Vague names die a slow death: `new_feature`, `temp_toggle`, `test_flag`, `pricing_update_v3`. Within months, no one knows which `pricing_update` shipped and which is dead. + +For deeper coverage including the table of typed prefixes, owner conventions, and the migration plan for existing badly-named flags, see [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md). + +--- + +## The flag lifecycle + +Every flag has five life phases. Each phase has explicit entry and exit criteria. Skipping phases is how flag mess accumulates. + +**Birth.** Flag created with explicit metadata: owner, type, target removal date (for release and experiment flags), rollout plan, monitoring approach. The metadata is not optional; without it the flag has no end-of-life. + +**Adolescence.** The feature behind the flag is being built. Code paths exist for both the disabled (current production) branch and the enabled (new) branch. Both are tested. The flag remains off in production. + +**Launch.** Production rollout begins. Percentage starts low (1 or 5 percent), monitored at each step, ramps if metrics hold. Ramp gates documented in [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +**Maturity.** The flag is at 100 percent rollout. The new code path is the production path. Monitoring continues for at least 30 days to catch issues that did not show up during the ramp. + +**Death.** The flag is removed from code (PR that deletes the gating logic) and removed from the platform. The audit trail records the removal. + +The asymmetry: birth is fast (one PR creates the flag and gates the new code), death requires intentional cleanup. Most flag mess is unfinished death. Birth-and-death have to be planned together; the death plan is part of the birth metadata. + +For the per-phase checklist, see [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md). + +--- + +## Targeting rules and segmentation + +A targeting rule is the boolean expression that determines whether a user, account, or request gets the treatment branch. There are four useful target dimensions: + +- **User attributes.** `user.email_domain == "acme.com"`, `user.signup_date > "2026-01-01"`, `user.plan == "enterprise"`. +- **Account attributes.** `account.tier == "enterprise"`, `account.region == "EU"`, `account.feature_x_enabled == true`. +- **Request attributes.** `request.country == "US"`, `request.device_type == "mobile"`, `request.api_version >= 3`. +- **Time-based.** `time > "2026-06-01T00:00:00Z"`, `time < "2026-12-31T23:59:59Z"`. + +Compose with AND, OR, and NOT. Keep the expressions simple. If your rule needs three nested clauses, your taxonomy is wrong. Either define a segment (a named group of users with shared attributes) and target the segment, or split into multiple flags. + +The most common pitfall: targeting on attributes that change frequently. If the rule is `user.last_login_date > "2026-04-01"`, a user who logs in on May 1 sees the treatment, then their value changes the next day, and they see the control again. The user experience whiplashes. Volatile attributes belong in segments computed off snapshots, not in live targeting rules. + +For pattern catalog and anti-patterns, see [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md). + +--- + +## Rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile. + +**Percentage rollout.** The default for release flags. Start at 1 or 5 percent. Watch error rates, latency, and the primary success metric for at least one peak hour. If clean, ramp to 10. Watch. Ramp to 25, then 50, then 100. Total elapsed time depends on traffic, but a typical pattern is 1 percent for one day, then 10 percent for two days, then 50 for two days, then 100. Production rollouts that complete in under four hours are usually rolling too fast. + +**Cohort rollout.** Internal employees first, then beta customers, then free tier, then paid. Each cohort is a named segment; the flag advances through them in sequence. Use this for risky launches where the blast radius matters more than rollout speed. + +**Geo-staged rollout.** One region at a time. The default for compliance-sensitive features (data residency, regulatory disclosures, region-specific UX). Pair with the platform's region targeting capability so the rule does not have to be hand-written. + +**Time-based rollout.** Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment. Watch the timezone; midnight Eastern is not midnight UTC. Avoid time-based rollouts on holidays unless you have weekend on-call coverage. + +The "ramp and watch" rule: at each percentage step, monitor the system for at least one peak hour before advancing. The peak hour is when the rate of any new failure mode is highest; if the system holds at peak for an hour, the next step is safe. If you ramp during off-peak and immediately advance, you have not actually tested the change. + +For full strategy detail and a worked example for a checkout redesign, see [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +--- + +## Stale flag management + +Every live flag adds runtime cost: evaluation overhead, two code paths to maintain, mental overhead for engineers who read the code. One flag is fine. Two hundred dead flags is a productivity tax that compounds. + +Most platforms support stale flag reporting: flags that have not been evaluated in N days. Threshold defaults: 30 days for release flags and experiment flags, 90 days for operational and permission flags. A flag that has not been evaluated in 30 days is either retired in production (no users in the targeting rule) or completely dead in code (the gating call has been removed but the flag itself was never deleted). + +The cleanup playbook is mechanical: + +1. Generate the stale flag report from the platform. +2. For each flag: identify owner, last evaluation, type, recommended action. +3. Triage in a quarterly meeting: keep, remove, or investigate. +4. Open one PR per flag for code-side removal. One per PR is reviewable; bundling ten is not. +5. Delete from the platform after the PR merges. + +The reason cleanup does not happen by default: removing a flag is a code change PR with review, testing, and deploy overhead. PMs do not reward it (the feature already shipped). SREs eventually get fed up with the noise. The fix is to make removal part of the launch checklist, not a separate effort. When a flag is created, the removal date is in the metadata. The launch ticket has a follow-up sub-ticket scheduled 30 days out that says "remove flag X." If the launch goes well, the sub-ticket gets done. + +For the full quarterly cadence including ownership rotation for orphan flags, see [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md). + +--- + +## Governance and permissions + +Different roles need different access. Engineering can create flags broadly. Product can author targeting rules in dev and staging. Production targeting changes deserve a smaller set of approvers. + +Recommended permission tiers: + +- **Viewer.** Read-only across all environments. Includes most of engineering, product, support. +- **Editor.** Can create and modify flags in dev and staging. Includes the team that owns the flag. +- **Approver.** Can promote flag changes from staging to production. Smaller group; usually the team lead and the on-call engineer. +- **Admin.** Full control including deleting flags, modifying permissions, and accessing audit logs. Smallest group; platform team plus a backup. + +Production-impacting flag changes go through review like deploys, not chat. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review; the rule does not silently appear in production because someone clicked a button. + +Audit trail: every flag change logged with actor, timestamp, before/after rule, reason. Most platforms expose this; configure it to write to the central log aggregator alongside other infrastructure events. + +Environment promotion: rules tested in dev, promoted to staging, promoted to production. Authoring a production rule directly in production skips both staging tests and the review gate. Treat it as a deploy: dev → staging → production, with the same review and approval at each stage. + +Emergency override: who can flip the kill switch at 3 AM? Document, test in incident drills, and confirm the override path actually works. A kill switch nobody can find is not a kill switch. + +--- + +## Flag dependencies and conflicts + +Two failure modes that come from flags interacting: + +**Dependency.** Flag B's code path requires flag A to be on. Hard to model in most platforms; the SDK does not know about the inter-flag relationship. Avoid where possible; if you need to express it, document in the flag description and add a unit test that fails if A is off and B is on. + +**Conflict.** Two flags target the same surface, last-write-wins. The result depends on evaluation order, which depends on SDK implementation, which depends on platform internals. Detect via shared-key audit: any two flags whose targeting rules overlap on the same code path is a conflict candidate. The platform usually does not flag this; the team has to audit. + +Cross-team conflict is the dangerous version: team Alpha's release flag for the checkout redesign interacts with team Bravo's experiment on the pricing page. The interaction is invisible until production users see broken UI because both flags fired. The fix is up-front coordination via the experiment registry described in `experiment-design`. Discover before launch via planning, not via a 2 AM incident. + +For mutually exclusive experiment groups (where the platform enforces that a user is in either test A or test B but never both), see the experiment-design skill's coverage of mutex enforcement. + +--- + +## Performance considerations + +A flag evaluation is a function call (cheap) plus possibly a network call to the platform (expensive). The performance question is how much you spend in the latter. + +Cache aggressively. Most server-side SDKs cache flag values per request, per session, or per user; configure the cache so the network call happens once per relevant scope, not on every flag check. A request that evaluates fifty flags should hit the platform once at request start, not fifty times. + +Bulk evaluation: most platforms support evaluating all flags for a user or context in one call. Use it. The latency cost of "fifty individual flag checks" is fifty times the per-check overhead; the latency cost of "one bulk evaluation that returns all fifty" is one round trip plus a fast lookup per check. + +SDK selection: server-side SDKs are usually preferable to client-side for sensitive logic where latency, security, and freshness matter. Client-side SDKs are appropriate for UI-only behavior where the user can see the flag value in DevTools anyway. Mixing the two creates inconsistencies; if a user gets a different flag value on the server than the client, the UI breaks. + +Latency budget: evaluating fifty flags per request should add no more than 5 ms in the typical case. If it adds more, the SDK is misconfigured (no caching, no bulk evaluation, evaluating in a hot loop). Audit before scaling. + +--- + +## Testing flag-gated code + +Both branches need tests. The disabled branch is the existing production behavior; the enabled branch is the new code. Unit tests cover both with explicit flag overrides at test setup. + +Test the transition. What happens to a user mid-session when their flag value changes? In most well-behaved systems, the user finishes their current request with the value they had at request start, then sees the new value on the next request. Document the assumption explicitly. If your system mid-flips a user inside a session, that is usually a bug. + +Integration tests with flag overrides: most platforms support test-only flag overrides that do not affect production. Use them for end-to-end tests that exercise both branches. Without test overrides, integration tests have to share the production flag config, which means you cannot test new features that are still gated off in production. + +Common failure: shipping a "wins" experiment but only the test environment had the right targeting rules. The test environment let in 100 percent of test users via a permissive rule; production rules are stricter and let in only 20 percent. The lift you measured does not translate. Catch via staged rollout: the first 1 percent in production should match the test result before you ramp further. + +--- + +## Rollback discipline + +Flags are useful for instant rollback of the gated change. They are not a substitute for code rollback. If a bug ships in code that is not flag-gated (a fix to the existing path, an unrelated change in the same deploy), flipping the flag does nothing. Treat flag rollback as one tool among several, not as the only tool. + +If flipping the flag does work, document the rollback. If it does not work, the bug is in non-flag-gated code or in flag dependencies. Diagnose accordingly; do not assume the flag failed. + +Speed matters. How fast can you flip a flag in production? The target is under 60 seconds via UI or MCP, under 5 minutes via API plus auth. If your platform takes 15 minutes to propagate a flag change, that is a real incident-response constraint and the team should know. + +Practice. Include flag rollback in incident drills. The first time you flip a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. + +--- + +## Observability on flags + +Log flag evaluations alongside other request data. The flag value at evaluation time goes on the request log as a contextual field. When you investigate a slow request or an error, the log shows which flag values were active. + +Alert on flag evaluation rate changes. If a flag's evaluation rate suddenly drops, the rule is misconfigured (no users matching) or the SDK is broken. Either way, the team should know within minutes. + +Build dashboards for production rollouts. What percentage of users see treatment versus control, broken down by region, plan, device, etc. Without the dashboard, the rollout is a black box; with it, the team can answer "are we actually rolling out evenly across segments?" without writing a SQL query. + +Connect to error tracking. When errors spike during a rollout, the dashboard should show whether errors correlate with the flag value. Spike on treatment branch = roll back the flag. Spike on both branches = the issue is unrelated and the flag rollback will not help. + +--- + +## Common failures (rapid-fire) + +A short pattern catalog. Detail in `references/`. + +- "We launched but 90 percent of users still see the old version" means the rollout rule is wrong. Audit the rule against actual user attributes. +- "We disabled the flag but the bug is still happening" means the affected code path is not flag-gated, or there is a cached value, or a dependent flag is still on. +- "We have 400 dead flags and removing them is too risky" means cleanup never happened. Start the quarterly cadence now; one PR per flag. +- "Two flags target the same code path and we don't know which wins" means a conflict. Audit shared keys, decide one of them is canonical, retire the other. +- "Our flag evaluator is causing latency spikes" means bulk evaluation or caching is missing. Audit the SDK config. +- "We need to give finance access to feature toggles but they shouldn't change production rules" means permission tiering. Viewer for finance, editor for the owning team, approver for the team lead. + +--- + +## The framework: 14 considerations for sustainable feature flagging + +When designing or auditing feature flags, walk these 14 considerations: + +1. **Type clarity.** Release, experiment, operational, permission, or configuration. Pick one at creation; do not let it drift. +2. **Naming.** Typed prefix, owner prefix, semantic name. Avoid vague. +3. **Lifecycle planning.** Birth and death committed at creation. Removal date in metadata. +4. **Targeting taxonomy.** User, account, request, or time-based. Avoid volatile attributes. +5. **Rule simplicity.** AND, OR, NOT only. Three nested clauses means the taxonomy is wrong. +6. **Rollout match.** Strategy matches the risk profile. Percentage for low risk, cohort for medium, geo for compliance, time-based for coordinated launches. +7. **Ramp discipline.** One peak hour at each percentage step. No four-hour rollouts. +8. **Stale flag cadence.** Quarterly cleanup. One PR per removal. Make removal part of the launch checklist. +9. **Permission tiering.** Viewer / editor / approver / admin. Fewer admins than approvers, fewer approvers than editors. +10. **Environment promotion.** Dev to staging to production with review gates. Production rules are not authored in production. +11. **Conflict audit.** Two flags on the same surface = conflict. Detect via shared-key audit; coordinate cross-team via the experiment registry. +12. **Performance budget.** Bulk evaluation, caching, server-side SDKs for sensitive logic. 5 ms total budget for fifty flag checks. +13. **Branch testing.** Both code paths covered by tests. Transition behavior documented. +14. **Observability.** Every flag evaluation logged. Every rollout dashboarded. Errors correlated with flag value during incidents. + +--- + +## Reference files + +The following reference files extend this skill: + +- [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md): typed prefixes, owner prefixes, semantic naming patterns, and the migration plan for existing badly-named flags. +- [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md): birth-to-death checklist organized by lifecycle phase. +- [`references/flag-types-reference.md`](references/flag-types-reference.md): the five flag types in detail with worked examples and common pitfalls. +- [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md): quarterly cleanup process and the orphan-ownership pattern. +- [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md): common patterns and anti-patterns for targeting rules. +- [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md): percentage, cohort, geo, time-based, and combination strategies with a worked example. +- [`references/governance-and-permissions.md`](references/governance-and-permissions.md): permission tiers, environment promotion, approval workflows, and emergency override. + +--- + +## Closing: when to remove a flag + +The default disposition for any flag should be removal. Flags that earn permanent residence in the codebase (operational kill switches, permission flags tied to billing, configuration flags tied to contracts) are exceptions, not norms. Most release and experiment flags should be removed within 30 days of the launch decision. + +The cost of leaving them is real: every dead flag is two code paths to maintain, two test suites to keep green, and one more line of mental overhead for the engineer who reads the file next quarter. The cost compounds across hundreds of flags. + +The discipline of removing them is the discipline of caring about the codebase you will work in next quarter. It is the same discipline behind cleaning up after a deploy, removing dead imports, and writing a post-mortem within a week of the incident. None of it ships features today. All of it makes shipping features tomorrow easier. + +For platform-specific patterns (which platform handles which flag type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the experiment-design layer above this skill (hypothesis discipline, sample size, decision-making), see the `experiment-design` skill. For the analytical layer below this skill (variance reduction, sequential testing math, Bayesian alternatives), see the `experimentation-analytics` skill. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md b/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md new file mode 100644 index 0000000..619adb8 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md @@ -0,0 +1,119 @@ +# Flag lifecycle checklist + +A phase-by-phase checklist for the operational discipline of a flag from creation through removal. Run through the phase the flag is currently in; do not skip ahead. + +--- + +## Phase 1: Birth (creation) + +Before merging the PR that introduces a new flag: + +- [ ] Type committed. Release, experiment, operational, permission, or configuration. Pick one. +- [ ] Name follows the convention from `flag-naming-conventions.md`. +- [ ] Owner assigned. The team or person responsible for the flag's lifecycle. +- [ ] Target removal date set in metadata (release flags: 30-60 days; experiment flags: end of test plus 14 days; operational/permission/configuration flags: "long-lived, review annually"). +- [ ] Rollout plan attached. Percentage, cohort, geo, or time-based; abort criteria defined. +- [ ] Monitoring approach attached. What metric is being watched? What alert fires if the rollout breaks something? +- [ ] Both code branches tested. The disabled branch (existing production) and the enabled branch (new code). +- [ ] Default value confirmed off in production. +- [ ] Removal sub-ticket created and scheduled (release/experiment flags only). + +If any item is no, do not merge. + +--- + +## Phase 2: Adolescence (pre-launch) + +The feature behind the flag is being built in dev and staging. The flag remains off in production. + +- [ ] Feature complete in code, both branches tested. +- [ ] QA sign-off on enabled branch. +- [ ] Staging rule mirrors planned production rule (does not have to match exactly; should be representative). +- [ ] Telemetry confirmed. Logs include flag value as a contextual field. Dashboards exist for the metrics the rollout will watch. +- [ ] Rollout plan reviewed by approver. + +--- + +## Phase 3: Launch (rollout) + +Production rollout begins. Each percentage step has its own gate. + +For each step (typical: 1% → 10% → 50% → 100%): + +- [ ] Apply rule change via platform UI, MCP, or API. +- [ ] Confirm rule applied. Flag evaluation rate matches expected percentage. +- [ ] Watch primary success metric, error rate, latency p95 for at least one peak hour. +- [ ] If clean, advance to next step. +- [ ] If degraded, hold or roll back. Document what was observed. + +At 100%: + +- [ ] Hold for 7 days at 100% before declaring launch complete. +- [ ] Confirm metrics stable across the full holding period. +- [ ] Schedule the 30-day review (calendar reminder for the owner). + +--- + +## Phase 4: Maturity (post-launch) + +Flag is at 100% rollout. Both code paths still exist. The new path is production. + +- [ ] 30-day review: any regressions detected? Any rollbacks needed? +- [ ] Confirm the removal sub-ticket created at birth still exists and is scheduled. +- [ ] Confirm no unexpected dependencies on the flag from other code paths. + +If the flag is operational, permission, or configuration, the lifecycle ends here. The flag is permanent. + +If the flag is release or experiment, proceed to Phase 5. + +--- + +## Phase 5: Death (removal) + +The flag has reached its target removal date or its purpose is complete. + +Code-side: + +- [ ] Open a single PR that removes the flag's gating logic. One flag per PR. +- [ ] Delete the disabled branch (the old code path). Keep only the enabled branch. +- [ ] Delete tests that targeted the disabled branch. +- [ ] Update any documentation that referenced the flag. +- [ ] Confirm CI passes; tests still cover the new (now permanent) code path. +- [ ] Merge the PR. + +Platform-side (after PR merges): + +- [ ] Confirm the flag has zero evaluations in the platform's dashboard for at least 24 hours. +- [ ] Archive or delete the flag from the platform. +- [ ] Audit log entry confirms deletion with actor, timestamp, reason. + +Documentation: + +- [ ] Close the original removal sub-ticket created at birth. +- [ ] Update any team-level flag inventory the team maintains. + +--- + +## Phase 6: Audit (quarterly) + +Even with the discipline above, some flags will slip through. The quarterly audit catches them. + +- [ ] Generate stale flag report from the platform (>30 days unevaluated for release/experiment, >90 days for operational). +- [ ] Triage in a meeting: keep, remove, or investigate per flag. +- [ ] Open removal PRs (one per flag) for the "remove" pile. +- [ ] Investigate the "investigate" pile; usually the answer is remove or rename. + +For the full audit pattern, see `stale-flag-cleanup-playbook.md`. + +--- + +## Common slips + +The phases above describe the disciplined path. Common slips: + +- Birth without removal date. Fix: require the removal date as part of the flag-creation form or PR template. +- Launch without monitoring. Fix: the rollout plan review at end of Phase 2 catches this. +- Maturity skipped (rolled to 100%, never reviewed). Fix: the 30-day review reminder is in the launch ticket. +- Death skipped (flag forgotten). Fix: the quarterly audit catches it. + +The slips compound. A skipped death today is one more flag to clean up at quarter end. A hundred skipped deaths over a year is the productivity tax described in `stale-flag-cleanup-playbook.md`. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md b/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md new file mode 100644 index 0000000..c5daa6d --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md @@ -0,0 +1,128 @@ +# Flag naming conventions + +A flag name encodes type, owner, and purpose. Encoding makes flag lists readable at month nine and lets the cleanup playbook tell what is safe to remove. This reference documents the conventions, shows worked examples, and provides the migration plan for existing badly-named flags. + +--- + +## The format + +`<type>_<owner>_<semantic_name>_<version_or_date>` + +Each segment is mandatory for new flags except the version/date suffix, which is recommended but optional for short-lived release flags. + +--- + +## Typed prefixes + +| Prefix | Type | Lifetime | Example | +|---|---|---|---| +| `release_` | Release flag | Days to weeks | `release_checkout_redesign_2026q2` | +| `exp_` | Experiment flag | 1-6 weeks | `exp_billing_pricing_v2` | +| `ops_` | Operational flag | Long-lived | `ops_search_circuit_breaker` | +| `perm_` | Permission flag | Long-lived | `perm_enterprise_audit_log` | +| `cfg_` | Configuration flag | Long-lived | `cfg_tenant_acme_custom_dashboard` | + +Pick one prefix style organization-wide. Mixing `release_` with `release-` produces typo bugs that bite during 3 AM rollbacks. + +--- + +## Owner prefix + +The owner segment is the team or component that owns the code behind the flag. It does not have to be the team that created the flag. + +Examples: +- `checkout` for the checkout team +- `billing` for the billing team +- `search` for the search team +- `growth` for the growth team +- `infra` for platform/SRE work + +Organizations with many small teams may use a two-segment owner like `growth_signup` or `infra_db_failover`. Organizations with a single product team may use a component-level owner like `pricing`, `dashboard`, `api`. + +--- + +## Semantic name + +The semantic name describes what the flag controls. It should read naturally to someone who has not seen the flag before. + +Good semantic names: +- `redesign` (the team is redesigning a surface) +- `ml_recommendations` (the feature is ML-driven recommendations) +- `circuit_breaker` (the flag is a circuit breaker, an operational kill switch) +- `audit_log` (the feature behind the flag is an audit log) +- `single_step_billing` (a specific UX pattern the flag controls) + +Bad semantic names: +- `new_feature` (which feature?) +- `temp_toggle` (temporary for what?) +- `test_flag` (for testing what?) +- `pricing_update_v3` (which version was v3? was there a v2?) + +--- + +## Version or date suffix + +For experiment flags and release flags that may iterate, include a version or date suffix so old and new variants are distinguishable. + +- `release_checkout_redesign_2026q2`: quarter-stamped release +- `exp_pricing_test_v2`: second iteration of a pricing test +- `release_signup_form_v3_2026_05`: third iteration, May 2026 + +Operational, permission, and configuration flags usually do not need a version suffix; they are stable infrastructure. + +--- + +## Worked examples (good) + +``` +release_checkout_redesign_2026q2 +release_signup_passwordless_2026_06 +exp_billing_pricing_v2 +exp_homepage_hero_copy_test_v1 +ops_search_circuit_breaker +ops_db_failover_manual_override +perm_enterprise_audit_log +perm_eu_data_residency +cfg_tenant_acme_custom_dashboard +cfg_white_label_partner_xyz +``` + +Each name says: what type of flag, who owns it, what it controls, and (where applicable) which iteration. + +--- + +## Worked examples (bad) + +``` +new_pricing // bad: no type, no owner, no version +temp_homepage_test // bad: "temp" promises removal that never happens +billing_flag_2 // bad: vague semantic, what does flag_2 do? +killswitch // bad: which feature does this kill? +enterprise_features // bad: ambiguous, is this permission or configuration? +beta_users_only // bad: targeting concept in the flag name; rule should target, not name +``` + +--- + +## Migration plan for badly-named flags + +If the existing platform has hundreds of badly-named flags, do not rename them all at once. The pattern is to rename on touch: + +1. Establish the convention. Document it; share with the team. +2. New flags follow the convention. No exceptions. +3. Existing flags get renamed when touched: when the rule changes, when the rollout advances, when ownership transfers, when removal is scheduled. +4. Quarterly cleanup includes a "rename batch" of the 5-10 worst-named flags, especially ones that are confusing during the cleanup itself. +5. After 6-12 months, the platform stabilizes on the convention. + +Bulk renames can be scripted via the platform's API, but renaming forces a code change in every place the flag key is referenced. Bundle renames with refactors, not as standalone PRs. + +--- + +## Anti-pattern: targeting in the name + +Do not put targeting concepts in the flag name. The flag name describes what the flag controls; the targeting rule describes who sees it. + +Bad: `enterprise_users_audit_log` (the "enterprise_users" is targeting) +Better: `perm_audit_log` (the flag is a permission flag for the audit log; the rule targets enterprise users) + +If the targeting rule changes (audit log opens up to all paid customers), the flag does not need to be renamed. The rule does the work. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md b/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md new file mode 100644 index 0000000..3b13fdc --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md @@ -0,0 +1,150 @@ +# Flag rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile of the change. The five patterns below cover most cases; combine them when needed. + +--- + +## Percentage rollout + +The default for release flags. The flag advances through fixed percentage steps with a monitoring gate at each step. + +Typical sequence: + +| Step | Percentage | Hold time | +|---|---|---| +| 1 | 1% | At least one peak hour | +| 2 | 10% | At least 24 hours | +| 3 | 50% | At least 48 hours | +| 4 | 100% | Hold for 7 days before declaring complete | + +Hold times are minimums. If the metric being watched takes longer than 24 hours to stabilize (retention, downstream conversion), extend the holds accordingly. + +Abort criteria at each step: +- Error rate exceeds baseline by 10 percent. +- Latency p95 exceeds baseline by 20 percent. +- Primary success metric trends materially negative. +- Any P1 alert fires that traces back to the flag. + +If any abort criterion fires, hold or roll back. Do not advance. + +--- + +## Cohort rollout + +For risky launches where the blast radius matters. Each cohort is a named segment; the flag advances through cohorts in sequence. + +Typical sequence: + +1. Internal employees only. Bugs surface from the team that can fix them quickly. +2. Beta customers (opt-in). Engaged users who tolerate roughness in exchange for early access. +3. Free-tier customers. Larger population; risk to revenue is bounded because they are unpaid. +4. Paid customers, smaller plans first. Tier-by-tier escalation. +5. Paid customers, enterprise. Last; highest revenue impact, lowest tolerance for issues. + +Each cohort hold is at least one full business cycle (5-7 days). Compress only with strong upstream confidence (the change has already shipped through internal and beta with zero issues). + +Abort criteria same as percentage rollout, plus: support ticket volume from the cohort exceeds baseline. + +--- + +## Geo-staged rollout + +Default for compliance-sensitive features (data residency, region-specific regulations, locale-specific UX). One region at a time. + +Typical sequence: + +1. Single test region (often the team's home region; US-East or EU-West for most products). +2. English-speaking regions (US, CA, UK, AU, NZ). +3. Western Europe (DE, FR, ES, IT, NL, etc.). +4. APAC (JP, SG, AU, etc.). +5. LATAM and remaining regions. + +Hold per region depends on the product. For compliance features, hold long enough to detect any regulatory complaint or support escalation; for UX features, one full business cycle suffices. + +Abort criteria same as cohort, plus: any region-specific regulatory escalation. Compliance issues are non-negotiable rollback triggers. + +--- + +## Time-based rollout + +Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment (a press release, a partner co-launch, a planned downtime window). + +Pattern: + +1. The flag has a `time > $LAUNCH_TIMESTAMP` condition. +2. Internal QA confirms the timestamp is correct in the platform UI. +3. The launch hour arrives; the flag flips automatically. +4. The team monitors the same metrics as a percentage rollout but at the full population from minute one. + +Watch the timezone. Coordinate the timestamp explicitly: midnight Eastern is not midnight UTC; "Friday at 9 AM" is ambiguous across timezones. Use UTC in the rule and let the platform UI display in the user's local time. + +Avoid time-based rollouts: +- On weekends, unless weekend on-call exists. +- On major holidays, unless the launch is the holiday itself (rare). +- Overlapping with other major launches or known marketing campaigns; the metrics get confounded. + +--- + +## Combination strategies + +The strategies above compose. Common combinations: + +**Percentage within cohort.** "Roll out to 50 percent of beta customers, then ramp to 100 percent of beta, then start the cohort rollout to free tier." Useful when the blast radius matters even within a single cohort. + +**Geo within percentage.** "Roll out to 1 percent of users in US-East only, then 10 percent of US-East, then expand to other regions." Useful when geo isolation is important for incident containment. + +**Time-based gated by cohort.** "At time T, the flag turns on, but only for the beta cohort. The rollout to other cohorts happens later." Useful when the public announcement matters but the broader rollout should still be cautious. + +--- + +## Worked example: checkout redesign launch + +A team is launching a redesigned checkout flow. The change is high-risk (revenue surface, complex code, third-party payment integrations). + +Rollout plan: + +| Day | Stage | Rule | Hold | Watch | +|---|---|---|---|---| +| 1 | Internal | `user.email_domain == "yourcompany.com"` | 24 hours | Bug reports from team | +| 2-4 | Internal extended | Same | 72 hours | Conversion, error rate | +| 5 | Beta | `user.beta_opted_in == true` | 24 hours | Conversion, error rate, support | +| 6-8 | Beta extended | Same | 72 hours | Conversion, primary funnel metrics | +| 9 | Production 1% | `rollout 1% of all users` | 24 hours (must include peak) | Full alerting | +| 10 | Production 10% | `rollout 10%` | 24 hours | Full alerting | +| 11 | Production 50% | `rollout 50%` | 48 hours | Full alerting | +| 13 | Production 100% | `rollout 100%` | 7 days | Full alerting | +| 20 | Launch declared complete | Same rule | n/a | 30-day review scheduled | +| 50 | 30-day review | Same rule | n/a | Decide on flag removal | +| 60-80 | Flag removal PR | Code path consolidated | n/a | n/a | + +Abort criteria at every stage: +- Checkout completion rate drops more than 1 percent absolute. +- Payment failure rate increases at all. +- Error rate (any 5xx) increases by more than 10 percent. +- Support ticket volume on checkout increases. + +Total time from launch to flag-removed: about 80 days. The work to remove the flag at day 60-80 is part of the launch plan, not an afterthought. + +--- + +## When to compress + +The cadences above are conservative defaults. Compress only with strong upstream confidence: + +- The change has already shipped behind a feature flag for an extended period (release-as-experiment-as-release). +- The blast radius is genuinely small (an internal admin tool, a low-traffic settings page). +- A previous similar launch went through the full cadence with zero issues, and the new launch is structurally analogous. + +Even with strong confidence, do not skip the production 1 percent stage. The first 1 percent in production is the only stage where production-specific issues (real user agents, real network conditions, real account distributions) surface. + +--- + +## When to extend + +Extend the cadence when: + +- The metric being watched is slow (retention measured at day-7 or day-30 cannot be observed at a 24-hour hold). +- The change involves a third party (payment processor, email provider, analytics vendor) whose behavior under load is unknown. +- The team is new to flag rollouts and benefits from the slower pace as a learning exercise. + +Extension is cheaper than incident response. Conservative defaults are correct defaults. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md b/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md new file mode 100644 index 0000000..f0a1325 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md @@ -0,0 +1,83 @@ +# Flag types reference + +The five flag types in detail. Mixing them in one flag is the most common source of flag mess; commit at creation and do not let the type drift. + +--- + +## Release flag + +**Definition.** A flag that gates a new feature so the code can ship to production while disabled. The team toggles it on for a percentage, ramps to 100, then removes the flag. + +**Lifetime.** Days to weeks. Most release flags should be removed within 30 days of reaching 100 percent rollout. + +**Lifecycle pattern.** Birth (PR adds gated code), adolescence (testing in dev/staging), launch (gradual percentage ramp in production), maturity (100 percent, monitor for 30 days), death (removal PR consolidates code paths). + +**Worked example.** `release_checkout_redesign_2026q2` gates a new checkout flow. Created when the new flow PR merges. Toggled on for 1 percent of users on day 1; ramps to 10 percent on day 2, 50 percent on day 4, 100 percent on day 6. Removed on day 36 after the 30-day review confirms no regressions. + +**Common pitfalls.** Skipping the removal step (the most common). Conflating with an experiment flag (the team wants to A/B test the rollout instead of just ramping it; that is a different type). Leaving the flag at 50 percent forever because the team is "watching" it (either ramp to 100 or roll back; do not park). + +--- + +## Experiment flag + +**Definition.** A flag that randomly assigns users to variants for an A/B or multivariate test. The platform tracks conversion per variant; the team decides which variant wins, then ships the winner. + +**Lifetime.** One to six weeks. Tied to the duration of the test. + +**Lifecycle pattern.** Birth (PR adds the variants behind the flag), adolescence (canary in dev/staging), launch (test runs at the full target audience), maturity (test ends, decision made), death (winning variant code consolidated; flag removed). + +**Worked example.** `exp_billing_pricing_v2` tests two pricing page layouts. 50/50 split. Test runs for 21 days, hits the pre-committed sample size. Variant B wins. The PR removes the flag and the variant A code path; only variant B remains in production. + +**Common pitfalls.** Letting the experiment flag persist after the decision (the most common). Treating an inconclusive result as "let's keep the test running" instead of "kill or redesign." Mixing experiment with release: the team uses an experiment flag to gradually ramp a feature; if it is a ramp, it is a release flag. + +--- + +## Operational flag + +**Definition.** A kill switch or circuit breaker. Lets ops disable a misbehaving feature without a code redeploy. The flag is on by default in production; flipped off only during incidents. + +**Lifetime.** Long-lived. Often years. Removed only when the underlying feature is removed. + +**Lifecycle pattern.** Birth (PR adds the kill switch around a risk surface), maturity (the flag sits at "on" indefinitely), occasional use during incidents. + +**Worked example.** `ops_search_circuit_breaker` wraps the search service. If the search service starts returning errors at high rates during a 3 AM incident, on-call flips the flag off, and the search bar shows a graceful fallback message until the underlying issue is fixed. + +**Common pitfalls.** No incident drill (the first time the kill switch is used should not be at 3 AM). Wrapping logic that does not need a kill switch (every feature does not need one; pick the high-risk surfaces). Conflating with a release flag (the team uses the kill switch as a rollout control; if it is a ramp, the new code path needs its own release flag, and the kill switch wraps the larger feature). + +--- + +## Permission flag + +**Definition.** Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. The flag is the access control mechanism. + +**Lifetime.** Long-lived. Tied to the business model. + +**Lifecycle pattern.** Birth (PR adds the gate around a paid feature), maturity (the flag stays in production indefinitely), evolution (the rule changes as plans evolve, but the flag remains). + +**Worked example.** `perm_enterprise_audit_log` controls access to the audit log feature. Only accounts on the enterprise plan see it. When the plan structure changes (audit log opens up to the team plan too), the rule changes; the flag remains. + +**Common pitfalls.** Putting permission logic in code instead of in the flag (so the team has to deploy when plans change). Conflating with configuration: permission flags govern access by plan/role; configuration flags govern behavior per tenant contract. Permission flags use the same evaluation surface as release flags but the lifecycle is fundamentally different. + +--- + +## Configuration flag + +**Definition.** Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account, partner integrations. + +**Lifetime.** Long-lived. Tied to the contract or regulatory requirement. + +**Lifecycle pattern.** Birth (PR adds the configuration switch for a specific tenant or partner), maturity (the flag remains as long as the contract is active), evolution (the rule changes as new tenants come on or existing ones renegotiate). + +**Worked example.** `cfg_tenant_acme_custom_dashboard` enables a custom dashboard for Acme Corp because their contract specifies it. The flag's targeting rule is `account.tenant_id == "acme"`. The flag remains in production as long as Acme is a customer. + +**Common pitfalls.** Configuration sprawl: every tenant request becomes a new flag, the platform has hundreds, no one can audit. Mitigation: use segments and tenant-attribute targeting on a smaller set of feature flags rather than per-tenant flags. Conflating with permission: configuration governs custom behavior per tenant contract; permission governs access by plan tier. + +--- + +## Anti-pattern: type drift + +A flag created as a release flag gets repurposed as an experiment, then later as a permission gate. The name still says `release_`. The targeting rule is now multi-purpose. The lifecycle expectation is unclear. Removing the flag breaks something somewhere. + +The fix is to refuse type drift. When the purpose changes, create a new flag of the new type and migrate the rule. The original flag is removed once nothing depends on it. This is more work than just changing the rule on the existing flag, but it preserves the type-clarity discipline. + +The recovery for an existing type-drifted flag: rename to one of the five types, document the current actual purpose, and treat the flag as that type from now on. The original mixed history is grandfathered; the going-forward behavior is single-typed. diff --git a/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md b/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md new file mode 100644 index 0000000..a56582d --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md @@ -0,0 +1,115 @@ +# Governance and permissions + +Different roles need different access to the flag system. Engineering needs broad ability to create flags. Product needs to author targeting rules in dev and staging. Production targeting changes deserve a smaller approver pool. The pattern below balances access with audit. + +--- + +## Permission tiers + +Four tiers cover most cases. Not every organization needs all four. + +| Tier | Scope | Typical members | +|---|---|---| +| Viewer | Read-only across all environments | Most of engineering, product, support, finance, executive | +| Editor | Create and modify flags in dev and staging | The team that owns the flag's surface | +| Approver | Promote flag changes from staging to production | Team lead, on-call engineer, designated approvers | +| Admin | Delete flags, modify permissions, access audit logs | Platform team plus a backup | + +Smaller organizations may collapse Editor and Approver into a single "Engineer" tier. Larger organizations may add a fifth tier ("Owner") for cross-cutting governance. + +--- + +## Environment-based permissions + +Permissions vary by environment. The same person can have Editor in dev/staging and Viewer in production. The environment-based scope is the second axis after role. + +| Environment | Default access | Notes | +|---|---|---| +| Dev | Editor for engineering, Viewer for everyone else | Sandbox; mistakes are cheap | +| Staging | Editor for the owning team, Viewer for everyone else | Pre-production; mistakes are detectable | +| Production | Approver for the owning team, Viewer for everyone else | Live; mistakes are expensive | + +Production changes go through review like deploys. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review. The rule does not silently appear in production because someone clicked a button. + +--- + +## Approval workflow + +For production-impacting changes: + +1. Editor authors the change in staging. +2. Editor tests the change in staging (the rule applies, the metric moves as expected). +3. Editor opens a change request in the platform (most platforms have a built-in change-request workflow; if not, a Slack channel with a bot suffices). +4. The request includes: rule diff, rollout plan, abort criteria, link to relevant ticket/PR, link to staging test results. +5. An approver reviews. If clean, applies. If not, comments and the editor revises. +6. The change applies in production with the audit trail attached. + +For low-risk operational changes (a kill switch flip during an incident), the workflow can be compressed: the approver applies directly without a separate change request, and the audit trail captures the change with the incident reference. Document this exception explicitly so emergencies do not produce unexplained audit entries. + +--- + +## Audit trail + +Every flag change must be logged with: + +- Actor (who applied it, by user identity). +- Timestamp. +- Before-state and after-state (the rule diff). +- Reason (free-text or linked ticket). + +Most platforms do this automatically. Configure the audit log to also write to the central log aggregator (Datadog, Splunk, ELK, the team's choice). The platform's audit log is fine for routine inspection; the centralized log is where investigation happens during incidents. + +Audit retention: at least one year. Two years for organizations with regulatory obligations. + +--- + +## Emergency override + +An emergency override is the path that lets on-call flip a kill switch at 3 AM without going through the standard approval workflow. + +The pattern: + +1. A small group has Approver permission on the operational kill switches specifically. +2. The group includes the on-call rotation; on-call inherits Approver for the duration of their shift. +3. Emergency overrides apply with the standard audit trail; the reason field includes the incident reference. +4. After the incident, the override is reviewed in the post-mortem. + +Test the override in incident drills. The first time on-call flips a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. If the drill reveals the override path is broken (the on-call's account does not have the right permission, the platform's UI is confusing, the mobile app does not let you change rules), fix it immediately. + +--- + +## Service accounts + +Automation needs flag access too. CI/CD pipelines may flip flags as part of deploys; monitoring systems may flip kill switches based on alerts; orchestration agents may modify flags via MCP. + +Service accounts: + +- Each automation has its own service account with a clearly named identity (`ci_pipeline`, `monitoring_alert_bot`, `agent_orchestrator`). +- Service accounts have the minimum permission needed for their scope. The CI account that flips release flags after deploy does not need permission to delete flags. +- Service account credentials rotate on a schedule (90 days for production access). +- Audit log entries from service accounts are clearly marked so they can be filtered separately from human changes. + +Mixing human and service-account credentials in the same identity is the most common audit-trail mistake. The investigation question "who changed this flag at 2 AM" should not have the answer "an automation, but we are not sure which one because it was authenticated as a human admin." + +--- + +## The "production console freeze" anti-pattern + +Some organizations respond to a production flag incident by tightening access so much that every flag change requires a ticket, a meeting, and a 24-hour delay. The result is over-correction: routine flag changes get queued, the team starts authoring rules in code instead of in the platform, and the platform stops being load-bearing. + +The fix is not to freeze access. The fix is to: + +- Tighten the approval workflow (require change requests for production). +- Tighten the audit log (capture every change with reason). +- Tighten the emergency override (drill it). +- Loosen the day-to-day workflow so editors can do their jobs without paperwork. + +Bureaucracy substitutes for trust. Trust is built via the audit log and the approval workflow. Once the audit log is solid, day-to-day editing can stay fast. + +--- + +## Cross-team coordination + +When a flag's surface overlaps with another team's work, coordinate before the change. The experiment registry pattern from the `experiment-design` skill applies here too: maintain a shared list (in the platform, in a wiki, in a shared doc) of flags currently being modified or rolled out per surface. Before launching a flag rollout, check the registry for conflicts. + +Cross-team coordination does not have to be heavy. A 5-minute Slack check ("we're rolling out flag X on the checkout flow tomorrow at 1 PM, anyone working on adjacent flags?") is enough for most cases. The cost of skipping the check is the cross-team conflict scenario from the [SKILL.md](../SKILL.md), where two flags interact and produce broken UI. diff --git a/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md b/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md new file mode 100644 index 0000000..a4e2670 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md @@ -0,0 +1,116 @@ +# Stale flag cleanup playbook + +A quarterly cadence for keeping the flag inventory healthy. Without it, dead flags compound: every quarter adds 20-50 release/experiment flags that never got removed, and after two years the platform has hundreds of dead entries that nobody can confidently delete. + +The playbook is mechanical. Run it every quarter, the same way. Resist the urge to skip a quarter because the platform "looks fine." + +--- + +## What counts as stale + +| Flag type | Stale threshold | +|---|---| +| Release | 30 days without evaluation | +| Experiment | 30 days without evaluation | +| Operational | 90 days without evaluation | +| Permission | Annual review; not "stale" by evaluation count | +| Configuration | Annual review; tied to contract status | + +Most platforms expose a "stale flag" report or a "last evaluated" timestamp per flag. If yours does not, the SDK can be configured to emit evaluation events to an analytics destination, and the analytics database becomes the source of truth. + +--- + +## Quarterly process + +### Step 1: Generate the report + +Pull the stale flag list from the platform. Filter by type-specific threshold above. Output: a list of flags with last-evaluation timestamp, owner, type, current rule. + +### Step 2: Owner triage + +For each flag in the list, route to the owner. The owner has three options per flag: + +- **Remove.** The flag is dead. Open a code-side removal PR. +- **Keep.** The flag is still load-bearing for a real reason (operational kill switch that has not fired in 90 days but should remain; permission flag for a feature whose rule is being audited annually). Document the reason; remove from this quarter's list. +- **Investigate.** The owner does not know why the flag exists or what it controls. Spawn a sub-task to investigate; the flag stays in next quarter's list. + +If a flag has no owner (the original owner left, ownership was never assigned, the flag predates the convention), rotate to the platform/SRE team for a forced decision in step 3. + +### Step 3: Triage meeting + +A 30-minute meeting per quarter. Attendees: representative from each team that owns flags, the platform/SRE team, the engineering lead. + +Walk the list. For each flag: + +- Confirm the owner's recommendation. +- For "investigate" flags, decide a deadline: investigation completes by next month or the flag is force-removed. +- For orphan flags (no owner, force-routed to platform), the platform team makes the call: remove if there is no evidence of active use, keep with documentation if there is. + +The meeting produces three artifacts: a remove list, a keep list with reasons, an investigate list with deadlines. + +### Step 4: Removal PRs + +One PR per flag. Bundle is tempting; resist it. One-flag-per-PR has three advantages: + +1. The reviewer can confirm the flag is genuinely dead by inspecting only the removed code paths. +2. If a flag was not actually dead (a code path uses it that the search missed), the rollback is a single revert. +3. The PR title and description reference the specific flag, which produces a clean audit trail. + +Each PR: + +- Removes the flag's evaluation calls from code. +- Consolidates the gated branches: usually keeps the "on" branch as permanent code and deletes the "off" branch. +- Removes any tests that targeted only the removed branch. +- Updates documentation that referenced the flag. + +### Step 5: Platform deletion + +After the removal PR merges and ships: + +- Wait 24 hours for the new code to fully roll out. +- Confirm the platform shows zero evaluations of the flag for the full 24-hour window. +- Archive or delete the flag from the platform. +- Audit log entry confirms deletion with actor, timestamp, reason ("quarterly cleanup, removal PR #NNNN"). + +### Step 6: Verification + +A week after platform deletion: + +- Spot-check the codebase for any remaining references to the flag's key (string-grep). Should be zero. +- Spot-check the platform for the flag's reappearance (sometimes platforms restore archived flags via API automation; rare but worth checking). + +--- + +## Orphan flags + +Orphan flags (no owner) are the hardest case. The original owner left the company, the team that owned the area dissolved, the flag predates the ownership convention. + +The pattern: + +1. Default ownership routes to the platform/SRE team. +2. The platform team asks: "Is this flag's targeting rule consistent with documented product behavior? Would removing it change observable behavior for any user?" +3. If no observable change, remove. If yes, escalate to the team most plausibly impacted. +4. If no team can be identified and no observable change is detectable, the flag is a candidate for removal in the next quarterly meeting; document the orphan status and remove on a 60-day delay so any silent dependency can be discovered. + +The 60-day delay is a hedge against unknown dependencies. In most cases, no one notices and the flag is safely removed. In the rare cases where a forgotten cron job or a downstream service was depending on the flag, the issue surfaces during the delay window. + +--- + +## Tooling + +Most platforms provide some automation: + +- LaunchDarkly: Code References finds usages in the codebase, flags candidates for removal. +- Statsig: Stale Gates report. +- GrowthBook: stale flag dashboard. +- Flagsmith: change request workflow integrates removal with governance. + +The automation reduces manual work but does not replace the triage meeting. The meeting is where humans make the keep/remove decision, which is the part automation cannot do. + +--- + +## Make removal part of the launch checklist + +The most important pattern is upstream: make flag removal part of the launch checklist, not a separate quarterly effort. When a release flag is created, the launch ticket has a sub-ticket scheduled 30 days out: "Remove flag X." When the launch goes well and the flag reaches 100 percent, the sub-ticket gets done as part of post-launch hygiene. + +Quarterly cleanup is the safety net for everything that slips past the upstream discipline. The discipline reduces the safety-net workload from "300 dead flags" to "5 dead flags," which is the difference between a 30-minute triage meeting and a multi-day project. diff --git a/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md b/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md new file mode 100644 index 0000000..edabbe0 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md @@ -0,0 +1,183 @@ +# Targeting rule patterns + +Common patterns and anti-patterns for flag targeting rules. The patterns work; the anti-patterns produce flag mess that takes quarters to unwind. + +--- + +## Pattern: percentage rollout + +Default: flag off (0 percent). Override: flag on for a percentage of the user population. + +``` +Default rule: off +Override: rollout 10% of all users +``` + +The platform handles the bucketing (usually a stable hash on user ID, so the same user gets the same value across requests). Use this for release flags during ramps. + +Variation: percentage within a segment. `Default off; rollout 50% of users where account.tier == "enterprise"`. Useful when the rollout should reach only a subset of the population. + +--- + +## Pattern: internal-only + +Restrict the flag to internal employees first. The flag is on for `@yourcompany.com` emails; everyone else sees the disabled state. + +``` +Default rule: off +Override: on if user.email_domain == "yourcompany.com" +``` + +Use this for the first stage of a sensitive release. Internal users find bugs without external exposure. + +--- + +## Pattern: opt-in beta + +Users who have opted into beta features see the flag on. Implementation requires an opt-in mechanism somewhere in the product (settings page, signup flow, support request). + +``` +Default rule: off +Override: on if user.beta_opted_in == true +``` + +Use this for risky features that need engaged-user feedback. The opt-in is the consent mechanism; the flag is the access mechanism. + +--- + +## Pattern: cohort-based + +Target a named segment defined elsewhere in the platform. The segment captures the cohort logic so the flag rule stays simple. + +``` +Default rule: off +Override: on if user IN segment "early_access_2026q2" +``` + +Use this when the cohort is shared across multiple flags (the same set of "early access" users sees several features). The segment is the single source of truth; flags reference it. + +--- + +## Pattern: geo-staged + +Target users by region. The country or region attribute usually comes from the request (IP-based geolocation) or the account profile. + +``` +Default rule: off +Override: on if request.country IN ("US", "CA") +``` + +Use this for compliance launches (data residency regulations, region-specific UX). Stage the rollout: US first, then EU, then APAC. + +--- + +## Pattern: time-based scheduled flip + +The flag turns on at a specific time. Useful for marketing-coordinated launches. + +``` +Default rule: off +Override: on if time > "2026-06-01T12:00:00Z" +``` + +Watch the timezone. Avoid scheduling on weekends or holidays unless on-call coverage exists for the rollout window. + +--- + +## Pattern: composition (cohort within percentage) + +A percentage of a cohort. Useful when the rollout should be slow even within an opt-in group. + +``` +Default rule: off +Override: on if user.beta_opted_in == true AND rollout 25% of those users +``` + +Order matters: the percentage applies to the cohort, not the full population. The platform's rule editor usually makes this clear. + +--- + +## Anti-pattern: volatile-attribute targeting + +Targeting on attributes that change frequently produces user-experience whiplash. + +Bad: +``` +Override: on if user.last_login_date > "2026-04-01" +``` + +A user's last_login_date changes every time they log in. They see the treatment one day, the control the next. The experience flickers; conversion data is noise. + +Fix: target on stable attributes. Or, snapshot the attribute at a fixed point (`user.first_login_date_was_after_2026_04_01`) and use the snapshot. + +--- + +## Anti-pattern: deeply nested AND/OR + +If your rule has three levels of nesting, the taxonomy is wrong. + +Bad: +``` +Override: on if ( + (user.country == "US" AND user.signup_date > "2026-01-01") + OR + (account.tier == "enterprise" AND NOT user.churned) + OR + (user.beta_opted_in == true AND request.device == "mobile") +) +``` + +The intent is unclear, the rule is fragile, and reviewing it during incidents is slow. + +Fix: define a segment that captures the intent (e.g., "eligible_for_new_dashboard") and use the segment in the flag rule. Or split into multiple flags (one for the US/recent-signup case, one for the enterprise case, one for the mobile-beta case) and let the calling code combine them. + +--- + +## Anti-pattern: production rules drift from staging + +The team tests the flag in staging with rule X. The rule that ships in production is rule Y, written directly in the production console without re-testing in staging. + +Result: the staging tests do not predict production behavior. The first 1 percent rollout in production reveals the gap, and the team scrambles to align. + +Fix: rules go through environment promotion. Author in staging, test in staging, promote to production via the platform's promotion workflow. If the platform does not have promotion, copy the rule from staging to production via a documented process and confirm the rule is identical in both before flipping production on. + +--- + +## Anti-pattern: targeting in the flag name + +Bad: `flag_name = "enterprise_audit_log"` with rule `account.tier == "enterprise"`. + +When the rule changes (audit log opens up to team-tier accounts), the flag name lies. + +Fix: name the flag for what it controls (`perm_audit_log`), let the rule do the targeting work. The rule can change without renaming the flag. + +--- + +## Anti-pattern: kill switch with a complex rule + +A kill switch (operational flag) should have a simple rule: `on for everyone` or `off for everyone`. If your kill switch's rule is `on for everyone except a specific cohort with these conditions`, you are using an operational flag as a permission gate. + +Fix: use a permission flag for the per-cohort access; use a separate operational flag (`ops_feature_x_killswitch`) for the universal kill. The operational flag wraps the entire feature; the permission flag wraps the access to the feature. + +--- + +## Pattern: explicit ramp gate + +Some platforms let you tag a flag's rule with explicit "stages." The flag advances through stages on a button press, with each stage having its own rule. + +``` +Stage 1: rollout 1% +Stage 2: rollout 10% (advance from stage 1 manually) +Stage 3: rollout 50% (advance from stage 2 manually) +Stage 4: rollout 100% (advance from stage 3 manually) +``` + +Use this when the platform supports it. The explicit stages make rollout history readable: you can see when each stage advanced, by whom, with what observed metrics. + +--- + +## Composition rule of thumb + +If a flag's rule reads naturally to a non-engineer ("on for enterprise customers in the US"), the rule is simple enough. If the rule requires a five-minute explanation, it is too complex; refactor into segments or split into multiple flags. + +The rule is read more times than it is written. Optimize for readability. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md b/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md new file mode 100644 index 0000000..119e651 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md @@ -0,0 +1,340 @@ +--- +name: feature-launch-playbook +description: "The operational playbook for launching a feature well. Positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring with pre-defined rollback triggers, post-launch measurement against spec hypotheses, and the discipline that distinguishes shipping from releasing from actually launching. Triggers on launch plan, feature launch, launch checklist, ship vs release, rollout strategy, gradual rollout, sales enablement, support readiness, launch announcement, post-launch measurement, launch failure, declared victory too early. Also triggers when planning a launch (any size, any segment), auditing an existing launch process, fixing the we shipped it but the metric did not move problem, or building a launch checklist for the team." +category: product +catalog_summary: "The operational discipline of launching a feature well: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement" +display_order: 10 +--- + +# Feature Launch Playbook + +A veteran PM-leader's playbook for launching features well, not just shipping them. + +Most teams conflate shipping, releasing, and launching. Shipping means engineering work is complete. Releasing means users can access it, even if it is behind a flag at 1 percent. Launching is the discipline of positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement that turns "feature exists" into "feature lands." + +A feature that ships without launching costs you the same engineering investment but captures a fraction of the value. Sales does not know how to sell it. Support does not know how to help with it. Customers do not notice it. The metric you said you would move does not move because nobody knows the feature is there. + +This skill is the operational playbook. It assumes you have already written the spec (`pm-spec-writing`), prioritized it onto the roadmap (`roadmap-planning`), instrumented it (`product-analytics-setup`), and possibly tested it (`experiment-design`). The launch is the next discipline: how to actually get the feature in front of the right users, with the right context, in a way that lets you measure whether it worked. + +When to use this skill: planning a launch (any size, any segment), auditing an existing launch process, fixing the "we shipped it but the metric did not move" problem, or building a launch checklist for the team. + +--- + +## What this skill is for + +This skill spans the operational launch discipline. It composes with the rest of the Product skill suite. + +- `pm-spec-writing` defines the launch hypotheses; this skill validates them. +- `roadmap-planning` provides the launch context (what came before, what comes next). +- `product-analytics-setup` is the instrumentation prerequisite; without it you cannot measure the launch. +- `experiment-design` and `data-warehouse-experimentation` provide the methodology for testing whether the launch worked. +- `feature-flagging` provides the rollout infrastructure this skill depends on. + +This skill does not cover pricing decisions, brand campaigns, or full GTM strategy. Those need a marketing team partner; this is the PM operational playbook for the engineering and product side. + +The audience is broad: every PM ships features, every PM has launched poorly at least once, every PM benefits from a checklist that stops the worst failure modes from recurring. The voice is veteran PM-leader to PM. Specific, opinionated, honest about what discipline matters at what stage. + +--- + +## Ship vs release vs launch + +The keystone distinction. Three definitions. + +**Shipping** means engineering completes the work. Code is on production. No users can access it yet, or only internal users via a flag. The PR is merged and deployed. + +**Releasing** means users can access it. Could be 1 percent rollout, could be 100 percent. The feature is "live" in some technical sense. The flag is on for at least one user. + +**Launching** means positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement are all in flight. The feature has been introduced to the people who would benefit from it, with the context they need to use it. + +The pathology. PMs report "we shipped feature X" when what happened is engineering completed the work. The feature might be released to 1 percent of users with no announcement, no documentation, no sales enablement, no measurement plan. From a value-capture perspective, that is an unlaunched feature. + +The discipline. Use precise vocabulary. "Engineering shipped on Tuesday. We are releasing to 25 percent on Thursday. We are launching publicly next month." The vocabulary forces honest accounting of what has and has not happened. + +Most "feature failed" diagnoses turn out to be "feature was unlaunched." This skill is structured around the launch dimension because that is where most teams under-invest. + +--- + +## Launch tiers + +Not every feature needs the full playbook. Match the work to the feature. + +**Tier 1 (full launch).** Net-new product, major feature reshaping the product narrative, pricing change, breaking change. Full playbook: positioning, all comms channels, sales enablement, customer success briefing, dedicated post-launch measurement, executive announcement. + +**Tier 2 (focused launch).** Meaningful improvement that materially affects user value or competitive positioning. Subset of the playbook: in-app comms, blog post or release note, support readiness, rollout strategy, post-launch measurement. + +**Tier 3 (release note).** Incremental improvement, bug fix made positive, polish. Minimal: changelog entry, release note, light monitoring. + +The trap on either side. + +- Treating every release as Tier 1 produces comms fatigue. Customers tune out the announcement firehose; your real Tier 1 launches lose signal in the noise. +- Treating every release as Tier 3 produces unlaunched features. The feature ships, the metric does not move, the team concludes "users do not want this" when the actual cause is "users were not told." + +Match the tier to the feature. This skill primarily covers Tier 1 and Tier 2. Tier 3 is mostly the changelog discipline; the launch playbook applies but compressed to the changelog entry plus light monitoring. + +Detail in [`references/launch-tier-decision.md`](references/launch-tier-decision.md). + +--- + +## Pre-launch: positioning + +Positioning answers: who is this for, what problem does it solve, why now, and what is the user-visible promise. + +The positioning canvas. One page, filled out before any comms drafting. + +- **Target user.** Segment, role, jobs-to-be-done. Specific enough that a sales rep could describe the customer profile in one sentence. +- **Problem it solves.** Specifically, in user words. Not "we improve productivity"; instead "the customer support manager who needs to triage 200 tickets a day cannot tell which are urgent without opening each one." +- **Current alternative.** What users do today without this. The status quo is the real competition. +- **User-visible promise.** One sentence. The promise the user will hear when they encounter the feature in the wild. +- **Proof points.** Three to five specific capabilities or outcomes. Concrete, not adjectives. +- **Anti-positioning.** What this is NOT, what it does not try to do. Prevents over-promising. + +The most common positioning failure is a vague target user. "It is for PMs" is not a target. "It is for B2B SaaS PMs at companies with 50 to 500 customers who need to coordinate roadmap discussions across engineering and customer success" is a target. The specificity is what lets sales, marketing, and support speak the same language about who this is for. + +Detail in [`references/positioning-canvas.md`](references/positioning-canvas.md). + +--- + +## Pre-launch: internal alignment + +Stakeholders who need to know before launch. + +- **Engineering leadership.** Capacity for follow-ups, support escalations, post-launch fixes. +- **Sales leadership.** Revenue forecast updates, deal coaching, pipeline impact. +- **Customer success leadership.** Proactive customer notifications, deal saves at risk, expansion conversations. +- **Marketing leadership.** Paid spend coordination, blog calendar, social timing. +- **Support leadership.** Training, FAQ, escalation paths. +- **Executive sponsor.** Visibility, public messaging, investor or board reporting. + +The discipline. A single internal launch brief, distributed two to four weeks before launch (Tier 1) or one week before (Tier 2). The brief contains a one-page summary, an FAQ, a decision log of choices already made, and the launch calendar. The brief should answer "what do I need to do differently because of this launch." + +The most common internal alignment failure: launching without sales knowing. Sales finds out from a customer asking about it. Trust erodes for the next launch. The fix is the launch brief plus a sales-specific briefing one to two weeks before customer-facing launch. + +Detail in [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md). + +--- + +## Pre-launch: customer comms plan + +Channels and decision factors. + +- **In-app.** Highest reach for active users; right for product-internal features. Tooltips, banners, modals. +- **Email (transactional or campaign).** High reach across active and inactive users; right for material changes that affect existing workflows. +- **Blog post.** SEO plus lead gen plus narrative; right for Tier 1 launches with external story. +- **Release notes.** Discoverable, archived, queryable; right for every Tier 2 and above. Often the canonical reference customers find later. +- **Social (LinkedIn, X, Bluesky).** Reach beyond existing customers; right when launch has external narrative or competitive angle. +- **Webinar or customer call.** Depth for enterprise customers; right for Tier 1 with material customer impact. +- **Sales-led briefing.** High-touch for top accounts; right when launch affects pricing, contracts, or strategic positioning. + +For each channel: who drafts, who approves, what is the timing, what is the call to action. + +The comms calendar pattern. A single document with all channels and dates, distributed in the internal launch brief. Prevents the "blog post went out before sales got the briefing" failure. Ordering typically goes: sales briefing first, support training second, customer success outreach to top accounts third, public comms fourth. + +Detail in [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md). + +--- + +## Pre-launch: sales enablement (B2B) + +For B2B products, sales enablement is not optional for Tier 1 and most Tier 2 launches. The deliverables. + +- **One-page battlecard.** Positioning, target customer, top objections, proof points. Sales can read it in two minutes and pitch the feature in five. +- **Demo script and recorded demo.** A repeatable demo the rep can run with a customer; the recorded version is the fallback for reps who join after the launch. +- **Pricing change documentation** if applicable. Sales reps cannot answer pricing questions accurately without explicit guidance. +- **Deal coaching guide.** Which deals does this unblock, which does it complicate. Specific named accounts where appropriate. +- **Internal training session** live or recorded, with Q&A archived. Sales reps need the chance to ask questions before they take the feature to a customer. + +The "shadow launch" failure. Feature ships, sales hears about it from product team Slack, no battlecard, sales reps either ignore it or misrepresent it to customers. Customers churn because the feature was promised in a way that did not match reality. + +For B2C and PLG products, this section is mostly skipped. The user is the buyer; there is no sales motion. Note this explicitly so PMs in those contexts do not feel they are missing the discipline. + +Detail in [`references/sales-enablement-template.md`](references/sales-enablement-template.md). + +--- + +## Pre-launch: support readiness + +Support is often the first to encounter the failure modes of a new feature. They need. + +- **Training** live or recorded, with Q&A. The same content as the sales training adapted to support workflows. +- **FAQ document** covering known questions, known limitations, and known bugs at launch. The FAQ updates daily during the first week as new questions surface. +- **Escalation path** for issues that need engineering or PM. Named owners and turnaround time commitments. +- **Monitoring access** or a way to ask for it. Support reps should be able to verify whether a customer's issue is feature-specific. + +The discipline. The support team's confusion is the test customer's confusion. If support does not understand the feature, neither will customers. Train support before customer-facing launch comms go out. + +Detail in [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md). + +--- + +## Launch day: rollout strategy + +Four common patterns matched to feature type. + +**All-at-once (big bang).** Zero to 100 percent in a single deploy. Right for marketing-coordinated launches where the announcement IS the rollout. Risky for anything where bugs would affect a meaningful customer base. Use sparingly. + +**Gradual percentage rollout.** 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days, monitored at each step. Right for most feature launches; the default unless there is a reason to deviate. + +**Flag-gated cohort rollout.** Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Right for features with cohort-specific risk profiles. + +**Phased launch (multi-week).** Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Right for Tier 1 launches with high uncertainty about user reception. + +The decision framework. Feature blast radius times confidence in correctness times external commitments. + +- High blast radius plus low confidence plus no external commitment: phased. +- Low blast radius plus high confidence plus external launch date: all-at-once. +- The middle (most launches): gradual percentage rollout. + +Detail in [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md). + +--- + +## Launch day: monitoring + +Pre-launch, define what you will monitor and what alerts you. Common dimensions. + +- **Error rates.** Overall plus feature-specific. +- **Latency.** Overall plus feature-specific. +- **Feature usage rate.** People who SHOULD use it actually do. +- **Funnel completion.** Users complete the new flow. +- **Support ticket volume.** Especially feature-specific tags. +- **Customer satisfaction signals.** NPS comments, feedback widget mentions. + +Define the rollback trigger explicitly before launch. Examples. + +- "Error rate above 1 percent sustained for 5 minutes triggers rollback." +- "Support tickets mentioning the feature exceed 50 in the first hour triggers escalation." +- "Funnel completion drops below 50 percent of pre-launch baseline for any cohort triggers paused rollout." + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate; the rule fires automatically and the team executes the rollback. + +Detail in [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md). + +--- + +## Launch day: comms execution + +The comms calendar from the customer comms section executes on launch day. Each channel has a clear owner, a clear time, and a clear sequence. + +- In-app banner activates when rollout reaches X percent. +- Email sends after a 4-hour stability check. +- Blog post publishes at the time announced internally. +- Sales briefing happens one day before public comms. +- Support training happens one week before launch. + +The "comms misfire" failure. Blog post auto-publishes at the scheduled time, but the rollout was paused two hours earlier due to an issue. Customers click through to a feature that is behind a flag for them. They lose trust; the launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +--- + +## Post-launch: measurement against spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses about what the feature would change. The launch measurement plan validates or invalidates each. + +Four measurement dimensions. + +1. **Adoption.** Did the right users actually use it? The reach question. Is the feature visible to the target segment, and are they trying it. +2. **Engagement.** Did users who tried it come back? The stickiness question. First use is necessary but not sufficient. +3. **Outcome.** Did the metric the spec said this would move actually move? The effect question. The hypothesis the spec made. +4. **Side effects.** Did any other metric move that was not supposed to? The safety question. Sometimes the feature works but breaks something else. + +Time horizons. Most launches need two to four weeks of post-launch data for engagement signals, four to eight weeks for outcome signals. Do not declare success or failure too early. + +The "no measurement plan" failure. Feature ships; the team moves on; six months later nobody knows if it worked. The feature becomes maintenance debt; the team cannot decide whether to invest in it further. + +Detail in [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md). + +--- + +## Post-launch: iteration and follow-ups + +Within the first four weeks post-launch, expect. + +- Bug discoveries that did not surface in QA or limited rollout. +- Usability issues that did not surface in user research. +- Adoption gaps in cohorts you did not expect to under-adopt. +- Feature requests for adjacent capabilities. + +The discipline. Document every issue, triage weekly, prioritize fixes against the original measurement plan. + +If adoption is below target, the question is. Is it a marketing problem (users do not know about the feature)? A usability problem (users try the feature and bounce)? A value problem (users try the feature and do not see value)? A wrong-segment problem (the target was not who we thought)? + +Each diagnosis maps to a different fix. + +- Marketing problem: more comms, repeat comms, sales reactivation. +- Usability problem: design or onboarding fix. +- Value problem: feature redesign or repositioning. +- Wrong-segment problem: re-target the comms to a different audience. + +The "we declared victory" failure. The launch metric hits target in week 1 (often due to the launch announcement spike); the team moves on; the metric falls back to baseline by week 4. The launch was reported as successful but the feature did not actually land. + +The fix. Declare success or failure based on a stable post-launch trend, not the launch-week spike. Most launches need at least a four-week stable trend before the success or failure call is reliable. + +--- + +## Common failure modes + +Twelve patterns recur across feature launches. Detail in [`references/common-launch-failures.md`](references/common-launch-failures.md). + +- "We shipped it but nothing happened." Unlaunched. No comms plan, no internal alignment, no measurement. +- "Sales is confused and selling it wrong." No enablement. Battlecard, demo, training were skipped or rushed. +- "Support is overwhelmed." No training, no FAQ. Support is encountering the feature for the first time when customers ask. +- "We rolled out and immediately rolled back." No rollout strategy, no health check. The big-bang deploy hit production and broke. +- "The blog post went out but the feature is broken." Comms misfire. The comms were not gated on rollout health. +- "Adoption was great in week 1, now it is flat." Declared victory on the launch spike. The metric reverted to baseline. +- "We do not know if it worked." No measurement plan tied to spec hypotheses. +- "Customers say we did not tell them." Comms did not reach the right segments. Email went to active users only; inactive users were not notified. +- "Enterprise customers found out from their account manager three days late." No high-touch tier in comms. Top accounts deserve sales-led briefing before public comms. +- "Our metric moved but it was actually because of a different launch that week." No isolation. Cannot attribute the metric movement to this launch versus other concurrent changes. +- "We launched the wrong feature." Positioning unclear. Customers expected something different from what shipped; the gap between expectation and reality reads as a failed launch even though the feature works. +- "It worked but nobody knew about it internally." No internal alignment. Sales did not capitalize on the feature in deals; customer success did not save accounts that were churning over the gap this feature now closes. + +--- + +## The framework: 12 considerations for a real launch + +When planning a launch, walk these 12 considerations. Skipping any of them produces one of the failure modes above. + +1. **Tier the launch.** Tier 1, Tier 2, or Tier 3. Match the effort to the feature. +2. **Position it.** Target user, problem, promise, proof points, anti-positioning. +3. **Align internally.** Single launch brief, distributed two to four weeks before launch. +4. **Plan customer comms.** Channel mix, calendar, owners, gates. +5. **Enable sales.** Battlecard, demo, training, deal coaching (B2B only). +6. **Ready support.** Training, FAQ, escalation paths, monitoring access. +7. **Pick a rollout strategy.** All-at-once, gradual, flag-gated, or phased. +8. **Define monitoring.** Metrics, alerts, rollback triggers. Pre-defined, not in-the-moment. +9. **Sequence comms execution.** Gated on health checks. Never auto-fire if the rollout is paused. +10. **Tie measurement to spec hypotheses.** Adoption, engagement, outcome, side effects. +11. **Iterate post-launch.** Weekly triage. Distinguish marketing, usability, value, and segment problems. +12. **Declare success or failure on a stable trend.** Not the launch-week spike. + +The output of the framework is a launch plan document. The positioning canvas, the internal launch brief, the comms calendar, the rollout strategy with health-check gates, the monitoring spec with rollback triggers, and the post-launch measurement plan tied to the spec hypotheses. The plan is reviewed two weeks before launch; gaps are filled before the launch date. + +--- + +## Reference files + +- [`references/launch-tier-decision.md`](references/launch-tier-decision.md) - Tier 1, 2, 3 decision framework with worked examples. +- [`references/positioning-canvas.md`](references/positioning-canvas.md) - One-page positioning template with B2B SaaS, B2C, and developer feature examples. +- [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md) - Stakeholders, brief structure, distribution timing by tier. +- [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md) - Channels, calendar, owners, gates. +- [`references/sales-enablement-template.md`](references/sales-enablement-template.md) - Battlecard, demo, deal coaching, training (B2B). Skip note for B2C and PLG. +- [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md) - Training, FAQ, escalation, monitoring access. +- [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md) - Four patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. +- [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md) - Metrics dimensions, alert thresholds, pre-defined rollback triggers. +- [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md) - Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. +- [`references/common-launch-failures.md`](references/common-launch-failures.md) - Twelve failure patterns with diagnoses and fixes. + +--- + +## Closing: most failed launches are unlaunched + +When a feature "fails," the most common diagnosis is not that the feature was wrong. It is that the launch was incomplete. Sales did not know. Customers were not told. Support could not help. The metric did not move because the launch did not reach the people who would have moved it. + +Before declaring a feature failed, audit the launch against this playbook. Half the time the feature was fine; the launch never happened. + +The discipline of separating shipping from releasing from launching is the single most useful PM vocabulary upgrade. Use it explicitly. Use it in stand-ups, in roadmap reviews, in launch retrospectives. The team that uses precise language about what has happened catches unlaunched features before declaring them failed and reallocates the engineering investment toward features that would actually capture value. + +When in doubt about whether a launch is ready, ask: is the launch brief written and distributed? Has sales seen the battlecard? Does support have the FAQ? Is the rollout strategy chosen and the rollback trigger defined? Are the comms gated on a health check? Is the measurement plan tied to the spec hypotheses? + +If any of those answers is no, the launch is not ready. Delaying the launch by a week to close the gaps is cheaper than launching incomplete and capturing a fraction of the value the feature could have delivered. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md b/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md new file mode 100644 index 0000000..987206f --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md @@ -0,0 +1,181 @@ +# Common launch failures + +Twelve patterns that recur across feature launches. For each: name, symptom, root cause, fix, prevention. Cross-references to other reference files. + +--- + +## 1. We shipped it but nothing happened + +**Symptom.** The team reports "we shipped feature X." Three weeks later, nobody is using it. The metric the spec said this would move has not moved. Internal stakeholders ask if the feature is live; nobody is sure. + +**Root cause.** Unlaunched. Engineering completed the work; the team did not execute the launch. No comms plan, no internal alignment, no measurement plan tied to spec hypotheses. + +**Fix.** Treat it as a re-launch. Audit against the playbook: positioning, internal alignment, customer comms, sales enablement, support readiness, measurement plan. Distribute the launch brief. Sequence comms. Re-measure at the four-week checkpoint. + +**Prevention.** The launch brief is the artifact that prevents this. Without a brief, the launch defaults to engineering completion plus silence. With a brief, the launch has a calendar, owners, and measurement. + +See: `internal-alignment-checklist.md`, `customer-comms-playbook.md`, `post-launch-measurement-framework.md`. + +--- + +## 2. Sales is confused and selling it wrong + +**Symptom.** Customers ask sales questions sales cannot answer. Reps over-promise capabilities the feature does not have. Customers churn because the feature was sold wrong. + +**Root cause.** No sales enablement. Battlecard, demo, training were skipped or rushed. Reps are improvising in front of customers. + +**Fix.** Pause the launch (pause public comms; let in-app and release notes continue). Run the sales enablement playbook in compressed form: write the battlecard, record the demo, hold the training. Resume public comms after sales is enabled. + +**Prevention.** Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. Battlecard plus 30-minute training plus recorded demo. The investment is small; skipping it is the largest avoidable launch cost. + +See: `sales-enablement-template.md`. + +--- + +## 3. Support is overwhelmed + +**Symptom.** Support ticket volume doubles or triples on launch day. Tickets pile up. Customer wait times balloon. Support reps escalate everything to the PM. + +**Root cause.** No training, no FAQ, or both. Support is encountering the feature for the first time when customers ask about it. They cannot answer questions; they escalate; the queue grows. + +**Fix.** Emergency FAQ. PM and support lead spend 4 hours documenting every question that has come in. FAQ updates push to support immediately. Re-train if needed (a short refresher). + +**Prevention.** Support training one week before launch. FAQ written before launch, not during. Estimate support volume realistically; staff for elevated volume. + +See: `support-readiness-checklist.md`. + +--- + +## 4. We rolled out and immediately rolled back + +**Symptom.** Big-bang deploy hit production. Within minutes, error rate was up. The team rolled back. Customers experienced a broken feature for 30 minutes; some saw error states. + +**Root cause.** Wrong rollout strategy. All-at-once was used when gradual was the right pattern. + +**Fix.** Audit the rollback. What was the bug; what would have caught it earlier in a gradual rollout. Pre-mortem the next launch. + +**Prevention.** Default to gradual percentage rollout for most launches. Use all-at-once only when the marketing-coordinated launch makes it unavoidable, AND the team has high confidence in correctness, AND the blast radius is low. + +See: `rollout-strategy-patterns.md`. + +--- + +## 5. The blog post went out but the feature is broken + +**Symptom.** Blog post auto-published at the announced time. Rollout had been paused two hours earlier due to an issue. Customers click through; 75 percent of them do not have the feature; they report "broken" feature that is actually a paused rollout. + +**Root cause.** Comms not gated on rollout health. Auto-fire schedule executed regardless of rollout state. + +**Fix.** Pull or update the blog post. Communicate transparently: "We hit an issue in our rollout; the feature is paused while we resolve. Your account will get access once we resume." + +**Prevention.** Make external comms manually triggered, gated on health check. Auto-fire is convenient but brittle. + +See: `customer-comms-playbook.md`. + +--- + +## 6. Adoption was great in week 1, now it is flat + +**Symptom.** The launch announcement drove a spike of users trying the feature. By week 4, adoption has dropped back to near-baseline. The team had declared victory in week 1. + +**Root cause.** Declared victory on the launch spike. The metric reverted because the launch announcement was the only driver of usage; users tried the feature once but did not come back. + +**Fix.** Re-evaluate as if the launch is unfinished. Diagnose: was it an awareness problem (users forgot the feature exists), a usability problem (users tried and bounced), a value problem (users tried and did not see value), a wrong-segment problem (the audience was wrong). Iterate based on the diagnosis. + +**Prevention.** Declare success or failure on the stable post-launch trend, not the launch-week spike. Minimum measurement window is four weeks. + +See: `post-launch-measurement-framework.md`. + +--- + +## 7. We do not know if it worked + +**Symptom.** Six months after launch, the team cannot answer "did feature X work?" Nobody measured. The feature is now maintenance debt. + +**Root cause.** No measurement plan tied to spec hypotheses. The launch did not commit to specific metrics with specific decision rules. + +**Fix.** Retroactive measurement. Pull the data; compare to a pre-launch baseline (if one exists); compute the lift. The retroactive measurement is less rigorous than a planned one but better than nothing. + +**Prevention.** Every launch has a measurement plan. The plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +See: `post-launch-measurement-framework.md`. + +--- + +## 8. Customers say we did not tell them + +**Symptom.** A customer reaches out asking why nobody told them about a feature that has been live for two months. The customer was on the email list; the email was sent; the customer missed it. + +**Root cause.** Comms did not reach the right segments. Email went to active users only; inactive users were not notified. Or the email subject line was generic and customers archived without reading. + +**Fix.** Re-send to the cohort that missed it. Use a different channel (in-app banner, account-manager outreach for top accounts). Improve the discoverability for new visitors (pricing page mention, feature-tour highlight). + +**Prevention.** Channel-mix analysis. For each launch, plan which channels will reach which cohorts. Inactive users need a different reach plan than active users. + +See: `customer-comms-playbook.md`. + +--- + +## 9. Enterprise customers found out from their account manager three days late + +**Symptom.** Enterprise customer hears about a launch from their account manager three days after public comms went out. The customer is annoyed; their AM is embarrassed; trust erodes. + +**Root cause.** No high-touch tier in comms. Public comms hit before account managers had been briefed. + +**Fix.** Apologize to the affected customer. Brief their AM immediately with the full context. Adjust process for the next launch. + +**Prevention.** Sales-led briefing for top accounts before public comms. Account managers should know about the feature one to three days before customers do, with talking points for the customer conversation. + +See: `customer-comms-playbook.md`, `sales-enablement-template.md`. + +--- + +## 10. Metric moved but it was actually because of a different launch that week + +**Symptom.** Outcome metric is up 8 percent in the four weeks post-launch. Team celebrates. Then someone notices a different launch happened the same week, and a price test concluded, and a marketing campaign ran. The 8 percent cannot be attributed to this specific feature launch. + +**Root cause.** No isolation. Multiple changes hit production in the same window; effects are confounded; the team cannot tell which change drove which metric. + +**Fix.** Run a follow-up isolated test. Roll back the feature for a cohort; measure the gap. If the gap is large, the feature was driving the metric. If the gap is small, other concurrent changes were the driver. + +**Prevention.** Stagger launches. Major launches should not coincide with each other; at minimum two weeks of separation for measurement isolation. For experiments, use the warehouse-native experimentation framework to isolate. + +See: `data-warehouse-experimentation` skill. + +--- + +## 11. We launched the wrong feature + +**Symptom.** The launch goes out. Customers respond with "this is great but it does not solve the problem we asked you to solve." The feature works; it just was not what customers expected. + +**Root cause.** Positioning unclear. The customer expected something different from what shipped because the spec, the comms, or both implied a different scope. + +**Fix.** Re-position. Re-write the comms to match what the feature actually does. Acknowledge the gap to customers who feel misled. Plan a follow-up that addresses the original ask. + +**Prevention.** The positioning canvas plus anti-positioning section forces explicit definition of what the feature is and is not. Review the canvas with sales and customer success before launch; their pushback often catches the positioning gap. + +See: `positioning-canvas.md`. + +--- + +## 12. It worked but nobody knew about it internally + +**Symptom.** The metric moved. Customer adoption was strong. The launch was a success. Six weeks later, sales is not pitching the feature, customer success is not using it as a save argument, and the executive team has forgotten about it. + +**Root cause.** No sustained internal awareness. The launch hit; the team moved to the next thing; internal momentum did not carry. + +**Fix.** Re-brief internal stakeholders at the four-week checkpoint. Share the metrics. Highlight customer use cases. Make the feature part of the next sales kickoff or company all-hands. + +**Prevention.** Internal launch is not a one-time event. After the four-week measurement, revisit. Share the win story. Update the sales playbook. The launch is not over until the feature is part of the team's vocabulary for at least a quarter. + +See: `internal-alignment-checklist.md`. + +--- + +## The pattern across all twelve + +Most launch failures share one root cause. The team treated the launch as a single event (the day the feature ships) rather than a multi-week discipline (the period when the feature lands). + +The shipping vs releasing vs launching distinction names this. Shipping is a moment; releasing is a moment; launching is a discipline that spans the four to eight weeks before and after. Teams that invest in the discipline catch most failure modes early; teams that treat the launch as a moment hit failure modes late or never. + +The fix at the meta level. Pre-launch checklist. Launch-day standup. Post-launch measurement at four-week and eight-week checkpoints. The discipline is the only thing that produces consistent launches across many features. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md b/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md new file mode 100644 index 0000000..739ade4 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md @@ -0,0 +1,148 @@ +# Customer comms playbook + +Channels, decision factors, calendar template, comms misfire failure mode. + +The principle. Every channel has a different reach, latency, and cost. Pick the channels that match the feature's audience and tier; sequence them so the highest-touch channels fire first and the highest-reach channels fire last. + +--- + +## Channel-by-channel + +### In-app + +**Reach.** Active users only. Highest engagement among the people who already use the product. + +**Latency.** Real-time once the rollout reaches them. + +**Right for.** Product-internal features. Tooltips, banners, modals. Discoverability prompts. + +**Decision factors.** Are users active enough to encounter the in-app surface within the launch window? If your DAU is 10 percent of MAU, in-app reaches one in ten users in the first week. + +**Anti-pattern.** Modal interrupting the user mid-task. Use banners, tooltips, or empty-state prompts that the user notices but does not have to dismiss. + +### Email (transactional or campaign) + +**Reach.** All users who opted in. Higher than in-app for inactive users. + +**Latency.** Hours from send to read. Delays for users who batch-read email. + +**Right for.** Material changes that affect existing workflows. Pricing changes. Breaking changes that need user awareness. + +**Decision factors.** Is the change material enough to justify an email? If the user can discover the feature on their next visit, email may be unnecessary. If the change affects their billing or their workflow, email is the right channel. + +**Anti-pattern.** Sending email for every release. Customers unsubscribe; the channel decays. + +### Blog post + +**Reach.** External traffic plus existing customers who read the blog. Best for SEO, lead gen, narrative. + +**Latency.** Hours to days from publish to traffic peak. + +**Right for.** Tier 1 launches with external story. Competitive positioning announcements. Major narrative shifts. + +**Decision factors.** Is there a story worth telling beyond "we shipped a feature"? Blog posts about feature ships read as marketing churn; blog posts about category narrative shifts read as substantive. + +### Release notes + +**Reach.** Customers who actively check release notes. Discoverable later via search. + +**Latency.** Real-time on publish; the long-tail value comes from search-engine and customer-search traffic over the following months. + +**Right for.** Every Tier 2 and above. The canonical reference customers find later when they encounter the feature in the wild. + +**Decision factors.** Always. Release notes are the cheapest comms channel; the cost of writing one is small; the long-tail value is real. + +### Social (LinkedIn, X, Bluesky) + +**Reach.** Beyond existing customers. Mostly other PMs, engineers, prospects. + +**Latency.** Hours to days from post to engagement. + +**Right for.** Launches with external narrative or competitive angle. Founder-led marketing. + +**Decision factors.** Does the launch have a story that a non-customer would care about? If no, social is filler. If yes, social can drive net-new pipeline. + +### Webinar or customer call + +**Reach.** Limited to attendees, but high engagement per attendee. + +**Latency.** Days to weeks from announcement to event. + +**Right for.** Tier 1 launches with material customer impact. Enterprise customers who need depth. + +**Decision factors.** Does the feature need explanation that a blog post or email cannot deliver? If yes, webinar. If the feature is self-evident, skip. + +### Sales-led briefing + +**Reach.** Top accounts only. Highest-touch channel. + +**Latency.** Days from scheduling to delivery. + +**Right for.** Launches affecting pricing, contracts, or strategic positioning. Top accounts hear about the feature from their account executive before they hear from any other channel. + +**Decision factors.** Does the launch affect the top 10 to 20 accounts in a way that requires a personal conversation? If yes, sales-led briefing is non-negotiable. + +--- + +## The comms calendar + +A single document with all channels and dates. Distributed in the internal launch brief. + +| Date | Channel | Owner | Status | Notes | +|---|---|---|---|---| +| T minus 14 days | Sales briefing scheduled | Sales lead | Pending | 30-min training | +| T minus 7 days | Support training delivered | Support lead | Pending | Live + recorded | +| T minus 3 days | CS outreach to top 20 accounts | CS lead | Pending | Email plus call | +| T minus 1 day | Sales briefing delivered | Sales lead | Pending | Q&A captured | +| T minus 1 day | Support FAQ published internally | Support lead | Pending | | +| T plus 0 (launch day, AM) | In-app banner activates | Eng | Auto on rollout | Gated on health | +| T plus 0 (launch day, AM) | Release notes publish | PM | Manual on health | | +| T plus 0 (launch day, PM) | Email send to all customers | Marketing | Manual on health | After 4-hr stability | +| T plus 1 day | Blog post publishes | Marketing | Manual on health | | +| T plus 1 day | Social posts | Marketing + founder | Manual on health | | +| T plus 7 days | Webinar (Tier 1 only) | PM + Marketing | Scheduled | | +| T plus 14 days | First post-launch checkpoint | PM | Recurring | Adoption review | + +The calendar names every channel, every date, every owner. Gaps in the calendar signal channels that are not covered (intentionally or accidentally). + +--- + +## Sequencing principles + +**Highest-touch first.** Sales-led briefing for top accounts before public comms. The top customer hearing about a feature from their account manager before they hear from a blog post is a trust win; the inverse is a trust loss. + +**Internal before external.** Sales training before sales is asked customer questions. Support training before customers ask support questions. Internal launch brief before any customer-facing channel fires. + +**Health-check gates on auto-fire channels.** In-app banners, scheduled emails, scheduled blog posts should be gated on a rollout health check. Manual triggers preferred for any channel that would be embarrassing if the rollout is paused. + +**Lower-reach to higher-reach.** Release notes and in-app first; email second; blog and social last. The lower-reach channels catch initial issues; the higher-reach channels amplify after stability. + +--- + +## The comms misfire failure + +The most common comms execution failure. + +**The setup.** The blog post is scheduled to auto-publish at the announced launch time. The rollout starts at 9 AM. At 11 AM, an issue is detected and the rollout is paused at 25 percent. The blog post auto-publishes at noon as scheduled. + +**The result.** Customers click through to the new feature page. 75 percent of them do not see the feature (the rollout has not reached them). They report bugs that are actually rollout-paused state. The launch story breaks. + +**The fix.** Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +The pattern. Auto-fire is convenient but brittle. Manual triggers are slightly more work but catch issues that auto-fire cannot. + +--- + +## Channel-mix rules of thumb by feature type + +| Feature type | Recommended channel mix | +|---|---| +| New feature for active users (Tier 2) | In-app + release notes | +| Major feature launch (Tier 1, B2B) | All channels: in-app, email, blog, release notes, social, sales-led briefing for top accounts | +| Pricing change | Email + blog + sales-led briefing + executive comms; in-app for affected users | +| Breaking change | Email + in-app prominent banner + release notes + (B2B) sales-led briefing | +| Performance improvement | Release notes + (Tier 2) in-app + (Tier 1) blog post | +| New integration | Release notes + email + blog + co-marketing with the integration partner | +| Enterprise-only feature | Sales-led briefing + customer success outreach + release notes; skip blog and social | + +The pattern. The channel mix is not "all channels" by default. It is the subset of channels that match the audience and the tier. Skipping the wrong channel hurts; firing on the wrong channel also hurts. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md new file mode 100644 index 0000000..13637c1 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md @@ -0,0 +1,144 @@ +# Internal alignment checklist + +Stakeholders, brief structure, distribution timing. The launch brief is the single document that aligns everyone before customer comms go out. + +The principle. Internal alignment fails silently. The team does not know they are misaligned until a customer asks sales a question that sales cannot answer, or a customer escalates an issue support did not know existed. The launch brief catches misalignment before customers do. + +--- + +## Stakeholders by org type + +### Small startup (under 50 employees) + +- Engineering lead. Capacity for fixes, support escalation handling. +- Sales lead (if B2B). Pipeline impact, deal coaching. +- Customer success / support lead. Often the same person at this size. +- Marketing or content lead (if exists). Comms execution. +- Executive sponsor. Usually CEO at this size. + +The brief is shorter at this size; the meeting is faster; but the discipline still matters. The "small team did not need a launch brief" assumption is a frequent source of small-launch failures. + +### Mid-size (50 to 500 employees) + +- Engineering leadership. +- Sales leadership and at least one regional sales lead. +- Customer success leadership. +- Marketing leadership. +- Support leadership. +- Executive sponsor (VP-level for most launches; C-level for Tier 1). + +The brief is longer. The launch meeting includes a Q&A. Decision log captures the questions and answers; the log is part of the brief. + +### Enterprise (500+ employees) + +- Engineering leadership. +- Sales leadership across regions and segments. +- Customer success leadership. +- Marketing leadership including PMM (product marketing manager). +- Support leadership. +- Legal, security, and compliance (for features touching pricing, data, or regulated workflows). +- Executive sponsor (C-level for Tier 1). + +At this size, the launch brief is a formal document with sections owned by different functions. PMM often co-owns the brief with the PM. + +--- + +## The launch brief + +A single document distributed two to four weeks before Tier 1 launch, one week before Tier 2 launch. + +### Section 1: one-page summary + +Top of the brief. The PM writes it. The reader should be able to answer "what is launching, when, who is it for, why now" after one minute. + +### Section 2: positioning + +The positioning canvas (from the positioning-canvas reference) embedded directly. Target user, problem, current alternative, user-visible promise, proof points, anti-positioning. + +### Section 3: launch calendar + +Every channel and every date. In-app banner activation, email send, blog post publish, social post times, sales briefing, support training, customer success outreach windows. Owners named for each. + +### Section 4: what each function needs to do differently + +The most important section for the readers. Each function gets a paragraph. + +- **Sales.** Battlecard link. Demo recording link. Top objections and answers. Deals to revisit. Training session date. +- **Customer success.** Top accounts to brief. Talking points for the briefing. Escalation contact during launch week. +- **Support.** Training session date. FAQ link. Escalation path. Ticket tagging convention. +- **Marketing.** Channel list, dates, message variants by channel. +- **Engineering.** On-call coverage during launch. Rollback authority. Health-check dashboard link. + +If a function does not have a paragraph, the launch was not designed with that function in mind; revisit before distributing. + +### Section 5: FAQ + +The questions that have already come up internally, with answers. The FAQ updates daily during the first week of distribution as new questions surface. + +### Section 6: decision log + +Choices already made. Includes the rationale for non-obvious decisions. Future questions ("why did we pick that rollout strategy?") get answered by reading the log instead of re-litigating the decision. + +--- + +## Distribution timing + +| Tier | Timing | Channel | +|---|---|---| +| Tier 1 | 2 to 4 weeks before launch | Email plus async meeting plus 1:1 follow-ups for sales and CS | +| Tier 2 | 1 week before launch | Email plus async meeting | +| Tier 3 | Day of launch or as part of a weekly release digest | Email or shared doc | + +The pattern. Launch brief lands first. Sales briefing, support training, customer success outreach all happen after the brief lands and before the public comms fire. + +--- + +## The pre-launch meeting + +For Tier 1 launches, hold a 30-minute pre-launch meeting one week before launch. + +Agenda. + +1. PM walks through the positioning canvas and the calendar (10 minutes). +2. Each function lead confirms their readiness (10 minutes). +3. Open Q&A captured in the decision log (10 minutes). + +The meeting is not for re-litigating the launch. It is for confirming readiness and catching last-minute gaps. If functions are not ready, the launch is delayed. The PM has authority to delay; the executive sponsor confirms. + +--- + +## The launch-day standup + +For Tier 1 launches, hold a brief launch-day standup at the start of launch day. Five to ten minutes. + +Agenda. + +1. Confirm rollout health check is green. +2. Confirm comms are gated on the health check (the social post will not auto-fire if the rollout is paused). +3. Confirm support is staffed for the launch window. +4. Confirm escalation contacts are reachable. +5. Open the post-launch monitoring channel. + +The launch-day standup catches "the marketing person took the day off and the social post is set to auto-fire" the morning of launch instead of in the moment. + +--- + +## Common internal alignment failures + +- **Launching without sales knowing.** Sales finds out from a customer. Trust erodes for the next launch. Fix: launch brief plus sales-specific briefing one to two weeks before public comms. +- **Sales briefing is the launch brief.** Sales reads a 12-page document. Their actual takeaway is partial. Fix: separate one-pager for sales (the battlecard) plus the full brief for reference. +- **Support is trained the day of launch.** Support cannot internalize a new feature in one morning. Fix: train support one week before customer-facing launch. +- **Customer success outreach happens after public comms.** Top accounts hear about the feature from the email blast like everyone else. Fix: customer success briefs top accounts one to three days before public comms. +- **Executive sponsor is surprised on launch day.** The executive read the brief but did not internalize it; on launch day they see press coverage and ask the team questions that should have been answered in the brief. Fix: brief executives in person, not just via document. + +--- + +## When the brief reveals misalignment + +The brief is the artifact that surfaces misalignment. Common signals. + +- The positioning canvas does not match how sales describes the customer profile. Misalignment between PM and sales on who the customer is. +- The launch calendar does not give sales enough time. Misalignment on what enablement requires. +- The FAQ has questions nobody can answer. Misalignment on what the feature actually does. + +The pattern. Surface misalignment before launch; resolve before launch. The brief is the tool that forces the conversation. A team that drafts the brief carefully and finds it easy to write probably has no misalignment. A team that struggles to write the brief has misalignment that the brief is now revealing; resolve it before customer comms go out. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md b/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md new file mode 100644 index 0000000..dab6ffc --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md @@ -0,0 +1,137 @@ +# Launch tier decision + +Tier 1 / Tier 2 / Tier 3 decision framework. Worked examples. Anti-patterns on both sides. + +The principle. Match launch effort to feature scope. Treating every release as Tier 1 produces comms fatigue; treating every release as Tier 3 produces unlaunched features. + +--- + +## The tiers + +### Tier 1: full launch + +**Scope.** Net-new product, major feature reshaping the product narrative, pricing change, breaking change. + +**Effort.** Full playbook. Positioning, all comms channels, sales enablement (B2B), customer success briefing, dedicated post-launch measurement, executive announcement. Two to four weeks of pre-launch work; four to eight weeks of post-launch monitoring. + +**Examples.** + +- A new product surface (Slack adds Canvas; Figma adds FigJam; Notion adds Sites). +- A pricing model change (per-seat to consumption; introducing a new tier). +- A foundational replatforming with user-visible impact (a new UI architecture, a new permissions model). +- A flagship competitive feature (the thing the sales team has been asking for, the thing the analyst report compared you on). + +### Tier 2: focused launch + +**Scope.** Meaningful improvement that materially affects user value or competitive positioning. + +**Effort.** Subset of the playbook. In-app comms, blog post or detailed release note, support readiness, rollout strategy, post-launch measurement. One to two weeks of pre-launch work; two to four weeks of post-launch monitoring. + +**Examples.** + +- A new export format that customers have been requesting. +- A redesigned core flow (e.g., a new onboarding experience). +- An integration with a major third-party (Slack notifications, Salesforce sync). +- A meaningful performance improvement (page loads twice as fast on a flagship surface). + +### Tier 3: release note + +**Scope.** Incremental improvement, bug fix made positive, polish. + +**Effort.** Minimal. Changelog entry, release note, light monitoring. Hours of pre-launch work; passive monitoring post-launch. + +**Examples.** + +- A new keyboard shortcut. +- A small UI polish (better empty states, refined typography). +- A minor configuration option (toggle to disable a non-default behavior). +- A bug fix that improves reliability for a small cohort. + +--- + +## Decision framework + +When unsure between two tiers, ask three questions. + +1. **Will sales need to talk about this?** If yes, at least Tier 2. If sales is selling against this gap today, Tier 1. +2. **Will customers be confused if we do not tell them?** If yes, at least Tier 2. +3. **Will the metric this is meant to move show up in board reporting?** If yes, Tier 1. If yes but only at the team level, Tier 2. + +If all three answers are no, the feature is Tier 3. + +--- + +## Worked examples + +### Example 1: a new export-to-PDF capability + +A B2B SaaS product adds export-to-PDF to its reporting feature. + +- Will sales talk about this? Yes; this has been a top sales objection. +- Will customers be confused without comms? No; the feature is discoverable in the existing UI. +- Will the metric move at board level? Probably not directly; might unblock some deals. + +**Tier 2.** Sales enablement (battlecard plus a one-paragraph deal-coaching note). Blog post. Release note. In-app banner on the reporting page. Light monitoring. + +### Example 2: a new pricing tier with consumption-based billing + +A SaaS company adds a usage-based tier alongside its existing per-seat plans. + +- Will sales talk about this? Yes; pricing changes always involve sales. +- Will customers be confused without comms? Yes; existing customers will wonder if they should switch. +- Will the metric move at board level? Yes; revenue mix and ARR composition are board-level. + +**Tier 1.** Full positioning canvas. Internal launch brief 4 weeks ahead. Sales enablement including pricing change documentation. Email to existing customers explaining what is and is not changing for them. Blog post. Webinar for top accounts. Phased rollout starting with new customers, then existing customer opt-in. + +### Example 3: a keyboard shortcut for a power-user action + +A consumer app adds Cmd+K for quick navigation. + +- Will sales talk about this? No; consumer product, no sales motion. +- Will customers be confused without comms? No; the feature is purely additive and discoverable. +- Will the metric move at board level? No; small UX improvement. + +**Tier 3.** Changelog entry. Maybe a tweet from the product team. No further work. + +### Example 4: an enterprise SSO integration + +A B2B SaaS adds SAML SSO support. + +- Will sales talk about this? Yes; SSO is a hard requirement for many enterprise deals. +- Will customers be confused without comms? Existing self-service customers no; enterprise prospects yes. +- Will the metric move at board level? Indirectly; SSO unblocks enterprise deals worth real ARR. + +**Tier 1 if SSO unlocks the enterprise segment for the first time, otherwise Tier 2.** Sales enablement is the highest-impact piece (the deal-coaching note for previously SSO-blocked accounts). Customer success outreach to top enterprise prospects. Blog post focused on the security and IT audience. Quiet rollout for self-service customers (changelog only). + +--- + +## Anti-pattern: everything is Tier 1 + +Symptom. Every release gets a blog post, an email, a sales briefing. Customers tune out the announcement firehose. Real Tier 1 launches lose signal in the noise. Sales reps stop reading the briefings because they assume every one is minor. + +Fix. Be honest about which features are major. If you ship five "major" launches per quarter, three of them are Tier 2 or Tier 3 in disguise. The Tier 1 budget should be one to three per quarter for most companies. + +--- + +## Anti-pattern: everything is Tier 3 + +Symptom. Features ship without comms. Sales does not know what is new. Customers are surprised when they discover a feature six months after launch. Metrics do not move because users do not know the feature exists. + +Fix. Tier honestly. Most B2B SaaS releases are Tier 2; defaulting them to Tier 3 leaves value on the table. The minimum Tier 2 effort (release note plus in-app banner plus support FAQ) is small; the marginal value capture is large. + +--- + +## How tier affects the rest of the playbook + +| Section | Tier 1 | Tier 2 | Tier 3 | +|---|---|---|---| +| Positioning canvas | Required | Required | Skip | +| Internal launch brief | 2 to 4 weeks ahead | 1 week ahead | Skip | +| Customer comms | All channels | In-app + blog + release note | Release note | +| Sales enablement (B2B) | Full battlecard + demo + training | One-page note + Q&A | Skip | +| Support readiness | Full training | Brief + FAQ | FAQ if applicable | +| Rollout strategy | Phased or gradual | Gradual | Either | +| Monitoring | Full + rollback triggers | Standard + alerts | Passive | +| Post-launch measurement | 4 to 8 weeks | 2 to 4 weeks | Light | + +The pattern. Tier 1 is the full playbook. Tier 2 is the playbook compressed. Tier 3 is the changelog plus passive monitoring. Each section's depth scales with tier. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md new file mode 100644 index 0000000..6770c30 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md @@ -0,0 +1,185 @@ +# Monitoring readiness checklist + +Metrics dimensions, alert thresholds, pre-defined rollback triggers. The "no rollback trigger" failure mode. + +The principle. Monitoring catches launch issues before they compound into customer pain. The discipline is defining what to watch and what to do BEFORE launch, so the team executes rather than debates during the launch window. + +--- + +## What to monitor + +Six dimensions for most launches. + +### 1. Error rates + +- **Overall error rate.** The baseline. Has the deploy increased errors across the application. +- **Feature-specific error rate.** Errors in code paths the new feature touches. Often the first signal of a feature-specific bug. +- **Per-cohort error rate.** Errors broken down by user segment, plan, region. Catches cohort-specific bugs. + +### 2. Latency + +- **Overall P50, P95, P99.** Has the deploy slowed the application. +- **Feature-specific latency.** New code paths often have unoptimized queries; latency tracking catches them. +- **Database query latency.** New features often add new queries; database load can spike. + +### 3. Feature usage rate + +- **Reach.** Of users in the rollout cohort, how many actually trigger the feature within their first session post-rollout. +- **Frequency.** Of users who used the feature once, how many used it again. +- **The expected vs actual gap.** Pre-launch projections vs actual numbers. Large gaps in either direction need investigation. + +### 4. Funnel completion + +- **End-to-end completion of the workflow the feature is part of.** Did users complete the flow at the same rate as pre-launch. +- **Step-by-step drop-off.** Where in the flow are users abandoning. Compare pre-launch to post-launch step-by-step. +- **Per-cohort completion.** Cohort-specific drop-off can hide in aggregate metrics. + +### 5. Support ticket volume + +- **Overall ticket volume.** Has the team's support load increased. +- **Feature-tagged tickets.** Tickets where the customer mentions the feature. +- **Ticket sentiment.** Frustrated tickets vs informational tickets vs positive tickets. + +### 6. Customer satisfaction signals + +- **NPS comments.** Mentions of the feature in NPS responses. +- **Feedback widget.** In-product feedback explicitly about the feature. +- **Social mentions.** Twitter or LinkedIn posts about the launch. + +--- + +## Alert thresholds + +For each dimension, pre-defined thresholds that fire alerts. + +### Error rates + +- **Yellow.** Overall error rate up by more than 25 percent vs pre-launch baseline. Investigate without escalation. +- **Orange.** Overall error rate up by more than 50 percent vs baseline. Escalate to PM and engineering on-call. +- **Red.** Overall error rate above 1 percent absolute. Trigger rollback. + +### Latency + +- **Yellow.** P95 up by 25 percent vs baseline. Investigate. +- **Orange.** P95 up by 50 percent. Escalate. +- **Red.** P95 doubled or worse. Trigger rollback if sustained for 10 minutes. + +### Feature usage rate + +- **Yellow.** Below 50 percent of pre-launch projection. Investigate (probably comms or discovery problem). +- **Orange.** Below 25 percent of projection. Escalate; the launch may not be reaching users. +- **Red.** Near zero usage. Likely an instrumentation bug; the feature is not firing or the metric is not capturing. + +### Funnel completion + +- **Yellow.** Down by 10 percent from pre-launch baseline. Investigate. +- **Orange.** Down by 25 percent. Escalate; the feature may be breaking the flow. +- **Red.** Down by 50 percent for any cohort. Trigger rollback for that cohort or pause the rollout. + +### Support volume + +- **Yellow.** Feature-tagged tickets exceed 10 in the first hour. Investigate. +- **Orange.** Feature-tagged tickets exceed 50 in the first hour. Escalate. +- **Red.** Feature-tagged tickets exceed 100 in the first hour. Trigger rollback or pause; the feature has a real problem. + +The numbers above are illustrative. Calibrate to the team's actual support volume and the feature's expected reach. + +--- + +## Pre-defined rollback triggers + +A rollback trigger is a rule that fires automatically. The team executes the rollback without re-litigating whether to. + +### Examples + +**For a feature touching the checkout flow.** + +- Error rate above 1 percent sustained for 5 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline. +- Stripe API errors increase by 100 percent. + +**For a new internal tool.** + +- Error rate above 5 percent sustained for 5 minutes (higher tolerance because internal users provide more context). +- Adoption near zero after 24 hours (instrumentation bug or feature not deployed). + +**For a pricing change.** + +- Subscription cancellation rate increase by 50 percent in the first 48 hours. +- Customer service contact rate about pricing increase by 200 percent. +- Revenue forecast adjustment indicates a 10 percent quarterly miss. + +The pattern. Each rollback trigger names a specific metric, a specific threshold, and a specific time window. The team rehearses what to do when the trigger fires. + +### What rollback means + +Rollback can be one of several things. + +- **Full rollback.** Flag off, code reverted, user-visible state returns to pre-launch. +- **Pause at current rollout percentage.** Flag stays on for users who already have it; no new users get the feature. +- **Cohort-specific rollback.** Flag off for the cohort showing issues; flag on for cohorts that look healthy. +- **Fix-forward.** A small fix is deployed; rollout continues at the previous percentage. Risky; only use when the fix is high-confidence. + +The team should know which rollback path applies to which trigger before launch. + +--- + +## The on-call rotation + +For Tier 1 launches, the on-call rotation should include. + +- **Primary engineering on-call.** Standard rotation. Receives alerts, executes rollbacks. +- **Secondary engineering on-call.** Backup if primary is unreachable. +- **PM contact.** The PM who owns the launch is reachable during the launch window. +- **Support escalation contact.** The support lead responsible for routing customer issues to the right team. +- **Marketing contact.** For comms decisions if the rollout pauses. + +Reachability hours for Tier 1 launches: 24/7 for the first 48 hours, business hours plus on-call after that. + +--- + +## The "no rollback trigger" failure + +The pattern. + +- Launch goes sideways. Error rate is up; support volume is high; engineering is investigating. +- The team debates whether to roll back. The debate takes an hour. +- During the debate hour, more users encounter the issue. Support tickets pile up. The press notices. Trust erodes. +- The team eventually rolls back, but the recovery is now harder than it would have been one hour earlier. + +The fix. Pre-define the rollback triggers. Write them down. Get team agreement before launch. When a trigger fires, execute the rollback. Debate the appropriateness of the trigger after the rollback, not during the incident. + +The discipline. The cost of a wrong rollback (the team rolls back when the feature was actually fine) is small (a paused launch and a re-rollout). The cost of a delayed rollback (the team debates while the issue compounds) is large (customer impact, reputation, recovery cost). Bias toward fast rollback. + +--- + +## Post-rollback retrospective + +After any rollback, hold a retrospective within 48 hours. + +Agenda. + +1. What was the trigger that fired. +2. What was the actual problem. +3. Was the rollback the right call (almost always yes; even false positives that catch nothing teach the team about the system). +4. What is the path to re-launch (fix the bug, test it, validate the test, schedule a new rollout). +5. What did we learn that updates the next launch's monitoring. + +The retrospective is not a blame session. It is an investment in the next launch's monitoring quality. + +--- + +## Health check before each rollout step + +For gradual percentage rollouts, define a health check that gates each step. + +The health check passes when. + +- All Yellow thresholds clear for the prior percentage step's full duration. +- No Orange or Red alerts in the prior step. +- Support volume stable. +- Customer feedback (NPS, social) neutral or positive. + +The health check fails when any of the above conditions does not hold. The rollout pauses at the current step until the health check passes. + +The pattern. The rollout proceeds when the system is healthy; it does not proceed on a schedule. Schedule-driven rollouts that ignore health checks are how launches go sideways. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md b/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md new file mode 100644 index 0000000..4ab4b54 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md @@ -0,0 +1,132 @@ +# Positioning canvas + +The one-page positioning template. Worked examples for B2B SaaS, B2C, and developer features. The vague-target-user failure mode. + +The principle. Positioning is the foundation of the launch. Without it, comms drift, sales improvise, and customers come away with a different understanding of the feature than the team intended. Filled out before any comms drafting; reviewed by sales, support, and an executive sponsor before launch. + +--- + +## The canvas + +One page. Six sections. Filled out by the PM with input from sales, customer success, and design. + +### 1. Target user + +**Segment.** What kind of company or individual. + +**Role.** What is their job title or function. + +**Jobs-to-be-done.** What is the user trying to accomplish in their work or life that this feature serves. + +**Specificity test.** Could a sales rep describe the customer profile in one sentence? Could marketing target ads at this segment? If no to either, the target user is too vague. + +### 2. Problem it solves + +**The current pain.** In the user's words. What is hard, slow, error-prone, or impossible today. + +**The cost of the pain.** Time, money, errors, missed opportunities. Quantified where possible. + +**Specificity test.** Is the problem stated in concrete terms or in abstract language? "Productivity is low" is abstract. "The customer support manager spends 3 hours per day triaging tickets that an automated system could route" is concrete. + +### 3. Current alternative + +**What users do today without this.** The status quo, the workaround, the competing product, the manual process, the spreadsheet. + +The status quo is the real competition. A feature that is better than nothing but worse than the user's existing workaround does not get adopted. + +### 4. User-visible promise + +**One sentence.** The promise the user will hear when they encounter the feature. + +**Specificity test.** Can sales repeat it without changing words? Can support repeat it without paraphrasing? If no, it is too long or too abstract. + +### 5. Proof points + +**Three to five specific capabilities or outcomes.** Concrete, not adjectives. + +Examples of bad proof points: "fast," "easy," "secure," "intelligent." These are claims, not proof. + +Examples of good proof points: "exports a 200-page report in under 5 seconds," "supports 14 languages including right-to-left," "SOC 2 Type II audited by Deloitte 2025." + +### 6. Anti-positioning + +**What this is NOT.** What it does not try to do. + +Anti-positioning prevents over-promising. If the feature does not handle enterprise scale, say so. If it does not work offline, say so. If it does not replace the customer's existing tool, say so. + +The anti-positioning protects the team from sales reps who hear about the feature and embellish. It protects support from customers who expected something the feature does not do. + +--- + +## Worked example 1: B2B SaaS feature + +A B2B project management tool ships a new automated routing feature. + +| Section | Content | +|---|---| +| Target user | Customer support managers at SaaS companies with 10 to 100 support reps. JTBD: triage incoming tickets and route them to the right team without reading every ticket. | +| Problem it solves | Current manual triage takes 2 to 3 hours of a support manager's day. Tickets sit in the queue waiting for routing while customers grow impatient. The cost is 10+ hours per week of manager time plus 30 to 60 minute response delays on simple tickets. | +| Current alternative | Manual triage by a senior support rep, or basic keyword routing rules in their existing helpdesk that produce 30 to 40% misroutes. | +| User-visible promise | "Route incoming tickets to the right team in under 30 seconds with 95% accuracy." | +| Proof points | (1) ML model trained on 90 days of historical ticket routing decisions. (2) Accuracy benchmarks: 95% routing accuracy at launch, retraining weekly. (3) Override and feedback flow lets support managers correct routes; corrections feed back into the model. (4) Audit log of every routing decision for compliance. (5) Configurable confidence threshold; below the threshold, the ticket falls back to manual routing. | +| Anti-positioning | This is not a full ticket-resolution AI. It does not draft replies, identify duplicate tickets, or detect sentiment. It only routes. | + +The anti-positioning protects the team from sales reps who would otherwise pitch this as "AI customer support." + +--- + +## Worked example 2: B2C feature + +A consumer note-taking app ships AI-generated summaries. + +| Section | Content | +|---|---| +| Target user | Students and knowledge workers who maintain long-form notes. Specifically users with 50+ notes longer than 500 words. JTBD: quickly recall the key points of a note without re-reading it. | +| Problem it solves | Long notes get written then forgotten. The user cannot recall what is in them without scrolling and re-reading. Cost: hours per week of search-and-rediscover, plus the worse cost of acting on stale information. | +| Current alternative | Manual TLDRs the user writes themselves (rare). Highlighted text within the note (common but unreliable). Re-reading the full note (default; expensive). | +| User-visible promise | "See a summary of any note in two seconds." | +| Proof points | (1) Summaries appear at the top of every note over 500 words. (2) Summary regenerates when the note is meaningfully edited. (3) Click any summary point to jump to its source paragraph in the note. (4) Generates in under 2 seconds for notes up to 5,000 words. | +| Anti-positioning | This is not a research assistant; it does not pull in outside context or related notes. It summarizes the note in front of you, nothing more. | + +--- + +## Worked example 3: developer feature + +A developer tools company ships a new CLI command. + +| Section | Content | +|---|---| +| Target user | Backend engineers using the platform's CLI for deploys. Specifically engineers who run more than 5 deploys per week. JTBD: deploy faster and roll back when something breaks. | +| Problem it solves | Rollbacks today require digging through deploy history, finding the prior version, and running a deploy command with the version pinned. Takes 2 to 5 minutes; under incident pressure, the time matters. | +| Current alternative | Manual deploy command with version pin. Some teams script this; most do it from memory under pressure. | +| User-visible promise | "Roll back to the last known good deploy with one command." | +| Proof points | (1) Single command: `acme deploy rollback`. (2) Defaults to the most recent successful deploy that is older than the current. (3) Confirmation prompt shows what will be rolled back; passes through to the existing deploy flow. (4) Logged as a rollback in deploy history (not as a fresh deploy) for clean audit trail. | +| Anti-positioning | This does not auto-detect bad deploys. The engineer still decides when to roll back. | + +--- + +## The vague-target-user failure mode + +The most common positioning failure. The PM writes "It is for PMs" or "It is for engineers" or "It is for marketers." + +Why it fails. Different PMs, engineers, and marketers have different jobs. A B2B PM at a 50-person startup has a different job from a B2C PM at a 5,000-person company. A backend engineer has a different job from a frontend engineer. The vague target prevents sales from filtering, prevents marketing from targeting ads, prevents support from anticipating questions. + +The fix. Specificity layers. + +- Industry or company type. (B2B SaaS at 50 to 500 customers.) +- Role and function. (Customer support manager, not just "support.") +- Jobs-to-be-done. (Triage incoming tickets, not "improve productivity.") + +Three layers of specificity move the target from useless to actionable. If you cannot fill in all three, the team has not yet decided who the feature is for. + +--- + +## Reviewing the canvas + +Before launch, review the positioning canvas with three audiences. + +1. **Sales review.** Can sales pitch this in 30 seconds? Does the language match how customers ask about the problem? +2. **Support review.** Can support answer the obvious questions (what does it cost, how do I turn it on, what are the limits) using only the canvas? +3. **Executive review.** Does the positioning fit the company narrative? Will it confuse customers who are mid-purchase on a different feature? + +If any of the three review groups push back, fix the canvas before launch comms drafting begins. Drafting comms on top of weak positioning produces comms that look fine in isolation but contradict each other across channels. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md b/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md new file mode 100644 index 0000000..3475f47 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md @@ -0,0 +1,181 @@ +# Post-launch measurement framework + +Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. The "declared victory on launch spike" failure mode. + +The principle. The launch measurement plan answers "did this work." Without it, the team moves on without knowing. + +--- + +## Four measurement dimensions + +### 1. Adoption (the reach question) + +Did the right users actually use the feature. + +**Metrics.** + +- Reach: of users in the rollout cohort, what fraction has tried the feature. +- Time to first use: of users who tried the feature, how long after rollout. +- Distribution by cohort: are the right segments (per the positioning canvas) the ones using the feature. + +**Signal interpretation.** + +- High reach plus right cohorts: the launch reached the target audience. +- High reach plus wrong cohorts: the launch reached the wrong audience; positioning or comms missed the target. +- Low reach: comms problem or discovery problem. Investigate which channel users would have learned about the feature from. + +### 2. Engagement (the stickiness question) + +Did users who tried the feature come back. + +**Metrics.** + +- Retention: of users who tried the feature once, what fraction used it again within 7, 14, 30 days. +- Frequency: how many times per week did adopters use the feature. +- Depth: did adopters use the full feature or only the first step. + +**Signal interpretation.** + +- High first-time use plus high retention: the feature is delivering value. +- High first-time use plus low retention: the feature failed to deliver on the first-use experience. Usability or value-prop problem. +- Low first-time use plus high retention among the few who tried: the feature is valuable to a niche; reach the niche better, or accept that it serves a smaller audience. + +### 3. Outcome (the effect question) + +Did the metric the spec said this would move actually move. + +**Metrics.** + +- The primary metric from the spec. Usually a business metric (revenue, retention, support deflection, conversion rate). +- The lift relative to a pre-launch baseline. +- The statistical significance of the lift, if a controlled comparison is available. + +**Signal interpretation.** + +- Metric moved as predicted: the feature delivered the value the team committed to. +- Metric moved less than predicted: partial success; the feature works but did not have the size of impact the team expected. Investigate why (smaller cohort than expected, smaller per-user impact, or simply optimistic projection). +- Metric did not move: the launch did not deliver the promised value. Investigate before declaring failure (could be measurement timeline, isolation issues, or the feature genuinely failing). + +### 4. Side effects (the safety question) + +Did any other metric move that was not supposed to. + +**Metrics.** + +- Cohorts adjacent to the target: did the feature affect users it was not designed for. +- Adjacent metrics: did related metrics move (positively or negatively). +- Support volume on adjacent topics: did the feature confuse customers about other parts of the product. + +**Signal interpretation.** + +- No side effects: clean launch. +- Positive side effects: the feature delivered value beyond the target. Document for the next iteration. +- Negative side effects: the feature broke something else. Triage urgently; this is a launch quality issue regardless of whether the primary metric moved. + +--- + +## Time horizons + +Different signals stabilize at different times. + +| Signal type | Stable at | +|---|---| +| Adoption (reach) | 1 to 2 weeks post-launch | +| Engagement (retention) | 4 weeks for week-2 retention; 8 weeks for week-4 retention | +| Outcome | 4 to 8 weeks for most business metrics; longer for retention or LTV | +| Side effects | 2 to 4 weeks | + +The rule. Do not declare success or failure on the outcome metric before week 4. The launch-week spike is unrepresentative; the metric needs time to stabilize at its post-launch level. + +--- + +## Tying back to spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses. The launch measurement plan validates each. + +Example hypotheses from a hypothetical spec. + +- "We expect this feature to be used by 40 percent of paid users within 30 days of rollout." (Adoption hypothesis.) +- "Of users who try the feature, we expect 60 percent to use it again within 7 days." (Engagement hypothesis.) +- "We expect this feature to reduce support tickets in the X category by 25 percent." (Outcome hypothesis.) +- "We do not expect this feature to affect billing-related support volume." (Side-effect hypothesis.) + +The measurement plan validates each. + +| Hypothesis | Measurement | Decision rule | +|---|---|---| +| 40% paid user adoption in 30 days | Cohort: paid users in rollout. Metric: distinct user count using the feature divided by cohort size. | Above 30% acceptable; below 20% requires intervention. | +| 60% week-1 retention | Cohort: users who tried the feature in week 1. Metric: fraction of cohort using the feature again in week 2. | Above 50% acceptable; below 40% indicates value or usability problem. | +| 25% reduction in X-category support tickets | Pre-launch baseline 30 days; post-launch 30 days. Compare ticket volumes. | Above 15% reduction acceptable; below 10% indicates the feature is not solving the right problem. | +| No effect on billing support | Billing ticket volume pre vs post. | Volume change above 20% requires investigation. | + +The measurement plan is written before launch. The decision rules are pre-committed; the team does not move the goalposts after seeing the data. + +--- + +## The "declared victory on launch spike" failure + +The pattern. + +- Week 1: adoption is high. The team announced the feature; users tried it; the metric is up. +- Week 2: adoption flat. The launch announcement spike has passed; the new users have tried the feature. +- Week 3: adoption declining. Users who tried the feature once are not coming back. +- Week 4: adoption near pre-launch baseline. The metric has reverted. +- The team had already declared the launch a success in week 1 and moved on. + +The cost. The team's roadmap is now built on a launch that did not actually work. The next quarter's plan assumes the metric is at the elevated level; when it does not stay there, the plan does not deliver. + +The fix. Declare success or failure based on the stable post-launch trend, not the launch-week spike. The minimum measurement window is four weeks; for retention or LTV signals, eight to twelve weeks. + +The discipline. The four-week checkpoint is on the calendar before launch. The team holds itself accountable to revisit; the executive sponsor holds the team accountable to revisit. Launches that are reported as successful in week 1 and never revisited are silent failures. + +--- + +## The "no measurement plan" failure + +The pattern. + +- Feature ships. +- Team moves on to the next feature. +- Six months later, someone asks "did feature X work?" Nobody knows. +- The feature becomes maintenance debt; the team cannot decide whether to invest in iteration. + +The cost. The team accumulates features whose value is unknown. Roadmap decisions get harder because the historical track record is opaque. Engineering investment is wasted on features that did not work; the team does not learn from them because they did not measure. + +The fix. Every launch has a measurement plan. The plan is short (one page); it names the four dimensions, the metrics, the time horizons, and the decision rules. The plan is reviewed at week 4 and again at week 8 or 12 depending on the signal. + +The discipline. The measurement plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +--- + +## When the metric did not move + +If the outcome metric did not move at week 4, the next investigation. + +1. **Is adoption strong?** If adoption is below target, the launch may be a comms or discovery problem, not a feature problem. +2. **Is engagement strong?** If engagement is below target among adopters, the value is not landing for the right reasons. +3. **Is the metric correctly attributed?** Did another concurrent change interfere with the measurement. +4. **Did the side-effects analysis catch a counterweight?** A negative side effect could be cancelling the positive primary effect. + +Each diagnosis maps to a different fix. + +- Adoption problem: more comms, repeat comms, deeper sales reactivation, in-app discovery surface. +- Engagement problem: usability or value-prop iteration. The feature may need redesign. +- Attribution problem: re-run measurement after the concurrent change has been accounted for. +- Side-effect counterweight: fix the side effect, then re-measure the primary. + +--- + +## When the launch worked but quietly + +Sometimes the launch works at every level (adoption strong, engagement strong, outcome metric moved) but the team does not feel like it succeeded. Usually the gap is internal awareness. + +Signs. + +- Sales is not using the feature in pitches. +- Customer success is not mentioning it in customer calls. +- The product narrative has not updated to include the feature. + +The fix. Internal launch effectiveness is part of the launch playbook. Even successful feature launches need ongoing internal advocacy. + +The discipline. After the four-week checkpoint, briefly re-engage internal stakeholders. Share the metrics. Highlight customer use cases. The internal awareness is not a one-time event at launch; it is sustained for a quarter or more. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md b/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md new file mode 100644 index 0000000..a7e0c83 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md @@ -0,0 +1,185 @@ +# Rollout strategy patterns + +Four rollout patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. + +The principle. The rollout is the mechanism by which users actually encounter the feature. The pattern depends on what would happen if the feature breaks, how confident the team is in correctness, and whether external comms are tied to a specific date. + +--- + +## Pattern 1: all-at-once (big bang) + +**Mechanism.** Zero to 100 percent of eligible users in a single deploy. No gradual rollout. + +**Right for.** + +- Marketing-coordinated launches where the announcement IS the rollout. The press is briefed for a specific date; the feature has to be live for everyone at that moment. +- Low-blast-radius features. The feature affects a small portion of the user experience; even if it breaks, the customer impact is limited. +- High-confidence releases. The feature has been tested thoroughly, used internally, validated with a beta cohort. + +**Risky for.** + +- High-traffic critical paths (checkout, login, primary navigation). Any bug affects a meaningful share of users immediately. +- Features without a clean rollback path. If the deploy breaks, recovery is hard. +- Features with cohort-specific risk (works for free users, breaks for enterprise). The cohort variance is not exposed before launch. + +**Operational shape.** One deploy. Health check after deploy. Rollback path ready but rarely used. Monitoring tightens for 24 hours post-deploy. + +--- + +## Pattern 2: gradual percentage rollout + +**Mechanism.** 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days. Health checks at each step. + +**Right for.** + +- Most feature launches. The default unless there is a reason to deviate. +- Features touching critical paths. The 1 percent rollout catches errors before they affect a meaningful share of users. +- Features with uncertain interaction effects. Other systems may behave differently when the feature is on; gradual rollout surfaces interactions safely. + +**Risky for.** + +- Marketing-coordinated launches with a fixed announcement date. The press writes about a feature that 90 percent of users do not have yet. + +**Operational shape.** + +- 1 percent to 10 percent: 4 to 24 hours. Watch error rates, latency, feature usage rate. +- 10 percent to 25 percent: 24 to 48 hours. Watch the same metrics plus support volume. +- 25 percent to 50 percent: 48 to 72 hours. Watch all metrics plus customer feedback. +- 50 percent to 100 percent: 24 to 72 hours. + +The pace is configurable. Faster for low-risk features; slower for high-risk. + +The rollback at any step. If a metric breaches a threshold, the rollout pauses. If the issue is severe, rollback to 0 percent. If the issue is minor, fix forward at the current percentage. + +--- + +## Pattern 3: flag-gated cohort rollout + +**Mechanism.** Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Specific named accounts first, then broad rollout. + +**Right for.** + +- Features with cohort-specific risk profiles. A pricing change affects existing customers differently from new customers; roll out to new customers first. +- Features that need cohort-specific configuration. Enterprise customers may need a setup step; roll out to them after they are configured. +- Features where the cost of a bad rollout varies by cohort. Bug in front of a Fortune 500 prospect costs more than a bug in front of a free-tier user. + +**Operational shape.** + +- The flag service controls which cohorts have the feature enabled. +- Cohorts are defined explicitly: account tier, account ID list, region, signup date range. +- Each cohort gets its own monitoring slice. Issues affecting one cohort do not pause the rollout to other cohorts. + +**Risky for.** + +- Features that interact across cohorts. If enterprise customers can see what free-tier customers create, a partial cohort rollout exposes a feature inconsistency that breaks workflows. + +--- + +## Pattern 4: phased launch (multi-week) + +**Mechanism.** Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Multi-week timeline. + +**Right for.** + +- Tier 1 launches with high uncertainty about user reception. Pricing changes often launch this way. +- Major UX redesigns. The team needs to learn what users do with the new design before broader rollout. +- Features that depend on user behavior change. The team needs to see whether users adopt before declaring readiness. + +**Operational shape.** + +- Phase 1: limited rollout (5 to 10 percent of eligible users). 1 to 2 weeks. Heavy feedback collection. +- Phase 2: iteration based on phase 1 feedback. Could be days; could be weeks. +- Phase 3: expanded rollout (25 to 50 percent). 1 to 2 weeks. +- Phase 4: general availability. + +The total timeline is 4 to 8 weeks for a typical phased launch. Longer for major UX changes; shorter for feature additions. + +**Risky for.** + +- Features that need to be all-on for users to encounter them naturally. A change to the homepage hero needs to be either visible or not; phased rollout creates inconsistent experiences across users. + +--- + +## The decision framework + +Three factors. Pick the rollout that matches. + +### Factor 1: blast radius + +What happens if the feature breaks for a meaningful share of users? + +- **Low.** Optional new tool that users opt into. Bug affects only users who tried the new tool. +- **Medium.** New surface in an existing flow. Bug affects users mid-flow but not users on other paths. +- **High.** Critical path change. Bug affects most active users immediately. + +### Factor 2: confidence in correctness + +How confident is the team that the feature works. + +- **Low.** First time the team has built this kind of feature. Edge cases unknown. +- **Medium.** The team has built similar features before. Most edge cases anticipated. +- **High.** Iterative refinement of an existing feature. Behavior well-understood. + +### Factor 3: external commitments + +Is the launch date tied to external press, partner coordination, or a public commitment. + +- **None.** Internal team knows the rough timeline; no external coordination. +- **Soft.** Marketing has scheduled comms but the date can shift by a few days. +- **Hard.** Press is briefed for a specific day. Partner is coordinating launches. The date is fixed. + +### The decision matrix + +| Blast radius | Confidence | External commitment | Recommended pattern | +|---|---|---|---| +| Low | High | Hard | All-at-once | +| Low | High | Soft or none | All-at-once or gradual | +| Low | Medium | Any | Gradual | +| Low | Low | Any | Gradual or phased | +| Medium | High | Hard | Gradual fast | +| Medium | High | Soft or none | Gradual | +| Medium | Medium | Any | Gradual | +| Medium | Low | Any | Phased | +| High | High | Any | Gradual slow | +| High | Medium | Any | Gradual or flag-gated | +| High | Low | Any | Phased | + +The defaults. Most launches use gradual percentage rollout. The other patterns are for specific situations. + +--- + +## Cohort-specific rollout sequencing + +When using flag-gated cohort rollout, the sequence matters. + +**Internal users first.** Eat your own dog food. Catch the obvious issues before any external user sees them. + +**Free or trial users next.** Lower-stakes; if the feature has issues, the cost of a bad experience is lower than for paying customers. + +**Self-service paid users.** Customers who use the product without a sales rep. They will encounter the feature naturally; their feedback is high-quality. + +**Top accounts last (with sales-led briefing first).** Top accounts hear about the feature from their account executive before encountering it. By the time they have access, the feature is stable. + +Reverse the sequence in specific cases. + +- A feature designed specifically for enterprise customers should roll out to those customers first; the feedback is the design feedback. +- A feature gated by configuration that only enterprise customers complete should roll out to them first; otherwise the feature is invisible to the cohort that can use it. + +--- + +## What "rollback trigger" means + +A pre-defined rule that determines when the team rolls back without further debate. + +Examples. + +- Error rate above 1 percent sustained for 5 minutes. +- Latency above the pre-launch P95 by 50 percent for 10 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline for any cohort. +- Support tickets mentioning the feature exceed 50 in the first hour. + +The trigger fires automatically; the team executes the rollback without re-litigating whether to do it. + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate. + +The discipline. Define the trigger before launch. Write it down. Rehearse the rollback. Make the trigger automatic where possible (alerting plus on-call paging); make the rollback execution one command, not a multi-step process. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md b/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md new file mode 100644 index 0000000..07b7cca --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md @@ -0,0 +1,173 @@ +# Sales enablement template + +Battlecard, demo script, deal coaching, training session structure. For B2B; skip for B2C and PLG. + +The principle. Sales reps cannot pitch a feature they were briefed on yesterday. Enablement is the structured way to give sales the language and the mechanics they need to talk about the feature accurately and quickly. + +--- + +## When to skip this section + +For B2C products and PLG products without a sales motion, this section does not apply. The user is the buyer; there is no rep in the middle. Skip ahead to the support readiness checklist. + +For B2B products, this section is non-negotiable for Tier 1 launches and most Tier 2 launches. + +--- + +## The battlecard + +One page. Sales can read it in two minutes and pitch the feature in five. + +### Section 1: positioning summary + +Two to three sentences. The user-visible promise plus the target customer profile plus the differentiator vs the status quo. Pulled directly from the positioning canvas. + +### Section 2: target customer profile + +The specifics sales needs to qualify. Industry, company size, role of the buyer, role of the user (often different), use case, current pain. + +### Section 3: top objections and answers + +Three to five expected objections with the answer for each. The answers are written, not improvised; reps should be able to quote them back. + +Example. + +| Objection | Answer | +|---|---| +| "We already have a routing solution that works fine." | "Most solutions are keyword-based. Ours uses ML trained on the customer's actual routing decisions, so it adapts to their specific team structure. Customers report 95 percent accuracy vs 60 to 70 percent on keyword-based systems." | +| "How is this different from what [Competitor] just shipped?" | "Both products do automated routing. The difference: ours retrains weekly on the customer's data; theirs uses a fixed model. Customers with non-standard team structures see materially better routing on our system." | +| "What if the model gets it wrong?" | "Below the configurable confidence threshold, the ticket falls back to manual routing. Manager corrections feed back into the model, so accuracy improves over time." | + +### Section 4: proof points + +The same proof points from the positioning canvas. Three to five concrete capabilities or outcomes. + +### Section 5: deal coaching + +Specific guidance on how this affects deals. + +- **Deals to revisit.** Customers in the pipeline who were blocked by the gap this feature now closes. Names where appropriate. +- **Deals it complicates.** Customers on the existing pricing or feature set who may need migration support. Names where appropriate. +- **Common pricing questions.** What customers ask about cost; the answers reps should give. + +### Section 6: where to learn more + +Links to the demo recording, the full launch brief, the FAQ, the support documentation, and the PM contact for sales questions. + +--- + +## The demo script + +A repeatable demo the rep can run with a customer. + +### Structure + +**Open (1 minute).** State the customer's pain in their language. Reference what they told the rep in discovery (use a generic placeholder if the rep is in a first-call demo). + +**Show the problem (2 minutes).** Demonstrate the status quo workflow that the feature replaces. The rep walks through the manual process, naming the friction points. + +**Show the feature (5 minutes).** Walk through the feature solving the same workflow. Highlight the proof points. Pause at the moments where the customer would feel the difference. + +**Show the safety net (2 minutes).** Walk through the failure mode. What happens when the feature does not work perfectly. The customer needs to trust the safety net before they trust the feature. + +**Close (1 minute).** Summarize the value. Ask the customer what they think. Surface objections. + +**Total.** 11 minutes. Demos longer than 15 minutes lose attention; demos shorter than 7 minutes feel rushed. + +### The recorded demo + +For reps who join after the launch or who want a refresher, a recorded version of the demo. Same structure. Annotated with timestamps. Stored where reps can find it (sales enablement platform, shared drive, internal wiki). + +The recorded demo is not a substitute for the live demo with a customer. It is reference material for the rep. + +--- + +## Deal coaching guide + +Beyond the battlecard's deal-coaching section, a longer-form guide for the top sales scenarios. + +### Scenario 1: deal blocked by missing capability + +The rep has a customer in the pipeline who was blocked by a feature gap that this launch closes. Coaching. + +- Confirm the gap was the actual blocker via discovery questions before pitching the new feature. +- Reference the customer's specific pain in the demo. +- If the deal stalled with a competitor, address the competitor head-on with the differentiator section of the battlecard. +- Time the outreach. Reach out one to three days after public launch comms; the customer will already be aware of the announcement. + +### Scenario 2: existing customer expansion + +The rep has an existing customer using a smaller plan; this launch could justify expansion. Coaching. + +- The customer success team should brief the customer first if the customer is in a top-account tier. +- The rep follows up with an upgrade conversation tied to the specific value the customer gets from the new feature. +- Pricing change documentation if applicable; reps should not improvise pricing. + +### Scenario 3: defensive against churn + +The rep has a customer at risk of churning to a competitor whose product had the feature this launch adds. Coaching. + +- The customer success team should flag the at-risk customer; the rep delivers the briefing in coordination. +- Acknowledge the gap that existed; explain the timeline of the launch; show the feature. +- Offer migration support if the customer was already starting to evaluate the competitor. + +### Scenario 4: net-new pipeline + +The rep is targeting net-new prospects for whom the launch is a relevant capability. Coaching. + +- Lead with the launch as the recent product update; reference the blog post or release. +- Tie the feature to the buyer's expected pain. +- The launch announcement is the conversation starter; the demo is the conversion. + +--- + +## The training session + +Live, 30 minutes, with Q&A. Recorded for reps who cannot attend. + +### Structure + +**0 to 5 minutes.** PM walks through the positioning canvas. Target user, problem, promise, proof points, anti-positioning. + +**5 to 15 minutes.** PM (or sales-engineering partner) demos the feature using the demo script. Reps see what the rep version of the demo looks like. + +**15 to 25 minutes.** Q&A. Reps ask the questions they expect customers to ask. The answers feed back into the FAQ. + +**25 to 30 minutes.** Coaching on top deal scenarios. Brief discussion of which named accounts in the pipeline are affected. + +### After the session + +- Recording posted to the sales enablement platform. +- Q&A captured in the launch brief's FAQ section. +- Battlecard finalized with any new objections that surfaced. +- Demo script updated with any clarifications from the live demo. + +--- + +## What to skip + +Do not. + +- Hand sales a 12-page document and call it enablement. +- Train sales the morning of public launch. +- Skip the recorded demo because "we can do it live." +- Assume sales will read the launch brief before the customer call. + +The discipline. Sales enablement is short, opinionated, and rehearsed. Reps internalize it once and pitch the feature naturally for the rest of the launch period. + +--- + +## The "shadow launch" failure + +The pattern. + +- Feature ships. +- Sales hears about it from product team Slack. +- No battlecard. +- No demo recording. +- Sales reps either ignore the feature in customer conversations (because they cannot pitch it) or misrepresent it (because they are improvising). +- Customers churn or escalate when the feature does not match what they were told. + +The cost. Engineering investment is captured at zero or negative value. The next product team launch is met with sales skepticism. + +The fix. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. The battlecard takes a half day to write. The training session takes 30 minutes. The recorded demo takes an hour. The investment is small relative to the engineering investment behind the feature. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md new file mode 100644 index 0000000..50f031c --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md @@ -0,0 +1,137 @@ +# Support readiness checklist + +Training, FAQ, escalation paths, monitoring access. The pattern of training support before customer-facing launch comms. + +The principle. Support is the first to encounter the failure modes of a new feature. They need the same context as sales but oriented toward post-purchase questions and incident resolution. + +--- + +## The four deliverables + +### 1. Training + +Live or recorded, with Q&A. + +The same content as the sales training, adapted for support workflows. Differences. + +- Sales pitches the feature; support solves problems with it. The training emphasizes how to diagnose customer issues, not how to position the feature. +- Sales sees the happy path; support sees the failure modes. The training includes the FAQ of expected support tickets and the escalation paths for unexpected ones. +- Sales has a 30-minute training; support often has 60 minutes because the breadth of expected questions is larger. + +Schedule. Support training one week before customer-facing launch comms. Recorded for reps who cannot attend live. + +### 2. FAQ document + +The questions that support expects customers to ask, with the answers. + +Categories. + +- **What does the feature do.** The basic explanation. Same content as the user-visible promise plus a short "how it works" paragraph. +- **How do I turn it on.** Configuration steps. Permissions required. Plan tier required. +- **What are the limits.** Rate limits, size limits, supported regions, supported plans. +- **What if it does not work.** Troubleshooting steps. When to escalate. +- **How do I turn it off.** For users who tried it and want to revert. Often forgotten until the first customer asks. +- **Pricing or billing questions.** If the feature affects billing, support needs the answer. + +The FAQ updates daily during the first week of launch as new questions surface. Support reps add questions they encountered to the FAQ; the PM reviews and approves daily. + +### 3. Escalation path + +When support cannot answer a question or solve an issue, who do they escalate to and how fast. + +The escalation contract. + +- **Tier 1 (in-product issue).** Support resolves with the customer using the FAQ and product knowledge. Target response: under 1 hour during business hours. +- **Tier 2 (product question support cannot answer).** Escalate to the PM. Target response from PM: same day during business hours. +- **Tier 3 (product is broken for the customer).** Escalate to engineering on-call. Target response from engineering: under 2 hours regardless of hours during launch week. + +For Tier 1 launches, the on-call rotation should include a launch-week PM contact in addition to the regular engineering on-call. + +### 4. Monitoring access + +Support reps should be able to verify whether a customer's issue is feature-specific. + +The minimum. + +- A dashboard showing feature health (overall error rate, feature-specific error rate, rollout percentage). +- A way to look up whether a specific customer is in the rollout cohort. (For flag-gated rollouts; some customers will not have access to the feature on launch day, and support needs to be able to confirm that.) +- A way to look up the customer's recent feature usage (or the lack thereof). + +Without monitoring access, support reps escalate every feature-related ticket to engineering or the PM. The escalation queue gets noisy; real Tier 3 issues get drowned in Tier 2 questions. + +--- + +## The training-before-comms rule + +The discipline. Support training happens before customer-facing comms launch. + +The reason. Customers will start asking support about the feature within minutes of the public announcement. Support needs to be ready before customers ask, not while customers are asking. + +The pattern. + +- Day T minus 7: support training delivered. FAQ published internally. Escalation paths confirmed. +- Day T minus 1: support team huddle. Last-minute questions. FAQ refresh. +- Day T (launch day): support staffed for elevated volume. PM and engineering on-call paths confirmed open. + +The "training day-of" failure. Support is trained the morning of public launch. By the afternoon, they have already encountered three customer questions they cannot answer well. The support team's confidence with the feature degrades; customers feel the rep does not know the product. Trust loss. + +--- + +## The "support is overwhelmed" failure + +The setup. The launch generates more support volume than the team expected. The feature is novel; customers ask many basic questions; the FAQ does not anticipate the actual questions; support reps escalate everything to the PM. + +The signs. + +- Support ticket queue length doubles or triples on launch day vs the prior week. +- Tickets tagged with the feature exceed the support team's capacity for new conversations. +- The PM's Slack is full of support questions that should have FAQ answers. + +The fix. + +- Pre-launch: estimate support volume. Look at ticket volume from prior comparable launches; double the estimate. +- Pre-launch: staff support for the launch window. Pull in cross-functional help if needed. +- Pre-launch: write the FAQ deeper than feels necessary. Most launches have 20 to 30 expected questions; document them all in advance. +- Launch day: PM is available for FAQ updates throughout the day. New questions get answers within an hour and propagate to support. + +--- + +## What support needs that sales does not + +Two specific differences. + +**Failure modes documentation.** Support needs to know what happens when the feature breaks. The error messages users see, the recovery flows, the limitations. Sales does not need this depth; support requires it. + +**Customer-facing language for limits.** Sales pitches the feature and addresses the limits at the negotiation stage. Support encounters the limits the moment a customer hits them. Support reps need pre-written language for "the feature supports up to X; for higher volumes, contact your account manager." + +Without these two, support is improvising at the moment of customer pain. Improvisation produces inconsistent answers across reps; customers compare notes and lose trust. + +--- + +## The post-launch FAQ refresh cycle + +For two to four weeks post-launch, the FAQ refreshes daily. + +- Support reps log new questions they encountered, with the answers they gave. +- PM reviews daily, approves or corrects answers, adds them to the canonical FAQ. +- Support team gets a daily summary of new FAQ entries. + +After two to four weeks, the FAQ stabilizes. The refresh moves to weekly, then monthly. + +The cost of the daily refresh is small. The benefit is that support builds confidence with the feature in the first month, instead of struggling for the first quarter. + +--- + +## When support flags an issue larger than a question + +Sometimes the support volume on a feature reveals a real problem with the feature, not just a need for better FAQ. + +Signs. + +- Many customers ask the same question, and the answer is "the feature does not do that." The customers expected something the feature does not deliver. Positioning was misaligned. +- Many customers report the same bug. The bug is real and affects a meaningful share of users. +- Support tickets cluster on a specific cohort (e.g., users on a specific plan, in a specific region). The feature does not work correctly for that cohort. + +The pattern. Support is the early-warning system for launch quality. The PM should review the support ticket digest daily during the first week and at least weekly thereafter. If the support volume reveals a feature problem, the launch may need to pause for a fix before further rollout. + +The discipline of treating support as a quality signal is the cheapest way to catch launch problems before they show up in revenue or churn metrics. diff --git a/dist/pi/.agents/skills/form-strategy/SKILL.md b/dist/pi/.agents/skills/form-strategy/SKILL.md new file mode 100644 index 0000000..75b63cb --- /dev/null +++ b/dist/pi/.agents/skills/form-strategy/SKILL.md @@ -0,0 +1,257 @@ +--- +name: form-strategy +description: "Design forms that convert, validate well, resist spam, and integrate cleanly with downstream systems. Use this skill when designing or auditing any form (contact, signup, checkout, multi-step, embedded), planning validation logic, fighting spam, choosing form tooling, or improving form conversion. Triggers on form design, form validation, form conversion, multi-step form, form spam, captcha, honeypot, form abandonment, signup form, contact form. Also triggers when form completion rates are low or spam is overwhelming." +category: cross-cutting +catalog_summary: "Form design, validation patterns, spam prevention, conversion tuning" +display_order: 1 +--- + +# Form Strategy + +Forms are where intent becomes action. Design them well or lose conversions, frustrate users, and drown in spam. Stack-agnostic. + +--- + +## When to use + +- Designing or redesigning a form +- Conversion is dropping on a key form +- Spam volume is overwhelming the inbox or database +- Auditing forms across a site +- Planning validation logic +- Choosing form tooling (form service, custom build, no-code) +- Integrating forms with CRM, email, or other downstream systems +- Multi-step form decisions + +## When NOT to use + +- Generic conversion optimization (use `cro-optimization`) +- The copy on the form (use `landing-page-copy`) +- Backend handling beyond form-specific concerns (use `frontend-component-build`, `code-review-web`) +- General accessibility (use `accessibility-audit`) + +--- + +## Required inputs + +- The form's purpose (what action, what outcome) +- Current form (URL, screenshot, or fields) +- Current performance (completion rate, spam rate, conversion to next step) +- Downstream system (where submissions go: CRM, email, database, support tool) +- Business context (volume, urgency of leads, cost of false vs missed signups) + +--- + +## The framework: 5 dimensions + +Every form decision falls into one of these dimensions. + +### Dimension 1: Field strategy + +The biggest lever. Every additional field reduces conversion. + +**Questions to ask for each field:** +- Is this required to deliver value to the user? +- Is this required to deliver value to the business? +- Can it be inferred from another source (email domain, behavior, context)? +- Can it be asked later (after first contact, on second visit, on settings page)? + +**Default rule:** ask for the minimum to make the next step happen. Everything else later. + +For a B2B contact form: name and email get you started. Phone, company size, role are nice-to-haves that often hurt conversion more than they help qualification. + +For a checkout: country, postal code, address, name, payment. Anything else (referral source, marketing opt-in, account creation) is optional or moved to post-purchase. + +### Dimension 2: Field design + +How each field looks and behaves. + +- **Labels above inputs** beat placeholders. Placeholder labels disappear when typing. +- **Inline labels** (floating labels) work for very compact forms. +- **Single column** for almost every form. Eyes flow vertically. +- **Logical grouping** with visible spacing. Don't put unrelated fields next to each other. +- **Right input type:** `email` for emails, `tel` for phone, `number` for numbers, `date` for dates. Mobile keyboards adapt. +- **Autocomplete attributes:** `autocomplete="email"`, `autocomplete="given-name"`, etc. Browsers and password managers fill them in. +- **Sensible defaults** for fields where one applies (country pre-selected by IP, etc.). Don't default to anything that would mislead if wrong. + +### Dimension 3: Validation + +Tell users what's wrong, when, and how to fix it. + +- **Validate on blur, not on every keystroke.** Inline errors that appear as someone types are jarring. +- **Re-validate on submit** (catch fields the user skipped). +- **Specific messages:** "Email must include @" beats "Invalid email." +- **Position errors next to the field** they refer to. +- **Don't submit a form when there are errors.** Highlight the first errored field. Scroll to it. +- **Validate server-side too.** Client validation is UX. Server validation is correctness. + +For format-flexible fields (phone numbers, postal codes), validate liberally. Reject only what's clearly wrong, not what's "non-standard." Many phone formats exist. + +### Dimension 4: Spam defense + +Public forms attract spam. Plan for it from day one. + +**Layered defense:** + +1. **Honeypot field.** A hidden field that humans don't fill in but bots do. If it's filled, reject silently. Free, low-friction, surprisingly effective for low-effort spam. +2. **Time-based detection.** Reject submissions completed in under 2-3 seconds (bots) or after very long delays (suspicious sessions). +3. **Rate limiting.** Reject if the same IP submits too many times. +4. **CAPTCHA as a last resort.** Modern invisible CAPTCHAs (hCaptcha, reCAPTCHA v3, Turnstile) are low-friction. Old image CAPTCHAs are conversion-killers. +5. **Behavioral signals.** Did the cursor move? Was there scroll? Modern services track this. +6. **Content filtering.** Reject obvious spam content (links, foreign-language content if your audience is local, common spam words). +7. **Server-side review.** A queue rather than direct delivery to inboxes for high-spam-target forms. + +For most contact forms: honeypot + time check + Turnstile (or similar) is sufficient. + +### Dimension 5: Submission flow + +What happens after submit. + +- **Inline success message** for short forms. Don't redirect just to confirm. +- **Confirmation page** for high-value submissions (to provide next steps, set expectations). +- **Email confirmation** for signups, purchases, RSVPs. Always. +- **Save data on errors** so the user doesn't re-enter everything. +- **Optimistic UI** (show success before the server confirms) for low-stakes forms; risky for high-stakes. + +For multi-step forms: +- Show progress (3 of 5) +- Save state between steps (in case of refresh or navigation) +- Allow back navigation without losing data +- Validate per step, not just at the end + +--- + +## Workflow + +### Step 1: Audit current state + +For each form on the site: +- What's its purpose? +- Number of fields, required vs optional +- Current completion rate +- Current spam rate +- Validation rules +- What happens after submit +- Where the data goes downstream + +### Step 2: Define success per form + +Different forms have different success metrics: +- Lead form: qualified leads (defined by sales) +- Newsletter: confirmed subscriptions (after double opt-in) +- Contact: substantive replies (not just submissions) +- Checkout: successful payments + +Track the metric that matters, not just submissions. + +### Step 3: Cut fields ruthlessly + +Apply the field strategy filter. For each field, answer: +- Required to deliver value? Keep. +- Nice to have? Move to optional or later. +- Used for routing or qualification? Often can be inferred. + +A 7-field form becomes a 3-field form. Conversion rises. + +### Step 4: Set up spam defense + +Before launching a public form: +- Add a honeypot field +- Add time-based detection +- Add rate limiting +- Add a modern CAPTCHA if the form is high-traffic or high-spam + +After launch, monitor. Tune layers based on what's actually getting through. + +### Step 5: Improve validation + +Walk through each field: +- Is validation specific? +- Does it run at the right time (blur or submit, not on keystroke)? +- Are error messages actionable? +- Is server-side validation matching client-side? + +### Step 6: Verify accessibility + +Critical baseline: +- Every input has an associated label (visually visible or `aria-label`) +- Errors are associated with inputs (`aria-describedby`, `aria-invalid`) +- Focus order matches visual order +- Color isn't the only way to indicate errors +- Form is fully keyboard-navigable + +See `accessibility-audit` for the full WCAG audit. + +### Step 7: Test downstream + +Submit the form. Verify: +- Data lands where it should +- Required fields are populated correctly +- Spam defenses are working (test with a script) +- The user gets the confirmation they expect +- Internal notification is timely + +Forms break silently when downstream systems change. Test after any integration update. + +### Step 8: Monitor + +- Completion rate over time +- Spam rate over time +- Errors per submission (high errors = bad UX) +- Drop-off field (where do people abandon?) + +--- + +## Failure patterns + +**Too many fields.** Most B2B contact forms have 3x more fields than they need. Cut. + +**Validation that fires while typing.** Annoying. Causes errors before the user has finished. + +**Generic error messages.** "Invalid input." Where? Why? Be specific. + +**Required fields not marked.** Users discover they're required only after submission fails. Mark required (or, for short forms, mark optional). + +**Autocomplete disabled.** "For security." It's almost never a security improvement and always a UX cost. Leave autocomplete on. + +**Tab order is broken.** Tab key skips fields or jumps backward. Set `tabindex` only when necessary; use natural DOM order. + +**Submit button below the fold.** Especially on mobile. Users don't see it. + +**No save on error.** User submits, has one error, returns to the form, all fields empty. Nightmare. Save the state. + +**Captcha as the only spam defense.** Captchas are friction. Layered defense beats brute-force friction. + +**Captcha visible by default.** Modern CAPTCHAs (Turnstile, reCAPTCHA v3) are invisible most of the time and only escalate when needed. Use those. + +**Newsletter signup that's actually a marketing list.** Honor opt-in scope. If the user signed up for product updates, don't add them to the marketing newsletter. + +**Confirmation page that's a dead end.** "Thanks for submitting" with no next step. What now? Provide an action (read related content, return to homepage, follow on social). + +**No double opt-in for marketing email.** Bots and typos pollute the list. See `email-deliverability` for why this matters. + +**Email field accepting `name@` as valid.** Browser spec validation is loose. Validate against an actual format. + +**Custom date pickers worse than native.** The native `<input type="date">` is now good on most platforms. Don't reinvent unless you have a specific reason. + +**Forms that lose state on refresh.** For long forms, save to localStorage and restore on load. + +--- + +## Output format + +A form audit document includes: + +- **Form inventory:** every form on the site +- **Per-form review:** purpose, fields, performance +- **Recommendations:** field cuts, validation improvements, spam defense, design changes +- **Spam defense plan:** layers per form +- **Accessibility status:** WCAG compliance per form +- **Downstream integration map:** where each form's data goes +- **Monitoring plan:** what's tracked + +--- + +## Reference files + +- [`references/form-anatomy-checklist.md`](references/form-anatomy-checklist.md): A field-by-field, behavior-by-behavior checklist for auditing or designing a form, covering structure, accessibility, validation, and spam defense. diff --git a/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md b/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md new file mode 100644 index 0000000..14f651f --- /dev/null +++ b/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md @@ -0,0 +1,243 @@ +# Form Anatomy Checklist + +A field-by-field, behavior-by-behavior checklist for auditing or designing a form. Walk through it for any form before shipping. + +--- + +## Overall structure + +- [ ] **Purpose is clear** from headline, subheadline, or surrounding context +- [ ] **Single column** layout (multi-column forms are slower to scan and complete) +- [ ] **Form is reasonably short** (cut fields you don't strictly need) +- [ ] **Required vs optional** is clear (mark one or the other based on which is shorter) +- [ ] **Logical grouping** of related fields with visible spacing +- [ ] **Submit button** is visible without scrolling on common viewports +- [ ] **Submit button text** is specific to the action ("Get the report" beats "Submit") + +--- + +## Per-field checklist + +For each field, verify: + +### Label + +- [ ] Has a visible label (or, for compact forms, a clearly associated visible cue) +- [ ] Label is **above** the input (preferred) or floats (acceptable for compact) +- [ ] Label is descriptive (not just the field name from the database) +- [ ] Label is associated with the input via `for=` and `id=` or a wrapping `<label>` + +### Input type + +- [ ] Uses semantic input type: + - `email` for emails + - `tel` for phone + - `number` for numeric (when not formatted, like a count or amount) + - `date` for dates + - `url` for URLs + - `text` for general +- [ ] Native input where possible (date, color, range) before custom widgets +- [ ] `inputmode` attribute set when it differs from type (e.g., `inputmode="decimal"` on a price) + +### Autocomplete + +- [ ] `autocomplete=` attribute set with the appropriate value + - `name`, `given-name`, `family-name` + - `email` + - `tel` + - `street-address`, `address-line1`, `postal-code`, `country` + - `cc-name`, `cc-number`, `cc-exp`, `cc-csc` + - `current-password`, `new-password` +- [ ] Doesn't disable autocomplete without good reason + +### Validation + +- [ ] Validates on blur, not on every keystroke +- [ ] Validates again on submit (in case fields were skipped) +- [ ] Error message is specific ("Email must include @" not "Invalid") +- [ ] Error message appears next to the field +- [ ] Error state is visually distinct (not just color; also icon or pattern) +- [ ] `aria-invalid="true"` on errored fields +- [ ] `aria-describedby` linking the field to its error message + +### Server-side validation + +- [ ] Server validates everything client validates (client validation is UX, server is correctness) +- [ ] Server validates fields the client can't (uniqueness, business rules, etc.) +- [ ] Server returns specific error messages +- [ ] Server is the source of truth for "save" + +### Hint text + +- [ ] If a field needs explanation, hint text is below the field (not in placeholder) +- [ ] Hint text uses `aria-describedby` to associate with the input +- [ ] Hint text doesn't contain critical info that would be missed if not read + +### Required vs optional + +- [ ] Marked clearly (consistently use either "required" markers or "optional" markers, not both) +- [ ] `required` attribute set on truly required fields +- [ ] Required fields announced to assistive tech (the `required` attribute does this) +- [ ] Field has a fallback if accidentally skipped (server validation catches it gracefully) + +### Width + +- [ ] Field width matches expected input length (don't make a postal code field as wide as a name field) +- [ ] Mobile field width is full-width minus reasonable margins + +### Specific field types + +**Password:** +- [ ] `autocomplete="current-password"` for login, `"new-password"` for signup +- [ ] Toggle to show password (not in lieu of, but in addition to, dots) +- [ ] Length and complexity hints visible before typing +- [ ] Allow long passphrases (no max length under 64+ chars) + +**Email:** +- [ ] `type="email"` and `autocomplete="email"` +- [ ] Server validates format more strictly than the browser default +- [ ] Confirms for high-stakes use (with a second email field) or relies on confirmation email + +**Phone:** +- [ ] `type="tel"` and `autocomplete="tel"` +- [ ] Liberal validation (accept various formats) +- [ ] Country code handling if international + +**Date:** +- [ ] `type="date"` for native picker, or a well-tested custom picker +- [ ] Timezone handling thought through (server side) + +**Address:** +- [ ] Multiple fields (line 1, line 2, city, region, postal code, country) +- [ ] `autocomplete` on each +- [ ] Validation by country (US ZIP differs from UK postcode) +- [ ] Optional autocomplete via address API for high-conversion forms + +**File upload:** +- [ ] Accepted types declared with `accept=` +- [ ] Size limit communicated and enforced (client and server) +- [ ] Drag-and-drop and click-to-browse both work +- [ ] Selected file feedback (name, size, preview if image) +- [ ] Progress indicator for slow uploads +- [ ] Server scans uploads if user-generated content goes public + +**Select / dropdown:** +- [ ] Native `<select>` for short lists (under ~15 options) +- [ ] Custom searchable component for long lists +- [ ] Default option that's not selectable (e.g., "Select a country") +- [ ] Sort by likelihood (popular options first), or alphabetical, not random + +**Radio buttons:** +- [ ] Use for 2-7 mutually exclusive options +- [ ] All options visible (no scrolling) +- [ ] One option pre-selected only if a sensible default exists + +**Checkboxes:** +- [ ] Use for boolean choices and multi-select +- [ ] Label is clickable (associated with checkbox) +- [ ] Marketing opt-ins are off by default (legal requirement in many regions) +- [ ] Terms-of-service is unchecked by default (active acceptance) + +**Multi-step forms:** +- [ ] Progress indicator (3 of 5) +- [ ] State saved between steps (refresh-resilient) +- [ ] Back navigation doesn't lose data +- [ ] Validation per step +- [ ] Final review step before submit (high-stakes only) + +--- + +## Spam defense + +- [ ] Honeypot field (hidden, must remain empty) +- [ ] Time-based detection (reject very fast or very slow submissions) +- [ ] Rate limiting per IP / per session +- [ ] Modern CAPTCHA (Turnstile, hCaptcha invisible, reCAPTCHA v3) if needed +- [ ] Server-side spam content filtering for high-volume forms +- [ ] Logging of rejected submissions for tuning + +--- + +## Accessibility + +- [ ] Form is fully keyboard-navigable (Tab, Shift+Tab, Enter to submit) +- [ ] Tab order matches visual order +- [ ] Focus is visible (don't remove the focus outline) +- [ ] Form errors are announced to screen readers +- [ ] Color contrast meets WCAG (4.5:1 for text, 3:1 for UI) +- [ ] Errors aren't communicated only by color +- [ ] Form works at 200% zoom +- [ ] Touch targets at least 44px on mobile +- [ ] No time limits without warning and the option to extend + +--- + +## Submission + +- [ ] Submit button is disabled while submission is in flight (prevent double-submit) +- [ ] Loading state on the button or near the form +- [ ] Success state is clear (inline message, redirect to confirmation page, or both) +- [ ] Failure state is clear (specific reason, what to do, support contact) +- [ ] State preserved on submission failure (user doesn't lose data) +- [ ] Email confirmation sent for signups, purchases, RSVPs +- [ ] Internal notification (if applicable) is timely + +--- + +## Privacy and compliance + +- [ ] Privacy notice or link visible near the form +- [ ] Terms of service link if relevant +- [ ] Marketing consent (where required by jurisdiction) is explicit and unchecked by default +- [ ] Data sent over HTTPS only +- [ ] Sensitive fields (passwords, payment) not autofilled by URL params (don't appear in browser history) + +--- + +## Performance + +- [ ] Form loads quickly (lazy-load any heavy assets like CAPTCHAs until needed) +- [ ] Submit handler doesn't block the UI +- [ ] No unnecessary fetches on field interaction +- [ ] CAPTCHA loads asynchronously + +--- + +## Monitoring + +- [ ] Completion rate tracked +- [ ] Field-level drop-off tracked (where do people abandon?) +- [ ] Errors tracked (which fields cause the most errors?) +- [ ] Spam rate tracked (compare layers of defense over time) +- [ ] Submission failures tracked (server errors, integration failures) + +--- + +## Pre-launch test + +Before publishing a form publicly: + +- [ ] Submit successfully with valid data +- [ ] Submit unsuccessfully with bad data (verify error UX) +- [ ] Submit with no data (verify required-field UX) +- [ ] Submit with the honeypot filled (verify silent rejection) +- [ ] Submit very fast (verify time-based rejection) +- [ ] Submit on mobile (verify mobile UX) +- [ ] Submit with keyboard only (verify accessibility) +- [ ] Submit with a screen reader (verify announcements) +- [ ] Submit with autocomplete enabled (verify it works) +- [ ] Verify data lands in the correct downstream system +- [ ] Verify confirmation email arrives (if applicable) +- [ ] Verify internal notification arrives (if applicable) +- [ ] Try to submit duplicate (verify deduplication if applicable) + +--- + +## Post-launch review (after first week) + +- [ ] Completion rate vs target +- [ ] Spam rate (tune defense if needed) +- [ ] Errors (most common errors? could be UX problems) +- [ ] Drop-off (which field loses people?) +- [ ] Downstream system happy? (CRM data clean, no broken integrations) +- [ ] Customer reports (anyone reporting a broken form?) diff --git a/dist/pi/.agents/skills/frontend-component-build/SKILL.md b/dist/pi/.agents/skills/frontend-component-build/SKILL.md new file mode 100644 index 0000000..fb5f5f7 --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/SKILL.md @@ -0,0 +1,184 @@ +--- +name: frontend-component-build +description: "Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with proper states and accessibility. Triggers on build a component, create a button, create a modal, create a form input, component API, props design, component states, refactor component, accessible component. Also triggers when implementing UI from a design that needs to be reusable." +category: development +catalog_summary: "Component architecture, props design, accessibility from the start" +display_order: 2 +--- + +# Frontend Component Build + +Build production-ready components. Stack-agnostic principles. Most patterns translate to React, Vue, Svelte, or vanilla web components. + +This skill is about implementing a component well. For broader system design see `design-system`. For day-to-day visual decisions see `design-standards`. + +--- + +## When to use + +- Building a new component from scratch +- Refactoring an existing component +- Designing a component API (props, slots, events) +- Adding accessibility to an existing component +- Implementing a component from a design + +## When NOT to use + +- Building a full design system (use `design-system`) +- Page-level design decisions (use `design-standards`) +- Backend or data work (use `code-review-web`) +- Performance-only optimization (use `performance-optimization`) + +--- + +## Required inputs + +- The component's purpose (what UI need it serves) +- The design (or willingness to design it) +- The framework or technical context +- The states the component must support +- Accessibility requirements + +--- + +## The framework: 6 dimensions + +A complete component handles six dimensions. Skip any one and the component is incomplete. + +### 1. Anatomy + +Identify the parts that make up the component before writing any markup. + +**Common anatomies:** +- Button: container + label + (optional) icon + (optional) loading indicator +- Modal: backdrop + container + header + body + footer + close affordance +- Form input: label + input + (optional) help text + (optional) error message +- Card: container + (optional) header + body + (optional) footer + (optional) media + +Naming the parts up front makes the API obvious. + +### 2. Variants + +What variations does the component support? + +- **Visual variants** (primary, secondary, ghost, danger) +- **Size variants** (small, medium, large) +- **Functional variants** (with icon, without icon, icon-only) + +Variants should be a managed set, not a free-for-all. Document the supported set; reject requests for new variants without a real use case. + +### 3. States + +What states must the component handle? + +- **Default** +- **Hover** (when pointer is supported) +- **Focus** (always - keyboard navigation requires it) +- **Active / pressed** +- **Disabled** +- **Loading** (where applicable) +- **Error** (for inputs, forms, validation-bound components) +- **Empty** (for components that display data) + +Every state needs visual treatment AND accessibility treatment. + +### 4. Props / API + +Design the component's contract. + +**API design principles:** + +- **Required props minimal.** What's truly needed every time? That's required. Everything else has a sensible default. +- **Boolean props are red flags.** Three booleans means seven combinations. Prefer enum strings: `variant: "primary" | "secondary" | "ghost"` over `primary={true} ghost={false}`. +- **Children > props.** Where content is content, accept children. Don't invent `headerText` and `bodyText` props when slots work. +- **Composition > configuration.** A component that does 5 things via 12 props often should be 5 smaller components. +- **Type the props.** TypeScript or PropTypes or JSDoc. The type is documentation that won't go out of date. + +### 5. Accessibility + +Build it accessible from the start. Adding accessibility later is 5x harder. + +**Universal:** +- Semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<form>`, etc.) over generic `<div>` +- Keyboard navigable (Tab, Shift+Tab, Enter/Space for buttons) +- Focus visible +- Tap targets minimum 44 by 44 pixels +- ARIA only where semantic HTML is insufficient + +**Component-specific:** + +- **Button:** use `<button>`. Don't fake one with a `<div>`. +- **Modal:** focus trap, ESC to close, returns focus to trigger on close, `role="dialog"` and `aria-labelledby`. +- **Form input:** label associated via `for`/`id` or `aria-labelledby`. Error messages linked via `aria-describedby`. `aria-invalid` when in error state. +- **Toggles:** `<button>` with `aria-pressed` for two-state, or `role="switch"` for on/off. +- **Tabs:** `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected` and arrow-key navigation. +- **Tooltips and popovers:** triggered by focus AND hover. Dismissible with ESC. +- **Loading states:** announce with `aria-live` so screen readers know something changed. + +### 6. Tests + +Verify the component works before declaring it done. + +**Test types by priority:** + +1. **Visual regression.** Renders correctly across variants and states. (Storybook + visual diff tools, or manual screenshots.) +2. **Accessibility.** Passes axe or equivalent automated checks. +3. **Keyboard navigation.** Tab, Enter, Escape, arrow keys all work as expected. +4. **Component logic.** Props produce expected output. Events fire correctly. (Unit tests.) +5. **Integration.** Component works inside its expected parent contexts. + +A component without at least automated accessibility testing is not done. + +--- + +## Workflow + +1. **Understand the use case.** What UI need does this component serve? Where will it appear? Adjacent components? +2. **Sketch the anatomy.** Name the parts. +3. **List variants and states.** Match the design system or define new ones if needed. +4. **Design the API.** Required props, optional props, children, events. Type it. +5. **Build the markup with semantic HTML.** Choose the right elements. Avoid generic `<div>` for interactive things. +6. **Style with tokens.** No hardcoded colors, spacing, or sizes. +7. **Add interaction.** Focus management, keyboard handlers, ARIA. +8. **Add states.** Hover, focus, active, disabled, loading, error. +9. **Test.** Automated accessibility, keyboard navigation, visual regression. +10. **Document.** Usage, API, examples, anti-patterns. + +--- + +## Failure patterns + +- **Building with `<div onClick>`.** Loses keyboard accessibility, screen reader semantics, and focus. Use `<button>` or `<a>`. +- **Hardcoding colors and sizes.** Tokens exist for a reason. Hardcoded values resist theming and consistency. +- **Boolean prop explosion.** `<Button primary large rounded fullWidth disabled icon />`. Too many booleans means you actually need fewer variants designed more thoughtfully. +- **Forgetting focus states.** Hover gets attention; focus gets neglected. Keyboard users see invisible buttons. +- **Skipping disabled-state thought.** A disabled button should look obviously disabled AND be `aria-disabled` AND not respond to clicks. +- **Inventing ARIA.** ARIA roles and properties have specific behaviors. Made-up ARIA is worse than no ARIA. Use semantic HTML first. +- **Loading state that doesn't announce.** Screen readers don't know the spinner appeared. Use `aria-live="polite"` or `role="status"`. +- **Tooltip-only critical content.** Hover-only content is invisible to keyboard and touch users. Critical content goes in the visible UI. +- **Component without docs.** Future-you, your teammate, or the next maintainer cannot use what they cannot understand. + +--- + +## Output format + +A complete component delivery includes: + +- **Component code** (in the appropriate framework) +- **Storybook (or equivalent) entry** showing all variants and states +- **Documentation:** + - Anatomy diagram or description + - Props/API table + - Usage examples (basic, advanced, edge cases) + - When to use vs. when to use an alternative + - Anti-patterns (what to avoid) + - Accessibility notes +- **Tests** (visual regression + accessibility + logic) + +--- + +## Reference files + +- [`references/component-spec-template.md`](references/component-spec-template.md) - Template for documenting a component (props, states, accessibility, edge cases) before building. +- [`references/component-api-patterns.md`](references/component-api-patterns.md) - Common patterns for designing flexible component APIs (compound components, controlled vs uncontrolled, polymorphic `as` prop, render props, slots). +- [`references/accessibility-patterns.md`](references/accessibility-patterns.md) - ARIA patterns for common interactive components. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md b/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md new file mode 100644 index 0000000..d32ab58 --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md @@ -0,0 +1,354 @@ +# Accessibility Patterns + +ARIA patterns for common interactive components. Each follows the WAI-ARIA Authoring Practices guidelines. + +When in doubt, use semantic HTML. Reach for ARIA only when semantic HTML cannot express what's needed. + +--- + +## Button + +```html +<button type="button"> + Click me +</button> +``` + +That's it. Don't reinvent it. + +**For buttons that toggle a state:** +```html +<button type="button" aria-pressed="false"> + Bookmark +</button> +``` +Toggle `aria-pressed` between `"true"` and `"false"` on click. + +**For buttons that disclose content:** +```html +<button type="button" aria-expanded="false" aria-controls="menu-1"> + Menu +</button> +<ul id="menu-1" hidden>...</ul> +``` +Toggle `aria-expanded` and `hidden` together. + +**Anti-patterns:** +- `<div onClick>` instead of `<button>` +- Buttons that look like buttons but use `<a href="#">` +- Missing `type="button"` (defaults to `type="submit"` inside forms, causing accidental submits) + +--- + +## Link + +```html +<a href="/destination"> + Link text +</a> +``` + +**For external links opening in new tab:** +```html +<a href="https://external.com" target="_blank" rel="noopener noreferrer"> + External site +</a> +``` + +**Anti-patterns:** +- `<a>` without `href` (breaks keyboard navigation; use `<button>` instead) +- `<a href="#">` for buttons (causes URL pollution and unexpected behavior) +- Generic link text ("click here," "read more") + +--- + +## Form input with label + +```html +<div> + <label for="email">Email address</label> + <input id="email" type="email" name="email" required /> + <p id="email-help">We'll never share your email.</p> +</div> +``` + +**With help text linked:** +```html +<input id="email" type="email" aria-describedby="email-help" /> +<p id="email-help">We'll never share your email.</p> +``` + +**With error state:** +```html +<input + id="email" + type="email" + aria-invalid="true" + aria-describedby="email-error" +/> +<p id="email-error" role="alert">Please enter a valid email.</p> +``` + +**Anti-patterns:** +- Placeholder as label (placeholder disappears on input, leaving field unlabeled) +- Label not associated (visual proximity isn't enough) +- Error indicated by color only (color-blind users miss it) + +--- + +## Modal / dialog + +```html +<div + role="dialog" + aria-modal="true" + aria-labelledby="dialog-title" + aria-describedby="dialog-description" +> + <h2 id="dialog-title">Confirm action</h2> + <p id="dialog-description">Are you sure you want to delete this?</p> + <button type="button" data-close>Cancel</button> + <button type="button" data-confirm>Delete</button> +</div> +``` + +**Behavior requirements:** +- Trap focus inside the modal while open +- Return focus to the trigger element on close +- Close on Escape key +- Close on backdrop click (optional, but expected) +- Background content should be inert (`inert` attribute or `aria-hidden`) +- Body scroll locked while modal is open + +**Anti-patterns:** +- Modal without focus trap (Tab escapes to background page) +- Modal without `aria-modal` and `role="dialog"` +- Modal that doesn't return focus on close +- Background content remains tabbable + +--- + +## Disclosure (accordion section) + +```html +<button + type="button" + aria-expanded="false" + aria-controls="section-1" +> + Section title +</button> +<div id="section-1" hidden> + Section content... +</div> +``` + +For full accordion (multiple disclosures, optionally limit one open at a time), repeat the pattern. + +--- + +## Tabs + +```html +<div role="tablist" aria-label="Settings sections"> + <button + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0" + > + Profile + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1" + > + Notifications + </button> +</div> + +<div role="tabpanel" id="panel-1" aria-labelledby="tab-1"> + Profile content... +</div> +<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden> + Notifications content... +</div> +``` + +**Behavior requirements:** +- Arrow keys navigate between tabs +- Active tab has `aria-selected="true"` and `tabindex="0"` +- Inactive tabs have `aria-selected="false"` and `tabindex="-1"` +- Selecting a tab shows the corresponding panel +- Home / End keys jump to first / last tab + +--- + +## Toggle switch + +```html +<button + type="button" + role="switch" + aria-checked="false" + id="darkmode-toggle" +> + <span class="visually-hidden">Dark mode</span> +</button> +<label for="darkmode-toggle">Dark mode</label> +``` + +Toggle `aria-checked` between `"true"` and `"false"` on click. + +**Alternatively, use a real checkbox styled as a switch:** +```html +<label> + <input type="checkbox" role="switch" /> + Dark mode +</label> +``` + +--- + +## Combobox / autocomplete + +```html +<label for="city">City</label> +<input + id="city" + type="text" + role="combobox" + aria-autocomplete="list" + aria-controls="city-listbox" + aria-expanded="false" + autocomplete="off" +/> +<ul id="city-listbox" role="listbox" hidden> + <li role="option" id="city-1" aria-selected="false">London</li> + <li role="option" id="city-2" aria-selected="false">Lagos</li> +</ul> +``` + +**Behavior requirements:** +- Down arrow opens listbox +- Arrow keys navigate options +- Enter selects highlighted option +- Escape closes listbox +- `aria-activedescendant` on the input points to highlighted option +- Type-ahead filtering + +This is one of the most complex patterns. Test thoroughly with screen readers. + +--- + +## Menu / menubar + +```html +<button + type="button" + aria-haspopup="menu" + aria-expanded="false" + aria-controls="user-menu" +> + Account +</button> +<ul role="menu" id="user-menu" hidden> + <li role="menuitem" tabindex="-1"><a href="/profile">Profile</a></li> + <li role="menuitem" tabindex="-1"><a href="/settings">Settings</a></li> + <li role="menuitem" tabindex="-1"><a href="/logout">Sign out</a></li> +</ul> +``` + +**Behavior requirements:** +- Down arrow / up arrow navigate menu items +- Escape closes menu +- Click outside closes menu +- Focus returns to trigger on close + +**Important:** `role="menu"` is for command-style menus (like a desktop application's File menu). For navigation, use `<nav>` with regular links instead. + +--- + +## Loading and live regions + +```html +<div role="status" aria-live="polite"> + Loading results... +</div> +``` + +Use `role="status"` (or `aria-live="polite"`) for non-urgent updates. +Use `role="alert"` (or `aria-live="assertive"`) for urgent errors. + +**Anti-patterns:** +- Spinners with no announcement (screen readers don't know anything changed) +- Live regions that announce too aggressively (`aria-live="assertive"` for non-critical updates) + +--- + +## Skip link + +```html +<a href="#main-content" class="skip-link">Skip to main content</a> +... +<main id="main-content">...</main> +``` + +CSS: +```css +.skip-link { + position: absolute; + top: -100px; + left: 0; +} +.skip-link:focus { + top: 0; +} +``` + +The skip link should be the first focusable element on the page. Visible only when focused. + +--- + +## Visually hidden but available to screen readers + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +Use for content that screen readers need but sighted users don't (e.g., the label of an icon-only button). + +```html +<button type="button"> + <SearchIcon aria-hidden="true" /> + <span class="visually-hidden">Search</span> +</button> +``` + +**Anti-pattern:** `display: none` or `visibility: hidden` removes content from the accessibility tree too. Use `visually-hidden` for content meant for screen readers only. + +--- + +## Generic notes + +- **Test with a real screen reader.** VoiceOver (macOS, iOS) and NVDA (Windows) are free. +- **Test with keyboard alone.** Unplug the mouse. Can you accomplish the task? +- **Run automated tests.** axe DevTools, Lighthouse, WAVE catch the basics. +- **Don't fake elements that exist.** A `<div role="button">` is worse than a `<button>`. +- **Less ARIA is more.** Most components need little or no ARIA. Semantic HTML does the work. + +For deep accessibility audits, use `accessibility-audit`. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md b/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md new file mode 100644 index 0000000..96283bc --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md @@ -0,0 +1,311 @@ +# Component API Patterns + +Common patterns for building flexible, predictable component APIs. Examples assume React idioms but the patterns translate to Vue, Svelte, and Web Components. + +--- + +## Pattern 1: Compound components + +Multi-part components where each part is a separate sub-component sharing state via context. + +**Use when:** +- The component has distinct, repeating sub-parts (header, body, footer) +- Consumers need flexibility in arrangement and content +- Internal state needs to coordinate across parts + +```jsx +<Card> + <Card.Header>Title</Card.Header> + <Card.Body> + <Text>Content</Text> + </Card.Body> + <Card.Footer> + <Button>Action</Button> + </Card.Footer> +</Card> +``` + +**Pros:** +- Highly composable +- Consumers control arrangement +- Internal state stays encapsulated + +**Cons:** +- More API surface to maintain +- Less guidance for the consumer (any arrangement is "valid") + +--- + +## Pattern 2: Slots / render children + +A single component that accepts content through specific slots. + +**Use when:** +- The component has one or two specific insertion points +- Compound components feel like overkill + +```jsx +<Modal + title="Confirm action" + footer={<Button>Confirm</Button>} +> + <p>Are you sure?</p> +</Modal> +``` + +In Web Components: `<slot name="title">`. In Vue: named slots. In React: prop-as-element. + +**Pros:** +- Smaller API surface than compound components +- Clear insertion points + +**Cons:** +- Less flexible if the consumer wants to vary arrangement + +--- + +## Pattern 3: Render props / function as children + +The component provides state, the consumer provides UI. + +**Use when:** +- The component has reusable behavior (e.g., dropdown logic) +- Multiple visual variations should share the behavior +- Headless component libraries (Radix, Headless UI) use this heavily + +```jsx +<Dropdown> + {({ isOpen, toggle, items }) => ( + <> + <button onClick={toggle}>Menu</button> + {isOpen && <ul>{items.map(item => <li>{item}</li>)}</ul>} + </> + )} +</Dropdown> +``` + +**Pros:** +- Maximum flexibility +- Behavior and presentation cleanly separated + +**Cons:** +- Steeper learning curve +- More boilerplate at the call site + +--- + +## Pattern 4: Headless components + +Components that ship behavior and accessibility without prescribing visual style. + +**Use when:** +- Multiple consumers want different looks +- Accessibility is hard and worth centralizing +- Building a primitive layer + +```jsx +// Headless: behavior + accessibility, no visual style +<Listbox value={selected} onChange={setSelected}> + <Listbox.Button>{selected}</Listbox.Button> + <Listbox.Options> + {options.map(option => ( + <Listbox.Option key={option} value={option}>{option}</Listbox.Option> + ))} + </Listbox.Options> +</Listbox> +``` + +The consumer styles each part however they want. + +**Pros:** +- Reusable across visual styles +- Accessibility hard work centralized + +**Cons:** +- Consumers must style every part +- Less batteries-included + +--- + +## Pattern 5: Controlled vs uncontrolled + +Two modes: + +**Uncontrolled** (component owns its state): +```jsx +<Input defaultValue="initial" onChange={handleChange} /> +``` + +**Controlled** (consumer owns the state): +```jsx +<Input value={value} onChange={setValue} /> +``` + +**Pattern:** Support both. Uncontrolled is convenient for simple cases. Controlled is required when state needs to live in the parent. + +```jsx +function Input({ value, defaultValue, onChange, ...props }) { + const isControlled = value !== undefined; + const [internalValue, setInternalValue] = useState(defaultValue); + const currentValue = isControlled ? value : internalValue; + + const handleChange = (e) => { + if (!isControlled) setInternalValue(e.target.value); + onChange?.(e); + }; + + return <input value={currentValue} onChange={handleChange} {...props} />; +} +``` + +**Convention:** `value` for controlled, `defaultValue` for uncontrolled. Documented behavior when both are provided (typically: warn, treat as controlled). + +--- + +## Pattern 6: Polymorphic components (the `as` prop) + +A component that can render as different HTML elements while preserving its API. + +**Use when:** +- Visual style should apply to multiple HTML elements (e.g., a Heading that could be h1, h2, etc.) +- Consumers occasionally need to override the rendered element + +```jsx +<Text as="h1">Page title</Text> +<Text as="span">Inline text</Text> +<Text as="a" href="/path">Link</Text> +``` + +**Pros:** +- Style and semantics decoupled when needed + +**Cons:** +- Type complexity (TypeScript polymorphic types are non-trivial) +- Easy to misuse (rendering an h1 styled as a span breaks structure) + +Use sparingly. The default rendered element should fit most cases. + +--- + +## Pattern 7: Context for cross-component state + +When sub-components in a tree need shared state, use context. Don't drill props. + +```jsx +const TabContext = createContext(); + +function Tabs({ children, defaultIndex = 0 }) { + const [activeIndex, setActiveIndex] = useState(defaultIndex); + return ( + <TabContext.Provider value={{ activeIndex, setActiveIndex }}> + {children} + </TabContext.Provider> + ); +} + +function Tab({ index, children }) { + const { activeIndex, setActiveIndex } = useContext(TabContext); + return ( + <button + role="tab" + aria-selected={activeIndex === index} + onClick={() => setActiveIndex(index)} + > + {children} + </button> + ); +} +``` + +**Convention:** Context tied to a specific component family. Don't overload one context across unrelated components. + +--- + +## Pattern 8: forwardRef and ref forwarding + +Components should pass refs through to their underlying DOM element when reasonable. + +```jsx +const Button = forwardRef(function Button({ children, ...props }, ref) { + return <button ref={ref} {...props}>{children}</button>; +}); +``` + +**Why:** +- Consumers need DOM access (focus, measure, scroll) +- Form libraries need refs to inputs +- Animation libraries need refs to elements + +**Convention:** Forward refs on any component that wraps a single primary DOM element. Document where the ref attaches. + +--- + +## Pattern 9: Variant / size enums via discriminated unions + +Use string enums for variant and size props. + +```typescript +type ButtonProps = { + variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; + size?: 'sm' | 'md' | 'lg'; + // ... +}; +``` + +**Why:** +- Self-documenting +- Type-safe +- Consumers see options via autocomplete + +**Anti-pattern:** Boolean variant props. + +```typescript +// Bad +type ButtonProps = { + primary?: boolean; + secondary?: boolean; + danger?: boolean; +}; +``` + +Boolean variants permit invalid combinations (`primary={true} danger={true}`). + +--- + +## Pattern 10: Event handler conventions + +| Convention | Example | +|---|---| +| `onX` for events | `onClick`, `onChange`, `onClose` | +| `onXChange` for state changes | `onValueChange`, `onOpenChange` | +| Pass event object as first arg | `onClick(event)` | +| For state changes, pass new state as first arg | `onOpenChange(isOpen)` | + +**Anti-patterns:** +- `handleClick` as a prop name (consumer confusion - this is the implementation, not the API) +- `change` instead of `onChange` +- Passing transformed event without the original + +--- + +## API audit checklist + +Before shipping a component: + +- [ ] Default behavior is reasonable with zero props +- [ ] Variant prop uses string enum, not booleans +- [ ] Size prop uses string enum, not numbers (when sizes are constrained) +- [ ] Event handlers use `onX` convention +- [ ] Required props are minimal (ideally zero, often one) +- [ ] Optional props document defaults +- [ ] Component is forwardable (refs work) +- [ ] Polymorphic only where genuinely useful +- [ ] No boolean explosion (more than 5 booleans is a smell) +- [ ] State is controllable when it makes sense (controlled/uncontrolled support) +- [ ] Accessibility props are first-class (`aria-label`, `aria-describedby`, etc.) +- [ ] className/style override pattern documented +- [ ] All variants have visual examples in docs +- [ ] All states have visual examples in docs +- [ ] Keyboard interactions documented + +If any item fails, the API needs another pass before ship. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md b/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md new file mode 100644 index 0000000..bae7d3f --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md @@ -0,0 +1,250 @@ +# Component Spec Template + +Fillable template for documenting a component before writing code. The cost of writing a spec is small. The cost of building, shipping, and rebuilding a component because the API was wrong is large. + +Fill every section. If a section is "N/A", say why. + +--- + +## Identity + +**Component name:** [PascalCase. e.g., `Button`, `DatePicker`, `DropdownMenu`] +**Layer:** [Primitive / Pattern / Template] +**Status:** [Proposal / Draft / In review / Production] +**Owner:** [Name] +**Related components:** [Sibling components, parent components, components this composes or replaces] + +--- + +## Purpose + +One paragraph. What this component does, who uses it, and why it exists at all. + +If you cannot articulate why this is a system component (vs a one-off in product code), it should not be in the system yet. + +> [Purpose statement] + +--- + +## Use cases + +List the real, concrete use cases this component must serve. If the list is empty or hypothetical, the component is premature. + +1. [Specific scenario, e.g., "Submit a form on the checkout page"] +2. [Specific scenario] +3. [Specific scenario] + +### Anti-use cases + +When NOT to use this component. Helps consumers pick the right primitive. + +- [Scenario, e.g., "Triggering navigation - use `Link` instead"] +- [Scenario] + +--- + +## API + +### Props + +| Prop | Type | Default | Required | Description | +|---|---|---|---|---| +| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | No | Visual treatment | +| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | | +| `disabled` | `boolean` | `false` | No | | +| `loading` | `boolean` | `false` | No | Shows spinner; auto-disables interaction | +| `leadingIcon` | `ReactNode` | - | No | | +| `trailingIcon` | `ReactNode` | - | No | | +| `as` | `ElementType` | `'button'` | No | Polymorphic root element | +| `onClick` | `(e: MouseEvent) => void` | - | No | | +| `children` | `ReactNode` | - | Yes | Visible label | +| (etc.) | | | | | + +### Slots / composition + +If this is a compound component, describe each sub-component and its role. + +| Slot / sub-component | Purpose | Required | +|---|---|---| +| `Card.Header` | Title and optional icon | No | +| `Card.Body` | Main content | Yes | +| `Card.Footer` | Actions | No | + +### Events + +| Event | Payload | When fires | +|---|---|---| +| `onChange` | `{ value: string }` | User changes value, on blur or on each keystroke depending on `mode` prop | + +### Refs / imperative handles + +If the component exposes imperative methods, list them. + +| Method | Signature | Purpose | +|---|---|---| +| `focus` | `() => void` | Move focus to the component's primary interactive element | + +--- + +## States + +List every state the component can be in. Each state needs a visual treatment. + +| State | Visual | Trigger | +|---|---|---| +| Default | | Initial render | +| Hover | | Pointer over (non-touch) | +| Focus | | Keyboard focus | +| Active / pressed | | Mouse down or `Enter`/`Space` | +| Disabled | | `disabled` prop true | +| Loading | | `loading` prop true | +| Error | | Error context (validation failure, API error) | +| Empty / no data | | (For data-bearing components) | +| Read-only | | (For form inputs) | + +### State combinations + +Some states combine. Document the priority rules. + +- Loading + disabled: spinner shows, looks disabled. +- Error + focus: focus ring shows in error color. +- (etc.) + +--- + +## Accessibility + +This section is non-negotiable. Every interactive component has an accessibility section. If the component is decorative, say so explicitly. + +### Role and semantics + +- **Native element:** [What HTML element is the root, e.g., `<button>`, `<input type="text">`] +- **ARIA role (if not native):** [e.g., `role="dialog"`] +- **Label requirement:** [How is the accessible name set? `aria-label`, visible label, etc.] + +### Keyboard interaction + +| Key | Action | +|---|---| +| `Tab` | | +| `Shift + Tab` | | +| `Enter` | | +| `Space` | | +| `Escape` | | +| `Arrow keys` | | +| `Home / End` | | + +### Screen reader behavior + +- What is announced on focus? +- What is announced on state change (loading, error)? +- Are there `aria-live` regions for status updates? + +### Focus management + +- Where does focus go on mount? On unmount? +- Is focus trapped (e.g., modals)? +- Is focus visible (focus ring)? + +### Color contrast + +Confirm WCAG AA at minimum (3:1 for non-text, 4.5:1 for body text, 3:1 for large text). Note any state where contrast is at risk (disabled state often fails AA on purpose; document the choice). + +### Touch target size + +- Minimum 44x44px on mobile (WCAG 2.5.5). +- Document if smaller and why. + +--- + +## Edge cases + +The cases that always come up after launch. Document them now. + +- [ ] **Empty content:** What if `children` is empty? +- [ ] **Very long content:** What if the label is 200 characters? Truncate, wrap, or expand? +- [ ] **No data:** For data-bearing components, what does the empty state look like? +- [ ] **Loading:** What does the loading state look like? Skeleton? Spinner? Disabled? +- [ ] **Error:** Inline error? Toast? Both? +- [ ] **Disabled with tooltip:** A disabled `<button>` cannot receive focus, so a tooltip explaining why it is disabled needs special handling. +- [ ] **Right-to-left:** Does the layout flip correctly? +- [ ] **High zoom (200%):** Does the layout hold? +- [ ] **Dark mode:** Are tokens used so dark mode works automatically? +- [ ] **Reduced motion:** Are animations disabled when `prefers-reduced-motion: reduce`? + +--- + +## Variants and customization + +### Built-in variants + +What variants ship out of the box (`size`, `variant`, etc.). Document each. + +### Customization API + +How can consumers customize without forking? `className` pass-through? Style props? Slots? CSS custom properties? + +### What is NOT customizable + +Be explicit about what consumers cannot override. This is the system's stance, not a bug. + +--- + +## Internationalization + +- [ ] Text is via prop or children (not hardcoded) +- [ ] Plural and count formatting uses `Intl.PluralRules` +- [ ] Date / time formatting uses `Intl.DateTimeFormat` +- [ ] Layout works in RTL (logical properties: `margin-inline-start`, `padding-inline-end`) +- [ ] Bidirectional text (mixed LTR / RTL strings) handled + +--- + +## Performance + +- **Bundle weight target:** [KB compressed] +- **Render cost:** [Should be cheap. If expensive, document why.] +- **Re-render risk:** [Memoize? Stable callbacks expected from consumers?] +- **Lazy-loadable:** [Yes / no] + +--- + +## Testing + +### Unit tests + +- [ ] Renders default state +- [ ] Renders all variants +- [ ] Fires events on interaction +- [ ] Respects disabled / loading state +- [ ] Forwards refs + +### Accessibility tests + +- [ ] Axe passes on default state +- [ ] Axe passes on each variant +- [ ] Keyboard navigation tested +- [ ] Screen reader pass (manual or automated) + +### Visual regression tests + +- [ ] Each variant snapshot +- [ ] Each state snapshot +- [ ] RTL snapshot +- [ ] Dark mode snapshot + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +- Design approved: [Name, date] +- Engineering approved: [Name, date] +- Accessibility reviewed: [Name, date] +- Ready for production: [Date] diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md b/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md new file mode 100644 index 0000000..ffa49be --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md @@ -0,0 +1,306 @@ +--- +name: funnel-flow-architecture +description: "Architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. Honest about silo-funnels (every tool standalone), kitchen-sink-funnels (every audience squeezed through one path), and matched-funnels (architecture matched to audience-and-stage) patterns. Triggers on funnel design, conversion architecture, marketing funnel, growth funnel, lifecycle architecture, nurture sequence design, multi-tool funnel orchestration. Also triggers when the team's growth tools are working individually but not together, when audience segments share one nurture path, or when a funnel is being architected from scratch." +category: growth-tooling +catalog_summary: "Architecting cross-tool conversion flows that match audience and stage. Distinguishes silo-funnels (every tool standalone) from kitchen-sink-funnels (every audience squeezed through one path) from matched-funnels (architecture matched to audience-and-stage)" +display_order: 6 +--- + +# Funnel Flow Architecture + +A senior growth practitioner's playbook for architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. The discipline of building a funnel architecture, not just collecting tools. + +Most growth programs accumulate tools without architecture. A chatbot, a calculator, a quiz, a lead magnet, a newsletter signup, a demo CTA. Each tool works individually; none of them work together. Visitors hit one tool, leave, and never enter the broader nurture sequence. The funnel is a collection of orphans. + +The growth programs that compound do something different. They architect the funnel deliberately. Different entry points lead to different nurture sequences. Different stages get different CTAs. Different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. + +This skill is the architecture skill that orchestrates the other 5 growth-tooling skills (lead-magnet-design, calculator-design, quiz-and-assessment-design, multi-step-form-design, chatbot-flow-design). Where those skills zoom into specific tool design, this skill zooms out to the cross-tool architecture that determines whether the tools compound. + +The voice is the senior growth practitioner who has watched funnels architecture compound and watched siloed funnel collections produce engagement metrics with no business impact. Practical, opinionated about the difference between collecting tools and architecting funnels, willing to call out when a team's growth program needs architecture rather than another tool. + +When to use this skill: architecting a funnel from scratch, auditing a growth program where tools work individually but conversion is flat, designing the cross-tool data flow that captures audience signal across touchpoints, or deciding which segments warrant which funnel paths. + +--- + +## What this skill covers + +This skill spans cross-tool funnel architecture. The growth-tooling distinctions: + +- `lead-magnet-design`, `calculator-design`, `quiz-and-assessment-design`, `multi-step-form-design`, `chatbot-flow-design` are tools that LIVE INSIDE the funnel architecture this skill designs. They zoom into specific tool design. +- `content-distribution` covers how content reaches audiences. This skill is what audiences DO once they reach content. +- `experiment-design` validates funnel changes. This skill designs the architecture; experiment-design tests it. +- `landing-page-copy` covers page-level copy. This skill is the cross-page architecture. +- **`funnel-flow-architecture` (this skill)** is audience-and-stage segmentation, entry-point architecture, tool-to-funnel mapping, nurture sequence architecture, cross-tool data flow. + +The audience: growth marketing leads, product marketing leads, marketing directors at SMB and mid-market companies, agencies running funnel architecture for clients, founders architecting growth programs from scratch. + +Out of scope: specific tool design (covered by the 5 sister growth-tooling skills); content distribution mechanics (covered by `content-distribution`); A/B testing methodology (covered by `experiment-design`); page-level copy (covered by `landing-page-copy`). + +--- + +## Silo-funnels vs kitchen-sink-funnels vs matched-funnels + +The keystone framing. + +**Silo-funnels.** Each tool (chatbot, calculator, lead magnet, quiz) lives independently. No coordinated flow; users hit one tool, leave, never enter the broader nurture sequence. Tools as orphans. Cost: each tool's investment does not compound; the audience that interacts with one tool is not connected to any next step; the team has tools but no architecture. + +**Kitchen-sink-funnels.** One funnel for everyone. Same nurture sequence regardless of audience or entry point. SMB and enterprise get the same emails. New visitors and bottom-of-funnel get the same CTAs. Conversion rates regress to mediocre on every segment. Cost: the funnel optimizes for the average; no segment is well-served; downstream conversion is uniformly low. + +**Matched-funnels.** Funnel architecture matches audience and stage. Different entry points lead to different nurture sequences; different stages get different CTAs; different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. Cost: the design effort upfront is significant; the maintenance is real; downstream conversion is meaningfully higher per segment. + +The litmus test. Pick a recent visitor to the site. Can the team explain which segment the visitor falls into, which entry point they used, which nurture sequence they are in, and what the next-step CTA they will see is? If yes, the funnel is matched. If the answer is "they got the same flow as everyone else," the funnel is kitchen-sink. If the answer is "they used the calculator but I do not know what comes next," the funnel is silo. + +--- + +## Audience and stage segmentation + +The foundation. + +**The principle.** Funnel architecture starts with audience and stage segmentation. Without segmentation, every visitor goes through the same path; the funnel cannot match. + +**Audience dimensions.** + +- **Company size or buyer type.** Solo, SMB, mid-market, enterprise. +- **Industry or vertical.** Healthcare, finance, retail, technology. +- **Use case.** What the audience is trying to accomplish. +- **Role.** Founder, PM, marketer, executive, IC. +- **Source.** Paid traffic, organic, referral, partner. + +**Stage dimensions.** + +- **Awareness.** Just discovered the brand or the topic. +- **Consideration.** Evaluating options actively. +- **Decision.** Choosing between specific options. +- **Customer.** Already a customer; ongoing relationship. + +**The intersection.** Audience x stage produces the matrix the funnel architecture serves. An enterprise PM in consideration is a different segment from an SMB founder in awareness; each warrants a different path. + +**Segmentation discipline.** Start with 3-5 audiences and 3 stages. 9-15 cells in the matrix. Some cells may share paths; some may have unique paths. The discipline is naming the segments deliberately rather than treating "everyone" as the audience. + +Detail in [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md). + +--- + +## Entry-point architecture + +How visitors land vs how they're routed. + +**The principle.** The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). + +**Common entry points.** + +- **Paid landing page.** Visitor arrives via ad; high intent; specific to the ad's promise. +- **Organic content page.** Visitor arrives via search or content discovery; awareness or research stage. +- **Direct.** Visitor arrives by typing URL or via bookmark; often returning. +- **Referral.** Visitor arrives via partner or word-of-mouth; warmer than paid. +- **Social.** Visitor arrives via social post; awareness or interest. +- **Tool entry.** Visitor arrives via a calculator, quiz, or chatbot directly. + +**Entry-point routing.** + +- Each entry point has expected segments and stages. +- The first action available at the entry point should match likely segment and stage. +- Different entry points may route to different downstream tools and sequences. + +**Worked example.** A visitor arriving via a paid ad about "B2B SaaS pricing" is likely in consideration stage looking for pricing information. The landing page should serve that need (clear pricing, comparison, calculator); the next-step offer should match consideration (demo, talk to sales). Same visitor arriving via an organic blog post about "B2B SaaS pricing strategy" is likely in awareness stage; the landing page should serve education (depth on pricing strategy); the next-step offer should match awareness (subscribe to content, get the framework). + +Detail in [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md). + +--- + +## Tool-to-funnel mapping + +Which tools serve which entry points. + +**The principle.** Each tool in the growth toolkit has a place in the funnel architecture. The tool serves specific segments at specific stages from specific entry points. + +**Mapping examples.** + +- **Lead magnet.** Often serves awareness-to-consideration transition. Captured email leads to nurture sequence. +- **Calculator.** Often serves consideration stage. The audience evaluating options uses the calculator to defend a specific decision. +- **Quiz.** Can serve any stage depending on design. Awareness quizzes for content marketing; consideration quizzes for product matching; decision quizzes for plan selection. +- **Multi-step form.** Often serves decision or qualification stage. The form captures qualified intent. +- **Chatbot.** Cross-cutting. Can serve any stage with intent recognition routing. + +**The tool-segment fit.** Tools should serve segments that match their value proposition. A calculator for solo founders may need different inputs and outputs than a calculator for enterprise buyers; the same calculator cannot serve both well. + +**The portfolio approach.** A team often has multiple tools serving different segments. The architecture maps each tool to its specific segments and stages. + +Detail in [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md). + +--- + +## Nurture sequence architecture + +Per-segment, per-stage. + +**The principle.** Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. + +**Sequence variation by stage.** + +- **Awareness sequence.** Educational; broad value; brand-building. Soft offers if any. +- **Consideration sequence.** Comparative; specific value; product-fit signals. Demo or trial CTAs. +- **Decision sequence.** Confidence-building; risk-reversal; urgency cues. Direct purchase or commitment CTAs. + +**Sequence variation by audience.** + +- Enterprise audiences get different content (white papers, case studies, ROI analysis) than SMB audiences (templates, quick wins, peer testimonials). +- Different roles get different framing (founder content emphasizes business outcomes; IC content emphasizes practitioner depth). +- Different industries get different examples and language. + +**The kitchen-sink sequence failure.** One sequence for everyone. Generic enough to send to all; specific enough for none. Conversion uniformly mediocre. + +**The matched sequence win.** Sequence specific to segment-and-stage. The audience perceives the brand as understanding their situation; conversion compounds. + +Detail in [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md). + +--- + +## Cross-tool data flow + +Capturing context from tool to tool. + +**The principle.** When the audience moves from one tool to another in the funnel, the audience signal travels with them. The chatbot conversation context informs the calculator's defaults; the calculator inputs inform the lead-magnet sequence; the quiz result informs the demo-request prefill. + +**Cross-tool data flow patterns.** + +- **Identity threading.** When the audience is identified at any point (logged in, opted in, identified by email), their identity carries forward across tools. +- **Context capture.** Inputs from one tool (calculator values, quiz results, form submissions) feed into the next interaction. +- **Segment tagging.** Each interaction tags the audience with segment information that informs future routing. +- **Sequence-tool integration.** Email sequences include links to specific tools matched to the audience's segment. + +**The siloed-tool failure.** Each tool captures its own data; nothing flows between them. The chatbot conversation is forgotten when the user opens the calculator; the calculator inputs are forgotten when the user opens the lead magnet. + +**The integrated-funnel win.** Data flows. The audience experiences continuity; the brand can match content and offers to the audience's specific journey. + +Detail in [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md). + +--- + +## Funnel measurement + +What to measure, what is noise. + +**The principle.** Funnel measurement should reveal architecture quality, not just tool quality. + +**Architecture-level metrics.** + +- **Cross-tool conversion.** What percentage of audience that hits tool A then engages with tool B? +- **Sequence-to-tool conversion.** What percentage of nurture sequence subscribers engage with downstream tools? +- **Segment-level downstream conversion.** Per-segment conversion to the program's main goal (trial, demo, purchase). +- **Funnel-stage progression.** What percentage of audience moves from awareness to consideration to decision over time? + +**Tool-level metrics.** + +- Conversion rate per tool (covered by each tool's skill). + +**Architecture-level vs tool-level.** Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. Both matter; architecture is often the missing measurement. + +Detail in [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md). + +--- + +## Funnel iteration discipline + +When to redesign, when to refine. + +**The principle.** Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +**Refine when:** + +- Specific tools are underperforming relative to baseline. +- Specific segments have lower conversion than peer segments. +- Specific transitions in the funnel are producing drop-off. +- Sequence engagement is declining for specific cohorts. + +**Redesign when:** + +- Audience composition has fundamentally shifted. +- Product or service strategy has changed. +- Competitive landscape has shifted significantly. +- Multiple refine cycles have not produced expected results, suggesting architectural issues. + +**Continuous-redesign trap.** Teams that constantly redesign never benefit from architectural compounding. Each redesign resets the learning; nothing accumulates. + +**Frozen-architecture trap.** Teams that never iterate watch their architecture decay as audiences and markets evolve. + +The middle ground. Refine continuously; redesign infrequently and deliberately. + +Detail in [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md). + +--- + +## Architecture anti-patterns + +Patterns that look like funnel architecture but degrade conversion. + +**The silo-funnels pattern.** Tools as orphans; no architecture. + +**The kitchen-sink-funnels pattern.** One funnel for everyone. + +**The over-segmented funnel.** So many segments that maintenance is impossible; segments are not actually distinguishable. + +**The unmaintained-funnel.** Architecture designed once, never reviewed; decay accumulates. + +**The tool-driven-architecture.** Architecture organized around tools rather than around audience-and-stage; each tool gets its own funnel regardless of whether that serves the audience. + +**The metric-blind-architecture.** Architecture without measurement; cannot diagnose where it works and where it does not. + +**The single-tool-funnel.** Architecture that depends on one tool (just the calculator, just the chatbot); no resilience if that tool underperforms. + +**The hand-off-broken-funnel.** Tools work individually but the transitions between them break. + +Detail in [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md). + +--- + +## The framework: 12 considerations for funnel flow architecture + +When designing or auditing a funnel architecture, walk these 12 considerations. + +1. **Matched-funnels, not silo or kitchen-sink.** Architecture matches audience-and-stage; each tool is part of the architecture, not a standalone artifact. +2. **Audience and stage segmentation defined.** 3-5 audiences x 3 stages; the matrix the architecture serves. +3. **Entry-point architecture mapped.** Each entry point routed to expected segments and stages. +4. **Tool-to-funnel mapping documented.** Each tool serves specific segments at specific stages. +5. **Nurture sequence architecture per segment.** Sequences vary by audience and stage; not one sequence for everyone. +6. **Cross-tool data flow integrated.** Context travels across tools; the audience experiences continuity. +7. **Architecture-level metrics tracked.** Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion. +8. **Funnel iteration discipline.** Refine continuously; redesign deliberately; avoid both extremes. +9. **Tool portfolio balanced.** Multiple tools serving different segments; not over-reliant on any single tool. +10. **Audience-fit honest.** The architecture serves the segments the brand can actually serve; out-of-fit audiences are filtered or routed elsewhere. +11. **Maintenance ownership clear.** Someone owns the architecture; quarterly review is calendared. +12. **Expansion plan defined.** When adding new tools, the architecture says where they fit; new tools earn their place rather than being added decoratively. + +The output of the framework is a funnel architecture that compounds over time, matches audience-and-stage segments, integrates tool data flows, and produces measurable downstream conversion. + +--- + +## Reference files + +- [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md) - The foundation. Audience dimensions, stage dimensions, the intersection matrix. +- [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md) - How visitors land vs how they're routed. Common entry points and their routing. +- [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md) - Which tools serve which entry points and segments. +- [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md) - Per-segment, per-stage sequence variation. The matched sequence win. +- [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md) - Identity threading, context capture, segment tagging, sequence-tool integration. +- [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md) - Architecture-level vs tool-level metrics. What to measure, what is noise. +- [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md) - When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. +- [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md) - The patterns that look like funnel architecture but degrade conversion. +- [`references/common-funnel-architecture-failures.md`](references/common-funnel-architecture-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: funnels are architecture, not collections + +The growth programs that compound are the ones that architect their funnels deliberately. Not collect tools. Not optimize one-tool-at-a-time. Architect. + +The architecture is the difference between tools that produce engagement and a funnel that produces business outcomes. The chatbot, the calculator, the quiz, the lead magnet, the multi-step form: each one is a tool. None of them are a funnel. The funnel is the architecture that makes them work together. + +That is the bar. Below the bar are silo-funnels (tools as orphans) and kitchen-sink-funnels (one path for everyone). Above the bar are matched-funnels where audience-and-stage segmentation drives entry-point routing, tool-to-funnel mapping, nurture sequence design, cross-tool data flow, and architecture-level measurement. + +## Closing: funnels earn investment when they compose + +Each tool in the growth toolkit costs investment to build and maintain. The investment compounds when the tools compose; the investment dilutes when the tools sit in silos. Architecture is the discipline of composition. + +The compounding mechanism. A visitor arrives. The architecture routes them based on entry point and observable signals. The first tool they encounter serves their segment-and-stage. The data they generate informs the next tool they encounter. The sequence they enter matches their context. Each interaction deepens the brand's understanding of the audience; each tool's contribution compounds with the others. + +When in doubt, ask: does each tool in the program serve a defined segment-and-stage, do the tools share data and context, can the team explain the architecture in one diagram, and does the team measure architecture-level outcomes (not just tool-level metrics)? If yes to all of those, the funnel is real architecture. If no to any, the gap is where the program's tools are failing to compose. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md new file mode 100644 index 0000000..6595f7a --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md @@ -0,0 +1,198 @@ +# Architecture anti-patterns + +The patterns that look like funnel architecture but degrade conversion. Anti-patterns are easy to ship; the cost shows up in downstream conversion, lead quality, and brand reputation over time. + +--- + +## The silo-funnels pattern + +The pattern. Tools as orphans. No coordinated flow. + +The signal. Each tool's metrics look fine individually; cross-tool metrics non-existent or near-zero. Downstream conversion does not match the sum of tool conversions. + +The cost. Each tool's investment does not compound. The audience that interacts with one tool is not connected to any next step. The team has tools but no architecture. + +The cure. Add cross-tool data flow and explicit funnel architecture. Detail in `references/cross-tool-data-flow-patterns.md` and the broader skill. + +--- + +## The kitchen-sink-funnels pattern + +The pattern. One funnel for everyone. Same nurture sequence regardless of audience or entry point. + +The signal. Conversion rates regress to mediocre on every segment. No segment is well-served. + +The cost. The funnel optimizes for the average; downstream conversion is uniformly low. + +The cure. Segment-and-stage architecture. Different paths for different cells in the matrix. Detail in `references/audience-and-stage-segmentation.md` and `references/nurture-sequence-architecture.md`. + +--- + +## The over-segmented funnel + +The pattern. So many segments that maintenance is impossible. 60 cells in the matrix; 60 distinct paths; nobody can keep up. + +The signal. Specific paths get little attention; maintenance backlog grows; specific cells are theoretical with no real visitors. + +The cost. The architecture exists on paper but not in execution. Tools and sequences for theoretical cells cost effort without producing value. + +The cure. Reduce to 9-15 cells. Start with the minimum viable matrix; expand only when data justifies. Detail in `references/audience-and-stage-segmentation.md`. + +--- + +## The unmaintained-funnel + +The pattern. Architecture designed once, never reviewed. Decay accumulates. + +The signal. Conversion declines slowly; tools age; sequences go stale; segments shift; the architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; the brand falls behind. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## The tool-driven-architecture + +The pattern. Architecture organized around tools rather than around audience-and-stage. Each tool gets its own funnel regardless of whether that serves the audience. + +The signal. The site has many tool-specific landing pages; users navigate to tools rather than tools serving users; the architecture is organized for the team, not the audience. + +The cost. Audiences cannot find what they need; tools cannibalize each other; the architecture cannot scale because each tool is its own funnel. + +The cure. Reorganize around audience-and-stage. The matrix drives the architecture; tools serve the matrix. + +--- + +## The metric-blind-architecture + +The pattern. Architecture without measurement. Cannot diagnose where it works and where it does not. + +The signal. Decisions made on intuition; no data to validate; iteration is guesswork. + +The cost. The architecture cannot improve through measurement; refinement is random; redesign happens reactively. + +The cure. Architecture-level metrics. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## The single-tool-funnel + +The pattern. Architecture that depends on one tool. Just the calculator. Just the chatbot. No resilience if that tool underperforms. + +The signal. The tool's quarterly performance dictates overall funnel performance. A bad month for the tool is a bad month for the funnel. + +The cost. The architecture is fragile. Tool failures cascade; redesigns of the central tool are high-risk. + +The cure. Portfolio approach. Multiple tools serving different segments. The architecture's resilience comes from diversification. + +--- + +## The hand-off-broken-funnel + +The pattern. Tools work individually but the transitions between them break. + +The signal. Each tool's metrics look fine; cross-tool conversion is low. The architecture's transitions are silently failing. + +The cost. The audience experiences the funnel as disconnected. Downstream conversion suffers because the bridges between tools are broken. + +The cure. Audit transitions. Cross-tool data flow. Sequence-tool integration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## The continuous-redesign funnel + +The pattern. Architecture redesigned every quarter. Each iteration starts over. + +The signal. Conversion does not improve over time. Each redesign resets the learning. Tools never reach maturity. + +The cost. Investment dilutes across redesigns. Compounding does not happen. + +The cure. Refine continuously; redesign infrequently and deliberately. Detail in `references/funnel-iteration-discipline.md` (continuous-redesign trap). + +--- + +## The frozen-architecture funnel + +The pattern. Architecture designed once; never iterated; treated as finished. + +The signal. Conversion declines slowly; tools and sequences feel dated; segments no longer match the audience. + +The cost. The architecture's value erodes; the brand becomes uncompetitive. + +The cure. Set refinement cadences. Quarterly audits. Detail in `references/funnel-iteration-discipline.md` (frozen-architecture trap). + +--- + +## The vanity-metric architecture + +The pattern. Architecture measured by surface metrics (tool engagement, total visitors, email signups) without measuring downstream outcomes. + +The signal. Metrics report looks healthy; business outcomes do not match. + +The cost. The team optimizes for the wrong metrics; the architecture appears successful while underperforming on what matters. + +The cure. Measure downstream conversion. Per-segment downstream conversion. Architecture-level metrics rather than tool-level activity. + +--- + +## The over-personalized funnel + +The pattern. Architecture designed for personalization the team cannot actually deliver. Many entry points; many sequences; many tools; team capacity exceeded. + +The signal. Personalization in design; generic in execution. Specific paths exist on paper; default to generic in practice. + +The cost. The team built complexity that does not get used. Maintenance burden without payoff. + +The cure. Match architecture complexity to team capacity. Start simple; add personalization where it produces meaningful lift; do not personalize for its own sake. + +--- + +## The under-personalized funnel + +The pattern. Architecture treats every visitor the same when meaningful personalization would lift conversion. + +The signal. Specific segments underperform; the audience's actual differences are not reflected in the funnel. + +The cost. Conversion stays at the average; no segment exceeds. + +The cure. Add personalization where data shows it would help. Start with segment-level differentiation; refine over time. + +--- + +## The orphan-tool architecture + +The pattern. Tools added to the funnel without explicit segment-and-stage assignment. Each new tool exists; no architecture says where it fits. + +The signal. The funnel's tool count grows; the architecture's clarity does not. + +The cost. Tools compete for the same audience; users see overlapping options; conversion fragments. + +The cure. Each tool earns its place. Architecture documents which segments and stages the tool serves. New tools are added with explicit mapping. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of the architecture, looking specifically for these anti-patterns. + +**Audit questions.** + +- Do the tools work together (anti-pattern check: silo, hand-off-broken)? +- Is there segment-and-stage architecture (anti-pattern check: kitchen-sink, tool-driven)? +- Is the matrix maintainable (anti-pattern check: over-segmented, over-personalized)? +- Are tools mapped to specific segments (anti-pattern check: orphan-tool, single-tool, under-personalized)? +- Are architecture-level metrics tracked (anti-pattern check: metric-blind, vanity-metric)? +- Is there iteration discipline (anti-pattern check: continuous-redesign, frozen-architecture, unmaintained)? + +**The retire decision.** Anti-pattern architectures often warrant redesign. Patching anti-patterns rarely produces a good architecture. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md new file mode 100644 index 0000000..f2ce571 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md @@ -0,0 +1,200 @@ +# Audience and stage segmentation + +The foundation. Audience dimensions, stage dimensions, the intersection matrix. + +Funnel architecture starts with audience and stage segmentation. Without it, every visitor goes through the same path; the funnel cannot match. With it, the architecture has a definable map of who the audience is and where they are in their journey. + +--- + +## The segmentation principle + +The funnel cannot be tailored without segments. Segments are the architecture's unit of design. + +**The discipline.** Define 3-5 audience segments and 3 stages. The intersection produces 9-15 cells; each cell is a potential funnel path. + +**The trap.** Over-segmenting. Defining 12 audiences x 5 stages produces 60 cells; the team cannot maintain that many distinct paths. Most cells end up sharing paths or being indistinguishable. + +**The discipline boundary.** Start with the minimum viable segmentation. 3-5 audiences and 3 stages is enough to start. Expand only if the data shows meaningful differentiation that justifies more cells. + +--- + +## Audience dimensions + +The dimensions that distinguish meaningful audience segments. + +**Company size or buyer type.** Solo founders, SMB (10-50), mid-market (50-500), enterprise (500+). Different sizes have different buying processes, different budgets, different needs. + +**Industry or vertical.** Healthcare, finance, retail, technology, education. Different industries have different language, regulations, examples, competitors. + +**Use case.** What the audience is trying to accomplish. "Customer support automation," "sales pipeline management," "content production at scale." + +**Role.** Founder, PM, marketer, sales lead, executive, IC. Different roles have different perspectives and different content preferences. + +**Source or channel.** Paid traffic, organic search, content referral, partner referral, direct. Different sources signal different intent and stage. + +**Geography or language.** Domestic vs international; English-first vs other-language audiences. May warrant different funnels for compliance, currency, or cultural reasons. + +The audience dimensions to use depend on the brand's strategy. Most B2B brands segment primarily by company size and use case; most consumer brands segment by demographic and behavioral attributes. + +--- + +## Stage dimensions + +The dimensions that distinguish where the audience is in their journey. + +**Awareness.** Just discovered the brand or the topic. Has not yet committed to research or evaluation. The audience is open but uncommitted. + +Content fit: educational, broad value, brand-building. +CTAs that fit: subscribe to content, get a framework, follow. +CTAs that do not fit: book a demo, start a trial, buy now. + +**Consideration.** Evaluating options actively. Has identified a need; comparing solutions. The audience is engaged but not yet decided. + +Content fit: comparative, specific value, product-fit signals. +CTAs that fit: see a calculator, take a quiz, download a comparison, book a demo. +CTAs that do not fit: just-published-content awareness asks; or hard sell. + +**Decision.** Choosing between specific options. The audience has narrowed the field; selecting is imminent. + +Content fit: confidence-building, risk-reversal, urgency cues. +CTAs that fit: start a trial, talk to sales, sign up. +CTAs that do not fit: top-of-funnel awareness; long-form education. + +**Customer.** Already a customer; ongoing relationship. Often left out of growth-funnel architecture even though it matters for retention and expansion. + +Content fit: success-deepening, capability-expanding, community. +CTAs that fit: upgrade, refer, join community, attend event. + +The four stages cover most audiences. Some programs combine awareness-and-consideration or consideration-and-decision into 2-stage models; the principle is the same. + +--- + +## The intersection matrix + +Audience x stage produces the matrix the funnel architecture serves. + +**Example matrix for a B2B SaaS company.** + +| Audience | Awareness | Consideration | Decision | +|----------|-----------|---------------|----------| +| Solo founder | Path A | Path B | Path C | +| SMB team | Path D | Path E | Path F | +| Mid-market | Path G | Path H | Path I | +| Enterprise | Path J | Path K | Path L | + +12 cells. Some may share paths (Path A and Path D might be similar awareness content for solo and SMB). The matrix is the architecture's map. + +**Cell-sharing patterns.** + +- Awareness paths often share more than decision paths (broad content can serve multiple audience segments). +- Consideration paths often diverge by audience (the comparison content for enterprise differs significantly from SMB). +- Decision paths almost always diverge (the offer for enterprise is different from SMB). + +The matrix shows where the funnel architecture invests in unique paths and where it shares. + +--- + +## Segmentation discipline + +The discipline boundaries. + +**Discipline 1: Define segments before designing paths.** Without segments, paths are arbitrary. Always start with the matrix. + +**Discipline 2: Name segments specifically.** "Solo founder pre-launch" beats "small business." Specific names reflect specific audiences. + +**Discipline 3: Validate segments with data.** A segment that does not appear in actual audience data is theoretical. Validate against site analytics, sales data, or audience research. + +**Discipline 4: Maintain the matrix.** Audiences shift; the matrix should be reviewed quarterly. Segments may merge or split over time. + +**Discipline 5: Avoid over-segmentation.** 60-cell matrices are not maintainable. Start with 9-15 cells; expand only with justification. + +--- + +## Segmentation worked example + +A B2B SaaS analytics platform. + +**Audiences (4).** + +- Data analysts at SMB companies (50-200 employees). +- Data leaders at mid-market companies (200-1000 employees). +- Engineering leaders at enterprise companies (1000+ employees). +- Solo data practitioners and consultants. + +**Stages (3).** + +- Awareness (researching the analytics topic). +- Consideration (evaluating analytics platforms). +- Decision (selecting and signing up). + +**Matrix (12 cells).** + +| Audience | Awareness | Consideration | Decision | +|----------|-----------|---------------|----------| +| Data analyst SMB | Educational content | Calculator, quiz | Trial, demo | +| Data leader mid-market | Strategic content | Comparison, ROI calc | Demo, custom quote | +| Engineering enterprise | Technical depth | Technical demo, security | Custom evaluation | +| Solo practitioner | Practical content | Self-serve resources | Free tier signup | + +Each cell has a defined path. The architecture invests where the cells need unique treatment; shares where the cells can use the same path. + +--- + +## Segmentation maintenance + +Segments decay. + +**What decays.** + +- Audience definitions that no longer match actual visitors. +- Stage definitions that have shifted as buying processes evolved. +- Cells that have become empty (no visitors fit the segment). +- Cells that have become bloated (too many visitors fit one segment; needs sub-segmentation). + +**Maintenance cadence.** Quarterly review of the matrix against actual audience data. + +**The drift indicator.** Sales reports that the funnel-sourced leads do not match expected segments; analytics show segments combining or splitting unexpectedly. + +--- + +## Segmentation and the rest of the architecture + +How segmentation drives the rest of the architecture. + +**Entry-point architecture.** Each entry point routes to expected segments. The matrix tells the architecture where each entry point's traffic likely lands. + +**Tool-to-funnel mapping.** Each tool serves specific cells in the matrix. The matrix tells the architecture which tools belong where. + +**Nurture sequence architecture.** Each cell may have its own sequence (or sequences may be shared across similar cells). The matrix is the sequence design map. + +**Cross-tool data flow.** As the audience moves through the matrix (awareness to consideration to decision), data flows with them. The matrix tracks the journey. + +**Funnel measurement.** Per-cell conversion is the architecture-level metric. The matrix is the measurement framework. + +--- + +## Common segmentation failures + +**No segmentation.** "Everyone" treated as the audience. Funnel cannot match. + +**Theoretical segments.** Segments defined that do not exist in actual audience data. + +**Over-segmentation.** 60-cell matrix that the team cannot maintain. + +**Under-segmentation.** 4-cell matrix when the audience genuinely splits into more meaningful segments. + +**Stale segmentation.** Matrix designed once; audience shifted; matrix not updated. + +**Segments without paths.** Matrix defined but no funnel paths designed for the cells; segmentation is decorative. + +**Paths without segments.** Funnel paths designed without clear segment mapping; treatments are arbitrary. + +--- + +## Methodology-level choices that stay in the public skill + +The segmentation principle and discipline boundaries. Audience dimensions. Stage dimensions. The intersection matrix. Segmentation discipline (5 disciplines). Worked example. Segmentation maintenance. Segmentation and the rest of the architecture. Common failures. + +## Implementation choices that stay internal + +Specific segments for the team's audience. Specific tooling for segment tagging and analysis. The team's matrix maintenance calendar. Specific path designs per cell. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md new file mode 100644 index 0000000..8f45320 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md @@ -0,0 +1,179 @@ +# Common funnel architecture failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the funnel is not converting" or "tools work individually but conversion is flat" or "we cannot tell where the funnel is broken." + +--- + +## "Tools work individually; conversion is flat." + +**The diagnosis.** Silo-funnels pattern. Tools as orphans; no architecture connects them. + +**The cure.** Add cross-tool data flow; map tools to specific segments; design transitions between tools. Detail in `references/cross-tool-data-flow-patterns.md` and `references/tool-to-funnel-mapping.md`. + +--- + +## "Every audience gets the same nurture sequence." + +**The diagnosis.** Kitchen-sink-funnels pattern. One sequence for everyone. + +**The cure.** Segment-and-stage sequences. Different cells in the matrix get different sequences. Detail in `references/nurture-sequence-architecture.md`. + +--- + +## "We have 12 tools and no clear architecture." + +**The diagnosis.** Tool-driven architecture. Tools accumulated without explicit segment mapping. + +**The cure.** Build the matrix; map each tool to specific cells; retire tools that do not have a mapping or that compete with better-mapped alternatives. + +--- + +## "Specific segments convert at half the rate of others." + +**The diagnosis.** Architecture for those segments may be broken. Or the segments may not be served by the current tools and sequences. + +**The cure.** Audit those segments' funnel paths. Are tools mapped to them? Are sequences designed for them? If not, build for those segments. If yes, refine the existing path. + +--- + +## "We cannot tell which tools or sequences are driving conversion." + +**The diagnosis.** Architecture-level metrics not tracked. Cannot attribute outcomes to architecture choices. + +**The cure.** Instrument cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## "We redesign every quarter; nothing improves." + +**The diagnosis.** Continuous-redesign trap. Each redesign resets learning; nothing compounds. + +**The cure.** Establish "no major redesign for X months" discipline. Refine continuously; redesign deliberately and rarely. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "The funnel was great at launch; now conversion has dropped 40 percent." + +**The diagnosis.** Frozen-architecture trap. Designed once; never iterated; decay accumulated. + +**The cure.** Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "Specific transitions in the funnel have high drop-off." + +**The diagnosis.** Hand-off-broken pattern. Tools work but the bridges between them break. + +**The cure.** Audit transitions. Add cross-tool data flow so context travels. Promote downstream tools at upstream tools' exits. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Our chatbot, calculator, and quiz all serve consideration-stage audiences." + +**The diagnosis.** Tool overlap without differentiation. Three tools competing for the same audience. + +**The cure.** Differentiate the tools' purposes. Calculator for ROI questions; quiz for product matching; chatbot for FAQ. Or consolidate to fewer tools with clearer roles. + +--- + +## "Sales says quiz-sourced leads, calculator-sourced leads, and lead-magnet-sourced leads are different qualities." + +**The diagnosis.** Tools may be attracting different segments; the architecture's segmentation is working but the tools are not all matched to high-quality segments. + +**The cure.** Investigate which tools attract which segments. Optimize tool placement and design for the segments the brand serves best; deprioritize tools that attract low-quality segments. + +--- + +## "We added a new tool last quarter; it does not seem to help conversion." + +**The diagnosis.** Orphan-tool pattern. Tool added without architecture mapping. + +**The cure.** Map the new tool to specific segments. Decide where it fits in the matrix. Promote it where it fits; remove it from places it does not. + +--- + +## "Our funnel has 8 stages; visitors only complete 2." + +**The diagnosis.** Funnel may be over-architected. Too many steps; audience cannot or will not progress through them all. + +**The cure.** Simplify the funnel. Combine stages; remove unnecessary tools; align the funnel length to the audience's likely journey. + +--- + +## "Cross-tool tracking is broken; we cannot tell who used what." + +**The diagnosis.** Identity threading or event tracking issue. Architecture's measurement infrastructure is broken. + +**The cure.** Audit identity threading. Verify event tracking. Fix the infrastructure before further iteration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Audiences arriving from paid traffic and organic traffic perform completely differently." + +**The diagnosis.** Either entry-point routing is not differentiating, or the funnel paths are not serving paid and organic audiences differently. + +**The cure.** Different routing for different entry points. Specific landing pages and sequences for paid vs organic. Detail in `references/entry-point-architecture-patterns.md`. + +--- + +## "The team built personas; the funnel does not reflect them." + +**The diagnosis.** Segments defined but not implemented in the funnel architecture. Decorative segmentation. + +**The cure.** Map personas to funnel cells. Build paths for the cells. The personas should drive the architecture, not sit in a deck. + +--- + +## "Our sequence-to-trial conversion is high; trial-to-paid is low." + +**The diagnosis.** Architecture handles funnel up to trial well; the trial-to-paid stage may need its own architecture (or may be a product issue rather than funnel issue). + +**The cure.** Treat trial-to-paid as its own funnel-stage progression. Build paths for trial users; nurture toward paid conversion. + +--- + +## "We have 15 lead magnets; 3 produce most of the leads." + +**The diagnosis.** Magnet portfolio not maintained. Most magnets are dead but still on the site. + +**The cure.** Audit and retire dead magnets. Free capacity for the strong ones. Detail in `lead-magnet-design`. + +--- + +## "We built a fancy architecture; the team cannot maintain it." + +**The diagnosis.** Over-architecture. Architecture exceeds team capacity. + +**The cure.** Simplify. Match architecture complexity to team capacity. Expand only when capacity grows. + +--- + +## "Funnel-sourced leads are different from sales-sourced leads." + +**The diagnosis.** Likely fine. Funnel and direct sales serve different segments and stages. Both can be valuable. + +**The action.** Track them separately. Optimize each for its specific path. + +--- + +## The pattern across failures + +Most funnel architecture failures fall into one of three patterns. + +**Pattern 1: Tools without architecture.** Silo, kitchen-sink, tool-driven, orphan-tool. The fix is to add explicit architecture (matrix, mapping, data flow). + +**Pattern 2: Architecture without measurement.** Metric-blind, vanity-metric, broken tracking. The fix is to instrument architecture-level metrics. + +**Pattern 3: Architecture without maintenance.** Frozen, decayed, unmaintained. The fix is iteration discipline (refine continuously, redesign rarely). + +The metric pattern: funnel architecture failures often look fine on tool-level metrics. The signal is in cross-tool conversion, segment-level outcomes, and funnel-stage progression. Programs that track only tool metrics keep shipping the same architectural patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (tools-without-architecture, architecture-without-measurement, architecture-without-maintenance). The principle that tool-level metrics alone are insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific architecture-level dashboards. Specific cures the team applies. The team's audit and redesign processes. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md new file mode 100644 index 0000000..a74f62a --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md @@ -0,0 +1,252 @@ +# Cross-tool data flow patterns + +Identity threading, context capture, segment tagging, sequence-tool integration. + +When the audience moves from one tool to another in the funnel, the audience signal travels with them. Done well, cross-tool data flow makes the audience experience continuous and lets the brand match content to the audience's specific journey. Done poorly, every tool starts from scratch and the audience signal is lost. + +--- + +## The continuity principle + +The audience experience should feel continuous across tools. Their interactions in one tool inform their experience in the next. + +**The win.** A visitor takes a quiz; the quiz tags them as "mid-market mid-funnel." When they later open the calculator, the defaults reflect mid-market context. When they download a lead magnet, the sequence delivered matches the segment. The visitor experiences a coordinated brand journey. + +**The fail.** The same visitor takes the quiz; the calculator does not know they took it; the lead magnet sequence is generic. Each tool is an island. The audience signal captured in one tool is wasted in the next. + +The discipline. Data flows. Each tool's interactions inform subsequent interactions. + +--- + +## Pattern A: Identity threading + +When the audience is identified, their identity carries forward across tools. + +**How it works.** + +- The audience opts in (email submission, account creation, login). +- Subsequent interactions are associated with that identity. +- Tools across the funnel access the identity record to personalize. + +**Strengths.** + +- Most powerful continuity mechanism. +- Lets all tools share context for the same person. + +**Weaknesses.** + +- Requires identity infrastructure (CRM, data warehouse, customer data platform). +- Privacy considerations (handling identity data carefully). + +**When to use.** When the program has identity infrastructure and the audience is willing to be identified (typically post lead-magnet download or account creation). + +--- + +## Pattern B: Context capture + +Inputs from one tool feed into the next interaction. + +**How it works.** + +- Tool A captures specific inputs (calculator values, quiz answers, form responses). +- Those inputs are stored with the identity (or with an anonymous session token). +- Tool B reads the inputs; uses them as defaults or context. + +**Example.** + +- Quiz captures "team size: 75." +- Calculator's defaults reflect team size 75. +- Lead magnet's recommended resource matches team size 75. + +**Strengths.** + +- Concrete continuity; the audience sees their inputs reflected. +- Reduces re-entry friction. + +**Weaknesses.** + +- Requires structured data capture (not just behavioral signals). +- Inputs from different tools must align (no conflict if quiz and calculator both capture team size). + +**When to use.** When tools capture overlapping or related context that benefits from shared use. + +--- + +## Pattern C: Segment tagging + +Each interaction tags the audience with segment information that informs future routing. + +**How it works.** + +- Tool A determines the audience's segment based on inputs (the quiz result; the calculator's input pattern). +- The segment tag attaches to the audience record. +- Subsequent tools and sequences route based on the tag. + +**Example.** + +- Quiz result: "Mid-market operator." +- Tag: segment = mid-market. +- Subsequent: lead magnet sequence is the mid-market sequence; calculator defaults are mid-market; chatbot routing is mid-market-aware. + +**Strengths.** + +- Lightweight. The tag is small; the routing logic uses it. +- Compatible with most marketing automation. + +**Weaknesses.** + +- Tag accuracy depends on the source tool's accuracy. +- Tags can conflict (different tools assign different segments). +- Tag staleness (the audience's segment may change over time). + +**When to use.** Default pattern for cross-tool routing. + +--- + +## Pattern D: Sequence-tool integration + +Email sequences include links to specific tools matched to the audience's segment. + +**How it works.** + +- Sequence email includes a CTA: "based on your situation, this calculator can help you compare." +- The CTA link includes parameters that pre-fill the calculator with the audience's known context. +- Audience clicks; calculator opens with their context already populated. + +**Strengths.** + +- Explicit cross-tool connection; the audience sees the journey. +- Reduces friction at the calculator (audience does not re-enter known information). + +**Weaknesses.** + +- Requires tooling for parameterized links and pre-fill. +- The pre-fill must respect what the audience consented to share. + +**When to use.** When the sequence is steering the audience toward specific tools and pre-fill would meaningfully reduce friction. + +--- + +## Conflict and source-of-truth + +When different tools capture different values for the same attribute. + +**The pattern.** The quiz says team size 75; the multi-step form says team size 60. Which is correct? + +**Approaches.** + +- **Latest wins.** The most recent capture overrides earlier captures. +- **Source authority.** Specific tools are designated as authoritative for specific attributes (form > quiz for verified data). +- **User confirmation.** Conflict surfaces a confirmation prompt: "We have you down as 75; is that still correct?" + +**The discipline.** Define source-of-truth for important attributes. Latest-wins is simple but can lose data; source authority is more disciplined but requires explicit definition. + +--- + +## Privacy and consent + +Cross-tool data flow involves handling user data. Consent matters. + +**The principle.** The audience should know what data flows where. Pre-filling a calculator with previously captured information is fine if the audience expects it; surprising them with knowledge they did not consent to share breaks trust. + +**Consent patterns.** + +- Explicit opt-in to identity tracking ("save my progress"). +- Disclosure of data flow ("we use your quiz answers to personalize subsequent recommendations"). +- Easy data deletion or account closure. + +**Privacy regulations.** GDPR, CCPA, and other regulations affect what data can flow and how. Compliance is essential; the architecture must respect the regulations applicable to the audience. + +--- + +## Anonymous-session continuity + +When the audience is not yet identified. + +**The pattern.** Browser-based continuity (cookies, local storage) lets tools share context within the same session even before identity capture. + +**Strengths.** + +- Continuity without requiring early opt-in. +- Smooth experience across same-session tool interactions. + +**Weaknesses.** + +- Lost when the audience switches devices or clears cookies. +- Limited persistence (typically days, not weeks). +- Privacy considerations (cookies-based tracking has its own complications). + +**When to use.** As a supplement to identity-based continuity; for early-funnel interactions before opt-in. + +--- + +## Cross-tool data flow architecture + +How to design the data flow at the architecture level. + +**The data layer.** A single data layer (CRM, customer data platform, data warehouse) holds the audience records. All tools read from and write to this layer. + +**The integration layer.** Tools integrate with the data layer either directly (API) or through a middleware (Zapier, Segment). + +**The privacy layer.** Consent and data-control mechanics live across the architecture; the data layer respects them. + +**Architecture-level discipline.** Cross-tool data flow is infrastructure work, not just tool work. Building the infrastructure is part of the funnel architecture investment. + +--- + +## Cross-tool measurement + +Track how data flows across tools. + +**Metrics.** + +- **Cross-tool engagement.** What percentage of subscribers who engaged with tool A also engaged with tool B? +- **Identity capture rate.** What percentage of visitors who interact with tools become identified? +- **Pre-fill usage.** When pre-fill is offered, what percentage of users engage with the pre-filled tool? +- **Segment tag accuracy.** Sample-based audit of whether segment tags match actual audience profiles. + +Diagnostic uses. Low cross-tool engagement signals tools are not connecting in the audience's journey; low pre-fill usage signals the pre-fill is not visible or not valued. + +--- + +## Cross-tool data flow audit + +Periodically audit the data flow. + +**The audit.** + +- Walk through critical journeys end-to-end. Does data actually flow? +- Verify identity threading works (logged-in user is recognized across tools). +- Verify context capture works (inputs in tool A appear in tool B as expected). +- Verify segment tagging works (quiz result tag triggers correct downstream sequences). +- Verify sequence-tool integration works (sequence links pre-fill correctly). + +**The drift.** Integrations break silently. Tool updates change data formats. Audit catches the drift. + +--- + +## Common data flow failures + +**No data flow.** Each tool isolated; identity and context lost between tools. + +**Identity threading broken.** Logged-in user not recognized across tools; same person treated as new visitor multiple times. + +**Context capture incomplete.** Tool A captures inputs but tool B does not access them. + +**Segment tag conflicts.** Different tools tag the same person differently; downstream routing inconsistent. + +**Pre-fill broken.** Sequence link includes parameters but the tool does not honor them; audience re-enters known information. + +**Privacy violations.** Cross-tool data flow happens without consent; audience surprised; trust damaged. + +**Stale data.** Audience's situation has changed but tools still use old captured data. + +--- + +## Methodology-level choices that stay in the public skill + +The continuity principle. Patterns A through D (identity, context, segment, sequence-tool integration). Conflict and source-of-truth. Privacy and consent. Anonymous-session continuity. Cross-tool data flow architecture. Cross-tool measurement. Audit cadence. Common failures. + +## Implementation choices that stay internal + +Specific data layer choices for the team's stack. Specific integration tooling. Specific consent flows and privacy disclosures. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md new file mode 100644 index 0000000..d3cb1a1 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md @@ -0,0 +1,190 @@ +# Entry-point architecture patterns + +How visitors land vs how they're routed. Common entry points and their routing. + +The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). Without entry-point architecture, every visitor goes through the same first experience regardless of where they came from. + +--- + +## The entry-routing principle + +Each entry point has expected segments and stages. The first action available at the entry point should match those expectations. + +**The win.** A visitor arrives via an ad about "B2B SaaS pricing." The landing page serves consideration-stage pricing content. The first available action is a pricing calculator and a demo CTA. The entry point's routing matches the visitor's likely intent. + +**The fail.** Same visitor arrives via the same ad. The landing page is the homepage. The visitor lands in awareness-stage content with no clear next step. The mismatch costs the conversion. + +The discipline. Each entry point's first experience matches the visitor's likely segment and stage. + +--- + +## Common entry points + +The entry points most growth programs work with. + +**Paid landing page.** Visitor arrives via paid ad (search, social, display). High intent; specific to the ad's promise. + +Expected segment: usually narrow (the ad targeted specific audience). +Expected stage: usually consideration or decision (paid traffic is rarely awareness-stage). +Routing: landing page should serve the ad's specific promise; next-step action should match consideration or decision stage. + +**Organic content page.** Visitor arrives via search or content discovery; awareness or research stage. + +Expected segment: variable (organic search may surface multiple audience types). +Expected stage: usually awareness or early consideration (research-driven). +Routing: content should serve the search intent; secondary CTAs offer movement toward consideration. + +**Direct or returning visitor.** Visitor arrives by typing URL or via bookmark; often returning. + +Expected segment: variable (depends on prior interactions). +Expected stage: variable (could be any stage). +Routing: homepage should provide multiple entry paths to different segments and stages; navigation matters more than single CTA. + +**Referral.** Visitor arrives via partner or word-of-mouth; warmer than paid. + +Expected segment: variable (depends on referral source). +Expected stage: usually consideration or decision (referrals indicate active interest). +Routing: page should match the referral context; next-step action should reflect the warmth (free trial, demo, talk to sales often work). + +**Social.** Visitor arrives via social post; awareness or interest. + +Expected segment: variable (depends on social audience). +Expected stage: usually awareness (social discovery is rarely buying intent). +Routing: page should serve the social post's promise; soft CTAs (follow, subscribe, learn more) often work better than hard sells. + +**Tool entry.** Visitor arrives via a calculator, quiz, or chatbot directly (often via shared link or specific tool URL). + +Expected segment: matches the tool's audience. +Expected stage: usually consideration (the tool is a consideration-stage artifact). +Routing: tool should serve its specific value; next-step actions should connect tool output to broader funnel. + +--- + +## Entry-point routing patterns + +How to route each entry point. + +**Pattern A: Direct match.** Entry point routes directly to a specific landing page and CTA. Simple; works when the entry point's segment and stage are well-defined. + +**Pattern B: Routing layer.** Entry point routes to a routing page that asks 1-2 questions and then sends to the matched destination. Useful when the entry point's segment is variable. + +**Pattern C: Personalized landing.** Entry point routes to a landing page that adapts based on visitor attributes (source, behavior, profile). Sophisticated; requires personalization infrastructure. + +**Pattern D: Quiz-as-router.** Entry point routes to a quiz that segments and recommends. Detail in `quiz-and-assessment-design`. + +The choice depends on entry-point variability and infrastructure. Most programs start with Pattern A and add complexity as data shows the need. + +--- + +## Entry-point and segment matching + +Each entry point likely surfaces specific segments. + +**The discipline.** For each entry point, document the expected segments. The first experience should serve those segments. + +**Worked example.** + +- Entry point: paid ad targeting "data analytics for SaaS." +- Expected segments: data analysts and data leaders at SaaS companies. +- Expected stage: consideration. +- Routing: landing page on data analytics for SaaS; calculator showing ROI; CTA to demo. + +The match is deliberate. Visitors arriving via this entry point get a first experience that fits their segment and stage. + +--- + +## Entry-point and stage matching + +The first experience should match the visitor's likely stage. + +**Common mismatches.** + +- Awareness-stage visitor lands on a hard-sell decision-stage page; bounces because not ready. +- Decision-stage visitor lands on awareness-stage content; bounces because oversold on what they already know. +- Consideration-stage visitor lands on either; serves the wrong intent. + +**The cure.** Match the entry point's expected stage to the page's stage. Awareness pages serve awareness traffic; decision pages serve decision traffic. + +--- + +## Multi-entry funnels + +When the same visitor arrives via different entry points across visits. + +**The pattern.** A visitor sees an ad on Tuesday (paid entry); reads a blog post on Wednesday (organic entry); types the URL on Thursday (direct entry). Each entry point may surface a different first experience. + +**Architecture implications.** + +- Personalization across visits requires identity threading. +- Nurture sequences may need to acknowledge prior visits. +- Cross-channel attribution becomes important. + +**The discipline.** Architecture should accommodate multi-entry without confusion. The visitor's progression through the funnel respects their cumulative interactions, not just the latest entry. + +--- + +## Entry-point measurement + +Track per-entry-point performance. + +**The metric.** Per entry point: visitors, segment composition, stage composition, conversion to next action. + +**Diagnostic uses.** + +- Entry points with low conversion: routing may be mismatched. +- Entry points with high conversion: investigate what is working; replicate to other entries. +- Entry points whose segment composition does not match expectations: the source may have shifted; review. + +--- + +## Entry-point and audience-segment audit + +Periodically audit entry-point routing. + +**The audit.** + +- For each entry point: what segments and stages are arriving? +- Does the first experience match those segments and stages? +- Is conversion at this entry point above or below baseline? + +**The drift.** Entry points decay as ad targeting shifts, content rankings change, partners evolve. Quarterly audit catches the drift. + +--- + +## Entry-point anti-patterns + +**The single-funnel-for-every-entry.** All visitors go through the same first experience regardless of entry. Routing not matching segments or stages. + +**The over-personalized-entry.** Entry routing so specific that maintenance is impossible; many entries route to landing pages that exist only for one entry source. + +**The mismatched-entry.** Entry expects one segment; landing page serves a different one. Conversion suffers. + +**The unmeasured-entry.** Per-entry data not tracked; routing decisions are guesswork. + +**The orphan-entry.** Entry point exists; no landing page or routing defined; visitors land somewhere generic. + +--- + +## Common entry-point failures + +**One landing page for everyone.** Different entry points get the same first experience; routing not matching variability. + +**Wrong stage routing.** Awareness traffic gets decision-stage CTAs; decision traffic gets awareness content. + +**Personalization without infrastructure.** Architecture designed for personalization that the team cannot actually implement. + +**Entry-point drift.** Entry sources shifted; routing not updated. + +**Single-tool entry.** Only one tool serves an entry point; if the tool fails, the entry has no recovery. + +**Entry-conversion attribution missing.** Cannot tell which entry points produce which downstream conversion. + +--- + +## Methodology-level choices that stay in the public skill + +The entry-routing principle. Common entry points (6 patterns). Entry-point routing patterns (4 patterns). Entry-point and segment matching. Entry-point and stage matching. Multi-entry funnels. Entry-point measurement. Audit cadence. Anti-patterns. Common failures. + +## Implementation choices that stay internal + +Specific entry points for specific programs. Specific routing logic per entry. Specific landing pages per entry. The team's audit calendars. These vary by team and program. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md new file mode 100644 index 0000000..22a62e8 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md @@ -0,0 +1,189 @@ +# Funnel iteration discipline + +When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. + +Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +--- + +## The compound-vs-reset distinction + +Refinement compounds. Redesign resets. + +**Refinement.** Targeted changes to specific tools, sequences, or transitions within the existing architecture. The architecture's bones stay; the muscles get stronger. + +**Redesign.** Overhaul of the architecture. Segments redefined; tool-to-funnel mapping changed; sequences rebuilt. The architecture restarts. + +**The discipline.** Refine continuously; redesign deliberately and rarely. Constant redesign prevents compounding; never iterating allows decay. + +--- + +## When to refine + +Five conditions that signal refinement is appropriate. + +**Specific tools are underperforming relative to baseline.** A calculator with declining conversion benefits from input adjustment, default updates, or methodology refinement. The architecture is fine; the tool needs attention. + +**Specific segments have lower conversion than peer segments.** A segment that converts at 4 percent while peer segments convert at 10 percent has a fixable architecture issue. Refine the segment's path. + +**Specific transitions in the funnel are producing drop-off.** The transition from quiz to recommended product page has high drop-off. Audit the transition; fix. + +**Sequence engagement is declining for specific cohorts.** Newer subscribers to a sequence engage less than older subscribers. The sequence may have decayed; refresh content. + +**Specific entry points are routing wrong segments.** A paid ad source has shifted; visitors arriving from it no longer match the segment the landing page serves. Adjust the routing. + +These are refinements. The architecture is sound; specific elements need attention. + +--- + +## When to redesign + +Four conditions that signal redesign is appropriate. + +**Audience composition has fundamentally shifted.** The brand pivots; the target audience changes; the segments are no longer accurate. The matrix needs redesign. + +**Product or service strategy has changed.** The brand offers a fundamentally different product line; the funnel that served the old products no longer fits. Redesign. + +**Competitive landscape has shifted significantly.** A new competitor reshapes the buying process; the funnel needs to respond. Redesign may follow. + +**Multiple refine cycles have not produced expected results.** The team has refined repeatedly; conversion has not moved. The issue may be architectural rather than tactical. Redesign worth considering. + +These are redesigns. The architecture's fundamentals need to change. + +--- + +## The continuous-redesign trap + +Teams that constantly redesign never benefit from architectural compounding. + +**The pattern.** Every quarter, the team rethinks the funnel. New segments; new tools; new sequences. Each redesign is partially built before the next redesign starts. + +**The signal.** Conversion does not improve over time. Each iteration starts over. Learning does not accumulate because the structure keeps changing. + +**The cost.** The team's investment dilutes across redesigns. Tools never reach maturity. Sequences never stabilize. + +**The cure.** Redesign infrequently. Refine continuously between redesigns. Set a "no major redesign for X months" discipline if needed. + +--- + +## The frozen-architecture trap + +Teams that never iterate watch their architecture decay. + +**The pattern.** The funnel was designed once; the team treats it as finished. No refinement; no redesign; no audit. + +**The signal.** Conversion declines slowly over months and years. Tools age; sequences go stale; segments shift. The architecture does not respond. + +**The cost.** The architecture's value erodes. Audiences move on; competitors improve; the brand falls behind. + +**The cure.** Set refinement cadences. Quarterly audit; targeted refinements based on data. Acknowledge that no architecture stays optimal forever. + +--- + +## The middle ground + +Refine continuously; redesign infrequently and deliberately. + +**Refinement cadence.** Monthly or quarterly. Targeted; data-driven; small enough to test in isolation. + +**Redesign cadence.** Annually at most. Often longer. Major triggers (audience pivot, product change, competitive shift) drive redesign rather than calendar. + +**The discipline.** Both rhythms running in parallel. Refinement maintains; redesign responds to fundamental change. + +--- + +## Refinement workflow + +How to iterate productively. + +**Step 1: Identify the gap.** Data-driven; specific to a tool, segment, transition, or sequence. + +**Step 2: Hypothesize the cause.** What might explain the gap? + +**Step 3: Design a treatment.** What change would address the hypothesis? + +**Step 4: Test if possible.** A/B test or before-after measurement when feasible. + +**Step 5: Validate.** Did the metric move? Did downstream metrics also benefit? + +**Step 6: Roll out or roll back.** Successful refinements stick; unsuccessful ones revert. + +The discipline. Each refinement is hypothesis-driven and validated. Random changes do not compound. + +--- + +## Redesign workflow + +How to redesign without resetting everything. + +**Step 1: Articulate why.** What has fundamentally changed that warrants redesign? + +**Step 2: Preserve what works.** Identify elements of the current architecture that are still appropriate. Do not throw away learning. + +**Step 3: Design the new architecture.** Segment matrix; entry-point routing; tool-to-funnel mapping; sequence architecture. Document everything. + +**Step 4: Plan migration.** How to transition existing audience and tools to the new architecture without losing momentum. + +**Step 5: Pilot before full rollout.** Test the new architecture with a subset of audience or one segment before full deployment. + +**Step 6: Migrate.** Roll out the new architecture; retire the old one. + +**Step 7: Monitor closely.** Architecture-level metrics in the first months show whether the redesign delivered. + +The discipline. Redesign is a project, not a flip of a switch. Plan it; pilot it; migrate; monitor. + +--- + +## The decay-driven redesign signal + +How to know decay has accumulated to redesign level. + +**Signals.** + +- Multiple refine cycles have not moved the metric. +- Segments no longer describe the audience accurately. +- Tools designed for one segment are being used by others (mapping has drifted). +- The architecture diagram no longer matches the actual experience visitors have. +- Quarterly audits surface the same issues quarter after quarter without fix. + +When these signals accumulate, refinement is not enough. Redesign is needed. + +--- + +## Iteration measurement + +How to know iterations are working. + +**The metric.** Architecture-level metrics improving over time. Cross-tool conversion rising; segment-level conversion rising; funnel-stage progression accelerating. + +**The trap.** Improving one metric while others decline. A refinement that lifts cross-tool conversion but tanks lead quality is not net positive. + +**The discipline.** Watch the portfolio of metrics, not individual ones. Refinement should improve the architecture's overall outcomes, not just one measure. + +--- + +## Common iteration failures + +**Continuous redesign.** Architecture never stabilizes; learning does not compound. + +**Frozen architecture.** Architecture never iterates; decay accumulates. + +**Random refinement.** Changes without hypothesis or testing; results are noise. + +**Refinement without measurement.** Cannot tell if changes are working. + +**Redesign without preserving learning.** Throws away what was working alongside what was not. + +**Redesign without migration plan.** Audience and tools left in transition; experience suffers. + +**Iteration without portfolio metrics.** Improving one metric while damaging others. + +--- + +## Methodology-level choices that stay in the public skill + +The compound-vs-reset distinction. When to refine (5 conditions). When to redesign (4 conditions). The continuous-redesign trap. The frozen-architecture trap. The middle ground. Refinement workflow. Redesign workflow. The decay-driven redesign signal. Iteration measurement. Common failures. + +## Implementation choices that stay internal + +Specific iteration calendars for the team. Specific refinement and redesign processes. Specific tooling for testing iterations. The team's iteration history and lessons. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md new file mode 100644 index 0000000..d23c914 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md @@ -0,0 +1,222 @@ +# Funnel measurement patterns + +Architecture-level vs tool-level metrics. What to measure, what is noise. + +Funnel measurement should reveal architecture quality, not just tool quality. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. + +--- + +## The architecture-vs-tool measurement distinction + +Two layers of measurement. + +**Tool-level metrics.** Each tool's individual performance (calculator conversion, quiz completion, lead-magnet downloads). Detail in each tool's skill. + +**Architecture-level metrics.** How the tools and sequences compose. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. + +**The discipline.** Measure both layers. Architecture-level metrics are often the missing measurement. + +--- + +## Architecture-level metric: Cross-tool conversion + +What percentage of audience that hits tool A then engages with tool B. + +**The metric.** Count the visitors who interact with tool A (calculator, quiz, lead magnet, etc.). Of those, how many subsequently interact with tool B? + +**Why it matters.** Cross-tool engagement signals whether the funnel is composing. High cross-tool conversion means the architecture is working; low cross-tool conversion means tools are silos. + +**Measurement methods.** + +- Identity-based tracking (same identified user across tools). +- Session-based tracking (same session sees multiple tools). +- Cohort analysis (cohorts entering through tool A and their downstream tool engagement). + +**Diagnostic uses.** + +- Low cross-tool conversion: tools may not be promoted to each other's audiences; transitions may be broken. +- Specific tool pairs underperforming: those transitions need design attention. + +--- + +## Architecture-level metric: Sequence-to-tool conversion + +What percentage of nurture sequence subscribers engage with downstream tools. + +**The metric.** Count subscribers in a sequence. Of those, how many click through to a tool the sequence promoted? + +**Why it matters.** Sequences should drive subscribers toward tools matched to their segment-and-stage. Low sequence-to-tool conversion signals that the sequences are not effectively bridging to tools. + +**Diagnostic uses.** + +- Specific sequence emails with low click-through: the email's tool promotion may not match the audience. +- Specific tools with low sequence-driven traffic: the sequences may not be promoting those tools enough. + +--- + +## Architecture-level metric: Segment-level downstream conversion + +Per-segment conversion to the program's main goal. + +**The metric.** For each segment in the matrix: what percentage convert to the main goal (trial, demo, purchase) within a defined timeframe? + +**Why it matters.** Different segments will convert at different rates; segments significantly underperforming relative to peers signal architecture issues. + +**Diagnostic uses.** + +- Segments with low downstream conversion: the funnel architecture for that segment may be broken or under-developed. +- Segments with high downstream conversion: investigate what is working; replicate to other segments. + +--- + +## Architecture-level metric: Funnel-stage progression + +What percentage of audience moves from awareness to consideration to decision over time. + +**The metric.** Track audience as they progress through stages. Awareness audience this month; what percentage are in consideration next month; what percentage in decision the following. + +**Why it matters.** The funnel's job is to progress audience through stages. Low progression signals the nurture sequences and tools are not advancing the relationship. + +**Diagnostic uses.** + +- Slow progression: sequences may be too educational without enough advancement; or the audience may be getting stuck. +- Fast progression but low conversion: progression without quality. + +--- + +## Tool-level metrics + +Each tool has its own metrics. Detail in each tool's skill. + +**Calculator.** Conversion rate per visitor; tier-2 (email gate) conversion; downstream conversion of calculator-sourced leads. + +**Quiz.** Completion rate; per-segment downstream conversion; recommendation click-through. + +**Lead magnet.** Download rate; sequence engagement; downstream conversion of magnet-sourced subscribers. + +**Multi-step form.** Completion rate; per-step drop-off; lead quality. + +**Chatbot.** Resolution rate per intent; escalation rate; downstream conversion. + +The tool-level metrics tell you whether each tool is doing its job. The architecture-level metrics tell you whether the tools are doing the funnel's job. + +--- + +## What is noise + +Metrics that look important but are not. + +**Total tool engagements.** Volume without context. A tool with 10000 engagements per month tells you nothing without conversion context. + +**Email open rate alone.** Open rate is a leading indicator at best; sequence-to-conversion is the metric that matters. + +**Time on page or session length.** Often correlates with confusion as much as engagement. + +**Bounce rate alone.** High bounce rate on awareness content may be normal; on decision content may signal a problem; aggregate bounce rate is noise. + +The discipline. Measure outcomes, not activity. Activity metrics are noise unless connected to outcome metrics. + +--- + +## Measurement granularity + +How granular to measure. + +**Per-tool measurement.** Standard. Each tool tracked. + +**Per-segment-per-tool measurement.** Measure each tool's performance per segment. Surfaces segment-specific tool issues. + +**Per-segment-per-stage measurement.** Measure progression and conversion per cell in the matrix. + +**Per-cohort measurement.** Track cohorts (groups arriving in the same period) over time. Surfaces evolution and decay. + +**The discipline.** Granularity matters when it informs decisions. Per-segment-per-stage is often where the diagnostic value lives; per-cohort surfaces decay. + +--- + +## Attribution + +Connecting outcomes to specific tools and sequences. + +**The challenge.** Audiences interact with multiple tools and sequences. Which one drove the conversion? + +**Approaches.** + +- **First-touch attribution.** Credit goes to the first interaction. +- **Last-touch attribution.** Credit goes to the most recent interaction. +- **Multi-touch attribution.** Credit distributed across interactions. +- **Position-based attribution.** Credit weighted by position (often U-shaped or W-shaped). + +**The honest framing.** Attribution is a model. No model is perfectly accurate. Choose a model deliberately; understand its biases; report consistently. + +--- + +## Measurement and architecture decisions + +How metrics inform architecture changes. + +**The pattern.** Metrics surface gaps; architecture decisions address them; subsequent metrics validate. + +**Examples.** + +- Cross-tool conversion low: redesign transitions; promote tool B in tool A's exit; measure improvement. +- Specific segment underperforming: review segment's funnel path; adjust tools or sequences; measure. +- Funnel-stage progression slow: review sequence design; add or refine; measure. + +**The discipline.** Metrics inform decisions; decisions are tested; results validated. Without measurement, architecture changes are guesswork. + +--- + +## Measurement instrumentation + +What needs to be in place. + +**Identity tracking.** Identified users tracked across tools. +**Event tracking.** Each tool interaction logged with event data. +**Funnel definition.** The funnel stages and segments defined in the analytics tool. +**Cohort capability.** Ability to define and track cohorts. +**Reporting.** Dashboards or reports that surface architecture-level metrics. + +**The discipline.** Instrumentation should be in place before launch, not added later. Retrofitting measurement is harder than building it in. + +--- + +## Measurement cadence + +How often to look at architecture-level metrics. + +**Weekly review.** For high-velocity programs or recently launched architectures. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable programs. Tracks trends and surfaces gradual decay. + +**Quarterly review.** Comprehensive architecture audit. Per-cell analysis; segment-level deep dive; funnel-stage progression. + +**Triggered review.** When tools change, when segments shift, when external factors (market, competition) change. + +--- + +## Common measurement failures + +**Tool-level only.** Architecture-level metrics not tracked; cannot diagnose composition issues. + +**Vanity metrics.** Volume metrics without conversion context. + +**No segment-level granularity.** Aggregate metrics hide segment-specific issues. + +**Attribution model not chosen.** Reports inconsistent because attribution is ad-hoc. + +**No cohort tracking.** Cannot see decay or evolution. + +**Metrics without action.** Metrics reviewed but no decisions follow. + +**Confounded data.** Multiple changes deployed without isolation; cannot attribute outcomes to changes. + +--- + +## Methodology-level choices that stay in the public skill + +The architecture-vs-tool measurement distinction. Architecture-level metrics (cross-tool, sequence-to-tool, segment-level, funnel-stage). Tool-level metrics (cross-reference). What is noise. Measurement granularity. Attribution approaches. Measurement and architecture decisions. Instrumentation requirements. Measurement cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific programs. Specific tooling for measurement. Specific attribution models. The team's reporting conventions. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md new file mode 100644 index 0000000..6469028 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md @@ -0,0 +1,256 @@ +# Nurture sequence architecture + +Per-segment, per-stage sequence variation. The matched sequence win. + +Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. Done well, sequences compound the brand's relationship with the audience; done poorly, sequences treat everyone the same and convert no one well. + +--- + +## The matched-sequence principle + +Each segment-and-stage cell warrants a sequence designed for that cell. Different cells get different sequences. + +**The win.** An SMB consideration-stage subscriber gets a 5-email sequence focused on SMB-relevant comparison content, ROI examples from similar SMB customers, and a soft demo invitation. The sequence reads as if written for them. + +**The fail (kitchen-sink sequence).** Every subscriber regardless of segment or stage gets the same 5-email sequence. The content is generic enough to send to all; specific enough for none. SMB subscribers see enterprise examples; enterprise subscribers see SMB examples; conversion uniformly low. + +The discipline. Sequences vary by segment and stage. The matrix from `audience-and-stage-segmentation` is the sequence design map. + +--- + +## Sequence variation by stage + +Stage-specific sequence patterns. + +**Awareness sequence.** + +- Goal: build relationship; deepen brand association with the topic. +- Content: educational, broad value, brand-building. +- Frequency: typically lower (weekly to bi-weekly); the audience is not in active research. +- Soft offers: subscribe to newsletter, follow on social, attend webinar. +- Hard offers: rare; awareness audiences are not buying yet. + +**Consideration sequence.** + +- Goal: move from "evaluating" to "selecting." +- Content: comparative, specific value, product-fit signals. +- Frequency: higher (every 3-7 days); audience is actively evaluating. +- Soft offers: see comparison guide, take quiz, calculator. +- Hard offers: demo, trial, talk to sales (toward end of sequence). + +**Decision sequence.** + +- Goal: commit; sign up; purchase. +- Content: confidence-building, risk-reversal, urgency cues, case studies of similar customers. +- Frequency: high (every 2-4 days); audience is close to deciding. +- Soft offers: rarely; mostly hard offers. +- Hard offers: trial, signup, talk to sales, custom quote. + +**Customer sequence (often missed).** + +- Goal: deepen success; expand and retain. +- Content: feature deep-dives, success stories from similar customers, community invitations. +- Frequency: ongoing; matches product cadence. +- Soft offers: attend events, refer others. +- Hard offers: upgrade, add-on, expansion. + +--- + +## Sequence variation by audience + +Audience-specific sequence patterns. + +**SMB audience.** + +- Tone: practical, fast-execution, peer-to-peer. +- Examples: SMB customers; focus on quick wins and resource constraints. +- Content depth: shorter, scannable, action-oriented. + +**Mid-market audience.** + +- Tone: strategic, considered, multi-stakeholder. +- Examples: mid-market customers; focus on team adoption and process change. +- Content depth: moderate; depth where it matters; summaries for executives. + +**Enterprise audience.** + +- Tone: rigorous, evidence-based, formal. +- Examples: enterprise customers; focus on security, scale, integration. +- Content depth: deep; white papers, technical documentation, case studies with metrics. + +**Solo or creator audience.** + +- Tone: personal, founder-to-founder. +- Examples: similar solo practitioners; focus on individual impact and time savings. +- Content depth: practical; templates and how-tos over strategy. + +--- + +## Sequence design discipline + +How to design each sequence. + +**Step 1: Define the goal.** What conversion does this sequence drive? Awareness to consideration; consideration to demo; demo to decision; decision to purchase. + +**Step 2: Define the audience.** Which segment-and-stage cell does this sequence serve? + +**Step 3: Outline the arc.** What is the email-by-email progression? Each email should have a purpose; cumulatively the arc moves the subscriber toward the goal. + +**Step 4: Match content to arc.** What specific content (template, case study, framework, demo invitation) fits each step? + +**Step 5: Define triggers and cadence.** What triggers the sequence (lead magnet download, demo request, behavior signal)? What is the spacing? + +**Step 6: Define the soft and hard offers.** Where do soft offers appear? Where do hard offers appear? At what point does the sequence make a direct ask? + +**Step 7: Define the exit.** When does the sequence end? Where do subscribers go after (newsletter, segment-specific stream, retired)? + +The output is a documented sequence ready to build and ship. + +--- + +## Sequence cadence + +How frequently to send. + +**Awareness cadence.** Weekly to bi-weekly typical. The audience is not in active research; over-sending feels intrusive. + +**Consideration cadence.** Every 3-7 days typical. The audience is actively evaluating; cadence matches their consideration pace. + +**Decision cadence.** Every 2-4 days typical. The audience is close to deciding; cadence reflects urgency. + +**Customer cadence.** Variable. Match product cadence and customer engagement patterns. + +The cadence-too-frequent risk. Daily sends can fatigue; unsubscribe rates climb. + +The cadence-too-infrequent risk. Weekly sends to consideration audiences can lose momentum; the audience moves on. + +--- + +## Sequence content sourcing + +Where the content for sequences comes from. + +**Repurposed content.** Existing blog posts, case studies, white papers can populate sequences. Cost-effective; benefits from existing content investments. + +**Sequence-original content.** Content written specifically for the sequence. More effort; can be highly tailored to the audience and arc. + +**Hybrid.** Most sequences mix repurposed and original. Original content for the key arc moments; repurposed content for supplementary value. + +The discipline. Sequence content should fit the sequence's audience and stage; off-fit content (even good content) weakens the sequence. + +--- + +## Sequence triggers + +What launches the sequence. + +**Trigger types.** + +- **Lead magnet download.** Most common trigger. +- **Calculator completion.** With segment data captured. +- **Quiz completion.** With segment matched to result. +- **Multi-step form submission.** Demo request, qualification. +- **Behavior signal.** Visited specific pages, viewed pricing, abandoned cart. +- **Manual addition.** Sales team adds a contact. + +**The trigger discipline.** The trigger informs which sequence the subscriber enters. A lead-magnet download for an awareness-stage resource enters the awareness sequence; a calculator completion with consideration-stage signals enters the consideration sequence. + +**Trigger-segment routing.** Multiple triggers can route to multiple sequences based on captured segment information. The trigger is one signal; segment is another. + +--- + +## Sequence intersection and routing + +When subscribers might enter multiple sequences. + +**The challenge.** A subscriber downloads two lead magnets in the same week. Each magnet has its own sequence. Should they enter both? + +**Approaches.** + +- **Override.** Latest trigger overrides; subscriber enters the latest sequence and exits prior ones. +- **Concatenate.** Subscriber completes the first sequence, then enters the next. +- **Pause.** Active sequence pauses other triggers; subscriber returns to queue after current sequence. +- **Multi-path.** Subscriber enters multiple sequences simultaneously (risk of frequency overload). + +The choice depends on subscriber experience and sequence design. Most programs benefit from override or pause patterns to avoid frequency overload. + +--- + +## Sequence and offer alignment + +The offers in the sequence must match the audience. + +**The principle.** A sequence for SMB consideration-stage subscribers should pitch SMB-appropriate offers. Pitching enterprise offers in this sequence wastes the audience signal. + +**Offer alignment failures.** + +- Magnet attracts SMB; sequence pitches enterprise. +- Awareness sequence pitches hard sales offers prematurely. +- Decision sequence pitches awareness content the subscriber outgrew. + +**The cure.** Sequence offers reflect the audience and stage the sequence serves. + +--- + +## Sequence measurement + +Per-sequence metrics. + +**Open rate.** Per email; per sequence overall. + +**Click-through rate.** Per email; per sequence. + +**Conversion to next step.** What percentage of subscribers in this sequence completed the desired conversion? + +**Unsubscribe rate.** Per email; per sequence. + +**Sequence-to-customer conversion.** What percentage of subscribers in this sequence eventually became customers? + +Diagnostic uses. Low open rates per email signal subject-line issues; low click-through signals content fit issues; high unsubscribe rates signal cadence or content problems. + +--- + +## Sequence maintenance + +Sequences decay. + +**What decays.** + +- Content references go stale (outdated case studies, retired products). +- Offers change (new products, new pricing, new programs). +- Audience composition shifts; sequence content no longer fits. +- Email deliverability changes; subject lines that worked stop working. + +**Maintenance cadence.** Quarterly review of every active sequence. Update content; refresh offers; verify links. + +**The drift indicator.** Sequence performance declining over time signals decay; specific cohorts (newer subscribers vs older) performing differently signals audience shift. + +--- + +## Common sequence failures + +**One sequence for everyone.** Kitchen-sink pattern; matches no segment specifically. + +**Sequence-trigger mismatch.** The trigger captured one segment; the sequence is designed for another. + +**Offer misalignment.** Sequence pitches offers that do not match the audience. + +**Cadence wrong for stage.** Awareness cadence on consideration audience; consideration cadence on awareness audience. + +**No trigger logic.** Subscribers enter the same default sequence regardless of how they were captured. + +**Sequence-orphan magnets.** Lead magnets without follow-up sequences; subscribers go cold. + +**Stale sequence content.** Sequence designed once; content no longer reflects the brand or product. + +**No sequence measurement.** Sequence performance unknown; maintenance is guesswork. + +--- + +## Methodology-level choices that stay in the public skill + +The matched-sequence principle. Sequence variation by stage (4 stages). Sequence variation by audience (4 audiences). Sequence design discipline (7 steps). Sequence cadence. Sequence content sourcing. Sequence triggers. Sequence intersection and routing (4 approaches). Sequence and offer alignment. Sequence measurement. Sequence maintenance. Common failures. + +## Implementation choices that stay internal + +Specific sequences for specific segments. Specific email content in brand voice. Specific tooling for sequence automation and measurement. The team's cadence baselines. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md new file mode 100644 index 0000000..61de4bf --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md @@ -0,0 +1,225 @@ +# Tool-to-funnel mapping + +Which tools serve which entry points and segments. Each tool in the growth toolkit has a place in the funnel architecture; the mapping makes the place explicit. + +Without explicit mapping, tools end up serving everyone (and serving no one well) or getting deployed where they do not fit. With explicit mapping, each tool serves the segments where it adds the most value. + +--- + +## The mapping principle + +Each tool serves specific segments at specific stages from specific entry points. The mapping is documented, not implicit. + +**The win.** A team's calculator is mapped to consideration-stage SMB and mid-market visitors arriving via organic content. The calculator's design (inputs, defaults, methodology) reflects this segment. Other segments do not see the calculator featured prominently; they see tools matched to their segment. + +**The fail.** A team's calculator is featured on every page for every visitor. The calculator's design is generic to serve everyone. SMB visitors see enterprise inputs; enterprise visitors see SMB defaults. The calculator serves nobody well. + +The discipline. Each tool has a defined place. The architecture documents which segments and stages and entry points the tool serves. + +--- + +## Common tool-to-funnel mappings + +How each growth tool typically maps. + +**Lead magnet.** Often serves awareness-to-consideration transition. + +- Audience: awareness-stage visitors who would benefit from a focused resource. +- Entry points: blog posts, content discovery, paid ads on educational topics. +- Position in funnel: captures email; routes to nurture sequence that bridges to consideration. +- Detail in `lead-magnet-design`. + +**Calculator.** Often serves consideration stage. + +- Audience: visitors evaluating options who need to defend a specific decision. +- Entry points: pricing pages, comparison content, paid ads on solution-evaluation. +- Position in funnel: provides defensible numeric output; routes to demo or trial CTA. +- Detail in `calculator-design`. + +**Quiz.** Variable depending on design. + +- Awareness quizzes: content marketing, brand-building. Captures email; routes to broad nurture sequence. +- Consideration quizzes: product matching, fit assessment. Captures email; routes to product-specific sequence. +- Decision quizzes: plan selection, configuration. Captures email and routes to specific sales motion or signup. +- Detail in `quiz-and-assessment-design`. + +**Multi-step form.** Often serves decision or qualification stage. + +- Audience: visitors with high intent who need to provide structured information. +- Entry points: demo CTAs, talk-to-sales pages, application flows. +- Position in funnel: captures qualified intent; routes to sales or to next-stage automation. +- Detail in `multi-step-form-design`. + +**Chatbot.** Cross-cutting; can serve any stage with intent recognition routing. + +- Audience: any visitor who has questions the bot can handle. +- Entry points: any page where conversation might add value. +- Position in funnel: handles in-conversation routing; escalates to humans for complex cases. +- Detail in `chatbot-flow-design`. + +--- + +## Mapping examples by audience segment + +How tools map for specific segments. + +**Solo founder, awareness stage.** + +- Lead magnet: practical template they can use today. +- Quiz (optional): "what stage of growth are you in" with matched recommendations. +- Chatbot: yes, for FAQ; lightweight routing. +- Calculator, multi-step form: probably not at this stage. + +**SMB team, consideration stage.** + +- Calculator: ROI estimate matched to SMB context. +- Lead magnet: comparison guide or worked example. +- Multi-step form: demo request capture. +- Chatbot: yes, for product-specific questions. +- Quiz (optional): plan recommendation. + +**Mid-market team, consideration-to-decision.** + +- Calculator: ROI estimate with mid-market context. +- Multi-step form: demo request with qualification. +- Chatbot: yes, with escalation to sales for complex questions. +- Lead magnet (optional): white paper or case study. +- Quiz: probably not (mid-market buyers often skip quizzes). + +**Enterprise, decision stage.** + +- Multi-step form: enterprise demo request with detailed qualification. +- Chatbot: lightweight; escalation-heavy. +- Custom calculator: with enterprise-specific inputs and ROI factors. +- Lead magnet, quiz: usually not (enterprise buyers expect direct human attention). + +The mapping is segment-aware. Tools that fit one segment may not fit another. + +--- + +## Mapping examples by stage + +How tools map for specific stages. + +**Awareness stage.** + +- Lead magnets prominent. Quizzes can serve. Calculators less common (consideration is when calculators earn their value). Chatbots support. +- Goal: capture awareness-stage email; route to nurture sequence. + +**Consideration stage.** + +- Calculators central. Quizzes useful for product matching. Lead magnets can deepen value. Chatbots support specific questions. +- Goal: convert consideration into qualified intent; route to demo or trial. + +**Decision stage.** + +- Multi-step forms central (demo requests, qualified intent capture). Calculators support specific decisions. Chatbots route to sales. +- Goal: convert decision-stage intent into commitment. + +**Customer stage.** + +- Onboarding flows (which can use multi-step forms). Chatbots for support. Lead magnets and quizzes less central; replaced by in-product education. +- Goal: deepen customer success; expand and retain. + +--- + +## Mapping discipline + +How to make the mapping rigorous. + +**Discipline 1: Document the mapping.** Write down which tools serve which segments and stages. The document is the architecture's reference. + +**Discipline 2: Match tool design to mapping.** A tool serving SMB should have SMB-relevant inputs and defaults; a tool serving enterprise should reflect enterprise context. + +**Discipline 3: Promote tools where they fit.** Show calculators on consideration-stage pages; show lead magnets on awareness-stage pages. Generic tool placement on every page dilutes their value. + +**Discipline 4: Retire tools that do not fit.** A tool that does not have a mapping is decorative. Either find its place or retire it. + +**Discipline 5: Audit the mapping quarterly.** Mappings decay as audience composition shifts. Quarterly review catches drift. + +--- + +## Multi-tool segments + +Some segments use multiple tools across their journey. + +**The pattern.** A consideration-stage SMB visitor uses a lead magnet (awareness arrival), a calculator (consideration depth), then a multi-step demo form (decision intent). Three tools across the journey. + +**Architecture implications.** + +- Each tool serves a specific moment in the visitor's journey. +- Cross-tool data flow lets each tool benefit from earlier interactions. +- Tools should not duplicate each other's value. + +**The discipline.** Tools complement, not duplicate. Each tool earns its place in the segment's journey. + +--- + +## Tool overlap and choice + +When multiple tools could serve the same segment-and-stage cell. + +**The pattern.** A team has both a calculator and a quiz that could serve consideration-stage SMB. + +**The decision.** Choose the tool that serves the segment best, or use both with clear differentiation. + +- Calculator: when the consideration involves a specific calculation (ROI, savings, sizing). +- Quiz: when the consideration involves categorization or product matching. +- Both: when the segment benefits from both, with clear positioning of when each helps. + +The discipline. Avoid having multiple tools competing for the same segment without clear differentiation. Audiences pick the most prominent; the others underperform. + +--- + +## Tool gaps + +When the mapping reveals gaps. + +**The pattern.** The architecture documents which tools serve which segments. Some cells in the matrix have no tool; the audience there has no relevant tool to engage with. + +**The decision.** Either build a tool to fill the gap, or accept that some cells use generic content rather than tools. + +- Build when the segment is high-value and the tool would meaningfully improve conversion. +- Accept when the segment is small or the tool would not earn its build cost. + +The architecture surfaces gaps; the team decides what to do about them. + +--- + +## Tool-mapping audit + +Periodically audit which tools serve which segments and how well. + +**The audit.** + +- For each tool: which segments does it currently serve? Which segments does it actually attract? +- For each cell in the matrix: which tools are mapped to it? Are they performing? +- Are any tools serving segments outside their intended mapping (drift)? + +**The drift indicators.** Tool conversion drops; tool's audience composition changes; tool gets traffic from segments it was not designed for. + +--- + +## Common mapping failures + +**No mapping.** Tools deployed without explicit segment-and-stage assignment. + +**Mismatched mapping.** Tool serving segments it was not designed for; tool's design does not fit the audience. + +**Decorative mapping.** Mapping documented but not enforced; tool appears everywhere regardless of mapping. + +**Stale mapping.** Mapping designed once; not updated as tools or audiences evolved. + +**Tool overlap without differentiation.** Multiple tools competing for the same segment; audience splits; none performs well. + +**Mapping gaps unaddressed.** Cells in the matrix have no tool support; the architecture has holes. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle. Common tool-to-funnel mappings (5 tools). Mapping examples by audience segment (4 examples). Mapping examples by stage (4 examples). Mapping discipline (5 disciplines). Multi-tool segments. Tool overlap and choice. Tool gaps. Tool-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific tool-to-segment mappings for specific programs. Specific tool placement decisions on specific pages. The team's audit calendars. These vary by team and program. diff --git a/dist/pi/.agents/skills/incident-response/SKILL.md b/dist/pi/.agents/skills/incident-response/SKILL.md new file mode 100644 index 0000000..f484749 --- /dev/null +++ b/dist/pi/.agents/skills/incident-response/SKILL.md @@ -0,0 +1,260 @@ +--- +name: incident-response +description: "Manage active production incidents through detection, triage, mitigation, communication, and resolution with structured roles and decision-making. Use this skill whenever the user has an active incident, a production issue, a service outage, a security incident, or needs to plan incident response procedures. Triggers on incident response, production incident, outage, service down, site down, P0, P1, severity, downtime, on-call, incident commander, status page, postmortem prep. Also triggers when something is actively broken in production and the user is figuring out what to do." +category: operations +catalog_summary: "Incident triage, comms, mitigation, escalation" +display_order: 2 +--- + +# Incident Response + +Manage active production incidents from detection to resolution. Stack-agnostic. Tool-agnostic. + +This skill is for active incidents and incident process. For after-the-fact analysis, use `after-action-report`. For planned launches, use `launch-runbook`. + +--- + +## When to use + +- An active incident is happening +- Building incident response procedures +- Defining severity levels +- Setting up on-call rotations +- Training a team on incident response + +## When NOT to use + +- Post-incident retrospective (use `after-action-report`) +- Planned launches (use `launch-runbook`) +- Pre-launch issue triage (use `qa-testing`) + +--- + +## Required inputs + +- Awareness of the incident (alert, customer report, internal observation) +- Access to production systems and monitoring +- Roles and authorities clearly defined +- Communication channels operational + +--- + +## The framework: 5 phases + +### 1. Detection + +How the incident becomes known. + +**Detection sources:** + +- Automated alerts (monitoring, SLO violations, error rate spikes) +- Customer reports (support tickets, social media, status page subscribers) +- Internal observation (engineer notices something off) +- Third-party (security researchers, partners) + +**On detection:** + +- Acknowledge within target time (typically 5 to 15 minutes for critical) +- Assess severity (see severity rubric below) +- Page the on-call if not already paged +- Open the incident channel + +### 2. Triage + +Establish severity and impact. + +**Severity rubric:** + +| Severity | Definition | Response | +|---|---|---| +| SEV-1 (Critical) | Major customer-facing functionality broken. Data integrity at risk. Security breach. | All-hands. Incident commander. Active war room. Public communication required. | +| SEV-2 (Major) | Significant degradation. Some customers affected. Revenue impact. | Incident commander assigned. Active response. Internal communication. May or may not need public communication. | +| SEV-3 (Minor) | Limited impact. Workaround available. Affecting a small group of users. | Standard on-call response. Single owner. | +| SEV-4 (Low) | Cosmetic, edge-case, or low-frequency. No urgent action needed. | Tracked as bug. Addressed in normal queue. | + +Severity can change. Re-evaluate as more info emerges. + +### 3. Mitigation + +Stop the bleeding before fixing the cause. + +**Mitigation patterns (faster than full fix):** + +- **Rollback** (revert recent deploy) +- **Feature flag off** (disable the broken feature without deploy) +- **Failover** (route to healthy replica or region) +- **Scale up** (more capacity to absorb the load) +- **Throttle** (reject some traffic to protect the rest) +- **Graceful degradation** (turn off non-essential features to keep core functional) +- **Maintenance mode** (last resort, blocks all users) + +**Mitigation principle:** Stop user impact first. Cause analysis second. + +### 4. Communication + +Three audiences during an incident: + +**Internal team:** +- Real-time updates in incident channel +- Cadence: every 15 minutes minimum during active incident +- Format: timestamped status updates with what we know, what we're doing, ETA + +**Internal stakeholders:** +- Higher-level updates to broader org +- Cadence: every 30 to 60 minutes +- Format: business-impact framing, not technical detail + +**External / customers:** +- Status page updates +- Cadence: every 30 minutes minimum during active incident +- Format: plain language, no blame, what users are experiencing, what to expect + +**Communication principles:** +- Acknowledge before you have answers ("We're aware and investigating") +- Update on schedule even if no progress ("Still investigating, no new information") +- Never speculate publicly about cause +- Confirm resolution explicitly when restored + +### 5. Resolution + +Verified fix, customers restored, incident closed. + +**Resolution criteria:** + +- Mitigation in place and verified +- Root cause identified (or explicitly deferred to AAR) +- All affected systems back to normal +- Customers can resume normal use +- Final status update posted (internal and external) +- Incident channel can be closed (or archived for AAR) + +After closure: +- Schedule AAR within 1 to 2 weeks +- Capture initial timeline while memories are fresh +- Track follow-up action items + +--- + +## Roles during an incident + +| Role | Responsibility | +|---|---| +| Incident commander (IC) | Owns the response. Calls decisions. Assigns work. Not necessarily the most technical person; needs to coordinate. | +| Communications lead | Owns internal and external messaging. Reduces IC's communication burden. | +| Operations lead | Drives the technical investigation and mitigation. Often the most senior on-call engineer. | +| Scribe | Captures the timeline as the incident unfolds. Critical for AAR. | +| Subject matter experts | Pulled in as needed. Service owners, database experts, security experts. | + +For small teams or low-severity incidents, one person can hold multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Decision-making during an incident + +**The IC's authority:** + +- Call rollback or other mitigations +- Pull additional people in +- Escalate severity +- Make the call when unclear options exist + +**Non-decisions to avoid:** + +- "Let's wait and see" when mitigations are available and impact is occurring +- Discussing root cause while users are actively impacted (mitigate first) +- Premature resolution announcements before verification +- Death-by-committee (pull in lots of people, no one decides) + +When in doubt: act. A wrong action that can be rolled back beats inaction while users suffer. + +--- + +## Status page communication patterns + +**Initial:** +> "We are investigating reports of [issue]. Updates to follow." + +**Identified:** +> "We have identified the issue affecting [scope]. Engineers are working on a fix. Next update by [time]." + +**Monitoring:** +> "A fix has been applied. We are monitoring to confirm resolution. Next update by [time]." + +**Resolved:** +> "This incident has been resolved. Service has been restored. A full incident report will be posted within [timeframe]." + +Patterns to avoid: + +- Vague language ("experiencing some issues" - what kind?) +- Missing affected scope ("login is down" - everywhere or just one region?) +- Missing time commitments +- "Should be resolved soon" without verification +- Using "back up" before verification + +--- + +## Workflow + +1. **Acknowledge.** First responder acknowledges within target time. +2. **Assess severity.** Use the rubric. Open the appropriate response channel. +3. **Assign roles.** IC, comms, ops at minimum. +4. **Communicate.** Initial status update. Internal channel active. +5. **Investigate.** Logs, metrics, recent changes. The four most common causes: a recent deploy, a configuration change, a third-party dependency change, a load spike. +6. **Mitigate.** Stop the bleeding. Don't wait for full root cause. +7. **Verify mitigation.** Don't trust dashboards alone; test the user flow. +8. **Communicate resolution.** Internal and external. +9. **Close incident.** Final timeline noted. Action items tracked. +10. **Schedule AAR.** Within 1 to 2 weeks. + +--- + +## Failure patterns + +- **No clear IC.** Multiple people debugging in parallel, no coordination. Slower to mitigate, easier to make conflicting changes. +- **Skipping mitigation, going straight to root cause.** Users keep suffering while engineers debug. +- **Premature "all clear."** Announcing resolution before verification. +- **Communication silence.** Users don't know if anyone is working on it. +- **Status updates too vague.** "We're working on it" with no detail. +- **Speculating publicly about cause.** Often wrong, always damaging trust. +- **Pulling in too many people.** Coordination overhead exceeds value. +- **No scribe.** The timeline gets lost. AAR has to reconstruct from chat logs. +- **Skipping AAR for "minor" incidents.** Patterns get missed. Lessons get re-learned. +- **Blame culture.** People hide mistakes, incidents take longer. + +--- + +## Output format + +During an active incident: incident channel updates and status page updates as per the framework above. + +After incident close: a brief incident summary feeding into the AAR. + +```markdown +# Incident: [Brief title] + +**Date:** [YYYY-MM-DD] +**Severity:** [SEV-1 / 2 / 3 / 4] +**Duration:** [Detection to resolution] +**Customer impact:** [Who, how many, how] + +## Summary +[1 to 2 paragraphs] + +## Timeline +[Timestamped events] + +## Mitigation +[What was done] + +## Action items +[Follow-ups, with owners] + +## AAR scheduled for +[Date] +``` + +--- + +## Reference files + +- [`references/incident-playbook.md`](references/incident-playbook.md) - Severity definitions, roles, status page templates, decision rubrics. diff --git a/dist/pi/.agents/skills/incident-response/references/incident-playbook.md b/dist/pi/.agents/skills/incident-response/references/incident-playbook.md new file mode 100644 index 0000000..b960f45 --- /dev/null +++ b/dist/pi/.agents/skills/incident-response/references/incident-playbook.md @@ -0,0 +1,280 @@ +# Incident Playbook + +The reference document during an incident. Severity definitions, role responsibilities, communication templates, and decision rubrics. + +--- + +## Severity rubric + +### SEV-1: Critical + +**Definition:** +- Major customer-facing functionality completely broken +- Data loss or data integrity at risk +- Active security breach or vulnerability being exploited +- Significant revenue impact ongoing + +**Response:** +- All-hands response activated +- Incident commander assigned (within 10 minutes of detection) +- War room (video call) opened +- Public status page updated immediately +- Executive notification within 15 minutes +- Customer-facing communication within 30 minutes + +**Acknowledgment SLA:** 5 minutes +**Update cadence:** Every 15 minutes +**Resolution target:** As fast as humanly possible + +### SEV-2: Major + +**Definition:** +- Significant degradation affecting many users +- Important feature unavailable +- Performance severely degraded +- Revenue impact, but limited + +**Response:** +- Incident commander assigned (within 30 minutes) +- Active investigation in incident channel +- Status page updated +- Internal communication to broader org +- Public communication if customer-facing + +**Acknowledgment SLA:** 15 minutes +**Update cadence:** Every 30 minutes +**Resolution target:** Within hours + +### SEV-3: Minor + +**Definition:** +- Limited impact (specific feature, specific user segment) +- Workaround available +- No revenue impact, or minor + +**Response:** +- Single owner assigned +- Standard on-call response +- No status page update unless customer-facing +- No public communication unless trending + +**Acknowledgment SLA:** 1 hour +**Update cadence:** As progress dictates +**Resolution target:** Within a day + +### SEV-4: Low + +**Definition:** +- Cosmetic issue +- Edge case affecting few users +- No customer impact + +**Response:** +- Track as bug, not incident +- Address in normal queue + +**Acknowledgment SLA:** Next business day +**Resolution target:** As prioritized + +--- + +## Roles + +### Incident Commander (IC) + +**Responsibilities:** +- Owns the response +- Makes decisions when options exist +- Assigns work to others +- Decides when to escalate severity +- Decides when to declare resolution +- Coordinates without doing technical work themselves + +**NOT the IC's job:** +- Doing the actual debugging +- Speculating about cause publicly +- Writing status page updates (delegates to comms lead) + +**Selection criteria:** Calm under pressure, good at coordination, clear communicator. Does not need to be the most senior or most technical. + +### Communications Lead + +**Responsibilities:** +- Posts internal updates on schedule +- Drafts status page updates +- Coordinates with customer support +- Drafts executive notifications +- Manages external messaging + +**Removes:** Communication burden from IC and ops lead. + +### Operations Lead + +**Responsibilities:** +- Drives the technical investigation +- Identifies the cause +- Identifies and applies mitigations +- Coordinates with subject matter experts +- Verifies fixes + +### Scribe + +**Responsibilities:** +- Captures the timeline as the incident unfolds +- Records decisions and rationale +- Records actions taken +- Provides material for the AAR + +**Often filled by:** A junior engineer (good learning experience), someone not in the active investigation, or anyone tasked specifically with note-taking. + +### Subject Matter Experts (SMEs) + +Pulled in as needed. Service owners, database experts, security experts, third-party vendors. Pulled by IC, not self-deploying. + +--- + +## Status page templates + +### SEV-1 / SEV-2 initial + +> "We are currently investigating reports of [user-facing description of impact]. Affected users may experience [specific symptoms]. We will update by [time, typically +30 minutes]." + +### Identified + +> "We have identified the cause of the issue affecting [scope]. Engineers are deploying a fix. Next update by [time]." + +### Monitoring + +> "A fix has been applied. We are monitoring to confirm full resolution. Next update by [time]." + +### Resolved + +> "This incident has been resolved. All services have returned to normal. A full incident report will be posted within [typically 1 week]. Thank you for your patience." + +### Patterns to avoid + +| Avoid | Why | Use instead | +|---|---|---| +| "Some users may be experiencing issues" | Vague | "Users in [region] may experience [specific symptom]" | +| "We are working on it" | Empty | "Engineers are investigating [hypothesis or symptom]" | +| "Should be resolved shortly" | Speculative | "Next update by [specific time]" | +| "We apologize for the inconvenience" | Hollow | Acknowledge specifically, then state action | +| Technical jargon | Excludes users | Plain language describing user experience | +| Blame language | "Our database vendor failed" | Focus on user impact and our response | + +--- + +## Decision rubrics + +### Should we roll back? + +Roll back if: +- A recent deploy correlates with the start of the incident +- Rollback can be completed safely +- The risk of leaving the broken state exceeds the risk of rollback + +Don't roll back if: +- The incident clearly predates the recent deploy +- Rollback would cause data loss or worse impact +- A targeted fix is available and faster + +When unsure: roll back. Recovery from rollback is usually cheaper than continued debugging in a broken state. + +### Should we declare SEV-1? + +Declare SEV-1 if any are true: +- Most users cannot use the core product +- Revenue is being lost at significant rate +- Data integrity is at risk +- A security breach is happening +- Senior leadership awareness is required + +When unsure between SEV-1 and SEV-2: start with SEV-1. Easier to de-escalate than to scale up. + +### Should we communicate publicly? + +Communicate publicly if any are true: +- Customers are experiencing impact and will notice +- Customer support is receiving inquiries +- The incident is visible externally (status page, social media chatter) +- Regulatory notification may be required (data breach, certain financial systems) + +Don't communicate publicly if: +- Impact is invisible to users +- Confidence is high that it will be resolved before users notice (but lean toward communication) + +When unsure: communicate. Silence on the status page is worse than a brief acknowledgment. + +### Should we escalate? + +Escalate to senior leadership if: +- Severity has reached SEV-1 +- Resolution is taking longer than expected at SEV-2 +- Decisions are needed that exceed the IC's authority +- Reputational risk is material + +--- + +## On-call rotation principles + +A healthy on-call: + +- **Rotates regularly.** Same person on call indefinitely is unsustainable. +- **Has a clear primary and secondary.** Backup if primary is unavailable. +- **Has documented runbooks.** On-call is not pop quiz. +- **Has acknowledgment SLAs that match severity.** A 1-hour SLA on SEV-1 is too slow. +- **Is paid or compensated** in some form. Time on-call has cost. +- **Includes a hand-off ritual.** Outgoing on-call briefs incoming on open issues, recent deploys, hot spots. + +Anti-patterns: + +- One person who is "always on" because they know the system best +- On-call without monitoring (you can only respond to what you know) +- On-call who lacks production access (cannot mitigate) +- No primary/backup, just one person + +--- + +## Common mitigation patterns + +| Symptom | Try first | +|---|---| +| Errors after recent deploy | Roll back the deploy | +| Errors with no recent deploy | Check third-party dependencies, recent config changes | +| Database errors | Check connection pool, recent query changes, capacity | +| Latency spike | Check load, capacity, slow downstream | +| Specific feature broken | Feature flag off if available | +| Security incident | Isolate affected systems, rotate credentials, preserve logs | +| Data integrity issue | Stop writes, snapshot, investigate before continuing | + +When unsure of cause but mitigation is available: mitigate. Investigate cause separately. + +--- + +## After the incident + +Once resolved: + +1. Final status page update (resolved) +2. Final internal update +3. Capture initial timeline (the scribe's notes) +4. Identify obvious follow-up action items, file tickets +5. Schedule AAR within 1 to 2 weeks +6. Hand off any monitoring to normal operations + +In the next 24 to 48 hours, while memory is fresh: + +- Each participant writes their own brief account of what they observed and did +- These individual accounts become primary source material for the AAR +- This avoids reconstruction errors that come from trying to piece together what happened weeks later + +--- + +## Anti-patterns to call out + +- **Hero culture.** One person stays up all night to fix it; gets praised. Real lesson: the system is too brittle, and the team has too little redundancy. +- **Blame in retrospectives.** "Whose fault was this?" produces hidden mistakes next time. +- **Skipping AARs for "minor" incidents.** The minor incidents are often the patterns that predict major ones. +- **Action items that never close.** Action items get filed, never actioned. The same incident recurs. +- **Status pages updated only at start and end.** "Updating every 30 minutes" with the same content is still better than silence. +- **Investigating root cause while users are impacted.** Mitigate first. diff --git a/dist/pi/.agents/skills/information-architecture/SKILL.md b/dist/pi/.agents/skills/information-architecture/SKILL.md new file mode 100644 index 0000000..b77d8a7 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/SKILL.md @@ -0,0 +1,254 @@ +--- +name: information-architecture +description: "Design the structure of a website or product including sitemap, navigation, URL structure, content types, taxonomy, and labeling. Use this skill whenever the user asks to plan a sitemap, design navigation, structure URLs, define content types, build taxonomies, design site search, or organize content at the system level. Triggers on sitemap, site structure, navigation, IA, information architecture, URL structure, content types, taxonomy, categorization, breadcrumbs, hub pages, faceted navigation, site search, labeling. Also triggers when content is being created without a structural plan, or when an existing site's structure is being audited or restructured." +category: strategy-and-discovery +catalog_summary: "Sitemap, navigation, URL structure, content types, taxonomy" +display_order: 4 +--- + +# Information Architecture + +Design the structure that holds the content. Stack-agnostic. Applies to marketing sites, product surfaces, knowledge bases, e-commerce, and editorial content. + +A well-designed IA makes the rest of the project easier. A poorly-designed IA forces every downstream decision to fight the structure. + +--- + +## When to use + +- Designing a new site or major section from scratch +- Restructuring an existing site +- Adding a new content type or category +- Designing site navigation or menu systems +- Defining URL structure and slug patterns +- Building taxonomies or tag systems +- Auditing an existing IA for problems + +## When NOT to use + +- Single-page design (use `design-standards`) +- Content production (use `content-and-copy`) +- SEO-driven content planning (use `seo-keyword`) +- Initial brand and audience discovery (use `brand-discovery`) + +--- + +## Required inputs + +- The site or product scope +- The audience and what they're trying to do +- The content that exists or is planned +- Any constraints (parent IA, regulatory, technical) + +If audience is unclear, run `brand-discovery` first. If content scope is unclear, run `content-strategy` first. + +--- + +## The framework: 6 layers + +Information architecture has six layers. Each builds on the one below. + +### 1. Mental models + +Before structure, understand how the audience thinks about the domain. + +- What concepts do they group together naturally? +- What words do they use? (Often different from what the company uses.) +- What is the dominant frame of reference? (By task? By role? By topic? By time?) +- What do they expect to find where, based on conventions in similar products? + +**Methods:** + +- **Card sorting** (open or closed): Give the audience the content items, ask them to group them. Open card sorts surface natural groupings. Closed card sorts validate proposed groupings. +- **Tree testing:** Give a proposed structure, ask users to find specific items. Surfaces where the structure breaks down. +- **First-click testing:** Given a goal, where do users click first? If first clicks are wrong, the labels and structure are wrong. + +### 2. Sitemap + +The map of all pages and how they relate. + +**Sitemap deliverables:** + +- A hierarchy diagram showing parent-child relationships +- Indication of page types (static, dynamic, listing, detail) +- Cross-references showing how pages relate beyond the hierarchy +- Sometimes a separate user-flow overlay for key journeys + +**Sitemap types:** + +- **Hub-and-spoke** (cornerstone content + supporting content): Common for content marketing +- **Tree** (strict hierarchy, every page has one parent): Common for product documentation +- **Faceted** (content lives in many overlapping categories): Common for e-commerce +- **Flat** (everything reachable from the home): Common for small sites + +Most sites blend types. Pick the dominant pattern and document the exceptions. + +### 3. URL structure + +URLs are part of the IA. They are user-facing, indexed by search engines, and shape how content is referenced. + +**URL principles:** + +- Reflect the content hierarchy +- Lowercase, hyphen-separated +- Predictable (same pattern across same content type) +- Stable (URLs don't change without redirects) +- Short (under 60 characters where possible) +- Descriptive (slug indicates the content) +- Free of dates unless time-bound +- Free of session IDs and tracking parameters in canonical form + +**Common patterns:** + +``` +/ home +/[section] section landing +/[section]/[subsection] subsection landing +/[section]/[subsection]/[item] detail page +/blog blog index +/blog/[slug] blog post +/blog/category/[category] category index +/blog/tag/[tag] tag index +/products product catalog +/products/[category] category page +/products/[category]/[product] product detail +``` + +Pick a pattern and stick to it. Inconsistent URL patterns confuse users, crawlers, and analytics. + +### 4. Navigation + +The chrome that gets users where they need to go. + +**Primary navigation:** + +- The top-level structure of the site +- Should reflect what the audience cares about, not what the org chart looks like +- 5 to 7 items maximum (more becomes cognitively heavy) +- Each label is recognizable in 2 to 3 words +- Order matters (left/first gets the most attention) + +**Secondary navigation:** + +- Within-section navigation +- Often shown as sidebars, sub-menus, or in-page tabs +- Supports the primary nav, doesn't duplicate it + +**Utility navigation:** + +- Account, search, login, support +- Visually subordinate to primary nav +- Often top-right (LTR languages) + +**Breadcrumbs:** + +- For nested hierarchies (3+ levels deep) +- Always linked except the current page +- Match the URL hierarchy or the conceptual hierarchy +- Marked up with BreadcrumbList schema + +**Footer navigation:** + +- Comprehensive; sometimes includes everything +- Organized by category for findability +- Includes secondary content (privacy, terms, contact) + +### 5. Taxonomy and metadata + +The classification system applied to content. + +**Categories:** + +- A small, controlled list (typically 5 to 15) +- Mutually exclusive ideal (one item, one category) +- Used for structural navigation + +**Tags:** + +- A larger, often growing list (50+) +- Multi-assignment (one item, many tags) +- Used for cross-cutting connections, related-content, and long-tail discovery + +**Metadata fields:** + +- Author, date, content type, audience segment +- Whatever is useful for filtering, sorting, and surfacing + +**Common failures:** + +- Categories that overlap (item could go in 3 different categories) +- Tags that are unmaintained (sprawl into thousands, become useless) +- Metadata fields that get filled inconsistently +- Different content types using different taxonomies for the same thing (chaos) + +### 6. Labeling + +What you call things. + +**Label principles:** + +- Audience language, not internal language +- Specific enough to be useful, short enough to scan +- Consistent across the site (call it "Product" or "Solutions" but not both) +- Tested with real users (closed card sort or tree test surfaces label problems) + +**Common label problems:** + +- "Solutions" (vague; usually means "products with marketing copy") +- "Resources" (catch-all; everything ends up there) +- Internal jargon ("PRD," "OKRs") that doesn't match user vocabulary +- Labels that change meaning across the site + +--- + +## Workflow + +1. **Understand the audience and content.** Use existing discovery and content strategy if available. +2. **Card sort or interview** to surface mental models. +3. **Draft the sitemap.** Hierarchy, page types, cross-references. +4. **Define URL patterns.** One pattern per content type. +5. **Design navigation.** Primary, secondary, utility, footer, breadcrumbs. +6. **Build taxonomy.** Categories (controlled, small) and tags (open, large). +7. **Validate labels.** Tree test or closed card sort with target users. +8. **Document.** Use the template in [`references/ia-document-template.md`](references/ia-document-template.md). +9. **Hand off to design and development.** IA decisions inform navigation components, URL routing, and taxonomy implementation. + +--- + +## Failure patterns + +- **IA designed by org chart.** "Engineering" and "Marketing" sections make sense to the company, not to the audience. +- **Categories that proliferate.** Every team adds a category for their thing. Becomes unscannable. Hold the line at 5 to 15. +- **Tags that sprawl.** No tag governance. Tags become a junk drawer. +- **Inconsistent URL patterns.** Some posts at /blog/[slug], some at /[slug], some at /articles/[slug]. Pick one. +- **Navigation that hides primary content.** The most important pages should be one click from home. +- **Search as a substitute for IA.** "Just use search" is not a structure. Search supports IA, doesn't replace it. +- **No validation.** Card sorts, tree tests, and first-click tests are cheap and surface huge problems early. +- **Treating IA as a one-time deliverable.** IA evolves with content. Plan for evolution. + +--- + +## Output format + +Default output is an IA document at `information-architecture.md` plus visual assets: + +1. Executive summary +2. Audience and mental models (synthesized) +3. Sitemap (hierarchical diagram) +4. URL structure (per content type) +5. Navigation specification (primary, secondary, utility, footer, breadcrumbs) +6. Taxonomy (categories and tag governance) +7. Labels (validated wording for navigation, categories, content types) +8. Implementation notes for design and development + +Visual deliverables: +- Sitemap diagram (Whimsical, Figma, OmniGraffle, etc.) +- Navigation wireframes for primary surfaces +- Optional: card sort and tree test results + +--- + +## Reference files + +- [`references/ia-document-template.md`](references/ia-document-template.md) - Template for the IA deliverable. +- [`references/url-pattern-library.md`](references/url-pattern-library.md) - URL pattern conventions for common content types. diff --git a/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md b/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md new file mode 100644 index 0000000..4f7ad12 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md @@ -0,0 +1,298 @@ +# Information Architecture Document Template + +A fillable template for the IA deliverable. Captures the sitemap, navigation, content types, taxonomy, and URL conventions. + +The IA document is the single source of truth for "what is this site, structurally." Engineering, design, content, and SEO all reference it. + +--- + +## Project metadata + +**Site / app:** [Name] +**Phase:** [New build / restructure / refresh] +**Date:** [YYYY-MM-DD] +**IA lead:** [Name] +**Status:** [Draft / In review / Approved] + +--- + +## 1. Audience and intent + +The IA serves audience tasks. Start with the tasks. + +### Primary audiences + +| Audience | Top tasks on this site | +|---|---| +| | | +| | | +| | | + +### Top tasks + +The 5-10 things people most commonly want to do or find. + +1. [Task] +2. [Task] +3. [Task] +4. [Task] +5. [Task] + +Each task should be discoverable in 3 clicks or fewer from the homepage. + +--- + +## 2. Sitemap + +The full set of pages the site contains, organized by hierarchy. + +### Top-level navigation + +The 4-7 sections that appear in the main nav. + +``` +Home +├── [Section 1] +├── [Section 2] +├── [Section 3] +├── [Section 4] +├── [Section 5] +└── [Utility nav: Login, Search, Cart, etc.] +``` + +### Full sitemap + +``` +Home (/) +├── Section 1 (/section-1/) +│ ├── Sub-page 1.1 (/section-1/sub-page-1-1/) +│ ├── Sub-page 1.2 (/section-1/sub-page-1-2/) +│ └── Sub-page 1.3 (/section-1/sub-page-1-3/) +├── Section 2 (/section-2/) +│ ├── Category 2.1 (/section-2/category-2-1/) +│ │ └── Detail pages (/section-2/category-2-1/[slug]/) +│ └── Category 2.2 (/section-2/category-2-2/) +├── Section 3 (/section-3/) +├── About (/about/) +├── Contact (/contact/) +├── Legal +│ ├── Privacy (/privacy/) +│ ├── Terms (/terms/) +│ └── Cookies (/cookies/) +└── 404 (/[unmatched]) +``` + +### Pages outside primary nav + +Pages that exist but are not in the top nav. Reachable from footers, contextual links, search, or direct entry. + +| Page | URL | Reached from | +|---|---|---| +| | | | +| | | | + +--- + +## 3. Navigation + +### Primary nav + +- **Items:** [List] +- **Behavior on desktop:** [Always visible / dropdown / mega menu] +- **Behavior on mobile:** [Hamburger / bottom nav / slide-in] +- **Active state indicator:** [Underline / color / weight] +- **Sticky on scroll:** [Yes / no] + +### Secondary nav + +If applicable. Examples: section nav within a section, sidebar nav for docs, breadcrumbs. + +- **Used in:** [Sections] +- **Pattern:** [Sidebar / breadcrumbs / tabs / pills] + +### Utility nav + +Login, search, cart, language switcher, account. Where they live on desktop and mobile. + +### Footer nav + +Comprehensive map of the site, plus legal and contact. + +- **Sections:** [Group names and what is in each] +- **Treatment:** [Links only / links + descriptions / multi-column / single column on mobile] + +--- + +## 4. Content types + +The reusable patterns that pages fall into. Each content type has a defined schema. + +### Content type: [Name, e.g., "Article"] + +- **Purpose:** [What this content type is for] +- **Required fields:** [Title, body, author, publish date, etc.] +- **Optional fields:** [Hero image, related articles, summary] +- **URL pattern:** [`/blog/[slug]/`] +- **Template:** [Which page template renders this] +- **SEO defaults:** [Default title pattern, meta description pattern, schema type] +- **Open Graph defaults:** [OG image source, OG type] + +(Repeat for each content type: page, article, product, case study, landing page, author, category, tag, etc.) + +--- + +## 5. Taxonomy + +How content is organized and tagged for filtering, related-content surfacing, and navigation. + +### Categories (hierarchical) + +The primary classification, often used in URLs. + +- Category 1 + - Subcategory 1.1 + - Subcategory 1.2 +- Category 2 + +Categories are typically mutually exclusive (a piece belongs to one). + +### Tags (flat, multi-select) + +Cross-cutting attributes a piece can have multiple of. + +- [Tag] +- [Tag] +- [Tag] + +### Custom taxonomies + +Domain-specific facets (e.g., for a recipe site: cuisine, dietary, cook time, meal type). + +| Taxonomy | Values | Used by content types | +|---|---|---| +| | | | +| | | | + +--- + +## 6. URL conventions + +See `url-pattern-library.md` for the full URL pattern reference. The IA document captures decisions specific to this site. + +| Type | Pattern | Example | +|---|---|---| +| Home | `/` | `/` | +| Static page | `/[slug]/` | `/about/` | +| Section landing | `/[section]/` | `/products/` | +| Article detail | `/blog/[slug]/` | `/blog/how-to-x/` | +| Product detail | `/products/[slug]/` | `/products/widget/` | +| Category archive | `/category/[slug]/` | `/category/news/` | +| Tag archive | `/tag/[slug]/` | `/tag/announcements/` | +| Author page | `/author/[slug]/` | `/author/jane-doe/` | +| Search results | `/search/?q=[query]` | `/search/?q=widget` | + +### Trailing slash policy + +[All URLs end with trailing slash / no trailing slash. Pick one and enforce via redirect.] + +### Casing + +[Lowercase only. Hyphens for word separation.] + +--- + +## 7. Search + +- **In-site search included?:** [Yes / no] +- **Source of truth:** [Internal index, Algolia, Elasticsearch, native CMS search] +- **Surface in nav:** [Always visible / icon-only / hidden behind utility nav] +- **Result page URL:** [`/search/?q=[query]`] +- **Result types:** [Pages, articles, products, etc.] +- **Filters:** [What filters appear on the result page] +- **Empty-state message:** [Text and suggested actions] + +--- + +## 8. Cross-linking strategy + +How pages link to other pages within the site. + +### Hub-and-spoke + +Pillar pages (hubs) link to related detailed pages (spokes). Spokes link back to the hub. + +| Hub | Spokes | +|---|---| +| `/topic-area/` | `/topic-area/[detail-1]`, `/topic-area/[detail-2]` | + +### Related content blocks + +Where they appear, what populates them. + +- **Article footer:** [Same category / same tag / manually curated] +- **Product detail page:** [Same category, similar price, frequently bought with] +- **Sidebar:** [Trending, recent] + +### Contextual links in body copy + +The single highest-value cross-link mechanism. Editorial guidelines: + +- Link the first natural mention of a related topic +- 2-5 contextual links per article +- Anchor text describes the destination, not "click here" + +--- + +## 9. Pagination, infinite scroll, and load more + +For listing pages (archives, search, category, etc.). + +| Listing type | Pattern | Page size | URL behavior | +|---|---|---|---| +| Article archive | Pagination | 10 per page | `/blog/page/2/` | +| Search results | Load more | 20 per page | URL stays at `/search/?q=...` | +| Product grid | Pagination | 24 per page | `/products/?page=2` | + +Pick deliberately. Each pattern affects SEO, accessibility, and analytics. + +--- + +## 10. Multilingual / multi-region + +If applicable. See `internationalization` skill for full guidance. + +- **Languages supported:** [List] +- **Regions supported:** [List] +- **URL pattern for locale:** [`/en/`, `/es/` subdir / `en.example.com` subdomain / no prefix on default locale] +- **Hreflang strategy:** [How locale alternates are declared] +- **Default locale fallback:** [What happens for unmatched locales] + +--- + +## 11. Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## 12. Change log + +| Date | Change | Approved by | +|---|---|---| +| | | | +| | | | + +--- + +## Sign-off + +IA approved by: + +- IA lead: [Name, date] +- Engineering lead: [Name, date] +- Content lead: [Name, date] +- SEO lead: [Name, date] + +Implementation can begin: [Date] diff --git a/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md b/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md new file mode 100644 index 0000000..75bf052 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md @@ -0,0 +1,377 @@ +# URL Pattern Library + +Conventional URL patterns for common content types. Use as a starting point. Adapt for the specific site. + +URL patterns matter because: +- Users see them in the address bar +- Search engines use them as a relevance signal +- They appear in shared links and citations +- Inconsistent patterns are a structural smell that creates downstream problems + +--- + +## Universal principles + +Apply to every URL on every site: + +- **Lowercase.** `/about` not `/About`. +- **Hyphens, not underscores.** `/blog/getting-started` not `/blog/getting_started`. +- **No trailing slash** for non-folder URLs (or always with trailing slash; pick one and be consistent). +- **No file extensions.** `/about` not `/about.html` or `/about.php`. +- **No query strings in canonical URLs.** Filters and sorts can use query strings, but the canonical version is parameter-free. +- **Stable.** URLs do not change without a 301 redirect from the old URL. +- **Predictable.** Same content type uses the same URL pattern site-wide. + +--- + +## Marketing site patterns + +### Home + +``` +/ +``` + +### Top-level pages + +``` +/about +/contact +/pricing +/careers +/blog +/help +``` + +Avoid generic catch-alls like `/info` or `/page`. + +### Sub-pages within sections + +``` +/about/team +/about/values +/about/history +/careers/engineering +/careers/design +``` + +Two levels deep is the typical maximum for marketing site pages. Beyond that, structure usually breaks down. + +### Marketing landing pages + +``` +/[campaign-slug] short, memorable, often used in print/ads +/lp/[campaign-slug] namespaced under /lp for clarity +/[product]/[campaign] nested under product if relevant +``` + +For high-traffic ad campaigns, a short root-level URL is fine. For evergreen marketing pages, namespace them. + +--- + +## Blog and editorial patterns + +### Blog index + +``` +/blog +``` + +### Blog posts + +``` +/blog/[slug] +``` + +The dominant pattern. Simple, scannable, no dates in the URL (so updates don't change the URL). + +If dates are genuinely required (news sites, time-sensitive content): + +``` +/blog/[year]/[month]/[slug] +``` + +But avoid dates by default. They make URLs longer and stale-looking when content gets updated. + +### Categories and tags + +``` +/blog/category/[category-slug] +/blog/tag/[tag-slug] +``` + +Or, if you prefer cleaner URLs: + +``` +/blog/[category-slug]/[post-slug] embeds category in the post URL +``` + +The embedded version is cleaner but creates URL changes when posts move categories. Pick based on whether posts move categories. + +### Author pages + +``` +/author/[author-slug] +/blog/author/[author-slug] +``` + +The first if authors are site-wide. The second if authors are blog-specific. + +### Archive pages + +``` +/blog/archive/[year] +/blog/archive/[year]/[month] +``` + +Optional, mostly for SEO and historical browsing. Often noindexed if they don't add unique value. + +--- + +## Product / e-commerce patterns + +### Product catalog + +``` +/products +/shop +``` + +Pick one and use site-wide. Don't have both. + +### Categories + +``` +/products/[category] +``` + +### Sub-categories + +``` +/products/[category]/[subcategory] +``` + +Two levels of category is typical maximum. Deeper hierarchies hurt findability. + +### Product detail + +``` +/products/[category]/[product-slug] +/products/[product-slug] if categorization isn't critical +``` + +The first is more SEO-friendly (signals category relevance). The second is cleaner but loses the hierarchy signal. + +### Filters and search + +``` +/products/[category]?filter=value&sort=price-asc filters as query strings +``` + +Canonical URL ignores query strings. Use the bare category URL as the canonical. + +--- + +## Documentation patterns + +### Docs root + +``` +/docs +/help +/support +``` + +### Sections + +``` +/docs/getting-started +/docs/api +/docs/integrations +``` + +### Pages within sections + +``` +/docs/getting-started/installation +/docs/api/authentication +/docs/integrations/slack +``` + +Two to three levels is typical. Deeper hierarchies become hard to navigate. + +### API reference + +``` +/docs/api/[endpoint] +/docs/api/v[N]/[endpoint] versioned APIs +/api-reference/[endpoint] if API docs are separate +``` + +--- + +## Account and product surface patterns + +These are the URLs inside an authenticated product. Not visible to crawlers but still matter for usability and consistency. + +### Dashboard + +``` +/dashboard +/app +/home inside the product, not the marketing site +``` + +### Settings + +``` +/settings +/settings/[section] +/account +/account/[section] +``` + +### Resources within an account + +``` +/projects +/projects/[id] +/projects/[id]/[resource] +/projects/[id]/[resource]/[item-id] +``` + +For e-commerce or SaaS, IDs matter more than slugs since these are user-specific items. + +--- + +## Special URL patterns + +### Search results + +``` +/search?q=[query] +``` + +Or, for SEO-friendly search landing pages: + +``` +/search/[query] +/find/[query] +``` + +The second pattern creates indexable search pages, which can be useful or harmful depending on the site. + +### Filter/facet pages (e-commerce or directory) + +``` +/[category]/[filter-slug] e.g., /running-shoes/men +/[category]?[filter]=[value] filters via query string +``` + +Static filter pages are SEO-friendly. Dynamic query strings are cleaner but don't index. + +### Pagination + +``` +/blog/page/2 +/blog/page/3 +/blog?page=2 via query string +``` + +The path-based version is more SEO-friendly. Either works as long as you canonical correctly. + +### Profile pages + +``` +/u/[username] +/users/[username] +/profile/[username] +/[username] if usernames don't conflict with other paths +``` + +The last (root-level usernames) is the cleanest but requires careful conflict prevention. + +### Internationalization + +``` +/[locale]/[path] e.g., /en/about, /es/about +[subdomain].domain.com/[path] e.g., en.domain.com/about +domain.[ccTLD]/[path] e.g., domain.fr/about +``` + +Each has tradeoffs. Path-based is most flexible. Subdomain is good for cleanly separated content. ccTLD is best for genuine country targeting. + +Use hreflang tags to indicate language pairs regardless of the URL strategy. + +--- + +## URL anti-patterns + +### Anti-pattern: Tracking parameters in canonical URLs + +``` +Bad: /post?utm_source=newsletter +Good: /post (with utm parameters preserved at runtime but stripped from canonical) +``` + +UTM parameters are for analytics, not for canonical URLs. + +### Anti-pattern: Session IDs in URLs + +``` +Bad: /products?sid=ABC123 +Good: /products (session in cookies, not URL) +``` + +URLs should be safe to share. Session IDs in URLs leak sessions when shared. + +### Anti-pattern: Verb-heavy URLs + +``` +Bad: /show-product/[id] +Good: /products/[id] +``` + +URLs are nouns, not verbs. + +### Anti-pattern: Date in URLs for evergreen content + +``` +Bad: /blog/2024/05/how-to-write-headlines +Good: /blog/how-to-write-headlines +``` + +Dates make URLs feel stale. They also break when posts get updated. + +### Anti-pattern: Stop words in URLs + +``` +Acceptable: /the-best-running-shoes +Better: /best-running-shoes +``` + +Removing "the," "and," "of" makes URLs shorter without losing meaning. + +### Anti-pattern: Fragment-only navigation + +``` +Bad: /home#features (no /features page) +Good: /features (real URL) +``` + +Fragments don't index. Real pages do. + +--- + +## Migration considerations + +When changing URL patterns on an existing site: + +1. **Map every old URL to a new URL.** No exceptions. +2. **301 redirect old URLs to new.** Permanent redirect preserves SEO equity. +3. **Avoid redirect chains.** Old URL should redirect directly to the new URL, not to an intermediate. +4. **Update internal links.** Every internal link should point at the new URL, not the old. +5. **Update sitemap.** New URLs only, no legacy URLs. +6. **Wait 90+ days before removing redirects.** Search engines and external sites take time to update. + +See `seo-technical/references/migration-checklist.md` for the full migration playbook. diff --git a/dist/pi/.agents/skills/integration-orchestrator/SKILL.md b/dist/pi/.agents/skills/integration-orchestrator/SKILL.md new file mode 100644 index 0000000..9a80690 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/SKILL.md @@ -0,0 +1,171 @@ +--- +name: integration-orchestrator +description: "Generate a phased delivery orchestration plan for creative-direction-driven work: which skills run when, what locks at which gate, how handoffs occur, and how the cadence implements in the team's tools (Jira, Linear, Notion, Figma, GitHub) with AI agents via MCP and CLI. A temporal map of phases, lock points, handoff specs, gate definitions, and QA verification gates. Distinct from `creative-brief` (static project brief) and `creative-direction` (aesthetic direction). Triggers on integration orchestrator, delivery cadence, project orchestration, when does the brief lock, how to phase creative direction, design-development handoff, QA gate, agent-driven QA, and when a creative-direction project is starting, mid-flight with broken cadence, or integrating AI agents into PM workflow. Does NOT fire for project scoping (use `creative-brief`), aesthetic direction (use `creative-direction`), or general project management without a creative-direction throughline." +category: product +catalog_summary: "Sequence creative-direction work across phases, gates, handoffs, and QA verification" +display_order: 3 +--- + +# Integration Orchestrator + +A brief tells a team what to make. Creative direction tells them what it should feel like. Neither tells them when each decision locks, who reviews what, or what stops the next phase from starting before the prior one is done. That is the gap this skill fills. + +The output is a phased orchestration plan the PM can paste into a calendar Monday morning and start running Tuesday. Phases, gates, lock points, handoffs, QA verification rules, and a platform-specific implementation guide for whatever stack the team actually uses (Jira, Linear, Notion, Figma, GitHub, agile sprints). + +--- + +## What this skill is + +A creative-direction project has three layers. The brief layer defines scope, audience, deliverables, constraints, success criteria. The direction layer defines tone, aesthetic, relationship, and sensory ambition. Both produce written artifacts. Neither answers the temporal question: when does the brief lock, when does identity lock, when does copy lock, who reviews each, what gets blocked while a gate is open, what happens when a downstream task discovers the brief is wrong, and what makes "Done" mean tested rather than self-reported. + +This skill produces that temporal layer. Most teams have briefs and creative direction but no orchestration plan. The result, by week 3, is everyone working in parallel with no shared sense of which decisions are still open and which are locked. Brief drift. Re-work. Identity tokens shifted after copy was already drafted against the old ones. Engineering shipping before design had a chance to review. "Done" tickets that were never actually verified. + +The orchestration plan answers all of that. It is not theory. It is a phased timeline with calendar weeks, ticket templates the PM can paste into Jira or Linear, MCP commands for setup, gate definitions with measurable pass criteria, handoff specs with artifact requirements, and QA verification gates with Playwright or Chrome MCP invocations. + +--- + +## When to use + +- Starting a new brand build, rebrand, or campaign and the team needs to sequence the work +- Mid-flight project where the brief is being revisited and downstream work is suffering from constant resets +- Setting up a new team's agent-driven workflow with MCPs and CLI integration +- Multi-team work where handoffs between brand, design, and engineering have broken down +- Establishing QA verification gates so "Done" is measurable, not self-reported +- Migrating from ad-hoc orchestration to a documented cadence +- Onboarding a new PM or design lead onto an existing project that has running tickets but no documented sequencing +- Adding new platforms or tools to an existing workflow and the cadence needs to be re-mapped + +--- + +## When NOT to use + +- Use `creative-brief` instead if the deliverable is the project brief itself: scope, audience, deliverables, constraints, success criteria. The orchestrator skill takes the brief as input. +- Use `creative-direction` if the deliverable is the aesthetic direction: tone, aesthetic, relationship, sensory. The orchestrator schedules the work that answers to the direction; it does not produce the direction. +- Generic project management software is the platform; this skill produces the plan that runs IN the platform. Do not run this skill if the team needs help picking a tool; it assumes the tool stack is already chosen. +- Sprint-planning tactics (story-pointing, retros, velocity charts) live downstream of orchestration. The skill produces the cadence; sprint planning fills it in. + +--- + +## Required inputs + +- **Project type.** New brand build, rebrand, single landing page, campaign, identity refresh, website refresh, microsite, product launch. The type implies a default phase decomposition that the skill adapts to the specific project. +- **Team composition.** Total size and role mix. Solo, small (2-3), medium (4-7), large (8+). Whether AI agents (Claude Code, Claude in Chrome, others) participate in production, QA, or both. +- **Tool stack.** Which of Jira, Linear, Notion, Figma, GitHub the team uses. Plus QA tooling (Playwright, Chrome MCP, Windows MCP, mobile testing harnesses) if known. Plus communication and paging channel (Slack, email, in-tool mention). The output adapts to the actual stack. +- **Timeline target.** Express (compressed timelines, fewer reviewers, accept higher rework risk), standard (typical cadence at the project type's default duration), or thorough (more reviewers, formal phase reviews, lower rework risk at the cost of slower delivery). +- **Existing constraints.** What is already locked? Brief approved, identity locked, platform fixed, brand voice already shipped, content management system non-negotiable. The orchestrator plan handles greenfield and mid-flight equally; the existing constraints input is how mid-flight projects are accommodated. +- **AI agent participation.** Which workflows include agents and at what fidelity. Examples: Claude Code does production tasks against a state file in the repo; Claude in Chrome runs human-readable QA flows on the staging deployment; the agent has access to the Linear MCP and the GitHub MCP but not Jira; the agent can move tickets between Todo, In Progress, Waiting, and Blocked but cannot move to Done (Done requires a human verification step). +- **Risk profile.** Optional input naming the failure modes the team is most worried about: brief drift, parallel-work conflicts, QA gaps, agent runaway. The orchestration plan front-loads mitigations for the named risks. + +--- + +## The framework: 7 considerations for orchestration + +A delivery orchestration plan sits at the intersection of seven considerations. Each filters the choices that follow. + +### 1. Phasing + +How the project decomposes into phases. The standard shape is discovery, direction, identity, production, QA, and launch. Not every project type uses every phase. A campaign skips identity (it inherits the locked brand identity). A landing page collapses discovery and direction into a single brief phase. A rebrand replaces discovery with audit (positioning is known; the audit assesses what to keep). + +The shape of the phases matters less than the explicit answer to two questions per project: which phases run sequentially because the downstream phase cannot start without the prior phase's output, and which phases overlap because their outputs do not depend on each other. Identity must complete before copy starts (copy depends on tone-axis position, which is part of identity). QA must complete before launch. Discovery and audit may overlap with brief drafting, because the brief consumes discovery findings as they emerge. + +### 2. Gates + +A gate is the approval moment that governs phase transition. The standard gates are brief approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, and launch readiness. Each gate has a trigger (the work that opens it), an approver (the person or test suite that passes it), required-to-pass criteria (the measurable thing that says yes or no), what's blocked until the gate passes, and what's already locked from prior gates. + +Gates work when the criteria are measurable. "Brief approved" is too vague; "client signed the brief artifact in writing or in a recorded review" is measurable. "QA passed" is too vague; "Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained" is measurable. Gates that are not measurable become political; gates that are measurable become structural. + +### 3. Lock points + +A lock point is the moment an artifact becomes immutable. The brief locks after direction is approved. Identity tokens lock after the identity gate. Voice rules lock after voice approval. Copy locks per page after copy approval. Once locked, the artifact cannot be changed by downstream work; it can only change via a formal change request that triggers re-review of dependent work. + +Without explicit lock points, every artifact is conceptually editable forever. That is the source of brief drift. The orchestrator plan names what locks at which gate, where the locked artifact lives, who can request a change, and what gets re-reviewed if a change is approved. Locked is not the same as final; locked means "any further change to this triggers downstream review work, so make changes deliberately." + +### 4. Handoffs + +A handoff is the moment work transfers between phases or skills. The standard handoffs are discovery to brief, brief to identity, brief to voice, identity plus voice to copy, identity plus copy to design, design to engineering, engineering to launch. Each transfers specific artifacts and decisions. Each leaves some things open and locks others. + +There is also a cross-cutting handoff: the adjacent observation handoff. While working on the homepage hero, an agent or person notices the footer copy is inconsistent with the new voice. That observation is not the current task. It is filed as an observation in the project triage queue. The PM or tech lead reviews observations on a regular cadence and triages them into proper tickets. This pattern keeps current work focused while not losing the contextually-relevant findings the team would otherwise either drop or derail current work to address. + +### 5. Team-size modulation + +A 2-person team and a 12-person team need different orchestration. Solo work is one person playing every role. Small (2-3) means a single reviewer per gate and async handoffs are fine. Medium (4-7) needs multiple reviewers and async sync points. Large (8+) needs formal phase reviews, a dedicated PM for orchestration, and explicit cross-track sync ceremonies because parallel tracks drift apart without them. + +The orchestration plan output modulates by scale. Solo gets self-review checklists per phase. Small gets per-gate "review by" assignments. Medium gets reviewer rotation and within-phase mini-gates. Large gets formal phase reviews, cross-track sync, and a brief-owner role. The framework is the same; the cadence's review density and ceremony level change. + +### 6. Tool-stack implementation + +Phases and gates exist in concept; they implement in tools. The orchestration plan specifies the implementation per platform: in Jira, phases become Epics with custom fields for "Phase", "Locked", "Approver", and "Gate Status"; in Linear, phases become Projects with cycles and label-driven views; in Notion, the brief becomes a database row with relation properties tying to direction docs, identity specs, voice guides, and copy decks; in Figma, phases become library folders with frame-level review status; in GitHub, phases interact with branch protection, PR templates, and CODEOWNERS-driven review routing. + +Where MCPs exist (Atlassian, Linear, Notion, GitHub), the plan specifies which orchestration setup operations the MCP can execute and which remain manual UI work. Where MCPs are limited (Figma's Dev Mode MCP is dev-mode-focused; the design library setup remains manual), the plan documents the recommendation without claiming end-to-end automation. + +### 7. Automation and QA verification + +The single most consequential discipline in the framework. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The standard status taxonomy is Todo, In Progress, Waiting, Blocked, Done. Blocked is a first-class status, distinct from Waiting. Waiting means the task is paused for normal handoff or scheduled review; Blocked means the task cannot proceed without human resolution of a specific issue. Agents move tasks to Blocked when they cannot autonomously resolve work; this prevents agents from spinning on un-resolvable problems and burning context. + +QA verification gates fire automatically. Playwright MCP runs critical-flow tests; Chrome MCP runs human-readable walkthroughs and captures evidence; Windows MCP handles desktop apps; mobile testing harnesses cover mobile applications. Failure routes to Blocked, files an adjacent observation if the failure surfaced something unrelated, pages the human via the configured channel, and stops. The agent does not retry autonomously. + +--- + +## Common project-type cadences + +Seven templates. Each is a skeletal phase map; the cadence-patterns reference file expands each. + +- **New brand build.** 6 to 8 weeks across 5 phases: Discovery (1 week), Direction (1 week), Identity (1 to 2 weeks), Production (2 to 3 weeks), Launch (1 week). Gates fire after each phase; identity locks before copy starts. +- **Rebrand.** 4 to 6 weeks across 4 phases: Audit (1 week, replaces Discovery), Direction (1 week), Identity (1 to 2 weeks), Production (1 to 2 weeks). Audit assumes positioning and audience are known; the work is assessing what to keep, drop, or refresh. +- **Single landing page.** 1 to 2 weeks across 3 phases: Brief (2 to 3 days), Production (5 to 7 days), QA-Launch (1 to 2 days). Identity is assumed locked. Voice is assumed locked. The work is page-specific copy, design, and engineering. +- **Campaign.** 2 to 4 weeks across 4 phases: Brief (3 to 5 days), Production (1 to 2 weeks), QA (3 to 5 days), Launch (1 to 2 days). Campaign assumes brand identity and voice exist and are locked. +- **Identity refresh.** 3 to 4 weeks across 3 phases: Audit (1 week), Identity (1 to 2 weeks), Production (1 week). Skips discovery and positioning. The output is a refreshed identity system that goes into production for application examples. +- **Website refresh.** 4 to 8 weeks across 4 phases: Audit (1 week), Direction (1 week), Production (2 to 4 weeks), QA-Launch (1 to 2 weeks). Direction may produce a refreshed brief if the audit surfaces positioning gaps. +- **Microsite or product launch.** 3 to 5 weeks across 4 phases: Brief (3 to 5 days), Production (2 to 3 weeks), QA (3 to 5 days), Launch (2 to 3 days). The microsite or product launch usually has a fixed launch date that drives backward planning. + +Each cadence reads as if the PM could paste it into a calendar and start running. Phase boundaries align with calendar weeks where possible, because that is how teams actually plan. + +--- + +## Failure patterns + +The orchestration plan exists to prevent these. Each is a real failure mode, observed in the wild on real projects. + +- **Brief becomes a write-once doc.** The brief is drafted, signed, then nobody references it again. Downstream work drifts. The fix: lock the brief at a gate and treat any reference to it as a reading, not an edit. +- **Brief gets unfrozen mid-flight without re-reviewing dependent work.** Someone tweaks the brief's audience or positioning; the change does not propagate to identity, voice, or copy that already depend on the old version. The fix: a formal change-request protocol that triggers re-review of dependent artifacts. +- **Identity locks before voice.** The typography is finalized before the voice is approved. Result: the type and the voice register conflict (a friendly voice in austere type, or a serious voice in casual type). The fix: voice approval gate fires before or alongside identity lock. +- **Copy starts before voice locks.** Writers draft against a moving target. Rework is invisible because the original draft never gets compared against the locked voice. The fix: voice approval before copy production. +- **Multiple parallel design tracks lose brief alignment.** Track A and Track B both interpret the brief slightly differently; by week 3 the two tracks read as different brands. The fix: cross-track sync ceremonies and a brief-owner role. +- **Engineering starts before design freeze.** Components get built against design that is still moving. Rework downstream when design lands somewhere else. The fix: design approval gate before engineering starts on the affected surface. +- **Reviews stack at end of phase.** Everyone defers their review to the final day; the gate becomes a 10-hour review marathon and approvers approve under fatigue. The fix: within-phase mini-gates that flatten review demand. +- **Async handoffs without artifact specification.** "Hand the design over to engineering" without specifying what artifacts (Figma file URL, exported tokens, asset library reference, PR draft template) means engineering opens half a dozen Slack threads to find what they need. The fix: explicit artifact specification per handoff. +- **QA gate is self-reported.** "Done" tickets get moved to Done without verification. Bugs land in production. The fix: automated verification that fires before status transitions to Done; failure routes to Blocked. +- **Agents spin on un-resolvable work.** A Claude Code task cannot resolve itself; the agent retries, burns context, runs out of tokens, leaves the work in a worse state than when it started. The fix: Blocked is a first-class status; agents move tasks to Blocked when they cannot autonomously resolve, document the blocker, and stop. + +--- + +## Output format + +Default output is a markdown document, typically saved as `ORCHESTRATION.md` at the project root or in a `docs/` subdirectory. The document contains the full plan and is the canonical reference for the team. + +Structure: + +1. **Project orchestration plan.** Phased timeline with calendar weeks, milestone dates, phase outputs. +2. **Per-phase gate specs.** What enters, what exits, who approves, the measurable pass criteria for each gate including the QA verification gate. +3. **Lock-point register.** What becomes immutable when, where the locked artifact lives, who can request a change, and what re-review work a change triggers. +4. **Tool-stack implementation guide.** Concrete setup for Jira, Linear, Notion, Figma, and GitHub as applicable, with MCP commands or CLI invocations for the parts that automate. +5. **QA verification gate spec.** Which automated tests must pass, which MCPs run them, where evidence attaches, what happens on failure. +6. **Handoff specs.** Artifacts transferred per handoff, locked items, change-request protocols, adjacent-observation routing. +7. **Cross-skill dependency graph.** Which skills run in which phase, what each skill consumes, what each produces. +8. **Risk register.** Cadence-specific risks with mitigations. + +The document is the orchestration plan. The next step after delivery is for the PM to set up the team's tools to match (Jira epics, Linear projects, Notion databases, Figma libraries, GitHub branch protection) and start running the plan. + +--- + +## Reference files + +- [`references/cadence-patterns.md`](references/cadence-patterns.md). The 7 project-type cadences in detail with phase decomposition, timelines, gate definitions, and tool-stack implementation skeletons. +- [`references/gate-definitions.md`](references/gate-definitions.md). Each standard gate with trigger, approver, pass criteria, what's blocked, what's already locked, and change-request protocols. +- [`references/handoff-protocols.md`](references/handoff-protocols.md). The standard handoffs between phases and skills, plus the adjacent observation handoff for filing things noticed while working nearby. +- [`references/platform-implementation.md`](references/platform-implementation.md). How the orchestration maps to Jira, Linear, Notion, Figma, and GitHub, including MCP integration notes per platform and CLI alternatives where MCP is the wrong tool. +- [`references/team-size-modulation.md`](references/team-size-modulation.md). How cadences scale across solo, small, medium, and large teams. +- [`references/automation-and-qa-tooling.md`](references/automation-and-qa-tooling.md). The QA verification gate pattern, MCP vs CLI tradeoffs, session memory and momentum patterns, code-to-ticket linkage, and evidence trails. +- [`references/example-orchestration.md`](references/example-orchestration.md). A complete worked example showing all sections populated for a representative scenario. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md b/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md new file mode 100644 index 0000000..d1649a5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md @@ -0,0 +1,167 @@ +# Automation and QA tooling + +The QA verification gate, MCP vs CLI tradeoffs at the strategic level, session memory and momentum patterns, code-to-ticket linkage, evidence trails, and failure routing. This file pairs with platform-implementation.md (which covers per-platform specifics) but stays at strategic-pattern level. + +--- + +## Section 1: The QA verification gate + +The single most important pattern in this reference file. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The orchestration plan specifies, per project type: + +- **Which automated tests must pass.** Defined in writing as part of the orchestration plan output. Different project types have different test suites. + - **Web project.** Playwright critical-flow tests covering signup, checkout, contact form, navigation, and any other paths that move money or capture data. Visual regression on key pages (homepage, pricing, top-traffic landing pages). Console error count not exceeding baseline (specify baseline as 0 errors at hero load and during critical flows). Accessibility floor (WCAG AA contrast, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled). Performance budgets (Lighthouse mobile and desktop scores at or above project target, Core Web Vitals at or above project target). + - **Microsite or landing page.** Subset of the above scoped to the page; performance budgets often tighter. + - **Campaign.** Cross-deliverable consistency check (do all assets reference the same brand identity? do all touchpoints use the locked voice?) plus per-deliverable QA. + - **Identity refresh.** Visual regression on the design library plus an audit of downstream files using deprecated components. + +- **Which MCPs run them.** + - **Playwright MCP** for browser-driven user-flow tests. The agent invokes the test suite, captures pass/fail per test, and attaches results to the ticket. + - **Claude in Chrome / Chrome MCP** for human-readable QA flows with screenshot or GIF evidence trails. Useful when the test isn't a deterministic pass/fail (e.g., "does the checkout flow feel right?" requires a human-readable record). Chrome MCP captures the agent's walkthrough as a GIF or screenshot sequence. + - **Windows MCP** for desktop applications. Covers Windows-specific testing scenarios when the project is desktop-app-shaped. + - **Mobile testing MCPs** (Detox-based, Appium variants) for mobile apps when applicable. + +- **What gets verified in a typical web QA pass.** + - Critical user-flow tests (signup, checkout, contact form submission, search if applicable). + - Visual regression on key pages (typically 5-10 pages flagged as critical). + - Console error count not exceeding baseline. + - Accessibility floor (WCAG AA contrast, keyboard navigation, screen reader landmarks). + - Performance budgets (Lighthouse, Core Web Vitals). + +- **Where the evidence attaches.** + - Linked to the ticket as a comment with screenshot or GIF. + - Optionally stored in a `.evidence/` folder in the repo (engineering projects) or a designated cloud bucket (S3, GCS). + +- **What happens on failure.** + - Status moves to Blocked (not back to In Progress). + - The blocker reason is documented in the ticket comment. + - If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. + - The human is paged via the configured channel. + - The agent does NOT keep retrying autonomously; it documents the state and waits. + +--- + +## Section 2: MCP vs CLI tradeoffs at the strategic level + +The platform-implementation reference covers per-platform specifics. This section is the strategic frame for choosing between MCP and CLI as the orchestration's primary interface. + +### MCP excels at + +- Small reads and writes (single ticket update, single comment posting, single page edit). +- Real-time data (current status of a project, current PRs awaiting review). +- API-shaped operations that map cleanly to JSON-in / JSON-out. +- Agent-friendly contracts (structured tool calls with typed responses). +- Navigation queries ("show me all open tickets in this project", "find the PR that touches this file"). +- Status reads (what's the current gate state, what's locked). + +### CLI excels at + +- Bulk content updates (large Confluence pages, multi-page Notion exports, repo-wide search-and-replace). +- File-tree-aware operations (operating on multiple files in a repo, generating a directory of artifacts). +- Git-like workflows (the gh CLI's strengths around branches, PRs, releases). +- Lower token cost on heavy operations. MCP roundtrips become expensive at scale; CLI runs locally with no token cost per operation. +- Scripted automation (CI workflows, deploy pipelines, scheduled jobs). + +### Decision pattern + +- **For setup and orchestration.** Prefer MCP. PM-friendly, declarative, easy to inspect. The agent can explain what it did via tool-call traces. +- **For bulk operations.** Prefer CLI. More efficient, lower token cost, better formatting preservation. +- **For QA verification.** Playwright CLI when the same test runs repeatedly (CI integration, pre-commit hooks). Playwright MCP when verification is ad-hoc and needs to interact with surrounding context (the agent reading a Linear ticket, then running specific tests against the deployed staging site). + +### Hybrid pattern + +Most production setups use both. MCP for the orchestration plan's setup operations and ongoing navigation; CLI for ongoing bulk work, CI integration, and operations the MCP can't handle efficiently. The orchestration plan specifies which interface fires when. + +--- + +## Section 3: Session memory and momentum + +The agent-starts-from-zero problem. Each new Claude Code session re-reads files, re-discovers decisions, re-learns the same gotchas. MCP gives the task list; it doesn't give working momentum. + +Patterns to bridge the gap: + +### Project state file + +Committed alongside code. Typical paths: `CLAUDE.md`, `AGENTS.md`, `.agent/state.md`. Contents: + +- **Last completed task** with brief outcome notes ("RAMP-123: homepage hero rewrite. Shipped in PR #456. Worth noting: the existing copy was longer than the new copy, so the design has extra whitespace below the hero now. May need design follow-up."). +- **Current task in progress** with current status ("RAMP-124: pricing page CTA test. In Progress. Blocking on getting the test variant ID from Mira."). +- **Open decisions awaiting human input** ("Should we use the new monogram on the favicon, or keep the existing letterform-as-symbol? Pending design lead review."). +- **Known gotchas the agent should avoid re-discovering** ("The CMS export step takes 8 minutes. Don't kick it off until you're ready to wait. The export contains stale image references; replace with current image URLs from the asset library before publishing."). +- **Convention reminders specific to the project** ("Branch names use uppercase ticket prefix: feat/RAMP-123-slug. PR descriptions include 'Closes RAMP-123'. Squash merge only."). + +### Per-task observation trail + +After completing each task, the agent records observations: + +- **What was unexpected** ("The CMS API returned a 429 on the first attempt; had to wait 60 seconds before retry succeeded."). +- **What broke before it worked** ("Initial regex for the slug pattern matched too broadly; tightened to require dash separators."). +- **What workaround was found** ("The token export script doesn't handle nested groups in Figma; flattened the groups manually before export."). +- **What pattern might generalize** ("All API endpoints return null when the resource doesn't exist, not 404. Worth refactoring the error handling to assume null rather than 404."). + +### Trail-as-next-task generation + +When N observations accumulate (typically 5 to 10), hand them back as the brief for the next iteration: "here are 10 observations from this week, turn them into improvements." Keeps the agent's capability pointed at code quality and process refinement, not just task completion. + +The orchestrator skill's output bakes these mechanisms into the plan: specifies which state file to use, what content goes in it, when observations get reviewed by the human (typically weekly grooming), how the observation trail informs next-cycle planning. + +--- + +## Section 4: Code-to-ticket linkage + +Standard but worth specifying so the orchestration plan can call out exactly which conventions the team uses. + +- **Branch naming.** `{type}/{ticket-id}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform. +- **PR descriptions.** Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- **Commit messages.** Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. +- **CODEOWNERS.** When set up, PR review routing happens automatically and the orchestration plan's review-by assignments align with platform-native routing. + +The orchestration plan specifies the convention per platform combination (Jira+GitHub uses RAMP-123 prefix style; Linear+GitHub uses LIN-456 or the team's chosen prefix). Without that specification, branch names drift across team members and the auto-linking breaks. + +--- + +## Section 5: Evidence trails and recording + +Some pattern, some practical advice. + +### Recording tools + +- **Claude in Chrome auto-records GIFs** of QA flows. Useful for evidence attached to tickets. Limitations: GIF format is large and not video-quality; for longer flows, prefer MP4 or WebP if the recording tool supports it. +- **Screenshot evidence** is sufficient for most ticket-level QA artifacts. Tools like Playwright auto-capture on test failure; Chrome MCP can take ad-hoc screenshots during human-readable QA. +- **Loom or similar** for human-narrated walkthroughs when the audience needs context (client review of the staging site, stakeholder review of a complex flow). + +### Where evidence lives + +Three options, each with tradeoffs: + +- **Attached directly to the ticket as a comment.** Most discoverable but bloats the ticket. Best for evidence that pairs tightly with a specific ticket. +- **In a designated cloud bucket** (S3, GCS) with a link in the ticket. Ticket stays clean, evidence has a stable URL. Best for projects with high evidence volume. +- **In a `.evidence/` folder in the repo.** Works for engineering-heavy projects but cumbersome for design or copy work. Pairs well with the project state file pattern; evidence and state co-locate. + +### Retention + +Most projects don't need permanent evidence retention beyond the ticket. Specify a retention policy in the orchestration plan: + +- 30 days for QA evidence (passing tests don't need long retention). +- 90 days for bug-related evidence (bug reproduction often resurfaces within 90 days). +- Indefinite for design final approvals (the audit trail matters for years). + +--- + +## Section 6: Failure routing + +When automated verification fails OR an agent hits something it cannot autonomously resolve, the failure follows a defined routing. + +1. **Status moves to Blocked.** Not back to In Progress, not to Waiting. Blocked is a first-class status that means "human action required to unblock". +2. **The blocker reason is documented** in the ticket comment with specifics: which test failed, which file was the locus, which assertion didn't pass, what the agent already tried. +3. **If the failure surfaced something unrelated to the current task,** an adjacent observation gets filed in the project triage queue. +4. **The human is paged via the configured channel.** + - Slack (preferred for in-team work, fastest response). + - Email (for cross-team or external-stakeholder blockers). + - Linear or Jira mention (for in-tool routing when the team prefers a single channel). +5. **The agent does NOT continue retrying.** It documents the state and waits. Retrying is the path that turns a single failure into a context-burning loop. + +This routing is itself part of the orchestration plan output: the skill specifies which channels are configured, who's on the escalation tree, and what response time is expected per blocker severity (typically: P0 blockers paged immediately; P1 paged within a working hour; P2 surfaced at next standup; P3 added to the triage queue without a page). + +The discipline of Blocked-as-first-class-status is what makes agent participation safe at scale. Without it, agents either burn context retrying or silently abandon work; with it, the agent has a clear "I'm stuck" signal that keeps the work visible to the human team. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md b/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md new file mode 100644 index 0000000..e21adb9 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md @@ -0,0 +1,245 @@ +# Cadence patterns + +The 7 project-type cadences in working detail. Each cadence covers phase decomposition, calendar timelines, gate definitions, lock-point map, and tool-stack implementation skeleton. + +## The 5-status taxonomy + +Every cadence in this file uses the same 5-status taxonomy: + +- **Todo.** Work scoped, not yet started. +- **In Progress.** Work being actively done. +- **Waiting.** Work paused for normal handoff or scheduled review. Examples: a ticket waiting for the next standup, a PR waiting for its assigned reviewer, a design awaiting client review at the next scheduled session. +- **Blocked.** Work cannot proceed without human resolution of a specific issue. Distinct from Waiting. An agent moves a task to Blocked when it cannot autonomously resolve and documents the blocker. The agent then stops; it does not retry. +- **Done.** Work complete AND verified. The QA verification gate must pass before transition to Done. Self-reported "I think this works" does not transition to Done; the automated test gate (or, in non-engineering contexts, the explicit reviewer signoff) does. + +Status transitions are restricted at the gate level. The QA gate prevents transition to Done. The approval gates prevent forward progress until the gate passes. Blocked tickets generate a paging signal to the configured channel. + +--- + +## 1. New brand build (6 to 8 weeks) + +The full lifecycle. Greenfield brand or a brand whose existing assets are being replaced wholesale. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Discovery | 1 week | Audience, positioning, competitive landscape, references | +| Direction | 1 week | Creative direction brief (axes locked) | +| Identity | 1 to 2 weeks | Logo system, color, typography, imagery direction, motion | +| Production | 2 to 3 weeks | Voice guide, copy, design system, page builds | +| Launch | 1 week | QA, soft launch, full launch | + +### Gates + +- **End of Discovery.** Brief approval. Required: client signed brief artifact (in writing or recorded review). +- **End of Direction.** Direction approval. Required: axis positions locked, references curated. +- **End of Identity.** Identity approval. Required: logo system, color tokens, typography, imagery direction documented. +- **Mid-Production.** Voice approval. Required: voice guide signed. +- **End of Production.** Copy approval and design approval. Required: per-page copy and design signed. +- **Pre-Launch.** QA verification. Required: Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained. +- **Launch readiness.** Final go/no-go. Required: deployment checklist complete, rollback plan documented. + +### Lock points + +Brief locks at end of Direction. Identity tokens lock at end of Identity. Voice locks mid-Production. Copy locks per page at end of Production. Design tokens lock with identity; design final lock at end of Production. + +### Tool-stack implementation + +- **Jira:** 1 Epic per phase, Stories per work item, custom fields for Phase / Locked / Approver / Gate Status. Workflow scheme with the 5-status taxonomy. +- **Linear:** 1 Project per phase, Cycles per week, Labels per skill (`brand-identity`, `brand-voice`, `landing-page-copy`, etc.). +- **Notion:** Brief database with one row, related databases for direction docs, identity specs, voice guides, copy decks. Phase dashboard views. +- **Figma:** Library structure: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status. +- **GitHub:** Branch protection on `main`. PRs from `phase/{phase-name}/*` branches. + +### Example ticket titles + +- Discovery: "Audience: 5 archetypes interviewed", "Positioning: locate the brand against 3 competitors" +- Direction: "Direction: confirm tone-axis position", "Direction: rejection list signed off" +- Identity: "Identity: logo lockup variants for review", "Identity: color tokens locked" +- Production: "Voice guide: tone-shift table approved", "Copy: homepage hero v3 reviewed" +- Launch: "QA: Playwright critical flow regression green", "Launch: deploy to production" + +--- + +## 2. Rebrand (4 to 6 weeks) + +Existing brand. Audience and positioning known. Audit replaces discovery. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | What to keep, drop, refresh; positioning gaps | +| Direction | 1 week | Creative direction brief | +| Identity | 1 to 2 weeks | Refreshed logo, color, type, imagery | +| Production | 1 to 2 weeks | Updated voice guide, copy, design library, page builds | + +### Gates + +Audit approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, launch readiness. Same gates as new brand build minus the Launch phase (rebrand often launches with the production push rather than a separate phase). + +### Lock points + +Audit findings lock at end of Audit (decisions about what to keep stay in scope; revisiting requires change request). All other lock points match new brand build. + +### Tool-stack implementation + +Same as new brand build. The Audit phase typically uses a Notion database with rows for "Existing asset / Decision (keep/drop/refresh)/Owner / Status". + +--- + +## 3. Single landing page (1 to 2 weeks) + +The brand identity and voice are locked. The work is page-specific copy, design, and engineering. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 2 to 3 days | Page brief, success criteria | +| Production | 5 to 7 days | Copy, design, build | +| QA-Launch | 1 to 2 days | QA, deploy | + +### Gates + +- **End of Brief.** Page brief approval. Required: success metric defined. +- **Mid-Production.** Copy approval. Required: signed against existing voice guide. +- **End of Production.** Design approval and engineering review. Required: design final, build complete. +- **End of QA-Launch.** QA verification and launch readiness combined. Required: Playwright run green, console errors at baseline, deploy executed. + +### Lock points + +Page brief locks at end of Brief. Copy locks mid-Production. Design tokens are inherited from the brand identity (already locked). Design final locks at end of Production. + +### Tool-stack implementation + +- **Jira / Linear:** Single Epic for the page, 5 to 8 Stories. +- **Notion:** Single brief row, one direction artifact (the page brief). +- **Figma:** Working file referencing the brand library; one set of frames. +- **GitHub:** Single feature branch, PR template, branch protection on `main`. + +--- + +## 4. Campaign (2 to 4 weeks) + +Brand identity and voice locked. Multiple deliverables under one campaign theme. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 3 to 5 days | Campaign brief, deliverable list | +| Production | 1 to 2 weeks | Per-deliverable copy, design, build | +| QA | 3 to 5 days | Cross-deliverable QA | +| Launch | 1 to 2 days | Coordinated launch | + +### Gates + +Campaign brief approval, per-deliverable copy approval, per-deliverable design approval, cross-deliverable QA verification, launch readiness. + +### Lock points + +Campaign brief locks at end of Brief. Per-deliverable copy locks at copy approval. Per-deliverable design locks at design approval. Cross-deliverable consistency checked at QA gate (a single change request on the campaign brief triggers re-review across all deliverables). + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic for campaign, 1 Story per deliverable plus per-deliverable subtasks. +- **Notion:** Campaign brief row plus deliverable rows in a related database. +- **Figma:** Library file plus one frame per deliverable. +- **GitHub:** Multiple feature branches off a campaign branch, single PR per deliverable. + +--- + +## 5. Identity refresh (3 to 4 weeks) + +Existing brand. Voice and positioning stay. Identity gets refreshed. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | What stays, what changes | +| Identity | 1 to 2 weeks | Refreshed logo, color, type, imagery | +| Production | 1 week | Application examples (web, signage, social) | + +### Gates + +Audit approval, identity approval, production review. Voice and copy gates skipped (voice stays locked; copy gets light updates if any). + +### Lock points + +Audit findings lock at end of Audit. Identity tokens lock at end of Identity. Application examples lock at end of Production but tokens remain canonical. + +### Tool-stack implementation + +- **Figma:** Refresh of existing library; new component versions; old components deprecated rather than deleted (downstream files still reference them). +- **Notion:** Identity spec row with relations to before/after asset databases. +- **Jira / Linear:** Smaller scope than rebrand; 1 Epic, 8 to 15 Stories. +- **GitHub:** Library updates land via versioned PR; downstream consumers update on their own cadence. + +--- + +## 6. Website refresh (4 to 8 weeks) + +Existing site. Either a partial refresh (specific sections) or a full overhaul. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | Current site assessment, gaps, priorities | +| Direction | 1 week | Refreshed brief if positioning has shifted | +| Production | 2 to 4 weeks | Voice updates, copy, design, build | +| QA-Launch | 1 to 2 weeks | Cross-page QA, soft launch, full launch | + +### Gates + +Audit approval, direction approval (if direction phase happens; some refreshes skip), per-section copy approval, per-section design approval, QA verification, launch readiness. + +### Lock points + +Audit findings lock at end of Audit. Direction (if produced) locks at end of Direction. Per-section copy locks at copy approval per section. Design tokens lock with the design library; design final per section locks at design approval. + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic per phase, sub-Epics per section if the site is large. +- **Notion:** Brief plus per-section page in a database. +- **Figma:** Library refresh plus per-section design files. +- **GitHub:** Per-section feature branches, branch protection, CI gates per section. + +--- + +## 7. Microsite or product launch (3 to 5 weeks) + +Fixed launch date. Plan backward from the launch. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 3 to 5 days | Launch brief, microsite scope | +| Production | 2 to 3 weeks | Copy, design, build, integrations | +| QA | 3 to 5 days | Cross-flow QA | +| Launch | 2 to 3 days | Coordinated launch sequence | + +### Gates + +Launch brief approval, copy approval, design approval, QA verification, launch readiness. + +### Lock points + +Launch brief locks at end of Brief. Copy locks at copy approval. Design locks at design approval. The launch date is the hardest lock; if QA fails, the launch slips rather than launching with bugs. + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic, multiple Stories per surface (microsite, supporting pages, integrations). +- **Notion:** Launch brief plus dependency table (assets, integrations, third parties). +- **Figma:** Microsite design file referencing brand library. +- **GitHub:** Microsite feature branch plus per-surface sub-branches; branch protection plus pre-launch CI gate. + +--- + +## How to use this file + +Pick the cadence whose project type matches yours. Follow the phase decomposition for your team size (use the team-size-modulation reference for adjustments). Implement in your tool stack using the platform-implementation reference for per-platform setup. Configure the QA verification gate using the automation-and-qa-tooling reference. The pieces compose; this file is the cadence skeleton. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md b/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md new file mode 100644 index 0000000..c481fb5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md @@ -0,0 +1,267 @@ +# Example orchestration + +A complete worked example showing all sections of the orchestration plan populated for a representative scenario. The PM should be able to read this Monday morning and start setting up tools Tuesday. + +## Scenario + +A 4-person team is doing a rebrand for a 15-year-old hospitality brand. The existing brand has a loyal customer base and recognizable identity assets, but the visual register has aged poorly and the digital surfaces haven't been updated since 2019. + +- **Team.** PM (Mira), design lead (Karim), copy lead (Jess), senior engineer (Dax). +- **Timeline.** 6 weeks. +- **Tool stack.** Jira (existing, the team's main work tracker) + Figma + GitHub. Notion is not used by this team. Slack for communication. Loom for client review walkthroughs. +- **AI agent participation.** Claude Code participates in production phase tasks (component library updates, page builds). Claude in Chrome runs QA gates on the staging deployment. Agents have access to the Atlassian MCP and GitHub MCP. Agents move tickets between Todo, In Progress, Waiting, and Blocked but do NOT move to Done; Done requires human verification. +- **Client.** Hospitality brand owner is non-technical. Reviews happen via Loom-recorded walkthroughs scheduled at end of each phase. + +--- + +## 1. Project orchestration plan + +### Phased timeline + +- **Week 1 (Audit).** Existing brand assessment. Audience already known; the audit assesses what to keep, drop, refresh. Output: audit findings document. +- **Week 2 (Direction).** Refreshed creative direction brief. Tone, aesthetic, relationship, sensory positions confirmed. Output: direction artifact. +- **Weeks 3-4 (Identity).** Refreshed logo lockup, color tokens, typography selections, imagery direction. Output: locked identity tokens published to Figma library, identity spec document. +- **Weeks 5-6 (Production).** Voice guide refresh, copy update for top 8 pages, design final per page, engineering implementation, QA verification, launch. + +### Calendar boundaries + +Week 1: Mon-Fri Audit, Friday phase review with brand owner via Loom walkthrough. +Week 2: Mon-Fri Direction, Friday phase review. +Weeks 3-4: Mon-Fri Identity, mid-Week 4 voice approval gate, Friday Week 4 identity approval gate plus Loom walkthrough. +Weeks 5-6: Mon-Tue Week 5 copy approval per page, Wed-Fri Week 5 design final per page (rolling), Mon-Wed Week 6 engineering implementation (rolling), Thu Week 6 QA verification, Fri Week 6 launch. + +--- + +## 2. Per-phase gate specs + +### Audit approval gate (end of Week 1) + +- **Trigger.** All Audit tasks transitioned to Done. Audit findings document complete. +- **Approver.** Brand owner (via Loom walkthrough plus email signoff). Mira reviews internally first. +- **Required to pass.** Audit findings document complete (existing assets categorized as keep / drop / refresh, gaps identified). Brand owner signed off in writing. +- **Blocks until passed.** Direction phase work. + +### Direction approval gate (end of Week 2) + +- **Trigger.** Tone, aesthetic, relationship, sensory positions selected. References curated. Rejection list documented. +- **Approver.** Brand owner plus Karim (design lead). +- **Required to pass.** All four axis positions confirmed in writing. Reference brand list documented. Rejection list signed off. +- **Blocks until passed.** Identity phase production work. + +### Voice approval gate (mid Week 4) + +- **Trigger.** Refreshed voice guide drafted by Jess against locked direction. +- **Approver.** Brand owner plus Jess (copy lead). +- **Required to pass.** Voice guide complete (attributes, tone shifts, vocabulary, paired examples). At least 3 paired examples per major content type. +- **Blocks until passed.** Copy production for shipping pages. + +### Identity approval gate (end of Week 4) + +- **Trigger.** Refreshed logo, color tokens, typography, imagery direction documented and rendered. +- **Approver.** Brand owner plus Karim. +- **Required to pass.** Logo lockup variants reviewed. Selected variants documented. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented. +- **Blocks until passed.** Design production at scale. + +### Copy approval gate (per page, Week 5) + +- **Trigger.** Per-page copy drafted against locked voice guide. +- **Approver.** Brand owner (via Loom walkthrough for top 3 pages; email approval for the other 5) plus Jess. +- **Required to pass.** Copy matches voice guide. Calls-to-action consistent with success criteria. +- **Blocks until passed.** Design final for that page. + +### Design approval gate (per page, Week 5-6) + +- **Trigger.** Design final rendered against locked copy and locked identity tokens. +- **Approver.** Karim plus Mira. +- **Required to pass.** Design references locked identity tokens. Copy reflected exactly as approved. Responsive states designed. Empty/loading/error states accounted for. +- **Blocks until passed.** Engineering of that page. + +### QA verification gate (Thu Week 6) + +- **Trigger.** Engineering signaled complete; ticket transitioned to QA status. +- **Approver.** Automated test suite (Playwright via MCP) plus Claude in Chrome walkthrough; human review on test failure. +- **Required to pass.** Playwright critical-flow suite green. Console error count at 0 for hero load and during critical flows. Accessibility floor maintained (WCAG AA contrast, keyboard navigation, screen reader landmarks). Lighthouse mobile score at or above 85, desktop at or above 95. Visual regression on top 8 pages within tolerance. +- **Blocks until passed.** Status transition to Done. Launch readiness for the affected page. + +### Launch readiness gate (Fri Week 6) + +- **Trigger.** All 8 affected pages have passed QA verification. +- **Approver.** Mira (project owner) plus Dax (launch coordinator). +- **Required to pass.** Deployment checklist complete. Rollback plan documented. On-call coverage assigned for the launch window. Brand owner notified. + +--- + +## 3. Lock-point map + +- **Audit findings lock at end of Week 1.** Existing-asset decisions cannot be revisited without change request triggering re-review of Direction work. +- **Direction locks at end of Week 2.** Axis positions cannot be revisited without change request triggering re-review of Identity, Voice, and Copy work. +- **Identity tokens lock at end of Week 4.** Color tokens, typography selections, logo lockup committed to Figma library v2.0. Downstream design and engineering work references the locked library version. +- **Voice rules lock mid Week 4.** Voice guide v2.0 committed to canonical Confluence page. Downstream copy production references the locked voice guide. +- **Per-page copy locks at copy approval gate (Week 5).** Each page's copy locks individually as it passes its approval gate; design final for that page can begin. +- **Per-page design locks at design approval gate (Week 5-6).** Each page's design locks individually; engineering for that page can begin. +- **Code merges to main (Week 5-6, rolling).** Branch protection prevents direct pushes; PRs merge after CODEOWNERS review and CI gates pass. + +--- + +## 4. Handoff specs + +- **Audit to Direction (Friday Week 1).** Audit findings document URL, summary of gaps and opportunities. Filed in Jira as a Confluence page link in the Direction phase Epic description. +- **Direction to Identity (Friday Week 2).** Direction artifact URL, axis positions documented, reference brand list, rejection list. Filed in Jira as Confluence page links in the Identity phase Epic description. +- **Direction to Voice (Friday Week 2, parallel to Direction-to-Identity).** Same artifacts; Voice phase work begins in parallel with Identity. +- **Identity plus Voice to Copy (Mid-Week 5).** Locked identity tokens (Figma library v2.0 URL), locked voice guide (Confluence URL), per-page scope (Jira tickets). Filed in Jira as Story descriptions per page. +- **Identity plus Copy to Design (Per page, Week 5).** Locked copy (Confluence URL with "approved" marker), locked identity tokens (Figma library v2.0 URL). Filed in Jira as the design-phase Story description per page. +- **Design to Engineering (Per page, Week 5-6).** Final design (Figma frame URL), exported asset library (cloud bucket URL), responsive notes (Figma annotations), motion specifications. Filed in Jira as the engineering-phase Story description per page. +- **Engineering to QA (Per page, Week 6).** Verified deployed-to-staging surface, QA evidence (Playwright run results URL, accessibility audit URL), deployment checklist URL. + +### Adjacent observation routing + +The team's triage queue is a Jira project labeled "Project triage". Filed observations route there without an assignee. Mira triages every Monday and Thursday at standup. Observation content includes: what was observed, why it might matter, link to the work that was happening when noticed, suggested triage priority. The agent uses the Atlassian MCP to file observations. + +--- + +## 5. Tool-stack implementation + +### Jira + +Issue type scheme: +- **Epic:** one per phase (Audit, Direction, Identity, Production-Voice, Production-Copy, Production-Design, Production-Engineering, Production-QA, Launch). +- **Story:** one per work item within a phase. +- **Task:** subtasks under stories. +- **Bug:** for issues filed during QA. + +Custom fields: +- Phase (single-select with the 8 phase names). +- Locked (checkbox). +- Approver (user picker). +- Gate Status (single-select with the 8 standard gates). + +Workflow scheme: 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) with workflow validators preventing premature transitions to Done without QA verification. + +Confluence space: +- Brief page (rebrand brief). +- Direction page (creative direction artifact). +- Audit findings page. +- Identity spec page (logo, color, typography, imagery). +- Voice guide page. +- Copy doc per page (top 8 pages). +- Orchestration plan page (this document, committed to the project space). + +MCP setup: +- Atlassian MCP configured with OAuth credentials (admin one-time setup). +- Initial Epic creation: 8 epics, one per phase, populated by the agent on Day 1. +- Initial Story creation per phase: agent populates from the orchestration plan. + +### Figma + +Library file structure: +- "Tokens" page: color, typography, spacing, motion. +- "Components" page: identity components (logo, badges, branded UI elements). +- "Patterns" page: page-level patterns (hero variants, card patterns, footer). +- "Page templates" page: top 8 page templates for the rebrand. +- "Working files" page: per-page design working files. + +Library publish discipline: +- v1.0 published at start of Week 3 (existing identity, used as baseline). +- v2.0 published at end of Week 4 (refreshed identity, locks at identity gate). +- Per-page working files reference v2.0 starting Week 5. + +### GitHub + +Repository: existing repo for the brand's website. + +Branch protection on main: +- Require PR reviews (1 reviewer minimum). +- Require status checks (lint, type-check, build, accessibility audit, Playwright run). +- Require linear history (squash merges only). + +CODEOWNERS: +- Frontend code: Dax. +- Design tokens: Karim. +- Copy markdown: Jess. + +PR template: +- Ticket reference (Closes RAMP-XXX or Refs RAMP-XXX). +- Summary. +- Test plan. +- Screenshots/GIFs for UI changes. +- QA evidence URL. + +GitHub MCP setup: +- GitHub MCP configured with the repo's PAT. +- Initial PR template committed via MCP. +- CODEOWNERS file committed via MCP. + +--- + +## 6. Automation and QA verification + +### Playwright test suite spec + +Critical flows to test: +- Homepage hero loads and renders. +- Reservation flow (the brand's primary conversion path) end-to-end through booking confirmation. +- Contact form submission (validation, submission, success state). +- Newsletter signup. +- Top-traffic landing pages render without console errors. + +Visual regression on top 8 pages: +- Homepage, About, Reservations, Locations, Menu, Press, Contact, Loyalty. + +Accessibility audit per page using axe-core or equivalent: +- WCAG AA contrast. +- Keyboard navigation reaching all interactive elements. +- Screen reader landmarks present and labeled. + +### Chrome MCP walkthrough scenarios + +For Loom-recorded brand owner reviews and ad-hoc human-readable QA: +- Reservation flow walkthrough with screenshots at each step. +- Brand consistency walkthrough (top 8 pages, evaluating typography and color consistency). +- Mobile responsive walkthrough (the brand's audience is heavily mobile). + +### Evidence trail policy + +- QA evidence (test results, screenshots, GIFs) attached to each ticket as comments. +- 90-day retention for engineering-related evidence. +- Indefinite retention for design final approvals (committed to Confluence with the design spec page). + +### Failure routing + +- Slack channel #project-rebrand-launch is the team's coordination channel. Blockers page Mira via Slack mention. +- P0 blockers (broken reservation flow): page Dax immediately via direct Slack mention. +- P1 blockers (broken page render): surface at next standup. +- P2-P3 blockers: file as adjacent observation in the triage queue. + +--- + +## 7. Risk register + +Cadence-specific risks and mitigations. + +### Risk 1: Brand owner availability for Loom reviews + +The brand owner is busy and may delay phase reviews, slipping the timeline. Mitigation: Mira schedules Loom reviews 1 week in advance with calendar holds. Backup reviewer for direction approval gate is the head of marketing on the brand owner's team (Mira identified this person at project kickoff). + +### Risk 2: Identity refresh expectations vs reality + +The brand owner may expect a more dramatic refresh than the audit recommends, OR may reject the refresh as too dramatic. Mitigation: Karim shares 3 directional moodboards at end of Week 1 to align expectations BEFORE Direction phase locks in. The moodboards are not the final identity; they're directional samples to confirm the team and the brand owner are pointing in the same direction. + +### Risk 3: Engineering surface area + +The website has 8 pages but also a custom CMS, a reservation integration, and an email pipeline. The 6-week timeline assumes only the page surface gets touched. Mitigation: Mira confirmed at project kickoff that CMS, reservations, and email pipeline are out of scope. Documented in the brief. If the brand owner requests adding any of these mid-flight, formal change request triggers timeline review. + +### Risk 4: Agent coordination overhead + +Claude Code participates in production tasks; Claude in Chrome runs QA gates. The agents access the Atlassian and GitHub MCPs. Risk: agent action and human action collide on the same ticket; human commits something the agent had also drafted. Mitigation: agents are not assigned tickets; they take tickets from the "Available for agent" queue (a Jira label). Humans take tickets from the "Available for human" queue. Mira moves tickets between queues at standup. + +### Risk 5: QA verification baseline drift + +Console error baseline is set at start of project. If a third-party script (analytics, heatmap, customer support chat) lands during the project and adds console errors, the baseline shifts. Mitigation: console error baseline is reset weekly during standup. Any new errors that appear get triaged immediately as either an accepted change to baseline (third-party expected) or a regression that needs fixing. + +--- + +## How to use this example + +This example is the format the orchestration plan output takes. Real outputs differ in specifics (different team, different timeline, different stack, different risks) but the structure is the same. The PM reads through, sets up the tools to match, and starts running the plan Tuesday. + +The discipline that makes this work: every section is specific. Generic plans fail. "QA gate must pass" is not a plan; "Playwright critical flows pass, console errors at baseline 0, accessibility floor WCAG AA, Lighthouse mobile at or above 85, visual regression on top 8 pages within tolerance" is a plan. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md b/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md new file mode 100644 index 0000000..74ea2ff --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md @@ -0,0 +1,119 @@ +# Gate definitions + +The 8 standard gates. Each gate includes its trigger, approver, pass criteria, what's blocked until passing, what's already locked from prior gates, and the change-request protocol if the gate is failed or reopened later. + +A gate is the moment a phase transition gets approved. Gates work when their pass criteria are measurable. "Approved" is too vague; "client signed the artifact in writing or in a recorded review" is measurable. The orchestration plan specifies measurable criteria per gate. + +--- + +## 1. Brief approval gate + +Closes the Discovery phase (or Audit phase, on rebrand projects) and opens Direction. + +- **Trigger.** All Discovery tasks transition to Done. The brief artifact is drafted. +- **Approver.** Project owner (typically the client or the founder). For internal work, the senior stakeholder. +- **Required to pass.** The brief artifact is complete (audience, positioning, deliverables, constraints, success criteria all populated). Approver signed in writing OR a recorded review session captured agreement. The brief artifact is committed to its canonical location (Notion brief database row, Confluence page, or repo file). +- **Blocks until passed.** Direction phase work, identity phase work, voice phase work, copy work. +- **Already locked.** Nothing yet; this is the first gate. +- **Change-request protocol.** If the brief is reopened after this gate, the project re-enters Discovery briefly to assess what changed, then re-runs Direction starting from the updated brief. Identity, voice, copy, and design work that depends on the changed brief sections gets re-reviewed. + +--- + +## 2. Direction approval gate + +Closes Direction phase and opens Identity. + +- **Trigger.** Axis positions selected (tone, aesthetic, relationship, sensory). References curated. Rejection list documented. +- **Approver.** Project owner plus the design lead. +- **Required to pass.** All four axis positions confirmed in writing. Reference brands documented with one-line rationale each. Rejection list signed off (what the brief explicitly says no to). +- **Blocks until passed.** Identity phase production work. Voice production work. Any copy production. +- **Already locked.** The brief. +- **Change-request protocol.** If a direction axis is changed after this gate, identity work and voice work that depend on the changed axis get re-reviewed. Tone changes ripple to voice; aesthetic changes ripple to identity; relationship changes ripple to copy register; sensory changes ripple to motion and rhythm decisions. + +--- + +## 3. Identity approval gate + +Closes Identity phase. Opens production at full volume. + +- **Trigger.** Logo system, color tokens, typography selections, imagery direction documented and rendered. +- **Approver.** Project owner plus design lead. +- **Required to pass.** Logo lockup variants reviewed (typically 6 to 12). Selected variants documented with rationale. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented (style, palette, treatment). +- **Blocks until passed.** Design production at scale (component library, page designs). Engineering work that depends on design tokens. +- **Already locked.** Brief, direction. +- **Change-request protocol.** If identity tokens change after this gate, design files that reference the tokens get re-rendered. Engineering work that consumed the old tokens gets reviewed. Voice work is typically unaffected unless typography selection changes the implied tone register. + +--- + +## 4. Voice approval gate + +Closes voice production. Opens copy production at scale. + +- **Trigger.** Voice guide drafted. Tone-shift table populated. Vocabulary list compiled. Paired examples written. +- **Approver.** Project owner plus copy lead. +- **Required to pass.** Voice guide complete (attributes, tone shifts, vocabulary, grammar, paired examples). At least 3 paired examples per major content type (hero copy, body, microcopy). Voice signed off in writing. +- **Blocks until passed.** Copy production for shipping pages. +- **Already locked.** Brief, direction, identity (or identity in progress; voice can lock alongside identity if both phases overlap). +- **Change-request protocol.** If voice rules change after this gate, all copy that has been drafted against the old rules gets re-reviewed. The copy rework varies by scope: a vocabulary substitution is light; a tone-shift table change can mean rewriting from scratch. + +--- + +## 5. Copy approval gate + +Per-page or per-deliverable. Closes copy production for that page or deliverable. + +- **Trigger.** Copy drafted against the locked voice guide. Internal review complete. +- **Approver.** Project owner plus copy lead. For per-page copy, the page owner if different. +- **Required to pass.** Copy matches the voice guide (verifiable by running the voice-guide checklist). All sections complete. Microcopy populated. Calls-to-action consistent with the brief's success criteria. +- **Blocks until passed.** Design final for that page or deliverable. Engineering of the copy-dependent surface. +- **Already locked.** Brief, direction, identity, voice. +- **Change-request protocol.** Per-page copy changes after this gate trigger re-review of the design final for that page (because design length, hierarchy, and rhythm depend on copy length). Engineering work for that page may need to be revisited if the copy change affects layout. + +--- + +## 6. Design approval gate + +Per-page or per-deliverable. Closes design production for that page or deliverable. + +- **Trigger.** Design final rendered against locked copy and locked identity tokens. +- **Approver.** Design lead plus project owner. +- **Required to pass.** Design references the locked identity tokens (no off-token color, type, or spacing values). Copy is reflected exactly as approved (no copy edits hidden in the design). Responsive states designed. Empty states, loading states, error states accounted for. +- **Blocks until passed.** Engineering of the design-dependent surface. +- **Already locked.** Brief, direction, identity, voice, copy. +- **Change-request protocol.** Design changes after this gate trigger engineering re-review for the affected surface. The change-request protocol routes through the design lead to assess scope (token-level changes are light; component or layout changes are heavy). + +--- + +## 7. QA verification gate + +Per-surface. Closes engineering and verification, opens launch readiness for that surface. + +- **Trigger.** Ticket transitions to "QA" status (developer signaled engineering complete). +- **Approver.** Automated test suite, with human review on test failure or ambiguous result. +- **Required to pass.** Defined Playwright critical-flow test suite green. Console error count at or below baseline (specify the baseline per project; for a typical web app, 0 errors at hero load, 0 errors during critical flows). Accessibility floor maintained: WCAG AA contrast ratios on all text, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled. Performance budgets met (Lighthouse mobile score at or above project target, Core Web Vitals at or above project target). Visual regression on key pages within tolerance. +- **Blocks until passed.** Status transition to Done. Launch readiness for the affected surface. +- **Already locked.** Code merged to main, design tokens, copy, identity, voice, direction, brief. +- **Change-request protocol.** Failure routes the ticket to Blocked status (not back to In Progress). The blocker reason is documented in the ticket comment. If the failure surfaced something unrelated to the ticket's scope (e.g., a regression in a sibling page), an adjacent observation is filed in the project triage queue. The human is paged via the configured channel. The agent does NOT continue retrying autonomously. + +--- + +## 8. Launch readiness gate + +Closes the project (or the launch phase of a multi-phase project). + +- **Trigger.** All affected surfaces have passed the QA verification gate. +- **Approver.** Project owner plus the launch coordinator (typically the PM or the senior engineer on rotation). +- **Required to pass.** Deployment checklist complete (environment variables set, secrets rotated, third-party integrations live, monitoring active, alerting configured). Rollback plan documented (which command, who runs it, where logs go). Launch communications drafted (internal: who knows the launch is happening; external: any customer-facing announcement). On-call coverage assigned for the launch window. +- **Blocks until passed.** The actual production deploy. +- **Already locked.** Everything: brief, direction, identity, voice, copy, design, code, QA evidence. +- **Change-request protocol.** Launch readiness failure typically delays the launch rather than reopening upstream gates. If the failure is severe (a critical bug found in pre-launch QA), the affected surface returns to In Progress for fix, then re-runs through Engineering and QA verification before launch can proceed. + +--- + +## How gates compose + +Gates are not isolated. Each gate locks artifacts that downstream gates assume are stable. A QA verification failure that traces to a copy bug means the copy approval gate produced bad output, which traces back to either a voice rule that wasn't applied or a brief that wasn't reflected. The gate chain is the audit trail. + +When a gate is reopened, the change-request protocol cascades downstream. The orchestration plan specifies the protocol per gate so the team knows in advance what re-review work a change triggers. The cost of a change is visible at the moment it's requested, not discovered after the fact. + +The QA verification gate is the gate that does the most work for the team. It is the gate that prevents "Done" from being self-reported. Configure it carefully; trust it once configured. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md b/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md new file mode 100644 index 0000000..0fd39c5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md @@ -0,0 +1,143 @@ +# Handoff protocols + +A handoff is the moment work transfers between phases or skills. Without explicit handoff specs, the receiving phase opens a half-dozen Slack threads to find what they need. With them, the work moves cleanly because the receiving phase knows exactly what artifacts to expect, what's locked, and what's still open. + +This file covers the 7 standard handoffs plus an 8th cross-cutting handoff: the adjacent-observation routing. + +--- + +## 1. Discovery to Brief + +The first handoff. Discovery findings transfer to brief drafting. + +- **What's transferred.** Audience research notes (interview summaries, persona documents, audience-side observations). Positioning notes (competitive landscape, differentiation hypotheses). Reference materials gathered during discovery (brands, articles, examples that surfaced). +- **What's locked.** Nothing yet. Everything is still open. +- **What stays open.** All of it. Discovery is input, not decision. +- **Common breakdown.** Discovery findings get summarized too aggressively; the brief drafter loses the nuance. Mitigation: hand off the full notes plus a synthesis, not just the synthesis. +- **Artifact specification.** Discovery findings live in a Notion database, a Google Doc, or a folder of markdown files. The handoff includes a link plus a one-paragraph synthesis. +- **Platform support.** Notion: relation property from brief row to discovery findings. Jira: linked issue. Linear: project relationship. + +--- + +## 2. Brief to Identity + +After brief approval. The identity work begins against the locked brief. + +- **What's transferred.** Approved brief (audience, positioning, deliverables, constraints). Direction artifact (axis positions). Reference brand list. Rejection list. +- **What's locked.** Brief is locked. Direction is locked. Audience and positioning cannot be revisited without change request. +- **What stays open.** Everything inside the identity scope: logo system, color, typography, imagery direction, motion. The identity team picks within the constraints the brief and direction set. +- **Common breakdown.** The identity team interprets the rejection list loosely. A "no laurel mark" rejection becomes "well, our laurel is different". Mitigation: rejection-list adherence is a gate criterion at identity approval. +- **Artifact specification.** Brief lives in its canonical location (Notion brief row, Confluence page, or repo file). Direction artifact is a sibling document. Both URLs go in the identity-phase Epic or Project description. +- **Platform support.** Jira: Epic description with links. Linear: Project description with attached docs. Notion: relation properties. + +--- + +## 3. Brief to Voice + +In parallel with Brief-to-Identity. Voice work begins against the locked brief and direction. + +- **What's transferred.** Approved brief. Direction artifact (specifically the tone-axis position). Reference voice samples (other brands the team likes for their voice). +- **What's locked.** Brief, direction. +- **What stays open.** Voice attributes, tone-shift rules, vocabulary choices, grammar rules, paired examples. +- **Common breakdown.** Voice gets started without referencing the locked tone-axis position; the writer drafts in their natural voice rather than the project's. Mitigation: voice production opens with a tone-axis check ("the brief says Provocative; here is what Provocative implies for vocabulary, sentence shape, and rejection list"). +- **Artifact specification.** Tone-axis position from direction artifact. Reference voice samples as a Notion subpage or a markdown file with quoted samples. +- **Platform support.** Same as Brief-to-Identity. + +--- + +## 4. Identity plus Voice to Copy + +After identity approval and voice approval. Copy production begins. + +- **What's transferred.** Identity tokens (typography selections, color tokens, spacing). Voice guide (attributes, tone shifts, vocabulary, paired examples). Page or deliverable scope (which pages, which sections, what each section needs). +- **What's locked.** Brief, direction, identity tokens, voice rules. +- **What stays open.** Per-page copy choices within the locked voice. Calls-to-action language. Section ordering decisions where the design has not yet been finalized. +- **Common breakdown.** Copy is drafted for length without the typography in mind, and lands in design as either too long or too short for the rendered hero. Mitigation: copy production references the typography selection from the start; the writer drafts knowing which weight and size the copy will live in. +- **Artifact specification.** Identity tokens published in Figma library or in a tokens markdown file. Voice guide as a Notion page or markdown file. Page scope as a Jira/Linear ticket per page. +- **Platform support.** Figma library is the canonical token source. Jira/Linear ticket per page or section. + +--- + +## 5. Identity plus Copy to Design + +After copy approval per page. Design final begins for that page. + +- **What's transferred.** Locked copy (final approved text). Identity tokens (typography, color, spacing). Voice guide (for microcopy and any error or empty states the design generates). +- **What's locked.** Brief, direction, identity, voice, copy for the affected page. +- **What stays open.** Design layout decisions, responsive breakpoint behavior, motion design, empty/loading/error states. +- **Common breakdown.** Design starts before copy locks. Length, rhythm, and hierarchy get designed against placeholder text; when copy lands, the design has to be reworked. Mitigation: copy locks per page before design final starts. If parallel work is needed, design produces a wireframe with placeholder copy AND a flag noting "real copy pending; layout subject to revision". +- **Artifact specification.** Locked copy in the canonical copy doc with an explicit "approved" marker. Identity tokens in Figma library. Page scope from copy-phase ticket. +- **Platform support.** Figma frame per page, linked to ticket in Jira/Linear. + +--- + +## 6. Design to Engineering + +After design approval per page. Engineering builds the page. + +- **What's transferred.** Final design (Figma file URL). Tokens (referenced from Figma library). Asset library (images, icons, illustrations exported and named per convention). Component specifications (any new components designed). Responsive behavior notes. Motion specifications (entry, exit, hover, loading states). +- **What's locked.** Brief, direction, identity, voice, copy, design final. +- **What stays open.** Implementation choices (state management, framework patterns, accessibility implementation, performance optimization). Component naming if new components. +- **Common breakdown.** Asset exports happen ad-hoc as engineering needs them, leading to inconsistent file names, missing variants, and back-and-forth Slack messages. Mitigation: design phase exports a complete asset library (using the team's naming convention) before handoff. Engineering pulls from the library, does not request new exports during build unless missing. +- **Artifact specification.** Figma URL, exported asset folder (cloud bucket or repo path), responsive notes as Figma annotations or a sibling markdown doc. +- **Platform support.** Figma URL in the engineering ticket. Asset folder URL or path in the ticket. PR template references the design ticket. + +--- + +## 7. Engineering to Launch + +After QA verification per surface. The surface goes to launch. + +- **What's transferred.** Verified surface (deployed to staging, tested). QA evidence (Playwright run results, accessibility audit results, performance audit results, console error counts). Deployment checklist for this surface. Rollback plan. +- **What's locked.** Everything: brief, direction, identity, voice, copy, design, code merged to main, QA evidence. +- **What stays open.** Launch coordination (which surface launches first, monitoring during launch window, on-call coverage). +- **Common breakdown.** Launch happens before all surfaces have passed QA verification. Result: one surface launches with bugs, recoverable with rollback if monitoring catches it. Mitigation: launch readiness gate requires ALL surfaces to have passed QA verification, not just the most-prominent surface. +- **Artifact specification.** QA evidence linked to ticket (screenshots, GIFs, test result logs). Deployment checklist as a runbook document. Rollback plan as a sibling runbook document. +- **Platform support.** GitHub PR with QA artifact attachments or evidence URL. Linear or Jira ticket with the runbook URL. + +--- + +## 8. Adjacent observation handoff (cross-cutting) + +The handoff that fires when an agent or person, while working on Task X, notices something about Task Y or Surface Z that is not the current task but is contextually adjacent. + +### Examples + +- Working on copy for the homepage hero, the writer notices the footer copy is inconsistent with the new voice. Filing the footer inconsistency as an observation, not stopping the homepage work. +- Running QA on the pricing page, an agent notices the contact form on the about page has a console error. Filing the contact form error as an observation, not pausing the pricing-page QA. +- Updating the Figma design library, the designer notices a deprecated component is still being used in the dashboard mockups. Filing a usage-cleanup observation, not modifying the dashboard mockup. +- Reviewing a PR, an engineer notices a typo in a docstring in an unrelated file. Filing a typo observation, not blocking the PR review on it. + +### Why this handoff matters + +Without it, the team has two bad options. Option one: stop the current work and address the observation, derailing focus. Option two: ignore it, lose the context, never come back to it. The adjacent-observation handoff lets the current work proceed while preserving the finding for triage. + +### Routing + +The observation gets filed in a project triage queue, NOT directly assigned to anyone. The triage queue is reviewed on a regular cadence (typically daily standup or weekly grooming). The PM or tech lead triages the observation: discard if it's not relevant, file as a normal ticket if it is, attach to an existing ticket if it's a fragment of larger work. + +### Content of the observation + +Each filed observation includes: + +- **What was observed.** A specific factual statement (the footer says "Get in Touch" while the new voice would say "Reach out"). +- **Why it might matter.** A brief rationale (voice consistency, user-facing inconsistency, latent bug). +- **Where it was noticed.** A link to the work that was happening when the observation surfaced (the PR, the Figma frame, the Notion page). +- **Suggested triage priority.** The reporter's gut call (low / medium / high). The triager makes the actual call; the suggestion is just signal. + +### Platform support + +- **Jira.** A separate "triage" project or a labeled queue inside the main project. Observations get filed without an assignee; the triager assigns at triage time. +- **Linear.** A "Triage" inbox is built into Linear and works exactly for this purpose. +- **Notion.** A triage database; the assignee field stays empty until triage. +- **GitHub.** Observations filed as issues without an assignee; CODEOWNERS may auto-route the issue to the relevant team for triage. + +The orchestration plan specifies which platform's triage queue is the canonical one for the project (typically the same platform as the main work) and the triage cadence (daily standup or weekly grooming). Without those specifics, observations either pile up untriaged or scatter across channels and get lost. + +--- + +## How handoffs compose with gates + +A gate closes a phase. A handoff opens the next phase's work against the gate's locked output. The two patterns reinforce each other: gates make sure nothing premature ships; handoffs make sure the receiving work has what it needs to start. + +A failed gate triggers a handoff backward (rework the prior phase). A failed handoff (artifact missing, scope unclear) is itself often the symptom of a gate that didn't enforce its pass criteria. When a handoff goes wrong, audit the prior gate's criteria. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md b/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md new file mode 100644 index 0000000..f62ee1b --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md @@ -0,0 +1,174 @@ +# Platform implementation + +How the orchestration plan implements in each platform. Per platform: workflow representation (how phases, gates, lock points, and handoffs map), MCP integration notes (what AI agents can do via the platform's MCP), and CLI alternatives (where the CLI is the better tool than MCP). + +For setup screenshots and additional team patterns, consult each platform's official documentation alongside this file. + +--- + +## Jira / Atlassian + +### Workflow representation + +- **Phase representation.** Each phase becomes an Epic. Stories or Tasks live within the Epic. Custom fields tag the Phase explicitly. +- **Gate representation.** Workflow status. The 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) maps to Jira's workflow statuses, with workflow validators or transitions enforcing gate rules. A custom "Gate Status" field tracks gate state separately from issue status. +- **Lock-point representation.** Custom field "Locked" (boolean) on the parent artifact (Epic for phase locks, Story for per-page locks). Locked issues display a visible label so reviewers know not to make untracked changes. +- **Handoff representation.** Issue link types ("Blocks", "Is blocked by", "Relates to"). Linked Confluence page for the artifact (brief, direction, voice guide, copy doc). +- **Concrete setup snippet.** Issue type scheme: Epic, Story, Task, Subtask, Bug. Custom fields: Phase (single-select with phase names), Locked (checkbox), Approver (user picker), Gate Status (single-select with the 8 standard gates). Workflow scheme: 5-status taxonomy with validators preventing premature transitions. + +### MCP integration notes + +- **Availability.** Official remote MCP server, launched 2025. +- **References.** [Atlassian's Remote MCP Server announcement](https://www.atlassian.com/blog/announcements/remote-mcp-server) and [github.com/atlassian/atlassian-mcp-server](https://github.com/atlassian/atlassian-mcp-server). +- **Capabilities.** Jira issue CRUD, status transitions, comment posting, JQL queries, Confluence page operations (read, write, update). Authentication via OAuth or API token. +- **What the orchestrator skill can populate via MCP.** Initial epic structure from the orchestration plan (one epic per phase). Initial issue tree (stories per work item). Custom field values from the orchestration plan (Phase, Approver, Gate Status). Comments documenting handoffs and gate transitions. Confluence pages for the brief, direction artifact, voice guide, and orchestration plan itself. +- **Practical limits.** Workflow scheme creation typically requires admin-level UI setup; MCP is better at populating against an existing scheme than at configuring the scheme from scratch. Heavy Confluence content edits lose Atlassian Document Format (ADF) details through MCP roundtrips when the content is rich (tables, callouts, complex code blocks). For simple page content, MCP roundtrips work; for heavily-formatted content, edit in the UI or use the CLI. + +### CLI alternatives and when to use them + +- **Atlassian official CLI (acli)** plus community alternatives (jira-cli, etc.). +- **When CLI is the better choice.** + - Bulk operations across many tickets (200+ issues). MCP roundtrips become token-expensive at scale; CLI is more efficient. + - Heavy Confluence content edits where ADF formatting matters. CLI tools that parse and write ADF directly preserve formatting better than MCP roundtrips. + - Scripted reporting (export issues to CSV, generate burndown reports, run JQL across multiple projects). + - CI integration (running JQL in a CI step to validate that all blockers are resolved before deploy). +- **Pattern note.** Some teams mirror Jira and Confluence content as local markdown files in a `.atlassian/` folder, syncing periodically via CLI. This pattern trades simplicity for power. Document it as one viable approach for engineering-heavy teams; PMs will rarely need it. + +--- + +## Linear + +### Workflow representation + +- **Phase representation.** Each phase becomes a Project. Cycles (Linear's time-boxed sprints) sit within the project for week-by-week granularity. +- **Gate representation.** Project status workflow plus issue status workflow. Linear's status workflow customizes to the 5-status taxonomy. Labels mark gate state per issue (e.g., "gate:identity-approved", "gate:qa-pending"). +- **Lock-point representation.** Labels (e.g., "locked:identity-tokens", "locked:voice"). Locked issues stay visible in their project but cannot be reopened without an explicit label removal. +- **Handoff representation.** Project relationships (predecessor / successor projects), issue dependencies, and Linear's automatic mention parsing for cross-references. +- **Concrete setup snippet.** Project template per project type (new brand build, rebrand, etc.) with phases pre-populated as projects, cycles configured, label taxonomy defined. Status workflow customized to include Blocked as a first-class status (Linear ships with Backlog, Todo, In Progress, Done, Cancelled by default; add Waiting and Blocked). + +### MCP integration notes + +- **Availability.** Official, well-supported. +- **Reference.** [linear.app/docs/mcp](https://linear.app/docs/mcp). +- **Capabilities.** Issues, projects, cycles, teams, labels, comments, attachments. Full CRUD on most entities; webhooks for event-driven workflows. +- **What the orchestrator skill can populate via MCP.** Project setup with cycles. Label taxonomy from the orchestration plan. Initial issue population per phase. Project description and milestones. Status workflow customization. Initial assignee and reviewer assignments per the orchestration plan's review-by routing. +- **Coverage note.** Linear's MCP coverage is the most complete of the 5 platforms. For teams running a Linear-based stack with AI agents, this MCP is the recommended starting point. The agent can do almost everything programmatically. + +### CLI alternatives and when to use them + +- **CLI status.** No widely-adopted Linear CLI. The MCP coverage is sufficient that CLI is rarely needed. +- **API direct calls** remain an option for scripted setup if MCP isn't available in the runtime context. +- **When the API is the better choice.** Bulk import scripts when migrating from another platform. Scheduled reports run from CI. Webhook handlers for event-driven external integrations. + +--- + +## Notion + +### Workflow representation + +- **Phase representation.** Brief database with one row per project. Related databases for direction docs, identity specs, voice guides, copy decks. Each related database has its own rows; relation properties tie everything to the canonical brief. +- **Gate representation.** Status property on each artifact row. Phase view filters the database by status to surface what's open vs locked. +- **Lock-point representation.** A "Locked" checkbox or status property on each artifact row. Filtered views surface locked vs unlocked artifacts. +- **Handoff representation.** Relation properties between databases. The brief row relates to the direction row, which relates to the identity spec row, which relates to the voice guide row, etc. +- **Concrete setup snippet.** Brief database schema: Title, Status, Phase, Locked, Approver, Owner, Notes. Related databases: Direction, Identity, Voice, Copy, Design, QA Evidence. Relation properties tie each related row back to the brief. Dashboard view per phase. + +### MCP integration notes + +- **Availability.** Official. +- **Reference.** [developers.notion.com/guides/mcp/overview](https://developers.notion.com/guides/mcp/overview). +- **Capabilities.** Database queries, page CRUD, property updates, block-level reads, search. +- **What the orchestrator skill can populate via MCP.** Brief-as-database-row schema creation (with the property set from the orchestration plan). Relation property setup between briefs and project artifacts. Initial brief content population from the orchestration plan. Dashboard view configuration where the view config supports it (with caveats; some view configurations remain UI-only). +- **Practical limits.** Workspace-level permissions and team membership remain UI-driven; MCP is most useful AFTER initial workspace setup. Some view types (calendar views, certain board views with custom grouping) cannot be created via MCP and must be set up in the UI. + +### CLI alternatives and when to use them + +- **Community CLIs.** notion-cli and similar tools exist but are less mature than the MCP. +- **When the CLI is the better choice.** Exporting databases for backup. Bulk content migration from another tool. Scripted database schema changes (adding properties across hundreds of rows). +- **For most teams.** The MCP is sufficient. CLI tools become useful only for specialized operations the MCP can't handle. + +--- + +## Figma + +### Workflow representation + +- **Phase representation.** Library file with frame folders per phase: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status surfaces in the Figma comments and frame metadata. +- **Gate representation.** Frame status (Ready for review / In review / Approved). Components versioned in the library; outdated components marked as deprecated rather than deleted (downstream files still reference them). +- **Lock-point representation.** Library publish state. Once a library version is published, dependent files reference that version. Token changes ship as a new library version, which downstream files explicitly opt into. +- **Handoff representation.** Frame URL plus exported assets. Engineering handoff uses Dev Mode for token export and component spec. +- **Concrete setup snippet.** Library file structure: top-level pages for "Tokens", "Components", "Patterns", "Page templates", "Working files". Within each, frame folders per phase. Frame-level review status set via Figma's standard comment-and-status workflow. Library publish discipline: identity tokens publish at the identity gate; the library version is the lock point. + +### MCP integration notes + +- **Availability.** Figma Dev Mode MCP exists but is dev-mode-focused (component inspection, code generation, design token export). +- **Reference.** Figma's [Dev Mode documentation](https://www.figma.com/dev-mode/). +- **Capabilities (Dev Mode MCP).** Component property reads. Design token export (color, typography, spacing). Frame inspection (layer tree, properties, constraints). Component variant queries. +- **What the orchestrator skill can populate via MCP.** Limited. Library structure recommendations and frame organization remain primarily manual setup. The MCP is more useful for downstream developer handoff than upstream design ops. +- **Practical limits.** Design library creation, frame organization, library-level permissions, and team membership are UI-driven. Treat the orchestrator skill's Figma recommendations as documentation for the design lead, not as automation targets. + +### CLI alternatives and when to use them + +- **Figma API.** Can be invoked via custom scripts for token export, asset download, and metadata queries. No first-party CLI for design ops. +- **When the API is the better choice.** Token export scripts that run in CI to update a design system repository. Asset download automation for engineering handoffs. Metadata reporting (audit how many frames are in review status across the library). +- **For most cases.** The design lead implements Figma orchestration manually following the skill's recommendations. Automation is layered in only when the project is large enough to warrant the engineering investment. + +--- + +## GitHub + +### Workflow representation + +- **Phase representation.** Issues for non-engineering tracking (when GitHub is the canonical platform; otherwise Jira/Linear lead). Branches per feature with naming convention `{type}/{ticket}-{slug}`. PRs for design and engineering review. +- **Gate representation.** Branch protection on `main`. PR review requirements. CODEOWNERS for review routing. GitHub Actions for CI gates (lint, test, build, deploy preview). +- **Lock-point representation.** Branch state. Once code is merged to main, it's locked unless a follow-up PR amends it. Tags mark release lock points. +- **Handoff representation.** PR description references the originating ticket. PR review by CODEOWNERS routes to the right reviewer. PR merge triggers ticket auto-transition (configured per platform combination). +- **Concrete setup snippet.** Branch protection: require PR reviews before merge, require status checks (CI), require linear history (rebase or squash, no merge commits). CODEOWNERS file routes PRs to the relevant team. PR template requires ticket reference, summary, test plan, screenshots/GIFs for UI changes. GitHub Actions workflow runs CI gates on every PR. + +### MCP integration notes + +- **Availability.** Official. +- **Reference.** [github.com/github/github-mcp-server](https://github.com/github/github-mcp-server). +- **Capabilities.** PR ops (create, comment, review, merge). Issue ops (create, comment, close, label). File content (read, write). Branch protection (read; configuration is mostly UI/API-driven). Repository search. Code search. Workflow runs (read). +- **What the orchestrator skill can populate via MCP.** PR template files. Issue templates. CONTRIBUTING.md and review-protocol docs. Initial issue tree from the orchestration plan when GitHub is the canonical work tracker. CODEOWNERS file. GitHub Actions workflow files committed to `.github/workflows/`. +- **Practical limits.** Branch protection rulesets are typically configured via GitHub UI or repository settings API (not MCP); the orchestrator skill's branch protection recommendations remain documentation rather than automation. Repository creation, team membership, and organization-level settings are UI-driven. + +### CLI alternatives and when to use them + +- **gh CLI.** The dominant tool for GitHub operations. Officially maintained, broadly adopted. +- **When to prefer gh CLI over MCP.** + - Bulk PR operations (merging 20 dependabot PRs in a single sweep). + - Scripted workflows (a deploy script that creates a release, tags, and updates a changelog). + - Repository setup automation (create a new repo, push initial commits, set up labels and branch protection). + - When token cost matters on heavy operations. The CLI is more efficient than MCP roundtrips for repetitive tasks. +- **Hybrid pattern.** Most production setups use both. MCP for navigation and orchestration ("show me open PRs assigned to me", "comment on PR #123 with this summary"); gh CLI for transactional and bulk operations ("create a PR from this branch with these reviewers", "merge these 10 dependabot PRs"). The two tools complement each other. + +--- + +## Cross-platform patterns + +### Code-to-ticket linkage + +The standard convention for linking PRs and commits back to tickets: + +- **Branch naming.** `{type}/{ticket}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform (RAMP for the team's main project in Jira, LIN for Linear, etc.). +- **PR descriptions.** Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- **Commit messages.** Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. + +### Status synchronization + +When a PR merges, the linked ticket auto-transitions. Configure via the linked platform's automation: + +- **Jira automation.** "When PR merged, transition issue to Done" (with QA verification gate enforced upstream so this is safe). +- **Linear's auto-transition.** Linear-GitHub integration auto-moves issues based on PR state. +- **GitHub Actions.** A workflow that runs on PR merge and posts a comment to the linked Linear/Jira issue. Useful when the platform's native integration doesn't cover the team's exact transition rules. + +### Multi-platform stacks + +Common combinations: + +- **Linear + GitHub.** Most common for tech teams. Linear's MCP is mature; GitHub's MCP is mature. The two integrate well via Linear's GitHub integration plus PR/branch naming conventions. +- **Jira + GitHub.** Most common for enterprise. Atlassian remote MCP plus GitHub MCP cover the orchestration; workflow setup is more involved than Linear because Jira's workflow flexibility means more setup decisions. +- **Notion + Linear + GitHub.** PM-led with engineering sub-tracking. Notion holds the brief and creative artifacts; Linear holds the engineering work; GitHub holds the code. Notion-Linear linking is via relation property pointing to the Linear issue URL; Linear-GitHub linking is via Linear's native integration. +- **Notion + Figma + GitHub.** Creative-led with engineering handoff. Notion holds the brief; Figma holds the design; GitHub holds the code. This combination has the lightest engineering tooling and works for design-led projects with simple production paths. + +The orchestration plan specifies the canonical platform for each work type and the linkage convention between platforms. Without that specification, work scatters across platforms and links break. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md b/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md new file mode 100644 index 0000000..246ba2f --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md @@ -0,0 +1,65 @@ +# Team-size modulation + +A 2-person team and a 12-person team need different orchestration. The framework (phases, gates, lock points, handoffs) is the same; the cadence's review density, sync ceremony, and tool-stack adjustments scale with team size. + +This file covers four scales: solo, small (2-3), medium (4-7), large (8+). For each: review density, sync cadence, handoff formality, risk profile, tool-stack adjustments, and AI agent participation pattern. + +--- + +## Solo (1 person) + +Everything is the same person playing every role. The brief author, identity designer, voice writer, copy writer, design lead, and engineer are all you. + +- **Review density.** Self-review only. Per-phase self-review checklists replace formal gates. The risk is that nothing actually catches mistakes; the discipline is to step away from the work between drafting and reviewing (overnight is best, an afternoon walk is the minimum). +- **Sync cadence.** Daily plan, weekly review against the orchestration plan. Document the daily plan and the weekly review in a project state file (CLAUDE.md, AGENTS.md, or .agent/state.md). +- **Handoff formality.** Inline. Self-handoffs document themselves in the project state file rather than as separate artifacts. +- **Risk profile.** Phases blur together. Lock points get unfrozen without ceremony. The brief that was approved last week becomes "well, I had a better idea, let me just edit it" and downstream work drifts. +- **Tool-stack adjustments.** Skip Jira workflow validators, Linear cycle ceremony, formal review routing. Use the simplest tool the project needs (often Notion or markdown files in a repo). Resist setting up tooling beyond what's actually used; solo projects fail more often from over-tooling than from under-tooling. +- **AI agent participation pattern.** Heavy. Solo work benefits most from agent participation because the agent is the second pair of eyes that solo work otherwise lacks. The agent runs QA verification gates, reviews copy against the locked voice, runs accessibility audits, and surfaces patterns the solo person might miss. The orchestration plan output specifies which agent runs at which gate. + +--- + +## Small (2-3 people) + +Single reviewer per gate. Async handoffs are fine. Daily standup is sufficient for sync. + +- **Review density.** One reviewer per gate. The team picks a primary reviewer per phase based on expertise (design lead reviews identity gates, copy lead reviews voice and copy gates, the senior engineer reviews QA verification and launch readiness). +- **Sync cadence.** Daily 15-minute standup. Weekly 60-minute phase review. Async messaging in between. +- **Handoff formality.** Documented but inline (a Notion page comment, a Linear issue description, a Slack message in the project channel). The small team can rely on shared context that larger teams cannot. +- **Risk profile.** The single reviewer becomes a bottleneck. When the design lead is the only person who can pass the identity approval gate and they're on PTO, the project blocks. Mitigation: the orchestration plan specifies a backup reviewer per gate. +- **Tool-stack adjustments.** Light tool setup. Linear's default workflow is fine; Jira can run with a basic workflow scheme; Notion runs with basic database schemas. Don't set up complex automations until the team feels the lack of them. +- **AI agent participation pattern.** Moderate. Agents handle production tasks, QA verification, and adjacent observation filing. Humans handle reviews, gate approvals, and decisions that require taste or political judgment. The orchestration plan specifies which roles agents fill and which stay human. + +--- + +## Medium (4-7 people) + +Multiple reviewers, async sync points, weekly phase reviews. The team is large enough that shared context erodes; documentation matters more. + +- **Review density.** Two reviewers per gate (one primary, one secondary for cross-check). Reviewer rotation across phases prevents one person from becoming the bottleneck. +- **Sync cadence.** Daily standup. Weekly phase review. Bi-weekly cross-track sync if there are parallel tracks. Async messaging in between with explicit channels per phase. +- **Handoff formality.** Documented in the canonical platform (Jira issue, Linear project, Notion database row). Slack threads are fine for discussion but the canonical record lives in the work-tracking platform. +- **Risk profile.** Review density becomes the gating factor. Reviewers stack up at end of phase, leading to fatigue reviews and rubber-stamped approvals. Mitigation: within-phase mini-gates that flatten review demand. Instead of reviewing 8 deliverables on phase-end Friday, review 2 mid-week and 6 at phase-end. +- **Tool-stack adjustments.** Custom fields, labels, and automation start to matter. Set up workflow validators that prevent premature transitions. Set up custom views per role (designer view, engineer view, PM view) so each person sees only what's relevant to them. +- **AI agent participation pattern.** Agents handle QA verification gates, surface adjacent observations, and run reports (which tickets are stuck, which gates are open, which assignees are overloaded). Humans handle reviews and approvals. The agent's role expands from "do production work" to "monitor the orchestration plan and surface drift". + +--- + +## Large (8+ people) + +Formal phase reviews, dedicated PM for orchestration, multiple parallel tracks. Cross-track drift is the dominant risk. + +- **Review density.** Three or more reviewers per gate. Phase reviews become formal meetings with prepared agendas. Reviewer rotation is mandatory; the project cannot rely on any one person. +- **Sync cadence.** Daily standup per track. Weekly cross-track sync. Bi-weekly project-wide review. Monthly stakeholder review for projects spanning multiple months. +- **Handoff formality.** Strict. Every handoff specifies artifacts, locked items, and change-request protocols in writing. Async handoffs without artifact specification break large teams; the receiving track wastes a week trying to figure out what was actually handed off. +- **Risk profile.** Cross-track drift. Track A and Track B both interpret the brief differently; by week 3 the two tracks read as different brands. Mitigation: a dedicated brief-owner role whose job is to maintain the brief as canonical reference, plus cross-track sync ceremonies and explicit change-request protocols. Brief drift is a leading indicator; the brief-owner role exists to catch it before it becomes track drift. +- **Tool-stack adjustments.** Full workflow scheme with validators. Custom fields tracking phase, gate status, approver, locked status. Multiple boards or views per track. Automation rules for status synchronization across linked platforms (Jira-GitHub, Linear-GitHub). Reporting dashboards. +- **AI agent participation pattern.** Agents become orchestration monitors. The agent's role is to track phase status across tracks, surface drift, run cross-track sync prep (which tracks are on schedule, which are slipping), file adjacent observations across track boundaries, and run QA verification gates. The agent is most valuable at the cross-track surface where humans cannot easily hold all the context. + +--- + +## How to choose your scale's pattern + +Match the cadence to actual team size. The most common mistake is to use a small-team cadence on a medium-team project, which leads to the single-reviewer bottleneck, OR to use a large-team cadence on a small-team project, which leads to ceremony overhead that nothing earns. + +When the team scales mid-project (a 2-person small team grows to 5 people during production phase, for example), the orchestration plan should specify the transition: at what point does the cadence shift, what new reviewers come online, what additional ceremonies start. The plan's risk register should flag scaling moments as a known risk because cadence transitions are themselves a source of drift. diff --git a/dist/pi/.agents/skills/interactive-product-tour/SKILL.md b/dist/pi/.agents/skills/interactive-product-tour/SKILL.md new file mode 100644 index 0000000..59256aa --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/SKILL.md @@ -0,0 +1,251 @@ +--- +name: interactive-product-tour +description: "Designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. Honest about tooltip-spam (visual noise that users develop blindness to), one-and-done (help invisible at the moment of need), and contextual-when-needed (surfaces help at the moment friction occurs) patterns. Triggers on product tour, in-product tooltip, contextual help, walkthrough, feature tour, hint system, in-app guidance, tour platform. Also triggers when feature adoption is low, when users miss key product capabilities, or when an in-product help system is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing in-product tours and contextual help. Distinguishes tooltip-spam (every button has a tour stop) from one-and-done (tour shows once, never seen again) from contextual-when-needed (surfaces help at the moment friction occurs)" +display_order: 8 +--- + +# Interactive Product Tour + +A senior product marketing director's playbook for designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. The discipline of building help systems that surface at moments of need and disappear when not needed. + +Most product tours fail in one of two ways. They paint every button, link, and feature with "click for tour" hints until the visual noise is so great that users develop blindness to the dots. Or they show a single first-login tour the user skips or skims, after which the same help never re-surfaces when the user actually hits a moment of friction. Help that is invisible at the moment of need is help that does not exist. + +The tours that work do something different. They trigger when the user is at a moment of friction, not all the time. They surface contextual hints when the user enters a section they have not explored, clicks into a feature requiring setup, or returns after a long absence. The system knows what the user knows and surfaces help at the right moment. + +The voice is the senior product marketing director who has watched feature adoption double when tours were redesigned and watched it collapse when more tooltips were piled onto every surface. Practical, opinionated about the trigger logic that distinguishes useful help from visual noise, willing to call out when no in-product tour at all is the right answer. + +When to use this skill: scoping an in-product help system for the first time, auditing a tour system that produces engagement metrics with no adoption lift, designing the trigger logic that decides when help surfaces, or deciding which features warrant tours vs documentation. + +--- + +## What this skill covers + +This skill spans in-product tours, tooltips, and contextual help. The growth-tooling distinctions: + +- `onboarding-wizard-design` is the sequential first-run experience. This skill is contextual help WITHIN the product, surfacing across the lifecycle. +- `chatbot-flow-design` is conversational help. This skill is non-conversational tour and tooltip help. +- **`interactive-product-tour` (this skill)** is trigger logic, tour architecture, contextual placement, completion tracking, and the discipline of being absent until needed. +- `discovery-research-synthesis` is research that informs tour content. Input, not part of. +- `pm-spec-writing` is the spec for engineers building the tour. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams, agencies running activation work for SaaS clients. + +Out of scope: first-run wizards (covered by `onboarding-wizard-design`); conversational help (covered by `chatbot-flow-design`); the engineering implementation; specific Userpilot/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The tour decision: when tours earn vs when documentation suffices + +Before designing the tour system, decide whether tours are the right tool. + +**Tours earn investment when:** + +- The product has features users genuinely miss without prompting. Specific functionality buried in menus, advanced workflows that require sequence, integrations users do not know exist. +- The audience benefits from in-context guidance more than out-of-context documentation. Tours teach in the place the user will use the feature; docs require context-switching. +- The team can maintain tours as the product evolves. Tour content decays; without maintenance commitment, tours point to deprecated UI. +- The success metric is defined. Feature adoption, time-to-value for specific capabilities, reduction in support tickets for tour-covered features. + +**Tours do NOT earn investment when:** + +- The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. +- The audience prefers self-directed discovery. Some audiences resent in-product guidance and prefer to explore. +- The team cannot maintain tours alongside product changes. Stale tours are worse than no tours. +- The product changes frequently. Tour maintenance can exceed tour value if the product churns rapidly. + +The decision is not "should we have a tour system"; it is "is in-product tour the right tool for this product and audience." + +Detail in [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md). + +--- + +## Tooltip-spam vs one-and-done vs contextual-when-needed + +The keystone framing. + +**Tooltip-spam.** Every button, link, and feature has a "click for tour" hint or pulsing dot. Visual noise. Users develop blindness to the dots; the tour system fails as a teaching surface. Cost: the design effort produces help nobody perceives; the visual clutter degrades the product overall. + +**One-and-done.** A single tour shown on first login. Users skip or skim. The same tour never re-surfaces when the user actually hits a moment of friction. Cost: help that is invisible at the moment of need does not help. Feature adoption stays low; support tickets persist for features the tour covered. + +**Contextual-when-needed.** Tours and tooltips trigger when the user is at a moment of friction (entered a section they have not explored, clicked into a feature requiring setup, returned after a long absence, hit a feature flag's first activation). The system knows what the user knows and surfaces help at the right moment. Cost: trigger logic is meaningful work; payoff is help that compounds adoption over time. + +The litmus test. Watch a user encounter a feature for the first time. Does the help system surface useful guidance at that moment, or did it surface guidance at first-login that the user has long forgotten? If the former, contextual-when-needed. If the latter, one-and-done. If the help is competing with 14 other tooltip dots scattered across the page, tooltip-spam. + +--- + +## Trigger logic: event-based vs time-based vs state-based + +The mechanism that decides when help surfaces. + +**Event-based triggers.** Help appears in response to a user action. Clicked a feature for the first time, entered a new section, completed a flow. + +When to use. Default for most contextual help. The user did something; help responds. + +**Time-based triggers.** Help appears after time elapsed. Returned to the product after 30 days of absence; been on this page for 60 seconds without acting. + +When to use. Time can signal need (long absence; stuck on a page). Use sparingly; time alone is a noisy signal. + +**State-based triggers.** Help appears based on user state. New user vs power user; account size; feature usage history. + +When to use. When the help differs by user segment. State-based triggers personalize help. + +**Combined triggers.** Most production tour systems combine all three. Event-driven, with time and state modulating frequency and content. + +The discipline. The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. + +Detail in [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md). + +--- + +## Tour architecture: single tour vs branched vs library of micro-tours + +How help is organized. + +**Single tour.** One linear tour covering the product. Simple; rigid; rarely fits how users actually explore. + +**Branched tour.** Tour adapts based on user choices or path through the product. More relevant; more complex. + +**Library of micro-tours.** Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. Most flexible; most maintenance. + +**The choice.** Most modern systems use the micro-tour library approach. Single tours feel canned; branched tours are hard to maintain at scale; a library of contextual micro-tours matches how users actually explore. + +Detail in [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md). + +--- + +## Contextual placement: where help appears, how it dismisses + +The visual design of help. + +**Placement patterns.** + +- **Tooltip on hover.** Help appears next to the element on hover. Lightweight; familiar. +- **Spotlight overlay.** Element highlighted, help appears alongside. More prominent; more disruptive. +- **Sidebar.** Help appears in a side panel. Can persist while the user works. +- **Inline.** Help appears in the page flow. Non-disruptive; harder to dismiss. + +**Dismissal mechanics.** + +- **Click X.** Standard close. Always available. +- **Click outside.** Help dismisses if the user interacts with anything else. Implies non-modal help. +- **Auto-dismiss.** Help fades after a few seconds. Risky; users may not have read it. +- **Persistent until acted on.** Help stays until the user takes the suggested action. Powerful for guided flows; intrusive otherwise. + +**Non-intrusion principle.** Help should be findable when wanted, ignorable when not. Modal help that blocks the screen is intrusive; help that disappears too easily fails to teach. + +Detail in [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) and [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md). + +--- + +## Completion tracking and re-trigger logic + +Knowing what each user has seen, deciding when to show again. + +**Per-user state tracking.** + +- Which tours has the user completed? +- Which tours has the user dismissed? +- Which tours has the user seen but not completed? +- Time since last interaction. + +**Re-trigger logic.** + +- Completed tours: usually do not re-show. +- Dismissed tours: respect the dismissal; possibly re-show after a long delay if the feature becomes relevant again. +- Skipped tours: re-show at moments of relevance. +- Long-absent users: re-orient with abbreviated help. + +**The over-trigger trap.** Showing the same tour to users who have completed it. Trust degrades; users disable tours. + +**The under-trigger trap.** Tours never re-surfacing when the user hits the same friction again. Help fails at the moment of need. + +Detail in [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md). + +--- + +## Power-user vs new-user differentiation + +Different users need different help. + +**The principle.** Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference. + +**Differentiation signals.** + +- Feature usage history (has the user used this feature before?). +- Tenure (how long has the user been on the product?). +- Engagement frequency (active daily vs returning monthly). +- Self-reported skill level (rare; usually inferred). + +**Differentiation patterns.** + +- Power users see help only on new features. +- New users see help on the features matching their stage of exploration. +- Returning users see re-orientation help if their last session was long ago. + +**The over-helping trap.** Helping power users with features they mastered. Trust degrades. + +**The under-helping trap.** Treating all users as power users. New users miss critical help. + +Detail in [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-tour-failures.md`](references/common-tour-failures.md). + +- "Tours show but feature adoption does not improve." Help may be visually present but not contextually relevant. Audit trigger logic. +- "Users disable tours globally." The system is annoying users. Audit frequency, dismissal, and over-triggering. +- "First-login tour completion is 80 percent; feature adoption is unchanged." One-and-done pattern; tour content not retained at moment of need. +- "Tooltips appear everywhere; nobody clicks them." Tooltip-spam; rebalance to contextual triggers. +- "Tour content references features we deprecated 6 months ago." Maintenance lapse. +- "Power users complain about pop-ups for things they already know." No power-user differentiation. +- "Tours work on desktop, break on mobile." Mobile UX of help system not tested. +- "Some teams ship tours; others don't bother. Inconsistent." No tour governance; some teams build, others ignore. +- "Tours triggered correctly but users do not act on the suggestion." Help content unclear or call-to-action absent. + +--- + +## The framework: 12 considerations for product tour design + +When designing or auditing an in-product tour system, walk these 12 considerations. + +1. **The tour decision.** Are tours the right tool, or does documentation suffice? +2. **Contextual-when-needed, not tooltip-spam or one-and-done.** Help surfaces at moments of friction. +3. **Trigger logic sound.** Event-based primary, with time and state modulation. +4. **Tour architecture matches usage.** Library of micro-tours preferred for most products. +5. **Contextual placement non-intrusive.** Help findable when wanted, ignorable when not. +6. **Dismissal mechanics honest.** Standard close, click-outside dismiss, no auto-dismiss before reading. +7. **Completion tracking instrumented.** Per-user state, per-tour status. +8. **Re-trigger logic respectful.** Completed tours do not re-show; dismissed tours respected. +9. **Power-user vs new-user differentiation.** Help calibrated to user state. +10. **Mobile parity.** Help works on the devices the audience uses. +11. **Maintenance discipline.** Tours updated alongside product changes; quarterly audit. +12. **Adoption as success metric.** Not just tour completion; feature adoption is the metric that matters. + +The output of the framework is a tour system that earns the user's attention by being absent until needed, surfaces help at moments of relevance, and produces feature adoption. + +--- + +## Reference files + +- [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md) - When tours earn the build vs when documentation suffices. +- [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md) - Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. +- [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md) - Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. +- [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) - Tooltip, spotlight, sidebar, inline. Placement and visual design. +- [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md) - Per-user state, re-trigger logic, the over-trigger and under-trigger traps. +- [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md) - Differentiation signals and patterns. The over-helping and under-helping traps. +- [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md) - Dismissal mechanics. The non-intrusion principle. +- [`references/tour-anti-patterns.md`](references/tour-anti-patterns.md) - The patterns that look like tours but degrade the product. +- [`references/common-tour-failures.md`](references/common-tour-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: tours earn the user's attention by being absent until needed + +The tour systems that work as compounding assets are the ones the user does not perceive as a tour system. Help surfaces at the moment of friction; disappears when the friction passes; never piles up as visual noise. The user encounters a feature for the first time, sees a brief contextual hint, takes the suggested action, and moves on. The system did its job; the user did not have to think about the system. + +That is the bar. Below the bar are tooltip-spam (visual noise that users develop blindness to) and one-and-done (help invisible at the moment of need). Above the bar are contextual-when-needed systems where trigger logic, tour architecture, contextual placement, and re-trigger respect work together to make help feel ambient rather than imposed. + +The discipline is in the design choices. The decision to build a tour system at all, or rely on documentation. The trigger logic that decides when help surfaces. The architecture that organizes micro-tours by feature and workflow. The placement and dismissal that make help non-intrusive. The completion tracking that prevents re-showing what users already know. The power-user differentiation that respects expertise. The maintenance cadence that keeps tours in sync with the product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md b/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md new file mode 100644 index 0000000..09a5d4d --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md @@ -0,0 +1,171 @@ +# Common tour failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Tours show but feature adoption does not improve." + +**The diagnosis.** Help may be visually present but not contextually relevant. Tour content may be unclear or call-to-action absent. + +**The cure.** Audit trigger logic (`references/trigger-logic-patterns.md`). Verify tours fire at moments of friction. Audit content; ensure tours have clear CTAs. + +--- + +## "Users disable tours globally." + +**The diagnosis.** The system is annoying users. Audit frequency, dismissal, over-triggering. + +**The cure.** Frequency caps (`references/dismissal-and-non-intrusion-patterns.md`). Per-user state tracking (`references/completion-tracking-and-re-trigger.md`). Audit cumulative exposure per session. + +--- + +## "First-login tour completion is 80 percent; feature adoption is unchanged." + +**The diagnosis.** One-and-done pattern. Tour content not retained at moment of need. + +**The cure.** Move from single first-login tour to library of contextual micro-tours. Detail in `references/tour-architecture-patterns.md`. + +--- + +## "Tooltips appear everywhere; nobody clicks them." + +**The diagnosis.** Tooltip-spam. Visual blindness has set in. + +**The cure.** Audit triggers. Remove tooltips that are not earning their place. Reserve hints for moments of friction. + +--- + +## "Tour content references features we deprecated 6 months ago." + +**The diagnosis.** Maintenance lapse. + +**The cure.** Quarterly tour audit. Tag tours by feature; deprecate tours when features deprecate. + +--- + +## "Power users complain about pop-ups for things they already know." + +**The diagnosis.** No power-user differentiation. + +**The cure.** Add feature-usage gating. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tours work on desktop, break on mobile." + +**The diagnosis.** Mobile UX of help system not tested. + +**The cure.** Mobile-first design and testing. Different placement patterns for mobile. + +--- + +## "Some teams ship tours; others don't bother. Inconsistent." + +**The diagnosis.** No tour governance. Some teams build tours, others ignore them. + +**The cure.** Tour ownership. Designate who maintains the system. Tour authoring guidelines. + +--- + +## "Tours triggered correctly but users do not act on the suggestion." + +**The diagnosis.** Help content unclear or call-to-action absent. + +**The cure.** Audit tour content. Each tour should have a clear, actionable CTA matched to the user's likely intent. + +--- + +## "Tour completion looks fine; adoption is mixed by feature." + +**The diagnosis.** Some tours work, others do not. Per-tour adoption tracking surfaces which. + +**The cure.** Per-tour adoption-lift measurement. Retire or redesign tours that do not produce adoption lift. + +--- + +## "We added more tours; user complaints went up." + +**The diagnosis.** Cumulative frequency overload. Each tour reasonable; total exposure too much. + +**The cure.** Per-session frequency caps. Audit cumulative exposure. + +--- + +## "Returning users miss new features we shipped during their absence." + +**The diagnosis.** No re-orientation help for long-absent users. + +**The cure.** Returning-user re-orientation pattern. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tour analytics broke after the last release." + +**The diagnosis.** Instrumentation drift. + +**The cure.** Verify analytics after every release. Add to deployment smoke test. + +--- + +## "Tour fires but user is mid-task; they abandon." + +**The diagnosis.** Trigger logic does not respect ongoing tasks. + +**The cure.** Detect mid-task state; defer tour. Trigger at moments of natural pause. + +--- + +## "We A/B tested tour content; adoption did not move." + +**The diagnosis.** Content was not the issue. Could be trigger, audience, or feature design. + +**The cure.** Test variables that matter. Trigger logic, audience targeting, feature design itself. Sometimes the tour cannot save a bad feature. + +--- + +## "Tours are clear; adoption is good; users still file support tickets." + +**The diagnosis.** Tours covered the feature but not the edge cases. Documentation is needed for depth. + +**The cure.** Tours plus docs. Tours teach the common case; docs cover edge cases. + +--- + +## "Power users say tours feel patronizing." + +**The diagnosis.** Copy tone wrong; or tours fire on features power users have mastered. + +**The cure.** Match copy to brand voice (treat users as adults). Add power-user differentiation. + +--- + +## "Tour platform broke after last platform update." + +**The diagnosis.** Tour platform changes (Userpilot/Pendo/Appcues SDK updates) can break existing tours. + +**The cure.** Test after platform updates. Have a rollback plan. + +--- + +## The pattern across failures + +Most tour failures fall into one of three patterns. + +**Pattern 1: The tour does not surface at the right moment.** Tooltip-spam, one-and-done, over-trigger, under-trigger. The fix is trigger logic. + +**Pattern 2: The tour does not match the audience or device.** No power-user differentiation, mobile-broken, patronizing. The fix is matching to user state. + +**Pattern 3: The tour decays.** Stale references, broken triggers, deprecated features still tour-covered. The fix is maintenance. + +The metric pattern: tour failures often look fine on completion alone. The signal is in feature adoption, support ticket reduction, user retention. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (trigger, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md b/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md new file mode 100644 index 0000000..fd7a8d5 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md @@ -0,0 +1,203 @@ +# Completion tracking and re-trigger + +Per-user state, re-trigger logic, the over-trigger and under-trigger traps. + +Knowing what each user has seen, deciding when to show again. Done well, tours feel ambient; done poorly, tours either re-show endlessly or fail to re-surface when needed. + +--- + +## The state-aware principle + +The tour system should know what each user has seen, completed, dismissed, and ignored. Decisions about whether to show, re-show, or skip a tour should be based on this state. + +**The win.** A user who completed the advanced filtering tour does not see it again. A user who skipped it might see it again at a moment of more relevance. A user who dismissed all tours sees nothing. + +**The fail.** Users see the same tour every time they log in. Users who dismissed tours globally still get them. Users who would benefit from a re-shown tour at the right moment never see it again. + +The discipline. Track state per user per tour; use state to inform re-trigger logic. + +--- + +## Per-user state tracking + +What to track. + +**Per tour, per user.** + +- Has the user seen this tour? +- Did they complete it? +- Did they dismiss it without completing? +- When did they last interact with it? +- Did they take the suggested action after the tour? + +**Globally per user.** + +- Are tours globally enabled or disabled? +- What is their tenure on the product? +- What user state attributes apply (plan, role, segment)? + +**Aggregate.** + +- Tour completion rate. +- Tour dismissal rate. +- Action-taken-after-tour rate. + +The data informs both individual and system decisions. + +--- + +## Re-trigger logic + +When to re-show. + +**Completed tours.** + +- Default: do not re-show. The user got what they needed. +- Exception: re-show if the feature changed materially. The tour is no longer the same tour. + +**Dismissed tours.** + +- Respect the dismissal. +- If the feature becomes relevant again much later (60+ days, significant feature change), consider gentle re-surfacing with respect. + +**Skipped tours (saw but did not complete).** + +- Re-trigger at moments of more relevance. The user did not commit; help may land better contextually. +- After 2-3 skip events, treat like dismissed; respect the pattern. + +**Ignored tours (saw but did not interact).** + +- Treat similarly to skipped. +- Re-trigger at moments of higher friction. + +--- + +## The over-trigger trap + +Showing the same tour to users who have completed it. + +**The pattern.** No completion tracking; tours fire on every page load. + +**The signal.** Users complain about repeat tours; users disable tours globally; trust drops. + +**The cost.** The tour system loses credibility. Users who would have benefited from new tours dismiss them along with the over-triggered repeats. + +**The cure.** Track completion. Tours that have been completed do not re-fire (with rare exceptions for material feature changes). + +--- + +## The under-trigger trap + +Tours never re-surfacing when the user hits the same friction again. + +**The pattern.** First-login tours that show once and never come back. + +**The signal.** Users hit the same feature later; have forgotten the tour; ask support; the help failed at the moment of need. + +**The cost.** The tour system was decorative; the help did not compound adoption. + +**The cure.** Re-trigger logic at moments of need. Even completed tours can re-surface in abbreviated form when the user hits the relevant feature months later. + +--- + +## Re-trigger conditions + +Specific conditions that warrant re-triggering. + +**Material feature change.** The feature the tour covers has changed enough that the tour content is materially different. Re-show with "this feature has changed; here is what is new." + +**Long absence.** User returned after 60+ days; subset of tours can re-surface as re-orientation. + +**Plan change.** User upgraded plan; tours for previously-locked features become relevant. + +**Role change.** User's role changed (e.g., promoted to admin); admin-relevant tours become applicable. + +**Time-based decay.** Some tours benefit from periodic refreshers (rare; use carefully). + +The discipline. Each re-trigger condition should be deliberate, not default. + +--- + +## Frequency limits + +Even thoughtful re-triggers can over-fire. + +**Per-tour frequency.** + +- Default: never re-show after completion. +- Re-trigger conditions: maximum once per condition met. + +**Per-session frequency.** + +- Maximum tours per session (cumulative across all tours): often 1-3. +- Beyond that, defer additional tours to next session. + +**Per-week frequency.** + +- Some users encounter many features in a week; the system should not fire 20 tours. +- Cap weekly tour exposure to maintain attention. + +The discipline. Audit cumulative tour exposure per session and per week. Individual tour decisions are not enough. + +--- + +## Dismiss vs disable distinction + +Two different signals. + +**Dismiss.** User closed a specific tour. Tells the system "this tour is not for me right now." + +**Disable.** User turned off all tours via settings. Tells the system "I do not want any tours." + +**Treatment.** + +- Dismiss: respect for that tour; consider re-trigger at moments of higher relevance. +- Disable: respect globally; do not show any tours. + +**The disable-respect failure.** Some tour systems override the global disable for "important" tours. This breaks user trust. Disable should mean disable (compliance triggers excepted, with disclosure). + +--- + +## Tour analytics for completion + +Track what each tour produces. + +**Per-tour metrics.** + +- Trigger rate (how often does this tour fire?). +- Completion rate (of users who saw it, how many completed?). +- Dismissal rate (how many dismissed without completing?). +- Action-taken rate (how many took the suggested action after?). +- Adoption lift (do users who saw the tour adopt the feature at higher rates than those who did not?). + +The metrics inform whether the tour is earning its place. + +**The adoption-lift question.** If users who saw the tour adopt the feature at the same rate as users who did not, the tour is not adding value. Either redesign or retire. + +--- + +## Common completion-tracking failures + +**No tracking.** Tours fire repeatedly; users complain. + +**Tracking exists but ignored.** State stored but trigger logic does not use it; over-trigger persists. + +**Stale state.** User dismissed tour 6 months ago; product changed; tour does not re-show despite being newly relevant. + +**Cross-device gaps.** State tracked per device; user switches device and re-encounters every tour. + +**Disable not respected.** Global disable ignored for "important" tours; user trust collapses. + +**No adoption-lift measurement.** Tours track completion but not whether they produced adoption; weak tours persist. + +**Re-trigger overzealous.** Re-trigger conditions fire too liberally; users see tours they completed re-appear without justification. + +--- + +## Methodology-level choices that stay in the public skill + +The state-aware principle. Per-user state tracking. Re-trigger logic. The over-trigger and under-trigger traps. Re-trigger conditions. Frequency limits. Dismiss vs disable distinction. Tour analytics. Common failures. + +## Implementation choices that stay internal + +Specific tracking implementations. Specific re-trigger logic per tour. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md new file mode 100644 index 0000000..9887927 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md @@ -0,0 +1,245 @@ +# Contextual placement patterns + +Tooltip, spotlight, sidebar, inline. Placement and visual design. + +The placement decides whether help feels ambient or imposed. Done well, help is findable when wanted, ignorable when not. Done poorly, help blocks the user or disappears before they read it. + +--- + +## The non-imposition principle + +Help should be findable when wanted, ignorable when not. Help that demands the user's full attention is help that costs trust. + +**The win.** A tooltip appears next to a feature, visible but not blocking. The user reads if interested, dismisses or ignores if not. The interaction is brief and respectful. + +**The fail.** A modal overlay blocks the entire screen, demanding the user click to dismiss before continuing. The user loses momentum; resents the interruption. + +The discipline. Match placement intensity to help importance. Most help should be lightweight. + +--- + +## Pattern A: Tooltip on hover + +Help appears next to the element on hover. + +**How it works.** + +- User hovers over the element. +- Tooltip appears next to it. +- Tooltip dismisses when hover ends. + +**Strengths.** + +- Lightweight. +- Familiar pattern. +- Non-intrusive. + +**Weaknesses.** + +- Mouse-only by default; keyboard users may miss. +- Limited content (cannot fit much in a tooltip). +- Dismisses too easily for content the user needs to read. + +**When to use.** Brief hints, definitions, quick clarifications. Not for multi-step guidance. + +--- + +## Pattern B: Spotlight overlay + +Element highlighted; help appears alongside. + +**How it works.** + +- The relevant element is highlighted (often via dimmed surrounding area). +- A help card appears nearby explaining the element. +- User clicks "Got it" or similar to dismiss. + +**Strengths.** + +- More prominent; harder to miss. +- Can fit more content than tooltip. +- Good for feature-specific tours. + +**Weaknesses.** + +- More disruptive. +- Dimming the page can frustrate users who wanted to do something else. + +**When to use.** Feature-specific tours, the kind of help that warrants the user's full attention briefly. + +--- + +## Pattern C: Sidebar + +Help appears in a side panel. + +**How it works.** + +- Help opens in a panel (often right side of screen). +- User can read while the main content remains accessible. +- Panel persists until dismissed. + +**Strengths.** + +- Persistent reference; user can refer back. +- Does not block main content. +- Can fit substantial content. + +**Weaknesses.** + +- Takes screen space. +- May not work on mobile. + +**When to use.** When the help is reference material the user may want to consult while working. Multi-step guides where the user is doing the steps in the main content. + +--- + +## Pattern D: Inline + +Help appears in the page flow. + +**How it works.** + +- Help is embedded directly in the page content. +- Often appears as a banner, inline hint, or contextual section. +- User scrolls past or interacts with it. + +**Strengths.** + +- Non-disruptive. +- Always findable (does not appear and disappear). +- Works well on mobile. + +**Weaknesses.** + +- Can be missed entirely. +- Adds page length. + +**When to use.** Empty states, contextual hints that should always be visible, supplementary information that some users want. + +--- + +## Pattern E: Modal overlay + +Help blocks the screen until dismissed. + +**How it works.** + +- A full-screen or large modal appears. +- User must dismiss to continue. + +**Strengths.** + +- Highest visibility. +- Forces attention on critical messages. + +**Weaknesses.** + +- Most disruptive. +- Easily abused; produces annoyance. +- Should be reserved for critical messages. + +**When to use.** Compliance-critical messages, terms updates, data-loss warnings. Almost never for routine help. + +--- + +## Placement choice by content type + +What pattern fits what content. + +**Brief hints (1 sentence):** tooltip on hover. + +**Feature explanations (2-3 sentences plus example):** spotlight overlay. + +**Multi-step guides (3-5 steps):** spotlight overlay sequence or sidebar. + +**Reference material (multiple paragraphs):** sidebar. + +**Empty states and contextual hints:** inline. + +**Compliance / critical messages:** modal overlay. + +The match between content and placement is part of the design discipline. + +--- + +## Visual design discipline + +How help looks. + +**Visual weight.** + +- Tooltips: light, almost invisible until needed. +- Spotlights: medium; visible but not aggressive. +- Modals: heavy; demand attention. + +**Brand consistency.** + +- Help styling matches the product's design system. +- Tone matches brand voice. +- Colors should not feel "this is a tour"; they should feel like part of the product. + +**Iconography.** + +- Help often uses small icons (info, lightbulb) to signal "this is help." +- Icons should be consistent across help surfaces. + +--- + +## Animation discipline + +How help appears and disappears. + +**Subtle animation.** Fade in, slight slide. Reinforces transition without distracting. + +**Aggressive animation.** Bounce, attention-grabbing motion. Useful sparingly; abused, becomes annoyance. + +**No animation.** Instant appear/disappear. Snappy; some users prefer it. + +**Prefers-reduced-motion.** Respect user system preferences. No bouncing for users who configured reduced motion. + +--- + +## Mobile placement considerations + +Mobile changes everything. + +**Tooltips.** Hover does not exist on mobile; tooltips need touch alternative. Often replaced with tap-to-show. + +**Spotlights.** Spotlight overlays need to fit mobile screens. Smaller content; fewer steps. + +**Sidebars.** Often impossible on mobile; replaced with full-screen modals or omitted. + +**Inline.** Works well on mobile. Usually the safest mobile-first pattern. + +**Modal overlays.** Take over the screen on mobile; even more disruptive than on desktop. + +The mobile discipline. Test help on actual devices. Mobile help should be lighter and more inline-oriented. + +--- + +## Common placement failures + +**Wrong pattern for content.** Modal for a brief hint; tooltip for a multi-step guide. + +**Visual weight wrong.** Aggressive animation for routine help; invisible animation for critical messages. + +**Mobile broken.** Tooltips that do not work on touch; sidebars that take over the mobile screen. + +**Brand-inconsistent.** Help styled differently from the rest of the product; feels bolted on. + +**Animation distracting.** Bouncing tooltips that draw the eye constantly. + +**No reduced-motion respect.** Animations fire regardless of system preferences. + +**Help blocks the action it is teaching.** Spotlight overlays the very element the user needs to click. + +--- + +## Methodology-level choices that stay in the public skill + +The non-imposition principle. Patterns A through E. Placement choice by content type. Visual design discipline. Animation discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific placement designs for specific tours. Specific tooling. Specific brand styles. The team's mobile testing benchmarks. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md new file mode 100644 index 0000000..ea74d3c --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md @@ -0,0 +1,229 @@ +# Dismissal and non-intrusion patterns + +Dismissal mechanics. The non-intrusion principle. + +How tours close, how they respect the user's path, how they avoid becoming friction. The discipline that makes tours feel ambient rather than imposed. + +--- + +## The non-intrusion principle + +Help should be findable when wanted, ignorable when not. Tours that demand the user's full attention earn user resentment quickly. + +**The win.** A tooltip appears next to a feature. The user reads, dismisses, moves on. Two seconds total. The interaction was brief. + +**The fail.** A modal blocks the screen. The user has to read or dismiss before continuing. The interruption costs momentum and trust. + +The discipline. Match intensity to importance. Most tours should be light. + +--- + +## Dismissal patterns + +How tours close. + +**Pattern A: Click X.** + +How it works. A standard close button (often X or "Close") dismisses the tour. + +When to use. Default. Always available; users always know how to dismiss. + +**Pattern B: Click outside.** + +How it works. Tour dismisses if the user clicks anywhere outside the help element. + +When to use. For non-modal tooltips; lightweight help. + +**Pattern C: Auto-dismiss.** + +How it works. Tour fades after a few seconds of no interaction. + +When to use. Sparingly. Risky because users may not have read it. Best for very brief notifications. + +**Pattern D: Persistent until acted on.** + +How it works. Tour stays until the user takes the suggested action. + +When to use. For guided flows where the user is meant to perform the action. Discouraged for routine help (intrusive). + +**Pattern E: Dismiss-and-don't-show-again.** + +How it works. Dismissing offers an explicit "don't show me this again" option. + +When to use. For tours users may want to never see again (low-priority recurring tips). + +--- + +## Dismiss prominence + +How visible the dismiss is. + +**Equal prominence.** Dismiss and primary action have similar visual weight. + +**Primary-prominent.** Primary action ("Got it" or "Try it") is bold; dismiss is secondary. + +**Hidden dismiss.** Dismiss requires clicking outside or finding a small X. Discouraged; users feel trapped. + +The discipline. Dismiss should be findable in under 2 seconds without searching. + +--- + +## Click-outside dismissal + +When the user clicks elsewhere, what happens. + +**Pattern: Dismiss fully.** Tour closes; user continues with what they were doing. + +**Pattern: Pause and resume.** Tour pauses; if the user comes back, it resumes. Rarely the right choice; introduces unpredictability. + +**Pattern: Block click.** Tour stays; click outside is captured but does not pass through. Most intrusive; reserved for compliance. + +The discipline. Click-outside should usually dismiss. Users want to continue; let them. + +--- + +## Auto-dismiss design + +When help fades automatically. + +**Time-based.** Help disappears after N seconds. + +- 3-5 seconds: too short for anything but a single sentence. +- 8-12 seconds: reasonable for short help. +- 15+ seconds: probably too long; users have moved on. + +**Action-based.** Help disappears when the user takes the suggested action. + +- Useful for guided steps. +- Risk: user does something else; help disappears confusingly. + +**Hover-based.** Help disappears when hover ends. + +- Tooltip default. +- Brief by nature. + +**The auto-dismiss risk.** Users who needed the help may have been reading slowly; auto-dismiss takes the help away before they finish. + +The cure. Either give enough time, or let users explicitly dismiss. + +--- + +## Frequency caps for non-intrusion + +How many tours can fire in a session. + +**Per-session caps.** + +- Maximum tours per session: 1-3 typical. +- Beyond that, additional tours defer to next session. + +**Per-page caps.** + +- Maximum tours per page load: usually 1. +- Multiple tooltips on a page can stack; visual noise climbs. + +**Per-day caps.** + +- For users who use the product all day, daily caps prevent fatigue. + +The discipline. Cumulative exposure matters as much as individual tour quality. + +--- + +## Spacing and animation + +How tours appear and disappear. + +**Subtle entry.** Fade in; slight slide. Reinforces transition without distracting. + +**Aggressive entry.** Bounce, pulse, shake. Gets attention; abused, becomes annoyance. + +**Subtle exit.** Fade out; quick. + +**The animation discipline.** Subtle entries and exits. Save aggressive animation for rare attention-needed moments. + +--- + +## Spatial respect + +Where the help appears matters. + +**Avoid blocking the action.** Help should not cover the element it is teaching. + +**Avoid blocking critical content.** Help should not obscure the user's primary work area. + +**Avoid covering navigation.** Help that hides nav prevents the user from leaving. + +**Allow scroll.** If the user needs to scroll while help is visible, scroll should still work. + +--- + +## Help dismissal preserves user state + +When the user dismisses, what is preserved. + +**Form data:** preserved. Dismissing help should not reset form inputs. + +**Page state:** preserved. Dismissing help should not navigate away. + +**User progress:** preserved. Dismissing help should not undo work. + +**The state-loss failure.** Help dismissal that resets the page or loses inputs costs trust catastrophically. + +--- + +## Power-user dismissal patterns + +Power users want to dismiss faster. + +**Keyboard dismissal.** ESC closes help. Power users use keyboard. + +**Click-anywhere-to-dismiss.** Allows fast dismissal without targeting the X. + +**Settings to disable globally.** Allows opting out of all tours. + +The discipline. Power users should be able to dismiss in under a second. + +--- + +## New-user dismissal patterns + +New users may need more time. + +**Persistent tooltips for guided flows.** Help stays visible during the flow it is teaching. + +**Linked help.** Dismissing help leaves a way to find it again ("Need help? Check our guides"). + +**Contextual reminders.** Help re-surfaces if the user struggles with the same area later. + +The discipline. New users should not lose access to help permanently from a single dismissal. + +--- + +## Common dismissal failures + +**Dismiss too prominent.** User dismisses before reading; misses the help. + +**Dismiss hidden.** User cannot find the dismiss; feels trapped. + +**Auto-dismiss too short.** Help disappears before reading; user does not know what was there. + +**Dismiss does not respect.** Tour reappears after dismiss. + +**Dismiss loses state.** Form inputs reset; user loses work. + +**No keyboard dismiss.** Power users cannot dismiss quickly. + +**Modal blocks until dismissed.** User cannot continue without engaging. + +**Help blocks the action.** Spotlight covers the very element being taught. + +--- + +## Methodology-level choices that stay in the public skill + +The non-intrusion principle. Patterns A through E for dismissal. Dismiss prominence. Click-outside dismissal. Auto-dismiss design. Frequency caps. Spacing and animation. Spatial respect. State preservation on dismiss. Power-user vs new-user dismissal patterns. Common failures. + +## Implementation choices that stay internal + +Specific dismissal designs for specific tours. Specific animation timings. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md new file mode 100644 index 0000000..646a365 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md @@ -0,0 +1,204 @@ +# Power-user vs new-user patterns + +Differentiation signals and patterns. The over-helping and under-helping traps. + +Different users need different help. The discipline is to know which user is which and tailor the help system to their state. + +--- + +## The state-respect principle + +Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference and respect both. + +**The win.** A power user encounters a newly-shipped feature; sees a brief tour. A new user encounters a feature for the first time; sees the same tour. A power user encounters a feature they have used 50 times; sees nothing. + +**The fail.** Both users see the same tour every time. Power users disable tours; new users miss critical help when they need it most. + +The discipline. Tour visibility should depend on user state, not user category alone. + +--- + +## Differentiation signals + +What lets the system know which user is which. + +**Feature usage history.** Has the user used this feature before? + +- Most reliable signal. +- Tracks per-feature, per-user state. +- Updates in real time as the user uses the feature. + +**Tenure on the product.** How long has the user been a customer? + +- Approximate signal; new accounts vs old accounts. +- Useful when feature usage data is missing. + +**Engagement frequency.** Daily active vs returning monthly. + +- Active users tend to know the product better. +- Returning users may need re-orientation. + +**Plan or role.** Free vs paid; admin vs end-user; user vs viewer. + +- Different roles use different feature sets. +- Plan changes can unlock new features. + +**Self-reported skill level.** Rare; usually inferred. + +- Some products ask during signup. +- Useful but unreliable; people self-assess inaccurately. + +The discipline. Combine signals. Single signals are noisy. + +--- + +## Differentiation patterns + +How to surface different help. + +**Pattern A: Feature-usage gating.** + +How it works. Each tour has a "show only if user has not used this feature" condition. Power users with usage history skip; new users see. + +When to use. Default for feature-specific tours. Most reliable. + +**Pattern B: Tenure-based filtering.** + +How it works. New users (under 7 days) see all relevant tours. Established users (over 30 days) see tours only for newly-shipped features. + +When to use. When feature usage data is incomplete or unavailable. + +**Pattern C: Engagement-based modulation.** + +How it works. Daily active users see fewer tours; returning monthly users may see re-orientation help. + +When to use. When engagement frequency predicts product knowledge. + +**Pattern D: Role-based differentiation.** + +How it works. Admins see admin-specific tours; end-users see end-user tours. + +When to use. When the product has materially different surfaces for different roles. + +**Pattern E: Newly-shipped feature highlighting.** + +How it works. New feature ships; tour fires for ALL users (power users and new users) because everyone is new to this feature. + +When to use. Feature launches. Power users benefit from the tour just as much as new users for this case. + +--- + +## The over-helping trap + +Helping power users with features they have mastered. + +**The pattern.** Tours fire regardless of user state; power users see tours they do not need. + +**The signal.** Power user complaints; tour disable rate climbs; trust degrades. + +**The cost.** Power users disable tours globally; the system loses access to them for genuinely new features. + +**The cure.** Add feature-usage gating. Respect tenure and engagement signals. + +--- + +## The under-helping trap + +Treating all users as power users. + +**The pattern.** Tours fire only on first-login or never. New users miss help when they need it. + +**The signal.** Feature adoption stays low among new users; support tickets persist for tour-covered features. + +**The cost.** New users churn or stay underactivated. + +**The cure.** Tours fire when users encounter features for the first time, regardless of how long they have been on the product. + +--- + +## Returning-user re-orientation + +Long-absent users may need re-orientation. + +**The pattern.** User has not logged in for 60+ days. On return, abbreviated re-orientation help surfaces. + +**Design.** + +- Brief (2-3 steps max). +- Highlights what changed in the user's absence. +- Easy to dismiss for users who do not need it. + +**The over-helping risk.** Users returning from a 1-week absence do not need re-orientation. Set the absence threshold appropriately. + +--- + +## Newly-shipped feature handling + +When a feature ships, the help system has new content. + +**The pattern.** A new tour ships with the feature. Trigger fires for all users (power and new alike) because everyone encounters this feature for the first time. + +**Discipline.** + +- Tag the tour as "new feature." +- Fire on first encounter regardless of user tenure. +- After most users have seen it (e.g., 80 percent of monthly active users), the tour can transition to standard new-user-only logic. + +**Power-user respect.** Even new feature tours should be brief. Power users will read what they need; do not slow them with five-step explanations. + +--- + +## Plan or role change handling + +User state can change. + +**Plan upgrade.** User moves from free to paid; new features become available; relevant tours become applicable. + +**Role change.** User promoted to admin; admin tours become applicable. + +**The discipline.** Re-evaluate tour eligibility on state change. Plan upgrade triggers a "you have new features available" re-orientation. + +--- + +## Inferred vs asked differentiation + +When to ask the user vs when to infer. + +**Ask sparingly.** Asking adds friction; users tire of being categorized. + +**Infer when possible.** Behavioral signals usually outperform self-report. + +**When to ask.** + +- Onboarding (use case, role). +- Major plan changes that affect tour eligibility. + +**When not to ask.** + +- After onboarding; let behavior speak. + +--- + +## Common power-user vs new-user failures + +**No differentiation.** All users see all tours; over-helping power users. + +**Differentiation only by tenure.** New accounts vs old; misses that some new accounts have power users (came from competitor) and some old accounts have casual users. + +**No re-orientation for returning users.** Users who left 90 days ago re-encounter as if first-time; they remember enough to skip re-orientation; but the help fails when they hit a changed feature. + +**Newly-shipped features not flagged.** Tour does not surface for power users who have used adjacent features; they miss the new capability. + +**Plan upgrade not triggering re-evaluation.** User upgrades; new features available; tours for those features do not surface. + +**Inferring poorly.** Inference logic mistakes user state; help is wrong for the user. + +--- + +## Methodology-level choices that stay in the public skill + +The state-respect principle. Differentiation signals (5 signals). Patterns A through E. The over-helping and under-helping traps. Returning-user re-orientation. Newly-shipped feature handling. Plan or role change handling. Inferred vs asked differentiation. Common failures. + +## Implementation choices that stay internal + +Specific differentiation rules for specific products. Specific signals weighted by team. The team's plan and role mapping. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md new file mode 100644 index 0000000..752725d --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md @@ -0,0 +1,224 @@ +# Tour anti-patterns + +The patterns that look like tours but degrade the product. Easy to ship; the cost shows up in feature adoption, user trust, and brand reputation. + +--- + +## The tooltip-spam tour + +The pattern. Every button, link, and feature has a "click for tour" hint or pulsing dot. + +The signal. Users develop blindness to the dots; click rates collapse; tour completion rates near zero. + +The cost. The visual clutter degrades the product; users learn to ignore all tooltips, including useful ones. + +The cure. Audit triggers. Reserve hints for moments of genuine friction. Detail in `references/trigger-logic-patterns.md`. + +--- + +## The one-and-done tour + +The pattern. A single first-login tour. Never re-surfaces. + +The signal. Users skip or skim; help unavailable at moments of later need. + +The cost. Feature adoption suffers; support tickets persist for tour-covered features. + +The cure. Library of micro-tours triggered contextually. Detail in `references/tour-architecture-patterns.md`. + +--- + +## The mega-tour + +The pattern. A single tour with 25 steps covering the whole product. + +The signal. High abandonment mid-tour; high skip rate; activation does not lift. + +The cost. Tutorial-overload pattern applied to tours. Users abandon; help fails. + +The cure. Break into micro-tours, each tied to a specific feature. + +--- + +## The over-trigger tour + +The pattern. Tour fires on every page load; no completion tracking. + +The signal. Repeat exposure; user complaints; tours globally disabled. + +The cost. Tour system loses credibility. + +The cure. Per-user state tracking. Completed tours do not re-fire. + +--- + +## The under-trigger tour + +The pattern. Tour fires only on first-login. Users hit the same friction later; help does not return. + +The signal. Specific features show low adoption among long-tenured users; help failed at the moment of need. + +The cost. The tour system was decorative for everyone after their first session. + +The cure. Re-trigger logic at moments of relevance, even for tours seen long ago. + +--- + +## The dismissive-of-disable tour + +The pattern. User disabled all tours globally; system fires tours anyway because they are deemed important. + +The signal. User trust collapses; explicit complaints. + +The cost. The tour system overrode the user's clear preference; trust does not recover quickly. + +The cure. Respect the global disable. Use compliance-only triggers for legally required messages, with clear disclosure. + +--- + +## The blocks-the-action tour + +The pattern. Spotlight overlay covers the element it is teaching; user cannot click through. + +The signal. User confusion; users dismiss and abandon the action they were about to take. + +The cost. The tour failed at its job; the user did not learn the feature because the tour blocked the feature. + +The cure. Spotlight placement that highlights without blocking. The user should be able to take the action while the help is visible. + +--- + +## The auto-dismiss-too-fast tour + +The pattern. Help fades after 3 seconds. + +The signal. Users complain about help disappearing before they read it. + +The cost. The help is technically present but functionally absent. + +The cure. Either longer auto-dismiss (8-12 seconds), or let users dismiss explicitly. + +--- + +## The validation-strict tour + +The pattern. Tour requires the user to take a specific action to proceed; the user takes a different valid path. + +The signal. Tour gets stuck; user abandons. + +The cost. Forced linearity penalizes users who explore. + +The cure. Tour either accepts multiple valid paths or dismisses if the user explores elsewhere. + +--- + +## The brand-inconsistent tour + +The pattern. Tour styling looks different from the rest of the product. Generic platform styling rather than brand-aligned. + +The signal. Users perceive the tour as bolted on; brand consistency suffers. + +The cost. The product feels less polished; tours feel like a separate system. + +The cure. Custom-styled tours matching the product's design system. + +--- + +## The mobile-broken tour + +The pattern. Tour designed for desktop; breaks on mobile. + +The signal. Mobile completion rates much lower; mobile-specific complaints. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. Detail in `references/contextual-placement-patterns.md` (mobile section). + +--- + +## The unmaintained tour + +The pattern. Tour built once; product evolved; tour content references deprecated features. + +The signal. Users hit broken steps; references that no longer apply. + +The cost. Trust degrades; users ignore tours expecting them to be wrong. + +The cure. Quarterly maintenance. Product changes trigger tour updates as part of the change. + +--- + +## The orphan-tour + +The pattern. Tour exists for a feature that was deprecated 6 months ago; nobody removed it. + +The signal. Tour fires; clicks lead to 404 or to a removed UI; users confused. + +The cost. The tour points to nothing; user trust degrades. + +The cure. Tour deprecation alongside feature deprecation. + +--- + +## The fake-engagement tour + +The pattern. Tour optimizes for click-through rate by making the action button huge and the dismiss tiny. + +The signal. Click-through rate looks high; downstream feature adoption does not match. + +The cost. Surface metrics look fine; real adoption does not improve. + +The cure. Track adoption as the metric; design honestly. Click-through alone is not enough. + +--- + +## The interrupting tour + +The pattern. Tour fires while the user is mid-task; takes over the screen. + +The signal. User abandonment spikes at the interruption; users complain. + +The cost. The tour cost the user a task completion. + +The cure. Tour triggers should respect ongoing tasks. Detect mid-task state; defer. + +--- + +## The patronizing-copy tour + +The pattern. Tour copy talks down to users. "Welcome! Let me show you around. Here's how to do something simple." + +The signal. Power users dismiss; new users feel patronized. + +The cost. Tone hurts trust. + +The cure. Match copy to brand voice. Treat users as adults. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active tour, looking for these anti-patterns. + +**Audit questions per tour.** + +- Is the tour triggered relevantly (anti-pattern check: tooltip-spam, over-trigger, under-trigger)? +- Does the tour respect dismissal (anti-pattern check: dismissive-of-disable)? +- Does the tour block the action it teaches (anti-pattern check: blocks-the-action)? +- Is auto-dismiss timed appropriately (anti-pattern check: auto-dismiss-too-fast)? +- Does the tour match the brand's design (anti-pattern check: brand-inconsistent)? +- Does the tour work on mobile (anti-pattern check: mobile-broken)? +- Is the tour current (anti-pattern check: unmaintained, orphan)? +- Is adoption tracked (anti-pattern check: fake-engagement)? + +**The retire decision.** Anti-pattern tours often warrant retirement or redesign. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md new file mode 100644 index 0000000..9048eaf --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md @@ -0,0 +1,225 @@ +# Tour architecture patterns + +Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. + +The architecture is how help is organized at the system level. Bad architecture produces canned tours that nobody finishes; good architecture matches how users actually explore. + +--- + +## The exploration-fit principle + +The architecture should match how users actually move through the product. Linear architecture fits linear products; library architecture fits exploration. + +**The win.** A library of focused micro-tours, each tied to a specific feature, triggered contextually as users encounter features. Each tour is small (2-4 steps); each fires only at relevant moments. Users feel helped without feeling herded. + +**The fail.** A single linear tour covering 25 features in sequence. Users who care about feature 17 get nothing relevant in the first 16 steps; they skip everything; help fails. + +The discipline. Match architecture to exploration patterns; do not impose linearity on non-linear products. + +--- + +## Pattern A: Single tour + +One linear tour covering the product. + +**How it works.** + +- Tour starts at first-login or via a "Take the tour" prompt. +- Steps cover features in a defined order. +- User completes or skips entirely. + +**Strengths.** + +- Simple to design and maintain. +- Predictable for users. + +**Weaknesses.** + +- Linear; rarely fits how users explore. +- Can become tutorial-overload if comprehensive. +- One-and-done; rarely re-shown. + +**When to use.** Very simple products with linear flows. Rarely the right answer for production tour systems. + +--- + +## Pattern B: Branched tour + +Tour adapts based on user choices or path. + +**How it works.** + +- User selects role/use case at start. +- Subsequent steps adapt based on the selection. +- Different users effectively complete different tours. + +**Strengths.** + +- More relevant than single tour. +- Personalized. + +**Weaknesses.** + +- Complex to build and maintain. +- Hard to instrument cleanly. +- Still linear in execution. + +**When to use.** When the audience splits into 2-3 clear segments with different exploration paths. Use sparingly. + +--- + +## Pattern C: Library of micro-tours + +Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. + +**How it works.** + +- Many small tours (2-4 steps each). +- Each tour is tied to a specific feature, workflow, or moment. +- Trigger logic decides when each fires. +- Users see only the tours relevant to their current exploration. + +**Strengths.** + +- Matches how users actually explore. +- Each micro-tour is small enough to complete. +- Re-trigger logic can re-surface as features become relevant. +- Most flexible. + +**Weaknesses.** + +- Most maintenance. +- Trigger logic complexity. +- Requires per-tour completion tracking. + +**When to use.** Default for production tour systems. Most modern products benefit from this approach. + +--- + +## Pattern D: Hybrid + +Combining patterns. Often a brief opening tour plus a library of micro-tours for ongoing help. + +**How it works.** + +- First-login: brief 3-4 step orientation tour (single). +- Ongoing: library of micro-tours triggered contextually. + +**Strengths.** + +- Orientation for new users + ongoing help for everyone. +- Combines the simplicity of single tour for the moment of arrival with the flexibility of library for the ongoing relationship. + +**Weaknesses.** + +- Two systems to maintain. + +**When to use.** When new users genuinely benefit from an opening orientation AND ongoing contextual help is also valuable. + +--- + +## Architecture choice criteria + +Which pattern fits which product. + +**Use single tour when:** + +- Product is genuinely linear. +- Audience expects guided sequence. +- Maintenance capacity is limited. + +**Use branched tour when:** + +- Audience splits into 2-3 distinct segments. +- Each segment has a different linear path. + +**Use library of micro-tours when:** + +- Product has many features users explore non-linearly. +- Audience is segmented in many ways. +- Maintenance capacity supports many tours. + +**Use hybrid when:** + +- New-user orientation matters AND ongoing help also matters. + +The simplest architecture that fits the product is usually the best choice. + +--- + +## Micro-tour discipline + +Each micro-tour should be small. + +**Size guideline.** 2-4 steps per micro-tour. + +**Why small.** + +- Completable in under a minute. +- Easy to maintain. +- Targeted to a specific feature or moment. +- Less likely to be skipped. + +**Anti-pattern.** Micro-tours that grow into 8-10 steps lose their micro nature; they become single tours that happen to be triggered contextually. Re-scope. + +--- + +## Tour tagging and organization + +When you have a library, organize it. + +**Tagging axes.** + +- Feature (which feature the tour covers). +- Workflow (which user workflow the tour fits in). +- User type (new, power, returning). +- Plan (free, paid, enterprise). + +**Why tagging matters.** + +- Trigger logic can use tags to decide which tour fires. +- Maintenance can find tours by feature when the feature changes. +- Audit can identify orphan tours not tied to current features. + +--- + +## Tour deprecation + +When features change, tours need to retire or update. + +**Retire when:** + +- Feature was deprecated; tour points to nothing. +- Feature changed enough that tour content is wrong; redesign instead of patch. + +**Update when:** + +- Feature changed in details but tour structure still applies. + +**The deprecation hygiene.** Quarterly audit of tours against current product. Tours pointing to deprecated features get retired; tours that still apply but need refresh get updated. + +--- + +## Common architecture failures + +**Single tour for non-linear product.** Users skip; help fails. + +**Branched tour with too many branches.** Maintenance burden; quality degrades per branch. + +**Library without tagging.** Tours accumulate; nobody can find them; some are stale. + +**Mega-tours.** Micro-tours that grew to 10+ steps; lose their micro nature. + +**Orphan tours.** Tours pointing to features that no longer exist; not retired. + +**Inconsistent micro-tour quality.** Some tours polished, others slapdash; users notice. + +--- + +## Methodology-level choices that stay in the public skill + +The exploration-fit principle. Patterns A through D. Architecture choice criteria. Micro-tour discipline. Tour tagging and organization. Tour deprecation. Common failures. + +## Implementation choices that stay internal + +Specific architectures for specific products. Specific tooling for tour authoring and management. The team's tagging conventions. Specific quarterly audit calendars. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md new file mode 100644 index 0000000..5bdf154 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md @@ -0,0 +1,154 @@ +# Tour decision criteria + +When tours earn the build vs when documentation suffices. + +A tour system is meaningful work. Trigger logic, tour architecture, contextual placement, completion tracking, ongoing maintenance. Tours earn this investment only when specific conditions are present. + +--- + +## When tours earn the build + +Five conditions that, when present, make tours a strong investment. + +**The product has features users genuinely miss.** Specific functionality buried in menus, advanced workflows requiring sequence, integrations users do not know exist. Without prompting, users do not find these features. + +**The audience benefits from in-context guidance more than documentation.** Tours teach in the place the user will use the feature; docs require context-switching. Some audiences prefer the immediacy of in-context help. + +**The team can maintain tours.** Tour content decays as the product evolves. Without maintenance commitment, tours point to deprecated UI; users hit broken steps. + +**The success metric is defined.** Feature adoption per tour-covered feature, time-to-value for specific capabilities, reduction in support tickets. Without the metric, evaluation is impossible. + +**The product changes at a sustainable pace.** Tours can keep up. Products that change weekly may have tour-maintenance burden exceeding tour value. + +When all five are present, tours are a strong investment. When two or fewer are present, documentation often serves better. + +--- + +## When tours do NOT earn the build + +Funnels where tours add complexity without value. + +**The product's feature set is small enough that documentation suffices.** A few tooltips on key features may be all that is needed. Building a full tour infrastructure is overkill. + +**The audience prefers self-directed discovery.** Some audiences resent in-product guidance. Developer tools, professional creative tools, specialist software often have audiences who want to explore on their own. + +**The team cannot maintain tours.** Stale tours are worse than no tours. Without commitment, tours decay into liability. + +**The product changes too frequently.** A product churning weekly may have tours that go stale within days of being shipped. The maintenance cost exceeds the tour benefit. + +**The audience is small enough that direct outreach is more efficient.** Onboarding calls, customer success engagement, and direct help may serve a small audience better than tour infrastructure. + +The honest assessment matters. Tours are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Documentation vs tours: the comparison + +Both teach features; they differ in delivery. + +**Documentation strengths.** + +- Stable; changes don't require tour updates. +- Searchable; users find what they need. +- Comprehensive; can cover edge cases. +- Accessible from outside the product (sharing, linking). + +**Documentation weaknesses.** + +- Requires context-switching from product to docs. +- Users may not know to consult docs. +- Static; cannot react to user state. + +**Tour strengths.** + +- In-context; help where the user will use the feature. +- Dynamic; can react to user state and behavior. +- Non-disruptive when designed well. + +**Tour weaknesses.** + +- Maintenance burden. +- Can become tooltip-spam if undisciplined. +- Less comprehensive than docs. + +**The combined approach.** Most production teams use both. Tours for the moments where in-context guidance matters; docs for depth and reference. + +--- + +## The opportunity-cost frame + +Tour systems are significant work. + +**The build cost.** Trigger logic infrastructure, tour authoring, instrumentation, integration with the product, design and copy. A meaningful tour system often takes 60-200 engineering hours plus design and copy per major tour. + +**The maintenance cost.** Quarterly review minimum; product changes trigger tour updates. 4-12 hours per active tour per quarter. + +**The opportunity cost.** What else could the team have built? Direct in-product improvements, better empty states, contextual prompts that do not require tour infrastructure. The tour system has to clear the bar of those alternatives. + +The decision frame. Tours earn investment when they produce more adoption lift than the alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering an in-product tour system. + +**Conditions check.** + +- Features users miss: yes. Advanced analysis modes, custom dashboard creation, integration setup all underused. +- In-context guidance benefits: yes. Users explore in-product; pulling them to docs breaks flow. +- Maintenance commitment: yes. Customer success team owns tours. +- Success metric defined: yes. Feature adoption per tour-covered feature within 30 days of first encounter. +- Product change pace: moderate. Major features ship monthly; minor changes weekly. Tour updates fit the cadence. + +**Decision.** Build the tour system. The conditions warrant it. + +**Architecture.** Library of micro-tours, each tied to a specific feature. Triggered contextually when users first encounter the feature. + +**Maintenance commitment.** CS team reviews quarterly; major product changes trigger tour updates as part of the change. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A developer-tool company considering in-product tours. + +**Conditions check.** + +- Features users miss: somewhat. Some advanced features underused, but the audience tends to find them through docs. +- In-context guidance benefits: weak. Developers strongly prefer docs and prefer not to be interrupted. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined. +- Product change pace: moderate. + +**Decision.** Do not build a full tour system. Invest in better docs, smarter empty states, and a few high-value contextual hints. The audience's preference for self-directed discovery argues against tour infrastructure. + +The decision was right-sized to the audience. + +--- + +## When to retire a tour system + +Tour systems can become wrong over time. + +**Retire when:** + +- Feature adoption (the tour's success metric) has declined consistently and refinements have not moved it. +- Users globally disable tours via settings. +- The product changes have outpaced maintenance; tours are stale. +- A redesigned product surface (better empty states, better contextual prompts) makes tours redundant. +- The team can no longer maintain tours. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant tours. The five conditions that argue against. Documentation vs tours comparison. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tour decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md new file mode 100644 index 0000000..aa489aa --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md @@ -0,0 +1,226 @@ +# Trigger logic patterns + +Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. + +The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. Useful triggers surface help at moments of friction. + +--- + +## The relevance principle + +Trigger help when the user is at a moment of friction or genuine need. Do not trigger help when the user is moving through familiar territory. + +**The win.** A user clicks into a feature for the first time. The tour system recognizes this is the user's first encounter and surfaces a brief contextual hint. The user reads, takes the suggested action, moves on. + +**The fail.** Same user, same feature. The tour system has no first-encounter detection; it triggers on every page load. The user has dismissed the same tooltip 12 times; develops blindness to all tooltips. + +The discipline. Each trigger should answer "why this user, why now." + +--- + +## Pattern A: Event-based triggers + +Help appears in response to a user action. + +**How it works.** + +- The user performs an action (clicks a feature, enters a section, completes a flow). +- The trigger fires based on the event. +- Help appears contextually. + +**Examples.** + +- First click into a new section. +- Completed a flow for the first time. +- Hit a state where help would be useful (empty list, no data connected, no teammates invited). + +**Strengths.** + +- Most relevant; help responds to what the user just did. +- Naturally contextual. + +**Weaknesses.** + +- Requires per-event tracking. +- Can over-trigger if events are too granular. + +**When to use.** Default for most contextual help. Events drive the trigger. + +--- + +## Pattern B: Time-based triggers + +Help appears after time elapsed. + +**How it works.** + +- A timer starts when relevant condition is met. +- After a defined interval, help triggers. +- Time can be session time, time on page, time since last action, or time since last login. + +**Examples.** + +- User has been on a page for 60 seconds without acting (signals stuck). +- User returned after 30 days of absence (signals re-orientation needed). +- User has been a customer for 90 days (signals capacity for advanced features). + +**Strengths.** + +- Catches stuck users events alone might miss. +- Useful for re-engagement of long-absent users. + +**Weaknesses.** + +- Time alone is a noisy signal. +- "Stuck" might just be reading. +- Easy to misuse and produce annoyance. + +**When to use.** Sparingly. Time-based triggers should always combine with event or state signals. + +--- + +## Pattern C: State-based triggers + +Help appears based on user state. + +**How it works.** + +- The user has attributes (new vs power; small vs large account; specific role; specific plan). +- Trigger fires based on attribute match. + +**Examples.** + +- Power users see help only on newly-shipped features. +- Enterprise customers see different tour on workspace features than SMB. +- Users on free plan see different upgrade-related help than paid. + +**Strengths.** + +- Personalizes help to user segment. +- Avoids over-helping users who do not need it. + +**Weaknesses.** + +- Requires user-state infrastructure. +- State changes (plan upgrade, role change) need to update triggers. + +**When to use.** When help differs significantly by user segment. State modulates event triggers. + +--- + +## Pattern D: Combined triggers + +Most production tour systems combine event, time, and state. + +**Example combined trigger.** + +"Show tour for advanced filtering feature when: +- User clicks the filter icon for the first time (event). +- User has been on the platform more than 7 days (state, not too new). +- User is on a paid plan (state, feature is paid-only). +- User has not dismissed this specific tour before (state, respect prior dismissal)." + +The combination produces relevant triggers without false positives. + +**The discipline.** Trigger conditions accumulate. Each condition prevents over-triggering. + +--- + +## Trigger frequency limits + +Even relevant triggers can over-fire. + +**Per-tour limits.** + +- Once per user (most tours). +- Once per quarter (re-orientation tours). +- Once per session per page (low-priority hints). + +**Per-session limits.** + +- Cap total tour interruptions per session (e.g., max 2 tours per session). +- Cap total tooltip appearances per session. + +**The cumulative-frequency problem.** Each individual tour may be reasonable; the cumulative count across many tours can become noise. + +The discipline. Audit cumulative triggers per session, not just per tour. + +--- + +## Trigger disabling and respect + +Users may disable tours globally. + +**The pattern.** A settings option lets users disable all tours. + +**The discipline.** Respect the disable. No tour should override the global setting (compliance triggers may be exception). + +**Re-engaging disabled users.** + +- Do not auto-re-enable. +- Surface specific high-value features as one-time prompts that respect the disable. +- Trust that users who disabled know what they want. + +--- + +## Trigger logic and accessibility + +Triggers must work for users with assistive technology. + +**Considerations.** + +- Triggers should not assume mouse hover (keyboard users miss them). +- Triggers should not auto-fire to overwhelm screen readers. +- Triggers should respect prefers-reduced-motion. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Trigger logic testing + +Test triggers across user paths. + +**Test cases.** + +- New user encounters feature: trigger fires. +- Returning user encounters same feature: trigger does not re-fire (respects history). +- Power user encounters newly-shipped feature: trigger fires. +- User who dismissed a tour: dismissed tour does not re-fire. +- User who disabled tours globally: no tours fire. +- User on mobile vs desktop: triggers behave consistently. + +**Production monitoring.** + +- Track trigger fire rate per tour. +- Track tour completion rate per tour. +- Track unique users who saw each tour. +- Anomalies (sudden spike in triggers) often indicate logic issues. + +--- + +## Common trigger logic failures + +**Over-triggering.** Triggers fire on every page load; users develop blindness. + +**Under-triggering.** Triggers fire only on first-login; users miss help when they need it later. + +**No state awareness.** Power users see beginner tours; new users see tours for features they have not unlocked. + +**No frequency limits.** Each individual tour is fine; cumulative triggers per session are noise. + +**Disabled users not respected.** Tours fire despite global disable. + +**Stale triggers.** Triggers reference features deprecated 6 months ago. + +**Untested edge cases.** Specific user paths produce broken triggers; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through D (event, time, state, combined). Trigger frequency limits. Trigger disabling and respect. Accessibility considerations. Trigger testing. Common failures. + +## Implementation choices that stay internal + +Specific trigger configurations for specific tours. Specific tooling for trigger management. The team's testing protocols. Specific frequency baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/internationalization/SKILL.md b/dist/pi/.agents/skills/internationalization/SKILL.md new file mode 100644 index 0000000..01f91ab --- /dev/null +++ b/dist/pi/.agents/skills/internationalization/SKILL.md @@ -0,0 +1,278 @@ +--- +name: internationalization +description: "Plan and run a multi-language or multi-region site. Use this skill when adding new locales, choosing URL structure for languages (subfolders vs subdomains vs ccTLDs), implementing hreflang, planning translation workflow, handling currency and date formats, designing for RTL languages, or auditing a stalled internationalization rollout. Triggers on internationalization, i18n, localization, l10n, hreflang, multi-language, translation workflow, RTL, locale, ccTLD, subfolder vs subdomain, language switcher. Also triggers when international audiences underperform or translations are stale." +category: cross-cutting +catalog_summary: "Locale strategy, hreflang, translation workflow, RTL design" +display_order: 3 +--- + +# Internationalization + +Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic. + +--- + +## When to use + +- Adding the first non-English (or non-default) language +- Adding additional locales to an existing internationalized site +- Choosing URL structure for languages +- Implementing hreflang tags +- Designing translation workflow +- Handling currency, date, time, and number formats +- Designing or fixing layout for RTL languages +- Auditing an internationalization rollout that's underperforming + +## When NOT to use + +- Single-language site (use other skills) +- Domain strategy that's not language-driven (use `domain-strategy`) +- Content strategy independent of locale (use `content-strategy`) +- Marketing copy production (use `content-and-copy`) + +--- + +## Required inputs + +- The locales in scope (language + region, e.g., `en-US`, `de-DE`, `fr-CA`) +- Business reason per locale (priority, audience size) +- Existing site architecture +- Translation resources (in-house, agency, AI-assisted, community) +- Content volume and update frequency + +--- + +## The framework: 5 layers + +Internationalization touches everything. Five layers, each with their own decisions. + +### Layer 1: URL structure + +How locales are reflected in URLs. + +| Pattern | Example | When | +|---|---|---| +| ccTLD | example.de, example.fr | Strong country focus, distinct legal entities, willing to maintain separate domains | +| Subdomain | de.example.com, fr.example.com | Logical separation, willing to host separately, common for large sites | +| Subfolder | example.com/de/, example.com/fr/ | SEO equity unified, simplest to manage, default for most | +| URL parameter | example.com?lang=de | Avoid; weak SEO signal | + +For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand). + +Within the chosen pattern, decide: +- Language only (`/de/`) or language plus region (`/de-de/`, `/de-at/`, `/de-ch/`)? +- Default locale: at the apex (`example.com`) or in a folder (`example.com/en/`)? + +The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an `x-default` and the canonical for the default language). + +### Layer 2: Content structure + +How content is organized across locales. + +**Pattern A: Mirror.** Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content. + +**Pattern B: Subset.** Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences. + +**Pattern C: Local.** Each locale has its own content largely independent of other locales. Common for media or community sites. + +Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial. + +The pattern affects: +- How content models are designed (does each piece have parent/translation relationships?) +- How translation is managed (workflow assumes the structure) +- How the team coordinates + +### Layer 3: hreflang and canonicals + +Telling search engines what's translated vs distinct. + +**hreflang** specifies the language and optional region for each version. + +```html +<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page"> +<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page"> +<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page"> +<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page"> +``` + +Rules: +- Every page lists every translated equivalent (including itself) +- Pages must reciprocate (page A says page B is its German version; page B says page A is its English version) +- `x-default` is the fallback for users in unspecified regions +- Each page has its own canonical pointing to itself (not to the default language) + +hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small. + +**Canonicals:** +- Self-referential per page +- Don't canonical the German page to the English page (search engines won't index the German page) + +### Layer 4: Translation workflow + +How content gets translated, kept fresh, and quality-controlled. + +**Sources of translation:** +- In-house translators (full-time staff) +- Translation agency (paid per word, professional) +- Community contributors (volunteer, variable quality, free) +- AI-assisted plus human review (cheap, fast, growing in quality) +- AI only (acceptable for some content, not for brand-critical) + +**Workflow stages:** + +1. **Source content authored** in the source language +2. **Translation requested** through a TMS (translation management system) or spreadsheet +3. **Translation produced** with translation memory (avoids retranslating reused phrases) +4. **Review** by a second translator or in-region staff +5. **Localization** beyond translation (currency, units, examples, cultural references) +6. **Publishing** in the destination locale +7. **Update propagation** when source content changes + +The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine. + +**Update propagation is the hardest part.** Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source. + +### Layer 5: Locale-aware UX + +Beyond translation, the experience must adapt. + +**Currency:** display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page. + +**Numbers:** thousand separators and decimals differ. `1,000.50` in en-US is `1.000,50` in de-DE. + +**Dates and times:** format and order vary. `MM/DD/YYYY` in en-US, `DD/MM/YYYY` in en-GB, `YYYY-MM-DD` (ISO) is universal but unfamiliar to many. + +**Names and addresses:** field order and required components differ. Country-aware address forms. + +**Phone numbers:** E.164 international format universally; display formatting per locale. + +**Units:** metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both. + +**Right-to-left (RTL) languages:** Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (`margin-inline-start` instead of `margin-left`) make this manageable. + +**Language switcher:** prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back. + +**Cultural sensitivity:** colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized. + +--- + +## Workflow + +### Step 1: Decide which locales + +Don't add languages just because you can. Each locale has ongoing maintenance cost. + +- Audience research: where are visitors and prospects? +- Business priority: which markets are growth targets? +- Content readiness: do you have the resources to maintain it? +- Legal: do regulations require localization (GDPR, accessibility laws)? + +### Step 2: Pick URL structure + +Subfolder for most. Document the choice and rationale. + +### Step 3: Pick content structure + +Mirror, subset, or local. Be honest about what's sustainable. + +### Step 4: Set up hreflang and canonicals + +Implement before launching the second locale, even if it's just one extra page. + +### Step 5: Set up translation workflow + +Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers. + +### Step 6: Localize beyond translation + +For each locale: +- Currency, numbers, dates, units +- Locale-specific images if needed +- Address forms +- Customer service hours and contact + +### Step 7: Implement language switcher + +- Prominent in the header or footer +- Shows the current locale clearly +- Lists all available locales in their own language +- Persists the choice (cookie or local storage) +- Doesn't auto-redirect based on browser; suggests instead + +### Step 8: Test + +- Each locale renders correctly +- hreflang links are valid (use a checker) +- Canonicals are self-referential per page +- Currency and dates are correct +- RTL layout is correct (for RTL locales) +- Language switcher works and persists +- Search-engine perspective: each locale is crawlable and indexable + +### Step 9: Launch and monitor + +Per locale: +- Indexing rate +- Traffic from intended geographies +- Engagement metrics in the locale +- Translation freshness (when did source content change without translation update?) + +### Step 10: Maintain + +- Translation update cadence (when source changes, when translations follow) +- Quarterly review of locale performance +- Sunset locales that aren't viable (better than maintaining a dead locale poorly) + +--- + +## Failure patterns + +**Auto-redirect based on browser language.** User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect. + +**Single canonical to default language.** Search engines can't index the translations. Self-canonical per page. + +**Reciprocal hreflang missing.** German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed. + +**hreflang language without region when region matters.** `hreflang="es"` is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions. + +**Auto-translated content treated as final.** Machine translation is an acceptable starting point. Human review is necessary for any user-facing content. + +**Currency baked into copy.** "$99/month" in body text breaks for European users. Use templated currency that adapts. + +**Hardcoded date formats.** "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale. + +**Field labels left in source language.** Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization. + +**Untranslated error messages.** User submits a form, gets an error in English on a French page. Frustrating. Translate UI states. + +**Untranslated emails.** Site is in French; transactional emails are English. Translate emails to match. + +**Forgotten locales in CMS.** Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift. + +**Locale switcher that doesn't work mid-flow.** User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale. + +**RTL layouts that don't actually flip.** Margin and padding hardcoded for LTR. Use CSS logical properties. + +**Sunset language without redirect.** Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language. + +--- + +## Output format + +An internationalization plan includes: + +- **Locale list:** with priority and audience rationale +- **URL structure:** chosen pattern and reason +- **Content structure:** mirror, subset, or local +- **hreflang plan:** how it's implemented +- **Translation workflow:** sources, stages, tools +- **Localization checklist:** beyond translation (currency, dates, etc.) +- **Language switcher design:** position, behavior, persistence +- **Test plan:** what's verified per locale +- **Maintenance plan:** update cadence, drift detection + +--- + +## Reference files + +- [`references/locale-checklist.md`](references/locale-checklist.md): Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal). diff --git a/dist/pi/.agents/skills/internationalization/references/locale-checklist.md b/dist/pi/.agents/skills/internationalization/references/locale-checklist.md new file mode 100644 index 0000000..8bb3bd8 --- /dev/null +++ b/dist/pi/.agents/skills/internationalization/references/locale-checklist.md @@ -0,0 +1,233 @@ +# Locale Checklist + +A per-locale checklist of everything that needs to adapt beyond translation. Walk through this for each locale before launch, and revisit when adding new content. + +--- + +## URL and structure + +- [ ] Locale URL pattern chosen and consistent (subfolder, subdomain, or ccTLD) +- [ ] Locale code uses standard format (BCP 47: `en`, `en-US`, `de-DE`, `zh-Hant`) +- [ ] Default locale handling decided (apex vs folder) +- [ ] URL slugs translated where appropriate (e.g., `/products/` → `/produkte/` for German) +- [ ] Or URL slugs kept consistent across locales (acceptable for many sites; prioritizes consistency over native readability) + +--- + +## Search engine signals + +- [ ] hreflang tags present on every page, every locale +- [ ] hreflang reciprocity verified (page A links to B, B links to A) +- [ ] hreflang includes `x-default` pointing to the fallback +- [ ] Canonical tags self-reference (each locale page canonicals to itself) +- [ ] Sitemaps include all locales (one sitemap per locale or a combined sitemap) +- [ ] robots.txt allows all locale paths +- [ ] Schema.org `inLanguage` attribute on appropriate types + +--- + +## Translation completeness + +- [ ] Page content translated +- [ ] Page titles and meta descriptions translated +- [ ] Image alt text translated +- [ ] Form labels translated +- [ ] Form validation messages translated +- [ ] Error pages (404, 500) translated +- [ ] Success messages translated +- [ ] Email templates translated (transactional, marketing) +- [ ] PDF or downloadable assets translated (or alternate version provided) +- [ ] Help and FAQ content translated +- [ ] Legal pages translated (privacy, terms, cookies) + +--- + +## Currency and money + +- [ ] Currency displayed matches the locale (EUR for euro zone, GBP for UK, JPY for Japan, etc.) +- [ ] Currency symbol position correct ($1,000 vs 1.000 €) +- [ ] Decimal separator correct (1,000.50 vs 1.000,50 vs 1 000,50) +- [ ] Thousand separator correct (comma, period, space, or none) +- [ ] Pricing tables localized to native pricing (not direct conversion) +- [ ] Tax handling (inclusive vs exclusive) matches local convention + +--- + +## Numbers and units + +- [ ] Number format follows locale (1,234.56 vs 1.234,56) +- [ ] Negative numbers (-5 vs (5)) follow convention +- [ ] Percentages format correctly (5% vs 5 %) +- [ ] Measurement units match (km vs miles, kg vs lb, °C vs °F) +- [ ] Paper sizes if relevant (A4 vs Letter) + +--- + +## Dates and times + +- [ ] Date format matches (DD/MM/YYYY for most of Europe, MM/DD/YYYY for US, YYYY-MM-DD ISO) +- [ ] Day-of-week localization (Monday vs Lundi vs 月曜日) +- [ ] Month names localized +- [ ] First day of week (Monday in Europe, Sunday in US) +- [ ] Time format (12-hour with AM/PM vs 24-hour) +- [ ] Time zone display where relevant +- [ ] Relative time strings localized ("2 hours ago" → "il y a 2 heures") + +--- + +## Names and addresses + +- [ ] Name field structure matches (single name field for some cultures, given/family for others, family-first ordering for some Asian languages) +- [ ] Address form fields adapt to country + - US: street, city, state, ZIP + - UK: street, town, county, postcode + - Germany: street, postal code, city + - Japan: postal code, prefecture, city, ward, block, building +- [ ] Postal code validation per country +- [ ] State/region/prefecture/county field renamed appropriately +- [ ] Country dropdown ordered by region or alphabetical (avoid US-first if not US-centric audience) + +--- + +## Phone numbers + +- [ ] Country code defaulted appropriately +- [ ] E.164 format stored (+CCNNNNNNNNNN) +- [ ] Display format adapts to country +- [ ] Validation accepts international formats + +--- + +## Imagery and media + +- [ ] Images depict locally relevant people, places, products +- [ ] Avoided imagery that's offensive in the locale (gestures, symbols, color associations) +- [ ] Cultural references in screenshots/examples are appropriate +- [ ] Image text translated (text in images doesn't auto-translate) +- [ ] Video subtitles or dubbing in the locale language + +--- + +## Layout and direction + +- [ ] LTR/RTL handling correct for the script +- [ ] CSS logical properties used (`margin-inline-start` instead of `margin-left`) +- [ ] Icons that imply direction (arrows, chevrons) flip for RTL +- [ ] Numbers display LTR even within RTL text (per Unicode bidi algorithm) +- [ ] Tables and lists adjusted for direction + +--- + +## Typography + +- [ ] Fonts support the script (not all fonts cover Cyrillic, CJK, Arabic, etc.) +- [ ] Font sizes adjusted if needed (some scripts read smaller; CJK often needs slightly larger) +- [ ] Line height appropriate (CJK often needs more) +- [ ] Word breaking handled (no breaking in the middle of CJK characters; break opportunities for Thai) +- [ ] Quotation marks correct ("..." in English, „..." in German, «...» in French, 「...」 in Japanese) + +--- + +## Search and sort + +- [ ] Search handles diacritics ("café" matches "cafe" or doesn't, by design) +- [ ] Sort order respects locale (German sorts ä with a, Swedish sorts ä after z) +- [ ] Search results in the same locale as the user (don't show English results to French users) + +--- + +## Forms and inputs + +- [ ] Input methods supported (IMEs for CJK, etc.) +- [ ] Pasting from clipboard works with non-Latin characters +- [ ] Field validation accepts non-Latin characters where appropriate (names should accept any Unicode) +- [ ] Min/max length constraints work for the script (Japanese names are often shorter; Arabic/Hebrew names use different character counts) + +--- + +## Legal and compliance + +- [ ] Privacy policy adapted to local laws (GDPR for EU, LGPD for Brazil, CCPA for California, etc.) +- [ ] Cookie consent matches local requirements +- [ ] Terms of service in local language and acknowledging local law +- [ ] Required disclaimers present (consumer protection, financial services, healthcare, etc.) +- [ ] Tax handling per locale (display inclusive in EU, exclusive in US, etc.) +- [ ] Local payment methods supported where customer expectations require + +--- + +## Customer support and contact + +- [ ] Support hours displayed in local timezone +- [ ] Support contact options match (phone numbers, chat, email, varies by region) +- [ ] Office address (if shown) is appropriate for the locale +- [ ] Local language support team or clear "support in [language]" indication + +--- + +## Marketing and SEO + +- [ ] Keyword research done in the local language (not just translated keywords) +- [ ] Meta titles and descriptions are locally compelling, not just translated +- [ ] Open Graph tags adapted (translated, locale-appropriate images) +- [ ] Schema.org markup translated where text-based +- [ ] Local search engines considered (Baidu in China, Yandex in Russia) +- [ ] Backlink strategy adapted to local web (local directories, local press) + +--- + +## Testing per locale + +- [ ] Page renders correctly in all major browsers +- [ ] Page renders correctly on mobile +- [ ] All links work and stay within the locale (or correctly switch locale) +- [ ] Forms submit correctly +- [ ] Confirmation flows work end-to-end (form → email → next step) +- [ ] No untranslated strings (search HTML for source-language strings) +- [ ] No broken images +- [ ] No layout breakage from longer or shorter text (German is often longer than English; CJK often shorter; Arabic similar to English in length but different layout) +- [ ] Performance comparable to default locale + +--- + +## Language switcher + +- [ ] Switcher visible on every page +- [ ] Available locales shown in their own language +- [ ] Current locale clearly indicated +- [ ] Switcher preserves the current page (not just sends to homepage) +- [ ] Switcher persists user choice (cookie or local storage) +- [ ] Switcher doesn't auto-redirect on first visit (suggests, doesn't force) + +--- + +## Maintenance + +- [ ] Translation update workflow defined +- [ ] Drift detection in place (when source changes, translation needs update) +- [ ] Per-locale analytics set up +- [ ] Per-locale error monitoring +- [ ] Translation quality reviewed periodically +- [ ] Locale sunset criteria defined (when to retire a poorly-performing locale) + +--- + +## Per-locale metrics to watch + +| Metric | Target | +|---|---| +| Page completion rate | Comparable to default locale | +| Form completion rate | Comparable to default locale | +| Bounce rate | Comparable to default locale | +| Time on page | Comparable to default locale | +| Conversion rate | Comparable to default locale | +| Translation freshness | Source content updates reflected within X days | + +A locale persistently underperforming on user metrics may have: +- Translation quality issues +- Cultural mismatches in copy or imagery +- Missing local payment or contact options +- Slow performance from far hosting +- Unmet user expectations (US e-commerce conventions used in markets that prefer different patterns) + +Investigate before scaling investment. diff --git a/dist/pi/.agents/skills/journey-mapping/SKILL.md b/dist/pi/.agents/skills/journey-mapping/SKILL.md new file mode 100644 index 0000000..c65508e --- /dev/null +++ b/dist/pi/.agents/skills/journey-mapping/SKILL.md @@ -0,0 +1,244 @@ +--- +name: journey-mapping +description: "Build customer journey maps and service blueprints that visualize the end-to-end user experience including touchpoints, emotions, friction, and underlying systems. Use this skill whenever the user wants to map a customer journey, build a service blueprint, identify friction across an experience, align teams on the user experience, or visualize touchpoints and pain points. Triggers on customer journey, journey map, service blueprint, user journey, experience map, touchpoint analysis, friction map, journey audit, end-to-end experience, customer experience map. Also triggers when the team has departmental views of users but no shared map of what the experience actually feels like." +category: research +catalog_summary: "Customer journey maps, service blueprints, friction analysis" +display_order: 3 +--- + +# Journey Mapping + +Build journey maps and service blueprints that surface friction, align teams, and identify opportunities. Stack-agnostic. Tool-agnostic. + +This skill is for mapping the experience. For testing specific touchpoints, use `usability-testing`. For broader generative research, use `ux-research`. For analyzing conversion, use `cro-optimization`. + +--- + +## When to use + +- Departments have different mental models of the customer experience +- Customer experience feels disjointed across touchpoints +- Specific friction or drop-off points need diagnosis +- Strategic planning needs a shared view of the user +- Service design (front-stage and back-stage) needs alignment +- New product or feature needs to be designed in context of broader experience + +## When NOT to use + +- Testing a single touchpoint or page (use `usability-testing`) +- Generative research before journey mapping (use `ux-research`) +- Operational process mapping that doesn't involve users +- Funnel optimization (use `cro-optimization`) + +--- + +## Required inputs + +- Identified user persona or segment to map (one map per segment) +- Existing research and data about that segment +- Cross-functional access (you cannot map back-stage without ops/support/engineering input) +- Time and stakeholder commitment (a real journey map is a project, not an afternoon) + +--- + +## The framework: 3 deliverables + +### 1. Customer journey map + +The user-facing view of the experience. + +**Structure (rows / lanes):** + +- **Phase.** The major stages in the journey (e.g., Awareness, Consideration, Onboarding, Activation, Retention, Advocacy). Phases vary by product type. +- **Steps.** Specific things the user does within each phase. +- **Touchpoints.** Where the user interacts with the product, brand, or service (web, app, email, support, social, in-person). +- **Goals.** What the user is trying to accomplish at this step. +- **Thoughts.** What's going through their mind. +- **Emotions.** The emotional state (often visualized on a curve). +- **Pain points.** Where things go wrong, friction, frustration. +- **Opportunities.** Where the experience could improve. + +**Format:** + +Typically a horizontal timeline with vertical lanes for each row. Phases across the top, touchpoints, thoughts, emotions, etc. underneath. + +### 2. Service blueprint + +The back-stage view that supports the customer-facing experience. + +**Adds these layers below the journey map:** + +- **Front-stage actions.** What employees do that the user sees (sales calls, support chats, in-store interactions). +- **Back-stage actions.** What happens behind the scenes (order fulfillment, data processing, internal handoffs). +- **Supporting processes.** Systems, vendors, infrastructure (CRM, payment processors, fulfillment partners). +- **Lines of visibility.** The line between front-stage (visible to user) and back-stage (invisible). + +The service blueprint shows where customer-facing problems originate in back-stage failures (e.g., the user's "shipping is slow" experience traces to a vendor handoff issue). + +### 3. Synthesized opportunity map + +Output of the mapping work. + +**Captures:** + +- **Top friction points.** Where the experience consistently fails users. +- **Untapped opportunities.** Moments where the experience could surprise and delight. +- **Disconnects.** Where front-stage and back-stage are misaligned. +- **Strategic gaps.** Where competitors have something the brand lacks (or vice versa). +- **Quick wins.** Low-effort, high-impact improvements. +- **Strategic bets.** Higher-effort transformations. + +This is the deliverable that produces decisions. The journey map and service blueprint are inputs; the opportunity map is the output that drives action. + +--- + +## Common phases by product type + +### Most products + +``` +Awareness → Consideration → Decision → Onboarding → Active use → Renewal/Repurchase → Advocacy +``` + +### SaaS + +``` +Trigger → Discovery → Evaluation → Trial → Onboarding → Activation → Habit → Expansion → Renewal → Advocacy +``` + +### Ecommerce + +``` +Need recognition → Discovery → Research → Decision → Purchase → Wait/Anticipation → Receive → Use → Reorder/Recommend +``` + +### Service + +``` +Awareness → Inquiry → Quote → Decision → Service delivery → Resolution → Follow-up → Repeat business +``` + +### Healthcare / high-stakes purchases + +``` +Trigger → Research → Provider selection → Appointment → Treatment → Recovery → Follow-up → Long-term outcome +``` + +Phases are not mandatory. Start with the user's actual experience and let the phases emerge from the steps. + +--- + +## How to gather the inputs + +A good journey map combines multiple sources of truth. + +### From users + +- **In-depth interviews.** Walk users through their actual experience. Ask for specifics from a recent occurrence. +- **Diary studies.** Users log their experience over the duration of the journey. +- **Surveys.** Quantitative signal at scale; less depth. + +### From the business + +- **Internal interviews.** Sales, support, success, ops. They see the experience from different angles than product or design. +- **Operational data.** Funnel data, support ticket categories, NPS responses, churn reasons. +- **System inventory.** What touchpoints exist, what tools support them, what data flows where. + +### Cross-validate + +- The user's experience as they describe it +- The data the business has about their behavior +- The internal team's perception of the experience + +These three views often disagree. The disagreements are themselves findings. + +--- + +## Workflow + +1. **Define scope.** One persona, one journey, one timeframe. Trying to map all users in one map produces a mess. +2. **Gather inputs.** User interviews, internal interviews, operational data. Plan 2 to 4 weeks for inputs. +3. **Draft the journey.** Phases, steps, touchpoints. Get to a working draft fast; iterate. +4. **Add the layers.** Goals, thoughts, emotions, pain points. +5. **Build the service blueprint.** Front-stage, back-stage, supporting processes. +6. **Identify opportunities.** Use the friction points and disconnects. +7. **Validate with users.** Does this match their actual experience? Refine. +8. **Workshop with stakeholders.** Walk teams through the map. Ensure shared understanding. +9. **Translate to action.** Specific projects, owners, timelines. +10. **Maintain.** A journey map is a living document. Revisit annually or after major changes. + +--- + +## Failure patterns + +- **Mapping without research.** A journey map built from internal assumptions reflects assumptions, not users. +- **One map for all users.** The mid-market buyer and enterprise buyer have different journeys. Don't merge. +- **No back-stage layer.** The map shows symptoms, not causes. +- **Beautiful map, no action.** Investment in production value at the expense of decisions. +- **Map as artifact, not tool.** Filed in Figma, never re-opened. +- **Ignoring emotional layer.** The "what" without the "how it feels" misses the point of journey mapping. +- **Vague pain points.** "Frustrating onboarding" - what specifically? When? Why? +- **Quick wins identified, never executed.** Same as research findings that don't ship. +- **Annual exercise without followup.** Year-old journey map describes year-old user. + +--- + +## Output format + +Default outputs: + +1. **Journey map** (visual, typically Figma / FigJam / Miro, plus a markdown narrative version) +2. **Service blueprint** (visual, typically same tool) +3. **Opportunity map** (markdown, prioritized list) + +Markdown narrative version of journey map: + +```markdown +# [Persona] journey map + +## Phase 1: [Phase name] + +### Step: [Step name] +- **Touchpoint:** [Where this happens] +- **Goal:** [What the user wants here] +- **Thoughts:** [What they're thinking] +- **Emotion:** [State on the emotional curve] +- **Pain points:** [Friction] +- **Opportunities:** [Improvement potential] + +### Step: [Step name] +[Same structure] + +## Phase 2: [Phase name] +[Repeat] + +## Service blueprint additions + +### Phase 1 +- **Front-stage actions:** [What employees do user-visibly] +- **Back-stage actions:** [What happens behind the scenes] +- **Supporting processes:** [Systems involved] + +[Repeat per phase] + +## Opportunity map + +### Critical friction +1. [Specific issue, with evidence] +2. [Specific issue, with evidence] + +### Quick wins +1. [Specific opportunity, with effort/impact] + +### Strategic bets +1. [Specific opportunity, with effort/impact] + +### Cross-team disconnects +1. [Specific disconnect, with implication] +``` + +--- + +## Reference files + +- [`references/journey-map-template.md`](references/journey-map-template.md) - Fillable journey map and service blueprint template. diff --git a/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md b/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md new file mode 100644 index 0000000..372ea22 --- /dev/null +++ b/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md @@ -0,0 +1,317 @@ +# Journey Map Template + +Fillable journey map and service blueprint template. Customize phases to fit the specific product or service. + +--- + +## Map metadata + +**Persona / segment mapped:** [Specific persona. Not "users" - "First-time buyers in the 25-40 age range exploring B2B project management tools."] + +**Time horizon mapped:** [Pre-purchase to first 90 days? Full lifetime? Specific feature?] + +**Map version:** [X.Y] + +**Last updated:** [YYYY-MM-DD] + +**Owner:** [Person or team] + +**Source data:** [Interviews, surveys, support tickets, analytics. List with counts.] + +--- + +## Map structure + +| Phase | Step | Touchpoint | Goal | Thoughts | Emotion | Pain points | Opportunities | +|---|---|---|---|---|---|---|---| + +--- + +## Phase 1: [Phase name, e.g., Awareness] + +### Step 1.1: [Step name, e.g., Encounters problem] + +**Touchpoint:** [Where this happens. Could be offline. "Conversation with peer." Or online: "LinkedIn post."] + +**Goal:** [What the user is trying to accomplish at this step] + +**Thoughts:** +- "[Specific thought, ideally a real quote from research]" +- "[Specific thought]" +- "[Specific thought]" + +**Emotion:** [Emotional state, ideally from a defined set: confused, hopeful, frustrated, curious, anxious, confident, etc.] + +**Emotional intensity:** [1 to 5, for plotting on the emotional curve] + +**Pain points:** +- [Specific pain, with evidence] +- [Specific pain, with evidence] + +**Opportunities:** +- [Specific improvement opportunity] +- [Specific improvement opportunity] + +**Time spent at this step:** [Minutes / hours / days / weeks - average and range] + +--- + +### Step 1.2: [Step name] + +[Repeat structure] + +--- + +## Phase 2: [Phase name, e.g., Consideration] + +### Step 2.1: [Step name, e.g., Searches for solutions] + +**Touchpoint:** [e.g., Google search, then 4 to 6 vendor websites] + +**Goal:** [Build a shortlist of options that could fit] + +**Thoughts:** +- "[Quote]" +- "[Quote]" + +**Emotion:** [State] + +**Emotional intensity:** [1 to 5] + +**Pain points:** +- [Specific pain] +- [Specific pain] + +**Opportunities:** +- [Opportunity] + +**Time spent:** [Range] + +--- + +### Step 2.2: [Step name] + +[Repeat] + +--- + +## Phase 3: [Phase name, e.g., Decision] + +[Repeat structure] + +--- + +## [Continue with phases relevant to the journey...] + +--- + +## Emotional curve + +Plot the emotional intensity across the journey. The curve typically reveals the moments of highest joy and highest frustration. + +``` +Emotion +intensity + 5 │ + 4 │ ● + 3 │ ● ● ● + 2 │ ● ● ● ● + 1 │ ● ● + └────────────────────── + 1.1 2.1 3.1 4.1 + Phase / Step +``` + +[Document the emotional curve in your visual tool. Note the peaks (highest joy) and troughs (highest frustration). These are the most strategic points in the journey.] + +--- + +## Service blueprint layers + +For each phase, document the back-stage view. + +### Phase 1: [Phase name] + +**Front-stage actions** (employees in user view): +- [Action] +- [Action] + +**Back-stage actions** (employees behind the scenes): +- [Action] +- [Action] + +**Supporting processes** (systems, tools, vendors): +- [Process / system] +- [Process / system] + +**Lines of visibility issues:** +- [Where back-stage failures cause front-stage problems] + +--- + +### Phase 2: [Phase name] + +[Repeat] + +--- + +## Disconnects and gaps + +The most valuable findings often come from comparing layers. + +### Front-stage / back-stage disconnects + +| Issue | Front-stage symptom | Back-stage cause | +|---|---|---| +| | | | +| | | | + +### Internal team perception vs user reality + +| Internal belief | User reality | Gap | +|---|---|---| +| | | | +| | | | + +### Touchpoint / message inconsistencies + +| Touchpoint A says | Touchpoint B says | Confusion result | +|---|---|---| +| | | | + +--- + +## Persona context (for reference) + +A reminder of who this map represents. + +**Persona:** [Name and one-line description] + +**Demographics:** +- Age range: +- Role / job: +- Company size or context: +- Geography: +- Tech savviness: + +**Goals:** +- [Primary goal] +- [Secondary goal] +- [Secondary goal] + +**Frustrations:** +- [Frustration] +- [Frustration] + +**Behavior patterns:** +- [Pattern] +- [Pattern] + +**Quote that captures them:** +> "[Quote from a research participant who exemplifies this persona]" + +--- + +## Data sources + +Document where the map's claims come from. Builds credibility and traceability. + +| Claim | Source | Evidence | +|---|---|---| +| [Pain point at step 2.1] | 8 of 10 interviews | [Quote samples] | +| [Behavior at step 1.2] | Analytics: 73% drop-off | [Funnel data] | +| [Emotion at step 3.1] | Survey, 45 responses | [Score data] | + +--- + +## Opportunity map + +The output that drives action. + +### Critical friction (fix soon) + +| Friction | Phase / step | Evidence | Recommended action | Effort | Owner | +|---|---|---|---|---|---| +| [Specific] | | | | S/M/L | | +| [Specific] | | | | S/M/L | | + +### Quick wins (low effort, meaningful impact) + +| Opportunity | Phase / step | Recommended action | Effort | Impact | +|---|---|---|---|---| +| [Specific] | | | S | M | + +### Strategic bets (high effort, transformative) + +| Opportunity | Phase / step | Recommended action | Effort | Impact | +|---|---|---|---|---| +| [Specific] | | | L | H | + +### Cross-team alignment opportunities + +[Issues that require multiple teams to coordinate, not single-team fixes.] + +- [Issue, teams involved, recommended approach] +- [Issue, teams involved, recommended approach] + +--- + +## Action plan + +Specific projects from the opportunity map. + +### Immediate (next 30 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Near-term (60 to 90 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Strategic (next 2 to 4 quarters) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +--- + +## Re-mapping schedule + +Journey maps decay. Schedule re-mapping: + +- **Triggering events:** Major product launch, new persona segment, significant business model change, drop in NPS or retention +- **Default cadence:** Annual review, with light updates quarterly + +--- + +## Workshop outputs + +Use this map in stakeholder workshops. Capture outputs: + +**Workshop 1: Validation** +- Date: +- Attendees: +- Findings validated: +- Findings disputed: +- New findings surfaced: + +**Workshop 2: Prioritization** +- Date: +- Attendees: +- Top opportunities agreed: +- Decisions made: +- Open questions: + +--- + +## Companion artifacts + +Often produced alongside a journey map: + +- **Persona document.** Detailed persona that this journey map represents. +- **Quote library.** Direct user quotes organized by phase. Powerful in stakeholder presentations. +- **Highlight reel video.** 5 to 10 minute compilation of user moments mapped to journey phases. +- **Service blueprint.** Detailed back-stage map (this template includes a layer; a full blueprint deserves its own document). +- **Opportunity backlog.** All opportunities, scored and queued for execution. diff --git a/dist/pi/.agents/skills/jtbd-framing/SKILL.md b/dist/pi/.agents/skills/jtbd-framing/SKILL.md new file mode 100644 index 0000000..56313a8 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/SKILL.md @@ -0,0 +1,260 @@ +--- +name: jtbd-framing +description: "The Jobs-to-be-Done framework as applied product methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity (discovery, prioritization, positioning) and where it becomes performative ritual (job-statement workshops that do not drive decisions, persona-theater disguised as JTBD). Triggers on jobs-to-be-done, JTBD, job statements, struggling moments, hire criteria, fire criteria, switch triggers, functional emotional social jobs, outcome-driven innovation. Also triggers when a team is over-relying on feature-request lists or persona archetypes that do not drive product decisions, when a positioning conversation needs the framing JTBD provides, or when discovery is producing outputs that do not connect to product strategy." +category: product +catalog_summary: "Jobs-to-be-Done framework. Job statements, struggling moments, hire/fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD earns its keep and where it becomes performative" +display_order: 11 +--- + +# Jobs-to-be-Done Framing + +A senior product leader's playbook for the Jobs-to-be-Done framework as applied methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity and where it becomes performative ritual. + +JTBD has become one of the more cited and less practiced frameworks in product. Teams cite it in strategy docs, run job-statement workshops, produce wall-sized artifacts, and continue building from feature requests and persona archetypes the next quarter. The methodology gets the credit; the practice gets skipped. + +This skill is JTBD as applied product methodology. The framework's actual contribution: surfacing what users are trying to ACCOMPLISH (the job) rather than treating users as preference-aggregators (feature requests) or demographic archetypes (persona theater). When the framing is grounded in struggling moments and hire/fire criteria, it produces decisions; when it stops at the job-statement worksheet, it produces ritual. + +This skill is honest about both modes. JTBD genuinely earns its keep in discovery, prioritization, and positioning when applied with rigor. It becomes ceremony when teams treat job statements as deliverables rather than as analytical tools. + +The voice is the senior product leader who has used JTBD well and watched plenty of teams use it badly. Concrete, opinionated about what the framework actually contributes, willing to call out where it gets oversold. + +When to use this skill: applying JTBD to a discovery cycle, replacing persona-driven prioritization with job-driven prioritization, reframing positioning around what users hire the product to do, or auditing whether existing JTBD work in the org is driving decisions. + +--- + +## What this skill is for + +This skill spans JTBD as a framing technique within product work. The PM-skill distinction: + +- `discovery-research-synthesis` is broader synthesis discipline; JTBD is one framing technique within it. +- **`jtbd-framing` (this skill)** is the specific JTBD methodology, its strengths, and its failure modes. +- `pm-spec-writing` is downstream: specs reference jobs as input. +- `creative-direction` is positioning territory; JTBD informs positioning but does not replace creative direction. +- `roadmap-planning` is downstream: roadmap can be organized around jobs rather than features. + +The audience: senior PMs, product directors, product strategists, agencies running discovery and positioning work, in-house teams considering or already using JTBD. + +What is not in scope: other product strategy frameworks (Wardley mapping, North Star, OKRs); the broader synthesis discipline (`discovery-research-synthesis` covers it); the demographic-persona work that sometimes gets confused with JTBD. + +--- + +## Feature-request-list vs persona-theater vs job-framing + +The keystone framing. + +**Feature-request-list.** "Users want X, Y, Z." Treats users as preference-aggregators. The product team builds the most-requested features. Output: a product that satisfies stated preferences but misses what users were actually trying to accomplish. Users do not always know what would solve their problem; they describe symptoms, not solutions. Feature-list-driven products often improve incrementally without becoming meaningfully better. + +**Persona-theater.** Demographic personas with cute names. "Marketing Manager Maria, 35, urban, Pinterest user, drinks oat milk lattes." Decorative, not decision-driving. Persona characteristics rarely correlate with what the user needs from the product; demographic detail substitutes for behavioral insight. Personas in the wild often live as wall posters that nobody references in actual prioritization debates. + +**Job-framing.** Users hire products to do jobs. The job is what the user is trying to accomplish, not who the user is or what features they request. The framing surfaces struggling moments (when do users feel pulled toward an alternative); hire criteria (what makes them adopt a product); fire criteria (what makes them switch away). Output: product decisions grounded in user motivation rather than user description. + +The litmus test. Take a product decision the team is debating. Can JTBD ground the decision? "Should we build feature X?" Reframed: "What job would feature X help users do? What job is currently done badly that this addresses?" If the JTBD framing produces clearer arguments on both sides, the framing is earning its keep. If the JTBD framing just adds vocabulary without resolving the debate, the framing is ritual. + +--- + +## The job statement structure + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." + +**Situation.** The context, trigger, or moment when the job becomes active. Not a demographic; a moment. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck..." +- "When I get a customer escalation outside of business hours..." + +**Motivation.** What the user is trying to do in that situation. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage and respond without disrupting my evening too much..." + +**Outcome.** What success looks like; what the user is trying to achieve by doing the job. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." + +The structure forces specificity at all three levels. Vague situations, vague motivations, or vague outcomes produce job statements that drive nothing. + +Detail in [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md). + +--- + +## Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when the alternative tools they have feel inadequate, when they would actively prefer a different way of doing the job. + +**The signal.** Users describe friction in their current approach. They describe workarounds. They describe wishing they had something better. They describe specific moments when the current approach broke down. + +**The methodology.** Discovery interviews surface struggling moments through specific prompts: "Walk me through the last time you did X." "What was hardest about that?" "What would you have done differently if you could?" Specific recent moments produce richer data than abstracted descriptions of "how I usually do this." + +**The pattern recognition.** Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well in the market. + +**The pitfall.** Teams that interview without grounding in specific moments produce abstracted job descriptions that cannot drive decisions. "Users want to be more productive" is not a struggling moment; "I lost an hour on Tuesday assembling the board metrics from three different dashboards because none of them had the slice I needed" is. + +Detail in [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md). + +--- + +## Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground the framework in real decisions users make. + +**Hire criteria.** + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +**Fire criteria.** + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +**Why hire/fire matters.** + +- Hire criteria reveal what the product needs to be excellent at to win adoption. +- Fire criteria reveal what the product needs to maintain to retain users. +- The two are often different: features that win adoption are not always the features that prevent churn. + +**The methodology.** Customer interviews surface hire/fire through specific prompts: "What were you doing before you adopted X?" "What made you switch?" "If you switched away from X tomorrow, what would the trigger be?" Recent switch decisions are particularly rich; users remember the specific moment. + +Detail in [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md). + +--- + +## Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. + +**Functional dimension.** What the user is mechanically trying to accomplish. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." + +**Emotional dimension.** How the user feels (or wants to feel) doing the job. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." + +**Social dimension.** How the user wants to be perceived doing the job. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." + +**Why three dimensions matter.** + +- Products that win on functional alone often lose to alternatives that also serve emotional and social. +- Some product decisions hinge on emotional dimensions ("the user wants to feel in control"); functional analysis alone misses these. +- Social dimensions inform positioning more than functional descriptions do. + +**The discipline.** For each job statement, ask the three dimensions explicitly. Most early job statements are functional-only; the addition of emotional and social often reveals what the product actually needs to address. + +Detail in [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md). + +--- + +## Where JTBD adds clarity vs where it becomes ritual + +The honest framing. + +**Where JTBD genuinely earns its keep.** + +- **Discovery.** When research is grounded in struggling moments and hire/fire decisions, JTBD surfaces the user motivation that feature-list discovery misses. Discovery interviews structured around jobs produce richer data than ones structured around feature preferences. +- **Prioritization.** When the team is debating which work to prioritize, jobs ground the debate in what users are trying to accomplish. "Does this work help users do an important job better?" cuts through the politics of feature-request prioritization. +- **Positioning.** When marketing or sales is articulating what the product does, jobs frame the product as a way of accomplishing something the customer cares about, rather than as a feature list. + +**Where JTBD becomes ritual.** + +- **Job-statement workshops as deliverables.** The team runs a workshop, produces a wall of job statements, and never references the artifacts in subsequent decisions. The workshop became the deliverable; the analytical work did not happen. +- **Job statements substituted for personas without analytical rigor.** "We have JTBD now" but the team treats job statements as named characters (Job Bob, Job Alice) instead of as analytical tools. +- **Mandatory JTBD for every product question.** Every meeting starts with "what's the job?" Even when the question does not benefit from the framing. The methodology becomes a tax rather than a tool. +- **JTBD as compliance.** The org adopts JTBD because a leadership book or conference talk endorsed it; teams produce JTBD artifacts to show they are using the framework; nobody actually uses the framework to decide. + +**The honest signal.** If the team can show how a recent product decision was different because of JTBD analysis, the framework is earning its keep. If the team uses JTBD vocabulary but cannot trace decisions to JTBD analysis, the framework is ritual. + +--- + +## Applying JTBD to discovery, prioritization, positioning + +The three modes where JTBD genuinely contributes. + +**Discovery.** Structure interviews around recent struggling moments, hire decisions, and fire decisions. Gather job statements after the interviews from the data, not before. Cluster jobs across users. Name jobs from the clusters. Pair with `discovery-research-synthesis` for the broader synthesis discipline. + +Detail in [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md). + +**Prioritization.** When evaluating roadmap candidates, frame each candidate by the job(s) it addresses. Ask: which jobs is the product currently doing badly? Which candidates address those jobs vs adjacent or unrelated work? Pair with `roadmap-planning` for the broader prioritization discipline. + +Detail in [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md). + +**Positioning.** When articulating what the product is for, lead with the job rather than the features. "Help product teams synthesize discovery research into decisions" is a job framing; "AI-powered research synthesis with collaboration tools" is a feature framing. Pair with `creative-direction` and `brand-discovery` for the broader positioning work. + +Detail in [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md). + +- "We did the JTBD workshop but nothing changed in our roadmap." Job-statement workshop as deliverable; no analytical work after the workshop. +- "Our job statements all sound the same." Generic job statements; not grounded in specific struggling moments. Re-ground in interview data. +- "Our jobs read like feature requests." "When I am using product X, I want feature Y" is not a job; the job is what the user was trying to accomplish, independent of the product. +- "We have personas and jobs and they contradict each other." Personas are demographic; jobs are situational. They do not have to align; if they conflict, jobs usually carry more decision weight. +- "JTBD says we should build everything." Without prioritization across jobs, JTBD identifies many opportunities and does not pick. Pair with prioritization discipline. +- "We dropped JTBD because it became theater." Common; the recovery is JTBD as analytical tool, not JTBD as ritual. Use the framework where it earns its keep; do not force it everywhere. +- "Our job statements are functional only." Add emotional and social dimensions; many product decisions hinge on the latter two. +- "We cannot agree on the job." Often signals different segments with different jobs. Surface the segment differences. +- "Our marketing copy uses JTBD vocabulary but our product does not." Positioning-product gap; the marketing claim is not load-bearing in product decisions. + +--- + +## The framework: 12 considerations for JTBD framing + +When applying JTBD or auditing JTBD work, walk these 12 considerations. + +1. **Job-framing, not feature-list or persona-theater.** Users hire products to accomplish jobs. +2. **Job statement structure: situation, motivation, outcome.** Specific at all three levels. +3. **Struggling moments ground the jobs.** Specific recent moments, not abstractions. +4. **Hire criteria identified.** What makes users adopt the product over alternatives. +5. **Fire criteria identified.** What makes users switch away (or would). +6. **Functional, emotional, social dimensions surfaced.** All three; not functional only. +7. **Jobs derived from data, not workshop output.** Job statements emerge from interview data, not from whiteboard sessions. +8. **JTBD applied where it earns its keep.** Discovery, prioritization, positioning. Not as ritual. +9. **Segment differences in jobs surfaced.** When the same product is hired for different jobs by different segments. +10. **Decisions traceable to JTBD analysis.** Each major decision can be explained through the job framing. +11. **JTBD vocabulary not substituted for analytical work.** Vocabulary without analysis is ritual. +12. **Honest assessment of where JTBD does not help.** Some questions do not benefit from the framing; force-fitting produces ritual. + +The output of the framework is product decisions grounded in user motivation rather than user description, with the framing applied where it adds clarity and held back where it would become ritual. + +--- + +## Reference files + +- [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md) - The situation/motivation/outcome structure with worked examples. Common structural failures (vague situations, motivation as feature request, outcome as feature output). +- [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md) - Discovery prompts that surface struggling moments. Pattern recognition across users. The specific-moment vs abstraction distinction. +- [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md) - Methodology for surfacing hire and fire criteria. Why the two are often different. Recent-switch interview discipline. +- [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md) - Three dimensions per job. Why functional-only fails. Worked examples per dimension. Positioning implications of social dimension. +- [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md) - Discovery interview structure around jobs. Job clustering. Naming jobs from data. Pair with discovery-research-synthesis. +- [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md) - Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. Pair with roadmap-planning. +- [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md) - Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pair with creative-direction. +- [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md) - 9+ failure patterns with diagnoses and cures. The cross-cutting pattern: JTBD as ritual vs JTBD as analytical tool. + +--- + +## Closing: jobs over features + +The Jobs-to-be-Done framework is one of the most useful product methodologies available when applied with rigor, and one of the most performative when applied as ritual. The difference is in whether the framework drives decisions or decorates documentation. + +Jobs over features is a real shift in product thinking. Feature-list discovery treats users as preference-aggregators; persona archetypes treat users as demographic categories; job-framing treats users as people trying to accomplish things, where the product is one tool they hire (or fire) for the job. + +The teams that benefit from JTBD are the ones that take the analytical work seriously: grounding jobs in struggling moments, identifying hire and fire criteria, surfacing functional-emotional-social dimensions, deriving jobs from data, and applying the framing where it earns its keep. The teams that adopt JTBD vocabulary without the analytical work produce ritual. + +When in doubt about whether a JTBD application is real or ritual, ask: can a recent product decision be traced to the JTBD analysis, or did the JTBD work happen in parallel with decisions that were made on other grounds? If the former, JTBD is doing its work. If the latter, the framework is decoration. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md new file mode 100644 index 0000000..cddb634 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md @@ -0,0 +1,211 @@ +# Applying JTBD to discovery + +How JTBD shapes discovery interview structure, job clustering, and naming jobs from data. Pairs with `discovery-research-synthesis` for the broader synthesis discipline. + +JTBD's strongest contribution to discovery is structural: interviews grounded in struggling moments and hire/fire decisions produce richer data than interviews that ask about feature preferences or use cases. + +--- + +## Structuring discovery interviews around jobs + +The JTBD discovery interview structure differs from feature-elicitation interviews. + +**Feature-elicitation interview pattern.** + +- "What problems are you trying to solve?" +- "What features would help?" +- "What is your ideal product?" + +This structure produces user-prescribed solutions: feature requests, ideal-product fictions, and abstracted preferences. The data is hard to act on because users do not always know what would actually help. + +**JTBD interview pattern.** + +- "Walk me through the last time you did [task]. What happened? What was hardest?" +- "What were you doing before you adopted [current solution]? What made you switch?" +- "Tell me about a recent time when [task] went badly. What was different about that time?" +- "If you switched away from [current solution] tomorrow, what would the trigger be?" + +This structure grounds the data in specific moments and real decisions. Users describe their experience; the PM doing synthesis interprets what the experience implies. + +--- + +## Interview prompts that work + +**Recent specific moments.** + +- "Walk me through the most recent time you did [task]." +- "What was the last week when [task] cost you more time than usual?" +- "When was the last time [task] surprised you in a bad way?" + +**Hire decision prompts.** + +- "Tell me about the moment you decided to start using [product]." +- "What were you doing before? What made you switch?" +- "What alternatives did you consider? What ruled them out?" + +**Fire decision prompts (for users who switched).** + +- "Tell me about the moment you decided to switch away from [product]." +- "What was the alternative starting to look better? What tipped you?" +- "Looking back, why didn't you switch sooner?" + +**Workaround prompts.** + +- "What's something you do that takes longer than it should?" +- "What workarounds have you built?" +- "When was the last time you accepted a worse outcome because the better path was too painful?" + +--- + +## Interview prompts that fail + +**Hypothetical prompts.** + +- "What would your ideal product look like?" (produces fiction) +- "If you had a magic wand, what would you change?" (produces wishlist) +- "What features would you like?" (produces feature lists) + +**Abstracted prompts.** + +- "How do you usually do [task]?" (produces averaged descriptions) +- "What's your typical experience?" (loses the specifics) +- "What kind of user are you?" (produces self-categorization) + +**Leading prompts.** + +- "Don't you find [feature] frustrating?" (confirms the team's hypothesis) +- "Wouldn't it be great if [feature]?" (produces agreement, not data) + +--- + +## The interview length and depth + +JTBD interviews benefit from depth. Surface answers come quickly; deeper jobs surface in the second half of an interview. + +**Typical structure.** + +- Minutes 0-15: warm-up, general context, what the user does and how their work fits together. +- Minutes 15-45: the recent specific moments, walk-throughs, struggling moments. The richest data emerges here. +- Minutes 45-60: hire and fire decisions, alternatives considered, switch decisions. +- Minutes 60-75 (when warranted): emotional and social dimensions, how the user wants to be perceived doing the work. +- Minutes 75-90: closing prompts, what the user wishes was different, what they would have done differently. + +**The depth payoff.** Users open up after 30-40 minutes. The struggling moments they describe in the second half are usually richer than the first-half answers. Cutting interviews short at 45 minutes loses the depth. + +**The 90-minute upper bound.** Beyond 90 minutes, fatigue degrades data quality. Schedule for 90; complete in 60-75; leave room for the depth without forcing it. + +--- + +## Job clustering from interview data + +After interviews, jobs emerge through clustering (per the synthesis sequence in `discovery-research-synthesis`). + +**The clustering work.** + +- Tag struggling moments and hire/fire decisions across interviews. +- Cluster moments that share underlying jobs (the user was trying to accomplish the same thing). +- Each cluster becomes a candidate job. +- Name the job from the cluster, not from a pre-built list. + +**Common clustering patterns.** + +- Multiple users described the same kind of friction in similar contexts. The cluster becomes one job. +- Multiple users described different surface-level frictions but the same underlying motivation and outcome. The cluster reveals a job that surfaces differently across users. +- One user's described moment is unique. May be an edge case, may be a job worth surfacing as smaller-segment. + +--- + +## Naming jobs from data + +Jobs are named from the cluster, not from a pre-built taxonomy. + +**The naming process.** + +- Read the cluster's contributing moments. +- Identify the situation, motivation, and outcome that recurred. +- Write the job statement: "When [situation], I want to [motivation], so I can [outcome]." +- Test the statement against the source moments: does it capture what users were trying to accomplish? + +**The iteration discipline.** First-pass job statements are usually too narrow or too broad; refine through iteration. + +**Worked example.** A cluster of moments around quarterly board prep: + +- Multiple users described assembling data from multiple sources. +- Multiple described uncertainty about whether they had the right slice. +- Multiple described the time pressure and the disruption to other work. +- Multiple described wanting to walk into the board with confidence. + +First-pass job statement: "When preparing the board deck, I want to assemble data from multiple sources, so I can present numbers correctly." + +Second-pass refinement: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The second pass captures the situation more specifically (quarterly business reviews, not just any board deck), the motivation more specifically (coherent narrative I can defend, not just data assembly), and the outcome more specifically (answer questions confidently without grinding the night before, not just present numbers correctly). + +--- + +## How many jobs emerge from typical discovery + +Strong discovery cycles often surface 3-8 jobs across the research batch. + +**Smaller numbers (1-2 jobs).** May indicate the discovery scope was narrow (only one user task investigated) or the synthesis under-clustered. + +**Mid numbers (3-8 jobs).** Typical for substantive discovery cycles. Jobs cover the major user motivations the research surfaced. + +**Larger numbers (10+ jobs).** May indicate over-clustering (each cluster is small and the overall synthesis is fragmented) or genuine breadth (the research investigated multiple distinct user contexts). + +The discipline. Job count should reflect the underlying patterns the data reveals, not a target number. Force-fitting to 7 jobs because "that feels right" produces synthesis that does not match the data. + +--- + +## Pairing JTBD discovery with quantitative validation + +Qualitative job patterns often warrant quantitative validation. + +**The pattern.** + +- Job statement claims a specific frequency or severity ("users hit this friction in 40% of attempts"). +- Quantitative data validates: analytics shows configuration step abandonment rate; survey data confirms the segment proportion; product instrumentation captures the in-the-moment frequency. +- If validation confirms: the job statement is strongly supported. +- If validation contradicts: revise the job statement to reflect the data. + +**Pair with `experiment-design`** for rigorous validation methodology and `product-analytics-setup` for the instrumentation that makes validation possible. + +--- + +## When JTBD discovery does not fit + +Some discovery does not benefit from JTBD framing. + +**Greenfield categories.** When the product is a category-defining product, users may not have struggling moments because the alternative is not having the capability at all. JTBD framing is useful but may need to be supplemented with broader product strategy. + +**Highly novel use cases.** When users have not yet developed mental models for the use case (e.g., new technology categories), struggling moments may not exist because the activity itself does not exist. Discovery may need to focus on adjacent activities and what users would do if the new capability existed. + +**Pure positioning research.** When the discovery is about how to position an existing product, hire and fire criteria interviews are useful, but emotional and social dimensions of positioning matter as much as the JTBD-framed jobs. + +**The discipline.** JTBD is a tool, not a mandate. When the discovery question fits the framework, use it. When it does not fit cleanly, supplement with other discovery techniques. + +--- + +## Common JTBD-discovery failures + +**Eliciting feature lists instead of jobs.** Interview prompts ask "what features do you want" rather than "what are you trying to accomplish." Restructure prompts. + +**Pre-built job taxonomy.** Researchers arriving with named jobs and slotting interview data into them. Jobs should emerge from data; pre-built taxonomies confirm what the team already thinks. + +**Skipping struggling moments.** Interviews capture preferences and use-cases without grounding in specific friction events. Add struggling-moment prompts. + +**Skipping hire/fire decisions.** Interviews ask about current usage but not about adoption or switch decisions. Add hire and fire prompts. + +**Job statements written from intuition rather than data.** Researchers writing jobs based on what they think users are trying to do, without grounding in interview clusters. + +**Force-fitting all data to JTBD.** Some interview data does not fit the JTBD framing cleanly; the team forces it in anyway. Better: surface what JTBD captures and supplement with other framings for the rest. + +--- + +## Methodology-level choices that stay in the public skill + +The interview structure that grounds in jobs. Prompts that work and fail. Interview length and depth. Job clustering from interview data. Naming jobs from data. Typical job counts. Pairing with quantitative validation. When JTBD discovery does not fit. Common failures. + +## Implementation choices that stay internal + +Specific interview templates. Specific recording and tagging tools. Specific synthesis tooling for job clustering. Specific recruitment criteria. The team's own conventions for interview cadence and batch sizing. These vary by team. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md new file mode 100644 index 0000000..8d40f19 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md @@ -0,0 +1,201 @@ +# Applying JTBD to positioning + +Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pairs with `creative-direction` and `brand-discovery` for the broader positioning work. + +JTBD's contribution to positioning is the lead message: positioning that names the job the product helps users accomplish creates affinity in ways feature lists do not. The functional, emotional, and social dimensions of jobs all inform positioning differently. + +--- + +## Job-led vs feature-led positioning + +The two positioning approaches. + +**Feature-led positioning.** + +- "AI-powered analytics with collaborative dashboards and integrations." +- "Cloud-native CRM with automation and reporting." +- "Project management software with timelines, kanban, and integrations." + +Characteristics: lists features; competes on feature comparison; gets compared head-to-head with alternatives that have similar feature lists; produces buyer behavior of feature-checklist evaluation. + +**Job-led positioning.** + +- "Help product teams synthesize discovery research into decisions." +- "The CRM your sales team will actually use because it stays out of their way." +- "Run the project, not the project management tool." + +Characteristics: names what the product helps users accomplish; competes on outcome rather than feature parity; produces buyer behavior of job-fit evaluation; harder to copy because the positioning is built on understanding the job. + +**The trade-off.** Feature-led positioning is easier to write and easier for buyers to evaluate. Job-led positioning is harder to write but produces stronger affinity and is more durable to feature-parity competition. + +--- + +## When job-led positioning works + +Job-led positioning works best when: + +- The product addresses a job that users currently do badly with alternatives. +- The job has emotional or social dimensions that the positioning can serve. +- The user can recognize themselves in the job description. +- The market category is mature enough that feature comparison is no longer differentiating. + +Job-led positioning is less effective when: + +- The product is a new category and users do not yet recognize the job. +- The product is a commodity where job-fit is similar across alternatives. +- The buyer is not the user, and the buyer evaluates on different criteria than job-fit. + +--- + +## The lead message structure + +The lead message is the first thing prospects encounter (homepage hero, ad headline, sales pitch opener). + +**Job-led lead message structure.** + +- "[Product/category] for [user trying to do job in situation], so [outcome]." +- "[Action verb describing the job] without [the friction users currently encounter]." +- "[Outcome the product produces] for [user in situation]." + +**Worked examples.** + +- "Help product teams synthesize discovery research into decisions, not deck performance." +- "Run quarterly business reviews without spending Sunday night reconciling spreadsheets." +- "Onboard new engineers without becoming their full-time guide." + +Each example names a job, an outcome, and either a contrast (without the friction) or a quality (the way the product accomplishes the job). + +--- + +## Functional, emotional, social in positioning + +Positioning leans on different dimensions of the job for different effects. + +**Functional dimension in positioning.** + +- "[Product] does [job]." Direct and informative; lower-affinity. +- Worked example: "Synthesize discovery research from interview transcripts and support tickets." + +Functional dimension positioning is useful for product details, not for lead messages. Lead messages on functional alone compete on feature comparison. + +**Emotional dimension in positioning.** + +- "[Product] lets you do [job] feeling [desired emotional state]." +- Worked example: "Run discovery cycles feeling in control, not buried in transcripts." + +Emotional dimension positioning creates affinity. Users recognize the emotional state they want and connect with positioning that names it. + +**Social dimension in positioning.** + +- "[Product] for [user identity]." +- Worked example: "For PMs who run discovery seriously." + +Social dimension positioning creates identity affinity. Users want to belong to the kind of users the positioning describes. This dimension is often the strongest for positioning because it is hardest to copy and creates the most durable affinity. + +**The composition.** Strong positioning often combines all three dimensions: a functional lead with emotional and social undertones. "Run discovery cycles for PMs who take synthesis seriously, without burying yourself in transcripts." Functional (run discovery cycles), social (PMs who take synthesis seriously), emotional contrast (without burying yourself in transcripts). + +--- + +## Avoiding job-positioning that misses + +Job-led positioning fails when the named job does not match the user's actual situation. + +**The pattern.** Marketing crafts a job-led message that sounds compelling but does not match how target users describe their work. Users do not recognize themselves; the positioning underperforms. + +**Worked failure example.** A productivity SaaS positions as "Eliminate the chaos in your day." + +The pattern. The job named (eliminating chaos) is too abstract; users describe specific frictions ("I cannot find the right meeting notes when I need them; I spend 20 minutes a day reconciling calendar conflicts; I miss commitments because tasks are scattered across tools"). The positioning is generic; users cannot recognize their specific situation. + +**The cure.** Ground positioning in specific job statements that emerged from user research. The positioning should sound like users describing their own work, not like marketing describing users. + +--- + +## Positioning testing for JTBD-led messages + +Job-led positioning benefits from user testing. + +**The test.** Show the positioning to target users. Ask: + +- "Does this describe your work?" +- "Would you keep reading this?" +- "What product would you expect to be behind this positioning?" + +**What good responses look like.** + +- "Yes, that's exactly what I do." (positive recognition) +- "I would want to see what this is." (interest signal) +- "It sounds like a [accurate product description]." (the positioning communicates accurately) + +**What bad responses look like.** + +- "I'm not sure this applies to me." (mismatch) +- "It sounds generic." (not specific enough to the job) +- "I expect this to be a [different product type]." (positioning misleads) + +**The iteration.** Positioning often improves through 2-3 rounds of testing and revision. The ground-truth from target users surfaces the gap between what marketing wrote and what users recognize. + +--- + +## Positioning across multiple jobs + +Many products serve multiple jobs. Positioning must decide whether to lead with one job or surface multiple. + +**Lead-with-one approach.** + +- Pick the most differentiating, most strategically important job. +- Lead with that job in the primary positioning. +- Surface other jobs in secondary positioning (feature pages, segment-specific pages). + +**Worked example.** A productivity SaaS that serves task management, team coordination, and reporting jobs: + +- Primary positioning leads with team coordination (the most strategic, most differentiating job). +- Feature pages address task management for users who land there. +- Reporting positioning lives on a dedicated page for evaluators looking specifically for that job. + +**Lead-with-many approach.** + +- The product genuinely serves several jobs equally; leading with one would mislead. +- Use a multi-job message: "[Product] for [job A], [job B], and [job C]." +- Risk: looks like a feature list dressed in job language. + +**The discipline.** Most products benefit from leading with one job and supplementing. Lead-with-many positioning often collapses into "do everything" messaging that creates no specific affinity. + +--- + +## Positioning for jobs vs positioning for users + +JTBD positioning leads with jobs; persona positioning leads with user identity. + +**Job-led positioning.** "Help product teams synthesize discovery research into decisions." + +**Persona-led positioning.** "For senior product managers at high-growth SaaS companies." + +The two can compose. Strong positioning often pairs job and identity: "Help senior PMs at high-growth SaaS companies synthesize discovery research into decisions." + +**The discipline.** Lead with the job (what the user is trying to do); add identity (who the user is) to create the affinity layer. Identity-only positioning is persona theater; job-only positioning may not create enough affinity. Job + identity is often the strongest form. + +--- + +## Common JTBD-positioning failures + +**Job-led messages that are too abstract.** "Eliminate the chaos in your day" is job-flavored but does not name a specific job. Replace with the specific job from research. + +**Feature-led messages dressed in job language.** "Use our analytics to make better decisions" is feature-led; "make better decisions" is too generic to be a job. + +**Job-led positioning that does not match user vocabulary.** Marketing wrote the positioning without grounding in user research; users do not recognize the language. + +**Lead-with-many positioning that becomes "do everything."** Multiple jobs surfaced equally; positioning loses specificity. + +**Positioning ignores the social dimension.** Strong positioning often leans on social dimension; positioning that omits it competes only on functional and emotional. + +**Positioning not user-tested.** Marketing crafts the positioning in isolation; target users have not validated that they recognize themselves in it. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led vs feature-led distinction. When job-led works and does not. The lead message structure. Functional, emotional, social in positioning. Avoiding job-positioning that misses. Positioning testing methodology. Positioning across multiple jobs. Job vs persona positioning. Common failures. + +## Implementation choices that stay internal + +Specific positioning frameworks the team uses. Specific copy templates. Specific A/B testing setups for positioning variants. Specific user-testing methodologies. The team's own conventions for primary vs secondary positioning. These vary by team and brand discipline. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md new file mode 100644 index 0000000..57c1a53 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md @@ -0,0 +1,206 @@ +# Applying JTBD to prioritization + +Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. The framing that cuts through feature-list politics. + +JTBD's contribution to prioritization is grounding the debate in user motivation rather than feature requests or stakeholder volume. Pairs with `roadmap-planning` for the broader prioritization discipline. + +--- + +## The job-led prioritization frame + +Each roadmap candidate gets evaluated by the jobs it addresses. + +**The questions.** + +- Which jobs is the product currently doing badly? +- Which roadmap candidates address those jobs vs adjacent or unrelated work? +- Which jobs matter most to the product's strategy and user base? +- What is the cost of addressing each candidate vs the value of the job improvement? + +**Why this frame works.** + +- It grounds prioritization in what users are trying to accomplish, not in what features they happen to have requested. +- It cuts through stakeholder politics: a roadmap candidate's value is measured against jobs, not against who is requesting it. +- It makes "we should not build this" defensible: candidates that do not address a load-bearing job get deprioritized clearly. + +**The compose-with-strategy discipline.** Job-led prioritization is downstream of strategy. The team needs to know which jobs matter for the product's market position; not all jobs are equally strategic. Pair with broader strategy work for the upstream framing. + +--- + +## Identifying jobs the product does badly + +The starting point for job-led prioritization. + +**The methodology.** + +- For each major job the product is meant to serve, evaluate how well it currently does the job. +- Use multiple inputs: user research (struggling moments, fire criteria), support data (where users hit friction), competitive analysis (where alternatives are stronger), in-product analytics (where users abandon). +- Score or rank jobs by how well they are currently served. Jobs done badly are candidates for prioritization investment. + +**Worked example.** A team productivity SaaS evaluating four core jobs: + +- Job A (creating tasks): well-served. Low priority for new investment. +- Job B (collaborating on tasks across teams): partially served. Some friction; alternatives are stronger; users describe workarounds. +- Job C (reporting on team progress): poorly served. High struggling-moment frequency; users export to spreadsheets; competitive products do this better. +- Job D (integrating with external tools): partially served. Friction at scale; mid-size customers describe pain. + +The badly-served jobs (B, C, D) are candidates for prioritization. Job A is not a fertile area for new investment. + +--- + +## Mapping roadmap candidates to jobs + +Each roadmap candidate gets associated with the jobs it addresses. + +**The mapping.** + +- Roadmap candidate: "Build cross-team task assignment with permissions." + - Job addressed: Job B (collaborating across teams). + - Job impact: addresses the core friction users describe; closes the gap with stronger alternatives. + +- Roadmap candidate: "Add custom report builder." + - Job addressed: Job C (reporting on team progress). + - Job impact: enables the reporting users currently export to spreadsheets to do. + +- Roadmap candidate: "Build mobile app for task creation." + - Job addressed: Job A (creating tasks) on mobile context. + - Job impact: extends a well-served job to a context where it currently is not served. Useful but not addressing a struggling job. + +- Roadmap candidate: "Redesign sidebar navigation." + - Job addressed: unclear. Possibly across multiple jobs. + - Job impact: hard to evaluate without clarification on which job this serves. + +**The fourth example signals a problem.** Roadmap candidates that do not clearly address a specific job often get prioritized on internal preferences rather than user value. The job mapping forces clarity: what job does this candidate serve, and how badly is that job currently being done? + +--- + +## The "no job, no priority" discipline + +Roadmap candidates that do not clearly address a job tied to user motivation often should not be prioritized. + +**The pattern.** + +- Candidate: "Migrate to a new internal framework." + - Job addressed: none directly; serves engineering velocity. + - Disposition: may be valuable for engineering reasons; do not prioritize on user-job grounds. If the team values engineering velocity, prioritize it on that basis explicitly. + +- Candidate: "Add dark mode." + - Job addressed: weak (some users describe preference). + - Disposition: low job-priority unless dark mode addresses an emotional dimension of jobs the team is also addressing. + +- Candidate: "Improve admin permissions." + - Job addressed: depends on which segment is asking. For enterprise: addresses fire criteria around compliance. For small teams: weak job impact. + - Disposition: prioritize for the segment whose job it serves; do not generalize. + +**The discipline.** Surface the job each candidate addresses (or does not). Candidates that do not serve jobs may still be valuable but should be prioritized on different grounds. The candidates the team can defend on jobs are the ones with the clearest user-value case. + +--- + +## Prioritization across jobs + +Different jobs have different strategic weights. The roadmap should reflect the strategy. + +**The questions.** + +- Which jobs are most load-bearing for the product's market position? +- Which jobs are most differentiated from competitors? (Where addressing the job better produces lasting advantage.) +- Which jobs serve the segments the strategy is targeting? +- Which jobs are growing in importance based on market trends? + +**Worked example.** A team productivity SaaS in mid-market growth: + +- Job B (cross-team collaboration): high strategic weight. Mid-market customers grow into multi-team workflows; the product needs to scale with them. +- Job C (reporting): high strategic weight. Mid-market customers need reporting that small-team customers did not require. +- Job D (integration): medium strategic weight. Important for retention; less differentiating than B and C. +- Job A (task creation): low strategic weight for new investment. Already served; not where competitors are winning. + +The strategic weighting biases the roadmap: B and C get more capacity than D; D gets more than A. + +--- + +## The "what job is this serving" review for in-flight work + +Job-led prioritization applies to existing work, not just new candidates. + +**The review.** + +- Take in-flight roadmap items. +- For each, ask: what job is this serving? How well does the work address that job? +- Items that cannot articulate a clear job may be candidates for re-scoping or cancellation. + +**The honest case.** Many roadmap programs accumulate work that started for reasons unrelated to user jobs (engineering preference, executive request, "we said we would"). The job review surfaces these and creates space to reconsider. + +**The kindness.** The review is not aimed at blame; sometimes work was committed before the team had the JTBD framing. The cure is reconsidering, not punishing. + +--- + +## Avoiding the JTBD-prioritization-religion failure + +JTBD as prioritization framework can become rigid in ways that hurt the team. + +**Patterns to avoid.** + +- Mandatory job-mapping for every roadmap item, including small bug fixes. The framework becomes overhead for low-value items. +- Treating job-impact estimates as precise numbers. Job-impact is often qualitative; pretending precision misleads. +- Over-weighting JTBD to the exclusion of other prioritization inputs. Strategic, technical, and operational considerations matter alongside jobs. + +**The discipline.** Use JTBD where it adds clarity to prioritization debates. Do not force the framework where it adds overhead without value. + +--- + +## Worked prioritization example + +A quarterly roadmap review at a team productivity SaaS. + +**Available capacity.** 5 large initiatives. + +**Candidates with job mapping.** + +1. Cross-team task assignment with permissions (Job B; high impact; high strategic weight). +2. Custom report builder (Job C; high impact; high strategic weight). +3. Mobile app for task creation (Job A on mobile; medium impact; low strategic weight). +4. Sidebar redesign (no clear job; serves general usability). +5. Slack integration upgrade (Job D; medium impact; medium strategic weight). +6. Onboarding redesign (multiple jobs; high impact on hire criteria for new customers). +7. Admin role overhaul (Job D for enterprise; high impact for that segment; matches enterprise expansion strategy). +8. Migration to new search backend (technical; serves multiple jobs indirectly). + +**Prioritization decision (5 of 8).** + +- Cross-team task assignment (1): yes. Top job priority. +- Custom report builder (2): yes. Top job priority. +- Onboarding redesign (6): yes. High hire-criteria impact. +- Admin role overhaul (7): yes. Enterprise strategy alignment. +- Migration to new search backend (8): yes. Technical foundation; serves multiple jobs. + +**Deferred.** + +- Mobile app for task creation (3): Job A is well-served on desktop; mobile is convenient but not high-priority. +- Sidebar redesign (4): no clear job. Reconsider for next cycle if a specific job emerges. +- Slack integration upgrade (5): Job D is medium-priority; can wait a quarter. + +**The defense.** The decisions can be explained on jobs and strategy. Stakeholders who pushed for items that did not make the cut can hear a clear rationale. The cut items can be reconsidered next quarter against jobs at that point. + +--- + +## Common JTBD-prioritization failures + +**Job-mapping all candidates without segmenting strategic weight.** Jobs treated as equal; the team picks based on impact estimates that obscure which jobs actually matter for strategy. + +**No job assigned to many candidates.** The team treats job mapping as optional; non-mapped candidates get prioritized on volume of requests or stakeholder preference. + +**Job-impact precision theater.** Numerical scores for job impact (Job B: 8/10) when the underlying assessment is qualitative. Decisions look quantitative but are not. + +**Forcing all decisions through JTBD.** Some decisions (technical migrations, strategic bets) do not benefit from JTBD framing. Force-fitting produces bad decisions. + +**JTBD as cover for predetermined prioritization.** The team ranks items by JTBD theater after deciding what to prioritize on other grounds. The framework becomes documentation rather than decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led prioritization frame. Identifying jobs done badly. Mapping candidates to jobs. The "no job, no priority" discipline. Strategic weighting across jobs. The in-flight work review. Avoiding JTBD-religion. Worked prioritization example. Common failures. + +## Implementation choices that stay internal + +Specific roadmap-tracking tools. Specific scoring rubrics for job impact. Specific stakeholder-review formats. Specific job-strategic-weight reviews. The team's own conventions for prioritization meetings. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md b/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md new file mode 100644 index 0000000..a36a25e --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md @@ -0,0 +1,166 @@ +# Common JTBD failures + +Nine-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most JTBD failures share a single root, which is treating JTBD vocabulary as a substitute for analytical work. + +--- + +## Failure 1: We did the JTBD workshop but nothing changed in our roadmap + +**Symptom.** A workshop was held. Job statements were produced. The wall has Post-its. The next quarter's roadmap looks the same as the prior quarter's. + +**Diagnosis.** Job-statement workshop as deliverable. The workshop became the artifact; the analytical work that should have followed never happened. + +**Cure.** Treat job statements as analytical input, not as workshop output. Re-evaluate roadmap candidates against the jobs. Apply the "no job, no priority" discipline. The roadmap should look different than it would have looked without the JTBD work; if it does not, the work is ritual. + +**Prevention.** Do not run JTBD workshops as standalone events. Pair the workshop with prioritization or positioning work that uses the job statements as input. Without downstream application, the workshop produces ritual. + +--- + +## Failure 2: Our job statements all sound the same + +**Symptom.** Multiple job statements share similar situations, motivations, or outcomes. They are hard to distinguish. + +**Diagnosis.** Generic job statements; not grounded in specific struggling moments. The statements were written from intuition rather than from interview data. + +**Cure.** Re-ground in interview data. Each job should be traceable to specific moments in specific interviews. Statements that cannot be traced are projections; rewrite from the ground up. + +**Prevention.** Job statements emerge from clustering, not from whiteboard sessions. The clustering work surfaces the distinctions; whiteboard sessions tend to produce homogeneous statements. + +--- + +## Failure 3: Our jobs read like feature requests + +**Symptom.** Job statements describe what users want from the product, not what users are trying to accomplish. + +**Examples that fail.** + +- "When using the dashboard, I want to see all my metrics on one screen." +- "When in the settings page, I want to configure permissions easily." + +The motivations and outcomes describe product features, not job-doing. + +**Diagnosis.** Product-bound job statements. The motivation is bound to the product; the outcome is feature output. + +**Cure.** Apply the product-independence test. The motivation should make sense without naming any specific product. If the user is "in the dashboard," they are using a product; the underlying job is what they are trying to accomplish that brought them to the dashboard. + +**Prevention.** During job-statement writing, check each statement: could this make sense if the user had no product to use? If no, rewrite the motivation and outcome to describe the underlying job. + +--- + +## Failure 4: We have personas and jobs and they contradict each other + +**Symptom.** The team has both demographic personas and JTBD job statements. Decisions get made differently depending on which framework the conversation invokes. + +**Diagnosis.** Personas are demographic; jobs are situational. They serve different purposes. Conflict often signals confusion about which framework drives which decisions. + +**Cure.** Decide the role of each framework. JTBD is usually better for product decisions (what to build, how to prioritize); demographic personas are sometimes useful for marketing audience targeting (who to advertise to). Use each where it adds clarity; do not require both for every decision. + +**Prevention.** When introducing JTBD, surface the relationship to existing personas. If personas are not driving decisions, consider deprecating them. If personas are useful for specific marketing work, keep them but separate from product decision-making. + +--- + +## Failure 5: JTBD says we should build everything + +**Symptom.** Job statements identify many job-improvement opportunities. The team cannot pick. The roadmap becomes a list of all the jobs to address. + +**Diagnosis.** Without prioritization across jobs, JTBD identifies opportunities but does not pick. The framework is doing its discovery work; it is not doing prioritization work. + +**Cure.** Pair JTBD with strategic weighting (which jobs matter most for the strategy?), capacity constraints (what can the team actually deliver?), and impact estimation (which job improvements move the needle most?). JTBD informs prioritization but does not replace prioritization frameworks. + +**Prevention.** When applying JTBD to roadmap prioritization, surface the strategic-weight question explicitly. Some jobs matter more than others; the team's strategy decides which ones. + +--- + +## Failure 6: We dropped JTBD because it became theater + +**Symptom.** The team adopted JTBD; produced workshop artifacts; never used them in decisions; and concluded JTBD does not work. + +**Diagnosis.** JTBD as ritual produced ritual. The framework was applied without the analytical work. + +**Cure.** Reintroduce JTBD as analytical tool, not as ritual. Apply where it earns its keep (discovery, prioritization, positioning). Skip the artifacts that decorate without informing decisions. Demonstrate the value through specific decisions JTBD informed. + +**Prevention.** When introducing JTBD, frame it as a tool for specific decisions, not as a methodology to be adopted org-wide. Start with one application (one discovery cycle, one prioritization debate) and show value before expanding. + +--- + +## Failure 7: Our job statements are functional only + +**Symptom.** Job statements describe mechanical tasks. The product strategy prioritizes functional features. The product wins on functional dimension and loses to alternatives on emotional and social. + +**Diagnosis.** Functional-only synthesis. The interview prompts and synthesis stayed at the functional dimension; emotional and social dimensions were not surfaced. + +**Cure.** Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing job statements. Re-evaluate strategy considering all three dimensions. + +**Prevention.** Interview structure should explicitly prompt for all three dimensions. Synthesis should surface all three. Single-dimension job statements are usually a sign that prompts or synthesis missed dimensions. + +--- + +## Failure 8: We cannot agree on the job + +**Symptom.** Different team members describe the user's job differently. The team debates the framing; the framing does not converge. + +**Diagnosis.** Often signals different segments with different jobs. The team is right that there is more than one job; they are wrong to think there should be one consensus job. + +**Cure.** Surface the segment differences. The same product may serve different jobs for different segments. Naming the segments and their distinct jobs resolves the disagreement and improves strategy. + +**Prevention.** When defining jobs, ask explicitly: do all target users share this job, or does it differ across segments? Often the answer is "differs"; surface the segments rather than forcing consensus. + +--- + +## Failure 9: Our marketing copy uses JTBD vocabulary but our product does not + +**Symptom.** Marketing positioning describes the job the product helps users accomplish. The product itself is built around feature-list thinking. Users adopt expecting one experience and encounter another. + +**Diagnosis.** Positioning-product gap. The marketing claim is not load-bearing in product decisions; product decisions are still made on feature-list grounds. + +**Cure.** Either align product decisions to the JTBD positioning (apply JTBD to prioritization), or revise the positioning to match what the product actually does. The mismatch erodes trust over time. + +**Prevention.** When introducing JTBD-led positioning, simultaneously apply JTBD to product strategy. Positioning that describes what the product is becoming should drive what the product becomes. + +--- + +## Failure 10: JTBD vocabulary substituted for analytical work + +**Symptom.** The team uses JTBD language ("the job," "struggling moment," "hire criteria") in conversations but cannot trace decisions to specific JTBD analyses. + +**Diagnosis.** Vocabulary without analysis is ritual. The framework provides language; the language does not produce decisions on its own. + +**Cure.** Audit recent decisions: which were grounded in JTBD analysis (specific job statements, specific hire/fire criteria, specific user research)? Which used JTBD vocabulary as decoration around decisions made on other grounds? Re-anchor in analytical work. + +**Prevention.** When the team uses JTBD vocabulary, surface the underlying analytical work explicitly. "What job is this serving?" should produce a specific job statement traceable to research, not a hand-wavy answer. + +--- + +## Failure 11: Force-fitting JTBD where it does not help + +**Symptom.** Every product question gets framed in JTBD. Even questions where the framing adds no clarity. + +**Diagnosis.** JTBD as mandate. The framework gets applied universally; tax for the team; signal-to-noise drops. + +**Cure.** Use JTBD where it earns its keep. Some questions (technical migrations, infrastructure decisions, urgent bug fixes) do not benefit from JTBD framing. Apply other frameworks where they fit better; apply JTBD where it fits. + +**Prevention.** Establish that JTBD is one tool among many. Frame the question first; then pick the framework. Do not start with the framework and look for questions to apply it to. + +--- + +## The cross-cutting pattern + +Most JTBD failures share a single root: treating JTBD vocabulary as a substitute for analytical work. + +The vocabulary is easy: "job," "struggling moment," "hire criteria," "fire criteria," "functional, emotional, social dimensions." Teams adopt the vocabulary and signal that they have adopted JTBD. + +The analytical work is hard: structured interviews, struggling-moment grounding, clustering across users, naming jobs from data, surfacing all three dimensions, applying the framework to specific decisions, validating that the analysis informs decisions. + +When the vocabulary is adopted without the analytical work, JTBD produces ritual. When the analytical work is done with discipline, JTBD produces decisions and the vocabulary is incidental. + +The fix for almost any JTBD failure starts with the same question: where is the analytical work happening, and what decisions is it informing? If the answers are clear, the framework is doing its job. If the answers are vague, the framework is ritual. + +--- + +## Methodology-level choices that stay in the public skill + +The eleven failure patterns with diagnoses and cures. The cross-cutting vocabulary-vs-analysis pattern. The discipline of using JTBD where it earns its keep. + +## Implementation choices that stay internal + +Specific JTBD-application audits. Specific reviewer training on failure detection. Specific tooling that surfaces JTBD ritual vs analytical use. The team's own conventions for catching ritual before it spreads. These vary by team. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md b/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md new file mode 100644 index 0000000..4460b0b --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md @@ -0,0 +1,201 @@ +# Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. The omission of emotional and social dimensions is one of the most common JTBD failure modes. + +--- + +## The three dimensions + +### Functional + +What the user is mechanically trying to accomplish. + +**Worked examples.** + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." +- "Prepare a customer-facing announcement for a feature launch." +- "Reconcile vendor payments at month-end." + +**Characteristics.** + +- Describable in task language. +- Often the easiest dimension to surface in interviews. +- Often the dimension product teams default to. + +--- + +### Emotional + +How the user feels (or wants to feel) doing the job. + +**Worked examples.** + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." +- "Comfortable that the announcement will not surprise anyone in a way that lands badly." +- "Confident that the reconciliation is correct without spending the whole week verifying." + +**Characteristics.** + +- Describes the user's internal experience. +- Often surfaces through how users describe what went well or badly. +- Distinguishes products that feel good to use from products that work mechanically but feel exhausting. + +--- + +### Social + +How the user wants to be perceived doing the job. + +**Worked examples.** + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." +- "Seen by customers as transparent and proactive, not evasive." +- "Seen by audit as someone whose work the team can trust without re-checking." + +**Characteristics.** + +- Describes how the user wants others to perceive their work. +- Often the most overlooked dimension. +- Drives positioning more than the other two dimensions. + +--- + +## Why three dimensions matter + +Products that win on functional alone often lose to alternatives that also serve emotional and social. + +**Worked example.** Two analytics tools serving the same functional job. + +- Tool A: technically thorough, full-featured, hard to learn, intimidating-feeling. Functional excellence; weak emotional dimension. +- Tool B: focused on the specific job, faster to confidence, feels manageable. Slightly less functional power; stronger emotional dimension. + +For users who could complete the job with either, Tool B often wins. The emotional dimension (feeling in control, confidence) tipped the decision even though Tool A's functional dimension was technically stronger. + +**Worked example, social dimension.** A board reporting tool serving CFOs. + +- Tool A: produces correct numbers; layout is utilitarian. +- Tool B: produces the same numbers; layout signals "this CFO knows their numbers" through design. + +The social dimension (how the CFO is perceived presenting from this tool) tips many decisions. Tool B is hired in part because it makes the CFO look good in front of the board. + +--- + +## Surfacing emotional and social dimensions in interviews + +Emotional and social dimensions often surface only when the interview prompts for them. + +**Functional prompts.** "Walk me through the task. What did you do?" + +**Emotional prompts.** "How did you feel doing this? What was the most stressful part? When did you feel relieved?" + +**Social prompts.** "Who else was watching this work? How did you want to come across to them? What did you do specifically because of how it would look?" + +**The interview discipline.** Surface all three dimensions; do not assume the functional dimension is the whole job. Many users will not volunteer emotional or social dimensions; the prompts surface them. + +--- + +## When functional alone is sufficient + +Some jobs are dominantly functional and the emotional/social dimensions are minor. + +**Worked example.** A backup utility that runs in the background. The functional dimension (data is backed up correctly) is the whole job; the user does not have an emotional relationship with the tool and is not perceived doing it. + +**The discipline.** Some products are appropriately functional-only. The team's job is to recognize when the dimensions matter and when they do not. Force-fitting emotional and social dimensions onto purely functional jobs produces false signal. + +--- + +## Functional-only failure mode + +The most common JTBD failure: surfacing only the functional dimension. + +**The pattern.** Job statements describe what the user is mechanically doing; the team prioritizes functional features; the product wins on functional excellence and loses on emotional and social. + +**The cure.** Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing jobs. Re-evaluate strategy considering all three dimensions. + +**The signal.** Products that are technically excellent but lose to "lesser" alternatives often have an emotional or social dimension the strategy missed. Investigate. + +--- + +## Emotional dimension and product feel + +The emotional dimension shows up in product feel: the way using the product makes users feel. + +**Examples of emotional dimensions in product design.** + +- A complex configuration interface vs a guided wizard. Both can be functionally equivalent; the wizard often serves the emotional dimension of "feeling in control rather than overwhelmed." +- An error message that explains and offers recovery vs one that just reports the failure. Both can be technically accurate; the explaining one serves the emotional dimension of "feeling supported rather than stuck." +- A success state that celebrates the milestone vs one that proceeds silently. Both can be functionally complete; the celebrating one serves the emotional dimension of "feeling progress rather than grinding." + +**The discipline.** Product designers often instinctively address emotional dimensions; the JTBD work makes this explicit and prioritizable. Emotional dimension can be a deliberate strategy choice rather than a designer's intuition. + +--- + +## Social dimension and positioning + +The social dimension informs positioning more than the other dimensions. + +**Examples of social dimensions in positioning.** + +- "Used by senior engineers at companies that ship reliable software." (positions the user as a senior engineer at a reliable company.) +- "The board reporting tool CFOs at high-growth startups trust." (positions the CFO as someone who works for a high-growth startup.) +- "Built for product teams that ship every week." (positions the product manager as part of a high-velocity team.) + +**Why social dimension is positioning-relevant.** + +- Users want to be perceived as belonging to the kind of teams the positioning describes. +- Positioning that names the social dimension creates affinity; positioning that names only functional features competes on feature comparison. +- The social dimension is durable; functional dimensions can be matched, social dimensions are harder to copy. + +**The discipline.** Positioning work should explicitly identify the social dimension of the jobs the product serves. Positioning that ignores social dimension misses one of the strongest tools available. + +--- + +## Worked synthesis combining all three dimensions + +A job statement enriched with all three dimensions: + +**Job:** "When my team is rolling out a new feature and I need to communicate it to customers, I want to write a clear announcement that explains what changed and why it matters, so I can ship the rollout without flooding support with confusion." + +**Functional dimension:** Write the announcement, distribute it to customers, prepare support for incoming questions. + +**Emotional dimension:** Confident that the announcement will land well, not anxious that it will trigger a wave of confused tickets, in control of the rollout rather than reactive to its fallout. + +**Social dimension:** Seen by the team as someone who handles rollouts smoothly, seen by customers as a brand that communicates clearly about changes, seen by support team as someone whose announcements reduce their workload rather than create it. + +**Product implications.** A tool that helps with this job needs to: + +- Functionally: support drafting, distribution, and support-team coordination. +- Emotionally: provide confidence-inducing review (preview tools, sentiment checks, changelog patterns). +- Socially: produce announcements that carry the brand voice the user wants associated with their rollouts. + +The three-dimensional analysis surfaces product needs the functional analysis alone would miss. + +--- + +## Common dimension-related failures + +**Functional-only synthesis.** Job statements describe mechanical tasks; strategy prioritizes functional features; product loses on feel. + +**Decorative emotional dimension.** Adding "feels good" without specifying which emotional state the product should support. The dimension exists on paper but does not drive design decisions. + +**Missing social dimension.** Strategy and positioning work that ignores how users want to be perceived. Positioning ends up generic; product fails to create affinity. + +**Force-fitting all three to every job.** Some jobs are functional-dominant. Adding emotional and social dimensions where they do not matter produces noise. + +**Treating dimensions as separate jobs.** Functional, emotional, and social dimensions are aspects of the same job, not separate jobs. Treating them separately produces fragmented strategy. + +--- + +## Methodology-level choices that stay in the public skill + +The three dimensions and their characteristics. Worked examples per dimension. Interview prompts per dimension. The functional-only failure mode. Emotional dimension and product feel. Social dimension and positioning. Worked three-dimensional synthesis. Common failures. + +## Implementation choices that stay internal + +Specific interview prompt templates per dimension. Specific synthesis templates that capture all three. Specific design-review patterns that check for emotional dimension. Specific positioning frameworks that lead with social dimension. These vary by team and design practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md b/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md new file mode 100644 index 0000000..d3aee67 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md @@ -0,0 +1,189 @@ +# Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground JTBD in real decisions users make. + +Hire and fire criteria are the JTBD methodology's most actionable contribution to product strategy. They surface what the product needs to be excellent at to win adoption (hire) and what the product needs to maintain to retain users (fire). The two are often different; products that win on hire criteria can lose on fire criteria. + +--- + +## Hire criteria + +What makes a user adopt a product. + +**The components.** + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +**Worked example.** A PM user adopting a new analytics tool: + +- Struggling moment: "I was spending hours every week assembling product metrics from three different sources before standup, and I was always uncertain whether I had the right slice." +- Alternatives considered: "Continued the manual spreadsheet approach. Tried to extend the existing BI tool. Considered building an internal dashboard." +- Why this product won: "It connected to all three sources out of the box, the slice I needed was a 30-second config, and the team could share the same view." +- Expected job output: "I would walk into standup with the metrics ready, with no manual reconciliation work the night before." + +**The discovery prompt.** "Tell me about the moment you decided to start using [product]. What were you doing before? What made you switch?" + +--- + +## Fire criteria + +What makes a user switch away. + +**The components.** + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +**Worked example.** A PM user switching away from an analytics tool: + +- Struggling moment: "Once we hit cross-source aggregations the basic config could not handle, I was back to manual workarounds." +- Alternative looking better: "A team I respect started using a different tool that handled cross-source natively." +- Tipping point: "When I had to rebuild a report three weeks in a row because the workaround broke whenever the source schemas changed." +- Failed job output: "The 30-second-config promise did not hold for the analyses that mattered most." + +**The discovery prompt.** "If you switched away from [product] tomorrow, what would the trigger be? What would the alternative need to do that [product] does not?" + +For users who have actually switched: "What was the moment you decided to switch away?" + +--- + +## Why hire and fire are often different + +Hire criteria reveal what the product needs to be excellent at to win adoption. Fire criteria reveal what the product needs to maintain to retain users. The asymmetry is consequential. + +**Examples of the asymmetry.** + +- A product that wins adoption with a fast onboarding (hire criterion) can lose users to depth limitations once they get past onboarding (fire criterion). The product needs both: fast onboarding AND depth that handles harder cases. +- A product that wins adoption with a single integration (hire criterion) can lose users when their tooling stack expands and the product does not keep up (fire criterion). The product needs both: a strong landing integration AND breadth as users grow. +- A product that wins adoption with a low price (hire criterion) can lose users when their budget expands and competitors offer more value at higher tiers (fire criterion). The product needs both: accessible entry AND value at higher tiers. + +**The implication.** Strategy work that focuses only on hire criteria builds for adoption. Strategy work that focuses only on fire criteria builds for retention. Mature strategy addresses both, often through different parts of the product or different lifecycle stages. + +--- + +## Recent-switch interview discipline + +Users who recently switched (in either direction) are particularly rich for JTBD interviews. + +**Why recent switches matter.** + +- The user remembers the specific moment of the switch decision; older switches get smoothed into abstractions. +- The user remembers the alternatives they considered, the criteria they used, the moment of tipping. +- The data is grounded in real decisions, not hypothetical preferences. + +**The recruiting target.** Users who switched in the last 30-90 days are the highest-value recruits for hire/fire interviews. Users who switched 6+ months ago provide weaker data. + +**The interview structure.** + +- Walk through the situation that prompted the switch consideration. +- Identify the alternatives evaluated. +- Surface the criteria the user used to evaluate. +- Identify the tipping moment. +- Compare expected vs realized outcomes after the switch. + +--- + +## Hire and fire across segments + +Different segments often have different hire and fire criteria. + +**Worked example.** A team productivity SaaS: + +- Small-team segment: hire criterion is "fast setup; works without admin"; fire criterion is "team grew and the product feels limiting." +- Mid-size segment: hire criterion is "supports our existing roles and permissions"; fire criterion is "missing reporting and audit features as we standardize." +- Enterprise segment: hire criterion is "compliance and security pass our review"; fire criterion is "vendor responsiveness during incidents." + +**The discipline.** Surface segment differences in hire and fire criteria explicitly. A product that wins on small-team hire criteria but loses on mid-size fire criteria has a known retention pattern that strategy must address. + +--- + +## The "why didn't you switch sooner" question + +A specific prompt that reveals the friction barrier to switching. + +**The prompt.** "Looking back, why didn't you switch sooner?" + +**What it surfaces.** + +- The switching cost the user had to overcome (data migration, team retraining, contract obligations). +- The alternatives that almost won earlier but did not (and why). +- The accumulated frustration that finally broke through the inertia. + +**Why it matters.** + +- High switching costs protect incumbents. Users tolerate friction longer when switching is expensive. +- The pattern of frustration accumulation reveals which fire criteria are load-bearing (the ones users finally cannot tolerate). +- The almost-won alternatives reveal what would have been compelling enough earlier. + +--- + +## Hire and fire criteria for non-switching users + +Not every user has switched. Some users are at the start of their relationship with the product; others have used it for years without considering alternatives. + +**For new users:** focus on hire criteria. The recent decision is the adoption decision; the fire criteria are hypothetical. + +**For long-tenured users:** focus on fire criteria. The hypothetical "what would make you switch" reveals the latent fire criteria even without a switch event. The product can use these to address fire risks before they become switch events. + +**For users who tried and abandoned:** rich data. They evaluated, found the product wanting, and stuck with the prior alternative. The reasons reveal both hire criteria the product failed and fire criteria for the alternative they kept. + +--- + +## Patterns across hire criteria + +Common patterns in hire criteria across product domains. + +**Speed-to-value.** Users hire products that get them to first value quickly. Long onboarding loses adoption races; fast onboarding wins. + +**Specific job fit.** Users hire products that look like they will solve the specific job. Generic products that "could be used for many things" lose to specific products that "solve this exact problem." + +**Confidence in continuity.** Users hire products they trust will be there in 2 years. Established products win on this; startups have to compensate with other criteria. + +**Workflow continuity.** Users hire products that fit their existing workflows. Products that demand workflow change face higher hire bars. + +**Recommendation chain.** Users hire products that someone they trust recommended. Word-of-mouth is often a stronger hire criterion than feature comparison. + +--- + +## Patterns across fire criteria + +Common patterns in fire criteria across product domains. + +**Reliability degradation.** Users fire products that become unreliable. A product that ships bugs faster than it ships fixes loses users. + +**Scaling friction.** Users fire products that get harder to use as they grow. The product that was great for 5 users may be painful at 50. + +**Vendor responsiveness.** Users fire products whose vendors stop responding. Support quality, account management, and incident response all matter. + +**Pricing trajectory.** Users fire products whose pricing escalates faster than the value they get. Enterprise tiers that gate basic functionality drive fire decisions. + +**Competitive pressure.** Users fire products when alternatives reach feature parity plus advantage. Products that stop innovating lose to products that overtake them. + +--- + +## Common hire-and-fire failures + +**Asking only about hire.** The team interviews about adoption decisions but never about switch decisions. The strategy biases toward adoption; retention concerns surface late. + +**Asking only about fire.** The team focuses on churn analysis without understanding hire criteria. New customer acquisition struggles because the team does not know what wins adoption. + +**Treating hire and fire as the same.** The team assumes the criteria match. Strategy ends up optimized for hire-with-no-fire-attention or vice versa. + +**Hypothetical-only fire data.** Long-tenured users describing what they "would" switch over. Useful but weaker than real-switch data. + +**Ignoring segment differences.** Hire and fire criteria collapsed across segments. Strategy that works for one segment fails for another. + +--- + +## Methodology-level choices that stay in the public skill + +The hire and fire criteria components. Why they are often different. The recent-switch interview discipline. Hire and fire across segments. The "why didn't you switch sooner" question. Hire and fire for non-switching users. Patterns across hire and fire criteria. Common failures. + +## Implementation choices that stay internal + +Specific interview templates for hire and fire interviews. Specific recruitment criteria for recent switchers. Specific synthesis tooling for hire and fire data. The team's own conventions for hire-fire balance in strategy work. These vary by team and research practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md b/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md new file mode 100644 index 0000000..a7e8590 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md @@ -0,0 +1,176 @@ +# Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when alternatives feel inadequate, when they would prefer a different way of doing the job. + +The struggling moment is the JTBD methodology's most direct contribution to discovery research. Most discovery interviews surface preferences and feature requests; well-structured JTBD interviews surface struggling moments, which produce richer data and clearer jobs. + +--- + +## What a struggling moment is + +A specific moment in time when: + +- The user encountered friction in trying to accomplish something. +- The current approach failed them or felt inadequate. +- They considered or wished for an alternative. +- They built a workaround or accepted suboptimal output. + +**Strong struggling-moment examples.** + +- "Last Tuesday I lost an hour assembling the board metrics from three different dashboards because none of them had the slice I needed. I ended up exporting CSVs and combining them manually, and then second-guessing whether I had pulled the right data." +- "When the customer escalation came in at 9pm, I was at dinner and tried to triage from my phone, but the support tool's mobile experience was unusable. I had to go back to my laptop and the whole evening was disrupted." +- "Last quarter I spent the whole onboarding week pair-programming with the new engineer because our docs assumed knowledge they did not have, and I could not point them anywhere that would work without me there." + +Each example names a specific time, a specific friction, and the workaround or impact. + +**Weak struggling-moment examples.** + +- "I wish dashboards were better." (general; not a moment) +- "It would be nice if the support tool was more mobile-friendly." (preference; not a friction-in-context) +- "Onboarding new engineers takes a lot of time." (abstracted; no specific moment) + +--- + +## Discovery prompts that surface struggling moments + +Specific prompts produce specific data. + +**Prompts that work.** + +- "Walk me through the last time you did [task]. What was hardest about it?" +- "What was the most recent time you wished you had a better way of doing [task]?" +- "When was the last time [task] went badly? What happened?" +- "Describe the last time you considered switching from [current tool] to something else. What triggered that?" +- "What's something you do that takes longer than it should? When was the last time it cost you?" + +The prompts share two characteristics: they ground in recent specific moments, and they invite the user to describe friction without pre-judging it. + +**Prompts that fail.** + +- "What features would you like to see?" (produces feature requests, not jobs) +- "How do you usually do [task]?" (produces abstracted descriptions, not moments) +- "Are you satisfied with [tool]?" (produces preferences, not behaviors) +- "What would your dream solution look like?" (produces fiction, not data) + +--- + +## The recency bias as a feature + +JTBD interviewing exploits recency. Recent moments are remembered with specifics; older moments get smoothed into abstractions. + +**The methodology.** Ask about the last time, the most recent occurrence, the situation that happened this week. Users can recall details from recent moments that they cannot recall from older ones. The details are where the job lives. + +**The trade-off.** Recent moments may not represent the dominant pattern; the most recent occurrence may be an outlier. The mitigation is interview volume: 8-15 interviews each grounded in recent moments produce a pattern; one interview grounded in one moment is one data point. + +--- + +## Pattern recognition across users + +Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well. + +**The clustering work.** + +- Across interviews, struggling moments get tagged with what the user was trying to accomplish, what failed, what alternative they wished for. +- Tags cluster: multiple users describe the same kind of friction in similar contexts. +- Each cluster suggests a job: the underlying thing users were trying to do that the cluster's friction was blocking. + +**Worked example.** Across 12 interviews with PM users: + +- Multiple users describe assembling data from multiple dashboards before quarterly business reviews. +- Multiple describe building Excel exports because their dashboard tool does not produce the right slice. +- Multiple describe second-guessing whether the data they assembled is correct. +- Multiple describe the time pressure and disruption these workarounds create. + +The cluster suggests a job: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The job emerges from the moments; the moments came from the prompts. + +--- + +## Distinguishing struggling moments from venting + +Not every friction users describe is a struggling moment for product purposes. + +**Struggling moments.** + +- Specific friction that interferes with the user accomplishing something they care about. +- The friction is reproducible (other users encounter similar friction in similar contexts). +- The friction has a workaround or alternative the user has tried. + +**Venting that is not a struggling moment.** + +- General complaint without specific friction context ("everything is too slow"). +- Preference for cosmetic differences ("I do not like the color"). +- One-off issues with no pattern across users. + +**The discipline.** Tag specific friction; do not over-weight venting. The struggling moments that drive product decisions are the ones with reproducible context across users. + +--- + +## The "what would you have done differently" question + +A specific prompt that surfaces both struggling moments and the implicit alternative. + +**The prompt.** "If you could have done [task] any way you wanted, how would you have done it?" + +**What it surfaces.** + +- The user's mental model of the ideal approach. +- The gap between current tools and the user's mental model. +- Sometimes the alternative tools the user has used or considered. + +**What it does not surface.** + +- Always-correct product solutions. Users often describe alternatives that would not actually work; the value is in understanding their mental model, not adopting their proposed solution. + +**The interpretation.** The user's described "would have done differently" is informative about the gap, not prescriptive about the fix. Synthesis interprets the gap and proposes product responses; users do not directly produce the responses. + +--- + +## When users do not have struggling moments + +Sometimes the interview reveals that the user is not struggling with the area the team is researching. They have a workable approach; they would not change it; the friction the team thought existed does not exist for this user. + +**The honest interpretation.** The team's hypothesis about a job that needs better tooling may be wrong, or this user may not be in the target segment for the job, or the job may be done well enough by existing solutions that there is no struggle. + +**The discipline.** Surface this finding rather than discounting it. "Some users are not struggling here" is data; ignoring it because it does not match the team's hypothesis is confirmation bias. + +--- + +## Struggling moments by product type + +Different product domains surface different kinds of struggling moments. + +**Tools that fit into existing workflows.** Struggling moments are workflow disruptions: the moment the existing tool failed and the user had to switch to a workaround. + +**Tools that change workflows.** Struggling moments are transition points: the moment the user realized the old workflow was unsustainable and considered changing it. + +**Consumer products.** Struggling moments are often emotional: the moment the user felt frustrated, blocked, or in conflict with their own goals. + +**B2B platforms.** Struggling moments often involve coordination: the moment the user could not align with a colleague, customer, or vendor because the tooling did not support the coordination. + +The discipline. Tailor interview prompts to the kind of struggling moment most likely in the product domain; do not assume one prompt works for all domains. + +--- + +## Common struggling-moment failures + +**Eliciting preferences instead of moments.** "What features do you wish existed?" produces preferences. Reframe: "What's the last task that took longer than it should have?" + +**Abstracting moments to patterns prematurely.** Users describing "what I usually do" instead of specific recent moments. Bring them back to the last specific time. + +**Ignoring countervailing data.** Users who do not struggle in the researched area. Their data is signal; do not discard it. + +**Treating venting as struggling moments.** General complaint without specific context does not produce jobs. + +**Over-relying on the "wish" question.** Users describe ideal alternatives that do not necessarily reflect what would work; treat as gap-revealing data, not as product specs. + +--- + +## Methodology-level choices that stay in the public skill + +What a struggling moment is and is not. Discovery prompts that work and fail. The recency bias as a feature. Pattern recognition across users. Distinguishing struggling moments from venting. The "what would you have done differently" question. When users do not struggle. Domain-specific struggling moment patterns. Common failures. + +## Implementation choices that stay internal + +Specific interview templates and discussion guides. Specific recording and tagging conventions. Specific recruitment criteria for who the team interviews. The team's own conventions for interview length and structure. These vary by team and research practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md b/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md new file mode 100644 index 0000000..663b49a --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md @@ -0,0 +1,198 @@ +# Job statement structure patterns + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." Each level demands specificity. Vague levels produce job statements that drive nothing. + +--- + +## The three levels + +### Situation + +The context, trigger, or moment when the job becomes active. + +**Strong situation patterns.** + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck the night before the meeting..." +- "When I get a customer escalation outside of business hours..." +- "When a new engineer joins my team mid-quarter..." + +**Weak situation patterns.** + +- "When I am at work..." (too broad) +- "As a marketing manager..." (demographic, not situational) +- "Whenever I need to communicate..." (lacks the specific trigger) + +**Why specificity matters.** Situations name the moment when the job activates. Different situations can produce different jobs even for the same user; collapsing situations together loses the patterns. + +--- + +### Motivation + +What the user is trying to do in that situation. + +**Strong motivation patterns.** + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage the escalation and respond without disrupting my evening too much..." +- "...I want to onboard the new engineer to our codebase without becoming their full-time guide..." + +**Weak motivation patterns.** + +- "...I want to do my job better..." (too vague) +- "...I want to use feature X..." (motivation is a feature, not a goal) +- "...I want to be more productive..." (universal; not actionable) + +**Why specificity matters.** Motivations name what the user is trying to accomplish in their own words. The motivation should describe the job the user is doing, not the product the user is using. "I want to use Slack to communicate" is not a motivation; "I want to coordinate with the team on the rollout" is. + +**The product-independence test.** A good motivation should make sense without naming any specific product. If the motivation is bound to the product, it has slid into feature framing. + +--- + +### Outcome + +What success looks like; what the user is trying to achieve by doing the job. + +**Strong outcome patterns.** + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." +- "...so the new engineer can ship their first PR within two weeks without depending on me for every question." + +**Weak outcome patterns.** + +- "...so I can succeed." (too vague) +- "...so I can use the feature." (outcome is feature use, not user goal) +- "...so I can be efficient." (universal; not specific) + +**Why specificity matters.** Outcomes name what success looks like in the user's terms. Different outcomes for the same situation+motivation can produce different jobs. The outcome anchors the job in the user's success criteria, not the product's metrics. + +--- + +## Worked examples across product domains + +### B2B SaaS for engineering teams + +- "When a production incident is detected and I am the on-call engineer, I want to identify the root cause and roll back if needed, so I can restore service before the SLO breach without escalating unnecessarily." + +### Consumer fitness app + +- "When I have 30 minutes between meetings and I want to use the time well, I want to do a workout that fits the time budget and uses the equipment I have at hand, so I can stay consistent without skipping when life gets busy." + +### Internal tools for finance teams + +- "When the month-end close is starting and I need to reconcile vendor payments, I want to identify discrepancies and document explanations, so the auditors can review without follow-up questions." + +### Creator-tools SaaS + +- "When I am editing a podcast episode the day before publication, I want to remove background noise and balance audio levels across speakers, so the episode sounds professional without spending another two hours on mastering." + +Each example specifies the moment, what the user is trying to do, and what success looks like. Each is product-independent at the motivation level: the user is trying to accomplish the job regardless of which tool they use. + +--- + +## Common structural failures + +### Vague situations + +**Failure.** "When I am at work..." + +**Diagnosis.** The situation does not name the trigger that activates the job. Most users are at work most of the time; the situation should name the specific moment. + +**Cure.** Re-ground in interview data. What was the user actually doing when this job became urgent? Use that moment. + +--- + +### Motivation as feature request + +**Failure.** "...I want to use the dashboard..." + +**Diagnosis.** Motivation is a feature, not a goal. The user does not want to use the dashboard; they want to accomplish something the dashboard supports. + +**Cure.** Ask the why-question. Why does the user want to use the dashboard? What are they trying to learn from it? The answer is the motivation. + +--- + +### Outcome as feature output + +**Failure.** "...so I can see the metrics." + +**Diagnosis.** Outcome is feature output, not user success. Seeing the metrics is intermediate; the user wants something the metrics enable. + +**Cure.** Ask another why. Why does the user want to see the metrics? What does seeing the metrics enable? The answer is the outcome. + +--- + +### Demographic as situation + +**Failure.** "As a marketing manager..." + +**Diagnosis.** Demographic, not situational. Different marketing managers in different moments have different jobs. + +**Cure.** Replace with the specific moment. "When the marketing manager is preparing the quarterly campaign retrospective..." + +--- + +### Universal as motivation or outcome + +**Failure.** "...I want to be more productive, so I can be efficient." + +**Diagnosis.** Universal language; could apply to any user, any job. Says nothing. + +**Cure.** Specificity at both motivation and outcome. What kind of productivity? What does productivity enable? The specifics are the job. + +--- + +## Multiple jobs per situation + +A single situation can produce multiple jobs. Different motivations or outcomes within the same situation are different jobs. + +**Worked example.** + +Situation: "When I am preparing the quarterly board deck..." + +Job A: "...I want to assemble revenue and engagement data into a coherent narrative, so I can answer the board's likely questions before they ask them." + +Job B: "...I want to flag the risks I want the board to engage with, so I can get their input on the calls I cannot make alone." + +Both jobs share the situation but have different motivations and outcomes. They may need different product responses. + +The discipline. Do not collapse multiple jobs into one because they share a situation. The motivation and outcome distinguish them. + +--- + +## Job statements vs alternatives in JTBD literature + +The "When... I want to... so I can..." format is the most widely used job statement structure. Other formats exist (outcome statements in outcome-driven innovation, struggle statements in switch interviews). They each name the same fundamental thing: the user's situation, motivation, and success criteria. + +This skill uses the When/I-want-to/So-I-can structure because it is the most teachable and the most consistently understood. Teams familiar with other JTBD lineages can translate; the underlying principles are the same. + +**The structure-vs-substance discipline.** The structure is a scaffold for analytical work. Job statements written in the right structure but without grounding in interview data are still ritual. Job statements written in slightly different structures but grounded in interview data and driving decisions are still jobs. + +--- + +## The job statement editing pass + +Strong JTBD work runs an editing pass focused on job-statement quality. + +**Per job statement, the editing questions.** + +1. Is the situation specific (a moment, not a demographic)? +2. Is the motivation product-independent and goal-directed? +3. Is the outcome the user's success criterion, not a feature output? +4. Is the statement specific enough that another team could distinguish it from related jobs? +5. Could the team use this job statement to evaluate a product decision? + +**The editing investment.** 1-2 hours per round of revisions on a typical job-statement set. The investment pays off in clarity for downstream applications (discovery, prioritization, positioning). + +--- + +## Methodology-level choices that stay in the public skill + +The three-level structure (situation, motivation, outcome). Strong vs weak patterns at each level. The product-independence test for motivation. Common structural failures and their cures. Multiple-jobs-per-situation discipline. The structure-vs-substance principle. The editing pass. + +## Implementation choices that stay internal + +Specific job-statement templates in the team's writing system. Specific document conventions for job-statement libraries. Specific A/B testing of statement variants in interview prompts. The team's own conventions for how many job statements per discovery cycle. These vary by team. diff --git a/dist/pi/.agents/skills/landing-page-copy/SKILL.md b/dist/pi/.agents/skills/landing-page-copy/SKILL.md new file mode 100644 index 0000000..cb3defd --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/SKILL.md @@ -0,0 +1,260 @@ +--- +name: landing-page-copy +description: "Write landing page copy with attention to the hero, value proposition, social proof, objection handling, and conversion-focused CTAs. Use this skill whenever the user wants to write a landing page, sales page, hero section, or any conversion-focused web copy. Triggers on landing page, sales page, hero copy, value proposition, headline, subheadline, hero section, CTA copy, conversion copy, opt-in page, squeeze page. Also triggers when the user has a marketing campaign or product launch needing dedicated conversion copy." +category: content +catalog_summary: "Landing pages, sales pages, hero-to-CTA flow" +display_order: 4 +--- + +# Landing Page Copy + +Write copy for pages with a single conversion goal: signup, purchase, demo request, download, lead capture. Stack-agnostic. + +This skill is narrower than `content-and-copy`. Landing pages exist to drive a specific action, not to inform broadly. + +--- + +## When to use + +- Writing a hero section for a homepage or product page +- Writing a sales page or long-form sales letter +- Drafting opt-in or lead-capture page copy +- Campaign-specific landing pages +- Pricing page copy +- Demo or signup CTAs + +## When NOT to use + +- Long-form blog content (use `content-and-copy`) +- Email sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- Page design and layout decisions (use `design-standards`) + +--- + +## Required inputs + +- The product, service, or offer +- The target audience and the specific objection they bring +- The conversion goal (one specific action) +- Brand voice +- Existing customer language (testimonials, support tickets, sales calls) +- Any constraints (length, format, regulatory) + +If audience is unclear or objections are unknown, run `brand-discovery` or pull from sales call recordings before writing. + +--- + +## The framework: 7 sections + +A landing page does seven things in sequence. The structure can flex (combine, reorder, expand), but the elements stay constant. + +### 1. Hero + +The first 3 to 5 seconds. Decides whether the visitor stays. + +**Three components:** + +- **Headline.** The promise. Specific, outcome-focused, free of cliche. +- **Subheadline.** The mechanism. How you deliver the promise. +- **Primary CTA.** The action. One button, descriptive label. + +**Strong hero patterns:** + +- **Outcome + audience + mechanism.** "Ship features 3x faster, for engineering teams who hate meetings, with our async-first project tool." +- **Pain reversal.** "Stop losing customers to slow page loads." +- **Surprising claim.** "The note-taking app that gets used. We have data." +- **Direct address.** "You have 47 unread Slack messages. Here's what to do about it." + +**Weak hero patterns:** + +- Generic adjective stacking ("Powerful, intuitive, scalable") +- "Welcome to our platform" +- Brand-name-only headlines ("Acme: The Future of X") +- Vague benefits ("Streamline your workflow") + +### 2. Social proof (early) + +Within the first scroll, prove someone else trusts you. + +**Forms:** +- Customer logos (recognizable beats unknown) +- Quantitative trust signal ("Over 10,000 teams") +- One strong testimonial with name and role +- Press mentions (logos of where you've been featured) + +**Placement:** Right below the hero, before the visitor invests in reading more. + +### 3. Problem / promise + +Establish that you understand the visitor's situation. + +**Pattern:** +- 1 to 3 paragraphs naming the specific problem +- Use the visitor's language (mined from research, not your marketing language) +- Stop before you sell. Resonate first. + +**Test:** Read the problem section aloud. Does the target audience nod? If they don't, you don't understand them yet. + +### 4. Solution / mechanism + +How you solve the problem. The "what we actually do" section. + +**Effective structure:** +- One headline summarizing the solution +- 3 to 5 specific features or capabilities, each with a 1-2 sentence explanation +- Each feature framed as the benefit it produces, not the technical detail +- Visual support (screenshots, illustrations, video clips) + +**Failure mode:** Listing features without translating to outcomes. "Real-time collaboration" is a feature. "Edit together without copying-pasting from email" is the outcome. + +### 5. Proof and detail + +The expanded social proof and case studies section. + +**Components:** +- 1 to 3 detailed case studies (specific customer, specific outcome, specific numbers) +- Multiple testimonials with attribution +- Specific data points (usage stats, success metrics, growth) +- Awards, certifications, or third-party validation + +The deeper proof section is where committed visitors convert. Skim-readers won't make it here, but the ones who do are ready to buy. + +### 6. Objection handling + +Anticipate the reasons people say no. Address them directly. + +**Common objection types:** +- **Price.** "Is this worth it?" +- **Time.** "Will this take forever to set up?" +- **Trust.** "Will this actually work for my situation?" +- **Risk.** "What if I commit and it's wrong?" +- **Comparison.** "How is this different from [competitor]?" +- **Implementation.** "Can my team handle the change?" + +**Handling formats:** +- **FAQ section.** Structured, scannable. +- **Comparison table.** Vs. competitors or vs. alternatives. +- **Risk reversal.** Money-back guarantee, free trial, no-contract terms. +- **Proof of effort needed.** "Setup takes 5 minutes, not 5 weeks." + +### 7. Final CTA + +The closer. Re-state the offer. Re-state the action. + +**Strong final CTAs:** +- Repeat the primary CTA from the hero (consistency) +- Frame in terms of the visitor's situation ("Get your team set up in 5 minutes") +- Remove friction ("No credit card required") +- One action only (avoid offering 5 alternatives that paralyze decision) + +**Avoid:** +- Multiple CTAs competing for attention at the bottom +- New offers introduced only at the bottom (visitor is now confused) +- Long forms that ask for more information than needed for the action + +--- + +## The CTA itself + +Buttons matter. Treat the button copy as a whole-page-worth of attention. + +**Strong CTA patterns:** + +- **Action + outcome.** "Start your free trial," "Get my pricing," "Send me the guide" +- **First-person.** "Show me how" outperforms "Show you how" +- **Specific.** "Book a 15-minute demo" beats "Contact us" +- **Low-friction.** "Free trial, no credit card" reduces commitment cost + +**Weak CTAs:** +- "Submit" (functional but lifeless) +- "Click here" (no value statement) +- "Learn more" (vague; about what?) +- "Get started" (started doing what?) + +--- + +## Workflow + +1. **Confirm the offer.** What exactly is being offered? At what price (if any)? What does the visitor get? +2. **Confirm the audience and objection.** Specific segment. The specific worry they bring. +3. **Mine the language.** Customer testimonials, support tickets, sales calls. Use real customer phrases. +4. **Draft the hero.** Headline, subheadline, CTA. Test 5 to 10 variations. +5. **Build the structure.** All 7 sections in order. Sections can combine for shorter pages. +6. **Draft sections.** Section by section. Don't polish until the structure is sound. +7. **Edit for friction.** Remove every word that doesn't earn its place. Landing pages do not have words to spare. +8. **Test the CTA.** Read the page aloud. By the end, is the visitor's next action obvious? +9. **Pre-publish:** check links, spell-check, mobile preview, SEO basics if SEO is a goal. + +--- + +## Failure patterns + +- **Hero that explains instead of sells.** "We're an X for Y" is description. "Get X without Y" is sell. +- **Feature lists with no outcomes.** Features without benefits read as a spec sheet. +- **Generic testimonials.** "Great product!" is worth less than nothing. "We cut onboarding time from 2 weeks to 4 days" is gold. +- **Multiple competing CTAs.** Pick one primary action. Everything else is noise. +- **Walls of text.** Visitors scan. Use short paragraphs, bullet lists, and visual breakpoints. +- **No social proof.** Trust is the first hurdle. Without proof, the rest of the page does not earn the chance to be read. +- **Mismatched headline and CTA.** Hero promises X, CTA asks for Y. Visitor confused. +- **Writing for everyone.** "Our solution works for any business" appeals to no one. Specificity converts. +- **Ignoring mobile.** Most visitors are on mobile. Test the page at 375px first. + +--- + +## Output format + +Default output is a structured markdown document for the page, with each section labeled. The markdown is ready to import into the CMS or hand to design. + +Structure: + +```markdown +# [Page Title] + +## SECTION: Hero +- Headline: [text] +- Subheadline: [text] +- Primary CTA: [button text] +- Supporting cue: [optional, e.g., "No credit card required"] +- Hero visual notes: [if any] + +## SECTION: Social proof (early) +- Logo bar: [list customer/press logos] +- Trust statistic: [if any] + +## SECTION: Problem / promise +[2 to 3 paragraphs] + +## SECTION: Solution +- Headline: [text] +- Feature 1: [headline + description] +- Feature 2: [headline + description] +- Feature 3: [headline + description] + +## SECTION: Proof +- Case study 1: [customer, outcome, numbers] +- Testimonials: [list] +- Data points: [list] + +## SECTION: Objection handling +- FAQ: [questions and answers] +- OR Comparison table: [vs alternatives] +- OR Risk reversal: [guarantee, terms] + +## SECTION: Final CTA +- Headline: [text] +- Final CTA button: [text] +- Supporting cue: [optional] + +## Variants for testing +- [Alternate headlines] +- [Alternate CTAs] +- [Alternate proof framings] +``` + +--- + +## Reference files + +- [`references/hero-formulas.md`](references/hero-formulas.md) - Patterns and formulas for hero headlines. +- [`references/objection-library.md`](references/objection-library.md) - Common objections by category, with handling strategies. diff --git a/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md b/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md new file mode 100644 index 0000000..d14a980 --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md @@ -0,0 +1,230 @@ +# Hero Headline Formulas + +The hero headline is the most-read line on the page. It earns the rest of the read or it doesn't. + +These are not magic templates. They are starting points. Apply them, then make them sound like the brand. + +--- + +## Formula 1: Outcome + audience + mechanism + +**Pattern:** [Specific outcome] for [specific audience] with [specific mechanism] + +**Examples:** +- "Ship features 3x faster, for engineering teams who hate meetings, with async-first project management." +- "Cut payroll processing from days to minutes, for finance teams of 50+, with one connected system." +- "Build a remote team that doesn't burn out, for founders scaling past 20 people, with rituals that actually work." + +**Strengths:** Highly specific. Hard to confuse with a competitor. + +**Weaknesses:** Can become long and clunky. Not always elegant. + +**When to use:** Product is in a crowded category and needs to differentiate quickly. + +--- + +## Formula 2: Pain reversal + +**Pattern:** Stop [specific pain]. Start [specific outcome]. + +**Examples:** +- "Stop losing customers to slow checkout. Start converting at industry-leading speeds." +- "Stop digging through Slack threads. Start finding answers in seconds." +- "Stop guessing what your users want. Start knowing." + +**Strengths:** Direct. Names the visitor's current frustration. + +**Weaknesses:** Depends on the pain being widely felt. If the pain isn't recognized, the headline doesn't connect. + +**When to use:** The audience is actively frustrated by something specific. + +--- + +## Formula 3: Surprising claim + +**Pattern:** A specific claim that contradicts what the audience expects. + +**Examples:** +- "The note-taking app most people actually use." +- "Email outreach that doesn't feel like spam." +- "The CRM that sales reps don't try to escape from." + +**Strengths:** Pattern-breaks. Creates curiosity. + +**Weaknesses:** Must be defensible. A surprising claim with no proof feels like marketing puffery. + +**When to use:** You can back up the claim with evidence in the page below. + +--- + +## Formula 4: Direct address + +**Pattern:** Speak to a specific situation the visitor is in right now. + +**Examples:** +- "You have 47 unread Slack messages. Here's what to do." +- "Your team just lost three candidates this month. Here's why." +- "Your app crashed at 3 AM. We watched your monitoring system miss it." + +**Strengths:** Visitor recognizes themselves immediately. + +**Weaknesses:** Risk of feeling presumptuous if the situation is wrong. + +**When to use:** The audience is highly specific and the scenario is universal among them. + +--- + +## Formula 5: Question they're already asking + +**Pattern:** Pose the question the visitor came to find an answer to. + +**Examples:** +- "How much should you actually spend on Google Ads?" +- "Should you build it or buy it? Here's the framework." +- "Why does your team's productivity drop after lunch?" + +**Strengths:** Aligns with search intent. Strong for SEO landing pages. + +**Weaknesses:** Less common in product hero copy. Better for content-driven landing pages. + +**When to use:** The page answers a specific question the visitor brought. + +--- + +## Formula 6: Comparison (us vs. them) + +**Pattern:** [Our category] without the [familiar pain of the category]. + +**Examples:** +- "CRM software without the bloat." +- "Project management without the meetings." +- "Customer support without the tickets." + +**Strengths:** Defines you in opposition to known alternatives. + +**Weaknesses:** Lazy version becomes "X but better." Specific version requires you to actually deliver on the difference. + +**When to use:** The category has a well-known pain point you avoid. + +--- + +## Formula 7: Number + outcome + +**Pattern:** Specific number that quantifies the value. + +**Examples:** +- "Cut your churn in half within 90 days." +- "Onboard your team in 15 minutes, not 15 weeks." +- "Generate 200 hours of meeting transcripts per month." + +**Strengths:** Specific and credible. + +**Weaknesses:** The number must be defensible. Made-up numbers undermine trust. + +**When to use:** You have real data backing the claim. + +--- + +## Formula 8: First-person promise + +**Pattern:** "Get [specific thing]" or "Find [specific thing]" - speaking as if to a friend. + +**Examples:** +- "Get insurance quotes in 60 seconds. Compare 30 carriers." +- "Find a contractor your neighbors actually recommend." +- "Get back the 6 hours a week you spend on email." + +**Strengths:** Conversational. Low-friction. + +**Weaknesses:** Casual register may not fit every brand. + +**When to use:** Brand voice supports a conversational first-person register. + +--- + +## Subheadline patterns + +The subheadline supports the headline. It usually does one of three jobs: + +### Job 1: Mechanism +The subheadline explains how you deliver the headline's promise. + +> Headline: Ship features 3x faster. +> Subheadline: Our async workflow eliminates the meetings that slow your team down. + +### Job 2: Audience qualifier +The subheadline names the audience precisely. + +> Headline: The simplest way to manage your inventory. +> Subheadline: Built for ecommerce stores doing $1M to $10M in revenue. + +### Job 3: Specificity / proof +The subheadline adds the credible detail. + +> Headline: Stop losing leads. +> Subheadline: Top performers reduce response time from hours to minutes. We help you do the same. + +--- + +## What to avoid in hero copy + +### Generic adjective stacking + +**Bad:** "Powerful. Intuitive. Scalable." + +These adjectives apply to anything. They distinguish nothing. + +### Vague benefits + +**Bad:** "Streamline your workflow with our innovative platform." + +What workflow? What's innovative? What does the visitor actually do? + +### Brand-name-only headlines + +**Bad:** "Acme: The Future of Work." + +The visitor doesn't know what Acme is yet. The headline must tell them. + +### Cleverness over clarity + +**Bad:** "Where productivity meets possibility." + +Sounds nice. Means nothing. Visitors do not have time to decode poetry. + +### "Welcome to" openers + +**Bad:** "Welcome to the [Brand] platform." + +Treats the visitor as a guest rather than a person trying to solve a problem. Wastes the most important real estate on the page. + +--- + +## Testing hero headlines + +Don't ship the first headline you write. Generate 5 to 10 variations using different formulas. Read them aloud. Show them to people. Pick the one that: + +1. A target-audience reader recognizes themselves in +2. Differentiates from at least 3 specific competitors +3. Sets up the rest of the page (the rest of the page must deliver on the headline's promise) +4. Sounds like the brand (not generic marketing speak) +5. Survives the "why now" test (why does this matter to the visitor today) + +If a headline can't survive all five, generate more variations. + +--- + +## CTA patterns to pair with hero headlines + +The headline and CTA must rhyme. If they don't, the visitor's mental model breaks. + +| Hero promise | CTA pattern | +|---|---| +| Get specific outcome | "Get [the outcome]" | +| Save time / money | "Save [the thing]" | +| See how it works | "Watch demo" / "See it in action" | +| Try the product | "Start free trial" / "Try it free" | +| Get information | "Get the guide" / "Show me how" | +| Talk to a person | "Book a call" / "Talk to sales" | + +The CTA copy is part of the hero, not an afterthought. Treat it with the same care as the headline. diff --git a/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md b/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md new file mode 100644 index 0000000..23ae871 --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md @@ -0,0 +1,244 @@ +# Objection Library + +Common objections by category, with handling strategies. Use this to pressure-test landing page copy and to make sure each major objection is met somewhere on the page. + +If a landing page does not name and answer the audience's real objections, it will not convert no matter how strong the hero is. + +--- + +## How to use this library + +1. Identify your audience and the specific decision they are facing. +2. Walk this library and flag every objection that applies. +3. For each flagged objection, decide where on the page it gets handled (and whether it gets handled with copy, social proof, a guarantee, an FAQ, or a feature). +4. Pressure-test the page: read it as a skeptical reader. Are the flagged objections answered before the CTA? + +Most pages handle 5-8 objections. Pages that handle 0-2 read as too good to be true. Pages that handle 15+ feel defensive. + +--- + +## Category 1: trust + +The audience does not know if you are real, competent, or honest. + +### "I have never heard of you" + +- **Symptom:** Bounce rate high, low time on page. +- **Handling:** Logo bar of customers, press mentions, founder photo and one-line bio, "since [year]" line, recognizable case study, security badges if relevant. + +### "How do I know this works?" + +- **Symptom:** Visitors read the whole page but do not act. +- **Handling:** Specific case studies with real names and specific outcomes ("X reduced Y by Z%"). Demo or trial. Money-back guarantee. Free assessment. + +### "How do I know you will be around in a year?" + +- **Symptom:** Common in B2B with switching costs, regulated industries, long-term commitments. +- **Handling:** Funding announcements, customer count, years in business, prominent enterprise customers, industry awards or compliance attestations. + +### "Who is behind this?" + +- **Symptom:** Common in personal brands, consultancies, or expertise-based services. +- **Handling:** Founder photo, credentials, prior work, authentic origin story. + +--- + +## Category 2: fit + +The audience cannot tell if this is for them. + +### "Is this for someone like me?" + +- **Symptom:** General-audience visitors converting; specific-segment visitors bouncing. +- **Handling:** Audience-specific copy, role-based or industry-based pages, named segments in the hero ("for [role] at [company size]"), audience-specific case studies. + +### "Will this work for my situation?" + +- **Symptom:** Visitors get to features and bounce. +- **Handling:** Use case sections, conditional FAQ ("if you are X, here is how this works"), filterable case studies, decision tree or quiz. + +### "Is my problem big enough to need this?" + +- **Symptom:** SMB visitors looking at enterprise products, or vice versa. +- **Handling:** Plan or tier comparison, "right-sized for [size]" messaging, alternatives section ("if you have [smaller problem], try [lighter approach]"). + +### "I have already solved this with [alternative]" + +- **Symptom:** Visitors compare and leave. +- **Handling:** Comparison page, "vs [competitor]" page, "in addition to" framing, integrations section. + +--- + +## Category 3: complexity and time + +The audience worries this will be hard, slow, or distracting. + +### "How long will this take to set up?" + +- **Symptom:** Time-on-page high; conversion low. Common in dev tools, SaaS. +- **Handling:** "5 minutes to set up" messaging, video walkthrough showing real timing, testimonials from peers about onboarding, white-glove option. + +### "Will I have to migrate or change what I am doing?" + +- **Symptom:** Switching anxiety. Common in any tool replacement. +- **Handling:** Migration guides, importer features highlighted, "works alongside [current tool]" framing, migration assistance offered. + +### "Will my team need training?" + +- **Symptom:** Buyer is enthusiastic; champion is worried about adoption. +- **Handling:** Onboarding program, in-product training, role-based docs, video library, account manager for enterprise. + +### "Is this going to add to my plate?" + +- **Symptom:** Visitors are already overworked. Common pitch to operators, ICs. +- **Handling:** Time-saving framing with specific numbers ("saves 4 hours per week"), automation highlighted, replace-not-add positioning. + +--- + +## Category 4: cost + +The audience worries about price, value, or hidden costs. + +### "How much does this cost?" + +- **Symptom:** Anyone visiting the pricing page bounces. Conversion only on free trial. +- **Handling:** Transparent pricing on the marketing site (or "starts at" if pricing varies), no "request a quote" for low-tier pricing, ROI calculator. + +### "Is it worth the price?" + +- **Symptom:** Pricing page visited; nothing happens. +- **Handling:** Specific ROI examples ("customers see X return in Y months"), comparison to alternative ("instead of hiring a [role], you get [tool]"), free trial or money-back, value framing throughout. + +### "Are there hidden fees?" + +- **Symptom:** Visitors abandon at checkout or in sales calls when extras come up. +- **Handling:** "No setup fees" line, "no per-seat charges" if true, "all features included" if true, transparent pricing page with all variables surfaced. + +### "I do not have budget right now" + +- **Symptom:** Common in macro slowdowns. Visitors say "interesting, send info." +- **Handling:** Annual discount, smaller plan, free tier, ROI-led copy, ROI calculator, "self-funding within X months" claim if defensible. + +--- + +## Category 5: risk + +The audience fears what happens if this goes wrong. + +### "What if it does not work?" + +- **Symptom:** Visitors explore deeply but do not commit. +- **Handling:** Money-back guarantee, free trial, free pilot, money-back specifically tied to outcome ("if you do not see X, we refund"), case studies of customers who got results. + +### "What if my data is at risk?" + +- **Symptom:** Common in B2B, data tools, financial, healthcare. +- **Handling:** Security page linked from footer (and from sales-relevant pages), compliance badges (SOC 2, ISO 27001, GDPR, HIPAA), data-handling explainer, "your data is yours" framing. + +### "What if I am locked in?" + +- **Symptom:** Visitors ask about export, contracts, cancellation in sales calls. +- **Handling:** "Export your data anytime," "no long-term contract," "cancel any time," month-to-month option visible. + +### "What if my team will not adopt it?" + +- **Symptom:** Champion deals stall. +- **Handling:** Onboarding program, role-based pricing or trials, internal-rollout playbook, customer testimonials from peer companies on adoption. + +--- + +## Category 6: timing + +The audience does not see urgency. + +### "I will get to this later" + +- **Symptom:** Sign-ups but no follow-through. Long sales cycles. +- **Handling:** Cost-of-inaction framing ("each month you wait costs X"), time-bound offer (tasteful, real, not fake), seasonal hook if relevant, before-and-after framing showing time loss. + +### "I am evaluating multiple options" + +- **Symptom:** Pipeline takes 6+ months to close. +- **Handling:** Comparison page, evaluation guide ("how to evaluate [category]"), trial that gets the buyer hands-on quickly, customer references for direct calls. + +--- + +## Category 7: politics and process + +The audience cannot decide alone. + +### "I need to get my boss to approve this" + +- **Symptom:** Champion engagement high; deal stuck above champion's authority. +- **Handling:** Business case template, ROI calculator, exec one-pager, "make the case to [role]" content, customer references at peer companies (named role buying the same tool). + +### "I need legal/security/procurement to review" + +- **Symptom:** Long lag between handshake and contract signature. +- **Handling:** Security questionnaire pre-completed, MSA boilerplate available, vendor onboarding kit, named legal/security contact for buyer-side reviewers. + +### "I need to align with [other team]" + +- **Symptom:** Multi-stakeholder deals stall. +- **Handling:** Team-specific pages, team-specific demos, multi-stakeholder ROI framing, internal advocacy kit (slide deck, FAQ). + +--- + +## Category 8: emotional / status + +The audience worries about how they will look. + +### "What if this is the wrong call?" + +- **Symptom:** Decision-maker stalls. Common with high-visibility purchases. +- **Handling:** Peer customer testimonials ("[Title] at [Recognizable Company] said X"), industry analyst recognition, awards, money-back guarantee that limits downside. + +### "Will this make me look behind / ahead?" + +- **Symptom:** First-mover anxiety or laggard anxiety. Industry-specific. +- **Handling:** "Industry standard now" framing for laggards, "ahead of the curve" framing for first-movers, social proof from peer companies in either case. + +--- + +## How objection handling shows up on the page + +The library is the inventory. The page is where it lands. The most common placements: + +- **Hero:** answers the "is this for me" objection. +- **Logo bar:** answers "are you real." +- **Feature sections:** answer "does this do what I need." +- **Use case sections:** answer "will this work for my situation." +- **Case study sections:** answer "does this work." +- **Comparison sections:** answer "what about alternatives." +- **Pricing section:** answers "what does it cost." +- **FAQ section:** answers the long tail of objections. +- **Guarantee / trial offer:** answers "what if it does not work." +- **Footer trust block:** answers "is my data safe" via compliance badges. + +If an objection from your audience is not answered anywhere on the page, the page is incomplete. + +--- + +## Worked example + +**Audience:** Engineering manager at a series-B startup, 30-50 person engineering org, evaluating an observability tool to replace an in-house Grafana setup. + +**Top 5 objections (filtered from the library):** + +1. *"How long will this take to set up?"* (Category: complexity) +2. *"Will I have to migrate?"* (Category: complexity) +3. *"What does this cost at our scale?"* (Category: cost) +4. *"What if my engineers do not adopt it?"* (Category: risk + politics) +5. *"What if our data is at risk?"* (Category: risk) + +**Page placements:** + +| Objection | Where it gets handled | +|---|---| +| Setup time | Hero ("Live in 10 minutes" + 60-second product video) | +| Migration | Migration section ("imports from Grafana automatically") + case study showing migration story | +| Cost at scale | Pricing page with engineer-count slider, transparent monthly cost | +| Adoption | Adoption section showing in-product onboarding, plus a customer quote ("80% of engineers logged in week one") | +| Data risk | Footer trust block (SOC 2, ISO, GDPR) + a "your data" explainer linked from pricing | + +Page is built around answering these five, in order, from hero to CTA. diff --git a/dist/pi/.agents/skills/launch-runbook/SKILL.md b/dist/pi/.agents/skills/launch-runbook/SKILL.md new file mode 100644 index 0000000..0fb3e62 --- /dev/null +++ b/dist/pi/.agents/skills/launch-runbook/SKILL.md @@ -0,0 +1,236 @@ +--- +name: launch-runbook +description: "Plan and execute a launch runbook covering pre-launch verification, go-live procedures, DNS cutover, post-launch monitoring, and rollback procedures. Use this skill whenever the user is preparing to launch a website or product, planning a DNS cutover, building a go-live checklist, or executing a launch day. Triggers on launch runbook, go-live, launch day, DNS cutover, deploy to production, site launch, product launch, cutover plan, launch checklist, deployment procedure. Also triggers when a launch is approaching and the team needs structured coordination, even if 'runbook' is not explicitly stated." +category: operations +catalog_summary: "Go-live runbook, DNS cutover, deploy day procedures" +display_order: 1 +--- + +# Launch Runbook + +Plan and execute the launch of a website, product, or major release. The runbook is the document everyone uses on launch day. Stack-agnostic. + +This skill is for the launch event. For pre-launch QA, use `qa-testing`. For post-launch incident handling, use `incident-response`. + +--- + +## When to use + +- Launching a new website or major redesign +- Migrating from one platform to another +- Releasing a major product or feature +- Coordinating cross-team launches +- Building a runbook for a recurring deploy + +## When NOT to use + +- Pre-launch testing (use `qa-testing`) +- Post-launch incident response (use `incident-response`) +- After-launch retrospective (use `after-action-report`) + +--- + +## Required inputs + +- The launch scope (what's being launched) +- The launch window (date, time, duration) +- The team (roles, on-call rotation) +- The rollback criteria (when to abort) +- The communication plan (who tells whom what, when) + +--- + +## The framework: 4 phases + +A launch has four phases. The runbook covers all four. + +### Phase 1: Pre-launch (T-30 days to T-1 hour) + +Verify everything is ready before the launch window. + +**T-30 days:** +- Final scope locked +- Cross-team commitments confirmed +- Pre-launch QA scheduled +- Comms plan drafted + +**T-7 days:** +- Pre-launch QA complete +- All critical and major issues resolved +- Performance baseline measured +- Rollback procedures documented and tested +- DNS TTL lowered (if DNS change is part of launch) + +**T-1 day:** +- Final go/no-go meeting +- Roles confirmed +- Communication channels set up +- Backup of current production state + +**T-1 hour:** +- Team assembled in shared communication channel +- Tools and access verified +- Final smoke test on staging + +### Phase 2: Cutover (T-0) + +The actual launch. Sequenced steps with owners and verifications. + +**Standard cutover steps:** + +1. Announce start to internal team +2. Enable maintenance mode (if applicable) +3. Run final database migrations (if applicable) +4. Deploy code to production +5. Verify deploy completed without errors +6. Run smoke tests on production +7. DNS cutover (if applicable) +8. Verify DNS propagation +9. Disable maintenance mode +10. Run full smoke tests on production +11. Announce launch to internal team +12. Begin monitoring window + +Each step has: +- Owner +- Pre-conditions +- Action +- Verification +- Time estimate +- Rollback procedure + +### Phase 3: Verification (T+0 to T+24 hours) + +Confirm the launch is healthy. + +**Within first hour:** +- Critical user flows working (checkout, signup, login) +- No spike in error rates +- Performance within expected ranges +- Analytics tracking firing +- Email and notifications working + +**Within first 24 hours:** +- No regression in key business metrics +- No accumulating error patterns +- Core Web Vitals stable +- Search Console showing no critical issues (if SEO-relevant) + +### Phase 4: Stabilization (T+24 hours to T+7 days) + +Monitor the long tail. + +- Track error rates day over day +- Track performance day over day +- Track key business metrics vs baseline +- Address any non-blocking issues identified +- Plan the AAR (after-action report) + +--- + +## Roles and responsibilities + +A launch has clear role assignments. Ambiguity here is the most common cause of launch chaos. + +| Role | Responsibility | +|---|---| +| Launch lead | Owns the runbook. Calls go/no-go. Calls rollback. | +| Deploy operator | Executes the technical deploy steps. | +| QA lead | Runs verification tests and confirms each milestone. | +| Comms lead | Posts internal updates, manages external messaging. | +| On-call engineer | Available for issues during and after launch. | +| Stakeholder rep | Approves on behalf of business stakeholders. | + +For small teams, one person may fill multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Rollback criteria + +Define before the launch. Decisions are easier to make pre-emptively than under pressure. + +**Automatic rollback triggers:** +- Error rate exceeds X percent of normal +- Critical user flow (defined) is broken +- Database integrity issue +- Security vulnerability discovered post-deploy + +**Discretionary rollback triggers:** +- Performance degradation beyond Y percent +- Significant degradation in key business metric +- Customer-facing error patterns + +**Decision authority:** The launch lead calls rollback. Pre-define who acts as deputy if launch lead is unavailable. + +--- + +## Communication plan + +### Internal channels + +- **Primary launch channel:** Real-time chat for the launch team only +- **Status channel:** Broader internal updates +- **War room:** Optional video call for high-stakes launches + +### Update cadence during launch + +- Every 15 minutes during cutover +- Every hour during verification phase +- Daily during stabilization phase + +### External communication + +- **Customer-facing announcement:** Pre-drafted, scheduled to publish at confirmed-success milestone +- **Status page:** Updated proactively if any user impact +- **Support team:** Briefed in advance on what's launching, common questions, escalation path + +--- + +## Workflow + +1. **Build the runbook 30 days out.** Scope, sequence, roles, rollback criteria, comms plan. +2. **Test the rollback procedure.** Untested rollback is hope, not procedure. +3. **Run a tabletop exercise.** Walk through the runbook with the full team. Find gaps. +4. **Lower DNS TTL** 48 to 72 hours before launch (if DNS change is part of launch). +5. **Day-of:** Run the runbook step by step. Verify each step before moving to next. +6. **Monitor.** First hour, first day, first week. Document anything noteworthy. +7. **Schedule the AAR** within 1 to 2 weeks of launch. + +--- + +## Failure patterns + +- **Runbook written by one person, not reviewed.** Single perspective misses scenarios. +- **No tested rollback.** Discovering rollback is broken at the moment you need it. +- **Vague step descriptions.** "Deploy to production" without specifying which tool, which command, which environment. +- **No verification step after each action.** Errors propagate. +- **Communication gaps.** Team doesn't know launch is happening, or doesn't know it succeeded. +- **Launching at end of day Friday.** Or before a holiday. Reduce the time available to respond. +- **Skipping pre-launch QA** to hit a date. The bugs appear on launch day instead. +- **Launch fatigue.** Long launches without breaks lead to errors. Plan rest cycles for multi-day launches. +- **No on-call for first 24 hours.** Someone must be reachable. + +--- + +## Output format + +Default output: a markdown runbook at `launch-runbook-[project].md` plus supporting checklists. + +Structure: + +1. Launch metadata (what, when, who) +2. Roles and responsibilities +3. Pre-launch checklist (T-30, T-7, T-1, T-1hr) +4. Cutover sequence (numbered steps, owners, verifications) +5. Rollback procedure +6. Rollback criteria (automatic and discretionary) +7. Communication plan +8. Verification checklist (first hour, first day) +9. Stabilization plan (first week) +10. Contacts (escalation paths, on-call) + +--- + +## Reference files + +- [`references/runbook-template.md`](references/runbook-template.md) - Fillable runbook template with example cutover sequences. diff --git a/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md b/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md new file mode 100644 index 0000000..bd2a9c2 --- /dev/null +++ b/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md @@ -0,0 +1,289 @@ +# Launch Runbook Template + +Fillable runbook for a launch. Copy this template, fill in specifics for your launch. + +--- + +## Launch metadata + +**What's launching:** [Specific scope. "New marketing site at example.com replacing the legacy site."] + +**Launch date:** [YYYY-MM-DD] + +**Launch window start:** [Time, timezone] + +**Launch window end:** [Time, timezone] + +**Maintenance window required:** [Yes / No, and if yes, expected duration] + +**Launch lead:** [Name + contact] + +**Deputy launch lead:** [Name + contact, in case primary is unavailable] + +--- + +## Roles + +| Role | Person | Backup | Contact | +|---|---|---|---| +| Launch lead | | | | +| Deploy operator | | | | +| QA lead | | | | +| Comms lead | | | | +| On-call engineer (post-launch) | | | | +| Stakeholder rep | | | | + +--- + +## Pre-launch checklist + +### T-30 days +- [ ] Final scope locked and signed off +- [ ] Cross-team commitments confirmed +- [ ] Pre-launch QA scheduled +- [ ] Communications plan drafted +- [ ] Rollback procedure documented + +### T-14 days +- [ ] Pre-launch QA in progress +- [ ] Performance baseline measured (current production) +- [ ] Critical and major issues triaged +- [ ] Internal launch announcement drafted + +### T-7 days +- [ ] All critical issues resolved +- [ ] All major issues resolved or accepted with mitigation +- [ ] Rollback procedure tested in staging +- [ ] DNS TTL lowered to 60 to 300 seconds (if DNS change is part of launch) +- [ ] Final go/no-go date confirmed + +### T-2 days +- [ ] Final go/no-go meeting held +- [ ] Decision: GO / NO-GO / DEFER +- [ ] All team members confirmed available for launch window +- [ ] Backup of current production state taken +- [ ] Customer support briefed on what's launching + +### T-1 day +- [ ] Final smoke test on staging passes +- [ ] Communication channels set up +- [ ] On-call rotation confirmed for first 24 hours +- [ ] Pre-drafted internal and external messaging ready + +### T-1 hour +- [ ] Team assembled in launch communication channel +- [ ] All required tools and access verified +- [ ] Final smoke test on staging passes +- [ ] Launch lead confirms GO + +--- + +## Cutover sequence + +For each step: +- **Owner:** Person executing +- **Pre-condition:** What must be true to start +- **Action:** What to do +- **Verification:** How to confirm success +- **Estimated time:** How long this should take +- **Rollback:** What to do if this step fails + +--- + +### Step 1: Announce start + +- **Owner:** Comms lead +- **Pre-condition:** Launch lead has confirmed GO +- **Action:** Post in internal status channel: "Starting launch of [scope] at [time]. Expected duration: [X minutes]." +- **Verification:** Message posted, key stakeholders confirmed they saw it +- **Time:** 2 minutes + +### Step 2: Enable maintenance mode + +- **Owner:** Deploy operator +- **Pre-condition:** Step 1 complete +- **Action:** [Specific command or action to enable maintenance mode] +- **Verification:** Visit production URL, confirm maintenance page is showing +- **Time:** 2 minutes +- **Rollback:** Disable maintenance mode + +### Step 3: Final database migrations + +- **Owner:** Deploy operator +- **Pre-condition:** Step 2 complete, database backup confirmed +- **Action:** [Specific migration command] +- **Verification:** Migration log shows success, schema verified +- **Time:** [estimate] +- **Rollback:** Restore from backup taken in T-2 + +### Step 4: Deploy code to production + +- **Owner:** Deploy operator +- **Pre-condition:** Step 3 complete +- **Action:** [Specific deploy command or CI trigger] +- **Verification:** Deploy log shows success, version endpoint returns new version +- **Time:** [estimate based on past deploys] +- **Rollback:** Re-deploy previous version + +### Step 5: Run smoke tests on production + +- **Owner:** QA lead +- **Pre-condition:** Step 4 complete +- **Action:** Run smoke test suite against production +- **Verification:** All smoke tests pass +- **Time:** [estimate] +- **Rollback:** If failures, evaluate severity. Critical failures = rollback to step 4. + +### Step 6: DNS cutover (if applicable) + +- **Owner:** Deploy operator +- **Pre-condition:** Step 5 passes +- **Action:** Update DNS records: [specific records and values] +- **Verification:** Use `dig` or DNS lookup tools to confirm new records propagating +- **Time:** Propagation up to 5 minutes (if TTL was lowered) up to 24+ hours (if not) +- **Rollback:** Revert DNS records to previous values + +### Step 7: Disable maintenance mode + +- **Owner:** Deploy operator +- **Pre-condition:** Step 6 verified +- **Action:** [Specific command to disable maintenance mode] +- **Verification:** Visit production URL, confirm new site loads +- **Time:** 2 minutes + +### Step 8: Full smoke test on production + +- **Owner:** QA lead +- **Pre-condition:** Step 7 complete +- **Action:** Run full smoke test suite (more comprehensive than step 5) +- **Verification:** All tests pass; critical user flows verified manually +- **Time:** [estimate] +- **Rollback:** If failures, evaluate. Critical failures = full rollback. + +### Step 9: Announce success + +- **Owner:** Comms lead +- **Pre-condition:** Step 8 passes +- **Action:** Post in internal status channel: "Launch complete. All checks pass." +- **Verification:** Confirmed by stakeholders +- **Time:** 2 minutes + +### Step 10: Begin monitoring window + +- **Owner:** On-call engineer +- **Pre-condition:** Step 9 complete +- **Action:** Begin elevated monitoring for first 60 minutes. Watch error rates, performance, key business metrics. +- **Verification:** Dashboards open, alerts armed +- **Time:** Continuous + +--- + +## Rollback procedure + +If rollback is called, execute these steps: + +1. Announce rollback in internal status channel +2. Re-enable maintenance mode (if applicable) +3. Revert DNS records to previous values (if changed) +4. Re-deploy previous code version +5. Restore database from backup (if migrations were destructive) +6. Verify previous version is functioning +7. Disable maintenance mode +8. Run smoke tests on rolled-back state +9. Announce rollback complete +10. Schedule post-mortem + +**Estimated total rollback time:** [Estimate, typically 15 to 60 minutes] + +**Authority to call rollback:** Launch lead (or deputy if launch lead unavailable) + +--- + +## Rollback criteria + +### Automatic rollback (no debate, just do it) +- [ ] Production error rate exceeds [X]% above baseline +- [ ] Critical user flow broken: [specify which flows] +- [ ] Database integrity issue detected +- [ ] Security vulnerability discovered + +### Discretionary rollback (launch lead's call) +- [ ] Performance degradation beyond [Y]% +- [ ] Significant degradation in [specific business metric] +- [ ] Customer-facing error pattern emerging + +--- + +## Communication plan + +### Internal updates during launch +- **Cadence:** Every 15 minutes during cutover +- **Channel:** [Specific Slack channel / Teams channel / etc.] +- **Format:** "[Time] - [Step name] - [Status: started / in progress / complete / blocked]" + +### Customer-facing announcement +- **When:** After step 9 (success announce internal) +- **Where:** [Specific channels: blog post, email, social, etc.] +- **Pre-drafted:** [Link to draft] +- **Approver:** [Name] + +### Status page updates +- Pre-launch: [Status set to "Maintenance scheduled"] +- During: [Status set to "Maintenance in progress"] +- Post-success: [Status set to "Operational"] +- If issues: [Status set to "Investigating" or "Identified"] + +### Support team brief +- Pre-launch brief covers: what's launching, what users may notice, common questions, escalation path +- During-launch updates posted to support channel + +--- + +## Verification checklist (first hour) + +- [ ] Homepage loads +- [ ] Critical user flow 1: [specify] - works +- [ ] Critical user flow 2: [specify] - works +- [ ] Critical user flow 3: [specify] - works +- [ ] Sign-up / sign-in - works +- [ ] Payment flow (if applicable) - works +- [ ] Email sending - works +- [ ] Analytics tracking firing +- [ ] Error rate within normal range +- [ ] Performance within normal range +- [ ] No security alerts triggered +- [ ] Search Console shows no critical issues (if SEO-relevant launch) + +--- + +## Verification checklist (first 24 hours) + +- [ ] No regression in key business metrics: [list specific metrics] +- [ ] Error rate stable +- [ ] Performance stable +- [ ] No accumulating error patterns +- [ ] Core Web Vitals stable +- [ ] Customer support volume within normal range + +--- + +## Contacts + +| Role | Name | Phone | Slack | Email | +|---|---|---|---|---| +| Launch lead | | | | | +| Deputy lead | | | | | +| Engineering on-call | | | | | +| Database admin | | | | | +| DNS / infrastructure | | | | | +| Customer support lead | | | | | +| Executive sponsor | | | | | + +--- + +## Post-launch + +- [ ] Schedule AAR within 1 to 2 weeks +- [ ] Document any deviations from runbook +- [ ] Capture metrics: rollback rate, time to launch, issues found, etc. +- [ ] File improvements to runbook for next launch diff --git a/dist/pi/.agents/skills/lead-magnet-design/SKILL.md b/dist/pi/.agents/skills/lead-magnet-design/SKILL.md new file mode 100644 index 0000000..29da923 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/SKILL.md @@ -0,0 +1,282 @@ +--- +name: lead-magnet-design +description: "Designing lead magnets that earn the email. The discipline of building gated content (ebooks, templates, checklists, swipe files, mini-courses, free tools) that delivers genuine standalone value while qualifying the lead and warming them for what comes next. Honest about thin-bait (overpromises, underdelivers), kitchen-sink-resource (everything, helps with nothing), and earned-value-magnet (delivers standalone value while qualifying the lead). Triggers on lead magnet, gated content, opt-in offer, ebook, checklist, template, swipe file, mini-course, free tool, content upgrade, freebie, opt-in, list-building offer. Also triggers when an audience is being asked for an email and the offer attached to that ask needs design discipline, when previous lead magnets converted but did not produce qualified leads, or when a lead magnet is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing gated content that earns the email. Distinguishes thin-bait (overpromises, underdelivers) from kitchen-sink-resource (everything, helps with nothing) from earned-value-magnet (delivers standalone value while qualifying the lead)" +display_order: 1 +--- + +# Lead Magnet Design + +A senior growth practitioner's playbook for designing lead magnets that earn the email. Templates, checklists, swipe files, mini-courses, free tools, ebooks. The discipline of building gated content that delivers genuine standalone value while qualifying the lead and warming them for the next conversation. + +Most lead magnets are bait. A vague headline, a thin PDF, an email gate, a follow-up sequence the reader resents. Conversion-rate metrics look fine because the form converted; the email list grows; and the unsubscribe rate climbs because the magnet was a transaction the reader regrets the moment they download. + +The lead magnets that work as compounding assets do something different. They deliver value the reader would have paid for if they had to. They qualify the lead by audience-fit, so the list that grows is the right list. They set up the next conversation honestly, so the follow-up sequence is a continuation rather than an apology. + +This skill is the parent-frame methodology for the growth tooling track. Calculators (`calculator-design`) and quizzes (`quiz-and-assessment-design`) are specific lead-magnet types covered as their own skills. This skill provides the methodology for deciding WHAT to build before deciding WHAT TYPE. + +The voice is the senior growth practitioner who has watched lead magnets earn long-term subscribers and watched them burn list trust within a single send. Practical, opinionated about format selection, willing to tell the reader when a lead magnet is the wrong investment for the goal. + +When to use this skill: scoping a lead magnet for the first time, auditing a lead magnet that converts but does not qualify, deciding which format fits a specific audience and offer, or designing the post-download sequence that turns the magnet into a relationship. + +--- + +## What this skill covers + +This skill spans lead magnet design as the parent discipline. The growth-tooling distinctions: + +- **`lead-magnet-design` (this skill)** is the parent-frame methodology. WHAT a magnet is, when to invest in one, which format fits, how to qualify the lead, how to set up the follow-up. +- `calculator-design` is one specific lead-magnet type with its own methodology (calculation transparency, tiered value, methodology disclosure). +- `quiz-and-assessment-design` is another specific lead-magnet type (scoring algorithms, result categorization, recommendation matching). +- `landing-page-copy` is the page-level discipline that wraps the magnet's offer. +- `content-distribution` is how the magnet reaches its audience. +- `content-strategy` is upstream: the topic decisions that earn investment in any one magnet. + +The audience: growth marketers, in-house product marketers, marketing teams, agencies running list-building work for clients, founders building their own funnels. + +Out of scope: long-form content marketing (covered by `content-strategy`); landing-page copy (covered by `landing-page-copy`); email sequence design at scale (covered by `email-sequences`); the specific tooling configurations that deliver the magnet (those stay implementation-side). + +--- + +## The lead magnet decision: when to build one, when not to + +Before designing the magnet, decide whether a magnet is the right investment. + +**A lead magnet earns investment when:** + +- The audience exists in volume but is not yet on the list. Traffic without conversion is the gap a magnet fills. +- The product or service has a long consideration cycle. The list builds the relationship across the consideration window. +- The audience has a specific, immediate problem that a focused resource can address. Magnets work when the gap they fill is concrete. +- The follow-up sequence has a real purpose. Without a sequence that turns subscribers into something (customers, community members, qualified leads), the magnet is list-building theater. + +**A lead magnet does NOT earn investment when:** + +- The audience would convert directly without a magnet. SaaS with a free trial, ecommerce with a discount code, or freemium with a low-friction signup may not need a magnet between the visitor and the product. +- The team cannot commit to the follow-up. A list without a sequence is a list that decays. +- The topic is too broad to focus a single resource. "Marketing" is not a magnet topic; "the welcome-email template that 4x'd our trial-to-paid rate" is. +- Sales calls or demos are the next step. If the goal is a booked call, design the call-booking flow, not the magnet. + +The decision is not "should we have a magnet"; it is "is the magnet the right next investment for this specific audience and goal." + +Detail in [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md). + +--- + +## Thin-bait vs kitchen-sink-resource vs earned-value-magnet + +The keystone framing. + +**Thin-bait.** "10 tips for X" PDFs that are 200 words of fluff behind an email gate. The headline overpromises; the contents underdeliver. The reader downloads, skims, deletes, and unsubscribes within a week. The conversion-rate metric looks fine; the list quality and brand trust both degrade. Cost: every subscriber acquired through thin-bait costs more than they appear to, because the unsubscribe rate, the reduced sender reputation, and the reduced list-trust each compound. + +**Kitchen-sink-resource.** 80-page "Ultimate Guide" containing everything anyone could want about the topic. Includes nothing the reader actually needs RIGHT NOW. Bookmarked, never read, eventually forgotten. Cost: the magnet does not produce the moment of "I needed this and got it," which is the moment the relationship starts. Subscribers stay on the list out of inertia; the relationship never deepens; future emails get ignored. + +**Earned-value-magnet.** Solves a specific, immediate problem the reader has. Genuine standalone value, the kind that would be worth paying for if it were not free. Qualifies the lead by audience-fit. Warms the reader for a specific related offer that follows. The reader downloads, uses the resource, gets the result, and remembers the brand as the source of that result. + +The litmus test. Hand the magnet to a non-subscriber in the target audience. Watch them use it. Does the resource produce the promised outcome inside the time the reader was willing to spend? If yes, the magnet is earned-value. If the reader downloads and never opens, the magnet is thin-bait or kitchen-sink-resource regardless of how the headline reads. + +--- + +## Format selection + +Magnets come in formats. Each format has strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +**Templates.** A starting artifact the reader fills in or adapts. Strong for audiences who need to produce a specific deliverable (a brief, a spec, a pitch deck, an email). Strong because the value is immediate and concrete. Weak when the template is too generic to feel custom. + +**Checklists.** A sequence of items to verify or complete. Strong for audiences executing a known process where the gap is comprehensiveness, not direction. Strong because the format signals "you can use this in 10 minutes." Weak when the checklist reads as marketing rather than as a working tool. + +**Swipe files.** A curated collection of examples (subject lines, headlines, ad copy, design references). Strong for audiences who learn from examples and need inspiration rather than instruction. Weak when the swipes are stale or unattributed. + +**Mini-courses.** A multi-part email or video sequence delivering structured learning. Strong for audiences willing to invest sequential attention; strong because the sequence creates multiple touchpoints. Weak when the course is filler or when each lesson does not stand on its own. + +**Free tools (calculators, quizzes, generators).** Interactive web tools that produce a result. Strong for audiences who want a personalized output rather than a generic resource. Strong because the interaction qualifies the lead by inputs. Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Ebooks.** Long-form treatment of a topic. Strong for audiences researching a complex decision; strong when the ebook reads as a definitive resource. Weak when used as a default format for topics that would have served the reader better as a checklist or template. + +**Video series.** Sequential video content delivered behind a gate. Strong for topics that benefit from demonstration; strong for audiences who learn from video. Weak when the production overhead exceeds the topic's value or when the audience does not consume video content at the time-of-magnet moment. + +The choice depends on the audience's preferred consumption mode, the topic's natural shape, and the production overhead the team can sustain. A great template often outperforms a mediocre ebook on the same topic. + +Detail in [`references/format-selection-patterns.md`](references/format-selection-patterns.md). + +--- + +## The "would they pay for this" test + +The single test that distinguishes earned-value from thin-bait. + +The question. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails this test is signaling that the value is below the threshold of "I would pay for this," which means the reader's time investment to download and consume it is at the edge of "worth it." + +The test is not perfect. Some valuable resources are hard to price (how much is a great checklist worth?). But the test catches the magnets that exist primarily to capture an email rather than to deliver value. + +Three failure modes the test catches. + +- The 5-page PDF that summarizes blog content. Free elsewhere; not pay-worthy. +- The "Ultimate Guide" that nobody finishes. Pay-worthy in theory; not delivered in usable form. +- The template that is so generic it adds no value over starting from scratch. Pay-worthy framing; thin in execution. + +The test the magnet should pass. + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +If the magnet passes the test, it earns the email. If it fails, redesign before launching. + +Detail in [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md). + +--- + +## Audience-fit qualification + +The magnet as filter, not just bait. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). + +**Filter through the headline.** The headline tells the wrong audience to opt out. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, and consumer-app PMs. The conversion rate from the visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +**Filter through the topic.** A magnet on a niche topic attracts a niche audience. Generic topics attract generic audiences who churn off the list. Specific topics attract specific audiences who stay. + +**Filter through the format.** A 60-minute video course filters out audiences who will not invest 60 minutes. A 2-page checklist filters in audiences who want quick wins. The format signals what the brand expects of the relationship. + +**Filter through the offer adjacent to the magnet.** The follow-up sequence often makes a soft offer for a related product or service. The magnet should be tightly enough scoped that the audience who downloads it is also the audience who would consider the adjacent offer. + +The filtering principle. A magnet that converts 50 percent of visitors but produces 5 percent qualified leads is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. Optimize for the qualified lead, not for the surface conversion rate. + +Detail in [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md). + +--- + +## Title and presentation discipline + +The magnet's title is the conversion lever and the qualification filter at the same time. + +**Title patterns that work.** + +- **Specific outcome + specific audience.** "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." +- **Specific deliverable + specific situation.** "The pricing one-pager for SaaS founders raising a seed round." +- **Specific framework + specific problem.** "The 4-question framework for deciding whether to fire a customer." +- **Specific count + specific value.** "23 onboarding emails, with the open and click rate for each." + +**Title patterns to avoid.** + +- "Ultimate Guide to X." Vague. Promises too much. Underdelivers reliably. +- "The Complete X Playbook." Same failure mode. Promises completeness; delivers volume. +- "Free [Topic] Resource." Generic. Tells the reader nothing about why this resource is the one to download. +- "10 Tips for Better X." Listicle framing signals thin content. + +**Presentation discipline beyond the title.** + +- The cover or preview image should reinforce the specificity. A clean type-driven cover often outperforms a cluttered one. +- The landing page (handled by `landing-page-copy`) should preview the magnet, not just describe it. +- The first page of the magnet should deliver value within the first read, not warm up with author bio and brand-positioning. + +Detail in [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md). + +--- + +## Delivery and follow-up sequence design + +The sequence is the magnet's second act. Without it, the magnet is one transaction; with it, the magnet starts a relationship. + +**The delivery moment.** The reader fills the form and expects the resource immediately. Delivery delay (manual review, scheduled send) breaks the moment. The first email should deliver the asset and confirm the next step. + +**The first 7 days.** The reader is most engaged in the days right after download. The sequence should make use of that window: a follow-up that helps them apply the resource, a related artifact that extends the value, a soft introduction to the brand and the next step. + +**The medium-term.** Days 8 to 30, the sequence transitions from "value-add" to "ongoing relationship." Newsletter signup, related-content rotation, or a soft offer for the adjacent product or service. + +**The honest offer.** When the sequence makes an offer, the offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course; the audience signal would be wasted. + +**The opt-out.** A reader who unsubscribes from the magnet sequence is not a failure; they are a clean filter. The list quality stays higher when the unfit subscribers leave on their own. + +Detail in [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md). + +--- + +## Format-specific quality gates + +Each format has quality gates specific to that format. A great template fails different tests than a great mini-course. + +**Template gates.** Does the reader produce a usable artifact in under 30 minutes? Are the prompts specific enough to feel custom? Is the template adaptable across the segment of the audience or rigidly bound to one situation? + +**Checklist gates.** Is each item actionable today? Does the checklist sequence reflect actual workflow order? Is the checklist scoped narrowly enough to feel comprehensive within scope? + +**Swipe file gates.** Are the swipes attributed (where possible)? Are they current (not 5 years stale)? Is the curation visible (the reader can see why each swipe is included)? + +**Mini-course gates.** Does each lesson deliver standalone value (not "you will learn the answer in lesson 4")? Is the cumulative time commitment honest in the title? Does the course end with a clear next step (not just "thanks for taking the course")? + +**Calculator and quiz gates.** Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Ebook gates.** Is the ebook navigable (table of contents, page numbers, summary boxes) such that a reader who does not finish still extracts value? Is the production quality consistent with the brand it represents? + +**Video series gates.** Is each video shot at a quality the brand can sustain? Is the audio consistently clear? Is the runtime honest in the listing? + +Each format's gates exist because thin-bait can hide in any format. The quality gates make hiding harder. + +Detail in [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md). + +- "Conversion rate is great, list quality is terrible." Thin-bait pattern; magnet attracts the wrong audience or fails to deliver the promised value. +- "We ship a magnet; nothing happens after." No follow-up sequence; the magnet is one transaction rather than the start of a relationship. +- "Our 80-page Ultimate Guide gets downloaded but never read." Kitchen-sink-resource; comprehensive in scope, useless in application. +- "We changed the format from PDF to webinar; conversion rate dropped." Format mismatched to audience; the audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. +- "The magnet works in paid traffic but not organic." The audience reaching the magnet through paid is different from the organic audience; the magnet may fit one but not the other. +- "Subscribers go cold after the first email." Sequence absent or poorly designed; the value evaporates after delivery. +- "We have 5 magnets; one converts well, the others are dead." Magnet portfolio not maintained; audiences move and topics decay; periodic audit missing. +- "The follow-up offer mismatches the magnet's audience." Magnet attracted one segment; offer pitches a different one; conversion to the offer near zero. +- "We cannot tell which traffic source produces qualified leads." Attribution missing or rolled up at the wrong level; lead-quality signal not connected back to source. +- "The team built three magnets last quarter; the team avoids talking about results." Magnets shipped without success metric definition; results ambiguous or quietly underwhelming. + +--- + +## The framework: 12 considerations for lead magnet design + +When designing or auditing a lead magnet, walk these 12 considerations. + +1. **The magnet decision.** Is a magnet the right investment for this audience and goal, or does the funnel work without one? +2. **Earned-value, not thin-bait or kitchen-sink-resource.** The magnet would be worth paying for; it solves a specific problem in usable form. +3. **Format matched to audience and topic.** The format reflects how the audience consumes content and how the topic naturally shapes. +4. **The "would they pay for this" test.** Pass before launching. +5. **Audience-fit qualification.** The magnet filters for the right audience, not just maximum conversion. +6. **Title and presentation discipline.** Specific, honest, signals what is inside. +7. **Delivery in the moment.** First email arrives immediately; the asset is in that email. +8. **Follow-up sequence designed.** The 30 days after download have a purpose, an arc, and a soft offer that matches the audience. +9. **Format-specific quality gates passed.** The format's specific tests verified before launch. +10. **Lead quality measured, not just conversion rate.** What percentage of subscribers fit the audience the magnet was designed for? +11. **Attribution to source.** The team can tell which source produced which leads at which quality. +12. **Audit cadence.** The magnet portfolio gets reviewed periodically; underperformers retired. + +The output of the framework is a lead magnet that earns the email by delivering real value, qualifies the audience by filtering at the headline and topic level, and starts a relationship through a sequence the team has actually designed. + +--- + +## Reference files + +- [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md) - When a lead magnet is the right investment and when it is not. The conditions that make magnets worth the build. +- [`references/format-selection-patterns.md`](references/format-selection-patterns.md) - Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit, conversion baselines. +- [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md) - The pricing thought experiment that distinguishes earned-value from thin-bait. Worked examples and failure modes. +- [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md) - The magnet as filter. Filtering through headline, topic, format, and follow-up offer. +- [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md) - Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. +- [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md) - Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. +- [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md) - Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. +- [`references/lead-magnet-anti-patterns.md`](references/lead-magnet-anti-patterns.md) - The patterns that look like lead magnets but do not behave like them. +- [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: magnets earn the email when they earn the reader's afternoon + +The magnets that work as compounding assets are the ones the reader uses. Not downloads. Not bookmarks. Uses. The reader opens the resource, applies it, and gets a result they would have paid for if they had to. + +That is the bar. Below the bar is thin-bait (the resource is too thin to use) or kitchen-sink-resource (too much to consume). Above the bar is the relationship: the reader remembers the brand as the source of the result, opens the next email, and considers the offer when it comes. + +The discipline is in the design choices upstream of the form. The format matched to the audience and topic. The title that filters and earns. The pricing thought experiment that catches the thin magnets before launch. The follow-up sequence designed before the magnet ships, not after. The audit cadence that retires the magnets that stopped working. + +When in doubt, ask: would the audience pay for this if it were not free, and will the team commit to the sequence after the download? If yes to both, the magnet earns the email. If no to either, redesign or do not ship. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md b/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md new file mode 100644 index 0000000..7278886 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md @@ -0,0 +1,171 @@ +# Audience-fit qualification + +The magnet as filter, not just bait. Filtering through headline, topic, format, and follow-up offer. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). The filtering is the difference between a list that grows and a list that grows in the right direction. + +--- + +## The filtering principle + +The magnet's job is not to maximize email captures. It is to maximize qualified email captures. + +A magnet that converts 50 percent of visitors but produces 5 percent qualified leads (visitors who match the audience the magnet was designed for) is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. The qualified-lead-rate metric matters more than the surface conversion rate. + +The filtering happens at multiple points: the headline, the topic, the format, the landing-page copy, and the follow-up offer. Each is a filter that lets in the right audience and turns away the wrong one. + +--- + +## Filter through the headline + +The headline is the first filter. The right audience self-selects in; the wrong audience self-selects out. + +**Specific outcome plus specific audience.** "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, consumer-app PMs. The conversion rate from visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +**Specific situation.** "The pricing one-pager for SaaS founders raising a seed round" filters out everyone except SaaS founders raising a seed round. That is a tiny audience; the audience that converts is exactly the audience the brand wants. + +**Specific deliverable.** "The 23-email sequence we send to trial signups who go cold" filters in PMs, growth marketers, and founders running SaaS funnels. Filters out everyone else. + +**The headline test.** Read the headline. Who in the broader audience self-selects out? If the answer is "no one, anyone might want this," the headline is not filtering. Generic headlines attract generic audiences; specific headlines attract specific audiences. + +--- + +## Filter through the topic + +The topic itself filters before the headline polishes the message. + +**Niche topics attract niche audiences.** "Pricing for B2B SaaS founders raising a seed round" is a topic that filters by definition. The audience for this topic is small but precise. + +**Generic topics attract generic audiences.** "Marketing tips" attracts everyone, which means it attracts no one specifically. The list grows; the lead quality dilutes. + +**The topic-segmentation question.** What audience segment is this topic specifically valuable for? If the answer is "everyone," the topic is too broad. Narrow until the answer is "the segment we want to serve." + +**Topic-narrowing examples.** + +- Too broad: "Email marketing tips." +- Narrowed: "Welcome-email sequences for B2B SaaS trials." +- Narrowed further: "The 7-email welcome sequence for B2B SaaS trials in the 5-50 employee segment." + +Each narrowing reduces the addressable audience and increases the qualification of those who convert. + +--- + +## Filter through the format + +The format signals what the brand expects of the relationship. + +**A 60-minute video course filters out audiences who will not invest 60 minutes.** This is sometimes the right filter (for high-investment audiences) and sometimes the wrong one (for skim-and-apply practitioners). + +**A 2-page checklist filters in audiences who want quick wins.** This is often the right filter for practitioners executing known processes. + +**A free tool with detailed inputs filters in audiences with concrete situations the tool addresses.** The inputs themselves qualify the lead. + +**An 80-page ebook filters in audiences researching a complex decision.** Filters out audiences seeking quick artifacts. + +The format choice should match the audience the magnet is designed to attract. A mismatch (a 60-minute course for a skim audience, a 2-page checklist for an in-depth research audience) breaks the filter. + +--- + +## Filter through the landing-page copy + +The landing page is the magnet's marketing layer. It filters by amplifying the headline and topic signals. + +**Audience-specific copy.** "For SaaS founders" beats "For founders" beats "For everyone." Each audience-specific cue filters. + +**Situation-specific copy.** "If you are scaling from 100 to 1000 customers, here is the playbook." Filters by situation. + +**Result-specific copy.** "After implementing this template, our trial-to-paid rate moved from 8 percent to 14 percent." Filters by who cares about that result. + +**Anti-filter copy.** "This is for everyone in marketing." Generic. No filter. Attracts the wrong audience and dilutes the list. + +The landing page should sharpen the filter the headline and topic establish, not dilute it. + +--- + +## Filter through the follow-up offer + +The follow-up offer is the late-stage filter. The audience who downloads the magnet and then engages with the offer is the audience the program needs to compound. + +**Offer-magnet alignment.** A magnet on B2B onboarding should be followed by an offer relevant to B2B teams. A misalignment (a magnet on B2B onboarding followed by an offer for consumer-app courses) wastes the qualification the magnet did. + +**Offer-audience alignment.** The offer should fit the audience the magnet attracted. If the magnet attracted SaaS founders and the offer is for enterprise sales teams, the audience signal is wasted. + +**Offer-stage alignment.** A top-of-funnel magnet should be followed by an offer at the right consideration stage (not "buy now" 3 emails after download for a high-ticket product). + +The follow-up offer's conversion rate is the qualification metric that matters most. A list that engages with the offer is a list the magnet qualified well. + +--- + +## The qualified-lead metric + +Beyond conversion rate, qualified-lead rate is the metric the magnet's filter should be measured by. + +**Definition.** Of the subscribers acquired through the magnet, what percentage match the audience profile the magnet was designed for? + +**Measurement methods.** + +- **Self-reported segment data.** Capture audience-segment data on the form (company size, role, industry). Measure the percentage that match. +- **Email engagement.** Measure open and click rates on follow-up emails relevant to the target audience. Low engagement signals audience mismatch. +- **Downstream conversion.** Measure conversion to the next step (trial, demo, purchase). Low downstream conversion despite high upstream engagement signals audience mismatch. + +**The qualified-lead-rate target.** Programs vary, but 40-70 percent of subscribers matching the target audience is a reasonable bar for a well-filtered magnet. Below 30 percent suggests the filter is broken; above 70 percent suggests the filter may be too narrow (and the magnet may be missing audience the brand could serve). + +--- + +## When to widen the filter, when to narrow + +Filter-tuning is part of the magnet's lifecycle. + +**Widen the filter when:** + +- Conversion rate is healthy but the audience the brand serves is broader than the magnet captures. +- The qualified-lead rate is high (suggesting the filter could let in more without sacrificing quality). +- The team is launching a broader product or service that fits a wider audience. + +**Narrow the filter when:** + +- Lead quality is diluting (the magnet attracts subscribers who do not match the brand's offering). +- The follow-up sequence's engagement is low because the audience does not match the offers. +- The team is focusing on a specific segment and wants the magnet to filter for it. + +The discipline. Filter tuning is iterative. The magnet's headline, topic, and follow-up can be adjusted to widen or narrow the filter as the program evolves. + +--- + +## Common filter failures + +**The headline does not filter.** Generic title; attracts everyone; lead quality dilutes. + +**The topic is too broad.** "Marketing" rather than "B2B SaaS pricing." Generic topic; generic audience. + +**The format is mismatched.** A long-form video for a skim audience; the wrong audience self-selects. + +**The landing page softens the filter.** Audience-specific headline followed by generic landing-page copy that anyone could read; the filter weakens. + +**The follow-up offer mismatches.** Magnet attracts one audience; offer pitches a different one; downstream conversion drops. + +**The team measures conversion rate but not lead quality.** The surface metric looks fine; the real metric (qualified-lead rate) is unmeasured; the magnet looks like a success while the list quality degrades. + +The pattern across failures: the team optimizes for the easier metric (conversion rate) and loses the harder metric (qualified-lead rate). The discipline is to measure both and to tune for the lead quality the program needs. + +--- + +## The high-conversion-low-quality trap + +A magnet can convert at exceptional rates while producing terrible lead quality. The trap surfaces when the team celebrates the conversion rate and ignores the downstream signal. + +**The pattern.** A generic, broadly-appealing magnet ("Marketing Tips for 2026") converts at 25 percent. The list grows quickly. The follow-up sequence sees low engagement; the offers convert at near-zero rates; the unsubscribe rate is high. + +**The diagnosis.** The magnet attracted everyone, including audiences the brand cannot serve. The high conversion rate masked the low lead quality. + +**The fix.** Narrow the magnet's filter. The conversion rate will drop; the lead quality will rise; the program's compounding metric (qualified-lead growth) will improve. + +--- + +## Methodology-level choices that stay in the public skill + +The filtering principle. Filter through headline, topic, format, landing-page, and follow-up offer. The qualified-lead metric and how to measure it. When to widen and when to narrow. The high-conversion-low-quality trap. Common filter failures. + +## Implementation choices that stay internal + +Specific filter-tuning conventions for the team's audience. Specific qualified-lead-rate baselines for specific magnets. Specific segment-data capture methods on forms. Specific tooling for engagement and downstream-conversion measurement. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md b/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md new file mode 100644 index 0000000..30ea197 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md @@ -0,0 +1,187 @@ +# Common lead magnet failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the magnet underperformed" or "the list is not converting" or "we cannot tell if the magnet worked." + +--- + +## "Conversion rate is great, list quality is terrible." + +**The diagnosis.** Thin-bait pattern. The magnet attracts the wrong audience or fails to deliver promised value. Conversion-rate metric looks fine because the form converted; the lead quality metric (which is the metric that matters for downstream conversion) is poor. + +**The cure.** Apply the "would they pay for this" test (`references/would-they-pay-for-this-test.md`). Apply audience-fit qualification (`references/audience-fit-qualification.md`). Strengthen the magnet until it earns the email rather than baits it. + +--- + +## "We ship a magnet; nothing happens after." + +**The diagnosis.** No follow-up sequence. The magnet is one transaction rather than the start of a relationship. + +**The cure.** Design the sequence before shipping the magnet (`references/delivery-and-follow-up-sequences.md`). The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## "Our 80-page Ultimate Guide gets downloaded but never read." + +**The diagnosis.** Kitchen-sink-resource pattern. Comprehensive in scope, useless in application. The reader cannot consume the resource in the time they were willing to spend. + +**The cure.** Narrow the topic until the magnet addresses one specific problem in usable form. The 80-page guide often becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## "We changed the format from PDF to webinar; conversion rate dropped." + +**The diagnosis.** Format mismatched to audience. The audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. + +**The cure.** Format selection (`references/format-selection-patterns.md`). Match the format to the audience's preferred consumption mode and the topic's natural shape. The format change might still be right (if the new format better serves a different segment) but the metric drop is signal. + +--- + +## "The magnet works in paid traffic but not organic." + +**The diagnosis.** The audience reaching the magnet through paid is different from the organic audience. The magnet may fit one but not the other. + +**The cure.** Understand the audience differences. Paid traffic often has different intent and different audience composition than organic. The magnet may need a separate version for each, or the magnet may need to be retitled to match the actual audience reaching it. + +--- + +## "Subscribers go cold after the first email." + +**The diagnosis.** Sequence absent or poorly designed. The value evaporates after delivery. + +**The cure.** Design the first-7-days arc to add value progressively (`references/delivery-and-follow-up-sequences.md`). Each email should add something the reader can use; the cumulative arc deepens the relationship. + +--- + +## "We have 5 magnets; one converts well, the others are dead." + +**The diagnosis.** Magnet portfolio not maintained. Audiences move and topics decay; the periodic audit is missing. + +**The cure.** Audit the portfolio (`references/lead-magnet-anti-patterns.md`, "How to detect anti-patterns in the portfolio"). Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## "The follow-up offer mismatches the magnet's audience." + +**The diagnosis.** Magnet attracted one segment; offer pitches a different one. The audience signal the magnet captured was wasted. + +**The cure.** Align the offer to the audience the magnet attracts (`references/delivery-and-follow-up-sequences.md`, "The offer-magnet alignment"). If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## "We cannot tell which traffic source produces qualified leads." + +**The diagnosis.** Attribution missing or rolled up at the wrong level. Lead-quality signal is not connected back to source. + +**The cure.** Capture source attribution at the form level. Measure lead quality (audience-fit, downstream conversion) per source. The diagnostic data informs which sources warrant further investment. + +--- + +## "The team built three magnets last quarter; the team avoids talking about results." + +**The diagnosis.** Magnets shipped without success metric definition. Results ambiguous or quietly underwhelming. + +**The cure.** Define the success metric before building (`references/lead-magnet-decision-criteria.md`, "The success metric is defined"). What does "the magnet worked" look like? Without the definition, evaluation is impossible and underperformers do not get retired. + +--- + +## "Downloads are high; trial signups are unchanged." + +**The diagnosis.** The magnet captures emails but does not move the downstream metric the team cares about. Either the magnet's audience does not match the trial-buying audience, or the sequence does not bridge to the offer. + +**The cure.** Trace the funnel from magnet download to trial signup. Identify the drop. The drop is often at the offer step (audience misalignment) or at the sequence step (no clear path from magnet to offer). + +--- + +## "The magnet got shared on social; we got 1000 subscribers; none converted." + +**The diagnosis.** The magnet's distribution outpaced its audience-fit. A viral magnet attracts an audience that does not match the brand's offer. + +**The cure.** This is a design tradeoff. Shareable magnets are great for reach but often produce diluted lead quality. Either accept the dilution and have a long path to qualification, or design the magnet to be less shareable but more audience-specific. + +--- + +## "We tried 12 different titles; conversion rate did not move." + +**The diagnosis.** Title testing without addressing the underlying audience-fit. The title is the surface; the audience-fit is the substance. If the substance is wrong, no title fixes it. + +**The cure.** Step back from title testing. Apply the audience-fit qualification (`references/audience-fit-qualification.md`). The title can amplify a strong audience-fit; it cannot create one. + +--- + +## "The magnet's references are stale and conversion is dropping." + +**The diagnosis.** Magnet decay. Screenshots, statistics, tooling references go out of date. The reader notices and engagement drops. + +**The cure.** Maintenance discipline (`references/lead-magnet-decision-criteria.md`, "When to retire a magnet"). Quarterly review for active magnets. Update or retire when references decay. + +--- + +## "We have a great magnet; the landing page does not convert." + +**The diagnosis.** The magnet is strong but the landing page (which is `landing-page-copy`'s domain) does not preview the value, frame the audience, or close the visitor. + +**The cure.** Apply landing-page-copy discipline. Show pages from inside the magnet. Frame the audience explicitly. Make the conversion action obvious and the friction minimal. + +--- + +## "The magnet got featured in [a major newsletter]; we lost the signal we built." + +**The diagnosis.** A traffic spike from a misaligned audience can dilute the qualified-lead-rate metric. The featured audience may not match the brand's offer. + +**The cure.** Distinguish "qualified subscriber" from "any subscriber" in the metric. The traffic spike grew the list; the qualified list grew less. The signal is intact; the metric needs disaggregation. + +--- + +## "We cannot keep the sequence content fresh." + +**The diagnosis.** The sequence's content needs ongoing maintenance. The team did not budget for it. + +**The cure.** Either reduce the sequence to evergreen content the team can sustain, or accept the maintenance cost as part of the magnet's true cost. Quarterly review of every active sequence (`references/delivery-and-follow-up-sequences.md`, "The maintenance discipline"). + +--- + +## "The magnet had great reviews; the lead-quality metric is mediocre." + +**The diagnosis.** Reviews are signal about the resource's quality. Lead quality is signal about the audience-fit. The two are different. A great resource for the wrong audience produces good reviews and mediocre lead quality. + +**The cure.** Audience-fit qualification (`references/audience-fit-qualification.md`). The magnet may need a tighter filter at the title and topic level, even if the resource itself is strong. + +--- + +## "We built a magnet for our PMM team's pet topic; nobody downloaded." + +**The diagnosis.** Vanity-magnet pattern. The topic was chosen for internal interest, not audience need. + +**The cure.** Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. + +--- + +## "The team ships magnets every quarter; conversion rate is the only metric we track." + +**The diagnosis.** Single-metric tracking misses lead quality, sequence engagement, downstream conversion, and retention. The conversion rate can look fine while the broader signal is weak. + +**The cure.** Multi-metric tracking. Conversion rate, qualified-lead rate, sequence engagement, downstream conversion, and unsubscribe rate together tell the story. Single-metric tracking misleads. + +--- + +## The pattern across failures + +Most lead magnet failures fall into one of three patterns. + +**Pattern 1: The magnet does not deliver value.** Thin-bait, kitchen-sink, undelivered-promise. The fix is to strengthen or kill the magnet. + +**Pattern 2: The magnet attracts the wrong audience.** Everyone-magnet, viral-but-misaligned, vanity-magnet. The fix is to tighten the filter or reframe the audience. + +**Pattern 3: The relationship after the download fails.** Orphan-magnet, sequence-too-short, misaligned-offer, follow-up-spam. The fix is to design the sequence with as much care as the magnet itself. + +The metric pattern: lead magnet failures often look fine on the conversion rate. The signal is in the lead quality, the sequence engagement, and the downstream conversion. Programs that track only the conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, relationship). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md b/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md new file mode 100644 index 0000000..1354ac6 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md @@ -0,0 +1,188 @@ +# Delivery and follow-up sequences + +Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. The sequence is the magnet's second act; without it, the magnet is one transaction. + +A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams that build the magnet but skip the sequence capture emails that go cold. + +--- + +## The delivery moment + +The reader fills the form and expects the resource immediately. The first email confirms the moment. + +**What the delivery email should do.** + +- Deliver the asset directly (link, attachment, or in-line content). The reader did not opt in to wait. +- Confirm the audience-fit signal. Acknowledge what the reader is here for. +- Set up the next email. "I will send you [related artifact] tomorrow" creates a hook for the next touchpoint. +- Avoid friction. No double opt-in unless required by jurisdiction. No survey-before-asset. The reader gets the resource first. + +**What the delivery email should NOT do.** + +- Make an offer. The reader has not yet experienced the magnet's value; offering anything is premature. +- Bury the asset. The link or attachment should be near the top, not after three paragraphs of brand-positioning. +- Apologize for the email. "Thanks for downloading, here is your resource" without filler is honest. + +**Delivery delay risk.** Delays of more than 5 minutes break the moment. Manual review, scheduled sends, or batch processing all introduce delay. Automate the delivery to minimize lag. + +--- + +## The first 7 days arc + +The reader is most engaged in the days right after download. The sequence should make use of that window. + +**Day 0: Delivery.** Asset in hand. The reader can act on the magnet immediately. + +**Day 1-2: Application help.** A follow-up that helps the reader apply the resource. "The 3 things people miss when implementing the [magnet]" or "the worked example we use ourselves." Adds value to the magnet without yet pitching anything. + +**Day 3-4: Adjacent value.** A related artifact, case study, or insight that extends the magnet's value. Reinforces the brand as a source of useful resources. + +**Day 5-7: Soft introduction to the brand.** Who the team is, what they work on, what kinds of problems they solve. Soft framing of the next step (newsletter signup, related product, demo). + +**The 7-day arc principle.** Every email in the first 7 days should add value, not extract. The relationship is being built; extraction breaks the trust the magnet earned. + +--- + +## The medium-term sequence + +Days 8-30, the sequence transitions from "value-add" to "ongoing relationship." + +**The transition options.** + +- **Newsletter signup.** Move the subscriber to the regular newsletter cadence. The relationship continues at the brand's normal pace. +- **Related-content rotation.** A series of additional resources, case studies, or insights related to the magnet's topic. The subscriber stays engaged in the topic area. +- **Soft offer for the adjacent product or service.** A demo invitation, a trial signup, a case study of a similar customer. The offer matches the audience the magnet attracted. + +**The honest offer principle.** The offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course. The audience signal would be wasted. + +**The hard-sell trap.** Some sequences pivot too early to hard selling, before the reader has had time to recognize the value. The early hard sell breaks trust. The discipline is to earn the right to pitch through demonstrated value first. + +--- + +## The offer-magnet alignment + +The offer that follows the magnet must match the audience the magnet attracted. + +**Worked example: aligned offer.** + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: SaaS founders, growth marketers, and PMs running SaaS funnels. +The offer: a B2B SaaS lifecycle email tool with a 14-day trial. + +The audience the magnet attracted is the audience the offer serves. The conversion to trial is high relative to baseline. + +**Worked example: misaligned offer.** + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: as above. +The offer: a marketing analytics platform aimed at enterprise marketing teams. + +The audience the magnet attracted is not the audience the offer serves. The conversion to demo is near zero. The audience signal was wasted. + +**The alignment discipline.** Before designing the magnet, identify the offer the magnet's audience will be pitched. If the offer does not exist or does not match, redesign the magnet (or the offer) before shipping. + +--- + +## The clean opt-out + +A reader who unsubscribes from the magnet sequence is not a failure. They are a clean filter. + +**The principle.** The list quality stays higher when the unfit subscribers leave on their own. A subscriber who is not the right audience for the offer is a subscriber whose engagement will be low; their unsubscribe is signal, not loss. + +**The mechanics.** + +- Make unsubscribe easy. One-click is honest; multi-step is friction the brand pays for in trust. +- Do not interrogate on the way out. "We are sorry to see you go, please answer 3 questions" is friction. +- Acknowledge the unsubscribe gracefully. The reader was a subscriber; they should leave with the brand intact. + +**The unsubscribe-as-feedback loop.** High unsubscribe rates after specific emails signal that the email did not match the audience or the value proposition. The signal informs sequence revision. + +--- + +## Sequence cadence considerations + +How frequently to send. + +**Day 0-7: daily or every-other-day is honest.** The reader just downloaded; engagement is high; the sequence can use the window without feeling spammy. + +**Day 8-30: 2-4 emails per week is reasonable.** Frequency depends on the value being delivered; if each email adds value, higher frequency is sustained. + +**Day 30+: settle into the brand's normal cadence.** Newsletter weekly, monthly, or per-publication. Whatever the brand sustains. + +**Cadence-too-frequent risk.** Daily emails for 30+ days exhaust the reader. The unsubscribe rate climbs. + +**Cadence-too-infrequent risk.** Weekly cadence in the first 7 days lets the magnet's momentum fade. The reader downloads, applies, and forgets the brand. + +--- + +## Sequence-engagement measurement + +The sequence's metrics surface whether the magnet did its qualifying job. + +**Open rates.** The audience opens what is interesting to them. Low open rates after the first email signal audience mismatch or sequence-content mismatch. + +**Click-through rates.** Clicks signal interest in specific content or offers. Low click-through on the offer email signals offer-magnet misalignment. + +**Conversion to next step.** Trials, demos, purchases. The downstream metric that matters most. Low conversion despite high engagement signals offer mismatch or pricing-mismatch. + +**Unsubscribe rates.** A reasonable rate (2-5 percent over the first 30 days) is normal. Higher rates signal cadence mismatch or audience mismatch. + +The metrics together tell the story. The sequence either qualifies and converts the audience the magnet attracted, or it surfaces the mismatch the magnet missed. + +--- + +## When the sequence fails + +The sequence sends; engagement drops; conversion is low. The diagnosis often surfaces magnet-side failures. + +**Diagnosis: the magnet attracted the wrong audience.** The sequence's content is right for the audience the magnet was designed for, but the audience the magnet actually attracted is different. The fix is upstream: tighten the magnet's filter. + +**Diagnosis: the offer is misaligned.** The audience is right; the offer does not match. The fix is to change the offer (or the magnet, if the offer is fixed). + +**Diagnosis: the sequence is too long or too frequent.** Engagement starts strong and drops as fatigue sets in. The fix is to trim the sequence or space the emails. + +**Diagnosis: the sequence's value drops off.** The first emails added value; the later emails became repetitive or extractive. The fix is to redesign the later emails to continue adding value. + +**Diagnosis: the sequence's tone shifted.** The early emails were honest; the later emails became salesy. The fix is to restore the honest tone. + +The sequence is part of the magnet's design. Failures in the sequence often surface as conversion-rate or engagement metrics, but the fix is sometimes upstream in the magnet itself. + +--- + +## The maintenance discipline + +Sequences decay. Email links break, references go stale, offers change. + +**The maintenance cadence.** Quarterly review of every active sequence. Are links working? Are references current? Does the offer at the end still match the brand's current product or service? + +**Stale-sequence risk.** A subscriber who clicks a broken link or sees a reference to a discontinued product disengages immediately. The brand looks careless. + +**The retire decision.** Sequences for retired magnets should be retired. Subscribers acquired through the magnet should be moved to the appropriate ongoing sequence (newsletter or other). + +--- + +## Common sequence failures + +**No sequence.** The magnet ships; subscribers download; nothing follows. The list goes cold. + +**Sequence too short.** 2-3 emails and done. The relationship does not deepen. + +**Sequence too long.** 30+ emails over months. Subscribers fatigue. + +**Sequence pivots to hard sell too early.** The trust the magnet earned gets spent before the value has been demonstrated. + +**Offer misaligned.** Magnet attracts one audience; offer pitches another. + +**Stale references.** Links break; product names changed; case studies outdated. + +**Cadence mismatch.** Too frequent or too infrequent for the engagement the audience can sustain. + +--- + +## Methodology-level choices that stay in the public skill + +The delivery moment principles. The first-7-days arc. The medium-term transition. The offer-magnet alignment principle. The clean opt-out. Cadence considerations. Sequence-engagement measurement. Diagnostic patterns when the sequence fails. The maintenance discipline. + +## Implementation choices that stay internal + +Specific email copy for specific magnets. Specific sequence templates the team uses. Specific tooling for delivery automation, sequence platforms, and engagement measurement. The team's cadence baselines. Specific offer-design choices for specific products. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md b/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md new file mode 100644 index 0000000..97e7ce8 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md @@ -0,0 +1,245 @@ +# Format selection patterns + +Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +A great template often outperforms a mediocre ebook on the same topic. The format is half the design decision; the topic is the other half. + +--- + +## Templates + +A starting artifact the reader fills in or adapts. + +**Strengths.** + +- Immediate, concrete value. The reader produces a usable artifact in minutes. +- High perceived value because the artifact is practical. +- Strong audience signal: people who download templates are people who execute, not just consume. +- Sustainable production: a single template, well-designed, can serve thousands of downloads with minimal updating. + +**Weaknesses.** + +- Generic templates feel useless; the bar for "custom enough" is high. +- The format does not work when the deliverable is non-standardizable (the reader's context varies too much for a template to fit). +- Distribution can be tricky if the template requires specific tools (a Notion template is unusable to teams not on Notion). + +**Audience-fit signals.** + +- Strong fit: practitioners who produce specific deliverables (specs, briefs, plans, decks, sequences). +- Weak fit: strategic readers who want frameworks rather than artifacts. + +**Conversion-rate baseline.** Templates often convert 3-12 percent on landing pages with reasonable traffic-fit. The high end is for templates that signal exceptional specificity in the title. + +**Production overhead.** Moderate. A polished template often takes 8-20 hours including design, instructions, and worked example. + +--- + +## Checklists + +A sequence of items to verify or complete. + +**Strengths.** + +- Fast to consume, fast to apply. Reader gets value in 10-20 minutes. +- Format signals "you can use this today." +- Strong for processes where the gap is comprehensiveness rather than direction (the reader knows what to do; the checklist verifies they did not miss steps). + +**Weaknesses.** + +- Easy to make thin. A 12-item generic checklist reads as marketing rather than a working tool. +- Sequence matters; an unordered checklist on a process is less useful than the same items in workflow order. +- Limited topic range; checklists fit verification-style tasks, not strategy-style decisions. + +**Audience-fit signals.** + +- Strong fit: practitioners executing known processes who need verification (launch checklists, audit checklists, onboarding checklists). +- Weak fit: strategic decisions where each situation differs. + +**Conversion-rate baseline.** Strong checklists convert 5-15 percent. The format signals quick wins, which lifts conversion. + +**Production overhead.** Low to moderate. 4-12 hours including design and field-testing. + +--- + +## Swipe files + +A curated collection of examples (subject lines, headlines, ad copy, design references, email templates). + +**Strengths.** + +- High perceived value. The reader gets a body of work to study and adapt. +- Strong for audiences who learn from examples rather than instruction. +- Often shareable; readers tell peers about a strong swipe file. + +**Weaknesses.** + +- Requires curation discipline; a 200-item swipe file with no commentary is less useful than 30 swipes with curation notes. +- Decays faster than templates or frameworks; swipes go stale as conventions change. +- Attribution matters; uncredited swipes can be perceived as theft. + +**Audience-fit signals.** + +- Strong fit: copywriters, designers, marketers, and creators who need inspiration plus example. +- Weak fit: audiences seeking instruction or process. + +**Conversion-rate baseline.** Strong swipe files convert 4-12 percent. + +**Production overhead.** Moderate to high. 12-30 hours including curation, attribution, and commentary. + +--- + +## Mini-courses + +A multi-part email or video sequence delivering structured learning. + +**Strengths.** + +- Multiple touchpoints, which deepens the relationship. +- Sequential structure can take the reader from "novice" to "competent" on a topic. +- The course format can charge implicit time investment, which qualifies the lead as serious. + +**Weaknesses.** + +- Each lesson must stand on its own; "the answer is in lesson 4" loses the reader by lesson 2. +- Production overhead is significant. +- Completion rates are honestly low (often 10-30 percent finish), which limits the cumulative value delivered. + +**Audience-fit signals.** + +- Strong fit: audiences willing to invest sequential attention and seeking structured learning. +- Weak fit: audiences who want quick wins or specific artifacts. + +**Conversion-rate baseline.** 3-10 percent. Lower than templates or checklists because the perceived time commitment is higher. + +**Production overhead.** High. 30-100 hours for a 5-7 lesson course depending on format. + +--- + +## Free tools (calculators, quizzes, generators, configurators) + +Interactive web tools that produce a personalized result. + +**Strengths.** + +- Highest perceived value among magnet types when the tool genuinely helps. +- Personalization makes the result feel custom. +- Often shareable; results can drive earned traffic. +- Lead-quality signal embedded in the inputs (a calculator's inputs reveal the lead's situation). + +**Weaknesses.** + +- Build cost is significant; a quality tool is engineering work, not just copy. +- Maintenance is ongoing as inputs and methodology evolve. +- Easy to fall into vanity-tool patterns (inputs and outputs that do not produce a meaningful result). + +**Audience-fit signals.** + +- Strong fit: audiences with concrete decisions or calculations the tool can address. +- Weak fit: topics that do not naturally produce a personalized output. + +**Conversion-rate baseline.** Wide range, 5-25 percent depending on tool quality and audience-fit. + +**Production overhead.** High. 40-150+ hours for a polished tool. + +Detail in `calculator-design` and `quiz-and-assessment-design`. + +--- + +## Ebooks + +Long-form treatment of a topic. + +**Strengths.** + +- Comprehensive coverage when comprehensiveness matters. +- Authority signal; a well-produced ebook positions the brand as a definitive source. +- Bookmarkable; readers may return over time. + +**Weaknesses.** + +- Easy to default to ebook for topics that would have been better as a checklist or template. +- Completion rates are honestly low; many ebooks are downloaded and never read. +- Production overhead and design overhead are high. +- The format invites kitchen-sink-resource patterns ("we have to cover everything"). + +**Audience-fit signals.** + +- Strong fit: audiences researching a complex decision who want depth. +- Weak fit: practitioners who want immediate-use artifacts. + +**Conversion-rate baseline.** 2-8 percent. Lower than other formats because the perceived time investment to read is high and many readers know they will not finish. + +**Production overhead.** High. 40-120 hours for a 30-50 page ebook. + +--- + +## Video series + +Sequential video content delivered behind a gate. + +**Strengths.** + +- Strong for topics that benefit from demonstration (UI walkthroughs, design critique, code review). +- Personality and brand presence land more directly in video than in text. +- Audiences who prefer video learning are well-served. + +**Weaknesses.** + +- Production overhead is high; video quality has to match the brand it represents. +- Audiences who do not consume video at the moment of magnet delivery underuse the resource. +- Updates require re-recording, which is more expensive than updating text. + +**Audience-fit signals.** + +- Strong fit: audiences who consume video for learning and have time to watch. +- Weak fit: practitioners who want skim-and-apply content. + +**Conversion-rate baseline.** 3-9 percent. + +**Production overhead.** Very high. 50-200+ hours for a 4-6 video series at quality. + +--- + +## Hybrid formats + +Some magnets combine formats. A template plus a worked-example video. A checklist plus a 5-day email mini-course that walks through it. + +**Strengths.** + +- Multiple consumption modes serve broader audience preferences. +- The hybrid often outperforms either format alone. + +**Weaknesses.** + +- Production overhead compounds. +- Risk of confusing the reader about what they are getting. + +**When hybrids work.** When the second format genuinely extends the first. A template that includes a video walkthrough adds value; a template that includes a 60-page ebook the reader did not ask for adds bloat. + +--- + +## Format-decision frame + +When choosing the format for a specific topic and audience. + +**Step 1: Audience consumption mode.** How does this audience consume content? Do they read long-form? Skim PDFs? Watch video? Use templates? + +**Step 2: Topic shape.** Does the topic naturally produce an artifact (template), a verification (checklist), inspiration (swipe), instruction (course), a calculation (tool), depth (ebook), or demonstration (video)? + +**Step 3: Production capacity.** What can the team sustain? A great template the team can ship beats a mediocre ebook the team is straining to finish. + +**Step 4: Conversion-rate target.** Templates and checklists generally convert higher; ebooks and courses convert lower. The expected conversion rate informs the topic-volume calculation. + +**Step 5: Maintenance overhead.** Some formats decay faster than others. Swipes go stale; templates with software-specific instructions decay; videos with UI screenshots decay. Choose formats the team can maintain. + +The right format is the one that fits the topic, the audience, the team's capacity, and the maintenance reality. There is no universal best format; there is only the format that fits the situation. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format strengths, weaknesses, audience-fit signals, conversion-rate baselines, and production overhead. The hybrid format consideration. The format-decision frame. The principle that there is no universal best format. + +## Implementation choices that stay internal + +Specific format choices for specific topics in the team's catalog. Specific production benchmarks for the team's capacity. Specific tooling for each format. The team's audit baselines for conversion rate and lead quality. These vary by team, topic, and audience. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md b/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md new file mode 100644 index 0000000..b781609 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md @@ -0,0 +1,196 @@ +# Format-specific quality gates + +Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. Each format has gates specific to that format. A great template fails different tests than a great mini-course. + +The quality gates exist because thin-bait can hide in any format. The gates make hiding harder. Apply them before launch; if the magnet fails a gate, redesign before shipping. + +--- + +## Template gates + +A template earns the email when the reader produces a usable artifact in minimal time. + +**Gate 1: Time-to-usable-artifact.** Can the reader produce a usable artifact in under 30 minutes? If the template requires hours of customization to be useful, the format is failing. + +**Gate 2: Specificity of prompts.** Are the prompts specific enough to feel custom? "Insert your unique value proposition here" is too generic. "What is the specific outcome your customer needs in the first week" is specific enough to guide the reader. + +**Gate 3: Adaptability across the segment.** Is the template adaptable across the segment of the audience, or rigidly bound to one situation? A template for "B2B SaaS pricing one-pager" should work across multiple B2B SaaS situations; a template that only fits one company's exact circumstances is too rigid. + +**Gate 4: Worked example included.** Does the template include a worked example showing what a completed version looks like? Worked examples reduce the time-to-usable-artifact and signal that the template was real-tested. + +**Gate 5: Tooling honesty.** If the template requires specific tools (a Notion template, a Figma file, an Airtable base), is the tool dependency honestly disclosed in the title? Surprise dependencies frustrate readers who do not have the tool. + +--- + +## Checklist gates + +A checklist earns the email when each item is actionable today. + +**Gate 1: Each item actionable today.** No "consult your team about X" or "decide on the strategy for Y." Each item should be something the reader can verify or complete. + +**Gate 2: Workflow order.** Does the checklist sequence reflect actual workflow order? An out-of-order checklist forces the reader to mentally re-sort, which costs the speed advantage the format promised. + +**Gate 3: Scope discipline.** Is the checklist scoped narrowly enough to feel comprehensive within scope? "Pre-launch checklist for B2B SaaS" is narrower than "Pre-launch checklist for any product" and produces a tighter, more useful resource. + +**Gate 4: Item count sanity.** Strong checklists are usually 12-30 items. Fewer than 8 items often signals thin-bait; more than 50 often signals that the format should have been an ebook or playbook instead. + +**Gate 5: Verification cues.** Does each item include enough cue for the reader to know they actually verified it? "Email sequence tested in production" is verifiable; "Email sequence reviewed" is not. + +--- + +## Swipe file gates + +A swipe file earns the email when the swipes are real, attributed, and curated. + +**Gate 1: Real swipes.** The swipes should be examples actually used in the wild, not invented for the magnet. Real swipes have specificity that invented ones lack. + +**Gate 2: Attribution where possible.** Each swipe attributed to source where the source is public. Unattributed swipes can read as theft. + +**Gate 3: Currency.** Are the swipes current? Swipes from 5 years ago may have specific dating cues that signal staleness. Periodic refresh is part of the swipe-file discipline. + +**Gate 4: Curation visible.** Is the curation visible? The reader can see why each swipe is included? A 200-swipe dump with no commentary is less useful than 30 curated swipes with notes on why each was included. + +**Gate 5: Categorization.** Are the swipes categorized by use case (subject lines, headlines, ad copy, design references)? A flat list of unsorted swipes is harder to extract value from than a categorized collection. + +--- + +## Mini-course gates + +A mini-course earns the email when each lesson stands on its own and the cumulative arc adds up. + +**Gate 1: Each lesson standalone.** A reader who only completes lesson 1 should still extract value. "You will learn the answer in lesson 4" loses readers who do not make it to lesson 4. + +**Gate 2: Cumulative time honesty.** Is the total time commitment honestly disclosed in the title or landing page? "5-day course" should mean 5 days of meaningful engagement, not 5 days of one paragraph emails. + +**Gate 3: Production consistency.** Are all lessons at consistent production quality? Courses that decay in production quality across lessons signal that the team ran out of capacity. + +**Gate 4: Clear next step at end.** Does the course end with a clear next step (related product, related resource, ongoing community)? "Thanks for taking the course" without a next step is a missed opportunity. + +**Gate 5: Completion tracking.** Does the course include progress markers ("Lesson 3 of 5") so the reader knows where they are? Lack of progress markers correlates with low completion. + +**Gate 6: Each lesson's central insight.** Can the team articulate the central insight of each lesson in one sentence? Lessons without a central insight are filler. + +--- + +## Free tool gates + +Free tools (calculators, quizzes, generators) earn the email when the result is meaningful. + +**Gate 1: Meaningful result.** The output should help the reader make a decision or understand a situation. "Your score is 73" without interpretation is meaningless. Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Gate 2: Calculation transparency or methodology disclosure.** Detail in `calculator-design`. + +**Gate 3: Email-capture honesty.** Detail in `calculator-design`. + +--- + +## Ebook gates + +An ebook earns the email when the resource produces value for readers who do not finish. + +**Gate 1: Navigability.** Table of contents, page numbers, summary boxes. A reader who jumps to chapter 3 should be able to extract value without reading 1 and 2. + +**Gate 2: Production quality consistent with the brand.** A poorly-produced ebook (typos, inconsistent formatting, low-resolution images) signals that the brand did not invest. The reader's expectation of the brand drops. + +**Gate 3: Length honesty.** Is the page count honestly disclosed? "30-page guide" should mean 30 pages of substance, not 30 pages including 12 of brand-positioning. + +**Gate 4: Chapter summaries.** Each chapter ends with a summary that lets a reader who skimmed extract the key insight. Summaries reduce the cost of skimming, which raises the value the reader gets even if they do not finish. + +**Gate 5: First-chapter discipline.** The first chapter should deliver value, not warm up. Author bio and brand-positioning belong in the appendix or the about-the-author note, not chapter 1. + +--- + +## Video series gates + +A video series earns the email when production quality and consumption shape match the audience. + +**Gate 1: Production quality consistent.** Audio clear, video stable, lighting reasonable. Production quality the brand can sustain across all videos. + +**Gate 2: Runtime honesty.** Total runtime disclosed honestly. "5-video series" with one video 30 seconds and another 45 minutes is dishonest. + +**Gate 3: Audio-first viability.** Many video viewers consume in audio-only contexts (commutes, exercise). Does the video work as audio? If the video has heavy on-screen reading required, the audio-only viewer loses the value. + +**Gate 4: Transcripts available.** A transcript reaches the audience that prefers reading and improves accessibility. + +**Gate 5: Each video standalone.** Same as the mini-course gate. A viewer who only watches video 1 should extract value. + +--- + +## Cross-format gates + +Some gates apply regardless of format. + +**Gate A: The "would they pay for this" test.** Detail in `references/would-they-pay-for-this-test.md`. + +**Gate B: Audience-fit signal.** Does the magnet attract the audience the brand serves? Detail in `references/audience-fit-qualification.md`. + +**Gate C: Title-content alignment.** Does the magnet deliver on the title's specific promise? Detail in `references/title-and-presentation-discipline.md`. + +**Gate D: First-impression quality.** Whatever the format, does the first impression (first page, first lesson, first calculator output) deliver something useful immediately? + +**Gate E: Update cadence.** Is the magnet updated when references go stale, screenshots change, or methodology evolves? Stale magnets degrade the brand. + +--- + +## When a magnet fails a gate + +The magnet fails a gate. Now what. + +**Option 1: Fix the magnet.** Add the worked example, narrow the scope, improve the production quality. Often the right answer. + +**Option 2: Change the format.** Sometimes the topic is wrong for the chosen format. A topic that fails ebook gates might pass checklist gates. + +**Option 3: Do not ship.** Some magnets should not exist. Killing the magnet at the gate stage is honest; shipping a failing magnet costs more than killing it. + +The team's response to gate failures is the discipline marker. Strong programs fix or kill at the gate; weak programs ship despite failed gates and accept the downstream cost. + +--- + +## The gate review process + +Gates are most useful when applied as a structured pre-launch review. + +**The review.** + +- Identify the format. +- List the gates for that format (plus the cross-format gates). +- For each gate, score pass / fail / marginal. +- Marginal gates warrant strengthening before launch. +- Failed gates require redesign before launch. + +**Who reviews.** + +- The magnet's author should self-review. +- A second person (outside the magnet's authoring team) should also review. Outside-in honesty catches what the authoring team rationalizes. + +**Document the review.** A short note on which gates passed and which were strengthened. Useful for future magnet design and team learning. + +--- + +## Common gate failures + +**Templates.** Generic prompts; no worked example; tool dependency hidden. + +**Checklists.** Items that are not actionable; out-of-workflow order; thin item count. + +**Swipe files.** Invented swipes; no attribution; uncategorized dump. + +**Mini-courses.** Lessons that depend on each other; production quality decays; no clear next step. + +**Free tools.** Vanity outputs without interpretation; misleading methodology; manipulative gates. + +**Ebooks.** Poor navigability; production quality below brand standard; length padded with brand-positioning. + +**Video series.** Inconsistent production; no transcripts; long runtime hidden. + +The pattern across formats: the gates surface the failures that conversion-rate metrics hide. A magnet can convert at high rates while failing the gates; the gate failures show up downstream as poor lead quality and poor sequence engagement. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format quality gates with specific tests. Cross-format gates. The gate review process. The decision tree when a magnet fails a gate. Common gate failures. + +## Implementation choices that stay internal + +Specific gate-scoring conventions for the team. Specific review processes and reviewers. Specific worked-example libraries. Specific production-quality benchmarks. Specific update-cadence calendars. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md new file mode 100644 index 0000000..e2d1f8f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md @@ -0,0 +1,197 @@ +# Lead magnet anti-patterns + +The patterns that look like lead magnets but do not behave like them. Anti-patterns are easy to ship and easy to celebrate; the cost shows up in lead quality, sequence engagement, and brand trust over time. + +--- + +## The thin-bait magnet + +The pattern. A vague-headline PDF that contains 200 words of fluff behind an email gate. + +The signal. Conversion-rate metric looks fine; unsubscribe rate after delivery is high; subsequent email open rates collapse. + +The cost. Every subscriber acquired through thin-bait costs more than they appear to. Reduced sender reputation, reduced list trust, and the brand reputation as a source of bait all compound. + +The cure. Apply the "would they pay for this" test before launch. Strengthen the resource until it would be worth paying for. If it cannot be strengthened, do not ship. + +--- + +## The kitchen-sink-resource magnet + +The pattern. An 80-page "Ultimate Guide" that covers everything anyone could want about the topic. Nothing the reader needs RIGHT NOW. + +The signal. Strong conversion rate (the title sounds comprehensive); low usage rate (the resource is too long to consume); no traceable downstream conversion. + +The cost. The magnet does not produce the moment of "I needed this and got it." The relationship never starts. Subscribers stay on the list out of inertia; future emails get ignored. + +The cure. Narrow the topic until the magnet addresses one specific problem. The 80-page guide becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## The undelivered-promise magnet + +The pattern. A title that promises a specific outcome ("the framework that doubled our conversion rate") followed by a magnet that delivers something less specific ("here is general advice on conversion rate optimization"). + +The signal. Reader downloads, opens, encounters the gap, and unsubscribes (or stays subscribed but disengages). + +The cost. The brand becomes the source of the gap. Future titles by the same brand are less trusted; conversion rates on future magnets decay. + +The cure. Either deliver on the title's promise (which often requires strengthening the magnet) or revise the title to be honest about what the magnet contains. + +--- + +## The bait-and-switch magnet + +The pattern. The magnet promises one resource and delivers another. "Free template" that turns out to be a 10-email mini-course; "calculator" that turns out to be a contact-sales form. + +The signal. Reader engagement collapses; the brand earns "deceptive" descriptors in support tickets and social mentions. + +The cost. Trust damage that extends beyond the magnet. The brand becomes harder to trust on any future offering. + +The cure. Match the title to what the magnet actually delivers. If the team wants to deliver a mini-course, title the magnet as a mini-course. If the team wants to gate a sales form, do not call it a calculator. + +--- + +## The orphan-magnet (no sequence) + +The pattern. The magnet ships; subscribers download; nothing follows. No sequence, no offer, no relationship-building. + +The signal. List grows; engagement on subsequent emails (when they happen) is low; downstream conversion to anything is near zero. + +The cost. The list is a list of cold contacts. The brand has the email but not the relationship. + +The cure. Design the sequence before shipping the magnet. The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## The misaligned-offer magnet + +The pattern. The magnet attracts one audience; the follow-up offer pitches a different one. Magnet on B2B onboarding; offer for consumer-app courses. + +The signal. Magnet conversion is fine; offer conversion is near zero; the audience signal the magnet captured was wasted. + +The cost. The team builds the magnet, runs the sequence, and gets no downstream conversion. The investment does not pay back. + +The cure. Align the offer to the audience the magnet attracts. If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## The dead-magnet portfolio + +The pattern. The team has shipped 12 magnets over 3 years. 3 still convert; 9 are dead but still on the site. Maintenance attention spreads thin; nothing is great. + +The signal. Aggregate conversion-rate metrics look fine; per-magnet metrics show 75 percent of the portfolio underperforming. + +The cost. Maintenance overhead on dead magnets; brand looks cluttered; team capacity diluted across underperformers. + +The cure. Audit the portfolio. Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## The everyone-magnet + +The pattern. A magnet titled to attract "everyone in marketing" or "any founder." Generic by design. + +The signal. Conversion rate may be high; lead quality is low; downstream engagement is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly because the audience is not aligned to any specific offer. + +The cure. Narrow the magnet's audience. Specific magnets attract specific audiences who convert well to specific offers. The everyone-magnet is the wrong tool for any specific goal. + +--- + +## The vanity-magnet + +The pattern. A magnet built because the team wanted to ship a magnet, not because the audience needed one. The topic was chosen for "we should write about this" rather than "the audience would download this." + +The signal. Low conversion rate; few signs that the audience cares about the topic; the magnet collects dust. + +The cost. Sunk effort; team morale drop; the team learns that magnets do not work (when in fact this specific magnet did not work because the topic was wrong). + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. Vanity-magnets often fail at the topic-validation step. + +--- + +## The follow-up-spam magnet + +The pattern. The magnet ships; the sequence follows; the sequence is 30 emails over 14 days, all of them sales-driven. + +The signal. Strong unsubscribe rate; high spam-complaint rate; the brand earns "spammy" descriptors. + +The cost. Sender reputation damage that affects all future emails. The brand's email program degrades. + +The cure. Redesign the sequence to add value rather than extract it. Cadence should match the audience's tolerance; content should be honest. + +--- + +## The interrogation-form magnet + +The pattern. The form before the magnet asks for 12 fields (name, company, role, company size, current tools, biggest challenge, etc.) before delivering the resource. + +The signal. Conversion rate collapses; the audience self-selects out at the form. + +The cost. The magnet's reach drops dramatically. The team gets rich data on the few who convert; the team loses the broader audience the magnet could have served. + +The cure. Ask only for what is needed (often just an email). Capture additional data later in the sequence as the relationship deepens. + +--- + +## The hidden-cost magnet + +The pattern. The magnet promises a free resource; the resource includes upselling, integrated ads, or links to paid offerings on every page. + +The signal. Reader downloads expecting a resource; experiences the upsells as bait; engagement collapses. + +The cost. The magnet is perceived as commercial-disguised-as-resource. Trust damages. + +The cure. Keep the magnet substantive. Soft offers can appear at the end or in the follow-up sequence; the body of the magnet should deliver the promised value. + +--- + +## The unfindable-asset magnet + +The pattern. The magnet is delivered as a link to a Google Drive folder, a Notion page, or some other location that the reader has to navigate to find the actual asset. The asset is buried 2-3 clicks away. + +The signal. Reader downloads the email link; cannot find the asset; abandons. + +The cost. The download metric counts but the consumption metric collapses. The reader's experience is friction. + +The cure. Deliver the asset directly (attachment or in-line link). Click count from email to asset should be 1. + +--- + +## The team-pat-on-the-back magnet + +The pattern. The magnet is content the team wanted to make (a thought-leadership piece, a brand statement, a manifesto) gated behind a form. The audience may not specifically want it. + +The signal. Conversion rate underwhelms; the team rationalizes ("brand-building is hard to measure"); the magnet does not produce relationship signal. + +The cost. The team builds the wrong thing for the audience and learns the wrong lesson. + +The cure. Design magnets for the audience's needs, not for the team's preferences. Brand-building content can exist as ungated content; gated content should be magnet-shaped. + +--- + +## How to detect anti-patterns in the portfolio + +Audit cadence. Quarterly review of every active magnet, looking specifically for these anti-patterns. + +**Audit questions per magnet.** + +- Is the conversion rate consistent with the audience-fit, or is it suspiciously high (suggesting thin-bait or everyone-magnet)? +- Is the lead quality consistent with the audience the magnet was designed for, or is it diluted (suggesting weak filters)? +- Does the sequence's engagement match the magnet's promise, or is there a drop (suggesting an undelivered-promise or misaligned-offer)? +- Is the asset usable in the form delivered, or is it hard to find (suggesting unfindable-asset)? +- Does the magnet have a sequence at all, or is it orphaned? + +**The retire decision.** Anti-pattern magnets often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-magnet plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md new file mode 100644 index 0000000..9fd5b1f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md @@ -0,0 +1,137 @@ +# Lead magnet decision criteria + +When a lead magnet is the right investment for the funnel and when it is not. The conditions that make magnets worth the build, and the funnels where the magnet is friction the audience does not need. + +A lead magnet is a long-lived asset. The build cost is upfront; the conversion lift compounds across visitors. But the long-lived asset only compounds if the audience and the goal warrant it. Magnets built without the conditions in place become dead PDFs in CMS folders. + +--- + +## When a magnet earns the build + +Five conditions that, when present, make a magnet a strong investment. + +**Traffic exists but conversion is missing.** The audience reaches the site (organic, paid, referral, social) but does not convert to the primary action (signup, purchase, demo). The magnet fills the gap between "interested enough to land" and "ready to commit." Without traffic, the magnet has no audience; without a conversion gap, the magnet adds friction. + +**The consideration cycle is long.** B2B SaaS, high-ticket services, and considered consumer purchases share the trait that buyers research over weeks or months before committing. The list-building motion lets the brand stay present across the consideration window. Short-cycle purchases (impulse ecommerce, low-stakes signups) often do not need a magnet between visitor and conversion. + +**The audience has a specific, immediate problem the magnet can address.** Generic problems do not focus a magnet. "Improve my marketing" is too broad; "the email sequence I send to trial signups who go cold" is specific enough to focus a checklist or template. The magnet lives or dies on specificity. + +**The team can commit to the follow-up sequence.** A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams without sequence-building capacity should fix that before building the magnet. + +**The success metric is defined.** What does "the magnet works" look like? List growth at quality, lead-quality signal, conversion to the next step, downstream revenue attribution. Without a defined success metric, the magnet's results cannot be evaluated, and underperformers do not get retired. + +When all five are present, the magnet is a strong investment. When two or fewer are present, the magnet is probably the wrong tool. + +--- + +## When a magnet does NOT earn the build + +Funnels where the magnet adds friction the audience does not need. + +**Frictionless conversion already exists.** A SaaS with a 14-day free trial, no credit card required, may not need a magnet between the visitor and the trial. The magnet adds a step where the trial alone would convert. + +**The next step is a sales call or demo.** When the goal is a booked call, design the call-booking flow rather than a magnet that delays the call. The magnet might still serve a separate audience (top-of-funnel readers not ready for a call), but the primary funnel is the call. + +**The audience is too small for list-building economics.** Building, hosting, and maintaining a magnet (plus the sequence) costs ongoing time. For very small target audiences, direct outreach or a simpler conversion path may be more efficient. + +**The team has no sequence capacity.** If the team cannot design and maintain the post-download sequence, the magnet captures emails that decay into unsubscribes. The list grows on paper and shrinks in trust. + +**No specific topic that focuses a magnet.** When the topic is "we do everything," no single magnet focuses. The honest move is to narrow the audience first (which produces the topic that focuses) rather than build a generic magnet. + +**The current funnel is already converting at a rate the magnet would not improve.** If the visitor-to-customer rate is already strong, the magnet adds steps without lifting the outcome. + +The honest assessment matters more than the default. "Should we have a lead magnet" is not the question. "Is the magnet the right investment for this audience and goal" is. + +--- + +## The opportunity-cost frame + +A magnet's cost is not just the build. It is the build plus the maintenance plus the sequence plus the team attention diverted from other work. + +**The build cost.** Format selection, copy, design, asset production, landing page, form integration, delivery automation. A meaningful magnet often takes 20-80 hours from scoping to launch. + +**The maintenance cost.** Magnets decay. References go stale, screenshots get outdated, the topic moves on. Maintenance often runs 2-4 hours per quarter per active magnet. + +**The sequence cost.** The post-download sequence is itself a build. 5-12 emails, copy and integration. 10-30 hours upfront. + +**The opportunity cost.** What else could the team have built with that time? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The magnet's success has to clear the bar of those alternatives. + +The decision frame. The magnet earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The audience precondition + +Without an audience, the magnet has no one to convert. + +The chicken-and-egg pattern. Teams sometimes build magnets to "drive traffic." That works only if the magnet itself is shareable enough to attract traffic (rare) or if the team has a separate plan to drive traffic to the magnet's landing page. + +The realistic frame. The magnet converts traffic that already exists. Driving traffic is a separate problem (covered by `content-distribution`, paid media, SEO, and partnerships). Build the magnet for the traffic that already lands; do not expect the magnet to do the traffic-driving work. + +The exception. Genuinely shareable magnets (free tools, viral calculators, definitive industry reports) can drive their own traffic. But these are the minority of magnets, and the design effort to reach shareability is significant. + +--- + +## The portfolio frame + +A team often has multiple magnets, not one. The portfolio earns more thought than any individual magnet. + +**The audience-segmentation frame.** Different magnets for different audience segments. The B2B SaaS founder magnet does not need to also serve the consumer marketer; segment-specific magnets often outperform generic ones. + +**The funnel-stage frame.** Magnets for top-of-funnel readers, magnets for middle-of-funnel evaluators, magnets for bottom-of-funnel near-buyers. Each stage has different value to deliver and different next-step offers. + +**The maintenance frame.** A portfolio of 4-6 active magnets is often more sustainable than 12 mediocre ones. Periodic audit retires the underperformers and frees capacity for the strong magnets. + +**The cross-magnet promotion frame.** The follow-up sequence from one magnet can promote another. Subscribers who downloaded the templates checklist may also want the pricing one-pager. + +The portfolio approach amplifies the value of each strong magnet and makes maintenance manageable. + +--- + +## The decision worked example + +A B2B SaaS targeting product managers at mid-market companies. + +**Conditions check.** + +- Traffic: 8000 monthly organic visitors, 1200 paid visitors. Yes. +- Consideration cycle: typical PM tool evaluation takes 6-12 weeks. Yes. +- Specific problem: PMs at mid-market companies struggle to define product metrics that the engineering team can instrument quickly. Yes. +- Sequence capacity: marketing team has built two prior sequences; capacity exists. Yes. +- Success metric: list growth at audience-fit (PMs at 50-500 person companies), conversion to product trial within 60 days. Yes. + +**Decision.** Build the magnet. The conditions warrant it. + +**Format selection.** Template plus worked example. The PM produces a usable artifact (the metric definition spec) inside 30 minutes. + +**Sequence.** 7-email arc over 21 days. Email 1 delivers the asset. Emails 2-4 deepen the value with related artifacts. Email 5 introduces the product as the next step. Emails 6-7 case study and offer. + +**Audit cadence.** Quarterly review of conversion rate, lead quality, sequence open and click rates, downstream trial conversion. + +The decision was not "should we have a magnet" but "given these conditions, this is the magnet to build." + +--- + +## When to retire a magnet + +Magnets decay. Retiring them is part of the discipline. + +**Retire when:** + +- Conversion rate has dropped below baseline for two consecutive quarters. +- The topic has shifted (the audience no longer cares about the problem the magnet solves). +- A newer magnet on the same topic is outperforming and the older one is cannibalizing. +- The follow-up sequence is no longer maintained and the leads go cold. +- The references and screenshots are stale and updating them costs more than retiring. + +The retiring discipline frees capacity. A portfolio of dead magnets costs maintenance attention without producing results. Honest retirement is part of the program. + +--- + +## Methodology-level choices that stay in the public skill + +The decision conditions for whether to build a magnet. The opportunity-cost frame. The audience precondition. The portfolio frame. The retirement discipline. The decision worked example. The honest "no" cases where a magnet adds friction. + +## Implementation choices that stay internal + +Specific magnet topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence work. Specific tooling for landing pages, forms, delivery, and sequence. Specific success-metric definitions and baselines. The team's portfolio composition and audit calendar. These vary by team and audience. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md b/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md new file mode 100644 index 0000000..f3b990f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md @@ -0,0 +1,190 @@ +# Title and presentation discipline + +Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. + +The magnet's title is the conversion lever and the qualification filter at the same time. Beyond the title, the cover, the landing-page preview, and the first page each carry signal about whether the resource will deliver. Get any of these wrong and the rest of the magnet's design effort is wasted. + +--- + +## Title patterns that work + +Specific, honest, signals what is inside. + +**Specific outcome plus specific audience.** "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." + +What works: the specific outcome (3x'd, 14-day activation), the specific audience (SaaS founders), the specific deliverable (email sequence). The reader knows exactly what they get and can predict whether it applies. + +**Specific deliverable plus specific situation.** "The pricing one-pager for SaaS founders raising a seed round." + +What works: the artifact (pricing one-pager), the situation (raising a seed round). Niche by design; the audience that converts is exactly the audience the brand wants to engage. + +**Specific framework plus specific problem.** "The 4-question framework for deciding whether to fire a customer." + +What works: the framework's structure (4 questions), the specific decision (fire a customer). Promises a tool, not a treatise. + +**Specific count plus specific value.** "23 onboarding emails, with the open and click rate for each." + +What works: the count (signals scope), the value-add (real metrics, not just templates). The reader knows the resource includes evidence. + +**Specific transformation.** "The audit that took our trial-to-paid rate from 8 percent to 14 percent." + +What works: the before-state (8 percent), the after-state (14 percent), the mechanism (the audit). The reader can imagine running their own version. + +--- + +## Title patterns to avoid + +Vague, overpromising, or generic. These titles correlate with thin-bait and kitchen-sink-resource patterns. + +**"Ultimate Guide to X."** Vague. Promises completeness; underdelivers reliably. The "Ultimate" qualifier signals that the team did not narrow the topic. + +**"The Complete X Playbook."** Same failure mode. Promises volume; suggests the resource is big and unfocused. + +**"Free X Resource."** Generic. Tells the reader nothing about what makes this resource the one to download. The "free" framing implies the resource has to apologize for asking for the email. + +**"10 Tips for Better X."** Listicle framing signals thin content. "10 tips" is rarely a useful resource; "the 1 specific change that doubled our X" is. + +**"X 101" or "Beginner's Guide to X."** Targets a low-investment audience. The list that grows from these titles tends to convert poorly to anything beyond the magnet. + +**"The Definitive X Resource."** Self-aggrandizing. Definitive is the reader's judgment, not the marketer's claim. + +**Vague verbs.** "Master," "Unlock," "Transform." Without specificity about what or how, these are filler. + +--- + +## The honesty discipline in titles + +The title should not promise more than the magnet delivers. + +**The check.** Read the title. Then open the magnet. Does the magnet deliver on the title's specific promise? If yes, the title is honest. If the title overpromises, redesign the title (or strengthen the magnet) before launching. + +**The consequence of dishonesty.** Readers download, find the gap between title and content, and unsubscribe. Worse, they remember the brand as the source of the gap. The conversion-rate metric looks fine; the brand reputation degrades. + +**The conservative title.** A title that slightly under-promises and then delivers more is better than a title that overpromises and disappoints. + +--- + +## Cover and visual presentation + +The cover is the second visual the reader processes (after the landing page hero). It should reinforce the title's specificity. + +**Strong cover patterns.** + +- **Type-driven covers.** The title in clean, large type. Color-blocked. Reads at thumbnail size. +- **Single-image covers.** A specific image (a screenshot, a diagram, a person) that signals what the magnet contains. +- **Brand-consistent covers.** Visual style matches the brand the magnet represents. + +**Weak cover patterns.** + +- **Stock-image covers.** Generic stock photos signal generic content. +- **Cluttered covers.** Too many visual elements; the title gets lost. +- **Off-brand covers.** Cover that does not match the brand the reader saw on the landing page; signals inconsistency. + +**The cover-as-thumbnail test.** The cover will be displayed at thumbnail size in social shares, in landing-page previews, and in delivery emails. Does it read at thumbnail size? If not, redesign. + +--- + +## Landing-page preview + +The landing page (which is the `landing-page-copy` skill's domain) should preview the magnet, not just describe it. + +**Strong preview patterns.** + +- **Show pages from inside.** Screenshots of actual pages from the magnet. The reader sees the resource before they download. +- **Show worked examples.** A specific page from the template, the checklist, or the swipe file. Concreteness lifts conversion. +- **Show the table of contents.** For longer magnets, show what is inside. The reader can predict whether the resource will help. + +**Weak preview patterns.** + +- **Stock-image hero only.** The landing page shows nothing of the actual magnet. The reader has to trust the marketing without evidence. +- **Generic descriptions.** "Learn the framework that..." without showing the framework. +- **Hidden contents.** "You will learn..." without showing what learning looks like in the resource. + +The preview is the second-best evidence that the magnet delivers (the best evidence is post-download, but the preview is the pre-download proxy). Strong previews lift conversion and reduce post-download disappointment. + +--- + +## First-page discipline + +The first page of the magnet is what the reader sees on opening. It sets the expectation for the rest. + +**The first page should deliver value within the first read.** The reader has just downloaded; they are most engaged in the first 30 seconds. Use the first page to deliver the headline insight, the first checklist item, the template's first prompt, the calculator's first input. + +**The first page should NOT.** + +- Warm up with author bio. The reader did not download the magnet to read about the author. +- Spend space on brand-positioning. The reader knows whose brand they downloaded from; they want the value. +- Recap the marketing. The landing page already sold the magnet; the first page should deliver, not re-sell. +- Defer the value. "In Chapter 3, you will learn..." loses the reader who wanted the value now. + +**The first-page test.** Open the magnet. Does the first page deliver something useful? If yes, the first-page discipline holds. If no, redesign the first page to deliver value upfront. + +--- + +## Title-magnet alignment audit + +Periodically audit titles against the magnets they represent. Drift accumulates: titles get polished while magnets remain unchanged, and the gap between promise and delivery widens. + +**The audit.** + +- For each active magnet, read the title and open the magnet. +- Does the magnet deliver on the title's specific promise? +- If not, the gap is either a title that overpromises (fix the title) or a magnet that underdelivers (strengthen the magnet). + +**The audit cadence.** Quarterly is reasonable for active magnets. Drift detection is part of magnet portfolio maintenance. + +--- + +## Worked title revisions + +**Original title: "Marketing Automation Guide."** + +Failure: vague, generic, overpromises (which guide?). + +**Revised title: "The 7-email re-engagement sequence we send to trial signups who go cold (with open and click rates)."** + +What changed: specific deliverable (7-email sequence), specific situation (trial signups who go cold), specific evidence (open and click rates). + +**Original title: "B2B Lead Generation Playbook."** + +Failure: "Playbook" suggests volume without focus. "B2B Lead Generation" is too broad to focus a single resource. + +**Revised title: "The cold-email template for B2B SaaS founders selling into mid-market product teams."** + +What changed: specific format (template), specific audience (B2B SaaS founders), specific buyer (mid-market product teams). Niche by design. + +**Original title: "The Complete Pricing Guide."** + +Failure: "Complete" overpromises; "Pricing Guide" suggests volume; the guide will likely be a kitchen-sink-resource. + +**Revised title: "The pricing one-pager template for SaaS founders raising a seed round."** + +What changed: specific deliverable (one-pager template), specific situation (raising a seed round). Tight scope; usable immediately. + +The pattern: replace vague nouns and adjectives with specific deliverables, audiences, and situations. The revision often shrinks the addressable audience and improves the qualified-lead rate. + +--- + +## Common title and presentation failures + +**Title overpromises.** The reader downloads, opens, finds less than expected, and unsubscribes. + +**Title is generic.** Anyone could want this; no one specifically wants it. + +**Cover signals stock content.** Generic visual; reader's expectation drops before opening. + +**Landing page hides the magnet.** The reader has no evidence the resource will deliver; conversion suffers. + +**First page warms up instead of delivering.** Author bio, brand statement, table of contents. The reader's engagement drops. + +**Drift between title and content.** The title was strong at launch; the magnet has not been updated; the gap has widened over time. + +--- + +## Methodology-level choices that stay in the public skill + +Title patterns that work and fail. The honesty discipline. Cover and visual presentation patterns. Landing-page preview discipline. First-page discipline. The title-magnet alignment audit. Worked title revisions. Common failures. + +## Implementation choices that stay internal + +Specific titles for the team's magnets. Specific cover-design conventions and brand application. Specific landing-page templates and layout choices. Specific first-page templates and brand voice. The team's audit calendar and revision processes. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md b/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md new file mode 100644 index 0000000..3b1db15 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md @@ -0,0 +1,158 @@ +# The "would they pay for this" test + +The pricing thought experiment that distinguishes earned-value from thin-bait. A single test the magnet either passes or fails before launch. + +The question is simple. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails the test is signaling that the value is below "I would pay for this," which means the reader's time investment to download and consume is at the edge of "worth it." The unsubscribe rate, the reduced trust, and the wasted email gate all follow from a failed test. + +--- + +## How to apply the test + +The test is a thought experiment, not a market study. Run it before the magnet ships. + +**Step 1: Imagine a stranger in the target audience.** Not the team's existing customer; not someone already on the list. A stranger who has not yet committed to the brand. + +**Step 2: Imagine showing them the magnet (the actual content, not the marketing).** Not the landing page; not the headline; the resource itself in the form they would receive it. + +**Step 3: Ask: would this person, having seen this resource, pay something for it?** A small amount, an honest amount. + +**Step 4: Be specific about the price.** Would they pay 5 dollars? 25 dollars? 100 dollars? The specific number forces an honest answer. + +The test fails when the honest answer is "no, they would not pay for this; they would expect it to be free or to come bundled with something else." The test passes when the honest answer is "yes, this is worth paying for, even at a small price, because the value is concrete." + +--- + +## What the test catches + +Three failure modes the test catches reliably. + +**The 5-page PDF that summarizes blog content.** Free elsewhere, available without a gate, worth 0 dollars in a paid context. Fails. + +**The "Ultimate Guide" that nobody finishes.** Pay-worthy in theory (comprehensive coverage), not delivered in usable form. The reader pays for the resource and never extracts the value because the resource is too long to consume. The test surfaces this when the team imagines whether the reader would actually use what they paid for. + +**The template that is so generic it adds no value over starting from scratch.** Pay-worthy framing (templates feel valuable), thin in execution (the template's content is "Insert your value here" 30 times). The test catches this when the team imagines the reader's reaction on opening the template. + +The test catches these failures because the question forces honesty about the resource's actual value rather than the resource's marketing claim. + +--- + +## What the test the magnet should pass looks like + +A magnet that passes is one where: + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +The first criterion is about value. The second is about usability. The third is about uniqueness or curation. A magnet that hits all three earns the email reliably. + +**Worked example: A passing magnet.** + +The B2B SaaS founder magnet "the welcome-email template that 4x'd our trial-to-paid rate." + +- Pay-worthy: a SaaS founder would pay 25-50 dollars for a template that demonstrably 4x'd a real trial-to-paid rate. The specificity (4x, real metric, real source) makes the payment plausible. +- Usable: 7 emails, copy-paste ready, with sender-side context for each. A founder can implement in 60 minutes. +- Unique: the specific template plus the specific result is not freely available elsewhere. + +The magnet passes. It is worth the email. + +**Worked example: A failing magnet.** + +The "Marketing Trends 2026" PDF. + +- Pay-worthy: a generic trends roundup is not worth paying for. Freely available analyses cover the same ground. The specificity is missing. +- Usable: a 30-page PDF of trend descriptions does not produce a result; it produces awareness, which the reader could have gotten elsewhere. +- Unique: marketing trend roundups are commoditized; this one is not differentiated. + +The magnet fails. It captures emails that decay because the resource did not earn the relationship. + +--- + +## When the test surfaces "almost passes" + +Sometimes the answer is "they might pay 5 dollars but not 25 dollars." This is signal, not failure. + +**The action.** Strengthen the resource until the answer becomes "yes, they would pay 25 dollars." This often means adding the specific worked example, the specific case study, or the specific tooling that makes the resource concretely useful. + +**The risk of skipping.** Shipping the "5 dollar" version saves time but produces conversion-rate metrics that look fine and lead-quality metrics that disappoint. The strengthened version costs more upfront and pays back in lead quality and downstream conversion. + +The test surfaces the gap between the magnet as built and the magnet at value-strong. The work to close the gap is often the difference between thin-bait and earned-value-magnet. + +--- + +## When the test surfaces "this should not be a magnet" + +Sometimes the honest answer is that the resource would not be paid for at any price. + +**The action.** Do not ship the magnet. Either redesign the resource until it would be paid for, or accept that the resource is content (not a magnet) and publish it ungated. + +**The release valve.** Not every piece of content has to be gated. Free, ungated content has its own value (SEO, distribution, brand). Forcing a gate onto thin content costs more than it adds. + +The test sometimes leads to "this should not be a magnet at all." That outcome is fine; it prevents shipping a thin-bait magnet that costs list trust. + +--- + +## When the test surfaces "this is so valuable we should sell it" + +Occasionally the honest answer is that the resource would be paid for at a meaningful price (200 dollars, 500 dollars). + +**The decision.** The team has a choice. Sell the resource (and use a different, more right-sized magnet for list-building) or use the high-value resource as the magnet (which signals exceptional generosity and often produces strong conversion at high lead quality). + +**The high-value-as-magnet pattern.** Some brands give away exceptionally valuable resources as magnets specifically to signal expertise and generosity. The conversion to paid offerings often increases because the magnet establishes credibility. + +The test surfaces this opportunity. The team's decision depends on the broader strategy. + +--- + +## The team-honesty discipline + +The test only works if the team answers honestly. Pressure to ship, sunk cost in production, attachment to the magnet's framing all bias the answer toward "yes." + +**The discipline.** + +- Have someone outside the magnet's authoring team apply the test. Outside-in honesty often catches what the authoring team rationalizes. +- Show the actual resource, not the marketing. The pretty landing page is not the test; the PDF or the template is. +- Be specific about the price. "Would they pay something" is too vague; "would they pay 25 dollars" forces specificity. +- Take the answer seriously. If the team applies the test and answers no, do not ship the magnet without redesign. + +The test's value is in the honesty it surfaces. A team that applies it and ignores the answer is worse off than a team that does not apply it at all. + +--- + +## What to do when the test fails + +The magnet fails the test. Now what. + +**Option 1: Strengthen the magnet.** Add the specific worked example, case study, tooling, or framework that brings the value to pay-worthy. This is often the right answer. + +**Option 2: Redesign as a different format.** The topic might not be magnet-shaped in the current format. A 30-page ebook on a topic might fail; a 2-page checklist on the same topic might pass. + +**Option 3: Reframe the audience.** The magnet's value depends on the audience. A magnet that fails for the broad audience might pass for a narrower segment that genuinely needs the resource. + +**Option 4: Do not ship.** Some magnets should not exist. Killing the magnet is honest; shipping a thin one costs more in list trust than killing it costs in sunk effort. + +The team's response to a failed test is the discipline marker. Strong programs redesign or kill; weak programs ship anyway. + +--- + +## Common test failure modes + +**The team rationalizes the failure.** "It is good enough; readers will appreciate it being free." This is the path to thin-bait. + +**The team applies the test to the wrong audience.** "Would a generalist marketer pay for this" when the magnet is for SaaS founders. The test must use the actual target audience. + +**The team applies the test to the marketing, not the resource.** The landing page sounds great; the resource is thin. The test surfaces this when applied to the actual content. + +**The team skips the test under deadline pressure.** The magnet ships, the metrics look fine, the unsubscribe rate quietly climbs. The test was the protection against this; skipping it costs trust. + +--- + +## Methodology-level choices that stay in the public skill + +The test as a thought experiment with specific steps. The failure modes the test catches. The criteria a passing magnet meets. The team-honesty discipline. The decision tree when the test fails. The test failure modes. + +## Implementation choices that stay internal + +Specific magnets the team has tested and the outcomes. Specific price-point conventions for the team's audience. The team's outside-team review process. Specific redesign patterns the team uses for failing magnets. These vary by team and audience. diff --git a/dist/pi/.agents/skills/logo-design/SKILL.md b/dist/pi/.agents/skills/logo-design/SKILL.md new file mode 100644 index 0000000..75d1e26 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/SKILL.md @@ -0,0 +1,206 @@ +--- +name: logo-design +description: "Generate logo variants for a brand, producing multiple production-grade marks across different architectures (wordmark, lockup, symbol-only, letterform-as-symbol, monogram) with rationale, application specs, and decision-ready presentation. Distinct from `brand-identity`, which produces the complete system (logo plus color, type, voice, applications). Goes deep on the logo specifically: typographic register, symbol approach, application-context discipline (16px favicon, embroidery, signage, motion), and production specs (SVG-ready, single-color, reverse). Triggers on logo design, design a logo, wordmark, monogram, lockup, mark variants, logo iterations, redesign or refine the logo, logo refresh, letterform-as-symbol, and exploring mark variants for an established brand. Does NOT fire for full brand identity (use `brand-identity`), positioning or strategy (use `brand-discovery`), project-wide creative direction (use `creative-direction`), or one-off illustration." +category: brand +catalog_summary: "Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol), with rationale and application specs" +display_order: 5 +--- + +# Logo Design + +A logo is a system of marks, not a single drawing. This skill produces multiple production-grade variants exploring different architectural approaches, each with rationale, application specs, and a clear position on what it signals and rejects. + +The output is decision material, not a finished logo. The brand owner selects from the variants and the skill produces production refinement on the chosen direction. + +--- + +## When to use + +- The brand has a name and tonal direction; the deliverable is logo work specifically +- Generating 6 to 12 variants for client review and selection +- Refining a wordmark to production: kerning, optical adjustments, weight selection +- Exploring symbol options to pair with an existing wordmark +- Designing a monogram from a longer name for use in constrained contexts +- Adapting an existing logo across application contexts (small-size, signage, motion, embroidery) +- The brand owner has reviewed a first round and wants iteration on a specific direction + +## When NOT to use + +- Use `brand-identity` instead when the deliverable is the complete identity system (logo plus color plus type plus voice plus applications). This skill is the logo-specific layer; brand-identity is the system layer. +- Use `brand-discovery` for brand positioning, audience, and voice work. A logo without strategy is a drawing. +- Use `creative-direction` for project-wide aesthetic direction. Creative direction calibrates many decisions; logo design produces specific marks. +- One-off illustration, icon, or pictogram work +- Designing brand patterns, textures, or supporting graphics +- Pure typographic exploration unrelated to a brand name + +--- + +## Required inputs + +- **Brand name.** Exact spelling. Capitalization and punctuation preferences if any. Whether the name has a category descriptor that travels with it (e.g., "Atlas Coffee" vs just "Atlas"). +- **Industry or category.** Legal firm, consumer goods, B2B SaaS, hospitality, etc. Category implies defaults that can be honored or broken. +- **Audience.** Who sees the logo, where, in what state of mind. The audience-side perception drives selection more than the founder-side aesthetic. +- **Tonal direction.** Where on the formal-to-casual axis. Where on the restrained-to-expressive axis. Where on the heritage-to-modern axis. +- **Application contexts.** Common set: web header, mobile app icon (28px), favicon (16 to 32px), business card, letterhead, email signature, social profile picture, signage (large format), embroidery patch (1.5 inch), single-color print, video motion lockup, merch (apparel, hats, totes). +- **Reference logos liked**, with a sentence each on what specifically resonates. The reference clarifies which architecture and register fit better than abstract description does. +- **Reference logos disliked**, with a sentence on what to avoid. Negative space sharpens positive selection. +- **Hard constraints.** Must include element X. Must avoid color Y due to industry conventions. Must reproduce in single color. Must work as a 16px favicon. Must survive embroidery. +- **Optional**: existing brand assets if the project is a refresh, not greenfield. Existing wordmark if the work is symbol-only. Existing color palette if it must remain locked. + +--- + +## The framework: 5 considerations for logo design + +A logo decision sits at the intersection of five considerations. Each one filters subsequent choices. + +### 1. Mark architecture + +What IS the logo, structurally? + +**Architectures:** + +- **Wordmark only.** The logo is the brand name set in a chosen typeface, possibly with custom letterforms. Stripe, Google, Pinterest. The discipline is letter-by-letter, with kerning, optical adjustments, sometimes a single distinguishing custom character. Strongest when the name is distinctive enough to own as type. +- **Lockup (wordmark plus symbol).** Standard architecture for most brands. The wordmark and symbol are positioned in a fixed relationship. Slack, Airbnb, Asana. Variants: symbol left of wordmark, symbol above wordmark, symbol right (rare). Each lockup may also have a stacked alternate for square contexts. +- **Symbol only.** The mark is a single symbol with no wordmark. Apple, Twitter, Target. Earned over decades through brand recognition. New brands rarely succeed with symbol-only as the primary mark, though most mature brands eventually develop a symbol-only fallback. +- **Letterform-as-symbol.** A single letter from the name (often the first) becomes the symbol. Beats by Dre's "b", McDonald's "M", Underscore's "_". Cleanest path to symbol when the wordmark is too long for a tight lockup or when the name has a letter that lends itself to visual play. +- **Monogram.** Multiple letters combined as a symbol. CN (Chanel), GG (Gucci), HBO, MN (a hypothetical Morgan Northrop monogram for an institutional financial firm). Common in legal, financial, hospitality, and heritage brands. Can read as initials or as ligature. + +**How to choose:** What does the brand need to do at small sizes? At 16px, most lockups fail. A favicon-grade mark needs either a strong symbol component or a letterform-as-symbol fallback. Lockups also need stacked alternates for square contexts (social profile pictures, app icons). A pure wordmark works only if the brand has another mark that can stand in at small sizes, often a letterform-as-symbol or monogram. + +A common production setup is: primary lockup for most contexts, monogram for square contexts, letterform-as-symbol for favicon and embroidery. All three derive from the same wordmark and share visual DNA. + +### 2. Typographic register + +If wordmark or lockup, what typographic family carries the type? + +**Registers:** + +- **Geometric sans.** Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde. Built from circles and verticals. Reads modern, considered, often optimistic. Risks reading cold or generic-tech-startup if not warmed up by color, custom letterform, or context. +- **Humanist sans.** Gill Sans, Optima, Frutiger, Source Sans, Inter at higher optical sizes. Has serif-like calligraphic gestures without serifs. Reads professional but warm. Excellent neutral choice when the category demands restraint with personality. +- **Neo-grotesque sans.** Helvetica, Inter, Aktiv Grotesk, Söhne, GT America. The modern professional default. Reads competent and contemporary. Risks reading generic if not paired with strong color or symbol. +- **Transitional serif.** Source Serif, Charter, Lyon, IBM Plex Serif. Modern serifs with high contrast and readability. Reads editorial, considered, intellectual. Good for legal, publishing, financial, editorial brands. +- **Old-style serif.** Garamond, Caslon, Sabon, Adobe Garamond. Classical serifs with low contrast and warm shapes. Reads heritage, traditional, institutional. Common in academic, legal, financial, and heritage brands. +- **Slab serif.** Sentinel, Adelle, Roboto Slab, Tisa. Heavy structural serifs. Reads strong, declarative, sometimes journalistic. Common in editorial and publishing. +- **Display custom.** A custom-drawn or heavily-modified typeface. Reads distinctive but expensive in time. Justified when the brand needs a wordmark no one else has and the budget supports drawing one. + +**How to choose:** What does the brand reject? Most categories have a default register. Legal firms default to old-style or transitional serif. Tech startups default to geometric or neo-grotesque sans. Choosing within the category default reads as competence; choosing outside reads as positioning. A boutique legal firm in geometric sans signals "modern, accessible". A SaaS startup in old-style serif signals "we take ourselves seriously". + +### 3. Symbol approach + +If the architecture includes a symbol (lockup, symbol-only, letterform-as-symbol), what KIND of symbol? + +**Approaches:** + +- **Literal.** The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. Fast recognition, low ambiguity. Risks reading as cliche if the depiction is generic. Saved by distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. +- **Abstract gesture.** The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity". Slower recognition, higher distinctiveness. Risks reading as arbitrary if the gesture is too abstract. Saved by clear formal logic and consistent visual vocabulary. +- **Geometric reduction.** The symbol is a formal abstraction with no specific referent. A hexagon, a triangle, a stack of horizontal lines, a circle bisected by a vertical. Reads modern and confident. Risks reading as identical to many other geometric-reduction marks. Saved by specific proportions, considered execution, and pairing with a distinctive wordmark. +- **Letterform-derived.** The symbol is built from the name's letterforms. The "M" of McDonald's, the "b" of Beats, a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. Strong wordmark-symbol coherence. Risks reading as wordmark-only if the letterform isn't emphasized enough. Saved by exaggerated character: the letter must read as both the letter AND the visual metaphor. +- **Monogram.** Multiple initials combined. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). Common in legal, financial, hospitality. Risks reading as old-fashioned if the type treatment is too conservative. Saved by modern execution within traditional architecture. + +**How to choose:** What does the brand name already do? Descriptive names (Atlas, Forge, Pulse, Anchor) invite literal symbols and letterform-as-symbol approaches. Abstract names (Stripe, Anthropic, Linear) demand abstract or geometric-reduction symbols. Heritage names (a founder's surname, a place name) often use monograms. The wrong approach disconnects symbol from name. + +### 4. Application context discipline + +A logo is not a single drawing. It must work in every context the brand touches. + +**Contexts and their constraints:** + +- **16px favicon.** The most aggressive small-size test. Lockups usually fail here; the symbol or letterform-as-symbol carries. Plan a fallback mark for this context from the start. +- **28px app icon.** Slightly more headroom than favicon. Still demands strong silhouette. Often uses the symbol or monogram, not the lockup. +- **1.5 inch embroidery patch.** Limits color count (often 4 to 6 max), demands clean shapes without fine detail. Eliminates gradient and photographic elements. Tests the mark's reproducibility in a tactile medium. +- **Single-color reproduction.** Etching, foil stamp, single-color print, fax. All gradient and color-dependent decisions must collapse cleanly to one color. Test by converting the design to pure black on white. +- **Reverse (light on dark).** Many marks fail when reversed. Test on the brand's expected dark backgrounds early. Gradient marks particularly struggle here. +- **Large-format signage.** Requires sharp vector with no rasterization. Tests construction grid quality. Tests whether thin strokes survive scaling. +- **Motion lockup.** Tests whether the logo has natural entry and exit animation. Wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts. +- **Social profile picture (square).** Lockups need a stacked alternate or monogram fallback. Symbol-only works natively. +- **Apparel embroidery (thread on fabric).** Tighter constraints than patch embroidery. Fine letterforms and detail die here. The mark needs a chunky-friendly variant. +- **Foil stamp on paper or leather.** Single-color, no gradients, requires substantial line weight to survive the impression. + +**The discipline:** Every variant must pass the application-context test before it's a contender. Generate each variant, then mentally test each context. If a variant fails three or more contexts, it's not a primary mark; it might still serve as a secondary or display lockup but it isn't carrying the brand. Build a fallback hierarchy: primary lockup, secondary monogram, favicon-grade letterform-as-symbol. + +### 5. Restraint discipline + +Most logo failure happens through over-design. The discipline is subtractive. + +**Tests:** + +- **Silhouette test.** Squint at the logo. If you cannot identify it from silhouette alone (with type stripped), the silhouette is too generic. Apple, Nike, Twitter pass. Most generic SaaS marks fail. +- **Distinctiveness test.** Search Google Images for "[your category] logo". If your candidate looks identical to three or more existing logos, it's not distinctive enough. Especially watch out for geometric-reduction marks that have already been done a thousand times. +- **Sketchability test.** A 7-year-old draws the logo from memory after 30 seconds of looking. If they can't, it's too detailed to live in cultural memory. +- **Single-color test.** Strip all color. Does it still read? If no, color is doing too much work. +- **Reproducibility test.** Print at 1 inch on a black-and-white printer. Is it still recognizable? If no, the mark won't survive embroidery, foil stamps, or low-resolution applications. +- **The two-second test.** Show the logo to someone unfamiliar with the brand for two seconds. Ask what they remember. The features they recall are the ones doing real work; the rest is noise. + +The discipline doesn't reject all detail. It rejects detail that doesn't earn its place. Every visual element should pass the question "does this read at the smallest application size?". + +--- + +## Workflow + +1. **Gather inputs.** Required inputs above. If the user has reference logos, walk through what specifically resonates in each. The references calibrate which architecture and register actually fit. + +2. **Establish primary architecture.** Wordmark-only? Lockup? Letterform-as-symbol? Monogram? This is the foundational decision; everything else flows from it. For most new brands with a distinctive descriptive name, the right architecture is lockup with literal or letterform-derived symbol, plus a monogram fallback for square contexts. + +3. **Generate typographic explorations.** Produce 3 to 4 wordmark-only variants exploring different typographic registers. Each variant should be a complete, kerned, optically-adjusted wordmark. These serve as both standalone candidates and as the foundation for subsequent symbol pairing. + +4. **Generate symbol explorations** (if architecture includes a symbol). For each typographic exploration, generate 1 to 2 symbol pairings using different symbol approaches (literal, abstract gesture, letterform-derived, monogram). The symbol must visually agree with the wordmark's type weight, optical density, and tonal register. A heavy slab wordmark needs a chunky symbol; a hairline geometric wordmark needs a thin symbol. + +5. **Test each variant against application contexts.** For each candidate, walk through 16px favicon, 1.5 inch embroidery, single-color reproduction, square stacked alternate. Eliminate variants that fail more than two contexts. Document which contexts each variant excels in versus needs a fallback for. + +6. **Pick top candidates for client review.** Typically 6 to 12 final variants. Each variant must be visually distinct from the others. Variants that are too similar dilute the review and frustrate the client (they cannot tell why they should pick one over the other). + +7. **Document each variant.** Per-variant: descriptive name (e.g., "01, Light geometric wordmark, Avenir Next"), architecture, typography, symbol approach if applicable, color tokens, application notes, signals (what it communicates), rejects (what it explicitly is NOT). + +8. **Provide production specs** for the top 3 candidates. SVG-ready construction notes, color hex codes (primary plus single-color black plus single-color white plus reverse), sizing guidelines (minimum sizes per medium), motion entry and exit recommendation, embroidery and foil-stamp adaptations. + +9. **Provide application mockups.** Render each top candidate in 3 to 5 representative contexts: web header, business card, favicon at 16 and 32px, embroidery patch, signage. Mockups can be image-generated or schematic. The point is to show the client how the mark lives across contexts, not to deliver finished marketing material. + +10. **Hand off.** Output is decision material. The brand owner selects a direction. The skill (or a follow-up iteration) then produces production refinement on the chosen path: cleaner construction, refined kerning, color system finalization, application library. + +--- + +## Failure patterns + +- **Designing for the founder's taste, not the audience's perception.** The founder sees the logo every day; the audience sees it for 3 seconds in a bad mood. The audience-side test wins. +- **Skipping the silhouette test.** Logos that fail silhouette die at small sizes and in motion. Test early. +- **Ignoring small-size legibility.** A favicon test at 16px is the single most overlooked discipline. Most lockups fail here. Plan a fallback symbol or letterform-as-symbol mark from the start. +- **Trying to depict everything the brand does.** Logos can hold one idea, sometimes two. Three is too many. Symbols stuffed with multiple metaphors read as committee work. +- **Picking a typeface for trend.** Monoline geometric sans (Cabinet Grotesk, GT Pressura) read as "2024 startup" in a way that ages quickly. Pick for category-fit and longevity, not for design-trend currency. +- **Over-customizing letterforms.** Custom letterforms should solve a specific problem (a flat-bottomed "g" that conflicts with a descender, an "a" that breaks the rhythm, an "A" that becomes a mountain peak). Custom for novelty's sake reads as gimmicky. +- **Lockups that fall apart at certain sizes.** Test the lockup at 200%, 100%, 50%, 25%. If proportions break or elements clash at any size, the lockup needs adjustment. +- **Color-dependent marks.** A logo that requires color to be recognizable cannot survive single-color reproduction. Color is the last layer, not the foundation. +- **Letterform-as-symbol marks that fail the silhouette test for the underlying letter.** An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. +- **Reviewing too many similar variants.** Showing a client 10 wordmark variants in different geometric sans typefaces dilutes the decision. Show 3 architectures, with 2 to 3 typographic options each. The client can see the architectural choice clearly. +- **Skipping the embroidery test.** Many brands eventually want a hat or a polo. A logo with fine detail or photographic gradients cannot be embroidered cleanly. Test before client signoff. + +--- + +## Output format + +Default output is a markdown spec with multiple variants, typically saved as `logo-variants.md` at the project root or in a `design/` subdirectory. The spec is paired with rendered images for each variant, saved alongside (typically in `design/logo-variants/`). + +Per-variant structure: + +1. **Variant name.** Descriptive identifier with index (e.g., "01, Light geometric wordmark, Avenir Next" or "07, Mountain peak A lockup, IBM Plex Sans"). +2. **Architecture.** Wordmark / Lockup / Symbol / Letterform-as-symbol / Monogram. +3. **Typography.** Specific typeface name and weight. Custom letterform notes if any. Tracking and kerning treatments. +4. **Symbol description** (if applicable). Approach (literal / abstract gesture / geometric reduction / letterform-derived / monogram) and visual description. Construction grid notes if relevant. +5. **Color tokens.** Hex codes for primary palette, single-color black version, single-color white version, reverse-on-dark treatment. +6. **Application notes.** Which contexts the variant excels in (e.g., "strong at large signage and letterhead") and which contexts need a fallback mark (e.g., "favicon falls back to letterform-as-symbol at 16px"). Embroidery adaptation notes if relevant. +7. **Signals.** What this variant communicates about the brand. The features it foregrounds. +8. **Rejects.** What this variant explicitly is NOT. The negative space the variant creates. +9. **Mockups.** Rendered in 3 to 5 application contexts. At minimum: web header, business card, favicon. Bonus: embroidery patch, large-format signage, social profile. + +The spec is decision material. The next step after delivery is selection plus production refinement on the chosen direction. + +--- + +## Reference files + +- [`references/architectures-explained.md`](references/architectures-explained.md). The 5 mark architectures with examples, when each fits, when each fails, and how to combine them in a primary plus fallback hierarchy. +- [`references/typographic-registers.md`](references/typographic-registers.md). The typographic registers with named typefaces, category-fit notes, and example brands per register. +- [`references/symbol-approaches.md`](references/symbol-approaches.md). The 5 symbol approaches with pattern examples, calibrating the agent's vocabulary for symbol generation. +- [`references/application-contexts.md`](references/application-contexts.md). The contexts every logo must pass, with constraint specs (favicon size, embroidery color count, single-color rules, motion entry recommendations). +- [`references/category-conventions.md`](references/category-conventions.md). A survey of common conventions across major brand categories, with defaults that work, conventions worth honoring, conventions worth breaking for positioning, and category-specific application contexts. +- [`references/example-variant-spec.md`](references/example-variant-spec.md). A complete example showing all nine per-variant fields filled in for a representative project. +- [`references/client-package.md`](references/client-package.md). The package format clients expect at delivery: file format matrix, variant matrix, folder structure, naming convention, documentation layer (usage guide plus brand colors plus license), delivery mechanisms, and the failure patterns that send the client back asking for a missing variant. diff --git a/dist/pi/.agents/skills/logo-design/references/application-contexts.md b/dist/pi/.agents/skills/logo-design/references/application-contexts.md new file mode 100644 index 0000000..a9cba88 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/application-contexts.md @@ -0,0 +1,312 @@ +# Application contexts + +A logo is not a single drawing. It is a system of marks that must work in every context the brand touches. Most logo failure happens because a designer optimized for one context (typically the web header at 200px wide) and never tested the others. This file expands the application contexts in [SKILL.md](../SKILL.md) with specific constraint specs, common failure modes, and mitigation patterns. Use it as the working checklist for every variant before declaring a candidate ready for review. + +The discipline is to design for the smallest, harshest application FIRST, then scale up. Most brand systems do the opposite: they design at the marketing scale and discover at production time that the mark cannot survive its smaller, harsher applications. + +--- + +## 16px favicon + +The most aggressive small-size test. The mark renders inside a 16x16 pixel grid (some browsers go to 32x32, but 16x16 is the historical baseline and still the test that reveals construction problems first). + +### Constraints + +- 16x16 pixels means roughly 4 to 6 distinguishable visual elements maximum +- No fine detail; lines under 2px disappear +- No gradients (gradients render as muddy color washes at this scale) +- No more than 3 to 4 colors before the rendering algorithm dithers +- Symbol or letterform must read at thumbnail scale, not as a logo + +### Failure modes + +- Lockups (wordmark plus symbol) almost always fail; the wordmark becomes illegible +- Fine letterform details (custom serifs, decorative crossbars) disappear +- Multi-color symbols dither into pixel noise +- Symbols with internal cutouts or fine negative space lose the cutout at 16px +- Geometric reductions with multiple primitives blur together + +### Mitigation patterns + +- Ship a dedicated 16x16 favicon-grade asset, not a downscaled version of the lockup +- Use a single element from the lockup (the symbol alone, the letterform-as-symbol, or the monogram) at favicon scale +- Test the favicon on actual browser tabs (Chrome, Safari, Firefox) at the operating system level; the rendering differs from a Photoshop preview +- If the favicon-grade asset cannot be derived from the lockup, the lockup itself is over-detailed; redesign the lockup so a clean 16x16 fallback exists + +--- + +## 28px app icon + +iOS, Android, and PWA app icons. Slightly more headroom than favicon (28x28 to 60x60 depending on rendering context) but still demanding strong silhouette. + +### Constraints + +- 28x28 to 60x60 pixels (varies by OS rendering context: notification badge, home screen, settings menu) +- Must work inside rounded-square or circle masks (iOS), rounded-square (Android) +- 4 to 8 distinguishable visual elements maximum +- Background color matters: app icons have visible bounds, so the mark either fills the icon background or sits inside a colored field +- No fine detail; lines under 3px disappear at the smallest rendering scales + +### Failure modes + +- Lockups fail at this scale almost as often as at favicon scale +- Symbols with thin strokes lose definition +- Multi-color symbols clash with the icon background fill +- Marks that depend on negative-space cutouts lose those cutouts +- Marks designed for a square ratio fail when rendered inside a circle mask + +### Mitigation patterns + +- Design the app icon as a separate asset, not a downscaled lockup +- Use the symbol or monogram, not the wordmark +- Pick a strong fill color that supports the symbol (not a generic white background) +- Test the app icon at every required size (29, 40, 60, 76, 80, 87, 120, 152, 167, 180, 1024 for iOS) and at every mask shape (rounded-square iOS, circle for some Android launchers) +- Ship a "monochrome" or "tinted" variant for iOS dark mode and tinted home screen modes (a single-color silhouette of the app icon) + +--- + +## 1.5 inch embroidery patch + +Tactile reproduction at small scale. Embroidered patches for hats, jackets, polos, and merchandise. The most demanding physical reproduction context. + +### Constraints + +- 1.5 inch diameter is the common patch size (some go to 2 or 2.5 inches) +- Color count: 4 to 6 maximum (each thread color is a separate setup cost) +- Minimum stroke weight: roughly 1mm (depends on the embroidery machine and thread weight) +- No gradients, no photographic elements, no fine textures +- Letterforms below 2mm tall do not embroider cleanly +- Sharp inside corners and acute angles fail under the needle path + +### Failure modes + +- Marks with more than 6 colors require expensive multi-step embroidery or get simplified by the embroiderer in ways the brand owner did not approve +- Fine letterforms (Garamond at small sizes, Helvetica Light) become muddy or fall apart +- Gradient marks fail entirely; the embroiderer either drops the gradient (changes the brand) or refuses the job +- Symbols with thin internal lines lose those lines under the thread weight +- Marks designed for screen do not anticipate the chunky construction embroidery requires + +### Mitigation patterns + +- Design an embroidery-grade variant of the mark from the start: simplified silhouette, chunky stroke weights, 4 colors maximum +- Test the variant against an actual embroidery sample (not a screen preview) before committing +- Pick a typeface for the wordmark that survives embroidery (slab serifs, heavy sans-serifs, custom thick letterforms work; thin sans-serifs and Garamond do not) +- For brands that anticipate substantial merchandise (apparel brands, hospitality brands, sports teams), build the embroidery-grade variant into the primary system, not as an afterthought + +--- + +## Single-color reproduction + +The mark must render in a single color, on any background, for any reproduction medium that does not support color. Etching, foil stamp, single-color print (offset or letterpress), faxed documents (still happens for legal and financial), engraving, screen printing limited to a single color. + +### Constraints + +- Pure black on white, pure white on black, or single ink color +- No gradients (must collapse to flat color) +- No color-dependent meaning (a symbol that means one thing in red and another in blue fails) +- No subtle color contrasts (a symbol with two shades of gray loses information when reduced to one color) + +### Failure modes + +- Color-dependent marks (the brand identity is the color, not the form) cannot be reproduced +- Gradients become muddy in single-color etching or foil +- Multiple-color symbols collapse to a single shape that does not read as the original +- Marks that rely on color-coded brand meaning (red = action, blue = trust) lose meaning +- Embossed or debossed reproductions test the construction grid; thin lines fail under embossment + +### Mitigation patterns + +- Test the design as a pure black-on-white silhouette early; if it does not read in monochrome, color is doing too much work +- Build a dedicated single-color version of the mark with stroke weights and proportions adjusted for monochrome reproduction +- Make sure the single-color version reads as the brand without color +- Pick application contexts that match the single-color variant (foil stamp on letterhead, engraved signage, etched glass, leather embossing, single-color print) + +--- + +## Reverse on dark + +The mark on a dark background. The brand's web header in dark mode. The signage at night. The product photography on a black field. The letterhead variant for black envelopes. Many marks fail when reversed because the negative space and stroke balance shift. + +### Constraints + +- Light strokes on dark background; the form is what is visible, not what is empty +- Gradient marks particularly struggle (the gradient direction may need to invert) +- Color contrast must remain readable (a brand color that works on white may disappear on black) +- Negative-space marks (where the brand identity is the empty space, like FedEx's hidden arrow) require careful inversion handling + +### Failure modes + +- Marks designed for light backgrounds invert into something that looks like a different mark +- Color contrast fails (yellow on black is fine; pale yellow on black is illegible) +- Thin strokes optimized for white-on-black render too heavy when inverted to black-on-white +- Symbols with internal cutouts work in one direction but not the other +- Brand color decisions made for one direction read wrong in the other + +### Mitigation patterns + +- Test every mark on dark backgrounds early in the process, not at production time +- Build dedicated reverse-on-dark variants where stroke weights or proportions are adjusted +- For marks that must work on both light and dark, design the construction grid so it is direction-neutral (Apple's apple, Nike's swoosh) +- For marks that cannot be neutral, ship two variants: light-on-dark and dark-on-light, with construction tuned for each + +--- + +## Large-format signage + +The mark at building scale. Storefront signage, lobby walls, conference signage, billboard, vehicle wrap. The opposite end of the scale spectrum from favicon. + +### Constraints + +- Sharp vector with no rasterization; print resolution must support 12+ feet output +- Construction grid integrity matters at every scale (proportional adjustments that work at 1 inch may not work at 12 feet) +- Thin strokes that survive at marketing scale may look anemic at signage scale +- Color reproduction differs (a brand color that prints clean on paper may print different on backlit acrylic, vinyl, or painted aluminum) +- Distance reading: the mark must read at street scale (50 to 200 feet) + +### Failure modes + +- Wordmarks with thin strokes look anemic at 12 feet +- Fine letterform details that read at marketing scale disappear at signage scale +- Color decisions based on screen rendering do not match the actual material (vinyl, paint, acrylic, illuminated channels) +- Lockups designed for desktop scale crowd or stretch when forced into signage's typical aspect ratios + +### Mitigation patterns + +- Test the mark at 8 to 12 feet wide as a printed mock-up before committing +- Build signage-grade variants where stroke weights are adjusted for distance reading +- Specify Pantone colors (not RGB or hex) for signage color reproduction +- For illuminated signage (channel letters, backlit acrylic), test the mark with the illumination direction the actual sign will use (front-lit, halo-lit, edge-lit each render differently) + +--- + +## Motion lockup + +The mark in animation. Brand entry sequences in video, app launches, motion identity. The mark is no longer static; it moves, scales, fades, transforms. + +### Constraints + +- The mark must have a natural entry and exit animation +- The construction must support stage-by-stage reveal (wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts) +- Frame rate: 30 to 60 fps for web, 24 fps for film +- Total animation duration: typically 1 to 3 seconds for brand entry; 0.5 to 1 second for app launch +- Easing curves must feel intentional, not generic + +### Failure modes + +- Marks with arbitrary construction have no natural animation; they snap into place rather than assembling +- Wordmarks animated with random letter entrance look generic; the entrance must follow the letterform construction +- Symbols animated with rotation or scale alone read as obvious; the animation should reveal something about the symbol's construction +- Animation duration too long becomes annoying; too short and the mark does not register + +### Mitigation patterns + +- Design the mark with animation in mind: the construction should suggest its own assembly +- Specify the motion direction: how does the mark enter, hold, and exit? +- Build a 1-second motion identity that works for app launch, video brand entry, and social media +- Test the motion at the actual deployment surface (app launch screen, social video, in-product brand entry) + +--- + +## Social profile picture (square) + +The mark in a square crop, usually inside a circle mask (Twitter, Instagram, LinkedIn, most social platforms). Lockups need a stacked alternate or symbol-only fallback. Symbol-only marks work natively. + +### Constraints + +- Square aspect ratio (often 400x400 to 800x800 pixels for social profile) +- Often rendered inside a circle mask, so the corners of the square are cropped +- Small enough size that fine detail disappears +- Must read in the user's notification feed at thumbnail scale (60-80 pixels) +- Color contrast against various background colors (light and dark mode platforms) + +### Failure modes + +- Horizontal lockups crop badly inside square; the wordmark loses its left and right edges +- Marks not designed for circle masking lose corners and read as cropped +- Detail that survives at 200x200 disappears at the 60-80 pixel notification feed scale +- Color choices that work on white backgrounds clash with the platform's darker UI + +### Mitigation patterns + +- Design a stacked alternate (symbol above wordmark, centered) for square contexts +- Use the symbol-only or monogram fallback for the social profile +- Test the mark inside a circle mask, not just inside a square +- Verify the mark reads at notification feed scale (60-80px), not just at the profile picture display scale (200-400px) + +--- + +## Apparel embroidery + +Thread on fabric, smaller scale than patch embroidery. Polo shirts, hats, beanies, t-shirts, aprons. The mark is embroidered directly into the fabric, often without a patch backing. + +### Constraints + +- Color count: 4 to 6 maximum (each thread color is a setup cost) +- Minimum stroke weight: 1.5mm to 2mm (heavier than patch embroidery because the fabric is the substrate) +- No gradients, no fine detail, no photographic elements +- Letterforms below 2.5mm tall do not embroider cleanly +- Fabric texture affects the read (cotton vs polyester vs wool render differently) +- The mark must survive washing (thread that bleeds or unravels on first wash is a quality failure) + +### Failure modes + +- Fine wordmark letterforms become muddy or fall apart +- Multi-color marks become expensive or get simplified without approval +- Marks with thin strokes do not survive washing cycles +- Marks not designed for fabric look pasted-on rather than embroidered + +### Mitigation patterns + +- Design a dedicated apparel-embroidery variant with chunky stroke weights and minimal color +- Specify thread colors (Madeira, Robison-Anton, or other professional embroidery thread brands) rather than CMYK or hex +- Test the variant on the actual fabric weight and color before committing +- Pick the variant of the mark that survives apparel embroidery (the symbol alone, the monogram, the simplified lockup) + +--- + +## Foil stamp on paper or leather + +Single-color metallic stamping. Business cards, letterhead, bound books, leather portfolios, signet rings, wax-seal-style stamps. The mark is impressed into the substrate with metallic foil. + +### Constraints + +- Single color (gold, silver, copper, black foil, etc.); no gradients +- Substantial line weight required (1mm+ minimum for gold or silver foil) +- No fine letterforms; thin serifs disappear under the foil impression +- The substrate matters (matte vs glossy paper, leather vs vellum); each renders differently +- The mark must read in metallic, not as a flat color + +### Failure modes + +- Thin letterforms disappear or look uneven under the foil +- Marks that depend on color contrast lose meaning in single-color metallic +- Heavy fills require more foil and may bleed at the edges +- Marks designed for screen rendering do not translate to the tactile, reflective surface of foil + +### Mitigation patterns + +- Design a foil-stamp variant with chunky stroke weights +- Specify foil color (PMS gold, silver, copper) and finish (matte vs glossy foil) +- Test the variant against the actual substrate (the brand's letterhead paper, the brand's leather portfolio cover) before committing +- Treat foil-stamp applications as a hierarchy decision: which mark goes here, given the constraints? + +--- + +## The discipline, restated + +Every variant under consideration must pass the application context test before it is a contender. The working checklist: + +1. **16px favicon.** Does the mark survive at smallest scale? +2. **28px app icon.** Does the mark work inside rounded-square or circle masks? +3. **1.5 inch embroidery patch.** Can the mark be embroidered with 4-6 colors and chunky strokes? +4. **Single-color reproduction.** Does the mark read in pure black on white? +5. **Reverse on dark.** Does the mark hold up inverted on a dark background? +6. **Large-format signage.** Does the mark survive scaling to 12 feet? +7. **Motion lockup.** Does the mark have a natural entry and exit animation? +8. **Social profile picture.** Does the mark work inside a circle mask at 80px? +9. **Apparel embroidery.** Does the mark survive thread on fabric? +10. **Foil stamp.** Does the mark survive single-color metallic impression? + +If a candidate fails three or more of these, it is not a primary mark. It might still serve as a secondary or display lockup, but it is not carrying the brand. The brand needs a fallback hierarchy: primary lockup, secondary monogram or symbol-only, tertiary letterform-as-symbol or simplified mark for the harshest applications. + +The hierarchy is the system. The system is what makes the brand readable across every context the audience encounters. diff --git a/dist/pi/.agents/skills/logo-design/references/architectures-explained.md b/dist/pi/.agents/skills/logo-design/references/architectures-explained.md new file mode 100644 index 0000000..4eac4c8 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/architectures-explained.md @@ -0,0 +1,165 @@ +# Mark architectures explained + +The architectural decision is the foundational one. Every other choice (typographic register, symbol approach, application context discipline) flows from it. This file expands the five architectures listed in [SKILL.md](../SKILL.md) with reference brands, fit and failure modes, and a working pattern for combining them in a primary-plus-fallback hierarchy. + +--- + +## Wordmark only + +The logo is the brand name set in a chosen typeface, possibly with custom letterform interventions. No standalone symbol. The wordmark IS the mark. Stripe, Google, Pinterest, FedEx, eBay, Coca-Cola, Visa. + +The discipline is letter-by-letter. Kerning is not optional. Optical adjustments matter at every weight. A wordmark earns its place when the brand name is distinctive enough that the type alone carries identity. Stripe's wordmark uses a single-character optical adjustment on the lowercase "r" that makes the word read as a unit; without it, the word fragments visually. FedEx hides an arrow in the negative space between the "E" and the "x", a famous earned detail that the brand's audience finds and remembers. Google's wordmark redrew its own custom geometric sans (Product Sans) so the brand owns the wordmark's specific letterforms. + +Wordmark-only works hardest at small sizes. The full wordmark fails at favicon scale almost universally. A wordmark-only brand still needs a fallback mark for 16px contexts, embroidery, and stacked square applications, even if that fallback never appears in the primary lockup hierarchy. + +### When this fits + +- The name is short (4 to 8 letters works best; 9 to 12 is the upper edge) +- The name has at least one distinguishing letter or letter combination +- The brand has high enough recognition that the wordmark alone signals identity +- The category rewards type-led restraint (editorial, financial, professional services) +- There is room and willingness to pay for custom letterform work + +### When this fails + +- The name is long (10+ letters) and the wordmark cannot fit common contexts +- The category demands instant visual recognition (consumer goods at shelf, app icons) +- The wordmark's letterforms are generic and the brand cannot afford custom drawing +- The brand has no fallback mark for square contexts, social profiles, embroidery +- The wordmark looks identical to many other brands' wordmarks in the same category + +### Combining in a hierarchy + +Wordmark-only as the primary requires a separate symbol-grade asset for square and small contexts. The most common production setup pairs a wordmark with a letterform-as-symbol fallback. Pinterest does this: the wordmark is the primary, the "P" inside a circle is the avatar mark. Stripe does this with a custom geometric "S" for the favicon. The fallback shares visual DNA with the wordmark (same weight class, same custom letterform language) so the system reads as one mark with two surfaces. + +--- + +## Lockup (wordmark plus symbol) + +A wordmark and a symbol locked into a fixed relationship. Slack, Airbnb, Asana, Spotify, MasterCard. This is the default architecture for most brands because it covers the widest range of application contexts with the fewest fallbacks. + +Lockups have variants. Symbol-left-of-wordmark is most common (left-to-right reading languages naturally pull the eye to the symbol first, then the wordmark). Symbol-above-wordmark works when the symbol is tall and narrow or when the lockup must fit a vertically constrained space. Symbol-right-of-wordmark is rare and usually reserved for editorial or signature treatments. Each lockup also tends to have a stacked alternate (symbol above wordmark, centered) for square contexts and an isolated symbol-only fallback for the smallest applications. + +The construction discipline is geometric. The symbol's optical weight should match the wordmark's stroke weight. The space between symbol and wordmark should be tied to the wordmark's x-height or cap height (e.g., the gap equals one x-height of the wordmark). Slack's lockup uses a tightly proportioned hash symbol whose stroke matches the wordmark's stroke at every weight, and the gap is sized to the wordmark's x-height. Without this geometric discipline, lockups fall apart at scale: stretched at large sizes, crowded at small ones. + +### When this fits + +- The brand needs a symbol-grade asset alongside the wordmark +- The wordmark alone is not distinctive enough at small sizes +- The category benefits from a symbol's ability to travel beyond text contexts (apps, signage, branded merchandise) +- The brand will deploy both the symbol and the lockup in different contexts +- The brand has the budget for two finished assets (symbol and wordmark) instead of one + +### When this fails + +- The lockup falls apart at small sizes because the symbol carries detail that disappears +- Symbol and wordmark visually compete (different weight class, different optical density) +- The lockup has no stacked alternate for square contexts +- The brand uses the lockup at favicon scale, where the symbol-only or letterform-as-symbol fallback should carry +- The symbol is too literal or too abstract for the wordmark's tonal register + +### Combining in a hierarchy + +The most common production hierarchy: lockup primary, symbol-only fallback for square and small contexts (social profile, app icon, favicon at 24-32px), letterform-as-symbol or monogram for embroidery and 16px favicon. Slack ships exactly this: the lockup for marketing surfaces, the hash symbol alone for app icons, a simplified hash for favicon and embroidery. The hierarchy is one identity expressed across three asset grades. + +--- + +## Symbol only + +The mark is a symbol with no accompanying wordmark in the primary asset. Apple, Twitter (the bird era and the X era), Target, Nike's swoosh, Mercedes-Benz, Mastercard's circles. This is the highest-recognition tier and is almost never available to new brands. + +Symbol-only as the primary mark requires brand recognition the audience already holds. Apple did not start as symbol-only; the original Apple logo was a Newton-under-an-apple-tree illustration with the word "Apple Computer Co." beside it. The bitten apple symbol earned its standalone status across decades of advertising, product placement, and cultural ubiquity. New brands that try to launch as symbol-only typically fail to break through the recognition barrier and end up adding their wordmark back into the primary lockup. + +The exception is brands launching with massive marketing budgets that can purchase recognition directly. Some legacy financial and luxury brands (Mercedes-Benz, Mastercard) achieved symbol-only status by spending decades and billions on awareness. New brands attempting the same path almost always fail. + +### When this fits + +- The brand has decades of recognition and the symbol carries the brand alone +- The brand is in a category where symbols travel further than wordmarks (sports apparel, automotive, luxury goods) +- The symbol is distinctive enough that no other brand uses anything similar +- The brand has secondary contexts (signage, packaging, apparel) where wordmark space is not available +- The brand can afford the multi-decade investment in recognition + +### When this fails + +- The brand is new and lacks the recognition required for symbol-only to read as the brand +- The symbol is generic (a hexagon, a triangle, a circle) and could belong to thousands of other brands +- The brand has not invested in recognition through advertising or distribution +- Symbol-only is chosen as the primary because the wordmark is too long, when the real solution is a different architecture entirely +- The category demands wordmark presence (B2B SaaS, professional services, anything where the brand name needs to register before the symbol does) + +### Combining in a hierarchy + +Symbol-only is rarely the only asset. Even Apple ships a wordmark for legal contexts, contractual documents, marketing surfaces where the wordmark adds clarity. The hierarchy for symbol-only-primary brands is: symbol primary, wordmark for legal and contextual surfaces, lockup for select marketing applications. The symbol carries; the wordmark plays a supporting role. + +--- + +## Letterform-as-symbol + +A single letter from the brand name (often the first) is treated as the symbol. The letter is custom-drawn or aggressively styled to read as both letter and visual element. Beats by Dre's "b", McDonald's "M", Underscore's "_", a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. + +The cleanest path to symbol when the full wordmark is too long for a tight lockup, when the name has a letter that lends itself to visual play, or when the brand wants the symbol and the wordmark to share construction. Beats's "b" inside a circle is the exact "b" weight and proportion as the rest of the wordmark; the symbol IS the same lettering language. McDonald's "M" reads as the golden arches and as the letter; both readings are simultaneous and reinforce each other. + +The discipline is the silhouette test on the underlying letter. If the letterform is over-styled and the silhouette no longer reads as the letter, the symbol fails one direction of its job. If the letterform is under-styled and reads as just a typed letter, the symbol fails the other direction. The custom letterform must do double duty. + +### When this fits + +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to read as one identity +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands +- The brand needs a small-size and embroidery-friendly fallback that derives from the wordmark + +### When this fails + +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it +- The brand uses the letterform-as-symbol at sizes where it is illegible + +### Combining in a hierarchy + +A common setup: lockup primary, letterform-as-symbol for square contexts and embroidery, full wordmark for legal and large-format contexts. Beats does this. The letterform-as-symbol is the favicon, the app icon, the embroidered patch on Beats apparel. The wordmark in lockup is the marketing primary. The hierarchy makes one identity across asset grades. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol is the initials, often with ligature treatment, tight kerning, geometric framing (ring, shield, diamond), or stacked composition. CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent). + +Common in legal, financial, hospitality, fashion, and heritage brands where institutional gravity is the positioning. A monogram says "we have a long name" and "we own the initials of that name". It also says "we are old enough that abbreviating is acceptable", which is a positioning move. + +Monograms come in three flavors. Pure ligature (the letters share strokes; CN and GG are ligatures). Stacked or geometrically framed (the letters sit inside a ring, shield, or diamond; HBO is framed; YSL is geometrically composed). Tight kerning with no framing (the letters are simply set together with optical adjustments; VW reads as initials without frame). + +### When this fits + +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit (M and N, C and N, V and W work; I and J or O and U are harder) +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +### When this fails + +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials +- The brand uses the monogram alone in contexts where the audience does not yet recognize the initials + +### Combining in a hierarchy + +The classic hierarchy is: full wordmark for marketing primary, monogram for square contexts (social profile, embroidery, foil stamp, signet, wax seal), lockup with both wordmark and monogram for transitional surfaces (letterhead, business card, signage). Chanel, Gucci, and most luxury houses ship exactly this. The monogram is the most-applied mark on physical goods (apparel, hardware, bottles), the wordmark is the most-applied mark on digital and marketing surfaces, and the lockup is reserved for specific institutional surfaces. + +--- + +## Putting it together: the three-asset working pattern + +For most brands, the working asset hierarchy is three marks: + +1. **Primary lockup** for marketing, web, packaging, signage. Wordmark plus symbol locked into a fixed relationship. +2. **Stacked or square alternate** for social profiles, app icons, square contexts. Same elements as the lockup but recomposed for square. +3. **Small-grade fallback** for favicon, embroidery, foil stamps. A single element (symbol-only, letterform-as-symbol, or monogram) that derives from the lockup. + +All three must share visual DNA. Same letterform language, same construction grid, same optical weight class. A brand whose three marks read as three different brands has a system problem, not a logo problem. The discipline is to design the small-grade fallback FIRST, before the lockup, so the constraints of the smallest application drive the construction of the largest. diff --git a/dist/pi/.agents/skills/logo-design/references/category-conventions.md b/dist/pi/.agents/skills/logo-design/references/category-conventions.md new file mode 100644 index 0000000..6533083 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/category-conventions.md @@ -0,0 +1,489 @@ +# Category conventions + +Every category has a default visual register the audience expects. Working inside the default signals competence; the brand reads as belonging. Working outside the default signals positioning; the brand reads as making a deliberate move. Both are legitimate. The trap is doing either by accident. + +This file surveys ten major brand categories at parity. For each: the defaults that work, the conventions worth honoring, the conventions worth breaking for positioning, the cliches to avoid, the application contexts unique to the category, and reference brands as visual shorthand. + +--- + +## 1. Legal firms + +The category is dominated by heritage positioning. White-shoe firms, century-old partnerships, names tied to founding partners' surnames. The audience reading the logo is general counsel, founders raising or selling, CFOs in industries where the wrong attorney is materially expensive. The buyer brings high stakes and trusts visual signals of institutional gravity. + +### Defaults that work + +- **Old-style or transitional serif typography** for the wordmark. Garamond, Caslon, Sabon, Source Serif. The serif reads as institutional and serious. +- **Lockup with monogram** OR **wordmark with monogram fallback**. The full firm name is often long (multiple partner surnames) so the monogram does heavy lifting in constrained contexts. +- **Restrained color palette.** Navy, deep charcoal, oxblood, deep forest green. No primary red, no bright blue, no anything that reads as casual. +- **Single-color reproduction** built into the system from day one (court filings reproduce in black on white, foil stamps on letterhead are common, embossed signage on lobby walls). + +### Conventions worth honoring + +- Heritage signaling through old-style serif type and monogram architecture +- Single-color reproducibility for court filings and formal documents +- Geometric framing (ring, shield) only in restrained executions; heavy ornament reads as fake heritage + +### Conventions worth breaking for positioning + +- Geometric sans for the wordmark signals "modern, accessible" (boutique firms, tech-adjacent practices, plaintiff-side firms) +- Lighter color palette signals approachability (firms competing for client comfort, not gravity) +- Asymmetric lockup signals contemporary execution (firms positioning against the traditional white-shoe model) + +### Common cliches to avoid + +- The Roman-pillar-as-justice. Pillars are exhausted. +- The scales-of-justice icon. Done thousands of times; signals nothing. +- The gavel. Cliche. +- The lady-Justice silhouette. Same. + +### Application contexts unique to the category + +- Court filings (single-color black on white at small scale) +- Embossed letterhead and business cards (the foil-stamp test is real) +- Lobby and conference room signage (engraved brass, etched glass) +- Email signatures with the firm wordmark and individual attorney name +- Billable-hours invoices (the wordmark must look reproducible at low quality) + +### Reference brands + +- **Latham & Watkins** (LW monogram in serif, conservative palette) +- **Wachtell, Lipton, Rosen & Katz** (full firm name as wordmark, no symbol; positioning as "we don't need a symbol") +- **Skadden, Arps, Slate, Meagher & Flom** (Skadden monogram, restrained sans) + +--- + +## 2. Consumer goods / CPG + +The category is dominated by retail competition. The mark must register at shelf distance (10 to 15 feet), at thumbnail scale (online product imagery), and at rapid scan speed (the shopper has 2 seconds per shelf section). Distinctiveness is survival. + +### Defaults that work + +- **Custom display typography** for the wordmark. The brand owns its letterforms because the wordmark is on every package. +- **Lockup with literal symbol** OR **strong wordmark only**. The symbol depicts what the brand is about; the wordmark carries the brand name. +- **Bold color palettes.** Bright colors register at distance. Restraint is the exception. +- **Pattern systems** that extend the brand identity onto packaging surfaces. + +### Conventions worth honoring + +- Distinctiveness at small scale (online product thumbnails, 80x80 pixels) +- Single-color or simplified versions for embossed packaging, foil stamps, hot-metal printing +- Color recognition: the brand color is the first signal on shelf, before the wordmark even reads + +### Conventions worth breaking for positioning + +- Restrained typography signals premium positioning (Method, Brandless, Aesop) +- Black-and-white-only signals minimalist or anti-CPG positioning +- Hand-drawn or organic letterforms signal craft or small-batch positioning + +### Common cliches to avoid + +- The swoosh-as-growth. Borrowed from Nike. +- The leaf-as-natural. Done thousands of times in wellness and organic. +- The dot-or-circle-as-modernity. The 2010s startup tier. +- The hand-drawn brushstroke under the wordmark. Saturated. + +### Application contexts unique to the category + +- Retail packaging at shelf scale +- Online product thumbnails (80x80 to 200x200 pixels) +- Print catalog imagery (offset print, sometimes single-color) +- In-store signage and end-cap displays +- Branded merchandise (hats, totes, t-shirts the brand sells) + +### Reference brands + +- **Method** (custom geometric sans, restrained palette, premium positioning in a category dominated by aggressive color) +- **Hu Chocolate** (hand-drawn wordmark, organic typography, craft positioning) +- **Brandless** (anti-brand brand: minimalist sans, monochrome, the wordmark IS the absence of conventional branding) + +--- + +## 3. B2B SaaS + +The category is dominated by visual interchangeability. Most B2B SaaS brands use neo-grotesque sans typography, geometric reduction symbols, and a primary color in the blue-to-purple range. The mark blurs into the category default unless the brand makes deliberate distinguishing choices. + +### Defaults that work + +- **Neo-grotesque sans typography** (Inter, Söhne, GT America, custom). The default register reads as competent and contemporary. +- **Lockup with abstract or geometric-reduction symbol**. The symbol carries small-size and app-icon contexts. +- **Single-accent color palette.** A primary brand color plus monochrome, no busy palette. +- **Custom letterform** in the wordmark to escape the interchangeable default. + +### Conventions worth honoring + +- Screen rendering optimization (the wordmark must read at every screen size and DPI) +- App icon construction (the symbol must work inside rounded-square and circle masks) +- Monochrome reproducibility (single-color and reverse-on-dark should both work) + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in SaaS; positions against the modern startup tier) +- Bright primary color (red, orange, yellow) signals energy in a category that defaults to blue and gray +- Custom display typography signals long-term brand investment in a category where most brands look interchangeable + +### Common cliches to avoid + +- The geometric hexagon. The most overused symbol in tech. +- The three-bars stacked horizontally. The 2018-2020 SaaS tier. +- The triangle pointing right. Done. +- The bisected circle. Same. +- The single-letter-inside-circle without distinctive letterform construction. + +### Application contexts unique to the category + +- App icons (iOS, Android, web app, browser extension) +- Marketing site at desktop scale +- Documentation site at small scale (favicon, header, footer) +- In-product brand display (loading screens, empty states, account avatars) +- Slack and email integration logos (small thumbnails) + +### Reference brands + +- **Stripe** (custom Sohne wordmark, abstract gesture symbol, restrained palette) +- **Linear** (Inter wordmark, geometric reduction symbol, signature single-color execution) +- **Vercel** (custom Geist wordmark, geometric reduction triangle, bold black-and-white) +- **Notion** (custom letterform with notebook reference) + +--- + +## 4. Hospitality (hotels, restaurants, resorts) + +The category sits between heritage luxury and contemporary craft. The audience experiences the brand across many surfaces simultaneously: building exteriors, interior signage, room key cards, menus, uniforms, towels, sheets, packaging. Multi-surface coherence is the discipline. + +### Defaults that work + +- **Custom display typography** OR **transitional serif** for the wordmark. The brand often becomes the visual identity of the property. +- **Lockup with monogram fallback**. The monogram appears on towels, sheets, room keys, embroidered uniforms. +- **Restrained palette** with a single signature color. The palette extends to interior design, materials, lighting. +- **Embroidery-grade variant** built into the system from day one. + +### Conventions worth honoring + +- Embroidery on uniforms, towels, robes, sheets (the monogram does this work) +- Foil-stamp on stationery, room key cards, room service menus +- Engraved or etched signage on building exteriors and interior wayfinding +- Restraint in palette (heritage hospitality avoids loud color) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "boutique, design-forward" (Ace Hotel, Standard Hotels) +- Bold color signals contemporary or playful positioning +- Asymmetric lockup signals contemporary execution +- Display custom typography signals investment in a unique brand identity + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in heritage hospitality. +- The shield-with-year-founded. Every craft beer label uses this. +- The crossed-keys (Hermes-derived). Done. +- The mountain-or-palm-tree literal symbol for resort properties. Done. + +### Application contexts unique to the category + +- Building exterior signage (channel letters, illuminated) +- Room key cards (foil stamp on plastic or paper) +- Towels, robes, sheets (embroidery) +- Glassware, china, silverware (etched, engraved) +- Stationery (letterhead, envelopes, business cards, foil stamp) +- Uniforms (embroidered name tags and lapel pins) +- Bag tags and luggage labels + +### Reference brands + +- **Aman Resorts** (restrained typographic identity, Asian-influenced design discipline) +- **Soho House** (custom display typography, monogram primary, modern member-club positioning) +- **Ace Hotel** (custom display typography, contemporary boutique positioning, regional variation across properties) + +--- + +## 5. Healthcare + +The category is dominated by trust signaling. The audience may be anxious, stressed, or grieving. The brand must read as competent and calm without reading as cold or clinical. Trust is built through restraint, not through aggressive visual claims. + +### Defaults that work + +- **Humanist sans typography** for the wordmark. The calligraphic warmth carries trust. +- **Lockup with abstract gesture symbol**. The symbol suggests care, balance, or healing without depicting it literally. +- **Calm color palette.** Blue, green, soft warm neutrals dominate. +- **Plenty of whitespace** in the brand system. Density reads as anxiety. + +### Conventions worth honoring + +- Accessibility floor: WCAG AA contrast ratios on every brand color combination +- Restrained palette: no aggressive red (reads as emergency or alarm) +- Avoid imagery that could be misread (a symbol that suggests a religious cross when the brand is secular, a symbol that suggests a specific medical specialty when the brand is generalist) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "tech-forward primary care" (One Medical, Forward) +- Warmer color palette (coral, peach, soft yellow) signals "we are not your old doctor's office" +- Custom display typography signals contemporary positioning (rare in legacy healthcare) + +### Common cliches to avoid + +- The medical cross. Trademark-protected by the Red Cross in some uses; otherwise generic. +- The caduceus (snakes around a staff). Misread by audiences as Hermes; not actually the medical symbol. +- The heartbeat-line. Saturated in fitness and healthcare. +- The blue-and-green gradient. The default healthcare palette to a fault. + +### Application contexts unique to the category + +- Wayfinding signage in clinics and hospitals +- Patient-facing materials (intake forms, appointment reminders, billing statements) +- Medical equipment branding (the wordmark on a screen, on a printed report) +- Insurance and billing communications (the wordmark on bills the patient hopes are accurate) +- Clinic uniforms and badges + +### Reference brands + +- **One Medical** (humanist sans wordmark, simplified circle symbol, restrained palette, primary care positioning) +- **Forward** (custom display typography, geometric reduction symbol, tech-forward primary care) +- **Hims** (custom geometric sans, single-color execution, modern men's health positioning) + +--- + +## 6. Financial services + +The category splits between heritage and fintech-modern. Heritage banks (Goldman Sachs, JPMorgan, Morgan Stanley) lean into old-style serif and institutional gravity. Fintech challengers (Ramp, Mercury, Stripe) lean into neo-grotesque sans and modern restraint. The split is itself a positioning decision. + +### Defaults that work + +- **Old-style serif** OR **neo-grotesque sans** (the heritage-vs-fintech axis) +- **Lockup with monogram fallback** (heritage) OR **wordmark with abstract symbol** (fintech) +- **Restrained palette.** Navy, gold, deep green for heritage. Black, white, single-accent for fintech. +- **Single-color reproducibility** built into the system (foil stamps, embossed checks, single-color regulatory documents) + +### Conventions worth honoring + +- Single-color reproducibility (foil stamps, regulatory filings, embossed checks) +- Trust signals through restraint and material quality (heavy paper, foil stamps) +- Color choice signals heritage (navy, gold, deep green) vs fintech (black, white, electric accent) + +### Conventions worth breaking for positioning + +- Modern geometric sans in heritage financial services signals "boutique, contemporary" (rare and high-stakes) +- Bright color in heritage financial services signals "we are not your father's bank" (high-risk positioning) +- Old-style serif in fintech signals "we take regulatory compliance seriously" (positions against fast-and-loose fintech) + +### Common cliches to avoid + +- The eagle-as-strength. Heritage cliche. +- The shield-as-security. Cliche across heritage and fintech. +- The bull-as-bullish. Wall Street cliche. +- The geometric chevron pointing up. Fintech cliche. +- The blue-and-gold gradient. Heritage default that reads as visually unconsidered. + +### Application contexts unique to the category + +- Embossed credit and debit cards (the mark is impressed, not printed) +- Regulatory filings and disclosures (single-color reproduction) +- Bank checks (single-color print, MICR-encoded routing numbers) +- Branch signage (channel letters, illuminated) +- ATM screens and branded interfaces + +### Reference brands + +- **Goldman Sachs** (old-style serif wordmark, restrained palette, heritage positioning) +- **Ramp** (custom Söhne wordmark, abstract symbol, modern restrained palette) +- **Mercury** (custom geometric sans, abstract gesture symbol, fintech positioning with restraint) + +--- + +## 7. Editorial / publishing + +The category is dominated by typography. The masthead IS the logo. Most editorial brands have no separate symbol; the wordmark in a specific custom serif IS the entire identity. The discipline is letterform and proportional refinement. + +### Defaults that work + +- **Custom display typography** OR **old-style serif** OR **transitional serif** for the wordmark +- **Wordmark only** OR **wordmark with monogram fallback** +- **Black-on-white** as the default reproduction (newsstand, print, digital header) +- **Restrained palette** (typically a single accent color, often the brand's signature) + +### Conventions worth honoring + +- Single-color reproducibility (every newspaper masthead must work in black on white at masthead scale) +- Custom letterform investment (the masthead is the brand's most-rendered asset) +- Typographic heritage (the masthead often references the publication's founding-era typography) + +### Conventions worth breaking for positioning + +- Geometric sans signals contemporary editorial (Vox, BuzzFeed, Vice attempted versions of this) +- Bold color signals contemporary positioning (rare in legacy editorial) +- Modern asymmetric layouts signal contemporary craft + +### Common cliches to avoid + +- The blackletter masthead. Saturated for newspapers; reads as German tabloid. +- The decorative initial cap drop. Editorial cliche. +- The pen-nib symbol for writing or journalism brands. Cliche. +- The book-and-ribbon. Cliche. + +### Application contexts unique to the category + +- Newsstand at street scale (the masthead must read at 50 to 100 feet) +- Print body and headline typography (the wordmark sits at the top of every printed page) +- Digital masthead at desktop and mobile scale +- Subscription and renewal direct mail (single-color print) +- Cover photography (the masthead overlays photographic backgrounds) + +### Reference brands + +- **The Atlantic** (custom transitional serif, restrained palette, editorial heritage) +- **The New Yorker** (custom Caslon-derived masthead, the mark is unmistakable) +- **Cereal** (custom display sans, considered minimalism, contemporary editorial) + +--- + +## 8. Tech / AI + +The category is dominated by abstract gesture and geometric reduction. Most AI and tech brands lean into one of two modes: either neo-grotesque sans with abstract gesture symbol (Anthropic's flower, OpenAI's geometric mark) or aggressive geometric reduction (every blockchain logo, every web3 brand). Visual fatigue in the category is real. + +### Defaults that work + +- **Neo-grotesque sans** OR **custom geometric sans** for the wordmark +- **Lockup with abstract gesture or geometric reduction symbol** +- **Single-accent color palette.** Often the brand's "signature color" plus monochrome. +- **Construction grid discipline** in the symbol + +### Conventions worth honoring + +- Screen rendering optimization (the brand lives on screens at every size) +- App icon construction (rounded-square and circle masks, every iOS/Android size) +- Monochrome and reverse-on-dark variants + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in tech, signals against the dominant aesthetic) +- Hand-drawn or organic letterforms signal craft or human-centered positioning +- Bright primary color signals energy in a sea of muted palettes + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain. The most overused symbol in crypto. +- The neural-network-circles symbol for AI brands. Done thousands of times. +- The brain-with-circuit-traces. Cliche. +- The triangle-with-an-eye. Cliche. +- The default purple gradient. The 2018-2022 tech tier. + +### Application contexts unique to the category + +- Developer documentation sites (the wordmark sits in dense technical contexts) +- API and CLI integrations (the brand appears in terminal output, error messages, log lines) +- Loading screens and empty states in product +- Open-source repository profile pictures +- Conference talk slide branding + +### Reference brands + +- **Anthropic** (custom display typography, abstract gesture symbol, restrained palette) +- **OpenAI** (custom geometric mark, simple wordmark, monochrome execution) +- **Hugging Face** (custom emoji-as-symbol, distinctive in a category that doesn't usually allow it) + +--- + +## 9. Outdoor / lifestyle / apparel + +The category sits at the intersection of illustration, heritage, and embroidery. Many outdoor brands use illustration-driven marks with hand-drawn or vintage-inspired execution. The application context is frequently embroidered (apparel, hats, packs) so the mark must survive thread on fabric. + +### Defaults that work + +- **Custom display typography** OR **slab serif** for the wordmark +- **Lockup with literal symbol** depicting the brand's outdoor world (mountain, river, tree, animal silhouette) +- **Heritage color palette.** Earth tones, warm reds, deep greens, cream-and-coffee +- **Embroidery-grade variant** built into the primary system + +### Conventions worth honoring + +- Embroidery on apparel, hats, and packs (the mark must survive 4-6 colors on thread) +- Patch-friendly construction for hats and uniforms +- Hand-drawn or vintage-inspired execution that signals craft and authenticity +- Color palette referencing the brand's outdoor environment + +### Conventions worth breaking for positioning + +- Modern geometric sans signals contemporary outdoor (Topo Designs, Outdoor Voices) +- Bright color signals younger or athletic positioning +- Wordmark-only signals premium or design-led positioning (rare) + +### Common cliches to avoid + +- The bear silhouette. Saturated for outdoor and lifestyle. +- The mountain peak with a sun rising. Done. +- The compass rose. Saturated for travel and outdoor. +- The Pacific-Northwest cabin aesthetic. Saturated since 2015. +- The tent silhouette. Cliche. + +### Application contexts unique to the category + +- Apparel embroidery (hats, polos, jackets, packs) +- Patch embroidery (jackets, packs, vests) +- Heat-transfer printing on technical fabrics +- Hangtags and care labels on apparel +- Retail signage at small specialty stores + +### Reference brands + +- **Patagonia** (custom display typography, Fitz Roy mountain silhouette, signature gradient palette) +- **REI** (custom slab serif wordmark, the wedge symbol, outdoor heritage positioning) +- **Filson** (custom slab serif, monogram and shield treatments, heritage workwear positioning) +- **Topo Designs** (custom display typography, contemporary outdoor positioning, designed in Colorado) + +--- + +## 10. Fashion / luxury + +The category is dominated by monogram and ligature conventions. Most heritage luxury brands use monograms (Chanel CN, Gucci GG, Yves Saint Laurent YSL, Louis Vuitton LV). Modern accessible-luxury brands lean toward custom display typography (The Row, Aimé Leon Dore, Jacquemus). The split is the positioning question. + +### Defaults that work + +- **Old-style serif** OR **custom display typography** OR **ligature monogram** for the primary mark +- **Lockup with monogram fallback** OR **wordmark with monogram on goods** +- **Restrained palette.** Black, white, gold, and the brand's signature accent +- **Embroidery-grade variant** for apparel and accessories + +### Conventions worth honoring + +- Embroidery on apparel and accessories (the monogram does this work) +- Foil stamp and emboss on packaging (the wordmark or monogram impressed in metallic foil) +- Material quality (heavy paper, leather, metallic foil) +- Restraint in palette and ornamentation + +### Conventions worth breaking for positioning + +- Modern geometric sans signals accessible-luxury (The Row, Aimé Leon Dore lean restrained-modern) +- Bright color signals contemporary or playful luxury (rare and risky) +- Hand-drawn or expressive letterforms signal craft positioning + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in fashion and hospitality. +- The decorative monogram with filigree. Reads as Renaissance Faire, not as Hermès. +- The shield-with-year-founded. Done. +- The gold-foil-with-Old-English-typeface. Cliche fake-heritage. + +### Application contexts unique to the category + +- Apparel embroidery (logos, monograms, signatures stitched into garments) +- Hardware embossing (buttons, rivets, zipper pulls, leather goods) +- Foil stamp on packaging (boxes, dust bags, ribbon) +- Engraved or etched hardware (jewelry, watches) +- Vellum and tissue paper printing (gift wrap, bag liners) +- Window displays at flagship stores + +### Reference brands + +- **Chanel** (CN monogram, no symbol beyond initials, the most institutionally consistent fashion brand) +- **Gucci** (GG monogram, custom display typography for the wordmark) +- **The Row** (custom display typography, restrained accessible-luxury positioning) +- **Aimé Leon Dore** (custom display typography, contemporary heritage positioning, restrained monogram on apparel) + +--- + +## How to use this file + +When designing for a category not your own, start with the defaults. They exist because they work. The audience reads them as competence. + +When designing for a category you want to position against, identify which convention you are breaking and why. The break should be deliberate and supported by the rest of the brand system. A boutique law firm in geometric sans signals modern positioning IF the rest of the brand (color, photography, voice, materials) also signals modern positioning. Breaking type without breaking the rest of the system reads as random. + +When designing without category context, the defaults are still the right starting point. Most brands sit inside a category. Most brands benefit from being recognizable inside that category before they push for distinctiveness. Distinctiveness without belonging reads as outsider; belonging without distinctiveness reads as forgettable. The discipline is to start with the category default and earn each departure. diff --git a/dist/pi/.agents/skills/logo-design/references/client-package.md b/dist/pi/.agents/skills/logo-design/references/client-package.md new file mode 100644 index 0000000..e41adf0 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/client-package.md @@ -0,0 +1,187 @@ +# Logo client package + +The package format clients expect when handing logo work back. The discipline here is doing the boring work upfront so the client never has to ask for "the SVG version" or "a small one for favicons" or "white-on-dark for the slide deck." + +## When this applies + +- Final delivery of logo work to a client (internal or external) +- Mid-project handoff where another team needs to start building against the mark +- Brand-refresh deliverables where existing applications need to update + +## When this does NOT apply + +- Concept presentation. Concept stage is for direction-setting, not delivery. Concept decks include 2-3 mark variations with rationale, not a full package. +- Style-guide level brand systems. The client package is the deliverable for the mark itself; a brand-style-guide is a separate concern covering color, type, voice, photography, motion. See the brand-style-guide skill. +- Individual application-specific exports. If the client needs a 2400x1260 LinkedIn cover image with the mark composed against a photo, that is a one-off design request, not a package update. + +## The package format + +### File formats (the matrix) + +Every variant ships in formats that cover the contexts the client will actually use: + +| Format | Use case | Notes | +|---|---|---| +| SVG | Web, scalable applications, modern email clients | Primary delivery format. Vector. | +| AI or EPS | Editable source for designers | Source file. Layered if the mark has multiple components. | +| PDF | Print, vector applications, archival | Vector. Embedded fonts or outlined. | +| PNG (transparent) | Web, slide decks, raster contexts where background is unknown | Multiple sizes: 64, 128, 256, 512, 1024, 2048. | +| JPG | Email signatures, contexts where transparency is not supported | Solid background; usually white. Single size, 1024px wide. | +| ICO | Favicon | Multi-resolution: 16x16, 32x32, 48x48 packed into one file. | +| Apple touch icon (PNG) | iOS home-screen bookmarks | Single size, 180x180. | + +The asymmetry matters. Vector formats (SVG, AI, PDF) are the source of truth; raster formats (PNG, JPG, ICO) are derived from the vector source at delivery time. Never deliver only raster; clients eventually need to scale up and they cannot. + +### Variant matrix + +The client gets every meaningful combination of the variant axes: + +**Color treatment:** +- Primary (full color, the canonical mark) +- Reverse (white on dark, for dark backgrounds) +- Mono black (single black, for grayscale or low-fidelity contexts) +- Mono white (single white, for full-bleed dark photography) +- Mono brand (single color in the brand color, for one-color print) + +**Composition (where the mark has multiple lockups):** +- Primary lockup (the canonical composition, usually horizontal) +- Stacked (vertical, for narrow contexts like favicons or app tiles) +- Symbol-only (when the wordmark is unavailable or unnecessary, like profile avatars) +- With tagline (where a tagline is part of the mark system) +- Without tagline + +The client gets every relevant combination. A simple wordmark might have 5 variants total (primary across 5 color treatments). A complex lockup with tagline plus symbol variants might have 30+. Either way: the matrix is exhaustive within the system, not arbitrary. + +### Folder structure + +Organized so the client can find what they need without thinking: + +``` +{brand-name}-logo-package/ +├── 01-primary/ +│ ├── primary-color.svg +│ ├── primary-color.ai +│ ├── primary-color.pdf +│ ├── primary-color-2048.png +│ ├── primary-color-1024.png +│ ├── primary-color-512.png +│ ├── primary-color-256.png +│ ├── primary-color-128.png +│ ├── primary-color-64.png +│ └── primary-color.jpg +├── 02-reverse/ +│ └── (same format set, white-on-dark) +├── 03-mono/ +│ ├── mono-black/ (full set) +│ ├── mono-white/ (full set) +│ └── mono-brand/ (full set) +├── 04-stacked/ +│ └── (same format set, vertical lockup) +├── 05-symbol/ +│ └── (symbol-only variants if applicable) +├── 06-favicon/ +│ ├── favicon.ico +│ ├── apple-touch-icon.png +│ ├── favicon-16.png +│ ├── favicon-32.png +│ └── favicon-48.png +├── 07-applications/ +│ ├── business-card-mockup.pdf +│ ├── letterhead-mockup.pdf +│ ├── email-signature.png +│ └── social-avatar.png +├── 08-documentation/ +│ ├── usage-guide.pdf +│ ├── brand-colors.pdf +│ └── license.pdf +└── README.md +``` + +Numbered prefixes ensure the client opens folders in the order that matches how they will use them. Documentation last because nobody reads it first; applications second-to-last because they are reference, not deliverable. + +### File naming convention + +Inside each folder, files follow this pattern: + +``` +{variant}-{color}-{size or context}.{ext} +``` + +Examples: +- `primary-color.svg` +- `primary-color-2048.png` +- `reverse-white.svg` +- `mono-black-1024.png` +- `stacked-color.pdf` +- `symbol-color.svg` + +Consistent naming means the client can guess a filename before looking. + +## The documentation layer + +Inside `08-documentation/`: + +### usage-guide.pdf + +Covers: +- **Clear space**: minimum padding around the mark, expressed as a multiple of a recurring element (often the x-height of the wordmark or the diameter of the symbol) +- **Minimum size**: smallest legible application, with explicit size for digital (px) and print (mm or in) +- **Do's**: contexts where the mark works +- **Don'ts**: stretching, recoloring outside the variant set, rotating, applying effects (drop shadow, gradient, embossed), placing on busy photography without sufficient contrast, replacing the typography in a wordmark +- **Co-branding rules**: how the mark composes with partner marks, including spacing and order + +A usage guide that just lists the variants is documentation theater. The do's-and-don'ts section is what protects the mark in the wild. + +### brand-colors.pdf + +Color values for every meaningful representation: +- Hex (web) +- RGB (digital) +- CMYK (print) +- Pantone (spot color print) +- HSL (where the brand has a programmatic color system) + +If the mark uses gradients, document the gradient stops and direction explicitly. Gradients vary in unpredictable ways across rendering engines; precise documentation is the only protection. + +### license.pdf + +Covers: +- Who owns the mark (usually the client) +- Who the designer is (for attribution, if required) +- Usage terms (typically: client has full and exclusive use; designer retains the right to display in portfolios) +- Modification rights (typically: client cannot modify without designer consent during a defined warranty period; after that, all rights to modify pass to the client) +- Successor terms (what happens if the client sells the brand or merges with another company) + +License documentation is the part most independent designers skip and most agencies overformat. The middle path is a 1-page document that names the parties, defines usage, and is signed. + +## Delivery mechanisms + +Three patterns, in increasing formality: + +**ZIP archive over email.** Smallest projects. The client gets a single `.zip`, downloads, expands, drops into their workspace. Works for packages under ~50 MB. Watch out for email size limits. + +**Cloud storage link.** Most common pattern. Drive, Dropbox, Box, OneDrive. Client gets a link, downloads at leisure, can re-share within their organization. Set link to view-only with download enabled. Set an expiration date if warranty terms are time-bound. + +**Brand portal.** Largest projects. Paid tools like Frontify, Brandfolder, Brandkit. The portal becomes the canonical source of truth; the client gets logins for stakeholders. Worth the cost when there are 10+ internal stakeholders downloading assets ad hoc, or when the brand system has dozens of marks (parent plus sub-brands). + +Match the mechanism to the client's actual workflow, not their stated preference. Clients will say they want a brand portal, then download the ZIP and never log in to the portal again. + +## Failure patterns + +**Delivering only raster.** PNG-only or JPG-only packages mean the client cannot scale up cleanly. Always include vector. If the work was done in raster (rare for logo work, but it happens), trace to vector before delivery. + +**Delivering only the primary variant.** A primary-mark-only package fails the moment the client needs to put the mark on a dark background or print it in one color. The variant matrix is the deliverable, not an optional extra. + +**Delivering source files without a license document.** Clients who paid for the work expect to own it. Source files (AI/EPS) without an explicit license create ambiguity that surfaces during acquisitions or partnerships. Always include the license PDF. + +**Variant naming drift across the package.** `Primary_Logo_Color.svg` in one folder and `primary-color.svg` in another means the client's tooling (CMS, design system) will not recognize the assets consistently. Pick a convention; apply it everywhere. + +**Skipping the favicon.** Almost every client will host a website. The website needs a favicon. Adding the favicon variant adds one folder; omitting it means the client comes back asking for it. + +**Embedding fonts in the SVG without confirming licensing.** SVG with embedded font glyphs is fine when the font is open-source. When the font is licensed (e.g., a Monotype or Adobe Fonts file), embedding the glyphs may violate the license. Outline the font in the SVG before delivery; the visual remains identical, and the licensing risk disappears. + +## What "done" looks like + +The client opens the ZIP (or the cloud link), sees a numbered folder structure, opens `01-primary/primary-color.svg`, and ships the mark to production within 5 minutes. + +If the client emails back asking "do you have a white version?" or "is there an SVG?" or "can you send the favicon?", the package was incomplete. diff --git a/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md b/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md new file mode 100644 index 0000000..111b6b2 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md @@ -0,0 +1,100 @@ +# Example variant spec + +A fully populated single-variant spec for a fictitious brand, **Atlas Coffee**. Atlas is a hypothetical specialty coffee company sourcing single-origin beans from Latin American producers, roasting in small batches, retailing through a single flagship cafe and an online subscription. The brand brief calls for considered craft positioning, outdoor adjacency without literal outdoor imagery, warmth without rusticity. + +This file shows what one variant looks like when documented for client review. A complete deliverable contains 6 to 12 such variants. The agent uses this format as the per-variant template; the client uses it to evaluate, compare, and select. + +--- + +## Variant 07, Mountain peak A lockup, IBM Plex Sans + +### Architecture + +Lockup. The wordmark sits to the right of a custom letterform-as-symbol "A". The "A" reads as both the first letter of "Atlas" and as a stylized mountain peak. The lockup also has a stacked alternate (the "A" centered above the wordmark) for square contexts and a symbol-only fallback (the "A" alone) for favicon, embroidery, and stamping. + +### Typography + +- **Wordmark typeface.** IBM Plex Sans, Medium weight (500), tracking +5 (10 units, on a 1000-unit em). +- **Custom letterform.** The "A" is a custom drawing, not IBM Plex Sans. The crossbar is replaced with a single horizontal stroke at 38 percent height; the apex rises to a sharp peak; the legs are slightly splayed (8 degrees from vertical) to suggest mountain base width without exaggeration. The custom "A" replaces the typed "A" in the wordmark "Atlas Coffee" so the entire wordmark reads as a unit. +- **Wordmark composition.** "Atlas Coffee" set as one word, with a small visual gap between "Atlas" and "Coffee" (one half x-height of additional spacing) so the eye reads both words as parallel parts of the same name without forcing a hyphen or stacked composition. +- **Optical adjustments.** The "t" of "Atlas" is shortened by 4 units to balance against the rising "A" to its left. The "f" of "Coffee" has its terminal pulled inward by 3 units to prevent it from reading as an extra bar. + +### Symbol description + +The custom "A" is the symbol. The construction is built on a 4-unit grid: + +- Apex height: 4 units, sharp peak +- Crossbar: at 1.5 unit height, single horizontal stroke +- Leg width at base: 4 units, splayed 8 degrees from vertical +- Stroke weight: matches the wordmark's stroke weight at the chosen Medium weight (approximately 90 units on a 1000-unit em) + +The peak silhouette is ungenerous on the apex (sharp, not rounded). The crossbar is single-stroke (no double bars). The legs end with a flat foot, not a serif. At every scale, the silhouette reads first as a peak, then as the letter A. The double-reading test passes. + +### Color tokens + +- **Primary.** Warm charcoal `#2A2521`. The wordmark and the "A" symbol both use this color in standard reproduction. +- **Accent.** Rust `#B85C38`. The accent appears in marketing surfaces (web header backgrounds, packaging trim) but not in the lockup itself. +- **Single-color black.** `#000000`. For court filings is irrelevant; for embossed letterhead, foil stamp on paper, single-color print, fax (yes, still). The mark renders as pure black on white. +- **Single-color white.** `#FFFFFF`. For reverse-on-dark applications (web header in dark mode, signage at night, embossed on dark leather). +- **Reverse-on-dark variant.** White on a dark background; the symbol's negative space inversion is direction-neutral so the mark reads identically in either direction. + +### Application notes + +The variant excels at: +- Large-format signage. The peak silhouette reads at street scale; the wordmark holds at 8 to 12 feet wide. +- Retail packaging. The lockup at coffee bag scale (4 inches wide) is the natural size; the symbol carries the front, the wordmark anchors the side. +- Mug and ceramic stamping. The lockup with stacked alternate works on cylindrical surfaces. +- Embossed letterhead. The custom "A" embossed at the top, the wordmark printed below in standard color. +- Web header at desktop scale (200 to 400 pixels wide). The lockup reads cleanly at this size. + +The variant needs fallbacks at: +- 16 px favicon. The full lockup fails; the symbol-only "A" carries. +- 1.5 inch embroidery patch. The lockup is too wide; the symbol-only "A" with the wordmark stacked below in a chunky weight (e.g., IBM Plex Sans Bold) is the patch variant. +- App icon at 28 to 60 pixels. The symbol-only "A" inside a colored field (warm charcoal background, white "A") is the app icon variant. +- Square social profile. The stacked alternate (the "A" above the wordmark, centered) is the social profile variant. + +Embroidery adaptation: thread color matched to the warm charcoal primary (Madeira Polyneon `1842` is the closest match for the primary, with `1338` for the rust accent). The embroidery-grade variant of the symbol-only "A" requires a 3 unit minimum stroke weight scaled for 1.5 inch patch reproduction. + +### Signals + +- **Considered craft.** The wordmark's optical adjustments (shortened "t", pulled-in "f") signal that the brand has thought about every letterform, which signals that the brand thinks about every other detail. +- **Outdoor / adventure adjacency without literal outdoor imagery.** The mountain peak silhouette references outdoor without depicting a trail, a tree, or a campsite. The audience associates the brand with adventure-adjacent positioning without the brand becoming a Pacific-Northwest cliche. +- **Warmth without rusticity.** The warm charcoal primary and rust accent read as warm but considered. The palette avoids the heritage-coffee browns and the third-wave-minimalist whites; the in-between space signals contemporary craft. +- **Single-origin discipline.** The restrained execution (one symbol, one wordmark, one accent color) signals that the brand chooses few things deliberately. The same discipline appears in single-origin coffee sourcing. + +### Rejects + +- **Not a typical coffee shop laurel mark.** Atlas does not use a laurel wreath, a coffee bean, a coffee cup, or any direct depiction of coffee. The brand is about the experience and origin, not the commodity. +- **Not a third-wave-minimalist wordmark with no symbol.** Many specialty coffee brands have moved toward wordmark-only with no symbol. Atlas chooses a lockup because the brand wants a symbol-grade asset for embroidery, hardware stamping, and merchandise. +- **Not a literal coffee bean.** No bean, no berry, no plant in the symbol. The category cliche is rejected. +- **Not a Pacific-Northwest-cabin aesthetic.** No tree silhouette, no compass rose, no flannel-pattern background. The brand's outdoor adjacency is structural (peak silhouette in the letter), not stylistic. + +### Mockups + +The mockups would be rendered as image assets in a complete deliverable. Described in prose: + +1. **Storefront signage at street scale.** The lockup as channel letters above the cafe entrance, illuminated, mounted on stained wood paneling. The peak silhouette reads from across the street; the wordmark anchors the brand name as visitors approach. + +2. **Retail bag at shelf scale.** The 12 oz coffee bag with the lockup printed at 4 inches wide on the front, the wordmark-only with origin information on the side panel. The symbol's peak references the high-altitude growing regions where Atlas sources beans. + +3. **Espresso cup at table scale.** Double-walled glass cup with the symbol-only "A" stamped in warm charcoal at 1 inch tall on the cup wall. The lockup is on the saucer rim. The customer sees both marks during a 4-minute espresso experience. + +4. **Embroidered apron.** Black cotton apron with the symbol-only "A" embroidered in rust on the chest pocket. The wordmark is embroidered on the back at the lower hem, in warm charcoal thread, smaller scale. The aprons are durable goods that get washed weekly; the embroidery is built for that. + +5. **Social profile picture as stacked mark.** The stacked alternate (the "A" above the wordmark, centered, white on warm charcoal background) renders cleanly inside Twitter/Instagram circle masks at 80 to 400 pixel display sizes. + +--- + +## Notes for the agent reading this file + +This single-variant spec is one of typically 6 to 12 in a complete deliverable. The brand owner reads through all variants, marks preferences, asks questions, and selects 1 to 3 finalists for production refinement. + +The discipline in writing the spec: + +- **Be specific.** "IBM Plex Sans Medium with tracking +5" is specific. "Modern sans-serif" is not. +- **Show the system.** Each variant is a primary mark plus its fallbacks. Document the fallback hierarchy, not just the primary. +- **Justify with signals and rejects.** What does the variant communicate? What does it explicitly NOT communicate? The negative space in the rejects sharpens the positive selection. +- **Render mockups, in image or in prose.** The brand owner needs to see the mark in context to evaluate. A spec without mockups is half-finished. +- **Prepare for production.** The color tokens, embroidery thread color matches, foil stamp specifications, and minimum sizes are production information. The spec is the bridge from decision to manufacture. + +The output of this skill is decision material. The next step after delivery is selection. The step after that is production refinement on the chosen direction: cleaner construction, refined kerning, color system finalization, application library. diff --git a/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md b/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md new file mode 100644 index 0000000..a0a1027 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md @@ -0,0 +1,266 @@ +# Symbol approaches + +A symbol is the part of the logo that does the most work outside of literacy. It travels where wordmarks cannot fit (favicon, embroidery, app icon, signet) and where wordmarks would not register (signage at distance, motion lockups, square contexts). The symbol approach is the question of WHAT KIND of symbol the brand needs. This file expands the five approaches in [SKILL.md](../SKILL.md) with reference brands, pattern vocabulary, decision criteria, and the cliches each approach has to escape. + +--- + +## Literal + +The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. A bicycle for a bicycle maker. A dog silhouette for a dog food brand. The mark and the meaning are tied together: see the mark, name the thing, recall the brand. + +Literal symbols deliver fast recognition and low ambiguity. The audience does not have to learn what the symbol means. They have to learn that THIS specific peak, rocket, leaf, or bird is THIS specific brand. That is a smaller cognitive load than abstract or geometric-reduction approaches require, which is why literal symbols often work for new brands without large marketing budgets. + +The risk is cliche. Every coffee shop has used a coffee bean. Every sustainable brand has used a leaf. Every fitness brand has used a flexed arm. Generic literal symbols disappear into the category background. The save is distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. Patagonia's mountain peaks (the Fitz Roy silhouette) are literal but read as Patagonia because no other outdoor brand uses that specific silhouette in that specific gradient. The execution carries the distinctiveness; the symbol approach is just the starting point. + +### Reference examples + +- **Apple's apple** (literal but with the bite, which is the distinctive execution) +- **Patagonia's Fitz Roy mountain silhouette** (literal landscape, specific peak) +- **Twitter's bird era** (literal bird, specific Larry-the-bird construction) +- **Shell's shell** (literal scallop shell, custom construction now near-symbol-only) +- **Burger King's burger** (literal but stylized; the bun, patty, and bun stack render as a unit) + +### Pattern vocabulary + +- Single-object silhouettes (peak, rocket, leaf, bird, fish, tree, building) +- Stylized object reductions (the apple bite, the burger as stacked rectangle, the shell as fan) +- Object-plus-frame compositions (the mountain inside a circle, the tree inside a shield) +- Repeated-object patterns (multiple stylized peaks, paired forms) +- Object combined with letterform (the mountain silhouette that doubles as a letter, see Letterform-derived approach below) + +### Decision criteria + +Literal symbols fit when: +- The brand name is descriptive (Atlas, Forge, Pulse, Anchor) and depicting the thing the name refers to is a natural move +- The category benefits from fast recognition (consumer goods at shelf, retail signage at street scale) +- The brand wants to feel approachable rather than abstract or institutional +- The audience reads symbols faster than they read wordmarks (younger audiences, retail audiences, audiences in low-literacy contexts) + +Literal symbols fail when: +- The brand name is abstract (Stripe, Anthropic, Linear) and forcing a literal symbol creates a metaphor the name does not invite +- The category has been saturated with literal symbols (every wellness brand using a leaf) +- The literal symbol cliches the category (every blockchain logo using a literal chain) +- The brand needs to feel institutional or premium and the literal depiction reads as childlike + +### Common cliches to avoid + +- **The leaf-as-natural** for any sustainability, wellness, or organic brand. The leaf is exhausted. +- **The swoosh-as-growth** for any growth-stage brand. Borrowed from Nike but watered down. +- **The mountain-as-aspiration** for any wellness or productivity brand. The mountain has been climbed. +- **The bullseye-as-precision** for any analytics or targeting brand. Done. +- **The shield-as-security** for any security or finance brand. Shields are everywhere. + +The escape is specific execution. A brand that uses a leaf must draw a specific leaf with specific construction (the maple leaf with eight points, drawn at this specific angle, with this specific stroke weight) so the audience reads "this leaf" not "a leaf". + +--- + +## Abstract gesture + +The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity" or "cycle". A spiral for "expansion". The symbol does not show the thing the brand does; it shows the quality the brand wants to be associated with. + +Abstract gesture marks read slower than literal marks but distinctively higher. The audience cannot name the thing in the symbol because there is no specific thing. Instead, the audience associates the symbol with the brand through repetition: see the symbol, recall the brand. Once associated, abstract gesture marks deliver more brand-specific recognition than literal marks because no other brand can use the same specific gesture. + +The risk is arbitrariness. A swoosh that suggests motion is fine. A swoosh that suggests motion AND innovation AND momentum AND speed is over-loaded. Abstract gesture marks work when the gesture is single, clear, and consistent. They fail when the gesture is multi-layered, when the symbol's construction does not visibly support the claimed gesture, or when the gesture is too abstract to register as anything at all. + +### Reference examples + +- **Nike's swoosh** (abstract gesture for motion, originally inspired by the wing of Nike, the Greek goddess of victory) +- **Mastercard's circles** (two overlapping circles, abstract gesture for connection or transaction) +- **Audi's four rings** (abstract gesture for the four merged companies, rendered geometrically) +- **Adidas's three stripes** (abstract gesture for ascension, originally a sports performance reference) +- **The PBS logo** (multiple human silhouettes implying community) + +### Pattern vocabulary + +- Arcs and curves (rising arc, descending arc, S-curve, spiral) +- Repeated forms (multiple stripes, multiple circles, multiple bars) +- Opposing forms (two halves meeting, mirrored shapes, yin-yang variants) +- Implied motion (lines that read as flow, shapes that suggest movement) +- Geometric primitives at scale (a single triangle, a single square, a single hexagon used as the gesture) + +### Decision criteria + +Abstract gesture fits when: +- The brand name is abstract and a literal symbol would feel forced +- The brand wants to claim a quality (motion, balance, growth, connection) without depicting it +- The category rewards distinctiveness over fast recognition (B2B, professional services, established mature brands) +- The brand has the recognition runway to teach the audience that this gesture means this brand + +Abstract gesture fails when: +- The brand is new and does not have the recognition to associate the gesture with the brand +- The gesture is borrowed from a saturated visual vocabulary (every fintech using a rising arc) +- The construction does not support the claim (a swoosh that does not actually swoop) +- The gesture is over-complicated and the audience cannot extract a single quality from it + +### Common cliches to avoid + +- **The swoosh-as-growth** for SaaS, fintech, or productivity brands. Swooshes are saturated. +- **The geometric-hexagon-as-blockchain** for crypto, web3, or distributed systems. Hexagons are the new dot-com blue. +- **The three-bars-as-tech-startup** for SaaS or developer tools. Three bars (or two, or four) are the most common geometric reduction in tech and now read as generic. +- **The infinity-as-continuous** for any "always-on" brand. Infinity loops are exhausted. +- **The ascending-arc-as-progress** for any analytics, growth, or financial services brand. Ascending arcs are the visual language of every dashboard ever. + +The escape is specific construction. A brand that uses a swoosh must draw a specific swoosh with specific weight, angle, and proportion so the gesture is identifiable as the brand's, not as a category default. + +--- + +## Geometric reduction + +The symbol is a formal abstraction with no specific referent. A hexagon. A triangle. A stack of horizontal lines. A circle bisected by a vertical. A square with a corner removed. The symbol is constructed from primitive geometric shapes with no narrative meaning attached. + +Geometric reduction reads modern and confident. The discipline of pure geometry signals "we made deliberate constructive choices". The risk is identical-to-everyone: thousands of brands use hexagons, triangles, circles, and squares. The reduction is so far from a specific narrative that the audience cannot distinguish one brand's geometric reduction from another's. + +The save is specific proportions, considered execution, and pairing with a distinctive wordmark. Microsoft's four-square mark is geometric reduction (four colored squares in a 2x2 grid) but works because the specific proportions, colors, and four-pane reference are unmistakably Microsoft. Pinterest's "P" inside a circle is geometric reduction but works because the specific letterform, the specific circle proportions, and the cultural recognition are Pinterest. Geometric reduction without distinctiveness in proportions or pairing reads as interchangeable. + +### Reference examples + +- **Microsoft's four-square** (four colored squares, the geometric reduction works because of color and arrangement) +- **Adidas's three stripes (geometric reduction reading)** (also abstract gesture, depending on read; the geometric reduction reading is three parallel diagonals) +- **Mastercard's two circles** (two overlapping geometric primitives) +- **Audi's four rings** (four overlapping circles) +- **Various B2B SaaS marks** (Linear's stacked horizontal bars, Slab's geometric construction) + +### Pattern vocabulary + +- Polygons (hexagon, octagon, triangle, square, diamond) +- Primitive intersections (overlapping circles, intersecting squares) +- Linear primitives (stacked bars, parallel lines, grids) +- Single primitives at scale (a single hexagon, a single triangle, a single square as the entire mark) +- Negative-space primitives (a hexagon defined by what surrounds it, a triangle defined by negative space) + +### Decision criteria + +Geometric reduction fits when: +- The brand has a budget for distinctive construction (the proportions and pairing must be specific enough to escape the category default) +- The brand wants to feel modern, technical, infrastructural +- The category rewards reduction over expression (B2B SaaS, infrastructure, fintech, distributed systems) +- The wordmark is distinctive enough that the geometric symbol can be quietly supportive rather than narratively loaded + +Geometric reduction fails when: +- The brand is new and the construction is generic +- The geometric primitive is the most common one in the category (every blockchain logo using a hexagon) +- The reduction is too far from any narrative the brand wants to tell +- The geometric symbol is not paired with a distinctive wordmark and the system reads as interchangeable + +### Common cliches to avoid + +- **The geometric hexagon-as-blockchain** for any crypto, web3, or distributed systems brand. Hexagons are the most overused geometric primitive in tech. +- **The triangle-as-direction** for any productivity, navigation, or strategy brand. Triangles point everywhere now. +- **The square-as-foundation** for any platform or infrastructure brand. Squares are the new shipping container. +- **The stacked-three-bars-as-tech-startup** for any SaaS brand. The three bars (or four) are the new dot-com gradient. +- **The bisected-circle-as-balance** for any wellness, productivity, or balance-claiming brand. Done. + +The escape is proportional specificity. A brand that uses a hexagon must use specific proportions (the regular hexagon vs the wide hexagon vs the tall hexagon, drawn at this specific angle, with this specific stroke or fill discipline) and pair it with a specific wordmark so the symbol is identifiable as the brand's specific reduction, not as a category default. + +--- + +## Letterform-derived + +The symbol is built from the name's letterforms. A custom letter, often the first, that doubles as a visual element. The "M" of McDonald's that reads as the golden arches and as a letter. The "b" of Beats inside a circle that reads as both a "b" and a stylized headphone. A custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. The Underscore brand's "_" that IS the symbol. + +Letterform-derived symbols deliver strong wordmark-symbol coherence. The wordmark and the symbol share construction language because they ARE the same construction language. The risk is that the letterform reads as just-a-typed-letter and adds nothing. The save is exaggerated character: the letter must read as both the letter AND the visual metaphor simultaneously. + +The discipline is the silhouette test on the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. The double-reading is what separates letterform-derived from wordmark-only or from literal symbols. + +### Reference examples + +- **McDonald's "M"** (the golden arches read as a letter and as the architectural arches of the original restaurant signage) +- **Beats by Dre's "b"** (the lowercase "b" inside a circle reads as a "b" and as a stylized headphone) +- **Underscore's "_"** (the underscore character IS the brand mark, read as a punctuation mark and as a structural element) +- **The Hoover Dam's "H"** (architectural lettering on signage that doubles as monumental ornament) + +### Pattern vocabulary + +- First-letter exaggeration (a custom "A", "B", "M", "S" that reads as both letter and shape) +- Letter-inside-frame (a letter inside a circle, square, or shield that reads as identity) +- Punctuation-as-symbol (an underscore, an asterisk, an ampersand used as the entire mark) +- Letter-as-object (a letter drawn so it doubles as a recognizable object: the M as arches, the A as a peak) +- Stacked or overlapping letterforms (one letter rendered on top of another, ligature-style) + +### Decision criteria + +Letterform-derived fits when: +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to share construction +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands + +Letterform-derived fails when: +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it + +### Common cliches to avoid + +- **The "letter inside circle"** as the universal letterform-derived solution. Beats works because the specific b-shape and the specific circle proportion are distinctive; copies of "letter inside circle" in B2B SaaS read as generic. +- **The "letter with an angled corner"** as a cheap attempt at distinctiveness. The angled corner does not read as a metaphor; it reads as decoration. +- **The "letter with extreme styling"** that no longer reads as the letter. If the styling is so heavy that the letterform fails the silhouette test, the metaphor is not earning its place. + +The escape is specific letterform decisions that produce a double reading. The "A as mountain peak" must work both ways. The "M as arches" must work both ways. The double reading is the only thing that justifies the custom drawing investment. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent), AOL. + +Monograms come in three flavors: +- **Pure ligature.** The letters share strokes; the two letters are drawn as one shape. CN and GG are ligatures. +- **Geometrically framed.** The letters sit inside a ring, shield, or diamond. HBO, with its rectangular framing. YSL, with its stacked geometric composition. +- **Tight kerning, no framing.** The letters are simply set together with optical adjustments and read as a unit. VW, with its overlapping V and W. AOL, set tight. + +Monograms signal institutional gravity. The audience reads "we have a long name" and "we own the initials of that name" and "we are old enough that abbreviating is acceptable". For brands wanting heritage, financial competence, hospitality polish, or luxury exclusivity, monograms are often the right architectural choice. + +### Reference examples + +- **Chanel's CN** (pure ligature, two letters share a counter) +- **Gucci's GG** (pure ligature, mirrored) +- **HBO** (geometrically framed inside a rectangle) +- **YSL** (stacked geometric composition, the three letters set as a tower) +- **Volkswagen's VW** (tight kerning, overlapping) + +### Pattern vocabulary + +- Ligature pairs (CN, GG, MN, AB, SR with shared counters or strokes) +- Stacked initials (the top letter above the bottom letter, often with a horizontal divider) +- Framed initials (letters inside a ring, shield, diamond, oval) +- Overlapping initials (the V and W of Volkswagen, the H and B of various heritage brands) +- Crowned or filigreed monograms (heritage luxury treatment with ornamental frame elements) + +### Decision criteria + +Monograms fit when: +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +Monograms fail when: +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials + +### Common cliches to avoid + +- **The "monogram inside a heavy ring"** for any brand wanting heritage. Heavy rings around initials read as fake-heritage logo template; rings work when they are restrained, geometrically specific, and earn their place. +- **The "heritage shield with a year"** for any brand wanting legacy. Founded-in-1923 shields look like every craft beer label. +- **The "ornamental monogram with filigree"** for any brand attempting traditional luxury. Heavy ornamentation reads as Renaissance Faire, not as Hermès. +- **The "monogram with a serif crown"** for any boutique heritage attempt. Crowns are exhausted. + +The escape is restrained execution. A monogram that earns its place uses specific letterform construction, specific kerning, and minimal framing. The discipline is what makes Chanel's CN read as Chanel and not as a costume version of Chanel. + +--- + +## How to choose, in summary + +Match the symbol approach to the brand name and the category positioning. + +- **Descriptive names invite literal or letterform-derived symbols.** Atlas, Forge, Pulse, Anchor, Falcon, Mountain. The name suggests something to depict. +- **Abstract names demand abstract or geometric-reduction symbols.** Stripe, Anthropic, Linear, Notion. The name does not point at anything specific, so the symbol cannot either. +- **Heritage names default to monograms.** A founder's surname, a place name, a multi-word firm. The monogram turns the long name into a positioning statement. +- **Tech-modern names often default to geometric reduction.** Anthropic's hex grid, OpenAI's flower, the universe of B2B SaaS marks built from primitives. The risk is interchangeability; the save is specific proportions and pairing. + +The wrong approach disconnects symbol from name. A literal peak on Stripe would read as a brand mistake. A geometric reduction on Atlas Coffee would feel cold. The approach is downstream of the name, the category, and the positioning intention. diff --git a/dist/pi/.agents/skills/logo-design/references/typographic-registers.md b/dist/pi/.agents/skills/logo-design/references/typographic-registers.md new file mode 100644 index 0000000..1d22e57 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/typographic-registers.md @@ -0,0 +1,263 @@ +# Typographic registers + +Type carries the wordmark. Type carries half the lockup. Type drives more of a logo's read than any other single decision because type is the voice of the brand, frozen. This file expands the seven registers listed in [SKILL.md](../SKILL.md) with named typefaces, category-fit notes, example brands, pairing guidance, and the failure mode each register tends toward. + +--- + +## Geometric sans + +Built from circles and verticals. Letterforms are constructed from primitive geometric shapes (circle, square, triangle) with consistent stroke weight and minimal optical adjustment. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde, Gotham, Proxima Nova. + +Geometric sans reads modern, considered, often optimistic. The discipline of the geometry signals "we made deliberate choices". Used well, it carries restraint. Used poorly, it reads as cold or interchangeable with every other modern startup. + +Futura was the original (1927, Paul Renner). Avenir is Adrian Frutiger's warmer, more humanist take on the same idea (1988). Avenir Next is the modern release with broader weights and language coverage. Cabinet Grotesk is a recent geometric sans that became a signature of the 2020-2023 startup wave (and now reads dated for that reason). Gotham (Tobias Frere-Jones) is the American-vernacular geometric sans, derived from New York signage; warmer than Futura, more grounded than Avenir. + +### Categories that default to geometric sans + +- Tech startups (the modern default; risk of looking like every other startup) +- Architecture and design firms (where the geometry signals craft) +- Modern hospitality (boutique hotels, restaurant groups built post-2010) +- Wellness and fitness brands at the considered end (not the energetic end) +- Real estate at the modern positioning end (urban, design-forward) + +### Example brands + +- Spotify (custom geometric sans, derived from Circular) +- Airbnb (Cereal, custom geometric sans by Dalton Maag) +- Headspace (Apercu Pro, geometric humanist sans) +- Nike's wordmark (custom Futura-derived) + +### Pairing notes + +Geometric sans pairs well with old-style serifs (the contrast between modern geometry and classical curves reads as intentional) and with slab serifs of similar weight class (both are structurally heavy, the contrast is in the silhouette). Avoid pairing geometric sans with neo-grotesque sans; the two registers are too close in feel and the pairing reads as indecisive. + +### Common pitfalls + +- The trend-chasing risk. Cabinet Grotesk became "2022-2023 startup typeface"; using it now codes the brand as late to a trend. +- The cold-tech risk. Pure geometric sans can feel emotionally distant. Warming requires color, custom letterform, or strong context. +- The interchangeability risk. Geometric sans wordmarks all start to look the same after a category saturates. Distinctiveness comes from custom letterforms or weight/proportion choices, not just typeface selection. + +--- + +## Humanist sans + +Has serif-like calligraphic gestures without serifs. The strokes vary in weight (subtle thick-thin contrast). The letterforms have movement, not just geometry. Gill Sans, Optima, Frutiger, Source Sans Pro, Inter at higher optical sizes, Hermann Zapf's Kabel, Jeremy Tankard's Bliss. + +Humanist sans reads professional but warm. The calligraphic origin gives the type a hand, where geometric sans has none. Excellent neutral choice when the category demands restraint with personality. Old enough to feel timeless; not old enough to feel dated. + +Gill Sans (Eric Gill, 1928) is the original British humanist sans, derived from Edward Johnston's London Underground typeface. Optima (Hermann Zapf, 1958) is the most calligraphic of the humanist sans, with strong thick-thin contrast that reads as sophisticated. Frutiger was designed for Charles de Gaulle airport signage in 1976 and has been the workhorse humanist sans for transit and wayfinding ever since. Source Sans Pro is Adobe's open-source humanist sans (Paul Hunt, 2012); Inter (Rasmus Andersson) crosses humanist and neo-grotesque registers depending on optical size. + +### Categories that default to humanist sans + +- Professional services (consulting, agencies, professional partnerships) +- Education and academic publishing +- Healthcare at the calm end (One Medical, Forward) +- Civic and institutional work (museums, libraries, public services) +- Editorial brands at the modern restrained end + +### Example brands + +- BBC (Gill Sans) +- BMW Group's corporate identity (custom humanist sans, derived from Helvetica with humanist warming) +- One Medical (FF Tisa Sans, humanist with slab adjacency) +- Various university identities (Penn, Stanford, MIT all use humanist or near-humanist marks) + +### Pairing notes + +Humanist sans pairs well with old-style serifs (the calligraphic origins of both registers complement each other) and with transitional serifs (humanist sans for body, transitional serif for display creates a coherent editorial system). Avoid pairing humanist sans with geometric sans; the calligraphic warmth of humanist clashes with the geometric coldness. + +### Common pitfalls + +- The "British civic" risk. Gill Sans is so coded as British civic that using it for a non-British brand can feel anachronistic. +- The dated risk for old humanist sans. Frutiger reads as 1990s transit unless deployed deliberately. Optima reads as 1970s pharmaceutical unless restored to its original sophistication. +- The lukewarm risk. Humanist sans is the safest choice; it can also be the most forgettable. Distinctiveness still requires custom letterform or strong color discipline. + +--- + +## Neo-grotesque sans + +The modern professional default. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America, Univers, Akzidenz-Grotesk. Neo-grotesque is descended from 19th-century grotesque sans typefaces but rationalized for the modern era. Even stroke weight, closed apertures, neutral letterform construction. + +Neo-grotesque reads competent and contemporary. It is the typographic equivalent of a black t-shirt: tasteful, defensible, easy to specify. The trade-off is that everyone else is wearing the same black t-shirt. Without strong color, distinctive symbol, or considered execution, a neo-grotesque wordmark blends into the category default. + +Helvetica (Max Miedinger, 1957) is the prototype. Akzidenz-Grotesk preceded it (1898) but Helvetica became the dominant version. Söhne (Klim Type Foundry, 2019) is the modern revival of the neo-grotesque tradition, with sharper detailing and broader weights. GT America (Grilli Type) crosses American grotesque and Swiss neo-grotesque traditions. Inter (Rasmus Andersson, 2016) is the modern open-source workhorse, designed for screen rendering at every size. + +### Categories that default to neo-grotesque sans + +- B2B SaaS (the unmistakable default; nearly every modern SaaS brand uses Inter, Söhne, or a custom neo-grotesque) +- Modern financial services (Stripe, Mercury, Ramp all use neo-grotesque or near-neo-grotesque) +- Tech at scale (Apple's San Francisco is a neo-grotesque-influenced humanist; Google's Product Sans is neo-grotesque-influenced geometric) +- Modern professional services rejecting the humanist sans default +- Editorial brands at the contemporary end (Bloomberg, modern news brands) + +### Example brands + +- Stripe (custom Sohne Mono and Sohne Schmal) +- Ramp (Söhne) +- Linear (Inter) +- Vercel (Inter, then custom Geist) +- Notion (Söhne) + +### Pairing notes + +Neo-grotesque sans pairs well with serif typefaces of similar weight class (both transitional and old-style serifs work), creating a clean modern-classical contrast for editorial systems. Avoid pairing neo-grotesque with geometric sans or humanist sans; the registers are too close and the pairing reads as indecisive. Custom-drawn neo-grotesque (Söhne, Geist) pairs especially well with stencil display faces, slab serifs, or condensed display sans for brand-system contrast. + +### Common pitfalls + +- The interchangeability risk is highest in this register. Neo-grotesque B2B SaaS wordmarks blur together. The brand that uses neo-grotesque without custom letterforms or strong supporting elements risks becoming visually identical to its category. +- The Helvetica problem. Helvetica is so over-used and so neutral that it now reads as "we did not make a typographic decision". Modern alternatives (Inter, Söhne, GT America) carry similar discipline with more current detailing. +- The screen-versus-print problem. Some neo-grotesque cuts are optimized for screen and look thin at print sizes; others are optimized for print and look chunky at small screen sizes. Pick based on primary application. + +--- + +## Transitional serif + +Modern serifs with high contrast (thick stems, thin transitions, sharp brackets). Source Serif, Charter, Lyon, IBM Plex Serif, Mrs Eaves, Caslon Pro at smaller sizes. Transitional serif sits between old-style serif (low contrast, organic) and modern Didone serif (extreme contrast, geometric). + +Transitional serif reads editorial, considered, intellectual. It carries the long-form heritage of book typography while reading as contemporary. Excellent for legal, publishing, financial, and editorial brands that want serif gravity without the heritage signal of old-style serif. + +Source Serif (Frank Grießhammer, 2014) is Adobe's open-source transitional serif, designed for both print and screen. Charter (Matthew Carter, 1987) is the original screen-optimized transitional serif, designed for low-resolution rendering before high-DPI displays existed; still excellent. Lyon (Kai Bernau, Commercial Type) is the contemporary editorial transitional serif of choice, used by The New York Times Magazine and many editorial brands. IBM Plex Serif (Mike Abbink, IBM, 2017) is IBM's open-source corporate serif, deployed across IBM's global identity. + +### Categories that default to transitional serif + +- Modern legal firms wanting serif gravity without old-fashioned positioning +- Editorial brands and publications (NYT Magazine, The Atlantic in some treatments, Cereal magazine) +- Financial services at the considered end +- Academic publishing (university presses, scholarly journals) +- Modern luxury at the editorial end (not the heritage-luxury end) + +### Example brands + +- The Atlantic (custom transitional serif, derived from Mrs Eaves and Filosofia) +- Vox Media (Lyon) +- Apple's editorial type (custom New York, transitional serif) +- IBM's identity system (Plex Serif) + +### Pairing notes + +Transitional serif pairs well with neo-grotesque sans (the modern-classical contrast is clean and editorial) and with humanist sans (both share calligraphic origins). The classic pairing for editorial is transitional serif for headlines and body, neo-grotesque sans for captions and metadata. Avoid pairing transitional serif with old-style serif; the readers will register the contrast as a mistake rather than an intention unless the deployment is deliberate. + +### Common pitfalls + +- The "magazine logo" trap. Transitional serif is so coded as editorial that using it for non-editorial brands can feel like the brand is trying to wear an editorial costume. +- The screen-rendering problem. Transitional serif's thin strokes can break at small screen sizes if the typeface wasn't optimized for low-DPI rendering. Pick a screen-optimized cut (Charter, Source Serif, Plex Serif) or set the wordmark large enough that the thin strokes survive. +- The "trying too hard" risk. Transitional serif communicates considered restraint; over-styling (italic, weight contrast, custom ligatures) can flip the register to ornate and undermine the restraint signal. + +--- + +## Old-style serif + +Classical serifs with low contrast and warm, organic shapes. Garamond, Caslon, Sabon, Adobe Garamond, Bembo, Janson Text. The letterforms reference 16th-18th century book typography. Diagonal stress, bracketed serifs, gentle thick-thin variation. + +Old-style serif reads heritage, traditional, institutional. It carries weight that newer registers cannot. Used in legal firms whose history runs to a partner's name from 1923, in academic institutions that predate the country, in luxury brands whose claim is centuries-long craft. Used poorly, it reads as a fake heritage costume. + +Garamond (Claude Garamond, mid-1500s) is the prototype; Adobe Garamond (Robert Slimbach, 1989) is the most-deployed modern revival. Caslon (William Caslon, 1722) is the British equivalent, long called "the safe choice for legal documents". Sabon (Jan Tschichold, 1967) is a modernized Garamond designed for industrial typesetting. Bembo (Stanley Morison's revival of Aldus Manutius's 1495 type) is the Italian Renaissance reference. All four predate every other typeface in this file by centuries. + +### Categories that default to old-style serif + +- Legal firms with heritage positioning (white-shoe firms, partnerships founded before 1950) +- Academic institutions (universities, presses, scholarly journals) +- Heritage luxury brands (centuries-old jewelers, watchmakers, fashion houses) +- Editorial brands with literary positioning (literary magazines, book publishers) +- Whiskey, wine, and other categories where "we have been doing this for generations" is the marketing claim + +### Example brands + +- The Economist (custom Caslon-derived display) +- The New Yorker (custom Caslon-derived masthead and ITC New Baskerville for body) +- Most university press identities (Yale, Oxford, Princeton) +- Most heritage law firm identities (Wachtell, Cravath, Latham use serifs derived from this register) + +### Pairing notes + +Old-style serif pairs well with humanist sans (both share calligraphic origins) and with neo-grotesque sans for editorial systems wanting modern-classical contrast. Avoid pairing old-style serif with geometric sans; the registers fight each other (geometric coldness vs old-style warmth). Avoid pairing old-style serif with transitional serif; the contrast is too subtle to register as intentional. + +### Common pitfalls + +- The dated risk. Old-style serif used without deliberate restraint reads as old-fashioned, which can be the goal (heritage) or the failure (trying to look serious by using old-looking type). +- The thin-stroke screen problem. Old-style serif's hairline serifs and thin strokes can disappear at small screen sizes. Either pick a screen-optimized old-style cut (Adobe Garamond Pro, EB Garamond) or accept that the wordmark must be set large. +- The fake-heritage risk. Using Garamond on a brand founded last year reads as costume, not heritage. The audience is not fooled by typography alone; the rest of the brand system has to carry the heritage claim. + +--- + +## Slab serif + +Heavy structural serifs with strong thick-thin uniformity. The serifs are blocky, rectangular, often nearly equal in weight to the stems. Sentinel, Adelle, Roboto Slab, Tisa, Rockwell, Archer, Vitesse. The visual register is strong, declarative, sometimes journalistic. + +Slab serif reads strong, structural, declarative. It carries authority without the heritage baggage of old-style serif. Common in editorial work, sports brands, journalistic identities, and brands that want serif weight without the ornament of transitional or old-style serifs. + +Sentinel (Hoefler & Frere-Jones, 2009) is the modern editorial slab. Adelle (TypeTogether, 2009) is the screen-optimized slab serif of choice for digital editorial. Roboto Slab is Google's open-source slab. Rockwell (Frank Hinman Pierpont, 1934) is the British slab serif of railway and industrial heritage. Tisa (Mitja Miklavčič) is the modern slab with humanist warming, used in editorial systems. + +### Categories that default to slab serif + +- Editorial and publishing (when the brand wants more weight than transitional serif provides) +- Sports brands (the typographic equivalent of athletic gravity) +- Journalistic identities (some newspapers, news magazines) +- Industrial and engineering brands (the structural quality reads as "we make real things") +- Outdoor and adventure brands (Filson, Patagonia in some treatments, REI's wordmark) + +### Example brands + +- Mailchimp's wordmark (custom slab-derived script) +- The Wall Street Journal (in older treatments) +- Various sports league identities (NFL teams, college athletics) +- Filson's wordmark (custom slab serif) + +### Pairing notes + +Slab serif pairs well with neo-grotesque sans (the structural similarity reads as one design language at different ornament levels) and with geometric sans (both are constructed registers). Avoid pairing slab serif with old-style serif; the contrast between structural and organic serifs reads as system inconsistency. + +### Common pitfalls + +- The "newspaper from 1985" risk. Some slab serifs read as 1980s editorial unless paired with current typographic systems. +- The clunky risk. Slab serifs' structural weight can feel heavy at large sizes; the wordmark needs to be sized carefully so the slabs do not overpower the letterforms. +- The genre-trapping risk. Slab serifs are so coded for sports, journalism, or industrial that using them outside those categories can feel like the brand is borrowing the register's gravity rather than earning its own. + +--- + +## Display custom + +Custom-drawn or heavily-modified typeface designed specifically for the brand. Reads distinctive but expensive in time and budget. The wordmark uses letterforms that exist nowhere else. + +Custom display is the highest distinctiveness tier. Stripe's wordmark, Google's Product Sans, Pinterest's custom geometric, Spotify's Circular variant, Airbnb's Cereal. Each is a custom typeface drawn to solve a specific problem in the brand's wordmark or identity system. + +The justification is when the brand needs a wordmark no one else has and the budget supports drawing one. Custom display is rarely justified for new brands without significant marketing investment because the brand has not yet earned the recognition that makes the custom letterforms register as distinctive. For mature brands, custom display is the ceiling of typographic discipline. + +### Categories where custom display fits + +- Mature brands at scale where custom letterforms become a competitive moat +- Tech-led brands with budget for type design partnerships +- Heritage luxury brands whose wordmark must be unique (not Garamond plus a name) +- Editorial brands with recognizable masthead type (The New York Times, The New Yorker) +- Sports leagues and major sports brands + +### Example brands + +- Stripe (custom Sohne, then Söhne plus custom optical adjustments on the wordmark) +- Google (Product Sans, custom geometric) +- Spotify (Circular variant, then custom Spotify Mix) +- Airbnb (Cereal, custom geometric humanist by Dalton Maag) +- Pinterest (custom geometric for the wordmark) + +### Pairing notes + +Custom display is rarely paired in lockup; the custom typeface IS the wordmark. The pairing decision is which body and metadata typefaces support the custom display in larger system applications. The body typeface is typically chosen for legibility at small sizes (a screen-optimized neo-grotesque or humanist sans) rather than for visual harmony with the custom display. + +### Common pitfalls + +- The cost risk. Custom letterform drawing is expensive (5-figure to 6-figure engagements depending on scope). The investment must match the brand's recognition trajectory. +- The over-customization risk. Custom letterforms should solve specific problems, not announce themselves. The custom "g" that reads as cleverly drawn rather than as just-the-letter-g signals committee work. +- The aging risk. Custom display typefaces age with the era they were drawn in. The Spotify wordmark from the 2010s reads as 2010s; the brand has had to update the system multiple times. Plan for redrawing every 5-10 years. + +--- + +## How to choose, in summary + +The choice flows from category default and positioning intention. + +- **In-category choice signals competence.** Legal in old-style serif, SaaS in neo-grotesque sans, sports in slab serif. The audience reads "this brand understands the category". +- **Out-of-category choice signals positioning.** Legal in geometric sans signals "we are modern". SaaS in old-style serif signals "we take the work seriously". Outdoor in geometric sans signals "we are not your grandfather's outdoor brand". The shift is intentional and the rest of the brand system has to support it. +- **Custom display is reserved for mature brands** with recognition that earns the investment. +- **Pairing logic** combines the wordmark register with body and metadata registers to build the system. The pairing should read as one design intention, not as two competing ones. + +The wrong typographic register is not always obvious in isolation. It becomes obvious in deployment: the wordmark on the business card, the lockup at retail, the favicon at 16px. Test the chosen register against the brand's actual application contexts before committing. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md b/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md new file mode 100644 index 0000000..b80133a --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md @@ -0,0 +1,311 @@ +--- +name: long-form-content-frameworks +description: "Patterns for individual long-form content pieces. Case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials. The structural disciplines that distinguish publication-quality long-form from bloggy-long padding or academic bloat. Different from pillar-content-architecture (which covers hub structure); this skill covers individual deep-dive pieces. Triggers on long-form content, case study writing, whitepaper, research report, definitive guide, ebook, manifesto, long-form tutorial, deep-dive article, anchor piece, foundational article, structural archetypes. Also triggers when a piece is over 3,000 words and the team is unsure how to structure it, when a long-form draft feels padded or saggy, or when a flagship asset needs the depth to actually earn the length." +category: content +catalog_summary: "Structural patterns for individual long-form pieces (case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials) that distinguish publication-quality work from bloggy-long padding or academic bloat" +display_order: 9 +--- + +# Long-Form Content Frameworks + +A senior editorial leader's playbook for individual long-form content pieces. The structural disciplines that distinguish publication-quality work from bloggy-long padding or academic bloat. + +Long-form is where most content programs lose their nerve or lose their way. Teams either stretch a 1,500-word post to 5,000 with filler (the bloggy-long failure mode), or they over-document the topic with no editorial spine (the academic-bloat failure mode). The pieces that earn their length are the ones where each section justifies its weight, the lede sets a thesis the body actually delivers, and the closing leaves the reader with something specific. + +This skill covers the individual long-form piece: the case study, the whitepaper, the research report, the manifesto, the ebook chapter or full ebook, the definitive guide, the long-form tutorial. Different from `pillar-content-architecture` (which covers HUB architecture: how a pillar plus cluster system fits together), this skill covers the long-form PIECE itself, regardless of whether it sits at the center of a hub or stands alone. + +The voice is the senior editorial leader who has shipped dozens of flagship long-form assets and watched plenty of others fail. Honest about which formats earn their length, which structural archetypes fit which problems, and where long-form most often goes wrong. + +When to use this skill: planning a flagship long-form piece, structuring a draft that feels saggy, reviewing a long-form piece that is technically correct but emotionally flat, or auditing a content library to find the long-form pieces that should have been blog posts. + +--- + +## What this skill is for + +This skill spans individual long-form content pieces. The content suite distinction: + +- `content-strategy` is program scope: what to produce across the program. +- `pillar-content-architecture` is HUB scope: pillar plus cluster as a topical hub system. +- **`long-form-content-frameworks` (this skill)** is PIECE scope for long-form: individual deep-dive pieces, standalone or as pillars. +- `content-and-copy` is execution scope at any length: writing the words. +- `content-brief-authoring` is per-piece brief scope at any length: the contract. +- `editorial-qa` is gate scope: pre-publish verification. +- `ai-content-collaboration` is workflow scope: how humans and AI compose. + +A pillar page IS often a long-form piece. The two skills compose: pillar-content-architecture decides the hub shape and which pieces sit where; this skill is how you structure the long-form pieces themselves so they earn the length they take up. + +The audience: editorial leads, content directors, in-house teams shipping flagship long-form, agencies producing whitepapers and research reports, anyone planning a piece that will run 3,000+ words and need to hold a reader to the end. + +What is not in scope: blog-post-length writing (covered by `content-and-copy`), the brief itself (covered by `content-brief-authoring`), the hub architecture around a long-form piece (covered by `pillar-content-architecture`), or the pre-publish QA pass (covered by `editorial-qa`). + +--- + +## Bloggy-long vs academic-bloat vs publication-quality + +The keystone framing. Two failure modes plus the discipline. + +**Bloggy-long.** A regular blog post stretched to 5,000 words via padding. Same structural shape as 1,500 words, just inflated: more transitional paragraphs, more "before we get into it," more recap sections, more bullet expansions of single ideas. The reader notices within 600 words and skims. Output: a piece that ranked because it was long, never gets read all the way through, never gets shared, never earns links because nobody finished it. + +**Academic-bloat.** Exhaustive coverage that loses the thread. 8,000 words where 4,500 would have served. Every adjacent topic surveyed; every definition restated; every caveat documented. Reader respects the effort and skims for the parts they need. Output: a "comprehensive" piece that nobody reads end-to-end, that does not change anyone's mind, that performs in search but underperforms in trust. + +**Publication-quality.** Structural depth that earns the length. Each section justifies its weight. The lede establishes a thesis the body delivers. The closing is specific. Reading flow varies in density, register, and rhythm so the piece sustains attention. The piece reads as the work of someone who had something specific to say and the discipline to say it well at length. + +The litmus test. Ask of any long-form draft: would cutting this section weaken the argument, or would it just make the piece shorter? If cutting strengthens it, the section was filler. The piece earns its length when each section is doing structural work the argument requires. + +--- + +## Long-form formats and when each fits + +Seven formats, each with a different structural shape and a different reader contract. + +**Case study.** A specific company, project, or initiative with quantified outcomes. Reader contract: "Show me what worked and why, with specifics." Length: 2,000 to 4,000 words typical. Structural archetype: usually problem-solution. The case-study tax: real numbers, real names, real specificity. Generic case studies signal nothing. + +**Whitepaper.** A position document on a substantive topic, typically with original analysis. Reader contract: "Take me through your reasoning on this question with the rigor I would expect from a serious source." Length: 3,000 to 8,000 words. Structural archetype: layered argument or comparative analysis. Often gated. The whitepaper tax: original synthesis, not survey of existing literature. + +**Research report.** Original primary research presented with methodology, findings, implications. Reader contract: "Show me the data, how you collected it, what it means." Length: 4,000 to 12,000 words. Structural archetype: taxonomic survey or comparative analysis. The research-report tax: actual primary research, not "we surveyed 300 marketers" with leading questions. + +**Definitive guide.** Comprehensive coverage of a topic for a specified audience. Reader contract: "Be the canonical resource on this." Length: 4,000 to 10,000 words. Structural archetype: taxonomic survey. The definitive-guide tax: actual comprehensiveness; gaps reveal that the guide is not actually definitive. + +**Manifesto.** A position paper on what the writer believes and why, often confrontational. Reader contract: "Tell me what you think and convince me." Length: 1,500 to 6,000 words. Structural archetype: layered argument or narrative arc. The manifesto tax: actual conviction, not diplomatic hedging. + +**Ebook.** Multi-chapter long-form, often a sequence of related pieces with introduction and conclusion. Reader contract: "Take me through a body of work." Length: 8,000 to 30,000+ words. Structural archetype: usually narrative arc across chapters. The ebook tax: each chapter earns its place; the table of contents is not padding. + +**Long-form tutorial.** Instructional content where the reader is following along. Reader contract: "Take me from where I am to where I want to be, step by step." Length: 3,000 to 8,000 words. Structural archetype: problem-solution with sequential steps. The long-form-tutorial tax: every step actually works; gaps in the sequence break the reader. + +Detail in [`references/format-decision-framework.md`](references/format-decision-framework.md). + +--- + +## Structural archetypes + +Five archetypes that fit different long-form problems. + +**Problem-solution.** State the problem with weight; develop why it matters; present the solution; show how it works; address objections. Fits case studies, long-form tutorials, manifestos with a clear opposition. Risk: feels formulaic if every piece uses it. + +**Narrative arc.** Beginning, middle, end. A protagonist (often the company, sometimes a person, sometimes the reader) faces a complication and resolves it. Fits ebooks, some case studies, longer manifestos. Risk: forced narrative on topics that are not actually stories. + +**Layered argument.** Position stated; layer 1 evidence; layer 2 evidence; counter-arguments addressed; synthesis. Fits whitepapers, manifestos, position pieces. Risk: feels academic if the layers do not build to a real synthesis. + +**Taxonomic survey.** A topic mapped into categories; each category explored; relationships among categories surfaced. Fits definitive guides, research reports surveying a landscape. Risk: feels like a list with subheads if the taxonomy is not actually load-bearing. + +**Comparative analysis.** Multiple options, frameworks, or positions compared along defined axes; tradeoffs surfaced; the writer's recommendation argued. Fits whitepapers, decision-guide research reports, technology comparisons. Risk: feels like a feature matrix if the analysis is shallow. + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. A whitepaper might be a layered argument with comparative-analysis sections. A definitive guide might be a taxonomic survey with problem-solution chapters. The archetype is the spine; variation prevents the piece feeling formulaic. + +Detail in [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md). + +--- + +## Section weight calibration + +How long sections should be relative to each other, varying by format. + +The general principle: section weights match how much load the section is bearing in the argument. Throat-clearing introductions get cut. Setup sections are short. Argument-bearing middle sections are longest. Closings are specific and tight. + +**Whitepaper / research report typical weights.** Introduction 8-12% (thesis stated, scope set). Methodology or framing 10-15% (how the analysis works). Body 60-70% (the actual argument or findings, divided into 3-5 weighted sections). Implications 10-15%. Closing 3-5%. + +**Case study typical weights.** Setup and context 15-20% (the company, the problem, why it mattered). Solution narrative 50-60% (what was done, in sequence). Outcomes 15-20% (quantified results, what worked, what did not). Reflection 5-10% (what the team would change). + +**Manifesto typical weights.** Position 5-10% (what is believed, stated early and clearly). Argument 70-80% (why, with the layers building intensity). Call 10-15% (what should change as a result). + +**Definitive guide typical weights.** Introduction 5-8% (what the guide covers, who it serves). Body across taxonomic sections 80-85% (each section roughly even). Closing and additional resources 7-10%. + +**Long-form tutorial typical weights.** Setup 10-15% (what the reader will achieve, what they need). Sequential steps 70-80% (each step its own subsection). Troubleshooting and edge cases 10-15%. + +The audit. If one section is more than 3x the length of another bearing similar argumentative load, the piece is structurally unbalanced. Either the long section needs to be split, or the short section needs to be deepened, or the imbalance reflects an actual content problem the writer has not surfaced. + +Detail in [`references/section-weight-calibration.md`](references/section-weight-calibration.md). + +--- + +## Lede patterns for long-form + +Long-form ledes do different work than blog-post ledes. + +A blog-post lede answers the user's likely query in the first 200 words. A long-form lede establishes a thesis the next 5,000 words will deliver, sets the reader's expectations for the piece's depth, and earns the reader's attention for the time investment ahead. + +**Patterns that work.** + +- **The contested-claim opener.** A surprising or contested position stated cleanly, then the rest of the piece argues for it. Fits manifestos, opinionated whitepapers. +- **The problem-with-stakes opener.** A problem stated with the stakes made tangible. Fits case studies, problem-solution pieces. +- **The data-anomaly opener.** A piece of data that does not fit the consensus, framed as the question the piece will answer. Fits research reports, analytical whitepapers. +- **The scene opener.** A specific moment, person, or scene that grounds the abstract topic. Fits narrative-arc pieces, magazine-style longform. +- **The orientation opener.** What this piece covers, who it is for, what reading it costs and pays. Fits definitive guides and tutorials where the reader's first question is "is this the right resource for me." + +**Patterns that fail.** + +- The throat-clear opener ("Content marketing has changed dramatically over the past decade. In this article, we will explore...") signals filler ahead. +- The dictionary-definition opener ("According to Merriam-Webster, X is defined as...") signals an unwillingness to commit a position. +- The history-of-the-topic opener (paragraphs of background before the argument starts) loses readers before the thesis lands. +- The "in this article we will discuss" tour opener flattens the piece into an outline before the writer has earned attention. + +The first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. Spending it on filler is the most common long-form failure. + +Detail in [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md). + +--- + +## Sustaining attention across 5,000+ words + +Long pieces that hold readers vary their density, register, and rhythm. Pieces that lose readers feel uniform: same paragraph length, same sentence rhythm, same density of claim, page after page. + +**Density variation.** Some sections argue tightly (claim, evidence, claim, evidence). Others reflect, illustrate, or breathe. The argument-tight sections earn the breathing sections; the breathing sections give readers room to absorb. + +**Register variation.** Most long-form pieces sustain a primary register (analytical, narrative, instructional) while occasionally shifting to a secondary register (anecdotal, reflective, declarative) for variation. A whitepaper that is purely analytical for 6,000 words exhausts the reader; a whitepaper with a mid-piece anecdote or a closing reflection lands harder. + +**Rhythm variation.** Sentence length variation matters more in long-form than short. Strings of 25-word sentences blur; strings of 8-word sentences fragment. The pattern that holds attention: medium sentences with occasional short punches and occasional layered longer constructions. + +**Visual rhythm.** Subheads, pull quotes, callouts, charts, illustrations break the page into navigable units. Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. The rhythm: visual element every 600-1,000 words on average, varied in type. + +**Mid-piece micro-thesis.** Around the 40-60% mark, restate the central claim with new framing. Long-form readers' attention naturally dips mid-piece; the mid-piece restatement reorients them and refreshes engagement. + +Detail in [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md). + +--- + +## Citations and source authority + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. + +**Source hierarchy for long-form.** + +- Primary research: original studies, datasets, interviews, the writer's own data work. Highest authority. +- Authoritative secondary sources: peer-reviewed papers, government data, established research firms, primary reporting from credible outlets. +- Industry-credible sources: vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners. +- Linked-aware secondary sources: reputable blogs and publications where the source is verifying claims, not just amplifying them. +- Avoid: citation laundering through other content marketing pieces, "studies show" claims with no link, anonymous "experts," reposts of reposts. + +**Citation density.** Long-form arguments need citations roughly proportional to claim density. A piece making 30 falsifiable claims needs 30 citations; a piece making 5 strong claims with extensive elaboration may need 5. The audit: every falsifiable claim is either cited or attributed to the writer's own analysis. + +**Source freshness.** Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. The "85% of marketers" stat from 2018 in a 2026 piece signals stale research. + +**Inline vs endnote citations.** Long-form on the web typically uses inline links to authoritative sources. For research-heavy pieces, endnote-style citations (numbered footnotes) signal academic rigor; for editorial whitepapers, inline links keep momentum. Either works; pick one and stay consistent within the piece. + +Detail in [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md). + +--- + +## Visualization and breakouts + +Long-form earns visual breakouts; blog posts often do not. The discipline is which breakouts earn their place. + +**Visual element types.** + +- Charts and graphs: data visualization that the prose alone cannot convey efficiently. +- Diagrams: relationships, flows, architectures, taxonomies that benefit from visual structure. +- Pull quotes: moments where a single sentence deserves visual weight. +- Sidebars: tangential but valuable context that does not fit the main thread. +- Tables: comparison data, structured reference material. +- Inline callouts: definitions, warnings, "if you only read one section" pointers. + +**Earned-position rule.** Each visual element earns its place by carrying argumentative load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. + +**Production tax.** Each visual element costs design time, accessibility work (alt text, screen-reader-friendly tables), and revision overhead when the underlying content changes. Long-form pieces with 25 charts each take meaningful production time to maintain. Plan visual count against production capacity, not against ideal-world maximalism. + +**Anti-pattern: the stock-image header.** Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. Either commission specific visual work (custom illustrations, branded data visualizations, scene photography) or skip the hero image. + +Detail in [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md). + +--- + +## Closing patterns + +Long-form pieces with strong closings get shared, get linked, and get remembered. Pieces with throat-clearing closings disappear after the last subhead. + +**Closings that work.** + +- **The specific call.** What should the reader do, decide, or change as a result of reading this. Concrete, not generic. +- **The reframed thesis.** The opening claim restated with the weight the body has now earned, often inverted or sharpened. +- **The open question.** The question this piece's findings raise but do not answer, framed as the next investigation. +- **The personal reflection.** The writer's stake in the topic surfaced briefly. Fits manifestos, opinionated long-form. +- **The provocation.** A challenge to the reader, the field, or the consensus. Fits manifestos. + +**Closings that fail.** + +- The recap closing ("In this piece we covered X, Y, Z") signals the writer ran out of energy. +- The "more research is needed" closing on every research report signals the writer did not commit a position. +- The throat-clear closing ("As we have seen, content is important and only getting more so") delivers no payload. +- The CTA-as-closing ("Book a demo") on a long-form piece breaks the editorial contract; if a CTA belongs, it sits below the closing, not as the closing. + +The audit. Ask of any long-form closing: does this leave the reader with something specific to do, decide, or think about, or does it just signal the piece is ending? If the latter, rewrite. + +Detail in [`references/closing-patterns.md`](references/closing-patterns.md). + +--- + +## Distribution implications for long-form + +Long-form's distribution shape differs from blog-post distribution. The format choices echo through how the piece reaches readers. + +**Gated vs ungated.** Whitepapers and research reports often gate behind a form to capture leads; ebooks frequently do; case studies sometimes do. The tradeoff: gating cuts reach by 70-90%; the gated audience is qualified but small. Manifestos and definitive guides typically stay ungated to maximize reach and link equity. The decision turns on whether the piece's primary value is reach (ungated) or qualified-lead capture (gated). + +**Format choices.** Long-form web page (HTML), downloadable PDF, mixed (web with PDF download option), interactive (web with embedded tools or visualizations). Web pages earn search traffic; PDFs earn email-shareable assets; mixed maximizes both. The production cost rises with format count. + +**Syndication and excerpting.** Long-form pieces lend themselves to chapter excerpts, summary blog posts, and email-newsletter serializations. Plan the excerpting at piece-design time so the chapters or sections are excerpt-ready. See `content-repurposing` for the cross-format adaptation discipline. + +**Refresh schedule.** Long-form pieces with research components need annual or quarterly refresh on the data; long-form pieces with timeless framings need lighter touch. See `content-refresh-system` for refresh prioritization. + +The decision sequence: format first, distribution shape second. A research report's distribution shape (often gated, often PDF, often paired with a webinar) follows from the format choice; trying to retrofit distribution onto a piece that was written for the wrong shape produces friction. + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-long-form-failures.md`](references/common-long-form-failures.md). + +- "We wrote 5,000 words and traffic is flat." Bloggy-long: stretched to length, no structural depth. Cut to 1,800 words or rewrite as publication-quality. +- "Our whitepaper looked authoritative but nobody finished it." Academic-bloat: comprehensive but not load-bearing. Cut sections that did not move the argument. +- "The lede took 800 words to get to the thesis." Throat-clearing opener; rewrite to land the position in the first 150-250 words. +- "Each section is the same length and rhythm." No section weight calibration; sections all bearing the same argumentative load suggests an undifferentiated piece. +- "The piece sags around the 60% mark." Standard mid-piece attention dip; add a mid-piece micro-thesis and rhythm variation. +- "The closing repeated the introduction." Recap closing; rewrite to a specific call, reframed thesis, or open question. +- "Citations are mostly other blog posts." Citation laundering; replace with primary or authoritative secondary sources. +- "We commissioned 12 charts, the team is exhausted, traffic is the same." Visual count exceeded production capacity and earned-position discipline; cut to charts that bear argumentative load. +- "The case study has no specifics." Generic case-study failure; the case-study tax is real numbers, real names, real specificity. Without those, the format does not work. +- "Our manifesto reads as diplomatic." Manifesto failure: the format demands conviction; if the writer cannot commit, write a different format. +- "The definitive guide has obvious gaps." Definitive-guide failure: the format requires actual comprehensiveness. Either fill the gaps or rename the piece. + +--- + +## The framework: 12 considerations for long-form content + +When planning or auditing a long-form piece, walk these 12 considerations. + +1. **Format fits the work.** Case study, whitepaper, research report, definitive guide, manifesto, ebook, or long-form tutorial. Format chosen for reader contract, not arbitrary length. +2. **Structural archetype selected.** Problem-solution, narrative arc, layered argument, taxonomic survey, or comparative analysis as the spine. +3. **Lede earns the next 30 minutes.** Thesis stated, stakes set, position committed within the first 150-250 words. +4. **Section weights calibrated to argumentative load.** No section 3x another bearing similar load; throat-clearing sections cut. +5. **Density variation.** Argument-tight sections balanced with reflective or illustrative sections. +6. **Register variation.** Primary register sustained with secondary-register moments for variation. +7. **Rhythm variation.** Sentence and paragraph length varies; visual breakouts every 600-1,000 words. +8. **Mid-piece micro-thesis.** Central claim restated around the 40-60% mark. +9. **Citations match claim density.** Falsifiable claims cited; primary or authoritative sources preferred; sources fresh. +10. **Visual elements earn position.** Each chart, diagram, sidebar carries load the prose alone cannot. +11. **Closing is specific.** Specific call, reframed thesis, open question, or provocation. Not recap. +12. **Distribution shape matches format choice.** Gating, format mix, syndication plan, refresh schedule planned at piece-design time. + +The output of the framework is a long-form piece that earns its length: every section justified, every page sustaining attention, every claim verifiable, every closing specific. + +--- + +## Reference files + +- [`references/format-decision-framework.md`](references/format-decision-framework.md) - When each long-form format fits. Reader contracts, length norms, structural archetype tendencies, format-specific taxes. +- [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md) - Five archetypes (problem-solution, narrative arc, layered argument, taxonomic survey, comparative analysis) with worked examples and combination patterns. +- [`references/section-weight-calibration.md`](references/section-weight-calibration.md) - Typical weight ratios by format. Whitepaper, case study, manifesto, definitive guide, long-form tutorial profiles. The 3x audit. +- [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md) - Five patterns that work, four that fail. The first-paragraph sales-pitch frame. +- [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md) - Density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis discipline. +- [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md) - Source hierarchy, citation density, freshness, inline vs endnote conventions, citation-laundering anti-pattern. +- [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md) - Visual element types, earned-position rule, production-tax discipline, the stock-image-header anti-pattern. +- [`references/closing-patterns.md`](references/closing-patterns.md) - Five closings that work, four that fail. The specific-call, reframed-thesis, open-question, personal-reflection, provocation patterns. +- [`references/common-long-form-failures.md`](references/common-long-form-failures.md) - 11+ failure patterns with diagnoses, including bloggy-long, academic-bloat, throat-clearing leads, visual-count overruns, citation laundering, format-tax failures. + +--- + +## Closing: long-form earns its length or it does not + +Length is not a virtue. A 5,000-word piece is only worth more than a 1,500-word piece if those extra 3,500 words carry structural and argumentative load the shorter version could not. Most long-form content underperforms because the team chose length first and structural depth second. + +The discipline is the inversion. Decide what the piece needs to deliver, choose the format and archetype that fit, calibrate sections to actual argumentative load, and let the length follow. Pieces written that way earn their length and read as the work of someone who had something to say. Pieces written length-first read as filler, no matter how many subheads dress them up. + +When in doubt about whether a long-form piece is ready, ask: does each section justify its weight, does the lede earn the next 30 minutes, does the closing leave the reader with something specific, are claims cited, do visuals carry load, does the mid-piece micro-thesis refresh attention? If yes to all of those, the piece is publication-quality. If no to any, the gap is where the reader stops reading. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md new file mode 100644 index 0000000..90a251c --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md @@ -0,0 +1,129 @@ +# Attention-sustaining techniques + +How long-form pieces hold readers across 5,000+ words. The patterns that keep reader attention across the time investment, and the underlying observation: readers leave because pieces feel uniform. + +The pieces that lose readers in long-form are the ones that feel monotone. Same paragraph length, same sentence rhythm, same density of claim, page after page. Even competent writing reads as exhausting under that pattern. The pieces that hold readers vary their density, register, and rhythm so the reader's attention has somewhere to recover and somewhere to engage. + +--- + +## Density variation + +Long-form pieces should alternate between argument-tight sections and breathing sections. + +**Argument-tight sections.** Claim, evidence, claim, evidence. Specific, direct, intellectually demanding. The reader is doing work to follow the argument. + +**Breathing sections.** Reflection, illustration, anecdote, restatement. Lower density of new claims; higher density of integration with what was just argued. + +The pattern that holds. After an argument-tight section, a breathing section gives the reader room to absorb. After a breathing section, the reader returns to argument-tight work refreshed. Pieces that are argument-tight throughout exhaust readers; pieces that breathe throughout never feel substantive. + +The audit. For each section, characterize it as argument-tight or breathing. If the sequence is all argument-tight, the piece is dense and exhausting. If the sequence is all breathing, the piece is shallow despite its length. The mix is the discipline. + +--- + +## Register variation + +Most long-form pieces sustain a primary register while shifting briefly to secondary registers for variation. + +**Primary registers.** + +- Analytical: claim-evidence-implication, measured tone, distance from the topic. +- Narrative: scene-driven, character-driven, time-progressive. +- Instructional: do-this-then-this, addressed to the reader directly. +- Declarative: positions stated, opinions committed, weight on conviction. + +**Secondary registers.** Anecdotal moments inside an analytical piece. Reflective moments inside an instructional piece. A specific scene inside a declarative manifesto. A measured analytical section inside a narrative. + +The pattern that holds. A whitepaper sustained in analytical register for 6,000 words exhausts readers; the same whitepaper with a mid-piece anecdote and a closing reflection lands harder. A long-form tutorial sustained in instructional register for 5,000 words feels mechanical; the same tutorial with a brief reflective section on common failures and a personal note from the writer feels human. + +The discipline. Choose the primary register first; insert secondary-register moments at section transitions where the shift will refresh attention rather than disorient. + +--- + +## Rhythm variation + +Sentence and paragraph length variation matters more in long-form than in short. + +**Sentence length.** + +- Strings of 25-word sentences blur. The reader's eye glides over the text without the cognitive checkpoints short sentences create. +- Strings of 8-word sentences fragment. The text reads as choppy, and the reader's attention is interrupted constantly. +- The pattern that holds: medium sentences with occasional short punches and occasional layered longer constructions. + +**Paragraph length.** + +- Long paragraphs (8+ sentences) feel academic. Suitable for argument-tight sections; exhausting if sustained. +- Short paragraphs (1-2 sentences) feel staccato. Suitable for emphasis and for breaking dense passages; fragmenting if sustained. +- The pattern that holds: most paragraphs 3-5 sentences with occasional shorter ones for emphasis and occasional longer ones for layered argument. + +**Heading rhythm.** H2 every 600-1,200 words on average. H3 within H2 sections to break navigation. Headings that come at uniform intervals feel mechanical; headings that follow the actual structural breaks feel natural. + +The audit. Read the piece aloud. Does the rhythm vary, or does every sentence and paragraph land with the same beat? If the latter, the piece needs rhythm work even if every individual sentence is competent. + +--- + +## Visual rhythm + +Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. + +**The norm.** A visual element every 600-1,000 words on average. Visual elements include subheads, pull quotes, callouts, charts, diagrams, sidebars, tables, and images. + +**Variation in type.** All-subheads-no-charts feels under-designed for the piece's length. All-charts-no-pull-quotes feels like a research dump. The visual rhythm should vary: a subhead, then 800 words of prose, then a chart, then 600 words of prose, then a pull quote, then 700 words of prose, then a callout, then 900 words and the next subhead. + +**The earned-position rule.** Each visual element earns its place by carrying load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. See `breakouts-and-visualization.md` for the discipline. + +**Mobile reading reality.** Long-form on mobile gets read in landscape stretches. Subheads should be visible without scrolling on each major section transition; pull quotes should be visible early to preview the piece's depth; charts should be readable without horizontal scrolling. + +--- + +## Mid-piece micro-thesis + +Long-form readers' attention naturally dips around the 40-60% mark. Pieces that survive the dip have a structural move that refreshes engagement at that point. + +**The micro-thesis pattern.** Around the midpoint, restate the central claim with new framing. The restatement does three things at once: it reorients readers who have been following sections, it gives drifting readers a checkpoint to re-engage, and it sets up the second half of the piece. + +**Worked example.** A whitepaper opens with the claim "Most teams treating content marketing as a volume problem will continue to underperform." At the midpoint, after the structural argument and the first empirical layer, the writer restates: "The pattern across the data is consistent. The teams that broke the volume-first cycle did not produce more; they produced less, and committed harder to what they produced." The reader is reoriented; the second half of the piece can build on the restatement. + +**Anti-pattern: the recap micro-thesis.** Restating "as we have seen so far, content marketing is changing" is filler, not micro-thesis. The micro-thesis should add framing or sharpen the claim, not recap. + +**Where the micro-thesis sits structurally.** Often at the boundary between two body sections, especially the boundary between the first and second halves of a layered argument or the boundary between the third and fourth chapters of an ebook. + +--- + +## Combining the techniques + +A 6,000-word whitepaper using all five techniques. + +- **Lede.** Contested-claim opener, declarative register, short paragraphs for opening punch. +- **Setup section.** Analytical register, medium-density argument, 3-5 sentence paragraphs. +- **First body section.** Argument-tight density, analytical register sustained, longer paragraphs as the argument layers. +- **Mid-piece micro-thesis.** A short paragraph that restates the claim with new framing. Brief register shift to declarative. +- **Second body section.** Argument-tight density, but with a worked example inserted as a breathing pause. Worked example shifts briefly to narrative register. +- **Counter-argument section.** Argument-tight again, analytical register, with the counter-arguments engaged seriously. +- **Synthesis.** Density lower, register declarative, paragraphs short and emphatic. +- **Closing.** Declarative, short, specific. + +The piece reads as varied across its length even though it is a single sustained argument. + +--- + +## Common attention-loss patterns + +Patterns that show up when readers drop off mid-piece. + +**The mid-piece sag.** Around the 50% mark, the piece becomes harder to follow. Cause: no micro-thesis, no rhythm variation, the reader is exhausted from sustained argument-tight density. Cure: add micro-thesis at the section boundary nearest the midpoint; insert a breathing section. + +**The wall-of-text section.** A 1,500-word body section with no subheads, no visuals, no rhythm variation. Cause: the writer was deep in the argument and stopped attending to the reader. Cure: identify the natural sub-structure within the section, add subheads or visuals at the boundaries. + +**The abstract drift.** The piece's specifics decrease as it progresses. Concrete examples in the early sections; vague generalizations in the later sections. Cause: the writer ran low on specific examples; padded with abstraction. Cure: cut to the depth where specificity holds; better a shorter piece with sustained specificity than a longer piece that drifts abstract. + +**The energy-decline closing.** The closing reads as a writer who ran out of energy. Cause: writers fatigue before readers do. Cure: write the closing first or revise the closing last with fresh attention; the closing is too important to deliver tired. + +--- + +## Methodology-level choices that stay in the public skill + +The five techniques (density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis), the combining pattern, the common attention-loss patterns and their cures, the read-aloud audit. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags rhythm patterns. Specific reading-time analytics that detect mid-piece drop-off in the team's content. Specific paragraph-length analyzers in the team's writing tool. Specific A/B testing of structural variants. The team's own conventions for visual-element budgets per long-form piece. These vary by team, stack, and analytics setup. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md new file mode 100644 index 0000000..f361487 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md @@ -0,0 +1,147 @@ +# Breakouts and visualization + +Visual element types for long-form, the earned-position rule, the production-tax discipline, and the stock-image-header anti-pattern. The patterns that distinguish visual rhythm from visual clutter. + +Long-form earns visual breakouts; blog posts often do not. A 1,500-word blog post can carry one image; a 5,000-word whitepaper can carry six or eight visual elements before they feel like clutter. The discipline is not visual count but earned position: which visuals carry argumentative load, and which are decoration. + +--- + +## Visual element types + +Six categories, each with different work to do. + +**Charts and graphs.** Data visualization that conveys patterns the prose alone cannot convey efficiently. Line charts for time series, bar charts for comparisons, scatter plots for correlations, distributions for spread. The chart's value is showing the pattern; if the prose can summarize the pattern in one sentence and the chart adds nothing, the chart is decoration. + +**Diagrams.** Relationships, flows, architectures, taxonomies that benefit from visual structure. Process diagrams, system architectures, hierarchical relationships, decision trees. The diagram's value is making structure visible; topics with simple linear structure rarely need diagrams. + +**Pull quotes.** Moments where a single sentence deserves visual weight. Used sparingly for emphasis; one or two per long-form piece typical. The pull quote's value is signaling "this matters"; using pull quotes too often dilutes the signal. + +**Sidebars.** Tangential but valuable context that does not fit the main thread. Background detail, related concepts, optional deeper coverage. The sidebar's value is letting the main thread stay focused while preserving context for readers who want it. + +**Tables.** Comparison data, structured reference material. Side-by-side option comparisons, parameter listings, multi-axis evaluations. The table's value is making parallel data scannable; tables for non-parallel data are confusing. + +**Inline callouts.** Definitions, warnings, "if you only read one section" pointers. Short, focused, specific. The callout's value is interrupting flow for a specific purpose; callouts without specific purpose are decoration. + +--- + +## The earned-position rule + +Each visual element earns its place by carrying argumentative load the prose alone cannot. + +**Earned visuals.** + +- A chart that shows a pattern the prose can only summarize in vague terms ("increasing over time" becomes specific with the line chart). +- A diagram that makes a complex relationship instantly visible (a system architecture; a process flow with decision points). +- A pull quote that captures a position the writer wants to stand alone for emphasis. +- A sidebar with context that would derail the main thread if inline. +- A table that makes parallel comparison instant when the prose would require careful reading. + +**Decorative visuals.** + +- A chart that restates a number the prose just stated (the chart adds visual interest, not information). +- A diagram of a relationship the prose described in one sentence ("the marketing funnel" diagrammed, when the prose said "marketing has stages"). +- A pull quote of a sentence that did not deserve standalone weight. +- A sidebar with information that should have been cut entirely or integrated into the main thread. +- A table where the rows or columns are not actually parallel. +- A stock image at the top of the piece that signals only that the writer wanted a hero image. + +The audit. For each visual, ask: does cutting this visual lose information or capability that the prose alone cannot replace? If yes, the visual is earned. If no, the visual is decoration. + +--- + +## Production tax + +Visual elements cost more than writers often estimate. + +**Per-visual costs.** + +- Design time. Even simple charts require choices about color, scale, labeling, formatting. +- Accessibility work. Charts need alt text or alternative-format descriptions; tables need proper header markup; complex visuals need text equivalents. +- Revision overhead. When the data changes, the chart changes. When the framing changes, the diagram changes. Visual elements that go stale because they were not updated when the underlying content changed are worse than no visuals. +- Production review. Editors review prose; design or production review visuals. Pieces with many visuals need more review cycles. + +**The capacity audit.** Before committing to a visual count for a piece, check: does the team have the design capacity, the data-engineering capacity (for charts based on data), and the maintenance capacity to keep this number of visuals current? Pieces that ship with 12 visuals and decay because nobody updates them are worse than pieces that ship with 4 visuals that stay current. + +**The MVP-visuals approach.** Plan the minimum viable visual count: which visuals are load-bearing for the argument, which would be nice to have, which would be decoration. Ship the load-bearing ones. Add nice-to-haves only if capacity permits and the piece is genuinely long enough to need more visual rhythm. + +--- + +## The stock-image-header anti-pattern + +Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. + +**The pattern.** A whitepaper opens with a generic stock photo of "diverse business team meeting around laptop with charts." The image conveys nothing specific; readers tune it out within milliseconds. + +**Why it fails.** Long-form's value proposition includes signaling that the work is serious. Stock imagery undermines the signal: a serious piece would have commissioned specific visual work or skipped the hero image. Stock imagery says "we wanted a hero image and did not invest in one." + +**The cure options.** + +- Commission specific visual work. Custom illustration matched to the piece's argument. Branded data visualization based on the piece's findings. Scene photography directly related to the piece's case study. +- Skip the hero image entirely. Long-form pieces can open without a hero image; many of the strongest editorial pieces do. +- Use a content-specific opening visual. The first chart in the piece appears at the top, doing dual duty as hero image and load-bearing visual. + +The discipline. If the piece's hero image could be on any other piece on the same general topic, it is generic and should be cut or replaced. + +--- + +## Chart conventions for long-form + +Charts in long-form pieces have specific expectations. + +**Title and caption.** Every chart should have a title that describes what the chart shows and a caption that explains the source of the data. Charts without titles or captions read as decoration. + +**Source attribution.** The data behind the chart should be cited. "Source: 2024 Industry Survey, n=412, methodology in appendix" or similar. Charts without source attribution are unverifiable. + +**Mobile readability.** Charts should be readable on mobile without horizontal scrolling. Wide charts should be redesigned for mobile or marked as "view on desktop for full detail." Charts that are unreadable on mobile lose mobile readers. + +**Color and contrast.** Charts should pass accessibility contrast guidelines (WCAG AA minimum). Color-coded charts need either patterns or labels for readers with color-blindness. Charts that rely on color alone fail accessibility. + +**Data integrity.** Truncated y-axes that exaggerate effects, cherry-picked time ranges, and apples-to-oranges comparisons violate the implicit chart contract. Long-form readers who notice deceptive charts lose trust in the entire piece. + +--- + +## Diagram conventions for long-form + +Diagrams should make structure visible without becoming the main attraction. + +**Simplicity.** A diagram with 30 boxes and 50 arrows is a diagram nobody reads. Diagrams should be visually parse-able in seconds. Complex topics may need multiple simple diagrams rather than one comprehensive one. + +**Labeling.** Every box, arrow, and group should be labeled clearly. Diagrams with unlabeled elements assume the reader can infer the labels from context, which often fails. + +**Reading order.** Diagrams should have an obvious reading order (top to bottom, left to right, or numbered steps). Diagrams without obvious reading order leave readers uncertain how to traverse them. + +**Mobile rendering.** Wide diagrams that work on desktop become unreadable on mobile. Either redesign for mobile, accept that mobile readers will scroll, or split into multiple smaller diagrams. + +--- + +## Sidebar conventions + +Sidebars should be visually distinct from the main thread but not overwhelming. + +**Length.** Most sidebars run 100-300 words. Sidebars longer than 500 words probably should have been their own section in the main thread or their own piece. + +**Visual treatment.** Background color or border that distinguishes the sidebar from main prose. Different typography weight or font (where the design system supports it). + +**Skip-readability.** Sidebars should be skippable without losing the main argument. If the main argument depends on the sidebar's content, that content belongs in the main thread, not in a sidebar. + +--- + +## Pull-quote discipline + +Pull quotes should be earned moments, not decoration. + +**Selection.** A pull quote is a sentence the writer wants to stand alone for emphasis. It should be a sentence whose weight justifies the visual treatment. Generic sentences pulled into pull-quote treatment dilute the device. + +**Frequency.** One or two pull quotes per long-form piece is typical. Three or four can work for very long pieces (8,000+ words). More than that and the device loses meaning. + +**Attribution within pull quotes.** Pull quotes from interviews or external sources need attribution; pull quotes of the writer's own sentences do not need attribution but should still earn the visual weight. + +--- + +## Methodology-level choices that stay in the public skill + +The six visual element types and their work, the earned-position rule, the production-tax discipline, the stock-image-header anti-pattern, the chart conventions, the diagram conventions, the sidebar and pull-quote discipline, the MVP-visuals approach. + +## Implementation choices that stay internal + +Specific design tokens for charts in the team's brand system. Specific charting libraries the team uses. Specific accessibility-checking automation. Specific design-review workflow for visual elements. Specific custom-illustration commissioning processes. Specific stock-photo blocklist or sourcing guidelines. The team's own visual-budget conventions per format. These vary by team, design capacity, and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md new file mode 100644 index 0000000..5e961f6 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md @@ -0,0 +1,130 @@ +# Citation and source authority + +Source hierarchy for long-form, citation density discipline, freshness norms, inline vs endnote conventions, and the citation-laundering anti-pattern. + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. Pieces that fail at citation discipline read as if the writer wanted authority without paying the verification cost. + +--- + +## Source hierarchy + +Sources are not interchangeable. The same claim cited from a peer-reviewed paper carries different weight than the same claim cited from a vendor blog post. + +**Tier 1: Primary research.** Original studies, datasets, interviews, the writer's own data work. The writer is producing the data, not citing it. Highest authority. Pieces with primary research signal that the writer or team did the work. + +**Tier 2: Authoritative secondary sources.** Peer-reviewed papers, government data (BLS, Census, equivalent), established research firms (Gartner, Forrester, Pew, IDC, etc.), primary reporting from credible outlets. The writer is citing rigorous secondary work where the source's reputation does the verification work. + +**Tier 3: Industry-credible sources.** Vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners with track records. The writer is citing sources that practitioners in the field would recognize as substantive even if they are not academically rigorous. + +**Tier 4: Linked-aware secondary sources.** Reputable blogs, publications, and commentary where the source is verifying claims rather than just amplifying them. The writer is citing sources that did some level of verification work, even if the source is a blog post rather than a study. + +**Tier 5 and below: Avoid.** Other content marketing pieces (citation laundering), "studies show" claims with no link, anonymous "experts," reposts of reposts, vendor marketing pages cited as research, AI-generated synthesis cited as primary source. + +The discipline. Long-form arguments should cite from tiers 1-3 wherever possible. Tier 4 is fine for color and context but should not bear primary argumentative load. Tier 5 sources signal the writer did not do the verification work. + +--- + +## Citation density + +Citations should be roughly proportional to claim density. + +**A piece making 30 falsifiable claims.** Roughly 30 citations or attributions to primary analysis. Each claim either points to a verifiable source or is identified as the writer's own analysis (in which case the analysis itself should be defended). + +**A piece making 5 strong claims with extensive elaboration.** May need only 5 citations if the elaboration is reasoning rather than fact-claim. Manifestos and position pieces often work this way: a small number of central claims, deeply argued, with citations supporting the claims rather than every elaboration. + +**The audit.** Mark every falsifiable claim in the piece. For each claim, check: is it cited, is it identified as the writer's own analysis, or is it floating? Floating claims are the failure mode. Either cite, attribute to the writer, or cut. + +**The over-citation failure.** Some long-form pieces cite every sentence as if academic rigor were the goal. The result reads as a literature review, not a piece of editorial writing. Citations should support the argument, not perform credibility theater. + +--- + +## Source freshness + +Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. + +**Fast-moving topics.** Technology, marketing tactics, AI capabilities, software stacks, social platforms. A 2018 stat in a 2026 piece on these topics signals stale research unless the writer is citing it specifically as historical context. + +**Stable topics.** Behavioral psychology research, structural economics, mathematical results, established scientific consensus. A 2015 stat on these topics may be perfectly current. + +**The acknowledgment pattern.** When citing older data on a fast-moving topic deliberately, acknowledge it: "A 2018 survey, the most recent rigorous data on the question, found..." The acknowledgment signals the writer knows the data is old and chose to cite it anyway, with reasoning. + +**The hidden-stale-data failure.** Citing a "2024 study" that turns out to be a 2024 republication of 2019 data. Verify primary publication date before citing. + +--- + +## Inline vs endnote citations + +Two conventions for how citations appear. + +**Inline links.** The cited source appears as a hyperlink within the prose. Reader clicks to verify. Common in editorial long-form, content marketing whitepapers, and most web-published research reports. + +- Strength: keeps reader momentum; the prose flows without numerical interruptions. +- Weakness: harder to verify without leaving the page; less academically formal. + +**Endnote-style citations.** Numbered footnotes at the end of the piece, with each citation numbered in the prose. Common in academic-influenced research reports, policy whitepapers, and some long-form published with print-style conventions. + +- Strength: signals academic rigor; preserves the citation list for verification. +- Weakness: interrupts reading flow; readers rarely follow endnotes in web reading. + +**The convention rule.** Pick one and stay consistent within the piece. Mixing conventions (some claims inline-linked, some endnoted) reads as inconsistent. The choice depends on audience expectations: B2B technical research often expects endnotes; editorial whitepapers usually expect inline. + +**Hybrid: inline + bibliography.** Inline links throughout the piece plus a "sources" or "further reading" section at the end. Common compromise. Works well when the piece has both casual references and core sources. + +--- + +## The citation-laundering anti-pattern + +Citing other content marketing pieces as authoritative when the cited piece itself does not have primary support. + +**The pattern.** Piece A claims X with a citation. Piece B cites A as the source for X. Piece C cites B. The original claim X may have been weak, made-up, or misinterpreted; each successive citation amplifies the appearance of authority without adding verification. + +**How it happens.** A writer searching for support for a claim finds another content marketing piece making the same claim and links to it. The writer feels they have cited a source. The source is itself unsourced or weakly sourced. The chain of laundering can run several pieces deep. + +**The cure.** When citing, follow the chain back. If the cited piece does not have primary or authoritative-secondary support, do not cite it. Either find a primary source, or remove the claim, or attribute it as the writer's own observation. + +**Why it matters in long-form.** The reader is investing time. Citation laundering produces pieces that read as authoritative because of citation count but fall apart under verification. Readers who verify discover the laundering; readers who do not develop a slow-decaying trust in the writer. + +--- + +## The own-analysis citation + +When the writer is making a claim from their own analysis rather than citing a source, the claim should be visibly the writer's analysis with the analytical work shown. + +**The pattern.** "Looking at the data across [scope], the pattern that emerges is X." The pattern claim is the writer's; the data is cited; the analytical work is described. + +**The discipline.** Own-analysis claims still need defensibility. The writer should be able to defend, if challenged: where the data came from, how the analysis was performed, what alternative interpretations were considered. + +**The hidden-claim failure.** Sentences that read as fact ("The reality is that programmatic SEO is dying") without acknowledgment that the claim is the writer's interpretation. If the claim is contested, frame it as the writer's view; if the claim is empirical, cite a source. The hidden middle (claim presented as fact when it is interpretation) is where readers lose trust. + +--- + +## Quote attribution + +Long-form pieces often include quotes from named experts, executives, or practitioners. + +**Verification.** Every quote should be from a real person who actually said the words attributed to them. Hallucinated quotes (especially in AI-assisted long-form) are an ethical failure regardless of whether the position is plausibly something the named person might say. See `editorial-qa`'s fact-accuracy reference for the discipline. + +**Context.** Quotes work best when the person's role is identified, the context of the statement is clear (interview, public statement, prior writing), and the quote earns its place by saying something specific. + +**The throwaway-quote failure.** A generic quote ("Content is king," John Smith, CEO) that does not advance the argument. If the quote does not say something specific the prose alone cannot convey, cut it. + +--- + +## Citation in research reports specifically + +Research reports have particularly strict citation expectations because they are claiming primary research authority. + +- **Methodology disclosed.** Sample size, recruitment method, dates, instrument design. Without these, the research is not verifiable. +- **Sample limits acknowledged.** What the sample does and does not represent. A sample of 300 marketers in B2B SaaS does not represent "marketers"; the report should not claim it does. +- **Statistical limits acknowledged.** Confidence intervals, margins of error, significance tests where applicable. Reports presenting cherry-picked data points without distribution context are weak research. +- **Original data made available.** Where possible, the underlying data should be shareable for verification. Reports that hide the data behind the headline findings invite skepticism. + +--- + +## Methodology-level choices that stay in the public skill + +The source hierarchy and tier definitions, the citation-density principle, the freshness rule and acknowledgment pattern, the inline-vs-endnote convention rule, the citation-laundering anti-pattern, the own-analysis discipline, the quote-attribution rules, the research-report citation expectations. + +## Implementation choices that stay internal + +Specific citation management tools the team uses. Specific bibliography generators integrated with the team's writing system. Specific link-checking automation that catches dead links and stale data. Specific data-publication conventions for research reports the team produces. The team's own internal source-tier classification when sources are ambiguous. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md new file mode 100644 index 0000000..34995e0 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md @@ -0,0 +1,161 @@ +# Closing patterns + +Five closings that work, four that fail, and the underlying frame: the closing is the writer's last opportunity to leave the reader with something specific. Closings that do not leave anything specific signal a writer who ran out of energy, and the piece is remembered accordingly. + +Long-form pieces with strong closings get shared, get linked, get remembered. Pieces with throat-clearing closings disappear after the last subhead. The closing is one of the most consequential 200-400 words of any long-form piece, and one of the easiest places for writers to under-invest. + +--- + +## The underlying frame + +The closing has three jobs at once. + +1. **Resolve the piece.** Whatever the lede promised, the closing delivers (or acknowledges what was not delivered). +2. **Leave the reader with something specific.** A specific call, a sharpened framing, a question to consider. The reader should be different at the closing than they were at the lede. +3. **Earn the reader's attention for next time.** The closing is the reader's last impression. Readers who finish a piece with a strong closing think of the writer as someone who delivers; readers who finish a piece with a weak closing think of the writer as someone who runs out of energy. + +Closings that do all three are memorable. Closings that do none are forgettable. Closings that do one or two are common and produce pieces that are technically complete but emotionally flat. + +--- + +## Pattern 1: The specific call + +**Shape.** What should the reader do, decide, or change as a result of reading this. Concrete, not generic. + +**Fits.** Most long-form pieces. Particularly strong for problem-solution archetype, manifestos, decision-guide research reports, long-form tutorials. + +**Worked example.** A 5,000-word whitepaper on content distribution closes: "If your team is producing content faster than you can distribute it, the bottleneck is not your production rate. It is your channel-fit decisions. Audit one piece you shipped in the last quarter against the channel-fit framework. Find the one channel where the audience-content match was strongest but the piece never reached that channel. That gap is where the next quarter's distribution work should focus." + +**Why it works.** The reader has a specific action. The action is grounded in the piece's framework, so the framework keeps working after the reading is over. + +**The discipline.** The call must be specific to the piece. Generic calls ("rethink your content strategy") signal that the writer did not commit to a specific recommendation. + +--- + +## Pattern 2: The reframed thesis + +**Shape.** The opening claim restated with the weight the body has now earned, often inverted, sharpened, or made more specific. + +**Fits.** Layered-argument pieces. Whitepapers. Manifestos. Pieces where the body's evidence justifies a stronger version of the opening claim. + +**Worked example.** A whitepaper that opens "Most teams treating content marketing as a volume problem will continue to underperform" closes: "The volume problem is not actually a content problem. It is a strategy problem the team has chosen to express through content. Teams that solve the strategy problem produce less content and more value; teams that try to solve the strategy problem with more content produce more content and less value. The path forward is not better content production. It is harder strategy decisions." + +**Why it works.** The reframed thesis lands the argument with weight the lede could not have carried. The body has done the work; the closing collects the payoff. + +**The discipline.** The reframing must be earned by the body. Pieces that restate the lede unchanged are recapping; pieces that restate it with sharpened framing the body justifies are doing the closing's work. + +--- + +## Pattern 3: The open question + +**Shape.** The question this piece's findings raise but do not answer, framed as the next investigation. + +**Fits.** Research reports. Analytical whitepapers. Pieces where the writer has gone as far as the available evidence allows but the topic continues. + +**Worked example.** A research report on AI search citation patterns closes: "The data is clear that statistics with named sources earn citations at 4x the rate of unsourced claims. The data does not tell us why. The hypothesis worth testing in the next research cycle: do AI engines weight named sources because they are training on a corpus that itself weights named sources, or because the engine providers have built explicit credibility-weighting into the retrieval logic? The answer matters because the answer changes how content programs should respond." + +**Why it works.** The reader is left with intellectual momentum. The piece does not pretend to have answered everything; it acknowledges what it did not answer and frames that as productive rather than as a limit. + +**The discipline.** The open question must be a real question, not a rhetorical one. "What does the future hold?" is rhetorical filler. "Is the citation pattern downstream of the training corpus or of explicit retrieval logic?" is a real question. + +--- + +## Pattern 4: The personal reflection + +**Shape.** The writer's stake in the topic surfaced briefly. What the writer thinks the piece illustrates beyond its specific argument. + +**Fits.** Manifestos. Opinionated long-form. Pieces where the writer has personal authority on the topic. Some case studies where the writer was personally involved. + +**Worked example.** A manifesto on content marketing's drift toward generic AI-assisted output closes: "I have been writing about content for a decade. The pattern that worries me is not that AI is involved; the pattern that worries me is that teams have stopped noticing when their content stopped sounding like them. The discipline this piece argues for is not anti-AI. It is pro-craft. The teams holding the line on craft will be readable in five years. The teams not holding the line will not be." + +**Why it works.** The personal stake adds weight to the argument. The writer's investment in the topic is the closing's payoff: the reader sees that the argument is not abstract for the writer. + +**The discipline.** The personal reflection must be earned by the writer's actual position. Personal reflections from writers without a real stake feel performed. + +--- + +## Pattern 5: The provocation + +**Shape.** A challenge to the reader, the field, or the consensus. Often paired with a refusal to soften the position. + +**Fits.** Manifestos. Position pieces. Long-form criticism. Pieces where the writer is staking out an unpopular or contested position deliberately. + +**Worked example.** A manifesto on programmatic SEO closes: "The teams that will survive the next three years of search-algorithm pressure are the ones that stop treating programmatic as a volume strategy and start treating it as a depth strategy. Most programmatic operations will not make this change. They will not survive. This piece is for the few that will." + +**Why it works.** The provocation establishes that the writer means it. The reader either accepts the provocation and reads the piece as a call to action, or rejects it and reads the piece as wrong; either response is engaged. The middle response (mild interest, no engagement) is what kills long-form's reach. + +**The discipline.** The provocation must be defensible. Provocations the body did not actually argue for read as posturing. Provocations the body argued for and the closing committed to with conviction read as serious. + +--- + +## Failure 1: The recap closing + +**Shape.** "In this piece, we covered X, Y, Z. As we have seen, content is important and only getting more so..." + +**Why it fails.** Signals the writer ran out of energy. Recap is what the table of contents does; the closing should add weight, not summarize. Readers who just spent 30 minutes reading do not need the recap; they need the writer to land the argument. + +**The cure.** Cut the recap. Replace with one of the five working patterns. The closing is not a tour through what the piece said; it is the writer's final position. + +--- + +## Failure 2: The "more research is needed" closing + +**Shape.** Most research reports default to "More research is needed in this area" as a closing. + +**Why it fails.** Signals the writer did not commit a position even when the data warranted one. "More research is needed" is the default closing of academic papers because academic papers have specific norms about hedging; editorial long-form does not have those norms, and the default reads as evasive. + +**The cure.** If the data does support a position, commit the position. If the data does not support a position, frame the closing as an open question (Pattern 3) rather than a generic call for more research. + +--- + +## Failure 3: The throat-clear closing + +**Shape.** "As we have seen, [topic] is important. Going forward, [generic platitude about the topic continuing to evolve]. Teams that [generic recommendation] will be best positioned to [generic outcome]." + +**Why it fails.** Delivers no payload. Every word could appear in any other piece on the same topic. The reader's response is "I read 5,000 words for this?" + +**The cure.** Strip the closing of every generic phrase. What is left is usually nothing; rewrite from scratch with one of the working patterns. + +--- + +## Failure 4: The CTA-as-closing + +**Shape.** The closing is "Book a demo with us today" or "Sign up for our newsletter" or "Download the full report." + +**Why it fails.** Breaks the editorial contract. Long-form readers who reached the closing have invested 30+ minutes in editorial content; pivoting to a sales call reads as bait-and-switch. Trust is damaged. + +**The cure.** If a CTA belongs in the piece, place it after the closing, visually distinct, framed as an offer rather than as the closing itself. The piece's editorial closing does its work first; the CTA appears afterward as a separate element. + +--- + +## The closing audit + +A short framework for auditing a draft closing. + +1. **Does the closing leave the reader with something specific to do, decide, or think about?** If not, rewrite. +2. **Could this closing appear at the end of any other piece on this topic?** If yes, the closing is generic. Rewrite to be specific to this piece. +3. **Does the closing have approximate weight to the piece?** A 5,000-word piece with a 50-word closing under-invests; a 1,500-word piece with a 600-word closing over-invests. +4. **Read the closing aloud. Does it have energy?** Closings that read as tired signal the writer was tired. The reader registers the energy. Rewrite when fresh. +5. **Does the closing match one of the five working patterns?** If it matches one of the failure patterns, rewrite using a working pattern. + +--- + +## When to write the closing first + +Some long-form writers write the closing first and write the body toward it. + +**The argument for closing-first.** Knowing where the piece lands clarifies what the body needs to argue. Writers who draft the body without knowing the closing often discover at the closing that the body did not actually support the planned closing, and have to rework substantial sections. + +**The argument against closing-first.** Some pieces' closings emerge from the body's argument; predetermining the closing constrains where the body can go. Research reports particularly may benefit from following the data and writing the closing once the analysis is complete. + +**The middle path.** Draft a target closing before writing the body. Revisit the target after the body draft. The target may stand, or the body may have produced a stronger closing than the target predicted. + +--- + +## Methodology-level choices that stay in the public skill + +The five working patterns and the four failure patterns, the underlying frame, the closing audit, the closing-first discussion, and the CTA-vs-editorial-closing distinction. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags closing patterns. Specific style guides on closing length and weight in the team's editorial system. Specific A/B testing of closing variants for engagement metrics. Specific conventions for whether and where CTAs appear after closings. These vary by team, audience, and analytics setup. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md new file mode 100644 index 0000000..2310a3b --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md @@ -0,0 +1,179 @@ +# Common long-form failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear repeatedly across long-form drafts, regardless of topic, format, or writer experience. Diagnosing them early saves the rewrite work that catches them late. + +The pattern across most failures: writers reaching for length without doing the structural work that justifies it, and writers under-investing in the structural decisions that make long-form land. + +--- + +## Failure 1: Bloggy-long + +**Symptom.** A 5,000-word piece reads as a 1,500-word piece stretched. Padding paragraphs. Recap sections. "Before we get into it" preludes. Bullet expansions of single ideas. The reader notices within 600 words and skims. + +**Diagnosis.** The writer chose length first and structural depth second. The piece needed to be longer than 1,500 words for SEO or marketing reasons but did not have 5,000 words of substantive content. + +**Cure.** Two options. Cut to actual substantive length (often 1,800-2,500 words). Or expand the structural depth: add original analysis, primary research, case study specificity, or comparative dimensions that justify the length. + +**Prevention.** Choose length based on substantive content, not based on competitor length or SEO targets. SEO algorithms are getting better at detecting padded length; the strategy of "outranking by being longer" is increasingly counterproductive. + +--- + +## Failure 2: Academic-bloat + +**Symptom.** A 7,000-word whitepaper that is exhaustive but loses the thread. Every adjacent topic surveyed. Every definition restated. Every caveat documented. Reader respects the effort and skims for the parts they need. + +**Diagnosis.** The writer aimed for comprehensiveness rather than for argumentative load. The piece treats inclusion as the metric instead of treating each section's contribution as the metric. + +**Cure.** Apply the section-weight audit: which sections are actually load-bearing, which are surveying. Cut surveying sections that do not support specific claims in the load-bearing sections. Often takes 7,000 words to 4,500 with the argument intact. + +**Prevention.** Outline the argument before drafting. Each section should answer: what does this section contribute to the argument? If a section's answer is "comprehensive coverage" rather than a specific contribution, question whether the section earns its place. + +--- + +## Failure 3: Throat-clearing lede + +**Symptom.** The lede took 800 words to get to the thesis. Multiple paragraphs of "content marketing has changed dramatically" before the piece's actual claim appears. + +**Diagnosis.** The writer was warming up. Drafts often have throat-clearing ledes; finished pieces should not. + +**Cure.** Cut the first 400-700 words of the lede. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clearing draft. + +**Prevention.** After drafting, ask: where does the piece's specific argument actually start? Whatever appears before that point is throat-clearing and can usually be cut. + +--- + +## Failure 4: Even-section padding + +**Symptom.** All H2s come within 10% of each other in word count. Each section running 800-1,000 words regardless of its argumentative load. + +**Diagnosis.** The writer treated section length as a quota. Long sections were padded; short sections were either padded or not deepened. + +**Cure.** Identify which sections are actually load-bearing. Let them grow. Cut filler from non-load-bearing sections. + +**Prevention.** Plan section weights in the outline based on argumentative load, not on parallel structure. Allow 2x or 3x weight differences between sections doing different amounts of work. + +--- + +## Failure 5: Mid-piece sag + +**Symptom.** The piece sags around the 60% mark. Reader-attention analytics show drop-off at this point. + +**Diagnosis.** Standard mid-piece attention dip, untreated. No micro-thesis, no rhythm variation; the reader is exhausted from sustained density. + +**Cure.** Add a mid-piece micro-thesis at the section boundary nearest the midpoint. Insert a breathing section (anecdote, illustration, or reflective moment) into a stretch of argument-tight prose. Vary visual rhythm in the mid-piece section. + +**Prevention.** During outlining, mark the midpoint and plan the micro-thesis explicitly. During drafting, audit the middle third for rhythm variation. + +--- + +## Failure 6: Recap closing + +**Symptom.** The closing repeated the introduction. "In this piece we covered X, Y, Z. As we have seen, content is important..." + +**Diagnosis.** The writer ran out of energy. The closing was drafted last, in fatigue, and it shows. + +**Cure.** Rewrite the closing using one of the five working patterns: specific call, reframed thesis, open question, personal reflection, or provocation. + +**Prevention.** Write the closing first, or revise the closing last with fresh attention. Closings deserve disproportionate effort because they are disproportionately consequential. + +--- + +## Failure 7: Citation laundering + +**Symptom.** Citations are mostly other content marketing pieces rather than primary or authoritative-secondary sources. + +**Diagnosis.** The writer searched for support for claims and found other content marketing pieces making the same claims. Citing them feels like sourcing; it is not. + +**Cure.** Follow each citation chain back to the original. If the chain ends at a primary source, cite the primary source. If the chain ends at unsourced or weakly sourced content marketing, either find a primary source for the claim or cut the claim. + +**Prevention.** Default to Tier 1-3 sources (primary research, authoritative secondary, industry-credible). Only cite Tier 4 sources for color and context, never for argumentative load. + +--- + +## Failure 8: Visual-count overrun + +**Symptom.** The piece commissioned 12 charts. The team is exhausted from production. Six months later, charts are stale because nobody updated them. Traffic is the same as it would have been with 4 charts. + +**Diagnosis.** Visual count exceeded production capacity and earned-position discipline. + +**Cure.** Cut to the visuals that bear argumentative load the prose alone cannot. Update them on a maintainable cadence. Future pieces budget visuals against capacity rather than against ideal-world maximalism. + +**Prevention.** Apply the MVP-visuals approach: which visuals are load-bearing, which would be nice to have, which would be decoration. Ship the load-bearing ones first; add others only if capacity permits. + +--- + +## Failure 9: Generic case study + +**Symptom.** The case study has no specifics. "A leading enterprise SaaS company" rather than the company name. "Significant revenue growth" rather than the actual percentage. "Several months" rather than the timeline. + +**Diagnosis.** The case study format failed at its primary tax: specificity. Either the case was too confidential to share specifics, or the specifics were never gathered. + +**Cure.** Get specifics. Negotiate with the customer for what can be shared. If specifics genuinely cannot be shared, abandon the case study format and write a different format (general thought-leadership piece on the lessons learned, with the specific case relegated to background). + +**Prevention.** Do not commit to the case study format until specifics are confirmed shareable. Generic case studies fail the format and are less valuable than honest pieces about the lessons without claiming case-study authority. + +--- + +## Failure 10: Diplomatic manifesto + +**Symptom.** The manifesto reads as diplomatic. "Both sides have valid points." "The answer probably lies somewhere in the middle." Hedge stacking on positions that should be specific. + +**Diagnosis.** The writer chose the manifesto format but could not commit to the conviction the format requires. Often reflects organizational risk-aversion: the manifesto's bold framing was approved but its actual conviction was edited out. + +**Cure.** Either rewrite to commit a position (the format demands it), or change the format. A diplomatic position paper that is not pretending to be a manifesto is fine; a manifesto that hedges is broken. + +**Prevention.** Before committing to the manifesto format, confirm the writer (and the organization) actually has a contested position to argue. If hedging is required, write a different format. + +--- + +## Failure 11: Definitive guide with gaps + +**Symptom.** The "definitive" guide has obvious sub-topic gaps that the audience would notice. The piece claims comprehensiveness but does not deliver it. + +**Diagnosis.** The format implies coverage that the piece does not have. Either the gaps reflect topics the writer did not cover deliberately (and should have flagged), or the writer did not realize the gaps existed. + +**Cure.** Either fill the gaps or rename the piece. "The definitive guide to X" with gaps is broken; "A practitioner's guide to X" with the same content but without the comprehensiveness claim is fine. + +**Prevention.** Before claiming definitive-ness, audit against the audience's likely sub-topic expectations. Confirm coverage or change the framing. + +--- + +## Failure 12: Wrong archetype + +**Symptom.** The piece is fighting itself. The writer is trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. The reader senses the structural friction even when they cannot articulate it. + +**Diagnosis.** Archetype-format mismatch or archetype-topic mismatch. The writer chose an archetype that does not fit the work. + +**Cure.** Identify the natural archetype for the topic and the format. Restructure. This is often a substantial revision because the archetype is the spine; changing it changes how sections fit together. + +**Prevention.** Choose archetype before drafting. Confirm the archetype fits the format and the topic. Do not commit to draft until the archetype-format-topic combination is coherent. + +--- + +## Failure 13: Format-tax unpaid + +**Symptom.** The piece is published in a long-form format but does not pay the format's specific tax. A whitepaper without original synthesis. A research report without primary research. A long-form tutorial with broken steps. + +**Diagnosis.** The writer reached for the format's authority without paying the cost the format demands. + +**Cure.** Either pay the tax (do the original work the format requires) or change the format. A piece published in the wrong format reads as a category error to readers familiar with the format. + +**Prevention.** Confirm the format-tax is payable before committing to the format. Format choice is a downstream decision from "what work is the team prepared to do." + +--- + +## The cross-cutting pattern + +Most long-form failures share a single root: the writer chose length, format, or visual ambition first, and chose the structural and substantive depth second. The pieces that read as publication-quality are the ones where the inverse choice is made: substantive depth first, then length, format, and visual ambition follow from the depth. + +The fix for almost any long-form failure starts with the same audit: what is the piece actually doing, what is each section actually contributing, what does the format require, what does the topic need? When those questions get clear answers, the piece either earns its length or shrinks to a length that fits its substance. + +--- + +## Methodology-level choices that stay in the public skill + +The thirteen-plus failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the prevention discipline. + +## Implementation choices that stay internal + +Specific draft-review checklists the team uses. Specific failure-pattern detection in the team's editing tools. Specific reviewer training on the patterns. Specific case-study negotiation templates for getting customer specifics. The team's own conventions for archetype-format fit confirmation. These vary by team, format mix, and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md new file mode 100644 index 0000000..c624e14 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md @@ -0,0 +1,139 @@ +# Format decision framework + +When each long-form format fits, what reader contract it implies, and the format-specific taxes that distinguish credible work from filler dressed in the format's clothes. + +Format selection is the first long-form decision. The wrong format produces predictable failure: a thinly-researched whitepaper reads as a blog post in formal clothing; a manifesto written diplomatically reads as a position paper that committed nothing. Each format has a reader contract. Failing the contract is what readers detect even when they cannot articulate why a piece is not landing. + +--- + +## Case study + +**Reader contract.** "Show me what worked, what did not, and the specifics that let me apply lessons to my own situation." + +**Length norm.** 2,000 to 4,000 words. Shorter feels like a marketing snippet; longer feels padded unless the case is unusually rich. + +**Structural archetype tendency.** Problem-solution, sometimes narrative arc. + +**Format-specific tax.** Specifics. Real company names (or, where confidential, well-disclosed anonymization with enough context to verify the case is real). Real numbers. Real timelines. Real failures alongside successes. Generic case studies that read like marketing collateral fail because the format's value proposition was specificity. + +**Common failures.** Anonymized to the point of meaninglessness ("a leading enterprise SaaS company saw 3x growth"); uncritical success narrative with no failures or surprises; missing methodology (what was measured, how, over what period); no reflection (what would the team change, what limits the lesson's applicability). + +**When the format does not fit.** When the case is too thin to support 2,000+ words of specificity, write a short customer story instead. When the case is so confidential that real numbers cannot be shared, the case study format is the wrong choice. + +--- + +## Whitepaper + +**Reader contract.** "Take me through your reasoning on this question with the rigor I would expect from a serious source. Make an argument I have not seen elsewhere." + +**Length norm.** 3,000 to 8,000 words. + +**Structural archetype tendency.** Layered argument or comparative analysis. + +**Format-specific tax.** Original synthesis. A whitepaper that surveys what other sources already said is not a whitepaper; it is a literature review. The whitepaper format implies the writer is contributing analysis, framing, or synthesis the reader cannot find elsewhere. + +**Common failures.** Survey of the field with no original argument; vendor-thinly-disguised pitch document; methodological hand-waving on the data the argument rests on; conclusion that hedges the position the introduction stated. + +**When the format does not fit.** When the writer does not have an original synthesis to contribute, write a different format. A survey-style "state of the industry" report is a research report, not a whitepaper. A vendor pitch is a pitch deck, not a whitepaper. Calling either a whitepaper to borrow the format's authority is the genre-mismatch failure mode. + +--- + +## Research report + +**Reader contract.** "Show me the data, how you collected it, what it means." + +**Length norm.** 4,000 to 12,000 words. Often longer when methodology and full data appendices are included. + +**Structural archetype tendency.** Taxonomic survey or comparative analysis. + +**Format-specific tax.** Actual primary research. Survey data with disclosed methodology, sample sizes, dates, and limits. Interview data with sample composition disclosed. Original quantitative work the writer did or commissioned. Citing other firms' research and calling the result a research report fails the contract. + +**Common failures.** "We surveyed 300 marketers" with leading questions and no methodology disclosure; cherry-picked data points presented without distribution or variance; methodology paragraph that gestures at rigor without delivering it; findings overstated relative to the sample's actual representativeness. + +**When the format does not fit.** When primary research budget is unavailable. Calling a literature synthesis a research report is genre fraud; write a whitepaper or a definitive guide instead. + +--- + +## Definitive guide + +**Reader contract.** "Be the canonical resource on this topic for the audience the piece names." + +**Length norm.** 4,000 to 10,000 words. + +**Structural archetype tendency.** Taxonomic survey. + +**Format-specific tax.** Actual comprehensiveness. A definitive guide that has obvious topic gaps fails the format. The audience the piece names matters: a definitive guide for senior practitioners and a definitive guide for newcomers are different pieces; trying to be definitive for both audiences usually fails both. + +**Common failures.** Comprehensive on the easy parts of the topic, thin on the hard parts; outdated when published because the format suggests timeless authority but the topic moves quickly; not actually definitive because key sub-topics are missing or treated as out-of-scope without justification. + +**When the format does not fit.** When the topic is too broad for a single piece to cover canonically (then write a hub: see `pillar-content-architecture`). When the topic is so specialized that "definitive" is a category of one and the format's value disappears. + +--- + +## Manifesto + +**Reader contract.** "Tell me what you believe, why, and convince me. Take a position I can argue with." + +**Length norm.** 1,500 to 6,000 words. + +**Structural archetype tendency.** Layered argument or narrative arc. + +**Format-specific tax.** Conviction. The manifesto format demands the writer commit a position with weight. Diplomatic hedging produces a piece that reads as a manifesto in form but a position paper in substance. Readers detect the gap. + +**Common failures.** "Both sides have valid points" framings that the manifesto format does not support; hedge-stacked claims ("typically", "generally", "often") on positions that should be specific; closing that walks back the opening's strength; fear of alienating audience segments producing a piece that alienates everyone by committing to nothing. + +**When the format does not fit.** When the writer does not actually have a contested position to argue. Calling a survey of consensus views a manifesto is a category error. Write a whitepaper or a position paper if hedging is required. + +--- + +## Ebook + +**Reader contract.** "Take me through a body of work as a sequence of related pieces." + +**Length norm.** 8,000 to 30,000+ words across multiple chapters. + +**Structural archetype tendency.** Narrative arc across chapters, with each chapter using its own archetype. + +**Format-specific tax.** Each chapter earns its place. A 12-chapter ebook with 3 chapters that should have been cut signals the format was reached for to add length, not because the work justified the format. Table of contents reading reveals the discipline: are the chapters distinct contributions, or is the ebook one argument padded into 12 pieces? + +**Common failures.** Repetitive chapters covering the same ground from slightly different angles; introduction and conclusion that are throat-clearing rather than load-bearing; missing connective tissue between chapters that leaves the reader uncertain how the chapters fit; no reason for the work to be an ebook rather than a long-form whitepaper. + +**When the format does not fit.** When the work fits in 6,000 words. Stretching a long-form whitepaper to ebook length usually weakens it. Write the long-form whitepaper. + +--- + +## Long-form tutorial + +**Reader contract.** "Take me from where I am to where I want to be, step by step, and make sure every step works." + +**Length norm.** 3,000 to 8,000 words. + +**Structural archetype tendency.** Problem-solution with sequential steps. + +**Format-specific tax.** Every step works. Long-form tutorials fail catastrophically when one step is broken: the reader stops there, cannot continue, and the rest of the tutorial is wasted. The tutorial-tax is verification that each step in the sequence delivers the result the next step assumes. + +**Common failures.** Skipped steps that were obvious to the writer but blocking to the reader; outdated steps that worked when written but no longer (especially common with tutorials referencing fast-moving tools); broken sequences where step 6 assumes a configuration step 4 did not actually create. + +**When the format does not fit.** When the topic does not have a clean sequential path. Branching tutorials where the path varies by reader context are usually better as a hub of shorter pieces (see `pillar-content-architecture`) than as one long-form tutorial trying to handle every branch. + +--- + +## The format-fit decision + +A short framework for choosing. + +1. **What is the reader contract?** What is the reader investing 30+ minutes to get? Specifics (case study)? Original analysis (whitepaper)? Original data (research report)? Comprehensive coverage (definitive guide)? Conviction (manifesto)? A body of work (ebook)? Sequential instruction (long-form tutorial)? +2. **Can the team pay the format-specific tax?** If the format demands specifics and the case is too confidential to share specifics, the format does not fit. If the format demands conviction and the writer wants to hedge, the format does not fit. +3. **Is there an original contribution?** Whitepapers, manifestos, and research reports particularly require original contribution. Definitive guides and tutorials can be valuable as comprehensive synthesis without original argument. +4. **Does the audience expect this format?** Some audiences expect whitepapers (B2B technical), some manifestos (founder-led brands), some research reports (analyst-influenced markets). Format choice signals genre-fit to the audience. +5. **Is the production capacity available?** Long-form tutorials with verified sequential steps cost meaningful verification time. Research reports cost primary-research budget. Format choice must match capacity, or the format-tax goes unpaid and the piece reads as the format-it-pretended-to-be. + +--- + +## Methodology-level choices that stay in the public skill + +The seven format definitions and their reader contracts. The format-specific taxes that distinguish credible work from filler dressed in the format. The decision framework that matches format to work. The genre-mismatch failure modes. The when-the-format-does-not-fit handling. + +## Implementation choices that stay internal + +Specific case study templates the team uses. Specific whitepaper layouts in the brand's design system. Specific research-report data presentation conventions matching the team's design tokens. Specific PDF production tooling. Specific gating workflow integrations with the team's marketing automation. Specific tutorial step-verification scripts that match the stack the tutorials cover. These vary by team, brand, and tooling; methodology applies regardless. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md new file mode 100644 index 0000000..0e357f1 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md @@ -0,0 +1,148 @@ +# Lede patterns for long-form + +Five patterns that work, four that fail, and the underlying frame: the first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. + +Long-form ledes do different work than blog-post ledes. A blog-post lede answers the user's likely query in the first 200 words for SEO. A long-form lede earns attention for the time investment ahead. Both can be true at once (an SEO-driven long-form piece needs to do both), but the long-form discipline is the harder of the two: the lede that answers a query in 200 words is not necessarily the lede that earns 30 minutes of reader attention. + +--- + +## The underlying frame + +Treat the first 150-250 words of a long-form piece as the writer's pitch to the reader. The reader is deciding, paragraph by paragraph, whether the time investment is going to be worth it. The lede has to: + +- Establish that the writer has something specific to say (not a survey). +- Set the thesis or central question the body will deliver. +- Earn enough attention to get the reader past the first H2. + +If the lede does not do these three things, readers leave at the first H2 boundary, before the body has a chance to deliver. + +--- + +## Pattern 1: The contested-claim opener + +**Shape.** A surprising or contested position stated cleanly, then the rest of the piece argues for it. + +**Fits.** Manifestos. Opinionated whitepapers. Position pieces. Long-form analysis where the writer has a specific view. + +**Example shape.** "Most teams treating content marketing as a volume problem will continue to underperform their budget through the end of the decade. The discipline that produces durable content programs is the one most teams skip: deciding what NOT to publish." + +**Why it works.** The reader's response is "wait, why?" The piece exists to answer that. The contested claim earns the reader's attention because the reader is now invested in seeing whether the argument holds. + +**The discipline.** The contested claim must actually be defensible across the piece. Lede claims that the body fails to support produce broken contracts; readers feel deceived. + +--- + +## Pattern 2: The problem-with-stakes opener + +**Shape.** A problem stated with the stakes made tangible. The reader sees themselves or their situation in the problem and wants the solution. + +**Fits.** Case studies. Problem-solution pieces. Long-form tutorials. Manifestos with a clear opposition. + +**Example shape.** "Three months after the migration, organic traffic was down 38%, the team had spent four hundred hours on the project, and nobody could explain where the loss was coming from. The migration had been planned for six months. Every checklist item had been completed. And the search-console graph was still pointing the wrong direction." + +**Why it works.** Stakes ground the abstract. The reader feels the problem before reading any solution, which earns attention for the solution that follows. + +**The discipline.** The stakes must be real, not invented for dramatic effect. Inflated stakes ("the future of marketing is at stake") read as filler. Specific stakes ("the migration cost $400K and three quarters of trust with the executive team") read as honest. + +--- + +## Pattern 3: The data-anomaly opener + +**Shape.** A piece of data that does not fit the consensus, framed as the question the piece will answer. + +**Fits.** Research reports. Analytical whitepapers. Evidence-driven long-form. + +**Example shape.** "The median programmatic SEO program in 2025 generated more than 80% of its traffic from fewer than 5% of its pages. The pattern held across e-commerce, B2B SaaS, marketplaces, and travel. This piece is about why." + +**Why it works.** The data point creates a specific question. The reader wants the answer. The body's job is to deliver the answer with the analytical depth the question deserves. + +**The discipline.** The data point must be load-bearing. If the body's argument does not actually flow from the opening data, the lede was decoration rather than scaffolding. + +--- + +## Pattern 4: The scene opener + +**Shape.** A specific moment, person, or scene that grounds the abstract topic. The reader enters the piece through a concrete situation, and the abstract argument follows. + +**Fits.** Narrative-arc pieces. Magazine-style longform. Pieces where human stakes are part of the argument. Some manifestos. + +**Example shape.** "On a Tuesday morning in September 2024, two engineers stood in front of a whiteboard covered in arrows and tried to explain to the new VP what the data pipeline actually did. The VP had been at the company three weeks. The whiteboard had been there four years. Neither of them could finish a sentence without contradicting the other." + +**Why it works.** Specific scenes hold attention. Readers complete narrative-arc pieces at higher rates than other archetypes; the scene opener uses that pull from the first paragraph. + +**The discipline.** The scene must connect to the piece's argument. Scene openers that are decorative ("imagine you are a marketer in 2026...") rather than load-bearing waste reader attention on prelude. + +--- + +## Pattern 5: The orientation opener + +**Shape.** What this piece covers, who it is for, what reading it costs and what it delivers. Orientation, not throat-clearing. + +**Fits.** Definitive guides. Long-form tutorials. Reference-type long-form where the reader's first question is "is this the right resource for me." + +**Example shape.** "This guide is for engineering leaders deciding whether to migrate from a service mesh to a sidecar-less alternative. It assumes familiarity with Kubernetes and basic mesh concepts. Reading it costs about 30 minutes. It will not cover the original arguments for adopting a mesh; that is a different question. It will cover the migration decision: when it makes sense, what to expect, what fails." + +**Why it works.** Reference-type readers self-select on relevance. The orientation opener saves the wrong reader's time and earns the right reader's attention. Pieces that the right reader does not finish often fail because the wrong readers came in and the right readers left. + +**The discipline.** The orientation must be honest. Guides that overpromise relevance ("for anyone interested in cloud infrastructure") draw wrong readers; guides that underpromise lose right readers. + +--- + +## Failure 1: The throat-clear opener + +**Shape.** "Content marketing has changed dramatically over the past decade. In this article, we will explore how to..." + +**Why it fails.** Filler signal. The reader knows the piece is about content marketing because of the title; restating it wastes attention. The "in this article we will explore" frame is a tour, not an argument; readers respond to arguments more than to tours. + +**The cure.** Cut the throat-clear paragraphs entirely. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clear draft. + +--- + +## Failure 2: The dictionary-definition opener + +**Shape.** "According to Merriam-Webster, X is defined as..." + +**Why it fails.** Signals an unwillingness to commit a position. The reader assumes the writer does not have a specific framing of their own and is hiding behind the dictionary's framing. For long-form, this is fatal: long-form earns reader attention through specific framing. + +**The cure.** State the writer's framing. If the writer needs to disambiguate the term, do so in their own words after stating their position. + +--- + +## Failure 3: The history-of-the-topic opener + +**Shape.** Three or four paragraphs of background before the argument starts. + +**Why it fails.** Long-form readers tolerate background but only after they know why they should care. Front-loading background means the reader leaves before the thesis lands. The history-of-the-topic opener typically reflects the writer's research process leaking into the piece structure: the writer learned the history while researching, so they put it first, even though the reader does not need it first. + +**The cure.** Move history into the body where it supports specific claims. Lead with the thesis or the question the piece answers. + +--- + +## Failure 4: The "in this article we will discuss" tour opener + +**Shape.** "In this article, we will discuss A, then B, then C, then D, then conclude with E." + +**Why it fails.** Flattens the piece into an outline before the writer has earned attention. Tours signal a writer who is not confident the body will hold the reader, so they preview it. The preview itself is what loses the reader: outlines are less interesting than the argument they describe. + +**The cure.** Trust the body to deliver. If the piece needs a navigation aid, use a table of contents or jump links, not an opening tour. + +--- + +## The lede audit + +A short framework for auditing a draft lede. + +1. **Does the first paragraph establish a specific position, problem, data point, scene, or orientation?** If it does general throat-clearing instead, cut. +2. **By the end of the first 250 words, has the thesis or central question of the piece been stated?** If not, the lede is too long. +3. **Does the lede earn the reader's next 30 minutes?** Read the lede as a stranger to the topic. Would you keep reading? If you would skim, the lede is filler. +4. **Does the body deliver on the lede's promise?** Some failed ledes are technically fine but make promises the body does not keep. The audit happens after the body is drafted: does the lede's framing match what the piece actually argues? + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns and the four failures, the underlying frame, the lede audit, the format-tendency mapping, and the lede-body integrity discipline. + +## Implementation choices that stay internal + +Specific lede templates the team has built. Specific draft-review tooling that flags throat-clearing language patterns automatically. Specific A/B testing of lede variants against engagement metrics. The team's own conventions for lede-length norms within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md new file mode 100644 index 0000000..9a95f94 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md @@ -0,0 +1,128 @@ +# Section weight calibration + +How long sections should be relative to each other, varying by format. The audit pattern that catches structural imbalance, and the underlying principle that section weight should match argumentative load. + +Most long-form pieces fail at section weight before they fail at any other dimension. A 6,000-word whitepaper with seven sections of similar length signals that the writer treated each H2 as a quota rather than as an argument-bearing unit. The pieces that read as publication-quality are the ones where some sections breathe and others compress, where argumentative load is reflected in word count, and where filler sections were cut rather than evened out. + +--- + +## The underlying principle + +Section weight should match how much argumentative load the section is bearing. + +Throat-clearing introductions get cut or compressed. Setup sections that orient the reader without making the argument yet are short. Body sections that are doing the actual work of the piece are longest. Closings are specific and tight. When section weights deviate from this, the piece is either padded (sections doing too little for their length) or under-developed (sections doing too much for their length). + +The audit is straightforward. For each section, ask: what argumentative work is this section doing, and is the word count proportional to that work? Sections doing little work that take up much space are filler. Sections doing much work that take up little space are under-developed. + +--- + +## Whitepaper / research report typical weights + +For a 5,000-word whitepaper or research report. + +- **Introduction.** 8-12%. Roughly 400-600 words. Thesis stated, scope set, why the piece exists. +- **Methodology or framing.** 10-15%. Roughly 500-750 words. How the analysis works, what data the argument rests on, what the reader should know about how the writer arrived at the position. +- **Body.** 60-70%. Roughly 3,000-3,500 words. Divided into 3-5 weighted sections. The actual argument or findings. The largest body sections are the load-bearing ones; smaller body sections support or transition. +- **Implications.** 10-15%. Roughly 500-750 words. What the argument means for the reader's situation. +- **Closing.** 3-5%. Roughly 150-250 words. Specific call, reframed thesis, or open question. + +--- + +## Case study typical weights + +For a 3,000-word case study. + +- **Setup and context.** 15-20%. Roughly 450-600 words. The company, the problem, why the problem mattered, what was at stake. +- **Solution narrative.** 50-60%. Roughly 1,500-1,800 words. What the team did, in sequence, with the decision points that mattered. +- **Outcomes.** 15-20%. Roughly 450-600 words. Quantified results, what worked beyond expectations, what did not work as planned. +- **Reflection.** 5-10%. Roughly 150-300 words. What the team would change, what limits the case's applicability. + +The case-study weight discipline. The setup and the outcomes can be roughly even; the solution narrative is the longest section because it is doing the most work; the reflection is short because it is concentrated honest assessment. + +--- + +## Manifesto typical weights + +For a 3,500-word manifesto. + +- **Position.** 5-10%. Roughly 175-350 words. What is believed, stated early and clearly. Manifestos that bury the position lose readers before the argument starts. +- **Argument.** 70-80%. Roughly 2,450-2,800 words. Why, with the layers building intensity. The argument's later layers should be more intense, more specific, or more confrontational than the earlier layers; intensity that flattens loses momentum. +- **Call.** 10-15%. Roughly 350-525 words. What should change as a result of accepting the position, who should change it, what the writer asks of the reader. + +The manifesto weight discipline. Position is short and load-bearing. Argument is long and intensifies. Call is specific and demands action or position-taking from the reader. + +--- + +## Definitive guide typical weights + +For a 7,000-word definitive guide. + +- **Introduction.** 5-8%. Roughly 350-560 words. What the guide covers, who it serves, what reading it costs and pays. +- **Body across taxonomic sections.** 80-85%. Roughly 5,600-5,950 words. Each category in the taxonomy treated with parallel structure. The categories should be roughly even in length unless the taxonomy itself implies asymmetry (some categories are more important than others). +- **Closing and additional resources.** 7-10%. Roughly 490-700 words. Synthesis, recommendation about which categories matter most, pointers to next steps. + +The definitive-guide weight discipline. Most of the weight is in the body categories. The introduction is short because the guide's value is in the taxonomy treatment, not in extended setup. The closing's value is synthesis, not recap. + +--- + +## Long-form tutorial typical weights + +For a 5,000-word long-form tutorial. + +- **Setup.** 10-15%. Roughly 500-750 words. What the reader will achieve, what they need to start, what the success state looks like. +- **Sequential steps.** 70-80%. Roughly 3,500-4,000 words. Each step its own subsection. Steps doing more work get more words; trivial steps stay short. The temptation to even out step lengths produces tutorials that feel padded on simple steps and rushed on hard ones. +- **Troubleshooting and edge cases.** 10-15%. Roughly 500-750 words. What goes wrong, what to do about it, when the reader has likely diverged from the success path. + +The tutorial weight discipline. Steps are weighted by actual difficulty, not by parallel structure. The troubleshooting section is load-bearing because tutorials fail at the failure-points; documenting them is the difference between a tutorial that works and one that strands readers. + +--- + +## Ebook typical weights + +For a 20,000-word ebook with 8 chapters. + +- **Introduction.** 3-5%. Roughly 600-1,000 words. Why the ebook exists, who it serves, how the chapters fit together. +- **Each chapter.** 10-13%. Roughly 2,000-2,600 words per chapter. Chapter weights can vary; a load-bearing chapter at the center may run 3,500 words while a transitional chapter runs 1,500. The variation should reflect actual content load, not arbitrary balancing. +- **Closing chapter or synthesis.** 5-8%. Roughly 1,000-1,600 words. What the body of work amounts to. + +The ebook weight discipline. Chapter weights match chapter load; introduction and closing earn their place by doing connective work the body chapters cannot. + +--- + +## The 3x audit + +A practical heuristic for catching section-weight problems. + +Compare any two sections bearing similar argumentative load. If one is more than 3x the length of the other, the piece is structurally unbalanced. Three responses: + +1. **Split the long section.** If the long section is genuinely doing 3x the work, it is probably actually two or three sections that should be separated for the reader's navigation. +2. **Deepen the short section.** If the long section's length is correct, the short section is probably under-developed and the argument it is making is being skipped. +3. **Acknowledge the imbalance.** If the asymmetry reflects an actual content reality (one category in the taxonomy genuinely matters 3x as much as another), the piece can keep the imbalance but should signal it to the reader so the structure does not feel arbitrary. + +--- + +## Common section-weight failures + +Patterns that show up repeatedly in long-form drafts. + +**Even-section padding.** All H2s come out within 10% of each other in word count. Signal: writer is treating section length as a quota. Cure: identify which sections are actually load-bearing and let them grow while cutting the filler ones back. + +**Front-loaded setup.** Introduction is 25% of the piece. Signal: writer was not confident enough in the thesis to commit it early; spent the first quarter of the piece warming up. Cure: cut the introduction by half, lead with the thesis. + +**Body imbalance.** One body section is 50% of the piece while three others are 10% each. Signal: either the long section is actually multiple sections that should be separated, or the short sections are filler that should be cut. + +**Missing closing.** Closing is 1-2% of the piece. Signal: writer ran out of energy. Cure: rewrite the closing to actual proportional weight; specific call, reframed thesis, or open question. + +**Throat-clearing across sections.** Each section starts with 100-200 words of "as we discussed in the previous section" before getting to the section's actual work. Signal: writer is over-managing reader navigation. Cure: trust the reader; cut the recap paragraphs. + +**Bullet inflation.** A section's word count comes mostly from bulleted lists where each bullet is one expanded sentence. Signal: writer is using bullets to inflate length without doing the integration work. Cure: rewrite the bullets as prose if the integration matters; cut to a tighter list if the items are genuinely parallel. + +--- + +## Methodology-level choices that stay in the public skill + +The underlying principle (weight matches argumentative load), the format-specific weight profiles, the 3x audit, the common section-weight failure patterns and their cures. + +## Implementation choices that stay internal + +Specific word-count tracking tools the team uses to audit drafts. Specific outline templates with weight targets per section in the team's writing system. Specific reviewer dashboards that surface section-weight imbalance for editorial review. The team's own conventions for which formats run shorter or longer than the typical bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md new file mode 100644 index 0000000..1e56d54 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md @@ -0,0 +1,145 @@ +# Structural archetype patterns + +Five archetypes that fit different long-form problems, with worked examples and the patterns for combining archetypes within a single piece. + +The archetype is the spine of a long-form piece. It determines how the argument unfolds, how the reader's attention is structured, and which structural moves feel natural versus which would jar. Selecting the wrong archetype produces a piece that fights itself: the writer trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. + +--- + +## Archetype 1: Problem-solution + +**Shape.** State the problem with weight. Develop why it matters and who is affected. Present the solution. Show how it works in detail. Address objections. Close with implications. + +**Fits.** Case studies. Long-form tutorials. Manifestos with a clear opposition. Pieces where the writer has a specific recommendation and a specific framing of what the recommendation answers. + +**Worked example: a 3,500-word case study.** + +- Setup: the company, the problem, why the problem mattered (15-20% of the piece). +- The solution narrative: what the team did, in sequence, with the decision points that mattered (50-60%). +- Outcomes: quantified results, what worked beyond expectations, what did not work as planned (15-20%). +- Reflection: what the team would change, what limits the case's applicability (5-10%). + +**Strengths.** Direct, action-oriented, satisfies readers looking for "show me how to solve this." Clear forward momentum prevents reader drift. + +**Risks.** Feels formulaic when overused (every case study reading the same shape). Tempts oversimplification: real situations rarely fit a clean problem-solution arc, and forcing them to flattens the case's interest. + +--- + +## Archetype 2: Narrative arc + +**Shape.** Beginning establishing characters and stakes. Middle developing complications. End resolving (or refusing to resolve) the central tension. Time progresses; events follow each other. + +**Fits.** Ebooks across chapters. Some case studies, particularly founder stories, transformation cases, multi-year initiatives. Magazine-style longform. Manifestos where the writer's own journey is part of the argument. + +**Worked example: a 6,000-word transformation case study.** + +- Opening: a specific scene that grounds the abstract topic (the Monday-morning meeting where the problem became inescapable). +- Rising action: the situation getting worse before it gets better, the failed attempts, the false starts. +- Turning point: the specific decision or insight that shifted the trajectory. +- Resolution: what the new state looks like, what the team learned, what is still in progress. +- Coda: the writer's broader observation about what the story illustrates. + +**Strengths.** Most engaging archetype for sustained attention. Readers complete narrative-arc pieces at higher rates than other archetypes. Memorable; readers tell other readers. + +**Risks.** Forced narrative on topics that are not stories. A whitepaper trying to be a narrative arc usually fails because the topic does not naturally have characters, complication, and resolution. The forcing is detectable. + +--- + +## Archetype 3: Layered argument + +**Shape.** Position stated. Layer 1 evidence supporting the position. Layer 2 evidence, often deeper or addressing a different aspect. Layer 3, often counter-arguments or caveats. Synthesis tying the layers together. + +**Fits.** Whitepapers. Manifestos. Position pieces. Analytical long-form. Pieces where the writer is making a case that requires building support across multiple distinct kinds of evidence. + +**Worked example: a 5,000-word whitepaper.** + +- Position: the central claim, stated cleanly in the first 200 words (10%). +- Layer 1: the structural argument (why the position follows from how the system works). 25%. +- Layer 2: the empirical argument (what data supports the position). 25%. +- Layer 3: counter-arguments engaged seriously and answered. 20%. +- Synthesis: what the layers together imply, including implications the position-statement alone did not surface. 15%. +- Closing: specific call or reframed thesis. 5%. + +**Strengths.** Rigorous, defensible, persuasive to skeptical readers. Readers engaging seriously with the position find their objections engaged in the counter-argument layer. + +**Risks.** Feels academic if the synthesis is weak. Layers that do not actually build to a synthesis read as three separate articles stacked. The audit: cut one layer; does the synthesis still work? If yes, that layer was filler. + +--- + +## Archetype 4: Taxonomic survey + +**Shape.** A topic mapped into categories. Each category explored. Relationships among categories surfaced. Sometimes a recommendation about which categories matter most, often a synthesis about what the taxonomy reveals. + +**Fits.** Definitive guides. Research reports surveying a landscape. Long-form tutorials covering a topic with parallel rather than sequential structure. Comparative pieces. + +**Worked example: a 7,000-word definitive guide.** + +- Introduction: what the guide covers, who it serves, what reading it costs and pays (5-8%). +- Taxonomy framing: how the topic divides, why these categories rather than other possible categories (8-12%). +- Category 1, 2, 3, 4 (etc.): each treated with parallel structure (definition, examples, when-it-fits, how-it-works) so readers can navigate. 70-75% across all categories. +- Synthesis: what the taxonomy reveals about the topic as a whole; which categories the writer thinks matter most and why. 7-10%. +- Closing: what to do with the taxonomy. 3-5%. + +**Strengths.** Reference-friendly. Readers come back to taxonomic surveys multiple times to look up specific categories. SEO-friendly because each category often answers a discrete query. + +**Risks.** Feels like a list with subheads if the taxonomy is not actually load-bearing. The audit: does the taxonomy reveal something that a list of items would not? If no, the piece is a list pretending to be a taxonomy. + +--- + +## Archetype 5: Comparative analysis + +**Shape.** Multiple options, frameworks, or positions. Defined axes of comparison. Each option scored or characterized along each axis. Tradeoffs surfaced. The writer's recommendation argued. + +**Fits.** Whitepapers comparing approaches. Decision-guide research reports. Technology comparisons. Evaluations. Pieces where the reader's question is "which of these should I choose." + +**Worked example: a 4,500-word technology comparison.** + +- Setup: the decision the reader is making, why it matters, who this comparison serves (8-10%). +- Comparison axes: the dimensions the writer chose to compare on, with justification for why these axes (5-8%). +- Each option treated along the axes: parallel structure so readers can compare at-a-glance. 50-60%. +- Tradeoff synthesis: what the comparison reveals about which option fits which context. 15-20%. +- Recommendation: the writer's view, with the conditions under which the recommendation holds. 8-10%. +- Closing: how to decide. 3-5%. + +**Strengths.** Decision-useful. Readers facing the decision the comparison addresses get clear input. Pairs well with comparison tables and side-by-side data. + +**Risks.** Feels like a feature matrix if the analysis is shallow. The axes matter: shallow axes (price, speed, ease) produce shallow analysis. Deep axes (failure modes under load, what the platform optimizes for, what the platform forces you to give up) produce useful comparison. + +--- + +## Combination patterns + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. + +**Layered argument with comparative-analysis sections.** A whitepaper arguing a position with a comparative-analysis section showing how the position handles edge cases that competing positions do not. + +**Taxonomic survey with problem-solution chapters.** A definitive guide where each category in the taxonomy includes a problem-solution treatment of how to apply it. + +**Narrative arc with layered-argument moments.** An ebook where the narrative carries the reader through a transformation while individual chapters argue for specific positions encountered along the way. + +**Problem-solution with taxonomic-survey frame.** A long-form tutorial that introduces a taxonomy of failure modes and then walks through the solution sequentially. + +**Comparative analysis with case-study illustration.** A whitepaper comparing approaches with a case study embedded for one of the approaches to ground the analysis. + +The discipline. One archetype as spine; another as variation. Pieces using three archetypes simultaneously fragment; pieces using one archetype rigidly feel formulaic. + +--- + +## Selecting the archetype + +A short framework. + +1. **What is the reader's relationship to the question?** "Tell me how" suggests problem-solution. "Tell me what happened" suggests narrative arc. "Convince me" suggests layered argument. "Map the landscape" suggests taxonomic survey. "Help me decide" suggests comparative analysis. +2. **What does the topic naturally have?** Topics with a clear protagonist, complication, and resolution naturally fit narrative arc. Topics with parallel categories naturally fit taxonomic survey. Topics with a contested position naturally fit layered argument or manifesto-flavored layered argument. +3. **What does the format expect?** Case studies expect problem-solution or narrative arc; whitepapers expect layered argument or comparative analysis; definitive guides expect taxonomic survey. Format-archetype mismatch is detectable to readers even when they cannot articulate it. +4. **What is the writer's strength?** Different writers have different archetype strengths. A writer who naturally argues should not force themselves into narrative-arc longform; a writer who naturally narrates should not force themselves into taxonomic surveys. Assign archetype to writer skill where possible. + +--- + +## Methodology-level choices that stay in the public skill + +The five archetype shapes, the worked examples, the combination patterns, the selection framework, the format-archetype fit tendencies, the writer-skill matching consideration. + +## Implementation choices that stay internal + +Specific archetype templates the team has built for repeat formats. Specific section-length scaffolds the team uses. Specific document templates per archetype in the team's writing tool. Specific archetype tagging in the team's content calendar so editorial mix can be reviewed. The decision rubric the team uses for archetype assignment when multiple writers are working on the same format. These are team-specific operationalizations of the methodology. diff --git a/dist/pi/.agents/skills/media-asset-management/SKILL.md b/dist/pi/.agents/skills/media-asset-management/SKILL.md new file mode 100644 index 0000000..85511d5 --- /dev/null +++ b/dist/pi/.agents/skills/media-asset-management/SKILL.md @@ -0,0 +1,305 @@ +--- +name: media-asset-management +description: "Plan and run a media pipeline for images, video, and downloadable assets. Use this skill when designing image storage and delivery, choosing formats (WebP, AVIF), setting up responsive images, picking a video host, organizing a brand asset library, or auditing a slow image pipeline. Triggers on image pipeline, asset library, DAM, image optimization, WebP, AVIF, responsive images, video hosting, image CDN, asset workflow, media management. Also triggers when images are slow, broken, or scattered across systems." +category: operations +catalog_summary: "Image pipelines, video hosting, asset libraries, format selection" +display_order: 9 +--- + +# Media Asset Management + +Design how images, video, and downloadable files get stored, processed, organized, and served. Stack-agnostic. The principles apply whether you're running a custom pipeline or using a hosted service. + +--- + +## When to use + +- Designing or redesigning the image and media pipeline +- Choosing a media CDN or image service +- Setting up responsive image delivery +- Planning a digital asset management (DAM) system +- Auditing media performance issues +- Picking video hosting and embedding strategy +- Setting up workflows for designers and writers to upload assets +- Migrating media from one platform to another + +## When NOT to use + +- Performance optimization beyond media (use `performance-optimization`) +- Brand identity or photography direction (use `brand-identity`, `art-direction`) +- Content production strategy (use `content-strategy`) +- Single-image optimization (covered in `performance-optimization`) + +--- + +## Required inputs + +- Current media inventory: where assets live, in what formats +- Volume: how many assets, how much storage, how much traffic +- Sources: who creates and uploads media (designers, writers, automated tools) +- Platforms: where media is consumed (web, email, app, partners) +- Performance baseline: current image sizes, load times +- Budget reality: hosted services have monthly costs + +--- + +## The framework: 4 stages + +The media pipeline has four stages. Each has its own decisions. + +### Stage 1: Source + +Where assets enter the system. + +**Sources:** +- Designers (Figma exports, Photoshop, Illustrator) +- Photographers (RAW or JPEG from camera) +- Stock photo libraries +- AI-generated images +- User-generated content (uploads) +- Automated systems (e.g., screenshots, generated thumbnails) + +**At source, decide:** +- File formats accepted (RAW, TIFF, PSD, AI vs delivered formats) +- Naming conventions +- Required metadata (alt text, captions, credits, rights) +- Maximum source resolution (high enough to derive any size; not so high it's wasteful) +- Where source files live (separate from delivered assets) + +**Anti-pattern:** sources and delivered assets in the same place. Hard to find masters. Hard to regenerate. Hard to audit usage. + +### Stage 2: Process + +Transforming source files into delivery formats. + +**Processing decisions:** +- Resize to standard sizes (e.g., a fixed set of widths: 320, 640, 960, 1280, 1920, 2560) +- Compress (lossy or lossless, with quality targets) +- Convert formats (JPEG, WebP, AVIF for raster; SVG for vector) +- Generate thumbnails and previews +- Strip metadata (EXIF, GPS) unless intentionally retained +- Color profile management (sRGB for web) + +**Process options:** +- **Build-time:** Static assets processed during deploy. Predictable, fast at runtime, hard to vary. +- **On-demand:** A service generates the right format/size when requested. Flexible, requires a processing layer. +- **Hybrid:** Static processed sizes plus on-demand for edge cases. + +For sites with many image variants and ongoing change, on-demand wins. For tightly controlled marketing sites, build-time can be simpler. + +### Stage 3: Deliver + +Getting assets to users efficiently. + +**Delivery decisions:** +- CDN: required for any non-trivial volume. Edge caching, global distribution. +- Format negotiation: serve AVIF to browsers that support it, WebP otherwise, JPEG as fallback. Use the `<picture>` element or content negotiation. +- Responsive images: `srcset` and `sizes` attributes so browsers pick the right size for the viewport. +- Lazy loading: `loading="lazy"` for below-the-fold images. +- Async decoding: `decoding="async"` for non-critical images. +- Width and height attributes: always set, prevents layout shift. + +**Modern HTML pattern:** + +```html +<img + src="/image-1280.jpg" + srcset="/image-640.jpg 640w, /image-960.jpg 960w, /image-1280.jpg 1280w, /image-1920.jpg 1920w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +Or for format negotiation: + +```html +<picture> + <source type="image/avif" srcset="/image.avif"> + <source type="image/webp" srcset="/image.webp"> + <img src="/image.jpg" alt="Descriptive alt text" width="1280" height="720"> +</picture> +``` + +### Stage 4: Manage + +Keeping the system organized and useful over time. + +**Management decisions:** +- Asset library or DAM (digital asset management): centralized place for the team to find assets +- Tagging and search +- Version control (designers updating an asset, old version still in use) +- Rights and licensing tracking +- Audit and cleanup (what's not used anymore?) +- Permissions (who can upload, edit, delete) + +A simple shared folder works at low scale. A real DAM is necessary above a few thousand assets or with multiple teams. + +--- + +## Format reference + +For typical web use: + +| Format | Use for | Avoid for | +|---|---|---| +| AVIF | Photographs, complex images. Best compression. | Browser support edge cases (rare in 2026, ubiquitous now) | +| WebP | Photographs, illustrations. Good compression. Wide support. | Print, archival | +| JPEG | Photographs (fallback). Universal support. | Sharp-edged graphics, transparent backgrounds | +| PNG | Sharp-edged graphics, transparent backgrounds, screenshots. Lossless. | Photographs (file size) | +| SVG | Logos, icons, simple illustrations. Scalable. | Photographs, complex art | +| GIF | Effectively obsolete. Use video formats for animation. | Anything modern | +| MP4 (H.264) | Video, universal support. | Static content | +| WebM (VP9 / AV1) | Video, better compression. | Older browsers | + +For most sites: serve AVIF/WebP for modern browsers, JPEG/PNG fallback. SVG for vector. MP4 for video. + +--- + +## Workflow + +### Step 1: Inventory + +What assets exist? Where? In what state? + +- Image count and total storage +- Average sizes (KB) per format +- Image-related performance metrics +- Number of pages with broken or missing images +- Source files vs delivered files + +### Step 2: Audit performance + +For a sample of pages: +- Image weight per page (target: under 500KB total for marketing pages) +- Number of image requests +- Are responsive images used? +- Are modern formats served? +- Is there layout shift from missing dimensions? + +Tools: Lighthouse, WebPageTest, your CDN's analytics. + +### Step 3: Pick the pipeline + +Three reasonable patterns: + +**Pattern A: Static, build-time** +- Assets in repo or storage bucket +- Build process generates sizes and formats +- Served via CDN +- Good for: static sites, low asset churn, tight performance control + +**Pattern B: Image CDN with on-demand** +- Source uploads to a bucket or service +- An image CDN (Cloudinary, imgix, Cloudflare Images, Bunny, etc.) processes on-demand via URL parameters +- Good for: mid-to-large sites, frequent asset changes, multiple variants + +**Pattern C: Headless CMS with built-in image API** +- CMS holds source assets +- CMS provides image API for resizing, format conversion +- Good for: content-heavy sites, non-technical content uploaders, when CMS is already chosen + +The patterns aren't mutually exclusive. Big sites often use Pattern A for design assets, Pattern B for content images. + +### Step 4: Define standards + +Document: +- Naming conventions +- Required metadata (alt text, attribution) +- Maximum source dimensions +- Minimum source dimensions per use case +- Approved formats +- File size targets + +Make these enforceable through tooling where possible (CI checks on file sizes, alt text required by CMS). + +### Step 5: Set up workflows + +For each source type: + +| Source | Workflow | +|---|---| +| Designer | Export from Figma, drop into bucket, automated processing handles the rest | +| Writer | Upload through CMS, CMS prompts for alt text | +| Photographer | RAW into source bucket, designer or automation creates web variants | +| User upload | Pass through the image service, automatic moderation if applicable | + +Document who does what. Workflows that aren't documented break. + +### Step 6: Build the asset library + +For all but the smallest sites: +- Centralized DAM or shared library +- Tag taxonomy (subject, style, brand, campaign, etc.) +- Search across tags and metadata +- Documented rights for each asset (stock license, custom commission, work-for-hire, etc.) +- Sunset workflow (rights expire, asset retires) + +### Step 7: Monitor and audit + +- Performance metrics on image-heavy pages +- Storage costs +- CDN costs +- Broken image alerts (404 on referenced media) +- Unused asset cleanup (storage costs accumulate) + +### Step 8: Document the pipeline + +A pipeline document covers: +- Diagram of source → process → deliver → manage +- Tools used at each stage +- Standards and naming conventions +- Workflows for common cases +- Escalation when something breaks + +--- + +## Failure patterns + +**Source files in the delivery bucket.** 50MB RAW files served to users. Fix: separate sources from delivered. + +**Single image format for every browser.** JPEG-only when AVIF could be 30-50% smaller. Use format negotiation. + +**Missing width and height attributes.** Causes layout shift, hurts CLS metric. Set always. + +**Lazy loading hero images.** Above-the-fold images shouldn't be lazy-loaded. Lazy below the fold. + +**Eager loading everything.** All images load on page load. Use `loading="lazy"` for below-fold. + +**No responsive images.** Mobile gets the desktop image. Wasteful, slow. Use `srcset` and `sizes`. + +**One source resolution.** Source is the delivery resolution. Can't generate retina or larger. Source should be 2-3x the largest delivered size. + +**Stripping all metadata.** Removes alt text, removes attribution. Strip GPS and personal EXIF; keep semantic metadata. + +**Random naming.** `IMG_4823.jpg`, `Screenshot 2024-03-15.png`. Hard to find later. Use a naming convention. + +**No alt text.** Accessibility failure, SEO failure. Make alt text required at upload. + +**Storage growing unbounded.** Old, unused assets pile up. Quarterly cleanup or automated lifecycle policies. + +**One person knows the pipeline.** When they're out, no one can fix issues or onboard new sources. Document. + +--- + +## Output format + +A media pipeline document includes: + +- **Inventory:** current asset count, formats, storage +- **Pipeline diagram:** source → process → deliver → manage with tools at each stage +- **Format and size standards:** what gets generated, when +- **Naming and metadata conventions:** with examples +- **Workflows by source type:** designer, writer, photographer, user +- **Performance baseline and targets:** weight per page, format adoption, etc. +- **Asset library:** tool, taxonomy, search, rights tracking +- **Monitoring:** performance, costs, broken assets +- **Roadmap:** improvements over the next 1-2 quarters + +--- + +## Reference files + +- [`references/responsive-image-patterns.md`](references/responsive-image-patterns.md): Copy-paste HTML patterns for common responsive image scenarios (hero, content, art-directed, format negotiation), with explanations. diff --git a/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md b/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md new file mode 100644 index 0000000..721f670 --- /dev/null +++ b/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md @@ -0,0 +1,373 @@ +# Responsive Image Patterns + +Copy-paste HTML patterns for common image scenarios. Each pattern is annotated with what it does and when to use it. + +The principles work across stacks. The HTML is the same whether you're in Next.js, WordPress, Webflow, or vanilla HTML. + +--- + +## Pattern 1: Simple responsive image + +The default for most content images. Same image at different sizes. + +```html +<img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w, + /img/photo-1920.jpg 1920w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +**What's happening:** +- `src`: fallback for browsers that don't support srcset (rare today, still good practice) +- `srcset`: list of available sizes with their widths +- `sizes`: tells the browser how wide the image will display at different viewport widths +- `width`/`height`: prevents layout shift; the browser reserves space before the image loads +- `loading="lazy"`: delays loading until near the viewport +- `decoding="async"`: doesn't block rendering on this image +- `alt`: accessibility and SEO + +**When to use:** Most content images, blog post bodies, article illustrations. + +--- + +## Pattern 2: Hero image (above the fold) + +The hero image needs special handling because it's critical to first paint. + +```html +<img + src="/img/hero-1920.jpg" + srcset=" + /img/hero-640.jpg 640w, + /img/hero-960.jpg 960w, + /img/hero-1280.jpg 1280w, + /img/hero-1920.jpg 1920w, + /img/hero-2560.jpg 2560w + " + sizes="100vw" + width="1920" + height="1080" + fetchpriority="high" + decoding="async" + alt="Descriptive alt text"> +``` + +**Differences from Pattern 1:** +- No `loading="lazy"` (hero must load immediately) +- `fetchpriority="high"` (hint to load this first) +- Larger size options for full-width displays +- `sizes="100vw"` (image takes full viewport width) + +Optionally preload the hero in the document head: + +```html +<link + rel="preload" + as="image" + href="/img/hero-1280.jpg" + imagesrcset="/img/hero-640.jpg 640w, /img/hero-960.jpg 960w, /img/hero-1280.jpg 1280w, /img/hero-1920.jpg 1920w, /img/hero-2560.jpg 2560w" + imagesizes="100vw"> +``` + +This tells the browser to start the request before HTML parsing reaches the `<img>`. + +**When to use:** The single hero or banner at the top of a page. Don't preload more than one image; it competes with critical resources. + +--- + +## Pattern 3: Format negotiation + +Serve modern formats to browsers that support them, fall back to JPEG. + +```html +<picture> + <source + type="image/avif" + srcset=" + /img/photo-640.avif 640w, + /img/photo-960.avif 960w, + /img/photo-1280.avif 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <source + type="image/webp" + srcset=" + /img/photo-640.webp 640w, + /img/photo-960.webp 960w, + /img/photo-1280.webp 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +**What's happening:** +- The browser tries each `<source>` in order +- The first one with a supported `type` is used +- The `<img>` is the fallback if no `<source>` matches +- The `<img>` also provides the alt text and dimensions for all formats + +**When to use:** Whenever your pipeline can produce multiple formats. AVIF is now well-supported; WebP is universal. JPEG is the safe fallback. + +**Easier alternative:** A modern image CDN can do format negotiation server-side based on the `Accept` header. The HTML stays as Pattern 1; the CDN serves the right format. Often the better approach. + +--- + +## Pattern 4: Art direction (different crops at different breakpoints) + +Sometimes you want a different image (not just a different size) on mobile vs desktop. + +```html +<picture> + <source + media="(max-width: 768px)" + srcset=" + /img/portrait-640.jpg 640w, + /img/portrait-960.jpg 960w + " + sizes="100vw"> + <source + media="(min-width: 769px)" + srcset=" + /img/landscape-1280.jpg 1280w, + /img/landscape-1920.jpg 1920w + " + sizes="100vw"> + <img + src="/img/landscape-1280.jpg" + width="1920" + height="1080" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +**What's happening:** +- On screens 768px wide or less, use the portrait crop +- On larger screens, use the landscape crop +- Different aspect ratios per device + +**When to use:** Marketing pages where the image composition matters at each breakpoint. Often for hero images of people or products. + +**Caution:** Set explicit dimensions to match each crop, or be careful about layout shift between crops. CSS aspect-ratio can help. + +--- + +## Pattern 5: Background images + +For decorative backgrounds set in CSS, use `image-set()` for responsive selection: + +```css +.hero { + background-image: image-set( + url('/img/hero-1280.jpg') 1x, + url('/img/hero-2560.jpg') 2x + ); +} +``` + +For format negotiation in CSS: + +```css +.hero { + background-image: image-set( + url('/img/hero.avif') type('image/avif'), + url('/img/hero.webp') type('image/webp'), + url('/img/hero.jpg') type('image/jpeg') + ); +} +``` + +**Note:** Background images are decorative. If the image carries meaning, it should be an `<img>` with alt text, not a CSS background. + +--- + +## Pattern 6: SVG (vectors) + +For logos, icons, simple illustrations: + +```html +<img + src="/img/logo.svg" + width="200" + height="40" + alt="Brand name"> +``` + +Or inline for icons (better for theming with CSS): + +```html +<svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true"> + <path d="..."/> +</svg> +``` + +**Notes:** +- SVG is resolution-independent. No `srcset` needed. +- For decorative icons, use `aria-hidden="true"`. For meaningful icons, provide a label. +- Inline SVG can be styled with CSS. Linked SVG cannot. + +--- + +## Pattern 7: Lazy-loaded video + +Treat video like a heavy image: + +```html +<video + width="1280" + height="720" + poster="/img/video-poster.jpg" + preload="metadata" + controls> + <source src="/video/clip.webm" type="video/webm"> + <source src="/video/clip.mp4" type="video/mp4"> + <track kind="captions" src="/video/clip-captions.vtt" srclang="en" label="English"> + Your browser does not support the video tag. +</video> +``` + +**Notes:** +- `poster`: image shown before play, sized to match video +- `preload="metadata"`: only loads enough to know duration, not the whole file +- `<track>`: captions for accessibility (always include for non-decorative video) +- Multiple `<source>`: browser picks the first supported format + +**For autoplay video** (decorative, no audio): + +```html +<video + autoplay + muted + loop + playsinline + poster="/img/poster.jpg" + preload="auto"> + <source src="/video/loop.mp4" type="video/mp4"> +</video> +``` + +`muted` and `playsinline` are required for autoplay on most browsers. Be cautious about autoplay; many users disable it or find it annoying. + +--- + +## Pattern 8: User-uploaded images + +For images uploaded by users (avatars, content), set defensive defaults: + +```html +<img + src="/uploads/avatar-medium.jpg" + width="200" + height="200" + loading="lazy" + decoding="async" + alt="" + onerror="this.style.display='none'"> +``` + +**Notes:** +- Process uploads through a moderation step before serving (especially for public sites) +- Generate consistent sizes (small, medium, large) +- Strip EXIF (GPS, etc.) for privacy +- Have a fallback (default avatar, broken image hidden) +- alt text from user-provided context where possible + +--- + +## Pattern 9: Image with caption + +Use `<figure>` for semantically grouped image and caption. + +```html +<figure> + <img + src="/img/photo-1280.jpg" + srcset="/img/photo-640.jpg 640w, /img/photo-960.jpg 960w, /img/photo-1280.jpg 1280w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> + <figcaption>Caption visible to all users.</figcaption> +</figure> +``` + +**Notes:** +- alt text describes the image for users who can't see it +- caption provides context for everyone +- They serve different purposes; both are useful when there's a caption + +--- + +## Anti-patterns + +**Lazy-loading the hero image.** Above-the-fold images should load immediately. + +**Missing width and height.** Causes layout shift. Always set. + +**Same image, different file extensions.** `image.jpg` and `image.JPG` for the same content. Pick one convention. + +**Tracking pixels masquerading as images.** Use proper analytics, not 1x1 GIFs. + +**Decorative images with descriptive alt text.** A decorative pattern with `alt="ornamental swirl background"` is noise for screen readers. Use `alt=""` for purely decorative. + +**Decorative images with no alt attribute at all.** Screen readers may announce the filename. Use `alt=""` (empty, not missing). + +**Inline base64 images for non-trivial sizes.** Bloats HTML. Use a URL. + +**Forgetting captions in non-English contexts.** Captions and alt text need translation just like any other content. + +--- + +## Alt text guidelines + +- **Decorative:** `alt=""` (empty) +- **Functional (e.g., a search button icon):** describes the action: `alt="Search"` +- **Informative:** describes the content the user is missing: `alt="Hand holding a coffee cup at a wooden desk"` +- **Complex (charts, infographics):** brief alt + a fuller description in nearby text or `aria-describedby` + +Alt text should: +- Convey what the image conveys, not what it depicts +- Be concise (typically under 125 characters) +- Not start with "Image of" or "Picture of" (screen readers say that already) +- Include important text that's part of the image + +--- + +## Tooling notes + +Most modern frameworks have an `<Image>` component that wraps these patterns. Examples include Next.js Image, Astro Image, Nuxt Image. They handle: + +- Format negotiation automatically +- Responsive sizes +- Lazy loading defaults +- Width/height enforcement + +If you're using a framework with such a component, prefer it over hand-rolling the HTML. The framework version usually includes optimizations the hand-rolled version misses. + +If you're not using a framework, the patterns here are the right baseline. diff --git a/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md b/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md new file mode 100644 index 0000000..971d963 --- /dev/null +++ b/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md @@ -0,0 +1,256 @@ +--- +name: monitoring-and-alerting +description: "Design and run a monitoring system for a website or web app. Use this skill when setting up uptime checks, defining SLOs, configuring error tracking, choosing what to alert on, designing on-call rotations, or fixing alert fatigue. Triggers on monitoring, alerts, uptime, SLO, SLA, error rate, on-call, pager, alert fatigue, observability, dashboards, what should we monitor. Also triggers when an incident reveals a gap in monitoring." +category: operations +catalog_summary: "SLO design, uptime checks, alert routing, on-call rotations" +display_order: 5 +--- + +# Monitoring and Alerting + +Decide what to watch, what to alert on, and how to make sure the right person finds out when things break. + +--- + +## When to use + +- Setting up monitoring on a new site or service +- Defining SLOs (service level objectives) and error budgets +- Choosing which alerts page someone vs which go to a quiet channel +- Designing or fixing on-call rotation +- Diagnosing alert fatigue +- Filling monitoring gaps revealed by an incident +- Migrating monitoring vendors + +## When NOT to use + +- Responding to an active incident (use `incident-response`) +- Writing the post-mortem (use `after-action-report`) +- Designing analytics dashboards for product metrics (use `analytics-strategy`) +- Performance optimization itself (use `performance-optimization`) + +--- + +## Required inputs + +- The system you're monitoring (URLs, services, dependencies) +- Existing monitoring tools (uptime, errors, logs, APM) +- Business hours and team timezone(s) +- Who is on-call or available for incidents +- Existing SLOs or success metrics, if any + +--- + +## The framework: 4 layers + +Monitoring works in layers. Skip a layer and you'll miss a class of problems. + +### Layer 1: Availability + +Is the site up? The simplest, most important layer. + +- HTTP checks from multiple regions (every 1-5 minutes) +- DNS resolution checks +- Certificate expiration checks +- Status code checks (alert on 5xx, not just timeout) + +Threshold: any sustained downtime (more than 2 consecutive failed checks) pages. + +### Layer 2: Correctness + +The site is up, but is it serving the right thing? + +- Synthetic checks (a script that loads the homepage, clicks a button, validates expected text) +- Critical user journeys (signup, checkout, search) +- Content presence checks (homepage hasn't gone blank) +- API contract checks (response shape and key fields are present) + +Threshold: failures of critical-path synthetics page. Non-critical page-level synthetics alert during business hours only. + +### Layer 3: Performance + +The site is up and correct, but is it fast enough? + +- Core Web Vitals (LCP, INP, CLS) from real users (RUM) +- Synthetic performance (Lighthouse, WebPageTest, custom) +- API response times (p50, p95, p99) +- Database query times for slow queries +- Dependency response times (third-party APIs) + +Threshold: regressions from baseline (e.g., p95 doubled in 5 minutes). Don't alert on absolute thresholds without baselines. + +### Layer 4: Errors and anomalies + +The site is up, correct, and fast for most, but errors are happening. + +- Error rate (% of requests returning 5xx) +- Client-side error rate (uncaught JS exceptions) +- Log error volume (unexpected spikes) +- Anomaly detection (traffic falling off a cliff) +- Background job failures +- Queue depth + +Threshold: rate-based, not count-based. "Error rate above 1% for 5 minutes" beats "more than 100 errors per minute." + +--- + +## SLOs and error budgets + +A Service Level Objective is the target for reliability. Common form: "99.9% of homepage requests succeed in under 2 seconds, measured over 30 days." + +The components: +- **The thing you're measuring** (homepage requests) +- **The success criterion** (returns 2xx in under 2 seconds) +- **The target** (99.9% of them) +- **The window** (over 30 days) + +The error budget is the inverse: 0.1% of requests can fail. If you've used the whole budget, slow down on risky changes. + +### Picking SLOs + +Don't aim for 100%. Don't aim for "five nines" (99.999%) unless you really need it. Each nine costs an order of magnitude more. + +| SLO | Allowed downtime per month | +|---|---| +| 99% | 7 hours, 18 minutes | +| 99.9% | 43 minutes | +| 99.95% | 21 minutes | +| 99.99% | 4 minutes, 22 seconds | +| 99.999% | 26 seconds | + +For most marketing sites, 99.9% is plenty. For SaaS, 99.95% is reasonable. Anything higher needs significant infrastructure investment. + +### Using error budgets + +When the budget is healthy, ship aggressively. When the budget is half-spent, slow down. When the budget is exhausted, freeze risky changes until reliability recovers. + +This is what makes SLOs useful: they create a feedback loop between reliability and velocity. + +--- + +## Workflow + +### Step 1: Inventory what's already monitored + +What tools are in place? What checks exist? What dashboards? What alerts? + +Many teams have a tangle of half-configured tools. The first job is the inventory. + +### Step 2: Map the system + +Draw the architecture. Front-end, back-end, database, third-party APIs, queues, workers. Each box is a candidate for monitoring. + +For each box, ask: +- What does "up" mean? +- What does "correct" mean? +- What does "fast" mean? +- What's the most common failure mode? + +### Step 3: Define the SLOs + +Pick 3-5 SLOs. They should be: +- Tied to user-visible behavior (not internal metrics) +- Achievable with current infrastructure +- Measured automatically +- Reviewed at least quarterly + +### Step 4: Set up checks across the 4 layers + +For each box, configure checks at each layer. Some boxes won't have all four; that's fine. + +| Box | Availability | Correctness | Performance | Errors | +|---|---|---|---|---| +| Homepage | HTTP check | Synthetic | LCP/INP | JS errors | +| Login API | HTTP check | Synthetic flow | p95 latency | 5xx rate | + +### Step 5: Decide what pages and what doesn't + +Three tiers: + +1. **Page (wakes someone up):** site down, critical flow broken, error rate spike, security incident. +2. **Notify (during business hours):** non-critical synthetic failure, performance regression, slow query, dependency degradation. +3. **Log (no notification):** anomalies for later review, low-priority warnings, info-level events. + +Anything in tier 1 must be: +- Actionable (the on-call can do something about it) +- Important (it represents real impact) +- Rare (less than 1-2 per week is the goal) + +If tier 1 alerts fire frequently, alert fatigue sets in. People stop responding. + +### Step 6: Configure routing + +Where do alerts go? + +- Tier 1: paging system (e.g., PagerDuty, Opsgenie). Direct to on-call. +- Tier 2: chat channel (Slack, Teams). Tagged with the area. +- Tier 3: dashboard or log only. + +Each tier should have a documented escalation path. If the on-call doesn't ack within 5-15 minutes, escalate. + +### Step 7: Build dashboards + +One dashboard per audience: + +- **Real-time ops dashboard:** current health, recent alerts, error rates, throughput +- **SLO dashboard:** SLO status and error budget consumption +- **Per-service dashboards:** detail for individual services or pages +- **Executive dashboard:** uptime over weeks/months, key business metrics + +Dashboards are different from alerts. Alerts say "look now." Dashboards say "here's what's happening." + +### Step 8: Run an alert audit + +Every quarter, audit: +- Which alerts fired? Were they actionable? +- Which alerts didn't fire when they should have? +- Are any alerts noisy (more than once a week, low actionability)? +- Are runbooks up to date? +- Have SLOs been met? Any consistently breached? + +Tune the system. Monitoring drifts without active maintenance. + +--- + +## Failure patterns + +**Alert on cause, not symptom.** "CPU is high" is a cause. "Users are slow" is a symptom. Alert on symptoms; investigate causes. + +**Alert without a runbook.** If the on-call doesn't know what to do, the alert is useless. Every paging alert needs a runbook (even a one-line one). + +**No baselines for "normal."** Alerting on "more than 100 errors per minute" sounds reasonable but a busy day might exceed that without anything being wrong. Use rate-based and anomaly-based alerts. + +**Single-region monitoring.** Your monitoring service in the same region as your site means you'll miss regional outages and you'll get woken up when monitoring itself has issues. + +**Monitoring the monitoring.** Or rather, not. If your alerting platform is down, who tells you? Most paging services offer their own status feeds. Subscribe. + +**Too many tiers of severity.** P0/P1/P2/P3/P4 with different SLAs becomes a sorting exercise. Three tiers (page, notify, log) is plenty. + +**Synthetics that don't match reality.** A synthetic that hits the homepage every minute tests "is the homepage up." It doesn't test "is the actual user flow working." Build synthetics for the journeys that matter. + +**Static thresholds that never get tuned.** Traffic grows, behavior changes, thresholds set last year are wrong. Review thresholds quarterly. + +**On-call rotation with no handoffs.** Each new on-call has to figure out the system. Document. Run weekly handoff meetings or async updates. + +**Pager fatigue.** If on-call is paged more than once or twice a week, something is wrong. Audit the alerts. Reduce, tune, or fix the underlying issues. + +--- + +## Output format + +A monitoring plan includes: + +- **System map:** what's being monitored +- **SLOs:** the 3-5 reliability targets +- **Checks per layer:** availability, correctness, performance, errors +- **Alert tiering:** what pages, what notifies, what logs +- **Routing:** where alerts go, escalation paths +- **Dashboards:** what audiences see +- **Runbooks:** linked from each paging alert +- **Audit cadence:** when this gets reviewed + +--- + +## Reference files + +- [`references/slo-design-guide.md`](references/slo-design-guide.md): Detailed walkthrough of writing SLOs, error budget policies, and common SLO mistakes for web services. diff --git a/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md b/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md new file mode 100644 index 0000000..1f5ec49 --- /dev/null +++ b/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md @@ -0,0 +1,246 @@ +# SLO Design Guide + +A walkthrough for designing Service Level Objectives that are useful, achievable, and aligned to user experience. + +--- + +## What an SLO is and isn't + +A Service Level Objective is a target for reliability, expressed as a percentage of "good" events out of all events, measured over a specific time window. + +An SLO is: +- A reliability target the team commits to +- Measured automatically +- Tied to user-visible behavior +- Reviewed and adjusted over time + +An SLO is not: +- A guarantee (that's an SLA, which has contractual consequences) +- A goal to maximize (100% is the wrong target) +- A vanity metric (uptime alone tells you almost nothing) +- Permanent (revise as the system evolves) + +--- + +## The structure of a good SLO + +Every SLO has four components: + +1. **The thing being measured (the SLI - Service Level Indicator)** +2. **The success criterion (what counts as "good")** +3. **The target (the percentage of events that should be "good")** +4. **The window (the time period over which to measure)** + +Example: + +> "99.9% of homepage requests return a 2xx status code in under 2 seconds, measured over a rolling 30-day window." + +Breaking it down: +- SLI: latency and status of homepage requests +- Good event: 2xx response in under 2 seconds +- Target: 99.9% +- Window: rolling 30 days + +If the system serves 1 million homepage requests in 30 days, this SLO allows 1,000 bad events. That's the error budget. + +--- + +## Picking SLIs + +The SLI is what you measure. Pick SLIs that reflect what users actually experience. + +### Good SLI categories + +**Availability:** the proportion of valid requests that succeed. +- "% of HTTP requests that return non-5xx" +- "% of API calls that complete without error" + +**Latency:** the proportion of requests that complete fast enough. +- "% of homepage requests with TTFB under 600ms" +- "% of search queries returning results in under 1 second" + +**Quality:** the proportion of requests that produce correct results. +- "% of recommendations served from the personalized model (vs fallback)" +- "% of search queries returning at least one result" + +**Freshness:** the proportion of data that's fresh enough. +- "% of cached pages updated within the last 24 hours" +- "% of analytics data ingested within 15 minutes of event" + +**Throughput:** the proportion of time the system handles required load. +- "% of minutes during which queue depth was below 1000" + +### Bad SLI patterns + +**CPU or memory utilization.** These are causes of problems, not symptoms users feel. Don't make them SLIs. + +**Number of incidents.** Too coarse. One nasty incident can blow it for the whole window. + +**Average response time.** Averages hide tail latency. P95 or P99 is closer to user experience. + +**Internal metrics that don't map to user impact.** "Database replica lag." Useful to monitor. Not a great SLO unless it directly affects users. + +--- + +## Picking targets + +Target percentages have specific implications. Here's the practical math: + +| Target | Allowed bad time per 30 days | Allowed bad events per million | +|---|---|---| +| 90% | 3 days | 100,000 | +| 99% | 7 hours, 18 minutes | 10,000 | +| 99.9% | 43 minutes, 30 seconds | 1,000 | +| 99.95% | 21 minutes, 48 seconds | 500 | +| 99.99% | 4 minutes, 22 seconds | 100 | +| 99.999% | 26 seconds | 10 | + +Each "9" added is roughly 10x harder. Pick the lowest target that's acceptable to users. + +### How to pick + +1. **Look at current performance.** What's the system actually achieving? Use that as the floor. +2. **Look at user expectations.** What do users tolerate? For a marketing site, occasional slow pages are fine. For a payment system, they're not. +3. **Look at competitive bar.** What do similar services achieve? +4. **Pick something achievable but slightly aspirational.** If the current achievement is 99.5%, set the SLO at 99.7%. Don't jump to 99.99%. + +### Common mistakes + +**Setting the SLO at 100%.** Impossible. Wastes infrastructure. Creates false promises. + +**Setting the SLO based on what marketing wants to advertise.** If marketing says "99.99% uptime!" but engineering can't deliver, the SLO is fiction. + +**Setting different SLOs for different teams without coordination.** End-to-end user experience depends on all of them. If one team has a 99.9% SLO and another has 99%, the combined experience is worse than either. + +--- + +## Picking windows + +The window affects how SLOs feel. + +**Calendar windows:** "99.9% in March." Resets at month boundaries. Good for reporting, bad for operating (the budget can be exhausted on March 1 with nothing you can do until April). + +**Rolling windows:** "99.9% over the last 30 days." Always current. Better for operations because the budget continuously updates. + +Common windows: +- 7 days: too short, noise dominates +- 28-30 days (rolling): the sweet spot for most operations +- 90 days: better for SLAs and stability assessment, worse for fast feedback + +For most teams: 30-day rolling. + +--- + +## Error budgets + +The error budget is `1 - SLO`. If your SLO is 99.9%, your error budget is 0.1%. + +The budget is what allows for change. Every release, every config change, every dependency update consumes some budget. The budget exists so the team can ship. + +### Error budget policy + +A written policy that says what happens when the budget is at different levels. Example: + +| Budget remaining | What's allowed | +|---|---| +| > 50% | Normal operation. Ship features, run experiments. | +| 25-50% | Caution. Postpone risky migrations. Prefer smaller releases. | +| 10-25% | Slow down. Only ship reliability fixes and security patches. Defer feature releases. | +| < 10% | Freeze. No non-urgent changes. Focus on reliability. | + +This is the operationally useful part of SLOs. It connects reliability to product velocity in a measurable way. + +### Burning the budget + +If the budget burns at a rate of, say, 10% in an hour, that's a fast burn. Alert on fast burns: "we'll exhaust the budget in 4 hours at this rate." + +Slow burn alerts catch sustained low-grade issues. Fast burn alerts catch acute incidents. + +### Refilling the budget + +The budget refills as the rolling window moves forward. If today is the last day of a bad month, tomorrow the worst day rolls off and the budget recovers slightly. + +Don't "make up" budget by tightening the SLO temporarily. SLOs are user-facing commitments. Don't move them to make numbers look better. + +--- + +## Multi-tier SLOs + +For complex systems, one SLO isn't enough. Multi-tier SLOs cover different aspects. + +A typical web app might have: + +1. **Availability SLO:** 99.95% of requests return non-5xx. +2. **Latency SLO:** 99% of requests complete in under 1 second. +3. **Critical flow SLO:** 99.9% of checkout flows complete successfully. + +Each has its own error budget and policy. + +For products with multiple tiers of importance, you can also have different SLOs per tier: + +- Critical pages (homepage, checkout): 99.95% +- Standard pages (product, category): 99.9% +- Long-tail pages (search, archive): 99% + +This reflects user impact: a slow checkout matters more than a slow archive page. + +--- + +## Reviewing and revising SLOs + +SLOs aren't set-and-forget. Review: + +- **Quarterly:** is the SLO still right? Has the system or user expectation changed? +- **After major incidents:** did the SLO catch it? Should the SLO be tighter? +- **After major launches:** did the new feature change the math? +- **Annually:** big-picture review of all SLOs. + +Common revisions: +- Tightening (e.g., 99.9% → 99.95%) when the system has improved and the team can sustain it +- Loosening (e.g., 99.95% → 99.9%) when the previous target was too aggressive (rare, requires justification) +- Splitting an SLO into multiple (e.g., one combined SLO becomes separate availability and latency SLOs) +- Retiring SLOs that no longer reflect what matters + +--- + +## Example: a marketing site + +For a typical marketing site: + +| SLO | Target | Window | +|---|---|---| +| Homepage availability (2xx response) | 99.9% | 30-day rolling | +| Homepage latency (TTFB < 800ms) | 95% | 30-day rolling | +| Form submission success | 99.5% | 30-day rolling | +| Critical-page availability (top 10 pages 2xx) | 99.9% | 30-day rolling | + +Error budget policy: +- Above 50% budget: ship freely +- 10-50% budget: defer risky changes +- Below 10%: freeze non-essential changes + +This is a reasonable starting point. Tune based on actual operating history. + +--- + +## Example: a SaaS product + +For a SaaS product with paying customers: + +| SLO | Target | Window | +|---|---|---| +| API availability (non-5xx) | 99.95% | 30-day rolling | +| API latency (p95 under 500ms) | 99% | 30-day rolling | +| Login success | 99.99% | 30-day rolling | +| Critical action success (e.g., save data) | 99.95% | 30-day rolling | +| Background job completion within 1 hour | 99% | 7-day rolling | + +Error budget policy is stricter (paying customers have higher expectations). Below 25% budget triggers a slowdown; below 10% triggers a freeze with executive approval needed to override. + +--- + +## When you don't have an SLO yet + +Start small. Pick one SLO that maps to the most important user-facing behavior. Live with it for a quarter. Add more once the team is comfortable. + +Trying to roll out 10 SLOs at once usually fails. Trying to roll out 1 SLO and using it well usually succeeds. diff --git a/dist/pi/.agents/skills/multi-step-form-design/SKILL.md b/dist/pi/.agents/skills/multi-step-form-design/SKILL.md new file mode 100644 index 0000000..5e53791 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/SKILL.md @@ -0,0 +1,332 @@ +--- +name: multi-step-form-design +description: "Designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. Honest about kitchen-sink-single-page (overwhelms before the user starts), progress-theater (steps without genuine staging), and genuinely-staged (each step earns its own page) patterns. Triggers on multi-step form, multi-page form, form wizard, signup wizard, lead form, application form, intake form, configurator, onboarding form. Also triggers when a long form is converting poorly, when an audience is dropping off mid-form, or when a multi-step form is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing multi-step forms that respect cognitive load while maintaining completion intent. Distinguishes kitchen-sink-single-page (overwhelms) from progress-theater (steps without genuine staging) from genuinely-staged (each step earns its own page)" +display_order: 4 +--- + +# Multi-Step Form Design + +A senior growth practitioner's playbook for designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. + +Most multi-step forms are either kitchen-sink-single-pages dressed up as steps or arbitrary chunking that adds friction without adding clarity. The form looks more sophisticated; the completion rate does not move; the audience is no better served than before. + +The multi-step forms that work do something different. Each step represents a coherent unit of cognitive work the user can complete with confidence. Progress indicators reinforce momentum. Conditional logic responds to earlier answers and removes irrelevant fields. The form feels like a guided process, not an obstacle course. + +The voice is the senior growth practitioner who has watched multi-step forms convert at twice the single-page rate and watched them collapse to half. Practical, opinionated about when steps add value and when they add friction, willing to call out arbitrary chunking that does not earn its complexity. + +When to use this skill: scoping a multi-step form for the first time, auditing a long single-page form that converts poorly, deciding when to break a form into steps and when to keep it on one page, or designing the conditional logic that makes the form feel adaptive. + +--- + +## What this skill covers + +This skill spans multi-step form design across acquisition, onboarding, and intake contexts. The growth-tooling distinctions: + +- `lead-magnet-design` covers lead-magnet methodology; forms are one delivery surface for lead magnets but this skill is about the form itself. +- `landing-page-copy` is the page wrapping the form. This skill is the form itself. +- `accessibility-audit` covers accessibility deeply; forms have specific accessibility requirements; this skill references but does not replace accessibility-audit. +- `pm-spec-writing` is the spec for engineers building the form. This skill is about WHAT to build; pm-spec-writing is about communicating it. +- **`multi-step-form-design` (this skill)** is the form's structure, step architecture, progression, and validation. + +The audience: growth marketers, product marketers, marketing teams designing acquisition forms, in-house teams designing onboarding flows, agencies running form-based growth tooling for clients. + +Out of scope: form-builder platform configurations (those stay implementation-side); deep accessibility audits (covered by `accessibility-audit`); landing-page copy that wraps the form (covered by `landing-page-copy`). + +--- + +## The multi-step decision: when to break into steps vs keep single-page + +Before designing the steps, decide whether the form should be multi-step at all. + +**Multi-step earns the build when:** + +- The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. +- The fields naturally group into logical categories. Personal info, then situation, then preferences. Steps that reflect real groupings respect cognitive load. +- The audience benefits from progressive commitment. Each step builds investment; the user is more likely to complete after they have engaged with step 2 than they would have been if they had seen step 5's complexity upfront. +- Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page. + +**Multi-step does NOT earn the build when:** + +- The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. +- The fields do not group naturally. Arbitrary chunking is friction. +- The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. +- The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes; the maintenance overhead is real. + +The decision is not "should the form be multi-step"; it is "is multi-step the right structure for this specific data collection and audience." + +Detail in [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md). + +--- + +## Kitchen-sink-single-page vs progress-theater vs genuinely-staged + +The keystone framing. + +**Kitchen-sink-single-page.** 30 fields on one page. Overwhelms before the user even starts. Drop-off near 100 percent on anything beyond a contact form. The audience scrolls, sees the length, and leaves. Cost: the form's data collection scope is correct; the structure is wrong; nobody completes it. + +**Progress-theater.** The form is broken into 5 steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone. Step 4: company. Step 5: role." The progress bar exists; the staging logic does not. Cost: the form feels broken; users reach step 3 wondering why they did not just fill a single page; the completion rate may be slightly better than kitchen-sink but the audience perceives the format as gimmicky. + +**Genuinely-staged.** Each step represents a coherent unit of cognitive work. The user finishes a step and feels they accomplished something. Steps progress from low-friction to higher-commitment as intent compounds. Cost: the design effort upfront is significant; the maintenance is real; the conversion rate often outperforms both alternatives meaningfully. + +The litmus test. Ask a user who completed step 2 what they just did. Can they describe the unit of work as something coherent ("I gave you the basics about my company") or is the answer atomized ("I typed my company name in a field")? Coherent answers signal genuinely-staged; atomized answers signal progress-theater. + +--- + +## Step architecture: what belongs on each step + +The structure that makes steps coherent. + +**The principle.** Each step should represent a coherent unit of work from the user's perspective. + +**Common step patterns.** + +- **Identity step.** Who the user is. Name, email, basic role. Low-friction; opens the form. +- **Context step.** What the user's situation is. Company size, industry, current setup. Medium-friction; user shares context. +- **Need step.** What the user is trying to accomplish. Goals, challenges, priorities. Higher-friction; user articulates intent. +- **Detail step.** Specifics needed to act on the user's request. Budget, timeline, specific requirements. Highest-friction; saved for last. +- **Confirmation step.** Review and submit. Summarizes what the user provided. + +**Step sequencing principle.** Low-friction first; commitment compounds; high-friction at the end after the user has invested. + +**Step coherence test.** Can each step be described in one sentence as a unit of work? "Step 2: tell us about your company's situation" beats "Step 2: company name, size, industry, and revenue range." + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## Progress indicator design + +When to show progress, what to show, how it builds momentum. + +**The principle.** Progress indicators reinforce momentum and reduce uncertainty about how much is left. + +**Progress indicator patterns.** + +- **Step counter.** "Step 2 of 4." Simple, common, effective for short forms (3-6 steps). +- **Progress bar.** Visual fill showing percentage complete. Effective for forms with variable-length steps where step count alone is misleading. +- **Step list.** Named steps shown with the current one highlighted. Useful when the user benefits from seeing what comes next. +- **No indicator.** Sometimes appropriate for very short forms (2-3 steps) where the indicator overhead exceeds its value. + +**Progress indicator failures.** + +- **Indicator that shifts mid-form.** "Step 4 of 5" becomes "Step 4 of 7" because conditional logic added steps. The user feels misled. +- **Indicator that hides remaining work.** Showing "almost done" when 5 fields remain on the next step. +- **Indicator that is decorative without being honest.** Progress that looks fast but the next step is the longest one. + +**Progress indicator discipline.** The indicator must reflect the actual remaining work, not flatter the user. + +Detail in [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md). + +--- + +## Conditional logic + +Branching that responds to earlier answers. + +**The principle.** Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +**Conditional logic patterns.** + +- **Show or hide fields based on previous answers.** "If user selected 'enterprise,' show enterprise-specific fields." +- **Skip entire steps.** "If user does not have a current CRM, skip the 'CRM details' step." +- **Adapt the language.** "If user is in healthcare, use healthcare-specific terminology in subsequent fields." +- **Adapt the destination.** "If user selected 'integration question,' route to the integration team after submission." + +**Conditional logic strengths.** + +- Removes irrelevant friction. +- Makes the form feel adaptive and intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +**Conditional logic risks.** + +- Maintenance complexity grows quickly. +- Testing becomes harder (more paths through the form). +- Progress indicators must adapt or honestly disclose the variability. + +**The simplicity preference.** Add conditional logic only when it produces real value. Conditional logic for decoration adds maintenance without lift. + +Detail in [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md). + +--- + +## Save-and-resume mechanics + +When to offer save-and-resume, how to communicate trust. + +**The principle.** Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. + +**When save-and-resume helps.** + +- Forms that require document uploads or specific information (W-2, financial details, technical configurations). +- Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms). +- Forms where the user benefits from coming back to verify or update. + +**When save-and-resume does not help.** + +- Quick lead-capture forms (under 60 seconds to complete). +- Single-session forms where save-and-resume adds complexity without lift. + +**Save-and-resume mechanics.** + +- **Email-link recovery.** "Save your progress; we will email you a link to continue." The most common pattern. +- **Account-based persistence.** Forms that require account creation persist by default. +- **Anonymous-session save.** Browser-based save without identification. Lowest friction but limited to the same browser/device. + +**Trust communication.** Users hesitate to save partial sensitive information. The form should communicate clearly: what is saved, how long it persists, who can access it, how to resume. + +Detail in [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md). + +--- + +## Validation strategy + +Per-step vs end-only. + +**Per-step validation.** Each step's fields are validated before allowing progression. The user catches errors early. + +**Strengths.** + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +**Weaknesses.** + +- Can feel intrusive if validation is too strict on every keystroke. +- May block the user from progressing when they want to revise later. + +**End-only validation.** All validation runs at submission. + +**Strengths.** + +- User completes uninterrupted. +- Validation logic is simpler. + +**Weaknesses.** + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. + +**The hybrid pattern.** Required-field validation per step; full validation at end. The user gets immediate feedback on critical issues; nuanced validation runs at submission. + +**Validation message discipline.** + +- Helpful messages: "Phone number must include area code" beats "Invalid phone number." +- Inline placement: errors appear next to the field, not in a banner. +- Specific guidance: "Try a value between 1 and 1000" beats "Out of range." + +Detail in [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon, and how to fix it. + +**Step-by-step drop-off tracking.** Track the percentage of users who reach each step and the percentage who complete it. The diagnostic data informs which steps need redesign. + +**Common drop-off points.** + +- **First field.** User clicked into the form, looked at it, and left. Often signals the form is too long or the value of completing is not clear. +- **Mid-form.** User abandoned mid-process. Often signals fatigue, sensitive questions, or unclear progress. +- **Final submission.** User completed all fields but did not submit. Often signals submission anxiety, validation error fear, or unclear next-step. + +**Remediation patterns.** + +- **First-field drop-off.** Reduce form length; clarify the value of completing; add social proof or trust signals. +- **Mid-form drop-off.** Audit the specific step where drop-off concentrates; add progress indicator; reduce field count on that step; reword sensitive questions. +- **Final-submission drop-off.** Add a confirmation step; reduce final-step requirements; clarify what happens after submission. + +**The instrumentation requirement.** Without per-step tracking, drop-off remediation is guesswork. Set up tracking before the form launches. + +Detail in [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md). + +--- + +## Form anti-patterns + +Patterns that look like multi-step forms but degrade conversion. + +**The kitchen-sink-single-page.** 30 fields on one page. Detail in keystone framing. + +**The progress-theater form.** Steps without genuine staging. Detail in keystone framing. + +**The arbitrary-chunking form.** Each step has 1-2 fields; user wonders why this is multi-step. + +**The hidden-length form.** No progress indicator; user does not know how long the form is; abandonment climbs. + +**The interrogation-form-with-steps.** 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +**The validation-strict form.** Validation that rejects too aggressively, frustrating users with valid inputs. + +**The mobile-broken form.** Form works on desktop, breaks on mobile. + +**The trust-broken form.** Save-and-resume offered without clear trust communication; user does not save because they distrust persistence. + +**The variable-step form.** Conditional logic that changes the step count visibly; user feels misled about remaining work. + +Detail in [`references/form-anti-patterns.md`](references/form-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md). + +- "Form converts at 4 percent; we expected 12 percent." Likely too long, or the value of completing is not clear, or the form is mobile-broken. +- "Drop-off concentrates at step 3." Specific-step issue; audit step 3's field count, sensitivity, and clarity. +- "Mobile completion is half of desktop." Mobile design issue; audit form behavior on actual devices. +- "Validation rejects valid inputs." Validation strictness; relax the validation or improve the input formats accepted. +- "Users abandon at submission." Final-step anxiety; add confirmation, reduce final requirements, clarify next step. +- "Save-and-resume is offered but nobody uses it." Trust communication missing; users do not save because they distrust persistence. +- "We added conditional logic; the form feels confusing." Conditional logic complexity outweighs benefit; simplify. +- "We split the form into more steps; conversion did not change." Steps were not coherent; progress-theater pattern. +- "Progress indicator shifts mid-form." Conditional logic added steps unexpectedly; either fix the indicator or fix the conditional logic. + +--- + +## The framework: 12 considerations for multi-step form design + +When designing or auditing a multi-step form, walk these 12 considerations. + +1. **The multi-step decision.** Is multi-step the right structure for this data and audience, or would single-page serve? +2. **Genuinely-staged, not kitchen-sink or progress-theater.** Each step represents a coherent unit of work from the user's perspective. +3. **Step architecture sound.** Identity, context, need, detail, confirmation. Low-friction first; commitment compounds. +4. **Progress indicator honest.** Reflects actual remaining work; does not shift mid-form. +5. **Conditional logic adds value.** Removes irrelevant fields without adding maintenance overhead. +6. **Save-and-resume mechanics fit the form.** Offered when the form length warrants; trust clearly communicated. +7. **Validation strategy matched to form.** Per-step for required fields; end-only for nuanced validation. +8. **Drop-off measurement instrumented.** Per-step tracking from launch. +9. **Mobile experience tested.** Form works on the devices the audience uses. +10. **Field count audited.** Each field necessary; non-essential fields removed. +11. **Final-step clear.** Submission action obvious; what happens after submission communicated. +12. **Maintenance discipline.** Quarterly review of conversion, drop-off, validation, and conditional logic. + +The output of the framework is a multi-step form that respects cognitive load, maintains completion intent, and converts the audience into the action the form is designed to capture. + +--- + +## Reference files + +- [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md) - When to break into steps vs keep single-page. The conditions that warrant the multi-step structure. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. +- [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md) - Step counter, progress bar, step list. When each works. Indicator failures. +- [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md) - Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. +- [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md) - When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. +- [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md) - Per-step vs end-only vs hybrid. Validation message discipline. +- [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md) - Step-by-step tracking. Common drop-off points and remediation patterns. +- [`references/form-anti-patterns.md`](references/form-anti-patterns.md) - The patterns that look like multi-step forms but degrade conversion. +- [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: multi-step forms earn completion when each step earns its place + +The multi-step forms that work as compounding assets are the ones the audience completes without resentment. Not because the form is short. Not because the steps are decorative. Because each step represented a coherent unit of cognitive work the user could complete with confidence, and the cumulative experience felt guided rather than obstructed. + +That is the bar. Below the bar are kitchen-sink-single-pages (overwhelm before the user starts) and progress-theater forms (decorative steps without coherence). Above the bar are genuinely-staged forms where the structure earns its complexity. + +The discipline is in the design choices upstream of the form. The decision to make the form multi-step (or not). The step architecture that makes each step coherent. The progress indicator that reflects honest progress. The conditional logic that removes friction without adding confusion. The validation that catches errors helpfully. The drop-off measurement that informs ongoing improvement. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md b/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md new file mode 100644 index 0000000..7281d88 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md @@ -0,0 +1,187 @@ +# Common multi-step form failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the form did not convert" or "audiences abandon mid-form" or "we cannot tell what is going wrong." + +--- + +## "Form converts at 4 percent; we expected 12 percent." + +**The diagnosis.** Likely one of: too long, value of completing not clear, mobile-broken, or the audience-fit is wrong. + +**The cure.** Audit the form length (`references/multi-step-decision-criteria.md`); audit the value proposition on the landing page (`landing-page-copy`); test on mobile devices; verify the audience matches the form's purpose. + +--- + +## "Drop-off concentrates at step 3." + +**The diagnosis.** Specific-step issue. Audit step 3's field count, sensitivity, and clarity. + +**The cure.** Per-step audit. Reduce field count if step 3 has too many; reword sensitive questions; clarify why step 3 is needed; consider whether step 3's content belongs there at all. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## "Mobile completion is half of desktop." + +**The diagnosis.** Mobile design issue. The form was designed for desktop and breaks on mobile. + +**The cure.** Mobile-first redesign. Touch-friendly inputs, single question per screen on long steps, sliders sized for thumb interaction, progress indicator visible without scroll. Test on actual devices. + +--- + +## "Validation rejects valid inputs." + +**The diagnosis.** Validation strictness. Rules are over-specified, rejecting inputs the system can handle. + +**The cure.** Audit validation rules (`references/validation-strategy-patterns.md`). Email with plus-signs, international phone formats, non-Latin names should all pass. + +--- + +## "Users abandon at submission." + +**The diagnosis.** Final-step anxiety. The CTA is unclear; the user does not know what happens; the final field requires information they did not have. + +**The cure.** Clarify the CTA ("Get my PDF" beats "Submit"). Add post-submission preview. Add a confirmation step. Move final-field demands earlier if the user needs time to gather info. + +--- + +## "Save-and-resume is offered but nobody uses it." + +**The diagnosis.** Trust communication missing. Users do not save because they distrust persistence. + +**The cure.** Trust copy alongside the save option. What is saved, how long, who can access. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## "We added conditional logic; the form feels confusing." + +**The diagnosis.** Conditional logic complexity outweighs benefit. Either too many rules or rules that change the user's experience visibly without explanation. + +**The cure.** Simplify the conditional logic. Remove rules that do not justify their value. Communicate variability if it remains. Detail in `references/conditional-logic-patterns.md`. + +--- + +## "We split the form into more steps; conversion did not change." + +**The diagnosis.** Steps were not coherent. Progress-theater pattern. Splitting fields without grouping them into meaningful units does not produce the multi-step benefit. + +**The cure.** Restructure into genuinely-staged steps. Each step should represent a coherent unit of cognitive work. Detail in `references/step-architecture-patterns.md`. + +--- + +## "Progress indicator shifts mid-form." + +**The diagnosis.** Conditional logic added or removed steps unexpectedly. + +**The cure.** Either fix the indicator to handle conditional steps honestly, or fix the conditional logic to not change step counts visibly. Detail in `references/progress-indicator-patterns.md`. + +--- + +## "We cannot tell where users abandon." + +**The diagnosis.** Instrumentation missing. No per-step tracking. + +**The cure.** Add per-step tracking before any further changes. Without data, remediation is guesswork. Detail in `references/drop-off-measurement-and-remediation.md` (instrumentation requirement). + +--- + +## "Conversion is fine; lead quality is poor." + +**The diagnosis.** The form is converting the wrong audience. Either the audience-fit on the landing page is broad, or the form does not filter for the audience the team needs. + +**The cure.** Tighten the audience-fit upstream. The form may need fewer fields (less interrogation) but more qualifying fields (audience-segmentation). Detail in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Conversion was strong at launch; it has declined 30 percent over a year." + +**The diagnosis.** Form decay. Stale references, broken integrations, validation rules that no longer match reality. + +**The cure.** Quarterly maintenance audit. Update references, fix broken integrations, refresh validation rules. + +--- + +## "We A/B tested adding a progress indicator; conversion did not change." + +**The diagnosis.** Either the form was already short enough that an indicator was not needed, or the indicator was poorly designed (dishonest, hidden, or confusing). + +**The cure.** Audit the indicator's design. If the form is genuinely short (3-4 steps), the indicator may not lift conversion much. If the form is longer, the indicator should help; redesign if it is not. + +--- + +## "The form looks great in QA; users complain it is broken." + +**The diagnosis.** QA tested with the team's devices and browsers; users have different setups. + +**The cure.** Cross-browser, cross-device, cross-network testing. Consider real-world conditions (slow connections, older devices, accessibility tools). + +--- + +## "The form's submit button is gray; we cannot figure out why." + +**The diagnosis.** Validation logic is preventing submission but the error is not surfaced. Common cause: a hidden required field or a cross-field validation that fails silently. + +**The cure.** Surface all validation errors visibly. Submit button state should follow form state visibly; the user should see why submit is disabled. + +--- + +## "We added save-and-resume; nobody resumes." + +**The diagnosis.** Either users save but the recovery link does not arrive, or the resume experience is broken, or the form's value did not persist (the user's interest faded). + +**The cure.** Test the recovery email deliverability. Test the resume experience end-to-end. Consider whether save-and-resume is genuinely needed or whether it is decorative. + +--- + +## "Sales says the form-sourced leads are wrong type." + +**The diagnosis.** Audience-fit mismatch. The form is converting the wrong segment. + +**The cure.** Audit the form's qualifying fields and the landing page that drives traffic. Either tighten the audience filter at the landing page, or add qualifying fields to the form that route based on segment. + +--- + +## "We made the form shorter; submissions went up but lead quality went down." + +**The diagnosis.** The fields removed were qualifying fields. Conversion improved because friction dropped; quality dropped because the qualifying signal was lost. + +**The cure.** Decide whether quality or quantity matters more. Restore qualifying fields if quality matters; accept the lower quality if volume is the priority. Often the right answer is to restore some fields and accept some conversion impact. + +--- + +## "The form works on Chrome desktop; it crashes on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The form was tested on the team's primary platform. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use. + +--- + +## "We translated the form to Spanish; conversion is half what English is." + +**The diagnosis.** Translation quality, cultural mismatch, or audience-fit issue specific to the Spanish-speaking audience. Often a combination. + +**The cure.** Audit the translation quality (idiomatic vs literal). Audit cultural assumptions (date formats, phone formats, name conventions). Verify the audience matches. + +--- + +## The pattern across failures + +Most multi-step form failures fall into one of three patterns. + +**Pattern 1: The form is the wrong structure.** Kitchen-sink-single-page, progress-theater, arbitrary-chunking, hidden-length. The fix is structural. + +**Pattern 2: The form does not match the audience or the device.** Mobile-broken, validation-strict-against-international-inputs, audience-fit weak. The fix is matching the form to where the audience actually is. + +**Pattern 3: The form decays.** Stale references, broken integrations, drift in conditional logic, instrumentation drift. The fix is maintenance discipline. + +The metric pattern: form failures often look fine on submission count alone. The signal is in completion rate, drop-off per step, lead quality, and downstream conversion. Programs that track only submission counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (structure, audience-device match, decay). The principle that submission count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md new file mode 100644 index 0000000..c24901b --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md @@ -0,0 +1,270 @@ +# Conditional logic patterns + +Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. + +Conditional logic responds to earlier answers and removes irrelevant fields. Done well, it makes the form feel adaptive and intelligent. Done poorly, it adds maintenance complexity without improving the user experience. + +--- + +## The relevance principle + +Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +**The principle's win.** A user who answered "no, I do not have a CRM today" should not be asked "what CRM do you use today" three steps later. The conditional logic removes the friction. + +**The principle's risk.** Conditional logic adds maintenance complexity. Each branch has to be tested. Each branch can break. The simplicity preference: add conditional logic only when it produces real value. + +--- + +## Pattern A: Show or hide fields based on previous answers + +The most common conditional logic pattern. + +**How it works.** + +- A field appears or disappears based on the answer to an earlier question. +- "If user selected 'enterprise,' show enterprise-specific fields." +- "If user selected 'has current solution,' show 'current solution name' field." + +**Example.** + +Question: "Do you currently use a CRM?" +- Yes → show field "Which CRM do you use today?" +- No → hide that field; show "What is your current process for managing customer data?" + +The form adapts to the user's situation in real time. + +**Strengths.** + +- Removes irrelevant fields. +- Makes the form feel intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +**Weaknesses.** + +- Each branch needs testing. +- Late additions to the form can break conditional logic in unexpected ways. + +**When to use.** When showing all fields would be confusing or when irrelevant fields cause significant drop-off. + +--- + +## Pattern B: Skip entire steps + +Conditional logic at the step level. + +**How it works.** + +- Based on early answers, an entire step is skipped or included. +- "If user does not have a current CRM, skip the 'CRM details' step entirely." +- "If user is in healthcare, include the 'compliance requirements' step." + +**Strengths.** + +- Removes whole sections of irrelevant content. +- Form length adapts to the user. + +**Weaknesses.** + +- Progress indicators must adapt or honestly disclose variability. +- The user may notice the form's variability and feel confused. + +**When to use.** When entire categories of fields are irrelevant to some users (e.g., enterprise-only fields for non-enterprise users). + +--- + +## Pattern C: Adapt the language + +Conditional logic that changes terminology based on user context. + +**How it works.** + +- The form's wording adapts to the user's industry, role, or context. +- "If user is in healthcare, use 'patient' terminology in subsequent fields." +- "If user is technical, use technical terms; if non-technical, use plain language." + +**Strengths.** + +- Form feels personalized. +- Reduces cognitive load on the user (they see terminology that matches their context). + +**Weaknesses.** + +- Significantly more copy to maintain. +- Risk of inconsistent or awkward language. + +**When to use.** When the audience spans contexts where terminology genuinely differs (B2C vs B2B, technical vs non-technical, regulated vs unregulated industries). + +--- + +## Pattern D: Adapt the destination + +Conditional logic that affects what happens after submission. + +**How it works.** + +- Based on answers, the form routes to different teams or triggers different follow-ups. +- "If user selected 'integration question,' route to the integration team after submission." +- "If user selected 'enterprise,' trigger an enterprise-sales follow-up sequence." + +**Strengths.** + +- The user gets matched to the right team or sequence. +- Sales and support efficiency improve. + +**Weaknesses.** + +- Routing complexity grows; failure modes (wrong team, missed routing) increase. +- The user does not see the routing logic; mistakes are invisible to the user but visible in downstream impact. + +**When to use.** When the form serves multiple downstream paths and the routing materially affects the user's experience. + +--- + +## Pattern E: Branching forms + +Different paths through the form for different users. + +**How it works.** + +- Based on early answers, the user takes a different path entirely. +- "If user selects 'individual,' show the individual flow; if 'team,' show the team flow." + +**Strengths.** + +- Highly tailored experience. +- Each user only sees fields relevant to them. + +**Weaknesses.** + +- Significantly more complex to build and test. +- Hard to compare paths because users took different forms. +- Maintenance is hard. + +**When to use.** When the audience genuinely splits into distinct groups that need fundamentally different forms. Use sparingly. + +--- + +## The simplicity preference + +Add conditional logic only when it produces real value. + +**The discipline.** For each piece of conditional logic, ask: +- Does this remove genuine friction? +- Is the maintenance cost justified by the friction removed? +- Could a simpler approach (single-page with sectioned design) achieve the same goal? + +**The over-conditional form.** A form with 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively, the form is fragile and hard to maintain. + +**The cure.** Audit conditional logic periodically. Remove rules that do not justify their maintenance overhead. + +--- + +## Conditional logic and progress indicators + +The interaction matters. + +**The challenge.** A form with conditional steps may have variable total step count. The progress indicator must accommodate. + +**Approaches.** + +- **Variable indicator.** "Step 2 of 5-7" or "Step 2 (about halfway)." Communicates the variability. +- **Range indicator.** "Step 2 of about 5." Approximate but honest. +- **Dynamic indicator.** Updates as the user's answers determine the path. Risk of feeling unstable. +- **Step-list indicator.** Shows all possible steps; current step highlighted. Variability visible upfront. + +The discipline. Choose an approach that does not lie about progress. + +--- + +## Conditional logic testing + +Test every branch of conditional logic. + +**The challenge.** A form with 5 conditional rules has 32 possible paths through the form. Testing all paths is infeasible at scale; testing critical paths is the discipline. + +**Critical paths.** + +- The most common path (most frequent user type). +- Each conditional rule's branch (one path that triggers it, one that does not). +- Edge cases (combinations that could produce unexpected behavior). + +**Testing methods.** + +- **Manual testing.** Walk through critical paths. +- **Automated testing.** Programmatic tests for each branch. +- **User testing.** Watch users complete the form; surface confusion or paths that break. + +**Production monitoring.** Track which paths users take. Sudden shifts may indicate logic issues. + +--- + +## Conditional logic and analytics + +Track which conditional branches trigger. + +**Why.** Understanding which branches are common informs maintenance priorities. A branch nobody triggers may not be worth maintaining; a branch everyone triggers may not need to be conditional. + +**The metric.** Per-branch trigger rate. Per-branch conversion rate. + +**The discipline.** Periodically review the data. Retire conditional rules that do not pay off. + +--- + +## Conditional logic and form maintenance + +Conditional logic decays. + +**What decays.** + +- Rules that point to fields that have been renamed or removed. +- Rules that produce paths now unused as the audience shifts. +- Rules whose triggering questions have been reworded. + +**Maintenance cadence.** Quarterly audit alongside the broader form audit. + +**The drift indicator.** Bug reports about specific paths failing; analytics showing unexpected branching behavior; testing surfaces broken rules. + +--- + +## Common conditional logic failures + +**Hidden complexity.** Many rules silently affecting many fields; the form's behavior is hard to reason about. + +**Unintended interactions.** Two rules that work individually but conflict when combined. + +**Stale rules.** Rules that point to fields no longer in the form. + +**Dead branches.** Conditional paths nobody triggers; maintenance overhead with no payoff. + +**Indicator-rule mismatch.** Progress indicator that does not handle conditional step count. + +**Untested edge cases.** Unusual answer combinations that produce broken paths. + +**Rule-driven layout shifts.** Fields appearing and disappearing causing visual jumpiness. + +**Over-conditional forms.** 25+ rules across the form; the maintenance burden exceeds the friction-reduction value. + +--- + +## When NOT to use conditional logic + +Some situations work better without conditional logic. + +**Short forms.** Adding conditional logic to a 5-field form rarely justifies the complexity. + +**Forms with stable audiences.** When everyone takes roughly the same path, conditional logic adds variability without value. + +**Forms in early stages.** A new form benefits from simplicity before adding complexity. Launch simple; add conditional logic when data shows where it would help. + +**Forms with high maintenance constraints.** Teams that cannot maintain complex forms should default to simpler designs. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. The simplicity preference. Conditional logic and progress indicators. Conditional logic testing. Conditional logic and analytics. Maintenance considerations. Common failures. When NOT to use conditional logic. + +## Implementation choices that stay internal + +Specific conditional rules for specific forms. Specific tooling for rule implementation and testing. The team's audit calendars and rule-retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md b/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md new file mode 100644 index 0000000..7f88000 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md @@ -0,0 +1,263 @@ +# Drop-off measurement and remediation + +Step-by-step tracking. Common drop-off points and remediation patterns. + +Drop-off is where the form fails. Measuring drop-off per step is the diagnostic that informs every other improvement. Without per-step tracking, drop-off remediation is guesswork. + +--- + +## The instrumentation requirement + +Set up per-step tracking before the form launches. + +**The minimum tracking.** + +- **Step start.** User landed on this step. +- **Step completion.** User completed this step (clicked Next). +- **Step abandonment.** User left without completing. + +**The derived metrics.** + +- **Step completion rate.** Of users who reached this step, what percentage completed it? +- **Step drop-off rate.** Of users who reached this step, what percentage abandoned at this step? +- **Funnel completion rate.** Of users who started the form, what percentage submitted? + +**Why instrumentation matters.** Drop-off remediation requires knowing where users abandon. Aggregate "the form converts at 8 percent" tells you something is wrong; per-step data tells you where. + +--- + +## Common drop-off points + +Three patterns recur across multi-step forms. + +**First-field drop-off.** User clicked into the form, looked at it, and left at the first field. + +Common causes. +- Form is too long; user saw the length and bounced. +- The value of completing is not clear; user does not know what they get. +- Form is mobile-broken; user could not interact. +- Form looks suspicious or untrustworthy. + +**Mid-form drop-off.** User abandoned partway through. + +Common causes. +- Fatigue; the form is too long and the user lost interest. +- Sensitive question they did not want to answer. +- Confusion about what is being asked. +- Loading delay or technical issue. +- The form's value did not justify the continued effort. + +**Final-submission drop-off.** User completed all fields but did not submit. + +Common causes. +- Submission anxiety; the user is not sure what happens next. +- Validation errors at submission lost them. +- The submission CTA is not clear. +- Final field requires information they did not have ready. + +--- + +## Remediation: first-field drop-off + +When users abandon at the first field. + +**Diagnostic questions.** + +- Is the form's value proposition clear at the start? +- Is the form length visible (creating bounce-on-length behavior)? +- Does the form work on mobile? +- Are trust signals present (privacy policy, security badges where appropriate)? + +**Remediation patterns.** + +- **Clarify the value.** "Get a personalized PDF in 5 minutes" beats "Fill out this form." +- **Hide the length.** Multi-step forms hide subsequent steps; the user does not see "this will take 20 minutes" upfront. +- **Add social proof.** "Trusted by 5000 teams" or "Used by [recognizable customer]" reduces hesitation. +- **Add trust signals.** Privacy assurance, security indicators, or testimonial near the form. +- **Reduce form to single page.** Sometimes the right answer is to revert from multi-step to single-page. + +**The diagnostic test.** A/B test variations. The treatment that improves first-field completion validates the diagnosis. + +--- + +## Remediation: mid-form drop-off + +When users abandon partway through. + +**Diagnostic.** + +- Which specific step has the highest drop-off? +- Are there sensitive questions on that step? +- How long does that step take to complete? +- Is the step's relevance clear? + +**Remediation patterns.** + +- **Reduce field count on the high-drop-off step.** Audit each field; remove non-essential fields. +- **Reword sensitive questions.** "How much do you spend on this today" beats "What is your annual budget?" Soft framing reduces abandonment. +- **Add progress indicator if missing.** Users abandon less when they know how much remains. +- **Add encouragement at the high-drop-off step.** "You are halfway there; just a few more questions to get your personalized result." +- **Restructure the step architecture.** If step 3 is a drop-off black hole, the architecture may be wrong; reconsider whether step 3's content belongs there at all. + +**The diagnostic test.** Watch real users complete the form (usability testing). The behavior often reveals the cause. + +--- + +## Remediation: final-submission drop-off + +When users complete fields but do not submit. + +**Diagnostic.** + +- Is the submission CTA clear? +- Does the user know what happens after submission? +- Are there validation errors at submission? +- Is the final field demanding information they did not have ready? + +**Remediation patterns.** + +- **Clarify the submission CTA.** "Get my personalized PDF" beats "Submit." The CTA should describe what the user gets. +- **Add post-submission preview.** "When you submit, we will email you within 5 minutes with..." sets expectations. +- **Move final-field demands earlier.** If the final field requires hard-to-find information, move it earlier so users gather it during the form. +- **Add a confirmation step.** A review-and-submit step where the user verifies their inputs reduces submission anxiety. +- **Validation pre-submission.** Surface errors before the user clicks Submit; do not let submission fail with surprise errors. + +--- + +## Tracking conditional-logic paths + +Multi-step forms with conditional logic have multiple paths through the form. + +**Per-path tracking.** + +- Tag each user's path through the form. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +**Path-specific remediation.** + +- A path that drops off at step 4 may need step-4 redesign for users on that path. +- A path that drops off rarely may not need attention. + +**The instrumentation challenge.** Conditional-logic paths multiply quickly. Track at the granularity that informs decisions, not at the granularity that overwhelms. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +**Segment-level tracking.** + +- Tag users by source, device, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +**Common segment patterns.** + +- Mobile users drop off more at long steps; desktop users push through. +- Paid-traffic users drop off earlier than organic; the audience-fit may be weaker. +- New visitors drop off more than returning visitors; trust matters. + +**Remediation by segment.** Sometimes the right answer is segment-specific. Mobile users may benefit from a shorter form variant; paid traffic may benefit from stronger trust signals. + +--- + +## Drop-off and time-of-completion + +Some drop-off correlates with how long the form takes. + +**Time-to-complete tracking.** + +- Average time per step. +- Total time across the form. +- Time-to-completion distribution. + +**Patterns.** + +- Forms taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Distribution skew (some users fast, some users slow) often signals usability issues that affect the slow users. + +**Remediation by time.** Forms taking too long should be shortened; steps taking too long should be split or simplified. + +--- + +## Drop-off audit cadence + +How often to audit drop-off data. + +**Weekly review.** For high-volume forms or recently launched forms. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable forms. Tracks trends and surfaces gradual decay. + +**Quarterly review.** For all active forms as part of the broader form audit. + +**Triggered review.** When form structure changes, when traffic source shifts, or when conversion drops. Ad-hoc reviews catch specific issues. + +The cadence depends on traffic volume and the form's importance. High-traffic forms warrant more frequent attention. + +--- + +## A/B testing for drop-off remediation + +Test remediation hypotheses rather than guessing. + +**The discipline.** Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall conversion. + +**Common test types.** + +- Form length: shorter vs longer. +- Step count: fewer vs more steps. +- Field count: fewer vs more fields per step. +- Validation strictness: stricter vs looser. +- Progress indicator: present vs absent. +- Trust signals: present vs absent. + +**Test discipline.** + +- One treatment variable per test. +- Long enough to capture statistical significance. +- Measure both the targeted metric and downstream metrics. + +The data informs which remediation actually moves the metric. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +**The signal.** The wrong audience self-selecting out is honest filtering. A multi-step form that drops 60 percent of visitors but produces 5x the qualified leads vs a single-page form is doing its job. + +**The discipline.** Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream metrics (lead quality, conversion to next step) reveal which is happening. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. Sometimes the right answer is to accept higher drop-off in exchange for higher qualification. + +--- + +## Common measurement failures + +**No instrumentation.** Form launched without per-step tracking; drop-off data unavailable. + +**Aggregate-only tracking.** Conversion rate tracked but not step-by-step; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; field renames or step changes broke the tracking. + +**Confounded data.** Multiple changes deployed simultaneously; cannot attribute conversion change to any one change. + +**Vanity metrics.** Tracking number of starts without tracking completion; the high-volume forms look successful even when conversion is poor. + +**Segment-blind tracking.** Aggregate data hides segment-specific issues. + +**Time-blind tracking.** No data on time-to-complete; cannot diagnose fatigue-driven drop-off. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points (first-field, mid-form, final-submission) with diagnoses and remediation patterns. Tracking conditional-logic paths. Drop-off and audience segmentation. Drop-off and time-of-completion. Audit cadence. A/B testing for drop-off remediation. When drop-off is signal not failure. Common measurement failures. + +## Implementation choices that stay internal + +Specific drop-off baselines for specific forms. Specific tooling for tracking and analysis. Specific A/B test designs and treatments. The team's audit calendars. These vary by team and form. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md new file mode 100644 index 0000000..999e4c7 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md @@ -0,0 +1,224 @@ +# Form anti-patterns + +The patterns that look like multi-step forms but degrade conversion. Anti-patterns are easy to ship; the cost shows up in completion rates, lead quality, and brand reputation over time. + +--- + +## The kitchen-sink-single-page + +The pattern. 30 fields on one page. Overwhelms before the user starts. + +The signal. First-field drop-off near 100 percent on anything beyond a contact form. Users scroll, see the length, and leave. + +The cost. The form's data collection is correct; the structure is wrong; nobody completes it. + +The cure. Multi-step the form; group fields into coherent steps. Detail in `references/multi-step-decision-criteria.md` and `references/step-architecture-patterns.md`. + +--- + +## The progress-theater form + +The pattern. The form is broken into steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone." + +The signal. Completion rate marginally better than kitchen-sink; users feel the form is gimmicky; some abandon mid-form because each step feels pointless. + +The cost. The build effort produced a form that is no better than the alternative. The audience perceives the format as decorative. + +The cure. Restructure into genuinely-staged steps. Detail in `references/step-architecture-patterns.md`. + +--- + +## The arbitrary-chunking form + +The pattern. Each step has 1-2 fields; the user wonders why this is multi-step. + +The signal. Quick completions but high abandonment; the format adds friction without value. + +The cost. The user perceives the form as gimmicky; trust degrades. + +The cure. Either consolidate to single-page (if the form has only 4-6 fields) or expand the staging to coherent units (if the form has more fields that group naturally). + +--- + +## The hidden-length form + +The pattern. No progress indicator; the user does not know how long the form is. + +The signal. Mid-form drop-off climbs as users lose patience; abandonment correlates with time spent. + +The cost. Users who would have completed if they knew the length abandon out of uncertainty. + +The cure. Add an honest progress indicator. Detail in `references/progress-indicator-patterns.md`. + +--- + +## The interrogation-form-with-steps + +The pattern. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The signal. Drop-off at every step; cumulative completion rate is poor; the form earns "interrogation" reputation. + +The cost. The audience that completes is over-disclosed and may resent the friction; the audience that does not complete walks away with a negative impression. + +The cure. Audit the field set. Remove fields that are not necessary for the form's purpose. The right field count is often half what teams initially design. + +--- + +## The validation-strict form + +The pattern. Validation rejects valid inputs because the rules are over-specified. Email validation rejects plus-sign aliases; phone validation rejects international formats; name validation rejects non-Latin characters. + +The signal. Users with valid but unusual inputs abandon when validation fails. Reports of "the form would not let me submit." + +The cost. The form filters out valid users. The team perceives the form as working because submissions look clean; the team does not see the audience that could not get past validation. + +The cure. Audit validation rules against actual business requirements. Detail in `references/validation-strategy-patterns.md`. + +--- + +## The mobile-broken form + +The pattern. Form works on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; touch targets too small. + +The signal. Mobile completion drops to half of desktop or worse. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. + +--- + +## The trust-broken form + +The pattern. Save-and-resume offered without clear trust communication. Users do not save because they distrust persistence. + +The signal. Save-rate is low; users abandon mid-form rather than save. + +The cost. The save mechanism's investment produces no value; the audience that would have saved instead leaves permanently. + +The cure. Trust communication. What is saved, what is not, how long it persists, who can access it. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## The variable-step form + +The pattern. Conditional logic that changes the step count visibly. "Step 4 of 5" becomes "Step 4 of 7" mid-form. + +The signal. Users feel misled; abandonment climbs at the moment the indicator shifts. + +The cost. Trust damage. The user trusted the indicator; the indicator lied. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). Detail in `references/progress-indicator-patterns.md`. + +--- + +## The submission-anxiety form + +The pattern. The submit button is unclear, or the user does not know what happens after submission, or the final step demands information they did not have ready. + +The signal. Final-submission drop-off is high; users completed all fields but did not submit. + +The cost. The form gets near-completion and loses the conversion at the last step. + +The cure. Clear submission CTA, explicit post-submission preview, optional confirmation step. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## The popup-interrupted form + +The pattern. The user is mid-form; a popup appears (newsletter signup, chat invitation, special offer). The user's flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about the interruption. + +The cost. The form's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Suppress popups during form completion. Save promotional content for after submission or for the next visit. + +--- + +## The reset-on-error form + +The pattern. The user submits; validation fails; the form resets, losing the user's inputs. + +The signal. Users who hit the error do not retry; they leave. + +The cost. The form treats errors punitively. Trust collapses. + +The cure. Preserve inputs on error. Show the error inline; let the user fix and resubmit without re-entering everything. + +--- + +## The slow-validation form + +The pattern. Real-time validation that lags. The user types; validation runs; the form feels sluggish. + +The signal. Users feel the form is slow; abandonment climbs at long-validation steps. + +The cost. The form's perceived performance damages the brand. + +The cure. Move validation to on-blur (when the user leaves the field) instead of on every keystroke. Reserve real-time validation for instant checks (format, character count). + +--- + +## The incompatible-with-autofill form + +The pattern. Form does not support browser autofill. The user has to type every field manually. + +The signal. Mobile completion is worse than desktop; users with password managers abandon. + +The cost. The form treats users as if autofill does not exist. Friction without justification. + +The cure. Support standard autofill attributes. Use semantic HTML input types. Test with browser autofill enabled. + +--- + +## The save-but-lose-on-resume form + +The pattern. Save-and-resume offered; user saves; resume returns the user to the start of the form, losing their progress. + +The signal. Resume rate is high (users click the recovery link) but completion rate from resume is low (users abandon when they see they have to redo work). + +The cost. The save mechanism's apparent value disappears at resume; trust collapses worse than if save had not been offered. + +The cure. Test the resume experience. Verify that resuming returns the user to their actual progress with inputs preserved. Detail in `references/save-and-resume-mechanics.md` (resume experience section). + +--- + +## The over-conditional form + +The pattern. 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively the form is fragile and hard to maintain. + +The signal. Bug reports about specific paths failing; testing surfaces broken rules; conditional logic decays unnoticed. + +The cost. Maintenance burden compounds. Form behavior becomes hard to reason about. + +The cure. Audit conditional logic. Remove rules that do not justify their maintenance overhead. Detail in `references/conditional-logic-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active form, looking specifically for these anti-patterns. + +**Audit questions per form.** + +- Does the form have natural step groupings (anti-pattern check: progress-theater, arbitrary-chunking)? +- Is the progress indicator honest and stable (anti-pattern check: hidden-length, variable-step)? +- Does each field affect the form's outcome (anti-pattern check: interrogation-form)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Does the form work on mobile (anti-pattern check: mobile-broken)? +- Is save-and-resume tested end-to-end (anti-pattern check: save-but-lose-on-resume, trust-broken)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is conditional logic maintained (anti-pattern check: over-conditional)? + +**The retire decision.** Anti-pattern forms often warrant retirement or redesign. Maintaining broken forms costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md b/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md new file mode 100644 index 0000000..92ced61 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md @@ -0,0 +1,159 @@ +# Multi-step decision criteria + +When to break a form into steps vs keep it on a single page. The conditions that warrant the multi-step structure, and the funnels where multi-step adds friction without lift. + +A multi-step form is a meaningful build. Step architecture, progress indicators, conditional logic, validation, save-and-resume, drop-off instrumentation. The multi-step form earns this investment only when specific conditions are present. + +--- + +## When multi-step earns the build + +Five conditions that, when present, make multi-step the right structure. + +**The form has more than 8-10 fields.** Single-page forms beyond this point overwhelm the audience visually. The user scrolls, sees the length, and leaves. Multi-step breaks the visual length into manageable pieces. + +**The fields naturally group into logical categories.** Personal info, then situation, then preferences, then specifics. Steps that reflect real groupings respect cognitive load. Arbitrary chunking does not. + +**The audience benefits from progressive commitment.** Each step builds investment. The user is more likely to complete after engaging with step 2 than they would have been if they had seen step 5's complexity upfront. + +**Different paths through the form make sense based on early answers.** Conditional logic that adapts the form to the user is hard to do on a single page; multi-step makes the adaptation feel natural. + +**The success metric warrants the build.** Higher completion rate, lower drop-off, better lead quality, faster review for the receiving team. Without a defined success metric, the build is hard to justify. + +When all five are present, multi-step is a strong structure. When two or fewer are present, single-page often serves better. + +--- + +## When multi-step does NOT earn the build + +Funnels where multi-step is the wrong structure. + +**The form has 4-6 fields.** A single-page form is faster to complete and faster to maintain. Multi-step adds friction (step transitions, progress indicators, save-and-resume mechanics) without adding clarity. + +**The fields do not group naturally.** Arbitrary chunking is friction. "Step 1: name. Step 2: email. Step 3: phone." The user wonders why this is multi-step and the question itself signals friction. + +**The audience expects speed.** Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. The multi-step format implies "this will take a while," which depresses high-intent users. + +**The team cannot maintain the multi-step complexity.** Multi-step forms have more failure modes (conditional logic bugs, progress indicator drift, validation issues across steps). The maintenance overhead is real; teams that cannot commit to it should choose single-page. + +**The form is a follow-up to a hot conversation.** A demo-request form right after a sales call should be quick. Multi-step here adds friction the audience is not ready for. + +The honest assessment matters more than the default. "Should the form be multi-step" is not the question. "Is multi-step the right structure for this specific data collection and audience" is. + +--- + +## The opportunity-cost frame + +A multi-step form is meaningful work. Account for the cost honestly. + +**The build cost.** Step architecture, progress indicators, conditional logic, save-and-resume, validation across steps, drop-off instrumentation. A meaningful multi-step form often takes 30-80 engineering hours plus design. + +**The maintenance cost.** Steps decay as the brand evolves; conditional logic bugs surface; progress indicators need updating. Quarterly review and maintenance run 2-6 hours per active form. + +**The opportunity cost.** What else could the team have built? A simpler form that converts adequately, a different growth-tooling investment, a content piece. The multi-step form's success has to clear the bar of those alternatives. + +The decision frame. The multi-step form earns investment when it produces more conversion than the single-page alternative, accounting for the full cost of build plus maintenance. + +--- + +## The grouping precondition + +Without natural field groupings, multi-step is arbitrary. + +**The check.** Can the fields be grouped into 3-5 coherent categories? Each category representing a unit of cognitive work the user can describe in one sentence? + +If yes, multi-step has natural step boundaries. + +If no (the fields do not group; the only structure is "first half" and "second half"), multi-step will feel arbitrary. Either restructure the data collection (some fields may not be needed) or choose single-page. + +**Examples of natural groupings.** + +- Identity (name, email, role) + Context (company size, industry, current setup) + Need (goal, challenge, timeline) + Confirmation. +- Personal info + Loan details + Property details + Financial verification + Submission (mortgage application). +- Account info + Use case + Plan selection + Payment + Confirmation (signup wizard). + +**Examples of forced groupings.** + +- Page 1 (name, email, phone) + Page 2 (company, role, source, industry, size). The page break is arbitrary; nothing groups these fields meaningfully. +- Page 1 (most fields) + Page 2 (one final field). The split is purely decorative. + +The discipline. If the team cannot articulate the unit of work each step represents, the steps are arbitrary; either rework the steps or use single-page. + +--- + +## The decision worked example + +A B2B SaaS company considering whether to make a "Talk to sales" form multi-step. + +**Conditions check.** + +- Field count: 12 fields (name, work email, company name, company size, industry, role, current solution, primary use case, timeline, budget range, source attribution, additional context). Above the 8-10 threshold; multi-step is on the table. +- Natural groupings: yes. Identity (name, email, role), company context (name, size, industry), current state (current solution, use case), buying intent (timeline, budget), additional (source, context). 5 natural groups. +- Progressive commitment: yes. The audience giving budget at the end after engaging with the early steps is more likely to give it than if asked upfront. +- Conditional logic value: yes. If the audience selects "evaluating" timeline, additional fields appear; if "active project," different additional fields appear. +- Success metric: defined. Conversion rate to submission, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo within 21 days. + +**Decision.** Build multi-step. The conditions warrant it. + +**Step architecture.** 5 steps: Identity, Company, Current State, Buying Intent, Submission Confirmation. + +**Maintenance commitment.** Quarterly audit of conversion, drop-off per step, and conditional logic. + +The decision was not "should we make this multi-step" but "given these conditions, this is the multi-step structure to build." + +--- + +## The single-page worked example + +The same B2B SaaS company considering whether to make a "Subscribe to newsletter" form multi-step. + +**Conditions check.** + +- Field count: 2 fields (email, name). Below the 8-10 threshold. +- Natural groupings: no. Two fields do not group. +- Progressive commitment: no. The audience subscribing benefits from speed. +- Conditional logic value: no. No branching needed. +- Success metric: simple conversion rate. + +**Decision.** Single-page. Multi-step would add friction without value. + +The decision was "what is the right structure" and the answer was single-page even though multi-step was nominally available. + +--- + +## The hybrid pattern + +Some forms work best with a "main" single-page form plus one optional follow-up step. + +**The pattern.** A short single-page form (3-5 fields) gets the user committed; an optional follow-up appears after submission for users who want personalization. + +**When this works.** When the primary action is fast (signup, lead-capture) but a richer follow-up benefits some users. + +**When this does not work.** When the follow-up has to be required for the primary action to be useful. + +The hybrid avoids both kitchen-sink-single-page and forced multi-step. It serves the speed-seeking audience and the depth-seeking audience separately. + +--- + +## When to retire a multi-step form (or convert to single-page) + +Multi-step forms can become wrong as the form evolves. + +**Retire-or-convert when:** + +- Field count has dropped below 6 over time as fields were removed. +- Conditional logic has been simplified out, leaving the steps with no real differentiation. +- Drop-off concentrates uniformly across steps, suggesting the staging is not working. +- A simpler single-page form might convert better. + +**The conversion-to-single-page move.** Sometimes the right answer is to revert. The multi-step format earned the build at one point; conditions changed; single-page is now better. Honest reversion is part of the discipline. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant multi-step. The opportunity-cost frame. The grouping precondition. The decision worked example. The single-page worked example. The hybrid pattern. The retire-or-convert decision. + +## Implementation choices that stay internal + +Specific multi-step decisions for specific forms. The team's capacity benchmarks for build and maintenance. Specific tooling for form engineering. Specific success-metric definitions and baselines. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md new file mode 100644 index 0000000..2051213 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md @@ -0,0 +1,289 @@ +# Progress indicator patterns + +Step counter, progress bar, step list. When each works. Indicator failures. + +The progress indicator reinforces momentum and reduces uncertainty about how much is left. Bad indicators flatter or mislead; good indicators reflect honest progress. + +--- + +## The honesty principle + +The progress indicator must reflect actual remaining work. Indicators that flatter the user or hide remaining complexity break trust. + +**The honest indicator.** "Step 3 of 5" when there are exactly 5 steps and the user is on step 3. + +**The dishonest indicator.** + +- "Almost done" when 5 fields remain on the next step. +- Progress bar that fills to 80 percent when 50 percent of fields remain. +- Step counter that shifts from "5 of 7" to "5 of 9" because conditional logic added steps. + +The honesty discipline. Match the indicator to the actual work; do not flatter; communicate variability when it exists. + +--- + +## Pattern A: Step counter + +"Step 2 of 4." Simple, common, effective for short forms. + +**How it works.** + +- The current step number is shown. +- The total step count is shown. +- The format is consistent across the form. + +**Strengths.** + +- Easy to implement. +- Easy to understand. +- Compact. + +**Weaknesses.** + +- Does not reflect within-step progress. +- Misleading when step lengths vary significantly. +- Breaks if conditional logic changes the total step count. + +**When to use.** Forms with 3-6 steps where step lengths are roughly similar. + +--- + +## Pattern B: Progress bar + +Visual fill showing percentage complete. + +**How it works.** + +- A bar fills from left to right (or follows other visual progression). +- The fill represents percentage of fields completed (or percentage of weight in some weighted scheme). +- Optionally includes a percentage label. + +**Strengths.** + +- Reflects continuous progress. +- Handles variable-length steps better than step counter. +- Visually engaging. + +**Weaknesses.** + +- More complex to design and implement. +- Risk of dishonest fill (bar fills fast, last 10 percent represents most of the remaining work). + +**When to use.** Forms with variable step lengths or where the user benefits from continuous-progress signal. + +--- + +## Pattern C: Step list + +Named steps shown with the current one highlighted. + +**How it works.** + +- All step names visible (often in a sidebar or header). +- Current step highlighted. +- Completed steps marked (checkmark or different color). +- Future steps indicated. + +**Strengths.** + +- Shows the user the full form path. +- Reduces uncertainty about what is coming. +- Lets the user navigate back to specific steps. + +**Weaknesses.** + +- Takes more screen real estate. +- Can overwhelm if there are many steps. +- Forces the form to commit to step names upfront. + +**When to use.** Forms with 3-7 well-named steps where the user benefits from seeing the structure. + +--- + +## Pattern D: No indicator + +Sometimes appropriate for very short forms. + +**When to use.** + +- Forms with 2-3 steps where the indicator overhead exceeds its value. +- Forms where the user's expectation is "this is short" and the indicator would imply length. + +**Risks.** + +- Without indication, longer forms can feel endless. +- Users may abandon because they cannot predict the form's length. + +**The discipline.** No indicator is rarely the right answer for forms with more than 3 steps. + +--- + +## Pattern E: Hybrid + +Combining patterns. A step counter plus a progress bar; or a step list plus a percentage. + +**Strengths.** + +- Multiple signals reinforce each other. +- Different users benefit from different indicators. + +**Weaknesses.** + +- Visual complexity grows. +- Risk of redundant or conflicting signals. + +**When to use.** Long forms (5+ steps) where rich indication helps the user understand the form's shape. + +--- + +## Indicator failures + +Patterns that break trust. + +**Failure 1: Indicator that shifts mid-form.** + +The form starts as "Step 4 of 5"; conditional logic adds steps; the form is now "Step 4 of 7." The user feels misled. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). + +**Failure 2: Indicator that hides remaining work.** + +"Almost done" when 5 fields remain on the next step. The user trusted the indicator and now feels betrayed. + +The cure. Calibrate the indicator to reflect remaining fields, not just remaining steps. + +**Failure 3: Indicator that fills fast and slows down.** + +Progress bar fills to 70 percent in the first 2 steps; the remaining 30 percent takes the next 5 steps. The user expects the form to end soon and is frustrated when it does not. + +The cure. Weight the progress bar by actual work, not just step count. If step 5 represents most of the remaining work, the bar should reflect that. + +**Failure 4: Indicator with no current-step context.** + +The progress bar shows 50 percent but the user does not know what the current step is about. Reduces orientation. + +The cure. Include both progress (where you are) and current-step name (what you are doing). + +**Failure 5: Indicator that is decorative without being honest.** + +Progress that looks fast but the next step is the longest one. The indicator misleads about pacing. + +The cure. Honest pacing. The indicator should reflect actual time-to-complete, not just step count. + +--- + +## Indicator placement + +Where the indicator lives on the page. + +**Top placement.** Above the form fields. Common; user sees it on every step. + +**Sidebar placement.** Alongside the form. Good for step-list patterns; takes more space. + +**Bottom placement.** Below the form fields. Less common; user has to scroll to see it on long steps. + +**Sticky placement.** Indicator stays visible as the user scrolls within a step. Useful for long steps. + +The choice depends on form length per step and visual hierarchy. Top placement is the safe default. + +--- + +## Indicator and mobile + +The indicator must work on mobile. + +**Mobile-specific considerations.** + +- Step counter: easy to mobile (small footprint). +- Progress bar: easy (full-width fits). +- Step list: harder; may need to collapse to step counter on mobile. +- Hybrid: simplify on mobile; do not stack multiple indicators. + +**The mobile discipline.** Ensure the indicator is visible without scrolling. Mobile users should see "Step 2 of 5" or the progress bar without searching for it. + +--- + +## Indicator messaging + +Optional language alongside the indicator. + +**Encouragement messages.** "Halfway there!" or "Almost done!" Can boost motivation; can also feel patronizing. + +**Time estimates.** "About 2 minutes left." Useful when honest; misleading when wrong. + +**Step-name labels.** "Step 2: Your Company." Useful when steps have meaningful names. + +**The discipline.** Encouragement and estimates should be honest. Patronizing or wrong messaging breaks trust faster than no messaging. + +--- + +## Indicator updating + +When the indicator updates. + +**On step transition.** The indicator updates as the user moves to the next step. Common pattern. + +**On field completion.** The indicator updates as fields within a step are filled. More granular; less common. + +**Smooth animation.** Subtle animation on transition reinforces progress. + +**No animation.** Instant update is fine; flashy animation can be distracting. + +--- + +## When indicators add no value + +Some forms work without indicators. + +**Very short forms.** 2-step forms often do not need indication. The user knows it is short. + +**High-frequency forms.** Forms the user fills repeatedly may not need indication after the first time. + +**Single-action forms.** A subscription form with email and submit does not need a progress indicator. + +The discipline. Default to including an indicator for multi-step forms. Skip only when the form is genuinely simple enough that the indicator adds noise. + +--- + +## Indicator audit + +Periodically audit the indicator. + +**The audit.** + +- Read the indicator on each step. Does it reflect honest progress? +- Test the form with conditional logic. Does the indicator handle the variability? +- Check mobile rendering. Does the indicator work on touch devices? +- Check accuracy. Does "almost done" actually mean almost done? + +**The drift.** Indicators decay as forms evolve. Steps get added; conditional logic gets added; the indicator falls out of sync. + +**The cure.** Quarterly audit alongside form audit. Update the indicator when the form structure changes. + +--- + +## Common indicator failures + +**No indicator on a long form.** User does not know how much remains; abandons. + +**Indicator shifts mid-form.** Conditional logic surprised the user. + +**Dishonest pacing.** Bar fills fast, work remains slow. + +**Indicator without current-step context.** Progress without orientation. + +**Indicator overflowing on mobile.** Step list designed for desktop; cramped on mobile. + +**Patronizing language.** "Almost done" repeatedly when the user is at step 2 of 6. + +**Wrong time estimates.** "About 1 minute left" when 5 minutes remain. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. Indicator failures (5 patterns). Indicator placement, mobile considerations, messaging, updating. When indicators add no value. Indicator audit. Common failures. + +## Implementation choices that stay internal + +Specific indicator designs for specific forms. Specific tooling for indicator implementation. Specific brand-voice messaging alongside indicators. The team's mobile testing benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md b/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md new file mode 100644 index 0000000..dc1b7a3 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md @@ -0,0 +1,267 @@ +# Save-and-resume mechanics + +When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. + +Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. Done well, it earns the user's trust and recovers what would otherwise be lost completions. + +--- + +## When save-and-resume helps + +Three conditions that, when present, make save-and-resume valuable. + +**Form length warrants it.** Forms taking more than 5 minutes to complete benefit. Below 5 minutes, the user can usually push through; above, the cost of starting over is high. + +**Information may not be at hand.** Forms requiring documents, technical configurations, or specific data the user may need to gather. Save-and-resume lets the user collect the information and return. + +**Multi-session use is expected.** Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms, complex onboarding). Save-and-resume is required, not optional. + +When all three are present, save-and-resume is a strong investment. When none are present, the mechanic adds complexity without lift. + +--- + +## When save-and-resume does not help + +**Quick lead-capture forms.** Under 60 seconds to complete. The save mechanic adds complexity; the audience does not need it. + +**Single-session forms.** Forms designed to be completed in one sitting. Save-and-resume can encourage abandonment ("I will come back later") that becomes permanent. + +**Forms that require trust.** Sensitive information may not be safe to persist; the user may not save because they distrust persistence. Adding save-and-resume without addressing trust degrades the form. + +**Forms with strict expiration.** Application deadlines or session timeouts may make save-and-resume confusing or counterproductive. + +--- + +## Pattern A: Email-link recovery + +The most common save-and-resume pattern. + +**How it works.** + +- The user clicks "Save and resume later." +- A form appears asking for an email address. +- The user enters email; a recovery link is sent. +- The user opens the email later, clicks the link, returns to the form with progress preserved. + +**Strengths.** + +- Familiar pattern; users understand it. +- Works across devices (user can save on desktop, resume on mobile). +- Simple to implement. + +**Weaknesses.** + +- Requires the user to give an email address before completing the form (which may itself be friction). +- Depends on email deliverability. +- Recovery link can expire or get lost. + +**When to use.** Default for most save-and-resume needs. The familiar UX reduces friction. + +--- + +## Pattern B: Account-based persistence + +Forms that require account creation persist by default. + +**How it works.** + +- The user creates an account at the start. +- Form progress saves automatically as the user completes fields. +- The user logs back in to resume. + +**Strengths.** + +- Persistence is automatic; user does not have to choose to save. +- Works across devices. +- Account integration may extend to other features beyond the form. + +**Weaknesses.** + +- Account creation is significant friction at the start. +- Adds engineering complexity. +- May not be appropriate for one-shot forms. + +**When to use.** Forms that are part of an account-based product or service where account creation is justified by ongoing use. + +--- + +## Pattern C: Anonymous-session save + +Browser-based save without identification. + +**How it works.** + +- Form progress saves to browser local storage as the user completes fields. +- The user returns to the same browser, picks up where they left off. + +**Strengths.** + +- Lowest friction; no email or account required. +- Automatic; user does not have to choose to save. + +**Weaknesses.** + +- Works only on the same browser/device. +- Lost if the user clears cookies or switches devices. +- Limited persistence (typically days, not weeks). + +**When to use.** Forms where the audience likely returns from the same device within a short window. Often used as a fallback or supplement to other patterns. + +--- + +## Pattern D: Hybrid + +Combining patterns. Anonymous-session save by default; email-link recovery as a backup. + +**How it works.** + +- Form auto-saves to browser as user completes. +- A "save and resume from any device" option offers email-link recovery. + +**Strengths.** + +- Lowest-friction default; user benefits even without explicit action. +- Cross-device option for users who want it. + +**Weaknesses.** + +- More complex to design and explain. +- Multiple save mechanisms can confuse the user. + +**When to use.** Forms with significant length where many users return same-device but some need cross-device. + +--- + +## Trust communication + +Users hesitate to save partial sensitive information. The form must communicate clearly. + +**What to communicate.** + +- **What is saved.** "Your answers so far will be saved." +- **What is not saved.** "We do not save passwords or payment information until submission." +- **How long it persists.** "Your progress will be available for 7 days." +- **Who can access it.** "Only you can access your saved progress through the link we email you." +- **How to delete.** "You can clear your saved progress by completing or abandoning the form." + +**Trust copy patterns.** + +- "We never share your saved information." +- "Your progress is encrypted at rest." +- "You control whether to come back." + +**Trust copy that fails.** + +- Generic privacy boilerplate. +- Long legal text the user will not read. +- Vague reassurances without specifics. + +The discipline. Trust copy should be specific, scannable, and honest. Generic privacy text does not earn trust. + +--- + +## When in the form to offer save-and-resume + +Timing matters. + +**Pattern: Always available.** A "Save and resume" link visible on every step. The user can save at any moment. + +**Pattern: Triggered by inactivity.** After 60-90 seconds of inactivity, prompt the user to save. Risk: the prompt feels intrusive. + +**Pattern: Offered at logical breakpoints.** Save prompts at the end of each step or at known long-pause points. Less intrusive than continuous availability. + +**Pattern: Offered before high-friction steps.** "The next step requires document uploads. You can save now and come back when you have your documents." + +The choice depends on form length and the audience's likely pause points. Always-available is the safe default for long forms. + +--- + +## Resume experience + +The user clicks the recovery link or logs in. What happens next. + +**The principle.** The resume experience should be uninterrupted. The user lands on the step they were on; their previous answers are preserved; they can continue without re-doing work. + +**The resume page.** + +- Welcome back message confirming the resume. +- Preserved progress visible (the user sees what they had done). +- Clear path to continue (button to proceed to current step). + +**Resume failures.** + +- The user lands at the start; previous answers lost. Trust collapses. +- The user lands at the right step but answers are wrong. Worse than starting over. +- The recovery link expires; the user is told their progress is gone. The save mechanism failed. + +The discipline. Test the resume experience as carefully as the form itself. A broken resume is worse than no save. + +--- + +## Save-and-resume measurement + +Track how many users save and resume. + +**The metrics.** + +- **Save rate.** What percentage of users who reach the save option choose to save? +- **Resume rate.** What percentage of users who saved actually resume? +- **Resume-to-completion rate.** What percentage of users who resumed complete the form? + +**Diagnostic uses.** + +- Low save rate: the option is not visible or trust is missing. +- Low resume rate: the recovery email failed or the user lost interest. +- Low resume-to-completion: the resume experience is broken or the form is too long. + +**The decision.** If save-and-resume is offered but rarely used, audit whether the offering is justified or whether the mechanic adds complexity without payoff. + +--- + +## Save-and-resume for sensitive information + +Some forms collect sensitive information. Save-and-resume requires extra care. + +**The principle.** Sensitive information may not be safe to persist. Audit what is saved and what is not. + +**Common patterns.** + +- **Save non-sensitive only.** Names, emails, situational information saved; passwords, SSNs, payment details not saved. +- **Encrypt at rest.** Saved data encrypted in storage; only retrievable through recovery flow. +- **Limit persistence window.** Sensitive forms may save only for 24-48 hours rather than 7+ days. + +**Compliance considerations.** + +- Some jurisdictions or regulations restrict what can be persisted. +- The form's save behavior should be reviewed against applicable compliance. +- Trust copy should disclose persistence honestly. + +The discipline. Sensitive forms warrant more conservative save behavior. The convenience of save-and-resume is not worth privacy or compliance risk. + +--- + +## Common save-and-resume failures + +**Save offered without trust communication.** Users do not save because they distrust persistence. + +**Recovery link expires too quickly.** User receives the link, intends to come back, finds the link expired by the time they do. + +**Resume to wrong step.** User clicks recovery link, lands at the start, has to redo everything. + +**Saved answers corrupted.** User resumes, answers are wrong or partial. + +**Save mechanic decays.** Storage backend changes; saved data becomes inaccessible. + +**Multiple save mechanisms confuse.** Anonymous-session and email-link both offered; user does not know which to use. + +**Save offered on a form that does not need it.** Quick form gets save mechanic; complexity without payoff. + +--- + +## Methodology-level choices that stay in the public skill + +When save-and-resume helps and does not. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Trust communication discipline. Timing of save offering. Resume experience. Measurement. Save-and-resume for sensitive information. Common failures. + +## Implementation choices that stay internal + +Specific save-and-resume implementations for specific forms. Specific persistence backends and expiration policies. Specific trust copy in brand voice. The team's compliance review processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..de0e936 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md @@ -0,0 +1,279 @@ +# Step architecture patterns + +What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. + +The architecture is the structure that makes steps coherent. Bad architecture produces progress-theater (decorative steps); good architecture produces genuinely-staged forms (each step is a coherent unit of work). + +--- + +## The coherence principle + +Each step should represent a coherent unit of work from the user's perspective. + +**The test.** Can the user describe what they just did at the end of the step in one sentence? + +- Coherent: "I told you the basics about my company." +- Atomized: "I typed my company name in a field." + +Coherent answers signal genuinely-staged. Atomized answers signal progress-theater. + +The discipline. Each step should bundle related fields into a single cognitive unit. The user processes the step as a whole, not as 5 isolated fields. + +--- + +## Common step patterns + +Patterns that recur across acquisition, onboarding, and intake forms. + +**Identity step.** Who the user is. + +- Fields: name, email, role. +- Friction level: low. +- Position: opens the form. +- The user provides minimal commitment; the form earns the right to ask for more. + +**Context step.** What the user's situation is. + +- Fields: company size, industry, current setup, current tools. +- Friction level: medium. +- Position: after Identity, before Need. +- The user shares context that lets the form (or the receiving team) understand them. + +**Need step.** What the user is trying to accomplish. + +- Fields: goal, challenge, timeline, urgency. +- Friction level: medium-to-high. +- Position: middle of the form. +- The user articulates intent. This step often includes the highest-value fields for the receiving team. + +**Detail step.** Specifics needed to act on the user's request. + +- Fields: budget, specific requirements, constraints, integrations. +- Friction level: high. +- Position: late in the form. +- The user shares specifics. By this point, commitment is built; the user is more willing to share. + +**Confirmation step.** Review and submit. + +- Fields: review summary, submission action, optional final fields (preferences, follow-up). +- Friction level: low. +- Position: last. +- The user reviews what they provided and submits. + +--- + +## Sequencing principles + +The order of steps matters as much as the steps themselves. + +**Principle 1: Low-friction first.** The opening step should be easy to complete. The user invests their first 30-60 seconds in something simple; commitment compounds. + +**Principle 2: Commitment compounds.** Each step builds on the previous. The user who completed step 2 is more invested than they were before step 1; later steps can ask for more. + +**Principle 3: High-friction at the end.** The most demanding fields (budget, specific requirements, sensitive info) belong later. By that point, the user has invested enough to push through. + +**Principle 4: Confirmation explicit.** A final review-and-submit step lets the user verify their inputs. Reduces submission anxiety. + +**Anti-pattern: high-friction first.** Asking for budget in step 1 depresses completion. The user has not yet committed; the high-friction question feels premature. + +**Anti-pattern: commitment-resetting.** A late step that requires the user to make decisions they thought they had already made. The user feels their earlier work was wasted. + +--- + +## Step coherence test + +For each step, ask: can this step be described in one sentence as a unit of work? + +**Coherent step examples.** + +- "Step 1: tell us who you are." (Identity) +- "Step 2: tell us about your company." (Context) +- "Step 3: tell us what you are trying to accomplish." (Need) +- "Step 4: tell us the specifics so we can help." (Detail) +- "Step 5: review and submit." (Confirmation) + +Each step has a coherent description. The user can predict what is coming and feel they accomplished something at the end of each step. + +**Incoherent step examples (progress-theater).** + +- "Step 1: name and email." +- "Step 2: phone and company." +- "Step 3: role and industry." + +Each step is two fields. The fields are unrelated. The grouping is arbitrary. The user wonders why this is multi-step. + +--- + +## Field count per step + +How many fields per step is too many or too few. + +**Too few.** 1-2 fields per step often signals over-staging. The user wonders why this needed its own step. + +**Right range.** 3-7 fields per step. Enough to represent a coherent unit of work; few enough to complete in 30-60 seconds. + +**Too many.** 10+ fields per step starts to recreate the kitchen-sink-single-page problem within a step. Audit for non-essential fields. + +**The variance.** Some steps may have more fields than others; that is fine if each step's fields cohere. The Detail step often has more fields than the Identity step because it captures more specific information. + +--- + +## Step length variability + +Steps do not have to be the same length. + +**The pattern.** Identity step: 3 fields. Context step: 5 fields. Need step: 4 fields. Detail step: 7 fields. Confirmation step: 1 action. + +The variability is fine because each step represents a coherent unit. The user does not expect equal length; they expect coherence. + +**The progress indicator implication.** A step counter ("Step 2 of 5") may not reflect time-to-complete accurately when steps vary. A progress bar based on percentage of fields complete reflects the variability better. + +--- + +## Conditional step inclusion + +Some forms include or exclude steps based on earlier answers. + +**The pattern.** "If user has a current CRM, include the 'CRM details' step. If not, skip it." + +**Strengths.** + +- Removes irrelevant fields entirely. +- Makes the form feel adaptive. + +**Risks.** + +- Progress indicators must accommodate the variability honestly. +- The user may notice the variability and feel confused. + +**The discipline.** Use conditional steps when the variability genuinely benefits the user; communicate the dynamic nature in the progress indicator if it shifts. + +--- + +## Step transitions + +How the user moves from one step to the next. + +**The forward transition.** A clear "Next" or "Continue" button. Validation runs before the transition. + +**The backward transition.** A "Back" or "Previous" button. The user can return to earlier steps without losing later inputs. + +**The skip transition.** Some forms allow skipping optional steps. Use sparingly; skipping creates inconsistent paths. + +**Transition friction.** Each transition should feel snappy. Loading delays at transitions break the flow. + +**Transition cues.** Brief visual confirmation that the step changed (slide animation, fade transition). Helps the user understand the navigation. + +--- + +## Step naming + +Each step should have a clear name visible to the user. + +**Strong step names.** + +- "Tell us about you." +- "About your company." +- "What you are looking for." +- "The details." +- "Review and submit." + +**Weak step names.** + +- "Step 1," "Step 2," "Step 3." (Numbers without names; user does not know what each represents.) +- "Personal Info," "Company Info," "Other Info." (Generic; does not signal what the step is about.) +- "Contact," "Business," "Submission." (Truncated; does not warm the user.) + +**The voice match.** Step names should match the brand voice. Casual brands use casual names; serious brands use serious names. + +--- + +## Step architecture for specific use cases + +How the architecture varies by form purpose. + +**Lead-capture form (5-8 fields).** + +- Identity (name, email) +- Context (company, role) +- Need (use case, urgency) + +3 steps; the form moves quickly. + +**Demo-request form (10-15 fields).** + +- Identity (name, work email, role) +- Company (name, size, industry) +- Current state (current solution, key pain points) +- Buying intent (timeline, budget range) +- Confirmation + +5 steps; meaningful staging. + +**Application form (20+ fields with documents).** + +- Identity +- Eligibility (qualifying questions) +- Personal details +- Financial details +- Document upload +- Review +- Submit + +7+ steps; long form benefits significantly from staging. + +**Onboarding wizard (configuration-driven).** + +- Welcome +- Account setup +- Use-case selection +- Preferences +- Connect-your-tools +- Confirmation + +6 steps; each step represents a coherent setup unit. + +--- + +## Step architecture audit + +Periodically audit the step architecture. + +**The audit.** + +- Read each step's name. Does it represent a coherent unit? +- Read each step's fields. Do they cohere? +- Check field count per step. Within the 3-7 range? +- Check conversion per step. Are some steps disproportionately drop-off-heavy? + +**The drift.** Steps decay as the form evolves. New fields get added to the wrong step; steps become incoherent; field counts drift. + +**The cure.** Quarterly audit. Re-group fields into the right steps; remove non-essential fields; restructure if the original architecture no longer fits. + +--- + +## Common architecture failures + +**Arbitrary chunking.** Steps that group fields by visual length rather than coherence. + +**Atomized steps.** Each step has 1-2 fields; the user wonders why it is multi-step. + +**Field-count overload.** Some steps have 15+ fields; recreates the kitchen-sink problem within a step. + +**High-friction-first.** Budget or sensitive question in step 1; user is not committed enough to push through. + +**Commitment-resetting steps.** Late steps that require the user to make decisions they thought were already made. + +**Generic step names.** "Step 1, Step 2" without descriptive names; user cannot predict the form. + +**No confirmation step.** Form ends at the data-collection step; user is not given the chance to review. + +--- + +## Methodology-level choices that stay in the public skill + +The coherence principle. Common step patterns. Sequencing principles. The step-coherence test. Field count per step. Step length variability. Conditional step inclusion. Step transitions. Step naming. Step architecture for specific use cases. Step-architecture audit. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific forms. Specific step naming in brand voice. Specific tooling for step transitions and validation. The team's audit calendars. These vary by team and form. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md new file mode 100644 index 0000000..2c53366 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md @@ -0,0 +1,288 @@ +# Validation strategy patterns + +Per-step vs end-only vs hybrid. Validation message discipline. + +The validation strategy determines when errors are caught and how they are communicated. Done well, validation catches errors helpfully and protects the form from invalid submissions. Done poorly, validation rejects valid inputs or surfaces errors at the worst time. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. Errors caught too early feel intrusive; errors caught too late waste the user's investment. + +**The win.** A user enters an invalid email; inline validation catches it immediately; the user fixes it and continues. + +**The fail (too early).** A user is mid-typing an email; "must contain @" appears before they have finished typing. + +**The fail (too late).** A user completes 5 steps; submission fails because of a step-1 error they did not see flagged. + +The strategy choice depends on the form's length, the audience, and the validation complexity. + +--- + +## Pattern A: Per-step validation + +Each step's fields are validated before allowing progression to the next step. + +**How it works.** + +- The user completes the current step. +- Validation runs on all fields in the step. +- If errors exist, they are shown; the Next button does not advance. +- The user fixes errors and proceeds. + +**Strengths.** + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +**Weaknesses.** + +- Can feel intrusive if validation is too strict on every step transition. +- May block the user from progressing when they want to revise the field later. + +**When to use.** Default for most multi-step forms. Each step's data is validated as a coherent unit. + +--- + +## Pattern B: End-only validation + +All validation runs at submission. + +**How it works.** + +- The user completes all steps. +- Validation runs only when the user clicks Submit. +- All errors surface at once. + +**Strengths.** + +- User completes uninterrupted. +- Validation logic is simpler (one validation pass). + +**Weaknesses.** + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. +- Errors that span multiple steps are confusing to surface. + +**When to use.** Rarely. Sometimes appropriate for very short forms where per-step validation overhead is not worth it. + +--- + +## Pattern C: Hybrid + +Required-field validation per step; full validation at end. + +**How it works.** + +- Per-step: critical errors (missing required fields, malformed email format) catch immediately. +- End: nuanced validation (cross-field consistency, business rules) catches at submission. + +**Strengths.** + +- Combines the responsiveness of per-step with the simplicity of end-only. +- The user gets immediate feedback on critical issues. +- Complex validation logic does not interrupt the flow. + +**Weaknesses.** + +- More complex to design (two validation tiers). +- Risk of inconsistent user experience if the tiers are not well-coordinated. + +**When to use.** When validation has both critical-immediate components (required fields, format checks) and nuanced-end components (cross-field rules, business logic). The default pattern for most multi-step forms with significant validation needs. + +--- + +## Pattern D: Real-time validation + +Validation runs as the user types or interacts with each field. + +**How it works.** + +- As the user types, validation runs on the field. +- Errors appear inline as soon as they are detectable. +- Some implementations validate on field blur (when the user leaves the field) rather than every keystroke. + +**Strengths.** + +- Earliest possible error detection. +- User sees the result of their input immediately. + +**Weaknesses.** + +- Can feel intrusive if validation appears before the user finishes typing. +- Real-time validation on complex rules can lag. +- Easy to surface errors prematurely. + +**When to use.** When the validation is simple enough to run instantly (format checks) and when the audience benefits from immediate feedback. Best practice: validate on blur rather than every keystroke. + +--- + +## Validation message discipline + +The error messages themselves matter. + +**Helpful messages.** + +- "Phone number must include area code" (specific guidance). +- "Try a value between 1 and 1000" (specific range). +- "Email must include @ and a domain" (specific format). +- "This field is required" (when blank). + +**Unhelpful messages.** + +- "Invalid input" (generic). +- "Error" (no information). +- "Out of range" (no range specified). +- "You must enter..." (scolding tone). + +**Tone discipline.** Messages should be helpful, not scolding. "Try a value between 1 and 1000" beats "You must enter a value between 1 and 1000." + +**Specificity.** "Phone number must be 10 digits" beats "Invalid phone number." Specific guidance lets the user fix the issue immediately. + +--- + +## Inline placement + +Where errors appear matters. + +**Inline placement.** Errors appear next to the field that triggered them. The user sees the error in context. + +**Banner placement.** Errors appear in a banner at the top of the step. Easy to miss; less helpful. + +**Mixed placement.** Some errors inline, some in a banner. Confusing. + +The discipline. Inline placement is the default. Banners can supplement (summarizing all errors on the step) but should not replace inline. + +--- + +## Validation timing + +When validation triggers. + +**On blur.** Validation runs when the user leaves the field. Default for most field types. + +**On change.** Validation runs as the user types. Useful for some real-time feedback (password strength, character count) but intrusive for most validation. + +**On submit.** Validation runs when the user clicks the Next or Submit button. Always required as the final check. + +The combination matters. Most fields work well with on-blur for individual validation plus on-submit for final check. + +--- + +## Cross-field validation + +Validation that depends on multiple fields. + +**Examples.** + +- "End date must be after start date." +- "Sum of allocations must equal 100 percent." +- "If selected 'enterprise,' company size must be above 200." + +**The challenge.** Cross-field validation does not fit per-field timing. The validation can only run when both fields have values. + +**Approaches.** + +- **End-only validation for cross-field rules.** The cross-field check runs at submission. +- **End-of-step validation.** The cross-field check runs when the step containing both fields is completed. +- **Reactive cross-field validation.** Each time either field changes, the cross-field check runs. + +The choice depends on the form's complexity and the user's likely workflow. + +--- + +## Validation strictness + +How aggressively to reject inputs. + +**Too strict.** Rejects valid inputs because the validation is over-specified. "Email format invalid" for an email with a plus-sign alias. + +**Too loose.** Accepts invalid inputs that fail at submission. The user finds out late. + +**The right strictness.** Match validation rules to actual business requirements. Do not reject inputs the system can handle; do not accept inputs the system will choke on. + +**Common over-strictness mistakes.** + +- Email validation that rejects plus-sign aliases. +- Phone validation that rejects international formats. +- Name validation that rejects non-Latin characters. +- Address validation that rejects valid international addresses. + +The discipline. Validation should reflect what the system actually requires, not what is stereotypical. + +--- + +## Validation and accessibility + +Validation must work for users with assistive technology. + +**Screen reader announcements.** Errors should be announced when they appear. ARIA live regions for inline errors; focus management for error summaries. + +**Keyboard navigation.** Users should be able to navigate to error messages with keyboard alone. + +**Visual cues alongside text.** Color-coding for errors should not be the only signal; text labels and icons help users who cannot perceive color. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Validation and mobile + +Mobile validation has specific considerations. + +**Touch-friendly error states.** Error indicators should be visible without pinch-zoom. + +**Inline placement on mobile.** Errors appearing below or above the field; do not push critical content off-screen. + +**Mobile keyboards.** Use input types (email, tel, number) so mobile keyboards adapt; this also helps validation. + +**Real-time validation latency.** On mobile, real-time validation can lag and feel sluggish; default to on-blur for performance. + +--- + +## Validation testing + +Test validation across edge cases. + +**Test cases to include.** + +- Empty required fields. +- Format-invalid inputs (malformed emails, invalid phone numbers). +- Format-valid but business-invalid inputs (email without account, valid date in the past for a future-only field). +- Boundary inputs (minimum, maximum, just-outside). +- Special characters and international inputs. + +**The discipline.** Validation should pass valid inputs and reject invalid ones consistently. Test with realistic edge cases the audience will encounter. + +--- + +## Common validation failures + +**Generic error messages.** "Invalid input" without guidance. + +**Over-strict validation.** Rejecting valid inputs that fall outside narrow expectations. + +**Late validation.** Errors caught only at submission for issues that should have surfaced earlier. + +**Banner-only error placement.** User cannot see which field has the issue. + +**Validation that rejects internationally.** US-only formatting rules applied to international audiences. + +**Inconsistent validation rules.** Same field validated differently in different contexts. + +**Validation without accessibility.** Errors invisible to screen readers; color-only cues. + +**Validation that interrupts typing.** Real-time validation surfacing errors before the user finishes typing. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Validation message discipline (helpful vs unhelpful). Inline placement. Validation timing. Cross-field validation. Validation strictness. Validation and accessibility (cross-reference). Validation and mobile. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific forms. Specific tooling for validation implementation. Specific brand-voice error messages. The team's accessibility review processes. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/SKILL.md b/dist/pi/.agents/skills/okr-design/SKILL.md new file mode 100644 index 0000000..83f3ea1 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/SKILL.md @@ -0,0 +1,310 @@ +--- +name: okr-design +description: "OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the difference between sandbagged OKRs (always 100%) and aspirational OKRs (always 30%) and stretch OKRs (genuine ambition with quarterly accountability). Triggers on OKR design, OKR setting, key result design, OKR scoring, mid-quarter recalibration, OKR cascading, outcomes vs outputs, quarterly planning, goal setting. Also triggers when a team's OKRs are always hit and producing no learning, when OKRs are demoralizing because they were set as fantasy, or when the team uses OKR vocabulary but the practice has decayed." +category: product +catalog_summary: "OKR design discipline. Outcome statements, key results, scoring, mid-quarter recalibration. Distinguishes sandbagged OKRs (always hit, useless) from aspirational fantasy (impossible, demoralizing) from stretch OKRs (genuine ambition with quarterly accountability)" +display_order: 12 +--- + +# OKR Design + +A senior product leader's playbook for OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the practical disciplines that distinguish OKRs from quarterly to-do lists or impossible-fantasy goal-setting. + +OKRs are accountability infrastructure. When designed well, they produce a quarterly rhythm of ambitious goal-setting, mid-quarter learning, end-of-quarter scoring, and adjustment for the next quarter. When designed badly, they become a tax on the team that produces no signal: sandbagged OKRs that always hit 100% (no ambition, no learning), aspirational fantasy OKRs that nobody can hit (demoralizing, ignored after week 2), or vague OKRs that the team scores generously regardless of outcome. + +This skill is OKR design as practical methodology. The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, key results that actually measure the outcome, scoring honestly even when uncomfortable, recalibrating mid-quarter when warranted, and using the OKR review cadence to drive learning rather than performance theater. + +The voice is the senior product leader who has run OKRs in healthy organizations and watched the practice decay in others. Concrete, opinionated about what actually works, willing to call out the failure modes that conference talks gloss over. + +When to use this skill: designing OKRs for the next quarter, auditing why current OKRs are not driving decisions, recalibrating an OKR practice that has decayed, or onboarding a team to OKRs that has never used them. + +--- + +## What this skill is for + +This skill spans OKR design and the operational rhythm around them. The PM-skill distinction: + +- **`okr-design` (this skill)** is outcomes (results to be achieved). +- `roadmap-planning` is outputs (features and initiatives sequenced). +- `feature-launch-playbook` is post-ship execution. +- `product-analytics-setup` is measurement infrastructure (the metrics that key results depend on). +- `experiment-design` is the discipline for testing whether specific initiatives produce outcomes. +- `discovery-research-synthesis` informs which outcomes to pursue. + +The audience: senior PMs, product directors, engineering leaders, executives setting org-wide OKRs, in-house teams operating in OKR-driven cultures. + +What is not in scope: the broader strategic planning that decides which outcomes matter (other strategy frameworks); the execution of specific initiatives toward OKRs (covered by roadmap-planning, pm-spec-writing, feature-launch-playbook); the analytics infrastructure (covered by product-analytics-setup, analytics-strategy). + +--- + +## Sandbagged vs aspirational-fantasy vs stretch + +The keystone framing. + +**Sandbagged.** OKRs designed to hit 100%. The key results target outcomes the team is already on track to deliver. End of quarter: 100% scores across the board. The team celebrates; nobody learns anything. Output: an OKR practice that produces no signal. The team has the same OKRs every quarter dressed in different vocabulary because nothing pushes them past where they would have gone anyway. + +**Aspirational-fantasy.** OKRs that nobody can hit. 1000% growth in 90 days. Demoralizing, performative, ignored after week 2. Teams that ship aspirational-fantasy OKRs typically discover by week 6 that no realistic effort path produces the targets; they disengage; the OKRs become decoration on the planning doc that nobody references. + +**Stretch.** Genuine ambition with quarterly accountability. Designed to hit 60-70% on average. Hits and misses both teach something. The 60% case ("we hit 60% of our key results") is informative about what the team can deliver in a quarter; the 100% case is rare and usually signals sandbagging in retrospect; the 30% case signals either fantasy or the team encountered something unexpected (which is also informative). + +The litmus test. Look at the team's last four quarters of OKRs. If the average score is 95%+, the OKRs are sandbagged. If the average is below 30%, they are fantasy. If the average is 50-75%, the design is in the stretch zone. Adjust upcoming OKRs to bring the practice into stretch territory. + +--- + +## Objective design + +Objectives are outcome statements. They name what the team is trying to achieve in the quarter. + +**Strong objective characteristics.** + +- Outcome-focused, not output-focused. "Improve activation for new sign-ups" is an outcome; "Ship the new onboarding flow" is an output. +- Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. +- Inspiring without being fantasy. The team should feel pulled toward the objective, not crushed by it. +- Few in number. Most teams should have 2-4 objectives per quarter; more than 5 dilutes focus. + +**Worked examples.** + +- "Improve activation for new sign-ups so that more reach the value-realization moment within the first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +**Weak objective characteristics.** + +- Output-disguised-as-outcome. "Ship the activation redesign" is an output; the objective should be the result the redesign is meant to produce. +- Too vague. "Improve user experience" is too broad to focus quarterly work. +- Too tactical. "Refactor the auth service" is a tactical decision, not a quarterly objective. +- Too many. 8 objectives produces no focus; the team works on too many things and excels at none. + +Detail in [`references/objective-design-patterns.md`](references/objective-design-patterns.md). + +--- + +## Key result design + +Key results measure progress toward the objective. They are the quantitative or testable indicators that show whether the objective is being achieved. + +**Strong key result characteristics.** + +- Measurable. There is a specific number or testable threshold. +- Outcome-aligned. Achieving the key result actually moves the objective forward. +- Within team influence. The team can affect the key result through their work. +- Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +**Worked example.** Objective: "Improve activation for new sign-ups." + +Strong key results: + +- "Increase the percentage of new sign-ups reaching the value-realization moment within their first week from 32% to 45%." +- "Reduce the median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on the onboarding flow (up from 64%)." + +Each key result is measurable, ties to activation, the team can influence it through onboarding redesign work, and is time-bounded to the quarter. + +**Weak key results.** + +- Vague: "Improve activation significantly." +- Output: "Ship 5 onboarding redesign initiatives." (counts work done, not outcomes produced.) +- Outside influence: "Increase total signups by 50%." (signups are mostly upstream of activation work.) +- Vanity: "Reach 1M users." (impressive number; not directly tied to activation outcome.) + +**The 3-5 key results rule.** Most objectives benefit from 3-5 key results. One key result is fragile (single measurement may not capture the outcome); 6+ key results dilute focus. + +Detail in [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md). + +--- + +## Cascading OKRs across the org + +When and how to cascade OKRs from leadership to teams. + +**The trade-off.** + +- Cascaded OKRs ensure team work aligns with company priorities. The product team's objective derives from the company's objective; the engineering team's objective derives from the product team's. +- Strict cascading produces top-down OKRs that miss bottom-up insight. The team closer to the work sometimes knows what to prioritize better than the layer above. +- Too-loose cascading produces team OKRs that do not connect to company priorities; teams optimize locally without contributing to org goals. + +**The middle path.** + +- Company-level OKRs set quarterly. Team-level OKRs set with reference to company OKRs but with team-level autonomy on how to contribute. +- Each team's OKRs explicitly identify which company OKRs they ladder up to. +- Some team OKRs may be team-specific (technical debt, infrastructure, experimentation infrastructure) without direct company-OKR ladders. Surface these explicitly so the team's full work is visible. + +**When to cascade strictly.** Early-stage companies aligning around a small number of company priorities. Times of strategic shift where the org needs to move in a coordinated direction. + +**When to cascade loosely.** Mature organizations with established team mandates. Cross-functional teams where strict cascading would over-constrain. + +**The honest disclosure.** Cascading is harder than conference talks suggest. Most orgs over-cascade in the first few cycles and learn to relax it; some never learn and produce OKRs that are increasingly performative as they propagate down. + +Detail in [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md). + +--- + +## Scoring discipline + +End-of-quarter scoring is where OKR practice succeeds or decays. + +**The 0.0-1.0 scale.** Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +**The 60-70% target.** Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. Higher average suggests sandbagging; lower suggests fantasy or unexpected disruption. + +**Scoring honesty.** + +- Score the actual outcome, not the effort. The team that worked hard but did not move the metric scores low; the team that got lucky and moved the metric without much effort scores high. The score reflects outcome. +- Do not round up. A key result at 0.55 is 0.55, not 0.6. Honest scoring produces honest signal. +- Acknowledge what changed mid-quarter. Some misses reflect priority shifts; surface those without using them as excuses. + +**What 100% means.** 100% scores warrant scrutiny. Either the OKR was sandbagged (under-set), the team had a great quarter (informative), or the team is rounding up. Investigate which. + +**What 30% means.** 30% scores warrant scrutiny. Either the OKR was fantasy (over-set), the team encountered unexpected disruption (informative), or the work was deprioritized mid-quarter (also informative). Investigate which. + +**The compensation question.** OKRs work best when not directly tied to compensation. When OKRs determine bonuses, sandbagging incentives become severe; teams set OKRs they know they can hit. Most healthy OKR cultures separate goal-setting from compensation. + +Detail in [`references/scoring-discipline.md`](references/scoring-discipline.md). + +--- + +## Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. + +**The default.** OKRs hold for the quarter. Teams adapt their tactics to the OKR; OKRs do not change to match what the team is doing. + +**When to recalibrate.** + +- Strategic shift. The company's strategy changed materially mid-quarter; OKRs that no longer reflect the strategy are no longer the right targets. +- Major external disruption. A market change, regulatory event, or significant outage warrants resetting the quarter's targets. +- Information that invalidates the OKR. The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +**When NOT to recalibrate.** + +- The team is not on track. OKRs that are missing should remain as set; the miss is the signal. +- The OKR is uncomfortable. Teams uncomfortable with stretch OKRs should not lower them mid-quarter to feel better. +- Easier OKRs would feel achievable. The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +**The recalibration discipline.** Recalibration should be rare (1-2 quarters out of 8). Frequent recalibration signals OKR design failure: either too aggressive or not strategically aligned. The recalibration itself should be transparent: surface what changed, why, and what the new targets are. + +Detail in [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md). + +--- + +## The OKR review cadence + +OKRs benefit from a structured review rhythm. + +**Weekly check-ins.** + +- Team reviews progress on each key result. 15-30 minutes. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Not for adjusting OKRs; for adjusting tactics to keep moving toward them. + +**Mid-quarter review.** + +- Roughly week 6 of the quarter. 60-90 minutes. +- Honest assessment of trajectory: which key results are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +**End-of-quarter review.** + +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +**Quarterly retrospective.** + +- Distinct from the scoring review. The retrospective examines the OKR practice itself: were the OKRs the right ones, did the cadence work, what should change. +- Often combined with the next-quarter OKR setting session. + +Detail in [`references/review-cadence-templates.md`](references/review-cadence-templates.md). + +--- + +## OKRs vs roadmap items vs metrics + +Three concepts often conflated. Each serves a different purpose. + +**OKRs.** Outcome targets for the quarter. "Improve activation for new sign-ups" is an OKR; "Increase first-week activation rate from 32% to 45%" is a key result. + +**Roadmap items.** Initiatives the team is building or doing. "Onboarding redesign" is a roadmap item. Roadmap items contribute to OKRs but are not the OKRs themselves. + +**Metrics.** Ongoing measurements the team tracks. "First-week activation rate" is a metric. Metrics inform key results (which are quarterly targets on metrics) and are tracked continuously regardless of whether the team has an OKR aimed at them. + +**The relationship.** + +- OKR: "Improve activation for new sign-ups." +- Key result: "First-week activation rate from 32% to 45%." +- Metric: "First-week activation rate" (tracked continuously). +- Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +**Common conflations.** + +- Treating roadmap items as OKRs. "Ship the onboarding redesign" as an OKR; the OKR should be the outcome the redesign is meant to produce. +- Treating every metric as needing an OKR. Some metrics matter for the team to track without setting quarterly targets on them. +- Treating OKRs as roadmap commitments. OKRs name outcomes; the team is committed to pursuing them but may shift tactics; treating OKRs as roadmap commitments locks in tactics that may need to change. + +Detail in [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-okr-failures.md`](references/common-okr-failures.md). + +- "Our OKRs are always 100% and produce no signal." Sandbagged. Set with stretch ambition; expect 60-70% scores. +- "Our OKRs are always 30% and demoralizing." Fantasy. Recalibrate to genuine stretch; investigate whether the targets are achievable in any realistic effort path. +- "Our key results measure work, not outcomes." Output-disguised-as-outcome. Rewrite key results to measure the result, not the work. +- "We have 12 OKRs and the team is working on 47 things." Too many OKRs; cap at 2-4 objectives, 3-5 KRs each. +- "Our OKRs are vague." Lack measurable targets; rewrite key results with specific numbers and thresholds. +- "Our cascading produces team OKRs that do not match team work." Strict cascading mismatched to team mandate; loosen cascading or change team mandate. +- "We never recalibrate even when the strategy shifts." Recalibration too tightly avoided; surface strategic-shift criteria and use them. +- "We recalibrate every quarter." Recalibration too easy; OKR design is failing; investigate. +- "Our weekly check-ins became status reports." Tactical-discussion missing; reform the check-in format. +- "Our scoring rounds up." Scoring discipline missing; commit to honest scoring. +- "OKRs and bonuses are tied; people sandbag." Predictable; decouple OKRs from compensation. + +--- + +## The framework: 12 considerations for OKR design + +When designing or auditing OKRs, walk these 12 considerations. + +1. **Stretch, not sandbagged or fantasy.** 60-70% average score target. +2. **Objectives are outcomes, not outputs.** What we are trying to achieve. +3. **Few objectives, well-focused.** 2-4 per team per quarter. +4. **Key results are measurable.** Specific numbers or testable thresholds. +5. **Key results are outcome-aligned.** Achieving them moves the objective forward. +6. **Key results are within team influence.** Not entirely dependent on external factors. +7. **3-5 key results per objective.** Single key results are fragile; many dilute focus. +8. **Cascading explicit but not over-constrained.** Team OKRs ladder up but with autonomy on how. +9. **Scoring honest, not rounded.** 0.0-1.0 reflects actual outcomes. +10. **Recalibration rare.** OKRs hold absent strategic shift or major disruption. +11. **Review cadence weekly + mid-quarter + end-of-quarter.** Tactical, then strategic, then scoring. +12. **OKRs separate from roadmap items and metrics.** Each serves a different purpose. + +The output of the framework is OKRs that produce quarterly accountability infrastructure: ambitious goal-setting, mid-quarter learning, end-of-quarter scoring honest enough to inform the next quarter. + +--- + +## Reference files + +- [`references/objective-design-patterns.md`](references/objective-design-patterns.md) - Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. +- [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md) - Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. +- [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md) - When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. +- [`references/scoring-discipline.md`](references/scoring-discipline.md) - The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. +- [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md) - When to recalibrate vs adapt tactics. Strategic shift vs uncomfortable OKRs. The recalibration discipline. +- [`references/review-cadence-templates.md`](references/review-cadence-templates.md) - Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. +- [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md) - The three concepts and their relationships. Common conflations. The complete picture across all three. +- [`references/okr-anti-patterns.md`](references/okr-anti-patterns.md) - 8+ anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling. +- [`references/common-okr-failures.md`](references/common-okr-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: OKRs are accountability infrastructure + +OKRs at their best produce quarterly accountability that informs the org's strategic learning. The team commits to outcomes; works toward them; scores honestly; learns from the gap between target and outcome; designs the next quarter's OKRs better. + +OKRs at their worst produce ritual that consumes time without producing signal. Sandbagged OKRs that always hit. Fantasy OKRs that nobody can. Vague OKRs that score generously regardless of outcome. The vocabulary persists; the practice has decayed. + +The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, measurable key results, stretch ambition, scoring honesty, recalibration only when warranted, and the review cadence that drives learning rather than performance theater. + +When in doubt about whether an OKR practice is working, ask: do the OKRs drive decisions about what to prioritize, do the scores produce learning that informs the next quarter, are key results actually measuring outcomes the team can influence, is the average score in the 60-70% range that stretch OKRs target? If yes to all of those, the practice is real. If no to any, the gap is where the OKR work is failing to produce the accountability infrastructure it is meant to provide. diff --git a/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md b/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md new file mode 100644 index 0000000..9ce7eb6 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md @@ -0,0 +1,187 @@ +# Cascading OKRs decisions + +When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. + +Cascading is one of the most contested OKR practices. Conference talks describe clean ladders from company to team to individual; in practice, strict cascading produces over-constrained team OKRs, while loose cascading produces team work disconnected from company priorities. The middle path is harder than the talks suggest. + +--- + +## The trade-off + +Cascading exists on a spectrum. + +**Strict cascading.** + +- Company sets OKRs. +- Each function (product, engineering, sales) cascades to function-level OKRs. +- Each team cascades to team OKRs. +- Each individual cascades to personal OKRs. +- All ladders trace cleanly upward. + +**Loose cascading.** + +- Company sets OKRs. +- Teams set their own OKRs informed by company priorities but with autonomy on scope and contribution. +- Teams may set OKRs not directly tied to company OKRs (technical debt, team-specific work). +- Individual OKRs often skipped. + +**The trade-off.** + +- Strict produces alignment but over-constrains. Teams set OKRs they think leadership wants rather than OKRs they can credibly commit to. +- Loose produces autonomy but risks misalignment. Team work optimizes locally without contributing to org goals. + +--- + +## When to cascade strictly + +**Early-stage companies aligning around small priorities.** When the company has 2-3 critical priorities and everyone needs to focus on them, strict cascading enforces the focus. + +**Times of strategic shift.** When the company is changing direction (new market, new segment, new product line), strict cascading helps the org turn together. + +**Crisis or focus periods.** When the company faces a specific challenge requiring all hands, strict cascading ensures everyone is rowing the same direction. + +**Common to these cases:** strategic clarity is high, alignment is more valuable than autonomy, and the org has fewer concurrent priorities to balance. + +--- + +## When to cascade loosely + +**Mature organizations with established mandates.** Teams have clear scope; their OKRs naturally fit company priorities through team mandate; strict cascading adds overhead without value. + +**Cross-functional teams where strict cascading would over-constrain.** Teams that span functions cannot cleanly ladder to a single function-level OKR; loose cascading lets them pursue cross-functional outcomes. + +**High-trust environments.** Teams trusted to set their own OKRs and credibly commit to them; the org accepts the autonomy in exchange for the engagement and creativity it produces. + +**Common to these cases:** team mandates are clear, autonomy is more valuable than tight alignment, and the org tolerates some local optimization in exchange for team engagement. + +--- + +## The middle path + +Most healthy OKR cultures sit between strict and loose. + +**The pattern.** + +- Company sets 3-5 OKRs at the start of the quarter. +- Teams set OKRs that explicitly identify which company OKRs they ladder up to (when applicable). +- Teams have autonomy on how to contribute (which key results, which initiatives, what scope). +- Some team OKRs are team-specific (technical debt, infrastructure, experimentation foundations) without direct company ladders. Surface these explicitly. +- Individual OKRs are usually skipped; commitment is at the team level. + +**The "explicit ladder when applicable" rule.** Each team OKR either: + +- Explicitly identifies the company OKR it ladders to. +- Explicitly identifies that it is team-specific without a company ladder. + +Both are honest; the failure mode is implicit ambiguity where the team is not sure whether their OKR connects to anything. + +--- + +## Worked example: middle path + +Company OKRs for Q3: + +1. Improve net new ARR through enterprise segment growth. +2. Improve activation for self-serve sign-ups. +3. Reduce infrastructure costs through architecture optimization. + +Product team OKRs: + +- "Improve activation for new sign-ups" (ladders to company OKR 2). +- "Establish enterprise-readiness foundations" (ladders to company OKR 1). +- "Reduce technical debt in the activation funnel" (team-specific; does not ladder directly). + +Engineering team OKRs: + +- "Ship onboarding redesign by week 6" (ladders to company OKR 2 via product team OKR). +- "Migrate to new search architecture" (ladders to company OKR 3). +- "Strengthen test coverage in critical paths" (team-specific). + +Sales team OKRs: + +- "Close 8 enterprise deals in Q3" (ladders to company OKR 1). +- "Improve discovery-call to demo conversion from 24% to 35%" (ladders to company OKR 1). +- "Build the design partner program" (team-specific). + +The pattern. Most team OKRs ladder up; some are team-specific. Each ladder is explicit. Teams have autonomy on how they contribute (which KRs, which initiatives). + +--- + +## Cascading anti-patterns + +**Strict cascading enforced top-down without team input.** Team OKRs become wishlist receivers from leadership; commitment is shallow because the team did not author what they are committing to. + +**Loose cascading without explicit ladders.** Team OKRs are set without any visible connection to company priorities. Some team work happens to align; some does not. Leadership cannot tell what is contributing to company OKRs. + +**Cascade theater.** OKR documents include ladders that look connected but do not actually drive anything. The team's work shows up the same regardless of which company OKR they "ladder to." + +**Over-cascading.** Every team OKR is required to ladder to a company OKR. Teams contort their work to fit. Team-specific work (technical debt, infrastructure) gets dressed up as ladder work or gets de-prioritized despite being important. + +**Personal OKRs as default.** Individual OKRs cascaded down. Most OKR cultures find this produces overhead without proportional value; commitment at team level is usually sufficient. + +--- + +## Cascading and team mandate + +Teams whose OKRs do not naturally ladder to company priorities often have a team-mandate problem. + +**The signal.** A team consistently sets OKRs that are team-specific. None of their work ladders to company priorities. + +**The interpretation.** + +- Possibly the team's mandate does not match the company's current priorities. Either the mandate should change (broader scope, different focus) or the team's work is not strategically critical (consider deprioritizing or restructuring). +- Possibly the team's work is foundational and supports many company priorities indirectly (platform teams, infrastructure teams). Their OKRs may legitimately be team-specific. + +**The audit.** Annually, review whether team mandates match company strategy. Teams whose mandates have drifted from strategy benefit from explicit redirection. + +--- + +## Cascading frequency + +The cascading work happens at OKR-setting time (start of quarter) and is generally locked for the quarter. + +**Quarterly cascading.** Most common. Company OKRs set; teams cascade; quarter executes. + +**Mid-quarter cascade revision.** Rare. Strategic shift mid-quarter may warrant rewriting team OKRs. See `mid-quarter-recalibration.md`. + +**The honest frequency.** Most orgs over-cascade in the first few quarters of OKR adoption (treating cascading as a thing to perfect) and learn to relax it. Some orgs never relax and produce increasingly performative cascading. Recognize the pattern; loosen when it stops adding value. + +--- + +## Cascading and individual goals + +Individual goals are usually a separate practice from OKRs. + +**Common patterns.** + +- Team OKRs commit at team level; individual contributors work toward team OKRs without separate personal OKRs. +- Individual goals (career development, skill-building, role expectations) live in performance management, separate from OKRs. +- Some orgs do cascade to individual OKRs; most find this produces overhead without value and stop after a few cycles. + +**The discipline.** Be intentional about whether to cascade to individuals. The default should be "no, commit at team level"; individual cascading should be justified rather than assumed. + +--- + +## Common cascading failures + +**Top-down enforced cascading.** Teams receive OKRs from leadership; commitment is shallow. + +**Implicit cascading.** Team OKRs do not explicitly identify their ladders; alignment is ambiguous. + +**Over-cascading.** Every team OKR forced to ladder to company; team-specific work dressed up artificially. + +**Cascade theater.** Ladders documented but not driving anything. + +**Personal-OKR overhead.** Individual cascading without proportional value. + +**Mandate-strategy drift.** Teams with mandates disconnected from current strategy producing OKRs that ladder to nothing. + +--- + +## Methodology-level choices that stay in the public skill + +The cascading trade-off. When to cascade strictly and loosely. The middle path with explicit ladders. Worked example. Cascading anti-patterns. Team mandate considerations. Cascading frequency. Individual goals separation. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that visualize ladders. Specific cascade-review meeting formats. Specific role-based templates. The team's own conventions for surfacing team-specific OKRs. These vary by org and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md b/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md new file mode 100644 index 0000000..675ddb3 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md @@ -0,0 +1,205 @@ +# Common OKR failures + +Eleven-plus failure patterns with diagnoses and cures. Cross-references the OKR anti-patterns reference; this file covers operational failures that arise during the OKR cycle. + +The cross-cutting pattern: most OKR failures share a single root, which is treating OKRs as ceremony rather than as accountability infrastructure. + +--- + +## Failure 1: Our OKRs are always 100% and produce no signal + +**Symptom.** End-of-quarter scoring shows the team hitting 95%+ on every KR. The OKR practice feels positive but does not produce learning. + +**Diagnosis.** Sandbagging. Targets set at or below the team's natural trajectory. The OKR practice has decayed into "what we know we can hit." + +**Cure.** Set targets above the historical trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The target should be meaningfully above that. + +**Prevention.** Track the average score over multiple quarters. Drift toward 0.85+ is a sandbagging signal; intervene before the practice fully decays. + +--- + +## Failure 2: Our OKRs are always 30% and demoralizing + +**Symptom.** End-of-quarter scoring shows the team consistently missing OKRs. Team disengages from OKRs by mid-quarter. + +**Diagnosis.** Aspirational fantasy. Targets have no realistic effort path. The OKR practice has decayed into "inspirational numbers nobody believes." + +**Cure.** Recalibrate to genuine stretch. Validate against the effort-path test: can the team identify specific initiatives that would produce the target? + +**Prevention.** During OKR setting, require effort-path reasoning. If the team cannot articulate what work would produce the target, the target is fantasy. + +--- + +## Failure 3: Our key results measure work, not outcomes + +**Symptom.** KRs read as roadmap items. "Ship X by Y." "Run Z interviews." + +**Diagnosis.** Output-disguised-as-outcome. The team is committing to work, not to results. + +**Cure.** Rewrite each output KR to measure the outcome the output is meant to produce. The output itself lives in the roadmap. + +**Prevention.** During KR drafting, apply the outcome test: is this measuring a result, or counting work? + +--- + +## Failure 4: We have 12 OKRs and the team is working on 47 things + +**Symptom.** Quarterly OKRs span many objectives and KRs; the team's work is scattered across many priorities. + +**Diagnosis.** OKR proliferation. Too many objectives produces no focus. + +**Cure.** Cap at 2-4 objectives, 3-5 KRs each. Surface deferred work explicitly so the team can see what they are choosing not to commit to. + +**Prevention.** Cap OKRs at the start of the cycle. Adding "just one more" OKR is a recurring pressure that should be resisted. + +--- + +## Failure 5: Our OKRs are vague + +**Symptom.** Objectives like "improve user experience" or KRs like "make activation better." Cannot be scored honestly. + +**Diagnosis.** Lack of measurable specificity. + +**Cure.** Rewrite KRs with specific numbers, baselines, and targets. "Increase first-week activation rate from 32% to 45%" instead of "improve activation." + +**Prevention.** During KR review, apply the specificity test: could two reasonable people disagree on whether this KR was hit at end of quarter? If yes, it is too vague. + +--- + +## Failure 6: Our cascading produces team OKRs that do not match team work + +**Symptom.** Team OKRs cascade to company OKRs but the team's actual capacity and mandate produce different work. + +**Diagnosis.** Strict cascading mismatched to team mandate. + +**Cure.** Loosen cascading; allow team-specific OKRs that do not directly ladder. Or change team mandate if it does not match strategy. + +**Prevention.** Use the middle path on cascading. Surface team-specific OKRs explicitly. + +--- + +## Failure 7: We never recalibrate even when the strategy shifts + +**Symptom.** The org's strategy changed mid-quarter. Team OKRs no longer reflect strategy. The team holds them anyway. + +**Diagnosis.** Recalibration too tightly avoided. + +**Cure.** Surface the strategic shift; recalibrate the affected OKRs explicitly. Document the trigger. + +**Prevention.** Make strategic-shift criteria for recalibration explicit. The team should know when recalibration is appropriate. + +--- + +## Failure 8: We recalibrate every quarter + +**Symptom.** OKRs get revised mid-quarter routinely. The team uses recalibration to soften uncomfortable OKRs. + +**Diagnosis.** Recalibration too easy. OKR design is failing or stretch ambition is being avoided. + +**Cure.** Hold OKRs absent the recalibration triggers (strategic shift, major disruption, invalidating information). Investigate why frequent recalibration is happening. + +**Prevention.** Track recalibration frequency. Drift toward "every quarter recalibrates" is a signal to intervene. + +--- + +## Failure 9: Our weekly check-ins became status reports + +**Symptom.** Weekly OKR check-ins lost their tactical decision focus; they became "here's what I did this week" updates. + +**Diagnosis.** Check-in format drift. The session is no longer producing tactical adjustments. + +**Cure.** Reform the format. Per KR: trajectory, blockers, planned work for the upcoming week. End with explicit commitments. + +**Prevention.** The team lead facilitates the check-in's tactical scope. Status reports happen elsewhere. + +--- + +## Failure 10: Our scoring rounds up + +**Symptom.** End-of-quarter scoring shows 0.85 average. Closer inspection shows scores were rounded up across most KRs. + +**Diagnosis.** Generous scoring. Honesty has decayed. + +**Cure.** Commit to honest scoring. A 0.55 KR scores 0.55, not 0.6. Document context; the context surfaces what produced the actual outcome regardless of the number. + +**Prevention.** Surface the rounding pattern explicitly. The team should know that rounding up is the failure mode. + +--- + +## Failure 11: OKRs and bonuses are tied; people sandbag + +**Symptom.** OKR scores directly determine bonuses. Targets set conservatively; scoring round up; stretch ambition gone. + +**Diagnosis.** Compensation coupling. + +**Cure.** Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs. + +**Prevention.** Establish from the start that OKRs are accountability infrastructure, not performance management. Compensation tied loosely or not at all. + +--- + +## Failure 12: OKRs were set but never referenced + +**Symptom.** OKRs documented at start of quarter. Mid-quarter prioritization debates ignore them. End-of-quarter scoring is generous because nobody tracked rigorously. + +**Diagnosis.** OKR theater. The practice produces overhead without value. + +**Cure.** Reform the cadence. Weekly check-ins reference OKRs explicitly. Mid-quarter review uses OKRs as the assessment lens. Scoring informs next quarter. + +**Prevention.** Tie OKRs to specific decisions. If OKRs are not load-bearing for prioritization, surface the disconnect and reform or abandon. + +--- + +## Failure 13: KRs depend on factors outside team influence + +**Symptom.** KRs miss because of external factors the team could not affect (market conditions, sales execution, infrastructure issues). The team cannot credibly own the KR. + +**Diagnosis.** KR design failure. Targets set on outcomes the team cannot meaningfully drive. + +**Cure.** Rewrite to focus on what the team can move. The team's contribution to a larger outcome may be the right KR, not the larger outcome itself. + +**Prevention.** During KR design, validate that the team can identify how their work moves the KR. + +--- + +## Failure 14: Cross-team OKRs produce coordination failures + +**Symptom.** Multiple teams have KRs aimed at the same outcome. Teams pursue independently; the outcome lags because nobody owns the integration. + +**Diagnosis.** Cross-team coordination missing. Either single ownership should have been assigned, or split KRs need stronger coordination. + +**Cure.** Establish single ownership for outcome OKRs that span multiple teams. Or use split-KR pattern where each team's KR is their specific contribution. + +**Prevention.** During OKR design, surface cross-team dependencies. Decide single-owner or split-KR explicitly. + +--- + +## Failure 15: OKRs are roadmap commitments to stakeholders + +**Symptom.** Stakeholders treat OKRs as commitments to specific work. Mid-quarter tactical adjustments feel like broken promises. + +**Diagnosis.** OKR-as-roadmap conflation. Stakeholders interpret outcomes as outputs. + +**Cure.** Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Both are visible; the OKR is the accountability; the roadmap is the team's current best guess at what work will produce the outcome. + +**Prevention.** When communicating OKRs to stakeholders, explicitly surface the distinction. Use different vocabulary. + +--- + +## The cross-cutting pattern + +Most OKR failures share a single root: treating OKRs as ceremony rather than as accountability infrastructure. + +Ceremony focuses on the appearance of OKR practice: documents produced, meetings held, scores generated. Accountability focuses on the work the practice is meant to support: stretch goal-setting, mid-quarter learning, end-of-quarter scoring honesty, next-quarter improvement. + +The fix for almost any OKR failure starts with the same question: what decision is this OKR practice supposed to inform? When the answer is clear, the practice becomes load-bearing. When the answer is "we should follow the OKR process," the practice becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-accountability pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md b/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md new file mode 100644 index 0000000..8ad33d3 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md @@ -0,0 +1,242 @@ +# Key result design patterns + +Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. + +Key results are where the OKR practice succeeds or fails operationally. Objectives can be inspiring without measurable; key results have to be measurable. Most OKR failure at the operational level shows up in the key result design. + +--- + +## The four characteristics of strong key results + +**Measurable.** A specific number, percentage, or testable threshold. + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." + +**Outcome-aligned.** Achieving the key result actually moves the objective forward. + +- For the activation objective, the key results above are aligned: they all measure aspects of activation. +- A key result like "ship the onboarding redesign" is not outcome-aligned; it measures the work, not the activation outcome. + +**Within team influence.** The team can affect the key result through their work. + +- "First-week activation rate" is influenced by onboarding design, welcome email content, in-product guidance. The team can affect it. +- "Total signups" depends primarily on marketing acquisition; the activation team's onboarding work affects it weakly. Not a strong key result for the activation team. + +**Time-bounded.** The measurement window is the quarter (or appropriate sub-window). + +- "Increase first-week activation rate from 32% to 45% by end of Q3." +- "Reach 80% completion rate by week 10 of the quarter." + +The four characteristics together produce key results the team can commit to credibly and measure honestly. + +--- + +## Strong key result examples by objective + +**Objective: "Improve activation for new sign-ups so more reach value-realization in week one."** + +Strong KRs: + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." +- "Reduce signup-to-first-key-action time from 8 minutes to under 4 minutes." + +Each measures an aspect of activation. The team can influence each through their work. Each has a baseline and target. + +**Objective: "Make support experience deflect predictable issues."** + +Strong KRs: + +- "Reduce ticket volume on the top 3 deflection-eligible categories by 40%." +- "Increase self-service resolution rate from 22% to 38%." +- "Maintain CSAT at or above 4.4/5 (no degradation while deflecting)." + +The third KR matters: deflecting tickets without protecting CSAT could damage the experience; the KR keeps both in scope. + +**Objective: "Establish enterprise-readiness foundations."** + +Strong KRs: + +- "Pass SOC 2 Type II audit with zero high-severity findings." +- "Complete admin role and permissions overhaul; reach 95% of enterprise-prospect compliance checklist items." +- "Onboard 3 design partners from the enterprise segment to the alpha enterprise build." + +Each measures a foundation outcome the enterprise readiness depends on. + +--- + +## Weak key result examples + +**Vague.** + +- "Improve activation significantly." +- "Reduce ticket volume." + +No specific number; cannot be scored honestly. + +**Output disguised as outcome.** + +- "Ship 5 onboarding redesign initiatives." +- "Run 12 customer interviews." + +Counts work done, not outcomes produced. The team can hit these by doing work without producing the outcome the objective targets. + +**Outside influence.** + +- "Increase total signups by 50%." +- "Maintain market share." + +Total signups are upstream of activation work; market share depends on competitive dynamics largely outside the team's control. + +**Vanity.** + +- "Reach 1M users." +- "Reach 10K NPS responses." + +Impressive numbers; not directly tied to the outcome the objective targets. + +**Single-data-point dependent.** + +- "Have one customer reference our product publicly." + +Fragile; a single data point may not represent progress. + +--- + +## The 3-5 key results rule + +Most objectives benefit from 3-5 key results. + +**Why not 1.** Single key results are fragile. If the metric does not move for reasons outside the team's tactical choices, the team has no way to show progress on the objective. Multiple KRs triangulate. + +**Why not 6+.** Too many KRs dilute focus. The team scatters attention across many metrics; trade-offs across KRs become impossible because all are claimed as priority. + +**The 3-5 sweet spot.** + +- Enough KRs to triangulate the outcome. +- Few enough that the team can pay attention to each. +- Allows for KRs that protect against unintended degradation (e.g., deflect tickets while protecting CSAT). + +**The KR composition.** + +- 1-2 KRs measure the primary outcome. +- 1-2 KRs measure secondary aspects of the outcome. +- 0-1 KRs protect against unintended consequences. + +--- + +## Baseline and target setting + +Each KR needs a baseline and target. + +**Baseline.** The current value of the metric. Pulled from analytics or recent measurement; should be honest, not aspirational. + +**Target.** The value the team commits to reaching by end of quarter. + +**Setting the target.** + +- Stretch: target a value that requires real work to reach. Should hit 60-70% of the time on average across KRs. +- Not sandbagged: target should not be where the team would land without focused effort. +- Not fantasy: target should be reachable through realistic effort paths the team can identify. + +**The historical-trajectory test.** Look at the metric over the past 4 quarters. Where would the metric be at end of next quarter on its current trajectory? The target should be meaningfully above that trajectory; otherwise, the OKR is sandbagged. + +**The effort-path test.** Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, the target is fantasy. + +--- + +## Leading vs lagging key results + +Key results can measure leading indicators (early signals) or lagging indicators (final outcomes). + +**Lagging.** The outcome the team ultimately wants. "First-week activation rate" measures the activation outcome. + +**Leading.** Early signals that the lagging outcome will move. "Onboarding flow completion rate" leads first-week activation rate. + +**The blend.** + +- Some KRs measure leading indicators (so the team has signal early in the quarter). +- Some KRs measure lagging indicators (so the team is accountable to the actual outcome). +- A blend produces both early signal and end-of-quarter accountability. + +**The lagging-only failure.** OKRs that only measure lagging indicators produce no mid-quarter signal. The team cannot tell if they are on track until end of quarter. + +**The leading-only failure.** OKRs that only measure leading indicators produce no end-of-quarter accountability. Leading indicators can move without lagging indicators following. + +--- + +## When binary KRs are appropriate + +Most KRs are quantitative (a number to reach). Some are binary (a milestone to achieve). + +**When binary works.** + +- Audit-pass milestones: "Pass SOC 2 Type II with zero high-severity findings." +- Foundational milestones: "Complete admin role overhaul." +- Launch milestones: "Ship the activation redesign to all users." + +**When binary fails.** + +- Used for KRs that should be quantitative. "Successfully implement activation improvements" is binary disguised as outcome; should be quantitative. +- Used to dodge measurement. Binary KRs that are not actually milestones become "we did it" claims without underlying outcome verification. + +**The discipline.** Use binary KRs sparingly and only when the milestone genuinely is the outcome. Most outcome KRs benefit from quantitative measurement. + +--- + +## KRs across teams + +When multiple teams contribute to the same outcome, KRs need careful design. + +**The split-KR pattern.** Each team has KRs that contribute to the cross-team outcome. + +- Product team KR: "Increase first-week activation rate from 32% to 45%." +- Engineering team KR: "Ship onboarding redesign by week 6 of the quarter." +- Customer success team KR: "Reduce activation-related support ticket volume by 30%." + +Each team is accountable for its contribution; the cross-team outcome benefits from all. + +**The single-owner pattern.** One team owns the outcome KR; other teams support without explicit KRs on the same metric. + +- Product team owns the activation KR. +- Engineering and CS support without separate KRs. +- Cross-team coordination happens outside the OKR structure. + +**The discipline.** Pick a pattern. Hybrid approaches (sometimes shared KRs, sometimes single-owner) produce confusion about accountability. + +--- + +## Common KR design failures + +**Output KRs.** Counts of work shipped instead of outcomes produced. Cure: rewrite. + +**Vague KRs.** Lack measurable targets. Cure: specify number and threshold. + +**Out-of-influence KRs.** Depend on factors the team cannot affect. Cure: rewrite to what the team can move. + +**Vanity KRs.** Impressive numbers not tied to outcome. Cure: tie to the actual outcome. + +**Too few KRs.** Single KR fragility. Cure: 3-5 KRs per objective. + +**Too many KRs.** 6+ KRs dilute focus. Cure: cap at 5. + +**No baseline.** "Reach X" without naming current value. Cure: include baseline. + +**Sandbagged targets.** Targets at or below current trajectory. Cure: stretch beyond what the team would do without focus. + +**Fantasy targets.** Targets with no realistic effort path. Cure: validate against effort-path test. + +**Lagging-only.** No leading indicators. Cure: add leading-indicator KRs. + +--- + +## Methodology-level choices that stay in the public skill + +The four characteristics. Strong and weak KR examples. The 3-5 KR rule. Baseline and target setting. Leading vs lagging KRs. Binary KRs when appropriate. Cross-team KR patterns. Common failures. + +## Implementation choices that stay internal + +Specific KR templates. Specific metrics tooling and dashboards. Specific historical-trajectory analysis. Specific KR scorecards. The team's own conventions for KR wording. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md b/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md new file mode 100644 index 0000000..91b96a0 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md @@ -0,0 +1,214 @@ +# Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. Strategic shift vs uncomfortable OKRs. The recalibration discipline. + +The default is that OKRs hold for the quarter. Teams adapt their tactics; OKRs do not change to match what the team is doing. Recalibration is the exception, not the rule. Recalibrating frequently signals OKR design failure. + +--- + +## The default: OKRs hold + +OKRs are quarterly commitments. The team commits at the start of the quarter and works toward them through the quarter regardless of whether progress feels comfortable. + +**Why holding matters.** + +- OKRs are accountability infrastructure. Changing them mid-quarter weakens the accountability. +- Stretch OKRs are uncomfortable by design. The discomfort is the work. +- Teams that recalibrate when uncomfortable train themselves to recalibrate as a coping mechanism. + +**Adapting tactics, not OKRs.** + +- The OKR target stays. +- The team's tactics for reaching the target adapt as they learn what works. +- New initiatives may be launched; existing ones may be scrapped; the OKR remains the destination. + +--- + +## When to recalibrate + +Three conditions warrant recalibration. + +### Strategic shift + +The company's strategy changed materially mid-quarter. OKRs that no longer reflect the strategy are no longer the right targets. + +**Examples.** + +- The company pivoted to a new market segment; OKRs aimed at the prior segment are no longer strategic. +- A major acquisition or restructure changed the team's mandate. +- Leadership announced a new strategic priority that supersedes the quarter's OKRs. + +**The handling.** Recalibrate explicitly. Document what changed strategically and how OKRs are revised. Communicate to stakeholders so the recalibration is visible and intentional. + +### Major external disruption + +A market change, regulatory event, or significant outage warrants resetting the quarter's targets. + +**Examples.** + +- A major outage consumed weeks of engineering capacity that was meant for OKR work. +- Regulatory changes required compliance work that displaced planned OKRs. +- Market conditions shifted dramatically (recession, supply chain disruption) and the OKRs no longer reflect realistic ambition for the new conditions. + +**The handling.** Recalibrate explicitly. Surface the disruption and its impact. Set new targets that reflect the post-disruption reality. + +### Information that invalidates the OKR + +The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +**Examples.** + +- Analytics work revealed that the activation metric the team was targeting is not the right measure of activation success; a better metric exists. +- Customer research revealed that the user segment the team was prioritizing is smaller or less important than expected. +- Technical investigation revealed that the planned approach to an OKR has fatal limitations that were not visible at planning time. + +**The handling.** Recalibrate explicitly. Document what was learned. Set new OKRs reflecting the new understanding. + +--- + +## When NOT to recalibrate + +Three patterns that look like recalibration triggers but are not. + +### The team is not on track + +OKRs that the team is missing should remain as set; the miss is the signal. + +**Why.** Stretch OKRs are designed to miss sometimes. Hitting 60-70% on average means roughly 30-40% of KRs miss the target. The miss is informative; lowering the target to match the trajectory eliminates the signal. + +**The cure.** Hold the OKR. Score honestly at end of quarter. Use the miss to inform next quarter's design. + +### The OKR is uncomfortable + +Teams uncomfortable with stretch OKRs sometimes want to recalibrate to feel better. + +**Why.** Stretch is uncomfortable by design. Teams that learn to lower OKRs when uncomfortable lose the stretch discipline; OKRs drift toward sandbagging quarter over quarter. + +**The cure.** Hold the OKR. Acknowledge the discomfort. Surface what the team would need to push toward the target. Use the discomfort productively rather than recalibrating it away. + +### Easier OKRs would feel achievable + +The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +**Why.** Hard OKRs are the point. Swapping for easier ones removes the accountability infrastructure stretch OKRs provide. + +**The cure.** Hold the OKR. If the original was genuinely fantasy (no realistic effort path), recalibrate per the strategic-shift pattern. If the original was genuine stretch but uncomfortable, hold. + +--- + +## The recalibration discipline + +When recalibration is warranted, the discipline matters. + +**Surface the trigger.** What changed? Strategic shift, external disruption, or invalidating information. Be specific. + +**Document the original target and the revised target.** The history of recalibration is part of the OKR record. Future audits should be able to see what changed. + +**Explain the new target.** Why this revised target? What effort path produces it? How does it reflect the new reality? + +**Communicate to stakeholders.** Recalibration is visible. Stakeholders who expected the original target should know it changed and why. + +**Score against the revised target at end of quarter.** The recalibrated OKR is the OKR for scoring purposes. Do not score against the original. + +--- + +## Frequency of recalibration + +Recalibration should be rare. + +**Healthy frequency.** 1-2 quarters out of 8 may include recalibration on at least one OKR. Most quarters should have no recalibrations. + +**Concerning frequency.** Every quarter includes recalibration on some OKR. This signals either: + +- The OKR design is consistently aggressive (fantasy targets). +- The strategy is shifting too frequently (lack of strategic stability). +- The team has learned to recalibrate as a coping mechanism for stretch. + +**The diagnosis.** Frequent recalibration is a signal to investigate, not a feature to lean into. The investigation surfaces whether the issue is OKR design, strategic stability, or team behavior. + +--- + +## Recalibration as honest tool vs avoidance + +The line between honest recalibration and avoidance. + +**Honest recalibration.** + +- The trigger is specific and external (strategic shift, disruption, invalidating information). +- The revised target reflects the new reality, not the team's preference. +- The recalibration is documented and visible. + +**Avoidance dressed as recalibration.** + +- The trigger is vague ("things changed"). +- The revised target is conveniently achievable. +- The recalibration happens when the OKR is uncomfortable, not when external conditions warrant it. + +**The honest test.** If a stakeholder asked the team to defend the recalibration, could the team point to a specific external trigger? If the answer is "we just thought the target was too ambitious," the recalibration is avoidance. + +--- + +## Recalibration in the OKR system + +How recalibration affects the broader OKR practice. + +**Trust effects.** + +- Recalibration that is rare and well-justified preserves trust in OKRs. +- Recalibration that is frequent or poorly justified erodes trust; stakeholders learn to expect targets to slide. + +**Org-wide signaling.** + +- One team's recalibration affects how other teams perceive recalibration norms. +- Leaders that recalibrate strict targets signal to teams that recalibration is acceptable; teams take the cue. +- Leaders that hold targets even when uncomfortable signal that stretch is real; teams take that cue. + +**The practice's calibration over time.** Recalibration norms accumulate. Healthy practices stay disciplined; decaying practices loosen. The annual review of OKR practice should look at recalibration frequency as one signal of practice health. + +--- + +## Communicating recalibration + +When recalibration happens, communication matters. + +**To the team.** + +- Surface the trigger before the recalibration is decided. The team should understand what changed. +- Discuss the revised target before committing. The team should be able to commit credibly to the new target. +- Document the change in the OKR system. + +**To stakeholders.** + +- Notify stakeholders explicitly. Do not let recalibration appear as a quiet edit. +- Explain the trigger and the revised target. +- Invite questions; stakeholder concerns may surface issues with the recalibration that warrant further discussion. + +**To the org.** + +- Recalibration patterns inform org-wide OKR discussion. If multiple teams recalibrate in the same quarter, surface the pattern; the strategic clarity may be lacking. + +--- + +## Common recalibration failures + +**Recalibration as the default.** Teams routinely revise OKRs mid-quarter. The OKR system collapses into rolling targets that always reflect current state. + +**Recalibration to avoid stretch discomfort.** Teams revise when OKRs feel uncomfortable; targets drift toward sandbagging. + +**Recalibration without trigger documentation.** OKRs change without surfaced reason; the change becomes invisible to stakeholders. + +**Refusal to recalibrate when warranted.** Teams hold OKRs even when strategy genuinely shifted; quarter ends with OKRs disconnected from strategy. + +**Recalibration to avoid scoring low.** Teams revise targets in the last weeks of the quarter to make the score look better. Scoring loses honesty. + +**Org-wide recalibration cascade.** One team's recalibration triggers others; the whole quarter resets; the OKR system loses meaning. + +--- + +## Methodology-level choices that stay in the public skill + +The default-to-hold principle. When to recalibrate (strategic shift, major disruption, invalidating information). When not to recalibrate (uncomfortable, off-track, easier-feels-better). The recalibration discipline. Frequency norms. Honest vs avoidance recalibration. Communication. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that capture recalibration history. Specific approval workflows for recalibration. The team's own conventions for recalibration communication. These vary by org. diff --git a/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md b/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md new file mode 100644 index 0000000..e1fc8fa --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md @@ -0,0 +1,191 @@ +# Objective design patterns + +Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. + +Objectives are the outcome statements that name what the team is trying to achieve in the quarter. Most OKR failure begins at the objective level: outputs disguised as outcomes, vague aspirations, or too many objectives diluting focus. Getting the objective right is upstream of everything else. + +--- + +## Outcome vs output + +The most consequential distinction. + +**Output objectives.** Describe work the team plans to do. + +- "Ship the activation redesign." +- "Migrate to the new auth service." +- "Run 12 customer interviews." + +**Outcome objectives.** Describe results the team is trying to achieve. + +- "Improve activation for new sign-ups so more reach value-realization in week one." +- "Establish auth foundations that support enterprise compliance review." +- "Build a research-grounded picture of how mid-market customers actually use the product." + +**Why the distinction matters.** Outputs can be shipped without producing outcomes. The activation redesign ships; activation rate stays the same. The auth migration completes; compliance review still fails. The interviews happen; the team cannot point to decisions that changed. + +**The output-as-outcome failure.** Output objectives shift the team's incentives toward shipping rather than achieving. The team optimizes for the work; the work gets done; the underlying goal goes unachieved. + +**The cure.** Each output objective gets rewritten to name the outcome the output is meant to produce. If the team cannot name the outcome, the output's value is unclear and may not warrant quarterly priority. + +--- + +## Strong objective characteristics + +**Outcome-focused.** Names the result, not the work. + +**Specific to the quarter.** Vague aspirations ("be more user-focused") do not focus quarterly work. The objective should be specific enough that the team knows when they have moved it forward. + +**Inspiring without being fantasy.** The team should feel pulled toward the objective. Fantasy demoralizes; sandbag bores. Stretch motivates. + +**Few in number.** 2-4 objectives per team per quarter. More dilutes focus; the team works on too many things and excels at none. + +**Connected to strategy.** Objectives ladder up to company-level priorities or to the team's strategic mandate. Disconnected objectives produce work that does not contribute to the org's direction. + +**Within team influence.** The team can affect the outcome through their work. Objectives entirely dependent on external factors are not the team's to commit to. + +--- + +## Weak objective characteristics + +**Output-disguised-as-outcome.** "Ship the redesign" is the work; the outcome should be the result the redesign produces. + +**Too vague.** "Improve user experience" is too broad to focus a quarter's work. What aspect of UX, in what part of the product, for which users? + +**Too tactical.** "Refactor the auth service" is a tactical decision the team makes within larger initiatives, not a quarterly objective. + +**Too many.** 8 objectives produces no focus. Each objective gets less attention; trade-offs become impossible because everything is priority. + +**Disconnected from strategy.** Objectives that do not ladder to company priorities or team mandate produce work that does not contribute. + +**Outside team influence.** "Total revenue grows 30%" may not be the product team's to commit to if revenue depends on sales execution, market conditions, and product work combined. + +--- + +## Worked objective examples by domain + +### B2B SaaS product team + +- "Improve activation for new sign-ups so that more reach the value-realization moment within their first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +### Consumer mobile app team + +- "Increase retention through the first month so users build habit before the typical churn window." +- "Improve performance and reliability so the experience matches the brand's reputation." + +### Internal platform team + +- "Reduce the time it takes engineering teams to ship a new service from days to under a day." +- "Eliminate the top three reasons engineering teams escalate to platform support." + +### Marketing-product team + +- "Convert more product trial users to paid by removing friction in the upgrade path." +- "Position the product clearly enough that prospects evaluating against alternatives understand the differentiation." + +Each objective is outcome-focused, specific to the quarter, and within the team's ability to influence. The work that produces these outcomes is multiple roadmap items; the OKR is the result, not the work. + +--- + +## The few-objectives discipline + +Most teams should have 2-4 objectives per quarter. The discipline produces focus. + +**Why fewer is better.** + +- Each objective gets serious attention. The team thinks about it weekly, makes trade-offs against it, surfaces blockers. +- Trade-offs are possible. With 3 objectives, the team can decide that work on objective A takes priority over work on objective C this week. With 12 objectives, all work claims priority. +- The team can credibly commit. 3 objectives are credible; 12 are not. + +**Why more feels tempting.** + +- Multiple stakeholders want their priorities reflected. Adding objectives feels like accommodating; capping objectives feels like saying no. +- The team sees many things they could pursue. Picking 3 means deferring others. +- Past quarters' OKRs sometimes accumulate; teams forget to retire objectives that no longer fit. + +**The discipline.** + +- Cap objectives. 4 is the upper bound for most teams. +- Surface what is being deferred. The objectives that did not make the cut get named explicitly; the team's choice to defer is transparent. +- Retire objectives quarter-over-quarter. Objectives are quarterly; they do not carry over by default. + +--- + +## Objectives across an org + +When the org has multiple teams, objectives should compose without overlap or contradiction. + +**Cross-team coordination.** + +- Objectives that depend on multiple teams should name the dependencies explicitly. The product team's objective may depend on engineering hiring; the engineering team's objective may depend on product prioritization. +- Objectives that conflict across teams need resolution before the quarter starts. Teams pulling in opposite directions waste capacity. + +**Team mandate alignment.** + +- Each team's objectives should fit the team's mandate. Product team objectives are product outcomes; engineering team objectives are engineering outcomes; design team objectives are design outcomes. +- Cross-functional outcomes (e.g., "improve activation") require multiple teams to commit. The lead team owns the OKR; the supporting teams commit dependencies in their own OKRs. + +--- + +## Objective writing process + +How objectives get drafted. + +**Draft sources.** + +- Strategy work that named the priorities for the quarter or year. +- Discovery synthesis that identified user-job priorities. +- Roadmap-planning work that surfaced major initiatives. +- Performance review that identified gaps from the prior quarter. + +**Draft method.** + +- Start from the outcome the team is trying to produce. +- Surface multiple draft phrasings. +- Test each: is this an outcome or an output? Is it specific enough? Is it within team influence? +- Iterate to a 2-4 objective set that the team can commit to and that ladders to strategy. + +**Stakeholder review.** + +- Draft objectives circulate to stakeholders before commit. Surfaces dependencies and conflicts. +- Stakeholder feedback informs revisions; the team owns the final commit. + +**The commitment.** Objectives published and visible to the org. The team is on the hook for them. + +--- + +## Objective revision through the quarter + +Objectives generally hold for the quarter. See `mid-quarter-recalibration.md` for when revision is appropriate. + +**The default.** Objectives stay; tactics adapt to keep moving toward them. + +**The exception.** Strategic shift, major external disruption, or invalidating information warrants revision. Rare. + +--- + +## Common objective design failures + +**Output objectives.** "Ship X" instead of "Achieve outcome Y through X." Cure: name the outcome. + +**Vague objectives.** "Improve experience" without specifying what or where. Cure: specificity. + +**Too many objectives.** 8+ per team per quarter. Cure: cap at 4. + +**Tactical objectives.** Specific implementation decisions framed as objectives. Cure: tactical decisions belong in roadmap items, not OKRs. + +**Strategic-disconnect.** Objectives that do not ladder to company or team priorities. Cure: explicit ladder before commit. + +**Out-of-influence.** Objectives entirely dependent on factors the team does not control. Cure: rewrite to focus on what the team can affect. + +--- + +## Methodology-level choices that stay in the public skill + +The outcome-vs-output distinction. Strong and weak objective characteristics. Worked examples across domains. The few-objectives discipline. Cross-team coordination. The drafting and review process. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools the team uses. Specific document templates for objectives. Specific stakeholder-review formats. The team's own conventions for objective wording within the principles. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md b/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md new file mode 100644 index 0000000..f70fe2f --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md @@ -0,0 +1,249 @@ +# OKR anti-patterns + +Eight-plus anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling, and others. Each anti-pattern names a recurring failure mode that decays OKR practice over time. + +--- + +## Anti-pattern 1: OKR-as-roadmap + +**The pattern.** OKRs are written as a list of features the team plans to ship. + +**Examples.** + +- "Objective: Ship the activation redesign. KR: Activation redesign launched by week 8. KR: Welcome email v2 launched by week 4." + +**Why it fails.** + +- Outputs disguised as outcomes. The team is committing to work, not to results. +- The outcome the work is meant to produce goes unspecified; the team can ship the redesign without producing the activation outcome. +- OKRs become roadmap commitments to stakeholders; mid-quarter tactical changes feel like broken promises. + +**The cure.** Each OKR names the outcome the work is meant to produce. The work itself lives in the roadmap. + +--- + +## Anti-pattern 2: Sandbagging + +**The pattern.** OKRs designed to hit 100%. Targets at or below the team's current trajectory. + +**How it manifests.** + +- KR targets within 5% of current values. +- KR targets achievable on standard execution without focused effort. +- Average end-of-quarter scores at 95%+. +- Team consistently celebrates "hitting all our OKRs." + +**Why it fails.** + +- No stretch; no learning. The team did not commit to ambition; the OKR practice produced no signal beyond what the team would have done anyway. +- Sandbagging compounds. Teams that sandbag once learn that sandbagging is safe; subsequent quarters get worse. +- Stakeholder trust degrades. Stakeholders learn that "hitting OKRs" does not mean ambitious work was done. + +**The cure.** Set targets above the team's current trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The OKR target should be meaningfully above that. + +--- + +## Anti-pattern 3: Aspirational fantasy + +**The pattern.** OKRs that nobody can hit. Targets with no realistic effort path. + +**How it manifests.** + +- KR targets at 5x or 10x current values without underlying capacity changes. +- Targets set for inspiration rather than commitment. +- Average end-of-quarter scores at 30% or below. +- Team disengages from OKRs by week 3-4 of the quarter. + +**Why it fails.** + +- Demoralizing. Teams cannot hit fantasy targets; the targets become decoration. +- Loss of meaning. When OKRs cannot be hit, scoring loses meaning; teams stop tracking. +- Compensation distortion. If OKRs are tied to compensation, fantasy targets create unfairness; teams cannot earn rewards regardless of effort. + +**The cure.** Validate against the effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, recalibrate. + +--- + +## Anti-pattern 4: Vanity metrics + +**The pattern.** KRs that measure impressive numbers not tied to the outcome. + +**Examples.** + +- "Reach 1M users." +- "Generate 10K leads." +- "Reach 500K social followers." + +**Why it fails.** + +- Numbers can be moved without producing the outcome the OKR was meant to address. +- Vanity targets often correlate with marketing or acquisition spend rather than with product outcomes. +- The team can hit vanity KRs while the underlying outcome (engagement, retention, revenue) does not improve. + +**The cure.** Each KR should connect to the outcome the OKR targets. If the connection is unclear, the KR is probably vanity. Replace with a KR that more directly measures the outcome. + +--- + +## Anti-pattern 5: OKR theater + +**The pattern.** OKRs are documented and presented but do not drive decisions. + +**How it manifests.** + +- OKRs are set at the start of the quarter and not referenced again until end of quarter. +- Mid-quarter prioritization decisions ignore OKRs. +- The team makes the same prioritization choices that they would have made without OKRs. +- OKR scores are produced at end of quarter but do not inform the next quarter's planning. + +**Why it fails.** + +- The OKR practice produces overhead without value. The team spends time on OKR ceremony without changing what they would have done. +- Stakeholder skepticism builds. Stakeholders learn that OKRs are not load-bearing. +- The practice decays further over time as the team rationalizes that the ceremony does not matter. + +**The cure.** Tie OKRs to specific decisions. Mid-quarter prioritization debates should reference OKRs. Roadmap items should map to OKRs. Scoring should inform the next quarter. If none of these happen, the OKR practice is theater; reform or abandon. + +--- + +## Anti-pattern 6: Compensation coupling + +**The pattern.** OKR scores directly determine bonuses or performance ratings. + +**Why it fails.** + +- Sandbagging incentives become severe. Teams set OKRs they know they can hit to protect their compensation. +- Honest scoring suffers. Teams round scores up to avoid compensation impact. +- Stretch ambition disappears. The OKR practice collapses to "what we are confident we can hit." +- Team trust in OKRs degrades; the practice becomes performance management theater. + +**The cure.** Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs (manager assessment, peer feedback, role expectations); OKR scores may be one input but should not be dominant. + +**The transition.** Orgs that have coupled OKRs and compensation need explicit decoupling communication. Teams need to trust that scoring honestly will not affect bonuses; the trust takes 2-3 cycles to establish. + +--- + +## Anti-pattern 7: OKR proliferation + +**The pattern.** Teams set 8-12 OKRs per quarter. Every team member's work is reflected in some OKR. + +**Why it fails.** + +- Focus dilutes. The team works on too many things; trade-offs become impossible because everything is priority. +- Tracking burden grows. Weekly check-ins become status reports across too many KRs. +- Scoring becomes performative. Teams cannot honestly score 40+ KRs at end of quarter. + +**The cure.** Cap OKRs. 2-4 objectives per team; 3-5 KRs per objective. Surface what is not in OKRs as deferred work that the team is choosing not to commit to this quarter. + +--- + +## Anti-pattern 8: Cascade theater + +**The pattern.** OKR documents include cascading ladders that look connected but do not actually drive work. + +**How it manifests.** + +- Team OKRs claim ladders to company OKRs but the team's actual work would have happened regardless. +- Cascading documents look impressive but do not coordinate cross-team work. +- The cascade is performed for stakeholders rather than for execution. + +**Why it fails.** + +- Cascading work is overhead without value. +- Cross-team coordination does not actually happen through the cascade. +- Stakeholders learn that the cascade is theater. + +**The cure.** Make ladders explicit only when they genuinely connect. Loosen cascading where strict ladders produce theater. See `cascading-okrs-decisions.md` for the discipline. + +--- + +## Anti-pattern 9: Mid-quarter recalibration as default + +**The pattern.** OKRs get revised mid-quarter routinely. The team uses recalibration to soften OKRs that feel uncomfortable. + +**Why it fails.** + +- OKRs lose accountability. Teams learn that revising mid-quarter is acceptable; commitment loosens. +- Stretch ambition disappears. Discomfort triggers recalibration rather than effort. +- Targets drift toward sandbagging quarter over quarter. + +**The cure.** Hold OKRs absent strategic shift, major disruption, or invalidating information. See `mid-quarter-recalibration.md` for the discipline. + +--- + +## Anti-pattern 10: Output-only KRs + +**The pattern.** Key results count work shipped rather than measure outcomes produced. + +**Examples.** + +- "Ship 5 onboarding initiatives." +- "Run 12 customer interviews." +- "Publish 8 marketing pieces." + +**Why it fails.** + +- Counts work, not outcomes. The team can hit these by doing work without producing the outcome. +- Optimizes for shipping volume rather than impact. +- Loses the connection between work and result. + +**The cure.** For each output KR, identify the outcome the output is meant to produce. Replace the count with a measurement of the outcome. + +--- + +## Anti-pattern 11: KRs entirely outside team influence + +**The pattern.** KRs depend on factors the team cannot control. + +**Examples.** + +- "Total revenue grows 30%" (depends on sales execution and market conditions, not just product work). +- "Maintain market share" (depends on competitive dynamics). +- "Reach Series B" (depends on investor decisions outside the team). + +**Why it fails.** + +- The team cannot credibly commit. Effort does not produce predictable outcomes. +- Failure is not informative. Misses do not reveal what the team should have done differently. +- Demoralizing. Teams hit fail OKRs they had little ability to affect. + +**The cure.** Rewrite KRs to focus on what the team can move. Total revenue may not be the team's KR; the team's contribution to revenue (e.g., product-led acquisition rate) might be. + +--- + +## Anti-pattern 12: Generous scoring + +**The pattern.** End-of-quarter scoring rounds up systematically. + +**How it manifests.** + +- KRs at 0.55 score 0.6 or 0.7. +- KRs at 0.85 score 1.0. +- The team's average score is 0.85+ even when objective outcomes were mid-range. + +**Why it fails.** + +- Honest signal lost. Scoring no longer reflects outcomes. +- Sandbagging compounds. Teams learn that scoring high is rewarded; subsequent quarters drift further. +- Lessons get lost. Misses scored as hits do not inform improvement. + +**The cure.** Hold the discipline of honest scoring. Document context per score; the context surfaces what produced the actual outcome regardless of the number. + +--- + +## The cross-cutting pattern + +Most OKR anti-patterns share a single root: optimizing for the appearance of OKR success rather than for the underlying outcomes. + +Sandbagging optimizes for hitting 100%. Fantasy optimizes for inspirational targets. OKR theater optimizes for documentation. Compensation coupling optimizes for bonus protection. Generous scoring optimizes for end-of-quarter celebration. + +Each anti-pattern produces apparent OKR success while undermining the OKR practice's actual purpose. The fix in every case is the same: focus on the underlying outcomes the practice is meant to produce, not on the OKR ceremony itself. + +--- + +## Methodology-level choices that stay in the public skill + +The twelve anti-patterns with diagnoses and cures. The cross-cutting appearance-vs-outcome pattern. + +## Implementation choices that stay internal + +Specific anti-pattern detection in the team's tracking tools. Specific reviewer training. Specific intervention patterns when anti-patterns are detected. The team's own conventions for catching drift early. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md b/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md new file mode 100644 index 0000000..9f9514c --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md @@ -0,0 +1,235 @@ +# OKRs vs roadmap vs metrics + +The three concepts and their relationships. Common conflations. The complete picture across all three. + +OKRs, roadmaps, and metrics are often conflated. Each serves a different purpose; conflating them produces confusion that decays each practice. Distinguishing them clarifies what each is for and how they compose. + +--- + +## OKRs + +Outcome targets for the quarter. + +**Characteristics.** + +- Quarterly time horizon. +- Outcome-focused. +- Stretch-ambition. +- Designed for accountability and learning, not for execution sequencing. + +**Examples.** + +- Objective: "Improve activation for new sign-ups." +- Key result: "Increase first-week activation rate from 32% to 45%." + +**What OKRs are not.** + +- A roadmap. OKRs do not specify which initiatives to ship. +- A metric. OKRs are quarterly targets on metrics; the metrics themselves are tracked continuously regardless of OKRs. +- A commitment to specific work. The team commits to pursuing the outcome; the tactics adapt. + +--- + +## Roadmap items + +Initiatives the team is building or doing. + +**Characteristics.** + +- Variable time horizon (weeks to months per initiative). +- Output-focused (the work being done). +- Sequenced by priority and dependency. +- Designed for execution coordination. + +**Examples.** + +- "Onboarding redesign." +- "Migrate to new auth service." +- "Build admin role overhaul." + +**What roadmap items are not.** + +- OKRs. Roadmap items are work; OKRs are outcomes. +- Metrics. Roadmap items contribute to moving metrics but are not metrics themselves. +- Permanent commitments. Items can be added, dropped, or re-prioritized as circumstances change. + +--- + +## Metrics + +Ongoing measurements the team tracks. + +**Characteristics.** + +- Continuous time horizon (always tracked). +- Quantitative, time-stamped, queryable. +- Designed for monitoring, learning, and OKR target-setting. + +**Examples.** + +- "First-week activation rate." +- "Median time-to-first-value." +- "Onboarding flow completion rate." + +**What metrics are not.** + +- OKRs. Metrics are continuous; OKRs are quarterly targets on metrics. +- Roadmap items. Metrics are measurements; roadmap items are work. +- Targets. Metrics are values; targets on metrics are KRs (or more generally, performance targets). + +--- + +## The relationship + +How the three compose. + +**OKR: "Improve activation for new sign-ups."** + +- Key result: "First-week activation rate from 32% to 45% by end of quarter." + - Underlying metric: "First-week activation rate" (tracked continuously). + - Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +**The composition.** + +- OKR names the outcome. +- Key result quantifies the outcome with a metric and target. +- Metric is the underlying measurement. +- Roadmap items are the work the team does to move the metric. + +**The flow.** + +- Strategy informs OKRs. +- OKRs inform roadmap prioritization (which work moves which OKR). +- Roadmap items get executed. +- Metrics track the impact. +- Scoring at end of quarter assesses the OKR's actual outcome. + +--- + +## Common conflations + +### OKRs treated as roadmap commitments + +**The pattern.** "Ship the onboarding redesign" written as an OKR. + +**The diagnosis.** This is a roadmap item, not an OKR. The OKR is the outcome the redesign is meant to produce. + +**The cure.** Rewrite as outcome: "Improve activation through onboarding redesign that reaches first-week activation 45%." The redesign is the contributing work; the outcome is what the work is meant to produce. + +### Roadmap items treated as OKRs + +**The pattern.** Quarterly OKRs are a list of features the team plans to ship. + +**The diagnosis.** Output disguised as outcome. The team is committing to work, not to results. + +**The cure.** For each output OKR, identify the outcome the output is meant to produce. The OKR is the outcome; the output is roadmap work that contributes. + +### Every metric needing an OKR + +**The pattern.** The team feels every metric they track must have an OKR target. + +**The diagnosis.** Metrics serve monitoring purposes regardless of whether the team is currently driving them. Some metrics are leading indicators the team watches without driving; some are protective metrics the team watches to ensure they do not degrade. + +**The cure.** OKRs select which metrics the team is actively driving this quarter. Other metrics get tracked without OKR targets. + +### OKRs as roadmap commitments to stakeholders + +**The pattern.** Stakeholders ask "what are you committing to ship next quarter?" The team answers with OKRs. + +**The diagnosis.** The team is using OKRs as roadmap; stakeholders interpret them as roadmap commitments; mid-quarter tactical adjustments feel like broken promises. + +**The cure.** Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Stakeholders can see both; the OKR is what the team is accountable for; the roadmap is the team's current best guess at what work will produce the outcome. + +### Treating metrics as OKRs + +**The pattern.** "Maintain CSAT at 4.5" written as an OKR for a quarter when the team has no specific work aimed at CSAT. + +**The diagnosis.** This is metric monitoring, not an OKR. OKRs are stretch outcomes the team is actively pursuing; metric monitoring continues regardless. + +**The cure.** Track CSAT as a metric. Set an OKR if the team is actively driving CSAT improvement; otherwise, the metric is monitored without an OKR. + +--- + +## When the three diverge + +Sometimes OKRs, roadmap, and metrics tell different stories. + +**The pattern.** + +- OKR is on track (KR moving toward target). +- Roadmap items are shipping on schedule. +- A different metric the team tracks is degrading. + +**The interpretation.** The OKR work is succeeding at its target; an unintended consequence may be hurting another metric. The team must decide whether to address the unintended consequence within the quarter or to defer. + +**The discipline.** OKRs are the formal commitment; roadmap items contribute to OKRs; metrics monitor everything (including OKR targets and protective metrics). When the three diverge, the team has decisions to make. + +--- + +## Roadmap-OKR alignment + +How the roadmap maps to OKRs. + +**The mapping.** + +- Each roadmap item gets associated with the OKR(s) it contributes to. +- Items not associated with any OKR are either team-specific work (technical debt, tooling) or candidates for deferral. + +**Worked example.** + +- OKR: "Improve activation for new sign-ups." +- Contributing roadmap items: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +- OKR: "Establish enterprise-readiness foundations." +- Contributing roadmap items: "Admin role overhaul," "SOC 2 audit preparation." + +- Team-specific roadmap items (no OKR ladder): "Migrate to new auth service" (foundational; supports many OKRs), "Strengthen test coverage in critical paths" (engineering health). + +**The discipline.** All roadmap items have either an OKR ladder or an explicit team-specific designation. Items with neither are candidates for deprioritization. + +--- + +## Metric coverage and OKR targets + +How metrics are selected and how OKR targets relate. + +**Metric coverage.** The team tracks metrics that: + +- Reflect strategic outcomes (input metrics for OKRs). +- Monitor protective concerns (metrics that should not degrade). +- Surface leading indicators of larger outcomes. +- Provide diagnostic signal for issues. + +**OKR target selection.** Each quarter, the team selects which metrics to set OKR targets on: + +- Metrics tied to the quarter's strategic priorities. +- Metrics where stretch progress is plausible and meaningful. +- Often a subset of the broader metric set. + +**The remaining metrics.** Tracked without OKR targets. Monitored for movement; surfaced if they shift unexpectedly. + +--- + +## Common failures across the three + +**OKR-as-roadmap.** Quarterly commitments written as features rather than outcomes. + +**Roadmap-as-OKR.** Roadmap items called OKRs; output disguised as outcome. + +**Every-metric-as-OKR.** OKRs proliferate to cover every tracked metric; focus diluted. + +**OKR-without-roadmap-mapping.** OKRs set without identifying which work will move them; teams miss the OKRs because no work is aimed at them. + +**Roadmap-without-OKR-mapping.** Work happens without explicit OKR connection; teams cannot tell what their work is contributing to. + +**Metrics-without-OKR-distinction.** All metrics treated as targets; team cannot prioritize. + +--- + +## Methodology-level choices that stay in the public skill + +The three concepts and their characteristics. The relationship and composition. Common conflations and cures. When the three diverge. Roadmap-OKR alignment. Metric coverage and OKR target selection. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools. Specific roadmap tools. Specific metrics dashboards. Specific integration between OKR system and roadmap system. The team's own conventions for OKR-roadmap-metric documentation. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md b/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md new file mode 100644 index 0000000..8ca8934 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md @@ -0,0 +1,230 @@ +# Review cadence templates + +Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. + +OKRs benefit from a structured review rhythm. The cadence produces accountability infrastructure: weekly tactical adjustment, mid-quarter strategic assessment, end-of-quarter scoring, and quarterly practice review. Teams that skip the cadence often watch OKRs decay into year-end reckoning that produces no learning. + +--- + +## Weekly check-ins + +The shortest, most frequent review. + +**Format.** + +- 15-30 minutes per team. +- Team reviews progress on each key result. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Decides tactical adjustments for the upcoming week. + +**Structure.** + +- Per KR: current value, trajectory, blockers, planned work for the upcoming week. +- Cross-OKR: any priority shifts, dependencies needing attention. +- Closing: commitments for the week. + +**Purpose.** + +- Tactical adjustment, not OKR adjustment. +- Surface blockers early so they can be addressed. +- Maintain focus on OKRs across the quarter (without weekly check-ins, OKRs get forgotten in the press of immediate work). + +**What this is not for.** + +- Adjusting the OKR or its targets. That is mid-quarter or end-of-quarter work. +- Status reports for stakeholders. Status reports may flow from the check-in but are a separate output. +- Detailed work review. The check-in is OKR-focused; other work happens elsewhere. + +**Common failures.** + +- Becoming status reports. The check-in turns into "here's what I did this week"; OKR-driven decisions get crowded out. Reform the format. +- Becoming OKR adjustment sessions. Teams uncomfortable with OKRs sometimes use weekly check-ins to soften them. Hold to tactical scope. +- Skipping when busy. Weeks where the check-in feels less urgent are exactly when discipline is needed. Skip rarely. + +--- + +## Mid-quarter review + +A longer, more strategic review. + +**Format.** + +- 60-90 minutes per team. +- Roughly week 6 of the quarter (mid-point). +- Honest assessment of trajectory: which KRs are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +**Structure.** + +- Per OKR: current state vs target, trajectory analysis, on-track or off-track assessment. +- Cross-OKR: priority adjustments, capacity reallocations, blockers requiring escalation. +- Recalibration check: is any OKR a candidate for revision per the strategic-shift / disruption / invalidating-information criteria? (See `mid-quarter-recalibration.md`.) +- Closing: tactical decisions for the second half of the quarter. + +**Purpose.** + +- Strategic assessment of OKR progress. +- Course correction before end-of-quarter when there is still time. +- Surface OKRs that may need recalibration (with the discipline that recalibration should be rare). + +**What this is not for.** + +- Routine recalibration. Most mid-quarter reviews end with no recalibration; tactical adjustments are the typical output. +- Scoring. Scoring is end-of-quarter; mid-quarter assesses trajectory toward the score. +- Postmortem. Postmortems are for completed work; mid-quarter is for live work in progress. + +**Common failures.** + +- Becoming a recalibration session. Teams uncomfortable with stretch use mid-quarter review to lower OKRs. Hold to the rare-recalibration discipline. +- Becoming a status meeting. The session becomes a presentation rather than a decision-making review. Reform format to surface decisions. +- Skipping. Teams that skip mid-quarter review often discover at end of quarter that they could have course-corrected; the missed opportunity is the cost. + +--- + +## End-of-quarter scoring + +The OKR-cycle closing review. + +**Format.** + +- 60-90 minutes per team. +- Last week of the quarter. +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +**Structure.** + +- Per KR: actual outcome, score (0.0-1.0), context (what produced this score). +- Per objective: average KR score, context. +- Cross-OKR: average score across all OKRs (informs whether the quarter was stretch, sandbag, or fantasy). +- Lessons: what this quarter's scoring reveals about OKR design, team capacity, or strategic clarity. +- Closing: insights to carry into next quarter's OKR setting. + +**Purpose.** + +- Honest scoring of outcomes. +- Learning from the gap between target and outcome. +- Input to the next quarter's OKR design. + +**What this is not for.** + +- Compensation discussions. OKRs work best decoupled from compensation; scoring should not feel like a performance evaluation. +- Blame allocation. Misses are informative; the discussion is about what produced the gap, not who failed. +- Setting next quarter's OKRs. That is a separate session. + +**Common failures.** + +- Generous scoring. Scores rounded up; the team protects feelings; honest signal lost. Hold the discipline. +- Skipping context. Scores published without explanation of what produced them. Lessons get lost. +- Treating scores as performance. Compensation coupling produces sandbagging in subsequent quarters. +- Not informing next quarter. Scores reviewed but lessons do not influence the next OKR setting. The cycle does not learn. + +--- + +## Quarterly retrospective + +A separate review focused on the OKR practice itself. + +**Format.** + +- 60-90 minutes per team or org. +- After end-of-quarter scoring. +- Reviews the OKR practice, not the OKR outcomes. +- Often combined with the next-quarter OKR setting session. + +**Structure.** + +- What worked in this quarter's OKR practice (cadence, format, design)? +- What did not work? +- What should change in the next cycle? +- What patterns are emerging across multiple quarters? + +**Purpose.** + +- Improve the OKR practice itself. +- Surface decay or drift in OKR discipline. +- Inform process changes for the next cycle. + +**What this is not for.** + +- Scoring or recalibrating current OKRs. That is end-of-quarter work. +- Setting next quarter's OKRs. That is a separate session that uses the retrospective's inputs. + +**Common patterns surfaced.** + +- Sandbagging or fantasy drift. Average score patterns over multiple quarters reveal practice decay. +- Cadence breakdown. Weekly check-ins becoming status reports; mid-quarter reviews becoming recalibration sessions. +- Cascading misalignment. Teams setting OKRs that do not ladder; cross-team coordination failing. +- Compensation coupling. OKRs becoming performance theater because they are tied to bonuses. + +**Common retrospective failures.** + +- Skipping the retrospective. The OKR practice does not improve; decay accumulates. +- Conflating with next-quarter OKR setting. Both can happen in one session, but the retrospective lens (process review) should be distinct from the OKR design lens (setting). +- Producing recommendations without follow-through. Retrospectives surface improvements; the team must implement them in the next cycle for the retrospective to matter. + +--- + +## The cadence as a system + +The four cadences compose. + +**The system.** + +- Weekly check-ins maintain tactical focus and surface blockers. +- Mid-quarter review provides strategic assessment and rare recalibration opportunity. +- End-of-quarter scoring produces honest signal on outcomes. +- Quarterly retrospective improves the practice over time. + +**The reinforcement.** + +- Weekly check-ins make mid-quarter assessment honest (the team has been tracking trajectory all along). +- Mid-quarter review surfaces issues end-of-quarter scoring will face. +- End-of-quarter scoring informs the retrospective. +- The retrospective informs the next cycle's design. + +**The skip risk.** Teams that skip cadences often skip several. Weekly check-ins falter; mid-quarter review becomes ad-hoc; end-of-quarter scoring becomes generous because the team has not been tracking honestly all along; the retrospective never happens. + +--- + +## Cadence ownership + +Each cadence has a clear owner. + +**Weekly check-ins.** Owned by the team lead (manager, PM, engineering lead). Facilitates the meeting; ensures it stays tactical. + +**Mid-quarter review.** Owned by the team lead, often with cross-functional partners attending. Surfaces strategic decisions. + +**End-of-quarter scoring.** Owned by the team lead. Ensures honest scoring; documents context. + +**Quarterly retrospective.** Owned by the team lead or by a process-focused role (chief of staff, ops lead). Often facilitated by someone slightly outside the team to bring fresh perspective. + +**Cross-team coordination.** When multiple teams have OKRs that compose, coordination across teams happens at the cadence boundaries (typically mid-quarter review). + +--- + +## Common cadence failures + +**Skipping cadences.** Weekly check-ins falter; mid-quarter review becomes ad-hoc; the system breaks. + +**Cadence merging.** Mid-quarter review and end-of-quarter scoring combined into one session. Loses the distinct purposes. + +**Status-report drift.** Weekly check-ins become status reports; tactical decisions get displaced. + +**Recalibration drift.** Mid-quarter review becomes a recalibration session; OKRs lose accountability. + +**Generous-scoring drift.** End-of-quarter scoring rounds up; honest signal lost. + +**Retrospective skipping.** OKR practice does not improve; decay accumulates. + +--- + +## Methodology-level choices that stay in the public skill + +The four cadence formats. Time investment per cadence. Structure and purpose per cadence. The cadence-as-system reinforcement. Ownership. Common failures. + +## Implementation choices that stay internal + +Specific meeting templates. Specific OKR-tracking tools that support each cadence. Specific facilitation conventions. Specific cross-team coordination formats. The team's own conventions for cadence cadence (no pun intended). These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md b/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md new file mode 100644 index 0000000..b51963d --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md @@ -0,0 +1,191 @@ +# Scoring discipline + +The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. + +End-of-quarter scoring is where OKR practice succeeds or decays. Honest scoring produces signal: which OKRs the team hit, which they missed, what the gap reveals about the work. Dishonest scoring produces theater: 100% scores claimed regardless of outcome, generous rounding, partial credit for effort rather than outcome. + +--- + +## The 0.0-1.0 scale + +Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +**Key result scoring examples.** + +- KR: "Increase first-week activation rate from 32% to 45%." +- Outcome: rate reached 41%. +- Score: (41 - 32) / (45 - 32) = 9/13 = 0.69. + +- KR: "Reduce median time-to-first-value from 4.2 days to under 2 days." +- Outcome: reduced to 2.6 days. +- Score: (4.2 - 2.6) / (4.2 - 2.0) = 1.6/2.2 = 0.73. + +- KR: "Pass SOC 2 Type II audit with zero high-severity findings." +- Outcome: passed with zero high-severity findings. +- Score: 1.0 (binary KR; achieved). + +**Objective scoring.** Average of the key result scores. + +- Objective with 3 KRs scoring 0.69, 0.73, 1.0: objective scores (0.69 + 0.73 + 1.0) / 3 = 0.81. + +--- + +## The 60-70% target + +Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. + +**Why this target.** + +- Average above 0.85 suggests sandbagging. The team set OKRs they were already on track to deliver. +- Average below 0.4 suggests fantasy. The team set OKRs that no realistic effort path would have produced. +- Average between 0.6-0.7 suggests stretch. The team committed to ambition and delivered most of it. + +**The trajectory check.** Track the team's average score over multiple quarters. Drift toward 0.85+ signals sandbagging is creeping in; drift toward 0.4 signals fantasy. The target zone is 0.55-0.75 over a multi-quarter window. + +**Variance is normal.** Some quarters will hit 0.8 average; some will hit 0.5. The variance reflects the genuine uncertainty in stretch OKRs. Programs that hit 0.65 every single quarter are usually managing scores rather than honestly scoring outcomes. + +--- + +## Scoring honesty + +**Score the actual outcome, not the effort.** A team that worked hard but did not move the metric scores low. A team that got lucky and moved the metric without much effort scores high. The score reflects outcome. + +**Do not round up.** A KR at 0.55 scores 0.55, not 0.6. Honest scoring produces honest signal. Rounding up across multiple KRs accumulates into systemic over-scoring. + +**Acknowledge what changed.** Some misses reflect mid-quarter priority shifts. Surface these without using them as excuses. "We deprioritized this in week 5 to address the security incident" is honest context; "we hit our priorities even though we missed this OKR" is hand-waving. + +**Scoring sessions are honest, not adversarial.** The scoring conversation is for capturing reality, not for blame. Honest low scores are fine; effort recognition happens elsewhere. + +--- + +## What 100% scores mean + +100% scores warrant scrutiny. + +**Possibilities.** + +- The OKR was sandbagged. The team set targets they were already on track to hit. +- The team had a great quarter. Sometimes hitting 100% reflects unusual progress; informative. +- The team is rounding up. The actual outcome was 0.85 but got rounded. +- Binary KRs that hit 1.0. A milestone-based KR that achieves the milestone is 1.0; this is not sandbagging. + +**The investigation.** + +- Compare the target to the historical trajectory. Was the target above what the metric would have done without focused effort? +- Compare the target to other teams setting similar OKRs. Was this target genuinely stretch? +- Look at the work the team did. Did the team push beyond their normal capacity, or did they hit the target on standard execution? + +**The interpretation.** Single-quarter 100% scores are not necessarily problematic. Repeated 100% scores across many KRs across multiple quarters are a sandbagging signal. The next OKR cycle should set targets above the prior quarter's actuals to prevent sandbagging compounding. + +--- + +## What 30% scores mean + +30% scores warrant scrutiny. + +**Possibilities.** + +- The OKR was fantasy. Targets had no realistic effort path; the team could not have hit them. +- Unexpected disruption. A market event, security incident, or priority shift consumed capacity that would have gone to the OKR. +- Mid-quarter deprioritization. The team chose to deprioritize this OKR for other work. +- Underperformance. The team did not execute well; the score reflects the execution gap. + +**The investigation.** + +- Was the target reachable? At setting time, could the team identify effort paths that would produce the target? +- What changed during the quarter that affected the trajectory? +- What did the team actually work on? Did effort match the OKR, or did effort go elsewhere? + +**The interpretation.** 30% scores are informative regardless of cause. Fantasy targets need recalibration in the next quarter. Disruption-driven misses inform what to plan around. Deprioritization-driven misses surface tension between OKRs and other work. Execution gaps surface team-capability or process issues. + +**The non-recovery.** Repeated 30% scores quarter after quarter signal that OKR design is failing. Either the org is consistently setting fantasy targets, or the team is consistently mismatched to its commitments. Investigate. + +--- + +## The compensation question + +OKRs work best when not directly tied to compensation. + +**The problem with compensation-coupling.** When OKRs determine bonuses or reviews, sandbagging incentives become severe. Teams set OKRs they know they can hit. The 60-70% target collapses to 95% target because nobody wants to risk their bonus on stretch. + +**Why decoupling works.** OKRs become genuine accountability infrastructure. The team can stretch without risking compensation. Honest scoring is safe. Misses produce learning rather than punishment. + +**Compensation alternatives.** + +- Compensation tied to overall performance (manager assessment, peer feedback, role expectations) rather than to OKR scores specifically. +- OKR scores inform performance review as one input among many, not as the dominant signal. +- Bonus structures based on company performance rather than team-OKR scores. + +**The transition for orgs already coupled.** Decoupling requires explicit communication. Teams need to trust that scoring honestly will not affect their bonuses. The transition can take 2-3 cycles before teams believe the decoupling is real. + +--- + +## Scoring formats + +How scoring sessions get run. + +**The format.** + +- Team meets at end of quarter (60-90 minutes). +- Each KR scored honestly. +- Each objective scored as the KR average. +- Discussion: what produced the scores, what worked, what did not. +- Output: published scores with brief context per OKR. + +**The discussion content.** + +- For high-scoring OKRs: was this stretch? What worked? What can be replicated? +- For low-scoring OKRs: what got in the way? What does the team need next quarter? +- For mid-scoring OKRs: where did the work land? What was the gap between target and actual? + +**The output.** Scores published to the team and stakeholders. Brief context per OKR. The published record informs the next quarter's setting and the org's broader OKR practice. + +--- + +## Scoring across multiple teams + +When multiple teams cascade to a company OKR, scoring composes. + +**The composition.** + +- Each team scores its KRs independently. +- The company OKR's score reflects the cumulative outcome (not the average of team scores). +- A company OKR can score high even if some contributing team OKRs scored low, depending on which contributions mattered most. + +**Worked example.** Company OKR: "Improve net new ARR through enterprise segment growth." + +- Sales team KR (close 8 enterprise deals): scored 0.85 (closed 7). +- Product team KR (enterprise-readiness foundations): scored 0.7 (achieved most foundations; SOC 2 in progress). +- Marketing team KR (enterprise-segment marketing campaigns): scored 0.5 (delayed launch). + +Company OKR score: depends on the actual ARR outcome, not the average of team scores. If ARR met the target despite the marketing delay (because sales over-delivered), the company OKR scores high. + +**The discipline.** Score outcomes, not averages of inputs. + +--- + +## Common scoring failures + +**Rounding up.** Systemic over-scoring through small individual rounds. + +**Effort-based scoring.** Scoring based on how hard the team worked rather than what was achieved. + +**Compensation-coupled scoring.** Sandbagging incentives produce 95%+ scores. + +**Avoidance of low scores.** Teams reluctant to score low; OKRs renamed or rewritten retroactively to avoid the miss. + +**Aggregate-of-input scoring.** Company OKR scored as average of team scores rather than as the actual outcome. + +**Scoring without context.** Scores published without the conditions that produced them. Lessons get lost. + +**One-quarter-at-a-time view.** Scoring evaluated only against the current quarter; trajectory over multiple quarters not surfaced. + +--- + +## Methodology-level choices that stay in the public skill + +The 0.0-1.0 scale and worked examples. The 60-70% target. Scoring honesty. What 100% and 30% scores mean. The compensation question. Scoring formats. Scoring across teams. Common scoring failures. + +## Implementation choices that stay internal + +Specific scoring tools and dashboards. Specific scoring-session facilitation formats. Specific compensation structures. The team's own conventions for context publishing. These vary by org. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md b/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md new file mode 100644 index 0000000..28ccaa7 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md @@ -0,0 +1,280 @@ +--- +name: onboarding-wizard-design +description: "Designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. Honest about tutorial-overload (dump everything upfront), skip-friendly-empty (skipped onboarding leads to abandoned product), and earned-progressive-disclosure (right things at the right moments) patterns. Triggers on onboarding wizard, product onboarding, first-run experience, signup flow, activation flow, FRX, time-to-value, ah-ha moment design. Also triggers when activation rates are low, when users skip onboarding and never return, when onboarding flows are being scoped for the first time, or when audience research shows users not finding key features." +category: growth-tooling +catalog_summary: "Designing first-run product onboarding wizards. Distinguishes tutorial-overload (dump everything upfront) from skip-friendly-empty (skipped onboarding leads to abandoned product) from earned-progressive-disclosure (right things at the right moments)" +display_order: 7 +--- + +# Onboarding Wizard Design + +A senior product marketing director's playbook for designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. The discipline of building an onboarding sequence the user actually completes. + +Most product onboarding wizards fail in one of two ways. They cram every feature into a 12-step intro the user has not earned the patience for. Or they offer a "skip onboarding" button so prominent that users skip into an empty product with no context, and then churn the next day because they never found the value. The activation rate is the metric that matters, and most wizards are optimizing for the wrong thing. + +The wizards that work do something different. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is balanced against staying engaged. The user reaches the ah-ha moment with a sense that the product respected their time. + +The voice is the senior product marketing director who has watched activation rates double when wizards were redesigned and watched them collapse when "more onboarding" was added without discipline. Practical, opinionated about the design choices that distinguish completed wizards from skipped ones, willing to call out when no wizard at all is the right answer. + +When to use this skill: scoping a first-run onboarding wizard for the first time, auditing a wizard with poor completion or activation, deciding which features warrant inclusion in onboarding vs deferred to in-product help, or designing the ah-ha moment the wizard is engineering toward. + +--- + +## What this skill covers + +This skill spans first-run product onboarding wizards. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access). This skill is post-signup product onboarding. Different phase, different audience state. +- `interactive-product-tour` is contextual help WITHIN the product, surfacing across the lifecycle. This skill is the sequential first-run experience. +- `chatbot-flow-design` is conversational help. This skill is non-conversational sequential setup. +- **`onboarding-wizard-design` (this skill)** is the post-signup wizard's structure, ah-ha moment design, progressive disclosure, skip mechanics, drop-off measurement. +- `pm-spec-writing` is the spec for engineers building the wizard. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams designing activation flows, agencies running activation work for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); in-product contextual tours (covered by `interactive-product-tour`); the engineering implementation; specific Userpilot/Userflow/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The wizard decision: when wizards earn vs when contextual help suffices + +Before designing the wizard, decide whether a wizard is the right tool. + +**Wizards earn investment when:** + +- The product has a meaningful setup step before value emerges. Connect a data source, invite a teammate, configure a workspace. Without setup, the product is empty; the wizard makes setup tractable. +- The ah-ha moment requires multiple actions in sequence. Single-action ah-ha moments (paste a URL, see a result) often work better with contextual prompts than with wizards. +- The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products. Some audiences (consumer, frictionless tools) reject wizard friction. +- The team can maintain the wizard. Wizards decay as the product evolves; without maintenance commitment, the wizard becomes a liability. + +**Wizards do NOT earn investment when:** + +- The product reaches value immediately. Single-input tools, simple consumer products. A wizard adds friction without lift. +- Contextual help would suffice. Tooltips, in-feature hints, and progressive in-product education sometimes serve better than upfront wizards. +- The audience expects no friction. Some audiences abandon at any wizard; meet them where they are. +- The team cannot maintain the wizard alongside product changes. Stale wizards point to deprecated features; users hit broken steps. + +The decision is not "should we have an onboarding wizard"; it is "is the wizard the right tool for this specific product and audience." + +Detail in [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md). + +--- + +## Tutorial-overload vs skip-friendly-empty vs earned-progressive-disclosure + +The keystone framing. + +**Tutorial-overload.** Every feature explained in a 12-step intro before the user has touched the product. Cognitive overload. Users skip if they can; abandon if they cannot. Cost: the wizard's design effort produces a sequence almost nobody completes; activation rate suffers because the user did not reach the value-giving moment. + +**Skip-friendly-empty.** "Skip onboarding" button at every step, so prominent that users always take it. Users skip; arrive at an empty product with no context; churn within hours. Cost: activation rate falls off a cliff because users never set up the basics that make the product functional. + +**Earned-progressive-disclosure.** Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is friction-balanced against staying engaged (e.g., skip places the user in a partially-set-up state with clear callouts to complete setup later). Cost: design effort is significant; activation rate often climbs significantly as a result. + +The litmus test. Watch a new user complete (or skip) the wizard. Did they reach a moment where the product visibly demonstrated value within their first session? If yes, the wizard is earned-progressive-disclosure. If they completed every step but never reached value, tutorial-overload. If they skipped and never returned, skip-friendly-empty. + +--- + +## Step architecture: what belongs in each step, sequence logic + +The structure that makes wizards actually work. + +**The principle.** Each step should move the user one step closer to value. Steps that do not should be cut. + +**Common step patterns.** + +- **Welcome and orientation.** Quick context-setting, often skippable. Sets expectations for what the wizard will do. +- **Identity and account context.** Who are you, what's your role, what brought you here. Often used to personalize subsequent steps. +- **Critical setup step.** The one thing the product cannot work without (connect data source, invite teammates, set primary use case). This is often where wizards justify their existence. +- **First-action step.** Get the user to take a meaningful action that produces visible result. The ah-ha moment lives here or right after. +- **Configuration deferral.** Surface the things that can be set up later but are commonly needed; let the user defer with a clear path back. +- **Confirmation and next steps.** Recap what was set up; surface what to do next; route to in-product home. + +**Step coherence test.** Each step should answer: did this step move the user closer to value? Steps that exist for completeness or feature-pride should be cut. + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## The ah-ha moment design + +What the wizard is actually trying to engineer. + +**The principle.** The ah-ha moment is the moment the user feels "oh, this is what the product does for me." The wizard's structure should engineer toward that moment. + +**Identifying the ah-ha moment.** + +- It is the visible demonstration of value, not just feature explanation. +- It is action-tied, not knowledge-tied. The user did something and saw the result. +- It is single-shot. One clear moment, not a checklist of moments. +- It is honest. The user genuinely got value; not a contrived demo. + +**Design implications.** + +- The wizard's path should converge on the ah-ha moment. Steps that do not contribute should be deferred or cut. +- The ah-ah moment should appear within the user's first session, ideally within 5-10 minutes of signup. Longer time-to-value correlates with churn. +- The ah-ha moment differs by audience. The B2B admin's ah-ha moment differs from the end-user's. Wizards may need to differentiate. + +**Common ah-ha moment patterns.** + +- **First successful query/output.** The user ran something against their data and saw a useful result. +- **First meaningful collaboration moment.** The user shared something with a teammate and saw the response. +- **First saved configuration.** The user set up something they will return to. +- **First value-demonstrating insight.** The user saw a metric, recommendation, or pattern that surprised them. + +Detail in [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md). + +--- + +## Progressive disclosure patterns + +How to surface only what is needed at each step. + +**The principle.** Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +**Pattern A: Default-heavy.** Each step has smart defaults. The user can accept or override. Most users accept; advanced users override. Reduces cognitive load. + +**Pattern B: Required-now, optional-later.** Required fields surface in the wizard; optional configuration surfaces in-product after activation. The wizard stays focused. + +**Pattern C: Expand-on-demand.** Sections collapsed by default; the user expands if interested. Rare; works when the user has agency to explore. + +**Pattern D: Branching.** Different users see different steps based on earlier answers. Powerful but adds maintenance complexity. + +The discipline. Each piece of information shown in the wizard must justify its inclusion. Decorative information adds friction; surface it later. + +Detail in [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md). + +--- + +## Skip and resume mechanics + +When users skip, where they land. When they resume, what they see. + +**The skip principle.** Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +**Skip patterns.** + +- **Soft skip with context.** "Skip for now" deposits the user into a partially-set-up state with clear callouts to complete deferred setup. +- **Skip-and-defer.** Skipped steps are queued for later in-product prompts. +- **Skip-with-warning.** "Skipping setup will limit your experience to X. Continue?" Honest about consequences. +- **No skip.** For wizards that absolutely require completion (compliance forms, paid signups). Use sparingly. + +**Resume patterns.** + +- **Auto-resume on next login.** The user lands at the step they left. +- **Manual resume from in-product entry.** A persistent "Complete setup" surface that returns the user to the wizard. +- **Soft resume.** Wizard fades out as the user completes equivalent actions in-product naturally. + +**The skip-friendly-empty failure.** Skip is too prominent and consequence-free; the user lands in an unconfigured product and has no path back. Activation collapses. + +**The cure.** Skip is honest about consequences and offers a path back. The user who skips knows what they skipped. + +Detail in [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon the wizard, and how to fix it. + +**Per-step instrumentation.** Track step start, step completion, step abandonment for every step. The metrics inform every other improvement. + +**Common drop-off patterns.** + +- **First-step drop-off.** User landed on the wizard, looked at it, left. Often signals the wizard's value proposition is not clear or the audience expected no wizard. +- **Mid-wizard drop-off.** User abandoned mid-process. Audit the specific step; field count, sensitive info, unclear progress. +- **Skip-everything drop-off.** User skipped every available step. Either the wizard is not earning its time or the skip is too prominent. + +**Remediation patterns.** + +- First-step drop-off: clarify the wizard's purpose; reduce upfront fields; consider whether the wizard is needed at all. +- Mid-wizard drop-off: audit the high-drop step; reduce friction; reconsider whether that step belongs in the wizard. +- Skip-everything drop-off: rebalance skip prominence; consider whether the wizard should be replaced with contextual prompts. + +**The instrumentation requirement.** Without per-step tracking, drop-off remediation is guesswork. Set up tracking before launch. + +Detail in [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md). + +--- + +## Wizard variations by user type + +Different users may need different wizards. + +**The admin vs end-user distinction.** Admins set up the workspace; end-users start using it. Wizards aimed at both fail both. Differentiated wizards serve each. + +**The technical vs non-technical distinction.** Technical users skip explanations; non-technical users need them. The wizard's tone and depth should match. + +**The size-of-team distinction.** Solo founders have different setup needs than 50-person teams. Wizards may branch. + +**Differentiation patterns.** + +- **Role-based branching.** First step asks role; subsequent steps adapt. +- **Use-case-based branching.** First step asks use case; wizard tailors. +- **Size-based branching.** Solo, team, enterprise paths differ. + +**The over-differentiated trap.** Too many variants produce unmaintainable wizards. Most wizards work with 2-3 variants at most. + +Detail in [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md). + +- "Activation rate is low; completion rate is high." Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. +- "Skip rate is over 50 percent." Either the wizard is not earning its time or skip is too prominent. Audit both. +- "Users complete the wizard then abandon the product within 24 hours." Time-to-value too long; ah-ha moment not in first session. +- "Wizard works for new users; existing users hit broken steps." Wizard not maintained alongside product; deprecated features still in flow. +- "Different segments complete at very different rates." Audience-fit varies; consider role-based or use-case-based branching. +- "Mobile completion is half of desktop." Mobile UX of the wizard broken. +- "We added more onboarding steps; activation went down." Tutorial-overload pattern; more is not better. +- "Skip mechanics work but users do not return to complete setup." Skip-and-defer not working; in-product prompts to return are missing or ignored. +- "Wizard analytics broke after the last release." Instrumentation drift; track and refresh. + +--- + +## The framework: 12 considerations for onboarding wizard design + +When designing or auditing an onboarding wizard, walk these 12 considerations. + +1. **The wizard decision.** Is a wizard the right tool, or do contextual prompts suffice? +2. **Earned-progressive-disclosure, not tutorial-overload or skip-friendly-empty.** Each step earns one step closer to value. +3. **Step architecture sound.** Each step moves the user closer to value; non-contributing steps cut. +4. **The ah-ha moment engineered.** Single visible value moment, action-tied, in the first session. +5. **Progressive disclosure applied.** Show only what is needed now; defer the rest. +6. **Skip mechanics honest.** Skip exists but does not produce an empty product. +7. **Resume mechanics work.** Skipped users have a path back; instrumented for follow-through. +8. **Drop-off measurement instrumented.** Per-step tracking from launch. +9. **User-type variations balanced.** 2-3 variants max; over-differentiation avoided. +10. **Mobile parity.** Wizard works on the devices the audience uses. +11. **Activation as success metric.** Not just completion rate; the metric is post-wizard product engagement. +12. **Maintenance discipline.** Wizard updated alongside product changes; quarterly audit. + +The output of the framework is an onboarding wizard that gets users to the ah-ha moment, respects their time, and produces activation rates the team can defend. + +--- + +## Reference files + +- [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md) - When wizards earn the build vs when contextual help suffices. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs in each step. Sequence logic. Step coherence test. +- [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md) - Identifying the ah-ha moment; designing the wizard to converge on it. +- [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md) - Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. +- [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md) - Skip patterns and resume patterns. The skip-friendly-empty failure. +- [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md) - Per-step instrumentation. Common drop-off patterns and remediation. +- [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md) - Admin vs end-user, technical vs non-technical, size-based branching. +- [`references/wizard-anti-patterns.md`](references/wizard-anti-patterns.md) - The patterns that look like onboarding but degrade activation. +- [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: wizards earn the user's first session + +The onboarding wizards that work as compounding assets are the ones that get the user to value within their first session. Not because the wizard had every feature explained. Not because the wizard was skipped quickly. Because the wizard engineered the ah-ha moment, respected the user's time, and surfaced the right thing at the right moment. + +That is the bar. Below the bar are tutorial-overload (everything upfront, nobody completes) and skip-friendly-empty (skip too prominent, nobody activates). Above the bar are earned-progressive-disclosure wizards where each step earns the user one step closer to value, skip is honest about consequences, and the activation metric reflects the wizard's actual job. + +The discipline is in the design choices. The decision to build a wizard at all, or defer to contextual help. The step architecture that converges on the ah-ha moment. The progressive disclosure that surfaces the right thing at the right moment. The skip mechanics that protect the user from an empty product. The drop-off instrumentation that informs ongoing improvement. The maintenance cadence that keeps the wizard in sync with the product it represents. + +When in doubt, ask: did the user reach the ah-ha moment in their first session, and did the wizard help or hinder that? If yes to the first and helped on the second, the wizard earned its build. If no to either, redesign. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md new file mode 100644 index 0000000..0ca8f3e --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md @@ -0,0 +1,167 @@ +# Ah-ha moment engineering + +Identifying the ah-ha moment; designing the wizard to converge on it. The single visible moment when the user feels "oh, this is what the product does for me." + +The wizard's job is not completion. It is engineering the ah-ha moment within the user's first session. Without an identifiable ah-ha moment, the wizard has nothing to engineer toward; the result is a sequence that completes without producing activation. + +--- + +## The ah-ha principle + +The ah-ha moment is action-tied, single-shot, and visible. The user did something and saw the value the product promised. The wizard's structure should make that moment likely within the first session. + +**The win.** A new user finishes the wizard and immediately sees their first dashboard with their actual data, with a number that surprises them in a useful way. They get it. + +**The fail.** The user finishes the wizard with a tour of features but never sees the product produce something specifically for them. They completed the wizard; they did not activate. + +--- + +## Identifying the ah-ha moment + +The hardest design step is also the most upstream. + +**Methods.** + +- **Customer research.** Interview activated users (those who returned and engaged) about the moment they felt the product clicked. Patterns emerge. +- **Usage analysis.** Compare cohorts that activated vs cohorts that churned. What action did the activated cohort take that the churned cohort did not? +- **Sales-call mining.** Sales conversations often surface the moment prospects say "now I get it." That moment, in-product, is the ah-ha moment. + +**Signals of a real ah-ha moment.** + +- It is action-tied (the user did something), not knowledge-tied (the user learned something). +- It is single-shot (one specific moment), not a checklist of moments. +- It is visible (the user saw the result), not internal (the user felt understanding). +- It is honest (the user got real value), not contrived (a demo with fake data). + +If the team cannot articulate the ah-ha moment, that is the design problem to solve before building the wizard. + +--- + +## Common ah-ha moment patterns + +By product type. + +**Analytics products.** First successful query against the user's actual data. Not a demo dataset; their data, their result. + +**Collaboration products.** First meaningful interaction with a teammate. A shared comment, a delegated task, a thread that produces a decision. + +**Content products.** First saved item the user returns to. The content was useful enough to revisit. + +**Tooling products.** First completed task that would have taken longer without the tool. The time savings is visible. + +**Marketplace products.** First successful match. Buyer found a seller; seller got a lead. + +**Configurator products.** First saved configuration. The user committed to a setup they want to see again. + +The ah-ha moment varies by product. The discipline (action-tied, single-shot, visible, honest) holds. + +--- + +## Designing the wizard around the ah-ha moment + +The wizard's path should converge on the moment. + +**Step 1: identify the prerequisites.** What does the user need before the ah-ha moment can happen? Connect data, invite teammate, configure workspace. Those steps are mandatory. + +**Step 2: identify the path.** What sequence of actions leads to the moment? The wizard's steps mirror that sequence. + +**Step 3: identify the friction.** What can break the path? Missing inputs, ambiguous decisions, validation errors. The wizard should pre-empt or smooth those. + +**Step 4: place the ah-ha moment intentionally.** The moment should appear at step 3-5 of the wizard, not after a 10-step setup. Earlier is better; aim for the user's first session, ideally first 5-10 minutes. + +--- + +## Time-to-value as design constraint + +The shorter the time to ah-ha, the higher the activation rate. + +**The benchmark.** First session ah-ha moment correlates with strong activation. Multi-session ah-ha (user has to come back) correlates with moderate activation. Multi-day ah-ha (user has to wait or work for it) correlates with poor activation. + +**The design implication.** If the ah-ha moment naturally takes hours or days (e.g., AI training, audit results), the wizard needs an interim ah-ha, something visible the user can see in their first session that signals the eventual ah-ha is coming. + +**Examples.** + +- AI product where training takes 24 hours: interim ah-ha is "see how your data looks; we will message you when training is done." +- Audit product where results take 48 hours: interim ah-ha is "see what we are auditing; preview a partial result." + +The user's first session should produce something visible and meaningful, even if the full ah-ha comes later. + +--- + +## The ah-ha moment for different audiences + +Different users may need different moments. + +**Admin vs end-user.** The admin's ah-ha moment may be configuration-related ("the workspace is set up, the team can use it"). The end-user's ah-ha moment is in-product engagement ("I did the thing I came to do"). Wizards may differentiate. + +**Technical vs non-technical.** Technical users often want depth (see the API work, see the integration succeed). Non-technical users want outcome (see the result, no API). Different ah-ha moments. + +**Solo vs team.** Solo users often want individual productivity. Team users want collaboration moments. The wizard's path may differ. + +The discipline. Identify the ah-ha moment per relevant audience segment. Wizards may branch based on segment. + +--- + +## Anti-patterns in ah-ha moment design + +**Tutorial-as-ah-ha.** Treating "learned about the features" as activation. The user knows what the product does but has not seen it do something specifically for them. Knowledge-tied, not action-tied; not real activation. + +**Demo-as-ah-ha.** Showing a polished demo that does not use the user's data. The user sees what is possible but not what is true for them. Contrived; activation does not stick. + +**Multi-moment ah-ha.** Treating "see all features" as the moment. No single moment lands; the user feels they need to see everything before getting it. + +**Delayed ah-ha.** The ah-ha moment lands two sessions in. The user does not return for the second session. + +**Theoretical ah-ha.** "When users connect their data and run their first analysis, they will love it." Belief without evidence. Without research validating the moment, the wizard is built on theory. + +--- + +## Measuring ah-ha moment effectiveness + +Activation rate is the metric. Completion rate is leading indicator at best. + +**Activation as the metric.** Define activation explicitly (e.g., user returned within 7 days and engaged with feature X). Track it. + +**Wizard completion as leading indicator.** Useful but insufficient. A high completion rate with low activation rate signals the wizard's ah-ha moment is wrong. + +**Time-to-activation.** Hours from signup to activation. Shorter correlates with retention. + +**Per-segment activation.** Different segments may have different activation rates. Surfaces audience-fit issues. + +--- + +## Validating the ah-ha moment + +Once defined, validate. + +**Cohort analysis.** Compare cohorts that hit the moment vs cohorts that did not. Did hitting it correlate with retention? If not, the moment is wrong. + +**User research.** Interview users who hit the moment. Did they recognize it as the ah-ha moment, or just another step? + +**A/B testing.** Test wizard variations that converge on the moment vs variations that do not. Activation rate difference quantifies the moment's value. + +The discipline. The ah-ha moment is a hypothesis until validated. Treat it as such. + +--- + +## Common ah-ha moment failures + +**No defined moment.** Wizard built without identifying the moment; result is decorative. + +**Wrong moment defined.** Moment defined based on intuition; cohort analysis shows it does not predict retention. + +**Moment too late.** Moment lands after multiple sessions; users do not return. + +**Moment requires too much work.** Moment is real but the user has to do significant setup; drop-off before the moment. + +**Moment varies wildly by segment.** Single-moment design fails for an audience with different needs. + +--- + +## Methodology-level choices that stay in the public skill + +The ah-ha principle. Methods for identifying the moment. Common patterns by product type. Designing the wizard around the moment. Time-to-value as design constraint. Audience-specific moments. Anti-patterns. Measurement. Validation. Common failures. + +## Implementation choices that stay internal + +Specific ah-ha moments for specific products. Specific cohort definitions. Specific research methodologies. The team's research capacity. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md new file mode 100644 index 0000000..63b23a1 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md @@ -0,0 +1,171 @@ +# Common onboarding failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "activation is low" or "users skip the wizard" or "we cannot tell if the wizard works." + +--- + +## "Activation rate is low; completion rate is high." + +**The diagnosis.** Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. + +**The cure.** Redesign around the ah-ha moment (`references/ah-ha-moment-engineering.md`). Define activation explicitly; verify the wizard produces it; cut steps that do not contribute. + +--- + +## "Skip rate is over 50 percent." + +**The diagnosis.** Either the wizard is not earning its time or skip is too prominent. Audit both. + +**The cure.** Audit step value (each step contribute to ah-ha?). Audit skip prominence (skip too easy?). Detail in `references/step-architecture-patterns.md` and `references/skip-and-resume-mechanics.md`. + +--- + +## "Users complete the wizard then abandon the product within 24 hours." + +**The diagnosis.** Time-to-value too long; ah-ha moment not in first session. + +**The cure.** Move the ah-ha moment earlier. If the moment naturally takes longer, design an interim ah-ha for the first session. + +--- + +## "Wizard works for new users; existing users hit broken steps." + +**The diagnosis.** Wizard not maintained alongside product; deprecated features still in flow. + +**The cure.** Maintenance discipline. Quarterly audit. Product changes trigger wizard updates as part of the change. + +--- + +## "Different segments complete at very different rates." + +**The diagnosis.** Audience-fit varies; consider role-based or use-case-based branching. + +**The cure.** Differentiate by segment where the differentiation produces materially different paths. Detail in `references/user-type-variation-patterns.md`. + +--- + +## "Mobile completion is half of desktop." + +**The diagnosis.** Mobile UX broken or compromised. + +**The cure.** Mobile-first design and testing. Test on actual devices. + +--- + +## "We added more onboarding steps; activation went down." + +**The diagnosis.** Tutorial-overload pattern; more is not better. + +**The cure.** Cut steps that do not contribute to the ah-ha moment. Defer feature explanations to in-product tours. + +--- + +## "Skip mechanics work but users do not return to complete setup." + +**The diagnosis.** Skip-and-defer not working; in-product prompts to return are missing or ignored. + +**The cure.** Audit prompt logic. Ensure prompts trigger at moments of relevance, with frequency limits, and route to the right setup flow. + +--- + +## "Wizard analytics broke after the last release." + +**The diagnosis.** Instrumentation drift; track and refresh. + +**The cure.** Verify analytics after every release. Add a smoke test to the deployment process. + +--- + +## "We A/B tested wizard length; conversion did not change." + +**The diagnosis.** Length alone may not be the issue. Could be step content, skip prominence, or the underlying ah-ha definition. + +**The cure.** Test variables that matter (skip prominence, ah-ha placement, step coherence). Length is one variable; isolate the right one. + +--- + +## "Activation looks good; retention is poor." + +**The diagnosis.** Activation metric may be wrong. Users hit a moment that does not predict retention. + +**The cure.** Validate the ah-ha moment with cohort analysis. Did users who hit it actually retain? If not, the moment is wrong. + +--- + +## "We cannot tell which step needs work." + +**The diagnosis.** Aggregate completion tracked but not per-step. + +**The cure.** Per-step instrumentation (`references/drop-off-measurement-templates.md`). + +--- + +## "Wizard worked great at launch; activation has declined." + +**The diagnosis.** Decay. Audience shifted; product evolved; references stale. + +**The cure.** Quarterly audit. Update what has decayed. + +--- + +## "Sales says the leads from signup are different than they used to be." + +**The diagnosis.** Audience composition shifted; the wizard's segmentation may be obsolete. + +**The cure.** Update branching or differentiation. Audit the audiences arriving and what they need. + +--- + +## "We built a wizard; the team thinks the bot would have been better." + +**The diagnosis.** Possibly. Different products warrant different activation tools. + +**The cure.** Validate. If the bot would serve better, test or migrate. The wizard format is not always the right tool. + +--- + +## "Power users complete the wizard then abandon." + +**The diagnosis.** Wizard does not respect power users' speed. They want to skip ahead. + +**The cure.** Add power-user paths. Skip should be available; advanced configuration should be findable post-wizard. + +--- + +## "We localized the wizard; activation in some locales dropped." + +**The diagnosis.** Translation quality, cultural mismatch, or audience-fit specific to the locale. + +**The cure.** Audit translation. Audit cultural assumptions. Verify audience-fit per locale. + +--- + +## "The wizard works on Chrome; it crashes on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. + +**The cure.** Cross-browser, cross-device testing. + +--- + +## The pattern across failures + +Most onboarding wizard failures fall into one of three patterns. + +**Pattern 1: The wizard does not engineer the ah-ha moment.** Tutorial-overload, decoration steps, demo-as-ah-ha, late ah-ha. The fix is to redefine and converge on the moment. + +**Pattern 2: The wizard does not match the audience.** Skip-friendly-empty, validation-strict, mobile-broken, segment mismatch. The fix is matching the wizard to where the audience actually is. + +**Pattern 3: The wizard decays.** Stale references, broken steps, analytics drift. The fix is maintenance discipline. + +The metric pattern: wizard failures often look fine on completion alone. The signal is in activation, retention, drop-off per step. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (ah-ha, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md new file mode 100644 index 0000000..6012f5a --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md @@ -0,0 +1,230 @@ +# Drop-off measurement templates + +Per-step instrumentation. Common drop-off patterns and remediation. Without per-step tracking, drop-off remediation is guesswork. + +The metrics inform every other improvement. Set up tracking before the wizard launches. + +--- + +## The instrumentation requirement + +Track step start, step completion, step abandonment for every step. + +**Minimum tracking.** + +- Wizard start (user landed on step 1). +- Step start (user reached step N). +- Step completion (user finished step N, advanced to step N+1). +- Step abandonment (user left without completing). +- Wizard completion (user finished all steps, reached end). +- Skip events (per step where applicable). + +**Derived metrics.** + +- Step completion rate (users who reached step / users who completed it). +- Step skip rate (users who reached step / users who skipped). +- Funnel completion rate (started wizard / finished). +- Time per step. + +Without this data, every diagnostic is theoretical. + +--- + +## Common drop-off points + +Three patterns recur across onboarding wizards. + +**First-step drop-off.** User landed on the wizard, looked at it, left. + +Common causes. +- Wizard length visible upfront and intimidating. +- Value proposition unclear. +- Audience expected no wizard. +- Mobile UX broken. + +**Mid-wizard drop-off.** User abandoned mid-process. + +Common causes. +- Specific step too demanding (high field count, sensitive question, ambiguous input). +- Cumulative fatigue (wizard too long). +- Friction at validation or backend processing. +- Time pressure (user expected faster). + +**Late-step drop-off.** User completed most steps but abandoned near the end. + +Common causes. +- Final step requires information the user does not have. +- Wizard length felt longer than expected. +- Submission anxiety (user does not know what happens after). + +--- + +## Remediation patterns + +For each drop-off pattern. + +**First-step drop-off.** + +- Reduce visible upfront length (defer to multi-screen or progressive disclosure). +- Clarify value ("This 5-step setup connects your data and shows your first insight"). +- Reduce step-1 cognitive load (start with the easiest step). +- Test mobile experience. + +**Mid-wizard drop-off.** + +- Audit the high-drop step. Is it too demanding? Sensitive? Ambiguous? +- Reduce field count or split into multiple smaller steps. +- Add progress indicator if missing. +- Add reassurance copy if the step is sensitive. +- Reword ambiguous fields. + +**Late-step drop-off.** + +- Reduce final-step requirements (move some fields earlier). +- Add post-submission preview ("After this, we'll set up your dashboard"). +- Add explicit confirmation step before submission. + +--- + +## Drop-off and skip distinction + +Skip is intentional; drop-off is involuntary. Track them separately. + +**Skip metrics.** + +- Skip rate per step (users who reached step / users who skipped). +- Resume rate per skip (users who skipped step / users who returned to complete). +- Activation rate per skip (users who skipped specific steps and still activated). + +**Drop-off metrics.** + +- Abandonment rate per step (users who reached step / users who left without completing or skipping). +- Time-to-abandonment. +- Re-engagement rate (users who came back to retry the wizard). + +**The diagnostic value.** Skip suggests the user does not value this step right now. Drop-off suggests the wizard failed to engage the user. + +--- + +## Tracking conditional paths + +Wizards with branching logic have multiple paths. + +**Per-path tracking.** + +- Tag each user's path through the wizard. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +**Path-specific remediation.** A path that drops off at step 4 may need step-4 redesign for users on that path. Other paths may not need attention. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +**Segment-level tracking.** + +- Tag users by source, device, role, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +**Common segment patterns.** + +- Mobile users drop off more on long steps. +- Paid-traffic users drop off earlier than organic. +- New users drop off more than returning visitors. + +**Remediation by segment.** Sometimes the right answer is segment-specific (e.g., shorter wizard variant for mobile). + +--- + +## Time-to-completion tracking + +How long the wizard takes. + +**Total time distribution.** Plot the time-to-complete distribution. Median, p25, p75, p95. + +**Per-step time.** Which steps take longest? Are they earning the time? + +**Patterns.** + +- Wizards taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Long-tail completers (p95) often signal usability issues. + +**Remediation by time.** Wizards or steps taking too long should be split or simplified. + +--- + +## A/B testing wizards + +Test changes rigorously. + +**Test design.** Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall activation. + +**Common test types.** + +- Wizard length (shorter vs longer). +- Step ordering (different sequences). +- Field count per step. +- Skip prominence. +- Help text presence/absence. +- Default-heavy vs required-now-optional-later. + +**Test discipline.** One variable at a time. Long enough to capture activation signal. Measure both wizard metrics and downstream activation. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +**The signal.** Wrong audience self-selecting out. A wizard that filters out audiences who would not activate anyway is doing its job. + +**The discipline.** Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream activation metric reveals which. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. + +--- + +## Wizard analytics dashboard + +What to surface. + +**Per-step funnel.** Start rate, completion rate, drop-off rate per step. + +**Skip rates per step.** Where skip is enabled. + +**Time-to-completion distribution.** With percentile breakdown. + +**Activation rate per cohort.** Wizard completers vs non-completers; activation by skip pattern. + +**Trend over time.** Have the metrics changed since the last release? + +--- + +## Common analytics failures + +**No instrumentation.** Wizard launched without tracking; quality is invisible. + +**Aggregate-only tracking.** Wizard completion tracked but not per-step; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; field renames or step changes broke the tracking. + +**Skip and drop-off conflated.** Cannot distinguish intentional skip from involuntary drop-off. + +**Activation not tracked.** Wizard metrics in isolation; cannot tell if completion correlates with activation. + +**No segment-level data.** Aggregate hides segment-specific issues. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points and causes. Remediation patterns. Drop-off vs skip distinction. Tracking conditional paths. Per-segment analytics. Time-to-completion. A/B testing. When drop-off is signal. Dashboard composition. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific wizards. Specific tooling. Specific A/B test designs. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md new file mode 100644 index 0000000..8b831d9 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md @@ -0,0 +1,238 @@ +# Progressive disclosure patterns + +Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Wizards that try to show everything become tutorial-overload. Wizards that defer everything become skip-friendly-empty. Progressive disclosure is the discipline that surfaces what matters when it matters. + +--- + +## Pattern A: Default-heavy + +Each step has smart defaults; the user can accept or override. + +**How it works.** + +- Inputs come pre-filled with sensible defaults. +- The user reviews; accepts most; overrides where their context differs. +- Most users move through quickly; advanced users find the override controls. + +**Strengths.** + +- Reduces cognitive load. +- Faster completion. +- Users without strong preferences proceed; users with strong preferences customize. + +**Weaknesses.** + +- Defaults must be honest. Bias-flattering defaults erode trust. +- Defaults need maintenance as the product evolves. + +**When to use.** Default for most wizards. Smart defaults reduce friction without removing customization. + +--- + +## Pattern B: Required-now, optional-later + +Required fields surface in the wizard; optional configuration surfaces in-product after activation. + +**How it works.** + +- Each step has only required fields. +- Optional configuration appears as in-product prompts after the wizard. +- The wizard stays focused on minimum-viable activation. + +**Strengths.** + +- Shortest possible wizard. +- Optional configuration happens when the user has product context. +- Activation rate improves; configuration completeness rises. + +**Weaknesses.** + +- Requires in-product prompt infrastructure for the deferred configuration. +- Some users may never return to complete deferred setup. + +**When to use.** When the wizard has accumulated optional fields that bloat completion time. The strongest pattern for trimming bloated wizards. + +--- + +## Pattern C: Expand-on-demand + +Sections collapsed by default; the user expands if interested. + +**How it works.** + +- Step shows the minimal interface. +- An "advanced options" or "more details" toggle expands additional fields. +- Most users skip; advanced users explore. + +**Strengths.** + +- Surfaces depth without forcing it. +- Power users get what they need. + +**Weaknesses.** + +- Risk of hiding important fields the user does not realize they need. +- Adds visual complexity to the step. + +**When to use.** When some users genuinely need depth that most do not. Use sparingly; default-heavy plus required-now-optional-later usually serves better. + +--- + +## Pattern D: Branching + +Different users see different steps based on earlier answers. + +**How it works.** + +- Step 1 asks about role, use case, or context. +- Subsequent steps adapt based on the answer. +- Different users effectively complete different wizards. + +**Strengths.** + +- Each user sees only steps that apply to them. +- Wizard feels personalized. + +**Weaknesses.** + +- Significant maintenance complexity. +- Testing burden grows (more paths). +- Analytics must accommodate variable paths. + +**When to use.** When the audience genuinely splits into segments with materially different needs. 2-3 branches max; more becomes unmaintainable. + +--- + +## Pattern E: Hybrid + +Combining patterns. Default-heavy plus required-now-optional-later plus a single branch for major audience split. + +**Strengths.** + +- Reduces friction at multiple levels. +- Different users benefit from different mechanisms. + +**Weaknesses.** + +- Design and maintenance complexity. + +**When to use.** When the wizard's audience and content warrant the combination. Most production wizards land in some hybrid configuration. + +--- + +## What to surface vs defer + +The decision per field. + +**Surface in the wizard.** + +- Fields without which the product cannot work for the user. +- Fields that affect the ah-ha moment. +- Fields that branch downstream steps. +- Fields that personalize the immediate experience. + +**Defer to in-product.** + +- Fields that affect long-term configuration but not immediate value. +- Fields that benefit from product context (the user understands what they are configuring). +- Fields that are commonly skipped anyway; surface them at moments of relevance. + +**The deferable test.** For each wizard field, ask: would the user be better served setting this up after seeing the product, with relevant context? If yes, defer. + +--- + +## Default discipline + +Defaults are powerful. They must be honest. + +**Honest defaults.** + +- Defaults reflect the typical case for the audience. +- Defaults are sourced (from cohort data, common practice, or team judgment). +- Defaults can be overridden visibly. + +**Bias-flattering defaults.** + +- Defaults set to produce favorable signup metrics (cheap plan pre-selected, opt-in checked) without disclosure. +- Defaults that misrepresent the user's real choice. +- Defaults that change over time without user notice. + +The discipline. Defaults reduce friction; they should not extract data or commitment the user did not consent to. + +--- + +## Information density per step + +How much to show. + +**Minimal density.** Just the required fields plus a sentence of context. Shortest, fastest. + +**Moderate density.** Required fields plus brief explanation plus optional toggle. Balanced. + +**Heavy density.** Multiple sections, expandables, detailed help text. Most cognitive load. + +The right density depends on the audience and the step's complexity. Default to minimal; add density only when the step's complexity warrants it. + +--- + +## Help text discipline + +When to include explanatory text. + +**Strong help patterns.** + +- Inline tooltip on non-obvious fields. +- One-sentence explanation per step ("we use this to tailor your dashboard"). +- Examples for fields where the format is ambiguous. + +**Weak help patterns.** + +- Long help text on every field. +- Help text that is marketing rather than explanation. +- Help text that explains things the user already knows. + +The discipline. Help text earns its inclusion when it reduces friction. Help text for the sake of completeness adds clutter. + +--- + +## Mobile considerations + +Progressive disclosure on mobile. + +**Mobile-first defaults.** Default values matter more on mobile because typing is harder. + +**Single question per screen.** Mobile screens are small; multi-field steps cramp. + +**Touch-friendly toggles.** Expand/collapse must be touch-targetable. + +**Minimal help text.** Mobile users skim; long help text is dismissed. + +--- + +## Common progressive disclosure failures + +**No defaults.** Every field blank; the user does work the wizard could have done. + +**Bias-flattering defaults.** Defaults extract commitment the user did not consent to. + +**Over-disclosed.** Every field surfaced; tutorial-overload. + +**Under-disclosed.** Important fields hidden; the user finishes the wizard with a misconfigured product. + +**Branching without need.** Branches that do not produce materially different paths add complexity without benefit. + +**Help text bloat.** Every field has a paragraph of explanation; cognitive load climbs. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns (default-heavy, required-now-optional-later, expand-on-demand, branching, hybrid). Strengths, weaknesses, when-to-use guidance. What to surface vs defer. Default discipline. Information density. Help text discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific wizards. Specific help copy in brand voice. Specific tooling for progressive disclosure. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md new file mode 100644 index 0000000..b41edba --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md @@ -0,0 +1,205 @@ +# Skip and resume mechanics + +Skip patterns and resume patterns. The skip-friendly-empty failure. Honest skip, honest resume. + +When users skip, where they land. When they resume, what they see. Skip mechanics done well let users escape without abandoning; done poorly, they produce skip-friendly-empty wizards where users skip into a useless product and churn. + +--- + +## The skip principle + +Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +**The win.** A user clicks "Skip for now" on a setup step. The product places them in a partially-configured state with a clear callout: "Your workspace needs a connected data source to show insights. Set it up here when you're ready." The user understands; engages later. + +**The fail (skip-friendly-empty).** A user clicks "Skip" on every step. The product places them in an empty state with no context; the user does not know what to do; they leave and never return. + +The discipline. Skip exists, but skip is consequence-honest and recoverable. + +--- + +## Skip patterns + +Common patterns for offering skip. + +**Pattern A: Soft skip with context.** + +How it works. The skip option is available but explains what gets deferred. "Skip for now; we will remind you to connect your data source later." + +When to use. Most wizards. Honest about the consequence; provides a path back. + +**Pattern B: Skip-and-defer.** + +How it works. Skipped steps are queued for later in-product prompts. The wizard does not require completion; the prompts handle re-engagement. + +When to use. When the wizard would otherwise be too long; defer everything that can be deferred. + +**Pattern C: Skip-with-warning.** + +How it works. Skipping triggers an honest warning. "Skipping setup means you won't see [X] until you complete it. Continue?" + +When to use. When skipping has real consequences the user should know about. Use sparingly; warnings on every step desensitize. + +**Pattern D: No skip.** + +How it works. The step must be completed. No skip option. + +When to use. For wizards that absolutely require completion (compliance forms, paid signups, regulatory required steps). Use sparingly; users who cannot skip and cannot complete leave instead. + +--- + +## Skip prominence + +How visible the skip option is. + +**Equal prominence.** Skip and continue have similar visual weight. Honest about both options. Most common. + +**Continue-prominent.** Continue is the visual primary; skip is a secondary link. Encourages completion without forbidding skip. + +**Skip-prominent.** Skip is more visible than continue. Almost never the right choice; produces skip-friendly-empty. + +**Hidden skip.** Skip exists but is hidden behind a "more options" toggle. Discouraged; users cannot find escape if they need it. + +The discipline. Continue-prominent for important steps; equal prominence for most steps; never skip-prominent. + +--- + +## Skip-friendly-empty: the failure mode + +The pattern where skip is too prominent and consequence-free. + +**The pattern.** Every step has a "Skip" button as prominent as "Continue." Skip is consequence-free; users skip every step. + +**The result.** Users land in an empty product; they have no context; they leave. + +**The cost.** Activation rate falls off a cliff. The wizard's design effort produces an experience nobody actually completes. + +**The cure.** Rebalance skip prominence. Make consequences visible. Add resume mechanics so skipped steps can be completed later. + +--- + +## Resume patterns + +Where users land when they return. + +**Auto-resume on next login.** + +How it works. The user returns; the wizard automatically lands at the step they left. + +When to use. When wizard completion is genuinely required for product use. + +**Manual resume from in-product entry.** + +How it works. A persistent "Complete setup" surface in-product returns the user to the wizard. + +When to use. When the wizard is recommended but not required; users can engage with the product partially. + +**Soft resume.** + +How it works. The wizard fades out as the user completes equivalent actions in-product naturally. No explicit re-entry needed. + +When to use. When the in-product experience surfaces equivalent prompts; the wizard becomes redundant. + +**No resume.** + +How it works. Skipped steps are skipped permanently; the wizard runs once. + +When to use. Rarely. Most wizards benefit from some resume mechanism. + +--- + +## Skip-and-defer in-product prompt design + +The prompts that bring users back. + +**Trigger logic.** Prompts trigger based on user behavior, time elapsed, or context. "You have not connected a data source yet; here is how" appears when the user attempts to use a feature requiring data. + +**Frequency limits.** Prompts should not nag. One reminder per session is often enough; some prompts should appear once and dismiss permanently. + +**Dismiss mechanics.** "Don't show this again" is honest. Hidden dismiss options are hostile. + +**Completion routing.** When the user accepts the prompt, route to the right setup flow (often shorter than the original wizard step). + +--- + +## Skip mechanics by step type + +Different steps warrant different skip treatment. + +**Critical setup steps (without which the product cannot work).** Skip should be possible but consequence-warned. Resume mechanics aggressive. + +**Optional configuration steps.** Skip easy and consequence-free; resume mechanics gentle. + +**Identity/personalization steps.** Skip easy; the product can default; resume not necessary. + +**Marketing/data-collection steps.** Skip easy; the product does not need this; resume rarely warranted (skip is a clean signal of opt-out). + +The discipline. Skip prominence and resume aggressiveness should match the step's importance. + +--- + +## Resume measurement + +Track resume effectiveness. + +**Skip rate per step.** What percentage of users skip each step? + +**Resume rate per step.** What percentage of users who skipped a step later return to complete it? + +**Activation rate per skip pattern.** Do users who skipped step X activate at lower rates? + +**Diagnostic uses.** + +- High skip + low resume: wizard losing users who never come back. Audit consequences. +- High skip + high resume: skip-and-defer working. The wizard is producing graceful escapes. +- Low skip overall: wizard is engaging users; check completion and activation as next metrics. + +--- + +## Resume copy discipline + +What the resume prompt says. + +**Helpful resume copy.** + +- "Connect your data source to see insights. It takes 2 minutes." +- "You skipped inviting teammates earlier. Want to do that now?" +- "Almost done. Two steps left to finish setup." + +**Unhelpful resume copy.** + +- "You did not finish onboarding." +- "Complete setup." +- "You missed steps." + +The voice discipline. Resume copy should be helpful, not scolding. The user did not fail; they deferred. + +--- + +## Common skip-and-resume failures + +**Skip too prominent.** Users skip everything; activation collapses. + +**No skip option.** Users who need to escape leave entirely. + +**Hidden skip.** Users cannot find escape; frustration builds; they leave. + +**No resume mechanism.** Skipped users never return to complete; configuration stays incomplete. + +**Aggressive resume prompts.** Prompts every session; users dismiss permanently. + +**Resume routes to wrong place.** User accepts prompt; lands in unrelated flow. + +**Resume copy scolds.** User feels punished for skipping; trust degrades. + +**Skip without consequence-disclosure.** Users skip not knowing what they will miss; abandon when they discover. + +--- + +## Methodology-level choices that stay in the public skill + +The skip principle. Skip patterns (4 patterns). Skip prominence guidance. The skip-friendly-empty failure. Resume patterns (4 patterns). Skip-and-defer prompt design. Skip mechanics by step type. Resume measurement. Resume copy discipline. Common failures. + +## Implementation choices that stay internal + +Specific skip and resume implementations for specific wizards. Specific prompt copy in brand voice. Specific tooling for resume infrastructure. The team's resume measurement baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..b610daf --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md @@ -0,0 +1,225 @@ +# Step architecture patterns + +What belongs in each step. Sequence logic. The step coherence test. + +The architecture is the structure that makes wizards work. Bad architecture produces decorative steps that do not move the user closer to value; good architecture converges on the ah-ha moment with discipline. + +--- + +## The convergence principle + +Each step should move the user one step closer to value. Steps that do not should be cut. + +**The test.** For each step, ask: did this step move the user toward the ah-ha moment? If no, cut it or defer it to in-product help. + +**The discipline.** Wizards accumulate steps over time as teams add "while we have them" requests (collect more data, surface more features, etc.). The discipline is to resist accumulation; the wizard's job is convergence, not feature pride. + +--- + +## Common step patterns + +Patterns that recur across product onboarding wizards. + +**Welcome and orientation.** + +- Purpose: set expectations for what the wizard will do. +- Skippable: usually yes, low cost. +- When to include: when the wizard's purpose is not obvious from context. +- When to skip: when the wizard's purpose is obvious; welcome adds friction without value. + +**Identity and account context.** + +- Purpose: capture who the user is, what brought them here. +- Required fields: minimal. Name and role are often enough. +- When to include: when subsequent steps adapt to identity. +- When to skip: when subsequent steps do not adapt; identity capture is just data collection. + +**Critical setup step.** + +- Purpose: the one thing the product cannot work without. +- Examples: connect data source, invite first teammate, set primary use case. +- This is often where wizards justify their existence. Without this step, the user lands in an empty product. + +**First-action step.** + +- Purpose: get the user to take a meaningful action that produces visible result. +- The ah-ha moment lives here or right after. +- Should be guided enough that success is likely; honest enough that the success is real. + +**Configuration deferral.** + +- Purpose: surface things that can be set up later but are commonly needed. +- Lets the user defer with a clear path back. +- Reduces wizard length without losing coverage. + +**Confirmation and next steps.** + +- Purpose: recap what was set up; surface what to do next; route to in-product home. +- Closes the wizard cleanly. +- Often skipped in design but useful for orientation. + +--- + +## Step sequencing principles + +The order matters as much as the steps themselves. + +**Principle 1: Earn the patience.** Open with low-friction steps; the user invests; deeper setup follows. Critical setup demanding effort works better at step 2-3 than step 1. + +**Principle 2: Ah-ha moment by step 3-5.** If the wizard runs longer than 5 steps before any visible value, drop-off climbs sharply. + +**Principle 3: Deferable last.** Steps that can be deferred should sit late in the wizard, where skip is least costly. + +**Principle 4: Confirmation explicit.** Close the wizard with a clear "you are done; here is what's next" step. Without it, users feel dropped. + +--- + +## Step coherence test + +For each step, can it be described in one sentence as a unit of work that contributes to the ah-ha moment? + +**Coherent steps.** + +- Step 1: tell us about your role so we can tailor what comes next. +- Step 2: connect your data source so we can show you something useful. +- Step 3: run your first query and see a result. +- Step 4: save the result so you can return to it. +- Step 5: optionally invite a teammate; otherwise, you are ready. + +Each step has clear purpose tied to value. + +**Incoherent steps.** + +- Step 1: name and email (already collected at signup; redundant). +- Step 2: tour of features (does not move toward action). +- Step 3: branding preferences (irrelevant to ah-ha moment). +- Step 4: marketing opt-in (data collection, not value). + +Steps without clear purpose should be cut or deferred. + +--- + +## Step count discipline + +How many steps is too many. + +**Sweet spot.** Most effective wizards run 3-7 steps. The user can predict completion time; the convergence is tight. + +**Too few.** 1-2 steps usually means the wizard format is overkill; contextual prompts often serve better. + +**Too many.** 10+ steps signals tutorial-overload. Drop-off climbs sharply; users skip when they can. + +**The deferable test.** For wizards exceeding 7 steps, audit each step. Which can be deferred to in-product? Often half can. + +--- + +## Field count per step + +Within each step, how many fields. + +**3-5 fields per step.** Sweet spot. Coherent unit; completable in 30-60 seconds. + +**1-2 fields per step.** Often signals over-staging. The user wonders why the field needed its own step. + +**6+ fields per step.** Recreates the kitchen-sink problem within a step. Audit; usually some fields can be cut or deferred. + +--- + +## Branching and conditional steps + +When wizards adapt based on earlier answers. + +**The pattern.** First step asks about role or use case; subsequent steps adapt. + +**Strengths.** The wizard feels relevant; users see only what applies to them. + +**Weaknesses.** Maintenance complexity; testing across paths. + +**The discipline.** Branch only when the variability genuinely benefits the user. Decorative branching adds cost without lift. + +--- + +## Step transitions + +How the user moves between steps. + +**Forward transitions.** Clear "Next" or "Continue" CTA. Validation runs before the transition. Snappy; no loading delays. + +**Back transitions.** "Back" or "Previous" available. Returning to earlier steps preserves answers. + +**Skip transitions.** Skip available but honest about consequences. Skip lands the user in a partially-set-up state with clear callouts to complete deferred setup. + +**Loading state.** When the wizard's step requires backend work (connecting data source, processing input), show progress. Silent loading kills momentum. + +--- + +## Step examples by product type + +How architecture varies by product. + +**B2B SaaS analytics.** + +- Welcome → role/use case → connect data source → first query → first saved view → invite team (deferable) → in-product home. + +7 steps; meaningful staging; ah-ha at step 5. + +**Project management tool.** + +- Welcome → workspace setup → first project → first task → invite team → in-product home. + +6 steps; ah-ha around step 4. + +**Marketing automation.** + +- Welcome → connect site → connect data source → first audience → first campaign → in-product home. + +6 steps; ah-ha at first audience visualization. + +**Consumer note-taking.** + +- Probably no wizard. Empty-state prompts and contextual hints serve better. + +The patterns vary. The discipline (each step earns its place; ah-ha moment by step 3-5) holds. + +--- + +## Step architecture maintenance + +Steps decay. Product changes mean wizard updates. + +**Maintenance triggers.** + +- Product feature added that the wizard should reference. +- Product feature deprecated that the wizard still references. +- Setup process changed; wizard steps no longer match. +- Audience composition shifted; old role-branching no longer fits. + +**Maintenance cadence.** Quarterly review minimum; product changes trigger updates as part of the change. + +--- + +## Common architecture failures + +**Decorative steps.** Steps that do not move toward value. + +**Tutorial steps.** Steps explaining features the user has not asked about. + +**Front-loaded effort.** High-friction step first; users abandon at step 1. + +**Late ah-ha moment.** Wizard runs 10 steps before visible value. + +**Mandatory steps that should be deferable.** Forces friction users would have accepted later. + +**No confirmation step.** User finishes the wizard, lands somewhere unclear. + +**Step transitions sluggish.** Loading delays kill momentum. + +--- + +## Methodology-level choices that stay in the public skill + +The convergence principle. Common step patterns. Sequencing principles. The step coherence test. Step count discipline. Field count per step. Branching considerations. Step transitions. Step examples by product type. Maintenance discipline. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific products. Specific copy and tone. Specific tooling. Specific testing protocols. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md new file mode 100644 index 0000000..d274a99 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md @@ -0,0 +1,199 @@ +# User type variation patterns + +Admin vs end-user, technical vs non-technical, size-based branching. When one wizard does not serve all users. + +Different users may need different wizards. The discipline is to differentiate where the audience genuinely splits, without producing unmaintainable proliferation. + +--- + +## The differentiation principle + +Differentiate where the audience genuinely splits into segments with materially different needs, language, or paths. Do not differentiate where one wizard serves all. + +**The win.** Admins set up the workspace; end-users start using it. A single wizard tries to serve both and fails both. Differentiated wizards serve each meaningfully. + +**The fail.** A team builds 5 wizard variants for 5 imagined personas. Maintenance burden compounds; the variants diverge over time; no variant is excellent. + +The discipline. Start with one wizard. Differentiate only when data shows segments with different needs and the differentiation produces meaningfully different paths. + +--- + +## Common differentiation axes + +Three axes recur. + +**Admin vs end-user.** + +- Admins set up the workspace, invite teammates, configure integrations. +- End-users start using what admins set up. +- Their first sessions look different; the ah-ha moments differ. + +**Technical vs non-technical.** + +- Technical users want depth (see the API, see the integration succeed, configure deeply). +- Non-technical users want outcome (see the result, no API). +- Tone, content, and step coverage differ. + +**Size of team.** + +- Solo founders configure for one. +- Small teams configure for collaboration. +- Enterprise teams have additional setup (SSO, governance, compliance). + +--- + +## Differentiation patterns + +How to implement. + +**Pattern A: Role-based branching.** + +How it works. First step asks role; subsequent steps adapt. + +When to use. When the role split is clear and produces different paths. + +**Pattern B: Use-case-based branching.** + +How it works. First step asks use case; wizard tailors to that use case. + +When to use. When the product serves multiple use cases that warrant different ah-ha moments. + +**Pattern C: Size-based branching.** + +How it works. First step asks team size; solo, team, enterprise paths differ. + +When to use. When the product has materially different setups for different scales. + +**Pattern D: Inferred branching.** + +How it works. Wizard uses signals (signup source, email domain, prior interaction) to infer the segment without asking. + +When to use. When asking would feel intrusive but the inference is reliable. + +**Pattern E: No branching.** + +How it works. Single wizard for all. + +When to use. Most products. Branching adds maintenance; only branch when the value is clear. + +--- + +## Admin vs end-user wizard design + +How they differ. + +**Admin wizard.** + +- Setup-heavy. Connect data, invite team, configure permissions. +- Ah-ha moment: "the workspace is ready; my team can use it." +- Often longer; admins accept guided setup. + +**End-user wizard.** + +- Action-light. Find the feature, take the first action, see the result. +- Ah-ha moment: "I did the thing I came to do." +- Often shorter; end-users want to start using. + +**Cross-talk.** Admins sometimes also become end-users in single-person teams. The wizard may need to detect and serve both modes. + +--- + +## Technical vs non-technical wizard design + +How they differ. + +**Technical wizard.** + +- API depth visible (configuration shown, integration tested). +- Tone: precise, terse, references documentation. +- Ah-ha moment: "the integration works; my data is flowing." + +**Non-technical wizard.** + +- Outcome visible (result shown, no API exposed). +- Tone: warm, supportive, hides technical complexity. +- Ah-ha moment: "I see the result the product promised." + +**Cross-talk.** Some users are technical for some products and not for others. The wizard may infer rather than ask. + +--- + +## Size-based wizard design + +How they differ. + +**Solo founder wizard.** + +- Single-user setup. +- Skip team-related steps. +- Ah-ha moment: individual productivity. + +**Small team wizard.** + +- Collaboration setup highlighted. +- Invite-team step prominent. +- Ah-ha moment: team coordination. + +**Enterprise wizard.** + +- SSO, governance, compliance setup. +- Often involves admin handoff to IT or security. +- Ah-ha moment: deployment-ready configuration. + +--- + +## When to combine vs separate + +Designing the matrix. + +**Combine when:** + +- The differentiation is small (1-2 different steps). +- Maintenance burden is the bigger concern. +- The audiences overlap significantly. + +**Separate when:** + +- The paths differ in 3+ steps. +- Tone and language differ significantly. +- Audience-fit is critical (B2B SaaS where different roles experience the product very differently). + +**The 2-3 variants max rule.** More than 3 wizard variants becomes unmaintainable. If 4+ variants seem necessary, reconsider whether the segmentation is too granular or whether different wizards should be different products. + +--- + +## Differentiation testing + +Verify the differentiation works. + +**Cohort comparison.** Compare activation rates across variants. Did differentiation help? + +**Per-segment satisfaction.** Survey users post-wizard. Does each segment feel served? + +**Drop-off per variant.** Are some variants dropping off more than others? Which steps? + +The data informs whether the differentiation earned its complexity. + +--- + +## Common differentiation failures + +**Over-differentiation.** Too many variants; maintenance burden; no variant is excellent. + +**Under-differentiation.** One wizard for distinct audiences; everyone feels poorly served. + +**Wrong axis.** Differentiated by an axis that does not predict need (e.g., gender when role would have been the right split). + +**Inferred wrongly.** Inference logic mistakes audience; users see wrong wizard. + +**Stale differentiation.** Audience composition shifted; old branching no longer fits. + +--- + +## Methodology-level choices that stay in the public skill + +The differentiation principle. Common differentiation axes. Patterns A through E. Admin vs end-user design. Technical vs non-technical design. Size-based design. Combine-vs-separate decision. Differentiation testing. Common failures. + +## Implementation choices that stay internal + +Specific wizard variants for specific products. Specific copy per variant in brand voice. Specific inference logic. The team's variant maintenance calendars. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md new file mode 100644 index 0000000..01f9cfc --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md @@ -0,0 +1,212 @@ +# Wizard anti-patterns + +The patterns that look like onboarding but degrade activation. Anti-patterns are easy to ship; the cost shows up in activation rate, retention, and brand reputation over time. + +--- + +## The tutorial-overload wizard + +The pattern. Every feature explained in a 12-step intro before the user has touched the product. + +The signal. High skip rate; users abandon mid-wizard; activation rate poor. + +The cost. Design effort produces a sequence almost nobody completes. Users who do complete have not seen value; activation suffers. + +The cure. Prune steps to those that contribute to the ah-ha moment. Defer feature explanations to in-product tours and contextual help. + +--- + +## The skip-friendly-empty wizard + +The pattern. "Skip onboarding" button at every step, so prominent that users always take it. + +The signal. Skip rate near 100 percent; users land in unconfigured product; activation rate falls. + +The cost. The product appears empty to users who skipped; they do not know what to do; they leave. + +The cure. Rebalance skip prominence. Add consequence-honest skip warnings. Add resume mechanisms so skipped steps come back as in-product prompts. + +--- + +## The decoration-step wizard + +The pattern. Steps that exist for completeness or feature pride, not for value. + +The signal. Drop-off concentrates on specific steps users perceive as pointless; analytics shows steps users always skip. + +The cost. Wizard length without value; user perceives the wizard as bloated. + +The cure. Audit each step. Cut steps that do not contribute to the ah-ha moment. + +--- + +## The tutorial-as-ah-ha wizard + +The pattern. Treating "learned about features" as activation. Wizard ends; user has seen a tour; team treats this as success. + +The signal. High completion rate, low retention. Users completed the wizard but did not engage afterward. + +The cost. The wizard's success metric is wrong. Real activation never happens. + +The cure. Define the ah-ha moment as action-tied. Redesign the wizard to converge on the moment. + +--- + +## The demo-as-ah-ha wizard + +The pattern. The wizard ends with a polished demo using fake data. + +The signal. Users see what is possible; do not return because their actual data has not been touched. + +The cost. The wizard's value is contrived; activation does not stick because the value was hypothetical. + +The cure. Make the ah-ha moment real. Use the user's actual data. + +--- + +## The over-branched wizard + +The pattern. 5 wizard variants for 5 imagined personas. Maintenance burden compounds. + +The signal. Variants diverge over time; some break; activation per variant is uneven. + +The cost. Maintenance overhead high; quality of any one variant degrades. + +The cure. Reduce variants to 2-3 max. Combine variants where the differentiation does not produce materially different paths. + +--- + +## The under-branched wizard + +The pattern. One wizard for distinct audiences. Admins, end-users, technical, non-technical all see the same flow. + +The signal. Some segments activate well; others do not. Per-segment data shows the gap. + +The cost. The audiences underserved leave; the wizard's design effort produces good outcomes for one segment and bad for others. + +The cure. Differentiate where the audience genuinely splits. + +--- + +## The hidden-skip wizard + +The pattern. Skip exists but is hidden behind a "more options" toggle or appears only after the user struggles. + +The signal. Users who need to escape leave the product entirely instead of skipping. + +The cost. Forced friction loses users who would have engaged later if they had been allowed to defer. + +The cure. Make skip findable. Make consequences clear. Add resume. + +--- + +## The validation-strict wizard + +The pattern. Validation rejects valid inputs because rules are over-specified. + +The signal. Users with valid but unusual inputs cannot proceed; abandon. + +The cost. Filter loses real users. + +The cure. Audit validation. Email plus-aliases, international phone, non-Latin names should pass. + +--- + +## The mobile-broken wizard + +The pattern. Wizard works on desktop; breaks on mobile. + +The signal. Mobile completion half of desktop or worse. + +The cost. Mobile audience underserved; mobile is often majority of traffic. + +The cure. Mobile-first design and testing. + +--- + +## The unmaintained wizard + +The pattern. Wizard built once; product evolved; wizard not updated. + +The signal. Users hit broken steps; references to deprecated features; analytics drift. + +The cost. The wizard becomes liability; current users get worse experience than past users. + +The cure. Quarterly maintenance. Product changes trigger wizard updates as part of the change. + +--- + +## The interrogation-disguised-as-wizard + +The pattern. Wizard asks 12 fields, of which 5 affect product setup. The other 7 are sales-qualification or marketing data. + +The signal. Drop-off climbs at fields that feel like sales forms; users sense the manipulation. + +The cost. Filter loses users who would have engaged with a product-focused wizard. + +The cure. Audit fields. Remove or defer fields that do not contribute to product setup. Capture sales/marketing data later in the relationship. + +--- + +## The popup-interrupted wizard + +The pattern. User is mid-wizard; a popup appears (newsletter, chat, special offer); flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about interruption. + +The cost. Wizard's user experience hostile; brand earns annoying reputation. + +The cure. Suppress popups during wizard completion. Save promotional content for after. + +--- + +## The reset-on-error wizard + +The pattern. User submits; validation fails; wizard resets, losing user inputs. + +The signal. Users who hit error do not retry; they leave. + +The cost. The wizard treats errors punitively; trust collapses. + +The cure. Preserve inputs on error. Show error inline; let the user fix and resubmit. + +--- + +## The wizard-without-activation-metric + +The pattern. Wizard tracked by completion rate alone. Activation not measured. + +The signal. Completion looks fine; team cannot diagnose whether the wizard is producing engaged users. + +The cost. The wizard's success metric is wrong; bad wizards look good in dashboards. + +The cure. Define and track activation explicitly. Wizard completion is leading indicator at best. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active wizard, looking for these anti-patterns. + +**Audit questions per wizard.** + +- Does each step contribute to the ah-ha moment (anti-pattern check: tutorial-overload, decoration)? +- Is skip honest about consequences and recoverable (anti-pattern check: skip-friendly-empty, hidden-skip)? +- Does the wizard match the product's current state (anti-pattern check: unmaintained)? +- Is activation tracked (anti-pattern check: completion-only metrics)? +- Does the wizard work on mobile (anti-pattern check: mobile-broken)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is the audience segmentation right (anti-pattern check: over-branched, under-branched)? + +**The retire decision.** Anti-pattern wizards often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md new file mode 100644 index 0000000..f1ec10b --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md @@ -0,0 +1,133 @@ +# Wizard decision criteria + +When wizards earn the build vs when contextual help suffices. The conditions that warrant the wizard format, and the funnels where a wizard adds friction without lift. + +A wizard is meaningful work. Step architecture, ah-ha moment design, progressive disclosure, skip mechanics, drop-off instrumentation, ongoing maintenance. The wizard earns this investment only when specific conditions are present. + +--- + +## When wizards earn the build + +Five conditions that, when present, make a wizard a strong investment. + +**The product has meaningful setup before value emerges.** Connect a data source, invite a teammate, configure a workspace, choose a use case. Without setup, the product is empty; the wizard makes setup tractable. Products that work immediately on signup do not need this. + +**The ah-ha moment requires multiple actions in sequence.** Single-action ah-ah moments (paste a URL, see a result) often work better with contextual prompts. Multi-action ah-ha moments benefit from a guided sequence. + +**The audience expects guided onboarding.** B2B SaaS with technical setup, enterprise software, configurable products often work well with wizards. Some audiences (frictionless consumer tools) reject wizard friction regardless of product complexity. + +**The team can maintain the wizard.** Wizards decay as the product evolves; deprecated features still in flow break the experience. Without maintenance commitment, the wizard becomes a liability. + +**The success metric is defined.** Not just completion rate; activation rate (post-wizard product engagement) and time-to-value. Without the success metric, evaluation is impossible. + +When all five are present, the wizard is a strong investment. When two or fewer are present, contextual prompts often serve better. + +--- + +## When wizards do NOT earn the build + +Funnels where the wizard adds friction without lift. + +**The product reaches value immediately.** Single-input tools, simple consumer products, frictionless utilities. A wizard adds steps where the user could already see value. + +**Contextual help would suffice.** Tooltips, in-feature hints, progressive in-product education sometimes serve better than upfront wizards. The user explores naturally; help surfaces when needed. + +**The audience expects no friction.** Some audiences abandon at any wizard. Consumer-facing high-volume products, embedded tools, prosumer utilities. Meet the audience where they are. + +**The team cannot maintain the wizard.** Stale wizards point to deprecated features; users hit broken steps. Without maintenance capacity, no wizard is better than a stale one. + +**The setup work is genuinely better in-product.** Some setup is better done after the user understands the product. Wizards that try to set up something the user does not yet understand produce poor configuration. + +The honest assessment matters more than the default. "Should we have an onboarding wizard" is not the question. "Is the wizard the right tool for this product and audience" is. + +--- + +## The opportunity-cost frame + +A wizard is significant work. Account for it. + +**The build cost.** Step architecture, copy, design, instrumentation, integration with the product, maintenance scaffolding. A meaningful wizard often takes 40-150 engineering hours plus design and copy. + +**The maintenance cost.** Quarterly review minimum; product changes trigger wizard updates. 4-12 hours per active wizard per quarter. + +**The opportunity cost.** What else could the team have built? Direct in-product improvements, contextual help, documentation, a simpler activation funnel. The wizard's success has to clear the bar of those alternatives. + +The decision frame. The wizard earns investment when it produces more activation lift than the alternatives, accounting for build plus maintenance. + +--- + +## The ah-ha-moment precondition + +Without an identifiable ah-ha moment, the wizard has nothing to engineer toward. + +The check. Can the team articulate the single visible moment when the user feels "oh, this is what the product does for me"? + +If yes, the wizard can be designed to converge on that moment. If no, the team has not yet defined what activation means; the wizard cannot be designed coherently until that is settled. + +**Defining the ah-ha moment is upstream of wizard design.** Sometimes the right move is to spend time identifying the ah-ha moment first (often through customer research) before scoping the wizard. The wizard built without a defined ah-ha moment is the wizard that produces high completion and low activation. + +--- + +## The decision worked example + +A B2B SaaS analytics platform considering an onboarding wizard. + +**Conditions check.** + +- Meaningful setup before value: yes. Connect at least one data source. +- Ah-ha moment multi-action: yes. Connect data, run first query, see useful result. +- Audience expects guided onboarding: yes. Data analysts and data leaders generally accept guided setup. +- Maintenance commitment: yes. Activation team owns the wizard. +- Success metric defined: yes. Activation = ran at least one query within 7 days of signup. + +**Decision.** Build the wizard. The conditions warrant it. + +**Step architecture.** Welcome (skippable) → connect first data source → confirm connection → guided first query → see result (ah-ha moment) → invite teammates (deferable) → in-product home. + +**Maintenance commitment.** Activation team reviews quarterly; product changes trigger wizard updates. + +The decision was not "should we have a wizard" but "given these conditions, this is the wizard to build." + +--- + +## The decision worked example: when to choose differently + +A consumer note-taking app considering an onboarding wizard. + +**Conditions check.** + +- Meaningful setup: no. The user can start typing immediately. +- Ah-ha moment multi-action: no. The ah-ha moment is "I can save a note and find it later," reachable without setup. +- Audience expects guided onboarding: no. Consumer note-taking audiences resist friction. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined (returned within 7 days). + +**Decision.** Do not build a wizard. Contextual prompts (sample notes, brief tooltip on first save, short empty-state prompts) serve better. + +The decision was "is this wizard right for this product" and the answer was no even though the team had capacity. + +--- + +## When to retire a wizard + +Wizards can become wrong even after being right initially. + +**Retire when:** + +- Activation rate has dropped below baseline for two consecutive quarters and refinements have not moved it. +- The product has changed enough that the wizard guides users toward deprecated paths. +- Customer research shows users skipping the wizard and activating fine without it. +- A redesigned in-product activation flow makes the wizard unnecessary. +- The team can no longer maintain the wizard. + +The retiring discipline frees capacity. Stale wizards are worse than no wizards. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant a wizard. The five conditions that argue against. The opportunity-cost frame. The ah-ha-moment precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific wizard scope decisions for specific products. The team's capacity benchmarks. Specific tooling for wizard implementation and instrumentation. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/paid-media-strategy/SKILL.md b/dist/pi/.agents/skills/paid-media-strategy/SKILL.md new file mode 100644 index 0000000..2d0a67b --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/SKILL.md @@ -0,0 +1,256 @@ +--- +name: paid-media-strategy +description: "A discipline for running paid media that does not light money on fire. Hypothesis writing for paid spend, channel selection, budget allocation, audience targeting, bid strategy, campaign types, what NOT to spend on, attribution reality, and the failure modes that produce expensive lessons. Triggers on paid media strategy, ad budget allocation, channel selection, paid media plan, audit my Google Ads, audit my Meta Ads, scale paid media, kill underperforming campaign, paid media hypothesis, ad spend strategy, attribution reality, performance marketing strategy. Also triggers when a team is asking how to scale paid media, or whether to add a new channel, or how to reallocate spend across channels." +category: marketing +catalog_summary: "Hypothesis to spend: channel selection, budget allocation, audience targeting, bid strategy, attribution reality, and the failure modes that burn agency-scale budgets" +display_order: 1 +--- + +# Paid Media Strategy + +A senior performance marketer's playbook for running paid media that produces real outcomes. + +The default state of paid media is wasted spend. Most accounts have campaigns running because they always have, audiences targeting because the rep suggested it, bid strategies on auto because manual is hard, creative not refreshed because there is no system. The cost compounds. A 20% efficiency gain on a $500K-per-year account is $100K back to the business. A 50% gain on a $5M-per-year account is $2.5M. + +This skill is the discipline that produces those gains. It assumes you have a paid media platform (Google Ads, Meta, LinkedIn, TikTok, or aggregators like Synter) connected. It assumes you have working analytics and conversion tracking. The hard part is the strategic discipline behind the spend, and that is what is here. + +When to use this skill: any time you are designing a paid media plan, evaluating whether to scale or kill a campaign, allocating budget across channels, or auditing an existing account. + +--- + +## What this skill is for + +This skill spans paid media strategy and operations. It does not cover ad creative production (use `ads-creative-development`), result interpretation in depth (use `ads-performance-analytics`), or platform-specific MCP tooling (consult each ad platform's official documentation for current MCP setup, auth, and example prompts). + +The audience is a performance marketer (in-house or agency), a growth lead allocating spend across channels, or a founder making early paid budget decisions. The voice is tactical. There is no "evaluate every option yourself with no opinion." Paid media decisions have shape, and a senior practitioner can map a situation to a defensible plan in an afternoon. + +--- + +## Hypothesis discipline for paid spend + +Most paid media failures start with a vague reason for spending. A real spend hypothesis has five parts: audience, offer, channel, outcome metric, and magnitude. Missing any of them and the campaign cannot be evaluated honestly. + +A bad reason: "We need to scale Google Ads spend." No audience, no outcome metric, no magnitude. Nothing is falsifiable. + +A good hypothesis: "Top-of-funnel SaaS prospects searching for project management tools convert from a free-trial CTA at 3.2% CAC under $80. Increasing Search budget from $40K to $80K per month should hold CAC under $80 and add roughly 500 trial signups based on Q3 search volume." + +That hypothesis names the audience (top-of-funnel SaaS prospects on PM-tool keywords), the offer (free trial), the channel (Google Search), the outcome metric (CAC, trial signups), and the magnitude (500 signups, CAC under $80). It is falsifiable: if CAC blows past $80 or signups come in below 250, the hypothesis is wrong and you pull back. + +Pre-commit the falsification rule. Decide before scale: at what CAC do we hold? At what CAC do we pull back? At what trial-signup count do we kill? Without pre-commit, every result becomes a debate. With pre-commit, the decision is mechanical. + +Primary metric is the one you are optimizing for (CAC, ROAS, CPL). Guardrails are the metrics you do not want to break (LTV, retention, brand search lift). Scaling the primary metric while breaking a guardrail is a Pyrrhic win. + +--- + +## Channel selection: when to use which platform + +Pick the channel where intent matches your offer. Run the wrong channel and your CAC reads as a channel problem when it is actually a fit problem. + +**Google Search.** High-intent demand capture. Best when you have a real product people search for and the query volume justifies the floor. Worst when category awareness is low and no one is searching. Predictable, expensive at scale, the highest floor of any channel. + +**Google Performance Max.** Automated multi-channel within the Google ecosystem. Best when you have a strong product feed (e-commerce) or want to lean into Google's automation. Worst when you need control over placements; PMax is a black box and disagreements with the algorithm cost money. + +**Meta (Facebook plus Instagram).** Broad-targeting demand creation. Best for visual products, lifestyle brands, B2C scale, and direct response with strong creative. Worst when targeting is too narrow (audiences saturate fast) or when the offer is high-consideration B2B. + +**TikTok.** Discovery-mode advertising. Best for native-feeling video creative, younger audiences, and brand awareness. Worst for direct response with high consideration cycles. Spark Ads (boosting organic posts) outperform pure paid creative. + +**LinkedIn.** B2B targeting precision. Best for high-LTV B2B with clear job-title targeting. Worst for low-AOV products; the floor is too high to be efficient. + +**Reddit, Pinterest, Snapchat, X.** Niche or supplementary. Best as scale-out channels after primary channels are working. Worst as starting points; spreading thin across niches before you have proven any channel is the most common waste pattern. + +**YouTube (Google).** Video at scale. Best for awareness or for B2C consideration. Underrated for B2B SaaS in some categories where the buyer-research path includes long-form video. + +The decision rule. Start with the channel where intent matches your offer. Search for high-intent demand capture. Meta or TikTok for demand creation. LinkedIn for B2B precision. Do not run all of them at once until you have proven any of them. Detail in [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md). + +--- + +## Budget allocation: brand vs performance, baseline vs test + +Four splits operate at the same time. Get them all right and the budget compounds. + +**Brand vs performance.** Brand keeps the demand pipeline filled (long term); performance captures it (short term). 70-30 to 80-20 performance-heavy is typical for most B2C. Brand-heavy splits fit high-consideration B2B where the buying cycle is months long and pipeline visibility matters more than week-over-week conversions. + +**Baseline vs test.** 70 to 80% of budget to channels, campaigns, and audiences that are working. 20 to 30% to systematic testing of new channels, new audiences, new creative. Without test budget, you stagnate. Without baseline budget, you have nothing to scale. + +**Primary vs secondary channel.** One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the equal-split temptation; spreading across channels before any one is proven is the most expensive way to learn nothing. + +**Daily vs lifetime budgets.** Daily for ongoing campaigns where you want a stable spend floor. Lifetime for finite tests where the platform should pace itself across the test window. Lifetime budgets prevent runaway spend during testing. + +Budget pacing matters too. Front-load some weeks to test creative aggressively. Back-load others to capture seasonality (holiday, end-of-quarter, category-specific moments). Do not run flat; flat budgets miss the demand peaks. + +Detail and templates in [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md). + +--- + +## Audience targeting: prospecting vs retargeting vs exclusion + +Three audience types. Treat them as separate strategies. + +**Prospecting.** New people who have not heard of you. Lookalike audiences (Meta), in-market audiences (Google), interest stacks, lookalikes seeded from high-LTV customers. Largest budget share for growth-mode brands; this is where new demand comes from. + +**Retargeting.** People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC. Do not bid too aggressively or you train the platform to charge a premium for users who would have converted anyway. + +**Exclusion.** Current customers and recent converters kept out of prospecting and retargeting. Saves spend, keeps frequency low, prevents creative fatigue from people who are already paying you. + +Common mistakes. Prospecting too narrow (not enough audience for the platform to optimize). Retargeting too aggressive (cannibalizing organic conversions). No exclusions (paying to advertise to your own paying customers). Lookalikes off the wrong source (use top-LTV customers, not all customers). + +Detail in [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md). + +--- + +## Bid strategy: when each fits + +Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. + +**Manual CPC or CPM.** Full control, slow to scale. Useful for diagnostics and very early campaigns where you do not trust the platform's machine learning yet. + +**Maximize Conversions.** Platform optimizes for volume within budget; the platform decides CPC. Use when you want as many conversions as possible regardless of cost. Good early-stage strategy while you gather data. + +**Target CPA (tCPA).** Set a max CPA, platform delivers within. Use when CPA is the constraint and you have at least 30 conversions in the recent window for the platform to optimize against. + +**Target ROAS (tROAS).** Set a min ROAS, platform delivers above. Use when revenue per conversion varies and you care about value, not count. + +**Maximum Conversion Value.** Like maximize conversions but optimizes for total revenue, not count. Use when high-value conversions are the goal and you have the conversion-value data wired in. + +**Enhanced CPC.** Manual CPC with platform adjustments. Hybrid; rarely the right answer because it muddies the signal. + +The progression for new campaigns: start manual or maximize conversions to gather data, switch to tCPA or tROAS once you have 30+ conversions, revisit periodically. + +Common mistakes. Using tCPA before you have 30+ conversions (no data to optimize against). Setting tROAS too aggressively (platform throttles delivery). Switching strategies too often (each change resets the learning phase). Detail in [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md). + +--- + +## Campaign types + +For each major platform, the campaign types and when to use them. + +**Google Ads.** Search, Shopping, Performance Max, Display, Video (YouTube), Demand Gen, Discovery, App. Search for direct demand capture. PMax for catalog-driven e-commerce. Display for retargeting. Video for awareness or consideration. + +**Meta.** Sales, Leads, Engagement, Awareness, Traffic, App Promotion. Sales for direct response. Awareness for brand at scale. Leads for B2B with native lead forms. + +**LinkedIn.** Sponsored Content, Message Ads, Conversation Ads, Lead Gen Forms. Format types: Single Image, Carousel, Video. Lead Gen Forms convert hardest because they pre-fill from LinkedIn profile data. Message Ads have stigma in many B2B segments; use carefully. + +**TikTok.** In-Feed, TopView, Spark Ads, Branded Hashtag Challenge. Spark Ads (boost organic posts) outperform pure paid creative because they retain organic-feel signal. Use Spark when you have organic posts performing. + +Detail per platform in [`references/campaign-type-reference.md`](references/campaign-type-reference.md). + +--- + +## What NOT to spend on + +Direct list. Audit any account against these and you will usually find easy savings. + +- **Branded keywords beyond defensive.** When ranking number one organically, branded paid clicks cannibalize free traffic. Some defensive spend is fine to block competitor bidding. Aggressive bidding on your own brand is waste. +- **Display network without targeting.** Broad display drives garbage traffic. Use only for retargeting unless you have specific contextual targeting. +- **Geographic markets you do not serve.** Sounds obvious, fails 30% of accounts. Audit geo targeting quarterly. +- **Hours you cannot service.** For service businesses (legal, B2B, medical). Pause off-hours unless lead form clearly converts asynchronously. +- **Devices that do not convert.** If mobile converts at 1% and desktop at 5% with the same CPC, bid down mobile aggressively. +- **Audiences who never convert.** Pull last 90 days of converters, build exclusion lists for everyone else who repeatedly clicks but never converts. +- **Creative that is tired.** Frequency above 4 with declining CTR means refresh. Refusing to refresh because "it still works ok" is incremental loss. + +The pattern across these is the same. Default settings or accumulated cruft generate spend without producing outcomes. Audit, exclude, and reclaim. + +--- + +## Creative testing: within campaign vs across campaign + +Two modes. Different learning rates, different overhead. + +Within-campaign testing rotates 4 to 6 ad variations and lets the platform optimize delivery to top performers. Lower test risk because all variations live inside one campaign with one budget. Slower learning because the platform's optimization muddies the signal of which variation actually wins. + +Across-campaign testing runs entire campaign concepts (audience plus offer plus creative) against each other. Higher learning rate because each campaign has its own audience and budget. Higher setup overhead and harder to keep apples-to-apples. + +Cadence. Refresh top creative every 30 to 60 days at scale. Weekly for high-frequency campaigns. Keep the top one or two evergreen winners running and rotate others. + +The "winning creative is the floor" principle. Do not kill winners to test new ideas. Test alongside. The downside of running the proven winner is small; the downside of killing it for an unproven concept is large. + +--- + +## Frequency capping + +Ad fatigue is real. Same audience seeing the same creative eight times in a week tunes it out, or worse, develops negative associations. + +Typical caps. Three to four impressions per user per week for Awareness campaigns. Six to eight per week for Direct Response. Lower for B2B (one to two per week per LinkedIn target). Platform defaults are usually too high; set explicit caps. + +Rotation as alternative. If you have enough creative variants, rotate often enough that no individual creative hits fatigue threshold. Rotation plus capping is the strongest pattern for high-spend, long-running campaigns. + +--- + +## Attribution mismatch: platform-reported vs actual + +The trap. Platform-reported conversions are inflated by view-through attribution, generous click attribution windows, and platform self-attribution bias. + +**Last-click in GA vs platform-reported.** Google Ads typically reports 1.3 to 1.5x the conversions GA reports. The gap comes from multi-touch attribution differences and view-through that GA does not credit. + +**iOS 14.5+ impact.** Meta and other platforms underreport iOS conversions because of App Tracking Transparency. Modeled conversions try to fill the gap; they are imperfect. Treat iOS-heavy reporting with extra skepticism. + +**View-through attribution.** Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Useful for awareness; misleading for performance optimization. + +**Cross-platform interference.** Meta retargeting captures users who would have converted from Google Search anyway. Both platforms claim the conversion. You pay for the same conversion twice. + +The discipline. Single source of truth in your warehouse or analytics platform. Report against that for incrementality decisions. Use platform metrics for in-flight optimization only. The deeper interpretation work belongs in `ads-performance-analytics` (forthcoming); this skill names the trap so you do not optimize against the wrong number. + +Per-platform reporting quirks in [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md). + +--- + +## Common failures + +Twelve patterns recur across paid media work. The short version. Detail in [`references/common-failures.md`](references/common-failures.md). + +- "We are scaling but CAC went up." Saturation on the primary audience. Expand the audience or diversify the channel mix. +- "Conversions look fine in the platform, terrible in revenue." Attribution mismatch plus customer quality, not just count. The platform is selecting low-LTV converters because they are easier to find. +- "We A/B tested and one wins, but only by 5%." Within margin of platform noise. Not a real signal. +- "We turned off the underperforming campaign and conversions dropped overall." View-through or assist conversions you were not counting. Test with hold-out, not flat off. +- "Frequency hit 8 last week." Refresh creative. Do not blame the audience. +- "We are trying to scale Meta to $100K per day from $20K per day." That is not scaling, that is a 5x jump. Expect efficiency drop; phase the increase. +- "We tried LinkedIn for our B2C product." Wrong channel for the offer. Not a LinkedIn problem. +- "tROAS will not deliver." You set it too aggressive. Loosen the target or switch strategy. +- "We saw a click-through bump after the Super Bowl ad." That is brand effect on existing demand, not paid attribution. Read it as a brand signal. +- "Search Impression Share dropped." Either competition increased or budget is constrained. Check both before tuning bids. +- "PMax is hard to optimize." Yes. Treat PMax as a tested channel with constrained levers, not a place to fine-tune at the keyword level. +- "Lookalike performance dropped after we expanded to 5%." Wider lookalikes are looser; the floor is lower. Tighten back to 1 to 2% if CAC is the constraint. + +--- + +## The framework: 11 considerations for sustainable paid media + +When designing or auditing paid media, walk these 11 considerations. Skipping any of them is how teams burn budget at scale. + +1. **Hypothesis.** Audience, offer, channel, outcome metric, magnitude. Pre-commit the falsification rule. +2. **Channel fit.** Intent matches offer. Search for capture, Meta and TikTok for creation, LinkedIn for B2B precision. +3. **Budget shape.** Brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. +4. **Audience strategy.** Prospecting, retargeting, exclusion. Treated as separate strategies. +5. **Bid strategy.** Manual, max conversions, tCPA, tROAS, max conversion value. Matched to data state. +6. **Campaign type.** Right type for the platform and the goal. +7. **What not to spend on.** Branded beyond defensive, untargeted display, wrong geos, off-hours, low-converting devices, never-convert audiences, tired creative. +8. **Creative testing.** Within campaign and across campaign, plus refresh cadence. +9. **Frequency capping.** Explicit caps and creative rotation. +10. **Attribution reality.** Single source of truth, platform metrics for in-flight only. +11. **Decision rule.** Pre-committed scale up, hold, or pull back at known thresholds. + +The output of the framework is one of three answers. Scale (the hypothesis is confirmed at the magnitude needed to justify more spend). Hold (results are at the falsification line; gather more data before committing). Kill (the hypothesis is wrong or the campaign is no longer pulling its weight). + +--- + +## Reference files + +- [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md) - Context-to-channel matrix with worked examples for the most common business contexts. +- [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md) - Typical splits and pacing patterns: growth-mode, steady-state, brand-heavy, performance-heavy. +- [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md) - Prospecting, retargeting, exclusion templates plus cross-platform reconciliation. +- [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md) - Each strategy's fit, common mistakes, and migration paths as data accumulates. +- [`references/campaign-type-reference.md`](references/campaign-type-reference.md) - Per-platform campaign type guide with pitfalls. +- [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md) - Platform reporting quirks, attribution differences, and the single-source-of-truth pattern. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, and prevention. + +--- + +## Closing: when in doubt, kill the campaign + +Most paid media decisions reduce to scale, hold, or kill. When the analysis is genuinely ambiguous, default to kill. + +The cost of a campaign that is not clearly working is real money flowing out the door every day. The cost of killing a marginal campaign is mostly just the inconvenience of restarting it later. Asymmetric risk. Default to kill. + +The follow-on rule is symmetric. When the hypothesis is clearly confirmed at the magnitude that matters, scale aggressively. The cost of slow-rolling a working campaign is opportunity cost; competitors compound on the same demand pool. Default to scale once the data justifies it. + +Marginal results are the trap. They invite more analysis, more meetings, more "let us give it another two weeks." Two weeks of marginal CAC is two weeks of lost money. Pre-commit the decision rule and execute it. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md b/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md new file mode 100644 index 0000000..3a181f8 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md @@ -0,0 +1,106 @@ +# Ads platform comparison + +Per-platform reporting quirks, attribution differences, and the single-source-of-truth pattern. + +The platforms do not agree on what counts as a conversion or how long a click should attribute. Reading the platform's reported numbers as truth is the most expensive mistake in paid media. + +--- + +## Google Ads + +**Default attribution model.** Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on the platform's machine learning. Single touch attribution (last-click) is available but no longer the default. + +**Conversion windows.** Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA reports by default, which produces the typical 1.3 to 1.5x conversion overcount versus GA. + +**Quirks to know.** +- DDA gives partial credit to keywords that touched the path even if the user did not click. The reported conversion volume under DDA is higher than under last-click. +- Smart Bidding optimizes against the DDA-reported conversions, not GA-reported. Optimizing for one number while measuring against another produces drift. +- View-through attribution on Display and Video is opt-in; default is off. + +**Reading the numbers.** Compare Google Ads conversions against GA's "Google Ads" channel rather than against total GA conversions. The gap between the two is the attribution-model gap; treat with awareness. + +--- + +## Meta (Facebook + Instagram) + +**Default attribution.** 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +**Conversion windows.** 7-day click is the standard. Wider windows are more generous to Meta; narrower windows are more conservative. + +**iOS 14.5+ impact.** App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated based on aggregated behavior) and Conversions API (server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +**Quirks to know.** +- View-through attribution counts impressions even if the user did not click. Often half the reported conversions are view-through. Treat with skepticism for direct response. +- Modeled conversions are a meaningful share of iOS-reported conversions in 2025-2026. They are statistically estimated, not directly observed; do not trust them with the precision you would trust click-based conversions. +- Conversions API (CAPI) sends server-side events that complement pixel events. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. + +**Reading the numbers.** Disaggregate by attribution window in the Ads Manager (1-day click, 7-day click, 1-day view, 7-day view). The 1-day click number is the most conservative and the closest to incremental. + +--- + +## LinkedIn + +**Default attribution.** 30-day click and 7-day view-through. + +**Conversion windows.** Longer than B2C platforms because B2B buying cycles are longer. The 30-day click window matches the typical B2B consideration cycle for many categories. + +**Quirks to know.** +- LinkedIn's reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair with self-reported attribution surveys for B2B. +- Lead Gen Forms count form submissions as conversions; downstream lead qualification is on you to track. +- Demographic insights (job title, seniority, company size, industry) are unique to LinkedIn and uniquely valuable for B2B audience refinement. + +**Reading the numbers.** Lead Gen conversions are easy to overcount because form friction is low; some leads are accidental. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. + +--- + +## TikTok + +**Default attribution.** 7-day click and 1-day view-through (similar to Meta). + +**Conversion windows.** Adjustable. TikTok also supports a "video view" event that is unique to the platform. + +**Quirks to know.** +- Video-completion-based attribution: TikTok counts conversions even when the user did not click but watched the full video. This is real signal for awareness; it inflates direct-response numbers. +- iOS impact similar to Meta but less mature in the modeling. +- Spark Ads attribution is shared between paid and organic. The same view that drove a conversion shows up in both surfaces; be careful not to double-count when reconciling. + +**Reading the numbers.** Click-based conversions are the most reliable. Video-view-based conversions are real signal but should be reported separately. + +--- + +## Cross-platform interference + +Two platforms claiming the same conversion is the single most common attribution mistake. + +**The classic case.** A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). GA might attribute it to organic if the brand search was not paid. Three different views of one conversion. + +**The defense.** A single source of truth in your warehouse or analytics platform. Multi-touch attribution at the warehouse level distributes credit fairly. Marketing-mix modeling (MMM) at the budget-allocation level cuts through the platform-self-attribution bias. + +--- + +## Single-source-of-truth pattern + +Three layers, each serving a different decision. + +**Layer 1: platform metrics.** Use for in-flight optimization only. Ad set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +**Layer 2: warehouse multi-touch attribution.** Use for cross-platform comparison. Each conversion gets attributed across all platforms that touched the path. Common patterns: last-click, first-click, linear, position-based, time-decay, data-driven. Pick one and standardize across the team. + +**Layer 3: marketing-mix modeling (MMM).** Use for budget allocation across channels. MMM treats spend as an input and revenue as an output, modeling the contribution of each channel net of the others. The strongest defense against platform-self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## What the numbers mean in practice + +A typical mid-stage account has the following attribution gap pattern: + +- Google Ads reports: 1.3 to 1.5x what GA reports for "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA reports for "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform-self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md b/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md new file mode 100644 index 0000000..9cedf2a --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md @@ -0,0 +1,87 @@ +# Audience segmentation patterns + +Three audience types treated as separate strategies: prospecting, retargeting, exclusion. Plus cross-platform reconciliation patterns and the most common anti-patterns. + +--- + +## Prospecting + +New people who have not engaged with your brand. The largest budget share for growth-mode brands. + +**Lookalike audiences (Meta, TikTok).** Seed from a high-quality source (top 10% LTV customers, paying customers from the last 90 days, repeat purchasers) and ask the platform for similar users. 1 to 2% lookalikes are tightest and convert best at lower volumes; 5 to 10% lookalikes are looser and scale to volume but convert at lower rates. Start narrow, expand only if the floor holds. + +**In-market audiences (Google).** Google's behavioral signals identify users actively researching a category. Pair with category-relevant keywords for capture, or use as broad targeting on Display, Video, and PMax. + +**Interest stacks (Meta).** Stack multiple interest groups within an ad set. The stack approach lets the algorithm find the overlap. Single interests are usually too narrow; flat lists of 30 interests are too broad. Aim for 5 to 10 related interests. + +**Custom intent or affinity (Google).** Build audiences from URL lists or keyword lists. Useful for niche categories where in-market is not a clean fit. + +**Account lists (LinkedIn).** Upload a target account list and target by company. Pair with job-title or seniority filters to narrow further. The strongest pattern for ABM-style B2B paid. + +The prospecting principle. Start with one well-defined audience that matches your hypothesis. Prove CAC. Then expand. Running five prospecting audiences in parallel before any one is proven is the most expensive way to learn nothing. + +--- + +## Retargeting + +People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC if executed correctly. + +**Window splits.** Different windows have different conversion intents. Run three retargeting tiers with different creative. + +| Window | Audience intent | Creative | +|---|---|---| +| 0 to 7 days | Hot. Recent visitors. | Direct conversion offer. Reinforce value prop. | +| 8 to 30 days | Warm. Considered but did not convert. | Address objections. Social proof. Comparison content. | +| 31 to 90 days | Cool. Long consideration cycle or churned interest. | Reactivate with new offers, new content, or value updates. | + +**Cart abandoner specific.** If e-commerce, cart abandonment is its own retargeting tier. Window: 0 to 7 days. Creative: cart contents reminder, often with a small incentive (free shipping, 10% off). CTR and CAC are usually the strongest of any retargeting segment. + +**Page-specific retargeting.** Visitors to high-intent pages (pricing, demo request, product detail) are warmer than homepage visitors. Run page-specific retargeting at higher bids. + +The retargeting trap. Bidding too aggressively trains the platform to charge a premium for users who would have converted anyway. Cap retargeting CPM and CPC; the high CTR and conversion rate produce strong results without aggressive bids. + +--- + +## Exclusion + +The audiences you do not want paying for clicks from. Saves spend and keeps frequency low. + +**Current customers.** Users with active subscriptions, recent purchases, or active accounts. Exclude from prospecting and most retargeting. Exception: lapsed-cart-from-paying-customer retargeting, which can lift add-to-cart-to-purchase rates. + +**Recent converters.** Users who converted in the last 30 to 90 days. Exclude from prospecting. The platform will keep showing them ads otherwise, which produces frequency fatigue and zero new revenue. + +**Failed-conversion audiences.** Users who clicked repeatedly across a 60 to 90 day window without converting. Build an exclusion list from this segment. They have signaled they are not converting from paid; stop paying to show them ads. + +**Employee lists.** Upload employee email lists and exclude from all paid traffic. Employees clicking on company ads inflate spend and pollute attribution. + +**Cross-platform exclusion.** When running both Meta and Google, exclude Meta retargeting from Google retargeting (and vice versa). Two platforms hitting the same user with the same offer produces frequency fatigue and double-billing. + +--- + +## Cross-platform audience reconciliation + +When running multiple platforms, audience definitions should align so attribution comparisons are meaningful. + +**The seed list problem.** If Meta sees a customer file and Google sees a different customer file, the lookalike sources differ. Reconcile by uploading the same customer list to both, segmented identically (top 10% LTV, last 90 days, etc.). + +**The retargeting overlap problem.** A user who visited the site appears in both Meta retargeting and Google retargeting. Both platforms claim the conversion. Reconcile by running one retargeting platform at a time, or by setting platform-specific retargeting budgets that match the actual incremental contribution. + +**The exclusion problem.** A user who converts on Meta should be excluded from Google paid prospecting (and vice versa). Without cross-platform exclusion, you pay to advertise the same offer to the same user twice. Pipe conversions to a unified audience layer (CDP, warehouse, or audience-sync tool like Synter or Hightouch) and push exclusions back to each platform. + +--- + +## Anti-patterns + +Common mistakes that recur across accounts. + +**Prospecting too narrow.** Audience size below the platform's optimization minimum (Meta: roughly 1M users; Google: roughly 100K). The platform cannot optimize against signal that thin. Expand the audience until it has at least 1 to 5 million reachable users (Meta) or in-market scale (Google). + +**Retargeting too aggressive.** Bidding above the value of the incremental conversion. Half the retargeting "conversions" would have happened anyway from organic; if you bid for them at full attribution, you overpay. + +**No exclusions.** The most common audit finding. Current customers, recent converters, and employees all clicking on paid ads. + +**Lookalike from the wrong source.** Building a 5% lookalike from "all customers" (including low-LTV churners). The platform returns users similar to the average, not similar to your best. Always seed from top-LTV or paid-and-retained customers. + +**Too many ad sets per campaign.** Splitting one campaign into 10 ad sets fractures the data the platform needs to optimize. Consolidate into 2 to 4 ad sets per campaign with audience size sufficient for each to learn. + +**Audience overlap across ad sets.** Two ad sets in the same campaign targeting similar users compete with each other and inflate CPC. Audit overlap with the platform's overlap tool; consolidate ad sets that overlap above 30%. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md b/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md new file mode 100644 index 0000000..f2a4630 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md @@ -0,0 +1,104 @@ +# Bid strategy reference + +Each major bid strategy with definition, fit criteria, common mistakes, and the migration path as data accumulates. + +The decision shape. Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. Pick the strategy that fits the current data state, run it long enough to gather signal, then promote. + +--- + +## Manual CPC or CPM + +**Definition.** Set a max cost per click or cost per thousand impressions. The platform charges no more than the cap. + +**When to use.** Diagnostics. Very early campaigns with no data history. Niche audiences where the platform's machine learning would over-broaden. Branded keyword campaigns where you want explicit cost control. + +**When not to use.** Most production campaigns at scale. Manual scales slowly because every adjustment requires a human decision; automated strategies optimize across thousands of micro-decisions per hour. + +**Common mistakes.** Setting CPC caps below the auction floor (the campaign delivers nothing). Switching from manual to automated too early before there is enough data for the automated strategy to optimize against. + +--- + +## Maximize Conversions + +**Definition.** Platform optimizes for conversion volume within the budget. The platform decides CPC. + +**When to use.** Early-stage campaigns where you want as many conversions as possible regardless of unit cost. Good for gathering the conversion data needed to graduate to tCPA later. Good for awareness or list-building campaigns where volume matters more than per-unit cost. + +**When not to use.** Once CAC is the binding constraint. Maximize Conversions does not respect CAC; it just optimizes for count. + +**Common mistakes.** Running Maximize Conversions for too long when CAC is creeping up. Set a cadence to evaluate the migration to tCPA once you have 30+ conversions in the recent window. + +--- + +## Target CPA (tCPA) + +**Definition.** Set a max CPA. Platform delivers conversions within the target. + +**When to use.** Once you have 30+ conversions in the recent 30 day window for the platform to optimize against. Use when CPA is the constraint and you have enough data for the platform's machine learning to converge. + +**When not to use.** Before you have enough conversion data. The platform cannot optimize tCPA without enough signal; it will either underdeliver or learn against noise. + +**Common mistakes.** Setting tCPA below the prior 30-day actual CPA (platform throttles delivery to almost zero). Setting tCPA too aggressive in a thin-data campaign (same effect; throttled delivery and no learning). Switching tCPA targets every week (each change resets the learning phase). Set the target reasonably (within 15% of recent actual) and let it run. + +--- + +## Target ROAS (tROAS) + +**Definition.** Set a min ROAS. Platform delivers conversions above the target. + +**When to use.** When revenue per conversion varies substantially (e-commerce with mixed AOV, marketplaces with mixed take rates). Once you have 50+ conversions and conversion-value tracking is wired in. + +**When not to use.** Before conversion-value tracking is reliable. Without conversion values, tROAS has nothing to optimize against and falls back to behavior similar to Maximize Conversions but with throttled delivery. + +**Common mistakes.** Setting tROAS too aggressively (platform delivers almost nothing). Not feeding accurate conversion values (the platform optimizes for the wrong number). Switching tROAS targets too often. + +--- + +## Maximum Conversion Value + +**Definition.** Like Maximize Conversions, but the platform optimizes for total conversion value rather than count. + +**When to use.** Same conditions as tROAS, but without a fixed target. Good when you want to maximize revenue within budget without specifying the per-unit ROAS floor. + +**When not to use.** Without conversion-value tracking. Without volume confidence; same as tROAS, the platform needs enough conversions to optimize against value. + +**Common mistakes.** Running without conversion values configured (the platform falls back to count). Treating it identically to Maximize Conversions; the value optimization changes which conversions the platform finds. + +--- + +## Enhanced CPC + +**Definition.** Manual CPC with platform adjustments based on conversion likelihood. + +**When to use.** Rarely. The hybrid muddies the signal. If you want manual control, run pure manual CPC. If you want automation, graduate to Maximize Conversions or tCPA. + +**When not to use.** Most situations. The hybrid is a transitional state from a previous platform default; modern campaigns should pick a clear strategy. + +**Common mistakes.** Treating Enhanced CPC as the safe default. It is neither full control nor full automation; the worst of both. + +--- + +## The migration path + +The progression for a new campaign as data accumulates. + +| Data state | Strategy | Rationale | +|---|---|---| +| Day 1 to ~30 conversions | Manual CPC or Maximize Conversions | Gather data. Platform machine learning has nothing to optimize against yet. | +| 30 to 100 conversions | Target CPA | Platform has enough signal to optimize against a CPA target. Set within 15% of recent actual. | +| 100+ conversions, value tracking on | Target ROAS or Max Conversion Value | Optimize for revenue or ROAS rather than count. | +| Mature campaign at scale | Whichever produces best CAC + ROAS | Stay there. Switching strategies on a mature campaign restarts the learning phase. | + +The migration cadence. Evaluate the migration after every 30 days or every 50% conversion volume increase, whichever comes first. Do not switch every week; the learning phase reset cost is real. + +--- + +## When to NOT switch strategy + +Three signals that suggest staying on the current strategy even when something else looks better. + +1. **Recent change.** If you switched strategy in the last 14 days, give it more time. The learning phase needs at least 2 weeks of consistent volume to converge. +2. **Volatile conversion volume.** If conversion volume is bouncing 50%+ week-over-week, the platform's optimization signal is noisy. Stabilize volume before switching. +3. **Active creative test.** If you are mid-test on creative or audience, do not also change bid strategy. One variable at a time. The bid strategy change muddies the creative test signal. + +The rule. Switch strategy when one variable is stable and the data state has clearly progressed. Avoid stacking changes; you cannot tell which change drove the result. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md b/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md new file mode 100644 index 0000000..9ff0017 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md @@ -0,0 +1,107 @@ +# Budget allocation templates + +Four split patterns plus pacing guidance. Pick the template closest to your situation and adapt. + +The splits operate at the same time: brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. + +--- + +## Template 1: Growth-mode allocation + +For brands actively scaling with a working unit economic model. + +| Bucket | Share | Notes | +|---|---|---| +| Prospecting | 70% | New audience reach. Largest share because growth comes from new demand. | +| Retargeting | 20% | Engaged-but-not-converted users. Small audience, high CTR, low CAC. | +| Test | 10% | Systematic tests of new audiences, channels, or creative concepts. | + +Plus brand-vs-performance: 25% brand, 75% performance for B2C. 50-50 for B2B with longer cycles. + +Plus channel: 60-70% to one primary channel that has proven its CAC, 25% to a secondary, 5-15% to scale-out experiments. + +--- + +## Template 2: Steady-state allocation + +For brands holding scale rather than aggressively pushing it. + +| Bucket | Share | Notes | +|---|---|---| +| Prospecting | 50% | Lower share because steady-state needs less new demand. | +| Retargeting | 30% | Higher share because the existing pipeline is the main flow. | +| Test | 20% | Higher share than growth-mode; steady-state is when systematic testing pays off. | + +Plus brand-vs-performance: 40% brand, 60% performance. The brand share is higher than growth-mode because steady-state is about defending position. + +--- + +## Template 3: Brand-heavy allocation + +For categories where brand investment compounds (premium consumer, B2B with long consideration, regulated industries). + +| Bucket | Share | Notes | +|---|---|---| +| Brand | 60% | Awareness, reach, video at scale. Long-term demand pipeline. | +| Performance | 40% | Search and retargeting on the demand the brand creates. | + +Within performance, 60% prospecting and 40% retargeting is typical. Test budget comes out of the brand share. + +--- + +## Template 4: Performance-heavy allocation + +For DTC and direct-response B2C where the unit economics are tight and brand effects are slow to compound. + +| Bucket | Share | Notes | +|---|---|---| +| Brand | 20% | Minimum viable awareness investment. Mostly content and organic. | +| Performance | 80% | Direct-response paid; CAC is the binding metric. | + +Within performance, growth-mode splits apply: 70% prospecting, 20% retargeting, 10% test. + +--- + +## Pacing patterns + +Budgets that run flat through the month miss the demand peaks and overspend during the troughs. Three pacing patterns to layer onto the daily template. + +**Front-load testing weeks.** When launching a new creative concept or a new audience, front-load 60% of the test budget in the first 7 to 10 days. The platform learning phase needs concentrated signal; spreading too thin means slower convergence. + +**Back-load seasonality.** For categories with a seasonal peak (holiday, end-of-quarter, category-specific moments), shift 30 to 50% of monthly budget into the peak two-week window. Flat budgets through Q4 leave money on the table. + +**Front-load for launch.** For new campaigns with no historical data, front-load creative testing in week one. Accept lower efficiency in week one in exchange for picking the winning creative quickly. By week three the winning concept should be running at scale. + +**Steady for evergreen.** For mature campaigns hitting consistent CAC at scale, run flat daily. The platform's learning is stable; introducing pacing variance creates noise that reduces optimization quality. + +--- + +## Daily vs lifetime budgets + +**Daily budget.** Use for ongoing campaigns where you want a stable spend floor. The platform charges up to your daily cap regardless of opportunity, which is what you want for predictable production work. + +**Lifetime budget.** Use for finite tests where the platform should pace itself across a defined window. Lifetime budgets prevent runaway spend during testing; the platform optimizes pacing so the test ends on the planned date with the planned spend. + +Mistakes. Using daily for tests (the test runs forever or stops abruptly when budget is paused). Using lifetime for evergreen campaigns (the platform front-loads or back-loads in ways you do not want). + +--- + +## Channel split mistakes + +The most common channel-budget mistake is the equal split. Spreading $100K across four channels at $25K each produces four underperforming campaigns; one campaign at $80K plus three at $7K each produces one strong learning signal and three quick reads on whether the others are worth scaling. + +The principle. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the temptation to be balanced. Balanced budgets across unproven channels is the most expensive way to learn nothing. + +The exception. After two channels are proven independently, splitting toward equal is fine because each channel has its own efficient scale. Before that point, concentrate. + +--- + +## Reallocation triggers + +Three signals that the current split needs to shift. + +1. **Primary channel CAC drifted up by 25% over two weeks.** The audience is saturating or competition increased. Shift some budget to the secondary channel and drop the primary's daily. +2. **Test budget produced a new winner.** A test channel or audience is hitting CAC equal to or better than baseline. Promote it to baseline at 15% of total budget; the previous baseline holds 55 to 60%. +3. **Frequency exceeded threshold across the prospecting audience.** The audience saw the creative more than the cap. Either rotate creative or expand the audience; if both are constrained, pull back budget. + +Reallocation cadence: monthly review minimum. Weekly during high-spend periods or active scale-up. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md b/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md new file mode 100644 index 0000000..2d3e007 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md @@ -0,0 +1,197 @@ +# Campaign type reference + +Per-platform campaign type guide. For each campaign type: what it is, when it fits, common pitfalls. + +--- + +## Google Ads + +### Search + +**What it is.** Text ads on Google search results pages, triggered by keyword auctions. + +**When to use.** Direct demand capture. Users searching for category, product, or competitor terms. + +**Pitfalls.** Branded over-spend (cannibalizing free traffic). Broad match on weak keywords (drives garbage clicks). Missing negative keyword lists (paying for irrelevant search terms). Audit search-term reports monthly and add negatives. + +### Shopping + +**What it is.** Product listing ads driven by your Google Merchant Center feed. + +**When to use.** E-commerce with a structured catalog. Comparison-shopping intent. + +**Pitfalls.** Bad feed quality (missing GTINs, weak titles, wrong categories). The feed is the bottleneck; clean it before scaling spend. + +### Performance Max (PMax) + +**What it is.** Automated multi-channel campaign that runs across Search, Shopping, Display, YouTube, Discover, and Gmail. The platform decides placement. + +**When to use.** E-commerce with a strong feed. When you want Google's automation to do the placement work. As a complement to Search, not a replacement. + +**Pitfalls.** Black box optimization makes manual tuning hard. Cannibalizes branded Search traffic; exclude branded queries via account-level negatives. Asset group quality drives results; weak creative produces weak results regardless of platform automation. + +### Display + +**What it is.** Banner and image ads on the Google Display Network (millions of partner sites). + +**When to use.** Retargeting (small audiences, defined intent). Specific contextual targeting where you trust the placement list. + +**Pitfalls.** Display without targeting drives garbage traffic. Default placements include low-quality sites that hurt brand. Use only for retargeting unless you have explicit placement controls. + +### Video (YouTube) + +**What it is.** Video ads on YouTube. Various formats (skippable, non-skippable, bumper, in-feed). + +**When to use.** Awareness at scale. B2C consideration. Underrated for B2B SaaS in some categories where buyer research includes long-form video. + +**Pitfalls.** Direct-response on Video rarely works as well as Meta video. Use for awareness or as an upper-funnel layer. Skippable ads with strong first-5-seconds work; non-skippable annoys. + +### Demand Gen + +**What it is.** Successor to Discovery ads. Visual ads across Discover, Gmail, YouTube Shorts, and YouTube in-feed. + +**When to use.** Visual-first products targeting users in discovery mode (not search mode). + +**Pitfalls.** Newer campaign type with less optimization history; results are more volatile than Search or Shopping. Treat as a tested channel. + +### Discovery + +**What it is.** Visual ads across Google's discovery surfaces. Being merged with Demand Gen. + +**When to use.** Largely deprecated in favor of Demand Gen. Migrate existing Discovery campaigns. + +### App + +**What it is.** Universal App Campaigns for app installs and engagement. + +**When to use.** App promotion. Mostly automated; you provide creative and budget. + +**Pitfalls.** Hard to optimize beyond budget and creative inputs. Track post-install events (subscription, retention) not just installs. + +--- + +## Meta (Facebook + Instagram) + +### Sales + +**What it is.** Campaigns optimized for conversions. The default for direct response. + +**When to use.** E-commerce, subscriptions, lead capture with measurable conversion events. + +**Pitfalls.** Wrong conversion event optimization (optimizing for "Add to Cart" when "Purchase" is what matters). Inadequate pixel setup (the conversion data feeding the algorithm is incomplete). + +### Leads + +**What it is.** Campaigns with native lead forms inside Facebook or Instagram. + +**When to use.** B2B with mid-funnel offers (whitepaper, demo request, newsletter signup). Native forms have lower friction than off-platform forms. + +**Pitfalls.** Lead quality is lower than off-platform forms (less friction, more accidental submissions). Build a CRM enrichment step to filter low-quality leads before passing to sales. + +### Engagement + +**What it is.** Optimizes for likes, comments, shares, page follows. + +**When to use.** Building an organic audience. Almost never as a primary objective for performance work. + +**Pitfalls.** Engagement does not predict conversion. Vanity metrics if used as a primary objective for revenue work. + +### Awareness + +**What it is.** Optimizes for reach and frequency. Brand-style budget. + +**When to use.** Brand at scale. New product launches. Competitor-conquest moments. + +**Pitfalls.** No conversion signal feeding the algorithm. Cannot evaluate against CAC. Use as a brand layer, not a performance layer. + +### Traffic + +**What it is.** Optimizes for clicks (link clicks or landing page views). + +**When to use.** Driving traffic to long-form content, blog posts, awareness pages where the user journey is multi-touch. + +**Pitfalls.** Click-optimized traffic does not predict conversion. The platform finds users likely to click, not users likely to convert. Only use for top-funnel content distribution. + +### App Promotion + +**What it is.** App install campaigns within Meta. + +**When to use.** App promotion specifically. Compare against Google App Campaigns. + +**Pitfalls.** iOS 14.5+ tracking restrictions impact attribution; modeled conversions fill the gap imperfectly. + +--- + +## LinkedIn + +### Sponsored Content + +**What it is.** Sponsored posts in the LinkedIn feed. + +**When to use.** B2B awareness and consideration. Native to the LinkedIn experience. + +**Pitfalls.** High floor (CPM 5 to 10x consumer platforms). Justify with B2B LTV; otherwise unprofitable. + +### Message Ads + +**What it is.** Direct messages delivered via LinkedIn InMail. + +**When to use.** High-intent B2B nudges where the message reads as a personal note. + +**Pitfalls.** Stigma in many segments. Treated as spam if the message reads generic. Personalize aggressively or skip. + +### Conversation Ads + +**What it is.** Multi-step interactive messages with branching CTAs. + +**When to use.** Mid-funnel B2B where multiple value propositions need to be tested in one experience. + +**Pitfalls.** Setup complexity. Many teams underuse the branching capability and run them as glorified Message Ads. + +### Lead Gen Forms + +**What it is.** Native lead forms pre-filled from LinkedIn profile data. + +**When to use.** Highest converting LinkedIn objective. Use whenever the offer is a lead capture (demo, whitepaper, content offer). + +**Pitfalls.** Lead quality varies by form length. Shorter forms get more leads; longer forms filter to higher quality. Iterate. + +### Format types + +Single image, carousel, video. Carousel often outperforms single image for product or feature explainers. Video performs best when shot LinkedIn-native with first-3-seconds hook and captions on by default. + +--- + +## TikTok + +### In-Feed + +**What it is.** Standard ads in the For You Page feed. + +**When to use.** Default TikTok format. Most direct-response and awareness work runs here. + +**Pitfalls.** Polished ad creative is rejected by the algorithm; native-feeling content wins. Iterate creative weekly to avoid fatigue. + +### TopView + +**What it is.** Premium first-impression placement when users open the app. + +**When to use.** Brand moments at scale. Product launches. + +**Pitfalls.** Expensive. Only justify with measurable brand lift or product launch impact. + +### Spark Ads + +**What it is.** Boost an existing organic post as an ad. Retains organic engagement and signal. + +**When to use.** Whenever you have organic posts performing. Spark Ads outperform pure paid creative because they retain the organic-feel signal. + +**Pitfalls.** Requires organic content to exist. If the brand has no organic presence, build one first. + +### Branded Hashtag Challenge + +**What it is.** Sponsored hashtag with branded content prompts. + +**When to use.** Major brand campaigns where user-generated participation matters. + +**Pitfalls.** Expensive. Hard to measure direct response. Best for brands with cultural-moment ambitions, not direct response. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md b/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md new file mode 100644 index 0000000..bf8ec6d --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md @@ -0,0 +1,56 @@ +# Channel decision matrix + +A context-to-channel map. The left column is the situation. The center columns are the recommended channels. The right column is reasoning and what NOT to start with. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. Use the remaining rows as cross-checks. + +--- + +## The matrix + +| Situation | Primary channel | Secondary channel | Reasoning and what to avoid early | +|---|---|---|---| +| Pre-PMF B2B SaaS | LinkedIn (precision) or Google Search (intent) | Content + organic; defer paid scale | Avoid Meta and TikTok early; the audience is not on those platforms. Avoid PMax; you do not have the data state for it. | +| High-AOV B2B (>$5K LTV) | LinkedIn Sponsored Content + Lead Gen Forms | Google Search on category and intent terms | LinkedIn floor is high but justified at this LTV. Avoid TikTok, Reddit, and broad Meta until the LinkedIn motion is repeating. | +| Low-AOV consumer product (<$50 LTV) | Meta (Sales objective) | TikTok (Spark Ads if organic exists) | Avoid LinkedIn (floor too high). Avoid Search unless category-defining query volume exists. Watch payback period; low LTV with paid CAC is razor-thin. | +| DTC with strong visual brand | Meta (Sales + Reels) | TikTok In-Feed and Spark Ads | Avoid LinkedIn. Avoid Display network. Visual-first creative is the moat; double down on the platforms that surface it. | +| Local services | Google Search + Local Service Ads | Meta with geo radius targeting | Avoid TikTok and LinkedIn (wrong intent). Pause off-hours. Geo-radius is the most important targeting lever. | +| Enterprise SaaS (>$50K ACV) | LinkedIn (job-title precision) | Account-Based Marketing platforms + Google Search on category terms | Avoid Meta and TikTok. Avoid broad Display. Pair with ABM on a target account list; audiences are too small for Meta lookalikes to work. | +| E-commerce with catalog | Google Performance Max + Shopping | Meta (Catalog Sales) | Avoid Search-only spend; PMax includes Search and adds catalog placements. Avoid LinkedIn. Feed quality is the bottleneck; fix the feed before spending on PMax. | +| Subscription consumer | Meta (Sales objective with subscriber LTV) | Google Search on intent + brand terms | Avoid LinkedIn. Watch retention; CAC paid back over multiple months means the unit economics window matters more than first-month CAC. | +| Marketplace (two-sided) | Channel-by-side: Meta for consumer side, LinkedIn or Search for supplier side | Reddit niche communities for the supplier side | Run two separate strategies, not one unified plan. The two sides have different intent and need different channels. | +| Pre-launch waitlist | Meta (Engagement or Lead) | Reddit and TikTok organic + light paid | Avoid Search; no one is searching for an unlaunched product. Avoid LinkedIn unless B2B. Cheap CPL but low intent; expect waitlist conversion under 20%. | + +--- + +## Worked examples + +### Example 1: Series B B2B SaaS, $25K ACV, North American sales motion + +The team has a working sales motion and is scaling outbound. They want paid media to add inbound demand without killing CAC. + +**Recommendation.** LinkedIn Sponsored Content as the primary, plus Google Search on category and competitor terms as secondary. Run Lead Gen Forms within LinkedIn to capture demos. Avoid Meta and TikTok early; the buying committee is on LinkedIn and at the office. Budget split: 60% LinkedIn, 30% Search, 10% test (Reddit B2B subreddits, niche newsletters). Watch CAC against the $25K ACV and a 3:1 LTV-to-CAC target. + +### Example 2: DTC adaptogenic soda, $24 AOV, US-only + +The brand has strong visual identity and an organic TikTok presence with one viral post per month. They want to scale paid. + +**Recommendation.** Meta (Sales objective with Catalog) as the primary. TikTok Spark Ads on the existing organic posts as the secondary. Avoid LinkedIn entirely. Avoid Search unless brand search volume justifies defensive spend. Budget split: 60% Meta, 30% TikTok, 10% test (Pinterest for visual discovery). The viral organic posts are the asset; Spark Ads recycle them at scale. Watch payback period; $24 AOV with paid CAC is razor-thin. + +### Example 3: Local home services, three-state operating area + +The team operates plumbing services across three states. They want predictable lead flow. + +**Recommendation.** Google Search plus Local Service Ads as the primary. Meta with geo radius as the secondary for awareness in the operating area. Avoid LinkedIn and TikTok (wrong intent). Pause off-hours unless 24-hour service is a positioning angle. Budget split: 70% Search and LSAs, 20% Meta geo, 10% test (Nextdoor where available). The geo-radius lever is the most important; a 2% mistargeting rate compounds at scale. + +### Example 4: E-commerce, 2,000 SKU catalog, $80 AOV + +The brand has a working e-commerce operation and wants to scale paid media efficiently. + +**Recommendation.** Google Performance Max as the primary (it includes Search, Shopping, Display, YouTube, Discover all in one). Meta Catalog Sales as the secondary. Avoid LinkedIn. Avoid Search-only campaigns; PMax already includes Search. Feed quality is the bottleneck; clean the feed (titles, categories, attributes, GTINs) before spending on PMax. Budget split: 70% PMax, 25% Meta, 5% test. Audit the geo and device cuts inside PMax weekly until the algorithm stabilizes. + +### Example 5: Pre-PMF B2B SaaS, $300K ARR, founders selling + +The team is pre-PMF. The founders are still doing all sales. They want to test paid media without burning runway. + +**Recommendation.** Defer paid scale. Use small Search budget ($2K to $5K per month) on category terms to capture in-market intent. Use LinkedIn organic plus founder-led content as the primary growth motion until PMF is clearer. The signal you would get from paid spend at this stage is too noisy to act on; the budget is better spent on content and outbound. Revisit paid in 6 months if PMF signals firm up. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md b/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md new file mode 100644 index 0000000..c60f2a8 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across paid media accounts. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Scaling but CAC went up + +**Symptom.** You doubled budget on the primary audience. Conversion volume rose less than 2x. CAC drifted up by 20 to 40%. + +**Root cause.** Audience saturation on the primary segment. The platform finds the easiest converters first; pushing more spend into the same audience produces diminishing returns at higher cost. + +**Fix.** Either expand the audience (broader lookalike, additional interests, geo expansion) or diversify across channels. Do not keep pushing the same audience harder; the marginal CAC will keep climbing. + +**Prevention.** Project the saturation curve before scaling. If a 1.5x spend increase doubled CAC over the prior 90 days, expect another 1.5x to push CAC past your threshold. Plan the diversification before the saturation. + +--- + +## 2. Conversions look fine in the platform, terrible in revenue + +**Symptom.** Platform reports stable conversion volume and CAC. Revenue per conversion or LTV is dropping. + +**Root cause.** Attribution mismatch plus customer-quality drift. The platform optimizes for finding "any conversion." The optimizer drifts toward lower-quality converters because they are easier to find. + +**Fix.** Switch from conversion-count optimization to conversion-value optimization (Maximum Conversion Value or tROAS). Feed accurate conversion values into the platform. Tighten audiences toward higher-LTV proxies. + +**Prevention.** Track LTV cohorts per channel monthly. If channel-LTV diverges from blended LTV by more than 15%, investigate the cohort quality before defending the channel. + +--- + +## 3. A/B test winner by 5% + +**Symptom.** Two variations tested. One wins by 5%. The team wants to ship the winner. + +**Root cause.** 5% is within typical platform noise. Across-campaign tests have higher variance than statistical lift implies. + +**Fix.** Re-run the test with more volume. Or run it longer. Or accept that the difference is not meaningful and pick the one that is easier to maintain (cheaper to produce, easier to refresh). + +**Prevention.** Set the minimum detectable effect (MDE) before testing. If the test cannot detect anything below 10%, do not act on a 5% difference. + +--- + +## 4. Turned off underperformer, total conversions dropped + +**Symptom.** A campaign was reading as underperforming. Pause it. Total account conversions drop more than the campaign's reported conversions would suggest. + +**Root cause.** View-through or assist conversions you were not counting in the campaign's CAC. The campaign was contributing upper-funnel exposure that drove conversions on other campaigns. + +**Fix.** Restart the campaign with a held-out portion of the audience to measure incrementality. Compare the held-out cohort against the exposed cohort over 30 days. + +**Prevention.** Run hold-out tests, not flat off-ons. The flat-off causes a discontinuity that is hard to attribute back to the right campaign. + +--- + +## 5. Frequency hit 8 last week + +**Symptom.** Frequency report shows 8 impressions per user last week. CTR is dropping. + +**Root cause.** Creative fatigue. Audience has seen the creative too many times. + +**Fix.** Refresh creative. Rotate in 3 to 5 new variations. Cap frequency explicitly at 4 to 6 per week. + +**Prevention.** Set explicit frequency caps at campaign launch. Track frequency weekly. Refresh creative on a 30 to 60 day cadence at scale, weekly for high-frequency campaigns. + +--- + +## 6. Trying to scale Meta from $20K to $100K per day + +**Symptom.** Aggressive scale plan. Budget multiplier is 5x in one move. + +**Root cause.** That is not scaling. That is a 5x jump that will crash through the audience at the new spend level. Expect efficiency drop of 30 to 50% in the first 14 days. + +**Fix.** Phase the increase. 25% per week is a typical safe pace. Larger jumps should pair with audience expansion or new channels to absorb the spend. + +**Prevention.** Plan the scale curve before starting. 5x in a month is fine if it is 4 weekly 1.4x increases. 5x in a single move is not fine. + +--- + +## 7. LinkedIn for a B2C product + +**Symptom.** Tested LinkedIn for a $40 AOV consumer product. CAC came in at $200. + +**Root cause.** Wrong channel for the offer. LinkedIn's floor is set for B2B economics; B2C does not justify it. + +**Fix.** Stop. Move budget to Meta, TikTok, or Search. + +**Prevention.** Match channel to offer at the strategy stage. Use the channel decision matrix. Do not try platforms because "we should be on LinkedIn"; be on LinkedIn only when the math supports it. + +--- + +## 8. tROAS will not deliver + +**Symptom.** Set tROAS at 4.0. Platform delivers almost no impressions. + +**Root cause.** tROAS target is too aggressive relative to recent performance. The platform throttles delivery to almost zero rather than deliver below the floor. + +**Fix.** Loosen the target to 110 to 115% of the prior 30-day actual ROAS. Let the platform learn at the new target, then incrementally tighten. + +**Prevention.** Set tROAS based on actual recent performance, not aspirational targets. Aspirational targets shut off delivery; pragmatic targets keep volume flowing while improving efficiency. + +--- + +## 9. Search Impression Share dropped + +**Symptom.** Search Impression Share fell from 70% to 50% over two weeks. Conversions held but you are missing volume. + +**Root cause.** Either competition increased (someone else is bidding more aggressively) or budget is constrained (you ran out of daily budget at peak hours). + +**Fix.** Check both. Compare auction-insight reports for new entrants. Check the time-of-day spend distribution; if budget runs out at noon, raise the daily cap. + +**Prevention.** Track Impression Share weekly. Set alerts on 10%+ week-over-week drops. The signal is leading; conversion drops typically follow within 2 to 3 weeks. + +--- + +## 10. PMax is hard to optimize + +**Symptom.** Performance Max is running. CAC is fine. You want to push it harder but cannot find levers. + +**Root cause.** PMax is by design a black box. The platform manages placements, audiences, and creative weighting. The levers you have are budget, asset groups, and exclusions. + +**Fix.** Treat PMax as a tested channel with constrained levers. Optimize via asset group quality (better creative, more variants), audience signals (Customer Match, in-market lists), and exclusions (branded queries, low-value SKUs). + +**Prevention.** Set expectations at launch. PMax is not a place to fine-tune at the keyword level. It is a place to feed strong inputs and let the platform optimize. + +--- + +## 11. Lookalike performance dropped after expansion + +**Symptom.** Expanded the lookalike from 1% to 5% to add volume. CAC drifted up. + +**Root cause.** Wider lookalikes are looser; the floor is lower. The expansion brought in users less similar to the seed. + +**Fix.** Tighten back to 1 to 2% if CAC is the constraint. Or split into two ad sets: the 1% as the workhorse and the 1 to 5% as a separate scale-out audience with its own budget. + +**Prevention.** When you need volume, expand horizontally (add a new audience type) rather than vertically (loosen the existing audience). The horizontal expansion preserves the working audience's CAC. + +--- + +## 12. Brand search lift after a Super Bowl-style ad + +**Symptom.** Brand search volume jumped after a brand campaign ran. Paid attribution did not credit it. + +**Root cause.** Brand effect on existing demand, surfaced in organic and branded paid search rather than the brand campaign's direct-attribution column. The platform's direct response metrics did not capture it. + +**Fix.** Track brand-search lift as a separate metric. Define a baseline brand-search rate before the campaign. Measure the lift during and after. + +**Prevention.** Plan brand campaigns with brand-search lift as a primary KPI, not direct response. Direct response measurement underrates brand campaigns; using it as the only success metric kills brand investment unfairly. + +--- + +## The pattern across all twelve + +Most paid media failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale CAC at the cost of LTV. Pause an underperformer at the cost of total volume. Expand the audience at the cost of the floor. Optimize one platform without checking incrementality. + +The fix at the meta level. Decide on the success metric (CAC, ROAS, LTV-adjusted) and the guardrails (volume, frequency, creative quality, customer-cohort quality) before scaling. Audit guardrails monthly. Pull back the moment a guardrail breaks, even if the success metric still looks fine. diff --git a/dist/pi/.agents/skills/performance-optimization/SKILL.md b/dist/pi/.agents/skills/performance-optimization/SKILL.md new file mode 100644 index 0000000..1bac7fb --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/SKILL.md @@ -0,0 +1,274 @@ +--- +name: performance-optimization +description: "Diagnose and fix web performance issues including Core Web Vitals (LCP, INP, CLS), bundle size, asset optimization, render performance, and runtime efficiency. Use this skill whenever the user wants to improve page speed, fix Core Web Vitals, optimize assets, reduce bundle size, debug slow renders, or systematically improve a site's performance. Triggers on performance, page speed, Core Web Vitals, LCP, INP, CLS, FID, TTFB, bundle size, code splitting, image optimization, lazy loading, render blocking, slow page, performance audit, Lighthouse score. Also triggers when traffic or conversion is dropping due to perceived slowness." +category: development +catalog_summary: "Core Web Vitals, asset optimization, render performance" +display_order: 4 +--- + +# Performance Optimization + +Diagnose web performance issues and produce a remediation plan. Stack-agnostic. Anchored to Core Web Vitals and standard browser performance patterns. + +This skill goes deeper than the performance checks in `qa-testing` and `seo-technical`. Use this when performance itself is the goal. + +--- + +## When to use + +- Fixing Core Web Vitals (LCP, INP, CLS) +- Diagnosing slow page loads +- Reducing JavaScript bundle size +- Optimizing images, fonts, and other assets +- Fixing layout shift, render-blocking resources, jank +- Pre-launch performance verification +- Annual performance health check + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Technical SEO including indexing and crawling (use `seo-technical`) +- Code review for general bugs (use `code-review-web`) + +--- + +## Required inputs + +- The site or page under audit +- Specific performance complaints if any +- Target metrics (Core Web Vitals thresholds, Lighthouse score, custom) +- Browser dev tools access +- Performance monitoring data if available (Real User Monitoring, lab data) + +--- + +## The framework: Core Web Vitals + +Three metrics carry most of the weight for both user experience and SEO: + +### LCP (Largest Contentful Paint) + +**What it measures:** Time until the largest visible content element finishes rendering. + +**Targets:** +- Good: under 2.5 seconds +- Needs improvement: 2.5 to 4.0 seconds +- Poor: over 4.0 seconds + +**Common causes of poor LCP:** +- Slow server response time (TTFB over 800ms) +- Render-blocking JavaScript or CSS +- Large unoptimized images for the LCP element +- Late-loading fonts that delay text render +- Client-side rendering of the LCP element + +**Common fixes:** +- Server-render the LCP element (no client-side render) +- Optimize the LCP image (right format, right size, preloaded) +- Reduce render-blocking resources (defer non-critical CSS and JS) +- Use modern image formats (WebP, AVIF) +- Specify image dimensions to skip layout pass + +### INP (Interaction to Next Paint) + +**What it measures:** Responsiveness to user interactions. Replaces FID as the standard interactivity metric. + +**Targets:** +- Good: under 200ms +- Needs improvement: 200 to 500ms +- Poor: over 500ms + +**Common causes of poor INP:** +- Long-running JavaScript blocking the main thread +- Heavy event handlers +- Excessive React/framework re-renders +- Synchronous operations in event handlers +- Large DOM with expensive layouts + +**Common fixes:** +- Break long tasks into chunks (`scheduler.yield()` or `setTimeout`) +- Memoize expensive computations +- Debounce or throttle high-frequency event handlers (scroll, mousemove, input) +- Avoid synchronous storage or DOM operations in handlers +- Reduce DOM size (under 1500 elements ideal) +- Use CSS over JS for animations where possible + +### CLS (Cumulative Layout Shift) + +**What it measures:** How much the page jumps around as it loads. Unexpected layout shifts hurt usability. + +**Targets:** +- Good: under 0.1 +- Needs improvement: 0.1 to 0.25 +- Poor: over 0.25 + +**Common causes of poor CLS:** +- Images without explicit dimensions +- Ads, embeds, iframes that load late +- Dynamically injected content above existing content +- Web fonts causing FOIT/FOUT (flash of invisible/unstyled text) +- CSS that depends on JS-loaded data + +**Common fixes:** +- Always specify `width` and `height` (or `aspect-ratio`) on images and videos +- Reserve space for ads and embeds before they load +- Use `font-display: optional` or `font-display: swap` thoughtfully +- Avoid injecting content above the fold after initial render +- Preload critical fonts + +--- + +## Beyond Core Web Vitals + +### Time to First Byte (TTFB) + +The server response time. Bad TTFB makes everything else worse. + +**Targets:** under 800ms ideal. + +**Common causes:** +- Slow database queries on the request path +- N+1 query patterns +- Missing caching +- Server geographic distance from users (no CDN) +- Cold starts on serverless + +**Fixes:** +- Cache database queries +- Use a CDN for static and cacheable dynamic content +- Optimize critical-path queries +- Pre-render where possible (SSG, ISR) +- Edge functions for low-latency dynamic content + +### Bundle size + +JavaScript shipped to the browser. + +**Targets:** +- Initial JS under 170KB compressed for typical pages +- Lazy-loaded chunks under 100KB compressed each + +**Common causes of bloat:** +- Importing entire libraries when only one function is used +- Bundling polyfills for modern browsers +- Including dev-only code in production +- Duplicate dependencies (multiple versions of the same library) +- Large client-side state (Redux store snapshots, etc.) + +**Fixes:** +- Tree-shake imports (`import { fn } from 'lib'` not `import lib from 'lib'`) +- Code-split per route +- Lazy-load below-the-fold components +- Audit dependencies; replace heavy ones (e.g., moment.js → date-fns or native Intl) +- Build-time bundle analyzer to spot bloat +- Dynamic imports for rarely-used features + +### Image optimization + +Images are typically 60 to 80 percent of page weight. + +**Best practices:** +- Modern formats: WebP everywhere supported, AVIF where supported +- Responsive images: `srcset` for different viewport sizes +- Lazy loading: `loading="lazy"` for below-the-fold +- Explicit dimensions: prevents CLS +- Right size: don't ship 4000px images for 800px display +- LCP image: preload, never lazy-load + +### Font loading + +Web fonts often delay text render and cause CLS. + +**Best practices:** +- Self-host fonts (avoid third-party blocking) +- Preload critical fonts (`<link rel="preload" as="font">`) +- Use `font-display: swap` for non-critical fonts +- Subset fonts to remove unused glyphs +- Use variable fonts where possible +- Provide system-font fallback that visually matches + +### Third-party scripts + +Third parties (analytics, ads, chat widgets) often dominate performance budgets. + +**Audit each:** +- Is it required? +- Can it load after page interaction (defer)? +- Can it run from a worker (off main thread)? +- Is the third party itself fast? +- Are there lighter-weight alternatives? + +A common pattern: 50 percent of performance issues come from third-party scripts. + +--- + +## Workflow + +1. **Establish a baseline.** Lighthouse scan, WebPageTest run, or Real User Monitoring data. Capture current Core Web Vitals. +2. **Identify the worst offender.** LCP, INP, or CLS - which is failing? Focus there first. +3. **Diagnose specifically.** Browser dev tools (Performance tab, Network tab, Coverage tab). Identify the actual cause of the metric failure. +4. **Plan fixes.** Per identified issue, plan a specific change. Estimate impact and effort. +5. **Implement.** One fix at a time where possible. Easier to measure impact. +6. **Re-measure.** After each major fix, re-run Lighthouse and check Real User Monitoring. +7. **Iterate.** Performance is rarely solved in one pass. Plan for ongoing monitoring and fixes. + +--- + +## Tools + +**Lab tools** (run on demand): +- Lighthouse (built into Chrome DevTools) +- PageSpeed Insights (online) +- WebPageTest (online, more configurable) +- Browser Performance tab (deep flame graph analysis) + +**Field tools** (real user data): +- Chrome User Experience Report (CrUX) - public data for any site +- Real User Monitoring (RUM) - your own users (DataDog, New Relic, custom, etc.) +- Search Console Core Web Vitals report + +Lab tools are useful for diagnosis. Field tools are the source of truth for what users actually experience. + +--- + +## Failure patterns + +- **Optimizing without measuring.** Performance theater without baseline metrics. Always measure first. +- **Optimizing the wrong metric.** A great Lighthouse score with bad real-user metrics means your test conditions don't match users. +- **Over-optimizing.** Spending weeks shaving 10ms off TTFB while CLS is 0.4. Fix the worst offender first. +- **Lighthouse-driven optimization only.** Lighthouse runs in idealized conditions. Always check field data. +- **Single-page optimization.** Performance regressions creep in across the codebase. Build performance budgets and CI checks. +- **Treating every byte as equal.** A render-blocking 100KB script is worse than a deferred 500KB script. +- **Bundle size obsession.** Bundle size matters, but execution time matters more. A small bundle that takes 5 seconds to parse is worse than a larger bundle that runs fast. +- **Ignoring third parties.** "It's the analytics tag, not us." Third parties run on your domain in your users' eyes. Own them. + +--- + +## Output format + +Default output is a performance report at `performance-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools, conditions, sample pages) +3. Current state (Core Web Vitals, Lighthouse scores, RUM data) +4. Critical issues (Core Web Vitals failures) +5. Important issues (sub-optimal but not failing) +6. Polish (further-than-required wins) +7. Remediation roadmap (sequenced) +8. Performance budget recommendations +9. Monitoring plan + +For complex audits, include: +- Per-page Lighthouse exports +- Bundle analysis output +- Network waterfall screenshots +- Specific code snippets to change + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Full performance audit report template. +- [`references/optimization-checklist.md`](references/optimization-checklist.md) - Quick-reference checklist of common optimizations by priority. +- [`references/optimization-playbook.md`](references/optimization-playbook.md) - Symptom-to-fix playbook for the common Core Web Vitals problems (LCP, INP, CLS). diff --git a/dist/pi/.agents/skills/performance-optimization/references/audit-template.md b/dist/pi/.agents/skills/performance-optimization/references/audit-template.md new file mode 100644 index 0000000..a4b256a --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/audit-template.md @@ -0,0 +1,203 @@ +# Performance Audit Report + +A fillable template for documenting a web performance audit. Fill every section. Empty sections signal an incomplete audit. + +The output is the report. The report is what the team acts on. Weak reports produce no fixes. + +--- + +## Audit metadata + +**Site / app:** [Name and URL] +**Pages audited:** [List the specific URLs, not "the site"] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Devices and conditions tested:** +- Mobile: [Device class, network throttling] +- Desktop: [Network throttling] +- Geographies: [If multi-region tested] +**Tools used:** [Lighthouse, WebPageTest, Chrome DevTools, real-user data source, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall state of performance. +2. Whether the site passes Core Web Vitals at the 75th percentile. +3. The single biggest issue and what it costs. +4. The recommended next move. +5. Estimated effort and impact for the top fix. + +> [Summary] + +--- + +## Core Web Vitals scorecard + +Use field data (CrUX, RUM) where available. Lab data (Lighthouse) is a fallback and a diagnostic, not a final verdict. + +| Metric | Target (good) | Mobile p75 | Desktop p75 | Status | +|---|---|---|---|---| +| LCP (Largest Contentful Paint) | < 2.5s | | | Pass / Needs work / Fail | +| INP (Interaction to Next Paint) | < 200ms | | | Pass / Needs work / Fail | +| CLS (Cumulative Layout Shift) | < 0.1 | | | Pass / Needs work / Fail | +| TTFB (Time to First Byte) | < 800ms | | | Pass / Needs work / Fail | +| FCP (First Contentful Paint) | < 1.8s | | | Pass / Needs work / Fail | + +### Trend + +- [ ] Improving over the past 28 days +- [ ] Stable +- [ ] Regressing + +### Field data source + +[CrUX history, Search Console, Sentry, RUM tool. Note the date range and traffic volume that the data covers.] + +--- + +## Page-level findings + +For each audited page, fill out: + +### Page: [URL or template name] + +**Type:** [Marketing / product / app shell / API-driven] +**Traffic share:** [Rough % of site traffic] +**Field metrics (if available):** +- LCP p75: +- INP p75: +- CLS p75: + +#### Lab metrics (Lighthouse mobile, slow 4G) + +- Performance score: +- LCP: +- INP (or TBT as proxy): +- CLS: +- Total page weight: +- Total requests: +- JS payload (parsed): + +#### Top issues on this page + +| # | Issue | Impact metric | Severity | Effort | +|---|---|---|---|---| +| 1 | | LCP / INP / CLS / TTFB | High / Med / Low | S / M / L | +| 2 | | | | | +| 3 | | | | | + +(Repeat the page block for each audited page.) + +--- + +## Cross-cutting findings + +Issues that affect many pages or the whole site. Often higher leverage than per-page fixes. + +### Asset pipeline + +- [ ] Images served in modern formats (WebP, AVIF)? +- [ ] Images served at appropriate sizes (responsive `srcset`)? +- [ ] Critical above-the-fold images preloaded? +- [ ] Below-the-fold images lazy-loaded? +- [ ] Video uses `preload="none"` or poster image until interaction? +- [ ] Fonts subsetted, woff2, `font-display: swap` (or `optional` for stable layout)? +- [ ] Self-hosted vs third-party fonts considered? + +### JavaScript + +- [ ] Bundle size budget defined? +- [ ] Code splitting per route? +- [ ] Third-party scripts inventoried, justified, and budgeted? +- [ ] Unused JavaScript flagged (Coverage tab in DevTools)? +- [ ] Long tasks (>50ms) inventoried? + +### CSS + +- [ ] Render-blocking CSS minimized? +- [ ] Critical CSS inlined for above-the-fold? +- [ ] Unused CSS flagged? + +### Server / network + +- [ ] HTTPS, HTTP/2 or HTTP/3 enabled? +- [ ] Compression (Brotli or gzip) enabled for text assets? +- [ ] Cache headers correct for static assets (long max-age, immutable)? +- [ ] CDN in front of origin? +- [ ] Origin response time (TTFB) measured and acceptable? + +### Layout stability + +- [ ] Images and embeds have explicit `width` and `height` (or `aspect-ratio`)? +- [ ] No layout shift from late-loading fonts? +- [ ] No layout shift from injected ads or banners? + +### Interactivity + +- [ ] Main-thread blocking under 200ms p75? +- [ ] Heavy listeners debounced or moved off main thread? +- [ ] Hydration cost measured (for SSR / partially hydrated frameworks)? + +### Third-party scripts + +| Vendor | Purpose | Bytes | Main-thread cost | Necessary? | +|---|---|---|---|---| +| | | | | | +| | | | | | + +--- + +## Recommendations + +Prioritized action list. Each item is concrete, owned, and sized. + +### Now (this week) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Next (this sprint or month) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Later (this quarter or beyond) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | + +--- + +## Monitoring and re-test plan + +- **Re-test cadence:** [When will the audit be re-run?] +- **Field data tracking:** [Where will Core Web Vitals be tracked over time? CrUX dashboard, RUM tool, Search Console.] +- **Performance budget:** [Define and link the budget. Example: LCP under 2.0s p75 mobile, JS payload under 200KB compressed per route.] +- **Alert thresholds:** [When does someone get paged?] +- **Owner of ongoing performance:** [Person or team] + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- **Lab tests run:** [Tool, settings, run count] +- **Field data window:** [Date range, traffic volume] +- **Throttling profile:** [Slow 4G, Fast 3G, etc.] +- **Geographies tested:** [List] +- **Caveats:** [Anything that limits the audit's confidence, e.g., no field data, low traffic, single-page sample] diff --git a/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md b/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md new file mode 100644 index 0000000..3c53a5a --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md @@ -0,0 +1,138 @@ +# Performance Optimization Checklist + +Quick-reference checklist of common performance optimizations, ordered by typical impact-per-effort. Use it as a triage list, not a script. Skip what does not apply. + +For symptom-to-fix walkthroughs, see `optimization-playbook.md`. For a structured audit report, see `audit-template.md`. + +--- + +## P0: blocks Core Web Vitals at the 75th percentile + +These optimizations almost always pay back. If a site is failing CWV, start here. + +### Images + +- [ ] LCP image is preloaded with `<link rel="preload" as="image" fetchpriority="high">` +- [ ] LCP image is NOT lazy-loaded +- [ ] Images use modern formats (WebP, AVIF) with fallback +- [ ] Images use responsive `srcset` with appropriately sized variants +- [ ] All `<img>` and `<video>` tags have explicit `width` and `height` (or `aspect-ratio` CSS) +- [ ] Below-the-fold images use `loading="lazy"` +- [ ] Decorative images use `decoding="async"` + +### Fonts + +- [ ] Web fonts use `font-display: swap` (or `optional` for layout stability) +- [ ] Font files are woff2 and subsetted to actual glyphs used +- [ ] Critical font files are preloaded +- [ ] Preconnect to font origin if hosted off-domain + +### JavaScript on the critical path + +- [ ] No render-blocking scripts in `<head>` (use `defer` or `async` or move to `<body>` end) +- [ ] Heavy third-party scripts (chat widgets, A/B test tools, analytics) are deferred until interaction or after load +- [ ] Bundle size budget enforced per route +- [ ] Code split per route or feature +- [ ] Unused JavaScript removed (Coverage tab in DevTools) + +### Layout stability + +- [ ] No content insertion above the fold after initial render (banners, ads, popups) +- [ ] Skeleton states or placeholders prevent layout shift on async content +- [ ] Avoid `@font-face` with no fallback chain +- [ ] Avoid web fonts that change metrics significantly between fallback and loaded state (use `size-adjust` and `ascent-override`) + +--- + +## P1: significant gains, moderate effort + +### Server and network + +- [ ] HTTP/2 or HTTP/3 enabled +- [ ] Brotli compression enabled (or gzip if Brotli unavailable) +- [ ] Cache headers correct for static assets: long `max-age` and `immutable` for hashed files +- [ ] CDN in front of origin for static assets (and dynamic where applicable) +- [ ] Origin response time (TTFB) under 800ms at p75 +- [ ] DNS prefetch and preconnect for critical third-party origins + +### Rendering strategy + +- [ ] Above-the-fold content is server-rendered (or static) where possible +- [ ] Critical CSS inlined for above-the-fold +- [ ] Non-critical CSS loaded asynchronously +- [ ] Partial / progressive hydration considered for heavy SPA pages + +### Resource loading + +- [ ] `<link rel="preload">` used for critical assets only (overuse hurts) +- [ ] `<link rel="modulepreload">` used for ESM critical chunks +- [ ] Resource hints (`prefetch`, `prerender`) used for likely next pages on key flows + +### Long tasks + +- [ ] Main-thread tasks over 50ms identified and broken up (`scheduler.yield()`, `requestIdleCallback`, web workers) +- [ ] Hydration cost measured for SSR sites; large components hydrated lazily + +--- + +## P2: smaller gains, useful in aggregate + +### Images and media + +- [ ] Hero video uses `preload="none"` or poster image until interaction +- [ ] Animated GIFs replaced with looped video (smaller, smoother) +- [ ] SVGs optimized (SVGO) and inlined where small +- [ ] Image delivery service (Cloudinary, ImgIX, native CDN image transform) used for on-the-fly resizing + +### Third-party scripts + +- [ ] Each third-party script audited: necessary, budgeted, and optimized +- [ ] Tag manager rules audited; remove unfired or duplicate tags +- [ ] Self-host third parties where licensing allows and origin caching helps + +### CSS + +- [ ] Unused CSS removed +- [ ] CSS specificity audited; avoid expensive selectors (deeply nested, universal) +- [ ] `will-change` and `transform`/`opacity` animations preferred over animating layout properties + +### JavaScript + +- [ ] Tree shaking confirmed working (check final bundle for dead code) +- [ ] Polyfills served only to browsers that need them (differential serving, `module/nomodule` pattern) +- [ ] Date / time / number formatting uses `Intl` instead of large libraries +- [ ] Heavy utility libraries replaced with smaller alternatives or native code where reasonable + +--- + +## P3: polish + +- [ ] Service worker caches critical assets for repeat visits +- [ ] Speculation Rules API used for likely next-page prerender +- [ ] HTTP early hints (103) used for critical preloads +- [ ] Server timing headers exposed for diagnostic visibility +- [ ] Real user monitoring (RUM) feeds CWV dashboard + +--- + +## Anti-patterns to remove + +These appear often, hurt always, and warrant a same-day fix. + +- [ ] Lazy-loaded LCP image +- [ ] Render-blocking analytics or tag manager in `<head>` without `async` +- [ ] Multiple competing fonts (more than 2 families or more than 4 weights) +- [ ] CSS-in-JS that ships runtime style generation to the client without static extraction +- [ ] Hero image larger than its rendered size by more than 2x +- [ ] Synchronous third-party scripts above any user-visible content +- [ ] Layout-shifting cookie banner or consent modal +- [ ] Background images that are CSS-loaded above the fold (preload friendlier as `<img>`) + +--- + +## How to use this checklist + +1. Run a Lighthouse + CrUX read of the 3-5 most important pages. +2. Walk this checklist top to bottom for each page. Mark passes, gaps, and not-applicable. +3. Triage gaps into the audit report (`audit-template.md`) under Now / Next / Later. +4. Re-test after each fix lands. Performance is a moving average, not a snapshot. diff --git a/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md b/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md new file mode 100644 index 0000000..b0419cf --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md @@ -0,0 +1,300 @@ +# Optimization Playbook + +A step-by-step playbook for common performance problems. Pick the symptom, follow the steps. + +--- + +## Symptom: LCP failing (>2.5s) + +The largest content element on the page takes too long to paint. + +### Step 1: Identify the LCP element + +In Chrome DevTools Performance panel: +1. Record a page load +2. Find the LCP marker +3. Note which element is the LCP (usually a hero image or large heading) + +### Step 2: Optimize that specific element + +**If LCP element is an image:** +- Use modern format (WebP, AVIF) +- Serve appropriately sized version (don't ship a 4000px image to a 800px container) +- Preload it: `<link rel="preload" as="image" href="hero.webp" fetchpriority="high">` +- Avoid lazy-loading the LCP image (use eager loading) +- Use `fetchpriority="high"` on the image element + +**If LCP element is text/heading:** +- Ensure web fonts don't block rendering (`font-display: swap`) +- Inline critical CSS for the heading section +- Preconnect to font origin: `<link rel="preconnect" href="https://fonts.example.com">` + +**If LCP is loading slowly because the page is slow overall:** +- See "Symptom: TTFB slow" below +- Reduce render-blocking resources +- Reduce total payload before LCP element + +### Step 3: Measure + +Re-test in Lighthouse and DevTools. Verify LCP under 2.5s on a slow connection (Slow 4G simulation in DevTools). + +--- + +## Symptom: INP failing (>200ms) + +Interactions feel sluggish. The page takes too long to respond to user input. + +### Step 1: Find the slow interactions + +In Chrome DevTools Performance panel: +1. Record while clicking, typing, or interacting +2. Look for long tasks (orange bars >50ms) following input events +3. Identify the function calls that take the longest + +### Step 2: Reduce the work + +**For event handlers:** +- Move heavy work out of the synchronous path +- Use `setTimeout` or `requestIdleCallback` to yield to the main thread +- Debounce or throttle frequent events (scroll, mouse move, resize) + +**For component re-renders (React, Vue, etc.):** +- Memoize expensive computations +- Avoid creating new objects/arrays/functions in render that get passed as props +- Use virtualization for large lists (react-window, virtua, or framework equivalent) +- Profile to find which components re-render and why + +**For startup hydration (SSR/SSG frameworks):** +- Defer hydration of non-critical components +- Use island architecture or partial hydration where supported +- Code-split aggressively below-the-fold + +### Step 3: Verify + +INP should be under 200ms at the 75th percentile of real user data. + +--- + +## Symptom: CLS failing (>0.1) + +Content jumps around as the page loads. + +### Step 1: Identify the shifts + +In Chrome DevTools: +1. Open Performance Insights or Performance panel +2. Look for "Layout Shifts" markers +3. Click each to see what shifted + +### Step 2: Reserve space for dynamic content + +**Common offenders and fixes:** + +- **Images without dimensions.** Add `width` and `height` attributes (or `aspect-ratio` CSS). +- **Late-loading ads or embeds.** Reserve a fixed-size container. +- **Web fonts swapping.** Use `font-display: optional` or size-adjust descriptors. +- **Skeleton loaders that don't match final size.** Match dimensions exactly. +- **Animations triggering layout.** Animate only `transform` and `opacity`. +- **Insertion of content above existing content.** Reserve space or insert below. + +### Step 3: Verify + +Run Lighthouse. Real-user CLS at 75th percentile should be under 0.1. + +--- + +## Symptom: TTFB slow (>800ms) + +Server takes too long to respond. + +### Step 1: Check the server response + +Use WebPageTest or `curl -w "@curl-format.txt" -s -o /dev/null https://example.com` to measure just TTFB. + +### Step 2: Identify the bottleneck + +**Common causes:** + +- **No caching at the edge.** Add a CDN. Set Cache-Control headers correctly. +- **Slow database queries.** Run EXPLAIN on slow queries. Add indexes. Eliminate N+1 patterns. +- **Slow third-party API calls in the render path.** Defer to client or precompute. +- **Heavy server-side rendering.** Profile the SSR work. Memoize what's repeated. +- **Cold starts (serverless).** Provisioned concurrency or warming pings. + +### Step 3: Verify + +TTFB under 600ms at the 75th percentile is the target. Under 200ms is excellent. + +--- + +## Symptom: Bundle size too large + +JavaScript payload bloating the page. + +### Step 1: Audit the bundle + +Run a bundle analyzer (Webpack Bundle Analyzer, source-map-explorer, etc.). Sort by size. + +### Step 2: Identify the offenders + +**Common bloat sources:** + +- **Unused dependencies.** Tree-shaking missing or broken. +- **Whole-library imports.** `import { debounce } from 'lodash'` pulls all lodash. Use `import debounce from 'lodash/debounce'`. +- **Polyfills shipped to modern browsers.** Use differential serving. +- **Source maps in production bundle.** Should be separate files, not inline. +- **Moment.js, Lodash, jQuery.** Often replaceable with smaller alternatives or native APIs. +- **Multiple versions of the same library.** Check `npm ls [library]`. Dedupe. + +### Step 3: Reduce + +- Replace heavy libraries with lighter alternatives (date-fns or dayjs instead of moment, native fetch instead of axios) +- Code-split routes +- Code-split heavy components (modals, charts, editors) +- Use dynamic imports for below-the-fold features + +### Step 4: Set a budget + +In your build config or CI, fail builds that exceed the budget. + +--- + +## Symptom: Image-heavy page loads slowly + +### Step 1: Audit images + +- Count images on the page +- Note current sizes and formats +- Note which are above-the-fold (eagerly loaded) vs below (should be lazy) + +### Step 2: Optimize each + +**Format:** +- Photos: WebP or AVIF (with JPEG fallback) +- Graphics: SVG or PNG (with WebP fallback) +- Animations: video (MP4/WebM) instead of GIF for size + +**Sizing:** +- Generate multiple sizes via `srcset` +- Use `sizes` attribute to tell the browser the rendered size + +```html +<img + src="hero-800.webp" + srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1600.webp 1600w" + sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px" + width="1600" + height="900" + alt="Description" + loading="eager" + fetchpriority="high" +/> +``` + +For below-the-fold: +- `loading="lazy"` +- Without `fetchpriority` + +**Compression:** +- Use a build-time image pipeline (sharp, imagemin) to compress automatically +- Quality 75-85 is usually invisible to users while halving file size + +--- + +## Symptom: Web fonts blocking text + +### Step 1: Audit font loading + +In DevTools Network tab, filter by font. Note: +- File size +- When they load relative to first paint +- Whether text is invisible or fallback during load + +### Step 2: Optimize + +- **Use `font-display: swap`** to show fallback text immediately +- **Subset fonts** to only the characters needed (Latin only is much smaller than full Unicode) +- **Self-host critical fonts** instead of CDN where possible +- **Preload critical fonts:** + ```html + <link rel="preload" href="/fonts/regular.woff2" as="font" type="font/woff2" crossorigin> + ``` +- **Use `size-adjust`, `ascent-override`, `descent-override`** in `@font-face` to match metrics with fallback fonts (reduces CLS) + +--- + +## Symptom: Third-party scripts dragging performance + +### Step 1: Inventory third-parties + +In DevTools Network tab, list all third-party domains. For each: +- Size +- Blocking or non-blocking? +- Necessary? + +### Step 2: Decide on each + +For every third-party script, ask: does the business value justify the performance cost? + +**Common offenders:** +- Heavy analytics (audit if all pixels are necessary; consider server-side tagging) +- Customer support chat widgets (load on user intent, not on page load) +- A/B testing tools (defer non-critical experiments) +- Multiple ad networks (consolidate) +- Tag managers loading hundreds of tags + +**Fixes:** +- Remove unused tags +- Defer non-critical scripts (`async` or `defer`) +- Self-host where licensing allows (avoids extra DNS lookup) +- Load chat widgets on user interaction, not on page load +- Consolidate analytics where possible + +### Step 3: Set a third-party budget + +Number of third-party domains, total third-party JS payload. Block-add for new third-parties without explicit performance review. + +--- + +## Performance budget template + +Set hard limits in your CI to prevent regression: + +```yaml +budget: + - resourceSizes: + - resourceType: total + budget: 500 # kilobytes + - resourceType: script + budget: 200 + - resourceType: image + budget: 200 + - resourceType: stylesheet + budget: 50 + - resourceType: font + budget: 100 + - resourceType: third-party + budget: 100 + - timings: + - metric: largest-contentful-paint + budget: 2500 # milliseconds + - metric: cumulative-layout-shift + budget: 0.1 + - metric: total-blocking-time + budget: 200 +``` + +Tools like Lighthouse CI, Calibre, or SpeedCurve can enforce these budgets in CI. + +--- + +## When to call it done + +A page is "performance optimized" when: + +1. Real-user Core Web Vitals at 75th percentile pass thresholds +2. Lighthouse performance score >90 on representative pages +3. Performance budgets enforced in CI +4. Periodic re-audit scheduled (quarterly minimum) + +Performance is not a one-time project. New code adds weight. New features add complexity. Plan for ongoing maintenance. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md b/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md new file mode 100644 index 0000000..a0bf78d --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md @@ -0,0 +1,260 @@ +--- +name: pillar-content-architecture +description: "How to design a content hub that earns topical authority. Pillar topic selection, cluster planning, internal linking architecture, URL structure, pillar and cluster page anatomy, topical authority signals for SEO and AEO/GEO, and the maintenance discipline that distinguishes intentional hubs from accidental orphans. Triggers on pillar content, content hub, topic cluster, topical authority, content architecture, hub and spoke, pillar page, cluster page, content silo, internal linking strategy. Also triggers when a content set is not ranking despite individual piece quality, when a pillar was launched without a cluster, or when content has accumulated without an architecture." +category: content +catalog_summary: "Hub-level content architecture: pillar topic selection, cluster planning, internal linking, URL structure, pillar and cluster page anatomy, topical authority signals, refresh discipline" +display_order: 1 +--- + +# Pillar Content Architecture + +A senior content architect's playbook for designing content hubs that earn topical authority. + +Most content programs accumulate accidentally. Pieces ship one at a time, internal linking happens (or does not) in editing, similar topics get covered by multiple pieces with no coordination, and six months later the team has a content set that looks like a sitemap but feels like a yard sale. Search engines see disconnected pages; AI engines see scattered citations; readers cannot tell which piece is the entry point and which is the reference. + +This skill is the discipline of intentional hub architecture. It assumes you have decided which topic areas to invest in (see `content-strategy`) and have keyword data (see `seo-keyword`). It does not write any individual piece (see `content-brief-authoring` for per-piece work and `content-and-copy` for execution). What it does is design the structure: which topic gets a pillar, which subtopics get cluster pieces, how the pieces link to each other, where they live in the URL hierarchy, and what topical authority signals the architecture is engineered to produce. + +When to use this skill: launching a new content hub, restructuring an existing content set into a hub, deciding whether a piece should be a pillar or a cluster, or auditing why a content area is not ranking despite individual piece quality. + +--- + +## What this skill is for + +This skill spans hub-level content architecture. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: multiple topic pillars, editorial calendar, governance, formats. Decides what topic areas to invest in across a quarter or year. +- `seo-keyword` is upstream-input: keyword research that surfaces candidate pillar topics with volume, difficulty, and intent data. +- This skill is hub-scope: one pillar plus its cluster, the architecture that ties them together. The structural decisions, not the per-piece content. +- `content-brief-authoring` is per-piece scope: brief for one content artifact. Each cluster piece (and the pillar itself) gets briefed via that skill. +- `content-and-copy` is execution scope: writing the piece itself. +- `seo-content-gap-audit` is audit-side: finds missing pieces in an existing content set after the fact. This skill prevents the gaps; that skill catches the ones that emerge. + +The clean composition: `content-strategy` decides which topics, `seo-keyword` surfaces opportunities, this skill designs the hub, `content-brief-authoring` briefs each piece, `content-and-copy` writes each piece, `seo-content-gap-audit` later catches what slipped. Six skills, sequential. + +The audience: SEO content strategists, content architects, in-house teams designing content hubs, agencies running topical authority programs. The voice is senior content architect to junior content marketer. Concrete, opinionated, honest about what makes a hub earn authority versus decorate the sitemap. + +--- + +## Pillar vs cluster vs orphan content + +The keystone distinction. Three categories of content in any program. + +**Pillar.** Comprehensive piece covering a major topic area. 2,500 to 5,000 words plus. Anchors the topical authority claim for the topic. Receives links from cluster pieces; links out to cluster pieces selectively, not as a footer dump. The pillar is the entry point for the topic and the reference the cluster orbits. + +**Cluster.** Narrower piece covering a specific facet of the pillar topic. 800 to 2,000 words. Links up to pillar; may link sideways to other clusters in the same hub when a connection is natural. Each cluster answers one specific question within the pillar's scope. + +**Orphan.** Piece that does not connect to a pillar or cluster. May rank or convert on its own merits, but does not compound into topical authority. Some orphans are fine by design (release-note pages, customer stories, one-off campaigns); most orphans are accidents. + +The pathology. Most content programs are 80% orphans, 15% accidental clusters, 5% accidental pillars. The discipline is moving toward 70% intentional clusters, 20% intentional pillars, 10% standalone-by-design. Same total content volume; different architectural outcome. + +The reading model. Search engines and AI engines both read internal-link graphs to infer topical authority. A pillar with 12 well-linked cluster pieces signals depth on a topic. 12 orphans on the same topic signal scattered, less-authoritative coverage. The architecture is the signal. + +Detail and decision tree in [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md). + +--- + +## Topic selection for pillar pages + +Not every topic deserves a pillar. The five-criterion selection framework: + +1. **Search volume justifies the investment.** Pillar topic has enough monthly volume to support a 3,000 to 5,000-word effort plus 8 to 15 cluster pieces. Sub-100 monthly searches usually does not. +2. **Topic has natural facets.** You can identify 8 to 15 distinct subtopics that could each be their own piece. If you can only think of 3, it is probably a cluster, not a pillar. +3. **Commercial relevance.** The topic connects to your business model. A pillar without commercial signal is content marketing for content marketing's sake. +4. **Competitive feasibility.** Top 10 SERP for the pillar keyword is achievable. If the SERP is dominated by Wikipedia, government sites, and Fortune 500 brands, your pillar will rank position 47 no matter how good it is. +5. **Editorial commitment.** The team will maintain the pillar (refresh annually, add new clusters, update statistics). Pillars are not ship-and-forget; they are 5-year commitments. + +The "everything is a pillar" anti-pattern. Teams call any 3,000-word piece a pillar. Length does not make a pillar. The architecture does. Pillar is the role a piece plays in the hub structure, not the word count. + +Detail in [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md). + +--- + +## Cluster planning + +Once a pillar is selected, plan its cluster: + +1. **Cluster size.** Typically 8 to 15 pieces for a strong hub. Below 5 reads thin; above 25 becomes unmanageable; sweet spot is 10 to 12. +2. **Cluster facets.** Each cluster piece covers one facet of the pillar topic. Facets are surfaced from keyword research (long-tail variations of pillar keyword), "people also ask" data, sub-headings in top-ranking pillar pages on the SERP, competitor cluster maps, and first-party customer questions (sales calls, support tickets). +3. **No facet duplication.** Two cluster pieces should not target overlapping queries. If they do, consolidate to one piece. +4. **Cluster heterogeneity.** Clusters should cover the topic from multiple angles (definition, how-to, comparison, examples, common mistakes, costs, alternatives, case studies) rather than 12 variations of "what is X." +5. **Sequence.** Ship pillar first (or alongside the first 3 to 5 clusters). The link graph will not form without the pillar in place; clusters that link to a non-existent pillar are orphans-in-waiting. + +Detail in [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md). + +--- + +## Internal linking architecture + +The hub's internal-link graph is what actually produces topical authority signals. The architecture has three directions: + +**Pillar to cluster (top-down).** Pillar links out to each cluster piece via contextual anchors, typically once per cluster from within the pillar's body. Do not bury cluster links in a "related reading" footer; weave them into the relevant section of the pillar where the reader's curiosity peaks. + +**Cluster to pillar (bottom-up).** Every cluster piece links up to the pillar at least once, typically in the first 200 words and again in the closing section. Bottom-up is the discipline that makes the pillar compound; without it the pillar is just a long article. + +**Cluster to cluster (lateral).** Selective lateral linking when one cluster naturally references another. Do not force lateral links; an "everyone links to everyone" cluster is messy and dilutes anchor text relevance. + +**Anchor text discipline.** Vary the anchor text. "Click here" is dead; exact-match keyword stuffing is dead; descriptive natural-language anchors are alive. The brief for each piece (see `content-brief-authoring`) specifies anchor text per outbound link. + +The "linking inventory" pattern. Maintain a sheet (or database row, or dbt model) tracking every link in the hub, who links to whom, and the anchor text used. Audit quarterly to catch broken links, anchor-text drift, and missing connections that should exist. + +Detail in [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md). + +--- + +## URL structure and information architecture + +URL patterns matter for both crawl clarity and reader navigation. Decision factors: + +**Subfolder vs subdomain.** Subfolder is the default (`example.com/hub-topic/cluster-piece`) for SEO consolidation; both pillar and cluster live on the same domain authority. Subdomain is appropriate only for genuinely distinct properties (`docs.example.com`, `community.example.com`). + +**Hub URL pattern.** `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. Avoid `/blog/cluster-piece/` if the goal is hub authority; the URL itself signals topical grouping to crawlers and readers. + +**Slug conventions.** Short, descriptive, keyword-aware but not stuffed. `/seo-content-strategy/keyword-research-for-pillars/` not `/the-ultimate-guide-to-seo-content-strategy-keyword-research-for-pillar-pages-2026/`. + +**Breadcrumbs.** Surface the hub structure in breadcrumb navigation. Helps readers see where they are; helps crawlers see the hierarchy. + +The "/blog/ trap." Teams put pillar and clusters under `/blog/` because that is where the CMS folder is. This works structurally but loses the URL signal that says "these pieces belong together as a topical hub." + +Detail in [`references/url-structure-patterns.md`](references/url-structure-patterns.md). + +--- + +## Pillar page anatomy + +A pillar page does specific work. The standard sections: + +- **Hero.** Defines the topic, signals scope ("The complete guide to X for Y audience"), establishes authority quickly. +- **TL;DR or executive summary.** 150 to 250 words at the top. AI engines often cite this section verbatim. Treat it as the citation-ready summary, not as a marketing intro. +- **Comprehensive body.** Covers the topic's major facets, with internal-link callouts to cluster pieces for deep dives. The body is not a comprehensive treatment of every facet; it is a guided tour with depth links. +- **Use cases or examples.** Anchor the abstract topic to concrete instances. +- **Common mistakes / FAQ.** AI-citation friendly section with structured Q&A. Pair with FAQ schema markup. +- **Closing or next steps.** Directs reader into the cluster (which piece to read next based on intent). +- **Schema markup.** Article or HowTo schema depending on intent; FAQPage schema for the FAQ section. + +Pillar length. 3,000 to 5,000 words is the typical range. Pillar quality is comprehensiveness AND depth, not just word count. A 6,000-word pillar that covers 3 facets is worse than a 4,000-word pillar that covers 12 facets. + +Detail in [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md). + +--- + +## Cluster piece anatomy + +Cluster pieces have a different shape: + +- **Hero.** Focused on one specific question or task, not broad. +- **Pillar callout.** Link up to pillar in the first 200 words. Typical phrasing: "This piece covers X. For the broader context on Y, see our guide to [pillar topic]." +- **Focused body.** Answers the specific question with depth, but does not expand into adjacent facets (those have their own cluster pieces). +- **Lateral callouts (selective).** When relevant, link to 1 or 2 sibling cluster pieces. +- **Closing.** Link back to pillar OR to the next logical cluster piece in a reader journey. + +Cluster length. 800 to 2,000 words typical. A cluster piece longer than 2,500 words is probably a mini-pillar that should either get promoted to its own pillar or be split into two cluster pieces. + +Detail in [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md). + +--- + +## Topical authority signals + +Signals that make hub architecture compound into authority. The two-engine view: pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +**SEO signals:** + +- Internal-link graph density on the topic (PageRank flow within the hub) +- Comprehensive entity coverage across pillar plus clusters (mentioned entities, statistics, citations) +- URL structure clarity +- Breadcrumb hierarchy +- Schema markup (Article, HowTo, FAQPage as appropriate) +- E-E-A-T signals: author credentials, expertise demonstrated, trust signals on every piece + +**AEO and GEO signals:** + +- Answer-paragraph format directly under H2 headings (40 to 60 words, citation-ready) +- TL;DR section on pillars (highly citable; AI engines extract it verbatim) +- FAQ schema (still cited heavily by AI engines including Perplexity and ChatGPT) +- Specific statistics with cited sources +- Named experts and named methods (entities AI engines weight heavily for citation) +- Distinctive POV that AI engines can attribute to your brand + +The two-engine optimization is complementary, not competing. Both reward depth, structure, and entity coverage. The hub architecture creates more surface area for both signal types than scattered orphan content can. + +Detail in [`references/topical-authority-signals.md`](references/topical-authority-signals.md) and the `seo-aeo-geo` skill for AEO/GEO strategy at the program level. + +--- + +## Maintenance and refresh patterns + +Hubs decay if not maintained. The discipline: + +- **Annual pillar refresh.** Every 12 months, audit the pillar against current SERP, update statistics, add new sections for emerged facets, prune sections that no longer matter, refresh internal-link callouts to cluster pieces (since the cluster has likely grown). +- **Cluster refresh as triggered.** Clusters refresh when keyword performance drops, when a new sub-topic emerges, or when a cluster's links go stale. +- **Cluster expansion.** Add new cluster pieces as the topic surfaces new facets. A hub at year 1 might have 8 clusters; year 3 could have 18. +- **Cluster pruning.** Kill cluster pieces that fail to rank or get cited after 12 months. Redirect to the most-relevant remaining cluster or to the pillar. Pruning is not failure; it is hygiene. +- **Hub lifecycle.** Hubs themselves have a lifespan. After 5 to 7 years, even mature hubs may need wholesale restructuring as the topic landscape shifts. + +The "set and forget" failure. Hub launches, ranks, drives traffic for 2 years, then decays without anyone noticing because nobody owns the hub long-term. Hub ownership is durable: single owner across 3 to 5 year horizons, not "the team that launched it." + +Detail in [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pillar-failures.md`](references/common-pillar-failures.md). + +- "We have 80 blog posts but no rankings." Orphan content; no hub architecture. +- "Our 8,000-word pillar does not rank." Comprehensive but no cluster support; pillar without a hub is just a long article. +- "We launched the pillar, never built the cluster." Architecture half-built signals nothing. +- "Cluster pieces do not link to the pillar." Top-down link graph but no bottom-up; the pillar does not compound. +- "Two cluster pieces target the same keyword." Self-cannibalization; consolidate. +- "Pillar URL is /blog/the-ultimate-guide-to..." Losing the URL hub signal. +- "Our pillar is 12 sections of 'what is X'." Facet homogeneity; covers one angle 12 ways. +- "We cannot tell which piece to refresh first." No maintenance ownership; no signals being tracked. +- "Pillar ranks but does not get cited by AI engines." Missing AEO/GEO signals (no TL;DR, no answer paragraphs, no FAQ schema). +- "Hub launched 3 years ago; nobody owns it now." Lifecycle ownership gap. +- "We have 25 clusters and it is chaos." Over-built; sweet spot was 12. + +--- + +## The framework: 12 considerations for hub architecture + +When designing or auditing a content hub, walk these 12 considerations. + +1. **Topic earns the pillar.** Search volume, facet count, commercial relevance, competitive feasibility, editorial commitment. +2. **Cluster size targets 10 to 12.** Sweet spot, not the maximum. +3. **Facet heterogeneity.** Definition, how-to, comparison, examples, mistakes, costs, alternatives. Not 12 variations of "what is X." +4. **No facet duplication.** Clusters cover distinct queries; consolidate when they overlap. +5. **Pillar to cluster to pillar link graph.** Top-down plus bottom-up plus selective lateral. +6. **Anchor text discipline.** Varied, descriptive, natural-language. No stuffing, no "click here." +7. **URL structure signals the hub.** `/topic/` not `/blog/`. +8. **Pillar anatomy includes TL;DR and FAQ.** Citation-ready sections for AI engines. +9. **Cluster anatomy links UP to pillar early.** First 200 words and closing. +10. **AEO/GEO and SEO together.** Two-engine optimization, complementary not competing. +11. **Annual pillar refresh plus triggered cluster refresh.** Maintenance is part of the architecture. +12. **Hub ownership is durable.** Single owner across 3 to 5 year horizons; not "the team that launched it." + +The output of the framework is an architecture document the team can reference at every stage: pillar selected, cluster planned, links specified, URLs chosen, page anatomies templated, refresh cadence set, owner named. + +--- + +## Reference files + +- [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md) - Pillar vs cluster vs orphan decision tree with worked examples and the "everything is a pillar" anti-pattern. +- [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md) - Five-criterion framework expanded with B2B SaaS, ecommerce, services, and media examples. +- [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md) - Facet sourcing methods, sequencing patterns, heterogeneity check. +- [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md) - Top-down, bottom-up, lateral patterns; anchor text discipline; linking inventory; quarterly audit checklist. +- [`references/url-structure-patterns.md`](references/url-structure-patterns.md) - Subfolder vs subdomain decision; slug conventions; breadcrumbs; the /blog/ trap. +- [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md) - Section-by-section anatomy; TL;DR placement; FAQ schema; internal-link callouts; schema choices; length calibration. +- [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md) - Focused-question framing; pillar callout placement; lateral linking judgment. +- [`references/topical-authority-signals.md`](references/topical-authority-signals.md) - SEO and AEO/GEO signals at hub level; two-engine optimization framing. +- [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md) - Annual pillar refresh; triggered cluster refresh; cluster expansion and pruning; hub lifecycle. +- [`references/common-pillar-failures.md`](references/common-pillar-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: architecture is the moat + +Comprehensive content can be replicated. Authoritative sources can be cited. Individual pieces can be matched in quality by competitors with similar resources. What is harder to replicate is the compounding of an intentional hub built and maintained over years: the link graph, the entity coverage, the maintenance discipline, the topical depth signals that build over a 3 to 5 year horizon. + +That is the moat. Architecture is the only part of content marketing that compounds reliably; everything else is execution that can be matched. + +When in doubt about whether a hub is ready, ask: is the pillar selected against the five criteria, are the 10 to 12 clusters planned with facet heterogeneity, is the link graph specified top-down and bottom-up, is the URL structure clean, is the pillar anatomy templated with TL;DR and FAQ, is the refresh cadence set, and is the durable owner named? If yes to all of those, ship the hub plan and let the per-piece briefs and writers work. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md new file mode 100644 index 0000000..85ca692 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md @@ -0,0 +1,120 @@ +# Cluster piece anatomy + +Focused-question framing. Pillar callout placement. Lateral linking judgment. + +--- + +## The shape of a cluster piece + +A cluster piece is not a mini-pillar. Different shape, different work. + +### Hero (first 100 to 150 words) + +Focused on one specific question or task. The hero does not introduce the broader topic; the pillar does that. The hero introduces the cluster piece's specific facet. + +- **Title.** Includes the cluster's primary keyword. Often question-form ("What is a feature flag kill switch?") or task-form ("How to design a feature flag kill switch"). +- **Subhead.** One sentence promising the specific answer. + +### Pillar callout (within first 200 words) + +The bottom-up link to the pillar. Required. + +**Pattern.** "This piece covers feature flag kill switches in depth. For the broader context on rollout strategies that include kill switches as one safety mechanism, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +**Why required.** The pillar callout is the structural signal that this cluster belongs to the hub. Without it, the piece reads as a standalone article and the hub does not compound. + +**Why early.** Crawlers and AI engines weight links higher when they appear near the top of the page. The first 200 words is the citation-prime real estate; the pillar callout there has more impact than the same callout in the closing. + +### Focused body (the bulk of the cluster) + +Answers the specific question with depth. Does not expand into adjacent facets. + +**The discipline.** When the writer notices an interesting tangent into an adjacent facet, they note it as a candidate for another cluster piece and stay on topic. The cluster piece does one thing well; expansion belongs in a different piece. + +**Section structure.** 4 to 6 H2 sections covering the cluster's question from different angles. Each H2 has a featured-snippet-bait answer paragraph (40 to 60 words) followed by 200 to 400 words of development. + +### Lateral callouts (selective) + +When the cluster's body naturally references a sibling cluster, link to it. + +**Pattern.** A cluster on percentage rollouts naturally references kill switches in the section on "what happens when the rollout shows problems." A 1-sentence aside with a contextual link to the kill switches cluster. + +**Frequency.** 0 to 3 lateral links per cluster piece. Some clusters need none; some clusters at the topic's center connect to several siblings. + +**Anti-pattern.** Forced lateral linking. If the connection is not natural to the body's flow, the link is decorative and dilutes anchor signal. + +### Closing + +Two equally valid closing patterns. + +**Pattern A: link back to pillar.** "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns." + +**Pattern B: link to next cluster in a journey.** "If you have your kill switches designed and want to think about progressive rollouts, read our [percentage rollout guide](/feature-flag-rollout/percentage-rollouts/) next." + +The choice. Pattern A is the safe default; it reinforces the pillar and works for most cluster pieces. Pattern B is appropriate when the cluster has a clear "next step" in a reader journey (foundational concept → next concept). + +--- + +## Length calibration + +800 to 2,000 words is the typical cluster range. Calibrate to: + +- **The SERP for the cluster's specific keyword.** Top 10 word counts tell you the band. +- **The cluster's place in the hub.** Foundational clusters (definitions, intros) often run shorter; advanced clusters (deep how-tos, comparisons) often run longer. + +**The 2,500-word cluster trap.** A cluster piece longer than 2,500 words is probably a mini-pillar. Two diagnostic questions: + +1. Does it cover 2+ distinct facets? If yes, split into two cluster pieces. +2. Does it have 8+ H2 sections? If yes, it is structurally a pillar; either promote it (with cluster support) or trim. + +**The 600-word cluster trap.** A cluster piece shorter than 800 words is often too thin to rank for its target keyword. Either: + +- Expand to 1,000+ words with deeper coverage of the question. +- Merge with a sibling cluster if the topic does not have enough depth. +- Demote to a non-hub blog post if the piece is just a brief observation. + +--- + +## Featured snippet bait at H2 level + +Cluster pieces benefit from featured-snippet-bait answer paragraphs at every H2, not just at the top. + +**Pattern.** + +> ## What is a feature flag kill switch? +> +> A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. + +The 40 to 60 word answer paragraph is self-contained and citation-ready. AI engines extract these paragraphs as the canonical answers. + +**Frequency.** Every H2 should have a snippet-bait paragraph. The pattern repeats throughout the piece; it is a structural discipline. + +--- + +## Schema markup for clusters + +Cluster pieces typically use Article schema (or HowTo if the cluster is a step-by-step guide). FAQPage schema applies if the cluster has a real FAQ section. + +BreadcrumbList schema is required for cluster pieces; it tells crawlers the cluster is part of the hub. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +--- + +## When the cluster piece is also useful as a standalone + +Some cluster pieces will rank for queries unrelated to the pillar's topic. A cluster on "kill switches" might also rank for queries about software safety patterns generally. + +The decision: keep the cluster piece in the hub even when it ranks for non-hub queries. The pillar callout costs nothing for the standalone-query reader; the hub-traffic reader benefits from the link. Both audiences are served. + +The exception: when the cluster piece's standalone ranking dominates and the pillar context is misleading to the standalone-query reader, consider splitting into two pieces. Rare; usually the pillar callout works fine for both audiences. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md new file mode 100644 index 0000000..ba1195e --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md @@ -0,0 +1,108 @@ +# Cluster planning patterns + +Facet sourcing methods, sequencing patterns, heterogeneity check. + +--- + +## Facet sourcing methods + +A pillar's cluster is built from 8 to 15 facets. Source them deliberately rather than from the writer's imagination. + +### Method 1: keyword research expansion + +Start with the pillar keyword. Pull the long-tail variations from keyword tools (Ahrefs, Semrush, GSC, dataForSEO). Filter by intent: each cluster facet should have its own SERP intent and dominant format. Variations that share intent with the pillar are not separate facets; they belong inside the pillar itself. + +### Method 2: "people also ask" extraction + +Pull the PAA box for the pillar keyword and 3 to 5 supporting keywords. Each unique question is a candidate cluster facet. PAA is the cleanest signal of what readers actually ask in this topic space. + +### Method 3: top-ranking competitor outline mining + +Pull the top 5 SERP results for the pillar keyword. Extract H2 sections from each. Cluster the H2s across the 5 competitors; sections that appear in 3+ competitors are facets the topic objectively requires. Sections unique to 1 or 2 competitors may be differentiation opportunities. + +### Method 4: first-party customer questions + +Sales calls, support tickets, customer success notes, sales enablement Q&A. The questions customers actually ask are facets the pillar needs to address even if SERP signal is weak. First-party questions also produce differentiation: questions your customers ask but that competitor content does not address. + +### Method 5: Frase or AirOps SERP analysis + +Frase's entity gap analysis and AirOps' workflow builder both run versions of methods 1 to 3 in software. The output is a candidate facet list with SERP coverage scores. Use the tool output as the starting point; refine with first-party questions (method 4) for differentiation. + +--- + +## Sequencing patterns + +How to ship the hub over time. + +### Pattern A: pillar first, cluster follows + +Ship the pillar as a 3,000 to 5,000 word piece. Over the next 6 to 12 weeks, ship 1 to 2 cluster pieces per week. By month 3, the hub has the pillar plus 8 to 12 clusters and starts compounding. + +**When this works.** Strong editorial team that can ship a pillar quickly. The pillar drives initial rankings; clusters fill in topical depth as they ship. + +**The risk.** Pillar ranks for 6 weeks before the cluster is complete; AI engines see a thin hub and may not return to crawl when clusters land. Mitigated by including cluster placeholders in the pillar with "coming soon" or by pre-publishing cluster stubs. + +### Pattern B: pillar plus first 5 clusters concurrent + +Ship the pillar and the first 5 clusters within the same 4-week window. The hub launches with the link graph already partially formed; rankings start with depth signals already in place. + +**When this works.** Larger team or agency support. The launch produces a more credible hub on day 1. + +**The cost.** Higher up-front investment. The first 5 clusters lock the team's editorial capacity for the launch window. + +### Pattern C: prove with 3 clusters, then commit to pillar + +Ship 3 cluster pieces under a planned-but-not-yet-shipped pillar slot. Measure performance over 8 to 12 weeks. If the clusters draw traffic and the topic shows commercial signal, commit to the pillar. If not, pivot to a different pillar topic without the sunk cost. + +**When this works.** Uncertain topic where the commercial signal needs validation before the pillar investment. Common in agencies running pillars for clients without strong upfront conviction. + +**The discipline.** The 3 clusters must be writeable as standalones during the validation window; they cannot reference the pillar by name yet because it does not exist. Once the pillar ships, retrofit the cluster pieces with pillar callouts and bottom-up links. + +--- + +## Heterogeneity check + +A cluster passes heterogeneity if its facets cover the topic from multiple distinct angles. The check: + +**Categorize each facet** by primary angle: + +- Definition (what is X) +- How-to (how to do X) +- Comparison (X vs Y) +- Examples (5 examples of X, X case studies) +- Mistakes (common X mistakes) +- Costs (how much X costs, X pricing models) +- Alternatives (alternatives to X) +- Best-of (best X tools, top X providers) +- Use cases (when to use X) +- Niche variants (X for [specific audience]) +- Foundational (related concept Y that supports X) +- Advanced (advanced X techniques) + +**The rule.** A 12-cluster hub should have facets across 6+ distinct angles. If 10 of 12 are "how-to," the cluster is homogeneous and the pillar will look like a how-to series rather than a topical authority hub. + +**The fix.** When facet brainstorming over-indexes on one angle, deliberately add 2 to 3 facets from different angles. The "5 examples of X" cluster piece is often the most under-served angle; teams forget to add concrete-example pieces and over-invest in abstract how-tos. + +--- + +## No facet duplication + +Two cluster pieces should not target overlapping queries. The check: + +- For each cluster piece, list the 3 to 5 keywords it would target. +- For each pair of cluster pieces, check whether their keyword lists overlap by more than 30%. +- Overlapping clusters compete for the same SERP and self-cannibalize. Consolidate to one piece. + +**The most common duplication.** "What is X" and "X explained" and "X definition" are the same facet. Pick one slug and one focus; do not split the foundational definition across three pieces. + +--- + +## When the cluster is too big + +A planned cluster with 25+ pieces is over-built. The hub becomes unmanageable: maintenance burden too high, link graph too dense to audit, reader navigation confusing. + +**Fix 1.** Split into two pillars under a parent pillar. The original pillar covers the broadest topic; sub-pillars cover major sub-territories with their own clusters. Three-level hierarchy is rare but valid for very broad topics. + +**Fix 2.** Trim to the 12 most-impactful facets. Rank facets by combined search volume + commercial relevance + heterogeneity contribution; keep the top 12; archive the rest as future-cluster candidates. + +The 12-cluster sweet spot is empirical. Below 8, the hub looks thin; above 15, maintenance overhead kicks in; 10 to 12 is the band where most healthy hubs sit. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md b/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md new file mode 100644 index 0000000..9ec094c --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md @@ -0,0 +1,150 @@ +# Common pillar failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "We have 80 blog posts but no rankings" + +**Symptom.** The team has been publishing for 2+ years; 80 pieces shipped; organic traffic is flat or declining. + +**Diagnosis.** Orphan content; no hub architecture. 80 disconnected pieces produce no topical authority signal regardless of individual quality. + +**Fix.** Audit the 80 pieces. Group by topic. For each major topic group, identify or build a pillar; refactor the existing pieces into clusters by adding pillar callouts and bottom-up links. Some pieces will not fit and become standalone-by-design; some will need consolidation. + +The expected outcome: 4 to 6 hubs, each with a pillar plus 8 to 12 clusters; 15 to 20 standalones; the rest pruned. See `pillar-cluster-decision.md`. + +--- + +## "Our 8,000-word pillar does not rank" + +**Symptom.** Team invested in a long, comprehensive pillar; 6 months in, position 23 on the primary keyword. + +**Diagnosis.** Comprehensive but no cluster support; the pillar is a long article without a hub. Length without architectural support does not signal authority. + +**Fix.** Build the cluster. Plan 10 to 12 cluster pieces under the pillar; ship 3 to 5 in the next 8 weeks; complete the cluster within 6 months. Update the pillar with internal-link callouts to each cluster as they ship. See `cluster-planning-patterns.md`. + +The expected outcome: ranking improves over 3 to 6 months as the cluster matures. The pillar that did not rank standalone will rank as the hub forms. + +--- + +## "We launched the pillar, never built the cluster" + +**Symptom.** Pillar shipped 8 months ago; team's editorial focus shifted; the planned cluster never landed. Pillar has 2 supporting pieces shipped haphazardly. + +**Diagnosis.** Architecture half-built. The 2 supporting pieces are functioning as orphans because the hub is not formed; the pillar gets minimal compounding. + +**Fix.** Either commit to completing the cluster (8 to 10 more pieces over 4 to 6 months) or prune the hub. Half-built hubs are worse than no hub; commit or unwind. If completing, prioritize facets the team can ship within 12 weeks. + +--- + +## "Cluster pieces do not link to the pillar" + +**Symptom.** Hub has pillar plus 12 clusters; pillar links to all clusters; only 4 of 12 clusters link back to the pillar. + +**Diagnosis.** Top-down link graph but no bottom-up. The pillar does not compound. Cluster pieces have not been required to include pillar callouts. + +**Fix.** Audit each cluster; add pillar callouts in the first 200 words and the closing of any cluster that lacks them. Update the brief template to require both pillar callouts on every future cluster piece. See `internal-linking-architecture.md`. + +--- + +## "Two cluster pieces target the same keyword" + +**Symptom.** Cluster includes "what is a feature flag" and "feature flags explained." Both rank position 8 to 12 alternately; neither breaks into the top 5. + +**Diagnosis.** Self-cannibalization. Two pieces competing for the same SERP; PageRank splits across two URLs; neither piece gets enough authority to rank top 5. + +**Fix.** Consolidate. Pick the stronger piece (higher current rank, more inbound links, longer URL history). 301 redirect the weaker piece to the stronger one. Merge any unique content from the weaker into the stronger. Update the linking inventory. + +--- + +## "Pillar URL is /blog/the-ultimate-guide-to..." + +**Symptom.** The pillar lives at `/blog/the-ultimate-guide-to-feature-flag-rollout-strategies/` because the CMS routes everything under `/blog/`. + +**Diagnosis.** Losing the URL hub signal. Crawlers cannot infer hub topology from the URL; readers cannot tell from the URL that this is a pillar. + +**Fix.** Migrate to `/feature-flag-rollout/` for the pillar; cluster pieces to `/feature-flag-rollout/[slug]/`. 301 redirect old URLs. Take a short-term ranking hit; gain long-term hub-signal clarity. See `url-structure-patterns.md`. + +The migration is not always worth it. If the pillar is small or the brand's overall content investment is modest, the cost may exceed the benefit. Score against the hub's commercial value. + +--- + +## "Our pillar is 12 sections of 'what is X'" + +**Symptom.** Pillar covers the topic comprehensively in length but every H2 is a definitional question. "What is X." "What does X do." "What are the parts of X." 12 variations of the same angle. + +**Diagnosis.** Facet homogeneity. The pillar covers one angle 12 ways instead of 12 distinct angles. + +**Fix.** Rewrite the pillar's outline using the heterogeneity check (definition, how-to, comparison, examples, mistakes, costs, alternatives, etc.). Replace 8 of the 12 definitional sections with sections covering different angles. See `cluster-planning-patterns.md`. + +--- + +## "We cannot tell which piece to refresh first" + +**Symptom.** Hub has 14 pieces; team knows refresh is needed; cannot prioritize where to start. + +**Diagnosis.** No maintenance ownership; no signals being tracked. Without per-piece performance data, refresh prioritization is guesswork. + +**Fix.** Assign a hub owner (see `content-refresh-patterns.md`). Track 4 metrics per piece: organic traffic, primary-keyword rank, AI citation count if measurable, last-updated date. Prioritize refresh on pieces with declining traffic, slipping ranks, or oldest update dates. The metrics make the prioritization mechanical. + +--- + +## "Pillar ranks but does not get cited by AI engines" + +**Symptom.** Pillar ranks position 4 on Google; brand mention rate from Profound is unchanged after the pillar shipped. + +**Diagnosis.** Missing AEO/GEO signals. Pillar may have no TL;DR, no answer paragraphs under H2s, no FAQ schema, vague statistics, no named experts. + +**Fix.** Audit the pillar against the AEO/GEO signals checklist (see `topical-authority-signals.md`). Add a 150 to 250 word TL;DR at the top. Add 40 to 60 word answer paragraphs under each H2. Mark FAQ section with FAQPage schema. Replace vague statistics with specific numbers and cited sources. Add named experts where the topic supports them. + +The AEO/GEO refresh is faster than the SEO refresh; expect citation improvement within 4 to 8 weeks of changes propagating. + +--- + +## "Hub launched 3 years ago; nobody owns it now" + +**Symptom.** Hub built by a content lead who left 18 months ago. No formal owner since. Performance has degraded; nobody noticed. + +**Diagnosis.** Lifecycle ownership gap. The "set and forget" failure mode. + +**Fix.** Assign a new owner. Allocate 1 to 2 weeks of editorial time for an emergency refresh: re-validate the SERP, update statistics, prune dead sections, refresh internal links. Set the annual refresh cadence going forward; track ownership renewal in the hub's planning doc. See `content-refresh-patterns.md`. + +Some hubs at this stage are unrecoverable. If the SERP has shifted enough that the original architecture no longer fits, restructure rather than refresh; treat as a year-5+ lifecycle event. + +--- + +## "We have 25 clusters and it is chaos" + +**Symptom.** Hub started at 12 clusters; expanded over 3 years to 25; the linking inventory is unmanageable; new pieces tangle with old pieces; readers cannot find what they need. + +**Diagnosis.** Over-built. The cluster expanded beyond the manageable sweet spot. + +**Fix.** Prune. Apply the cluster pruning criteria (see `content-refresh-patterns.md`): clusters that have not ranked in top 30 after 12 months, clusters with zero search volume, clusters that duplicate other clusters. Aim to trim back to 12 to 15 active clusters; archive the rest with redirects. + +Alternative: split into two pillars under a parent topic. Rare; valid only for genuinely broad topics. + +--- + +## "We did all the SEO work but the AI engines do not cite us" + +**Symptom.** Pillar ranks well; clusters rank well; brand mention rate from Profound is flat. AI engines cite competitors instead. + +**Diagnosis.** Could be either: + +- The hub is structurally fine for SEO but missing AEO/GEO signals (see "pillar ranks but does not get cited" above). +- The hub is missing distinctive POV. AI engines preferentially cite content with attributable claims; content that reads as SEO consensus does not get cited even when it ranks. + +**Fix.** Audit each pillar and high-traffic cluster for distinctive claims. Add at least one strong POV per piece: a position the team is willing to defend, a recommendation that is not "it depends," a specific claim with named experts and statistics behind it. Bland comprehensive content does not get cited; opinionated comprehensive content does. + +--- + +## "We have a hub but conversions are flat" + +**Symptom.** Hub drives traffic, ranks well, gets cited; trial signups attributable to the hub are flat. + +**Diagnosis.** Topical authority is working; commercial conversion is not. The hub's content does not connect cleanly to the buyer journey. + +**Fix.** Audit the pillar and clusters for commercial CTAs. Each cluster should have a clear next step that is NOT just "read another cluster." Trial signup, demo request, content download, newsletter subscription. The hub is producing the audience; the conversion path needs separate design work. + +This failure is outside this skill's scope to fully solve; pair with `landing-page-copy` for conversion-focused next-step pages and `content-strategy` for funnel-aware content planning. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md new file mode 100644 index 0000000..3517077 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md @@ -0,0 +1,164 @@ +# Content refresh patterns + +Annual pillar refresh checklist. Triggered cluster refresh signals. Cluster expansion patterns. Cluster pruning criteria. Hub lifecycle (5 to 7 year horizon). + +--- + +## Why refresh matters + +Hubs decay. Statistics go stale; SERPs shift; new facets emerge; existing pieces drift from current best practice. A hub that ranks at year 1 often falls to position 12 by year 3 if nobody refreshes it. + +The discipline is built into the architecture: refresh is not an afterthought; it is a budgeted activity. + +--- + +## Annual pillar refresh checklist + +Run every 12 months on each pillar. Allocate 1 to 2 weeks of editorial time per pillar. + +### Step 1: re-validate the SERP + +Pull the current SERP top 10 for the pillar's primary keyword. Compare to the last refresh's top 10. + +- Are new competitors in the top 10? What are they covering that you are not? +- Have existing competitors updated their pillars? What new sections did they add? +- Has the SERP intent shifted (e.g., from informational to commercial-investigation)? + +### Step 2: update statistics + +Find every numeric claim in the pillar. Verify each is still accurate; replace stale numbers with current ones; cite the new source. + +**Common stale numbers.** Industry statistics that were "as of 2023" and now are 2 years old. Pricing references that have shifted. Tool capabilities that have evolved. + +### Step 3: add new sections for emerged facets + +Did the topic surface new facets in the last 12 months? Add H2 sections covering them. Each new section should be 300 to 500 words; if it grows beyond 700, promote it to a new cluster piece and reduce the pillar section to a callout. + +### Step 4: prune sections that no longer matter + +Did old sections become irrelevant? Maybe a tool you covered shut down; maybe a method you described was deprecated. Cut or significantly trim those sections. Pillar bloat from un-pruned content is the most common pillar-decay symptom. + +### Step 5: refresh internal-link callouts to clusters + +The cluster has likely grown since last refresh. Add callouts to any new cluster pieces that did not exist before. Verify all existing callouts still link to live cluster URLs. + +### Step 6: update the TL;DR + +The TL;DR captures the pillar's argument as of the refresh date. Revise to reflect any structural changes: new facets, removed sections, shifted POV. + +### Step 7: bump the last-updated date + +Set the publish-modified date to the refresh completion date. The freshness signal matters; do not skip it. + +### Step 8: re-submit to search engines + +Submit the updated pillar URL to Google Search Console for re-crawl. Some teams also ping AI engine indexing endpoints (Perplexity, Bing for Copilot) where available. + +--- + +## Triggered cluster refresh signals + +Clusters do not need annual refresh; they need triggered refresh when specific signals appear. + +### Trigger 1: keyword performance drops + +The cluster's primary keyword falls 5+ positions in 30 days. The drop is the signal; pull the SERP, identify what is now ranking ahead, and update the cluster to compete. + +### Trigger 2: new sub-topic emerges + +Within the cluster's facet, a new sub-topic appeared (new tool launched, new technique published, new regulation issued). Update the cluster to reference the new sub-topic. + +### Trigger 3: cluster's links go stale + +The quarterly link audit (see `internal-linking-architecture.md`) finds broken outbound links from the cluster. Update the cluster with new links. + +### Trigger 4: AI citation drops + +The cluster was being cited by AI engines and the citation count drops. Check whether content drifted, whether new entities should be added, whether the answer paragraphs need tightening. AI citation drops are slower-moving than ranking drops; act on month-over-month trends, not week-over-week. + +### Trigger 5: customer feedback surfaces a gap + +A sales rep, support agent, or customer success manager flags that the cluster does not cover a question customers actually ask. Add the section. + +--- + +## Cluster expansion patterns + +A hub at year 1 might have 8 clusters. Year 3 could have 18. Expansion happens deliberately, not opportunistically. + +### When to expand + +- A new facet emerges and customer questions confirm demand. +- Competitor analysis shows a facet your hub does not cover. +- Keyword research surfaces new long-tail variations with traffic. +- AI citation patterns show queries your hub does not address. + +### When not to expand + +- Tempting facet but no customer demand. Adds maintenance burden without driving traffic. +- Facet already covered by another piece on the site outside the hub. Either move that piece into the hub or update its links. +- Facet is too narrow (sub-100 monthly searches with no commercial signal). Add as a section to an existing cluster, not as its own cluster. + +### Expansion cap + +Max 20 clusters per pillar. Above that, the hub becomes unmanageable. If the topic genuinely supports 25+ facets, split into two pillars under a parent topic (rare; valid for very broad topics). + +--- + +## Cluster pruning criteria + +Some clusters should die. Pruning is hygiene, not failure. + +### Prune when + +- Cluster has not ranked in top 30 after 12 months despite refresh attempts. +- Cluster's keyword has gone to zero search volume. +- Cluster duplicates another cluster (consolidate). +- Cluster covers a tool, technique, or topic that no longer exists. + +### How to prune + +- 301 redirect the URL to the most-relevant remaining cluster, or to the pillar. +- Remove links from the pillar and other clusters to the pruned URL. +- Update the linking inventory. + +### What not to do + +- Do not delete the URL without redirecting; 404s waste any acquired authority. +- Do not redirect to the homepage; redirect to the most topically-relevant alternative. + +--- + +## Hub lifecycle (5 to 7 year horizon) + +Hubs themselves have lifespans. After 5 to 7 years, the topic landscape often shifts enough that wholesale restructuring becomes appropriate. + +### Signs the hub needs restructuring (vs annual refresh) + +- The pillar's primary keyword has shifted intent (the SERP is now showing a different content type). +- Competitors have rebuilt their hubs around a different angle that better matches current reader needs. +- The cluster has grown unwieldy (25+ pieces) and the topical organization no longer makes sense. +- AI citation patterns suggest readers are asking questions the original hub structure cannot answer. + +### Restructuring approach + +- Treat the restructuring as a new hub launch. Plan the new pillar and cluster shape first. +- 301 redirect old pillar and cluster URLs to new equivalents where possible. +- Archive content that does not fit the new structure rather than force-fitting. +- Communicate the change in a release-note-style post linked from both old and new URLs during the transition. + +The 5-to-7 year cycle is empirical. Some hubs last longer (foundational topics like "what is SEO"); some need restructuring sooner (fast-moving topics like "AI search"). Ownership tracks the lifecycle; the durable hub owner is the one who decides when to restructure. + +--- + +## Maintenance ownership + +The pillar owner is named and durable. Common patterns: + +- **Single editor.** One person owns the hub for a 12-month commitment. Renewed annually. +- **Editor + SEO partner.** Editor owns content; SEO partner owns rankings and link audits. +- **Cross-functional team.** Editor, SEO, product marketing rotate quarterly reviews. Works for large teams; falls apart in small teams (rotation diffuses ownership). + +The "set and forget" failure mode happens when ownership dissolves. The team that launched the hub disbanded, was reorganized, or moved on; nobody picks up maintenance. Six quarters later, the hub has decayed and recovery costs more than the original launch. + +The fix. Assign a durable owner before the hub launches. Renew the assignment annually. Track the owner's continued ownership in the hub's planning doc; surface in quarterly reviews. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md b/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md new file mode 100644 index 0000000..805f61f --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md @@ -0,0 +1,100 @@ +# Internal linking architecture + +Top-down, bottom-up, lateral linking patterns. Anchor text discipline. The linking inventory pattern. Quarterly link audit checklist. + +--- + +## The three link directions + +A hub's link graph has three directions; all three need discipline. + +### Top-down: pillar to cluster + +The pillar links out to each cluster piece via contextual anchors woven into the pillar's body. The reader is reading the section on, for example, "kill switches"; that section includes a contextual link to the cluster piece on kill switches. + +**Pattern.** "Most rollouts include a kill switch as a final safety net. For the full pattern including code-level implementations, see [our guide on kill switch design](/feature-flag-rollout/kill-switches/)." + +**Anti-pattern.** A "Related reading" footer at the bottom of the pillar listing 12 cluster links. Footer links pass less topical signal and read as decorative; contextual body links read as load-bearing. + +**Frequency.** One link per cluster from within the pillar. Two links to the same cluster from the pillar is fine if the cluster covers two distinct sections; three links to the same cluster suggests the pillar should reference the cluster more selectively. + +### Bottom-up: cluster to pillar + +Every cluster piece links up to the pillar at least twice. First in the introduction (within the first 200 words); second in the closing. + +**Pattern in introduction.** "This piece covers kill switches in feature flag rollouts. For the broader context on rollout strategies, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +**Pattern in closing.** "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns, or jump to [percentage rollouts](/feature-flag-rollout/percentage-rollouts/)." + +**Why two.** First link tells crawlers and readers the topical context immediately. Second link captures readers who got value from the cluster piece and want to dig deeper into the hub. + +### Lateral: cluster to cluster + +Selective. When one cluster piece naturally references another, link with descriptive anchor text. Do not force lateral links. + +**Pattern.** A cluster on "percentage rollouts" naturally references "kill switches" when discussing what to do if the rollout shows problems. The lateral link is contextual; the reader is at a moment where the related cluster is actually useful. + +**Anti-pattern.** Every cluster piece links to every other cluster piece. The link graph becomes complete-graph-shaped; anchor text relevance dilutes; PageRank flow is undirected and weaker. + +**Frequency.** 1 to 3 lateral links per cluster piece is typical. Some clusters need zero lateral links; some clusters that sit at the center of a topic naturally connect to 5 sibling clusters. + +--- + +## Anchor text discipline + +Anchor text is the signal that tells search engines what the linked-to page is about. The discipline: + +**Vary the anchor text.** Do not link to the pillar with the exact same phrase every time. Use the pillar's primary keyword, secondary keywords, and natural-language phrases that describe the linked page. + +**Descriptive natural-language anchors.** "See our guide to feature flag rollout strategies" beats "click here to read more." The anchor text should make sense if it is the only thing the reader reads. + +**No over-optimization.** Do not stuff every link with exact-match keywords. Anchor text that varies naturally is what a real authority cluster looks like; uniform exact-match anchors signal manipulation to ranking systems. + +**Brand-mention anchors.** Sometimes the right anchor is the brand name or product name when linking to a product page. "RampStack's experimentation skill" is a brand anchor; "experimentation skills documentation" is a descriptive anchor. Mix both. + +**Common dead anchors.** "Click here," "this article," "read more," "more info." All dead. They pass minimal topical signal and waste the link's potential. + +--- + +## The linking inventory pattern + +Maintain an inventory of every link in the hub. The format depends on the team's tooling. + +**Spreadsheet.** Columns: source page slug, target page slug, anchor text, link section (intro / body / closing / sidebar), link direction (top-down / bottom-up / lateral / external). + +**Notion database.** Same columns as relations, queryable per page or per direction. + +**dbt model with content metadata.** For warehouse-native content tracking; the link graph becomes a queryable table that compounds with other content metrics (rank, citation count, conversion). + +**CMS audit fields.** Some CMSs (Contentful, Sanity, custom WordPress) allow per-page metadata fields. Track outbound links per piece; aggregate at the hub level. + +The inventory enables the quarterly audit; without it, the audit becomes a manual scan that misses things. + +--- + +## Quarterly link audit checklist + +Run every 90 days. Catches the failures that compound silently. + +1. **Broken outbound links.** Crawl every cluster piece for 404s on outbound links. Common cause: cluster piece was renamed or moved without redirect. +2. **Missing bottom-up links.** Every cluster should link to the pillar in intro and closing. Audit checks both. +3. **Missing top-down links.** Pillar should link to every cluster from within the body. Audit checks each cluster has at least one body link from the pillar. +4. **Anchor text drift.** Same anchor text used by 5+ links to the same target reads as over-optimized. Vary by editing 2 to 3 of them. +5. **Dead anchors.** "Click here" or "read more" anchors that crept in during writing. Replace with descriptive anchors. +6. **Lateral over-linking.** Cluster pieces linking to 5+ siblings reads as complete-graph noise. Trim to 2 to 3 most-relevant siblings. +7. **Orphan clusters.** Cluster piece that no other piece links to (besides the pillar). The pillar's top-down link is required; ideally 1 to 2 sibling lateral links also exist. +8. **Stale references.** Cluster pieces that reference statistics, products, or pages that no longer exist. Update the references; refresh the piece if the underlying topic shifted. +9. **New cluster integration.** When a new cluster piece ships, audit confirms it received its top-down link from the pillar AND its bottom-up plus lateral links. New clusters often miss the inbound updates that would prevent orphan status. +10. **Anchor diversity.** Pull the inventory; group anchor texts by target page. If 8 of 10 links to a page use the same anchor, edit 3 to 5 to vary. + +The audit takes 1 to 3 hours per hub. The cost is real but smaller than the cost of letting the link graph decay. + +--- + +## When the link graph is too dense + +Some teams over-link. Every cluster piece has 8 outbound contextual links plus 5 lateral plus 3 external. The reader is bombarded; the anchor text relevance dilutes. + +**Heuristic.** A cluster piece with more than 6 outbound internal links per 1,000 words is over-linked. Trim to the 4 to 6 highest-relevance links. + +The trim improves both reader experience and PageRank concentration. Each remaining link gets more weight; the link graph becomes more legible to crawlers. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md new file mode 100644 index 0000000..a5fe670 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md @@ -0,0 +1,98 @@ +# Pillar vs cluster vs orphan decision + +The decision tree, worked examples, and the "everything is a pillar" anti-pattern. + +--- + +## The decision tree + +When a new piece is being planned, walk these questions in order. + +**Question 1.** Does this topic have 8 to 15 distinct facets that could each be a separate piece? + +- Yes: this might be a pillar. Continue to question 2. +- No: this is not a pillar. Continue to question 4 to test cluster fit. + +**Question 2.** Is the topic competitive enough to require comprehensive coverage to rank? + +- Yes (top 10 SERP shows long-form pillars from authoritative sources): pillar candidate confirmed. Continue to question 3. +- No (top 10 SERP shows short articles or tools): the topic does not need a pillar. A cluster piece probably suffices. + +**Question 3.** Is the team committed to maintaining this pillar for 3 to 5 years (annual refresh, cluster expansion, ownership)? + +- Yes: ship as pillar. Plan the cluster. +- No: do not start. A pillar without maintenance is worse than no pillar; it ranks for a year, then decays. + +**Question 4.** Is there an existing pillar this piece could connect to as a cluster? + +- Yes: ship as cluster. Specify the pillar callout and the bottom-up link in the brief. +- No: continue to question 5. + +**Question 5.** Is this piece intentionally standalone (release note, customer story, one-off campaign, executive announcement)? + +- Yes: ship as standalone. Standalone-by-design is fine. +- No: this is an accidental orphan. Either build the pillar first, or postpone the piece until a pillar exists, or rescope the piece to fit an existing pillar's cluster. + +--- + +## Worked examples + +### Example 1: "Feature flag rollout strategies" + +A B2B SaaS team is planning a piece on feature flag rollout strategies. + +- 8 to 15 facets? Yes: percentage rollout, ring deployment, canary, blue-green, kill switches, automatic rollbacks, rollout per cohort, rollout by geography, rollout by plan tier, etc. ✓ +- Competitive SERP? Top 10 are long-form articles from LaunchDarkly, Statsig, Optimizely. Pillar candidate confirmed. ✓ +- 3 to 5 year commitment? The team plans to expand the cluster as new patterns emerge. ✓ + +Decision: pillar. Plan 10 to 12 cluster pieces around it. + +### Example 2: "How to set up a Statsig experiment" + +The same team is planning a how-to on Statsig experiment setup. + +- 8 to 15 facets? No. The topic is one task with maybe 5 sub-steps. ✗ +- Existing pillar to connect to? Yes: the team has an "experimentation" pillar. + +Decision: cluster. Pillar callout to "experimentation" pillar; link up in first 200 words and closing. + +### Example 3: "Q3 2026 product release notes" + +The marketing team is planning a quarterly release-notes post. + +- 8 to 15 facets? No. ✗ +- Existing pillar to connect to? Not a topical fit; release notes are a different content type. +- Standalone-by-design? Yes; release notes serve customers tracking the product, not topical authority. + +Decision: standalone. Do not force into a hub; serve the customer tracking purpose. + +### Example 4: "What is a feature flag?" + +A piece on the basic definition. + +- 8 to 15 facets? No. The topic is one definition. ✗ +- Existing pillar to connect to? Yes: the "feature flag rollout strategies" pillar from example 1 needs a "what is a feature flag" cluster piece for the foundational facet. + +Decision: cluster under the feature flag rollout pillar. The pillar gets the cluster it needs; the piece gets the topical context it needs. + +--- + +## The "everything is a pillar" anti-pattern + +The symptom. Every 3,000-word piece on the team's site is called a pillar. The marketing team uses the word loosely; the SEO team uses it strictly; nobody agrees on what makes a pillar. + +The diagnosis. Length is being treated as the pillar criterion. Length does not make a pillar. The architectural role does. A 3,000-word piece with no cluster supporting it is a long article, not a pillar. A 1,500-word piece with 12 cluster pieces linking up to it is closer to a pillar than the 3,000-word standalone, even though the word counts are reversed. + +The fix. Use the word "pillar" precisely. Pillar is a piece that anchors a hub. If there is no hub, there is no pillar. Long articles that are not anchoring hubs are just long articles, and that is fine; they do not need to be promoted to "pillar" to justify the investment. + +The diagnostic question. "What pieces link up to this pillar?" If the answer is "none yet" or "we are planning to add some," the pillar is not yet a pillar. It is a planned pillar that becomes a real pillar when the cluster ships. + +--- + +## When the decision is hard + +**The "almost a cluster" case.** A piece is 1,800 words, covers a specific facet of an existing pillar, and would link up to the pillar. Sounds like a cluster. But the piece also stands alone for non-hub queries. Decision: ship as cluster. The pillar callout is cheap; the topical compounding is real. The "standalone-by-design" exception is for pieces that have a different purpose (release notes, customer stories), not for pieces that happen to be readable alone. + +**The "almost a pillar" case.** A piece is 3,500 words, covers a topic with 6 facets (not 8 to 15), and the SERP for the topic is moderately competitive. Decision: ship as a long cluster piece under a broader pillar, or postpone until the topic surfaces more facets. Forcing 3,500 words into a 6-facet topic creates the "pillar with 12 sections of 'what is X'" failure mode. + +**The "we already have 5 standalone pieces on this topic" case.** No pillar exists; 5 orphans cover related facets. Decision: build the pillar, then refactor the 5 orphans into clusters by adding pillar callouts and bottom-up links. The hub is being created from existing content rather than from scratch; this is faster than starting over and works well when the orphans are already decent. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md new file mode 100644 index 0000000..c3ba778 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md @@ -0,0 +1,144 @@ +# Pillar page anatomy + +Section-by-section anatomy. TL;DR placement and length. FAQ schema. Internal-link callout placement. Schema markup choices. Length calibration. + +--- + +## Section-by-section structure + +A pillar page does specific work across a recognizable set of sections. + +### Hero (first 200 words) + +Defines the topic, signals scope, establishes authority quickly. + +- **Title.** Includes the primary keyword. Reads as comprehensive ("The complete guide to feature flag rollout strategies"). +- **Subhead.** One sentence promising specific value to a specific audience. +- **Author / publish / update line.** Author name with link to bio (E-E-A-T signal); last-updated date (freshness signal). + +### TL;DR or executive summary (150 to 250 words) + +The most important section for AI citation. AI engines extract this verbatim and use it as the canonical answer when users ask the topic question. + +**What goes in.** A self-contained summary of the pillar's argument. Read alone, it answers the topic. Read in context, it sets up the comprehensive body. + +**What does not go in.** Marketing fluff. Throat-clearing meta-commentary that announces what the page is about to do instead of doing it. Cut it. + +**Format.** Either a single dense paragraph (150 to 250 words) or 5 to 7 bullet points. Both work; bullets often extract more cleanly to AI engines. + +### Table of contents + +Auto-generated from H2 and H3 structure. Anchors to each section. Helps readers scan; helps crawlers see structure. + +### Comprehensive body (the bulk of the pillar) + +12 to 20 H2 sections covering the topic's major facets. The body is a guided tour with depth links, not a comprehensive treatment of every facet. + +**Per H2 section.** + +- **Featured snippet bait.** A 40 to 60 word answer paragraph immediately following the H2 question. AI engines often quote this as the citation. +- **Body of the section.** 200 to 600 words developing the answer with examples, formulas, edge cases. +- **Cluster link callout.** When the section maps to a cluster piece, link to the cluster contextually within the body. "For the full pattern including [specific facet], see our [cluster piece guide]." + +### Use cases or examples + +Anchor the abstract topic to concrete instances. 3 to 5 worked examples. Each example named, scoped, and referenced in the body. + +### Common mistakes / FAQ + +Structured Q&A. Each Q is a real question; each A is a 40 to 80 word answer. + +**Pair with FAQPage schema.** Mark the Q&A section with FAQPage structured data. AI engines (Perplexity especially) cite FAQPage content heavily. + +**Anti-pattern.** "Frequently asked questions" that nobody actually asks. The FAQ should source from real customer questions, sales-call transcripts, support tickets. Fabricated FAQs are obvious to readers and to AI engines. + +### Closing or next steps + +Directs the reader into the cluster. "If you are starting fresh, read [intro cluster piece]. If you have rollouts running and need to harden them, read [advanced cluster piece]." + +The closing is also where the second bottom-up pillar reinforcement lands for cluster pieces; for the pillar itself, the closing names the next-best clusters by reader intent. + +--- + +## TL;DR placement and length + +Place immediately after the hero, before the table of contents. The reader sees TL;DR within the first scroll. AI engines scrape from the top of the page; TL;DR placed early gets prioritized. + +**150 words minimum.** Below 150, the TL;DR is too thin to serve as a citation candidate. + +**250 words maximum.** Above 250, the TL;DR loses its punch and starts duplicating the body. + +**Self-contained.** A reader who reads only the TL;DR should walk away with the topic's core. No throat-clearing or hedging; the TL;DR IS the answer. + +--- + +## FAQ schema + +The FAQ section gets FAQPage schema. The format: + +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is a feature flag kill switch?", + "acceptedAnswer": { + "@type": "Answer", + "text": "A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. Kill switches are configured at deploy time and remain available throughout the feature's lifecycle." + } + } + ] +} +``` + +**Common mistake.** FAQPage schema on questions that are not real FAQs. Schema markup that misrepresents page content can trigger manual penalties; mark only genuine FAQ sections. + +--- + +## Internal-link callout placement + +The pillar links to cluster pieces from within the body, not from a "related reading" footer. + +**Pattern.** Inside the H2 section that maps to a cluster, place one contextual link to the cluster piece. Position the link at the moment in the section where the reader's curiosity peaks: typically after the section has set up the question and before the answer goes deep. + +**Example.** In the H2 "What is a kill switch?" section, after the 40 to 60 word answer paragraph, link to the cluster piece on kill switches with the phrase "For the full pattern including code-level implementations, see our [kill switch design guide]." + +**Frequency.** One link per cluster from the pillar. Two if the cluster maps to two distinct sections of the pillar. Avoid more than two; the second link is the reinforcement, not a third or fourth. + +--- + +## Schema markup choices + +The pillar's primary schema depends on intent. + +**Article schema.** Default for most pillars. Marks the page as long-form editorial content. + +**HowTo schema.** When the pillar is a step-by-step guide ("how to launch a feature flag rollout"). HowTo gives Google more structured data to render in SERPs. + +**FAQPage schema.** Always pair with the FAQ section, not the pillar overall. + +**BreadcrumbList schema.** Always include for hub navigation context. + +**Author schema.** Embed Person schema for the author with credentials, bio link, and same-as references to LinkedIn or X. E-E-A-T signal. + +--- + +## Length calibration + +3,000 to 5,000 words is the typical pillar range. Calibrate to the SERP, not to a quota. + +**SERP top 10 average word count tells you the band.** Pull the top 10; tag word counts; aim for the top 3 average. If the top 3 average 4,200 words, your pillar should target 4,000 to 4,500. + +**The depth-vs-length tradeoff.** Pillar quality is comprehensiveness AND depth, not just length. A 6,000-word pillar that covers 3 facets in massive depth is worse than a 4,000-word pillar that covers 12 facets at appropriate depth. Length without breadth is not a pillar; it is a long article. + +**The cluster offload.** Each cluster piece reduces the depth required in the pillar's corresponding section. If kill switches has its own cluster piece, the pillar's kill-switches section can be 300 words pointing to the cluster, not 1,200 words duplicating the cluster. The cluster offload is what keeps the pillar at the right length. + +--- + +## Updates and freshness signals + +The pillar's "last updated" date is a freshness signal. Update it whenever you make material changes (statistics refreshed, new section added, cluster expanded). Do not update it for cosmetic edits; spurious freshness signals are noticed by ranking systems. + +The annual pillar refresh (see `content-refresh-patterns.md`) is the discipline that produces honest freshness signals. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md b/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md new file mode 100644 index 0000000..f5505a5 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md @@ -0,0 +1,104 @@ +# Topic selection criteria + +The five-criterion framework for pillar topic selection, with worked examples across business types. + +--- + +## The five criteria + +A topic earns pillar status only when all five hold. Failing one is a hard signal to stop. + +### 1. Search volume justifies the investment + +The pillar will cost 3 to 6 weeks of editorial effort and 8 to 15 cluster pieces. The topic needs enough monthly search demand to repay the investment over a 3 to 5 year horizon. + +**Heuristic.** Pillar topic with combined volume across the keyword cluster of 1,000+ monthly searches usually justifies a pillar. Below 500 combined monthly searches, the topic is probably a single cluster piece under a broader pillar, not its own pillar. + +**Exception.** High-commercial-value topics with low volume (enterprise B2B SaaS niches, expensive professional services) can justify pillars at lower volumes because each ranking visit is worth more. + +### 2. Topic has natural facets + +A pillar covers a topic with internal structure. The team should be able to brainstorm 8 to 15 distinct subtopics, each capable of being a standalone cluster piece. + +**The test.** Spend 30 minutes listing facets. If the list reaches 12 organically, the topic has the structure. If the list stalls at 5, the topic is a cluster, not a pillar. + +**Common false positive.** Listing 12 keyword variations of "what is X" is not 12 facets. It is one facet (definition) said 12 ways. True facets are dimensionally different (definition, how-to, comparison, mistakes, costs, alternatives, examples, case studies). + +### 3. Commercial relevance + +The topic connects to the business model. A pillar without commercial signal is content marketing for content marketing's sake. + +**The test.** Can you draw a line from "reader lands on this pillar" to "reader becomes customer or contributor of customer-related signal"? If yes, the topic is commercially relevant. If the line requires three hops and a leap of faith, the topic is too far from the business. + +### 4. Competitive feasibility + +Top 10 SERP for the pillar keyword is achievable for the brand at its current authority. If the SERP is dominated by Wikipedia, government sites, and global household-name brands, your pillar will rank position 47 no matter how good it is. + +**The test.** Pull the SERP top 10. Tag each result by domain authority and commercial profile. If the top 10 are all DR 80+ household names and your brand is DR 35, do not start the pillar. Either pick a less-competitive long-tail variant or build authority on adjacent topics first. + +### 5. Editorial commitment + +The team will maintain the pillar for 3 to 5 years: annual refresh, cluster expansion, ownership through team changes. + +**The test.** Name the durable owner. If the owner is "the marketing team" instead of a specific person with a 12-month commitment, the pillar will not get maintained. Pillars without owners decay; the decay is invisible until the traffic drop is unrecoverable. + +--- + +## Worked example: B2B SaaS + +The brand is a feature-flag platform competitor (DR 45). Considering a pillar on "feature flag rollout strategies." + +- Volume: 2,400 combined monthly searches across the cluster. ✓ +- Facets: 14 listed (rollout strategies, naming conventions, lifecycle, governance, kill switches, technical debt, multi-environment, A/B testing integration, etc.). ✓ +- Commercial: pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes LaunchDarkly (DR 78), Statsig (DR 65), and several DR 60+ blogs. Tight but not impossible at DR 45 with strong cluster support. ✓ (with effort) +- Commitment: PM and content lead jointly own; renewal review every 12 months. ✓ + +Decision: pillar candidate. Plan a 12-cluster hub. + +--- + +## Worked example: ecommerce + +A direct-to-consumer skincare brand (DR 38). Considering a pillar on "retinol routine for beginners." + +- Volume: 8,500 combined monthly searches. ✓ +- Facets: 11 listed (intro, how to start, percentages, frequency, side effects, sun pairing, age considerations, mixing with other actives, sensitive-skin variant, pregnancy considerations, troubleshooting). ✓ +- Commercial: high; pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes The Ordinary blog, Paula's Choice, Reddit threads, dermatology sites. Mixed authority; achievable at DR 38 with cluster depth and original photography. ✓ +- Commitment: brand educator owns; refresh every 12 months. ✓ + +Decision: pillar. Plan a 10 to 12 cluster hub. + +--- + +## Worked example: services business + +A regional accounting firm (DR 28). Considering a pillar on "small business tax preparation." + +- Volume: 1,200 combined monthly searches. ✓ +- Facets: 12 listed (deductions, quarterly estimates, software comparison, when to hire vs DIY, common mistakes, audit risk, retirement contributions, payroll tax, sales tax, state-specific notes, multi-state operations, business structure choice). ✓ +- Commercial: very high; readers are local prospective clients. ✓ +- Competitive: top 10 includes Intuit, H&R Block, IRS itself, AICPA. Hard at DR 28. ✗ + +Decision: do not pursue this pillar. Instead, scope to a niche the brand can win: "small business tax preparation in [city]" with a pillar focused on the local-business audience and local SEO signals where DR matters less. + +--- + +## Worked example: media or publishing + +A career-focused publication (DR 55). Considering a pillar on "remote work productivity." + +- Volume: high. ✓ +- Facets: easily 15+. ✓ +- Commercial: ad-driven; pillar traffic monetizes through display and email signups. Indirect but real. ✓ +- Competitive: top 10 is moderately authoritative; achievable. ✓ +- Commitment: senior editor owns. ✓ + +Decision: pillar. Note the commercial-signal pattern is different from B2B SaaS or ecommerce; the funnel is impressions to audience growth rather than impressions to qualified lead. Same architecture, different success metrics. + +--- + +## When to walk away + +If three or more criteria fail, walk away from the pillar idea. If exactly one criterion fails (usually competitive feasibility), see whether a long-tail variant of the topic resolves the failed criterion. The "long-tail variant pivot" is the most common save: instead of "feature flags" (DR 78 incumbents), pick "feature flags for [niche]" (DR 50 incumbents) where the brand can compete. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md b/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md new file mode 100644 index 0000000..547a43d --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md @@ -0,0 +1,126 @@ +# Topical authority signals + +SEO and AEO/GEO signals at the hub level. Two-engine optimization framing. + +--- + +## Why hubs produce stronger signals than orphans + +Search engines and AI engines both read internal-link graphs and content patterns to infer topical authority. A hub with 12 connected pieces produces signals an orphan set cannot match: + +- **Density of internal links on the topic.** PageRank flows within the hub; pages reinforce each other. +- **Comprehensive entity coverage across pieces.** The hub mentions more named tools, methods, experts, and statistics than any single piece could. +- **Repeated topical signal at scale.** Multiple pieces with overlapping topical vocabulary, distinct facets, consistent structure. +- **Crawl-rate compounding.** Search engines crawl high-link-density clusters more frequently; AI engines re-index hubs more aggressively. + +Same total content volume; different architectural outcome. 12 orphans on the same topic produce scattered, weaker signals than a 12-piece hub. + +--- + +## SEO signals at the hub level + +### Internal-link graph density + +Google's PageRank algorithm flows authority through internal links. A pillar with 12 cluster pieces linking back to it concentrates PageRank on the pillar; the pillar in turn passes authority to clusters via top-down links. The graph shape compounds. + +**Heuristic.** Compare PageRank on a pillar before and after the cluster ships. Most teams see ranking improvements on the pillar within 3 to 6 months as the cluster matures. + +### Comprehensive entity coverage + +The hub mentions more named entities than any single page could: tools, methods, experts, datasets, frameworks. Search engines extract entity graphs at crawl time; comprehensive coverage signals topical depth. + +**The discipline.** Each piece in the hub mentions the topic's required entities (entities the SERP top 10 share) and the gap entities (entities only 1 or 2 SERP results mention). The hub-level entity graph is the union across all pieces. + +### URL structure clarity + +The `/topic/cluster-piece/` pattern signals topical grouping. Crawlers follow the URL hierarchy and infer the hub structure even before parsing internal links. + +### Breadcrumb hierarchy + +BreadcrumbList schema tells crawlers the hub structure explicitly. Some SERPs surface breadcrumb URLs as rich-result enhancements. + +### Schema markup at scale + +Article, HowTo, FAQPage, BreadcrumbList schema across the hub. Each schema type passes additional structured data to crawlers. The hub is structured for extraction in a way that orphan content rarely is. + +### E-E-A-T signals + +Experience, Expertise, Authoritativeness, Trustworthiness. Google's quality framework. Hub-level E-E-A-T comes from: + +- Author credentials displayed on every piece (with Person schema) +- Expertise demonstrated through depth and accuracy +- Authoritativeness signaled by entity coverage and citations +- Trustworthiness signaled by clear authorship, last-updated dates, and corrections to prior work when relevant + +E-E-A-T is not a discrete signal; it is the aggregate of many small signals. Hubs accumulate E-E-A-T faster than orphans because the signals compound across pieces. + +--- + +## AEO and GEO signals at the hub level + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) cite content based on different patterns than traditional search ranking. Hubs serve AI engines as well as search engines if the right signals are present. + +### Answer-paragraph format under H2 headings + +40 to 60 word self-contained answers immediately following H2 questions. AI engines extract these as citation candidates. The pattern repeats across pillar and clusters; the hub becomes a structured set of citation-ready answers. + +### TL;DR section on pillars + +The pillar's TL;DR (150 to 250 words) is the most-cited section by AI engines. Place it at the top, make it self-contained, write it as the canonical summary. + +### FAQPage schema + +AI engines (Perplexity especially) heavily cite FAQPage-marked content. Pair every pillar's FAQ section with FAQPage schema. Cluster pieces with genuine FAQs also benefit. + +### Specific statistics with cited sources + +"23% of feature flag rollouts include a kill switch (Feature Flag Survey 2025, n=412)" cites better than "many feature flag rollouts include a kill switch." Specific numbers with sources are higher-citation signals; vague qualifiers are lower-citation. + +### Named experts and named methods + +"As Adam Kalai noted in the original CUPED paper" cites better than "experts have shown." Named attribution earns citation; anonymous attribution does not. The hub should mention 5+ named experts or methods across pillar and clusters. + +### Distinctive POV + +AI engines preferentially cite content with a clear, attributable position. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. The hub's POV is the brand's editorial position; consistency across pieces reinforces attribution. + +--- + +## The two-engine optimization + +Pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +**Both reward depth.** Search engines reward comprehensive treatment of a topic. AI engines reward citation-ready depth. Same content; different extraction. + +**Both reward structure.** Search engines parse heading hierarchy for ranking. AI engines parse heading hierarchy for citation extraction. Same structure; different use. + +**Both reward entity coverage.** Search engines use entities for topical relevance. AI engines use entities for retrieval and citation. Same entities; different scoring. + +**Both reward freshness.** Search engines reward recent updates. AI engines re-index recently-updated content more aggressively. Same updates; different cadence. + +The implication. Optimizing for AEO/GEO does not trade off against SEO. The hub architecture that earns search rankings is the same architecture that earns AI citations. Teams that treat them as separate optimizations under-invest in both. + +--- + +## Measuring topical authority signals + +Hub-level metrics worth tracking: + +**Search-side:** + +- Aggregate organic traffic to all pieces in the hub +- Average position for the pillar's primary keyword +- Number of cluster pieces ranking in top 10 for their target keywords +- Internal-link count per cluster piece (from inventory) +- Crawl frequency (Google Search Console) + +**AI-side:** + +- Brand mention rate from Profound, Frase, AirOps, or similar tools +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude) +- Top-cited pieces (which clusters get cited most often) +- AI crawler hit frequency (server logs, Profound Agent Analytics) + +The hub-level dashboard composes these metrics. Tracking at the hub level (not per piece) is what surfaces architecture-level patterns: which clusters drive traffic, which clusters drive citations, which clusters are dead weight. + +See the `seo-aeo-geo` skill for AEO/GEO program-level strategy. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md new file mode 100644 index 0000000..1b498c0 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md @@ -0,0 +1,105 @@ +# URL structure patterns + +Subfolder vs subdomain decision, slug conventions, breadcrumbs, the /blog/ trap. + +--- + +## Subfolder vs subdomain + +The default for hubs is subfolder. Subdomain has narrow valid use cases. + +**Subfolder pattern.** `example.com/feature-flag-rollout/` for the pillar; `example.com/feature-flag-rollout/kill-switches/` for cluster pieces. Both pillar and cluster live on the same domain authority; PageRank flow is consolidated; the hub compounds within the brand's existing SEO equity. + +**Subdomain pattern.** `docs.example.com`, `community.example.com`, `support.example.com`. Used when the property is genuinely distinct (different audience, different content type, different team ownership). Subdomains receive less of the parent domain's authority signal in most analyses; do not split a hub across subdomains without a strong reason. + +**Decision rule.** Pillar plus cluster always on the same subdomain as the rest of the marketing content. If the brand's marketing content lives at `example.com`, the hub lives at `example.com/[hub]/`. Splitting the hub onto a subdomain treats the hub as a separate property, which is almost never correct. + +--- + +## Hub URL pattern + +The pattern: `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. + +**Why this pattern.** The URL itself signals topical grouping. Crawlers see the path structure and infer that pages under `/feature-flag-rollout/` belong to a topical hub. Readers see the breadcrumb in the URL and know where they are. + +**The /blog/ alternative.** `/blog/feature-flag-rollout/` and `/blog/kill-switches/`. This works structurally; the pieces still rank. But the hub signal is weaker because the URL groups by content type (blog) rather than by topic. Two unrelated blog posts share the `/blog/` path; nothing in the URL says "kill-switches is part of the feature-flag-rollout hub." + +**The fix when migrating off /blog/.** Change the URL pattern via 301 redirects from old to new. Lose some short-term ranking equity during the redirect; gain long-term hub-signal clarity. The migration is worth it for major hubs; not worth it for smaller content sets. + +--- + +## Slug conventions + +**Short, descriptive, keyword-aware but not stuffed.** + +Good: `/feature-flag-rollout/kill-switches/` + +Bad: `/feature-flag-rollout/the-ultimate-guide-to-implementing-kill-switches-in-feature-flag-rollouts-2026/` + +**Why short.** Long slugs read as keyword-stuffed and break in social shares, email previews, and conversational mentions. Search engines do not need every keyword in the URL; they parse the page content. + +**Why descriptive.** The slug should make sense as a standalone string. `/feature-flag-rollout/kill-switches/` is self-describing; `/post-1247/` is not. + +**Keyword-aware.** Include the primary keyword for the cluster piece. Do not include the supporting cluster keywords (those go in the page content, not the URL). + +**Date-free.** Avoid dates in slugs (`/2026-rollout-guide/`). Dated slugs anchor the piece in time; refreshing the piece in 2027 is awkward. Pieces with date-relevant content (annual reports, year-in-review) are exceptions. + +**Hyphens, not underscores.** Search engines treat hyphens as word separators; underscores as part of one word. `kill-switches` reads as two words; `kill_switches` reads as one. + +**Lowercase.** Mixed-case URLs cause case-sensitivity confusion across servers and create duplicate-content issues. + +--- + +## Breadcrumb structure + +Breadcrumbs surface the hub structure in the page UI and the page schema. The pattern: + +`Home > Hub topic > Cluster piece` + +In the UI, breadcrumbs typically render as a small horizontal nav above the title. In schema, BreadcrumbList markup tells crawlers the path. + +**Why breadcrumbs help.** Readers see they are in a hub and can navigate up. Crawlers parse the BreadcrumbList schema and reinforce the hub hierarchy. Some SERPs also surface breadcrumb URLs in rich results. + +**Breadcrumb anti-pattern.** Breadcrumbs that show URL segments instead of human-readable labels. `Home > /feature-flag-rollout > /kill-switches` is the wrong format. Use the hub's display name and the cluster piece's title, not the URL slug. + +**Schema example.** + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +The third item omits "item" because breadcrumbs typically do not link to the current page. + +--- + +## The /blog/ trap + +The symptom. The team's content all lives at `/blog/[slug]/` because that is how the CMS is configured. Pillar and cluster live alongside unrelated blog posts in the same flat URL space. + +The diagnosis. The CMS folder defaulted to `/blog/`. Nobody changed it because changing CMS routing is non-trivial. Hub structure exists in the editorial team's head but not in the URL. + +The cost. Hub signal is weakened; PageRank flow is less topically concentrated; readers cannot tell from the URL that a piece is part of a hub. + +The fix. Change CMS routing to support topic-based subfolders. Migration via 301 redirects from old `/blog/` URLs to new `/[hub]/` URLs. Take a short-term ranking hit during redirect; gain long-term hub authority. + +The "do not migrate" exception. If the existing `/blog/` URL structure is generating significant traffic and the hub investment is small, the migration may not pay back. Score the migration cost against the hub's commercial value; migrate only when the hub justifies it. + +--- + +## Multilingual or multi-region URL patterns + +Hubs that span languages or regions add another structural decision. The two main patterns: + +**Subfolder per locale.** `example.com/en/[hub]/`, `example.com/de/[hub]/`. Cleanest for SEO consolidation; clearest for crawlers. + +**ccTLD per region.** `example.de/[hub]/`, `example.fr/[hub]/`. Stronger for regional ranking but splits domain authority. + +The decision usually depends on the brand's existing internationalization choice; the hub follows the existing pattern. Do not use the hub launch as the moment to switch internationalization strategies. diff --git a/dist/pi/.agents/skills/pm-spec-writing/SKILL.md b/dist/pi/.agents/skills/pm-spec-writing/SKILL.md new file mode 100644 index 0000000..abb72ad --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/SKILL.md @@ -0,0 +1,226 @@ +--- +name: pm-spec-writing +description: "Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks." +category: product +catalog_summary: "PRDs, user stories, acceptance criteria, dev briefs" +display_order: 1 +--- + +# PM Spec Writing + +Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work. + +--- + +## When to use + +- Translating an idea into a buildable feature spec +- Writing a PRD or product requirement document +- Filing a bug report that someone else can act on +- Scoping a project before kickoff +- Prioritizing a backlog of feature requests +- Writing acceptance criteria for an existing feature +- Breaking a large initiative into shippable increments + +## When NOT to use + +- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`) +- Code review or debugging existing code (use `code-review-web`) +- Design decisions for a feature already specced (use `design-standards`) +- User research to validate an idea (use `ux-research`) + +--- + +## Required inputs + +- The idea, request, or problem being addressed +- The audience or user affected +- Any existing constraints (stack, deadlines, dependencies) +- The success metric (how will you know it worked?) + +If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness. + +--- + +## The framework: 4 phases + +Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary. + +### Phase 1: Clarify the idea + +Before any spec, answer four questions. If any answer is "I don't know," go back to the user. + +1. **What user problem does this solve?** Not "what does it do." The problem comes first; the feature is the proposed solution. +2. **Who specifically benefits?** Be precise. "Users" is not specific. "First-time visitors who don't convert" is. +3. **What is the success metric?** How will you know it worked? Pick one primary metric. +4. **Why now?** What changed that makes this the right time to build it? If "nothing changed," it might not be the right time. + +### Phase 2: Scope by impact and effort + +Plot every candidate idea on the impact/effort grid: + +``` +HIGH IMPACT / LOW EFFORT Ship immediately + Examples: copy fixes, contrast fixes, meta tags, + broken links, missing alt text, redirects + +HIGH IMPACT / HIGH EFFORT Plan and batch + Examples: new page type, new feature, schema overhaul, + major redesign, new integration + +LOW IMPACT / LOW EFFORT Nice-to-have batch + Examples: tooltip improvements, minor copy polish, + cosmetic UX touches + +LOW IMPACT / HIGH EFFORT Skip or defer indefinitely + Examples: rebuilding what already works, exotic + edge case features, premature optimization +``` + +This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions. + +### Phase 3: Write the spec + +Three formats based on the type of work. + +#### Format A: Feature spec (for new features) + +``` +TITLE: [Specific, action-oriented] + +PROBLEM +[1-2 sentences. The user problem and current state.] + +USERS +[Who specifically benefits. Be precise about the user segment.] + +PROPOSAL +[1 paragraph. The proposed solution. Stay at the conceptual level.] + +USER STORIES +- As a [user type], I want to [action], so that [outcome] +- As a [user type], I want to [action], so that [outcome] + +ACCEPTANCE CRITERIA +- Given [context], when [action], then [expected outcome] +- Given [context], when [action], then [expected outcome] + +OUT OF SCOPE +[What this spec explicitly does NOT cover. Important for scope control.] + +DEPENDENCIES +[Other systems, APIs, designs, content needed before this can ship.] + +SUCCESS METRIC +[The one primary metric that tells us this worked. With current baseline if known.] + +ESTIMATED EFFORT +[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)] + +PRIORITY +[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog] +``` + +#### Format B: Dev brief (for handing to a developer or AI agent) + +For tactical, ready-to-build work. Lighter than a full spec. + +``` +CONTEXT: [1-2 sentences explaining why this matters] + +TASK: [Specific files, exact changes needed] + +CONSTRAINTS: [What must NOT change, what to preserve] + +VERIFY: [Exact steps to confirm the work is done correctly] +``` + +The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means. + +#### Format C: Bug report + +``` +URL or context: [Where it happens] + +Symptom: [What the user sees or experiences] + +Expected: [What should happen instead] + +Steps to reproduce: +1. [Specific step] +2. [Specific step] +3. [Specific step] + +Hypothesis: [Likely root cause if known] + +Files to investigate: [Likely files involved if known] + +Priority: + P0 - blocking critical user flow, ship immediately + P1 - degrades UX significantly, fix this sprint + P2 - minor issue, fix when convenient + P3 - nice-to-have improvement + +Browser/device: [If reproducibility might be browser-specific] +``` + +### Phase 4: Sequence and ship + +Specs without sequencing become dust on a shelf. + +For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate. + +For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels. + +--- + +## Workflow + +1. **Clarify.** If the idea is vague, ask the four phase-1 questions before proceeding. +2. **Scope.** Plot the work on the impact/effort grid. +3. **Pick the right format.** Feature spec for new features, dev brief for tactical work, bug report for defects. +4. **Write the spec.** Use the template format. Fill in every section. Empty sections are flags. +5. **Define done.** Verify steps must be unambiguous. "Test it" is not a verify step. +6. **Get buy-in.** Walk through the spec with whoever will build it before they start. +7. **Sequence.** Identify the smallest shippable increment. + +--- + +## Failure patterns + +- **Specs that describe solutions before problems.** Always start with the user problem. The solution is downstream. +- **Specs without a success metric.** Without a metric, you cannot tell if the feature worked. +- **Acceptance criteria that are not testable.** "User experience is improved" is not testable. "User completes signup in under 60 seconds" is. +- **Specs that include the "how" instead of the "what."** Implementation details belong in the dev brief, not the spec. The spec is the desired outcome. +- **No "out of scope" section.** Without explicit boundaries, scope creeps. +- **Bug reports without reproduction steps.** Cannot be acted on. Always include steps. +- **Verify steps that are vague.** "Make sure it works." Useless. Must be specific actions with observable outcomes. +- **Skipping the smallest-shippable-increment exercise.** Leads to 6-month projects that should have been 2-week experiments. + +--- + +## Output format + +Output is one of three formats based on work type, all in markdown: + +- `spec-[feature-name].md` for feature specs +- `brief-[task-name].md` for dev briefs +- `bug-[summary].md` for bug reports + +For larger initiatives, group related specs in a folder: +``` +specs/ + initiative-name/ + spec-feature-1.md + spec-feature-2.md + brief-task-1.md + README.md (overview and sequencing) +``` + +--- + +## Reference files + +- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template. +- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work. +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW. diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md b/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md new file mode 100644 index 0000000..289ffef --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md @@ -0,0 +1,207 @@ +# Dev Brief Template + +A dev brief is the lightweight version of a spec. Used for tactical work that does not need a full PRD: bug fixes, copy changes, small feature additions, infrastructure tweaks. + +The brief is structured to be handed directly to a developer or AI agent. They should be able to act on it without follow-up questions. + +--- + +## Template + +``` +TASK: [One-sentence summary of what to do] + +CONTEXT +[1 to 2 sentences. Why this matters. What problem it solves.] + +WHAT TO DO +[Specific changes. List the exact files (if known), the exact behavior to change, the exact copy to update. Be unambiguous.] + +CONSTRAINTS +[What must NOT change. What to preserve. What's out of bounds.] + +VERIFY +[Exact steps to confirm the work is done correctly. Each step should produce an observable outcome that proves the change worked.] + +DEPENDENCIES +[Anything that must be done first, or that this depends on.] + +PRIORITY +[P0 / P1 / P2 / P3 with one-line reason] + +ESTIMATED TIME +[Minutes or hours - not days. If it would take days, write a feature spec instead.] +``` + +--- + +## Example: Bug fix brief + +``` +TASK: Fix the broken submit button on the contact form + +CONTEXT +Users reported that the contact form submit button does not respond on mobile Safari. +This is blocking lead capture from a major traffic source. + +WHAT TO DO +- Investigate components/forms/ContactForm.tsx +- Check the onClick handler and form submission logic +- The issue is likely related to a recent change to the button onClick handler; + check git log for the most recent commit touching this component +- Fix so submit fires on tap as well as click + +CONSTRAINTS +- Do not change any other forms in the codebase +- Do not modify the form validation logic +- Preserve the existing visual design of the button + +VERIFY +1. Open contact form on mobile Safari (or device-mode in browser) +2. Fill required fields with valid data +3. Tap submit button +4. Confirm form submits and success message displays +5. Repeat on Chrome and Firefox to ensure no regression +6. Check browser console for errors after submit + +DEPENDENCIES +None. Self-contained fix. + +PRIORITY +P1 - blocking lead capture from primary traffic source + +ESTIMATED TIME +30 to 60 minutes +``` + +--- + +## Example: Copy change brief + +``` +TASK: Update homepage hero copy to match new positioning + +CONTEXT +The marketing team has finalized the new positioning statement. +The current hero copy is from the previous brand iteration and needs updating. + +WHAT TO DO +File: pages/index.tsx (or app/page.tsx in App Router) + +Change the hero H1 from: + "The all-in-one platform for modern teams" +To: + "Move work forward without moving the meeting" + +Change the hero subheadline from: + "Streamline your workflow with our innovative collaboration suite" +To: + "Async-first project management for distributed teams that ship." + +Change the primary CTA button text from: + "Get started" +To: + "Start free trial" + +CONSTRAINTS +- Do not change the hero image +- Do not change the secondary CTA +- Preserve all existing styling and component structure + +VERIFY +1. Reload the homepage in a browser +2. Confirm new H1, subheadline, and CTA text display correctly +3. Confirm visual layout is unchanged (no new layout shifts) +4. Confirm responsive behavior on 375px viewport +5. Run a Lighthouse pass to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P1 - aligned with brand launch on [date] + +ESTIMATED TIME +15 to 30 minutes +``` + +--- + +## Example: Small feature brief + +``` +TASK: Add an estimated reading time to blog post pages + +CONTEXT +Users have asked for an indication of how long a post takes to read. +Improves perceived value and helps users decide whether to start reading. + +WHAT TO DO +- Calculate reading time as word count / 200 words per minute, rounded up +- Display below the post title, alongside the publish date +- Format: "5 min read" (with the minute count appropriate to length) +- Apply to all blog post pages (single post template) + +Suggested implementation: +- Compute server-side from the post body content +- Add to the post component's metadata section +- Style consistently with the existing publish date + +CONSTRAINTS +- Must work for posts of any length (test 1 minute to 30+ minute posts) +- Must not affect SEO (e.g., no JS-rendering for crawlers) +- Must not regress page load performance + +VERIFY +1. Open 3 different blog posts of varying length +2. Confirm reading time displays correctly for each +3. Verify the calculation is right (count words manually for a short post) +4. Check the rendered HTML to confirm the value is server-rendered, not JS +5. Confirm visual styling matches the publish date treatment +6. Run Lighthouse to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P2 - nice user enhancement, no urgency + +ESTIMATED TIME +1 to 2 hours including QA +``` + +--- + +## What makes a good brief + +**Context** answers "why am I doing this?" Without it, the implementer cannot make good judgment calls. + +**What to do** is specific. Names files when known. Quotes exact copy when copy is changing. Describes desired behavior unambiguously. + +**Constraints** prevent scope creep. Especially for AI agents who tend to "improve" things outside the task. + +**Verify** is the most-skipped section and the most important. Each verify step must be: +- Observable (you can see whether it passed or failed) +- Specific (no "make sure it works") +- Sufficient (if all verify steps pass, the work is genuinely done) + +**Dependencies** prevent the implementer from starting work that's blocked. + +**Priority** sets expectations on order. + +**Estimated time** sets expectations on effort. Briefs are for work measured in minutes to a few hours. Days-long work should be a feature spec. + +--- + +## When NOT to use a dev brief + +If the work has any of the following, write a feature spec instead: + +- Multiple stakeholders need to weigh in +- The user-facing behavior needs design review +- The change affects multiple parts of the system +- The estimate exceeds 1 day of work +- The success metric is non-obvious +- The work cannot be verified by a few specific steps + +A dev brief is for "do this exact thing." A feature spec is for "build this product capability." diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md b/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md new file mode 100644 index 0000000..48c4447 --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md @@ -0,0 +1,192 @@ +# Feature Spec: [Feature Name] + +**Author:** [Name] +**Date:** [YYYY-MM-DD] +**Status:** [Draft / In Review / Approved / In Development / Shipped] +**Target ship:** [Date or sprint] + +--- + +## TL;DR + +[2 to 3 sentences. What this is, who it's for, why it matters. If a stakeholder reads only this section, they should understand the proposal.] + +--- + +## Problem + +[1 to 2 paragraphs. The user problem. The current state and why it's inadequate. Include data if available (analytics, support tickets, user research quotes).] + +### Evidence + +- [Specific data point or research finding] +- [Specific data point or research finding] +- [Specific data point or research finding] + +--- + +## Users + +**Primary user:** [Specific user segment that benefits most] + +**Use cases:** +1. [Specific scenario where this user encounters the problem] +2. [Specific scenario] +3. [Specific scenario] + +**Secondary users:** [Other segments affected] + +**Anti-users:** [Segments this feature is NOT for; helps prevent scope creep] + +--- + +## Proposal + +[1 paragraph at the conceptual level. The solution, not the implementation. Stay at "what" not "how".] + +### How it works (high level) + +[3 to 5 bullets describing the user experience flow. Still high level; not implementation details.] + +1. [User action] +2. [System response] +3. [User action] +4. [System response] + +--- + +## User stories + +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. + +--- + +## Acceptance criteria + +The feature ships when ALL of these are true. + +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] [Additional criteria] +- [ ] [Additional criteria] + +Each criterion must be observable and testable. If you cannot verify it with a specific check, rewrite it. + +--- + +## Out of scope + +[Explicit boundaries. What this spec does NOT cover. Critical for scope control.] + +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] + +--- + +## Dependencies + +### Required before development can start +- [ ] [Design completed and approved] +- [ ] [API contracts defined] +- [ ] [Content delivered] +- [ ] [Legal/compliance review if applicable] + +### External systems or services +- [System or service]: [What we depend on] +- [System or service]: [What we depend on] + +### Team dependencies +- Design: [What's needed and who owns it] +- Engineering: [Specific resources and timeline] +- Content: [If applicable] +- Marketing: [If launch-related] + +--- + +## Success metric + +**Primary metric:** [The one metric that tells us this worked] + +**Current baseline:** [If known] + +**Target:** [What success looks like quantitatively] + +**Measurement window:** [When and for how long we measure] + +**Secondary metrics (signals to watch):** +- [Metric] - [why it matters] +- [Metric] - [why it matters] + +**Negative signals (what would tell us this hurt):** +- [Metric] - [threshold for concern] +- [Metric] - [threshold for concern] + +--- + +## Estimated effort + +**Size:** [Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (multiple sprints)] + +**Breakdown:** +- Design: [hours/days] +- Frontend: [hours/days] +- Backend: [hours/days] +- QA: [hours/days] +- Content: [hours/days] +- Total: [estimated] + +--- + +## Priority + +**P0** Launch blocker - must ship before [event/launch] +**P1** Next sprint - high impact, addressable now +**P2** Within quarter - valuable but not urgent +**P3** Backlog - nice-to-have, no commitment + +**This spec:** [P0 / P1 / P2 / P3] + +**Reasoning:** [Why this priority] + +--- + +## Open questions + +[Things that need to be decided before development can start, or before the feature can ship.] + +- [ ] [Question] - **Owner:** [Who decides] - **Decision needed by:** [Date] +- [ ] [Question] - **Owner:** [Who decides] - **Decision needed by:** [Date] + +--- + +## Risks and mitigations + +| Risk | Likelihood | Impact | Mitigation | +|---|---|---|---| +| [Risk description] | High/Med/Low | High/Med/Low | [How we'll mitigate] | +| [Risk description] | | | | + +--- + +## Smallest shippable increment + +**MVP:** What is the simplest version that delivers user value? + +[Description of the MVP. Shippable in 1 to 2 weeks for most features. If you can't describe an MVP that fits, the feature is too big and should be split.] + +**Future iterations** (NOT in MVP, may come later): +- [Iteration 1] +- [Iteration 2] +- [Iteration 3] + +--- + +## Changelog + +| Date | Author | Change | +|---|---|---| +| YYYY-MM-DD | [Name] | Initial draft | diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md b/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md new file mode 100644 index 0000000..0fb7f3d --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md @@ -0,0 +1,219 @@ +# Prioritization Frameworks + +Beyond the simple impact/effort grid, there are several frameworks for prioritizing work. Each is useful in different situations. None is universally correct. + +--- + +## Impact / Effort matrix + +The simplest and most common. + +**How it works:** plot every candidate on a 2x2 grid. + +``` + Low Effort High Effort + +High Impact Quick wins Major projects + (Ship now) (Plan and batch) + +Low Impact Backlog batch Skip or defer + (When time allows) (Reconsider) +``` + +**Strengths:** Fast. Forces blunt judgment. Useful for triage. + +**Weaknesses:** Subjective. "Impact" and "effort" are estimates that get inflated. + +**When to use:** Triage of a long list. Initial sorting. + +--- + +## RICE + +A weighted scoring method that produces a numeric priority score. + +**How it works:** + +``` +RICE Score = (Reach × Impact × Confidence) / Effort +``` + +- **Reach:** How many users this affects per period (e.g., per quarter). Use real numbers. +- **Impact:** The per-user impact, scored on a fixed scale: + - 3 = Massive (transformative) + - 2 = High (significant lift) + - 1 = Medium (modest lift) + - 0.5 = Low (minor lift) + - 0.25 = Minimal (barely noticeable) +- **Confidence:** How certain you are of the reach and impact estimates, as a percentage. + - 100% = high confidence (data-backed) + - 80% = medium confidence (some evidence) + - 50% = low confidence (mostly intuition) +- **Effort:** Person-months (or person-weeks for smaller work). + +**Example:** + +A new onboarding flow: +- Reach: 5,000 new users per quarter +- Impact: 1 (modest improvement to activation) +- Confidence: 80% +- Effort: 2 person-months + +RICE = (5000 × 1 × 0.8) / 2 = 2,000 + +A bug fix on a rarely-used page: +- Reach: 50 users per quarter +- Impact: 2 (significant for those affected) +- Confidence: 100% +- Effort: 0.25 person-months + +RICE = (50 × 2 × 1) / 0.25 = 400 + +The onboarding flow scores higher. + +**Strengths:** Numeric. Forces explicit estimates. Surfaces the math behind judgment. + +**Weaknesses:** Garbage-in-garbage-out. Reach and impact estimates can be wildly wrong. + +**When to use:** Comparing across many candidate features. When stakeholders disagree on priority. + +--- + +## MoSCoW + +Categorical, used for release scoping. + +**How it works:** every item is one of four: + +- **Must have** - non-negotiable for this release +- **Should have** - important but not critical +- **Could have** - nice if time allows +- **Won't have** - explicitly out of scope (this release) + +**Example for a redesign launch:** + +- **Must:** New navigation, mobile responsive, all P0 pages migrated +- **Should:** New blog template, updated forms +- **Could:** New illustrations on lower-traffic pages +- **Won't:** Internationalization (deferred to phase 2) + +**Strengths:** Clear scope boundaries. Forces explicit "won't have" decisions, which prevent scope creep. + +**Weaknesses:** Not a framework for relative priority within categories. + +**When to use:** Defining the scope of a release. Cutting features when timeline pressure hits. + +--- + +## Cost of Delay / Weighted Shortest Job First + +A framework from lean product development. Optimizes for delivering value sooner. + +**How it works:** + +``` +Priority = Cost of Delay / Job Duration +``` + +- **Cost of Delay:** What is the cost (in revenue, risk, customer impact) of NOT doing this for one more period? +- **Job Duration:** How long will this take? + +The work with the highest "Cost of Delay per unit time" gets done first. + +**Example:** + +A revenue-impacting bug: +- Cost of Delay: $5,000 per week of lost conversions +- Duration: 1 week +- Priority score: 5,000 + +A large feature: +- Cost of Delay: $20,000 per week of unrealized revenue +- Duration: 12 weeks +- Priority score: 1,667 + +Even though the feature has higher absolute cost of delay, the bug ships first because it delivers value faster. + +**Strengths:** Captures urgency. Useful for revenue-sensitive decisions. + +**Weaknesses:** Cost of Delay is hard to estimate. + +**When to use:** Operational backlogs. Revenue-sensitive features. + +--- + +## Value vs Effort with strategic alignment + +A 3-axis variant for when strategic fit matters more than raw impact. + +**How it works:** score each candidate on: + +- **Value** (1 to 5) +- **Effort** (1 to 5, inverted - 5 means low effort) +- **Strategic fit** (1 to 5) + +Composite score: Value + Effort + Strategic fit. + +Candidates with the highest composite score win. + +**Strengths:** Captures that some valuable work is wrong for the company right now. + +**Weaknesses:** Three axes is more complex than most teams can sustain. + +**When to use:** When the team is being pulled toward locally-valuable work that does not advance the strategy. + +--- + +## The "next thing" framework + +The simplest, for solo founders or very small teams. + +**How it works:** ask one question: + +> "What is the single most important thing I could ship in the next two weeks?" + +Ship it. Then ask the question again. + +**Strengths:** Maximum focus. Avoids analysis paralysis. + +**Weaknesses:** Misses opportunities to batch related work. Susceptible to recency bias. + +**When to use:** Solo work. When the backlog is short. When velocity matters more than precision. + +--- + +## Choosing a framework + +| Situation | Framework | +|---|---| +| Long backlog, need triage | Impact / Effort matrix | +| Comparing features for the next quarter | RICE | +| Defining a release scope | MoSCoW | +| Revenue-sensitive operations work | Cost of Delay / WSJF | +| Strategic misalignment risk | Value + Effort + Strategic fit | +| Solo founder, weekly cadence | "Next thing" | + +The frameworks are tools. The output is a prioritized list. If the list is helpful and team agrees, the framework worked. If it's not, try another framework or revisit the inputs. + +--- + +## Common pitfalls + +- **Framework theater.** Spending more time on the framework than the work. Pick one. Move on. +- **Estimate inflation.** Engineers underestimate effort by 2x. PMs overestimate impact by 3x. Calibrate over time. +- **Static prioritization.** A one-time sort that never gets revisited. Re-prioritize at least monthly. +- **Ignoring sunk cost dynamics.** Just because you've worked on something for 3 months does not mean it deserves to ship. Cut your losses if the priority math no longer works. +- **Optimizing the wrong metric.** A framework's output is only as good as the metric you're optimizing for. Make sure that metric is correct. +- **Treating the score as truth.** A RICE score is a directional signal, not a verdict. Use judgment alongside the math. + +--- + +## Recommended default + +For most teams, the default is: + +1. **Impact / Effort matrix** for triage and backlog grooming +2. **RICE** for comparing feature candidates within a quarter +3. **MoSCoW** for release scoping when timeline is fixed + +That covers 90 percent of prioritization decisions a typical product team faces. diff --git a/dist/pi/.agents/skills/product-analytics-setup/SKILL.md b/dist/pi/.agents/skills/product-analytics-setup/SKILL.md new file mode 100644 index 0000000..926677a --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/SKILL.md @@ -0,0 +1,308 @@ +--- +name: product-analytics-setup +description: "How to actually instrument product analytics correctly. Event taxonomy, property design, naming conventions, schema versioning, identity stitching, funnel design, retention cohorts, North Star metric selection, dashboard hygiene, instrumentation debt, and the failure modes that produce data nobody trusts. Triggers on product analytics setup, event taxonomy, tracking plan, instrumentation, schema versioning, North Star metric, retention cohorts, funnel design, naming conventions, instrument new feature, audit existing analytics, dashboard reconciliation, instrumentation debt, Mixpanel setup, Amplitude setup, PostHog setup, warehouse-native analytics. Also triggers when the team has data but cannot trust it, or when designing instrumentation for a new feature, or when auditing an existing setup that has drifted." +category: product +catalog_summary: "Instrument product analytics correctly: event taxonomy, properties, naming conventions, schema versioning, funnels, retention cohorts, North Star selection, and the instrumentation debt that compounds without discipline" +display_order: 8 +--- + +# Product Analytics Setup + +A senior PM and analyst's playbook for instrumenting product analytics correctly the first time. + +Most product analytics setups are some combination of inherited mistakes, dashboard sprawl, and events nobody trusts. The team launches a new feature; instrumentation gets bolted on under deadline pressure; naming drifts; properties are inconsistent; six months later nobody can answer simple questions because the answer depends on which event you trust. + +This skill is the discipline that prevents that. It assumes you have answered the strategic questions about what to measure (see `analytics-strategy`). It assumes you have a tool connected (Mixpanel, Heap, PostHog, Amplitude, or warehouse-native via BigQuery, Snowflake, or dbt). The hard part is the systematic execution: naming conventions, property design, schema versioning, funnel construction, cohort definitions, retention measurement. + +When to use this skill: setting up product analytics from scratch, auditing an existing instrumentation, fixing a "we have data but cannot trust it" problem, or designing instrumentation for a new feature. + +--- + +## What this skill is for + +This skill spans instrumentation execution. It does not cover measurement strategy (use `analytics-strategy`), experimentation result interpretation (use `experimentation-analytics`), paid media analytics (use `ads-performance-analytics`), or platform decisions (use `experimentation-platform-orchestrator`). Pair this skill with the relevant integrations microsite for your specific tool. + +The clean distinction from analytics-strategy. That skill (Growth category) is strategic: what to measure and why, KPI hierarchy, dashboard architecture, attribution models. This skill (Product category) is execution: how to actually instrument the product correctly. The two compose. Read analytics-strategy first to decide what matters; read this skill to instrument it. + +--- + +## The instrumentation hierarchy + +The mental model. Every analytics setup is a stack of layers. Each layer depends on the one below it being correct. + +- **Events** are the atomic facts: `user_signed_up`, `checkout_completed`, `feature_x_used`. +- **Properties** describe events: who, what, where, when, with what context. +- **Identities** map events to people: `anonymous_id`, `user_id`, `account_id`. +- **Cohorts** are filters across events: "users acquired via paid in March." +- **Funnels** are sequences of events: signup, then activated, then first paid action. +- **Retention** measures repeat behavior: signups still active at week N. + +You cannot construct higher levels without correct lower levels. Garbage events produce garbage funnels. The discipline is bottom-up. Most "we have data but cannot trust it" problems trace back to the bottom two layers. + +--- + +## Event taxonomy design + +Three rules for event design. + +1. **Past tense, action-oriented.** `checkout_completed`, not `checkout_complete` or `completing_checkout`. Past tense reads as "this happened" rather than as a state. +2. **Object-action format.** Noun then verb. `video_played`, `form_submitted`, `email_opened`. Reading the event name aloud should describe what happened. +3. **Granular but not redundant.** Track distinct user actions, not button clicks. Fire `checkout_completed` once at the moment of completion, not `submit_button_clicked` plus `checkout_completed`. UI events are noise; semantic events are signal. + +The verbs vs states trap. + +- Verbs ARE events. `checkout_completed`, `subscription_canceled`, `account_upgraded`. +- States are NOT events; they are properties. `user_status: active` is a property on the user, not an event. Setting state via events ("status_changed_to_active") is a code smell that produces double-counting. + +How many events to design. Thirty to fifty events is the sweet spot for a typical SaaS product. Below twenty means under-instrumented; above one hundred almost always means tracking UI noise or duplicating events in different formats. + +Detail and a canonical event spec in [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md). + +--- + +## Property design: event-level vs user-level + +Two property types, treated separately. + +**Event-level properties** describe THIS event. The `checkout_completed` event has properties like `cart_value`, `item_count`, `payment_method`, `discount_code`. They live on the event payload and are immutable once fired. + +**User-level properties** describe the USER over time. `subscription_tier`, `lifetime_value`, `acquisition_channel`. Set them once on the user profile; the analytics tool joins them onto every event the user fires. They update over time as the user changes. + +The trap. Putting user-level properties on every event. Do not track `subscription_tier` on every event payload; set it once on the user profile and rely on the join. Putting it on the event creates payload bloat, schema drift when the value changes, and reporting confusion when a user upgrades mid-session. + +Data type discipline. + +- **Strings** for enums: status, tier, channel, region. Enumerable values where the set is bounded. +- **Numbers** only for actual numbers: count, value, duration, score. Never use strings for numeric data ("free trial day 7" should be `trial_day: 7`). +- **Booleans** for actual booleans: `is_admin`, `has_trial`, `is_new_user`. Two values; nothing else. +- **Timestamps** in ISO 8601, always. Always. The number of bugs caused by inconsistent date formats is uncountable. +- **Arrays** rarely. An array property is usually a sign you should split into multiple events with one item per event. + +Worked example in [`references/property-design-patterns.md`](references/property-design-patterns.md) showing right and wrong design for a `product_viewed` event. + +--- + +## Naming conventions + +Pick ONE convention and enforce it. Three conventions worth picking. + +- **snake_case** for events and properties: `user_signed_up`, `cart_value`. Most platforms default to this; pushback is rarely worth it. +- **Object-action format** for events: `user_signed_up`, `video_played`. Reading the name should describe what happened. +- **Verb-noun for user properties** (or just nouns): `subscription_tier`, `is_admin`, `last_active_at`. + +What NOT to do. + +- Mixed case across events. `user_signedUp`, `User Signed Up`, `userSignedUp` all coexisting in the same project. Pick one and migrate. +- Spaces in event or property names. "Sign Up Completed" breaks every URL-encoding scenario and confuses every tool. +- Inconsistent verbs. `user_signed_up` plus `completedCheckout` plus `VIEW_PRODUCT` in the same project means nobody can predict an event name without looking it up. +- Brand names in event names. `mailchimp_email_opened` ages badly when you switch to Customer.io. + +The naming convention reference file provides a complete style guide. Cite it in your team's data contract. + +Detail in [`references/naming-convention-reference.md`](references/naming-convention-reference.md). + +--- + +## Schema versioning + +Schema changes are inevitable. The pattern. + +**Additive changes** are safe. New event, new property on an existing event, new value in an enum. Just ship. Existing dashboards continue to work. + +**Breaking changes** require migration. Renamed event, removed property, changed property type, narrowed enum. These break dashboards downstream; the migration plan is part of the change. + +Versioning patterns. + +- Append `_v2` to events when semantics change. `checkout_completed_v2` fires alongside `checkout_completed` during a transition. +- Keep old events firing during the transition (90 days is typical). Both versions fire; analytics queries gradually migrate to v2. +- Migrate dashboards to v2 before retiring v1. Then deprecate v1 explicitly with a documentation note. + +The data contract idea. + +- Document the canonical schema in code: TypeScript interface, JSON Schema, or Protobuf definition. +- Code review every schema change. Schema is product, not afterthought. +- CI lint rejects schema violations before they hit production. The deploy that adds an event with the wrong type fails the build. + +Detail in [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md). + +--- + +## Funnel design + +Funnels measure progression through a sequence. Four rules. + +1. **Order matters.** A then B then C is a different funnel from B then A then C. The platform will compute different conversion rates depending on order. +2. **Time windows matter.** Most funnels use a 1 to 30 day window from the first event. Document the window explicitly; "users who completed signup AND activated" is meaningless without "within 14 days." +3. **Drop-off interpretation is hard.** Eighty percent of users dropping at step 2 might be the funnel design (audience is wrong), might be the audience (timing is wrong), or might be the product (genuine drop-off). Investigate before declaring. +4. **The anchor event pattern.** Every funnel starts with a high-intent action: signup, trial start, key feature use. Not a vanity event like `page_view` or `session_start`. Vanity-event-anchored funnels show 99% drop-off and tell you nothing. + +Common funnel mistakes. + +- Funnels that include events firing automatically. `session_started` happens for every visit; using it as a step inflates the denominator and makes the rest of the funnel meaningless. +- Funnels too long (10+ steps). Break into two or three shorter funnels. A 10-step funnel produces near-zero end-to-end conversion that is hard to interpret. +- Funnels with the same event in multiple positions. The platform handles this poorly; the analyst handles it worse. +- Mixing different time windows in one funnel. "Users who signed up within 7 days AND converted within 30 days" is two different cohort definitions glued together. + +Common funnel shapes and time-window guidance in [`references/funnel-design-templates.md`](references/funnel-design-templates.md). + +--- + +## Cohort definitions + +A cohort is a group of users sharing an attribute or behavior. Useful patterns. + +- **Acquisition cohorts.** Users acquired in month X. The standard for retention analysis. +- **Behavioral cohorts.** Users who completed action Y. Useful for activation analysis ("users who sent first message in week 1"). +- **Property cohorts.** Users with `subscription_tier: pro`. Useful for segment-level analysis. +- **Combined cohorts.** Signup in March AND completed onboarding AND in EU. The most common in real analytics work. + +Cohort discipline. + +- Define cohorts in code (or in your tool's saved-cohort feature) so they are reusable. +- Version them when criteria change. Compare apples-to-apples. +- Do not compare a 30-day-old cohort to a 365-day-old cohort on retention; the older cohort has had more time to retain by definition. + +Detail in [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md). + +--- + +## Retention measurement + +Retention is repeat behavior over time. Three flavors. + +- **N-day retention.** Did user X come back on day 7, day 14, day 30 specifically. High noise on any single day; useful for short-cycle products. +- **Bracket retention.** Did user X come back at any point during the week 7 to 13 window. More stable than N-day; reads cleaner on retention curves. +- **Unbounded (rolling) retention.** Did user X come back any time after signup. Useful for longer-cycle products where weekly cadence is misleading. + +For most SaaS products, bracket retention is the right default. Day-7 is high-noise; week-2 (bracket) is more stable. Day-1 retention is almost always over-indexed to onboarding effects rather than product-market-fit signal. + +Retention curve interpretation. + +- Steep early drop, then plateau. The product has core users; the rest churn fast. Typical for most SaaS products. +- Gradual decay across weeks with no plateau. No one is sticking. Usually a value-prop or onboarding problem; the product is not delivering recurring value. +- Flat line at low percentage. A power-user product with a small but engaged base. Not a problem; just a different shape. + +Detail in [`references/retention-measurement-patterns.md`](references/retention-measurement-patterns.md). + +--- + +## North Star and supporting metrics + +North Star metric (NSM) selection rules. + +- Reflects user value, not company value alone. +- Captures the core action that, if it grows, the business grows. +- Measurable consistently across time. +- Hard to game. + +Bad NSMs. Signups (vanity; many signups never activate). Revenue (lagging; not action-oriented; varies by mix). DAU (only useful for engagement-driven products; misleads on monthly-cadence products). + +Better NSMs. Weekly active editors (Figma). Nights booked (Airbnb). Messages sent per day (Slack). Products created per workspace per week (Linear). Each names a user-value action that maps to business growth. + +Supporting metrics framework. + +- One NSM. +- Three to five input metrics that drive the NSM. For "weekly active editors" these might be: signups per week, signup-to-active conversion rate, week-over-week active retention. +- Five to ten health metrics that warn of problems. Monthly churn rate, account-level concentration, support ticket volume. + +Detail and product-type-specific examples in [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md). + +--- + +## The trustable dashboard principle + +A dashboard is trustable when four things are true. + +1. **Each metric has a clear definition** documented inline. Not "active users" but "users who fired any event in the last 7 days, deduplicated by user_id, excluding employees." +2. **Each metric has a known data source.** Not "from the warehouse" but "from `fct_orders`, last 30 days, joined to `dim_customers`." +3. **Each metric has known caveats.** Modeled iOS conversions excluded. Internal employees excluded. Test users in QA accounts excluded. +4. **Each metric is reproducible.** The same query, run tomorrow, produces the same number for the same time period. + +The stale dashboard failure mode. A dashboard built two years ago is still in use. The underlying schema changed; the dashboard's query points at columns that no longer exist or now mean something different. The team makes decisions on broken numbers and does not realize until something breaks loudly. + +Prevention. Every dashboard has an owner, a refresh cadence, and a quarterly audit. Dashboards without an owner get deprecated. Dashboards that have not been refreshed in 90 days get deprecated. The half-life of a dashboard is shorter than the half-life of the product. + +--- + +## Instrumentation debt + +The compounding cost of cutting corners. + +- New feature ships without instrumentation: 1 hour saved. +- Six months later: nobody can answer "is feature X working?" +- Cost to retroactively instrument: 20 hours (re-deploy, backfill, validate). +- Cost in lost decisions during the gap: untrackable but real. Decisions get made on intuition rather than data; sometimes the intuition is wrong. + +Instrumentation debt is real and compounds like technical debt. The discipline. + +- Every PR for new functionality includes instrumentation. The PR template asks "what events does this fire?" and rejects the PR if the answer is none. +- Quarterly schema audits. Identify orphan events (firing but not used in any dashboard or query) and deprecate them. Identify gaps (features without events) and fill them. +- "If we cannot measure it, we do not ship it" with explicit exceptions for genuinely experimental features where the cost of instrumentation exceeds the value of the data. + +Detail in [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md). + +--- + +## Common failure modes + +Twelve patterns recur across product analytics setups. The short version. + +- "We have data but cannot trust it." Naming and schema drift. Fix is a schema audit plus naming convention enforcement. +- "Our funnel says 80% drop-off but real conversion is fine." Wrong anchor event or wrong window. Fix the funnel definition. +- "Retention curve is flat at 5%." Often not a problem. Power-user products genuinely have small engaged bases. Compare against business reality before treating as a fix-it. +- "Mixpanel says 1000 conversions, warehouse says 800." Attribution plus identity stitching mismatch. Reconcile against warehouse for canonical numbers. +- "Dashboards take 30 seconds to load." Over-broad queries, unindexed properties, or schema bloat. Profile and refactor. +- "Everyone has their own definition of MAU." No canonical metric document. Ship one; force everyone to use the same definition. +- "We track every button click." UI noise. Audit and remove events that are not used by any dashboard or query. +- "Our event names changed three times." No versioning. Migrate to a versioning pattern; freeze further renames. +- "Analytics tool says iOS users converted 3% but warehouse says 5%." iOS Intelligent Tracking Prevention plus modeled conversions. Treat platform iOS data with extra skepticism. +- "We cannot answer simple questions." Under-instrumented or wrong abstraction layer. Audit the events list against the questions the team is asking; fill the gaps. +- "Two analysts compute different MAU." Different identity stitching. Pick one canonical identity layer and make everyone query from it. +- "Numbers are different than last quarter for no reason." Underlying schema changed without versioning. The dashboard quietly broke; nobody noticed until the gap got large. + +Detail in [`references/common-failures.md`](references/common-failures.md). + +--- + +## The framework: 12 considerations for trustable product analytics + +When designing or auditing product analytics, walk these 12 considerations. Skipping any of them is how the team ends up with data nobody trusts. + +1. **Event taxonomy.** Past tense, object-action, granular but not redundant. Verbs are events; states are properties. +2. **Property design.** Event-level vs user-level. Type discipline. ISO 8601 timestamps everywhere. +3. **Naming conventions.** Pick one and enforce it. snake_case wins by default. +4. **Schema versioning.** Additive vs breaking. `_v2` suffix during transitions. Data contract in code. +5. **Identity stitching.** Anonymous to authenticated, cross-device, cross-tool. One canonical identity layer. +6. **Funnel design.** Anchor on high-intent events. Document time windows. No auto-firing events as steps. +7. **Cohort definitions.** Reusable, versioned, apples-to-apples. Defined in code or saved in the tool. +8. **Retention measurement.** Bracket over N-day for stability. Compare cohorts at matched ages. +9. **North Star.** Captures user value. Hard to game. One NSM, three to five inputs, five to ten health metrics. +10. **Dashboard hygiene.** Definitions, sources, owners, refresh cadence. Stale dashboards get deprecated. +11. **Instrumentation debt.** Every PR includes instrumentation. Quarterly audits. +12. **Single source of truth.** Warehouse for board metrics. Tool for in-flight optimization. Reconcile when they disagree. + +The output of the framework is a tracking plan. A list of events with their properties, the canonical user identity, the named cohorts, the named funnels, the retention measurement choice, the named NSM, the dashboard owners. The plan lives in code and gets reviewed like any other product spec. + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Canonical event spec for typical SaaS: account, user, activation, engagement, conversion, retention events with required properties. +- [`references/property-design-patterns.md`](references/property-design-patterns.md) - Event-level vs user-level patterns. Type discipline. Worked example: `product_viewed` right vs wrong. +- [`references/naming-convention-reference.md`](references/naming-convention-reference.md) - Complete style guide. snake_case, past tense, object-action. Boolean prefixes. Money in cents. Timestamps with `_at` suffix. Do/don't side-by-side. +- [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md) - Additive vs breaking changes. `_v2` suffix pattern. Data contract in TypeScript. CI lint patterns. +- [`references/funnel-design-templates.md`](references/funnel-design-templates.md) - Activation, conversion, engagement, feature adoption funnels. Time windows, anchor events, drop-off interpretation. +- [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md) - Acquisition, behavioral, property, combined cohorts. SQL examples plus tool-specific examples. +- [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md) - NSM rules with examples by product type. Anti-patterns. Migration patterns when changing NSM. +- [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md) - Quarterly audit playbook: schema review, volume sanity checks, dashboard freshness, owner audit, deprecation candidates. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: when in doubt, instrument less + +Most product analytics setups are over-instrumented, not under-instrumented. Tracking every button click produces noise that drowns the signal. The discipline of saying "we do not need to track that" is harder than "let us track that just in case." Default to less. + +The data you do not have can be added later. The data you over-collected costs you forever, in dashboard performance, in schema complexity, in signal-to-noise. The team that ships with thirty well-designed events and a small set of named cohorts outperforms the team that ships with two hundred events and no cohort discipline. + +When the team disagrees on whether to add an event, the question is not "could this be useful?" but "what specific decision will this event inform, and is the decision worth the instrumentation cost?" If the answer is "we might want to know" the answer to the question is no. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md new file mode 100644 index 0000000..1dc8ca5 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md @@ -0,0 +1,202 @@ +# Cohort definition patterns + +Four cohort patterns: acquisition, behavioral, property, combined. With SQL examples for warehouse-native and tool-specific examples for Mixpanel, Amplitude, and PostHog. + +--- + +## Pattern 1: acquisition cohort + +Users acquired in a specific time window. The standard for retention analysis. + +### Definition + +```sql +-- Warehouse-native (BigQuery / Snowflake / Postgres) +SELECT user_id +FROM dim_users +WHERE first_seen_at >= '2026-04-01' + AND first_seen_at < '2026-05-01'; +``` + +### Tool-specific + +**Mixpanel.** Cohort builder, condition: "First time the user did `user_signed_up` was between April 1 and April 30, 2026." + +**Amplitude.** User segment, condition: "First event date between April 1 and April 30, 2026." + +**PostHog.** Cohort, condition: "Person property `first_seen` is between April 1 and April 30, 2026." + +### Use cases + +- Retention analysis. Compare retention curves across acquisition cohorts to detect product or onboarding regressions. +- Onboarding A/B test results. The treatment cohort and control cohort are both acquisition cohorts. +- Cohort revenue tracking. How much did April's signups generate over the next 12 months? + +### Common mistakes + +- Comparing cohorts at different ages. A 30-day-old cohort has lower retention than a 90-day-old cohort by definition. +- Using "user created" vs "first event" inconsistently. Pick one and document it. + +--- + +## Pattern 2: behavioral cohort + +Users who completed a specific action. The standard for activation and engagement analysis. + +### Definition + +```sql +-- Users who fired first_value_action_completed within 14 days of signup +SELECT u.user_id +FROM dim_users u +JOIN fct_events e ON e.user_id = u.user_id +WHERE e.event_name = 'first_value_action_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '14 days'; +``` + +### Tool-specific + +**Mixpanel.** Cohort builder, condition: "User did `first_value_action_completed` at least once where event time was within 14 days of `user_signed_up`." + +**Amplitude.** Behavioral cohort, "Performed event `first_value_action_completed` within 14 days after first event." + +**PostHog.** Cohort, condition: "Person performed event `first_value_action_completed` and the event happened within 14 days of person creation." + +### Use cases + +- Activation funnel: activated users vs non-activated users. +- Feature adopters: users who used feature X. How does their retention compare to non-adopters? +- Power users: users who fired a specific high-value event 5 or more times. + +### Common mistakes + +- Using behavioral cohorts for retention without a time anchor. "Users who completed onboarding" includes users from January and users from October; their retention curves are at different ages. +- Confusing "users who ever did X" with "users who did X recently." Specify the time window. + +--- + +## Pattern 3: property cohort + +Users with a specific property value. The standard for segment-level analysis. + +### Definition + +```sql +SELECT user_id +FROM dim_users +WHERE subscription_tier = 'pro' + AND region = 'us' + AND is_admin = false; +``` + +### Tool-specific + +**Mixpanel.** Cohort, condition: "User properties: `subscription_tier = pro` AND `region = us`." + +**Amplitude.** User segment, condition: "User properties match: `subscription_tier = pro` AND `region = us`." + +**PostHog.** Cohort, condition: "Person properties: `subscription_tier = pro` AND `region = us`." + +### Use cases + +- Segment performance: how does the Pro tier behave differently from the Free tier? +- Geographic analysis: do EU users convert at a different rate than US users? +- Role-based analysis: do admins use the product differently than members? + +### Common mistakes + +- Using event-level properties as if they were user-level. "Users who fired any event with `cart_value > 100`" returns events, not users; use a behavioral cohort for "users who fired a high-value event." +- Snapshot vs current property values. "Users who were Pro in March" vs "users who are Pro now" are different cohorts; some platforms default to current values without warning. + +--- + +## Pattern 4: combined cohort + +Combinations of the above. The most common in real analytics work. + +### Definition + +```sql +-- Users who signed up in March, completed onboarding within 7 days, +-- are in EU, and are on the Pro tier +SELECT u.user_id +FROM dim_users u +WHERE u.first_seen_at >= '2026-03-01' + AND u.first_seen_at < '2026-04-01' + AND u.region = 'eu' + AND u.subscription_tier = 'pro' + AND EXISTS ( + SELECT 1 FROM fct_events e + WHERE e.user_id = u.user_id + AND e.event_name = 'onboarding_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '7 days' + ); +``` + +### Tool-specific + +All three platforms support combined cohorts via boolean composition (AND, OR, NOT). The composition gets unwieldy past 4 or 5 conditions; consider whether the cohort is genuinely useful or whether the team is over-segmenting. + +### Use cases + +- Activation analysis by acquisition channel: "Paid Meta users who signed up in March and activated within 7 days." +- Quality cohorts: "Pro tier users acquired via organic search who reached aha_moment within 14 days." +- Test cohorts: "Treatment group users who completed the onboarding A/B test within 7 days." + +### Common mistakes + +- Cohorts so narrow that the population is too small for analysis. A cohort of 50 users has high variance on every metric. +- Combining conditions that contradict each other. "Pro tier free users" returns nothing. +- Forgetting to time-box. A combined cohort without acquisition or behavioral time bounds drifts as users join and leave. + +--- + +## Cohort discipline + +Three rules that apply across all four patterns. + +### Rule 1: define cohorts in code (or saved in the tool) + +Re-querying the same cohort definition by hand each time produces inconsistencies. Define the cohort once; reuse the definition across analyses. + +In SQL: a `WITH` clause or a saved view. + +```sql +WITH march_cohort AS ( + SELECT user_id + FROM dim_users + WHERE first_seen_at >= '2026-03-01' + AND first_seen_at < '2026-04-01' +) +SELECT COUNT(*) FROM march_cohort; +``` + +In analytics tools: saved cohorts. Every analysis references the saved cohort by name. + +### Rule 2: version when criteria change + +A cohort definition that evolves over time produces non-comparable results. If you change the activation definition, the new cohort is a different cohort. + +Pattern. Append `_v2` to the cohort name when criteria change. Keep the old definition queryable for historical comparison. + +### Rule 3: compare apples-to-apples + +Two cohorts compared at different ages produce misleading conclusions. Always compare at matched ages. + +If comparing March cohort retention against November cohort retention, both should be measured at the same number of days post-acquisition. November cohort at 30 days vs March cohort at 60 days is not a fair comparison. + +--- + +## When to introduce a cohort + +The team has a question that filters on a user attribute or behavior. The question repeats across analyses. The team is computing the same filter 5+ times by hand. + +That is the trigger. Define the cohort once; reuse it. + +--- + +## When to deprecate a cohort + +The cohort has not been queried in 90 days. The cohort criteria no longer match a real product question (e.g., the feature it tracked was deprecated). The team has built a more precise replacement cohort. + +Stale cohorts in the analytics tool produce dropdown clutter and tempt analysts to use them when newer cohorts are appropriate. Deprecate explicitly. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md b/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md new file mode 100644 index 0000000..9e5fa5e --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across product analytics setups. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. We have data but cannot trust it + +**Symptom.** The team has years of events. Two analysts run the same query and get different numbers. Stakeholders ask for "the real number" and the answer is "it depends." + +**Root cause.** Naming and schema drift over time. Same event name has slightly different semantics in different code paths. Properties have inconsistent types or values. + +**Fix.** Schema audit. Identify the canonical events; deprecate the duplicates and aliases. Standardize property types. Document the canonical definitions. + +**Prevention.** Schema in code (TypeScript interface or JSON Schema). CI lint that rejects schema violations. Naming convention enforcement. + +--- + +## 2. Funnel says 80% drop-off but real conversion is fine + +**Symptom.** The activation funnel shows 20% conversion. The team knows from revenue numbers that real activation is 60%. + +**Root cause.** Wrong anchor event (using a too-broad event like `page_view` as the start) or wrong time window (asking for activation within 24 hours when the real cycle is 14 days). + +**Fix.** Audit the funnel definition. Anchor on a high-intent event (signup, trial start). Set the time window to match the actual activation cycle. + +**Prevention.** Document the funnel anchor and window in the funnel definition itself, not implicit in dashboard text. Review funnels at each quarterly audit. + +--- + +## 3. Retention curve is flat at 5% + +**Symptom.** Retention curve drops fast then plateaus at 5%. The team panics; only 5% of users are active. + +**Root cause.** Not always a problem. Some products are power-user products with small but engaged bases (developer tools, niche B2B software). The 5% may be the natural shape. + +**Fix.** Compare against business reality. If 5% retention with strong unit economics, the curve is healthy. If 5% retention and the business model assumes 20% retention, then it is a problem and the cohort needs investigation. + +**Prevention.** Set retention targets based on business model assumptions, not industry benchmarks. The right retention for a niche tool is different from the right retention for a consumer app. + +--- + +## 4. Mixpanel says 1000 conversions, warehouse says 800 + +**Symptom.** Two systems report different conversion counts for the same event. + +**Root cause.** Identity stitching mismatch. Mixpanel may stitch anonymous-to-authenticated differently than the warehouse. Server-side and client-side fires of the same event may not deduplicate correctly. Time-window differences (Mixpanel using event time, warehouse using ingest time). + +**Fix.** Pick one source as canonical (warehouse for board metrics, tool for in-flight). Reconcile the gap by understanding the cause. Document the expected gap so stakeholders are not surprised. + +**Prevention.** Identity stitching pattern documented and consistent. Server-side and client-side firing for the same event handled with explicit deduplication. Use a single time field consistently. + +--- + +## 5. Dashboards take 30 seconds to load + +**Symptom.** The team's main dashboard takes 30+ seconds to refresh. Reviewing a metric becomes a coffee break. + +**Root cause.** Over-broad queries (scanning years of data for a 30-day metric). Unindexed properties used as filters. Schema bloat from too many events or too many properties on each event. + +**Fix.** Profile the slow queries. Add date filters. Index the filter properties. Pre-aggregate metrics into a daily summary table; query the summary, not the raw events. + +**Prevention.** Set query budgets per dashboard (target: under 5 seconds). Audit performance during the quarterly audit. Cap the data volume per query. + +--- + +## 6. Everyone has their own definition of MAU + +**Symptom.** Three people compute MAU; three different numbers. + +**Root cause.** No canonical definition. One person counts unique user_ids firing any event. Another counts users who fired a specific qualifying event. Another counts authenticated users only. + +**Fix.** Write a canonical metric document. "MAU is unique user_ids firing any event in the last 30 days, deduplicated, excluding employee accounts (employees identified by email domain) and excluding test accounts (account_type = 'test')." Force everyone to use this definition. + +**Prevention.** Canonical metric document maintained as living documentation. Every dashboard's metric definitions reference the canonical document. Disagreements get resolved by updating the document, not by recomputing on the fly. + +--- + +## 7. We track every button click + +**Symptom.** The event list has 800 events. Many are individual button clicks. Dashboards are slow; analyses produce noise. + +**Root cause.** Tracking UI events (clicks, hovers, page views) rather than semantic events (created, completed, shared). Each button gets its own event "for completeness." + +**Fix.** Audit the event list. Deprecate UI events. Replace with semantic events that capture user intent. + +**Prevention.** Naming convention enforcement (verbs are events; UI states are properties). Code review on new events asks "is this a semantic event or a UI event?" UI events get rejected unless there is a specific use case. + +--- + +## 8. Our event names changed three times + +**Symptom.** `signup_complete`, then `signupCompleted`, then `user_signed_up`. Dashboards reference all three; nobody knows which is current. + +**Root cause.** No versioning. Each rename happened without coordination, leaving old events in the warehouse and old queries in the dashboards. + +**Fix.** Migrate to a single canonical version. Use the `_v2` pattern if semantics changed. Deprecate old versions explicitly. Update all dashboards. + +**Prevention.** Versioning pattern in the schema documentation. Schema review on every PR that adds or modifies an event. CI lint on event names. + +--- + +## 9. Analytics tool says iOS users converted 3% but warehouse says 5% + +**Symptom.** iOS conversion rate looks bad in the analytics tool but fine in the warehouse. + +**Root cause.** iOS Intelligent Tracking Prevention (ITP) blocks third-party cookies, breaking attribution for iOS users. The analytics tool models the missing data; the warehouse uses server-side conversion tracking that is unaffected. + +**Fix.** Treat iOS analytics-tool data with extra skepticism. Use the warehouse for canonical iOS metrics. Set up server-side event tracking (Conversions API for Meta, server-side GA4) where possible. + +**Prevention.** Document the iOS measurement gap. Pair every iOS-specific metric with a note on the data source. + +--- + +## 10. We cannot answer simple questions + +**Symptom.** Stakeholder asks: "How many users came back this week?" Three days of analyst time later, still no clean answer. + +**Root cause.** Under-instrumented or wrong abstraction layer. The events list does not include the right event. The user identity layer does not stitch correctly. The cohort definition is too narrow or too broad. + +**Fix.** Audit the event list against the questions the team actually asks. Fill gaps with new events; fix identity stitching; create canonical cohorts for the most common questions. + +**Prevention.** Quarterly review of the question backlog. Map questions to events; identify gaps. Fill gaps proactively, not after the question goes unanswered. + +--- + +## 11. Two analysts compute different MAU on the same data + +**Symptom.** Same query, same data, different numbers. The discrepancy is not because of a definition disagreement; it is because the queries silently return different rows. + +**Root cause.** Different identity stitching layers. One query uses user_id; another uses anonymous_id with stitching applied at query time. Edge cases (users who logged out and back in, users on multiple devices) get counted differently. + +**Fix.** Pick one canonical identity layer. Build a `dim_users` table in the warehouse that resolves identity once. Force all queries to join through this table. + +**Prevention.** Identity-stitching pattern documented. New queries use the canonical table. Code review rejects queries that bypass the layer. + +--- + +## 12. Numbers different than last quarter for no reason + +**Symptom.** A dashboard's metrics shifted between Q1 and Q2 by 30%. No product change, no instrumentation change... or so it seems. + +**Root cause.** Underlying schema changed without versioning. An event was renamed; the dashboard's query points at the old name and now silently returns nothing or returns a different cohort. Often discovered weeks after the fact. + +**Fix.** Audit the dashboard's query against the current schema. Update to current event names. Check for similar drift in other dashboards. + +**Prevention.** Versioning pattern enforced. CI lint catches event renames before they ship. Quarterly dashboard audit catches drift early. + +--- + +## The pattern across all twelve + +Most product analytics failures share one root cause: cutting corners during instrumentation produces compounded debt that surfaces months later as untrustworthy data. The team that ships without a tracking plan saves an hour at instrumentation time and pays 20+ hours at audit time. + +The fix at the meta level. Treat instrumentation as a first-class engineering concern. Schema in code. Naming convention enforced. Quarterly audits. Single source of truth for canonical metrics. Instrumentation debt is real; the discipline of paying it down regularly is the only thing that keeps the data trustworthy. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md b/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md new file mode 100644 index 0000000..86bb1df --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md @@ -0,0 +1,114 @@ +# Event taxonomy template + +A canonical event spec for typical SaaS. Six event categories with the events that belong in each, when they fire, who fires them (client or server), required properties, and common pitfalls. + +The principle. Thirty to fifty events covers most SaaS products. Below twenty is under-instrumented; above one hundred is usually UI noise. The categories below are the durable shape; the specific event names map to your product. + +--- + +## Account events + +Account-level lifecycle. Server-side firing typical because billing is server-side. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `account_created` | A new account (workspace, organization) is provisioned. | `account_id`, `plan_tier`, `seat_count` | Distinct from `user_signed_up` (a user can join an existing account). | +| `account_upgraded` | The account moves to a higher plan tier. | `account_id`, `from_tier`, `to_tier`, `change_reason` | Fires server-side from the billing webhook. | +| `account_downgraded` | The account moves to a lower plan tier. | `account_id`, `from_tier`, `to_tier`, `change_reason` | Same source as upgrade. | +| `account_canceled` | The account cancels and stops renewing. | `account_id`, `cancellation_reason`, `final_term_end_at` | Cancellation reason is critical; capture it from the cancellation flow. | +| `seat_added` | A new seat is provisioned on the account. | `account_id`, `seat_count_after`, `added_by_user_id` | Useful for net-revenue-retention analysis. | +| `seat_removed` | A seat is released from the account. | `account_id`, `seat_count_after`, `removed_by_user_id`, `removal_reason` | | + +Common pitfall. Firing account events client-side from the admin UI. The admin's browser may not be open during the cancellation; server-side from the billing webhook is the right source. + +--- + +## User events + +User-level lifecycle. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `user_signed_up` | A user creates an account or joins an existing account. | `user_id`, `account_id`, `signup_source`, `referrer_source` | Distinct from `account_created`; one account, many users. | +| `user_invited` | An existing user invites a new user. | `inviter_user_id`, `invited_email`, `account_id`, `invitation_role` | The invitation event; `user_signed_up` fires later when the invite is accepted. | +| `user_role_changed` | A user's role within the account changes. | `user_id`, `account_id`, `from_role`, `to_role`, `changed_by_user_id` | | +| `user_logged_in` | A user authenticates after a logged-out state. | `user_id`, `auth_method`, `device_type` | Different from session start. Logged-in across multiple sessions. | +| `user_logged_out` | A user explicitly signs out. | `user_id`, `logout_reason` | Often missed; explicit signout vs session timeout. | +| `user_deactivated` | A user's account is deactivated. | `user_id`, `account_id`, `deactivation_reason` | Soft delete pattern. | + +--- + +## Activation events + +The first-value moment. Critical for activation analysis. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `onboarding_step_completed` | The user completes a step in the onboarding flow. | `user_id`, `step_name`, `step_number`, `time_in_step_s` | Step name is canonical; do not change it without versioning. | +| `onboarding_completed` | The user finishes all onboarding steps. | `user_id`, `total_time_s`, `steps_completed_count` | Distinct from activation; onboarding completion does not equal activation. | +| `first_value_action_completed` | The user does the thing that delivers product value for the first time. | `user_id`, `action_name`, `time_since_signup_s` | Define this carefully per product. For Slack, first message sent. For Figma, first frame created. | +| `aha_moment_reached` | The user crosses the activation threshold. | `user_id`, `threshold_metric`, `threshold_value` | Tied to the activation definition (e.g., "5 messages in week 1"). | + +--- + +## Engagement events + +Recurring product use. The bulk of event volume. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `feature_x_used` | The user invokes feature X. Replace x with the actual feature name. | `user_id`, `feature_name`, `entry_point` | Granularity guidance: one event per feature, not one event per button. | +| `content_y_created` | The user creates a new asset (document, project, message, etc.). | `user_id`, `content_type`, `content_id`, `creation_source` | | +| `content_y_edited` | The user modifies an existing asset. | `user_id`, `content_type`, `content_id`, `edit_type` | High volume; consider sampling if storage is a concern. | +| `content_y_shared` | The user shares an asset externally. | `user_id`, `content_type`, `content_id`, `share_method`, `recipient_count` | Sharing is often the strongest engagement signal. | +| `search_executed` | The user runs an in-product search. | `user_id`, `query_length`, `result_count`, `clicked_result_position` | Capture click-through rates. | + +--- + +## Conversion events + +Money moves. Server-side firing required. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `trial_started` | The user starts a free trial. | `user_id`, `account_id`, `trial_plan`, `trial_length_days` | Server-side from the billing system. | +| `trial_converted` | The trial converts to paid. | `user_id`, `account_id`, `from_plan`, `to_plan`, `mrr_added` | Server-side. The MRR property feeds revenue analysis. | +| `trial_expired_no_conversion` | The trial ends without converting. | `user_id`, `account_id`, `trial_plan`, `usage_during_trial` | Useful for win-back campaigns. | +| `subscription_purchased` | A subscription begins (any path). | `user_id`, `account_id`, `plan_tier`, `mrr_added`, `purchase_source` | Includes trial conversions and direct purchases. | +| `subscription_renewed` | A subscription renews for the next term. | `account_id`, `plan_tier`, `mrr_at_renewal` | | +| `payment_failed` | A payment attempt fails. | `account_id`, `failure_reason`, `attempt_number` | Critical for involuntary churn analysis. | + +--- + +## Retention events + +Repeat behavior markers. Useful for retention curve construction. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `weekly_active_marker` | The user fires any qualifying event in a given week. | `user_id`, `week_of_year`, `qualifying_event_count` | Some teams compute this in the warehouse rather than fire it as an event; either pattern works. | +| `returned_after_n_days` | The user returns after N days of inactivity. | `user_id`, `inactive_days_count`, `last_active_at` | Useful for resurrection-flow analytics. | + +--- + +## Property requirements across all events + +Every event payload should include: + +- `user_id` (or `anonymous_id` for pre-auth events) +- `account_id` (where applicable; for B2B SaaS especially) +- `timestamp` (ISO 8601, server-stamped) +- `device_type` and `platform` (mobile, web, desktop) +- `app_version` (for change-tracking) +- `session_id` (for path analysis) + +Some platforms inject these automatically. Verify; do not assume. + +--- + +## Common pitfalls in event taxonomy + +- **Tracking page views as the primary engagement signal.** Page views are noise. Track semantic events (created, edited, shared) instead. +- **Treating onboarding completion as activation.** Many users complete onboarding without ever returning. Define activation as a recurring-value action, not as flow completion. +- **Inconsistent fire timing across the funnel.** Some events fire client-side, some server-side. Reconcile by picking one source per event and documenting it. +- **Adding new events without checking existing ones.** Six months in, the event list has three versions of "subscription started." Audit before adding. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md b/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md new file mode 100644 index 0000000..f7b110a --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md @@ -0,0 +1,174 @@ +# Funnel design templates + +Common funnel shapes with anchor events, time windows, and drop-off interpretation guidance. + +The principle. Every funnel measures progression through a sequence. The shape of the funnel must match the shape of the user behavior; mismatch produces conversion rates that are uninterpretable. + +--- + +## Activation funnel + +Signup to first value. The most important funnel for product-led growth. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `user_signed_up` | The anchor. High intent. | +| 2 | `onboarding_started` | The user begins the guided onboarding. | +| 3 | `onboarding_completed` | The user finishes onboarding. Note: this is not activation. | +| 4 | `first_value_action_completed` | The user does the action that delivers product value. THIS is activation. | +| 5 | `aha_moment_reached` | Optional. The threshold beyond which retention curves stabilize. | + +### Time window + +7 to 14 days from signup. Longer windows include users who activated after a long delay; shorter windows undercount slow adopters. + +### Anchor selection + +`user_signed_up` is the standard anchor. Avoid `landing_page_viewed` (too noisy) and `email_collected` (too low-intent). + +### Drop-off interpretation + +- 70%+ drop between signup and onboarding_started: the post-signup experience is the problem. Often a friction issue (email verification, account setup steps). +- 30%+ drop between onboarding_completed and first_value_action_completed: onboarding is teaching the wrong thing. Users complete the tour but do not understand the product. +- High drop at first_value_action_completed: the value action is too hard or too far from the user's natural path. Move it earlier in the experience. + +--- + +## Conversion funnel + +Trial to paid. The most important funnel for SaaS subscription businesses. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `trial_started` | The anchor. High intent and ready to evaluate. | +| 2 | `aha_moment_reached` | The user experiences product value. Critical predictor of conversion. | +| 3 | `paywall_viewed` | The user sees the upgrade prompt. | +| 4 | `checkout_started` | The user begins the payment flow. | +| 5 | `subscription_purchased` | The conversion. | + +### Time window + +The trial length plus a 7-day grace period. A 14-day trial uses a 21-day funnel window. Shorter windows undercount last-day conversions. + +### Anchor selection + +`trial_started` is the standard anchor. Funnels that start at signup (rather than trial start) include users who never engaged with the trial; the conversion rate looks lower than it actually is for engaged users. + +### Drop-off interpretation + +- High drop between aha_moment_reached and paywall_viewed: users got value but the paywall did not appear (timing issue) or did not feel relevant. Audit the paywall trigger logic. +- High drop between paywall_viewed and checkout_started: pricing or feature gating is the friction. Often a positioning issue rather than a UX issue. +- High drop between checkout_started and subscription_purchased: payment flow friction. UX audit the checkout pages; check failed-payment rates. + +--- + +## Engagement funnel + +Visit to action. Useful for understanding session-level conversion. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `feature_x_landing_page_viewed` | The anchor. Specific intent (feature page, not homepage). | +| 2 | `feature_x_used` | The user performs the core action. | +| 3 | `feature_x_completed_workflow` | The user finishes the workflow. | +| 4 | `content_y_shared` or similar high-intent action | Optional. Strongest engagement signal. | + +### Time window + +Single session, typically 30 to 60 minutes from the first event. + +### Anchor selection + +A feature-specific landing or entry point. Avoid `homepage_viewed` (too broad) and `session_started` (auto-firing, not intent). + +### Drop-off interpretation + +- High drop from landing to use: the page promises something the feature does not deliver, or the activation friction is too high. +- High drop from use to workflow completion: the workflow has too many steps, or a specific step has UX issues. + +--- + +## Feature adoption funnel + +Awareness to repeat use. Tracks how a feature spreads through the user base. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `feature_x_announced_to_user` | The anchor. The user saw a notification, prompt, or in-app message about feature X. | +| 2 | `feature_x_first_used` | The user tried feature X for the first time. | +| 3 | `feature_x_used_in_week_2` | The user used feature X again in a different week. | +| 4 | `feature_x_used_in_week_4` | Sustained adoption. | + +### Time window + +4 weeks from announcement. + +### Anchor selection + +The announcement event is the right anchor for measuring rollout effectiveness. For organic discovery (no announcement), use `feature_x_first_used` as the anchor and measure the feature's reach as a denominator. + +### Drop-off interpretation + +- High drop from announcement to first use: the announcement was missed, the announcement was unclear, or the feature was not relevant to the audience. Audit by user segment. +- High drop from first use to repeat use in week 2: the feature did not deliver value on first use. Either the use case was wrong (user tried it for the wrong thing) or the value-prop is weak. +- Adoption stalls at 5% of the user base: the feature is for a niche; this may be expected. Compare against the projected target audience size. + +--- + +## Common funnel design mistakes + +### Mistake 1: vanity-event anchor + +Using `homepage_viewed` or `session_started` as the anchor. The denominator is huge; the conversion rate is tiny; the funnel says nothing about user behavior. + +Fix. Anchor on a high-intent action: signup, trial_started, feature-specific page view. + +### Mistake 2: too long + +Ten or more steps. The end-to-end conversion rate is near zero; the funnel is hard to interpret; small numerator changes look like dramatic shifts. + +Fix. Break into 2 or 3 shorter funnels. An activation funnel plus a conversion funnel beats one 10-step funnel. + +### Mistake 3: auto-firing events as steps + +Including `session_started`, `app_opened`, or any event that fires automatically. The denominator is the entire user base; the meaning of conversion rates is muddled. + +Fix. Use only intentional, semantic events as funnel steps. + +### Mistake 4: same event in multiple positions + +Using `feature_used` at step 2 and step 5. The platform double-counts; the analyst gets confused. + +Fix. Distinguish via different events (`feature_first_used` vs `feature_used_in_week_2`) or via a property filter. + +### Mistake 5: mixed time windows + +The funnel definition allows step 2 within 7 days but step 4 within 30 days. The math becomes interpretable only by the analyst who built it; everyone else gets it wrong. + +Fix. One time window for the entire funnel. Document it explicitly. + +### Mistake 6: forgetting the cohort + +Running the funnel against "all users ever" rather than a specific acquisition cohort. The cohort matters; January users behave differently from November users. + +Fix. Always specify the cohort. "Users who signed up in March, evaluated against the activation funnel within 14 days." + +--- + +## Comparing funnels across cohorts + +The strongest analytical use of funnels is comparing how the funnel performs across cohorts. + +- This month's signup cohort vs last month's: is the funnel stable, or are recent users dropping more? +- Paid acquisition cohort vs organic: are paid users converting at the same rate, or are paid users worse-quality? +- Mobile vs web: is the experience parity issue real? + +Always compare cohorts at matched ages. A 30-day-old cohort vs a 60-day-old cohort has different conversion rates by definition. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md b/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md new file mode 100644 index 0000000..b481bff --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md @@ -0,0 +1,119 @@ +# Instrumentation audit checklist + +The quarterly playbook for keeping product analytics trustworthy. Five categories: schema, volume, dashboard freshness, ownership, deprecation. + +The principle. Instrumentation decays without active maintenance. Quarterly audits catch decay early; without them, the team ends up with the "we have data but cannot trust it" problem. + +--- + +## 1. Schema review + +Goal. Ensure the event taxonomy and property schema match the canonical contract. + +Steps. + +- **Pull the event list from the analytics tool.** Mixpanel: Lexicon. Amplitude: Govern. PostHog: Data Management. Or directly from the warehouse if warehouse-native. +- **Compare against the schema definition in code.** Every event in the tool should appear in the schema; every event in the schema should appear in the tool. +- **Flag drift.** Events firing without a schema entry. Schema entries with no events firing in the last 90 days. Property type mismatches between schema and observed values. +- **Audit naming.** Events that do not match the naming convention (snake_case, past tense, object-action). Property names with inconsistent casing or typo variants. +- **Action items.** For each drift item, decide: fix the schema, fix the tracking code, or deprecate the event. Document the decision. + +Cadence. Quarterly. More frequently if the team is shipping rapidly. + +--- + +## 2. Volume sanity check + +Goal. Confirm event volumes match expectations. + +Steps. + +- **Pull weekly event counts** for the last 90 days. Group by event name. +- **Identify volume anomalies.** Sudden drops (deployment broke instrumentation). Sudden spikes (a new code path is firing the event excessively or a bot is hitting the endpoint). Events whose volume drifts steadily down (the feature behind them was deprecated; instrumentation should follow). +- **Check ratios.** If `signup_started` fires 10x more than `signup_completed`, signup completion is broken or the events fire under different conditions than expected. If `checkout_started` fires more than `add_to_cart`, the events are misordered or one fires automatically. +- **Compare against business reality.** The dashboard says 50,000 weekly signups; the warehouse says 38,000 paying customers were acquired in the same period. The gap is fine if the business is in trial mode; alarming if the gap should be smaller. +- **Action items.** For each anomaly, identify the cause. Either the instrumentation is broken (fix it), the business changed (update expectations), or the event semantics drifted (version it). + +Cadence. Quarterly minimum. Real-time alerts on the highest-volume events for major deviations. + +--- + +## 3. Dashboard freshness review + +Goal. Identify dashboards that have rotted. + +Steps. + +- **Pull the dashboard inventory** from the analytics tool or BI platform. +- **Check last-viewed dates.** Dashboards not viewed in the last 90 days are candidates for deprecation. Dashboards not viewed in the last 180 days are almost always stale. +- **Check last-edited dates.** A dashboard last edited 18 months ago whose underlying schema changed is silently broken. Audit whether the dashboard's metrics still compute correctly. +- **Check ownership.** Every dashboard should have a named owner. Dashboards with no owner or with an owner who has left the company need reassignment or deprecation. +- **Spot-check key metrics.** Pick 5 to 10 dashboards. Compute the same metric directly from the warehouse. Compare. Drift over 5% needs investigation. +- **Action items.** Reassign orphan dashboards. Deprecate stale dashboards. Fix or rewrite dashboards that have drifted from underlying truth. + +Cadence. Quarterly. + +--- + +## 4. Owner assignment audit + +Goal. Every event, dashboard, cohort, and saved query has a named owner who can answer questions about it. + +Steps. + +- **Pull the ownership map** for events, dashboards, cohorts, saved queries. Most analytics tools support tagging or property fields for owner. +- **Identify orphans.** Items with no owner. Items whose owner has left the company. +- **Reassign.** For each orphan, assign a new owner or deprecate. Owner means "the person who can explain why this exists and what depends on it." It is not a vanity tag. +- **Document the chain of custody.** If the original owner left and the new owner is unfamiliar with the history, write down what you know. +- **Action items.** Update the ownership tags. Notify owners of items they are now responsible for. Set up a review cycle (every 6 months minimum) for owners to confirm or release ownership. + +Cadence. Quarterly minimum. Whenever someone leaves the team, immediately for their owned items. + +--- + +## 5. Deprecation candidates + +Goal. Identify and remove instrumentation, cohorts, and dashboards that no longer serve a purpose. + +Steps. + +- **Identify candidate events.** Events whose volume is below 10 per week. Events not referenced in any active dashboard or query in the last 90 days. Events that are duplicate or near-duplicate of other events. +- **Identify candidate cohorts and saved queries.** Items not used in the last 90 days. Items whose source data is now stale. +- **Identify candidate dashboards.** Already covered in step 3; gather candidates here. +- **Soft deprecation.** Tag items as deprecated; remove from default views. Wait 30 days. If anyone notices, reverse the deprecation; if nobody notices, hard delete. +- **Communicate.** Post the deprecation list to the data channel. Anyone with a use case has 14 days to push back. +- **Action items.** Soft deprecate. Wait. Hard delete on the next audit if no objections. + +Cadence. Quarterly. Hard deletion happens at the next audit, not the same one. + +--- + +## The audit deliverable + +Each quarterly audit produces a written report with five sections matching the steps above. The report includes. + +- **What changed since the last audit.** Events added, removed, renamed. Schema migrations completed. +- **Drift identified.** Events firing without schema entries. Property type mismatches. Volume anomalies. +- **Decisions made.** What was fixed, what was deprecated, what was deferred. +- **Open items.** Drift not yet resolved. Pending decisions. Owners reassigned but not yet confirmed. +- **Forward planning.** Schema changes anticipated next quarter. Dashboards likely to be migrated. Events likely to be deprecated. + +The report goes to the data team and the eng leads. It does not need to go to the entire company; the value is in the discipline of writing it. + +--- + +## When to skip an audit + +Never. The cost of skipping a quarter compounds. The team that audits twice a year ends up doing 3x the work each audit; the team that audits quarterly maintains a steady state. + +The exception. A team in a 30-day sprint to launch a major product version may defer one audit by 4 to 6 weeks. After that, the audit is overdue and the discipline is at risk. + +--- + +## What the audit is not + +Three things to avoid. + +- **Not a witch hunt.** The audit identifies drift, not blame. Many drift items are produced by good-faith engineering decisions that did not include the analytics-debt cost. +- **Not perfectionism.** Some drift is acceptable. Aim for 95% clean, not 100%. Spending the audit cycle chasing the last 5% leaves real problems unaddressed. +- **Not silent.** The audit produces a deliverable. Without the deliverable, the audit happened in someone's head; it does not transfer to the next quarter or the next team. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md b/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md new file mode 100644 index 0000000..c4572a7 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md @@ -0,0 +1,125 @@ +# Naming convention reference + +A complete style guide. Pick one convention; enforce it via CI lint. + +--- + +## The canonical conventions + +**snake_case** for events and properties. `user_signed_up`, `cart_value`, `trial_day`. + +**Past tense, action-oriented** for events. `checkout_completed`, not `complete_checkout` or `completing_checkout`. + +**Object-action format** for events. Noun then verb. `video_played`, `form_submitted`, `email_opened`. + +**Boolean prefix** for boolean properties. `is_`, `has_`, `can_`. `is_admin`, `has_trial`, `can_invite`. + +**Counting suffix** for count properties. `_count` or `_total`. `seat_count`, `total_purchases`, `signup_count`. + +**Money in smallest unit** with currency named. `price_cents` not `price` (and currency on `currency` property). + +**Timestamp suffix** for date-time properties. `_at` for absolute timestamps. `created_at`, `last_active_at`. `_s` or `_ms` for durations. `time_since_signup_s`. + +**Period suffix** for relative-time properties. `_days`, `_weeks`. `inactive_days_count`, `trial_length_days`. + +--- + +## Do and don't + +| Don't | Do | Why | +|---|---|---| +| `Sign Up Completed` | `signup_completed` | snake_case, no spaces. URL-safe. | +| `userSignedUp` | `user_signed_up` | snake_case wins by default; consistent across the platform. | +| `signup` (event) | `user_signed_up` | Past tense, object-action. Reads as "this happened." | +| `complete_checkout` | `checkout_completed` | Past tense for events. | +| `completing_checkout` | `checkout_completed` | Past tense, not progressive. | +| `Sign Up` | `signup` or `signed_up` | Pick one form for the same concept. Document it. | +| `price: "$19.99"` | `price_cents: 1999` plus `currency: "USD"` | Money in smallest unit. Currency separate. | +| `quantity: "5"` | `quantity: 5` | Numbers as numbers, not strings. | +| `is_premium: "yes"` | `is_premium: true` | Booleans as booleans. | +| `viewed: 1` | `is_viewed: true` | If it is yes/no, it is boolean, not 0/1. | +| `created: "5/5/2026"` | `created_at: "2026-05-05T14:30:00Z"` | ISO 8601, always. UTC. | +| `tags: "a,b,c"` | `tag_list: ["a", "b", "c"]` | Arrays for bounded lists, not delimiter-strings. | +| `signup_source` (one event) plus `source` (another event) | `signup_source` plus `referral_source` | Disambiguate when the same name means different things. | +| `User Signed Up` (event), `signupCompleted` (event), `SIGN_UP` (event) | `user_signed_up` (event), `signup_completed` (event) | Pick one casing, stick to it. | +| `mailchimp_email_opened` | `email_opened` plus `provider: "mailchimp"` property | Brand-neutral event names; vendor as a property. | +| `feature_x_clicked` | `feature_x_used` | Track usage, not button clicks. UI events are noise. | + +--- + +## Boolean property prefixes + +The prefix should make the property read as a yes-or-no question. + +- `is_admin` reads as "is admin?" Yes or no. +- `has_trial` reads as "has trial?" Yes or no. +- `can_invite` reads as "can invite?" Yes or no. +- `should_notify` reads as "should notify?" Yes or no. + +What NOT to do. + +- `admin: true`. Reads as "admin is true." Awkward in queries. +- `premium: 1`. Reads as a count, not a yes-or-no. +- `trial: "yes"`. String, not boolean. + +--- + +## Time, date, and duration suffixes + +| Suffix | Meaning | Example | +|---|---|---| +| `_at` | Absolute timestamp (ISO 8601 UTC) | `created_at`, `last_active_at`, `event_timestamp` | +| `_s` | Duration in seconds | `time_in_step_s`, `session_duration_s` | +| `_ms` | Duration in milliseconds | `response_time_ms` | +| `_days` | Duration in days (integer) | `inactive_days_count`, `trial_length_days` | +| `_weeks` | Duration in weeks (integer) | `weeks_since_signup` | +| `_months` | Duration in months (integer) | `months_active` | + +Mixing units across the schema produces bugs. Pick one unit per concept and document it. + +--- + +## Money + +Two rules. + +1. **Smallest unit, integer.** `price_cents`, `mrr_cents`, `total_revenue_cents`. Float arithmetic on money produces rounding errors. +2. **Currency named separately.** `currency: "USD"`. Do not assume USD; international users break the assumption. + +When the smallest unit varies (yen has no decimals; bitcoin has 8), pick a precision and document it. The integer math discipline still applies. + +--- + +## Identifiers + +Three identifier patterns. + +- **Stable IDs** are immutable. `user_id`, `account_id`, `product_id`. Use UUIDs or a system-generated identifier. +- **Human-readable names** are mutable. `product_name`, `account_name`. Useful for reporting; never use as a join key. +- **Display IDs** are user-visible. `invoice_number`, `order_number`. Often distinct from the database primary key. + +Always include a stable ID in event payloads. Optionally include the human-readable name for reporting convenience. + +--- + +## What NOT to encode in event names + +Three categories of detail belong on properties, not in event names. + +1. **State or status.** Not `user_active`, `user_inactive`. Use `user_signed_in` (event) plus `status` (user property). +2. **Variant or treatment.** Not `signup_variant_a`. Use `user_signed_up` (event) plus `experiment_variant` (property). +3. **Source or channel.** Not `signup_from_facebook`. Use `user_signed_up` (event) plus `acquisition_channel: "facebook"` (property). + +The principle. Event names answer "what happened?" Properties answer "with what context?" + +--- + +## Enforcement + +A naming convention without enforcement decays. Two patterns. + +**CI lint.** A schema definition (TypeScript interface, JSON Schema) plus a CI step that rejects events whose payload does not match. The lint catches new violations before they hit production. + +**Code review checklist.** PRs that add or modify events include a snippet showing the event name, properties, and types. The reviewer compares against the naming convention reference and the existing taxonomy. + +Without enforcement, the convention becomes documentation that nobody reads. With enforcement, it becomes a constraint that the codebase respects. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md b/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md new file mode 100644 index 0000000..979ffe8 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md @@ -0,0 +1,159 @@ +# North Star metric selection + +Rules for picking a North Star metric (NSM), examples by product type, anti-patterns, and migration patterns when changing NSM. + +The principle. The NSM is the single number the team optimizes against. Picking the wrong number focuses the team on the wrong work for as long as the team uses it. + +--- + +## NSM selection rules + +A trustworthy NSM passes four tests. + +1. **Reflects user value, not company value alone.** Revenue is company value; the NSM should track an action that delivers user value. Revenue can be the trailing measure; the NSM is the leading driver. +2. **Captures the core action that, if it grows, the business grows.** The NSM should be cause-correlated with revenue growth, retention, and any other business goal. If you double the NSM and the business does not improve, the NSM is wrong. +3. **Measurable consistently across time.** The definition should not drift. If the NSM definition changes every quarter, year-over-year comparison is impossible. +4. **Hard to game.** The team should not be able to grow the NSM via shortcuts that do not deliver user value. A gameable NSM produces local maxima that the team optimizes toward at the expense of the actual mission. + +--- + +## Examples by product type + +### Engagement-driven products + +The product creates ongoing value through repeated use. + +| Product | NSM | Why it works | +|---|---|---| +| Slack | Messages sent in workspaces of 3+ active users per week | Captures recurring value; harder to game than DAU; size threshold filters out trial-only users. | +| Figma | Weekly active editors | The action that delivers value (creating in Figma); active editors filters out viewers who do not get full product value. | +| Notion | Weekly content blocks created per workspace | Captures the core verb (creating); per-workspace normalizes for team size variance. | +| Linear | Weekly issues created per workspace | The product use case is project tracking; issues created is the load-bearing action. | + +### Transaction-driven products + +The product makes money on each transaction. + +| Product | NSM | Why it works | +|---|---|---| +| Airbnb | Nights booked (not bookings) | Nights captures the value delivered to hosts and guests; bookings count is gameable via short stays. | +| Uber | Rides completed (not requests) | Completion includes the driver-side fulfillment; requests alone misses the supply-side metric. | +| Etsy | GMV per active buyer | GMV per buyer is more stable than total GMV; it tracks user value rather than top-line growth alone. | + +### Conversion-driven products (SaaS subscription) + +The product is sold via subscription; the NSM tracks recurring engagement that drives renewal. + +| Product | NSM | Why it works | +|---|---|---| +| HubSpot | Activated workspaces (defined as workspaces using 3+ products) | Multi-product use is the activation signal that drives expansion revenue. | +| Stripe (developer-side) | Production payments processed per merchant per week | Captures the core transaction; per-merchant per-week filters for active integrations. | +| Calendly | Meetings booked via Calendly per user per week | The exact value delivered (meetings booked) and the recurring cadence. | + +### Content-driven products (media, publishing) + +The product delivers value through content consumption. + +| Product | NSM | Why it works | +|---|---|---| +| Spotify | Hours listened per active user | Hours captures depth of engagement; per active user normalizes for catalog growth. | +| YouTube (creator-side) | Watch time per video per audience cohort | Watch time is the core metric that drives ads and creator earnings. | +| Substack (writer-side) | Paid subscribers added per month | The action that converts to revenue; not just total subscribers (which is lagging). | + +--- + +## Anti-patterns + +Six NSMs that consistently produce the wrong incentives. + +### Bad NSM 1: signups + +Captures top-of-funnel volume, not value. A team optimizing for signups loosens activation criteria and chases low-quality acquisition channels. The NSM grows; the business does not. + +### Bad NSM 2: revenue + +Lagging, not action-oriented. The team can optimize against revenue only by changing pricing or sales tactics. Revenue is the trailing outcome; the NSM should be the leading action that produces revenue. + +### Bad NSM 3: DAU (daily active users) + +Useful for engagement-driven products with a daily cadence. Misleading for products with a longer cadence (weekly, monthly). DAU on a B2B SaaS often shows an unhealthy daily ritual the product does not actually need. + +### Bad NSM 4: page views or sessions + +Captures traffic, not value. A team optimizing for page views or sessions loosens content quality and adds engagement loops that do not deliver user value. + +### Bad NSM 5: feature usage + +The team optimizes for "feature X used" by promoting feature X aggressively. The feature usage grows; the underlying user value may not. NSM should capture cross-cutting value, not feature-specific use. + +### Bad NSM 6: reviews or NPS + +Captures sentiment, not value. NPS is useful as a health metric but a poor NSM because it is heavily influenced by survey design and customer-service interactions, neither of which the product team controls directly. + +--- + +## Supporting metrics framework + +The NSM does not stand alone. Around it lives a framework of input metrics and health metrics. + +### One NSM + +The single number the team optimizes against. + +### Three to five input metrics + +The metrics that drive the NSM. If the input metrics improve, the NSM should follow. + +For "weekly active editors" (Figma's NSM): +- Signups per week (the top of the funnel) +- Signup-to-active conversion rate (the activation step) +- Week-over-week active retention (the repeat-use step) + +For "messages sent in workspaces of 3+ active users per week" (Slack's NSM): +- Workspaces created per week +- Workspaces reaching 3+ active members +- Messages per active workspace per week + +The team's roadmap should map every initiative to one or more input metrics. + +### Five to ten health metrics + +Metrics that warn of problems. They should not regress while the NSM grows. + +- Monthly churn rate +- Account-level concentration (is growth coming from one big customer?) +- Support ticket volume per active user +- Latency or error rate +- Activation rate (signup-to-NSM-action) + +If any health metric regresses while the NSM grows, the team should investigate before declaring success. + +--- + +## Migration patterns when changing NSM + +The NSM should change rarely. When it does, the migration is high-risk. + +### Pattern 1: phased migration + +Run both NSMs in parallel for a quarter. Track team behavior; document where the new NSM produces different incentives. Decide based on real evidence, not speculation. + +### Pattern 2: shadow mode first + +The new NSM is tracked privately by the data team. The team continues to optimize against the old NSM. After 90 days, the data team reports on the divergence. Public switch happens only if the new NSM clearly aligns better with business outcomes. + +### Pattern 3: replace plus reinforce + +The new NSM replaces the old. The old metric becomes a health metric (still tracked, no longer the primary target). Over the next 6 months, ensure the old metric does not regress while the new NSM grows. + +--- + +## When to refuse to change the NSM + +Three signs that a proposed NSM change is wrong. + +1. **The change is reactive to a single quarter's bad numbers.** "Our NSM went down so we should change the NSM" is not a reason to change the NSM. +2. **The proposed new NSM is gameable.** A new NSM that the team can grow without delivering user value is worse than the existing NSM, even if the old one is imperfect. +3. **The change has no concrete decision the team will make differently.** If switching from old NSM to new NSM does not change which initiatives the team prioritizes, the change is theater. + +The NSM should be stable for years. Change it when the business model changes substantively or when the existing NSM is producing demonstrably wrong incentives. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md new file mode 100644 index 0000000..7c75d02 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md @@ -0,0 +1,168 @@ +# Property design patterns + +Event-level vs user-level properties, with type discipline and a worked example. + +The principle. Event-level properties describe a specific event. User-level properties describe a user across all events. Mixing them up creates payload bloat, schema drift, and reporting confusion. + +--- + +## Event-level vs user-level + +**Event-level properties** belong on the event payload. They describe the specific event, snapshot at the moment it fires. + +- `cart_value` on `checkout_completed` +- `item_count` on `checkout_completed` +- `payment_method` on `checkout_completed` +- `discount_code` on `checkout_completed` +- `referrer_source` on `user_signed_up` + +**User-level properties** belong on the user profile. They describe the user over time. Set them once; the analytics tool joins them onto every event the user fires. + +- `subscription_tier` +- `acquisition_channel` +- `lifetime_value` +- `account_role` +- `is_admin` +- `last_active_at` + +The trap. Putting user-level properties on every event payload. Three problems. + +1. **Payload bloat.** Every event carries the same `subscription_tier` value. Multiplied across millions of events, the storage and bandwidth cost is real. +2. **Schema drift when the value changes.** A user upgrades mid-session. Some events have `subscription_tier: free`; later events have `subscription_tier: pro`. Reporting becomes ambiguous about which value to use. +3. **Reporting confusion.** Analyst writes "WHERE subscription_tier = 'pro'" thinking they are filtering users. The query actually filters events, returning a different cohort. + +The fix. Set user-level properties on the user profile via the platform's identify/track-user API. Let the analytics tool perform the join. + +--- + +## Type discipline + +Property types matter. The analytics tool will accept any value, but the reporting breaks when types are inconsistent. + +**Strings** for enumerable values. + +- `status`, `tier`, `channel`, `region`, `category` +- Bounded sets. Document the allowed values in the schema. +- Wrong: storing numbers as strings. `quantity: "5"` breaks every numeric aggregation. + +**Numbers** for actual numbers. + +- `count`, `value`, `duration_s`, `score` +- Cents (or smallest unit) for money. Never floats. `price_cents: 1999`, not `price: 19.99`. +- Wrong: `trial_day: "day 7"`. Use `trial_day: 7`. + +**Booleans** for actual booleans. + +- `is_admin`, `has_trial`, `is_new_user` +- Two values: `true` and `false`. Nothing else. Not "yes"/"no", not 1/0, not strings. +- Prefix discipline: `is_`, `has_`, `can_`. Reading the property name should suggest a yes/no question. + +**Timestamps** in ISO 8601, always. + +- `created_at`, `last_active_at`, `event_timestamp` +- Format: `2026-05-05T14:30:00Z` (UTC, with the Z suffix). +- Wrong: Unix timestamps as strings, locale-specific formats, or any other variant. ISO 8601 across the entire schema. +- Suffix discipline: `_at` for timestamps, `_s` or `_ms` for durations. + +**Arrays** rarely. + +- An array property usually means you should split into multiple events with one item per event. +- Example: instead of `cart.items: [item_a, item_b, item_c]` on `checkout_completed`, fire one `item_purchased` event per item plus one `checkout_completed` event with the item count. +- Exception: small bounded arrays where the use case is clear (e.g., `tag_list: ["urgent", "billing"]`). + +--- + +## Worked example: product_viewed event + +A `product_viewed` event fires when a user views a product detail page in an e-commerce app. + +### Wrong design + +```json +{ + "event": "Product Viewed", + "user_id": "u_12345", + "product": "Premium Hoodie", + "price": "$49.99", + "category": "Apparel", + "user_subscription_tier": "Premium", + "user_lifetime_purchases": 8, + "user_acquisition_source": "Meta", + "is_premium_user": "true", + "viewed_at": "5/5/2026 2:30 PM", + "tags": "summer, hoodie, sale" +} +``` + +Problems. + +- Event name uses spaces and mixed case. `Product Viewed` should be `product_viewed`. +- `price` is a money string with currency symbol. Should be `price_cents: 4999`. +- User-level properties on the event: `user_subscription_tier`, `user_lifetime_purchases`, `user_acquisition_source`, `is_premium_user`. These belong on the user profile. +- `is_premium_user` is a string `"true"`, not a boolean. +- `viewed_at` is a locale-specific date format. Should be ISO 8601: `2026-05-05T14:30:00Z`. +- `tags` is a comma-delimited string. Should be an array of strings, or split into separate events. +- `product` is the human-readable name; lacks the stable identifier. Should include `product_id`. + +### Right design + +User profile (set via `identify`): + +```json +{ + "user_id": "u_12345", + "subscription_tier": "premium", + "lifetime_purchase_count": 8, + "acquisition_channel": "meta", + "is_premium": true, + "last_active_at": "2026-05-05T14:30:00Z" +} +``` + +Event payload (`product_viewed`): + +```json +{ + "event": "product_viewed", + "user_id": "u_12345", + "product_id": "p_premium_hoodie_v2", + "product_name": "Premium Hoodie", + "price_cents": 4999, + "currency": "USD", + "category": "apparel", + "tag_list": ["summer", "hoodie", "sale"], + "viewed_at": "2026-05-05T14:30:00Z" +} +``` + +Differences. + +- Event name is `snake_case`. +- Money in cents with currency named. +- User-level properties live on the user profile, not the event. The analytics tool joins them. +- Boolean is an actual boolean. +- Timestamp is ISO 8601 UTC. +- Tags are a bounded array (acceptable here because the use case is faceted filtering). +- Stable identifier (`product_id`) included alongside the human-readable name. + +--- + +## When to put a property on every event + +A small set of properties should appear on every event regardless of category. + +- `app_version` and `platform` (web, ios, android, desktop) +- `device_type` and `device_id` +- `session_id` +- `experiment_assignments` if the user is in active experiments + +These are technically event-level (they describe the context of the event) but they are required across every event for path analysis and segmentation. + +--- + +## Common property design mistakes + +- **Property names that are also event names.** `signup` as a property and `signup` as an event creates queries that depend on context. Disambiguate. +- **Free-text properties for things that should be enums.** "Where did you hear about us?" with free-text answers produces 47 unique values that map to 5 actual channels. Force the enum at collection time. +- **Storing PII in properties.** Email addresses, full names, phone numbers should not be in event properties. Use a hashed identifier and look up PII separately. +- **Reusing property names across events with different meanings.** `source` on `user_signed_up` means acquisition source. `source` on `email_opened` means email campaign source. Same name, different meaning, breaks queries. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md new file mode 100644 index 0000000..cd610a4 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md @@ -0,0 +1,167 @@ +# Schema versioning patterns + +Schema changes are inevitable. The discipline is distinguishing safe changes from breaking ones, then versioning the breaking ones. + +--- + +## Additive vs breaking changes + +**Additive changes** are safe. They preserve existing dashboards and queries. + +- New event. `feature_y_used` ships alongside existing events. Old dashboards continue to work. +- New property on an existing event. `checkout_completed` gains a `discount_code` property. Old dashboards ignore it; new dashboards can use it. +- New value in an enum. The `acquisition_channel` enum gains `"tiktok"`. Old dashboards may filter incorrectly if they hard-code values; usually low-risk. + +**Breaking changes** require migration. + +- Renamed event. `signup_complete` becomes `user_signed_up`. Every dashboard, query, and saved cohort referencing the old name breaks. +- Removed property. `cart_value_cents` is removed because it was redundant with `total_value_cents`. Queries referencing the removed property fail. +- Changed property type. `price` was a string; now it is a number. Existing queries cast or compare differently. +- Narrowed enum. `acquisition_channel` previously had `"organic"` and `"paid"`; the new schema removes `"organic"` and replaces it with `"organic_search"` and `"organic_social"`. Old queries break. +- Changed semantics. The same event name now fires under different conditions. The dashboard reading "weekly active users" silently gets a different number. + +The rule. If old code or old queries continue to work after the change, it is additive. Otherwise, it is breaking. + +--- + +## The `_v2` suffix pattern + +Versioning in the event name makes the change visible at every layer. + +``` +checkout_completed <- v1, fires alongside v2 during transition +checkout_completed_v2 <- new semantics, new schema +``` + +The transition. + +1. **Phase 1: ship v2 alongside v1.** Both events fire. Dashboards continue to read v1. New queries can use v2. +2. **Phase 2: migrate dashboards.** Update every saved query, dashboard tile, and downstream consumer to read v2. Document each migration. +3. **Phase 3: deprecate v1.** Stop firing v1. Mark it deprecated in the schema. Remove from event tracking instrumentation. +4. **Phase 4: cleanup.** Six months after deprecation, remove v1 from any historical reference documentation. Existing v1 data in the warehouse stays for historical analysis but is not used in current dashboards. + +Typical transition window. 90 days from v2 ship to v1 deprecation. Longer if the team is small or the dashboard inventory is large. + +--- + +## The data contract idea + +The canonical schema lives in code, not in the analytics tool. + +### TypeScript interface + +```typescript +// schema/events.ts + +export interface CheckoutCompletedEvent { + event: "checkout_completed"; + user_id: string; + account_id: string; + cart_value_cents: number; + currency: string; + item_count: number; + payment_method: "card" | "paypal" | "apple_pay" | "google_pay"; + discount_code?: string; + event_timestamp: string; // ISO 8601 UTC +} + +export interface UserSignedUpEvent { + event: "user_signed_up"; + user_id: string; + account_id: string; + signup_source: "homepage" | "pricing_page" | "blog" | "invite" | "other"; + referrer_source: string | null; + event_timestamp: string; +} + +export type AnalyticsEvent = + | CheckoutCompletedEvent + | UserSignedUpEvent; + // ... etc. +``` + +The interface is the contract. TypeScript catches type mismatches at compile time. The CI pipeline runs the type check. + +### JSON Schema + +For non-TypeScript projects, JSON Schema serves the same role. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "checkout_completed", + "type": "object", + "required": ["event", "user_id", "account_id", "cart_value_cents", "currency", "item_count", "payment_method", "event_timestamp"], + "properties": { + "event": { "const": "checkout_completed" }, + "user_id": { "type": "string" }, + "account_id": { "type": "string" }, + "cart_value_cents": { "type": "integer", "minimum": 0 }, + "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, + "item_count": { "type": "integer", "minimum": 1 }, + "payment_method": { "enum": ["card", "paypal", "apple_pay", "google_pay"] }, + "discount_code": { "type": "string" }, + "event_timestamp": { "type": "string", "format": "date-time" } + } +} +``` + +A CI step validates events against the schema before they ship. + +--- + +## CI lint patterns + +Three lint rules catch most schema drift. + +1. **Type validation.** Every event payload validates against its declared type. Failed validations fail the build. +2. **Naming convention check.** Event names match snake_case. Property names match snake_case. Boolean properties have `is_`, `has_`, or `can_` prefix. +3. **Forbidden-event check.** Removed or deprecated events do not appear in the codebase. The deploy that adds a deprecated event back fails. + +Implementation. A pre-commit hook plus a GitHub Actions workflow plus a runtime sampling check (random 1% of events validated against the schema in production; failures alert). + +--- + +## Migration patterns for breaking changes + +Three common migration patterns. + +### Pattern 1: rename + +The event name changes. The semantics are the same. + +1. Ship v2 with the new name; old name continues to fire. +2. Migrate dashboards, queries, saved cohorts. +3. Deprecate v1. + +### Pattern 2: split + +One event splits into two or more events with narrower meanings. + +1. Ship the new events; the old event continues to fire alongside. +2. Update tracking code to fire the appropriate new event instead of the old one. +3. Migrate dashboards. +4. Deprecate the old event. + +Example. `subscription_changed` splits into `subscription_upgraded` and `subscription_downgraded`. Both new events provide more analytical power than the old single event. + +### Pattern 3: merge + +Two events merge into one event with a discriminating property. + +1. Ship the new event with the discriminating property. +2. Update tracking code to fire the new event with the appropriate property value. +3. Migrate dashboards (often: queries that filtered on event name now filter on property value). +4. Deprecate the old events. + +Example. `signup_via_facebook` and `signup_via_google` merge into `user_signed_up` with `auth_method: "facebook" | "google"`. + +--- + +## Common schema versioning mistakes + +- **Renaming events without versioning.** The dashboards break overnight; the team blames the analytics tool. +- **Skipping the transition period.** v2 ships and v1 stops firing the same day. Historical analysis of v1 data is fine, but in-flight queries break. +- **Versioning everything pre-emptively.** `event_v3_v2` is overkill. Version when semantics change, not at every iteration. +- **Letting the analytics tool be the schema source of truth.** The tool's "events you have ever fired" list is a graveyard, not a contract. Maintain the schema in code; export to the tool. +- **No CI enforcement.** The discipline becomes an etiquette that decays as the team grows. Enforcement is the only thing that scales. diff --git a/dist/pi/.agents/skills/product-configurator-design/SKILL.md b/dist/pi/.agents/skills/product-configurator-design/SKILL.md new file mode 100644 index 0000000..593b80c --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/SKILL.md @@ -0,0 +1,289 @@ +--- +name: product-configurator-design +description: "Designing build-your-own product configurators (Tesla-style, custom-pricing, plan-builders) with constraint logic, real-time pricing, validation, and save-and-share mechanics. Honest about infinite-options (decision paralysis), canned-bundles-only (no real customization), and guided-configuration (smart defaults plus meaningful constraints plus escape hatches) patterns. Triggers on configurator design, build-your-own, custom configuration, plan builder, product customizer, configuration tool. Also triggers when users abandon mid-configuration, when configurator conversion is poor, or when a configurator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive product configurators. Distinguishes infinite-options (decision paralysis from too many options) from canned-bundles-only (no real customization) from guided-configuration (smart defaults plus meaningful constraints plus escape hatches)" +display_order: 12 +--- + +# Product Configurator Design + +A senior product marketing director's playbook for designing build-your-own product configurators. Tesla-style vehicle configurators, custom-pricing builders, plan-builders, product customizers. Constraint logic, real-time pricing, validation, save-and-share mechanics. The discipline of building a configurator that produces configurations users actually commit to. + +Most configurators fail in one of two ways. They expose every parameter at full granularity (47 toggles, 12 sliders) and produce decision paralysis; users abandon halfway through. Or they pretend to be configurators but are actually three pre-built bundles labeled "Custom"; the configurator framing was marketing while the product is bundles. + +The configurators that work do something different. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations and surface why; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Users feel guided rather than overwhelmed. + +The voice is the senior product marketing director who has watched configurators double conversion when redesigned with smart defaults and watched them collapse when "more options" were added without constraint logic. Practical, opinionated about the constraints that protect users from themselves, willing to call out when canned bundles are the right answer. + +When to use this skill: scoping a build-your-own configurator for the first time, auditing a configurator with high abandonment, designing the constraint logic that prevents invalid combinations, or deciding which parameters earn exposure vs which should default. + +--- + +## What this skill covers + +This skill spans build-your-own product configurators. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number from inputs. This skill builds a product configuration with multiple decisions. +- `comparison-tool-design` is comparing known options. This skill builds a custom option. +- `multi-step-form-design` is data capture. This skill is configuration design. +- **`product-configurator-design` (this skill)** is constraint logic, real-time pricing, validation, save-and-share, and configurator-to-cart handoff. +- `pm-spec-writing` is the spec for engineers building the configurator. + +The audience: product marketers, growth marketers, ecommerce teams, B2B teams shipping configurable products, agencies running configurator work for clients. + +Out of scope: calculator design (covered by `calculator-design`); comparison tools (covered by `comparison-tool-design`); the engineering implementation; specific configurator-platform configurations (those stay implementation-side). + +--- + +## The configurator decision: when configurators earn investment vs when bundles suffice + +Before designing the configurator, decide whether a configurator is the right answer. + +**Configurators earn investment when:** + +- The product has genuinely customizable parameters that affect outcome and cost. +- The audience values customization beyond what bundles offer. +- The team can support the configuration logic (validation, pricing, fulfillment). +- The combinatorial space is meaningful but constrained (not literally infinite). + +**Configurators do NOT earn investment when:** + +- The product is essentially bundles. Calling them "configurations" is marketing, not product. +- The audience does not value customization. Some audiences want to choose from curated options, not build. +- The combinatorial space is so large that no audience can navigate it. +- Customization produces invalid combinations the team cannot prevent. +- A simpler comparison or selection tool would serve. + +The decision is not "should we have a configurator"; it is "is the configurator the right tool for this product and audience." + +Detail in [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md). + +--- + +## Infinite-options vs canned-bundles-only vs guided-configuration + +The keystone framing. + +**Infinite-options.** Every parameter exposed at full granularity. 47 toggle switches and 12 sliders. Decision paralysis. Users abandon halfway through; few complete a configuration. Cost: design effort produces a configurator nobody completes; conversion suffers. + +**Canned-bundles-only.** "Configurator" that is actually three pre-built bundles labeled Basic/Pro/Enterprise. No real customization. The configurator framing was marketing; the product is bundles. Cost: audience that came expecting customization feels deceived; conversion suffers because expectations did not match reality. + +**Guided-configuration.** Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Cost: design effort upfront is significant; conversion typically improves meaningfully because users complete configurations they commit to. + +The litmus test. Hand the configurator to a stranger in the target audience. Do they reach a configuration they would actually buy in under 5 minutes without expert help? If yes, guided-configuration. If they paralyze at the options, infinite-options. If they only see bundles, canned-bundles-only. + +--- + +## Default-configuration design + +The starting point. + +**The principle.** The configurator opens with a sensible default configuration. The user adjusts from there. + +**Default selection.** + +- The configuration most audiences would choose. +- Reflects audience research (sales-call mining, prior configurations). +- Inferable from referrer, query, or stated preference. + +**Default presentation.** + +- Default visible immediately; user sees a complete configuration with price. +- Adjust controls obvious; user knows what is changeable. +- Reset-to-default available; users who experiment can return. + +**The blank-canvas trap.** Configurator opens empty; user must build from scratch. Decision paralysis at the start. + +**The cure.** Default-heavy. The user adjusts; never builds from zero. + +Detail in [`references/default-configuration-design.md`](references/default-configuration-design.md). + +--- + +## Constraint logic + +Preventing invalid combinations; surfacing why. + +**The principle.** The configurator should not let users build invalid configurations (combinations that cannot ship, cannot be priced, or do not work together). When constraints engage, the configurator surfaces why. + +**Constraint patterns.** + +- **Hard constraints.** "Option A and Option B are incompatible." Configurator prevents the combination; explains why. +- **Soft constraints.** "Combining Option A with Option C is unusual but possible." Configurator allows; warns. +- **Implication constraints.** "Selecting Option A requires Option D." Configurator auto-includes D; explains. +- **Capacity constraints.** "This configuration exceeds shipping capacity." Configurator caps; explains. + +**Constraint communication.** + +- Why this constraint engaged. +- What user can do (different option, contact for custom). +- No friction-only blocking; always offer a path. + +**The over-constrained trap.** Too many constraints; user feels boxed in. + +**The under-constrained trap.** User builds configuration that fails at checkout or fulfillment. + +Detail in [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md). + +--- + +## Real-time pricing and impact display + +Pricing that responds to choices. + +**The principle.** Price updates as the user adjusts. The user sees the cost impact of each choice immediately. + +**Strong pricing display.** + +- Total price prominent and updated in real time. +- Per-choice impact visible ("Adds $X" or "Saves $X"). +- Breakdown available ("How is this priced"). +- Currency and locale appropriate. + +**Weak pricing display.** + +- Price hidden until the end. +- Per-choice impact invisible; user does not know what each option costs. +- Breakdown not available; total is opaque. + +**The price-shock trap.** User configures heavily; reaches checkout; sees a price they did not expect; abandons. + +**The cure.** Price visible throughout. No surprises at checkout. + +Detail in [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md). + +--- + +## Validation and error patterns + +When the configurator catches invalid input. + +**The principle.** Validation should be helpful, not punitive. + +**Validation patterns.** + +- **Inline validation.** Error appears next to the invalid choice. +- **Pre-emptive validation.** Constraint logic prevents the error from being possible. +- **Final validation.** Pre-checkout review surfaces any remaining issues. + +**Error communication.** + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +**The validation-strict trap.** Validation rejects valid edge-case inputs. + +**The validation-loose trap.** Configurator accepts inputs that fail downstream. + +Detail in [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md). + +--- + +## Save-and-share mechanics + +Configurations users return to or send to others. + +**The principle.** Configurators that serve real decision-making produce configurations users want to save and share. + +**Save patterns.** + +- **Email-link save.** User enters email; configuration link emailed. +- **Account-based save.** Logged-in users save automatically. +- **Anonymous-session save.** Browser-based persistence. + +**Share patterns.** + +- **Shareable URL.** Configuration encoded in URL; share via any channel. +- **Embed code.** Configuration embeddable on other sites or in proposals. +- **Email share.** Direct email-to-recipient with configuration. + +**Why save-and-share matters.** + +- Multi-decision purchases require deliberation. +- B2B configurations often need stakeholder review. +- Returning users continue rather than restart. + +Detail in [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md). + +--- + +## Configurator-to-cart handoff + +When the user commits. + +**The principle.** Handoff from configurator to cart should preserve the configuration entirely. + +**Handoff patterns.** + +- Configuration becomes the cart item. +- Cart shows the configuration summary. +- Edit-from-cart returns to configurator with state preserved. + +**The handoff failure.** Configuration partially preserved; cart shows a generic SKU; user cannot tell if their custom build is reflected. + +**The cure.** Handoff loop closed. Configuration visible in cart; price matches; edits possible. + +Detail in [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-configurator-failures.md`](references/common-configurator-failures.md). + +- "Users abandon halfway through configuration." Likely infinite-options pattern; too many decisions. +- "Configurator generates valid-looking configs that fail at fulfillment." Under-constrained; constraint logic missing. +- "Users complain about price surprises at checkout." Pricing not real-time or hidden until end. +- "Sales says many users contact for help configuring." Configurator too complex for audience; defaults wrong. +- "Users save configurations but do not return." Save mechanism works but follow-up missing. +- "Configurator works on desktop, breaks on mobile." Mobile UX broken. +- "Audience completes but conversion to purchase is low." Configurator works; commitment friction at handoff. +- "We added more options; abandonment climbed." Crossed the cognitive-load threshold. +- "Constraint engaged but user did not understand why." Communication broken; users feel arbitrarily blocked. + +--- + +## The framework: 12 considerations for configurator design + +When designing or auditing a configurator, walk these 12 considerations. + +1. **The configurator decision.** Is configurator the right tool, or do bundles serve? +2. **Guided-configuration, not infinite-options or canned-bundles-only.** Smart defaults plus meaningful constraints plus escape hatches. +3. **Default configuration sensible.** User adjusts from default; does not build from zero. +4. **Constraint logic prevents invalid combinations.** Hard, soft, implication, capacity constraints. +5. **Constraint communication clear.** Why constraint engaged; what user can do. +6. **Real-time pricing visible.** Price updates with choices; breakdown available. +7. **Validation helpful.** Inline; specific; offers paths. +8. **Save-and-share works.** Multi-session; shareable; B2B-friendly. +9. **Configurator-to-cart handoff preserves state.** Cart shows configuration. +10. **Mobile parity.** Configurator works on the devices the audience uses. +11. **Conversion as success metric.** Not just completion rate; downstream purchase. +12. **Maintenance discipline.** Configurations updated as product changes; quarterly audit. + +The output of the framework is a configurator that earns the configuration that ships, with constraint logic, pricing, and handoff working together to produce commitments users keep. + +--- + +## Reference files + +- [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md) - When configurators earn the build vs when bundles serve. +- [`references/default-configuration-design.md`](references/default-configuration-design.md) - The starting point. Default selection and presentation. +- [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md) - Hard, soft, implication, capacity constraints. Communication patterns. +- [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md) - Price updates with choices. Breakdown and impact display. +- [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md) - Helpful validation. Inline, pre-emptive, final. +- [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md) - Email-link, account, anonymous, shareable URL, embed. +- [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md) - Handoff that preserves configuration; cart visibility; edit-from-cart. +- [`references/configurator-anti-patterns.md`](references/configurator-anti-patterns.md) - The patterns that look like configurators but degrade conversion. +- [`references/common-configurator-failures.md`](references/common-configurator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: configurators earn investment when they earn the configuration that ships + +The configurators that work as compounding assets are the ones that produce configurations users commit to. Not 50-cell decision matrices. Not bundles dressed as configurators. Configurations the user built, priced, validated, saved, and bought. + +That is the bar. Below the bar are infinite-options (decision paralysis; users abandon) and canned-bundles-only (configurator framing without real customization; users feel deceived). Above the bar are guided-configuration tools where smart defaults, meaningful constraints, real-time pricing, validation, and save-and-share work together to produce commitments. + +The discipline is in the design choices. The decision to build a configurator at all. The default configuration that opens the experience. The constraint logic that protects users from invalid combinations. The pricing that updates with choices. The validation that helps without punishing. The save-and-share that supports multi-decision purchases. The cart handoff that preserves the configuration. The maintenance that keeps the configurator in sync with the product it represents. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md b/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md new file mode 100644 index 0000000..2e5c19c --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md @@ -0,0 +1,179 @@ +# Common configurator failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Users abandon halfway through configuration." + +**The diagnosis.** Likely infinite-options pattern; too many decisions. + +**The cure.** Smart defaults; reduce option count; escape hatches into deeper customization. + +--- + +## "Configurator generates valid-looking configs that fail at fulfillment." + +**The diagnosis.** Under-constrained; constraint logic missing. + +**The cure.** Add constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## "Users complain about price surprises at checkout." + +**The diagnosis.** Pricing not real-time or hidden until end. + +**The cure.** Real-time pricing throughout. Detail in `references/real-time-pricing-patterns.md`. + +--- + +## "Sales says many users contact for help configuring." + +**The diagnosis.** Configurator too complex for audience; defaults wrong. + +**The cure.** Audit defaults; reduce option exposure; consider canned bundles for simple cases. + +--- + +## "Users save configurations but do not return." + +**The diagnosis.** Save mechanism works but follow-up missing. + +**The cure.** Reminder email after save; nudge before configuration expires. + +--- + +## "Configurator works on desktop, breaks on mobile." + +**The diagnosis.** Mobile UX broken. + +**The cure.** Mobile-first design and testing. + +--- + +## "Audience completes but conversion to purchase is low." + +**The diagnosis.** Configurator works; commitment friction at handoff. + +**The cure.** Audit cart handoff; ensure configuration preserved; reduce checkout friction. + +--- + +## "We added more options; abandonment climbed." + +**The diagnosis.** Crossed cognitive-load threshold. + +**The cure.** Cut options; surface fewer; defer complexity behind escape hatches. + +--- + +## "Constraint engaged but user did not understand why." + +**The diagnosis.** Communication broken. + +**The cure.** Constraint copy specific; explains why; offers paths. + +--- + +## "Configurations frequently differ from cart." + +**The diagnosis.** Handoff broken. + +**The cure.** Test cart handoff. Configuration ID system; single pricing source. + +--- + +## "Sales says enterprise customers want full configurations sales-led." + +**The diagnosis.** Enterprise audience wants white-glove; configurator self-serve does not match expectation. + +**The cure.** Enterprise path: configurator surfaces "Talk to sales for custom" for above-threshold configurations. + +--- + +## "We A/B tested adding more options; conversion went down." + +**The diagnosis.** Crossed the threshold. + +**The cure.** More is not always better. Maintain option discipline. + +--- + +## "Returning users see different prices than they saved." + +**The diagnosis.** Pricing shifted; configurator silently updated. + +**The cure.** Honest about price changes on resume. + +--- + +## "Mobile configuration completion is half of desktop." + +**The diagnosis.** Mobile UX significantly worse. + +**The cure.** Mobile-first redesign; reduce option exposure on mobile. + +--- + +## "Validation rejects valid international inputs." + +**The diagnosis.** Validation too strict. + +**The cure.** Audit validation rules; allow international formats. + +--- + +## "Some configurations work; others fail post-checkout." + +**The diagnosis.** Constraint logic incomplete; some invalid combinations slip through. + +**The cure.** Audit constraints. Add missing rules. + +--- + +## "Configurator's average configuration is more expensive than baseline." + +**The diagnosis.** May not be a problem (real customization adds cost) or may be (default biased toward expensive). + +**The cure.** Audit defaults. Defaults should reflect typical use, not flatter revenue. + +--- + +## "Sales pipeline shrunk after configurator launch; people self-serve." + +**The diagnosis.** Configurator absorbed the audience that would have called. + +**The cure.** This may be intentional (cost reduction) or unintentional (loss of complex deals). Decide if the shift is desired. + +--- + +## "Configurator launched; analytics broke." + +**The diagnosis.** Instrumentation missed. + +**The cure.** Verify analytics post-launch. Per-step instrumentation for diagnostic. + +--- + +## The pattern across failures + +Most configurator failures fall into one of three patterns. + +**Pattern 1: Cognitive overload.** Infinite-options, too many decisions, no defaults. The fix is guided-configuration. + +**Pattern 2: Trust damage.** Hidden pricing, price drift, unclear constraints, lost state. The fix is transparency. + +**Pattern 3: Handoff failures.** Cart loses configuration; checkout disappears it. The fix is loop closure. + +The metric pattern: configurator failures often look fine on engagement. Signal is in completion rate, conversion to purchase, downstream order accuracy. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (cognitive overload, trust damage, handoff). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md new file mode 100644 index 0000000..d31b61b --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md @@ -0,0 +1,193 @@ +# Configurator anti-patterns + +The patterns that look like configurators but degrade conversion. Easy to ship; the cost shows up in completion rates, downstream conversion, and brand trust. + +--- + +## The infinite-options configurator + +The pattern. Every parameter exposed at full granularity. + +The signal. Decision paralysis; high abandonment. + +The cure. Smart defaults; meaningful constraints; escape hatches into deeper customization. + +--- + +## The canned-bundles-only configurator + +The pattern. Three pre-built bundles labeled "Custom." + +The signal. Audience expecting customization feels deceived. + +The cure. Real configuration logic; or honest bundle framing. + +--- + +## The blank-canvas configurator + +The pattern. Configurator opens empty; user must build from scratch. + +The signal. First-step abandonment. + +The cure. Default-heavy. Open with sensible default. + +--- + +## The hidden-pricing configurator + +The pattern. Price not visible until checkout. + +The signal. Users abandon at checkout when total surprises. + +The cure. Real-time pricing throughout. + +--- + +## The under-constrained configurator + +The pattern. User can build invalid configurations that fail downstream. + +The signal. Sales gets calls about failed orders. + +The cure. Constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## The over-constrained configurator + +The pattern. Too many constraints; user feels boxed in. + +The signal. User abandons; sales gets calls for "custom" configurations. + +The cure. Reduce constraints to genuine requirements; offer custom path for edge cases. + +--- + +## The unclear-constraint configurator + +The pattern. Constraint engages without explanation. + +The signal. Users confused; bounce rate climbs. + +The cure. Constraint communication. Why constraint engaged; what user can do. + +--- + +## The lose-state-on-error configurator + +The pattern. Validation engages; configuration resets. + +The signal. Users abandon at first error. + +The cure. Preserve state; errors local. + +--- + +## The mobile-broken configurator + +The pattern. Configurator works on desktop; breaks on mobile. + +The signal. Mobile completion much lower than desktop. + +The cure. Mobile-first design. + +--- + +## The lost-on-cart configurator + +The pattern. Cart shows generic SKU; configuration not visible. + +The signal. Users edit; configurator restarts; abandonment. + +The cure. Cart presentation preserves configuration. + +--- + +## The price-drift configurator + +The pattern. Configurator shows one price; cart shows another. + +The signal. Users feel deceived. + +The cure. Single source of truth for pricing. + +--- + +## The save-mechanism-broken configurator + +The pattern. User saves; recovery link broken; configuration lost. + +The signal. Users complain; abandonment increases on long configurations. + +The cure. Test save mechanism end-to-end. + +--- + +## The validation-strict configurator + +The pattern. Validation rejects valid edge-case inputs. + +The signal. Users with valid inputs cannot proceed. + +The cure. Audit validation; allow international, plus-aliased, non-Latin inputs. + +--- + +## The unmaintained configurator + +The pattern. Product changed; configurator did not. + +The signal. Configurator references deprecated options; pricing wrong. + +The cure. Quarterly maintenance; product changes trigger configurator updates. + +--- + +## The aggressive-pricing-anchoring configurator + +The pattern. Strikethrough prices that were never charged; "$X for a limited time" perpetually. + +The signal. Sophisticated audiences notice; trust collapses. + +The cure. Honest anchoring; real discounts only. + +--- + +## The orphan-configuration configurator + +The pattern. Configurations save; user returns; configuration valid but pricing changed silently. + +The signal. Users surprised at price difference. + +The cure. Honest about price changes on resume. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +**Audit questions per configurator.** + +- Is default sensible (anti-pattern check: blank-canvas)? +- Are constraints calibrated (anti-pattern check: over-constrained, under-constrained, unclear)? +- Is pricing visible and consistent (anti-pattern check: hidden-pricing, price-drift)? +- Does state preserve on error (anti-pattern check: lose-state-on-error)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Does cart preserve configuration (anti-pattern check: lost-on-cart)? +- Is validation calibrated (anti-pattern check: validation-strict)? +- Is configurator current (anti-pattern check: unmaintained)? +- Are saved configurations honest about price changes (anti-pattern check: orphan-configuration)? + +**The retire decision.** Configurators failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md new file mode 100644 index 0000000..60185a6 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md @@ -0,0 +1,129 @@ +# Configurator decision criteria + +When configurators earn the build vs when bundles serve. + +A configurator is meaningful work. Constraint logic, real-time pricing, validation, save-and-share, cart handoff, ongoing maintenance. The configurator earns this investment only when specific conditions are present. + +--- + +## When configurators earn the build + +Five conditions that, when present, make a configurator a strong investment. + +**The product has genuinely customizable parameters that affect outcome and cost.** Not just cosmetic options; real parameters that change what the user gets. + +**The audience values customization beyond what bundles offer.** Some audiences want choice; others prefer curated bundles. + +**The team can support the configuration logic.** Validation, pricing, fulfillment for variable configurations. + +**The combinatorial space is meaningful but constrained.** Not literally infinite; not so small that bundles would suffice. + +**The success metric is defined.** Configuration completion rate, configuration-to-purchase rate, average configuration price. + +When all five are present, a configurator is strong investment. When two or fewer are present, bundles often serve better. + +--- + +## When configurators do NOT earn the build + +Funnels where configurators add complexity without lift. + +**The product is essentially bundles.** Calling them configurations is marketing. + +**The audience prefers curated options.** Some audiences resent customization friction. + +**The combinatorial space is too large.** No audience can navigate. + +**Customization produces invalid combinations.** Team cannot prevent; users hit failures. + +**A simpler tool would serve.** Comparison, calculator, or selection tool. + +The honest assessment matters. Configurators are sometimes the wrong tool. + +--- + +## Configurators vs bundles + +When each fits. + +**Bundles strengths.** Simple; clear; no decision paralysis. Easy to maintain. + +**Bundles weaknesses.** Audiences that need customization underserved. + +**Configurators strengths.** Match real customer needs; capture revenue from edge cases. + +**Configurators weaknesses.** Build cost; complexity. + +**The combined approach.** Some products offer bundles AND a configurator for users who want custom. + +--- + +## The opportunity-cost frame + +Configurators are significant work. + +**Build cost.** Constraint logic, pricing engine, save-and-share, validation, cart integration. 60-200 engineering hours typical. + +**Maintenance cost.** Product changes trigger configurator updates. 4-12 hours per quarter. + +**Opportunity cost.** Better bundles, comparison tool, calculator. The configurator has to clear those alternatives. + +The decision frame. Configurators earn investment when they produce more revenue than bundle-only or alternative formats. + +--- + +## Decision worked example + +A B2B SaaS with seat-based + add-on pricing. + +**Conditions check.** + +- Genuinely customizable: yes (seats, add-ons, integrations). +- Audience values customization: yes; team size and add-ons vary. +- Team can support: yes. +- Combinatorial space: meaningful but constrained. +- Success metric: defined. + +**Decision.** Build the configurator. + +The decision was deliberate. + +--- + +## Decision worked example: when bundles serve + +A consumer SaaS with three plans. + +**Conditions check.** + +- Genuinely customizable: no; plans are bundles. +- Audience values customization: no; users pick plans. +- Combinatorial space: trivial. + +**Decision.** Bundles. No configurator needed. + +The decision was right-sized. + +--- + +## When to retire a configurator + +Configurators can become wrong over time. + +**Retire when:** + +- Conversion declined and refinements have not moved it. +- Most users default-and-purchase; customization unused. +- Product changed; configurator no longer matches. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions for configurators. The five against. Configurators vs bundles. Opportunity-cost frame. Decision worked examples. The retire decision. + +## Implementation choices that stay internal + +Specific configurator decisions for specific products. Capacity benchmarks. Tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md new file mode 100644 index 0000000..36bbf43 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md @@ -0,0 +1,159 @@ +# Configurator-to-cart handoff + +Handoff that preserves configuration; cart visibility; edit-from-cart. + +When the user commits, the handoff to cart determines whether the commitment sticks. Done well, handoff preserves the configuration; done poorly, the cart shows generic SKUs and the user feels their custom build was lost. + +--- + +## The preserve-the-build principle + +The configuration becomes the cart item. The cart shows the configuration. Editing returns to the configurator with state preserved. + +**The win.** User finishes configuration; clicks add to cart; cart shows the custom configuration with breakdown and price; user can edit, returning to configurator with all choices preserved. + +**The fail.** User finishes; clicks add to cart; cart shows "Custom Product - $X" with no detail. User cannot tell if their build is reflected. + +The discipline. Handoff loop closed. + +--- + +## Cart presentation + +How the configuration appears in cart. + +**Configuration summary.** Key choices listed (not all; not none). + +**Price breakdown.** Subtotal matches configurator's price. + +**Edit link.** Clear path back to configurator with state preserved. + +**Visual.** If configurator shows visual configuration, cart shows it too (or summary image). + +--- + +## Edit-from-cart + +When user wants to change. + +**Pattern.** Cart includes "Edit configuration" link. + +**Behavior.** + +- Click; return to configurator. +- All choices loaded. +- Adjust; commit; cart updates. + +**The lose-state-on-edit failure.** User clicks edit; configurator restarts; previous choices lost. + +The cure. State preserved through the handoff loop. + +--- + +## Multi-item handoff + +When the user configures multiple items. + +**Pattern.** Each configuration becomes a separate cart item with its own summary. + +**Edit each independently.** User can edit one without affecting others. + +--- + +## B2B configurator-to-quote + +When the configurator generates a quote rather than direct cart. + +**Pattern.** Configuration generates a quote; quote can be shared, approved, then converted to order. + +**Strengths.** B2B workflows often require approval. + +**The discipline.** Quote includes everything the configuration includes; conversion to order preserves. + +--- + +## Handoff to checkout + +After cart, checkout. + +**The principle.** Configuration details flow through checkout. Confirmation email reflects the configuration. + +**The drop-config-at-checkout failure.** Configuration disappears at checkout; user cannot verify. + +The cure. Configuration visible throughout the funnel. + +--- + +## Configuration ID + +The technical bridge. + +**Pattern.** Each configuration gets an ID. Cart, checkout, fulfillment all reference the ID. + +**Strengths.** Stable reference. + +**Weaknesses.** Requires backend infrastructure. + +--- + +## Pricing consistency + +Prices match across configurator, cart, checkout. + +**The principle.** No price drift between stages. + +**The drift failure.** Configurator shows $X; cart shows $Y; user feels deceived. + +**Causes.** Caching, currency conversion, tax estimation, discount expiration. + +**The cure.** Single source of truth for pricing; all stages query. + +--- + +## Save-and-share-to-cart + +When users return from saved configurations. + +**Pattern.** Saved configuration link opens configurator with state; user can add to cart from there. + +**The discipline.** Save mechanism integrates with cart workflow. + +--- + +## Mobile cart handoff + +On mobile, the handoff transition matters. + +**Considerations.** + +- Cart visible without horizontal scroll. +- Edit returns work on mobile. +- Configuration summary readable. + +--- + +## Common handoff failures + +**Cart shows generic SKU.** User cannot verify configuration. + +**Edit restarts configurator.** Previous choices lost. + +**Pricing drifts between stages.** User confused. + +**Configuration disappears at checkout.** Cannot verify. + +**Multi-item handoff broken.** Configurations conflict in cart. + +**B2B quote misses details.** Quote does not match configuration. + +**Confirmation email lacks configuration.** User cannot verify post-purchase. + +--- + +## Methodology-level choices that stay in the public skill + +The preserve-the-build principle. Cart presentation. Edit-from-cart. Multi-item handoff. B2B configurator-to-quote. Handoff to checkout. Configuration ID. Pricing consistency. Save-and-share-to-cart. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific cart implementations for specific configurators. Specific configuration-ID systems. Specific backend integrations. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md new file mode 100644 index 0000000..809e52b --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md @@ -0,0 +1,173 @@ +# Constraint logic patterns + +Hard, soft, implication, capacity constraints. Communication patterns. + +Constraints prevent invalid configurations. Done well, they protect users from errors and surface why; done poorly, they feel arbitrary or fail to prevent invalid configurations. + +--- + +## The protect-and-explain principle + +Constraints should prevent invalid configurations and explain why when they engage. + +**The win.** User selects Option A. System recognizes A is incompatible with currently-selected Option B. Inline message: "Option A and Option B are incompatible. Choose A or B." User adjusts; understands. + +**The fail.** User builds configuration. Submits. Backend rejects. User confused; no path forward. + +The discipline. Constraints engage at choice-time; explain why; offer paths. + +--- + +## Pattern A: Hard constraints + +Combinations that cannot exist. + +**How it works.** + +- Two options incompatible; configurator prevents both selected. +- User selects A; B becomes unavailable (greyed; with explanation). +- Or vice versa. + +**Strengths.** Prevents invalid configurations. + +**Weaknesses.** Can frustrate users who do not understand the constraint. + +**When to use.** Genuinely incompatible options. + +--- + +## Pattern B: Soft constraints + +Combinations that are unusual but possible. + +**How it works.** + +- User selects unusual combination. +- System warns: "This combination is unusual. Most teams choose [alternative]." +- User can proceed. + +**Strengths.** Respects user agency; provides guidance. + +**Weaknesses.** Some users will ignore warning; downstream issues. + +**When to use.** Combinations that work but are uncommon. + +--- + +## Pattern C: Implication constraints + +When choosing one option requires another. + +**How it works.** + +- User selects A. +- System auto-selects required B (or surfaces it for selection). +- Explains: "Selecting A requires B because [reason]." + +**Strengths.** Prevents missing-dependency errors. + +**Weaknesses.** Implication chains can grow complex. + +**When to use.** When dependencies are clear and predictable. + +--- + +## Pattern D: Capacity constraints + +Configuration exceeds product or fulfillment capacity. + +**How it works.** + +- User configures heavily; reaches capacity ceiling. +- System caps; explains: "Max [X] supported per configuration." +- Offers contact for custom. + +**Strengths.** Prevents impossible configurations. + +**Weaknesses.** Can frustrate enterprise audiences; offer contact for custom. + +**When to use.** Hard product limits. + +--- + +## Pattern E: Combinatorial constraints + +When multiple choices interact in complex ways. + +**How it works.** + +- Configurator evaluates the full configuration after each change. +- Constraints engage based on combinations, not individual options. +- Surface conflicts as they emerge. + +**Strengths.** Handles complex products. + +**Weaknesses.** Maintenance complexity. + +**When to use.** Products with genuine combinatorial constraints. + +--- + +## Constraint communication + +How constraints surface. + +**Inline.** Message next to the constrained choice. + +**Modal.** Full-screen explanation for major constraints. + +**Toast.** Brief notification for minor. + +**The discipline.** Match intensity to constraint importance. + +--- + +## Constraint copy + +What the message says. + +**Strong copy.** "Option A and Option B are incompatible because [specific reason]. Choose A or B." + +**Weak copy.** "Invalid configuration." + +The discipline. Specific; explanatory; offers paths. + +--- + +## Constraint maintenance + +Constraints decay. + +**What decays.** + +- Constraints from old product variants. +- Constraints inherited from deprecated options. +- New options not yet constrained. + +**Maintenance cadence.** Quarterly review with product changes. + +--- + +## Common constraint failures + +**Over-constrained.** Too many constraints; user feels boxed in. + +**Under-constrained.** User builds invalid configuration; fails downstream. + +**Constraint without explanation.** User confused by arbitrary blocking. + +**Stale constraints.** Inherited from old product. + +**Constraint surface inappropriate.** Modal for minor; toast for major. + +**No path offered.** Constraint blocks; user has no alternative. + +--- + +## Methodology-level choices that stay in the public skill + +The protect-and-explain principle. Patterns A through E. Constraint communication. Constraint copy. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific constraints for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md b/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md new file mode 100644 index 0000000..aee99bf --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md @@ -0,0 +1,109 @@ +# Default-configuration design + +The starting point. Default selection and presentation. + +The configurator opens with a default configuration. Done well, the default makes the user feel guided rather than overwhelmed; done poorly, the user faces a blank canvas and abandons. + +--- + +## The default-heavy principle + +Configurators should open with a sensible default, not a blank canvas. + +**The win.** User opens the configurator; sees a complete configuration with price; can adjust from there. + +**The fail.** User opens the configurator; sees empty fields and 0 fields completed. Decision paralysis. + +The discipline. Default-heavy; user adjusts from default; never builds from zero. + +--- + +## Default selection + +Which configuration is the default. + +**Common-case default.** The configuration most audiences would choose. Reflects audience research. + +**Inferred default.** Based on referrer, query, or stated preference. + +**Audience-segment default.** Different defaults for different segments (small vs enterprise). + +**The most-popular default.** Use what most users actually pick. + +--- + +## Default presentation + +How the default appears. + +**Visible immediately.** User sees a complete configuration with price. + +**Adjust controls obvious.** User knows what is changeable. + +**Reset-to-default available.** Users who experiment can return to default. + +**Summary-and-detail.** Default shown as summary with expandable detail. + +--- + +## The blank-canvas trap + +When configurators open empty. + +**The pattern.** Empty fields; user must build from scratch. + +**The signal.** High first-step abandonment. + +**The cost.** Users abandon before reaching ah-ha moment of seeing a configuration. + +**The cure.** Default-heavy. Open with a complete configuration. + +--- + +## Default updating + +Defaults decay. + +**What decays.** + +- Most-popular configuration shifts. +- Audience composition changes. +- Product changes invalidate defaults. + +**Maintenance cadence.** Quarterly review. + +--- + +## Default-by-segment + +Different audiences may warrant different defaults. + +**Pattern.** Detect or ask about audience; default adapts. + +**Detection.** Referrer, query, stated input, or inferred from context. + +The discipline. Audience-fit defaults serve better than one-size-fits-all. + +--- + +## Common default failures + +**Blank canvas.** No default; user paralyzes. + +**Wrong default.** Most users adjust away; default does not match audience. + +**Stale default.** Reflects old product or pricing. + +**Default obscures customization.** User does not realize options exist. + +**Default biased toward expensive.** Default flatters revenue, not user fit. + +--- + +## Methodology-level choices that stay in the public skill + +The default-heavy principle. Default selection. Default presentation. The blank-canvas trap. Default updating. Default-by-segment. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific configurators. Specific detection logic. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md new file mode 100644 index 0000000..b562309 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md @@ -0,0 +1,157 @@ +# Real-time pricing patterns + +Price updates with choices. Breakdown and impact display. + +Pricing that responds to choices. Done well, users see cost impact immediately; done poorly, price-shock at checkout drives abandonment. + +--- + +## The no-surprises principle + +Price visible throughout the configuration. No surprises at checkout. + +**The win.** Total price visible at top of configurator. Updates as user adjusts. Per-choice impact visible ("Adds $X"). Breakdown available. + +**The fail.** Price hidden until checkout. User configures heavily. Sees price; abandons. + +The discipline. Price visible; breakdown available; surprises eliminated. + +--- + +## Total price display + +How the total appears. + +**Prominent placement.** Top or top-right of configurator. + +**Real-time updates.** Updates immediately as user changes choices. + +**Currency and locale.** Match the user's locale. + +**Period.** Per-month, per-year, one-time. Match the product's pricing model. + +--- + +## Per-choice impact + +Showing what each option costs. + +**Inline impact.** "+$X/month" next to the option. + +**Strikethrough for upgrades.** Old price strikethrough; new price highlighted. + +**Free options labeled.** "Free" or "Included" explicit. + +The discipline. User can see the cost of each choice without computing. + +--- + +## Pricing breakdown + +How the total breaks down. + +**Expandable breakdown.** "How is this priced" toggle reveals detail. + +**Categorized breakdown.** Base + add-ons + fees. + +**Subscription vs one-time.** Recurring vs one-time costs distinguished. + +The discipline. Breakdown available on demand; not forced. + +--- + +## Annual vs monthly + +Subscription periods. + +**Toggle visible.** User can switch between annual and monthly. + +**Discount disclosed.** "Save X% with annual billing." + +**Both totals shown.** Annual total and monthly equivalent. + +--- + +## Hidden cost surfacing + +Costs that often hide. + +**Setup fees.** Disclosed at configuration; not at checkout. + +**Implementation costs.** If applicable, visible. + +**Per-user vs flat.** Mode disclosed. + +**Overage pricing.** What happens beyond capacity, disclosed. + +The hidden-cost trap. Costs surfaced only at checkout; user feels deceived. + +--- + +## Tax and shipping + +Where applicable. + +**Tax estimate.** Approximate tax visible if jurisdiction can be inferred. + +**Shipping estimate.** Approximate shipping visible if applicable. + +**Final calculation at checkout.** Estimate at configurator; final at checkout. + +The discipline. Estimates clearly labeled; final disclosed. + +--- + +## Price comparison anchoring + +Showing alternative configurations. + +**Comparison anchoring.** "If you upgrade to X, the price increases to Y." + +**Bundle anchoring.** "Equivalent bundle is Z." + +**Use carefully.** Anchoring can manipulate; honesty matters. + +--- + +## Pricing maintenance + +Pricing decays. + +**What decays.** + +- Pricing levels from old pricing models. +- Currency conversions stale. +- Discount terms expired. + +**Maintenance cadence.** When pricing changes, configurator pricing updates as part of the change. + +--- + +## Common pricing failures + +**Hidden pricing.** Total not visible until checkout. + +**Per-choice impact hidden.** User does not know what each choice costs. + +**Surprise fees.** Setup, implementation costs hidden until checkout. + +**Stale pricing.** Reflects old prices. + +**Tax surprise.** Tax not estimated; user surprised at checkout. + +**Currency wrong.** Local user sees wrong currency. + +**No annual-vs-monthly toggle.** User locked into one period. + +**False discount anchoring.** Strikethrough prices that were never charged. + +--- + +## Methodology-level choices that stay in the public skill + +The no-surprises principle. Total price display. Per-choice impact. Pricing breakdown. Annual vs monthly. Hidden cost surfacing. Tax and shipping. Price comparison anchoring. Pricing maintenance. Common failures. + +## Implementation choices that stay internal + +Specific pricing displays for specific configurators. Specific currency and tax logic. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md b/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md new file mode 100644 index 0000000..5ca6010 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md @@ -0,0 +1,218 @@ +# Save-and-share mechanics + +Email-link, account, anonymous, shareable URL, embed. + +Configurations users return to or send to others. Multi-decision purchases require deliberation; B2B configurations often need stakeholder review. Save-and-share supports these workflows. + +--- + +## The deliberation-friendly principle + +Configurators that serve real decision-making produce configurations users want to save and share. + +**The win.** User configures complex purchase. Saves via email-link. Shares with stakeholders. Returns days later. Configuration intact; price unchanged; ready to buy. + +**The fail.** User configures; cannot save; loses work between sessions; abandons. + +The discipline. Save mechanisms support multi-session and multi-stakeholder workflows. + +--- + +## Pattern A: Email-link save + +User enters email; link emailed. + +**How it works.** + +- "Save and resume later" CTA. +- User enters email. +- Link emailed; user clicks to return. + +**Strengths.** No account required; cross-device. + +**Weaknesses.** Email deliverability; link expiration. + +**When to use.** Default for non-authenticated configurators. + +--- + +## Pattern B: Account-based save + +Logged-in users save automatically. + +**How it works.** + +- User logs in. +- Configurations save to account. +- User returns; finds saved configurations. + +**Strengths.** Multi-configuration management. + +**Weaknesses.** Account creation friction. + +**When to use.** When configurator is part of a logged-in product. + +--- + +## Pattern C: Anonymous-session save + +Browser-based persistence. + +**How it works.** + +- Configuration saved to browser local storage. +- User returns same browser; configuration restored. + +**Strengths.** Lowest friction. + +**Weaknesses.** Lost on browser change; limited persistence. + +**When to use.** As supplement to other patterns. + +--- + +## Pattern D: Shareable URL + +Configuration encoded in URL. + +**How it works.** + +- Configurator encodes the configuration in URL parameters. +- User shares URL; recipient opens; sees same configuration. + +**Strengths.** Easy sharing across channels. + +**Weaknesses.** URL length; pricing may shift over time. + +**When to use.** Shareable configurations; B2B stakeholder review. + +--- + +## Pattern E: Embed code + +Configuration embeddable on other sites. + +**How it works.** + +- Configurator generates embed code. +- User pastes into other sites or proposals. + +**Strengths.** Used in B2B proposals. + +**Weaknesses.** Cross-site complexity. + +**When to use.** B2B sales contexts. + +--- + +## Pattern F: Hybrid + +Combining patterns. Common for production configurators. + +**Common combination.** Email-link save + shareable URL + anonymous-session backup. + +**Strengths.** Multiple paths. + +**Weaknesses.** Complexity. + +--- + +## Save trust communication + +Users hesitate to save partial sensitive configurations. + +**What to communicate.** + +- What is saved. +- How long it persists. +- Who can access it. +- How to delete. + +The discipline. Trust communication explicit; not buried in privacy policy. + +--- + +## Resume experience + +When user returns. + +**The principle.** Resume should be uninterrupted. + +**The pattern.** + +- User clicks recovery link or logs in. +- Lands at the configuration; rest preserved. +- Continues without re-doing. + +**Resume failures.** + +- Configuration partially preserved; values lost. +- Pricing changed; user surprised. +- Constraint logic shifted; configuration now invalid. + +The discipline. Resume preserves; communicate any changes (e.g., "Pricing has updated since you last visited"). + +--- + +## Pricing on resume + +When prices change between save and resume. + +**Honest pattern.** Show the saved configuration with original price; surface "Pricing has changed; updated price is X" with explanation. + +**Dishonest pattern.** Silently update price; user does not notice. + +The discipline. Honesty about price changes. + +--- + +## Sharing privacy + +Shared configurations may include sensitive info. + +**Considerations.** + +- What is in the URL/embed. +- Who can see it. +- How long links are valid. + +The discipline. Sharing respects user privacy; sensitive details may need account-based sharing rather than URL. + +--- + +## Save-and-share analytics + +Track usage. + +**Metrics.** + +- Save rate. +- Resume rate per saved configuration. +- Share rate. +- Configurations completed via save-and-share path. + +--- + +## Common save-and-share failures + +**No save mechanism.** Users lose work; abandon. + +**Save mechanism brittle.** Links expire; account access broken. + +**Resume loses state.** User lands at start; loses work. + +**Pricing surprise on resume.** Silent price update. + +**Sharing exposes sensitive info.** Embedded URLs share more than intended. + +**Save trust missing.** Users do not save because they distrust persistence. + +--- + +## Methodology-level choices that stay in the public skill + +The deliberation-friendly principle. Patterns A through F. Save trust communication. Resume experience. Pricing on resume. Sharing privacy. Analytics. Common failures. + +## Implementation choices that stay internal + +Specific save mechanisms for specific configurators. Specific tooling for URL encoding and embed generation. Privacy review processes. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md new file mode 100644 index 0000000..7375621 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md @@ -0,0 +1,191 @@ +# Validation and error patterns + +Helpful validation. Inline, pre-emptive, final. + +Validation catches invalid input. Done well, validation is helpful and inline; done poorly, validation is punitive or arrives only at submission. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. + +**The win.** User selects an option that requires another. Inline validation surfaces immediately; explains; auto-corrects or guides. + +**The fail.** User configures complete configuration. Submits. Validation runs at backend. User sees error; loses momentum. + +The discipline. Validation timing matters; specific, helpful messages matter; preserve user inputs on error. + +--- + +## Pattern A: Inline validation + +Validation runs as the user makes choices. + +**How it works.** + +- User selects an option. +- System validates against the rest of the configuration. +- If invalid, message appears next to the choice. + +**Strengths.** Errors caught at point of input. + +**Weaknesses.** Real-time validation can lag; intrusive if too aggressive. + +**When to use.** Default for most configurators. + +--- + +## Pattern B: Pre-emptive validation + +Constraints prevent invalid choices from being selectable. + +**How it works.** + +- Options that would create conflicts are disabled with explanation. +- User cannot select the invalid option. + +**Strengths.** Errors prevented; user does not encounter them. + +**Weaknesses.** Some users want to see the option even if disabled. + +**When to use.** When the constraint is hard and explanation is clear. + +--- + +## Pattern C: Final validation + +Validation runs at submission. + +**How it works.** + +- User completes configuration. +- Submit; system runs full validation. +- Errors surfaced at this stage. + +**Strengths.** Catches errors that span multiple fields. + +**Weaknesses.** Late; user invested in completing. + +**When to use.** As supplement to inline validation; not primary. + +--- + +## Pattern D: Hybrid + +Combining patterns. + +**Common combination.** Pre-emptive for hard constraints; inline for soft validation; final as backup. + +**Strengths.** Multiple safety nets. + +**Weaknesses.** Complexity. + +**When to use.** Production configurators with multiple constraint types. + +--- + +## Validation message discipline + +What the message says. + +**Strong messages.** + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +**Examples.** + +- "Option A requires Option B; we have selected B for you." +- "Option C is incompatible with Option D. Choose one or contact us for custom." +- "Quantity exceeds 1000; for larger quantities contact our team." + +**Weak messages.** + +- "Invalid configuration." +- "Error." +- "Please correct the issues." + +The discipline. Specific, helpful, offers paths. + +--- + +## Validation strictness + +How aggressively to validate. + +**Too strict.** Rejects valid inputs at edge cases. Frustrates users. + +**Too loose.** Accepts invalid inputs that fail downstream. + +**The right strictness.** Validation matches actual product constraints. + +--- + +## Preserve inputs on error + +What happens when validation engages. + +**The principle.** Errors should not lose user inputs. + +**The pattern.** Error appears; rest of configuration preserved; user adjusts the specific issue. + +**The reset-on-error failure.** Form resets entirely on error. User loses all work; abandons. + +The cure. Errors are local; configuration state preserved. + +--- + +## Mobile validation + +Validation on mobile. + +**Mobile considerations.** + +- Inline messages must fit mobile screens. +- Auto-correct should work with touch. +- Error states must be visible without zoom. + +The mobile discipline. Test validation on actual devices. + +--- + +## Validation testing + +Test validation across cases. + +**Test cases.** + +- Valid configurations: pass through. +- Invalid configurations (each constraint type): caught with helpful message. +- Edge cases (boundary values, unusual combinations): handled. +- Mobile: works on touch. + +--- + +## Common validation failures + +**Late validation.** Errors caught only at submission. + +**Generic error messages.** No guidance. + +**Strict validation rejects valid inputs.** Edge cases lost. + +**Loose validation accepts invalid.** Fails downstream. + +**Reset-on-error.** User loses work. + +**Validation interrupts typing.** Real-time validation too eager. + +**Mobile-broken validation.** Errors invisible or off-screen. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D. Validation message discipline. Validation strictness. Preserve inputs on error. Mobile validation. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/programmatic-seo/SKILL.md b/dist/pi/.agents/skills/programmatic-seo/SKILL.md new file mode 100644 index 0000000..124d85f --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/SKILL.md @@ -0,0 +1,279 @@ +--- +name: programmatic-seo +description: "How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. Data source identification, template design, schema patterns, quality control at scale, internal linking architecture, crawl budget management, AEO/GEO for programmatic pages, refresh discipline, and the make-or-break question of whether pSEO is the right answer for your program at all. Triggers on programmatic SEO, pSEO, scaled content, page generation, template SEO, location pages, comparison pages, directory site, listing site, scaled landing pages, programmatic content. Also triggers when a content set is not ranking, has been hit by an algorithm update, or when a team is considering pSEO as a growth lever." +category: content +catalog_summary: "Designing pSEO programs that work: data sources, template design, quality control at scale, internal linking, crawl budget, AEO/GEO patterns, refresh discipline, and when pSEO is and is not the right answer" +display_order: 6 +--- + +# Programmatic SEO + +A senior SEO strategist's playbook for designing and running programmatic SEO programs that produce durable traffic instead of penalty-bait. + +Programmatic SEO has a complicated reputation. Sites like Zillow, Airbnb, TripAdvisor, Indeed, and Yelp have built billion-dollar traffic engines on pSEO. Other sites have built pSEO programs that got hit by Google's helpful-content updates and lost 80% of their traffic in a week. The difference is rarely the technique; it is the underlying data quality and the quality control discipline at scale. + +This skill is the playbook for getting that distinction right. It assumes you have decided what keyword space to target (see `seo-keyword`) and how the broader content program is shaped (see `content-strategy`). It does not write individual editorial pieces (see `content-and-copy` for that) and does not architect editorial topic hubs (see `pillar-content-architecture` for that). What it does is teach the discipline of generating high-volume pages programmatically from structured data sources without producing thin content, duplicate content, or scale-without-substance pages that get penalized. + +When to use this skill: deciding whether pSEO is a fit for the program at all (the most important question), designing a new pSEO system, auditing an existing pSEO set that is not ranking or has been hit by an algorithm update, or building quality-control discipline for a pSEO program that grew faster than its quality processes. + +--- + +## What this skill is for + +This skill spans scaled-content programs from data source through quality control. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: editorial pillars, calendar, governance. Decides whether pSEO fits the program at all. +- `pillar-content-architecture` is hub-scope: one topic with 10 to 15 intentional editorial pieces. Editorial in nature. +- `content-brief-authoring` is per-piece scope: brief for one editorial artifact. +- `content-and-copy` is execution scope: writing individual editorial pieces. +- This skill is scaled scope: 100s to 100,000s of pages generated programmatically from structured data sources, each targeting a long-tail query. + +The clean reading order: `content-strategy` decides whether pSEO is a fit, `seo-keyword` surfaces the long-tail keyword space, this skill designs the pSEO system, `editorial-qa` (forthcoming) provides the QA discipline for sampled quality control across the set. `content-and-copy` and `content-brief-authoring` are not in the loop for pSEO at scale; those skills are for editorial pieces, not data-driven generated pages. + +The audience: SEO content strategists, content engineers, agencies running pSEO programs, in-house teams considering pSEO as a growth lever. The voice is senior SEO strategist to junior PM or marketer. Specific, opinionated, honest. The reputation problem is not pSEO; it is pSEO without underlying value. + +--- + +## When pSEO is the right answer + +The keystone question. pSEO works when all of the following are true. + +**1. Real underlying data.** A genuine structured data source with depth: 10+ fields per record, ideally 20+, with first-party data, expert-curated data, or licensed datasets. Not just scraped data or AI-generated facts dressed as structured records. + +**2. Long-tail query volume justifies the effort.** The queries the program would target have meaningful aggregate volume even if individual queries are small. Real estate "homes for sale in {neighborhood}" works at scale. "Blue widget reviews 2026" generated for every adjective times widget combination does not, because the queries are not actually searched. + +**3. User intent is queryable.** The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +**4. Update cadence aligns with query volatility.** Real estate listings update daily and the data refresh aligns. "Best [thing] for [year]" pages get stale annually and need a refresh discipline budgeted in. + +**5. Quality control is operationally feasible.** The team has the capacity to sample-audit the set, fix failures, and maintain quality as the set grows. Not aspirationally; budgeted in headcount. + +pSEO does NOT work when: + +- The underlying data is shallow (3 to 5 fields, mostly AI-generated, no first-party signal) +- The query volume is illusory (long-tail keywords nobody actually searches) +- User intent requires narrative or judgment that data cannot supply +- Quality control is not budgeted (write a bunch of pages, ignore them) +- The program is scaling AI-generated thin pages without unique data + +The honest framing. Most teams that ask "should we do pSEO?" should hear "probably not, unless the underlying data is unique or first-party expertise makes the pages actually useful." The reputation problem is not the technique; it is the technique applied without underlying value. + +Detail in [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md). + +--- + +## Data source identification + +The data source is the pSEO program. Common sources with different defensibility profiles. + +**First-party data.** Customer transactions, content database, user-generated content. Defensible because nobody else has it. Examples: Glassdoor's employee reviews, Yelp's user ratings, TripAdvisor's traveler reviews. + +**Licensed datasets.** Industry databases, regulatory data, government datasets, licensed third-party feeds. Defensible by license terms and integration depth. Examples: Zillow's MLS partnerships, real estate brokerage feeds, sports statistics licenses. + +**Aggregated public data.** Scraped, cleaned, enriched. Judgment call on legality (often gray area depending on robots.txt, terms of service, jurisdictional rules). Defensibility depends on the cleaning and enrichment work. Easy to copy if the cleaning is shallow. + +**Expert-curated content.** The dataset is built by hiring experts to populate it. Slow, high-quality, defensible. Examples: Wirecutter's product testing, expert-reviewed medical content, curated editorial databases. + +**Synthesized data.** Combining multiple sources into a unique view. "Neighborhoods times schools times prices" combining three datasets into a comparison view. Defensibility comes from the synthesis logic and the ongoing maintenance of multi-source pipelines. + +The "moat" question. Would a competitor be able to replicate the data source? If yes, the pSEO program has no defensibility; anyone can copy. If no, the data source becomes a moat that compounds. Zillow's MLS partnerships, Glassdoor's employee reviews, Crunchbase's funding data, are moats. "Scraped Wikipedia plus AI rewrite" is not. + +Detail in [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md). + +--- + +## Template design + +The template is the structure that data fills. Design principles. + +**Above-the-fold answer.** The user's specific question answered in the first 200 words of the rendered page, structured for both human reading and AI extraction. The answer is what gets cited; the rest is supporting depth. + +**Variable density.** The template accommodates records with sparse fields (some have 5 data points, others have 50) without looking broken. Sparse pages need fallback patterns; dense pages need progressive disclosure to avoid overwhelming. + +**Heading hierarchy that reflects data.** H2s and H3s map to data sections (overview, details, comparisons, related). The heading structure is not decorative; it tells crawlers and AI engines what the page covers. + +**Schema markup as part of template.** Structured data (JSON-LD, microdata, or RDFa depending on the stack) embedded in the template renders machine-readable signals at scale across the entire set. Without schema, the set is invisible to the structured-data extraction layer search and answer engines run. + +**Internal linking placeholders.** The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. 5 to 15 internal links per page is typical for a well-linked set. + +**Distinctive value per page.** Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. If the page is just a re-pivot of the parent's data, the page is filler. + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. If a randomly sampled page is thin, the entire set is thin. + +Detail in [`references/template-design-patterns.md`](references/template-design-patterns.md). + +--- + +## Schema design + +The data shape that drives the template. Design principles. + +**Field count signals depth.** 5 fields per record is thin. 15 to 20 is competent. 30+ is deep. The field count is not a vanity metric; it determines what the template can render at depth versus what falls back to filler. + +**Required vs optional fields.** Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. A page with 3 of 30 optional fields populated should not ship; a page with 25 of 30 should. + +**Computed fields.** Derived from source data. Average price per square foot computed from listings adds depth without requiring more source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +**Cross-record fields.** Fields that reference other records in the set enable internal linking and comparison. The "5 most similar neighborhoods" field on every neighborhood page powers the sibling-link section without manual curation. + +**Update frequency tags.** Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). Without tagging, refresh becomes "audit everything" instead of "refresh the volatile fields." + +The "schema-as-product" principle. The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. Versioned, reviewed, documented, breaking-change-aware. + +Detail in [`references/schema-design-patterns.md`](references/schema-design-patterns.md). + +--- + +## Quality control at scale + +Auditing all 100,000 pages individually is infeasible. The discipline. + +**Sampling strategy.** Random sample 50 to 200 pages per audit cycle, balanced across data shape (sparse, dense, recent, old, popular categories, niche categories). The sample is not "the latest 50 pages"; it is a stratified sample that exposes problems specific to particular data shapes. + +**Automated checks.** Heading structure, schema validity, internal link count, word count thresholds, duplicate-content checks, broken-link checks. Run on every page on a cadence; surface failures as a queue. + +**Manual review checklist.** For sampled pages, check the top-200-word answer quality, check whether the page would satisfy the user's query, check whether the page reads as distinctive versus templated. The manual review is the layer automated checks miss. + +**Failure thresholds.** If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. The threshold is not negotiable; without it, quality drift compounds invisibly until the algorithm update reveals it. + +**Cohort tracking.** Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. Cohort tracking is the pSEO equivalent of the experimentation team's drift detection. + +The team budget question. A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. If that is not budgeted, the program will decay. The set will look fine on launch and degrade over 6 to 12 months as data drifts, templates ship without QC, and the gap between the QC plan and the actual cadence widens. + +Detail in [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md). + +--- + +## Internal linking across the set + +pSEO sets need intentional internal linking architecture to compound. + +**Hub pages.** Parent-level pages (e.g., "homes for sale in Denver") that link to all child pages (specific neighborhoods). Hub pages are linked from main navigation; they are the entry point for the set's traffic. + +**Sibling linking.** Each page links to 5 to 15 related sibling pages: similar neighborhoods, similar price ranges, similar features. Sibling links are computed from cross-record fields in the schema; they are not manual curation at scale. + +**Reverse-direction linking.** Child pages link up to hub; sibling links go both directions. The graph is bidirectional; PageRank flows both ways. + +**Anchor text variation.** Avoid every page using the same anchor text. Vary by record characteristic (the record name, a descriptive phrase, the parent category). Uniform anchor text at scale signals manipulation to ranking systems. + +**Crawl-friendly architecture.** Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +The PageRank flow principle. Internal linking is what makes pSEO sets compound. A well-linked set distributes ranking signal across all pages; a poorly-linked set has hub pages ranking and child pages orphaned. The link architecture is half the program; the data is the other half. + +Detail in [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md). + +--- + +## Crawl budget management + +Search engines have crawl budgets. Large pSEO sets can exhaust them. + +**Sitemap segmentation.** Split sitemaps by category or recency so crawlers prioritize active pages. A single sitemap with 100,000 entries is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each, organized by category or last-update. + +**Noindex on thin pages.** Pages with insufficient data should noindex rather than ship as bait. The discipline: pages that fail the schema's required-field threshold do not get a public URL; they sit in the system as drafts until their data populates. + +**Canonical handling.** Comparison pages (X vs Y) often have inverse pages (Y vs X). Canonicalize to one. Comparison-pivot duplicates without canonicalization split ranking signal. + +**Crawl rate signals.** Monitor Google Search Console crawl stats. If crawl rate is plateauing while page count grows, the set is hitting budget limits. The fix is not "publish more pages"; it is "noindex thin pages and improve internal linking so crawlers prioritize better." + +**Pruning criteria.** Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. Pruning is hygiene, not failure. A 100,000-page set with 60% earning traffic is healthier than the same set with 40% earning traffic plus 60% dead weight crawlers waste budget on. + +Detail in [`references/crawl-budget-management.md`](references/crawl-budget-management.md). + +--- + +## AEO and GEO for programmatic pages + +Answer engines treat programmatic pages differently from editorial pages. + +**Direct-answer extraction.** AI engines extract the top-200-word answer; templates that lead with the answer get cited. The opening of the page is the citation candidate; everything after it is supporting depth. + +**Structured data signals.** JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. Programmatic pages with minimal schema lose to programmatic pages with deep schema even when the underlying data is similar. + +**Citation patterns.** AI engines tend to cite programmatic data pages for factual queries (prices, statistics, comparisons, factual details) and editorial pages for analytical queries (why, how, what should I think). Design templates to fit the factual-query lane; do not try to make programmatic pages compete for analytical queries that editorial content owns. + +**Quality crackdown sensitivity.** AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. The pSEO penalty risk has migrated to AI surfaces; the same quality-at-scale discipline applies, with less tolerance. + +The "two-engine optimization" framing applies. pSEO pages should serve both search engines and answer engines. Most pSEO programs were designed pre-AEO and need template updates for the new surface: stronger top-200-word answers, deeper schema markup, FAQPage schema where the page contains FAQ structure. + +Detail in [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md). + +--- + +## Refresh and maintenance at scale + +pSEO sets decay if not maintained. + +**Data refresh cadence.** Quarterly minimum for most datasets. Daily or weekly for time-sensitive data (real estate listings, prices, availability, current statistics). The refresh cadence is set when the program launches; retrofitting is expensive. + +**Template version migration.** When the template improves, all existing pages need migration. Cohort-by-cohort migration with monitoring beats big-bang migration. Each cohort gets the new template, sits for 30 days under monitoring, then the next cohort migrates. + +**Pruning lifecycle.** Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. The 24-month checkpoint is the standard cutoff; some categories warrant earlier or later pruning. + +**Set-level refresh.** Occasionally the entire set's template needs a refresh as user expectations evolve, AI engine signals shift, or category conventions change. Set-level refreshes are 6-month projects, not weekend cleanups. + +Detail in [`references/refresh-at-scale.md`](references/refresh-at-scale.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pseo-failures.md`](references/common-pseo-failures.md). + +- "We generated 50,000 pages and got penalized." Thin content, scaled too fast, no QC discipline. +- "We have 10,000 pages but only 200 rank." Internal linking architecture missing; child pages are orphans. +- "Crawl rate plateaued." Crawl budget exhausted; noindex thin pages and improve sitemap segmentation. +- "Pages look identical." Template lacks variable density; data is too sparse to differentiate. +- "We cannot update the templates without 10,000 manual fixes." Template versioning was not designed for scale. +- "Our quality control is whoever has time." No sampling discipline, no thresholds, no ownership. +- "AI engines do not cite our pages." Top-200-word answer was not designed; structured data is thin. +- "We are at 100,000 pages and engagement is dropping." The set has outgrown its data depth. +- "Competitors copied our pages." The data source was not a moat. +- "Refresh is overwhelming." Cadence was not designed for scale; templates are not migration-friendly. +- "Our pSEO drives traffic but no conversions." Query intent does not match buyer intent; reconsider whether pSEO was the right channel for the program goal. + +--- + +## The framework: 12 considerations for programmatic SEO + +When designing or auditing a programmatic SEO program, walk these 12 considerations. + +1. **Right answer for the program.** pSEO needs real underlying data, queryable intent, and quality-control budget. Default to no if any is missing. +2. **Data source as moat.** Replicable data is not defensible; first-party, licensed, expert-curated, or synthesized data is. +3. **Schema depth.** 15+ fields per record minimum; 30+ for competitive depth. +4. **Template variable density.** Accommodates sparse and dense records gracefully. +5. **Above-the-fold answer.** First 200 words answer the user's specific query. +6. **Schema markup at scale.** Structured data on every page; this is the AEO/GEO signal. +7. **Internal linking architecture.** Hub-and-spoke plus sibling linking, no orphans. +8. **Quality control sampling.** 50 to 200 pages per audit, balanced across data shape. +9. **Failure thresholds.** 5% sample failure halts generation until template or data fixes ship. +10. **Crawl budget discipline.** Sitemap segmentation, noindex on thin pages, canonicalization on duplicates. +11. **Refresh cadence.** Quarterly minimum data refresh; cohort-by-cohort template migration. +12. **Pruning lifecycle.** Pages that fail to earn traffic in 12 to 24 months get noindexed or removed. + +The output of the framework is a pSEO design document the team can reference at every stage: data source named, schema versioned, template specified, QC discipline budgeted, internal linking architecture mapped, refresh cadence set. + +--- + +## Reference files + +- [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md) - Five-criterion decision framework with worked examples of yes, no, and maybe. +- [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md) - First-party, licensed, public, expert-curated, synthesized; defensibility analysis. +- [`references/template-design-patterns.md`](references/template-design-patterns.md) - Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. +- [`references/schema-design-patterns.md`](references/schema-design-patterns.md) - Field count, computed fields, cross-record fields, update tags, schema-as-product. +- [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md) - Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. +- [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md) - Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. +- [`references/crawl-budget-management.md`](references/crawl-budget-management.md) - Sitemap segmentation, noindex patterns, canonicalization, crawl rate monitoring, pruning criteria. +- [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md) - Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. +- [`references/refresh-at-scale.md`](references/refresh-at-scale.md) - Data refresh cadence, template versioning, cohort migration, pruning lifecycle. +- [`references/common-pseo-failures.md`](references/common-pseo-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: quality at scale or not at all + +The only durable pSEO programs are the ones that hold quality at scale. The temptation to scale quantity at the cost of quality has produced the entire bad reputation pSEO carries. Sites that resist that temptation, that maintain real data depth, real quality control, real refresh discipline, keep producing meaningful traffic for years. Sites that do not get penalized within months of an algorithm update. + +The discipline is not optional and it is not free. Budget for it before generating the first page, or do not start at all. + +When in doubt about whether a pSEO program is ready, ask: is the data source actually unique, is the schema deep, does the template lead with the answer, is the internal linking architecture mapped, is QC budgeted in headcount, is the refresh cadence set? If yes to all of those, ship the design document and let the engineering work begin. If no to any of them, fix the gap before any pages generate. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md b/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md new file mode 100644 index 0000000..2300287 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md @@ -0,0 +1,106 @@ +# AEO and GEO for programmatic pages + +Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. + +Answer engines treat programmatic pages differently from editorial pages. The differences shape how pSEO templates should be designed for the AI search era. + +--- + +## Direct-answer extraction + +AI engines extract the top-200-word answer; templates that lead with the answer get cited. + +**The pattern.** The opening of the page is the citation candidate. AI engines pull from the first answer-shaped paragraph, FAQPage schema entries, and structured-data fields. Everything after the opening is supporting depth that justifies the citation but is rarely cited directly. + +**Template implication.** The first 200 rendered words must answer the user's specific query in a self-contained way. A page about "homes for sale in Denver under $500k" should answer that exact query in the opening: count of listings, average price, top neighborhoods, with structured data backing each claim. + +**Anti-pattern.** Welcome paragraphs, navigation hints, "below you will find" filler. These dilute the citation candidate and reduce the page's AI-engine pull. + +**Snippet-bait paragraphs at H2 level.** Beyond the top-200-word answer, each H2 should have a 40 to 60 word snippet-bait paragraph. AI engines often quote multiple snippet-bait paragraphs as multi-paragraph citations. + +--- + +## Structured data signals + +JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. + +**The "thin schema" penalty.** Programmatic pages with minimal schema (just the basic Article or Product type, with required fields only) lose to programmatic pages with deep schema (complete schema graph, optional fields populated, cross-entity references). The underlying data may be similar; the schema markup is what AI engines see. + +**Schema patterns that signal quality at scale.** + +- **Type-appropriate schema.** Product for product pages, LocalBusiness for location pages, Article for editorial pages, FAQPage for FAQ sections, BreadcrumbList for navigation context. +- **Cross-entity references.** Schema entries that reference other entities in the dataset (relatedProduct, parentOrganization, hasPart) signal a connected knowledge graph rather than isolated pages. +- **Aggregate schema.** Reviews, ratings, statistics presented as structured aggregateRating, aggregateOffer, aggregateProperty fields. +- **FAQPage schema on FAQ sections.** AI engines (Perplexity especially) cite FAQPage-marked content heavily; programmatic pages that include FAQ sections should mark them. + +**Schema validation.** Run schema validation on every page; failures produce silent invisibility in AI surfaces. The validation is automated and gates publish. + +--- + +## Citation patterns + +AI engines cite programmatic data pages and editorial pages for different query types. + +**Factual-query lane.** AI engines tend to cite programmatic data pages for factual queries: prices, statistics, comparisons, factual details, specifications, locations, ratings. The page renders the fact as structured data; the AI engine cites the structured data as the answer. + +**Analytical-query lane.** AI engines tend to cite editorial pages for analytical queries: why, how, what should I think, recommendations with reasoning, opinions, judgments. Programmatic pages cannot compete in this lane; the data does not supply the analysis the user wants. + +**Implication for pSEO design.** Design templates to fit the factual-query lane. Do not try to make programmatic pages compete for analytical queries that editorial content owns. The two lanes coexist; pSEO is one half of a two-lane content strategy. + +**The "hybrid page" pattern.** Some pSEO programs add an editorial layer to programmatic pages (per-page expert commentary, AI-summarized analysis with human review). Hybrid pages can compete in both lanes when the editorial layer is genuinely substantive. Without substantive editorial layer, hybrid pages read as factual pages with filler attached and lose in both lanes. + +--- + +## Quality crackdown sensitivity + +AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. + +**The migration of penalty risk.** Pre-AI search era, thin pSEO sets could rank for 12 to 24 months before quality crackdowns hit. AI engines apply quality signals more aggressively. Thin pSEO sets in 2026 lose AI citations within 3 to 6 months even when traditional search rankings are still holding. + +**Signals AI engines use beyond traditional search signals.** + +- **Distinctiveness.** Pages that read as templated boilerplate get deprioritized. Pages that surface page-specific data prominently get cited. +- **Source credibility.** Pages with named authors, expert credentials, and citation chains get cited preferentially. Anonymous pSEO pages with no attribution lose to attributed pages. +- **Citation traceability.** Pages that cite their underlying data sources (with links to the source) get treated as authoritative. Pages that present facts without sourcing get treated as unreliable. +- **Freshness.** Pages with recent update dates get cited preferentially for time-sensitive queries. Stale pages lose AI citations even when traditional search rankings hold. + +**The implication.** pSEO programs designed pre-AEO need template updates: stronger above-the-fold answers, deeper schema markup, FAQPage schema on FAQ sections, source citations on factual claims, named authorship where the program supports it. + +--- + +## Two-engine optimization + +pSEO pages should serve both search engines and answer engines. + +**Both engines reward depth.** Search engines reward comprehensive coverage; AI engines reward citation-ready depth. Same content, different extraction. + +**Both engines reward structure.** Search engines parse heading hierarchy for ranking; AI engines parse heading hierarchy for citation extraction. Same structure, different use. + +**Both engines reward freshness.** Search engines reward recent updates; AI engines re-index recently updated content more aggressively. Same updates, different cadence. + +**The two-engine implication.** Designing for AEO does not trade off against SEO. The template improvements that earn AI citations (top-200-word answers, FAQPage schema, named authorship, source citations) also earn search rankings. Teams that treat AEO and SEO as separate optimizations under-invest in both. + +--- + +## Set-level reputation signals + +Beyond individual page signals, AI engines apply set-level reputation. The set's overall quality affects each page's citation likelihood. + +**Domain-level reputation.** A domain with a substantive editorial content layer plus a high-quality pSEO set ranks both layers more strongly than a domain with only pSEO. The editorial layer establishes the domain's expertise; the pSEO layer benefits. + +**Set-level signal compounds.** A 10,000-page pSEO set with 90% high-quality pages and 10% thin gets the entire set treated as high-quality. The same set with 60% high-quality pages and 40% thin gets the entire set deprioritized. The bad pages drag the good ones down. + +**The implication.** Set-level QC discipline (covered in `quality-control-at-scale.md`) is also AEO discipline. Holding the quality threshold across the set protects the set's AI-citation reputation, not just its search ranking. + +--- + +## Measurement + +Hub-level AEO/GEO metrics worth tracking on the pSEO set: + +- Brand mention rate from AI search visibility tools (Profound, Frase visibility tracking, AirOps AEO data) +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude, Google AI Mode) on the set's target queries +- Top-cited pages within the set (which template patterns get cited most) +- AI crawler hit frequency from server logs (GPTBot, PerplexityBot, ClaudeBot) + +Track at the set level, not just per page. Aggregate trends surface patterns that per-page tracking misses. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md b/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md new file mode 100644 index 0000000..175bb9b --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md @@ -0,0 +1,161 @@ +# Common pSEO failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: pSEO programs that ship without one of the five readiness criteria (real data, queryable intent, sufficient volume, refresh cadence, QC budget) and assume the gap will close later. The gap rarely closes; the failure compounds. + +--- + +## "We generated 50,000 pages and got penalized" + +**Symptom.** Algorithm update lands; the set loses 60 to 90% of its traffic in days. + +**Diagnosis.** Thin content scaled too fast without QC discipline. The set was generating filler pages, sometimes from AI-summarized public data, sometimes from sparse first-party data with bolt-on AI text. The algorithm update detected the scale-without-substance pattern. + +**Fix.** Halt new generation. Run a triage audit: which pages have substantive data backing them, which are filler. Noindex the filler. The remaining pages may recover ranking once the set's quality signal improves; the filler ones will not. Sometimes the right call is removing the entire pSEO surface and rebuilding from a higher-quality data source. + +**Prevention.** The five-criterion check (`when-pseo-works-decision.md`) before launch. The QC discipline (`quality-control-at-scale.md`) before scaling. + +--- + +## "We have 10,000 pages but only 200 rank" + +**Symptom.** Pages exist in the set; few of them rank for their target queries. + +**Diagnosis.** Internal linking architecture missing or incomplete. Hub pages rank because they receive site-wide navigation links. Child pages do not rank because they have no in-page link votes; they are partial orphans reachable only via sitemap. + +**Fix.** Build the link graph. Add sibling-link slots to the template. Compute cross-record similarity to populate sibling links. Backfill the link graph across the existing set. Audit for orphans; surface them in the QC queue (`internal-linking-at-scale.md`). + +--- + +## "Crawl rate plateaued" + +**Symptom.** Page count grows; pages crawled per day stays flat or declines. + +**Diagnosis.** Crawl budget exhaustion. The set has more pages than the search engine's crawl budget supports. + +**Fix.** Noindex thin pages. Segment sitemaps. Improve internal linking so crawlers prioritize substantive pages. Reduce server response time. Prune the dead-page tail. Detail in `crawl-budget-management.md`. + +The wrong fix: publishing more pages to "catch up" on traffic targets. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## "Pages look identical" + +**Symptom.** Random sampling of pages from the set finds them indistinguishable in substance, only different in identifiers. + +**Diagnosis.** Template lacks variable density, or the data is too sparse to differentiate. The template renders the same boilerplate for every record because the records do not actually differ on the dimensions the template surfaces. + +**Fix.** Two paths. + +- If the template is the problem (the data has variation but the template hides it): redesign the template to surface distinctive fields prominently. Move the differentiating data above the fold; demote the boilerplate. +- If the data is the problem (the records genuinely lack distinctive fields): the schema is too thin. Either deepen the schema with more source data, or accept that the program does not justify pSEO and pivot to editorial content. + +--- + +## "We cannot update the templates without 10,000 manual fixes" + +**Symptom.** A template change requires manually editing every existing page. + +**Diagnosis.** Template versioning was not designed for scale. Pages were generated as static output rather than as renders from the schema; updating the template now requires updating each rendered page. + +**Fix.** Architectural rebuild. Pages need to be re-rendered from the schema each time the template changes. The schema is the source of truth; the rendered pages are the output. Without this discipline, every template change becomes a per-page migration project. + +**Prevention.** Design pages as renders from data, not as static artifacts. The specific stack choice (build-time generation that re-runs on template change, server rendering with template version in the cache key, hybrid approaches) varies by team; the methodology principle is the same. + +--- + +## "Our quality control is whoever has time" + +**Symptom.** No regular QC cadence. Sample audits happen sporadically when someone notices a problem. + +**Diagnosis.** No sampling discipline, no thresholds, no ownership. The QC was assumed to be everyone's job, which means it is nobody's job. + +**Fix.** Assign a QC owner. Set the sampling cadence (monthly minimum for active programs). Codify the failure threshold (5% sample failure halts new generation). Track cohort metrics. Detail in `quality-control-at-scale.md`. + +--- + +## "AI engines do not cite our pages" + +**Symptom.** Traditional search rankings are stable; brand mention rate from AI search visibility tools is flat or declining. + +**Diagnosis.** Multiple possible causes. + +- The top-200-word answer was not designed; pages start with welcome paragraphs instead of answers. +- Schema markup is thin; AI engines see the pages as low-authority. +- FAQPage schema is missing on FAQ sections. +- Source citations are missing on factual claims. +- The pages read as templated boilerplate rather than as distinctive answers. + +**Fix.** Audit the template against the AEO/GEO patterns (`aeo-geo-for-programmatic-pages.md`). Update the template; migrate cohorts; monitor citation count by cohort to confirm the fix earned gains. + +--- + +## "We are at 100,000 pages and engagement is dropping" + +**Symptom.** Traffic continues but bounce rate climbs, time-on-page falls, conversion rate decays. + +**Diagnosis.** The set has outgrown its data depth. Early pages were the highest-data-quality records; later pages were lower-quality data backfilled to grow the set. Users are landing on pages that do not satisfy their query. + +**Fix.** Reverse the growth and prune. The set should be smaller and higher-quality, not larger and lower-quality. Identify the data-quality threshold below which pages do not satisfy queries; noindex pages below the threshold; let the set's average quality recover. + +**Prevention.** The required-field threshold in the schema enforces a quality floor. Pages that fail the threshold should not have shipped in the first place. + +--- + +## "Competitors copied our pages" + +**Symptom.** A competitor launched a similar pSEO set; the brand's traffic share is shrinking. + +**Diagnosis.** The data source was not a moat. The pSEO pages were replicable. + +**Fix.** Two paths. + +- Deepen the data source. First-party data accumulation, expert curation investment, licensed-feed integration that competitors cannot match. The defensibility comes from the data, not from the pSEO build. +- Pivot. If the data cannot be deepened, the program does not have a long-term moat. Consolidate the strongest pages, prune the rest, redirect the team to higher-defensibility work. + +**Prevention.** The defensibility test (`data-source-identification-patterns.md`) before launch. If competitors could replicate the data source within 6 months at reasonable cost, do not launch the program. + +--- + +## "Refresh is overwhelming" + +**Symptom.** Quarterly refresh cycles are missed or partially completed; data drifts; pages get stale. + +**Diagnosis.** Refresh cadence was not designed for scale. The team thought "we will refresh quarterly" but the actual work to refresh 10,000 to 100,000 pages exceeds the team's quarterly capacity. + +**Fix.** Automate the volatile-field refresh through data pipelines (mostly hands-off after pipeline build). Reduce slow-changing-field refresh frequency to annual on most fields. Cohort-migrate the template refresh rather than big-bang. Detail in `refresh-at-scale.md`. + +If the work still exceeds capacity after these fixes, the set is too large for the team's resources. Prune to a sustainable size. + +--- + +## "Our pSEO drives traffic but no conversions" + +**Symptom.** Traffic from pSEO pages is high; signups, sales, or engagement on the funnel goal are flat or low. + +**Diagnosis.** Query intent does not match buyer intent. The pSEO pages are answering informational queries; the buyer the program needs to capture is searching with different intent. + +**Fix.** Audit the queries the pSEO traffic is coming from. If the queries are not in the buyer's funnel, the program is producing non-converting traffic regardless of how well the pages are optimized. The fix is not "add more CTAs to pSEO pages"; the fix is recognizing that pSEO was not the right channel for the program's conversion goal. + +**The reconsider-pSEO moment.** If the program's metric is conversions and the pSEO traffic does not convert, pSEO is the wrong tool. Editorial content with stronger buyer-intent alignment, paid acquisition with conversion tracking, or product-led growth surfaces may be the better fit. + +--- + +## "Our QC discipline drifted over time" + +**Symptom.** The program launched with strong QC. Months in, the cadence slipped, the threshold became aspirational rather than enforced, the cohort tracking went unread. + +**Diagnosis.** QC ownership rotated, accountability dispersed, the metric dashboard stopped being reviewed. The pattern is the same as the "set and forget" failure for editorial pillar maintenance. + +**Fix.** Assign a durable QC owner with quarterly accountability. Reinstate the cadence. Audit the set for the drift that accumulated; fix or noindex pages that ship below the threshold. + +**Prevention.** The QC owner is named in the program's planning doc and renewed annually. The dashboard that tracks cohort metrics has an actual owner who reviews it monthly. The threshold is treated as enforced, not aspirational. + +--- + +## The pattern across all failures + +Most pSEO failures are designed-in. They were predictable from the program's launch shape. The five-criterion check, the schema-as-product principle, the QC budget, the refresh cadence, the link architecture: each one shipped or did not at design time. The set's eventual success or decay was largely determined before the first page generated. + +The discipline is upstream. Hold the line at design time; the operational discipline at scale becomes manageable. Skip the design discipline; the program produces filler at scale and gets penalized. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md b/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md new file mode 100644 index 0000000..8d28d56 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md @@ -0,0 +1,115 @@ +# Crawl budget management + +Sitemap segmentation, noindex on thin pages, canonicalization on duplicates, crawl rate monitoring, pruning criteria. + +Search engines have crawl budgets. Large pSEO sets can exhaust them. Crawl budget management is the discipline that keeps the set crawlable as it scales past 10,000+ pages. + +--- + +## Sitemap segmentation + +A 100,000-page sitemap is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each. + +**Segmentation by category.** One sitemap per top-level category. Crawlers prioritize sitemaps differently; segmentation helps the crawler prioritize active categories over dormant ones. + +**Segmentation by recency.** A "recent" sitemap surfaces pages generated in the last 30 days. Crawlers find new content faster; existing content remains crawlable through category sitemaps. + +**Segmentation by update frequency.** A "frequently-updated" sitemap surfaces pages whose volatile fields refresh weekly or daily. Crawlers re-crawl these pages on a tighter cadence. + +**Sitemap index.** A parent sitemap-of-sitemaps points to all segmented sitemaps. The index is what gets submitted to Search Console; the segments handle the actual page lists. + +**Sitemap size limits.** 50,000 URLs per sitemap is the hard limit. 10,000 to 25,000 per segmented sitemap is the typical practical size; smaller is fine for niche categories, larger is fine for high-volume categories. + +--- + +## Noindex on thin pages + +Pages with insufficient data should noindex rather than ship as bait. + +**The discipline.** Pages that fail the schema's required-field threshold do not get a public URL. They sit in the system as drafts until their data populates. + +**Why noindex matters.** Thin pages drag down the entire set's quality signal. Search engines and AI engines both apply set-level quality scoring; a set with 10,000 thin pages and 90,000 substantive pages scores worse than a set with just the 90,000 substantive pages, even though the absolute page count is lower. + +**Noindex implementation patterns.** + +- The thin pages render with a `noindex` meta tag in the head. +- The thin pages are excluded from the sitemap. +- The thin pages are not linked from any other page in the set. + +**The "we'll fix it later" trap.** Teams ship thin pages with `index, follow` and plan to backfill data later. The data backfill rarely happens; the thin pages accumulate; the set's quality signal degrades over time. + +--- + +## Canonical handling + +Comparison pages and other pivot patterns produce duplicate-content risks. + +**The X-vs-Y pattern.** A page comparing X to Y often has an inverse page comparing Y to X. The two pages cover the same content from different orderings. Canonicalize one to the other. + +**Canonical decision.** Pick the canonical based on search volume, alphabetical order, or category hierarchy. The choice itself matters less than picking one consistently. + +**Other pivot patterns.** + +- **Filter pivots.** "Homes in Denver under $500k" and "Homes under $500k in Denver" should canonicalize to one. +- **Sort pivots.** "Top hotels in Paris by rating" and "Top hotels in Paris by price" might be distinct enough to live separately, or might canonicalize depending on the user-intent overlap. +- **Date pivots.** "Best [thing] for 2025" and "Best [thing] for 2026" usually live separately because the content genuinely differs by year; canonicalization would lose the time-relevance signal. + +**The discipline.** Canonical decisions are designed at template time, not retroactively. The template either generates canonical-pair URLs (and chooses one as canonical from the start) or it does not generate the duplicate at all. + +--- + +## Crawl rate monitoring + +Search engines publish crawl statistics. Monitor them. + +**Google Search Console crawl stats.** Pages crawled per day, average response time, crawl request distribution by category. Monitor monthly; investigate drops or plateaus. + +**Crawl rate plateauing while page count grows.** The set is hitting crawl budget limits. The fix is not "publish more pages." The fix is: + +- Noindex thin pages to remove low-value crawl targets +- Improve internal linking so crawlers prioritize the substantive pages +- Segment sitemaps so the crawler can prioritize active categories +- Reduce server response time so crawlers can crawl more in the same budget + +**Crawl rate dropping unexpectedly.** Investigate. Common causes: server errors that the crawler is encountering, robots.txt changes that excluded important paths, sitemap submissions that broke, large-scale URL pattern changes without redirects. + +--- + +## Pruning criteria + +Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. + +**The 6-month checkpoint.** A page that has been in the set for 6+ months and has earned zero impressions in Search Console is dead weight. The fix is not "wait longer." + +**Pruning options.** + +- **Noindex.** The page stays accessible to direct visitors but is removed from the search index. Reversible if the page later starts earning impressions. +- **410 Gone.** The page is removed entirely; the URL returns 410. Permanent; appropriate for genuinely obsolete content. +- **301 Redirect.** The page redirects to a more-relevant alternative. Appropriate when the user's intent for the dead page can be served by an alternative page that still exists. + +**The 12-month and 24-month checkpoints.** Pages that have not earned traffic by month 12 should be reviewed for noindex or removal; pages that have not earned traffic by month 24 should be removed unless there is a specific strategic reason to keep them. + +**Why pruning matters.** Dead pages waste crawl budget. Crawlers visit them, find nothing useful, and the set's average quality signal degrades. Pruning concentrates the set's PageRank on the pages that earn traffic. + +--- + +## When the set is too large for the budget + +Symptoms: + +- Crawl rate is permanently below the page count's natural crawl demand +- New pages take weeks or months to get indexed +- Existing pages drop out of the index unexpectedly +- The site's overall ranking is degrading despite the set being substantively unchanged + +The diagnosis is usually crawl budget exhaustion. The fix is set reduction (prune to the substantive pages), set restructuring (split into multiple subdomains or sites if appropriate), or technical optimization (server response time, sitemap discipline). + +The temptation is to publish more pages to "catch up" with traffic targets. The temptation is wrong. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## Methodology vs implementation + +The principles above are methodology: which pages to noindex, when to canonicalize, how to segment sitemaps, how to read crawl stats. + +The specific implementation (the framework's noindex meta tag pattern, the sitemap generation library, the canonical link helpers, the deployment-time crawl-test integration) is stack-specific. Each team implements crawl budget management within their own stack's tooling; the methodology applies regardless of the implementation choice. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md new file mode 100644 index 0000000..e6fa193 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md @@ -0,0 +1,104 @@ +# Data source identification patterns + +First-party, licensed, public, expert-curated, synthesized. Defensibility analysis for each pattern. + +The data source IS the pSEO program. A weak data source produces a weak set regardless of template quality, internal linking, or QC discipline. A strong data source produces durable traffic that compounds across years. + +--- + +## Pattern 1: first-party data + +Data the team owns because the business produced it. + +**Sources.** Customer transactions, content database, user-generated content, support ticket history, internal product analytics, sales call records, customer feedback databases. + +**Defensibility.** Maximum. Nobody else has the data. A competitor would have to build the same business and accumulate the same usage history to replicate. + +**Examples.** Glassdoor's employee reviews (built by getting employees to submit). Yelp's restaurant ratings (built by getting users to rate). TripAdvisor's traveler reviews (built by getting travelers to write). Reddit's discussion threads (built by getting users to post). + +**Watchouts.** Privacy and terms-of-service compliance. User-generated content used for pSEO needs explicit consent in the original collection terms; retrofitting consent is not legal in most jurisdictions. PII in pSEO pages is a separate liability. + +**The "moat compounds over time" effect.** First-party data sources get stronger as the business runs longer. A 10-year-old review database is more defensible than a 2-year-old one with the same volume because the time-series depth itself becomes valuable. + +--- + +## Pattern 2: licensed datasets + +Data acquired through commercial licensing. + +**Sources.** Industry databases (real estate MLS, automotive VIN databases, sports statistics feeds), regulatory data (SEC filings, government statistics), third-party content licenses (medical content, legal precedent). + +**Defensibility.** Medium to high. Defensibility depends on license exclusivity and integration depth. An exclusive license is a moat; a non-exclusive license that anyone can also buy is not. + +**Examples.** Zillow's MLS partnerships (licensed feeds with depth integration). Sportradar customers building stats sites. Bloomberg Terminal customers building financial content. Real estate brokerages with regional MLS access. + +**Watchouts.** License costs scale with usage; the unit economics need to work at scale. License terms typically restrict redistribution, which can complicate pSEO scaling (the data can power the pSEO pages but cannot be exported as a downloadable dataset). + +--- + +## Pattern 3: aggregated public data + +Data scraped, cleaned, enriched from public sources. + +**Sources.** Open government data, public web pages, academic research, public APIs. + +**Defensibility.** Low to medium. Anyone can scrape the same sources; the defensibility comes from the cleaning and enrichment work. If the cleaning is shallow, the defensibility is none. + +**Examples.** Sites built on government statistics (census data, BLS data). Sites built on academic research summaries. Sites built on public company filings (EDGAR data plus enrichment). + +**Watchouts.** Legality is jurisdictional and often gray. robots.txt compliance, terms-of-service review, copyright considerations, anti-circumvention rules in some jurisdictions. The legal review is mandatory, not optional, even when the data is "public." + +**The "scraped Wikipedia plus AI rewrite" anti-pattern.** The lowest-effort form of this category. The data is not really enriched (AI rewrite of public encyclopedia entries adds no defensible value). The pSEO sets built on this pattern are the ones that get penalized first when algorithm updates run. + +--- + +## Pattern 4: expert-curated content + +Data produced by hired experts who populate the dataset by hand. + +**Sources.** Expert-written reviews, expert-curated lists, professionally-tested products, professionally-evaluated services, professional translations. + +**Defensibility.** High. The defensibility is in the curation cost. A competitor would have to hire and pay the same experts for the same time to replicate. + +**Examples.** Wirecutter's product testing (experts test products in lab conditions). Consumer Reports' product reviews. Edmunds' car reviews. Specialty publications with paid expert contributors. + +**Watchouts.** Slow to build. The set scales at the speed of expert capacity, not at the speed of automated generation. Budget reflects the headcount, not the engineering effort. + +**The combination pattern.** Expert-curated content often combines with structured data (the expert reviews a car; the dataset captures the expert's score plus structured specifications) to produce pages with both narrative depth and queryable structure. + +--- + +## Pattern 5: synthesized data + +Data produced by combining multiple sources into a unique view. + +**Sources.** Multi-source pipelines that produce derived analyses unavailable from any single source. + +**Defensibility.** Medium to high. Defensibility comes from the synthesis logic and the ongoing pipeline maintenance. + +**Examples.** "Neighborhoods times schools times prices" combining three datasets into a comparison view. "Companies times salaries times employee reviews" combining three sources into a candidate-decision view. Aggregator pages that show "best X for Y use case" combining multiple product databases with use-case classification. + +**Watchouts.** The synthesis logic is the moat, not the underlying sources. Changes to source schemas break the pipelines. The pSEO program inherits the operational fragility of multi-source pipelines. + +--- + +## The defensibility test + +For each candidate data source, walk this question: would a competitor be able to replicate this source within 6 months at reasonable cost? + +- **Yes, easily.** No moat. Pursue editorial content instead, or invest in expert curation to build a moat. +- **Yes, with effort.** Partial moat. The first-mover advantage matters; ship before competitors. +- **No, requires major investment.** Real moat. pSEO compounds. +- **No, requires assets the competitor cannot acquire.** Strongest moat. The pSEO program becomes a long-term competitive advantage. + +--- + +## Combining patterns + +The strongest pSEO programs combine multiple patterns. + +- First-party data plus licensed data (Glassdoor: user reviews plus salary licenses) +- Licensed data plus expert curation (Wirecutter: licensed product databases plus expert testing) +- First-party data plus synthesized data (Yelp: user ratings synthesized with location data and external attributes) + +Single-pattern programs are simpler to ship but easier to replicate. Multi-pattern programs are harder to build and harder to copy. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md new file mode 100644 index 0000000..6c4d441 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md @@ -0,0 +1,116 @@ +# Internal linking at scale + +Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. + +The internal-link graph is half the program; the data is the other half. A well-linked pSEO set distributes ranking signal across all pages and compounds. A poorly-linked set has hub pages ranking and child pages orphaned. + +--- + +## Hub-and-spoke architecture + +The standard pSEO link topology. + +**Hub pages.** Parent-level pages that aggregate the children. "Homes for sale in Denver" is a hub for the neighborhoods; "Software engineer salaries" is a hub for the company-specific salary pages; "Hotels in [city]" is a hub for individual hotel pages. + +**Hub-level discipline.** + +- Hub pages are linked from main site navigation, not just from sitemaps. Crawlers reach hubs first and traverse to children from there. +- Hub pages link to all children in the category. The hub's body or a paginated listing exposes the full set. +- Hub pages are not just link aggregators; they have their own content (category overview, comparison tables, top-of-category aggregates) that earns ranking on its own. + +**Spoke pages.** The individual records. Each spoke links up to the hub and laterally to siblings. + +--- + +## Sibling linking + +Each page links to 5 to 15 related sibling pages. + +**The pattern.** The sibling-link section of the template renders 5 to 15 related records computed from cross-record fields in the schema. Most-similar-by-attribute, similar-price-range, similar-features, geographic neighbors. + +**Why sibling linking matters.** Without it, the link graph is a star (hub to spokes only). PageRank concentrates at the hub; spokes get minimal flow. With sibling linking, the graph is dense; PageRank distributes across the set. + +**Bidirectional linking.** Sibling links go both directions. If A links to B as a sibling, B should link to A. Asymmetric sibling linking creates ranking dead ends. + +**Avoiding the "everyone links to everyone" trap.** Every page linking to every other page is a complete graph; anchor text relevance dilutes; the link graph reads as algorithmic rather than semantically meaningful. The 5 to 15 sibling-link cap keeps each page's outbound graph navigable and signal-dense. + +--- + +## Reverse-direction (bottom-up) linking + +Spoke pages link UP to hub. + +**The first-200-words pattern.** The spoke page's introduction includes a contextual link up to the hub: "This page covers [specific record]. For the broader [category] overview, see [hub page]." + +**The closing pattern.** The spoke page's closing includes a link back to the hub or to the next-most-relevant sibling, giving readers a navigation path back to broader content. + +**Why bottom-up matters.** Without it, the hub does not compound. The spokes inherit traffic from their long-tail queries; without bottom-up links, that traffic does not flow back to lift the hub. + +--- + +## Anchor text variation + +Avoid every page using the same anchor text. + +**The principle.** Anchor text is the signal that tells search engines what the linked-to page is about. Identical anchor text across thousands of links to the same page reads as manipulation; varied anchor text reads as natural authority. + +**Variation patterns for pSEO.** + +- **Record-name variation.** "View [neighborhood name]" / "[neighborhood name] homes for sale" / "Browse [neighborhood name] listings" / "[neighborhood name] guide" used across different siblings linking to the same record. +- **Descriptive variation.** Anchor text that describes the linked page's distinctive attribute. "Affordable [neighborhood]" / "Top-rated [neighborhood]" / "Family-friendly [neighborhood]" computed from the target record's attributes. +- **Context-driven variation.** The anchor text shifts based on what the linking page is about. A page about prices uses price-relevant anchor text; a page about schools uses school-relevant anchor text. + +**Anti-pattern.** Every sibling link uses "[Record name]" as the anchor. Easy to ship at scale, signals manipulation, dilutes the page's anchor profile. + +--- + +## Crawl-friendly architecture + +Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +**Sitemap segmentation.** A pSEO set with 50,000 child pages does not put all 50,000 in a single sitemap. Segment by category, by recency, by data freshness. Crawlers process segmented sitemaps more reliably. + +**Sitemap-only access is not enough.** A child page only reachable via sitemap, with no other page linking to it, is a partial orphan. Crawlers may visit it; the page will struggle to compound ranking signal because no in-page link votes for it. + +**The orphan check.** Pages with zero inbound internal links besides the sitemap are orphans. Audit quarterly; surface in QC. The fix: add the page to the hub's listing, add it to sibling sets it should belong to, expose it through breadcrumb navigation. + +--- + +## The PageRank flow principle + +Internal linking is what makes pSEO sets compound. + +**The pattern that compounds.** Hub linked from main nav (high PageRank concentration). Hub links to all children (PageRank distributes). Children link laterally to siblings (PageRank circulates within the set). Children link back up to hub (PageRank reinforces). + +**The pattern that does not compound.** Hub linked from main nav. Hub links to children. Children do not link to siblings, do not link back to hub. PageRank flows hub-to-child but does not circulate; child pages slowly accumulate independent ranking signal but never compound. + +**The auditable signal.** Average internal-links-in per page. The set's average should be 8 to 20 inbound internal links per page. Below 5, the set is under-linked and orphans dominate. Above 30, the set is link-dense and anchor signal dilutes. + +--- + +## Linking inventory + +Maintain an inventory of every internal link in the pSEO set. + +**Inventory format.** A queryable dataset (typically a database table or analytics schema) tracking source page, target page, anchor text, link slot (breadcrumb / hub / sibling / related-record / related-content), link direction, last-validated date. + +**Why inventory matters.** + +- Quarterly audits run queries against the inventory: orphan check, sibling symmetry check, anchor diversity check, broken-link check. +- Template changes that affect linking (slot adjustments, anchor pattern changes) can be analyzed against the inventory before shipping. +- Pruning decisions reference the inventory: "if we noindex these 200 pages, what siblings lose links and need their slots refilled?" + +**The "no inventory" failure.** Without inventory, audits become "crawl the site each time," which is slow and produces inconsistent results. The inventory turns audit into a query operation. + +--- + +## When linking architecture is broken + +Symptoms: + +- Hub pages rank, child pages do not (under-linked spokes; add sibling linking) +- Specific category cluster does not rank as well as siblings (the category's internal links are sparse; investigate) +- Crawl rate plateaus while page count grows (link graph cannot absorb new pages; sitemap and link slots need restructuring) +- Algorithm update hits child pages disproportionately (children read as orphans without hub-and-spoke reinforcement) + +The fix is rarely "more pages." The fix is usually "better link graph through the existing pages." Internal linking is the structural multiplier. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md new file mode 100644 index 0000000..c108409 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md @@ -0,0 +1,126 @@ +# Quality control at scale + +Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. The discipline that distinguishes durable pSEO from penalty-bait. + +Auditing all 100,000 pages individually is infeasible. Quality control at scale is sampling discipline plus automated checks plus failure thresholds plus cohort tracking. Without it, pSEO sets degrade silently until algorithm updates expose the rot. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle, balanced across data shape. + +**Stratified sampling.** Not "the latest 50 pages" or "the top-traffic 50 pages." A stratified sample exposes problems specific to particular data shapes. + +Stratification dimensions: + +- **Sparse vs dense data.** Sample some records with minimum-required fields; sample some with most-fields-populated. +- **Recent vs old.** Sample some pages generated in the last 30 days; sample some generated 12+ months ago. +- **Popular vs niche categories.** Sample some pages from high-traffic parent categories; sample some from low-traffic ones. +- **Different cohort versions.** If the template has shipped revisions, sample some pages from each cohort. + +**Sample size by set size.** + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +**Cycle frequency.** Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks + +Run on every page on a cadence; surface failures as a queue. + +**Heading-structure check.** Validates H1 exists once, H2s are in order, no orphan H3s, no H2-H3-H4 cascades that nobody scrolls. + +**Schema-validity check.** Validates JSON-LD against the page's intended schema type; flags missing required fields, type mismatches, malformed structured data. + +**Internal-link-count check.** Flags pages with fewer than 10 internal links (under-linked) or more than 50 (link-dense, anchor-signal-diluting). + +**Word-count threshold check.** Flags pages below the template's minimum (typically 300 to 500 words depending on category). Pages below the threshold either need data backfill or should sit as drafts. + +**Duplicate-content check.** Hash similarity across the set; flags pages with >80% content overlap with another page in the set. Common cause: comparison pages where X-vs-Y duplicates Y-vs-X without canonicalization. + +**Broken-link check.** Crawl outbound and internal links; flag 404s and 5xx responses. Ages quickly without the check; cluster pieces that linked to deleted records become orphan-link generators. + +**Schema-population-rate check.** For each optional schema field, the percentage of pages that populate it. Flag fields with population rates below 50%; these usually need either to be required, dropped, or backfilled. + +--- + +## Manual review checklist + +For sampled pages, the human review covers what automation misses. + +**Above-the-fold answer quality.** Read the first 200 words. Does it answer the user's likely query? Is the language specific to this record or templated boilerplate? + +**Distinctive vs templated.** Compare the page to two siblings. Could you tell them apart on substance, not just on the names? If they read identically, the template lacks variable density or the data is too sparse to differentiate. + +**Citation-readiness.** Would an AI engine cite this page for the user's query? Specifically: is there a self-contained answer paragraph, are statistics with sources present, is FAQPage or Article schema marked correctly? + +**User-intent satisfaction.** If a real user landed on this page from the target SERP, would they stay or bounce? Bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +**Off-brand or off-tone signals.** Does the page read consistently with the brand voice? Templated pSEO tends to drift toward generic neutral voice; the brand voice should still be present. + +--- + +## Failure thresholds + +If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. + +**The 5% threshold.** Empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +**What "halt" means.** New page generation stops. The template or data fix is shipped. The next sample audit confirms the fix improved the failure rate before generation resumes. + +**Why halt instead of "fix as you go."** Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +**The threshold is not negotiable.** "Just ship the next batch and we'll fix later" is the failure mode. The pattern produces pSEO sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. + +**Cohort cuts.** Pages from a given month, pages from a given template version, pages from a given data-source version. Track ranking, click-through rate, citation count (from AEO measurement), and engagement metrics by cohort. + +**Drift signals.** + +- **Cohort A pages rank top 10; cohort B pages rank position 30.** Template or data changed between cohorts; identify the change. +- **Cohort A pages get cited; cohort B pages do not.** Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- **Cohort A pages have stable engagement; cohort B pages have decaying engagement.** Cohort B may have a data freshness problem. + +**Why cohorts matter.** Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically; aggregate tracking misses it. + +--- + +## Team budget + +A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. A 100,000-page set requires 2 to 4 FTE. + +**Where the headcount goes.** + +- Sample audit cycles (monthly to quarterly) +- Automated check failure queue triage +- Manual review of sampled pages +- Template or data fixes when failures surface +- Cohort tracking analysis and investigation +- Refresh cycle execution (volatile-field refresh, template-version migration) + +**The "we'll get to QC later" failure.** Programs that ship without QC headcount budgeted typically degrade within 6 to 12 months. The set looks fine on launch day; the data drifts, the template ships untracked changes, the cohort gap widens, and by month 12 the algorithm update finds the rot. + +**The discipline.** Budget the QC headcount before generating the first page. If the budget cannot absorb 0.5+ FTE for ongoing QC, the program's scope is too large; reduce scope until QC fits. + +--- + +## When QC reveals the program is broken + +Sometimes the QC discipline reveals that the underlying program is wrong, not just that individual pages need fixes. Signals: + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole in that category; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. The sunk cost is real but smaller than the cost of continuing to generate filler. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md new file mode 100644 index 0000000..a402ea8 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md @@ -0,0 +1,100 @@ +# Refresh at scale + +Data refresh cadence, template versioning, cohort migration, pruning lifecycle. + +pSEO sets decay if not maintained. Refresh discipline is built into the program at design time; retrofitting refresh on a 50,000-page set that was not designed for it costs more than building it from the start. + +--- + +## Data refresh cadence + +Match the refresh cadence to the data's volatility and the query's freshness reward. + +**Volatile fields.** Daily to weekly refresh. Real estate listings, current prices, current availability, recent reviews, current ratings. The data feed updates daily; the pages update daily; the search and AI surfaces see fresh data. + +**Slow-changing fields.** Quarterly refresh. Population statistics, business categories, attribute classifications, neighborhood demographics. The data updates seasonally or annually; the refresh cycle aligns. + +**Static fields.** No refresh required. Geographic coordinates, founding years, fixed attributes. Set at record creation; tracked in the schema's update-tag system. + +**Mixed-cadence pages.** Most pSEO pages are mixed: some volatile fields, some slow-changing, some static. The refresh pipeline updates each field on its own cadence; the page renders the latest data on each request (or rebuilds when fields change). + +**The "refresh cadence wasn't designed in" failure.** A program ships with annual refresh as the plan. Six months in, the volatile fields are stale (prices moved, listings expired). The fix is expensive: retrofit a daily pipeline for fields that should have had one from launch. + +--- + +## Template version migration + +When the template improves, all existing pages need migration. + +**Why templates ship revisions.** AEO patterns evolve, SERP intent shifts, schema requirements update, brand voice tightens. Templates from 18 months ago may need significant updates to compete in the current search and AI environment. + +**Cohort-by-cohort migration.** Migrate one cohort at a time, monitor, then migrate the next. The cohort might be a category, a generation period, a data-density tier. The cohort approach surfaces problems specific to particular page shapes before they spread across the entire set. + +**Big-bang migration.** Migrate all pages at once. Higher risk; if the new template has a regression, the entire set degrades simultaneously. Sometimes the right call when the migration is small or the team can roll back fast; usually the wrong call for large changes. + +**Migration monitoring.** Each cohort post-migration is monitored for 30 days minimum: ranking changes, citation count changes, click-through rate changes, engagement metric changes. Negative trends pause the migration and surface the regression before it propagates. + +**Rollback discipline.** The template migration ships with a rollback path. If a cohort's metrics degrade post-migration, the cohort rolls back to the previous template while the regression is investigated. Without rollback discipline, a bad migration produces permanent damage. + +--- + +## Cohort migration patterns + +Three common patterns. + +**Category-based cohort migration.** Migrate one parent category at a time. Real estate: migrate Denver pages first, monitor 30 days, then migrate Seattle. The advantage: category-level metrics are clean; investigation is scoped. + +**Generation-period cohort migration.** Migrate the oldest cohort first (pages generated in year 1), then the next, then the next. The advantage: oldest pages have the most accumulated decay; migrating them first improves the set's average quality fastest. + +**Data-density cohort migration.** Migrate the dense-data pages first (most fields populated), then the medium, then the sparse. The advantage: dense pages have the most upside from template improvements; sparse pages may need data backfill before template migration earns gains. + +The right pattern depends on the migration's intent. AEO-focused migrations often prefer dense-data first. Algorithm-update recovery migrations often prefer category-based. Maintenance migrations often prefer generation-period. + +--- + +## Pruning lifecycle + +Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. + +**The 24-month checkpoint.** Standard cutoff. A page that has been indexed for 24+ months and has earned zero impressions in Search Console is dead weight. Pruning options: noindex, 410, or 301 redirect to a more-relevant alternative. + +**Earlier pruning for some categories.** Time-sensitive pages (annual "best of [year]" pages, event-specific pages, deal-specific pages) prune earlier. A "best of 2024" page generated in 2024 should be archived or pruned by mid-2026; the freshness signal has decayed. + +**Later pruning for stable categories.** Some categories support evergreen pages that earn traffic for decades. Geographic pages (neighborhoods, cities), historical reference pages, foundational definitional pages. The 24-month checkpoint is too aggressive for these; review case-by-case. + +**Pruning is hygiene, not failure.** Pruning a page that did not earn traffic is not abandoning the program; it is removing dead weight that drags the set's quality signal down. The set is healthier with 40,000 traffic-earning pages than with the same 40,000 plus 60,000 dead pages. + +--- + +## Set-level refresh + +Occasionally the entire set's template needs a refresh. + +**Triggers for set-level refresh.** + +- AEO patterns shifted significantly (the entire set needs better above-the-fold answers, FAQPage schema, or source citations) +- The dataset's underlying source changed schema (the new data exposes fields the old template did not render) +- User expectations evolved (the category's accepted page shape shifted; the set's pages now read as dated) +- An algorithm update affected the set disproportionately (the set's design needs to adapt to the new ranking signals) + +**Set-level refresh is a 6-month project.** Plan accordingly. The work includes template redesign, cohort-by-cohort migration, post-migration monitoring, and pruning of pages that the new template cannot improve. Underestimating the duration is the most common mistake. + +**The "do not refresh and let the set decay" anti-pattern.** Some teams treat the initial pSEO build as ship-and-forget. The set ranks for 12 to 18 months, then declines as competitors with refreshed sets pass it. The decline accelerates when an algorithm update finds the set's accumulated drift. Refresh is part of the program's ongoing cost; teams that do not budget for it should not start the program. + +--- + +## Refresh budget + +The ongoing refresh cost in headcount. + +**Volatile-field refresh.** Mostly automated (data pipelines pull new data into the schema). 0.1 to 0.5 FTE for pipeline maintenance and exception handling. + +**Slow-changing-field refresh.** Quarterly cycles. 0.2 to 0.5 FTE during cycles; lower between cycles. + +**Template version migration.** Project-based when migrations ship. 1 to 3 FTE for the duration of the migration; varies by set size and migration scope. + +**Pruning lifecycle.** Quarterly review of dead pages. 0.1 to 0.3 FTE. + +**Total ongoing refresh budget.** A 10,000-page set: roughly 0.5 FTE steady state plus migration projects when they ship. A 100,000-page set: 1 to 2 FTE steady state plus larger migration projects. + +The refresh budget is in addition to the QC budget. Programs that under-budget either degrade; programs that budget both produce durable traffic for years. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md new file mode 100644 index 0000000..563400f --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md @@ -0,0 +1,114 @@ +# Schema design patterns + +Field count, computed fields, cross-record fields, update tags, schema-as-product. The data shape that drives the template. + +The schema design here is the methodology layer: what shape the data takes, what fields earn their keep, what derivations add depth. Specific framework type signatures, ORM bindings, and database column choices are stack-specific implementation that varies by team. + +--- + +## Field count signals depth + +5 fields per record is thin. 15 to 20 is competent. 30+ is deep. + +**Why field count matters.** Field count determines what the template can render at depth versus what falls back to filler. A record with 5 fields can produce a 200-word page; a record with 30 fields can produce a 1,500-word page that reads as substantive across multiple sections. + +**The "thin schema" failure mode.** Teams design with 5 to 10 fields, ship, find pages reading as thin, then try to bolt on additional fields after the fact. Bolt-on fields rarely populate consistently across the existing dataset; the result is a half-thin set with a thin tail and a thicker head. + +**The "too-many-fields" trap.** 50+ fields per record where most are sparsely populated. The schema looks deep on paper but most fields are empty for most records. The template either renders empty sections (looks broken) or hides them (back to thin pages). Better to design 25 fields with 90% population than 50 fields with 30% population. + +--- + +## Required vs optional fields + +Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. + +**Required field discipline.** Define a minimum field-count threshold below which a record does not get a public page. The threshold ships in the schema validation; pages that fail validation sit as drafts until their data populates. + +**Optional field handling.** Each optional field has a render rule: if populated, render this section; if empty, hide this section or substitute a computed default. The render rules are part of the template, not afterthoughts. + +**The discipline.** A page with 25 of 30 optional fields populated is fine. A page with 3 of 30 should not ship; it produces filler content that drags the entire set's quality signal down. + +--- + +## Computed fields + +Derived from source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +**Common computed-field patterns.** + +- **Aggregations.** "Average price per square foot" computed from listing data; "median rating" computed from review data. +- **Derived classifications.** "Price tier" computed from price percentiles; "freshness tier" computed from data age. +- **Comparisons.** "Price vs neighborhood average" computed from the record's price and the parent category's average; "rating vs category average." +- **Trends.** "Price trend over 12 months" computed from time-series source data; "review-volume trend" from review-date stamps. +- **Rankings.** "Top 10 percent by [field]" computed across the set; "ranked by [field] within [category]." + +**Why computed fields earn their keep.** Each computed field adds a section to the template without requiring more source-data collection. The pipeline does the work; the template renders the result. This is how 15-field source data produces 30-field rendered pages. + +--- + +## Cross-record fields + +Fields that reference OTHER records in the set. Enable internal linking and comparison without manual curation. + +**Common cross-record patterns.** + +- **Most similar records.** "5 most similar neighborhoods" computed by attribute distance. +- **Parent and child references.** "Parent category" and "list of child records" computed from the hierarchy. +- **Sibling-comparison aggregates.** "Average price across sibling neighborhoods" computed across the parent's children. +- **Recommended-related.** "Users who viewed X also viewed Y" computed from analytics data (when first-party analytics is available). + +**How they power linking.** The sibling-link slot in the template renders from the "most similar records" cross-record field. Without this field, sibling linking becomes manual curation at scale, which is infeasible. + +--- + +## Update frequency tags + +Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). + +**Tag categories.** + +- **Static.** Set at record creation; rarely changes (geographic coordinates, neighborhood name, founding year). +- **Slow-changing.** Updates quarterly to annually (population statistics, business categories, attribute classifications). +- **Volatile.** Updates daily to weekly (current price, current availability, current rating, recent reviews). +- **Real-time.** Updates within minutes (live availability, dynamic pricing). Only relevant when the underlying data feed supports it. + +**Why tagging matters.** Without tags, refresh becomes "audit everything every cycle," which does not scale. With tags, refresh becomes "refresh volatile fields daily, slow-changing fields quarterly, static fields never," which scales. + +--- + +## Schema-as-product principle + +The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. + +**Schema versioning.** Major schema changes (renaming required fields, restructuring nested objects, changing field types) bump a version. Minor changes (adding optional fields, adding computed fields) do not. All schema changes are reviewed; breaking changes require migration plans. + +**Schema documentation.** Every field has a description, a source (where the data comes from), an update tag, a population rate (what percentage of records have this field), and example values. Documentation lives alongside the schema; it is not a separate doc that drifts. + +**Schema review.** Before adding fields or changing field types, the schema change goes through review with stakeholders who depend on the schema (template authors, QC reviewers, analytics consumers). Schema changes affect downstream rendering; review catches breakage before it ships. + +**Schema testing.** Validation rules ship as automated tests. Required fields, type constraints, value-range constraints, cross-field consistency checks. The tests run on every record in the dataset on a cadence; failures surface in the QC queue. + +--- + +## When the schema is wrong + +The schema is wrong when: + +- Required-field threshold produces too few publishable pages (relax the threshold or fix the data pipeline) +- Required-field threshold produces too many shallow pages (raise the threshold; let thin records sit as drafts) +- Optional fields are sparsely populated, dragging the average page quality down (drop them and refocus on dense fields) +- Computed fields are not actually used by the template (cut them; reduce schema bloat) +- Cross-record fields produce poor sibling matches (revise the similarity algorithm; the sibling-link section is doing real work for users) +- Update tags are wrong (refresh cadence is missing or over-shooting; recalibrate) + +The schema is iterated, not designed once. The "schema-as-product" principle makes that iteration safe by enforcing review and migration discipline; without it, every schema change risks breaking the template. + +--- + +## Methodology-level choices that stay in the public skill + +Field-count thresholds, computed-field patterns, cross-record patterns, update-tag categories, the schema-as-product principle. + +## Implementation choices that stay internal + +The specific schema language (TypeScript type definitions, dbt YAML, Sanity schema config, Prisma schema, etc.). The specific ORM or query layer. The specific validation framework. The specific deployment pipeline for schema migrations. These vary by stack. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md new file mode 100644 index 0000000..e56000d --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md @@ -0,0 +1,104 @@ +# Template design patterns + +Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. + +The template is the structure that data fills. Templates are designed at the methodology level here; specific framework implementations (rendering, slot composition, build-time generation versus on-demand rendering) are stack-specific and belong in internal team documentation. + +--- + +## Above-the-fold answer + +The first 200 words of the rendered page answer the user's specific query. + +**Why.** Search engines and AI engines both extract the top of the page disproportionately. Featured snippets pull from the first answer-shaped paragraph. AI engines extract the first 200 words as the canonical citation. The reader who lands on the page from a SERP decides within 5 seconds whether to stay; the answer needs to be visible. + +**The pattern.** Lead with the structured answer to the specific query: the price, the rating, the count, the comparison, the location, the recommendation. Follow with supporting details that justify or expand the answer. The opening is not a marketing introduction; it is the answer paragraph. + +**Anti-pattern.** "Welcome to our [page type] page. Below you will find information about [topic]." This intro reads as filler to crawlers and humans. Cut it; lead with the answer. + +--- + +## Variable density + +The template accommodates records with sparse fields and dense records gracefully. + +**Sparse-record handling.** Some records will have fewer fields populated. The template needs fallback patterns: hide sections that depend on missing fields, substitute computed defaults, surface "limited data available" rather than rendering empty headings. + +**Dense-record handling.** Some records will have many fields. The template needs progressive disclosure: collapse less-essential sections behind expandable headings, paginate long lists, prioritize the most-queried fields above the fold. + +**The shape principle.** Two pages from the same template can differ significantly in length and depth based on data density without either looking broken. A page with 20% of optional fields populated should still feel competent; a page with 95% should not feel overstuffed. + +--- + +## Heading hierarchy reflects data + +H2s and H3s map to data sections, not to template decoration. + +**The pattern.** The H2 set is the same across all pages in the template, but the content under each H2 reflects each page's specific data. "Overview," "Details," "Comparisons," "Related" might be the H2 set; what populates each varies per page. + +**Snippet-bait paragraphs at H2 level.** Each H2 has a 40 to 60 word answer paragraph immediately following it that summarizes that section's specific content. AI engines often quote these as multi-paragraph citations. + +**Anti-pattern.** Every page has a different H2 set because the template branches on data. The inconsistency confuses crawlers; the heading structure should be predictable across the set. + +--- + +## Schema markup as part of template + +Structured data renders machine-readable signals at scale. + +**The principle.** Pick the schema type that matches the page's content (Product, Article, LocalBusiness, FAQPage, BreadcrumbList, etc.). Embed the schema in the template; populate from the same data that renders the visible page. The schema is generated, not hand-written; the template ensures every page has it. + +**Validation discipline.** Run schema validation as an automated check on every generated page. Schema errors produce silent failures in search and AI surfaces; the validation catches them before publish. + +**Schema field coverage.** Populate every relevant schema field, not just the required ones. Optional schema fields (aggregateRating, additionalProperty, areaServed, etc.) signal depth at scale even when individual fields are not visibly rendered. + +--- + +## Internal linking placeholders + +The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. + +**Standard slot patterns.** + +- **Breadcrumb slot.** Path from home to current record. 3 to 4 levels typical. +- **Parent-category slot.** Link up to the hub page for the record's category. +- **Sibling slot.** 5 to 15 related sibling records. Computed from cross-record fields in the schema. +- **Related-record slot.** 3 to 5 records related across categories (different parent, similar attributes). +- **Related-content slot.** Editorial content related to the record (blog posts, guides, comparison editorials). + +**Total internal links per page.** 15 to 30 typical for a well-linked pSEO page. Below 10, the page is under-linked; above 50, the page reads as link-dense and dilutes anchor signal. + +--- + +## Distinctive value per page + +Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. + +**The test.** Generate three sample pages from the template using different records. Read all three. Can you tell them apart on substance, not just on the names? If the pages are interchangeable in everything but identifiers, the template is not generating distinct value. + +**The fix.** Surface the distinctive fields prominently. The fields that vary most across the set are the ones that justify the page's existence; those should be in the above-the-fold answer and in the H2 structure, not buried as "additional details." + +--- + +## Quality bar: the random-sample test + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. + +**The test sequence.** + +1. Pick 5 random records from the dataset. +2. Render them through the template. +3. Read each page as if you arrived from a search results page. +4. Score each page on three dimensions: does it answer the query, is the depth competitive with editorial content for the same query, would you trust this page as a source. + +If any of the 5 fails, the template needs work before scaling. The 5-page sample is the minimum viable QC; the cohort tracking discipline scales it across the program's lifetime. + +--- + +## Methodology-level design choices that stay in the public skill + +The principles above. Field-count heuristics, slot patterns, hierarchy choices, validation discipline, sample-test discipline. + +## Implementation choices that stay internal + +The framework rendering choice (build-time generation, server rendering, hybrid), the specific component composition pattern, the specific data-fetching layer, the deployment topology, the cache-invalidation strategy. These vary by stack and team and should not be prescribed at the methodology level. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md b/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md new file mode 100644 index 0000000..269fb79 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md @@ -0,0 +1,107 @@ +# When pSEO works decision + +The five-criterion framework for deciding whether programmatic SEO is the right answer, with worked examples across business types. + +The default answer is no. Most teams asking "should we do pSEO?" should hear "probably not." pSEO works only when all five criteria are met; failing any one is a hard signal to pursue editorial content or paid acquisition instead. + +--- + +## The five criteria + +### 1. Real underlying data + +A genuine structured data source with depth. 10+ fields per record, ideally 20+. First-party data, licensed datasets, expert-curated content, or synthesized multi-source data. Not scraped Wikipedia plus AI rewrite. + +**The test.** Could a competent reader extract genuine value from a single page in the set without reading any other page? If yes, the data is real. If no, the page is filler dressed as pSEO. + +### 2. Long-tail query volume justifies the effort + +The queries the program targets have meaningful aggregate volume. Individual queries can be small (10 to 100 monthly searches each) as long as the aggregate across the set is large. + +**The test.** Pull the top 20 candidate queries from keyword research. Sum their volumes. If the aggregate is below 5,000 monthly searches, pSEO probably does not justify the build. If above 50,000, the volume case is strong. + +**The illusion to watch for.** Long-tail keywords that look reasonable in keyword tools but are not actually searched by humans. Permutation keywords (every adjective times every noun) often have keyword-tool volume because the tools generate the data; the queries themselves are dead. + +### 3. User intent is queryable + +The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +**Queryable intent examples.** "Homes for sale in [neighborhood]" answered by listing data. "Software engineer salary at [company]" answered by salary data. "Restaurants near [landmark]" answered by location and rating data. + +**Non-queryable intent examples.** "Should I buy a house in [neighborhood]" requires personal financial judgment. "Why is Y better than X" requires editorial argumentation. "How do I choose [thing]" requires guidance. + +If the intent requires narrative, choose editorial. If the intent requires data presented well, choose pSEO. + +### 4. Update cadence aligns with query volatility + +Real estate listings update daily; the data feed updates daily; pSEO refresh aligns with the volatility. "Best [thing] for [year]" pages get stale annually; the refresh cadence is annual. + +**The test.** Match the data's update frequency to the query's volatility. If the data is static (geographic features, founding dates) and the queries are stable, low maintenance. If the data shifts daily and the queries reward freshness, daily refresh. + +**The trap.** Underestimating refresh effort at design time. A team designs for "annual refresh" because that feels reasonable, ships 50,000 pages, and discovers the refresh requires 2 FTE for 6 weeks every year. The cadence was real; the resourcing was not. + +### 5. Quality control is operationally feasible + +Headcount is budgeted to sample-audit the set, fix failures, and maintain quality. Not aspirationally; in actual hours allocated. + +**The rule of thumb.** A 10,000-page set requires roughly 0.5 to 1.0 FTE of ongoing quality control. A 100,000-page set requires 2 to 4 FTE. If the budget cannot absorb the QC headcount, the program will degrade within 12 months of launch. + +--- + +## Worked examples + +### Example 1: real estate listings (yes) + +A regional brokerage considering pSEO for "homes for sale in [neighborhood]" pages. + +- Real underlying data: yes. MLS feeds with 30+ fields per listing. +- Long-tail volume: yes. Each neighborhood query has 50 to 500 monthly searches; aggregate across 200 neighborhoods is significant. +- Queryable intent: yes. Buyers want listings. +- Update cadence: data updates hourly; pSEO refresh aligns daily; manageable. +- QC feasible: yes; the brokerage already has data ops headcount. + +Decision: yes. This is the canonical pSEO use case. + +### Example 2: SaaS comparison pages (maybe) + +A B2B SaaS considering "X vs Y" pages for every competitor combination. + +- Real underlying data: judgment call. If the comparison data is licensed (G2 reviews, feature databases) or first-party (the team's actual evaluation), yes. If the data is "scraped competitor websites plus AI summary," no. +- Long-tail volume: yes for major competitors; thin for niche ones. +- Queryable intent: yes for "X vs Y," but readers often want narrative judgment ("which is better for my use case") that data alone cannot supply. +- Update cadence: feature databases drift; quarterly refresh required. +- QC feasible: depends on team size. + +Decision: maybe, leaning yes if the team commits to combining structured comparison data with brief editorial analysis per page. Pure-data comparison pages tend to underperform pages that include the analytical layer. + +### Example 3: AI-generated city guides (no) + +A travel content site considering "things to do in [city]" pSEO across 5,000 cities. + +- Real underlying data: no. The plan is "AI-generate the content from public sources." Anyone can replicate. +- Long-tail volume: yes for major cities; thin for small ones. +- Queryable intent: yes, but the queries reward editorial depth (curation, recommendations, taste). +- Update cadence: events change weekly; the AI-generated approach cannot match. +- QC feasible: no; "AI-generate 5,000 pages" is the plan because QC was not budgeted. + +Decision: no. This is the pattern that produces penalty-bait. Either invest in real expert-curated data or pursue editorial content for the highest-volume cities only. + +### Example 4: enterprise B2B pricing pages (no) + +An enterprise B2B SaaS considering "pricing for [industry] companies" pSEO across 50 industries. + +- Real underlying data: no. Pricing for enterprise SaaS is typically negotiated; there is no structured data feed to render. +- Long-tail volume: yes for some industries. +- Queryable intent: no. Buyers want a sales conversation, not a price table. +- Update cadence: not relevant. +- QC feasible: not relevant. + +Decision: no. The intent is not queryable. Editorial content explaining the buying process plus a sales-led conversion path is the right approach, not pSEO. + +--- + +## When two of five criteria fail, walk away + +If two or more criteria fail, walk away from the pSEO idea. The temptation is to start anyway and "improve as you go," but pSEO programs that launch with weak foundations rarely recover. The data depth, the QC budget, and the refresh cadence are designed in or they are missing forever. + +If exactly one criterion fails, see whether a smaller scope resolves the failure. "5,000 pages across all cities" failing on data depth might become "500 pages across major cities with expert-curated depth" that succeeds on all five criteria. diff --git a/dist/pi/.agents/skills/qa-testing/SKILL.md b/dist/pi/.agents/skills/qa-testing/SKILL.md new file mode 100644 index 0000000..22a57a5 --- /dev/null +++ b/dist/pi/.agents/skills/qa-testing/SKILL.md @@ -0,0 +1,294 @@ +--- +name: qa-testing +description: "Run QA testing on a page, feature, or full site at one of three depth tiers (smoke, standard, full). Use this skill whenever the user asks to test a page, audit a site, check for bugs, verify a deploy, run a QA sweep, or review accessibility, performance, or SEO basics. Triggers on test, QA, audit, verify, check, is it working, does it look right, broken, 404, image not loading, post-deploy check, regression test. Also triggers proactively after any significant code change or new page launch where verification matters." +category: qa +catalog_summary: "Pre-launch QA, regression testing, cross-browser checks" +display_order: 1 +--- + +# QA Testing + +Verify that a page, feature, or site is working before declaring it shipped. Stack-agnostic. Console-snippet driven for speed. + +This skill is faster than `accessibility-audit` (which goes deeper on WCAG) and `performance-optimization` (which goes deeper on Core Web Vitals). Use this skill for general QA. Use the specialists for deep audits. + +--- + +## When to use + +- After every deploy (smoke test) +- After launching a new page or feature (standard audit) +- Before a major release (full release matrix) +- Investigating a "something looks off" report +- Pre-launch verification of a site or section + +## When NOT to use + +- Deep accessibility compliance work (use `accessibility-audit`) +- Deep performance investigation (use `performance-optimization`) +- Code review or debugging (use `code-review-web`) +- Initial site setup or technical SEO baseline (use `seo-technical`) + +--- + +## Required inputs + +- The page URL or site under test +- The tier of QA needed (smoke, standard, or full) +- Browser dev tools access +- Any specific concerns to check beyond the standard tier + +--- + +## The framework: 3 tiers + +QA scales with the stakes. Pick the tier that matches the context. + +| Tier | When to run | Time | Coverage | +|---|---|---|---| +| Smoke | After every deploy | 2 minutes | Critical signals only | +| Standard | New page or feature | 10 minutes | On-page basics, accessibility, structure | +| Full | Major release, pre-launch | 30+ minutes | Comprehensive across all dimensions | + +### Tier 1: Smoke test + +The 2-minute "did the deploy break anything obvious?" check. Run after every deploy. + +Console snippet (paste in browser dev tools): + +```javascript +const smoke = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + h1Count: document.querySelectorAll('h1').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { try { return JSON.parse(s.innerText)['@type'] } catch(e) { return 'invalid' } }), + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete || i.naturalWidth === 0).length, +}; +console.log(JSON.stringify(smoke, null, 2)); +``` + +**Pass criteria:** +- Title exists and is 30 to 60 characters +- Canonical points at the production domain (never staging or preview URLs) +- Exactly one H1 +- Zero missing alts +- Zero broken images +- Schema includes the expected types for the page + +If any of these fail, do not proceed with deeper testing until the smoke issue is fixed. + +### Tier 2: Standard page audit + +The 10-minute new-page-or-feature audit. Covers the on-page basics plus accessibility and structure. + +Console snippet: + +```javascript +const audit = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + metaDesc: document.querySelector('meta[name="description"]')?.content, + metaDescLen: document.querySelector('meta[name="description"]')?.content?.length, + ogImage: document.querySelector('meta[property="og:image"]')?.content, + ogTitle: document.querySelector('meta[property="og:title"]')?.content, + twitterCard: document.querySelector('meta[name="twitter:card"]')?.content, + h1Count: document.querySelectorAll('h1').length, + h1Text: document.querySelector('h1')?.innerText, + h2Count: document.querySelectorAll('h2').length, + h2s: [...document.querySelectorAll('h2')].map(h => h.innerText.trim().slice(0, 60)), + totalImages: document.querySelectorAll('img').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete || i.naturalWidth === 0).length, + externalLinksWithoutNoopener: [...document.querySelectorAll('a[target="_blank"]')] + .filter(a => !a.rel?.includes('noopener')).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { + try { + const d = JSON.parse(s.innerText); + return d['@graph'] ? d['@graph'].map(x => x['@type']) : d['@type']; + } catch(e) { return 'invalid' } + }), + hasSkipLink: !!document.querySelector('a[href^="#"]:first-of-type'), + pageLanguage: document.documentElement.lang || 'NOT SET', + hasFavicon: !!document.querySelector('link[rel*="icon"]'), +}; +console.log(JSON.stringify(audit, null, 2)); +``` + +**Pass criteria** (in addition to smoke): +- Meta description: 120 to 160 characters +- og:image, og:title, twitter:card present +- H2s present and descriptive +- All external links with `target="_blank"` have `rel="noopener"` +- Page language declared (`lang` attribute on `<html>`) +- Favicon present + +### Tier 3: Full release matrix + +The 30-minute pre-launch check. Cover all dimensions. + +| Dimension | Pass criteria | +|---|---| +| Smoke and standard | All pass | +| Accessibility (basic) | Run browser audit tool (e.g., Lighthouse), score above 90 | +| Performance (basic) | Lighthouse Performance score above 80, LCP under 2.5s, CLS under 0.1 | +| Mobile responsiveness | Tested at 375px, 768px, 1024px, 1440px | +| Cross-browser | Tested in Chrome, Safari, Firefox (and Edge if relevant audience) | +| Forms | All forms submit successfully and validate correctly | +| Internal links | No broken internal links (sample 20 random) | +| External links | All return 200 (sample 10) | +| Sitemap | Returns 200, lists canonical URLs only | +| robots.txt | Allows production crawlers, blocks staging if applicable | +| Security headers | HSTS, X-Frame-Options, X-Content-Type-Options present | +| HTTPS | All resources load over HTTPS, no mixed content | +| 404 handling | 404 pages return HTTP 404 (not soft 200) | +| Schema validation | All schema validates in Rich Results Test | +| Analytics | Events fire as expected on key user actions | +| Cache behavior | Cache headers appropriate for page type | + +For headers, run: + +```javascript +fetch(window.location.origin, { method: 'HEAD' }) + .then(r => { + const headers = {}; + for (const [k, v] of r.headers.entries()) headers[k] = v; + console.log(JSON.stringify(headers, null, 2)); + }); +``` + +Look for: `strict-transport-security`, `x-frame-options`, `x-content-type-options`. + +--- + +## Specific QA snippets + +### Image audit + +```javascript +const imgs = [...document.querySelectorAll('img')].map(i => ({ + src: i.src.split('/').pop().split('?')[0].slice(0, 60), + alt: i.alt || 'MISSING', + width: i.naturalWidth, + height: i.naturalHeight, + loaded: i.complete && i.naturalWidth > 0, +})); +console.table(imgs); +console.log({ + total: imgs.length, + broken: imgs.filter(i => !i.loaded).length, + noAlt: imgs.filter(i => i.alt === 'MISSING').length, +}); +``` + +### Heading hierarchy check + +```javascript +const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')].map(h => ({ + level: parseInt(h.tagName[1]), + text: h.innerText.trim().slice(0, 80), +})); +console.table(headings); + +// Check for skipped levels +const levels = headings.map(h => h.level); +let skipped = false; +for (let i = 1; i < levels.length; i++) { + if (levels[i] > levels[i-1] + 1) { + console.warn(`Skipped from H${levels[i-1]} to H${levels[i]}: "${headings[i].text}"`); + skipped = true; + } +} +if (!skipped) console.log('No skipped heading levels'); +``` + +### Contrast spot-check + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + const r = ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2); + return r + ':1 ' + (parseFloat(r) >= 4.5 ? 'PASS body' : parseFloat(r) >= 3 ? 'PASS large only' : 'FAIL'); +} + +// Examples +contrast('#FFFFFF', '#4B5563'); // body color check +contrast('#FFFFFF', '#9CA3AF'); // verify gray choices +``` + +### Form audit (per form) + +```javascript +[...document.querySelectorAll('form')].forEach((form, i) => { + const fields = [...form.querySelectorAll('input, select, textarea')].map(field => ({ + type: field.type || field.tagName.toLowerCase(), + name: field.name, + hasLabel: !!form.querySelector(`label[for="${field.id}"]`) || !!field.closest('label'), + required: field.required, + })); + console.log(`Form ${i + 1}:`); + console.table(fields); +}); +``` + +### External link audit + +```javascript +const externalLinks = [...document.querySelectorAll('a[href^="http"]')] + .filter(a => !a.href.includes(window.location.host)); +const issues = externalLinks.filter(a => + a.target === '_blank' && (!a.rel?.includes('noopener') || !a.rel?.includes('noreferrer')) +); +if (issues.length) { + console.warn(`${issues.length} external links missing noopener/noreferrer:`); + issues.forEach(a => console.warn(a.href)); +} else { + console.log(`All ${externalLinks.length} external links properly attributed`); +} +``` + +--- + +## Workflow + +1. **Pick the tier.** Smoke for routine deploys. Standard for new work. Full for releases. +2. **Run the snippet.** Paste the appropriate console snippet, review output. +3. **Note failures.** Each failure either gets fixed before ship or filed as a known issue. +4. **For Standard tier**, add: visual review at 375px, 768px, 1440px. Test the primary user flow. +5. **For Full tier**, add: cross-browser testing, Lighthouse audit, schema validation, security headers, 404 handling. +6. **Document.** Use the template in [`references/qa-report-template.md`](references/qa-report-template.md) for full audits. + +--- + +## Failure patterns + +- **Skipping smoke tests on "small" deploys.** Half of broken-production incidents start with a deploy that "looked safe." +- **Running snippets but not reading the output.** The console snippet is a tool. The judgment is reading what it returns. +- **Visual-only QA.** Eyeballing a page misses missing alt text, broken schema, missing canonical. Always run the snippet. +- **Single-browser testing.** Mobile Safari and Chrome differ enough to surprise you. Test at least Chrome and Safari. +- **No mobile QA.** The 375px viewport is where most users live. Test there or get burned later. +- **Pass-fail with no remediation.** A failed QA must produce a fix or a known-issue ticket. Failed QA that ships unfixed is process theater. + +--- + +## Output format + +For smoke tests: console output is the report. + +For standard and full audits: a markdown report at `qa-report-[date].md`. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md). + +--- + +## Reference files + +- [`references/qa-report-template.md`](references/qa-report-template.md) - Markdown report template for standard and full audits. diff --git a/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md b/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md new file mode 100644 index 0000000..91b7bdd --- /dev/null +++ b/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md @@ -0,0 +1,200 @@ +# QA Report: [Page or Site URL] + +**Date:** [YYYY-MM-DD] +**Tier:** [Smoke / Standard / Full] +**Tester:** [Name] +**Browser(s):** [List] +**Device(s):** [Desktop, mobile device, viewport width] + +--- + +## Summary + +**Overall:** [Pass / Pass with minor issues / Fail] + +[1 to 3 sentences. The headline finding. What works, what's broken, what to do.] + +**Critical issues found:** [N] +**Important issues found:** [N] +**Minor issues found:** [N] + +--- + +## Smoke check + +| Check | Pass | Notes | +|---|---|---| +| Title tag present and 30-60 chars | ☐ | | +| Canonical = production URL | ☐ | | +| Exactly one H1 | ☐ | | +| Zero missing image alts | ☐ | | +| Zero broken images | ☐ | | +| Schema present and valid | ☐ | | + +--- + +## Standard audit (if applicable) + +### Meta tags +| Field | Value | Pass | +|---|---|---| +| Title | | ☐ | +| Title length | | ☐ | +| Meta description | | ☐ | +| Meta description length | | ☐ | +| og:image | | ☐ | +| og:title | | ☐ | +| twitter:card | | ☐ | + +### Structure +| Check | Result | Pass | +|---|---|---| +| H1 text | | ☐ | +| H2 count | | ☐ | +| Skipped heading levels | | ☐ | +| Page language declared | | ☐ | +| Favicon present | | ☐ | + +### Images +| Check | Count | +|---|---| +| Total images | | +| Broken images | | +| Missing alt text | | + +### Links +| Check | Count | +|---|---| +| External links | | +| External missing `noopener` | | + +### Schema +[List schema types found and any validation issues] + +--- + +## Full release matrix (if applicable) + +### Accessibility +- [ ] Lighthouse Accessibility score above 90 (actual: __) +- [ ] No skipped heading levels +- [ ] All form fields have labels +- [ ] Skip link present +- [ ] Page operable by keyboard alone +- [ ] Focus indicators visible + +### Performance +- [ ] Lighthouse Performance score above 80 (actual: __) +- [ ] LCP under 2.5s (actual: __) +- [ ] CLS under 0.1 (actual: __) +- [ ] INP under 200ms (actual: __) + +### Mobile responsiveness +- [ ] 375px viewport: layout intact, no horizontal scroll +- [ ] 768px viewport: layout adapts cleanly +- [ ] 1024px viewport: desktop variant works +- [ ] 1440px viewport: max-width holds, no awkward stretch +- [ ] Tap targets minimum 44px + +### Cross-browser +- [ ] Chrome: tested +- [ ] Safari: tested +- [ ] Firefox: tested +- [ ] Edge: tested (if relevant audience) +- [ ] Mobile Safari: tested +- [ ] Mobile Chrome: tested + +### Forms +- [ ] All forms submit successfully +- [ ] Validation works as expected +- [ ] Error states display clearly +- [ ] Success states display clearly + +### Links +- [ ] No broken internal links (sample of 20 tested) +- [ ] No broken external links (sample of 10 tested) + +### Site infrastructure +- [ ] Sitemap returns 200 and lists canonical URLs +- [ ] robots.txt correct (allows production, blocks staging) +- [ ] HTTPS on all resources, no mixed content +- [ ] HSTS header present +- [ ] X-Frame-Options header present +- [ ] X-Content-Type-Options header present + +### 404 handling +- [ ] 404 pages return HTTP 404 (not 200) +- [ ] 404 page provides helpful navigation + +### Schema +- [ ] All schema validates in Rich Results Test +- [ ] Required properties filled +- [ ] No mixed signals (canonical vs sitemap vs internal links) + +### Analytics +- [ ] Page view fires correctly +- [ ] Key events fire on user actions +- [ ] No PII in event parameters + +### Cache behavior +- [ ] Cache headers appropriate for page type +- [ ] No stale content displayed +- [ ] Cache invalidation works after content updates + +--- + +## Critical issues + +[Things that block ship.] + +### 1. [Issue title] +- **Where:** [URL or component] +- **What:** [What's broken] +- **Impact:** [Who is affected] +- **Fix:** [Specific remediation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Things that should be fixed but might not block ship.] + +### 1. [Issue title] +- **Where:** +- **What:** +- **Impact:** +- **Fix:** + +--- + +## Minor issues + +[Polish items.] + +- [Issue] +- [Issue] +- [Issue] + +--- + +## Recommendations + +[Suggestions beyond fixing the identified issues.] + +- [Recommendation] +- [Recommendation] + +--- + +## Sign-off + +- [ ] All critical issues resolved +- [ ] Important issues resolved or have known-issue tickets +- [ ] Minor issues acknowledged + +**Approved for ship:** [Yes / No / Conditional] +**Approved by:** [Name] +**Date:** [YYYY-MM-DD] diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md b/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md new file mode 100644 index 0000000..d364cea --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md @@ -0,0 +1,283 @@ +--- +name: quiz-and-assessment-design +description: "Designing quizzes, personality assessments, and recommendation tools that segment users into actionable categories rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping, lead capture integration. Honest about clickbait-quiz (engagement only), vanity-result (entertaining, not useful), and actionable-segmentation (genuine categorization that drives next-step recommendations) patterns. Triggers on quiz, assessment, personality test, recommendation tool, scorecard, diagnostic, fit evaluator, what-type-of-X-are-you, persona quiz. Also triggers when an audience needs a categorization-driven lead magnet, when a vanity quiz is producing engagement but no qualified leads, or when an assessment is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing quizzes and assessments that produce actionable segmentation. Distinguishes clickbait-quiz (engagement only) from vanity-result (entertaining, not useful) from actionable-segmentation (genuine categorization that drives next-step recommendations)" +display_order: 3 +--- + +# Quiz and Assessment Design + +A senior growth practitioner's playbook for designing quizzes and assessments that produce actionable segmentation rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping. The discipline of building a quiz the audience actually uses to make a decision. + +Most quizzes on the web are clickbait. "What kind of pizza are you?" energy applied to brand-building, with results that flatter the taker but drive no specific next step. The quiz captures emails because the format implies fun; the leads are unqualified because the result told them nothing they could act on. + +The quizzes that work as compounding assets do something different. They categorize the taker into a defined segment with a specific recommendation matched to that segment. The taker comes away knowing what to do next, not just what they are. The brand becomes the source of the recommendation the audience acted on. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the quiz-specific methodology (scoring algorithms, result categorization, recommendation matching) lives here. + +The voice is the senior growth practitioner who has watched quizzes earn long-term subscribers and watched them produce engagement metrics with no downstream impact. Practical, opinionated about the difference between fun-quiz and decision-quiz, willing to call out when a quiz is the wrong format for the goal. + +When to use this skill: scoping a quiz or assessment for the first time, auditing a quiz that produces engagement but no qualified leads, designing the result categories that drive specific recommendations, or deciding which inputs warrant the lead-capture step. + +--- + +## What this skill covers + +This skill spans quiz and assessment design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology. Quizzes are one specific lead-magnet type. +- `calculator-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- **`quiz-and-assessment-design` (this skill)** is quiz-specific methodology (question architecture, scoring algorithms, result categorization, recommendation matching). +- `discovery-research-synthesis` is customer-research synthesis (this skill is user-facing assessment, not internal research). +- `landing-page-copy` is the quiz landing page (downstream of quiz design). + +The audience: growth marketers, product marketers, content marketers, agencies running quiz-based growth tooling for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); calculator design (covered by `calculator-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the quiz (handed off via `pm-spec-writing`). + +--- + +## The quiz/assessment decision: when this format earns investment + +Before designing the quiz, decide whether a quiz is the right tool for the audience and the goal. + +**Quizzes earn investment when:** + +- The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. +- The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation; 30 questions stops being a quiz and becomes a survey. +- The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation does not justify the format; the segment-recommendation mapping is the value. +- The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage; audiences who do not (technical buyers, enterprise) often see quizzes as gimmicks. + +**Quizzes do NOT earn investment when:** + +- The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. +- The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. +- The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. +- The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional; the format choice has to fit the audience. + +The decision is not "should we have a quiz"; it is "is the quiz the right next investment for this specific audience and decision." + +Detail in [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md). + +--- + +## Clickbait-quiz vs vanity-result vs actionable-segmentation + +The keystone framing. + +**Clickbait-quiz.** "What kind of pizza are you?" energy. Generates engagement (shares, comments, brief virality), segments nothing useful. Fun but not strategic. Cost: the engagement metric looks fine; the leads have no qualification signal because the quiz did not reveal anything actionable about them. + +**Vanity-result.** Elaborate-feeling result that flatters the taker but does not drive any specific next step. "You are an INTJ visionary entrepreneur" with a description that reads like horoscope, no actionable follow-up. Cost: the taker enjoyed the result, did not act on it, did not return. The quiz produced a moment of attention, not a relationship. + +**Actionable-segmentation.** Result places the taker into a defined category with a specific recommendation matched to that category. The result tells them what to DO next, not just what they ARE. The category and the recommendation are the value; the taker comes away with a next step. + +The litmus test. After taking the quiz, can a stranger in the target audience name the next thing they should do? Can they describe the recommendation matched to their result? If yes, the quiz is actionable-segmentation. If they got a flattering description with no clear next step, the quiz is vanity-result. If they got entertainment with no segmentation, the quiz is clickbait. + +--- + +## Question architecture + +The questions are the mechanism that produces the segmentation. Bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +**Question count.** Most effective quizzes use 5-10 questions. Fewer than 5 rarely produces meaningful segmentation; more than 12 stops feeling like a quiz and starts feeling like an interrogation. + +**Question types.** + +- **Multiple-choice (single-select).** The most common. Each option maps to a segment or scoring weight. +- **Multiple-select.** Useful when multiple attributes apply. Care needed; multi-select complicates scoring. +- **Slider or scale.** "On a scale of 1-5, how often do you..." Useful for intensity questions; less useful for categorical segmentation. +- **Yes/no.** Useful for binary qualifying questions; rarely produces nuanced segmentation alone. +- **Free text.** Avoid in quizzes. Free text breaks the scoring flow and adds friction. + +**Question ordering.** Start with engaging, low-friction questions. Save more revealing or sensitive questions for later when commitment has built. Demographic or qualifying questions belong at the end, not the start. + +**Question phrasing.** + +- Plain language. Avoid jargon. +- Specific situations the audience recognizes. +- Avoid leading questions ("How much do you struggle with X" presumes struggle). +- Avoid double-barreled questions ("How much do you value speed AND simplicity" mixes two dimensions). + +**Question-segment mapping.** Each question should contribute to the segmentation in a defined way. Questions that do not affect the result are filler; remove them. + +Detail in [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md). + +--- + +## Scoring algorithms + +The math that turns answers into a segment. + +**Pattern A: Direct mapping.** Each answer corresponds directly to a segment. The dominant answer choice determines the result. Simple, transparent, easy to explain. + +**Pattern B: Weighted scoring.** Each answer adds points to one or more segments. The highest-scoring segment wins. Allows for nuance; one answer can contribute to multiple segments. + +**Pattern C: Multi-dimensional.** The quiz produces scores across multiple axes (e.g., introvert/extrovert AND analytical/intuitive). The result combines the scores into a 2D or 3D segment. Common in personality assessments. + +**Pattern D: Branching logic.** The next question depends on the previous answer. Allows for adaptive questioning; complicates scoring. + +**Choice criteria.** + +- Direct mapping when the segments are well-defined and the questions clearly distinguish them. +- Weighted scoring when nuance matters and most answers contribute to multiple segments. +- Multi-dimensional when the segmentation is genuinely multi-axis (personality, fit-evaluation). +- Branching when later questions make sense only in the context of earlier answers. + +**Scoring transparency.** Some quizzes show the score during or after the quiz; others present only the segment. The choice depends on whether the score is meaningful to the user. Personality assessments benefit from showing dimensions; recommendation quizzes often do not. + +Detail in [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md). + +--- + +## Result categorization + +How many segments, named how, distinguishable from each other. + +**Segment count.** Most quizzes work well with 4-8 result categories. Fewer than 4 makes the categorization feel coarse; more than 8 makes individual segments feel under-developed. + +**Segment naming.** + +- Memorable. The taker should be able to describe their segment to a friend. +- Specific. "The Strategic Planner" beats "Type 3." +- Honest. Names should not flatter universally; some segments are more flattering than others, which is honest segmentation. +- Brand-voice consistent. The names should sound like the brand the quiz represents. + +**Segment distinguishability.** Each segment should be meaningfully different. If two segments have similar descriptions and similar recommendations, the segmentation is fake. + +**Segment balance.** The quiz should not always route 80 percent of takers to one segment. Balanced segmentation (each segment receives a meaningful share of takers) signals that the questions actually distinguish. + +Detail in [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md). + +--- + +## Result-to-recommendation mapping + +The action attached to each category. This is where the quiz earns its conversion. + +**The principle.** Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +**Mapping examples.** + +- B2B SaaS quiz: "Which CRM tier fits your team" maps each segment to a recommended plan. +- Content quiz: "What kind of marketer are you" maps each segment to a different content series matched to that maturity level. +- Onboarding quiz: "What is your readiness for X" maps each segment to a different onboarding path or resource. + +**The recommendation has to be real.** The brand should actually offer the recommended next step; the recommendation should match the segment specifically; the recommendation should be valuable to the segment. + +**Mapping discipline.** + +- Each segment has a distinct recommendation. No two segments share the same next step. +- Each recommendation is actionable. The taker can act on it without additional research. +- Each recommendation is valuable to that specific segment. Generic recommendations for one segment do not earn the segmentation. +- The recommendation is delivered in context of the result. Not buried 3 emails later. + +**The vanity-result failure.** Result describes the segment without a recommendation. "You are a Strategic Planner" with a description but no next step. The taker enjoys the segment, does nothing. + +**The actionable-segmentation win.** Result describes the segment, then says: "Strategic Planners benefit most from [specific resource or product or path]. Here is the next step." The taker has a specific action. + +Detail in [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md). + +--- + +## Lead capture integration + +When and where to ask for the email, with what value-add. + +**The principle.** Capture the email in exchange for the personalized result delivery, not in exchange for seeing the result at all. + +**Pattern A: Email after questions, before result.** "Enter your email to see your personalized result." Common; works when the perceived value of the result is high. Risk: lead-trap pattern if the result was already calculated and is being held hostage. + +**Pattern B: Email after result, for personalized delivery.** "See your result here. Want a PDF with personalized recommendations matched to your segment? Enter your email." Honest; the result is free, the additional value justifies the email. + +**Pattern C: Email integrated with optional features.** "See your result. Save this scenario, get notified when new content for your segment is available, or download a personalized resource." Gradual opt-in; less aggressive. + +**The value-add at lead capture.** What the user gets for their email matters. A personalized PDF report, a follow-up email series matched to their segment, a curated resource list specific to their result. Generic delivery (just sending the same result by email) does not justify the gate. + +**Conversion vs lead quality.** Pattern A converts higher; Pattern B and C produce higher lead quality. Pattern choice depends on what the program optimizes for. + +Detail in [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md). + +--- + +## Quiz anti-patterns + +Patterns that look like quizzes but degrade trust. + +**The clickbait-quiz.** Engagement-driven framing with no actionable segmentation. "What kind of marketer are you" with 4 personality types and no recommendations. + +**The vanity-result quiz.** Flattering descriptions for every segment; no honest segmentation; no specific recommendations. + +**The forced-result quiz.** Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +**The interrogation-quiz.** 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +**The leading-question quiz.** Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +**The black-box quiz.** No explanation of how the result was determined. The taker gets a label with no insight into why. + +**The no-recommendation quiz.** Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +**The mismatched-recommendation quiz.** Recommendation does not match the segment. Audience that catches the mismatch loses trust. + +Detail in [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-quiz-failures.md`](references/common-quiz-failures.md). + +- "Quiz gets shared widely; lead quality is poor." Clickbait pattern; the audience taking and sharing is not the audience the brand serves. +- "Engagement is high; downstream conversion is near zero." Vanity-result pattern; takers enjoyed the segment but had no next step. +- "Most takers route to the same segment." Question architecture not distinguishing; algorithm needs review. +- "Drop-off mid-quiz is high." Too many questions; or questions feel uncomfortable; or the value of finishing is not clear. +- "Segments feel similar." Distinguishability problem; segments need more divergent descriptions and recommendations. +- "Recommendations feel generic." Mapping problem; each segment needs a specific recommendation, not a default. +- "We cannot tell which segment converts best downstream." Attribution missing; segments need tracking through the funnel. +- "Audience comments that the result was wrong." Either question or scoring problem; the segments do not match audience self-perception. + +--- + +## The framework: 12 considerations for quiz and assessment design + +When designing or auditing a quiz, walk these 12 considerations. + +1. **The quiz decision.** Is a quiz the right format for this audience and decision, or would a comparison table or assessment-as-content serve better? +2. **Actionable-segmentation, not clickbait or vanity.** The result places the taker into a category with a specific recommendation. +3. **Question architecture sound.** 5-12 questions; each contributes to segmentation; phrased plainly without leading. +4. **Scoring algorithm fits the segmentation.** Direct mapping, weighted scoring, multi-dimensional, or branching as appropriate. +5. **Result categories distinguishable and balanced.** 4-8 segments; each meaningfully different; each receives a meaningful share of takers. +6. **Segment naming memorable and brand-consistent.** Names the taker can describe to a friend. +7. **Recommendations specific to each segment.** No two segments share the same recommendation; each recommendation is valuable to that segment. +8. **Lead capture honest.** Email exchange for personalized delivery, not for seeing the result. +9. **Result delivery in context.** Recommendation appears with the result, not buried 3 emails later. +10. **Drop-off measured.** Question-by-question drop-off tracked; questions that lose audience flagged for review. +11. **Lead quality measured by segment.** Downstream conversion tracked per segment; some segments may be more valuable than others. +12. **Audit cadence.** Periodic review of segment balance, recommendation alignment, and conversion-by-segment. + +The output of the framework is a quiz that segments the audience meaningfully, produces specific recommendations, and converts the segments into action. + +--- + +## Reference files + +- [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md) - When a quiz is the right tool for the audience and goal, and when a comparison table or other format would serve. +- [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md) - Question count, types, ordering, phrasing, and segment mapping discipline. +- [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md) - Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. +- [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md) - Segment count, naming, distinguishability, balance. +- [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md) - The action attached to each category. Mapping discipline and worked examples. +- [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md) - When and where to ask for the email. Pattern choices and tradeoffs. +- [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md) - The patterns that look like quizzes but degrade trust. +- [`references/clickbait-vs-actionable-distinctions.md`](references/clickbait-vs-actionable-distinctions.md) - Detailed treatment of the keystone framing with worked examples and counter-examples. +- [`references/common-quiz-failures.md`](references/common-quiz-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: quizzes earn engagement when they earn the next step + +The quizzes that work as compounding assets are the ones the audience acts on. Not shares. Not engagement metrics. Action. The taker runs the quiz, gets a segment with a matched recommendation, and does the recommendation. + +That is the bar. Below the bar are clickbait-quizzes (engagement without action) and vanity-results (flattery without action). Above the bar are actionable-segmentation tools that produce specific next steps the taker actually takes. + +The discipline is in the design choices. The questions that genuinely distinguish segments. The scoring algorithm that maps answers to meaningful categories. The recommendations that match each segment specifically. The result-delivery that surfaces the recommendation in context, not 3 emails later. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md new file mode 100644 index 0000000..43f8d87 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md @@ -0,0 +1,192 @@ +# Clickbait vs actionable distinctions + +Detailed treatment of the keystone framing with worked examples and counter-examples. The single distinction that separates quizzes that compound credibility from quizzes that produce engagement without action. + +--- + +## The three-state framing + +Three states a quiz can land in. Only one of them produces compounding value. + +**State 1: Clickbait.** The quiz exists primarily to generate engagement. "What kind of pizza are you?" energy. The result is fun but means nothing. No segmentation that maps to a decision. No recommendation. Engagement metrics look healthy; downstream metrics are zero. + +**State 2: Vanity-result.** The quiz produces a result that feels meaningful but does not drive action. "You are an INTJ visionary entrepreneur." The taker reads the description, may share it, does not act on it. The result is descriptive without being prescriptive. + +**State 3: Actionable-segmentation.** The quiz produces a result that includes a specific recommendation matched to that segment. The taker can act immediately on the recommendation. The result is both descriptive (this is who you are) and prescriptive (this is what to do next). + +The states are not always obvious from the outside. A quiz can look polished and still be vanity-result; a quiz can look simple and still be actionable-segmentation. The distinction is in the design, not the surface. + +--- + +## What separates the states + +The three differences that separate actionable-segmentation from the others. + +**Difference 1: The result includes a recommendation.** + +- Clickbait: result is a label or description. "You are a 'Strategic Visionary'." +- Vanity: result is an elaborate description. "You are a 'Strategic Visionary': big-picture thinker, comfortable with ambiguity, drawn to long-term impact..." +- Actionable: result is a description plus a recommendation. "You are a 'Strategic Visionary'. The next step that fits this profile: [specific resource, product, or path]." + +**Difference 2: The recommendation is specific to the segment.** + +- Clickbait: no recommendation, so the question does not apply. +- Vanity: every segment may get a similar generic next step ("read our blog"); the recommendation is decorative. +- Actionable: each segment gets a distinct recommendation matched to that segment specifically. + +**Difference 3: The recommendation is actionable today.** + +- Clickbait: no recommendation. +- Vanity: recommendation is aspirational ("consider whether you might be ready for X someday"). +- Actionable: recommendation is concrete and immediate ("start your trial here," "book a 30-minute call here," "download the playbook here"). + +The pattern. Clickbait has no recommendation. Vanity has decorative recommendation. Actionable has specific, matched, concrete recommendation. + +--- + +## Worked example: the same topic in three states + +A quiz on "what kind of marketer are you" treated three ways. + +**Clickbait version.** + +- 5 questions about content preferences and personality. +- Result: "You are 'The Storyteller'." Description: "Storytellers love narrative and connect deeply with their audience." +- Action: share the result. + +The taker enjoys the result, may share it, learns nothing actionable. The quiz produces engagement; the brand earns no qualified leads. + +**Vanity-result version.** + +- 8 questions about marketing approach, content, audience interaction. +- Result: "You are 'The Storyteller': a marketer who values narrative, audience connection, and emotional resonance. Storytellers thrive in brands that prioritize voice and depth..." +- Action: 3 paragraphs of description; soft CTA at the bottom: "Want more? Subscribe to our newsletter." + +The taker reads the elaborate description; may subscribe to the newsletter; does not take a specific action that converts. The quiz produces a moment of attention; the brand earns subscribers but no qualified leads. + +**Actionable-segmentation version.** + +- 7 questions about marketing approach, content, audience interaction, current tools, current challenges. +- Result: "You are 'The Storyteller'. Storytellers benefit most from our 4-part 'Brand Voice Workshop' series. Here is the first lesson; the next 3 arrive over the following week. Or, if you prefer, start with our 'Brand Voice Audit Template' [direct download]." +- Action: clear next step with two options matched to the segment's likely preference (sequence or self-serve). + +The taker gets a matched recommendation. The taker who wants the sequence opts in; the taker who wants the template downloads. Either way, action is taken; the brand earns a qualified lead. + +The same topic, three quizzes, three different outcomes. The actionable version compounds value; the others do not. + +--- + +## How to evaluate which state a quiz is in + +Diagnostic questions to apply to any quiz. + +**Question 1: Does the result include a specific recommendation?** + +- No: the quiz is clickbait or vanity. +- Yes: continue. + +**Question 2: Does each segment have a distinct recommendation, or do all segments share the same recommendation?** + +- All same: the quiz is forced-result; segmentation is decorative. +- Distinct: continue. + +**Question 3: Is the recommendation actionable today?** + +- No (aspirational, vague, "consider"): the quiz is vanity. +- Yes (specific link, button, or action): the quiz is actionable-segmentation. + +**Question 4: Does the recommendation match the segment specifically (not a generic offer)?** + +- No: the quiz is vanity with decorative recommendations. +- Yes: the quiz is actionable-segmentation. + +When all four questions get the right answer, the quiz is actionable-segmentation. When any fails, the quiz is somewhere between clickbait and vanity. + +--- + +## The compounding-value mechanism + +Why actionable-segmentation compounds and the others do not. + +**Actionable-segmentation compounds.** + +- The taker acts on the recommendation; the brand becomes the source of the action. +- The taker sees results from the action; the brand earns credit. +- The taker returns or refers; the brand's reach grows. +- The brand's recommendations become trusted; future quizzes earn more conversion. + +**Clickbait does not compound.** + +- The taker engages; the engagement does not convert. +- The brand's quiz is one of many forgotten amusements. +- No relationship deepens; no credibility builds. + +**Vanity does not compound.** + +- The taker enjoys; the enjoyment does not convert. +- The brand's quiz is one of many flattering distractions. +- The newsletter subscription (if any) decays without engagement. + +The compounding effect is the difference between quizzes that earn ongoing investment and quizzes that get retired. + +--- + +## Why teams build clickbait and vanity quizzes + +The patterns are easy to ship. Understanding why teams default to them helps teams choose actionable-segmentation instead. + +**Reason 1: Engagement metrics are easier to measure.** Conversion rate to email, share counts, time on page are all available immediately. Downstream conversion takes weeks or months to measure. Teams optimize what they measure. + +**Reason 2: Designing recommendations is hard.** Each segment needs a matched recommendation; the brand has to have the recommendations to give. Designing the segment-recommendation mapping is more work than designing the quiz alone. + +**Reason 3: Templates default to clickbait.** Many quiz-platform templates are designed for engagement, not for segmentation-driven action. Using a template often produces clickbait by default. + +**Reason 4: The vanity-result feels safer.** Flattering descriptions feel safer than honest segmentation; teams worry about "telling someone they are not a fit." Honest segmentation is harder but produces more trust. + +**Reason 5: Short-term thinking.** Engagement is immediate; downstream conversion is delayed. Teams optimizing for the next quarter default to engagement. + +The cure. Track downstream conversion as the primary metric. Build the recommendation portfolio before designing the quiz. Avoid templates that default to engagement. Practice honest segmentation. + +--- + +## Counter-example: when engagement is the goal + +Some quizzes are intentionally engagement-driven, and that is fine. + +**The legitimate engagement-quiz.** A consumer brand running a viral quiz to drive social shares and brand awareness. The goal is reach, not lead-capture. The quiz is intentionally entertainment. + +**The pattern.** Light, fun, shareable. No email gate. Result is shareable. Brand association is the value. + +**Why this is fine.** The brand has chosen reach as the metric. The quiz delivers on that goal. The quiz is not pretending to be something it is not. + +**The discipline.** Be honest about the goal. If the goal is engagement, do not pretend the quiz is for lead-capture; do not include a half-hearted email gate that produces neither real engagement nor real leads. + +The clickbait pattern fails when teams pretend it is something else. When teams own the engagement goal and design for it explicitly, the quiz can serve that goal well. + +--- + +## Common patterns by industry + +How clickbait, vanity, and actionable-segmentation play differently across industries. + +**Consumer brands.** Consumer brands often run engagement-quizzes successfully when the brand-association goal is the value. Lead-capture quizzes are harder; consumer audiences resist email gates more. + +**B2B SaaS.** B2B SaaS audiences expect actionable-segmentation. Clickbait and vanity are read as unprofessional. Actionable quizzes that route to specific plans or resources work well. + +**Education and creators.** Mixed. Some audiences engage with personality-style quizzes; some want practical assessment. The audience the brand serves determines which works. + +**Enterprise.** Enterprise audiences usually skip quizzes entirely. When they engage, only actionable-segmentation works; clickbait or vanity is read as unserious. + +**Ecommerce.** Recommendation quizzes ("which of our products fits you") work well as actionable-segmentation when the product portfolio supports it. + +The discipline. Match the quiz pattern to the audience expectation. Audiences that expect actionable-segmentation will reject anything else; audiences that engage with personality quizzes will not be converted by overly-formal segmentation. + +--- + +## Methodology-level choices that stay in the public skill + +The three-state framing. The three differences that separate actionable-segmentation from clickbait and vanity. The diagnostic questions. The compounding-value mechanism. Why teams default to clickbait and vanity. The counter-example for legitimate engagement-quizzes. Industry patterns. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. Specific recommendation portfolios. Specific tracking for downstream conversion per pattern. The team's measurement framework for engagement vs action. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md new file mode 100644 index 0000000..a350ba8 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md @@ -0,0 +1,187 @@ +# Common quiz failures + +8+ failure patterns with diagnoses and cures. The patterns that surface as "the quiz did not produce qualified leads" or "engagement is high but nothing converts" or "we cannot tell if the quiz worked." + +--- + +## "Quiz gets shared widely; lead quality is poor." + +**The diagnosis.** Clickbait pattern. The audience taking and sharing is not the audience the brand serves; the quiz attracts engagement from a broader audience than the brand's target. + +**The cure.** Tighten the quiz's audience-fit. Specific titles, specific topics, specific recommendations matched to the brand's actual buyers. Detail in `references/quiz-investment-criteria.md` (recommendation-portfolio precondition) and `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Engagement is high; downstream conversion is near zero." + +**The diagnosis.** Vanity-result pattern. Takers enjoyed the segment but had no next step. The quiz produced moments of attention without action. + +**The cure.** Add specific recommendations to each segment. Detail in `references/result-to-recommendation-mapping.md`. Each result page must include a clear next step. + +--- + +## "Most takers route to the same segment." + +**The diagnosis.** Question architecture not distinguishing. Either the questions do not actually capture differentiating signals, or the scoring algorithm biases toward one segment. + +**The cure.** Audit the question-segment mapping (`references/question-architecture-patterns.md`). Ensure each question contributes meaningfully to multiple segments. Audit the scoring weights for unintended bias. + +--- + +## "Drop-off mid-quiz is high." + +**The diagnosis.** Too many questions, or questions feel uncomfortable, or the value of finishing is not clear. + +**The cure.** Reduce question count if over 12. Audit questions for those that feel sensitive or repetitive. Add a progress indicator and a teaser of the result ("almost done; see your result next") to reduce late-stage drop-off. + +--- + +## "Segments feel similar." + +**The diagnosis.** Distinguishability problem. Either over-segmentation (more segments than the questions can support) or weak descriptions that do not differentiate. + +**The cure.** Reduce segment count to what the questions can distinguish (`references/result-categorization-patterns.md`). Strengthen the descriptions to make each segment meaningfully different. + +--- + +## "Recommendations feel generic." + +**The diagnosis.** Mapping problem. Each segment needs a specific recommendation, not a default. + +**The cure.** Audit the segment-to-recommendation mapping (`references/result-to-recommendation-mapping.md`). Verify each segment has a distinct, valuable, actionable recommendation. + +--- + +## "We cannot tell which segment converts best downstream." + +**The diagnosis.** Attribution missing. Segments need tracking through the funnel. + +**The cure.** Tag leads by segment at capture. Track downstream conversion per segment. The data informs which segments warrant continued investment and which segments may need different recommendations. + +--- + +## "Audience comments that the result was wrong." + +**The diagnosis.** Either question or scoring problem. The segments do not match audience self-perception. + +**The cure.** Persona testing. Have personas representing each segment take the quiz; verify each persona reaches the intended segment. Adjust questions or scoring weights to align. + +--- + +## "The quiz earns 5000 takers; the email list grows by 200." + +**The diagnosis.** Either the result is not perceived as valuable enough to opt in for additional value (Pattern B failure), or the email gate is for the result itself with no value-add (lead-trap risk). + +**The cure.** Design a substantive value-add for the email opt-in (PDF, sequence, resource). Make the value-add visible at the result. Detail in `references/lead-capture-integration-patterns.md`. + +--- + +## "We added a quiz; our other lead magnets stopped converting." + +**The diagnosis.** Cannibalization. The quiz absorbed the audience that previously converted via other magnets. + +**The cure.** This may not be a failure. If the quiz-sourced leads are higher quality than the previous magnets, the cannibalization is portfolio improvement. If not, the quiz may have replaced a working magnet with a worse one; audit and decide. + +--- + +## "Sales says quiz-sourced leads are low-fit." + +**The diagnosis.** Either the audience-fit at the quiz is wrong (the quiz attracts non-target audiences) or the recommendation-mapping routes audiences to wrong products. + +**The cure.** First, audit the audience-fit. If the quiz is attracting the wrong audience, tighten the targeting (title, topic, distribution channels). Second, audit the recommendation-mapping. If the audience-fit is right but the recommendation is wrong, fix the mapping. + +--- + +## "The quiz looks great; nobody completes it." + +**The diagnosis.** Either the topic does not engage the audience (audience-fit weak) or the question count is too high (drop-off too early). + +**The cure.** First, validate the topic with audience research. If the topic is right, audit the question count and question phrasing. + +--- + +## "Engagement was great at launch; conversion has dropped 40 percent over a year." + +**The diagnosis.** Decay. Recommendations have shifted; segments have evolved; references are stale. + +**The cure.** Audit and refresh. Update recommendations to match current portfolio; verify segments still describe the audience accurately; refresh any stale references in question phrasing or result descriptions. + +--- + +## "We made the quiz shorter; conversion went up but downstream conversion went down." + +**The diagnosis.** Question removal removed differentiating signals. The quiz now produces engagement faster but the segmentation is weaker. + +**The cure.** Restore the questions that contributed to segmentation. Speed-of-completion is a metric; segmentation quality is a separate metric. Optimize for the right one. + +--- + +## "The result page is fine; the email follow-up sequence converts terribly." + +**The diagnosis.** Sequence does not match the segment. Either the sequence is generic across segments, or the sequence does not deepen the matched recommendation. + +**The cure.** Design segment-specific sequences (or at least segment-specific opening emails). The sequence should extend the result's recommendation, not start over with generic content. + +--- + +## "We tried branching logic; the quiz felt confusing." + +**The diagnosis.** Branching added complexity without value. Different takers got different question sets; comparison across takers became hard. + +**The cure.** Revert to linear quiz unless branching is genuinely warranted. The simplicity often produces better outcomes. + +--- + +## "The quiz works on Chrome; it breaks on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The quiz was tested on the team's primary platform; the audience's actual devices were not covered. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use; the quiz has to work there. + +--- + +## "The recommendation links to a product we discontinued." + +**The diagnosis.** Maintenance lapse. The quiz's recommendation drifted out of sync with the brand's actual offering. + +**The cure.** Set a maintenance trigger: when products are discontinued or pricing changes, the quiz updates are part of the change. Quarterly review at minimum. + +--- + +## "Audiences take the quiz multiple times to get different results." + +**The diagnosis.** This is fine, often. Audiences exploring the segmentation may take it multiple times to understand how the algorithm works. Track unique users vs total completions. + +**The action.** Make sure the algorithm is stable enough that repeated takes with consistent answers produce consistent results. Inconsistency at this level signals algorithm issues. + +--- + +## "The quiz produces good leads; the sales team does not follow up." + +**The diagnosis.** Sequence or routing missing. Quiz-sourced leads should be tagged, routed to sales, and prioritized appropriately. + +**The cure.** Design the post-conversion flow. Calculator-sourced leads should be tagged with their segment, routed to the appropriate sales rep, and the sales rep should know which segment the lead represents. + +--- + +## The pattern across failures + +Most quiz failures fall into one of three patterns. + +**Pattern 1: The quiz does not deliver actionable segmentation.** Clickbait, vanity-result, no-recommendation, mismatched-recommendation. The fix is to add or correct the recommendations. + +**Pattern 2: The quiz does not match the audience.** Audience-fit weak, topic-audience mismatch, format-audience mismatch (e.g., quizzes for enterprise audiences who reject the format). The fix is to align the quiz to the audience the brand serves. + +**Pattern 3: The quiz decays.** Recommendations point to retired products; segments no longer describe the audience; references are stale. The fix is maintenance discipline. + +The metric pattern: quiz failures often look fine on engagement metrics. The signal is in lead quality, downstream conversion, and audience self-recognition. Programs that track only engagement keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that engagement alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md new file mode 100644 index 0000000..d10544c --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md @@ -0,0 +1,240 @@ +# Lead capture integration patterns + +When and where to ask for the email. Pattern choices and tradeoffs. The decision that affects both conversion and lead quality. + +The lead-capture integration is where the quiz earns its email. Done well, the audience opts in for personalized value; done poorly, the quiz becomes a lead-trap that the audience resents. + +--- + +## The capture-honest principle + +Capture the email in exchange for personalized result delivery, not in exchange for seeing the result at all. + +**The honest pattern.** The taker completes the quiz; the result is shown; an offer is made for additional value (PDF, follow-up sequence, saved scenario) that requires the email. + +**The dishonest pattern.** The taker completes the quiz; the result is calculated but hidden; the email is required to reveal it. This is the lead-trap pattern (described in `calculator-design`'s email-capture-decision-tree but applies equally to quizzes). + +--- + +## Pattern A: Email after questions, before result + +The taker completes the quiz; before the result is shown, an email gate appears. + +**How it works.** + +- The taker answers all questions. +- A form appears: "Enter your email to see your personalized result." +- The taker enters email; the result is shown. + +**Strengths.** + +- Highest conversion to email opt-in. +- Common pattern; audiences are familiar. + +**Weaknesses.** + +- Lead-trap pattern. The audience that recognizes the manipulation feels resentment. +- Lead quality is lower; some takers enter throwaway emails. +- Downstream conversion suffers because some leads are unqualified or actively annoyed. + +**When to use.** When the quiz is genuinely entertainment-driven and the audience expects the format (consumer brands sometimes work here). For B2B and considered purchases, this pattern often degrades trust. + +--- + +## Pattern B: Email after result, for personalized delivery + +The result is shown; an offer is made for personalized PDF or follow-up. + +**How it works.** + +- The taker answers all questions. +- The result is shown immediately, including segment description and matched recommendation. +- Below or alongside the result, an offer: "Want this as a PDF you can share?" or "Want a personalized 5-day sequence with deeper resources for your segment?" +- The taker who wants the additional value enters email. + +**Strengths.** + +- Honest. The audience gets what they came for. +- Lead quality is higher; takers who opt in are signaling real interest. +- Trust is preserved; audience that does not opt in still leaves with positive brand association. + +**Weaknesses.** + +- Lower conversion rate to email than Pattern A. +- Requires designing additional value (PDF, sequence) that justifies the email. + +**When to use.** Default pattern for B2B and considered purchases. The honest exchange compounds trust over time. + +--- + +## Pattern C: Email integrated with optional features + +The result is shown; multiple optional opt-ins are offered. + +**How it works.** + +- The taker answers all questions. +- The result is shown. +- Multiple opt-in options appear, each with distinct value: "Save this scenario for later," "Get notified when new content for your segment is available," "Download a personalized resource." +- The taker chooses which (if any) to opt into. + +**Strengths.** + +- Most flexibility for the audience. +- Allows different audience segments to engage at different levels. +- Lead quality is high because each opt-in is for specific value. + +**Weaknesses.** + +- More complex to design and implement. +- Multiple options can dilute conversion ("paradox of choice"). +- Requires the brand to actually deliver on each opt-in. + +**When to use.** When the quiz has multiple legitimate value-add follow-ups and the audience benefits from choice. + +--- + +## Pattern D: Progressive opt-in across the quiz + +Email is captured early but only used after the quiz completes. + +**How it works.** + +- The quiz starts with optional email entry ("get a personalized PDF report when you finish"). +- Takers can enter email upfront or skip. +- The quiz proceeds; the result is shown for everyone. +- Takers who entered email get the PDF; others see the result and an opt-in offer. + +**Strengths.** + +- Captures highly committed takers early. +- Does not gate the result. +- Provides a soft opt-in path for less-committed takers. + +**Weaknesses.** + +- Asking for email upfront can depress quiz starts. +- Two-path design (email-given vs not-given) adds complexity. + +**When to use.** When the audience benefits from setting expectations upfront and when the brand can deliver value differently to opted-in vs walk-up takers. + +--- + +## The value-add at lead capture + +What the user gets for their email matters as much as when the email is asked. + +**Strong value-adds.** + +- A personalized PDF report matched to the segment. +- A follow-up email series that deepens the segment-matched content. +- A curated resource list specific to the result. +- Notifications about new resources, products, or events relevant to the segment. + +**Weak value-adds.** + +- Just sending the same result by email (no value-add over what is on screen). +- A generic newsletter signup (not personalized to the result). +- A "join our community" offer with no clear value. + +**The discipline.** The value-add should be substantively better than what the audience saw on screen. If it is not, the email gate is not justified. + +--- + +## Conversion vs lead quality + +The patterns trade off these two metrics. + +**Conversion-optimized.** Pattern A captures the most emails but produces lower lead quality. Suitable when the goal is volume or when the audience is highly aligned (every taker is a target lead). + +**Quality-optimized.** Pattern B and C capture fewer emails but produce higher lead quality. Suitable when the goal is downstream conversion or when the audience is mixed (only some takers are target leads). + +**The choice.** Depends on what the program optimizes for. Brands optimizing for downstream revenue often choose Pattern B or C. Brands optimizing for list growth may default to Pattern A. + +**The trap.** Optimizing for conversion at the expense of lead quality is short-term thinking. The conversion metric looks fine; the downstream metrics suffer; the program quietly underperforms. + +--- + +## The "no email needed" alternative + +Some quizzes do not capture email at all. + +**When this works.** When the quiz's purpose is brand-building, SEO, or audience-engagement rather than lead-capture. The quiz's existence and shareability are the value; the email is incidental. + +**The pattern.** The taker takes the quiz; the result is shown; share buttons are prominent; no email gate. + +**Why it can work.** Some brands earn more from a widely-shared quiz than from a gated quiz that captures fewer emails. The brand association is the value. + +**When it fails.** When the program needs leads and the no-gate design produces nothing for the funnel. + +--- + +## Lead-capture form design + +The form itself matters. + +**Field count.** Email only is the strong default. Each additional field reduces conversion. + +**Field justification.** If additional fields are required (name for personalization, company for B2B sales context), justify them inline. "We use your name to personalize your follow-up" is honest; uncontextualized fields feel like sales-form padding. + +**Form placement.** Inline with the result is honest; popup that interrupts the result viewing is hostile. + +**CTA copy.** "Get my personalized PDF" beats "Submit." Specific value statement beats generic action. + +**Loading state.** After submission, show progress and confirm receipt. "Sending your PDF now... check your inbox in 2 minutes." + +--- + +## Post-capture experience + +What happens after the email is captured. + +**Immediate delivery.** The promised PDF, sequence, or resource arrives within minutes. Delays break trust. + +**Confirmation message.** On the result page or in the email, confirm what was sent and what to expect next. + +**Sequence integration.** If a follow-up sequence was offered, the first email arrives within 24 hours. The sequence delivers the promised cadence. + +**Opt-out clarity.** Easy unsubscribe from the start. Audiences that find unsubscribe friction lose trust permanently. + +--- + +## Capture-pattern testing + +Test pattern choice with real metrics. + +**Test design.** A/B test Pattern A vs Pattern B with the same quiz. Measure both conversion to email and downstream conversion (trial signup, demo request, purchase). + +**The metric that matters.** Downstream conversion per visitor, not conversion to email. A pattern that captures fewer emails but produces more downstream conversion is the better pattern. + +**Test duration.** Long enough to capture downstream signal (often 30-60 days minimum, depending on consideration cycle). + +--- + +## Common capture failures + +**Lead-trap pattern.** Result hidden behind email; downstream conversion drops; trust degrades. + +**Email gate without value.** Email required for the same content; gate is not justified; conversion drops. + +**Too many fields.** Form asks for name, company, role, phone in addition to email; conversion plummets. + +**Generic CTA copy.** "Submit" rather than "Get my personalized PDF"; conversion suffers. + +**Popup that interrupts.** Result loads; popup appears; user's flow breaks. + +**Slow delivery.** PDF arrives 30 minutes later; trust drops. + +**No confirmation.** User submits, sees no acknowledgment, wonders if it worked. + +**Hard unsubscribe.** Multi-step or hidden unsubscribe; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The capture-honest principle. Pattern A through D with strengths, weaknesses, and when-to-use guidance. The value-add at lead capture. The conversion-vs-quality tradeoff. The no-email-needed alternative. Lead-capture form design. Post-capture experience. Capture-pattern testing. Common failures. + +## Implementation choices that stay internal + +Specific capture pattern choices for specific quizzes. Specific PDF templates and sequence designs. Specific form copy and CTAs in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md new file mode 100644 index 0000000..8fca5ba --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md @@ -0,0 +1,212 @@ +# Question architecture patterns + +Question count, types, ordering, phrasing, and segment mapping discipline. The questions are the mechanism that produces the segmentation; bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +--- + +## Question count + +Most effective quizzes use 5-10 questions. + +**Fewer than 5 questions.** Rarely produces meaningful segmentation. The taker reaches the result quickly, but the result feels arbitrary because too few signals were captured. Useful only for very simple categorizations (binary or 3-segment outcomes). + +**5-7 questions.** The sweet spot for most quizzes. Enough to produce nuanced segmentation; few enough that the audience completes without fatigue. + +**8-12 questions.** Acceptable when the segmentation is genuinely multi-dimensional or when the audience has high commitment. Watch drop-off carefully; the last few questions are where audiences abandon. + +**13+ questions.** Stops feeling like a quiz; starts feeling like a survey. Drop-off rises sharply. If the segmentation truly needs this many questions, consider whether quiz is the right format. + +--- + +## Question types + +Choose the type that fits the variable being captured. + +**Multiple-choice (single-select).** The most common quiz question type. Each option maps to a segment or scoring weight. + +When to use: when the answer space is well-defined and mutually exclusive. +When to avoid: when the audience genuinely could choose multiple answers; forcing single-select frustrates the taker. + +**Multiple-select.** Useful when multiple attributes apply to the taker. + +When to use: when the answer space includes overlapping options ("which features matter most" with multiple selections). +When to avoid: when scoring complexity outweighs the value; multi-select complicates segmentation. + +**Slider or scale.** "On a scale of 1-5, how often do you..." Useful for intensity questions. + +When to use: when the variable is continuous (frequency, importance, satisfaction). +When to avoid: when the categorization is genuinely categorical; sliders force false continuity. + +**Yes/no.** Useful for binary qualifying questions. + +When to use: as part of a broader question set when one binary attribute matters (does the team use a CRM today, yes or no). +When to avoid: as the primary question type; quizzes built only on yes/no questions feel coarse. + +**Free text.** Avoid in quizzes. Free text breaks the scoring flow and adds friction. The few quizzes that genuinely need free text often work better as forms or assessments. + +--- + +## Question ordering + +The order matters as much as the questions themselves. + +**Open with engaging, low-friction questions.** "What kind of role best describes you?" or "What size is your team?" These warm up the taker and build commitment. + +**Mid-quiz: substantive segmentation questions.** The questions that most influence the segmentation belong in the middle. The taker has invested enough to commit; you have not yet exhausted their patience. + +**Late-quiz: more revealing or sensitive questions.** "How effective is your current process?" or "What is your biggest challenge?" These questions benefit from the trust built earlier. + +**End: qualifying questions, if needed.** Demographic data, company-size confirmation, or contact-channel preferences. These belong at the end, not the start. Asking demographic questions first signals "this is a sales form" and depresses completion. + +--- + +## Question phrasing + +Plain language. No jargon. No leading. + +**Plain language.** Avoid technical terms the audience may not know. If the quiz is for SaaS founders, "ARR" is fine; if it is for general business owners, "annual revenue" is clearer. + +**Specific situations.** Frame questions around situations the audience recognizes. "When you onboard a new customer, do you..." beats "What is your customer-onboarding maturity." + +**Avoid leading questions.** Phrasing that pushes toward a specific answer biases the result. + +- Leading: "How much do you struggle with X?" (presumes struggle) +- Honest: "How would you describe your experience with X?" + +**Avoid double-barreled questions.** Questions that mix two dimensions confuse scoring. + +- Double-barreled: "How much do you value speed AND simplicity?" +- Cleaned up: split into two questions if both dimensions matter. + +**Avoid "all of the above" or "none of the above" defaults.** These options are escape valves that produce uninterpretable answers. + +--- + +## Question-segment mapping + +Each question should contribute to the segmentation in a defined way. + +**The principle.** For each question, document which answer choices map to which segments and with what weight. + +**Example: "What size is your team?"** + +- 1-5 employees → segment "Solo or small" (+3 to that segment) +- 6-25 employees → segment "Growing team" (+3) +- 26-100 employees → segment "Mid-market" (+3) +- 101+ employees → segment "Enterprise" (+3) + +**Example: "What is your sales process maturity?"** + +- "Founder-led, no defined process" → "Solo or small" (+2), "Growing team" (+1) +- "Some defined steps, owner driven" → "Growing team" (+2), "Mid-market" (+1) +- "Defined sales playbook, multiple reps" → "Mid-market" (+2), "Enterprise" (+1) +- "Multi-stage enterprise sales process" → "Enterprise" (+3) + +The mapping is explicit. Each question contributes specific weight to specific segments. The mapping should be documented so future maintenance can verify it. + +**Filler questions.** Questions that do not affect the segmentation are filler. They add friction without adding value. Audit and remove. + +--- + +## Question count vs segmentation depth + +The relationship between question count and segmentation accuracy. + +**Few questions, broad segments.** A 5-question quiz produces 4-5 segments reliably; trying to produce 10 segments from 5 questions makes each segment poorly distinguished. + +**More questions, narrower segments.** An 8-question quiz can produce 6-8 segments with enough distinction. + +**The over-segmentation trap.** Too many segments produced from too few questions creates segments that are not really different. The audience that lands in different segments gets similar recommendations; the segmentation is fake. + +**The right ratio.** Roughly 1.5-2 questions per segment is a useful baseline. 5-7 segments from 8-12 questions; 4-5 segments from 5-7 questions. + +--- + +## Conditional questions and branching + +Whether to ask different questions based on earlier answers. + +**Branching when it helps.** Later questions make sense only in the context of earlier ones. "If you have a CRM today, which one?" is a useful follow-up to "Do you use a CRM today?" + +**Branching when it hurts.** When branching adds complexity without value, when the branching makes the quiz feel different for different takers in confusing ways, when the scoring becomes hard to reason about. + +**The simplicity preference.** Linear quizzes (everyone gets the same questions in the same order) are easier to maintain, easier to test, and easier for the audience to predict. Use branching only when the value justifies the complexity. + +--- + +## Drop-off considerations + +Where audiences abandon, and why. + +**The first question.** Some takers click into the quiz and leave at question 1. Often the question or the format made them realize this is not for them. This is fine; honest filtering. + +**Mid-quiz (questions 4-7).** Drop-off here usually signals fatigue or discomfort. Audit the questions; are they too long, too sensitive, too repetitive? + +**Late-quiz (final questions).** Drop-off here often signals that the user got bored or the value of finishing was not clear. A progress indicator and a teaser of the result ("almost done; see your result next") can reduce late-stage drop-off. + +**Question-by-question tracking.** Tracking drop-off per question is the diagnostic. Questions with disproportionate drop-off warrant review. + +--- + +## Mobile question design + +Most quiz takers are on mobile. The question UX has to work there. + +**Mobile-specific considerations.** + +- Touch-friendly answer options (minimum 44x44 pixel touch targets). +- Single question per screen on mobile (multi-question screens cramp). +- Progress indicator visible without scroll. +- Answer options large enough to tap accurately; spacing prevents accidental taps. +- Sliders sized for thumb interaction. + +**Mobile testing.** Test the quiz on actual devices. Real-device behavior often differs from browser dev-tools simulation. + +--- + +## Question-mapping audit + +Periodically audit the question-segment mapping. + +**The audit.** For each segment, verify that the questions actually produce that segment for takers who should get it. Run the quiz with personas representing each segment; confirm each persona reaches the right result. + +**The audit cadence.** When the recommendation portfolio changes, when the audience composition shifts, or at least quarterly. + +**Drift indicators.** + +- One segment now receives 70+ percent of takers. +- Another segment receives less than 5 percent. +- Specific personas reach the wrong segment when audited. +- Audience comments that the result was wrong. + +These signals warrant question or scoring revision. + +--- + +## Common question architecture failures + +**Too many questions.** 15+ questions feels like a survey; drop-off climbs. + +**Filler questions.** Questions that do not affect segmentation; audit and remove. + +**Leading questions.** Phrasing that biases the answer. + +**Double-barreled questions.** Two dimensions in one question; scoring becomes ambiguous. + +**Demographic questions first.** Signals "sales form"; depresses completion. + +**Vague answer options.** "Sometimes" vs "often" without anchors; the taker cannot calibrate. + +**Inconsistent question types.** Mixing 5-point sliders with yes/no without coherent rationale; the rhythm breaks. + +**Mobile-broken questions.** Sliders that do not work on touch; answer options that overflow. + +--- + +## Methodology-level choices that stay in the public skill + +Question count, types, ordering, phrasing. Question-segment mapping discipline. Question count vs segmentation depth. Conditional questions and branching. Drop-off considerations. Mobile question design. Question-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific question sets for specific quizzes. Specific scoring weights and segment mappings. Specific tooling for quiz engineering and analytics. The team's drop-off benchmarks and audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md new file mode 100644 index 0000000..533a111 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md @@ -0,0 +1,223 @@ +# Quiz anti-patterns + +The patterns that look like quizzes but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The clickbait-quiz + +The pattern. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you?" with 4 personality types and no recommendations. + +The signal. Engagement metrics are high (shares, completions); downstream metrics are flat. The quiz is fun; it does not produce qualified leads or conversions. + +The cost. The build cost is wasted on entertainment that does not compound business value. The brand earns "fun but not useful" association. + +The cure. Add actionable segmentation. Each segment maps to a specific recommendation matched to that segment. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The vanity-result quiz + +The pattern. Flattering descriptions for every segment. No honest characterization. No specific recommendations. + +The signal. Takers enjoy the result; do not act on it; do not return. The quiz produces a moment of attention without a relationship. + +The cost. The audience associates the brand with horoscope-style content. The quiz does not differentiate the brand from competitors offering similar entertainment. + +The cure. Honest segmentation. Some segments are more flattering than others; honest descriptions produce respect; recommendations that match each segment specifically produce action. + +--- + +## The forced-result quiz + +The pattern. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The signal. Sales team or product team notices that quiz-sourced leads all look the same; the segmentation is not differentiating. + +The cost. The quiz misleads the audience. Takers who answered honestly believing they would get a matched recommendation get a generic one; trust degrades. + +The cure. Real segmentation that produces real different recommendations per segment. If the brand only has one recommendation, do not use a quiz format; use a clear landing page. + +--- + +## The interrogation-quiz + +The pattern. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The signal. High drop-off rate, especially at questions 8-15. Few takers reach the result. + +The cost. The build effort produces a quiz few people complete. The audience that drops off remembers the brand as the source of the long form they abandoned. + +The cure. Reduce question count. 5-12 questions is the working range. Audit questions for those that do not affect segmentation; remove them. + +--- + +## The leading-question quiz + +The pattern. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The signal. The result distribution is biased; takers report that the result felt predetermined; analytical audiences notice the leading. + +The cost. The audience that catches the leading loses trust. The result is artificially produced rather than reflecting the taker's actual situation. + +The cure. Plain phrasing without bias. "How would you describe your experience with X?" beats "How much do you struggle with X?" + +--- + +## The black-box quiz + +The pattern. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The signal. Audience comments asking how the result was calculated; some takers question whether the result is real or random. + +The cost. The quiz feels arbitrary. Even when the segmentation is real, the audience cannot verify; trust suffers. + +The cure. Some transparency about the methodology. "Your result reflects your answers to questions 2, 4, and 6" or a brief explanation of what the segments represent. + +--- + +## The no-recommendation quiz + +The pattern. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The signal. Strong engagement; near-zero downstream conversion; the quiz captures a moment without converting it. + +The cost. The brand has the audience's attention and does nothing with it. The quiz produces brand impression without business impact. + +The cure. Every result page must include a specific next step. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The mismatched-recommendation quiz + +The pattern. The recommendation does not match the segment. A taker classified as "enterprise" gets a "starter plan" recommendation, or vice versa. + +The signal. Sales team feedback that quiz-sourced leads do not match the recommended product. Audience feedback that the recommendation felt wrong. + +The cost. Trust damage. The taker who notices the mismatch feels misled; the brand earns "doesn't get me" reputation. + +The cure. Audit the segment-to-recommendation mapping. Verify each segment's recommendation actually fits. + +--- + +## The over-segmentation quiz + +The pattern. 12+ segments produced from 5 questions. Most segments end up similar; segmentation is fake. + +The signal. Segments that read the same; segments that get the same recommendation; segments that receive less than 3 percent of takers each. + +The cost. Design and copy effort wasted on segments that do not really exist. The audience that lands in similar segments cannot tell them apart. + +The cure. Reduce segment count to what the questions can actually distinguish. 4-7 segments from 5-7 questions; 6-8 segments from 8-10 questions. + +--- + +## The under-segmentation quiz + +The pattern. 2 segments that could have been a yes/no question. The quiz format is over-engineering. + +The signal. The audience completes the quiz quickly; the result feels obvious; the quiz adds friction without adding value. + +The cost. Build effort wasted on a quiz that did not need to be a quiz. The audience that recognizes the over-engineering questions the brand's judgment. + +The cure. Either expand the segmentation to justify the format or replace the quiz with a simpler tool (yes/no qualifier, comparison table). + +--- + +## The lead-trap quiz + +The pattern. The result is calculated but hidden behind an email gate. The taker enters 8 fields, hits Calculate, sees "enter your email to see your result." + +The signal. Email-form conversion is high; downstream conversion is low; audience that recognizes the pattern bounces immediately. + +The cost. Lead quality suffers. The brand earns "lead-trap" reputation. Detail in `references/lead-capture-integration-patterns.md`. + +The cure. Show the result freely; gate the additional value (PDF, follow-up sequence) instead. + +--- + +## The cookie-cutter quiz + +The pattern. The quiz looks and behaves like every other quiz from a template platform. Generic UI, generic question style, generic result format. + +The signal. The quiz does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The quiz becomes commodity. The brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Question phrasing in brand voice. Result presentation that feels distinct. + +--- + +## The mobile-broken quiz + +The pattern. Quiz works on desktop; breaks on mobile. Answer options that overflow; sliders impossible to grab; result hidden below the fold. + +The signal. High mobile bounce rate; mobile completion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Detail in `references/question-architecture-patterns.md` (mobile section). + +--- + +## The popup-interrupted quiz + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. + +The signal. Bounce rate spikes at the result moment; users complain about the interruption. + +The cost. The quiz's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. + +--- + +## The orphan-quiz + +The pattern. The quiz exists; no follow-up sequence; no integration with the broader funnel. Takers complete; nothing happens. + +The signal. Email captures sit on a list with no engagement; downstream conversion is near zero. + +The cost. The lead-capture work was for nothing. The brand has emails but no relationship. + +The cure. Design the post-quiz sequence as part of the quiz design (similar to the lead-magnet sequence discipline in `lead-magnet-design`). + +--- + +## The everyone-quiz + +The pattern. Quiz designed to appeal to "everyone." Generic segments; generic recommendations. + +The signal. Conversion may be high; lead quality is low; downstream conversion is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly. + +The cure. Narrow the audience the quiz serves. Specific quizzes for specific segments produce specific recommendations that convert. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active quiz, looking specifically for these anti-patterns. + +**Audit questions per quiz.** + +- Does each segment have a specific, distinct recommendation (anti-pattern check: forced-result, mismatched-recommendation)? +- Is segment distribution balanced across takers (anti-pattern check: over-segmentation, under-segmentation)? +- Is drop-off concentrated at specific questions (anti-pattern check: interrogation, leading questions)? +- Does the result page include a clear next step (anti-pattern check: no-recommendation, vanity-result)? +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Does the quiz feel branded or templated (anti-pattern check: cookie-cutter)? +- Does the quiz work on mobile (anti-pattern check: mobile-broken)? + +**The retire decision.** Anti-pattern quizzes often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-quiz plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md new file mode 100644 index 0000000..11cf765 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md @@ -0,0 +1,145 @@ +# Quiz investment criteria + +When a quiz is the right tool for the audience and the goal, and when a comparison table or other format would serve. The conditions that warrant the quiz format. + +A quiz is a meaningful build. Question architecture, scoring algorithm, result categorization, recommendation mapping, lead-capture integration. The quiz earns this investment only when specific conditions are present. + +--- + +## When a quiz earns the build + +Five conditions that, when present, make a quiz a strong investment. + +**The audience faces a decision that benefits from categorization.** "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. + +**The categorization can be derived from a small number of questions.** 5-12 questions can produce meaningful segmentation. If the categorization needs 30+ questions, the format is closer to a survey or assessment than a quiz; the audience drop-off makes the format wrong. + +**The brand has a portfolio of recommendations that match the segments.** A quiz that produces 5 segments and only one recommendation is decorative; the segment-recommendation mapping is the value. + +**The result format suits the audience.** Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage well. Audiences who do not (technical buyers, enterprise sales) often see quizzes as gimmicks. + +**The success metric is defined.** Lead volume from the quiz, lead quality by segment, downstream conversion per segment, the audience acting on the recommendation. Without the success metric defined, evaluation is impossible. + +When all five are present, the quiz is a strong investment. When two or fewer are present, a different format (comparison table, worked example, calculator) often serves better. + +--- + +## When a quiz does NOT earn the build + +Funnels where the quiz is the wrong tool. + +**The categorization is trivial.** "What plan is right for you" with two plans does not need a quiz; a comparison table works. Quizzes earn investment when the categorization is non-trivial. + +**The categorization is irrelevant to the next step.** A personality quiz with no product-recommendation tie-in entertains but does not convert. The categorization needs to map to action. + +**The brand has no varied recommendations.** A quiz with one outcome is bait; the segmentation is decorative. Without a portfolio of segment-matched recommendations, the quiz cannot deliver the actionable-segmentation value. + +**The audience disrespects quizzes in this context.** Enterprise buyers often see quizzes as unprofessional. Technical decision-makers often skip quizzes in favor of direct documentation. The format choice has to fit the audience the brand wants to serve. + +**The team cannot maintain the quiz.** Quizzes decay as recommendations change, segments evolve, and audience preferences shift. Without maintenance commitment, the quiz becomes stale. + +**The audience would convert without the quiz.** When the funnel is already producing the conversion the quiz would serve, the quiz adds friction without lift. + +The honest assessment matters more than the default. "Should we have a quiz" is not the question. "Is the quiz the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A quiz is a meaningful build. Account for the cost honestly. + +**The build cost.** Question design, scoring algorithm, result categorization, recommendation mapping, UI design, mobile responsiveness, integration. A meaningful quiz often takes 30-100 engineering hours plus design, copy, and content for the recommendations. + +**The maintenance cost.** Recommendations change; segments evolve; question phrasing decays. Quarterly review and updates run 3-8 hours per active quiz. + +**The recommendation portfolio cost.** Each segment needs a matched recommendation. Building or curating those recommendations is itself work. + +**The opportunity cost.** What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization. The quiz's success has to clear the bar of those alternatives. + +The decision frame. The quiz earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus recommendation portfolio. + +--- + +## The recommendation-portfolio precondition + +Without a portfolio of segment-matched recommendations, the quiz cannot deliver actionable segmentation. + +The check. For the segmentation the quiz will produce, does the brand have a distinct, valuable recommendation for each segment? + +If yes, the quiz can deliver actionable segmentation. The takers get matched to a recommendation that fits their result. + +If no (the brand has one product, one resource, one recommendation regardless of segment), the quiz becomes vanity. The segmentation is decorative; the recommendation was predetermined. + +**How to assess the recommendation portfolio.** + +- Does the brand have multiple products, services, or content paths that fit different audience segments? +- Can the brand articulate which recommendation fits which segment specifically? +- Are the recommendations valuable enough to that segment to justify the quiz? + +If yes to most of these, the recommendation portfolio supports the quiz. If no, the quiz is the wrong format until the portfolio exists. + +--- + +## The decision worked example + +A B2B SaaS company considering a "What CRM fits your team" quiz. + +**Conditions check.** + +- Decision benefits from categorization: yes. Prospects evaluate CRMs based on team size, use case, sales process maturity, integration needs. The categorization is non-trivial. +- Small number of questions sufficient: yes. 6-8 questions can capture team size, use case, sales process, integration needs. +- Recommendation portfolio: yes. The brand offers 3 plan tiers plus 2 industry-specific configurations. Each segment can map to a distinct recommendation. +- Audience-fit for quiz format: yes. B2B mid-market PMs and sales leads engage with quizzes when the recommendation is genuinely useful. +- Success metric: yes. Lead volume from the quiz, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo or trial within 60 days. + +**Decision.** Build the quiz. The conditions warrant it. + +**Result categorization.** 5 segments: "Solo founder just starting," "Growing team without CRM," "Mid-market with multiple sales reps," "Enterprise with complex sales cycles," "Integration-heavy team." + +**Recommendation per segment.** Each segment maps to a specific plan and onboarding path. The segment description explains why that recommendation fits. + +**Lead capture.** Email after result for personalized PDF showing the recommendation, alternative options considered, and case study from a similar customer. + +The decision was not "should we have a quiz" but "given these conditions, this is the quiz to build." + +--- + +## When to choose a different format + +The quiz is the wrong tool. What works. + +**Comparison table.** When the choice is between 2-4 well-defined options with clear distinguishing features, a comparison table often serves better. The audience compares directly without going through questions. + +**Worked-example resource.** When the audience benefits from seeing how others in their situation chose, a 2-page worked-example resource often serves better than a quiz. The audience identifies which example matches them. + +**Calculator.** When the decision benefits from a calculation rather than a categorization, a calculator serves better. Detail in `calculator-design`. + +**Direct documentation.** When the audience prefers self-directed research, a clear documentation page about which option fits which situation often serves better than a quiz. + +The pattern. Many "we need a quiz" intuitions are actually "we need a clear way to communicate which option fits which audience." Often the simpler format works as well or better, at lower build cost. + +--- + +## When to retire a quiz + +Quizzes decay. Retiring them is part of the discipline. + +**Retire when:** + +- Lead volume has dropped below baseline for two consecutive quarters. +- The recommendation portfolio has shifted enough that the quiz routes to outdated recommendations. +- One segment now receives 80 percent of takers, suggesting the question architecture no longer distinguishes. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. Stale quizzes route audience to outdated recommendations and damage trust. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a quiz. The opportunity-cost frame. The recommendation-portfolio precondition. The decision worked example. When to choose a different format. The retirement discipline. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. The team's capacity benchmarks for build, maintenance, and recommendation curation. Specific tooling for quiz engineering and integration. Specific recommendation portfolios per segment. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md new file mode 100644 index 0000000..f9e74d7 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md @@ -0,0 +1,233 @@ +# Result categorization patterns + +Segment count, naming, distinguishability, balance. The shape of the result categories that the quiz produces. + +The categorization is the quiz's segmentation product. Bad categorization produces results that feel arbitrary or that fail to help the audience act. Good categorization produces results the audience recognizes and uses. + +--- + +## Segment count + +Most quizzes work well with 4-8 result categories. + +**Fewer than 4 segments.** The categorization feels coarse. Two-segment quizzes (e.g., "is this for you, yes or no") rarely earn the quiz format; a comparison or qualifying form serves better. + +**4-6 segments.** The sweet spot for most quizzes. Enough segments to feel nuanced; few enough that each gets adequate development. + +**7-8 segments.** Acceptable when the segmentation is genuinely multi-dimensional. Each segment needs a distinct description, distinct recommendation, and clear distinguishability. + +**9+ segments.** Often a sign of over-segmentation. Many segments end up similar in description and recommendation; the segmentation becomes fake. + +--- + +## Segment naming + +Memorable. Specific. Honest. Brand-voice consistent. + +**Memorable.** The taker should be able to describe their segment to a friend. "The Strategic Planner" is memorable; "Type 3" is not. + +**Specific.** Names should distinguish the segment from others. + +- Specific: "The Hands-On Builder" (vs "Type B") +- Specific: "Solo founder just starting" (vs "Beginner") +- Specific: "Mid-market operator with multiple sales reps" (vs "Mid-tier user") + +**Honest.** Names should not flatter universally. Some segments are more flattering than others; honest segmentation reflects this. + +- Honest: "Just exploring" alongside "Already executing" alongside "Mature operator." Each describes a real position. +- Dishonest: every segment named with a flattering descriptor regardless of where the taker actually is. + +**Brand-voice consistent.** The names should sound like the brand the quiz represents. A serious brand uses serious names; a playful brand can use playful names. Consistency matters. + +--- + +## Segment distinguishability + +Each segment should be meaningfully different from the others. + +**The test.** Read the descriptions of two adjacent segments. Are they meaningfully different in: +- Who the segment describes? +- What the segment's situation is? +- What the segment's recommendation is? + +If yes, the segments are distinguished. If no (the descriptions are similar, the recommendations overlap), the segmentation is fake. + +**The fake-segmentation pattern.** A quiz produces 5 segments, but segments 2, 3, and 4 are described in similar terms with similar recommendations. The audience that lands in different segments gets indistinguishable results; the segmentation is decorative. + +**The cure.** Either reduce the segment count (if the segmentation does not support 5 segments, do not pretend it does) or strengthen the distinctions (rewrite descriptions and recommendations so each segment is distinct). + +--- + +## Segment balance + +Each segment should receive a meaningful share of takers. + +**Balanced segmentation.** Each segment receives roughly 10-30 percent of takers (depending on segment count). The audience is genuinely distributed across segments. + +**Imbalanced segmentation.** One segment receives 70+ percent of takers; another receives less than 5 percent. The segmentation is not working; the questions do not distinguish meaningfully. + +**Why balance matters.** + +- Imbalance signals the segmentation is broken. +- The unused segments waste design and copy effort. +- The dominant segment becomes a default that does not really categorize anyone. + +**The cure.** Audit the question architecture (`references/question-architecture-patterns.md`). Often the questions do not produce balanced segmentation because they bias toward one segment. Adjust questions or weights to produce more even distribution. + +**The exception.** Some quizzes intentionally produce imbalanced segmentation because the audience genuinely skews. A "what is your team size" quiz may produce 60 percent "small team" because the audience is mostly small teams. Honest imbalance reflecting real audience composition is fine; imbalance from broken questions is not. + +--- + +## Segment description + +What appears at the result, beyond the segment name. + +**The description should include:** + +- A 2-3 sentence summary of the segment (who they are, what their situation is). +- Specific characteristics the audience will recognize. +- The matched recommendation (what to do next). +- Optional: case study or worked example of someone in this segment. + +**Example segment description.** + +``` +Segment: "The Mid-Market Operator" + +You are running a sales team of 5-25 people across multiple +products or regions. You have a defined sales process but +inconsistent execution; some reps follow it, others freelance. +Your top priority is unifying the team's process without +slowing your fastest performers. + +Recommendation: Our Growth plan with the multi-region +playbook configuration. We have a 30-day onboarding path +for teams in your situation. + +[Link to PDF: see how 3 mid-market operators implemented +this and the results] +``` + +The description is specific. The recommendation is matched. The next step is clear. + +**Description antipatterns.** + +- Generic descriptions that could fit multiple segments. +- Flattering descriptions with no honest characterization. +- Descriptions that describe but do not recommend. +- Recommendations that are the same across segments. + +--- + +## Segment naming patterns + +Common patterns and their tradeoffs. + +**Pattern A: Role-based names.** "The Strategic Planner," "The Hands-On Builder." Useful when segments correspond to functional roles. + +**Pattern B: Maturity-based names.** "Just Starting," "Growing," "Mature." Useful when segments correspond to stages of development. + +**Pattern C: Style-based names.** "The Optimizer," "The Connector," "The Visionary." Common in personality assessments. Risk of feeling horoscope-like. + +**Pattern D: Situation-based names.** "Solo founder pre-launch," "Mid-market operator with multi-region team." Useful when segments correspond to specific situations the audience recognizes. + +**Pattern E: Outcome-based names.** "Cost-focused buyer," "Time-saver-focused buyer." Useful when segments correspond to what the buyer is optimizing for. + +The pattern choice depends on the quiz's purpose and the audience the brand serves. The discipline is that whatever pattern is chosen, names should be specific and honest. + +--- + +## Result-page composition + +What the result page contains beyond the segment description. + +**The standard structure.** + +- The segment name and key visual. +- The segment description (2-3 sentences). +- The matched recommendation. +- The clear next step (CTA: download PDF, talk to team, explore product). +- Optional: comparison to other segments (so the taker sees the full picture). +- Optional: share button (if the quiz is shareable). + +**The clear-next-step principle.** Every result page must include a specific next step. Without it, the quiz produces awareness without action. + +**The optional comparison.** Showing the other segments lets the taker see the full segmentation. Useful when the audience benefits from understanding where they sit; less useful when the segments would distract from the matched recommendation. + +--- + +## Result-page mobile design + +The result page must work on mobile. + +**Mobile considerations.** + +- Segment name and recommendation visible without scroll. +- Visual elements sized for mobile screens. +- CTA button large and prominent. +- Share buttons functional on mobile platforms. + +**Common mobile failures.** + +- Result hidden below the fold; user does not know it loaded. +- Recommendation buried after a long scroll. +- CTA button tiny or hard to tap. + +--- + +## Segment maintenance + +Segments decay along with the quiz. + +**What decays.** + +- Segment descriptions that no longer match the audience composition. +- Recommendations that point to retired products or content. +- Brand voice that has shifted. + +**Maintenance cadence.** Quarterly review of segment descriptions and recommendations. Update as the recommendation portfolio evolves. + +**The retire-segment decision.** A segment that receives less than 3 percent of takers consistently may not warrant maintenance. Either restructure the segmentation to merge underused segments or accept that the segmentation has segments that exist but are rarely produced. + +--- + +## The segmentation-recommendation alignment audit + +Periodically verify that each segment's recommendation still matches. + +**The audit.** For each segment: +- Does the recommendation still exist (not pointing to a retired product)? +- Does the recommendation still match the segment's situation? +- Does the recommendation deliver value to that specific segment? + +**The drift.** Recommendations decay. Products are retired, content is updated, the brand evolves. Audit cadence catches the drift. + +--- + +## Common categorization failures + +**Too few segments.** Categorization feels coarse; quiz earns no segmentation value. + +**Too many segments.** Over-segmentation; segments end up similar; categorization feels fake. + +**Generic segment names.** Names that could apply to multiple segments; not memorable. + +**Flattering-everyone descriptions.** No honest segmentation; all segments feel positive. + +**Indistinguishable segments.** Two segments that read the same; categorization is decorative. + +**Imbalanced distribution.** One segment dominates; segmentation is broken. + +**Result without recommendation.** Description but no next step; quiz produces awareness without action. + +**Recommendations all the same.** Different segments routed to the same product or path; segmentation is decorative. + +--- + +## Methodology-level choices that stay in the public skill + +Segment count guidance. Naming patterns and discipline (memorable, specific, honest, brand-voice consistent). Distinguishability test. Balance principle. Segment description structure. Naming patterns A through E. Result-page composition. Mobile design. Segment maintenance. Segmentation-recommendation alignment audit. Common failures. + +## Implementation choices that stay internal + +Specific segment names for specific quizzes. Specific descriptions in brand voice. Specific recommendations matched to segments. Specific result-page layouts. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md new file mode 100644 index 0000000..e94131f --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md @@ -0,0 +1,255 @@ +# Result-to-recommendation mapping + +The action attached to each category. Mapping discipline and worked examples. The recommendation is what the taker does next; without it, the quiz produces awareness without action. + +The mapping is where the quiz earns its conversion. A great segmentation produces nothing if each segment lacks a matched, actionable recommendation. + +--- + +## The mapping principle + +Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +**The principle's three requirements.** + +- The recommendation is real (the brand actually offers the recommended next step). +- The recommendation matches the segment specifically (no two segments share the same recommendation). +- The recommendation is valuable to that specific segment (not a generic offer applied to everyone). + +Quizzes that hit all three produce action. Quizzes that miss any of the three produce vanity-result patterns. + +--- + +## What a recommendation can be + +The next step the taker should take. Many forms. + +**Product or service.** "Solo founders benefit most from our Starter plan with the founder-led onboarding path." The recommendation is a specific tier or configuration matched to the segment. + +**Content or resource.** "Mid-market operators benefit most from our 30-day playbook for unifying multi-rep teams." The recommendation is a specific resource matched to the segment. + +**Conversation or consultation.** "Enterprise buyers benefit most from a 30-minute conversation with our team." The recommendation is a specific human touchpoint. + +**Path or sequence.** "Creators just starting benefit most from our 4-part onboarding sequence." The recommendation is a structured next experience. + +**Configuration or setup.** "Teams using Salesforce benefit most from our integration setup wizard." The recommendation is a specific technical configuration. + +The form depends on the brand's offerings and the segment's situation. The discipline is that the recommendation is specific, not generic. + +--- + +## The mapping discipline + +Each segment-to-recommendation mapping should pass these tests. + +**Test 1: Does the recommendation actually exist?** The brand currently offers it; it is not aspirational or in development. + +**Test 2: Does the recommendation match the segment specifically?** Other segments would not benefit from this recommendation as much; the matching is real. + +**Test 3: Does the recommendation deliver value to this segment?** The segment that gets this recommendation can act on it and benefit from it. + +**Test 4: Is the recommendation deliverable?** The brand can provide what is being recommended in the timeframe and form the taker expects. + +**Test 5: Does the recommendation include a clear action?** The taker knows what to do (click here, start here, talk to someone, download this). + +When all five pass, the mapping is honest. When any fails, the mapping is decorative or misleading. + +--- + +## Worked example: B2B SaaS pricing quiz + +A SaaS platform offering 4 plan tiers with industry-specific configurations. + +**Segments and recommendations.** + +**Segment 1: "Solo founder just starting"** +- Description: 1-person team, exploring options, pre-revenue or early revenue. +- Recommendation: Starter plan ($X / month) with the founder-led onboarding path. Free for first 30 days; no credit card required. +- Action: "Start your 30-day trial." Direct link to signup pre-filled with the recommended plan. + +**Segment 2: "Growing team without CRM"** +- Description: 2-15 people, no CRM today, sales process is informal but starting to need structure. +- Recommendation: Growth plan ($Y / month) with the team-onboarding path. 30-day setup support included. +- Action: "Talk to our team about your setup." Calendar booking link. + +**Segment 3: "Mid-market with multiple reps"** +- Description: 16-100 people, multiple sales reps, defined process but inconsistent execution. +- Recommendation: Business plan ($Z / month) with multi-rep configuration and 60-day implementation support. +- Action: "Get a custom demo." Form for demo request. + +**Segment 4: "Enterprise with complex sales cycles"** +- Description: 100+ people, multi-stage sales process, integration-heavy environment. +- Recommendation: Enterprise plan (custom pricing) with dedicated implementation manager. +- Action: "Talk to enterprise sales." Direct line to enterprise contact. + +**Segment 5: "Integration-heavy team"** +- Description: Any size, but the primary need is integrating with their existing tool stack. +- Recommendation: Any plan plus the integration setup wizard. Detailed integration documentation linked. +- Action: "Explore our integrations." Integration catalog page. + +Each segment maps to a distinct, specific recommendation. Each recommendation includes a clear action. + +--- + +## Worked example: content-marketing quiz + +A content-marketing brand offering multiple content paths. + +**Segments and recommendations.** + +**Segment 1: "Just starting in content"** +- Recommendation: 4-part email course covering content fundamentals. +- Action: "Get the 4-part course." Signup form. + +**Segment 2: "Producing content but inconsistent results"** +- Recommendation: Content audit template + worked-example case study. +- Action: "Download the audit template." Direct download. + +**Segment 3: "Scaling a content team"** +- Recommendation: Team-management playbook + interview with a content director. +- Action: "Read the playbook." Resource page with playbook and interview. + +**Segment 4: "Optimizing for distribution"** +- Recommendation: Distribution-strategy framework + 5 worked examples. +- Action: "Read the framework." Resource page. + +Each segment routes to a distinct content path matched to where the audience is. + +--- + +## Worked example: readiness-assessment quiz + +A consultancy offering readiness assessments before engagement. + +**Segments and recommendations.** + +**Segment 1: "Not yet ready"** +- Description: Foundation work needed before the consultancy's offering would help. +- Recommendation: Self-serve resources for foundation work. Honest acknowledgment that engagement is not warranted yet. +- Action: "Explore the foundation library." Free resources. + +**Segment 2: "Ready for assessment"** +- Description: Foundation in place; specific gaps need addressing. +- Recommendation: 60-minute assessment call to identify specific engagement scope. +- Action: "Book the assessment call." Calendar link. + +**Segment 3: "Ready for full engagement"** +- Description: Foundation in place; clear gaps; ready to engage. +- Recommendation: Direct engagement conversation. +- Action: "Talk to our partner." Direct contact. + +**Segment 4: "Ongoing support"** +- Description: Already engaged, looking for continued partnership. +- Recommendation: Continuity-engagement options. +- Action: "Discuss your next phase." Direct contact. + +The honest segmentation includes a "not yet ready" segment. This is honest and earns trust; not every taker should be sold to immediately. + +--- + +## The "not for you" segment + +Honest segmentation sometimes includes a segment that is not the brand's audience. + +**The pattern.** A segment for takers who are not a fit. The recommendation acknowledges the lack of fit and offers something useful (a referral, a different brand's resource, a self-serve path). + +**Why it works.** + +- The taker who would have churned anyway leaves with respect for the brand. +- The brand earns "honest" reputation that compounds across audience segments. +- The unfit taker may refer fit takers later. + +**The dishonest alternative.** Pretending every taker is a fit; routing everyone to a sales contact regardless of segment. Audiences that catch the dishonesty disengage. + +--- + +## Recommendation freshness + +Recommendations decay; the mapping needs maintenance. + +**What decays.** + +- Recommendations pointing to retired products. +- Recommendations referencing outdated pricing or features. +- Recommendations linking to broken pages or moved resources. +- Recommendations that no longer match the brand's strategic priorities. + +**Maintenance cadence.** Quarterly review of every active recommendation. Update or replace as the brand's portfolio evolves. + +**The drift indicator.** Sales-team feedback that quiz-sourced leads are landing on the wrong recommendation. The mapping has drifted; refresh. + +--- + +## Recommendation testing + +Test the recommendations as part of quiz launch and updates. + +**Click-through testing.** What percentage of takers in each segment click the recommendation's CTA? Low click-through suggests the recommendation does not feel matched. + +**Conversion testing.** What percentage of takers in each segment complete the recommended action (sign up, book a call, download the resource)? Low conversion suggests the recommendation does not deliver expected value. + +**Feedback testing.** Direct user feedback ("does this recommendation feel right for you?"). Useful for early validation; rarely scalable. + +--- + +## The recommendation-as-CTA discipline + +The recommendation is also the call to action. + +**The pattern.** The recommendation includes a specific button or link that takes the taker to the next step. + +**Specific CTAs.** + +- "Start your 30-day trial" (specific action, specific timeframe). +- "Book a 30-minute assessment call" (specific format, specific duration). +- "Download the audit template" (specific deliverable). + +**Generic CTAs to avoid.** + +- "Learn more" (about what?). +- "Get started" (started doing what?). +- "Click here" (no value statement). + +The recommendation deserves a specific CTA matched to the action. + +--- + +## Multi-recommendation results + +Some quizzes produce multiple recommendations per segment. + +**The pattern.** The result includes a primary recommendation and one or more secondary recommendations. + +**When this works.** When the segment genuinely benefits from multiple paths (e.g., "you can start with X, or if you have specific need Y, consider Z instead"). + +**When this fails.** When multiple recommendations dilute the call to action; the taker does not know which to choose. + +**The discipline.** Default to one primary recommendation. Add secondary recommendations only when the segment genuinely benefits from a choice. + +--- + +## Common mapping failures + +**Same recommendation across segments.** Different segments route to the same product or path; segmentation is decorative. + +**Generic recommendations.** "Talk to our team" for every segment without segment-specific framing. + +**Aspirational recommendations.** Recommendations for products or services not yet available; the taker tries the action and hits dead ends. + +**Mismatched recommendations.** Recommendation does not match the segment's situation; takers feel unheard. + +**Buried recommendations.** Recommendation appears 3 emails after the result rather than in the result itself. + +**No clear CTA.** Recommendation describes what to do without providing the link or button to do it. + +**No "not for you" segment.** Every taker routed toward sales; the audience that does not fit is treated as fitting; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle and three requirements. Forms a recommendation can take. The mapping discipline (5 tests). Worked examples across quiz types. The "not for you" segment. Recommendation freshness. Recommendation testing. Recommendation-as-CTA discipline. Multi-recommendation results. Common failures. + +## Implementation choices that stay internal + +Specific segment-to-recommendation mappings for specific quizzes. Specific recommendation copy and CTAs in brand voice. Specific tracking for click-through and conversion per recommendation. The team's quarterly mapping audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md new file mode 100644 index 0000000..31c9328 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md @@ -0,0 +1,284 @@ +# Scoring algorithm patterns + +Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. The math that turns answers into a segment. + +The scoring algorithm is the bridge from question answers to result categorization. The right algorithm produces meaningful segments; the wrong algorithm produces results that do not match audience self-perception. + +--- + +## Pattern A: Direct mapping + +Each answer corresponds directly to a segment. The dominant answer choice determines the result. + +**How it works.** + +- Each question's answer choices map to specific segments. +- Each answer adds 1 point (or fixed weight) to its corresponding segment. +- The segment with the most points wins. + +**Example.** + +Question: "What size is your team?" +- 1-5 → "Solo" (+1) +- 6-25 → "Growing" (+1) +- 26-100 → "Mid-market" (+1) +- 100+ → "Enterprise" (+1) + +After all questions, the segment with the highest count wins. + +**Strengths.** + +- Simple, transparent, easy to explain. +- Easy to maintain (changes are obvious in their effect). +- The scoring logic can be displayed to the audience without confusion. + +**Weaknesses.** + +- Limited nuance; one answer cannot contribute to multiple segments meaningfully. +- Risk of ties when multiple segments score equally. + +**When to use.** When segments are well-defined and questions clearly distinguish them. The default starting point for many quizzes. + +--- + +## Pattern B: Weighted scoring + +Each answer adds points (with weights) to one or more segments. The highest-scoring segment wins. + +**How it works.** + +- Each question's answer choices add weighted points to one or more segments. +- An answer might add 3 points to segment A and 1 point to segment B. +- After all questions, the segment with the highest total score wins. + +**Example.** + +Question: "What is your sales process maturity?" +- "Founder-led, no defined process" → "Solo" (+3), "Growing" (+1) +- "Some defined steps" → "Growing" (+3), "Mid-market" (+1) +- "Defined sales playbook" → "Mid-market" (+3), "Enterprise" (+1) +- "Multi-stage enterprise process" → "Enterprise" (+4) + +This question is more central to segmentation, so its weights are higher. + +**Strengths.** + +- Allows nuance; one answer can contribute to multiple segments. +- Different questions can have different importance through their weights. +- Reduces tie likelihood by spreading weights. + +**Weaknesses.** + +- Less transparent (audience cannot easily reverse-engineer the result). +- More complex to maintain (changes to weights have non-obvious effects). +- Easy to bias accidentally if weights are not audited. + +**When to use.** When segmentation needs nuance, when some questions are more important than others, when the segmentation is multi-attribute. + +--- + +## Pattern C: Multi-dimensional + +The quiz produces scores across multiple axes. The result combines the scores into a 2D or 3D segment. + +**How it works.** + +- The quiz captures scores across 2-3 distinct dimensions (e.g., introvert/extrovert AND analytical/intuitive). +- The result is determined by the position on each dimension (introvert + analytical = one quadrant; extrovert + intuitive = another). +- Common in personality assessments, fit-evaluations, and any segmentation that is genuinely multi-axis. + +**Example.** + +A 2-dimensional quiz might score: +- Dimension 1: technical depth (low to high) +- Dimension 2: collaboration preference (solo to team) + +Result quadrants: +- High technical, solo → "Solo specialist" +- High technical, team → "Team specialist" +- Low technical, solo → "Solo generalist" +- Low technical, team → "Team generalist" + +**Strengths.** + +- Captures genuine multi-dimensional segmentation. +- Produces results that feel nuanced and accurate. +- Allows for richer recommendations matched to the dimensional combination. + +**Weaknesses.** + +- Significantly more complex than single-axis scoring. +- Larger result-set to design and maintain (4 quadrants from 2 dimensions; 8 from 3 dimensions). +- Harder for the audience to predict their result before taking. + +**When to use.** When segmentation is genuinely multi-axis (personality, fit-evaluation, learning style, decision-making style). + +--- + +## Pattern D: Branching logic + +The next question depends on the previous answer. Allows for adaptive questioning. + +**How it works.** + +- The quiz starts with a few common questions. +- Based on early answers, the quiz routes to different question sets. +- Different paths through the quiz produce different results. + +**Example.** + +Question 1: "Do you currently use a CRM?" +- Yes → branch A (questions about current CRM, satisfaction, gaps) +- No → branch B (questions about why not, what would change, current process) + +The two branches produce different question sets that map to different segments. + +**Strengths.** + +- Adaptive; questions feel relevant to the taker. +- Can produce highly specific segmentation. +- Reduces irrelevant questions for any one taker. + +**Weaknesses.** + +- Significantly more complex to build and test. +- Harder to compare segments because not all takers answered the same questions. +- Maintenance is harder; changes to one branch can affect overall scoring. + +**When to use.** When later questions make sense only in the context of earlier ones, when the audience genuinely needs different questions based on their initial situation. + +--- + +## Choice criteria + +Which pattern fits which quiz. + +**Use direct mapping when:** + +- Segments are well-defined and clearly distinguished. +- Each question maps cleanly to one segment. +- Transparency matters (audience benefits from being able to reason about their result). + +**Use weighted scoring when:** + +- Segmentation needs nuance. +- Some questions are more central to segmentation than others. +- Most answers contribute to multiple segments meaningfully. + +**Use multi-dimensional when:** + +- Segmentation is genuinely multi-axis. +- The audience expects a richly textured result (personality assessments, learning styles). +- Each dimension can be measured by a coherent subset of questions. + +**Use branching when:** + +- Later questions depend on earlier context. +- The audience genuinely splits into distinct groups that need different question sets. +- The maintenance complexity is justified by the segmentation value. + +The simplest pattern that produces the right segmentation is usually the best choice. Complexity has cost; only spend it where it produces value. + +--- + +## Tie-breaking + +What happens when two segments score equally. + +**Pattern A: First-tied-segment wins.** The segment that reached the top score first (in the order segments are evaluated) wins. Simple but can introduce bias if the order is not deliberate. + +**Pattern B: Tie-breaker question.** A specific question whose answer breaks the tie. Useful when ties are common. + +**Pattern C: Combined-segment result.** A result for the tie itself ("You are between segment A and segment B"). Useful when the tie is genuinely meaningful. + +**Pattern D: Re-prompt or randomize.** Ask one more clarifying question to break the tie. Adds friction but produces a definitive result. + +**The choice.** Depends on how often ties occur and how meaningful the distinction between tied segments is. If ties are rare and the segments are similar, Pattern A is fine. If ties are common and the segments differ significantly, Pattern B or C is warranted. + +--- + +## Edge-case handling + +What happens at the boundaries of the scoring. + +**The all-segments-zero edge case.** A taker answers in a way that gives zero points to every segment. Rare but possible. Default to the most common segment, or surface a "we could not categorize you" message that prompts re-engagement. + +**The very-high-single-segment edge case.** A taker scores extremely high on one segment, far above any other. Often signals strong segmentation; the result is reliable. + +**The all-segments-equal edge case.** A taker scores equally across all segments. Often signals the questions did not distinguish; the result is unreliable. May warrant a different question set or a different recommendation flow. + +**The contradictory-answers edge case.** A taker's answers contradict each other in ways the scoring did not anticipate. Often surfaces in audit; the question set may need clarification. + +--- + +## Scoring transparency to the user + +Whether to show the score during or after the quiz. + +**Show the score.** When the dimensions or score are themselves meaningful to the user (personality assessments often benefit from showing dimensional scores). + +**Hide the score.** When the score is implementation detail and the segment is the meaningful output (most recommendation quizzes hide the score). + +**Hybrid.** Show segment + a brief explanation of how it was determined. "Your result is X. The questions that most influenced this were Y and Z." + +The choice depends on whether the score helps the user understand or distract from the result. + +--- + +## Algorithm decay + +Scoring algorithms decay along with quizzes. + +**What decays.** + +- Question weights that no longer reflect the segmentation reality. +- Segments that have shifted in audience composition. +- Edge cases that have become more common. + +**Maintenance cadence.** Quarterly review of the scoring algorithm. Audit a sample of takers to confirm results match expectations. + +**Drift indicators.** + +- One segment receiving 70+ percent of takers. +- Audience comments that the result feels wrong. +- Sales-team feedback that quiz-sourced leads are misclassified. + +--- + +## Algorithm testing + +Test the scoring algorithm before launch and after changes. + +**Persona testing.** Create personas representing each intended segment. Take the quiz as each persona; verify each persona reaches the intended segment. + +**Edge-case testing.** Try answer combinations that should produce ties, contradictions, or boundary conditions. Verify the algorithm handles them gracefully. + +**Volume testing.** Run the quiz with synthetic data simulating expected audience composition. Verify segment distribution matches expectations. + +**Production monitoring.** Track segment distribution over time. Sudden shifts may indicate question or scoring issues. + +--- + +## Common scoring failures + +**Algorithm too simple for the segmentation.** Direct mapping when weighted scoring is needed; segments end up poorly distinguished. + +**Algorithm too complex for the segmentation.** Multi-dimensional when single-axis would have served; complexity without value. + +**Hidden bias in weights.** Weights that systematically favor one segment regardless of true audience composition. + +**Tie-breaking arbitrary.** Ties resolved in inconsistent or biased ways. + +**No production monitoring.** Algorithm drifts unnoticed; segment distribution becomes skewed. + +**Scoring not documented.** Future maintainers cannot reason about the algorithm; changes break in unexpected ways. + +--- + +## Methodology-level choices that stay in the public skill + +The four scoring patterns with how-it-works, strengths, weaknesses, and when-to-use guidance. Choice criteria. Tie-breaking patterns. Edge-case handling. Scoring transparency. Algorithm decay and maintenance. Algorithm testing. Common failures. + +## Implementation choices that stay internal + +Specific scoring algorithms for specific quizzes. Specific weights and segment mappings. Specific testing personas. Specific tooling for algorithm implementation and monitoring. These vary by team. diff --git a/dist/pi/.agents/skills/roadmap-planning/SKILL.md b/dist/pi/.agents/skills/roadmap-planning/SKILL.md new file mode 100644 index 0000000..ba9cc5e --- /dev/null +++ b/dist/pi/.agents/skills/roadmap-planning/SKILL.md @@ -0,0 +1,228 @@ +--- +name: roadmap-planning +description: "Build a multi-quarter roadmap from a backlog of ideas, requests, and ongoing initiatives. Use this skill when planning the next quarter, sequencing dependent work, balancing build vs improve vs maintain, or making the case for what NOT to do. Triggers on roadmap, quarterly planning, what should we build next, sequencing, prioritization, OKR planning, capacity planning, what's on the roadmap, plan the year, what to ship next quarter. Also triggers when stakeholders are pulling in different directions and the team needs a defensible plan." +category: product +catalog_summary: "Quarterly planning, prioritization, dependency mapping" +display_order: 2 +--- + +# Roadmap Planning + +Take a pile of ideas, requests, and ongoing work. Produce a defensible plan for what to ship, when, and why. The output is a roadmap document plus the prioritization work that made it credible. + +--- + +## When to use + +- Planning the next quarter or the next year +- Sequencing work where some items depend on others +- Balancing new builds, improvements, and maintenance +- Saying no (or "not yet") to specific requests with a defensible reason +- Aligning a team around a single shared plan +- Communicating the plan to stakeholders outside the team +- Replanning after a strategy shift, a missed quarter, or new constraints + +## When NOT to use + +- Specifying a single feature for development (use `pm-spec-writing`) +- Validating whether the idea is worth building (use `ux-research`) +- Designing the feature itself (use `design-standards`) +- Writing the launch plan for a single initiative (use `launch-runbook`) +- Reviewing what shipped vs what was promised (use `after-action-report`) + +--- + +## Required inputs + +- The team's strategy or top-level goals (1 to 5 OKRs, themes, or pillars) +- The backlog: every candidate item, with at least a one-sentence description +- The team's capacity (people × time) +- Known constraints (deadlines, dependencies, hiring, budget) +- The planning horizon (a quarter, two quarters, a year) + +If the strategy is missing, the roadmap will be a list of features, not a plan. Push back and get the strategy first. A roadmap without strategy is just a queue. + +--- + +## The framework: 5 layers + +Roadmaps fail at five different layers. A roadmap is only as good as its weakest one. + +### Layer 1: Themes (the WHY) + +Top-level groupings tied to strategy. Every theme answers: "If we do nothing else this period, this is the outcome we want." + +Good themes are: +- Outcome-shaped, not feature-shaped ("Reduce time-to-first-value" beats "Build onboarding") +- Limited (3 to 5 max) +- Defensible (you can explain why this and not something else) +- Measurable (each maps to one or two metrics) + +Bad themes look like a junk drawer: "Improvements," "Tech debt," "Misc." If it can't be defended in one sentence, it isn't a theme. + +### Layer 2: Initiatives (the WHAT) + +Multi-week or multi-month efforts that ladder up to a theme. Each initiative is bigger than a feature but smaller than a theme. Initiatives have: + +- A clear outcome (the metric or result it should produce) +- A rough size (S / M / L / XL) +- A confidence rating (how sure are we this is the right initiative?) +- A dependency map (what has to happen first) + +Initiatives are where stakeholders push hard. Resist the urge to commit to dates here. Commit to outcomes and rough sizes. + +### Layer 3: Sequencing (the WHEN) + +The order things happen. Sequencing is constrained by: + +- **Dependencies** (X must finish before Y can start) +- **Capacity** (the team can do N things at once) +- **Calendar reality** (Q4 has fewer working days, certain teams have hiring gaps) +- **Strategic windows** (some launches need to land before a season, conference, or competitive moment) + +Build the sequence after the prioritization. Putting things in time-order before deciding what matters produces a plan optimized for calendar fit, not impact. + +### Layer 4: Capacity reality (the HOW MUCH) + +Most roadmaps fail here. The plan looks good on paper but assumes 100% of every person's time on roadmap work. Real capacity is much lower. + +Default capacity assumptions: + +- Engineers: 60-70% of time on roadmap initiatives. The rest is meetings, reviews, on-call, support, interviews, debugging, ramp-up. +- Designers: 50-60%. Same reasons plus more cross-team support. +- PMs: 40-50%. The rest is planning, comms, stakeholder management, async writing. +- New hires: assume 50% of full capacity for the first quarter, 75% for the second, 100% from Q3 on. +- On-call rotations, leave, holidays: subtract before sizing. + +If the math says the plan needs 100% of the team, the plan is wrong. Cut. + +### Layer 5: Trade-off communication (the WHY NOT) + +Every roadmap has a "Not now" list as important as the "Doing" list. The "Not now" is what makes the plan defensible. + +Include: +- The top requests you considered and rejected +- The reason for each rejection (not the right time, not the right size, conflicts with theme, lower expected impact) +- The condition that would make it move into "Doing" (a metric, a date, a finished prerequisite) + +Stakeholders pushing for cut items can argue against the rejection criteria, not the omission. That's a productive argument. + +--- + +## Workflow + +### Step 1: Anchor the strategy + +Before touching the backlog, write down 3 to 5 themes. If the team's OKRs or strategy doc gives you these, copy them. If not, draft them and validate with the people who own strategy. + +If the strategy is missing or vague, stop. Producing a roadmap against an unclear strategy is worse than producing nothing. Surface the gap. + +### Step 2: Catalog the backlog + +Every candidate gets: +- Name (one phrase) +- Theme it ladders up to (or "no theme" - flag for later) +- Source (request, OKR, retro, customer feedback, leadership ask, technical need) +- Rough size (S / M / L / XL) +- Owner or proposed owner +- Status (idea, validated, scoped, ready) + +Items with "no theme" are warning flags. Either the theme list is incomplete, or the item should be cut. + +### Step 3: Prioritize within each theme + +Inside each theme, rank the initiatives. Use one prioritization framework consistently. Common ones: + +- **RICE** (Reach × Impact × Confidence ÷ Effort): good for feature-heavy roadmaps +- **MoSCoW** (Must / Should / Could / Won't): good for fixed-deadline projects +- **Kano** (Threshold / Performance / Excitement): good for product investment decisions +- **Cost of delay**: good when timing matters more than effort +- **Strategic alignment + impact**: good for executive-facing roadmaps + +The framework matters less than the consistency. Pick one. Use it the same way for every initiative. Document the math. + +See [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) for the full breakdown. + +### Step 4: Build the dependency map + +For every "Doing" initiative, list what must happen first: +- Other initiatives +- Hiring +- External dependencies (vendor delivery, partner readiness) +- Research or validation work +- Infrastructure or platform readiness + +Visualize as a graph or a Gantt-style sequence. Items with no dependencies can start immediately. Items with multiple unmet dependencies are warning flags. + +### Step 5: Lay out the sequence + +Now place initiatives in time. Use the dependency map. Use the capacity math. Match initiatives to people who can actually do them. + +Default cadence: month-by-month for one quarter, quarter-by-quarter beyond that. Weekly is too granular for most roadmaps. Half-year buckets are too vague to commit to. + +### Step 6: Validate with the team + +Before sharing externally, validate with the people doing the work: +- Are the size estimates realistic? +- Are the dependencies correctly mapped? +- Are the capacity assumptions accurate? +- Is anyone overcommitted? + +If the team says the plan is impossible, the plan is impossible. Adjust. Going to leadership with a plan the team disagrees with is how trust gets broken. + +### Step 7: Write the "Not now" list + +For every "Doing" item, name what got cut to make room. Document why. Document the trigger that would move it to "Doing" later. + +### Step 8: Communicate + +Different audiences need different views: + +- **Team:** detailed sequence, owners, dependencies, sizes +- **Cross-functional partners:** themes, initiatives, rough timing, what they need to provide +- **Leadership:** themes, expected outcomes, key initiatives, top trade-offs +- **Public or customer-facing:** themes, no specific dates, "what to expect" + +The same roadmap should produce all four. If it can't, the roadmap is incomplete. + +--- + +## Failure patterns + +**A list of features instead of a plan.** Themes are missing. The roadmap is a backlog with months attached. Fix: start over from strategy. + +**Date-driven thinking.** "What can we ship by end of Q2?" instead of "What is the most important thing to do in Q2?" Dates are constraints, not goals. + +**Capacity fantasy.** The plan adds up to 100% of every person's time. No room for support, interrupts, planning, or unknown unknowns. Roadmap dies in week three. + +**Stakeholder pressure overrides strategy.** A loud customer or executive request gets prioritized because they pushed hard, not because it ladders up. The "Not now" list saves you here. + +**Missing dependencies.** Initiative B depends on initiative A, but A is scheduled later. Or A depends on a hire that hasn't happened. The plan looks fine until execution starts. + +**Too far out.** Specific commitments six months out create promises the team can't keep. Use ranges or themes for far horizons, specifics for near horizons. + +**One framework for every level.** RICE for the whole roadmap including platform work, infra, and exploration. RICE is great for features, weak for foundational work. Use different lenses for different initiative types. + +**No "Not now."** Stakeholders rediscover their cut requests every two weeks because there's no record of why they were cut. Document once, point to it forever. + +--- + +## Output format + +The roadmap document includes: + +- **Strategy summary** (1 page or section): themes, why these themes, how they ladder to top-level goals +- **The plan** (the visual): a quarter-by-quarter or month-by-month view, color-coded by theme +- **Initiative briefs** (one per initiative): outcome, size, owner, dependencies, success metric +- **Capacity model**: who is doing what, with utilization math +- **Trade-offs and "Not now"**: top items considered and rejected, with reasons +- **Risks and assumptions**: what could derail the plan +- **Update cadence**: when the roadmap will be revisited (monthly is typical) + +The roadmap is a living document. Plan to revisit it monthly. Replan it formally each quarter. Do not treat it as a contract. + +--- + +## Reference files + +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Detailed breakdown of RICE, MoSCoW, Kano, Cost of Delay, and Strategic Alignment frameworks. When to use each, how to apply them, common mistakes. diff --git a/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md b/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md new file mode 100644 index 0000000..fead81c --- /dev/null +++ b/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md @@ -0,0 +1,192 @@ +# Prioritization Frameworks + +Five frameworks for prioritizing work. Each suits different problems. Pick one per planning cycle. Use it consistently. + +--- + +## RICE + +Best for: feature-heavy roadmaps where features are roughly comparable in shape. + +### The math + +``` +RICE Score = (Reach × Impact × Confidence) ÷ Effort +``` + +- **Reach:** how many people will this affect in a fixed period (e.g., users per quarter). Use real numbers, not relative scores. +- **Impact:** how much will it affect each person? Use a fixed scale: 3 (massive), 2 (high), 1 (medium), 0.5 (low), 0.25 (minimal). +- **Confidence:** how sure are you in the estimates? 100% (high), 80% (medium), 50% (low). Below 50%, you don't know enough to score. +- **Effort:** total person-months to deliver. Be honest. Include design, dev, QA, launch. + +Higher score = higher priority. + +### Where it shines + +Comparing many similarly-shaped feature ideas. Forces conversation about the inputs (Reach, Impact, Confidence) instead of a gut "I think this is more important." + +### Where it fails + +- Foundational work (infra, platform, refactors). Reach and Impact don't apply cleanly. +- Strategic bets where Confidence is low but the upside is huge. RICE punishes low-confidence work. +- "Cost of inaction" items (security, compliance). These often score badly but must ship. + +### Common mistakes + +- Inventing Reach numbers without a basis. If you don't have data, your Reach is a guess wrapped in math. +- Effort estimates that come from PMs, not engineers. Effort is always the engineer's call. +- Treating Impact as a continuous variable. The scale is fixed for a reason - so it's comparable. +- Re-scoring each cycle without checking what shipped last cycle and what its actual Reach × Impact turned out to be. + +--- + +## MoSCoW + +Best for: fixed-deadline projects where you have to decide what's in scope and what isn't. + +### The buckets + +- **Must have:** without these, the project fails. Non-negotiable for launch. +- **Should have:** important but not deal-breaking. Plan to include unless capacity tightens. +- **Could have:** nice to include if there's room. First to be cut. +- **Won't have (this time):** explicitly out of scope. Documented to prevent drift. + +### Where it shines + +Deadline-driven launches. New site builds. Migrations. Anything with a fixed go-live date. + +### Where it fails + +- Open-ended product work without a hard deadline. Everything tends to drift to "Must have." +- Long-running platforms. The buckets don't help sequence multi-quarter work. + +### Common mistakes + +- "Must have" creeping. By the end of planning, 80% of items are Must. Hard rule: "Must have" should be 30-50% of items, never more. +- No "Won't have." The "Won't have" list is the discipline. Without it, scope grows. +- Ambiguous lines between Must and Should. Define each explicitly. "If we ship without X, will the product work?" If yes, X is Should, not Must. + +--- + +## Kano + +Best for: product investment decisions about feature investment vs polish vs new bets. + +### The categories + +- **Threshold features:** users expect them. Their absence causes dissatisfaction. Their presence is barely noticed. (Examples: a working login. Email password reset.) +- **Performance features:** users notice them and value them linearly. More is better. (Examples: speed, search relevance, design quality.) +- **Excitement features:** users don't expect them. Their presence is delight. Their absence is unnoticed. (Examples: a clever zero state, an unexpected automation.) + +### How to use + +Audit the product. Categorize every feature. Decide where to invest: + +- Threshold features must be present and working. Underinvestment is a tax on everything else. +- Performance features should get sustained investment. They are how the product stays competitive. +- Excitement features are the differentiation budget. Spend selectively, expect them to age into Performance and eventually Threshold. + +### Where it shines + +Product strategy conversations. "Should we polish what we have or ship something new?" Kano answers it: are the Thresholds shipped? Then Performance. Then Excitement. + +### Where it fails + +- Doesn't help with sequencing among features in the same category. +- The categories shift over time. Today's Excitement is tomorrow's Threshold. + +### Common mistakes + +- Treating Excitement as the most valuable category. It's not. Threshold gaps will sink you faster than missing Excitement features. +- Confusing Excitement with novelty. Many "innovative" features are just Performance features in disguise. + +--- + +## Cost of Delay + +Best for: portfolios where timing matters more than effort, especially under capacity constraints. + +### The math + +``` +Cost of Delay per Week = Value Lost Per Week the Item Doesn't Ship +``` + +For each candidate, estimate: if we delay this by one week, what does it cost in revenue, retention, market position, or risk? + +Then divide by effort: + +``` +Cost of Delay Divided by Duration (CD3) = Cost of Delay per Week ÷ Duration in Weeks +``` + +The highest CD3 ships first. + +### Where it shines + +Sequencing inside a constrained team. Surfaces items where every week of delay matters (compliance deadlines, seasonal launches, competitive responses). + +### Where it fails + +- Estimating Cost of Delay is hard. Many items have qualitative cost ("brand damage," "team morale") that resists numerical estimates. +- Bias toward urgent over important. Recurring time-sensitive items (deadlines, customer escalations) keep beating strategic work. + +### Common mistakes + +- Treating all delays as having the same cost shape. Some items have flat cost (delay a week or a year, same outcome). Others have step changes (miss a deadline, lose 80% of the value). +- Ignoring the cost of NOT delaying (opportunity cost from working on this instead of something else). + +--- + +## Strategic Alignment + Impact + +Best for: executive-facing roadmaps and any planning where the question is "should we do this at all?" + +### The matrix + +A 2×2 grid: Strategic Alignment (low/high) on one axis, Impact (low/high) on the other. + +- **High alignment / High impact:** ship now. Resource heavily. +- **High alignment / Low impact:** ship if cheap. Question if expensive. +- **Low alignment / High impact:** dangerous. Either redefine strategy or cut. Items here drag the team away from the plan. +- **Low alignment / Low impact:** cut. Always. + +### Where it shines + +Cutting noise from the backlog. The bottom-right quadrant (Low/Low) is where most of the noise lives, and the matrix makes it obvious. + +Communicating with leadership. "This is high impact but not aligned" is a defensible reason to deprioritize. + +### Where it fails + +- Doesn't sequence within quadrants. Inside "High/High," you still need a tiebreaker. +- "Strategic alignment" is judgment, not math. Different people will plot the same item differently. + +### Common mistakes + +- Plotting everything as High/High to avoid the conversation. The matrix is only useful if there's a Low quadrant. +- Treating Strategic Alignment as fixed. Strategy changes. Re-plot every cycle. + +--- + +## Picking a framework + +| If your team is... | Use | +|---|---| +| Building features for a product, comparable in shape | RICE | +| Launching against a fixed deadline | MoSCoW | +| Deciding investment levels across product areas | Kano | +| Sequencing under capacity constraints with timing-sensitive items | Cost of Delay | +| Cutting noise and aligning with leadership | Strategic Alignment + Impact | + +You can use more than one in a single planning cycle, but apply each consistently within its scope. Don't switch frameworks halfway through to justify a pre-decided answer. + +--- + +## The meta-rule + +Every framework has known weaknesses. Every framework can be gamed by stakeholders who learn how the math works. + +The frameworks are conversation tools, not decision tools. Their value is forcing the team to articulate inputs (reach, impact, alignment, urgency) instead of arguing about outputs. + +A good roadmap can be defended without the framework. The framework is the work, not the result. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md b/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md new file mode 100644 index 0000000..1057df6 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md @@ -0,0 +1,273 @@ +--- +name: scheduler-and-booking-design +description: "Designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic Calendly link. Availability logic, qualification gating, prep automation, follow-up sequencing. Honest about any-time-friction (no qualification, just a booking link), interrogation-gate (so much qualification it scares users off), and qualified-fast-path (just enough qualification to set up the call well) patterns. Triggers on scheduler design, meeting booking, demo scheduling, sales call scheduling, calendar tool, booking page, qualification flow. Also triggers when sales team complains about cold demos, when booking conversion is poor, or when scheduler is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing schedulers and booking flows. Distinguishes any-time-friction (no qualification, just a booking link) from interrogation-gate (so much qualification it scares users off) from qualified-fast-path (just enough qualification to set up the call well)" +display_order: 10 +--- + +# Scheduler and Booking Design + +A senior growth practitioner's playbook for designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic booking link. Availability logic, qualification gating, prep automation, follow-up sequencing. The discipline of building a scheduler that earns the booking by earning a better call. + +Most schedulers fail in one of two ways. Generic booking links produce cold demos where reps know nothing about the person they are about to talk to. Conversion stays at the rate of unqualified raw demos. Or qualification forms with 12 fields scare users off before they can book; drop-off at the form approaches 90 percent; only the leads who happen to survive the form actually convert. + +The schedulers that work do something different. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads route differently), prep automation that briefs the rep before the call. The booking is honest about who the audience is; the call is set up to succeed. + +The voice is the senior growth practitioner who has watched schedulers double demo conversion when redesigned and watched them collapse when more qualification was added. Practical, opinionated about which fields earn their place, willing to call out when the booking flow is the wrong tool. + +When to use this skill: scoping a scheduler for the first time, auditing a booking flow with poor conversion or poor downstream call quality, designing the qualification gate that produces context without producing friction, or deciding routing logic that matches leads to the right reps. + +--- + +## What this skill covers + +This skill spans meeting schedulers and booking experiences across acquisition and sales contexts. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access to anything). This skill is meeting-booking specifically; qualification fields exist but the goal is the call, not the data. +- `funnel-flow-architecture` is broader funnel architecture. This skill is the scheduler specifically. +- `lead-magnet-design` is different commitment level. Magnets earn an email; bookings earn time. +- **`scheduler-and-booking-design` (this skill)** is the qualification, availability, routing, prep automation, and follow-up sequencing for meetings. +- `pm-spec-writing` is the spec for engineers building the scheduler. + +The audience: growth marketers, product marketers, marketing operations leads, sales operations leads, agencies running booking optimization for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); broader funnel orchestration (covered by `funnel-flow-architecture`); the engineering implementation; specific Calendly/Cal.com/Chili Piper/SavvyCal platform configurations (those stay implementation-side). + +--- + +## The booking-flow decision: scheduler vs forms vs sales-pipeline tools + +Before designing the scheduler, decide whether a scheduler is the right tool. + +**Schedulers earn investment when:** + +- The conversion goal is a meeting (demo, sales call, consultation). Email-only conversions do not need a scheduler. +- The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. +- The team has enough sales or success capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. +- The team can support qualification logic and routing. Without these, a generic booking link is the result. + +**Schedulers do NOT earn investment when:** + +- The conversion goal is a download or signup. Use forms or magnet flows. +- The audience volume is too low for routing logic. A handful of bookings per month does not need infrastructure. +- The team's capacity is variable and routing cannot reflect that. Scheduling without capacity awareness produces no-shows on both sides. +- A simpler contact form would serve the same purpose. + +The decision is not "should we have a scheduler"; it is "is the scheduler the right next investment for this audience and goal." + +Detail in [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md). + +--- + +## Any-time-friction vs interrogation-gate vs qualified-fast-path + +The keystone framing. + +**Any-time-friction.** Generic booking link with no qualification, no context capture. Reps show up to calls cold; they spend the first 10 minutes asking the same qualification questions the form should have captured. Conversion stays at the rate of unqualified raw demos. Cost: sales capacity used inefficiently; high-fit leads get the same experience as low-fit leads; downstream conversion suffers. + +**Interrogation-gate.** Qualification form with 12 fields before the user can book. Drop-off at the form approaches 90 percent. The qualification works for the leads who survive but the system loses everyone else. Cost: high-fit leads who would have converted abandon at the form; conversion rate is poor even though the post-form leads are well-qualified. + +**Qualified-fast-path.** Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads see SDRs or are routed to async), prep automation that briefs the rep before the call. Cost: design effort upfront is significant; conversion plus downstream call quality both improve meaningfully. + +The litmus test. Does the rep arrive at the call already knowing the prospect's situation? Did the prospect feel respected by the booking experience? If yes to both, qualified-fast-path. If the rep starts cold, any-time-friction. If the prospect dropped at the form, interrogation-gate. + +--- + +## Qualification field design + +Which fields earn their place; which create friction. + +**The principle.** Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +**Strong qualification fields.** + +- **Company size or team size.** Routes to the right rep tier; enables enterprise vs SMB tracking. +- **Use case or primary goal.** Lets the rep prepare for the conversation that matches. +- **Current solution or stack.** Tells the rep where the prospect is starting. +- **Timeline or urgency.** Routes to active-pipeline vs nurture. +- **Role or job function.** Lets the rep tailor framing. + +**Weak qualification fields.** + +- **Phone number** (often unnecessary if email and meeting time are captured). +- **Generic comments box** (free-text; rarely informs prep). +- **Marketing data not used in the call** (industry codes, lead-source detail). +- **Demographic data unrelated to the call** (gender, age). + +**The five-field rule.** Most production schedulers work well with 3-5 qualification fields. More than 5 starts producing interrogation-gate dynamics. Less than 3 does not give the rep useful prep context. + +Detail in [`references/qualification-field-design.md`](references/qualification-field-design.md). + +--- + +## Availability logic + +Round-robin, weighted by fit, calendar integration. + +**Pattern A: Pure round-robin.** Bookings cycle through available reps in order. + +When to use. Simple distribution; small teams. + +Strengths. Even distribution; simple logic. + +Weaknesses. Does not match high-fit leads to senior reps; does not load-balance based on capacity. + +**Pattern B: Weighted round-robin.** Bookings cycle but weighted by rep performance, capacity, or specialty. + +When to use. Teams with rep specialization; teams where capacity differs. + +**Pattern C: Fit-based routing.** High-fit leads (large company, high urgency) route to senior reps; lower-fit leads route to SDRs or async resources. + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +**Pattern D: Hybrid.** Combines patterns. Fit-based routing for top tier; round-robin within tier. + +When to use. Most production teams. + +**The match-to-rep discipline.** The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +Detail in [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md). + +--- + +## Routing patterns + +Different reps for different lead types. + +**By company size.** SMB to SDRs, mid-market to AEs, enterprise to senior AEs. + +**By use case.** Different specialists for different product use cases. + +**By geography.** Different reps for different time zones or regions. + +**By language.** Native-language reps for non-English-primary leads. + +**By account ownership (B2B).** If the lead's company is already a customer or prospect of an AE, route to that AE. + +**The unrouted lead.** Some leads do not fit obvious routing. Default rule needed: round-robin or specific catchall. + +Detail in [`references/routing-patterns.md`](references/routing-patterns.md). + +--- + +## Prep automation + +Briefing the rep before the call. + +**The principle.** The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused. + +**Prep automation patterns.** + +- **CRM enrichment.** Qualification data populates the CRM record; rep sees it in their pre-call review. +- **Calendar invite enrichment.** Qualification data appears in the meeting invite description; rep sees it on their calendar. +- **Slack or email brief.** Pre-call brief sent to the rep with synthesized prospect info. +- **Account research.** Qualification data triggers automated research (company size verification, recent news). + +**Strong prep automation.** The rep arrives at the call already knowing: who the prospect is, what they are trying to accomplish, what they are using today, when they need a solution. + +**Weak prep automation.** The rep has the qualification data but it is buried in a CRM field nobody opens. The rep starts the call cold despite the data. + +Detail in [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md). + +--- + +## Confirmation and reminder sequences + +The communications around the booking. + +**Booking confirmation.** Sent immediately after booking. Confirms time; restates context; sets expectations. + +**Pre-meeting reminder.** Sent 24 hours and/or 1 hour before. Reduces no-shows. + +**Post-meeting follow-up.** Sent within hours of the call. Recap; next steps; resources. + +**Reschedule and no-show flows.** Different flows for different outcomes. + +**The reminder discipline.** Reminders are useful; over-reminding is friction. Two reminders (24-hour and 1-hour) is typical. + +Detail in [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md). + +--- + +## Reschedule and no-show handling + +What happens when meetings do not go to plan. + +**Reschedule patterns.** + +- Easy self-serve reschedule (no friction). +- Reschedule preserves qualification data. +- Reschedule notifies the rep proactively. + +**No-show patterns.** + +- Auto-detect (rep reports no-show; or system detects unattended meeting). +- Follow-up to the prospect (gentle; not punitive). +- Re-engagement sequence (one or two attempts to rebook). +- Eventual deactivation (do not pursue forever). + +**The respect-the-no principle.** Prospects who no-show twice often do not want the meeting. Multiple aggressive reschedule attempts feel like pressure. + +Detail in [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md). + +- "Booking conversion is high; demo conversion to sale is low." Qualification too thin; cold demos do not convert. +- "Booking conversion is low; demo conversion to sale is high." Interrogation-gate; qualification scares off would-be buyers. +- "Sales says many bookings come from wrong-fit leads." Routing logic not connecting qualification to rep tier. +- "No-show rate is over 30 percent." Reminder sequence broken; or commitment friction at booking too low. +- "Reps complain they get no context before calls." Prep automation broken; data captured but not delivered to rep. +- "Calendar integration breaks every few weeks." Brittle integration; or rep calendar permissions changing. +- "Mobile booking conversion is half of desktop." Mobile UX issue. +- "Booking link gets shared by reps; routing logic bypassed." Generic link in use alongside structured flow; bypass undermines routing. +- "Round-robin produces uneven workload." Reps with different capacity treated equally. + +--- + +## The framework: 12 considerations for scheduler and booking design + +When designing or auditing a scheduler, walk these 12 considerations. + +1. **The booking-flow decision.** Is a scheduler the right tool, or a form / sales-pipeline tool? +2. **Qualified-fast-path, not any-time-friction or interrogation-gate.** Just enough qualification to set up the call well. +3. **Qualification fields earn their place.** 3-5 fields; each routes or preps. +4. **Availability logic matches team structure.** Round-robin, weighted, fit-based, or hybrid. +5. **Routing connects qualification to rep tier.** High-fit leads to senior reps. +6. **Prep automation delivers data to reps.** CRM enrichment, calendar invite, Slack brief. +7. **Confirmation and reminders reduce no-shows.** 24-hour and 1-hour typical. +8. **Reschedule is friction-low.** Self-serve; preserves data. +9. **No-show flow honest.** Re-engagement attempts limited; respect non-response. +10. **Mobile parity.** Booking works on the devices the audience uses. +11. **Conversion to sale as success metric.** Not just booking rate; downstream call-to-sale conversion. +12. **Maintenance discipline.** Routing rules updated as team changes; quarterly audit. + +The output of the framework is a scheduler that earns the booking by earning a better call, with conversion that compounds because the calls themselves are better. + +--- + +## Reference files + +- [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md) - When schedulers earn the build vs when forms or sales-pipeline tools serve. +- [`references/qualification-field-design.md`](references/qualification-field-design.md) - Strong and weak qualification fields. The five-field rule. +- [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md) - Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. +- [`references/routing-patterns.md`](references/routing-patterns.md) - By size, use case, geography, language, account ownership. Unrouted-lead default. +- [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md) - CRM enrichment, calendar invite, Slack brief, account research. +- [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md) - Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. +- [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md) - Reschedule patterns, no-show patterns, respect-the-no principle. +- [`references/scheduler-anti-patterns.md`](references/scheduler-anti-patterns.md) - The patterns that look like schedulers but degrade conversion. +- [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: schedulers earn the booking when they earn the better call + +The schedulers that work as compounding assets are the ones that produce better calls. Not just more bookings. Calls where the rep arrives prepared; the prospect feels respected; the conversation moves faster because qualification was already done. Conversion compounds because the calls themselves convert better. + +That is the bar. Below the bar are any-time-friction (cold demos, conversion suffers) and interrogation-gate (90 percent abandon at the form). Above the bar are qualified-fast-path schedulers where qualification, availability, routing, prep automation, and follow-up sequencing combine into a system that earns the booking and the call. + +The discipline is in the design choices. The decision to use a scheduler at all. The qualification fields that earn their place. The availability logic that matches lead to rep. The routing that respects rep tier and capacity. The prep automation that delivers context to reps before the call. The reminder cadence that reduces no-shows without becoming spam. The reschedule and no-show handling that respects the prospect. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md new file mode 100644 index 0000000..a2c9192 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md @@ -0,0 +1,272 @@ +# Availability logic patterns + +Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. + +How the scheduler decides which rep gets which booking. Done well, availability logic distributes load while matching high-fit leads to senior reps; done poorly, leads land on the wrong reps and conversion suffers. + +--- + +## The match-to-rep principle + +The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +**The win.** A high-fit enterprise lead (large company, urgent timeline) sees availability for senior AEs. Low-fit lead (small team, exploring) sees availability for SDRs. Each lead gets the right call. + +**The fail.** Same scheduler with pure round-robin. Enterprise lead lands on an SDR; SDR is unprepared; conversion drops. + +The discipline. Routing is not separate from qualification; the two are coupled. + +--- + +## Pattern A: Pure round-robin + +Bookings cycle through available reps in order. + +**How it works.** + +- Available reps in the queue. +- Each booking goes to the next rep. +- Cycle continues. + +**Strengths.** + +- Even distribution. +- Simple logic. +- Easy to explain to the team. + +**Weaknesses.** + +- Does not match high-fit leads to senior reps. +- Does not load-balance based on capacity. +- Does not account for rep specialization. + +**When to use.** Small teams; reps are interchangeable; volume is low. + +--- + +## Pattern B: Weighted round-robin + +Bookings cycle but weighted by rep performance, capacity, or specialty. + +**How it works.** + +- Each rep has a weight (performance score, capacity, etc.). +- Distribution skews toward higher-weighted reps. +- Still distributes; just unevenly. + +**Strengths.** + +- Higher-performing reps get more bookings. +- Capacity differences accommodated. + +**Weaknesses.** + +- Lower-performing reps get fewer learning opportunities. +- Weighting must be maintained. + +**When to use.** Teams with significant rep performance differences; teams where capacity differs. + +--- + +## Pattern C: Fit-based routing + +High-fit leads route to senior reps; lower-fit leads route to SDRs or async resources. + +**How it works.** + +- Qualification fields determine fit score. +- High-fit leads see availability for senior reps only. +- Lower-fit leads see availability for SDRs. + +**Strengths.** + +- Senior reps focus on high-value conversations. +- SDRs handle qualification and nurture. +- Resource allocation matches lead value. + +**Weaknesses.** + +- Requires clear fit signals from qualification. +- May produce uneven workload (senior reps light, SDRs heavy). + +**When to use.** Teams with multi-tier sales motion; clear fit signals captured. + +--- + +## Pattern D: Specialty-based routing + +Bookings route to reps with specific expertise. + +**How it works.** + +- Qualification captures use case or industry. +- Bookings route to the rep with matching specialty. + +**Strengths.** + +- Rep is genuinely prepared for the specific conversation. +- Higher conversion when specialty matches. + +**Weaknesses.** + +- Specialist reps can become bottlenecks. +- Requires per-rep specialty tagging. + +**When to use.** Products with multiple distinct use cases or verticals. + +--- + +## Pattern E: Account-ownership routing (B2B) + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +**How it works.** + +- Qualification or domain matching detects existing-account leads. +- Bookings route to the AE who owns the account. +- Override default routing. + +**Strengths.** + +- Account owner has context. +- Avoids confusion of multiple reps on the same account. + +**Weaknesses.** + +- Requires CRM integration to detect ownership. +- Account ownership must be current. + +**When to use.** B2B teams with account-ownership models. + +--- + +## Pattern F: Hybrid + +Combining patterns. Most production teams use hybrid. + +**Common combinations.** + +- Account-ownership routing first (existing accounts to AEs). +- Then fit-based routing (high-fit new leads to senior AEs). +- Then specialty-based routing within tier. +- Then round-robin within remaining pool. + +**Strengths.** + +- Handles common cases. +- Routes lead to best-matched rep. + +**Weaknesses.** + +- More complex to maintain. +- More edge cases to handle. + +**When to use.** Mature production teams with multi-tier sales motion. + +--- + +## Calendar integration + +How availability connects to actual calendars. + +**Direct calendar integration.** Scheduler reads rep calendars; shows actual availability. + +Strengths. No double-booking; reflects reality. + +Weaknesses. Requires calendar permissions; integration brittle. + +**Office hours definition.** Reps define availability windows; scheduler shows those. + +Strengths. Simpler integration; no calendar permissions needed. + +Weaknesses. Manual maintenance; reps may forget to update. + +**Hybrid.** Scheduler uses office hours plus calendar busy/free for fine-grain. + +Strengths. Resilient to integration issues. + +Weaknesses. More complex. + +--- + +## Buffer time + +Time between meetings. + +**Why it matters.** Back-to-back meetings produce rushed reps and late starts. Buffer protects rep effectiveness. + +**Common buffers.** 10-15 minutes between meetings. + +**The discipline.** Buffer should be in the calendar logic, not optional. + +--- + +## Capacity caps + +How many meetings per day per rep. + +**Why caps matter.** Reps booked solid produce poor calls; quality drops; conversion suffers. + +**Common caps.** 3-5 demos per day per rep typical for B2B SaaS. + +**The discipline.** Caps respect rep effectiveness, not just calendar availability. + +--- + +## Time zone handling + +The scheduler shows availability in the prospect's time zone. + +**The principle.** Display in prospect's time zone; reps see in their own. + +**Common patterns.** + +- Auto-detect from browser; show prospect that detection. +- Allow manual override. +- Display rep's time zone for clarity ("PT" badge). + +**Anti-pattern.** Showing all times in rep's time zone; prospect has to convert mentally. + +--- + +## Out-of-office and holiday handling + +Real life intervenes. + +**Patterns.** + +- Calendar integration handles vacation as busy time. +- Manual office-hours updates handle planned absences. +- Holiday calendars block company-wide closures. + +**The discipline.** Out-of-office should be respected automatically; otherwise no-shows happen. + +--- + +## Common availability failures + +**Pure round-robin for tiered teams.** High-fit leads land on junior reps. + +**No capacity caps.** Reps overbooked; quality drops. + +**No buffer.** Meetings run late; reps are stressed. + +**Time zone confusion.** Prospect sees rep's time zone; bookings happen at wrong times. + +**Stale rep weights.** Weighted round-robin uses last-quarter performance; recent changes ignored. + +**Specialty routing without specialty data.** Specialty-based routing requires per-rep tagging; missing tags route incorrectly. + +**Account-ownership not detected.** Existing-account lead bounces around between reps. + +**Calendar integration broken.** Double-bookings happen; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The match-to-rep principle. Patterns A through F (round-robin, weighted, fit-based, specialty, account-ownership, hybrid). Calendar integration. Buffer time. Capacity caps. Time zone handling. Out-of-office and holiday handling. Common failures. + +## Implementation choices that stay internal + +Specific routing logic for specific teams. Specific weights and caps. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md new file mode 100644 index 0000000..be02c42 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md @@ -0,0 +1,179 @@ +# Common scheduler failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Booking conversion is high; demo conversion to sale is low." + +**The diagnosis.** Qualification too thin; cold demos do not convert. + +**The cure.** Add 3-5 strategic qualification fields. Detail in `references/qualification-field-design.md`. + +--- + +## "Booking conversion is low; demo conversion to sale is high." + +**The diagnosis.** Interrogation-gate; qualification scares off would-be buyers. + +**The cure.** Cut qualification to 3-5 fields. Defer non-essential questions to in-call. + +--- + +## "Sales says many bookings come from wrong-fit leads." + +**The diagnosis.** Routing logic not connecting qualification to rep tier. + +**The cure.** Add fit-based routing. Detail in `references/routing-patterns.md`. + +--- + +## "No-show rate is over 30 percent." + +**The diagnosis.** Reminder sequence broken; or commitment friction at booking too low. + +**The cure.** Audit reminder cadence. Strengthen pre-meeting communications. Detail in `references/reminder-sequence-patterns.md`. + +--- + +## "Reps complain they get no context before calls." + +**The diagnosis.** Prep automation broken; data captured but not delivered. + +**The cure.** CRM enrichment, calendar invite enrichment, Slack brief. Detail in `references/prep-automation-patterns.md`. + +--- + +## "Calendar integration breaks every few weeks." + +**The diagnosis.** Brittle integration; or rep calendar permissions changing. + +**The cure.** Monitor integration; fix permissions; have a manual fallback for downtime. + +--- + +## "Mobile booking conversion is half of desktop." + +**The diagnosis.** Mobile UX issue. + +**The cure.** Mobile-first design and testing. + +--- + +## "Booking link gets shared by reps; routing logic bypassed." + +**The diagnosis.** Generic link in use alongside structured flow. + +**The cure.** Disable generic links. Train reps; provide rep-specific structured links if needed. + +--- + +## "Round-robin produces uneven workload." + +**The diagnosis.** Reps with different capacity treated equally. + +**The cure.** Weighted round-robin or capacity-aware routing. + +--- + +## "Time zone errors cause no-shows." + +**The diagnosis.** Time zone display unclear or auto-detection wrong. + +**The cure.** Display time zone clearly at booking and in invites. Auto-detect prospect time zone; allow override. + +--- + +## "Reps reschedule manually frequently." + +**The diagnosis.** Routing produces wrong-fit bookings; reps fix manually. + +**The cure.** Audit routing logic; fix the source of the wrong-fit bookings. + +--- + +## "Conversion was strong; quality dropped after sales team change." + +**The diagnosis.** New rep tier or specialization mix; routing not updated. + +**The cure.** Routing rules updated as team changes. Quarterly review. + +--- + +## "We added more qualification fields; conversion dropped." + +**The diagnosis.** Crossed the five-field threshold. + +**The cure.** Cut back. Five-field rule from `references/qualification-field-design.md`. + +--- + +## "Some segments convert; others do not." + +**The diagnosis.** Single scheduler treats all segments the same. + +**The cure.** Per-segment qualification or routing. Different segments may need different schedulers. + +--- + +## "Schedulers work for direct traffic; partner-sourced leads convert poorly." + +**The diagnosis.** Partner-sourced leads have different fit profile; routing or qualification not adapted. + +**The cure.** Source-based routing. Partner leads may need different rep tier or different prep. + +--- + +## "We tried different reminder cadences; no-shows did not move." + +**The diagnosis.** No-show may not be reminder-driven. Could be commitment friction at booking, time zone errors, or audience mismatch. + +**The cure.** Test other variables. Audit booking commitment level, time zone clarity, audience-fit. + +--- + +## "Sales says enterprise prospects skip the scheduler and email instead." + +**The diagnosis.** Enterprise audiences sometimes want personal contact rather than self-serve booking. + +**The cure.** Offer a "talk to sales" alternative for enterprise leads. Hybrid approach. + +--- + +## "Conversion dropped after we updated the booking flow." + +**The diagnosis.** Specific change introduced friction. + +**The cure.** Compare metrics pre- and post-change. Roll back if necessary; isolate the issue. + +--- + +## "Reschedule flow loses qualification data." + +**The diagnosis.** Reschedule treated as new booking; data not preserved. + +**The cure.** Reschedule preserves qualification. Detail in `references/reschedule-and-no-show-handling.md`. + +--- + +## The pattern across failures + +Most scheduler failures fall into one of three patterns. + +**Pattern 1: Qualification miscalibrated.** Any-time-friction, interrogation-gate, or wrong fields. The fix is calibrating qualification to the team's needs. + +**Pattern 2: Routing or prep miscalibrated.** Wrong-rep-tier, no-prep-automation, broken integrations. The fix is connecting qualification to rep workflow. + +**Pattern 3: Communication miscalibrated.** Aggressive reminders, brittle no-show flows, missing reschedule paths. The fix is gentle, useful communication. + +The metric pattern: scheduler failures often look fine on booking conversion alone. The signal is in demo-to-sale conversion, no-show rates, rep prep quality. Programs that track only booking rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (qualification, routing/prep, communication). The principle that booking rate alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md new file mode 100644 index 0000000..fe9f876 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md @@ -0,0 +1,247 @@ +# Prep automation patterns + +CRM enrichment, calendar invite, Slack brief, account research. + +The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused and the rep starts the call cold despite the data being captured. + +--- + +## The data-reaches-rep principle + +Prep automation closes the loop between qualification capture and rep readiness. + +**The win.** Prospect books; qualification data populates the CRM record, appears in the calendar invite, and triggers a brief Slack message to the rep with synthesized prep notes. The rep arrives at the call already knowing the prospect's situation. + +**The fail.** Qualification data captured; sits in a database; rep does not see it until they search for it. Most reps do not search; they start the call cold. + +The discipline. Capture qualification AND deliver it to the rep where they will see it. + +--- + +## Pattern A: CRM enrichment + +Qualification data populates the CRM record. + +**How it works.** + +- Booking submission writes to CRM (Salesforce, HubSpot, etc.). +- Fields populate the lead/contact record. +- Rep sees the data when they review the lead. + +**Strengths.** + +- Single source of truth. +- Fits existing rep workflow (reps already check CRM). + +**Weaknesses.** + +- Reps may not check CRM before every call. +- CRM custom fields require setup. + +**When to use.** Default; baseline for any prep automation. + +--- + +## Pattern B: Calendar invite enrichment + +Qualification data appears in the meeting invite description. + +**How it works.** + +- When the meeting is created, the invite description includes the qualification data. +- Rep sees it on their calendar; visible at-a-glance. + +**Strengths.** + +- Rep cannot miss it; calendar is the moment of action. +- Works regardless of CRM access. + +**Weaknesses.** + +- Calendar invite descriptions can be long; reps may not read fully. +- Updates after booking do not appear in the invite. + +**When to use.** Strong complement to CRM enrichment. + +--- + +## Pattern C: Slack or email brief + +Pre-call brief sent to the rep with synthesized prospect info. + +**How it works.** + +- Booking triggers a Slack message or email to the rep. +- Brief includes qualification data plus context (account history, company info, prior interactions). +- Often delivered hours or a day before the call. + +**Strengths.** + +- Active delivery; rep receives it without searching. +- Can include synthesized context (CRM history, news, prior touches). + +**Weaknesses.** + +- Slack noise can dilute brief; reps may scroll past. +- Email may sit unread. + +**When to use.** When the team's workflow includes Slack or email-driven prep. + +--- + +## Pattern D: Account research + +Qualification data triggers automated research. + +**How it works.** + +- Booking triggers automated lookup (company size verification via Clearbit/ZoomInfo, recent news search, social media check). +- Research results appended to CRM or prep brief. + +**Strengths.** + +- Rep gets richer context than qualification alone provides. +- Catches data prospects did not provide. + +**Weaknesses.** + +- Research tools cost. +- Can miss for small companies or international. + +**When to use.** Enterprise sales motion; high-value calls warrant research investment. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production teams use multiple. + +**Common combination.** + +- CRM enrichment as baseline. +- Calendar invite enrichment for at-a-glance visibility. +- Slack brief 24 hours before the call for richer prep. +- Account research for high-fit leads. + +The hybrid produces multiple touchpoints; rep sees prep data wherever they happen to look first. + +--- + +## What to include in prep automation + +The fields that matter to the rep. + +**Standard inclusions.** + +- Prospect name and role. +- Company name and size. +- Use case or primary goal. +- Current solution. +- Timeline or urgency. +- Source (paid, organic, referral). + +**Sometimes useful.** + +- Company industry and recent news. +- Prior interactions with the brand. +- LinkedIn profile link. +- Account history (existing customer, prior trial). + +**Avoid in prep.** + +- Free-text fields the prospect filled with noise. +- Marketing data not relevant to the call (UTM details, lead source granularity). +- Personal data not needed for the call. + +--- + +## Prep timing + +When the brief reaches the rep. + +**At-booking.** Brief delivered immediately after booking. Rep can prepare any time. + +**Day-before.** Brief delivered 24 hours before. Forces prep into the rep's workflow. + +**Hour-before.** Brief delivered 1 hour before. Last-minute prep; useful for back-to-back calls. + +**The combined approach.** Most teams use at-booking (CRM record) plus day-before (Slack) plus calendar visibility throughout. + +--- + +## Prep brief copy + +What the brief says. + +**Strong brief copy.** + +- "Sarah Lee, Director of Marketing at [Company], 200-500 employees, evaluating analytics tools to replace [current solution] within 60 days." + +What works. Specific; structured; gives rep enough to prepare. + +**Weak brief copy.** + +- "New booking from Sarah Lee." + +What fails. No context; rep starts cold despite the data being captured upstream. + +The discipline. Brief should be specific enough that the rep arrives ready. + +--- + +## Prep automation testing + +Verify the loop works. + +**Test cases.** + +- Booking happens; CRM record created; data populates. +- Booking happens; calendar invite shows the qualification data. +- Booking happens; Slack brief arrives at the right time. +- Edge case: prospect updates booking; prep updates accordingly. + +**Production monitoring.** If reps consistently arrive at calls cold, prep automation is broken somewhere. + +--- + +## Privacy and consent + +Prep automation involves handling user data. + +**The principle.** Data captured at booking flows to internal systems for prep. The prospect has implicitly consented to internal use through the booking. + +**Limits.** + +- Data should not flow to systems unrelated to the booking purpose. +- Account research should respect privacy norms. +- GDPR and other regulations apply. + +--- + +## Common prep automation failures + +**No automation.** Data captured; reps do not see it. + +**CRM enrichment without rep CRM use.** Data is in CRM; reps do not check CRM before calls. + +**Slack brief lost in noise.** Prep brief among 50 other Slack messages; rep misses. + +**Calendar invite truncated.** Invite description too long; reps see only opening. + +**Stale account research.** Research data from months ago. + +**Brief copy generic.** Brief contains data but not synthesized context. + +**Updates after booking not propagated.** Prospect updates info; prep stays old. + +**No testing.** Prep loop broken; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The data-reaches-rep principle. Patterns A through E (CRM, calendar, Slack, research, hybrid). What to include in prep. Prep timing. Prep brief copy discipline. Prep automation testing. Privacy and consent. Common failures. + +## Implementation choices that stay internal + +Specific prep configurations for specific teams. Specific Slack templates and CRM custom fields. Specific research tooling. The team's privacy review processes. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md new file mode 100644 index 0000000..ea83e3c --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md @@ -0,0 +1,221 @@ +# Qualification field design + +Strong and weak qualification fields. The five-field rule. + +The fields decide the booking flow's friction and the call's quality. Done well, qualification produces context for the call without scaring off prospects; done poorly, it produces interrogation-gate dynamics. + +--- + +## The earns-its-place principle + +Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +**The win.** Four fields: company size, role, primary use case, timeline. Each routes or preps. Conversion is high; rep prep is concrete. + +**The fail.** Twelve fields including industry code, employee count range, marketing source, lead-source detail, gender. Most do not affect routing or prep; conversion drops 70 percent. + +The discipline. Audit each field. Cut fields that do not earn placement. + +--- + +## Strong qualification fields + +Patterns that earn placement. + +**Company size or team size.** + +Why it works. Routes to the right rep tier (SMB vs mid-market vs enterprise); enables segment tracking; concrete signal of fit. + +Format. Dropdown with bands ("1-10," "11-50," "51-200," "201-1000," "1000+"). + +**Use case or primary goal.** + +Why it works. Lets the rep prepare for the conversation that matches. + +Format. Dropdown with 5-7 use cases; or short open text if use cases are not enumerable. + +**Current solution or stack.** + +Why it works. Tells the rep where the prospect is starting; informs migration vs greenfield framing. + +Format. Dropdown of common alternatives plus "other" with text field. + +**Timeline or urgency.** + +Why it works. Routes to active-pipeline vs nurture; signals urgency to the rep. + +Format. Dropdown ("Within 30 days," "1-3 months," "3-6 months," "Just exploring"). + +**Role or job function.** + +Why it works. Lets the rep tailor framing; routes to specialist reps if role-aligned. + +Format. Dropdown of common roles; "Other" field for unusual cases. + +--- + +## Weak qualification fields + +Patterns that fail. + +**Phone number.** + +Why it fails. Often unnecessary if email and meeting time are captured. Reps can request phone in the call. Phone field adds friction without value for the booking itself. + +When to include. If the call is by phone (not video), phone is necessary. + +**Generic comments box.** + +Why it fails. Free-text rarely informs prep. Most prospects skip; some over-share; few provide useful context. + +When to include. Sparingly; if structured fields cannot capture the necessary context. + +**Marketing data not used in the call.** + +Why it fails. Industry codes, lead-source detail, etc. add friction without affecting the call's quality. + +When to include. Capture later (post-meeting follow-up form, CRM enrichment) rather than at the booking. + +**Demographic data unrelated to the call.** + +Why it fails. Gender, age, etc. rarely inform a B2B sales conversation. + +When to include. Almost never. Only if regulatory or product-specific reasons require. + +--- + +## The five-field rule + +Most production schedulers work well with 3-5 qualification fields. + +**Why 3-5.** + +- 3 fields is the minimum for useful qualification. +- 5 fields is the threshold beyond which drop-off climbs. +- Production data across many SaaS products supports this range. + +**Exceptions.** + +- Some enterprise sales contexts warrant 5-7 fields because the audience expects qualification. +- Some highly specialized products warrant fewer fields (1-2) because conversion volume matters more. + +**The over-five trap.** Each additional field beyond 5 reduces conversion meaningfully. The marginal value of field 6 rarely justifies the conversion cost. + +--- + +## Field ordering + +Within the form, the order matters. + +**Open with low-friction.** Identity fields (name, email) first. Familiar; easy. + +**Build to value.** Use-case or goal fields next. The prospect engages with what the call will be about. + +**Save commitment for later.** Timeline or budget fields late. The prospect has invested; harder ask is acceptable. + +**End with optional.** Comments or "anything else?" at the end if included. The prospect can leave or skip. + +--- + +## Field formats + +How each field captures input. + +**Dropdowns.** Best for categorical fields. Constrains responses; easy to route on. + +**Text fields.** For free-form fields (name, email, sometimes use case). + +**Sliders.** Rarely useful in qualification. + +**Yes/No toggles.** For binary qualifying questions (e.g., "Do you currently use a CRM?"). + +**Conditional fields.** Some fields appear based on earlier answers. Use sparingly; complexity adds maintenance. + +--- + +## Field validation + +What to validate. + +**Email format.** Standard validation; respect plus-aliases and international domains. + +**Required vs optional.** Mark explicitly. + +**Length and character.** Don't reject international names or non-Latin characters. + +**The validation-strict failure.** Validation that rejects valid inputs (international phone formats, plus-sign emails) loses real prospects. + +--- + +## Inferred vs asked fields + +What to ask vs what to infer. + +**Ask sparingly.** Each field is friction. + +**Infer when possible.** + +- Lead source: from URL parameters or referrer. +- Company info: from email domain. +- Geography: from IP or browser. +- Timezone: from browser. + +**The discipline.** If the system can infer a value reliably, do not ask. + +--- + +## Field-level analytics + +Track per-field drop-off. + +**Per-field completion rate.** Where in the form do prospects abandon? + +**Diagnostic uses.** + +- Specific field with high abandonment: friction at that field. +- Field rarely completed even by survivors: often signals the field can be cut. +- Specific segment abandons specific fields: segment-specific friction. + +The data informs which fields earn their place over time. + +--- + +## Field maintenance + +Fields decay. + +**What decays.** + +- Dropdowns with options that no longer match audience. +- Fields the rep team stopped using for prep. +- Fields whose routing logic changed without update. + +**Maintenance cadence.** Quarterly review of each field. Are reps using the data? Is routing connecting field-to-tier? + +--- + +## Common field failures + +**Too many fields.** Drop-off at the form. + +**Fields not used.** Captured but reps do not prep with them. + +**Wrong field types.** Free text where dropdown would route better. + +**Validation too strict.** Loses valid prospects. + +**No analytics.** Cannot tell which fields are working. + +**Stale field options.** Dropdowns no longer match audience. + +**Fields asked that could be inferred.** Friction without need. + +--- + +## Methodology-level choices that stay in the public skill + +The earns-its-place principle. Strong qualification fields (5 patterns). Weak qualification fields (4 patterns). The five-field rule. Field ordering. Field formats. Field validation. Inferred vs asked. Field-level analytics. Field maintenance. Common failures. + +## Implementation choices that stay internal + +Specific fields for specific schedulers. Specific dropdown options. Specific tooling for inference. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md new file mode 100644 index 0000000..05b3b4d --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md @@ -0,0 +1,256 @@ +# Reminder sequence patterns + +Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. + +The communications around the booking. Done well, reminders reduce no-shows without becoming spam; done poorly, reminders are either insufficient (no-shows climb) or excessive (prospect resents). + +--- + +## The reduce-no-shows-without-spam principle + +Reminders matter; their volume should be calibrated. + +**The win.** Confirmation immediately after booking; one reminder 24 hours before; one reminder 1 hour before. Three communications total. No-show rate drops; prospects feel reminded but not nagged. + +**The fail.** Confirmation; 5-day reminder; 2-day reminder; 1-day reminder; 1-hour reminder; 15-minute reminder. Six communications. Prospects mute the channel; no-shows persist for users who muted. + +The discipline. Reminders earn their place; cumulative volume should be capped. + +--- + +## Pattern A: Booking confirmation + +Sent immediately after booking. + +**What it includes.** + +- Confirmed time and meeting type. +- Calendar invite attached. +- Brief restate of expectations (e.g., "Looking forward to learning about your X"). +- Reschedule and cancel links. + +**Strengths.** + +- Immediate; reduces buyer's remorse. +- Sets expectations. +- Provides reschedule path. + +**Weaknesses.** + +- One-touch communication. + +**When to use.** Always. + +--- + +## Pattern B: Pre-meeting reminder + +Sent 24 hours and/or 1 hour before. + +**24-hour reminder.** + +- Useful for users who book days in advance. +- Lets them prepare or reschedule with notice. + +**1-hour reminder.** + +- Useful for last-minute prep. +- Catches calendar drift. + +**Both useful or one only?** + +- Most production teams use both. +- For very short booking windows (same-day), 1-hour is enough. +- For longer-lead bookings, 24-hour matters. + +--- + +## Pattern C: Post-meeting follow-up + +Sent within hours of the call. + +**What it includes.** + +- Brief recap. +- Action items (rep's commitments). +- Resources mentioned in the call. +- Next-step CTA (next meeting, document, trial). + +**Strengths.** + +- Captures momentum from the call. +- Documents commitments. + +**Weaknesses.** + +- Requires rep to populate after the call (or rep-side tooling to auto-generate). + +**When to use.** Sales conversations where next steps matter. + +--- + +## Pattern D: Reschedule prompts + +When the prospect cannot make the meeting. + +**What it includes.** + +- Easy reschedule link. +- Brief check-in copy ("Need to reschedule? No problem."). + +**Strengths.** + +- Reduces no-shows; users reschedule rather than ghost. + +**Weaknesses.** + +- Some users use this to reschedule indefinitely. + +**When to use.** Always available; not aggressive. + +--- + +## Pattern E: No-show follow-up + +When the prospect does not attend. + +**What it includes.** + +- Acknowledgment of missed meeting. +- Reschedule link. +- Brief context-restatement. + +**Tone.** Gentle, not punitive. The prospect may have had a real reason. + +**The respect-the-no-show principle.** After 1-2 reschedule attempts, accept that the prospect is not engaging. + +--- + +## Reminder timing + +When each communication fires. + +**Common cadence.** + +- T+0: Confirmation immediately after booking. +- T-24h: Reminder 24 hours before. +- T-1h: Reminder 1 hour before. +- T+15m: Late-arrival check (sometimes). +- T+24h: Post-meeting follow-up. + +The discipline. Each communication earns its place. Drop the ones that do not. + +--- + +## Channel choice + +Which channels to use. + +**Email.** Default. Reliable; familiar. + +**SMS.** Higher attention; more friction. Use selectively for high-value bookings. + +**In-app notification.** If the booking is for a logged-in user, in-app reminders work. + +**Slack or Teams.** For B2B internal-team meetings. + +**The cumulative discipline.** Multiple channels for the same reminder is excessive. Pick one channel per reminder. + +--- + +## Reminder copy + +What the reminders say. + +**Strong reminder copy.** + +- "Looking forward to our call tomorrow at 2 PM PT. Here's what we'll cover: [agenda]." +- "Reminder: 1 hour until our call. Join here: [link]." +- "Thanks for the call today. Here's what we discussed: [recap]." + +What works. Specific; useful; brief. + +**Weak reminder copy.** + +- "Don't forget your meeting!" +- "Your meeting is in 1 hour." +- "Did you know..." + +What fails. Generic; no value-add; just a notification. + +--- + +## Reminder personalization + +How much to personalize. + +**Default personalization.** Name; meeting time; rep name. + +**Strong personalization.** Brief context tied to qualification ("Looking forward to discussing your [use case] situation"). + +**Over-personalization.** Long personalized paragraphs that read as marketing. + +The discipline. Personalize where it adds value; do not pad with personalization for its own sake. + +--- + +## Reminder analytics + +Track effectiveness. + +**Metrics.** + +- Open rate per reminder. +- Reschedule rate per reminder. +- No-show rate (cumulative across cadence). +- Cancellation rate. + +**Diagnostic uses.** + +- Low open rate: subject line weak or channel wrong. +- High reschedule rate after specific reminder: that reminder triggers reconsideration. +- High no-show despite reminders: friction at the meeting itself, not the reminder. + +--- + +## Reminder maintenance + +Reminders decay. + +**What decays.** + +- Templates with stale rep names or roles. +- Calendar links that broke after platform changes. +- Channel preferences that no longer fit audience. + +**Maintenance cadence.** Quarterly review of reminder templates and channels. + +--- + +## Common reminder failures + +**Too many reminders.** Cumulative volume is spam; users mute. + +**Too few reminders.** No-show rate climbs. + +**Generic copy.** No value; users dismiss. + +**Wrong channel.** SMS for an audience that prefers email. + +**Stale templates.** Rep names from former employees; broken calendar links. + +**No post-meeting follow-up.** Conversation momentum lost. + +**Aggressive no-show follow-up.** Multiple reminder attempts after a no-show; respect non-response. + +**Personalization padding.** Long personalized text that reads as marketing. + +--- + +## Methodology-level choices that stay in the public skill + +The reduce-no-shows-without-spam principle. Patterns A through E (confirmation, pre-meeting, post-meeting, reschedule, no-show). Reminder timing. Channel choice. Reminder copy discipline. Reminder personalization. Reminder analytics. Reminder maintenance. Common failures. + +## Implementation choices that stay internal + +Specific reminder cadences for specific teams. Specific copy in brand voice. Specific channel choices. The team's no-show baselines. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md new file mode 100644 index 0000000..081a420 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md @@ -0,0 +1,241 @@ +# Reschedule and no-show handling + +Reschedule patterns, no-show patterns, respect-the-no principle. + +What happens when meetings do not go to plan. Done well, reschedule and no-show handling protect the relationship and capture re-engagement; done poorly, they punish the prospect for ordinary life events. + +--- + +## The respect-the-no principle + +Prospects who reschedule or no-show often have real reasons. Handling should be gentle, not punitive. + +**The win.** Prospect no-shows; gentle follow-up offers easy reschedule. Prospect reschedules once; offered again at a new convenient time. After two no-shows, the system stops aggressive pursuit and routes to nurture. + +**The fail.** Prospect no-shows; system fires three reminder emails over two days; phone call follows; prospect feels harassed. + +The discipline. Acknowledge that life intervenes; offer a path back; do not pressure. + +--- + +## Reschedule patterns + +When prospects need to change the meeting. + +**Pattern A: Self-serve reschedule.** + +How it works. The booking confirmation includes a reschedule link. Prospect clicks; sees new availability; selects new slot. + +Strengths. No friction; respect for the prospect's time. + +Weaknesses. Some abuse possible (repeated reschedules). + +When to use. Default for most schedulers. + +**Pattern B: Reschedule preserves qualification data.** + +How it works. Reschedule keeps all the qualification info; rep does not lose context. + +Strengths. Reschedule does not cost prep work. + +Weaknesses. None significant. + +When to use. Always. + +**Pattern C: Reschedule notifies the rep.** + +How it works. When prospect reschedules, rep gets notified. Original calendar slot freed up. + +Strengths. Rep can use the freed slot. + +Weaknesses. None. + +When to use. Always. + +**Pattern D: Reschedule limits.** + +How it works. After N reschedules, the system flags the booking for review or routes to nurture. + +Strengths. Prevents abuse. + +Weaknesses. Risks alienating prospects with legitimate scheduling difficulty. + +When to use. Sparingly; usually 3+ reschedules before flagging. + +--- + +## No-show patterns + +When prospects do not attend. + +**Detection.** + +- Rep reports no-show after the meeting time. +- System detects unattended meeting (if integrated with video platform). +- Manual reports from CS or sales ops. + +**Pattern A: Single follow-up.** + +How it works. Within 4-24 hours of the no-show, send a single gentle email offering reschedule. + +Strengths. Catches genuine forgetfulness. + +Weaknesses. Single touch may not catch users on vacation. + +When to use. Default. + +**Pattern B: Two-touch follow-up.** + +How it works. First email immediate. Second email 3-5 days later if no response. + +Strengths. Catches prospects who were genuinely busy. + +Weaknesses. Risks feeling persistent. + +When to use. Higher-value bookings where multi-touch is justified. + +**Pattern C: Sales-led recovery.** + +How it works. For high-value no-shows, sales rep reaches out personally. + +Strengths. Most engaging; can recover the relationship. + +Weaknesses. Expensive; only viable for high-value accounts. + +When to use. Enterprise no-shows or accounts with strategic value. + +**Pattern D: Async route.** + +How it works. Send the no-show prospect resources or content rather than another booking attempt. Re-engagement deferred. + +Strengths. Respects the no-show as a signal. + +Weaknesses. May lose prospects who would have rebooked. + +When to use. After 1-2 unsuccessful reschedule attempts. + +--- + +## Reschedule cadence + +How often to retry. + +**Single reschedule attempt:** offer once; respect non-response. + +**Multiple attempts:** at most 2 attempts spaced 3-7 days apart. Stop after that. + +**No reschedule attempts:** for bookings flagged as low-fit; route to nurture. + +The discipline. Each reschedule attempt earns its place. Cumulative attempts become harassment. + +--- + +## When to abandon reschedule + +Some no-shows should be respected as final. + +**Signals to stop.** + +- Prospect explicitly asked to stop contact. +- Multiple no-shows from same prospect. +- No response to 2 reschedule attempts. +- Email bounced or unsubscribed. + +**The respect-the-pattern principle.** Multiple no-shows often signal the prospect's needs changed. Continuing pursuit damages the brand. + +--- + +## No-show flow design + +The full sequence. + +**T+0 (no-show happens).** + +- Rep marks no-show in CRM. +- Free the calendar slot. + +**T+4-24h (first follow-up).** + +- Email: "Sorry we missed you. Want to reschedule? [Link]." + +**T+3-5d (second follow-up if needed).** + +- Email: "We're still interested in connecting if your schedule changed. Here's the reschedule link." + +**T+10d (final attempt or async route).** + +- Send relevant content; surface re-engagement option without pressure. + +**T+30d+.** + +- Treat as nurture; pursue through other channels (email newsletter, content). + +The cadence respects multiple touchpoints without becoming aggressive. + +--- + +## No-show analytics + +Track patterns. + +**Per-segment no-show rate.** + +- Different sources, sizes, or use cases may no-show at different rates. + +**Per-rep no-show rate.** + +- Some reps may correlate with higher no-shows (timing, time zone, prep gaps). + +**Reschedule conversion rate.** + +- Of rescheduled bookings, what percentage attend. + +**Diagnostic uses.** + +- High overall no-show: reminder sequence weak or commitment friction at booking too low. +- Specific segment no-shows more: that segment may need different cadence. +- Specific rep no-shows more: their availability or prep may be off. + +--- + +## Time zone and travel mistakes + +Common reasons for no-shows that are not the prospect's fault. + +**Prevention.** + +- Display time zone clearly at booking. +- Calendar invites include time zone. +- Reminders include time zone. + +**The cure for time zone mistakes.** Quick reschedule; do not penalize. + +--- + +## Common reschedule and no-show failures + +**Aggressive recovery.** Multiple touches over short periods; harassment. + +**Reschedule limits too tight.** Genuine prospects flagged after 2 reschedules; lost. + +**Reschedule loses qualification data.** Rep loses context on reschedule. + +**No reschedule path.** Prospect cannot reschedule; ghosts instead. + +**No-show no follow-up.** Prospect's missed meeting is just lost; could have rebooked. + +**Punitive copy.** No-show follow-up shames the prospect. + +**Time zone confusion.** Prospect missed because of time zone error; system blames the prospect. + +**Stale reschedule links.** Link works at booking; broken later. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-no principle. Reschedule patterns A through D. No-show patterns A through D. Reschedule cadence. When to abandon. No-show flow design. No-show analytics. Time zone considerations. Common failures. + +## Implementation choices that stay internal + +Specific reschedule limits for specific teams. Specific follow-up cadences. Specific copy in brand voice. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md new file mode 100644 index 0000000..fe64b71 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md @@ -0,0 +1,235 @@ +# Routing patterns + +By size, use case, geography, language, account ownership. Unrouted-lead default. + +The specific routing rules that translate qualification answers into rep assignments. Done well, routing matches lead to rep cleanly; done poorly, leads bounce around or land on wrong reps. + +--- + +## Routing-by-company-size + +The most common routing axis. + +**Pattern.** + +- 1-50 employees: SDR or self-serve. +- 51-500 employees: AE. +- 501-2000 employees: senior AE. +- 2000+ employees: enterprise AE. + +**Why it works.** Different sizes have different sales motions; rep tier should match. + +**Failure modes.** + +- Size bands set years ago; team scaled; bands no longer right. +- Size data missing or stale. +- Solo founders with backed companies appear "small" but warrant senior treatment. + +--- + +## Routing-by-use-case + +Different specialists for different product use cases. + +**Pattern.** + +- Use case A: rep with A specialty. +- Use case B: rep with B specialty. +- General use case: any AE. + +**Why it works.** Specialists arrive with deeper context; conversion higher. + +**Failure modes.** + +- Specialist becomes bottleneck. +- New use cases without assigned specialist. +- Use case overlap; multiple specialists could fit. + +--- + +## Routing-by-geography + +Different reps for different regions or time zones. + +**Pattern.** + +- Americas: US-based AEs. +- EMEA: European AEs. +- APAC: APAC AEs. + +**Why it works.** Time zone alignment; cultural fit; language fit. + +**Failure modes.** + +- Insufficient coverage in some regions. +- Cross-region accounts confuse routing. +- Geography data missing or wrong. + +--- + +## Routing-by-language + +Native-language reps for non-English-primary leads. + +**Pattern.** + +- English-primary: US/UK AEs. +- Spanish-primary: Spanish-speaking AEs. +- Etc. + +**Why it works.** Native-language conversation produces better calls. + +**Failure modes.** + +- Incomplete language coverage. +- Multi-language leads bounce. +- Language inferred wrong from email or location. + +--- + +## Routing-by-account-ownership + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +**Pattern.** + +- Detect domain match against CRM. +- If match, route to AE who owns the account. +- If no match, default routing. + +**Why it works.** Account owner has context; avoids confusion. + +**Failure modes.** + +- Domain detection misses subsidiaries or aliases. +- Account ownership stale (former AE). +- New lead from existing account but for unrelated use case. + +--- + +## Routing-by-source + +Different reps for different lead sources (paid, organic, partner, referral). + +**Pattern.** + +- Partner-sourced leads: partner-channel AE. +- Paid-sourced leads: marketing-aligned AEs. +- Organic-sourced: general AEs. + +**Why it works.** Different sources signal different commitment; specialists handle differently. + +**Failure modes.** + +- Source data missing or attribution wrong. +- Paid traffic includes high-fit leads who would have come organically. + +--- + +## Routing-by-tier + +Combining size, use case, and other signals into a tier score. + +**Pattern.** + +- Lead score 80-100: senior AE. +- Lead score 50-79: AE. +- Lead score 0-49: SDR or async. + +**Why it works.** Single score combines multiple signals. + +**Failure modes.** + +- Score model out of date. +- Score thresholds wrong for current capacity. +- Score data incomplete; defaults dominate. + +--- + +## The unrouted-lead default + +Some leads do not fit obvious routing. + +**Patterns for default.** + +- **Round-robin among all available reps.** Simple. +- **Catchall AE.** One rep gets all unrouted leads. +- **Async or self-serve.** Lead goes to a self-serve resource if no obvious rep. + +**The discipline.** Default rule should be explicit. Unrouted leads should not silently fail or bounce. + +--- + +## Routing transparency + +Prospect-side vs rep-side visibility. + +**Prospect-side.** Generally, prospects do not see routing logic. They see a calendar with available times. + +**Rep-side.** Reps should see why they were assigned (lead score, fit signals). Helps with prep. + +**Anti-pattern.** Routing happens silently; rep does not know what made this lead route to them. + +--- + +## Routing changes and team transitions + +When the team changes, routing must follow. + +**Common transitions.** + +- Rep leaves; their accounts and routing reassign. +- New rep hires; routing weights adjust. +- Tier restructure (rep promoted from SDR to AE). +- Specialty changes. + +**The maintenance discipline.** Routing rules update as team changes. Stale routing can route leads to absent reps. + +--- + +## Routing analytics + +Track routing effectiveness. + +**Metrics.** + +- Per-rep booking volume. +- Per-rep conversion (booking-to-sale). +- Per-route conversion (route x → sale rate). +- Routing override rate (manual reassignments). + +**Diagnostic uses.** + +- Per-rep volume uneven without reason: routing logic skewing. +- Per-route conversion uneven: routing matching wrong. +- High override rate: routing logic not capturing real fit. + +--- + +## Common routing failures + +**Routing data missing.** Qualification did not capture; routing defaults dominate. + +**Stale routing rules.** Team changed; rules did not. + +**Stale rep weights.** Performance scores from quarters ago. + +**Account-ownership detection wrong.** Subsidiary leads route to unfit AE. + +**Specialty routing without specialty data.** Specialty-based routing requires tagging; tags miss. + +**Default rule unclear.** Unrouted leads silently fail. + +**Routing override frequent.** Reps reassign manually; routing logic does not match reality. + +**Round-robin for tiered team.** High-fit leads land on junior reps. + +--- + +## Methodology-level choices that stay in the public skill + +Routing patterns by size, use case, geography, language, account ownership, source, tier. The unrouted-lead default. Routing transparency. Team transitions. Routing analytics. Common failures. + +## Implementation choices that stay internal + +Specific routing rules for specific teams. Specific size bands and tier thresholds. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md new file mode 100644 index 0000000..6b3c225 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md @@ -0,0 +1,209 @@ +# Scheduler anti-patterns + +The patterns that look like schedulers but degrade conversion. Anti-patterns are easy to ship; the cost shows up in booking conversion, downstream call quality, and brand reputation. + +--- + +## The any-time-friction scheduler + +The pattern. Generic booking link with no qualification. + +The signal. Reps show up cold; downstream demo-to-sale conversion poor. + +The cost. Sales capacity used inefficiently; call quality suffers. + +The cure. Add 3-5 qualification fields; route to right rep tier; deliver prep to reps. + +--- + +## The interrogation-gate scheduler + +The pattern. 12-field qualification form before booking. + +The signal. 90 percent drop-off at the form. + +The cost. Lose conversions from would-be buyers; only the most committed survive the form. + +The cure. Cut to 3-5 fields; defer additional questions to in-call or post-meeting. + +--- + +## The wrong-rep-tier scheduler + +The pattern. Round-robin routing for tiered team. + +The signal. Enterprise leads land on SDRs; SDRs unprepared; conversion drops. + +The cost. High-value leads get junior reps; senior reps underutilized. + +The cure. Fit-based routing tied to qualification. + +--- + +## The no-prep-automation scheduler + +The pattern. Qualification captured but not delivered to reps. + +The signal. Reps start calls cold despite qualification data existing. + +The cost. Qualification work wasted; cold-call dynamics return. + +The cure. CRM enrichment, calendar invite enrichment, Slack briefs. + +--- + +## The no-buffer scheduler + +The pattern. Back-to-back meetings without buffer time. + +The signal. Reps run late; calls feel rushed; quality drops. + +The cost. Reps stressed; calls poorer; conversion suffers. + +The cure. 10-15 minute buffer between meetings. + +--- + +## The no-capacity-cap scheduler + +The pattern. Reps booked solid all day every day. + +The signal. Quality drops; rep burnout. + +The cost. Calls that book are lower quality; reps eventually leave. + +The cure. Cap meetings per day per rep (3-5 typical). + +--- + +## The time-zone-confused scheduler + +The pattern. Times shown in rep's time zone; prospect has to convert mentally. + +The signal. Wrong-time bookings; no-shows from time zone errors. + +The cost. Prospects miss meetings; assume their fault. + +The cure. Auto-detect prospect time zone; display explicitly. + +--- + +## The aggressive-reminder scheduler + +The pattern. Multiple reminders per booking (5+ touchpoints). + +The signal. Prospects mute or unsubscribe; reminder effectiveness drops. + +The cost. Reminders trained to be ignored; no-shows persist. + +The cure. Two reminders typical (24-hour, 1-hour). Cap cumulative volume. + +--- + +## The aggressive-no-show-recovery scheduler + +The pattern. Multiple reschedule attempts over short period. + +The signal. Brand earns harassment reputation; recovery rate drops. + +The cure. One-to-two reschedule attempts max; respect non-response. + +--- + +## The aggressive-cancellation-prevention scheduler + +The pattern. Cancellation requires multi-step or contact with sales. + +The signal. Public complaints; trust damage. + +The cost. Reputation harm; sometimes regulatory issues. + +The cure. Self-serve cancellation; one click. + +--- + +## The unmaintained scheduler + +The pattern. Routing rules from years ago; team changed; rules did not. + +The signal. Leads route to absent reps; bookings sit unread. + +The cure. Quarterly maintenance. Team transitions trigger routing updates. + +--- + +## The mobile-broken scheduler + +The pattern. Booking flow works on desktop; breaks on mobile. + +The signal. Mobile conversion half of desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. + +--- + +## The double-booking scheduler + +The pattern. Calendar integration broken; multiple bookings for same time. + +The signal. Reps and prospects both arrive; one waits or leaves. + +The cost. Rep frustration; prospect confusion; brand damage. + +The cure. Calendar integration tested. Buffer time. Conflict detection. + +--- + +## The shared-link bypass scheduler + +The pattern. Reps share generic booking links alongside structured flow. + +The signal. Routing logic bypassed; cold demos return. + +The cost. Investment in qualification and routing partially undone. + +The cure. Disable generic links. Train reps to use structured links. + +--- + +## The integration-brittle scheduler + +The pattern. Calendar, CRM, or video integration breaks frequently. + +The signal. Reps complain about manual workarounds. + +The cost. Operational friction; data inconsistency. + +The cure. Stable integrations; monitoring; rollback plans. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of scheduler portfolio. + +**Audit questions.** + +- Is qualification calibrated (anti-pattern check: any-time-friction, interrogation-gate)? +- Does routing match team tier (anti-pattern check: wrong-rep-tier)? +- Does prep automation deliver (anti-pattern check: no-prep-automation)? +- Is calendar logic sound (anti-pattern check: no-buffer, no-capacity-cap, double-booking)? +- Are reminders calibrated (anti-pattern check: aggressive-reminder)? +- Is no-show recovery respectful (anti-pattern check: aggressive-no-show-recovery)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does the system work on mobile (anti-pattern check: mobile-broken)? +- Are integrations stable (anti-pattern check: integration-brittle)? + +**The retire decision.** Anti-pattern schedulers warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md new file mode 100644 index 0000000..62327fe --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md @@ -0,0 +1,175 @@ +# Scheduler decision criteria + +When schedulers earn the build vs when forms or sales-pipeline tools serve. + +A scheduler is meaningful work. Qualification logic, availability rules, routing, prep automation, follow-up sequences, ongoing maintenance. The scheduler earns this investment only when specific conditions are present. + +--- + +## When schedulers earn the build + +Five conditions that, when present, make a scheduler a strong investment. + +**The conversion goal is a meeting.** Demo, sales call, consultation. Email-only or trial-signup conversions do not need a scheduler. + +**The audience is willing to commit time.** Schedulers ask for a calendar slot; not all audiences are ready for that. Top-of-funnel awareness audiences are usually not ready; consideration-stage audiences often are. + +**The team has enough capacity to handle scheduled meetings.** Without capacity, scheduled meetings produce wait times that erode conversion. Reps booked solid for two weeks lose conversions to faster competitors. + +**The team can support qualification logic and routing.** Without these, a generic booking link is the result. Generic booking links produce cold demos. + +**The success metric is defined.** Booking conversion, demo-to-sale conversion, no-show rate, call quality (often measured via rep self-reports). Without the success metric, evaluation is impossible. + +When all five are present, a scheduler is strong investment. When two or fewer are present, simpler tools (contact forms, sales pipeline outreach) often serve better. + +--- + +## When schedulers do NOT earn the build + +Funnels where the scheduler is the wrong tool. + +**The conversion goal is a download or signup.** Use forms (covered by `multi-step-form-design`) or magnet flows (covered by `lead-magnet-design`). + +**The audience volume is too low.** A handful of bookings per month does not need routing infrastructure; a contact form may serve better. + +**The team's capacity is variable and routing cannot reflect it.** Scheduling without capacity awareness produces booked-too-tight or booked-too-loose patterns; both fail. + +**A simpler contact form would serve.** Inbound leads where sales does outbound contact may not need a scheduler; the prospect just provides info; the rep reaches out. + +**The audience prefers async communication.** Some audiences (technical buyers, asynchronous teams) prefer email or document exchange to scheduled calls. + +The honest assessment matters. Schedulers are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Schedulers vs forms + +Both capture lead info; they differ in commitment. + +**Form strengths.** + +- Lower commitment from the prospect. +- Higher top-of-funnel volume. +- Suitable for any conversion type (download, demo request, contact). + +**Form weaknesses.** + +- No automatic time commitment. +- Requires sales follow-up to schedule. +- Wait time between form submission and meeting. + +**Scheduler strengths.** + +- Time committed at booking; no scheduling delay. +- Higher prospect commitment signal. +- Direct conversion to a calendar slot. + +**Scheduler weaknesses.** + +- Higher friction; not all prospects ready. +- Requires capacity to handle bookings. +- Routing complexity. + +**The choice.** When the conversion is a meeting and the audience is consideration-stage, scheduler. When the conversion is more open or the audience is awareness-stage, form. + +--- + +## Schedulers vs sales-pipeline tools + +For B2B sales, alternatives exist. + +**Sales pipeline strengths.** + +- Sales-led; rep makes contact on their schedule. +- Can prioritize based on fit before reaching out. + +**Sales pipeline weaknesses.** + +- Slower response. +- Higher acquisition cost per booking. + +**Scheduler advantages.** + +- Self-serve; faster response. +- Lower acquisition cost. + +**The combined approach.** Many production teams use both: scheduler for self-serve high-intent leads; sales pipeline for outbound and complex deals. + +--- + +## The opportunity-cost frame + +A scheduler is significant work. Account for it. + +**The build cost.** Qualification logic, availability rules, routing, prep automation, reminder sequences, integration with CRM and calendar, mobile responsiveness. A meaningful scheduler often takes 40-150 engineering hours plus operational setup. + +**The maintenance cost.** Routing rules update as team changes; integrations need maintenance. Quarterly review and updates run 4-8 hours. + +**The opportunity cost.** What else could the team have built? A simpler contact form, a better sales-led process, direct outreach. The scheduler has to clear the bar of those alternatives. + +The decision frame. Scheduler earns investment when it produces more meeting volume at acceptable quality than alternatives. + +--- + +## Decision worked example + +A B2B SaaS with 50 demo requests per week. + +**Conditions check.** + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes (mid-market audience). +- Team capacity: yes; 4 reps with capacity for 12-15 demos per week each. +- Qualification and routing supported: yes; reps differ by industry vertical. +- Success metric defined: booking conversion, demo-to-trial within 14 days. + +**Decision.** Build the scheduler. The conditions warrant it. + +**Architecture.** 4-field qualification (size, role, use case, timeline); fit-based routing (enterprise to senior AE, mid-market to AE, SMB to SDR); CRM enrichment and Slack brief for prep automation. + +**Maintenance commitment.** Quarterly review; team-change updates as part of onboarding. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A consumer-facing financial advisory company with 5 inbound consultations per week. + +**Conditions check.** + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes. +- Team capacity: yes (3 advisors). +- Qualification and routing supported: not really; advisors are interchangeable. +- Volume justifies scheduler infrastructure: low. + +**Decision.** Do not build a custom scheduler. Use a generic booking link with a brief 2-field qualification form. The volume does not justify routing infrastructure; the simplicity is fine. + +The decision was right-sized. + +--- + +## When to retire a scheduler + +Schedulers can become wrong over time. + +**Retire-or-redesign when:** + +- Conversion has dropped below baseline consistently and refinements have not moved it. +- Team structure changed; routing logic no longer fits. +- Volume changed; infrastructure no longer matches need. +- Integration with CRM or calendar has broken repeatedly. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant schedulers. The five conditions that argue against. Schedulers vs forms. Schedulers vs sales-pipeline tools. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific scheduler decisions for specific teams. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/security-baseline/SKILL.md b/dist/pi/.agents/skills/security-baseline/SKILL.md new file mode 100644 index 0000000..bd3f1ec --- /dev/null +++ b/dist/pi/.agents/skills/security-baseline/SKILL.md @@ -0,0 +1,296 @@ +--- +name: security-baseline +description: "Establish a security baseline for a website or web app. Use this skill when configuring HTTPS and TLS, setting security headers, planning secrets management, evaluating CSP policies, doing a basic security audit, or hardening a site before launch. Triggers on security headers, HTTPS, TLS, CSP, content security policy, HSTS, secrets management, vulnerability scan, security audit, harden, OWASP, security baseline. Also triggers when a security review is required for compliance or before going live." +category: operations +catalog_summary: "HTTPS, security headers, CSP, secrets management, vulnerability scans" +display_order: 7 +--- + +# Security Baseline + +Establish the security floor for any production website or web app. Stack-agnostic. Covers the things that should be in place before public launch and verified periodically after. + +--- + +## When to use + +- Pre-launch security review +- Setting up a new site or environment +- Periodic security audit (quarterly recommended) +- Onboarding a new vendor or third-party integration +- Responding to a security finding or report +- Hardening after an incident + +## When NOT to use + +- Active incident response (use `incident-response`) +- Code-level security review (use `code-review-web`) +- Email-specific authentication (SPF/DKIM/DMARC) (use `email-deliverability`) +- DNS-level security (CAA, DNSSEC) (use `domain-strategy`) +- Performance-related security (DDoS protection sizing) (use `performance-optimization`) + +--- + +## Required inputs + +- The site or app in scope (URLs, environments) +- The hosting platform and CDN +- Authentication method (if any) +- Third-party scripts and integrations +- Compliance context (PCI, SOC2, GDPR, etc., if applicable) +- Existing security tooling + +--- + +## The framework: 6 layers + +Security is layered. Each layer addresses a different attack surface. + +### Layer 1: Transport security + +How data moves from server to client. + +- HTTPS everywhere. No HTTP variants serving content. +- TLS 1.2 minimum, TLS 1.3 preferred. Disable TLS 1.0 and 1.1. +- HSTS (Strict-Transport-Security) header set, with `includeSubDomains` and `preload` for high-confidence sites. +- Strong cipher suites only. Modern browsers handle this if you pick a modern config from your provider. +- Certificates from a trusted CA, monitored for expiration. + +### Layer 2: Response headers + +What the browser is told about your site. + +| Header | Purpose | Default value | +|---|---|---| +| `Strict-Transport-Security` | Force HTTPS | `max-age=31536000; includeSubDomains` | +| `Content-Security-Policy` | Restrict resource loading | Site-specific | +| `X-Content-Type-Options` | Prevent MIME sniffing | `nosniff` | +| `X-Frame-Options` | Clickjacking protection | `DENY` or `SAMEORIGIN` | +| `Referrer-Policy` | Control referrer info | `strict-origin-when-cross-origin` | +| `Permissions-Policy` | Control browser features | Site-specific (camera, mic, etc.) | +| `Cross-Origin-Opener-Policy` | Process isolation | `same-origin` (where compatible) | +| `Cross-Origin-Embedder-Policy` | Cross-origin restrictions | `require-corp` (where applicable) | + +CSP deserves its own attention. See the framework section below. + +### Layer 3: Authentication and authorization + +How users prove who they are and what they can do. + +- Strong password requirements (length over complexity rules; allow long passphrases) +- Account lockout or rate limiting on login +- 2FA available, required for admin accounts +- Session tokens: short-lived, secure, HttpOnly cookies +- Logout invalidates tokens server-side, not just client-side +- Password reset flows that don't reveal account existence +- Authorization checked on every request (don't rely on UI hiding) + +### Layer 4: Input handling + +How untrusted input is processed. + +- Validate on the server (client validation is UX, not security) +- Parameterized queries for any database access (no string concatenation into SQL) +- Output encoding by context (HTML, JS, URL, CSS) +- File upload restrictions (type, size, location, scanning) +- Rate limiting on endpoints that could be abused +- CSRF tokens on state-changing requests + +### Layer 5: Secrets management + +Where credentials and keys live. + +- No secrets in code, config files in repos, or environment variables baked into images +- Secrets in a dedicated secrets manager +- Different secrets per environment (no shared dev/prod secrets) +- Rotation schedule documented and followed +- Audit log of secret access +- Limited blast radius (each service has its own credentials, scoped narrowly) + +### Layer 6: Operational security + +How the team operates. + +- Access controls reviewed quarterly (offboard immediately on departure) +- 2FA enforced on every admin account (hosting, DNS, registrar, code host, deploy tools) +- Audit logs enabled and reviewed +- Vulnerability scanning (dependencies, containers, infrastructure) +- Patch cadence defined +- Incident response runbook exists (see `incident-response`) +- Backups exist and are tested (see `backup-and-disaster-recovery`) +- Security contact published (security.txt at /.well-known/security.txt) + +--- + +## Content Security Policy + +CSP is the most powerful response header and the most often misconfigured. Worth its own treatment. + +### What CSP does + +CSP tells the browser which sources are allowed for various resource types: scripts, styles, images, frames, connections, etc. A strict CSP prevents most XSS attacks even when input handling has bugs. + +### Two flavors + +**Strict CSP (recommended):** uses `nonce-` or `hash-` based source allowlists. Inline scripts must be explicitly allowed via nonce. + +``` +Content-Security-Policy: script-src 'self' 'nonce-{random}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; +``` + +**Allowlist CSP (legacy):** lists allowed domains. Easier to set up, much weaker. + +``` +Content-Security-Policy: script-src 'self' https://trusted.com; ... +``` + +Strict CSP requires application changes (every inline script needs a nonce). The investment pays off. + +### Roll out CSP gradually + +1. Start with `Content-Security-Policy-Report-Only` to log violations without blocking. +2. Set up a violation report endpoint. +3. Watch for legitimate violations (third-party scripts, inline handlers). +4. Tune the policy. +5. Switch to enforcing mode once violations are mostly false positives. +6. Continue monitoring violation reports for new issues. + +### Common CSP mistakes + +- `unsafe-inline` in script-src. Defeats most of CSP's value. +- `unsafe-eval` in script-src. Often required by older libraries; refactor or replace. +- Wildcard sources (`*`). Defeats the policy. +- Allowing CDNs that host arbitrary user content. Attackers can upload scripts to the CDN. +- Not restricting `frame-ancestors`. Use this for clickjacking defense (more flexible than `X-Frame-Options`). + +--- + +## Workflow + +### Step 1: Run a baseline scan + +Use a free scanner: securityheaders.com, observatory.mozilla.org. Get a current grade. This is the floor. + +### Step 2: Inventory the surface + +- Domains and subdomains in scope +- Public endpoints (forms, APIs) +- Authentication entry points +- Admin interfaces +- Third-party integrations and their permissions + +### Step 3: Audit each layer + +Walk the 6 layers. For each, document: +- What's in place +- What's missing +- Risk level (high, medium, low) + +### Step 4: Prioritize + +High risk, easy fixes go first: +- HSTS not set +- Default headers missing +- Admin without 2FA +- Old TLS versions enabled + +Medium risk, medium fixes next: +- CSP rollout +- Input validation gaps +- Secret management improvements + +Low risk, nice-to-haves last: +- Permissions-Policy refinements +- Optional headers (Cross-Origin-* family) + +### Step 5: Implement and verify + +For each fix: +- Make the change +- Test in a non-production environment +- Verify with a scanner +- Roll out +- Re-verify in production + +### Step 6: Set up monitoring + +- Certificate expiration alerts +- CSP violation reporting +- Failed login monitoring +- Unusual admin activity alerts +- Dependency vulnerability alerts (Dependabot, Snyk, or equivalent) + +### Step 7: Document the baseline + +Write a security baseline document. It says what's expected on every site: +- Required headers +- Required configurations +- Required practices + +New sites get audited against this. Existing sites get re-audited periodically. + +### Step 8: Schedule review + +Quarterly is the floor. Add reviews after major changes or incidents. + +--- + +## Common compliance touchpoints + +Not legal advice. Surfaces where security baseline meets compliance requirements: + +- **PCI DSS** (if handling payment cards): much more involved than baseline. The baseline is a starting point, not sufficient. +- **SOC 2:** baseline aligns with most CC controls (CC6 series). Documented baseline plus evidence of execution is the audit ask. +- **GDPR / privacy regs:** baseline supports security obligations (Article 32). Privacy is broader than security. +- **HIPAA, HITRUST, FedRAMP:** baseline is necessary, far from sufficient. Get specialized help. + +When compliance applies, the baseline is necessary but not the full answer. + +--- + +## Failure patterns + +**HSTS without `includeSubDomains`.** Attacker tricks browser into HTTP on a subdomain you haven't HTTPS'd yet. + +**HSTS preload without commitment.** Once preloaded, removing it takes weeks. Don't preload until HTTPS is solid across all subdomains forever. + +**CSP with `unsafe-inline`.** Defeats most of CSP. Either go strict (nonce-based) or accept that CSP is providing limited protection. + +**Default headers missing.** `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` are easy and free. Set them. + +**Admin without 2FA.** The single most common high-impact vulnerability across small teams. Fix today. + +**Secrets in environment variables baked into images.** Anyone with image access has the secrets. Use a runtime secret manager. + +**No security.txt.** Researchers find issues; they need somewhere to report. Publish a security.txt at /.well-known/security.txt. + +**Old TLS versions enabled.** Disable TLS 1.0 and 1.1. Most providers offer this as a checkbox. + +**CDN allowing arbitrary inline scripts via misconfigured CSP.** The CDN proxies user content; attackers leverage that. Audit the CSP against actual loaded resources. + +**No incident response plan.** When (not if) something happens, no runbook = chaos. See `incident-response`. + +**Vulnerability scanning without remediation.** Reports pile up. The scan is theater unless someone fixes findings. + +**Penetration test ignored.** Pen test report sits on a shelf. Test results without remediation are worse than no test. + +--- + +## Output format + +A security baseline document includes: + +- **Inventory:** what's in scope +- **Layer-by-layer status:** what's in place, what's missing +- **Required headers:** with values, applied per environment +- **Required configurations:** TLS, secrets, auth +- **Required operational practices:** access reviews, patch cadence, audit logging +- **Findings:** prioritized list of gaps +- **Remediation plan:** owners, dates +- **Re-audit cadence:** when this is reviewed next + +--- + +## Reference files + +- [`references/headers-checklist.md`](references/headers-checklist.md): A copy-paste checklist of recommended security headers with example values, organized by tier of importance. diff --git a/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md b/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md new file mode 100644 index 0000000..3a847f9 --- /dev/null +++ b/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md @@ -0,0 +1,311 @@ +# Security Headers Checklist + +Copy-paste reference for HTTP response headers that improve security. Organized by tier of importance. + +Test current headers with: securityheaders.com or observatory.mozilla.org. + +--- + +## Tier 1: Set on every site, no excuse + +These are simple to deploy, low risk of breaking things, and material security improvements. + +### Strict-Transport-Security (HSTS) + +Forces browsers to use HTTPS for all future requests to this domain. + +``` +Strict-Transport-Security: max-age=31536000; includeSubDomains +``` + +- `max-age`: lifetime in seconds (31536000 = 1 year, recommended for stable HTTPS deployments) +- `includeSubDomains`: applies to all subdomains. Only enable when every subdomain serves HTTPS reliably. +- `preload`: optional. Enables inclusion in browser preload lists. Once enabled, removal takes weeks. Only add when committed. + +**Common mistake:** Setting `includeSubDomains` before all subdomains are HTTPS-ready. Internal staging or admin subdomains break. + +--- + +### X-Content-Type-Options + +Prevents browsers from MIME-sniffing the content type, which can lead to confusion attacks. + +``` +X-Content-Type-Options: nosniff +``` + +No nuance. Set it everywhere. + +--- + +### X-Frame-Options + +Prevents your site from being framed by other sites (clickjacking defense). + +``` +X-Frame-Options: DENY +``` + +Use `SAMEORIGIN` instead if your own site uses iframes of itself. + +`X-Frame-Options` is largely superseded by CSP's `frame-ancestors`, but setting both is fine for backward compatibility with older browsers. + +--- + +### Referrer-Policy + +Controls how much information is sent in the Referer header on outbound links and resource loads. + +``` +Referrer-Policy: strict-origin-when-cross-origin +``` + +This sends full URL on same-origin requests, only the origin on cross-origin HTTPS-to-HTTPS, and nothing on HTTPS-to-HTTP downgrades. + +For privacy-sensitive sites: + +``` +Referrer-Policy: no-referrer +``` + +--- + +## Tier 2: Material security improvements, requires planning + +These add real protection but may require code changes or rollout planning. + +### Content-Security-Policy + +The most powerful header. Prevents most XSS attacks even when input handling has bugs. + +**Strict CSP (recommended for new sites):** + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' 'nonce-{random}' 'strict-dynamic'; + style-src 'self' 'nonce-{random}'; + img-src 'self' data: https:; + font-src 'self'; + connect-src 'self'; + frame-ancestors 'none'; + base-uri 'self'; + form-action 'self'; + object-src 'none'; + upgrade-insecure-requests; +``` + +**Notes:** +- `nonce-{random}` is replaced per request with a fresh random token, included on legitimate inline scripts. +- `'strict-dynamic'` allows scripts loaded by trusted scripts (recursive trust). Most modern apps need this. +- `frame-ancestors 'none'` is the modern equivalent of `X-Frame-Options: DENY` and is more flexible. +- `object-src 'none'` blocks Flash and similar (still useful even though Flash is dead). +- `base-uri 'self'` prevents base tag hijacking. + +**Allowlist CSP (if you can't do strict):** + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' https://trusted-cdn.com; + style-src 'self' 'unsafe-inline'; + img-src 'self' data: https:; + ... +``` + +This is weaker than strict CSP. Plan to migrate to strict. + +**Roll out via Report-Only first:** + +``` +Content-Security-Policy-Report-Only: ...; report-uri /csp-violation-report +``` + +Watch reports, tune, then switch to enforcing. + +--- + +### Permissions-Policy + +Controls which browser features (camera, microphone, geolocation, etc.) can be used. + +Conservative default: + +``` +Permissions-Policy: + accelerometer=(), + camera=(), + geolocation=(), + gyroscope=(), + magnetometer=(), + microphone=(), + payment=(), + usb=(), + interest-cohort=() +``` + +This denies all listed features by default. Allow specific ones if needed: + +``` +Permissions-Policy: camera=(self), geolocation=(self "https://maps.example.com") +``` + +`interest-cohort=()` opts the site out of FLoC and similar third-party tracking. + +--- + +## Tier 3: Newer, useful in specific contexts + +These provide additional isolation and protection. Some require more careful integration. + +### Cross-Origin-Opener-Policy (COOP) + +Isolates your site's window from cross-origin windows. Defends against cross-origin attacks like Spectre. + +``` +Cross-Origin-Opener-Policy: same-origin +``` + +May break some popup-based OAuth flows. Test carefully. + +--- + +### Cross-Origin-Embedder-Policy (COEP) + +Required for `SharedArrayBuffer` and high-resolution timers. Restricts what can be loaded. + +``` +Cross-Origin-Embedder-Policy: require-corp +``` + +Means every cross-origin resource you load must explicitly opt in via `Cross-Origin-Resource-Policy: cross-origin`. + +Often impractical for sites with many third-party resources. Use `credentialless` as a softer option: + +``` +Cross-Origin-Embedder-Policy: credentialless +``` + +--- + +### Cross-Origin-Resource-Policy (CORP) + +For your own resources (images, scripts, styles), declares who can include them. + +``` +Cross-Origin-Resource-Policy: same-origin +``` + +For resources you want others to be able to embed (a public CDN, a sharing widget): + +``` +Cross-Origin-Resource-Policy: cross-origin +``` + +--- + +### Reporting-Endpoints + +Modern way to specify where violation reports go (replaces the older `report-uri`). + +``` +Reporting-Endpoints: csp-endpoint="https://example.com/csp", default="https://example.com/reports" +Content-Security-Policy: ...; report-to csp-endpoint +``` + +--- + +## Headers to remove or set carefully + +### Server + +The `Server` header reveals what server software is running. + +``` +Server: nginx/1.18.0 +``` + +Reveals software and version. Helps attackers target known vulnerabilities. Set to a generic value or remove: + +``` +Server: web +``` + +(Or remove entirely if your stack allows.) + +--- + +### X-Powered-By + +Reveals the framework or language. + +``` +X-Powered-By: Express +X-Powered-By: PHP/8.0 +``` + +Same issue as `Server`. Remove. + +--- + +### X-AspNet-Version, X-AspNetMvc-Version + +Same. Remove. + +--- + +## What to skip + +These are deprecated, not useful, or actively harmful: + +- **`X-XSS-Protection`**: deprecated. Modern browsers ignore it. Use CSP instead. +- **`Public-Key-Pins`** (HPKP): removed from browsers. Don't bother. +- **`Expect-CT`**: deprecated. Certificate Transparency is enforced automatically. +- **`Feature-Policy`**: replaced by `Permissions-Policy`. Use the latter. + +--- + +## Quick reference table + +| Header | Tier | Default value | +|---|---|---| +| `Strict-Transport-Security` | 1 | `max-age=31536000; includeSubDomains` | +| `X-Content-Type-Options` | 1 | `nosniff` | +| `X-Frame-Options` | 1 | `DENY` (or `SAMEORIGIN`) | +| `Referrer-Policy` | 1 | `strict-origin-when-cross-origin` | +| `Content-Security-Policy` | 2 | Site-specific (see strict CSP example) | +| `Permissions-Policy` | 2 | Site-specific (deny by default) | +| `Cross-Origin-Opener-Policy` | 3 | `same-origin` | +| `Cross-Origin-Embedder-Policy` | 3 | `require-corp` or `credentialless` | +| `Cross-Origin-Resource-Policy` | 3 | `same-origin` (resources), `cross-origin` (public) | +| `Server` | Remove | Set generic or remove | +| `X-Powered-By` | Remove | Remove | + +--- + +## Verification + +After deploying, verify: + +```bash +curl -I https://example.com +``` + +Look for the headers in the response. + +Test grade: securityheaders.com gives a letter grade. Aim for A or A+. + +--- + +## Setting headers by stack + +Where you set these depends on the stack. Common locations: + +- **Reverse proxy (Nginx, Caddy, HAProxy):** in the proxy config +- **CDN (Cloudflare, Fastly, Akamai):** in the CDN's response header rules +- **Application (Express, Django, Rails, etc.):** middleware or filter +- **Hosting platform (Vercel, Netlify, Cloudflare Pages):** platform-specific config file (e.g., `vercel.json`, `_headers`) + +Setting at the edge (CDN or proxy) is preferred when possible: applies to every response without depending on application code. + +For dynamic values (like the CSP nonce), the header has to be set per-request from the application. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md b/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md new file mode 100644 index 0000000..c60a7b4 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-aeo-geo +description: "Optimize content and site structure for AI-driven search experiences including AI overviews, large language model citations, generative answer engines, and AI assistants. Use this skill whenever the user wants to optimize for AI search, get cited by language models, appear in AI overviews, build llms.txt, structure content for AI extraction, or future-proof their SEO for the shift from blue links to AI answers. Triggers on AEO, GEO, AI search, AI SEO, AI overview, generative search, LLM optimization, llms.txt, AI citation, ChatGPT search, Perplexity, Gemini, Claude search, AI assistant optimization, answer engine. Also triggers when the user expresses concern about AI eating their organic traffic or wants to understand how to remain visible as search shifts." +category: seo-foundation +catalog_summary: "AI search optimization, llms.txt, extraction-friendly content" +display_order: 7 +--- + +# AEO and GEO + +Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO). Make content discoverable, extractable, and citable by AI search experiences. + +This skill encodes principles. AI search products evolve fast. The principles age slower than the products. + +--- + +## When to use + +- Optimizing content for AI overviews and generative answer engines +- Building or updating llms.txt +- Structuring content so AI assistants can extract and cite it correctly +- Future-proofing a site as search shifts from blue links to AI answers +- Auditing whether existing content is AI-friendly +- Adding signals that help AI assistants identify the site as a trustworthy source + +## When NOT to use + +- Traditional on-page or technical SEO (use `seo-onpage` or `seo-technical`) +- Keyword research (use `seo-keyword`) +- Off-page authority and link building (use `seo-offpage`) + +This skill stacks on top of those. Strong AEO/GEO requires strong fundamental SEO underneath. + +--- + +## Required inputs + +- The site or page to optimize +- The topic area or query types AI should cite the site for +- Access to inspect rendered HTML and structured data + +--- + +## The framework: 5 layers + +AI search visibility comes from five stacked layers. Each layer compounds. + +### 1. Extractable content structure + +AI systems extract facts and pull citations from content. Make extraction easy. + +- **Direct answers.** Open major sections with a definitive 1 to 3 sentence answer to the question that section addresses. AI extracts the first answer it sees. +- **Question-headers.** Use H2s and H3s phrased as questions when natural. Mirrors how people prompt AI. +- **Atomic facts.** When stating a fact, state it once, clearly, with the supporting context next to it. AI struggles when claims are spread across paragraphs. +- **Tables and lists.** AI parses these reliably. Use them for comparisons, specs, steps, and data. +- **Definitions early.** When introducing a concept, define it inline. Do not assume the reader (or AI) saw a definition three pages ago. +- **Numbered steps.** For procedural content, number every step. Avoid prose disguised as instructions. + +### 2. Citation worthiness + +AI cites sources it considers authoritative. Earn that consideration. + +- **Original data.** Surveys, studies, proprietary research, internal benchmarks. AI prefers primary sources over restatements. +- **Specific numbers.** "Roughly 40 percent" beats "many." Specific stats with sources beat round-number generalizations. +- **Named experts.** Author bios with credentials, links to professional profiles, schema-marked-up Person entities. +- **Date stamps.** Publication date AND last-updated date, both visible AND in schema. AI heavily weights recency for time-sensitive queries. +- **Methodology disclosure.** When stating a finding, briefly note how it was reached. AI rewards transparency. +- **Citations of other sources.** Linking to authoritative sources you used builds reciprocal credibility. + +### 3. Structured data depth + +Schema is how you speak machine-readable language. AI assistants parse it heavily. + +- **Schema.org types** appropriate to content (Article, FAQPage, HowTo, Recipe, Product, Organization, Person, LocalBusiness, etc.) +- **Required AND recommended properties** filled in (most sites only fill required, leaving signal on the table) +- **Person schema** for authors, with `sameAs` links to verifiable profiles +- **Organization schema** on the homepage with logo, contact, social links +- **FAQPage schema** for content with genuine question-answer pairs +- **HowTo schema** for procedural content +- **BreadcrumbList schema** site-wide +- Validates in Schema.org Validator AND Rich Results Test (some properties differ) + +### 4. AI-readable accessibility + +Beyond traditional SEO, AI tools need access patterns of their own. + +- **llms.txt at the site root.** A markdown file at `/llms.txt` describing the site's content, key URLs, and what topics the site covers. See [`references/llms-txt-guide.md`](references/llms-txt-guide.md). +- **llms-full.txt** (optional) - a complete content dump for AI training and context, if the site permits it. +- **robots.txt allowing AI crawlers.** Decide explicitly which AI crawlers to allow (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, etc.) or disallow. Do not block by default if visibility matters. +- **Clean HTML semantics.** Semantic tags (`article`, `section`, `nav`, `main`) help AI parse structure. +- **Avoid client-side-only rendering for critical content.** Many AI crawlers render less reliably than Googlebot. + +### 5. Real-world entity signals + +AI builds knowledge graphs and prefers entities with multiple consistent signals. + +- **Wikipedia entry** if the brand or person qualifies for notability (do not force this; it requires genuine notability) +- **Wikidata entry** for the entity, with consistent properties +- **Consistent NAP** (Name, Address, Phone) across all citations +- **Brand mentions across multiple authoritative sources.** AI cross-references entity claims across the open web. +- **Social profile schema** linking owned profiles via `sameAs` properties +- **Reviews and reputation signals.** Aggregate ratings on Google Business, Trustpilot, industry-specific review sites where applicable + +--- + +## Workflow + +1. **Audit current state.** Run the 5-layer framework against the existing site. Score each. +2. **Identify the priority queries.** What questions should AI cite this site for? List 10 to 20. +3. **Test current AI visibility.** Query each of the major AI products (those relevant to the audience) with the priority questions. Note which sources they cite. +4. **Identify gaps.** Is the site cited? On which queries? Why does it lose to the cited sources? +5. **Layer-by-layer plan.** + - Fix extractable structure on top 20 priority pages + - Add citation-worthy signals (original data, expert authorship, methodology) + - Deepen schema implementation + - Build/update llms.txt + - Strengthen entity signals +6. **Implement and re-test.** AI products update frequently. Re-test priority queries quarterly. + +--- + +## Failure patterns + +- **Treating AEO/GEO as separate from SEO.** Strong fundamental SEO is a prerequisite. AI cites pages, not magic. +- **Stuffing FAQ schema on pages that have no genuine FAQs.** Search engines and AI alike penalize manufactured FAQ blocks. +- **Hiding key content behind heavy JavaScript.** AI crawlers render less reliably. Server-render or pre-render critical content. +- **Optimizing for one AI product only.** Different products use different ranking and citation logic. Optimize for the principles, not for one product's quirks. +- **Ignoring entity strength.** Content alone, with no real-world entity signals, will not get cited reliably for branded or expertise-related queries. +- **Treating llms.txt as a magic bullet.** It helps, but it is one of many signals. +- **Static optimization.** AI products evolve faster than search algorithms historically did. Re-audit at least quarterly. + +--- + +## Output format + +Default output is a markdown plan at `aeo-geo-strategy.md`. Structure: + +1. Current AI visibility audit (which queries cite the site, which do not) +2. 5-layer scorecard +3. Priority queries (the 10 to 20 the site should be cited for) +4. Layer-by-layer remediation plan +5. Implementation roadmap +6. Re-test schedule (quarterly) + +--- + +## Reference files + +- [`references/llms-txt-guide.md`](references/llms-txt-guide.md) - How to write a useful llms.txt, with examples. +- [`references/extraction-friendly-patterns.md`](references/extraction-friendly-patterns.md) - Content patterns that AI extracts cleanly, with before/after examples. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md b/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md new file mode 100644 index 0000000..2906fb1 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md @@ -0,0 +1,266 @@ +# Extraction-Friendly Patterns + +Content patterns that AI search experiences extract cleanly, with before-and-after examples. The goal is not to write for AI exclusively. The goal is to write so a human reader gets the answer fast and an AI extractor gets it fast too. The two overlap more than people think. + +--- + +## The principle + +AI extractors and skim-readers want the same thing: the answer first, the supporting context second. Content that buries the answer behind preamble loses both audiences. + +Three structural moves do most of the work: + +1. **Lead with the answer.** First sentence of the section answers the section's question. +2. **Use semantic structure.** Headings name the question. Lists separate items. Tables compare options. Code blocks contain code. +3. **Be self-contained.** Each section should make sense without depending on the section above. + +Everything below is an application of these three moves. + +--- + +## Pattern 1: question-led headings + +Headings phrased as the question the user actually asks. + +### Bad + +> ## Onboarding optimization + +### Better + +> ## How long should employee onboarding take? + +The question form does three jobs at once: it matches likely search queries, it tells the reader what they will learn, and it tells the AI extractor what answer follows. + +--- + +## Pattern 2: answer-first paragraph + +The first sentence answers the question. Subsequent sentences provide context, caveats, and depth. + +### Bad + +> ## How long should employee onboarding take? +> +> Onboarding has many definitions across organizations. Some companies define onboarding as the first day, some as the first week, and others as the entire ramp-up period. There is no industry consensus, and the question depends on many factors. With that said, most modern companies aim for a structured program lasting somewhere between 30 and 90 days. + +### Better + +> ## How long should employee onboarding take? +> +> Most structured onboarding programs run 30 to 90 days, with 90 being the most common. The exact length depends on role complexity, company size, and how much time managers can dedicate. The first week typically covers logistics and culture; the first month adds shadowing and small projects; the second and third months ramp the new hire into full ownership. + +The "Better" version puts the extractable answer in the first sentence. The follow-up adds context without burying the lead. + +--- + +## Pattern 3: definitions in inverse pyramid + +Define the term in one sentence, then expand. + +### Bad + +> ## What is a service blueprint? +> +> A service blueprint is a versatile tool used by many designers and product teams. Originally developed in the 1980s by G. Lynn Shostack at Bankers Trust, it has since been adopted across industries from healthcare to retail. Service blueprints help teams visualize the relationships between people, processes, and physical evidence in a service experience. + +### Better + +> ## What is a service blueprint? +> +> A service blueprint is a diagram that maps every step of a service experience, both what the customer sees and what happens behind the scenes. It typically uses lanes for the customer journey, frontstage actions, backstage actions, and supporting systems. Originally developed by G. Lynn Shostack in the 1980s, it is now standard in service design, healthcare workflow design, and operations planning. + +The first sentence is a complete, extractable definition. AI assistants quoting your page will quote this sentence. Search snippets will lift it. + +--- + +## Pattern 4: numbered lists for sequenced steps + +Sequenced procedures go in numbered lists. Not in prose. + +### Bad + +> To deploy with the CLI, first you'll want to run npm install. Once that completes, run npm run build to generate the production bundle, then npm run deploy to push to your environment. After that, verify the deployment by checking the status endpoint. + +### Better + +> ## How to deploy with the CLI +> +> 1. Install dependencies: `npm install` +> 2. Build the production bundle: `npm run build` +> 3. Deploy to your environment: `npm run deploy` +> 4. Verify the deployment by checking the status endpoint. + +The numbered list extracts cleanly into "how-to" snippets, FAQ-style answers, and HowTo schema. The prose version forces the extractor (human or AI) to do the work of parsing the steps. + +--- + +## Pattern 5: bullet lists for parallel items + +Parallel items go in bullets. Especially "what is included" or "options" lists. + +### Bad + +> Our enterprise tier includes single sign-on, audit logs, advanced role-based access controls, dedicated support, and custom data retention policies. + +### Better + +> ## What is included in the enterprise tier +> +> - Single sign-on (SSO) +> - Audit logs +> - Advanced role-based access controls +> - Dedicated support +> - Custom data retention policies + +The bullet form is extractable. An AI assistant asked "what does the enterprise tier include" can quote this list verbatim. + +--- + +## Pattern 6: tables for comparisons + +When comparing 2+ options across 2+ criteria, use a table. AI extractors handle tables well; prose comparisons get garbled. + +### Bad + +> The free plan supports up to 3 projects and 5 team members, with email support only. The pro plan extends this to 25 projects and 25 team members, adds priority support, and includes the API. The enterprise plan removes all limits, adds SSO, audit logs, and a dedicated success manager. + +### Better + +> | Feature | Free | Pro | Enterprise | +> |---|---|---|---| +> | Projects | 3 | 25 | Unlimited | +> | Team members | 5 | 25 | Unlimited | +> | Support | Email | Priority | Dedicated CSM | +> | API access | - | ✓ | ✓ | +> | SSO | - | - | ✓ | +> | Audit logs | - | - | ✓ | + +--- + +## Pattern 7: explicit Q&A blocks + +For pages where the user is asking a direct question (FAQs, help docs, glossaries), use explicit Q&A formatting. + +### Pattern + +> **Q: [The question phrased as the user would ask it]** +> +> A: [Direct answer in 1-3 sentences. Optional supporting paragraph after.] + +This is what FAQ schema lifts directly. AI extractors recognize the pattern and treat it as a discrete answerable unit. + +--- + +## Pattern 8: self-contained sections + +Each section under an H2 should make sense if read in isolation. AI extractors often pull a single section as the answer to a query. If the section depends on context from earlier sections, the answer it surfaces will be incomplete or wrong. + +### Bad + +> ## Setup +> +> Use the same approach we discussed in the previous section, but with the production endpoint instead of staging. + +### Better + +> ## Setup for production +> +> Run the deploy command against the production endpoint: +> +> ```bash +> npm run deploy --target=production +> ``` +> +> The production endpoint requires the `PROD_API_KEY` environment variable. See "Environment variables" for setup. + +The "Better" version stands alone. A reader (or AI assistant) landing here from search gets a complete answer. + +--- + +## Pattern 9: explicit data and units + +State numbers, ranges, and units explicitly. Vague modifiers ("a lot," "fast," "some users") do not extract. + +### Bad + +> Our customers see a major improvement in conversion after switching. + +### Better + +> On average, our customers see a 23% lift in conversion within the first 30 days after switching, based on data from 412 customers measured between January and March 2025. + +The "Better" version has extractable specifics: the metric, the magnitude, the time window, the sample size, and the date range. Trustworthy AI assistants prefer extracting specifics. + +--- + +## Pattern 10: structured author and date metadata + +For any content that depends on currency or expertise, expose the metadata visibly and in schema. + +- **Author byline** with a real name and a credential or one-line bio. +- **Publish date** and **last updated date** in human-readable form. +- **Reviewer** if the content is reviewed by an SME. +- Article schema with `author`, `datePublished`, `dateModified`, and (where applicable) `reviewedBy`. + +AI search uses author and date signals as part of trustworthiness scoring. + +--- + +## Pattern 11: explicit topic boundaries + +Tell the reader (and the extractor) what the page is and is not about. + +### Pattern + +> ## What this guide covers +> +> This guide covers backup strategies for Postgres databases on managed services (AWS RDS, GCP Cloud SQL, Supabase). It does not cover self-hosted Postgres tuning, backup of file storage, or disaster recovery testing. +> +> If you are self-hosting Postgres, see [other guide]. If you are designing DR drills, see [other guide]. + +This pattern protects against AI summaries that conflate your scope with adjacent topics. + +--- + +## Pattern 12: predictable summary blocks + +Sections like "Summary," "Key takeaways," "TL;DR" at the top or bottom of an article extract well. Keep them tight: 3-7 bullets, one short sentence each. + +### Pattern + +> ## Key takeaways +> +> - Aim for 30-90 day onboarding, with 90 being the most common. +> - First week: logistics and culture. First month: shadowing and small projects. Months 2-3: full ramp. +> - The single highest-impact factor is manager time, not program design. +> - Track time-to-productivity, not arbitrary onboarding completion. + +A summary block doubles as the AI snippet, the social card excerpt, and the email digest line. + +--- + +## What to avoid + +These patterns hurt extraction: + +- **Walls of text without headings.** The reader and the extractor both lose place. +- **Inline references that depend on prior sections.** "As mentioned above" is invisible to a snippet. +- **Vague modifiers in place of numbers.** "Many users," "several studies," "a long time." +- **Jargon without definition.** AI assistants will define it incorrectly if you do not. +- **Marketing fluff in lead sentences.** "Discover the powerful possibilities of..." extracts as gibberish. +- **PDFs and images for content that should be text.** Tables and key data trapped in images cannot be extracted. +- **Iframe-embedded content.** AI assistants do not consistently follow iframes. + +--- + +## How to test + +After writing a page, simulate extraction: + +1. Read only the H1 and the first sentence under each H2. Does the page still make sense? +2. Read only the bullet lists, tables, and Q&A blocks. Do they answer the obvious questions? +3. Ask an LLM (in a fresh context) the questions your page answers. Does it pull useful, accurate snippets from your page? +4. Check Google's "People also ask" for your topic. Does your page answer those exact questions? + +If a test fails, the structure needs more semantic markup, not more words. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md b/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md new file mode 100644 index 0000000..5360369 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md @@ -0,0 +1,227 @@ +# llms.txt Guide + +`llms.txt` is a markdown file at the root of a domain (e.g., `example.com/llms.txt`) that helps AI systems understand what the site is, what it covers, and which URLs are most valuable. + +It is the AI-era equivalent of `robots.txt` plus a sitemap, written in plain language for language models. + +This guide walks through how to write a useful one. + +--- + +## What llms.txt is for + +- Tell AI assistants what the site is and what it covers +- Point AI to the most valuable URLs for citation +- Provide structured context that helps AI summarize and cite the site accurately +- Reduce the chance of AI hallucinating about your brand or content + +What it is NOT: + +- A ranking signal (yet, possibly ever) +- A guarantee of citation +- A replacement for sitemap.xml or robots.txt +- A way to block AI crawlers (use robots.txt for that) + +--- + +## The format + +llms.txt is a markdown file with a specific structure: + +```markdown +# [Site or Brand Name] + +> [One-sentence description of what the site is and who it serves] + +[1 to 3 paragraphs of context. Who runs the site, what topics it covers, what makes it credible, what audience it serves. Plain language.] + +## [Section 1 - typically content categories or product lines] + +- [Title](URL): [One-line description] +- [Title](URL): [One-line description] + +## [Section 2] + +- [Title](URL): [One-line description] + +## Optional + +[Less critical resources.] +``` + +Section headers are flexible. Use whatever organization fits the site's content. + +--- + +## Example: a simple content site + +```markdown +# Example Knowledge Base + +> A free guide library on [topic area] for [audience]. + +We publish in-depth guides, comparisons, and how-tos on [topic area]. Content is written by [credentials of authors] and updated [frequency]. Our methodology is documented at /methodology. + +## Core guides + +- [The Complete Guide to X](https://example.com/complete-guide-x): A 5,000-word reference covering fundamentals through advanced topics. +- [How to Choose Y](https://example.com/how-to-choose-y): Decision framework with comparison tables and worked examples. +- [The Beginner's Guide to Z](https://example.com/beginner-z): A 30-minute primer for someone new to the topic. + +## Comparisons + +- [A vs B](https://example.com/a-vs-b): Head-to-head feature, pricing, and use case comparison. +- [Top 10 [Category]](https://example.com/top-10): Ranked list with selection criteria. + +## Tools + +- [Calculator](https://example.com/calculator): Free interactive tool for [purpose]. +- [Templates](https://example.com/templates): Downloadable templates with examples. + +## About + +- [About us](https://example.com/about) +- [Methodology](https://example.com/methodology) +- [Editorial standards](https://example.com/editorial-standards) +``` + +--- + +## Example: a SaaS product site + +```markdown +# ProductName + +> [Product category] for [target audience]. [Core value proposition in one phrase]. + +ProductName is built and operated by a team of [size and background]. We serve [audience description]. The product is used by [scale, e.g., "over 10,000 teams" or "from solo founders to Fortune 500 companies"]. + +## Product + +- [How it works](https://example.com/product): Overview of core functionality and architecture. +- [Pricing](https://example.com/pricing): Transparent pricing tiers and what each includes. +- [Integrations](https://example.com/integrations): Third-party tools we connect with. + +## Documentation + +- [Getting started](https://docs.example.com/getting-started): 15-minute setup guide. +- [API reference](https://docs.example.com/api): Complete API documentation. +- [Best practices](https://docs.example.com/best-practices): How successful customers use the product. + +## Resources + +- [Customer stories](https://example.com/customers): How specific customers achieved specific outcomes. +- [Blog](https://example.com/blog): Engineering posts, product updates, and industry analysis. +- [Changelog](https://example.com/changelog): Recent product changes. + +## Trust + +- [Security](https://example.com/security): SOC 2, encryption, compliance. +- [Privacy policy](https://example.com/privacy) +- [Terms of service](https://example.com/terms) +``` + +--- + +## What to include + +A good llms.txt is curated, not exhaustive. Include: + +- **Cornerstone content.** Your 10 to 30 best, most authoritative pieces. +- **Decision-support pages.** Comparisons, calculators, frameworks. +- **Authority signals.** Methodology, editorial standards, about pages. +- **Trust signals.** Security, privacy, compliance, certification pages. +- **Recency cues.** A changelog or "latest" link if you publish frequently. + +What to leave out: + +- Every URL on the site (use sitemap.xml for that) +- Marketing fluff with no informational substance +- Pages that exist primarily for SEO (low-quality programmatic content, doorway pages) +- Internal admin URLs + +--- + +## What to write in the description + +The opening description (under the title, prefixed by `>`) is what AI extracts when asked "what is [site]?" Make it count. + +**Bad description:** +> A leading provider of innovative solutions in the digital space. + +**Good description:** +> A free guide library on home renovation for first-time buyers, with calculators and template contracts. + +The good description names: what it is (guide library), what topic (home renovation), who it serves (first-time buyers), and what's unique (calculators and templates). + +--- + +## Length and depth + +- **Title and one-sentence description**: required +- **Context paragraphs**: 1 to 3 paragraphs, 100 to 400 words total +- **Sections**: 3 to 8 sections is typical +- **URLs per section**: 3 to 10 is the sweet spot +- **Total file length**: 500 to 2000 words for most sites + +A 50-word llms.txt is too thin to be useful. A 5000-word llms.txt buries the signal. + +--- + +## Updating + +- Update llms.txt when you launch a major new content category, product, or section +- Re-review at least quarterly +- Remove dead links (broken URLs in llms.txt actively damage credibility with AI) +- Keep the description fresh as the site evolves + +--- + +## llms-full.txt (the optional sibling) + +Some sites also publish `llms-full.txt`, which contains the full text content of the linked pages concatenated into one file. This is more aggressive: it offers AI systems the entire content for context. + +Reasons to publish it: + +- You want maximum AI context, including verbatim content +- Your content is freely licensed or you accept it being used for AI training +- Your content is short enough that the file is manageable (under 10MB, ideally under 5MB) + +Reasons NOT to publish it: + +- You sell or gate content (e.g., paid courses, premium reports) +- Your terms of service disallow AI training on your content +- File size would exceed reasonable limits + +If you do publish it, link to it from llms.txt: + +```markdown +## Full content + +- [Full content dump](https://example.com/llms-full.txt): The complete content of all linked pages. +``` + +--- + +## Common mistakes + +- **Auto-generating llms.txt from sitemap.xml.** Defeats the purpose. The point is editorial curation. +- **Treating it as a sitemap.** Sitemap is for crawlers. llms.txt is for AI context. +- **Stuffing it with thin content.** Every URL listed should be content you would proudly cite if a human asked. +- **Forgetting to update it.** A 2-year-old llms.txt makes you look abandoned. +- **Hosting it at a non-root path.** It belongs at `/llms.txt` (root of the domain), not `/docs/llms.txt`. +- **Returning HTML instead of plain text.** Serve as `text/markdown` or `text/plain`, not as a rendered HTML page. + +--- + +## Verification + +After publishing: + +- [ ] File is at `https://yourdomain.com/llms.txt` (root) +- [ ] File serves with content type `text/markdown` or `text/plain` +- [ ] All linked URLs return 200 +- [ ] All linked URLs use the canonical URL form (no redirects) +- [ ] File is referenced (or at least not blocked) in robots.txt +- [ ] File renders cleanly in a plain text viewer +- [ ] Description and section headings accurately describe the site diff --git a/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md b/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md new file mode 100644 index 0000000..92c3e96 --- /dev/null +++ b/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md @@ -0,0 +1,182 @@ +--- +name: seo-audit-orchestration +description: "Master orchestrator for a full SEO audit suite powered by the Ahrefs MCP. Use this skill when running a comprehensive SEO audit, scoping a quarterly health check, doing pre-acquisition SEO due diligence, or post-migration verification. Triggers on full SEO audit, comprehensive SEO review, SEO health check, audit my site, SEO due diligence, audit suite, comprehensive audit, end-to-end SEO. Also triggers when a stakeholder wants the complete picture rather than a single-dimension audit." +category: seo-audit-suite +catalog_summary: "Master orchestrator: sequences the suite, produces a rollup report" +display_order: 1 +--- + +# SEO Audit Orchestration + +Run a complete SEO audit by sequencing the sibling audit skills in a defined order. Stack-agnostic. Assumes the Ahrefs MCP is connected. Produces a single rollup report that synthesizes findings across backlinks, keywords, content, traffic, technical health, and rankings. + +--- + +## When to use + +- Running a full SEO audit (quarterly, biannual, annual) +- Pre-acquisition SEO due diligence +- Post-migration verification (after content move, replatform, or domain change) +- Onboarding a new client or new property +- Building a baseline before a major SEO investment +- Diagnosing chronic underperformance + +## When NOT to use + +- Single-dimension audits (use the specific child skill: `seo-onpage`, `seo-backlink-audit`, etc.) +- Investigating a specific traffic drop (use `seo-traffic-diagnosis`) +- Tactical questions like "which keywords should we target" (use `seo-keyword-gap-audit`) +- Routine monitoring (use `seo-rank-tracking`) + +--- + +## Required inputs + +- The site or properties in scope +- Target market and primary languages +- Competitor set (3-5 properties) +- Goal of the audit (baseline, due diligence, fix plan, growth roadmap) +- Time and reporting constraints +- Confirmation that the Ahrefs MCP is connected and the workspace has access to the target property + +--- + +## The framework: 6 phases of an end-to-end audit + +A complete audit moves through six phases in order. Skipping phases produces gaps. Reordering them produces rework. + +### Phase 1: Scope and baseline + +Define the audit before running it. + +- What is in scope (subdomains, paths, languages) +- What is out of scope +- Goal of the audit (baseline, fix plan, growth roadmap, due diligence) +- Stakeholders and their priorities +- Reporting format and length expectations + +Output: a 1-page audit charter. + +### Phase 2: Data gather + +Pull the raw data from Ahrefs and any companion sources. + +Required pulls: + +- Site Explorer: organic keywords, organic traffic, top pages, top countries, referring domains, backlinks, anchor text profile +- Site Audit: full crawl results +- Keywords Explorer: target keyword universe and competitor keyword overlap +- Content Explorer: top performing content in target topics +- Rank Tracker: current tracked positions if set up + +Companion pulls (not Ahrefs-native): + +- Search Console: query and page data, coverage issues +- Analytics: traffic, conversions, segment by source +- Server logs (if available): bot crawl behavior + +Document data freshness for every pull. Stale data yields wrong conclusions. + +### Phase 3: Run the sub-audits + +Run each child audit. Each produces its own findings doc. + +| Sub-audit | Skill | What it produces | +| --- | --- | --- | +| Site health | `seo-site-health-audit` | Prioritized technical fix backlog | +| Backlinks | `seo-backlink-audit` | Profile health, toxic list, reclamation list | +| Keywords | `seo-keyword-gap-audit` | Prioritized opportunity list | +| Content | `seo-content-gap-audit` | Create/update/merge roadmap | +| Page-level | `seo-onpage` | Per-page audit on top pages | +| AI search | `seo-aeo-geo` | AI search readiness gaps | + +The child skills do the analysis. This skill sequences them and integrates the outputs. + +### Phase 4: Synthesize + +Combine findings into themes. A list of 200 issues is not an audit. A list of 5-7 themes is. + +Themes typically emerge in categories like: + +- Technical foundation gaps that cap upside +- Content depth gaps in priority topics +- Backlink profile concentration risks +- Keyword opportunities the site is leaving on the table +- Cannibalization or thin coverage +- AI search readiness + +Each theme should answer: what is happening, why it matters, what is the size of prize, what is the fix. + +### Phase 5: Prioritize + +Rank the themes. Use a simple impact/effort matrix. + +- Quick wins: high impact, low effort. Do now. +- Strategic plays: high impact, high effort. Plan and resource. +- Maintenance: low impact, low effort. Backlog. +- Avoid: low impact, high effort. Drop. + +Tie each theme to a measurable target (organic clicks, ranked keywords in target band, conversions from organic). + +### Phase 6: Deliver + +Produce the rollup report. See [`references/audit-rollup-template.md`](references/audit-rollup-template.md). + +Structure: + +- Executive summary (1 page) +- Themes and recommendations (5-7 themes, 1 page each) +- Sub-audit findings (linked or appended) +- Roadmap (next 90 days) + +Walk stakeholders through it. Get commitment to the next 90 days of work. + +--- + +## Workflow + +1. **Charter the audit.** 1-page scope, goal, stakeholders, format. +2. **Confirm Ahrefs MCP access.** Verify the workspace has the target property and recent data. +3. **Pull all data.** Run the gather list in phase 2. Document freshness. +4. **Run each sub-audit.** Use the child skills. Each produces its own findings doc. +5. **Synthesize themes.** 5-7 themes max. Each ties to an impact and a fix. +6. **Prioritize.** Impact/effort matrix. Quick wins surface to the top. +7. **Draft the rollup.** Use the template. Executive summary first. +8. **Review with the team.** Pressure-test conclusions before stakeholder readout. +9. **Deliver.** Walk stakeholders through. Get commitment to next 90 days. +10. **Schedule the next one.** Audits decay. Rerun on a cadence. + +--- + +## Failure patterns + +- **Audit without a goal.** Produces a 60-page document nobody reads. Charter the audit first. +- **All findings, no themes.** A list of 200 issues is data, not an audit. Synthesize into themes. +- **Skipping the sub-audits.** Running one big audit instead of six focused ones produces shallow analysis everywhere. +- **No prioritization.** "Here are 47 things to fix" gets nothing fixed. Rank them. +- **Stale data.** Ahrefs index updates on a delay. Note freshness. Do not draw conclusions from week-old movement. +- **Tool worship.** Ahrefs is one source. Search Console, analytics, and logs add ground truth. Triangulate. +- **Audit-to-audit drift.** Running every audit differently makes trends impossible to spot. Standardize the structure. +- **No 90-day roadmap.** Without a plan after the audit, the audit is shelfware. +- **Solo audit.** Audits done alone miss context. Pull in the people who own the work. + +--- + +## Output format + +A rollup audit report with: + +1. **Executive summary** (1 page). +2. **Audit charter** (scope, goal, methodology). +3. **Themes and recommendations** (5-7 themes, each with what, why, size of prize, fix). +4. **Sub-audit appendix** (linked outputs from each child skill). +5. **90-day roadmap** (sequenced work with owners and targets). +6. **Methodology notes** (data sources, pull dates, caveats). + +Total length: 15-30 pages including appendices. Executive summary readable in 5 minutes. + +--- + +## Reference files + +- [`references/audit-rollup-template.md`](references/audit-rollup-template.md) - Template for the rollup report including executive summary, theme structure, and roadmap format. diff --git a/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md b/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md new file mode 100644 index 0000000..2343b76 --- /dev/null +++ b/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md @@ -0,0 +1,236 @@ +# Audit rollup template + +A template for the final SEO audit deliverable. Adapt sections to fit the audit goal and stakeholder appetite. + +--- + +## Document structure + +``` +1. Executive summary (1 page) +2. Audit charter (1 page) +3. Themes and recommendations (5-7 themes, 1 page each) +4. 90-day roadmap (1-2 pages) +5. Sub-audit appendix (linked or attached) +6. Methodology notes (1 page) +``` + +Total: 15-30 pages. Executive summary always readable in 5 minutes. + +--- + +## 1. Executive summary template + +``` +# [Property] SEO Audit + +**Audit date:** [date] +**Period covered:** [date range] +**Auditor:** [name or team] + +## Headline + +[One sentence. The state of SEO at this property.] + +## Top 3 themes + +1. **[Theme name].** [One sentence. Why it matters.] +2. **[Theme name].** [One sentence. Why it matters.] +3. **[Theme name].** [One sentence. Why it matters.] + +## Top 3 quick wins + +1. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. +2. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. +3. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. + +## Recommended next 90 days + +[3-5 bullets describing the proposed plan.] + +## What is going well + +[2-4 bullets. Avoid an audit that reads as 100% negative.] +``` + +--- + +## 2. Audit charter template + +``` +## Scope + +- Properties in scope: [list] +- Languages: [list] +- Subdomains: [list] +- Out of scope: [list] + +## Goal + +[Baseline / fix plan / growth roadmap / due diligence] + +## Stakeholders + +| Name | Role | Priority | +| --- | --- | --- | +| [name] | [role] | [their main concern] | + +## Methodology + +- Data sources: [Ahrefs, Search Console, Analytics, logs] +- Pull dates: [dates] +- Sub-audits run: [list] + +## Limitations + +[Anything that limits confidence: data gaps, access restrictions, time constraints.] +``` + +--- + +## 3. Theme template + +Use one page per theme. 5-7 themes total. + +``` +## Theme [N]: [Name] + +**What is happening** + +[2-3 sentences describing the pattern.] + +**Why it matters** + +[2-3 sentences linking the pattern to a business outcome.] + +**Size of prize** + +[Quantified opportunity. E.g., "+12,000 monthly clicks" or "+$80k annual revenue at current conversion."] + +**Evidence** + +- [Data point with source] +- [Data point with source] +- [Data point with source] + +**Recommendation** + +[The proposed fix or action. 1 paragraph.] + +**Effort and timeline** + +[Effort: S/M/L. Timeline: weeks or sprints. Dependencies: list.] + +**Owners** + +[Who needs to do what.] +``` + +--- + +## 4. 90-day roadmap template + +Sequence the work. Tie to themes. Assign owners. + +``` +## Days 1-30 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Days 31-60 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Days 61-90 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Review cadence + +[Weekly, biweekly, monthly. Who attends. What is reviewed.] +``` + +--- + +## 5. Sub-audit appendix + +Link or attach the output from each child skill: + +- Site health audit: [link or attachment] +- Backlink audit: [link or attachment] +- Keyword gap audit: [link or attachment] +- Content gap audit: [link or attachment] +- Page-level audits (top pages): [link or attachment] +- AI search readiness: [link or attachment] + +Do not paste full sub-audits into the rollup. Reference them. Stakeholders who want detail can drill in. + +--- + +## 6. Methodology notes + +``` +## Data sources and freshness + +| Source | Pull date | Coverage | Notes | +| --- | --- | --- | --- | +| Ahrefs Site Explorer | [date] | [scope] | [caveats] | +| Ahrefs Site Audit | [date] | [scope] | [caveats] | +| Search Console | [date range] | [scope] | [caveats] | +| Analytics | [date range] | [scope] | [caveats] | + +## Caveats + +- Ahrefs metrics are estimates, not ground truth. +- Search Console data is sampled and capped. +- Analytics may have tagging gaps. +- Server log data was [available / unavailable] for this audit. + +## Repeatability + +To rerun this audit: + +- [Steps to reproduce data pulls] +- [Saved Ahrefs reports or filters] +- [Companion data pull instructions] +``` + +--- + +## Style guidance + +- Lead with the "so what." Stakeholders skim. +- Quantify wherever possible. Vague impact claims get ignored. +- Pair every problem with a proposed fix. Audits without recommendations are reports. +- Keep technical jargon out of the executive summary. +- Use tables and bullets. Avoid wall-of-text. + +--- + +## Common length targets by audit type + +| Audit type | Total length | Executive summary | Themes | +| --- | --- | --- | --- | +| Quarterly health check | 10-15 pages | 1 page | 3-4 themes | +| Full annual audit | 25-40 pages | 1-2 pages | 5-7 themes | +| Pre-acquisition due diligence | 30-50 pages | 2 pages | 6-10 themes | +| Post-migration verification | 10-20 pages | 1 page | 3-5 themes | + +--- + +## Pre-delivery checklist + +- [ ] Executive summary readable in 5 minutes +- [ ] Every theme tied to a quantified impact +- [ ] Every recommendation tied to an owner +- [ ] Quick wins called out separately +- [ ] 90-day roadmap is sequenced and resourced +- [ ] Methodology and caveats are documented +- [ ] Internal review completed before stakeholder readout +- [ ] Next audit date scheduled diff --git a/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md b/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md new file mode 100644 index 0000000..31e223d --- /dev/null +++ b/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md @@ -0,0 +1,166 @@ +--- +name: seo-backlink-audit +description: "Audit a backlink profile using Ahrefs MCP data: profile health, anchor text distribution, toxic link identification, lost link reclamation, and gap analysis against competitors. Use this skill when reviewing backlink health, scoping a disavow project, recovering from a manual action, planning link building, or doing M&A due diligence on a property's link equity. Triggers on backlink audit, link profile, toxic links, disavow, anchor text analysis, lost links, link reclamation, referring domains, link gap. Also triggers when traffic decline correlates with link loss or when an unnatural link warning appears in Search Console." +category: seo-audit-suite +catalog_summary: "Profile health, anchor mix, toxic links, reclamation, gap analysis" +display_order: 2 +--- + +# SEO Backlink Audit + +Audit a backlink profile using data pulled from the Ahrefs MCP. Stack-agnostic. Produces a profile health assessment, a toxic link list (if needed), a reclamation list, and a gap analysis against competitors. + +--- + +## When to use + +- Periodic backlink health check (quarterly or biannual) +- Recovering from a Google manual action or unnatural link warning +- Scoping a disavow file +- Pre-acquisition due diligence on link equity +- Planning a link building campaign (need a baseline) +- Investigating ranking drops correlated with link loss +- Recovering lost links after a migration or replatform + +## When NOT to use + +- Building new links (use `seo-offpage`) +- General SEO audits (use `seo-audit-orchestration`) +- Keyword opportunity analysis (use `seo-keyword-gap-audit`) +- Technical issues unrelated to links (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Target property (root domain, subdomain, or URL prefix) +- Competitor set (3-5 properties with comparable strategies) +- Time window (typically last 12-24 months) +- Confirmation Ahrefs MCP is connected and has access to the property +- Search Console manual action status (if any) +- Recent SEO history (migrations, link campaigns, penalties) + +--- + +## The framework: 5 dimensions of a backlink profile + +A profile is healthy when all five dimensions are healthy. Issues in any one can cap rankings or invite penalties. + +### Dimension 1: Referring domain quality + +Volume of links matters less than the quality and relevance of the linking domains. + +Pull from Ahrefs: + +- Total referring domains (current and trended) +- Domain Rating distribution (DR bands) +- Topical relevance of linking domains +- Geographic distribution (where appropriate) +- Domain age and trust signals + +Healthy signal: a long tail of relevant, established domains. Concentration in any single source is a risk. + +### Dimension 2: Link velocity + +How fast links are gained or lost. + +Pull from Ahrefs: + +- New referring domains per month (trended 12-24 months) +- Lost referring domains per month +- Net change + +Healthy signal: steady positive growth. Sudden spikes suggest paid campaigns or negative SEO. Sudden drops correlate with redirect mistakes, content removal, or the linking sites going down. + +### Dimension 3: Anchor text distribution + +The mix of anchor types tells search engines what the property is about and whether the profile looks natural. + +Categories to map: + +- Branded (the brand name) +- Naked URL +- Generic ("click here", "this page") +- Exact-match keyword +- Partial-match keyword +- Image (alt text or none) + +Healthy signal: branded and naked URL anchors dominate. Exact-match keyword anchors are a small minority. Heavy exact-match concentration triggers spam filters. + +### Dimension 4: Link types + +Not all links are equal. + +Categories: + +- Dofollow versus nofollow +- Editorial versus directory or comment +- In-content versus footer or sidebar +- Sponsored or UGC tagged +- Redirect chains +- Lost links recoverable via outreach + +Healthy signal: editorial in-content dofollow links from relevant sites dominate. + +### Dimension 5: Competitive gap + +What links do peers have that you do not? + +Pull from Ahrefs: + +- Domains linking to 2+ competitors but not the target +- Domains linking to 1 competitor with high relevance to the target +- Top performing competitor pages by referring domain count + +Healthy signal: the gap is shrinking over time. A widening gap is a strategic risk. + +--- + +## Workflow + +1. **Charter the audit.** Goal, scope, time window, competitor set. +2. **Pull baseline data.** Referring domains, anchor text, link types, lost links, competitor overlap. +3. **Map the profile across 5 dimensions.** One section per dimension. +4. **Identify red flags.** Velocity spikes, anchor concentration, low-DR concentration, suspect TLDs, repeated footprints. +5. **Build the toxic list (if needed).** Use the criteria in [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md). +6. **Build the reclamation list.** Lost links worth recovering via outreach. +7. **Build the gap list.** Domains linking to peers, prioritized by relevance. +8. **Synthesize.** Profile health verdict, top 3 risks, top 3 opportunities. +9. **Recommend.** Disavow (rare), reclamation outreach, link building targets, monitoring cadence. +10. **Document and hand off.** Outputs feed `seo-offpage` and `seo-audit-orchestration`. + +--- + +## Failure patterns + +- **Disavow happy.** Most profiles do not need a disavow. Disavowing legitimate links damages rankings. Use it only after a manual action or clear algorithmic signals. +- **Counting links instead of evaluating them.** A profile with 10,000 referring domains can be weaker than one with 200 high-quality editorial links. +- **Ignoring lost links.** Recovering a lost link is faster and cheaper than building a new one. +- **No competitor benchmark.** Profile health is relative. A "low" backlink count for a tier-1 competitor is a "great" count for a niche site. +- **Anchor text panic.** A high exact-match percentage in absolute terms is fine for niche sites where the brand and keyword overlap. Investigate before disavowing. +- **One-time audit.** Profile health drifts. Audit on a cadence (quarterly minimum for active properties). +- **Treating Ahrefs as ground truth.** Ahrefs sees most links but not all. Triangulate with Search Console for completeness. +- **Over-indexing on Domain Rating.** DR is a relative metric, not a quality signal. A DR-30 niche site can be more valuable than a DR-80 generalist. + +--- + +## Output format + +A backlink audit document with: + +1. **Executive summary.** Profile health verdict and top risks. +2. **Profile snapshot.** Key metrics: referring domains, DR distribution, anchor mix, velocity. +3. **5-dimension analysis.** One section per dimension with findings. +4. **Toxic link list.** If needed. Disavow file ready format. +5. **Reclamation list.** Lost links worth recovering, with contact paths. +6. **Gap list.** Top 50 domains linking to competitors but not target. +7. **Recommendations.** Disavow (Y/N), reclamation outreach plan, link building targets. +8. **Methodology.** Data sources, pull dates, criteria used. + +Length: 8-15 pages depending on profile complexity. + +--- + +## Reference files + +- [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md) - Decision framework for classifying a link as toxic, including the disavow file format and threshold guidance. diff --git a/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md b/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md new file mode 100644 index 0000000..8e26d42 --- /dev/null +++ b/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md @@ -0,0 +1,182 @@ +# Toxic link criteria + +A decision framework for classifying a backlink as toxic and worth disavowing. Bias the framework toward keeping links unless the case is clear. Disavowing legitimate links damages rankings. + +--- + +## The disavow bar + +Disavow when one or more of the following is true: + +1. The site has been hit with an algorithmic devaluation that correlates with link-based signals. +2. The site has received a manual action citing unnatural links. +3. There is clear evidence of a negative SEO attack with low-quality links pointed at the property. +4. Pre-acquisition due diligence on a property reveals a known toxic profile. + +Outside these cases, the default is to leave links alone. Google has stated repeatedly that they ignore most low-quality links automatically. + +--- + +## Per-link signals (any one is concerning, multiple is decisive) + +### Site-level signals + +| Signal | Severity | +| --- | --- | +| Site is in a known link network | High | +| Site exists primarily to host links | High | +| Site has thin or auto-generated content | High | +| Site is on a suspect TLD pattern (mass registered) | Medium | +| Site has no organic traffic per Ahrefs estimates | Medium | +| Site is in an irrelevant language or geography | Medium | +| Site has been deindexed or penalized | High | +| Site is parked or for sale | High | +| Site has a footprint shared with many other suspect sites | High | + +### Page-level signals + +| Signal | Severity | +| --- | --- | +| Page is a low-effort link page or directory | Medium | +| Page has a high outbound link count with no editorial logic | Medium | +| Page is hidden from the site's main navigation | Medium | +| Page is in a foreign language with no relevance | Medium | +| Page has been hacked or is serving malware | High | + +### Link-level signals + +| Signal | Severity | +| --- | --- | +| Anchor text is exact-match commercial and unnatural in context | High | +| Link is in a footer with hundreds of others | Medium | +| Link is part of a sitewide footer link | Medium | +| Link is in a comment with promotional text | Low | +| Link is paid without disclosure | High | + +--- + +## Deciding by domain versus by URL + +Disavow at the domain level when: + +- The entire site is suspect. +- Multiple pages from the same site link to you. +- You expect the site to keep adding links. + +Disavow at the URL level when: + +- Only one specific page is suspect on an otherwise legitimate site. +- The site has editorial credibility but a single contributor placed the link. + +Default to domain-level disavow when in doubt. URL-level disavows are fragile: the site can move the content and the disavow no longer applies. + +--- + +## Outreach before disavow + +Disavow is a last resort. Before disavowing, attempt outreach for high-value but problematic links: + +1. Find a contact (whois, contact page, social). +2. Send a polite link removal request. +3. Wait 14 days. +4. Send a follow-up. +5. If no response after 30 days, disavow. + +Document outreach attempts. If a manual action review is needed later, Google requires evidence of cleanup effort beyond just a disavow file. + +--- + +## Disavow file format + +The disavow file is a plain text file submitted to Google Search Console. + +Format: + +``` +# Disavow file for [property] +# Last updated: [date] +# Submitted: [date or pending] + +# Section 1: Domain-level disavows + +domain:lowqualitysite-example.com +domain:linkfarm-example.net +domain:hackedsite-example.org + +# Section 2: URL-level disavows + +https://otherwiselegitimate-example.com/sponsored-post-page + +# Section 3: Notes for future me + +# - Disavowed lowqualitysite-example.com after manual action 2024-03 +# - Reviewed quarterly +``` + +Rules: + +- One entry per line +- `domain:` prefix for domain-level +- Full URL for URL-level +- Lines starting with `#` are comments and ignored +- File must be UTF-8 plain text +- Maximum 100,000 lines or 2 MB + +--- + +## Bulk classification heuristic + +When auditing thousands of referring domains, use this triage: + +### Round 1: filter obvious keepers + +Mark as KEEP without further review: + +- Domain Rating above a relevance-appropriate threshold and topical match +- Known media, government, education domains +- Linking from a page with organic traffic + +Skip these. They are not toxic. + +### Round 2: filter obvious toxics + +Mark as TOXIC for further review: + +- Domain Rating zero with no organic traffic +- TLDs in known spam patterns +- Domains matching known link network footprints +- Sites that link to thousands of unrelated properties + +### Round 3: review the middle + +The remaining domains need manual review. Apply the per-link signal table above. + +Expected breakdown for a healthy profile: 80%+ keep, 5-15% review, under 5% toxic. If toxic exceeds 20%, the profile has structural problems beyond a disavow. + +--- + +## After disavow + +- Submit the file in Search Console. +- Document submission date in your audit log. +- Wait 4-8 weeks before evaluating impact. +- Recrawl can take longer for larger sites. +- Do not submit revised disavows weekly. Submit, wait, evaluate. + +If a manual action was the trigger, file a reconsideration request with: + +- Summary of the cleanup effort +- Evidence of outreach attempts +- The submitted disavow file +- An honest acknowledgment of the cause + +--- + +## Common mistakes + +- **Disavowing low-traffic links indiscriminately.** Most have no negative effect. Disavowing them can lose minor positive equity. +- **Disavowing competitor links by accident.** Double-check the file before submission. +- **Forgetting that disavow is reversible.** Resubmit a file without the entry to remove a disavow. Test cautiously. +- **Treating disavow as a recurring task.** It is not. Audit and submit when needed. Otherwise leave it alone. +- **Disavowing without documenting why.** Six months later you will not remember which entries were intentional. +- **Using disavow as a substitute for outreach.** For high-value links, removal is better than disavow. diff --git a/dist/pi/.agents/skills/seo-competitor/SKILL.md b/dist/pi/.agents/skills/seo-competitor/SKILL.md new file mode 100644 index 0000000..39e585d --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/SKILL.md @@ -0,0 +1,137 @@ +--- +name: seo-competitor +description: "Run a competitive SEO analysis comparing the user's site to chosen competitors across SERP overlap, content depth, backlink profiles, technical posture, and brand presence. Use this skill whenever the user wants to analyze competitors, find content gaps, identify backlink opportunities, understand why competitors outrank them, or benchmark against the rest of their category. Triggers on competitor analysis, competitive analysis, SERP analysis, content gap, backlink gap, why is X ranking, who is winning the SERP, beat my competitor, benchmark, market positioning. Also triggers when planning a content strategy and the question 'what are competitors doing' is implicit." +category: seo-foundation +catalog_summary: "SERP overlap, content gaps, backlink gaps, technical comparison" +display_order: 4 +--- + +# SEO Competitor Analysis + +Compare a site to its competitors and find the gaps worth closing. Stack-agnostic. Tool-friendly but tool-optional. + +--- + +## When to use + +- Identifying which competitors to study +- Finding content gaps (topics they cover, you do not) +- Finding backlink gaps (sites linking to them, not you) +- Understanding why a specific competitor outranks the user +- Benchmarking authority, technical posture, and content depth + +## When NOT to use + +- Single-page optimization (use `seo-onpage`) +- Initial keyword research with no competitors yet identified (use `seo-keyword` first to find them) +- Auditing one's own existing content (use `seo-content-audit`) + +--- + +## Required inputs + +- The user's site +- 3 to 5 named competitors (or the topic area, if competitors are not yet identified) +- Access to a keyword tool, a backlink tool, and any crawler + +If competitors are unknown, start by listing the top 10 ranking domains for the user's top 10 priority keywords. Pick the 3 to 5 that appear most often. + +Where competitor traffic estimation is the input you need (relative scale, channel mix, audience overlap), Similarweb MCP is the strongest source. Pair with Ahrefs (for backlink and keyword overlap) and Semrush (for SERP feature presence and SEO-PR overlap). Each platform gives a different cut of the same competitive landscape; using them together produces sharper signal than any one alone. + +--- + +## The framework: 5 angles + +Competitor analysis covers five angles. Run all five for a full picture, or pick two or three for a focused investigation. + +### 1. SERP overlap +Where do you and the competitor compete head-to-head? + +- For each priority keyword, who ranks in the top 10? +- For each top-10 ranking, what page type wins (article, product, comparison, video)? +- Are there SERP features (featured snippet, AI overview, video, image pack) one party holds and the other does not? +- Which queries do competitors rank for that the user does not? (the content gap) + +### 2. Content depth +What does their winning content look like? + +- Word count and structure of their top-ranking pages +- Information types they include (data tables, original research, video, calculators, downloadable assets) +- Update frequency on key pages (last modified date, change history) +- Internal linking patterns (do their winning pages link to commercial pages?) +- Topical breadth (how many related topics do they cover?) + +### 3. Backlink profile +Where does their authority come from? + +- Total referring domains +- Domain rating (or equivalent authority metric) +- Top 50 referring pages by traffic value +- Backlink types (editorial, directory, partner, paid, spam) +- Link velocity (gaining or losing referring domains over time) +- Pages on their site attracting the most links (these are their "linkable assets") + +### 4. Technical posture +How clean is their technical foundation? + +- Core Web Vitals (LCP, INP, CLS) +- Mobile usability +- Schema implementation (which types, on which page types) +- Site architecture and internal linking density +- Crawl efficiency (are they wasting crawl budget?) +- HTTPS, security headers +- llms.txt and AI search readiness + +### 5. Brand and entity strength +How well-known are they outside organic search? + +- Branded search volume (how many people search their name?) +- Entity recognition in knowledge graph (do they have a Wikipedia page, knowledge panel, structured data feeding entity status?) +- Mention frequency in their topic area (PR coverage, podcast appearances, citations) +- Social signals (followers, engagement, share rates) +- Reviews and reputation + +--- + +## Workflow + +1. **Confirm the competitors.** Either named, or derive from SERP overlap on top 10 priority keywords. +2. **Pick the angles.** Run all 5 for a full audit, or 2 to 3 for a focused dive. +3. **Pull the data.** Keyword tool exports, backlink tool exports, manual SERP inspection, technical crawl. +4. **Score each angle.** Where does the user lead? Where do they trail? +5. **Identify gaps.** Specific content gaps, specific backlink gaps, specific technical gaps. +6. **Prioritize.** Which gaps are highest leverage to close? (Big traffic potential, achievable effort, strategic fit.) +7. **Write the report.** Use the template in [`references/competitive-audit-template.md`](references/competitive-audit-template.md). + +--- + +## Failure patterns + +- **Picking the wrong competitors.** A site that outranks you on one keyword but operates a different business is not a competitor. Pick by SERP overlap and audience overlap, not by who you think you compete with. +- **Treating "more content" as the takeaway.** They are not winning because they have 500 articles. They are winning because of specific content + links + UX. Find the actual lever. +- **Copying their pages verbatim.** Diminishing returns. Beat them by being more useful, not by paraphrasing them. +- **Ignoring brand strength.** A weaker site with a stronger brand wins on branded queries you cannot touch with content alone. +- **Static analysis.** Re-run the analysis at least annually. Competitor strategies shift. + +--- + +## Output format + +Default output is a markdown report at `competitive-analysis.md` plus accompanying spreadsheets for the keyword and backlink data. + +Structure: +1. Executive summary (3 to 5 critical findings) +2. Competitor profiles (one per competitor, brief) +3. SERP overlap analysis +4. Content gap analysis +5. Backlink gap analysis +6. Technical comparison +7. Brand and entity comparison +8. Prioritized gap-closing roadmap + +--- + +## Reference files + +- [`references/competitive-audit-template.md`](references/competitive-audit-template.md) - Fillable competitive audit template. +- [`references/content-gap-method.md`](references/content-gap-method.md) - Detailed methodology for finding content gaps with example. diff --git a/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md b/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md new file mode 100644 index 0000000..556d013 --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md @@ -0,0 +1,160 @@ +# Competitive SEO Analysis: [Your Site] vs Competitors + +**Date:** [YYYY-MM-DD] +**Site under audit:** [URL] +**Competitors analyzed:** [List] +**Analyst:** [Name] + +--- + +## Executive summary + +[3 to 5 critical findings. Lead with the most important. What is the single biggest gap to close, and what is the single biggest strength to defend?] + +**Top 3 priorities:** +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Competitor profiles + +### Competitor 1: [Name] +- **Domain rating:** [X] +- **Estimated organic traffic:** [X / month] +- **Total referring domains:** [X] +- **Top 3 ranking categories:** [What they win on] +- **Why they matter:** [1 to 2 sentences] +- **Their key advantage over us:** [1 sentence] + +### Competitor 2: [Name] +[Same structure] + +### Competitor 3: [Name] +[Same structure] + +--- + +## SERP overlap analysis + +**Keywords where we both rank top 10:** [N] +**Keywords where they rank, we don't:** [N] +**Keywords where we rank, they don't:** [N] +**Keywords where they hold a SERP feature we don't:** [N] + +### Head-to-head wins +[Top 10 keywords where we currently rank above them] + +| Keyword | Our rank | Their rank | Volume | +|---|---|---|---| +| | | | | + +### Head-to-head losses +[Top 10 keywords where they rank above us] + +| Keyword | Our rank | Their rank | Volume | Likely reason they win | +|---|---|---|---|---| +| | | | | | + +### Their territory (we don't rank) +[Top 20 keywords they rank for that we don't, ranked by traffic potential] + +| Keyword | Their rank | Volume | Difficulty | Strategic fit for us | +|---|---|---|---|---| +| | | | | | + +--- + +## Content gap analysis + +[Topics or page types they cover that we don't, organized by theme.] + +### Theme 1: [e.g., "How-to guides for beginners"] +- **Their coverage:** [X pages, including these top performers...] +- **Our coverage:** [None / weak / partial] +- **Estimated traffic value if closed:** [X visits/month] +- **Recommended action:** [Produce / partial coverage / skip] + +### Theme 2: [e.g., "Comparison content"] +[Same structure] + +--- + +## Backlink gap analysis + +**Their referring domains we don't have:** [N] +**Their unique referring domains (in our category):** [N] + +### Top 10 backlink opportunities +[Domains linking to multiple competitors but not us. These are the highest-probability outreach targets.] + +| Domain | Domain rating | Links to (competitors) | Why they link to them | +|---|---|---|---| +| | | | | + +### Their linkable assets +[Pages on competitor sites that attract the most backlinks. These are the asset types we could replicate.] + +| URL | Referring domains | Asset type | +|---|---|---| +| | | | + +--- + +## Technical comparison + +| Dimension | Us | Comp 1 | Comp 2 | Comp 3 | +|---|---|---|---|---| +| LCP (mobile) | | | | | +| INP (mobile) | | | | | +| CLS (mobile) | | | | | +| Mobile-friendly | | | | | +| HTTPS / HSTS | | | | | +| Schema types | | | | | +| Sitemap quality | | | | | +| llms.txt present | | | | | +| Internal links per page (avg) | | | | | + +**Key takeaways:** [Where are we ahead, where are we behind?] + +--- + +## Brand and entity comparison + +| Dimension | Us | Comp 1 | Comp 2 | Comp 3 | +|---|---|---|---|---| +| Branded search volume | | | | | +| Wikipedia entity | | | | | +| Knowledge panel | | | | | +| Editorial mentions / month | | | | | +| Social following | | | | | +| Reviews aggregate | | | | | + +--- + +## Prioritized gap-closing roadmap + +[Sequenced list of actions, with effort and expected impact.] + +### Quarter 1 +1. [Action] - [effort] - [expected impact] +2. [Action] - [effort] - [expected impact] + +### Quarter 2 +1. [Action] + +### Quarter 3+ +[Strategic plays that take longer to execute.] + +--- + +## What we should defend + +Areas where we currently lead and need to maintain: + +- [Strength] +- [Strength] +- [Strength] + +A defensive strategy is as important as a gap-closing one. diff --git a/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md b/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md new file mode 100644 index 0000000..f7f0083 --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md @@ -0,0 +1,225 @@ +# Content Gap Method + +A detailed methodology for finding content gaps between your site and competitors. The output is a prioritized list of topics or queries the competition ranks for and you do not, ranked by opportunity. + +This is the methodology. For the orchestrated version that runs against the Ahrefs MCP, use `seo-content-gap-audit`. + +--- + +## What a content gap is (and is not) + +A content gap is a query or topic where: + +- One or more competitors rank in the top 10 +- You do not rank in the top 100 (or rank weakly) +- The query is plausibly something your audience cares about +- You could credibly produce content that addresses it + +A content gap is not: + +- Every keyword a competitor ranks for. Many of those will not match your audience. +- Branded queries for the competitor. You will never rank for "[CompetitorName] login" and should not try. +- Queries with unwinnable SERPs (dominated by Reddit, video, or marketplace listings) unless you have an unusual asset. + +--- + +## Step 1: define the competitor set + +Three categories of competitors. Include all three. + +### Direct competitors + +Same product, same audience. Found in your "industry," your sales process, your churn data. + +### Search competitors + +Whoever ranks for the queries you care about. Often surprising. Often includes industry publications, aggregators, and adjacent SaaS tools you do not consider competition commercially. + +To find search competitors: + +1. Pull your top 20 priority queries. +2. Note the top 10 ranking domains for each. +3. Aggregate. Domains that appear 5+ times are search competitors, even if they are not direct. + +### Aspirational competitors + +Brands that own the topic-area you want to own. Often larger or older. Useful for surfacing topics, less useful for direct comparison. + +Build a final set of 5-10 competitors. More than that gets noisy. + +--- + +## Step 2: pull keyword data + +For each competitor, pull the queries they rank for in the top 10 (or top 20 for completeness). + +Filter out: + +- Branded queries containing the competitor name +- Queries with monthly volume below your relevance threshold (commonly 50-100, lower for niche industries) +- Queries with no clear commercial or informational intent (typos, location-specific irrelevant queries, etc.) +- Queries with parent topic that does not apply to your business + +Tools: Ahrefs Site Explorer (Organic keywords), Semrush Organic Research, or DataForSEO equivalents. + +--- + +## Step 3: build the gap matrix + +Cross-reference all competitors against your site. + +| Query | Competitor 1 position | Competitor 2 position | Competitor 3 position | Your position | Monthly volume | Difficulty | +|---|---|---|---|---|---|---| +| query a | 3 | 7 | - | 45 | 1,200 | 32 | +| query b | 5 | 4 | 8 | not ranking | 800 | 28 | +| query c | 1 | - | 5 | 12 | 500 | 41 | + +Three categories emerge: + +- **Pure gaps:** competitors rank, you do not. Highest opportunity. Filter for queries where 2+ competitors rank. +- **Weak coverage:** you rank but poorly (positions 11-50). Often the fastest wins. +- **Saturated topics:** you and 1+ competitors all rank well. Defensive territory; opportunity to leapfrog. + +Focus the next steps on Pure gaps and Weak coverage. + +--- + +## Step 4: cluster by topic + +Raw query lists are unmanageable. Cluster by topic so you can plan content, not chase individual keywords. + +### Method + +Group queries that share intent and can be answered by the same piece of content. + +- "best crm for startups," "top crm small business," "crm software comparison" - one cluster, one comparison piece. +- "how to choose a crm," "crm buying guide" - same cluster. +- "what is a crm," "crm definition" - separate cluster (top-of-funnel, glossary or pillar lead-in). + +A cluster is one piece of content (or a closely-related set: pillar + spokes). + +### Output + +| Cluster | Sample queries | Total monthly volume | Avg difficulty | Recommended format | Lead competitor | +|---|---|---|---|---|---| +| | | | | | | +| | | | | | | + +--- + +## Step 5: assess each cluster + +For each cluster, answer: + +### Audience fit + +Does this cluster match your audience? If you sell to enterprise but the cluster is dominated by SMB intent ("free crm for solopreneurs"), score it low. + +### SERP analysis + +Open the SERP for the highest-volume query in the cluster. Note: + +- **Result types:** organic blue links, video, AI overview, featured snippet, local pack, shopping. Some SERPs leave little real estate for new entrants. +- **Result formats:** what kind of pages rank? Blog posts, comparison pages, product pages, free tools, video? +- **Domain mix:** dominated by big publishers (HubSpot, Forbes), niche players, Reddit, or peer companies? +- **SERP volatility:** has the top 10 been stable, or churning? + +### Effort estimate + +How long would it take to produce content competitive with what is ranking? Be honest. Some clusters need a 4,000-word definitive guide with original research. Others need a 1,200-word how-to. + +### Scoring + +Combine into a simple opportunity score per cluster. Example: + +``` +Opportunity = (Volume × Audience Fit × SERP Winnability) / Effort +``` + +Where: + +- **Volume:** total monthly volume across cluster +- **Audience Fit:** 1 (poor), 2 (decent), 3 (perfect match) +- **SERP Winnability:** 1 (saturated, big domains), 2 (mixed), 3 (gettable) +- **Effort:** hours of writing, research, asset creation + +This is not a precise formula. Use it to rank clusters, then sanity-check the top of the list against editorial judgment. + +--- + +## Step 6: produce the gap report + +A typical output deliverable: + +### Section 1: executive summary + +- Top 10 clusters ranked by opportunity score +- Estimated total monthly traffic potential if you captured the average competitor position +- Estimated effort (in hours or pieces of content) to address the top 10 + +### Section 2: cluster details + +For each top cluster: + +- Cluster name and theme +- Sample queries with volume and difficulty +- SERP analysis snapshot +- Lead competitor's content URL with a one-line note on what makes it strong +- Recommended content format and length +- Recommended hook or angle +- Estimated effort +- Why we should rank: the unique asset, perspective, or data we can bring + +### Section 3: clusters to skip + +Clusters that surfaced but should not be pursued, with the reason. (Audience mismatch, SERP unwinnable, etc.) Documenting skips prevents re-litigation. + +### Section 4: next steps + +- Hand-off to `content-strategy` for editorial planning +- Production sequencing (which cluster ships first) +- Measurement: how will you track whether the gap is closing + +--- + +## Worked example + +**Site:** B2B project management tool, 50-person company, target audience is engineering leads at series-B SaaS startups. + +**Competitors (5):** +1. Linear (direct, peer) +2. Jira (direct, incumbent) +3. Notion (adjacent, encroaching) +4. Asana (direct, larger) +5. Height (direct, peer) + +### Gap matrix excerpt + +| Cluster | Sample queries | Volume | Difficulty | Lead competitor | Audience fit | SERP winnable | Effort | Opportunity | +|---|---|---|---|---|---|---|---|---| +| "linear vs jira" | 5,400 | 38 | linear.app | High | Mixed | Med | High | +| "engineering project management" | 2,100 | 42 | linear.app | High | Big domains | Med | High | +| "agile sprint planning" | 14,000 | 55 | atlassian.com | Med | Saturated by Atlassian | High | Low | +| "github issue templates" | 3,200 | 28 | github.com | High | Owned by github.com | Med | Skip | + +### Recommendations + +- **Pursue:** "linear vs jira" cluster (5 related comparison queries, 7,200 combined monthly volume, mid-effort, audience-perfect). Format: comparison page anchored by an internal POV piece. +- **Pursue:** "engineering project management" cluster (broader topic, 4 related queries, requires a pillar piece + 3 spokes). Format: pillar guide + spokes. +- **Skip:** "agile sprint planning." Atlassian owns this with deep, mature content; effort to compete is too high vs opportunity. +- **Skip:** "github issue templates." github.com itself ranks #1; even strong content will not displace. + +### Next steps + +- Hand the two pursued clusters to content-strategy for editorial sequencing. +- Track positions weekly for the cluster's primary queries. +- Re-run the gap analysis quarterly to spot new gaps as competitors publish. + +--- + +## When to re-run + +- **Quarterly** as a routine. +- **After a major competitor launch** (new product page, big content push, redesign). +- **After a search algorithm update** (especially core updates that reshuffle SERPs). +- **When entering a new audience segment** (segment-specific competitors emerge). diff --git a/dist/pi/.agents/skills/seo-content-audit/SKILL.md b/dist/pi/.agents/skills/seo-content-audit/SKILL.md new file mode 100644 index 0000000..36ecee8 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/SKILL.md @@ -0,0 +1,193 @@ +--- +name: seo-content-audit +description: "Audit existing content across a site to decide what to keep, update, merge, redirect, or delete. Use this skill whenever the user wants to audit existing content, fix content decay, resolve keyword cannibalization, prune underperforming pages, prioritize content updates, or apply a keep/update/merge/redirect/delete framework to a content library. Triggers on content audit, content decay, content refresh, cannibalization, keyword cannibalization, prune content, delete pages, redirect old pages, content inventory, what to keep, what to update, content scorecard, evergreen refresh. Also triggers when traffic is dropping site-wide and the cause might be content quality, even if 'audit' is not said explicitly." +category: seo-foundation +catalog_summary: "Keep/update/merge/redirect/delete decisions across a site" +display_order: 6 +--- + +# Content Audit + +Inventory existing content, score it, and decide for each piece: keep, update, merge, redirect, or delete. Stack-agnostic. Works on blogs, marketing sites, knowledge bases, and product content. + +--- + +## When to use + +- Inheriting a content library you did not create +- Diagnosing site-wide traffic decline +- Resolving cannibalization (two pages competing for the same query) +- Pre-migration cleanup +- Annual or semi-annual content health check +- Pruning before a redesign or replatform + +## When NOT to use + +- Optimizing a single page (use `seo-onpage`) +- Planning new content (use `seo-keyword`) +- Comparing your content to competitors (use `seo-competitor`) +- Site-level technical issues (use `seo-technical`) + +--- + +## Required inputs + +- The site URL and access to crawl it (or a complete URL list) +- Search console access (or a 12-month export) +- Analytics access (sessions, conversions, engagement) +- A backlink tool (to identify pages with referring domains worth preserving) + +--- + +## The framework: 5 actions + +For every content piece, the audit produces one of five decisions. + +### 1. Keep +The page performs well, has clear intent, and needs no changes. + +**Signals:** +- Top 10 ranking for its primary query +- Consistent traffic with no decay +- Healthy engagement (above-site-average time on page or interaction rate) +- Up-to-date information + +### 2. Update +The page has potential but is underperforming due to fixable issues. + +**Signals:** +- Page 2 ranking for high-value queries (rank 11 to 30) +- Traffic decay over the last 6 to 12 months +- Information gone stale +- Title or meta need rewriting for CTR +- Thin content that could expand to match competitor depth +- Missing schema or other technical hygiene + +### 3. Merge +Two or more pages target overlapping queries and should consolidate. + +**Signals:** +- Cannibalization (multiple pages ranking for the same query, none ranking well) +- Significant content overlap between pages +- Combined, they would outperform either alone +- Both have backlinks worth preserving + +### 4. Redirect +The page has no future but has assets (links, equity) worth preserving. + +**Signals:** +- No traffic, no rankings +- Holds backlinks (especially editorial ones) +- A relevant target page exists that would benefit from the equity +- Topic is still relevant but this specific page is not + +### 5. Delete (and let return 404 or 410) +The page has no future and no assets worth preserving. + +**Signals:** +- No traffic, no rankings, no backlinks +- Content is outdated and not worth updating +- Topic is no longer relevant +- Even thin or spam content from a previous era + +Note: In most cases, return 410 (gone) for intentionally deleted content. 410 is processed faster than 404 and signals the deletion was deliberate. + +--- + +## Scoring inputs + +Pull these for every URL before deciding: + +| Metric | Source | Threshold for "low" | +|---|---|---| +| Sessions (last 90 days) | Analytics | <10/month | +| Organic traffic (last 90 days) | Search console or analytics | <5/month | +| Average position for top query | Search console | >30 | +| Impressions (last 90 days) | Search console | <100/month | +| Click-through rate | Search console | <1% (when impressions exist) | +| Referring domains | Backlink tool | 0 | +| Engagement (avg time on page) | Analytics | <30 seconds | +| Last meaningful update | Manual / git | >24 months | +| Word count | Crawler | <300 (for articles) | +| Internal links in | Crawler | 0 | + +A page can survive low scores on a few metrics. A page that fails on most is a delete or redirect candidate. + +--- + +## Decision matrix + +A simplified decision tree: + +``` +Has traffic? ─── Yes ──── Recent decay? ─── Yes ── UPDATE + │ │ + │ └── No ─── KEEP + │ + └── No ──── Has backlinks? ─── Yes ── Has relevant target? ─── Yes ── REDIRECT + │ │ + │ └── No ─── UPDATE (rebuild) + │ + └── No ──── Cannibalizing another page? ─── Yes ── MERGE + │ + └── No ─── DELETE (410) +``` + +For overlapping pages, "merge" usually wins over "delete" because it preserves both link equity and any topical authority. + +--- + +## Workflow + +1. **Inventory.** Pull a complete URL list from the crawl, sitemap, and search console (some indexed pages may not be in the sitemap). +2. **Pull the metrics.** Sessions, organic, search console rank/CTR, backlinks, last-modified date, word count. +3. **Score each URL.** Use the framework. Mark a decision: Keep / Update / Merge / Redirect / Delete. +4. **Identify cannibalization clusters.** Group URLs targeting the same query. Decide which becomes the canonical, what to merge, what to redirect. +5. **Sequence the work.** Do redirects and deletes in batches. Plan updates by priority (highest-traffic-recovery potential first). +6. **Implement.** With change tracking. Re-crawl after each batch to confirm no broken redirect chains. +7. **Measure.** Track aggregate organic traffic 30, 60, 90 days post-audit. + +--- + +## Failure patterns + +- **Deleting pages with backlinks.** Always check referring domains before deleting. A redirect preserves equity at near-zero cost. +- **Updating pages that should be merged.** Two thin pages updated to medium pages still cannibalize. Merge first. +- **Merging without preserving the better URL.** Pick the merge target by which URL has stronger signals (older URL, more backlinks, better URL slug, currently better ranking), not which one has more content. +- **Mass-deleting low-traffic pages.** Some have value: fresh pages still ramping, niche pages serving a specific audience, evergreen pages with seasonal traffic. Do not bulk-delete by sessions alone. +- **Over-aggressive pruning of "old" content.** Date alone is not a delete signal. Topic relevance and intent quality are. +- **No post-audit measurement.** Without measurement, you cannot tell if the audit worked. + +--- + +## Output format + +Default output: a spreadsheet with one row per URL, plus a summary markdown report. + +**Spreadsheet columns:** +- URL +- Page type (article, product, category, etc.) +- Sessions (90d), organic clicks (90d), impressions (90d), avg position +- Referring domains +- Word count +- Last modified +- Decision (keep / update / merge / redirect / delete) +- Merge target / redirect target (if applicable) +- Priority (1-5) +- Notes + +**Summary report:** +1. Inventory totals (URLs by decision) +2. Cannibalization clusters identified +3. Top 20 update priorities +4. Redirect map (CSV) +5. Delete list +6. Implementation roadmap (sequenced by priority) +7. Measurement plan + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Spreadsheet column definitions and report template. +- [`references/cannibalization-resolution.md`](references/cannibalization-resolution.md) - Detailed methodology for resolving cannibalization clusters. diff --git a/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md b/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md new file mode 100644 index 0000000..246de40 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md @@ -0,0 +1,223 @@ +# Content Audit Template + +Spreadsheet column definitions and report template for a site-wide content audit. The output is a per-URL decision (keep / update / merge / redirect / delete) plus a summary report for stakeholders. + +--- + +## What this audit produces + +- A spreadsheet (one row per URL) with all signals and the final decision +- A report that summarizes the decisions, the rationale, and the next-step backlog +- A roll-up of expected SEO impact and effort + +--- + +## Required spreadsheet columns + +Every row is one URL. Every column below is required. + +| Column | Type | Source | Description | +|---|---|---|---| +| **URL** | Text | Crawl | Full URL | +| **Title tag** | Text | Crawl | Current `<title>` | +| **H1** | Text | Crawl | Current H1 | +| **Word count** | Number | Crawl | Body text words | +| **Publish date** | Date | CMS / inferred | Original publish date | +| **Last updated** | Date | CMS | Most recent meaningful update | +| **Page type** | Pick list | Manual / patterned URL | Article / product / category / landing / utility / legal / etc. | +| **Topic cluster** | Pick list | Manual | Which topic cluster (from content strategy) | +| **Primary query target** | Text | Manual / GSC top query | The query the page should rank for | +| **Sessions (last 90d)** | Number | Analytics | Organic sessions | +| **Conversions (last 90d)** | Number | Analytics | Goal completions attributable to this URL | +| **Top ranking position** | Number | GSC / rank tracker | Best position achieved in last 90d | +| **Average position** | Number | GSC | Average position in last 90d | +| **Impressions (last 90d)** | Number | GSC | | +| **CTR (last 90d)** | Number | GSC | | +| **Backlinks (referring domains)** | Number | Backlink tool | | +| **Internal inlinks** | Number | Crawl | Number of internal pages linking to this URL | +| **Last meaningful traffic** | Date | Analytics | Most recent month with traffic above threshold | +| **Decision** | Pick list | Manual | Keep / Update / Merge / Redirect / Delete | +| **Reasoning** | Text | Manual | One sentence per decision | +| **Action notes** | Text | Manual | What needs to happen if Update or Merge | +| **Owner** | Person | Manual | Who executes | +| **Target completion** | Date | Manual | When the action ships | +| **Status** | Pick list | Manual | Backlog / In progress / Shipped / Verified | + +--- + +## Optional but recommended columns + +| Column | Description | +|---|---| +| **Cannibalization risk** | Other URLs ranking for the same primary query. See `cannibalization-resolution.md`. | +| **Schema present** | Yes / No / Type | +| **Has index tag** | Indexable / noindex | +| **Status code** | 200 / 301 / 404 etc. (catches accidental noindex or broken pages) | +| **Time on page** | From analytics; rough engagement signal | +| **Bounce rate or scroll depth** | From analytics | +| **Current canonical** | Self / other URL | +| **Image count** | Helps identify thin pages | +| **Outbound external links** | | +| **Topic authority signal** | Original research, expert author, structured comparison, etc. - subjective but useful | + +--- + +## The 5 decision types + +### Keep + +Page is performing or recently published. No action needed. Track for future audits. + +**Default for:** +- Top 20% of pages by sessions +- Pages within 3 months of publish (too early to judge) +- Cornerstone pages with strong rankings or backlinks + +### Update + +Page is on the right topic but has decayed (rankings down, content stale, broken links, missing schema). + +**Action:** add to the editorial backlog with a specific update brief. Common updates: refresh examples and dates, expand thin sections, add new H2s for related queries surfacing in GSC, improve title and meta, add schema, update screenshots and links. + +### Merge + +Two or more pages cover the same intent and split signals. Combine into one stronger page. + +**Action:** pick the canonical winner (usually the one with more backlinks and more search visibility), redirect the loser(s) to the winner, fold the loser's unique content into the winner. + +### Redirect + +Page no longer relevant but has equity (backlinks, traffic, internal links) worth preserving. + +**Action:** 301 redirect to the closest topical match. If no match exists, redirect to the parent category or topic hub. Avoid blanket redirects to homepage (Google often treats them as soft 404s). + +### Delete + +Page has no traffic, no rankings, no backlinks, no internal links pointing to it, and no strategic role. + +**Action:** return 410 Gone (preferred) or 404 if 410 is not supported. Update sitemap. Remove internal links pointing to the deleted page. + +### Decision tree + +``` +Page is performing well? +├── Yes → Keep +└── No → Page is on a relevant topic? + ├── Yes → Page is the only one on this topic? + │ ├── Yes → Update (refresh and expand) + │ └── No → Merge (consolidate into stronger version) + └── No → Page has equity (backlinks, internal links)? + ├── Yes → Redirect to closest topical match + └── No → Delete (410 Gone) +``` + +--- + +## Triage thresholds + +The audit looks at hundreds or thousands of URLs. Triage thresholds let you focus. + +### Performing (default Keep) + +- 100+ organic sessions in last 90 days, OR +- 1+ conversions in last 90 days, OR +- 10+ referring domains, OR +- Average position 1-10 for primary query + +### Decaying (default Update or Merge) + +- 5-100 sessions in last 90 days +- Average position 11-50 +- Last meaningful traffic 6-24 months ago + +### Dormant (default Redirect or Delete) + +- 0-5 sessions in last 90 days +- Average position 51+ +- Last meaningful traffic 24+ months ago + +These are starting points. Adjust to your site's volume. + +--- + +## Cannibalization check + +For each primary query target, group URLs targeting the same query. If 2+ URLs target the same query: + +- **One ranking, one not:** the non-ranking one is a Merge or Redirect candidate. +- **Both ranking but neither in top 5:** classic split-signal case. Merge into one definitive page. +- **One ranking strong, one ranking weak:** the weak one is a Merge candidate. + +For deeper diagnosis and resolution patterns, see `cannibalization-resolution.md`. + +--- + +## Report template + +The audit produces a stakeholder-readable report. + +### Section 1: executive summary + +- Total URLs audited +- Decisions: Keep / Update / Merge / Redirect / Delete (with counts and percentages) +- Estimated SEO impact: traffic preserved, traffic potential unlocked, traffic risk if action delayed +- Estimated effort: hours of writing, engineering URL work, design work + +### Section 2: decisions by topic cluster + +Per cluster: how many pages, decisions, top action items. + +### Section 3: top opportunities + +The 10-20 highest-leverage actions (typically Updates and Merges that protect strong rankings or unlock obvious wins). + +### Section 4: risks if no action + +What happens if the team does not act. Common: continued ranking decay, cannibalization that suppresses both URLs, technical risk (crawl budget), content sprawl that confuses readers. + +### Section 5: backlog and sequencing + +Prioritized backlog with owners and target dates. Sequence so that: + +- Redirects ship first (they are mechanical and preserve equity) +- Merges ship second (combine before refreshing) +- Updates ship third (work on what remains) +- Deletes happen last (after all redirects and merges that depend on those URLs are in) + +--- + +## Pre-audit checklist + +Before running the audit: + +- [ ] Analytics access granted (GA4 or equivalent) +- [ ] Search Console access granted +- [ ] Crawl tool ready (Screaming Frog, Sitebulb, or hosted equivalent) +- [ ] Backlink data source identified (Ahrefs, Semrush, GSC limited data) +- [ ] Topic clusters defined (from content strategy) +- [ ] Threshold values agreed (sessions, position, age) +- [ ] Decision authority confirmed (who can approve Delete and Merge actions) +- [ ] Implementation owner confirmed (who runs the post-decision work) + +--- + +## Post-audit verification + +After the actions ship: + +- [ ] Verify all redirects resolve correctly (no chains, no loops) +- [ ] Verify all 410/404 pages return correct status +- [ ] Update sitemap to remove deleted URLs and reflect canonical changes +- [ ] Resubmit sitemap in Search Console +- [ ] Monitor the merged URLs for ranking confirmation (typically 2-8 weeks) +- [ ] Re-run a slim audit at 90 days to confirm decay was halted + +--- + +## Sign-off + +Audit produced by: [Name, date] +Decisions approved by: [Name, role, date] +Implementation owner: [Name, date] + +Next audit scheduled: [Date - typically annual or after major content investment] diff --git a/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md b/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md new file mode 100644 index 0000000..e4ad239 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md @@ -0,0 +1,148 @@ +# Cannibalization Resolution + +When two or more pages on the same site compete for the same query, all of them lose. Search engines either pick the wrong one to rank, split the ranking signal across both, or rotate between them unpredictably. + +This reference walks through how to identify and resolve cannibalization. + +--- + +## How to identify cannibalization + +You have cannibalization when: + +- Two or more URLs from your site appear in the top 50 for the same query +- A query has multiple URLs ranking and rotating across the top 30 over time (search console shows this as inconsistent) +- A new page appears for a query and the previously-ranking page drops sharply +- Two URLs on the same site share the same primary intent and substantial content overlap + +**How to find it:** + +1. Export search console queries with multiple ranking URLs +2. Look for queries where the same site appears more than once in the data +3. Check rank stability: if a query bounces between URLs week to week, that is the signal +4. Internal: search your own site (`site:yourdomain.com "exact query"`) and see how many results appear + +--- + +## Resolution decision tree + +For each cannibalization cluster, you have four options. + +``` +Same intent? ─── Yes ──── Substantial content overlap? ─── Yes ── MERGE + │ + └── No ── Different angles, same intent? ─── DIFFERENTIATE + │ + └── No ──── Confirm intent classification, may not be cannibalization +``` + +### Option 1: Merge + +Combine the pages into one canonical page. Use this when: +- Both pages serve the same intent +- Content overlaps substantially +- Combined, the page would be stronger than either alone + +**Steps:** +1. Pick the merge target. Best signals win: highest-ranking URL, most backlinks, older URL, cleaner URL slug. +2. Pull the unique content from the loser pages, integrate into the winner. +3. 301 redirect the loser URLs to the winner. +4. Update internal links pointing at loser URLs to point at the winner. +5. Submit the winner URL for re-crawling. +6. Monitor rankings for 30 to 60 days. + +### Option 2: Differentiate + +Keep both pages, but reposition each to target distinct sub-intents. Use this when: +- The pages serve genuinely different queries that just look similar +- Both have meaningful traffic and rankings that are worth preserving +- The category supports nuanced sub-topics + +**Steps:** +1. Identify the distinct intent each page should target (e.g., "best running shoes" vs "best running shoes for beginners") +2. Rewrite titles, meta, H1, and intros to reinforce the distinct intent +3. Update internal links to use distinct anchor text +4. Cross-link the two pages so each acknowledges the other +5. Update any sitemap or hub page that lists them + +### Option 3: Redirect + +Pick a winner, kill the rest. Use this when: +- One page is clearly stronger +- The losers have no unique content worth preserving +- There is no benefit to maintaining multiple pages + +**Steps:** +1. Pick the winner using the same criteria as merge. +2. 301 redirect the losers to the winner. +3. Pull any unique content from the losers and integrate into the winner if useful. +4. Update internal links. + +### Option 4: Noindex the secondary page + +Keep both pages, but tell search engines to only consider one for ranking. Use this when: +- One page has a strong UX or business reason to exist (e.g., a product variant page) +- It does not need to rank, but does need to exist +- Merging would damage UX + +**Steps:** +1. Add `<meta name="robots" content="noindex, follow">` to the secondary page +2. Confirm the canonical of the secondary page points at itself (not the primary), since canonical and noindex serve different purposes +3. Verify in search console after a week that the noindex took effect +4. Maintain the user-facing functionality of the page + +--- + +## Picking the merge winner + +When you have to choose which URL becomes canonical, use this prioritized scoring: + +1. **Current ranking position.** If one URL is on page 1 and the other on page 3, keep page 1. +2. **Backlinks.** Highest count of referring domains usually wins. +3. **URL quality.** Cleaner slug, fewer parameters, shorter, descriptive. +4. **Internal links in.** More inbound internal links signals existing site structure. +5. **Page age.** Older URLs often have accumulated trust signals. +6. **Content quality.** If all else is tied, pick the one with better content (or the one easier to expand). + +Do not pick by recency of publication or "I just wrote it." Search engines reward signals that have accumulated over time. + +--- + +## Common cannibalization patterns + +### Pattern 1: Old article + new article on same topic + +Common in evergreen sites. Resolution: merge, with the older URL as canonical (preserves backlinks and age signals). + +### Pattern 2: Category page + product page targeting same query + +Resolution: differentiate. Category page targets the broad query ("running shoes"). Product pages target product-specific queries ("[brand] [model] running shoes"). + +### Pattern 3: Blog post + landing page + +Resolution: differentiate aggressively or merge. Blog post targets informational intent. Landing page targets commercial intent. If they keep cannibalizing, the keyword is fundamentally one-intent and one of them needs to retire. + +### Pattern 4: Multiple "best X" listicles for slight variants + +E.g., "best running shoes," "best running shoes for women," "best running shoes for marathons." Resolution: maintain a clear hub-and-spoke structure. The hub page targets the broad query. Spoke pages target specific variants. Cross-link. + +### Pattern 5: Geographic variants + +E.g., "best plumber" vs "best plumber in Denver." Resolution: differentiate by geo modifier in title, H1, content. Use schema (LocalBusiness) for the geo-specific pages. + +--- + +## Verification after resolution + +For 60 days post-resolution, monitor: + +- Rank for the canonical URL on the target query (should stabilize and improve) +- Rank for the merged/redirected URLs (should drop out, which is expected) +- Aggregate impressions and clicks for the cluster (should rise as ranking signals consolidate) +- Internal links pointing at deprecated URLs (should be zero after cleanup) + +If the canonical URL does not improve in rank within 60 days, recheck: + +- Did the redirects fire correctly? (Test 5 random old URLs) +- Are there still other pages on the site competing for the same query? +- Is the canonical URL strong enough on its own to rank? (Compare to top-ranking competitors) diff --git a/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md b/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md new file mode 100644 index 0000000..f7fcf21 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md @@ -0,0 +1,159 @@ +--- +name: seo-content-gap-audit +description: "Audit content gaps and decay using Ahrefs MCP data: missing topics, thin coverage, outdated content, and decaying pages. Use this skill when planning a content roadmap, refreshing a stale catalog, building topical authority, or identifying which existing pages need update versus replacement. Triggers on content gap, content audit, content refresh, content roadmap, decaying content, content decay, topical authority, what topics should we cover, where is competitor content stronger. Also triggers when organic traffic is flat despite consistent publishing." +category: seo-audit-suite +catalog_summary: "Missing topics, thin coverage, outdated content, decay diagnosis" +display_order: 4 +--- + +# SEO Content Gap Audit + +Find content gaps and decay using Ahrefs MCP data. Stack-agnostic. Produces a roadmap of create, update, merge, and prune actions across the existing content catalog and identified topic gaps. + +--- + +## When to use + +- Planning the next quarter or half of content investment +- Refreshing a stale or underperforming content catalog +- Building topical authority in a target space +- Identifying decaying pages before they tank traffic +- Audit prep before a major site redesign or migration +- Diagnosing why content investment is not driving organic growth + +## When NOT to use + +- Pure keyword research (use `seo-keyword`) +- Competitor keyword gap (use `seo-keyword-gap-audit`) +- Single-page optimization (use `seo-onpage`) +- Pure prune-and-redirect decisions (use `seo-content-audit`) +- New site planning with no existing content (use `content-strategy`) + +--- + +## Required inputs + +- Target property and content scope +- Competitor set (3-5 properties with comparable content depth) +- Target topics or pillars (if defined) +- Existing content inventory with URLs, primary topics, publish dates +- Performance data (organic clicks per page, ranked keywords per page) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: 4 categories of content opportunity + +Every content opportunity falls into one of four categories. Different categories need different actions. + +Content gap analysis is sharper with multiple data sources. Ahrefs surfaces keyword and topic gaps (the primary backend below). Similarweb surfaces traffic-driving page-level gaps (which of a competitor's pages earn meaningful traffic, not just rankings). Semrush surfaces SERP-feature gaps (where competitors win answer boxes, knowledge panels, People Also Ask placements). The three platforms often disagree on individual data points; that disagreement is itself a useful signal. + +### Category 1: Missing topics + +Topics with traffic potential where the property has no relevant page at all. Competitors often rank in the top 10. The fix: create new content. + +Pulled from: + +- Ahrefs Content Explorer (top performing content in target topics) +- Competitor top pages (Ahrefs Site Explorer) +- Keyword gap audit output (clustered into topics) + +### Category 2: Thin coverage + +Topics where the property has a page but it is too shallow, narrow, or single-keyword to compete with topical hubs. Competitor pages cover the topic across multiple subtopics. The fix: deepen the existing page or expand into a topic cluster. + +Pulled from: + +- Pages ranking on page 2-3 for target keywords +- Pages with low organic click share relative to ranked keyword volume +- Pages where competitors have longer or broader equivalents + +### Category 3: Outdated content + +Pages that ranked well historically but have lost ground due to staleness. Information is dated, examples are old, the SERP intent has shifted. The fix: refresh with current information and re-promote. + +Pulled from: + +- Pages with declining organic clicks over the last 6-12 months +- Pages with publish dates over 18 months old +- Pages with ranked keywords slipping in position + +### Category 4: Decaying content + +Pages that have lost traffic for reasons not obviously about staleness: SERP feature changes, competitor publishing, intent shifts, internal linking dilution. The fix: diagnose why, then refresh, merge, or redirect. + +Pulled from: + +- Pages with sharp recent traffic drops +- Pages where SERP composition has shifted (more video, more featured snippets, AI overviews) +- Pages that compete with newer pages on the same site (cannibalization) + +--- + +## Workflow + +1. **Charter the audit.** Scope (whole site or section), goal, time window for performance data. +2. **Pull the inventory.** Every URL, with publish date, primary topic, organic clicks, ranked keywords. +3. **Pull competitor coverage.** Top pages and content clusters from each competitor. +4. **Classify each existing page.** Healthy / thin / outdated / decaying / off-topic. +5. **Identify missing topics.** Cross-reference competitor top pages and keyword gap output. +6. **Score each opportunity.** See [`references/content-decision-matrix.md`](references/content-decision-matrix.md). +7. **Cluster.** Group related missing topics into pillar concepts. +8. **Decide actions.** Create / update / merge / redirect / prune for each opportunity. +9. **Sequence the roadmap.** Quarter by quarter, with effort estimates and traffic forecasts. +10. **Hand off.** Output feeds `content-strategy`, `content-and-copy`, and `seo-onpage`. + +--- + +## The action decision matrix + +For each piece of existing content or proposed new content, decide one action. + +| Signal | Action | +| --- | --- | +| Strong page, healthy traffic, current information | Keep. Defend with internal linking and refresh on schedule. | +| Page exists, ranking on page 2-3, content is thin vs SERP | Update. Deepen, restructure, broaden. | +| Page exists, traffic declining, content is dated | Refresh. Update facts, examples, year references, screenshots. | +| Page exists, low or zero traffic, low ranking, no improvement path | Prune or merge. Redirect to a stronger relative if one exists. | +| Multiple pages on overlapping topics | Merge into one canonical page. Redirect the others. | +| Topic missing entirely, competitor coverage strong | Create new page or pillar. | +| Topic missing, but competitors do not rank well either | Validate intent before investing. Could be an opportunity or could be a dead end. | +| Page is off-topic for the property | Redirect to most relevant page or remove from sitemap. | + +--- + +## Failure patterns + +- **All-create, no-update bias.** Teams default to creating new content. Updates and merges often outperform new pieces by a wide margin and at lower cost. +- **Treating publish date as currency.** A 5-year-old page can outrank a 1-month-old page if it is better. Stop deleting old content reflexively. +- **Cannibalization blind spots.** Two pages on overlapping topics dilute each other. Audit for it explicitly. +- **No effort estimates.** A roadmap without effort sizes cannot be sequenced realistically. +- **No traffic forecast.** A roadmap without forecasted impact loses funding fights. Forecast even with wide confidence bands. +- **Refreshing without re-promotion.** A refreshed page needs a re-crawl signal: update sitemap, internal links, distribution. +- **Ignoring intent shift.** Some keywords have shifted from informational to transactional or to AI-answer-dominated. Recognize when the SERP is no longer addressable by the existing format. +- **Confusing decay with seasonality.** A 30% click drop in summer for a back-to-school topic is not decay. Compare year-over-year, not month-over-month. +- **Auditing in isolation from the keyword gap.** The two audits feed each other. Run them adjacent. + +--- + +## Output format + +A content gap audit document with: + +1. **Executive summary.** Top 3 themes, content health verdict, recommended quarterly investment split. +2. **Content inventory snapshot.** Counts by health classification. +3. **Missing topics.** Prioritized list with cluster mapping and traffic forecast. +4. **Thin coverage.** Pages to deepen, with recommendation for each. +5. **Outdated content.** Pages to refresh, with refresh scope. +6. **Decaying content.** Pages to diagnose and act on, with hypothesis for each. +7. **Cannibalization findings.** Page pairs to merge. +8. **Action roadmap.** Quarter by quarter, with effort and forecast. +9. **Methodology.** Data sources, classification criteria, caveats. + +Length: 8-15 pages plus an attached inventory spreadsheet. + +--- + +## Reference files + +- [`references/content-decision-matrix.md`](references/content-decision-matrix.md) - Detailed decision tree for classifying pages and choosing the create/update/merge/prune action, with worked examples. diff --git a/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md b/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md new file mode 100644 index 0000000..65f3685 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md @@ -0,0 +1,177 @@ +# Content decision matrix + +A decision tree for classifying every page in a content audit and picking the right action. Use it after pulling the inventory and performance data. + +--- + +## The 6 actions + +Every page gets exactly one of these: + +1. **Keep.** Page is healthy. Defend it. +2. **Refresh.** Update facts, examples, screenshots, year references. +3. **Update.** Deeper rework. New sections, restructured argument, expanded scope. +4. **Merge.** Combine with another page. Redirect the loser. +5. **Redirect.** Page has no path forward. Redirect to closest relative. +6. **Prune.** Remove from sitemap, return 410 or noindex. + +--- + +## The decision tree + +Follow the tree top to bottom. The first match wins. + +### Step 1: Is the page on-topic for the property? + +If no: redirect to the most relevant page. If no relative exists, prune. + +### Step 2: Is the page duplicative of another page on the same site? + +If yes: merge. Pick the stronger of the two as the canonical, redirect the other. See "Merge selection criteria" below. + +### Step 3: Has traffic declined sharply over the last 6-12 months? + +Define "sharp": a drop of 40% or more, sustained for 3+ months, not explainable by seasonality. + +If yes: investigate. Likely actions are refresh, update, or redirect depending on root cause. See "Decay diagnosis" below. + +### Step 4: Is the page over 18 months old with stale specifics? + +Stale specifics include: outdated year references, old screenshots, dated examples, products no longer available, statistics from old reports. + +If yes: refresh. Keep the structure. Replace the stale parts. + +### Step 5: Is the page ranking on page 2-3 for relevant terms? + +Page 2-3 means positions 11-30 for keywords with meaningful volume. + +If yes: update. The page has potential. It needs more depth, better structure, or broader scope to break into top 10. + +### Step 6: Is the page getting steady traffic but the content is shallow vs the SERP? + +Shallow means: shorter than the top 3 SERP results, missing subtopics they cover, or single-keyword focused while they cover a topic cluster. + +If yes: update. The page is winning despite being thin. Make it stronger before competitors push it down. + +### Step 7: Is the page getting low traffic with no growth trend? + +Low traffic: under 50 organic clicks per month for an established page (over 12 months old). + +If yes and no clear path to improvement: prune or redirect. Do not waste effort trying to rescue every page. + +### Step 8: Default + +If none of the above, the page is healthy. Keep. Schedule a routine refresh on a 12-18 month cadence. + +--- + +## Merge selection criteria + +When two pages cover overlapping topics, decide which becomes canonical. + +Pick the page with: + +1. Stronger backlink profile (Ahrefs Site Explorer) +2. More ranked keywords with meaningful volume +3. Better URL (cleaner, more descriptive, shorter) +4. Higher current position for the head term + +If the pages have different strengths, often the right move is to keep the better URL and migrate the better content into it. + +Always: + +- 301 redirect the loser to the winner +- Update internal links to point at the canonical +- Notify Search Console (resubmit sitemap) +- Wait 4-8 weeks before evaluating impact + +--- + +## Decay diagnosis + +Sharp traffic decline can have multiple root causes. Diagnose before deciding action. + +### Possible causes and their signatures + +| Cause | Signature | Action | +| --- | --- | --- | +| SERP feature steal (featured snippet, PAA, AI overview) | Position stable, click-through rate fell | Refresh + restructure for snippet capture, or accept the new normal | +| Competitor published better content | Position fell, SERP composition includes new domain | Update to match or exceed competitor depth | +| Intent shifted (informational to transactional, etc.) | SERP composition is now a different content type (e.g., now product pages dominate) | Re-evaluate format, or pivot URL purpose | +| Internal cannibalization | A newer page on same site now ranks for the same term | Merge or differentiate | +| Site-wide ranking decline | Multiple pages lost position simultaneously | Likely site-wide issue, see `seo-traffic-diagnosis` | +| Content went stale | Year references and stats are outdated | Refresh | +| Algorithm update | Decline correlates with a known update date | Audit content quality and E-E-A-T | +| Lost backlinks | Referring domain count fell | See `seo-backlink-audit` for reclamation | +| Migration aftermath | Decline started immediately after a migration | Audit redirect chains and structural changes | + +Always confirm the cause before acting. Wrong diagnosis equals wrong fix. + +--- + +## Worked examples + +### Example 1: keep + +Page: pillar guide on a core topic, 2 years old, top 3 ranking, steady traffic, 800+ clicks/month, content is current. + +Decision: keep. Schedule routine refresh in 6 months. + +### Example 2: refresh + +Page: how-to guide, 3 years old, position 6-8, traffic flat for 12 months, screenshots show old UI, references "in 2023". + +Decision: refresh. Update screenshots, year references, and any tool versions. Re-promote internally. + +### Example 3: update + +Page: 1,200 word article on a category topic, position 14 for the head term, low CTR, top 3 results are 3,000+ word topic hubs covering 8-10 subtopics. + +Decision: update. Expand to cover the missing subtopics. Restructure for skim. Add internal links from related pages. + +### Example 4: merge + +Pages: two articles on closely overlapping topics, both ranking somewhere between positions 8-15 for related terms, splitting traffic. + +Decision: merge. Pick the page with stronger backlinks as canonical. Migrate the unique content from the other. 301 redirect the loser. Update internal links. + +### Example 5: redirect + +Page: outdated tutorial for a tool no longer in use, no organic traffic, no ranked keywords, off-topic for current site direction. + +Decision: redirect to closest relevant page. If none, prune (410 or noindex). + +### Example 6: prune + +Page: thin tag archive with under 5 items, no organic traffic, no internal links, indexed only because of CMS defaults. + +Decision: prune. Noindex via meta tag or remove from sitemap. Add to robots disallow if appropriate. + +--- + +## Effort and traffic forecast cheat sheet + +For sequencing the roadmap, use these rough estimates: + +| Action | Typical effort per page | Traffic impact timeline | +| --- | --- | --- | +| Keep | 0 (or routine refresh in 6-12 months) | None | +| Refresh | 2-4 hours | 30-60 days to see ranking impact | +| Update | 6-16 hours | 60-120 days | +| Merge | 4-8 hours per pair | 60-120 days | +| Redirect | 30 min | Immediate (no ranking impact) | +| Prune | 30 min | Immediate (positive if it removes thin content drag) | +| Create new | 12-30 hours | 90-180 days for new pages to gain traction | + +Updates and merges typically deliver more traffic per hour invested than new content. Most teams underweight them. + +--- + +## Common mistakes + +- **Pruning aggressively without verifying low value.** Some low-traffic pages have backlinks, internal link equity, or seasonal traffic. Audit these before pruning. +- **Refreshing pages that need updates.** A surface refresh on a thin page does not move rankings. Match the action to the root cause. +- **Updating pages that need merges.** Two competing pages on the same topic will keep splitting traffic. Merge first, then optimize. +- **Skipping internal link audit.** Updates and refreshes underperform without renewed internal links pointing to them. +- **Optimizing pages with intent mismatch.** If the SERP is now product pages and the page is an article, no amount of editing fixes that. Either pivot the page type or redirect. +- **Forgetting to notify Search Console.** Resubmit sitemap after major content moves to accelerate recrawl. diff --git a/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md b/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md new file mode 100644 index 0000000..ac38d93 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md @@ -0,0 +1,161 @@ +--- +name: seo-keyword-gap-audit +description: "Find keywords competitors rank for that the target property does not, and prioritize them by opportunity. Uses Ahrefs MCP for keyword and competitor data. Use this skill when planning content investment, identifying quick wins, building a content calendar against a competitor set, or scoping a market entry. Triggers on keyword gap, content gap, competitor keywords, opportunity keywords, what should we target, where are competitors winning, keyword opportunity. Also triggers when planning content for a new market or after losing organic share to a specific competitor." +category: seo-audit-suite +catalog_summary: "Competitor keyword gaps with opportunity scoring and clustering" +display_order: 3 +--- + +# SEO Keyword Gap Audit + +Find keyword opportunities by comparing the target property's organic footprint against a competitor set, using Ahrefs MCP data. Stack-agnostic. Produces a prioritized list of keywords to target with new or improved content. + +--- + +## When to use + +- Planning content investment for the next quarter +- Identifying quick-win keywords for fast organic gains +- Scoping market entry into a new vertical +- Refreshing a stale content strategy +- Diagnosing why a competitor is gaining organic share +- Pre-acquisition due diligence on growth ceiling + +## When NOT to use + +- Pure keyword discovery without a competitor frame (use `seo-keyword`) +- Single-page optimization (use `seo-onpage`) +- Content audit on existing pages (use `seo-content-audit`) +- Topic and pillar planning (use `content-strategy`) + +--- + +## Required inputs + +- Target property +- Competitor set (3-5 properties with overlapping intent and audience) +- Target market and language +- Business priorities (which segments matter most) +- Existing content inventory (URLs and primary topics) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: the gap matrix + +A keyword can fall into one of four cells based on whether the target ranks and whether competitors rank. + +| | Target ranks | Target does not rank | +| --- | --- | --- | +| **Competitors rank** | Shared territory (defend and grow) | Pure gap (the opportunity) | +| **Competitors do not rank** | Unique territory (asset to protect) | Untouched (validate before investing) | + +The audit focuses primarily on the "pure gap" cell. The other cells get secondary treatment. + +### Pure gap (top focus) + +Keywords where one or more competitors rank in the top 10 and the target does not rank at all or ranks past page 3. These are the primary opportunities. + +### Shared territory + +Keywords where both target and competitors rank. Useful for defending position and finding pages to push from page 2 to page 1. + +### Unique territory + +Keywords where the target ranks and no competitor does. These are differentiators. Audit to confirm they are actually valuable (not just irrelevant terms). + +### Untouched + +Keywords no one in the set ranks for. Could be opportunity or could be irrelevant. Validate intent before investing. + +--- + +## Opportunity scoring + +Not every gap keyword is worth pursuing. Score each candidate. + +### Scoring dimensions + +| Dimension | What it measures | Weight | +| --- | --- | --- | +| Search volume | Estimated monthly searches in target market | 20% | +| Business relevance | How close to a money topic for the target | 30% | +| Difficulty | How hard to rank (Ahrefs KD or proxy) | 15% | +| Intent match | Whether target can satisfy the dominant intent | 20% | +| Position potential | Realistic top 3 reach within 6 months | 15% | + +Weights adjust based on goal. For quick wins, weight position potential and difficulty higher. For strategic territory, weight business relevance and volume higher. + +### Opportunity score formula + +``` +score = (volume_normalized * 0.2) + + (relevance_score * 0.3) + + (difficulty_inverted * 0.15) + + (intent_match * 0.2) + + (position_potential * 0.15) +``` + +Where each input is normalized to 0-100. The result is a 0-100 score. + +### Banding for action + +| Score | Action | +| --- | --- | +| 80-100 | Top priority. Plan content this quarter. | +| 60-79 | Strong priority. Plan within 6 months. | +| 40-59 | Watch list. Revisit if competitive landscape shifts. | +| Below 40 | Park or drop. | + +--- + +## Workflow + +1. **Define the competitor set.** 3-5 properties. Confirm they share intent and audience. +2. **Pull keyword data.** For each property: organic keywords, top pages, traffic estimates. +3. **Build the gap matrix.** Label each keyword with which property ranks where. +4. **Filter to the pure gap cell.** Strip out the other cells for now. +5. **Validate intent.** For each keyword, confirm the SERP intent matches what the target can produce. +6. **Score by opportunity.** Use the formula. See [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md). +7. **Cluster.** Group related keywords into topics. One topic, one piece of content. +8. **Map to existing content.** Some gap keywords are addressable by updating an existing page rather than creating new. +9. **Sequence.** Build the prioritized list with action (create / update / merge / new pillar). +10. **Hand off.** Output feeds `content-strategy` and `seo-onpage`. + +--- + +## Failure patterns + +- **Wrong competitor set.** Choosing competitors by brand recognition rather than SERP overlap produces gap lists that are not actually competitive. Pick competitors that fight you in the SERPs. +- **Volume worship.** High-volume gap keywords are often unrealistic. A 50-volume keyword you can rank for beats a 5,000-volume keyword you cannot. +- **Ignoring intent.** A gap keyword where the SERP is dominated by tools or marketplaces is not addressable by an article. Match content type to intent. +- **Skipping clustering.** Targeting individual keywords instead of topics produces thin content that loses to topical hubs. +- **Over-relying on Ahrefs KD.** Difficulty scores are heuristics. Look at the actual SERP. If it is dominated by Forbes and Wikipedia, KD is misleadingly low. +- **No business filter.** A high-volume gap with zero buyer intent is a vanity opportunity. Filter for relevance. +- **One-shot audits.** Gap closes and reopens as competitors publish. Rerun on a cadence. +- **Forgetting unique territory.** Defending what you uniquely rank for can be more valuable than chasing gaps. Audit both directions. +- **Single-language audits in multi-market sites.** Run separate gap audits per market. Patterns differ. + +--- + +## Output format + +A keyword gap audit document with: + +1. **Executive summary.** Top 3 themes and top 10 priority keywords. +2. **Competitor set.** Who, why selected, SERP overlap evidence. +3. **The gap matrix.** Counts and patterns across the four cells. +4. **Pure gap analysis.** The opportunity list, scored and banded. +5. **Topic clusters.** Groups of related keywords mapped to content concepts. +6. **Action map.** Create / update / merge decisions per cluster. +7. **Quick wins.** Top 5-10 highest-confidence opportunities. +8. **Strategic plays.** High-impact, longer-horizon investments. +9. **Methodology.** Data sources, scoring weights, caveats. + +Length: 6-15 pages plus an attached opportunity spreadsheet. + +--- + +## Reference files + +- [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md) - Scoring rubric with normalization rules, formula, and worked examples. diff --git a/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md b/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md new file mode 100644 index 0000000..3b9af2a --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md @@ -0,0 +1,233 @@ +# Opportunity scoring rubric + +A scoring framework for ranking keyword gap opportunities. The score combines five normalized inputs into a single 0-100 ranking. Use it to convert a long gap list into a prioritized roadmap. + +--- + +## The 5 inputs + +### 1. Search volume (weight: 20%) + +Monthly search volume in the target market. + +Normalize on a log scale because volume is heavily skewed: + +| Volume range | Normalized score (0-100) | +| --- | --- | +| 0-100 | 20 | +| 100-500 | 40 | +| 500-2,000 | 60 | +| 2,000-10,000 | 80 | +| 10,000+ | 100 | + +Use Ahrefs Keywords Explorer for the volume figure. Confirm the country setting matches the target market. + +### 2. Business relevance (weight: 30%) + +How close is this keyword to a revenue or conversion topic? + +Score on intent stage: + +| Stage | Normalized score | Examples | +| --- | --- | --- | +| Direct purchase intent | 100 | "buy [product] online", "[product] price" | +| Comparison and evaluation | 80 | "best [product] for [use case]", "[product A] vs [product B]" | +| Problem-aware research | 60 | "how to [solve problem]", "what is [problem]" | +| Top-of-funnel education | 40 | "[broad topic] guide", "[topic] meaning" | +| Tangentially related | 20 | Adjacent topic with weak conversion path | +| Off-topic | 0 | Drop | + +Adjust based on business model. SaaS values evaluation-stage highly. Ecommerce values direct purchase highly. Media values volume across all stages. + +### 3. Difficulty (weight: 15%) + +How hard is it to rank in the top 10? Use Ahrefs Keyword Difficulty as the starting input, but verify against the actual SERP. + +Invert the score. Lower difficulty equals higher opportunity: + +| KD score | Inverted normalized score | +| --- | --- | +| 0-10 | 100 | +| 11-30 | 80 | +| 31-50 | 60 | +| 51-70 | 40 | +| 71-100 | 20 | + +Override KD if the SERP visibly contradicts it. A KD-15 SERP dominated by Forbes, Reddit, and Wikipedia is harder than a KD-40 SERP of niche bloggers. + +### 4. Intent match (weight: 20%) + +Can the target produce content that matches the dominant SERP intent? + +Look at the top 10 results and classify what they are: + +| SERP type | Match score for an article | Match score for a tool | Match score for a product page | +| --- | --- | --- | --- | +| Articles dominate | 100 | 20 | 0 | +| Tools or calculators dominate | 20 | 100 | 0 | +| Product pages dominate | 0 | 0 | 100 | +| Marketplaces dominate | 20 | 40 | 60 | +| Video dominates | 40 | 60 | 0 | +| Mixed (no dominant type) | 60 | 60 | 60 | + +If the target cannot produce the matching content type, drop the keyword regardless of other scores. + +### 5. Position potential (weight: 15%) + +Realistic top 3 reach within 6 months given current site authority. + +Estimate based on: + +- Current ranking position (if any) +- Domain Rating relative to the SERP +- Content depth required +- Topical authority in this space + +| Current position | DR vs SERP avg | Position potential score | +| --- | --- | --- | +| Top 3 already | Any | Skip (defend, do not gap-target) | +| Position 4-10 | At or above | 100 | +| Position 11-20 | At or above | 80 | +| Position 11-20 | Below | 60 | +| Position 21+ | At or above | 50 | +| Not ranking | Above SERP avg | 60 | +| Not ranking | At SERP avg | 40 | +| Not ranking | Below SERP avg | 20 | + +--- + +## The formula + +``` +score = (volume_normalized * 0.20) + + (relevance_score * 0.30) + + (difficulty_inverted * 0.15) + + (intent_match * 0.20) + + (position_potential * 0.15) +``` + +Score ranges 0-100. Apply the action banding: + +| Score | Action | Typical timeline | +| --- | --- | --- | +| 80-100 | Top priority. Plan content this quarter. | 0-90 days | +| 60-79 | Strong priority. Plan within 6 months. | 90-180 days | +| 40-59 | Watch list. Revisit on landscape shift. | Quarterly review | +| Below 40 | Park or drop. | Annual review | + +--- + +## Worked example 1: high-priority gap + +Keyword: "[mid-funnel evaluation phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 1,800/month | 60 | +| Relevance | Comparison stage | 80 | +| Difficulty | KD 25, SERP confirms accessible | 80 | +| Intent | Articles dominate, target produces articles | 100 | +| Position | Currently position 14, DR above SERP avg | 80 | + +``` +score = (60 * 0.20) + (80 * 0.30) + (80 * 0.15) + (100 * 0.20) + (80 * 0.15) + = 12 + 24 + 12 + 20 + 12 + = 80 +``` + +Band: top priority. Plan this quarter. + +--- + +## Worked example 2: borderline opportunity + +Keyword: "[broader top-of-funnel phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 9,500/month | 80 | +| Relevance | Top-of-funnel education | 40 | +| Difficulty | KD 55 with Forbes in top 3 | 30 (override) | +| Intent | Mixed SERP, target produces articles | 60 | +| Position | Not ranking, DR below SERP avg | 20 | + +``` +score = (80 * 0.20) + (40 * 0.30) + (30 * 0.15) + (60 * 0.20) + (20 * 0.15) + = 16 + 12 + 4.5 + 12 + 3 + = 47.5 +``` + +Band: watch list. Revisit if domain authority grows or if priority shifts. + +--- + +## Worked example 3: drop + +Keyword: "[high-volume but off-topic phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 22,000/month | 100 | +| Relevance | Tangentially related | 20 | +| Difficulty | KD 65 | 30 | +| Intent | Marketplaces dominate, target produces articles | 20 | +| Position | Not ranking, DR well below SERP avg | 20 | + +``` +score = (100 * 0.20) + (20 * 0.30) + (30 * 0.15) + (20 * 0.20) + (20 * 0.15) + = 20 + 6 + 4.5 + 4 + 3 + = 37.5 +``` + +Band: drop. High volume is not enough. + +--- + +## Adjusting weights for goal + +Default weights work for general opportunity audits. For specific goals: + +### Quick wins focus + +- Volume: 15% +- Relevance: 25% +- Difficulty: 25% +- Intent: 20% +- Position: 15% + +### Strategic territory focus + +- Volume: 25% +- Relevance: 35% +- Difficulty: 10% +- Intent: 20% +- Position: 10% + +### Defensive (protect rankings) + +Reuse the formula but apply to "shared territory" cell. Position potential weights higher. + +--- + +## Clustering after scoring + +After scoring individual keywords, cluster them. Targeting clusters beats targeting one-off keywords. + +Cluster rules: + +- Same dominant intent +- Overlapping SERP results (top 5 results match for 60%+ of the cluster) +- Naturally addressable by one piece of content + +Apply the highest score in the cluster as the cluster's score for prioritization. + +--- + +## Common mistakes when scoring + +- **Trusting volume estimates blindly.** Ahrefs estimates have wide confidence intervals at low volumes. A "50/month" keyword may be 5 or 200. +- **Treating KD as ground truth.** Always look at the SERP. KD is a heuristic, not a verdict. +- **Scoring before intent matching.** A keyword with mismatched intent scores high on paper but cannot rank for the target. Filter intent first. +- **One-time scoring.** Re-score quarterly. SERPs evolve. Competitor moves change difficulty. +- **No business filter.** A high score on a topic with zero conversion path is not an opportunity. Add a sanity check on relevance. +- **Optimizing for the formula, not the goal.** The score informs the call. The goal makes the call. diff --git a/dist/pi/.agents/skills/seo-keyword/SKILL.md b/dist/pi/.agents/skills/seo-keyword/SKILL.md new file mode 100644 index 0000000..f635e1f --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/SKILL.md @@ -0,0 +1,163 @@ +--- +name: seo-keyword +description: "Run keyword research, classify by search intent, cluster into topical groups, and prioritize for content production. Use this skill whenever the user asks to do keyword research, find target keywords, identify ranking opportunities, classify search intent, build a topical map, or plan a content strategy around what people search for. Triggers on keyword research, keyword strategy, search intent, keyword clustering, topic clusters, keyword difficulty, search volume, ranking opportunity, content gap, what should I write about, target keyword, primary keyword, secondary keyword, long-tail. Also triggers when planning a content calendar or new site without keywords yet defined." +category: seo-foundation +catalog_summary: "Discovery, intent classification, clustering, prioritization" +display_order: 3 +--- + +# Keyword Research + +Find the queries worth ranking for, classify them by intent, cluster them into topics, and prioritize what to produce. Stack-agnostic. Tool-agnostic (works with any keyword tool). + +--- + +## When to use + +- Starting a new site or content section +- Planning a content calendar +- Looking for ranking opportunities on an existing site +- Understanding search intent before writing +- Building topic clusters for internal linking +- Identifying content gaps vs competitors + +## When NOT to use + +- Optimizing a single page where the target query is already known (use `seo-onpage`) +- Comparing your site to a competitor across many dimensions (use `seo-competitor`) +- Auditing existing content for performance (use `seo-content-audit`) + +--- + +## Required inputs + +- The site or topic area +- The target audience and what they need +- A keyword tool (Ahrefs, Semrush, Moz, Google Keyword Planner, or similar) OR access to search console for an existing site +- Optional: 3 to 5 known competitors to seed the research + +If no tool is available, the skill still works using SERP inspection and search console data alone, but the volume estimates will be rough. + +--- + +## The framework: 4 stages + +### Stage 1: Discover + +Cast a wide net. Sources: + +- **Seed terms** from the brief or the user's vocabulary +- **Competitor keywords** (any keyword tool will export these) +- **Search console queries** for an existing site (find the page-1 and page-2 queries) +- **Related searches and "People also ask"** in actual SERPs +- **Customer language** (support tickets, sales calls, reviews) +- **Forum and community language** (Reddit, niche forums, Stack Overflow) + +Goal: 200 to 500 candidate keywords for a typical content sprint. More if planning a year of content. + +### Stage 2: Classify by intent + +Every keyword maps to one of four intents. Get this right or the rest is noise. + +| Intent | Signal | Page type that wins | +|---|---|---| +| **Informational** | "how to," "what is," "why," "best way to" | Article, guide, tutorial | +| **Navigational** | brand or product name + modifier | Brand homepage, product page | +| **Commercial** | "best," "review," "vs," "comparison," "alternatives" | Listicle, comparison, review | +| **Transactional** | "buy," "price," "deal," "near me," "for sale" | Product page, category page | + +A keyword tool's volume tells you the demand. The SERP tells you the intent. When in doubt, look at what's actually ranking. If page 1 is articles, the query is informational. If page 1 is product pages, it's transactional. + +**Hybrid intents exist.** "Best running shoes" is commercial-investigational. "Best running shoes under $100" is the same intent narrowed by a budget filter. Treat hybrids as their dominant intent and note the modifier. + +### Stage 3: Cluster + +Group keywords that should target the same page (or topic cluster). + +Two clustering approaches: + +**Approach A: SERP overlap.** If two keywords share at least 3 of the top 10 results, they target the same page. This is mechanical and reliable. + +**Approach B: Topical relevance.** Group keywords by the underlying topic, not just word overlap. "How to start a podcast" and "podcast equipment for beginners" are the same topic, different facets. + +Use both. A typical cluster has: +- 1 primary keyword (highest volume, broadest intent) +- 5 to 15 secondary keywords (variations and long-tails) +- 1 page that targets them all + +### Stage 4: Prioritize + +For each cluster, score on three dimensions: + +**Opportunity** (1 to 5): +- Volume (raw search demand) +- Click potential (some queries answer themselves in the SERP, lowering CTR) +- Conversion potential (does this query attract buyers or browsers?) + +**Difficulty** (1 to 5): +- Domain authority of top results +- Backlink count of top results +- Content depth and freshness of top results +- Whether the SERP has features (featured snippets, AI overview, video carousel) that compete with organic + +**Strategic fit** (1 to 5): +- Does it serve our audience? +- Does it support our positioning? +- Does it link to commercial pages naturally? + +**Priority score = Opportunity + Strategic fit - Difficulty.** + +Rank the clusters. Top 20 percent get produced first. + +--- + +## Workflow + +1. **Define the scope.** What site, what topic area, what audience. +2. **Run discovery.** Pull seeds, competitor exports, search console data, SERP inspections. Aim for 200 to 500 candidates. +3. **Deduplicate and clean.** Remove obvious junk, brand misspellings, irrelevant terms. +4. **Classify by intent.** Mark each keyword. +5. **Cluster.** Group into topical clusters. Aim for 20 to 50 clusters. +6. **Score each cluster** on opportunity, difficulty, and strategic fit. +7. **Prioritize.** Rank by composite score. Identify the top 10 to 20 clusters to produce first. +8. **Output.** Use the template in [`references/keyword-research-template.md`](references/keyword-research-template.md). + +--- + +## Failure patterns + +- **Chasing volume without intent.** A 10,000-volume informational keyword does not drive purchases. Match query to commercial outcome. +- **Targeting impossibly competitive keywords.** New sites cannot rank for "credit cards." Find the underserved long-tail variant. +- **Ignoring search console.** Existing sites already rank for queries they did not target. These are the easiest wins. +- **Treating clusters as one-keyword-per-page.** A page can target 10 to 30 related keywords. One-keyword-per-page leads to thin, cannibalized content. +- **Ignoring SERP features.** A query with a featured snippet, AI overview, and a video carousel above the organic results may not be worth pursuing. +- **Static keyword research.** Search demand shifts. Refresh the research at least annually for evergreen sites, quarterly for fast-moving topics. + +--- + +## Output format + +Default output: a spreadsheet (CSV or sheet) with one row per keyword and one row per cluster, plus a markdown summary with the top 10 to 20 clusters detailed. + +Recommended columns for the keyword sheet: + +| Column | Source | +|---|---| +| Keyword | Discovery | +| Volume | Tool | +| Difficulty | Tool | +| Intent | Manual classification | +| SERP features | Manual or tool | +| Cluster | Stage 3 | +| Cluster role (primary/secondary) | Stage 3 | +| Opportunity score | Stage 4 | +| Strategic fit | Stage 4 | +| Priority | Composite | +| Notes | Free text | + +--- + +## Reference files + +- [`references/keyword-research-template.md`](references/keyword-research-template.md) - Spreadsheet column definitions and a markdown summary template. +- [`references/intent-classification-guide.md`](references/intent-classification-guide.md) - Detailed examples of each of the four intent categories. diff --git a/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md b/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md new file mode 100644 index 0000000..0b145f2 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md @@ -0,0 +1,246 @@ +# Intent Classification Guide + +Detailed examples of each of the four search intent categories. Use this to tag every keyword in research with its intent before deciding what content (if any) to build. + +Intent classification is the most important and most-skipped step in keyword research. Tools surface volume and difficulty. They do not tell you whether the searcher wants to learn, compare, navigate, or buy. Without intent, you produce content that ranks for words but converts nothing. + +--- + +## The four intents + +| Intent | The searcher wants to | Right content | Right CTA | +|---|---|---|---| +| **Informational** | Learn something | Article, guide, video | Subscribe, related content | +| **Navigational** | Reach a specific destination | Branded page, login, location | Direct link | +| **Commercial investigation** | Compare options before buying | Comparison, review, list, buyer's guide | Demo, trial, deeper guide | +| **Transactional** | Take an action (buy, sign up, download) | Product page, pricing, signup, checkout | Buy / sign up / download | + +The same root word can fall into multiple intents depending on modifier. "Crm" alone is ambiguous. "What is a crm" is informational. "Salesforce login" is navigational. "Best crm for startups" is commercial investigation. "Buy salesforce" is transactional. + +--- + +## Informational intent + +The searcher wants to understand, learn, or solve a problem. + +### Signals + +- Question words: what, why, how, when, where, who +- "Guide," "tutorial," "examples," "definition," "explained" +- Topic-only queries with no commercial modifier ("dmarc records," "css grid") +- "How to" + a task + +### Examples + +| Query | Intent depth | Notes | +|---|---|---| +| "what is a service blueprint" | Top-of-funnel learning | Definition piece | +| "how to write a creative brief" | How-to | Step-by-step guide | +| "service blueprint examples" | Mid-funnel learning | Examples gallery | +| "service blueprint vs customer journey map" | Comparison-flavored learning | Overlaps with commercial; treat as info if no products in result | +| "why is css grid useful" | Conceptual | Explainer with code examples | +| "history of bauhaus design" | Background | Editorial / long-form | +| "node js error eaddrinuse" | Troubleshooting | Specific fix article | + +### What to publish + +Long-form articles, guides, glossary entries, video tutorials, original research. Content that earns subscribers, social shares, and backlinks. Not where conversion happens; where awareness builds. + +### CTA approach + +Soft. "Subscribe to the newsletter," "read the related guide," "join the community." A pricing CTA at the end of an informational piece reads as a bait-and-switch. + +### Failure mode + +Producing informational content with hard sales CTAs because someone metric'd it as "low conversion." Informational content's job is awareness and authority. Measure it on assists, brand recall, and downstream conversions, not last-click. + +--- + +## Navigational intent + +The searcher knows what they want and is using search to get there. + +### Signals + +- Brand names ("HubSpot," "Notion") +- Brand + modifier ("HubSpot login," "Notion pricing," "Salesforce careers") +- Product names ("MacBook Pro M4," "Tesla Model Y") +- Domain-style queries ("github.com," "facebook") + +### Examples + +| Query | What the searcher wants | +|---|---| +| "linear" | Linear's homepage | +| "linear login" | Linear's login page | +| "salesforce careers" | Salesforce's careers page | +| "amazon prime" | Amazon Prime's page | +| "github status" | GitHub's status page | + +### What to publish + +For your own brand: own the navigational queries. The homepage, login page, status page, careers page, contact page, pricing page should rank #1 for branded variants. + +For other brands' navigational queries: do not pursue. You will not rank, you should not try, and even if you did, the user does not want you. + +The exception: comparison queries ("Linear alternatives," "vs Linear") are not navigational; they are commercial investigation. See below. + +### CTA approach + +Whatever the destination expects. Login page → login form. Pricing page → buy or trial. Careers page → application. + +### Failure mode + +Treating "alternatives to" queries as navigational. They are not. They are commercial investigation, and a comparison page is the right format. + +--- + +## Commercial investigation intent + +The searcher is in the buying process but not ready to buy. They are comparing, reading reviews, building a shortlist. + +### Signals + +- "Best [category]" ("best crm for small business") +- "Top [category]" ("top hosting providers") +- "[Category] comparison" ("crm comparison") +- "[Brand] vs [brand]" ("notion vs obsidian") +- "[Brand] alternatives" ("alternatives to mailchimp") +- "[Brand] review" ("notion review") +- "[Category] for [audience]" ("crm for startups") +- "Cheap / affordable / free [category]" +- "Buyer's guide for [category]" + +### Examples + +| Query | What the searcher wants | +|---|---| +| "best email marketing tool" | A ranked list of options | +| "mailchimp vs convertkit" | A direct comparison | +| "alternatives to mailchimp" | A shortlist of competitors with pros and cons | +| "convertkit review" | Honest assessment from a third party (or the brand's own page if positioning) | +| "crm for solo consultants" | Curated shortlist for a niche | +| "free project management software" | Filtered list with feature notes | + +### What to publish + +- **For your category (high traffic, broad):** "best of" lists, ranked comparisons, buyer's guides. Honest about tradeoffs. Include yourself if relevant; do not lie about ranking. +- **For your brand vs others:** comparison pages on your own domain ("[YourBrand] vs [Competitor]"). These are the highest-converting content type after pricing pages. +- **For your category by use case:** segment-specific landing pages ("CRM for solo consultants," "CRM for series-A startups"). Use case + CTA. + +### CTA approach + +Stronger than informational, lighter than transactional. "Try [product] free," "see how it compares," "book a demo," "download the buyer's guide." Multiple CTAs are OK because the visitor's progress is uncertain. + +### Failure mode + +Writing a "best of" list that is transparently a sales pitch for your product. Readers and Google can both spot this. Honest comparison pages, even when they include you, perform far better than disguised brochures. + +--- + +## Transactional intent + +The searcher wants to act now. Buy, sign up, download, contact, get a quote. + +### Signals + +- "Buy," "purchase," "order" +- "Sign up," "create account" +- "Download" +- "Get a quote," "request a demo," "contact sales" +- Brand + transactional modifier ("buy [product]," "[product] coupon," "[product] discount") +- "[Product] near me" (local-transactional) +- "[Product] free trial" + +### Examples + +| Query | What the searcher wants | +|---|---| +| "buy iphone 16 pro" | Purchase, fast | +| "salesforce free trial" | Trial signup | +| "download notion mac" | Direct download | +| "request a demo hubspot" | Demo form | +| "plumber near me" | A plumber to call | +| "amazon prime sign up" | Amazon Prime signup flow | + +### What to publish + +Product pages, pricing pages, signup pages, checkout flows, contact pages. Make the transactional path frictionless. Strong CTAs above the fold. Trust signals near the action. + +### CTA approach + +The CTA is the page. One primary action, sized and placed so the user cannot miss it. Secondary actions allowed if they protect the primary (e.g., "talk to sales" alongside "start free trial" for enterprise vs SMB). + +### Failure mode + +Burying the transactional action behind marketing copy. The user came to act. Get out of the way. + +--- + +## Mixed and ambiguous intent + +Many queries do not fit cleanly. Use the SERP to disambiguate. + +### Method + +Open the query in incognito. Look at the top 10 results. + +- All articles? Informational. +- All branded landing pages? Navigational or transactional. +- Mix of comparison pages, "best of" lists, and product pages? Commercial investigation. +- Mix of articles and product pages? Mixed - the safer bet is to produce both kinds of content. + +### Example: "crm software" + +Could be informational ("what is CRM software"), commercial investigation ("which CRM should I pick"), or transactional ("crm software to buy now"). The SERP shows: a definition (HubSpot's), a "best of" list (multiple), several product pages, and a Wikipedia entry. Mixed intent leaning commercial investigation. + +The right play: produce a comparison page that opens with a one-paragraph definition. Catches both intents. + +--- + +## Intent shifts across the funnel + +The same audience moves through intents. + +| Stage | Example query | Intent | Right content | +|---|---|---|---| +| Aware of problem | "team is missing deadlines" | Informational | Article on missed-deadline diagnosis | +| Aware of category | "project management software" | Informational + commercial | Pillar guide | +| Comparing options | "linear vs jira" | Commercial investigation | Comparison page | +| Ready to commit | "linear pricing" | Transactional | Pricing page | +| Already a customer | "linear keyboard shortcuts" | Informational | Help docs | + +Build coverage across the funnel for your category. A site that only addresses transactional intent has nothing to rank for at the top of funnel and loses the audience to category-defining publishers. + +--- + +## Tagging in research + +When pulling keyword research, tag every row. + +| Query | Volume | Difficulty | Intent | Notes | +|---|---|---|---|---| +| "service blueprint" | 8,100 | 32 | Informational | Definition + examples piece | +| "service blueprint vs customer journey" | 1,200 | 28 | Commercial investigation | Comparison piece | +| "service blueprint template" | 2,400 | 25 | Informational + transactional | Template page with download CTA | +| "service blueprint software" | 880 | 41 | Commercial investigation | Buyer's guide | + +The intent tag drives the format and the CTA. Without it, content drifts into whatever the writer felt like producing. + +--- + +## Decision rule + +Once intent is tagged: + +- **Informational:** publish if the topic supports authority-building and the SERP is winnable. Skip if the SERP is dominated by big publishers and you have no asset. +- **Navigational (your brand):** make sure you own it. If not, fix. +- **Navigational (someone else's brand):** skip. +- **Commercial investigation:** publish if you compete in the category. These convert. +- **Transactional:** make sure your product / pricing / signup pages rank for the obvious branded transactional queries. Optimize them aggressively. + +--- + +## When intent surprises you + +Sometimes a query you assumed was one intent reveals as another. Trust the SERP over your assumption. The SERP reflects what Google has learned about searcher behavior at scale, which is more reliable than your guess. diff --git a/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md b/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md new file mode 100644 index 0000000..b701650 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md @@ -0,0 +1,115 @@ +# Keyword Research: [Site or Topic Area] + +**Date:** [YYYY-MM-DD] +**Scope:** [What this research covers] +**Audience:** [Who we are writing for] +**Tools used:** [Which keyword tools were used] + +--- + +## Summary + +**Total keywords analyzed:** [N] +**Clusters identified:** [N] +**Priority clusters (top 20%):** [N] + +[2 to 3 sentence overview. The headline themes, the surprising finds, the strategic priorities.] + +--- + +## Top priority clusters + +The following clusters scored highest on opportunity, strategic fit, and reasonable difficulty. Produce these first. + +### Cluster 1: [Cluster name] +- **Primary keyword:** [keyword] (volume: X, difficulty: Y) +- **Intent:** [Informational / Commercial / Transactional / Navigational] +- **Recommended page type:** [Article / guide / comparison / product page / category] +- **Secondary keywords:** [list 5 to 15] +- **Suggested URL:** [/proposed-slug] +- **Estimated effort:** [Hours or days] +- **Why this cluster:** [1 to 2 sentences on strategic fit] + +### Cluster 2: [Cluster name] +- **Primary keyword:** +- **Intent:** +- **Recommended page type:** +- **Secondary keywords:** +- **Suggested URL:** +- **Estimated effort:** +- **Why this cluster:** + +[Continue for top 10 to 20 clusters.] + +--- + +## Full keyword sheet + +[Link to or attach the spreadsheet.] + +Columns: +1. Keyword +2. Volume +3. Difficulty +4. Intent (I/N/C/T) +5. SERP features (featured snippet, AI overview, PAA, video, image, local pack) +6. Cluster +7. Cluster role (primary / secondary / long-tail) +8. Opportunity score (1-5) +9. Strategic fit (1-5) +10. Priority (composite) +11. Notes + +--- + +## Topic map + +A visual or hierarchical view of how the clusters relate. This becomes the basis for internal linking and information architecture. + +``` +[Top-level topic] + ├── [Cluster A] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + ├── [Cluster B] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + └── [Cluster C] + └── ... +``` + +--- + +## Quick wins + +Existing pages that already rank on page 2 or low page 1 for high-value keywords. Optimizing these is faster than producing new content. + +| URL | Current rank | Target query | Volume | Recommended action | +|---|---|---|---|---| +| | | | | | +| | | | | | + +(Pull from search console: queries with average position 5 to 20 and impressions over 100/month.) + +--- + +## Deferred clusters + +Clusters that did not make the priority cut and why. + +| Cluster | Reason | +|---|---| +| [Cluster name] | Too competitive for current authority | +| [Cluster name] | Low commercial value | +| [Cluster name] | Audience mismatch | +| [Cluster name] | Better suited for paid acquisition | + +--- + +## Refresh schedule + +This research should be revisited: +- **Quarterly** for fast-moving topics (tech, news, trends, finance) +- **Annually** for evergreen topics +- **After any major SERP feature change** (e.g., AI overviews appearing on key queries) +- **After authority increases** that unlock harder keywords (e.g., domain rating going up by 10+ points) diff --git a/dist/pi/.agents/skills/seo-offpage/SKILL.md b/dist/pi/.agents/skills/seo-offpage/SKILL.md new file mode 100644 index 0000000..fc103e6 --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/SKILL.md @@ -0,0 +1,168 @@ +--- +name: seo-offpage +description: "Plan and execute off-page SEO including link building, digital PR, brand mentions, citation building, and external authority signals. Use this skill whenever the user wants to build backlinks, plan a digital PR campaign, list local citations, run guest post outreach, develop linkable assets, recover lost links, or audit a backlink profile for risk. Triggers on link building, backlinks, digital PR, brand mentions, citation building, guest post, outreach, linkable asset, broken link building, HARO, podcast outreach, off-page SEO, anchor text, link velocity, toxic backlinks, disavow. Also triggers when the user is trying to grow domain authority or earn coverage." +category: seo-foundation +catalog_summary: "Link building, digital PR, citations, linkable assets" +display_order: 5 +--- + +# Off-Page SEO + +Build the external signals that earn rankings: backlinks, brand mentions, citations, and trusted sources pointing back to the site. Stack-agnostic. + +--- + +## When to use + +- Planning a link-building strategy +- Running digital PR or earned-media campaigns +- Building citations for a local business +- Developing linkable assets (research, tools, calculators) +- Recovering lost backlinks after a migration or audit +- Auditing a backlink profile for spam or toxicity +- Pitching guest posts, podcast appearances, or expert quotes + +## When NOT to use + +- On-site optimization (use `seo-onpage` or `seo-technical`) +- Keyword research and content planning (use `seo-keyword`) +- Competitor backlink research alone (start with `seo-competitor`, then return here for outreach planning) +- Paid link buying (this skill does not endorse or facilitate that) + +--- + +## Required inputs + +- The site or brand getting the links +- The audience and category +- A backlink tool (Ahrefs, Semrush, Moz, Majestic, or similar) for prospecting and monitoring +- A target outcome (rank for X, build authority in Y, recover from Z) + +--- + +## The framework: 4 strategies + +Off-page work splits into four strategy types. Most programs blend them. Pick the mix that fits your phase. + +### 1. Earned media +Links and mentions you earn through coverage, journalism, or contribution. + +- Digital PR (data-driven studies, original research, surveys) +- Expert quotes (HARO, journalist platforms, expert request services) +- Podcast appearances (relevant shows in your category) +- Speaking engagements and conference content +- Newsworthy product launches or company milestones + +**Strength:** Highest authority, hardest to replicate. +**Cost:** Time-intensive, often requires PR or content budget. +**Volume:** Low to medium per quarter. + +### 2. Owned assets +Linkable assets on your own site that attract links passively over time. + +- Original research and reports +- Free tools, calculators, and generators +- Comprehensive guides (the kind that become "the X resource for Y") +- Visualizations and interactive content +- Templates and frameworks +- Industry data trackers (regularly updated benchmarks) + +**Strength:** Compounds over time. Each link points at an evergreen asset. +**Cost:** Upfront content investment. +**Volume:** Slow to start, accelerates as the asset earns mentions. + +### 3. Partnerships and relationships +Links earned through real business relationships. + +- Customer case studies (where they link back) +- Partner programs and integrations +- Co-marketing campaigns +- Industry association memberships +- Speaker and expert contributor relationships +- Affiliate and referral programs + +**Strength:** Trustworthy, contextually relevant. +**Cost:** Time to develop relationships. +**Volume:** Medium and consistent. + +### 4. Citations and listings +Local and category-specific listings that establish entity legitimacy. + +- Google Business Profile (for local businesses) +- Bing Places, Apple Maps Connect +- Industry directories (review-quality only, skip spam directories) +- Niche association directories +- Wikipedia entry (where the brand qualifies for notability) +- Wikidata entry +- Trade publications and category indexes + +**Strength:** Foundational for local and entity SEO. +**Cost:** Low to medium, mostly setup time. +**Volume:** One-time foundation, occasional refresh. + +--- + +## Workflow + +1. **Audit the current profile.** + - Total referring domains + - Domain rating trend + - Top referring pages by traffic value + - Anchor text distribution (over-optimized exact-match anchors are a risk) + - Toxic links (spam directories, link farms, irrelevant categories) + - Lost links (referring domains that disappeared) + +2. **Define the goal.** "Rank top 3 for X by Q4" requires a different tactic mix than "build category authority." + +3. **Pick the strategy mix.** Allocate effort across the 4 strategies. A new site typically goes 70/20/10/0 (assets/citations/partnerships/earned) for the first year. An established site can lean more toward earned media. + +4. **Build the prospecting list.** + - For earned media: relevant journalists, podcast hosts, publication beats + - For owned assets: identify what assets to build based on what gets linked in your category + - For partnerships: list 50 to 100 potential partner sites + - For citations: standard list per category, plus niche directories + +5. **Outreach.** Personalized, value-first. Generic templated pitches damage the brand more than they help. + +6. **Track and measure.** + - Referring domains gained per month + - Domain rating trend + - Anchor text mix (avoid over-optimization) + - Pages on the site attracting links + - Lost link recovery rate + +7. **Audit and disavow.** Quarterly review for toxic links. Disavow only when there is real evidence of harm (manual penalty notice, sudden drop after spam attack). Most sites should not need to disavow. + +--- + +## Failure patterns + +- **Volume over quality.** 100 directory submissions help less than 5 editorial links from category-relevant sites. +- **Buying links.** Risk of manual penalties is real. Cost-adjusted, the ROI rarely works out. +- **Over-optimized anchor text.** If 40 percent of your inbound anchors are "best running shoes," it looks engineered. Aim for natural distribution: brand, naked URL, generic, partial-match, exact-match (in roughly that order of frequency). +- **Generic outreach templates.** "Dear [first name], I love your blog about [topic]" gets archived in seconds. Personalize or do not send. +- **Ignoring lost links.** A 5 percent monthly loss in referring domains compounds. Build a recovery workflow. +- **Treating disavow as a routine cleanup tool.** Disavow is for confirmed spam attacks or penalty recovery, not preemptive hygiene. +- **Working off-page before the site is worth linking to.** A poorly-designed, thin-content site will not convert outreach. Fix on-site first. + +--- + +## Output format + +Default output is a markdown plan at `offpage-strategy.md` plus tracking spreadsheets for prospects and outreach. + +Structure: +1. Current backlink profile summary +2. Goal and target metrics +3. Strategy mix (allocation across the 4 types) +4. Q1, Q2, Q3, Q4 tactical plan +5. Prospecting lists (in spreadsheets) +6. Outreach templates (personalized, never generic) +7. Tracking and measurement plan + +--- + +## Reference files + +- [`references/outreach-templates.md`](references/outreach-templates.md) - Templates for guest posting, expert quotes, broken-link outreach, podcast pitches. +- [`references/linkable-assets-guide.md`](references/linkable-assets-guide.md) - Categories of linkable assets with examples and effort estimates. diff --git a/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md b/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md new file mode 100644 index 0000000..ed9c7d7 --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md @@ -0,0 +1,353 @@ +# Linkable Assets Guide + +Categories of linkable assets, with examples and effort estimates. A linkable asset is content (or a tool, or a dataset) that other sites have a reason to link to. Without a linkable asset, link building is begging. With one, it is offering value. + +--- + +## What makes an asset linkable + +A linkable asset has at least one of these properties: + +- **It is the only place to find this thing.** Original data, original tool, original framework. +- **It is the best place to find this thing.** Most comprehensive, most current, most carefully built. +- **It saves the linker time.** A reusable resource the linker would otherwise have to build or explain. +- **It carries authority.** Survey from a recognized brand, published research, expert-authored. +- **It is current.** Updated more recently than alternatives, with the year visible. + +Pages that fail all five are not linkable. They might be useful, but they are not assets that earn links. + +--- + +## Category 1: original research + +Surveys, studies, or data analyses you ran and nobody else has. + +### Examples + +- Annual industry survey (e.g., "State of [category] 2026") +- Benchmark report from your own product data ("the average [metric] across 1,000 companies using us") +- Trend analysis from public data sources you cleaned and synthesized +- Salary or compensation report for your industry +- Pricing transparency report ("what [category] really costs") + +### Effort + +- **Low end:** 40-80 hours (existing data, in-house analysis, single-author write-up) +- **High end:** 200-400 hours (custom survey, n=1,000+, design and PR investment) + +### Link earning rate + +Highest of any category, when done well. A defensible original research asset can earn 100+ referring domains over its life. + +### When to invest + +If you have unique access to data (your product's data, your customer base, your industry network) and you can update annually, this is the highest-leverage asset category. + +### When to skip + +If the data is shallow, the sample is small, or the analysis is obviously self-serving, the asset will be ignored or worse, criticized publicly. + +--- + +## Category 2: free tools + +Calculators, validators, generators, viewers - small interactive utilities that solve a specific problem. + +### Examples + +- Calculators (mortgage, ROI, paycheck, conversion rate) +- Validators (HTML, schema markup, robots.txt, regex) +- Generators (favicon, color palette, password, lorem ipsum, og image) +- Converters (currency, units, file format) +- Viewers (JSON, EXIF, certificate) + +### Effort + +- **Low end:** 20-40 hours (single-purpose calculator, basic UI) +- **High end:** 200+ hours (rich tool with saved state, account integration, PWA, accessibility-perfect) + +### Link earning rate + +High and durable. Tools earn links steadily for years if they remain useful and current. + +### When to invest + +When the problem is recurring, you can build something cleaner than what exists, and the tool naturally surfaces your product as the next step (e.g., a "how much will this site weigh" tool from a perf optimization vendor). + +### When to skip + +When the space is saturated with free tools that already work well. A new "color picker" is unlikely to displace the entrenched ones. + +--- + +## Category 3: definitive guides + +Long-form, exhaustive coverage of a topic that becomes the reference everyone links to. + +### Examples + +- "The complete guide to DMARC" +- "The HTTP status code reference" +- "Web performance metrics explained" +- "The 2026 GDPR compliance checklist" +- "All the CSS units, with examples" + +### Effort + +- **Low end:** 40-80 hours +- **High end:** 200+ hours, plus annual maintenance + +### Link earning rate + +High when the topic has natural inbound demand and the asset is genuinely the best version. Lower when 5+ competitor guides already exist. + +### When to invest + +When you can credibly produce something better than the current best (more comprehensive, more current, better organized, better examples, better visuals). When the topic supports your business strategically. + +### When to skip + +When the topic is dominated by an evergreen entrenched guide (Wikipedia-level reference, MDN, NN/g) that you cannot displace. + +--- + +## Category 4: visual / interactive assets + +Infographics, interactive explainers, micro-sites built around a single concept. + +### Examples + +- Interactive timelines +- Animated explainers ("how does HTTPS work") +- Map-based visualizations +- Comparison interactive ("the size of every JavaScript framework") +- Single-purpose explainer micro-sites (e.g., "supply chain visualizer") + +### Effort + +- **Low end:** 40-80 hours (static infographic, simple interactive) +- **High end:** 400+ hours (complex interactive, custom illustration, browser-based simulation) + +### Link earning rate + +High when the visual is genuinely useful and shareable. Often peaks early and decays unless the topic has lasting interest. + +### When to invest + +When visual treatment unlocks something prose cannot show. When the topic has strong visual storytelling potential. When you have design capacity to do it well. + +### When to skip + +When the same value can be delivered as a normal article. Visual treatment is not a substitute for substance; it is a multiplier on substance that already exists. + +--- + +## Category 5: templates and frameworks + +Reusable structures the audience can copy, adapt, and use. + +### Examples + +- Project plan templates +- Notion / Airtable templates with download +- Email outreach templates +- Pitch deck templates +- Resume / CV templates +- Code starter templates (CodeSandbox, Stackblitz, GitHub repos) +- Frameworks ("the SPADE framework for decisions") + +### Effort + +- **Low end:** 8-20 hours per template +- **High end:** 40-80 hours for a polished template suite + +### Link earning rate + +Moderate. Templates earn references in roundups and resource lists. Less likely to earn high-authority editorial links. + +### When to invest + +When the template solves a frequent problem in your audience's work and naturally connects to your product. + +### When to skip + +When the template space is crowded with free, polished alternatives. + +--- + +## Category 6: glossaries and reference indexes + +Comprehensive, well-organized indexes of terms, codes, status messages, error codes, etc. + +### Examples + +- "All HTTP status codes with examples" +- "Glossary of marketing terms" +- "Every accessibility WCAG criterion explained" +- "The full list of CSS pseudo-classes" + +### Effort + +- **Low end:** 40-80 hours +- **High end:** 200+ hours, plus continuous updates + +### Link earning rate + +Moderate to high. Reference assets earn links steadily as authors writing on related topics need a place to link the term. + +### When to invest + +When you have the patience to be exhaustive and the topic supports it. + +### When to skip + +When canonical references already exist and dominate (MDN, W3C, official docs). + +--- + +## Category 7: industry rankings and lists + +Annual or continuous lists ranking companies, products, or trends in a category. + +### Examples + +- "The 100 fastest-growing [category] companies" +- "The 50 best [job role] to follow" +- "[Industry] state-of-the-art software comparison" + +### Effort + +- **Low end:** 60-100 hours +- **High end:** 200+ hours with PR + +### Link earning rate + +Moderate to high. Ranked companies link to the list as a credibility signal. Higher rankings earn more links. + +### When to invest + +When you have the credibility to be the ranker (your audience trusts your judgment in the category). + +### When to skip + +When you would be ranking yourself or competitors with no objectivity. + +--- + +## Category 8: events and community assets + +Conferences, summits, awards, communities you sponsor or run. + +### Examples + +- Industry conference recap and highlight reels +- Annual awards +- Slack / Discord community +- Recurring meetup +- Podcast + +### Effort + +- **High.** Events and communities require continuous investment, not one-time. + +### Link earning rate + +Moderate. Earns links from participants, partners, press coverage. + +### When to invest + +When the audience-building flywheel is part of your strategy and you can sustain investment for 2+ years. + +### When to skip + +When the team cannot commit to sustained investment. + +--- + +## Category 9: opinionated takes and POVs + +Strong, well-argued positions on industry questions. Not lists, not data; arguments. + +### Examples + +- "Why we stopped using [framework]" +- "The case against [common practice]" +- "[Industry standard] is wrong, and here is why" +- Manifestos + +### Effort + +- **Low.** A great POV piece can be 1,500-3,000 words and 10-30 hours. + +### Link earning rate + +Highly variable. A POV that hits a nerve in the industry can earn 50+ links in a week. Most POVs earn nothing. + +### When to invest + +When the author has standing to take the position credibly (track record, role, prior writing). When the POV is genuinely held and well-defended. + +### When to skip + +When the POV is contrarian for the sake of being contrarian. Bad-faith hot takes earn ire and short-term traffic, not durable links. + +--- + +## How to pick + +Score candidates against four dimensions: + +| Dimension | Weight | Score 1-5 | +|---|---|---| +| Strategic fit | 30% | Does it serve a topic cluster you want to own? | +| Defensibility | 25% | Can you build something competitors will not easily match? | +| Effort | 25% | What does it cost to ship and maintain? (Lower effort = higher score) | +| Audience pull | 20% | Will the right people link to it? | + +Build the highest-scoring candidate first. Ship one asset all the way through promotion before starting the next. Two well-promoted assets beat ten orphaned ones. + +--- + +## Promotion plan (a separate but linked task) + +A linkable asset that nobody knows about earns no links. The promotion plan must exist before the build starts. + +Typical promotion plan elements: + +- 5-10 pre-launch outreach contacts (industry voices, friendly press, peer companies who would benefit) +- Coordinated social, email, and content launch +- Explicit "ask" templates for outreach (no link begging; offer the asset as relevant, let the linker decide) +- Follow-up content that references the asset for the next 3-6 months +- Ongoing maintenance plan (annual update for research, evergreen updates for tools) + +Without a promotion plan, even great assets sit unlinked. + +--- + +## Common failure modes + +- **Asset is too thin.** Calling a 600-word article a "definitive guide" earns no respect. +- **Asset is dated.** "2022 industry report" still on the site in 2026. Looks abandoned. +- **No promotion plan.** Built, shipped, never told anyone. +- **Self-serving disguised as research.** Survey questions written to produce a result that flatters your product. +- **Tool that breaks.** Calculator with stale data, validator that misses common cases. Returns negative trust. +- **Asset that offers no follow-up.** Visitor arrives, uses it, leaves. No reason to subscribe, register, or convert. + +--- + +## Rough effort vs durable links matrix + +| Category | Effort | Typical referring domains over asset's life | +|---|---|---| +| Free tool (single-purpose) | 30 hours | 40-200 | +| Free tool (rich) | 200 hours | 100-1,000 | +| Original research (annual) | 100 hours | 50-500 per edition | +| Definitive guide | 80 hours | 30-300 | +| Visual / interactive | 80 hours | 30-200 | +| Templates suite | 40 hours | 10-100 | +| Glossary / reference index | 80 hours | 50-300 | +| Industry ranking (annual) | 100 hours | 50-300 per edition | +| Community / event | 1,000+ hours | 100-1,000 | +| POV piece | 20 hours | 0-200 (high variance) | + +These are rough ranges from typical SaaS and content-led businesses. Industry, audience size, and promotion quality all shift them substantially. diff --git a/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md b/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md new file mode 100644 index 0000000..4db4f4b --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md @@ -0,0 +1,213 @@ +# Outreach Templates + +Templates for the most common off-page outreach scenarios. Personalize every send. The templates are scaffolding, not ready-to-fire copy. + +A few rules across all templates: + +- Subject lines under 60 characters +- First line never says "I love your blog" or any variant +- One specific reference to their actual work (not a generic compliment) +- One clear ask +- One reason it benefits them, not you +- Sign with a real name and link to a real profile +- Plain text, no formatting, no images, no tracking pixels + +--- + +## Guest post pitch + +**Subject:** [Topic] for [their site name]? + +Hi [first name], + +I just read your piece on [specific article, published Date] and noticed [specific observation about an angle they did not cover, or a question their piece raised but did not answer]. + +I write about [your topic area] and I think the gap there could become a strong follow-up. Working title: "[Specific working title]." It would cover: + +- [Specific point 1] +- [Specific point 2] +- [Specific point 3] + +I can have a draft to you in two weeks. Recent samples of my writing: +- [URL 1] +- [URL 2] + +If this is not a fit, no worries. Let me know either way. + +Thanks, +[Name] +[Title and where you write] + +--- + +## Expert quote / source pitch + +**Subject:** Expert source on [topic] for your [piece type] + +Hi [first name], + +I saw your request for sources on [topic] via [HARO / Twitter / their site]. + +Quick credentials: [one sentence on why you're qualified - title, years, specific work]. Happy to provide a quote, full interview, or background on: + +- [Specific angle 1] +- [Specific angle 2] +- [Specific angle 3] + +Available for a quick reply via email today, or a call this week. + +[Name] +[Title] +[Profile / portfolio link] + +--- + +## Broken link outreach + +**Subject:** Broken link on your [page topic] page + +Hi [first name], + +I was reading your [page name] page (great resource) and noticed the link to [specific old URL] is broken - the destination returns a 404. + +I run [your site] and we have a piece on the same topic that might be a relevant replacement: [your URL]. It covers [specific overlap with what the broken link was for]. + +No pressure either way. Just wanted to flag the broken link. + +[Name] + +--- + +## Podcast pitch + +**Subject:** [Specific topic angle] for [show name]? + +Hi [first name], + +I have been listening to [show name] for [time period]. The recent episode with [guest name] on [topic] resonated because [specific reason]. + +I would love to come on and talk about [specific topic angle]. Why this is a fit for your audience: + +- [Specific angle 1] +- [Specific angle 2] +- [What I bring that other guests have not covered] + +Past appearances: +- [Show name] - [topic] - [link] +- [Show name] - [topic] - [link] + +If the topic resonates, I can send a one-page brief with sample questions. + +[Name] +[Title] +[Headshot / bio link] + +--- + +## Resource page link request + +**Subject:** Resource for your [page topic] roundup + +Hi [first name], + +Your [page name] page is one of the better roundups I have seen on [topic]. I noticed it includes [example resource they list]. + +I run [site] and recently published [your URL], which covers [specific angle]. A few reasons it might earn a spot in the list: + +- [Differentiator 1: e.g., original data, more detail, recently updated] +- [Differentiator 2] + +If it is a fit, I would be grateful for the inclusion. If not, completely understood. + +[Name] + +--- + +## Linkable asset announcement + +**Subject:** New [asset type] on [topic] + +Hi [first name], + +We just published [asset type, e.g., "an interactive calculator", "a 50-source benchmark study", "a free template"] on [topic]: [URL]. + +The reason I am sending it your way: [specific reason this person or publication would care - their audience overlap, a stated interest, a recent piece they wrote]. + +Three things that make it different from existing resources: +1. [Specific differentiator] +2. [Specific differentiator] +3. [Specific differentiator] + +If it is useful for your readers, I would love a mention. Either way, I would value your read of it. + +[Name] + +--- + +## Citation / mention reclamation + +When your brand is mentioned online but not linked to. + +**Subject:** Quick note on the [piece] you published + +Hi [first name], + +Thanks for mentioning [your brand] in your [piece title, with link]. Genuinely appreciated. + +Quick request: would you be open to linking the mention back to [your URL]? Helps your readers find us, and helps us track the reach of the piece. + +No worries if it is not your editorial standard to add links retroactively. + +Thanks, +[Name] + +--- + +## Partnership pitch (low-key) + +**Subject:** [Brand] x [their brand]? + +Hi [first name], + +I run [your brand]. We share an audience with [their brand] - both serving [audience description]. + +A few low-effort ways we could collaborate: + +1. [Specific idea: e.g., cross-promote in newsletters, swap quotes for content, co-host a webinar] +2. [Specific idea] +3. [Specific idea] + +If any resonate, I would love a 20-minute call to figure out the simplest version we could ship in 30 days. + +[Name] +[Title] +[Site] + +--- + +## Universal don'ts + +- Do not start with "Hope you are doing well." +- Do not call yourself a "fellow [profession]" unless you actually know them. +- Do not say "I'll keep this brief" and then write 600 words. +- Do not attach files in cold outreach. +- Do not follow up more than twice. Three+ follow-ups damage reputation. +- Do not use subject lines like "Quick question" or "Re: [topic]" if it is not actually a reply. +- Do not include phrases like "value-add," "synergy," or "leverage." +- Do not pitch yourself as the expert in their field. They are. + +--- + +## Personalization checklist + +Before sending any outreach: + +- [ ] Used their first name correctly (spelled right) +- [ ] Referenced specific recent work of theirs (not from 5 years ago) +- [ ] Stated the ask clearly in the first 3 lines +- [ ] Gave them a reason to say yes that benefits them +- [ ] Plain text, no HTML, no images, no tracking pixel +- [ ] Subject line under 60 characters and not deceptive +- [ ] Signature includes real credentials and a way to verify the sender + +If any are missing, do not send. diff --git a/dist/pi/.agents/skills/seo-onpage/SKILL.md b/dist/pi/.agents/skills/seo-onpage/SKILL.md new file mode 100644 index 0000000..ae226fe --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-onpage +description: "Run a comprehensive on-page SEO audit or optimization pass covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, URL hygiene, and on-page schema. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review header structure, check internal linking, improve a single URL's search performance, or write SEO-friendly copy. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization, optimize this page, SEO this page. Also triggers for any single-page review where ranking, click-through, or relevance signal quality is the goal, even if the user does not say 'SEO' explicitly." +category: seo-foundation +catalog_summary: "Single-page audits and optimization across 8 dimensions" +display_order: 1 +--- + +# On-Page SEO + +Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site. + +--- + +## When to use + +- Auditing or optimizing a single page (homepage, product page, article, landing page) +- Writing or reviewing title tags and meta descriptions +- Fixing header structure or content hierarchy +- Reviewing internal links from or to a page +- Improving a page's CTR from search results + +## When NOT to use + +- Site-wide crawl, indexing, or speed issues (use `seo-technical`) +- Keyword research or intent mapping (use `seo-keyword`) +- Competitor SERP analysis (use `seo-competitor`) +- Auditing many pages at once for prune/merge decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- The page URL or the draft content if pre-launch +- The primary target query (one phrase the page should rank for) +- The page's role in the site (commercial, informational, navigational) + +If the target query is unknown, run `seo-keyword` first or ask the user to name one. + +--- + +## The framework: 8 dimensions + +A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix. + +### 1. Title tag +- One unique title per URL across the site +- Roughly 50 to 60 characters (longer gets truncated in SERPs) +- Primary query near the front +- Brand at the end if it earns inclusion +- Distinct from the H1 (often very similar, but should not be identical word-for-word) + +### 2. Meta description +- One unique description per URL +- Roughly 150 to 160 characters +- Restates the value proposition, not the title +- Includes a soft CTA where natural +- Treats the description as ad copy that earns the click + +### 3. Header structure +- Exactly one H1 per page +- H1 contains or paraphrases the primary query +- H2 sections cover the major sub-topics +- H3+ used only when an H2 has genuine sub-points +- No skipped levels (no H2 followed by H4) +- Headers describe sections accurately enough that a reader could navigate by them alone + +### 4. Body content +- Opens with the primary user intent answered in the first paragraph +- Covers the topic comprehensively (define your competition's depth, then match or exceed it) +- Includes related entities and supporting concepts naturally +- Avoids keyword stuffing (write for the reader, not the bot) +- Reading level matches the audience (run a readability check) +- Paragraphs short enough to scan on mobile (3 to 5 lines) + +### 5. Internal links +- At least 2 to 3 outbound internal links to closely related pages +- At least 2 to 3 inbound internal links from related pages +- Anchor text is descriptive, not "click here" or "learn more" +- Links to canonical URLs, not redirects +- No broken internal links + +### 6. Images and media +- Every meaningful image has descriptive alt text (skip alt for purely decorative images) +- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg") +- Modern format used where supported (WebP, AVIF) +- Lazy loading on below-the-fold images +- Width and height attributes set to prevent layout shift + +### 7. URL slug +- Lowercase, hyphen-separated +- Includes the primary query naturally (no stuffing) +- Short (under 60 characters where possible) +- No dates unless the page is genuinely time-bound +- No session IDs, tracking parameters, or random hashes +- Matches the site's URL pattern conventions + +### 8. On-page schema +- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.) +- Required properties filled (review Schema.org docs for the type) +- Validates in Google's Rich Results Test or equivalent +- Matches what is visible on the page (do not lie to crawlers) +- Author and publisher schema linked correctly for content pages + +--- + +## Workflow + +1. **Confirm the target query.** If unclear, ask. Do not optimize without one. +2. **Render the page.** View it as a user would. Read the content top to bottom. +3. **View the rendered HTML.** Inspect the actual served markup, not just the visual page. Check `<title>`, `<meta>`, headers, and schema in the source. +4. **Run the 8-dimension framework.** Score each, note specific fixes. +5. **Prioritize.** Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish). +6. **Write the report.** Use the template in [`references/audit-template.md`](references/audit-template.md). +7. **Offer to draft fixes.** If the user wants, draft the new title, meta, headers, or copy directly. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Make it more SEO."** Vague. Ask for the target query and what's broken first. +- **"Add the keyword 5 times in the body."** Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead. +- **Optimizing a page that is not crawlable or indexable.** Check `seo-technical` first. No on-page work helps a noindexed page. +- **Optimizing a page with no clear user intent.** A page that does not serve a real query will not rank no matter how well-tagged it is. +- **Targeting the same query as another page on the site.** This is cannibalization. Use `seo-content-audit` to decide which page should rank. + +--- + +## Output format + +Default output is a markdown audit at `seo-audit-[page-slug].md` in the project root. Structure: + +1. Page summary (URL, target query, role) +2. Score across 8 dimensions +3. Critical fixes +4. Important fixes +5. Nice-to-have polish +6. Drafted replacements (if requested) + +Keep audits under 1500 words. If a page needs more detail, link to deeper appendices. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable audit template, copy and use. +- [`references/onpage-checklist.md`](references/onpage-checklist.md) - Quick-reference checklist for the 8 dimensions. +- [`references/title-and-meta-patterns.md`](references/title-and-meta-patterns.md) - Patterns for writing strong titles and meta descriptions. diff --git a/dist/pi/.agents/skills/seo-onpage/references/audit-template.md b/dist/pi/.agents/skills/seo-onpage/references/audit-template.md new file mode 100644 index 0000000..ab15d58 --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/audit-template.md @@ -0,0 +1,112 @@ +# On-Page SEO Audit: [Page URL] + +**Target query:** [The primary phrase this page should rank for] +**Page role:** [Commercial / Informational / Navigational] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] + +--- + +## Summary + +[2 to 3 sentence overview. What's working, what's broken, what to fix first.] + +**Overall score:** [Pass / Needs work / Fail] + +| Dimension | Score | One-line note | +|---|---|---| +| Title tag | | | +| Meta description | | | +| Header structure | | | +| Body content | | | +| Internal links | | | +| Images and media | | | +| URL slug | | | +| On-page schema | | | + +--- + +## Critical fixes + +[Things that are broken, missing, or actively hurting the page.] + +### 1. [Fix name] +- **Current:** [What it is now] +- **Problem:** [Why it's broken] +- **Fix:** [Specific replacement] + +### 2. [Fix name] +- **Current:** +- **Problem:** +- **Fix:** + +--- + +## Important fixes + +[Things that are suboptimal but not broken.] + +### 1. [Fix name] +- **Current:** +- **Problem:** +- **Fix:** + +--- + +## Nice-to-have polish + +[Things that would lift the page from good to great.] + +- [Item] +- [Item] + +--- + +## Drafted replacements + +### Title tag +> **Current:** [exact current title] +> **Proposed:** [exact proposed title, with character count] + +### Meta description +> **Current:** [exact current meta] +> **Proposed:** [exact proposed meta, with character count] + +### H1 +> **Current:** [exact current H1] +> **Proposed:** [exact proposed H1] + +### Header outline +``` +H1: [proposed H1] + H2: [proposed section title] + H3: [if needed] + H2: [proposed section title] + H2: [proposed section title] +``` + +### URL (only if changing) +> **Current:** [current URL] +> **Proposed:** [proposed URL] +> **Redirect required:** Yes / No + +--- + +## Implementation notes + +[Any stack-specific considerations, deploy gotchas, or order-of-operations notes.] + +- [Note] +- [Note] + +--- + +## Verify after deploy + +- [ ] Rendered title in SERP preview tool matches proposed +- [ ] Rendered meta description matches proposed +- [ ] H1 visible and matches proposed +- [ ] Schema validates in Rich Results Test +- [ ] Internal links resolve, no broken anchors +- [ ] Images load with correct alt text +- [ ] If URL changed: 301 redirect in place, old URL no longer in sitemap diff --git a/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md b/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md new file mode 100644 index 0000000..283cf3e --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md @@ -0,0 +1,90 @@ +# On-Page SEO Checklist + +A condensed checklist for the 8 dimensions. Use as a pre-publish gate or a quick audit pass. + +--- + +## Title tag + +- [ ] Unique across the site +- [ ] 50 to 60 characters +- [ ] Primary query near the front +- [ ] Brand at end (only if it earns inclusion) +- [ ] Not identical to H1 +- [ ] Reads as a compelling search snippet, not a list of keywords + +## Meta description + +- [ ] Unique across the site +- [ ] 150 to 160 characters +- [ ] Restates value, does not repeat title verbatim +- [ ] Includes a soft CTA where natural +- [ ] No keyword stuffing +- [ ] Treats it as ad copy + +## Header structure + +- [ ] Exactly one H1 +- [ ] H1 contains or paraphrases primary query +- [ ] H2s cover the major sub-topics +- [ ] No skipped levels (H2 to H4 with no H3) +- [ ] Headers describe the section accurately +- [ ] A reader could navigate by headers alone + +## Body content + +- [ ] First paragraph answers the primary user intent directly +- [ ] Topical depth matches or exceeds top-ranking competitors +- [ ] Related entities and concepts appear naturally +- [ ] No keyword stuffing +- [ ] Reading level matches the audience +- [ ] Paragraphs are mobile-scannable (3 to 5 lines) +- [ ] Includes original perspective or proprietary data where possible + +## Internal links + +- [ ] At least 2 to 3 outbound internal links to related pages +- [ ] At least 2 to 3 inbound internal links from related pages +- [ ] Anchor text is descriptive +- [ ] Links to canonical URLs (no redirects) +- [ ] No broken internal links + +## Images and media + +- [ ] Every meaningful image has descriptive alt text +- [ ] Decorative images use empty alt (`alt=""`) +- [ ] File names are descriptive +- [ ] Modern format used (WebP or AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] Width and height attributes set +- [ ] Captions where they aid comprehension + +## URL slug + +- [ ] Lowercase, hyphen-separated +- [ ] Includes primary query naturally +- [ ] Under 60 characters where possible +- [ ] No dates unless time-bound +- [ ] No tracking parameters +- [ ] Matches site URL conventions + +## On-page schema + +- [ ] Appropriate Schema.org type +- [ ] Required properties filled +- [ ] Validates in Rich Results Test +- [ ] Matches what is visible on the page +- [ ] Author and publisher schema linked for content pages +- [ ] BreadcrumbList schema for nested pages + +--- + +## Quick wins (fastest to implement, biggest typical impact) + +1. Rewrite title tag for CTR +2. Rewrite meta description for CTR +3. Fix any missing or duplicate H1 +4. Add 2 to 3 internal links from existing related pages +5. Add alt text to images that lack it + +If a page is underperforming and you only have 30 minutes, run those five. diff --git a/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md b/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md new file mode 100644 index 0000000..71d1dd1 --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md @@ -0,0 +1,306 @@ +# Title and Meta Patterns + +Patterns for writing strong title tags and meta descriptions. The title tag and meta description are the two most-edited and most-impactful elements in on-page SEO. They are also the two most often left as defaults. + +--- + +## Title tag patterns + +### The job of the title tag + +- Tell Google what the page is about (ranking signal) +- Tell the human what the page is about (CTR signal) +- Distinguish from other pages on the same site (uniqueness signal) +- Earn the click against 9 other titles in the SERP + +A title that does all four wins on rankings AND clicks. A title that does only the first ranks but earns no clicks. A title that does only the last earns clicks but ranks badly. + +### Length + +- 50-60 characters is the safe range for most desktop and mobile SERPs. +- Longer titles get truncated (Google appends "..."). +- Truncation is not catastrophic if the most important words are in the first 50 characters. + +### Character priority + +The most important word (typically the primary query target) goes near the front. Secondary words and brand go at the end. + +``` +[Primary query target] | [Modifier or value prop] | [Brand] +``` + +Examples: + +| Bad | Better | +|---|---| +| "Welcome to Acme - your trusted partner in widgets since 1995" | "Widgets for industrial use - Acme" | +| "Acme Inc. - Best widgets - Buy online" | "Industrial widgets - free shipping - Acme" | +| "About us" | "About Acme - 25 years building industrial widgets" | + +### Patterns by page type + +#### Homepage + +``` +[Brand]: [One-line value prop] +``` + +Examples: +- "Notion: the all-in-one workspace for your notes and tasks" +- "Linear: built for modern software teams" +- "Acme Hardware: industrial widgets for builders" + +#### Category page + +``` +[Category name] - [Modifier or differentiator] | [Brand] +``` + +Examples: +- "Industrial widgets - in stock, free shipping | Acme" +- "Project management software for engineers | Linear" +- "Recipes by region - 1,000+ tested recipes | RecipeCo" + +#### Product / detail page + +``` +[Product name] - [Key benefit or spec] | [Brand] +``` + +Examples: +- "10mm steel widget - 50 lb capacity | Acme" +- "Linear Free - up to 10 users, unlimited issues | Linear" +- "Mediterranean lentil soup recipe | RecipeCo" + +#### Article / blog post + +``` +[Headline that promises value] - [Brand] +``` + +Examples: +- "How to choose an industrial widget supplier - Acme" +- "Linear vs Jira: 5 differences that actually matter - Linear" +- "Why your meta descriptions are getting rewritten - Search Engine Journal" + +The blog title is usually the H1 + brand. If the H1 is long, shorten for the title. + +#### Comparison / vs page + +``` +[Brand A] vs [Brand B]: [Differentiating angle] | [Your brand] +``` + +Examples: +- "Linear vs Jira: speed, opinions, and team size | Linear" +- "MongoDB vs PostgreSQL: when to pick which | Engineering Blog" + +#### Pricing page + +``` +[Brand] pricing - [What is included] | [Brand] +``` + +Examples: +- "Linear pricing - free forever for small teams | Linear" +- "Pricing - simple, transparent, no surprises | Acme" + +#### Geographic / location page + +``` +[Service] in [City], [State] | [Brand] +``` + +Examples: +- "Plumbing services in Austin, TX | Smith Plumbing" +- "Coworking in Brooklyn - day passes and memberships | WorkSpace" + +--- + +## Title rules and anti-patterns + +### Do + +- Put the primary query near the front +- Include brand at the end +- Use a separator that the SERP renders cleanly (`|`, `-`, `:`) +- Be specific (numbers, modifiers, segments earn attention) +- Match the H1 in spirit, not word-for-word + +### Do not + +- Repeat the primary query multiple times ("Widgets, industrial widgets, buy widgets - Widgets.com") +- Start with the brand on every page (homepage is the exception) +- Use ALL CAPS for emphasis +- Use clickbait phrasing that mismatches the page content +- Pad with filler words ("Welcome to," "Find the best," "Looking for") +- Append "Home" / "Default" / "Untitled" +- Leave it as the CMS default + +--- + +## Meta description patterns + +### The job of the meta description + +- Earn the click in the SERP +- Set expectations for what the page delivers +- Reinforce the primary query (Google bolds matched terms) + +The meta description is **not** a ranking signal directly. It is a CTR signal, which feeds back into ranking via behavioral signals. + +### Length + +- 140-160 characters. Longer gets truncated on most devices. +- Mobile truncates earlier than desktop. Front-load the value. + +### Structure + +Three moves in 1-3 sentences: + +1. **Promise the value.** What does the reader get if they click? +2. **Justify it.** Why is this credible? (Numbers, recency, specificity, authority.) +3. **Cue the action.** What should they expect to do or learn? + +Not every meta description does all three. The strongest do. + +### Examples + +| Bad | Better | +|---|---| +| "Welcome to our blog where we write about widgets." | "How to pick the right industrial widget for your project. 10 specs that matter, with a comparison chart." | +| "Acme Inc. is a leading provider of widgets and other products." | "Industrial widgets in 50+ sizes. Free shipping over $100. Same-day dispatch from Austin, TX." | +| "Click here to learn more about our pricing." | "Linear pricing: free forever for teams up to 10. Pro is $8/user/month. No setup fee. See plans and limits." | + +--- + +## Meta description patterns by page type + +### Homepage + +``` +[What the brand does, one sentence]. [The audience or use case]. [The differentiator or social proof]. +``` + +Example: "Modern issue tracking for software teams. Built for speed. Used by 5,000+ teams from startups to enterprise." + +### Category page + +``` +[What the category contains]. [The selection or differentiator]. [Trust or shipping signal]. +``` + +Example: "Industrial widgets in 50+ sizes from 10mm to 200mm. Free shipping over $100. In stock and ready to ship from Austin." + +### Product / detail page + +``` +[Product, with key spec]. [Use case]. [Trust signal or guarantee]. +``` + +Example: "10mm steel widget rated to 50 lb. Built for industrial assembly lines. 5-year warranty, free returns." + +### Article / blog post + +``` +[The promise of the article in one sentence]. [The substance or evidence]. [Optional: who it is for]. +``` + +Example: "How to choose between Linear and Jira: 5 specific differences in workflow, speed, and pricing. With screenshots and benchmarks. For engineering managers comparing the two." + +### Pricing page + +``` +[The headline pricing]. [What is included]. [Anti-friction language]. +``` + +Example: "Linear is free forever for teams up to 10. Pro plan starts at $8/user/month. No setup fee, cancel anytime." + +--- + +## Meta description rules + +### Do + +- Front-load the value +- Use the primary query naturally (Google bolds it) +- Include numbers, specifics, and proof points +- Match the page's actual content +- Write for humans (it is a sales line, not a ranking line) + +### Do not + +- Pad with marketing-speak ("revolutionary," "industry-leading") +- Repeat the title verbatim +- End mid-sentence +- Stuff keywords (Google will rewrite the description if it looks unnatural) +- Leave the CMS default +- Use the same description on multiple pages + +--- + +## When Google rewrites your meta description + +Google rewrites meta descriptions when it thinks its rewrite will earn more clicks. Common triggers: + +- The description does not match the query +- The description is too short, too generic, or stuffed +- The page content has clearly different value from the description +- The page is matched against a long-tail query the description does not address + +To avoid rewrites: + +- Match the description to the page's actual content +- Make sure the primary query appears naturally in the description +- Keep the description specific and current + +If Google rewrites your description and the rewrite is wrong (low CTR, misleading), tighten the description and consider adding `name="description"` plus alternative phrasings via `<meta property="og:description">` for parity. + +--- + +## CTR optimization tips (beyond pattern) + +- **Numbers earn attention.** "5 ways," "100+ examples," "in 10 minutes." +- **Year in title for evergreen-but-current content.** "(2026)" earns clicks in fast-moving categories. Update annually. +- **Brackets and parens are click-bait when overused, useful when accurate.** "[Free Template]," "(2026 update)." +- **Question titles work for some intents.** "How do I [task]?" earns clicks for how-to. +- **Comparison titles are click magnets.** "X vs Y: [angle]." +- **Promise-and-deliver framing.** Title promises a specific value; the page delivers it. + +--- + +## Title and description audit shortcut + +For any page, ask: + +1. Does the title contain the primary query in the first 30 characters? +2. Is the title under 60 characters? +3. Is the title unique on the site? +4. Does the meta description promise value, justify it, and read as a human-written sentence? +5. Is the meta description under 160 characters? +6. Has Google rewritten the description? (Check Search Console performance report.) + +If 4 of 6 are "no," the title or description is the highest-leverage fix on the page. + +--- + +## A/B testing titles and descriptions + +For high-traffic pages, A/B test alternates. Tools that support this: native CMS tools, edge workers, dedicated SEO testing platforms. + +Test one variable at a time (title length, vs comparison hook vs question form, etc.). Run for 2-4 weeks per variant. Measure CTR and downstream conversion, not just rank position. + +--- + +## Snippet appearance is not just title and description + +What the SERP shows can include: + +- The title and description (this guide) +- Sitelinks (Google-auto, can be encouraged via clean IA) +- Rich results from schema (recipe, FAQ, product, review) +- Breadcrumbs (improves CTR, requires breadcrumb schema) +- Author and date (article schema) +- Featured snippets (a separate optimization layer) + +Title and description are the foundation. Schema and sitelinks are leverage on top. diff --git a/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md b/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md new file mode 100644 index 0000000..c1cb198 --- /dev/null +++ b/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md @@ -0,0 +1,250 @@ +--- +name: seo-rank-tracking +description: "Set up and run rank tracking using Ahrefs MCP: pick the right keywords to track, segment them by purpose, set baselines, and define alert thresholds. Use this skill when starting a new tracking project, baselining for a campaign, choosing what to monitor, or building a rank reporting cadence. Triggers on rank tracking, keyword tracking, monitor rankings, track positions, what should we track, ranking dashboard, baseline rankings, alert thresholds. Also triggers when a stakeholder wants weekly or monthly ranking visibility." +category: seo-audit-suite +catalog_summary: "Setup, baseline, segmentation, alerting, dashboarding" +display_order: 7 +--- + +# SEO Rank Tracking + +Set up and run an ongoing rank tracking program using Ahrefs MCP data. Stack-agnostic. Produces a tracked keyword set, segmentation, baseline, alert thresholds, and a review cadence. + +--- + +## When to use + +- Starting rank tracking for a new property or section +- Baselining before a campaign, content launch, or major site change +- Deciding what keywords are worth tracking +- Setting up a ranking dashboard for stakeholders +- Establishing alert thresholds for ranking drops +- Reviewing whether the current tracked set is still meaningful + +## When NOT to use + +- Keyword discovery (use `seo-keyword`) +- Competitor keyword analysis (use `seo-keyword-gap-audit`) +- Diagnosing a ranking change that already happened (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) + +--- + +## Required inputs + +- Target property +- Target market and language +- Business priorities (which segments matter) +- Existing ranked keywords (Ahrefs Site Explorer) +- Stakeholder reporting cadence (weekly, monthly, quarterly) +- Confirmation Ahrefs MCP and Rank Tracker access + +--- + +## The framework: tracking taxonomy + +A good tracked keyword set has structure. Random keyword lists produce noisy dashboards. Segmented keyword sets produce signal. + +Group every tracked keyword into one of four buckets. + +### Bucket 1: Brand keywords + +Queries containing the brand name (and major variants and misspellings). + +Why track: + +- Detect brand visibility issues +- Catch competitors bidding on the brand +- Spot reputation problems early + +Volume in this bucket: typically 10-30 keywords for most brands. + +Healthy signal: position 1 for all variants. Anything else is investigate-worthy. + +### Bucket 2: Money keywords + +Queries that drive (or should drive) revenue: high-intent transactional and evaluation-stage queries directly tied to the business model. + +Why track: + +- These are the keywords that pay the bills +- Movement here directly affects revenue +- Stakeholders care most about these + +Volume in this bucket: 30-100 keywords for most properties. More for ecommerce. + +Healthy signal: top 3-5 positions. Watch for position drift in either direction. + +### Bucket 3: Opportunity keywords + +Queries the property is currently ranking on page 2-3 (positions 11-30) with potential to break into top 10. + +Why track: + +- These are the active growth bets +- Movement reflects whether content investment is working +- Quick wins typically come from this bucket + +Volume in this bucket: 50-200 keywords typically. + +Healthy signal: trending toward page 1 over a 90-day window. + +### Bucket 4: Competitor benchmark keywords + +A representative sample of head and torso queries shared with the competitor set, used to track relative position over time. + +Why track: + +- Measure share of voice +- Spot competitor gains in real time +- Provide industry context for movement + +Volume in this bucket: 50-150 keywords. + +Healthy signal: relative position improving or holding within a defined competitive band. + +--- + +## Selection criteria + +### Brand bucket + +- Brand name (exact) +- Brand name + product or service +- Brand name common misspellings +- Brand name + "review", "vs", "alternative" +- Brand-owned product names if relevant + +### Money bucket + +- Top 20 ranked keywords by traffic value (Ahrefs Site Explorer) +- Top transactional queries from Search Console with non-trivial impressions +- Conversion-driving queries identified in analytics +- Strategic head terms from `seo-keyword-gap-audit` output + +Quality over volume. 50 well-chosen money keywords beats 500 noisy ones. + +### Opportunity bucket + +- All keywords currently ranking positions 11-30 with monthly volume above a relevance-appropriate threshold +- Queries with rising impression volume in Search Console +- Output from the keyword gap audit's quick wins list + +Refresh this bucket quarterly. Opportunity is a moving target. + +### Competitor benchmark bucket + +- Keywords where 3+ competitors rank in top 20 +- Mix of head, torso, and informational queries +- Sized to represent the broader category + +This bucket is for relative comparison, not absolute targeting. + +--- + +## Segmentation beyond buckets + +Tag every tracked keyword on additional dimensions for filtering: + +| Tag | Purpose | +| --- | --- | +| Topic or pillar | Group by editorial theme | +| Funnel stage | TOFU, MOFU, BOFU | +| Content type expected | Article, product page, calculator, etc. | +| Page mapped | Which URL is targeting this query | +| Country and language | For multi-market sites | +| Device | Desktop, mobile | +| SERP feature presence | Featured snippet, AI overview, video, etc. | + +Tagging up front pays off when filtering reports later. + +--- + +## Baselines + +Capture the starting state on day one. + +For each keyword, record: + +- Current position +- Current SERP composition (top 10 domains, dominant content type, SERP features present) +- Current click-through rate at that position (from Search Console if available) +- Date of baseline + +Baselines are the reference for measuring future movement. Without one, every dashboard is just current state. + +--- + +## Alert thresholds + +Not every position change deserves attention. Set thresholds that filter noise. + +### Default thresholds + +| Bucket | Alert if | +| --- | --- | +| Brand | Position drops below 1 for any tracked variant | +| Money | Position drops by 5+ places, or out of top 10 | +| Opportunity | Position rises into top 10 (positive alert), or drops past 30 | +| Competitor benchmark | Aggregate share-of-voice changes by 10%+ | + +Adjust thresholds based on volatility of the niche. High-competition spaces need looser thresholds to reduce false alarms. + +### Alert routing + +- Brand alerts: notify SEO lead and brand manager immediately +- Money alerts: notify SEO lead within a daily digest +- Opportunity alerts: weekly summary +- Competitor alerts: monthly summary + +--- + +## Workflow + +1. **Define scope.** Target property, market, language, stakeholders. +2. **Pull starting data.** Existing ranked keywords, Search Console queries, competitor overlap. +3. **Build the tracked set.** 4 buckets, 200-500 total keywords for most properties. +4. **Segment with tags.** Topic, funnel stage, page mapped, etc. +5. **Configure tracking.** Set up Ahrefs Rank Tracker projects with tags and locations. +6. **Capture baseline.** Day-one positions and SERP composition. +7. **Define alert thresholds.** By bucket. Wire to notification system. +8. **Build the dashboard.** See [`references/dashboard-template.md`](references/dashboard-template.md). +9. **Set the cadence.** Weekly review of money + brand. Monthly review of all. Quarterly rebuild of opportunity bucket. +10. **Iterate.** Drop dead keywords. Add new ones. Recalibrate thresholds based on noise. + +--- + +## Failure patterns + +- **Tracking too many keywords.** A 5,000-keyword tracker is unreadable. Pick fewer, watch closer. +- **Tracking too few.** A 30-keyword tracker misses the picture. Most properties need 200-500. +- **No segmentation.** Untagged tracked keywords produce dashboards that cannot be filtered. +- **No baseline.** Without day-one snapshots, "did the campaign work" becomes unanswerable. +- **Alert fatigue.** Loose thresholds produce too many alerts. Stakeholders stop reading. Tighten. +- **Set and forget.** Tracked keyword sets need quarterly review. Opportunity moves. Money keywords shift. +- **Conflating position with traffic.** A position-1 keyword with no clicks is worse than a position-5 keyword with steady traffic. Layer in CTR and clicks data. +- **Single-device tracking on a mobile-dominant business.** Track the device that matches the audience. +- **Tracking aggregate position only.** Aggregate position averages can hide important movement in specific buckets. Always show by bucket. +- **Reporting absolute position without context.** "We are position 4" means nothing. "Up from position 11 over 60 days" means something. + +--- + +## Output format + +A rank tracking setup document with: + +1. **Tracking charter.** Property, scope, stakeholders, cadence. +2. **Tracked keyword set.** All keywords with bucket and tag assignments. +3. **Baseline snapshot.** Position, SERP composition, CTR per keyword. +4. **Alert configuration.** Thresholds by bucket, routing. +5. **Dashboard layout.** What charts, what filters, what is visible. +6. **Review cadence.** Weekly, monthly, quarterly responsibilities. +7. **Methodology notes.** Country and device settings, refresh frequency, data caveats. + +Plus a recurring rank report at the chosen cadence (typically weekly or monthly). + +--- + +## Reference files + +- [`references/dashboard-template.md`](references/dashboard-template.md) - Template for the rank tracking dashboard layout, including the recurring report structure for weekly and monthly cadences. diff --git a/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md b/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md new file mode 100644 index 0000000..f3ec228 --- /dev/null +++ b/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md @@ -0,0 +1,273 @@ +# Rank tracking dashboard template + +A template for the rank tracking dashboard and the recurring weekly and monthly rank reports. + +--- + +## Dashboard layout principle + +The dashboard should answer three questions in order: + +1. **Are we okay?** (brand and money buckets) +2. **Are we growing?** (opportunity bucket) +3. **How do we compare?** (competitor benchmark bucket) + +Anything that does not serve those three questions is clutter. + +--- + +## Section 1: Brand health (top of dashboard) + +Single panel. Status indicator. Should be glanceable. + +Display: + +- Position 1 status across all brand variants (count: e.g., "27 of 30 variants at position 1") +- Any brand variant not at position 1, listed below the status + +Alert color coding: + +- Green: all brand variants at position 1 +- Yellow: 1-3 variants below position 1 +- Red: 4+ variants below position 1, or any branded query showing competitor in top 3 + +--- + +## Section 2: Money keyword health + +The keystone section. Show: + +### Headline metric + +- Average position across all money keywords (current vs 30 days ago vs 90 days ago) +- Count of money keywords in top 3, top 10, top 20, beyond + +### Movement table + +Top 10 movers (positive and negative) over the chosen window: + +| Keyword | Bucket | Current position | Change | Page mapped | +| --- | --- | --- | --- | --- | +| [keyword] | Money | 4 | +6 | /products/[slug] | + +### Distribution chart + +Stacked bar showing how many money keywords are at each position band: + +- Top 3 +- Positions 4-10 +- Positions 11-20 +- Positions 21-50 +- Beyond 50 or unranked + +Track this distribution over time. Improving SEO shifts the distribution upward. + +--- + +## Section 3: Opportunity progress + +The growth section. + +### Headline metric + +- Count of opportunity keywords that broke into top 10 over the chosen window +- Count that fell out of opportunity range (past 30 or to top 10) +- Net opportunity bucket size (with quarterly refresh) + +### Top breakthroughs + +Keywords that crossed from positions 11-30 into top 10: + +| Keyword | Previous position | Current position | Page mapped | Likely cause | +| --- | --- | --- | --- | --- | +| [keyword] | 14 | 7 | /guides/[slug] | Refresh shipped 30 days ago | + +### Top regressions + +Keywords moving the wrong way: + +| Keyword | Previous position | Current position | Page mapped | Likely cause | +| --- | --- | --- | --- | --- | + +--- + +## Section 4: Competitor benchmark + +### Share of voice + +Aggregate position-weighted share of voice across the benchmark keyword set: + +| Property | SOV (current) | SOV (90 days ago) | Change | +| --- | --- | --- | --- | +| [Target] | 18% | 14% | +4 | +| [Competitor A] | 22% | 23% | -1 | +| [Competitor B] | 15% | 16% | -1 | +| [Competitor C] | 12% | 10% | +2 | + +### Head-to-head + +For top 20 strategic head terms, show position for target and each competitor side by side. + +--- + +## Section 5: SERP feature awareness + +Dashboard should call attention to SERP composition changes. + +Track: + +- Featured snippets owned by target (count, change) +- AI overviews appearing on target's tracked queries (count, change) +- Featured snippets owned by competitors on tracked queries +- New SERP feature types appearing (video carousels, image packs, etc.) + +A position-1 ranking that loses its featured snippet can lose 30%+ clicks while position stays the same. + +--- + +## Section 6: Filters + +The dashboard must be filterable by: + +- Bucket (brand, money, opportunity, benchmark) +- Topic or pillar tag +- Funnel stage tag +- Country and language +- Device +- Page mapped (URL) + +Filters let stakeholders drill from "the dashboard" to "my section". + +--- + +## Weekly report template + +The weekly report is for the SEO team and immediate stakeholders. + +``` +# Weekly rank report: [property] +**Week of:** [date range] +**Prepared:** [date] + +## Brand health + +[Green/Yellow/Red indicator] +[1-2 sentences. Anything not at position 1.] + +## Money keyword movement + +- Average position: [N] (vs [N] last week, [N] 90 days ago) +- Top 3 count: [N] (vs [N] last week) +- Top 10 count: [N] (vs [N] last week) + +### Notable gainers + +| Keyword | Previous | Current | Change | +| --- | --- | --- | --- | + +### Notable decliners + +| Keyword | Previous | Current | Change | +| --- | --- | --- | --- | + +## Opportunity progress + +- Breakthroughs to top 10: [N] +- Regressions out of opportunity range: [N] + +## Alerts triggered this week + +| Date | Keyword | Bucket | Alert | Action taken | +| --- | --- | --- | --- | --- | + +## Hypothesis or call-out + +[1-2 sentences on the most interesting movement and what it suggests.] +``` + +Length: 1 page. Readable in 3 minutes. + +--- + +## Monthly report template + +The monthly report is for broader stakeholders. Add narrative. + +``` +# Monthly rank report: [property] +**Month:** [month] +**Prepared:** [date] + +## Headline + +[1 paragraph. State of organic visibility.] + +## Brand and money keywords + +- Brand health: [status, with any concerns] +- Money keyword distribution: [chart description, key shifts] +- Notable wins: [bullet list] +- Notable concerns: [bullet list] + +## Opportunity progress + +- Breakthroughs to top 10 this month: [N] +- Quarterly target progress: [N of target N] +- Top opportunities watched + +## Competitive landscape + +- Share of voice: [target % vs competitor set] +- Notable competitor movement +- New SERP features observed + +## Themes for the month + +[3-5 themes from the data. Each is 1 paragraph.] + +## Recommendations for next month + +[Specific actions with owners and expected outcomes.] + +## Methodology + +- Tracking set: [N] keywords across [N] buckets +- Country: [list] +- Device: [list] +- Last refresh: [date] +- Data caveats: [list] +``` + +Length: 4-8 pages. + +--- + +## Quarterly rebuild + +Every 90 days, audit the tracked set itself. + +### Rebuild checklist + +- [ ] Brand bucket: any new product names, brand variants, or PR-driven query patterns? +- [ ] Money bucket: any keywords no longer aligned with current product or content focus? +- [ ] Money bucket: any new high-value queries identified by analytics or Search Console? +- [ ] Opportunity bucket: rebuild from current page 2-3 rankings; remove keywords that broke into top 10 (move to money) or fell past 30 (drop) +- [ ] Benchmark bucket: still representative of competitive landscape? +- [ ] Tags: any new pillars or topics that need tagging? +- [ ] Alert thresholds: too noisy? too quiet? recalibrate +- [ ] Reporting cadence: still useful at this frequency? + +Document the rebuild in a short changelog so historical comparisons remain interpretable. + +--- + +## Common dashboard pitfalls + +- **Single big number.** "Average position" alone hides bucket-level signal. +- **No trend lines.** Current state without trend is half the picture. +- **No segmentation visible.** A dashboard that cannot be filtered cannot answer follow-up questions. +- **Showing every keyword.** Stakeholders cannot read 500 rows. Show distributions and movers. +- **Hiding SERP features.** Feature changes cause invisible click drops. Always show them. +- **Showing only target, not competitors.** Movement is meaningless without context. +- **Static data.** A rank dashboard updated monthly is too slow for fast-moving niches. Match refresh to volatility. +- **No annotations.** Mark deploy dates, content launches, and known algorithm updates on charts so movement has context. diff --git a/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md b/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md new file mode 100644 index 0000000..a47c414 --- /dev/null +++ b/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md @@ -0,0 +1,184 @@ +--- +name: seo-site-health-audit +description: "Triage technical SEO findings from Ahrefs Site Audit (and similar crawlers) by SEO impact, not just severity. Use this skill when reviewing crawl results, prioritizing technical fixes, scoping a technical SEO sprint, or after running any site-wide crawl. Triggers on site audit results, technical fix list, crawl errors, technical SEO triage, prioritize technical issues, what should we fix first, broken links, redirect chains. Also triggers when a long list of crawler issues is creating decision paralysis." +category: seo-audit-suite +catalog_summary: "Triage Ahrefs Site Audit findings by SEO impact, not severity" +display_order: 6 +--- + +# SEO Site Health Audit + +Triage technical SEO findings from Ahrefs Site Audit (or any equivalent crawler) by impact on rankings and traffic, not by raw issue count or severity label. Stack-agnostic. Produces a prioritized backlog of fixes mapped to business impact. + +--- + +## When to use + +- After running an Ahrefs Site Audit or other site-wide crawl +- Reviewing a long list of technical issues and needing to prioritize +- Scoping a technical SEO sprint +- Pre-launch or post-migration technical verification +- Quarterly technical health check +- When developer time is limited and you must pick the highest-leverage fixes + +## When NOT to use + +- Running the crawl itself (use the crawler tool directly) +- Diagnosing specific traffic drops (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) +- Pure technical strategy or schema design (use `seo-technical`) + +--- + +## Required inputs + +- Crawl results from Ahrefs Site Audit (or equivalent) +- Search Console coverage and Core Web Vitals data +- Property's organic traffic profile (which pages drive traffic) +- Stakeholder time and developer capacity available +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: triage by SEO impact, not severity + +Crawlers label issues "critical", "warning", "notice". These labels are useful but not sufficient. Two issues both labeled "critical" can have wildly different actual impact on the property. + +Triage on three axes. + +### Axis 1: Page-level traffic impact + +Does the issue affect a page that drives meaningful organic traffic, or one that does not? + +A "critical" issue on a tag archive with zero traffic is lower priority than a "warning" on a top-10-traffic landing page. + +Tier the affected URLs: + +- **Tier 1:** Top 10% of pages by organic traffic +- **Tier 2:** Pages that rank but do not yet drive significant traffic (page 2-3 results) +- **Tier 3:** Pages that exist but do not rank meaningfully + +A fix on Tier 1 is worth 10x a fix on Tier 3 in most cases. + +### Axis 2: Mechanism of impact + +Does the issue actually move rankings or traffic? Some "critical" issues are aesthetic or theoretical. + +Categories of real impact: + +| Mechanism | Examples | +| --- | --- | +| Indexability | Accidental noindex, robots.txt blocks, canonical errors, X-Robots-Tag | +| Crawlability | Crawl traps, infinite redirects, 5xx errors, slow server response | +| Renderability | JS errors blocking critical content, blocked resources | +| Core Web Vitals | LCP, INP, CLS in the poor band | +| Structured data | Errors on rich-result-eligible pages (not warnings) | +| Internal link integrity | 404s on internally linked URLs, broken canonicals | +| Hreflang | Errors on multilingual deployments | + +Categories of low or theoretical impact: + +| Type | Why it is lower priority | +| --- | --- | +| Title tag length warnings | Not a ranking factor in itself | +| Meta description length | Not a ranking factor | +| H1 absence on low-traffic pages | Marginal impact | +| Alt text missing on decorative images | Accessibility issue, low SEO impact | +| Schema warnings (not errors) | Often best-practice nudges, not ranking issues | + +Fix the high-mechanism categories first. + +### Axis 3: Effort + +Some issues are 5-minute fixes. Some are multi-sprint projects. + +- **S (small):** Configuration change, single template edit, sitemap regeneration +- **M (medium):** Theme or component change, redirect map work, template-level fixes +- **L (large):** Architecture change, re-platform, framework migration, schema overhaul + +--- + +## The triage matrix + +Combine the three axes into a priority score. + +| Tier | Mechanism | Effort | Priority | +| --- | --- | --- | --- | +| Tier 1 | High mechanism | S | P0 (do this week) | +| Tier 1 | High mechanism | M | P1 (do this sprint) | +| Tier 1 | High mechanism | L | P2 (plan as project) | +| Tier 1 | Low mechanism | S | P3 (batch when convenient) | +| Tier 1 | Low mechanism | M-L | Park unless evidence emerges | +| Tier 2 | High mechanism | S | P1 | +| Tier 2 | High mechanism | M-L | P2 | +| Tier 3 | High mechanism | S | P3 | +| Tier 3 | Anything else | Anything | Park | + +P0-P1 work earns the team's attention. P2 goes on the roadmap. P3 batches into routine maintenance. Park is honest about deprioritization. + +--- + +## Workflow + +1. **Pull the crawl results.** Ahrefs Site Audit + Search Console + Core Web Vitals. +2. **Tier the URLs.** Use organic traffic data. Tag every affected URL as Tier 1, 2, or 3. +3. **Categorize each issue by mechanism.** High or low impact mechanism. +4. **Estimate effort per fix type.** Group similar fixes into one effort estimate. +5. **Apply the triage matrix.** Assign P0-P3 or Park. +6. **Cluster the fixes.** Group fixes that share an effort: one template change can resolve hundreds of issues. +7. **Build the backlog.** P0 first, P1 next, etc. Add fix descriptions, owners, expected impact. +8. **Add measurement.** What metric will confirm the fix worked? Define before shipping. +9. **Hand off.** Output feeds the development backlog and `seo-audit-orchestration`. +10. **Re-crawl after fixes.** Confirm resolution. Update the backlog. + +--- + +## High-leverage clusters worth looking for + +These patterns commonly produce outsized impact when fixed: + +- **Wholesale redirect chain cleanup.** One sitemap update plus internal link updates can resolve thousands of "redirect chain" issues at once. +- **Accidental noindex on a template.** A single line of code change can re-index hundreds or thousands of pages. +- **Sitemap freshness pipeline.** A broken sitemap regeneration job affects every issue that depends on Search Console seeing the right URLs. +- **Canonical inconsistencies on faceted navigation.** A template-level canonical fix can resolve duplicate content issues across an entire ecommerce category tree. +- **Robots.txt restored.** A reverted production robots.txt can recover a sitewide drop in days. +- **Hreflang block fix.** One template change resolves hreflang issues across the whole multilingual site. +- **Image optimization at the asset pipeline.** Fixing the build process resolves thousands of individual asset issues. + +When you spot one of these, prioritize even if individual issues look small. The cluster impact is large. + +--- + +## Failure patterns + +- **Severity worship.** Treating every "critical" label as truly critical. Many are not. Triage by mechanism and traffic impact. +- **Counting issues.** Reporting "we fixed 1,200 issues" without showing traffic or ranking impact wastes engineering credibility. +- **Skipping the tiering.** Fixing 100 Tier-3 issues before 5 Tier-1 issues is busy work. +- **Single-issue fixes.** Most issues come in clusters. Fixing one redirect chain when 800 share the same root cause is the wrong unit of work. +- **No re-crawl.** "Fixed" without verification leaves doubt. Always re-crawl after major fixes. +- **Ignoring Search Console.** Ahrefs sees what its crawler finds. Search Console reflects what Google actually sees and indexes. Use both. +- **Treating Core Web Vitals like a checklist.** CWV is field data, not lab data. Optimize for real-user experience, not synthetic scores. +- **Fixing low-mechanism issues for show.** A clean technical report with no traffic gain helps no one. +- **Not measuring.** Define the metric that proves the fix worked before fixing. + +--- + +## Output format + +A site health triage document with: + +1. **Summary.** Total issues, top 3 fix clusters, expected impact. +2. **URL tiering.** How URLs were classified and counts per tier. +3. **Issue categorization.** Counts by mechanism category, by tier, by priority band. +4. **Prioritized backlog.** P0-P3 ordered. Each item has: issue, affected URLs, fix description, effort, expected impact, owner. +5. **Fix clusters.** Groups of issues that share a fix. Highest leverage at the top. +6. **Measurement plan.** Per fix or cluster, what proves it worked. +7. **Methodology.** Crawler used, date, scope, caveats. + +Length: 5-12 pages plus a backlog spreadsheet. + +--- + +## Reference files + +- [`references/issue-impact-table.md`](references/issue-impact-table.md) - Mapping table of common crawler issues to mechanism impact and typical fix effort, plus the triage matrix in detailed form. diff --git a/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md b/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md new file mode 100644 index 0000000..672e1b0 --- /dev/null +++ b/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md @@ -0,0 +1,190 @@ +# Issue impact table + +A reference table mapping common crawler-reported issues to their actual SEO impact mechanism and typical fix effort. Use it to triage Ahrefs Site Audit (or any equivalent) findings without treating every "critical" label as equally important. + +--- + +## How to use + +For each issue type from the crawler: + +1. Look up the mechanism and effort here. +2. Combine with URL tier (Tier 1 = top 10% by traffic) using the triage matrix. +3. Assign priority band P0-P3 or Park. + +Mechanism tiers: + +- **HIGH:** Direct effect on indexing, rankings, or Core Web Vitals. +- **MEDIUM:** Indirect effect via crawl, equity flow, or user signals. +- **LOW:** Best practice nudge or cosmetic. Real impact is usually marginal. + +--- + +## Indexability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Page returns noindex on indexed URL | HIGH | S | Template fix usually resolves at scale | +| Robots.txt blocks important URLs | HIGH | S | One file edit | +| X-Robots-Tag header set to noindex | HIGH | S-M | Often a CDN or hosting config | +| Canonical points to non-canonical URL | HIGH | M | Often template-level | +| Canonical points to redirect | HIGH | S | Update canonical to final URL | +| Self-canonical missing on important page | MEDIUM | S | Add to template | +| URL not in sitemap but indexed | MEDIUM | S | Regenerate sitemap | +| URL in sitemap but noindexed | HIGH | S | Decide indexability, fix one or the other | + +--- + +## Crawlability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| 5xx errors on URLs | HIGH | M-L | Investigate hosting and app errors | +| 4xx errors on internally linked URLs | HIGH | M | Fix links or add redirects | +| Redirect chain (3+ hops) | MEDIUM | M | Update final destination in links | +| Redirect loop | HIGH | S | Fix immediately | +| Slow time to first byte | MEDIUM | M-L | Hosting, caching, or app changes | +| Crawl trap (infinite parameter combinations) | HIGH | M | Robots disallow patterns or canonical | +| Orphan page (indexed but no internal links) | MEDIUM | S-M | Add internal links or noindex | +| Excessive redirects in sitemap | MEDIUM | S | Update sitemap to final URLs | +| 301 used where 302 intended (or vice versa) | LOW-MEDIUM | S | Audit and fix per case | + +--- + +## Renderability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Critical content rendered only via JS (with crawler issues) | HIGH | L | Server render, prerender, or hybrid | +| Blocked CSS or JS resources | MEDIUM | S | Allow in robots.txt | +| Excessive client-side dependencies for above-fold content | MEDIUM | M-L | Code splitting and SSR | +| Render mismatch (HTML differs from rendered DOM in important ways) | HIGH | M-L | Investigate framework rendering | + +--- + +## Core Web Vitals (field data) + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| LCP > 4 seconds (poor band) on Tier 1 pages | HIGH | M-L | Image optimization, caching, render path | +| LCP 2.5-4 seconds (needs improvement) | MEDIUM | M | Lower priority but still worth fixing | +| INP > 500ms (poor band) | HIGH | M-L | JS optimization, hydration deferral | +| CLS > 0.25 (poor band) | HIGH | S-M | Reserve space for images, ads, embeds | +| CLS 0.1-0.25 | LOW-MEDIUM | S | Often quick wins | + +CWV thresholds are based on the 75th percentile of real-user data per URL group. + +--- + +## Structured data issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Schema error blocking rich result eligibility | HIGH | S-M | Fix the offending field | +| Schema warning (recommended field missing) | LOW | S | Optional improvement | +| Wrong schema type for content | MEDIUM | S | Replace with correct type | +| Schema markup but content does not match | HIGH | M | Either fix schema or fix content (Google penalizes mismatch) | +| Duplicate schema across multiple types | LOW-MEDIUM | S | Clean up duplicates | + +Pages eligible for rich results (FAQ, How-to, Recipe, Product, etc.) deserve high priority. Schema on pages without rich result eligibility is lower priority. + +--- + +## Internal link integrity + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Internal link to 404 | MEDIUM | S | Update or remove link | +| Internal link to redirect | LOW | S | Update to final URL when batching | +| Internal link with empty anchor | LOW | S | Add descriptive anchor | +| Page receiving zero internal links (orphan) | MEDIUM | S-M | Add links or reassess if page should exist | +| Important page with very few internal links | MEDIUM | S | Identify and add link points | +| Footer or sitewide internal link to broken URL | MEDIUM | S | High visibility, fix quickly | + +--- + +## Hreflang (multilingual sites) + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing return tag (hreflang reciprocity) | HIGH | M | Template fix often resolves at scale | +| Hreflang points to redirected URL | MEDIUM | S | Update to final URL | +| Hreflang points to noindexed URL | HIGH | S | Decide indexability or remove hreflang | +| Hreflang language code malformed | HIGH | S | Use ISO 639-1 + ISO 3166-1 alpha-2 | +| Mixing x-default and specific tags incorrectly | MEDIUM | S | Audit pattern across site | + +Multilingual sites with broken hreflang often see the wrong locale rank in the wrong market. Real ranking impact. + +--- + +## On-page elements + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing title tag | MEDIUM | S | Add via template | +| Duplicate title tag across many pages | MEDIUM | S-M | Template fix or unique-by-default | +| Missing meta description | LOW | S | Affects CTR, not ranking | +| Duplicate meta descriptions | LOW | S | Affects CTR, not ranking | +| Missing H1 on Tier 1 page | MEDIUM | S | Add to template | +| Missing H1 on Tier 3 page | LOW | S | Park unless trivial to fix | +| Multiple H1s | LOW | S | Modern HTML allows; rarely a real issue | +| Title or H1 that does not match content topic | MEDIUM | S | Audit content and update | + +--- + +## Image issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing alt text on content images | LOW (SEO), HIGH (accessibility) | S | Important for accessibility regardless | +| Missing alt text on decorative images | LOW | S | Use empty alt="" | +| Image weight (large file size) on Tier 1 page | HIGH | M | Asset pipeline fix at scale | +| Image format not modern (no WebP/AVIF) | MEDIUM | M | Pipeline change | +| Image lazy loading missing | MEDIUM | S | Add `loading="lazy"` to off-screen images | +| Hero image lazy loaded | MEDIUM | S | Should be `loading="eager"` for LCP | + +--- + +## Security and trust + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Mixed content (HTTPS page loading HTTP resources) | MEDIUM | S | Update resource URLs | +| Expired or misconfigured SSL | HIGH | S | Fix immediately | +| HSTS missing | LOW | S | Best practice | +| Internal links use HTTP, page is HTTPS | LOW | S | Update links to relative or HTTPS | + +--- + +## Cluster opportunities + +When you see multiple issues from the same root cause, treat as one fix: + +| Cluster signal | Single fix | +| --- | --- | +| Hundreds of "redirect chain" warnings | Update internal links and sitemap to final URLs | +| Sitewide "missing canonical" | Add canonical to base template | +| Mass "noindex on indexable URL" | Audit template-level meta tag | +| Many "page not in sitemap" | Regenerate sitemap from canonical URL list | +| Many slow LCP pages with same image pattern | Optimize image pipeline once | +| Many hreflang errors with same pattern | Template-level hreflang fix | +| Many H1 issues on archive pages | Theme or template change | + +Always look for clusters before fixing one-off. Cluster fixes are 10-100x more efficient. + +--- + +## Park or skip + +These rarely deserve dedicated work even when flagged: + +- Title tag length warnings (within reason; only fix if truncation visibly hurts CTR on a Tier 1 page) +- Meta description length warnings (same logic) +- "URL contains uppercase" if redirects already handle it +- "URL contains underscore" if URLs are stable and ranking +- Trailing slash inconsistency if redirects handle it +- Schema warnings (not errors) on pages with no rich result eligibility +- HTML validation issues that do not affect rendering or indexing +- Old browser-specific issues (IE-era) + +Park them. Document why. Move on. diff --git a/dist/pi/.agents/skills/seo-technical/SKILL.md b/dist/pi/.agents/skills/seo-technical/SKILL.md new file mode 100644 index 0000000..ef9c358 --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/SKILL.md @@ -0,0 +1,154 @@ +--- +name: seo-technical +description: "Run a comprehensive technical SEO audit covering crawlability, indexability, rendering, site architecture, structured data, page experience, security, and internationalization. Use this skill whenever the user asks about technical SEO, crawl issues, indexing problems, sitemaps, robots.txt, canonical tags, schema markup, page speed, Core Web Vitals, hreflang, redirects, or site-wide search performance. Triggers on technical SEO, site audit, crawlability, indexability, sitemap, robots.txt, canonical, redirect chain, schema, JSON-LD, Core Web Vitals, page speed, hreflang, mobile usability, HTTPS, security headers, render-blocking, JavaScript SEO. Also triggers when a site has indexing problems, traffic drops, or migration concerns, even if 'technical SEO' is not said explicitly." +category: seo-foundation +catalog_summary: "Crawlability, indexability, rendering, schema, page experience" +display_order: 2 +--- + +# Technical SEO + +Audit and fix the layer beneath the content: how search engines crawl, render, index, and trust a site. Stack-agnostic. + +--- + +## When to use + +- Site-wide audit before or after a migration +- Investigating indexing or ranking drops +- Setting up SEO foundations on a new site +- Auditing Core Web Vitals or page experience signals +- Fixing crawl waste, redirect chains, or canonical issues +- Setting up multilingual or multi-regional sites + +## When NOT to use + +- Single-page on-page optimization (use `seo-onpage`) +- Keyword strategy or content planning (use `seo-keyword`) +- Competitor backlink or SERP analysis (use `seo-competitor`) +- Pure performance optimization without SEO context (use `performance-optimization`) + +--- + +## Required inputs + +- The site URL or staging URL +- Access to (at minimum) view the rendered HTML, robots.txt, and sitemap +- Ideally: search console access, server logs, and a crawler + +If the site is large (10K+ URLs), confirm whether the audit is a full crawl or a sample. + +--- + +## The framework: 6 layers + +Technical SEO has six layers, stacked. A failure in a lower layer breaks everything above it. + +### 1. Crawlability +Can search engines access the URLs? + +- robots.txt does not block important paths +- No accidental `noindex` on indexable pages +- No accidental `disallow` patterns blocking CSS or JS (rendering breaks) +- Sitemap is present, returns 200, and lists canonical URLs only +- Sitemap is referenced in robots.txt +- No infinite spaces (faceted nav generating endless URLs) +- Crawl budget is not wasted on low-value URLs + +### 2. Indexability +Of crawlable URLs, which should be indexed? + +- One canonical URL per piece of content (no duplicates) +- Canonical tags self-reference on canonical pages +- `noindex` on staging, search results, filter pages, thank-you pages, internal admin +- No mixed signals (canonical pointing one way, sitemap another, internal links a third) +- Pagination handled correctly (rel=next/prev is deprecated, but consistent canonicals matter) +- Parameter handling deliberate (UTM, session IDs, sort orders) + +### 3. Rendering +Does the rendered HTML match what crawlers see? + +- Critical content visible without JavaScript (or properly server-rendered) +- For SPAs: confirm Googlebot sees the rendered content (test with the URL Inspection tool) +- No cloaking (showing different content to bots vs users) +- Lazy-loaded content has proper loading attributes +- Hydration errors do not strip content from the rendered DOM + +### 4. Site architecture +Is the site structured for both users and crawlers? + +- Clear URL hierarchy that mirrors site structure +- Important pages reachable in 3 clicks or fewer from the homepage +- Internal linking distributes authority logically +- Breadcrumb navigation present and marked up with schema +- No orphan pages (pages with no internal links) +- No redirect chains (one redirect max) +- No 4xx errors on internally-linked URLs + +### 5. Structured data and signals +Does the site speak crawler language? + +- Schema.org markup on appropriate page types +- JSON-LD format (preferred over microdata) +- Validates in the Rich Results Test +- Organization or LocalBusiness schema on the homepage or about page +- BreadcrumbList schema on nested pages +- Author and publisher schema linked correctly on content pages +- llms.txt present at the root (for AI crawlers, see `seo-aeo-geo`) + +### 6. Page experience and security +Does the site meet the page experience baseline? + +- HTTPS on all pages, no mixed content +- HSTS header set +- Core Web Vitals pass (LCP, INP, CLS within thresholds) +- Mobile-friendly (responsive, no horizontal scroll, tap targets sized correctly) +- No intrusive interstitials on mobile +- Stable URL structure (no random URL changes between deploys) +- 404 pages return 404, not 200 with "page not found" content (soft 404) + +--- + +## Workflow + +1. **Define scope.** Whole site, a subfolder, a migration check, or a specific issue. +2. **Confirm access.** What can you actually see (HTML, robots, sitemap, search console, server logs, staging)? +3. **Crawl.** Use a crawler to enumerate URLs and statuses. Sample if the site is huge. +4. **Run the 6-layer framework.** Score each, note specific issues with example URLs. +5. **Cross-reference.** Search console for what's actually indexed. Compare to sitemap and crawl output. +6. **Prioritize.** Critical (blocks indexing or causes traffic loss), Important (suboptimal), Nice-to-have (polish). +7. **Write the report.** Use the template in [`references/audit-template.md`](references/audit-template.md). + +--- + +## Failure patterns + +- **Optimizing rankings on a page that is `noindex`.** Always check indexability before content work. +- **Adding sitemaps without fixing canonical issues.** A sitemap of duplicate URLs is worse than no sitemap. +- **Blocking crawlers from CSS or JS.** Breaks Google's rendering. Common in over-aggressive robots.txt files. +- **Over-relying on canonical tags.** Canonicals are hints, not directives. Use redirects when content actually moved. +- **Migrating without a redirect map.** Single biggest cause of post-migration traffic loss. +- **Treating Core Web Vitals as the only ranking signal.** Page experience matters but does not override relevance. + +--- + +## Output format + +Default output is a markdown audit at `seo-technical-audit.md`. Structure: + +1. Scope and methodology +2. Executive summary (3 to 5 critical findings) +3. 6-layer score +4. Critical issues (with example URLs) +5. Important issues +6. Nice-to-have polish +7. Implementation roadmap (sequenced) + +For migrations, include a redirect map as a CSV alongside the report. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable technical SEO audit template. +- [`references/migration-checklist.md`](references/migration-checklist.md) - Pre and post-migration checklist (covers the highest-risk scenario). diff --git a/dist/pi/.agents/skills/seo-technical/references/audit-template.md b/dist/pi/.agents/skills/seo-technical/references/audit-template.md new file mode 100644 index 0000000..a424d3f --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/references/audit-template.md @@ -0,0 +1,321 @@ +# Technical SEO Audit Template + +Fillable template for a technical SEO audit. The audit covers crawlability, indexability, rendering, schema, page experience, and site architecture. + +The output is a stakeholder-readable report plus a prioritized backlog. For migration scenarios specifically, also use `migration-checklist.md`. + +--- + +## Audit metadata + +**Site:** [Domain] +**Pages audited:** [Sample size and selection method] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Tools used:** [Crawler, GSC, log analyzer, Lighthouse, schema validator, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall technical state. +2. The single biggest blocker. +3. The estimated traffic at risk if technical issues persist. +4. The recommended next move. +5. Estimated effort for the top fix. + +> [Summary] + +--- + +## 1. Crawlability + +Can search engines crawl the site? + +### Robots.txt + +- [ ] File exists at `/robots.txt` +- [ ] File is syntactically valid (test in GSC) +- [ ] Critical sections of the site are not accidentally disallowed +- [ ] Specific user agents are not blocked (`Googlebot`, `Bingbot`) +- [ ] Sitemap location is declared (`Sitemap: https://example.com/sitemap.xml`) + +### XML sitemap(s) + +- [ ] Sitemap exists and is reachable +- [ ] Sitemap is referenced in robots.txt +- [ ] Sitemap is submitted in Search Console +- [ ] Sitemap contains only canonical, indexable URLs +- [ ] Sitemap is updated automatically when content changes +- [ ] Sitemap is split if over 50,000 URLs or 50MB +- [ ] `lastmod` reflects the actual last meaningful update (not the build date) + +### Internal linking + +- [ ] No important pages are orphaned (zero internal inlinks) +- [ ] Crawl-discoverable from the homepage within 4 clicks +- [ ] No internal links go to redirected URLs +- [ ] No internal links go to broken URLs (404) +- [ ] Anchor text is descriptive (avoid "click here," "read more") +- [ ] No `nofollow` or `noindex` on important internal pages + +### Crawl budget + +- [ ] Log analysis confirms Googlebot reaches the important sections regularly +- [ ] No crawl traps (calendar pages, infinite faceted nav, session ID parameters) +- [ ] Faceted nav uses `noindex,follow` or controlled parameter handling +- [ ] No duplicate URLs from URL parameter variations (UTMs, tracking, sort orders) +- [ ] Pagination handled with `rel="next"` and `rel="prev"` or paginated URL structure (no infinite scroll for important content) + +--- + +## 2. Indexability + +Can search engines index the site? + +### Index status + +- [ ] GSC "Indexed" count matches expected (production URL count) +- [ ] GSC "Not indexed" reasons are reviewed and addressed +- [ ] "Discovered - currently not indexed" pages are not high-value (or are addressed) +- [ ] "Crawled - currently not indexed" pages are not high-value (or are addressed) + +### Index directives + +- [ ] No `<meta name="robots" content="noindex">` on important pages +- [ ] No `X-Robots-Tag: noindex` HTTP header on important pages +- [ ] Staging or dev environments are noindexed (and not bypassable) +- [ ] Login pages, internal search results, and tag archives are noindex (or otherwise low-priority) + +### Canonicalization + +- [ ] Every page has a `rel="canonical"` tag +- [ ] Self-canonical URLs match the actual URL (no http/https mismatch, no trailing slash mismatch) +- [ ] Cross-canonical references point to indexable, live URLs +- [ ] Pagination uses self-canonicals (not pointing to page 1) +- [ ] No conflicting signals (canonical to URL A, redirect to URL B) + +### Status codes + +- [ ] 200 for live pages +- [ ] 301 for permanently moved pages +- [ ] 302 used only for genuinely temporary redirects +- [ ] 404 for genuinely missing pages (with helpful 404 page) +- [ ] 410 for intentionally removed pages +- [ ] 5xx errors investigated and resolved + +### Redirect chains + +- [ ] No redirect chains over 1 hop (A → B is fine; A → B → C → D is not) +- [ ] No redirect loops +- [ ] HTTPS redirect from HTTP is single-hop +- [ ] Trailing-slash redirect is single-hop + +--- + +## 3. Rendering + +Can search engines render JavaScript-dependent content? + +### Rendering strategy + +- [ ] Critical content is in the initial HTML response (server-rendered or static) +- [ ] If JS-rendered, "fetch as Google" via URL Inspection in GSC shows full content +- [ ] No reliance on user interaction to load primary content (no "click to load article") + +### Specific rendering risks + +- [ ] No JS-rendered title tags or meta descriptions (these often fail to be picked up) +- [ ] No JS-injected canonical tags +- [ ] Lazy-loaded images use native `loading="lazy"` or proper IntersectionObserver implementation +- [ ] Lazy-loaded content above the fold is not lazy-loaded +- [ ] CSS is not blocking critical content rendering + +### JavaScript SEO sanity check + +- [ ] Disable JS in DevTools and reload key pages. Critical content should still appear. +- [ ] Use the URL Inspection tool in GSC and view the rendered HTML. Compare to user-rendered version. + +--- + +## 4. Schema and structured data + +- [ ] Pages have appropriate schema (Article, Product, Organization, BreadcrumbList, FAQ, HowTo, Recipe, etc.) +- [ ] Schema validates in Google's Rich Results Test +- [ ] Schema validates in Schema.org validator +- [ ] No schema violations in GSC enhancement reports +- [ ] BreadcrumbList schema implemented (often-overlooked CTR boost) +- [ ] Organization schema on the homepage +- [ ] WebSite schema with SearchAction (enables sitelinks search box) +- [ ] No schema for content not visible on the page + +--- + +## 5. Page experience + +### Core Web Vitals + +Field data preferred (CrUX, RUM). Lab data is a fallback diagnostic. + +| Metric | Target | Mobile p75 | Desktop p75 | Status | +|---|---|---|---|---| +| LCP | < 2.5s | | | | +| INP | < 200ms | | | | +| CLS | < 0.1 | | | | + +For detailed performance audit, see `performance-optimization` skill. + +### HTTPS + +- [ ] Entire site served over HTTPS +- [ ] No mixed content warnings +- [ ] HSTS header set +- [ ] Certificate valid and not approaching expiry + +### Mobile + +- [ ] Responsive (single URL, single HTML, CSS adapts) +- [ ] Mobile usability passes in GSC +- [ ] No tap targets too close together +- [ ] Viewport meta tag set + +### Safe browsing + +- [ ] No security warnings in GSC +- [ ] No malware or phishing flags + +--- + +## 6. International SEO + +If the site is multilingual or multi-region: + +- [ ] `hreflang` tags present and correct on every locale alternate +- [ ] `hreflang` includes self-reference +- [ ] `x-default` set for language picker fallback +- [ ] Language and region codes follow ISO standards +- [ ] No hreflang errors in GSC International Targeting report +- [ ] URL structure follows a consistent pattern (subdir / subdomain / ccTLD) + +--- + +## 7. Site architecture and URLs + +### URL hygiene + +- [ ] URLs are lowercase +- [ ] URLs use hyphens, not underscores or spaces +- [ ] URLs are short and descriptive +- [ ] No session IDs or tracking parameters in canonical URLs +- [ ] URL structure reflects content hierarchy (category → subcategory → page) + +### Trailing slash + +- [ ] Consistent trailing slash policy (with or without) +- [ ] One version redirects to the other (no duplicates) + +### Subdomains vs subdirectories + +- [ ] Strategic decision documented (subdir typically pools authority better; subdomain better for separate sites) +- [ ] `www` and non-`www` consolidated via 301 + +--- + +## 8. Search Console hygiene + +- [ ] Both `https://www` and `https://` (and `http://` versions) verified as separate properties +- [ ] Domain property verified (the recommended approach) +- [ ] Sitemap submitted and showing "Success" +- [ ] No critical issues in Coverage report +- [ ] No manual actions or security issues +- [ ] Crawl stats reviewed (sudden drops or spikes investigated) + +--- + +## 9. Log file analysis (advanced) + +For larger sites, server logs reveal what crawlers actually do, vs what the site allows. + +- [ ] Top crawled pages match top-priority pages +- [ ] Googlebot does not waste crawl on noindex / parameter / faceted URLs +- [ ] No orphaned pages getting crawler traffic +- [ ] No 5xx errors served to Googlebot + +--- + +## Findings summary + +| Severity | Issue | Pages affected | Recommended fix | Effort | +|---|---|---|---|---| +| P0 (blocking) | | | | | +| P1 (high) | | | | | +| P2 (medium) | | | | | +| P3 (low) | | | | | + +### Severity definitions + +- **P0:** Critical content cannot be crawled or indexed; major technical errors causing exclusion from search. +- **P1:** Significant indexability or rendering issues affecting traffic; broken canonicals; large redirect chains. +- **P2:** Suboptimal but not blocking; missing schema, suboptimal sitemap, partial CWV failures. +- **P3:** Polish; minor inefficiencies, documentation gaps. + +--- + +## Recommendations + +### Now (this week) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Next (this sprint or month) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Later (this quarter) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | + +--- + +## Monitoring after fixes ship + +- [ ] GSC Coverage report rechecked weekly until stable +- [ ] Position tracking for top queries to confirm no regression +- [ ] Log analysis re-run 2-4 weeks after fixes ship +- [ ] CWV field data tracked for affected page templates +- [ ] Set alerts for: 5xx errors, sudden index drops, certificate expiry + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- **Crawl tool config:** [tool, depth, render mode, user agent] +- **Sample selection:** [How URLs were selected for deep review] +- **Field data window:** [Date range] +- **Caveats:** [What this audit did not cover] + +--- + +## Sign-off + +Audit conducted by: [Name, date] +Reviewed with: [Stakeholders] +Implementation owner: [Name] +Re-audit scheduled: [Date] diff --git a/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md b/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md new file mode 100644 index 0000000..c812907 --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md @@ -0,0 +1,118 @@ +# Migration Checklist + +A site migration (domain change, platform change, URL restructure, HTTPS move) is the single highest-risk SEO event. Follow this checklist to avoid the typical 30 to 70 percent traffic loss most migrations cause. + +--- + +## Pre-migration (T minus 30 days) + +### Document the current state +- [ ] Crawl the entire current site, save URL list +- [ ] Export top 1000 organic landing pages from search console (last 12 months) +- [ ] Export top 1000 organic queries from search console +- [ ] Note current rankings for the top 50 commercial queries +- [ ] Save current XML sitemap +- [ ] Save current robots.txt +- [ ] Document current schema implementation +- [ ] Screenshot current SERP appearance for top 10 queries + +### Plan the new structure +- [ ] Map every old URL to its new URL (redirect map) +- [ ] Confirm every important URL has a destination (no orphan redirects) +- [ ] Decide on canonical URL structure (trailing slash, www vs non-www, http to https) +- [ ] Plan handling of parameter URLs (UTM, sort, filter) +- [ ] Plan handling of pagination +- [ ] Plan internal linking structure (avoid relying on redirects) + +### Build and stage +- [ ] Set staging environment to `noindex` +- [ ] Block staging from search engines via robots.txt and HTTP auth +- [ ] Build redirect logic for the redirect map +- [ ] Implement the new sitemap +- [ ] Implement schema on all page types +- [ ] Verify Core Web Vitals on staging +- [ ] Test mobile usability on staging +- [ ] Test HTTPS configuration (HSTS, no mixed content) + +--- + +## Migration day + +### Just before cutover +- [ ] Final crawl of the production site (baseline for comparison) +- [ ] Final export of indexed URL list from search console +- [ ] Confirm DNS TTLs lowered if changing hosts (24 to 48 hours prior) +- [ ] Backup the current site fully +- [ ] Communicate the migration window to stakeholders + +### During cutover +- [ ] Deploy the new site +- [ ] Confirm 301 redirects firing for old URLs (test 20 random samples) +- [ ] Remove `noindex` from new site +- [ ] Update robots.txt on new site (allow crawling) +- [ ] Submit new sitemap in search console +- [ ] Submit change of address (if domain changed) +- [ ] Update canonical references on the new site + +### Within 24 hours of cutover +- [ ] Crawl the new site, compare to baseline +- [ ] Spot-check 50 redirected URLs end-to-end +- [ ] Verify search console shows the new sitemap as processed +- [ ] Check for unexpected 4xx or 5xx errors in server logs +- [ ] Submit top 20 priority URLs for re-indexing + +--- + +## Post-migration (T plus 1 to 30 days) + +### Week 1 +- [ ] Daily check on indexed page count in search console +- [ ] Daily check on crawl errors +- [ ] Daily check on average position for top 50 queries +- [ ] Verify no traffic anomalies in analytics +- [ ] Fix any redirect loops or chains identified in logs + +### Week 2 to 4 +- [ ] Verify all old URLs redirecting to new URLs (full crawl) +- [ ] Verify no redirect chains (max one hop) +- [ ] Verify schema validates on key page types +- [ ] Check Core Web Vitals trend (any regressions vs pre-migration) +- [ ] Update external backlinks where feasible (highest-value links first) +- [ ] Check social media platforms display new URLs correctly + +### Month 2 +- [ ] Compare organic traffic to pre-migration baseline +- [ ] Compare keyword rankings to pre-migration baseline +- [ ] Note any pages that lost rankings, investigate +- [ ] Begin pruning redirect rules for URLs that no longer receive traffic (after 90 days minimum) + +--- + +## Common migration failures (and how to prevent each) + +| Failure | Prevention | +|---|---| +| Old URLs returning 404 | Comprehensive redirect map, tested before cutover | +| Redirect chains (2+ hops) | Direct redirect old → new, never old → middle → new | +| Lost rankings on key pages | Same content, same intent, same internal linking on new pages | +| Crawl waste from old parameters | Clean URL structure, parameter handling rules | +| Mixed HTTPS and HTTP content | Audit all asset URLs, force HTTPS via HSTS | +| Search console disconnect | Verify both old and new properties, submit change of address | +| Sitemap mismatch | New sitemap lists new canonical URLs only, no legacy URLs | +| Hreflang breaks (international sites) | Map hreflang to new URLs, preserve language pair relationships | + +--- + +## Recovery if traffic drops + +If organic traffic drops more than 20 percent within 14 days: + +1. Verify all critical URLs return 200 or 301 (no 404 or 500) +2. Verify search console is processing the new sitemap +3. Spot-check top 50 lost-traffic URLs for content parity (does the new page actually answer the same query?) +4. Check robots.txt and meta robots for accidental noindex +5. Check for hreflang errors if international +6. Submit affected URLs for re-indexing manually +7. Audit internal linking - are key pages still well-linked? + +Most migration drops recover within 60 to 90 days IF the redirect map is complete and the content is preserved. If not recovering by day 90, the issue is structural and needs deeper investigation. diff --git a/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md b/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md new file mode 100644 index 0000000..cd5c87b --- /dev/null +++ b/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md @@ -0,0 +1,180 @@ +--- +name: seo-traffic-diagnosis +description: "Diagnose organic traffic changes (drops, stalls, or unexpected wins) using Ahrefs MCP plus Search Console data. Use this skill when traffic suddenly dropped, has been flat despite investment, after an algorithm update, after a migration or deploy, or when a competitor seems to be taking share. Triggers on traffic dropped, traffic decline, traffic stalled, organic decline, lost rankings, why is traffic down, algorithm update, post-migration traffic loss, traffic diagnosis. Also triggers when stakeholders are panicking about analytics." +category: seo-audit-suite +catalog_summary: "Diagnose drops, stalls, or wins via 5-layer root cause analysis" +display_order: 5 +--- + +# SEO Traffic Diagnosis + +Diagnose why organic traffic moved (down, flat, or unexpectedly up) using Ahrefs MCP combined with Search Console and analytics data. Stack-agnostic. Produces a root-cause diagnosis and an action plan. + +--- + +## When to use + +- Organic traffic dropped sharply +- Organic traffic has been flat for months despite content investment +- After a known Google algorithm update +- After a migration, replatform, or domain change +- After a deploy that touched routing, redirects, or rendering +- When a competitor is visibly taking organic share +- When a single page dropped from a ranked position +- When stakeholders need an explanation, fast + +## When NOT to use + +- Routine performance reporting (use `analytics-strategy`) +- Pre-emptive content planning (use `seo-content-gap-audit`) +- Backlink-only investigations (use `seo-backlink-audit`) +- Technical issue triage outside of traffic concerns (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Description of the symptom (what changed, when, magnitude) +- Date the change started (best estimate) +- Recent SEO history: deploys, migrations, content changes, link campaigns +- Access to Ahrefs MCP, Search Console, and analytics +- Confirmation the change is real (not a tracking artifact) + +--- + +## The framework: 5 layers of diagnosis + +A traffic change has one or more root causes. Move through the layers in order. Stop when you have enough evidence. + +### Layer 1: Confirm the change is real + +Before diagnosing, rule out: + +- Tracking gaps (analytics outages, tag manager issues) +- Bot traffic changes +- Reporting comparison errors (different date ranges, wrong segment) +- Seasonality (compare year-over-year, not just month-over-month) +- Holiday or weekday effects + +Cross-check Search Console clicks against analytics organic sessions. Significant divergence often points to a tracking issue, not a real traffic change. + +### Layer 2: Localize the change + +Where is the change happening? + +Segment by: + +- Country and language +- Device (mobile, desktop, tablet) +- Page or section (homepage, blog, product, category) +- Query type (branded vs non-branded) +- Landing page + +A change in one segment requires different diagnosis than a change everywhere. + +| Pattern | Likely cause | +| --- | --- | +| One country dropped | Local algorithm update, hreflang issue, geo redirect issue | +| Mobile dropped, desktop flat | Mobile usability or page speed regression | +| One section dropped | Topical algorithm update or section-specific quality issue | +| Branded queries dropped | Brand-level issue: site outage, reputation, manual action | +| Non-branded dropped | Algorithmic ranking issue | +| Single page dropped | Page-level issue: content, technical, or competitive | +| Sitewide dropped | Sitewide issue: penalty, technical, migration, or algorithm | + +### Layer 3: Page-level analysis + +For affected pages, audit: + +- Position changes per ranked keyword (Ahrefs Rank Tracker history) +- SERP composition changes (more ads, AI overviews, featured snippets, video) +- Click-through rate changes +- Index status (Search Console coverage) +- Crawl errors and accessibility +- Recent content changes +- Internal link changes +- Backlink changes (lost links, redirect chains) + +A page can lose traffic without losing rank if SERP composition changed. + +### Layer 4: Technical analysis + +Did anything break technically? + +Check: + +- Robots.txt changes +- Canonical tag changes +- Meta robots changes (accidental noindex) +- Redirect chains and loops +- Render issues (especially for JS-heavy frameworks) +- Site speed regressions +- Hreflang errors +- Sitemap freshness +- HTTP status codes (4xx, 5xx spikes) +- Server log evidence of crawl behavior changes + +Recent deploys are the prime suspect. Compare deploy dates to traffic change dates. + +### Layer 5: External analysis + +If layers 1-4 do not explain the change, look outward. + +- Algorithm update calendar (cross-reference timing) +- Competitor moves (new content, new SERP features they captured) +- Industry trend (declining search demand for the topic) +- Manual action (Search Console security and manual actions) +- Negative SEO (sudden link velocity changes) + +External-factor diagnosis benefits from competitive context: did your traffic drop while competitors held steady (suggests an algorithm-specific issue), or did the entire vertical lose ground (suggests a user-behavior shift)? Similarweb shows competitor traffic trends; Ahrefs shows competitor SERP movement; pairing both surfaces whether the issue is yours alone or the category's. + +--- + +## Workflow + +1. **Confirm the symptom.** Get exact dates, magnitude, segment if known. +2. **Validate the data.** Layer 1 checks. Rule out tracking and seasonality. +3. **Localize.** Layer 2. Segment until the pattern is clear. +4. **Page-level dive.** Layer 3 on the most affected pages. +5. **Technical check.** Layer 4. Recent deploys, robots, canonicals, redirects. +6. **External check.** Layer 5. Algorithm updates, competitors, industry. +7. **Build the hypothesis.** State the cause as a single sentence. +8. **Validate the hypothesis.** Find the evidence that confirms or refutes it. See [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md). +9. **Action plan.** Specific fixes mapped to specific evidence. +10. **Communicate.** Write up the diagnosis. Stakeholders want clarity, not exhaustive analysis. + +--- + +## Failure patterns + +- **Jumping to algorithm update.** "It must be the algorithm" is the lazy answer. Eliminate technical and page-level causes first. +- **Solving the wrong problem.** A drop diagnosed as "content quality" when the real cause was an accidental noindex on a deploy. Validate the hypothesis before fixing. +- **No baseline for "normal."** Without a baseline, every fluctuation looks alarming. Establish what normal noise looks like before reacting. +- **Treating one page as the site.** Site-wide and page-level diagnoses are different. Confirm scope first. +- **Ignoring branded vs non-branded.** A drop in branded queries means a brand-level problem. A drop in non-branded means an SEO problem. Different teams own them. +- **Comparing wrong date ranges.** Comparing 28 days to the previous 28 days during a holiday distorts the picture. Use year-over-year for seasonal businesses. +- **Stopping at correlation.** A deploy and a drop on the same day is a strong correlation, not proof. Find the mechanism. +- **Single-source diagnosis.** Ahrefs sees position. Search Console sees clicks and queries. Analytics sees behavior. Logs see crawl. Use them together. +- **Premature reassurance.** Telling stakeholders "it is just an algorithm update, will recover" without evidence sets up a worse conversation later. + +--- + +## Output format + +A diagnosis document with: + +1. **Summary.** What changed, when, magnitude, root cause in one paragraph. +2. **The symptom.** Charts and segment breakdowns. +3. **Layer-by-layer findings.** What each layer ruled in or out. +4. **Root cause hypothesis.** Single statement with evidence. +5. **Action plan.** Ordered fixes with owners and timelines. +6. **Recovery forecast.** Realistic expectations on timeline and ceiling. +7. **Monitoring plan.** What to watch for confirmation of recovery. + +Length: 4-10 pages. Stakeholders read this fast. + +--- + +## Reference files + +- [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md) - Layer-by-layer diagnostic checklist with the specific data to pull at each layer and how to interpret each signal. diff --git a/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md b/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md new file mode 100644 index 0000000..2895ed3 --- /dev/null +++ b/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md @@ -0,0 +1,209 @@ +# Diagnosis checklist + +A layer-by-layer checklist for diagnosing organic traffic changes. Use it after the symptom is confirmed real and you need to narrow root cause. + +--- + +## Layer 1: Confirm the change is real + +### Pulls + +- Search Console clicks and impressions (last 90 days, day-by-day) +- Analytics organic sessions (matching window) +- Year-over-year same-period comparison +- Bot or crawler traffic if filterable + +### Checks + +- [ ] Date range comparison is apples to apples +- [ ] No tracking outage in analytics during the window +- [ ] No tag manager deploys during the window +- [ ] Search Console clicks and analytics organic sessions move together (within 10-20%) +- [ ] Year-over-year shows the same pattern (rules out seasonality) +- [ ] No major holiday or industry event explains the change + +If clicks and sessions diverge significantly: the issue may be tracking, not traffic. +If year-over-year shows the same pattern: the change is seasonal, not anomalous. + +--- + +## Layer 2: Localize the change + +### Pulls + +- Search Console: clicks segmented by country, device, query type, page +- Analytics: organic sessions segmented by landing page, country, device + +### Checks for each segment + +- [ ] One country dropped, others stable: local algorithm or geo issue +- [ ] One device dropped, others stable: device-specific issue +- [ ] One section dropped, others stable: section-specific quality or technical issue +- [ ] Branded queries dropped: brand-level issue +- [ ] Non-branded dropped: SEO ranking issue +- [ ] Single page dropped: page-level issue +- [ ] Everything dropped: sitewide issue + +### Decision + +Pick the dominant pattern. Carry the most affected segment into Layer 3. + +--- + +## Layer 3: Page-level analysis + +For each affected page or page cluster: + +### Pulls + +- Ahrefs: ranked keywords with current and historical positions +- Ahrefs: SERP overview for top 5-10 ranked keywords (current and from before the drop) +- Search Console: queries, impressions, clicks, position, CTR for each affected page +- Analytics: landing page sessions, conversion rate, bounce rate +- Index status in Search Console +- Recent edits to the page (CMS history) +- Internal links pointing to the page (Ahrefs Site Explorer) +- Backlinks to the page (Ahrefs) + +### Checks + +- [ ] Did position drop, or did position stay flat with CTR drop? +- [ ] Did the SERP composition change (new AI overviews, featured snippet steal, more ads, more video)? +- [ ] Are click-through rates lower than benchmarks for the position? +- [ ] Has the page been recently edited (intentionally or accidentally)? +- [ ] Has the page lost backlinks? +- [ ] Have internal links to the page decreased? +- [ ] Is the page indexed? + +### Interpretation + +| Pattern | Cause | +| --- | --- | +| Position fell, SERP same | Quality, freshness, or competitor improved | +| Position stable, CTR fell | SERP feature change (snippet, AI overview, ads) | +| Position fell, SERP added new strong domain | Competitor took share | +| Position fell after a CMS edit | Recent edit broke something | +| Page deindexed | Technical issue (robots, canonical, noindex) | +| Backlinks fell | Link-based ranking signal decline | +| Internal links fell | Internal link equity dilution | + +--- + +## Layer 4: Technical analysis + +### Pulls + +- Robots.txt (current and historical via web archive if needed) +- Canonical tag check on affected pages +- Meta robots tag check on affected pages +- Redirect map for any URL changes +- HTTP status codes for affected URLs +- Sitemap freshness +- Hreflang implementation (multilingual sites) +- Server logs (Googlebot crawl behavior) +- Recent deploy log +- Recent infrastructure changes (CDN, DNS, hosting) + +### Checks + +- [ ] Robots.txt has not blocked anything new +- [ ] No accidental `noindex` on affected pages +- [ ] No accidental canonical to a different URL +- [ ] Redirects resolve in 1 hop with 301 status +- [ ] No 4xx or 5xx spikes for affected URLs +- [ ] Sitemap includes affected URLs and is current +- [ ] Hreflang is reciprocal and points to live URLs (multilingual) +- [ ] Googlebot is crawling at normal rates +- [ ] No deploy date matches the traffic drop date + +### Common technical regressions + +| Symptom | Likely cause | +| --- | --- | +| Sudden full-site drop after a deploy | Robots.txt blocked everything, accidental sitewide noindex, or routing broke | +| Pages return 404 or 410 | URL structure changed, redirects missing | +| Pages return 5xx | Server or hosting issue, possible CDN misconfiguration | +| Render mismatch | JS rendering broke for crawlers (especially with framework upgrades) | +| Hreflang broken | Cross-country traffic falls but other markets shift | +| Mass canonical change | Pages canonicalized to wrong URLs after redesign | + +--- + +## Layer 5: External analysis + +### Pulls + +- Algorithm update calendar (cross-reference traffic change date) +- Ahrefs SERP overview for affected keywords (looking for new ranking domains) +- Ahrefs competitor traffic estimates (their gain may be your loss) +- Search Console security and manual actions +- Backlink velocity changes (sudden gains or losses) +- News or industry trend search interest + +### Checks + +- [ ] No manual action notice in Search Console +- [ ] Drop date does not align with a known algorithm update +- [ ] No competitor has visibly taken share on affected keywords +- [ ] Industry-wide search demand for the topic has not shifted +- [ ] No spike in suspicious backlinks (negative SEO signal) +- [ ] No negative news or PR event affecting the brand + +### If layers 1-4 are clean + +- Drop on a known update date is likely algorithmic. Audit content quality and E-E-A-T signals. Recovery often takes the next update cycle. +- Drop with new dominant SERP domain is likely a competitive shift. Audit their content and update yours. +- Drop with industry-wide demand decline is not your fault. Manage stakeholder expectations. + +--- + +## Hypothesis statement template + +After working through the layers, state the hypothesis as a single sentence: + +``` +[Property] lost [magnitude] organic traffic starting [date] +because [root cause], +evidenced by [specific data points], +and recovery requires [specific actions] +with an expected timeline of [duration]. +``` + +Examples: + +> Site organic clicks dropped 35% starting March 12 because a deploy on March 11 added an accidental `noindex` meta tag sitewide, evidenced by Search Console coverage going from 2,400 indexed pages to 180 in 14 days, and recovery requires removing the noindex tag and resubmitting the sitemap with an expected timeline of 4-8 weeks. + +> Blog section organic clicks dropped 22% starting August 8 because Google rolled out a core update on that date that emphasizes E-E-A-T signals our author bylines lacked, evidenced by position drops on informational queries while transactional queries held, and recovery requires adding author E-E-A-T signals and improving content depth with an expected timeline of 1-2 update cycles (3-6 months). + +--- + +## When the diagnosis is unclear + +Sometimes the data points in multiple directions. In that case: + +1. State the top 2 hypotheses with evidence for each. +2. Recommend the lowest-risk action that helps in either case. +3. Identify the data that would distinguish the hypotheses. +4. Propose a monitoring plan to gather that data. + +Avoid forcing a clean conclusion when the evidence does not support one. Stakeholders prefer honest uncertainty to confident-but-wrong. + +--- + +## Communication template + +When delivering the diagnosis to stakeholders: + +``` +**What happened:** [1 sentence] + +**Why it happened:** [1 sentence] + +**What we are doing:** [3-5 specific actions] + +**When to expect recovery:** [timeline with confidence level] + +**What to watch for:** [leading indicators of recovery or further decline] +``` + +Stakeholders rarely want the layer-by-layer detail. They want clarity, accountability, and timeline. Keep the full diagnosis as an appendix. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md b/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md new file mode 100644 index 0000000..7683255 --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md @@ -0,0 +1,261 @@ +--- +name: skill-creation-walkthrough +description: Step-by-step guide for creating your own Claude Skills, from deciding whether a skill is the right tool to writing the SKILL.md file, structuring reference material, and making it trigger reliably. Use when you want to package a workflow, framework, or repeated task into a reusable Skill, when an existing skill is not triggering or not loading the right context, when you are auditing a skill that is underperforming, or when you want to publish a skill for others. Also triggers when someone asks "how do I make a skill" or "what makes a good skill". Useful for individuals, teams, and anyone publishing skills publicly. +category: process-and-team +catalog_summary: "The meta-skill: how to write your own custom skills" +display_order: 5 +--- + +A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate. + +## When to use + +- You catch yourself writing the same prompt or instructions repeatedly. +- You want to package a workflow or framework for reuse. +- An existing skill of yours is not triggering when it should. +- You are publishing skills for others to use. +- You want to teach Claude a domain-specific way of working. +- You are reviewing a skill someone wrote and need a quality bar. + +## When NOT to use + +- For one-off prompts (just write the prompt). +- For information that should live in system context, not progressive disclosure. +- For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills). +- For replacing tool calls (skills are instructions, not tools). + +## Required inputs + +- The task or workflow you want to encode. +- The audience: who will trigger this skill, in what kind of conversation. +- Existing artifacts: prompts you have used, docs you have written, examples of good output. + +## The framework: how skills work + +A Skill is a folder with a `SKILL.md` file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed. + +The key property: **progressive disclosure**. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context. + +What this means for you: + +- The **description** is everything for triggering. Get it right or the skill never loads. +- The **SKILL.md body** is for the workflow itself. +- The **references** are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material. + +## Workflow + +### Phase 1: Decide if a skill is the right shape + +Not everything should be a skill. Run this test: + +| Sign it should be a skill | Sign it should not be | +| --- | --- | +| You repeat the same workflow 5+ times. | You used it once. | +| The output benefits from a consistent structure. | Each output is bespoke. | +| The task has a clear trigger (a question shape, a file type, a domain). | The task is part of every conversation already. | +| The instructions exceed 200 words. | A one-line system instruction would do. | +| Templates or reference material would help. | Pure prose is enough. | +| Other people might benefit from the same workflow. | Only relevant to your single project. | + +If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction. + +### Phase 2: Define the trigger + +Before writing anything, ask: when should this skill load? + +Be concrete. Write down the exact phrases or situations that should trigger it. Examples: + +- "When the user asks for a creative brief, kickoff doc, or project brief." +- "When the user uploads a CSV and wants tabular analysis." +- "When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related." +- "When the user mentions they want to pick a vendor or compare tools." + +The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably. + +### Phase 3: Write the description + +This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill. + +Good descriptions have 4 parts: + +1. **What it does** (one sentence, action-oriented). +2. **When to use it** (the trigger phrases or situations). +3. **Edge cases** with "Also triggers when..." (catches less obvious situations). +4. **Useful for...** (audience or use cases, helps disambiguation). + +Bad description: + +> "Helps with SEO." + +Why it fails: vague, no trigger phrases, will not fire when the user actually needs it. + +Good description: + +> "Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits." + +Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity. + +### Phase 4: Structure the SKILL.md body + +A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills: + +``` +--- +name: [your-skill-name] +description: [your description] +--- + +[One-sentence purpose statement] + +## When to use +[Bulleted list of trigger situations] + +## When NOT to use +[Bulleted list, ideally redirecting to sibling skills] + +## Required inputs +[What Claude needs from the user to run this skill] + +## The framework +[The durable IP: the model, the steps, the dimensions, the layers] + +## Workflow +[Numbered steps Claude follows] + +## Failure patterns +[Common mistakes to avoid or push back on] + +## Output format +[What the deliverable looks like] + +## Reference files +[List of files in the references/ folder with descriptions] +``` + +Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed. + +### Phase 5: Add references for what does not belong in SKILL.md + +References are the second tier of progressive disclosure. They load when Claude reads them, not by default. + +Use references for: + +- Long checklists (a 100-item audit checklist). +- Templates with worked examples. +- Detailed playbooks for specific scenarios. +- Reference material like spec links, glossaries, decision tables. +- Anything over 100 lines that not every invocation needs. + +Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides. + +Naming patterns that work: + +- `references/[noun]-template.md` for templates. +- `references/[noun]-checklist.md` for checklists. +- `references/[noun]-playbook.md` for end-to-end runbooks. +- `references/example-[scenario].md` for worked examples. + +Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each. + +### Phase 6: Test and iterate + +Skills do not work the first time. Plan to iterate. + +Testing checklist: + +- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong. +- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire? +- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad. +- [ ] Output test: run the skill on a real task. Is the output what you expected? +- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim. + +After testing, common fixes: + +- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..." +- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience. +- Output is generic → add a clearer framework or workflow with more specifics. +- Reference is overwhelming → split into multiple references, keep each focused. + +## Deep dive: description anatomy + +The description is hard to get right. Here is the formula in detail. + +### Sentence 1: What it does + +Lead with the verb. Be specific. + +- Good: "Audit on-page SEO." +- Bad: "Help with SEO things." + +### Sentence 2: When to use it + +State the primary triggers. Use phrases users would actually say. + +- Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'." +- Bad: "Use for SEO improvements." + +### Sentence 3: "Also triggers when..." + +Catch the secondary triggers and edge cases. + +- Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup." +- Bad: (omitted) + +### Sentence 4: Useful for... + +Explain audience or scope to help with disambiguation. + +- Good: "Useful for both individual page reviews and small-batch audits." +- Bad: (omitted) + +If your skill description is one sentence, it is probably not specific enough. + +## Deep dive: worked example + +Imagine you keep writing technical post-mortem documents and want to skill-ify it. + +**Step 1: Decide it's a skill.** You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill. + +**Step 2: Trigger.** "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong." + +**Step 3: Description.** + +> "Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews." + +**Step 4: SKILL.md body.** Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up). + +**Step 5: References.** A `post-mortem-template.md` with the document structure and a `facilitator-checklist.md` for running the post-mortem meeting. + +**Step 6: Test.** Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro). + +You iterate until the triggers fire correctly, then ship. + +## Failure patterns + +- **Description too narrow.** The skill never fires because your description requires exact phrases the user does not say. +- **Description too broad.** The skill fires constantly, including for unrelated tasks. +- **No trigger phrases.** The description describes what the skill does but not when to load it. Triggering is unreliable. +- **SKILL.md too long.** A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references. +- **References that duplicate SKILL.md.** If a reference repeats what the body says, prune one. +- **No "When NOT to use".** Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly. +- **No examples.** A framework without a worked example is hard to apply. Include at least one in the reference material. +- **Optimizing for one example.** A skill written around your single use case fails at adjacent ones. Generalize. +- **No iteration.** Shipping a skill once and never revisiting it. Skills decay. Audit yearly. +- **Branding or product-specific assumptions in a public skill.** Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md) for the full discipline and the user-outcome reasons it matters. + +## Output format + +When using this skill to create another skill, deliver: + +1. **Trigger analysis**: a short list of phrases and situations that should fire the skill. +2. **Description draft**: the 2-4 sentence description for the YAML frontmatter. +3. **SKILL.md body**: the full body of the skill, following the standard structure. +4. **Reference plan**: a list of reference files to create with one-line descriptions. +5. **First reference file**: at least one reference written end to end as a starting point. +6. **Test plan**: 3-5 test prompts that should trigger the skill, plus 2-3 that should not. + +## Reference files + +- [`references/skill-template.md`](references/skill-template.md): A blank SKILL.md template with annotated section guidance, ready to copy and fill in. +- [`references/description-cookbook.md`](references/description-cookbook.md): A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs). +- [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md): What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md new file mode 100644 index 0000000..ff3ba60 --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md @@ -0,0 +1,214 @@ +# Description cookbook + +The skill description is the single most important sentence (or paragraph) in your skill. It is what Claude sees in the system prompt to decide whether to load the rest of the skill. If the description is wrong, the skill never fires when it should, or fires when it should not. + +This cookbook gives you description patterns for common skill types, each with a worked example. + +## The 4-part formula + +A reliable description has 4 parts: + +1. **Action**: what the skill does (verb-led, specific). +2. **Primary triggers**: when to use it (the obvious cases). +3. **Edge cases**: secondary triggers introduced with "Also triggers when...". +4. **Audience or scope**: who this serves, introduced with "Useful for...". + +Not every skill needs all four parts. Most benefit from at least three. + +## Pattern 1: The audit skill + +For skills that evaluate something against a rubric. + +### Template + +``` +[Verb] [the thing] for [purpose]. Use when the user asks for [a concrete request], wants to [common task], or asks "[likely user phrasing]". Also triggers when the user mentions [related concepts] or shares [input that implies the audit]. Useful for [scope: one-off vs ongoing, individual vs batch]. +``` + +### Worked example + +``` +Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks "why is this page not ranking". Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits. +``` + +Why this works: + +- "Audit" is a clear verb. +- The "on a single URL or a small set of pages" sets scope, which prevents this from competing with bulk audit skills. +- Three primary triggers in different phrasings. +- "Also triggers when..." catches secondary signals. +- "Useful for..." narrows the use case. + +## Pattern 2: The template or generator skill + +For skills that produce a structured artifact. + +### Template + +``` +Generate [the artifact] following [methodology or structure]. Use when the user asks to write [artifact name], needs [related deliverable], or describes [the work this artifact captures]. Also triggers when the user has [precondition] and is preparing to [downstream action]. Useful for [audience or use case]. +``` + +### Worked example + +``` +Generate a creative brief that aligns stakeholders before a project starts. Use when the user asks to write a brief, kickoff doc, or project brief, or describes a project that has a goal but no shared context document. Also triggers when the user is starting design or development work without an agreed scope. Useful for individual project briefs and recurring brief templates. +``` + +Why this works: + +- "Generate" is the verb. +- "That aligns stakeholders before a project starts" tells Claude the context. +- Multiple ways the user might phrase the request. +- The "also triggers" catches the upstream signal (no shared context yet). + +## Pattern 3: The framework or methodology skill + +For skills that teach or apply a way of thinking. + +### Template + +``` +Apply [framework name or shape] to [the problem]. Use when the user is [the situation], asks "[likely question]", or needs to think through [the kind of decision]. Also triggers when [secondary condition]. Useful for [scope]. +``` + +### Worked example + +``` +Apply the Diataxis framework to documentation problems: separate tutorials, how-to guides, references, and explanations. Use when the user is reorganizing docs, asks "where should I put this", or has docs that try to do too much at once. Also triggers when the user is starting a fresh docs site and needs a content structure. Useful for both internal and external documentation. +``` + +Why this works: + +- Names the framework explicitly. +- Concrete trigger phrases. +- "Has docs that try to do too much at once" is a specific symptom that maps to this framework. + +## Pattern 4: The walkthrough or playbook skill + +For skills that take the user through a multi-step process. + +### Template + +``` +Walk through [the process] step by step. Use when the user is [the situation], asks how to [the goal], or needs a structured approach to [complex task]. Also triggers when [edge case]. Useful for [first-time vs repeat use, individuals vs teams]. +``` + +### Worked example + +``` +Walk through a domain migration step by step, including DNS, redirects, content mapping, and post-launch validation. Use when the user is moving content between platforms, changing domains, or restructuring URLs at scale. Also triggers when the user mentions hreflang updates, sitemap regeneration, or 301 redirect maps. Useful for both small migrations (a few hundred URLs) and large ones (tens of thousands). +``` + +Why this works: + +- "Step by step" sets expectation. +- Names the components ("DNS, redirects, content mapping, and post-launch validation") so users with one of these in mind still trigger correctly. +- Scale guidance in "useful for" helps with disambiguation. + +## Pattern 5: The decision or evaluation skill + +For skills that help the user pick between options. + +### Template + +``` +Compare [option type] and recommend [outcome]. Use when the user is choosing between [options], asks "[option A] vs [option B]", or needs to decide [the question]. Also triggers when [renewal/replacement/scaling situation]. Useful for [scope]. +``` + +### Worked example + +``` +Compare vendors and recommend a pick for a specific job. Use when the user is choosing between SaaS tools, asks "X vs Y", or needs to evaluate options before signing a contract. Also triggers when an existing vendor is up for renewal or being replaced. Useful for both small SaaS decisions and large infrastructure choices. +``` + +Why this works: + +- "Compare and recommend" frames the action. +- Multiple trigger phrasings. +- "Also triggers when..." catches the renewal/replacement situation that often forces a decision. + +## Pattern 6: The diagnostic or troubleshooting skill + +For skills that help find what is wrong. + +### Template + +``` +Diagnose [the problem class] and propose fixes. Use when the user reports [symptom], asks "why is [thing] [bad state]", or shares [evidence of the problem]. Also triggers when [related signal]. Useful for [scope of diagnosis]. +``` + +### Worked example + +``` +Diagnose slow page performance and propose specific fixes. Use when the user reports slow load times, asks "why is my site slow", or shares a Core Web Vitals report. Also triggers when the user mentions Lighthouse scores, LCP, INP, or CLS issues. Useful for both individual page diagnosis and site-wide performance reviews. +``` + +Why this works: + +- "Diagnose and propose fixes" is the action. +- Catches the user's likely phrasing ("why is my site slow"). +- Catches technical phrasings (Core Web Vitals report, Lighthouse, specific metric names). + +## Pattern 7: The strategy or planning skill + +For skills that produce a plan or strategy. + +### Template + +``` +Design [the plan or strategy] for [outcome]. Use when the user is [the situation], asks for a [plan / strategy / roadmap], or needs to align [stakeholders or work] around [the goal]. Also triggers when [precondition or constraint]. Useful for [scope]. +``` + +### Worked example + +``` +Design a content strategy that supports a specific business goal. Use when the user is starting a content program, asks for an editorial plan, or needs to align content production with marketing or SEO objectives. Also triggers when the user mentions topical authority, content calendar, or pillar pages. Useful for both new programs and reboots of stalled ones. +``` + +Why this works: + +- "Design a content strategy that supports a specific business goal" sets the action and the constraint. +- Catches both fresh starts and reboots in "useful for". + +## Anti-patterns: descriptions that fail + +### "Helps with X" + +Too vague. No triggers. Will fire constantly or never. + +### "When the user wants help with technical SEO and on-page SEO and off-page SEO" + +Too broad. Should be split into multiple skills or narrowed. + +### "Use when the user mentions XYZ" + +Too narrow. Real users will not always use the exact phrase. + +### "Comprehensive guide to [topic]" + +Marketing copy, not a trigger. Does not tell Claude when to load. + +### "[no description, just a name]" + +The skill never loads except by accident. + +## How to test a description + +Before publishing: + +1. Write down 5 prompts that should trigger the skill. +2. Write down 3 prompts that should not. +3. In a fresh conversation with the skill installed, try each prompt. +4. Check whether the skill loaded. +5. Adjust the description until trigger and non-trigger prompts behave correctly. + +If a should-trigger prompt does not fire, broaden the description: add the phrasing the user used, add an "also triggers" clause. + +If a should-not-trigger prompt fires, narrow the description: add scope boundaries, name the sibling skill the user actually wants, or add a "Do not trigger when..." clause if needed (most skill descriptions do not need this, but it is available). + +## Final tip: match the user's vocabulary + +Users do not say "perform an SEO audit". They say "can you check my page" or "is my site optimized". Your description should anticipate the user's vocabulary, not yours. + +If your description is full of expert jargon and the user is a beginner, the skill will not fire. Use the words your audience actually says. Use jargon as a backup, not the lead. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md new file mode 100644 index 0000000..55c6f4f --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md @@ -0,0 +1,96 @@ +# Methodology vs implementation + +What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. + +A public skill is methodology, not implementation. Skills teach the framework, the decision criteria, the taxonomies, the anti-patterns. They do not teach the specific page architecture, type definitions, image generation script structure, or stack-specific patterns that any one team uses to ship polished delivery. + +This is not gatekeeping. It is user-aligned. Methodology produces work that is distinctive to each team's stack and judgment. Cookie-cutter implementation produces homogenized output that looks identical across users. Stack-agnosticism makes the catalog actually portable. Implementation specificity makes it useless to teams on different stacks. + +--- + +## What belongs in a public skill (methodology layer) + +- Conceptual frameworks (architectures, registers, taxonomies, classifications) +- Decision criteria (when to choose X versus Y, with the tradeoffs surfaced) +- Anti-patterns and common failure modes +- The shape of artifacts the skill produces, described in generic terms (a markdown brief with these sections; a JSON object with these fields; a design spec with these decisions documented), not as type signatures bound to a specific framework +- Voice and style guidance for the work +- Workflow descriptions at the methodology level (the sequence of decisions and handoffs, not the platform commands) +- General principles applicable across stacks +- Worked examples with fictional or anonymized actors that demonstrate the framework concretely without prescribing a specific tooling stack + +The 12-consideration framework pattern (or 5-pillar, 4-axis, etc.) lives here. Frameworks are durable; they survive stack migrations and team transitions because they teach judgment, not code. + +--- + +## What does not belong in a public skill (implementation layer) + +- Specific Next.js, React, Vue, Svelte, or other framework-specific page architectures +- TypeScript or other type definitions optimized for a specific application's data shapes +- Component patterns with stack-specific code (JSX, template syntax, framework directives) +- Image generation script structures matching a specific implementation +- Application-context CSS-rendered mockup component code +- Theme integration patterns tied to specific design tokens (brand-color names, spacing scales, font tokens that exist only in one team's design system) +- Tailwind class strings or other utility-CSS specifics that prescribe one stack's idioms +- Schema markup component shapes that match one team's component library +- Vercel, Netlify, or specific deployment patterns + +If a section of a skill cannot be applied by a reader on a different stack, it does not belong in the public skill. It belongs in an internal playbook, a productized client deliverable, or a stack-specific reference implementation maintained separately. + +--- + +## Why the line matters + +Three principles, each user-outcome framed. + +### 1. Methodology produces distinctive work + +A skill that teaches "five logo architectures" leaves the user to choose, design, and execute the architecture that fits their brand. A skill that teaches "render this Next.js component with these Tailwind classes" produces work that looks identical across every user who runs the skill. Cookie-cutter implementation homogenizes; methodology requires the user to engage with why, which produces work distinctive to each team's context. + +The user outcome that matters: did the skill help the user produce work that is theirs, or did it produce work that signals "I ran a skill"? + +### 2. Stack-agnosticism is real value + +A skill that mandates a specific Next.js component is useless to teams on Astro, vanilla HTML, Figma-only workflows, WordPress, Shopify, or anywhere off the prescribed stack. Methodology applies across all of them. + +The catalog gets used by people writing in plain markdown, working in Notion, building on a static site generator, running in WordPress, or shipping in something that did not exist when the skill was written. Methodology survives all of those. Stack-coupled implementation does not. + +### 3. The catalog compounds because skills are durable + +Skills last across stack changes, framework migrations, and team transitions because they teach judgment, not code. A skill that hardcodes the framework du jour decays as the framework changes. A skill that teaches the framework-agnostic principle the framework was implementing keeps working when teams migrate to the next framework. + +Implementation-leaking skills decay as their implementations become outdated. Methodology-pure skills compound across years. + +--- + +## The audit pattern + +The catalog is audited periodically for methodology versus implementation drift. The first formal audit (May 2026) reviewed 18 flagship skills against the criteria in this reference and found zero implementation-leakage findings; the discipline had been held by instinct from the catalog's earliest skills onward. Future audits will land as the catalog grows past current size. + +Findings shape the discipline. Recently shipped skills tend to carry the discipline more cleanly than the earliest ones, which reflects the maturation any catalog goes through. The principle is not "perfection from day one"; it is "audit, learn, codify, hold the line going forward." + +--- + +## How to apply this when authoring new skills + +A short checklist for skill authors: + +1. **Before writing, identify the methodology versus implementation boundary explicitly.** What part of this skill teaches a framework that applies across stacks? What part teaches your specific stack's implementation? The framework part goes in the public skill; the implementation part stays internal. +2. **When tempted to include specific code, ask: is this teaching the framework, or is this teaching my stack?** If it teaches the framework using your stack as one illustration, keep it; if it teaches your stack using the framework as scaffolding, move it. +3. **When referring to tooling, prefer general categories** ("a feature flag platform," "a data warehouse," "a CMS with structured content models") over specific products. Name specific products when the category needs concretization, and name multiple alternatives so readers see the category rather than locking into one vendor. +4. **Cross-references to specific tools or services should be sparse.** Each cross-reference should earn its inclusion through methodology relevance, not marketing value. If a cross-reference exists primarily to drive traffic, it is not earning its keep in a methodology skill. +5. **Run the audit checklist before merge.** Any specific code? Any type signatures matching your application? Any framework-specific patterns? If yes, move to internal playbook. + +--- + +## What stays internal + +Implementation specifics live somewhere; they just do not live in the public skill. Common locations: + +- Internal playbooks in private repositories +- Internal documentation in team wikis or knowledge bases +- Productized client deliverables produced by combining methodology plus playbook plus judgment +- Stack-specific reference implementations maintained as separate properties +- Onboarding materials for team members joining the implementation work + +The principle: anyone reading the public skill should be able to produce quality methodology-driven work on their own stack. Teams that want polished productized delivery in a specific stack do that work themselves, build their own internal playbooks, or engage practitioners who specialize in that delivery. The public skill is the upstream input; the implementation is the downstream work, owned by whoever is doing it. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md new file mode 100644 index 0000000..eb5f92f --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md @@ -0,0 +1,153 @@ +# Skill template + +A blank SKILL.md template with annotated guidance. Copy this, fill it in, and you have a skill that fits the pattern. + +## How to use this template + +1. Copy the YAML and structure below into a new file at `your-skill-name/SKILL.md`. +2. Replace the placeholder text in `[brackets]`. +3. Delete sections you do not need (most skills do not need every section). +4. Read the annotations to understand what each section is doing. +5. Test the skill on a real task. Iterate. + +## The template + +``` +--- +name: [your-skill-name] +description: [2-4 sentences. What the skill does. When to use it. "Also triggers when..." for edge cases. "Useful for..." for audience clarity.] +--- + +[One-sentence purpose statement. What this skill exists to do.] + +## When to use + +- [Trigger situation 1] +- [Trigger situation 2] +- [Trigger situation 3] +- [Trigger situation 4] + +## When NOT to use + +- [Situation that looks similar but should use a different skill] +- [Situation that is out of scope for this skill] +- [Sibling skill cross-reference: "For X, use the [other-skill] skill."] + +## Required inputs + +- [Information Claude needs from the user before it can do good work] +- [Or context Claude needs to gather] +- [Or files, links, or examples needed] + +## The framework + +[The durable IP. The model, dimensions, layers, principles that make this skill different from a freeform response. This is where the skill earns its keep.] + +[Format options: numbered list of layers, table of dimensions, hierarchy of concepts. Pick what fits the content.] + +## Workflow + +1. [First step Claude takes] +2. [Second step] +3. [Third step] +4. [...] +5. [Final step or output] + +## Failure patterns + +- **[Common mistake]**: [Why it happens, how to avoid]. +- **[Common mistake]**: [Why it happens, how to avoid]. +- **[Common mistake]**: [Why it happens, how to avoid]. + +## Output format + +Deliverables from this skill: + +1. **[Artifact 1]**: [What it is]. +2. **[Artifact 2]**: [What it is]. +3. **[Artifact 3]**: [What it is]. + +[Optional: notes on format, length, or delivery mechanism.] + +## Reference files + +- `references/[name].md`: [One-line description of what is in this reference]. +- `references/[name].md`: [One-line description]. +``` + +## Annotations: what each section is for + +### YAML frontmatter + +The `name` should match the folder name and use lowercase hyphens. The `description` is the most important field in the entire skill. It is what Claude sees in the system prompt to decide whether to load the skill body. Be specific about triggers. + +### Purpose statement (one sentence) + +This is the elevator pitch. A reader should know what the skill does after this one sentence. If you cannot summarize it in a sentence, the skill may be doing too much. + +### When to use + +Be concrete. List the actual situations where the skill should fire. These map to the trigger phrases in the description but in more detail. + +### When NOT to use + +Just as important as "when to use". This is where you redirect to sibling skills and prevent overlap. Without this section, related skills compete and Claude makes ambiguous choices. + +### Required inputs + +What does Claude need before it can do good work with this skill? Sometimes this is information ("the URL to audit"). Sometimes it is context ("the user's audience"). Listing it explicitly helps Claude ask the right question if it is missing. + +### The framework + +This is the durable IP. The thing that makes your skill better than a generic LLM response on the topic. A model, a set of dimensions, a hierarchy, a checklist of layers. + +If you cannot articulate the framework, the skill may be more about output structure than methodology. That is fine. Skip this section. + +### Workflow + +The numbered steps Claude follows when running the skill. Should be repeatable across different invocations. If the steps differ wildly per use case, you may need multiple skills or a more abstract framework. + +### Failure patterns + +What goes wrong in practice. This section is what makes a skill feel earned. It signals "we have done this many times and these are the mistakes". Specific failure patterns are more useful than abstract ones. + +### Output format + +What the deliverable looks like. Not "good output" - actually structured and named. This is what Claude produces at the end. + +### Reference files + +The list of `references/` files with brief descriptions. Each reference should be standalone and useful even if read out of order. + +## Sizing guidance + +| Component | Target | Hard limit | +| --- | --- | --- | +| Description | 2-4 sentences | 1 paragraph | +| SKILL.md total | Under 250 lines | 500 lines | +| Single reference file | Under 400 lines | 800 lines | +| Number of references | 1-3 | 5 | + +If you are over the targets, split or trim. Skills get heavier and more brittle as they grow. + +## Naming conventions + +- Skill folder: `lowercase-hyphenated` +- SKILL.md: always exactly `SKILL.md` (case-sensitive) +- References: `references/[name].md` +- Templates: `[noun]-template.md` +- Checklists: `[noun]-checklist.md` +- Playbooks: `[noun]-playbook.md` +- Examples: `example-[scenario].md` + +## Common adaptations + +Not every skill needs the standard structure. Examples of valid adaptations: + +- **Pure how-to skill**: skip the "framework" section, lead with workflow. +- **Pure template skill**: skip framework and workflow, focus on the structure of the output. +- **Audit skill**: heavy on the framework (the dimensions to score), lighter on workflow. +- **Walkthrough skill**: numbered phases as the spine, no separate framework section. +- **Decision skill**: heavy on options and tradeoffs, lighter on workflow. + +The structure exists to make sure you cover the right ground. If a section does not earn its place, drop it. But know what you are dropping and why. diff --git a/dist/pi/.agents/skills/stakeholder-communication/SKILL.md b/dist/pi/.agents/skills/stakeholder-communication/SKILL.md new file mode 100644 index 0000000..f5a1950 --- /dev/null +++ b/dist/pi/.agents/skills/stakeholder-communication/SKILL.md @@ -0,0 +1,360 @@ +--- +name: stakeholder-communication +description: "Communicate effectively with stakeholders across functions and seniority levels. Use this skill when writing status updates, preparing executive reviews, sharing technical decisions with non-technical audiences, managing up, communicating bad news, or designing the communication cadence for a project. Triggers on stakeholder update, status report, executive summary, exec review, manage up, communicate bad news, project comms, status meeting, weekly update. Also triggers when a project is going off track and the team needs to communicate it." +category: process-and-team +catalog_summary: "Status updates, exec readouts, project communications" +display_order: 1 +--- + +# Stakeholder Communication + +Get the right information to the right people at the right time, in a form they can act on. Stack-agnostic. Applies to any team operating with cross-functional stakeholders. + +--- + +## When to use + +- Writing weekly or monthly status updates +- Preparing for an executive review or board update +- Sharing a technical decision with a non-technical audience +- Communicating a delay, miss, or quality problem +- Asking for help, resources, or decisions +- Managing up to a manager or sponsor +- Designing the communication cadence for a project +- Drafting an internal announcement + +## When NOT to use + +- Customer-facing communication (use marketing/support skills) +- Public comms or press (different framework, different stakes) +- Incident communication during an active incident (use `incident-response`) +- Internal documentation that isn't time-sensitive (use `documentation-strategy`) +- Specific delivery formats (slide deck design, email tone) - this skill is about content and structure + +--- + +## Required inputs + +- The audience (who specifically, what's their context, what do they care about) +- The purpose (inform, decide, escalate, ask, celebrate) +- The substance (what's actually happening) +- The medium (email, doc, meeting, slide, chat) +- Time constraints (when do they need this) + +--- + +## The framework: 5 questions + +Before any stakeholder communication, answer: + +### Question 1: Who is the audience? + +Specifically. "Leadership" is too vague. The CFO and the VP of Engineering have different concerns. + +For each named audience: +- What do they care about? (revenue, risk, quality, velocity, costs, customers) +- What do they already know? (background you can skip) +- What's their level of detail tolerance? (executives want headlines; ICs want details) +- What action do you want from them? (acknowledgment, decision, help, no action) + +### Question 2: What's the headline? + +If they read only one sentence, what should they take away? + +The headline goes first. Always. The narrative supports it; the data confirms it. + +This is the biggest gap in most stakeholder communication: people start with context and build to a conclusion. Stakeholders want the conclusion first. + +### Question 3: What's the so-what? + +Stakeholders ask "and?" implicitly. Answer it explicitly. + +- "We hit 80% of the milestone." → so what? +- "We hit 80% of the milestone, which puts the launch one week behind plan." → that's the so-what. + +The so-what makes the information actionable. + +### Question 4: What do you want? + +Communications generally have one of these requests: + +- **Inform:** no action needed. Just keeping them in the loop. +- **Decide:** a decision is needed; here are the options and recommendation. +- **Escalate:** something is stuck; we need help. +- **Ask:** a specific request (resource, introduction, review). +- **Celebrate:** a win to share; no action needed but morale matters. + +State which. Don't bury the request. + +### Question 5: What format? + +- **Async written** (doc, email): rich content, decision trail, easy to reference +- **Sync written** (chat, ticket comment): quick exchange, conversational +- **Sync spoken** (meeting, call): nuance, debate, alignment +- **Mixed** (doc + meeting): the doc is read in advance; meeting is decision + +For most updates: async written. Save sync time for actual discussion. + +--- + +## The structure: the inverted pyramid + +Stakeholder communication reads like a news article, not an essay. + +``` +Headline (one sentence) + +The "so what" and the request (one paragraph) + +Status / progress (the body) + +Risks and asks (what we need) + +Detail / appendix (what curious readers want) +``` + +Cut from the bottom. If your update gets shortened, the top survives. + +--- + +## Update templates + +### Weekly project update + +``` +**Project:** [Name] +**Status:** [On track / At risk / Off track] +**Headline:** [One-sentence summary] + +**This week:** +- [Specific accomplishment] +- [Specific accomplishment] +- [Specific accomplishment] + +**Next week:** +- [Specific plan] +- [Specific plan] + +**Risks / blockers:** +- [Risk + what we're doing about it / what we need] + +**Metrics:** +- [Metric: value vs target] +- [Metric: value vs target] +``` + +The status indicator (on track / at risk / off track) is essential. Stakeholders scan for it. + +### Executive review + +``` +**Headline:** [The summary, one sentence] + +**Key points:** +1. [Point with one supporting sentence] +2. [Point with one supporting sentence] +3. [Point with one supporting sentence] + +**Decisions needed:** +- [Decision A: options and recommendation] +- [Decision B: options and recommendation] + +**Asks:** +- [Specific request] + +**Detail:** [Linked doc or appendix] +``` + +Executives skim. They click into detail when interested. + +### Bad news + +The hardest update to write well. + +``` +**Headline:** [The bad news, plainly stated] + +**What happened:** +[Specific facts, no euphemisms] + +**Impact:** +[Who's affected, how much, by when] + +**What we're doing:** +[Specific actions and owners] + +**What we need:** +[Specific asks, if any] + +**Timeline:** +[When the next update will land] +``` + +Don't soften the headline. Soft headlines on bad news erode trust faster than the news itself. + +### Decision request + +``` +**Decision:** [What needs to be decided] + +**Context:** [The minimum needed to understand] + +**Options:** +1. [Option A: description, pros, cons] +2. [Option B: description, pros, cons] +3. [Option C: description, pros, cons] + +**Recommendation:** [Option X, because...] + +**Need by:** [Date] +**Decision rights:** [Who decides] +``` + +Recommendation matters. Not making one is putting the work back on the decider. + +--- + +## Tone and register + +### Across audiences + +| Audience | Tone | Detail | Length | +|---|---|---|---| +| Direct manager | Candid, briefer | Mid | Medium | +| Skip-level / VP | Polished, sharper | Low | Short | +| Cross-functional peer | Collaborative, specific | Mid-high | Medium | +| Executive / board | Headlines, confident | Low (with detail available) | Short | +| Team / IC stakeholders | Detailed, direct | High | Long | + +### What to avoid + +- **Hedging when confident.** "I think maybe we might be able to..." Just say what you mean. +- **Confidence when uncertain.** "Definitely launching Friday" when there's risk. Calibrate. +- **Jargon for non-technical audiences.** Replace with plain language. +- **Burying the lede.** Headline first. +- **Implicit asks.** State explicitly what you want. +- **Status updates that are 90% activity, 10% outcome.** Focus on outcomes; activity is supporting evidence. + +--- + +## Workflow + +### Step 1: Define the audience and purpose + +Before writing, answer Q1-Q5 above. Often this clarifies the message before any drafting. + +### Step 2: Draft the headline + +One sentence. The takeaway. If you can't write the headline, you don't know yet what you're communicating. + +### Step 3: Write inverted pyramid + +Headline, so-what, body, asks, detail. + +### Step 4: Cut + +A first draft is usually 30-50% too long. + +- Cut activities that don't have outcomes +- Cut adjectives (great, awesome, excellent, exciting) +- Cut filler (just, really, very, actually) +- Cut hedging (kind of, sort of, somewhat) when confident +- Cut sentences that don't add information + +### Step 5: Verify the request + +Reread. Is the ask clear? Is it specific? Is the deadline named? + +### Step 6: Check the audience + +Imagine the recipient reading. Will they understand the headline? Have you skipped context they need? Have you given context they don't need? + +### Step 7: Send and follow up + +After sending: +- Did the right people see it? Acknowledge the right channel. +- Did they understand? Watch for confused replies; address them. +- Did they act? Follow up on stale asks. + +--- + +## Cadence design + +Different audiences need different cadences. + +### High-frequency (weekly or more) + +- Direct team, manager, sponsor +- Active project stakeholders +- People making day-to-day decisions + +### Medium-frequency (biweekly to monthly) + +- Skip-level +- Cross-functional partners +- Adjacent teams +- Strategic stakeholders + +### Low-frequency (quarterly) + +- Executive review +- Board update +- Wider organization +- External stakeholders (where relevant) + +The right cadence is what's needed, not what fills the calendar. Update people when there's something new; don't manufacture updates. + +--- + +## Failure patterns + +**Long preamble before the point.** Three paragraphs of context, then the one sentence that mattered. Lead with the point. + +**Status: yellow.** Same status three weeks in a row. Yellow with no change is red. Be honest about progress. + +**Update without a clear ask.** "We're working on it." OK, what do you want? If nothing, say "no action needed." + +**Sandwiching bad news in good news.** "We've done X and Y, and unfortunately Z is delayed, but we've also done W." The bad news gets lost. Lead with it if it's the headline. + +**Walls of text.** Too long, unread. Cut to the structure. + +**Activity vs outcome.** "Met with team. Reviewed plan. Updated tickets." So what? "Cut scope to hit launch date" is an outcome. + +**Different update for every audience.** Maintaining 5 versions doubles work. Have one core update; tailor the framing. + +**Status update that's actually a request.** Buries an ask in a wall of status. Pull the ask out. Make it visible. + +**Optimistic projections.** "We'll be back on track next week." Then we're not. Then again. Trust erodes. Be honest about the path. + +**No follow-up on asks.** Asked for a decision; didn't get one; moved on. Now the project is stuck. Follow up. + +**Communicating bad news only when forced to.** Stakeholders find out from someone else, or from a missed deadline. Lose trust. Communicate proactively. + +**Performative comms for the audience of one.** Every update reads like a sales pitch to the boss. Stakeholders see through it. Be direct. + +**No comms when no news.** Silence is worse than "no change this week." Set expectations on cadence and stick to it. + +--- + +## Output format + +A communication plan for a project includes: + +- **Stakeholder map:** named people, their interests, their decision rights +- **Cadence:** what updates go to whom, how often +- **Templates:** standardized formats for repeated updates +- **Escalation paths:** who to involve when something's at risk +- **Decision log:** running record of decisions made, by whom, why + +For individual communications: + +- **Headline:** the takeaway +- **Body:** the supporting structure +- **Ask:** the request, explicitly +- **Distribution:** who gets it, in what form + +--- + +## Reference files + +- [`references/update-templates.md`](references/update-templates.md): Ready-to-use templates for the most common stakeholder communications, with annotated examples. diff --git a/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md b/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md new file mode 100644 index 0000000..70d88d4 --- /dev/null +++ b/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md @@ -0,0 +1,452 @@ +# Update Templates + +Ready-to-use templates for the most common stakeholder communications. Annotated with what each section is doing. + +Adapt to your house style. The structure matters more than the exact wording. + +--- + +## Template 1: Weekly project status + +For internal teams, manager, sponsor. Sent same day each week. + +``` +Subject: [Project] weekly update: [date] + +**Status: On track** + +We're on plan to ship [milestone] by [date]. + +This week: +- Shipped [specific outcome] +- Started [specific work], [N]% complete +- Decision: chose [option] for [problem] + +Next week: +- Complete [specific work] +- Begin [specific work] +- Review: [decision needed by sponsor] + +Risks: +- [Risk]: [what we're doing about it] + +Asks: +- [Specific ask, if any] + +Detail: [link to project doc] +``` + +**Annotations:** +- Status indicator (On track / At risk / Off track) is the first thing readers scan +- "This week" is outcomes, not activities +- "Next week" is specific commitments, not vague intentions +- Risks have plans attached +- Asks are explicit and called out + +--- + +## Template 2: At-risk update + +When the project is no longer comfortably on track. + +``` +Subject: [Project] update: at risk for [milestone] + +**Status: At risk** + +The [milestone] target of [date] is at risk because [specific reason]. + +What's happening: +- [Fact 1] +- [Fact 2] +- [Fact 3] + +Impact: +- If we miss by a week: [specific impact] +- If we miss by a month: [specific impact] + +What we're doing: +- [Action 1] (owner: [name], by: [date]) +- [Action 2] (owner: [name], by: [date]) + +What we need from you: +- [Specific decision or help] + +Next update: [date] +``` + +**Annotations:** +- Doesn't pretend to be on track +- Names the specific cause +- Quantifies the impact +- Has a plan with owners and dates +- Has a clear ask +- Sets expectations for next update + +--- + +## Template 3: Off-track / missed milestone + +When the milestone has been missed or will be. + +``` +Subject: [Project] off track: [milestone] will miss [date] + +**Status: Off track** + +We will miss the [date] milestone for [specific reason]. Revised target: [new date]. + +What happened: +[2-3 sentences of what specifically caused the miss. Direct, no euphemisms.] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we're doing: +- [Action 1] +- [Action 2] + +Lessons we're applying: +- [Lesson learned] + +What we need: +- [Specific ask, if any] + +Next milestone: [date for the next checkpoint] +``` + +**Annotations:** +- States the miss in the headline +- Names cause without scapegoating +- Quantifies impact +- Has a plan +- Includes lessons (shows learning, builds trust) +- Sets the next checkpoint + +--- + +## Template 4: Decision request + +When you need a decision from a stakeholder. + +``` +Subject: Decision needed: [decision] by [date] + +**The decision:** [What needs to be decided] + +**Context (60 seconds):** +[The minimum needed for someone to understand. Include only what's relevant.] + +**Options:** + +Option A: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option B: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option C: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +**Recommendation:** Option [X], because [reason]. + +**Need by:** [Date] + +**Detail:** [Link to fuller analysis] +``` + +**Annotations:** +- The decision is named at the top +- Context is bounded (60 seconds) +- Options are parallel in structure +- Recommendation is explicit +- Deadline is named + +--- + +## Template 5: Executive review + +For exec audiences: monthly, quarterly, or per major milestone. + +``` +Subject: [Initiative] exec review: [date] + +**Headline:** [One-sentence summary of the state of things] + +**Key points:** + +1. [Point 1 with one supporting sentence] +2. [Point 2 with one supporting sentence] +3. [Point 3 with one supporting sentence] + +**Metrics:** + +| Metric | Target | Actual | Trend | +|---|---|---|---| +| [Metric 1] | [Target] | [Actual] | ↑/↓/→ | +| [Metric 2] | [Target] | [Actual] | ↑/↓/→ | +| [Metric 3] | [Target] | [Actual] | ↑/↓/→ | + +**Decisions needed:** +- [Decision 1: brief context, options summary, recommendation] +- [Decision 2: brief context, options summary, recommendation] + +**Risks:** +- [Top risk and mitigation] + +**Asks:** +- [Specific ask] + +**Detail:** [Link to fuller documentation] +``` + +**Annotations:** +- Executives skim. Headline carries the load. +- 3 key points (not 7) +- Metrics in table form, with trend +- Decisions called out, with recommendations +- Detail is linked, not inlined +- One page max for the email body + +--- + +## Template 6: Launch announcement (internal) + +For announcing something shipped. + +``` +Subject: Launched: [Thing] + +We've launched [Thing]. + +What it is: +[1-2 sentences of plain description. What it does, who it's for.] + +Why it matters: +[1-2 sentences of impact. What problem it solves, what changes.] + +How to learn more: +- [Link to docs / demo / page] +- [Contact for questions] + +Thanks to: +[The team that did the work, by name] +``` + +**Annotations:** +- Short and clear +- Includes the why (not just the what) +- Acknowledges the team + +--- + +## Template 7: Asking for help + +When you need expertise, time, or introduction from a colleague. + +``` +Subject: [Specific ask]: [N] minutes + +Hi [Name], + +I'm working on [brief context, one sentence]. I'd value your help with [specific ask]. + +What I need: +- [Specific item 1] +- [Specific item 2] + +What I've already tried: +- [Approach 1, outcome] +- [Approach 2, outcome] + +Time I'm asking for: [N minutes / specific session / specific deliverable] +Need by: [Date or "no rush"] + +If you're not the right person, who would you suggest? + +Thanks, +[Name] +``` + +**Annotations:** +- Subject is specific +- Specific ask, not vague +- Shows you've tried (respect for their time) +- States time required +- Provides an out (suggest someone else) + +--- + +## Template 8: Update for skip-level / VP + +For your manager's manager. Shorter, sharper than direct-manager update. + +``` +Subject: [Initiative]: quick update + +[Initiative] is [on track / at risk] for [milestone]. + +Highlights: +- [Outcome 1] +- [Outcome 2] +- [Decision: what was decided] + +What's coming: +- [Next big milestone] + +Risks I'm watching: +- [Top risk] + +I'll come to you for: [specific upcoming need] + +Detail: [link] +``` + +**Annotations:** +- Half the length of a manager update +- Emphasizes outcomes, not activities +- "I'll come to you for" sets expectations on when you'll need them +- Detail is linked, not inlined + +--- + +## Template 9: Quarterly business review (QBR) + +Cross-functional, leadership audience. Substantive. + +``` +Subject: [Function/team] QBR: Q[N] + +**Quarter at a glance:** + +[3-sentence narrative summarizing the quarter] + +**Goals vs results:** + +| Goal | Target | Result | Status | +|---|---|---|---| +| [Goal 1] | [Target] | [Result] | ✅ / 🟡 / ❌ | +| [Goal 2] | [Target] | [Result] | ✅ / 🟡 / ❌ | +| [Goal 3] | [Target] | [Result] | ✅ / 🟡 / ❌ | + +**Wins this quarter:** +- [Specific win 1] +- [Specific win 2] +- [Specific win 3] + +**What didn't go as planned:** +- [Specific miss 1: what happened, what we learned] +- [Specific miss 2: what happened, what we learned] + +**Next quarter:** +- [Top priority 1] +- [Top priority 2] +- [Top priority 3] + +**Risks and asks:** +- [Risk and what we're doing] +- [Ask if any] + +**Headcount / budget changes:** +[If relevant, brief] +``` + +**Annotations:** +- Narrative summary up front +- Goals table with clear pass/fail +- Wins AND misses (honest) +- Forward-looking section +- Asks are explicit + +--- + +## Template 10: Bad news, broader audience + +For when something significant has gone wrong and a wider audience needs to know. + +``` +Subject: [Plain description of what happened] + +[1 sentence: what happened, in plain language] + +What happened: +[2-4 sentences of specific facts. No euphemisms.] + +Who's affected: +- [Specific group 1] +- [Specific group 2] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we've done so far: +- [Action 1] +- [Action 2] + +What's next: +- [Action and timeline] +- [Action and timeline] + +If you have questions: +[Contact and channel] + +[Sign-off from named accountable person, with their role] +``` + +**Annotations:** +- Plain subject. No spin. +- Facts before reassurance +- Impact stated, not hedged +- Forward path is clear +- Named accountable person at the bottom +- Channel for questions + +--- + +## What to avoid in any template + +**Vague status indicators.** "Things are going well" is not status. On track / at risk / off track is. + +**Activity dumps.** "We met. We reviewed. We updated." Stakeholders care about what changed, not what you did. + +**Hedge words on certainty.** "We should probably maybe be on track." If you know, say it. If you don't, say what you don't know. + +**Buried asks.** Asks at the bottom in a paragraph go unread. Pull them out. Bold them. Make them findable. + +**Different units in different sections.** "5 days" in one place, "by next Tuesday" in another. Pick a convention and stick with it. + +**Acronyms not understood by the audience.** Especially across functions. Spell out on first use. + +**No links.** Detail in the email forces everyone to read the same wall of text. Link the detail. Let people choose. + +**Missing accountable owner.** Who owns each next step? If the answer is "the team," nothing happens. Name people. + +**Inconsistent cadence.** Update Monday, then nothing for three weeks, then a wall on a Friday. Set cadence. Hold it. + +--- + +## Customizing for your context + +The templates above are starting points. Customize for: +- Your organization's tone (formal vs casual) +- Your stakeholders' preferences (some want bullets, some want narrative) +- Your medium (email vs doc vs slide) +- Your project's complexity (more or less detail in the body) + +Whatever you customize, keep: +- Headline first +- Status indicator visible +- Asks explicit +- Owners and dates named +- Consistent structure across updates (so readers can scan reliably) diff --git a/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md b/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md new file mode 100644 index 0000000..180e5c4 --- /dev/null +++ b/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md @@ -0,0 +1,189 @@ +--- +name: team-onboarding-playbook +description: Design a structured onboarding experience that gets new team members productive in 30, 60, and 90 days. Use when a new hire is joining, when contractors or agency partners need to ramp up, when an existing team is restructuring and members are switching focus, or when current onboarding feels chaotic and slow. Also triggers when one person owns all the tribal knowledge and you need to capture it, when you keep losing people in their first 90 days, or when a new project has many fresh members joining at once. Useful for engineering, design, product, marketing, and operations roles. +category: process-and-team +catalog_summary: "30-60-90 onboarding plans for new hires and contractors" +display_order: 4 +--- + +A repeatable framework for building an onboarding playbook that ramps new team members predictably without burning out the people training them. + +## When to use + +- A new hire is joining and you do not have a written onboarding plan. +- An existing onboarding process is informal and inconsistent. +- A team is growing fast and onboarding is the bottleneck. +- A contractor or agency partner needs to ramp up quickly. +- A team member is leaving and their knowledge needs capturing. +- Onboarding currently takes too long and you want to reduce it. + +## When NOT to use + +- For ongoing performance management (different problem). +- For training on a specific technology (use targeted docs and tutorials). +- For documentation strategy in general (use `documentation-strategy`). +- For role definition or hiring (different upstream problem). + +## Required inputs + +- The role: what the person will do, what success looks like at 90 days. +- Existing artifacts: docs, runbooks, codebases, design files. +- The team: who will mentor, who will pair, who answers what kind of question. +- Tools and access: what accounts and systems the new person needs. +- Time budget: how much time team members can invest in onboarding. + +## The framework + +A good onboarding plan operates on 4 layers. Build all four. + +### Layer 1: Belonging (Day 1 to Week 1) + +The first week is mostly about belonging, not productivity. Get this right and everything else accelerates. + +- Welcome message before they start. +- Workspace and accounts ready before day 1. No "we will get to that". +- A buddy or onboarding partner assigned (someone other than the manager). +- Day 1 schedule that is not 8 hours of meetings, but is also not zero meetings. +- Introductions to the people they will work with regularly. +- A first-week rhythm: daily check-in with manager or buddy. + +### Layer 2: Context (Week 1 to Week 4) + +The next phase is context. The new person needs to understand the system before they can change it. + +- The product or business: what we do, who we serve, why we exist. +- The team: who owns what, how decisions get made. +- The technical or operational landscape: the architecture diagram, the main tools, the key files. +- The recent past: major decisions, recent launches, current priorities. +- Active projects: what is in flight and how it fits. + +A reading list is part of this. Keep it short. Annotated. Curated. + +### Layer 3: Contribution (Week 2 to Week 6) + +By week 2 or 3, the new person should be making real contributions. Not because they are fully ramped, but because contribution is how ramping happens. + +- A first task that is small, scoped, and shippable in week 2. +- Pairing or shadowing on a real piece of work in week 3. +- Independent ownership of a small project by week 4 or 5. +- Code review, design critique, or equivalent peer feedback from the start. + +The first task matters. Pick something that touches the main systems but cannot break anything important. Something that ships gives confidence and visibility. + +### Layer 4: Mastery (Month 2 to Month 3) + +By the end of 90 days, the new person should be a full member of the team. + +- Owning a project end to end. +- On-call or on-rotation if the team has one. +- Contributing to roadmap discussions, not just executing them. +- Mentoring or supporting the next new hire. + +90 days is a checkpoint, not a finish line. Document what worked and what was missing for the next person. + +## The 30/60/90 plan + +Every onboarding plan should have explicit milestones at 30, 60, and 90 days. + +### 30 days + +- Workspace, tools, and access fully set up. +- Has met every team member. +- Understands the product, the team, and the recent context. +- Has shipped or contributed to at least one real piece of work. +- Has a clear picture of their first major project or area. + +### 60 days + +- Owns a project or area independently. +- Knows where to find answers without asking every time. +- Has formed working relationships beyond the immediate team. +- Has made at least one meaningful improvement to a process, doc, or codebase. + +### 90 days + +- Fully productive in the role. +- Participating in roadmap and planning discussions. +- Capable of training the next new hire on parts of the system. +- Comfortable raising concerns and pushing back. + +If someone is significantly behind these markers at the 30/60/90 checkpoints, address it directly. Either the plan is wrong, the support is wrong, or the role fit is wrong. Hoping it resolves itself does not work. + +## The role-specific overlay + +The framework above applies to every role. The specifics differ. + +### Engineering + +- Day 1: dev environment running, first commit (a docs fix or trivial change). +- Week 1: read the architecture doc, read the main service code paths. +- Week 2: ship a small bug fix or refactor. +- Week 4: own a feature or component. +- Month 2: on-call shadow, then on-call. + +### Design + +- Day 1: design tools set up, design system access, brand guidelines reviewed. +- Week 1: studio crit and design review participation. +- Week 2: own a small surface (a setting page, an empty state). +- Week 4: lead a design review for a feature in flight. +- Month 2: own a feature design end to end. + +### Product + +- Day 1: read the strategy doc, the roadmap, and the latest 3 PRDs. +- Week 1: shadow customer calls, attend support sync, join standup of all relevant teams. +- Week 2: write a discovery doc or competitive analysis. +- Week 4: own a feature spec. +- Month 2: own a roadmap area. + +### Marketing or content + +- Day 1: brand voice doc, recent campaigns, top performing content. +- Week 1: customer research artifacts and persona docs. +- Week 2: ship a small piece of content (a social post, a blog edit). +- Week 4: own a content piece end to end. +- Month 2: own a campaign or channel. + +Adapt to your role and stack. The shape stays the same. + +## Workflow + +1. Start the playbook before the new person arrives. Do not write it on day 1. +2. Pre-stage accounts, hardware, and access. This is the most common day-1 failure point. +3. Assign a buddy. Tell the buddy what is expected of them. +4. Send the welcome message and the day-1 schedule before they start. +5. Run the first week with a focus on belonging and context, not output. +6. Check in daily for the first week, weekly for the first month. +7. Run formal 30/60/90 check-ins with explicit milestones. +8. After 90 days, do a retrospective: what worked, what was missing. +9. Update the playbook based on the retrospective. Onboarding is a living doc. + +## Failure patterns + +- **No plan.** Day 1 with no schedule, no laptop, no accounts. Sets a tone. +- **Drinking from a firehose.** 8 hours of meetings on day 1. People remember nothing. +- **No real work for too long.** Three weeks of "reading docs" is demoralizing. Ship something small early. +- **All buddy, no manager.** Buddies are great but cannot evaluate or advocate. Manager is still on the hook. +- **Tribal knowledge as gating.** "Just ask Sara if you have questions" works until Sara is on vacation. Document the answers Sara keeps giving. +- **No 30/60/90 milestones.** Onboarding "ends" when someone seems busy. That is not a milestone. +- **Generic plan for every role.** Engineering and marketing have different first-week needs. Use the role overlay. +- **No retrospective.** The same gaps catch every new hire because nobody updated the playbook. +- **Buddy with no time.** Assigning a buddy who is also drowning is a recipe for poor onboarding and burnout. Protect their time. +- **Skipping the customer or product context.** Engineers who do not know who the customer is build the wrong things. Marketers who do not know how the product works write thin copy. + +## Output format + +Deliverables: + +1. **Pre-day-1 checklist**: accounts, hardware, access, buddy assignment, welcome message. +2. **Day-1 schedule**: meeting list, intros, first deliverable. +3. **First-week reading list**: 5-10 curated, annotated docs. +4. **30/60/90 milestones**: the explicit checkpoints for this role. +5. **Buddy guide**: what is expected of the onboarding partner. +6. **Manager check-in cadence**: scheduled 1:1s and milestone reviews. +7. **Retrospective template**: to fill out at 90 days for next-time improvement. + +## Reference files + +- [`references/onboarding-checklist.md`](references/onboarding-checklist.md): A day-by-day, week-by-week checklist for the first 30 days, with role-specific variants and a 30/60/90 review template. diff --git a/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md b/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md new file mode 100644 index 0000000..c82acb7 --- /dev/null +++ b/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md @@ -0,0 +1,214 @@ +# Onboarding checklist + +A day-by-day, week-by-week checklist for the first 30 days. Adapt the role-specific items to fit your team. + +## Before day 1 (1 week ahead) + +Manager prep: + +- [ ] Confirm start date and any logistics (remote, hybrid, in-office). +- [ ] Assign onboarding buddy. Brief them on expectations. +- [ ] Order hardware. Confirm delivery before start date. +- [ ] Create accounts: email, chat, source control, design tools, project management, calendar, password manager. +- [ ] Add to relevant team channels and meeting invites. +- [ ] Block manager calendar for daily check-ins in week 1. +- [ ] Send welcome email to new hire 3-5 days before start. Include: day-1 logistics, what to expect, where to be, what to bring. +- [ ] Notify the team via channel: who is starting, when, what role. +- [ ] Prep first task. Something small, scoped, shippable in week 1 or 2. + +## Day 1 + +Morning: + +- [ ] Welcome from manager (30 min, not 90 min). +- [ ] Tour of tools, accounts, and where things live. +- [ ] Lunch with buddy or team (whatever is normal for your team). + +Afternoon: + +- [ ] Read the welcome doc or onboarding hub. +- [ ] Set up local environment. Buddy or buddy-channel available for help. +- [ ] First commit, design upload, doc edit, or equivalent. Trivial. Just to validate the workflow. + +End of day: + +- [ ] 15-minute check-in with manager. How did it go. + +## Week 1 + +Goals: belonging and basic context. Not productivity. + +- [ ] Daily 15-minute check-in with manager. +- [ ] 1:1 with buddy at least twice. +- [ ] Read the curated reading list (5-10 docs, no more). +- [ ] Meet with 5-7 people they will work with. 30 minutes each. Casual. +- [ ] Attend team standup and one team meeting (without obligation to contribute). +- [ ] Submit at least one trivial fix or improvement (typo, doc clarification, small refactor). +- [ ] Set up time tracking, expense, or admin systems if your org uses them. +- [ ] Confirm hardware, software, and access are all working. + +End of week 1: + +- [ ] Manager check-in: what is unclear, what felt wrong, what is missing. + +## Week 2 + +Goals: contributing to real work, even in a small way. + +- [ ] Pair with a teammate on a real task. Half day to a full day. +- [ ] Take ownership of the first small task. Should be shippable in 3-5 days. +- [ ] Attend customer call, support sync, or equivalent customer touchpoint. +- [ ] Read the recent decision log or major PRDs from the last 3 months. +- [ ] First contribution to standups: what they are working on. + +End of week 2: + +- [ ] Manager check-in: how is the first task going. What is blocking. What feels overwhelming. + +## Week 3 + +Goals: independent ownership starts. + +- [ ] Ship the first small task. +- [ ] Take on a slightly larger task. 1-2 weeks of work. +- [ ] Participate in code review, design critique, or equivalent. +- [ ] Meet with 3-5 cross-functional partners (PM ↔ Eng, Design ↔ PM, etc.). +- [ ] Begin to recognize patterns: "this is the third time someone asked X, where is that documented?" + +End of week 3: + +- [ ] Buddy check-in: how is the experience. What is the new hire stuck on that they will not raise to the manager. + +## Week 4 / 30-day mark + +Goals: validate the ramp is on track. + +- [ ] Complete the first medium-sized project or be visibly in flight. +- [ ] Have a working mental model of the product, team, and stack. +- [ ] Have at least one improvement filed (a doc fix, process suggestion, automation). +- [ ] Manager 30-day review (see template below). + +## 30-day review + +Manager runs this with the new hire, in 1:1, around day 30. + +``` +30-day review for [name] + +What is going well: +- [Two or three things] + +What is unclear or hard: +- [Two or three things] + +What I have shipped or contributed to: +- [List] + +What I want to be doing more of: +- [List] + +What I want help with: +- [List] + +Manager observations: +- [What you have noticed] + +Action items: +- [Specific things to address before 60-day mark] +``` + +The output of the 30-day review is honest signal. If the new hire is behind, the manager addresses the cause, not the symptom. If they are ahead, accelerate. + +## 60-day milestones + +By day 60: + +- [ ] Owning a project or area independently. +- [ ] Asking targeted questions, not "how does anything work" questions. +- [ ] Has working relationships outside the immediate team. +- [ ] Has been on customer or user calls if applicable. +- [ ] Has flagged at least one process improvement. +- [ ] 60-day review complete. + +## 90-day milestones + +By day 90: + +- [ ] Fully productive in the role at expected level. +- [ ] Participating in planning and roadmap discussions. +- [ ] On call or on rotation if the team has one. +- [ ] Capable of teaching parts of the system to a peer. +- [ ] Has identified gaps in onboarding from their perspective. +- [ ] 90-day review and onboarding retrospective complete. + +## 90-day onboarding retrospective + +Run this with the new hire at the end of 90 days. Capture the answers. Update the playbook. + +``` +What was great about your onboarding: +- [List] + +What was confusing or hard: +- [List] + +What was missing: +- [List] + +What you would have liked on day 1: +- [List] + +What you would change for the next person: +- [List] + +What you wish you had known earlier: +- [List] +``` + +The output of this retro feeds the next version of the playbook. Without this loop, every new hire faces the same gaps. + +## Role-specific first tasks + +Examples of good first tasks (shippable in week 1-2): + +### Engineering + +- Fix a small bug from the bug tracker (not customer-blocking, but real). +- Add a missing test or improve a flaky one. +- Update a deprecated API call in one place. +- Improve a developer doc that has been out of date. + +### Design + +- Audit a small part of the product against the design system. +- Design an empty state, error state, or settings sub-page. +- Update an outdated illustration or asset. +- Document a component that is in production but not in the design system. + +### Product + +- Write a competitive analysis on one feature area. +- Document a customer pain point heard in support. +- Update a stale PRD with current state. +- Write a one-pager on a roadmap item that needs sharper framing. + +### Marketing / Content + +- Edit and update a stale blog post. +- Audit recent campaign performance and write a 1-page summary. +- Repurpose an existing piece of content into a new format. +- Write a short customer quote roundup or testimonial summary. + +The pattern: real, scoped, ships in days, low risk, builds context. + +## What "fully ramped" looks like + +A new hire is fully ramped when: + +- They no longer ask "how does this work" but "why was it built this way". +- They contribute to direction, not just execution. +- They identify gaps and fill them without being asked. +- They mentor or assist the next new hire. +- They push back on things that do not make sense. + +This usually lands somewhere between 90 and 180 days, depending on the role and the system's complexity. Track it. If 180 days passes and the person is still not at this bar, dig into why. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md b/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md new file mode 100644 index 0000000..da26f0f --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md @@ -0,0 +1,309 @@ +--- +name: upgrade-flow-design +description: "Designing free-to-paid conversion flows for SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. Honest about paywall-everywhere (gates everything aggressively), free-forever-trap (no upgrade path surfaces), and value-triggered-upgrade (paywall surfaces at moments of demonstrated value) patterns. Triggers on upgrade flow, paywall, free-to-paid, freemium conversion, trial conversion, plan upgrade, subscription upgrade, win-back flow, churn prevention. Also triggers when free-to-paid conversion is low, when paywalls are blocking the wrong moments, or when upgrade flows are being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing free-to-paid conversion flows. Distinguishes paywall-everywhere (gates everything aggressively) from free-forever-trap (no upgrade path surfaces) from value-triggered-upgrade (paywall surfaces at moments of demonstrated value)" +display_order: 9 +--- + +# Upgrade Flow Design + +A senior product marketing director's playbook for designing free-to-paid conversion flows in SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. The discipline of asking for the upgrade at the moment the user has a reason to say yes. + +Most upgrade flows fail in one of two ways. They block meaningful product use behind paywalls so aggressively that users churn before reaching the moment that would justify paying. Or they offer a generous free tier with no upgrade path that ever surfaces; users get everything they need; conversion stays at single-digit percentages indefinitely. + +The upgrade flows that work do something different. They surface paywalls at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next; the user is positioned to say yes because the value is fresh. + +The voice is the senior product marketing director who has watched conversion rates double when paywalls were re-timed and watched them collapse when more aggressive paywalls were added. Practical, opinionated about the moments that earn the upgrade ask, willing to call out when the product's free tier is too generous to convert. + +When to use this skill: scoping a free-to-paid conversion flow for the first time, auditing paywalls that block conversion or never surface, designing the trigger moments that earn upgrade asks, or deciding plan structure that supports upgrades over time. + +--- + +## What this skill covers + +This skill spans free-to-paid conversion flows in SaaS products. The growth-tooling distinctions: + +- `lead-magnet-design` is top-of-funnel email capture. This skill is free-to-paid conversion in-product. +- `funnel-flow-architecture` is the cross-tool funnel architecture. This skill is the upgrade flow specifically. +- **`upgrade-flow-design` (this skill)** is trigger-moment design, paywall presentation, plan structure, win-back, churn prevention. +- `landing-page-copy` is pricing-page copy; lives downstream of this skill's plan-structure decisions. +- `pm-spec-writing` is the spec for engineers building the upgrade flow. + +The audience: product marketers, growth marketers, in-house product teams, agencies running SaaS conversion work for clients. + +Out of scope: cross-funnel architecture (covered by `funnel-flow-architecture`); pricing-page copy (covered by `landing-page-copy`); the engineering implementation; specific Stripe/Chargebee/Recurly/Paddle billing-platform configurations (those stay implementation-side). + +--- + +## The free-tier decision: freemium vs free-trial vs no-free + +Before designing the upgrade flow, decide the free-tier structure. + +**Freemium (free-forever tier).** + +- Users use the product indefinitely without paying. +- Paid tier offers more value (capacity, features, support). +- Conversion typically 2-5 percent; volume compensates. + +When it works: products with strong network effects, or where free users provide product value (data, content, virality). + +**Free-trial (time-limited).** + +- Users get full or near-full product for a defined period. +- After trial, must pay to continue. +- Conversion typically 10-25 percent of trial signups. + +When it works: products where the value is clear quickly; audiences willing to commit time before paying. + +**Reverse trial.** + +- Users start on paid plan; auto-downgrade to free after period. +- Less common; mixes signals; can produce surprise churn. + +**No-free (paid-only).** + +- No free tier; users pay to start. +- Conversion is from prospects rather than free users. +- Conversion rates depend on sales motion, not in-product upgrade flows. + +When it works: enterprise products, high-touch sales, products where free would dilute brand or capacity. + +The decision is upstream of upgrade flow design. Different free-tier structures warrant different upgrade flows. + +Detail in [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md). + +--- + +## Paywall-everywhere vs free-forever-trap vs value-triggered-upgrade + +The keystone framing. + +**Paywall-everywhere.** Paywall blocks meaningful product use. Free tier exists but is too constrained to demonstrate value. Users churn before reaching the moment that would justify paying. Cost: users who would have paid after seeing value never reach that moment; conversion suffers despite aggressive paywalling. + +**Free-forever-trap.** Generous free tier with no upgrade path that ever surfaces. Users get everything they need; never see why they would pay. Conversion rate stays at single-digit percentages indefinitely. Cost: the team has built a product users like for free; revenue does not follow because the upgrade ask never lands. + +**Value-triggered-upgrade.** Paywall surfaces at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next. Cost: design effort upfront is significant; conversion typically meaningfully higher than either alternative. + +The litmus test. After a user encounters the upgrade flow, can they articulate why they should pay? "Because I just hit my limit on this feature I have used 200 times" is value-triggered. "Because the product told me to pay before letting me use it" is paywall-everywhere. "I have not seen an upgrade ask" is free-forever-trap. + +--- + +## Trigger-moment design: where paywalls earn their interruption + +The single most consequential decision in upgrade flow design. + +**The principle.** Paywalls surface at moments where the user has demonstrated they are getting the product's value. The interruption is justified because the user has a reason to say yes. + +**Strong trigger moments.** + +- **Usage threshold reached.** User has used a feature N times; further use requires paid plan. Honest because they are clearly getting value. +- **Capacity limit hit.** User has reached free-tier capacity; upgrade unlocks more. Predictable; expected. +- **Advanced feature attempted.** User clicked into a feature that requires paid plan. Interest is fresh. +- **Workflow completed successfully.** User has seen value through a completed action; upgrade ask connects that value to recurring access. +- **Team-collaboration moment.** User wants to invite teammates; team capabilities require paid plan. +- **Time-trial ending.** Trial-based products surface upgrade as trial nears end. + +**Weak trigger moments.** + +- **First-login.** User has not yet seen value; upgrade ask is premature. +- **Random in-product placement.** Paywall on the dashboard with no specific trigger; users dismiss. +- **Every-page banner.** Persistent upgrade banner across all surfaces; users develop blindness. + +**The discipline.** Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +Detail in [`references/trigger-moment-design.md`](references/trigger-moment-design.md). + +--- + +## Paywall presentation: modal vs banner vs inline + +How the paywall surfaces. + +**Pattern A: Modal paywall.** Full-screen overlay blocks the action; user must upgrade or dismiss. + +When to use. Capacity limits, feature gates the user has hit. The interruption is warranted by the trigger. + +**Pattern B: Banner paywall.** Persistent banner at top of page suggesting upgrade. + +When to use. Soft prompts; awareness without interruption. Risk of becoming visual noise. + +**Pattern C: Inline paywall.** Upgrade ask embedded in the surface where the trigger occurred. + +When to use. Contextual prompts that integrate with the workflow. + +**Pattern D: Toast or notification.** Brief paywall surfaced as a notification. + +When to use. Soft prompts; low-priority upgrade asks. + +**Choice criteria.** + +- The trigger's strength determines the presentation's intensity. +- Strong triggers (capacity hit, feature gate) warrant modal. +- Soft triggers (general awareness) warrant inline or toast. + +**Copy and value-prop discipline.** + +- The paywall copy should connect to what the user just did. +- "You have used [feature] 50 times. Upgrade to remove the limit and unlock [related capabilities]." matches the trigger. +- "Upgrade for more features" is generic and weak. + +Detail in [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md). + +--- + +## Upsell vs downsell logic + +When the user does not accept the primary upgrade. + +**Upsell.** User is on basic plan; ask them to upgrade to higher tier. + +**Cross-sell.** User is paying; offer add-ons or related products. + +**Downsell.** User declined the higher tier; offer a smaller commitment (smaller plan, monthly vs annual, basic vs full feature set). + +**The downsell discipline.** Some users will not upgrade to the proposed tier but will upgrade to something. Downsell captures revenue otherwise lost. + +**Examples.** + +- User declined Pro upgrade; offer Starter plan as a path to begin paying. +- User declined annual plan; offer monthly with explicit cost difference disclosed. +- User declined full team plan; offer single-seat upgrade. + +**Anti-pattern.** Aggressive downsell that makes the user feel manipulated. Honest framing: "If Pro is more than you need, here is something that fits." + +Detail in [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md). + +--- + +## Win-back flow design + +Lapsed users, downgrades, partial-churn. + +**Win-back triggers.** + +- User has not logged in for 30/60/90 days. +- User downgraded plan. +- User canceled but did not delete account. +- User churned and signed up again later. + +**Win-back patterns.** + +- **Email-based.** Outreach with renewed value-prop, sometimes with discount or trial extension. +- **In-product upon return.** When the lapsed user returns, surface re-engagement help and (if appropriate) an upgrade-back ask. +- **Personal outreach.** For high-value lapsed users, sales or customer success conversation. + +**Discount discipline.** + +- Discounts to win back can create reverse-incentive (user churns to get discount). +- Discount sparingly; emphasize new value first. + +Detail in [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md). + +--- + +## Churn prevention upstream of upgrade + +The best upgrade flow is the one the user does not need because they did not churn. + +**Upstream churn signals.** + +- Declining engagement; sessions per week dropping. +- Last login distant. +- Support ticket pattern (frustration signals). +- Plan downgrade interest signals. + +**Prevention patterns.** + +- **Engagement re-orientation.** Surface help when engagement drops. +- **Outreach.** Customer success contact for high-value accounts at risk. +- **Friction reduction.** Audit the reasons users disengage; fix the friction. + +**The prevention-vs-recovery economics.** Preventing churn is much cheaper than winning back churned users. Invest upstream. + +Detail in [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md). + +--- + +## Plan structure: tier count, feature gating, pricing-page design + +The plans that the upgrade flow leads to. + +**Tier count.** + +- 2-tier (Free + Paid): simple; clear upgrade path; works for many products. +- 3-tier (Starter + Pro + Enterprise): broader audience; harder to design. +- 4+ tier: rarely better; complexity confuses users. + +**Feature gating.** + +- **Capacity-based.** Free tier limited by use volume; paid unlocks more. +- **Feature-based.** Free tier missing specific features; paid unlocks them. +- **Hybrid.** Both capacity and features differ. + +**Discipline.** Each tier should have a clear "this is for [X audience] because of [Y]." Tiers without clear audience-fit produce weak conversions. + +**Pricing-page design.** The pricing page is downstream of plan structure but lives close to upgrade flow. Detail in `landing-page-copy` for pricing-page copy specifically. + +Detail in [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md). + +- "Conversion rate is low; users churn before reaching upgrade." Paywall-everywhere; gates blocking value demonstration. +- "Conversion rate is single-digit; free users use the product for years." Free-forever-trap; no upgrade path surfaces. +- "Paywall fires; users dismiss; conversion does not lift." Trigger moments wrong; paywall not connected to demonstrated value. +- "Users hit paywall and churn." Wrong moment; paywall blocks before value is fresh. +- "Upgrade rate looks fine; downgrade rate is high." Plan structure wrong; users upgrade then realize they did not need the higher tier. +- "Win-back attempts have low conversion." Re-engagement timing wrong, or value-prop unchanged from what failed initially. +- "Annual plans not converting; monthly plans dominate." Annual value-prop weak; or commitment friction too high. +- "Sales says many leads come from churned users coming back." Win-back working but the previous churn was avoidable; audit upstream. +- "Conversion did not change after we redesigned the paywall." Paywall design was not the problem; trigger or plan structure may be. + +--- + +## The framework: 12 considerations for upgrade flow design + +When designing or auditing an upgrade flow, walk these 12 considerations. + +1. **The free-tier decision.** Freemium, free-trial, reverse trial, or no-free. +2. **Value-triggered-upgrade, not paywall-everywhere or free-forever-trap.** Paywalls at moments of demonstrated value. +3. **Trigger-moment design sound.** Paywalls connect to specific user-demonstrated value. +4. **Paywall presentation matches trigger intensity.** Strong triggers warrant modal; soft triggers inline. +5. **Copy connects to the trigger.** Specific value-prop tied to what the user just did. +6. **Upsell, cross-sell, downsell logic.** When primary upgrade is declined, secondary paths exist. +7. **Win-back flows designed.** Lapsed users have a clear re-engagement path. +8. **Churn prevention upstream.** Upstream signals trigger prevention; downstream upgrade flow is one of multiple defenses. +9. **Plan structure clear.** Tier count appropriate; each tier has clear audience-fit. +10. **Pricing-page coordinates with upgrade flow.** Plan structure decisions reflected on the pricing page. +11. **Conversion as success metric.** Not just paywall display; downstream conversion to paid. +12. **Maintenance discipline.** Plans, paywalls, win-back flows updated alongside product and pricing changes. + +The output of the framework is an upgrade flow that earns the user's "yes" by asking at the moment the user has a reason to say yes, with plan structure that fits the audience the product serves. + +--- + +## Reference files + +- [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md) - Freemium, free-trial, reverse trial, no-free. Choice criteria. +- [`references/trigger-moment-design.md`](references/trigger-moment-design.md) - Where paywalls earn their interruption. Strong vs weak trigger moments. +- [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md) - Modal, banner, inline, toast. Copy and value-prop discipline. +- [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md) - When primary upgrade is declined, secondary paths. +- [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md) - Lapsed users, downgrades, partial-churn re-engagement. +- [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md) - Preventing churn before the upgrade flow is needed. +- [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md) - Tier count, feature gating, audience-fit per tier. +- [`references/upgrade-flow-anti-patterns.md`](references/upgrade-flow-anti-patterns.md) - The patterns that look like upgrade flows but degrade trust. +- [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: upgrade flows earn revenue when they earn the user's yes + +The upgrade flows that compound revenue are the ones that ask at the moment the user has a reason to say yes. Not because the paywall blocked them. Not because the upgrade prompt happened to appear. Because the user just did something that demonstrated value, and the upgrade ask connected that value to continued or expanded access. + +That is the bar. Below the bar are paywall-everywhere (gates before value, conversion suffers) and free-forever-trap (no upgrade path, conversion never starts). Above the bar are value-triggered-upgrade flows where trigger-moment design, paywall presentation, plan structure, win-back, and churn prevention work together to convert the right users at the right moments. + +The discipline is in the design choices. The free-tier decision (freemium, trial, paid-only) sets the funnel shape. Trigger-moment design decides when paywalls earn their interruption. Paywall presentation decides how the ask lands. Plan structure decides what the user is upgrading to. Win-back and churn prevention catch the cases that escaped the primary upgrade flow. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md b/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md new file mode 100644 index 0000000..d20876e --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md @@ -0,0 +1,250 @@ +# Churn prevention upstream + +Preventing churn before the upgrade flow is needed. + +The best upgrade flow is the one the user does not need because they did not churn. Investing upstream of churn produces more revenue than recovering churned users. + +--- + +## The prevention-vs-recovery economics + +Preventing churn is much cheaper than winning back churned users. + +**The math.** Cost of preventing one churn (engagement program, support intervention, friction reduction): X. Cost of winning back one churned user (outreach, discount, re-acquisition): often 3-10X. + +**The implication.** Programs that detect churn risk early and intervene save more revenue than win-back programs that activate only after churn. + +The discipline. Build upstream signals; intervene before churn happens. + +--- + +## Upstream churn signals + +What predicts churn. + +**Engagement decline.** + +- Sessions per week dropping over 4-week period. +- Time-in-product per session declining. +- Feature usage breadth narrowing. + +**Engagement gap.** + +- Last login distant. +- Specific feature stopped being used. +- Days since last meaningful action. + +**Support pattern.** + +- Support tickets indicating frustration. +- Multiple unresolved issues. +- Tone shift in support conversations. + +**Plan-related signals.** + +- Asked about cancellation. +- Researched competitors (sometimes detectable through partner data). +- Downgrade interest. + +**Team-level signals (B2B).** + +- Champion left the company. +- Team reduced seats internally. +- Decision-maker became unresponsive. + +The signals combine. Single signals are noisy; combinations predict more reliably. + +--- + +## Detection systems + +How to know which users are at risk. + +**Engagement scoring.** Composite score based on usage signals; threshold for at-risk classification. + +**Health scores.** Often used by customer success teams; combines product engagement, support pattern, contract data. + +**Predictive models.** Statistical or ML models that predict churn probability per user. + +**Manual flags.** Account managers flag accounts they sense are at risk. + +The discipline. Detection should be operationalized; signals should fire alerts to teams who can act. + +--- + +## Intervention patterns + +What to do when at-risk users surface. + +**Pattern A: Engagement re-orientation.** + +How it works. In-product help surfaces when engagement drops. Re-orients the user to value. + +When to use. Soft signals; users who may have forgotten what the product does for them. + +**Pattern B: Outreach.** + +How it works. Customer success or sales reaches out to at-risk accounts. + +When to use. High-value accounts; B2B contexts where personal touch matters. + +**Pattern C: Friction reduction.** + +How it works. Audit reasons users disengage; fix the friction. Often product changes rather than outreach. + +When to use. When patterns of disengagement reveal product issues. + +**Pattern D: Educational re-engagement.** + +How it works. Send the user content (case study, advanced feature explanation) that re-anchors value. + +When to use. Soft re-engagement; cheap to scale. + +**Pattern E: Plan adjustment.** + +How it works. If usage shows the user is over-paying, suggest a downgrade. Counterintuitive but builds trust. + +When to use. When the user is genuinely on the wrong plan; saves the relationship. + +--- + +## The engagement-re-orientation pattern + +In-product help that surfaces when engagement drops. + +**Implementation.** + +- Trigger fires when engagement signal drops below threshold. +- In-product surface shows: "It looks like you have not used [specific feature] in a while. Here is how others use it." +- Optional brief tour or case study. + +**Strengths.** + +- Cheap. +- Scalable. +- Often catches users who simply forgot. + +**Weaknesses.** + +- May feel intrusive. +- Cannot address all reasons for disengagement. + +--- + +## The customer success outreach pattern + +Personal contact for high-value accounts. + +**Implementation.** + +- Health score crosses at-risk threshold. +- Account manager or CS lead reaches out. +- Conversation: what is happening, what would help, can we address. + +**Strengths.** + +- Highest engagement potential. +- Surfaces real reasons. +- Builds relationship. + +**Weaknesses.** + +- Expensive. +- Only viable for accounts above revenue threshold. + +--- + +## The friction-reduction pattern + +Fixing the underlying reason rather than just intervening per user. + +**Implementation.** + +- Audit common reasons for disengagement. +- Identify product changes that would address. +- Ship the changes. + +**Strengths.** + +- Compounds across all users. +- Often the highest-impact intervention. + +**Weaknesses.** + +- Slower; requires product team prioritization. +- Some friction reasons cannot be product-fixed (audience-fit issues). + +--- + +## The educational-re-engagement pattern + +Send content that re-anchors value. + +**Implementation.** + +- Email or in-product content showing case studies, advanced features, or use cases. +- Targeted to the user's profile. + +**Strengths.** + +- Cheap and scalable. +- Educates without demanding immediate action. + +**Weaknesses.** + +- Lower engagement than personal outreach. +- May feel like marketing. + +--- + +## When intervention has limits + +Not all churn can be prevented. + +**Genuinely unfit users.** Some users signed up but are not the right audience. Their churn is appropriate. + +**Genuinely changed needs.** User changed jobs; product no longer relevant. Cannot be retained. + +**Genuinely better alternatives.** Competitor genuinely better fit. Recovery may not be appropriate. + +**The honest assessment.** Recognizing unpreventable churn is part of the discipline. Intervention should focus on preventable churn. + +--- + +## Churn prevention vs upgrade flow + +Different problems; complementary disciplines. + +**Churn prevention.** Keeps users engaged; avoids churn. + +**Upgrade flow.** Converts engaged users to paid (or higher paid). + +**The interaction.** Strong churn prevention produces engaged users; engaged users are the audience for upgrade flow. Programs running both produce more revenue than either alone. + +--- + +## Common prevention failures + +**No detection.** Churn happens; nobody flagged it; recovery is the only option. + +**Detection without intervention.** Signals fire but nobody acts. + +**Intervention timing wrong.** Action too late; user already disengaged emotionally. + +**Generic intervention.** Same outreach to all at-risk users; no segmentation. + +**Discount-led intervention.** Lead with discount instead of value; trains discount-seeking behavior. + +**Prevention misses fixable friction.** Patterns of disengagement reveal product issues; team focuses on per-user intervention instead. + +**No measurement.** Cannot tell if prevention reduces churn rate. + +--- + +## Methodology-level choices that stay in the public skill + +The prevention-vs-recovery economics. Upstream churn signals (5 categories). Detection systems. Intervention patterns A through E. When intervention has limits. Churn prevention vs upgrade flow interaction. Common failures. + +## Implementation choices that stay internal + +Specific signals and thresholds for specific products. Specific health-score formulas. Specific intervention copy and protocols. The team's CS staffing model. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md b/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md new file mode 100644 index 0000000..bdc5116 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md @@ -0,0 +1,179 @@ +# Common upgrade failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Conversion rate is low; users churn before reaching upgrade." + +**The diagnosis.** Paywall-everywhere; gates blocking value demonstration. + +**The cure.** Loosen free tier. Surface paywalls at moments of demonstrated value. Detail in `references/trigger-moment-design.md`. + +--- + +## "Conversion rate is single-digit; free users use the product for years." + +**The diagnosis.** Free-forever-trap; no upgrade path surfaces. + +**The cure.** Add value-triggered paywalls. Connect upgrade asks to demonstrated value. + +--- + +## "Paywall fires; users dismiss; conversion does not lift." + +**The diagnosis.** Trigger moments wrong; paywall not connected to demonstrated value. + +**The cure.** Audit trigger logic. Each paywall should answer "what value did the user just demonstrate?" + +--- + +## "Users hit paywall and churn." + +**The diagnosis.** Wrong moment; paywall blocks before value is fresh. + +**The cure.** Move paywalls to moments of demonstrated value, not pre-value moments. + +--- + +## "Upgrade rate looks fine; downgrade rate is high." + +**The diagnosis.** Plan structure wrong; users upgrade then realize they did not need the higher tier. + +**The cure.** Clarify tier audiences. Each plan should have specific audience-fit. Detail in `references/plan-structure-patterns.md`. + +--- + +## "Win-back attempts have low conversion." + +**The diagnosis.** Re-engagement timing wrong, or value-prop unchanged from what failed initially. + +**The cure.** Lead with value-prop change. Avoid discount-only win-back. Detail in `references/win-back-flow-patterns.md`. + +--- + +## "Annual plans not converting; monthly plans dominate." + +**The diagnosis.** Annual value-prop weak; or commitment friction too high. + +**The cure.** Strengthen annual value (better discount, additional features). Reduce commitment friction (easier mid-year cancellation, prorated refunds). + +--- + +## "Sales says many leads come from churned users coming back." + +**The diagnosis.** Win-back working but the previous churn was avoidable; audit upstream. + +**The cure.** Invest in churn prevention upstream. Detail in `references/churn-prevention-upstream.md`. + +--- + +## "Conversion did not change after we redesigned the paywall." + +**The diagnosis.** Paywall design was not the problem; trigger or plan structure may be. + +**The cure.** Test variables that matter. Trigger moment, plan structure, value-prop copy. Paywall presentation alone often does not move the needle. + +--- + +## "Upgrade flow works for new users; existing users do not upgrade." + +**The diagnosis.** Triggers designed for new-user behavior; existing users do not hit them. + +**The cure.** Segment trigger logic. Existing users may need different triggers (feature-launch upgrades, capacity-growth upgrades). + +--- + +## "Conversion increased but new customer churn climbed." + +**The diagnosis.** Paywall too aggressive; converting users who do not see value. + +**The cure.** Audit conversion-to-retention correlation. Aggressive conversion may produce buyer's remorse. + +--- + +## "Users complain about hidden charges after upgrade." + +**The diagnosis.** Pricing not transparent; users surprised by total cost. + +**The cure.** Surface all costs upfront. Annual price, monthly price, taxes if applicable. Hidden costs damage trust. + +--- + +## "Cancellation rate spikes 3 months after upgrade." + +**The diagnosis.** Upgrade was made but value did not materialize; users gave it 3 months and left. + +**The cure.** Post-upgrade welcome and onboarding. Surface paid features; help users access value of paid plan. + +--- + +## "Different audience segments convert at different rates; we cannot tell why." + +**The diagnosis.** Per-segment data not tracked. + +**The cure.** Per-segment conversion analytics. Different segments may need different upgrade flows. + +--- + +## "Win-back outreach has unsubscribe rate climbing." + +**The diagnosis.** Outreach too frequent or generic. + +**The cure.** Segment outreach. Respect non-response. Reduce frequency. + +--- + +## "We A/B tested annual vs monthly default; result was wash." + +**The diagnosis.** Default may not have been the issue; price-anchoring or commitment friction may be. + +**The cure.** Test different variables. Price level, discount magnitude, presentation order. + +--- + +## "Sales-led upgrades convert at higher rate than self-serve." + +**The diagnosis.** Self-serve flow misses something that sales touches address. + +**The cure.** Audit what sales does that the flow does not. Often: clarifies value, addresses objections, customizes recommendation. + +--- + +## "We added more upsell prompts; existing customer churn went up." + +**The diagnosis.** Prompt fatigue. Existing customers feel squeezed. + +**The cure.** Frequency limits on upsell. Less is often more. + +--- + +## "Conversion drops at the credit-card-entry step." + +**The diagnosis.** Form friction or trust signals missing. + +**The cure.** Optimize the credit-card form. Add trust signals (security badges, refund policy). Reduce required fields. + +--- + +## The pattern across failures + +Most upgrade flow failures fall into one of three patterns. + +**Pattern 1: Paywalls at wrong moments.** Paywall-everywhere, premature, unconnected, free-forever-trap. The fix is to align paywalls with demonstrated value. + +**Pattern 2: Plan structure misaligned.** Plan-paralysis, plan-mismatch, post-upgrade-empty. The fix is clearer tier audiences and post-upgrade experience. + +**Pattern 3: Trust damage.** Bait-and-switch, hidden-price, aggressive-downsell, hard-to-cancel. The fix is transparency and respect for the user. + +The metric pattern: upgrade flow failures often look fine on conversion alone. The signal is in retention post-upgrade, churn rate, win-back conversion. Programs that track only conversion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (paywall timing, plan structure, trust). The principle that conversion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md b/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md new file mode 100644 index 0000000..6111ee4 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md @@ -0,0 +1,253 @@ +# Free-tier decision criteria + +Freemium, free-trial, reverse trial, no-free. Choice criteria. + +The free-tier decision is upstream of upgrade flow design. The structure determines what the upgrade flow looks like, which trigger moments matter, and what conversion rates are achievable. + +--- + +## The free-tier decision matters + +Different free-tier structures warrant different upgrade flows. + +**The win.** A SaaS product chooses freemium because users provide product value (data, virality, network). Upgrade flow surfaces capacity-based paywalls. Conversion is 3 percent but volume produces meaningful revenue. + +**The fail.** Same product chooses free-trial without realizing user value matters more than time-bound trial. Trial ends; users churn rather than convert; the product loses the network effect users were providing for free. + +The decision is strategic; downstream design choices follow from it. + +--- + +## Pattern A: Freemium (free-forever tier) + +Users use the product indefinitely without paying. + +**How it works.** + +- Free tier offers core value with constraints (capacity limits, feature limits). +- Paid tier removes constraints or unlocks more. +- Users may stay free forever; conversion happens when they hit constraints they value enough to pay around. + +**Conversion baseline.** 2-5 percent typical for B2B SaaS; varies widely. + +**Strengths.** + +- Volume. +- Network effects from free users. +- Users provide product value (data, content, virality). +- Lower acquisition cost. + +**Weaknesses.** + +- Most users do not convert. +- Free-tier capacity costs. +- Plan-design pressure to gate the right things. + +**When to use.** Products with strong network effects, or where free users genuinely contribute to product value. + +--- + +## Pattern B: Free-trial (time-limited) + +Users get full or near-full product for a defined period. + +**How it works.** + +- Trial period (7-30 days typical). +- After trial, must pay to continue. +- Often credit-card-required at start (with auto-charge) or credit-card-not-required (with explicit conversion at end). + +**Conversion baseline.** 10-25 percent of trial signups; higher with credit-card-required. + +**Strengths.** + +- Strong commitment from users who start. +- Clear conversion deadline. +- Revenue arrives quickly post-trial. + +**Weaknesses.** + +- Friction at signup if credit card required. +- Users churn if trial ends before they reach value. +- Trial extension dynamics can become a negotiation. + +**When to use.** Products where value is clear within the trial period; audiences willing to commit time before paying. + +--- + +## Pattern C: Reverse trial + +Users start on paid plan; auto-downgrade to free after period. + +**How it works.** + +- Signup grants paid features for a defined period. +- After period, auto-downgrades to free tier. +- Users who want continued paid features upgrade. + +**Conversion baseline.** Moderate; mixes signals. + +**Strengths.** + +- Users see paid features; familiarity may drive conversion. +- Easier to start than credit-card-required trial. + +**Weaknesses.** + +- Surprise when downgrade hits. +- Some users dislike the loss-aversion framing. +- Less common; users may not know what to expect. + +**When to use.** When the team has tested both freemium and free-trial and reverse-trial outperforms; specific product-audience fits. + +--- + +## Pattern D: No-free (paid-only) + +No free tier; users pay to start. + +**How it works.** + +- Sales conversation or demo; user signs contract or starts subscription. +- No self-serve free path. + +**Strengths.** + +- Higher revenue per signup. +- Clearer signal of intent. +- No free-tier capacity costs. + +**Weaknesses.** + +- Lower top-of-funnel volume. +- Higher acquisition cost. +- Sales-motion dependent. + +**When to use.** Enterprise products, high-touch sales, products where free would dilute brand or capacity. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production products mix. + +**Common combinations.** + +- Freemium with free-trial of paid tier (free forever; trial of higher tier for free users). +- Free-trial with credit-card-not-required for self-serve, plus paid-only for enterprise. +- Reverse-trial for new users, freemium for users who downgrade at end of reverse-trial. + +**The hybrid challenge.** More complexity; more paths to maintain. Justify complexity with conversion data. + +--- + +## Choice criteria + +How to decide. + +**Use freemium when:** + +- Network effects matter; free users contribute value. +- Audience expects free; paid-only would limit reach. +- Conversion rate at scale produces meaningful revenue. + +**Use free-trial when:** + +- Value is clear within a trial period. +- Audience willing to commit time before paying. +- Conversion economics favor higher rate over higher volume. + +**Use reverse-trial when:** + +- Both freemium and free-trial have been tested and reverse-trial outperforms. +- Audience signal-strength is high (paid features get used). + +**Use no-free when:** + +- Audience is enterprise or high-touch. +- Product capacity costs prohibit freemium. +- Sales motion is the dominant funnel. + +**Use hybrid when:** + +- Different audience segments warrant different free structures. +- Data justifies the complexity. + +--- + +## Free-tier capacity design + +For freemium, the capacity decision. + +**The principle.** Free tier offers enough capacity to demonstrate value; not enough to replace paid tier. + +**Capacity dimensions.** + +- **Use volume.** Number of items, queries, exports per month. +- **Capacity.** Storage, seats, integrations. +- **Feature set.** Specific features paid only. +- **Support level.** Self-serve only on free; live support on paid. +- **Branding.** Free tier shows brand; paid removes. + +**Design discipline.** Free tier should let users hit the ah-ha moment; paid tier should be necessary for sustained or scaled use. Too generous: users do not convert. Too constrained: users do not reach ah-ha. + +--- + +## Trial period length + +For free-trial, how long. + +**Common periods.** + +- **7 days.** Aggressive; works when ah-ha moment is clear and quick. +- **14 days.** Common B2B; balances time-to-value with urgency. +- **30 days.** Generous; works for products with longer evaluation cycles. +- **60+ days.** Rare; usually reflects enterprise sales cycles. + +**Decision factors.** + +- Time-to-value of the product. +- Audience evaluation cycle. +- Conversion rate by trial length (test if uncertain). + +--- + +## Free-tier maintenance + +Free-tier structures decay. + +**What decays.** + +- Capacity limits set years ago no longer match current product capability. +- Features moved between tiers without comprehensive update. +- Audience composition shifted; old free-tier no longer fits. + +**Maintenance cadence.** Quarterly review of free-tier structure alongside pricing review. + +**The decay-driven redesign.** When refinements have not moved conversion, the free-tier structure may need redesign. + +--- + +## Common free-tier failures + +**Free-tier too generous.** Users get everything they need; conversion never starts. + +**Free-tier too constrained.** Users do not reach value; churn before conversion. + +**Trial too short.** Users do not reach ah-ha moment; trial ends with low conversion. + +**Trial too long.** Conversion incentive weak; users defer decision. + +**Wrong free-tier structure for audience.** Freemium chosen for enterprise audience that wanted no-free; adoption suffers. + +**No maintenance.** Free-tier static; conversion declines as product evolves. + +--- + +## Methodology-level choices that stay in the public skill + +The free-tier decision matters principle. Patterns A through E. Choice criteria. Free-tier capacity design. Trial period length. Maintenance considerations. Common failures. + +## Implementation choices that stay internal + +Specific free-tier structures for specific products. Specific capacity limits. Specific trial lengths. The team's pricing review calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md new file mode 100644 index 0000000..a08b9ea --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md @@ -0,0 +1,293 @@ +# Paywall presentation patterns + +Modal, banner, inline, toast. Copy and value-prop discipline. + +How the paywall surfaces. Done well, the presentation matches the trigger's intensity; done poorly, presentation fights the trigger and conversion suffers. + +--- + +## The presentation-matches-trigger principle + +Strong triggers warrant prominent presentation; soft triggers warrant subtle presentation. + +**The win.** A user hits a capacity limit; a modal surfaces explaining the limit and offering upgrade. The modal is justified because the trigger is hard (the user cannot continue without resolving). The user accepts the interruption. + +**The fail.** Same user, soft trigger (general awareness moment). A modal surfaces the same way. The interruption is not justified by the trigger; user resents. + +The discipline. Match presentation intensity to trigger strength. + +--- + +## Pattern A: Modal paywall + +Full-screen overlay blocks the action. + +**How it works.** + +- Modal overlay appears. +- User must engage (upgrade) or dismiss to continue. +- Often blocks the action that triggered it. + +**Strengths.** + +- Highest visibility. +- Clear demand for attention. +- Works for hard triggers (capacity hit, feature gate). + +**Weaknesses.** + +- Most disruptive. +- Easily abused; produces annoyance. + +**When to use.** Hard triggers where the user cannot proceed without resolution. + +--- + +## Pattern B: Banner paywall + +Persistent banner at top of page. + +**How it works.** + +- Banner remains visible across pages. +- Often dismissable for the session. +- Soft prompt; does not block action. + +**Strengths.** + +- Persistent awareness without blocking. +- Reaches users who have not hit hard triggers. + +**Weaknesses.** + +- Visual noise; users develop blindness. +- Cumulative exposure can feel like spam. + +**When to use.** Awareness campaigns. Use sparingly; persistent banners abused become noise. + +--- + +## Pattern C: Inline paywall + +Upgrade ask embedded in the surface where the trigger occurred. + +**How it works.** + +- Paywall content appears within the workflow. +- User reads in context; can act or scroll past. +- No overlay; no modal. + +**Strengths.** + +- Contextual; integrated with the workflow. +- Non-disruptive. +- Respectful of user momentum. + +**Weaknesses.** + +- Easier to miss. +- May not produce conversion if too easy to ignore. + +**When to use.** Soft triggers; awareness without interruption. + +--- + +## Pattern D: Toast or notification + +Brief paywall surfaced as a notification. + +**How it works.** + +- Small notification appears (often corner of screen). +- Auto-dismisses after time or on click. +- Brief content. + +**Strengths.** + +- Lightest weight. +- Easy to dismiss. + +**Weaknesses.** + +- Easy to miss entirely. +- Limited content. + +**When to use.** Soft prompts; low-priority awareness. + +--- + +## Pattern E: Hybrid + +Combining patterns. + +**Common combinations.** + +- Modal for hard triggers + inline for soft triggers. +- Banner for awareness + modal at hard trigger moments. +- Inline for in-feature prompts + modal at capacity limits. + +**The hybrid discipline.** Each presentation has a clear role; users do not see overlapping or competing paywalls. + +--- + +## Choice criteria + +Which presentation fits which trigger. + +**Use modal when:** + +- Trigger is hard (cannot proceed without resolution). +- Capacity limit reached. +- Feature gate hit. + +**Use inline when:** + +- Trigger is contextual but soft. +- User can continue without resolving. +- Workflow integration is the priority. + +**Use banner when:** + +- Awareness campaign across pages. +- Soft prompt for users who have not hit hard triggers. + +**Use toast when:** + +- Low-priority awareness. +- Brief acknowledgment. + +The simplest pattern that matches the trigger is usually right. Most upgrade flows benefit from inline + occasional modal. + +--- + +## Copy and value-prop discipline + +What the paywall says. + +**The principle.** Paywall copy should connect to what the user just did and what they get next. + +**Strong copy patterns.** + +- "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [advanced capabilities]." +- "You have hit your free tier's [capacity]. Upgrade to expand to [paid capacity]." +- "Inviting teammates requires our [team plan]. Upgrade to invite up to [number] teammates." + +What works: specific connection to user action; specific value of upgrade. + +**Weak copy patterns.** + +- "Upgrade for more features." (Generic; no connection.) +- "Get the full experience." (Vague; no specifics.) +- "Don't miss out." (FOMO without value.) + +What fails: no connection to user behavior; no specific value-prop. + +--- + +## Plan presentation in paywalls + +Showing the upgrade options. + +**Single-plan paywall.** One upgrade option presented. Simple; clear. + +When to use. When the upgrade is unambiguous (capacity hit; one obvious path). + +**Multi-plan paywall.** Two or three upgrade options presented (e.g., Pro vs Enterprise). + +When to use. When multiple plans could fit; let the user choose. + +**Presentation discipline.** + +- Highlight the recommended plan. +- Make pricing clear. +- Make value differences clear. + +**Anti-pattern.** Showing 5 plans in a paywall. Decision paralysis; user does not choose. + +--- + +## Pricing presentation + +How prices appear. + +**Per-month vs per-year.** Default to the user's likely commitment level; offer the alternative. + +**Price anchoring.** Show what the upgrade saves vs equivalent value (use carefully; can feel manipulative). + +**Currency and locale.** Match the user's locale. + +**Discounts.** Surface honest discounts (annual discount, promotion). Avoid fake urgency. + +--- + +## Action design + +The buttons and CTAs. + +**Primary CTA.** "Upgrade to Pro" with specific plan name. Bold; visible. + +**Secondary CTA.** "Maybe later" or "See plans." Allows decline without forcing. + +**No third option.** Two paths (upgrade or decline) preferred. Three or more paths confuse. + +**The decline-respect principle.** "Maybe later" should respect the decline. The same paywall should not re-fire immediately. + +--- + +## Paywall as opportunity to communicate value + +Even when the user declines, the paywall is a touchpoint. + +**The principle.** Paywall copy explains what paid offers in concrete terms. Even users who decline understand more about the paid plan than they did before. + +**Why this matters.** Future trigger moments find users with more context. The decline today may convert next month because the value is now understood. + +--- + +## Paywall analytics + +Track the paywall's performance. + +**Metrics.** + +- Display rate (how often does it surface?). +- Click rate (how many engage with upgrade button?). +- Conversion rate (of clicks, how many complete upgrade?). +- Decline rate (how many dismiss?). +- Re-show rate per declined paywall. + +**Diagnostic uses.** + +- High display, low click: copy or value-prop weak. +- High click, low conversion: friction in upgrade flow downstream. +- High decline rate: trigger may be wrong, or copy unclear. + +--- + +## Common presentation failures + +**Wrong presentation for trigger.** Modal on soft trigger; inline on hard trigger. + +**Generic copy.** Paywall does not connect to user behavior. + +**Plan paralysis.** Too many options in the paywall. + +**Hidden price.** User has to dig to find the cost. + +**Decline ignored.** Same paywall re-fires immediately after dismiss. + +**Cumulative exposure.** User sees too many paywalls per session. + +**Mobile-broken paywall.** Modal on mobile blocks all interaction. + +**Loading delay.** Paywall takes time to appear; user has moved on. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation-matches-trigger principle. Patterns A through E. Choice criteria. Copy and value-prop discipline. Plan presentation. Pricing presentation. Action design. Paywall as value communication. Paywall analytics. Common failures. + +## Implementation choices that stay internal + +Specific paywall designs for specific products. Specific copy in brand voice. Specific tooling. The team's analytics dashboards. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md new file mode 100644 index 0000000..da29b03 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md @@ -0,0 +1,240 @@ +# Plan structure patterns + +Tier count, feature gating, audience-fit per tier. + +The plans the upgrade flow leads to. Done well, plan structure makes upgrade decisions clear; done poorly, plan structure produces decision paralysis or upgrade-then-downgrade churn. + +--- + +## The clear-tier-fit principle + +Each tier should have a clear "this is for [audience] because of [reason]." Tiers without clear audience-fit produce weak conversions. + +**The win.** A SaaS analytics product has 3 tiers. Starter ("solo analysts and small teams"), Growth ("10-50 person analytics teams"), Enterprise ("complex analytics needs at scale"). Each tier maps to a specific audience; users self-select by recognizing themselves. + +**The fail.** Same product has 3 tiers labeled Bronze, Silver, Gold with feature checkmarks. Audiences cannot tell which is for them; many pick the wrong tier; downgrade rates climb. + +The discipline. Each tier has clear audience-fit articulated. + +--- + +## Tier count + +How many tiers. + +**2-tier (Free + Paid).** + +How it works. Free for some users, paid for everyone else. + +Strengths. Simple; clear upgrade path. + +Weaknesses. Cannot capture enterprise-tier revenue; cannot serve segmented audiences differently. + +When to use. Single-audience products; products with limited feature differentiation. + +**3-tier (Starter + Pro + Enterprise).** + +How it works. Three plans serving three audiences. + +Strengths. Captures entry-level, mid-market, and enterprise. Industry-standard. + +Weaknesses. Requires clear audience differentiation; can create decision paralysis if audiences are not clear. + +When to use. Most B2B SaaS products. Default for products with diverse audiences. + +**4+ tier.** + +How it works. Four or more plans. + +Strengths. Highly granular; serves many audiences. + +Weaknesses. Decision paralysis; users cannot tell which tier fits. + +When to use. Rarely. Most products do better with 3 tiers and add-ons rather than 4+ tiers. + +The simplest tier count that fits the audience is usually best. + +--- + +## Feature gating patterns + +How features differ between tiers. + +**Pattern A: Capacity-based gating.** + +How it works. All tiers have most features; tiers differ in volume (seats, queries, storage). + +Strengths. Clear upgrade trigger when capacity hit. Easy to understand. + +Weaknesses. Encourages users to optimize against limits. + +When to use. Products where capacity is the key cost driver. + +**Pattern B: Feature-based gating.** + +How it works. Lower tiers missing specific features; higher tiers unlock them. + +Strengths. Clear value differentiation between tiers. + +Weaknesses. Feature gating can feel arbitrary; users may want one paid feature but not the rest. + +When to use. Products with clearly tiered feature sets (basic vs advanced vs enterprise). + +**Pattern C: Hybrid gating.** + +How it works. Both capacity and features differ between tiers. + +Strengths. Most flexibility; serves diverse audiences. + +Weaknesses. More complex to communicate; feature comparison tables get long. + +When to use. Default for production B2B SaaS; most products benefit from hybrid. + +**Pattern D: Service-based gating.** + +How it works. Tiers differ in service level (support, onboarding, SLA). + +Strengths. Aligns with enterprise expectations. + +Weaknesses. Service costs scale with tier. + +When to use. Often for top tier (Enterprise); rarely the only differentiation. + +--- + +## Plan naming + +What to call the plans. + +**Audience-named plans.** "For solo creators," "For growing teams," "For enterprise." + +Strengths. Self-selecting; users know which fits. + +Weaknesses. Audience names age; "for startups" can feel limiting. + +**Tier-named plans.** "Starter," "Pro," "Enterprise" or "Basic," "Pro," "Premium." + +Strengths. Industry-standard; users recognize. + +Weaknesses. Generic; does not differentiate from competitors. + +**Outcome-named plans.** "Build," "Grow," "Scale." + +Strengths. Aspirational; aligns with user goals. + +Weaknesses. Vague; users may not know which outcome describes them. + +The discipline. Names should be specific enough that users self-select correctly. + +--- + +## Pricing structure + +How prices map to tiers. + +**Per-seat.** Cost scales with team size. + +When to use. Team collaboration products. + +**Per-feature.** Cost scales with feature set. + +When to use. Modular products. + +**Per-usage.** Cost scales with use volume. + +When to use. Capacity-driven products. + +**Flat per-tier.** Each tier has fixed price regardless of usage. + +When to use. Predictable-budget audiences (often enterprise). + +**Hybrid pricing.** Combinations of the above. + +When to use. Most production products use hybrid (per-seat with usage caps; flat tier with feature differences). + +--- + +## Annual vs monthly + +Commitment options. + +**Monthly.** Lower commitment; higher friction at cancellation; users can leave easily. + +**Annual.** Higher commitment; usually discounted; reduces churn but requires upfront payment. + +**Both offered.** Most products offer both; annual discount incentivizes commitment. + +**Discipline.** Discount on annual should reflect real value to the company (lower churn, predictable revenue) rather than arbitrary marketing percent-off. + +--- + +## Plan transition design + +How users move between plans. + +**Free to paid.** First commitment. Smooth experience matters most. + +**Tier upgrade (within paid).** From Pro to Enterprise. Often involves billing transition. + +**Downgrade (within paid).** From Enterprise to Pro. Should be friction-low to maintain trust; aggressive downgrade prevention damages trust. + +**Cancellation to free.** Some products auto-downgrade on cancellation; others fully cancel. Each has tradeoffs. + +The transitions should be smooth. Friction at transition damages trust. + +--- + +## Pricing-page coordination + +Plan structure decisions reflect on the pricing page. + +**The principle.** Plan structure decisions made for the upgrade flow appear on the pricing page. Users should see consistent information. + +**The integration.** Pricing-page copy (covered by `landing-page-copy`) implements the plan structure decisions made here. The two skills coordinate. + +--- + +## Plan maintenance + +Plans decay. + +**What decays.** + +- Capacity limits set years ago no longer match product capability. +- Features moved between tiers over time without comprehensive update. +- Pricing levels no longer match market. +- Tier audiences shifted. + +**Maintenance cadence.** Annual review at minimum; major product or market changes trigger more frequent. + +**The decay-driven redesign.** When plan structure no longer reflects reality, redesign rather than patch. + +--- + +## Common plan structure failures + +**Too many tiers.** Decision paralysis; users pick wrong tier. + +**Tiers without clear audience-fit.** Generic names without differentiation. + +**Misaligned pricing.** Prices that do not reflect value differences between tiers. + +**Feature gating arbitrary.** Features gated based on what is easy rather than what audiences need. + +**No annual discount.** Users default to monthly; cumulative revenue lower. + +**Aggressive downgrade prevention.** Users want to downgrade; friction damages trust. + +**Plans not updated.** Pricing or tiers from years ago no longer fit current product or market. + +**Pricing-page mismatched.** Plans on the page differ from plans in the upgrade flow. + +--- + +## Methodology-level choices that stay in the public skill + +The clear-tier-fit principle. Tier count guidance. Feature gating patterns A through D. Plan naming patterns. Pricing structure patterns. Annual vs monthly. Plan transition design. Pricing-page coordination. Plan maintenance. Common failures. + +## Implementation choices that stay internal + +Specific plans for specific products. Specific feature gating decisions. Specific pricing levels. Specific naming conventions. The team's pricing review calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md b/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md new file mode 100644 index 0000000..7b4af5d --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md @@ -0,0 +1,217 @@ +# Trigger-moment design + +Where paywalls earn their interruption. Strong vs weak trigger moments. + +The single most consequential decision in upgrade flow design. Paywalls surface at moments where the user has demonstrated they are getting value. Get this wrong and conversion suffers regardless of paywall design quality. + +--- + +## The earned-interruption principle + +Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +**The win.** User has used a feature 50 times. Hits the 50th-use limit. Paywall surfaces: "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [related advanced capabilities]." The trigger is fresh; the value is demonstrated; the user is positioned to say yes. + +**The fail.** Same user. Paywall surfaces on first login: "Upgrade for more features." User has not yet demonstrated value; the upgrade ask is premature; user dismisses. + +The discipline. Paywalls earn their interruption by connecting to recent demonstrated value. + +--- + +## Strong trigger moments + +Patterns that recur across products. + +**Usage threshold reached.** + +How it works. User has used a feature N times in a period. Further use requires paid plan. + +Why it works. The user clearly values the feature. The threshold is predictable; the paywall is honest about the constraint. + +**Capacity limit hit.** + +How it works. User reached free-tier capacity (storage, seats, queries). Upgrade unlocks more. + +Why it works. User encountered an unambiguous block. The block is part of the free-tier promise; the upgrade is the resolution. + +**Advanced feature attempted.** + +How it works. User clicked into a feature that requires paid plan. + +Why it works. Interest is fresh; the user wanted this specific feature. Upgrade ask connects to the specific interest. + +**Workflow completed successfully.** + +How it works. User completed an action that produced visible value (saved view, exported result, completed flow). Upgrade ask connects continuing or expanding that value to paid plan. + +Why it works. Value is fresh; user just experienced what the product does. Upgrade frames continuation. + +**Team-collaboration moment.** + +How it works. User wants to invite teammates; team capabilities require paid plan. + +Why it works. The collaboration intent is concrete; team capabilities are a clear value extension. + +**Time-trial ending.** + +How it works. Trial-based products surface upgrade as trial nears end. + +Why it works. Predictable; user expected it; the conversion conversation is timely. + +**Multi-session usage.** + +How it works. User has returned multiple times; engagement signal strong; soft upgrade prompt. + +Why it works. The user has demonstrated commitment through return; soft prompt fits. + +--- + +## Weak trigger moments + +Patterns that fail. + +**First-login paywall.** + +The pattern. Upgrade ask on first login. + +Why it fails. User has not yet seen value; the ask is premature. + +**Random in-product placement.** + +The pattern. Persistent paywall on the dashboard with no specific trigger. + +Why it fails. Not connected to user behavior; users develop blindness. + +**Every-page banner.** + +The pattern. Persistent upgrade banner across all surfaces. + +Why it fails. Visual noise; users learn to ignore. + +**Paywall on the action the user expected free.** + +The pattern. User believed a feature was free (because of marketing or onboarding); paywall surfaces when they try to use it. + +Why it fails. Trust damage. The user feels deceived. + +**Paywall on irrelevant moments.** + +The pattern. Paywall surfaces during user actions unrelated to the paid feature. + +Why it fails. Confusing; user does not connect the ask to anything. + +**Paywall right after an error.** + +The pattern. User just had a bad experience; immediately gets an upgrade ask. + +Why it fails. Tone-deaf; trust degrades. + +--- + +## Trigger moment design discipline + +Designing each trigger. + +**Step 1: Identify the demonstrated value.** What did the user just do that demonstrates value? + +**Step 2: Identify the connection to paid.** How does the paid plan extend or continue that value? + +**Step 3: Time the ask.** When in the user's flow does the ask land cleanly without breaking momentum? + +**Step 4: Match presentation to importance.** Strong triggers warrant modal; soft triggers inline. + +**Step 5: Plan the response paths.** What if user accepts? Declines? Asks for info? Each path designed. + +The output is a trigger moment that the user perceives as fair. + +--- + +## Trigger frequency + +How often paywalls fire. + +**Per-trigger.** A specific trigger should not fire repeatedly. Once it has fired and been declined, give space before re-asking. + +**Cumulative session frequency.** Total paywall exposures per session capped (often 1-2). Beyond that, additional triggers defer. + +**Per-week.** For users who use the product frequently, weekly cap prevents fatigue. + +**The over-trigger trap.** Each individual trigger looks reasonable; cumulative exposure is annoying. + +--- + +## Personalized trigger logic + +Different users may warrant different triggers. + +**Power-user vs new-user.** Power users may have different trigger thresholds; new users may need more time. + +**Plan tier.** Free users see free-to-paid triggers; paid users see paid-to-higher-paid triggers. + +**Engagement frequency.** Daily active vs returning monthly may warrant different timing. + +**The discipline.** Personalize where data justifies; do not over-segment. + +--- + +## Trigger testing + +Test triggers before launching. + +**Test cases.** + +- New user encounters trigger: appropriate timing? +- Returning user encounters trigger: re-fire respect? +- Power user encounters trigger: relevant? +- User who declined trigger encounters again: respectful? + +**Production monitoring.** + +- Per-trigger fire rate. +- Per-trigger conversion rate. +- Decline rate per trigger. +- Cumulative session exposure. + +The data informs which triggers earn their place and which should be retired. + +--- + +## Trigger maintenance + +Triggers decay. + +**What decays.** + +- Thresholds set years ago no longer match current usage patterns. +- Features the trigger references have changed or been deprecated. +- Audience composition shifted; old triggers no longer fit. + +**Maintenance cadence.** Quarterly review. Triggers that fire too often, too rarely, or with low conversion warrant attention. + +--- + +## Common trigger-moment failures + +**Premature triggers.** Asking before value is demonstrated. + +**Unconnected triggers.** Paywall not tied to the user's recent action. + +**Over-frequent triggers.** Cumulative exposure becomes noise. + +**Stale triggers.** Threshold values set long ago no longer match usage. + +**Mistimed triggers.** Right concept, wrong moment in the user's flow. + +**Triggers right after errors.** Tone-deaf placement after frustration. + +**Triggers that violate free-tier promise.** Asking the user to pay for something they were told was free. + +--- + +## Methodology-level choices that stay in the public skill + +The earned-interruption principle. Strong trigger moments (7 patterns). Weak trigger moments (6 patterns). Trigger moment design discipline. Trigger frequency. Personalized trigger logic. Trigger testing. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific triggers for specific products. Specific thresholds. Specific tooling. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md new file mode 100644 index 0000000..3c9cb48 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md @@ -0,0 +1,212 @@ +# Upgrade flow anti-patterns + +The patterns that look like upgrade flows but degrade trust. Easy to ship; the cost shows up in conversion, retention, and brand reputation. + +--- + +## The paywall-everywhere flow + +The pattern. Paywall blocks meaningful product use; free tier too constrained. + +The signal. Users churn before reaching value; conversion stays low despite aggressive paywalling. + +The cost. Users who would have paid after seeing value never reach it. + +The cure. Loosen the free tier; surface paywalls at moments of demonstrated value. + +--- + +## The free-forever-trap flow + +The pattern. Generous free tier; no upgrade path surfaces. + +The signal. Conversion stays at single-digit indefinitely. + +The cost. Product is loved free; revenue does not follow. + +The cure. Add value-triggered paywalls. Connect upgrade to demonstrated value. + +--- + +## The premature-paywall flow + +The pattern. Paywall on first login or before value is demonstrated. + +The signal. High dismiss rate; conversion does not lift. + +The cost. Users associate the brand with hard-sell early; some leave entirely. + +The cure. Move paywalls to moments of demonstrated value. + +--- + +## The unconnected-paywall flow + +The pattern. Paywall not connected to user behavior; appears at random or on every page. + +The signal. Visual noise; users develop blindness. + +The cost. Cumulative exposure becomes spam; trust degrades. + +The cure. Tie each paywall to specific user-demonstrated value. + +--- + +## The plan-paralysis flow + +The pattern. 5+ tiers presented in upgrade flow; users cannot decide. + +The signal. Click rate on plans is even across tiers; conversion does not match interest. + +The cost. Decision paralysis prevents conversion. + +The cure. Reduce tier count to 3. Recommend a default plan based on user signals. + +--- + +## The hidden-price flow + +The pattern. Prices buried; users have to dig to find them. + +The signal. Users abandon at the price-discovery step. + +The cost. Friction at the moment of decision; users leave. + +The cure. Surface prices clearly. Hidden pricing damages trust. + +--- + +## The decline-ignored flow + +The pattern. User dismisses paywall; same paywall fires immediately. + +The signal. Users disable tours globally; complain about persistent paywalls. + +The cost. Trust degrades; users may churn from the friction itself. + +The cure. Respect declines. Wait substantial time before re-asking. + +--- + +## The aggressive-downsell flow + +The pattern. User declines primary; multiple decline-and-counter rounds; user feels pressured. + +The signal. Users associate the brand with manipulation. + +The cost. Even users who eventually convert leave with negative impressions. + +The cure. One downsell at most. Respect the second decline. + +--- + +## The bait-and-switch flow + +The pattern. User believed feature was free (because of marketing); paywall surfaces when they try to use it. + +The signal. Users complain about deception; trust collapses. + +The cost. Long-term brand damage. + +The cure. Marketing and product align on what is free. No surprise paywalls on advertised-as-free features. + +--- + +## The discount-led-win-back flow + +The pattern. Win-back discount-only; no value-prop change. + +The signal. Re-engaged users churn again; users learn to lapse for discounts. + +The cost. Reverse incentive; lapse rate rises strategically. + +The cure. Lead with value-prop change; discount sparingly. + +--- + +## The aggressive-cancellation-prevention flow + +The pattern. User wants to cancel; flow makes cancellation hard (multi-step, hidden, support-only). + +The signal. Users complain publicly; brand earns "hard to cancel" reputation. + +The cost. Long-term trust damage; sometimes regulatory issue. + +The cure. Cancellation should be as easy as signup. Friction at exit damages reputation. + +--- + +## The plan-mismatch flow + +The pattern. Tier audiences not clearly differentiated; users pick wrong plan. + +The signal. Upgrade rate looks fine; downgrade rate climbs as users realize they picked wrong. + +The cost. Churn through dissatisfaction. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit visible. + +--- + +## The post-upgrade-empty flow + +The pattern. User upgrades; nothing changes immediately. New features unlocked but not surfaced. + +The signal. Upgraded users do not engage with paid features they paid for. + +The cost. Buyer's remorse; downgrade rate climbs. + +The cure. Post-upgrade welcome; surface what changed; help users access new features immediately. + +--- + +## The aggressive-upsell flow + +The pattern. Customers paying already; upsell asks fire constantly. + +The signal. Customer fatigue; cross-sell rate drops over time. + +The cost. Existing customer relationship damaged. + +The cure. Frequency limits on upsell. Cross-sell at moments of relevance, not constantly. + +--- + +## The win-back-spam flow + +The pattern. Lapsed users get win-back outreach repeatedly without segmentation. + +The signal. Unsubscribe rate climbs; brand earns spammy reputation. + +The cost. Loses users who might have returned with better outreach. + +The cure. Segment win-back; respect non-response; abandon after reasonable attempts. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of upgrade flows. + +**Audit questions per flow.** + +- Are paywalls connected to demonstrated value (anti-pattern check: paywall-everywhere, premature, unconnected)? +- Is decline respected (anti-pattern check: decline-ignored, aggressive-downsell)? +- Is plan structure clear (anti-pattern check: plan-paralysis, plan-mismatch)? +- Is pricing visible (anti-pattern check: hidden-price)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does post-upgrade experience deliver (anti-pattern check: post-upgrade-empty)? +- Is win-back honest (anti-pattern check: discount-led, win-back-spam)? +- Is marketing-product alignment maintained (anti-pattern check: bait-and-switch)? + +**The retire decision.** Anti-pattern flows often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md b/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md new file mode 100644 index 0000000..f5497ed --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md @@ -0,0 +1,214 @@ +# Upsell vs downsell logic + +When the user does not accept the primary upgrade. Secondary paths. + +Not every user accepts the proposed upgrade. The discipline is to capture revenue from users who would pay something but not the proposed amount, while respecting users who genuinely do not want to upgrade. + +--- + +## The secondary-path principle + +When the primary upgrade is declined, secondary options may capture revenue otherwise lost. + +**The win.** User is offered Pro plan ($X/month). Declines. System offers Starter plan ($X/3/month). User accepts Starter. Some revenue beats no revenue. + +**The fail.** User declines Pro; sees no other path; remains free; revenue is zero. + +The discipline. Design secondary paths thoughtfully; do not aggressive-downsell into manipulation. + +--- + +## Pattern A: Upsell + +User on basic plan; ask them to upgrade to higher tier. + +**How it works.** + +- Trigger fires when user demonstrates value of higher-tier features. +- Upgrade flow surfaces with the higher plan. + +**Strengths.** + +- Higher revenue per converted user. +- Aligned with demonstrated value. + +**Weaknesses.** + +- User may not need the higher tier; conversion can be poor. + +**When to use.** When the user has hit limits or used features that the higher tier addresses. + +--- + +## Pattern B: Cross-sell + +User is paying; offer add-ons or related products. + +**How it works.** + +- Trigger fires when user shows interest in adjacent capabilities. +- Cross-sell surfaces complementary product or add-on. + +**Strengths.** + +- Expands revenue from existing customer. +- Often easier than acquiring new customers. + +**Weaknesses.** + +- Risks fatigue if cross-sells are too frequent. +- Users may feel they are being squeezed. + +**When to use.** When add-ons or related products genuinely fit the customer's profile. + +--- + +## Pattern C: Downsell + +User declined the higher tier; offer a smaller commitment. + +**How it works.** + +- User dismisses upgrade. +- Secondary paywall offers a lower-tier plan, monthly instead of annual, or smaller seat count. + +**Strengths.** + +- Captures revenue from users not ready for the primary plan. +- Establishes paying relationship that may upgrade later. + +**Weaknesses.** + +- Aggressive downsell feels manipulative. +- Users may downgrade to the lowest option even when they would have paid more. + +**When to use.** When the primary plan is decline-prone; downsell catches users who would pay something. + +--- + +## Pattern D: Annual-vs-monthly downsell + +User declined annual; offer monthly. + +**How it works.** + +- Annual plan offered first (with discount). +- Decline; monthly offered as backup. + +**Strengths.** + +- Some users avoid annual commitment but accept monthly. +- Captures revenue from commitment-averse users. + +**Weaknesses.** + +- Cumulative revenue lower. +- Can train users to expect monthly when annual was the goal. + +**When to use.** When annual is the desired commitment but conversion suffers from upfront cost. + +--- + +## Pattern E: Seat-count downsell + +User declined full team plan; offer single-seat upgrade. + +**How it works.** + +- Team plan offered first. +- Decline; single-seat upgrade offered. + +**When to use.** When the user's situation suggests they would value paid features for themselves but cannot commit team-wide yet. + +--- + +## Downsell discipline + +When downsell crosses into manipulation. + +**Honest framing.** "If Pro is more than you need, here is something that fits your team size." + +**Manipulative framing.** Aggressive flow that pressures the user. Multiple decline-and-counter rounds. Hidden costs. Switching plan terms after acceptance. + +**The discipline.** Downsell respects the decline; offers an alternative; does not pressure. + +--- + +## When NOT to downsell + +Some declines should be respected. + +**The user explicitly does not want any plan.** Continued upgrade asks become harassment. + +**The user has signaled disengagement.** Aggressive downsell on a disengaged user accelerates churn. + +**The user is on a free tier that fits.** Forcing an upgrade where the user is happy on free degrades trust. + +**The user is in a bad moment.** After an error, support ticket, or negative experience, downsell is tone-deaf. + +--- + +## Sequencing upsell, cross-sell, downsell + +In a typical flow. + +**Step 1: Primary upgrade ask** (matched to trigger). +**Step 2 (if declined): Downsell** (smaller commitment alternative). +**Step 3 (if declined): Soft acknowledgment** ("No problem; here is the link to plans whenever you are ready."). +**Step 4 (later): Cross-sell** (when the user has continued use signals). + +The flow respects each decline before re-engaging at a later moment. + +--- + +## Frequency limits across upsell/downsell + +How often these surface. + +**Within session.** Once primary + once downsell + soft acknowledgment. No more. + +**Across sessions.** Wait days or weeks before re-ask. The user's circumstances may have changed. + +**Per quarter.** Major upgrade pushes per quarter at most. + +--- + +## Conversion economics of upsell vs downsell + +Different patterns have different revenue dynamics. + +**Upsell.** Higher revenue per converted user. Lower conversion rate. + +**Cross-sell.** Adds revenue per existing customer. Conversion depends on fit. + +**Downsell.** Lower revenue per converted user. Higher conversion rate. Captures users who would otherwise stay free. + +**The math question.** Total revenue = (upsell rate × upsell revenue) + (downsell rate × downsell revenue) + (free-to-paid rate × paid revenue). Optimize the sum. + +--- + +## Common upsell/downsell failures + +**Aggressive downsell rounds.** Multiple decline-and-counter loops; user feels manipulated. + +**Downsell that breaks the upsell.** Users learn to decline upsell to get downsell discount. + +**No downsell.** Users decline primary; revenue is zero. + +**Cross-sell fatigue.** Customers see too many cross-sells; resent. + +**Wrong sequencing.** Cross-sell before user has paid first plan. + +**No frequency limits.** Cumulative upgrade asks become spam. + +**Tone-deaf timing.** Downsell after a customer support escalation. + +--- + +## Methodology-level choices that stay in the public skill + +The secondary-path principle. Patterns A through E (upsell, cross-sell, downsell, annual-vs-monthly, seat-count). Downsell discipline. When NOT to downsell. Sequencing logic. Frequency limits. Conversion economics. Common failures. + +## Implementation choices that stay internal + +Specific upsell, cross-sell, downsell flows for specific products. Specific copy. Specific tooling. The team's revenue economics modeling. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md new file mode 100644 index 0000000..80eb6ab --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md @@ -0,0 +1,240 @@ +# Win-back flow patterns + +Lapsed users, downgrades, partial-churn re-engagement. + +When users disengage, downgrade, or churn, win-back flows attempt to bring them back. Done well, win-back captures revenue from users who left due to specific (often fixable) reasons; done poorly, win-back becomes spam that confirms the user's decision to leave. + +--- + +## The respect-the-decline principle + +Users who left often left for reasons. Win-back should be honest about the reasons and offer something genuinely changed, not just a discount. + +**The win.** A user lapsed 60 days ago. Win-back email surfaces with: "Since you last logged in, we shipped [specific feature you mentioned wanting]. Want to try it?" The user returns; the value-prop is fresh. + +**The fail.** Same user. Win-back email surfaces with: "We miss you! Come back for 20 percent off." The user dismisses; the discount feels like manipulation; the previous problems remain. + +The discipline. Win-back is most effective when something has changed (new feature, fixed problem) the user would value. + +--- + +## Win-back triggers + +When to fire. + +**User has not logged in for 30 days.** Soft trigger; light re-engagement. + +**User has not logged in for 60-90 days.** Moderate trigger; more substantive re-engagement. + +**User has not logged in for 6+ months.** Aggressive trigger; usually the last attempt before treating as fully churned. + +**User downgraded plan.** Trigger surfaces post-downgrade; win-back attempts to retain the higher tier. + +**User canceled but did not delete account.** Soft trigger; re-engage before full churn. + +**User churned and signed up again.** Different trigger; usually treat as new signup with prior context. + +The triggers vary by product and audience. + +--- + +## Pattern A: Email-based win-back + +Outreach with renewed value-prop. + +**How it works.** + +- Email sent to lapsed user. +- Content focuses on what has changed since they left. +- May include discount or trial extension. + +**Email design discipline.** + +- Subject line concrete; not generic "we miss you." +- Body specific to what has changed. +- One clear CTA back to product. +- Easy unsubscribe; respect users who do not want re-engagement. + +**Strengths.** + +- Cheap; can scale. +- Reaches users outside the product. + +**Weaknesses.** + +- Easy to feel like spam. +- Email deliverability for lapsed users is harder. + +**When to use.** Default for lapsed-user re-engagement. + +--- + +## Pattern B: In-product upon return + +When a lapsed user returns, surface re-engagement help. + +**How it works.** + +- User logs in after long absence. +- In-product surfaces re-orientation and (if appropriate) upgrade-back ask. + +**Design.** + +- Welcome-back banner with what has changed. +- Brief tour of new features added during absence. +- Soft upgrade-back if user downgraded. + +**Strengths.** + +- The user has already returned; engagement is fresh. +- Can be specific to the user's prior usage. + +**Weaknesses.** + +- Misses users who do not return on their own. + +**When to use.** When email or other re-engagement has produced a return. + +--- + +## Pattern C: Personal outreach + +For high-value lapsed users, sales or customer success conversation. + +**How it works.** + +- Customer success or sales reach out directly. +- Often via email or call. +- Conversation about what changed for the user; what would bring them back. + +**Strengths.** + +- Highest engagement potential. +- Surfaces real reasons; can address them. + +**Weaknesses.** + +- Expensive; only viable for high-value accounts. +- Risk of harassment if not done well. + +**When to use.** Enterprise lapsed accounts, high-revenue lapsed customers, accounts with strategic value. + +--- + +## Pattern D: Offer-based win-back + +Discount or trial extension as primary motivator. + +**How it works.** + +- Offer (e.g., 30 percent off, 3 months free, extended trial) presented to lapsed user. +- Limited time; explicit terms. + +**Strengths.** + +- Can move users who left for cost reasons. +- Easy to implement. + +**Weaknesses.** + +- Can train users to lapse intentionally to get discounts. +- Discount alone does not address why they left. + +**When to use.** Sparingly. Combine with value-prop changes; do not lead with discount alone. + +The discount-as-only-strategy failure. Discounts to win back can create reverse incentives. If users learn that lapsing gets them discounts, lapse rate climbs strategically. + +--- + +## Win-back sequence design + +A multi-touch win-back rather than single email. + +**Typical sequence.** + +- Day 30: light re-engagement (what's new). +- Day 60: more substantive (specific feature; case study). +- Day 90: explicit win-back offer (if appropriate). +- Day 120: final outreach; respect non-response. +- Beyond Day 120: treat as fully churned. + +The sequence respects the user's silence; multiple touches at different intensities. + +--- + +## When to abandon win-back + +Some users genuinely do not want to come back. Respect that. + +**Signals to stop.** + +- User unsubscribed from emails. +- User explicitly stated they do not want contact. +- Multiple win-back attempts produced no response. +- User left for reasons unfixable by the product (changed jobs, changed needs). + +**The respect-the-no principle.** Continuing win-back after clear no signals is harassment. + +--- + +## Discount discipline in win-back + +When discounts make sense. + +**Use discount when:** + +- The user explicitly stated cost was a factor. +- The product's price has not changed but the user's situation has. +- A time-limited promotion is genuinely available. + +**Avoid discount when:** + +- The user left for non-cost reasons (poor experience, missing features). +- The discount would train lapse-for-discount behavior. +- The discount cannibalizes existing customer revenue. + +--- + +## Win-back analytics + +Track effectiveness. + +**Metrics.** + +- Re-engagement rate (lapsed users who returned after win-back outreach). +- Conversion rate (returned users who paid or upgraded back). +- Retention of returned users (do they stay or lapse again?). + +**Diagnostic uses.** + +- Low re-engagement: outreach not relevant or not delivered. +- High re-engagement, low conversion: returns happen but value-prop weak. +- Returns lapse again quickly: underlying issue not fixed. + +--- + +## Common win-back failures + +**Generic outreach.** "We miss you" with no specifics; user dismisses. + +**Discount-only strategy.** Discount without value-prop change; trains lapse-for-discount. + +**Frequency overload.** Too many win-back attempts; harassment. + +**No segmentation.** Same outreach to all lapsed users regardless of why they left. + +**Ignoring unsubscribes.** Outreach continues despite explicit no. + +**No measurement.** Cannot tell if win-back works. + +**Returns-lapse-again.** Win-back succeeds short-term; underlying issue persists; user lapses again. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-decline principle. Win-back triggers. Patterns A through D (email, in-product, personal, offer-based). Win-back sequence design. When to abandon. Discount discipline. Win-back analytics. Common failures. + +## Implementation choices that stay internal + +Specific win-back sequences for specific products. Specific outreach copy in brand voice. Specific discount levels. The team's segment-specific approaches. These vary by team and product. diff --git a/dist/pi/.agents/skills/usability-testing/SKILL.md b/dist/pi/.agents/skills/usability-testing/SKILL.md new file mode 100644 index 0000000..26f0a9e --- /dev/null +++ b/dist/pi/.agents/skills/usability-testing/SKILL.md @@ -0,0 +1,238 @@ +--- +name: usability-testing +description: "Plan and run usability tests on existing or prototype designs including test design, task scripts, moderation, observation, and findings synthesis. Use this skill whenever the user wants to test usability, run a moderated test, run an unmoderated test, validate a design, find usability issues, or improve task completion. Triggers on usability test, usability testing, moderated test, unmoderated test, task script, think aloud, prototype testing, user testing, design validation, task completion. Also triggers when the user has built something and wants to know if real users can use it before shipping." +category: research +catalog_summary: "Test design, moderation, findings reports" +display_order: 2 +--- + +# Usability Testing + +Plan and run tests that find usability problems before users hit them in production. Stack-agnostic. Tool-agnostic. + +This skill is for testing existing designs or prototypes. For broader discovery research, use `ux-research`. For conversion testing in production, use `cro-optimization`. + +--- + +## When to use + +- Before launching a new flow or major redesign +- After a redesign to verify it doesn't introduce new problems +- When analytics show drop-off but you don't know why +- When customer support tickets pattern around specific UI areas +- Pre-launch user validation +- Comparing two design directions + +## When NOT to use + +- Discovery / generative research (use `ux-research`) +- Live conversion optimization (use `cro-optimization`) +- Mapping the broader experience (use `journey-mapping`) +- Pure quantitative measurement (use `analytics-strategy`) + +--- + +## Required inputs + +- The design or prototype to test (functional or near-functional) +- Specific tasks users would do +- The audience (who should be tested) +- Testing infrastructure (moderated tool, unmoderated tool, in-person setup) + +--- + +## The framework: 5 phases + +### 1. Define what to test + +Don't test the whole product. Test specific tasks. + +**Task selection criteria:** + +- The task represents a real user goal (not "click around and explore") +- The task has a clear start and end +- The task is achievable in 2 to 10 minutes +- The task is one of: most common, most strategic, most problematic + +**Examples of testable tasks:** + +> "You want to find a contractor near you who can install a fence. Show me how you'd do that on this site." + +> "You're a first-time visitor. You want to understand if this product fits your needs. Walk me through how you'd evaluate it." + +> "Your team needs a new tool to manage projects. Use this site to figure out which plan is right for a 12-person team." + +**Task framing rules:** + +- State the user goal, not the system action ("find a place to stay" not "click the search button") +- Provide context (why are you doing this?) +- Don't reveal the path +- Don't use product terminology in the task framing + +### 2. Choose moderated or unmoderated + +**Moderated** (live, with researcher): + +- Researcher observes and probes in real time +- Best for early-stage prototypes, complex tasks, novel concepts +- Higher cost, smaller sample (5 to 8 participants typical) +- Catches surprises and probe deeper + +**Unmoderated** (recorded, asynchronous): + +- Participant completes alone, often via tool (UserTesting, Maze, Lookback) +- Best for stable designs, simple tasks, larger sample +- Lower cost, larger sample (15 to 30 participants typical) +- Catches patterns at scale, less depth per session + +For most teams: moderated for early/critical decisions, unmoderated for ongoing validation. + +### 3. Recruit + +Target audience - not just convenience. + +**Recruit criteria:** + +- Match real users (target audience, not just "anyone") +- Mix of experience levels with the product (new and existing if applicable) +- Mix of relevant device types (mobile, desktop, tablet if relevant) +- Exclude friends, family, employees + +**Sample size:** + +- Moderated: 5 to 8 participants (Nielsen's "5 users find 85% of usability issues" for the most common segment) +- Unmoderated: 15 to 30 participants (more participants compensate for less probing) +- Multi-segment testing: 5 to 8 per segment + +### 4. Run the test + +**Pre-task setup:** + +- Confirm recording works +- Brief participant (purpose, anonymity, recording, "no wrong answers") +- Get verbal consent +- Have participant share screen if remote + +**Moderated session structure:** + +1. **Warm-up** (2 to 3 min). Easy questions to put participant at ease. +2. **Pre-test questions** (3 to 5 min). Background context, current behavior with similar products. +3. **Task 1** (5 to 10 min). Describe task. Have participant attempt while thinking aloud. +4. **Post-task questions** (1 to 2 min). What was easy/hard? Anything confusing? +5. **Repeat for tasks 2, 3, 4** (typically 3 to 5 tasks per 60-minute session). +6. **Overall debrief** (5 to 10 min). General reactions, comparisons to alternatives, anything else. +7. **Close** (2 min). + +**Moderation principles:** + +- Encourage think-aloud ("What's going through your mind?") +- Don't help unless they're truly stuck (and even then, only after a long pause) +- Don't lead ("Are you looking for the menu?" - bad) +- Note where they hesitate, scroll, or backtrack +- Note their language vs the product's language +- Note emotional reactions + +**Anti-patterns:** + +- Talking too much (researcher should talk maybe 20% of the time) +- Defending the design when participants struggle +- Helping prematurely +- Asking participants to predict their future behavior +- Treating participant suggestions as features ("Users want X" - test demand for X separately) + +### 5. Synthesize and report + +Patterns across participants are signal. Single-participant complaints are weaker (but worth investigating). + +**Synthesis steps:** + +1. **Issue inventory.** Every issue observed, with which participant, which task, severity. +2. **Cluster.** Issues that are the same root problem. +3. **Severity.** + - **Critical:** Blocks task completion. Most users hit this. + - **Major:** Significantly slows task. Many users hit this. + - **Minor:** Friction. Some users hit this. Workaround exists. + - **Cosmetic:** Polish. Doesn't affect task. +4. **Recommendations.** For each issue, propose specific fixes. +5. **Prioritize.** By severity and effort. + +**Report structure:** + +```markdown +# Usability Test: [Design / flow] + +## Summary +[2 to 3 paragraphs covering: what was tested, headline findings, top 3 priorities] + +## Method +[Moderated/unmoderated, sample size, audience, dates, tasks] + +## Critical findings +[Each with description, frequency, supporting evidence (quotes/clips), recommendation] + +## Major findings +[Same structure] + +## Minor findings +[Brief] + +## Cosmetic findings +[Briefest] + +## What worked well +[Calibration: capture successes too] + +## Recommendations +[Prioritized list with effort estimates] + +## Next steps +[Test re-run schedule, design iteration plan] +``` + +--- + +## Workflow + +1. **Define the goals.** What decisions hinge on this? What tasks matter most? +2. **Design tasks.** 3 to 5 specific, realistic, goal-framed tasks. +3. **Choose moderated vs unmoderated.** Match to stage and depth needed. +4. **Recruit.** Specific to audience. +5. **Pilot.** 1 to 2 sessions before main batch. Refine tasks if needed. +6. **Run.** Follow the protocol. Stay disciplined. +7. **Synthesize during, not just after.** Patterns emerge by session 4 or 5. +8. **Report.** Multiple formats - written report + highlight clips. +9. **Track fixes.** Every critical issue should have an owner and date. +10. **Re-test after fixes.** Verify the fix worked, didn't introduce new issues. + +--- + +## Failure patterns + +- **Testing the whole product instead of specific tasks.** Vague results. +- **Tasks that reveal the path.** ("Click the menu and find...") +- **Friends and family as participants.** Biased, not representative. +- **Researcher leading the participant.** Findings reflect the researcher. +- **Defending the design when participants struggle.** Misses real issues. +- **Helping too quickly.** Participant doesn't experience the friction. +- **Treating participant suggestions as features.** Users solve their problem; product team designs the solution. +- **One participant = data point.** A single strong opinion isn't a finding. +- **Skipping severity scoring.** All findings treated equally; team can't prioritize. +- **Reports no one reads.** Highlight clips and live walkthroughs work better than 80-page decks. +- **Testing once, never re-testing.** Fixes that introduce new problems go undetected. + +--- + +## Output format + +Default outputs: + +1. **Test plan** (before testing) - `usability-test-plan-[topic].md` +2. **Task script** (per session) - `usability-tasks-[topic].md` +3. **Findings report** (after synthesis) - `usability-findings-[topic].md` +4. **Highlight clips** (separately produced) + +--- + +## Reference files + +- [`references/task-script-patterns.md`](references/task-script-patterns.md) - Task framing patterns by common product type, with good and bad examples. diff --git a/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md b/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md new file mode 100644 index 0000000..bcc0cd7 --- /dev/null +++ b/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md @@ -0,0 +1,315 @@ +# Task Script Patterns + +Patterns for writing usability test tasks that produce real findings rather than scripted compliance. Includes good and bad examples by common product type. + +--- + +## Universal task framing rules + +### Rule 1: State the user goal, not the system action + +| Bad (system action) | Good (user goal) | +|---|---| +| "Click the search button at the top." | "Find a place to stay in Lisbon for a weekend." | +| "Open the settings menu and change your password." | "You think someone else might know your password. Update it." | +| "Add this product to your cart." | "You want to buy this jacket. Walk me through purchasing it." | + +The system-action version reveals the path. Findings tell you whether the participant could follow instructions, not whether they could use the product. + +### Rule 2: Provide motivating context + +| Bare task | Better with context | +|---|---| +| "Find a hotel in Paris." | "You're planning a 3-day trip to Paris next month for your anniversary. Find a hotel that fits." | +| "Sign up for an account." | "You decided this looks promising and want to try it. Get started." | + +Context shapes how participants approach the task. Without it, they make their own assumptions, often differently from each other. + +### Rule 3: Avoid product terminology + +| Bad (uses our terms) | Good (uses user's terms) | +|---|---| +| "Create a workspace." | "Set this up so your team can collaborate." | +| "Find an experience." | "Find an activity to do this Saturday." | + +If the participant doesn't already know the product's terminology, using it in the task gives them the answer. + +### Rule 4: Don't reveal the path + +| Bad (path revealed) | Good (open) | +|---|---| +| "Use the filters to narrow the results to under $100." | "Find something within your budget of $100." | +| "Click on the FAQ section to find the return policy." | "Find out if you can return this if it doesn't fit." | + +If the path is in the task, you're not testing whether the participant can find the path. + +### Rule 5: Make it specific + +| Bad (vague) | Good (specific) | +|---|---| +| "Try out the product." | "Find out if this product would work for tracking your team's meetings." | +| "Look around." | "Walk me through how you'd evaluate whether this is right for you." | + +Vague tasks produce vague findings. Specific tasks produce actionable findings. + +--- + +## Common pre-test framing + +Use a script for the opening so it's consistent across sessions. + +### Standard opener + +> "Thanks again for joining. As I mentioned, we're testing a [website / app / prototype]. The point is to learn from your experience, not to test you. There are no right or wrong ways to do anything. If you get confused or stuck, that's information for us, not a problem with you. +> +> A few things to know: +> 1. I'll ask you to do some tasks. As you go, please think out loud. Tell me what you're looking at, what you're thinking, what you expect to happen, what's confusing. +> 2. I won't be able to help much during the tasks. The whole point is to see how you'd use this without help. After each task, we'll talk about what was easy and what wasn't. +> 3. We're recording this session for our own notes. The recording stays internal. Sound good? +> +> Any questions before we start?" + +### Pre-task framing + +> "OK, here's the first task. Take your time, think out loud, and there's no rush. +> +> [Read the task aloud, slowly. Send it in chat if remote so they can refer back.] +> +> Go ahead and start whenever you're ready." + +### Mid-task probes (use sparingly) + +When participant is silent for a while: +> "What are you thinking?" + +When participant pauses on something: +> "What's going through your mind right now?" + +When participant takes an unexpected action: +> "What did you expect to happen there?" + +### When participant gets truly stuck + +Wait at least 30 seconds before intervening. Real frustration is signal. + +> "Take a moment. What would you typically do at a point like this?" + +Or: + +> "Is there anything you'd want to do that you're not seeing a way to do?" + +If they're still stuck after another 30 seconds, you can offer a hint: "What might happen if you scrolled?" But this is a last resort. The struggle is the data. + +### Post-task probes + +> "On a scale of 1 to 5, how easy or hard was that?" + +> "What was hardest?" + +> "What was easiest?" + +> "If you could change one thing about how that worked, what would it be?" + +### Closing + +> "Thanks for working through these tasks. Two last questions: +> +> Overall, what's your impression? +> +> If you imagine using this regularly, what would make it work for you? What might keep you from using it? +> +> Anything else you want to mention before we wrap?" + +--- + +## Task patterns by product type + +### Ecommerce + +#### Browse and discovery + +> "You're looking for a gift for a friend who loves cooking. They've been getting into making bread. You have a budget of about $75. Find something that might work." + +[Tests: navigation, search, filtering, product browsing] + +#### Specific product purchase + +> "You've decided to buy [specific product]. Walk me through purchasing it. Stop just before you'd actually enter your payment info." + +[Tests: cart flow, checkout flow, friction points] + +#### Comparison + +> "You're trying to decide between two of these products. Use the site to figure out which one is better for your needs." + +[Tests: comparison features, product pages, decision support] + +#### Returns + +> "You bought something from this store last month. It doesn't fit. Find out how to return it." + +[Tests: help center, account flows, post-purchase support] + +--- + +### SaaS / B2B + +#### Self-service evaluation + +> "You're a [role] at a 30-person company. Your team needs better [tool category]. Use this site to figure out if this is the right fit, and if so, what plan to pick." + +[Tests: positioning, value prop, pricing, evaluation flow] + +#### Onboarding (post-signup) + +> "You just signed up for an account. Walk me through what you'd do next. Try to get to the point where the product would be useful for you." + +[Tests: onboarding, time-to-value, activation friction] + +#### First key task + +> "You're new to this product. Try to [specific key action: create your first project, set up an integration, invite a teammate]. Think out loud as you go." + +[Tests: feature discovery, task completion] + +#### Existing-user task + +> "You're an experienced user of this product. You need to [specific advanced task]. Show me how you'd do that." + +[Tests: depth of features, expert workflows] + +--- + +### Marketplaces + +#### Buyer side: discovery + +> "You need someone to [service]. Find a few options that look good to you." + +[Tests: search, filters, listing pages] + +#### Buyer side: deciding + +> "You've narrowed it down to a few options. Pick the one you'd actually book and walk me through what you'd do next." + +[Tests: details pages, social proof, booking flow] + +#### Seller side: setup + +> "You [run a business / offer a service]. You're considering listing it here. Use this site to figure out how to get started." + +[Tests: onboarding, value prop for the supply side] + +#### Seller side: ongoing + +> "You're an existing seller. You want to [check on inquiries / update your availability / respond to a review]. Show me how you'd do that." + +[Tests: account management, dashboard] + +--- + +### Content / publisher + +#### Reading flow + +> "Read [specific article / topic that interests you]. As you go, tell me what's working or not working about the experience." + +[Tests: readability, page experience, ads, related content] + +#### Discovery + +> "Spend a few minutes exploring this site. Find articles that interest you. Tell me how you decide what to click." + +[Tests: navigation, recommendations, browse paths] + +#### Subscribe + +> "You've decided you want to read more from this publication. Sign up for whatever you think makes sense." + +[Tests: paywall flow, subscription page, account setup] + +--- + +### Mobile app + +#### Initial impression + +> "You just downloaded this app. Open it and start using it. Tell me what you do, what you expect." + +[Tests: app onboarding, initial value] + +#### Specific feature + +> "You want to [specific feature use]. Show me how you'd do that." + +[Tests: feature discovery, mobile-specific patterns] + +#### Push / notification flow + +> "Your phone just buzzed with a notification from this app. Show me what you'd do." + +[Tests: notification design, deep links, post-notification flow] + +--- + +## Task script common pitfalls + +### Pitfall 1: Multiple tasks in one + +> "Sign up, create a project, and invite a teammate." + +This is three tasks. Run as three separate tasks so you can score and analyze each. + +### Pitfall 2: Tasks that aren't realistic + +> "Imagine you're an enterprise CFO evaluating procurement tools." + +If the participant is not a CFO, they're roleplaying. Findings tell you about roleplay, not real CFO behavior. Recruit real CFOs or pick a different task. + +### Pitfall 3: Tasks the participant has already done + +> "Sign up for an account." +> +> Participant: "I already have one." + +Either log them out for the test, or change the task to first-time-user-feeling tasks. + +### Pitfall 4: Tasks tied to specific data the participant doesn't have + +> "Update your billing address." +> +> Participant: "I don't have an account on this site." + +Provide a test account with realistic data, or pick tasks that work for first-time users. + +### Pitfall 5: Asking about future behavior as a task + +> "Tell me what you'd pay for this." + +Hypothetical questions are weak signal. Test actual behavior (do they get to the pricing page? where do they hesitate?) and ask post-task what they'd be willing to pay if useful. + +--- + +## Severity scoring rubric + +Use after testing to score each issue. + +| Severity | Definition | Example | +|---|---|---| +| Critical | Most users cannot complete the task. Hard blocker. | "5 of 6 participants gave up trying to find pricing." | +| Major | Most users complete the task, but with significant struggle. | "4 of 6 participants needed multiple tries to find the search." | +| Minor | Some users hit friction. Most complete the task fine. | "2 of 6 participants paused on the form, but all completed." | +| Cosmetic | Polish issue. No effect on task completion. | "Multiple participants noted a typo." | + +Critical and Major issues block ship. Minor issues prioritize on cost/benefit. Cosmetic gets fixed in normal iteration. + +--- + +## Reporting tips + +- Lead with the **most surprising** finding, not the easiest fix +- Include **at least one quote per major finding** (specifics persuade) +- Include **video clips for critical findings** (no document beats seeing it) +- For each finding, include both **the issue** and **the recommended fix** +- Sort by **severity**, not by section of the product +- Make it **scannable**. Stakeholders skim. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md b/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md new file mode 100644 index 0000000..0336049 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md @@ -0,0 +1,302 @@ +--- +name: user-feedback-aggregation +description: "Collecting and synthesizing user feedback across channels (support tickets, NPS, in-app feedback, sales calls, social mentions, customer councils) into a continuous signal that informs product decisions. The triage discipline that distinguishes loudest-voice (whoever complains most wins) from averaged-noise (every signal weighted equally) from triaged-synthesis (signal weighted by source quality, frequency, and decision relevance). Triggers on user feedback, customer feedback aggregation, NPS, support ticket analysis, customer councils, feedback synthesis, voice of customer, feedback triage, in-app feedback. Also triggers when feedback channels overflow with volume that does not produce decisions, when the loudest-voice problem is steering roadmap, or when continuous feedback streams need synthesis discipline." +category: research +catalog_summary: "Collecting and synthesizing user feedback across channels into continuous decision signal. Triage discipline that distinguishes loudest-voice (whoever complains most) from averaged-noise (every signal weighted equally) from triaged-synthesis (weighted by source quality and decision relevance)" +display_order: 5 +--- + +# User Feedback Aggregation + +A senior product leader's playbook for collecting and synthesizing user feedback across channels into continuous decision signal. Support tickets, NPS surveys, in-app feedback, sales calls, social mentions, customer councils, all aggregated into a triaged synthesis the team can actually act on. + +Most product programs accumulate feedback they do not use. Channels overflow with submissions; CSAT and NPS scores get reported in monthly updates; customer council meetings produce notes that nobody references. The loudest voices steer roadmap because they are easiest to hear; quieter signal that matters more goes unaddressed. + +This skill is the triage discipline that turns continuous feedback streams into continuous decision signal. Each channel surfaces different signal at different reliability. Each signal type warrants different weight in different decisions. The team that aggregates feedback well makes better decisions; the team that drowns in feedback makes the same decisions they would have made without the feedback. + +Different from `discovery-research-synthesis`, which covers one-off research projects (a defined batch of artifacts, a defined synthesis output). This skill covers the always-on streams: feedback that arrives every day, every week, every month, and that the team must continuously triage and synthesize. + +The voice is the senior product leader who has watched feedback aggregation work and watched it fail. Concrete, opinionated about which channels matter for which decisions, willing to call out where loudest-voice or averaged-noise patterns produce bad outcomes. + +When to use this skill: building a feedback aggregation system, auditing a feedback program that is producing volume without decisions, deciding which feedback channels matter for the program, or designing the synthesis cadence for ongoing feedback streams. + +--- + +## What this skill is for + +This skill spans continuous user-feedback aggregation. The PM-skill distinction: + +- `discovery-research-synthesis` is one-off discovery research. Defined batch, defined output. +- **`user-feedback-aggregation` (this skill)** is ongoing feedback streams. Always-on channels needing continuous synthesis. +- `beta-program-management` covers feedback specific to beta participants. This skill spans all users continuously. +- `ux-research` is structured research projects. This skill is unsolicited feedback. +- `pm-spec-writing` is downstream: specs use feedback aggregation as input. +- `roadmap-planning` is downstream: roadmap uses feedback patterns as input. + +The audience: senior PMs, product directors, customer success and support managers running feedback programs, in-house teams aggregating feedback across many channels. + +What is not in scope: structured discovery research (covered by `discovery-research-synthesis`); beta-specific feedback (covered by `beta-program-management`); commissioned research projects (covered by `ux-research`). + +--- + +## Loudest-voice vs averaged-noise vs triaged-synthesis + +The keystone framing. + +**Loudest-voice.** Whoever complains the most gets their feature. Vocal minorities steer roadmap. Silent majority's needs go unaddressed. The squeaky-wheel anti-pattern. Cost: the program optimizes for the loudest customer, not for the broader customer base; quieter customers leave for products that addressed their needs. + +**Averaged-noise.** Every signal weighted equally. 1 enterprise customer's feedback = 1 trial user's feedback = 1 angry social mention. Volume aggregates without weighting; noise drowns signal. Cost: the team cannot tell which feedback matters; decisions get made on aggregate sentiment that does not reflect the customers who matter most for the strategy. + +**Triaged-synthesis.** Signal weighted by source quality, frequency, and decision relevance. Different feedback types have different weights for different decisions. The team that does this well makes decisions grounded in the signal that matters; the team that does it badly defaults to loudest-voice or averaged-noise. + +The litmus test. Pick a recent product decision. Can the team explain why specific feedback signals weighted into the decision the way they did? If yes, the aggregation is triaged. If the answer is "we heard a lot about this from customers," without specificity about which customers in which contexts, the aggregation is loudest-voice or averaged-noise. + +--- + +## Feedback channels and what each surfaces + +Six common channels. Each surfaces different signal at different reliability. + +**Support tickets.** What users hit when things break or confuse them. High volume, high signal-on-friction, biased toward users willing to contact support. + +**NPS surveys.** Aggregate sentiment toward the product or specific features. Periodic, quantitative-with-comments, bias toward respondents who feel strongly (positive or negative). + +**In-app feedback.** Friction at the moment users encounter it. Contextualized to specific product moments; volume varies; quality varies. + +**Sales calls.** Pre-purchase prospect perspective. Objections, competitive mentions, gaps between marketing and what sales leads with. Bias toward prospects, not existing customers. + +**Social mentions.** Public commentary about the product. Real-time but biased toward customers willing to post publicly; often skews negative or hyper-positive. + +**Customer councils.** Curated panels of customers in structured forums. High-quality feedback from selected customers; bias depends on selection. + +Each channel has strengths and weaknesses. Strong feedback aggregation triangulates across channels rather than relying on one. + +Detail in [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md). + +--- + +## Channel-source weighting + +The discipline that distinguishes triaged-synthesis from averaged-noise. + +**The principle.** Different sources warrant different weights in different decisions. + +**Worked example.** A decision about whether to prioritize an enterprise admin feature. + +- Sales call data showing enterprise prospects asking for the feature: high weight (the decision is about enterprise; the source matches). +- Support ticket data from enterprise customers: high weight (existing enterprise customers' friction is directly relevant). +- NPS data from small-team customers: low weight (the feature is not for them; their satisfaction is not load-bearing for the decision). +- Social mentions: variable weight (signal depends on who is mentioning; enterprise practitioners on LinkedIn carry more weight than anonymous trial users on social). + +**The discipline.** For each decision, identify which sources matter most. Weight accordingly. Volume from low-weight sources should not override signal from high-weight sources. + +**The averaged-noise failure.** Decisions made on aggregate volume regardless of source. The enterprise admin feature gets deprioritized because more total feedback came from small-team customers who do not need it; enterprise customers churn because their needs went unaddressed. + +Detail in [`references/channel-source-weighting.md`](references/channel-source-weighting.md). + +--- + +## Categorization and tagging discipline at scale + +How feedback gets organized when it arrives at high volume. + +**The taxonomy.** + +- Feature area or product surface (where in the product the feedback applies). +- Issue type (bug, friction, feature request, positive signal, edge case). +- User segment (who is providing the feedback). +- Severity or urgency (how blocking is it for the user). +- Source channel (where the feedback came from). + +**The discipline.** + +- Tags emerge from feedback patterns, not from a pre-built taxonomy. +- Tags get refined over time as patterns clarify. +- Multiple tags per feedback item; do not force single-category. +- Periodic taxonomy review surfaces categories that need to merge or split. + +**The volume challenge.** A program receiving 500-2000 feedback items per week needs aggregation tooling that supports tagging at scale. Manual tagging at scale burns out the team; AI-assisted tagging with human review on patterns is often the practical middle path. + +Detail in [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md). + +--- + +## Frequency vs intensity + +Two dimensions of feedback signal. + +**Frequency.** How often the same feedback recurs. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +**Intensity.** How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive, or describe satisfaction as transformative. +- Low-intensity feedback: minor friction or mild satisfaction. + +**The matrix.** + +- High-frequency, high-intensity: top priority. Many users hit this; it matters to them. +- High-frequency, low-intensity: papercuts. Address in batches; individual items are minor but cumulatively erode experience. +- Low-frequency, high-intensity: the affected users are deeply impacted but few. Often segment-specific. +- Low-frequency, low-intensity: noise. Capture; do not action individually. + +**The discipline.** Triage assigns each piece of feedback a frequency-intensity assessment. The combination informs prioritization weight. + +Detail in [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md). + +--- + +## From feedback to product decision + +The synthesis loop that turns aggregated feedback into roadmap input. + +**The loop.** + +- Feedback arrives across channels. +- Triage categorizes and weights. +- Periodic synthesis (weekly, monthly, quarterly) surfaces patterns. +- Patterns inform roadmap discussions, spec drafts, prioritization debates. +- Decisions reference specific feedback patterns as input. + +**The cadences.** + +- Daily: critical feedback (security, data loss, broken core flows) handled immediately. +- Weekly: team review of recent patterns. Adjusts current-quarter execution. +- Monthly: synthesis review. Surfaces trending patterns; informs next-quarter roadmap. +- Quarterly: strategic synthesis. Patterns over the quarter inform strategic planning. + +**The discipline.** Feedback aggregation has cadence. Without cadence, feedback accumulates without producing decisions. + +Detail in [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md). + +--- + +## Closing the loop with users + +When feedback shapes product, telling users matters. + +**The practice.** + +- When feedback drives a change, communicate to the users who provided that feedback. +- "We heard from many of you that X was painful; we shipped Y this week to address it. Thanks for the feedback that informed this work." +- Communication can be public (release notes, blog posts) or targeted (email to users who opened tickets on the issue). + +**Why it matters.** + +- Users who see their feedback acted on engage more in the future. +- The closed loop signals that the team is listening, which strengthens the relationship. +- Users without feedback follow-through stop providing feedback over time. + +**The risk of over-promising.** Promising changes that do not ship erodes trust faster than not promising. Communicate what shipped, not what might ship. + +Detail in [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md). + +--- + +## Detecting drift in feedback patterns over time + +What changes in feedback signal over time can reveal. + +**Drift patterns.** + +- Increasing feedback volume in a category: either the issue is worsening, the user base is growing, or awareness of the channel is increasing. Investigate the cause. +- New patterns emerging: previously-rare feedback becomes more common. Often signals product or market change. +- Patterns disappearing: feedback that used to be common stops. The issue may be resolved, or users may have given up reporting it. +- Sentiment shifts: NPS or CSAT trending differently than before. Often signals broader experience changes. + +**The investigation discipline.** Drift signals warrant investigation. Why did the volume increase? Why did this pattern emerge? The root cause often informs product decisions more than the surface signal. + +Detail in [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md). + +--- + +## Feedback aggregation tooling considerations + +Tooling choices without endorsing specific products. + +**Tooling categories.** + +- Customer feedback platforms (aggregate across multiple sources, support tagging, surface patterns). +- Support ticket systems with analytics layers. +- NPS or survey platforms with response aggregation. +- Customer relationship management systems with feedback fields. +- Custom dashboards combining feedback signal with usage analytics. + +**The criteria for tooling selection.** + +- Does it support multi-channel aggregation, or is it single-channel? +- Does it support tagging at scale? +- Does it surface patterns, or is it just storage? +- Does it integrate with the team's other systems (roadmap, ticketing, communication)? +- Does it scale with program volume? + +**The build-vs-buy tension.** Many programs end up with a mix: dedicated tooling for some channels, custom dashboards for cross-channel synthesis. Pure single-tool solutions often miss the multi-channel pattern detection. + +Detail in [`references/tooling-considerations.md`](references/tooling-considerations.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md). + +- "Loudest customers steer the roadmap." Loudest-voice pattern; vocal minorities dominate; silent majority underaddressed. +- "We have lots of feedback but no decisions." Aggregation without synthesis; no triage cadence. +- "Our channels overflow; we cannot keep up." Aggregation without weighting or tooling that scales. +- "Different teams cite different feedback for the same decision." Channel-source weighting absent; teams reach for whatever feedback supports their position. +- "Customer council meetings produce notes nobody references." Council without synthesis loop; the meeting is the deliverable. +- "NPS is reported monthly but does not inform decisions." NPS as compliance metric, not as decision input. +- "Feedback we shipped against did not move sentiment." Wrong feedback prioritized; the loud feedback was not the most consequential. +- "Users gave feedback once and never returned." Closed-loop missing; users feel ignored. +- "We tagged everything but cannot find patterns." Taxonomy too granular or too noisy; periodic taxonomy review missing. +- "Drift in feedback caught us by surprise." Drift detection missing; the team did not investigate trending patterns until they became problems. +- "Sales call data and support ticket data tell different stories." Cross-channel synthesis missing; each channel's signal stays in its own silo. + +--- + +## The framework: 12 considerations for feedback aggregation + +When designing or auditing a feedback aggregation system, walk these 12 considerations. + +1. **Triaged-synthesis, not loudest-voice or averaged-noise.** Signal weighted by source, frequency, decision relevance. +2. **Channel taxonomy known.** Support, NPS, in-app, sales, social, councils. What each surfaces. +3. **Channel-source weighting per decision.** Different decisions weight channels differently. +4. **Categorization and tagging at scale.** Taxonomy that emerges from data; tooling that supports volume. +5. **Frequency-intensity matrix.** Each feedback item assessed on both dimensions. +6. **Synthesis cadence.** Daily critical, weekly patterns, monthly review, quarterly strategic. +7. **Cross-channel triangulation.** Patterns that appear across channels are stronger. +8. **Closing the loop with users.** When feedback drives change, communicate. +9. **Drift detection.** Patterns over time reveal changes. +10. **Tooling that scales.** Multi-channel aggregation, pattern surfacing, integration. +11. **Specific feedback informs specific decisions.** Decisions traceable to specific signals. +12. **Honest assessment of source bias.** Each channel's bias acknowledged in synthesis. + +The output of the framework is feedback aggregation that produces decision-grade signal continuously, scales with program volume, and treats users well enough that they keep providing feedback over time. + +--- + +## Reference files + +- [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md) - Six common channels with strengths, weaknesses, biases, and synthesis implications. +- [`references/channel-source-weighting.md`](references/channel-source-weighting.md) - Decision-relative weighting. Worked examples of how channels weight differently for different decisions. +- [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md) - Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. +- [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md) - The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. +- [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md) - The synthesis loop. Cadences. The discipline of decisions traceable to feedback. +- [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md) - When and how to communicate feedback-driven changes. The over-promising risk. +- [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md) - Drift patterns. Investigation discipline. Drift as early signal of change. +- [`references/tooling-considerations.md`](references/tooling-considerations.md) - Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. +- [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: feedback as continuous signal, not periodic survey + +The teams that make good product decisions over time are the ones that aggregate feedback continuously and synthesize it into decision input. Not as compliance with a feedback-collection mandate; not as monthly NPS reporting; not as ad-hoc reactions to whoever complains loudest. As a continuous discipline that surfaces what users are actually experiencing, weighted appropriately, synthesized for the decisions the team is actually making. + +Feedback aggregation done well is invisible: the team makes better decisions, but the feedback work itself does not feel heroic. Feedback aggregation done badly is loud: channels overflow, NPS gets reported, customer councils produce decks, and decisions still get made on gut feel because the feedback work did not produce decision input. + +The discipline is in the triage. Each channel weighted by what it reveals. Each piece of feedback assessed on frequency and intensity. Patterns surfaced through synthesis. Decisions traceable to specific feedback. The closed loop with users that keeps feedback flowing. + +When in doubt about whether a feedback program is working, ask: can the team trace recent decisions to specific feedback patterns, are channels weighted differently for different decisions, is the synthesis cadence producing input the team uses, are users seeing their feedback acted on? If yes to all of those, the program is real. If no to any, the gap is where the feedback work is failing to convert into decisions. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md new file mode 100644 index 0000000..5faac7a --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md @@ -0,0 +1,213 @@ +# Categorization and tagging at scale + +Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. + +How feedback gets organized when it arrives at high volume. The discipline that prevents the "we tagged everything but cannot find patterns" failure. + +--- + +## The taxonomy dimensions + +Each feedback item gets tagged across multiple dimensions. + +**Feature area or product surface.** Where in the product the feedback applies. Examples: onboarding, dashboard, billing, integrations, mobile app. + +**Issue type.** Bug, friction, feature request, positive signal, edge case. + +**User segment.** Who is providing the feedback. Examples: free tier, pro tier, enterprise, trial, churned. + +**Severity or urgency.** How blocking is the issue. Examples: critical (blocks core flow), high (significant friction), medium (workaround exists), low (minor). + +**Source channel.** Where the feedback came from. Examples: support ticket, NPS comment, in-app widget, sales call, social mention, customer council. + +**Date or time period.** When the feedback was submitted. Useful for drift detection. + +Most programs use 3-6 of these dimensions. More dimensions produce richer queries; more dimensions also increase tagging burden. + +--- + +## Tags emerge from data, not from a pre-built taxonomy + +The same principle as discovery research synthesis (see `discovery-research-synthesis`). + +**The pattern.** Tags emerge from feedback patterns. Initial tagging captures what users actually said; the taxonomy builds up from the data. + +**The anti-pattern.** Pre-built taxonomies that force feedback into categories. Patterns the taxonomy did not anticipate get missed; categories that do not match the data get used anyway. + +**Why emergent tagging matters.** + +- Users describe issues in their own language; pre-built categories often miss the actual issues. +- New product features generate new categories; emergent tagging adapts. +- Issues evolve over time; emergent tagging captures the evolution. + +**The transition.** Programs starting feedback aggregation often need a starting taxonomy to begin with. The starting taxonomy is provisional; it gets refined as feedback accumulates and patterns clarify. + +--- + +## Multiple tags per feedback item + +Most feedback items deserve multiple tags. + +**The pattern.** A single feedback item often touches multiple feature areas, issue types, or context dimensions. + +**Worked example.** Support ticket: "I'm an enterprise admin trying to set up SSO for the team and the configuration step keeps timing out." + +Tags: + +- Feature area: SSO configuration, admin settings. +- Issue type: bug (timeout) + friction (configuration is hard). +- User segment: enterprise. +- Severity: high (blocks core enterprise setup). +- Source channel: support ticket. + +Multiple tags capture the feedback's full context. Single-tag forcing loses information. + +--- + +## Tagging at volume + +Programs receiving 500-2000+ feedback items per week need tooling support. + +**Tooling approaches.** + +- **Manual tagging.** Each item tagged by a human. Highest quality; lowest scale. Works for low-volume programs (under 100 items per week). +- **AI-assisted tagging.** AI suggests tags; humans review and adjust. Scales better; quality depends on the AI's training and the team's review discipline. +- **Automated tagging.** AI tags without human review. Scales highest; quality is lowest because no one validates. +- **Hybrid.** Manual tagging for high-priority items (enterprise feedback, critical issues), AI-assisted for the bulk. + +**The recommended pattern for most programs.** AI-assisted tagging with human review on patterns. The AI handles bulk classification; humans review aggregate patterns and validate that the categorization is producing useful signal. + +**The volume calibration.** + +- Under 100 items/week: manual tagging is feasible and preferred. +- 100-500 items/week: AI-assisted with sample review. +- 500+ items/week: AI-assisted with pattern review; manual handling reserved for high-priority items. + +--- + +## Tag quality vs tag granularity + +Two competing pressures. + +**Granularity helps.** More specific tags surface more specific patterns. "Onboarding configuration step 3 friction" is more useful than "onboarding friction." + +**Granularity also harms.** More specific tags fragment data. If 10 different tags split what should be one pattern, the pattern is invisible. + +**The middle path.** + +- Start with moderate granularity. +- Refine over time. Tags that consistently co-occur may need to merge; tags that combine distinct patterns may need to split. +- Periodic taxonomy review (see below) catches granularity issues. + +--- + +## Periodic taxonomy review + +Quarterly or bi-annual review of the taxonomy. + +**The questions.** + +- Are there tags that consistently co-occur and could merge? +- Are there tags that contain multiple distinct patterns and should split? +- Are there new patterns that need new tags? +- Are there tags that no longer apply (deprecated features, resolved issues)? +- Is the taxonomy too granular (fragmenting patterns) or too coarse (hiding patterns)? + +**The output.** A revised taxonomy. Old tags may get retired; new tags may get added; some tags may get renamed. + +**The discipline.** Without periodic review, taxonomies decay. Old tags accumulate; new patterns get tagged into wrong categories; the taxonomy stops surfacing useful patterns. + +**The frequency.** Quarterly works for most programs. Annual works for stable programs with low product change rate. Bi-annual works as a middle path. + +--- + +## Tag conflicts and resolution + +Sometimes feedback could be tagged in multiple ways. + +**Resolution approaches.** + +- **Multi-tagging.** When in doubt, apply multiple tags. Captures the ambiguity rather than forcing a choice. +- **Convention.** Document conventions for ambiguous cases. "Friction with the dashboard's filter functionality" gets tagged "dashboard" + "filtering" + "friction" rather than choosing. +- **Reviewer judgment.** Train reviewers (human or AI) on conventions. Ambiguous cases get reviewed for consistency. + +**The cost of inconsistent tagging.** Patterns become invisible because the same kind of feedback gets tagged differently. The "we tagged everything but cannot find patterns" failure often traces to inconsistent tagging. + +--- + +## Tag distribution as signal + +The distribution of tags across feedback can be informative beyond individual tags. + +**Examples.** + +- Spike in volume on a specific tag: trending issue or feature area in flux. +- Decline in volume on a tag: issue resolved or users gave up reporting. +- Co-occurrence patterns: tags that consistently appear together suggest related issues. +- Segment-specific tag distributions: enterprise vs free-tier feedback patterns differ. + +**The dashboard view.** Most feedback aggregation tooling supports tag-distribution dashboards. The dashboards surface patterns the team would not see in individual feedback items. + +--- + +## Tagging discipline at the channel level + +Different channels need different tagging conventions. + +**Support tickets.** Often pre-tagged by the support system (issue type, product area). Augment with feedback-specific tags. + +**NPS comments.** Lighter tagging. Often just sentiment + topic area. Open-ended comments are mined for patterns; not every comment needs comprehensive tagging. + +**In-app feedback.** Auto-tagged by context (which page, which feature). Augment with issue-type and severity. + +**Sales calls.** Often summarized rather than tagged at the moment level. Summaries get tagged. + +**Social mentions.** Auto-classified by sentiment and topic; manual review for high-impact mentions. + +**Customer council notes.** Manually tagged after each council session. Higher tagging investment because volume is low and signal is high. + +--- + +## Cross-channel tag consistency + +Tags should mean the same thing across channels. + +**The risk.** "Onboarding friction" in support tickets means something slightly different than "onboarding friction" in NPS comments because the channels surface different aspects. + +**The mitigation.** + +- Document tag definitions explicitly. "Onboarding friction" includes X, Y, Z signals. +- Periodic cross-channel calibration. Review tagged samples from each channel to ensure consistency. +- Channel-specific sub-tags where appropriate. "Onboarding-friction-support" vs "Onboarding-friction-nps" if the distinction matters. + +**The honest framing.** Cross-channel tag consistency is hard. Strong programs work toward it; perfect consistency is rare. + +--- + +## Common tagging failures + +**Pre-built taxonomy forced.** Patterns the taxonomy did not anticipate get missed. + +**Single-tag forcing.** Multi-dimensional feedback gets reduced to one tag; information lost. + +**Inconsistent tagging.** The same kind of feedback gets tagged differently across reviewers or time periods. + +**Tag bloat.** Too granular; patterns fragment across many tags. + +**Tag coarseness.** Too broad; distinct patterns hide within the same tag. + +**No taxonomy review.** Tags decay over time without periodic review. + +**Volume overwhelms tagging.** High-volume programs without tooling support; tagging falls behind; old feedback never gets tagged. + +**Tag-without-purpose.** Tagging happens because it is supposed to; nobody uses the tags for synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The taxonomy dimensions. Emergent tagging. Multi-tag discipline. Tagging at volume (manual, AI-assisted, automated, hybrid). Tag quality vs granularity tradeoffs. Periodic taxonomy review. Tag conflict resolution. Tag distribution as signal. Channel-specific tagging. Cross-channel consistency. Common failures. + +## Implementation choices that stay internal + +Specific tagging tools and AI models. Specific tag definition documents. Specific reviewer training. Specific dashboard configurations. The team's own conventions for tagging within the principles. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md new file mode 100644 index 0000000..aac3763 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md @@ -0,0 +1,216 @@ +# Channel-source weighting + +Decision-relative weighting. Worked examples of how channels weight differently for different decisions. + +The discipline that distinguishes triaged-synthesis from averaged-noise. Different sources warrant different weights for different decisions; treating all sources as equal produces decisions made on aggregate volume rather than on signal that matters. + +--- + +## The weighting principle + +Each piece of feedback has a source. The source's weight in a decision depends on how relevant the source is to that decision. + +**Worked principle.** A piece of feedback from an enterprise customer has different weight than a piece of feedback from a trial user when the decision is about enterprise pricing. The enterprise customer's feedback is high-weight; the trial user's feedback is low-weight (they are not the audience for the decision). + +The same piece of feedback from a trial user has different weight when the decision is about trial conversion. Now the trial user is the audience; their feedback is high-weight. + +The weighting is decision-relative, not source-absolute. + +--- + +## Worked examples of channel weighting + +### Decision: Should we prioritize the enterprise admin role overhaul this quarter? + +**Audience for the decision.** Existing enterprise customers and enterprise prospects. + +**Channel weights for this decision.** + +- Sales call data with enterprise prospects: high weight. They directly inform the decision. +- Support ticket data from enterprise customers: high weight. Existing enterprise friction is directly relevant. +- Customer council data from enterprise members: high weight. Curated enterprise perspective. +- NPS data from enterprise customers: moderate weight. Aggregate signal but not specific to admin features. +- NPS data from small-team customers: low weight. Different segment; admin features not relevant. +- Social mentions: variable weight. Enterprise practitioners' posts higher than anonymous trial accounts. +- In-app feedback from small-team users: low weight. Different segment. + +The decision weighs enterprise sources heavily. Volume from non-enterprise sources should not displace enterprise signal. + +### Decision: Should we redesign the onboarding flow for new free-tier signups? + +**Audience for the decision.** Free-tier new signups. + +**Channel weights for this decision.** + +- Support tickets from free-tier users in their first week: high weight. Direct friction signal. +- In-app feedback from free-tier users during onboarding: high weight. Moment-of friction. +- NPS data from free-tier users: moderate weight. Aggregate sentiment. +- Sales call data: low weight. Sales calls are usually with prospects, not free signups; pre-decision conversation differs from post-signup experience. +- Customer council data: low weight. Councils usually have established customers, not new signups. +- Support tickets from long-tenured customers: low weight. Their onboarding friction was a year ago; current onboarding may differ. + +The decision weighs new-signup sources heavily. Long-tenured customer feedback is informative for other decisions but not this one. + +### Decision: Should we launch a new pricing tier? + +**Audience for the decision.** Both prospects and existing customers (existing customers may move tiers; prospects' tier choice affects acquisition). + +**Channel weights for this decision.** + +- Sales call data on pricing conversations: high weight. Prospects' pricing perception is critical. +- Support tickets about pricing or upgrade requests: high weight. Existing customer pricing pain points. +- Customer council discussion on pricing: high weight. Strategic discussion with curated customers. +- NPS data with pricing comments: moderate weight. Some signal but not decision-specific. +- Social mentions about pricing: moderate weight. Public perception affects acquisition. +- In-app feedback unrelated to pricing: low weight. Off-topic for this decision. + +Multiple high-weight channels because the decision spans audiences. + +### Decision: Should we invest in social mention monitoring as a primary channel? + +**Audience for the decision.** Strategic question about feedback aggregation infrastructure. + +**Channel weights for this decision.** + +- Past examples of social signal driving decisions: high weight. Direct evidence. +- Past examples where social signal misled (vocal minority, anonymous accounts): high weight as counter-evidence. +- Other companies' published patterns on social signal: moderate weight. Indicative but not specific. +- Internal team intuition about social signal: low weight unless backed by data. + +The decision weighs evidence of past signal-driven decisions heavily. + +--- + +## The averaged-noise failure + +When sources are weighted equally regardless of decision relevance. + +**The pattern.** + +- The team aggregates all feedback equally. +- Volume from any source counts the same. +- The most-feedback issue gets prioritized regardless of source. + +**Why it fails.** + +- Decisions get made on aggregate volume rather than on signal that matters for that decision. +- Decisions that should be enterprise-driven get displaced by volume from segments that do not matter for that decision. +- The team optimizes for the squeaky-wheel signal because it is loudest in the aggregate. + +**Worked failure.** The team is deciding whether to prioritize enterprise admin features. NPS and in-app feedback show low priority for this area (because most respondents are small-team users who do not need enterprise admin). Sales calls and enterprise support tickets clearly indicate the priority. The team aggregates volume, sees more total feedback against enterprise admin priority, and deprioritizes. Enterprise customers churn. + +**The cure.** Weight by decision relevance. Enterprise channels weight high for enterprise decisions; small-team feedback should not displace enterprise signal on enterprise decisions. + +--- + +## The loudest-voice failure + +When the most vocal source dominates regardless of representativeness. + +**The pattern.** + +- A small number of customers complain frequently and loudly. +- Their feedback dominates synthesis because they generate the most volume. +- Their preferences shape the roadmap. + +**Why it fails.** + +- Vocal minorities do not represent the broader user base. +- Silent majority's needs go unaddressed. +- The roadmap optimizes for the customers most likely to complain rather than the customers most strategic for the business. + +**The cure.** Weight by source quality and representativeness, not by volume. A complaint repeated 50 times by one user is not 50x the signal of one complaint by 50 distinct users. + +--- + +## How to set weights + +In practice, weighting is qualitative. Quantitative scoring schemes often produce false precision. + +**The discipline.** + +- For each decision, identify the audience (who the decision serves). +- Identify which channels surface signal from that audience. +- Identify which channels do not (and why their feedback is less relevant for this decision). +- In synthesis, give high-weight channel signal more attention than low-weight channel signal. + +**Quantitative weighting risks.** + +- Scoring systems (this channel = 3x weight; that channel = 1x) often produce false precision. +- Decisions made on weighted scores rather than on judgment can miss qualitative nuances. +- The discipline is qualitative judgment informed by source-relevance, not arithmetic. + +**The honest framing.** Weighting is a judgment call. The synthesis names the weighting choices explicitly: "We weighted enterprise channel signal heavily here because the decision is about enterprise priorities." Readers can disagree with the weighting; disagreement is productive. + +--- + +## Source bias acknowledgment + +Each source has biases that affect its signal. + +**Sources skew toward.** + +- Support: users willing to contact support; tend toward problem-reporting. +- NPS: users with strong opinions; middle-ground underrepresented. +- In-app feedback: users who interact with widgets; specific segments may dominate. +- Sales calls: prospects, not existing customers; pre-purchase context. +- Social: users who post publicly; enthusiasts and angry voices. +- Councils: curated members; specific selection criteria. + +**The synthesis discipline.** When weighting, acknowledge the bias. "Support tickets show high friction in this area" should be paired with "noting the support-channel bias toward users who contact support." The acknowledgment makes synthesis more honest and readers more informed. + +--- + +## Multi-channel triangulation as weighting + +When patterns appear across multiple channels, weighting becomes easier. + +**Strong cross-channel signal.** Same pattern in support, NPS, in-app, and sales. The cross-channel pattern survives any single channel's bias. + +**Single-channel signal.** Pattern in only one channel. Weighting depends on channel reliability for the decision; treat with more caution. + +**Conflicting cross-channel signal.** Different channels disagree. Investigate the source of the conflict; the disagreement often reveals segment differences or context-specific patterns. + +The discipline. Cross-channel triangulation is a form of weighting: patterns that survive multiple channels' biases are more reliable signal. + +--- + +## Weighting in tooling + +Some feedback aggregation tools support explicit weighting (priority scores, segment-specific dashboards). + +**Tooling support.** + +- Tagging by source channel and segment. +- Filtering and grouping by tag combinations. +- Dashboards that show signal per segment or channel. + +**The tooling principle.** Tooling supports weighting; the weighting judgment still belongs to humans. Tools that automate weighting away from human judgment risk false precision. + +**The build-vs-buy tension.** Many programs end up with custom dashboards or filtering that supports their specific weighting. Generic tooling rarely supports the program's specific decision-relative weighting needs out of the box. + +--- + +## Common weighting failures + +**No weighting.** All sources treated equally. Averaged-noise pattern. + +**Static weighting.** Same weights regardless of decision. Misses that different decisions need different weights. + +**Quantitative false precision.** Scoring systems that produce decisions without judgment. + +**Volume as proxy for weight.** Loudest-voice pattern; whoever generates most feedback wins. + +**Bias acknowledgment skipped.** Synthesis claims stronger signal than the channel's bias warrants. + +**Single-channel reliance.** Decisions made on one channel's signal without triangulation. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relative weighting principle. Worked weighting examples for different decisions. The averaged-noise and loudest-voice failures. How to set weights. Source bias acknowledgment. Multi-channel triangulation. Weighting in tooling. Common failures. + +## Implementation choices that stay internal + +Specific weighting conventions for specific decision types. Specific tooling that supports weighting. Specific dashboard configurations. The team's own conventions for naming weighting choices in synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md new file mode 100644 index 0000000..c2c0ec3 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md @@ -0,0 +1,263 @@ +# Channel types and what each surfaces + +Six common feedback channels with strengths, weaknesses, biases, and synthesis implications. Each channel surfaces different signal at different reliability; strong aggregation triangulates across channels. + +--- + +## Channel 1: Support tickets + +What users hit when things break or confuse them. + +**What support surfaces.** + +- Functional friction (where the product breaks down for users). +- Documentation gaps (questions users ask repeatedly). +- Feature requests that arrive in the form of complaints. +- Edge case failures. +- Confusion about intended behavior vs actual behavior. + +**Strengths.** + +- High volume; signal accumulates from many users. +- Grounded in specific user contexts (the user was trying to do something specific). +- Captures friction users actually encountered, not friction they speculated about. + +**Weaknesses.** + +- Bias toward users willing to contact support. Users who silently leave the product do not appear here. +- Bias toward fixable issues. Users who struggle but figure it out (or give up) without contacting support are invisible. +- Sentiment skew: users contact support when frustrated; positive experience is underrepresented. + +**Synthesis implications.** + +- Support volume on a feature area is a strong signal of friction; absence of volume is weak signal of satisfaction. +- Pattern-detection across tickets reveals systemic issues better than individual tickets. +- Combine with usage analytics: a feature with high support volume and low usage suggests broken value; high support volume and high usage suggests meaningful friction in something users still want. + +--- + +## Channel 2: NPS surveys + +Aggregate sentiment toward the product or specific features. + +**What NPS surfaces.** + +- Aggregate sentiment trend lines. +- Distribution between promoters, passives, and detractors. +- Open-ended comments (often the most useful part). +- Sentiment differences across segments. + +**Strengths.** + +- Quantitative signal that aggregates across many users. +- Trends over time reveal whether sentiment is improving or degrading. +- Open-ended comments provide qualitative depth. +- Industry-standard metric makes benchmarking possible. + +**Weaknesses.** + +- Response bias. Users with strong opinions (positive or negative) respond at higher rates than users in the middle. +- Cultural and segment biases in scoring (some segments score lower on average than others for cultural reasons). +- The 0-10 scale loses granularity; many decisions need more than promoter/passive/detractor categorization. +- Surveys on specific features can have small sample sizes that produce noisy signal. + +**Synthesis implications.** + +- NPS as a single number is less useful than NPS distribution and trend. +- Open-ended comments are often the highest-value section; mine them for patterns. +- Segment-specific NPS is more actionable than aggregate NPS. +- Single-quarter NPS shifts can be noise; multi-quarter trends are more reliable signal. + +--- + +## Channel 3: In-app feedback + +Friction at the moment users encounter it. + +**What in-app feedback surfaces.** + +- Contextual friction (the user was at a specific moment in the product when they submitted). +- Ratings or sentiment scoped to specific features or flows. +- Quick observations users would not bother to file as a ticket. + +**Strengths.** + +- Captures the moment. Friction is fresh; context is automatic (the system knows where the user was). +- Lower friction submission than support tickets; surfaces issues users would not formally report. +- Volume varies; some products see high in-app feedback, others minimal. + +**Weaknesses.** + +- Bias toward users who interact with the feedback widget. Some segments use it heavily; others rarely. +- Quality varies. Quick submissions are often shallow. +- Volume can overwhelm if the widget triggers too aggressively. + +**Synthesis implications.** + +- In-app feedback is best for detecting moment-specific friction. +- Pair with usage analytics: where users submit feedback in the product is informative. +- Filter by submission length and pattern; one-word submissions ("frustrating!") are weak signal compared to specific submissions ("I expected the export to include the filters I had applied; it did not"). + +--- + +## Channel 4: Sales calls + +Pre-purchase prospect perspective. + +**What sales calls surface.** + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Prospect vocabulary for describing their situation (often different from internal product language). + +**Strengths.** + +- Prospect view of the product before they have invested in it. Reveals what attracts and what blocks adoption. +- Competitive intelligence in the form of comparisons prospects make. +- Hire criteria signal (why prospects would choose the product). + +**Weaknesses.** + +- Bias toward prospects, not existing customers. Existing-customer experience differs. +- Sales-team interpretation can color how calls are tagged. +- Stage selection matters: early-stage discovery calls reveal different things than late-stage closing calls. + +**Synthesis implications.** + +- Sales call data informs positioning, pricing, and adoption-hire-criteria decisions. +- Combine with existing-customer feedback to understand the full lifecycle. +- Lost-deal analysis (specifically, calls with prospects who did not buy) is a separate research mode that surfaces what the product would need to win. + +--- + +## Channel 5: Social mentions + +Public commentary about the product. + +**What social mentions surface.** + +- Public sentiment in real time. +- Comparison to competitors (often more honest than survey responses). +- Use cases and use contexts the team did not anticipate. +- Reputation signals (how the product is perceived in the broader market). + +**Strengths.** + +- Real-time signal. +- Public visibility means the team can respond to issues that affect brand reputation. +- Captures users who post publicly but would not file feedback through formal channels. + +**Weaknesses.** + +- Bias toward users willing to post publicly. Often skews toward enthusiasts (positive) or angry (negative); middle-ground users are quiet. +- Volume can overwhelm; signal-to-noise ratio is low. +- Anonymous accounts complicate weighting (who is this person? are they a real customer?). +- Platform algorithms shape what is visible; the visible signal is not the full signal. + +**Synthesis implications.** + +- Social signal is one input, rarely a primary driver. Triangulate with other channels. +- Track reputational themes (what the product is known for in the broader market). +- Respond to specific issues that affect brand reputation; do not use social as the primary feedback prioritization channel. + +--- + +## Channel 6: Customer councils + +Curated panels of customers in structured forums. + +**What customer councils surface.** + +- Curated customer perspective on strategic questions. +- Deep discussion that reveals motivations and priorities. +- Cross-customer patterns (council members compare notes; the team sees what they share). +- Long-term relationship signal (council members commit time and engagement). + +**Strengths.** + +- High-quality feedback from selected customers. +- Structured forum makes discussion deeper than ad-hoc feedback. +- Council members often become advocates and references. + +**Weaknesses.** + +- Bias depends on selection. A council selected for size, role, or vocal customers will skew accordingly. +- Council members are often outliers (engaged, willing to commit time); their perspective may not represent broader users. +- Small sample size (usually 5-30 members); patterns from one council are weak signal. +- Cost: councils require curation, scheduling, and ongoing relationship management. + +**Synthesis implications.** + +- Council feedback is valuable but limited; do not treat as representative of the full user base. +- Use councils for strategic discussions, not for tactical prioritization. +- Council patterns can be a leading indicator of broader user patterns; validate with other channels. + +--- + +## Channels not covered here + +Some feedback channels are out of scope for this skill but worth naming. + +**Beta participants.** Covered by `beta-program-management`. Beta feedback is bounded to the beta period; this skill covers ongoing streams. + +**Discovery research interviews.** Covered by `discovery-research-synthesis`. One-off research projects, not always-on streams. + +**App store reviews.** A specific channel for consumer products. Similar dynamics to social mentions: public, biased toward strong opinions, real-time but volume-heavy. + +**Customer success quarterly business reviews.** Often produce structured customer feedback; can be treated as a council-like channel for top customers. + +**Internal employee feedback.** Sometimes valuable (employees are users of internal tools, or use the product alongside customers); always biased toward internal context. + +--- + +## Cross-channel triangulation + +Patterns that appear across channels are stronger than patterns from a single channel. + +**Worked example.** A feature area showing: + +- Support tickets: increasing volume in this area. +- NPS comments: this area mentioned negatively in detractor comments. +- In-app feedback: friction submissions in this area. +- Sales calls: prospects asking about this area as a comparison point against competitors. + +The cross-channel pattern is stronger than any single-channel signal. The feature area is a load-bearing issue across multiple lenses. + +**Worked counter-example.** A loud single-channel signal: + +- Social mentions: vocal complaints about a feature. +- Support tickets: minimal volume on the same feature. +- NPS: feature not flagged in detractor comments. +- Sales calls: feature not raised by prospects. + +The cross-channel pattern shows the social signal is loud but not load-bearing. Loud-on-one-channel-only is often vocal-minority signal. + +--- + +## Channel reliability calibration + +Different channels have different reliability for different kinds of decisions. + +**Functional friction decisions.** Support tickets and in-app feedback are most reliable. NPS is moderate. Social and sales are less reliable. + +**Adoption hire-criteria decisions.** Sales calls are most reliable. Support tickets and in-app feedback are less reliable (existing-customer bias). + +**Positioning decisions.** Sales calls and social mentions are most reliable (prospect/public perception). NPS and councils are moderate. + +**Strategic prioritization.** Customer councils and NPS trends are useful inputs. Support tickets indicate friction but not strategic priority. + +**Reputation decisions.** Social mentions are direct signal. Support and NPS are indirect. + +The discipline. For each decision, identify which channels are most reliable. Weight accordingly. + +--- + +## Methodology-level choices that stay in the public skill + +The six channel types with strengths, weaknesses, biases, and synthesis implications. Channels not covered. Cross-channel triangulation. Channel reliability calibration for different decision types. + +## Implementation choices that stay internal + +Specific tooling per channel. Specific tagging schemas. Specific integration patterns across channels. The team's own conventions for channel coverage. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md new file mode 100644 index 0000000..5c70fb4 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md @@ -0,0 +1,246 @@ +# Closing the loop with users + +When and how to communicate feedback-driven changes. The over-promising risk. + +Closing the loop is the practice of telling users when their feedback drove a product change. Done well, it strengthens the feedback relationship; users see their input matter. Done badly, it over-promises or appears performative; trust erodes. + +--- + +## Why closing the loop matters + +Users who provide feedback are doing the team a favor. The cost is their time and attention. The return on their investment is, in part, seeing their input acted on. + +**What happens when the loop is open.** + +- Users provide feedback. +- The team uses it (or does not). +- Users do not know what happened. +- Engagement decays. Why provide feedback if it does not seem to matter? + +**What happens when the loop is closed.** + +- Users provide feedback. +- The team uses it (or explains why not). +- Users see their input matter. +- Engagement strengthens. Future feedback flows. + +--- + +## What gets communicated + +Three categories of communication. + +**Changes shipped.** "We shipped X this week. Many of you reported Y was painful; X addresses that." + +- Specific, actionable, ties to specific feedback. +- Best when the team can quantify the change ("Step 3 deferral; activation rate increased from 32% to 41% in the first month"). + +**Changes coming.** "We are working on X for Q3. Several of you have asked about this; here is the timeline." + +- Specific timeline. +- Honest about uncertainty if applicable. +- Risk: over-promising. Communicating coming changes that do not ship erodes trust. + +**Decisions to defer or decline.** "We have heard feedback about X; we are choosing not to prioritize it because Y. Here is the reasoning." + +- Honest about the deferral. +- Explains the reasoning. +- Treats users as capable of understanding tradeoffs. + +The third category is rarely done; it is the most credibility-building. Teams that explain why something was not prioritized earn more trust than teams that promise everything. + +--- + +## Communication channels + +How to close the loop. + +**Public channels.** + +- **Release notes.** Standard post-launch communication. Includes feedback context where relevant. +- **Blog posts or changelog.** Longer-form for major changes. Names the feedback patterns that drove the work. +- **Public roadmap.** Shows what is coming; signals that user feedback informs prioritization. + +**Targeted channels.** + +- **Email to users who reported the issue.** "You reported X; we shipped Y to address it." Personalized; high impact for specific users. +- **In-app notification at the moment of relevance.** When the user encounters the changed flow, an in-product banner: "We changed this based on feedback like yours; here is what is different." +- **Customer success outreach.** For high-value or high-engagement users, direct outreach is appropriate. + +**Community channels.** + +- **Beta or community forums.** Where applicable, communicate to the engaged community. +- **Social media.** For high-visibility changes; risk of public attention if poorly communicated. + +The channel should match the audience and the change. High-impact public changes warrant public communication; targeted changes warrant targeted communication. + +--- + +## Frequency and timing + +When to close the loop. + +**Immediately after shipping.** Most effective. The change is fresh; users remember providing feedback. + +**Periodic recap (monthly or quarterly).** "Here are the changes we shipped this quarter, and the feedback patterns that motivated them." + +- Useful for changes that did not warrant individual announcement. +- Builds an aggregate sense that feedback is shaping the product. + +**Before shipping (preview).** "We are about to ship X; here is what to expect." + +- Heads-up for users who will encounter the change. +- Risk: pre-launch announcements that get delayed; users wonder when the change is coming. + +The frequency calibration. Avoid silence (users feel ignored). Avoid over-communication (users tune out). Calibrate to the change cadence and audience attention. + +--- + +## The over-promising risk + +Communicating future changes that do not ship erodes trust. + +**The pattern.** + +- The team announces "we are working on X" with a timeline. +- The work gets deprioritized, delayed, or canceled. +- Users who counted on the change feel deceived or ignored. + +**Why it happens.** + +- Marketing or stakeholder pressure to share roadmap information. +- The team's own optimism about timelines. +- Failure to communicate when plans change. + +**The cure.** + +- Communicate shipped changes with confidence. +- Communicate coming changes with appropriate hedging ("we are exploring this," "we are planning this for next quarter"). +- Communicate plan changes when they happen, not silently. + +**The honest framing.** Promising "X will ship in Q3" is high-risk; promising "X is on our radar; we are evaluating priority" is honest. The first looks more confident; the second is more credible over time. + +--- + +## Communication for declined or deferred feedback + +When the team decides not to prioritize requested changes. + +**The pattern.** + +- User provides feedback requesting a change. +- The team evaluates and decides not to prioritize. +- The team communicates the decision. + +**Strong communication.** + +- "Several of you have asked about [feature]. We have evaluated and are choosing not to prioritize it this year because [reason]. Here are alternatives or workarounds that may help in the meantime." +- "We hear the feedback about [issue]. We are choosing not to address this for now because [tradeoff]. We are open to reconsidering if the pattern strengthens." + +**Why it builds trust.** + +- Acknowledges the feedback was heard. +- Explains the reasoning. +- Treats the user as capable of understanding tradeoffs. + +**The risk of avoiding.** + +- Silence. The user wonders if the feedback was heard. +- "Maybe in the future." Vague commitments that do not commit. +- "We will consider it." Performative. + +The decline communication is rare in practice but disproportionately valuable. + +--- + +## Communication for high-volume feedback + +When many users have provided similar feedback. + +**The pattern.** + +- A specific change addresses widely-reported feedback. +- The team has many users to potentially notify. + +**Approaches.** + +- **Public announcement** referencing the feedback pattern. "Many of you reported X; we shipped Y." +- **Targeted email to users who reported the issue** (using support ticket history, NPS comments, etc.). +- **In-product notification** at the moment of relevance. + +**The capacity calibration.** Targeted communication is high-effort; public communication scales. Most programs combine: public announcement for visibility, targeted communication for highest-impact users. + +--- + +## Personal vs aggregate + +Sometimes the closing-the-loop communication is to a specific user; sometimes it is aggregate. + +**Personal.** + +- "John, you reported X two months ago. We shipped Y this week to address it. Thanks for the feedback that informed this work." +- Direct email or in-app message. +- High impact for the specific user; low cost; very high relationship value. + +**Aggregate.** + +- "Many of you have asked about X; we shipped Y this week." +- Public announcement; reaches many users. +- Lower per-user impact but scales. + +The discipline. Personal communication for high-impact users (long-tenured customers, design partners, council members). Aggregate for broader changes. + +--- + +## When closing the loop fails + +Common failures. + +**Silence.** The most common failure. Users provide feedback; the team uses it (or does not); users never know what happened. Engagement decays. + +**Generic acknowledgment.** "Thanks for the feedback! We will look into it." Standard auto-reply that everyone gets. Feels performative; closes the loop technically but not meaningfully. + +**Over-promising.** "We will ship this in Q3." The team misses the date or cancels; users feel deceived. + +**Late communication.** Changes shipped months ago; communication never happens; users stopped using the product. + +**Vague communication.** "We have heard your feedback and are working on improvements." No specifics; users cannot tell what was actually changed. + +**No deferral communication.** Changes the team decided not to prioritize go uncommunicated. Users keep wondering or assume the feedback was ignored. + +**Communication only on shipping.** Successes communicated; failures and deferrals never. Trust erodes when users notice the asymmetry. + +--- + +## Closing the loop and feedback volume + +Programs that close the loop well often see feedback volume increase over time. Users who saw their input matter contribute more. + +**The virtuous cycle.** + +- Feedback closes the loop. +- Users see their input matter. +- Engagement strengthens. +- Feedback volume and quality increase. +- The team has more signal to act on. + +**The vicious cycle.** + +- Feedback aggregation happens in silos. +- Closing the loop does not happen. +- Users feel ignored. +- Engagement decays. +- Feedback volume and quality decrease. +- The team has less signal. + +The discipline. Closing the loop is an investment in the future of the feedback program. + +--- + +## Methodology-level choices that stay in the public skill + +Why closing the loop matters. What gets communicated. Communication channels. Frequency and timing. The over-promising risk. Communication for declined or deferred feedback. Communication for high-volume feedback. Personal vs aggregate. Common failures. The virtuous and vicious cycle. + +## Implementation choices that stay internal + +Specific email templates for closing-the-loop communication. Specific automation that triggers communication. Specific in-product notification systems. The team's own conventions for personal vs aggregate. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md new file mode 100644 index 0000000..c16ce67 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md @@ -0,0 +1,193 @@ +# Common feedback aggregation failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most feedback aggregation failures share a single root, which is treating feedback aggregation as collection rather than as decision input. + +--- + +## Failure 1: Loudest customers steer the roadmap + +**Symptom.** A small number of vocal customers dominate roadmap discussions. Quieter customers' needs go unaddressed. The product evolves to serve the loudest, not the broadest. + +**Diagnosis.** Loudest-voice pattern. Volume from vocal users mistaken for broad signal. + +**Cure.** Apply channel-source weighting. Distinguish between distinct-user signal and per-user volume. Triangulate across channels to validate that loud signal represents broad pattern. + +**Prevention.** Synthesis names the source distribution explicitly. "This pattern came from 50 distinct users across 3 channels" is different from "this pattern came from 5 users with 200 tickets." + +--- + +## Failure 2: We have lots of feedback but no decisions + +**Symptom.** Feedback channels overflow. Tagging happens. Dashboards exist. Decisions get made on intuition rather than on the feedback signal. + +**Diagnosis.** Aggregation without synthesis. The triage cadence is missing or broken; feedback is collected without being turned into decision input. + +**Cure.** Establish the synthesis cadence (weekly, monthly, quarterly). Each cadence produces output the team uses for decisions. + +**Prevention.** Synthesis ownership explicit. Whoever owns synthesis is accountable for the loop's continuity. + +--- + +## Failure 3: Our channels overflow; we cannot keep up + +**Symptom.** Feedback volume exceeds the team's capacity to triage, tag, and synthesize. Old feedback never gets reviewed; new feedback piles up. + +**Diagnosis.** Capacity mismatch. Either tooling does not scale, or the team is under-staffed for the volume, or both. + +**Cure.** Scale tooling: AI-assisted tagging, aggregated channels, automated pattern surfacing. Or reduce capture: not every channel needs to be aggregated. + +**Prevention.** Match tooling and capacity to expected volume. Plan for growth; the volume that is comfortable today often is not in 6 months. + +--- + +## Failure 4: Different teams cite different feedback for the same decision + +**Symptom.** Engineering team cites one feedback pattern; product team cites another; sales team cites a third. The teams reach for whatever feedback supports their position. + +**Diagnosis.** Channel-source weighting absent. Each team uses the channel that is most accessible to them, regardless of decision relevance. + +**Cure.** Establish weighting per decision. The synthesis surfaces what the relevant channels say, weighted appropriately. Teams use the synthesis rather than going to channels independently. + +**Prevention.** Centralize synthesis ownership. The synthesis owner produces the canonical view; teams reference it rather than producing parallel interpretations. + +--- + +## Failure 5: Customer council meetings produce notes nobody references + +**Symptom.** Customer council convenes regularly. Notes are taken. Decks summarize. The notes get filed; no roadmap discussions reference them. + +**Diagnosis.** Council without synthesis loop. The meeting is the deliverable; the analytical follow-through is missing. + +**Cure.** Apply the synthesis loop to council inputs. Each council meeting produces specific actionable input that feeds product decisions. + +**Prevention.** Treat council inputs as part of the broader feedback aggregation, not as a separate stream that produces ceremonial outputs. + +--- + +## Failure 6: NPS is reported monthly but does not inform decisions + +**Symptom.** NPS scores get reported in monthly business reviews. The number is part of compliance reporting. It does not inform product decisions. + +**Diagnosis.** NPS as compliance metric. The number gets tracked; the underlying signal does not. + +**Cure.** Mine NPS comments for patterns. Segment NPS by user segment. Use NPS trends as drift signal. The number itself is less informative than the underlying signal. + +**Prevention.** NPS reporting includes the qualitative signal alongside the quantitative score. Decisions reference what NPS comments revealed, not just the score. + +--- + +## Failure 7: Feedback we shipped against did not move sentiment + +**Symptom.** Major feature shipped to address feedback. Post-launch sentiment did not improve. The team is confused. + +**Diagnosis.** Wrong feedback prioritized. The loud feedback was not the most consequential; the patterns the team addressed were not the patterns that drove sentiment. + +**Cure.** Re-examine the synthesis that motivated the work. Was the pattern strong across channels, or was it loud in one channel? Was the segment broad or narrow? Was the change the right response to the pattern? + +**Prevention.** Strong synthesis grounds prioritization in cross-channel patterns and frequency-intensity assessment. Single-channel signals get treated cautiously. + +--- + +## Failure 8: Users gave feedback once and never returned + +**Symptom.** Users submit feedback through channels. They never engage again. Repeat feedback rates are low. + +**Diagnosis.** Closed-loop missing. Users feel ignored after providing feedback. + +**Cure.** Establish closing-the-loop communication. Tell users when their feedback drove change. Personal communication for high-impact users; aggregate for broader changes. + +**Prevention.** Closing the loop is part of the feedback workflow, not an afterthought. Decisions to ship include closing-the-loop communication as a step. + +--- + +## Failure 9: We tagged everything but cannot find patterns + +**Symptom.** Tagging happens systematically. The team applies tags to most feedback items. But synthesis cannot identify clear patterns. + +**Diagnosis.** Taxonomy too granular, too coarse, or noisy. Periodic taxonomy review missing. + +**Cure.** Run a taxonomy review. Merge tags that fragment patterns; split tags that hide distinct issues; deprecate tags that no longer apply. + +**Prevention.** Quarterly or bi-annual taxonomy review. The taxonomy evolves with the program. + +--- + +## Failure 10: Drift in feedback caught us by surprise + +**Symptom.** A feedback category grew significantly over weeks or months. The team discovered the change only when it became a problem. + +**Diagnosis.** Drift detection missing. The team did not investigate trending patterns until they became urgent. + +**Cure.** Establish drift detection: trend dashboards, threshold alerts, periodic trend review. + +**Prevention.** Weekly quick scans for sharp drift. Monthly systematic review of category trends. Tooling that surfaces changes automatically. + +--- + +## Failure 11: Sales call data and support ticket data tell different stories + +**Symptom.** Sales suggests one priority; support suggests another. Both teams have data; the data conflicts. + +**Diagnosis.** Cross-channel synthesis missing. Each channel's signal stays in its own silo. + +**Cure.** Run cross-channel synthesis. Compare what sales calls reveal (prospect view) to what support tickets reveal (existing customer view). Often the conflict surfaces meaningful differences (different segments, different lifecycle stages); sometimes it surfaces inconsistency that warrants investigation. + +**Prevention.** Synthesis includes cross-channel triangulation. Conflicts get surfaced and resolved or acknowledged. + +--- + +## Failure 12: Feedback aggregation as compliance + +**Symptom.** Feedback collection happens because customers expect it or because leadership mandates it. The collection is performative; the synthesis is minimal. + +**Diagnosis.** Feedback aggregation treated as ceremony rather than as decision input. + +**Cure.** Tie feedback aggregation to specific decisions. The synthesis informs roadmap; decisions reference patterns. If the team cannot trace decisions to feedback, the program is compliance, not aggregation. + +**Prevention.** Feedback program goals are explicit and tied to decisions. The program's success is measured by whether decisions reference its synthesis, not by whether feedback was collected. + +--- + +## Failure 13: Synthesis that does not surface patterns + +**Symptom.** Monthly or quarterly synthesis happens. The output is descriptive but does not surface patterns or inform decisions. + +**Diagnosis.** Synthesis writing is documentation rather than analytical work. The patterns are not extracted; the implications are not drawn. + +**Cure.** Apply discovery-research-synthesis discipline to feedback synthesis. Patterns named with conviction; implications drawn; decisions informed. + +**Prevention.** Synthesis ownership includes analytical responsibility, not just documentation responsibility. + +--- + +## Failure 14: Tooling-led process + +**Symptom.** The team's process follows what the tooling supports. Capabilities the tooling does not support do not happen. + +**Diagnosis.** Tooling drives the process rather than the process driving tooling selection. + +**Cure.** Step back. Define what the team needs the feedback aggregation to produce. Evaluate tooling against those needs. + +**Prevention.** Tooling decisions are downstream of process design. The team designs the process, then selects or builds tooling that supports it. + +--- + +## The cross-cutting pattern + +Most feedback aggregation failures share a single root: treating feedback aggregation as collection rather than as decision input. + +Collection focuses on capturing feedback: channels integrated, items tagged, dashboards built, scores reported. Output: a record that feedback was collected. + +Decision input focuses on what the feedback informs: which decisions, what signal will inform them, what synthesis surfaces patterns the team needs. Output: decisions traceable to feedback patterns. + +The fix for almost any feedback aggregation failure starts with the same question: what specifically is this feedback program supposed to inform, and is the synthesis loop producing that input? When the answer is clear, the program becomes load-bearing. When the answer is "we should be aggregating feedback," the program becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting collection-vs-decision-input pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md new file mode 100644 index 0000000..cff4b6c --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md @@ -0,0 +1,236 @@ +# Detecting drift in feedback + +Drift patterns. Investigation discipline. Drift as early signal of change. + +Feedback signal changes over time. Volume in a category increases or decreases; new patterns emerge; old patterns disappear; sentiment shifts. The team that detects drift early often catches issues before they compound; the team that does not detect drift often discovers problems after they are large. + +--- + +## The drift patterns + +Common ways feedback signal changes over time. + +### Increasing volume in a category + +**Signal.** Feedback volume in a specific area is rising over weeks or months. + +**Possible causes.** + +- The issue is worsening. +- The user base is growing (more total volume across all categories). +- Awareness of the channel is increasing (more users finding the feedback channel). +- Recent product changes introduced or amplified an issue. + +**The investigation.** Look at the cause: + +- Is the percentage of total feedback in this category increasing? (If yes, this category is growing relative to others; the issue is real, not just user-base growth.) +- Did recent product changes affect this area? (Often the cause when volume increases sharply.) +- Are users describing similar issues in different ways? (Could be one underlying issue surfacing through multiple feedback styles.) + +### Decreasing volume in a category + +**Signal.** Feedback volume in a specific area is declining over weeks or months. + +**Possible causes.** + +- The issue was resolved. +- Users gave up reporting (resignation rather than satisfaction). +- The user base shifted (fewer users in the affected segment). +- Channel access changed (users stopped using the feedback channel for this category). + +**The investigation.** Decreasing volume can be good or bad: + +- If a fix shipped and volume dropped: fix worked. +- If no fix shipped but volume dropped: investigate. Are users churning? Are they working around the issue silently? + +### New patterns emerging + +**Signal.** Feedback that was rare or non-existent starts appearing more frequently. + +**Possible causes.** + +- Recent product changes introduced new patterns. +- Market conditions changed (new competitors, new user expectations). +- User base expansion brought new use cases. +- Existing users developed new workflows. + +**The investigation.** Investigate the cause; new patterns often inform roadmap decisions. + +### Patterns disappearing + +**Signal.** Feedback patterns that used to be common stop appearing. + +**Possible causes.** + +- Product changes addressed the issue. +- Users migrated away from the affected workflows. +- The user base shifted. + +**The investigation.** Validate that the disappearance reflects resolution, not silent abandonment. + +### Sentiment shifts + +**Signal.** Aggregate sentiment (NPS, CSAT, in-app rating) trends differently than before. + +**Possible causes.** + +- Specific changes affected sentiment. +- External factors (market conditions, competitor actions, news cycles). +- User base composition changed. +- Cumulative experience changes that the team did not flag individually. + +**The investigation.** Sentiment shifts warrant root-cause analysis; both improvements and degradations are informative. + +--- + +## The drift detection cadence + +When the team checks for drift. + +**Weekly:** quick scans for sharp drift in critical categories. Sharp increases in support volume on specific issues, sudden NPS drops, viral social mentions. + +**Monthly:** systematic review of category-level trends. Compare the past month to prior months. Identify categories with significant increases or decreases. + +**Quarterly:** strategic drift review. Long-term trends, sentiment shifts, emerging patterns. Pairs with quarterly strategic synthesis. + +**Annually:** taxonomy and aggregate drift. Are tag categories still appropriate? Has the user base composition changed? Long-term sentiment trends. + +--- + +## Tooling for drift detection + +What infrastructure helps catch drift. + +**Trend dashboards.** Time-series views of feedback volume per category. Visual surfacing of changes. + +**Threshold alerts.** Automated alerts when a category's volume changes significantly (e.g., 50%+ increase week-over-week). + +**Sentiment tracking.** NPS or CSAT trends over time, segmented by user segment and product area. + +**Cross-channel views.** Aggregate trends across channels surface patterns that single-channel views miss. + +**Period comparisons.** Compare current period to prior periods (this month vs last month, this quarter vs same quarter last year). + +The tooling supports detection; humans interpret. + +--- + +## Investigation discipline + +When drift is detected, what to investigate. + +**The questions.** + +- What changed in the product or in the user base that could explain the drift? +- Is the drift persistent or a temporary spike? +- Is the drift segment-specific or universal? +- Is the drift correlated with other signals (churn, engagement, support volume)? +- What is the underlying cause vs the surface signal? + +**The investigation methodology.** + +- Pull a sample of feedback from the drifting category. +- Compare it to feedback in the same category from before the drift started. +- Identify what changed: language, contexts, severity, user segments. +- Map to product changes or external events that could explain. +- Form a hypothesis; test it through additional investigation. + +--- + +## Drift as early signal + +Drift often signals issues before they become large. + +**The leading-indicator pattern.** + +- A category's volume starts increasing. +- The team investigates and identifies the cause. +- The cause is addressed before it affects more users. + +Without drift detection, the same issue might compound for months before the team notices. + +**Worked example.** + +- Support tickets in the "configuration step 3" category increase 30% in two weeks. +- Investigation reveals: a recent change to the configuration form introduced a confusing default. +- The change is reverted or fixed within a week. +- Without drift detection, the issue might have continued for months, affecting many more users. + +--- + +## Drift in segments + +Drift can be segment-specific. + +**The pattern.** Aggregate metrics look stable; segment-specific metrics show drift. + +**Worked example.** Aggregate NPS is stable. Enterprise NPS is dropping; small-team NPS is improving. The aggregate hides the segment-specific drift. + +**The investigation.** Segment-level views surface patterns the aggregate hides. Enterprise drift may indicate a specific issue with enterprise features or experience that aggregate metrics miss. + +The discipline. Drift detection should include segment views, not just aggregate views. + +--- + +## Drift in cross-channel patterns + +Sometimes drift appears across channels even when individual channels look stable. + +**The pattern.** Each channel shows mild changes; the cross-channel aggregate shows a stronger pattern. + +**Worked example.** Support tickets in onboarding category up 15%. NPS comments mentioning onboarding up 10%. In-app feedback in onboarding up 20%. No single channel signals an emergency; the cross-channel aggregate suggests a real issue. + +**The investigation.** Cross-channel drift detection requires unified views or manual cross-channel review. + +--- + +## False-positive drift + +Not every change is real drift. + +**Common false positives.** + +- Seasonal patterns: support volume drops over holidays; NPS dips during certain campaigns. +- One-off events: a viral social mention spikes social signal but does not represent persistent change. +- Product launches: short-term volume spikes around new features, then normalize. +- Channel changes: a new feedback channel launches; volume in that channel grows from zero, not because the underlying issue grew. + +**The investigation discipline.** Before declaring drift, validate that the change is persistent and not explained by known factors. + +--- + +## Drift acknowledgment in synthesis + +Drift signals get surfaced in monthly and quarterly synthesis. + +**The pattern.** Synthesis documents include a drift section: what is changing, what may explain it, what action (if any) is recommended. + +**The honest framing.** Some drift gets acknowledged but not actioned (low-priority categories, edge cases). Some drift drives investigation. Some drift drives roadmap decisions. The synthesis names the disposition for each drift signal. + +--- + +## Common drift detection failures + +**No detection.** Aggregate volume is the only metric tracked; trends invisible. + +**Aggregate only.** Segment-specific drift hidden by aggregate stability. + +**Single-channel only.** Cross-channel patterns missed. + +**Late detection.** Drift caught after it has compounded for months. + +**False positives treated as real drift.** Seasonal patterns or one-off events trigger investigation that wastes time. + +**Real drift treated as false positive.** The team dismisses signals as noise; underlying issues compound. + +**Investigation without follow-through.** Drift detected; team investigates; finds cause; does not act. The detection was performative. + +--- + +## Methodology-level choices that stay in the public skill + +The drift patterns (increasing/decreasing volume, new/disappearing patterns, sentiment shifts). The drift detection cadence. Tooling for drift detection. Investigation discipline. Drift as early signal. Drift in segments. Drift in cross-channel patterns. False-positive drift. Drift acknowledgment in synthesis. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for drift detection. Specific threshold settings for alerts. Specific seasonality models. Specific segment-view configurations. The team's own conventions for drift acknowledgment in synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md new file mode 100644 index 0000000..3f96062 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md @@ -0,0 +1,231 @@ +# Frequency vs intensity + +The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. + +Feedback signal varies along two dimensions: how often the same feedback recurs (frequency) and how strongly users feel about it (intensity). The combination produces a matrix that informs prioritization. + +--- + +## The two dimensions + +**Frequency.** How often the same feedback recurs across users. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +**Intensity.** How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive ("I cannot use the product because of this"), or describe satisfaction as transformative ("This feature changed how my team works"). +- Low-intensity feedback: minor friction ("Slightly annoying") or mild satisfaction ("It's fine"). + +The two dimensions are independent. High frequency does not imply high intensity; high intensity does not imply high frequency. + +--- + +## The four-quadrant matrix + +### Quadrant 1: High frequency, high intensity + +**Top priority.** Many users hit this; it matters to them. + +**Examples.** + +- A bug that affects core flow for many users. +- A friction point users describe as "I almost canceled because of this." +- A feature gap that users repeatedly cite as a competitive disadvantage. + +**The disposition.** Address quickly. The combination of broad impact and high stakes warrants priority investment. + +### Quadrant 2: High frequency, low intensity + +**Papercuts.** Many users hit this but it is minor. + +**Examples.** + +- A confusing button label that users figure out within seconds. +- A slight delay in a flow that users tolerate. +- A small visual inconsistency. + +**The disposition.** Address in batches. Individual papercuts are minor; cumulatively they erode experience. Periodic "papercut sprints" address many at once. + +**The risk of ignoring papercuts.** Papercuts compound. Users who tolerate one papercut leave when they accumulate. The cumulative experience is worse than the sum of individual papercuts. + +### Quadrant 3: Low frequency, high intensity + +**Affected users deeply impacted but few.** Often segment-specific. + +**Examples.** + +- A bug that affects users in a specific configuration that 5% of customers use, but for those users it is blocking. +- A feature gap that prevents enterprise customers from passing compliance review. +- An accessibility issue that excludes a specific user group entirely. + +**The disposition.** Depends on segment importance and reversibility. + +- If the affected segment is strategically important: high priority. +- If the affected segment is marginal: lower priority but documented. +- If the issue is a complete blocker for the affected users (cannot use the product at all): often warrants urgency regardless of segment size. + +### Quadrant 4: Low frequency, low intensity + +**Noise.** Capture; do not action individually. + +**Examples.** + +- One-off observations from users with unusual contexts. +- Minor preferences that one user mentions. +- Edge cases nobody else encounters. + +**The disposition.** Note in the system. Do not invest action on individual items. Aggregate sometimes reveals patterns; the noise can become signal if patterns emerge. + +--- + +## Frequency assessment + +How to assess frequency. + +**Quantitative signals.** + +- Number of distinct users reporting the same issue across channels. +- Volume of feedback items in the relevant tag or category. +- Trend over time: is the frequency increasing or stable? + +**Cautions.** + +- Volume can reflect channel bias rather than actual frequency. A loud single user generating 50 tickets is not high-frequency feedback (50x). +- Channel coverage matters. If a feedback channel only reaches a subset of users, frequency in that channel does not reflect frequency across all users. + +**The cross-channel triangulation.** Issues that show up across multiple channels are higher-frequency than issues that appear in one channel only. + +--- + +## Intensity assessment + +How to assess intensity. + +**Verbal signals.** + +- Strong language: "I cannot use this," "This is unacceptable," "I love this," "This changed my workflow." +- Specific impact descriptions: "I lost 3 hours," "This made my quarterly review possible," "I missed a deadline." +- Workaround intensity: heavy workarounds suggest high-intensity friction; light workarounds suggest low-intensity. + +**Behavioral signals.** + +- Churn correlation: users with feedback in a category churn at higher rates. +- Engagement correlation: users with positive feedback in a category engage more. +- Escalation patterns: users escalating to higher support tiers or to executive contacts signal high intensity. + +**Cautions.** + +- Some users naturally use stronger language than others. +- Cultural differences affect verbal intensity. +- Triangulate verbal and behavioral signals. + +--- + +## The matrix in practice + +Worked example: a feedback aggregation review for a product team's quarterly planning. + +**Top-of-list items (high frequency, high intensity).** + +- Onboarding configuration step 3 abandonment (broad signal across support, NPS comments, in-app feedback; users describe it as "I almost gave up"). +- Mobile app stability issues (frequent mobile crashes; users describe them as blocking). +- Enterprise admin role limitations (consistent across enterprise sales calls and support tickets; described as compliance blockers). + +**Papercut batch (high frequency, low intensity).** + +- Inconsistent button labeling across the product. +- Slow page transitions in the dashboard. +- Filter resets when navigating between views. +- Date format inconsistencies. + +**Strategic-decision items (low frequency, high intensity).** + +- Specific accessibility issues affecting screen reader users. +- Compliance gaps for healthcare-segment customers (small segment but blocking for them). +- Bug affecting users in specific timezone configurations (5% of users, but blocking). + +**Noise-watch (low frequency, low intensity).** + +- Various individual feature requests with no aggregate pattern. +- Cosmetic preferences mentioned by single users. + +The team's quarterly planning weights the four quadrants differently: + +- Top-of-list: included in the next quarter's roadmap. +- Papercut batch: scheduled for a dedicated sprint. +- Strategic decisions: discussed at strategy review for prioritization. +- Noise-watch: captured but not actioned. + +--- + +## When the matrix is misapplied + +Common matrix misuses. + +**Volume as proxy for frequency.** Loudest-voice users generate volume that does not reflect distinct-user frequency. + +**Intensity assessed only verbally.** Some users complain loudly about minor issues; some users underreport severe ones. Triangulate verbal and behavioral signals. + +**Quadrant 4 dismissed too quickly.** Some apparent noise is early-signal of patterns that will grow. Periodic review of low-frequency items catches emerging patterns. + +**Quadrant 3 generalized to quadrant 1.** Strategic-segment issues weighted as if they affected all users. Or marginal-segment issues weighted as if they were strategic. + +**Frequency-only or intensity-only prioritization.** Looking at one dimension misses the matrix. + +--- + +## Frequency over time + +Frequency dimensions can shift over time. + +**Increasing frequency.** Issue is worsening, user base is growing, or reporting awareness is increasing. Investigate the cause. + +**Decreasing frequency.** Issue is resolving, users are giving up reporting, or the user base shifted. The decreasing frequency may not mean problem solved. + +**Stable frequency.** Issue is recurring at consistent rate. May indicate steady-state or chronic issue. + +The drift detection (see `detecting-drift-in-feedback.md`) covers temporal changes in feedback signal. + +--- + +## Intensity at scale + +Intensity assessments at high feedback volume. + +**The challenge.** Reading every piece of feedback to assess intensity is impractical at high volume. + +**The approach.** + +- Sample-based intensity assessment. Read a sample; characterize the intensity distribution. +- Behavioral signal as proxy. Churn rates, escalation patterns, support-tier escalations. +- AI-assisted intensity classification. AI flags high-intensity feedback for human review. + +**The discipline.** Even at high volume, the team should be able to identify high-intensity feedback and weight it appropriately. + +--- + +## Common frequency-intensity failures + +**Loudest-voice as high-frequency.** A few loud users generate volume; the team mistakes volume for frequency. + +**Intensity ignored.** Volume drives prioritization; intensity is not assessed; quadrant 1 and quadrant 2 get treated similarly. + +**Frequency ignored.** A single emotional submission gets prioritized as if it were broad-pattern signal. + +**Papercuts ignored as "low priority."** Cumulative papercut impact erodes experience; treating each papercut as too minor to address misses the cumulative effect. + +**Strategic-segment issues underweighted.** Quadrant 3 treated as quadrant 4 because the affected segment is small. + +**Noise treated as signal.** Quadrant 4 items that are genuinely one-off get actioned as if they were broad patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The two dimensions (frequency and intensity). The four-quadrant matrix with worked dispositions. Frequency assessment. Intensity assessment. The matrix in practice. When the matrix is misapplied. Frequency over time. Intensity at scale. Common failures. + +## Implementation choices that stay internal + +Specific tooling for frequency tracking. Specific intensity classification (manual or AI-assisted). Specific dashboard views by quadrant. The team's own conventions for matrix application in prioritization. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md new file mode 100644 index 0000000..3f911df --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md @@ -0,0 +1,225 @@ +# From feedback to product decision + +The synthesis loop. Cadences. The discipline of decisions traceable to feedback. + +Feedback aggregation produces value when it informs decisions. Without the synthesis loop that turns aggregated feedback into decision input, the program produces volume without action. + +--- + +## The synthesis loop + +The cycle that turns continuous feedback into continuous decisions. + +**The stages.** + +1. Feedback arrives across channels. +2. Triage categorizes and weights. +3. Periodic synthesis surfaces patterns. +4. Patterns inform roadmap discussions, spec drafts, prioritization debates. +5. Decisions reference specific feedback patterns as input. +6. Decisions ship; the loop continues with new feedback informed by the changes. + +**The discipline.** The loop is continuous. Feedback aggregation is not a one-time research project; it is a steady-state discipline. + +--- + +## The cadences + +Feedback synthesis benefits from multiple cadences operating in parallel. + +**Daily: critical issues.** + +- Critical feedback (security incidents, data loss, broken core flows) handled immediately. +- The triage system surfaces critical items for immediate attention. +- Response within hours to a day. + +**Weekly: pattern review.** + +- Team review of recent feedback patterns. +- Categorization, tagging, and pattern identification. +- Adjusts current-quarter execution where patterns suggest changes. +- 1-2 hours per week typical. + +**Monthly: synthesis review.** + +- Surfaces trending patterns over the past month. +- Identifies what to escalate to roadmap discussions. +- Compares current month patterns to prior months (drift detection). +- 2-4 hours per month. + +**Quarterly: strategic synthesis.** + +- Patterns over the quarter inform strategic planning and next-quarter roadmap. +- Customer council inputs and other longer-cadence channels integrated. +- Pairs with the team's broader strategic planning. +- A multi-day effort within the quarter's planning cycle. + +The cadences compose. Critical issues do not wait for weekly review; weekly review captures patterns that monthly review aggregates; monthly synthesis informs quarterly strategic decisions. + +--- + +## The synthesis output + +What each cadence produces. + +**Daily/critical:** specific incidents handled, no formal output beyond the response. + +**Weekly:** internal team notes on emerging patterns. May include a short summary email or dashboard update. + +**Monthly:** a synthesis document covering the month's patterns. Surfaces what is emerging, what is stable, what has resolved. Roadmap discussions reference this document. + +**Quarterly:** a strategic synthesis document. Trends over the quarter, recommendations for next quarter, strategic implications. Senior product leadership reviews this. + +The output gets richer at longer cadences. Daily and weekly are tactical; monthly and quarterly are strategic. + +--- + +## Decisions traceable to feedback + +The discipline that distinguishes triaged-synthesis from feedback ceremony. + +**The pattern.** Each major product decision can be traced to specific feedback patterns. The team can articulate: "We decided to prioritize X because feedback showed Y pattern across Z channels." + +**The anti-pattern.** Decisions get made on intuition or politics. Feedback aggregation happens in parallel but does not inform the decisions. The team uses general impressions ("we hear a lot about this from customers") rather than specific patterns. + +**The discipline.** + +- Roadmap items reference the feedback patterns that motivated them. +- Prioritization debates reference specific signal weight. +- Spec drafts include feedback context for the design decisions. +- Stakeholder communication explains decisions in terms of feedback patterns. + +**The audit.** For recent decisions, can the team trace each to specific feedback signals? If yes, the program is informing decisions. If the answer is "we generally know what customers want," the program is feedback theater. + +--- + +## Roadmap input from feedback + +How feedback aggregation informs roadmap planning. + +**The roadmap inputs.** + +- High-frequency-high-intensity patterns (quadrant 1 from the frequency-intensity matrix). +- Strategic-segment patterns (quadrant 3 from segments that matter for strategy). +- Cross-channel patterns that have validated across multiple sources. +- Drift signals that suggest emerging issues. + +**The roadmap-output mapping.** Roadmap candidates get characterized by which feedback patterns they address. + +- Candidate: "Onboarding redesign." Feedback motivation: configuration step 3 abandonment pattern across support, NPS, in-app feedback. +- Candidate: "Enterprise admin overhaul." Feedback motivation: enterprise sales-call objections + enterprise customer support patterns. + +The mapping makes the roadmap defensible: each item has a feedback-grounded reason. + +**The "no feedback signal, no priority" discipline.** Candidates that lack feedback grounding may still be valuable but should be defensible on other grounds (technical foundation, strategic bet). Candidates without any defensible grounding should be deprioritized. + +Pair with `roadmap-planning` for the broader prioritization discipline. + +--- + +## Spec input from feedback + +How feedback aggregation informs spec writing. + +**The pattern.** Specs reference feedback context for design decisions. + +**Worked example.** A spec for an onboarding redesign: + +- Background: feedback shows 40% of new signups abandon at configuration step 3. Cross-channel pattern (support tickets, in-app feedback, NPS comments). +- User stories: grounded in the specific feedback patterns. "As a new signup, I want to defer credit-card configuration until after I have seen the value, so I do not need my card on hand at signup." +- Design decisions: tied to the feedback. "Step 3 deferral chosen because feedback specifically cites credit-card-not-on-hand as the abandonment cause; alternative approaches that do not address this would not move the metric." + +The spec is grounded in feedback rather than in intuition. + +Pair with `pm-spec-writing` for the broader spec discipline. + +--- + +## Stakeholder communication from feedback + +How feedback aggregation informs stakeholder discussions. + +**The pattern.** Decisions presented to stakeholders are explained in terms of feedback patterns. + +**Strong stakeholder communication.** + +- "We are prioritizing the onboarding redesign because feedback across support, NPS, and in-app surveys consistently shows 40%+ abandonment at configuration step 3, with users citing credit-card friction as the cause." +- "We are deferring the dashboard expansion because feedback signal is mixed: enterprise customers want it; small-team customers do not need it; the strategic priority for this quarter is small-team activation." + +**Weak stakeholder communication.** + +- "We have heard a lot of feedback about onboarding." +- "Customers want this feature." + +The strong version is defensible; readers can engage substantively. The weak version is hand-waving. + +--- + +## Closing the synthesis loop + +After decisions ship, feedback responds. + +**The post-decision feedback.** + +- Did the change reduce the feedback patterns that motivated it? +- Did new patterns emerge as a result? +- Did the change introduce new friction in adjacent areas? + +**The discipline.** Track post-decision feedback to validate that the decision worked. Decisions that ship without post-decision feedback tracking lose the loop's learning value. + +--- + +## Cadence drift + +When the synthesis cadence breaks down. + +**Common drift patterns.** + +- Critical issues handled but no weekly pattern review. Tactical signal lost. +- Weekly review happens but does not aggregate to monthly synthesis. Patterns over time invisible. +- Monthly synthesis happens but does not inform quarterly planning. Strategic input missing. +- Quarterly strategic synthesis happens but the team does not act on it. Synthesis ceremony. + +**The signal.** When decisions stop being traceable to feedback, the cadence has drifted. The fix is restoring the cadence rather than blaming the team. + +--- + +## Synthesis ownership + +Who owns the synthesis loop. + +**Common ownership patterns.** + +- A dedicated feedback program owner (often a senior PM, product ops, or customer-success-product liaison). +- The product team's PM rotates through synthesis duties. +- A customer feedback team that synthesizes and feeds product teams. + +**The discipline.** Whoever owns synthesis is accountable for the loop's continuity. Without explicit ownership, synthesis falls to whoever has time, which often means it does not happen. + +--- + +## Common decision-loop failures + +**Synthesis without decisions.** Patterns surfaced; team does not use them. Documentation theater. + +**Decisions without synthesis grounding.** Team makes decisions on intuition; feedback aggregation happens in parallel but does not inform. + +**Cadence breakdown.** Daily critical handled; weekly and monthly synthesis fall behind. Loop loses continuity. + +**No post-decision tracking.** Decisions ship; feedback response not tracked; learning lost. + +**Synthesis ownership missing.** No clear owner; synthesis falls between roles. + +**Synthesis output not actionable.** Documents produced but framed in ways that do not inform decisions. Dense, generic, or unfocused. + +**Stakeholder communication still hand-waving.** Synthesis happens internally but stakeholder communication does not reference the patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The synthesis loop. The cadences (daily, weekly, monthly, quarterly). The synthesis output per cadence. Decisions traceable to feedback. Roadmap input. Spec input. Stakeholder communication. Closing the loop after decisions ship. Cadence drift. Synthesis ownership. Common failures. + +## Implementation choices that stay internal + +Specific tooling for synthesis production. Specific document templates per cadence. Specific reviewer workflows. Specific dashboard configurations. The team's own conventions for owning synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md new file mode 100644 index 0000000..5669fc4 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md @@ -0,0 +1,247 @@ +# Tooling considerations + +Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. + +Feedback aggregation tooling shapes what the program can do. The right tooling supports multi-channel aggregation, tagging at scale, pattern surfacing, and integration with adjacent systems. The wrong tooling produces silos, manual labor, and synthesis bottlenecks. + +This skill is platform-agnostic; specific products are not endorsed. The categories below describe what kinds of tooling exist; the team's actual product choices depend on stack, budget, and program shape. + +--- + +## Tooling categories + +Several categories of tooling support feedback aggregation. + +### Customer feedback platforms + +**What they do.** Aggregate feedback from multiple sources. Support tagging and categorization. Surface patterns through dashboards and analytics. + +**Strengths.** + +- Multi-channel support (often integrate with support, NPS, in-app, and other sources). +- Built-in tagging and pattern detection. +- Often include AI-assisted categorization. + +**Weaknesses.** + +- Pre-built taxonomies may not fit team-specific needs. +- Vendor-locked: switching costs grow over time. +- Coverage varies by vendor; some channels may not integrate. + +### Support ticket systems with analytics + +**What they do.** Track support tickets with tagging, routing, and reporting. Often the primary support channel. + +**Strengths.** + +- Native to support workflows. +- Strong tagging and routing for support-specific work. +- Analytics on support-team metrics. + +**Weaknesses.** + +- Often single-channel (support only). +- Cross-channel synthesis requires additional tooling or custom integration. + +### NPS or survey platforms + +**What they do.** Distribute surveys, collect responses, track sentiment trends. + +**Strengths.** + +- Specialized for survey distribution and response collection. +- Built-in NPS or CSAT methodology. +- Trend tracking over time. + +**Weaknesses.** + +- Single-modality (surveys only). +- Limited integration with other feedback sources. + +### Customer relationship management (CRM) systems + +**What they do.** Manage customer relationships, contact history, deal pipelines, customer feedback fields. + +**Strengths.** + +- Rich customer context (segment, deal stage, account history). +- Integration with sales workflows. + +**Weaknesses.** + +- Feedback aggregation is often a side feature, not a core function. +- Cross-channel feedback synthesis requires additional configuration. + +### Custom dashboards combining feedback signal with usage analytics + +**What they do.** Custom-built views combining feedback data with product analytics. + +**Strengths.** + +- Tailored to the team's specific needs. +- Cross-channel synthesis built-in to the design. +- Combines feedback patterns with behavioral signals. + +**Weaknesses.** + +- Build cost and ongoing maintenance. +- Skill requirements: data engineering or analytics expertise. + +--- + +## The criteria for tooling selection + +What to evaluate when choosing tooling. + +**Multi-channel aggregation.** Does it integrate with the channels the team uses? Or does it cover one channel only? + +**Tagging at scale.** Does it support the tagging volume the program needs? Manual tagging at low volume; AI-assisted at high volume. + +**Pattern surfacing.** Does it surface patterns, or is it just storage? Some tools store feedback without making it analyzable. + +**Integration with other systems.** Does it connect to roadmap tools, ticketing systems, communication channels? Isolated tools produce silos. + +**Scaling.** Does it scale with program volume? Tools that work at 100 items/week may break at 1000 items/week. + +**Cost.** License or build cost vs the value produced. Expensive tooling that fits is sometimes worth it; cheaper tooling that does not fit is often more expensive in practice. + +**Team skill match.** Does the team have skills to use the tool effectively? Sophisticated tools that the team cannot operate produce value that does not get realized. + +--- + +## The build-vs-buy tension + +Most programs end up with a mix. + +**The reasons to buy.** + +- Faster setup. Off-the-shelf tools work immediately. +- Specialized expertise. Vendors have built tooling for many programs. +- Standard features that the team would not build themselves. + +**The reasons to build.** + +- Cross-channel synthesis often requires custom work that off-the-shelf tools do not support. +- Team-specific tagging schemas and dashboards. +- Integration with the team's specific stack. + +**The hybrid pattern.** + +- Off-the-shelf tools for primary channels (support ticketing, NPS surveys). +- Custom dashboards for cross-channel synthesis. +- Custom integration to bring data together. + +The hybrid is more common than pure build-or-pure-buy in practice. + +--- + +## Volume considerations + +Different volume tiers warrant different tooling approaches. + +**Low volume (under 100 items/week).** + +- Manual tagging is feasible. +- Off-the-shelf tools usually sufficient. +- Custom build often overkill. + +**Mid volume (100-1000 items/week).** + +- AI-assisted tagging often worth the investment. +- Multi-channel aggregation tools earn their keep. +- Custom dashboards often add value. + +**High volume (1000+ items/week).** + +- Heavy AI-assisted or automated tagging. +- Custom infrastructure for cross-channel synthesis. +- Team capacity becomes the bottleneck; tooling must reduce manual work substantially. + +**Very high volume (10,000+ items/week).** + +- Often requires custom data engineering. +- Sampling and aggregation strategies replace per-item review. +- Tooling investment is substantial. + +--- + +## Integration considerations + +Feedback aggregation rarely lives alone. + +**Common integrations.** + +- **Roadmap tools.** Feedback patterns feed roadmap candidates. Tools that integrate (or are linked through workflows) reduce manual transfer. +- **Spec writing.** Feedback context for spec drafts. +- **Communication channels.** Slack or email for surfacing patterns to the team. +- **Customer success systems.** Closing the loop with users; account-level feedback views. +- **Product analytics.** Cross-reference feedback with usage patterns. + +**The integration discipline.** Tooling that integrates produces value compound across the systems. Isolated tooling produces silos that the team must manually bridge. + +--- + +## AI-assisted feedback work + +AI plays an increasing role in feedback aggregation. + +**Common AI uses.** + +- Automatic categorization and tagging. +- Sentiment classification. +- Pattern surfacing across feedback items. +- Summary generation for synthesis documents. +- Anomaly detection for drift identification. + +**The discipline.** + +- AI suggestions get human review at pattern-level. +- Critical decisions remain human-driven; AI accelerates the work. +- AI's biases (overfitting to training data, surface-level patterns) get checked through human pattern review. + +**The honest framing.** AI does not replace human synthesis; it supports it. Programs that automate synthesis entirely produce volume without judgment; programs that integrate AI with human review produce signal at scale. + +See `ai-content-collaboration` for the broader workflow discipline that applies to AI-assisted feedback work. + +--- + +## Privacy and data considerations + +Feedback often contains user information. + +**Considerations.** + +- User consent for feedback use beyond the immediate channel. +- Anonymization where appropriate (especially for sensitive feedback). +- Data retention policies. +- Compliance with regulations (GDPR, CCPA, industry-specific). + +**The discipline.** Tooling choices include data handling considerations. Vendors with poor data practices can create compliance issues regardless of tool capability. + +--- + +## Common tooling failures + +**Single-channel reliance.** Tooling supports only one channel; cross-channel synthesis impossible without additional work. + +**Overly generic tools.** Pre-built taxonomies and dashboards do not match team needs. + +**Custom build that consumes capacity.** Building feedback infrastructure absorbs PM and engineering capacity that should produce product. + +**Volume mismatch.** Tools that fit current volume break when the program scales. + +**Integration neglected.** Feedback tooling isolated from roadmap, spec, customer success systems. + +**AI without review.** Automated categorization without human pattern review produces patterns the team cannot trust. + +**Tooling-led process.** The tool drives the process rather than the process driving tool selection. The team adopts a tool's workflow rather than designing for their needs. + +--- + +## Methodology-level choices that stay in the public skill + +The tooling categories. The criteria for selection. The build-vs-buy tension. Volume considerations. Integration considerations. AI-assisted feedback work. Privacy and data considerations. Common failures. + +## Implementation choices that stay internal + +Specific tooling vendor selections. Specific integration configurations. Specific dashboard designs. Specific data pipelines. The team's own conventions for tool evaluation. These vary by team, stack, and program shape. diff --git a/dist/pi/.agents/skills/ux-research/SKILL.md b/dist/pi/.agents/skills/ux-research/SKILL.md new file mode 100644 index 0000000..2de3cb2 --- /dev/null +++ b/dist/pi/.agents/skills/ux-research/SKILL.md @@ -0,0 +1,252 @@ +--- +name: ux-research +description: "Plan and execute user research including research planning, recruiting, interview design, qualitative synthesis, and translating findings into product decisions. Use this skill whenever the user wants to plan user research, design interviews, recruit participants, conduct discovery, run formative research, or synthesize qualitative findings. Triggers on user research, UX research, user interviews, discovery research, generative research, formative research, qualitative research, user insights, research synthesis, recruitment, interview guide, jobs to be done. Also triggers when product decisions are being made without user input and the user wants to fix that." +category: research +catalog_summary: "Research planning, user interviews, qualitative synthesis" +display_order: 1 +--- + +# UX Research + +Plan and execute user research that produces decisions, not just decks. Stack-agnostic. Tool-agnostic. + +This skill is for generative and discovery research. For testing existing designs, use `usability-testing`. For mapping the full customer experience, use `journey-mapping`. + +--- + +## When to use + +- Starting a new product or major feature without sufficient user understanding +- Diagnosing why something isn't working without clear data signals +- Generating new opportunity hypotheses +- Validating a strategic direction before significant investment +- Building empathy across a team that's drifted from users +- Translating "we should talk to users" intent into a real plan + +## When NOT to use + +- Testing a specific design or prototype (use `usability-testing`) +- Mapping the full journey of an existing experience (use `journey-mapping`) +- Quantitative measurement (use `analytics-strategy`) +- Conversion testing (use `cro-optimization`) + +--- + +## Required inputs + +- The research question(s) - what you need to answer +- Stakeholder buy-in (who needs the findings, what decisions hinge on them) +- Access to users (current customers, prospects, lapsed users, target segments) +- Timeline and budget +- Any prior research to build on + +--- + +## The framework: 6 phases + +### 1. Frame the question + +Bad questions produce bad research. Spend disproportionate time on framing. + +**Good research questions:** +- Specific (not "How do users feel about our product?") +- Open-ended (not "Do users like feature X?") +- Decision-relevant (the answer changes what gets built) +- Researchable (can be answered through user contact, not just analysis) + +**Examples:** + +| Weak question | Better question | +|---|---| +| "Do users like our onboarding?" | "Where in onboarding do new users feel uncertain about whether to continue?" | +| "What features should we build?" | "What unmet needs do current users have when [specific job]?" | +| "Why is conversion low?" | "What's the user mental model when they reach the pricing page, and where does it diverge from our intent?" | + +### 2. Choose the method + +The method follows the question. + +**Generative methods (what's true?):** + +- **In-depth interviews.** 60 minutes, 5 to 15 participants. Best for understanding context, motivation, mental models. +- **Contextual inquiry.** Observe users in their environment doing their work. Best for workflow understanding. +- **Diary studies.** Participants log their experience over days/weeks. Best for behaviors that don't manifest in a single session. +- **Field research.** Spend time where users live/work. Best for cultural and contextual understanding. +- **Surveys (qualitative-heavy).** When you need broad signal with open-ended responses. + +**Validation methods (is this hypothesis right?):** + +- **Concept testing.** Show a description, mockup, or prototype. Get reactions. +- **Card sorts.** Validate information architecture. +- **Tree tests.** Validate findability without visual design influence. + +(For testing usability of working designs, see `usability-testing`.) + +### 3. Recruit + +The recruit makes or breaks the research. + +**Recruit criteria:** + +- Match the audience the research targets (not "anyone willing") +- Mix of behaviors (active users, lapsed users, never-users) +- Mix of demographics where relevant +- Excludes friends, family, employees (biased) +- Excludes professional research participants if possible (different population) + +**Recruit channels:** + +- In-product recruiting (intercept current users) +- Email outreach to user segments +- Recruiting platforms (UserInterviews, Respondent, etc.) +- Customer support team referrals +- Field intercept for in-person + +**Incentive:** Pay participants. Standard rates: $50 to $150 for 60 minutes, more for executives or specialized professions. + +**Recruit volume:** Plan for 20 to 30 percent no-show. Recruit 7 to schedule 5. + +### 4. Conduct + +The interview or session itself. + +**Pre-interview:** + +- Send confirmation 24 hours and 1 hour before +- Test recording setup (audio quality is non-negotiable) +- Prepare interview guide (see template) +- Have a notetaker if possible (frees the interviewer to focus) + +**During the interview:** + +- Record video and audio (with consent) +- Open with rapport-building, not the research questions +- Use open-ended questions ("Tell me about the last time...") +- Use silence (let participants fill it; don't rush to the next question) +- Ask "why" but not too many times in a row (becomes interrogation) +- Ask for specifics and examples ("Can you walk me through what you did?") +- Probe contradictions gently ("Earlier you said X, now you're saying Y; help me understand") +- Watch for moments of emotion (often signal something important) +- Don't sell or convince - this is listening, not pitching + +**Anti-patterns:** + +- Leading questions ("Don't you find this confusing?") +- Hypothetical questions ("Would you use a feature that...?") - poor predictor of behavior +- Multiple questions at once +- Interrupting +- Filling silence +- Interviewing your hypothesis (only asking questions that confirm what you already think) + +### 5. Synthesize + +Notes don't become insights automatically. + +**The synthesis process:** + +1. **Capture observations.** From recordings, notes, transcripts. Each observation is a single data point: a quote, a behavior, an emotion, a moment. +2. **Affinity mapping.** Cluster observations into themes. Physical sticky notes or digital equivalents. +3. **Find patterns.** Themes that appear across multiple participants are signal. One-off observations are interesting but weaker. +4. **Identify insights.** An insight is more than a theme. It's a non-obvious finding that explains a why or implies a so what. +5. **Test the insight against the data.** If the insight only fits some interviews, it's a hypothesis, not an insight. +6. **Distinguish signal from noise.** A belief that 1 of 8 participants holds may be noise. A belief 6 of 8 hold is signal. + +**Heuristics for strong insights:** + +- They surprise the team (insights you already knew aren't insights) +- They explain a "why" the team has been guessing about +- They imply specific actions (so what?) +- They hold up across multiple data points +- They can be stated in one or two sentences + +### 6. Communicate + +Findings die in slide decks. Plan distribution. + +**Outputs that work:** + +- **Top-line insights document.** 5 to 10 insights, clearly stated, with supporting quotes. +- **Highlight reels.** Edited 5 to 10 minute video of key participant moments. More persuasive than any document. +- **In-room workshops.** Walk stakeholders through the synthesis themselves. They internalize when they participate. +- **Per-stakeholder briefs.** Different audiences need different framings. CEO wants strategic implications. Designers want pain points. Engineers want use cases. + +**Outputs that fail:** + +- 80-slide decks that get skimmed +- Reports that no one reads past the executive summary +- Verbose narrative summaries +- Insights that sit in a doc no one re-opens + +--- + +## Workflow + +1. **Frame the research question.** With stakeholders. Multiple iterations. +2. **Pick the method.** Match to the question. +3. **Plan logistics.** Timeline, budget, recruit, tools, team. +4. **Recruit.** Start early. Slow recruits delay everything. +5. **Pilot.** Run 1 to 2 sessions before the main batch. Refine the guide. +6. **Conduct.** Stay disciplined to the guide while staying open to surprises. +7. **Synthesize.** Don't wait until all sessions are done; start mid-way. +8. **Communicate.** Multiple formats. Multiple audiences. +9. **Track impact.** Did decisions change because of the research? If not, the research failed regardless of quality. + +--- + +## Failure patterns + +- **Research without a decision.** Findings have no home. Effort wasted. +- **Vague research questions.** Bad questions produce uninterpretable answers. +- **Recruiting "anyone willing."** Sample doesn't match audience. +- **Over-recruiting professional participants.** Pattern-matched answers, not real users. +- **Leading questions in the guide.** Findings reflect the researcher, not the user. +- **Skipping synthesis.** Notes alone aren't insights. +- **Insights that confirm the team's existing beliefs.** Suspect those especially. +- **Findings that never ship.** Research findings that don't change product decisions are decoration. +- **Single research project for years of decisions.** Research has a shelf life. Refresh. +- **Research as one-time project.** Continuous discovery beats episodic research. + +--- + +## Output format + +Default outputs: + +1. **Research plan** (before research starts) - `research-plan-[topic].md` +2. **Interview guide** - `interview-guide-[topic].md` +3. **Findings doc** (after synthesis) - `research-findings-[topic].md` +4. **Highlight reel** (video, separately produced) + +Findings document structure: + +```markdown +# [Topic] research findings + +## Question we set out to answer +[Specific question] + +## Method +[Approach, sample size, dates] + +## Top insights +1. [Insight, stated in one sentence] + - Supporting evidence: [Quotes, behaviors] + - Implication: [What this means for product/strategy] +2. [Insight 2] + ... + +## Themes (less prominent than top insights, still worth noting) +[List] + +## Outliers worth investigating +[Single-participant observations that may be signal in disguise] + +## Recommended next steps +[Specific actions] +``` + +--- + +## Reference files + +- [`references/interview-guide-template.md`](references/interview-guide-template.md) - Structured interview guide template with example openings, probes, and closes. diff --git a/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md b/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md new file mode 100644 index 0000000..88fcb00 --- /dev/null +++ b/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md @@ -0,0 +1,241 @@ +# Interview Guide Template + +A structured template for in-depth research interviews. Customize the sections to your topic. Length: typically 60 to 75 minutes. + +--- + +## Pre-interview prep + +**Participant info:** +- Name: +- Role / context: +- How they were recruited: +- Anything noteworthy from screener: + +**Research question being answered:** [The specific question this interview is helping answer] + +**Top 3 things I'm trying to learn:** +1. +2. +3. + +**Hypotheses I'm holding loosely:** +- [What I think I'll find. Naming this helps me notice when I confirm vs disconfirm it.] + +**Recording setup:** +- [ ] Audio recorder tested +- [ ] Video recorder (if applicable) tested +- [ ] Notetaker confirmed (or not present) +- [ ] Consent form sent + +--- + +## Section 1: Welcome and rapport (5 to 10 minutes) + +**Goal:** Put the participant at ease. Start collecting context. + +### Opening + +> "Thanks so much for joining today. As I mentioned, we're [purpose: studying how people do X / learning about Y / etc.]. There are no right or wrong answers; I'm here to learn from your experience. +> +> Before we start, do you have any questions? +> +> A few practical notes: I'll be recording so I can focus on listening rather than note-taking. The recording stays internal and is used only for our research. I'll never quote you by name without permission. You can ask me to stop the recording any time. Sound good? +> +> Great. Let's start with something easy." + +### Easy opener + +> "Tell me a little about yourself. What's your role, what does a typical [day / week / project] look like?" + +[Listen for context: industry, role, scale, constraints. Take notes on anything you want to come back to.] + +--- + +## Section 2: Context (10 to 15 minutes) + +**Goal:** Understand the world the participant lives in. Establish the context that shapes their decisions and behavior. + +### Probes (pick 3 to 5 that fit your topic) + +> "Walk me through how you handle [task] today, from start to finish." + +> "What's the last time you [specific behavior or event]? Tell me about that." + +> "Who else is involved when you [activity]? What's their role?" + +> "What tools do you use? Why those specifically?" + +> "What's typical, and what's unusual about how you approach this?" + +> "Where does your [organization / team] stand on [topic]? Any constraints I should understand?" + +### Listening notes + +- Look for **specific examples**, not generalities. "I've never been frustrated by X" is less reliable than "Tell me about the last time X frustrated you." +- Watch for **emotional tone**: where do they perk up, get quiet, or shift body language? +- Note any **language they use** that's different from how the team frames things. + +--- + +## Section 3: The core question (20 to 30 minutes) + +**Goal:** Address the heart of the research. + +### Sample probes for common research goals + +#### If exploring problems / unmet needs + +> "Tell me about the last time you had to [specific situation related to research]." + +> "What was hardest about that?" + +> "What did you try? What worked, what didn't?" + +> "If you had a magic wand and could change one thing about how this works, what would it be?" + +> "When you think about [topic], what frustrates you most?" + +#### If exploring mental models + +> "How would you explain [concept] to someone who's never heard of it?" + +> "When you hear [term we use], what comes to mind?" + +> "Can you draw or sketch how you think about [process]?" + +> "What's the goal when you [action]? What does success look like?" + +#### If exploring evaluation behavior + +> "Walk me through the last time you decided to [action]. How did you decide?" + +> "What were you comparing? How did you compare them?" + +> "What information would have helped you decide?" + +> "What made you confident in your decision? What made you nervous?" + +#### If exploring product or feature use + +> "Tell me about a time you used [product / feature]. Why? What happened?" + +> "When does [product] work well for you? When does it fall short?" + +> "What's the first thing you do when you open [product]?" + +> "What would have to be true for you to [action: recommend, expand use, switch]?" + +### Probe library (use as needed) + +> "Tell me more about that." + +> "What was that like for you?" + +> "Why does that matter to you?" + +> "Give me an example." + +> "Help me understand what you mean by [term]." + +> "Earlier you said X, now you're saying Y. Help me understand." + +> "What were you thinking at that moment?" + +> "What did you do next?" + +### Things to avoid + +- Leading questions ("Don't you think it would be better if...?") +- Hypothetical questions about future behavior ("Would you pay for...?") +- Multi-part questions +- Filling silence too quickly +- Defending the product +- Selling the product +- Asking "why" more than 2 to 3 times in a row (becomes interrogation) + +--- + +## Section 4: Reactions to specific stimuli (optional, 10 to 15 minutes) + +**Goal:** Get specific reactions to a concept, prototype, message, or design. Skip if research is purely generative. + +> "I'd love to show you something we're thinking about. There are no wrong reactions - whatever comes up for you is helpful. Take a look [share screen / show prototype / read description]." + +[Wait. Don't fill the silence.] + +> "What's your initial reaction?" + +> "What questions does this raise?" + +> "If you saw this in [context], what would you do next?" + +> "What's confusing or unclear?" + +> "Is there anything that doesn't fit your situation?" + +[Be especially alert to confused expressions, silences, and "I'm not sure what this is for." These are signal.] + +--- + +## Section 5: Wrap-up (5 to 10 minutes) + +**Goal:** Capture anything missed. Leave the participant feeling good about the experience. + +### Catch-all questions + +> "Is there anything I should have asked but didn't?" + +> "Is there anything you'd want me to know about this topic that didn't come up?" + +> "If you could give one piece of advice to the team building this, what would it be?" + +### Closing + +> "This was incredibly helpful. Thank you for the time and the candor. The [incentive] should arrive [timeline]. If you think of anything else after we hang up, my email is [email]; happy to hear from you. +> +> Last question: would it be okay if I reached out for follow-up research? I won't bombard you, but if something specific comes up and your perspective would be helpful, I'd love to be able to ask." + +--- + +## Post-interview (within 1 hour) + +While memory is fresh: + +- [ ] Write down 3 to 5 most surprising or vivid moments +- [ ] Note any quotes worth coming back to +- [ ] Note any new questions raised by this interview that should change subsequent ones +- [ ] Add to the running synthesis (don't wait to start synthesis until all interviews are done) + +--- + +## Common interview pitfalls and recoveries + +| Pitfall | Recovery | +|---|---| +| Participant gives short, surface answers | "Tell me more about that." Or wait silently. Often produces depth. | +| Participant goes far off-topic | "That's interesting. Let me bring us back to [topic]." | +| You realize the question was leading | "Let me ask that differently. What's been your experience with [topic], in your own words?" | +| Participant asks what you're working on | "I want to hear your unbiased thoughts first. Happy to share more at the end." | +| Participant tries to give you the "right" answer | "Honestly, the more frank you can be, including frustrations or criticisms, the more valuable for us." | +| You realize you're 20 minutes over | Wrap promptly. Ask the most important remaining question. End on time. | +| Participant has emotional reaction | Pause. Acknowledge. "That sounds like it was really frustrating. Take your time." Don't rush past. | + +--- + +## Customization notes + +This template is a scaffold. Adapt: + +- The sections to fit the topic +- The number and type of probes +- The amount of time per section +- Whether to include stimuli (Section 4) + +What stays constant: + +- Open with rapport, not the research question +- Use specific recent examples, not abstract opinions +- Use silence +- Don't lead +- Wrap on time, with grace diff --git a/dist/pi/.agents/skills/vendor-evaluation/SKILL.md b/dist/pi/.agents/skills/vendor-evaluation/SKILL.md new file mode 100644 index 0000000..03b9d4c --- /dev/null +++ b/dist/pi/.agents/skills/vendor-evaluation/SKILL.md @@ -0,0 +1,280 @@ +--- +name: vendor-evaluation +description: "Evaluate, select, and contract with vendors and SaaS tools. Use this skill when comparing alternatives, running an RFP, scoring vendors against criteria, negotiating contracts, planning a switch, or assessing a vendor's risk. Triggers on vendor evaluation, RFP, vendor selection, build vs buy, SaaS evaluation, vendor scorecard, vendor comparison, contract negotiation, vendor switch, procurement. Also triggers when a renewal is coming up or when a tool isn't meeting expectations." +category: process-and-team +catalog_summary: "Tool and vendor selection using a structured rubric" +display_order: 3 +--- + +# Vendor Evaluation + +Pick the right tool or service, negotiate fair terms, and avoid the lock-in traps. Stack-agnostic. Applies to SaaS, infrastructure providers, agencies, and any external dependency. + +--- + +## When to use + +- Selecting a tool or vendor for a new need +- Evaluating alternatives to a current vendor +- Build vs buy analysis +- Renewal coming up: should we stay or switch? +- Running a formal RFP or RFI +- Comparing finalists in a vendor selection +- Negotiating a contract +- Assessing vendor risk (financial, security, dependency) + +## When NOT to use + +- General cost reduction (use `cost-optimization`) +- Specific contract legal terms (those go to legal) +- Performance issues with an existing vendor (try fixing before switching) +- Hiring an agency for a one-off project (lighter framework needed) + +--- + +## Required inputs + +- The need (what problem are you solving, what would success look like) +- Constraints (budget, timeline, integration requirements) +- Stakeholders (users, IT, security, finance, legal) +- Existing context (what's already used, what's been tried) +- Compliance requirements + +--- + +## The framework: 5 phases + +A structured vendor evaluation. Skip phases at your peril. + +### Phase 1: Define the need + +Before looking at vendors, define what you actually need. + +- What problem are you solving? +- What's the user / use case? +- What does "success" look like in 6 months? In 2 years? +- What's the budget (range, not just ceiling)? +- What's the timeline? +- Are there must-have integrations or constraints? + +The temptation: skip this and start demoing. Vendors are happy to show off; you end up choosing what looks shiny rather than what fits. + +### Phase 2: Build vs buy + +Before evaluating vendors, decide whether you should build instead. + +**Build when:** +- It's core to the business (differentiating) +- The need is so specific no vendor matches +- The economics work at your scale +- You have the team to maintain it +- Vendor lock-in would be unacceptable + +**Buy when:** +- It's table stakes (not differentiating) +- The need is well-served by existing products +- The economics favor it +- The team should focus elsewhere +- The vendor's specialization beats your generalism + +Most teams over-build. The rule of thumb: buy unless there's a strong reason to build. Then question even that strong reason. + +### Phase 3: Generate the shortlist + +Cast a wider net than feels comfortable, then narrow. + +Sources: +- Internal team's existing knowledge +- Industry analyst reports (Gartner, Forrester, etc.) +- Peer recommendations (other companies similar to yours) +- Reviews (G2, Capterra; with caveats about review quality) +- Adjacent vendors you already use (often have the feature you need) +- Open-source alternatives + +Cast wide first. Aim for 5-8 candidates. Then narrow to 2-4 finalists for deep evaluation. + +### Phase 4: Score the finalists + +Use a scorecard. Without one, you'll be swayed by demo theatrics or who has the friendliest sales rep. + +Scorecard dimensions (weight by your situation): + +**Functional fit (40%):** Does it do what you need? Edge cases handled? UX quality. Workflow fit. + +**Technical fit (15%):** Integration with your stack. API quality and completeness. Data export and portability. Performance at your scale. Self-hosted, hybrid, or SaaS-only. + +**Operational fit (10%):** Onboarding effort. Training and adoption. Documentation quality. Support quality (test by submitting a ticket). SLAs. + +**Security and compliance (10%):** SOC 2, ISO 27001, HIPAA, etc., as applicable. Data residency. Encryption at rest and in transit. Access controls and audit logs. Penetration test results (ask). Subprocessors. + +**Vendor health (10%):** Years in business. Funding and runway (or revenue if private). Customer base size and similar customers. Public references. Roadmap visibility. + +**Cost (10%):** License or subscription cost. Implementation and onboarding cost. Training cost. Integration cost. Opportunity cost (in-house resource time). Switching cost (in case of failure). + +**Lock-in risk (5%):** Data export quality. Standard formats vs proprietary. Migration paths to alternatives. Open standards alignment. Contract escape clauses. + +Score each finalist 1-5 on each dimension. Multiply by weight. Sum. + +The score isn't gospel. It surfaces the tradeoffs. + +### Phase 5: Negotiate + +Most enterprise contracts are negotiable. Most aren't negotiated. + +**What's negotiable:** +- Price (multi-year, volume, prepayment, end-of-quarter timing) +- Terms (payment schedule, renewal terms) +- Success commitments (training, onboarding, support) +- SLAs (uptime, response time, credits) +- Termination clauses (auto-renewal, notice period, data export) +- Liability caps and indemnity (legal will care about these) +- Subprocessors and data handling (security/legal cares) + +**Common negotiation moves:** +- Multi-year discount (3-year for a 15-30% discount is common) +- Volume tiers (commit to higher usage for a per-unit discount) +- Annual prepayment for a discount +- Free or discounted onboarding +- Pilot pricing (trial period at reduced rate) +- "Most favored customer" clauses (if your size warrants) + +**What to avoid:** +- Multi-year lock with no escape clause for material breach +- Auto-renewal with short notice window (under 60 days; want longer) +- "All right, no further negotiation" stance from the start +- Signing without legal review + +--- + +## Workflow + +### Step 1: Define the need + +Write a one-page brief: what we need, why, success criteria, constraints, stakeholders. + +### Step 2: Build vs buy + +Honestly answer the build/buy question. Document the rationale. + +### Step 3: Generate shortlist + +Wider net first, narrowed via desk research: +- Read summaries +- Skim reviews +- Look at customer logos +- Skim docs +- Skim API specs + +Eliminate obvious misfits. Land on 2-4 finalists. + +### Step 4: Run demos and trials + +For each finalist: +- Demo with the use case (don't take their default demo; bring yours) +- Trial period if possible +- Reference calls with similar customers +- Pilot with real data if feasible + +Don't be charmed by the polished demo. Try it with your real workflow. + +### Step 5: Run security and compliance review + +Critical for any vendor handling sensitive data: +- Request SOC 2 / ISO 27001 reports +- Review their security questionnaire (most have one ready) +- Verify data handling matches your requirements +- Identify subprocessors + +This can take weeks for enterprise vendors. Start early. + +### Step 6: Score + +Apply the scorecard. Do this collaboratively with stakeholders. + +The scoring conversation matters more than the final number. It surfaces disagreement (one person scored UX 5, another scored 2: why?). + +### Step 7: Negotiate + +With the apparent winner: +- Open negotiation by asking for terms (not just price) +- Be willing to walk +- Run negotiations with #2 in parallel where appropriate (gives you leverage) + +### Step 8: Plan the rollout + +Contract signing is the start, not the end. Plan: +- Onboarding owner +- Training plan +- Migration plan if replacing an incumbent +- Success criteria at 30, 90, 180 days +- Renewal calendar + +### Step 9: Document + +Record: +- The decision and the rationale +- Alternatives considered +- Scorecard results +- Negotiated terms +- Renewal date and notice deadlines +- Owner of the relationship + +This is gold for the next renewal or the next similar evaluation. + +--- + +## Failure patterns + +**Skipping the needs definition.** Demoing first. Buying what's shiny. Realizing 6 months in that the actual need wasn't met. + +**Single-source decisions.** Talking to one vendor; deciding. No comparison. Probably overpaying or under-fitting. + +**Charisma-driven decisions.** Buying based on the sales rep's likability. The product is what you'll use for years; the rep won't be there. + +**Reference calls that the vendor curated.** Of course their references love them. Find references the vendor didn't suggest. + +**Glossing over security.** Security review skipped because of timeline pressure. Then a breach. Slow down or accept the risk explicitly. + +**Demos that don't match the use case.** Their default demo, not yours. Always do a use-case demo. + +**Trial that doesn't simulate real usage.** A trial with synthetic data tells you the product works in synthetic conditions. Use real (or close to real) data. + +**Negotiating only on price.** Terms, SLAs, and exit clauses matter more for long-term satisfaction than 5% price. + +**Auto-renewal without notice tracking.** Renewal happens; rate goes up 15%. No one was watching. Track renewals; review with notice. + +**Lock-in without exit plan.** Tightly integrating into a vendor's proprietary surface. When you want to leave, you can't. Plan exit at the start. + +**Multi-year contract for an unproven vendor.** Save the multi-year for vendors you trust. New vendor: shorter term, evaluate after. + +**No internal champion.** Tool selected; no one drives adoption. Tool sits unused. Identify the champion before signing. + +**Negotiating after a verbal commitment.** "Yes, we want to buy" means they have less reason to negotiate. Keep options open until terms are settled. + +**Ignoring red flags in security review.** Vendor's security responses are evasive or incomplete. Treat as a no. + +**Comparing apples to oranges.** Vendors price differently (per user, per usage, flat). Build a comparable cost model at your scale. + +--- + +## Output format + +A vendor evaluation document includes: + +- **Need brief:** problem, success criteria, constraints +- **Build vs buy decision:** with rationale +- **Shortlist:** 2-4 finalists with brief description +- **Scorecard:** filled out per finalist +- **Demo and trial notes:** what was learned +- **Security and compliance summary:** findings per finalist +- **Reference call notes:** what customers said +- **Recommendation:** which vendor, with rationale +- **Negotiated terms:** what was agreed +- **Rollout plan:** onboarding, training, migration +- **Renewal calendar:** with notice deadline + +--- + +## Reference files + +- [`references/evaluation-rubric.md`](references/evaluation-rubric.md) - Scoring template with weighted dimensions, 1-5 scale criteria for each dimension, and a worked vendor-comparison example. diff --git a/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md b/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md new file mode 100644 index 0000000..6689c2f --- /dev/null +++ b/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md @@ -0,0 +1,178 @@ +# Evaluation rubric + +A scoring template for vendor evaluations. Adapt the dimensions, weights, and scale to fit the decision. + +## The rubric structure + +Score each candidate on each dimension using a 1-5 scale. Multiply by the dimension's weight. Sum for a total. + +Numbers do not make the decision. They make differences visible. Use the totals to challenge your gut, not replace it. + +## Dimensions and what to score + +### Functional fit (typical weight: 25%) + +How well does the product do the specific job? + +| Score | Meaning | +| --- | --- | +| 5 | Does the job exactly. Built for this use case. | +| 4 | Does the job with minor configuration. | +| 3 | Does the job with workarounds or extensions. | +| 2 | Partial fit. Significant gaps. | +| 1 | Wrong tool for the job. | + +Evaluation method: trial the product on real (or representative) data. + +### Total cost (typical weight: 20%) + +Three-year total cost of ownership, including hidden fees and scaling. + +| Score | Meaning | +| --- | --- | +| 5 | Cost is well below alternatives. Pricing is predictable. No hidden fees. | +| 4 | Cost is competitive. Pricing scales gracefully. | +| 3 | Cost is fair. Some scaling concerns. | +| 2 | Cost is high or scaling is punitive. | +| 1 | Cost is prohibitive or pricing is opaque. | + +Evaluation method: project cost at 1x, 5x, and 10x current usage. Read the pricing page line by line. Ask sales for a custom quote at projected scale. + +### Reliability (typical weight: 15%) + +How often does it work? + +| Score | Meaning | +| --- | --- | +| 5 | Strong SLA, public status page, low historical incidents. | +| 4 | Reasonable SLA, transparent status, infrequent incidents. | +| 3 | Standard SLA, some visibility, occasional issues. | +| 2 | Weak SLA, limited visibility, frequent issues. | +| 1 | No SLA, no status page, customer reports of unreliability. | + +Evaluation method: read the SLA, browse status page history for 90 days, search for outage reports. + +### Integrations and ecosystem (typical weight: 15%) + +How well does it fit your stack and what is the exit story? + +| Score | Meaning | +| --- | --- | +| 5 | Native integrations to your stack, comprehensive API, easy data export. | +| 4 | Most integrations exist or are easy to build. Clean export path. | +| 3 | Some integrations, partial API, exportable with effort. | +| 2 | Limited integrations, weak API, hard to export. | +| 1 | Closed ecosystem, no API, vendor lock-in. | + +Evaluation method: list the integrations you need. Check each. Test the export. + +### Operational fit (typical weight: 10%) + +How easy is it to run? + +| Score | Meaning | +| --- | --- | +| 5 | Self-service, well-documented, low ongoing burden. | +| 4 | Mostly self-service. Support responds when needed. | +| 3 | Requires some hand-holding from vendor. | +| 2 | Requires significant ops effort or vendor intervention. | +| 1 | Black box that needs constant management. | + +Evaluation method: read the docs, send a test support question, ask "who would own this internally" and gauge the answer. + +### Vendor durability (typical weight: 10%) + +Will they be around in 3 years? + +| Score | Meaning | +| --- | --- | +| 5 | Profitable, established, deep customer base, growing. | +| 4 | Well-funded, growing, healthy customer base. | +| 3 | Stable but uncertain. Some risk signals. | +| 2 | Layoffs, leadership turnover, customer churn signals. | +| 1 | Likely to be acquired, shut down, or pivot. | + +Evaluation method: company news search, LinkedIn for headcount trends, customer review sites for sentiment. + +### Support quality (typical weight: 5%) + +What happens when something goes wrong? + +| Score | Meaning | +| --- | --- | +| 5 | Fast, technical, available 24/7 if needed. | +| 4 | Reliable, knowledgeable, business-hours coverage. | +| 3 | Adequate. Sometimes slow. | +| 2 | Slow, scripted, escalation needed for real issues. | +| 1 | Unreachable or unhelpful. | + +Evaluation method: send a real technical question during the trial. Time the response. Read the answer. + +## Worked example: picking an email service provider + +Job statement: "Send 200K transactional emails per month, 50K marketing emails per month, with deliverability above 98%, webhook delivery confirmation, and integration with our CRM." + +### Weighted scores + +| Dimension | Weight | Vendor A | Vendor B | Vendor C | +| --- | --- | --- | --- | --- | +| Functional fit | 25% | 5 (1.25) | 4 (1.00) | 5 (1.25) | +| Total cost | 20% | 3 (0.60) | 4 (0.80) | 2 (0.40) | +| Reliability | 15% | 5 (0.75) | 4 (0.60) | 5 (0.75) | +| Integrations | 15% | 4 (0.60) | 3 (0.45) | 5 (0.75) | +| Operational fit | 10% | 4 (0.40) | 5 (0.50) | 3 (0.30) | +| Vendor durability | 10% | 5 (0.50) | 3 (0.30) | 5 (0.50) | +| Support quality | 5% | 4 (0.20) | 4 (0.20) | 5 (0.25) | +| **Total** | **100%** | **4.30** | **3.85** | **4.20** | + +### What the numbers say + +Vendor A and Vendor C are close. The difference comes down to cost (B and A both better than C) vs integrations (C better than A and B). + +### What the numbers do not say + +The numbers do not capture: + +- A's pricing has a cliff at 500K monthly emails. We project crossing that within 18 months. +- C has best-in-class deliverability for our specific industry. +- B is rumored to be in acquisition talks. + +The numbers narrow the field to A and C. The qualitative read picks one. In this hypothetical: Vendor C wins on the strength of deliverability and ecosystem fit, despite being more expensive, because deliverability is the actual job and cost is recoverable. + +### What the decision memo looks like + +``` +Vendor: C +Reasoning: +- Best functional fit on deliverability and webhook reliability. +- Strongest ecosystem and exit story. +- Higher cost is justified by ROI from deliverability lift. +- A was a strong second; we will revisit if C disappoints in + year 1. + +Decision date: [date] +Reviewer: [person] +Next review: [date + 12 months] +Contract terms: +- 1-year commit, with option to extend +- Termination notice: 60 days +- Data export confirmed working in trial +``` + +## Adapting the rubric + +Different decisions weight dimensions differently. Some examples: + +- **Hosting decision**: reliability and operational fit weighted higher. +- **CMS decision**: functional fit and integrations weighted higher. +- **Analytics decision**: vendor durability and integrations weighted higher (you keep data here for years). +- **Payment processor decision**: reliability, support quality, and vendor durability weighted higher. + +Adjust weights before scoring. If you adjust after, you are rationalizing. + +## How to use the rubric without lying to yourself + +- Score independently first if multiple stakeholders are evaluating. Compare scores. Discuss the differences. +- Sleep on the scores before deciding. +- If the math points to a vendor your gut hates, find out why. Either the rubric is missing a dimension or your gut is wrong. Both happen. +- Document the score, the weights, and the qualitative notes. Store with the contract. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md b/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md new file mode 100644 index 0000000..b9f6e22 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md @@ -0,0 +1,213 @@ +--- +name: vertical-site-conventions +description: "Compose pages and sites that read as their vertical: ecommerce-catalog storefronts that look like storefronts, hospitality-food sites that look like restaurants, b2b-manufacturer sites that look industrial. Use this skill whenever the user wants to build a site that looks like the vertical it serves, fix a build that reads as generic or off-vertical, build to an experience bar produced by competitor-experience-audit, or compose pages with the merchandising, density, and layout conventions a credible site in the category is expected to carry. Triggers on vertical conventions, storefront layout, ecommerce layout, retail conventions, merchandising layout, category page composition, site composition, build to the experience bar, make it look like the vertical, off-vertical, looks generic, build conventions for a vertical, site grammar. Also triggers when a build that is technically clean reads wrong for its category, and the cause is composition, not visual taste." +category: design +catalog_summary: "Vertical page and site composition built to the experience bar" +display_order: 4 +--- + +# Vertical Site Conventions + +Compose pages and whole sites to the layout, density, and merchandising conventions that make a build read as a credible member of its vertical. Stack-agnostic. Works on any framework that can express server-rendered pages and component composition. + +This skill owns vertical-level composition: which modules go where, how dense the page is, how much of the catalog or offering is surfaced, and which paths the navigation serves. It routes the day-to-day visual decisions to `design-standards`, the aesthetic register to `creative-direction`, the site-structure modeling to `information-architecture`, and the component implementation to `frontend-component-build`. It does not duplicate any of them; it composes their outputs into a vertical-correct site. + +It is the build-side counterpart to `competitor-experience-audit`. The audit measures the field on seven dimensions; this skill builds to those same seven, dimension by dimension. The two are deliberately structured as two sides of one standard so an experience bar produced by the audit maps one-to-one onto what this skill builds. + +--- + +## When to use + +- Building a new site in a vertical you have not built in before +- Fixing a build that reads as generic or off-vertical even though it is technically clean (the SEO, accessibility, and component implementation are correct, but the page does not read like its category) +- Building to an experience bar produced by `competitor-experience-audit` (the audit-fed path is the intended use) +- Adding the merchandising, density, and navigation conventions a site in this category is expected to carry +- Building a showcase or demo where the build must read as its vertical, not as a generic SaaS landing page + +## When NOT to use + +- Day-to-day visual decisions on a known build (use `design-standards`) +- Defining the brand register or aesthetic from scratch (use `creative-direction`, `brand-archetype-system`, `brand-discovery`) +- Building one component well (use `frontend-component-build`) +- Modeling site structure and navigation hierarchy from scratch (use `information-architecture`) +- Building a formal design system or token system (use `design-system`) +- Auditing the competitive field for what conventions exist (use `competitor-experience-audit`; this skill consumes that audit's output, it does not produce it) + +--- + +## Required inputs + +- The site shape the build is for, from the controlled list: `ecommerce-catalog`, `inventory-listing`, `directory-marketplace`, `local-service-booking`, `subscription-app`, `hospitality-food`, `institution-mission`, `b2b-manufacturer`, `ecommerce-standout`, `hospitality-experience`. +- An experience bar from `competitor-experience-audit` (the cross-site patterns and gaps for the vertical). If absent, the skill falls back to the per-shape default conventions in the references; the audit-fed path is stronger and is the intended use. +- The brand register and aesthetic decisions (from `creative-direction` or already settled). This skill does not redefine them. +- The framework or technical context the build will use (the skill is stack-agnostic but the consumer needs to know). + +If the site shape is unclear, ask. Building to the wrong shape's conventions produces a build that reads off-vertical, which is the exact failure this skill exists to prevent. + +--- + +## The framework: build to the seven dimensions + +The framework mirrors the seven dimensions `competitor-experience-audit` measures. Each is expressed here as build guidance (what to do) rather than audit questions (what to observe). Run them in order; the synthesis in dimension 7 is the composition checklist that catches what the earlier six missed. + +### 1. Build the primary task as the dominant, earliest element + +The visitor arrives with a primary job. The leaders in the vertical lead with that job; off-vertical builds bury it behind marketing copy or competing CTAs. + +- Identify the vertical's primary task from the experience bar or the per-shape reference. (Ecommerce-catalog: a fitment, search, or category-entry interaction. Hospitality-food: a menu or reservation entry. Inventory-listing: a search-and-filter. Local-service-booking: a "book now" or service-picker.) +- Give that task the largest, earliest interactive treatment in the hero. +- Demote competing CTAs. The hero gets one primary action; secondary actions live below the fold or in the chrome. +- Reach the core task without scrolling on the device class the vertical's visitors use. +- For commercial pages, sticky a compact version of the primary task to the chrome so it stays reachable on scroll. + +If the primary task cannot be the hero (a constraint from a stakeholder, a regulated vertical), surface the closest equivalent and document the compromise. Do not silently push the primary task below the fold. + +### 2. Build to the vertical's layout register and density + +Most off-vertical builds default to a generic SaaS-airy landing page. Retail and catalog verticals are denser; editorial verticals are calmer; hospitality is image-led. Build to the field's density, not to a default. + +- Identify the register from the experience bar or the per-shape reference (storefront-dense, editorial-calm, marketing-airy, image-led). +- Match the field's content-per-viewport: a catalog vertical surfaces more modules above the fold than a SaaS landing page. +- Choose the module count above the fold deliberately. State the count in the build notes. +- Route the actual color, type, and aesthetic choice to `creative-direction` and `design-standards`. This skill owns the density and module-count decision, not the visual register itself. + +Composition decision lives here. Visual register lives there. Do not redefine either; route to the right skill. + +### 3. Build the merchandising and category surface the vertical uses + +How much of the catalog or offering is surfaced at once, and in what shape, is a per-vertical decision the build must own. + +- Surface the catalog the way the vertical does: how many category, collection, or entry-point modules appear before scroll. +- Signal depth the way the vertical signals it: mega-menu hover, grid of category cards, faceted-search side rail, breadcrumb-driven hierarchy. Pick one and commit; do not stack three. +- Choose flat (one tier visible) or hierarchical (parent plus child categories shown together) per the vertical's convention. +- Use icon / image / text / hybrid category presentation per the vertical. + +Cross-reference `information-architecture` for the structural modeling of the nav tree. This skill owns the compositional surface; that skill owns the structural model. + +### 4. Build both the know-what-I-want and the browse path the vertical expects + +Verticals differ on which path is primary. A catalog vertical needs both search and category browse, with search often primary. A hospitality-food site rarely needs search but always needs a menu and a reservation entry. Build to the paths the field actually offers, in the prominence the field gives them. + +- List the paths the experience bar names (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience). +- Score each path as primary, secondary, or absent per the vertical. +- Build the primary paths into the hero or primary nav. Build the secondary paths into the chrome or below the fold. Drop the paths the field does not use. +- Search input prominence is a per-vertical decision: header-primary, secondary in a side rail, or absent. Match the field. + +Route the structural nav modeling to `information-architecture`; route the search UX patterns to that skill or to the project's existing search component. This skill owns which paths exist and how prominent each is. + +### 5. Build the brand posture consistently across the page + +The brand register is set by `creative-direction` and `brand-archetype-system`. This skill does not redefine it. But composition decides whether the posture holds across the page or only in the hero. + +- Carry the brand register from the hero into the nav, the cards, the empty states, the trust signals, and the footer. A premium-utilitarian register that disappears below the hero is a composition failure, not a brand failure. +- Apply the voice consistently in headings, microcopy, CTAs, and empty states. Do not let the empty states default to generic copy. +- Hold the imagery posture across the page: a vertical that uses studio product photography in the hero does not switch to abstract illustration in the trust section. + +Route the actual register choice and the voice attributes to `creative-direction` and `brand-voice`. Own the consistency requirement here. + +### 6. Build the trust and conversion signals the vertical requires + +Each vertical has a different set of trust signals it is expected to carry. A build that ships without them reads as not-yet-credible. Build them in. + +- Identify the required signals from the experience bar or the per-shape reference. (Ecommerce-catalog: reviews, guarantees, pricing transparency, stock signals, fitment confirmation, shipping promises. Hospitality-food: hours, location, reservation availability, menu price range. B2b-manufacturer: certifications, customer logos, spec sheets. Local-service-booking: licensing, insurance, service-area, response time.) +- Surface them where the field surfaces them. Reviews near the buying action; service-area in the hero; certifications in the chrome. +- Honor the functional-vs-demo line for showcase builds: real where touchable (real reviews if they exist, real cart state), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment). + +### 7. Run the synthesis as a composition checklist + +The seventh dimension is the synthesis: the specific conventions a credible build in this vertical must have, named explicitly. Run this as a pre-ship checklist before declaring the composition done. + +- Pull the conventions from the experience bar's dimension 7, or from the per-shape reference's recurring-conventions section. +- For each, confirm the build does it. Mark each item present, absent, or routed elsewhere (with a link to the routing decision). +- If three or more conventions are absent, the build is off-vertical. Go back to the earlier dimensions; this is not a polish-pass fix. +- If one or two are absent, name the reason: deliberate positioning (the wedge the build is exploiting from the audit's gaps section), constraint (stakeholder, technical), or oversight (fix before ship). + +The synthesis is what catches builds that pass dimensions 1 through 6 individually but compose into something off-vertical anyway. Run it. + +--- + +## How the skill consumes an experience bar + +When `competitor-experience-audit` has run for the vertical, its output is the input to this skill. The audit's seven dimensions map directly onto this skill's seven, in order. Concretely: + +- The audit's `Primary-task prominence` pattern names what to build in this skill's dimension 1. +- The audit's `Layout register and density` pattern names the density target for dimension 2. +- The audit's `Merchandising and category surface` pattern names the surface shape for dimension 3. +- The audit's `Primary navigation and search paths` pattern names the path inventory for dimension 4. +- The audit's `Brand register and conviction` pattern names the register `creative-direction` should be working from, which this skill carries across the page in dimension 5. +- The audit's `Trust and conversion signals` pattern names the required signals for dimension 6. +- The audit's `Recurring vertical conventions` are the checklist for dimension 7. +- The audit's `Gaps` section names the positioning opportunity the build can exploit as its wedge. + +If no audit has been run, fall back to the per-shape reference files in `references/`. The default conventions there are derived from observable cross-site patterns and are honest, but a vertical-specific audit is stronger and is the intended path. + +--- + +## Stays in its lane (load-bearing) + +This skill owns one thing: vertical-level page and site composition. It routes everything else, and that routing discipline is what keeps it useful and what keeps the catalog clean. + +- Visual tokens, color, type, contrast, spacing scale: route to `design-standards`. +- Aesthetic register, archetype, voice attributes: route to `creative-direction` and `brand-archetype-system`. +- Site structure, nav hierarchy, URL design: route to `information-architecture`. +- Component API, states, accessibility implementation: route to `frontend-component-build`. +- Formal design system, token library, component documentation: route to `design-system`. +- The audit that produces the experience bar: route to `competitor-experience-audit`. +- On-page SEO and accessibility audits: route to `seo-onpage` and `accessibility-audit`. + +If a build decision sits inside one of those skills, do not restate the standard here. Link to the skill and let it own its territory. + +--- + +## Workflow + +1. **Confirm the site shape and the experience bar.** Site shape from the controlled list. Experience bar from `competitor-experience-audit` if run; the per-shape reference otherwise. +2. **Run dimensions 1 through 6 in order.** For each, name the build decision and which other skill it routes to (for the parts that route elsewhere). +3. **Run dimension 7 as a checklist.** Confirm every recurring convention from the vertical is present, absent for a stated reason, or routed elsewhere. +4. **Write the composition notes.** Use the template in [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md). The notes are what `frontend-component-build` and `design-standards` read as the spec to implement against. +5. **Hand off to the implementation skills.** This skill's output is composition decisions, not finished components. The build is done when those decisions have been implemented through `frontend-component-build`, `design-standards`, and the project's component library. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Make it look modern."** Vague. Ask which vertical, which experience bar, which conventions. "Modern" without a vertical produces the generic SaaS-airy build this skill exists to prevent. +- **Building to a generic / SaaS-airy default when the vertical wants a denser storefront.** Retail and catalog verticals surface more per viewport than a marketing page. If the build looks calm and roomy, check the density against the field. +- **Burying the primary task.** A hero stuffed with marketing copy and three competing CTAs is the most common off-vertical failure. Dimension 1 is not optional. +- **Redefining aesthetic vocabulary instead of routing to `creative-direction`.** This skill does not coin new register names or invent new voice attributes. If the question is what posture the brand takes, that is `creative-direction`'s call. +- **Treating the experience bar as optional when it is available.** If `competitor-experience-audit` has run for the vertical, the bar is the spec. Building to the per-shape default while ignoring the audit's bar is half a build. +- **Producing a template instead of building to the field's actual conventions.** Per-shape references are starting points, not finished templates. They name the patterns the field shares; the build still has to land them in this brand and this brief. +- **Skipping dimension 7.** A build that passes dimensions 1 through 6 individually can still compose off-vertical. The synthesis check is the one that catches it. +- **Calling implementation detail "composition".** Button radius, font size, color contrast are `design-standards` decisions. Module count, primary-task prominence, category-surface depth are this skill's decisions. Do not bleed across the line. + +--- + +## Output format + +Default output is a markdown set of composition notes at `composition-[site-shape]-[brand-slug].md` in the project root. Structure: + +1. The site shape and the experience bar consulted (or "no audit available; per-shape reference used") +2. Dimension-by-dimension build decisions (1 through 6) +3. The synthesis checklist (dimension 7), each convention marked present / absent / routed +4. The wedge (which gap from the audit's gaps section this build is exploiting, if any) +5. The hand-off list: what `frontend-component-build`, `design-standards`, and `creative-direction` need from these notes to implement + +Keep notes under 1500 words. The notes are a spec for the implementation skills; if they need more detail, that is a sign one of those skills should own the deeper specification. + +--- + +## Reference files + +- [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md) - The per-dimension build checklist applied as a pre-ship review. Mirror of the audit's dimension checklist on the build side. +- [`references/shape-ecommerce-catalog.md`](references/shape-ecommerce-catalog.md) - Default conventions for the ecommerce-catalog shape (first test case; auto-parts and similar dense storefronts). +- [`references/shape-inventory-listing.md`](references/shape-inventory-listing.md) - Stub; fill when the first inventory-listing demo is built. +- [`references/shape-directory-marketplace.md`](references/shape-directory-marketplace.md) - Stub. +- [`references/shape-local-service-booking.md`](references/shape-local-service-booking.md) - Stub. +- [`references/shape-subscription-app.md`](references/shape-subscription-app.md) - Stub. +- [`references/shape-hospitality-food.md`](references/shape-hospitality-food.md) - Stub. +- [`references/shape-institution-mission.md`](references/shape-institution-mission.md) - Stub. +- [`references/shape-b2b-manufacturer.md`](references/shape-b2b-manufacturer.md) - Stub. +- [`references/shape-ecommerce-standout.md`](references/shape-ecommerce-standout.md) - Stub. +- [`references/shape-hospitality-experience.md`](references/shape-hospitality-experience.md) - Stub. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md new file mode 100644 index 0000000..5b9abf4 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md @@ -0,0 +1,120 @@ +# Shape: b2b-manufacturer + +Industrial manufacturers, robotics, machine tools, components, OEMs, industrial integrators. The reader arrives as a buying engineer, a procurement specialist, an operations leader, or an industrial integrator, wanting specs, applied examples with named metrics, certifications, and a short path to an engineer-not-a-sales-rep. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (robotics, machine tools, semiconductor equipment, industrial sensors), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** see the products with specs visible, see the applied examples with named metrics, and request a demo or working session with an application engineer. The B2B-manufacturer conversion is a sales conversation, not a transactional add-to-cart; the page is a credibility document and a routing tool. + +**Build conventions:** +- The demo / contact action is in the chrome on every page AND in the hero AND at the end of each product detail page. Three placements, one form. +- The form is short. Six fields at most (name, company, work email, role, product of interest, problem statement). Long forms signal funnel-thinking; the field's leaders treat the first call as a working session, not a qualification step. +- Specs are surfaced in HTML, not in a PDF gated behind a marketing form. PDF datasheets exist for downloading after the page has done its job, not as the only path to the spec. +- The site does not invent dollar figures for products that are quote-based. Quote-based products carry "request a quote" or "talk to engineering," not "$ X." + +## 2. Layout register and density + +**Register:** technical-considered. Denser than a SaaS marketing page; less dense than an ecommerce catalog. Photography is industrial: factory floor, product close-up on a clean concrete surface, single subject. Cinematic, restrained, not Instagram. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: a single-subject hero photograph of a product (or a representative product), a declarative one-line manifesto or capability statement, the demo CTA, AND a product-or-application strip. A B2B-manufacturer hero that leads with a marketing slogan and no product visible reads as a brochure, not equipment. +- The hero photograph is industrial, not lifestyle. Equipment on the factory floor or in studio; no humans in lab coats unless they are doing real work. +- Whitespace is engineered, not generous. The page is a working document. Editorial-airy layouts read as off-vertical; catalog-dense layouts read as wrong too. A considered mid-density grid is the convention. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be cinematic-premium (anode-ev style: drivetrain-as-design), technical-considered (edge-devtools style: spec-as-page), institutional-professional (counsel-law style: certification-led), or rugged-utilitarian (forge-fitness style: equipment-as-tool); not flowery or expressive. + +## 3. Product surface + +**Conventions:** +- A product listing page carries each product line with a name, a tagline (one declarative sentence), three to six headline specs, a product image, and a link to the detail page. +- A product detail page carries: full spec table (payload, reach, repeatability, latency, IP rating, safety standards, integration interfaces), the blurb, **a primary product image plus at least one secondary image** (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot), the certifications applicable to this product, the applications that use it, a demo CTA wired to this product, integration-interface section (OPC UA, EtherNet/IP, REST API, etc.). +- Specs are an HTML table, not an image of a table from a PDF. Crawlers and screen readers read it; copy-paste works. +- Product imagery is real, single-subject, industrial-product photography. Premium register matching the brand (factory-floor or studio backdrop, controlled lighting, the machine as the subject). Spec tables alone read as a brochure-with-numbers; a buyer needs to see the machine. Specs remain the spine of the page; imagery supports the specs, it does not replace them. +- Certifications are carried at the **product level** on the detail page, not buried on About. A buyer screening for "must be ISO 10218 certified" should see the certification on the product page in under three seconds. +- Quote-based pricing is named openly. "Quote-based"; "Talk to engineering"; "Configurations vary by integration." A blank price field signals "this is hidden from me" rather than "this is configured to your line." +- Product imagery is honest-demo where the build is a showcase: unbranded equipment, no fabricated competitor logos, no real-world manufacturer brand marks, no baked-in pricing or spec text in the image (specs live in HTML). Industrial-product image generation is prone to hallucinating brand badges and control-panel writing; the image-pipeline gate's brand-name and fabricated-logo checks are load-bearing here. + +## 4. Applications surface (the case studies) + +**Conventions:** +- An **applications page** with named industries and named metrics. Battery cell assembly, warehouse throughput, precision machining, automotive sub-assembly. Each application named with the cycle time, the throughput change, the payback period, the first-pass yield, the operator-hours saved. +- Genericized marketing prose ("a global leader in X partnered with us") is the field's miss; the convention is to name the metric even if the customer is anonymized. "Throughput up 38%. Scrap rate down 22%. Cycle time per module under nine seconds." Pattern-level facts are credible; vague success language is not. +- Each application links to or references the products it uses, so a reader who arrived via Products can cross-walk to Applications and back. +- For showcase or demo builds, the functional-vs-demo line: pattern-level facts are acceptable but should be labeled as such in the workup; the build should not imply a real anonymized customer when one does not exist. + +## 5. Company, certifications, and engineering posture + +**Conventions:** +- A Company page with founding year, headquarters, certifications, plain-language about the engineering posture. Not a brand story. +- Certifications baseline at the company level (ISO 9001, ISO 10218, UL, AS9100, IEC 61508, etc.) and at the product level on each detail page. Buyers screen for these; making them findable is a credibility move. +- Made-in-X is named openly if relevant (made in Pittsburgh, designed in Munich, assembled in Taiwan). Country of design and country of manufacture are different and both are surfaceable. +- Founding team, depth of bench, customer count, plant size are facts a buyer's committee asks for; the page should answer them without forcing a sales conversation first. +- The engineering posture (what the company believes about how to build equipment) is a real thing to name. "The factory is the test bench" or "every product runs on our own line before it ships" is the kind of plain claim that does the work brand-essay generic copy fails to do. + +## 6. JSON-LD and structured data + +**Conventions:** +- Organization schema at the layout level: name, description, url, logo, founding date, address. +- Product schema on each product detail page: name, description, category, brand, manufacturer, sku, identifier. +- Where pricing is quote-based, omit the price field rather than fake one. Structured-data validators flag missing price; the buyer reads quote-based as honest. +- BreadcrumbList on every page beneath the home. + +## 7. Demo / contact flow + +**Conventions:** +- The demo form is on-site, six fields, no third-party gating. Form mounts the same component everywhere. +- The form does not require a phone number to submit; phone is optional. +- The "what happens next" copy is honest. "An application engineer reaches out within one business day to schedule a working session" is the field's leader posture. "A representative will be in touch shortly" is the field's miss. +- Phone-as-fallback: a visible phone number for buyers who would rather call. +- For procurement-led conversations, a separate "Request a quote" path that asks for the line spec (units per year, integration constraints, certifications required) is conventional; for a single-build demo, the demo form covers both. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- Specs visible, in HTML, on every product page. +- Applications named with named metrics. +- Certifications surfaced at the product level. +- Plain company facts (founding, headquarters, plant size, deployment geography). +- Engineering-posture statement that names what the company believes. +- Optional but conventional: a named-publication pull-quote or analyst quote ("X named Volta to the top tier"). Logo walls are the field's miss; one named pull-quote is the convention. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction, real spec tables), honestly demo where it needs a backend (clearly labeled demo request modal, no fake CRM entry, no fake customer logos). + +## 9. Recurring vertical conventions (the synthesis) + +A credible B2B-manufacturer site, against the field of leaders, carries eleven conventions: + +1. A single-subject industrial hero photograph above the fold at a 1280x800 desktop viewport, with a declarative one-line manifesto and the demo CTA. +2. **(Density-bearing)** Specs surfaced as an HTML table per product, not gated behind a PDF. +3. A product listing page with each product line, its tagline, three to six headline specs, and a product image visible per line. +4. A product detail page with full spec table, certifications at the product level, applied applications, and a demo CTA wired to the product. +5. **(Density-bearing)** An applications page with named industries and named metrics (cycle time, throughput change, payback period, first-pass yield); no genericized "global leader in X" prose. +6. A Company page with founding year, headquarters, certifications, and an engineering-posture statement that names what the company believes. +7. JSON-LD Organization at the layout level; Product schema on each product detail page (with the primary and secondary image URLs populated under image). +8. **(Density-bearing)** A demo / contact form that is on-site, six fields, no third-party gating; the demo flow lives within the site's visual contract. +9. Honest "what happens next" copy on the demo path; phone-as-fallback visible. +10. Where pricing is quote-based, no fake dollar figures; the page names the quote-based posture openly. +11. **(Density-bearing, new)** Real product imagery on the product surface. Each product detail page carries a primary product image plus at least one secondary (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot). Product listing cards lead with a product image above the spec table, not specs alone. Premium / industrial / single-subject register, honest-demo where the build is a showcase (no fabricated brand marks or pricing baked into the imagery). Spec tables remain the spine of the page; imagery supports the specs, it does not replace them. + +**Threshold and density-bearing items.** A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 5, 8, and 11 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a brochure, a lead-gen funnel, or a half-built equipment site instead of a credibility document. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of the density-bearing four will make the build read off-vertical regardless of how many other conventions it hits. Treat the density-bearing items as non-skippable. + +**Why convention 11 needed to be added separately.** The first b2b-manufacturer build (Volta Robotics) carried conventions 1 through 10 cleanly: spec tables in HTML, named-metric applications, six-field on-site demo form, certifications at the product level, JSON-LD Product schema. It passed the checklist and still read thin against a premium-industrial buyer's eye: one hero image, then spec-only product cards on the lineup and spec-only detail pages. A premium capital-equipment buyer expects to see the machine, multiple angles, in-context on a line. The model flagged it, the human confirmed it. A spec-led build can be checklist-correct and still register as a brochure-with-numbers rather than equipment. Convention 11 closes that gap: the product surface carries real product imagery as a chrome-level convention, not a polish extra; the spec table is the spine and the imagery is the evidence the spine describes a real machine. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Specs are the page.** Most competitors gate specs behind a marketing form for a PDF download. A build that surfaces the full spec table in HTML on every product page owns the "we are not afraid of comparison" position. +- **Named metrics on the applications page.** Most competitors write applications in genericized marketing prose. A build that names cycle time, throughput change, and payback period (even with the customer anonymized) owns the "we ship outcomes, not narratives" position. +- **Engineer-facing demo flow.** Most competitors route demo requests through marketing-gated long forms with MQL scoring. A build that runs a six-field on-site form and connects to an application engineer (not a sales rep) owns the "first call is a working session" position. +- **Certifications at the product level.** Most competitors mention certifications on About. A build that carries the applicable certifications on each product detail page owns the "we screen the way your committee does" position. +- **Engineering-posture statement.** Most competitors write a brand story. A build that names a plain engineering belief ("the factory is the test bench"; "every product runs on our own line before it ships") owns the "we mean what we say" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md new file mode 100644 index 0000000..17b57ae --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md @@ -0,0 +1,97 @@ +# Vertical Site Conventions Checklist + +Run this checklist as the composition pre-ship review. It mirrors the seven dimensions `competitor-experience-audit` measures, on the build side. Mark each item present, absent for a stated reason, or routed elsewhere (with a link). + +Three or more absences across the seven dimensions means the build is off-vertical and needs composition work, not a polish pass. + +--- + +## 1. Primary-task prominence + +- [ ] The vertical's primary task is named (from the experience bar or per-shape reference). +- [ ] The primary task is the largest, earliest interactive element in the hero. +- [ ] No competing CTA is louder than the primary task in the hero. +- [ ] The primary task is reachable without scroll on the device class the vertical's visitors use. +- [ ] A compact version of the primary task is sticky to the chrome on scroll (for commercial pages). +- [ ] If the primary task is not the hero, the compromise is documented and the closest equivalent is surfaced. + +## 2. Layout register and density + +- [ ] The vertical's register is named (storefront-dense, editorial-calm, marketing-airy, image-led). +- [ ] The module count above the fold is decided deliberately, not by default, and matches the field's content-per-viewport. +- [ ] The visual register (color, type, aesthetic) is routed to `creative-direction` and `design-standards`, not redefined here. +- [ ] The page does not default to a generic SaaS-airy layout when the field uses a denser register. + +## 3. Merchandising and category surface + +- [ ] The number of category, collection, or entry-point modules above the fold matches the field. +- [ ] The depth signaling pattern is chosen and committed to (mega-menu, grid, faceted side rail, breadcrumb hierarchy). Not stacked. +- [ ] Flat or hierarchical category presentation matches the vertical. +- [ ] Category presentation style (icon, image, text, hybrid) matches the field. +- [ ] The nav tree structural modeling is routed to `information-architecture`, not redefined here. + +## 4. Navigation and search paths + +- [ ] The paths the field offers are inventoried (by category, brand, attribute, vehicle, location, occasion, audience). +- [ ] Each path is scored primary, secondary, or absent against the vertical. +- [ ] Primary paths land in the hero or primary nav; secondary paths land in chrome or below the fold. +- [ ] Search input prominence matches the vertical (header-primary, secondary side-rail, or absent). +- [ ] Paths the field does not use are not surfaced (do not invent paths the vertical does not carry). + +## 5. Brand register and conviction + +- [ ] The brand register is set by `creative-direction` and `brand-archetype-system`, not by this skill. +- [ ] The register carries from the hero into the nav, cards, empty states, trust signals, and footer. +- [ ] Voice is applied consistently in headings, microcopy, CTAs, and empty states. Empty states do not fall back to generic copy. +- [ ] Imagery posture is consistent across the page (no switch from studio photography to abstract illustration mid-page without a reason). + +## 6. Trust and conversion signals + +- [ ] The vertical's required signals are inventoried from the experience bar or per-shape reference. +- [ ] Each required signal is built into the page where the field places it (reviews near the buying action, service-area in the hero, certifications in the chrome, etc.). +- [ ] For showcase or demo builds, the functional-vs-demo line is honored: real where touchable, honestly demo where it needs a backend (clearly labeled demo modals, no fake payment, no real account creation). + +## 7. The synthesis: recurring vertical conventions + +Pull the conventions from the experience bar's dimension 7 (or the per-shape reference's "recurring conventions" section). For each: + +- [ ] Convention 1: __________________ , [present / absent (reason) / routed to ____] +- [ ] Convention 2: +- [ ] Convention 3: +- [ ] Convention 4: +- [ ] Convention 5: +- [ ] Convention 6: +- [ ] Convention 7: +- [ ] Convention 8: +- [ ] Convention 9: +- [ ] Convention 10: +- [ ] (Add rows as needed for the vertical's full convention list.) + +**Density-bearing items.** Some conventions are density-bearing: their absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. For the ecommerce-catalog shape, conventions 2 (category surface band above the fold at 1280x800), 9 (a promotional or deal surface near the top), and 10 (an inventory or catalog-depth signal a first-time visitor sees) are the density-bearing trio. Each shape's per-shape reference names its own density-bearing items. + +Mark the density-bearing items explicitly in the list above. Missing any one density-bearing item is sufficient to fail the synthesis on its own, regardless of how many other conventions hit. This rule comes from a real build hitting 6 of 8 conventions in an earlier (pre-density-bearing) form of this reference and still reading off-vertical because the density-bearing items it missed were the load-bearing ones. + +**Threshold:** a build hitting 8 of 10 (or the equivalent ratio for shapes with a different convention count) is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more conventions, OR any density-bearing item, is off-vertical and needs composition work, not a polish pass. Go back to dimensions 1 through 6. + +--- + +## The wedge + +If the experience bar named a recurring gap across the field, the build can exploit it as positioning. State which gap is being exploited and how the build addresses it. + +- **Gap exploited:** [from the audit's gaps section] +- **How the build addresses it:** +- **What that buys the build:** + +If the build is not exploiting a gap, that is fine; the build hits the experience bar and competes on execution. Say so explicitly. + +--- + +## Hand-off list + +- [ ] `frontend-component-build`: the components the build needs and the states each must support. +- [ ] `design-standards`: the tokens, contrast, and spacing the composition assumes. +- [ ] `creative-direction`: the register and voice the composition carries. +- [ ] `information-architecture`: the nav tree and URL structure the composition expects. + +The hand-off list is what makes this skill's output a real spec for the implementation skills, not a wish list. Each item should be specific enough that the implementation skill can read it and start. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md new file mode 100644 index 0000000..50a1acd --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md @@ -0,0 +1,19 @@ +# Shape: directory-marketplace + +Service-provider directories, home services marketplaces, freelance / contractor matching. The reader arrives wanting to find a provider for a need they can name. + +## Status + +Stub. Fill when the first directory-marketplace demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** describe the need (service, location, urgency) and surface ranked providers. Often a wizard pattern (service picker, then ZIP, then refine). +- **Layout register:** trust-led and service-led. Photos of providers, ratings, and quoted response time carry the page. +- **Merchandising:** the provider list is the merchandising. Hero often carries a service-picker plus a band of top categories. +- **Paths:** by service category primary; by location primary; by provider (named) secondary. +- **Brand register:** marketplace-neutral or strongly opinionated (premium-curated vs widest-net). Cross-reference `creative-direction`. +- **Trust signals:** verified, licensed, insured, response time, ratings with review count, dispute resolution promise. +- **Synthesis (provisional):** service picker as the first interaction, location capture early, provider ratings with substantive review counts, response-time signal, clarity on what is curated vs open. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md new file mode 100644 index 0000000..fae3e57 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md @@ -0,0 +1,119 @@ +# Shape: ecommerce-catalog + +Dense catalog storefronts. Auto-parts, hardware, industrial supply, mass-merchant retail. The reader arrives with a part to find or a category to browse. The build leads with the path that gets them to the part. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (auto-parts, hardware, tooling), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** the path to a part. For verticals where compatibility matters (auto-parts, electronics), this is a fitment / compatibility selector. For undifferentiated catalogs (hardware, office supply), this is a search input. For mass merchants, this is category-entry-grid. + +**Build conventions:** +- The primary task is the largest, earliest interactive element. Not a sidebar widget; not a modal triggered by a marketing CTA. +- Competing CTAs (newsletter, account, brand pitch) live below the fold or in the chrome. +- The primary task is sticky to the chrome on scroll. A visitor mid-page who realizes the fitment is wrong can change it without scrolling back to the hero. +- For fitment-led verticals: setting the vehicle / compatibility once carries to every subsequent page. The selection is the global context, surfaced visibly. + +## 2. Layout register and density + +**Register:** storefront-dense. Not editorial; not marketing-airy. The page is a working surface, not a brand brochure. + +**Build conventions:** +- More than four modules above the fold on desktop is normal for this shape. Two-module heros are off-vertical. +- **Above the fold at a 1280x800 desktop viewport** (not "the first or second viewport"; the assertion is hard) the page carries: the primary task, the category surface band, AND at least one merchandising or trust signal. A category band that requires any scroll to reach reads as airy and off-vertical for this shape; a real build verifies this against a rendered capture, not in prose. +- Whitespace is functional, not generous. The leaders in this shape are dense; an airy build reads as not-a-real-store. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be utilitarian, premium-utilitarian, or technical; not flowery or expressive. + +## 3. Merchandising and category surface + +**Conventions:** +- A category surface band sits **above the fold at a 1280x800 desktop viewport.** Eight to twelve category entry points is typical for a wide catalog; four to six for a focused one. ("First or second viewport" is too loose; a real build hit that and still read airy because the band slipped below the fold.) +- Depth signaling is one of: mega-menu hover (broad catalogs), grid of category cards on the home (narrow catalogs), faceted-search side rail on category pages. Pick one; do not stack. +- Category cards carry an icon, an image, or a tight text-only treatment. Hybrid icon-plus-text reads as catalog; image-only reads as marketing. +- Hierarchical surface (parent plus child categories) is conventional for broad catalogs. Flat surface fits focused catalogs. +- A **promotional or deal surface** lives near the top: a deal-of-the-week strip, a promo band, a featured-offer row. The field carries it to signal "this is an active store with offers." Its absence reads as brochure-like rather than storefront-like. The promo can be a single strip with one or two offers; it does not have to be a full module. +- An **inventory or catalog-depth signal** appears somewhere a first-time visitor will see it: a part count, "12,000+ parts in stock," a category-count figure, or a near-equivalent that establishes the catalog has real depth. The field carries it as a credibility move; its absence reads as a thin or demo catalog. The figure can be approximate, can be in the hero, the trust band, or the chrome. +- Featured / promoted collections appear below the category surface, not above; categories carry the navigation load. (The promotional surface above is distinct from featured collections; one is a deal band, the other is a curation grid.) + +## 4. Navigation and search paths + +**Paths the shape carries:** +- By category: primary. Always present. +- By search: primary. Always present, in the header. +- By brand or manufacturer: secondary to primary for broad catalogs (often a band in the chrome or a top-level page). +- By attribute (price, size, color, condition): primary on category pages via the faceted side rail. +- By vehicle / compatibility / fitment: primary for compatibility-led verticals; absent for undifferentiated catalogs. +- Newsletter, account, cart: chrome-level secondary affordances. + +**Build conventions:** +- Search input is in the header, not in a side panel. Visible width meaningful (not collapsed to an icon). +- Faceted filtering on the listing page is conventional; flat lists are off-vertical for broad catalogs. +- Sort options (price asc, price desc, name, relevance) are visible on the listing. +- Search and category browse coexist; one is not gated behind the other. + +## 5. Brand register and conviction + +**Typical postures:** utilitarian, premium-utilitarian, technical, value-led. Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; do not invent new register names here. + +**Build conventions (consistency, not register choice):** +- The register carries into the empty states, the cart, the demo modals, and the trust signals. A premium-utilitarian register that dissolves into generic copy below the fold is a composition failure. +- Voice consistency in headings, microcopy, CTAs, and empty states. +- Product imagery posture is consistent: studio product photography across listing and detail; lifestyle imagery in the hero or category headers, if used at all. + +## 6. Trust and conversion signals + +**Signals this shape carries:** +- Reviews / ratings: average plus count on listing cards and at the top of the detail page. If reviews are absent, surface an alternative (warranty, return policy, brand reputation). +- Pricing transparency: price visible on the listing card; total cost (price plus shipping plus tax) surfaced before checkout, not after. +- Stock signals: in stock, low stock, lead time, backorder. Surfaced on the listing and detail. +- Fitment / compatibility confirmation: required for fitment-led verticals. The confirmation badge ("confirmed to fit your {vehicle}") on the detail page is conventional. +- Shipping promises: free over $X, same-day, two-day. Surfaced in the chrome or hero. +- Return policy: linked from the cart and the detail page. The exact text is in `terms` or `returns`. +- Brand or store badges: certifications, "X years in business", authorized-dealer, where relevant. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real cart state, real fitment filtering), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment, no real account creation). + +## 7. Recurring vertical conventions (the synthesis) + +A credible ecommerce-catalog storefront, against the field of leaders, carries eleven conventions: + +1. A primary task that owns the hero (fitment, search, or category-grid; not a brand pitch). +2. **(Density-bearing)** A category surface band **above the fold at a 1280x800 desktop viewport**, not buried in a menu and not requiring scroll to reach. +3. Working faceted filtering on category pages. +4. A persistent global context indicator if the vertical is fitment-led (the confirmed vehicle, the selected compatibility, the active filter set). +5. Visible price on every listing card, with no "click to reveal". +6. Reviews or an explicit substitute (warranty, return policy) near the buying action. +7. A working cart with real client-side state across pages. +8. A clearly labeled checkout flow (real in production; honestly demo in showcase builds). +9. **(Density-bearing)** A promotional or deal surface near the top: a deal-of-the-week strip, a promo band, or a featured-offer row. +10. **(Density-bearing)** An inventory or catalog-depth signal a first-time visitor will see (a part count, an SKU total, a category count, or a near-equivalent). +11. **(Density-bearing, new)** Section count and merchandising volume at the field's level, not at a token-row level. A credible storefront carries roughly thirteen-plus distinct merchandising surfaces top-to-bottom on the home (desktop and mobile each, mobile typically taller), three SKU rails carrying twelve-plus product cards in total, a multi-card deals grid of four-to-eight distinct deal cards (not a single thin promo strip), a category grid of eight-plus photographic tiles, a four-to-six-cell services and trust band, twenty-five-plus distinct images on the home, and a five-to-seven-column footer. A build that hits conventions 2, 9, and 10 with one four-card rail and a five-tile category band passes the presence-check and still reads thin against the field; the bar is volume, not presence. + +**Threshold and density-bearing items.** A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 9, 10, and 11 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. A build can miss a nice-to-have (a strong substitute for reviews, for example) and still read as the vertical; missing any of the density-bearing four is the failure mode the auto-parts builds exposed across multiple iterations. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +**Why convention 11 needed to be added separately.** Before this entry, a build could carry the category band, the promo strip, and the inventory signal (conventions 2, 9, 10) and still read thin, because the prior conventions named *which* sections, never *how many* or *how full*. A category band with five tiles passed convention 2; a promo strip with one offer passed convention 9; a part-count badge passed convention 10. The build read storefront-correct on the checklist and read SaaS-airy in a rendered comparison against the field. Convention 11 closes that gap: the bar is the field's actual volume, observed top-to-bottom on a rendered home page, not a presence-check that any single token instance satisfies. + +--- + +## Capture-path note (audit infrastructure) + +The named field leaders in heavily-defended verticals (auto-parts is one) sit behind CDN/WAF bot-mitigation layers that block Fork A rendered capture even with realistic User-Agent strings. In a render-and-match attempt against the four leading parts retailers, all four were intercepted (Cloudflare, Akamai 403, DataDome interstitial, network-idle timeout) and Fork A returned zero homepage content. A synthesis pass on zero captured content silently falls back to training-knowledge abstraction, which is the exact failure mode this shape was added to defend against. + +**The lesson, recorded as audit-infrastructure guidance for this shape:** in bot-walled verticals, the realistic capture path is screenshot ingestion (a human takes desktop and mobile screenshots of each leader and drops them at a known path; the audit reads the PNGs with vision and produces the section-and-density target from observed evidence). Render-and-match through Fork A alone is not a reliable capture path for this shape. The audit script's selection of capture path should treat Fork A as the default and fall back to screenshot ingestion when zero or trivial content is returned; absent that fallback, the audit silently degrades to abstraction and the build it informs reads thin. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Fitment-first as the entire navigation pattern.** Most catalogs treat fitment as a sidebar widget. A build that makes fitment the primary, persistent, single-source-of-truth navigation owns the "wrong-fit return is impossible" position. +- **Pricing transparency to the dollar.** Most catalogs hide total cost until checkout. A build that surfaces shipping plus tax on the listing card owns the "no surprises" position. +- **Honest stock and lead-time signals.** Most catalogs use "low stock" theatrically. A build that names actual lead time owns the "we tell you when it ships, not what we want you to feel" position. +- **Real reviews vs review theater.** Most catalogs surface 4.7-star aggregates that no one trusts. A build that surfaces verified-buyer reviews with the bad ones visible owns the trust position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md new file mode 100644 index 0000000..d1d528d --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md @@ -0,0 +1,19 @@ +# Shape: ecommerce-standout + +Single-product or narrow-line ecommerce where the brand and the object carry the page. Premium boots, designer goods, single-product subscriptions, expressive consumer brands. The reader arrives because of the brand, not because of a category need. + +## Status + +Stub. Fill when the first ecommerce-standout demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** see the product (image-led), see the story (brand-led), buy. Hero often carries large product photography or a brand statement. +- **Layout register:** expressive or premium-considered. The opposite of a dense catalog; air and image carry the load. +- **Merchandising:** one product line, surfaced as a few SKUs or one product with options. The product story is the merchandising; spec lists are short. +- **Paths:** by SKU or by product secondary (the catalog is small); by story / about primary; press or recognition often surfaced; size / fit guides important. +- **Brand register:** expressive-maximalist or premium-considered. Cross-reference `creative-direction`; this shape is where strong register choices land. +- **Trust signals:** materials, where-made, founder story, press, reviews focused on quality and longevity, return policy generous and visible. +- **Synthesis (provisional):** large product photography in the hero, brand story or founding line surfaced early, size / fit / materials guide reachable, press logos if they exist, reviews emphasizing quality and longevity (not quantity), generous and clearly stated return policy. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md new file mode 100644 index 0000000..bdf348c --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md @@ -0,0 +1,19 @@ +# Shape: hospitality-experience + +Tours, balloon rides, escape rooms, adventure outfitters, immersive experiences. The reader arrives wanting to understand what the experience is, see real photos, and book. + +## Status + +Stub. Fill when the first hospitality-experience demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** book a date and time. The hero CTA is "book" or "check availability"; secondary is "what to expect" for first-timers. +- **Layout register:** image-led, atmosphere-heavy. The hero is the experience itself, in photography or video. +- **Merchandising:** experiences as packages with dates, durations, and prices. What-to-expect content carries the trust load. +- **Paths:** by experience or package primary; by date / availability primary; private events or group secondary. +- **Brand register:** expressive, premium-considered, or warm-considered. Often regionally-anchored (place-led brand). +- **Trust signals:** what-to-expect, what-to-bring, age and accessibility constraints, cancellation policy, weather policy (for outdoor experiences), safety briefing, real customer photos, recent reviews on a trusted platform. +- **Synthesis (provisional):** book or check-availability in the hero, what-to-expect content surfaced before the booking choice, constraints (age, accessibility, weather) clearly stated, cancellation and weather policies visible, recent real photography and reviews, no stock imagery that does not match the actual experience. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md new file mode 100644 index 0000000..d1b76d1 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md @@ -0,0 +1,115 @@ +# Shape: hospitality-food + +Restaurants, cafés, bakeries, food halls, ghost kitchens with a storefront. The reader arrives wanting to know if they want to eat there: what the food is, what it costs, when the place is open, whether they can get a table. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (fine dining, neighborhood restaurant, café, bakery), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** see the menu. The reservation action is the secondary primary task. For walk-in-only restaurants and cafés, the menu and the hours-and-address pair are the primary tasks; for reservation-led restaurants, the menu and the reservation flow share the lead. + +**Build conventions:** +- The menu is reachable in one click from the home page. A site that buries the menu behind a PDF link, behind a modal, or below the fold without a clear cue is off-vertical. The menu is the page, not a download. +- The reservation action is the largest CTA in the chrome (after the menu link). For walk-in-only shops, the equivalent is "where we are" and "when we open." +- The reservation flow is on-site, not punted to a third-party widget iframe. A widget that breaks the site's visual contract dissolves the room's identity at the moment the visitor is closest to deciding. +- The site's primary task is the same component everywhere. One reservation modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +**Register:** image-led, atmospheric. Less dense than a catalog; more density than a marketing page; more atmosphere than a service-booking page. The page should feel like the room. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: an edge-to-edge dish or room photograph, the restaurant name and one-line identity, AND the reservation CTA. A hospitality-food hero without a real photograph reads as a marketing template. +- The hero photograph is a single subject (one dish, one corner of the room, one moment of service), not a collage. Tiled grids of every dish lose focus; stock food imagery loses identity; single-subject photography on a confident background is the convention. +- Whitespace is generous and atmospheric. The dish gets to breathe. Catalog-dense layouts are off-vertical for this shape unless the vertical is a fast-casual chain. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be editorial-restrained (fine dining), warm-neighborhood (everyday), industrial-bright (fast-casual), or playful-soft (bakery, café); not corporate-flat. + +## 3. The menu + +**Conventions:** +- A **menu page**, not a PDF, with each item carrying a name, a description, and a price visible per item. Hiding prices is off-vertical; it tells the visitor the shop is luxury-pretense rather than confidence. +- Items are grouped by course (starters, mains, sides, desserts, drinks). For tasting menus, the courses are the structure. For diner-style menus, the categories are functional. +- Item descriptions are written, not enumerated. Two or three short sentences per item. Adjective stacks ("savory, hearty, comforting") read as marketing; ingredient-and-method copy ("twenty-four-hour bone broth, brisket, eye round") reads as the kitchen. +- Signature dishes carry a small visible mark (badge, label) so the visitor knows what to order. Hiding the signature inside the list misses the assist. +- Allergen notes are surfaced (peanut, shellfish, gluten) where the kitchen's handling requires it. Generic "ask your server" copy is acceptable but less confident than naming the handling. + +## 4. Chef, provenance, and story + +**Conventions:** +- A short chef-perspective or chef-partner passage is conventional, on the home page or the about page. Two short paragraphs at most; first-person, ingredient-literate, no marketing register. +- Provenance content (where the ingredients come from, who farms what, who supplies the seafood) carries the hospitality wedge for restaurants whose positioning leans on it. For places where it does not, this is absent. +- Staff bios beyond the chef are absent in fine dining and present in neighborhood restaurants and cafés (named baristas, pastry chefs, line cooks). Match the register of the shop. +- The story is not a brand history; it is a kitchen perspective. Brands tell origin stories; restaurants tell what they care about. + +## 5. Reservations flow + +**Conventions:** +- The form asks: name, party size, date, time, email, allergies and notes. Nothing more at this stage; not an account, not a password, not marketing consent. +- Confirmation is honest. Real production: email confirmation within the hour, sometimes within minutes. Demo build: clearly labeled demo-only, no fake confirmation copy. +- Cancellation, late, and allergy policies are visible on the reservation page, not hidden in terms or buried in confirmation email. +- Walk-in policy is named openly if relevant ("walk-ins welcome at the bar", "no walk-ins"). +- Phone-as-fallback: a visible phone number for visitors who would rather call. Restaurant customers vary; the field's best builds carry both. + +## 6. Address, hours, and visit info + +**Conventions:** +- Address visible in the chrome on every page. Hours visible at minimum in the footer; the home page should carry "open tonight" or the day's hours above the fold. +- Hours that vary (brunch on Sundays, late on weekends, closed Mondays) are listed line-by-line, not summarized. +- Transit and parking notes belong on a Visit page; they are a trust signal for visitors planning to travel to the restaurant. +- Accessibility notes (step-free entrance, accessible restroom, dress code, noise level) are conventional on the Visit page and rare in the field; their presence reads as care. +- A live map embed is optional; a static "find us" image plus a deep link to the visitor's preferred map app works as well and avoids the embed's accessibility and performance overhead. + +## 7. Press, reviews, and aggregate trust + +**Conventions:** +- One named-publication pull-quote is the conventional press treatment, not a logo wall. A short, specific quote that names what the restaurant is good at carries more credibility than five logos. +- Aggregate ratings (Google, Yelp, Resy) are present in the chrome or near the reservation action, not in a logo grid. Numbers plus counts; not stars alone. +- Awards (Michelin, James Beard, regional press) are listed plain text in the chrome or on About, not in a badge wall. +- For demo or showcase builds, the functional-vs-demo line: a placeholder press quote is acceptable but should be labeled as such in the workup, not implied to be a real publication. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- The dish photograph itself, edge-to-edge, dramatic light, single subject. +- The chef's-perspective passage that does the work of branding. +- Plain-language menu descriptions with prices. +- Open cancellation, late, and allergy policies on the reservation page. +- Visible address and hours. +- Aggregate ratings near the reservation action. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo reservation modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible hospitality-food site, against the field of leaders, carries ten conventions: + +1. An edge-to-edge hero photograph of a single dish, room, or moment, above the fold at a 1280x800 desktop viewport. +2. **(Density-bearing)** A menu page, not a PDF, with name, description, and price visible per item, reachable in one click from the home. +3. Item descriptions in ingredient-and-method voice, not adjective stacks; signature dishes marked. +4. A reservation action that is on-site, not a third-party widget iframe, available from the chrome on every page. +5. **(Density-bearing)** A short chef-perspective or chef-partner passage, first-person, two short paragraphs at most. The story of the kitchen, not a brand history. +6. Address and hours visible above the fold; full hours line-by-line on the home or visit page. +7. JSON-LD Restaurant with hasMenu, servesCuisine, acceptsReservations, openingHoursSpecification, and aggregateRating. +8. Cancellation, late, and allergy policies stated openly on the reservation page. +9. **(Density-bearing)** One named-publication press pull-quote OR a visible aggregate rating (count plus number), placed near the reservation CTA. Not a logo wall. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +**Threshold and density-bearing items.** A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **1, 5, and 9 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a template instead of the room. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of conventions 1, 5, or 9 will make the build read as a marketing page about food rather than a restaurant. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **The menu is the page.** Most competitors hide the menu behind a PDF or a modal. A build that surfaces the menu in plain HTML with ingredient-literate descriptions owns the "we know what we cook" position. +- **On-site reservations.** Most competitors punt to a third-party reservation widget. A build that keeps the reservation flow visually within the site's identity owns the "the room is the experience" position. +- **Single-subject photography.** Most competitors either tile every dish or use stock food imagery. A build that leads with edge-to-edge single-subject photography on a confident background owns the "this is the dish" position. +- **Chef's-perspective voice.** Most competitors write in marketing register (adjective stacks, brand voice). A build that writes the menu in the chef's voice (ingredient, method, restraint) owns the "we are not selling you, we are cooking for you" position. +- **Provenance literacy.** Most competitors gesture vaguely at "local, seasonal." A build that names the farmer, the supplier, the cut, owns the "we know where the food came from" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md new file mode 100644 index 0000000..b5c9e03 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md @@ -0,0 +1,19 @@ +# Shape: institution-mission + +Nonprofits, museums, foundations, public-interest organizations. The reader arrives wanting to understand what the institution does and decide whether to give, attend, volunteer, or read further. + +## Status + +Stub. Fill when the first institution-mission demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** depends on the moment. Donate during a campaign; visit / attend for an institution with a physical presence; sign up or read for a research or advocacy group. The hero CTA matches the institution's primary ask. +- **Layout register:** editorial-considered. More text than a catalog, less than a long-form publication. Trust load is heavy; expressive maximalism is rare in this shape. +- **Merchandising:** the cause or mission is the merchandising. Programs, impact, and recent work carry the page. +- **Paths:** by program primary; by impact / outcomes primary for established institutions; news / press / blog secondary; financials / 990 secondary but conventional for nonprofits. +- **Brand register:** institutional, considered, mission-led. Premium-considered for arts and culture; restrained-authoritative for advocacy. +- **Trust signals:** mission statement, board / leadership, financial transparency (for nonprofits, the 990 or audit), accreditations, named donors or partners, recent impact numbers with sources. +- **Synthesis (provisional):** mission statement above the fold, a clear primary ask (donate, attend, sign up), program or impact surface, leadership and governance reachable from the chrome, financial transparency linked (for nonprofits), no over-emotive imagery that reads as manipulative. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md new file mode 100644 index 0000000..ca1fa7f --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md @@ -0,0 +1,19 @@ +# Shape: inventory-listing + +Used-car lots, real estate, equipment rental, marketplace listings. The reader arrives wanting to filter a finite inventory down to the right item. + +## Status + +Stub. Fill when the first inventory-listing demo is built, or when a `competitor-experience-audit` for an inventory-listing vertical has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** filtered search with high-fidelity facets (price range, location, condition, year, make, model, beds, square feet). Search and faceted filtering are co-primary. +- **Layout register:** dense, but more grid-led than catalog-led. Each listing carries multiple attributes that need room to read. +- **Merchandising:** the listing is the merchandising. Hero carries a search-and-filter entry plus a few featured items. +- **Paths:** search-and-filter primary; saved-search and favorites secondary (account-gated); browse-by-attribute primary on category pages. +- **Brand register:** transactional, trust-led. Premium-led for high-ticket inventory (real estate, luxury cars). +- **Trust signals:** verified seller, listing freshness, photos count, condition reports, response time. +- **Synthesis (provisional):** persistent filter chip row, listing freshness indicators, photo count signal, save-this-listing affordance, contact-the-seller path. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md new file mode 100644 index 0000000..2628de6 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md @@ -0,0 +1,125 @@ +# Shape: local-service-booking + +Barber shops, salons, gyms, BJJ schools, dental practices, repair shops, dog groomers. The reader arrives wanting to book a time, see prices, or confirm the place exists. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (barbershops, dentists, repair shops), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** book an appointment. For unbookable services (drop-in only), the primary task is to call or to confirm hours. The booking action is the largest CTA on the page; everything else competes for second place. + +**Build conventions:** +- The book-now action is in the chrome (persistent on every page) AND in the hero, not one or the other. +- A first-time visitor who arrived to book should reach a booking surface in one click from the home page. A flow that requires "services then pick then book" is one click too many. +- For services where the picked practitioner matters (barber, stylist, trainer, dentist), the booking action surfaces the practitioner choice before the time choice. For services where practitioner does not matter (oil change, dog wash), it does not. +- The booking action is the same component everywhere on the site so a visitor cannot get lost. One booking modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +**Register:** image-led-warm. Less dense than a catalog; more dense than a marketing page. The page should feel like a room the visitor wants to be in. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: the booking CTA, an interior photograph of the space, AND a trust signal (years, license, review average, or named practitioners). A booking page without a photograph of the room reads as a third-party scheduler iframe, not a shop. +- A hero image of the space (or a close-up of the craft) is conventional and load-bearing. Stock or generic imagery reads as "any salon"; the shop's specific room reads as the shop. +- Whitespace is generous but purposeful. Editorial-airy is off-vertical; the visitor needs to see the menu and book without scrolling far. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be warm-classic, considered-premium, institutional-professional (medical, legal), or rugged-craft; not corporate-flat or marketing-flashy. + +## 3. Service menu and pricing + +**Conventions:** +- A **service menu with duration and price visible per item** lives above the fold at a 1280x800 desktop viewport, OR is one click from the home page and clearly signposted. Hiding prices behind a phone call is off-vertical for the field's modern bar; it tells the visitor the shop is friction-tolerant. +- Service descriptions are plain language, not marketing. Two sentences max per service. +- Service categories (haircut, shave, beard, package) are grouped, not flat-listed, for shops with more than five services. +- Packages (cut-and-shave, cut-and-color) are surfaced as their own line items with their own price, not as "add $X to the base service". +- For services where duration varies (skin fade vs classic cut), the longer duration is named honestly; the shop blocks the chair for the time the cut takes. + +## 4. Trust block and identity + +**Signals this shape carries above the fold:** +- Years in business ("Est. 2014", "11 years on Walnut Street"). +- License or certification, where the vertical has one (master barber license, dental board, state cosmetology, ASE certification for repair shops). +- Review average plus count (not just the stars; the count is the credibility). +- Address visible, not buried in a footer-only treatment. +- Hours visible, not buried in a footer-only treatment. A visitor planning a drop-in needs to know if the shop is open right now. +- For practitioner-driven shops: the practitioners' names and faces. Anonymous "our team" copy reads as franchise; named, photographed practitioners read as shop. + +**Build conventions:** +- The trust block is **aggregated**, not scattered. Years in one footer line, reviews on a separate widget, hours on a separate page is the field's miss; pulling them into a single above-the-fold block is the field's lever. +- JSON-LD `LocalBusiness` (or the more specific subtype: `HairSalon`, `BarberShop`, `Dentist`, `AutoRepair`) carries address, hours, telephone, and aggregateRating in structured form. Most competitors ship none. + +## 5. Practitioner roster + +**Conventions for practitioner-driven shops (barber, stylist, trainer, dentist):** +- A **roster with faces** above the booking CTA is the conversion lever the field leaves on the table. Most competitors gate the practitioner choice inside the booking flow; surfacing it before the booking choice removes a decision point. +- Each practitioner card carries: name, face, years of experience, specialties (one to three short tags). +- Bio length is one or two sentences, plain language. Long bios read as profile pages, not a roster. +- For non-practitioner-driven shops (drop-in repair, walk-in clinic), this section is absent or replaced by a "what makes this shop different" block. + +## 6. Booking flow specifics + +**Conventions:** +- The booking surface is a modal or a single-page form, not a multi-step wizard. Local-service appointments are not enterprise sales. +- The form asks: name, service, practitioner (if applicable), preferred date, preferred time window, notes. It does not ask for an account, a password, or marketing consent at this stage. +- Confirmation is honest. Real production: SMS or email within the hour. Demo build: clearly labeled demo-only, no fake confirmation copy ("you're booked!" with no booking). +- Cancellation policy, late policy, and payment policy are visible on the booking page, not hidden in terms. +- Phone-as-fallback: a visible phone number for visitors who would rather call. Local-service customers vary in digital comfort; the field's best builds carry both. + +## 7. Navigation paths + +**Paths the shape carries:** +- Services (menu, prices, durations): primary. +- Book: primary, persistent. +- Visit (address, hours, directions, parking, accessibility): primary. +- About / story / team: secondary. +- Newsletter, account, cart: absent or chrome-level afterthought. Local-service shops are not subscription products. + +**Build conventions:** +- Hours and address are in the chrome (footer at minimum) on every page. +- Accessibility info (step-free entrance, adjustable chairs, accessible restroom, quieter hours) sits on the Visit page; competitors rarely carry it and it is a real differentiator. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- Reviews / ratings: average plus count, surfaced above the fold. A four-and-up rating without a count reads as theater. +- Years in business: visible in the chrome or hero. Local shops earn trust over time and the field rewards saying so. +- License or certification number: visible, on the Visit or About page if not in the chrome. +- Plain-language service descriptions: no upcharge surprises. +- Cancellation and late policies stated openly. Generous grace windows read as confident; harsh ones read as defensive. +- Quieter hours / accessibility / language spoken: trust signals the field rarely carries; presence reads as care. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo booking modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible local-service-booking site, against the field of leaders, carries ten conventions: + +1. A book-now action that owns the hero and persists in the chrome on every page. +2. **(Density-bearing)** An interior or craft photograph of the **specific** shop above the fold at a 1280x800 desktop viewport, not stock or generic. +3. A service menu with duration and price visible per item, one click from the home page at most. +4. **(Density-bearing)** A trust block aggregated above the fold: years in business, license or certification, review average plus count. Not scattered across footer and about page. +5. For practitioner-driven shops: a roster with faces and specialties above the booking CTA. +6. Address and hours in the chrome (footer at minimum) on every page. +7. JSON-LD LocalBusiness (or vertical-specific subtype) with address, hours, telephone, and aggregateRating. +8. A booking flow that is a single-page form or modal, not a multi-step wizard; asks for name, service, time, and nothing more at this stage. +9. **(Density-bearing)** A cancellation, late, and payment policy stated openly on the booking page, not hidden in terms. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +**Threshold and density-bearing items.** A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 4, and 9 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a third-party scheduler iframe or a franchise template instead of a specific shop with a specific room. A build can miss a nice-to-have (the practitioner roster for a drop-in shop, for example) and still read as the vertical; missing any of conventions 2, 4, or 9 makes the build read as anyone's shop. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Booking-first composition.** Most competitors bury the booking action below the fold or behind a third-party scheduler iframe that breaks the visual contract. A build that makes the booking action the largest element on every page, with the shop's identity intact, owns the "we want you to book" position. +- **Roster-before-booking.** Most competitors gate the practitioner choice inside the booking flow. A build that surfaces a small, photographed roster above the booking CTA owns the "you pick the chair, then the time" position. +- **Honest service menu.** Most competitors hide prices behind a phone call or list services without durations. A build that posts duration and price for every service owns the "no surprises" position. +- **Specific-room photography.** Most competitors use stock or generic salon imagery. A build that leads with the shop's actual room owns the "this is the place" position. +- **Aggregated trust above the fold.** Most competitors scatter the trust signals (years, license, reviews) across the chrome and about page. A build that pulls them into a single above-the-fold block owns the "we are real, we are local, we are licensed" position before the visitor scrolls. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md new file mode 100644 index 0000000..2e3919a --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md @@ -0,0 +1,19 @@ +# Shape: subscription-app + +Weather apps, productivity tools, news readers, fitness trackers, language learning. The reader arrives wanting to understand the app and decide whether to install or subscribe. + +## Status + +Stub. Fill when the first subscription-app demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** install (App Store / Play Store buttons) or start trial. The download or trial CTA is the hero. +- **Layout register:** marketing-led with strong product imagery (device frames, screen captures). Editorial-airy is common. +- **Merchandising:** features as a vertical scroll of capability sections; not a catalog grid. +- **Paths:** by feature primary (scroll); pricing secondary (navigable but not first); blog / support tertiary. +- **Brand register:** wide range. Consumer apps lean expressive or playful; productivity leans considered or technical. +- **Trust signals:** App Store rating, install count, press logos, customer testimonials, screenshots that read as the actual product. +- **Synthesis (provisional):** install CTAs (real store buttons) in the hero and chrome, feature-by-feature scroll with real product imagery, pricing surfaced clearly with the free / paid line drawn, App Store rating and review count surfaced, no fake screenshots. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/PORT_NOTES.md b/dist/pi/PORT_NOTES.md new file mode 100644 index 0000000..45677c0 --- /dev/null +++ b/dist/pi/PORT_NOTES.md @@ -0,0 +1,128 @@ +# Pi port notes + +Spike: a Pi-compatible distribution of the RampStack skills catalog, produced +by a repeatable, dependency-free build (`scripts/build-pi.mjs`). Do not merge. + +## Count + +- Source skills (`skills/*/SKILL.md`): 102 +- Emitted skills (`dist/pi/.agents/skills/*/SKILL.md`): 102 +- Reference files preserved: 488 + +Note on the count: this dist was first built on a stale 99-skill base after a +disk-full event left a `git reset --hard origin/main` un-applied. It has since +been rebased onto the corrected `main` (PR #90), which is 102 skills with all +descriptions shortened under the 1024-char cap. The build now emits exactly 102 +skills, including `creative-brief-selector`, and validation asserts emitted +count equals source count. + +## Key decision: preserve native frontmatter (no sidecar) + +This is the one substantive difference from the Codex and Antigravity dists. + +- Codex and Antigravity trim each skill's frontmatter down to `name` and + `description`, and move the remaining keys (`category`, `catalog_summary`, + `display_order`) into a `references/_claude-frontmatter-extras.yaml` sidecar + so the port stays lossless and reversible. They do this because those agents + validate frontmatter against a fixed key set and reject or warn on unknown + keys. +- Pi does not. Pi's frontmatter type is `{ name?, description?, + "disable-model-invocation"?, [key: string]: unknown }`. Arbitrary keys are + accepted and ignored. So the correct, simplest, and most faithful port is to + copy each `SKILL.md` byte-for-byte with its native frontmatter intact. No + trimming, no sidecar, no transformation. + +Consequences: +- The build is a pure byte-for-byte directory copy. Building twice yields + byte-identical output. `--check` rebuilds to a temp dir and diffs against the + committed tree, exiting nonzero and listing any differing paths (staleness + guard). +- `category`, `catalog_summary`, and `display_order` remain visible in every + emitted `SKILL.md` exactly as authored. Pi ignores them; they cost nothing and + keep the dist a faithful mirror of source. + +## Validation results + +Run `node scripts/build-pi.mjs --validate`: + +- PASS: every emitted SKILL.md has valid `---` frontmatter +- PASS: every emitted SKILL.md has non-empty `name` and `description` +- PASS: every name conforms to Pi rules (lowercase a-z / 0-9 / hyphen, max 64 + chars, no consecutive hyphens) +- PASS: every description is <= 1024 chars +- PASS: emitted skill count equals source (102) +- PASS: every source references file has an emitted counterpart (488) + +No warnings. An earlier build on the stale 99-skill base reported three +descriptions over 1024 chars (`creative-direction`, `integration-orchestrator`, +`logo-design`). Those were shortened at source in PR #90, so the over-length +warning is now gone. Pi would have loaded those skills anyway (an over-length +description is a non-fatal warning; only a missing description prevents +loading), but the source fix removes the warning entirely. + +## Live discovery check + +Pi CLI is installable, so this was exercised for real, not skipped. + +- Installed `@mariozechner/pi-coding-agent` (v0.73.1) locally into a throwaway + directory outside the repo (so no `node_modules` or lockfile lands in the + lane). +- Called Pi's own loader, `loadSkillsFromDir({ dir, source })`, against + `dist/pi/.agents/skills/`. + +Results (on the corrected 102-skill base): +- 102 skills discovered (matches emitted count). +- 0 diagnostics. The three description-length warnings seen on the earlier + 99-skill base are gone now that PR #90 shortened those descriptions. +- `creative-brief` loaded cleanly (description length 701, + `disableModelInvocation: false`, filePath resolved). +- `formatSkillsForPrompt(skills)` rendered all 102 skills into a system-prompt + block (about 92k chars) with no errors thrown. + +Conclusion: Pi discovers and parses the entire emitted catalog with zero parse +errors and zero warnings. + +Manual repro (if installing fresh): + +``` +mkdir pi-cli-test && cd pi-cli-test +npm init -y && npm i @mariozechner/pi-coding-agent +# then, from a script that imports the package: +# import { loadSkillsFromDir } from '@mariozechner/pi-coding-agent'; +# loadSkillsFromDir({ dir: '<repo>/dist/pi/.agents/skills', source: 'check' }); +# or, to exercise the CLI interactively after configuring a provider: +cd <repo>/dist/pi && pi # ancestor discovery finds .agents/skills, then /skill:creative-brief +``` + +## Future options (NOT applied here) + +These are deliberately out of scope for this spike. Listed for whoever takes +the port forward. + +(a) Publishable Pi package wrapper. Pi can load skills from a `skills/` + directory or a `pi.skills` entry in a package's `package.json`, distributed + over npm or git. A thin wrapper package that points `pi.skills` at this + catalog would let users `pi install <source>` instead of copying `.agents` + by hand. Not applied: the spike's goal is a copy-in distribution, and a + published package is a separate release decision. + +(b) Explicit-only orchestration skills. Pi supports a frontmatter key + `disable-model-invocation: true` (the practical equivalent of a "hidden" + skill). A skill with this set is excluded from the always-in-context + descriptions and can only be invoked explicitly via `/skill:<name>`. This + would be a good fit for noisy orchestration skills (for example + `seo-audit-orchestration`) so they do not crowd the model's skill list and + are only run on purpose. Not applied: it changes runtime behavior and would + edit source frontmatter, which is outside this preserve-native build. + +## Running Pi on alternative models + +Pi is model-agnostic through its `pi-ai` provider layer, so the same skills run +unchanged on any supported provider. To run Pi on Kimi K2.6, point Pi at +Moonshot's API (platform.moonshot.ai) as a provider; Moonshot exposes both an +OpenAI-compatible and an Anthropic-compatible endpoint. Recommended sampling +temperature for K2.6 is 0.6. Important: Moonshot's Anthropic-compatible endpoint +already scales the incoming temperature by 0.6 internally, so do not apply the +0.6 a second time when using that endpoint (doing so would effectively send +0.36). This is provider/model configuration only; it is not a skills change and +nothing in this distribution depends on it. diff --git a/dist/pi/README.md b/dist/pi/README.md new file mode 100644 index 0000000..c5b280f --- /dev/null +++ b/dist/pi/README.md @@ -0,0 +1,73 @@ +# Pi-compatible skills distribution + +This directory is a Pi-compatible build of the RampStack skills catalog. It is +generated from the read-only `skills/` source tree by `scripts/build-pi.mjs`. +Every source skill is copied byte-for-byte into `.agents/skills/<name>/`, with +its native frontmatter preserved intact (Pi accepts arbitrary frontmatter keys, +so nothing is trimmed and there is no sidecar file). + +Pi reference: https://pi.dev and https://github.com/earendil-works/pi + +## What is here + +``` +dist/pi/ + .agents/ + skills/ + <skill-name>/ + SKILL.md preserved byte-for-byte from source + references/... preserved byte-for-byte from source + README.md this file + PORT_NOTES.md port decisions, live-check results, future options +``` + +102 skills, 488 reference files. See `PORT_NOTES.md` for details. + +## Pi discovery paths + +Pi resolves skills from the following locations. Later sources override earlier +ones on name collision: + +- Global / user: `~/.pi/agent/skills/` and `~/.agents/skills/` +- Project: `.pi/skills/` and `.agents/skills/`, searched in the current working + directory and every parent up to the git root (ancestor discovery) +- Packages: a `skills/` directory or a `pi.skills` entry in `package.json` +- Settings: a `skills` array (files or directories) in Pi settings +- CLI: the `--skill <path>` flag (a skill file or directory; repeatable) + +Because this build emits `.agents/skills/`, dropping the `.agents` directory at +the root of any project (or any ancestor of where you run Pi, up to the git +root) makes every skill discoverable with no further configuration. + +## Install + +Copy the `.agents` directory into the root of your target project: + +``` +cp -r dist/pi/.agents <target-project>/ +``` + +Then run `pi` from anywhere inside that project. Skills are discovered +automatically via ancestor discovery. To verify discovery without committing +the directory, you can instead point Pi at the tree directly: + +``` +pi --skill dist/pi/.agents/skills/creative-brief +``` + +## Invoking a skill + +Pi loads skill descriptions into context at startup (progressive disclosure) +and loads the full `SKILL.md` on demand when a task matches. You can also invoke +a skill explicitly: + +``` +/skill:<name> +``` + +Arguments typed after the command are appended to the skill content as a user +message (`User: <args>`). For example: + +``` +/skill:creative-brief a landing page for a B2B onboarding tool +``` diff --git a/docs/architecture-mobile.jpg b/docs/architecture-mobile.jpg new file mode 100644 index 0000000..1ae2bda Binary files /dev/null and b/docs/architecture-mobile.jpg differ diff --git a/docs/architecture-wide.jpg b/docs/architecture-wide.jpg new file mode 100644 index 0000000..76a1ccb Binary files /dev/null and b/docs/architecture-wide.jpg differ diff --git a/docs/rampstack-complete-banner.jpg b/docs/rampstack-complete-banner.jpg new file mode 100644 index 0000000..08827f7 Binary files /dev/null and b/docs/rampstack-complete-banner.jpg differ diff --git a/og-card.png b/og-card.png new file mode 100644 index 0000000..b7863cf Binary files /dev/null and b/og-card.png differ diff --git a/scripts/build-pi.mjs b/scripts/build-pi.mjs new file mode 100644 index 0000000..49a95f1 --- /dev/null +++ b/scripts/build-pi.mjs @@ -0,0 +1,281 @@ +#!/usr/bin/env node +// build-pi.mjs - Build a Pi-compatible distribution of the skills catalog. +// +// Pi (pi.dev, github.com/earendil-works/pi) discovers skills from +// `.agents/skills/<name>/SKILL.md`. Pi accepts arbitrary frontmatter keys, +// so this build copies every source skill directory byte-for-byte into +// dist/pi/.agents/skills/ with native frontmatter preserved intact. No +// trimming, no sidecar (this is the key difference from the Codex and +// Antigravity dists, which trim frontmatter into a sidecar file). +// +// Dependency-free: Node ESM, fs and path only. +// +// Usage: +// node scripts/build-pi.mjs Build dist/pi/.agents/skills/ +// node scripts/build-pi.mjs --check Rebuild to a temp dir and diff +// against committed output; exit +// nonzero if anything differs. +// node scripts/build-pi.mjs --validate Validate emitted output against +// the Pi skill rules and source. + +import { + readdirSync, + readFileSync, + writeFileSync, + mkdirSync, + rmSync, + existsSync, +} from 'fs'; +import { fileURLToPath } from 'url'; +import { dirname, join, relative } from 'path'; + +const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = dirname(SCRIPT_DIR); +const SRC_SKILLS = join(REPO_ROOT, 'skills'); +const DIST_ROOT = join(REPO_ROOT, 'dist', 'pi'); +const DIST_SKILLS = join(DIST_ROOT, '.agents', 'skills'); + +// --- small fs helpers (sorted, deterministic) -------------------------------- + +function listDirsSorted(dir) { + return readdirSync(dir, { withFileTypes: true }) + .filter((e) => e.isDirectory()) + .map((e) => e.name) + .sort(); +} + +// Return all file paths under `dir`, relative to `dir`, sorted. Uses forward +// slashes so output is identical across platforms (determinism). +function listFilesSorted(dir) { + const out = []; + function walk(current) { + const entries = readdirSync(current, { withFileTypes: true }); + for (const e of entries) { + const full = join(current, e.name); + if (e.isDirectory()) walk(full); + else if (e.isFile()) out.push(relative(dir, full).split('\\').join('/')); + } + } + walk(dir); + return out.sort(); +} + +function copyFileBytes(srcFile, destFile) { + mkdirSync(dirname(destFile), { recursive: true }); + // Buffer copy: no encoding transform, byte-for-byte identical. + writeFileSync(destFile, readFileSync(srcFile)); +} + +// --- build -------------------------------------------------------------------- + +// Build the .agents/skills tree under `destSkills`. Returns counts. +function build(destSkills) { + // Clean target so removed source skills never linger (determinism). + if (existsSync(destSkills)) rmSync(destSkills, { recursive: true, force: true }); + mkdirSync(destSkills, { recursive: true }); + + const skills = listDirsSorted(SRC_SKILLS); + let referenceFiles = 0; + let skillFiles = 0; + + for (const name of skills) { + const srcDir = join(SRC_SKILLS, name); + const destDir = join(destSkills, name); + const files = listFilesSorted(srcDir); + for (const rel of files) { + copyFileBytes(join(srcDir, rel), join(destDir, rel)); + if (rel === 'SKILL.md') skillFiles++; + if (rel.startsWith('references/')) referenceFiles++; + } + } + + return { skills: skills.length, skillFiles, referenceFiles }; +} + +// --- check (staleness guard) -------------------------------------------------- + +function check() { + const tmp = join(REPO_ROOT, '.pi-check-tmp'); + if (existsSync(tmp)) rmSync(tmp, { recursive: true, force: true }); + const tmpSkills = join(tmp, '.agents', 'skills'); + build(tmpSkills); + + const committed = DIST_SKILLS; + if (!existsSync(committed)) { + console.error('FAIL: committed output not found at ' + rel(committed)); + rmSync(tmp, { recursive: true, force: true }); + process.exit(1); + } + + const freshFiles = new Set(listFilesSorted(tmpSkills)); + const committedFiles = new Set(listFilesSorted(committed)); + const differing = []; + + for (const f of freshFiles) { + if (!committedFiles.has(f)) { + differing.push('missing in committed: ' + f); + continue; + } + const a = readFileSync(join(tmpSkills, f)); + const b = readFileSync(join(committed, f)); + if (!a.equals(b)) differing.push('content differs: ' + f); + } + for (const f of committedFiles) { + if (!freshFiles.has(f)) differing.push('stale in committed (no source): ' + f); + } + + rmSync(tmp, { recursive: true, force: true }); + + if (differing.length) { + console.error('FAIL: committed dist/pi is stale. ' + differing.length + ' difference(s):'); + for (const d of differing) console.error(' ' + d); + process.exit(1); + } + console.log('PASS: committed dist/pi/.agents/skills matches a fresh build (byte-identical).'); +} + +// --- validate ----------------------------------------------------------------- + +// Parse the frontmatter block (between the first two `---` lines) into a flat +// map of top-level keys. Quotes are stripped from values for length checks. +function parseFrontmatter(text) { + const lines = text.split(/\r?\n/); + if (lines[0].trim() !== '---') return null; + let end = -1; + for (let i = 1; i < lines.length; i++) { + if (lines[i].trim() === '---') { + end = i; + break; + } + } + if (end === -1) return null; + const map = {}; + for (let i = 1; i < end; i++) { + const line = lines[i]; + const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s?(.*)$/); + if (!m) continue; + let val = m[2].trim(); + if ( + (val.startsWith('"') && val.endsWith('"')) || + (val.startsWith("'") && val.endsWith("'")) + ) { + val = val.slice(1, -1); + } + map[m[1]] = val; + } + return map; +} + +const PI_NAME_RE = /^[a-z0-9-]{1,64}$/; + +function validate() { + const results = []; + const pass = (label) => results.push(['PASS', label]); + const fail = (label) => results.push(['FAIL', label]); + // WARN is reported loudly but does not fail the run. Used where Pi itself + // only warns (and still loads the skill) and where this build is forbidden + // from fixing the source (preserve-native frontmatter, no trimming). + const warn = (label) => results.push(['WARN', label]); + + if (!existsSync(DIST_SKILLS)) { + console.error('FAIL: ' + rel(DIST_SKILLS) + ' does not exist. Run the build first.'); + process.exit(1); + } + + const emitted = listDirsSorted(DIST_SKILLS); + const source = listDirsSorted(SRC_SKILLS); + + // 1. Frontmatter validity + non-empty name/description. + const badFrontmatter = []; + const emptyFields = []; + // 2. Name rules. + const badNames = []; + // 3. Description length. + const longDescriptions = []; + + for (const name of emitted) { + const text = readFileSync(join(DIST_SKILLS, name, 'SKILL.md'), 'utf8'); + const fm = parseFrontmatter(text); + if (!fm) { + badFrontmatter.push(name); + continue; + } + if (!fm.name || !fm.name.trim()) emptyFields.push(name + ' (name)'); + if (!fm.description || !fm.description.trim()) emptyFields.push(name + ' (description)'); + + const n = fm.name || ''; + if (!PI_NAME_RE.test(n) || n.includes('--')) badNames.push(name + ' -> "' + n + '"'); + + if ((fm.description || '').length > 1024) { + longDescriptions.push(name + ' (' + fm.description.length + ' chars)'); + } + } + + if (badFrontmatter.length === 0) pass('Every emitted SKILL.md has valid --- frontmatter'); + else fail('Invalid frontmatter: ' + badFrontmatter.join(', ')); + + if (emptyFields.length === 0) pass('Every emitted SKILL.md has non-empty name and description'); + else fail('Empty name/description: ' + emptyFields.join(', ')); + + if (badNames.length === 0) pass('Every name conforms to Pi rules (lowercase a-z/0-9/hyphen, <=64, no consecutive hyphens)'); + else fail('Names violating Pi rules (reported, not renamed): ' + badNames.join('; ')); + + if (longDescriptions.length === 0) pass('Every description is <= 1024 chars'); + else warn('Descriptions over 1024 chars (Pi loads with a warning; preserved as-is from source, not trimmed): ' + longDescriptions.join(', ')); + + // 4. Emitted count equals source. + if (emitted.length === source.length) pass('Emitted skill count equals source (' + emitted.length + ')'); + else fail('Emitted count ' + emitted.length + ' != source count ' + source.length); + + // 5. Every source references file has an emitted counterpart. + const missingRefs = []; + let refTotal = 0; + for (const name of source) { + const srcRefDir = join(SRC_SKILLS, name, 'references'); + if (!existsSync(srcRefDir)) continue; + for (const rf of listFilesSorted(srcRefDir)) { + refTotal++; + const counterpart = join(DIST_SKILLS, name, 'references', rf); + if (!existsSync(counterpart)) missingRefs.push(name + '/references/' + rf); + } + } + if (missingRefs.length === 0) pass('Every source references file has an emitted counterpart (' + refTotal + ' files)'); + else fail('Missing emitted references: ' + missingRefs.join(', ')); + + // Report. + let failed = 0; + let warned = 0; + for (const [status, label] of results) { + console.log(status + ': ' + label); + if (status === 'FAIL') failed++; + if (status === 'WARN') warned++; + } + console.log(''); + const suffix = warned ? ' (' + warned + ' warning(s))' : ''; + console.log(failed === 0 ? 'VALIDATION PASS' + suffix : 'VALIDATION FAIL (' + failed + ' check(s) failed)'); + if (failed) process.exit(1); +} + +function rel(p) { + return relative(REPO_ROOT, p).split('\\').join('/'); +} + +// --- entrypoint --------------------------------------------------------------- + +const arg = process.argv[2]; + +if (arg === '--check') { + check(); +} else if (arg === '--validate') { + validate(); +} else if (arg) { + console.error('Unknown flag: ' + arg); + console.error('Usage: node scripts/build-pi.mjs [--check|--validate]'); + process.exit(2); +} else { + const { skills, skillFiles, referenceFiles } = build(DIST_SKILLS); + console.log('Pi build complete -> ' + rel(DIST_SKILLS)); + console.log(' skills copied: ' + skills); + console.log(' SKILL.md files copied: ' + skillFiles); + console.log(' reference files copied: ' + referenceFiles); +} diff --git a/scripts/crosslink_pass.py b/scripts/crosslink_pass.py new file mode 100644 index 0000000..d895aff --- /dev/null +++ b/scripts/crosslink_pass.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 +r"""One-shot script for the cross-linking pass. + +Convert plain-text mentions of ``references/X.md`` and ``SKILL.md`` into +markdown links so readers can navigate between SKILL.md and reference +files in rendered markdown (GitHub web view, README catalog). + +Patterns handled: + +1. In every ``skills/*/SKILL.md``, replace inline-code mentions + ``\`references/X.md\`` that are NOT already part of a markdown link + with ``[\`references/X.md\`](references/X.md)``. + +2. In every ``skills/*/references/*.md``, replace plain-text mentions + of ``SKILL.md`` that are NOT already part of a markdown link with + ``[SKILL.md](../SKILL.md)``. + +The ``skill-template.md`` template file is skipped for the SKILL.md +substitution because its mentions are templating instructions, not +references to a sibling SKILL.md. + +Run from the repo root: ``python scripts/crosslink_pass.py``. + +Idempotent: running twice produces the same result as running once. +Reports counts so the result can be diffed. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" + +# Files to skip for the SKILL.md -> [SKILL.md](../SKILL.md) substitution. +# The template file's mentions are templating instructions, not references. +SKIP_SKILL_LINK_FILES = { + SKILLS_DIR / "skill-creation-walkthrough" / "references" / "skill-template.md", +} + +# Pattern 1: ``\`references/X.md\`` that's NOT already preceded by ``[`` (which +# would mean it's the link text inside ``[\`references/X.md\`](references/X.md)``). +REF_INLINE_CODE_RE = re.compile( + r"(?<!\[)`(references/[a-z][a-z0-9-]*\.md)`" +) + +# Pattern 2: bare ``SKILL.md`` (not inline code, not a link target). Match a +# word-boundary before so we don't catch ``MYSKILL.md``. Skip mentions inside +# inline code spans (between backticks) and existing links. +SKILL_BARE_RE = re.compile( + r"(?<![`/\[\w-])SKILL\.md(?!\)|`)" +) + + +def link_references_in_skill_md(text: str) -> tuple[str, int]: + """Replace inline-code reference paths with markdown links.""" + count = 0 + + def replace(match: re.Match[str]) -> str: + nonlocal count + path = match.group(1) + count += 1 + return f"[`{path}`]({path})" + + return REF_INLINE_CODE_RE.sub(replace, text), count + + +def link_skill_md_in_reference(text: str) -> tuple[str, int]: + """Replace bare SKILL.md mentions with markdown links.""" + count = 0 + + def replace(match: re.Match[str]) -> str: + nonlocal count + count += 1 + return "[SKILL.md](../SKILL.md)" + + return SKILL_BARE_RE.sub(replace, text), count + + +def main() -> int: + if not SKILLS_DIR.exists(): + print(f"ERROR: {SKILLS_DIR} not found", file=sys.stderr) + return 1 + + skill_md_changes = 0 + skill_md_files_touched = 0 + skill_md_total = 0 + ref_changes = 0 + ref_files_touched = 0 + ref_total = 0 + + for skill_dir in sorted(SKILLS_DIR.iterdir()): + if not skill_dir.is_dir(): + continue + + # Pattern 1: SKILL.md + skill_md_path = skill_dir / "SKILL.md" + if skill_md_path.exists(): + skill_md_total += 1 + text = skill_md_path.read_text(encoding="utf-8") + new_text, count = link_references_in_skill_md(text) + if new_text != text: + skill_md_path.write_text(new_text, encoding="utf-8") + skill_md_files_touched += 1 + skill_md_changes += count + + # Pattern 2: references/*.md + ref_dir = skill_dir / "references" + if ref_dir.exists(): + for ref_path in sorted(ref_dir.iterdir()): + if not ref_path.is_file() or ref_path.suffix != ".md": + continue + ref_total += 1 + if ref_path in SKIP_SKILL_LINK_FILES: + continue + text = ref_path.read_text(encoding="utf-8") + new_text, count = link_skill_md_in_reference(text) + if new_text != text: + ref_path.write_text(new_text, encoding="utf-8") + ref_files_touched += 1 + ref_changes += count + + print( + f"SKILL.md pass: {skill_md_changes} replacements across " + f"{skill_md_files_touched} of {skill_md_total} files" + ) + print( + f"references pass: {ref_changes} replacements across " + f"{ref_files_touched} of {ref_total} files" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate_og_card.py b/scripts/generate_og_card.py new file mode 100644 index 0000000..8c47c32 --- /dev/null +++ b/scripts/generate_og_card.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 +"""Generate the GitHub Social Preview card (``og-card.png``) for this repo. + +Produces a 1280 by 640 PNG that GitHub displays when someone shares the +repo URL on Twitter, LinkedIn, Slack, etc. The output is committed to +the repo root; configuring GitHub's Social Preview is a separate manual +step (Settings to Social Preview to Upload). + +Design intent: + +- Brand-consistent palette matching rampstack.co (navy gradient base, + gold accent dot, cyan decorative pattern, white display type). +- Distinctive enough that the card does not read as the default GitHub + repo template; the dot grid on the right hints at catalog density + without being chartjunk. +- Single-line ASCII text only so it renders identically across the + fonts that ship with Pillow's bundled installations. + +Counts shown on the card are pulled live from the catalog, so the card +stays in sync as the catalog grows. Re-run after meaningful changes +(skill count change, walkthrough or integration count change). + +Run from the repo root:: + + python scripts/generate_og_card.py +""" + +from __future__ import annotations + +import os +import re +import sys +from pathlib import Path + +import numpy as np +from PIL import Image, ImageDraw, ImageFont + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" +OUTPUT = REPO_ROOT / "og-card.png" + +# Card dimensions: GitHub Social Preview recommended size. +WIDTH, HEIGHT = 1280, 640 + +# Brand palette. Hex values match rampstack.co (CSS custom properties +# in app/globals.css of the rampstackco-app repo). +BG_TOP = (15, 23, 42) # slate-900-ish +BG_BOTTOM = (21, 32, 70) # brand-navy +ACCENT = (255, 210, 125) # warm gold +CYAN = (59, 180, 224) # brand-cyan +INK = (248, 250, 252) # near-white +MUTED = (203, 213, 225) # slate-300 + +# Typography sizes. Tuned for 1280x640 against Arial which ships with +# Pillow on Windows; falls back to Arial-equivalent on other systems. +SIZE_EYEBROW = 26 +SIZE_TITLE = 100 +SIZE_SUBTITLE = 36 +SIZE_FOOTER = 24 + + +def find_font(weight_hints: list[str], size: int) -> ImageFont.ImageFont: + """Return the first available TrueType font from a hint list. + + Hints are font filenames searched against the system font path. If + none load, falls back to the PIL default bitmap font, which is + coarse but never throws. + """ + for name in weight_hints: + try: + return ImageFont.truetype(name, size) + except OSError: + continue + return ImageFont.load_default() + + +def gradient_background() -> Image.Image: + """Vertical linear gradient from BG_TOP to BG_BOTTOM.""" + top = np.array(BG_TOP, dtype=np.float32) + bottom = np.array(BG_BOTTOM, dtype=np.float32) + t = np.linspace(0.0, 1.0, HEIGHT, dtype=np.float32)[:, None] + rows = top * (1.0 - t) + bottom * t + arr = np.tile(rows[:, None, :], (1, WIDTH, 1)).astype(np.uint8) + return Image.fromarray(arr, mode="RGB") + + +def draw_dot_grid(canvas: Image.Image) -> None: + """Subtle dot grid on the right portion of the card. + + Draws a 14-column by 7-row matrix of small cyan circles, with + alpha-fading toward the left so the grid blends into the headline + region rather than competing with it. + """ + overlay = Image.new("RGBA", (WIDTH, HEIGHT), (0, 0, 0, 0)) + draw = ImageDraw.Draw(overlay) + + cols, rows = 14, 7 + grid_x_start = 760 # leaves room for headline on the left + grid_x_end = 1200 + grid_y_start = 80 + grid_y_end = 560 + radius = 5 + + col_step = (grid_x_end - grid_x_start) / (cols - 1) + row_step = (grid_y_end - grid_y_start) / (rows - 1) + + for c in range(cols): + x = grid_x_start + int(round(c * col_step)) + # Fade from 30 alpha on the left edge of the grid up to 90 on the right. + edge_t = c / (cols - 1) + alpha = int(round(30 + edge_t * 60)) + for r in range(rows): + y = grid_y_start + int(round(r * row_step)) + color = (CYAN[0], CYAN[1], CYAN[2], alpha) + draw.ellipse( + (x - radius, y - radius, x + radius, y + radius), + fill=color, + ) + + canvas.alpha_composite(overlay) + + +def count_skills() -> int: + """Walk skills/ and count folders that contain a SKILL.md. + + Avoids importing the README generator to keep this script + self-contained; the heuristic matches the linter's catalog count. + """ + if not SKILLS_DIR.exists(): + return 0 + return sum( + 1 + for child in SKILLS_DIR.iterdir() + if child.is_dir() and (child / "SKILL.md").exists() + ) + + +def count_walkthroughs() -> int: + """Read the rampstackco-app sibling repo for a live walkthrough count. + + Falls back to 0 if the sibling repo is not checked out next to this + one, which keeps the script runnable in CI clones that only fetch + claude-skills. + """ + sibling = REPO_ROOT.parent.parent / "rampstackco-app" / "app" / "walkthroughs" / "_data" / "walkthroughs.ts" + if not sibling.exists(): + return 0 + text = sibling.read_text(encoding="utf-8") + # Each walkthrough entry begins with ` slug: "..."`. Match those + # specifically rather than the generic `slug: ...` pattern that also + # appears in type definitions. + return len(re.findall(r"^ slug: \"[^\"]+\"", text, re.MULTILINE)) + + +def count_audience_tracks() -> int: + """Number of audience suite tiles on the rampstack.co homepage. + + Sourced from app/page.tsx in the sibling repo. Falls back to 6, + which matches the count at the time this script was written. + """ + sibling = REPO_ROOT.parent.parent / "rampstackco-app" / "app" / "page.tsx" + if not sibling.exists(): + return 6 + text = sibling.read_text(encoding="utf-8") + match = re.search(r"const SKILL_SUITES: SuiteCard\[\]\s*=\s*\[(.*?)\n\];", text, re.DOTALL) + if not match: + return 6 + return len(re.findall(r"^ \{$", match.group(1), re.MULTILINE)) + + +def main() -> int: + canvas = gradient_background().convert("RGBA") + draw_dot_grid(canvas) + draw = ImageDraw.Draw(canvas) + + # Type setting. + font_eyebrow = find_font(["arialbd.ttf", "DejaVuSans-Bold.ttf"], SIZE_EYEBROW) + font_title = find_font(["arialbd.ttf", "DejaVuSans-Bold.ttf"], SIZE_TITLE) + font_subtitle = find_font(["arial.ttf", "DejaVuSans.ttf"], SIZE_SUBTITLE) + font_footer = find_font(["arial.ttf", "DejaVuSans.ttf"], SIZE_FOOTER) + + skill_count = count_skills() + walkthrough_count = count_walkthroughs() + track_count = count_audience_tracks() + + eyebrow = "OPEN SOURCE - MIT LICENSED" + title_line_1 = "Brand Build Skills" + title_line_2 = "for Claude." + subtitle = ( + f"{skill_count} skills - {walkthrough_count} walkthroughs - " + f"{track_count} audience tracks" + ) + footer_left = "github.com/rampstackco/claude-skills" + footer_right = "rampstack.co" + + # Top-left accent dot + eyebrow. + pad_x = 80 + eyebrow_y = 80 + dot_radius = 7 + draw.ellipse( + (pad_x, eyebrow_y + 14, pad_x + dot_radius * 2, eyebrow_y + 14 + dot_radius * 2), + fill=ACCENT, + ) + # Tighten letter-tracking by drawing the eyebrow as one block; the + # text method already kerns reasonably for caps + spacing. + draw.text( + (pad_x + dot_radius * 2 + 16, eyebrow_y), + eyebrow, + fill=MUTED, + font=font_eyebrow, + ) + + # Headline. Two lines stacked so the display size stays comfortable + # inside the 1280-wide canvas without crowding the dot grid. + title_y = 180 + line_height = SIZE_TITLE + 12 + draw.text((pad_x, title_y), title_line_1, fill=INK, font=font_title) + draw.text((pad_x, title_y + line_height), title_line_2, fill=INK, font=font_title) + + # Subtitle stat strip. + subtitle_y = title_y + line_height * 2 + 30 + draw.text((pad_x, subtitle_y), subtitle, fill=MUTED, font=font_subtitle) + + # Footer row. + footer_y = HEIGHT - 60 + draw.text((pad_x, footer_y), footer_left, fill=INK, font=font_footer) + # Right-align the rampstack.co mark. + bbox = draw.textbbox((0, 0), footer_right, font=font_footer) + text_width = bbox[2] - bbox[0] + draw.text( + (WIDTH - pad_x - text_width, footer_y), + footer_right, + fill=INK, + font=font_footer, + ) + + # Output. + canvas.convert("RGB").save(OUTPUT, "PNG", optimize=True) + print( + f"Wrote {OUTPUT.relative_to(REPO_ROOT)} " + f"({skill_count} skills, {walkthrough_count} walkthroughs, " + f"{track_count} audience tracks)" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate_readme_catalog.py b/scripts/generate_readme_catalog.py new file mode 100644 index 0000000..66eef2c --- /dev/null +++ b/scripts/generate_readme_catalog.py @@ -0,0 +1,532 @@ +#!/usr/bin/env python3 +"""Generate README.md catalog content from skill folder metadata. + +Walks ``skills/`` and parses each ``SKILL.md`` frontmatter for the fields +``name``, ``description``, ``category``, ``catalog_summary``, and +``display_order``. Produces the README catalog section, the skill count +badge, the subtitle blockquote, the "What you get" counts, the catalog +header, the table-of-contents anchor, the catalog intro line, and a +handful of inline skill counts (install block, install-all paragraph, +hub paragraph, family-table claude-skills row, contributing paragraph) +that are substituted via anchored regex rather than marker pairs. + +Two operating modes: + + --check Exit 0 if README is in sync with skill metadata. Exit 2 with + a unified diff if README is stale. + --write Update README.md in place between marker comments. Print a + one-line summary on success. + +Run from the repo root: ``python scripts/generate_readme_catalog.py --check``. + +Markers in README.md: + +  ...  +  ...  +  ...  +  ...  +  ...  +  ...  +  ...  +  ...  +  ...  +""" + +from __future__ import annotations + +import argparse +import re +import sys +from dataclasses import dataclass +from difflib import unified_diff +from pathlib import Path + +try: + import yaml +except ImportError: + print("ERROR: PyYAML is required. Install with: pip install pyyaml", file=sys.stderr) + sys.exit(1) + + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" +README = REPO_ROOT / "README.md" + + +# Canonical category order. Drives the README catalog section order and the +# allowed values for the ``category`` frontmatter field. Each tuple is +# (category_id, display_title, optional_intro_paragraph). +CATEGORIES: list[tuple[str, str, str | None]] = [ + ("strategy-and-discovery", "Strategy and discovery", None), + ("brand", "Brand", None), + ("design", "Design", None), + ("content", "Content", None), + ( + "seo-foundation", + "SEO foundation", + "Tool-agnostic SEO skills. These define the conceptual frameworks. " + "The SEO audit suite below adds the Ahrefs MCP-powered execution layer.", + ), + ( + "seo-audit-suite", + "SEO audit suite (Ahrefs MCP-powered)", + "End-to-end SEO audit workflows that pull data from the Ahrefs MCP " + "and produce concrete deliverables. These skills assume the Ahrefs " + "MCP is connected.", + ), + ("product", "Product", None), + ("development", "Development", None), + ("qa", "Quality assurance", None), + ("operations", "Operations", None), + ("growth", "Growth", None), + ( + "growth-tooling", + "Growth tooling", + "Interactive web tools that turn visitors into leads. Lead " + "magnets, calculators, quizzes, multi-step forms, chatbots, " + "and the cross-tool funnel architecture that orchestrates them.", + ), + ( + "marketing", + "Marketing", + "Paid media discipline: strategy, creative, and performance " + "analytics. Pairs with the paid media platforms in the " + "/integrations catalog at rampstack.co.", + ), + ("research", "Research", None), + ("cross-cutting", "Cross-cutting workflows", None), + ("process-and-team", "Process and team", None), +] +CATEGORY_IDS = {cid for cid, _, _ in CATEGORIES} + + +MARKERS = [ + "COUNT_INTRO", + "COUNT_WHATYOUGET", + "COUNT_TOC", + "FEATURED_SKILLS", + "SURFACES", + "COUNT_CATALOG_HEADER", + "COUNT_CATALOG_INTRO", + "CATALOG", +] + + +# Featured skills section: one entry-point skill per audience track. +# These six map to the audience tracks that the rampstack.co landing +# surfaces are organized around. Order matches the homepage suite tiles. +# Tuple shape: (track_label, slug, one-line blurb). +FEATURED_SKILLS_DATA: list[tuple[str, str, str]] = [ + ( + "Brand and creative", + "creative-direction", + "Four-axis brief (tone, aesthetic, audience, sensory ambition) that gives every downstream skill a coherent direction", + ), + ( + "PM, experimentation", + "experiment-design", + "From hypothesis to decision: sample size, duration, segment analysis, and the failure modes that produce wrong shipping calls", + ), + ( + "PM, gap-closing", + "feature-launch-playbook", + "The discipline of launching a feature well: positioning, internal alignment, customer comms, enablement, rollout, monitoring", + ), + ( + "Content", + "pillar-content-architecture", + "Hub-and-cluster topical authority: pillar selection, cluster planning, internal linking, refresh discipline", + ), + ( + "Marketing", + "landing-page-copy", + "Landing pages, sales pages, hero-to-CTA flow with copy that converts", + ), + ( + "Growth tooling", + "funnel-flow-architecture", + "Cross-tool conversion flows architected to match the audience and the funnel stage", + ), +] + + +# Surfaces section: explains the layered offering (open-source methodology + +# commercial flagship surfaces at rampstack.co). Static content; the URLs +# do not change with each catalog update. +SURFACES_CONTENT = """\ +This catalog is the open-source methodology layer. Commercial surfaces at [rampstack.co](https://rampstack.co) extend it: + +- **[Skills directory](https://rampstack.co/skills)**. Every skill on a curated landing surface with audience tracks, search, and category navigation. +- **[Walkthroughs](https://rampstack.co/walkthroughs)**. Multi-skill recipes that orchestrate skill clusters end-to-end. Use these when one skill is not enough and a packaged sequence is. +- **[Integrations directory](https://rampstack.co/integrations)**. Curated MCPs, APIs, and tooling that the skills hook into. +- **[Showcase](https://rampstack.co/showcase)**. Real brand sites built from these skills, with the brief that produced each one. + +The skills in this repository remain free, open-source, and stack-agnostic. The surfaces above are how the same methodology is delivered as a product.""" + + +@dataclass(frozen=True) +class Skill: + slug: str + name: str + description: str + category: str + catalog_summary: str + display_order: int | None + + +def parse_frontmatter(skill_md: Path) -> dict: + """Read SKILL.md and return its YAML frontmatter as a dict.""" + text = skill_md.read_text(encoding="utf-8") + match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", text, re.DOTALL) + if not match: + raise ValueError(f"{skill_md}: no YAML frontmatter delimited by --- markers") + data = yaml.safe_load(match.group(1)) + if not isinstance(data, dict): + raise ValueError(f"{skill_md}: frontmatter is not a YAML dict") + return data + + +def load_skills() -> list[Skill]: + """Walk SKILLS_DIR and return validated Skill records. + + Raises SystemExit with a list of validation errors if any skill is + missing required fields or has an unknown category. + """ + skills: list[Skill] = [] + errors: list[str] = [] + for entry in sorted(SKILLS_DIR.iterdir()): + if not entry.is_dir(): + continue + skill_md = entry / "SKILL.md" + if not skill_md.exists(): + continue + try: + fm = parse_frontmatter(skill_md) + except ValueError as exc: + errors.append(str(exc)) + continue + name = fm.get("name") + description = fm.get("description") + category = fm.get("category") + catalog_summary = fm.get("catalog_summary") + display_order = fm.get("display_order") + missing = [ + label + for label, value in ( + ("name", name), + ("description", description), + ("category", category), + ("catalog_summary", catalog_summary), + ) + if not value + ] + if missing: + errors.append( + f"{entry.name}: missing frontmatter fields: {', '.join(missing)}" + ) + continue + if category not in CATEGORY_IDS: + allowed = ", ".join(sorted(CATEGORY_IDS)) + errors.append( + f"{entry.name}: unknown category '{category}'. " + f"Allowed values: {allowed}" + ) + continue + desc_len = len(str(description)) + if desc_len > 1024: + errors.append( + f"{entry.name}: description is {desc_len} characters, " + f"exceeds the 1024-character portability cap (Codex CLI, Pi, " + f"and Antigravity reject longer descriptions)" + ) + continue + skills.append( + Skill( + slug=entry.name, + name=str(name), + description=str(description), + category=str(category), + catalog_summary=str(catalog_summary), + display_order=int(display_order) if display_order is not None else None, + ) + ) + if errors: + raise SystemExit("Skill frontmatter validation failed:\n " + "\n ".join(errors)) + return skills + + +def group_by_category(skills: list[Skill]) -> dict[str, list[Skill]]: + """Bucket skills by category id and sort within each bucket. + + Sort key: (display_order ascending, slug ascending). Skills without a + display_order sort to the end alphabetically. + """ + grouped: dict[str, list[Skill]] = {cid: [] for cid, _, _ in CATEGORIES} + for skill in skills: + grouped[skill.category].append(skill) + sentinel = 10_000 + for items in grouped.values(): + items.sort( + key=lambda s: (s.display_order if s.display_order is not None else sentinel, s.slug) + ) + return grouped + + +def count_reference_files() -> int: + """Count files under any skills/*/references/ directory, at any depth. + + Recurses into nested reference subdirectories (for example + references/by-vertical/) so every shipped reference file is counted, + including the ones below the top level of references/. + """ + total = 0 + for entry in sorted(SKILLS_DIR.iterdir()): + if not entry.is_dir(): + continue + ref_dir = entry / "references" + if not ref_dir.exists(): + continue + for ref in ref_dir.rglob("*"): + if ref.is_file(): + total += 1 + return total + + +def generate_catalog(grouped: dict[str, list[Skill]]) -> str: + """Build the full catalog markdown block: section headers and tables.""" + lines: list[str] = [] + for index, (cid, title, intro) in enumerate(CATEGORIES): + items = grouped.get(cid, []) + lines.append(f"### {title} ({len(items)})") + lines.append("") + if intro: + lines.append(intro) + lines.append("") + lines.append("| Skill | What it does |") + lines.append("|---|---|") + for skill in items: + lines.append( + f"| [`{skill.slug}`](skills/{skill.slug}/SKILL.md) | " + f"{skill.catalog_summary} |" + ) + if index < len(CATEGORIES) - 1: + lines.append("") + return "\n".join(lines) + + +def generate_badge(total: int) -> str: + return f"[![Skills](https://img.shields.io/badge/Skills-{total}-blue.svg)](#the-{total}-skill-catalog)" + + +def generate_intro_blockquote(total: int) -> str: + return ( + f"> {total} stack-agnostic skills covering brand, design, content, " + "SEO, dev, ops, growth, and research. Includes an Ahrefs MCP-powered " + "SEO audit suite. Use them on Next.js, WordPress, Shopify, Webflow, " + "plain HTML, or anything else." + ) + + +def generate_whatyouget(total: int, ref_total: int, cat_total: int) -> str: + return ( + f"- **{total} skills** across {cat_total} categories, every one " + "with a complete `SKILL.md` and at least one reference file\n" + f"- **{ref_total} reference files** (templates, checklists, decision " + "matrices, worked examples)" + ) + + +def generate_toc_link(total: int) -> str: + return f"- [The {total}-skill catalog](#the-{total}-skill-catalog)" + + +def generate_catalog_header(total: int) -> str: + return f"## The {total}-skill catalog" + + +def generate_catalog_intro(total: int) -> str: + return ( + f"All {total} skills are shipped. Each has a complete SKILL.md " + "plus at least one reference file (template, checklist, or playbook)." + ) + + +def generate_featured_skills(skills_by_slug: dict[str, Skill]) -> str: + """Build the Featured skills section as an intro line + markdown table.""" + missing = [slug for _, slug, _ in FEATURED_SKILLS_DATA if slug not in skills_by_slug] + if missing: + raise ValueError( + "Featured skills not found in catalog: " + ", ".join(missing) + ) + lines = [ + "Six entry-point skills, one per audience track. Run any of these standalone, or compose them with the rest of the catalog.", + "", + "| Skill | What it does |", + "|---|---|", + ] + for track, slug, blurb in FEATURED_SKILLS_DATA: + lines.append(f"| [`{slug}`](skills/{slug}/SKILL.md) ({track}) | {blurb} |") + return "\n".join(lines) + + +def generate_surfaces() -> str: + """Return the static Surfaces section body.""" + return SURFACES_CONTENT + + +def replace_block(text: str, marker: str, new_content: str) -> str: + """Replace the body between a START/END marker pair. + + The replacement body is sandwiched by single newlines, producing:: + +  + {new_content} +  + """ + pattern = re.compile( + rf"()(.*?)()", + re.DOTALL, + ) + matches = list(pattern.finditer(text)) + if not matches: + raise ValueError(f"Marker pair '{marker}' not found in README.md") + if len(matches) > 1: + raise ValueError(f"Marker pair '{marker}' appears more than once in README.md") + replacement = f"\\1\n{new_content}\n\\3" + return pattern.sub(replacement, text, count=1) + + +def replace_badge_count(text: str, total: int) -> str: + """Substitute the skill count in the Skills badge markdown. + + The badge sits inline inside a centered div alongside other badges. + A line that begins with an HTML comment triggers CommonMark's HTML + block (type 2) parsing, which prevents inline markdown from being + parsed on that line. Wrapping the badge with marker comments breaks + the badge rendering. Anchor on the unique full-badge markdown + pattern instead, so the substitution touches only the badge in the + centered div and leaves the TOC link and catalog header (which + have their own marker-based substitution) alone. + """ + badge_pattern = re.compile( + r"\[!\[Skills\]$https://img\.shields\.io/badge/Skills-(\d+)-blue\.svg$\]" + r"$#the-(\d+)-skill-catalog$" + ) + matches = list(badge_pattern.finditer(text)) + if not matches: + raise ValueError("Skills badge markdown pattern not found in README.md") + if len(matches) > 1: + raise ValueError("Skills badge markdown pattern appears more than once in README.md") + replacement = ( + f"[![Skills](https://img.shields.io/badge/Skills-{total}-blue.svg)]" + f"(#the-{total}-skill-catalog)" + ) + return badge_pattern.sub(replacement, text, count=1) + + +def replace_inline_count(text: str, pattern: str, total: int, label: str) -> str: + """Substitute a skill count embedded in prose or a code fence. + + The pattern must capture the text before the count as group 1 and the + text after as group 2, with the digits ungrouped between them. Asserts + the pattern matches exactly once so a drifted or duplicated anchor fails + loudly rather than silently mis-substituting. + """ + rx = re.compile(pattern) + matches = list(rx.finditer(text)) + if not matches: + raise ValueError(f"{label}: count pattern not found in README.md") + if len(matches) > 1: + raise ValueError(f"{label}: count pattern appears more than once in README.md") + return rx.sub(rf"\g<1>{total}\g<2>", text, count=1) + + +def render_readme(text: str, skills: list[Skill]) -> str: + """Apply all marker replacements and return the updated README content.""" + grouped = group_by_category(skills) + skills_by_slug = {s.slug: s for s in skills} + total = len(skills) + ref_total = count_reference_files() + cat_total = len(CATEGORIES) + text = replace_badge_count(text, total) + text = replace_inline_count(text, r"(# full catalog $)\d+( skills$)", total, "install-block count") + text = replace_inline_count(text, r"(You do not have to install all )\d+(\.)", total, "install-all count") + text = replace_inline_count(text, r"(already uses\. )\d+( skills at the center)", total, "hub count") + text = replace_inline_count(text, r"(Full catalog $you are here$ \| )\d+( \|)", total, "family-table count") + text = replace_inline_count(text, r"(authoring discipline used across all )\d+( skills)", total, "contributing count") + text = replace_block(text, "COUNT_INTRO", generate_intro_blockquote(total)) + text = replace_block( + text, "COUNT_WHATYOUGET", generate_whatyouget(total, ref_total, cat_total) + ) + text = replace_block(text, "COUNT_TOC", generate_toc_link(total)) + text = replace_block(text, "FEATURED_SKILLS", generate_featured_skills(skills_by_slug)) + text = replace_block(text, "SURFACES", generate_surfaces()) + text = replace_block(text, "COUNT_CATALOG_HEADER", generate_catalog_header(total)) + text = replace_block(text, "COUNT_CATALOG_INTRO", generate_catalog_intro(total)) + text = replace_block(text, "CATALOG", generate_catalog(grouped)) + return text + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Generate README catalog content from skill folder metadata." + ) + mode = parser.add_mutually_exclusive_group(required=True) + mode.add_argument( + "--check", + action="store_true", + help="Exit non-zero with a diff if README is stale.", + ) + mode.add_argument( + "--write", + action="store_true", + help="Update README.md in place between marker comments.", + ) + args = parser.parse_args() + + if not SKILLS_DIR.exists(): + print(f"ERROR: skills/ directory not found at {SKILLS_DIR}", file=sys.stderr) + return 1 + + try: + skills = load_skills() + except SystemExit as exc: + print(f"ERROR: {exc}", file=sys.stderr) + return 1 + + current = README.read_text(encoding="utf-8") + try: + updated = render_readme(current, skills) + except ValueError as exc: + print(f"ERROR: {exc}", file=sys.stderr) + return 1 + + if args.check: + if current == updated: + return 0 + diff = unified_diff( + current.splitlines(keepends=True), + updated.splitlines(keepends=True), + fromfile="README.md (current)", + tofile="README.md (generated)", + ) + sys.stdout.writelines(diff) + print( + "\nREADME catalog is stale. " + "Run: python scripts/generate_readme_catalog.py --write" + ) + return 2 + + # Write LF newlines explicitly so --write does not flip the file to + # CRLF on Windows, which would churn every line in the diff. + README.write_text(updated, encoding="utf-8", newline="\n") + ref_total = count_reference_files() + print( + f"Updated {len(MARKERS)} sections in README.md, " + f"{len(skills)} skills, {ref_total} reference files" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/accessibility-audit/SKILL.md b/skills/accessibility-audit/SKILL.md new file mode 100644 index 0000000..9a93d44 --- /dev/null +++ b/skills/accessibility-audit/SKILL.md @@ -0,0 +1,239 @@ +--- +name: accessibility-audit +description: "Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, accessibility report, fix accessibility, axe scan. Also triggers when accessibility issues have been reported and need systematic remediation." +category: development +catalog_summary: "WCAG compliance audit with remediation plan" +display_order: 3 +--- + +# Accessibility Audit + +Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant. + +This skill goes deeper than the accessibility checks in `qa-testing` and `design-standards`. Use this when accessibility itself is the goal. + +--- + +## When to use + +- Pre-launch accessibility verification +- Compliance preparation (ADA, EN 301 549, AODA, Section 508) +- Remediation after an audit finding or complaint +- Annual or quarterly accessibility health check +- Onboarding accessibility into a team that hasn't prioritized it before + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Component-level accessibility implementation (use `frontend-component-build`) +- Color contrast for design tokens (use `design-standards` or `brand-identity`) + +--- + +## Required inputs + +- The site or product under audit +- The scope (full site, specific section, specific user flow) +- The target standard (WCAG 2.1 AA is most common) +- Any specific concerns or known issues +- Tools available (automated scanners, screen readers, manual testing) + +--- + +## The framework: WCAG's 4 principles + +WCAG organizes accessibility around four principles. The audit covers each in depth. + +### 1. Perceivable + +Information and UI must be presentable in ways users can perceive. + +**Audit checks:** + +- **Text alternatives.** All non-decorative images have descriptive `alt` text. Decorative images use `alt=""`. Complex images (charts, infographics) have long descriptions. +- **Time-based media.** Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required. +- **Adaptable.** Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled. +- **Distinguishable.** Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted. + +### 2. Operable + +UI components and navigation must be operable. + +**Audit checks:** + +- **Keyboard accessible.** All functionality available via keyboard alone. No keyboard traps. Focus visible. +- **Enough time.** Time limits can be adjusted, paused, or extended. Auto-updating content can be paused. +- **Seizures and physical reactions.** No content that flashes more than 3 times per second. +- **Navigable.** Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive. +- **Input modalities.** Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives. + +### 3. Understandable + +Information and operation must be understandable. + +**Audit checks:** + +- **Readable.** Page language declared (`<html lang="...">`). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience. +- **Predictable.** Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly. +- **Input assistance.** Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission. + +### 4. Robust + +Content must be robust enough to work with current and future user agents. + +**Audit checks:** + +- **Compatible.** Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced. + +--- + +## Audit methodology + +### Stage 1: Automated scan + +Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest. + +**Tools:** +- axe DevTools (browser extension) +- Lighthouse (Chrome DevTools accessibility audit) +- WAVE (browser extension) +- Pa11y (CLI for batch scanning) + +**Output:** A list of automated findings, by page. + +### Stage 2: Manual keyboard testing + +Unplug the mouse. Navigate the priority user flows using only keyboard. + +**Test:** +- Tab and Shift+Tab move through interactive elements in logical order +- Enter activates buttons and links +- Space activates buttons (and toggles checkboxes) +- Arrow keys navigate within composite widgets (tabs, menus, listboxes) +- Escape dismisses modals, popovers, menus +- Focus is always visible +- Focus returns to a sensible place after modals or popovers close +- No keyboard trap (focus can always leave) + +**Document:** Any flow where keyboard navigation breaks down. + +### Stage 3: Screen reader testing + +Test with at least one real screen reader. Each combination has quirks. + +**Common combinations:** +- VoiceOver + Safari (macOS / iOS) +- NVDA + Firefox or Chrome (Windows) +- JAWS + Chrome (Windows; commercial but common in enterprise) +- TalkBack + Chrome (Android) + +**Test:** +- Page structure announced correctly (headings, landmarks) +- Form labels read with their inputs +- Errors announced when they appear +- Status changes announced (loading, success, error) +- Modal context announced when opened +- Images have meaningful alt text (or are correctly identified as decorative) + +### Stage 4: Visual testing + +Verify the visual aspects of accessibility. + +**Test:** +- Color contrast for all text/background pairs (use a contrast checker) +- UI element contrast (3:1 for icons, borders, focus rings) +- Color-blindness simulation (deuteranopia at minimum) +- Zoom to 200% - content remains usable, no horizontal scroll +- Reflow at 320px viewport +- Text spacing applied (line height, letter spacing) - no content cut off +- Motion can be reduced (`prefers-reduced-motion` honored) + +### Stage 5: Cognitive accessibility + +Often overlooked. Critical for inclusive products. + +**Test:** +- Reading level appropriate +- Instructions clear +- Error messages explain how to fix the error, not just that one occurred +- Forms allow correction before submission +- Time limits avoidable or extendable +- Important content not dependent on memory of prior pages + +--- + +## Workflow + +1. **Define scope.** Full site? Specific flows? Specific page templates? +2. **Run automated scans.** Document findings per page. +3. **Manual keyboard pass.** Test all priority flows. +4. **Screen reader pass.** Test with at least one combination. +5. **Visual checks.** Contrast, zoom, color blindness, motion. +6. **Cognitive checks.** Reading level, error handling, time limits. +7. **Score against WCAG.** Per success criterion (level A, AA, AAA). +8. **Prioritize findings.** Critical (blocks users), Important (degrades experience), Minor (polish). +9. **Write the report.** Use the template in [`references/audit-report-template.md`](references/audit-report-template.md). +10. **Build a remediation plan.** Sequenced fixes with effort and impact estimates. + +--- + +## Severity classification + +For prioritization: + +**Critical (P0):** +- Blocks an entire user flow for an assistive-tech user +- Renders a key page completely inaccessible +- Examples: form with no labels, modal without focus management, primary CTA not keyboard-accessible + +**Important (P1):** +- Significantly degrades the experience for assistive-tech users +- Examples: missing alt text on key images, low-contrast body text, error messages that don't announce + +**Minor (P2):** +- Affects edge cases or specific assistive technology combinations +- Examples: minor focus order issues, missing decorative alt attributes, edge case keyboard handling + +**Polish (P3):** +- Above-AA improvements that benefit accessibility but aren't compliance-blocking +- Examples: AAA contrast targets, additional reduced-motion variants, language attributes on inline foreign words + +--- + +## Failure patterns + +- **Automated scan only.** Catches 30 to 50 percent of issues. The remaining 50 to 70 percent are in keyboard, screen reader, and cognitive testing. +- **Testing only on the home page.** The home page is usually the most accessible. Bugs hide in deeper flows. +- **Treating accessibility as a one-time project.** Accessibility erodes with every deploy. Bake it into the development cycle. +- **Fixing without root cause.** Patching individual issues without understanding why they happened means new ones keep appearing. +- **Ignoring screen reader testing.** Hard to do well, easy to skip. Single biggest source of "we thought we were accessible" surprises. +- **Confusing AA and AAA.** AAA is rarely the right target. AA is the practical baseline for most products. +- **Treating accessibility as a designer or developer responsibility alone.** Content, product, QA, and leadership all need to participate. +- **Assuming compliance equals accessibility.** WCAG conformance is a floor, not a ceiling. Real users may still struggle. + +--- + +## Output format + +Default output is a comprehensive audit report at `accessibility-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools used, pages tested, screen readers used) +3. Findings by WCAG principle +4. Critical findings (P0) with specific URLs and fixes +5. Important findings (P1) +6. Minor findings (P2) +7. Polish (P3) +8. Remediation roadmap (sequenced and prioritized) +9. Appendices (full automated scan results, keyboard navigation notes, screen reader notes) + +Plus a remediation tracking spreadsheet with one row per finding. + +--- + +## Reference files + +- [`references/audit-report-template.md`](references/audit-report-template.md) - Full audit report template. +- [`references/wcag-quick-reference.md`](references/wcag-quick-reference.md) - Condensed WCAG 2.1 AA criteria with audit checks. +- [`references/aria-patterns.md`](references/aria-patterns.md) - Decision-grade ARIA patterns. Semantic-HTML-first principle, common interactive widgets (accordion, tabs, modal, toggle, disclosure, navigation), live regions, hiding patterns, labeling, state indicators, anti-patterns. diff --git a/skills/accessibility-audit/references/aria-patterns.md b/skills/accessibility-audit/references/aria-patterns.md new file mode 100644 index 0000000..b74fc67 --- /dev/null +++ b/skills/accessibility-audit/references/aria-patterns.md @@ -0,0 +1,471 @@ +# ARIA patterns reference + +Decision-grade ARIA patterns for the audit. Covers when to use ARIA, when to skip it, and the common patterns that recur across web products. + +ARIA is powerful and easy to misuse. The most common mistake is reaching for ARIA when semantic HTML would have done the job already. The second most common mistake is applying ARIA without the supporting JavaScript that makes the attribute true (e.g., `aria-expanded="false"` on a button that does not actually toggle anything). + +This file expands the audit checks in [SKILL.md](../SKILL.md) with the specific patterns auditors should verify and the anti-patterns to flag. + +--- + +## The semantic-HTML-first principle + +Before reaching for ARIA, check whether semantic HTML already does what is needed. + +**The principle.** ARIA exists to fill gaps in HTML. When semantic HTML provides the same semantics natively, the semantic element is the right answer. Adding ARIA on top of semantic HTML is usually redundant and sometimes broken. + +**Examples of redundant ARIA.** + +- `<button role="button">` is redundant; the element is already a button. +- `<nav role="navigation">` is redundant; `<nav>` already has the role. +- `<a href="..." role="link">` is redundant; the element is already a link. +- `<input type="checkbox" role="checkbox">` is redundant. + +**Examples of correct ARIA.** + +- A `<div>` styled to behave like a button needs `role="button"`. A real `<button>` does not. +- A custom dropdown built on `<div>`s needs `role="combobox"` plus full keyboard handling. A `<select>` does not. +- A live status region needs `role="status"` or `aria-live`. A static element does not. + +**The audit check.** For every ARIA attribute on a page, ask: would this element have the same semantics without ARIA? If yes, the ARIA is redundant; flag it. + +**The first ARIA rule.** No ARIA is better than bad ARIA. Bad ARIA actively confuses assistive technology; missing ARIA at most leaves a feature inaccessible (which is bad, but recoverable). Bad ARIA misrepresents the UI to the user, which is worse. + +--- + +## Interactive widget patterns + +Patterns that recur across products. + +### Accordion (expandable disclosure section) + +**Required ARIA.** + +- Trigger button: `aria-expanded="true"` or `aria-expanded="false"` reflecting state. +- Trigger button: `aria-controls="<id-of-panel>"` pointing to the controlled region. +- Panel: `id="<the-id>"` matching `aria-controls`. + +**Required behavior.** + +- Trigger is a `<button>` (not a `<div>` or `<a>`). +- Trigger toggles `aria-expanded` when activated. +- Click and keyboard (Enter, Space) both work. + +**Audit checks.** + +- `aria-expanded` reflects current state, not a stale value. +- `aria-controls` ID exists in the DOM. +- Multiple accordions on a page: focus stays on trigger after toggle (does not jump unexpectedly). + +### Tabs + +**Required ARIA.** + +- Tab list: `role="tablist"`. +- Each tab: `role="tab"`, `aria-selected="true"` or `aria-selected="false"`, `aria-controls="<panel-id>"`. +- Each panel: `role="tabpanel"`, `id="<panel-id>"`, `aria-labelledby="<tab-id>"`. + +**Required behavior.** + +- Arrow keys move between tabs. +- Tab key moves into and out of the tablist (not between tabs). +- Selected tab has `tabindex="0"`; non-selected tabs have `tabindex="-1"` (roving tabindex). +- Activating a tab updates `aria-selected` and shows the corresponding panel. + +**Audit checks.** + +- All tabs reachable via arrow keys. +- Tab key escapes the tablist after one press. +- Only one tab has `aria-selected="true"` at a time. + +### Modal / dialog + +**Required ARIA.** + +- Container: `role="dialog"` (or `role="alertdialog"` for confirmations). +- Container: `aria-modal="true"` when modal. +- Container: `aria-labelledby="<heading-id>"` pointing to the dialog's heading, or `aria-label="<purpose>"`. +- Optional: `aria-describedby="<description-id>"` pointing to descriptive content. + +**Required behavior.** + +- Focus moves into the modal when opened (typically to the first focusable element or the dialog itself). +- Focus is trapped within the modal while open (Tab cycles within; cannot escape). +- Escape closes the modal. +- Focus returns to the triggering element when the modal closes. +- Background content has `inert` attribute or `aria-hidden="true"` (and is not focusable). + +**Audit checks.** + +- Focus management on open and close (the most common modal failure). +- Tab does not escape into background content. +- Screen reader does not read background content while modal is open. + +### Toggle button (button that holds state) + +**Required ARIA.** + +- `aria-pressed="true"` or `aria-pressed="false"` reflecting state. + +**Examples.** Mute button, favorite button, bold/italic in a text editor. + +**Audit checks.** + +- `aria-pressed` reflects state, not a stale value. +- Toggling produces an audible state change (some screen readers announce the new pressed state). +- Use of toggle button is appropriate (the button is genuinely a toggle, not a momentary action). + +### Disclosure widget (show/hide additional content) + +**Required ARIA.** + +- Trigger: `<button>` with `aria-expanded="true"` or `aria-expanded="false"`. +- Optional: `aria-controls="<region-id>"` if the controlled region is not adjacent. + +**Examples.** "Show more" buttons, "Read more" expansions. + +**Difference from accordion.** Accordions are typically grouped (multiple panels in a related set, often only one open at a time); disclosure widgets are standalone reveals. The ARIA is similar; the surrounding pattern differs. + +### Navigation + +**Required ARIA.** + +- `<nav>` element (semantic; no `role="navigation"` needed). +- For multiple navs on a page: each `<nav>` should have `aria-label` or `aria-labelledby` to distinguish them ("Primary", "Footer", "Breadcrumb"). +- Current page link: `aria-current="page"`. + +**Audit checks.** + +- Multiple navs are distinguishable to screen readers. +- The current page is identified. +- Skip link is present and works (typically "Skip to main content"). + +--- + +## Live region patterns + +Regions that announce dynamically. + +### aria-live + +**Values.** + +- `aria-live="polite"`: announces when the user is idle. Most common. +- `aria-live="assertive"`: announces immediately, interrupting the user. Use sparingly. +- `aria-live="off"`: do not announce. Default; rarely set explicitly. + +**The polite-vs-assertive choice.** + +- Polite for status updates that can wait (form save confirmation, content updates). +- Assertive for urgent messages (errors that block submission, session timeout warnings, security alerts). + +**Anti-pattern.** Assertive on routine updates. The screen reader interrupts whatever the user was doing; trust degrades quickly. + +### aria-atomic + +`aria-atomic="true"` tells screen readers to announce the entire region when any part changes, not just the changed part. + +**When to use.** When the announcement only makes sense in context (e.g., "5 of 10 items processed" should announce as a whole, not just "5"). + +**When not to use.** For long regions where atomic announcements would be repetitive. + +### role="status" + +Implicit `aria-live="polite"`. Use for non-urgent status messages. + +**Examples.** "Item added to cart," "Form saved," "Loading complete." + +### role="alert" + +Implicit `aria-live="assertive"` and `aria-atomic="true"`. Use for urgent messages. + +**Examples.** Form submission errors, session timeout warnings, security alerts. + +**Audit checks.** + +- Status and alert regions exist where needed (audit dynamic flows). +- They announce when content changes (test with screen reader). +- The region is not assertive when polite would do. +- The region is not used for static content (status/alert are for dynamic announcements). + +--- + +## Hiding from screen reader patterns + +When and how to hide content. + +### aria-hidden + +`aria-hidden="true"` removes the element and its children from the accessibility tree. + +**When to use.** + +- Decorative icons that have an adjacent text label (the icon is redundant; hide it). +- Background visual elements that have no semantic meaning. +- Modal closed state (when not using `inert`). + +**When NOT to use.** + +- On focusable elements. A focusable element with `aria-hidden="true"` produces a confusing experience: keyboard users can focus it, but screen readers will not announce it. +- On meaningful content. If the content is meaningful enough to render visually, it is meaningful enough to announce. +- On entire interactive widgets. The keyboard user can still tab into them; the screen reader cannot announce them. + +**Audit check.** For every `aria-hidden="true"`, verify the element is not focusable and contains no focusable descendants. The combination is the most common ARIA bug. + +### Visually-hidden CSS class + +A CSS pattern that hides content visually but keeps it in the accessibility tree. + +**Common implementation.** + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +**When to use.** + +- Skip links that should be invisible until focused. +- Form labels that the design hides but accessibility requires. +- Additional context for screen reader users (e.g., "Item 3 of 10 in shopping cart"). + +**Anti-pattern.** Using `display: none` or `visibility: hidden` for content that should remain in the accessibility tree. Both remove from the tree; visually-hidden does not. + +--- + +## Description and labeling patterns + +How to give elements accessible names and descriptions. + +### aria-label + +Provides an accessible name when no visible label exists. + +**When to use.** + +- Icon-only buttons (`<button aria-label="Close">`). +- Generic links that need context (`<a aria-label="Read more about pricing" href="...">Read more</a>`). +- Form inputs without visible labels (rare; usually a visible label is better). + +**When not to use.** + +- When a visible `<label>` exists. The visible label is the accessible name. +- For decorative content. Use `aria-hidden` instead. + +### aria-labelledby + +Points to one or more existing elements whose text becomes the accessible name. + +**When to use.** + +- When the visible label is in another element (e.g., a `<legend>` for a fieldset). +- When the accessible name comes from multiple elements (e.g., "Add to cart" combined with the product name). +- For dialogs labeled by their heading. + +**Syntax.** `aria-labelledby="id1 id2"` (space-separated IDs; the names concatenate). + +### aria-describedby + +Points to one or more existing elements whose text becomes the accessible description (announced after the name and role). + +**When to use.** + +- Form fields with help text that should announce after the label. +- Buttons with secondary explanation. +- Errors associated with form inputs (`aria-describedby="error-id"`). + +**Syntax.** Same as `aria-labelledby`. + +**The labeling priority.** Browsers compute the accessible name in this priority order: `aria-labelledby` > `aria-label` > `<label>` > placeholder/title (last-resort and unreliable). The accessible description follows: `aria-describedby` > `title`. + +--- + +## State indicator patterns + +ARIA attributes for component state. + +### aria-busy + +`aria-busy="true"` tells assistive tech that the element is in a transitional state (e.g., loading). + +**When to use.** + +- Sections being updated dynamically. +- Long-running operations where partial content would be confusing. + +**Audit check.** `aria-busy` is removed when the operation completes. + +### aria-disabled + +`aria-disabled="true"` indicates an element is disabled. + +**When to use vs `disabled` attribute.** + +- Native HTML `disabled` removes the element from the tab order and prevents interaction. +- `aria-disabled="true"` keeps the element focusable but indicates disabled state. Useful when you want users to focus and read why the element is disabled, but cannot activate it. + +**Audit check.** When using `aria-disabled`, the element should still appear disabled visually and click handlers should be suppressed. + +### aria-invalid + +`aria-invalid="true"` indicates a form input has a validation error. + +**When to use.** + +- After validation finds an error. +- Combined with `aria-describedby` pointing to the error message. + +**Audit check.** `aria-invalid` is set/cleared as validation state changes; not a stale attribute. + +--- + +## Common ARIA anti-patterns + +Patterns to flag in the audit. + +### Overusing roles on semantic elements + +**Pattern.** `<button role="button">`, `<nav role="navigation">`, `<a role="link">`. + +**Why it fails.** Redundant; clutters markup; sometimes overrides correct semantics. + +**Cure.** Remove the redundant role. + +### ARIA without supporting behavior + +**Pattern.** `aria-expanded="false"` on a button that has no JavaScript to toggle it. + +**Why it fails.** The attribute lies; assistive tech reports state that does not match reality. + +**Cure.** Either implement the behavior or remove the attribute. + +### Focusable element with aria-hidden + +**Pattern.** A `<button>` or `<a>` with `aria-hidden="true"`. + +**Why it fails.** Keyboard users can focus it; screen readers ignore it. The user encounters a focused element with no announcement. + +**Cure.** Either remove `aria-hidden` (if the element is meaningful) or remove from tab order with `tabindex="-1"` and disable interaction. + +### Modal without focus management + +**Pattern.** `role="dialog"` opens; focus stays on the triggering element behind the modal. + +**Why it fails.** Screen reader users do not realize a modal opened. Keyboard users can tab into background content. + +**Cure.** Move focus into the modal on open. Trap focus while open. Return focus to trigger on close. + +### Live region without dynamic updates + +**Pattern.** Static `<div role="status">Loading complete</div>` rendered in initial HTML. + +**Why it fails.** Live regions only announce when their content changes after page load. Static content in a live region announces nothing. + +**Cure.** Either remove the role (if the content is static) or update the content dynamically. + +### Assertive live region for routine updates + +**Pattern.** `role="alert"` on every form-save confirmation. + +**Why it fails.** Each confirmation interrupts whatever the user was doing. Trust degrades quickly. + +**Cure.** Use `role="status"` (polite) for non-urgent updates; reserve `role="alert"` for urgent messages. + +### Form input without accessible name + +**Pattern.** `<input type="text">` with placeholder but no label. + +**Why it fails.** Screen reader announces "edit" or similar generic; user does not know what the input is for. Placeholder disappears when typing, removing context. + +**Cure.** Add a visible `<label>` (preferred) or `aria-label`. Placeholder is not a label. + +### Error message not associated with input + +**Pattern.** Error text appears near a form input but no programmatic association. + +**Why it fails.** Screen reader users do not hear the error when focused on the input. + +**Cure.** Use `aria-describedby="error-id"` on the input, with the error message in an element with that ID. Optionally add `aria-invalid="true"`. + +### Tab order broken by tabindex + +**Pattern.** Positive `tabindex` values (`tabindex="1"`, `tabindex="2"`) used to control order. + +**Why it fails.** Positive tabindex creates a separate tab order that often conflicts with DOM order; very brittle; almost always wrong. + +**Cure.** Use `tabindex="0"` to add to natural order, `tabindex="-1"` to remove from natural order. Avoid positive values. + +--- + +## ARIA in audit reports + +What to flag in audit findings. + +**Per finding, document:** + +- The element (URL plus selector or screenshot). +- The current ARIA (or its absence). +- The behavior observed. +- The behavior expected. +- The fix. + +**Severity calibration.** + +- Modal without focus management: P0 (blocks assistive-tech users). +- Form input without accessible name: P0. +- Live region using assertive for routine updates: P1. +- Redundant `role="button"` on a `<button>`: P3 (cosmetic, but trims technical debt). + +The severity tracks user impact, not specification adherence per se. A redundant role does not block users; a missing label does. + +--- + +## ARIA testing approach + +How auditors verify ARIA. + +**Tooling.** + +- Browser DevTools accessibility tree (Chrome, Firefox, Safari) shows what assistive tech sees. +- axe DevTools flags many ARIA misuses. +- Screen reader testing is the ultimate verification. + +**Common verification steps.** + +- Inspect the accessibility tree for each interactive component. +- Verify dynamic ARIA attributes change when state changes. +- Verify focus management on open/close patterns (modals, menus, popovers). +- Test with at least one screen reader to hear what users hear. + +The accessibility tree (DevTools) often reveals issues invisible to automated scanners. Make it part of the audit. + +--- + +## ARIA references + +Beyond this file. + +- W3C ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/. Patterns and examples. +- WAI-ARIA 1.2 specification: https://www.w3.org/TR/wai-aria-1.2/. Canonical reference. +- The W3C ARIA Roles, States, and Properties listing: https://www.w3.org/TR/wai-aria-1.2/#role_definitions. Searchable. + +The APG is the most practical resource. Most patterns in this file are simplified summaries of APG patterns; for production implementation, consult the APG examples. + +--- + +## Methodology-level choices that stay in the public skill + +The semantic-HTML-first principle. Required ARIA and behavior for common interactive patterns (accordion, tabs, modal, toggle button, disclosure, navigation). Live region patterns (aria-live, aria-atomic, role="status", role="alert"). Hiding patterns (aria-hidden, visually-hidden CSS). Description and labeling patterns (aria-label, aria-labelledby, aria-describedby). State indicators (aria-busy, aria-disabled, aria-invalid). Common anti-patterns. ARIA in audit reports. ARIA testing approach. References. + +## Implementation choices that stay internal + +Specific component implementations in the team's framework. Specific JavaScript and class-name conventions for live regions, focus management, and ARIA toggling. Specific design-system patterns for dialogs, tabs, and accordions. The team's ARIA testing protocols and tooling configurations. These vary by team and stack. diff --git a/skills/accessibility-audit/references/audit-report-template.md b/skills/accessibility-audit/references/audit-report-template.md new file mode 100644 index 0000000..42c8760 --- /dev/null +++ b/skills/accessibility-audit/references/audit-report-template.md @@ -0,0 +1,228 @@ +# Accessibility Audit Report Template + +A fillable accessibility audit template. Customize the level (AA, AAA, EN 301 549) and scope (page, component, site) per project. + +--- + +## Audit metadata + +**Audited:** [URL or component name] +**Date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Compliance target:** [WCAG 2.1 AA / WCAG 2.1 AAA / EN 301 549] +**Scope:** [What was and was not tested] +**Methodology:** [Tools used, manual tests performed] + +--- + +## Executive summary + +[2 to 3 paragraph overview. The state of accessibility, the most important issues, the recommended path forward.] + +**Issue counts:** + +| Severity | Count | +|---|---| +| Critical | | +| Major | | +| Minor | | +| **Total** | | + +**Top 3 priorities:** + +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Tools and methods used + +**Automated:** +- [ ] axe DevTools +- [ ] Lighthouse accessibility audit +- [ ] WAVE +- [ ] Pa11y (or other CI tool) + +**Manual:** +- [ ] Keyboard-only navigation +- [ ] Screen reader: [NVDA / JAWS / VoiceOver / TalkBack] +- [ ] 200% zoom +- [ ] Mobile reflow at 320px width +- [ ] Color blindness simulation +- [ ] Windows High Contrast (or browser equivalent) +- [ ] Reduced motion preference + +--- + +## Critical findings + +Findings that block usage for some users. Must be fixed before sign-off. + +### Critical 1: [Issue name] + +- **WCAG criterion:** [e.g., 2.1.1 Keyboard] +- **Severity:** Critical +- **Affected users:** [Keyboard / screen reader / low vision / etc.] +- **Reproduction steps:** + 1. [Step] + 2. [Step] + 3. [Step] +- **Expected:** [What should happen] +- **Actual:** [What does happen] +- **Recommended fix:** [Specific solution] +- **Estimated effort:** [Hours / days] +- **Owner:** [Team or person] + +### Critical 2: [Issue name] + +[Same structure] + +--- + +## Major findings + +Findings that significantly degrade experience. Should be fixed before broad launch. + +### Major 1: [Issue name] + +[Same structure as critical] + +### Major 2: [Issue name] + +[Same structure] + +--- + +## Minor findings + +Findings that add friction without blocking. Tracked and addressed in normal iteration. + +### Minor 1: [Issue name] + +[Brief structure] + +- **WCAG criterion:** +- **Issue:** +- **Recommended fix:** + +--- + +## WCAG 2.1 AA scorecard + +For full audits, score each criterion. For partial audits, score only those in scope. + +### 1. Perceivable + +| Criterion | Pass / Fail / N/A | Notes | +|---|---|---| +| 1.1.1 Non-text content | | | +| 1.2.1 Audio-only and video-only | | | +| 1.2.2 Captions (prerecorded) | | | +| 1.2.3 Audio description or media alternative | | | +| 1.2.4 Captions (live) | | | +| 1.2.5 Audio description (prerecorded) | | | +| 1.3.1 Info and relationships | | | +| 1.3.2 Meaningful sequence | | | +| 1.3.3 Sensory characteristics | | | +| 1.3.4 Orientation | | | +| 1.3.5 Identify input purpose | | | +| 1.4.1 Use of color | | | +| 1.4.2 Audio control | | | +| 1.4.3 Contrast (minimum) | | | +| 1.4.4 Resize text | | | +| 1.4.5 Images of text | | | +| 1.4.10 Reflow | | | +| 1.4.11 Non-text contrast | | | +| 1.4.12 Text spacing | | | +| 1.4.13 Content on hover or focus | | | + +### 2. Operable + +| Criterion | Pass / Fail / N/A | Notes | +|---|---|---| +| 2.1.1 Keyboard | | | +| 2.1.2 No keyboard trap | | | +| 2.1.4 Character key shortcuts | | | +| 2.2.1 Timing adjustable | | | +| 2.2.2 Pause, stop, hide | | | +| 2.3.1 Three flashes or below threshold | | | +| 2.4.1 Bypass blocks | | | +| 2.4.2 Page titled | | | +| 2.4.3 Focus order | | | +| 2.4.4 Link purpose (in context) | | | +| 2.4.5 Multiple ways | | | +| 2.4.6 Headings and labels | | | +| 2.4.7 Focus visible | | | +| 2.5.1 Pointer gestures | | | +| 2.5.2 Pointer cancellation | | | +| 2.5.3 Label in name | | | +| 2.5.4 Motion actuation | | | + +### 3. Understandable + +| Criterion | Pass / Fail / N/A | Notes | +|---|---|---| +| 3.1.1 Language of page | | | +| 3.1.2 Language of parts | | | +| 3.2.1 On focus | | | +| 3.2.2 On input | | | +| 3.2.3 Consistent navigation | | | +| 3.2.4 Consistent identification | | | +| 3.3.1 Error identification | | | +| 3.3.2 Labels or instructions | | | +| 3.3.3 Error suggestion | | | +| 3.3.4 Error prevention (legal, financial, data) | | | + +### 4. Robust + +| Criterion | Pass / Fail / N/A | Notes | +|---|---|---| +| 4.1.1 Parsing | | | +| 4.1.2 Name, role, value | | | +| 4.1.3 Status messages | | | + +--- + +## Remediation roadmap + +Sequenced by severity and dependency. + +### Phase 1: Critical fixes (target: [date]) + +- [ ] [Critical 1] +- [ ] [Critical 2] + +### Phase 2: Major fixes (target: [date]) + +- [ ] [Major 1] +- [ ] [Major 2] + +### Phase 3: Minor fixes (target: [date]) + +- [ ] [Minor 1] +- [ ] [Minor 2] + +### Phase 4: Process improvements + +- [ ] Add automated a11y checks to CI +- [ ] Establish a11y review in PR process +- [ ] Train design and engineering teams on common failures +- [ ] Set up regular re-audit schedule + +--- + +## Re-audit schedule + +- **Verify critical fixes:** [Date, typically 1 to 2 weeks post-remediation] +- **Verify major fixes:** [Date, typically 4 weeks] +- **Full re-audit:** [Date, typically 6 to 12 months] +- **Trigger-based re-audit:** Significant design system updates, major feature launches + +--- + +## Sign-off + +Critical fixes verified by: [Name and date] +Major fixes verified by: [Name and date] +Final approval: [Name and date] diff --git a/skills/accessibility-audit/references/wcag-quick-reference.md b/skills/accessibility-audit/references/wcag-quick-reference.md new file mode 100644 index 0000000..4e4afd1 --- /dev/null +++ b/skills/accessibility-audit/references/wcag-quick-reference.md @@ -0,0 +1,250 @@ +# WCAG 2.1 AA Quick Reference + +A condensed list of WCAG 2.1 AA success criteria with the practical audit check for each. + +For the canonical specification, refer to W3C: https://www.w3.org/TR/WCAG21/ + +--- + +## Principle 1: Perceivable + +### 1.1 Text alternatives + +**1.1.1 Non-text content (A)** +- All meaningful images have descriptive `alt` text +- Decorative images have `alt=""` (empty alt) +- Complex images have long descriptions +- Form inputs have associated labels +- CAPTCHA has alternatives for users who cannot perceive it +- Audit check: scan for `<img>` without `alt`, run alt-text quality review + +### 1.2 Time-based media + +**1.2.1 Audio-only and video-only prerecorded (A)** +- Audio-only content has a transcript +- Video-only content (no audio) has a description or transcript + +**1.2.2 Captions prerecorded (A)** +- Pre-recorded video content has captions + +**1.2.3 Audio description or media alternative (A)** +- Pre-recorded video has audio description OR an alternative + +**1.2.4 Captions live (AA)** +- Live video content has captions + +**1.2.5 Audio description prerecorded (AA)** +- Pre-recorded video has audio description + +### 1.3 Adaptable + +**1.3.1 Info and relationships (A)** +- Structure conveyed through markup, not just visual styling +- Headings use `<h1>` through `<h6>`, not styled `<div>` +- Lists use `<ul>`, `<ol>`, `<li>` +- Tables use `<table>`, `<th>`, `<td>` correctly with `scope` attributes +- Form inputs have `<label>` associated via `for`/`id` or `aria-labelledby` + +**1.3.2 Meaningful sequence (A)** +- Reading order makes sense without CSS +- Audit check: disable CSS, read the page top to bottom + +**1.3.3 Sensory characteristics (A)** +- Instructions don't rely solely on shape, size, color, or position +- Audit check: avoid "click the green button" or "the button on the right" + +**1.3.4 Orientation (AA)** +- Content does not restrict view to a single orientation (portrait or landscape) + +**1.3.5 Identify input purpose (AA)** +- Form fields collecting user information use `autocomplete` attributes correctly + +### 1.4 Distinguishable + +**1.4.1 Use of color (A)** +- Color is not the only way information is conveyed +- Audit check: check error states, status indicators, chart elements + +**1.4.2 Audio control (A)** +- Audio that plays automatically for more than 3 seconds has pause/stop control + +**1.4.3 Contrast minimum (AA)** +- Normal text contrast ratio at least 4.5:1 +- Large text (18pt regular or 14pt bold) at least 3:1 +- Audit check: contrast checker on every text/background pair + +**1.4.4 Resize text (AA)** +- Text can be resized to 200% without loss of content or functionality +- Audit check: zoom to 200% in the browser, verify usability + +**1.4.5 Images of text (AA)** +- Use real text, not images of text, except for logos or where customization is essential + +**1.4.10 Reflow (AA)** +- Content can be presented without horizontal scrolling at 320px viewport +- Audit check: resize to 320px, verify no horizontal scroll + +**1.4.11 Non-text contrast (AA)** +- UI components and graphical objects at least 3:1 contrast ratio against adjacent colors +- Audit check: borders, icons, form field outlines, focus rings + +**1.4.12 Text spacing (AA)** +- No loss of content or functionality when text spacing is increased to specific minimums +- Audit check: apply line-height: 1.5, letter-spacing: 0.12em, word-spacing: 0.16em, paragraph-spacing: 2x font size + +**1.4.13 Content on hover or focus (AA)** +- Hover/focus tooltips can be dismissed, hovered, and persist until dismissed + +--- + +## Principle 2: Operable + +### 2.1 Keyboard accessible + +**2.1.1 Keyboard (A)** +- All functionality available from keyboard +- Audit check: navigate the entire site without a mouse + +**2.1.2 No keyboard trap (A)** +- Focus can always be moved away from any component using keyboard alone +- Audit check: open every modal, dropdown, widget; verify Tab can leave + +**2.1.4 Character key shortcuts (A)** +- If single-character keyboard shortcuts exist, they can be turned off, remapped, or only active on focus + +### 2.2 Enough time + +**2.2.1 Timing adjustable (A)** +- Time limits can be turned off, adjusted, or extended (with exceptions for real-time and essential) + +**2.2.2 Pause, stop, hide (A)** +- Auto-updating content can be paused or stopped (with exceptions for essential) + +### 2.3 Seizures and physical reactions + +**2.3.1 Three flashes or below threshold (A)** +- Nothing flashes more than 3 times per second + +### 2.4 Navigable + +**2.4.1 Bypass blocks (A)** +- Skip link present at the top of the page +- Or, use proper landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`) + +**2.4.2 Page titled (A)** +- Each page has a unique, descriptive `<title>` + +**2.4.3 Focus order (A)** +- Focus order matches visual and logical reading order + +**2.4.4 Link purpose in context (A)** +- Link purpose is clear from the link text alone, or from text + immediate surrounding context +- Avoid "click here," "read more," "learn more" without context + +**2.4.5 Multiple ways (AA)** +- Multiple ways to find content (sitemap, search, navigation menu) + +**2.4.6 Headings and labels (AA)** +- Headings and labels are descriptive + +**2.4.7 Focus visible (AA)** +- Keyboard focus indicator is visible +- Audit check: Tab through the page; can you always see where focus is? + +### 2.5 Input modalities + +**2.5.1 Pointer gestures (A)** +- Multipoint or path-based gestures have single-point alternative + +**2.5.2 Pointer cancellation (A)** +- Down-event does not trigger action; action triggers on up-event or has way to abort + +**2.5.3 Label in name (A)** +- Accessible name (for screen readers) contains the visible label text + +**2.5.4 Motion actuation (A)** +- Motion-triggered functionality has UI alternative and can be disabled + +--- + +## Principle 3: Understandable + +### 3.1 Readable + +**3.1.1 Language of page (A)** +- Page language declared in HTML: `<html lang="en">` + +**3.1.2 Language of parts (AA)** +- Inline foreign-language passages marked: `<span lang="fr">...</span>` + +### 3.2 Predictable + +**3.2.1 On focus (A)** +- Receiving focus does not change context (no auto-submit, no unexpected navigation) + +**3.2.2 On input (A)** +- Changing a setting does not automatically change context unless user is warned + +**3.2.3 Consistent navigation (AA)** +- Navigation appears in the same relative order across pages + +**3.2.4 Consistent identification (AA)** +- Components with the same function are identified consistently + +### 3.3 Input assistance + +**3.3.1 Error identification (A)** +- Errors are identified and described in text (not just color or icon) + +**3.3.2 Labels or instructions (A)** +- Labels or instructions provided for inputs requiring user input + +**3.3.3 Error suggestion (AA)** +- When errors occur and suggestions are known, suggestions are provided + +**3.3.4 Error prevention (legal, financial, data) (AA)** +- For pages causing legal commitments or financial transactions: submissions are reversible, checked for errors, OR confirmed before final submission + +--- + +## Principle 4: Robust + +### 4.1 Compatible + +**4.1.1 Parsing (A) [removed in 2.2 but still in 2.1]** +- Markup is well-formed (no duplicate IDs, properly nested elements) + +**4.1.2 Name, role, value (A)** +- For all UI components, name and role can be programmatically determined; states, properties, and values can be set +- Use semantic HTML, ARIA where needed + +**4.1.3 Status messages (AA)** +- Status messages can be programmatically determined through role or properties so they can be announced by assistive technology +- Use `role="status"`, `role="alert"`, or `aria-live` + +--- + +## Audit check summary + +For each criterion, the audit needs to: + +1. **Identify the requirement** (what does WCAG ask for?) +2. **Test against the site** (does the site meet it?) +3. **Document failures** (which pages, which elements, what's wrong) +4. **Specify the fix** (what specific change resolves it) +5. **Assign severity** (P0 critical, P1 important, P2 minor, P3 polish) +6. **Estimate effort** (small, medium, large) + +A complete audit covers all 30+ AA criteria. Most sites fail 5 to 15 of them on first audit. Don't try to fix all at once. Sequence by severity and impact. + +--- + +## What WCAG does NOT cover + +WCAG is a floor, not a ceiling. Some accessibility considerations are outside its scope: + +- **Cognitive accessibility nuances** (reading level, attention, memory) - some basics in 3.1, but limited +- **Audience-specific needs** (the cognitive support a user with dyslexia needs vs. a user with autism) +- **Mental models** (whether the navigation makes sense to your specific audience) + +For these, supplement WCAG with usability testing including users with disabilities, and with specific design patterns aimed at cognitive accessibility. diff --git a/skills/ads-creative-development/SKILL.md b/skills/ads-creative-development/SKILL.md new file mode 100644 index 0000000..7fb0a7b --- /dev/null +++ b/skills/ads-creative-development/SKILL.md @@ -0,0 +1,231 @@ +--- +name: ads-creative-development +description: "How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting." +category: marketing +catalog_summary: "Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter" +display_order: 2 +--- + +# Ads Creative Development + +A senior creative strategist's playbook for producing ad creative that performs. + +Performance creative is a different discipline from brand creative. Brand work optimizes for memorability, emotional resonance, and distinctive identity. Performance creative optimizes for stopping the scroll, communicating value in three seconds, and producing a click. Both matter. Mixing them up costs money. Brand creative running as performance ads bleeds budget; performance creative running as brand ads erodes equity. + +This skill is the discipline that produces performance creative without diluting brand. It assumes you know your audience and offer (see `paid-media-strategy`). It assumes you have brand-voice guidance (see `brand-voice`). The hard part is the systematic production of variations that test cleanly and ship without manual approval bottlenecks, and that is what is here. + +When to use this skill: producing ad creative for paid campaigns, planning a creative testing cycle, diagnosing creative fatigue, or auditing why creative is not converting. + +--- + +## What this skill is for + +This skill spans creative production, hook patterns, testing methodology, and fatigue diagnosis. It does not cover paid media strategy (use `paid-media-strategy`), result interpretation (use `ads-performance-analytics` once it ships), or brand voice authoring (use `brand-voice`). Pair this skill with the relevant integrations microsite for platform-specific MCP details and example prompts. + +The audience is an ad creative producer, a growth marketer responsible for creative testing, or an agency producing creative at scale. The voice is tactical. There is no "consider every option." Performance creative has shape, and a senior practitioner can map a brief to a production-ready variation matrix in an afternoon. + +--- + +## Performance vs brand creative + +The two disciplines optimize for different metrics. Brand creative optimizes for memorability, distinctiveness, and emotional resonance over months. Performance creative optimizes for scroll-stop in 1 second, value comprehension by 5 seconds, and click by 15. + +The shared layer. Both should reflect brand voice. Both should look like they came from the same brand. The difference is structure, pacing, and where the creative effort concentrates. + +The failure mode. Most agency creative tries to do both and does neither well. The brand video that runs as a 60-second performance ad has a strong narrative arc and zero CTR. The performance ad that ignores brand voice converts but trains the audience to not recognize the brand. The fix is not to compromise; it is to produce both, in their respective formats, with shared voice and divergent structure. + +A worked example. A premium coffee brand running a 60-second YouTube awareness ad gets to build the world: cinematography, the founder's hands, slow-pour rituals, music that sets a mood. That same brand running a 15-second Meta Reels performance ad gets 1 second to stop the scroll (a visual pattern interrupt: the steam rising from a cup, fast cut, brand logo dropping in), 4 seconds to clarify the offer (the new flavor, the price, the deal), 8 seconds for social proof (three customer-style testimonials, fast cuts), and 2 seconds for CTA (shop now, end card with logo). Same voice. Different structure. Different pacing. Different creative effort distribution. + +--- + +## Hook patterns: the first 3 seconds + +The biggest lever in performance creative. If the hook fails, no amount of body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. The hook is the whole game until the body justifies why the user kept watching. + +Twelve hook patterns work consistently. Detail in [`references/hook-pattern-library.md`](references/hook-pattern-library.md). + +1. **Problem-agitate-solve.** Open with the problem the audience feels. Agitate by naming the consequence. Solve with the offer. Works when the audience recognizes the pain. +2. **Direct callout to audience.** "If you are a B2B founder running paid ads..." Triggers self-identification. Works when the audience is narrow and self-aware. +3. **Contrarian claim.** "Stop using lookalike audiences." Hooks attention by violating expectation. Works when the audience has heard the conventional wisdom too often. +4. **Result-led.** "How we cut CAC 40% in 30 days." Specific number, specific timeframe. Works when the result is real and documented. +5. **Curiosity gap.** "The mistake 80% of marketers make..." Promises a payoff after the gap. Works when the gap is real; clickbait without payoff trains the audience to scroll past. +6. **Social proof at top.** "Used by 10,000+ teams." Validation before pitch. Works when the proof is impressive enough to do the heavy lifting. +7. **Visual pattern interrupt.** A surprising visual that does not match the platform's usual feed flow. Works on TikTok and Reels where the pattern is fast and the interrupt is louder. +8. **Question that hits intent.** "Tired of paying $400 for project management software?" The question pre-qualifies the audience. Works when the question matches a real search query the audience has typed. +9. **Number-led.** "3 changes that doubled our ROAS." Lists trigger the brain's pattern-completion instinct. Works for educational content; less so for product ads. +10. **Personal story open.** "Last year I was burning $50K a month on Meta ads with no return..." First-person specificity is hard to skip. Works when the story is real and the conclusion is action-relevant. +11. **Comparison.** "X vs Y: which actually works." Pits two options against each other. Works when the audience is in evaluation mode. +12. **Behind-the-scenes / process.** "How we onboard a new client in 7 days..." Demystifies the work. Works when the process is the differentiator. + +For each pattern, the anti-pattern is the same: a hook that does not actually hook. Generic openings ("In today's world...", brand-logo cards, slow zooms over title cards) train the audience to scroll past. The first second is for the hook. The brand can wait. + +--- + +## Format selection + +Different formats fit different combinations of audience, platform, and offer. + +- **Static image.** Best for simple value props, retargeting, and quick test cycles. Lowest production cost. Limited room for narrative. +- **Carousel.** Best for multi-feature products, educational content, and B2B SaaS. Each card carries one idea; users swipe through at their own pace. Strong for considered purchases. +- **Video (in-feed).** Best for demonstration, story, and broad audiences. Higher production cost. Performance correlates strongly with hook quality. +- **UGC-style video.** Best for trust building, social proof, and lower production cost. Looks like an ordinary user filmed it. Especially strong on TikTok and Reels. +- **Stories or Reels (vertical 9:16).** Best for TikTok, Instagram, and Snap. Native to the platform's primary surface. Skipping anything not vertical here is leaving performance on the table. +- **Spark Ads (boosted organic).** Best for TikTok. Promotes an existing organic post as an ad. Retains organic engagement signals; consistently outperforms pure paid creative on TikTok. + +The decision rule. Match format to platform native style and to audience consumption pattern. Detail in [`references/format-decision-matrix.md`](references/format-decision-matrix.md). + +--- + +## Video pacing + +Video performance correlates more with pacing than with production value. A well-paced phone-shot video outperforms a poorly-paced agency-produced spot. Specific guidance for the 15-second performance video. + +| Time window | Job | +|---|---| +| 0 to 1s | Hook. Visual pattern interrupt plus audio hook. | +| 1 to 3s | Clarify what this is. Brand and offer registered. | +| 3 to 7s | Value proposition. The problem-solution moment. | +| 7 to 12s | Social proof or demonstration. Show, do not just tell. | +| 12 to 15s | CTA. End card with logo and call to action. | + +Anything past 15 seconds in a performance video is awareness territory. Performance creative should resolve by 15s. + +Platform variations. TikTok performs at 15 to 30 seconds; the platform tolerates longer because the audience is in a longer dwell mode. Meta In-Feed performs at 15s. YouTube Shorts at 15 to 60s. Long-form YouTube at 30s+ for awareness, with the value prop still front-loaded. + +--- + +## Variation systems + +The systematic way to produce 20 to 50 ad variations from one core concept without manual creative authoring per variation. + +The decomposition. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. + +- 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. +- Most are not worth shipping. The matrix narrows to 20 to 40 variations the team will actually run. +- Asset library structure: organize by concept, not by date. `concepts/launch-2026/hooks/`, `concepts/launch-2026/bodies/`, etc. + +Naming convention. Use a structured naming system so the analyst can join performance data back to creative components. Example: `launch2026_meta-reel_hookA_bodyB_ctaC_v1`. The analyst pulls the report, joins on the naming components, and identifies which hook is winning across body and CTA combinations. + +Worked example in [`references/creative-variation-templates.md`](references/creative-variation-templates.md). A half-day production session produces 40 variations from one core concept by using the matrix. Without the matrix, the same 40 variations require five days of authoring overhead. + +--- + +## Sequential testing methodology + +The waterfall. Most teams test everything at once and lose the signal. Sequential testing isolates the variable that matters at each step. + +1. **Test hooks first.** 5 to 10 hook variants, same body, same CTA, same format. The hook is the biggest lever; isolate it first. +2. **Winners advance to body testing.** Top 2 to 3 hooks each get 5 to 10 body variants. Now you are testing what the audience watches after the hook lands. +3. **Winners advance to CTA testing.** Top hook plus body combinations each get 3 to 5 CTAs. Smaller search space at this stage; the differences are usually marginal. +4. **Winners advance to format testing.** Top combinations each render in 2 to 3 formats (vertical video, carousel, static). Catches format-specific drop-offs. +5. **Top combos go into evergreen rotation.** Two to four winners run on rotation. Refresh on the cadence below. + +The common mistake. Testing all variables at once. Variance compounds; the team cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential is slower but produces real learnings the team can apply to the next campaign. + +Detail in [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md). + +--- + +## Creative fatigue detection + +Fatigue is real. The same audience seeing the same creative six times a week tunes it out, or worse, develops negative associations. Five signals indicate fatigue. + +1. **Frequency above 4 to 5 per user per week.** Set explicit caps. Defaults are usually too high. +2. **CTR declining 30%+ week over week.** The creative is no longer fresh to the audience. +3. **CPM increasing without audience saturation explanation.** The platform is having to bid harder to deliver impressions because engagement signals are weakening. +4. **Negative comments increasing.** A direct user signal that the audience is irritated. +5. **Hide ratio increasing.** Meta exposes this as "negative feedback rate." TikTok exposes "not interested" rate. + +Refresh cadence. Weekly for high-spend campaigns ($50K+/month). Biweekly for medium spend. Monthly for low spend. The economics: producing a fresh variant is cheaper than running tired creative for one extra week. + +The decision tree. If a top performer's metrics are still strong but frequency is climbing, ship variants of the same concept (same hook structure, different copy and visuals). If the metrics are dropping, retire the concept and ship a new one. Detail in [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md). + +--- + +## Brand-voice alignment without conversion dilution + +The tension. Brand voice can feel off-brand when squeezed into 15-second ads. The fix is hierarchy, not compromise. + +Voice attributes that survive compression. Tone (playful, serious, expert, irreverent). Cadence (short sentences vs long-form). Vocabulary (industry-specific or accessible). Visual treatment (color, type, motion language). These survive in 15s because they live in the texture of every frame. + +Voice attributes that do not survive compression. Deep narrative arcs. Complex metaphors. Layered humor that requires setup. Long-form storytelling. These need 30s+ of runtime to land. Forcing them into 15s produces diluted versions that read as off-brand. + +The hierarchy. Brand voice in every frame; performance discipline in the structure. The brand voice shows up in tone, cadence, vocabulary, and visual treatment. The performance discipline shows up in pacing, hook strength, and CTA placement. + +A worked example. A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs three creatives. The 60-second YouTube awareness piece has the founder talking to camera, plain language, contrarian framing of the category. The 15-second Meta performance ad has fast cuts, plain language captions on screen, contrarian hook ("Stop overpaying for project management software"), specific value prop, CTA. The static carousel has 6 cards, plain language, contrarian opening card, value prop progression, CTA on the last card. Same voice. Different structure. None feels off-brand to a customer who has seen all three. + +Detail in [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md). + +--- + +## Platform-specific creative norms + +Each platform has native norms. Violating them tanks performance. The fix is producing platform-native, not repurposing. + +**Meta (Facebook plus Instagram).** In-feed visual hierarchy. Captions on by default (most users watch sound-off). Native-feeling production beats studio production for direct response. Vertical 9:16 for Reels and Stories; 1:1 or 4:5 for in-feed. CTAs above the fold or in first 2 lines of caption. + +**TikTok.** Vertical 9:16 only. Native-creator aesthetic; phone-shot is the default. Fast cuts every 1 to 2 seconds. Captions for accessibility. Music-driven; trending sounds compound reach but expire fast. Spark Ads (boost an existing organic post) consistently outperform pure paid because they retain organic engagement signal. + +**LinkedIn.** Professional tone. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. B2B vocabulary is fine; consumer-style copy reads as off-platform. Thought leadership angle works; product pitches feel salesy. + +**Google Search.** Text-only headlines plus descriptions. Character limits are real constraints (30-character headlines, 90-character descriptions). RSA (Responsive Search Ads) optimization rewards 15+ headline variations and 4+ descriptions; the platform mixes them. + +**Google Display and YouTube.** Depends on placement. YouTube allows longer narrative (15s to 6m); Display is fast banner-style. Skippable YouTube ads need to earn the next second of attention; non-skippable annoys. + +Detail in [`references/platform-creative-norms.md`](references/platform-creative-norms.md). + +--- + +## Common failures + +Eight patterns recur across creative production work. The short version. + +- "We made a beautiful brand video and ran it as performance." Wrong format and length for the channel. Brand video belongs in awareness; performance ads need the 15-second structure. +- "All our ads use the same hook." Saturation. Ship five to ten hook variants per concept and rotate. +- "Our ads stopped working after 3 days." Fatigue plus narrow audience. Either ship more variants or expand the audience; usually both. +- "We A/B tested 50 ad variations." Too many simultaneous variables. Run sequential tests instead. +- "Creative passes brand approval but underperforms." Brand discipline at the cost of performance discipline. The hierarchy is wrong; voice in every frame, performance in the structure. +- "TikTok ad uses Meta-style production." Platform norm violation. TikTok rejects polished ad creative; phone-shot native wins. +- "Our hooks all start with the brand logo." Kills the first-3-second hook. Brand logo belongs at second 1 to 3 (after the hook lands), not at second 0. +- "We never refresh creative because the old set still works ok." Incremental loss compounds. CTR decay is gradual; the team that does not refresh discovers a 40% performance gap when they finally check. + +--- + +## The framework: 10 considerations for sustainable creative production + +When designing or auditing ad creative, walk these 10 considerations. + +1. **Performance vs brand.** Name what this creative is optimizing for; do not mix. +2. **Hook strength.** First 3 seconds. Scroll-stopping. Specific. +3. **Format-platform fit.** Native to the channel. +4. **Pacing.** Value prop hits within 5 seconds; CTA by 15s. +5. **Variation system.** Matrix-based, not ad-hoc. +6. **Sequential testing.** Hooks, then bodies, then CTAs, then formats. +7. **Fatigue monitoring.** Frequency, CTR decay, CPM trend, negative feedback. +8. **Brand-voice alignment.** Voice that survives compression; performance in the structure. +9. **Platform creative norms.** Vertical for short-video platforms, captions on, native production. +10. **Refresh cadence.** Weekly to monthly by spend tier. + +The output of the framework is a production plan. A list of variations to ship in the next testing cycle, the testing waterfall to run, the fatigue thresholds that trigger refresh, and the platform-specific norms the variations respect. Three answers from the framework: ship as planned, revise the plan, or stop because a precondition is missing. + +--- + +## Reference files + +- [`references/hook-pattern-library.md`](references/hook-pattern-library.md) - Twelve hook patterns with worked examples and anti-patterns for each. +- [`references/format-decision-matrix.md`](references/format-decision-matrix.md) - Audience-objective context to recommended format with reasoning and common alternatives. +- [`references/creative-variation-templates.md`](references/creative-variation-templates.md) - Matrix-based production system, naming conventions, asset library structure, half-day worked example. +- [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md) - Sequential testing waterfall with per-stage variant counts, durations, and winner-advancement criteria. +- [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md) - Five fatigue signals with thresholds and refresh decision tree. +- [`references/platform-creative-norms.md`](references/platform-creative-norms.md) - Per-platform aspect ratios, lengths, audio expectations, caption norms, and native-aesthetic anti-patterns. +- [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md) - Voice attributes that survive 15-second compression vs those that do not, with a four-format worked example. + +--- + +## Closing: the hook is the whole game + +In performance creative, the hook is the whole game. If the hook fails, no body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. + +Spend the disproportionate creative effort on the first 3 seconds. The rest is delivery. The team that puts 60% of its creative effort into the hook and 40% into everything else outperforms the team that distributes effort evenly. The team that puts 90% of its effort into hooks and 10% into delivery beats both, as long as it ships enough variations for the testing waterfall to find which hooks actually work. + +When in doubt, ship the variant. A weak variant ships; a perfect variant never does. The sequential testing waterfall finds the winners; the variation system makes shipping cheap. The asymmetric cost of inaction is real; the asymmetric cost of shipping a marginal variant is small. diff --git a/skills/ads-creative-development/references/brand-voice-performance-balance.md b/skills/ads-creative-development/references/brand-voice-performance-balance.md new file mode 100644 index 0000000..2be0aa0 --- /dev/null +++ b/skills/ads-creative-development/references/brand-voice-performance-balance.md @@ -0,0 +1,101 @@ +# Brand voice plus performance balance + +How to keep brand voice intact at 15-second performance scale without diluting conversion. + +The tension. Brand voice often feels off-brand when squeezed into a 15-second ad. The instinct is to compromise: water down the voice for the format, or sacrifice the format for the voice. Both are wrong. The fix is hierarchy. + +--- + +## Voice attributes that survive compression + +Four attributes carry the brand voice in 15 seconds without consuming runtime. + +**Tone.** Playful, serious, expert, irreverent, warm, blunt. Tone lives in the texture of every frame; it does not need narrative space to land. A blunt brand can write blunt captions in 15 seconds. A warm brand can shoot warm faces. + +**Cadence.** Short sentences vs long-form. Short and punchy fits the 15-second frame; long sentences need 30+ seconds to land. The brand whose voice is short and punchy is naturally well-fit for performance creative. + +**Vocabulary.** Industry-specific or accessible. Plain or formal. The brand voice that uses certain words and not others can preserve that vocabulary in any format. + +**Visual treatment.** Color, type, motion language, photographic style. Visual identity survives in 1 second; it survives in 15. + +--- + +## Voice attributes that do not survive compression + +Three attributes need runtime to land. Forcing them into 15-second performance creates diluted versions that read as off-brand. + +**Deep narrative arcs.** Hero's journey, character development, story-with-resolution. These need 30 to 60 seconds minimum. A 15-second compression of a narrative is the trailer, not the story. + +**Complex metaphors.** A brand whose voice relies on extended metaphors needs runtime to set up the metaphor and pay it off. 15 seconds of metaphor is the setup with no payoff; the audience leaves confused. + +**Layered humor that requires setup.** Jokes that depend on a long setup work in long-form. In 15 seconds the joke is too rushed to land. Punchline-style humor works; setup-dependent humor does not. + +The implication. A brand whose voice is built on narrative depth or complex metaphor will struggle with performance creative. The fix is not to compromise the voice; the fix is to use the appropriate format for the voice. Long-form awareness ads carry the narrative; performance creative carries the tone, cadence, vocabulary, and visual treatment without trying to land the full narrative in 15 seconds. + +--- + +## The hierarchy + +Brand voice in every frame. Performance discipline in the structure. + +**Voice in every frame.** The tone, cadence, vocabulary, and visual treatment of every clip, caption, and CTA reflects the brand. The audience watching three different ad variations should recognize the same brand across all of them. + +**Performance in the structure.** The pacing, hook strength, value-prop placement, and CTA placement follow performance norms. Hook in 1 to 3 seconds. Value prop by 5 seconds. Social proof or demo by 7 to 12. CTA by 15. The structure is platform-driven, not voice-driven. + +The two layers do not compete. Voice operates at the texture level; structure operates at the timing level. A blunt brand can be blunt in 1 second (texture) and structured in performance pacing (timing). + +--- + +## Worked example: same voice, four formats + +A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs four creatives. + +### 60-second YouTube awareness piece + +The founder talks to camera. Plain language. Contrarian framing of the category. The opening question hooks; the middle 40 seconds tell the story of why the brand exists; the closing 10 seconds invite the audience to learn more. + +Voice carries because there is runtime. Structure is narrative-led. + +### 15-second Meta Reels performance ad + +Fast cuts. Plain language captions on screen. Contrarian hook in second 1 ("Stop overpaying for project management software"). Specific value prop in seconds 4 to 7 ("$10 per user per month, all features"). Social proof in seconds 8 to 12 ("Used by 10,000+ teams"). CTA in seconds 13 to 15 ("Start your free trial"). + +Voice carries through tone (direct, plain) and visual treatment (consistent typography). Structure is performance-led. + +### 15-second TikTok Spark Ad + +Phone-shot. Creator-style. Plain language captions. Contrarian opening line spoken to camera ("Most project management tools cost too much"). Demonstration in seconds 4 to 9 (creator showing the product on their laptop). CTA in seconds 12 to 15. + +Voice carries through tone and the conversational cadence. Production aesthetic is platform-native (phone-shot, not studio). + +### Static carousel (6 cards) + +Card 1: Contrarian opening ("Most PM tools cost too much"). Card 2: The number ($10/user). Card 3: The features. Card 4: The customer logos. Card 5: The story (one customer who switched). Card 6: CTA. + +Voice carries through plain-language copy and consistent visual treatment. Structure is card-by-card progression, not narrative. + +The check. A customer who has seen all four pieces should recognize them as the same brand. The voice is consistent. The structure is format-appropriate. None of the four feels off-brand. + +--- + +## When voice and performance genuinely conflict + +Two situations where the conflict is real, not solvable. + +**The brand voice is built on narrative depth.** Some brands (especially heritage brands, premium brands, brands with founders who write long-form) have voices that genuinely require runtime. Performance creative for these brands often works better as static or carousel (where the depth lives in the copy) than as 15-second video (where the runtime is too short for the voice). + +**The performance objective requires a tone the brand does not use.** Direct response often pushes toward urgency, scarcity, and aggressive CTAs. A brand whose voice is calm and considered will read as off-brand if the performance ad uses high-urgency CTAs. The fix is to push back on the performance team's CTA defaults; calm-and-considered brands can have calm-and-considered CTAs that still convert when the offer is right. + +The default. Resolve the conflict by adjusting the format choice (use static or carousel for narrative-deep brands; use longer awareness pieces alongside performance) or by adjusting the CTA register (calm CTAs for calm brands). Do not compromise the voice; the voice is the long-term asset. Do not compromise the performance; the performance is the short-term revenue. Find the format and register that keeps both intact. + +--- + +## Common mistakes + +**Watering down the voice for the format.** A brand whose voice is sharp produces a soft 15-second ad to "fit the format." The audience does not recognize the brand; the ad converts marginally; the brand erodes. + +**Sacrificing the format for the voice.** A brand whose voice is narrative-deep produces a 60-second performance ad with no hook. The audience scrolls past in 1 second; the voice never lands. + +**Treating voice and structure as the same axis.** Voice is texture; structure is timing. They do not compete unless the voice depends on structure (narrative-led brands), in which case the format choice is the lever, not the voice itself. + +**No brand-voice review on performance creative.** The performance team produces ads that convert but read as off-brand. A 5-minute brand-voice review on every variation catches the off-brand drift before it ships. diff --git a/skills/ads-creative-development/references/creative-variation-templates.md b/skills/ads-creative-development/references/creative-variation-templates.md new file mode 100644 index 0000000..01f6754 --- /dev/null +++ b/skills/ads-creative-development/references/creative-variation-templates.md @@ -0,0 +1,123 @@ +# Creative variation templates + +The matrix-based production system. How to produce 20 to 50 ad variations from one core concept in a half-day session. + +The principle. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. The matrix lets you ship dozens of variations from minimal authoring overhead, which is what the sequential testing waterfall requires. + +--- + +## The decomposition + +A single creative is composed of independent components. + +| Component | Example | Authoring cost | +|---|---|---| +| Concept | Theme or message ("the project management tax") | High (the strategy work) | +| Hook | First 3 seconds, scroll-stop | Medium (per variant) | +| Body | The middle 5 to 10 seconds | Medium | +| CTA | The closing call to action | Low | +| Format | Vertical video, carousel, static, etc. | Medium (rendering) | + +The math. 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. Most are not worth shipping; the matrix typically narrows to 20 to 40 the team will actually run. The point is that authoring 5 hooks plus 4 bodies plus 3 CTAs equals 12 components total, which compose into 60 hook-body-CTA combinations. + +--- + +## Variation matrix template + +A simple spreadsheet that drives the production session. + +| Concept | Hook ID | Body ID | CTA ID | Format | Variant ID | Status | +|---|---|---|---|---|---|---| +| launch2026 | hook_a | body_a | cta_a | meta-reel | v001 | drafted | +| launch2026 | hook_b | body_a | cta_a | meta-reel | v002 | drafted | +| launch2026 | hook_c | body_a | cta_a | meta-reel | v003 | drafted | +| launch2026 | hook_a | body_b | cta_a | meta-reel | v004 | drafted | +| launch2026 | hook_a | body_a | cta_b | meta-reel | v005 | drafted | +| launch2026 | hook_a | body_a | cta_a | tiktok-vertical | v006 | drafted | +| launch2026 | hook_a | body_a | cta_a | static-1x1 | v007 | drafted | + +The status column tracks the production pipeline: drafted, rendered, approved, shipped, paused, retired. + +--- + +## Naming conventions + +Every variation has a structured name so the analyst can join performance data back to creative components. + +``` +{concept}_{platform-format}_{hook}_{body}_{cta}_v{n} +``` + +Examples: + +``` +launch2026_meta-reel_hookA_bodyB_ctaC_v1 +launch2026_tiktok-vertical_hookE_bodyA_ctaA_v3 +launch2026_static-1x1_hookA_bodyA_ctaB_v2 +``` + +The analyst pulls the report, splits the names on the underscore, joins to a master variant table, and reports performance by component. "Hook E is winning across body and CTA combinations on TikTok" becomes a query, not a manual review. + +--- + +## Asset library structure + +Organize files by concept, not by date. + +``` +concepts/ + launch2026/ + hooks/ + hookA-direct-callout.txt + hookB-contrarian-claim.txt + hookC-result-led.txt + hookD-curiosity-gap.txt + hookE-personal-story.txt + bodies/ + bodyA-feature-list.txt + bodyB-customer-story.txt + bodyC-comparison.txt + bodyD-process-walkthrough.txt + ctas/ + ctaA-shop-now.txt + ctaB-start-trial.txt + ctaC-book-demo.txt + visuals/ + hero-product-shot.png + ugc-customer-1.mp4 + founder-camera.mp4 + rendered/ + meta-reel/ + tiktok-vertical/ + static-1x1/ +``` + +Date-based organization rots fast. Concept-based organization composes; the team that runs three concepts a quarter has three folders, each with a clean inventory of components. Six months in, the library is searchable. + +--- + +## Half-day production session worked example + +The goal. Produce 40 variations of one core concept in 4 hours. The team: one creative strategist, one editor, one copywriter. + +**Hour 1: matrix planning.** Strategist drafts 5 hooks, 4 bodies, 3 CTAs against the concept brief. Copywriter refines language. Output: 12 component scripts. + +**Hour 2: visual asset prep.** Editor pulls the visual library (hero product shot, two UGC videos, two founder-to-camera takes). Copywriter writes captions per platform. Output: visual atoms ready to compose. + +**Hour 3: rendering.** Editor renders the matrix using a video editor's template feature (or a tool like Pencil, Vidico Forge, or in-house automation). The hook component swaps in; the body component swaps in; the CTA component swaps in; the format renders per platform. Output: 30 rendered variations. + +**Hour 4: review and final renders.** Team reviews the 30 outputs, kills the 5 to 10 that fail the smell test, renders the final 10 that need higher-quality cuts. Output: 20 to 25 production-ready variations. + +The math. 12 component scripts plus a half day of editor time produces 20 to 25 variations. Without the matrix, the same 20 to 25 variations require 5 days of independent authoring per variation. + +--- + +## When the matrix breaks down + +Two situations where the matrix is the wrong shape. + +**Concept-driven brand work.** Awareness creative often does not decompose cleanly. The 60-second YouTube spot is one creative, not a matrix. The hook, body, and CTA are integrated into the narrative. For brand work, drop the matrix and produce one strong piece. + +**Highly format-specific creative.** A behind-the-scenes TikTok is not a hook plus body plus CTA; it is a single creator's continuous take. Forcing the matrix produces stilted ads that read as agency-produced. For format-native creative, accept that one format produces one creative; do not try to render the same content into static. + +The rule. Use the matrix for performance creative where direct response is the goal. Drop the matrix for awareness, brand, or format-native creative where the integrity of the piece matters more than ship volume. diff --git a/skills/ads-creative-development/references/fatigue-detection-checklist.md b/skills/ads-creative-development/references/fatigue-detection-checklist.md new file mode 100644 index 0000000..c4b52d5 --- /dev/null +++ b/skills/ads-creative-development/references/fatigue-detection-checklist.md @@ -0,0 +1,110 @@ +# Fatigue detection checklist + +Five signals that creative is fatiguing, with thresholds and a refresh decision tree. + +The principle. Creative fatigue is a real economic cost. The tired ad still spends; it just does not convert. The team that monitors fatigue catches the decay early; the team that does not discovers a 30 to 50% performance gap when they finally check. + +--- + +## The five signals + +### 1. Frequency above 4 to 5 per user per week + +**Threshold.** Above 4 per user per week for performance ads. Above 5 for awareness ads. + +**Why it matters.** The same audience sees the same creative too many times. CTR drops, irritation rises, brand association erodes. + +**Where to check.** Meta Ads Manager: frequency report at the ad-set level. Google Ads: frequency at the campaign level. TikTok: less granular, but available at the ad group level. + +**Action.** If frequency is climbing past 4, ship variants of the same concept (different copy and visuals, same hook structure). If multiple concepts are all climbing, the audience is too narrow; expand. + +### 2. CTR declining 30%+ week over week + +**Threshold.** A 30% drop week over week is the alarm. A 10 to 15% drop is normal noise; 30% is a signal. + +**Why it matters.** The audience is no longer interested in the creative. Continuing to run it spends without producing the click. + +**Where to check.** Each platform's reporting at the ad level over a 4-week window. Look at the trendline, not just the latest week. + +**Action.** Refresh the creative within 7 days. If multiple ads in the same audience are dropping simultaneously, the audience is fatigued; rotate audiences as well as creative. + +### 3. CPM increasing without audience saturation explanation + +**Threshold.** A 25%+ increase over 14 days, with audience size and competition both stable. + +**Why it matters.** The platform's algorithm is having to bid harder to deliver impressions because engagement signals are weakening. The audience is still there but the platform sees the creative as less relevant. + +**Where to check.** Each platform's CPM trend. Cross-reference with audience overlap reports and competitor activity (Meta Ads Library, SimilarWeb, etc.). + +**Action.** Refresh creative. The CPM will recover within 7 to 14 days of fresh creative landing. + +### 4. Negative comments increasing + +**Threshold.** Comments containing "spam," "stop showing me this," "annoying," or platform-specific negative reactions exceeding 1% of impressions. + +**Why it matters.** Direct user signal of irritation. The audience is mad; the brand is paying for that anger. + +**Where to check.** Meta Ads Manager: comments section per ad. TikTok: comments per ad. Less visible on LinkedIn. + +**Action.** Pull the creative within 24 hours. Negative comments compound; the audience that complains often is the audience that complains to friends. + +### 5. Hide ratio (negative feedback) increasing + +**Threshold.** Meta exposes "negative feedback rate"; trigger refresh when it exceeds 1.5% of impressions or rises 50% week over week. + +**Why it matters.** Hide is a stronger signal than scroll-past. The audience is actively rejecting the ad. Platform algorithms penalize creatives with high hide ratios by reducing reach. + +**Where to check.** Meta Ads Manager: customize columns to expose negative feedback. Other platforms: less direct equivalents (TikTok "not interested" rate is similar). + +**Action.** Pull the creative immediately. The cost is real: the platform will deliver less of all your ads to that audience as it learns to weight negative signals. + +--- + +## Refresh cadence by spend tier + +| Monthly spend | Refresh cadence | Variants per refresh | +|---|---|---| +| Under $5K | Monthly | 2 to 3 | +| $5K to $25K | Biweekly | 3 to 5 | +| $25K to $100K | Weekly | 5 to 10 | +| Above $100K | Twice weekly | 10+ | + +The economics. Producing a fresh variant costs less than running tired creative for one extra week. At $100K per month, even one day of underperformance is meaningful. Higher spend justifies higher refresh investment. + +--- + +## Refresh decision tree + +When fatigue signals trigger, three options. Pick based on the diagnosis. + +**Option 1: variant of working concept.** The hook structure is still working but the specific creative is fatigued. Ship 3 to 5 variants of the same concept (different copy, different visuals, same hook structure). + +When. CTR drop with frequency above threshold, but the concept itself was strong (top performer in the testing waterfall). + +Cost. Half-day production session if the matrix is in place. Variants ship within 48 hours. + +**Option 2: replace concept entirely.** The concept is exhausted. Ship a fresh concept (different hook structure, different angle, different value prop emphasis). + +When. Multiple variants of the same concept are dropping simultaneously, or the concept has been in market for 6 to 12 weeks at high frequency. + +Cost. Full production cycle. Variants ship within 1 to 2 weeks. + +**Option 3: full creative rotation.** Multiple concepts are tired across the account. The audience is over-saturated. + +When. CPM rising across multiple campaigns, hide ratio climbing across the account, multiple concepts dropping in parallel. + +Cost. Quarterly creative refresh. Plan ahead; do not let the rotation be reactive. + +--- + +## Common mistakes + +**Watching only CTR.** CTR is a fatigue signal but not the only one. CPM and frequency lead CTR; the team watching only CTR is reactive when leading signals would have caught it 1 to 2 weeks earlier. + +**Refreshing too late.** Once CTR has dropped 50%, the audience has already developed negative associations. The next creative inherits that fatigue context. Refresh on leading signals (CPM, frequency). + +**Refreshing without analysis.** Producing fresh creative without understanding what worked about the previous creative. The team ships variants that miss what made the original successful and reverts to baseline performance. + +**Ignoring the platform algorithm's cooldown.** A new creative variant goes through a learning phase (3 to 7 days). Performance during the learning phase is not representative; do not kill a new variant in week 1. + +**Treating all fatigue the same.** Audience fatigue is different from creative fatigue. If multiple creatives are all fatigued, the audience is the problem. Rotate audiences, not just creative. diff --git a/skills/ads-creative-development/references/format-decision-matrix.md b/skills/ads-creative-development/references/format-decision-matrix.md new file mode 100644 index 0000000..12b3bf6 --- /dev/null +++ b/skills/ads-creative-development/references/format-decision-matrix.md @@ -0,0 +1,48 @@ +# Format decision matrix + +Audience-objective context to recommended format. Read top to bottom; pick the row that matches your situation. + +--- + +## The matrix + +| Context | Primary format | Secondary format | Reasoning and what to avoid | +|---|---|---|---| +| B2C direct response, fast-scroll platforms (Meta, TikTok) | Vertical video 9:16, 15s | Static image (retargeting) | Native to the feed, scroll-stop in 1s. Avoid horizontal video; it gets letterboxed and ignored. | +| B2B SaaS demo or feature explainer | Carousel | Vertical video with captions | Carousel lets users self-pace; B2B audiences are in research mode. Avoid horizontal video for B2B feed placements. | +| DTC visual product | UGC-style vertical video | In-feed product carousel | UGC retains organic feel and beats studio production for direct response. Avoid heavily produced product shots; reads as "ad" and gets skipped. | +| Trust-led offer (financial, healthcare) | Static with social proof + carousel | UGC video with named customers | Trust requires repeat exposure to credible signals. Avoid moving cuts and music; reads as a pitch. | +| Founder-led B2B SaaS | Founder-to-camera video, 15 to 30s | Static quote card | First-person specificity is high-trust. Avoid voiceover with stock footage; reads as agency-produced. | +| Education-led content marketing | Long-form video (60s to 3m) | Carousel | Long-form rewards educational content. Use for awareness or top-funnel; not direct response. | +| App install | Vertical video with screen recording | Static screenshot grid | Screen recording shows the product in 5 seconds, faster than narration. Avoid feature lists; show the product. | +| Local services | Static image + lead form | UGC-style customer quote | Lead capture is the goal; minimize friction. Avoid long video; the audience is conversion-ready. | +| Enterprise B2B (>$50K ACV) | LinkedIn Sponsored Content with carousel or static | Long-form video for awareness | Professional tone, slower pacing. Avoid TikTok-style fast cuts; reads as off-platform. | +| Retargeting (warm audience) | Static image with offer | Short carousel with social proof | Audience already knows the brand; lead with the offer or social proof, not the brand intro. Avoid full hooks; the audience does not need them. | +| Black Friday or peak moment | Static with discount + countdown | Vertical video with offer + urgency | Speed matters in peak; the audience is decision-ready. Avoid long-form storytelling. | +| Pre-launch awareness | Long-form vertical video, 30 to 60s | Carousel for waitlist | The audience is curious, not converting. Reward attention with substance. Avoid short performance hooks; they undersell. | + +--- + +## Decision rules + +Three rules apply across the matrix. + +**Match the platform's native style.** A 1:1 video on TikTok performs worse than the same video as 9:16 vertical. A horizontal video on LinkedIn performs better than the same vertical, because LinkedIn audiences watch on desktop more than TikTok audiences do. Rules differ; produce per platform. + +**Match the audience's consumption mode.** Scroll mode (TikTok, Reels) needs hook in 1 second. Research mode (LinkedIn, B2B blogs) tolerates longer pacing. Decision mode (retargeting, peak moments) wants the offer up front and skips the hook. + +**Match the offer's complexity to the format's information density.** Simple offers (a discount, a free trial) work in static. Complex offers (a multi-feature product, a service with a process) need carousel or video. Forcing a complex offer into static fails because the audience cannot understand what is being offered in 1 second. + +--- + +## Common mistakes + +**One format across all platforms.** A 16:9 video produced for YouTube does not work on TikTok or Reels. The team that ships one format and adapts crops produces underperforming creative on every platform except the one the format was designed for. + +**Format chosen by what is easy to produce.** Static is fastest to make; teams default to it even when video would convert 3x better. The cost of one good vertical video is recouped in one strong campaign; the production overhead is real but worth it for high-spend campaigns. + +**Format chosen without testing.** Most teams pick a format and stick with it. The matrix gives a starting point; the testing waterfall (see `testing-cadence-playbook.md`) gives the real answer for the specific brand and audience. + +**Carousel without progression.** A carousel is a multi-card story. Each card should advance the narrative or value prop. Six cards of the same image with different text waste the format. + +**Vertical video without captions.** Most users watch sound-off. A vertical video without captions communicates only its visual; the value prop disappears. Captions are not optional on Meta and TikTok. diff --git a/skills/ads-creative-development/references/hook-pattern-library.md b/skills/ads-creative-development/references/hook-pattern-library.md new file mode 100644 index 0000000..cf7d559 --- /dev/null +++ b/skills/ads-creative-development/references/hook-pattern-library.md @@ -0,0 +1,157 @@ +# Hook pattern library + +Twelve hook patterns that work consistently in performance creative. For each: what makes it work, when it fits, the anti-pattern, and one or two worked examples. + +A hook is the first 1 to 3 seconds of an ad. If the hook fails, the rest of the creative does not get watched. The hook carries 60% of the performance weight; the body and CTA carry 40%. Spend the creative effort accordingly. + +--- + +## 1. Problem-agitate-solve + +**What makes it work.** Names the audience's pain in their own language, then makes the consequence vivid, then offers the way out. The structure mirrors how the audience already thinks. + +**When it fits.** When the audience recognizes the pain and feels it as a real cost. Less effective when the pain is abstract. + +**Anti-pattern.** Skipping the agitate step. The audience hears the problem named and shrugs because the consequence is not vivid. + +**Example.** "Spending 4 hours a week on status updates? That is 200 hours a year. (Pause.) StatusBot writes them for you in 5 minutes." + +--- + +## 2. Direct callout to audience + +**What makes it work.** Triggers self-identification in the first second. The viewer thinks "that is me" and watches. + +**When it fits.** When the audience is narrow, self-aware, and proud of the identity. Founders, doctors, parents, runners, B2B SaaS PMs. + +**Anti-pattern.** Calling out an audience that is too broad. "If you are a person on the internet..." triggers nothing. + +**Example.** "If you are a B2B founder running paid ads with no in-house marketer, this is for you." + +--- + +## 3. Contrarian claim + +**What makes it work.** Violates expectation. The viewer's brain pauses on the contradiction. + +**When it fits.** When the audience has heard the conventional wisdom too many times and is exhausted by it. + +**Anti-pattern.** Contrarian for its own sake. The claim has to be defensible by the body of the ad; otherwise the audience disengages by second 5. + +**Example.** "Stop using lookalike audiences. Here is the audience strategy that actually scales." + +--- + +## 4. Result-led + +**What makes it work.** Specific number plus specific timeframe. The brain treats specificity as a credibility signal. + +**When it fits.** When the result is real and documented. Faked numbers train the audience to scroll past the entire account. + +**Anti-pattern.** Vague results. "We helped a client grow" produces no curiosity; "we cut their CAC 40% in 30 days" does. + +**Example.** "How we cut CAC 40% in 30 days for a Series B SaaS with no creative budget." + +--- + +## 5. Curiosity gap + +**What makes it work.** Promises a payoff after the gap. The viewer stays to find out. + +**When it fits.** When the gap is real and the payoff is on-topic. Clickbait without payoff trains the audience to scroll past. + +**Anti-pattern.** Gap without payoff. "The mistake 80% of marketers make..." with no actual mistake named in the body of the ad. Audience feels deceived. + +**Example.** "The mistake 80% of marketers make on Meta Ads is the one that costs them 30% of their budget every month." + +--- + +## 6. Social proof at top + +**What makes it work.** Validation before pitch. The audience trusts the offer because someone they trust trusts it. + +**When it fits.** When the proof is impressive enough to do the heavy lifting. Specific names beat generic numbers when the audience knows the names. + +**Anti-pattern.** Generic proof. "Trusted by thousands" is filler. "Used by Notion, Brex, and Figma" is signal. + +**Example.** "Used by 10,000+ teams including Notion, Brex, and Whatnot. Now available for solo founders too." + +--- + +## 7. Visual pattern interrupt + +**What makes it work.** A surprising visual that does not match the platform's usual feed flow. The eye snaps to it. + +**When it fits.** TikTok, Reels, Stories. Platforms with fast scroll and high pattern density. Less effective on slower platforms (LinkedIn). + +**Anti-pattern.** Overproduced visual interrupt that reads as ad. The interrupt has to feel native to the platform; a Hollywood-style pattern interrupt on TikTok reads as "ad" and gets skipped. + +**Example.** A creator-style cold open: a person on screen, looking confused at their phone, then turning the camera around to show the screen. Two-second hook before the first word. + +--- + +## 8. Question that hits intent + +**What makes it work.** The question pre-qualifies the audience. The audience that does not match disengages immediately, which is fine. + +**When it fits.** When the question matches a real search query the audience has typed. "Tired of paying $400 for project management software" works because that is what the audience googles. + +**Anti-pattern.** Generic questions. "Want to grow your business?" filters nothing. + +**Example.** "Tired of paying $400 a month for project management software you barely use?" + +--- + +## 9. Number-led + +**What makes it work.** Lists trigger the brain's pattern-completion instinct. The viewer wants to know all three (or five, or seven) reasons. + +**When it fits.** Educational content, list-style ads. Less effective for product ads where the offer should be specific. + +**Anti-pattern.** Too many items. "10 reasons" is too many for a 15-second ad; 3 to 5 is the sweet spot. + +**Example.** "3 changes that doubled our ROAS in Q4. Number 2 surprised our agency." + +--- + +## 10. Personal story open + +**What makes it work.** First-person specificity. The brain treats personal stories as data, not pitch. + +**When it fits.** When the story is real and the conclusion is action-relevant. Founder-led ads especially. + +**Anti-pattern.** Manufactured stories that read as fictional. The audience can usually tell. + +**Example.** "Last year I was burning $50K a month on Meta ads with no return. Here is what I changed in 30 days." + +--- + +## 11. Comparison + +**What makes it work.** Pits two options against each other. The audience in evaluation mode wants the comparison. + +**When it fits.** When the audience is actively comparing. "X vs Y" search queries are the tell. + +**Anti-pattern.** Unfair comparisons. The audience smells the spin and discounts the brand. + +**Example.** "Notion vs Linear: which actually works for engineering teams under 50." + +--- + +## 12. Behind-the-scenes / process + +**What makes it work.** Demystifies the work. The audience that wonders how something is done watches to find out. + +**When it fits.** When the process is the differentiator. Agencies, services businesses, niche craft. + +**Anti-pattern.** Process content that is actually a sales pitch in disguise. Audience disengages. + +**Example.** "How we onboard a new client in 7 days, end to end, with one PM and no kickoff meeting." + +--- + +## The pattern across all twelve + +Every working hook does the same thing: it makes the next second non-optional. The viewer cannot skip without losing something. Specificity, surprise, identification, curiosity, proof. Different mechanisms; same effect. + +The non-working hooks all do the same thing too: they let the viewer skip with no cost. Generic openings. Brand logo cards. Slow zooms over title text. "In today's world..." The first second is for the hook. The brand can wait. diff --git a/skills/ads-creative-development/references/platform-creative-norms.md b/skills/ads-creative-development/references/platform-creative-norms.md new file mode 100644 index 0000000..cfa0389 --- /dev/null +++ b/skills/ads-creative-development/references/platform-creative-norms.md @@ -0,0 +1,111 @@ +# Platform creative norms + +Per-platform creative requirements and unwritten conventions. Each platform has native norms; violating them tanks performance. + +--- + +## Meta (Facebook plus Instagram) + +**Aspect ratios.** 9:16 for Reels and Stories. 4:5 for in-feed (preferred over 1:1; uses more vertical real estate). 1:1 acceptable. Avoid 16:9 horizontal in feed. + +**Length.** 15 seconds is the sweet spot for performance. 6-second bumpers work for awareness. Long-form (60s+) only for storytelling formats; performance ads should resolve by 15s. + +**Audio.** Sound-off is the default. Captions are mandatory. Music is helpful when matched to the platform's audio context (low-fi background, not stock library bombast). + +**Captions.** On-screen captions for spoken audio. Bold, high-contrast, animated to track delivery. Avoid tiny captions; they are unreadable at scroll speed. + +**Native aesthetic.** Phone-shot or polished both work. UGC-style outperforms studio for direct response; studio outperforms for awareness. The brand voice and the offer drive which fits. + +**Anti-patterns.** Horizontal video in feed (gets letterboxed). No captions on spoken audio. Brand logo at second 0 (kills the hook). Slow zoom over title cards. Stock music bombast. Overproduced agency-style cuts that signal "ad" before the value lands. + +**What feels native.** Real people on camera. Direct address. Specific value props. Social proof named with brand names. Pacing that respects the user's scroll velocity (cuts every 1 to 2 seconds in the first 5 seconds). + +--- + +## TikTok + +**Aspect ratios.** 9:16 vertical only. Anything else is rejected by the algorithm. + +**Length.** 15 to 30 seconds for performance. The platform tolerates and rewards longer dwell than Meta. + +**Audio.** Sound-on is default. Trending sounds compound reach but expire fast. Original audio works. Captions for accessibility, not just for sound-off viewers. + +**Native aesthetic.** Phone-shot, creator-style. Studio production reads as "ad" and gets skipped. Pencil-and-paper aesthetic, jump cuts, unfiltered backgrounds, daylight. + +**Spark Ads.** Boost an existing organic post. Retains organic engagement signal. Outperforms pure paid creative; if the brand has organic content performing, this is the format. The Pipeboard and Synter MCPs cover Spark Ad creation; the integrations microsite covers the tactical setup. + +**Anti-patterns.** Polished agency video. Brand logo at second 0. Voiceover with stock footage. Slow-paced narrative. Music that signals "ad" (cinematic stock library). Anything that does not look like a creator filmed it. + +**What feels native.** Direct-to-camera creator. Fast cuts (1 to 2 seconds). On-screen captions following the speaker. Trending sounds when they fit. Backgrounds that look like a kitchen or bedroom, not a studio. + +--- + +## LinkedIn + +**Aspect ratios.** 1:1 or 16:9 for feed. 9:16 vertical works for Stories but Stories has limited reach on LinkedIn relative to other platforms. + +**Length.** 15 to 60 seconds. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. 30 seconds is a strong default. + +**Audio.** Sound-off default but sound-on more common than Meta. Captions still recommended. Music optional; many high-performing LinkedIn ads use no music. + +**Voice.** Professional. B2B vocabulary fine; consumer-style copy reads as off-platform. Thought leadership framing works; product pitches feel salesy. + +**Native aesthetic.** Founder-to-camera, expert-to-camera, slide-deck style, screen-recording demos. Studio production fine for LinkedIn; the audience is more tolerant of polished production than TikTok. + +**Anti-patterns.** TikTok-style fast cuts. Bombastic music. Casual or irreverent tone for serious B2B categories. UGC-style production for high-trust offers (financial services, healthcare). Generic "let us help your business grow" copy. + +**What feels native.** Specific industry vocabulary. Named customers and case studies. Slower pacing. Captions over slides. Founder-led specificity beats agency-style polish. + +--- + +## Google Search + +**Format.** Text-only headlines plus descriptions plus extensions. + +**Character limits.** Headlines 30 characters; 15 headline variants for RSA. Descriptions 90 characters; 4 description variants. Path 1 and Path 2 in the display URL: 15 characters each. + +**RSA optimization.** Provide 15+ headline variants and 4 description variants. The platform mixes them. More variants give the platform more material to optimize against. + +**Voice.** Direct. Specific. Action-led. The search query is high-intent; the ad's job is to confirm the user is in the right place. + +**Anti-patterns.** Keyword stuffing in headlines. Generic "we do X" headlines. Same value prop in every headline (the platform cannot test variation). Caps lock entire headlines (rejected). Unsubstantiated superlatives. + +**What works.** Specific value props per headline ("Free 14-day trial", "Used by 10,000+ teams", "Deploy in 5 minutes"). Question headlines that match search intent. Geographic specificity for local. Price points where they are the differentiator. + +--- + +## Google Display and YouTube + +### Display + +**Format.** Static or short animated banners across the Google Display Network. + +**Anti-patterns.** Unhelpful targeting (broad display drives garbage clicks). Vague creative (the audience is not in search mode; they need the value prop fast). + +**What works.** Retargeting with specific offers. Contextual placements (publisher list filtering). Cart-abandonment creative. + +### YouTube + +**Format.** Skippable video ads (TrueView), non-skippable, bumper (6s), in-feed video. + +**Length.** Skippable: 15s to 6m. Non-skippable: 15s. Bumper: 6s. + +**Audio.** Sound-on default. Captions still recommended for accessibility. + +**Native aesthetic.** YouTube allows longer narrative; the audience is in dwell mode. Both phone-shot and studio production work depending on context. + +**Anti-patterns.** Saving the value prop for the unskippable end. Skippable ads need to earn the next second; the value prop has to land in 5 seconds even on skippable. + +**What works.** First 5 seconds earn the rest. Specific value props. Demonstrations. Skippable with strong hooks routinely outperform non-skippable because the audience self-selects into watching. + +--- + +## Cross-platform principles + +Three rules apply across the matrix. + +**Native production beats repurposing.** A 16:9 video produced for one platform and cropped for others performs worse than three platform-native pieces. Produce per platform; do not adapt. + +**Pacing matches the platform's scroll velocity.** TikTok scroll is fast; cuts every 1 to 2 seconds. LinkedIn scroll is slow; longer takes work. Meta is in between. + +**Captions everywhere.** Sound-off is the default on most platforms most of the time. Spoken audio without captions is wasted audio. diff --git a/skills/ads-creative-development/references/testing-cadence-playbook.md b/skills/ads-creative-development/references/testing-cadence-playbook.md new file mode 100644 index 0000000..664b7ac --- /dev/null +++ b/skills/ads-creative-development/references/testing-cadence-playbook.md @@ -0,0 +1,121 @@ +# Testing cadence playbook + +The sequential testing waterfall. How to find the winning creative without testing 50 things at once. + +The principle. Variance compounds. Testing all variables at once means you cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential testing isolates the variable that matters at each step. + +--- + +## The waterfall + +Five stages. Each stage isolates one variable and advances the winners. + +### Stage 1: Hook test + +**Goal.** Find which hooks stop the scroll. + +**Setup.** 5 to 10 hook variants, same body, same CTA, same format. Each variant gets equal budget initially. + +**Duration.** 7 to 14 days, or until each variant has 50+ conversions or 1M+ impressions, whichever comes first. + +**Winner criteria.** Top 2 to 3 hooks by CTR (the metric that isolates hook performance) plus conversion rate above the floor. Eliminate hooks with high CTR but low conversion (the click is generated by the hook but the ad does not deliver). + +**Output.** 2 to 3 winning hooks advance to Stage 2. + +### Stage 2: Body test + +**Goal.** Find which body copy or middle-section visuals convert best given the winning hooks. + +**Setup.** Winning hooks times 5 to 10 body variants. Same CTA, same format. If two hooks advanced, that is 2 hooks times 5 bodies equals 10 ad sets. + +**Duration.** 7 to 14 days, or until each combination has 50+ conversions. + +**Winner criteria.** Top 2 to 3 hook plus body combinations by conversion rate. CTR is no longer the primary metric; the body is what holds attention after the hook. + +**Output.** 2 to 3 hook plus body combinations advance to Stage 3. + +### Stage 3: CTA test + +**Goal.** Find which CTA produces the strongest action given the winning hook plus body. + +**Setup.** Winning hook plus body combinations times 3 to 5 CTAs. Same format. Differences at this stage are usually marginal; do not over-engineer. + +**Duration.** 5 to 10 days, or until each combination has 30+ conversions. + +**Winner criteria.** Top hook plus body plus CTA combinations by conversion rate plus AOV (if value matters). + +**Output.** 2 to 4 winning combinations advance to Stage 4. + +### Stage 4: Format test + +**Goal.** Find which format works best for the winning combinations. + +**Setup.** Winning combinations rendered in 2 to 3 formats (vertical video, carousel, static). + +**Duration.** 7 to 14 days. + +**Winner criteria.** Top combinations by conversion rate within each format. Different formats may have different winners; that is fine. Run the winning format per surface. + +**Output.** 2 to 4 production-ready creatives ready for evergreen rotation. + +### Stage 5: Evergreen rotation + +**Goal.** Run winners at scale; refresh on cadence. + +**Setup.** 2 to 4 winners running in rotation. Frequency capping per audience. + +**Duration.** Ongoing. Refresh creative on the cadence in `fatigue-detection-checklist.md`. + +--- + +## Statistical thresholds + +Two ways to call winners. Pick one and standardize across the team. + +**Statistical significance.** Run until the winner has 95% confidence (or whatever threshold the team agrees on). Some platforms expose a "significance" indicator; others do not. + +**Pre-commit duration plus minimum volume.** Decide before launching: "we will run for 14 days, each variant gets at least 50 conversions, top performer wins." This is the simpler, more honest approach for most performance work. The platform's algorithm will not run a clean test under your nose anyway, so trying for high-confidence statistical significance is often overkill. + +The trap. Calling winners on small samples. A variant with 5 conversions and 10% lift over the other looks impressive but is within margin of platform noise. Wait for volume before declaring. + +--- + +## Common mistakes + +**Testing too many variables at once.** The most common mistake. Six hooks times five bodies times three CTAs times two formats equals 180 ad sets. The platform cannot optimize against that many variants; the team cannot interpret the results. Sequential is slower but produces real learnings. + +**Killing variants too early.** A variant in the learning phase has not yet converged. The platform's first 3 days of delivery are not representative. Wait at least 7 days before killing. + +**Calling winners on CTR alone.** A hook can drive high CTR with no conversion follow-through. The hook is doing its job (stopping the scroll) but the body is failing. Use conversion rate as the primary winner criterion; CTR is a hook-quality signal, not a creative-quality signal. + +**No exclusion of recent converters from the test audience.** Recent converters click ads at higher rates because they are warm; mixing them into the test audience produces false-positive results. Exclude. + +**Ignoring fatigue during the test.** A variant that wins the test in week 1 because it is new can underperform in week 4 once frequency builds. Test results are read against frequency; high-frequency winners are unreliable. + +--- + +## Per-stage budget guidance + +Rough percentages for the testing budget within a campaign's total spend. + +| Stage | Share of testing budget | +|---|---| +| Hook test | 40% | +| Body test | 25% | +| CTA test | 10% | +| Format test | 15% | +| Buffer (re-tests, lift checks) | 10% | + +The hook test gets the biggest share because it filters the most variants. CTA and format tests are smaller because the differences are usually marginal. + +--- + +## When to break the waterfall + +Two situations. + +**Time pressure.** A peak moment (Black Friday, product launch) does not allow 6 weeks of sequential testing. Compress: run a hook test concurrently with format test using your best-guess body and CTA. Accept lower confidence in exchange for speed. + +**Discovery of an outlier.** A hook variant that is winning by 5x at the end of week 1 should not wait for the full 14-day stage. Promote early, but track the long-tail performance to confirm. + +The default is the waterfall. The exceptions are real but rare; do not let "we are on a tight timeline" become the default reason to skip the discipline. diff --git a/skills/ads-performance-analytics/SKILL.md b/skills/ads-performance-analytics/SKILL.md new file mode 100644 index 0000000..2bcadc2 --- /dev/null +++ b/skills/ads-performance-analytics/SKILL.md @@ -0,0 +1,275 @@ +--- +name: ads-performance-analytics +description: "How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue." +category: marketing +catalog_summary: "Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget" +display_order: 3 +--- + +# Ads Performance Analytics + +A data-team-mentor's playbook for interpreting paid media dashboards without fooling yourself. + +The dashboard is the moment of truth for paid media decisions. The numbers on it determine whether you scale, hold, or kill. They also expose every platform's self-attribution bias, every modeled-conversion shortcut, every cross-platform double-count. Most "scale this campaign" decisions trace back to misreading the dashboard. + +This skill is the discipline that prevents misreading. It assumes the campaign was strategically sound (see `paid-media-strategy`). It assumes the creative was tested properly (see `ads-creative-development`). The hard part is knowing what each number actually means, what it does not, and how to reconcile platform-reported metrics with the truth in your warehouse. + +When to use this skill: any time you are about to scale, kill, or rebudget a campaign based on platform metrics; reconciling platform reports with revenue data; evaluating an agency's reporting; or building a paid media dashboard that will not lie to you. + +--- + +## What this skill is for + +This skill spans paid media result interpretation. It does not cover paid media strategy (use `paid-media-strategy`), creative production (use `ads-creative-development`), or platform-specific tooling (covered in the integrations microsites). Pair this skill with the relevant integrations microsite for platform-specific MCP commands and example prompts. + +The audience is a marketer, growth analyst, agency analyst, or founder evaluating paid media reports. The voice is patient and clinical. There is no "trust the platform's number" or "ignore the platform entirely." Both are wrong. The discipline is knowing which numbers from which platform mean what, and what to reconcile against to make the actual decision. + +--- + +## The result panel: what every paid media platform should expose + +A trustworthy result panel exposes nine things. Anything missing is a signal to treat reported numbers with extra skepticism. + +1. **Spend, impressions, clicks.** Table-stakes metrics. Should match across platforms within rounding. +2. **Conversions with definition and window visible.** Not just a count; the definition of what counts as a conversion and the attribution window applied. Without this, the count is unreadable. +3. **Attribution breakdown.** Last-click vs view-through vs modeled. The mix of how the conversions were credited. +4. **Frequency.** Impressions per unique user. The fatigue early-warning system. +5. **Audience saturation.** Where the platform exposes it. A flat audience-saturation curve means there is room to scale; a steep curve means efficiency is dropping. +6. **Time series.** Daily breakdown to spot novelty effects, fatigue, day-of-week patterns, and exogenous variance. +7. **Cost metrics in clear currency.** CPC, CPM, CPA, ROAS with the math defined and the currency labeled. Do not assume USD. +8. **Conversion path data.** Touchpoints before conversion, where available. Tells you whether a campaign is a closer or an opener. +9. **Filters, segments, and exports.** Without these, the panel is a brochure, not a tool. + +Platforms hide what makes their reporting look weakest. Google PMax hides keyword-level and placement-level data. Meta hides the modeled-conversion share. LinkedIn hides cross-device click paths. Treat hidden metrics as the place to dig. + +--- + +## Platform-reported vs reality + +Every platform's dashboard is optimized to make the platform look effective. This is not a moral failing; it is a structural incentive. Platforms with rosier reporting attract more spend. + +**Conversion windows.** Meta defaults to 7-day click plus 1-day view. Google defaults to 30-day click plus 1-day view. Different windows, same activity, different reported numbers. If you compare Google's 30-day-click count against Meta's 7-day-click count, you are comparing different definitions and pretending they are the same. + +**View-through attribution.** Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Treat view-through as a signal of awareness contribution, not as a direct response measurement. The user might have converted from organic search anyway. + +**Modeled conversions.** When iOS users opt out of tracking, Meta and others statistically model what the conversion would have been. Modeled numbers are educated guesses, not measurements. They are useful for direction; they are not reliable for precision. + +**Self-attribution bias.** Every platform's pixel fires on conversion and the platform claims credit. If you ran Meta, Google, and TikTok in the same week, all three platforms report your conversions as theirs. Sum-of-platforms is always greater than 100% of actual conversions. + +The discipline. Never report platform-reported numbers as fact in board decks. Always reconcile against the single source of truth (warehouse, GA4, or unified analytics platform). Detail in [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md). + +--- + +## Attribution models in practice + +Six models and one anti-model. None is right. They are all approximations. The discipline is picking one, committing, and reading the others as sanity checks. + +**Last-click.** Simple, reproducible, undercredits awareness. The conversion is fully credited to the last click before the conversion event. Easy to compute; easy to compare across channels; bad for understanding upper-funnel contribution. + +**First-click.** Opposite bias. Fully credits the first touchpoint, undercredits closing channels. Useful as a sanity check against last-click; rarely the right primary view. + +**Linear.** Equal credit across all touchpoints. Gives every channel something. Defensible; not informative. Most useful for board reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. + +**Time-decay.** More credit to recent touchpoints. Reflects the intuition that recent ads are more influential. Hard to argue against; hard to verify. + +**U-shaped (position-based).** Heavy on first and last (40% each), light on middle (20% distributed). Honors both opener and closer roles. The default in many MTA tools. + +**Data-driven attribution (DDA, Google).** Machine-learning model that distributes credit based on observed conversion paths. Opaque; hard to audit. The closest to "right" for digital channels but a black box. + +**Marketing mix modeling (MMM).** Regression-based, top-down. Uses spend and revenue time series across channels to estimate channel contributions. Requires 2+ years of data. The strongest defense against platform self-attribution because it does not rely on platform-reported conversions at all. + +**The anti-model: trusting platform-reported attribution.** Each platform's "DDA" or "attributed conversions" is the platform's self-attribution. Sum across platforms exceeds reality. Use platform attribution for in-flight optimization within the platform; use a unified attribution model for cross-channel decisions. + +Practical guidance. + +- Early-stage. Use last-click plus a single guardrail metric (warehouse-attributed CAC). Sophisticated attribution requires data volume you do not have. +- Mid-stage. Data-driven attribution from Google plus GA4, with explicit awareness vs closing channel labeling. +- Mature. MMM as the canonical incremental reference. MTA for in-flight optimization. Last-click for channel-level decisions where ambiguity is acceptable. + +Detail and a decision matrix in [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md). + +--- + +## Multi-platform reconciliation + +The trap. Google says you spent $50K with 800 conversions. Meta says $30K with 600. LinkedIn says $20K with 200. Total reported equals 1,600 conversions. Your warehouse says 950. Where did 650 go? + +The answer. Nowhere. They never existed. Each platform claimed conversions other platforms also claimed. + +The reconciliation pattern. + +- Trust the warehouse for total conversions and total revenue. +- Trust platforms for relative ranking within platform (which campaign won, which audience won). +- Never trust platform sums. +- Compute blended CAC as (total ad spend across platforms) divided by (total new customers from warehouse). Not from platform reports. + +The board-deck pattern. Report warehouse-attributed conversion counts, never platform-summed. Report blended CAC, not channel-by-channel CAC unless explicitly noted as platform-self-attributed. Detail and templates in [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md). + +--- + +## ROAS vs LTV: the time horizon trap + +ROAS is short-term. Revenue from purchases attributed to a campaign in a fixed window, often 7 to 30 days. LTV is long-term. Total customer lifetime revenue. + +Decisions made on ROAS can be wrong if LTV varies by channel. A worked example. + +Meta drives 2.5x ROAS at $40 CAC with $80 LTV. The 7-day-click revenue covers 1.5x payback over the customer lifetime. + +Google drives 1.8x ROAS at $60 CAC with $200 LTV. The 7-day-click revenue covers 3.3x payback over the customer lifetime. + +Google looks worse on ROAS, better on LTV-adjusted return. Allocating budget to Meta because the ROAS is higher is the wrong move. + +The fix. Cohort-based LTV by acquisition channel, updated quarterly. Compare channels on payback period or LTV-CAC ratio, not raw ROAS. The 2x ROAS heuristic is a dangerous shortcut. Same ROAS at different LTVs equals different actual returns. + +The trap that compounds. Performance teams optimize for short-term ROAS because the metric refreshes weekly. Brand and high-LTV channels get cut because their short-term ROAS is lower. Six months later, the brand pipeline has eroded and short-term ROAS itself drops because the cheap channels are saturated. The metric that drove the decision was the wrong horizon. + +--- + +## Cohort analysis vs daily metrics + +Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. + +Three cohort cuts that matter for paid media. + +**By acquisition month.** Are users acquired in March retaining better than users acquired in January? A declining LTV over rolling acquisition cohorts means recent acquisition is lower quality; the daily metrics will show this two to three months later when the retention starts hurting. + +**By acquisition channel.** Are users from Meta retaining better than users from Google? Channel-level cohort divergence is the data behind the LTV-vs-ROAS argument. Meta might drive volume at lower LTV; Google might drive lower volume at higher LTV. The cohort tells the story the daily ROAS hides. + +**By acquisition campaign.** Campaign-level cohort signals. Useful for diagnosing why a campaign that "works" in week 1 produces no recurring revenue. + +The signal to act on. Declining cohort LTV over two consecutive months is the alarm. Pause the channel or campaign before the daily metrics force you to. Detail in [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md). + +--- + +## Statistical noise in performance metrics + +Most "the campaign improved 15% week over week" stories are noise. Real performance changes are 30% or more in metrics that vary 10 to 20% naturally. Below that threshold, you are looking at variance and calling it signal. + +Sources of noise in paid media metrics. + +- **Day-of-week effects.** B2C tends to weekend dips. B2B tends to weekend gains. A "Monday morning is better" hypothesis often dissolves when day-of-week is normalized. +- **Holiday and seasonal effects.** Q4 dwarfs most "optimization" effects. A campaign launched in Q4 looks great because of seasonality, not strategy. +- **Weather, news, competitor activity.** Real exogenous variance. Last week's news cycle can shift CPMs across an entire vertical. +- **Pixel fire and reporting delay.** Conversions reported on a 7-day click window arrive incrementally. Reading the panel on Monday for last week's performance undercounts. + +The fix. Pre-commit to test duration before drawing conclusions. Use the experimentation discipline from `experimentation-analytics` for any directional change you want to claim is real. The signal-to-noise problem in paid media metrics is the same as the signal-to-noise problem in product experiments; the framework transfers. + +This is where `experimentation-analytics` bridges in. The statistical patterns are the same; the application is different. Read both for the full picture. + +--- + +## Incrementality testing + +The honest test. If we had not run this ad, would we still have gotten the conversion? The number above zero is the incremental contribution. + +Most paid media is 30 to 70% incremental, not 100%. Some is zero. Branded search bidding is often 5 to 20% incremental (most converters would have found you organically). Retargeting is often 20 to 40% incremental (many of those users were going to convert anyway). Prospecting is often 50 to 90% incremental. + +Four methods. + +**Geo holdout.** Hold one region out from the campaign. Measure the difference in conversions between the holdout region and the matched test region. The cleanest causal test for paid media at scale. + +**Ghost bidding (Google).** Google's own incrementality tool. Bids on a holdout share of impressions but does not actually serve the ad. Reports incremental conversions. Honest signal; some teams find the math opaque. + +**Conversion lift studies (Meta).** Splits audiences into test and control. Test sees the ad; control does not. Reports incremental lift. The cleanest within-Meta test. + +**PSA tests.** Serve some users a public service announcement instead of your ad. Compare conversion rates. Useful for legacy brands with deep budget. + +Incremental rate ranges by channel type are in [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md). The discipline is to run incrementality tests at least quarterly on the highest-spend channels. Without them, you are optimizing against platform-reported attribution that systematically overcounts. + +--- + +## Geo experiments and holdouts + +For paid media specifically, geo-based testing is the most reliable causal method. + +**Geo holdout.** Turn off paid media in one region. Measure baseline organic conversions. The difference between expected and actual conversions in the holdout region is the incremental paid contribution. + +**Geo lift.** Scale spend in one region by 2x. See if conversions scale linearly. A linear scale means the channel has headroom. A sublinear scale means saturation; further spend is diminishing returns. + +**Switchback.** Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. Useful when geo splitting is not feasible. + +**Pre-and-post analysis.** Launch in a region; measure 30 days before vs 30 days after. Weak design because external factors confound the comparison. Use only when no other test is available. + +The right setup. Matched markets (similar demographics, similar baseline conversion rates). Statistical power calculation upfront (how big a difference can the test actually detect). Pre-committed analysis window (so you do not stop early when the data looks good or wait too long when it looks bad). + +The trap. Calling a geo test successful because of timing-correlated revenue lift. A campaign launched in October will see "lift" because Q4 is starting; without a control region, the lift is not attributable to the campaign. + +--- + +## Platform self-attribution bias + +A specific failure mode worth its own section. + +The mechanism. Platform's pixel fires on conversion. Platform claims credit. The user might have converted from any channel; the platform that loaded the pixel last gets the credit on the platform's own dashboard. + +Why platforms reward this design. More credit on the platform dashboard equals better-looking ROAS equals more advertiser spend. Platforms have no incentive to underreport their own contribution. + +Detection patterns. When platform-reported conversions exceed warehouse-attributed conversions for the same channel by more than 30%, you have heavy double-counting. When sum-of-platform-reports exceeds total conversions in the warehouse, you have cross-platform double-counting. + +The fix. Warehouse as canonical for board reporting. Platform reporting as in-flight signal only. Incrementality tests at least quarterly to keep the channel-attribution honest. + +A worked example. A retargeting campaign in Meta showed 3.5x ROAS for six months. The team scaled spend from $20K to $80K per month. A geo holdout test revealed that 65% of the "conversions" would have happened anyway from organic. Real ROAS adjusted for incrementality was 1.2x, not 3.5x. The campaign got cut and warehouse-attributed CAC dropped 18% in the next quarter. + +--- + +## Common interpretation failures + +Twelve patterns recur in paid media reporting work. Detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "ROAS dropped 20% week over week, kill the campaign." Could be noise. Pre-commit a test window before acting on weekly variance. +- "Meta says 500 conversions, my warehouse says 200, who is right?" Both are wrong; warehouse is closer to truth, Meta self-attributes. Reconcile, do not pick a winner. +- "We turned off Google PMax and conversions did not drop." PMax was harvesting branded search you would have gotten free. Audit branded queries inside PMax. +- "The new campaign hit 5x ROAS in week 1." Likely retargeting hot leads. Check the audience composition before declaring victory. +- "We A/B tested and one creative wins by 12%." Within margin of platform noise. Not significant. +- "Our LTV calculation says this channel is profitable." Check cohort age. Recent cohorts may not have hit LTV yet; the calculation is a projection, not a measurement. +- "The platform says high frequency is fine because conversions are still happening." Fatigue masked by free organic conversions. The campaign is taking credit for conversions that would have happened anyway. +- "Last-click attribution shows Meta at 60% credit." Last-click bias. First-click view of the same data shows different. Pick a model and stick. +- "We scaled spend 5x and conversions only doubled." Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher. +- "Brand campaigns underperform on direct ROAS." They do not have to. Brand impact shows up in other channels' efficiency. Measure brand against brand-search lift, not direct ROAS. +- "ROAS held steady but profit dropped." The mix shifted toward lower-margin products. Channel-level ROAS hides product-mix effects. +- "Agency reported a 4x ROAS month." Whose number? Platform-reported, warehouse-attributed, or model-adjusted? The unit of measurement matters more than the magnitude. + +--- + +## The framework: 12 considerations for trustworthy paid media interpretation + +When reading a paid media dashboard about to inform a decision, walk these 12 considerations. Skipping any of them is how teams ship the wrong call. + +1. **Result panel completeness.** What is the platform showing vs hiding. +2. **Platform-reported vs reality.** View-through, modeled conversions, conversion windows. +3. **Attribution model.** Pick one and read the others as sanity checks. +4. **Multi-platform reconciliation.** Sum-of-platforms is always inflated. +5. **ROAS vs LTV horizon.** Short-term metric, long-term impact. +6. **Cohort vs daily.** Cohort tells the quality story; daily tells the volume story. +7. **Statistical noise.** Weekly variance, day-of-week, seasonal, exogenous. +8. **Incrementality.** What would have happened without the spend. +9. **Geo and holdout testing.** The honest causal test. +10. **Self-attribution bias.** Platforms claim credit they do not deserve. +11. **Decision rule.** Pre-committed scale up, hold, or pull back. +12. **Single source of truth.** Warehouse over platform reporting for board metrics. + +The output of the framework is one of three answers. Scale (the campaign is incremental and unit economics work). Hold (data is ambiguous; gather more before deciding). Kill (the campaign is not incremental enough to justify the spend). + +--- + +## Reference files + +- [`references/metric-definitions-glossary.md`](references/metric-definitions-glossary.md) - CTR, CPC, CPM, CPA, ROAS, LTV, AOV, frequency, reach, impressions, conversion window, view-through, modeled conversion, blended CAC, MER. +- [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md) - Last-click, first-click, linear, time-decay, U-shaped, DDA, MMM. Decision matrix by business stage. +- [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md) - Google PMax black box, Meta iOS impact and Conversions API, LinkedIn 30-day click defaults, TikTok video-completion attribution, programmatic viewability gates. +- [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md) - Geo holdout, ghost bidding, conversion lift, PSA tests, switchback designs. Setup, duration, analysis pattern, expected incremental rates. +- [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md) - Warehouse as canonical, platform as in-flight signal, blended CAC formula, board-deck patterns, reconciliation cadence. +- [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md) - By acquisition month, channel, and campaign. Retention curves, when to act on cohort signals. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it incremental zero + +Most paid media spend is not 100% incremental. Some channels are 70% incremental. Some are 30%. Some are zero, paying for conversions you would have gotten anyway. + +The discipline of accepting that channels can be incremental zero, and pulling spend accordingly, is the single highest-impact skill in paid media analytics. Most accounts have at least one campaign that looks profitable in the platform but is incremental zero in the warehouse. Branded paid search at $4 CPC when the same users find you at position one organically. Retargeting at $0.30 CPC for users who already added items to cart. PMax cannibalizing free brand traffic. + +The discipline of finding those campaigns and killing them is the work. The platform will not tell you. The platform's incentive is the opposite. The warehouse, paired with quarterly incrementality tests, is the only honest source. + +When in doubt about whether a campaign is incremental, run a geo holdout. The two-week test is cheaper than a quarter of unincremental spend. The team that does not run incrementality tests is optimizing against numbers that are systematically wrong, and the size of the error is exactly the size of the budget waste. diff --git a/skills/ads-performance-analytics/references/attribution-model-comparison.md b/skills/ads-performance-analytics/references/attribution-model-comparison.md new file mode 100644 index 0000000..55d3e3f --- /dev/null +++ b/skills/ads-performance-analytics/references/attribution-model-comparison.md @@ -0,0 +1,128 @@ +# Attribution model comparison + +For each major attribution model: definition, fit, bias direction, and a worked example showing how the same activity gets different attribution. + +The principle. No model is right. They are all approximations. The discipline is to pick one as the primary view, read the others as sanity checks, and report against the warehouse rather than against any single platform's view. + +--- + +## The models + +### Last-click + +**Definition.** Full credit to the last clickable touchpoint before conversion. + +**When it fits.** Early-stage measurement where simplicity matters more than precision. Final-stage decisions where the closer matters more than the opener. + +**When it does not fit.** Awareness-channel evaluation. Brands with multi-touch sales cycles. Anything upper-funnel. + +**Bias direction.** Undercredits awareness channels (display, video, top-of-funnel social). Overcredits closing channels (branded search, retargeting). + +### First-click + +**Definition.** Full credit to the first touchpoint in the conversion path. + +**When it fits.** Awareness-channel evaluation. Comparing top-of-funnel sources. + +**When it does not fit.** Closing-channel evaluation. Performance optimization at the bid level. + +**Bias direction.** Mirror image of last-click. Undercredits closing; overcredits opening. + +### Linear + +**Definition.** Equal credit across every touchpoint in the conversion path. + +**When it fits.** Board-deck reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. Defensible-by-default. + +**When it does not fit.** Decisions where the marginal contribution of each channel matters. Linear treats first-click and last-click the same; reality usually does not. + +**Bias direction.** Diffuses credit. Channels that touched the path always get something; channels that drove the conversion do not get more. + +### Time-decay + +**Definition.** More credit to recent touchpoints. Older touchpoints get progressively less. + +**When it fits.** When the intuition is that recent ads are more influential. Reasonable for short-cycle B2C. + +**When it does not fit.** Long sales cycles where the first touchpoint may have been months before the close. Decay underweights the opener. + +**Bias direction.** Skews toward the closer. Slightly less aggressive than last-click. + +### U-shaped (position-based) + +**Definition.** 40% credit to first touch. 40% credit to last touch. 20% distributed across middle touches. + +**When it fits.** When you want to honor both opener and closer roles without flattening to linear. Reasonable default for most B2C. + +**When it does not fit.** Single-touch paths (awards 80% to a single touchpoint, which is over-attributing). Long paths where the middle touchpoints matter as much as the ends. + +**Bias direction.** Balances the last-click and first-click views into one number. + +### Data-driven attribution (DDA, Google) + +**Definition.** Machine-learning model that distributes credit based on observed conversion paths. Compares paths that did and did not convert; assigns credit to touchpoints that correlate with conversion. + +**When it fits.** Mature accounts with sufficient conversion volume (Google requires 600+ conversions per month for DDA). Cross-channel optimization. + +**When it does not fit.** Sub-scale accounts. Accounts that need explainability for regulators or boards. The black-box nature is hard to audit. + +**Bias direction.** Best in class for digital channels where the data is clean. Still suffers from platform self-attribution bias because Google's DDA only sees Google touchpoints. + +### Marketing mix modeling (MMM) + +**Definition.** Regression-based, top-down. Models the relationship between spend across channels and revenue over time. Typically requires 2 to 3 years of data. + +**When it fits.** Mature accounts with cross-channel spend at scale. Brands where offline channels (TV, OOH, podcast) contribute. Anywhere platform self-attribution bias is a real concern. + +**When it does not fit.** Early-stage accounts without enough historical data. Fast-changing channel mixes where the historical data does not represent current reality. + +**Bias direction.** The strongest defense against platform self-attribution because MMM does not rely on platform-reported conversions. Limitations are statistical: confidence intervals are wide; granularity is low (channel-level, not campaign-level). + +--- + +## The same path under each model + +A worked example. A B2C SaaS user converts after this path: + +1. Sees a YouTube awareness ad (impression, not click). +2. Clicks a Meta retargeting ad three days later. +3. Searches for the brand on Google. Clicks a paid branded search ad. +4. Returns directly the next day. Converts. + +Attribution by model. + +| Model | YouTube | Meta | Branded Search | Direct | +|---|---|---|---|---| +| Last-click | 0% | 0% | 0% (depending on direct vs paid) | 100% | +| First-click | 0% (impressions excluded) | 100% | 0% | 0% | +| Linear | 0% | 33% | 33% | 33% | +| Time-decay | 0% | 15% | 35% | 50% | +| U-shaped | 0% | 40% | 20% | 40% | +| Google DDA | (only sees Google touchpoints) | (only sees Meta touchpoints if Conversions API integration) | varies | varies | +| MMM | partial credit (spend in YouTube correlates with conversions) | partial credit | partial credit | (organic, not modeled) | + +The takeaway. Same path. Five different attribution stories. None is right. Each tells you something different. + +--- + +## Decision matrix by business stage + +| Stage | Primary model | Secondary check | Why | +|---|---|---|---| +| Pre-PMF | Last-click + warehouse-attributed CAC | None; insufficient volume for sophisticated models | Sophisticated attribution needs volume you do not have | +| Series A or early growth | Last-click + GA4 data-driven | First-click as sanity check on awareness | Volume insufficient for MMM; DDA requires more conversions than most early-stage accounts have | +| Mid-stage (10K+ conversions per month) | Google DDA + GA4 path data | Last-click for channel decisions; first-click for awareness | DDA gets reliable here; cross-validate with simple models | +| Mature (100K+ conversions per month, 2+ years data) | MMM as canonical | Last-click for in-flight; DDA for cross-channel | MMM is the strongest defense against self-attribution at scale | +| Multi-channel including offline | MMM mandatory | DDA for digital | MMM is the only model that captures offline contribution | + +The progression. As volume grows and channel mix expands, the model that fits changes. Locking in last-click forever is fine if the business stays simple; the moment offline or upper-funnel channels matter, the model has to advance. + +--- + +## How to communicate which model produced which number + +Three rules for honest reporting. + +1. **Always label the model.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions on last-click attribution with a 7-day-click window" is honest. +2. **Report the same number under at least two models when stakes are high.** Board decks should show the conservative view (last-click) and the generous view (linear or DDA). The range tells stakeholders what they are not learning. +3. **Reconcile against the warehouse before reporting in dollars.** Dollar figures attached to platform-reported conversions inherit all the platform's attribution biases. Warehouse-attributed dollars are the only dollars that have been independently verified. diff --git a/skills/ads-performance-analytics/references/cohort-analysis-templates.md b/skills/ads-performance-analytics/references/cohort-analysis-templates.md new file mode 100644 index 0000000..dbd3fdb --- /dev/null +++ b/skills/ads-performance-analytics/references/cohort-analysis-templates.md @@ -0,0 +1,113 @@ +# Cohort analysis templates + +Three cohort cuts that matter for paid media. By acquisition month, by channel, by campaign. Plus retention curves and when to act. + +The principle. Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. The difference is the leading indicator that a channel or campaign is degrading; daily metrics catch the same problem two to three months later when it shows up in revenue. + +--- + +## Template 1: Cohort by acquisition month + +The standard rolling 12-month view of LTV growth. + +**Setup.** For each acquisition month over the last 12 months, compute the cumulative revenue per customer at month 1, month 3, month 6, and month 12 (where data is available). + +**Output.** + +| Acquisition month | M1 revenue/customer | M3 revenue/customer | M6 revenue/customer | M12 revenue/customer | +|---|---|---|---|---| +| 2025-05 | $42 | $86 | $128 | $185 | +| 2025-06 | $44 | $89 | $135 | $192 | +| 2025-07 | $40 | $82 | $122 | $178 | +| 2025-08 | $43 | $85 | $130 | (incomplete) | +| 2025-09 | $38 | $78 | (incomplete) | (incomplete) | +| 2025-10 | $35 | $72 | (incomplete) | (incomplete) | +| 2025-11 | $33 | $68 | (incomplete) | (incomplete) | +| 2025-12 | $34 | (incomplete) | (incomplete) | (incomplete) | + +**The signal.** The M3 revenue per customer dropped from $86 to $68 over six months. Recent acquisitions are lower-quality customers. The daily metrics will show this as ROAS deterioration in two to three months when the recent cohorts hit their declining LTV plateau. + +**Action.** Investigate which channels or campaigns shifted in the last six months. The drop usually correlates with a specific channel scaling into lower-quality audiences. + +--- + +## Template 2: Cohort by acquisition channel + +The channel-level LTV story that ROAS hides. + +**Setup.** For each channel, compute LTV at fixed time windows (30, 60, 90, 180, 365 days post-acquisition). Track the trend over multiple acquisition cohorts. + +**Output (cohort: 2025-Q3 acquisitions, measured at 90 days post-acquisition).** + +| Channel | New customers | CAC | 90-day revenue/customer | 90-day LTV/CAC | Verdict | +|---|---|---|---|---|---| +| Google brand search | 420 | $45 | $128 | 2.8x | Strong | +| Google generic search | 280 | $95 | $112 | 1.2x | Marginal | +| Meta prospecting | 540 | $72 | $84 | 1.2x | Marginal | +| Meta retargeting | 320 | $48 | $156 | 3.3x | Strong | +| LinkedIn Sponsored | 95 | $320 | $580 | 1.8x | Long payback; B2B-typical | +| TikTok In-Feed | 180 | $58 | $61 | 1.1x | Marginal | +| Direct (organic) | 1,200 | n/a | $145 | n/a | Reference baseline | + +**The signal.** Meta retargeting and Google brand search are the strong performers on LTV-CAC. Meta prospecting and TikTok In-Feed are marginal; the customer quality is lower than the platform-reported ROAS suggests. + +**Action.** The marginal channels need either CAC reduction or audience-quality improvement. Pulling back on the marginal channels and reallocating to the strong ones improves blended LTV-CAC. + +--- + +## Template 3: Cohort by acquisition campaign + +Campaign-level cohort signals. Use sparingly; sample sizes get small fast. + +**Setup.** For each campaign with sufficient acquisition volume (typically 100+ customers per cohort), compute LTV at 30 and 60 days. Compare against the channel average. + +**Output.** + +| Campaign | New customers | CAC | 60-day revenue/customer | vs channel average | +|---|---|---|---|---| +| Meta-Lookalike-1pct | 320 | $58 | $112 | +30% | +| Meta-Lookalike-5pct | 180 | $48 | $74 | -15% | +| Meta-Interest-SaaS | 90 | $72 | $86 | -5% | +| Meta-Retargeting-30day | 240 | $42 | $148 | +60% | + +**The signal.** The 5% lookalike is finding lower-quality customers than the 1% lookalike, even at lower CAC. The ROAS view favors the 5% lookalike (lower CAC, decent revenue); the cohort view shows the customer quality dropped. + +**Action.** Pull back the 5% lookalike. Concentrate spend on the 1% lookalike and the retargeting segments. Watch for next-cohort confirmation before a permanent reallocation. + +--- + +## Retention curves + +A retention curve plots customer activity over time. Three patterns to recognize. + +**Plateau curve.** Activity drops in the first 30 days, then stabilizes at a level it sustains long-term. The plateau height is the long-run user value. Healthy SaaS, subscription consumer, marketplace. + +**Smile curve.** Activity drops, plateaus, then trends upward (resurrection effect). Less common; characteristic of products with seasonal or lifecycle re-engagement. + +**Decay curve.** Activity drops continuously without stabilizing. The product is not retaining; the unit economics will not work no matter what CAC the channel produces. Common in low-engagement consumer apps. + +**The curve to watch by acquisition channel.** A channel whose retention curve plateaus higher than another is delivering higher-LTV customers, regardless of the CAC ratio. This is the data behind LTV-CAC channel comparisons. + +--- + +## When to act on cohort signals + +Three triggers. + +1. **Two consecutive months of LTV decline at the same time horizon.** A single month is noise; two is signal. Investigate which channels shifted. +2. **Channel-level LTV-CAC ratio falls below 2x for two consecutive cohorts.** Pause or reallocate the channel. The 2x threshold accounts for gross margin, payback period, and the variance in LTV measurement. +3. **A campaign-level cohort underperforms the channel average by 20%+ for two consecutive cohorts.** The campaign is bringing in lower-quality audiences than the rest of the channel. Pause or reallocate. + +The discipline. Watch cohort signals on a monthly cadence. Most teams over-index on weekly platform metrics and under-index on cohort signals; the cohort-watchers see the problems first. + +--- + +## Common cohort mistakes + +**Reading recent cohorts as final.** A 30-day cohort's "LTV" is actually 30-day revenue, not LTV. Naming matters. If the team treats 30-day revenue as LTV in spreadsheets, they will undercount channels with longer payback periods. + +**Comparing cohorts at different ages.** A January cohort measured at 12 months vs a November cohort measured at 2 months is comparing different things. Always compare at matched ages. + +**Ignoring seasonal cohorts.** Q4 cohorts often have higher first-purchase value but lower retention because Q4 acquisition includes one-time gifters. Account for the seasonal pattern; do not over-index on Q4 cohort numbers. + +**Not segmenting by channel.** Aggregate LTV trends hide channel-level shifts. The channel-segmented cohort is where the action signal lives. diff --git a/skills/ads-performance-analytics/references/common-interpretation-failures.md b/skills/ads-performance-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..5b6e91d --- /dev/null +++ b/skills/ads-performance-analytics/references/common-interpretation-failures.md @@ -0,0 +1,155 @@ +# Common interpretation failures + +Twelve failure patterns that recur in paid media reporting work. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. ROAS dropped 20% week-over-week, kill the campaign + +**Symptom.** Weekly ROAS chart shows a drop. Team wants to pause the campaign. + +**Root cause.** Could be noise. Day-of-week, holiday timing, conversion-window lag, exogenous variance. A 20% drop in a metric that varies 10 to 15% naturally is below the signal threshold. + +**Fix.** Pre-commit a test window before acting on weekly variance. For most campaigns, two consecutive weeks of decline below the threshold is the signal. Single-week swings are usually noise. + +**Prevention.** Establish baseline variance for each campaign before declaring "improvement" or "decline." Without the baseline, every weekly chart looks alarming. + +--- + +## 2. Meta says 500 conversions, my warehouse says 200, who is right + +**Symptom.** Platform-reported numbers do not match warehouse numbers. The team picks the more flattering one. + +**Root cause.** Both are wrong; warehouse is closer to truth. Meta self-attributes (claims credit for conversions other channels also touched). View-through and modeled conversions inflate Meta's count. + +**Fix.** Reconcile, do not pick a winner. Report the warehouse number as canonical for board metrics. Use Meta's number only for in-flight optimization within Meta. + +**Prevention.** Make the reconciliation cadence explicit. Weekly check, monthly deep dive, quarterly attribution review. The team that runs the reconciliation never has to "pick a winner." + +--- + +## 3. Turned off Google PMax, conversions did not drop + +**Symptom.** Paused PMax. Total account conversions held steady. + +**Root cause.** PMax was harvesting branded search conversions you would have gotten free from organic. The platform was claiming credit for traffic that was not incremental. + +**Fix.** Audit branded queries inside PMax. Add account-level negative keywords for branded queries. Restart PMax with branded excluded; the incremental contribution from non-branded inventory is the real value. + +**Prevention.** At PMax setup, exclude branded queries from the start. Audit PMax's spend distribution monthly to catch the cannibalization pattern early. + +--- + +## 4. New campaign hit 5x ROAS in week 1 + +**Symptom.** A fresh campaign's first-week ROAS is 5x. Team wants to scale immediately. + +**Root cause.** Likely retargeting hot leads or running on a small audience of warm prospects who would have converted anyway. The first week is unrepresentative. + +**Fix.** Check the audience composition. If retargeting or warm-list, the 5x is not the steady-state. Wait two to four weeks before scaling. + +**Prevention.** Define the success metric and the test window before launch. Do not let a strong first week change the plan; pre-commit to the four-week measurement. + +--- + +## 5. A/B tested and one creative wins by 12% + +**Symptom.** Two creatives tested. One wins by 12%. Team wants to ship the winner. + +**Root cause.** 12% is within margin of platform noise for a typical creative test. Variants compete with each other inside the platform's optimization; the platform's own decisions confound the test. + +**Fix.** Re-run the test with more volume, or accept that the difference is within noise and pick based on production cost or refresh ease. + +**Prevention.** Set the minimum detectable effect (MDE) before testing. A 12% threshold requires a specific volume; if you cannot reach it, the test cannot detect that effect cleanly. + +--- + +## 6. LTV calculation says this channel is profitable + +**Symptom.** A team's LTV-CAC analysis shows a channel as profitable. Spend is increased. + +**Root cause.** The "LTV" in the calculation may be a 60-day cumulative revenue projected forward, not actual lifetime value. Recent cohorts have not aged enough to confirm the LTV. + +**Fix.** Confirm the cohort age. If projecting forward, document the assumption and stress-test (what happens if actual LTV is 80% of projected). + +**Prevention.** Always pair LTV calculations with cohort age. A 30-day cohort has 30-day revenue, not LTV. Naming clearly prevents the substitution error. + +--- + +## 7. High frequency is fine because conversions are still happening + +**Symptom.** Frequency at 6 to 8 per week. Conversions on the platform are stable. Team concludes fatigue is not an issue. + +**Root cause.** Fatigue masked by conversions that would have happened anyway from organic, retargeting overlap, or recurring customers. The platform is taking credit for traffic the high frequency did not actually drive. + +**Fix.** Run an incrementality test on the high-frequency campaign. The likely finding is that incremental rate dropped substantially even as raw conversions held. + +**Prevention.** Watch frequency as a leading indicator. Above 4 to 5 per week is the alarm regardless of conversion levels. Refresh creative. + +--- + +## 8. Last-click attribution shows Meta at 60% credit + +**Symptom.** Last-click view of paid media shows Meta dominant. Team allocates budget accordingly. + +**Root cause.** Last-click bias. Meta may also be the closer because users who searched for the brand on Google clicked through, then later saw a Meta retargeting ad and converted. Last-click credits Meta; the conversion would have happened anyway. + +**Fix.** Read the same data under first-click and a multi-touch model. The picture changes. Allocate based on a balanced view, not the last-click view alone. + +**Prevention.** Always compare attribution under at least two models for budget decisions. The single-model view is reliable for in-flight only. + +--- + +## 9. Scaled spend 5x, conversions only doubled + +**Symptom.** Budget went from $20K to $100K per month. Conversions went from 800 to 1,600. + +**Root cause.** Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher than the average CAC the team was reporting. + +**Fix.** Calculate the marginal CAC, not just average CAC. The marginal CAC at the higher spend tier tells you whether more spend will produce more conversions or just spend more for the same conversions. + +**Prevention.** Project the saturation curve before scaling. If a 1.5x spend increase produced a 1.2x conversion increase, expect the next 1.5x to produce 1.0x or less. + +--- + +## 10. Brand campaigns underperform on direct ROAS + +**Symptom.** A brand campaign reports 0.8x ROAS. Team wants to cut it. + +**Root cause.** Brand campaigns affect downstream channel efficiency, not direct conversion. The direct ROAS is the wrong measurement for brand impact. + +**Fix.** Measure brand against brand-search lift, organic traffic growth, or direct-traffic growth. The brand campaign's effect shows up in cheaper performance acquisition over the next 60 to 90 days. + +**Prevention.** At brand campaign setup, define the success metric explicitly (brand search lift target, organic traffic target, awareness lift). Do not let direct ROAS become the unintended grading metric. + +--- + +## 11. ROAS held steady but profit dropped + +**Symptom.** Channel-level ROAS at 3x, stable. Profit on the same channel dropped 20% over the quarter. + +**Root cause.** The mix shifted toward lower-margin products. ROAS is a revenue metric; it does not see margin. The channel attracted bargain hunters at lower margin, holding ROAS but cutting profit. + +**Fix.** Track contribution-margin ROAS, not gross-revenue ROAS. The contribution-margin view catches the mix shift the gross view hides. + +**Prevention.** Build margin-aware reporting from the start. Most teams default to gross revenue; the move to contribution margin pays for itself within a quarter. + +--- + +## 12. Agency reported a 4x ROAS month + +**Symptom.** External agency claims a 4x ROAS for the month. Team accepts the number. + +**Root cause.** Whose number? Platform-reported, warehouse-attributed, or model-adjusted? Agencies often report the most generous number (their incentive). Without specifying the attribution methodology, the 4x ROAS is unreadable. + +**Fix.** Demand the attribution methodology in every agency report. Reconcile against the warehouse before presenting to leadership. + +**Prevention.** Build attribution-methodology specification into the agency contract. Reports must include the model, the window, and the source of conversion data. The contract that does not specify produces reports that cannot be evaluated. + +--- + +## The pattern across all twelve + +Most paid media interpretation failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale ROAS at the cost of LTV. Pause an underperformer at the cost of total volume. Trust platform-reported attribution at the cost of incremental truth. + +The fix at the meta level. Decide on the success metric (warehouse-attributed CAC, LTV-CAC ratio, contribution-margin ROAS) and the guardrails (volume, frequency, customer-cohort quality, brand metrics) before reading any dashboard. Pull back the moment a guardrail breaks, even if the success metric still looks fine. The dashboard is a tool, not the truth; the warehouse plus quarterly incrementality testing is closer to truth. diff --git a/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md b/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md new file mode 100644 index 0000000..1066402 --- /dev/null +++ b/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md @@ -0,0 +1,114 @@ +# Dashboard reconciliation patterns + +The single-source-of-truth pattern for paid media reporting. Warehouse as canonical; platforms as in-flight signals. + +The principle. Sum-of-platform-reports is always greater than reality because every platform claims credit for conversions other platforms also touched. Reporting platform-summed numbers as fact in board decks is the most expensive error in paid media analytics. + +--- + +## The three-layer reporting model + +**Layer 1: platform metrics.** Use for in-flight optimization only. Ad-set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +**Layer 2: warehouse multi-touch attribution.** Use for cross-platform comparison and channel-level decisions. Each conversion gets attributed across all platforms that touched the path. Pick one model (last-click, first-click, linear, U-shaped, DDA) and standardize across the team. + +**Layer 3: marketing-mix modeling (MMM) at scale.** Use for budget allocation across channels. MMM treats spend as input and revenue as output; it does not rely on platform-reported attribution at all. The strongest defense against platform self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## Blended CAC + +The board-deck number. Resistant to attribution debates because it does not require choosing an attribution model. + +**Formula.** + +``` +Blended CAC = (total ad spend across platforms) / (total new customers from warehouse) +``` + +**Worked example.** + +In Q4, the team spent $200K total: $80K on Google Ads, $70K on Meta, $30K on LinkedIn, $20K on TikTok. The warehouse shows 1,250 new customers in Q4 from all sources (paid, organic, direct, referral). + +But the team needs to attribute the new customers to paid specifically. Two ways to do this: + +1. **Approximate.** Assume the proportion of paid-attributed customers in the warehouse roughly equals the proportion that paid contributed to traffic. If 60% of traffic in Q4 was paid-attributed, then 60% of 1,250 equals 750 paid-acquired customers. Blended paid CAC: $200K / 750 = $267. +2. **Precise.** Use the warehouse's multi-touch attribution to credit paid channels with a fraction of each conversion. Sum the paid-attributed share across all conversions; that becomes the denominator. + +The precise version is better when available. The approximate version works when the warehouse data is incomplete. Both produce a number that does not double-count across platforms. + +--- + +## The board-deck pattern + +Three rules for reporting paid media numbers to leadership. + +1. **Lead with blended CAC, not channel CAC.** Channel CAC depends on attribution model; blended CAC does not. Stakeholders not in the weeds on attribution find blended CAC easier to compare across quarters. +2. **Show the range.** Report the conservative view (last-click) and the generous view (linear or DDA) for any high-stakes channel decision. The range tells stakeholders what they are not learning. +3. **Always label the source.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions per Meta's 7-day-click attribution; warehouse-attributed: 540" is honest. + +A worked example board slide. + +``` +Q4 paid media performance + +Total spend: $200K (vs $185K Q3, +8%) +New customers from paid (warehouse-attributed): 750 (vs 680 Q3, +10%) +Blended paid CAC: $267 (vs $272 Q3, -2%) + +Channel CAC (warehouse-attributed, last-click): + Google: $240 (40% of new customers) + Meta: $290 (35% of new customers) + LinkedIn: $480 (15% of new customers) + TikTok: $180 (10% of new customers) + +Platform-reported CAC (for in-flight context, not board decision): + Google: $190 (Google reports 26% more attributed conversions than warehouse) + Meta: $210 (Meta reports 38% more) + LinkedIn: $475 (roughly aligned) + TikTok: $135 (TikTok reports 33% more) + +Quarterly incrementality test result (geo holdout, October): + Brand search: 12% incremental (95% CI: 6-18%). Reduced spend 30%; CAC dropped. + Meta retargeting: 31% incremental (95% CI: 22-40%). Maintained spend; CAC view adjusted. +``` + +The slide tells the truth: the warehouse number is the canonical CAC, the platform numbers are inflated, the incrementality test confirms which channels are real. + +--- + +## Reconciliation cadence + +**Weekly.** Pull platform-reported numbers and warehouse numbers. Confirm the sum-of-platforms vs warehouse ratio is in the expected range. A sudden divergence means a tracking break, an attribution-model change, or a platform reporting bug. Investigate. + +**Monthly.** Deeper reconciliation. Compare channel-level attribution across last-click, first-click, and the team's chosen model. Identify channels whose ranking changes by model. + +**Quarterly.** Run an incrementality test on the highest-spend channel. Update the channel-level CAC adjustment factor based on the test result. + +--- + +## Common reconciliation mistakes + +**Reporting platform-summed conversions to the board.** The most common error. The board sees "1,600 conversions across paid channels" when the warehouse says 950. The team gets caught when someone divides revenue by 1,600 and gets a CAC that does not match the P&L. + +**Comparing platforms on platform-reported CAC.** Each platform's CAC is computed against a different attribution window and a different set of self-attribution biases. Compare on warehouse-attributed CAC instead. + +**Treating "lift" as incrementality without a controlled test.** A campaign that ran during a period of overall conversion growth gets credit for "lift" that was actually seasonality or organic momentum. Lift requires a control group; otherwise it is correlation reported as causation. + +**Updating attribution models mid-quarter.** Switching from last-click to DDA mid-quarter makes the quarter's data uninterpretable. Pick a model for the quarter; switch only at quarter boundaries with a documented changelog. + +**Reporting blended CAC without naming the time window.** "$267 blended CAC" depends on whether you measured over 30, 60, or 90 days. Pin the window. + +--- + +## When the platforms agree more than usual + +A useful diagnostic. If platform-reported sums match warehouse total within 10%, something has changed. Possibilities: + +- The team set up Conversions API on Meta or server-side tagging on Google, which improved tracking precision. +- The mix shifted toward branded search, where attribution overlap is lower. +- One platform's conversion volume dropped significantly (saturation, fatigue, or campaign issue). + +Investigate any sudden alignment. The platforms diverging is the normal state; alignment usually has a cause worth understanding. diff --git a/skills/ads-performance-analytics/references/incrementality-testing-playbook.md b/skills/ads-performance-analytics/references/incrementality-testing-playbook.md new file mode 100644 index 0000000..a52ea6c --- /dev/null +++ b/skills/ads-performance-analytics/references/incrementality-testing-playbook.md @@ -0,0 +1,139 @@ +# Incrementality testing playbook + +The honest test in paid media analytics. If we had not run this ad, would we still have gotten the conversion? The answer above zero is the incremental contribution. + +The principle. Most paid media is not 100% incremental. Branded search bidding is often 5 to 20% incremental. Retargeting is often 20 to 40% incremental. Prospecting is often 50 to 90% incremental. The number that matters for spend decisions is the incremental rate, not the platform-reported attribution rate. + +--- + +## Method 1: Geo holdout + +The cleanest causal test for paid media at scale. + +**Setup.** Pick two regions with similar baseline conversion rates and demographic profiles (matched markets). Run the campaign in one region (test); turn it off in the other (holdout). + +**Duration.** Two to four weeks minimum. Statistical power calculation upfront determines the right length given the spend scale and expected lift. + +**Analysis.** Compare conversions in test vs holdout, normalized by population. The difference is the incremental contribution. + +**Expected incremental rate ranges.** + +| Channel | Typical incremental rate | +|---|---| +| Branded search | 5 to 20% | +| Retargeting | 20 to 40% | +| Lookalike audiences | 40 to 70% | +| Cold prospecting | 50 to 90% | +| Awareness video | 30 to 60% | + +**Common pitfalls.** + +- Picking holdout regions with confounding factors (different competitive presence, weather event, retail launch). Confounded results are worse than no test. +- Stopping the test early when the data looks good. Pre-commit the duration and stick to it. +- Holding out for too long. A 6-week holdout in a small region is expensive in lost conversions; 2 to 4 weeks is usually enough at scale. + +--- + +## Method 2: Ghost bidding (Google) + +Google's own incrementality tool. The platform bids on a holdout share of impressions but does not actually serve the ad. The reported delta between served and ghost is incremental. + +**Setup.** Configure within Google Ads. Choose the campaigns and the holdout share (typically 5 to 20%). + +**Duration.** Two to four weeks. + +**Analysis.** Google reports incremental conversions directly. Cross-validate against your own warehouse measurement. + +**Pitfalls.** + +- The math is opaque to many teams. The output is a single incremental number; the underlying methodology is Google's. Trust but verify with a manual geo test on the same campaign. +- Only available within Google Ads, not cross-channel. + +--- + +## Method 3: Conversion lift studies (Meta) + +Meta's incrementality tool. Splits audiences into test (sees the ad) and control (does not). Measures lift. + +**Setup.** Configure within Meta Ads Manager. Specify the campaign and the test-control split. + +**Duration.** Three to four weeks. Meta requires a minimum spend per study. + +**Analysis.** Meta reports incremental lift. The reporting includes statistical significance bands. + +**Pitfalls.** + +- The minimum spend requirement makes it expensive for small accounts. +- Only available within Meta, not cross-channel. +- Meta's interpretation tilts toward generous (their incentive). Cross-validate with geo holdout when possible. + +--- + +## Method 4: PSA tests + +Serve some users a public service announcement instead of your ad. Compare conversion rates. + +**Setup.** Run two parallel campaigns: one with your ad, one with a PSA (typically a charity or public-interest message). Match audiences. + +**Duration.** Three to six weeks. + +**Analysis.** Compare conversion rate of the PSA-exposed audience against the ad-exposed audience. The difference is incremental. + +**Pitfalls.** + +- Ethically and brand-wise, choose PSAs that align with brand values. +- Setup overhead is high. Reserved for legacy brands with deep budgets and serious incrementality questions. + +--- + +## Method 5: Switchback designs + +Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. + +**Setup.** Run for at least 8 weeks. Alternate weekly: on, off, on, off. Or alternate by audience segment. + +**Duration.** Eight to twelve weeks. Shorter switchbacks have low statistical power. + +**Analysis.** Difference in conversions between on-weeks and off-weeks, normalized for week-of-year and external variance. + +**Pitfalls.** + +- Confounded by exogenous factors (news, competitor activity, seasonality). Best for steady-state campaigns where the external context is stable. +- Audience contamination: users who saw the ad in week 1 may convert in week 2 even when the campaign is off. The contamination dilutes the measured incremental rate. + +--- + +## Choosing the right method + +| Constraint | Recommended method | +|---|---| +| Single platform, want quick answer | Platform-native (ghost bidding for Google, conversion lift for Meta) | +| Cross-platform incremental test | Geo holdout | +| Small account, limited budget | Geo holdout in two small matched markets | +| Long campaign cycle, steady-state | Switchback | +| Brand or awareness channel | PSA test or geo holdout | +| Regulated industry, ethics concern | Geo holdout (no PSA) | + +The default. Geo holdout. It is the most honest causal test, works cross-channel, and produces results that are interpretable without trusting the platform's methodology. + +--- + +## How to run a geo holdout step by step + +1. **Pick matched markets.** Use designated market areas (DMAs) or postal-code-level regions with similar baseline conversion rates and demographic profiles. Aim for at least three test and three holdout regions for statistical power. +2. **Calculate statistical power.** Given the expected lift and the regional conversion volume, can the test detect the effect? If the regions are too small, the test is underpowered and inconclusive results are likely. +3. **Pre-commit the analysis window.** Define the start date and end date before the test begins. Do not adjust based on early results. +4. **Run the test.** Campaign on in test regions; off in holdout. No mid-test changes. +5. **Wait for the full window.** Analyzing early produces noise. +6. **Compute the delta.** Conversions in test minus conversions in holdout, normalized by population. The delta divided by spend is the incremental CPA. Compare against the platform-reported CPA; the gap is the over-attribution. +7. **Report incremental contribution.** Do not report platform-reported CAC alongside warehouse CAC and incremental CAC without labeling. The unit of measurement matters as much as the number. + +--- + +## Cadence + +For accounts spending $25K+ per month, run incrementality tests at least quarterly on the highest-spend channels. The cost of the test is small relative to the cost of running un-incremental spend at scale. + +For accounts under $25K per month, annual or semi-annual tests are typically enough. The test cost vs the spend savings does not pencil out as often. + +The discipline. Schedule the tests. Do not wait for a "we should test this" moment; the moment never comes voluntarily. diff --git a/skills/ads-performance-analytics/references/metric-definitions-glossary.md b/skills/ads-performance-analytics/references/metric-definitions-glossary.md new file mode 100644 index 0000000..ee569ff --- /dev/null +++ b/skills/ads-performance-analytics/references/metric-definitions-glossary.md @@ -0,0 +1,83 @@ +# Metric definitions glossary + +The paid media metrics that show up on every dashboard, with explicit definitions, formulas, and the common pitfalls in usage. + +The point of an explicit glossary. Two teams using the same metric name often compute different numbers. "Conversion rate" might mean clicks-to-conversion or impressions-to-conversion or unique-users-to-conversion. The team that does not pin definitions ends up arguing about numbers that are not the same number. + +--- + +## Volume metrics + +**Impressions.** Count of times an ad was displayed. Includes the same user seeing the ad multiple times. + +**Reach.** Count of unique users who saw the ad. Always less than or equal to impressions. + +**Frequency.** Impressions divided by reach. The average number of times a unique user saw the ad. Above 4 to 5 per week is the fatigue alarm. + +**Clicks.** Count of clicks on the ad. Some platforms count "outbound clicks" (which leave the platform) separately from "all clicks" (which include in-platform interactions like saves and shares). Use outbound for direct response. + +--- + +## Cost metrics + +**CPC (cost per click).** Spend divided by clicks. Formula: `spend / clicks`. The cost of one click; not the cost of one conversion. Conflating them is the most common reporting error. + +**CPM (cost per thousand impressions).** Spend divided by (impressions / 1000). Formula: `spend / (impressions / 1000)`. The cost of reach. Useful for comparing platforms on awareness efficiency. + +**CPA (cost per acquisition).** Spend divided by conversions. Formula: `spend / conversions`. The variant where "conversion" is defined matters; the same campaign reports different CPAs depending on whether the conversion is a click, a lead form submission, a purchase, or a paid customer. + +**ROAS (return on ad spend).** Revenue from ad-attributed conversions divided by spend. Formula: `attributed revenue / spend`. NOT profit-divided-by-spend. ROAS is a revenue metric, not a profit metric. A 3x ROAS at 30% margin is a 0.9x return on cost; the ROAS reading on its own is misleading. + +**MER (marketing efficiency ratio).** Total revenue divided by total marketing spend, across all channels. Formula: `total revenue / total marketing spend`. The most honest top-line number; resistant to per-channel attribution debates. + +**Blended CAC.** Total ad spend divided by total new customers from warehouse. Formula: `total ad spend / new customers from warehouse`. The board-deck number. Channel-level CAC depends on attribution; blended CAC does not. + +--- + +## Conversion metrics + +**Conversion.** The event the campaign optimizes for. Definition varies. Always document: which event, what window, which attribution model. Without these three, "conversions = 800" is unreadable. + +**Conversion rate.** Conversions divided by something. The denominator changes the meaning. Click-through conversion rate (`conversions / clicks`) is different from impression conversion rate (`conversions / impressions`) which is different from unique-user conversion rate (`conversions / reach`). Pin the denominator at every report. + +**Conversion window.** The maximum time between the ad event (click or view) and the conversion for which the platform takes credit. Meta default: 7-day click plus 1-day view. Google default: 30-day click plus 1-day view. Different windows mean different reported counts from the same activity. + +**View-through conversion.** A conversion attributed to an ad the user saw but did not click. Counted by Meta and Google. Often half the platform-reported conversions are view-through. Treat as a soft signal of awareness contribution, not as direct response measurement. + +**Modeled conversion.** A statistically estimated conversion when actual tracking is blocked (most commonly iOS users on Meta after ATT). The platform models what the conversion would have been based on aggregated data. Modeled is an estimate, not a measurement; precision is low. + +--- + +## Customer-value metrics + +**LTV (lifetime value).** Total revenue from a customer over their relationship with the brand. Many definitions; the right one for paid media analytics is gross revenue or contribution margin, not unit count. Pair with CAC for the LTV:CAC ratio. + +**LTV:CAC ratio.** LTV divided by CAC. Formula: `LTV / CAC`. The unit-economics test. 3:1 is the venture-capital benchmark; the right number for any specific business depends on payback period and gross margin. + +**Payback period.** Months until cumulative revenue from a customer equals the CAC to acquire them. The cash-flow companion to LTV:CAC. Investors care about payback; operators care about both. + +**AOV (average order value).** Revenue divided by order count. Formula: `revenue / orders`. Useful for e-commerce; less for subscription. The number that turns "increased conversion rate" into "increased revenue." + +--- + +## Engagement metrics (less direct) + +**CTR (click-through rate).** Clicks divided by impressions. Formula: `clicks / impressions`. Useful for hook quality. Less useful for conversion quality; high CTR with low conversion rate means the hook is too aggressive for the offer. + +**Hide ratio (negative feedback).** Count of users who explicitly hid or marked the ad as not-interested, divided by impressions. Above 1.5% is the alarm; the platform algorithm will throttle delivery to that audience. + +**Engagement rate.** Likes plus comments plus shares plus saves divided by impressions. Useful for organic-style content; less directly tied to performance for paid. + +--- + +## Common pitfalls + +**Treating ROAS as profit.** ROAS is revenue-divided-by-spend. Profit-divided-by-spend is "return on ad investment" or "ROI." Confusing the two leads to greenlit campaigns that lose money on every conversion. + +**Ignoring conversion window in cross-platform comparisons.** Meta's 7-day-click count is not comparable to Google's 30-day-click count without normalization. + +**Treating frequency as a vanity number.** Frequency above 4 to 5 per week is a fatigue signal. Many teams celebrate high frequency as proof of "audience saturation"; it is the inverse. + +**Using CPA when conversion definitions differ across campaigns.** A search campaign with a "lead-form-submission" conversion has a CPA in different units from a display campaign with a "purchase" conversion. Compare campaign-level CPA only when the conversion event matches. + +**Confusing modeled conversions with measured conversions.** Modeled is an estimate; measured is a count. Treating the two as interchangeable produces false confidence in the size of the effect. diff --git a/skills/ads-performance-analytics/references/platform-reporting-quirks.md b/skills/ads-performance-analytics/references/platform-reporting-quirks.md new file mode 100644 index 0000000..363477b --- /dev/null +++ b/skills/ads-performance-analytics/references/platform-reporting-quirks.md @@ -0,0 +1,108 @@ +# Platform reporting quirks + +Per-platform reporting behaviors that affect how to read the numbers. The platforms do not agree on what counts as a conversion or how to credit it; reading their dashboards as truth is the most expensive error in paid media analytics. + +--- + +## Google Ads + +**Default attribution model.** Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on machine learning. Single-touch attribution (last-click) is available but no longer the default. + +**Conversion windows.** Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA4 reports by default; this produces the typical 1.3 to 1.5x conversion overcount versus GA4 for the "Google Ads" channel. + +**Modeled conversions.** Google models conversions for users with consent restrictions or cross-device gaps. Modeled volume can be material in iOS-heavy traffic. Modeled is an estimate; do not treat with the precision you would treat directly observed conversions. + +**Performance Max black box.** PMax does not expose keyword-level, placement-level, or audience-level performance directly. The platform manages allocation across Search, Shopping, Display, YouTube, Discover, and Gmail. Levers you have: budget, asset groups (creative quality), audience signals (Customer Match seeds), and exclusions (account-level negatives). + +**Branded search cannibalization in PMax.** PMax includes Search by default. It will harvest branded queries you would have ranked for organically. Add account-level negative keywords for branded queries to prevent paid cannibalization. + +**Lost Impression Share metrics.** Search exposes "Lost IS (rank)" and "Lost IS (budget)" to indicate why your ad did not show. Lost IS rising is the leading indicator that competition increased or budget became constrained. + +**Search-term reports.** The list of actual queries that triggered your ad, vs your keyword targeting. Underused. Audit monthly to find irrelevant queries (negative keyword candidates) and high-performing queries you might want to add as exact-match keywords. + +--- + +## Meta (Facebook and Instagram) + +**Default attribution.** 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +**iOS 14.5+ impact.** App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated) and Conversions API (CAPI, server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +**Conversions API necessity.** CAPI sends server-side events directly from your backend to Meta, bypassing the browser-pixel restrictions. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. Without CAPI, the platform's optimization signal degrades significantly on iOS-heavy audiences. + +**View-through attribution overcount.** View-through counts impressions even when the user did not click. Often half the reported conversions on Meta are view-through. Useful as awareness signal; misleading for performance optimization. + +**Modeled conversions in iOS reports.** Meta reports modeled conversions inline with directly observed ones unless you filter explicitly. Use the breakdown view to disaggregate by attribution type (1-day click, 7-day click, 1-day view, modeled). + +**Frequency reporting at the ad set level.** Meta exposes frequency in the Ads Manager. Use it as the primary fatigue signal; CTR decay is downstream of frequency rising. + +**Negative feedback rate.** Meta exposes "negative feedback rate" as a customizable column. Above 1.5% is the alarm; the algorithm penalizes high-feedback creatives by reducing reach. + +--- + +## LinkedIn + +**Default attribution.** 30-day click and 7-day view-through. + +**Why the longer windows.** B2B buying cycles are longer than B2C. The 30-day-click window matches the typical B2B consideration cycle. Comparing LinkedIn's reported numbers against Meta's 7-day-click numbers without normalizing is comparing different definitions. + +**Cross-device gaps.** LinkedIn reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair LinkedIn paid reports with self-reported attribution surveys when the offer is high-consideration B2B. + +**Lead Gen Forms reporting.** Form submissions count as conversions regardless of downstream lead qualification. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. Many leads are accidental or low-quality. + +**Demographic insights.** LinkedIn's demographic reporting (industry, job seniority, company size, function) is unique to the platform. Use it for audience refinement; the data is not available cleanly on other platforms. + +**Cost insights.** LinkedIn's CPM tends to be 3 to 10x higher than B2C platforms because of the audience precision premium. The justification is B2B LTV; lower-LTV offers cannot make LinkedIn math work. + +--- + +## TikTok + +**Default attribution.** 7-day click and 1-day view-through, similar to Meta. + +**Video-completion-based attribution.** TikTok counts conversions even when the user did not click but watched the full video. This is unique among the platforms covered here. The signal is real for awareness; it inflates direct-response numbers. + +**iOS impact, less mature modeling.** TikTok faces similar ATT-driven tracking gaps as Meta. The modeling is less mature, which means iOS-heavy audiences see more under-reporting on TikTok than on Meta. + +**Spark Ads attribution overlap.** Spark Ads boost organic posts. Engagement on the boosted version shows up in both organic and paid surfaces. Be careful not to double-count when reconciling against organic engagement reports. + +**Spark Ads vs paid creative differential.** Spark Ads consistently outperform pure paid creative on TikTok because they retain organic engagement signals. A team comparing CPMs of Spark vs paid will see Spark consistently lower; the difference is real, not a reporting artifact. + +**Trend-based volatility.** TikTok performance is more sensitive to trending sounds and formats than other platforms. Reporting comparisons across long time periods are less reliable because the platform itself shifted. + +--- + +## Programmatic and Display + +**Viewability gates.** Programmatic display sells impressions, but only "viewable" impressions count toward billed performance. The Media Rating Council (MRC) standard is 50% of pixels in view for 1 second (display) or 2 seconds (video). Below this threshold, the impression should not be billed. + +**Fraud filters.** Programmatic exposes fraud-detection metrics. Without fraud filtering, 10 to 30% of programmatic impressions are bot or fraudulent traffic. Use vendors like DoubleVerify or IAS for filtering. + +**Attribution decay.** Programmatic display's incremental rate is usually 5 to 20%. Most clicks come from users who would have converted from other channels anyway. Treat programmatic as awareness; do not optimize for direct response unless the incrementality test confirms it. + +--- + +## Cross-platform interference + +A specific quirk worth a dedicated callout. + +**The mechanism.** Two platforms claim the same conversion. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). The same revenue event shows up twice in the platform totals. + +**The detection.** Sum-of-platforms exceeds total conversions in the warehouse. If platform-reported sum is 1.5 to 3x the warehouse total, you have heavy cross-platform double-counting. + +**The defense.** Warehouse as canonical for board reporting. Platform reports for in-flight tuning of the platform's own levers. MMM at scale to estimate true cross-channel contribution. + +--- + +## Reporting differences in numbers + +A typical mid-stage account has the following attribution gap pattern across platforms. + +- Google Ads reports: 1.3 to 1.5x what GA4 reports for the "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA4 reports for the "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA4 for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA4 reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/skills/after-action-report/SKILL.md b/skills/after-action-report/SKILL.md new file mode 100644 index 0000000..d1690cc --- /dev/null +++ b/skills/after-action-report/SKILL.md @@ -0,0 +1,282 @@ +--- +name: after-action-report +description: "Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings." +category: operations +catalog_summary: "Post-mortems, retros, learnings documentation" +display_order: 3 +--- + +# After-Action Report + +Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document. + +This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`. + +--- + +## When to use + +- After any incident (any severity) +- After every major launch +- At the end of a project (sprint retro, quarterly retro, project closeout) +- When a recurring issue has happened enough times to demand investigation +- When a decision didn't work out and the team wants to learn + +## When NOT to use + +- During an active incident (use `incident-response`) +- For pre-launch planning (use `launch-runbook`) +- For one-off bug fixes that don't merit broad analysis + +--- + +## Required inputs + +- The event being analyzed (incident, launch, project) +- A timeline reconstructed from logs, chat, tickets +- Participant accounts of what they observed and did +- Outcomes and impact (what actually happened to users, the business) + +--- + +## The framework: blameless analysis + +The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones. + +### What blameless means + +- Focus on systems, not individuals +- Assume everyone made reasonable decisions given what they knew at the time +- The question is "why was this decision reasonable to make?" not "who screwed up?" +- Fixing the system means the next person in that situation succeeds where this person didn't + +### What blameless does not mean + +- No accountability (action items still have owners) +- No hard truths (sometimes the system is broken in obvious ways) +- No standards (some patterns of failure are individual, not systemic) +- No discomfort (real reflection is uncomfortable) + +--- + +## The framework: 6 sections + +A complete AAR covers six sections. + +### 1. Summary + +A 2 to 3 paragraph overview. Captures: + +- What happened +- Impact (users, business, time) +- Root cause (in plain language) +- Top action items + +This is what executives read. Anyone who reads only this section should leave with the most important information. + +### 2. Timeline + +A reconstructed timeline of events. + +For incidents: +- T-0: Detection +- T+X: Acknowledgment +- T+Y: Severity assessed, IC assigned +- T+Z: Investigation began +- ... mitigation, communication, resolution events +- T+N: Resolution declared + +For launches: +- Pre-launch decisions and milestones +- Launch day events +- Post-launch monitoring observations + +For projects: +- Major milestones, decisions, pivots +- Both planned and emergent + +The timeline is the source of truth. Disagreements about what happened get resolved here. + +### 3. Root cause analysis + +What caused this, in plain language. + +Use one or both of: + +**Five whys.** Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology. + +Example: +- Why did the site go down? Database connection pool exhausted. +- Why was the pool exhausted? Background job opened too many connections. +- Why did the background job open too many connections? Connection cleanup code didn't run on errors. +- Why didn't cleanup run on errors? Original code review didn't cover error paths. +- Why didn't the review cover error paths? No checklist for error handling in our review process. + +The fifth why often reveals the system fix. In this case: improve the review process. + +**Causal chain.** Multiple contributing factors that combined. + +- Factor 1: Background job opened too many connections (technical) +- Factor 2: Connection limit was set too low for actual traffic (configuration) +- Factor 3: No alert on connection pool saturation (monitoring) +- Factor 4: Recent traffic doubled without infra capacity review (process) + +No single fix addresses the incident. Multiple gaps need attention. + +### 4. Contributing factors + +Factors that didn't cause the event but made it worse, or removed safety nets that would have caught it. + +- Monitoring gaps +- Documentation gaps +- Process gaps +- Tooling gaps +- Knowledge gaps + +A "would have been caught earlier if..." factor. + +### 5. What went well + +Real lessons require capturing successes, not just failures. + +- What detection worked? +- What response worked? +- What decisions were good? +- What tools or processes performed as expected? + +This is not consolation. It's calibration. Things that worked here should be reinforced and replicated. + +### 6. Action items + +Specific, owned, dated. + +| Action | Owner | Due | Type | +|---|---|---|---| +| Add alert on connection pool saturation | [name] | [date] | Monitoring | +| Add error handling checklist to PR template | [name] | [date] | Process | +| Audit other background jobs for similar issue | [name] | [date] | Code | + +**Action item criteria:** + +- **Specific.** "Improve monitoring" is not actionable. "Add alert on connection pool saturation, threshold 80%, page on-call" is. +- **Owned.** A name. Not "the team." +- **Dated.** A real date. Not "soon." +- **Sized.** Roughly hours, days, or weeks of effort. +- **Closeable.** Definition of done is clear. + +Action items that don't close in their committed timeframe should re-surface in the next AAR. Patterns of unclosed actions point to deeper organizational issues. + +--- + +## Workflow + +### 1. Schedule the AAR + +Within 1 to 2 weeks of the event. Long enough that emotions cooled and facts gathered. Short enough that memories are fresh. + +For incidents: pre-decided in the response procedure. +For launches: schedule on the runbook. +For projects: schedule at project closeout. + +### 2. Gather inputs + +Before the meeting: + +- Reconstructed timeline (often the scribe's notes if there was one) +- Logs, chat transcripts, tickets, incident updates +- Individual accounts from each participant (written, before the meeting) +- Impact data (users affected, duration, revenue impact, etc.) + +### 3. Run the meeting + +Typical agenda (60 to 90 minutes): + +- Read the summary as drafted (5 min) +- Walk the timeline together. Add corrections. Resolve disagreements. (20 to 30 min) +- Discuss root cause. Use five whys or causal chain. (15 to 20 min) +- Discuss contributing factors. (10 min) +- Discuss what went well. (10 min) +- Identify action items. Owners and dates. (10 min) + +A facilitator runs the meeting. Often the IC for an incident, or a project lead for a project. The facilitator is not the scribe. + +### 4. Write the document + +Within a few days of the meeting. The full AAR includes all 6 sections. + +### 5. Distribute + +Internal: post in a known location. Make searchable. Reference in onboarding. + +For high-severity incidents: external summary may be appropriate (status page, customer email, public blog). + +### 6. Track action items + +Every action item should be tracked to closure. The next AAR re-surfaces unclosed ones. + +--- + +## Failure patterns + +- **Skipping the AAR for "small" incidents.** Patterns get missed. +- **Naming and shaming.** Real lessons get hidden when people fear blame. +- **Generic action items.** "Improve testing" instead of specific testing change. +- **Action items that never close.** Filed, forgotten. Same incident recurs. +- **Theater retrospectives.** Going through the motions without genuine reflection. +- **Skipping "what went well."** Misses calibration on what's working. +- **Blame externalized.** "Our vendor failed." OK, what's our system for vendor risk? +- **Single-person AAR.** One person writes the whole thing. Misses other perspectives. +- **AAR only for failures.** Successful launches deserve AARs too. Lessons from success are valuable. +- **Long delays.** Memories fade. Conversations cool. Get it done within 2 weeks. + +--- + +## Output format + +A markdown document at `aar-[date]-[event-name].md`. + +Structure: + +```markdown +# AAR: [Event name] + +**Date of event:** [YYYY-MM-DD] +**AAR date:** [YYYY-MM-DD] +**Severity / scope:** [SEV-1 / Major launch / Project closeout] +**Facilitator:** [Name] +**Participants:** [Names] + +## Summary +[2 to 3 paragraphs] + +## Impact +- Users affected: [number, segment] +- Duration: [time] +- Revenue / business impact: [if applicable] + +## Timeline +[Timestamped events] + +## Root cause analysis +[Five whys or causal chain] + +## Contributing factors +[List] + +## What went well +[List] + +## Action items +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| | | | | | + +## Lessons +[Reflections that don't fit elsewhere. Often the most quotable section.] +``` + +--- + +## Reference files + +- [`references/aar-template.md`](references/aar-template.md) - Fillable AAR template covering incidents, launches, and projects. diff --git a/skills/after-action-report/references/aar-template.md b/skills/after-action-report/references/aar-template.md new file mode 100644 index 0000000..0d37d24 --- /dev/null +++ b/skills/after-action-report/references/aar-template.md @@ -0,0 +1,296 @@ +# AAR Template + +Fillable after-action report template. Three variations: incident AAR, launch AAR, project closeout AAR. The structure is similar; the inputs and emphasis differ. + +--- + +## Universal sections (used in all three variations) + +### Header + +```markdown +# AAR: [Event name] + +**Type:** [Incident / Launch / Project] +**Date of event:** [YYYY-MM-DD or range] +**AAR date:** [YYYY-MM-DD] +**Severity / scope:** [SEV-1 / Major launch / Project closeout] +**Facilitator:** [Name] +**Participants:** [Names] +**Distribution:** [Internal only / Internal + customers / Public] +``` + +--- + +## Variation 1: Incident AAR + +### Summary + +> [2 to 3 paragraphs. What happened, what was the impact, what was the root cause, what are the top action items. Should stand alone for executives who read only this section.] + +### Impact + +- **Users affected:** [Number and segment. "All US users" or "Approximately 12% of paid customers in EU."] +- **Duration:** [Detection to resolution] +- **Severity:** [SEV-1 / 2 / 3 / 4] +- **Revenue impact:** [If quantifiable] +- **Customer-facing communication:** [What was said, when] +- **Regulatory implications:** [If any] + +### Timeline + +| Time | Event | Notes | +|---|---|---| +| T-X | [Pre-incident state, recent deploy, etc.] | | +| T-0 | [Detection event] | | +| T+5min | [Acknowledgment] | | +| T+10min | [Severity assessed, IC assigned] | | +| T+Xmin | [Investigation milestone] | | +| T+Ymin | [Mitigation applied] | | +| T+Zmin | [Verification] | | +| T+Nmin | [Resolution declared] | | +| T+Hours | [Customer comms, post-incident] | | + +Timeline source: [Logs, chat, monitoring, IC notes] + +### Detection + +- **How was it detected?** [Alert / customer report / internal observation] +- **Time to detection:** [From event start to detection] +- **Was detection adequate?** [Should we have detected this faster? How?] + +### Response + +- **Time to acknowledgment:** [Detection to acknowledgment] +- **Time to mitigation:** [Detection to mitigation] +- **Time to resolution:** [Detection to resolution] +- **Were the right people involved?** [Yes / No, why] +- **Did the response procedure work?** [Yes / No, what gaps] + +### Root cause analysis + +**Surface symptom:** [What users experienced] + +**Five whys:** + +1. Why did [symptom] happen? [Answer] +2. Why did [Answer 1] happen? [Answer] +3. Why did [Answer 2] happen? [Answer] +4. Why did [Answer 3] happen? [Answer] +5. Why did [Answer 4] happen? [Answer - often the system fix] + +**Or, causal chain (multiple contributing factors):** + +- Factor 1 (technical): [Description] +- Factor 2 (configuration): [Description] +- Factor 3 (process): [Description] +- Factor 4 (monitoring): [Description] + +### Contributing factors + +What didn't cause this but made it worse, or removed safety nets: + +- [Factor] +- [Factor] +- [Factor] + +### What went well + +- [Detection mechanism that worked] +- [Decision that was correct] +- [Tool that performed as designed] +- [Communication that was effective] + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | [Name] | [Date] | Monitoring | Open | +| [Specific action] | [Name] | [Date] | Code | Open | +| [Specific action] | [Name] | [Date] | Process | Open | +| [Specific action] | [Name] | [Date] | Documentation | Open | +| [Specific action] | [Name] | [Date] | Training | Open | + +### Lessons + +[Reflections beyond the action items. Often the most-quoted section in the long term.] + +--- + +## Variation 2: Launch AAR + +### Summary + +> [2 to 3 paragraphs. What launched, did it go well, what surprised us, what should we do differently next time.] + +### Outcomes + +- **What launched:** [Specific scope] +- **Launch window:** [Planned vs actual] +- **Maintenance time:** [If applicable] +- **Issues during launch:** [Count and severity] +- **Rollback?:** [Yes / No] +- **Post-launch incidents:** [In the first 7 days] +- **Business outcomes:** [If measurable, e.g., conversion impact] + +### Timeline + +| Time | Event | Notes | +|---|---|---| +| Pre-launch | [Major decisions, milestones] | | +| Launch start | | | +| Cutover steps | [Each step with timing] | | +| Verification | | | +| Public announcement | | | +| First 24 hours | [Notable observations] | | +| First week | [Notable observations] | | + +### What went according to plan + +- [Step that worked exactly as runbook described] +- [Communication that was clear] +- [Decision that proved correct] + +### What deviated from plan + +- [Deviation, why, what we did] +- [Deviation, why, what we did] + +### What surprised us + +- [Unexpected observation] +- [Unexpected user behavior] +- [Unexpected technical behavior] + +### What we'd do differently + +- [Change to runbook for next launch] +- [Change to pre-launch QA] +- [Change to communication plan] + +### What we'd repeat + +- [Practice that worked, want to keep] + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | | | | | + +### Lessons + +[Reflections.] + +--- + +## Variation 3: Project closeout AAR + +### Summary + +> [2 to 3 paragraphs. What we set out to do, what we delivered, what we learned, what comes next.] + +### Goals vs outcomes + +| Goal | Outcome | Notes | +|---|---|---| +| [Original goal 1] | [Met / Partially met / Not met] | [Notes] | +| [Original goal 2] | [Met / Partially met / Not met] | [Notes] | +| [Original goal 3] | [Met / Partially met / Not met] | [Notes] | + +### Timeline + +| Phase | Planned | Actual | Variance | +|---|---|---|---| +| Discovery | | | | +| Design | | | | +| Build | | | | +| QA | | | | +| Launch | | | | + +### What went well + +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] + +### What didn't go well + +- [Pain point with system-level explanation] +- [Pain point with system-level explanation] + +### What surprised us + +- [Surprising input from users / market / internal] +- [Surprising scale / complexity / opportunity] + +### What we'd do differently + +For people working on similar projects in the future: + +- [Specific change] +- [Specific change] +- [Specific change] + +### Decisions in retrospect + +| Decision | Was it right? | Why or why not | +|---|---|---| +| [Major decision 1] | | | +| [Major decision 2] | | | +| [Major decision 3] | | | + +### Action items + +| Action | Owner | Due | Type | Status | +|---|---|---|---|---| +| [Specific action] | | | | | + +### Lessons + +[Reflections.] + +### Recommendations for next phase + +[If the project continues. Otherwise, recommendations for what builds on this work.] + +--- + +## Universal facilitator guide + +### Before the meeting (pre-work) + +- Send the timeline draft to all participants +- Ask each participant to write their personal account of what they observed and did (1 to 2 paragraphs each) +- Compile contributing data: logs, metrics, ticket counts, customer feedback +- Send participants the agenda 24 hours in advance + +### During the meeting + +- Set the tone in the first 60 seconds: "This is blameless. Focus on systems, not individuals." +- Walk the timeline. Add corrections from participants. +- For root cause: ask "why" until the answers stop being substantive. Note when it shifts from technical to process. +- For action items: insist on specificity, owner, date. +- Don't let the meeting become a debugging session. Investigation happened before; this is for analysis. +- Capture the document live where possible. Edits in real time prevent recall errors. + +### After the meeting + +- Polish the document within 48 hours +- Distribute to broader audience +- File action items into a tracking system +- Schedule follow-up to verify action items closed (typically 30 days out) + +--- + +## Common AAR anti-patterns + +| Anti-pattern | What it looks like | Better | +|---|---|---| +| Naming and shaming | "Sarah deployed the bug" | "Our review process didn't catch the issue. Why? What checklist or test would have?" | +| Generic actions | "Improve testing" | "Add a test for X scenario to the existing test suite by [date]" | +| No follow-through | Action items filed, never tracked | Action item review at next AAR; pattern of unclosed items surfaces | +| Skipping success | Only failures discussed | Equal time to what went well | +| Sole authorship | One person writes the AAR | Group discussion + sole author for polish | +| Long delay | AAR happens 2 months later | AAR within 2 weeks of event | +| Skipping minor incidents | "Not worth the time" | Patterns hide in the minors | diff --git a/skills/ai-content-collaboration/SKILL.md b/skills/ai-content-collaboration/SKILL.md new file mode 100644 index 0000000..d04119e --- /dev/null +++ b/skills/ai-content-collaboration/SKILL.md @@ -0,0 +1,281 @@ +--- +name: ai-content-collaboration +description: "How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy." +category: content +catalog_summary: "How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production" +display_order: 8 +--- + +# AI Content Collaboration + +A senior editorial leader's playbook for how humans and AI compose in content workflows. Pragmatic, tool-agnostic, honest about both what AI in the loop enables and what it threatens. + +Most content programs in 2026 use AI somewhere in the workflow. Pretending otherwise is dishonest; treating AI as a magic content factory is the failure mode this skill exists to prevent. The discipline is in between: knowing where AI legitimately accelerates, where humans must own, what hybrid patterns produce work that earns reader trust, and what crosses the line into AI slop or intellectual dishonesty. + +This skill is the WORKFLOW layer that composes with every other content skill. Briefs can be AI-assisted; hub architectures can be AI-assisted; programmatic SEO is almost always AI-involved; editorial QA now includes AI-content audit by necessity. The collaboration discipline applies to all production stages, not to a single artifact type. + +The voice is pragmatic and tool-agnostic deliberately. The methodology applies whether the AI in your loop is one of the major commercial models, an open-source model, or whatever ships next quarter. What stays constant is the workflow shape, the participation boundaries, the voice ownership question, and the ethical frame. What changes is which specific tool you reach for, which is implementation work that varies by team and budget. + +When to use this skill: building or refining an AI-content workflow, calibrating a team on consistent AI usage, addressing the "we use AI but our work feels generic" problem, designing disclosure policies, or working through the ethics of AI-assisted content production for a regulated or trust-sensitive context. + +--- + +## What this skill is for + +This skill spans the workflow layer of AI-assisted content production. It composes with all six other content-suite skills as the cross-cutting discipline. + +- `content-strategy` is program scope: what to produce. Strategy decisions can be AI-assisted; the program-level judgment stays human. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. Hub architecture can be AI-suggested; the architectural commitment stays human. +- `content-brief-authoring` is per-piece scope: briefs each piece. Briefs can be AI-drafted from research; the contract decisions stay human. +- `content-and-copy` is execution scope: writes each piece. Drafts can be AI-produced; voice and editorial judgment stay human. +- `programmatic-seo` is scaled scope: generates pages from data. AI generation is the dominant production model; sampling QA is the human gate. +- `editorial-qa` is gate scope: verifies before publish. AI-content audit is now a load-bearing gate; the audit's judgment stays human. +- This skill is workflow scope: how the human and AI layers compose across all six stages above. + +The audience: editorial leaders, content directors, content ops managers, agencies running AI-assisted production, in-house teams calibrating AI usage across writers. The voice is senior editorial leader to junior editor or content marketer. Pragmatic, honest, tool-agnostic. + +What is not in scope: specific prompts (those are implementation; teams develop their own), specific tool endorsements (the methodology applies regardless of which tool is in the loop), specific integration code (varies by stack and team). Tool categories appear when they earn methodology relevance; specific tools appear only as illustrations of categories, never as recommendations. + +--- + +## Humans own, AI accelerates + +The keystone framing. + +The pathology to avoid is treating AI as either a magic content factory (cheap, fast, scaled, output quality optional) OR as a forbidden intruder (purity gospel that does not survive contact with deadlines). Both readings produce bad work. + +The discipline that produces durable work: humans own the content; AI accelerates the work. Specifically: + +**Humans own.** Editorial judgment, voice, distinctive POV, fact accuracy, ethical decisions, what to publish versus what to kill, brand voice, narrative arc, tone calibration, reader empathy, claim verification. + +**AI accelerates.** Research synthesis, draft generation against a brief, copy edit suggestions, alternative phrasings, summary, transcription, quality-control automation at scale. + +The line. AI does work that the human directs and verifies. AI does NOT make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +The litmus test. If your AI-assisted piece publishes without a human being able to defend every claim, every position, and every word, you have crossed the line. The piece is AI's work, dressed in your byline. Readers eventually notice. + +--- + +## Where AI legitimately participates + +A non-exhaustive list of stages where AI in the loop is fine and often improves the work. + +- **Research synthesis.** AI condenses long-form sources into briefs the writer reads. Saves hours; the writer still reads and verifies. +- **Outline generation against a brief.** AI proposes an H2 / H3 structure from a brief; the editor approves or restructures. +- **First-draft generation.** AI produces a draft against an explicit brief; the human edits substantially. +- **Alternative phrasings.** AI offers 3 versions of a sentence; the human picks one or rewrites. +- **Copy edit suggestions.** AI catches typos, awkward phrasings, repetition. +- **Summary and abstraction.** AI condenses long pieces into TL;DRs. +- **Transcription.** AI transcribes interview audio; the human verifies. +- **Translation drafts.** AI produces a translation draft; a native speaker reviews and corrects. +- **Quality-control automation at scale.** AI flags pages in a programmatic SEO set that need human review. +- **Idea generation.** AI proposes 30 angles; the human picks 3. + +In each case, AI accelerates work the human still owns. The acceleration is real; the ownership stays unchanged. + +Detail in [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md). + +--- + +## Where humans must own + +The boundary list. + +- **Editorial judgment.** What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. +- **Voice.** Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution. +- **Fact verification.** Every claim, every statistic, every quote, every named person. AI hallucinates; humans verify. +- **Ethical decisions.** What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. +- **Reader empathy.** What the reader actually needs from this piece, not what the algorithm scores well. +- **Quote attribution.** Real people who actually said the thing, with consent where relevant. +- **Tone calibration on hard topics.** Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. +- **Narrative arc.** How the piece unfolds, where the reader's attention goes. AI produces shapes; humans choose them. +- **Final approval.** The human who signs off is accountable for what shipped. + +The "human in the loop" framing is necessary but insufficient. A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. Ownership requires the human to have made the actual decisions the piece embodies. + +--- + +## Hybrid workflow patterns + +Five patterns that work, with tradeoffs. + +**1. AI-first draft, human-edit-heavy.** AI produces a 90% draft; the human spends 60% of the time editing. Output: efficient for high-volume editorial; risks generic voice if editing is light. + +**2. Human-first outline + research, AI-draft, human-rewrite.** Human builds the outline and gathers research; AI drafts within that scaffold; human rewrites in voice. Output: preserves voice better; slower than AI-first. + +**3. AI-as-research-assistant, human-writes.** AI condenses sources into a brief; human writes the entire piece from the brief. Output: highest voice fidelity; slowest. + +**4. Human-writes, AI-as-editor.** Human drafts; AI suggests edits, alternative phrasings, copy edits; human accepts or rejects. Output: writer voice preserved; AI catches details. + +**5. AI-generates-at-scale, human-samples.** For programmatic SEO. AI generates thousands of pages; human samples 50 to 200 with editorial-qa discipline. Output: scaled production; depends entirely on template quality and sampling discipline. + +The pattern that fits depends on volume, voice sensitivity, team skill, and time budget. No pattern is "the right one"; pattern selection is a real decision that should match the production context. + +Detail in [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md). + +--- + +## Voice ownership preservation + +Voice is the dominant casualty of careless AI workflows. The patterns that preserve voice. + +- **Voice guidelines as prompt input.** Every AI generation includes the brand voice guidelines as context. Generic AI defaults regress without this. +- **Sample text as voice anchor.** Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. +- **Mid-draft voice check.** At the halfway mark of a long piece, have a human or a separate AI pass read for voice drift. Long AI generations regress halfway through almost always. +- **Final pass in human voice.** The human edits the closing sections in their own voice; this is where the piece's emotional register often lands. +- **Reject the bland.** Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The honest framing. Voice is the hardest thing to preserve in AI-assisted work and the easiest thing to lose. Programs that do not actively preserve voice end up with content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +Detail in [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md). + +--- + +## The AI slop problem + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. Cross-reference `editorial-qa`'s ai-content-audit-patterns reference for the detection patterns; this section addresses prevention. + +**Patterns that produce slop.** + +- AI does too much of the work (no real human direction or rewriting) +- Generic prompts (no brand voice context, no audience specificity, no anti-pattern guidance) +- No editorial judgment in the loop (AI generates, human glances, ship) +- Volume prioritized over quality (10x more pages can mean 10x more slop, not 10x more value) +- No iteration (first draft ships; no rewrite for voice) + +**Patterns that prevent slop.** + +- Strong briefs (per `content-brief-authoring`) +- Voice guidelines as prompt context +- Heavy human editing pass +- Iteration: AI draft, then human rewrite, then AI suggestions, then human final +- Editorial judgment at every gate + +The reader-detection problem. Readers can often sense AI-flavored content even when they cannot articulate why. Generic openings, predictable structures, "perfect" grammar that is emotionally flat. Slop loses reader trust over time even when individual pieces are not penalized. + +Detail in [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) and cross-reference editorial-qa's audit patterns. + +--- + +## Disclosure and transparency + +When should AI usage be disclosed to readers? + +The tiered framework. + +- **Always disclose.** Journalism, news reporting, attributed expert opinion, content where AI tools are the subject. +- **Default disclosure (consider context).** Thought leadership where the byline is doing trust work, regulated industries, content that influences purchase decisions. +- **Generally not necessary.** Marketing copy, descriptive product content, programmatic data pages, copy edit assistance only. +- **Clearly fine without disclosure.** AI as research assistant only; AI for transcription; AI for spelling and grammar suggestions. + +The principle. Disclose when the reader's understanding of the content's origin would change their trust in it. A bylined opinion piece purportedly by a named expert that is substantially AI-drafted is a trust violation; a product description on an ecommerce site that was AI-drafted is not. + +**Disclosure language patterns (when used).** + +- "AI tools assisted in research and drafting; the author edited and verified all claims." +- "This piece was generated programmatically from [data source]; reviewed by [team] before publish." +- Avoid hedging language like "may have used AI" or "could have been AI-assisted"; be specific or omit. + +Industry-specific norms vary. Major journalism organizations have published explicit AI usage standards. Content marketing has weaker norms but is moving toward disclosure for high-trust pieces. + +Detail in [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md). + +--- + +## Team training and calibration + +Inconsistent AI usage across a team produces inconsistent output. The discipline. + +- **Documented AI policy.** Which uses are approved, which require explicit permission, which are prohibited. +- **Calibration sessions.** Editors review AI-assisted pieces from multiple writers, surface differences, agree on standards. +- **Voice library updates.** As voice evolves, the prompts and sample text fed to AI evolve with it. +- **Quality benchmarks.** What does "AI-assisted but on-voice" look like for your brand? Document it with examples. +- **Tool standardization or intentional pluralism.** Team uses one tool consistently OR documents which tools fit which tasks. +- **Forbidden patterns list.** This team does not use AI for X (whatever X is for your context). +- **Onboarding.** New writers learn the AI policy and calibration in their first 2 weeks. + +The pathology. AI usage emerges informally, every writer develops their own patterns, output drifts, editors cannot pinpoint why pieces feel off. The discipline is making AI usage explicit, calibrated, and documented. + +Detail in [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md). + +--- + +## Ethics: training data, attribution, intellectual honesty + +AI tools were trained on copyrighted material. That is the simple ethical reality of every major LLM in 2026. The catalog's position on this question is not "AI use is unethical" (that would render the catalog itself hypocritical) but "intellectual honesty about AI involvement is non-negotiable." + +The principles. + +- **Do not pass AI work as fully human-written.** Bylined content where the byline implies human craft requires substantial human craft. +- **Do not claim AI did not help when it did.** False denials are worse than disclosure. +- **Do not generate content that closely mirrors copyrighted source material.** AI tools can produce near-replicas of training data when prompted carelessly; humans verify originality. +- **Attribute when borrowing.** Ideas, frameworks, statistics that came from specific sources get cited. +- **Do not fabricate quotes or expertise.** Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. +- **Be honest about AI capabilities and limits.** Do not oversell AI as more capable than it is. + +The intellectual-honesty frame supersedes any specific policy debate. Teams that treat AI usage with intellectual honesty produce content readers can trust over time. Teams that hide, deny, or rationalize lose trust eventually. + +Detail in [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md). + +- "We used AI and the content feels generic." Voice not preserved; not enough human rewriting. +- "Hallucinated facts made it to publish." Fact-verification gate skipped or rushed. +- "Different writers produce wildly different AI-assisted output." No team calibration. +- "Our AI-assisted SEO content got penalized." Slop volume plus thin templates plus no QA discipline. +- "We cannot tell what was AI versus human." No AI usage tracking; teams should document at the workflow level. +- "Readers complained about AI-flavored content." Slop reaching audience; intensify human craft pass. +- "We disclosed AI usage and lost credibility." Depends on context; disclosure is sometimes a trust gain, sometimes a loss; calibrate to audience norms. +- "Our AI tools changed and our content shifted." Over-coupled to one tool's specific behavior; methodology should be tool-agnostic. +- "We are producing 10x more content but the same audience growth." Volume was not the constraint that was binding; quality was. +- "The team is using AI inconsistently." Calibration sessions overdue. +- "An expert byline turned out to be substantially AI-drafted." Ethics breach; correct, disclose, recalibrate. + +--- + +## The framework: 12 considerations for AI content collaboration + +When designing or auditing an AI-assisted content workflow, walk these 12 considerations. + +1. **Humans own; AI accelerates.** Make this explicit in your workflow, not implicit. +2. **Participation boundaries.** Document where AI legitimately helps, where humans must own. +3. **Hybrid pattern selection.** Match the pattern to volume, voice sensitivity, time budget. +4. **Voice guidelines as prompt input.** Every AI generation includes brand voice context. +5. **Voice drift sampling.** Long pieces drift mid-way; sample throughout. +6. **Fact verification gate.** Every claim, every quote, every stat verified before publish. +7. **AI slop prevention.** Heavy human editing, strong briefs, iteration. +8. **Disclosure tiering.** Disclose when origin would change reader trust; calibrate to audience. +9. **Team calibration.** Documented policy, calibration sessions, voice library. +10. **Tool-agnostic methodology.** Workflow shape stays constant as tools change. +11. **Ethical floor.** Intellectual honesty, no fabrication, no hidden AI in trust-sensitive work. +12. **Final accountability.** The human who signs off is accountable; AI does not sign off. + +The output of the framework is a workflow document the team can reference: AI participation rules named, hybrid pattern selected, voice preservation patterns specified, disclosure tier set, calibration cadence committed, ethical floor articulated, accountable signer named for each piece. + +--- + +## Reference files + +- [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md) - Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. +- [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md) - Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. +- [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md) - Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. +- [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) - What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. +- [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md) - Tiered disclosure framework, language patterns, industry norms. +- [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md) - Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. +- [`references/quality-calibration-with-ai-in-loop.md`](references/quality-calibration-with-ai-in-loop.md) - How editorial standards shift when AI is in the workflow. Same standards, different failure modes. +- [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md) - Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. +- [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: collaboration, not replacement + +AI in content workflows is neither magic nor menace. It is a category of tooling that, like every tooling category before it, rewards disciplined use and punishes careless use. The teams producing memorable AI-assisted content are the ones holding the line on human ownership, voice, fact accuracy, and intellectual honesty. The teams producing AI slop are the ones treating AI as a content factory. + +The discipline is not anti-AI; it is pro-craft. Craft was always what made content worth reading; AI does not change that, it just raises the cost of skipping it. + +When in doubt about whether an AI-assisted workflow is ready, ask: is human ownership specified, are participation boundaries documented, is voice preservation built into the prompt and review patterns, is fact verification a halt-condition, is disclosure tiered to audience trust, is the team calibrated, and is the ethical floor explicit? If yes to all of those, the workflow is ready. If no to any, the gap is where the program will produce slop and lose reader trust. diff --git a/skills/ai-content-collaboration/references/ai-participation-boundaries.md b/skills/ai-content-collaboration/references/ai-participation-boundaries.md new file mode 100644 index 0000000..0d6b20a --- /dev/null +++ b/skills/ai-content-collaboration/references/ai-participation-boundaries.md @@ -0,0 +1,131 @@ +# AI participation boundaries + +Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. + +The boundary list below is the operational expression of the keystone framing: humans own the content, AI accelerates the work. The list is not exhaustive; the principle is: AI does work the human directs and verifies, AI does not make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +--- + +## Where AI legitimately participates + +### Research synthesis + +AI condenses long-form sources (papers, interviews, prior reports, internal docs) into a research brief. The writer reads the brief, follows up on the citations the brief surfaced, and verifies anything that will become a load-bearing claim in the piece. + +The acceleration: hours of reading become minutes of reviewing. The retained ownership: the writer judges what is worth using, where the source is questionable, what additional research is needed. + +### Outline generation against a brief + +AI proposes an H2 / H3 structure based on the content brief and SERP analysis. The editor approves the outline, restructures it, or rejects it. + +The acceleration: the writer starts from a structure that fits the brief instead of from a blank page. The retained ownership: the editor decides whether the structure fits the audience and the publication. + +### First-draft generation + +AI produces a draft against an explicit brief. The human edits substantially. + +The acceleration: a 1,500-word draft in minutes that the human revises rather than composing from scratch. The retained ownership: the human chooses what to keep, what to rewrite, what to cut, what to add. A draft that ships unchanged is not collaboration; it is rubber-stamping. + +### Alternative phrasings + +AI offers 3 versions of a sentence, paragraph, or headline. The human picks one or rewrites. + +The acceleration: faster surfacing of options the writer might not have considered. The retained ownership: the writer chooses the option that fits the voice and the context. + +### Copy edit suggestions + +AI catches typos, awkward phrasings, repetition, weak connections between paragraphs. + +The acceleration: faster than a manual copy edit pass. The retained ownership: the editor decides which suggestions to accept; some of what AI flags as awkward is actually deliberate stylistic choice. + +### Summary and abstraction + +AI condenses long pieces into TL;DR summaries, executive summaries, or social media captions. + +The acceleration: faster TL;DR generation; useful for content systems that produce summaries at scale. The retained ownership: the human verifies the summary captures what matters and does not flatten the piece's distinctive points. + +### Transcription + +AI transcribes interview audio. The human verifies the transcription against the audio for accuracy, especially on names, technical terms, and quoted positions. + +The acceleration: hours of transcription become minutes of verification. The retained ownership: the human is responsible for what gets attributed; transcription errors that misquote sources are the human's accountability to catch. + +### Translation drafts + +AI produces a translation draft. A native speaker reviews and corrects. + +The acceleration: a translation starting point in seconds. The retained ownership: the native speaker is the source of truth on idiomatic correctness, cultural context, and brand-voice translation. + +### Quality-control automation at scale + +AI flags pages in a programmatic SEO set that need human review (per `editorial-qa`'s sampling discipline). + +The acceleration: automated check on every page; manual review focused on the flagged subset. The retained ownership: the editor decides what counts as a fail; the AI flags candidates, the human judges. + +### Idea generation + +AI proposes 30 angles on a topic; the human picks 3. + +The acceleration: faster brainstorm. The retained ownership: the human chooses which angles fit the brand and the audience. + +--- + +## Where humans must own + +### Editorial judgment + +What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. The judgment requires audience knowledge, brand context, and quality standards the AI does not have. + +### Voice + +Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution that the AI can mimic if shown samples but cannot originate. + +### Fact verification + +Every claim, every statistic, every quote, every named person. AI hallucinates plausible-but-fake claims; humans verify against authoritative sources. Fact verification is a halt-condition gate; pieces with unverified claims do not ship. + +### Ethical decisions + +What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. Ethics requires context, audience awareness, and accountability that the AI does not carry. + +### Reader empathy + +What the reader actually needs from this piece, not what the algorithm scores well. The reader's situation, knowledge, and emotional context shape the piece's job; the AI cannot model the specific reader the way a writer who has spent time with the audience can. + +### Quote attribution + +Real people who actually said the thing, with consent where relevant. AI hallucinates quotes; humans verify against the source. + +### Tone calibration on hard topics + +Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. A piece on bereavement should not read as if a chatbot wrote it. + +### Narrative arc + +How the piece unfolds, where the reader's attention goes, what the climax is, what the resolution is. AI produces shapes; humans choose them. + +### Final approval + +The human who signs off is accountable for what shipped. Accountability cannot be delegated to AI; the byline and the editorial chain stop at humans. + +--- + +## "Human in the loop" is not ownership + +The phrase "human in the loop" appears in many AI workflows. It is necessary but insufficient. + +A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. The piece's substance, voice, and judgment are still AI-produced; the human's role is signature only. + +Ownership requires the human to have made the actual decisions the piece embodies. Specifically: the human chose the angle, the human verified the facts, the human enforced the voice, the human made the editorial judgment calls that distinguish this piece from the AI's default output. + +The test. Could the human defend every claim, every position, and every word in the piece? If yes, the human owns it. If no, the human is rubber-stamping. + +--- + +## Methodology-level choices that stay in the public skill + +The list of where AI legitimately participates, the list of where humans must own, the "human-in-the-loop versus ownership" distinction, the verification-and-defense litmus test. + +## Implementation choices that stay internal + +The specific AI tools the team uses for each participation category (research synthesis tool, drafting tool, copy edit tool, transcription tool, translation tool, QC automation tool). The specific prompts the team has developed for each task category. The specific tracking system that records which AI participated in which piece. The specific review workflows that gate publish. These vary by team and stack. diff --git a/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md b/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md new file mode 100644 index 0000000..4e3df19 --- /dev/null +++ b/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md @@ -0,0 +1,134 @@ +# AI slop detection and avoidance + +What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. The detection patterns live in `editorial-qa/references/ai-content-audit-patterns.md`. This reference addresses prevention: what production patterns produce slop, what production patterns prevent it. + +--- + +## Patterns that produce slop + +### AI does too much of the work + +The pattern. The AI generates the entire piece; the human glances at it and ships. The piece reads as model-default because no human substantively rewrote it. + +The signal. Pieces ship in less time than they would take a human to write from scratch. Speed is not the problem; the problem is that the speed comes from skipped craft. + +### Generic prompts + +The pattern. The prompt is "write a 1,500-word blog post about X." No brand voice, no audience specificity, no anti-pattern guidance. The AI generates the most common kind of post about X, which is by definition generic. + +The signal. Prompts can fit in one sentence. Prompts that produce on-voice output are typically multi-paragraph, with voice guidelines, sample text, audience description, and anti-pattern lists. + +### No editorial judgment in the loop + +The pattern. The workflow is "AI generates, human reviews quickly, ship." The reviewer is not making editorial decisions; they are spell-checking. Whether the piece is good enough to publish, whether it answers the user's actual question, whether it reflects brand POV are not asked. + +The signal. The team cannot articulate the editorial judgments made on a piece because those judgments did not happen. Pieces ship with no halt-decisions, no rewrites, no "this piece does not work, kill it" calls. + +### Volume prioritized over quality + +The pattern. The team commits to publishing 50 pieces a month with the same headcount that previously produced 10. AI is the multiplier. Quality drops because the production line cannot sustain craft at the new volume. + +The signal. Publish targets defined in pieces-per-week or pages-per-month. Quality-controlled publish targets are defined differently: traffic earned, citations earned, leads converted, audience grown. Volume targets without quality targets produce slop volume. + +### No iteration + +The pattern. First draft (AI-generated) ships. No revision pass. No second draft. No "let us read this aloud and rewrite the bland sections." + +The signal. The workflow document does not include a rewrite step. Production is generation-then-publish, not generation-then-iteration-then-publish. + +--- + +## Patterns that prevent slop + +### Strong briefs + +Per `content-brief-authoring`. A brief that fills all 12 fields gives the AI enough context to produce a draft that respects audience, voice, structure, entity coverage, and success criteria. Vague briefs produce slop output regardless of how the AI is prompted. + +The discipline. Brief-adherence is the first QA gate per `editorial-qa`. AI drafts that fail brief-adherence get returned, not rubber-stamped. + +### Voice guidelines as prompt context + +Per `voice-ownership-preservation.md`. Every AI generation includes the brand voice guidelines and sample anchor text as prompt input. Without active voice prompting, AI defaults dominate. + +### Heavy human editing pass + +The discipline. The human spends substantial time editing AI drafts: rewriting flat sentences, replacing abstractions with specifics, restoring brand voice in mid-piece sections, replacing generic openings and closings with specific ones. + +The time investment. 50 to 60% of the piece's production time goes to human editing in Pattern 1 (AI-first draft, human-edit-heavy). Lower than that and the editing is light; the piece ships with AI defaults preserved. + +### Iteration + +The discipline. The workflow includes multiple revision passes: AI draft, then human rewrite, then AI suggestions for the rewrite, then human final pass. Each pass catches a different layer. + +- AI draft: structure, completeness, basic prose. +- Human rewrite: voice, specificity, claim verification, distinctive POV. +- AI suggestions: copy edit catches, alternative phrasings, repetition flagging. +- Human final: closing voice, emotional register, final polish. + +The pattern produces work that reads as human-crafted with AI assistance. Skip any pass and the piece moves toward AI default. + +### Editorial judgment at every gate + +The discipline. Each QA gate is a judgment moment, not a rubber stamp. Brief-adherence asks "did this piece execute the brief?" Voice consistency asks "does this sound like our brand?" Fact accuracy asks "is every claim verified?" Each question requires a human's actual judgment. + +The signal of editorial judgment in action. Halts happen. Pieces get sent back for revision. Some pieces get killed because they cannot be made to work. Programs that publish 100% of what they draft are not exercising editorial judgment; they are producing whatever the workflow ships. + +--- + +## The reader-detection problem + +Readers can often sense AI-flavored content even when they cannot articulate why. The signals. + +- Generic openings that could be the opening of any article on the topic +- Predictable structure (intro, three points, conclusion) +- Bullet-list overuse where prose would serve +- "Perfect" grammar that reads as emotionally flat +- Specific-but-fake details (named decimals, named sources that turn out to be fake) +- Hedge stacking that avoids commitment + +Slop loses reader trust over time even when individual pieces are not penalized by algorithm updates. Readers stop returning. Email open rates drop. Citation quality declines. The traffic numbers may hold for a year before the trust loss compounds visibly. + +The implication. Slop is not a search-engine problem; it is a reader-trust problem. Programs that optimize away from slop because of algorithm fear are missing the bigger reason: readers stop trusting the brand. + +--- + +## The slop avoidance audit + +For each AI-assisted piece, ask the following before publish. + +1. Could this piece have been published by any competitor using the same tools? If yes, the voice is not preserved. +2. Are the claims in this piece specific enough to verify? If no, the piece is hedging. +3. Does the piece take a position the reader will remember? If no, the piece is forgettable. +4. Did the human substantially rewrite, or is the AI draft mostly intact? If mostly intact, the piece is at slop risk. +5. Does the closing read as the writer's own voice? If no, the final pass was skipped. +6. Did the brief adhere to the 12-field discipline? If no, the failure is upstream. + +A piece that fails 3+ of these is slop-shaped. Halt and revise. + +--- + +## The "we are producing 10x more content but the same audience growth" pattern + +A common signal that slop has set in. The volume increased; the audience metric did not. The team often interprets this as "we need even more content"; the diagnosis is usually the opposite. + +The actual diagnosis. Volume was not the constraint. Quality was. The 10x content production has produced 10x slop, which earns less per piece and sometimes hurts the brand's overall trust signal. + +The fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## Cross-reference + +The detection patterns (AI tells, hallucination patterns, voice drift) live in `editorial-qa/references/ai-content-audit-patterns.md`. The avoidance patterns (production discipline) live here. The two skills compose: editorial-qa catches what reaches the gate; this skill prevents production patterns that produce slop in the first place. + +--- + +## Methodology-level choices that stay in the public skill + +The patterns that produce slop, the patterns that prevent slop, the reader-detection observation, the 6-question slop avoidance audit, the volume-vs-quality counter-intuition, the cross-reference to editorial-qa. + +## Implementation choices that stay internal + +The specific iteration loop the team runs (AI draft to human rewrite to AI suggestions to human final, or variations). The specific time-tracking that captures the editing-time-to-generation-time ratio. The specific prompt patterns that include voice guidelines and sample text. The specific reader-feedback channels that surface slop perception. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/common-collaboration-failures.md b/skills/ai-content-collaboration/references/common-collaboration-failures.md new file mode 100644 index 0000000..cfabbca --- /dev/null +++ b/skills/ai-content-collaboration/references/common-collaboration-failures.md @@ -0,0 +1,165 @@ +# Common collaboration failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: the team treated AI as either a magic content factory (producing slop at scale) or as a pure-replacement-or-nothing question (producing inconsistent output as writers privately negotiated their own AI usage). The discipline is in between: humans own, AI accelerates, the workflow is documented, the team is calibrated. + +--- + +## "We used AI and the content feels generic" + +**Symptom.** Pieces ship technically clean but feel indistinguishable from competitors using the same tools. Audience growth flat despite consistent publishing. + +**Diagnosis.** Voice not preserved. Editing was light; AI defaults reached publish. The pattern that produces this: AI-first drafts with a quick review pass that catches typos but does not rewrite for voice. + +**Fix.** Apply the voice ownership preservation patterns (`voice-ownership-preservation.md`): voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland audit. Increase editing intensity to 50-60% of production time. + +--- + +## "Hallucinated facts made it to publish" + +**Symptom.** A statistic, quote, citation, or product claim in a published piece turns out to be invented. + +**Diagnosis.** Fact-verification gate skipped or rushed. The team trusted AI output that read as authoritative. + +**Fix.** Fact-accuracy as halt-condition gate per `editorial-qa/references/fact-accuracy-and-citation-discipline.md`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +--- + +## "Different writers produce wildly different AI-assisted output" + +**Symptom.** Two writers given the same brief and the same AI tools produce pieces that read as if they came from two different programs. + +**Diagnosis.** No team calibration. Each writer developed their own AI patterns; the program drifted as different patterns produced different output shapes. + +**Fix.** Documented AI policy, calibration sessions, voice library, quality benchmarks per `team-training-and-calibration.md`. Onboarding for new writers includes calibration. + +--- + +## "Our AI-assisted SEO content got penalized" + +**Symptom.** A programmatic SEO set or a high-volume editorial program loses 60-90% of traffic in an algorithm update. + +**Diagnosis.** Slop volume plus thin templates plus no QA discipline. The set was generating filler pages with limited human direction; the algorithm update detected the scale-without-substance pattern. + +**Fix.** Halt new generation. Apply QA at scale per `editorial-qa/references/qa-at-scale-patterns.md`. Sampling discipline with 5% failure threshold. Noindex pages that fail the data-depth threshold. Possibly remove the entire pSEO surface and rebuild from a stronger data source. + +--- + +## "We can't tell what was AI vs human" + +**Symptom.** Asked to characterize AI usage on a specific piece, the team cannot answer. Workflow logs, CMS metadata, and writer recall all yield uncertain answers. + +**Diagnosis.** No AI usage tracking. The workflow does not capture which AI participated in which stage. + +**Fix.** Add AI involvement tracking to the production workflow. The metadata captures: which workflow pattern was used, which AI tools were involved, which stages, which prompts (or prompt template versions), which human made which decisions. The tracking is the input to retrospective audits and to disclosure decisions. + +--- + +## "Readers complained about AI-flavored content" + +**Symptom.** Direct audience feedback (comments, support tickets, social mentions) flags content as feeling AI-generated. + +**Diagnosis.** Slop reaching the audience. Reader detection is real even when the team's QA does not catch it. + +**Fix.** Intensify the human craft pass. Audit recent pieces against the slop avoidance audit (`ai-slop-detection-and-avoidance.md`). If multiple pieces fail the audit, the production patterns need to shift: heavier human editing, more rejection-of-bland, possibly pattern shift from AI-first to AI-as-editor for higher-trust content. + +--- + +## "We disclosed AI usage and lost credibility" + +**Symptom.** Team added AI disclosure to a piece; audience response shifted negative. + +**Diagnosis.** Could be either: + +- The disclosure was for content where audience norms expect human authorship (Tier 1 or Tier 2 content per the disclosure framework); disclosure was correct but audience trust calibration is moving slowly +- The disclosure language was hedging or defensive, signaling lower commitment than direct authorship would have +- The disclosure was for content where it was unnecessary (Tier 4); the disclosure created an issue where there was none + +**Fix.** Calibrate disclosure to audience norms per `disclosure-and-transparency-patterns.md`. Specific language matters; defensive language reads worse than no disclosure. Consider audience-research feedback to inform per-content-type disclosure tiering. + +--- + +## "Our AI tools changed and our content shifted" + +**Symptom.** Team updates the AI tool or model version. Output behavior changes. Content quality shifts before the team recalibrates. + +**Diagnosis.** Over-coupled to one tool's specific behavior. The methodology should be tool-agnostic; the team's prompts and patterns should produce similar output across tools. + +**Fix.** Methodology-first calibration. The voice library, prompt templates, and quality benchmarks should be portable across tools. After tool changes, run a calibration session against the new tool to verify the methodology still produces on-voice output. If the methodology no longer works, that is a signal the methodology was over-coupled to tool-specific behavior. + +--- + +## "We're producing 10x more content but the same audience growth" + +**Symptom.** Team committed to a 10x content target enabled by AI. Volume hit the target. Audience growth flat or declining. + +**Diagnosis.** Volume was not the constraint that was binding. Quality was. The 10x volume produced 10x slop, which earns less per piece. + +**Fix.** Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## "The team is using AI inconsistently" + +**Symptom.** Team members use different AI tools in different patterns for the same kind of work. Output varies by who picked up the assignment. + +**Diagnosis.** Calibration sessions overdue. Either the policy is informal (no documented standards) or the documented policy has not been reinforced through calibration. + +**Fix.** Quarterly calibration sessions. Tool standardization (or intentional pluralism with documented selection criteria). Onboarding refresh. The cadence is calendar-anchored. + +--- + +## "An expert byline turned out to be substantially AI-drafted" + +**Symptom.** A piece bylined by a named expert is publicly identified as substantially AI-drafted (sometimes by AI-detection tools, sometimes by readers familiar with the expert's actual voice). + +**Diagnosis.** Ethics breach. The byline implied human authorship; AI authorship was substantive; the gap between claim and reality reached the audience. + +**Fix.** Two parts. + +- **Immediate.** Correct the published piece (issue an editor's note clarifying the workflow, possibly retract and republish with appropriate disclosure). Apologize where appropriate. Recalibrate. +- **Process.** Restore the ethical floor: bylined expert content requires substantial human authorship. Recalibrate the team. Update the AI policy to document the floor explicitly. + +The fix is not "stop using AI." The fix is using AI consistently with the byline's implied authorship. + +--- + +## "Our AI policy is 18 months stale and references tools we no longer use" + +**Symptom.** Team consults the AI policy doc; the doc references tools the team migrated away from a year ago. The doc is treated as not authoritative because it is obviously dated. + +**Diagnosis.** Policy review cadence has slipped. The doc has not been updated as tools, capabilities, and team practices have evolved. + +**Fix.** Quarterly policy review. Each quarter the policy gets reviewed against current practice; updates ship; the team is briefed on the changes. The policy is a living document; staleness signals process failure. + +--- + +## "The team feels guilty about AI use but uses it anyway" + +**Symptom.** Team members use AI substantively but do not document, do not discuss in calibration sessions, do not include in retrospectives. AI usage is treated as something to hide. + +**Diagnosis.** The team has not articulated its AI ethics. Without articulation, individual writers privately negotiate their own ethics; the team accumulates ethical debt. + +**Fix.** Run an ethics conversation explicitly. Articulate the team's position on the six ethical floors per `ethics-and-intellectual-honesty.md`. Document where AI is used substantively. Make the workflow visible. Guilt is usually a signal of unresolved ethical questions; the resolution is articulation, not avoidance. + +--- + +## The pattern across all failures + +Most AI-collaboration failures reduce to two patterns. + +1. **The team treated AI as a magic content factory.** Outcome: slop, hallucinations, voice loss, audience trust decline. +2. **The team failed to articulate its AI workflow explicitly.** Outcome: drift, inconsistency, ethics debt, calibration failures. + +The fix in both cases is the same: explicit articulation of where AI participates, where humans own, what the discipline looks like in practice, and what the team's ethical floors are. The articulation is the work; once the work is done, individual failures become per-piece corrections rather than program-level breakdowns. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the cross-references to other reference files, the underlying-pattern observation about magic-factory thinking and unarticulated workflows. + +## Implementation choices that stay internal + +The specific tracking system the team uses for AI usage. The specific calibration session cadence. The specific ethics-policy doc and its review process. The specific tool selections and their rationale. These vary per team and brand. diff --git a/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md b/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md new file mode 100644 index 0000000..454370a --- /dev/null +++ b/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md @@ -0,0 +1,170 @@ +# Disclosure and transparency patterns + +Tiered disclosure framework, language patterns, industry norms. + +When should AI usage be disclosed to readers? The answer is not "always" or "never"; it is "calibrate to context." The framework below tiers disclosure decisions by trust sensitivity. + +--- + +## The tiered framework + +Four tiers, ordered by disclosure obligation. + +### Tier 1: Always disclose + +AI usage is disclosed regardless of how light the involvement was. + +**Categories.** + +- Journalism and news reporting (any AI involvement, any extent) +- Bylined expert opinion (where the byline implies human authorship of the argument) +- Content where AI tools are themselves the subject (transparency about methodology is part of the topic) +- Regulated industries with explicit AI disclosure requirements (financial advice, medical content, legal content in some jurisdictions) + +**Reasoning.** In these categories, the reader's understanding of the content's origin is load-bearing for trust. A news story partially AI-drafted reads differently from a story fully reported and written by a journalist; readers have a right to that information. + +### Tier 2: Default disclosure (consider context) + +Disclosure is the default; opting out requires a specific reason. + +**Categories.** + +- Thought leadership pieces where the byline carries trust value +- Content that influences purchase decisions (reviews, comparisons, recommendations) +- Content for trust-sensitive audiences (academia, enterprise procurement, professional services) +- Long-form pieces where the audience has reasonable expectation of human craft + +**Reasoning.** Readers in these contexts often assume human authorship; AI involvement that is undisclosed becomes a trust violation if discovered. Disclosure is cheap; the trust hit from undisclosed-then-discovered AI involvement is expensive. + +### Tier 3: Generally not necessary + +Disclosure is allowed but not required by audience expectations. + +**Categories.** + +- Marketing copy (web pages, ad copy, email marketing copy) +- Descriptive product content (product descriptions, spec listings) +- Programmatic data pages (where the page is obviously data-generated) +- Internal team content (memos, internal reports) +- Copy edit assistance only (the human wrote the piece; AI suggested edits) + +**Reasoning.** In these categories, audience expectations do not assume specific authorship. Readers recognize the genre as functional content; AI involvement does not violate trust the way it would in a thought leadership piece. + +### Tier 4: Clearly fine without disclosure + +Disclosure is unnecessary and would feel weird if present. + +**Categories.** + +- AI as research assistant (the AI condensed sources; the human wrote) +- AI for transcription only (the human is the writer; the AI was a typist) +- AI for spelling and grammar suggestions (copy edit role only) +- AI as brainstorming partner where the human took the ideas and wrote independently + +**Reasoning.** The AI's role was so light that disclosure would imply more involvement than there was. Readers would interpret a disclosure as misleading. + +--- + +## Language patterns + +When disclosure is used, the language matters. + +### Patterns that work + +> "AI tools assisted in research and drafting; the author edited and verified all claims." + +> "This piece was generated programmatically from [data source]; reviewed by [team] before publish." + +> "The author drafted this piece; AI tools were used for copy edit suggestions." + +> "Research synthesis assisted by AI; all sources verified by the author." + +The patterns share three features: they specify what AI did, they specify what humans did, they identify the accountability party. + +### Patterns to avoid + +- **Hedge language.** "May have used AI" or "could have been AI-assisted" reads as covering legal bases without committing to honesty. Be specific or omit. +- **Disclosure that minimizes.** "AI was minimally involved" is hedging; either AI was substantively involved (disclose substantively) or it was not (no disclosure needed for Tier 4 use). +- **Disclosure that overstates.** "Fully written by AI" when humans rewrote 50% is dishonest in the other direction. The disclosure should match the actual AI involvement. + +### Where to place disclosure + +- **Footer or byline area.** Standard placement; readers find disclosure where they expect it. +- **Inline at relevant points.** When AI involvement varies across a piece, inline notes are clearer than a single footer note. +- **Methodology section.** Long pieces with substantial AI involvement benefit from a "How this piece was produced" section that explains the workflow. + +--- + +## Industry norms + +Disclosure norms vary by industry. The principle of intellectual honesty is constant; the specific expectations differ. + +**Journalism.** Major journalism organizations have published explicit AI usage standards. The norm is moving toward disclosure of AI involvement in any reported piece. Journalism trust depends on transparency; AI-related opacity is a fast trust violation in the audience. + +**Content marketing.** Norms are weaker but moving toward disclosure for high-trust pieces. Branded thought leadership is increasingly expected to disclose AI involvement; routine marketing copy is not. + +**Academic and research content.** AI involvement in research papers is a contested area; conferences and journals have varying policies. The conservative default is full disclosure, including which AI tools were used and at what stages. + +**Regulated industries.** Financial, medical, and legal content increasingly carries explicit AI disclosure requirements. The defaults here are tighter than in unregulated marketing content; consult the specific regulatory environment. + +**Ecommerce and product content.** Disclosure is generally not expected on product descriptions or spec listings. AI generation is genre-typical; readers do not interpret presence or absence of disclosure as meaningful. + +--- + +## When disclosure helps and when it hurts + +The honest framing. Disclosure is sometimes a trust gain, sometimes a trust loss; the calibration depends on audience norms. + +**Disclosure as trust gain.** + +- Audience expects human authorship; disclosure preempts trust loss from later discovery +- Brand positions itself on transparency +- Industry is moving toward disclosure as the new norm +- The piece's value is in research and verification, which AI assisted but did not replace + +**Disclosure as trust loss.** + +- Audience interprets AI involvement as quality reduction (sometimes a misreading, sometimes accurate) +- Disclosure language reads as defensive or hedging +- Audience expects routine content (where AI is genre-typical) + +The decision is not "always disclose" or "never disclose" but "calibrate." The calibration is best done by someone who knows the audience and the brand's positioning, not by a generic policy. + +--- + +## Disclosure policy at the program level + +The program-level discipline. Document the disclosure policy by content type. Editors and writers know which content types require disclosure; the disclosure language is templated; the policy is reviewed quarterly. + +**Template policy structure.** + +- Content type: [thought leadership]. Disclosure: [required]. Language template: [template]. +- Content type: [knowledge base article]. Disclosure: [optional]. Language template: [template if used]. +- Content type: [programmatic data page]. Disclosure: [not required]. +- Content type: [marketing landing page]. Disclosure: [not required]. + +The policy gets updated as norms evolve. AI disclosure norms in 2026 are looser than they will be in 2028; policy review keeps the program aligned with audience expectations. + +--- + +## When the disclosure decision is hard + +Edge cases. + +**Long-running expert byline.** A column under a named expert's byline, where some pieces are pure expert authorship and others are substantively AI-assisted. Disclosure on the AI-assisted pieces is the right call; the byline's trust value depends on it. + +**Pillar content with mixed authorship.** A pillar piece where the lede is human-written, the body is AI-drafted-then-rewritten, the closing is human-written. Disclosure language can specify the mix: "Research and core argument by the author; AI assisted in initial drafting of body sections; all claims verified." + +**Internal-only content that becomes external.** An internal report that gets externalized requires retroactive disclosure if the internal version was AI-assisted. Sometimes the externalization should include rewriting to bring the disclosure inline. + +The principle. When the disclosure decision is hard, default to disclosure. Trust is recoverable from over-disclosure; trust is not always recoverable from under-disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The four-tier framework, the disclosure language patterns, the industry norms summary, the trust-gain-vs-trust-loss calibration, the program-level policy structure, the edge-case handling. + +## Implementation choices that stay internal + +The specific disclosure language the team has developed for each content type. The specific tracking that records AI involvement per piece (workflow log, CMS metadata, byline annotation). The specific review cadence for the disclosure policy. The specific audience-research feedback that informs disclosure norms for the brand's specific audience. These vary by team, brand, and industry. diff --git a/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md b/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md new file mode 100644 index 0000000..d435d59 --- /dev/null +++ b/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md @@ -0,0 +1,154 @@ +# Ethics and intellectual honesty + +Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. + +This is the most ethically loaded reference in the catalog. The voice is honest, pragmatic, non-preachy. The catalog itself is produced with AI assistance; pretending otherwise would render any anti-AI position hypocritical. The position is not "AI use is unethical" but "intellectual honesty about AI involvement is non-negotiable." + +--- + +## Training data realities + +Every major LLM in 2026 was trained on copyrighted material. That is the simple ethical reality. + +The legal status of training-data copyright is contested in multiple jurisdictions and is being litigated. The position the catalog takes is not "AI training is ethical" or "AI training is unethical"; the position is "the question is unresolved, the tools exist, teams use them, the way to use them ethically is the question this skill addresses." + +What this skill does not relitigate. The training-data copyright question. The compute-intensity environmental question. The labor-displacement question. These are real ethical questions; this skill is not the place to resolve them. Teams reading this skill make their own choices about whether to use AI tools at all; the skill addresses how to use them with intellectual honesty when teams have made the use-AI choice. + +--- + +## Don't pass AI work as fully human-written + +The first ethical floor. + +Bylined content where the byline implies human craft requires substantial human craft. A column under a named expert's byline that is substantially AI-drafted is a trust violation regardless of whether disclosure was technically present somewhere on the page. The byline's value depends on the audience's understanding that the named human authored the piece; AI authorship that the byline obscures is dishonest. + +What "substantial human craft" requires. + +- The argument is the human's +- The voice is recognizable as the human's +- The judgments about what to include, what to cut, what to emphasize are the human's +- The fact verification is the human's +- The final approval is the human's + +What it does not require. Every word being typed by the human (research-assistant patterns are fine). Every sentence being unrewritten (copy edit assistance is fine). The human spending a specific time-on-task (the time matters less than the substance). + +--- + +## Don't claim AI didn't help when it did + +The second ethical floor. + +False denials are worse than disclosure. A team that uses AI substantially and then claims the work is fully human is staking trust on a falsifiable claim. Discovery of the AI involvement (which becomes more reliable each year as detection tools improve) compounds the trust violation: the audience now distrusts both the work and the team's honesty about the work. + +The honest pattern. If AI was used in any way that would matter to the audience, the team is honest about it. The disclosure tiering framework (per `disclosure-and-transparency-patterns.md`) addresses when disclosure is required; the no-false-denial floor is broader: even when disclosure is not required, false denial is not allowed. + +In practice. Most teams do not face direct denial questions; the issue comes up in interview contexts ("how do you produce your content?"), retrospectives, or conversations with clients and partners. The honest answer in those contexts is the truthful one, even when no public disclosure was attached to specific pieces. + +--- + +## Don't generate content that closely mirrors copyrighted source material + +The third ethical floor. + +AI tools can produce near-replicas of training data when prompted carelessly. The team's responsibility is to verify that AI-generated content is original work and not a paraphrase of a specific copyrighted source. + +The check. For each substantive section of AI-generated content, search for the unique phrasing in quoted form. If results come back to a specific copyrighted source that the AI was likely trained on, the section is too close to source material. Revise. + +The pattern. AI tools tend to mirror training data more closely on niche topics than on common topics. Common topics have many sources to blend; niche topics have fewer. Specialized content (academic topics, technical documentation, industry-specific niches) needs more careful mirroring checks. + +--- + +## Attribute when borrowing + +The fourth ethical floor. + +Ideas, frameworks, statistics, and specific phrasings that came from identifiable sources get cited. The principle is not changed by whether AI surfaced the source or whether the human did; attribution belongs to the source, not to the discovery method. + +The pattern. + +- Statistics with sources: cite the source. +- Frameworks attributed to specific thinkers: cite the thinker. +- Specific arguments traceable to a specific publication: cite the publication. +- Common knowledge: no citation needed, but verify it actually is common knowledge and not specialized knowledge that the AI surfaced from a specific source. + +The honesty test. If the team would feel uncomfortable having the source's author read the piece and recognize their work uncited, citation is required. + +--- + +## Don't fabricate quotes or expertise + +The fifth ethical floor. + +Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. The team is accountable for what gets attributed; the AI is not the accountable party. + +The pattern. AI generates plausible-but-fake quotes in 2026; that is a known limitation. The fact-accuracy gate per `editorial-qa` catches them before publish. The ethical position is broader than the QA position: even if a fabricated quote were never caught, generating it under attribution to a real person is dishonest. + +The same applies to expertise claims. AI-drafted "expert content" attributed to a named expert who did not draft it is fabricated expertise. The expert's name carries trust value; the trust depends on the expert having actually drafted the piece. + +--- + +## Be honest about AI capabilities and limits + +The sixth ethical floor. + +Do not oversell AI as more capable than it is. Do not undersell it as less capable than it is. Both produce decision-making errors in the team and in the audience. + +The pattern. AI in 2026 is genuinely useful for research synthesis, drafting against briefs, copy edit suggestions, transcription, summary, and quality-control automation at scale. AI in 2026 is genuinely limited at editorial judgment, fact verification (it is what gets fact-checked, not what does fact-checking), voice origination, ethical decisions, and reader empathy. + +Teams that get this right calibrate AI use to the limits. Teams that oversell AI ship work that exceeds AI's actual capabilities and produces hallucinations or voice failures. Teams that undersell AI miss productivity gains the technology offers. + +--- + +## The intellectual honesty frame + +The frame that supersedes specific policy debate. + +The question is not "is AI use ethical?" The question is "can the team be intellectually honest about AI use?" If yes, the team's ethics hold. If no, the team is rationalizing. + +What intellectual honesty looks like. + +- The team can articulate its AI-usage policy without defensiveness +- The team can name the specific patterns it does and does not use +- The team can defend each pattern on the merits, not just by precedent +- The team can engage with critiques of its policy without dismissing them +- The team updates its policy when reality changes (new tools, new evidence, new audience norms, new regulatory requirements) + +What intellectual dishonesty looks like. + +- Defensiveness when AI involvement is questioned +- Refusal to articulate the policy +- Dismissing critiques without engaging +- Hiding AI involvement that would be material to audiences +- Claiming AI does what it does not, or hiding that AI does what it does + +The honest team can withstand external scrutiny because its position holds up. The dishonest team eventually faces external scrutiny that surfaces the gap between claimed and actual practice. + +--- + +## When the ethical question is hard + +Edge cases. + +**Ghostwritten content historically allowed.** Industries where ghostwriting has always been the norm (executive thought leadership, celebrity book authorship, political speechwriting). AI assistance in ghostwriting workflows raises questions: is the ghost an AI? does the byline still mean what it meant? + +The conservative position. The byline implies human authorship; if the ghost is an AI rather than a human writer, that distinction is material to the audience and disclosure is appropriate. The aggressive position. Ghostwriting has always been a fiction the audience tolerates; AI ghostwriting is the same fiction with different tools. + +The catalog's position. Default to the conservative reading. The byline's trust value depends on audience understanding of authorship; AI ghostwriting under a named expert byline is more honest with disclosure than without. + +**Educational content with structured explanations.** Topics where the explanation has a canonical shape (math, basic programming, established science). AI-drafted explanations of canonical topics may closely mirror training data because the canonical shape is what the training data contains. + +The conservative position. Cite the canonical sources where they exist; rephrase substantively where citation is impractical. + +**Programmatic SEO at scale.** Hundreds of thousands of pages where individual disclosure is impractical and audience expectations differ from editorial content. + +The position. Programmatic content is genre-typically machine-generated; specific disclosure per page is unnecessary; transparency about the program's overall production model is appropriate at the brand level. + +--- + +## Methodology-level choices that stay in the public skill + +The training-data realities framing, the six ethical floors, the intellectual honesty frame, the edge-case handling, the conservative-vs-aggressive position taking on contested cases. + +## Implementation choices that stay internal + +The specific ethics policy the team has documented. The specific review process when an ethics question surfaces. The specific escalation pathway for ethics decisions. The specific tracking that records ethics-related decisions for retrospective review. These vary per team and brand. diff --git a/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md b/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md new file mode 100644 index 0000000..1f91b00 --- /dev/null +++ b/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md @@ -0,0 +1,121 @@ +# Hybrid workflow patterns + +Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. + +No pattern is "the right one." Pattern selection is a real decision that should match volume, voice sensitivity, team skill, and time budget. The wrong pattern produces predictable failures: AI-first drafts on voice-sensitive pieces produce slop; human-writes patterns on programmatic-scale work produce throughput failures. + +--- + +## Pattern 1: AI-first draft, human-edit-heavy + +The shape. AI produces a 90% draft against a brief. The human spends 60% of the production time editing: rewriting flat sentences, restructuring sections that miss the brief, adding voice and specificity, verifying facts. + +**Best for.** High-volume editorial where the brief is well-authored and the voice is moderately tolerant of AI defaults. SaaS blog posts, knowledge-base articles, secondary editorial pieces. + +**Risks.** Generic voice if editing is light. The pattern fails quietly; pieces ship with AI defaults preserved because the editor was rushed. + +**Time profile.** 30% AI generation, 60% human editing, 10% fact verification. Faster than human-writes for the same word count but slower than naive AI-only generation because editing time scales with the piece's length. + +**When this fits.** The team has clear brand voice and disciplined editors. The volume requirement is real (multiple pieces per day). The audience is tolerant of AI-assisted-but-edited content (most B2B, most consumer marketing). + +--- + +## Pattern 2: Human-first outline + research, AI-draft, human-rewrite + +The shape. Human builds the outline (or extends the brief's outline). Human gathers and verifies the research. AI drafts within that scaffold. Human rewrites in voice. + +**Best for.** Voice-sensitive editorial where the brand voice is distinctive enough that AI drafts need substantive rewriting anyway. The pattern formalizes the rewrite as the discipline rather than treating it as cleanup. + +**Risks.** Slower than AI-first drafts. If the rewrite is light, output is similar to Pattern 1. The discipline is in the rewrite intensity. + +**Time profile.** 20% human research and outline, 20% AI drafting, 50% human rewriting, 10% fact verification. + +**When this fits.** Brand voice is distinctive (provocative, opinionated, or emotionally specific). The audience would notice generic drafts. Time budget allows substantive rewrites. + +--- + +## Pattern 3: AI-as-research-assistant, human-writes + +The shape. AI condenses sources into research briefs. Human writes the entire piece from the brief in their own voice. + +**Best for.** Highest-trust editorial: thought leadership, contributed expert pieces, journalism, regulated content. Pieces where the byline is doing trust work and any AI involvement in drafting would compromise the byline's value. + +**Risks.** Slowest pattern. AI's role is small enough that the team may question whether AI is helping at all; the answer is usually yes (research time savings are real) but the gain is in time-to-research, not time-to-publish. + +**Time profile.** 40% human reading and outlining, 60% human writing, 10% fact verification (with AI sometimes assisting in flagging fact-check candidates). + +**When this fits.** The byline is named and trusted (a CEO, an expert, a journalist). The publication's positioning depends on human craft. Disclosure norms in the audience expect human authorship. + +--- + +## Pattern 4: Human-writes, AI-as-editor + +The shape. Human drafts the piece. AI suggests copy edits, alternative phrasings, structural improvements. Human accepts or rejects each suggestion. + +**Best for.** Senior writers whose voice is established and whose drafts are mostly clean. The AI's role is the second-pair-of-eyes that catches what fatigue or close reading missed. + +**Risks.** AI suggestions can pull voice toward AI defaults if the writer accepts too many. The discipline is rejecting the suggestions that would homogenize voice even when they read as "cleaner." + +**Time profile.** 80% human writing, 15% AI suggestion review, 5% fact verification. + +**When this fits.** The writer is experienced, the brand voice is well-developed, the piece is high-stakes. Pattern is over-kill for routine editorial; right-sized for thought leadership and named-byline pieces. + +--- + +## Pattern 5: AI-generates-at-scale, human-samples + +The shape. For programmatic SEO. AI generates thousands of pages from structured data and templates. Human samples 50 to 200 pages per cycle with editorial-qa sampling discipline. Failures above the 5% threshold halt new generation until template or data fixes ship. + +**Best for.** Programmatic SEO programs (per `programmatic-seo`). Volume scales the AI does not penalize the program because the underlying data is real and the template is strong; humans sample rather than fully review. + +**Risks.** Without sampling discipline, the program produces slop at scale. Without threshold gating, slop compounds invisibly until algorithm updates expose it. Pattern requires the editorial-qa scaling pattern to work; without QA scaling, the pattern is just AI-content-factory thinking with extra steps. + +**Time profile.** 5% template and data setup (one-time, deep), 0.5% per-page generation (mostly automated), 10% sampling QA (per cycle), 5% threshold response. + +**When this fits.** Data depth is real, query intent is queryable, QC headcount is budgeted. All five criteria from `programmatic-seo`'s when-pseo-works-decision must be met. + +--- + +## Selection criteria + +How to pick the pattern. + +**Voice sensitivity.** Distinctive voice → Pattern 2, 3, or 4. Generic-tolerant voice → Pattern 1 or 5. + +**Volume.** Single-piece-at-a-time editorial → Pattern 2, 3, or 4. High-volume editorial → Pattern 1. Programmatic scale → Pattern 5. + +**Trust requirement.** Named-byline trust work → Pattern 3 or 4. Standard branded content → Pattern 1, 2, or 5. + +**Time budget.** Tight (hours not days) → Pattern 1. Generous (days available) → Pattern 2, 3, or 4. One-time-deep then automated → Pattern 5. + +**Team skill.** Junior writers → Pattern 1 or 2 (more AI scaffolding). Senior writers → Pattern 3 or 4 (less AI, more craft). + +--- + +## Combining patterns within one program + +Most content programs run multiple patterns simultaneously. Common combinations. + +- **Editorial pillar + cluster**: Pattern 3 (AI as research assistant) for the pillar piece; Pattern 1 (AI-first draft, human-edit-heavy) for the cluster pieces. The pillar carries the trust; the cluster scales. +- **Editorial + programmatic**: Pattern 2 or 4 for editorial; Pattern 5 for programmatic. Same brand, different production model per content type. +- **Marketing copy + thought leadership**: Pattern 1 for marketing; Pattern 3 for thought leadership. Different trust requirements; different patterns. + +The discipline. Document which pattern the team uses for which content type. Without explicit documentation, the patterns drift; one writer uses Pattern 1 on a piece that should have been Pattern 3, and the trust value of the byline is compromised. + +--- + +## Anti-pattern: pattern drift mid-piece + +Sometimes a piece starts in Pattern 4 (human-writes, AI-as-editor) and drifts into Pattern 1 (AI-first, human-edits) when the writer falls behind on deadline. The piece publishes with AI default voice in sections the writer was supposed to draft. + +The fix. Recognize the drift as a process failure, not a writing failure. The writer was over-committed; the fix is workload management, not blame. Future pieces of this type either get more time (preserving Pattern 4) or get reassigned to Pattern 1 with the editing intensity that Pattern 1 requires. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns, the tradeoffs per pattern, the selection criteria framework, the multi-pattern combinations within a program, the pattern-drift anti-pattern. + +## Implementation choices that stay internal + +The specific AI tools used in each pattern (drafting model, editing model, research model). The specific prompts each pattern uses for the AI handoff. The specific time-tracking that captures pattern adherence per piece. The specific deadline-management workflow that prevents pattern drift mid-piece. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md b/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md new file mode 100644 index 0000000..e16cab8 --- /dev/null +++ b/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md @@ -0,0 +1,143 @@ +# Quality calibration with AI in the loop + +How editorial standards shift when AI is in the workflow. Same standards apply; the failure modes shift. + +The editorial standards from `editorial-qa` apply identically to AI-assisted work: brief adherence, voice consistency, fact accuracy, structure and clarity, AEO/SEO compliance, internal linking and schema validation. What shifts is the failure-mode profile. Programs that ship AI-assisted content with the same QA discipline as human-written content but without recognizing the new failure modes produce slop while believing they are calibrated. + +This reference connects the QA discipline to the AI workflow discipline. It surfaces the shifts. + +--- + +## Same standards, different failure modes + +For each editorial standard, the failure mode that dominates in AI-assisted production differs from the failure mode that dominated in human-only production. + +### Brief adherence + +**Human-only failure.** Writer skips a brief field because they think they know better, or misreads the brief. + +**AI-assisted failure.** AI ignores brief fields that were not in the prompt context. The brief is in one document; the AI prompt is in another. Brief fields that did not get pasted into the prompt do not get executed. + +**The fix.** Prompt templates that explicitly include all 12 brief fields. Brief-adherence QA gate runs against the brief, not against the prompt. + +### Voice consistency + +**Human-only failure.** Writer fatigue causes voice drift in section 4 of long pieces. Editorial style drift over months as writers absorb each other's tics. + +**AI-assisted failure.** AI default voice reasserts mid-piece. Long AI generations regress toward generic by section 4 reliably. The drift is faster than human drift and more consistent across pieces. + +**The fix.** Mid-piece voice sampling per `voice-ownership-preservation.md`. Voice anchor text in every prompt. Final pass in human voice on every long piece. + +### Fact accuracy + +**Human-only failure.** Lazy fact-checking. The writer "remembers reading" something but does not verify. Citations to publications without specific dates or page references. + +**AI-assisted failure.** AI hallucinations. Plausible-but-fake statistics with named sources that do not exist. Quotes attributed to real people who did not say them. Citations to URLs that 404. + +**The fix.** Fact-accuracy as halt-condition gate per `editorial-qa`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +### Structure and clarity + +**Human-only failure.** Buried lede, vague opening, history dump in section 1. Mismatched section lengths. + +**AI-assisted failure.** Generic opening that could open any article on the topic. Repetitive paragraph structure (every paragraph 2 to 3 sentences). Bullet-list overuse where prose would serve. Forced bilateral framing throughout. Wrap-up filler endings. + +**The fix.** AI-content audit per `editorial-qa/references/ai-content-audit-patterns.md`. Read-aloud audit catches what line-review misses. + +### AEO and SEO compliance + +**Human-only failure.** Writer forgets to include the target keyword in title and headings. Schema markup absent or invalid. + +**AI-assisted failure.** AI over-optimizes the surface (keyword in every heading, schema markup over-claimed) but under-optimizes the substance (the answer paragraph is generic, the entity coverage is thin, the POV is absent). + +**The fix.** AEO/SEO checks that go beyond surface compliance into substance: is the top-200-word answer self-contained, is the entity coverage what the brief specified, is the POV distinctive. + +### Internal linking and schema validation + +**Human-only failure.** Writer skips internal-link discipline because it feels mechanical. Anchor text uses "click here" or generic phrases. + +**AI-assisted failure.** AI-generated links to URLs that do not exist (hallucinated link targets). Anchor text repeats the same exact-match keyword across multiple links because the AI defaults to that pattern. + +**The fix.** Link-target liveness check on every published piece. Anchor text variation as a explicit QA item. + +--- + +## The "QA standards must be tighter" claim is wrong + +A common misreading. Teams shipping AI-assisted work decide their QA needs to be tighter, more checks, more thresholds. The misreading produces checkbox theater. + +The accurate reading. QA needs to be calibrated to the new failure modes, not tightened indiscriminately. The standards stay the same; the patterns to look for shift. + +The discipline. When a team starts AI-assisted production, the QA process gets reviewed against the new failure-mode profile. Some checks become more important (fact accuracy, voice consistency, AI-content audit). Some checks become less important (the writer's preferred typo patterns, since the AI does not have the same typo patterns). The QA shape adjusts. + +--- + +## Calibration sessions specific to AI-assisted work + +The calibration session methodology from `team-training-and-calibration.md` adapts for AI-assisted work specifically. + +**The AI-specific calibration session.** + +1. Three editors independently review the same 3 to 5 AI-assisted pieces. +2. Each editor's assessment includes the AI-content audit dimensions: AI tells, hallucination patterns, voice drift, slop signals. +3. The team reads all assessments together. +4. Differences in interpretation surface; reconcile. +5. Output: addendum to the AI policy doc capturing the calibration consensus on AI-specific QA dimensions. + +The cadence. Quarterly minimum. More frequent during program build or after AI tool changes that affect output behavior. + +--- + +## When the team is calibrated but the output still feels off + +Symptoms. + +- QA gates pass, individual pieces look fine, the program's overall feel is generic +- Readers complain about AI-flavored content despite QA passing +- Audience growth flat despite shipped quality being technically high + +Diagnosis. The QA discipline catches per-piece failures. It does not catch program-level patterns: every piece passing voice review individually but the cumulative output reading as homogenized. + +The fix. Add a program-level review to the calibration cadence. Read 10 published pieces in sequence. Do they sound like one publication with a distinctive voice, or do they sound like 10 separate AI-assisted pieces from different generic publications? The latter signals voice has been preserved at the per-piece level but lost at the program level. + +The intervention. Tighter voice library, more aggressive reject-the-bland discipline, possibly a return to a heavier human-writes pattern for trust-anchor pieces (pillars, thought leadership, named-author content) while keeping AI-assisted patterns for cluster work. + +--- + +## The "ship vs hold" calibration + +In AI-assisted production, the ship-vs-hold decision shifts. More pieces marginally pass QA; the question becomes whether marginal-pass pieces should ship. + +**Human-only mode.** Marginal pieces usually have specific fixes. The editor flags them; the writer fixes them; the piece ships. + +**AI-assisted mode.** Marginal pieces often have systemic AI-tells throughout that fixing one-by-one will not address. The editor's choice is between substantial rewrite (back to Pattern 2 or 3) or kill. + +The discipline. Some AI-assisted pieces are kill candidates, not revise candidates. The team should have explicit kill criteria: pieces that fail AI-content audit on 4+ dimensions, pieces where voice was lost beyond paragraph-level recovery, pieces where the underlying brief was thin enough that the AI draft has nothing to anchor to. + +Killing pieces is part of the discipline. Programs that publish 100% of what they draft are not exercising editorial judgment. + +--- + +## The calibration-with-AI checklist + +For each AI-assisted piece, beyond the standard QA gates. + +1. AI-content audit run per `editorial-qa/references/ai-content-audit-patterns.md`? +2. Voice anchor text was used in the prompt? +3. Mid-piece voice sample taken on long pieces? +4. Final pass in human voice for the closing? +5. Fact-accuracy gate ran with AI-hallucination patterns specifically in mind? +6. Disclosure decision made per the disclosure tier framework? +7. The piece passes the "could a competitor have shipped this with the same tools" test? + +If 2+ items fail, the piece is at slop risk. Halt and revise. + +--- + +## Methodology-level choices that stay in the public skill + +The same-standards-different-failure-modes mapping, the "QA standards must be tighter" misreading correction, the AI-specific calibration session adaptation, the program-level review pattern, the kill-criteria discipline, the calibration-with-AI checklist. + +## Implementation choices that stay internal + +The specific QA tooling that surfaces AI-specific failure patterns. The specific automation that flags potential AI tells before manual review. The specific calibration session cadence and team composition. The specific kill-criteria thresholds the team has settled on. These vary by team scale and content sensitivity. diff --git a/skills/ai-content-collaboration/references/team-training-and-calibration.md b/skills/ai-content-collaboration/references/team-training-and-calibration.md new file mode 100644 index 0000000..da21f15 --- /dev/null +++ b/skills/ai-content-collaboration/references/team-training-and-calibration.md @@ -0,0 +1,149 @@ +# Team training and calibration + +Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. + +Inconsistent AI usage across a team produces inconsistent output. The discipline below makes AI usage explicit, calibrated, and documented at the team level so the program ships consistent work regardless of which writer is assigned which piece. + +--- + +## Documented AI policy + +The starting point. Every team running AI-assisted content has a policy document, even if currently informal. + +**What the policy specifies.** + +- **Approved uses.** AI in research synthesis, AI in copy edit suggestions, AI in transcription, AI in alternative phrasings. The team uses these without per-piece approval. +- **Conditional uses.** AI in first-draft generation, AI in outline generation, AI in long-form drafting. Approved per content type (e.g., approved for cluster pieces, requires editor approval for pillar pieces). +- **Prohibited uses.** AI as the sole author of bylined expert content, AI for fact verification (the AI is what gets fact-checked, not what does fact-checking), AI for ethical decisions, AI for final approval. +- **Tool standards.** Either "the team uses [specific tool] for [specific task]" or "the team selects from this list of tools per task type." Documented either way. +- **Disclosure requirements.** By content type, per the disclosure framework. +- **Voice library reference.** Where the team's voice anchor texts and prompt templates live. + +**The discipline.** The policy is a document, not an oral tradition. Writers, editors, and contributors know where to find it; it is referenced in onboarding; it is updated quarterly. + +--- + +## Calibration sessions + +The discipline. Quarterly editor sessions where editors review the same AI-assisted pieces and surface differences in their judgment. + +**Session structure.** + +1. Three editors independently review the same 3 to 5 recently-published pieces. +2. Each editor writes a one-paragraph assessment per piece: voice, brief adherence, AI tells, fact accuracy, overall quality. +3. The team reads all assessments together. +4. Differences in interpretation surface; the team reconciles to a shared standard. +5. The session output is an addendum to the policy doc capturing the calibration consensus. + +**Why this matters.** Without calibration, individual editors apply individual taste. Some editors flag AI-tells aggressively; others ship the same piece without flagging. The inconsistency confuses writers and produces drift in published quality. + +**Cadence.** Quarterly minimum. More frequent during onboarding waves or after policy updates. + +--- + +## Voice library + +The team's collection of canonical brand-voice samples used as anchor text in AI prompts. + +**What goes in the library.** + +- 2 to 3 paragraphs of canonical brand voice per content type (blog, whitepaper, help doc, marketing copy, thought leadership) +- 2 to 3 paragraphs per writer voice (where the brand has multiple distinct contributor voices) +- 5 to 10 examples of AI-generated content that the team rewrote successfully (showing the before-and-after as a calibration aid) +- The vocabulary list: preferred terms, forbidden terms, term-specific usage rules + +**Update cadence.** Monthly during program build; quarterly once stable. + +**Why this matters.** The voice library is the operational expression of brand voice. Without a library, every AI prompt reinvents the voice context; the team produces inconsistent output. With a library, the prompt is templated and the voice context stays consistent. + +--- + +## Quality benchmarks + +The team's documented examples of "AI-assisted but on-voice" pieces. + +**What the benchmarks show.** + +- 5 to 10 published pieces where AI assistance was substantial but the output reads as on-voice +- For each benchmark: the pattern used (which workflow pattern), the editing intensity, the time profile, the quality outcome +- The benchmarks are calibration aids: writers and editors look at them when calibrating their own AI-assisted work + +**Why this matters.** "On-voice AI-assisted content" is an abstraction. Concrete examples make it tangible. New writers calibrate to the benchmarks; experienced writers reference them when their work feels off. + +**Anti-pattern.** Benchmarks that are aspirational rather than achieved. The benchmark library should be real published work, not "what we wish we shipped." Aspirational benchmarks set unrealistic expectations. + +--- + +## Tool standardization vs intentional pluralism + +Two valid models for AI tool selection at the team level. + +### Standardization + +The team uses one tool consistently for each task type. Drafting on tool A, editing on tool B, transcription on tool C. New writers learn the standard tools; the prompt templates and voice library are tool-specific. + +**When this fits.** Smaller teams. Predictable content types. Time-budget for tool learning is limited. Consistency matters more than per-task optimization. + +### Intentional pluralism + +The team documents which tools fit which tasks; writers select per-task. Tool A for tasks of type X, tool B for tasks of type Y, contributors choose between them as appropriate. + +**When this fits.** Larger teams. Diverse content types. Writers have time to learn multiple tools. Per-task optimization matters more than absolute consistency. + +The discipline either way. The choice is documented; tool selection is not arbitrary or per-writer. + +--- + +## Forbidden patterns list + +The patterns the team explicitly does not use AI for, even when AI could technically do them. + +**Common forbidden patterns.** + +- AI fabricating quotes (always; this is fabrication) +- AI generating content that names specific real people (consent and verification issues) +- AI as the sole author of bylined opinion (ethics) +- AI for content involving regulated topics where the team lacks AI-policy guidance (medical advice, legal advice, financial advice) +- AI for content the team would be ashamed to publish under their byline (slop test) + +**Why this matters.** The forbidden list is shorter than the approved list but more important. The forbidden list is what keeps the program out of ethics violations and trust failures. + +--- + +## Onboarding + +New writers learn the AI policy and calibration in their first 2 weeks. + +**Onboarding components.** + +- **Policy read.** The new writer reads the AI policy doc. +- **Voice library walkthrough.** The new writer reviews the voice samples and prompt templates. +- **Calibration session participation.** The new writer participates in the next calibration session as observer. +- **Shadow assignment.** The new writer's first piece is reviewed jointly with an experienced editor; the editor narrates the calibration in real-time. +- **Quality benchmark walkthrough.** The new writer reviews the quality benchmarks and identifies what makes each "on-voice." + +**Why this matters.** New writers without onboarding develop their own AI patterns. The program drifts as new writers join. Onboarding makes the team's discipline transferable. + +--- + +## When team calibration breaks + +Symptoms. + +- Different writers produce wildly different AI-assisted output (calibration overdue) +- Editors disagree on whether a piece is "AI-flavored" (calibration session needed) +- The AI policy doc is 6 months stale and references tools the team no longer uses (policy update overdue) +- New writers are using AI in ways that experienced writers do not (onboarding gap) +- Voice library has not been updated since the program launched (library refresh overdue) + +The fix. Quarterly calibration sessions, quarterly policy review, quarterly voice library updates, structured onboarding for every new writer. The cadences are calendar-anchored; skipping them is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +The documented-policy structure, the calibration session methodology, the voice library practice, the quality-benchmark library, the standardization-vs-pluralism choice, the forbidden-patterns discipline, the onboarding components, the calibration-breakdown signals. + +## Implementation choices that stay internal + +The specific format of the policy doc (Notion page, Markdown file, internal wiki). The specific tooling that hosts the voice library (database, Notion, Git repo of sample text). The specific calibration session cadence and team composition. The specific onboarding tracking system. The specific tool selections the team has standardized on. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/voice-ownership-preservation.md b/skills/ai-content-collaboration/references/voice-ownership-preservation.md new file mode 100644 index 0000000..cbeb488 --- /dev/null +++ b/skills/ai-content-collaboration/references/voice-ownership-preservation.md @@ -0,0 +1,133 @@ +# Voice ownership preservation + +Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. + +Voice is the dominant casualty of careless AI workflows. The patterns below are what programs do to keep voice through AI-assisted production. Programs that skip these patterns produce content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +--- + +## Voice guidelines as prompt input + +The principle. Every AI generation includes the brand voice guidelines as part of the prompt context. Without explicit voice context, AI defaults to a generic register that flattens distinctive brands into industry-standard prose. + +**What goes into the prompt.** + +- Voice attributes (3 to 5 attributes; e.g., "direct, confident, slightly skeptical") +- Sentence rhythm preference (short and punchy, measured and layered, conversational with asides) +- Stance pattern (opinionated, diplomatic, coach-style, peer-style) +- Register (formal, casual, register that matches the surface) +- Vocabulary preferences (preferred terms, forbidden terms list) +- Anti-patterns (specific phrases or structures to avoid) + +**The discipline.** The voice guidelines are an input to every AI run, not a one-time setup. Teams that paste the voice guidelines into a saved prompt template ensure consistency; teams that re-type them per session produce drift. + +**Why this works.** Generic AI defaults are stronger than the AI's training-era voice memory. Without active voice prompting, the AI regresses to the most common patterns in its training data, which are the most common patterns in published content, which are by definition not distinctive. + +--- + +## Sample text as voice anchor + +The principle. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. + +**What to use as anchor.** + +- The brand's strongest published piece in the relevant register +- A canonical opening from the brand's editorial doc +- A published piece from a writer whose voice the brand wants to maintain consistency with + +**The discipline.** Anchor text is updated as the brand voice evolves. Stale anchors produce stale-feeling content; the program treats anchors as living documents. + +**Why this works.** Description prompts ("write in a direct, skeptical voice") are abstract. AI mimics them generically. Sample text is concrete; AI mimics specific patterns: word choices, sentence shapes, transitional phrases, opening patterns. The mimicry is not perfect but it is closer to the brand voice than the abstract description. + +**The combination.** The strongest voice prompt combines voice guidelines (description) with sample text (concrete examples). Either alone produces drift; together they hold the line. + +--- + +## Mid-draft voice check + +The principle. Long pieces drift. At the halfway mark of a 3,000-word piece, AI generations regress toward generic. The check catches the drift before publish. + +**The check.** + +1. Sample paragraphs from the start (first 300 words), middle (1,200 to 1,800 words), and end (last 300 words). +2. Compare each sample to the brand voice doc. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. Send back for revision. + +**Detection patterns.** + +- Vocabulary regresses (words from the do-not-use list reappear; brand-specific terms drop out) +- Sentence rhythm uniforms (every paragraph 2 to 3 sentences, similar lengths) +- Stance softens (specific positions become "there are good arguments on all sides") +- Register drifts toward "professional neutral" regardless of the surface's intended register + +**Cross-reference.** This check is also covered in `editorial-qa/references/voice-consistency-patterns.md`. The two skills are aligned; the QA gate enforces what this skill prescribes. + +--- + +## Final pass in human voice + +The principle. The human edits the closing sections in their own voice. The closing is where the piece's emotional register often lands; AI defaults there reduce the piece to flat informational tone. + +**Why the closing matters.** + +- The reader's last impression +- The conversion or memory moment for the piece +- The signature moment where the brand voice is most recognizable + +**The discipline.** Even in Pattern 1 (AI-first draft, human-edit-heavy), the closing 100 to 300 words should be substantially or fully human-written. The opening can be AI-drafted with heavy editing; the closing benefits from being composed in the writer's own register. + +**Anti-pattern.** AI-drafted closing paragraphs that announce the piece is ending ("In summary," "By following these steps," "Now you have a comprehensive understanding"). These are AI tells; the human pass should replace them with specific endings: a question, an action, an observation, a direct call to action with concrete language. + +--- + +## Reject the bland + +The principle. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +**The audit.** Read the piece. For each sentence, ask: is this distinctively from this brand, or could it have come from any competitor? The interchangeable sentences are the bland ones. + +**The fix.** + +- **Replace abstractions with specifics.** "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research, do the research; if not, cut the claim. +- **Replace hedges with stances.** "It depends on your situation" becomes "for teams under 50 employees, [specific recommendation]; for teams over 200, [different specific recommendation]." +- **Replace generic openings with brand-specific openings.** Throat-clearing intros become specific entry-points tied to the piece's argument. + +**The discipline.** Bland sentences are not just "less interesting" sentences; they are voice-killers. A piece with 20% bland sentences reads as 80% diluted; the brand voice is present but watered down past distinction. + +--- + +## The voice library + +A program-level practice. The team maintains a library of canonical brand-voice samples that get used as anchor text in AI prompts. The library evolves as the brand voice evolves. + +**Library structure.** + +- Voice samples by register (formal whitepaper, casual blog post, conversational email, professional help doc) +- Voice samples by content type (pillar editorial, cluster piece, thought leadership, listicle) +- Voice samples by writer (where the brand has multiple distinct contributor voices) + +**Update cadence.** Quarterly. As new pieces ship that exemplify the voice, they go into the library. As old pieces feel stale, they come out. + +**Why this matters.** Teams without a voice library re-paste the same 3 paragraphs as anchor text for years. The voice ages; the AI mimicry ages with it; the content starts feeling dated. Library updates keep the anchor fresh. + +--- + +## When voice cannot be preserved + +Sometimes the voice is genuinely incompatible with AI assistance at the volume the program requires. Signals. + +- Brand voice is so distinctive that AI drafts always need 80% rewriting (Pattern 2 might fit; if even Pattern 2 fails, Pattern 3 or 4 are the only options) +- Audience is so trust-sensitive that any AI involvement compromises the byline (Pattern 3 only) +- Volume target requires AI involvement that voice cannot tolerate + +The honest answer in these cases. Reduce volume to match what voice tolerates, or accept voice trade-off as a strategic choice. The trade-off must be deliberate; "we did not realize voice was suffering" is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +Voice guidelines as prompt input, sample text as voice anchor, the mid-draft sampling discipline, the final-pass-in-human-voice discipline, the reject-the-bland audit, the voice library practice, the "when voice cannot be preserved" honest framing. + +## Implementation choices that stay internal + +The specific format of the brand voice doc (Notion page, Markdown file, internal wiki). The specific AI tool prompt templates that include voice guidelines and sample text. The specific voice library storage and access pattern. The specific calibration session cadence and team composition. These vary by brand and team. diff --git a/skills/analytics-strategy/SKILL.md b/skills/analytics-strategy/SKILL.md new file mode 100644 index 0000000..c67502c --- /dev/null +++ b/skills/analytics-strategy/SKILL.md @@ -0,0 +1,230 @@ +--- +name: analytics-strategy +description: "Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track." +category: growth +catalog_summary: "Measurement frameworks, dashboard design, event taxonomy" +display_order: 1 +--- + +# Analytics Strategy + +Design measurement frameworks that produce decisions, not just dashboards. Stack-agnostic. Tool-agnostic. + +This skill is for measurement planning. For conversion optimization, use `cro-optimization`. For SEO measurement specifically, use `seo-onpage` and adjacent SEO skills. + +--- + +## When to use + +- Setting up analytics on a new product or site +- Auditing existing analytics setup +- Designing dashboards for a team or business +- Defining KPIs and a north star metric +- Building event taxonomies for product analytics +- Designing attribution models for marketing +- Translating business questions into measurement plans + +## When NOT to use + +- Conversion testing or optimization (use `cro-optimization`) +- SEO performance measurement (use SEO skills) +- Pure data infrastructure decisions (different domain) + +--- + +## Required inputs + +- The business or product context (what does success look like) +- The audience for the analytics (who needs to make what decisions) +- The current measurement state (existing tools, tracking, gaps) +- The questions the team needs to answer + +--- + +## The framework: 4 layers + +A complete measurement strategy covers all four. Each layer feeds the next. + +### 1. North star and KPI hierarchy + +The single metric that captures the most important outcome, plus the supporting metrics. + +**North star metric:** + +- One metric. Singular. +- Captures customer-perceived value. +- Leads to revenue, but isn't revenue itself (revenue is too far downstream). +- Examples: weekly active users, completed jobs, revenue-generating sessions, hours of value delivered. + +**Underneath the north star, the KPI hierarchy:** + +``` +North star metric +├── Acquisition KPI (how new users enter) +├── Activation KPI (when new users get value) +├── Engagement KPI (how often users return) +├── Retention KPI (how many stick over time) +└── Monetization KPI (how value translates to revenue) +``` + +This is the "AARRR" or "pirate metrics" framework. It works because it covers the full lifecycle. + +### 2. Event taxonomy + +The vocabulary the product uses to describe what users do. + +**Event design principles:** + +- **Verb + noun.** `signed_up`, `created_project`, `completed_checkout`. Past tense, snake_case. +- **One event per discrete action.** Not "interacted_with_modal" - too vague. Specifically `opened_modal_X`, `closed_modal_X`, `confirmed_in_modal_X`. +- **Properties capture context.** Each event has properties (key-value pairs) for context. `signed_up` has properties like `signup_method`, `referrer`, `plan`. +- **Standardize property names.** `user_id` everywhere, not `userId` here and `id` there. +- **Document everything.** A tracking plan that lives nowhere is a tracking plan no one follows. + +**Event coverage:** + +- All key user actions tracked +- All conversion points tracked +- All errors tracked +- All page views tracked (with consistent properties) +- All button clicks that matter (not all button clicks - that's noise) + +**Anti-patterns:** + +- 500+ events with no documentation +- Inconsistent naming (`buttonClicked`, `Button Clicked`, `clicked_button`) +- Property keys that vary across events +- Events fired client-side that should be server-side (and vice versa) +- PII in event properties (privacy issue and tooling issue) + +### 3. Dashboards and reports + +The interface between data and decisions. + +**Dashboard design principles:** + +- **One audience per dashboard.** Executive dashboard != product team dashboard. Different metrics, different cadence. +- **One question per chart.** A chart should answer one question, not three. +- **Annotations matter.** Note launches, experiments, holidays, outages. A spike means nothing without context. +- **Context comparisons.** "10,000 signups this month" - compared to what? Last month, last year, target? +- **Lead with the action.** What does this dashboard help someone decide? + +**Common dashboard types:** + +| Dashboard | Audience | Metrics | Cadence | +|---|---|---|---| +| Executive | Leadership | North star, top 3 KPIs, big-picture trends | Weekly review | +| Product | Product team | Funnel metrics, feature adoption, retention | Daily / weekly | +| Marketing | Marketing team | Acquisition by channel, CAC, attribution | Daily / weekly | +| Operations | Ops / on-call | Performance, errors, capacity | Real-time | +| Custom (per team) | Specific team | Their specific KPIs | Their cadence | + +### 4. Attribution and segmentation + +How to connect cause and effect. + +**Attribution models:** + +- **First-touch.** Credit the first interaction. Useful for awareness understanding. +- **Last-touch.** Credit the final interaction before conversion. Default in many tools, often misleading. +- **Linear.** Spread credit equally across touches. Avoids over-crediting any single channel. +- **Time-decay.** Recent touches get more credit. Reasonable middle ground. +- **Position-based.** First and last get more credit, middle touches less. +- **Data-driven (algorithmic).** Tools like Google Analytics 4 use ML. Black box but increasingly the default. + +For most businesses: pick one primary attribution model, use multiple secondary models for validation. + +**Segmentation principles:** + +- Segment by what causes different behavior, not by what's easy to track +- Useful segments: source/channel, plan tier, geography, device, cohort (signup date) +- Less useful: demographic guesses without behavioral validation + +--- + +## The tracking plan document + +Output of the analytics strategy. A living document. + +**Structure:** + +1. **Goals and KPIs.** Business objectives, north star, KPI hierarchy. +2. **Event catalog.** Every event, with properties, when fired, why tracked. +3. **User properties.** Persistent attributes (plan, signup_date, role). +4. **Page taxonomy.** Page categories, page properties. +5. **Naming conventions.** Snake_case, verb_noun, etc. +6. **Implementation notes.** Client-side vs server-side, SDK details, sampling. +7. **Privacy and compliance.** PII rules, consent handling, data retention. +8. **Governance.** Who can add events, review process, change log. + +--- + +## Workflow + +1. **Define the questions.** What does the team need to answer? Working backward from questions to metrics works better than starting from metrics. +2. **Define the north star.** One metric. Tested against the criteria above. +3. **Build the KPI hierarchy.** Acquisition, activation, engagement, retention, monetization. +4. **Audit existing tracking.** What's there? What's broken? What's missing? +5. **Design the event taxonomy.** Cover the user journey. Document everything. +6. **Implement with care.** Test each event. Verify properties. Catch issues in staging. +7. **Build dashboards.** One per audience. Lead with action. +8. **Establish review cadence.** Weekly business review, monthly KPI review, quarterly strategy review. +9. **Govern.** Who adds events, who reviews, how changes propagate. + +--- + +## Failure patterns + +- **Tracking everything.** Noise overwhelms signal. +- **Tracking nothing strategic.** Page views and that's it. Cannot answer real questions. +- **No documentation.** Tracking plan lives in someone's head. +- **Inconsistent naming.** Same concept, three names. Reports become detective work. +- **Events fired but never reviewed.** Tracking debt accumulates. +- **Dashboards no one looks at.** Built for vanity, not decisions. +- **Single attribution model treated as truth.** All models lie. Some lie usefully. +- **PII in events.** Compliance and tooling problems. +- **Client-side only.** Critical business events should be server-side too. Ad blockers, network issues, edge cases lose client-side events. +- **No connection to business outcomes.** Metrics exist in a silo, never connected to revenue, retention, or strategic decisions. + +--- + +## Output format + +Default output: a markdown tracking plan at `analytics-tracking-plan.md` plus a dashboard inventory. + +Tracking plan structure: + +```markdown +# Tracking Plan + +## North star metric +[Definition, calculation, target] + +## KPI hierarchy +[Each KPI with definition, calculation, owner] + +## Event catalog +| Event | When fired | Properties | Owner | Status | +|---|---|---|---|---| +| user_signed_up | After successful signup form submit | source, plan, referrer | Marketing | Live | +| project_created | When user clicks Create Project | project_type, template_used | Product | Live | +| ... | | | | | + +## User properties +[List with definitions] + +## Naming conventions +[Rules] + +## Privacy and compliance +[Rules] + +## Governance +[Process] +``` + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Starter event catalog with patterns for common product types. diff --git a/skills/analytics-strategy/references/event-taxonomy-template.md b/skills/analytics-strategy/references/event-taxonomy-template.md new file mode 100644 index 0000000..69e22bb --- /dev/null +++ b/skills/analytics-strategy/references/event-taxonomy-template.md @@ -0,0 +1,407 @@ +# Event Taxonomy Template + +Starter event catalogs for common product types. Adapt to specific products. The patterns generalize. + +--- + +## Universal events (most products need these) + +### Lifecycle events + +| Event | When fired | Common properties | +|---|---|---| +| `user_signed_up` | New account created | signup_method, source, referrer, plan | +| `user_logged_in` | Successful login | login_method | +| `user_logged_out` | Session ended | session_duration | +| `user_deleted_account` | Account deletion | reason (if collected) | + +### Product/feature engagement + +| Event | When fired | Common properties | +|---|---|---| +| `feature_used` | Specific feature interaction | feature_name, feature_version | +| `setting_changed` | User changes a setting | setting_name, old_value, new_value | +| `notification_clicked` | User clicks a notification | notification_type, notification_id | + +### Errors + +| Event | When fired | Common properties | +|---|---|---| +| `error_occurred` | Anywhere an error is shown to user | error_type, error_message, page, action_attempted | +| `form_validation_failed` | Form submit blocked by validation | form_name, fields_with_errors | + +### Communication + +| Event | When fired | Common properties | +|---|---|---| +| `email_received` | Email delivered (server-side, via ESP webhook) | email_type, campaign_id | +| `email_opened` | Email opened (via tracking pixel) | email_type, campaign_id | +| `email_clicked` | Link in email clicked | email_type, campaign_id, link_text | +| `email_unsubscribed` | User unsubscribes | email_type | + +--- + +## SaaS / B2B product events + +``` +Acquisition +├── user_signed_up +├── trial_started +└── trial_extended + +Activation (the "aha" moment) +├── workspace_created +├── teammate_invited +├── first_project_created +├── first_integration_connected +└── first_value_action (product-specific - the moment user gets value) + +Engagement +├── session_started +├── project_opened +├── workflow_completed +└── feature_X_used (one per key feature) + +Conversion +├── plan_upgraded +├── seats_added +├── invoice_paid +└── annual_plan_purchased + +Retention +├── returned_after_inactivity +├── reactivated_from_email +└── usage_milestone_hit (e.g., crossed 100 actions) + +Risk signals +├── support_ticket_opened +├── billing_failure_occurred +├── trial_expiring_soon (calculated, server-side) +└── churn_risk_threshold_hit (calculated) +``` + +### Properties to capture across all events + +``` +user_id Persistent across sessions +session_id New per session +account_id For multi-user accounts +plan Current plan tier +days_since_signup +device_type +browser +os +geo_country +geo_region +referrer +utm_source / utm_medium / utm_campaign / utm_term / utm_content +``` + +--- + +## Ecommerce events + +``` +Discovery +├── page_viewed +├── search_performed +├── search_results_viewed +├── filter_applied +└── product_listing_viewed + +Consideration +├── product_viewed +├── product_image_zoomed +├── size_selected +├── color_selected +├── reviews_read +└── product_shared + +Cart +├── product_added_to_cart +├── product_removed_from_cart +├── cart_viewed +├── cart_quantity_changed +└── cart_abandoned (calculated, server-side) + +Checkout +├── checkout_started +├── shipping_info_entered +├── billing_info_entered +├── promo_code_applied +├── promo_code_failed +├── checkout_step_viewed (with step_name) +└── purchase_completed + +Post-purchase +├── order_shipped +├── order_delivered +├── product_returned +├── review_submitted +└── reorder_initiated +``` + +### Ecommerce-specific properties + +``` +For purchase_completed: + order_id + total_value + currency + shipping_method + payment_method + discount_applied + items: [ + { product_id, product_name, category, brand, variant, quantity, unit_price } + ] + +For product_viewed: + product_id + product_name + category + brand + price + in_stock + position (when viewed in a list) +``` + +--- + +## Content site / publisher events + +``` +Reading +├── page_viewed +├── article_started (when article body enters viewport) +├── article_25_percent_scrolled +├── article_50_percent_scrolled +├── article_75_percent_scrolled +├── article_100_percent_scrolled (read to end) +└── article_time_spent (calculated on page exit) + +Engagement +├── newsletter_signup_shown +├── newsletter_signup_completed +├── comment_posted +├── article_shared +├── article_bookmarked +└── related_article_clicked + +Subscription (if metered/paywalled) +├── paywall_hit +├── paywall_dismissed +├── subscribe_started +├── subscribe_completed +├── article_unlocked (free, registered, paid) +``` + +### Content-specific properties + +``` +For article events: + article_id + article_title + category + author + published_date + word_count + paywall_status (free, registered_only, paid_only) + is_premium +``` + +--- + +## Marketplace events + +Marketplaces have two-sided tracking: buyers and sellers/providers. + +``` +Buyer side +├── search_performed +├── listing_viewed +├── inquiry_sent +├── booking_started +├── booking_completed +├── review_left +└── repeat_booking_made + +Seller/provider side +├── listing_created +├── listing_published +├── listing_edited +├── inquiry_received +├── inquiry_responded +├── booking_received +├── booking_completed +├── payout_received +└── review_received +``` + +### Marketplace-specific properties + +``` +For listing_viewed: + listing_id + category + price + location + seller_id + position_in_search + +For booking_completed: + booking_id + listing_id + seller_id + buyer_id + total_value + fee_amount +``` + +--- + +## Mobile app events + +``` +App lifecycle +├── app_installed (server-side or attribution platform) +├── app_first_opened +├── app_opened (every launch) +├── app_backgrounded +├── app_foregrounded +└── app_uninstalled (often inferred, hard to track directly) + +Engagement +├── push_notification_received +├── push_notification_opened +├── deep_link_opened +└── share_extension_used + +Permissions +├── permission_requested (push, location, camera, etc.) +├── permission_granted +└── permission_denied +``` + +### Mobile-specific properties + +``` +app_version +app_build +device_model +os_version +network_type (wifi, cellular) +push_token +notification_permission_status +``` + +--- + +## Forms and surveys + +``` +Form lifecycle +├── form_viewed +├── form_started (first field interaction) +├── form_field_focused +├── form_field_completed +├── form_field_validation_failed +├── form_submitted +└── form_abandoned (left page without submit) +``` + +### Properties + +``` +form_name +form_id +fields_total +fields_completed +fields_with_errors +time_spent_seconds +``` + +--- + +## Naming convention rules + +### Verb_noun, past tense, snake_case + +✓ `user_signed_up` +✓ `product_added_to_cart` +✓ `article_50_percent_scrolled` +✗ `signupCompleted` +✗ `addProduct` +✗ `Article 50% Scrolled` + +### Properties: camelCase or snake_case (pick one and stay) + +snake_case is more common in SQL contexts (data warehouses). +camelCase is more common in JavaScript/TypeScript contexts. +The choice matters less than consistency. + +✓ `user_id`, `signup_method`, `email_type` (consistent snake_case) +✓ `userId`, `signupMethod`, `emailType` (consistent camelCase) +✗ `userId`, `signup_method`, `EmailType` (mixed) + +### Property values: standardize where possible + +Don't allow free-text where an enum should exist. + +✓ `signup_method: "email" | "google" | "github" | "sso"` +✗ `signup_method: "email", "Email", "EMAIL", "via email", "with email address"` + +### Reserved properties + +Most analytics tools have built-in properties. Don't override them. + +Common reserved names: +- `id`, `userId` (or system equivalent) +- `event`, `event_name` +- `timestamp`, `time` +- `session_id` +- `anonymous_id` +- `properties`, `traits` + +--- + +## What NOT to track + +- **PII in event properties.** Email, phone, full name, address. Privacy issue and tooling issue. +- **Every click.** Track meaningful clicks. Hover events. Mouse movements. Generic interactions are noise. +- **Server-side state churn.** Background jobs, cron runs, internal events. These belong in monitoring, not product analytics. +- **Anything you cannot define in one sentence.** If you can't describe what the event represents, you won't be able to use it. + +--- + +## Privacy and consent + +Common compliance patterns: + +- **Consent before tracking.** Cookie banner, opt-in flow. +- **Honor Do Not Track.** Browsers signal preferences. +- **Right to deletion.** User can request all their data deleted (GDPR, CCPA). +- **Right to export.** User can request their data in machine-readable format. +- **No cross-site tracking without consent.** Some jurisdictions require explicit opt-in. +- **Data residency.** EU user data may need to stay in EU. + +Standard compliance approaches: + +- Server-side tagging when available (more reliable, more controllable) +- Consent management platform (CMP) for cookie consent +- Clear privacy policy that lists what you collect +- A pseudonymous user ID separate from PII + +Compliance specifics vary by jurisdiction. Consult counsel for high-stakes decisions. + +--- + +## Governance and review + +Patterns that work: + +- New events require an RFC or short proposal +- Event catalog reviewed quarterly +- Deprecated events flagged and removed after a grace period +- Tracking plan version-controlled (in Git) +- Implementation tested in staging before production +- Monitoring on event volume (sudden drops = tracking break) diff --git a/skills/art-direction/SKILL.md b/skills/art-direction/SKILL.md new file mode 100644 index 0000000..65e9452 --- /dev/null +++ b/skills/art-direction/SKILL.md @@ -0,0 +1,198 @@ +--- +name: art-direction +description: "Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables." +category: design +catalog_summary: "Photography, illustration, and visual direction for campaigns" +display_order: 3 +--- + +# Art Direction + +Direct creative work that extends the brand into specific deliverables. Photography, illustration, video, motion, campaigns, environmental design. + +This skill assumes brand identity is approved (`brand-identity` complete). Art direction is about applying and extending it, not defining it. + +--- + +## When to use + +- Briefing photographers, illustrators, videographers +- Developing campaign creative concepts +- Directing in-house creative teams +- Writing creative direction documents for vendors +- Evaluating creative deliverables for brand fit +- Adapting brand visual identity to a new format or context + +## When NOT to use + +- Setting project-wide aesthetic direction across multiple downstream skills (use `creative-direction` instead). This skill briefs specific creative deliverables; `creative-direction` produces the structured aesthetic brief that this skill consumes. +- Defining brand visual identity from scratch (use `brand-identity`) +- Day-to-day component design (use `design-standards`) +- Writing copy for creative work (use `content-and-copy` or `landing-page-copy`) +- Building a design system (use `design-system`) + +--- + +## Required inputs + +- The deliverable (photo shoot, illustration set, video, campaign) +- The brand identity (visual system, voice, imagery direction) +- The audience for this specific work +- The goal (brand awareness, conversion, education, emotional connection) +- Budget and timeline +- Distribution context (where it will be seen) + +--- + +## The framework: 5 layers + +A creative brief covers five layers. Each must be clear before the brief leaves your hands. + +### 1. The story + +What this creative work is fundamentally about. + +- **The premise.** The core idea in one sentence. +- **The emotional through-line.** What the audience feels. +- **The role of the brand.** How the brand shows up in the story. +- **The takeaway.** What the audience walks away with. + +A weak premise produces work that's pretty but says nothing. Spend time here. + +### 2. The look + +The visual treatment. + +**For photography:** +- Subject and composition (close-up, environmental, candid, posed) +- Lighting (natural, studio, dramatic, soft) +- Color palette (true color, treated, monochrome) +- Locations (specific or general direction) +- Wardrobe and props +- Mood references (3 to 5 reference images) + +**For illustration:** +- Style (flat, dimensional, hand-drawn, geometric, abstract) +- Color use (full palette, restricted, brand-only) +- Line treatment +- Composition style +- Detail level +- Reference artists or works (with explicit "we want like X but NOT like Y") + +**For video / motion:** +- Pacing (slow, medium, fast cuts) +- Camera movement (static, handheld, sweeping) +- Color grading +- Transitions and effects +- Audio direction (music, voiceover, ambient) +- Reference work (3 to 5 examples) + +### 3. The execution + +Production-level direction. + +**Specifications:** +- Deliverable formats and sizes (web hero, social square, print full-page) +- Required shots or frames +- Optional shots if budget allows +- Wardrobe and prop list (for live action) +- Color and asset specs (RGB, CMYK, hex codes for matching) + +**Constraints:** +- Things to avoid (specific cliches, forbidden treatments, regulatory) +- Brand-system requirements (logo placement, color use, type rules) + +### 4. The variants + +How this creative scales across distribution. + +Most creative needs to live in multiple places. Plan the variants up front. + +**Common variant set for a campaign:** +- Hero web image (16:9 or wider) +- Mobile web hero (4:5 or 1:1) +- Social square (1:1) +- Social vertical (9:16) +- Email banner (3:1 typical) +- Display ad sizes (300x250, 728x90, etc.) +- Print sizes if applicable + +For each variant, note: how the composition adapts, what gets cropped or repositioned, what assets are required. + +### 5. The standards + +The quality bar. + +**Technical:** +- Resolution and format requirements +- Color profile +- File naming conventions +- Delivery format (raw + edited, layered files, exported variants) + +**Creative:** +- What "approved" looks like (specific examples of acceptable work) +- What "not approved" looks like (specific examples to avoid) +- Number of revision rounds budgeted + +--- + +## Workflow + +### For briefing external creative + +1. **Confirm the inputs.** Brand identity locked. Audience and goal clear. Budget and timeline known. +2. **Develop the concept.** Premise, emotional through-line, takeaway. +3. **Build the look.** Mood references. Specific direction on style elements. +4. **Write the spec.** Production-level direction. Variants. Constraints. +5. **Brief the vendor.** In writing. Walk through it live. Allow questions. +6. **Review milestones.** Treatment review, halfway review, final review. Don't skip the early reviews; corrections compound. +7. **Approve and document.** What was produced, what's licensed for what use. + +### For directing in-house creative + +1. **Same brief, lighter format.** In-house direction can be more iterative. Still document the brief. +2. **Co-create.** In-house teams know the brand. Use their judgment. Don't over-direct. +3. **Establish review rhythm.** Daily check-ins for fast work, weekly for longer projects. + +### For evaluating existing creative + +1. **Score against the brief.** Did the work hit the brief? Where did it deviate? +2. **Score against the brand.** Does this look like the brand? Could this be confused with a competitor? +3. **Score against the goal.** Will this drive the intended outcome? +4. **Identify fixes.** What can be improved? What's a deal-breaker vs. acceptable? + +--- + +## Failure patterns + +- **"Modern, clean, minimal" briefs.** Means nothing. Force specificity. Use specific reference brands, named artists, or visual examples. +- **No "what to avoid" direction.** Vendors interpret broadly. Tell them what's out of bounds explicitly. +- **Reference imagery that's actually competitor work.** You'll get something that looks like the competitor. Never use direct competitors as references. +- **Skipping early reviews.** Every revision late in the process is 5x more expensive than catching issues at treatment stage. +- **Too many cooks.** 6 stakeholders all giving creative feedback produces incoherent work. Concentrate creative authority. +- **Ignoring distribution.** Creative that doesn't work in the actual contexts where it will live is failed creative. +- **No variant planning.** Discovering at delivery that you need a square crop and the photographer composed for 16:9 only. +- **Approving creative that's "fine."** Fine is the enemy of distinctive. If it doesn't move you, it won't move the audience. + +--- + +## Output format + +Default output is a creative brief at `creative-brief-[project].md`. + +Structure: +1. The story (premise, through-line, role of brand, takeaway) +2. The look (visual treatment with references) +3. The execution (specs, variants, constraints) +4. The standards (quality bar, examples of acceptable and unacceptable) +5. The logistics (timeline, milestones, budget, deliverables) + +Plus a separate moodboard or visual reference doc with images. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Generic art direction brief template covering any production type (photo, illustration, video, animation, mixed). +- [`references/photo-shoot-brief.md`](references/photo-shoot-brief.md) - Detailed brief template for photography commissions. +- [`references/illustration-brief.md`](references/illustration-brief.md) - Brief template for illustration commissions. diff --git a/skills/art-direction/references/creative-brief-template.md b/skills/art-direction/references/creative-brief-template.md new file mode 100644 index 0000000..feb2406 --- /dev/null +++ b/skills/art-direction/references/creative-brief-template.md @@ -0,0 +1,249 @@ +# Art Direction Brief Template + +A fillable brief for art direction projects. Fill every section before production begins. A short brief beats a generic brief; a generic brief produces generic work. + +--- + +## Project: [Name] + +**Project type:** [Photography / Illustration / Video / Animation / Mixed] +**Channel(s):** [Where this will live] +**Date briefed:** [YYYY-MM-DD] +**Production date:** [YYYY-MM-DD] +**Director:** [Name] +**Producer:** [Name] +**Budget:** [Range] + +--- + +## 1. Project context + +**Why this project exists:** +[1 to 2 paragraphs. The business reason this work needs to be made.] + +**What it must accomplish:** +[The specific outcome. Awareness, conversion, brand association, internal use, etc.] + +**How it will be measured:** +[Concrete success indicator. Engagement, completion rate, brand lift, internal feedback.] + +--- + +## 2. Concept + +**The big idea (one sentence):** +[The angle, insight, or opinion the creative work expresses.] + +**Why this concept now:** +[2 to 3 sentences. Why this idea fits the moment, the brand, and the audience.] + +**What this concept rejects:** +[The opposite or adjacent ideas this concept is not.] + +--- + +## 3. Audience + +**Primary audience:** +[Specific persona. "Mid-career operator at a B2B SaaS company evaluating tools for their team," not "B2B buyers."] + +**What they currently feel about the category:** +[1 to 2 sentences.] + +**What we want them to feel after seeing this:** +[1 to 2 sentences.] + +--- + +## 4. Subjects + +**People:** +- Cast: [Demographics, archetypes, specific casting direction] +- Wardrobe: [Direction] +- Expression: [What we want them showing] +- Diversity: [Explicit casting expectations] + +**Products:** +- What appears: [List] +- Staging: [How they're shown] +- Hierarchy: [Hero product vs supporting] + +**Settings:** +- Locations: [Specific or category] +- Environment: [Indoor/outdoor, real/built, public/private] +- Time of day: [If relevant] + +**Objects/props:** +- Required: [Specific items] +- Forbidden: [Things never to include] + +--- + +## 5. Composition + +**Formats and channels:** +| Channel | Aspect ratio | Resolution | Specific requirements | +|---|---|---|---| +| [e.g., Instagram feed] | 1:1 | [px] | [Crop-safe area for text overlay] | +| [e.g., Instagram stories] | 9:16 | [px] | [Top/bottom safe areas] | +| [e.g., Web hero] | 16:9 | [px] | [Subject must allow text overlay on left] | +| [e.g., Print] | [Specific] | [DPI] | | + +**Shot list:** +[Specific shots required. Include reference frame for each.] + +1. [Shot description]: [Reference image] +2. [Shot description]: [Reference image] +3. [Shot description]: [Reference image] + +**Framing direction:** +- Crop tendency: [Tight / medium / wide] +- Subject placement: [Centered / off-center / dynamic] +- Eye line: [To camera / away / unspecified] +- Depth: [Foreground emphasis / background environment / flat] +- Negative space: [Generous / minimal / variable] + +--- + +## 6. Lighting + +**Direction:** +[2 to 4 sentences describing the lighting approach.] + +**Specific qualities:** +- Source: [Natural / available / controlled] +- Direction: [Front / side / back / overhead] +- Quality: [Hard / soft] +- Color temperature: [Warm / neutral / cool] +- Time of day if natural: [Specific] + +**Lighting references:** +[3 to 5 reference images with annotations.] + +--- + +## 7. Color and treatment + +**Color palette:** +[Brand palette + any campaign-specific extensions] + +**Treatment direction:** +- Saturation: [True / muted / desaturated / heightened] +- Contrast: [Low / balanced / high] +- Color grade: [Specific look or signature] +- Film references: [Specific films, photographers, or art if relevant] + +**Treatment references:** +[3 to 5 reference images with annotations.] + +--- + +## 8. Tone + +**Adjectives (3 to 5):** +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] + +**Pacing (moving image):** +[If applicable: brisk / deliberate / breathless / languid] + +**Sound direction (moving image):** +[If applicable: score, sound design, voice, silence] + +--- + +## 9. Reference moodboard + +[Link to moodboard with 10 to 15 curated images.] + +Each reference labeled with what we are taking from it (composition, lighting, treatment, casting, etc.). Avoid using a single reference for everything; pull specific elements from different sources. + +--- + +## 10. What to avoid + +**Visual cliches in our category to reject:** +- [Specific cliche with example] +- [Specific cliche with example] +- [Specific cliche with example] + +**Treatments not aligned with our direction:** +- [Specific treatment] +- [Specific treatment] + +**Casting we will not use:** +- [Specific casting type and why] + +--- + +## 11. Deliverables + +**Final deliverables required:** + +| Asset | Format | Count | Specifications | +|---|---|---|---| +| [e.g., Hero image] | JPG, PNG | 5 | 16:9, 4K | +| [e.g., Story crops] | MP4 | 10 | 9:16, 1080p, 15s max | +| [e.g., Behind-the-scenes] | MP4 | 1 | 16:9, 60s | + +**Editing/retouching specifications:** +[Color grading approach, retouching rules, watermarking, captions] + +**File naming convention:** +[`project-asset-version-channel.format`] + +**Delivery method:** +[How files arrive. Drive, DAM, direct upload.] + +--- + +## 12. Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Pre-production complete | | | +| Production day(s) | | | +| Selects review | | | +| Edit v1 / first cut | | | +| Final delivery | | | + +--- + +## 13. Approvals + +**Approval path:** +1. [Person / role] - [What they approve] +2. [Person / role] - [What they approve] +3. [Final approver] + +**Maximum review rounds:** [Typically 2 to 3] +**Hard stop:** [Date after which changes are out of scope] + +--- + +## 14. Talent + +**Photographer / Illustrator / Director:** [Name and rate] +**Why we picked them:** [1 to 2 sentences linking their portfolio to this brief] +**Crew:** [Producer, stylist, lighting, etc.] +**Talent (on-camera):** [Casting decisions] + +--- + +## 15. Open questions + +[Anything unresolved at brief-writing time. Resolve before production day.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: +- [Name] [Date] +- [Name] [Date] + +Production day(s) confirmed: [Date] diff --git a/skills/art-direction/references/illustration-brief.md b/skills/art-direction/references/illustration-brief.md new file mode 100644 index 0000000..46bba36 --- /dev/null +++ b/skills/art-direction/references/illustration-brief.md @@ -0,0 +1,238 @@ +# Illustration Brief + +A complete brief for commissioning illustration work. Use as a starting template, fill out fully before sending to the illustrator. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a redo (and most illustrators charge for redos). + +--- + +## Project overview + +**Project name:** [Working title] +**Date of brief:** [YYYY-MM-DD] +**Delivery deadline:** [Final files due] +**Illustrator / studio:** [If selected] +**Producer / point of contact:** [Name and contact] +**Budget:** [Total or per-illustration rate] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is each illustration fundamentally about?] + +### Audience +[Who will see these illustrations. Their context, their state of mind.] + +### Goal +[What do these illustrations accomplish? Editorial illustration, brand storytelling, product visualization, instruction, decoration?] + +### Brand role +[How does the brand show up? Subtle (illustrations stand on their own), prominent (brand mark visible in scene), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Playful," "considered," "warm," "sharp," "optimistic."] + +--- + +## The look + +### Style references + +[5 to 10 reference illustrations. Source: illustrator portfolios (Behance, It's Nice That, Cargo), editorial illustration archives, ad campaigns. AVOID: direct competitor imagery, AI-generated images, copyrighted character work used out of context.] + +For each reference, note WHAT to take from it: +- "From this illustration: the loose hand-drawn line quality" +- "From this illustration: the limited color palette" +- "From this illustration: the flat geometric construction" + +NOT just dumping references with no commentary. The illustrator needs to know which qualities matter. + +### What to AVOID + +- [Specific style cliche to avoid, e.g., "Corporate Memphis / Alegria figures"] +- [Specific style cliche to avoid, e.g., "isometric tech-startup spot illustrations"] +- [Visual treatment that's been overused in the category] + +### Style and technique + +- **Medium:** [Vector / raster / mixed / hand-drawn scanned / 3D] +- **Line quality:** [Geometric and clean / loose and gestural / no line / variable] +- **Fill style:** [Flat / textured / gradients / cross-hatching / watercolor] +- **Detail level:** [Highly detailed / minimal / mid] +- **Perspective:** [Flat / isometric / one-point / loose / mixed] +- **Figure style** (if illustrating people): [Realistic / stylized / abstract / no figures] + +### Color + +- [Specific palette with hex codes if matching brand] +- [Number of colors: limited (2-3), moderate (4-6), full] +- [Treatment: brand-matched / shifted / monochrome / sepia / saturated / muted] + +### Composition + +- [Single subject focus / scene with multiple elements / pattern / decorative] +- [Negative space treatment] +- [Orientation defaults: square, landscape, portrait, mixed] + +--- + +## Illustration list + +A specific list of illustrations needed. Each entry is a deliverable. + +### Required illustrations (must-have) + +1. **[Illustration name]** + - Subject: [What's depicted] + - Concept: [What it should communicate or evoke] + - Use case: [Where it will appear, e.g., "blog post hero, 1200x675"] + - Variants: [Aspect ratios or color modes needed] + +2. **[Illustration name]** + - Subject: + - Concept: + - Use case: + - Variants: + +[Continue for all required illustrations] + +### Optional illustrations (if time and budget allow) + +1. **[Illustration name]** +2. **[Illustration name]** + +### Variants per illustration + +Most illustrations need to work in multiple contexts: + +- **Light mode and dark mode:** does the illustration need a dark-background variant? +- **Aspect ratios:** which crops are needed (16:9, 1:1, 9:16, banner)? +- **Resolution variants:** retina vs standard, social vs hero +- **Cropped vs full:** is a cropped detail of the same illustration also needed? +- **Animation:** is a static illustration plus a looping animated version needed? + +When briefing, note which variants each illustration must support. + +--- + +## Technical specs + +### Source files + +- **Format:** [AI / SVG / PSD / PNG layered / Procreate / Figma] +- **Layered structure required:** [Yes - so the brand can adjust colors, swap elements, or animate later. No - flat delivery only.] +- **Editability:** [Editable text and shapes preferred / OK to outline] + +### Export formats + +- **Web:** [SVG for vector, WebP / PNG for raster] +- **Print:** [If applicable: CMYK, 300 DPI, with bleed] +- **Resolution:** [Specific minimums per use case] +- **Color profile:** [sRGB for web, CMYK for print] + +### Delivery + +- **Format:** [Cloud delivery, file sharing, hard drive] +- **Naming convention:** [e.g., "ProjectName_IllustrationN_VariantX.svg"] +- **Asset management:** [Where the files live after delivery] + +### Licensing + +- **Usage:** [Where the illustrations can be used; web, print, paid media, all media, in perpetuity] +- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual] +- **Geography:** [Worldwide, US-only, etc.] +- **Exclusivity:** [Exclusive to brand, or illustrator can include in portfolio? Most illustrators want portfolio rights even on exclusive work.] +- **Modification rights:** [Can the brand modify the illustration in-house, or does any change require returning to the illustrator?] +- **NFT / generative AI training:** [Explicitly state whether the illustrator can use the work to train AI, and whether the brand can.] + +--- + +## Process and milestones + +### Stages and approvals + +A typical illustration commission moves through these stages. Define what each milestone delivers and who approves. + +| Stage | What is delivered | Who approves | +|---|---|---| +| Brief approved | This document, signed | Brand lead | +| Sketches / thumbnails | 2-3 rough directions per illustration | Brand lead + creative director | +| Refined sketch | Single chosen direction, more detail | Brand lead + creative director | +| Color and style test | One illustration finalized as reference | Brand lead + creative director | +| Final illustrations | All deliverables, in all variants | Brand lead | +| Files handed over | Source + exports, organized | Brand lead | + +### Revision rounds + +- **Sketch round 1:** [What is in scope. Typically composition and concept. Major changes are easier here.] +- **Sketch round 2:** [Refinement only. Style and composition are locked.] +- **Final art rounds:** [Typically 1 round of small adjustments. Beyond this, usually billed separately.] +- **Beyond included rounds:** [Cost or process for additional rounds.] + +### Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Brief approved | | | +| Sketches delivered | | | +| Sketch sign-off | | | +| First finished illustration | | | +| Style sign-off | | | +| Remaining illustrations delivered | | | +| Final files handed over | | | + +--- + +## Budget breakdown + +| Item | Cost | Notes | +|---|---|---| +| Illustrator fee (base) | | | +| Per-illustration rate | | | +| Style test / first finish | | | +| Revisions beyond included rounds | | | +| Rush fees (if applicable) | | | +| License fees (if separate from base) | | | +| Source file delivery (if separate) | | | +| **Total** | | | + +--- + +## Approval process + +### Who approves at each stage + +- **Brief:** [Name] +- **Sketches:** [Names] +- **Style test:** [Names] +- **Final illustrations:** [Name] +- **Final delivery:** [Name] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Illustrator credit: [Required / optional / no credit. Typical: credit required where editorial use, optional where commercial.] +- Promotion: [Illustrator can / cannot promote on their own portfolio. Typical: yes after the work is publicly launched.] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/skills/art-direction/references/photo-shoot-brief.md b/skills/art-direction/references/photo-shoot-brief.md new file mode 100644 index 0000000..c3efba1 --- /dev/null +++ b/skills/art-direction/references/photo-shoot-brief.md @@ -0,0 +1,255 @@ +# Photo Shoot Brief + +A complete brief for commissioning a photo shoot. Use as a starting template, fill out fully before sending to the photographer. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a reshoot. + +--- + +## Project overview + +**Project name:** [Working title] +**Date of brief:** [YYYY-MM-DD] +**Shoot date(s):** [Target dates] +**Location(s):** [Specific or "TBD - photographer recommends"] +**Photographer / studio:** [If selected] +**Producer / point of contact:** [Name and contact] +**Budget:** [Total or range] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is this shoot fundamentally about?] + +### Audience +[Who will see these images. Be specific. Their context, their state of mind.] + +### Goal +[What do these images accomplish? Brand awareness? Conversion? Emotional connection? Editorial illustration?] + +### Brand role +[How does the brand show up? Subtle (it's about the people), prominent (the product is the hero), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Confident," "intimate," "celebratory," "considered," "energetic."] + +--- + +## The look + +### Visual references + +[5 to 10 reference images. Source: photographers' portfolios, ad campaigns, editorial work. AVOID: direct competitor imagery.] + +For each reference, note WHAT to take from it: +- "From this image: the soft natural light" +- "From this image: the close composition on hands" +- "From this image: the muted color palette" + +NOT just dumping references with no commentary. + +### What to AVOID + +- [Specific visual cliche to avoid, e.g., "Stock-photo-style smiling at camera"] +- [Specific visual cliche to avoid] +- [Visual treatment that's been overused in the category] + +### Lighting + +- [Natural / studio / mixed] +- [Soft and diffused / dramatic and directional / high-contrast / low-contrast] +- [Time of day if natural] + +### Color + +- [True color / treated / monochrome / desaturated] +- [Specific color palette or mood, with hex codes if matching brand] + +### Composition + +- [Tight crops vs. wide environments] +- [Symmetrical vs. asymmetrical] +- [Subject placement preferences] +- [Portrait vs. landscape orientation defaults] + +### Wardrobe and styling + +- [Casual / formal / specific style direction] +- [Color preferences for wardrobe] +- [Things to avoid (logos other than ours, distracting patterns, etc.)] + +### Subjects / talent + +- [Demographics and casting direction] +- [Specific talent if cast, or open call criteria] +- [Diversity considerations] +- [Number of subjects per shot] + +### Props and set + +- [Required props] +- [Set direction (clean, lived-in, organized, chaotic, etc.)] +- [Branded elements (yes / no / minimal)] + +--- + +## Shot list + +A specific list of shots needed. Each entry is a shot the photographer must deliver. + +### Required shots (must-have) + +1. **[Shot name]** + - Description: [What's in the frame] + - Composition: [Tight, wide, environmental] + - Use case: [Where this image will be used, e.g., "homepage hero, 16:9"] + - Quantity: [How many variations] + +2. **[Shot name]** + - Description: + - Composition: + - Use case: + - Quantity: + +[Continue for all required shots] + +### Optional shots (if time and budget allow) + +1. **[Shot name]** +2. **[Shot name]** + +### Variants per shot + +Most shots need to work in multiple aspect ratios. Specify: + +- **16:9 (wide):** for web hero, video thumbnails +- **4:5 (vertical):** for social, mobile hero +- **1:1 (square):** for Instagram, app icons, avatars +- **9:16 (vertical extreme):** for Stories, vertical video + +When briefing, note which aspect ratios each shot must support. Photographer composes accordingly (loose enough to crop multiple ways, OR shoots specifically for each crop). + +--- + +## Technical specs + +### Resolution and format + +- **Minimum resolution:** [e.g., 6000x4000] +- **File format:** [RAW + edited high-res JPG / TIFF] +- **Color profile:** [sRGB / Adobe RGB] +- **Color space:** [Web vs. print] + +### Editing + +- **Editing scope:** [Color correction only / full retouch / specific retouch needs] +- **Editing reference:** [Examples of approved final-look] + +### Delivery + +- **Format:** [Cloud delivery, file sharing, hard drive] +- **Naming convention:** [e.g., "ProjectName_ShotN_VariantX.jpg"] +- **Asset management:** [Where the files live after delivery] + +### Licensing + +- **Usage:** [Where the images can be used; web, print, paid media, all media, in perpetuity] +- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual] +- **Geography:** [Worldwide, US-only, etc.] +- **Exclusivity:** [Exclusive to brand, or photographer can include in portfolio?] + +--- + +## Logistics + +### Timeline + +| Milestone | Date | Owner | +|---|---|---| +| Brief approved | | | +| Treatment / mood board sign-off | | | +| Casting / location finalized | | | +| Shoot day(s) | | | +| Selects delivered | | | +| Final edits delivered | | | + +### Budget breakdown + +| Item | Cost | Notes | +|---|---|---| +| Photographer fee | | | +| Talent | | | +| Wardrobe / styling | | | +| Hair / makeup | | | +| Location fee | | | +| Set / props | | | +| Equipment | | | +| Editing / retouching | | | +| Production / coordination | | | +| Contingency (10%) | | | +| **Total** | | | + +### Crew + +- Photographer: [Name] +- Photo assistant: [Name] +- Producer: [Name] +- Stylist: [Name] +- Hair / makeup: [Name] +- Talent: [Names] +- Brand reps on set: [Names] + +### Logistics day-of + +- Call time: [Time] +- Wrap time (target): [Time] +- Catering / craft services: [Plan] +- Wet weather plan: [If outdoor] +- Day-of contact list: [Names and numbers] + +--- + +## Approval process + +### Who approves at each stage + +- **Brief:** [Name] +- **Treatment / mood board:** [Names] +- **Day-of selects:** [Names on set or remote review] +- **Edited final selects:** [Name] +- **Final delivery:** [Name] + +### Revision rounds + +- **Edits round 1:** [What's in scope] +- **Edits round 2:** [What's in scope] +- **Beyond round 2:** [Cost or process for additional rounds] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Photographer credit: [Required / optional / no credit] +- Promotion: [Photographer can / cannot promote on their own portfolio] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/skills/backup-and-disaster-recovery/SKILL.md b/skills/backup-and-disaster-recovery/SKILL.md new file mode 100644 index 0000000..3a5c787 --- /dev/null +++ b/skills/backup-and-disaster-recovery/SKILL.md @@ -0,0 +1,268 @@ +--- +name: backup-and-disaster-recovery +description: "Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability." +category: operations +catalog_summary: "RPO/RTO targets, backup strategy, restoration drills" +display_order: 6 +--- + +# Backup and Disaster Recovery + +Plan for the worst case: the database is gone, the host is down for a week, the deploy was poisoned, ransomware encrypted everything. The skill is in advance preparation, not reaction. + +--- + +## When to use + +- Setting up backups for a new system +- Reviewing and validating backup architecture +- Defining RPO (recovery point objective) and RTO (recovery time objective) +- Running a disaster recovery drill +- Diagnosing gaps after an incident +- Planning for ransomware, data corruption, or insider threats +- Migrating to a new platform (DR planning belongs in the migration plan) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Routine deploy rollbacks (use `launch-runbook`) +- Code or content versioning (covered by Git, CMS revision history) +- Routine database snapshots (use this skill to set them up; routine review goes in monitoring) + +--- + +## Required inputs + +- The systems in scope (databases, file storage, code, configs, secrets) +- The hosting platforms and providers +- Existing backup tooling and what it covers +- Tolerance for data loss (in time) +- Tolerance for downtime (in time) +- Compliance requirements (some regulations mandate specific backup standards) + +--- + +## The framework: 4 questions + +Every disaster recovery plan answers four questions explicitly. + +### Question 1: What needs to be recoverable? + +List every system that holds state. Categorize by criticality. + +**Tier 1: must recover.** Without it, the business stops. (Customer database, transaction log, primary content store.) + +**Tier 2: should recover.** Loss is painful but not fatal. (Analytics, logs, secondary services.) + +**Tier 3: nice to recover.** Easy to rebuild. (Caches, derived data, temporary state.) + +The tier drives RPO, RTO, backup frequency, and storage spend. + +### Question 2: How much data loss is acceptable? (RPO) + +RPO is the maximum age of data that's acceptable to lose, measured in time. + +- RPO = 1 hour: hourly backups or continuous replication needed +- RPO = 1 day: daily backups acceptable +- RPO = 1 week: weekly backups acceptable + +For most production data, RPO of 1 hour or less is the target. For critical financial systems, near-zero RPO (continuous replication). + +For derived or rebuildable data, RPO of 1 day or longer is fine. + +### Question 3: How much downtime is acceptable? (RTO) + +RTO is the maximum time to restore service after a disaster. + +| RTO target | Implies | +|---|---| +| < 5 minutes | Hot standby with automatic failover | +| < 1 hour | Warm standby with manual failover or fast restore from recent snapshot | +| < 24 hours | Cold backup with documented restore process | +| Days to weeks | Best-effort, accept extended downtime | + +RTO drives architecture spend. Aggressive RTOs (< 1 hour) are expensive. Loose RTOs (days) are cheap. + +### Question 4: What's the disaster? + +Plan for specific scenarios. Each has different implications. + +**Hardware failure.** Disk dies. Standard backups solve this. Most modern hosts handle automatically. + +**Provider outage.** Region or vendor goes down. Cross-region or cross-provider redundancy needed for low RTO. + +**Data corruption.** Bad migration, bug, accidental delete. Point-in-time restore needed. The latest backup might be corrupted; you need history. + +**Ransomware or compromise.** Attacker encrypts or deletes. Backups must be immutable or air-gapped, otherwise the attacker takes them too. + +**Account compromise.** Attacker has admin credentials, deletes everything. Same defense as ransomware: immutable backups, separate access control. + +**Vendor lock-out.** Account suspended, billing dispute, vendor disappears. Backups outside the vendor needed. + +**Insider threat.** Disgruntled employee deletes or exfiltrates. Audit logs, separation of duties, immutable backups. + +A backup strategy that handles only hardware failure isn't a strategy. It's the easiest case. + +--- + +## Workflow + +### Step 1: Inventory state + +Every system that holds state goes on a list: + +| System | Data type | Tier | Current backup | Tested? | +|---|---|---|---|---| + +If you can't list it, you can't protect it. Often the inventory itself reveals gaps (the "we forgot about that database" moment). + +### Step 2: Set RPO and RTO per tier + +For each tier, agree on RPO and RTO. Get sign-off from the people who'd be impacted by a disaster. + +Push back on aspirational targets that aren't backed by infrastructure spend. RTO of 5 minutes for a system without a hot standby is not real. + +### Step 3: Verify or design backup architecture + +For each system, ensure: + +- **Frequency** matches RPO. +- **Retention** covers point-in-time recovery (typically 30+ days for production data). +- **Storage location** is separate from the source. Same disk, same account, same region: not enough. +- **Immutability or write-once storage** for at least some backup copies. Defends against ransomware. +- **Encryption at rest.** Standard for compliance. +- **Tested restore procedure.** Untested backups are not backups. + +The "3-2-1 rule" is a useful starting point: 3 copies of data, 2 different storage types, 1 offsite (or off-account, off-platform). + +### Step 4: Document the restore runbook + +For each system, write the runbook: + +1. How to detect the disaster (cross-reference monitoring) +2. How to decide to restore (decision criteria, who authorizes) +3. The exact restore steps (commands, screenshots, sequence) +4. How to verify the restore worked +5. How to switch traffic back +6. Communication template (status page, customer notice) + +The runbook is for the worst night of someone's career. Write it for tired, panicked you. + +### Step 5: Run a drill + +The first restore should never be during a real disaster. + +Drills can be: + +- **Tabletop:** walk through the runbook on paper. Useful for finding gaps in the plan. +- **Partial:** restore to a non-production environment. Verify the data, validate the steps. +- **Full:** simulate the disaster. Production failover or full restore. Maximum confidence, maximum risk. + +For most teams: quarterly tabletop, annual partial drill, full drill before major launches or after major architecture changes. + +### Step 6: Document drill results + +After each drill, document: +- What was tested +- What worked +- What broke +- What the actual RPO and RTO were (vs. targets) +- Action items + +If the actual RTO was 6 hours when the target was 1 hour, the target is fiction. Either fix the gap or revise the target. + +### Step 7: Schedule the next drill + +Calendar it. Assign an owner. Backups that aren't drilled drift toward useless. + +--- + +## Special topics + +### Database point-in-time recovery + +Many managed databases offer point-in-time recovery (PITR) within a retention window (often 7-35 days). This typically achieves RPO of seconds to minutes. + +For longer retention, schedule periodic exports to immutable storage. + +PITR alone isn't enough. If the database service itself is compromised, PITR is gone too. Always have at least one backup outside the source service. + +### File storage backups + +Object stores (S3, GCS, Azure Blob) usually offer: + +- Versioning (recover overwritten objects) +- Replication (cross-region) +- Object lock or immutability (defense against deletion) + +Set all three for production-critical buckets. Don't rely on the storage provider's default retention. + +### Code and config backups + +Code lives in Git. The Git host (GitHub, GitLab, etc.) is your backup, but a single host is a single point of failure. + +For high-criticality code: +- Mirror to a second host or your own server +- Periodic offline exports + +Configs and secrets need separate handling: +- Infrastructure-as-code: in Git, mirrored +- Runtime configs: backed up alongside the system +- Secrets: in a secret manager with its own backup story + +### Backups of backups + +The backup system itself can fail. Backup metadata, backup credentials, encryption keys: all must be backed up. + +If your backup is encrypted with a key you've lost, the backup is useless. + +### Compliance backups + +Some regulations require specific retention (e.g., 7 years for financial data). Comply with the highest applicable standard. + +Don't conflate compliance retention with operational backup. Compliance often allows much slower restore (just need to be able to produce the data eventually). + +--- + +## Failure patterns + +**Untested backups.** The single most common failure. Backups appear to work; restore fails. Test. + +**Backups in the same account or region as the source.** Account compromise or region outage takes both. + +**No immutability.** Ransomware encrypts the backups too. Use object lock or air-gapped storage. + +**RTO and RPO that aren't measured.** Target says "1 hour" but no one has verified the actual RTO. Assume the actual is longer than the target until proven otherwise. + +**Restore runbook only in someone's head.** Person leaves or is unavailable; runbook is gone. Document. + +**Backups but no DR plan.** "We have backups" isn't a plan. The plan is the runbook plus the architecture plus the drilling. + +**Optimism bias.** "It won't happen to us." It happens. Plan as if it will. + +**Backups too old or too new.** Want point-in-time history (in case corruption isn't immediately discovered). Daily snapshots with 30+ day retention. Or continuous replication with separate periodic snapshots for history. + +**Skipping drills "because we're busy."** Then you'll be busier during the disaster. + +**No communication plan.** Restoring data is half the job. Telling customers, stakeholders, and internal teams what's happening is the other half. + +--- + +## Output format + +A DR plan document includes: + +- **Inventory:** every stateful system +- **Tiering:** criticality per system +- **Targets:** RPO and RTO per tier +- **Architecture:** backup tooling, frequency, storage, immutability +- **Runbooks:** restore procedures per system +- **Drill schedule:** what gets tested when +- **Drill log:** results of past drills +- **Communication templates:** what to say during a real DR event + +--- + +## Reference files + +- [`references/restore-runbook-template.md`](references/restore-runbook-template.md): Fillable template for a restore runbook, covering detection, authorization, steps, verification, and rollback. diff --git a/skills/backup-and-disaster-recovery/references/restore-runbook-template.md b/skills/backup-and-disaster-recovery/references/restore-runbook-template.md new file mode 100644 index 0000000..6adf708 --- /dev/null +++ b/skills/backup-and-disaster-recovery/references/restore-runbook-template.md @@ -0,0 +1,231 @@ +# Restore Runbook Template + +Fill out one of these per system that needs to be restorable. The runbook is read by a tired, panicked person at 3am. Optimize for that reader. + +--- + +## System: [System name] + +**Owner team:** [Team name] +**On-call escalation:** [Who, how to reach] +**Last drill:** [YYYY-MM-DD] +**Last verified working:** [YYYY-MM-DD] + +--- + +## Tier and targets + +| | Target | Last measured | +|---|---|---| +| Tier | [1 / 2 / 3] | | +| RPO | [Time] | [Time] | +| RTO | [Time] | [Time] | + +If the last measured RTO is longer than the target, the target needs revision or the architecture needs investment. + +--- + +## What this system does + +[2-3 sentences describing what the system is and why it matters. The reader may not be familiar with this system in a panic.] + +--- + +## What "lost" looks like + +The triggers for using this runbook: + +- [ ] [Specific symptom, e.g., "Database returns errors on all queries"] +- [ ] [Specific symptom, e.g., "Data has been deleted or appears corrupted"] +- [ ] [Specific symptom, e.g., "Provider region is down per their status page"] +- [ ] [Specific symptom, e.g., "Account access is locked or suspended"] + +If none of these match, this might not be the right runbook. Pause and check `incident-response`. + +--- + +## Decision: should we restore? + +Restoring is destructive. Don't do it without authorization. + +**Authorize restoration if:** +- [Condition 1] +- [Condition 2] +- [Condition 3] + +**Do NOT restore if:** +- The system is recoverable through less destructive means (failover, replica promotion, partial fix) +- The data loss is recoverable through other channels (event replay, cache rebuild) +- We're not yet sure of the cause (restoring on top of an unknown cause can make things worse) + +**Authorization required from:** [Role] +**Backup authorization from:** [Role] + +Document the authorization in the incident channel before proceeding. + +--- + +## Pre-restore checklist + +- [ ] Authorization received and documented +- [ ] Communication sent: status page updated, internal notice posted +- [ ] Recent backup identified and validated +- [ ] Backup integrity verified (checksum, sample query, etc.) +- [ ] Target environment prepared (downtime accepted, traffic redirected) +- [ ] Rollback plan understood +- [ ] Timer started (track actual RTO) + +--- + +## Restore procedure + +### Step 1: Identify the backup to restore from + +[Specific instructions: which backup system, how to find the right one, how to verify it's the right one.] + +``` +[Example commands] +``` + +### Step 2: Prepare the target + +[Specific instructions: which environment, how to ensure no traffic, how to clear or prepare destination.] + +``` +[Example commands] +``` + +### Step 3: Run the restore + +[Specific instructions: the actual restore command(s), expected duration, what success looks like.] + +``` +[Example commands] +``` + +Expected duration: [Time] + +### Step 4: Verify + +[Specific instructions: how to know the restore worked. Sample queries, row counts, data spot-checks.] + +``` +[Example commands and queries] +``` + +Expected results: [What to look for] + +### Step 5: Re-enable traffic + +[Specific instructions: how to direct traffic back to the restored system.] + +``` +[Example commands] +``` + +### Step 6: Monitor + +For [time period] after the restore: + +- [ ] Watch error rates (link to dashboard) +- [ ] Watch latency (link to dashboard) +- [ ] Spot-check user-visible behavior +- [ ] Confirm no further data anomalies + +--- + +## Rollback + +If the restore makes things worse: + +[Specific instructions for reverting. This is rarely possible for data restores, but for failover-style restores, rollback is just the failover in reverse.] + +--- + +## Post-restore + +### Communication + +- [ ] Status page updated (resolved) +- [ ] Internal notice updated (system restored) +- [ ] Customer comms (if appropriate, who and what) +- [ ] Stakeholder summary + +### Documentation + +- [ ] Actual RTO recorded +- [ ] Actual RPO measured (latest data point preserved vs latest data point lost) +- [ ] Notes on any deviations from the runbook +- [ ] Items to fix in the runbook + +### After-action + +Schedule the after-action report within 5 business days. See `after-action-report` skill for the framework. + +--- + +## Backup details + +### Backup architecture + +| | Detail | +|---|---| +| Backup tool | [Tool name] | +| Frequency | [Cadence] | +| Retention | [Period] | +| Storage location | [Where, including account/region] | +| Immutable? | [Yes / No, details] | +| Encryption | [Method, key location] | + +### How backups are tested + +- [ ] [Test method 1] +- [ ] [Test method 2] +- [ ] [Test method 3] + +Last test: [YYYY-MM-DD] +Test cadence: [How often] + +--- + +## Dependencies + +This system depends on: +- [Dependency 1, what it provides] +- [Dependency 2, what it provides] + +If a dependency is also down, the restore may need to wait or proceed with workarounds. Document the workarounds: + +- [Dependency unavailable scenario 1]: [Workaround] +- [Dependency unavailable scenario 2]: [Workaround] + +--- + +## Drill log + +| Date | Type (tabletop / partial / full) | Outcome | Issues found | Fixes | +|---|---|---|---|---| +| YYYY-MM-DD | [Type] | [Pass / Partial / Fail] | [Issues] | [Fixes applied] | + +--- + +## Maintenance + +This runbook needs review: +- After every restore (real or drill) +- When the system architecture changes +- When backup tooling changes +- At least quarterly + +Last review: [YYYY-MM-DD] by [Name] +Next review: [YYYY-MM-DD] + +--- + +## Common gotchas + +[List of things that have surprised people during past restores or drills. Specific to this system.] + +- [Gotcha 1] +- [Gotcha 2] +- [Gotcha 3] diff --git a/skills/beta-program-management/SKILL.md b/skills/beta-program-management/SKILL.md new file mode 100644 index 0000000..30362a4 --- /dev/null +++ b/skills/beta-program-management/SKILL.md @@ -0,0 +1,312 @@ +--- +name: beta-program-management +description: "Running closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time." +category: product +catalog_summary: "Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops)" +display_order: 13 +--- + +# Beta Program Management + +A senior product leader's playbook for running betas that produce real signal. Closed and open betas, alpha programs, design partner programs, early access. Participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). + +Most betas underperform. Teams ship a beta because they think they should run a beta; participants are recruited loosely or open-flooded; feedback is collected ad-hoc through whatever channels exist; the decision to graduate to GA happens on calendar rather than on signal. The beta produced activity but not learning; the team launches with the same uncertainty they had before the beta. + +This skill is the discipline that turns betas into decision input. Calibrated cohorts who match the post-launch user profile. Structured feedback that captures what the team needs to know. Mid-beta triage that uses what is being learned. Graduation criteria that distinguish "ready" from "we are tired of running the beta." The discipline is not bureaucratic; it is the difference between a beta that informs the GA launch and a beta that produces noise. + +The voice is the senior product leader who has run betas with real signal and watched plenty of betas produce nothing. Concrete, opinionated about what produces signal, willing to call out where beta programs slide into ceremony. + +When to use this skill: planning a beta for an upcoming launch, auditing why prior betas have not produced actionable signal, designing the beta participant experience, or deciding whether a feature is ready to graduate from beta to GA. + +--- + +## What this skill is for + +This skill spans beta program design and execution. The PM and engineering distinction: + +- `feature-flagging` is rollout mechanics; the technical layer for controlling who gets which features. +- **`beta-program-management` (this skill)** is participant management and feedback discipline; the human layer. +- `feature-launch-playbook` is the full launch (post-GA); this skill is what happens BEFORE GA. +- `experiment-design` is rigorous A/B testing; betas are softer, qualitative-leaning, smaller-N. +- `user-feedback-aggregation` is ongoing feedback streams; beta feedback is bounded to the beta period. +- `discovery-research-synthesis` is one-off discovery research; betas are validation-stage rather than discovery-stage. + +The audience: senior PMs, product directors, engineering leads coordinating with product, customer success and support running beta cohorts, anyone planning a closed or open beta. + +What is not in scope: the broader feature launch (covered by `feature-launch-playbook`); the technical rollout mechanics (covered by `feature-flagging`); the rigorous experimentation methodology (covered by `experiment-design`); the discovery-stage research that informs whether to build the feature in the first place. + +--- + +## Soft-launch vs kitchen-sink vs structured-beta + +The keystone framing. + +**Soft-launch.** "We will just turn it on for some users." No structured participant selection, no defined feedback collection, no graduation criteria. The beta runs because the team wanted to ship the feature without the full launch ceremony. Output: the feature is in production for some users; the team has no organized way to learn from their experience; signal accumulates through whatever channels happen to surface it; mid-beta course-correction does not happen because there is no structure to surface what should be corrected. + +**Kitchen-sink.** Everyone gets in. The beta opens to whoever signs up. 5,000 beta users; 50 useful pieces of feedback; 4,950 silent users who provide no signal. Volume drowns signal. The team cannot tell which users matched the target post-launch profile. Feedback channels overflow; useful patterns get lost in noise; mid-beta triage cannot keep up. Output: a sense of "we ran a big beta" without the actionable feedback that smaller calibrated cohorts produce. + +**Structured-beta.** Calibrated cohort selected by participant criteria. Intentional feedback loops the cohort knows to use. Clear graduation criteria that distinguish "ready for GA" from "tired of the beta." Mid-beta triage that uses what is being learned. Output: the beta produces decision-grade signal; the GA launch ships with confidence; problems that would have surfaced in production get caught and addressed in beta. + +The litmus test. After the beta concludes, ask: what specifically did we learn from this beta that changed the GA launch? If the team can name 3-7 specific lessons, the beta was structured. If the team can only generally say "the beta went well," the beta was soft-launch or kitchen-sink. + +--- + +## Beta type decisions + +Several axes of beta-type choice. The right combination depends on the launch context. + +**Closed vs open.** + +- Closed: invite-only. Participants are selected by criteria. Cohort is bounded. +- Open: anyone can join. Cohort is self-selecting. +- Closed produces calibrated signal; open produces volume signal that may not match the target user profile. + +**Alpha vs beta vs RC.** + +- Alpha: very early, internal or trusted-partner only, expectation of bugs. +- Beta: more polished, broader cohort, expectation of feedback rather than crash discovery. +- RC (release candidate): essentially launch-ready, last validation, expectation of production-grade quality. + +**Internal vs external.** + +- Internal: only employees use the feature. +- External: real customers use the feature. +- Internal betas catch only what employees would experience; external betas catch the full user-context complexity. + +**Time-bounded vs open-ended.** + +- Time-bounded: 4-week beta, 8-week beta, with a defined end. +- Open-ended: beta runs until the team decides to graduate. +- Time-bounded forces the graduation decision; open-ended risks beta-purgatory. + +The combination decision. A typical structured beta might be closed + beta + external + 6-week time-bounded. A design partner program might be closed + alpha + external + open-ended. An open early access might be open + beta + external + time-bounded. The combination should match the kind of signal the team needs. + +Detail in [`references/beta-type-decisions.md`](references/beta-type-decisions.md). + +--- + +## Participant selection criteria + +The discipline that makes calibrated cohorts possible. + +**The criteria that work.** + +- **Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. The beta participant profile should resemble the target GA audience. +- **Variety across relevant dimensions.** Not all participants identical. If the feature has segment-specific behavior, the cohort spans segments. If usage volume varies, the cohort includes high-volume and low-volume users. +- **Feedback willingness.** Participants who agree to provide feedback through the structured channels. Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- **Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively. Customers in churn-risk are less likely to engage; their feedback may also be less representative. + +**The criteria that fail.** + +- **Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers; their feedback may not represent the broader target user. +- **Highest-paying customers only.** Skews toward enterprise patterns that may not generalize; misses smaller-team use cases. +- **Internal employees only.** Misses the customer-context complexity; signals "we tested" without "real users tested." + +**The cohort size question.** Calibrated cohorts are usually 20-200 participants for closed external betas. Smaller (5-20) for design partner programs. Larger (200-2,000) for open early access. Beyond 2,000 the program is a soft-launch with beta branding. + +Detail in [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md). + +--- + +## Beta cohort sizing + +How big is enough; when does signal saturate. + +**Saturation patterns.** + +- Critical feedback (bugs, crashes, broken flows) saturates quickly. 20-30 participants surface most critical issues in the first 2 weeks. +- Behavioral feedback (how users actually use the feature) saturates more slowly. 50-100 participants needed to see usage patterns clearly. +- Edge case feedback saturates slowly. 100+ participants needed; some edge cases never surface in beta. + +**Sizing decisions.** + +- For betas focused on bug discovery: 20-50 participants for 2-4 weeks. Beyond this, returns diminish. +- For betas focused on behavioral signal: 50-200 participants for 4-8 weeks. +- For betas focused on validating product-market fit assumptions: 100-500 participants over 8-12 weeks. +- For betas focused on at-scale infrastructure validation: 500-2,000 participants over 4-8 weeks. + +**The "beta size matches signal need" principle.** Cohort size follows from what the team needs to learn. Larger is not always better; calibrated is. + +Detail in [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md). + +--- + +## Onboarding beta participants + +How participants enter the beta and what they know going in. + +**The setup.** + +- Welcome communication that sets expectations: what the beta is, what feedback is expected, how long it runs, what happens at graduation. +- NDAs where relevant (for unannounced features, design partner programs). +- Feedback channel access: where participants give feedback, what format, what cadence. +- Support escalation path: who participants contact when things break. +- Compensation or incentive disclosure: free access to the feature post-GA, gift cards, swag, named recognition, etc. + +**The expectations contract.** + +- What the team commits to participants: communication cadence, response to feedback, transparent about graduation criteria. +- What participants commit to the team: feedback through the structured channels, not sharing externally during NDA, willingness to engage in interviews if requested. + +**Common onboarding failures.** + +- Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. +- No NDA where appropriate. Beta features get screenshotted on social before the team is ready. +- Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. +- No incentive clarity. Participants feel underrecognized; engagement decays. + +Detail in [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md). + +--- + +## Feedback collection patterns + +Structured channels that produce signal rather than noise. + +**Channels that work.** + +- **Structured surveys.** 5-15 question surveys at defined points (week 1, week 4, end of beta). Specific questions tied to the team's learning goals. +- **Async feedback forms.** Participants submit specific feedback through a defined form. Fields prompt for use case, severity, expected vs actual behavior. +- **Structured interviews.** 30-60 minute interviews with a subset of participants (5-15 per beta). Focused on usage patterns, decision moments, and qualitative depth. +- **In-product feedback widgets.** Contextualized to the moment. The feedback is timestamped to the user's actual experience. +- **Support tickets routed to beta-aware support.** Beta participants get faster, more contextualized support; the support interactions surface usage friction. + +**Channels that fail.** + +- **Slack channels for venting.** Beta participants vent in real time; signal mixes with noise; nobody synthesizes. +- **"Reply to this email with feedback."** Returns long unstructured emails; synthesis is hard; useful patterns get lost. +- **"Tell us what you think in the survey at the end."** End-of-beta surveys catch only what participants remember; in-the-moment friction is forgotten. + +**Channel mix discipline.** Most structured betas use 3-5 channels. Each channel surfaces different kinds of signal. The team synthesizes across channels. + +Detail in [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md). + +--- + +## Mid-beta triage and iteration + +How the team responds to feedback during the beta. + +**The principle.** Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. + +**The triage cadence.** + +- Weekly: review feedback across all channels. Categorize: critical bug, friction issue, feature request, positive signal, edge case. +- Bi-weekly: surface patterns. What recurring feedback are we seeing? What signal is converging? +- As-needed: critical issues get same-day response. Bugs that prevent core flows are not allowed to sit. + +**The iteration discipline.** + +- Critical bugs fixed during the beta. Beta participants experience the fixes; the post-fix experience informs the GA decision. +- Friction issues prioritized for fixes during the beta where feasible; documented for the GA decision where not. +- Feature requests captured for post-GA roadmap; not added during the beta unless they are graduation-blocking. +- Positive signal validated; surfaces what works, informs marketing copy and onboarding for GA. + +**The communication discipline.** Participants are kept informed: "We received your feedback on X; we are addressing it in next week's beta update." Silence makes participants feel ignored; over-communication signals overhead. Calibrate. + +Detail in [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md). + +--- + +## Beta-to-GA decision criteria + +Graduation gates that distinguish "ready" from "tired of running the beta." + +**The criteria.** + +- **Critical bugs cleared.** No known crashes, data loss, or core-flow failures. +- **Friction issues addressed or accepted.** Friction the team will not address by GA is documented and accepted as known limitation. +- **Behavioral validation.** Beta participants are using the feature in the patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). +- **Performance under load.** The feature performs adequately at the scale GA will produce. (For infrastructure betas, this is the central criterion.) +- **Documentation and support readiness.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work. +- **Positive signal sufficient.** Feedback is net-positive enough to launch with confidence. Not all participants delighted, but a substantial majority finding value. + +**The "we are tired of running the beta" anti-pattern.** Beta has run long enough that the team wants to graduate regardless of signal. The graduation decision happens on calendar rather than on criteria. Resist this; either the criteria are met (graduate) or they are not (extend or reset). + +**The "perpetual beta" anti-pattern.** Beta runs indefinitely because no firm graduation criteria were set. The team avoids the GA commitment by keeping the feature in beta. Force the graduation decision; if the feature is not ready for GA, identify what would make it ready or reconsider whether to ship at all. + +Detail in [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md). + +--- + +## Beta wind-down and participant communication + +How the beta ends. + +**The graduation announcement.** Participants are told the feature is graduating. Specific date. What changes for them: continued access (typically yes), pricing changes (often beta participants get free access for some period), feature stability commitments (the GA version is what they will use going forward). + +**The transition.** + +- For most participants: nothing changes operationally. The feature stays available; the "beta" label drops. +- Pricing transitions communicated explicitly if applicable. +- Beta-only features that did not make GA are flagged. Participants who relied on those features are given alternatives or transition timelines. + +**The thank-you.** Beta participants invested time providing feedback. Recognition matters: named in changelog (with consent), gift cards or swag, advance access to future betas. The recognition strengthens future-beta recruitment. + +**The postmortem.** Internal review of what the beta produced. What was learned, what changed in the GA launch, what would be done differently in future betas. This feeds the team's beta program practice. + +Detail in [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-beta-failures.md`](references/common-beta-failures.md). + +- "Our beta produced no signal." Soft-launch pattern; no structured selection or feedback collection. +- "Our beta has 5,000 users and we cannot synthesize feedback." Kitchen-sink; cohort too large for the structured signal the team needs. +- "Our beta participants never gave feedback." Onboarding contract was unclear or feedback channels were friction-laden. +- "We graduated to GA on schedule but launched with critical bugs." Graduation criteria not enforced; calendar-driven graduation. +- "Our beta has been running for 8 months with no graduation." Perpetual beta; no firm graduation criteria; graduation decision avoided. +- "Beta participants vented on Twitter before the launch." NDA missing or unclear; trust violation early erodes participant willingness. +- "The beta surfaced patterns we did not act on." Mid-beta triage missing; feedback collected but not used during the beta. +- "The GA launch surprised us." Beta was not actually validating the GA experience; cohort or feedback structure was wrong. +- "Beta participants felt ignored after providing feedback." Communication discipline missing; participants commit time and want to know it mattered. +- "We ran a closed beta that was effectively employees only." Internal-only beta; missed customer-context complexity. + +--- + +## The framework: 12 considerations for beta program management + +When designing or auditing a beta program, walk these 12 considerations. + +1. **Structured-beta, not soft-launch or kitchen-sink.** Calibrated cohort, intentional feedback, clear graduation. +2. **Beta type matches signal need.** Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. +3. **Participants match the post-launch profile.** Match the user the GA serves. +4. **Cohort size calibrated to signal need.** Smaller for bugs; larger for behavioral signal. +5. **Onboarding contract clear.** Expectations on both sides documented. +6. **Feedback channels structured.** 3-5 channels; signal not noise. +7. **Mid-beta triage active.** Feedback acted on during the beta. +8. **Communication keeps participants engaged.** Updates on what was heard and what is changing. +9. **Graduation criteria explicit.** Critical bugs cleared, friction addressed, behavioral validation, performance under load, support readiness, positive signal. +10. **Wind-down treats participants well.** Transition clarity, recognition, thank-you. +11. **Postmortem feeds practice.** Each beta improves the next. +12. **Honest decisions on graduation.** Either criteria met (graduate) or not (extend or reconsider). No tired-of-the-beta graduation. + +The output of the framework is a beta program that produces decision-grade signal, supports the GA launch, and treats participants well enough to recruit them for future betas. + +--- + +## Reference files + +- [`references/beta-type-decisions.md`](references/beta-type-decisions.md) - Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. +- [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md) - Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. +- [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md) - Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. +- [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md) - Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. +- [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md) - Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. +- [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md) - Triage cadence. Iteration discipline (what to fix during, what to defer). Communication with participants. +- [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md) - The six graduation criteria. The "tired of the beta" anti-pattern. Perpetual beta anti-pattern. +- [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md) - Graduation announcement, transition, recognition, postmortem. Treating participants well. +- [`references/common-beta-failures.md`](references/common-beta-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: betas earn their keep with structure + +A structured beta is one of the most useful product activities available. The cohort experiences the feature; the team learns from their experience; the GA launch ships with reduced uncertainty. The discipline pays back many times its cost. + +A soft-launch or kitchen-sink beta is one of the least useful. The team spends weeks running an activity that produces ambient activity without converting to learning. The GA launches with the same uncertainty the beta was supposed to address. + +The teams that earn returns on betas are the ones that take the structure seriously: cohorts calibrated to the GA profile, feedback channels designed for signal, mid-beta triage that uses what is being learned, graduation criteria that distinguish ready from tired, wind-down communication that treats participants well enough to recruit them again. + +When in doubt about whether a beta is ready, ask: are participants matched to the GA user, are feedback channels structured, is the team responding to feedback during the beta, are graduation criteria explicit and being applied honestly, will participants want to join the next beta? If yes to all of those, the beta is real. If no to any, the gap is where the beta will fail to convert participation into learning. diff --git a/skills/beta-program-management/references/beta-onboarding-templates.md b/skills/beta-program-management/references/beta-onboarding-templates.md new file mode 100644 index 0000000..a691d40 --- /dev/null +++ b/skills/beta-program-management/references/beta-onboarding-templates.md @@ -0,0 +1,230 @@ +# Beta onboarding templates + +Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. + +Onboarding sets the tone for the beta. Done well, participants enter with clear expectations and stay engaged through the program. Done badly, participants drop off, fail to provide feedback, or violate confidentiality unintentionally. + +--- + +## The welcome communication + +The first message participants receive after accepting the invitation. + +**What it covers.** + +- Welcome and thank-you for joining. +- What the beta is: the feature, the goals, what is being validated. +- Beta duration: start date, end date, what graduation looks like. +- What is expected of participants: feedback channels, cadence, format. +- What participants get: access to the feature, support, recognition or compensation, post-GA terms. +- NDA reminder where applicable. +- How to access the feature: links, accounts, configuration steps. +- Who to contact: support escalation path, beta program manager. +- First feedback prompt: what the team would like to hear about in the first week. + +**What it does not cover.** + +- A complete product manual. The participant should be able to use the feature; in-product guidance handles the detail. +- Internal team structure or politics. Participants do not need to know who reports to whom. +- Future roadmap. The beta is about this feature; future plans are separate communication. + +**Length.** 400-800 words for substantive features. Shorter for simpler features. The welcome should be readable in 3-5 minutes. + +**Tone.** Warm but professional. Beta participants are doing the team a favor; the welcome reflects that. Avoid corporate-stiff or overly casual. + +--- + +## The expectations contract + +Both sides commit to specific behaviors. + +**What the team commits to.** + +- Communication cadence: regular updates (weekly or bi-weekly). +- Response to feedback: critical issues addressed quickly; friction issues prioritized; feature requests captured. +- Transparency: participants are told what is being changed based on feedback and what is being deferred. +- Graduation criteria: explicit criteria, applied honestly. +- Post-GA continuity: participants know what their access looks like after graduation (typically continued access; sometimes special pricing). + +**What participants commit to.** + +- Feedback through the structured channels (specific channels named). +- Confidentiality where NDA applies (no public posts, screenshots, or sharing of beta features outside the participant's organization). +- Reasonable engagement: not required to use the feature daily, but expected to use it enough to provide informed feedback. +- Willingness to engage in interviews if requested (with the right to decline specific interviews). + +**The signed-or-implicit agreement.** + +- For substantial NDAs, participants sign an explicit agreement. +- For lighter beta agreements, the welcome communication may be the implicit acceptance (participation implies agreement to terms). +- The team should know which approach applies and apply it consistently. + +--- + +## NDA considerations + +When NDAs are appropriate. + +**NDA appropriate.** + +- Unannounced features (the beta is essentially confidential). +- Features that affect competitive positioning (the team does not want competitors to see the feature early). +- Design partner programs with deep collaboration on feature shaping. +- Enterprise features that touch sensitive customer data or workflows. + +**NDA not appropriate or unnecessary.** + +- Open public betas. +- Features that have already been announced. +- Features where the team welcomes public discussion (e.g., developer-tool launches that benefit from community feedback). + +**NDA enforcement reality.** + +- NDAs in open beta are essentially unenforceable. Pretending an open beta has NDA protection is theater. +- Closed-beta NDAs are enforceable but require trust; the team should not invite participants who are likely to violate confidentiality. +- For sensitive betas, the cohort selection itself is the primary control; NDAs are the legal backstop. + +**What an NDA covers.** + +- Confidentiality of the beta feature, its functionality, and the team's plans. +- Restrictions on screenshots, public posts, recordings. +- Term: typically until the feature is publicly announced or for a defined period. +- Exceptions: feedback to the team is allowed; discussion within the participant's organization is usually allowed. + +--- + +## Feedback channel access + +What participants need to know about how to give feedback. + +**Channel inventory.** + +- Structured surveys: when they will arrive, how long they take, how to access. +- Async feedback forms: link, instructions, what fields to fill. +- Interview signups: how to volunteer for interviews, what compensation if any. +- In-product feedback widget: how to use, what context it captures. +- Support routing: how beta participants flag issues to the support team. +- Slack or community: if a beta-only channel exists, how to join and what tone is expected. + +**Channel discipline.** + +- Each channel serves a different purpose. The welcome communication explains which channel is for which feedback type. +- Avoid duplicating channels (multiple Slack-like channels for the same feedback) or confusing channel mappings. + +--- + +## Support paths + +How participants escalate issues. + +**The escalation map.** + +- Bug reports: filed through the structured form or support ticketing system tagged "beta." +- Critical issues (crashes, data loss): escalation contact named explicitly; not buried in standard support queues. +- Feature questions and how-to: routed to in-product help or beta program manager. +- Account issues: standard support paths or beta-aware support reps. + +**Support team awareness.** + +- Support team should know the beta is running and how to handle beta-tagged tickets. +- Beta-tagged tickets often deserve faster response than standard tickets (the participant is doing the team a favor; long support waits damage the relationship). +- Common beta issues should be documented for the support team in advance. + +--- + +## Incentive disclosure + +What participants get for joining. + +**Common incentives.** + +- Free access to the feature post-GA for some period. +- Discounted pricing on the feature post-GA. +- Beta-only feature flags or capabilities preserved post-GA. +- Recognition (named in changelog, on website, in launch communications) with consent. +- Gift cards, swag, or other compensation. +- Direct access to product team during the beta (some participants value this most). + +**Disclosure discipline.** + +- The welcome communication names the incentives explicitly. No surprise reveals at the end. +- Different participants may have different incentive packages (design partners often get more); each participant knows their package. +- The incentives match the commitment level. Light betas have light incentives; design partner programs have substantive ones. + +**The "no incentive" pattern.** + +- Some betas offer no formal incentive beyond access to the feature. +- This works for high-engagement audiences (developers, enthusiasts) where access itself is the incentive. +- It does not work for audiences where the time investment is significant; participants need a reason to engage substantively. + +--- + +## First-week onboarding + +What happens after the welcome message. + +**The first week's actions.** + +- Day 1: welcome arrives; participants get access; first-day checklist (set up, access feature, complete profile if applicable). +- Day 2-3: first feedback prompt arrives. Could be an in-product widget triggered after first usage, or an email asking specifically about the first impression. +- End of week 1: brief check-in. Are participants able to access? Have they used the feature? Any friction with onboarding itself? + +**Onboarding-specific friction.** + +- Beta participants who cannot access the feature in the first 24-48 hours often disengage. Access friction is the most consequential onboarding failure. +- Documentation that does not match the actual experience (because the docs were written for a slightly different feature version) frustrates early. +- Missing context about what the feature is for. Participants who do not know what the feature is meant to accomplish use it tentatively or not at all. + +--- + +## Onboarding for different beta types + +Different beta types warrant different onboarding intensity. + +**Lightweight onboarding (open beta, RC validation).** + +- Email welcome with key information. +- Self-service access. +- In-product guidance handles most setup. + +**Standard onboarding (closed beta, structured cohort).** + +- More substantial welcome email. +- Optional onboarding call for participants who request it. +- Beta program manager available via direct channel. + +**Deep onboarding (design partner program, complex feature).** + +- Onboarding call with each participant or company. +- Custom configuration support. +- Direct channel to product team for ongoing collaboration. + +The onboarding intensity matches the beta type. Heavyweight onboarding for an open beta with 5,000 participants is impossible; lightweight onboarding for a 5-partner design program under-invests in the relationships. + +--- + +## Common onboarding failures + +**Vague expectations.** Participants do not know what feedback is wanted; ad-hoc venting fills the channels. + +**Missing NDA where appropriate.** Beta features get screenshotted on social before the team is ready. + +**Missing support path.** Participants hit issues, do not know who to contact, churn out of the beta. + +**No incentive clarity.** Participants feel underrecognized; engagement decays. + +**Welcome communication too long or too short.** Too long: participants do not read; too short: participants miss critical context. + +**Access friction in first 24-48 hours.** Participants cannot get into the feature; many disengage permanently. + +**Onboarding intensity mismatched to beta type.** Heavy onboarding for an open beta wastes effort; light onboarding for a design partner program under-invests. + +--- + +## Methodology-level choices that stay in the public skill + +The welcome communication structure. The expectations contract for both sides. NDA considerations. Feedback channel access. Support paths. Incentive disclosure. First-week onboarding. Onboarding by beta type. Common failures. + +## Implementation choices that stay internal + +Specific welcome email templates. Specific NDA boilerplate. Specific support routing automation. Specific incentive packages and approval workflows. The team's own conventions for onboarding intensity. These vary by team and beta type. diff --git a/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md b/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md new file mode 100644 index 0000000..e835ce5 --- /dev/null +++ b/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md @@ -0,0 +1,239 @@ +# Beta-to-GA graduation criteria + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. + +Graduation is the decision that distinguishes a structured beta from beta theater. Honest graduation criteria, applied honestly, separate "ready for GA" from "we are tired of running the beta." Defining the criteria explicitly upfront prevents calendar-driven graduation decisions later. + +--- + +## The six graduation criteria + +The criteria that should be met before graduating from beta to GA. + +### 1. Critical bugs cleared + +**The criterion.** No known crashes, data loss, or core-flow failures. + +**The validation.** Bug tracker shows no open critical issues. The beta cohort has not reported new critical issues in the past 1-2 weeks. + +**The exception.** Some critical issues may be acceptable if they affect a tiny segment that the GA can either exclude or address with documentation. Decisions to graduate with known issues should be explicit. + +### 2. Friction issues addressed or accepted + +**The criterion.** Friction issues are either fixed before GA or documented as known limitations the team is choosing not to address pre-GA. + +**The validation.** Each friction issue from the beta has a disposition: fixed, fix-in-progress (with timeline), accepted-for-now (with rationale), accepted-permanently (with rationale). + +**The honest disposition.** "Accepted for now" is honest if the team plans to address post-GA. "Accepted permanently" is honest if the team has decided the friction is not worth the engineering cost. Hidden friction that the team hopes nobody will notice is not honest. + +### 3. Behavioral validation + +**The criterion.** Beta participants are using the feature in patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). + +**The validation.** Usage data from the beta cohort shows the feature being used in the ways the design assumed. Significant deviations are investigated; either the design is adjusted, or the GA experience is modified to support the actual usage pattern. + +**The unexpected-pattern handling.** + +- Pattern A: most beta participants are using the feature in a different way than the design assumed. The design is wrong; iterate before GA. +- Pattern B: a subset of participants is using the feature in an unexpected way that suggests an additional use case. Capture for post-GA expansion; do not delay GA. +- Pattern C: participants are not using the feature much at all. The feature may not be solving a real problem; reconsider whether to ship. + +### 4. Performance under load + +**The criterion.** The feature performs adequately at the scale GA will produce. + +**The validation.** Performance testing under projected GA load. Beta cohort performance was acceptable; the GA scale projection has been tested. + +**The infrastructure-validation focus.** For features where scale is the primary concern (data-processing features, real-time features, multi-tenant features), this criterion is the central one. RC betas often exist primarily to validate this. + +### 5. Documentation and support readiness + +**The criterion.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work. + +**The validation.** + +- Help docs match the feature as it will ship at GA. +- Support team has been briefed and has handled at least the simulated beta-tier ticket volume. +- Common issues are documented for the support team's reference. +- Escalation paths from support to engineering are tested. + +**The skip risk.** Teams often graduate before docs and support are ready. The GA launch then catches the support team off-guard; tickets pile up; users have a worse experience than they would have with proper readiness. + +### 6. Positive signal sufficient + +**The criterion.** Beta feedback is net-positive enough to launch with confidence. + +**The validation.** + +- Survey signal shows positive sentiment among beta participants. +- Behavioral signal shows continued usage (participants are not just trying the feature once). +- Participants would recommend the feature to others. + +**The "sufficient" calibration.** Not all participants need to be delighted. A substantial majority finding value, with the dissenting voices understood (segment misfit, expectations mismatch, unfixable friction), is sufficient. A divided cohort with no clear majority signal is not. + +--- + +## The "tired of the beta" anti-pattern + +Graduation that happens because the team wants to be done with the beta. + +**The pattern.** + +- Beta has run for the planned duration. +- Some criteria are met; some are not. +- The team graduates anyway because "we have to ship at some point" or "the beta cannot run forever." + +**Why it fails.** + +- Unmet criteria mean the GA launches with known issues that are not yet addressed or acknowledged. +- Support, marketing, and customer success encounter problems the beta would have caught if extended. +- Trust degrades: customers experience friction the beta participants reported but the team did not fix. + +**The cure.** + +- Either extend the beta until criteria are met. +- Or graduate with explicit acknowledgment of the unmet criteria (known issues, deferred work). +- Or reset the beta if significant changes are needed. + +The discipline: the graduation decision is criteria-driven, not calendar-driven. Calendar pressure can inform whether to ship a smaller scope, but it should not produce graduation despite unmet criteria. + +--- + +## The perpetual beta anti-pattern + +Graduation that does not happen because the beta drifts indefinitely. + +**The pattern.** + +- Beta runs without firm graduation criteria. +- Issues keep surfacing; the team keeps fixing; the beta extends. +- 6 months later, the beta is still running. The "perpetual beta" branding becomes a strategic stance ("everything is always evolving"). +- The GA commitment is avoided. + +**Why it fails.** + +- Beta participants experience indefinite uncertainty about the feature's status. +- The team avoids the discipline of GA readiness; the feature stays in a less-mature state than it could be. +- Marketing, support, and customer success cannot operate around a beta-forever feature. +- Stakeholder trust degrades: the team is not shipping. + +**The cure.** + +- Force the graduation decision. Either the criteria are met (graduate) or they are not (decide what would make them met, set a timeline, commit). +- "Perpetual beta" as a strategic stance is rare and usually a rationalization. +- Some features genuinely need extended-beta status for valid reasons (regulatory complexity, unusual scale validation); these should be exceptions documented explicitly, not the default. + +--- + +## Honest graduation patterns + +When graduation criteria are mostly but not fully met. + +**Graduation with known issues.** + +- Some criteria fully met; one or two have known gaps. +- Graduate with explicit acknowledgment: "We are shipping with X known limitation; documented; will address in [timeline]." +- Communicate the known issues to support, marketing, customer success. +- Customers who hit the known issue are not surprised; they were warned. + +**Graduation with extended monitoring.** + +- Behavioral signal not fully validated due to cohort limitations. +- Graduate with monitoring infrastructure that surfaces issues at GA scale. +- Plan for fast iteration if monitoring catches issues post-GA. + +**Graduation with phased rollout.** + +- All criteria met for a subset of users; less certain for broader users. +- Graduate to the validated subset first; expand the rollout in phases. + +These patterns preserve graduation discipline while accommodating real-world constraints. + +--- + +## When NOT to graduate + +Conditions that warrant extending or resetting the beta. + +**Not to graduate.** + +- Critical bugs are unaddressed. +- Major friction issues affect mainline usage. +- Behavioral signal contradicts the design assumptions. +- Performance under projected load is inadequate. +- Documentation and support are not ready. +- Beta sentiment is divided without clear positive signal. + +**The honest extension.** + +- Acknowledge the gap explicitly. +- Define what would close the gap. +- Set a new timeline. +- Communicate to participants and stakeholders. + +**The reset.** + +- If the gap requires significant feature changes, end the current beta and start a new one with the changed feature. +- Do not blend "old beta" and "new feature" data. + +--- + +## Graduation decision-making + +Who decides graduation and how. + +**The decision-maker.** Typically the product manager who owns the feature, with input from engineering lead, design lead, and beta program manager. + +**The decision process.** + +- Beta program manager prepares a graduation review document: status against each criterion, known issues, recommendation. +- Decision meeting (60-90 minutes): review the document, discuss any open questions, make the decision. +- Decision recorded explicitly: graduate, extend, or reset. + +**Stakeholder visibility.** The decision is communicated to stakeholders (executives, marketing, sales, customer success) before participants are notified. + +**Graduation timing.** Once the decision is made, graduation typically takes 1-2 weeks to execute (final code, marketing prep, support readiness, participant communication). + +--- + +## Graduation criteria for different beta types + +The criteria adapt to the beta type. + +**Closed beta with calibrated cohort.** All six criteria apply. The cohort is small enough to validate behavioral signal directly. + +**Open beta with large volume.** Behavioral signal validates at scale. Critical bugs and performance criteria are more central. Documentation and support readiness scale with the open-beta visibility. + +**RC validation.** Performance under load is the central criterion. Other criteria should already have been met in prior alpha or beta stages. + +**Design partner program.** The criteria apply but graduation often happens incrementally (specific design partners moving to GA terms while the program continues with new partners). Less of a single graduation moment. + +**Internal beta.** Customer-context criteria (behavioral validation, support readiness for external) may need to be validated at GA rather than during beta. Honest disclosure: the beta did not fully validate the customer experience. + +--- + +## Common graduation failures + +**Calendar-driven graduation.** Graduate when the planned duration ends regardless of criteria. + +**Criteria not defined upfront.** Graduation decision happens without explicit criteria; subjective decision. + +**Hidden known issues.** Graduate with known issues that are not surfaced; customers and support discover them later. + +**Perpetual beta.** Indefinite extension; graduation decision avoided. + +**Premature graduation.** Graduate before behavioral signal has emerged or critical bugs are fully cleared. + +**No stakeholder notification.** Graduation happens; support, marketing, customer success encounter the GA launch unprepared. + +**No participant communication about graduation.** Beta participants are not told about graduation timing or what changes for them. + +--- + +## Methodology-level choices that stay in the public skill + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. Honest graduation patterns. When not to graduate. Graduation decision-making. Graduation criteria for different beta types. Common failures. + +## Implementation choices that stay internal + +Specific graduation review document templates. Specific decision-meeting formats. Specific stakeholder notification workflows. The team's own conventions for graduation timing. These vary by team and tooling. diff --git a/skills/beta-program-management/references/beta-type-decisions.md b/skills/beta-program-management/references/beta-type-decisions.md new file mode 100644 index 0000000..0995f48 --- /dev/null +++ b/skills/beta-program-management/references/beta-type-decisions.md @@ -0,0 +1,228 @@ +# Beta type decisions + +Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. + +Beta type is the upstream decision that constrains everything downstream: who participates, what feedback channels make sense, what graduation looks like. Getting the type wrong makes the rest of the program harder. + +--- + +## Closed vs open + +The cohort-control axis. + +**Closed beta.** Invite-only. Participants are selected by the team based on criteria. Cohort is bounded. + +**Strengths.** + +- Calibrated cohort: the team knows who is in the beta and can match participants to the GA user profile. +- Quality of feedback: invited participants typically engage more substantively than self-selected open-beta users. +- NDA enforceability: closed cohorts can sign NDAs; open cohorts usually cannot. +- Synthesis tractability: bounded cohort means feedback volume is manageable. + +**Weaknesses.** + +- Recruiting overhead: identifying and inviting participants is real work. +- Limited diversity: the cohort reflects the team's recruiting choices; gaps in selection produce gaps in feedback. +- Slower feedback volume: smaller cohorts produce less total feedback. + +**Open beta.** Anyone can join. Cohort is self-selecting. + +**Strengths.** + +- Volume: large numbers of participants quickly. +- No recruiting overhead: participants opt in. +- Marketing value: open betas can build pre-launch audience awareness. + +**Weaknesses.** + +- Self-selection bias: early adopters and enthusiasts skew the cohort; their feedback may not represent the broader target user. +- Signal-to-noise ratio: most participants do not provide actionable feedback; the team must mine signal from volume. +- NDA difficulty: open cohorts cannot reasonably enforce NDAs; the feature is essentially public. + +--- + +## Alpha vs beta vs RC + +The polish axis. + +**Alpha.** + +- Very early. Significant bugs expected. +- Internal users or trusted partners only. +- Goal: surface fundamental issues before broader exposure. +- Feedback orientation: bug discovery, fundamental flow validation. + +**Beta.** + +- More polished. Major bugs caught; remaining issues are friction or edge cases. +- Broader cohort. External customers in calibrated cohorts. +- Goal: validate the feature works for real users in real contexts. +- Feedback orientation: usage patterns, friction, behavioral signal, edge cases. + +**RC (release candidate).** + +- Essentially launch-ready. Production-grade quality expected. +- Cohort can be large (open beta or extended beta). +- Goal: last validation before GA, performance at scale, infrastructure readiness. +- Feedback orientation: scale issues, infrastructure issues, last-mile polish. + +**The progression.** Many features pass through all three (alpha → beta → RC) before GA. Some skip alpha (sufficient internal testing) or skip RC (the beta is the last validation). The decision depends on feature complexity and risk tolerance. + +--- + +## Internal vs external + +The audience axis. + +**Internal beta.** Only employees use the feature. + +**Strengths.** + +- Fast feedback: employees are easy to recruit and follow up with. +- High engagement: employees usually feel some ownership of company products. +- NDA simplicity: confidentiality is implicit. + +**Weaknesses.** + +- Missing customer context: employees experience features differently than customers (familiarity, infrastructure context, motivations). +- Bias toward team-known patterns: employees use products in ways the team designed for; customers often use products differently. +- Limited signal: internal-only cannot validate customer-context complexity. + +**External beta.** Real customers use the feature. + +**Strengths.** + +- Real customer experience: feedback reflects how customers actually use the product. +- Behavioral signal: usage patterns from real customers inform GA decisions. +- Trust building: customers who beta-test become advocates. + +**Weaknesses.** + +- Requires customer relationship: cannot just turn the feature on for employees. +- Recruiting overhead: identifying willing customers and managing the cohort. +- Risk: bugs reaching customers can damage trust if not handled well. + +**The combination.** Most strong betas pass through both: internal alpha, then external beta. Some skip internal (when internal use cases differ enough from customer use cases that internal validation is misleading). + +--- + +## Time-bounded vs open-ended + +The duration axis. + +**Time-bounded beta.** A defined end date. Common durations: 4 weeks, 6 weeks, 8 weeks, 12 weeks. + +**Strengths.** + +- Forces the graduation decision. The end date arrives; the team must decide ready or not. +- Clarity for participants: they know how long they are committing. +- Resource bounding: the team's beta-running effort is bounded. + +**Weaknesses.** + +- Calendar pressure can force premature graduation: "we are at the end date so we are graduating" regardless of signal. +- Some signals need longer to surface: behavioral patterns may not be visible in 4 weeks. + +**Open-ended beta.** No defined end. The beta runs until the team decides to graduate. + +**Strengths.** + +- Signal-driven graduation: the team graduates when the criteria are met, regardless of calendar. +- Allows long-running validation: behavioral signal can develop over months. +- Suits design partner programs: ongoing relationships rather than time-bounded cohorts. + +**Weaknesses.** + +- Beta-purgatory risk: beta runs indefinitely because nobody forces the graduation decision. +- Participant fatigue: open-ended commitments without clear duration drain engagement. +- Resource drain: the team's beta-running effort is open-ended. + +**The default.** Most betas should be time-bounded. Open-ended is appropriate for design partner programs and specific extended-validation scenarios. + +--- + +## The combination decision + +How to choose across the four axes. + +**Worked combinations.** + +**Standard structured beta:** closed + beta + external + time-bounded (6-8 weeks). + +- Use when: shipping a meaningful feature that needs validation before GA. Most common combination. + +**Alpha:** closed + alpha + internal + open-ended (typically 2-6 weeks of internal testing before external alpha). + +- Use when: very early feature; need to surface fundamental issues before exposing customers. + +**Design partner program:** closed + alpha or beta + external + open-ended. + +- Use when: building a feature with deep customer involvement; small set of partner customers (3-10) collaborating closely on shaping the feature. + +**Open early access:** open + beta or RC + external + time-bounded (4-12 weeks). + +- Use when: pre-GA marketing matters; the feature is sufficiently polished that early access can build audience; team can handle the volume. + +**RC validation:** open or closed + RC + external + time-bounded (2-4 weeks). + +- Use when: the feature is essentially launch-ready; need last validation at scale or in the production environment. + +**Internal-only RC:** closed + RC + internal + time-bounded. + +- Use when: the feature is for internal users (e.g., admin tools used by support team), or when external testing is impractical for the type of feature. + +--- + +## When the combination decision goes wrong + +Common mismatches. + +**Open + alpha.** Open cohorts on an alpha-stage feature exposes customers to bugs the team has not caught. Damages trust. Cure: alpha should be closed; open up at beta stage when the feature is more polished. + +**Closed + RC.** Closed RCs miss the at-scale validation that RCs are meant to provide. The cohort is too small to surface scale issues. Cure: RCs are usually open or large-closed. + +**External + alpha + open-ended.** External customers commit to an alpha that has no end date and many bugs. Engagement decays. Cure: alpha should be internal or trusted-partner only; external alpha should be time-bounded and limited. + +**Open + beta + open-ended.** Volume cohort with no end date. The beta runs forever; participants lose interest; the team cannot synthesize. Cure: time-bound the beta; force graduation decision. + +--- + +## Beta type for specific contexts + +Common contexts and the typical type combinations. + +**B2B SaaS feature launch.** Closed + beta + external + time-bounded. 20-200 participants from existing customer base, 6-8 weeks. + +**Consumer product launch.** Open + beta + external + time-bounded (or open + RC). 1,000-10,000+ participants, 4-8 weeks. Marketing value is part of the rationale. + +**Enterprise platform major release.** Closed + alpha + design-partner + open-ended initially, then closed + beta + extended cohort + time-bounded for validation. + +**Developer-tool launch.** Open + beta + external + time-bounded, with public roadmap and community feedback channels. + +**Internal tool launch.** Closed + alpha or beta + internal + time-bounded. The cohort is the internal users who will use the tool post-GA. + +**Compliance-impacting feature.** Closed + extended beta + external + carefully selected design partners. The validation needs to surface compliance edge cases before GA. + +--- + +## Common beta-type failures + +**Defaulting to soft-launch.** Skipping beta-type decisions and just turning the feature on for some users. Decide the type explicitly. + +**Defaulting to open beta for everything.** Open volume substituted for calibrated cohorts. Open is right for some contexts; not for all. + +**Mismatching alpha/beta/RC to feature polish.** Calling something "beta" when it is alpha (too many bugs); calling something "RC" when it is beta (not yet production-grade). + +**Internal-only when external context matters.** Validates an internal experience that does not match what customers will encounter. + +**Open-ended without graduation criteria.** Beta drifts into perpetual beta because no firm end was set. + +--- + +## Methodology-level choices that stay in the public skill + +The four axes (closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended). Strengths and weaknesses per axis. Worked combinations. Common mismatches. Beta type for specific contexts. Common failures. + +## Implementation choices that stay internal + +Specific platform feature-flagging configurations. Specific recruitment platforms and processes. Specific NDA templates. Specific time-bounding workflows. The team's own conventions for beta-type decisions in different contexts. These vary by team and tooling. diff --git a/skills/beta-program-management/references/beta-wind-down-communication.md b/skills/beta-program-management/references/beta-wind-down-communication.md new file mode 100644 index 0000000..8f77cc2 --- /dev/null +++ b/skills/beta-program-management/references/beta-wind-down-communication.md @@ -0,0 +1,231 @@ +# Beta wind-down communication + +Graduation announcement, transition, recognition, postmortem. Treating participants well. + +The beta's wind-down is its closing impression. Done well, participants leave the beta engaged and willing to participate in future betas. Done badly, participants feel discarded after providing significant feedback. + +--- + +## The graduation announcement + +Communication to participants when the beta graduates. + +**Timing.** 1-2 weeks before graduation, with confirmation at graduation. + +**Content.** + +- The feature is graduating to GA. Specific date. +- What changes for participants. +- What does not change. +- Recognition or thank-you for participation. +- Information about post-GA support, pricing, or special terms. +- Any beta-specific features or terms that will not carry to GA. + +**Tone.** Warm, appreciative. Participants invested time; the announcement reflects that. + +**Length.** 300-600 words. Long enough to cover the necessary information; short enough to be readable. + +--- + +## What changes for participants at graduation + +**Continued access.** Most beta participants retain access to the feature post-GA. The beta was their preview; GA continues their use. + +**Pricing transitions.** If the feature has paid tiers, participants need to know: + +- Does beta access include free use of the feature post-GA for some period? +- Does the feature require an upgraded plan for full access? +- Are there special pricing terms for beta participants (early-bird discount, lifetime grandfathering, etc.)? + +**Feature stability.** Communicate what level of stability participants should expect post-GA. Beta features sometimes have rough edges; GA implies stability commitments. + +**Support transition.** Beta-aware support routing typically ends at GA. Participants now use standard support channels. + +**Beta-only features.** Some features in the beta may not make GA (deprecated, simplified, removed). Participants who relied on those features need clear communication about alternatives. + +--- + +## Recognition + +Beta participants invested time providing feedback. Recognition matters. + +**Forms of recognition.** + +- **Named in changelog or launch communications** (with consent). +- **Gift cards or compensation** for substantial time investment. +- **Swag** for closed-beta participants. +- **Advance access to future betas.** +- **Direct thank-you from product team**, often via personal email. +- **Public acknowledgment** in marketing or community materials. + +**Calibration.** + +- Light betas: direct thank-you, possibly modest swag. +- Standard betas: thank-you, swag, post-GA continued access on favorable terms. +- Design partner programs: substantial recognition, sometimes including case studies, named partnerships, financial compensation. + +**The discipline.** Recognition matches the participant's investment. Light recognition for a heavy commitment feels dismissive; heavy recognition for a light commitment is unnecessary. + +--- + +## The post-beta survey + +A final feedback collection at graduation. + +**Purpose.** Capture overall reflections on the beta experience and the feature. + +**Content.** + +- Overall feature satisfaction. +- Likelihood to continue using post-GA. +- Likelihood to recommend. +- What worked well in the beta program (process feedback, not feature feedback). +- What could be improved in future betas. +- Optional open-ended reflections. + +**Length.** 5-10 questions, 5-10 minutes to complete. + +**Why it matters.** The post-beta survey closes the loop with participants and informs the team's beta-program practice. The process feedback is particularly valuable: future betas improve based on past feedback. + +--- + +## The beta postmortem + +Internal review of what the beta produced. + +**Timing.** Within 1-2 weeks of graduation. + +**Participants.** Beta program manager, product manager, engineering lead, design lead, customer success lead, support lead. + +**Content.** + +- What was learned from the beta? (Patterns, behavioral validation, friction discovery.) +- What changed in the GA launch as a result? +- What worked well in the beta program (process)? +- What did not work? What would the team do differently next time? +- What patterns recur across multiple betas? Are there lessons for the broader practice? + +**Output.** A short postmortem document. Surfaces lessons. Informs future betas. + +**Why it matters.** Beta programs improve through accumulated learning. Without postmortems, the team repeats the same mistakes; with postmortems, the practice gets sharper over time. + +--- + +## Recruiting for future betas + +The wind-down is a recruiting moment for future betas. + +**The pattern.** Participants who had a good beta experience are likely to participate in future ones. The wind-down communication can include an invitation: would they like to be considered for future betas? + +**The benefits.** + +- Builds a roster of engaged beta participants for future programs. +- Reduces recruiting overhead for future betas. +- Strengthens the participant relationship. + +**The discipline.** Do not over-commit; future betas should not be promised in ways that are not honored. The invitation is to be considered, not a guarantee. + +--- + +## Handling beta-only features that do not make GA + +Sometimes beta features include capabilities that are removed or simplified at GA. + +**Why it happens.** + +- The feature scope was reduced based on beta findings. +- Some capabilities did not perform well enough to ship at GA. +- The team learned the capability was not load-bearing. + +**The communication.** + +- Surface the change explicitly. Do not silently remove. +- Explain the reasoning where appropriate. +- Provide alternatives or workarounds for participants who relied on the removed capability. +- Acknowledge the impact on participants. + +**The participant impact.** Some participants may push back; their usage assumed the capability would persist. The team must decide whether to extend support, offer migration help, or accept the participant churn. + +--- + +## Special cases: extended beta + +Some betas extend beyond their planned duration. + +**Communication for extension.** + +- Tell participants when the extension is decided, not when the original end date passes. +- Explain why the extension is needed. +- Give a specific new end date. +- Acknowledge the participant impact (they committed to the original timeline). +- Provide an option to opt out if the extension is significant. + +**Avoid.** + +- Silent extensions where the planned end passes without acknowledgment. +- Multiple extensions that erode the timeline credibility. +- Extensions framed as "no big deal" when they affect participants' ongoing time investment. + +--- + +## Special cases: beta cancellation + +Sometimes the team decides not to graduate the feature to GA. + +**Why it happens.** + +- The beta revealed the feature does not work as intended. +- Strategic shift redirected resources. +- The feature would compete poorly at GA scale. + +**The communication.** + +- Be honest about the cancellation. +- Acknowledge the participants' time investment. +- Explain (at appropriate level of detail) why the cancellation. +- Discuss what happens to participants' beta data, configurations, etc. +- Recognize the participation despite the cancellation. + +**The participant impact.** Cancellation can frustrate participants who invested time. Honest communication and good recognition mitigate the impact. + +--- + +## Long-term participant relationships + +Beta participants represent ongoing relationships, not transactional interactions. + +**The relationship investment.** + +- Participants who had a good beta experience may become advocates, references, case study subjects. +- Future product strategy benefits from continued conversation with beta alumni. +- Customer success can use beta participation as relationship signal. + +**The maintenance.** Periodic check-ins with notable beta participants strengthen relationships even outside formal beta programs. Light-touch communication (annual newsletter, occasional product updates, personalized outreach for major launches) maintains the connection. + +--- + +## Common wind-down failures + +**Silent graduation.** Beta participants discover graduation through the public launch announcement rather than through advance communication. + +**Vague transition information.** Participants do not know what changes for them; uncertainty produces churn. + +**Insufficient recognition.** Heavy participation rewarded with thin thank-you; participants feel dismissed. + +**Missing post-beta survey.** Process feedback is lost; future betas do not improve. + +**No postmortem.** Internal lessons are lost; the team repeats mistakes. + +**Surprise feature removals.** Beta-only features removed without warning; participants discover at GA that capabilities they relied on are gone. + +**No invitation to future betas.** The relationship ends at graduation; future betas restart recruitment from scratch. + +--- + +## Methodology-level choices that stay in the public skill + +The graduation announcement structure. What changes for participants. Recognition forms and calibration. The post-beta survey. The beta postmortem. Recruiting for future betas. Handling beta-only feature removals. Extended betas. Beta cancellations. Long-term relationships. Common failures. + +## Implementation choices that stay internal + +Specific graduation announcement templates. Specific recognition packages and approval. Specific postmortem templates. Specific CRM tracking of beta alumni. The team's own conventions for relationship maintenance. These vary by team. diff --git a/skills/beta-program-management/references/cohort-sizing-patterns.md b/skills/beta-program-management/references/cohort-sizing-patterns.md new file mode 100644 index 0000000..1457a9e --- /dev/null +++ b/skills/beta-program-management/references/cohort-sizing-patterns.md @@ -0,0 +1,207 @@ +# Cohort sizing patterns + +Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. + +Cohort size is a calibration decision, not a maximize-volume decision. Each beta has a specific signal need; the right cohort size is the smallest that produces that signal reliably. + +--- + +## Saturation patterns by feedback type + +Different kinds of feedback saturate at different cohort sizes. + +**Critical bugs (crashes, data loss, broken core flows).** + +- Saturate fast: most surface in the first 1-2 weeks with 20-30 participants. +- Beyond ~50 participants, additional volume produces few new critical bugs. +- The cohort size for bug discovery: 20-50 participants is usually sufficient. + +**Friction issues (workflow interruptions, confusing flows, slow performance in specific cases).** + +- Saturate moderately: most surface in 2-4 weeks with 50-100 participants. +- Volume helps surface friction in less-common usage patterns. +- The cohort size for friction discovery: 50-200 participants typical. + +**Behavioral patterns (how users actually use the feature, what flows they follow, what features they ignore).** + +- Saturate slowly: 4-8 weeks with 100-500 participants needed for clear patterns. +- Patterns require usage volume; small cohorts may not generate enough usage to see patterns. +- The cohort size for behavioral signal: 100-500+ participants typical. + +**Edge cases (unusual configurations, rare usage contexts, specific environment combinations).** + +- Saturate very slowly: 500+ participants needed; some edge cases never surface in beta and are discovered post-GA. +- Volume is the only way to surface low-frequency edge cases. +- The cohort size for edge case discovery: 500-5,000+ participants; even at this scale, rare cases may slip through. + +**Performance under load (scale-related issues, infrastructure constraints, concurrent-use issues).** + +- Saturate when cohort exceeds the load threshold the issue requires. +- 1,000-10,000+ participants for at-scale validation. +- Often the central goal of RC betas. + +--- + +## Sizing decisions for different beta goals + +The cohort size matches what the team needs to learn. + +**Goal: Catch critical bugs before GA.** + +- Cohort size: 20-50 participants. +- Duration: 2-4 weeks. +- Closed cohort, calibrated to GA user profile. +- Most critical bugs surface fast; beyond this, returns diminish. + +**Goal: Validate behavioral assumptions about how users will use the feature.** + +- Cohort size: 100-300 participants. +- Duration: 4-8 weeks. +- Closed cohort with variety across usage patterns. +- Behavioral patterns need usage volume to emerge clearly. + +**Goal: Validate product-market fit assumptions for a major new feature.** + +- Cohort size: 200-500 participants. +- Duration: 8-12 weeks. +- Closed cohort spanning segments. +- Long enough duration to see retention and continued usage, not just initial engagement. + +**Goal: Validate at-scale infrastructure for a launch.** + +- Cohort size: 1,000-5,000+ participants. +- Duration: 4-8 weeks. +- Often open beta or large closed RC. +- Volume is the point; calibration is less important than scale. + +**Goal: Build a design partner program for ongoing collaboration.** + +- Cohort size: 3-10 partners. +- Duration: open-ended (months to years). +- Highly calibrated cohort with strong relationships. +- Depth over breadth; the program is qualitative collaboration, not at-scale validation. + +**Goal: Generate pre-launch marketing and audience.** + +- Cohort size: 1,000-10,000+ participants. +- Duration: 4-12 weeks. +- Open beta with marketing-driven recruitment. +- The cohort serves both validation and pre-launch buzz. + +--- + +## The size-matches-signal principle + +The cohort should be the smallest size that produces the signal the team needs. + +**Why "smaller is better when calibrated."** + +- Smaller cohorts produce more synthesizable feedback. The team can read every transcript, review every survey response, follow up with every participant who reports an issue. +- Smaller cohorts make participant relationships stronger. Each participant feels seen; engagement is higher. +- Larger cohorts produce volume that can drown signal. The team cannot synthesize 5,000 pieces of feedback as well as 50. + +**When larger is necessary.** + +- The team needs at-scale validation (load, concurrent users, edge cases). +- The team needs marketing reach. +- The team needs behavioral signal that requires substantial usage volume. + +**The discipline.** Default to the smallest cohort that produces the needed signal. Justify any larger size against specific signal needs. + +--- + +## Cohort size and feedback channel design + +Larger cohorts require different feedback channel design than smaller ones. + +**For cohorts of 5-50.** + +- Direct channels work: email, dedicated Slack, structured interviews. +- The team can engage with each participant individually. +- Synthesis can include reviewing all feedback. + +**For cohorts of 50-500.** + +- Mixed channels: structured surveys + sample interviews + in-product feedback widgets. +- Sampling required for synthesis: review all surveys, sample interviews and tickets. + +**For cohorts of 500-5,000.** + +- Aggregated channels: in-product feedback widgets, support ticket aggregation, automated surveys. +- Heavy sampling: review aggregate patterns, sample individual feedback. + +**For cohorts of 5,000+.** + +- Volume aggregation: NPS-style scoring, automated categorization, statistical analysis of usage patterns. +- Individual feedback rarely reviewed; patterns are the signal. + +The implication. Beta planning includes feedback channel design appropriate to cohort size. Mismatches (small cohort with aggregated channels, or large cohort with direct channels) produce friction. + +--- + +## Adjusting cohort size mid-beta + +Sometimes the team realizes mid-beta that the cohort is wrong-sized. + +**Cohort too small.** + +- Symptom: feedback volume is insufficient to see patterns. +- Cure: open recruitment for additional participants, applying the same selection criteria. +- Caution: late additions have less time in the beta; their feedback covers less of the beta period. + +**Cohort too large.** + +- Symptom: feedback volume overwhelms synthesis capacity; the team is reactive rather than analytical. +- Cure: usually do not reduce; instead, scale up synthesis capacity (more reviewers, more aggregation tooling). Reducing cohort feels like a betrayal to participants. +- Prevention: better sizing decision upstream. + +**Cohort skewed.** + +- Symptom: feedback patterns reflect skew (one segment over-represented). +- Cure: targeted recruitment to balance the cohort, or explicit acknowledgment of skew in synthesis. +- The cohort cannot always be re-balanced quickly; sometimes the synthesis adjusts for the skew rather than the cohort. + +--- + +## Cohort and beta duration + +Cohort size and duration interact. + +**Short beta (2-4 weeks).** Smaller cohort works because feedback saturates faster on critical issues. 20-100 participants typical. + +**Medium beta (4-8 weeks).** Mid-size cohort matches the duration. 50-300 participants typical. + +**Long beta (8+ weeks).** Larger cohort works because behavioral signal needs duration. 100-1,000+ participants. + +**The mismatch failures.** + +- Long beta with small cohort: insufficient volume; the duration produces no proportional signal. +- Short beta with very large cohort: insufficient time; the volume produces no proportional learning. + +The matching. Beta duration and cohort size both follow from signal need; they should be consistent. + +--- + +## Common cohort sizing failures + +**Defaulting to "more is better."** Large cohorts where small calibrated ones would produce stronger signal. + +**Sizing without reference to signal need.** Cohort size set arbitrarily; team cannot defend why this size. + +**Cohort size mismatched to duration.** Small cohort in a long beta produces sparse signal; large cohort in a short beta produces noise. + +**Cohort size mismatched to feedback channel design.** Direct channels with too many participants overwhelm; aggregated channels with too few participants under-utilize. + +**Mid-beta cohort changes without synthesis adjustment.** Cohort grows or shrinks; the synthesis approach does not adapt. + +**Confusing volume with signal.** Larger cohort numbers reported as success; the team did not actually learn proportionally more. + +--- + +## Methodology-level choices that stay in the public skill + +The saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. Cohort size and feedback channel design alignment. Adjusting cohort size mid-beta. Cohort and beta duration interaction. Common failures. + +## Implementation choices that stay internal + +Specific recruitment automation tooling. Specific aggregation tooling for large cohorts. Specific synthesis processes for different cohort sizes. The team's own conventions for sizing within the bands. These vary by team and tooling. diff --git a/skills/beta-program-management/references/common-beta-failures.md b/skills/beta-program-management/references/common-beta-failures.md new file mode 100644 index 0000000..204a1c2 --- /dev/null +++ b/skills/beta-program-management/references/common-beta-failures.md @@ -0,0 +1,205 @@ +# Common beta failures + +Ten-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most beta failures share a single root, which is treating beta as ceremony rather than as decision input. + +--- + +## Failure 1: Our beta produced no signal + +**Symptom.** The beta ran. The team has nothing actionable to show for it. The GA launch will happen with the same uncertainty the beta was supposed to address. + +**Diagnosis.** Soft-launch pattern. No structured selection, no defined feedback collection, no graduation criteria. + +**Cure.** Restructure the beta. Define the cohort, channels, criteria, and triage cadence. If the current beta cannot be saved, plan a more structured beta for the next feature. + +**Prevention.** Plan beta structure at the start, not after the beta has been running. + +--- + +## Failure 2: Our beta has 5,000 users and we cannot synthesize + +**Symptom.** Open beta or large cohort. Volume is high. The team is reactive rather than analytical. Synthesis cannot keep up. + +**Diagnosis.** Kitchen-sink. Cohort too large for the structured signal the team needs. + +**Cure.** Two paths. Scale up synthesis capacity (more reviewers, aggregation tooling). Or reduce the active cohort by focusing structured channels on a calibrated subset (e.g., select 200 active participants for interviews; let the rest contribute through aggregated channels). + +**Prevention.** Size cohort to match synthesis capacity. Larger cohorts require aggregated feedback infrastructure. + +--- + +## Failure 3: Our beta participants never gave feedback + +**Symptom.** Few survey responses. Few in-product widget submissions. Few interview signups. The cohort is silent. + +**Diagnosis.** Onboarding contract was unclear or feedback channels were friction-laden. Participants did not know what was expected or could not easily give feedback. + +**Cure.** Re-engage. Send specific, prompted requests for feedback. Make the channels easier (in-product prompts, simpler forms). Communicate what is being heard from those who do respond. + +**Prevention.** Onboarding makes feedback expectations explicit. Channels are designed for low friction. + +--- + +## Failure 4: We graduated to GA on schedule but launched with critical bugs + +**Symptom.** The GA launches. Critical issues that the beta cohort would have surfaced (or did surface but were not addressed) appear post-GA. + +**Diagnosis.** Graduation criteria were not enforced. The decision was calendar-driven; the team graduated before the criteria were met. + +**Cure.** Damage control: address the bugs quickly, communicate transparently, reset support expectations. + +**Prevention.** Graduation criteria are enforced honestly. The decision is criteria-driven, not calendar-driven. If criteria are not met, extend the beta or graduate with explicit acknowledgment of unmet criteria. + +--- + +## Failure 5: Our beta has been running for 8 months with no graduation + +**Symptom.** Beta has run far longer than planned. No firm graduation date. The team has avoided the GA decision. + +**Diagnosis.** Perpetual beta. No firm graduation criteria; the team avoided commitment. + +**Cure.** Force the graduation decision. Define criteria explicitly. Decide: graduate now, graduate by a specific date, or reset the beta. + +**Prevention.** Time-bound the beta from the start. Define graduation criteria upfront. Force the decision when the criteria are met or when the time is up. + +--- + +## Failure 6: Beta participants vented on Twitter before the launch + +**Symptom.** Beta participants posted screenshots, mentioned the feature publicly, or discussed the beta outside the cohort. + +**Diagnosis.** NDA missing or unclear. Trust violation early erodes participant willingness; broader visibility may damage launch plans. + +**Cure.** Damage control depending on impact. Reach out to participants individually. Adjust the launch plan if the leaked information affects positioning. + +**Prevention.** NDAs in place where appropriate. Confidentiality expectations explicit in onboarding. Cohort selection includes trust assessment. + +--- + +## Failure 7: The beta surfaced patterns we did not act on + +**Symptom.** The beta produced clear feedback about specific issues. The GA launches without addressing them. Customers hit the same issues post-GA. + +**Diagnosis.** Mid-beta triage missing. Feedback was collected but not used during the beta. + +**Cure.** For the GA: address the issues quickly post-launch; communicate transparently. For future betas: implement the triage cadence and iteration discipline. + +**Prevention.** Weekly triage cadence. Categorization of feedback. Iteration on critical and high-impact items during the beta. + +--- + +## Failure 8: The GA launch surprised us + +**Symptom.** Issues emerge at GA that the team did not anticipate from the beta. The beta did not actually validate the GA experience. + +**Diagnosis.** Cohort or feedback structure was wrong. The cohort did not match the GA user; the channels did not surface the kinds of issues the GA exposed. + +**Cure.** Address the surprises post-GA. Investigate the gap between beta and GA experience. Apply lessons to future betas. + +**Prevention.** Cohort calibrated to GA user. Channels designed to surface the kinds of signal the GA decision needs. Validation of the cohort-GA match before the beta starts. + +--- + +## Failure 9: Beta participants felt ignored after providing feedback + +**Symptom.** Participants gave feedback. The team did not communicate what was heard or addressed. Participants disengaged. + +**Diagnosis.** Communication discipline missing. Participants commit time and want to know it mattered. + +**Cure.** Re-engage with appreciation and specific acknowledgment. For future participants, tighten the communication discipline. + +**Prevention.** Weekly or bi-weekly updates to participants. Updates reference specific feedback. Participants who give substantive feedback receive direct acknowledgment. + +--- + +## Failure 10: We ran a closed beta that was effectively employees only + +**Symptom.** The "external beta" included primarily employees, employees' family members, or very-friendly customers. Not actual representative customers. + +**Diagnosis.** Internal-only beta with external branding. Missed the customer-context complexity. + +**Cure.** Run a true external beta before GA, even if shorter. Apply lessons to future cohort selection. + +**Prevention.** Cohort selection includes "are these actually external customers using the product in real conditions?" Internal-leaning cohorts get flagged in cohort review. + +--- + +## Failure 11: Cohort and channels mismatched + +**Symptom.** Small cohort with aggregated channels (no signal extracted from the small volume). Or large cohort with direct channels (overwhelmed synthesis). + +**Diagnosis.** Cohort size and channel design did not align. + +**Cure.** Adjust mid-beta if possible: scale synthesis for large cohorts, deepen direct channels for small ones. + +**Prevention.** Cohort size and channel design decided together. Mismatches caught at planning. + +--- + +## Failure 12: Feedback collected but not synthesized + +**Symptom.** Surveys completed; widgets submitted; interviews recorded. The beta ends; the team has not synthesized the feedback into patterns or recommendations. + +**Diagnosis.** Synthesis was treated as optional or postponed. Without synthesis, the feedback never produced decisions. + +**Cure.** Allocate synthesis time post-beta. Apply discovery-research-synthesis discipline (see that skill). Produce the synthesis even if delayed. + +**Prevention.** Plan synthesis as part of the beta timeline. Allocate explicit time and ownership. + +--- + +## Failure 13: Wind-down treated participants poorly + +**Symptom.** Participants graduated to GA without clear transition information. Recognition was thin or missing. Future-beta recruitment is harder because alumni are unenthused. + +**Diagnosis.** Wind-down communication missed key elements. Recognition was insufficient for the time invested. + +**Cure.** Reach out individually to participants who feel underrecognized. Adjust future wind-down templates. + +**Prevention.** Wind-down communication template covers all elements (transition, recognition, post-survey, future beta invitation). + +--- + +## Failure 14: No postmortem + +**Symptom.** Beta ends; team moves on. Lessons from this beta do not inform future ones. Patterns recur across multiple betas because nobody surfaced them. + +**Diagnosis.** Postmortem was skipped. The beta program does not improve. + +**Cure.** Run a delayed postmortem if feasible. Establish postmortem as a non-negotiable step. + +**Prevention.** Postmortem on the timeline. Owner identified. Lessons documented and applied. + +--- + +## Failure 15: Beta scope crept + +**Symptom.** Mid-beta, additional capabilities were added based on participant requests. The beta validated a different feature than the original. + +**Diagnosis.** Scope creep during the beta. Feature requests were absorbed into the live beta. + +**Cure.** Reset the beta if the changes are significant. Capture for post-GA roadmap rather than addressing during the beta. + +**Prevention.** Triage discipline rejects scope-expanding feature requests during the beta. Capture for post-GA; do not add. + +--- + +## The cross-cutting pattern + +Most beta failures share a single root: treating beta as ceremony rather than as decision input. + +Ceremony focuses on running a beta because betas are expected: invite participants, collect feedback, ship the GA. The beta is a stage gate, not a learning loop. + +Decision input focuses on what the beta needs to inform: which decisions, what signal will inform them, what cohort and channels will produce that signal. The beta is structured around the decision it serves. + +The fix for almost any beta failure starts with the same question: what specifically did the team need to learn from this beta, and how is the beta structured to produce that learning? When the answers are clear, the beta becomes load-bearing. When the answers are vague, the beta becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-decision pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/beta-program-management/references/feedback-collection-patterns.md b/skills/beta-program-management/references/feedback-collection-patterns.md new file mode 100644 index 0000000..49e1bbf --- /dev/null +++ b/skills/beta-program-management/references/feedback-collection-patterns.md @@ -0,0 +1,295 @@ +# Feedback collection patterns + +Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. + +The feedback collection design is what determines whether the beta produces signal or noise. Structured channels capture usable data; ad-hoc venting channels produce volume that does not synthesize. + +--- + +## Structured surveys + +Surveys at defined points in the beta. + +**The structure.** + +- 5-15 questions per survey. +- Mix of structured questions (Likert scale, multiple choice) and 1-2 open-ended questions. +- Tied to specific learning goals: each question has a reason for being there. +- Sent at defined points: end of week 1, mid-beta, end of beta. + +**Strong survey questions.** + +- "On a scale of 1-7, how likely are you to use this feature daily?" (closed-ended; quantitative signal) +- "What's the most useful thing you've done with this feature so far?" (open-ended; surfaces use cases) +- "What was confusing or frustrating in your first week?" (open-ended; surfaces friction) +- "Compared to how you did this task before, is this feature better, worse, or about the same?" (specific comparison) + +**Weak survey questions.** + +- "Do you like the feature?" (binary; not actionable) +- "What features would you like next?" (out of beta scope; produces wishlist) +- "How can we improve?" (too open-ended; produces unfocused responses) + +**Why structured surveys work.** + +- Quantitative signal aggregates. Mid-beta NPS or satisfaction trend lines surface signal. +- Open-ended questions tied to specific topics produce focused qualitative data. +- Participants understand what is being asked; response rates are higher than for vague open-ended surveys. + +--- + +## Async feedback forms + +Forms participants fill when they encounter specific issues. + +**The structure.** + +- Always-available link or in-product entry point. +- Form fields prompt for specific information: use case, severity, expected vs actual behavior, screenshots if applicable. +- Auto-routes to the team's tracking system (issue tracker, feedback aggregation tool). + +**Strong form fields.** + +- "What were you trying to do?" (use case context) +- "What did you expect to happen?" (mental model) +- "What actually happened?" (observed behavior) +- "How blocking is this?" (severity) +- "Steps to reproduce" (when applicable) + +**Why async forms work.** + +- Captures issues at the moment they happen. +- Structured fields produce consistent data across submissions. +- Synthesis is easier when each submission has the same information shape. + +--- + +## Structured interviews + +30-60 minute interviews with a subset of participants. + +**The structure.** + +- 5-15 interviews per beta, depending on cohort size. +- Mid-beta or near end of beta. +- Discussion guide tied to the team's learning goals. +- Recorded with permission; transcribed for synthesis. + +**Strong interview prompts.** + +- "Walk me through the last time you used this feature. What were you trying to do?" +- "What was the most useful thing about it? What was the most frustrating?" +- "How did you decide to use this instead of [alternative]?" +- "Looking back, what do you wish was different?" + +**Why structured interviews work.** + +- Depth that surveys cannot capture. +- Specific moments and decisions surface in conversation that participants would not write into surveys. +- The qualitative data complements the quantitative survey data. + +**Cross-reference `discovery-research-synthesis`** for the broader interview discipline. Beta interviews are validation-stage; the interviewing methodology is similar. + +--- + +## In-product feedback widgets + +Feedback collection contextualized to the moment. + +**The structure.** + +- Trigger: button or prompt within the beta feature. +- Captures: what the user was doing (page or context), brief feedback text, optional rating. +- Routes to the team's tracking system. + +**Strong in-product widget design.** + +- Triggered after specific moments (completing the feature's primary action, abandoning a flow). +- Brief: 1-3 fields max. +- Optional severity or sentiment rating. +- Captures the page or context automatically. + +**Why in-product widgets work.** + +- Capture friction at the moment, not weeks later. +- Context is preserved automatically. +- Low friction encourages submissions. + +--- + +## Beta-aware support tickets + +Support tickets routed to a beta-aware support team. + +**The structure.** + +- Beta participants flagged in the support system. +- Tickets from beta participants get special handling: tagged "beta," routed to support reps trained on the feature, given priority response. +- Common beta issues documented for the support team in advance. + +**Strong beta-support practices.** + +- Faster response than standard tickets (the participant is doing the team a favor). +- Support reps escalate beta issues to product team where the issue affects beta program decisions. +- Patterns across tickets surface to the beta program manager. + +**Why beta-aware support works.** + +- Surfaces issues participants encounter "in the wild," not just the issues they choose to flag through formal channels. +- Captures the support burden of the feature, which informs GA support readiness. + +--- + +## Channels that fail + +Common feedback channels that produce noise rather than signal. + +**Beta-only Slack channels for venting.** + +- Participants vent in real time. +- Mixes critical signal with casual chat. +- Nobody synthesizes. +- High-engagement participants drown out quieter ones. +- Cure: structured channels instead, or use Slack for community building rather than feedback collection. + +**"Reply to this email with feedback."** + +- Returns long unstructured emails. +- Synthesis is hard; useful patterns get lost. +- Cure: structured forms or surveys. + +**End-of-beta survey only.** + +- Catches only what participants remember at the end. +- In-the-moment friction is forgotten. +- Cure: surveys at multiple points; in-product widgets for moment-of capture. + +**"Tell us anything."** + +- Unfocused open-ended prompts produce unfocused responses. +- Participants do not know what is wanted; many do not respond. +- Cure: specific prompts tied to what the team needs to learn. + +--- + +## Channel mix discipline + +Most structured betas use 3-5 channels. Each surfaces different signal. + +**Typical channel mix.** + +- 1 structured survey at end of week 1 (quantitative + first-impression qualitative). +- 1 structured survey at mid-beta (quantitative trend + behavior signal). +- Always-available async feedback form (specific issues as they arise). +- 5-10 structured interviews near end of beta (qualitative depth). +- In-product feedback widget (in-the-moment friction). +- Beta-aware support routing (issues participants choose to escalate). + +**The synthesis.** The team synthesizes across channels. Patterns that appear in multiple channels are stronger; signals from a single channel are weaker. + +**Channel mix calibration.** + +- Smaller cohorts (5-50): more interviews, less aggregation. +- Larger cohorts (100-500): more surveys and aggregation, fewer interviews. +- Largest cohorts (500+): heavy aggregation, sampling for interviews. + +--- + +## Feedback synthesis cadence + +How feedback gets reviewed during the beta. + +**Weekly synthesis.** + +- 1-2 hours weekly during the beta. +- Review feedback across all channels for the week. +- Categorize: critical bug, friction, feature request, positive signal, edge case. +- Surface patterns: what recurring feedback are we seeing? + +**Bi-weekly pattern review.** + +- 1-2 hours bi-weekly. +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening? +- Decide: what to fix during the beta vs what to defer to post-GA roadmap. + +**End-of-beta synthesis.** + +- Substantial work: 1-2 weeks of synthesis depending on cohort size. +- Apply discovery-research-synthesis discipline (see that skill). +- Output: beta synthesis document with patterns, implications, and graduation recommendation. + +--- + +## Feedback signal quality + +Not all feedback is equally valuable. + +**High-signal feedback.** + +- Specific moments of friction with reproducible context. +- Patterns across multiple participants. +- Behavioral data showing what users actually do (vs what they say). +- Comparison to alternatives (what users tried before, why they switched). + +**Lower-signal feedback.** + +- One-off complaints with no pattern. +- Hypothetical preferences ("it would be nice if..."). +- Wishlist features unrelated to the beta scope. +- Venting without specific context. + +**The discipline.** Synthesis weights higher-signal feedback. Lower-signal feedback gets noted but does not drive decisions. + +--- + +## Feedback volume management + +Managing the flow of feedback as the beta runs. + +**Volume signals.** + +- Critical issues surface fast: most appear in the first 2 weeks. +- Friction issues surface continuously through the beta. +- Behavioral signal accumulates; visible by mid-beta. + +**Volume management.** + +- The team's synthesis capacity bounds usable volume. Beyond that capacity, additional feedback produces less actionable signal. +- For larger cohorts, aggregate channels (surveys, in-product widgets) scale better than direct channels (Slack, email). + +**Burnout risk.** + +- Beta program managers reading 100+ feedback items per week burn out. +- Triage is the discipline: not all feedback gets equal attention. +- Critical and pattern feedback gets full attention; one-off venting gets noted briefly. + +--- + +## Common feedback collection failures + +**Single-channel reliance.** Only one feedback channel; misses signal that other channels would have caught. + +**Channels not tied to learning goals.** Feedback collected without clear purpose; synthesis cannot tell what to do with it. + +**Noisy channels (Slack venting).** High volume, low signal-to-noise ratio. + +**End-of-beta only.** Misses in-the-moment friction; relies on participant memory. + +**Vague prompts.** Open-ended questions without focus; produces unfocused responses. + +**No mid-beta synthesis.** Feedback collected but not reviewed until end; opportunities to address issues during the beta missed. + +**Feedback channels that conflict.** Multiple Slack channels for the same purpose; participants confused about where to post. + +**No closing the loop.** Participants give feedback; team never tells them what was heard or changed; engagement decays. + +--- + +## Methodology-level choices that stay in the public skill + +Channels that work (structured surveys, async forms, interviews, in-product widgets, beta-aware support). Channels that fail. Channel mix discipline. Feedback synthesis cadence. Signal quality discipline. Volume management. Common failures. + +## Implementation choices that stay internal + +Specific survey tools and templates. Specific feedback form integrations. Specific in-product widget implementations. Specific support ticketing systems. The team's own conventions for channel selection. These vary by team and tooling. diff --git a/skills/beta-program-management/references/mid-beta-triage-and-iteration.md b/skills/beta-program-management/references/mid-beta-triage-and-iteration.md new file mode 100644 index 0000000..aa2614c --- /dev/null +++ b/skills/beta-program-management/references/mid-beta-triage-and-iteration.md @@ -0,0 +1,216 @@ +# Mid-beta triage and iteration + +Triage cadence. Iteration discipline (what to fix during the beta, what to defer). Communication with participants. + +Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. Mid-beta triage turns a static validation into an iterative one. + +--- + +## The triage cadence + +How the team reviews feedback during the beta. + +**Weekly triage (1-2 hours).** + +- Review feedback across all channels for the week. +- Categorize each piece: critical bug, friction issue, feature request, positive signal, edge case. +- Tag for action: fix this week, fix later in the beta, defer to post-GA, no action needed (one-off). +- Identify any critical issues warranting immediate response. + +**Bi-weekly pattern review (1-2 hours).** + +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening, which are not surfacing in volume? +- Surface decisions: what to address in the remaining beta period. + +**As-needed escalation.** + +- Critical issues (data loss, security, broken core flows) get same-day response regardless of cadence. +- The triage cadence does not delay critical-issue response. + +--- + +## Categorization + +Each piece of feedback gets categorized. + +**Categories.** + +- **Critical bug.** Crashes, data loss, broken core flows, security issues. Must be fixed before GA. +- **Friction issue.** Workflows that are confusing, slow, or sub-optimal but functional. Fix during beta where feasible; document otherwise. +- **Feature request.** Capability the participant wants that is outside beta scope. Capture for post-GA roadmap; do not add during beta. +- **Positive signal.** What is working well; what users find valuable. Surfaces what to preserve in GA and what to highlight in marketing. +- **Edge case.** Unusual configurations or contexts. Note for post-GA monitoring; address only if affecting many participants. +- **One-off.** Single observation without pattern. Note briefly; do not action. + +**Why categorization matters.** + +- Different categories have different action paths. Treating all feedback the same overwhelms triage. +- The categorization is the basis for the iteration decisions. + +--- + +## What to fix during the beta + +The team should fix some things during the beta and defer others. + +**Fix during the beta.** + +- Critical bugs that prevent participants from using the feature. The beta cannot validate the feature if participants cannot use it. +- Friction issues that are clearly addressable and significantly affect participant experience. Fixing them produces stronger end-of-beta signal. +- Issues that, if unfixed, will surface again post-GA at higher cost. +- Issues that participants are about to escalate publicly (if NDA-relevant) or that damage trust if left. + +**Defer to post-GA.** + +- Feature requests outside beta scope. +- Friction issues that affect a small subset of users in ways the team can document. +- Polish work that does not block the GA decision. +- Edge cases that do not affect mainline usage. + +**The "what changes the GA decision" test.** If fixing this issue affects whether the team can ship to GA, fix it. If it does not affect the GA decision, capture it for post-GA roadmap. + +--- + +## The iteration discipline + +Mid-beta iteration adds value but has constraints. + +**The discipline.** + +- Iterate on the feature, not the beta scope. Adding features to the beta mid-way confuses participants and dilutes signal. +- Fix critical and high-impact friction; capture rather than fix lower-impact issues. +- Communicate iteration to participants: when they see a fix or change, they know it came from their feedback. + +**The "do not redesign mid-beta" rule.** + +- Significant feature changes mid-beta produce two betas: the pre-change beta and the post-change beta. Neither is fully validated. +- If significant changes are needed, end the current beta, redesign, and start a new beta. Do not blend them. + +**The "no creep" discipline.** + +- Mid-beta is not the time to add capabilities outside the beta's original scope. +- Feature requests get captured for post-GA, not added to the beta. +- The beta's signal depends on consistency; scope creep undermines the validation. + +--- + +## Communication with participants + +Mid-beta communication keeps participants engaged. + +**The cadence.** + +- Weekly or bi-weekly updates to participants. +- Format: short email or in-product notification. +- Content: what was heard, what is being addressed, what is being deferred, what to expect next week. + +**Strong update content.** + +- "We heard your feedback about the configuration friction in step 3. We pushed a fix this week; please let us know if it is improved." +- "Several of you reported the dashboard load time is slow at scale. We are investigating; we expect a fix in the next 1-2 weeks." +- "We are seeing strong positive signal on the new export functionality. We will expand the format options in the next iteration." +- "Several of you requested integrations beyond the beta scope. We have captured these for post-GA roadmap." + +**Why communication matters.** + +- Participants who see their feedback acted on engage more substantively. +- Participants who feel ignored decay. +- Communication signals to participants that the team is listening. + +**Common communication failures.** + +- Silence between welcome and end of beta. Participants feel ignored. +- Generic updates that do not reference specific feedback. Feels performative. +- Over-communication. Daily updates are too much; participants tune out. +- Updates that promise more than the team will deliver. Erodes trust when promises are not kept. + +--- + +## The mid-beta health check + +A specific mid-beta milestone. + +**The milestone.** Roughly the midpoint of the beta. The team takes stock of where the beta is. + +**The questions.** + +- Is the feedback volume what was expected? If not, what is causing the difference? +- Are critical issues surfacing or has the team caught them all in the first part of the beta? +- Are behavioral patterns emerging? What do they suggest for the GA experience? +- Are participants engaged? Are some segments dropping off? +- Is the trajectory toward graduation criteria? Where are gaps? + +**The output.** + +- Adjustments to the beta operations: more triage, more communication, additional cohort recruitment if needed. +- Surfaced concerns about graduation: are the criteria reachable in the remaining beta time? +- Surfaced wins: what is going well that the team can build on for GA. + +--- + +## Mid-beta participant churn + +Some participants will drop off during the beta. + +**Why participants churn.** + +- The feature did not match their use case (they expected something different). +- They lost interest or got busy. +- They hit critical friction early and gave up. +- They felt ignored after providing feedback. + +**The response.** + +- Investigate churn. A subset of churn is normal; high churn is signal. +- For participants who churned because of friction: address the friction; possibly re-engage them. +- For participants who churned because of misfit: the cohort may have been miscalibrated; learn for future betas. +- For participants who felt ignored: tighten the communication discipline; thank them for prior feedback even if they have stopped engaging. + +**Replacement recruitment.** + +- For betas that need a specific cohort size for signal, replace churned participants if possible. +- Late-recruited replacements have less time in the beta; their feedback covers less of the beta period. +- Sometimes accepting churn and a smaller-than-planned cohort is the right call. + +--- + +## Triage anti-patterns + +Common ways triage decays. + +**Triage skipping.** No formal triage cadence; feedback accumulates without categorization or action. + +**Triage as logging.** Feedback gets categorized but never actioned. The categorization is documentation theater. + +**Triage by loudest voice.** Loudest participants get attention; quieter ones with similar feedback do not. Skews the synthesis. + +**Triage by easiness.** Easy fixes get prioritized regardless of impact. Important harder fixes get deferred indefinitely. + +**Triage without communication.** Internal triage happens but participants are not told. They feel ignored. + +**Triage that absorbs feature requests.** Participants request features outside scope; the team adds them mid-beta; scope creeps; signal dilutes. + +--- + +## Common iteration failures + +**No iteration during the beta.** Feedback is collected; the team waits for end of beta; opportunities to address issues during the beta are missed. + +**Excessive iteration.** Significant feature changes mid-beta. The beta becomes two different betas; neither validates the GA experience cleanly. + +**Iteration without communication.** The team fixes issues; participants do not know; engagement decays. + +**Iteration on participant requests outside scope.** Scope creep; the beta validates a different feature than the original. + +**No closing the loop.** Iterations happen; participants are not told their feedback drove the change; the connection between feedback and improvement is invisible. + +--- + +## Methodology-level choices that stay in the public skill + +The triage cadence. The categorization scheme. What to fix during the beta vs defer. The iteration discipline. The "do not redesign mid-beta" rule. Communication with participants. The mid-beta health check. Mid-beta churn handling. Common failures. + +## Implementation choices that stay internal + +Specific triage tools and trackers. Specific communication templates. Specific health-check formats. The team's own conventions for what counts as critical vs friction. These vary by team and tooling. diff --git a/skills/beta-program-management/references/participant-selection-criteria.md b/skills/beta-program-management/references/participant-selection-criteria.md new file mode 100644 index 0000000..b95bbcf --- /dev/null +++ b/skills/beta-program-management/references/participant-selection-criteria.md @@ -0,0 +1,212 @@ +# Participant selection criteria + +Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. + +Participant selection determines what the beta can produce. Calibrated cohorts produce decision-grade signal; misaligned cohorts produce noise that does not represent the GA user. Selection is upstream of every other beta decision. + +--- + +## Criteria that produce calibrated cohorts + +**Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. + +- Worked example: a feature for product managers at growth-stage SaaS companies. Beta participants should be PMs at growth-stage SaaS companies. Not designers, engineers, or PMs at very-early or very-late stage companies. +- The matching dimensions depend on the feature: role, company size, industry, usage volume, tenure, technical sophistication. + +**Variety across relevant dimensions.** Not all participants identical. + +- If the feature has segment-specific behavior, the cohort spans segments. +- If usage volume varies, the cohort includes high-volume and low-volume users. +- If geography matters (compliance, latency, language), the cohort spans relevant geographies. +- The variety should match the GA user diversity. + +**Feedback willingness.** Participants who agree to provide feedback through structured channels. + +- Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Recruiting should make the feedback expectation explicit. Participants who agree are more likely to engage; participants who decline are honest about their availability. + +**Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively. + +- Champion users, design partners, customers with active customer success relationships engage more. +- Customers in churn-risk are less likely to engage; their feedback may also be less representative (the relationship is already strained). + +**Real usage of the broader product.** Beta participants who use the broader product actively can give grounded feedback. Participants who signed up only for the beta and do not use the product otherwise often give surface-level feedback. + +--- + +## Criteria that produce miscalibrated cohorts + +**Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers. + +- Skews toward users who try every new feature; their feedback may not represent the broader target user. +- Misses users who would adopt at GA but who do not seek out beta sign-ups. + +**Highest-paying customers only.** Skews toward enterprise patterns. + +- Misses smaller-team and individual use cases. +- Enterprise feedback may emphasize features that smaller customers do not need. + +**Internal employees only.** Misses customer-context complexity. + +- Employees experience features differently than customers (familiarity, infrastructure, motivations). +- Internal-only validation produces "we tested" without "real customers tested." + +**Whoever happens to be available.** No selection criteria; the cohort is whoever the team can recruit quickly. + +- The cohort may not match the GA user; signal does not transfer to the GA decision. + +**Champion users only.** All beta participants are existing strong advocates. + +- Enthusiastic feedback may overstate readiness; missing the friction non-champion users would hit. + +--- + +## Variety calibration + +How to ensure the cohort spans the relevant dimensions. + +**The dimension audit.** + +- For the feature being beta'd, identify the dimensions that affect user experience. +- Common dimensions: role, company size, industry vertical, usage volume, geographic region, technical sophistication, tenure with the product. +- Decide which dimensions matter most for this feature. + +**Cohort composition.** + +- For each high-priority dimension, ensure the cohort includes representation across the values. +- If role matters: cohort includes participants in each relevant role. +- If usage volume matters: cohort includes high-volume, mid-volume, low-volume users. +- If industry varies meaningfully: cohort spans industries. + +**Worked example.** A feature for product managers using analytics tools. + +- Role dimension: cohort is all PMs (no other roles). +- Usage dimension: high-volume PMs (active daily users) + mid-volume PMs (weekly users). Skip low-volume because they likely will not use the feature meaningfully. +- Company size dimension: 10-50 employee, 50-200 employee, 200-500 employee. Skip enterprise (different feature priorities). +- Tenure dimension: PMs who have used the product 3+ months (so they have established workflows the new feature will integrate into). Skip new users. + +The cohort composition is intentional; each participant fits multiple criteria. + +--- + +## The cohort size question + +How many participants are enough. + +**The calibration is signal-need-driven.** + +- Bug discovery saturates fast: 20-30 participants surface most critical issues in 2-4 weeks. +- Behavioral signal saturates slower: 50-100 participants needed to see usage patterns clearly. +- Edge case discovery: 100-500+ participants needed; some edge cases never surface in beta. + +**Common cohort sizes by beta type.** + +- Design partner program: 3-10 participants. +- Closed alpha: 10-30 participants. +- Closed beta: 50-200 participants. +- Open beta: 500-5,000+ participants. +- RC validation: 1,000-10,000+ participants. + +**The "more is better" anti-pattern.** Teams default to large cohorts thinking volume produces signal. In practice, larger-than-needed cohorts produce volume without proportional signal increase, while making feedback synthesis harder. + +**The "smaller produces calibrated" principle.** A 50-person calibrated cohort often produces stronger signal than a 5,000-person uncalibrated one. Pick the smallest cohort that produces the signal needed. + +--- + +## The recruitment process + +How participants get selected. + +**Sources.** + +- Existing customer base: customer success identifies candidates matching the criteria. +- Sales pipeline: late-stage prospects who could become customers and provide feedback. +- Past beta participants: customers who participated in prior betas and proved engaged. +- Public sign-up forms (for open betas): with screening criteria applied to actual selection. +- Partner referrals: customers who recommend other customers fitting the profile. + +**The screening.** + +- Define the criteria explicitly (role, dimension values, feedback willingness). +- Apply the screening to candidates: who fits the criteria? +- For closed betas, decide which subset of fitting candidates to invite (cohort sizing). +- For open betas with screening, the sign-up form captures qualifying information; the team selects from sign-ups. + +**The invitation.** + +- Personalized invitations engage better than mass invitations. +- The invitation explains: what the beta is, what is expected, what participants get, how long it runs. +- Acceptance is opt-in; participants who decline are honest. + +**The capacity.** + +- Recruiting takes real time. A 50-participant closed beta may take 2-4 weeks of recruiting work depending on customer base and selection criteria. +- Plan recruiting time as part of the beta timeline. + +--- + +## The diversity-vs-control tradeoff + +Calibrated cohorts can over-control diversity in ways that miss valuable signal. + +**The tradeoff.** + +- Tightly-defined selection criteria produce a cohort that is uniform along the criteria. Reduces variety; may miss signal from users who differ. +- Loosely-defined criteria produce more diverse cohorts but make the cohort less calibrated to the GA user. + +**The middle path.** + +- Define the must-have criteria (role, key segment markers). +- Allow variety in the optional dimensions (industry, geography, tenure). +- The cohort is calibrated on what matters and varied on what does not. + +--- + +## When recruitment fails + +What to do when selection criteria cannot be met. + +**Insufficient candidates fitting criteria.** + +- Reconsider whether the criteria are too narrow. +- Extend recruiting time if feasible. +- Accept a smaller cohort that fully fits the criteria, rather than a larger cohort that includes mismatches. + +**Candidates fitting criteria decline to participate.** + +- Investigate why. Is the beta commitment too heavy? The compensation insufficient? The timing wrong? +- Adjust the offer; re-invite. +- If still insufficient, consider whether the beta plan is realistic given customer engagement willingness. + +**Cohort skew despite intentional selection.** + +- Some dimensions skew despite efforts (e.g., one industry over-represented because that industry is more receptive). +- Acknowledge the skew explicitly in synthesis. Patterns from the over-represented dimension may not generalize. + +--- + +## Common selection failures + +**No criteria.** Whoever happens to be available joins. Cohort does not represent GA user. + +**Self-selection only.** Open sign-ups skew the cohort. + +**Only champions.** Cohort over-represents enthusiasts; misses friction non-champions hit. + +**Internal employees only.** Misses customer-context complexity. + +**Single-dimension calibration.** Cohort uniform on one dimension (role) but mismatched on others (usage, segment). + +**Recruiting too late.** Beta starts before the cohort is calibrated; recruitment continues mid-beta; signal is muddled. + +**Enterprise-only.** Cohort over-represents large customers; misses smaller use cases. + +--- + +## Methodology-level choices that stay in the public skill + +The criteria for calibrated cohorts. The criteria for miscalibrated cohorts. Variety calibration with worked example. The cohort size question. The recruitment process. The diversity-vs-control tradeoff. When recruitment fails. Common selection failures. + +## Implementation choices that stay internal + +Specific recruiting tools and CRM integration. Specific screening surveys. Specific outreach templates. Specific tracking of cohort composition. The team's own conventions for selection criteria within different beta types. These vary by team and customer base. diff --git a/skills/brand-archetype-system/SKILL.md b/skills/brand-archetype-system/SKILL.md new file mode 100644 index 0000000..feb6c98 --- /dev/null +++ b/skills/brand-archetype-system/SKILL.md @@ -0,0 +1,143 @@ +--- +name: brand-archetype-system +description: "Apply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles." +category: brand +catalog_summary: "12 archetype defaults across 18 verticals: color, type, voice, imagery starters" +display_order: 5 +--- + +# Brand Archetype System + +Pre-composed aesthetic archetype defaults that jumpstart brand design work. Each archetype bundles color tendencies, type pairings, layout patterns, voice samples, and imagery direction for a recognizable aesthetic family. Stack-agnostic. Tool-agnostic. + +This is a starting-point library, not a methodology library. The agent applies archetype defaults to a specific brief; the archetypes themselves provide anchor points, not endpoints. + +--- + +## When to use + +- The user wants a starting point rather than designing from first principles +- The user references a brand or aesthetic family they want to design near +- Need to converge faster from many directions to one +- The user wants vertical-typical defaults (for example fintech consumer, B2B developer tools) +- The user wants to test what a brief would look like in a different archetype + +## When NOT to use + +- The user wants pure methodology guidance (use `brand-identity`) +- The user is in early ideation needing positioning territories (use `brand-ideation`) +- Defining voice for an existing brand (use `brand-voice`) +- Documenting a finished brand (use `brand-style-guide`) + +--- + +## How this composes with other skills + +This skill works upstream of `brand-identity` (provides starting defaults that brand-identity refines into a finished system) and parallel to `creative-direction` (archetypes can be located by position on the 4 creative-direction axes). + +Typical flow when this skill is invoked: +1. User provides a brief or references a target archetype +2. Agent picks the most relevant core archetype, or composes from 2 adjacent archetypes +3. Agent adapts the archetype's defaults to the brief (color tokens shift, type swaps to vertical-appropriate fonts, voice samples rewrite for the brand) +4. Agent flags adaptation choices made + +Direct verbatim copying of an archetype's default palette into a new brand is a failure mode. Archetypes constrain the design space; the brief specifies the point within that space. + +--- + +## The framework: 12 core archetypes plus 18 vertical applications + +Two layers of content in `references/`: + +### Core archetypes (12 files) + +Located in `references/core-archetypes/`. Each is an aesthetic family with: +- Aesthetic summary +- Position on the 4 `creative-direction` axes +- Color palette starter (4 to 6 hex values with token names and rationale) +- Type pairing starter (Google Fonts pairing with size scale) +- Layout and composition patterns +- Voice samples (5 to 10 representative lines) +- Component pattern descriptions (heroes, buttons, cards, tables) +- Imagery direction +- When to pick and when to avoid +- Adaptation guidance +- Exemplar brands with attribution language + +### Vertical applications (18 files) + +Located in `references/by-vertical/`. Each maps named brands to core archetypes in that vertical with: +- Vertical summary +- Common archetypes +- Brand-to-archetype mapping (5 to 10 brands per vertical) +- Vertical-specific adaptation notes +- Common archetype evolution patterns as brands mature + +### Two overview files + +- `00-archetype-system-overview.md`: how the system works, the taxonomy +- `01-how-to-apply-an-archetype.md`: the adaptation discipline, the failure modes + +--- + +## The 12 core archetypes + +| # | Archetype | Single-line summary | +|---|---|---| +| 01 | Editorial Restrained | Low-saturation, type-led, generous whitespace, considered | +| 02 | Technical Precise | Monospace and grid prominent, data-dense, system-feeling | +| 03 | Warm Conversational | Human imagery, mid-saturation, friendly type, approachable | +| 04 | Bold Confident | High-contrast, large display type, saturated, direct | +| 05 | Playful Energetic | Bright colors, illustration-led, dynamic, character-driven | +| 06 | Luxe Considered | Serif-led, generous spacing, restrained palette, premium | +| 07 | Clinical Trustworthy | Cool palette, sans-serif, clean medical or financial register | +| 08 | Rugged Utilitarian | Earth tones, workwear influence, no-nonsense type | +| 09 | Retro Nostalgic | Period-specific palette and type, intentional vintage reference | +| 10 | Minimal Essentialist | Black, white, single accent, sans-serif only, sparse | +| 11 | Vibrant Saturated | High-saturation across full palette, color as character | +| 12 | Documentary Honest | Photography-led, real people, low-touched imagery | + +## The 18 vertical applications + +- B2B SaaS: Developer Tools, Business Productivity, Marketing and Sales, Data and Analytics +- Fintech: Consumer, Enterprise +- DTC: Fashion, Beauty, Home and Lifestyle, Food and Beverage +- Consumer Health and Wellness +- Hospitality and Travel +- Media and Publishing +- EdTech +- Gaming and Entertainment +- Marketplace +- Crypto and Web3 +- Real Estate and Proptech + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands. "Editorial Restrained" not "Stripe-like." Brands are referenced as exemplars in description text using attribution language: "exemplified by [brands]", "common among [brands]", "characteristic of [brands]". + +This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## The four creative-direction axes (reference) + +Each archetype positions on the 4 axes defined in the `creative-direction` skill. Brief summary for cross-reference: + +- **Tone register**: Professional, Conversational, Playful +- **Aesthetic register**: Restrained, Considered, Expressive, Maximal +- **Audience relationship**: Authority, Peer, Companion, Performer +- **Sensory ambition**: Functional, Considered, Immersive, Theatrical + +Each core archetype file specifies its position on each axis. + +--- + +## Reference files + +- [`references/00-archetype-system-overview.md`](references/00-archetype-system-overview.md) - How the two-layer system fits together, entry patterns, when archetypes compose, and the recurring failure modes. +- [`references/01-how-to-apply-an-archetype.md`](references/01-how-to-apply-an-archetype.md) - The 5-step adaptation process: locate the design space, map the brief to adjustable dimensions, adapt color, adapt type, write voice samples. Includes the cross-archetype coherence check. + +The 12 core archetype files live in the `core-archetypes/` subdirectory under references, numbered 01 (Editorial Restrained) through 12 (Documentary Honest). The 18 vertical application files live in the `by-vertical/` subdirectory under references, numbered 01 (B2B SaaS Developer Tools) through 18 (Real Estate and Proptech). Load the relevant core archetype file plus the relevant vertical file together for any brief that names both an aesthetic family and an industry. + diff --git a/skills/brand-archetype-system/references/00-archetype-system-overview.md b/skills/brand-archetype-system/references/00-archetype-system-overview.md new file mode 100644 index 0000000..b47a529 --- /dev/null +++ b/skills/brand-archetype-system/references/00-archetype-system-overview.md @@ -0,0 +1,40 @@ +# Archetype system overview + +This document explains the taxonomy and how the layers fit together. Read this first when working with the archetype system for the first time. + +## The two layers + +**Core archetypes** (12 files) are the aesthetic families themselves. They span verticals; an archetype like Editorial Restrained appears in B2B SaaS, in media publishing, in DTC fashion. The core archetype files describe the family in pure form: what makes it recognizable, the color tendencies, the type pairings, the voice character. + +**Vertical applications** (18 files) describe how the archetypes manifest in specific industries with named brands. They are discovery surfaces: a user working on a fintech brand should be able to find their vertical, see which archetypes are common, see specific brand-to-archetype mappings, and decide which core archetype to start from. + +## How the agent should use the system + +Two entry patterns: + +**Entry by archetype** (user references an aesthetic family): "I want something Editorial Restrained for my analytics product." Agent loads the Editorial Restrained core archetype file, plus the B2B SaaS Data and Analytics vertical file for context. Composes defaults adapted to the brief. + +**Entry by vertical** (user references their industry): "I'm designing a consumer fintech app, what archetypes work here?" Agent loads the Fintech Consumer vertical file first, sees the brand-to-archetype mappings, picks the most relevant core archetype, then loads that for full defaults. + +## What this system is and is not + +**It is**: a library of pre-composed defaults that accelerate brand work by providing known-good starting points with documented rationale. + +**It is not**: a substitute for design judgment. The defaults are anchor points; the brief specifies where to land within the archetype's design space. + +**It is not**: a comprehensive theory of brand aesthetics. The 12 archetypes capture the most recognizable contemporary Western brand aesthetics. They are not exhaustive. Regional, cultural, and historical archetypes are deferred to future expansions of the catalog. + +## When archetypes compose + +Two archetypes can blend. Linear is Editorial Restrained with Technical Precise undertones. Stripe is Technical Precise with Editorial Restrained surfaces. Glossier is Vibrant Saturated with Minimal Essentialist composition. + +When the brief calls for blending, the agent picks two core archetypes and notes which contributes which dimension (for example "Editorial Restrained for type and whitespace, Technical Precise for color and density"). + +## The failure modes + +1. **Verbatim copying**: pulling the exact starter palette into a new brand without adaptation. Produces generic output. +2. **Archetype mismatch with audience**: picking an archetype because the user likes its exemplars rather than because it fits the audience. +3. **Cross-archetype tokens**: pulling a color from one archetype and type from another without considering coherence. Often produces incoherent output. +4. **Stale exemplars**: assuming a brand still exemplifies an archetype after a redesign. The archetype is durable; the brand is not. + +Each core archetype file's "Adaptation guidance" section addresses these. diff --git a/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md b/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md new file mode 100644 index 0000000..02c6607 --- /dev/null +++ b/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md @@ -0,0 +1,69 @@ +# How to apply an archetype + +This document is the operating manual. Once an archetype is picked, follow this process to adapt it to the specific brief. + +## The 5-step adaptation process + +### Step 1: Locate the archetype's design space + +Read the core archetype file. Understand: +- Position on the 4 creative-direction axes +- The non-negotiable structural choices (for example "single accent" for Editorial Restrained, "monospace prominent" for Technical Precise) +- The adjustable dimensions (specific hue of the accent, specific serif, specific density) + +The structural choices are what make the archetype recognizable. The adjustable dimensions are where the brief lands. + +### Step 2: Map the brief to adjustable dimensions + +For each adjustable dimension, ask: what does the brief specify or imply? + +- **Audience character**: Younger audience usually wants warmer accent; older wants cooler. Technical audience tolerates more density; consumer audience needs more whitespace. +- **Category context**: Crowded categories need stronger contrast; quiet categories can be more restrained. +- **Emotional direction**: Trust-needing brands lean cooler; warmth-needing brands lean warmer. +- **Competitive position**: If the closest competitor is in the same archetype, shift one adjustable dimension hard to differentiate. + +### Step 3: Adapt the color palette + +The starter palette is a relationship between values, not absolute hex codes. Preserve the relationship; shift the values. + +Example with Editorial Restrained: +- Default: ink #0F1B2D (navy), accent #5B8B85 (muted teal) +- Adaptation for a finance brief: ink #1A1F2E (deeper navy), accent #4A5D6E (slate blue), reads more institutional +- Adaptation for a consumer wellness brief: ink #2A2520 (warm dark brown), accent #7A9B7C (sage green), reads more grounded and warm + +Preserve: low saturation, single accent, paper-not-white background, ink-not-black text. Shift: specific hues to match emotional direction. + +### Step 4: Adapt the type pairing + +The starter pairing is a relationship between display and body, not specific fonts. Preserve the relationship; shift the fonts. + +Example with Editorial Restrained: +- Default: IBM Plex Serif (display) plus Inter (body) +- Adaptation for luxe-leaning brief: Tiempos Display (display) plus Inter (body) preserves the pairing, shifts the serif character +- Adaptation for technical-leaning brief: IBM Plex Serif (display) plus IBM Plex Sans (body) keeps within one family, reads more system-like + +Preserve: serif display plus sans body, modular scale, single weight per role. Shift: specific font choices to match register. + +### Step 5: Write voice samples for the specific brand + +The voice samples in the core archetype show character; they are not copy to lift directly. Write 5 to 10 new voice samples for the specific brand using the archetype's cadence and register. + +## The cross-archetype check + +Before finalizing, verify the output reads as coherent within the archetype: + +- Color: matches the archetype's saturation and contrast character? +- Type: matches the archetype's display and body relationship? +- Voice: matches the archetype's cadence and register? +- Layout: matches the archetype's density and whitespace tendency? + +If two of the four diverge from the archetype, either pick a different archetype or accept that the brand is a blend (and document which archetype contributes which dimension). + +## When to abandon an archetype mid-flow + +The archetype is wrong if: +- Three or more dimensions resist adaptation to the brief +- The audience signals reject the archetype's defaults (for example picking Editorial Restrained for a children's app) +- Direct competitors all live in the same archetype and your brief needs differentiation + +When abandoning, return to the vertical file for that industry and pick a different starting archetype. Do not try to retrofit an archetype that does not fit. diff --git a/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md b/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md new file mode 100644 index 0000000..1241203 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md @@ -0,0 +1,44 @@ +# B2B SaaS: Developer Tools + +## Vertical summary + +Brands serving developers building software. Audience values: technical precision, documentation depth, time-to-first-API-call. Brands compete on developer experience, primitive quality, observability, and composition. The category is mature with established archetypes. + +## Common archetypes in this vertical + +The dominant archetype is **Technical Precise** (Stripe docs, Sentry, Datadog). **Editorial Restrained** is the rising adjacent archetype (Linear, Vercel, Resend). **Bold Confident** appears at the consumer-edge (Loom, formerly Heroku). Other archetypes are rare in this space; warmth and play do not read as credibility to developers building production systems. + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Stripe | Technical Precise with Editorial undertones | Best-in-category documentation aesthetic; navy and violet accents; serif display creeping into marketing | +| Linear | Editorial Restrained | Single-accent restraint; brutal type hierarchy; muted palette | +| Vercel | Editorial Restrained leaning Technical Precise | Black and white; Geist font system; minimal accents | +| Sentry | Technical Precise | Dark mode dominant; purple accent; data-dense | +| Datadog | Technical Precise | Cool palette; UI-led marketing; dense | +| Resend | Editorial Restrained | New entrant; serif display; warm paper background | +| Cloudflare | Bold Confident | Orange brand color; energetic; consumer-tilted | +| GitHub | Editorial Restrained adjacent | Octocat character softens the precision | +| Supabase | Bold Confident leaning Technical Precise | Green primary; recently more restrained | +| Cursor | Technical Precise | Dark-mode-first; tool-focused; understated | + +## Vertical-specific adaptation notes + +- **Documentation surfaces are first-class**: developer brands need documentation as part of the brand surface, not an afterthought. The type system must scale to long-form technical reading. +- **Code samples are brand assets**: how code renders (syntax highlighting palette, line numbers, copy buttons) is brand expression. +- **Dark mode is required**, not optional. Most developers spend their day in dark interfaces. +- **Performance signals as brand signals**: page load time, animation frame rate, perceived speed are part of how developers judge developer brands. +- **Density tolerance**: developers tolerate (and often prefer) higher information density than other B2B audiences. + +## Common archetype evolution + +Developer brands frequently start Technical Precise and add Editorial Restrained as they mature. Stripe's evolution from pure technical to editorial-influenced marketing is the canonical example. Conversely, brands that start Bold Confident (Cloudflare, Supabase) sometimes retreat toward restraint as they target enterprise. + +The early-stage developer brand archetype shift is almost always: drop the consumer-tinted color, add a serif, lean into restraint. The mature-stage shift is sometimes: re-introduce a careful illustration system to soften pure restraint (GitHub's Octocat-era is the canonical case). + +## Vertical anti-patterns + +- **Playful Energetic in developer tools**: reads as unserious. Developers building production systems do not want a mascot taking up screen real estate in their dashboard. +- **Luxe Considered in developer tools**: reads as out-of-touch. Developer tools differentiate on substance, not premium feel. +- **Vibrant Saturated in developer tools**: rare and risky; works only when the brand is consumer-tilted (Cloudflare manages it with discipline). diff --git a/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md b/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md new file mode 100644 index 0000000..76f81c5 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md @@ -0,0 +1,43 @@ +# B2B SaaS: Business Productivity + +## Vertical summary + +Brands serving teams getting work done across documents, projects, communications, and design. Audience is prosumer-tilted: knowledge workers who self-serve, evaluate based on demos and free trials, and bring tools into their organizations from the bottom up. Brands compete on approachability, integration depth, and brand likeability alongside functional differentiation. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Slack, Mailchimp, Figma in marketing) and **Bold Confident** (Notion, Linear in launches). **Playful Energetic** appears at the edges (Asana classic era). **Editorial Restrained** is rising (Coda, Notion's recent surfaces). The category rewards personality more than developer tools but less than consumer apps. + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Notion | Bold Confident leaning Warm Conversational | Black on white plus illustration character; emoji-rich; oversized type | +| Figma | Warm Conversational | Multi-hue creative palette; illustration-led; community-driven | +| Loom | Bold Confident | Recent rebrand bold-purple-and-black; high contrast | +| Slack | Warm Conversational | Multi-hue saturated brand colors; hands-and-objects illustration era | +| Airtable | Warm Conversational | Multi-color brand; spreadsheet-meets-database approachable | +| Coda | Editorial Restrained | Type-led; restrained palette; document-first feeling | +| Asana | Playful Energetic moving to Warm Conversational | Mascot-era to recent considered warmth | +| ClickUp | Vibrant Saturated | Multi-hue palette; expressive; consumer-tilted | +| Monday.com | Vibrant Saturated | Saturated multi-hue; bold UI; high energy | +| Dropbox | Vibrant Saturated leaning Editorial Restrained | 2017 rebrand era is the canonical example of the shift | + +## Vertical-specific adaptation notes + +- **Illustration budget matters**: brands without illustration capacity should pick Editorial Restrained or Bold Confident rather than Warm Conversational or Playful Energetic. Bad illustration kills the warm archetypes immediately. +- **Onboarding surface as brand surface**: in productivity, onboarding flows are heavily branded and high-impact. The archetype must extend cleanly into product chrome. +- **Self-serve discovery**: pricing pages, signup flows, and product tours carry brand weight. Restraint in these surfaces signals trust; warmth signals approachability. +- **Bottom-up adoption pattern**: brands are evaluated by individual users before procurement. The archetype should not require enterprise sign-off to feel right. + +## Common archetype evolution + +Productivity brands often start Warm Conversational with heavy illustration and pull back toward Editorial Restrained or Bold Confident as they scale into enterprise. Slack's evolution shows this: early Slack was warm-illustration-heavy; current Slack reads more restrained while retaining color personality. Notion's evolution is similar. + +The mature-stage shift is frequently: keep the personality in voice and color, remove decorative illustration from primary surfaces, lean into typographic hierarchy. + +## Vertical anti-patterns + +- **Pure Technical Precise in productivity**: reads as developer tool rather than productivity tool. Audience expects warmth. +- **Luxe Considered in productivity**: reads as enterprise theatre. Self-serve audiences read restraint as remote. +- **Rugged Utilitarian**: completely incompatible with the audience. diff --git a/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md b/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md new file mode 100644 index 0000000..ae51ddf --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md @@ -0,0 +1,43 @@ +# B2B SaaS: Marketing and Sales + +## Vertical summary + +Brands serving marketers, sales teams, growth professionals, and revenue operations. Audience is mixed prosumer and enterprise: bottom-up adoption among individual marketers, top-down evaluation by RevOps and procurement. Brands compete on platform breadth, integration ecosystems, attribution claims, and trust signals to budget-holders. + +## Common archetypes in this vertical + +The dominant archetypes split by audience tier. **Warm Conversational** dominates SMB and prosumer (Mailchimp, Intercom, ConvertKit). **Bold Confident** appears at the growth-energy edge (Drift, Mutiny). **Clinical Trustworthy** dominates enterprise (Salesforce, Marketo). **Editorial Restrained** is the rising adjacent archetype (Webflow's marketing surfaces). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Mailchimp | Warm Conversational | Multi-hue brand; mascot-era illustration; SMB-focused | +| Webflow | Editorial Restrained | Serif-led marketing; typographic hierarchy; designer audience | +| HubSpot | Warm Conversational | Orange and white; rounded illustration; inbound voice | +| Intercom | Warm Conversational | Friendly conversational brand; chat-first UX | +| Drift | Bold Confident | Bold colors; conversational-AI positioning | +| Marketo | Clinical Trustworthy | Cool palette; enterprise-trust signals; B2B authority | +| Salesforce | Clinical Trustworthy at enterprise edge | Cloud iconography; trust-blue; enterprise authority | +| ConvertKit (Kit) | Warm Conversational | Creator-focused warmth; muted palette | +| Mutiny | Bold Confident | Saturated personalization-as-brand | +| Apollo | Editorial Restrained leaning Bold Confident | Recent restrained typography redesign | + +## Vertical-specific adaptation notes + +- **Enterprise versus prosumer split is wide**: prosumer leans warm and friendly; enterprise leans clinical and authoritative. The brand should pick a lane and commit; trying to do both produces neither. +- **Trust signals matter**: customer logo strips, peer-reviewed comparison tables, security certifications carry brand weight in this vertical. +- **Demo and trial flows**: a high portion of brand perception forms during the demo or free trial. The archetype must extend cleanly into in-product surfaces. +- **AI-positioning surge**: many brands in this category have recent AI-features positioning that affects archetype choice; AI features tend to pull brands toward Technical Precise or Bold Confident. + +## Common archetype evolution + +Marketing and sales brands frequently start Warm Conversational at SMB and evolve toward Clinical Trustworthy or Editorial Restrained as they target upmarket. Mailchimp's evolution from playful-illustration to more restrained type-led marketing reflects this. HubSpot's evolution from friendly orange to a more institutional brand presence is another example. + +The mature-stage shift is frequently: drop heavy illustration, narrow the palette, lean into customer evidence rather than personality. + +## Vertical anti-patterns + +- **Playful Energetic in enterprise marketing tools**: reads as unserious to budget-holders. +- **Luxe Considered in mass-market marketing tools**: reads as out-of-touch with the SMB user base. +- **Pure Technical Precise**: works for some categories (analytics, attribution) but feels wrong for relationship-building tools (CRM, email). diff --git a/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md b/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md new file mode 100644 index 0000000..a1cff84 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md @@ -0,0 +1,43 @@ +# B2B SaaS: Data and Analytics + +## Vertical summary + +Brands serving data teams, analysts, product managers, and engineers working with data infrastructure, business intelligence, and product analytics. Audience values: query power, schema clarity, time-to-first-insight, and trust in numbers. The category overlaps with developer tools at the infrastructure end and with marketing analytics at the application end. + +## Common archetypes in this vertical + +The dominant archetypes are **Technical Precise** (Mixpanel, Amplitude, Snowflake) and **Editorial Restrained** (dbt, Hex, Threshold the fictional reference build). The category rewards precision; **Clinical Trustworthy** appears at the enterprise BI edge (Tableau historically); **Bold Confident** appears at the new-entrant edge (Hex at launch). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Mixpanel | Technical Precise | Cool palette; product analytics rigor; chart-as-hero | +| Amplitude | Technical Precise | Blue and white; data-density tolerant; PLG positioning | +| Looker | Technical Precise | Enterprise BI restraint; Google acquired | +| Snowflake | Editorial Restrained adjacent | Restrained type; cloud-native confidence | +| Tableau | Clinical Trustworthy historically, Editorial Restrained recently | Recent rebrand pulled toward typographic restraint | +| dbt | Editorial Restrained | Type-led; community-driven; restraint as differentiator | +| Hex | Bold Confident | Saturated brand; modern data workspace positioning | +| Census | Editorial Restrained | Recent shift toward type-led restraint | +| Hightouch | Bold Confident | Strong brand colors; reverse ETL positioning | +| Threshold (fictional reference) | Editorial Restrained | Catalog reference build; PLG onboarding analytics | + +## Vertical-specific adaptation notes + +- **Chart and table rendering as brand**: how a chart looks, how table cells align, how numbers format are core brand expression. The archetype must extend cleanly into data visualization conventions. +- **Documentation depth**: data tools live and die on documentation. Long-form technical reading is core to the brand surface, not auxiliary. +- **Trust through precision**: vague claims undermine the archetype. Specific numbers, specific schemas, specific examples carry the brand. +- **SQL and code as content**: query examples, schema definitions, and code samples are first-class brand assets. + +## Common archetype evolution + +Data brands frequently start Technical Precise and add Editorial Restrained as they mature into prosumer territory. Snowflake's evolution from pure technical to restrained editorial is the canonical case. Conversely, brands that start Bold Confident (Hex, Hightouch) often pull back toward restraint as they target enterprise. + +The early-stage shift is usually: keep the technical precision in product surfaces, add editorial restraint to marketing. + +## Vertical anti-patterns + +- **Playful Energetic in data tools**: reads as untrustworthy with numbers. Audiences expecting analytical rigor reject playful brand expression. +- **Luxe Considered in data tools**: reads as marketing rather than substance. +- **Rugged Utilitarian**: completely incompatible with the audience and the category. diff --git a/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md b/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md new file mode 100644 index 0000000..1050614 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md @@ -0,0 +1,43 @@ +# Fintech: Consumer + +## Vertical summary + +Brands serving individual consumers across banking, investing, payments, lending, and budgeting. Audience splits sharply by age and risk tolerance: younger audiences tolerate (and prefer) energy and playfulness; older audiences require clinical trust signals. Brands compete on trust, fee transparency, and emotional positioning around money. + +## Common archetypes in this vertical + +The dominant archetypes are **Bold Confident** (Cash App, Robinhood for younger audiences) and **Clinical Trustworthy** (Chime, SoFi, Wealthfront for trust-needing positions). **Warm Conversational** appears at the savings-and-budgeting edge (Acorns). **Playful Energetic** appears at the consumer-payments edge (Venmo historically). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Cash App | Bold Confident | Black plus saturated green; oversized type; consumer-payments register | +| Robinhood | Bold Confident | Saturated green plus black; recently more institutional | +| Chime | Clinical Trustworthy | Trust-blue palette; calm voice; banking-not-bank positioning | +| SoFi | Clinical Trustworthy | Multi-product trust signals; restrained palette | +| Venmo | Playful Energetic historically | Multi-color personality; payments-as-social positioning | +| Wealthfront | Editorial Restrained | Type-led; institutional confidence; long-term-investing register | +| Acorns | Warm Conversational | Warm palette; round-up framing; approachable savings | +| Mint | Clinical Trustworthy historically | Cool palette; budgeting-trust positioning | +| Current | Bold Confident | Saturated brand; younger-audience positioning | +| Step | Playful Energetic leaning Bold Confident | Teen-banking; character-driven | + +## Vertical-specific adaptation notes + +- **Trust versus energy is the central design tension**: every consumer fintech brand sits somewhere on this spectrum. Picking the archetype is picking the position. +- **Regulatory and compliance copy** affects voice. The brand's voice must accommodate disclosures, terms, and risk language without breaking the archetype. +- **Money is emotional**: the archetype carries emotional positioning about money (excitement, security, freedom, control). The visual must match the emotional position. +- **Mobile-first**: most consumer fintech brand exposure is on phone screens. The archetype must extend cleanly to small screens with reduced ornamentation. + +## Common archetype evolution + +Consumer fintech brands frequently shift archetype as they target older audiences. Robinhood's evolution from pure bold-energy to more institutional restraint as it added retirement and IRA products is the canonical case. Cash App's evolution into financial-products-beyond-payments shows similar restraint additions. + +The mature-stage shift is usually: keep the brand color, add restraint to type, dial back the swagger in voice, add trust signals. + +## Vertical anti-patterns + +- **Luxe Considered in mass-market fintech**: reads as out-of-touch. +- **Documentary Honest in payments and investing**: photography of real people does not communicate the right thing in this category; the value is the product, not the experience. +- **Rugged Utilitarian**: completely incompatible. diff --git a/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md b/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md new file mode 100644 index 0000000..eb6935b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md @@ -0,0 +1,43 @@ +# Fintech: Enterprise + +## Vertical summary + +Brands serving businesses with payments, treasury, banking, spend management, and financial infrastructure. Audience splits between developer-touching (payment infrastructure) and finance-touching (corporate cards, spend management, treasury). Brands compete on integration depth, control surfaces, and operational trust. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Editorial Restrained** with Technical Precise undertones dominates developer-touching fintech (Stripe, Modern Treasury). **Bold Confident** dominates finance-touching B2B (Ramp, Brex, recent Mercury). **Technical Precise** dominates pure infrastructure (Plaid). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Stripe | Editorial Restrained with Technical Precise undertones | Best-in-category fintech brand; serif marketing, technical product | +| Plaid | Technical Precise | Developer-first; cool palette; integration-as-product | +| Mercury | Bold Confident, recently shifting to Editorial Restrained | Recent rebrand pulled back toward restraint | +| Brex | Bold Confident | Bold colors; corporate-card energy; recent restraint additions | +| Ramp | Bold Confident | Saturated palette; spend-management-with-energy positioning | +| Modern Treasury | Editorial Restrained | Type-led; payments-infrastructure restraint | +| Adyen | Editorial Restrained leaning Clinical Trustworthy | Enterprise-payments authority | +| Square (now Block) | Bold Confident historically | Black plus accent; SMB-payments register | +| Bill.com | Clinical Trustworthy | Cool palette; finance-team-tool positioning | +| Carta | Editorial Restrained | Recent rebrand pulled toward editorial type-led | + +## Vertical-specific adaptation notes + +- **Developer-touching versus finance-touching split**: payment infrastructure (Stripe, Plaid) is evaluated by developers; spend management (Ramp, Brex) is evaluated by finance. The archetype must match the evaluator. +- **Compliance and trust copy** is heavier than in consumer fintech: SOC 2, PCI-DSS, certifications must appear above the fold and be visually weighty. +- **Documentation depth**: developer-facing fintech needs documentation as primary surface; finance-facing needs reporting and dashboards as primary surface. +- **Multi-product expansion**: many enterprise fintech brands expand from a single product (payments, cards, banking) into a platform. The archetype must extend to multiple product lines coherently. + +## Common archetype evolution + +Enterprise fintech brands frequently start Bold Confident as challengers and shift toward Editorial Restrained as they target larger customers. Mercury's recent rebrand from bold-pastel to restrained-serif is the canonical example. Carta's recent restraint shift follows the same pattern. + +The mature-stage shift is usually: dial back the saturated color, lean into typographic restraint, add institutional confidence to voice. + +## Vertical anti-patterns + +- **Playful Energetic in enterprise fintech**: reads as financially unserious. Finance buyers reject playful brand expression even in modern challenger brands. +- **Vibrant Saturated**: tolerated only when the brand is a category challenger; mature enterprise positions require restraint. +- **Documentary Honest**: incompatible with the category; product surfaces and dashboards carry the brand, not real photography. diff --git a/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md b/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md new file mode 100644 index 0000000..b98fed8 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md @@ -0,0 +1,43 @@ +# DTC: Fashion + +## Vertical summary + +Brands selling apparel directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability or ethical positioning where relevant. The category is dominated by photography quality; brand archetypes ride on photo direction more than on type or color. Price point splits the vertical: above 80 dollars per piece favors Luxe Considered, mass-market favors Minimal Essentialist or Warm Conversational. + +## Common archetypes in this vertical + +The dominant archetypes are **Luxe Considered** (Aritzia, Reformation, COS at the premium end) and **Minimal Essentialist** (Everlane, Allbirds at launch, Cuyana). **Bold Confident** appears at streetwear and challenger brands (Stüssy digital, Kith). **Documentary Honest** appears in heritage and outdoor-adjacent fashion (Patagonia, Filson). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Aritzia | Luxe Considered | Editorial photography; serif type; mid-premium positioning | +| Reformation | Luxe Considered with sustainability voice | Cream and earthy palette; sustainability framing | +| Everlane | Minimal Essentialist | Black plus white; transparency narrative | +| Allbirds (launch era) | Minimal Essentialist | Warm white plus single accent; sustainable-essentials | +| Cuyana | Luxe Considered | Cream and warm-neutral; fewer-better-things positioning | +| Stüssy | Bold Confident at streetwear edge | High-contrast; oversized lockup; streetwear authority | +| COS | Minimal Essentialist | Black on white; architectural typography; H and M premium tier | +| Filson | Documentary Honest with Rugged Utilitarian | Heritage workwear; earned authenticity | +| Outdoor Voices (historical) | Vibrant Saturated leaning Warm Conversational | Multi-hue palette; recreation-not-sport positioning | +| Universal Standard | Editorial Restrained | Size-inclusive premium; serif-led type-first | + +## Vertical-specific adaptation notes + +- **Photography quality is the gating factor**: every archetype in this vertical depends on excellent product and lifestyle photography. Brands without photography budget should pick Minimal Essentialist (which can survive on product-on-white) over the other archetypes. +- **Model casting** is brand expression: who appears in the photography signals the audience the brand is speaking to. Casting decisions are archetype-relevant. +- **Sustainability framing** is increasingly default in this vertical: the archetype may need to accommodate sustainability narrative without leaning preachy. +- **Seasonal updates** affect archetype continuity: brands must be able to refresh imagery seasonally without breaking the brand system. + +## Common archetype evolution + +Fashion brands frequently start Minimal Essentialist at launch (low-cost archetype with high signal) and migrate toward Luxe Considered as they raise prices and add product lines. Allbirds' evolution shows this: launch era was pure Minimal Essentialist; recent surfaces lean warmer and more storied (Warm Conversational with Documentary Honest notes). + +Conversely, brands that start Luxe Considered sometimes pull back toward Minimal Essentialist when they target younger or more digitally-native audiences. + +## Vertical anti-patterns + +- **Technical Precise in fashion**: completely incompatible. +- **Playful Energetic in mass-market fashion**: reads as costume; works only at children's-or-novelty edge. +- **Bold Confident in heritage fashion**: undermines the heritage positioning. diff --git a/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md b/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md new file mode 100644 index 0000000..e007077 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md @@ -0,0 +1,43 @@ +# DTC: Beauty + +## Vertical summary + +Brands selling skincare, cosmetics, hair care, and personal care directly to consumers. Audience values: ingredient evidence (in clinical positions), aesthetic alignment (in aspirational positions), and category authority (in challenger positions). The vertical splits sharply across three lanes that map cleanly onto archetypes. + +## Common archetypes in this vertical + +Three clear lanes: **Vibrant Saturated** for personality-driven challenger brands (Glossier, Drunk Elephant); **Luxe Considered** for premium and aspirational (Aesop, Augustinus Bader); **Minimal Essentialist** for clinical-and-rational positioning (The Ordinary). **Documentary Honest** appears at the editorial-skincare edge (Topicals). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Glossier | Vibrant Saturated with restraint | Pink-and-white world; soft typography; community-as-brand | +| Drunk Elephant | Vibrant Saturated | Multi-hue saturated palette; clinical ingredient framing | +| Aesop | Luxe Considered | Apothecary aesthetic; restrained palette; editorial confidence | +| The Ordinary | Minimal Essentialist | Black on white; ingredient-as-name; clinical transparency | +| Fenty Beauty | Bold Confident | Saturated brand; inclusivity-as-positioning | +| Topicals | Vibrant Saturated with editorial photography | Saturated palette plus documentary photo direction | +| Sunday Riley | Luxe Considered | Premium clinical; warm palette; ingredient narrative | +| Augustinus Bader | Luxe Considered | Pure luxury skincare; serif-led; minimal product range | +| Tatcha | Luxe Considered | Japanese-influenced premium; cream palette; heritage narrative | +| Bubble | Vibrant Saturated leaning Playful Energetic | Gen-Z skincare; bright multi-hue; accessible price point | + +## Vertical-specific adaptation notes + +- **Three-lane decision is the central archetype choice**: Vibrant Saturated (personality), Luxe Considered (premium), Minimal Essentialist (clinical). Commit to one lane; trying to do two reads as confused. +- **Ingredient communication**: how ingredients are presented carries archetype weight. Clinical lane presents ingredients as data; premium lane treats ingredients as story; personality lane treats ingredients as character. +- **Packaging design** is integrated with the digital brand: the bottle, jar, or tube on the page is brand expression. Packaging design must match the archetype. +- **Photography conventions**: clinical lane uses product-on-white; premium lane uses editorial styled photography; personality lane uses saturated lifestyle and product-on-color. + +## Common archetype evolution + +Beauty brands frequently stay within their original archetype but refine over time. Glossier has stayed Vibrant Saturated with increasing restraint as the brand has matured. The Ordinary has stayed Minimal Essentialist with subtle additions for new product lines. Aesop has stayed Luxe Considered with consistent discipline since launch. + +Brands that try to switch archetypes (for example a clinical brand adding personality) usually undermine their original positioning. + +## Vertical anti-patterns + +- **Technical Precise in beauty**: incompatible; reads as cold and clinical without the trust signals to justify it. +- **Rugged Utilitarian**: completely incompatible. +- **Mixed clinical-and-personality**: a brand that tries to be both The Ordinary and Glossier ends up neither. diff --git a/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md b/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md new file mode 100644 index 0000000..5d47154 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md @@ -0,0 +1,43 @@ +# DTC: Home and Lifestyle + +## Vertical summary + +Brands selling bedding, furniture, kitchenware, home accessories, and lifestyle goods directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability framing where relevant. The vertical rides on lifestyle photography quality more than any other element; the archetype is downstream of how the brand photographs interiors and objects in use. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Brooklinen, Article, Floyd in marketing) and **Luxe Considered** (Parachute, West Elm, Pottery Barn premium tier). **Minimal Essentialist** appears at the design-purist edge (Floyd in product surfaces, Hem). **Bold Confident** appears at the challenger-mattress edge (Tuft and Needle historically, Casper historically). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Brooklinen | Warm Conversational | Friendly bedding brand; mid-saturation palette; clear value framing | +| Parachute | Luxe Considered | Cream and warm-neutral; aspirational bedding | +| Article | Warm Conversational | Mid-century furniture; muted palette; design-led | +| Floyd | Minimal Essentialist | Minimal modular furniture; clean type; restrained palette | +| West Elm | Luxe Considered | Premium home; serif type; lifestyle photography | +| Tuft and Needle (historical) | Bold Confident historical, Warm Conversational now | Direct-to-consumer mattress positioning | +| Casper (historical) | Bold Confident historical | Original sleep-better-everything campaign register | +| Hem | Minimal Essentialist | Scandinavian-influenced minimal; modular furniture | +| Quince | Minimal Essentialist leaning Luxe Considered | Premium-quality at accessible pricing; restraint as positioning | +| Snowe | Luxe Considered | Cream palette; minimal kitchenware aesthetic | + +## Vertical-specific adaptation notes + +- **Lifestyle photography is the foundation**: the archetype rides on environmental photography quality. Bad room photography kills any archetype in this vertical. +- **Product-in-context dominates**: the bedding on a real bed, the chair in a real room. Product-on-white works only for technical specifications, not for hero photography. +- **Material and craftsmanship narrative**: how the brand discusses what the product is made of carries archetype weight. Luxe Considered uses material story heavily; Warm Conversational uses it lightly. +- **Sustainability framing**: increasingly default in this vertical; the archetype must accommodate it without leaning preachy. + +## Common archetype evolution + +Home brands frequently start Warm Conversational at launch and pull toward Luxe Considered as they raise prices and add product lines. Parachute's evolution shows this: launch era was more Warm Conversational; current Parachute is firmly Luxe Considered. Brooklinen has stayed Warm Conversational by intentionally holding its accessibility positioning. + +The mature-stage shift is usually: dial back the brand color, lean into typography and photography, drop overt accessibility framing. + +## Vertical anti-patterns + +- **Technical Precise in home goods**: completely incompatible. +- **Vibrant Saturated in home goods**: works only at the kids and novelty edge; reads as cheap on premium furniture and bedding. +- **Rugged Utilitarian**: works only when the brand is genuinely heritage-craftsman (cast iron, woodworking); slips into costume on mainstream home goods. diff --git a/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md b/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md new file mode 100644 index 0000000..1677ab1 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md @@ -0,0 +1,43 @@ +# DTC: Food and Beverage + +## Vertical summary + +Brands selling beverages, snacks, supplements, and packaged food directly to consumers. Audience values: ingredient transparency, taste promise, and category disruption framing. The vertical is dominated by challenger brands using nostalgic-or-bold positioning to break into commoditized categories (soda, water, snacks, protein, energy drinks). + +## Common archetypes in this vertical + +The dominant archetype right now is **Retro Nostalgic** (Olipop, Liquid Death, Poppi), differentiating by era pick more than by archetype switch. **Bold Confident** appears at the energy and functional drink edge (AG1, Athletic Brewing). **Minimal Essentialist** appears at the clean-label edge (RXBar). **Vibrant Saturated** appears at the wellness-with-personality edge (Recess). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Olipop | Retro Nostalgic (70s lean) | Wellness-soda category creator; 70s wellness palette and type | +| Liquid Death | Retro Nostalgic (80s metal lean) | Water with metal-band branding; saturated metal aesthetic | +| Poppi | Retro Nostalgic (90s lean) | Pastel 90s palette; gut-health soda | +| AG1 (Athletic Greens) | Bold Confident | Black plus saturated green; premium green-powder positioning | +| RXBar | Minimal Essentialist | Black on white; no-bullshit label as brand identity | +| Athletic Brewing | Bold Confident with retro undertones | Non-alcoholic beer; heritage type plus modern energy | +| Recess | Retro Nostalgic (70s wellness lean) | Pastel palette; CBD and adaptogens with chill positioning | +| Magic Spoon | Retro Nostalgic (90s cereal lean) | Adult cereal with 90s saturated palette | +| Olly | Retro Nostalgic with Playful Energetic notes | Mass-market vitamins with playful 70s wellness register | +| Bare Performance Nutrition | Bold Confident | Black plus saturated accent; performance-supplement register | + +## Vertical-specific adaptation notes + +- **Era pick is the differentiation strategy**: the F and B challenger category is dominated by Retro Nostalgic right now. Brands differentiate primarily by which era they reference, not by which archetype they pick. +- **Packaging design is integrated with digital**: the can, bottle, or box on the website is the brand. Packaging design must lead the digital brand expression. +- **Ingredient transparency is default**: nutrition facts, ingredient lists, and provenance stories must accommodate the archetype. +- **Subscription mechanics**: many F and B brands are subscription-driven; the archetype must extend cleanly into subscription management and unsubscribe surfaces. + +## Common archetype evolution + +F and B challenger brands frequently start strong in Retro Nostalgic and stay there. The brand identity is the era choice. Brands that try to evolve away from their original era reference usually lose differentiation. + +Mature brands sometimes dial back the era reference as they enter mass distribution: Olipop's recent surfaces are subtler about the 70s reference than its original launch. + +## Vertical anti-patterns + +- **Editorial Restrained in F and B**: works only at premium spirits and craft chocolate; reads as wrong-category for mass beverage and snack. +- **Technical Precise**: completely incompatible. +- **Generic minimalism**: F and B is so saturated with retro-and-bold brands that Minimal Essentialist works only when the brand has a sharp specific reason to be minimal (RXBar's no-bullshit label is the canonical case). diff --git a/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md b/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md new file mode 100644 index 0000000..3a97ae8 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md @@ -0,0 +1,43 @@ +# Consumer Health and Wellness + +## Vertical summary + +Brands serving consumers across telehealth, mental wellness, fitness, supplements, and self-care. Audience values: trust signals, clinical credibility, and emotional positioning around health. The vertical splits between mental health (which leans warmer and softer) and physical health (which leans clinical and trust-led). + +## Common archetypes in this vertical + +The dominant archetypes split by mental versus physical: **Clinical Trustworthy** for telehealth and physical-meds (Hims, Ro, Cerebral, Care/of); **Warm Conversational** and **Playful Energetic** for mental wellness (Calm, Headspace); **Vibrant Saturated** at the gen-Z mental health edge (Bumble Health). **Editorial Restrained** appears at the longevity-clinic edge (Function Health). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Hims | Clinical Trustworthy with peach warmth | Mens-health telehealth; warm tone breaks pharmaceutical cold | +| Hers | Clinical Trustworthy with warm accent | Womens-health telehealth; same brand system, womens lens | +| Ro | Clinical Trustworthy | Trust-blue palette; multi-condition telehealth | +| Care/of | Clinical Trustworthy with Warm Conversational | Personalized supplements; warm trust register | +| Cerebral | Clinical Trustworthy | Mental-health telehealth; restraint signals seriousness | +| Calm | Vibrant Saturated with restraint | Sleep-and-meditation; gradient-rich; soft palette | +| Headspace | Playful Energetic | Orange brand; character-illustration-driven; meditation-with-personality | +| Talkspace | Clinical Trustworthy | Therapy access; cool palette; trust signals | +| Function Health | Editorial Restrained | Longevity testing; type-led restraint; institutional confidence | +| Whoop | Technical Precise | Performance health; data-density; athlete positioning | + +## Vertical-specific adaptation notes + +- **Mental versus physical health split**: mental health brands lean warmer (Calm, Headspace, Talkspace); physical health brands lean clinical (Hims, Ro). The audience signals differ; the archetype must match. +- **Regulatory copy** affects voice. FDA disclaimers, medical disclaimers, prescription-required notices must accommodate the archetype. +- **Trust through specificity**: vague claims undermine the archetype. Specific dosages, specific evidence, specific licensed-clinician credentials carry the brand. +- **Subscription-and-cancellation flows**: the archetype must extend into ongoing subscription management; brands often lose trust here when the archetype breaks. + +## Common archetype evolution + +Health and wellness brands frequently stay in their original archetype but refine. Hims has stayed Clinical Trustworthy with growing warmth as it expanded categories. Calm has stayed in its restrained-vibrant lane as it expanded from meditation to sleep to broader wellness. + +Mental wellness brands that try to add physical-health products (or vice versa) often struggle to extend the archetype; the brand may need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- **Bold Confident in clinical wellness**: reads as overpromising. Health categories punish overpromise heavily. +- **Rugged Utilitarian**: works only in performance-athletic wellness; reads wrong in mainstream health. +- **Vibrant Saturated in physical health**: works only at younger-audience edges (Bumble Health for college students); reads wrong in mainstream telehealth. diff --git a/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md b/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md new file mode 100644 index 0000000..8b0b68a --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md @@ -0,0 +1,43 @@ +# Hospitality and Travel + +## Vertical summary + +Brands across hotels, short-term rentals, travel platforms, and travel-adjacent services. Audience values: trust signals (especially for booking platforms), aesthetic alignment (for hotels and properties), and experiential promise. The vertical is photography-dominated; the archetype rides on photo direction. + +## Common archetypes in this vertical + +The dominant archetypes are **Documentary Honest** (Airbnb in marketing, Selina, Hostelworld) and **Luxe Considered** (Aman, Four Seasons, premium hotel collections). **Editorial Restrained** appears at the hotel-tech edge (Sonder). **Minimal Essentialist** appears at travel-product brands (Away). **Bold Confident** at the disruptor edge (Hopper). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Airbnb | Documentary Honest | Real-photography of real homes; experiential framing | +| Aman | Luxe Considered (extreme) | Pure luxury hospitality; serif-led; understated authority | +| Four Seasons | Luxe Considered | Premium hotel chain; institutional luxury aesthetic | +| Selina | Documentary Honest | Lifestyle hotels; real-photography; community framing | +| Sonder | Editorial Restrained | Boutique short-stay; type-led; quiet confidence | +| Away | Minimal Essentialist | Travel luggage; minimal product photography; restrained type | +| Marriott Bonvoy | Luxe Considered | Loyalty program brand; aspirational typography | +| Hopper | Bold Confident | Saturated brand; price-prediction positioning | +| Hostelworld | Playful Energetic | Backpacker positioning; multi-color; younger-audience | +| Tripadvisor | Warm Conversational | Trust-through-reviews; friendly approachable register | + +## Vertical-specific adaptation notes + +- **Photography defines the vertical**: the archetype is downstream of photo direction. Brands without exceptional photography cannot execute Documentary Honest or Luxe Considered. +- **Booking flow versus discovery flow**: the brand must extend across both surfaces. Booking flow leans toward trust signals (Clinical Trustworthy notes); discovery flow leans toward aspiration (the chosen archetype). +- **Trust signals matter**: reviews, ratings, cancellation policies must appear with archetype-appropriate weight. Luxe Considered makes trust signals understated; Documentary Honest puts them alongside imagery. +- **Multi-property versus single-property**: hotel chains (Marriott, Hilton) face different brand challenges than single-property luxury (Aman individual properties). The archetype must scale. + +## Common archetype evolution + +Hospitality brands frequently stay in their original archetype. Airbnb has stayed Documentary Honest through multiple rebrand iterations. Aman has stayed Luxe Considered since launch. Travel-product brands (Away) have stayed Minimal Essentialist. + +Brands that try to switch archetypes (for example a budget brand trying to feel premium without raising prices) usually fail to land. + +## Vertical anti-patterns + +- **Technical Precise in hospitality**: completely incompatible. +- **Rugged Utilitarian in mainstream hospitality**: works only at adventure-travel edges (REI Adventures); reads wrong in city hotels. +- **Vibrant Saturated in luxury hospitality**: undermines the premium positioning immediately. diff --git a/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md b/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md new file mode 100644 index 0000000..588967b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md @@ -0,0 +1,43 @@ +# Media and Publishing + +## Vertical summary + +Brands across digital publications, newsletters, books, podcasts, and editorial platforms. Audience values: editorial voice, intellectual rigor, and reading experience quality. The vertical is dominated by typography; the archetype rides on type system more than on color or photography. + +## Common archetypes in this vertical + +The dominant archetypes are **Editorial Restrained** (Substack, The Browser, Bloomberg, NYT Cooking) and **Luxe Considered** (Stripe Press, premium book design). **Minimal Essentialist** appears at the classic-publishing edge (Medium in its restrained era). **Documentary Honest** appears at journalism-as-brand (NYT visual journalism). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Substack | Editorial Restrained | Serif-led; cream paper; type-as-product | +| Stripe Press | Luxe Considered | Premium book design; typography excellence; collector-grade | +| The Browser | Editorial Restrained | Restrained newsletter; type-led; institutional reading register | +| NYT Cooking | Editorial Restrained | Recipe-focused; serif typography; brand-trust-through-restraint | +| Bloomberg | Editorial Restrained | Financial publishing; high-density information; institutional confidence | +| The Information | Editorial Restrained | Tech business journalism; type-led; subscriber-business model | +| Medium (classic) | Minimal Essentialist | Original era was pure restrained sans; recent evolution warmer | +| The New York Times | Editorial Restrained | Canonical example; serif-led; institutional journalism | +| Defector | Editorial Restrained with personality | Worker-owned sports; restrained with editorial voice | +| Lithub | Editorial Restrained | Literary publishing; serif throughout; reading-first | + +## Vertical-specific adaptation notes + +- **Type system carries the brand**: in media and publishing, the typography is the brand. Most archetype decisions are font-pair decisions. +- **Reading experience as primary surface**: the article page must lead the brand expression. Marketing surfaces follow the article-reading experience. +- **Long-form versus short-form**: long-form journalism brands lean Editorial Restrained or Documentary Honest; newsletter and short-form brands have more archetype range. +- **Subscription mechanics**: paywall surfaces, subscription management, and unsubscribe flows must extend the archetype. Brands often lose archetype coherence at these surfaces. + +## Common archetype evolution + +Media brands frequently stay in their original archetype. Substack has stayed Editorial Restrained since launch. The New York Times has stayed Editorial Restrained for over a century. Bloomberg has stayed Editorial Restrained through multiple redesigns. + +Brands that try to add personality to a restrained archetype (Medium's attempts to feel warmer over time) often produce confusion. The discipline is the brand. + +## Vertical anti-patterns + +- **Bold Confident in journalism**: undermines credibility; reads as opinion-blog rather than reporting. +- **Vibrant Saturated in publishing**: works only at children's-publishing and novelty edges. +- **Technical Precise in media**: works only at niche publications (tech-focused) and reads wrong elsewhere. diff --git a/skills/brand-archetype-system/references/by-vertical/14-edtech.md b/skills/brand-archetype-system/references/by-vertical/14-edtech.md new file mode 100644 index 0000000..7b3d29b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/14-edtech.md @@ -0,0 +1,43 @@ +# EdTech + +## Vertical summary + +Brands across K-12 learning, higher education, professional development, and consumer learning apps. Audience splits sharply by age and learning context: children's apps lean playful; professional development leans clinical; consumer learning leans warm; technical education leans precise. The vertical rewards personality on the consumer side and authority on the institutional side. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Playful Energetic** for K-12 and habit-forming consumer learning (Duolingo, Khan Academy Kids). **Warm Conversational** for adult consumer learning (Khan Academy, Brilliant). **Clinical Trustworthy** for professional development (Coursera, edX). **Luxe Considered** for premium adult education (MasterClass). **Technical Precise** for technical education (Codecademy, Frontend Masters). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Duolingo | Playful Energetic (canonical) | Owl mascot; saturated green; character-driven habit formation | +| Khan Academy | Warm Conversational | Friendly approachable; muted palette; non-profit mission framing | +| Brilliant | Bold Confident leaning Warm Conversational | Math-and-science learning; saturated palette; problem-solving register | +| MasterClass | Luxe Considered | Premium adult education; editorial photography; celebrity-instructor positioning | +| Codecademy | Technical Precise | Developer education; dark mode; code-first | +| Coursera | Clinical Trustworthy | Higher-ed-credentialed; cool palette; institutional partnerships | +| edX | Clinical Trustworthy | University-courses-online; restrained academic register | +| Udemy | Warm Conversational | Mass-market courses; multi-hue palette; accessible pricing | +| Outschool | Playful Energetic with Warm Conversational | K-12 small-group learning; warm illustration; family register | +| Frontend Masters | Technical Precise | Developer-focused; dark mode; instructor-as-authority | + +## Vertical-specific adaptation notes + +- **Audience age determines archetype**: K-12 leans playful; teens lean bold; adults lean warm or clinical; technical learners lean precise. Pick the audience first. +- **Habit formation versus information transfer**: habit-formation products (language apps, daily-skill apps) lean playful. Information-transfer products (course platforms, lectures) lean restrained or clinical. +- **Credential signaling**: institutional partnerships, certifications, accreditation must appear with archetype-appropriate weight. Clinical Trustworthy makes them prominent; Playful Energetic makes them secondary. +- **Progress mechanics**: streaks, badges, leveling are core to many edtech products. The archetype must extend into gamification surfaces. + +## Common archetype evolution + +Edtech brands frequently start in their target audience archetype and stay. Duolingo has stayed Playful Energetic since launch (with increasing character development). Coursera has stayed Clinical Trustworthy. MasterClass has stayed Luxe Considered. + +Brands that try to switch (a K-12 brand attempting to add adult learning) usually need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- **Playful Energetic for adult professional development**: reads as unserious; adult learners reject playful brand expression for credential-building. +- **Clinical Trustworthy for K-12**: reads as cold and unfriendly to children and parents. +- **Rugged Utilitarian**: works only at outdoor-education edge (NOLS, Outward Bound); reads wrong elsewhere. diff --git a/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md b/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md new file mode 100644 index 0000000..86dba90 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md @@ -0,0 +1,43 @@ +# Gaming and Entertainment + +## Vertical summary + +Brands across gaming platforms, streaming services, game studios, and entertainment apps. Audience values: cultural alignment with the gaming or entertainment subculture, content discovery, and community signals. The vertical splits between platform brands (chrome that hosts content) and content brands (the games or shows themselves). Platforms tend toward restraint to let content carry; content brands lean toward expression. + +## Common archetypes in this vertical + +The dominant archetypes are **Bold Confident** (Epic Games, Riot, Discord) and **Vibrant Saturated** (Discord with character, Twitch). **Editorial Restrained** appears at the platform-chrome edge (Steam at category level). **Retro Nostalgic** appears at indie-gaming and arcade-revival brands. **Minimal Essentialist** appears at platform-distributor edges (Itch.io). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Discord | Vibrant Saturated with character | Multi-hue brand palette; community-focused; playful chrome | +| Steam | Editorial Restrained at category level | Platform chrome restrained to let games lead; dark mode dominant | +| Twitch | Vibrant Saturated | Saturated purple; live-streaming positioning | +| Epic Games | Bold Confident | Strong brand colors; platform energy | +| Riot Games | Bold Confident | Saturated brand; competitive-gaming positioning | +| Itch.io | Minimal Essentialist | Indie game platform; minimal chrome; lets games carry | +| Spotify (entertainment) | Vibrant Saturated | Saturated green; mood-based personalization | +| Netflix | Bold Confident | Black plus red; content-as-hero; minimal platform chrome | +| HBO Max (Max) | Editorial Restrained leaning Luxe Considered | Premium streaming positioning; restrained type | +| Roblox | Playful Energetic | Multi-color brand; family-friendly positioning | + +## Vertical-specific adaptation notes + +- **Platform versus content distinction**: platform brands (the place where games or shows live) lean toward restraint to avoid competing with content. Content brands (individual games, shows, studios) lean toward expression. +- **Dark mode dominance**: most gaming and entertainment surfaces lean dark-mode-first to support content viewing. +- **Subculture signaling**: gaming brands often signal subculture alignment (esports, indie, MMO, casual mobile). The archetype must extend to subculture-appropriate visual cues. +- **Live and real-time experiences**: many brands in this vertical have real-time surfaces (live streams, multiplayer lobbies) that affect archetype expression. + +## Common archetype evolution + +Gaming brands frequently choose archetypes orthogonal to their content. Discord is Vibrant Saturated despite hosting communities of every register. Steam is Editorial Restrained despite hosting saturated games. The platform chrome makes a brand decision separate from the content's character. + +Mature platforms sometimes pull back ornamentation to let content lead (Netflix's evolution toward minimalist chrome shows this). + +## Vertical anti-patterns + +- **Clinical Trustworthy in gaming**: incompatible; gaming audiences reject clinical framing. +- **Rugged Utilitarian**: works only at simulation-and-mil-sim edges; reads wrong on mainstream gaming. +- **Luxe Considered in mass gaming**: works only at premium subscription tiers (Max, Apple TV Plus); reads wrong on free-to-play and casual. diff --git a/skills/brand-archetype-system/references/by-vertical/16-marketplace.md b/skills/brand-archetype-system/references/by-vertical/16-marketplace.md new file mode 100644 index 0000000..2148be5 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/16-marketplace.md @@ -0,0 +1,43 @@ +# Marketplace + +## Vertical summary + +Brands operating two-sided platforms connecting buyers and sellers across categories: handmade goods, secondhand, niche-expert, livestream commerce, B2B wholesale. Audience values: trust signals, seller quality verification, and category authority. Marketplace brands face a unique brand challenge: the platform brand interacts with hundreds or thousands of seller brands, and the platform must hold an identity that does not compete with seller identities. + +## Common archetypes in this vertical + +The dominant archetypes are **Warm Conversational** (Etsy, Faire in marketing) and **Bold Confident** (StockX, Whatnot). **Editorial Restrained** appears at the niche-expert edge (Reverb). **Vibrant Saturated** appears at the gen-Z commerce edge (Depop). **Documentary Honest** at the artisan-commerce edge (Etsy's seller stories). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Etsy | Warm Conversational with craft emphasis | Handmade marketplace; warm palette; seller-story framing | +| Reverb | Editorial Restrained with niche-expert voice | Musical instruments; type-led; expertise-as-trust | +| Faire | Editorial Restrained | Wholesale marketplace; restrained type; B2B confidence | +| StockX | Bold Confident | Sneakers and streetwear; saturated brand; market-data positioning | +| Whatnot | Bold Confident | Livestream commerce; saturated palette; energy register | +| Depop | Vibrant Saturated | Gen-Z fashion resale; bright multi-hue palette | +| Vinted | Warm Conversational | European resale; cream palette; friendly approach | +| eBay | Bold Confident | Established marketplace; high-energy multi-color brand | +| Mercari | Warm Conversational | Resale marketplace; soft palette; approachable | +| Substack (creator marketplace) | Editorial Restrained | Newsletter marketplace; serif type; creator-economy framing | + +## Vertical-specific adaptation notes + +- **Platform brand versus seller brands**: the marketplace brand must hold an identity that does not compete with seller brands. Restraint often wins; let sellers carry visual energy. +- **Trust signals matter heavily**: ratings, reviews, return policies, seller verification carry brand weight. The archetype must give trust signals appropriate space. +- **Multi-category challenge**: marketplaces frequently span many product categories. The brand must work for fashion, electronics, home goods, and handmade simultaneously. +- **Buyer-side versus seller-side surfaces**: marketplace brands often have parallel surfaces for buyers (consumer-facing) and sellers (creator-or-merchant facing). The archetype must extend coherently to both. + +## Common archetype evolution + +Marketplace brands frequently start in their original archetype and stay. Etsy has stayed Warm Conversational since its early days (with refinements). StockX has stayed Bold Confident since launch. + +Brands that try to switch archetypes (Etsy's brief attempts at more polished marketing in the late 2010s) usually pull back to their original positioning. + +## Vertical anti-patterns + +- **Luxe Considered in mass-market marketplaces**: works only at curated-luxury marketplaces (1stDibs, Sotheby's); reads out-of-place elsewhere. +- **Technical Precise**: works only at B2B infrastructure marketplaces (Faire's developer-tools edge); reads wrong on consumer. +- **Clinical Trustworthy**: incompatible; reads as cold and corporate where marketplaces need community feeling. diff --git a/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md b/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md new file mode 100644 index 0000000..6a1e674 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md @@ -0,0 +1,43 @@ +# Crypto and Web3 + +## Vertical summary + +Brands across crypto exchanges, wallets, NFT platforms, DeFi protocols, and Web3 infrastructure. Audience splits between consumer (Coinbase-tier accessibility) and infrastructure (developer-and-builder-tier precision). The vertical has unusual archetype range because crypto culture spans speculative-energy to cypherpunk-minimal to artist-luxe. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. **Bold Confident** for consumer crypto (Coinbase, OpenSea, Rainbow). **Technical Precise** for protocol and infrastructure (Anchor, Alchemy). **Editorial Restrained** at the writing-and-publishing edge (Mirror). **Luxe Considered** at the NFT-art edge (Foundation, Async Art). **Vibrant Saturated** at the consumer-wallet edge (Rainbow). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Coinbase | Bold Confident with blue | Trust-blue palette; mainstream-consumer positioning | +| OpenSea | Bold Confident | Saturated palette; NFT marketplace energy | +| Mirror | Editorial Restrained | Decentralized publishing; serif-led; restrained confidence | +| Foundation | Luxe Considered | NFT art marketplace; cream palette; curated-gallery feeling | +| Rainbow | Vibrant Saturated | Multi-hue wallet brand; gradient-rich; consumer-friendly | +| Phantom | Bold Confident with purple | Solana wallet; saturated brand; consumer-tilted | +| Uniswap | Bold Confident with Vibrant Saturated | DeFi protocol; pink-and-saturated brand; consumer-DeFi | +| Alchemy | Technical Precise | Web3 infrastructure; developer-facing; cool palette | +| Polygon | Bold Confident | Layer-2 infrastructure; saturated purple; institutional positioning | +| Async Art | Luxe Considered | Programmable art; restrained gallery aesthetic | + +## Vertical-specific adaptation notes + +- **Consumer versus infrastructure split**: consumer brands (Coinbase, Rainbow, Phantom) lean energetic and friendly. Infrastructure brands (Alchemy, Anchor) lean toward Technical Precise. The archetype must match the audience. +- **Trust signals matter**: regulatory framing, audit reports, security signals must accommodate the archetype. Bold Confident makes them inline; Technical Precise gives them dedicated surfaces. +- **Cultural alignment**: crypto culture has subcultures (cypherpunk, DeFi-degen, NFT-collector, builder). Brands must signal which subculture they speak to. +- **Compliance copy**: increasing regulatory pressure (especially post-2024) affects brand voice; the archetype must accommodate disclaimers without breaking. + +## Common archetype evolution + +Crypto brands frequently shift archetype as the regulatory environment matures and as they target broader audiences. Coinbase has moved from more energetic to more institutional over its lifetime. Many crypto brands started Vibrant Saturated (matching crypto culture energy of 2021-2022) and pulled back toward Bold Confident or Editorial Restrained. + +The mature-stage shift is typically: dial back the saturation, add trust signals, lean into typographic restraint without losing the consumer accessibility. + +## Vertical anti-patterns + +- **Warm Conversational in crypto**: works only at extremely consumer-tilted onboarding products; reads wrong on most surfaces. +- **Rugged Utilitarian**: incompatible. +- **Clinical Trustworthy in pure DeFi**: reads as trying to be a bank; works only at the regulated-stablecoin edge. diff --git a/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md b/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md new file mode 100644 index 0000000..d04cc2f --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md @@ -0,0 +1,44 @@ +# Real Estate and Proptech + +## Vertical summary + +Brands across residential real estate platforms, premium real estate, proptech tools, and home-buying products. Audience splits sharply by price point: premium residential real estate leans Luxe Considered universally; mass-market platforms split between Warm Conversational, Bold Confident, and Clinical Trustworthy. The vertical rewards trust signals across every archetype because real estate transactions are high-value, high-friction, and infrequent. + +## Common archetypes in this vertical + +The dominant archetypes are **Luxe Considered** at the premium tier (Compass, Sotheby's International Realty, Pacaso). **Bold Confident** at the disruptor tier (Opendoor, Sundae). **Warm Conversational** at the consumer-information tier (Zillow). **Clinical Trustworthy** at the technology-platform tier (Redfin). **Editorial Restrained** at the proptech-software edge (some commercial real estate platforms). + +## Brand-to-archetype mapping + +| Brand | Archetype | What's distinctive | +|---|---|---| +| Compass | Luxe Considered | Premium residential; serif typography; agent-network positioning | +| Zillow | Warm Conversational at consumer edge | Friendly approachable; muted palette; consumer-information register | +| Redfin | Clinical Trustworthy | Cool palette; technology-platform positioning; agent-as-employee model | +| Opendoor | Bold Confident | Saturated brand; instant-offer disruption framing | +| Sundae | Bold Confident | Saturated brand; off-market-property positioning | +| Pacaso | Luxe Considered | Co-ownership of vacation homes; premium photography; lifestyle framing | +| Sotheby's International Realty | Luxe Considered (extreme) | Pure premium real estate; serif throughout; institutional luxury | +| Cadre | Editorial Restrained | Commercial real estate investment platform; restrained type | +| Knock | Bold Confident | Home-trade-in services; saturated brand | +| Vacasa | Warm Conversational with Documentary Honest | Vacation rental management; real-photography of properties | + +## Vertical-specific adaptation notes + +- **Premium versus mass-market split is sharp**: premium real estate is universally Luxe Considered; mass-market splits into three or four archetypes based on positioning. +- **Photography is critical**: real estate brands depend on excellent property photography. The archetype rides on photo direction. +- **Trust signals across every archetype**: license info, agent credentials, customer reviews, third-party certifications must appear with appropriate weight. Premium archetypes make these understated; consumer archetypes make them prominent. +- **Local versus national**: many real estate brands operate hyper-locally (individual agents and small brokerages). The archetype must extend to local agent-branded surfaces. + +## Common archetype evolution + +Real estate brands frequently stay in their original archetype. Compass has stayed Luxe Considered since launch. Zillow has stayed Warm Conversational. Redfin has stayed Clinical Trustworthy. + +Brands that try to switch archetypes (a mass-market brand attempting to feel premium) usually struggle to convince either audience. Real estate is unusually punishing of inauthentic positioning. + +## Vertical anti-patterns + +- **Vibrant Saturated in real estate**: incompatible; reads as untrustworthy with high-value transactions. +- **Playful Energetic**: incompatible. +- **Rugged Utilitarian**: works only at vacation-property and recreational-land edges; reads wrong on mainstream residential. +- **Technical Precise**: works only at commercial real estate analytics platforms (CoStar tier); reads wrong on consumer. diff --git a/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md b/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md new file mode 100644 index 0000000..0af4a7c --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md @@ -0,0 +1,119 @@ +# Editorial Restrained + +## Aesthetic summary + +Low-saturation, type-led, generous whitespace. Considered rather than performed. The brand earns attention through restraint instead of demanding it through volume. Reads as institutional confidence without stiffness. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (warm but precise, comfortable with first person) +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0F1B2D | Primary text, body, anchors | +| ink-muted | #1F2D44 | Secondary text | +| paper | #FAF9F6 | Warm off-white background | +| paper-soft | #F3F1EC | Card surfaces, subtle elevation | +| accent | #5B8B85 | Single accent for links and key actions | +| accent-muted | #3F6E55 | Hover states, secondary accent applications | +| highlight | #C9A227 | Numeric callouts, display sizes only | +| highlight-body | #8E6E1A | Same hue at body-text contrast (WCAG AA) | +| line | #EDEFF2 | Borders, separators | + +Rationale: +- Ink at #0F1B2D not pure black. Pure black on warm paper feels harsh; navy ink reads as ink-on-paper. +- Paper at #FAF9F6 not pure white. Warm tint signals editorial register versus UI register. +- Accent restricted to one hue. Two-color systems read as institutional; multi-color reads as consumer. +- Highlight restricted to display sizes; the body-contrast variant (#8E6E1A) covers WCAG AA at smaller scales without losing the warm-gold character. + +## Type pairing starter + +- **Display**: IBM Plex Serif (Google Fonts, free). 700 for hero, 600 for sections. +- **Body**: Inter (Google Fonts, free). 400 for prose, 500 for UI labels. +- **Numerics**: JetBrains Mono (Google Fonts, free). 400 to 500 for KPIs and code. + +Size scale (modular, 1.2 ratio anchored at 16px): +- Hero: 56 to 72px serif +- H2: 32 to 40px serif +- H3: 22 to 26px serif +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Mono: 14 to 16px monospace + +Pairing rationale: serif display plus sans body is the classic editorial pairing (NYT, magazines). IBM Plex specifically has open apertures and modest contrast that reads as institutional but modern. JetBrains Mono for numbers communicates precision without being overtly technical. + +## Layout and composition + +- Generous whitespace. Sections separated by 96 to 128px vertical rhythm minimum. +- Single-column hero, content left-aligned, max-width around 720px for prose. +- Asymmetric grids on landing pages: 2-column with deliberate imbalance (40/60 or 60/40) more often than centered or 50/50. +- Density: low. The page should breathe. +- Cards: subtle elevation via 1px line border at line color, no drop shadows. + +## Imagery direction + +- Photography: editorial, low-touched, real environments, natural light. +- Illustration: rare. If used, line-only, single color, technical drawing register. +- Product UI: shown in stylized chrome with branded surfaces; rarely the actual app screenshot. +- Decorative imagery: avoided. Everything earns its place. + +## Voice samples + +- "Built around the question, not against the event stream." +- "Real components, real brand foundations, real working forms." +- "The measurement surface PLG teams actually need." +- "Onboarding metrics live in the cracks between general-purpose tools." +- "Focused, not just smaller." +- "Sample funnel, real benchmarks, your cohort." +- "Pre-built activation funnels. Time-to-first-value benchmarking." + +Cadence: complete sentences. Comma-separated qualifiers more often than dashed asides. Direct claims with built-in qualification. No exclamation marks. Numerals over written numbers. + +## Component pattern descriptions + +**Hero**: Eyebrow (uppercase, accent color, letterspaced 0.16em), then serif headline 56 to 72px, then sans subhead 18px paragraph, then 2 buttons (primary solid ink, secondary outline), optional KPI strip below. + +**Buttons**: Primary is solid ink, white text. Secondary is white surface, ink border 1px, ink text. No gradients. No drop shadows. Hover state shifts opacity to 0.9 or fills the secondary surface. + +**Cards**: Paper-soft background, 1px line border, 24 to 32px internal padding. Numerals top-left in mono. Title in serif. Body in sans. + +**Tables**: Paper-soft header row, line color separators between rows, monospace numerics aligned right. + +## When to pick this + +- B2B brand for a measured, considered audience (PMs, engineers, founders, finance) +- Category is loud and your differentiation is calm +- Product earns attention through depth rather than novelty +- Audience reads documentation and trusts restraint + +## When to avoid + +- Consumer brand for an audience that wants energy and warmth +- Product that needs to feel inviting at first touch +- Category where competitors are already restrained (you will disappear) +- Brand that needs to communicate playfulness or character + +## Adaptation guidance + +When applying this archetype to a specific brief: + +1. **Keep the structure** (whitespace, single-accent, restrained type pairing). Adapt specific values. +2. **Color**: shift accent hue to match emotional direction. Muted teal feels rational; muted plum feels considered; muted moss feels grounded; muted slate feels institutional. +3. **Type**: IBM Plex Serif is a starting point. Substitutes that fit: GT Sectra, Tiempos, Fraunces, Source Serif. +4. **Density**: dial up or down based on audience. Developers tolerate more density; founders prefer more whitespace. +5. **Highlight color**: optional. Brands without a numeric story do not need it. + +Direct copying of all defaults verbatim produces generic Editorial Restrained output. The brief should produce a meaningful variant. + +## Exemplar brands + +Editorial Restrained is exemplified by Linear, Vercel, Stripe Press, Resend, and the fictional Threshold reference build in this catalog. Earlier examples include Pentagram's institutional work and the early Medium publication system. + +These brands share: serif display, sans body, single accent, generous whitespace, editorial photography or stylized product UI, peer-relationship voice. + +The archetype overlaps with Technical Precise (Stripe docs, Sentry); blended brands typically use Editorial Restrained for marketing surfaces and Technical Precise for documentation surfaces. diff --git a/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md b/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md new file mode 100644 index 0000000..8180aea --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md @@ -0,0 +1,122 @@ +# Technical Precise + +## Aesthetic summary + +Monospace prominent in display and numerics. Grid visible in compositions. Data density tolerated and embraced. Dark mode often dominant. Cool palette with high precision feel. The brand communicates that it understands the technical substance of what it is selling, and that its audience does too. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (precise, low-affect, treats the reader as informed) +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Functional + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0A0E1A | Light-mode primary text | +| ink-muted | #1F2937 | Light-mode secondary text | +| paper | #FFFFFF | Light-mode background | +| paper-soft | #F6F8FA | Light-mode card surface | +| surface-dark | #0F1117 | Dark-mode primary background | +| surface-dark-elevated | #161922 | Dark-mode card surface | +| text-dark | #E6E9F2 | Dark-mode primary text | +| text-dark-muted | #9DA4B4 | Dark-mode secondary text | +| accent | #7C5CFF | Saturated single accent (violet shown) | +| accent-muted | #5B3FD6 | Active state | +| signal-success | #16A34A | Positive numeric signal | +| signal-warn | #F59E0B | Caution signal | +| signal-error | #DC2626 | Error signal | +| line | #2A2F3C | Dark-mode line, panel separators | + +Rationale: +- Dark mode is first-class; the palette is built dark-mode primary with light-mode adaptations. +- Single saturated accent (violet, electric blue, lime, or cyan) lets the rest of the palette stay neutral. +- Signal colors are functional, not decorative; reserved for status communication in dashboards and logs. +- Lines visible (#2A2F3C in dark, #E5E7EB in light) to reinforce the grid character. + +## Type pairing starter + +- **Display**: Geist Sans (Vercel, free) or Inter Display. 600 to 700 weight. +- **Body**: Geist Sans or Inter. 400 to 500. +- **Monospace**: Geist Mono or JetBrains Mono. Prominent in display, numerics, code samples, KPIs, badges, and labels. + +Size scale (modular, 1.25 ratio anchored at 15px for higher density): +- Hero: 48 to 64px sans +- Hero-mono: 36 to 48px mono (for technical brands using mono in display) +- H2: 28 to 36px sans +- Body: 15 to 16px sans +- Small: 13px sans +- Code: 14 to 15px mono + +Pairing rationale: Geist (and its mono variant) was designed specifically for technical product interfaces. Inter plus JetBrains Mono is the equivalent if Geist is not available. The mono should appear regularly enough that the reader registers the brand uses it deliberately. + +## Layout and composition + +- Higher density than Editorial Restrained. The reader expects information. +- Grids are visible: hairline borders on cards and tables, monospace coordinates in nav, table-of-contents sidebars. +- Code samples are treated as primary content, not supplementary. +- Hero often pairs a clean headline with a live-looking product surface (dashboard, terminal, code editor). +- Dark mode is the design target; light mode is the adaptation. + +## Imagery direction + +- Photography: rare. When used, abstract or product-context, not people. +- Illustration: technical diagrams, network graphs, architecture maps. Single accent color over neutral background. +- Product UI: shown as real screenshots or near-real chrome. The product surface itself is the brand asset. +- Decorative imagery: minimal. The information density is the visual. + +## Voice samples + +- "Latency p99: 47ms across 12 regions." +- "Idempotent by default. Versioned endpoints. Zero-downtime migrations." +- "Built for the request volume you actually have at 3am." +- "Error budgets, not vibes." +- "Your stack already speaks this protocol." +- "Run it locally. Deploy it globally. Same primitives." +- "Observability that does not require its own observability." + +Cadence: short. Often fragments. Numerals over words. Technical specificity over abstraction. Comfortable with industry vocabulary. + +## Component pattern descriptions + +**Hero**: Often split layout: left side is headline plus sub plus 2 CTAs, right side is a live product surface (terminal, dashboard, code editor). Or full-bleed dark with an oversized mono headline. + +**Buttons**: Primary is solid accent on dark, or solid ink on light. Secondary is bordered. Often a small mono prefix on labels ("$ deploy" pattern). + +**Cards**: Hairline border, dark-elevated background, monospace metadata in the header row, sans body. Often with a small status dot (signal color) in the corner. + +**Tables**: Dense. Hairline rows. Mono numerics, right-aligned. Hover state with a faint accent tint. Sortable columns marked. + +**Code blocks**: First-class. Syntax highlighting palette is part of the brand. Copy button. Language label. + +## When to pick this + +- Developer audience +- Observability, platform, infrastructure, or DX product +- Audience values data density and precise specification +- Brand needs to communicate "we built this, we run it, we understand it" + +## When to avoid + +- Consumer audience that wants warmth +- Product that is not technically substantive (the archetype will read as costume) +- Brand needs to communicate approachability over rigor +- Photography or human imagery is central to the brand story + +## Adaptation guidance + +1. **Accent hue**: violet for product-first brands, electric blue for infrastructure, lime or cyan for AI-adjacent, soft green for sustainability-leaning. +2. **Mono density**: dial up for developer brands (mono in hero, mono in nav, mono in labels) and dial down for prosumer brands wanting only the precision signal. +3. **Dark mode**: required. Skip this archetype if the brand cannot ship a dark mode. +4. **Photography**: if the brand needs human imagery, blend with Editorial Restrained or Warm Conversational instead of forcing it into Technical Precise. +5. **Voice density**: stay specific. Vague claims in this archetype read as worse than vague claims elsewhere, because the visual is promising specificity. + +## Exemplar brands + +Technical Precise is exemplified by Stripe (especially the documentation and developer surfaces), Sentry, Datadog, Vercel, Cursor, and Linear in its most technical surfaces. Adjacent older examples include the early Heroku CLI and the original GitHub UI before its consumer-tilted redesigns. + +These brands share: dark-mode-first, monospace prominent, code as first-class content, saturated single accent, dense tables and grids, low-affect voice. + +The archetype frequently blends with Editorial Restrained at the marketing surface level (Stripe's marketing pages, Vercel's announcements) while keeping the technical surface pure Technical Precise. diff --git a/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md b/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md new file mode 100644 index 0000000..82530ab --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md @@ -0,0 +1,114 @@ +# Warm Conversational + +## Aesthetic summary + +Human imagery, mid-saturation palette with warm undertones, approachable type, second-person voice. The brand reads as a colleague who genuinely wants to help rather than a vendor selling. Friendly without performance; honest without coldness. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational +- **Aesthetic register**: Considered +- **Audience relationship**: Companion +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1F2937 | Primary text | +| ink-muted | #4B5563 | Secondary text | +| paper | #FFFBF5 | Cream background | +| paper-soft | #FAF3E7 | Card surface | +| accent | #D97757 | Warm terracotta primary accent | +| accent-soft | #F3B690 | Tint of accent for backgrounds | +| accent-deep | #A75440 | Active state | +| support-green | #5A8A6E | Sage green secondary | +| support-blue | #5E8FA8 | Dusty blue secondary | +| line | #E8DFCF | Borders, separators on cream | + +Rationale: +- Cream background (not white) is the foundation; it signals warmth before any other element fires. +- Mid-saturation accent (terracotta shown) is warm and human; cooler accents (sage, dusty blue) appear as secondary tones rather than primaries. +- The palette is calibrated mid-saturation throughout; no value is below 35% or above 70% saturation. This is what produces the "considered warmth" reading instead of either pastel or vivid. +- Lines use a warm gray rather than neutral gray to keep coherence with the paper. + +## Type pairing starter + +- **Display**: Hubot Sans or Söhne or GT America. 600 to 700. +- **Body**: Same family for body, 400 to 500. Single-family systems read warmer than serif plus sans pairings. +- **Optional accent type**: a friendly humanist serif (Tiempos Text, Source Serif) for editorial moments inside otherwise sans content. + +Size scale (modular, 1.2 ratio anchored at 17px for comfortable reading): +- Hero: 48 to 64px sans +- H2: 30 to 38px sans +- H3: 22 to 26px sans +- Body: 17 to 19px sans (slightly larger than B2B default) +- Small: 14 to 15px sans + +Pairing rationale: single-family sans systems read warm and consistent. Humanist or geometric-humanist sans (Hubot, Söhne, GT America) have rounder shapes than neo-grotesques like Helvetica, which is what produces the "friendly" reading without sliding into childlike. Body sizes run slightly larger than other archetypes because the reader is expected to actually read. + +## Layout and composition + +- Comfortable density. Not as breathing as Editorial Restrained, not as dense as Technical Precise. +- Sections frequently use full-bleed photography or illustration as scene-setters. +- Hero often pairs a human photo (real customer, real team member) with a friendly headline. +- Generous interior padding inside cards and forms; the page feels welcoming rather than businesslike. +- Curved corners (8 to 16px) on cards and buttons; sharp corners read colder. + +## Imagery direction + +- Photography: real people, varied skin tones and body types, candid rather than posed, natural light, real environments (homes, coffee shops, offices that look lived-in). +- Illustration: custom illustration systems are common (Mailchimp's monkey era, Slack's hands-and-objects era). When used, illustration should have a consistent vocabulary rather than stock-feeling variety. +- Product UI: shown in real photo-context (laptop on a real desk) more often than stylized chrome. +- Stock photography pitfall: this archetype dies on bad stock photo selection. Curate hard or commission custom. + +## Voice samples + +- "Sign up takes about a minute. We will not ask for a credit card." +- "Here is what we tried, what worked, and what did not." +- "You probably do not need a meeting for this. But if you do, we can hop on one." +- "Made for teams who would rather get the work done than configure the tool that does the work." +- "Yes, we send fewer emails than other tools. On purpose." +- "We charge what we charge because that is what it costs to run the thing well." + +Cadence: complete sentences. Comfortable with first and second person. Contractions and hedging are fine; performed informality ("hey friend!") is not. Reads honest, not chummy. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 or 2 CTAs, often paired with a human photo or warm illustration. Background frequently cream (not white). Headline weight is mid-bold (600), not display-heavy. + +**Buttons**: Primary is solid accent, white text, 10 to 16px corner radius. Secondary is bordered or text-only. Hover states use a slight color deepening rather than opacity shift. + +**Cards**: Soft cream surfaces, 12 to 16px radius, generous padding (32 to 40px), shadow at low intensity (0 4px 12px rgba(0,0,0,0.04)). + +**Forms**: Generous field height (48 to 56px). Labels above inputs (not floating). Help text below fields. Pre-fill where possible. + +## When to pick this + +- Prosumer SaaS, team productivity, marketing tools at the consumer-leaning edge +- Brand needs to communicate "we get you" more than "we are best in class" +- Audience values approachability over rigor +- Brand wants to differentiate in a category of cold competitors + +## When to avoid + +- Audience that reads warmth as unserious (most developer infrastructure, most enterprise) +- Brand with limited photography or illustration budget (the archetype dies on bad imagery) +- Brand needs to communicate authority or expertise as the primary signal +- Category is already crowded with warm brands (you will disappear) + +## Adaptation guidance + +1. **Accent hue**: terracotta and warm orange feel grounded; sage green and dusty blue feel calm; coral and peach feel optimistic. Pick one primary based on emotional direction. +2. **Single-family vs paired type**: single-family sans is the default. If the brand needs editorial moments, add a humanist serif as the accent type, not as the body. +3. **Illustration vs photography**: pick one as primary. Brands trying to do both usually do neither well. +4. **Voice**: write honest first, friendly second. Performed friendliness without honest substance reads cheap. +5. **Density**: avoid over-roominess. The archetype tips into "marketing fluff" when the page is too breathing and the content is too thin. + +## Exemplar brands + +Warm Conversational is exemplified by Mailchimp (especially the illustration-driven era), Webflow, Slack, Notion in its marketing surfaces, Loom, Intercom, and Figma. Adjacent examples include Khan Academy and Mailchimp's earlier mascot work. + +These brands share: cream or warm-white surfaces, single-family sans, mid-saturation warm accent, human or custom-illustration imagery, second-person voice, comfortable density. + +The archetype frequently overlaps with Playful Energetic when the illustration system carries character; the difference is that Warm Conversational keeps the illustration in service of communication, while Playful Energetic lets the illustration become the dominant visual. diff --git a/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md b/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md new file mode 100644 index 0000000..f1710a6 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md @@ -0,0 +1,115 @@ +# Bold Confident + +## Aesthetic summary + +High-contrast color (often black plus one saturated accent). Oversized display type used as design element. Direct copy. Strong horizontal grids. The brand walks into the room and says what it is selling without flinching. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (direct, comfortable with first person) +- **Aesthetic register**: Expressive +- **Audience relationship**: Performer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0A0A0A | Near-black primary | +| paper | #FFFFFF | White surface | +| paper-soft | #F2F2F2 | Tinted surface | +| accent | #FF4D2E | Saturated single accent (vibrant orange shown) | +| accent-deep | #C13A20 | Active state | +| support | #18181B | Off-black for layered surfaces | +| line | #1F1F1F | Heavy line color (matches the bold register) | + +Alternative accent picks that fit this archetype (one only): +- Hot pink: #EC2877 +- Lime: #C7F11D +- Electric blue: #2563EB +- Saturated yellow: #FFD400 (use with extreme contrast) + +Rationale: +- Two-tone is the move: high-contrast black-and-white plus one saturated accent. Three or more colors dilute the boldness. +- Pure black (or near-black) and pure white reinforce the contrast register. Off-blacks or warm whites pull the archetype toward Editorial Restrained. +- The accent is loud enough that it has to be deployed sparingly. Used as background for one section, not as button color everywhere. + +## Type pairing starter + +- **Display**: Druk Wide, Söhne Breit, GT Sectra Display, Helvetica Now Display, or PP Editorial New (when leaning expressive editorial). Heavy weight (800 to 900) on display. +- **Body**: Söhne, Inter, or Helvetica Now. Mid-weight (500). + +Size scale (extreme contrast between hero and body): +- Hero: 80 to 140px display (the headline is the hero) +- H2: 48 to 72px display +- H3: 28 to 36px +- Body: 17 to 19px +- Small: 14 to 15px + +Pairing rationale: the archetype is built around extreme type contrast. Hero type runs huge (often 100px or more on desktop); body type is normal. The size ratio itself is the visual signature. Heavy display weights are non-negotiable; light or regular weights produce a different archetype entirely. + +## Layout and composition + +- Horizontal grids dominate. Heroes often full-bleed with the headline as the design element. +- Asymmetric layouts with intentional imbalance: text aligned hard-left, oversized headlines that extend past container edges. +- High contrast section transitions: black section, then white section, then accent section. The page reads as panels. +- Sharp corners more often than rounded. +- Minimal decorative imagery; the type IS the visual. + +## Imagery direction + +- Photography: high-contrast, often desaturated or single-color-tinted, real but stylized. +- Illustration: bold flat illustration when used, single accent color, no gradients. +- Product UI: shown in oversized chrome that mirrors the brand's contrast register. +- Decorative: type-as-image; the headline often becomes the visual. + +## Voice samples + +- "We do not negotiate with hidden fees." +- "Built for the people doing the actual work." +- "This is the version that works. The free trial is the version that works." +- "No setup call. No demo. Just sign up." +- "We charge once. You own the thing." +- "Our competitor's pricing page has a button to talk to sales. Ours has a price." + +Cadence: short sentences. Declarative. Contrasts and oppositions ("not X, just Y"). Comfortable with confrontation. Avoids hedging. + +## Component pattern descriptions + +**Hero**: Oversized headline as the dominant element (80 to 140px). Sub headline below at standard size. 1 to 2 buttons. Often a single bold visual or a horizontal divider in the accent color. + +**Buttons**: Primary is solid ink or accent on white. Often oversized (56 to 72px height) to match the bold register. Square or low-radius corners (0 to 4px). + +**Cards**: Sharp corners, heavy border (2 to 3px) or strong shadow, large internal padding. Often the card itself uses contrast (black card with white text, or accent card with black text). + +**Tables**: Heavy header (black background, white text). Large row height. Bold numerics. + +## When to pick this + +- Launch moments or rebrand moments where the brand needs to reset attention +- Category is full of timid competitors and your brief needs differentiation through volume +- Product confidence is high and the value prop is sharp +- Brand is comfortable being polarizing + +## When to avoid + +- Brand needs to communicate care, gentleness, or expertise-through-restraint +- Audience reads boldness as bro-culture or as insecurity +- Product value is technical and needs space to explain itself +- Brand will be embarrassed by the visual in 18 months (this archetype dates faster than restrained ones) + +## Adaptation guidance + +1. **Accent pick**: hot pink leans consumer, lime leans tech-edgy, electric blue leans fintech, orange leans general-purpose bold, yellow only with extreme contrast discipline. +2. **Display size**: do not pull this back to "reasonable." If the hero is 56px, you have made an Editorial Restrained brand instead. Commit to 100px+ or pick a different archetype. +3. **Voice**: easy to slip into bro-culture. Pull back the swagger by writing honest, not performed. The visual is bold; the voice is direct, not bombastic. +4. **Image strategy**: pick type-as-visual or one strong photo. Mixed imagery dilutes the impact. +5. **Use the contrast**: panel-by-panel section transitions are core. A single-color page is not Bold Confident. + +## Exemplar brands + +Bold Confident is exemplified by Loom (current era), Cash App, Robinhood, Mercury (in its recent rebrand), Notion (in product launches), Linear (in major launches), Cloudflare (consumer edge), and Brex. Adjacent older examples include the original Squarespace launch era and the original Mailchimp redesign. + +These brands share: high-contrast palette, oversized display type as visual element, direct voice, panel-based section transitions, one strong accent. + +The archetype often pairs with Technical Precise on developer-tilted brands (the marketing page is Bold Confident; the product surface is Technical Precise). It also overlaps with Vibrant Saturated when the accent is the brand color rather than a supporting note. diff --git a/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md b/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md new file mode 100644 index 0000000..3accaa3 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md @@ -0,0 +1,114 @@ +# Playful Energetic + +## Aesthetic summary + +Bright multi-color palette. Illustration-led, frequently character-driven. Dynamic, sometimes literally animated. Chunky display type or rounded sans. The brand has a personality, often a recurring character or mascot, and that personality is the primary asset. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Companion +- **Sensory ambition**: Immersive + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1B1B2A | Soft-black text | +| paper | #FFFDF7 | Cream surface | +| paper-soft | #FFF4D6 | Pastel surface tint | +| accent-primary | #58CC02 | High-saturation primary (Duolingo green shown) | +| accent-secondary | #FF4B4B | Bright contrast accent | +| accent-tertiary | #FFC800 | Sunny yellow | +| accent-quaternary | #1CB0F6 | Bright sky blue | +| accent-quinary | #CE82FF | Bright purple | + +Rationale: +- Multi-hue palette is the signature. Single-accent palettes do not produce Playful Energetic. +- High saturation (often above 80%) across the full palette. Pastel-only is a different archetype (Vibrant Saturated pulled toward soft). +- The palette is calibrated so any two colors can sit next to each other without clashing. This is harder than it looks and requires hue and value discipline. +- Soft black for text (not pure black) keeps the warmth of the palette intact. + +## Type pairing starter + +- **Display**: Recoleta, Sofia Pro Black, Pangaia, or a chunky humanist serif. Heavy weight, rounded shapes. +- **Body**: Nunito, Inter, or a rounded humanist sans. 500 to 600. +- **Character lettering**: Many brands in this archetype use custom wordmark lettering for the brand name itself (Duolingo, Mailchimp, Headspace). The custom mark sits outside the type system. + +Size scale (energetic, with playful proportions): +- Hero: 56 to 80px display (heavy weight) +- H2: 32 to 44px display +- H3: 22 to 28px +- Body: 17 to 19px sans (rounded) +- Small: 14 to 15px + +Pairing rationale: rounded shapes communicate friendliness. Heavy weights communicate playfulness over preciousness. The pairing is "chunky and round" rather than "tall and narrow." + +## Layout and composition + +- Generous use of decorative elements (mascot illustrations, sparkles, shapes, patterns). +- Asymmetric layouts; intentional cheerful imbalance. +- Diagonal motion lines, jaunty rotations on key elements (cards rotated 2 to 4 degrees), bouncy interactions on hover. +- Heavy use of card-based sections with playful borders (heavy, often colored borders rather than hairlines). +- Rounded corners are aggressive (16 to 24px); sharp corners feel wrong in this archetype. + +## Imagery direction + +- Illustration: custom illustration system is the brand's primary visual asset. Often character-driven (mascot has a personality and shows up across surfaces). +- Animation: motion design is core. The mascot moves; cards bounce on hover; loading states have personality. +- Photography: rare. When used, candid and bright, never sterile. +- Stock imagery: forbidden. The archetype requires custom illustration capacity. + +## Voice samples + +- "Hi! It is time for your daily lesson." +- "You did the thing. We are very proud." +- "Skip a day, and the streak ends. We are watching." +- "Two minutes today is better than zero minutes today." +- "Surprise! You earned a badge." +- "Your friend just passed you. Are you going to let that stand?" + +Cadence: short, punchy. First and second person. Comfortable with exclamation marks (but not abuse). Frequent direct address. Humor as a primary tool. Occasional knowing winks at the reader. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 CTA, paired with a large illustration or animated mascot. The illustration is roughly equal weight to the headline rather than supplementary. + +**Buttons**: Heavily rounded (12 to 20px radius). Often with a 2 to 4px solid bottom border in a darker shade (the "neumorphic toy button" pattern). Bouncy hover animations. + +**Cards**: 16 to 24px radius, soft drop shadows, often slightly rotated. Sometimes with character illustrations integrated into the card itself. + +**Forms**: Inputs are oversized, friendly, with playful focus states. Validation errors are gentle ("Hmm, that does not look right" rather than "Invalid input"). + +**Loading states**: have personality. The mascot waves, bounces, makes a face. Default spinners are missed opportunities in this archetype. + +## When to pick this + +- Consumer apps targeting habit formation, learning, or wellness +- B2B brands intentionally breaking category convention with humor +- Audience appreciates personality over precision +- Brand has illustration budget and willingness to build a character system + +## When to avoid + +- Brand has no illustration budget (this archetype dies on poor illustration) +- Audience reads playfulness as unserious (most enterprise, most developer tools) +- Brand is selling to risk-averse buyers (finance, health, B2B procurement) +- Brand is in a category where competitors are already playful (you will not differentiate) + +## Adaptation guidance + +1. **Character commitment**: decide early whether the brand has a mascot. Mascot brands need ongoing illustration. Mascot-less playful brands rely on pattern and color systems. +2. **Palette discipline**: defining 4 to 6 saturated hues that compose together is the hardest part. Spend real time here; the rest of the archetype is downstream. +3. **Motion**: the archetype needs motion to feel right in product. Static-only execution reads as toy-without-charm. +4. **Voice**: write to one specific reader, not "users." The archetype falls apart when the voice tries to be funny without commitment. +5. **Restraint**: even Playful Energetic needs editorial moments. Pages that are 100% playful all the way through exhaust the reader. + +## Exemplar brands + +Playful Energetic is exemplified by Duolingo (the canonical example, with a full character system), Mailchimp in its monkey-mascot era, Headspace, Asana classic era, Liquid Death (visual side), Ben and Jerry's, and MoonPay. Adjacent examples include the Trello mascot era and the original Slackbot personality. + +These brands share: multi-hue saturated palette, custom illustration as primary asset, second-person voice with personality, heavy use of motion, rounded everything. + +The archetype overlaps with Warm Conversational when the illustration is friendly but not character-driven; the difference is that Playful Energetic lets the personality become the brand, while Warm Conversational keeps the human relationship in the foreground. diff --git a/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md b/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md new file mode 100644 index 0000000..d97188b --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md @@ -0,0 +1,112 @@ +# Luxe Considered + +## Aesthetic summary + +Serif-led across display and body. Extreme whitespace. Restrained monochromatic palette plus one premium accent. Photography is editorial-grade. Voice is sparse and confident. The brand communicates premium not by saying premium but by behaving premium: in pacing, in spacing, in what it omits. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (formal but not stiff) +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Theatrical + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1A1614 | Warm near-black | +| ink-soft | #3A332E | Secondary text | +| paper | #F5F1EA | Cream off-white background | +| paper-warm | #EDE6D9 | Warmer cream surface | +| accent | #5C2A26 | Deep oxblood (alternative: forest #2D4A38, charcoal navy #1F2A40, champagne #C3A87C) | +| accent-soft | #8B4843 | Active states | +| line | #D9D0BC | Warm beige border | + +Rationale: +- Cream and warm-neutral palette is the foundation. Pure white feels cheap in this archetype; cool grays feel corporate. Warmth is the premium signal. +- Single deep accent (oxblood, forest, navy, champagne, deep emerald). Saturation is restrained; the depth of value carries the premium feel. +- No bright colors. Even subtle saturation reads as cheap in this archetype. +- Line color matches paper-warm; lines should be visible but not strong. + +## Type pairing starter + +- **Display**: Tiempos Headline, GT Super, Reckless, Reforma, or Saol Display. Light to regular weight (300 to 400). +- **Body**: Tiempos Text, GT Super Text, or Source Serif. Light weight (300 to 400) at comfortable reading size. +- **Optional sans**: Söhne or GT America at low weight (300) for UI labels and metadata only. + +Size scale (editorial proportions, smaller hero than Bold Confident, larger body than Technical Precise): +- Hero: 48 to 64px serif (light weight) +- H2: 32 to 42px serif +- H3: 22 to 26px serif +- Body: 18 to 20px serif (light weight, comfortable line height) +- Small: 14 to 15px sans + +Pairing rationale: editorial serifs throughout produce the "magazine" feeling. Light weights communicate confidence without aggression. The pairing is rare in B2B (which mostly uses serif display plus sans body) and that rarity is part of the premium signal. + +## Layout and composition + +- Extreme whitespace. Sections separated by 144 to 200px vertical rhythm. +- Often centered or left-aligned with massive horizontal margins on desktop (max content width can run 580 to 720px even on wide screens). +- Asymmetric compositions where the imbalance is intentional and editorial (a 70/30 split with text against a single dominant photograph). +- Minimal UI chrome. Buttons are often text-only with underlines, or thin-bordered, or absent entirely (the call to action is a single line of body copy with a link). +- Page transitions are slow and deliberate. Animations cross-fade rather than slide. + +## Imagery direction + +- Photography: editorial-grade, professionally lit, deliberately styled. Natural light is fine but composition is intentional. Real product, real environment, but elevated. +- Photography is large. Hero images are full-bleed or near-it. The image carries the page. +- Illustration: rare. When used, line-only, sometimes hand-drawn or engraved-feeling. +- Decorative imagery: none. The composition is the visual. +- This archetype requires real photography or excellent stock curation. Bad photo direction kills it instantly. + +## Voice samples + +- "Made from cashmere. From goats that live in places we visit." +- "One garment, one decision." +- "We do not chase trends. We do not need to." +- "Built in 1923. Refined since." +- "If it is not in this collection, it is because it was not ready." +- "The thing we changed was the thread." + +Cadence: short, often fragments. First-person plural ("we") more often than first-person singular. Comfortable with silence. Avoids superlatives ("the best," "the most"); the visual communicates premium without verbal claim. Numbers used sparingly, with deliberate weight when they appear. + +## Component pattern descriptions + +**Hero**: Single full-bleed photograph or a small serif headline against generous whitespace. No subhead. No CTAs in the visible hero region; the page expects the reader to scroll. + +**Buttons**: Often text-only with a serif underline, or thin-bordered with serif label. Solid buttons exist but are rare and reserved for primary purchase moments. Padding is generous (16 to 20px vertical). + +**Cards**: Often no card chrome at all; product is shown on a tinted surface with serif type alongside. When cards exist, they are bordered (1px line color) rather than shadowed, with sharp or low-radius corners (0 to 4px). + +**Navigation**: Minimal. Often horizontally centered with wide letter spacing. Logo small. The brand does not announce itself loudly. + +## When to pick this + +- Luxury or premium-priced products (above 50 dollars consumer, premium-tier B2B) +- Hospitality, fashion, beauty at price points where the visual must signal value +- Audience explicitly buys premium and is reassured by understated execution +- Brand has the production budget for premium photography + +## When to avoid + +- Brand is competing on price or accessibility +- Audience reads restraint as unfriendly +- Brand has no photography budget (the archetype dies immediately) +- Product is not actually premium (the visual will read as costume) + +## Adaptation guidance + +1. **Accent depth**: oxblood reads heritage, forest reads sustainability, deep navy reads institutional, champagne reads contemporary luxury. Pick based on brand position. +2. **Photography commitment**: this is a photography archetype before it is a type archetype. Lock photography direction first. +3. **Type weight discipline**: light weights (300 to 400) only. Bold serif display pulls the archetype toward Bold Confident. +4. **CTA restraint**: resist adding obvious buy buttons in hero positions. The archetype expects the reader to discover, not be sold to. +5. **Sans usage**: keep sans confined to UI labels and metadata. Sans body copy breaks the archetype. + +## Exemplar brands + +Luxe Considered is exemplified by Aesop, Aritzia, Reformation, La Marzocco, Loro Piana, Aman, Bottega Veneta digital, and Stripe Press (in the book design surface). Adjacent examples include the Apple mid-2010s premium product pages, Squarespace's recent rebrands, and the original Goop. + +These brands share: cream and neutral palette, serif-throughout type system, generous whitespace, editorial photography, sparse voice, premium pricing. + +The archetype overlaps with Editorial Restrained (which is the B2B-tilted cousin) and Minimal Essentialist (which strips out the serif entirely). The key difference: Luxe Considered uses the serif and warmth to signal premium; Minimal Essentialist uses absence of ornament to signal premium; Editorial Restrained uses considered ornament to signal trust. diff --git a/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md b/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md new file mode 100644 index 0000000..c3bac14 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md @@ -0,0 +1,115 @@ +# Clinical Trustworthy + +## Aesthetic summary + +Cool palette (blue, teal, soft greens) with optional warm accent for humanity. Sans-serif throughout. Clean compositions. Medical or financial register. Photography of products and clinical environments, occasionally real hands and real people in calm contexts. The brand communicates "trust us with something important" without sliding into cold or pharmaceutical. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional (calm, knowledgeable, low-affect) +- **Aesthetic register**: Considered +- **Audience relationship**: Authority +- **Sensory ambition**: Functional + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #0F2540 | Deep navy primary | +| ink-soft | #344C68 | Secondary text | +| paper | #FFFFFF | White surface | +| paper-soft | #F4F8FB | Cool tinted surface | +| accent-primary | #2D7FB8 | Trust blue | +| accent-secondary | #4CA8A0 | Soft teal | +| warm-tone | #F4B69B | Optional peach warm accent for humanity | +| signal-success | #2F8F5F | Calm success green | +| line | #DAE3EC | Cool gray border | + +Rationale: +- Cool palette communicates calm authority. Blues and teals are the trust signals; warm tones are optional humanizers, not primary brand colors. +- Trust blue (#2D7FB8) is calibrated to read confident without sliding into corporate cold. Bluer (toward #1976D2) reads more pharmaceutical; teal-shifted reads more wellness. +- The optional warm accent (peach, soft coral) is the single move that distinguishes contemporary Clinical Trustworthy from sterile pharma aesthetic. Without it, the brand reads dated. +- White surfaces. Off-whites and creams pull the archetype toward warmth and away from clinical. + +## Type pairing starter + +- **Display**: Avenir Next, Circular, Söhne, or GT America. 500 to 700 weight. +- **Body**: Same family, 400 to 500. Or paired with a soft humanist body (Inter, Source Sans). +- **Optional accent serif**: A clean serif (Source Serif, Tiempos Text) used sparingly for editorial moments or testimonials. + +Size scale (calm, generous, accessible): +- Hero: 48 to 60px sans +- H2: 30 to 38px sans +- H3: 22 to 24px sans +- Body: 17 to 19px sans (accessible default; this archetype frequently serves older audiences) +- Small: 14 to 15px + +Pairing rationale: geometric sans-serif communicates clinical without medical-sterile. Circular and Avenir specifically have open shapes that read calm rather than clinical. Body sizes run slightly larger because the audience may include older readers and the brand should not require strain. + +## Layout and composition + +- Comfortable density; not as dense as Technical Precise, not as breathing as Luxe Considered. +- Generous internal padding inside cards and forms. Trust is communicated partly through "we are not hurrying you." +- Hero often pairs a clean headline with a calm photograph (a real hand holding a product, a calm clinical environment, a portrait of a doctor or pharmacist). +- Comfortable line lengths (60 to 80 characters per line) and generous line height (1.6 to 1.8). +- Soft drop shadows on cards (gentle elevation, not floating). Rounded corners at moderate radius (8 to 12px). + +## Imagery direction + +- Photography: real hands, real products in real environments. Calm lighting (often natural). Real people who look like the audience. +- Product packaging: shown clearly, frequently against soft tinted backgrounds. +- Illustration: rare; when used, technical diagrams of how something works (a calm anatomical illustration, a process flow with annotations). +- Avoid: aggressive close-ups of medical procedures, stock photos of clinicians in lab coats with crossed arms, hands-only-on-keyboard generic stock. + +## Voice samples + +- "Reviewed by licensed clinicians." +- "Effective ingredients at evidence-backed doses." +- "Same medication. Less hassle." +- "Your doctor will see this report. So will you." +- "We do not bill you for what we do not provide." +- "If it is not safe for you, we will tell you." + +Cadence: complete sentences. Comfortable with first and second person. Calm, qualified, specific. Numbers used carefully (specific doses, specific time-to-response). Avoids superlatives. Compliance-aware writing without being legal-coded. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus 1 to 2 CTAs, paired with a calm photograph. Trust signals (clinician endorsements, FDA mentions, peer-reviewed citations) appear above the fold but understated. + +**Buttons**: Primary is solid trust-blue or solid ink-navy, white text, 8 to 12px corner radius. Secondary is bordered. Hover states use a slight darkening rather than opacity shift. + +**Cards**: White or paper-soft surface, 8 to 12px radius, gentle shadow (0 2px 8px rgba(15,37,64,0.06)). Generous internal padding (32 to 40px). Trust signals (clinician credentials, certification marks) frequently appear in cards. + +**Forms**: Generous field height (48 to 56px). Labels above inputs. Help text below explaining why each piece of information is needed (trust signal: we explain why we ask). + +**Trust strip**: Common pattern. Logo strip of certifications, regulatory bodies, peer-reviewed citations, or major employers using the product. + +## When to pick this + +- Telehealth, digital health platforms +- Fintech, especially at the trust-needing edge (banking, insurance, investments for older audiences) +- Insurance, retirement, anything where the conversion driver is "trust us with this" +- Health-finance intersection (HSA, healthcare benefits, prescription savings) + +## When to avoid + +- Audience is young and reads clinical as boring or institutional +- Brand needs to communicate energy or excitement +- Category is already dominated by clinical-trustworthy brands (you will disappear) +- Product is not actually substantive enough to support the trust register (the visual will read as costume) + +## Adaptation guidance + +1. **Cool to warm balance**: pure clinical cool reads pharmaceutical. The optional warm accent (peach, soft coral, butter yellow) is what distinguishes contemporary from dated. +2. **Photography**: real hands and real environments are the move. Stock photos of "doctor with arms crossed" date the brand immediately. +3. **Voice density**: write specific. Vague claims in a clinical archetype read as worse than vague claims in a playful one, because the visual is promising specificity. +4. **Trust signals**: dedicate space to credentials, certifications, citations. Hide them and the archetype is half-built. +5. **Density**: keep it comfortable. Both too dense and too breathing read as untrustworthy in this archetype. + +## Exemplar brands + +Clinical Trustworthy is exemplified by Hims, Ro, Care/of, Cerebral, Mercury (in finance-trust context), and Stripe (in payment-trust context). Older or adjacent examples include early One Medical, the original Headspace landing surfaces before they leaned playful, and the original Robinhood when it was selling trust over excitement. + +These brands share: cool palette with optional warm humanizer, geometric or humanist sans throughout, real-hand photography, calm voice with specific evidence, generous form fields with help text. + +The archetype frequently splits brands by surface: Clinical Trustworthy for the marketing and conversion surface, with Warm Conversational notes in customer support and post-purchase. The hand-off matters: trust converts, warmth retains. diff --git a/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md b/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md new file mode 100644 index 0000000..6690a5f --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md @@ -0,0 +1,115 @@ +# Rugged Utilitarian + +## Aesthetic summary + +Earth tones (clay, olive, charcoal, raw paper). Workwear-influenced type (slab serifs, condensed sans, stencil). Photography of real conditions: outdoor, working, lived-in. Voice is direct and unadorned. The brand reads as built for use rather than for show, and the visual restraint communicates that the product earns its place through function. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational (plain, direct, working-class register without affectation) +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #2C2A26 | Charcoal primary | +| paper | #F0EAD8 | Raw paper background | +| paper-soft | #E2DAC2 | Tinted surface | +| accent-clay | #B8543B | Clay red primary | +| accent-olive | #5C6B3D | Olive green secondary | +| accent-sand | #C29A60 | Warm sand tertiary | +| accent-charcoal | #2C2A26 | Heavy charcoal (alternative primary) | +| line | #A89B7F | Warm tan border | + +Rationale: +- Earth tones throughout. The palette is derived from natural pigments: oxide reds, military olives, sun-bleached tans, deep charcoals. +- Saturation is low to medium; nothing in the palette exceeds 60% saturation. Higher saturation pulls toward Bold Confident or Vibrant Saturated. +- The palette reads as outdoor and used. Pure white feels wrong; cool grays feel wrong. Warmth and weight are signature. +- Primary color is often the clay red or charcoal; olive functions as a secondary. The reverse also works. + +## Type pairing starter + +- **Display**: Druk Condensed, Bebas Neue, Roboto Slab, or a workwear-influenced slab (United Sans Slab, Sentinel). Heavy weight, condensed proportions. +- **Body**: Inter, Söhne, or a clean humanist sans. 400 to 500. +- **Optional accent type**: stencil or workshop-influenced display for product callouts and signage moments. + +Size scale (utilitarian, less extreme than Bold Confident): +- Hero: 56 to 80px display +- H2: 32 to 44px display +- H3: 22 to 26px sans +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Numeric mono: 14 to 16px (for spec sheets) + +Pairing rationale: condensed display type feels like signage on industrial equipment, on workwear labels, on shipping crates. Slab serifs feel like surveyor stamps and field guides. Clean humanist sans body keeps the page legible without dressing it up. + +## Layout and composition + +- Functional density. Information shown without softening. +- Heavy use of horizontal rules and labeled sections (the page reads like a spec sheet or field manual). +- Photography is large and full-bleed; the image carries the page. +- Cards are bordered (1 to 2px) rather than shadowed. Corners are sharp or low-radius (0 to 4px). +- Type often allCAPS for labels and section headers (reinforcing the signage register). + +## Imagery direction + +- Photography: real conditions. Real users in real environments. Dirt, sweat, weather, work. Not staged. Natural light dominant; flash photography rare. +- Photography subjects: products in use rather than products on white. The brand wants to show what the product looks like after a season of work, not what it looks like in a studio. +- Illustration: technical diagrams, exploded views, blueprints. Functional rather than decorative. +- Forbidden: pristine product-on-white shots (those belong to Minimal Essentialist or Luxe Considered), happy-family-lifestyle shots (those belong to Warm Conversational). + +## Voice samples + +- "Built to outlast you." +- "If it breaks, send it back. We will fix it." +- "Designed in Bozeman. Tested where it gets cold." +- "We made it heavier on purpose." +- "Spend it on the gear. Save it on the brand." +- "Lifetime guarantee. Read that again." + +Cadence: short. Direct. First-person plural ("we") when the brand speaks. Comfortable with imperative voice. No marketing jargon, no superlatives, no exclamation marks. Honest specifications over emotional appeals. + +## Component pattern descriptions + +**Hero**: Photograph (full-bleed, real-conditions) with overlaid type, or split layout with text left and photograph right. Headline in display, often condensed or slab. Buttons are direct. + +**Buttons**: Primary is solid charcoal or clay, white or cream text, sharp or low-radius corners (0 to 4px). Heavy and substantial; never floaty. Often labeled in all caps or with stencil-style lettering. + +**Cards**: Bordered (1 to 2px line), low-radius, generous internal padding. Often with a labeled header strip (uppercase, condensed) that reads like a product tag. + +**Tables**: Specification-sheet feel. Labeled rows. Mono numerics. Heavy horizontal rules between sections. + +**Product detail**: Honest. Materials listed. Construction methods explained. The reader is expected to care about how it is made. + +## When to pick this + +- Outdoor, gear, work-tool products +- Brands where durability and utility are the genuine value proposition +- Audience values function over fashion +- Brand has authentic claim to ruggedness (the brand actually serves people doing the work) + +## When to avoid + +- Brand is not actually utilitarian (the archetype reads as costume when applied to delicate products) +- Audience reads ruggedness as bro-culture or as anti-intellectual +- Brand needs to communicate softness, care, or gentleness +- Brand has no claim to outdoor or work-tool authenticity + +## Adaptation guidance + +1. **Authenticity test**: if the brand cannot show real photography of real use, this archetype is wrong. Switch to Documentary Honest if real photography is feasible at a different intensity. +2. **Palette pick**: clay-and-olive feels heritage outdoor (REI, Filson register). Charcoal-and-sand feels industrial workwear (Carhartt, Dickies register). Pick based on category position. +3. **Type weight**: heavy is non-negotiable. Light or regular weights pull the archetype toward Editorial Restrained. +4. **Voice**: avoid performed toughness ("BUILT FOR THE GRIND"). Real Rugged Utilitarian voice is matter-of-fact, not bombastic. +5. **Specification depth**: dedicate page real estate to materials, construction, warranty, repair policy. These are the trust signals. + +## Exemplar brands + +Rugged Utilitarian is exemplified by Patagonia, Carhartt, Yeti, Filson, Snow Peak, Best Made Co (historical), Topo Designs, REI in its product detail surfaces, Stanley (recently), and Hemlock Goods. Adjacent examples include Tom Bihn and Goruck. + +These brands share: earth-tone palette, condensed display or slab serif, real-conditions photography, plainspoken voice, specification depth, lifetime guarantee or repair offering. + +The archetype overlaps with Documentary Honest when photography is the dominant visual; the difference is that Rugged Utilitarian has explicit utility framing (this is for working) while Documentary Honest is about authentic representation more broadly (this is what real life looks like). diff --git a/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md b/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md new file mode 100644 index 0000000..72a07e7 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md @@ -0,0 +1,136 @@ +# Retro Nostalgic + +## Aesthetic summary + +Period-specific palette and type. Intentional vintage reference to a specific era (70s, 80s, 90s, or earlier). Often uses textured or grainy compositions. Voice references the era in cadence or vocabulary. The brand asks the audience to associate it with a felt period rather than with a category, and that association does most of the differentiation work. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Companion +- **Sensory ambition**: Theatrical + +## Color palette starter + +Three era-keyed palette options. Pick ONE era; do not blend. + +**70s palette** (warm, earthy, optimistic): + +| Token | Hex | Role | +|---|---|---| +| ink | #2A1810 | Deep brown primary | +| paper | #F4EAD0 | Cream ground | +| accent-orange | #D2602B | Burnt orange | +| accent-avocado | #6A7A3A | Avocado green | +| accent-mustard | #D4A02E | Harvest gold | +| accent-rust | #8E3F1E | Deep rust | + +**80s palette** (neon, geometric, bold): + +| Token | Hex | Role | +|---|---|---| +| ink | #0D0D2A | Deep navy primary | +| paper | #FAF5EF | Cream surface | +| accent-pink | #FF2D87 | Hot pink | +| accent-cyan | #18C2D9 | Electric cyan | +| accent-yellow | #FFD30F | Saturated yellow | +| accent-purple | #6A2EB8 | Bold purple | + +**90s palette** (muted, grunge-edged, prosumer): + +| Token | Hex | Role | +|---|---|---| +| ink | #1F1A14 | Warm dark brown | +| paper | #E8DEC8 | Aged cream | +| accent-rust | #9C4B2E | Muted rust | +| accent-teal | #3E7575 | Faded teal | +| accent-yellow | #C49A35 | Aged mustard | +| accent-purple | #654273 | Muted purple | + +Rationale: +- Each era has a recognizable palette signature. Mixed-era palettes read confused; the audience cannot place the reference. +- The 70s palette is warm and earth-toned, optimistic but not bright. The 80s palette is neon and geometric. The 90s palette is muted, with deliberate aged warmth. +- Pick the era based on the audience's nostalgia moment: 70s for late-30s and older, 80s for late-30s to mid-40s, 90s for late-20s to mid-30s, early 00s for current 20-somethings. + +## Type pairing starter + +Era-keyed type pairings. Pick ONE era. + +- **70s**: Cooper Black or VAG Rounded or ITC Bauhaus (display); Cooper or Avenir (body). +- **80s**: Eurostile, Avant Garde, or Compacta (display); a clean geometric sans (Avenir, Futura) for body. +- **90s**: Trade Gothic, a worn grunge serif (Bureau Grot, Knockout), or a digital-feeling sans (Eurostile) for display; classic sans for body. + +Size scale (varies by era, but generally expressive): +- Hero: 56 to 96px display +- H2: 36 to 48px display +- Body: 16 to 18px sans + +Pairing rationale: type is the era signature. Cooper Black is 70s consumer; Eurostile is 80s tech-future; Trade Gothic worn is 90s grunge. The reader recognizes the era through the type before recognizing it through the color. + +## Layout and composition + +- Era-specific composition styles. 70s leans toward soft asymmetric blocks and groovy curves. 80s leans toward hard geometric grids, oversized type, and Memphis-influenced shapes. 90s leans toward grunge collage, intentional rough edges, and zine-influenced layouts. +- Textures matter: grain, scan lines, paper-aged effects, halftone. Pure digital flat surfaces fight the archetype. +- Iconography is period-keyed: hand-drawn for 70s, geometric for 80s, photocopied-feeling for 90s. + +## Imagery direction + +- Era-keyed photography: warm-tinted and grainy for 70s, neon-lit and high-contrast for 80s, muted and slightly desaturated for 90s. +- Often pairs modern product photography with period-accurate styling (the product is contemporary, but the styling and framing reference the era). +- Pattern: era-accurate decorative elements (sunbursts, stripes, Memphis shapes, halftone dots) are common. + +## Voice samples + +(80s example for an energy drink brand) +- "Soda for people who remember what soda was." +- "From the era when caffeine had personality." +- "Yes, it tastes like that on purpose." +- "Made with cane sugar. Like before." + +(70s example for a wellness brand) +- "Roots, herbs, and a generally chill outlook." +- "Wellness from when wellness was just called feeling good." +- "Brewed the long way. Drunk the slow way." + +Cadence: era-keyed. 70s reads warm and unhurried. 80s reads punchy and confident. 90s reads ironic and self-aware. The voice should evoke the era without quoting it directly. + +## Component pattern descriptions + +**Hero**: Often centered with oversized era-keyed display type, paired with era-accurate decorative elements (sunburst, Memphis shapes, halftone, scan lines). Background frequently textured. + +**Buttons**: Era-keyed. 70s buttons are rounded and warm. 80s buttons are geometric and high-contrast. 90s buttons are flat with rough edges or grunge texture. + +**Cards**: Often with era-specific borders (chunky 70s borders, neon 80s outlines, distressed 90s edges). Background textures common. + +**Patterns**: Era-keyed pattern systems are common (gingham, paisley, geometric, Memphis, halftone). Used as section backgrounds, packaging, and brand accents. + +## When to pick this + +- F&B challenger brands in commoditized categories (soda, water, snacks) +- Lifestyle brands with a clear era-of-inspiration +- Brands wanting to differentiate in categories crowded with contemporary minimalist competitors +- Brand has clear position on which era and why + +## When to avoid + +- Brand has no genuine connection to the era (the archetype reads as costume) +- Brand needs to communicate forward-looking innovation +- Audience reads the chosen era as embarrassing or dated rather than nostalgic +- Brand cannot commit to the era at production cost (this archetype requires real photography styling and packaging design) + +## Adaptation guidance + +1. **Era commitment**: pick one era and commit. 70s plus 80s blend reads as confused; the audience cannot place the reference. +2. **Texture investment**: this archetype requires real textures (grain, halftone, paper aging). Flat digital versions read as contemporary-with-retro-fonts rather than genuinely retro. +3. **Voice**: avoid direct era quotation ("groovy," "rad," "totally tubular"). The voice should feel like the era, not parody it. +4. **Modern functionality**: the archetype is visual reference, not functional regression. The website should still work well in 2026; the visual reference is decorative. +5. **Photography**: era-styled photography is expensive. If budget is limited, lean harder into pattern and type as era carriers. + +## Exemplar brands + +Retro Nostalgic is exemplified by Olipop (70s wellness lean), Liquid Death (80s metal lean), Poppi (90s lean), Recess (70s wellness), Athletic Brewing (early 1900s heritage lean), Magic Spoon (90s cereal lean), and Olly (70s wellness lean). Adjacent examples include Brooklyn Brewery (heritage industrial), Hoxton Hotels (period-specific by property), and Howler Brothers. + +These brands share: era-keyed palette and type, period-specific decorative elements, texture-rich compositions, era-aware voice, packaging design that reads as the period. + +The archetype frequently anchors F&B challenger brands; the era pick is the differentiation strategy within a crowded category. Olipop and Poppi are both in the gut-health soda space; they differentiate primarily through 70s versus 90s era reference. diff --git a/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md b/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md new file mode 100644 index 0000000..7bcd522 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md @@ -0,0 +1,111 @@ +# Minimal Essentialist + +## Aesthetic summary + +Black, white, single accent maximum. Sans-serif only. Extreme whitespace. Type-led but at smaller scales than Luxe Considered. Compositions almost sparse to the point of empty. Voice is short and declarative. The brand earns attention by removing rather than adding, and the absence of ornament itself becomes the brand signal. + +## Position on the 4 creative-direction axes + +- **Tone register**: Professional +- **Aesthetic register**: Restrained +- **Audience relationship**: Authority +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #000000 | True black primary | +| paper | #FFFFFF | Pure white | +| paper-soft | #F7F7F7 | Tinted gray surface (only when needed) | +| muted | #888888 | Mid-gray for secondary text | +| line | #E5E5E5 | Hairline separator | +| accent | #FF3B30 | Optional single accent (red shown; reserve for one use case) | + +Rationale: +- Pure black and pure white. Off-black or off-white pulls the archetype toward Luxe Considered or Editorial Restrained. +- Single accent if any. Many Minimal Essentialist brands use no accent at all. When used, the accent appears once per page (a single CTA, a single error state, a single quote). +- Gray is the secondary palette. Mid-gray for secondary text, hairline gray for borders. +- No gradients. No tints beyond the gray scale. No color washes. + +## Type pairing starter + +- **Display and body**: One sans-serif family across all surfaces. Helvetica Now, Söhne, GT America, Inter, or Suisse Int'l. Multiple weights (300 to 700) carry the hierarchy. +- **Optional secondary**: Sometimes the same family in a tightly-set condensed cut for labels or navigation. + +Size scale (modest contrast, hierarchy through weight more than size): +- Hero: 40 to 56px sans (smaller than Bold Confident; the hero does not need to shout) +- H2: 28 to 36px sans +- H3: 20 to 24px sans +- Body: 16 to 17px sans +- Small: 13 to 14px sans + +Pairing rationale: one family across the system reinforces the discipline. Hierarchy is communicated through weight, size, and color rather than through type pairing. Neo-grotesque sans (Helvetica, Söhne, Suisse) feel pure; geometric sans (Avenir, Circular) feel slightly warmer; humanist sans (GT America, Inter) feel slightly friendlier. Pick based on the temperature you want. + +## Layout and composition + +- Extreme whitespace, but at smaller scale than Luxe Considered. The page reads as efficient rather than ceremonial. +- Often a strict grid: 12-column desktop with deliberate column spans. Asymmetry less frequent than in Editorial Restrained. +- Type-led: type sits in space rather than being framed by photography or color blocks. +- Cards are rare. Content sits directly on the page surface with hairline separators rather than card containers. +- Sharp corners (0 to 2px). Curves feel wrong in this archetype. + +## Imagery direction + +- Photography: product on white. Studio-lit. Considered. No styling beyond the product itself. +- People photography: rare. When used, portraits against neutral backgrounds, minimal styling. +- Illustration: extremely rare. Diagrams in line-only black-on-white if at all. +- Decorative imagery: none. The whitespace is the decoration. + +## Voice samples + +- "One mattress. One price." +- "We make the product. We tell you how it works. You decide." +- "The product is described accurately on the product page." +- "Returns within 100 days. No questions." +- "There is no enterprise tier." +- "The cheapest plan is the only plan." + +Cadence: very short. Declarative. First-person plural ("we") common. Numbers when relevant; otherwise sparse. The voice is honest to the point of dryness. No salesmanship, no superlatives, no hedging. + +## Component pattern descriptions + +**Hero**: Headline plus subhead plus single CTA. Often centered or hard left-aligned. Sometimes paired with a single product photograph against white; often with no imagery at all. + +**Buttons**: Solid black, white text, or solid white with black border. Sharp corners or 2 to 4px radius. Single CTA per section. + +**Cards**: Rare. When present: hairline border (1px line gray), no shadow, sharp corners, minimal internal styling. + +**Tables**: Hairline rows. Sans body throughout (no mono). Left-aligned text, right-aligned numerics. + +**Navigation**: Minimal. Logo (often wordmark only), a small number of nav items, a single CTA. No mega-menus, no drawer animations, no decorative chrome. + +## When to pick this + +- Brand wants to communicate timelessness or rigor +- Product is design-focused and the audience appreciates restraint as a value signal +- Brand is competing in a category where every competitor is ornamented; restraint is the differentiator +- Brand can defend the discipline (saying no to internal requests to add color, illustration, ornament) + +## When to avoid + +- Brand has rich content that benefits from visual organization (the archetype's lack of cards and color makes dense content hard to scan) +- Audience reads minimalism as cold or unwelcoming +- Brand needs to communicate warmth, personality, or specific human values +- Brand will eventually be tempted to add ornament (better to start in a more flexible archetype) + +## Adaptation guidance + +1. **Discipline is the brand**: this archetype requires institutional commitment to saying no. Adding decoration over time degrades the archetype faster than other archetypes. +2. **Type family pick**: Helvetica reads neutral and Swiss; Söhne reads contemporary and sharp; Suisse reads precise and minimal; Inter reads accessible and modern. Pick based on temperature, not novelty. +3. **Color discipline**: black plus white plus one accent maximum. Brands that "just add one more color" frequently undermine the archetype. +4. **Photography**: product-on-white only. Lifestyle photography pulls toward Warm Conversational or Luxe Considered. +5. **Voice**: write honest, not poetic. Minimal Essentialist voice that tries to be evocative reads as Luxe Considered; minimal voice that is too plain reads as Editorial Restrained. + +## Exemplar brands + +Minimal Essentialist is exemplified by Apple at its most restrained (mid-2010s product pages), Allbirds at launch, Muji, Casper at launch, Everlane, Squarespace (in its minimal era), The Ordinary, and Aritzia in product detail pages. Adjacent examples include Dieter Rams' principles applied to digital and the early Medium publication system. + +These brands share: black-white-plus-accent, single sans family, extreme whitespace, product-on-white photography, terse declarative voice, no decorative ornament. + +The archetype differs from Editorial Restrained primarily in the absence of serif type and the absence of warm paper backgrounds. Editorial Restrained allows serif display and warm cream; Minimal Essentialist eliminates both. Brands frequently start Minimal Essentialist at launch and migrate toward Warm Conversational or Editorial Restrained as the audience matures and the brand needs more content depth. diff --git a/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md b/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md new file mode 100644 index 0000000..0484151 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md @@ -0,0 +1,112 @@ +# Vibrant Saturated + +## Aesthetic summary + +High saturation across the full palette. Color used as primary brand expression. Type often plays second to color. Compositions are color-blocked. Voice is energetic and personality-driven. The brand makes color the primary asset, and the audience remembers the brand by hue before they remember the wordmark. + +## Position on the 4 creative-direction axes + +- **Tone register**: Playful +- **Aesthetic register**: Expressive +- **Audience relationship**: Performer +- **Sensory ambition**: Immersive + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #181818 | Soft-black text | +| paper | #FFFFFF | White surface | +| accent-primary | #FE2D81 | Saturated brand pink | +| accent-secondary | #2BC8F4 | Bright cyan | +| accent-tertiary | #FFD426 | Saturated yellow | +| accent-quaternary | #8B3DFF | Vivid purple | +| accent-quinary | #21D17C | Bright green | +| signal | varies | Color-blocking accents derived from the palette | + +Rationale: +- Multi-hue saturated palette is the signature. Single-accent palettes do not produce Vibrant Saturated. +- Saturation generally above 70% across the palette. The discipline is that all colors are at similar saturation; this is what produces palette coherence despite hue variety. +- Pure white surfaces. Cream and warm-white pull the archetype toward Warm Conversational. +- The palette is calibrated so any two colors can sit next to each other. This requires hue and value discipline; brands that wing it produce chaos rather than coherent vibrancy. + +## Type pairing starter + +- **Display**: A clean geometric or neo-grotesque sans (Söhne, GT America, Helvetica Now, or a brand-custom face). 600 to 800 weight. +- **Body**: Same family, 400 to 500. +- **Optional serif**: A clean serif (Source Serif, Tiempos Text) for editorial moments. Used sparingly. + +Size scale (color carries the page; type is competent rather than expressive): +- Hero: 48 to 64px sans +- H2: 32 to 40px sans +- Body: 16 to 18px sans +- Small: 14 to 15px + +Pairing rationale: the type is intentionally calmer than the color. Going expressive on both type and color produces visual chaos; one element carries the personality while the other carries the functional load. In Vibrant Saturated, color carries personality and type carries function. + +## Layout and composition + +- Color-blocked compositions are signature. Sections alternate full-bleed background colors; the page reads as panels. +- Heavy use of color as section organizer. The brand may use 6 different colors across a single page, each demarcating a different content type. +- Type sits in color fields rather than on white. White-on-saturated and dark-on-light alternate. +- Rounded corners are common but not aggressive (8 to 16px). +- Motion design uses color transitions (sections fade between hues on scroll, hover states shift hue). + +## Imagery direction + +- Photography: high-saturation, often product-on-color-block, sometimes graphic-treated. +- Illustration: brand-custom illustration systems often appear, with the brand's color palette as the discipline. +- Pattern: bold pattern systems common, using the brand palette. +- Product UI: shown against brand-color backgrounds rather than neutral surfaces. The product takes on the brand's color identity. + +## Voice samples + +- "Music for whatever you're feeling. All of it. Right now." +- "The good news: this works. The better news: you do not have to figure it out." +- "Yes, we are different. That is the point." +- "Press play. We will handle the rest." +- "Built for people who pick a color and commit." + +Cadence: energetic. First and second person. Comfortable with personality. Direct address. Numbers used playfully ("100 percent honest, 0 percent boring"). The voice is the spoken version of the visual energy. + +## Component pattern descriptions + +**Hero**: Often a single dominant brand color as background, with white type and a contrasting accent CTA. Sometimes split between two brand colors. The hero is the color, not the photograph. + +**Buttons**: Solid brand color, contrast text. 8 to 16px radius. Buttons may use one of several brand colors depending on context (the CTA color signals the section's purpose). + +**Cards**: Often colored rather than white. Each card may use a different brand color, with the color carrying meaning (category, type, status). 12 to 16px radius. + +**Sections**: Strong color demarcation. Section A is pink-on-white; Section B is cyan-on-white; Section C is yellow-on-dark. The reader navigates by color. + +**Patterns and shapes**: Common as section dividers and decorative accents. Always within the brand palette. + +## When to pick this + +- Consumer apps with strong category brands +- B2B brands targeting prosumer or creator audiences +- Brands where memorability through color is the strategy +- Brand has color system design discipline (this archetype is harder than it looks) + +## When to avoid + +- B2B brand targeting risk-averse buyers +- Brand cannot commit to color system discipline (winging it produces chaos) +- Brand needs to communicate seriousness or rigor as primary signals +- Category is already crowded with vibrant brands + +## Adaptation guidance + +1. **Palette discipline first**: defining 4 to 6 saturated hues that compose together is the hardest part of this archetype. Spend real time here; the rest is downstream. +2. **Saturation calibration**: keep all colors at similar saturation. Mixed high-saturation and low-saturation produces incoherence. +3. **Type restraint**: the type should not also be expressive. Clean type plus expressive color is the formula; expressive type plus expressive color is chaos. +4. **Color carries meaning**: in the strongest applications of this archetype, color is functional (different colors signal different content types). Use this rather than decorative color. +5. **Accessibility**: contrast ratios must work despite saturated palette. Test every color combination against WCAG AA at minimum. + +## Exemplar brands + +Vibrant Saturated is exemplified by Glossier (with restraint), Spotify, Notion (in its color-era brand expressions), Headspace (overlaps with Playful Energetic), Wise, Klarna, Bumble, and Patreon. Adjacent examples include the Slack rebrand era and the early Stripe consumer-facing surfaces. + +These brands share: multi-hue saturated palette, clean sans type, color-blocked compositions, color as section organizer, expressive but not chaotic compositions. + +The archetype overlaps with Playful Energetic when illustration becomes the dominant element; the difference is that Vibrant Saturated is color-first while Playful Energetic is character-first. Spotify is Vibrant Saturated; Duolingo is Playful Energetic. Both are colorful; the dominance pattern is what distinguishes them. diff --git a/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md b/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md new file mode 100644 index 0000000..183c053 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md @@ -0,0 +1,111 @@ +# Documentary Honest + +## Aesthetic summary + +Photography-first. Real people in real conditions. Low touch on imagery. Type recedes to let imagery lead. Compositions are large and image-dominant. Voice is direct and journalistic. The brand uses honest representation as its primary asset, and the visual restraint signals that the product or experience is the real thing rather than the constructed thing. + +## Position on the 4 creative-direction axes + +- **Tone register**: Conversational +- **Aesthetic register**: Restrained +- **Audience relationship**: Peer +- **Sensory ambition**: Considered + +## Color palette starter + +| Token | Hex | Role | +|---|---|---| +| ink | #1B1B1B | Near-black text | +| paper | #FAFAF8 | Off-white surface | +| paper-soft | #F0EFEB | Subtle tinted surface | +| accent | varies by imagery | Pulled from dominant photography tones | +| muted | #5C5C5A | Mid-gray for metadata | +| line | #E2E0DA | Soft line color | + +Rationale: +- The palette derives from photography rather than being imposed on photography. Each brand expression of this archetype has a distinct accent because the accent comes from the imagery world. +- Off-white surfaces with subtle warmth; the photography sits on the page rather than being framed by aggressive surfaces. +- Mid-gray secondary text reads as caption-feeling rather than UI-feeling. +- Saturation throughout the palette is low; photographs may be saturated, but the surrounding UI is muted to let imagery be the contrast. + +## Type pairing starter + +- **Display**: A clean serif (Tiempos Headline, Source Serif, GT Sectra) or a humanist sans (GT America, Söhne, Inter Display). 500 to 700. +- **Body**: Same family or matched body weight, 400 to 500. +- **Caption type**: A subtle italic or smaller weight for image captions and metadata, often in muted gray. + +Size scale (modest, deferential to imagery): +- Hero: 36 to 48px (smaller than most archetypes; the photograph carries hero weight, not type) +- H2: 26 to 32px +- Body: 17 to 19px (comfortable reading) +- Caption: 14 to 15px italic or in muted gray + +Pairing rationale: type sits in service of imagery. Restrained scale and weight let the photograph dominate. Italic captions read journalistic, evoking magazine and newspaper conventions. Either serif or sans works; the pairing should be calm. + +## Layout and composition + +- Photography is large and frequently full-bleed. The image occupies more page real estate than the type. +- Compositions reference editorial design: photograph with caption, photograph with pull quote, photograph plus body text. +- Asymmetric layouts where the image leads and text follows. Often 60/40 splits with photography dominant. +- Generous internal padding around text blocks. The text breathes within the layout. +- Hover states are subtle. The page reads as a document rather than as an interface. + +## Imagery direction + +- Real people, real environments, real conditions. Candid more often than posed. +- Natural light dominant. Studio lighting rare and intentional when used. +- Documentary photography conventions: telephoto compression for environmental portraits, wide-angle for context shots, intentional grain accepted. +- The archetype assumes investment in photography. Stock imagery undermines the archetype immediately. +- Photo direction matters more than photo quantity. A few exceptional images carry the archetype better than many adequate ones. + +## Voice samples + +- "She has been on the trail for six days. Today is the first day she has had warm feet." +- "We met him in the workshop where he learned the trade. He has worked there for 31 years." +- "Three thousand miles. Six time zones. One bag." +- "Built in Vermont. Tested in places where bad gear ends careers." +- "This is what we did. These are the people we did it with. These are the results." + +Cadence: journalistic. Third-person more often than first. Comfortable with specificity (real dates, real durations, real names where appropriate). The voice reads as reporting rather than selling. + +## Component pattern descriptions + +**Hero**: Large photograph (full-bleed or near-it) with overlaid restrained type, or photograph above type-only headline section. The photograph IS the hero. + +**Buttons**: Restrained. Often text-only with underlines, or thin-bordered with calm labels. The buttons recede; the photography leads. + +**Cards**: Often a card is a photograph plus caption plus body excerpt. The card structure mirrors editorial conventions (photo, caption, headline, dek). + +**Quotes**: Pulled quotes are a recurring pattern, set in restrained type with attribution beneath. + +**Sequences**: This archetype frequently uses image sequences (3 to 6 photographs telling a small story) where most archetypes use a single hero image. + +## When to pick this + +- Travel, hospitality, lifestyle brands where the experience IS the value proposition +- Journalism-adjacent brands (publications, archives, documentary work) +- Brands where real stories are the differentiation +- Brand has access to genuine documentary photography (either custom or excellently curated) + +## When to avoid + +- Brand has no real photography access or budget +- Product is functional rather than experiential +- Audience expects highly designed marketing rather than journalistic restraint +- Category is built on aspiration rather than reality (Documentary Honest fights aspirational positioning by definition) + +## Adaptation guidance + +1. **Photography commitment**: this is a photography archetype before it is anything else. If photography is going to be stock or poorly art-directed, switch archetypes. +2. **Voice register**: write journalistic, not marketing. Documentary Honest voice that slides into "we are passionate about" undermines the archetype. +3. **Restraint discipline**: resist adding decorative elements, color accents, or pattern. The photography is the visual; everything else should recede. +4. **Caption discipline**: captions are first-class content. They carry the story alongside the image. Treat them with the same care as headlines. +5. **Authenticity test**: the brand should be able to defend each photograph with a real story. Generic stock-feeling images destroy the archetype. + +## Exemplar brands + +Documentary Honest is exemplified by Airbnb (in its early marketing surfaces), Patagonia (overlaps with Rugged Utilitarian), Outside Magazine, The New York Times' visual journalism work, REI in its editorial content, Selina, and Yeti (in its long-form brand content). Adjacent examples include Field Mag, Topo Designs in long-form marketing, and Filson's historical archives. + +These brands share: real photography as primary visual, restrained type system, journalistic voice, image-plus-caption editorial conventions, low-saturation palette derived from imagery. + +The archetype overlaps with Rugged Utilitarian (both rely on real photography) and Editorial Restrained (both rely on restrained type). The difference: Rugged Utilitarian has utility framing (this is for working); Editorial Restrained is institutional confidence applied to B2B; Documentary Honest is honest representation applied to experience and story. diff --git a/skills/brand-discovery/SKILL.md b/skills/brand-discovery/SKILL.md new file mode 100644 index 0000000..3829f09 --- /dev/null +++ b/skills/brand-discovery/SKILL.md @@ -0,0 +1,197 @@ +--- +name: brand-discovery +description: "Run upstream brand discovery covering audience research, competitive landscape, category dynamics, problem space, and positioning territory exploration. Use this skill at the very start of a brand or website project when the user needs to understand who they're for, who they compete with, what the audience actually needs, and where the brand could plausibly stand. Triggers on brand discovery, audience research, market research, competitive scan, category research, customer research, who is this for, who are we, positioning research, intake, kickoff. Also triggers when a creative brief is requested but the upstream inputs (audience, competitors, problem space) are not yet clear." +category: strategy-and-discovery +catalog_summary: "Audience research, competitive scan, positioning territory exploration" +display_order: 1 +--- + +# Brand Discovery + +Upstream of every brief, identity, and content plan. Discovery answers four questions: who the brand is for, what they need, who else is competing for that need, and where the brand could plausibly stand that competitors do not. + +--- + +## When to use + +- The very first phase of a new brand or website project +- Understanding an audience before any creative work begins +- Mapping competitors and category dynamics +- Surfacing the problem space the brand will operate in +- Generating positioning territories before brief or ideation +- When a creative brief was requested but the inputs are missing + +## When NOT to use + +- The audience and category are already well-understood (jump to `creative-brief` or `brand-ideation`) +- Validating a specific design or feature with users (use `usability-testing`) +- Mapping the customer journey of an existing audience (use `journey-mapping`) +- Generating brand names or visual directions (use `brand-ideation`) + +--- + +## Required inputs + +- The product, service, or organization being branded +- Whatever is already known about the audience and category (often very little) +- Access to existing materials (sales calls, support tickets, reviews, analytics) +- Any constraints (parent brand, regulatory, geographic) +- A timeline (a 1-week discovery looks different than a 6-week one) + +--- + +## The framework: 4 dimensions + +Discovery covers four dimensions. Each has its own sources, methods, and outputs. + +### 1. Audience + +Who specifically does this serve? + +**Layers to surface:** + +- **Demographic:** Age range, geography, language, life stage, income (only if relevant; do not over-collect demographics) +- **Psychographic:** Values, motivations, beliefs, fears +- **Behavioral:** What they currently do to address the problem, what tools they use, where they spend time online and offline +- **Jobs-to-be-done:** The functional, emotional, and social jobs they hire a brand to perform + +**Sources:** + +- Existing customer interviews (5 to 8 ideal) +- Sales call recordings or transcripts +- Support ticket themes +- Review and forum analysis (Reddit, Trustpilot, App Store, niche communities) +- First-party analytics (search console queries, on-site search, top pages) +- Social listening (what they post about the category) + +**Output:** 1 to 3 named audience segments, each with a one-page profile. + +### 2. Competitors + +Who else competes for the same audience and need? + +**Three layers of competitor:** + +- **Direct:** Solves the same problem the same way (e.g., another SaaS in the category) +- **Indirect:** Solves the same problem a different way (e.g., a spreadsheet replacing a SaaS tool) +- **Status quo:** Doing nothing, doing it manually, or living with the problem + +The third is most often forgotten and most often the actual competitor. + +**Per competitor, document:** + +- Who they target (audience overlap with you) +- How they position (what they claim to be) +- What they actually deliver (often different from positioning) +- Pricing model and structure +- Strengths and weaknesses from the audience's perspective +- Recent moves (launches, pivots, hires, departures) + +**Sources:** + +- Their own website and marketing +- Reviews of their product or service +- Their content and SEO presence (use `seo-competitor` for the search angle) +- Social proof and customer voices + +Competitive scan benefits from quantitative grounding: not just "who are the competitors" but "how much traffic do they earn, where does it come from, who is the audience overlap." Similarweb is the standard for this kind of competitive landscape analysis; pair with Ahrefs for the SEO-specific overlap. + +**Output:** Competitor matrix (3 to 8 competitors deep), plus a one-line "what makes them dangerous" for each. + +### 3. Category and problem space + +What is the broader context this brand operates in? + +**Map:** + +- **The problem.** What is the actual user problem? Not the surface symptom, the underlying job to be done. +- **The category.** How is the category structured? Is it new, mature, fragmenting, consolidating? +- **The conventions.** What does every brand in the category do the same way? (These are the conventions you can break.) +- **The shifts.** What is changing in the category? Technology, regulation, audience behavior, distribution. +- **The moats.** What protects incumbents? Brand, distribution, network effects, switching costs? +- **The vocabulary.** What language does the category use? What is jargon, what is meaningful, what is empty? + +**Sources:** + +- Industry reports and analyst coverage +- Trade publications and conferences +- Adjacent category observations +- Customer language vs. category language (the gap is informative) + +**Output:** A category map and a list of conventions to consider breaking (or keeping deliberately). + +### 4. Positioning territory + +Given the audience, competitors, and category, where could this brand plausibly stand? + +This is not yet "the positioning." Discovery surfaces possible territories. `brand-ideation` narrows them and commits. + +**Generate territories from:** + +- Underserved audience segments (audiences others ignore) +- Underserved jobs (jobs the category does not do well) +- Category convention violations (what would happen if you broke the rules everyone follows) +- Honest brand truths (what is genuinely true about this brand that competitors cannot also claim) +- Category shifts (where the puck is going) + +**Per territory, document:** + +- The statement (one sentence) +- Why it could work (proof point) +- Who would resonate (the audience for this territory) +- Who is competing in this territory (often, no one good) +- Risk (what makes it fragile) + +**Output:** 3 to 5 distinct territories. Not yet committed. Inputs to `brand-ideation`. + +--- + +## Workflow + +1. **Define the discovery scope.** 1 week for a startup pre-launch. 4 to 6 weeks for a major rebrand. Set expectations. +2. **Audit existing inputs.** Sales calls, support tickets, reviews, analytics, internal docs. Often more is known than people think. +3. **Audience research.** 5 to 8 interviews if possible. Plus secondary research from review and forum analysis. +4. **Competitor mapping.** 3 to 8 competitors deep, including indirect and status-quo competitors. +5. **Category mapping.** Conventions, shifts, vocabulary, moats. +6. **Territory generation.** 3 to 5 plausible positioning territories. +7. **Write the discovery report.** Use the template in [`references/discovery-report-template.md`](references/discovery-report-template.md). +8. **Hand off to next phase.** Discovery feeds into `creative-brief`, `brand-ideation`, or `content-strategy` depending on where the project goes next. + +--- + +## Failure patterns + +- **Skipping discovery to "save time."** Every shortcut here costs 10x downstream when the brand fails to land. +- **Audience research that confirms what you already believe.** If your audience research validates every assumption, you did not actually research. Look for surprises. +- **Demographic-heavy audience profiles.** "Women aged 25 to 45" is not insight. Behavior, beliefs, and jobs-to-be-done are. +- **Listing every competitor as if equal.** Most competitors do not matter. Pick the 3 that are genuinely dangerous. +- **Forgetting status-quo as competition.** The biggest competitor is usually "doing nothing" or "doing it manually." +- **Outputting territories without rejection criteria.** A territory without a "what this rejects" is not a territory. +- **Treating discovery as a one-time event.** Categories shift. Audiences evolve. Re-run discovery at least every 3 years. + +--- + +## Output format + +Default output is a discovery report at `discovery-report.md` plus appendices. + +Structure: +1. Executive summary (5 to 10 bullets) +2. Audience (1 to 3 named segments with profiles) +3. Competitors (matrix and per-competitor analysis) +4. Category and problem space +5. Positioning territories (3 to 5 candidates) +6. Implications and recommendations +7. Open questions that require further research + +Appendices: +- Interview notes (sanitized) +- Competitor research data +- Source list + +--- + +## Reference files + +- [`references/discovery-report-template.md`](references/discovery-report-template.md) - Full discovery report template. +- [`references/interview-guide.md`](references/interview-guide.md) - Audience interview guide with question prompts. diff --git a/skills/brand-discovery/references/discovery-report-template.md b/skills/brand-discovery/references/discovery-report-template.md new file mode 100644 index 0000000..68844e7 --- /dev/null +++ b/skills/brand-discovery/references/discovery-report-template.md @@ -0,0 +1,177 @@ +# Brand Discovery Report Template + +A fillable template for the discovery deliverable. The discovery report is what every later phase of brand work references. If a section is thin, later phases will be too. + +Fill every section. If a section is "N/A", say why explicitly. + +--- + +## Project metadata + +**Brand / project:** [Name] +**Phase:** [Initial discovery / refresh / repositioning] +**Date:** [YYYY-MM-DD] +**Lead:** [Name] +**Stakeholders interviewed:** [Names and roles] +**Customers interviewed:** [Number, segments] + +--- + +## Executive summary + +Three to five sentences. The single most important thing the discovery surfaced, the strongest opportunity, and the biggest risk. + +> [Summary] + +--- + +## Audience + +### Primary audience + +**Who they are:** [Demographic and behavioral picture. Not a persona archetype. Real, specific, current.] + +**What they want:** [The job they hire the category to do. Surface and underlying.] + +**What they fear or doubt:** [Objections, hesitations, alternative options being considered.] + +**Where they are:** [Channels, communities, sources of trust.] + +**Quotes (verbatim from interviews):** + +> "[Verbatim quote that reveals motivation or pain]" - [Segment] +> "[Verbatim quote]" - [Segment] +> "[Verbatim quote]" - [Segment] + +### Secondary audience(s) + +[Only include if they materially shape the work. Otherwise note "none material" and move on.] + +--- + +## Category and competition + +### The category as the audience sees it + +What the audience calls this category. What they group us with. (Often different from how the company sees it.) + +### Direct competitors + +| Competitor | Position they hold | Strength | Weakness | Opportunity for us | +|---|---|---|---|---| +| | | | | | +| | | | | | +| | | | | | + +### Indirect / adjacent + +[Substitutes the audience considers, even if not in the same product category.] + +### Reference brands (aspirational) + +[Brands the audience admires that we want to be associated with - same audience, different category.] + +--- + +## Positioning territory + +### What we found + +The discovery process should produce 2 to 4 candidate positioning territories. Each is a defensible space the brand could own. + +#### Territory 1: [Name] + +- **Core idea:** [One sentence] +- **Why it could work:** [Audience need it serves, gap in competition, asset we have] +- **Why it could fail:** [Risk, what would have to be true] +- **What it would look like:** [How marketing, product, copy would feel under this territory] +- **Evidence from research:** [Specific findings that support this] + +#### Territory 2: [Name] + +[Same structure] + +#### Territory 3: [Name] + +[Same structure] + +### Recommendation + +The discovery report is allowed to recommend one. Make the case. Or explicitly punt: "Run a positioning workshop with these four candidates." + +--- + +## Brand truths + +What the discovery surfaced about who this brand actually is, not what marketing has been saying. + +### What is true + +- [Fact about the company, founders, product, or community that is real and ownable] +- [Fact] +- [Fact] + +### What is aspirational (and that is OK) + +- [Thing we want to be that we are not yet, but are credibly working toward] +- [Thing] + +### What is not true (and stop saying) + +- [Claim the company makes that did not survive scrutiny] +- [Claim] + +--- + +## Strategic implications + +What the discovery means for the work ahead. + +### For brand identity + +- [Implication, e.g., "The visual direction should signal quietness, not loudness; the audience is exhausted by category noise."] + +### For brand voice + +- [Implication, e.g., "Voice should be confident without being clever; the audience equates cleverness with sales pressure."] + +### For product + +- [Implication if discovery surfaced product-level gaps or strengths] + +### For marketing + +- [Implication for channel strategy, content focus, message hierarchy] + +--- + +## Open questions + +Things discovery raised that it did not answer. These belong in the next phase. + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Methodology and sources + +- **Stakeholder interviews:** [Number, role mix, format] +- **Customer interviews:** [Number, segment mix, format] +- **Customer surveys:** [Sample size, response rate] +- **Competitive scan:** [Number of brands, depth of review] +- **Search and social listening:** [Sources, time window] +- **Internal docs reviewed:** [Strategy decks, prior research] +- **Caveats:** [What this discovery did not cover, sample limitations] + +--- + +## Sign-off + +Discovery accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand ideation / positioning workshop / direct to identity / etc.] diff --git a/skills/brand-discovery/references/interview-guide.md b/skills/brand-discovery/references/interview-guide.md new file mode 100644 index 0000000..340ee32 --- /dev/null +++ b/skills/brand-discovery/references/interview-guide.md @@ -0,0 +1,193 @@ +# Audience Interview Guide + +A guide for conducting 30 to 45 minute interviews with current customers, prospects, or audience members during brand discovery. + +The goal of interviews is not to validate assumptions. It is to find surprises. Plan to be wrong about most of what you think you know. + +--- + +## Before the interview + +### Who to interview + +For a typical brand discovery, talk to 5 to 8 people across these segments: + +- **Active customers** who have been using the product for 3+ months (deep understanding) +- **Recent customers** who joined in the last 30 days (still remember the buying journey) +- **Lapsed customers** who churned (the most informative; understand why people leave) +- **Prospects who didn't buy** (understand objections) +- **Power users** in adjacent categories (understand alternatives and substitutes) + +If the project is for a new brand with no customers yet, interview members of the target audience using competitive products or substitutes. + +### Recruiting + +Recruit through: +- Customer email list with a thank-you incentive +- Sales team referrals +- LinkedIn outreach to titles matching the audience profile +- Existing user research panels +- Niche communities (Reddit, niche Slack groups, professional forums) + +Compensate participants. $50 to $100 in cash or product credit is reasonable for 30 minutes. + +### Logistics + +- 30 to 45 minutes is the right length. Longer fatigues both sides. +- Record (with consent). Take notes too in case the recording fails. +- Use a video tool that creates transcripts automatically. +- Send a calendar invite with a clear agenda. +- Confirm the day before. + +--- + +## Question framework + +Structure interviews in three sections: their world, the problem, and how they currently solve it. + +### Opening (3 to 5 minutes) + +Get them talking. Build rapport. Establish that there are no wrong answers. + +- "Tell me a bit about yourself and what you do." +- "Walk me through a typical day. What does work look like?" +- "How long have you been doing this kind of work?" + +These warm-up questions also surface context you'll need later. + +### Section 1: Their world (10 minutes) + +Understand the context the brand fits into. + +- "When you think about [the problem area or category], what comes to mind?" +- "What's the part of your work or life this connects to?" +- "How important is [the problem area] in the bigger picture of what you do?" +- "Who else is involved in [the problem area]? Coworkers? Family? Clients?" +- "What's the goal you're trying to hit in this area?" + +Listen for: priorities, stakeholders, vocabulary, time pressure. + +### Section 2: The problem (10 to 15 minutes) + +Surface the actual problem, not the surface symptom. + +- "Tell me about the last time you ran into [the problem]. Walk me through what happened." +- "What was frustrating about that?" +- "What did you try to do about it?" +- "What did you wish had happened instead?" +- "What's the cost of this problem? Time? Money? Stress? Relationships?" +- "Have you ever just decided to live with it instead of solving it? Why?" + +Listen for: emotional weight, the real cost, the workarounds people invent, the resignation. + +The key follow-up: **"Tell me more about that."** Use it relentlessly. Most insight is one or two layers below the first answer. + +### Section 3: How they solve it now (10 to 15 minutes) + +Understand the current toolkit and the alternatives considered. + +- "What do you currently use to address [the problem]?" +- "How did you start using [their current solution]? What were you using before?" +- "What did you consider but not pick? Why not?" +- "What do you wish [your current solution] did better?" +- "If you could wave a magic wand and have [the problem] solved perfectly, what would that look like?" +- "Imagine a tool came along that promised to solve [the problem]. What would it have to be true for you to switch?" + +Listen for: the switching cost, the unmet needs, the specific moments where current solutions fail. + +### Closing (3 to 5 minutes) + +- "Is there anything I should have asked but didn't?" +- "Is there anyone else you think I should talk to about this?" +- "Would you be open to a follow-up if questions come up later?" + +--- + +## Common interview pitfalls + +### Leading questions + +**Bad:** "Do you find it frustrating when [your assumption]?" + +**Better:** "Tell me about your last experience with [the activity]." + +The first question telegraphs the answer you want. The second lets them tell you what was actually frustrating, including things you didn't predict. + +### Asking for solutions + +**Bad:** "What features would you want in [the product]?" + +**Better:** "What's frustrating about how this works today?" + +Users are not product designers. They are the world's leading experts on their own frustrations. Mine the frustrations; you'll design the solutions. + +### Validating instead of investigating + +**Bad:** "Would you use [feature description]?" + +**Better:** "When was the last time you needed something like that? What did you do?" + +Hypothetical answers are useless. Past behavior is informative. + +### Closed questions + +**Bad:** "Was that frustrating?" + +**Better:** "How did you feel about that?" + +Yes/no questions kill the conversation. Open questions keep it going. + +### Talking too much + +If you're talking more than 20 percent of the time, you're talking too much. Your job is to listen, follow up, and get out of the way. + +--- + +## Synthesis + +After all interviews, synthesize across them. + +### Step 1: Tag the transcripts + +Read every transcript. Tag passages by theme: +- Pain points +- Workarounds +- Aspirations +- Vocabulary they use +- Emotional moments +- Surprising statements + +### Step 2: Identify recurring patterns + +A theme that appears in 3+ interviews is signal. A theme in 1 interview is interesting but anecdotal. + +### Step 3: Look for surprises + +The most valuable findings are things you didn't expect. List them explicitly. These often become the basis for distinctive positioning. + +### Step 4: Identify quotes + +The right quote captures more than a paragraph of synthesis. Pull 5 to 10 quotes that capture the core insights. + +### Step 5: Write the audience section of the discovery report + +For each segment: +- Who they are (with the specificity you've earned) +- What they're trying to do +- What's getting in the way +- How they currently solve it +- What they wish were different +- Anchor quote (one strong verbatim quote) + +--- + +## What to avoid + +- Treating the interview as a sales pitch +- Asking about your specific product or feature ideas (validation theater) +- Skipping interviews because "we already know our customer" (you don't) +- Interviewing only happy customers (lapsed customers are more informative) +- Doing 1 or 2 interviews and declaring "we did research" +- Skipping synthesis and going straight to "here's what we learned" without rigor + +5 interviews is the minimum to find patterns. 8 is comfortable. 12+ has diminishing returns for most projects. diff --git a/skills/brand-ideation/SKILL.md b/skills/brand-ideation/SKILL.md new file mode 100644 index 0000000..55ed7b3 --- /dev/null +++ b/skills/brand-ideation/SKILL.md @@ -0,0 +1,175 @@ +--- +name: brand-ideation +description: "Generate, evaluate, and narrow brand concepts during early ideation including positioning territories, naming candidates, mood directions, and narrative angles. Use this skill whenever the user is in the early phase of brand creation, exploring brand directions, brainstorming names, building moodboards, generating positioning options, or trying to choose between multiple brand directions. Triggers on brand ideation, brand concept, naming, brand name, name candidates, positioning, brand positioning, mood board, brand directions, exploring brands, early brand work, brand exploration, brand brainstorm, brand options. Also triggers when the user has multiple half-formed brand ideas and needs help converging on one, even if they do not say 'ideation' explicitly." +category: brand +catalog_summary: "Naming, positioning territories, mood directions, narrative angles" +display_order: 1 +--- + +# Brand Ideation + +Generate and converge on brand directions before committing to identity work. This is upstream of `brand-identity` (the visual system) and `brand-style-guide` (the documentation). It is the divergent-then-convergent thinking phase where ideas are cheap and direction matters more than polish. + +--- + +## When to use + +- Generating naming options for a new brand or product +- Exploring positioning territories before committing +- Building moodboards and visual direction options +- Drafting narrative or origin-story angles +- Helping the user converge from many half-ideas to one direction +- Stress-testing an existing brand idea before investing in identity work + +## When NOT to use + +- The brand direction is already locked, the user wants logo and identity work (use `brand-identity`) +- Documenting an existing brand system (use `brand-style-guide`) +- Defining voice for an existing brand (use `brand-voice`) +- Initial discovery and audience research (use `brand-discovery`) + +--- + +## Required inputs + +- The category or product type +- The audience (at least roughly) +- The reason this brand exists (the problem it solves or the gap it fills) +- Constraints (existing brand assumptions, parent brand, regulatory limits) +- Number of directions desired (typically 3 to 5) + +If the audience is unclear, run `brand-discovery` first. + +--- + +## The framework: 4 stages + +Brand ideation moves through four stages. Each stage diverges (generate options) then converges (pick a direction). + +### Stage 1: Positioning territories + +A positioning territory is the strategic space the brand occupies. It is not a tagline. It is the answer to "what does this brand stand for that competitors do not?" + +Generate 3 to 5 territories using these angles: + +- **Functional benefit.** "The fastest way to X." (Risk: easy to copy.) +- **Emotional benefit.** "The brand that makes you feel Y." (Risk: vague if not earned.) +- **Identity.** "For people who are Z." (Risk: alienates non-Z customers.) +- **Antagonist.** "The opposite of [incumbent]." (Risk: defines you by them.) +- **Originator.** "The first or only one to do W." (Risk: must be defensible.) +- **Worldview.** "We believe V." (Risk: must be lived, not just stated.) + +For each territory, write: +- **Statement** (one sentence) +- **Why this is true** (the proof point) +- **What this rejects** (the territory we are NOT going to) +- **Risk** (what makes this fragile) + +### Stage 2: Naming directions + +Names cluster by approach. Generate names across multiple approaches, not just one. + +| Approach | Description | Examples | +|---|---|---| +| Descriptive | Says what it is | "General Electric," "American Airlines" | +| Evocative | Suggests a feeling or quality | "Patagonia," "Oasis," "Stripe" | +| Founder | Person's name | "Disney," "Ford," "Tesla" | +| Acronym | Letters from longer phrase | "IBM," "BMW," "AWS" | +| Coined | Made-up word | "Kodak," "Häagen-Dazs," "Asana" | +| Metaphor | Borrowed concept | "Apple," "Amazon," "Twitch" | +| Compound | Two words combined | "Facebook," "PayPal," "Spotify" | +| Suggestive | Hints at function without describing | "Tide," "Sprint," "Slack" | + +Generate 8 to 15 candidates per direction. Apply naming filters before short-listing: + +- **Pronounceable** in target languages +- **Spellable** without confusion +- **Available** as a domain (.com or relevant TLD), social handles, and trademark +- **Distinctive** in the category (search the name + category, see what comes up) +- **Stretchable** (does the name still work if the company expands?) +- **Free of negative associations** (run it past native speakers of any major target market) + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high. + +### Stage 3: Mood and visual direction + +Generate visual directions BEFORE designing anything. Each direction should be distinct enough that a designer would produce visibly different work for each. + +For each mood direction (typically 2 to 4): + +- **Mood adjectives** (3 to 5 words) +- **Color territory** (warm/cool, saturated/muted, light/dark - not specific hex yet) +- **Type territory** (serif/sans, modern/classical, geometric/humanist) +- **Imagery direction** (photography style, illustration style, iconography) +- **Reference brands or sites** (3 to 5 that exemplify the direction) +- **What this rejects** (the visual territory we are NOT going to) + +A mood direction is "Editorial sophistication: Warm cream paper backgrounds, classical serifs, archival photography. Think: The New York Times Magazine meets a literary journal." + +A bad mood direction is "Modern and clean." + +### Stage 4: Narrative and origin + +Every brand has a story. The narrative answers: how do we tell people why this exists? + +Common narrative shapes: + +- **Founder story.** A real person solved a real problem they had. +- **Mission story.** A bigger purpose drives every decision. +- **Discovery story.** We found something the world did not know. +- **Heritage story.** This has always been done a certain way; we honor or refresh it. +- **Frustration story.** The category was broken; we built the alternative. +- **Vision story.** Here is the future we are pulling toward. + +For each candidate narrative: + +- **One-sentence summary** +- **The opening line** (how the story starts when told for the first time) +- **The proof points** (what makes it true and not marketing puff) +- **The hero** (who the audience identifies with - the founder, the customer, the world) + +--- + +## Workflow + +1. **Confirm the inputs.** Category, audience, reason for being, constraints. +2. **Stage 1: Generate 3 to 5 positioning territories.** Use the 6 angles above. Name what each rejects. +3. **Pick 1 to 2 territories.** Move forward with the strongest. +4. **Stage 2: Generate 30 to 50 naming candidates** across at least 4 approaches. Filter to 8 to 12 that pass the six-criteria check. +5. **Stage 3: Generate 2 to 4 mood directions.** Each must be distinguishable enough to brief a designer. +6. **Stage 4: Generate 2 to 3 narrative shapes.** Pick the one that fits the founders, the audience, and the proof points. +7. **Converge.** Present the user with: 1 positioning, 8 to 12 naming finalists, 2 to 4 mood directions, 2 to 3 narrative shapes. Help them pick. +8. **Output.** Use the template in [`references/ideation-output-template.md`](references/ideation-output-template.md). + +--- + +## Failure patterns + +- **Generating one option and calling it "the answer."** The point of ideation is divergence. Without options, there is no real choice. +- **Skipping the rejection step.** A territory that does not name what it rejects is not a territory. Same for moods. +- **Naming before positioning.** Names without positioning end up arbitrary. Position first. +- **Falling in love with one name too early.** Run the full filter on every candidate. The clever name that fails the trademark check is not a candidate. +- **"Modern, clean, minimal" mood direction.** Means nothing. Always require specific reference brands. +- **Skipping pronunciation tests.** Especially for international brands. A name that confuses non-English speakers loses search volume forever. +- **Mistaking ideation for execution.** The output of this stage is direction, not finished assets. Resist the urge to design logos here. + +--- + +## Output format + +Default output is a markdown brief at `brand-ideation.md` in the project root. Includes: + +1. The chosen positioning territory (with what it rejects) +2. Naming finalists (8 to 12) with notes on each +3. Mood directions (2 to 4) with reference URLs +4. Narrative shape (chosen) with opening line and proof points +5. Open questions and decisions still needed before identity work begins + +Optional: a separate `naming-explorations.md` with the full list of 30 to 50 candidates (the "kill file") in case the chosen finalists fail later checks. + +--- + +## Reference files + +- [`references/ideation-output-template.md`](references/ideation-output-template.md) - Fillable template for the ideation deliverable. +- [`references/naming-evaluation-rubric.md`](references/naming-evaluation-rubric.md) - The 6-criteria filter applied with examples. diff --git a/skills/brand-ideation/references/ideation-output-template.md b/skills/brand-ideation/references/ideation-output-template.md new file mode 100644 index 0000000..e3d208c --- /dev/null +++ b/skills/brand-ideation/references/ideation-output-template.md @@ -0,0 +1,181 @@ +# Brand Ideation Output Template + +A fillable template for the ideation deliverable. Captures the candidate names, positioning territories, mood directions, and narrative angles produced during ideation. + +The deliverable is not a single answer. It is a structured set of options the team can evaluate, narrow, and combine. + +--- + +## Project metadata + +**Brand / project:** [Name] +**Ideation lead:** [Name] +**Date:** [YYYY-MM-DD] +**Inputs used:** [Discovery report, brief, prior decks - link them] + +--- + +## Recap: what we are ideating against + +Two to four sentences. Pull from the discovery report. Anyone reading this deliverable cold should know: + +- Who the audience is +- What position the brand is trying to take +- What the constraints are (legal, geographic, category) + +> [Recap] + +--- + +## Naming candidates + +Generate widely first. Filter later. Aim for 30-50 candidates per round before applying the rubric. + +### Round 1: divergent + +| # | Name | Type | Source / inspiration | +|---|---|---|---| +| 1 | | Coined / descriptive / metaphorical / founder / acronym / compound / portmanteau | | +| 2 | | | | +| 3 | | | | +| ... | | | | + +### Round 2: filtered shortlist + +After applying the 6-criteria rubric (`naming-evaluation-rubric.md`), the names that survive. + +| # | Name | Why it survived | Open concerns | +|---|---|---|---| +| 1 | | | | +| 2 | | | | +| 3 | | | | +| 4 | | | | +| 5 | | | | +| 6 | | | | + +### Round 3: top 3 with full case + +For each finalist, write a one-page case. + +#### Finalist 1: [Name] + +- **Pronunciation:** [How it is said] +- **Type:** [Coined, metaphor, etc.] +- **Meaning:** [What it evokes, intentionally or by association] +- **Why it works:** [Per the 6 criteria] +- **Risks:** [Domain availability, trademark, cultural concerns, audience misreading] +- **Domain status:** [.com / alternative TLDs / acquisition cost estimate] +- **Trademark status:** [Cleared by counsel / preliminary search clean / requires deeper search] +- **Visual potential:** [How it could render as a wordmark, monogram, icon] + +#### Finalist 2: [Name] + +[Same structure] + +#### Finalist 3: [Name] + +[Same structure] + +--- + +## Positioning territories + +The territories from discovery, sharpened into ideation directions. Each territory should produce a distinct creative direction. + +### Territory 1: [Name] + +- **One-sentence position:** [The territory in a sentence] +- **Voice direction:** [How it sounds] +- **Visual direction:** [How it looks] +- **Headline examples:** [3-5 sample headlines that could only come from this territory] +- **What it rules out:** [Names, treatments, or messages this territory disqualifies] + +### Territory 2: [Name] + +[Same structure] + +### Territory 3: [Name] + +[Same structure] + +### Territory 4: [Name] + +[Same structure] + +--- + +## Mood directions + +Three to five mood directions, each with reference imagery, color cues, and a one-line description. These are not final design - they are starting points for art direction. + +### Mood 1: [Name, e.g., "Quiet confidence"] + +- **Description:** [One line] +- **References:** [3-5 visual references with credit and one-line note on what to take from each] +- **Color cues:** [General feel, not exact palette] +- **Typography cues:** [General feel] +- **Photography or illustration direction:** [General feel] +- **Adjacent brands as reference:** [Not to copy, to triangulate] + +### Mood 2: [Name] + +[Same structure] + +### Mood 3: [Name] + +[Same structure] + +--- + +## Narrative angles + +Three to five candidate brand stories or origin narratives. Each is a different way of telling who this brand is and why it exists. + +### Angle 1: [Name, e.g., "Founder's journey"] + +- **Premise:** [The narrative angle in two sentences] +- **First page hero:** [What the homepage hero would say under this angle] +- **About page opening:** [The first paragraph of the about page] +- **Why it works:** [What it earns the brand] +- **Why it might fail:** [Risk] + +### Angle 2: [Name] + +[Same structure] + +### Angle 3: [Name] + +[Same structure] + +--- + +## Synthesis: provisional recommendation + +Even though ideation produces options, the team should leave with a provisional combination to test next. + +> **Provisional combination:** Name [X], territory [Y], mood [Z], narrative [W]. +> +> **Why this combination:** [Two sentences.] +> +> **What we test next:** [Concept board, name validation with audience, treatment exploration, etc.] + +--- + +## Open questions + +- [ ] [Trademark search needed for finalist names] +- [ ] [Domain acquisition feasibility] +- [ ] [Audience reaction test for top 2 names] +- [ ] [Stakeholder alignment session for territory selection] +- [ ] [Other] + +--- + +## Sign-off + +Ideation accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand identity / further name validation / board-level review / etc.] diff --git a/skills/brand-ideation/references/naming-evaluation-rubric.md b/skills/brand-ideation/references/naming-evaluation-rubric.md new file mode 100644 index 0000000..d34bbfa --- /dev/null +++ b/skills/brand-ideation/references/naming-evaluation-rubric.md @@ -0,0 +1,151 @@ +# Naming Evaluation Rubric + +A name has to clear six bars. This document walks through each, with examples of names that pass and fail. + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high because a name lives forever. + +--- + +## 1. Pronounceable + +A name people cannot say will not get said. + +**Pass:** +- "Stripe" - one syllable, unambiguous +- "Notion" - two syllables, common word, clear stress +- "Loom" - one syllable, common phoneme + +**Fail:** +- "Xobni" (the X is silent? before the b? unclear) +- Names with non-English diacritics for an English-speaking market that get stripped to ambiguity +- "Yext" - is it "yext" with a hard Y or "ekst"? People disagree + +**Test:** Read the name aloud to 5 people who have not seen it written. If 3 of 5 pronounce it differently, fail. + +--- + +## 2. Spellable + +A name people cannot spell will not get found. + +**Pass:** +- "Asana" - phonetic, spelled exactly as it sounds +- "Patagonia" - long but predictable +- "Slack" - one syllable, common word + +**Fail:** +- "Häagen-Dazs" - even the inventors made it hard to spell on purpose +- Names with silent letters that are not standard English +- Names with "ee" / "ea" / "ie" ambiguity +- Names with double letters in unexpected places + +**Test:** Read the name aloud to 5 people. Ask them to spell it. If 2 of 5 misspell it, fail. + +--- + +## 3. Available + +A name you cannot legally use is not a candidate. + +Check, in this order: + +1. **Trademark search** in the relevant jurisdictions. Class matters - you can have the same name as another brand if you operate in different categories, but check. +2. **Domain availability.** The .com (or category-relevant TLD) for the exact name. Adjacent TLDs (.io, .co, .app) are weaker; .com is still default for most categories. +3. **Social handles.** Check the major platforms. Inconsistent handles fragment the brand. +4. **Existing brands in the category.** Even if trademark is technically clear, a confusable competitor name is a problem. +5. **Negative associations.** Search the name in quotes. See what shows up. + +**Pass:** +- A name with .com available, no conflicting trademark, clean handles across major platforms + +**Fail:** +- A name where the .com is parked at $50,000 and no budget exists +- A name that conflicts with a registered trademark in the same class +- A name that someone notable already uses on social platforms + +--- + +## 4. Distinctive + +A name that gets confused with competitors loses every benefit of being a name. + +**Pass:** +- "Stripe" in payments - distinct from PayPal, Square, Adyen +- "Notion" in productivity tools - distinct from Asana, Monday, Trello +- "Loom" in async video - distinct from Zoom, Vimeo, YouTube + +**Fail:** +- A name one letter different from a major competitor +- A name that rhymes with a major competitor +- A name from the same conceptual family (e.g., another fruit name in a market dominated by Apple) +- A name with words common in the category (e.g., "Pay" in fintech, "Code" in dev tools, "AI" in AI products) that gets lost in search + +**Test:** Search the name + category. If your name is buried under unrelated content or competitor confusion, fail. + +--- + +## 5. Stretchable + +A name that locks you into one product or category will hurt as you grow. + +**Pass:** +- "Amazon" - was a bookstore. Now sells everything. +- "Apple" - was a computer company. Now does phones, music, services. +- "Stripe" - "stripe of code" implied developer tools. Now does broader fintech. + +**Fail:** +- "TomatoTracker" - locked to tomatoes +- "PDFMonkey" - locked to PDFs +- Names that explicitly describe a single product feature, when the company plans to be more than that single feature + +**Note:** Locked-in names can be the right choice IF the company is committed to staying narrowly focused. "PDFMonkey" works if you genuinely just want to be the best PDF tool. The failure is when you outgrow the name and have to rebrand at scale. + +**Test:** Imagine the company in 5 years, expanded into adjacent categories. Does the name still fit? If not, plan for it. + +--- + +## 6. Free of negative associations + +A name that means something embarrassing in another language, or that already carries cultural baggage, will hit a ceiling. + +Check: + +- **Translations.** Run the name through a few major target market languages. Native speakers should review (translation tools miss nuance). +- **Slang.** Especially Gen Z and online slang shifts fast. A name that was clean five years ago may not be clean today. +- **Acronyms.** Some names form embarrassing acronyms when written in caps or in initialisms. +- **Visual confusions.** When written in certain fonts, do letters create unfortunate combinations? (Famous example: "kidsexchange" spelled as one word.) +- **Existing pop culture.** Is the name a character in a recent TV show, a banned topic, or a meme? + +**Pass:** +- Cleared in target markets, no recent cultural collisions, no embarrassing acronyms + +**Fail:** +- Names that translate to insults or anatomical terms in target markets +- Names that match recent meme content (the meme will fade but the association sticks) +- Names with unfortunate acronyms (e.g., "Strategic Health Initiative Team") + +**Test:** Native speakers in each target market review. Plus a 5-minute search of the name in pop culture context. + +--- + +## Scoring + +For each candidate name, score 1 to 5 on each of the six criteria, where 5 is "passes cleanly" and 1 is "definite fail." + +A name is short-listable if it scores 4 or 5 on every criterion. A 3 anywhere is a yellow flag (proceed with eyes open). A 2 or 1 anywhere is disqualifying. + +--- + +## Pragmatic notes + +- **Domains:** .com is still default for most US/global brands. Category-specific TLDs (.app, .ai, .io) work in some categories but require more brand investment to teach the audience. +- **Trademark:** Get a real attorney to clear the trademark before launch. The cost of a TM search is dramatically less than a rebrand. +- **Generic names** (descriptive of the category) cannot be trademarked and will struggle with distinctiveness. +- **Made-up names** are easier to clear and trademark but require more marketing investment to load with meaning. +- **Founder names** carry heritage but can complicate equity and exits. + +--- + +## When to walk away + +If the top 3 candidates all fail at least 2 criteria, the naming exploration was not deep enough. Generate another 30 to 50 candidates before settling. The cost of a bad name is paid every day for the life of the brand. diff --git a/skills/brand-identity/SKILL.md b/skills/brand-identity/SKILL.md new file mode 100644 index 0000000..f3a8ef8 --- /dev/null +++ b/skills/brand-identity/SKILL.md @@ -0,0 +1,203 @@ +--- +name: brand-identity +description: "Design or evaluate a brand visual identity system covering logo, color, typography, imagery direction, iconography, and motion principles. Use this skill whenever the user wants to design a logo, build a visual identity, define brand colors, choose brand typography, develop iconography, plan brand imagery, or evaluate an existing identity for cohesion. Triggers on logo design, brand identity, visual identity, brand mark, wordmark, monogram, color palette, brand colors, brand typography, type system, iconography, brand imagery, motion design, brand system, identity system. Also triggers when the user has a brand direction approved and now needs the visual artifacts that express it." +category: brand +catalog_summary: "Logo system, color, typography, imagery, iconography, motion" +display_order: 2 +--- + +# Brand Identity + +Design or evaluate the visual artifacts that express a brand: logo system, color, typography, imagery, iconography, and motion. Stack-agnostic. Tool-agnostic. + +This skill assumes a brand direction is already approved (positioning, mood, name). If not, run `brand-ideation` first. + +--- + +## When to use + +- Designing a logo system +- Defining a brand color palette +- Choosing brand typography +- Developing iconography or illustration style +- Defining imagery direction (photography, illustration) +- Establishing motion principles +- Auditing an existing identity for cohesion or gaps + +## When NOT to use + +- Brand direction is not yet defined (use `brand-ideation`) +- Documenting a finished system (use `brand-style-guide`) +- Defining voice and tone (use `brand-voice`) +- Building UI components from an existing brand (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- The brand name and approved positioning +- The mood direction (from ideation, or supplied as references) +- Audience and category context +- Application contexts (web, print, packaging, motion - whatever applies) +- Constraints (parent brand requirements, regulatory marks, accessibility minimums) + +--- + +## The framework: 5 elements + +A complete identity has five elements. Each element should reinforce the others. Inconsistency between them is the most common identity failure. + +### 1. Logo system + +Most brands need not one logo but a system of marks for different contexts. + +**Components of a logo system:** + +- **Primary mark.** The main logo. Used wherever there is room. +- **Wordmark.** Just the typography, no symbol. Used in tight horizontal contexts. +- **Symbol or glyph.** Just the symbol, no type. Used in app icons, favicons, social avatars. +- **Lockup variations.** Horizontal, stacked, square - whichever apply. +- **Monogram.** The initial(s) styled as a mark. Optional but useful for small contexts. + +**Design principles:** + +- **Legible at 16 pixels.** Test the logo at favicon size. If it falls apart, redesign. +- **Reproducible in single-color.** If the logo only works in full color, it cannot be screen-printed, embroidered, or rendered in browser favicons. +- **Distinctive silhouette.** Squint at it. Can you still tell what it is? If it looks like every other logo in the category at silhouette, redesign. +- **Construction grid.** Every curve and angle is intentional. Document the construction. + +**Common failure:** +- Designing only the primary mark and discovering at launch that the wordmark, glyph, and small-size variants do not exist. + +### 2. Color system + +A color system is more than a palette. It is the rules for how color carries meaning. + +**Components:** + +- **Primary color.** The signature color most associated with the brand. +- **Secondary colors.** 1 to 3 supporting colors that extend the palette. +- **Neutrals.** The grays and tints that make up most of the surface area. +- **Semantic colors.** Success, warning, error, info - if the brand operates in product UI. +- **Accent colors.** Used sparingly for highlight and emphasis. + +**Per color, document:** +- Hex, RGB, HSL, CMYK (if print is in scope), and Pantone (if brand-critical print exists) +- WCAG AA contrast against the other colors in the system +- Allowed and disallowed pairings (some brand colors look terrible together) +- Usage notes (when to use, when not to use) + +**Design principles:** + +- **Test for accessibility.** WCAG AA requires 4.5:1 contrast for normal text, 3:1 for large text. If the brand color cannot pass either against white, you have a problem. +- **Test for color blindness.** Around 8 percent of men have some form of color blindness. Critical UI signals should not rely on color alone. +- **Define neutrals carefully.** Neutrals are 80 percent of the surface area in most brand applications. They carry more weight than the brand color. +- **Limit the palette.** A 30-color palette is unmanageable. 5 to 8 carefully chosen colors beats a sprawling system. + +### 3. Typography + +Type is the second-most-recognizable element of a brand after the logo. + +**Components of a type system:** + +- **Display typeface.** For headlines and brand moments. +- **Body typeface.** For long-form reading. Often the same as display, sometimes different. +- **Monospace typeface** (if applicable for technical brands). +- **Type scale.** The set of sizes used across applications. Typically 5 to 8 steps. +- **Type weights and styles.** Which weights and italics are part of the system. + +**Design principles:** + +- **Pairing.** If using two typefaces, they must work together at body and display sizes. Common pattern: serif display + sans body, or geometric sans display + humanist sans body. +- **Web licensing.** Confirm web licensing covers expected pageviews. Some popular typefaces have prohibitive web licenses. +- **Variable fonts** are increasingly the right call for performance and flexibility. +- **Fallback stack.** Specify system fallbacks for when the brand font fails to load. The fallback should be visually similar. +- **Open-source alternatives.** Document open-source equivalents for situations where licensing is impractical (third-party tools, embedded contexts). + +### 4. Imagery and illustration + +Imagery direction is often underspecified, leading to brand drift over time. + +**Photography direction:** + +- **Subject matter.** What does the brand show? +- **Composition style.** Tight crops, wide environments, candid, posed? +- **Lighting.** Bright and natural, dramatic and directional, soft and diffused? +- **Color treatment.** True color, warm shifted, desaturated, high-contrast? +- **What to reject.** Stock photo aesthetics, specific cliches in the category. + +**Illustration direction:** + +- **Style.** Flat, dimensional, hand-drawn, geometric, abstract, representational? +- **Color use.** Full palette, restricted palette, brand colors only? +- **Line treatment.** Bold and outlined, soft and shaded, no outlines? +- **Subject matter.** What gets illustrated and what does not? + +**Iconography:** + +- **Style.** Filled or outline. Rounded or sharp. Single weight or variable. +- **Grid.** Pixel-perfect grid (often 24x24 or 16x16 base). +- **Stroke weight.** Consistent across the icon set. +- **Set.** Which icons exist, and how new icons get added consistently. + +### 5. Motion + +If the brand lives in any digital product, marketing video, or animated touchpoint, motion is part of the identity. + +**Motion principles to define:** + +- **Easing curves.** Default easings used across animations. Linear, ease-in-out, custom. +- **Duration scale.** Fast (100ms), medium (200-300ms), slow (500ms+) and when each applies. +- **Choreography.** How elements enter, exit, and respond to interaction. +- **Brand moments.** Signature animations (logo build, page transitions, loaders). + +**Design principles:** + +- **Restraint.** Most motion in product UI should be quick and subtle. Reserve dramatic motion for brand moments. +- **Reduced motion.** Always provide a `prefers-reduced-motion` alternative for users with vestibular sensitivities. +- **Performance.** Animations must be 60fps on the target devices. Profile before shipping. + +--- + +## Workflow + +1. **Confirm brand direction.** Positioning, mood, audience. If unclear, return to `brand-ideation`. +2. **Audit applications.** List every place the brand will appear (web, print, packaging, app, social, signage, video). The application contexts drive what the system needs to handle. +3. **Element-by-element design.** Start with logo and color, since these constrain typography. Then type. Then imagery, iconography, motion. +4. **Stress-test.** Apply the system to 3 to 5 mock applications (homepage, social post, business card, product UI, signage). Where does it break? Iterate. +5. **Document.** Each element with rules, examples, and dos/don'ts. This becomes the input to `brand-style-guide`. +6. **Get sign-off** before broad rollout. Identity changes after rollout are 10x the cost of changes during design. + +--- + +## Failure patterns + +- **Designing logos in isolation from application.** A logo that looks great on a hi-res mockup but illegible at favicon size is a design failure. +- **Picking a brand color without contrast testing.** A brand color that fails WCAG AA against white means UI built on the brand will be inaccessible by default. +- **Specifying typography without checking web licensing.** Discovering at deploy that the foundry charges per-pageview for the chosen typeface is a budget-buster. +- **Skipping imagery direction.** Without it, the brand becomes whatever stock photos the next person picks. +- **Treating motion as decoration.** Inconsistent motion erodes brand cohesion as fast as inconsistent color. +- **Designing only primary states.** What does the brand look like in error? In dark mode? In a localization where the wordmark needs to flip direction? These are not edge cases; they are the brand. + +--- + +## Output format + +Default output is a structured set of files: + +- `identity/logo/` - All logo variants (SVG primary, plus PNG/JPG exports at common sizes) +- `identity/colors.md` - Color system with hex codes, contrast ratios, usage rules +- `identity/typography.md` - Type system with scale, weights, fallbacks +- `identity/imagery.md` - Imagery direction with reference examples +- `identity/iconography/` - Icon set or icon style spec +- `identity/motion.md` - Motion principles +- `identity/applications/` - 3 to 5 application mockups stress-testing the system + +These feed directly into `brand-style-guide`. + +--- + +## Reference files + +- [`references/identity-system-spec.md`](references/identity-system-spec.md) - Detailed spec template for documenting each element. +- [`references/contrast-and-accessibility.md`](references/contrast-and-accessibility.md) - Accessibility checks for color and type, with the math. diff --git a/skills/brand-identity/references/contrast-and-accessibility.md b/skills/brand-identity/references/contrast-and-accessibility.md new file mode 100644 index 0000000..d0f964e --- /dev/null +++ b/skills/brand-identity/references/contrast-and-accessibility.md @@ -0,0 +1,188 @@ +# Contrast and Accessibility for Brand Identity + +A brand color choice that fails accessibility is a design defect. Every product, page, button, and label using that color inherits the failure. + +This reference walks through the math, the standards, and the practical implications. + +--- + +## The standards + +**WCAG 2.1 AA** is the minimum bar for most professional brand work. + +| Element | Required contrast ratio | +|---|---| +| Normal body text | 4.5:1 | +| Large text (18pt regular or 14pt bold) | 3:1 | +| UI components and graphical elements | 3:1 | + +**WCAG 2.1 AAA** is stricter. Required for some accessibility-focused products, optional but admirable for most. + +| Element | Required contrast ratio | +|---|---| +| Normal body text | 7:1 | +| Large text | 4.5:1 | + +--- + +## The math + +Contrast ratio is calculated as: + +``` +(L1 + 0.05) / (L2 + 0.05) +``` + +Where L1 is the relative luminance of the lighter color and L2 of the darker. Relative luminance comes from a weighted formula on RGB values that accounts for human perception (green contributes more than blue). + +**Quick contrast checker (run in browser console):** + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + return ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2) + ':1'; +} + +// Example +contrast('#FFFFFF', '#4B5563'); // returns '6.40:1' +``` + +--- + +## Common brand color failures + +These are color choices that look great in a logo but fail WCAG when used for text or UI: + +| Pairing | Ratio | Status | +|---|---|---| +| Light gray (#9CA3AF) on white | 2.85:1 | Fails AA | +| Bright yellow on white | 1.07:1 | Fails AAA, AA, and basic legibility | +| Bright orange (#FF9900) on white | 2.14:1 | Fails AA | +| Sky blue (#3B82F6) on white | 4.57:1 | Passes AA for normal text | +| Most "vibrant" brand reds on white | 3-4.5:1 | Borderline; check exact values | +| White text on bright orange | 2.14:1 | Fails AA | + +When in doubt, darken the brand color for text contexts. Keep the original hue for non-text brand expressions (logos, large graphics, decorative elements). + +--- + +## The "darker variant" strategy + +For brand colors that fail AA contrast, define a darker variant for use in text and UI. + +``` +Brand orange (signature): #FF9900 (used in logos, illustrations, large graphics) +Brand orange (text/UI): #B86600 (passes AA against white) +``` + +Both are "the brand color." The signature version is what people associate with the brand. The text variant is what enables accessible UI without abandoning the identity. + +This is standard practice. Most major brands have both versions, even if only the signature version is publicized. + +--- + +## Color blindness considerations + +Around 8 percent of men and 0.5 percent of women have some form of color vision deficiency. The most common is red-green (deuteranopia and protanopia). + +**Tests to run:** + +- **Red-green confusion.** Greens and reds at similar luminance look the same to deuteranopes. If your success/error indicators rely on red-green distinction, add an icon or text label. +- **Tritan simulation.** Less common but worth checking. Blues and yellows. +- **Greyscale conversion.** Convert your palette to grayscale. If two brand colors look identical in greyscale, they will be hard to distinguish for people with severe color blindness. + +**Tools:** Stark plugin (Figma), Coblis (online simulator), Chrome DevTools rendering tab. + +**Practical rule:** Critical UI signals must communicate through more than just color. Use icons, labels, position, or shape as redundant signals. + +--- + +## Typography contrast + +Type contrast is not just about color. It includes: + +- **Color contrast** (per the standards above) +- **Weight contrast** (light text on a busy background fails even at high color contrast) +- **Size contrast** (very small text needs higher color contrast) + +**Practical rules:** + +- Body text: minimum 14px on web, ideally 16px. Below 14px is uncomfortable for most readers regardless of contrast. +- Body text on photographs or busy backgrounds: add a scrim, increase the type weight, or move the text. +- Light-weight fonts (Thin, Extra Light) for body text: avoid. They fail visual contrast even at passing color contrast. + +--- + +## Dark mode considerations + +Most brand colors that work on white do not work on dark backgrounds. + +**Common failure:** +- Brand color = dark navy. On white: 12:1 contrast (excellent). On near-black: 1.4:1 (terrible). + +**Solutions:** + +- Define light-mode AND dark-mode variants of every functional color in the system. +- Brand colors typically need to be lightened or desaturated in dark mode. +- Test the entire palette against both light and dark surfaces. + +``` +Brand navy: + Light mode (on white): #0F2A4A (12:1 contrast) + Dark mode (on #111): #6B9FE8 (5.2:1 contrast against #111) +``` + +Both are "the brand color." Both express the identity. They just live in different lighting conditions. + +--- + +## Icons and graphical elements + +WCAG requires 3:1 for UI components and graphical elements. This includes: + +- Icons used to convey meaning +- Form field borders +- Focus indicators +- Chart elements that distinguish data series +- Toggle and switch states + +**Common failure:** +- Light gray icon (#D1D5DB) on white background: 1.4:1. Invisible to users with low vision. +- Form field borders at #E5E7EB: 1.3:1. Borderline visible. + +**Fix:** +- Icons that convey meaning: minimum #6B7280 on white (3.9:1). +- Form field borders: minimum #9CA3AF on white (3.0:1) for default state. Stronger for focus. + +--- + +## Practical checklist for brand color decisions + +Before locking a brand color: + +- [ ] Tested against white at WCAG AA for body text (4.5:1) +- [ ] Tested against white at WCAG AA for large text (3:1) +- [ ] Tested against the brand's dark surface color (for dark mode) +- [ ] Tested for color blindness (deuteranopia simulation) +- [ ] A "darker variant" defined for text contexts if signature color fails AA +- [ ] White text on the brand color tested for 4.5:1 (for buttons and CTAs) +- [ ] All semantic colors (success, warning, error) pass AA on white and dark +- [ ] Neutrals scale tested across the full range + +If any check fails, document the failure and provide an alternative variant for the failing context. Do not just hope it will be fine in practice. It will not be fine. + +--- + +## Resources + +- WebAIM Contrast Checker (free, browser-based) +- Stark plugin for Figma +- Chrome DevTools accessibility panel +- Coblis color blindness simulator +- WCAG 2.1 specification at w3.org diff --git a/skills/brand-identity/references/identity-system-spec.md b/skills/brand-identity/references/identity-system-spec.md new file mode 100644 index 0000000..4b08849 --- /dev/null +++ b/skills/brand-identity/references/identity-system-spec.md @@ -0,0 +1,212 @@ +# Identity System Spec + +A spec template for documenting each element of the brand identity system. This is the working document during identity build, before the polished style guide. It locks decisions and exposes gaps. + +Fill every section. The point of the spec is to surface what is undecided. + +--- + +## System metadata + +**Brand:** [Name] +**Version:** [v1.0, v1.1, etc.] +**Date:** [YYYY-MM-DD] +**Owner:** [Name] +**Status:** [Draft / In review / Approved] + +--- + +## 1. Logo system + +### Primary logo + +- **Form:** [Wordmark / lettermark / combination mark / pictorial / abstract] +- **Construction notes:** [Geometry, custom letterforms, optical adjustments] +- **Source files:** [SVG, AI, layered] +- **Color versions:** [Full color, single color, reversed (white on dark)] +- **Minimum size:** [Pixels for digital, inches/mm for print] +- **Clear space:** [Minimum margin around logo, defined as multiple of a logo element, e.g., "1x cap height"] + +### Logo variants + +| Variant | When to use | Source file | +|---|---|---| +| Horizontal | Default | | +| Stacked | Constrained widths, social avatars | | +| Mark only | Favicons, app icons, watermarks | | +| Wordmark only | Inline text contexts | | + +### Misuse rules + +What never to do with the logo. Ten short rules at most. + +- Do not stretch +- Do not rotate +- Do not recolor outside the approved palette +- Do not place on busy photography without a scrim +- (etc.) + +### Application examples + +Where the logo lives. Document the canonical placements. + +- Web header: [Position, size, color treatment] +- Email signature: [Position, size] +- Favicon: [Variant used, sizes generated] +- App icon: [Variant, background, padding] +- Print: [Letterhead, business card] +- Social: [Avatar variant, banner specs] + +--- + +## 2. Color + +### Primary palette + +| Token name | Hex | RGB | HSL | Usage | +|---|---|---|---|---| +| `color-brand-primary` | | | | Primary brand color, dominant in identity | +| `color-brand-secondary` | | | | Secondary brand color | +| `color-brand-tertiary` | | | | Optional accent | + +### Neutrals + +| Token name | Hex | Usage | +|---|---|---| +| `color-neutral-0` | #FFFFFF | Background, max contrast | +| `color-neutral-50` | | | +| `color-neutral-100` | | | +| `color-neutral-200` | | | +| ... | | | +| `color-neutral-900` | | | +| `color-neutral-1000` | #000000 | | + +### Semantic tokens + +| Token name | Resolves to | Usage | +|---|---|---| +| `color-text-primary` | | Body text | +| `color-text-secondary` | | Captions, less important text | +| `color-text-disabled` | | Disabled state | +| `color-text-inverse` | | Text on dark backgrounds | +| `color-bg-primary` | | Default background | +| `color-bg-elevated` | | Cards, modals | +| `color-border-default` | | Card borders, dividers | +| `color-success` | | | +| `color-warning` | | | +| `color-error` | | | +| `color-info` | | | + +### Color rules + +- Never invent a new color. If a use case is not covered, propose a new token. +- Brand color contrast against approved backgrounds must meet WCAG AA for text. See `contrast-and-accessibility.md`. +- Dark mode tokens defined separately or via theme switch logic. + +--- + +## 3. Typography + +### Type families + +| Role | Family | Weights used | License | +|---|---|---|---| +| Display | | | | +| Body | | | | +| Mono (code, data) | | | | + +### Type scale + +| Token | Size | Line height | Weight | Use case | +|---|---|---|---|---| +| `text-display-1` | | | | Hero headline | +| `text-display-2` | | | | Section headline | +| `text-h1` | | | | Page title | +| `text-h2` | | | | Section title | +| `text-h3` | | | | Sub-section | +| `text-body-lg` | | | | Lead paragraph | +| `text-body` | | | | Default body | +| `text-body-sm` | | | | Caption, supporting text | +| `text-label` | | | | UI labels | +| `text-overline` | | | | Eyebrow text | + +### Typography rules + +- Display weights only at display sizes. Do not use display weights for body. +- Body line height target 1.5 to 1.65 for readability. +- Line length target 50 to 75 characters per line. +- Avoid mixing more than two type families on a single page. + +--- + +## 4. Iconography + +- **Style:** [Outline / filled / mixed / two-tone] +- **Stroke weight:** [Specific px or em value] +- **Corner radius:** [Specific px] +- **Grid:** [24x24 default, with optional 16, 32, 48 sizes] +- **Source:** [Custom set / Lucide / Heroicons / Phosphor / Material] +- **Naming convention:** [`icon-[noun]-[modifier]`] +- **License:** [If using a third-party set] + +### Icon rules + +- Icons paired with labels by default. Icon-only buttons require an accessible label. +- Decorative icons get `aria-hidden="true"`. +- Functional icons inherit text color via `currentColor`. + +--- + +## 5. Imagery + +### Photography + +- **Style:** [Editorial / lifestyle / product / documentary / abstract] +- **Color treatment:** [Natural / treated / desaturated / signature filter] +- **Composition:** [Tight / wide / asymmetrical / symmetrical / negative space] +- **Subject direction:** [Demographics, environments, energy] + +### Illustration + +- **Style:** [If applicable - flat / textured / line / mixed] +- **Color usage:** [Limited palette / full palette] +- **Pattern library:** [Where it lives] + +### Stock and AI policy + +- **Stock photography:** [Allowed / banned / case-by-case with approval] +- **AI-generated imagery:** [Allowed / banned / case-by-case] +- **Sources approved:** [Specific platforms or studios] + +--- + +## 6. Motion + +- **Default duration:** [ms - typically 200-300] +- **Default easing:** [Standard easing curve, e.g., `cubic-bezier(0.4, 0, 0.2, 1)`] +- **Token naming:** [`motion-duration-fast`, `motion-easing-standard`] +- **Reduced motion:** [What animates becomes static when `prefers-reduced-motion: reduce`] + +--- + +## 7. Voice (cross-reference) + +Voice has its own deliverable. See the brand voice document. The identity spec only notes voice attributes that interact with visual identity (e.g., if voice is "quiet," typography should not be loud). + +--- + +## Open questions + +- [ ] [Token naming convention finalized?] +- [ ] [Dark mode strategy defined?] +- [ ] [Brand color WCAG contrast verified across approved backgrounds?] +- [ ] [Icon set licensed for production?] +- [ ] [Photography source defined?] + +--- + +## Sign-off + +- Design lead: [Name, date] +- Creative director: [Name, date] +- Engineering lead (for token implementability): [Name, date] diff --git a/skills/brand-style-guide/SKILL.md b/skills/brand-style-guide/SKILL.md new file mode 100644 index 0000000..a852bf3 --- /dev/null +++ b/skills/brand-style-guide/SKILL.md @@ -0,0 +1,202 @@ +--- +name: brand-style-guide +description: "Build or audit a comprehensive brand style guide that documents the full brand system including story, logo system, color, typography, imagery, voice, applications, and dos/don'ts. Use this skill whenever the user wants to create brand guidelines, document an existing brand, build a brand book, audit an existing style guide for completeness, or produce the artifact that other teams will reference for years. Triggers on style guide, brand guidelines, brand book, brand standards, brand manual, style sheet, brand documentation, brand reference. Also triggers when the brand identity is finished and needs to be documented for handoff to designers, developers, vendors, or future team members." +category: brand +catalog_summary: "The canonical reference document for the full brand system" +display_order: 3 +--- + +# Brand Style Guide + +Document the brand system so other people can use it without ambiguity. This is the artifact that lives longest. Designers, developers, agencies, and vendors will reference it for years. Build it like a reference manual, not a presentation. + +This skill assumes the brand identity is designed (run `brand-identity` first if not). The output of this skill is the canonical reference document. + +--- + +## When to use + +- Creating brand guidelines for a finished identity +- Documenting an existing brand that has no formal guide +- Auditing an existing style guide for gaps or inconsistencies +- Building a brand book to hand to vendors, partners, or new team members +- Updating a guide after a major brand evolution + +## When NOT to use + +- The brand identity is not yet designed (use `brand-identity`) +- Brand voice work specifically (use `brand-voice` for the voice doc, then integrate) +- Building UI components (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- Finished brand identity (logo, colors, typography, imagery direction, motion principles) +- Brand voice and tone documentation (or sufficient inputs to write a voice section) +- Application examples that show the brand in real contexts +- Decisions on what is mandatory vs flexible vs forbidden + +--- + +## The framework: 8 sections + +A complete style guide has eight sections. Most guides skip 2 or 3 of them and create downstream confusion. Build all 8 from the start. + +### 1. Story +The narrative behind the brand. Why it exists, what it stands for, what it rejects. + +- Origin / founding story +- Mission and vision +- Values (3 to 5, with what each means in practice) +- Positioning statement +- Audience (with the level of specificity from the brief) +- What we are not (the things we explicitly reject) + +### 2. Logo system +Every variant of every mark, with rules. + +- Primary logo (with construction grid showing relationships) +- Wordmark +- Symbol / glyph +- Lockup variations (horizontal, stacked, etc.) +- Monogram (if part of system) +- Clear space rules (minimum spacing around logo) +- Minimum sizes (smallest acceptable size for print and digital) +- Acceptable color treatments (full color, single color, knock-out, reverse) +- Forbidden treatments (stretching, rotating, recoloring, drop shadows, gradients - whatever is forbidden) +- File formats and where to find them + +### 3. Color +The full color system with rules. + +- Primary palette (signature colors) +- Secondary palette +- Neutrals scale +- Semantic colors (success, warning, error, info) +- Light mode and dark mode variants +- Per color: hex, RGB, HSL, CMYK, Pantone (if print-relevant) +- Contrast ratios documented +- Allowed pairings +- Forbidden pairings +- Usage hierarchy (primary first, secondary supporting, neutrals dominant) + +### 4. Typography +The full type system. + +- Display typeface (with sample sizes) +- Body typeface (with sample sizes) +- Monospace (if applicable) +- Type scale (specific sizes used) +- Weight and style usage (which weights for which contexts) +- Line height ratios +- Letter spacing standards +- Web fallback stacks +- Open-source alternatives for licensing-restricted contexts +- Forbidden treatments (all caps overuse, fake italics, etc.) + +### 5. Imagery and illustration +What pictures look like in this brand. + +- Photography direction with example library +- Illustration style with example library +- Iconography system with the full icon set (or rules for adding to it) +- Forbidden imagery (stock photo cliches, specific things never to show) +- Photo treatment rules (color treatment, crops, composition) + +### 6. Voice and tone +How the brand sounds. (Pulled from `brand-voice` work if done separately.) + +- Voice attributes (3 to 5 adjectives with "we are X, not Y" framing) +- Tone shifts by context (onboarding, error, marketing, support, legal) +- Vocabulary preferences (words we use, words we avoid) +- Grammar and style rules +- Examples (good and bad copy side by side) + +### 7. Applications +The brand applied to real contexts. + +- Web (homepage, product pages, blog template) +- Email (template, signature, transactional) +- Social (post templates, profile imagery, story formats) +- Print (business cards, letterhead, print ads) +- Packaging (if applicable) +- Signage (if applicable) +- Internal documents (slides, reports, proposals) +- Each with examples showing what good looks like + +### 8. Dos and don'ts +The boundaries, illustrated. + +- Logo dos and don'ts (visual examples of correct and incorrect use) +- Color dos and don'ts (combinations to use, combinations to avoid) +- Type dos and don'ts (treatments to use, treatments to avoid) +- Composition dos and don'ts (layout patterns that work, ones that do not) +- Voice dos and don'ts (phrases that fit, phrases that do not) + +The dos and don'ts section is what people actually reference in practice. Make it the easiest section to scan. + +--- + +## Workflow + +1. **Inventory the inputs.** What identity work is finished? What voice work is finished? What is missing? +2. **Confirm the format.** Is this a PDF, a web page, a Notion doc, a printed book, or all of the above? Different formats have different production requirements. +3. **Section by section, draft.** Use the template in [`references/style-guide-template.md`](references/style-guide-template.md). +4. **Stress-test with real examples.** For every rule, find a real application example. Rules without examples get ignored. +5. **Get review from the people who will use it.** Designers, developers, marketers. They will surface gaps. +6. **Version control.** Style guides evolve. Date the doc. Note what changed in each version. +7. **Publish in the format the team will actually open.** A 200-page PDF that lives on a shared drive is dead weight. A web page or Figma file with a clear URL gets used. + +--- + +## Failure patterns + +- **Skipping the "what we are not" sections.** Without rejection rules, anything becomes acceptable. +- **Document with no examples.** Rules without visual examples are abstract and ignored. +- **Document with only examples.** Examples without rules cannot be applied to new situations. +- **Static PDF that no one opens.** Ship the guide in the format the team uses daily (web page, Figma, Notion, etc.). +- **No version history.** When the brand evolves, no one knows which rules changed or when. +- **Aspirational rules.** Rules the brand does not actually follow get treated as suggestions. Document what is actually true, not what is wished. +- **Treating "dos and don'ts" as filler.** This section is what people use most. Invest in it. + +--- + +## Output format + +Default output is a multi-section markdown document or a structured set of files, plus a presentation-ready version (web page, PDF, or Figma) for sharing with stakeholders. + +Recommended structure: + +``` +brand/ + style-guide.md (the canonical document) + story.md (or as a section) + logo/ + construction.md + files/ (SVG, PNG, etc.) + colors.md + typography.md + imagery/ + photography.md + illustration.md + icons/ + icons.md + files/ + voice.md + applications/ + web.md + email.md + social.md + print.md + dos-and-donts.md +``` + +For consumer-facing presentation, build a web page version that imports from these source files. The source files are canonical. The presentation is a view of them. + +--- + +## Reference files + +- [`references/style-guide-template.md`](references/style-guide-template.md) - Fillable section-by-section template. +- [`references/maintenance-playbook.md`](references/maintenance-playbook.md) - How to keep the guide current after launch. diff --git a/skills/brand-style-guide/references/maintenance-playbook.md b/skills/brand-style-guide/references/maintenance-playbook.md new file mode 100644 index 0000000..33e208d --- /dev/null +++ b/skills/brand-style-guide/references/maintenance-playbook.md @@ -0,0 +1,251 @@ +# Brand Style Guide Maintenance Playbook + +A style guide that does not get maintained becomes a museum piece within a year. This playbook covers who owns it, when it gets updated, and how change requests get handled. + +--- + +## Why guides decay + +The common failure modes: + +- **No owner.** The guide was a project deliverable. The team disbanded. No one maintains it. +- **Drift.** Real work in market diverges from the guide. The guide stops reflecting reality. +- **Frozen in time.** The guide was right at launch. Markets, products, and audiences moved. +- **Locked away.** The guide lives in a tool nobody opens. Teams reinvent rather than reference. +- **Too rigid.** The guide bans variation that real work demands. Teams ignore it rather than challenge it. + +The maintenance playbook addresses each of these. + +--- + +## Ownership + +### The owner + +Every brand guide has one owner. Not a committee. The owner: + +- Is named in the guide itself +- Has explicit authority to approve changes +- Has time allocated (typically 5-10% of one role) for guide upkeep +- Reports to a stakeholder who cares about brand consistency + +If the role is vacant, the guide is at risk regardless of how good the content is. + +### The guidance council (optional) + +For larger organizations, a small council reviews proposed changes before the owner approves. Typically: + +- Brand lead (chair) +- Design lead +- Marketing lead +- Engineering lead (if guide includes design tokens / dev assets) +- One product representative + +The council meets quarterly to review the change queue. + +--- + +## Change types and authority + +Not every change needs the same review. Define tiers. + +### Tier 1: clarifications (owner approves directly) + +- Typo fixes +- Adding examples to existing rules +- Improving wording without changing meaning +- Adding missing assets that are already approved (new logo file format, etc.) + +**Process:** owner ships within a week. + +### Tier 2: extensions (owner consults, then approves) + +- New use cases for existing elements +- New approved color combinations +- New typographic patterns within the existing scale +- New illustration or photography patterns within existing direction + +**Process:** owner posts to a working channel for 5-day comment period, addresses feedback, ships. + +### Tier 3: changes (council reviews, owner ships) + +- Modifying or expanding the color palette +- Modifying the type scale +- Adding or removing approved photographic styles +- Updating logo construction or variants +- Voice tone adjustments + +**Process:** RFC document, council review at quarterly meeting (or async if time-sensitive), then owner ships. + +### Tier 4: shifts (executive approval required) + +- Logo redesign +- Brand voice repositioning +- Color palette overhaul +- Naming or positioning changes + +**Process:** full brand project. Treat as a separate engagement, not a maintenance ticket. + +--- + +## Update cadence + +Even without inbound change requests, schedule reviews. + +| Cadence | What happens | +|---|---| +| Monthly | Owner sweeps the change queue, ships Tier 1 fixes, queues Tier 2 for the comment period. | +| Quarterly | Council reviews Tier 3 RFCs, takes a sample-based audit (see below), updates roadmap. | +| Annually | Full audit (see audit playbook), refresh of examples, prune of stale content, version bump. | +| As-needed | Tier 4 shifts driven by business strategy. | + +--- + +## Change request process + +Anyone in the organization can propose a change. The process: + +1. **Submit** via the request channel (template below). +2. **Triage** by owner within 5 business days. Assigns tier. +3. **Comment / review** depending on tier. +4. **Decide.** Approve, decline (with reason), or revise. +5. **Ship.** Update the guide, update related assets, communicate. +6. **Communicate.** Announce in the brand channel. Note in the changelog. + +### Request template + +``` +**What is the change?** +[One paragraph] + +**Why is it needed?** +[Real use case that surfaced this] + +**What is affected?** +[Pages, assets, components] + +**Proposed solution** +[Specific change to the guide] + +**Alternatives considered** +[Other ways to solve this] + +**Requester** +[Name, team] +``` + +--- + +## Audit cadence + +### Monthly: surface scan + +Owner scans 5-10 randomly selected production touchpoints (web pages, ads, emails, social posts) and notes any guide violations or undocumented patterns. 30 minutes max. + +The output is a row in a tracking sheet, not a deliverable. Used to surface drift trends. + +### Quarterly: sample audit + +Owner (or council) audits 20-30 production touchpoints across channels. Categorize each: + +- Compliant +- Minor deviation (acceptable, document if recurring) +- Major deviation (followup required) +- Undocumented pattern (consider adding to guide) + +Output: a one-page summary with action items. + +### Annual: full audit + +Use the audit template (typically a separate audit deliverable, not part of the guide itself). Full review across: + +- Logo usage +- Color +- Typography +- Imagery +- Voice and copy +- Motion and interaction +- Adoption (which teams use the guide vs work around it) + +Output: a backlog for the next year. + +--- + +## Versioning + +Use semantic versioning for the guide. + +- **Major (1.0 → 2.0):** brand shift. Logo redesign, voice repositioning, palette overhaul. +- **Minor (1.1 → 1.2):** new sections, expanded color or type, new approved patterns. +- **Patch (1.1.1 → 1.1.2):** clarifications, typo fixes, new examples. + +Each version has a changelog entry: what changed, who approved, when, and migration notes if any. + +### Backward compatibility window + +When a Tier 3 or Tier 4 change ships, set a deprecation window: + +- **Tier 3:** 90 days. Old patterns acceptable in production, new patterns required for new work. +- **Tier 4:** 6-12 months depending on production cycle (print catalogs, manufactured goods, regulatory deliverables may need longer). + +Document deprecated patterns with a clear "Replaced by [new pattern], deprecated as of [date], removal date [date]" note. + +--- + +## Communication + +When the guide changes, people need to know. + +### Channels + +- **Brand channel:** standing channel for all updates, requests, questions. +- **Changelog page in the guide:** running list of versioned changes. +- **Quarterly digest email:** roundup of the past quarter's changes, plus the audit summary. +- **Annual review post:** the year's biggest changes, the audit findings, the next year's priorities. + +### When to push, when to publish + +- **Push** (announce, require attention) for Tier 3 and Tier 4 changes. +- **Publish** (update the guide and the changelog, no broadcast) for Tier 1 and Tier 2. + +--- + +## Adoption health metrics + +The guide is healthy when teams use it. Track: + +| Metric | Healthy | Warning | Failing | +|---|---|---|---| +| Average page views per month | Steady or growing | Declining | Near-zero | +| Change requests per quarter | 5-15 | <3 | 0 (or 50+) | +| Audit compliance score (Tier 3+) | >90% | 75-90% | <75% | +| Percent of new launches that referenced the guide pre-launch | >80% | 50-80% | <50% | +| Time to ship a clarification | <1 week | 1-4 weeks | >4 weeks | + +If multiple metrics are failing simultaneously, the guide needs a refresh, not just maintenance. + +--- + +## When to retire and rewrite + +Sometimes maintenance is not enough. Signs the guide needs a rewrite: + +- The brand has shifted enough that >30% of the guide no longer applies +- The audience or category has shifted enough that the brand position is dated +- A new owner cannot make sense of the structure +- The guide reads as if it was written for a different company +- Compliance has fallen below 60% across multiple audits + +Rewriting is not a maintenance task. It is a separate brand project. The maintenance playbook ends when the rewrite begins. + +--- + +## Sign-off + +Maintenance plan accepted by: + +- Brand owner: [Name, date] +- Council members: [Names, date] +- Executive sponsor: [Name, date] + +Next quarterly review: [Date] diff --git a/skills/brand-style-guide/references/style-guide-template.md b/skills/brand-style-guide/references/style-guide-template.md new file mode 100644 index 0000000..a55b540 --- /dev/null +++ b/skills/brand-style-guide/references/style-guide-template.md @@ -0,0 +1,407 @@ +# [Brand Name] Style Guide + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Maintained by:** [Team or person] +**Format:** This document is canonical. Other formats (PDF, web page, Figma) are views of this document. + +--- + +## How to use this guide + +[1 to 2 paragraphs explaining what the guide is for, who it serves, and where to go with questions.] + +**Quick links:** +- [Logo files](#logo-files) +- [Color values](#color-values) +- [Typography](#typography) +- [Voice cheat sheet](#voice) +- [Dos and don'ts](#dos-and-donts) + +--- + +## 1. Story + +### Origin +[1 to 3 paragraphs. Why this brand exists. The problem it solves. The moment it began.] + +### Mission +[One sentence. What we are trying to do in the world.] + +### Vision +[One sentence. The future we are pulling toward.] + +### Values + +We hold [N] values. + +**[Value 1]** +[What it means in practice. 2 to 3 sentences. Include a behavioral example.] + +**[Value 2]** +[Same structure.] + +**[Value 3]** +[Same structure.] + +### Positioning + +[The positioning statement. One paragraph. What we offer, to whom, and what makes us different.] + +### Audience + +**Primary:** [Who, with specificity] + +**Secondary:** [Who, briefly] + +**Anti-personas:** [Who we are not for] + +### What we are not + +- [Thing we explicitly reject] +- [Thing we explicitly reject] +- [Thing we explicitly reject] + +--- + +## 2. Logo system + +### Primary logo + +[Image of primary logo] + +[Description: what it is, what it represents, when to use it.] + +### Wordmark + +[Image of wordmark] + +[Description and usage.] + +### Symbol / glyph + +[Image of glyph] + +[Description and usage.] + +### Lockup variations + +[Images of horizontal, stacked, square variants.] + +### Construction + +[Image showing construction grid, proportions, key relationships.] + +### Clear space + +[Image showing minimum clear space around the logo.] + +The logo requires minimum clear space equal to [X] on all sides. + +### Minimum sizes + +| Format | Minimum size | +|---|---| +| Digital primary | [Xpx] wide | +| Print primary | [Xmm] wide | +| Favicon | [Xpx] | +| Mobile | [Xpx] | + +### Color treatments + +**Allowed:** +- Full color on white +- Full color on light backgrounds (with [contrast rule]) +- Single color on light backgrounds +- White (knockout) on dark backgrounds +- Single color black + +**Forbidden:** +- [Specific forbidden treatment with example image] +- [Specific forbidden treatment with example image] + +### Logo files + +| File | Use case | Path | +|---|---|---| +| logo-primary.svg | Web primary | /brand/logo/primary.svg | +| logo-wordmark.svg | Tight horizontal | /brand/logo/wordmark.svg | +| logo-symbol.svg | App icon, favicon | /brand/logo/symbol.svg | +| logo-monogram.svg | Tiny contexts | /brand/logo/monogram.svg | +| [more files] | | | + +--- + +## 3. Color + +### Primary palette + +| Name | Hex | RGB | Use | +|---|---|---|---| +| [Name] | #XXXXXX | (R,G,B) | [Use case] | +| [Name] | #XXXXXX | (R,G,B) | [Use case] | + +### Secondary palette + +[Same table structure] + +### Neutrals + +[Same table structure] + +### Semantic colors + +| Name | Hex | Use | +|---|---|---| +| Success | #XXXXXX | Positive states, confirmations | +| Warning | #XXXXXX | Caution, attention needed | +| Error | #XXXXXX | Errors, destructive actions | +| Info | #XXXXXX | Neutral information | + +### Dark mode variants + +| Color | Light mode | Dark mode | +|---|---|---| +| Brand primary | #XXXXXX | #XXXXXX | +| Body text | #XXXXXX | #XXXXXX | +| Surface | #FFFFFF | #XXXXXX | + +### Contrast ratios + +[For each meaningful pairing, document the ratio and pass/fail.] + +| Pairing | Ratio | WCAG | +|---|---|---| +| Brand primary on white | X.X:1 | Pass AA / Pass AAA | +| Body text on white | X.X:1 | Pass AA | + +### Allowed pairings + +[List or visual showing which colors work together.] + +### Forbidden pairings + +[List or visual showing combinations not to use.] + +--- + +## 4. Typography + +### Display typeface + +**[Typeface name]** + +[Sample at large size] + +Used for: [Headlines, hero copy, brand moments] + +Weights used: [list] + +### Body typeface + +**[Typeface name]** + +[Sample at body size] + +Used for: [Long-form reading, paragraphs] + +Weights used: [list] + +### Monospace (if applicable) + +**[Typeface name]** + +Used for: [Code, technical data] + +### Type scale + +| Step | Size | Weight | Line height | Letter spacing | Use | +|---|---|---|---|---|---| +| Display 1 | 64 | 700 | 1.0 | -0.02em | Hero headlines | +| Display 2 | 48 | 700 | 1.05 | -0.01em | Section headers | +| H1 | 36 | 700 | 1.1 | 0 | Page titles | +| H2 | 28 | 600 | 1.2 | 0 | Section titles | +| H3 | 22 | 600 | 1.3 | 0 | Sub-sections | +| Body Large | 18 | 400 | 1.5 | 0 | Lead paragraphs | +| Body | 16 | 400 | 1.6 | 0 | Default body | +| Small | 14 | 400 | 1.5 | 0 | Captions, metadata | +| Caption | 12 | 400 | 1.4 | 0.01em | Footnotes, labels | + +### Web fallback stack + +``` +font-family: '[Brand display]', '[OS fallback 1]', '[OS fallback 2]', sans-serif; +``` + +### Open-source alternatives + +For contexts where the licensed brand fonts are impractical (third-party tools, embeds), use: + +- Display alternative: [Open-source typeface name] +- Body alternative: [Open-source typeface name] + +### Forbidden treatments + +- [No fake italics] +- [No fake bold] +- [No all-caps body text] +- [Other forbidden treatments] + +--- + +## 5. Imagery and illustration + +### Photography + +**Subject matter:** [What we photograph] + +**Style:** [Composition, lighting, color treatment] + +**What we reject:** [Stock photo aesthetics, specific cliches] + +**Examples:** +[Include 4 to 6 example images] + +### Illustration + +**Style:** [Description] + +**Color use:** [Rules] + +**Examples:** +[Include 4 to 6 example illustrations] + +### Iconography + +**Style:** [Filled / outline / mixed] + +**Grid:** [Base grid size] + +**Stroke weight:** [Specification] + +**Set:** +[Include the icon set or rules for adding new icons] + +--- + +## 6. Voice and tone + +### Voice attributes + +We sound: [adjective], [adjective], [adjective], [adjective], [adjective]. + +We do not sound: [opposite], [opposite], [opposite], [opposite], [opposite]. + +| We are | We are NOT | +|---|---| +| [Adjective] | [What it could tip into] | +| [Adjective] | [What it could tip into] | +| [Adjective] | [What it could tip into] | + +### Tone shifts + +| Context | Tone | +|---|---| +| Onboarding | [Description] | +| Error states | [Description] | +| Success states | [Description] | +| Marketing | [Description] | +| Support | [Description] | +| Legal | [Description] | + +### Vocabulary preferences + +**Use:** [Words and phrases that fit] + +**Avoid:** [Words and phrases that do not fit] + +### Sample copy + +**Bad (off-voice):** +> [Example] + +**Good (on-voice):** +> [Example] + +--- + +## 7. Applications + +### Web + +[Show 2 to 3 example layouts: homepage, product page, blog template] + +### Email + +[Show template, signature, transactional examples] + +### Social + +[Show post templates, profile imagery, story formats] + +### Print (if applicable) + +[Show business cards, letterhead, print examples] + +### Packaging (if applicable) + +[Show packaging examples] + +### Internal documents + +[Show slide template, report template, proposal template] + +--- + +## 8. Dos and don'ts + +### Logo + +| Do | Don't | +|---|---| +| [Visual example with caption] | [Visual example with caption] | +| | | + +### Color + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Type + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Composition + +| Do | Don't | +|---|---| +| [Visual example] | [Visual example] | +| | | + +### Voice + +| Do | Don't | +|---|---| +| "[Example phrase]" | "[Example phrase]" | +| | | + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial publication | + +--- + +## Contact + +Questions or requests for clarification: [contact info] + +To suggest changes: [process] diff --git a/skills/brand-voice/SKILL.md b/skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b5c55f1 --- /dev/null +++ b/skills/brand-voice/SKILL.md @@ -0,0 +1,193 @@ +--- +name: brand-voice +description: "Develop or document a complete brand voice and tone system covering voice attributes, tone shifts by context, vocabulary preferences, grammar rules, and copy examples. Use this skill whenever the user wants to define how a brand sounds, write a voice and tone document, audit existing copy for voice consistency, train a team or AI assistant on brand voice, or refine the personality of brand writing. Triggers on brand voice, voice and tone, tone of voice, writing voice, brand personality, copy voice, voice document, voice guidelines, how should we write, voice training, voice audit. Also triggers when the user has copy that 'feels off' and the underlying issue is voice, even if not stated explicitly." +category: brand +catalog_summary: "Voice attributes, tone shifts, vocabulary, paired-example library" +display_order: 4 +--- + +# Brand Voice + +Define how a brand sounds in writing. Document it in a way that anyone (writer, designer, founder, AI assistant) can apply it consistently. + +This skill produces a standalone voice document that can either live in the brand style guide or feed into it. + +--- + +## When to use + +- Defining brand voice for the first time +- Auditing existing copy for voice consistency +- Training a team, freelancer, or AI assistant on the brand voice +- Refining a voice that exists but is inconsistent across applications +- Adapting voice when a brand evolves (new audience, new positioning) + +## When NOT to use + +- Writing specific copy (use `content-and-copy`) +- Brand visual identity work (use `brand-identity`) +- Documenting a complete brand system (use `brand-style-guide`, which incorporates voice) +- Initial brand exploration (use `brand-ideation`) + +--- + +## Required inputs + +- The brand and its positioning +- The audience and what they need to hear +- 5 to 10 examples of existing brand writing (if any) +- 3 to 5 reference brands whose voice resonates with where this brand should go +- Any voice attributes already specified in the brief + +--- + +## The framework: 4 layers + +Voice has four layers, stacked. Each layer constrains the one below it. + +### Layer 1: Voice attributes + +The constants. The personality traits that define how the brand sounds across every context. + +Pick 3 to 5 attributes. Pair each with what it is NOT (the failure mode if overdone). + +Common attribute pairings (NOT a menu - generate your own): + +- Confident, not arrogant +- Direct, not blunt +- Warm, not saccharine +- Witty, not sarcastic +- Smart, not academic +- Honest, not harsh +- Playful, not silly +- Practical, not boring +- Bold, not loud +- Curious, not unfocused + +The "not" half is what saves writers from overshooting. "Confident" alone produces swagger. "Confident, not arrogant" tells writers where the line is. + +### Layer 2: Tone shifts + +Voice is constant. Tone adapts to context. + +Map the major contexts the brand writes in. For each, document how voice expresses differently. + +Common contexts: + +| Context | Tone shift | +|---|---| +| Onboarding | Warmer, more enthusiastic, slightly slower pace | +| Hero / marketing | Confident, signature voice fully on | +| Product copy / UX | Direct, helpful, brief | +| Error messages | Calm, matter-of-fact, no apology theater | +| Success states | Brief celebration, redirect to next action | +| Empty states | Helpful, slightly playful, suggest action | +| 404 / not found | Self-aware, light, points the way home | +| Account deletion / cancellation | Quiet, respectful, no jokes | +| Pricing | Direct, transparent, confidence-inspiring | +| Legal / TOS | Plain language version sits next to the legal version | +| Support / help center | Patient, thorough, no condescension | +| Crisis communication | Calm, factual, accountable | +| Product announcements | Excited but not breathless | +| Email subject lines | Specific, never click-bait | + +Voice stays consistent across all of these. Tone is what shifts. + +### Layer 3: Vocabulary and grammar + +The granular dial settings. + +**Vocabulary preferences:** + +- Words and phrases the brand uses +- Words and phrases the brand avoids +- Words the brand has redefined (if any) - e.g., a SaaS product calling its features "huddles" instead of "meetings" +- Industry jargon: keep it (signals expertise) or strip it (signals approachability) +- Sentence-opening preferences (some brands lean on imperatives, some on questions, some on statements) + +**Grammar and style:** + +- Contractions (use them = casual, avoid them = formal) +- Sentence length default (short = punchy, medium = considered, long = literary) +- Punctuation marks favored or avoided (em dash is famously polarizing) +- Pronouns ("we" / "you" / "I") +- Capitalization style (title case, sentence case, all-lowercase deliberate) +- Number formatting (spell out under ten, or always digits) +- Oxford comma (use or skip) +- Active vs passive voice (most brands prefer active) + +### Layer 4: Examples and patterns + +Voice is taught through examples, not rules. Build a library. + +For each major content type, show: + +- Bad example (off-voice) +- Good example (on-voice) +- Brief note on what changed + +Common content types to cover: + +- Headline +- Subheadline +- Hero CTA +- Feature description +- Testimonial intro +- Email subject line +- Email opening +- Push notification +- Error message +- Success message +- About page paragraph +- Social post +- Sales page paragraph + +Aim for 15 to 25 paired examples. This is the most-used part of the voice doc in practice. + +--- + +## Workflow + +1. **Audit existing copy** if it exists. Identify what is on-brand, what is off, what patterns recur. +2. **Layer 1: Voice attributes.** Generate 5 to 8 candidates with "we are X, not Y" framing. Pick 3 to 5. +3. **Layer 2: Tone shifts.** List 8 to 15 contexts the brand writes in. Note the tone shift for each. +4. **Layer 3: Vocabulary and grammar.** Define preferences. Skip default rules unless they actually distinguish the brand. +5. **Layer 4: Examples.** Build the paired-example library. 15 to 25 minimum. +6. **Stress-test.** Pick a fresh writing brief and apply the voice doc. Does it produce on-voice copy? If not, the doc is incomplete. +7. **Document.** Use the template in [`references/voice-document-template.md`](references/voice-document-template.md). +8. **Distribute.** Voice docs only work if they get used. Make the doc easy to reference inline (link to it from CMS templates, brief templates, AI assistant prompts). + +--- + +## Failure patterns + +- **Generic attributes ("friendly, professional, approachable").** Every brand says this. Means nothing. Pick attributes that genuinely distinguish. +- **No "we are NOT" pairings.** Without the rejection, attributes drift toward extremes. +- **Voice doc with no examples.** Rules without examples cannot be applied. +- **Examples that are obviously bad and obviously good.** Real voice work shows nuanced shifts, not cartoonish before/after. +- **Skipping tone shifts.** Treating voice as one-size-fits-all leads to a brand that sounds wrong in error states or legal contexts. +- **Documenting aspirational voice.** If the brand does not actually sound this way today and has no plan to shift, the doc is fiction. +- **Voice without distribution.** A perfect doc that no one references is worth nothing. + +--- + +## Output format + +Default output is a markdown document at `voice.md` in the brand folder. Sections: + +1. Voice attributes (with we-are-not pairings) +2. Tone shifts by context +3. Vocabulary preferences +4. Grammar and style rules +5. Paired examples library (the most-used section) +6. Anti-patterns (specific phrases or constructions to avoid) +7. References (the brands and writers we are inspired by) + +This doc can stand alone or feed into `brand-style-guide`. + +--- + +## Reference files + +- [`references/voice-document-template.md`](references/voice-document-template.md) - Fillable template. +- [`references/voice-frameworks.md`](references/voice-frameworks.md) - Detailed walkthrough of the Nielsen Norman 4 dimensions, Jung archetypes, and the "we are X not Y" approach. diff --git a/skills/brand-voice/references/voice-document-template.md b/skills/brand-voice/references/voice-document-template.md new file mode 100644 index 0000000..b0362e1 --- /dev/null +++ b/skills/brand-voice/references/voice-document-template.md @@ -0,0 +1,324 @@ +# [Brand Name] Voice and Tone + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Maintained by:** [Team or person] + +--- + +## How to use this doc + +[1 to 2 paragraphs. Who this is for, when to reference it, where to ask questions.] + +For most writers, the section that gets used most is the **paired examples library** at the end. When unsure how to write something, find the closest example and pattern-match. + +--- + +## Voice attributes + +We sound: + +- **[Adjective 1]**, not [opposite] +- **[Adjective 2]**, not [opposite] +- **[Adjective 3]**, not [opposite] +- **[Adjective 4]**, not [opposite] +- **[Adjective 5]**, not [opposite] + +### What each attribute means + +**[Adjective 1]** +[2 to 3 sentences. What this looks like in practice. Include one specific example phrase.] +Failure mode: when [Adjective 1] tips into [opposite], we sound [bad outcome]. + +**[Adjective 2]** +[Same structure.] + +**[Adjective 3]** +[Same structure.] + +**[Adjective 4]** +[Same structure.] + +**[Adjective 5]** +[Same structure.] + +--- + +## Tone shifts by context + +Voice stays constant. Tone adjusts based on what the user is doing and feeling. + +| Context | Tone | +|---|---| +| Hero / marketing | [How tone shifts] | +| Onboarding | [How tone shifts] | +| Product copy / UX labels | [How tone shifts] | +| Empty states | [How tone shifts] | +| Error messages | [How tone shifts] | +| Success states | [How tone shifts] | +| 404 / not found | [How tone shifts] | +| Account deletion / cancellation | [How tone shifts] | +| Pricing | [How tone shifts] | +| Legal / TOS | [How tone shifts] | +| Support / help center | [How tone shifts] | +| Crisis communication | [How tone shifts] | +| Email subject lines | [How tone shifts] | +| Social posts | [How tone shifts] | + +--- + +## Vocabulary preferences + +### Words and phrases we use + +[Bulleted list of vocabulary that fits the brand. Be specific.] + +- [Word or phrase] +- [Word or phrase] +- [Word or phrase] + +### Words and phrases we avoid + +[Bulleted list of vocabulary that does not fit. Often these are category cliches or fluff words.] + +- [Word or phrase] - [optional note on why] +- [Word or phrase] +- [Word or phrase] + +### Redefined words (if any) + +If the brand uses standard words in non-standard ways, document here. + +| Standard term | We say | Why | +|---|---|---| +| [Standard] | [Our term] | [Reasoning] | + +### Industry jargon + +We [keep / strip] industry jargon. [1 to 2 sentences explaining the call.] + +--- + +## Grammar and style + +| Decision | Our standard | +|---|---| +| Contractions | [Use / avoid] | +| Default sentence length | [Short / medium / long] | +| Em dashes | [Use / avoid] | +| Oxford comma | [Yes / no] | +| Pronouns | [we / you / I patterns] | +| Capitalization (headlines) | [Title / sentence / lowercase] | +| Numbers under 10 | [Spell out / digits] | +| Active vs passive | [Active default] | +| Hashtags (in social) | [In body / in comment / not used] | +| Exclamation points | [Frequency rule] | +| Emoji | [Use / avoid / context-specific] | + +--- + +## Paired examples library + +The most-used part of this doc. When in doubt, find the closest example and pattern-match. + +### Headlines + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +[Brief note on what changed and why.] + +--- + +### Subheadlines + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Hero CTA + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Feature description + +**Off-voice:** +> [Bad example, 2 to 3 sentences] + +**On-voice:** +> [Good example, 2 to 3 sentences] + +--- + +### Testimonial intro + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Email subject line + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Email opening + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Push notification + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Error message + +**Off-voice:** +> "An error has occurred. Please try again later." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### Success message + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Empty state + +**Off-voice:** +> "No items found." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### About page paragraph + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Social post + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### Sales page paragraph + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +### 404 page + +**Off-voice:** +> "404. Page not found." + +**On-voice:** +> [Good example specific to this brand] + +--- + +### Cancellation flow copy + +**Off-voice:** +> [Bad example] + +**On-voice:** +> [Good example] + +--- + +## Anti-patterns + +Specific phrases or constructions that NEVER appear in our writing: + +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] + +--- + +## References + +Brands and writers whose voice we admire and learn from: + +- **[Brand or writer]** - [What we learn from them] +- **[Brand or writer]** - [What we learn from them] +- **[Brand or writer]** - [What we learn from them] + +We are not copying these voices. We are calibrating against them. + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial publication | + +--- + +## How to evolve this doc + +[1 paragraph on how the team proposes voice updates, who reviews, who approves.] + +Voice should be reviewed: +- Annually as a minimum +- After any major audience shift +- After any major positioning change +- When it consistently fails the "stress test" (writing produced from this doc no longer feels right) diff --git a/skills/brand-voice/references/voice-frameworks.md b/skills/brand-voice/references/voice-frameworks.md new file mode 100644 index 0000000..8d57718 --- /dev/null +++ b/skills/brand-voice/references/voice-frameworks.md @@ -0,0 +1,188 @@ +# Voice Frameworks + +Three established frameworks for thinking about brand voice. Each emphasizes a different layer. Mix and match. None is "right." Each is a tool. + +--- + +## Framework 1: The "We are X, not Y" approach + +The most pragmatic framework. Start here if you have not done voice work before. + +### How it works + +Pick 3 to 5 voice attributes. For each, name what the attribute is NOT. The pairing is the framework. + +``` +We are confident, not arrogant. +We are direct, not blunt. +We are warm, not saccharine. +We are smart, not academic. +``` + +### Why the "not Y" matters + +Single-word attributes are aspirational. They float. Without a counterweight, writers (and AI assistants) overshoot. + +- "Confident" alone = swagger, bravado, dismissiveness +- "Direct" alone = curtness, coldness, rudeness +- "Warm" alone = mushy, performative, over-friendly +- "Smart" alone = jargon-heavy, exclusionary + +Each "not Y" tells the writer where the line is. It is the guardrail. + +### Picking attributes + +Avoid generic words every brand claims. "Friendly," "professional," "approachable," "trustworthy," "innovative" are filler. They do not distinguish. + +Better attributes are specific enough to make some other brand a bad fit. If you can imagine your competitor saying the same word, the word is too generic. + +A good list: +- Distinctive (no other brand in your category would put it the same way) +- Honest (you actually sound this way, or are committed to) +- Useful (writers can apply it to a real piece of copy) +- Limited (3 to 5 attributes; 8+ becomes unworkable) + +### Stress test + +Take a recent piece of copy. Score it 1 to 5 against each attribute. If it scores below 3 on any, the copy is off-voice. If it scores 5 across the board, the attributes might be too generous. + +Apply the test to a competitor's copy. If their copy scores high on your attributes, the attributes are not distinctive enough. + +--- + +## Framework 2: The Nielsen Norman 4 dimensions + +Nielsen Norman Group introduced a model that treats voice as four sliders rather than a list of adjectives. + +### The 4 sliders + +**1. Funny vs serious** +Where on the spectrum from playful to earnest does the brand sit? + +- Far funny: jokes are signature, even in support content +- Mid: occasional wit, mostly straightforward +- Far serious: humor is rare and only when context invites it + +**2. Formal vs casual** +How structured and decorous is the writing? + +- Far formal: full sentences, correct grammar, no contractions, professional register +- Mid: standard professional, occasional contractions +- Far casual: contractions, fragments, conversational rhythms, slang where appropriate + +**3. Respectful vs irreverent** +Does the brand treat its audience and category with deference, or does it poke fun? + +- Far respectful: customers are addressed with care, category is treated with seriousness +- Mid: respectful default, willing to be playful at edges +- Far irreverent: category cliches get punctured, the brand is willing to mock conventions (its own and competitors') + +**4. Matter-of-fact vs enthusiastic** +What is the energy level? + +- Far matter-of-fact: calm, even, measured +- Mid: warm but not effusive +- Far enthusiastic: animated, expressive, energetic + +### How to use + +Plot the brand on each of the four. The position is the brand's voice signature. + +Example: +- Funny vs serious: 30 (mostly serious, occasional dryness) +- Formal vs casual: 70 (mostly casual, contractions standard) +- Respectful vs irreverent: 40 (respectful default, willing to be playful) +- Matter-of-fact vs enthusiastic: 50 (warm but measured) + +This produces a recognizable signature distinct from competitors plotted on the same axes. + +### Why this framework + +It forces choices. Adjective lists let you claim "warm AND professional AND witty AND smart." The dimensions force you to commit to a position, which is what voice actually is. + +### When to use it + +Best as a complement to the "We are X, not Y" approach. Use the dimensions to plot the brand. Use the attributes to give writers actionable language. + +--- + +## Framework 3: Brand archetypes (the Jung-derived model) + +A model from depth psychology, applied to brands by Margaret Mark and Carol Pearson. Twelve archetypes, each with a recognizable voice pattern. + +### The 12 archetypes + +| Archetype | Voice signature | Example brands (illustrative, not endorsements) | +|---|---|---| +| Innocent | Pure, optimistic, simple | Wholesome consumer brands, family-oriented | +| Sage | Wise, considered, knowledgeable | Educational publishers, research institutions | +| Explorer | Adventurous, free, restless | Outdoor brands, travel platforms | +| Outlaw | Rebellious, defiant, anti-establishment | Disruptors, challenger brands | +| Magician | Visionary, transformative, mystical | Tech that "changes everything" | +| Hero | Brave, decisive, achievement-oriented | Athletic brands, ambitious tools | +| Lover | Sensual, intimate, devoted | Premium consumer goods, luxury | +| Jester | Playful, irreverent, lighthearted | Entertainment, fast food, fun-first | +| Everyman | Down-to-earth, relatable, fair | Mass market, "for everyone" | +| Caregiver | Compassionate, generous, protective | Healthcare, family services | +| Ruler | Authoritative, sophisticated, in-control | Premium brands, enterprise | +| Creator | Imaginative, expressive, original | Creative tools, artistic brands | + +### How to use + +Pick a primary archetype. Optionally a secondary. The combination is the voice signature. + +A brand might be primary Sage with secondary Caregiver. That voice is wise + protective. It would write differently than a Sage + Outlaw (wise + defiant). + +### Strengths + +- Forces a clear voice character rather than a list of adjectives +- The archetypes are recognizable, which helps writers visualize the voice +- Distinguishes brands that might otherwise sound similar + +### Weaknesses + +- Some archetypes are dated or culturally specific +- "Pick one" is harder than it sounds; brands often span 2 or 3 +- Easy to pick aspirational archetypes the brand does not actually live + +### When to use it + +When the brand has a distinctive personality you want to crystallize. Less useful for utilitarian or category-defining brands. + +--- + +## Combining frameworks + +The three frameworks are not mutually exclusive. They emphasize different layers. + +A useful combination: + +1. **Archetype** for the high-level character +2. **NN/g dimensions** for the calibration +3. **"We are X, not Y" attributes** for the daily writing guardrails + +Example for a fictional brand: + +- **Archetype:** Sage (primary) + Everyman (secondary) +- **Dimensions:** 30 funny / 60 casual / 50 respectful / 40 enthusiastic +- **Attributes:** + - Knowledgeable, not academic + - Plain-spoken, not basic + - Honest, not harsh + - Patient, not condescending + +Each layer adds resolution. The archetype gives character. The dimensions give calibration. The attributes give writers the daily tool. + +--- + +## Choosing a framework + +If you have done voice work before and know what you want, the "We are X, not Y" approach alone is enough. + +If the brand voice is undefined and you need to start from zero, begin with archetypes (high-level character), move to dimensions (calibration), then derive attributes (daily guardrails). + +If voice work has been done but is too vague, the dimensions framework is the best clarifier. + +If voice has been documented but writers do not know how to apply it, the attributes framework is the missing piece. + +The frameworks are tools. The output of voice work is consistent writing across the brand. If the writing is consistent, the framework worked. If it is not, no framework is the right one yet. diff --git a/skills/calculator-design/SKILL.md b/skills/calculator-design/SKILL.md new file mode 100644 index 0000000..a9be8c1 --- /dev/null +++ b/skills/calculator-design/SKILL.md @@ -0,0 +1,296 @@ +--- +name: calculator-design +description: "Designing interactive calculators (ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments) that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. Honest about vanity-calculator (no real value), lead-trap (hides the answer behind email), and transparent-decision-tool (gives the result and earns the email through tiered value) patterns. Triggers on calculator, ROI calculator, pricing estimator, savings calculator, custom calculator, interactive tool, decision tool, financial calculator. Also triggers when an audience needs a calculation-driven lead magnet, when a vanity calculator is producing leads but no qualified ones, or when a calculator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive calculators that deliver decision-support value while qualifying leads. Distinguishes vanity-calculator (no real value) from lead-trap (hides answer behind email) from transparent-decision-tool (gives genuine value, captures leads honestly)" +display_order: 2 +--- + +# Calculator Design + +A senior growth practitioner's playbook for designing interactive calculators that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments. The discipline of building a tool the audience actually trusts. + +Most calculators on the web are bait. Random multipliers behind official-looking math; an "Industry Average" number that does not cite a source; the result hidden behind a contact-sales form. The calculator captures emails because the format implies calculation; the leads are unqualified because the calculator did not actually help anyone decide anything. + +The calculators that work as compounding assets do something different. They give the audience a result they can defend to a stakeholder. They show the methodology so the result is interrogatable. They capture leads through value (a PDF report, a save-and-compare account, a custom analysis) rather than through manipulation. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the calculator-specific methodology (calculation transparency, tiered value, methodology disclosure) lives here. + +The voice is the senior growth practitioner who has watched calculators earn long-term credibility and watched them burn it within weeks of launch. Practical, opinionated about transparency, willing to say when a calculator is the wrong investment for the goal. + +When to use this skill: scoping a calculator for the first time, auditing a calculator that converts but does not qualify, designing the methodology disclosure that earns audience trust, or deciding which features warrant the email gate. + +--- + +## What this skill covers + +This skill spans calculator design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology (when to invest in any magnet, format selection, audience-fit, follow-up sequence). Calculators are one specific lead-magnet type. +- **`calculator-design` (this skill)** is calculator-specific methodology (calculation transparency, tiered value, methodology disclosure, input design). +- `quiz-and-assessment-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `landing-page-copy` is the calculator landing page (downstream of calculator design). +- `pm-spec-writing` is writing the spec for engineers building the calculator. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: growth marketers, product marketers, marketing teams building lead-magnet calculators, agencies running growth-tooling work for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the calculator (handed off via `pm-spec-writing`). + +--- + +## The calculator decision: when calculators earn investment + +Before designing the calculator, decide whether a calculator is the right tool for the audience and the goal. + +**Calculators earn investment when:** + +- The audience faces a specific calculation as part of a decision. ROI on a software purchase, savings from a refinance, monthly cost of an expense, sizing for a service tier. Without a real calculation in the audience's actual workflow, the calculator becomes a vanity tool. +- The calculation is non-trivial. Multiplying two numbers does not need a calculator; calibrating across 5-10 inputs with branching logic does. +- The brand has methodology authority. The calculator's output has to be defensible. Brands without methodology authority (or unwilling to disclose methodology) often produce calculators audiences do not trust. +- The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation); the sequence has to use that signal. + +**Calculators do NOT earn investment when:** + +- The audience does not actually run this calculation. A calculator solving a problem the audience does not have produces low usage. +- The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" does not earn its build. +- The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend, the calculator becomes a vanity tool by necessity. +- A simpler magnet would serve the same audience and goal. Templates and checklists are cheaper to build and maintain than calculators; choose the calculator only when the calculation is the value. + +The decision is not "should we have a calculator"; it is "is the calculator the right next investment for this specific audience and goal." + +Detail in [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md). + +--- + +## Vanity-calculator vs lead-trap vs transparent-decision-tool + +The keystone framing. + +**Vanity-calculator.** Inputs and outputs that do not actually help anyone decide anything. "Calculate your marketing ROI" with random multipliers; "estimate your savings" with no defensible methodology. Looks impressive in a screenshot; helps nothing in a real decision. Cost: leads downloaded the result, found it useless, and remember the brand as the source of the useless tool. + +**Lead-trap.** Genuine calculation logic but the result is hidden behind an email gate. The user inputs 8 fields, hits "Calculate," and sees "enter your email to see your result." Manipulative; reader resents the friction; conversion drops below baseline because the audience can tell when the gate is bait rather than value-add. + +**Transparent-decision-tool.** Genuine calculation that gives the result immediately. Email gate for advanced features (PDF report, custom analysis, save-and-compare across scenarios) where the additional value justifies the ask. The reader gets the answer they came for; the brand gets the email through demonstrated generosity. + +The litmus test. After running the calculator, can a stranger in the target audience defend the result to a stakeholder? Can they cite the methodology behind the number? If yes, the calculator is a transparent-decision-tool. If they got a number with no defensible source, the calculator is vanity. If they could not see the result without giving an email, the calculator is a lead-trap. + +--- + +## Input design + +The calculator's inputs are the audience's first interaction. Bad input design loses the user before the calculation runs. + +**The principle.** Each input should be necessary for the calculation, easy for the user to provide, and respectful of the user's time. + +**Necessary.** If an input does not affect the output meaningfully, do not ask for it. Calculators that ask 18 inputs but only use 5 in the actual math signal that the form is collecting data for sales rather than for the calculation. The audience can tell. + +**Easy to provide.** Use defaults from honest assumptions. "Average company size" preset to a reasonable industry baseline. "Typical conversion rate" preset to a defensible number. Defaults reduce the cognitive load and let the user adjust where their context differs. + +**Respectful of time.** Group related inputs visually. Show only the fields the user is currently working through (progressive disclosure where it helps). Indicate progress so the user knows how many steps remain. + +**Input types.** + +- Numeric (revenue, customer count, monthly cost). The most common. Often warrants tooltip explaining what the number represents. +- Slider (percentage estimates, conversion rates). Good for ranges where exact values are not knowable. +- Dropdown (industry, company size, region). Good for predefined categories. +- Toggle (feature on/off, scenario A vs B). Good for binary choices. +- Free text (only when the value is genuinely user-specific and cannot be calculated). Use sparingly; free text is friction. + +Detail in [`references/input-design-patterns.md`](references/input-design-patterns.md). + +--- + +## Calculation logic transparency + +The defensibility of the result is the calculator's credibility currency. + +**The principle.** The audience should be able to inspect the methodology. Either the calculation is shown openly, or a methodology link explains it, or the team is willing to share the spec on request. + +**Methodology disclosure options.** + +- **Inline formulas.** "Your savings = (current cost x 12) - (our cost x 12) + implementation savings of $X." Explicit and verifiable. +- **Methodology page.** A link from the calculator to a page explaining the assumptions, sources, and formulas. The audience can read if they care; defaults are good for those who do not. +- **Source citations.** When inputs come from external benchmarks ("Industry Average: 14 percent"), cite the source. Uncited benchmarks erode trust. +- **Assumption list.** A list of the calculator's assumptions, plain-language. "We assume you are comparing month-over-month after a 3-month implementation period." + +**The vanity-calculator failure.** Assumptions hidden, sources missing, formulas opaque. The audience uses the tool, gets a number, and cannot defend it. The brand is invisible in their next conversation about the decision because the calculator did not earn the credibility. + +**The transparent-tool win.** Assumptions visible, sources cited, formulas inspectable. The audience uses the tool, gets a number, and can defend it. The brand is in the conversation because the audience cites the calculator as their source. + +Detail in [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md). + +--- + +## Result presentation + +The result is the calculator's product. Bad result presentation wastes the calculation work. + +**The principle.** The result should be specific, contextualized, and actionable. + +**Specific.** A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." + +**Contextualized.** Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." The context makes the number interpretable. + +**Actionable.** What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step is the calculator's bridge from result to action. + +**Result-presentation patterns.** + +- **Headline number.** The single most important output, large and prominent. +- **Breakdown.** Sub-results that explain how the headline number was calculated. +- **Visualization.** Bar chart, comparison table, or simple graphic that helps the user see the relationship. +- **Scenario comparison.** "Your current state vs the optimized state." Useful when the calculator is illustrating a delta. + +**Avoid.** + +- Burying the result. The result should be visible immediately, not after a scroll. +- Result followed by 5 paragraphs of marketing. The result is what the user came for; marketing belongs after, not before. +- Result that requires re-entering all inputs to view. Persist inputs and results within the session. + +Detail in [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md). + +--- + +## Email-capture decision + +What to gate, what to give freely. + +**The principle.** Give the audience the result they came for. Gate the additional value (PDF report, custom analysis, save-and-compare, saved scenarios across visits). + +**What to give freely.** + +- The headline result. +- The breakdown of how the result was calculated. +- A visualization of the result. +- The methodology disclosure. + +**What to gate (with email or account creation).** + +- A formatted PDF report the user can share or save. +- A saved scenario the user can revisit and compare against alternatives. +- A custom analysis (a deeper version of the calculation, often delivered later). +- Email-based notifications when assumptions change or new benchmarks emerge. + +**The lead-trap failure.** The headline result is gated. The user inputs 8 fields, hits Calculate, sees "enter your email to see your result." Conversion drops because the audience perceives the manipulation. The lead-trap pattern is short-term thinking. + +**The transparent-tool win.** The result is free; the additional value is gated. Conversion is honest; lead quality is high because the lead opted in for the additional value, which signals real interest. + +Detail in [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md). + +--- + +## Tiered-value structures + +The architecture that lets calculators capture leads honestly. + +**The principle.** The calculator delivers tiered value: free immediate result + gated advanced features. + +**Tier 1 (free, no gate):** the headline result, the breakdown, the methodology, basic visualization. + +**Tier 2 (email-gated):** a formatted PDF, a saved scenario, an emailed copy of the result. + +**Tier 3 (account or sign-up gated):** save-and-compare across multiple scenarios over time, advanced analysis, integration with the brand's product or service. + +**The tier-design discipline.** + +- Each tier should add real value over the previous. If Tier 2 is just "the same result in a PDF," the tier does not justify the email ask. +- The gate at each tier should be matched to the value. Email for Tier 2; account creation only for Tier 3. +- The tier transitions should feel natural. The user gets the free result, sees the additional value visibly, and chooses whether to opt in for it. + +**Worked example.** + +A B2B SaaS pricing calculator. + +- Tier 1 (free): the user enters team size and use case, sees the recommended plan and the estimated monthly cost. Methodology link explains tier breakpoints. +- Tier 2 (email-gated): a PDF showing the recommended plan, the calculation, and a comparison to alternative plans the user might consider. +- Tier 3 (account-gated): a saved scenario the user can revisit; ability to compare against historical pricing if the calculator is used periodically; option to receive notifications if pricing or recommended plans change. + +Each tier earns its gate. + +Detail in [`references/tiered-value-structures.md`](references/tiered-value-structures.md). + +--- + +## Calculator anti-patterns + +Patterns that look like calculators but degrade trust. + +**The lead-trap.** Result hidden behind email. Detail in keystone framing. + +**The vanity output.** A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? + +**The hidden-methodology calculator.** No way to see the math; no methodology page; no assumption list. The audience uses the tool, gets a number, and cannot defend it. + +**The interrogation form disguised as calculator.** 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +**The misleading-baseline calculator.** "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. The audience that knows the industry sees the gap. + +**The misaligned-units calculator.** "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +**The static-assumption calculator.** Assumptions hardcoded in 2022 that have not been updated. The calculator's outputs are stale. + +**The mobile-broken calculator.** Calculator works fine on desktop, breaks on mobile. The mobile audience either bounces or gets a worse experience that misrepresents the brand. + +Detail in [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-calculator-failures.md`](references/common-calculator-failures.md). + +- "Conversion rate is high; downstream conversion is near zero." Lead-trap or vanity-output pattern; the audience captured did not get value, did not engage with the follow-up, did not convert. +- "Audience visits the calculator, runs it once, never returns." Calculator does not produce a save-worthy or share-worthy result; no reason to come back. +- "Sales team says the calculator-sourced leads are unqualified." Calculator's audience-fit weak; the calculation does not match the buyer's actual decision. +- "We get questions about how the calculator works; we have no answer." Methodology not documented; the team cannot defend the calculator's outputs. +- "We updated the product; the calculator outputs are now wrong." No update cadence; the calculator drifted out of sync with the actual offering. +- "The calculator works; nobody uses it." Calculator hidden in the site; no distribution; the audience does not know it exists. +- "Our calculator looks like our competitor's." Generic calculator-template patterns produce generic calculators; the brand differentiation absent. +- "The form has 12 fields and 4 percent conversion." Interrogation-form pattern; the calculator is collecting data, not delivering value. +- "Audience trusts our brand; the calculator outputs feel arbitrary." Methodology disclosure missing; the brand's credibility does not transfer to the tool because the tool does not show its work. + +--- + +## The framework: 12 considerations for calculator design + +When designing or auditing a calculator, walk these 12 considerations. + +1. **The calculator decision.** Is a calculator the right investment, or would a simpler magnet serve? +2. **Transparent-decision-tool, not vanity or lead-trap.** Result is free; methodology is visible; gate is on additional value, not on the result. +3. **Inputs are necessary, easy, respectful of time.** Each input affects the math; defaults reduce friction; progressive disclosure where it helps. +4. **Calculation methodology disclosed.** Inline formulas, methodology page, source citations, or assumption list. +5. **Result is specific, contextualized, actionable.** Number with units; baseline for interpretation; clear next step. +6. **Tiered value structure.** Free immediate result; gated advanced features; each tier earns its gate. +7. **Email-capture decision honest.** Gate on real value-add (PDF, save-and-compare, custom analysis), not on the result the user came for. +8. **Source attribution clear.** Industry averages, benchmarks, and assumptions all cited or explained. +9. **Mobile experience tested.** Calculator works on the device the audience uses. +10. **Update cadence defined.** When inputs, benchmarks, or product details change, the calculator gets updated. +11. **Distribution planned.** The calculator's audience knows it exists. Landing page, navigation, content references all include the calculator. +12. **Lead quality measured.** Downstream conversion from calculator-sourced leads is the real metric, not surface conversion. + +The output of the framework is a calculator that delivers real decision-support value, earns the email through demonstrated generosity, and produces leads the team can convert downstream. + +--- + +## Reference files + +- [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md) - When a calculator is the right tool for the audience and goal, and when a simpler magnet would serve. +- [`references/input-design-patterns.md`](references/input-design-patterns.md) - Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. +- [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md) - Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. +- [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md) - Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. +- [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md) - What to give freely, what to gate. The lead-trap failure and the transparent-tool win. +- [`references/tiered-value-structures.md`](references/tiered-value-structures.md) - Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. +- [`references/methodology-disclosure-templates.md`](references/methodology-disclosure-templates.md) - Templates for assumption lists, methodology pages, source citations, formula explanations. +- [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md) - The patterns that look like calculators but degrade trust. +- [`references/common-calculator-failures.md`](references/common-calculator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: calculators earn the email when they would have been worth paying for + +The calculators that work as compounding assets are the ones the audience trusts. Not impressive screenshots. Not high conversion rates. Trust. The audience runs the calculator, gets a result they can defend, and remembers the brand as the source of the result they used in their actual decision. + +That is the bar. Below the bar are vanity-calculators (no real result) and lead-traps (result hidden until you pay with an email). Above the bar are transparent-decision-tools that give the audience the answer freely and capture leads through additional value the audience opts in for. + +The discipline is in the design choices. The methodology disclosure that earns credibility. The input design that respects the audience's time. The tiered value structure that makes the email-capture honest. The result presentation that makes the calculator's output usable in the audience's real conversation. The update cadence that keeps the calculator in sync with the offering it represents. + +When in doubt, ask: would the audience pay for this calculator if it were not free, and can they defend the result to a stakeholder after they use it? If yes to both, the calculator earns the email. If no to either, redesign or do not ship. diff --git a/skills/calculator-design/references/calculation-logic-transparency.md b/skills/calculator-design/references/calculation-logic-transparency.md new file mode 100644 index 0000000..8afc216 --- /dev/null +++ b/skills/calculator-design/references/calculation-logic-transparency.md @@ -0,0 +1,200 @@ +# Calculation logic transparency + +Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. The defensibility of the result is the calculator's credibility currency. + +A calculator's output is only as trustworthy as the audience's ability to inspect how it was computed. Calculators that hide methodology produce numbers; calculators that disclose methodology produce defensible numbers. The difference shows up in whether the audience cites the calculator in stakeholder conversations. + +--- + +## The transparency principle + +The audience should be able to inspect the methodology if they care. + +Three levels of transparency, in increasing depth. + +**Level 1: Inline.** The methodology appears in the calculator itself, near the result. "Your annual savings: $14,200 = (current cost x 12) - (estimated new cost x 12) + first-year implementation savings of $X." + +**Level 2: Methodology page.** A linked page explaining the formulas, assumptions, and sources in detail. The result page links to it; users who want depth find it. + +**Level 3: Spec on request.** The team is willing to share the underlying spec, customer-data sources, or formula derivations on request. Useful for analytical or enterprise audiences who want full inspection. + +A calculator should at minimum support Level 1 or Level 2. Level 3 is optional and signals analytical credibility. + +--- + +## Inline formulas + +Show the math near the result. + +**The pattern.** Below or alongside the headline result, show the formula that produced it. + +**Example: ROI calculator inline formula.** + +``` +Annual savings: $14,200 + +Calculation: + Current annual cost: $36,000 ($3,000 / month x 12) + Estimated new annual cost: $24,000 ($2,000 / month x 12) + Annual savings: $36,000 - $24,000 = $12,000 + + First-year implementation savings: $2,200 + Total: $14,200 +``` + +**The win.** The audience can verify the math. They can adjust their inputs and predict how the result will change. They can defend the result to a stakeholder by citing the formula. + +**When to use inline formulas.** When the calculation is straightforward enough to display in a few lines. Most ROI, savings, and pricing calculators fit this pattern. + +**When inline formulas hurt.** When the calculation is so complex (multi-stage, with branching) that the formula display overwhelms the result. In those cases, link to a methodology page instead. + +--- + +## Methodology page + +A linked page explaining the calculation in depth. + +**The pattern.** The result page includes a "How this is calculated" or "Methodology" link. The link opens a page with formulas, assumptions, and sources. + +**What a methodology page should include.** + +- The central formulas in plain text (not just images). +- Each variable defined. +- Each assumption listed plainly. "We assume a 3-month implementation period." "We assume the user is comparing month-over-month." +- Sources for any external benchmarks. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025]." +- Worked example. A specific scenario with input values and the resulting calculation. +- Caveats. "This calculator does not account for [X]; for that, see [other resource]." + +**The methodology page test.** A skeptical reader of the methodology page should come away thinking "this is reasonable" or "I disagree with assumption Y, here is why." Either response is a sign the methodology is real and the audience can engage with it. + +**Methodology pages and SEO.** Methodology pages can themselves rank for search terms ("how is X calculated"), bringing additional traffic to the calculator. The page is not just transparency; it is also a content asset. + +--- + +## Source citations + +When the calculator uses external benchmarks or data, cite the source. + +**The pattern.** "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025, page 23]." + +**Why source citations matter.** They signal that the benchmark is real, not invented. They let the skeptical user verify. They protect the brand if the benchmark is later disputed. + +**Citation discipline.** + +- Cite the most authoritative source available (industry report, academic paper, published study). +- Date the source. Benchmarks decay; an undated source could be from any year. +- Link to the source where possible. Inaccessible sources (paywalled reports cited from memory) are weaker than linked sources. +- If the source is internal customer data, say so. "Source: [Brand]'s customer cohort, n=200, 2024-2025." Internal sources are valid; honesty about their origin matters. + +**The uncited-benchmark failure.** "Industry Average: 14 percent" with no source. The audience that knows the industry sees the gap; the audience that does not know rolls the dice on whether to trust. Either way, credibility leaks. + +--- + +## Assumption lists + +A plain-language list of what the calculator assumes. + +**The pattern.** Either inline (near the result) or on the methodology page, list the assumptions in plain English. + +**Example assumption list for a SaaS pricing calculator.** + +- "We assume your team will use the platform daily." +- "We assume implementation takes 4-6 weeks." +- "We assume the productivity gains compound through year 1 and stabilize in year 2." +- "We assume your current solution costs include licenses, hosting, and 1 FTE for maintenance." +- "We do not account for [specific factors] in this estimate." + +**Why assumption lists matter.** They make the calculator's worldview visible. The audience can see whether the assumptions match their situation. If the assumptions diverge, the audience knows to discount the result accordingly. + +**Honest assumptions vs flattering assumptions.** Honest assumptions reflect the typical case; flattering assumptions reflect the case that produces the most attractive output. Audiences that catch flattering assumptions stop trusting the calculator. + +**The assumption-decay problem.** Assumptions need updating as the world changes. A calculator with assumptions from 2022 may have outdated benchmarks; review quarterly. + +--- + +## The methodology-authority spectrum + +Calculators sit on a spectrum from "fully transparent" to "fully opaque." Each position has tradeoffs. + +**Fully transparent.** All formulas, all assumptions, all sources visible. The audience can fully reconstruct the calculation. Trust is maximum; competitive risk (others copying the methodology) is highest. + +**Largely transparent.** Major formulas visible; minor weighting or proprietary elements glossed. The audience trusts the result; the brand keeps some IP. Common middle ground. + +**Methodology-page transparent.** The result is shown without inline formulas; the methodology page has the depth. The audience that cares finds the depth; the audience that does not, does not have to. + +**Opaque.** No methodology shown. The audience either trusts the brand or not; there is no inspection path. High competitive protection; low audience trust. + +The right position depends on the audience and the goal. Analytical audiences (engineers, finance teams, technical buyers) need transparency to trust. Less-analytical audiences may accept opacity if the brand has earned trust through other means. Most calculators benefit from at least Level 2 (methodology page) transparency. + +--- + +## When the calculation cannot be fully disclosed + +Some calculations include proprietary IP. Honest framing matters. + +**The honest framing.** "The output combines public benchmark data with proprietary insights from our customer cohort. Public elements are detailed in the methodology page; the proprietary weighting reflects our own data and is not detailed here." + +**The dishonest framing.** Hiding the proprietary nature; presenting opaque outputs as if they came from public methodology. + +**The audience's reaction.** Honest framing about proprietary IP is usually accepted. The audience understands that some IP is protected; they appreciate the honesty about what is shown and what is not. Dishonest framing breaks trust when the audience tries to interrogate and finds nothing. + +**The discipline.** Disclose what can be disclosed. Honestly label what cannot. The combination earns more trust than full opacity or false transparency. + +--- + +## Methodology display patterns + +How to integrate methodology into the calculator's UI. + +**Pattern A: Always-visible inline formulas.** The result and the formula appear together. Best for short calculations where the formula is digestible. + +**Pattern B: Expandable methodology details.** The result appears prominently; "How this was calculated" is an expandable section below. The user opens it if they want depth. + +**Pattern C: Methodology link to a separate page.** The result is shown; the methodology page is linked. Good for complex calculations that need full discussion. + +**Pattern D: Hover-revealed assumption tooltips.** Each variable in the result has a tooltip explaining how it was derived. Useful when the calculation has many components. + +**Pattern E: Methodology in PDF report.** The free result shows the headline; the gated PDF contains the full methodology. This pattern works when the PDF is genuinely the value-add and the headline result is enough for free users. + +The choice depends on calculator complexity, audience analytical depth, and the brand's transparency posture. + +--- + +## Common transparency failures + +**No methodology shown.** Result is a number; user has no way to verify or defend it. + +**Hidden assumptions.** Inputs and outputs visible; assumptions baked into the math without disclosure. + +**Uncited benchmarks.** "Industry Average: 14 percent" with no source. + +**Stale assumptions.** Methodology written in 2022, never reviewed. + +**Flattering defaults.** Defaults set to produce favorable outputs; the audience that catches the bias stops trusting. + +**Methodology page that hides more than it reveals.** Marketing copy disguised as methodology; no actual formulas or sources. + +**Inconsistent precision.** Result shown as "$14,237" when the inputs justify only "$14,000 (estimated)." False precision erodes trust. + +**No version history on methodology.** Methodology page changed over time without record; users who relied on previous outputs cannot tell what changed. + +--- + +## The credibility compounding effect + +Transparent calculators compound credibility. + +**The mechanism.** The audience uses the calculator, gets a defensible result, cites it in their decision-making conversation. The brand is in the conversation. The audience returns to the calculator for related decisions. The brand's authority on the topic deepens. + +**The opposite.** Opaque calculators do not compound. The audience uses the calculator, gets a number they cannot defend, leaves it out of their stakeholder conversation. The brand is invisible. The audience does not return. + +**The metric.** Track whether the calculator is being cited. Mentions in customer conversations, references in industry discussions, backlinks from other content all signal compounding credibility. + +--- + +## Methodology-level choices that stay in the public skill + +The transparency principle and the three levels. Inline formulas, methodology pages, source citations, assumption lists. The methodology-authority spectrum. Honest framing for proprietary calculations. Methodology display patterns. Common transparency failures. The credibility compounding effect. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source citations and benchmark relationships. Specific tooling for methodology display. Specific brand-voice methodology copy. The team's update calendars and version control for methodology. These vary by team. diff --git a/skills/calculator-design/references/calculator-anti-patterns.md b/skills/calculator-design/references/calculator-anti-patterns.md new file mode 100644 index 0000000..430a9c9 --- /dev/null +++ b/skills/calculator-design/references/calculator-anti-patterns.md @@ -0,0 +1,211 @@ +# Calculator anti-patterns + +The patterns that look like calculators but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The lead-trap + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +The signal. Conversion-rate metric on the email form looks fine; downstream conversion is near zero; the audience that recognizes the pattern bounces immediately. + +The cost. The leads captured are unqualified or actively annoyed. The brand earns "lead-trap" reputation; trust erodes across all future interactions. + +The cure. Restructure so the result is free and the additional value (PDF, save-and-compare, custom analysis) is gated. Detail in `references/email-capture-decision-tree.md`. + +--- + +## The vanity output + +The pattern. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? Compared to what? + +The signal. Audiences run the calculator out of curiosity; do not return; do not cite the result anywhere; do not engage with the follow-up sequence. + +The cost. The calculator's build cost was wasted. The audience does not associate the brand with useful analysis. + +The cure. Anchor the result to a decision the audience actually makes. The output should be a number with units, contextualized against a baseline, with a clear next step. + +--- + +## The hidden-methodology calculator + +The pattern. No way to see the math. No methodology page. No assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The signal. Sales-team friction; prospects who used the calculator cannot bring its outputs into stakeholder conversations. + +The cost. The calculator does not compound credibility. Each user runs it once and does not return; the brand stays invisible in the audience's actual decision conversations. + +The cure. Disclose methodology. Detail in `references/calculation-logic-transparency.md`. + +--- + +## The interrogation form disguised as calculator + +The pattern. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The signal. Conversion rate on the form is poor. The audience self-selects out at the form length. + +The cost. The calculator's reach drops dramatically. The leads that do convert are over-disclosed and may resent the friction; the audience the calculator could have served does not get to use it. + +The cure. Audit the input set. Remove fields that do not affect the calculation. Capture additional data later in the relationship, not at the form. + +--- + +## The misleading-baseline calculator + +The pattern. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. + +The signal. Audiences with industry knowledge notice the gap. Those audiences do not return; they may post about the bias publicly. + +The cost. Trust damage that can be hard to recover. Brand earns "spin" reputation. + +The cure. Source the baselines honestly. Use defensible benchmarks; if the brand's data is favorable, disclose that the data comes from the brand's own customer cohort and acknowledge the bias. + +--- + +## The misaligned-units calculator + +The pattern. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The signal. Audiences cannot interpret the result; cannot use it in their decision; do not return. + +The cost. The calculator's outputs are uninterpretable; the calculator does not produce decision-grade signal. + +The cure. Numbers with units. Percentages with bases. Multipliers with reference values. Contextualization that makes the result interpretable. + +--- + +## The static-assumption calculator + +The pattern. Assumptions hardcoded in 2022 that have not been updated. Industry benchmarks from 2 years ago. Tooling references to products that have been deprecated. + +The signal. Audiences with current knowledge see the staleness; trust drops; some users may report the inaccuracy. + +The cost. The calculator's outputs are unreliable. The brand looks careless or out of touch. + +The cure. Quarterly maintenance review. Update assumptions, refresh benchmarks, prune stale references. + +--- + +## The mobile-broken calculator + +The pattern. Calculator works fine on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; result hidden below the fold. + +The signal. High mobile bounce rate; mobile conversion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic; this failure is significant. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. Detail in `references/input-design-patterns.md` (mobile section). + +--- + +## The over-precise calculator + +The pattern. Result shown as "$14,237.42" when the inputs justify only "$14,000 (estimated)." False precision suggests the calculator knows more than it does. + +The signal. Analytical audiences see the false precision and discount the result. The calculator earns "fake math" reputation among the audience that matters most. + +The cost. Trust erosion specifically among the audience the calculator was designed to serve. + +The cure. Round to honest precision. Use "estimated" or "approximately" framing. Disclose the precision the inputs support. + +--- + +## The marketing-disguised-as-methodology calculator + +The pattern. The methodology page exists but contains marketing copy ("our proprietary algorithm draws on industry-leading data") rather than actual formulas, sources, or assumptions. + +The signal. Audiences who click through to verify find no real verification; trust drops. + +The cost. The calculator's credibility is performative rather than real; the audience that interrogates discovers the gap. + +The cure. Real methodology. Formulas, assumptions, sources. Brand voice can frame the methodology page; brand voice cannot replace the methodology itself. + +--- + +## The orphan-result calculator + +The pattern. The result loads; no next step is offered. The user gets the number and leaves. + +The signal. Conversion to next step (PDF, save, contact, demo) is near zero because no next step is offered. + +The cost. The calculator captures attention without converting it. The brand has the audience's moment of intent and does nothing with it. + +The cure. Offer a clear next step at the result. PDF, save scenario, talk to team, related resource. Detail in `references/result-presentation-patterns.md` (result-to-action transitions). + +--- + +## The popup-interrupted calculator + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. The user's flow breaks. + +The signal. Bounce rate spikes at the popup moment; users complain about the interruption. + +The cost. The calculator's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. Detail in `references/result-presentation-patterns.md`. + +--- + +## The cookie-cutter calculator + +The pattern. The calculator looks and behaves like every other calculator from a template platform. Generic UI, generic assumption set, generic output styling. + +The signal. The calculator does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The calculator becomes commodity; the brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## The pessimistic-default calculator + +The pattern. Defaults set to make the brand's outputs look favorable through pessimistic baselines. "Current cost" defaults to the high end; "savings" defaults to the optimistic end. + +The signal. Audiences who notice (often analytical audiences) discount the result. The audience the calculator was built for stops trusting it. + +The cost. Same as misleading-baseline. Trust damage; brand earns "spin" reputation. + +The cure. Honest defaults sourced from data; let the user adjust to their actual context. + +--- + +## The form-without-calculator + +The pattern. A "calculator" that is actually a form. No real calculation; the result is generic ("based on your inputs, our team will reach out") or static ("your estimated savings: 30 percent"). + +The signal. Audiences expecting a real calculation get a sales form; bounce rate spikes; the audience perceives bait-and-switch. + +The cost. The calculator's framing was a lie; trust collapses. + +The cure. Either build a real calculator with real math, or do not call the form a calculator. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active calculator, looking specifically for these anti-patterns. + +**Audit questions per calculator.** + +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Is the methodology disclosed in a way the audience can verify (anti-pattern check: hidden-methodology)? +- Are the inputs all necessary for the calculation (anti-pattern check: interrogation-form)? +- Are the baselines and benchmarks sourced and current (anti-pattern check: misleading-baseline, static-assumption)? +- Does the calculator work on mobile (anti-pattern check: mobile-broken)? +- Is the result actionable, with a clear next step (anti-pattern check: orphan-result)? +- Does the calculator differentiate from other calculators on similar topics (anti-pattern check: cookie-cutter)? + +**The retire decision.** Anti-pattern calculators often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-tool plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/calculator-design/references/calculator-investment-criteria.md b/skills/calculator-design/references/calculator-investment-criteria.md new file mode 100644 index 0000000..b0673aa --- /dev/null +++ b/skills/calculator-design/references/calculator-investment-criteria.md @@ -0,0 +1,144 @@ +# Calculator investment criteria + +When a calculator is the right tool for the audience and the goal, and when a simpler magnet would serve. The conditions that warrant the calculator's build cost. + +A calculator is one of the highest-build-cost magnet formats. Engineering, design, methodology research, and ongoing maintenance all add up. The calculator earns this investment only when specific conditions are present. + +--- + +## When a calculator earns the build + +Five conditions that, when present, make a calculator a strong investment. + +**The audience faces a specific calculation as part of a real decision.** ROI on a software purchase, savings from a refinance, monthly cost projection, sizing for a service tier, time-to-payback estimate. The calculation has to be one the audience actually runs in their workflow. Without a real calculation, the calculator becomes vanity. + +**The calculation is non-trivial.** Multiplying two numbers does not need a calculator; the audience can do that in their head. Calibrating across 5-10 inputs with branching logic, applying industry benchmarks, or running a multi-scenario comparison earns the format. + +**The brand has methodology authority.** The output has to be defensible. Brands with research, customer data, or industry expertise that informs the calculation can disclose methodology credibly. Brands without that authority often produce calculators audiences cannot trust. + +**The follow-up sequence has a real purpose for the lead.** Calculators capture a specific signal (the inputs reveal the lead's situation: company size, current configuration, projected savings). The sequence has to use that signal. A generic sequence wastes the input data. + +**The success metric is defined.** What does "the calculator works" look like? Lead volume, lead quality, downstream conversion, the audience citing the calculator in stakeholder conversations. Without the success metric defined, evaluation is impossible. + +When all five are present, the calculator is a strong investment. When two or fewer are present, a simpler magnet (template, checklist, or worked example) often serves better. + +--- + +## When a calculator does NOT earn the build + +Funnels where the calculator is the wrong tool. + +**The audience does not actually run this calculation.** The team imagines the audience would benefit from the calculation; the audience does not actually face this decision. Usage is low; the build cost was wasted. + +**The calculation is trivial.** A "savings calculator" that computes "monthly cost x 12" is not a calculator; it is a multiplication. The audience can do this without a tool. + +**The brand cannot disclose methodology honestly.** If the math depends on assumptions the brand cannot defend ("we estimate 60 percent improvement based on internal data we cannot share"), the calculator becomes a vanity tool by necessity. The audience that would benefit from a defensible calculator gets a brand-flattering one instead. + +**A simpler magnet would serve the same audience and goal.** A pricing PDF that shows worked examples and methodology might serve the same audience as a pricing calculator at one-tenth the build cost. Choose the simpler magnet when it would serve. + +**The audience is too small to justify the build.** A calculator for a niche of 200 prospects is hard to justify against the build cost. Direct outreach or a simpler resource may be more efficient. + +**The team cannot maintain the calculator.** Calculators decay as benchmarks change, product details evolve, and tooling updates. Without maintenance commitment, the calculator becomes a stale liability. + +The honest assessment matters more than the default. "Should we have a calculator" is not the question. "Is the calculator the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A calculator's cost is significant. Account for it honestly. + +**The build cost.** Methodology research, formula design, input UX, result UX, calculation engine, methodology disclosure, mobile responsiveness, edge-case handling. A meaningful calculator often takes 60-200 engineering hours plus design and copy. + +**The maintenance cost.** Benchmarks change; product details change; assumptions shift. Quarterly review and updates run 4-12 hours per active calculator. + +**The sequence cost.** The follow-up sequence using the input data is itself a build. 10-30 hours upfront. + +**The opportunity cost.** What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The calculator's success has to clear the bar of those alternatives. + +The decision frame. The calculator earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The methodology-authority precondition + +Without methodology authority, the calculator cannot be defensible. + +The audience's question. After running the calculator: "Where does this number come from?" + +If the team can answer with sources (industry benchmarks, customer data, public research, defensible assumptions), the calculator has methodology authority. The audience can trust the result and use it in their decision. + +If the team cannot answer ("our model just produces this number"), the calculator does not have methodology authority. The audience either does not trust the result or trusts it without understanding it (which is worse for the audience and ultimately for the brand). + +**How to assess methodology authority.** + +- Does the team have direct customer data on the calculation's central variables? +- Does the team have access to defensible industry benchmarks? +- Is the team willing to publish the methodology, or does the methodology have to stay proprietary? +- Can the team defend the methodology to a sophisticated stakeholder? + +If the answer to most of these is yes, the calculator has methodology authority. If the answer is no, the calculator is being built on assumptions that will not survive interrogation. + +--- + +## The decision worked example + +A SaaS analytics platform considering a "ROI of moving from spreadsheets" calculator. + +**Conditions check.** + +- Specific calculation: yes. Prospects evaluating the platform run an internal estimate of switching value. +- Non-trivial: yes. The calculation involves time-saved-per-week, hourly cost of analyst time, error-rate reduction, decision-speed lift, and implementation cost. +- Methodology authority: yes. The team has customer data on time saved, error reduction, and decision speed across 200+ deployed customers. +- Sequence has purpose: yes. Calculator inputs reveal company size, analytics maturity, and current tooling. Sequence can match the lead's profile. +- Success metric defined: yes. Lead volume from the calculator, lead quality (audience-fit at SaaS companies above 50 employees), downstream conversion to demo within 90 days. + +**Decision.** Build the calculator. The conditions warrant it. + +**Tier design.** Tier 1 (free): the headline annual savings number, the breakdown across time-saved, error-reduction, and decision-speed components, methodology disclosure linked. Tier 2 (email-gated): a PDF the prospect can share with their stakeholders showing the calculation in defensible form. Tier 3 (account-gated, optional): saved scenarios across multiple analyst counts and use-case configurations. + +**Maintenance commitment.** Quarterly review of the customer-data benchmarks. Update assumptions when the customer base shifts. + +The decision was not "should we have a calculator" but "given these conditions, this is the calculator to build." + +--- + +## When to choose a simpler magnet instead + +The calculator is the wrong tool. What works. + +**Pricing one-pager template.** When the calculation is "what would my pricing look like," a worked-example one-pager often serves better than a calculator. The prospect adapts the example; the team avoids building. + +**ROI worked-example PDF.** When the calculation is "what would I save," a PDF showing 3-5 worked-example customer scenarios often serves better. The prospect identifies which scenario matches them; the team gets a downloadable resource without engineering overhead. + +**Sizing checklist.** When the calculation is "what tier do I need," a checklist of features and team-size signals can guide the prospect to the right tier without a calculator. + +**Comparison table.** When the calculation is "is this better than the alternative," a static comparison table often serves better than a dynamic calculator. + +The pattern. Many "we need a calculator" intuitions are actually "we need a clear way to communicate this calculation to prospects." Often the simpler format works as well or better, at one-tenth the build cost. + +--- + +## When to retire a calculator + +Calculators decay. Retiring them is part of the discipline. + +**Retire when:** + +- Lead volume has dropped below baseline for two consecutive quarters. +- The product or pricing has changed enough that the calculator's calculations no longer reflect the offering. +- The benchmarks the calculator relies on are stale and the team cannot update them. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. A portfolio of stale calculators costs maintenance attention without producing results. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a calculator. The opportunity-cost frame. The methodology-authority precondition. The decision worked example. When to choose a simpler magnet. The retirement discipline. + +## Implementation choices that stay internal + +Specific calculator topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence. Specific tooling for calculator engineering, hosting, and integration. Specific methodology sources and update calendars. These vary by team. diff --git a/skills/calculator-design/references/common-calculator-failures.md b/skills/calculator-design/references/common-calculator-failures.md new file mode 100644 index 0000000..badb9cc --- /dev/null +++ b/skills/calculator-design/references/common-calculator-failures.md @@ -0,0 +1,179 @@ +# Common calculator failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the calculator did not work" or "the leads are unqualified" or "we cannot tell what the calculator is producing." + +--- + +## "Conversion rate is high; downstream conversion is near zero." + +**The diagnosis.** Lead-trap or vanity-output pattern. The audience captured did not get value; did not engage with the follow-up; did not convert downstream. + +**The cure.** Audit for lead-trap (`references/email-capture-decision-tree.md`). Audit for vanity-output (`references/result-presentation-patterns.md`). The result has to be specific, contextualized, and actionable; the email gate has to be on additional value, not on the result itself. + +--- + +## "Audience visits the calculator, runs it once, never returns." + +**The diagnosis.** The calculator does not produce a save-worthy or share-worthy result. No reason to come back. + +**The cure.** Add tier-2 value (PDF, saved scenario) that gives the user something to bring back to. Audit the result presentation (`references/result-presentation-patterns.md`); a result the user cannot share with stakeholders rarely produces return visits. + +--- + +## "Sales team says the calculator-sourced leads are unqualified." + +**The diagnosis.** Calculator's audience-fit is weak. The calculation does not match the buyer's actual decision; the audience captured is curious-but-not-buying. + +**The cure.** Audit the calculator's audience-fit. Does the calculation map to a real decision the buyer faces? If not, the calculator may be capturing wrong-segment leads. Detail also in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "We get questions about how the calculator works; we have no answer." + +**The diagnosis.** Methodology not documented. The team cannot defend the calculator's outputs. + +**The cure.** Document the methodology (`references/calculation-logic-transparency.md`, `references/methodology-disclosure-templates.md`). The methodology page should answer the audience's interrogation questions before they ask. + +--- + +## "We updated the product; the calculator outputs are now wrong." + +**The diagnosis.** No update cadence. The calculator drifted out of sync with the actual offering. + +**The cure.** Maintenance discipline. Quarterly review of every active calculator. Update inputs, recommendations, and pricing as the offering evolves. + +--- + +## "The calculator works; nobody uses it." + +**The diagnosis.** Calculator hidden in the site; no distribution; the audience does not know it exists. + +**The cure.** Distribution. Link to the calculator from related landing pages, blog posts, and navigation. Promote it in newsletter and social channels. Cite it in sales conversations. The calculator's existence is not enough; the audience has to know about it. + +--- + +## "Our calculator looks like our competitor's." + +**The diagnosis.** Generic calculator-template patterns produce generic calculators. Brand differentiation is absent. + +**The cure.** Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## "The form has 12 fields and 4 percent conversion." + +**The diagnosis.** Interrogation-form pattern. The calculator is collecting data, not delivering value. + +**The cure.** Audit the input set (`references/input-design-patterns.md`). Each input should affect the calculation. Remove fields that do not. + +--- + +## "Audience trusts our brand; the calculator outputs feel arbitrary." + +**The diagnosis.** Methodology disclosure missing. The brand's credibility does not transfer to the tool because the tool does not show its work. + +**The cure.** Disclose methodology (`references/calculation-logic-transparency.md`). The brand-trust is one part of credibility; the tool's transparency is a separate part. Both have to be present. + +--- + +## "Our pricing changed; the calculator was not updated for 6 months." + +**The diagnosis.** Maintenance lapse. The calculator's outputs were misleading for half a year. + +**The cure.** Set a maintenance trigger: when pricing or product details change, the calculator update is part of the change. Otherwise, set a calendar review at minimum quarterly. + +--- + +## "The calculator was great at launch; conversion has dropped 40 percent over a year." + +**The diagnosis.** Decay. Stale benchmarks; outdated references; methodology that no longer reflects the brand's offering. + +**The cure.** Audit and refresh. If the calculator is still relevant, update it. If it is not, retire it. + +--- + +## "The free result is just 'estimated savings: significant.'" + +**The diagnosis.** Vanity output. The free tier is a teaser rather than a substantive result. + +**The cure.** The free tier has to be substantive. "Estimated annual savings: $14,200" with breakdown and methodology beats "significant savings" with email gate. + +--- + +## "Audiences complete the inputs but do not opt for the PDF." + +**The diagnosis.** The PDF does not justify the email exchange. Either the PDF is the same content as the free result (no value-add) or the audience does not perceive the PDF as worth the email. + +**The cure.** Make the PDF genuinely better. Add comparison tables, case studies, or additional analysis. Frame the PDF as "what you can share with your CFO" so the audience sees the use case. + +--- + +## "We get traffic; we get email signups; the sales team never hears about the leads." + +**The diagnosis.** Sequence missing or poorly designed. The leads sit on the list without being routed to sales. + +**The cure.** Design the post-conversion flow. Calculator-sourced leads should be tagged, routed, and sequenced. Sales should know which leads came from the calculator and what the leads' inputs revealed. + +--- + +## "We added a calculator; our other lead magnets stopped converting." + +**The diagnosis.** Cannibalization. The calculator absorbed the audience that previously converted via other magnets. + +**The cure.** This may not be a failure. If the calculator-sourced leads are higher quality than the previous magnets, the cannibalization is a portfolio improvement. If the calculator absorbed leads but produced no incremental value, the calculator may have replaced a working magnet with a worse one. + +--- + +## "The calculator works on Chrome desktop; it breaks on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The calculator was tested on the team's primary platform; the audience's actual devices were not covered. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use; the calculator has to work there. + +--- + +## "The calculator estimates 60 percent savings; our actual customers see 35 percent." + +**The diagnosis.** The calculator's assumptions are flattering rather than accurate. The customers who used the calculator's projections are now disappointed. + +**The cure.** Recalibrate. Use actual customer cohort data to set the assumptions. The honest result may be less impressive on the marketing screen but earns more trust over time. + +--- + +## "We want to A/B test the calculator's email gate placement." + +**The diagnosis.** This is fine, but the test should be designed carefully. Moving the email gate is a gating-decision change that affects both conversion and lead quality. + +**The cure.** Test gate placement with both conversion-rate and downstream-conversion metrics. A change that lifts conversion but tanks downstream is a regression, not an improvement. + +--- + +## "The calculator's methodology page got 200 visits and 50 unsubscribes." + +**The diagnosis.** Likely the audience interrogated the methodology and found it wanting. Either the methodology has a real flaw, or the methodology page is unclear. + +**The cure.** Audit the methodology page. Either fix the methodology (if there is a real flaw) or clarify the page (if the issue is presentation). + +--- + +## The pattern across failures + +Most calculator failures fall into one of three patterns. + +**Pattern 1: The calculator does not deliver real value.** Vanity output, hidden methodology, lead-trap. The fix is to deliver real, defensible, accessible results. + +**Pattern 2: The calculator does not match the audience or decision.** Audience-fit weak, calculation-decision mismatch, interrogation-form. The fix is to align the calculator to the audience the brand serves and the decision the audience faces. + +**Pattern 3: The calculator decays.** Stale assumptions, outdated benchmarks, broken integration. The fix is maintenance discipline. + +The metric pattern: calculator failures often look fine on conversion rate. The signal is in lead quality, downstream conversion, and audience interrogation behavior. Programs that track only conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/calculator-design/references/email-capture-decision-tree.md b/skills/calculator-design/references/email-capture-decision-tree.md new file mode 100644 index 0000000..f1fb4fc --- /dev/null +++ b/skills/calculator-design/references/email-capture-decision-tree.md @@ -0,0 +1,205 @@ +# Email-capture decision tree + +What to give freely, what to gate. The lead-trap failure and the transparent-tool win. + +The single most consequential decision in calculator design is what gets shown freely and what requires an email. Get this wrong and the calculator is either a lead-trap (gating the result the user came for) or a missed opportunity (giving away everything with no capture mechanism). + +--- + +## The honest principle + +Give the audience the result they came for. Gate the additional value. + +The audience showed up to run a calculation. They want the answer. Gating the answer is bait-and-switch: the calculator promised a result, the user provided inputs, and the result is held hostage until they trade an email. + +The transparent alternative: give the result freely. The audience gets what they came for. The brand offers additional value (a PDF report, a saved scenario, a custom analysis) that the audience can opt in for. The email exchange is then for additional value, not for the result the calculator promised. + +--- + +## What to give freely + +Tier 1, no gate. + +**The headline result.** The number the user came for. "Your annual savings: $14,200" or "Recommended plan: Growth." + +**The breakdown.** The components that explain how the headline number was calculated. Necessary for the audience to defend the result. + +**A basic visualization.** A chart or comparison that helps the user see the relationship. + +**The methodology disclosure.** Either inline formulas or a methodology link. Necessary for the audience to trust the result. + +**Source citations.** Where the calculator's benchmarks come from. + +**The assumption list.** What the calculator assumes about the user's situation. + +This set is what the audience needs to use the calculator's output in their decision. Holding any of it hostage is the lead-trap pattern. + +--- + +## What to gate (with email) + +Tier 2, email-required. + +**A formatted PDF report.** The result, breakdown, methodology, and assumptions in a shareable format. The user can send this to their stakeholders. The PDF has to be genuinely better than a screenshot of the result; otherwise the gate is not justified. + +**A saved scenario the user can revisit.** Persistence across visits. The user adjusts inputs over time, returns to compare, sees how the result has changed. Email-required to identify the user. + +**A custom or deeper analysis.** A second-pass calculation that uses the user's inputs as a starting point and adds more depth (more variables, more scenarios, more methodology). Often delivered later (by email) rather than immediately. + +**Email-based notifications.** When the calculator's benchmarks change or new versions launch, the user can be notified. + +The discipline. Each gated tier has to add real value over the free tier. If the PDF is just "the same result in a PDF," the gate is not earning the email. + +--- + +## What to gate (with account or sign-up) + +Tier 3, account-required. + +**Save-and-compare across multiple scenarios.** The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +**Integration with the brand's product or service.** The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +**Historical comparison.** When the calculator is used periodically (monthly cost projection, quarterly review), the user's historical inputs and results are tracked. + +**Collaboration features.** Multiple users on the same account can model scenarios together. + +These features warrant the higher friction of account creation. Email alone is insufficient; the user needs persistent identity for these to work. + +--- + +## The lead-trap failure + +The pattern that destroys conversion. + +**The pattern.** The user enters inputs, hits Calculate, sees "enter your email to see your result." + +**Why it fails.** + +- The audience perceives the manipulation. The calculator promised a result; the result is hidden. +- Conversion drops. Many users abandon at the gate; some enter throwaway emails. +- The leads that do convert are unqualified or actively annoyed; downstream conversion is poor. +- The brand earns "lead-trap" reputation; future users who recognize the pattern bounce immediately. + +**Why teams build lead-traps.** Short-term thinking. The team optimizes for capture rate without measuring downstream conversion. The lead-trap looks like it works because the form-fill rate is high; the lead-trap fails because the leads do not convert. + +**The cure.** Restructure the calculator so the result is free and the additional value is gated. Conversion to the email gate may drop in absolute terms, but the leads that do opt in are higher-quality. + +--- + +## The transparent-tool win + +The pattern that compounds credibility. + +**The pattern.** The user enters inputs, sees the result immediately, and is offered a "Get this as a PDF" or "Save this scenario" option that requires email. + +**Why it works.** + +- The audience trusts the brand. The calculator delivered on its promise. +- The email opt-in is for additional value, not for the result. Users who opt in are signaling real interest in the topic. +- Lead quality is higher because the lead opted in for value-add, which signals genuine interest. +- The brand earns "honest" reputation; word-of-mouth and referral grow. + +**The metrics that matter.** + +- Free-tier completion rate (how many users finish the calculation and see the result). +- Email-tier conversion rate (of those who see the result, how many opt in for the additional value). +- Downstream conversion (of those who opted in, how many engage with the follow-up sequence and convert to the next step). + +The transparent-tool optimizes for downstream conversion, which is the metric that matters for the program. + +--- + +## The decision tree + +Walk through this for each gating decision. + +**Question 1: Is this the result the user came for?** + +- If yes: do not gate. Holding the user-promised result hostage is lead-trap. +- If no: continue. + +**Question 2: Is this additional value the user might want?** + +- If yes: gating is potentially appropriate. +- If no: do not gate; the user does not want it badly enough for the email exchange to be worthwhile. + +**Question 3: Is the additional value substantial enough to justify the email?** + +- If yes: gate it. The user gets real value; the brand gets the email; the exchange is honest. +- If no: do not gate; the gate is not earning its friction. + +**Question 4: Could the additional value be delivered better as a follow-up after the email?** + +- If yes: gate it as a follow-up offer in the post-result flow, not as a barrier to the result. +- If no: gate it as a clear "get this additional value" offer near the result. + +This decision tree separates honest gating from manipulative gating. + +--- + +## Worked examples + +**Example 1: SaaS pricing calculator.** + +- Free: recommended plan, monthly cost estimate, breakdown by component, methodology link. +- Email-gated: a PDF showing the recommendation, alternative plans considered, and a printable comparison table. +- Account-gated: ability to save the scenario and adjust over time as the team's needs change. + +The free tier delivers what the prospect came for. The email gate delivers a shareable artifact for the prospect's internal stakeholders. The account gate enables ongoing use. + +**Example 2: ROI calculator for a B2B service.** + +- Free: estimated annual savings, breakdown across cost reduction and productivity gains, methodology disclosure. +- Email-gated: PDF analysis with industry-comparison context and worked-example case study. +- Account-gated: not offered. The calculator is single-use; account creation is unnecessary friction. + +The free tier serves the audience. The email gate serves the prospect's internal stakeholders by providing a shareable analysis. + +**Example 3: Mortgage calculator.** + +- Free: estimated monthly payment, breakdown across principal, interest, taxes, insurance, methodology link. +- Email-gated: a personalized rate quote (which requires the bank to underwrite based on user inputs). +- Not offered: account creation. The calculator is a one-shot tool; account creation does not match the use case. + +The email gate is justified by genuine value-add (personalized rate quote requires underwriting). The free tier delivers the calculator's promise. + +--- + +## When the email gate is the wrong tool + +Sometimes no gating is the right answer. + +**Calculators built primarily for SEO or brand authority.** A widely-shared, well-ranked calculator can be a strong brand asset even without lead capture. The audience that uses it associates the brand with the topic; the SEO ranking compounds traffic. + +**Calculators where lead-capture friction destroys the value proposition.** A simple, quick-use calculator may be best as a no-gate tool. The audience uses it, gets value, returns; the brand becomes the source of the tool. + +**Calculators in regulated industries.** Some sectors have specific privacy or regulatory constraints on email capture. The calculator may need to operate without standard lead-capture flows. + +The decision depends on the program's goals. Not every calculator needs to be a lead magnet. Some calculators serve other purposes (SEO, brand, audience-building) better without gates. + +--- + +## Common gating failures + +**Result hidden behind email.** The lead-trap. Conversion drops; downstream metrics drop further. + +**Gate without value.** Email required to access something that should have been free; no real additional value behind the gate. + +**Gate that lies about what is gated.** "Get the full analysis" suggests the free version was incomplete; the user expects more depth, gets the same content reformatted, feels deceived. + +**Multiple gates in sequence.** Email for one tier, account for another, phone number for a third. Each step adds friction; cumulative drop-off destroys the audience. + +**Gate copy that is manipulative.** "Don't lose your result, give us your email" is hostile. "Want this as a PDF? Enter your email" is honest. + +**Gate placement that interrupts the result viewing.** The result loads; the user starts reading; a popup appears asking for email. The user's flow breaks; trust drops. + +--- + +## Methodology-level choices that stay in the public skill + +The honest principle. What to give freely. What to gate at email and at account level. The lead-trap failure pattern. The transparent-tool win pattern. The decision tree. Worked examples. When the email gate is the wrong tool. Common gating failures. + +## Implementation choices that stay internal + +Specific gating decisions for the team's calculators. Specific PDF templates and follow-up flows. Specific account-creation flows and integration patterns. Specific gate copy in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/skills/calculator-design/references/input-design-patterns.md b/skills/calculator-design/references/input-design-patterns.md new file mode 100644 index 0000000..4f8cf5d --- /dev/null +++ b/skills/calculator-design/references/input-design-patterns.md @@ -0,0 +1,218 @@ +# Input design patterns + +Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. + +The calculator's inputs are the audience's first interaction with the tool. Bad input design loses users before the calculation runs. Good input design respects the user's time and produces inputs that genuinely affect the math. + +--- + +## The necessity principle + +Each input should be necessary for the calculation. Inputs that do not affect the output meaningfully should not be asked for. + +**The test.** For each input, ask: does removing this input change the result by a meaningful amount? If no, the input is not necessary; remove it. + +**The interrogation-form failure.** Calculators that ask 18 inputs but only use 5 in the math are signaling that the form is collecting sales-qualification data. The audience can tell. Conversion drops; trust drops. + +**The honest input set.** Most calculators need 4-10 inputs. Tools asking 15+ inputs almost always have non-essential fields that should move to a separate (later, optional) interaction. + +**The exception: meaningful customization.** When inputs do affect the result and the audience values the customization, more inputs are warranted. A pricing calculator that customizes to industry, team size, use case, and feature needs may need 8-12 inputs because each input affects the output. + +The discipline. Audit the input set against the actual math. Remove fields that do not affect the result. + +--- + +## Default discipline + +Defaults reduce cognitive load. Bad defaults bias the result. + +**Honest defaults.** Set defaults to honest, sourced values. "Average company size: 50" if 50 is the median across the audience. "Typical conversion rate: 14 percent" if 14 percent is a defensible benchmark. + +**Sourced defaults.** When defaults come from external benchmarks, source them. A footnote or tooltip explaining the default's origin earns trust. + +**Adjustable defaults.** The user should be able to override the default with their actual value. Defaults that look hardcoded reduce trust; defaults the user can edit signal that the calculator respects the user's situation. + +**Bias-flattering defaults.** Defaults set to flatter the brand's outputs (high savings, low costs) destroy credibility when the user notices. The audience that catches the bias remembers it. + +**Default decay.** Defaults need updating as benchmarks shift. A default set in 2022 that has not been touched is stale; the audience that knows the current benchmark sees the gap. + +--- + +## Input types + +Choose the right input control for each variable. + +**Numeric input.** Free-form number entry. Use for variables that are user-specific and where exact values matter (revenue, customer count, monthly cost). Often warrants a tooltip explaining what the number represents. + +**Slider.** Visual range control. Use for percentage estimates and ranges where exact values are not knowable (conversion rate, growth rate, retention). Sliders communicate the range and reduce cognitive load on choosing a precise number. + +**Dropdown.** Select from predefined categories. Use for variables that are categorical (industry, region, company size band). Dropdowns prevent invalid inputs and group similar audiences. + +**Toggle.** Binary on/off. Use for feature inclusion/exclusion or scenario switching (with implementation / without implementation). + +**Stepper.** Increment/decrement controls. Use for small whole-number variables (number of users, number of locations) where the range is bounded. + +**Free text.** Open-ended text input. Use sparingly. Free text adds friction and rarely affects calculation; if the calculator needs free text to function, the calculation may be the wrong format. + +The choice depends on the variable's nature. The wrong control type adds friction; the right control type makes the input feel natural. + +--- + +## Progressive disclosure + +Show only the inputs the user is currently working through. + +**The pattern.** The calculator presents 2-4 inputs at a time. The user completes those, the next set appears. Each step builds on the previous. + +**When progressive disclosure helps.** When the calculator has 8+ inputs, when input groups are conceptually distinct (company info, then current state, then desired state), or when later inputs depend on earlier choices. + +**When progressive disclosure hurts.** When the calculator has 4-6 inputs that the user could complete in 30 seconds, hiding any of them adds friction. Single-page calculators are fine for short input sets. + +**Progress indicators.** When the calculator is multi-step, show progress ("Step 2 of 4") so the user knows the time commitment. + +**Back navigation.** The user should be able to go back and adjust earlier inputs without losing later ones. + +--- + +## Input grouping and visual flow + +Group related inputs visually. The user processes related inputs as a unit. + +**Logical groups.** + +- Company info (name, size, industry). +- Current state (current cost, current process, current tools). +- Desired state (target outcome, target timeline). +- Configuration choices (tier, options, add-ons). + +**Visual cues.** + +- Section headers for each group. +- Spacing between groups. +- Consistent input styles within a group. + +**Avoid.** + +- Mixing unrelated inputs in one section. +- Inconsistent label patterns across the form. +- Required-vs-optional ambiguity (mark required inputs explicitly). + +--- + +## Tooltips and explanations + +Inputs that are not self-explanatory need explanation. Inputs that are self-explanatory do not need it. + +**When tooltips help.** When the input requires context the user may not have ("Customer Acquisition Cost: the marketing and sales spend per new customer"), when the input has a specific definition that varies by interpretation, or when the default needs sourcing ("Industry average from [source]"). + +**When tooltips hurt.** When the input is obvious (no tooltip needed for "Number of users"), when the tooltip is marketing rather than explanation, or when the tooltip overwhelms the form visually. + +**Tooltip placement.** Inline (right next to the field label) or hover-triggered. Hover-triggered keeps the form clean for users who do not need explanation. + +**Tooltip discipline.** Each tooltip should answer one question. Multiple paragraphs in a tooltip signal that the input itself needs redesign. + +--- + +## Validation and error handling + +Inputs need validation. Errors need helpful messages. + +**Inline validation.** Validate as the user types or after they leave the field. Catch errors at the point of input, not at submission. + +**Helpful error messages.** "Number must be greater than 0" beats "Invalid input." "Try a value between 1 and 1000" beats "Out of range." + +**Avoid friction.** Validation that rejects too aggressively (rejecting all special characters when only a few cause problems) frustrates users. Error messages that scold ("You must enter...") signal a hostile form. + +**Required vs optional.** Mark required inputs explicitly. Optional inputs should be obvious (and rare; if it is not used, why ask). + +--- + +## Mobile input design + +Many calculator users are on mobile. The input experience has to work there. + +**Mobile-specific considerations.** + +- Touch-friendly input sizes (minimum 44x44 pixel touch targets). +- Numeric keyboards for numeric inputs (use input type="number" or appropriate inputmode). +- Sliders sized for thumb interaction. +- Dropdowns that work with native mobile selection. +- Sufficient spacing between inputs to prevent accidental taps. + +**Mobile testing.** Test the calculator on actual mobile devices, not just browser dev tools. Real-device behavior often differs. + +**Mobile-broken calculator failure.** Calculator works on desktop, breaks on mobile. The mobile audience either bounces or has a worse experience. This failure is common; mobile testing prevents it. + +--- + +## Input examples and worked patterns + +**Pattern: company info input set.** + +- Company size (dropdown: 1-10, 11-50, 51-200, 201-500, 501-2000, 2000+) +- Industry (dropdown of 8-12 categories) +- Current annual revenue (numeric, optional, with tooltip explaining how it affects calculation) + +3 inputs, 30 seconds to complete, all affect the calculation. + +**Pattern: current state input set.** + +- Current monthly cost (numeric, with tooltip) +- Current team size on the relevant function (numeric) +- Current process (dropdown: manual, partially automated, fully automated) + +3 inputs, sets the baseline for the calculation. + +**Pattern: desired state input set.** + +- Target outcome (dropdown: cost reduction, time savings, revenue lift, all of the above) +- Target timeline (slider: 3 months to 24 months) + +2 inputs, sets the goal for the calculation. + +Total: 8 inputs across 3 logical groups. Each input affects the math. Defaults reduce friction. Progressive disclosure presents groups one at a time. + +--- + +## Input decay + +Inputs need maintenance. + +**What decays.** + +- Defaults based on benchmarks that have shifted. +- Tooltips referencing tools or terms that have changed. +- Dropdown options that are no longer accurate (industry categories, product tiers). +- Sources cited in tooltips that no longer exist or have moved. + +**Maintenance cadence.** Quarterly review of every active calculator's inputs. Update defaults, refresh tooltips, prune stale options. + +**The decay-trust connection.** Stale defaults erode trust. The audience notices when "Industry Average: 14 percent (2022)" appears in a 2026 tool. + +--- + +## Common input failures + +**Too many inputs.** 15+ inputs signal interrogation rather than calculation. Audit for non-essential fields. + +**Bias-flattering defaults.** Defaults that produce favorable outputs for the brand. Audiences notice; trust drops. + +**Hardcoded defaults that cannot be changed.** The audience cannot adjust to their actual situation. The calculator feels generic. + +**Wrong input type for the variable.** Free text where dropdown would be better; dropdown where slider would be better. Adds friction. + +**Missing tooltips on non-obvious inputs.** The audience does not know what the input means; they guess; the result is meaningless. + +**Mobile-broken inputs.** Sliders impossible to grab on mobile; dropdowns that overflow; numeric keyboards not triggered. + +**Stale defaults.** Benchmarks from years ago; tooltips referencing deprecated tools; dropdown options that no longer match reality. + +--- + +## Methodology-level choices that stay in the public skill + +The necessity principle. Default discipline. Input type guidance. Progressive disclosure. Input grouping and visual flow. Tooltip discipline. Validation and error handling. Mobile input design. Input decay and maintenance. + +## Implementation choices that stay internal + +Specific input sets for specific calculators. Specific default values from the team's data sources. Specific tooltip copy in brand voice. Specific input components and styling. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/skills/calculator-design/references/methodology-disclosure-templates.md b/skills/calculator-design/references/methodology-disclosure-templates.md new file mode 100644 index 0000000..170bf18 --- /dev/null +++ b/skills/calculator-design/references/methodology-disclosure-templates.md @@ -0,0 +1,321 @@ +# Methodology disclosure templates + +Templates for assumption lists, methodology pages, source citations, formula explanations. Patterns for disclosing calculation logic in ways the audience can use to defend the result. + +A methodology disclosure is not a marketing document. It is a technical document that lets the audience interrogate the calculator. The templates here cover the patterns that hold up to interrogation. + +--- + +## Methodology page template + +A standalone page that explains the calculator's calculations in detail. + +**Structure.** + +``` +# How the [calculator name] is calculated + +## What this calculator does +[2-3 sentences describing the calculation in plain language] + +## The formulas +[Plain-text formulas with each variable defined] + +## Assumptions +[Plain-language list of what the calculator assumes] + +## Sources +[Citations for any external benchmarks or data] + +## Worked example +[A specific scenario with input values and resulting calculation] + +## Caveats +[What the calculator does not account for; when to seek additional analysis] + +## Updates +[Date of last methodology review; how often the calculator is updated] +``` + +--- + +## Assumption list template + +A plain-language list of assumptions, formatted for scan-ability. + +**Structure.** + +``` +## What this calculator assumes + +- [Assumption 1: stated plainly] +- [Assumption 2: stated plainly] +- [Assumption 3: stated plainly] + +## What this calculator does NOT account for + +- [Excluded factor 1] +- [Excluded factor 2] + +If your situation differs significantly from these assumptions, the result is an estimate; consider [additional resource] for more precise analysis. +``` + +**Example assumption list for a SaaS pricing calculator.** + +``` +## What this calculator assumes + +- Your team will use the platform daily across business hours. +- Implementation takes 4-6 weeks for teams in the 50-200 employee range. +- The recommended plan is based on typical usage patterns from our customer base. +- Productivity gains compound through year 1 and stabilize in year 2. + +## What this calculator does NOT account for + +- Custom integrations or enterprise SSO requirements. +- Volume discounts available for annual contracts above $50K. +- Migration cost from your current platform. + +If your situation involves enterprise SSO, custom integrations, or migration costs, talk to our team for a tailored estimate. +``` + +--- + +## Source citation template + +How to cite external benchmarks or data. + +**Inline citation pattern.** + +``` +Industry Average: 14 percent (Source: [Industry Benchmark Report 2025], page 23) +``` + +**Footnote pattern.** + +``` +Industry Average: 14 percent [^1] + +[^1]: Industry Benchmark Report 2025. Available at [URL]. Accessed [Date]. +``` + +**Multi-source pattern.** + +``` +The conversion-rate benchmark we use combines: +- Industry Benchmark Report 2025 (Source A) +- Our customer cohort data (n=200, 2024-2025) +- Public conversion-rate studies from [Source C] + +The composite benchmark is 14 percent. +``` + +**Internal-source pattern.** + +``` +Source: [Brand]'s customer cohort data, n=200, 2024-2025. The cohort represents customers in the 50-500 employee range across SaaS, e-commerce, and B2B services. +``` + +--- + +## Formula explanation template + +How to display formulas in ways the audience can verify. + +**Plain-text formula pattern.** + +``` +Annual savings = (current annual cost) - (estimated new annual cost) + first-year implementation savings + +Where: + current annual cost = current monthly cost x 12 + estimated new annual cost = recommended plan price x 12 + first-year implementation savings = $500 if migrating from a manual process, otherwise $0 +``` + +**Step-by-step calculation pattern.** + +``` +1. Calculate current annual cost: $3,000 / month x 12 = $36,000 +2. Calculate estimated new annual cost: $2,000 / month x 12 = $24,000 +3. Calculate cost reduction: $36,000 - $24,000 = $12,000 +4. Add first-year implementation savings: $12,000 + $2,200 = $14,200 + +Annual savings: $14,200 +``` + +**Conditional logic pattern.** + +``` +The recommended plan is determined by: + +If team size is 1-10: Starter plan ($X / month) +If team size is 11-50: Growth plan ($Y / month) +If team size is 51-200: Business plan ($Z / month) +If team size is 201+: Enterprise (contact for pricing) + +Plan recommendations may shift based on use case (e.g., teams with heavy data needs may benefit from a higher tier even at a lower seat count). +``` + +--- + +## Worked-example template + +A concrete scenario the audience can read end-to-end. + +**Structure.** + +``` +## Worked example: [scenario description] + +Inputs: +- [Input 1]: [value] +- [Input 2]: [value] +- [Input 3]: [value] + +Calculation: +[Step-by-step formula application] + +Result: +[Final output with units] + +Interpretation: +[1-2 sentences explaining what the result means and how the audience would use it] +``` + +**Example for a SaaS pricing calculator.** + +``` +## Worked example: 75-person B2B SaaS team + +Inputs: +- Team size: 75 +- Use case: Customer support +- Current solution: Manual spreadsheets + +Calculation: +- Recommended plan: Business ($45 / user / month) +- Monthly cost: 75 users x $45 = $3,375 +- Annual cost: $3,375 x 12 = $40,500 +- Estimated time savings: 8 hours / week / agent x 75 agents x $40 / hour x 50 weeks = $1.2M +- Net annual value: $1.2M - $40,500 = $1.16M + +Result: +- Recommended plan: Business +- Monthly investment: $3,375 +- Estimated annual time-savings value: $1.2M +- Net annual value: $1.16M + +Interpretation: +A 75-person customer-support team migrating from manual spreadsheets to the Business plan would invest $40,500 annually and save approximately $1.16M in time-equivalent value. The largest contributor is hours saved per agent per week. +``` + +--- + +## Caveats template + +What the calculator does not do, stated honestly. + +**Structure.** + +``` +## What this calculator does not account for + +- [Excluded factor 1]: why it is excluded and what to do if it matters +- [Excluded factor 2]: why it is excluded and what to do if it matters + +For situations involving [specific complex case], the calculator's estimate may not apply; consider [additional resource or contact] for more precise analysis. +``` + +**Why caveats matter.** Caveats signal the calculator's honesty. The audience that knows the caveats can use the result with appropriate confidence; the audience that does not know the caveats may apply the result to a situation it does not fit. + +**Common caveats to include.** + +- The calculator does not account for taxes, regulations, or jurisdiction-specific factors. +- The calculator does not account for one-time setup or migration costs. +- The calculator's benchmarks reflect the typical case; outliers may differ significantly. +- The calculator's projections are estimates, not guarantees. + +--- + +## Update-history template + +How to track methodology changes over time. + +**Structure.** + +``` +## Updates + +This calculator's methodology was last reviewed on [date]. + +Recent updates: +- [Date]: Updated industry-benchmark source from [old] to [new]. +- [Date]: Adjusted productivity-gains assumption based on cohort data through [year]. +- [Date]: Added consideration for [new factor]. + +Major version history: +- v1.0 ([date]): Initial release. +- v1.1 ([date]): Added [feature]. +- v2.0 ([date]): Refactored methodology to include [new dimension]. +``` + +**Why update history matters.** Audiences who relied on previous outputs can see what changed. The transparency about updates signals that the calculator is maintained, not abandoned. + +--- + +## Methodology integration patterns + +How to integrate the methodology disclosure into the calculator UI. + +**Pattern A: Inline disclosure.** The methodology appears alongside the result. Best for short calculations where the formula is digestible. + +**Pattern B: Expandable section.** "How this is calculated" expandable below the result. The user opens it if they want depth. + +**Pattern C: Linked methodology page.** A "How this is calculated" link to a separate page. Best for complex calculations. + +**Pattern D: Hover-revealed detail.** Each result component has a tooltip explaining how it was derived. Useful for multi-component results. + +**Pattern E: Methodology-in-PDF.** The free result shows the headline; the gated PDF contains full methodology. Works when the PDF is genuine value-add. + +--- + +## Audience-specific methodology depth + +Calibrate methodology depth to the audience's analytical sophistication. + +**Highly analytical audiences (engineers, finance, data scientists).** Detailed formulas, source citations, version history. The audience expects depth and rewards transparency. + +**Moderately analytical audiences (PMs, marketers, operations).** Plain-language formulas, key assumptions, summary citations. The audience wants to verify but does not need every variable. + +**Less analytical audiences (executives, generalists).** Plain-language summary of the methodology, key assumptions, "talk to us if you want depth" option. The audience trusts based on the summary; depth is available if needed. + +The discipline. Match the methodology depth to the audience that uses the calculator. Too thin loses analytical audiences; too dense loses generalist audiences. + +--- + +## Common methodology disclosure failures + +**No methodology shown.** Result without explanation; audience cannot verify or defend. + +**Methodology hidden behind email.** Lead-trap pattern applied to methodology; audience that wants to verify must opt in first. + +**Methodology in marketing language.** "Our proprietary algorithm draws on industry-leading data" is not methodology; it is brand copy. + +**Methodology that hides the assumptions.** Formulas shown; assumptions not stated; audience cannot tell what the calculator assumes about their situation. + +**Methodology that hides the sources.** Industry averages cited without attribution. + +**Methodology that does not match the calculation.** Stated methodology and actual implementation drift apart over time. + +**Methodology with no update history.** Calculator changes silently; audience that relied on previous outputs cannot see what changed. + +--- + +## Methodology-level choices that stay in the public skill + +The methodology page template. The assumption list template. The source citation patterns. Formula explanation patterns. Worked-example template. Caveats template. Update-history template. Methodology integration patterns. Audience-specific methodology depth. Common disclosure failures. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source-citation conventions and benchmark relationships. Specific formula-display tooling and styling. Specific worked-example libraries. The team's methodology update calendars and version control. These vary by team. diff --git a/skills/calculator-design/references/result-presentation-patterns.md b/skills/calculator-design/references/result-presentation-patterns.md new file mode 100644 index 0000000..5cd614b --- /dev/null +++ b/skills/calculator-design/references/result-presentation-patterns.md @@ -0,0 +1,247 @@ +# Result presentation patterns + +Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. The result is the calculator's product; bad presentation wastes the calculation work. + +A calculator that runs the right math and presents the result poorly fails as completely as a calculator that runs the wrong math. Result presentation is half the user experience. Get it wrong and the audience does not know what to do with the number they computed. + +--- + +## The presentation principle + +The result should be specific, contextualized, and actionable. + +**Specific.** A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." Precision matters; the audience uses the result in their actual decision. + +**Contextualized.** Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." Without the baseline, the number is just a number; with the baseline, it becomes meaningful. + +**Actionable.** What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step bridges from result to action. + +A result that hits all three is one the audience can use in their actual decision. A result that misses any of the three leaves the audience with an unanswered "so what." + +--- + +## The headline number + +The single most important output, large and prominent. + +**The pattern.** One number, one label, large type, central placement. The audience sees the headline number first. + +**Example headline outputs.** + +- "Estimated annual savings: $14,200" +- "Recommended plan: Growth (37 users, 3 admins)" +- "Time to payback: 8 months" +- "Estimated monthly cost: $2,400" + +**The discipline.** + +- One headline number, not five. Multiple competing headlines fragment the user's attention. +- Number with units. "$14,200" beats "14200." "8 months" beats "8." +- Honest framing. "Estimated" or "Projected" is honest; "Guaranteed" is overstatement. +- Visual hierarchy. The headline is the largest text on the result screen. + +**Headline number antipatterns.** + +- "Up to $50,000" (range with no specific value). +- "Significant savings" (no number). +- "X% improvement" (no base). +- Multiple competing numbers (user does not know which to focus on). + +--- + +## The breakdown + +Sub-results that explain how the headline number was calculated. + +**The pattern.** Below the headline, show the components that make up the result. + +**Example breakdown for an ROI calculator.** + +``` +Annual savings: $14,200 + + Cost reduction: $9,200 + Current cost: $36,000 + New cost: $26,800 + + Productivity gains: $4,000 + Hours saved per week: 8 + Hourly cost: $50 + Weeks per year: 50 + + Implementation savings: $1,000 (first year only) +``` + +**Why the breakdown matters.** + +- It makes the headline number defensible. The user can cite the components. +- It helps the user understand how their inputs influenced the result. Adjusting inputs becomes meaningful. +- It surfaces the assumptions implicitly. The user sees what the calculator weighted. + +**Breakdown display options.** + +- Stacked text (as above). +- Expandable section (compact by default; user opens for detail). +- Visual breakdown (stacked bar chart, pie chart for components). + +--- + +## Visualization + +Charts and graphics that help the user see the relationship. + +**When visualization helps.** + +- Comparing the result against a baseline ("current vs new"). +- Showing components contributing to a total ("savings breakdown"). +- Showing change over time ("month-by-month savings projection"). +- Showing thresholds ("you fall in the 'mid-market' band based on your inputs"). + +**When visualization hurts.** + +- When the data does not warrant a chart (a single number does not need a pie chart). +- When the chart obscures rather than clarifies (3D pie charts, gratuitous animation). +- When the chart cannot be interpreted on mobile. + +**Visualization patterns.** + +- **Bar comparison.** Current state vs new state. Easy to read; instant relative comparison. +- **Stacked bar (component breakdown).** Total height = headline; segments = components. +- **Line chart (time series).** Monthly cost projection over 12-24 months. +- **Threshold indicator.** Position the user's result on a scale ("you are at the 73rd percentile"). + +**Visualization quality discipline.** + +- Charts should be readable at the size displayed. +- Labels should be present and legible. +- Color should reinforce, not decorate (different colors for different components, not random palette). +- Mobile rendering should preserve readability; charts that work on desktop and break on mobile fail half the audience. + +--- + +## Scenario comparison + +Useful when the calculator is illustrating a delta between two states. + +**The pattern.** Show the user's current state and the projected state side-by-side, with the delta highlighted. + +**Example: SaaS migration calculator.** + +``` + Current New Change +Annual cost $36,000 $24,000 -$12,000 +Hours/week 12 hrs/wk 4 hrs/wk -8 hrs/wk +Errors/month 14 3 -11 +``` + +**Why scenario comparison works.** + +- The delta is the value proposition; showing both states makes the delta concrete. +- The user can see what they are giving up (if anything) alongside what they are gaining. +- The comparison format is familiar from spreadsheets and decision tools. + +**When scenario comparison applies.** Calculators that compare a current state to a proposed state (migrations, refinances, configurations). Less applicable to calculators that produce a single recommendation without an explicit baseline. + +--- + +## Result-presentation antipatterns + +Patterns that waste the calculation. + +**Buried result.** The result requires scrolling past 5 paragraphs of marketing. The user came for the result; serve it first. + +**Vague output.** "Significant" or "Up to" framing without specific values. The audience cannot use vague results in real decisions. + +**Result followed by 5 paragraphs of marketing.** The result is what the user came for; the brand pitch belongs after, not before. + +**Result that requires re-entering inputs to view.** Persist inputs and results within the session. Forcing re-entry is a friction the user did not consent to. + +**False precision.** "$14,237.42" when the inputs justify only "$14,000 (estimated)." Precision the math does not support erodes trust. + +**Multiple competing headlines.** Five "important" numbers; the user does not know what to focus on. + +**Disconnected result and breakdown.** The headline number does not obviously add up from the breakdown components. The user does the mental math, finds the gap, loses trust. + +**Result without a next step.** The user gets the number, then what? Without a next step, the calculator does not bridge to action. + +--- + +## Mobile result presentation + +The result should work on mobile. + +**Mobile-specific considerations.** + +- Headline number readable without zoom. +- Breakdown components stack vertically rather than spread horizontally. +- Visualizations sized for mobile screens; complex multi-axis charts often do not translate. +- Scroll position lands on the result, not the inputs. + +**Common mobile failures.** + +- Headline number tiny on mobile because it was sized for desktop. +- Breakdown table requires horizontal scroll. +- Charts illegible at mobile size. +- Result hidden below the fold; user does not know it loaded. + +--- + +## Result-to-action transitions + +The result should lead naturally to a next step. + +**Patterns.** + +- **CTA below the result.** "Get a PDF of this analysis" or "Save this scenario" or "Talk to our team about implementing this." +- **Multiple CTAs ranked.** Primary action prominent; secondary action visible but smaller; tertiary action available but not pushy. +- **Email-capture in context.** When the gated tier (PDF, save) is offered, the form appears in context with the result, not in a popup that breaks flow. + +**The discipline.** + +- The next step should match the audience's likely intent. After a savings calculator, "talk to sales" may be premature; "get a PDF I can share" may match. +- Multiple CTAs should not compete; rank them by likely user intent. +- The next step should be honest. Promising "instant analysis from a specialist" and delivering "we will email you in 5 days" breaks trust. + +--- + +## Result update behavior + +When the user adjusts inputs, the result updates. + +**Real-time updates.** As the user changes a slider, the result recalculates. Useful for exploration; the audience sees the relationship between inputs and result. + +**On-submit updates.** The user adjusts inputs, hits Calculate, sees the new result. Useful for calculators with many inputs where real-time updates would be distracting. + +**Hybrid.** Real-time for sliders and toggles; on-submit for full input changes. Common middle ground. + +**The choice.** Depends on calculator complexity and the value of input exploration. Calculators that benefit from "what if" exploration favor real-time; calculators that produce a definitive recommendation favor on-submit. + +--- + +## Result-context for share-ability + +When users share the result with stakeholders, the result has to be self-contained. + +**The principle.** The shared result (PDF, email, screenshot, link) should be interpretable by someone who did not run the calculator. + +**What share-able results need.** + +- The headline number and what it represents. +- The breakdown so the recipient can verify the math. +- The methodology so the recipient can interrogate the assumptions. +- The inputs so the recipient knows what scenario was modeled. +- Brand attribution so the recipient knows the source. + +**The non-shareable result.** "Your savings: $14,200" with no inputs, no methodology, no breakdown. The recipient cannot use this; they ignore it or come back to ask follow-up questions that should not have been necessary. + +The shareable result extends the calculator's reach. The audience that shares is bringing the brand into a conversation; make the result strong enough to carry that weight. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation principle (specific, contextualized, actionable). Headline number discipline. Breakdown patterns. Visualization patterns and discipline. Scenario comparison. Result-presentation antipatterns. Mobile result presentation. Result-to-action transitions. Result update behavior. Share-ability discipline. + +## Implementation choices that stay internal + +Specific result-page layouts for specific calculators. Specific visualization libraries and styling. Specific PDF templates for share-able results. Specific brand-voice copy for next-step CTAs. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/skills/calculator-design/references/tiered-value-structures.md b/skills/calculator-design/references/tiered-value-structures.md new file mode 100644 index 0000000..ce17cf8 --- /dev/null +++ b/skills/calculator-design/references/tiered-value-structures.md @@ -0,0 +1,236 @@ +# Tiered value structures + +Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. + +The architecture that lets calculators capture leads honestly. The user gets immediate value (free tier) and is offered progressively richer value at each tier with proportional friction. Each tier earns its gate. + +--- + +## The tier-design principle + +Each tier should add real value over the previous. Tiers that gate the same content at higher friction destroy trust. + +**Tier 1 (no gate).** Immediate, complete result. The audience gets what they came for. The free tier is not a teaser; it is the substantive output of the calculator. + +**Tier 2 (email-gated).** Additional value the user might want for sharing, persistence, or depth. Email is the appropriate friction level for this value. + +**Tier 3 (account-gated).** Persistent, multi-session, collaborative, or product-integrated value. Account creation is the appropriate friction level for this value. + +Each tier's friction matches its value-add. Tiers that ask for more friction than they justify destroy conversion. + +--- + +## Tier 1: free immediate result + +What lives at Tier 1. + +**The calculator's primary output.** The headline result the user came for. Annual savings, recommended plan, monthly cost, time to payback. + +**The breakdown.** Components that show how the headline was calculated. + +**Basic visualization.** A chart or comparison that helps the user see the relationship. + +**Methodology disclosure.** Either inline formulas or a methodology link. + +**Assumption list.** What the calculator assumes about the user's situation. + +**Source citations.** Where the calculator's benchmarks come from. + +The Tier 1 set is complete. A user who never opts into Tier 2 still got the calculator's full value. The brand still earns trust; the audience still associates the brand with the topic. + +**What Tier 1 should NOT include.** + +- A teaser version of the result that withholds the actual answer. +- A "preview" of the analysis that requires email to see in full. +- Marketing copy that displaces the result itself. + +--- + +## Tier 2: email-gated additional value + +What lives at Tier 2. + +**A formatted PDF report.** The Tier 1 content packaged in a shareable format. The PDF has to be genuinely better than a screenshot, or the gate is not justified. + +**A saved scenario.** The user's inputs and result persist; they can return to the calculator and see their previous calculation. + +**A custom analysis.** A deeper second-pass calculation, often delivered by email after submission. + +**Notification opt-in.** Updates when benchmarks change, when new calculator versions launch, or when the brand publishes related content. + +**Tier 2 design discipline.** + +- Each Tier 2 offering must clearly justify the email exchange. "Get a PDF that you can share with your CFO" is justifiable; "Get the same content in a PDF" is not. +- The email-capture form should appear in context with the offer, not as an interruption to the Tier 1 viewing. +- The follow-up email should deliver the promised value immediately, not delay it. + +--- + +## Tier 3: account-gated persistent value + +What lives at Tier 3. + +**Save-and-compare across multiple scenarios.** The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +**Historical tracking.** When the calculator is used periodically (monthly projection, quarterly review), the user's historical inputs and results are tracked over time. + +**Collaboration features.** Multiple users on the same account can model scenarios together. + +**Product integration.** The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +**Tier 3 design discipline.** + +- Account creation is significant friction. Tier 3 features must justify it. +- Tier 3 is often unnecessary. Many calculators serve their purpose with Tier 1 and Tier 2 alone; do not add Tier 3 unless the use case warrants it. +- Account-creation friction can be reduced (social login, magic link) but not eliminated. + +--- + +## Worked example: SaaS pricing calculator + +A B2B SaaS platform considering a tiered pricing calculator. + +**Tier 1 (free).** + +- The user enters team size, role distribution, and use case. +- Sees the recommended plan and the estimated monthly cost. +- Sees a breakdown showing per-seat cost, included features, and any add-ons. +- Sees a comparison against the next-tier-up plan with a brief explanation of when it would be worth it. +- Sees a methodology link explaining how recommendations are made. + +**Tier 2 (email-gated).** + +- A PDF showing the recommended plan, the breakdown, the next-tier comparison, and 2-3 customer case studies of similar teams using similar plans. +- The PDF is shareable and contains enough context for an internal stakeholder to evaluate. + +**Tier 3 (account-gated).** + +- The user can save the scenario and adjust inputs over time as the team grows. +- The user can model alternative scenarios (different team size, different use case) and compare side-by-side. +- The user can receive an email when their team size threshold suggests a tier change. + +Each tier earns its gate. The user can stop at Tier 1 and still get value. Tier 2 is offered as a way to share with stakeholders. Tier 3 is offered for users who want ongoing tracking. + +--- + +## Worked example: ROI calculator for a B2B service + +A B2B service company considering an ROI calculator. + +**Tier 1 (free).** + +- The user enters current cost, team size, and process maturity. +- Sees estimated annual savings. +- Sees a breakdown across cost reduction, productivity gains, and implementation savings. +- Sees the methodology disclosed inline. + +**Tier 2 (email-gated).** + +- A PDF showing the calculation in defensible form, with industry-context comparison and a worked-example case study from a similar customer. + +**Tier 3.** Not offered. The calculator is single-use; account creation would be unnecessary friction. + +The two-tier structure fits the use case. Adding Tier 3 would add friction without value. + +--- + +## Worked example: financial calculator (mortgage, refinance, savings) + +A financial services company considering a savings calculator. + +**Tier 1 (free).** + +- The user enters current loan details, target rate, and timeline. +- Sees estimated monthly savings, total savings over the loan term, and break-even point on closing costs. +- Sees the breakdown and methodology. + +**Tier 2 (email-gated).** + +- A PDF analysis with comparison across multiple lender scenarios. +- A personalized rate quote (which requires underwriting based on user inputs). + +**Tier 3.** Optional. An account that tracks the user's loan over time and notifies them when refinance opportunities emerge as rates change. + +The Tier 2 includes genuine value-add (personalized quote requires underwriting). The Tier 3 is optional for users who want ongoing monitoring. + +--- + +## Tier-design failures + +Patterns that look like tiered value but degrade trust. + +**Teaser-tier-as-Tier-1.** The free tier shows a partial result; the email tier shows the full result. This is lead-trap dressed as tiered value. + +**Same-content-different-format.** Tier 1 is the result on screen; Tier 2 is the same result in a PDF. The PDF is not value-add; the gate is not justified. + +**Inverted tiers.** Tier 1 is thin; Tier 2 is what should have been Tier 1; Tier 3 is what should have been Tier 2. The audience that gets Tier 1 sees nothing useful; conversion drops. + +**Tier-3 friction without Tier-3 value.** Account creation required for features that could have been email-only or free. Friction without value-add destroys the gate. + +**Surprise upsells.** The user opts into Tier 2; the email follow-up reveals additional gates the user did not anticipate. Trust drops. + +--- + +## The flat-tier alternative + +Some calculators do not need tiers. + +**When flat is right.** + +- Simple calculators where the result is the only output worth offering. +- Calculators built for SEO or brand authority where lead capture is secondary. +- Calculators where account creation does not match the use case. + +**The flat structure.** Tier 1 (free, complete result). Optional email opt-in for newsletter or related content (no gate, no friction). + +This structure works when the calculator's primary value is the calculation itself and the lead-capture motion is secondary or absent. + +--- + +## Tier transitions + +How the user moves from tier to tier. + +**Tier 1 to Tier 2.** The user sees the free result. Below or alongside, an offer: "Want this as a PDF you can share?" or "Save this scenario for later." Email-capture in context. + +**Tier 2 to Tier 3.** After the user has engaged with Tier 2 (downloaded the PDF, returned to the saved scenario), an offer: "Want to track this over time? Create an account." The friction increase is justified by the additional value. + +**The discipline.** Tier transitions should feel natural, not pushy. The user gets value at each tier; the next tier is offered, not demanded. + +--- + +## Tier maintenance + +Tiers decay along with the calculator. + +**Tier 1 maintenance.** Update defaults, refresh sources, update methodology as benchmarks shift. + +**Tier 2 maintenance.** Update PDF templates as the brand evolves; refresh case studies; update comparison data. + +**Tier 3 maintenance.** Maintain the account-side functionality; ensure persistence works; update integrations. + +**The retire-tier decision.** Tier 3 features that are not used can be retired. Tier 2 PDFs that no one downloads can be simplified. Periodic audit of tier usage informs maintenance. + +--- + +## Common tier failures + +**Tier 1 is a teaser.** Lead-trap pattern. + +**Tier 2 does not justify the email.** Same content, repackaged. + +**Tier 3 is offered but unused.** Friction without payoff; sometimes the right answer is to retire Tier 3. + +**Tier transitions are pushy.** Aggressive popups at each transition; the user feels pressured. + +**Tier maintenance lapses.** Stale PDFs, broken account features, outdated comparison data. + +--- + +## Methodology-level choices that stay in the public skill + +The tier-design principle. What lives at each tier. Tier-design discipline at each level. Worked examples across calculator types. The flat-tier alternative. Tier transitions. Tier maintenance. Common failures. + +## Implementation choices that stay internal + +Specific tier structures for specific calculators. Specific PDF templates and account-creation flows. Specific tooling for tier transitions. The team's tier-usage measurement and audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/SKILL.md b/skills/chatbot-flow-design/SKILL.md new file mode 100644 index 0000000..0cdffe9 --- /dev/null +++ b/skills/chatbot-flow-design/SKILL.md @@ -0,0 +1,266 @@ +--- +name: chatbot-flow-design +description: "Designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. Honest about scripted-bot (rigid trees, fail edge cases), hallucinating-bot (LLM without structure, makes things up), and structured-guided-conversation (LLM-powered with intent architecture and fallback discipline) patterns. Distinguishes chatbot DESIGN (this skill) from chatbot IMPLEMENTATION (engineering and platform work). Triggers on chatbot, conversational AI, AI agent, chat widget, intent design, conversational flow, bot escalation, LLM grounding. Also triggers when a chatbot is hallucinating, when a scripted bot is failing edge cases, or when a chatbot is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing conversational flows for chatbots and AI agents on websites. Distinguishes scripted-bot (rigid trees, fail edge cases) from hallucinating-bot (LLM without structure, makes things up) from structured-guided-conversation (LLM-powered with intent architecture and fallback discipline)" +display_order: 5 +--- + +# Chatbot Flow Design + +A senior growth practitioner's playbook for designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. The discipline of building a bot that knows what it knows and routes appropriately when it does not. + +Most chatbots on the web fail in one of two ways. Scripted bots break the moment a user phrases something the script did not anticipate; the user gets pushed through a decision tree that does not fit their situation. LLM-powered bots without structure hallucinate; they confidently answer questions about pricing, policy, or capabilities and frequently make up answers, creating support burden and trust damage. + +The chatbots that work do something different. They have an intent architecture that defines what the bot can and cannot handle. They ground their responses in a knowledge base so they do not invent facts. They have explicit fallback paths for unclear or out-of-scope intents. They escalate to humans cleanly when the bot's job is done. The audience trusts the bot because the bot is honest about its scope. + +The voice is the senior growth practitioner who has watched chatbots become trusted brand surfaces and watched them become liability risks. Practical, opinionated about the architecture that distinguishes the two outcomes, willing to call out when a chatbot is the wrong investment or when an existing chatbot needs to be redesigned rather than tuned. + +When to use this skill: scoping a chatbot for the first time, auditing a chatbot that hallucinates or fails edge cases, designing the intent architecture and fallback patterns, or deciding when to escalate to humans. + +--- + +## What this skill covers + +This skill spans chatbot design as conversational flow architecture, not chatbot implementation. The growth-tooling distinctions: + +- `ai-content-collaboration` covers AI in content workflows. This skill covers AI in customer-facing conversations. +- `integration-orchestrator` covers cross-team coordination for chatbot deployment. This skill is the conversational design itself. +- `pm-spec-writing` covers the spec for engineers building the bot. This skill is about WHAT the conversation should be; pm-spec-writing is about communicating it. +- `discovery-research-synthesis` covers customer research that informs intent architecture. Input to this skill, not part of it. +- **`chatbot-flow-design` (this skill)** is intent architecture, knowledge-base grounding, fallback patterns, and escalation discipline. + +The audience: growth marketers and product marketers shipping chatbot growth tooling, in-house teams designing conversational flows for marketing or support contexts, agencies running chatbot work for clients. + +Out of scope: AI in content workflows (covered by `ai-content-collaboration`); the engineering implementation of chatbots (handed off via `pm-spec-writing`); platform-specific bot configurations (those stay implementation-side); voice agents and IVR flows (different methodology though related principles apply). + +--- + +## The chatbot decision: when chatbots earn deployment + +Before designing the chatbot, decide whether a chatbot is the right tool. + +**Chatbots earn deployment when:** + +- The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. +- The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. +- The bot can ground its answers in real knowledge (documentation, product specs, pricing pages). Without grounding, the bot's answers are at best generic and at worst fabricated. +- The team can maintain the bot. Chatbots decay; intents drift; knowledge bases need updating. Without maintenance commitment, the bot becomes stale liability. + +**Chatbots do NOT earn deployment when:** + +- The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. +- The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates or stays so generic it adds no value. +- The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. +- The audience is small enough that direct human conversation is more efficient. +- The team cannot maintain the bot. Stale bots produce wrong answers. + +The decision is not "should we have a chatbot"; it is "is the chatbot the right tool for this specific audience and conversation." + +Detail in [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md). + +--- + +## Scripted-bot vs hallucinating-bot vs structured-guided-conversation + +The keystone framing. + +**Scripted-bot.** Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. The chatbot equivalent of an automated phone tree. Cost: the user's actual question goes unanswered; the bot pushes the user through paths that do not fit; the audience leaves with a worse experience than no bot. + +**Hallucinating-bot.** LLM-powered with no structure. Will confidently answer questions about pricing, policy, capabilities, and frequently make up answers. Liability risk; trust-eroding; support burden when wrong answers reach customers. Cost: the bot's confident wrong answers damage the brand more than no bot would; the team learns about the hallucinations through customer complaints. + +**Structured-guided-conversation.** LLM-powered with intent architecture, knowledge-base grounding, defined fallback paths, and explicit escalation to humans. The bot knows what it knows, knows what it does not, and routes appropriately. Cost: the design effort upfront is significant; the maintenance is real; the audience trusts the bot because the bot is honest about its scope. + +The litmus test. Ask the bot a question outside its intended scope. Does it confidently make up an answer (hallucinating), refuse rigidly (scripted), or honestly route the user to a human or alternative resource (structured-guided)? The third response is the goal. + +--- + +## Intent architecture + +Defining what the bot can and cannot handle. + +**The principle.** The bot has a defined set of intents it can handle. Each intent maps to a conversation pattern (questions to ask, knowledge to ground in, response to provide). Anything outside the intent set falls to fallback. + +**Intent design patterns.** + +- **Named intents.** "Pricing question," "feature comparison," "integration question," "support escalation," "demo request." Each intent is explicit. +- **Intent hierarchy.** Top-level categories with sub-intents. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question." +- **Intent boundaries.** Each intent has clear scope. Out-of-scope topics route to fallback. + +**Intent coverage.** The bot's intents should cover 70-90 percent of expected conversations. The remaining percentage falls to fallback. Trying to cover 100 percent often produces bloated intent sets that the bot cannot handle reliably. + +**Intent maintenance.** Intents drift as products evolve, audiences shift, and conversations change. Periodic review surfaces which intents are useful and which need refining. + +Detail in [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md). + +--- + +## Knowledge-base grounding + +The bot's responses must come from real knowledge, not made-up confidence. + +**The principle.** The bot's response generation should reference a structured knowledge base (documentation, product specs, pricing pages, support articles). The bot does not invent answers; it retrieves and presents. + +**Grounding patterns.** + +- **Retrieval-augmented generation (RAG).** The bot searches a knowledge base for relevant content before generating a response. The response is grounded in retrieved content. +- **Source-of-truth design.** The knowledge base is the canonical source. When the bot answers, the underlying source is identified. +- **Citation discipline.** The bot can cite the source ("based on our pricing page, ..."). Audiences benefit from knowing where the answer came from. +- **Knowledge-base maintenance.** The knowledge base is maintained as the product evolves; the bot's answers stay current. + +**The hallucinating-bot failure.** No grounding. The LLM generates confident-sounding answers from nothing. The team discovers wrong answers through customer complaints. + +**The structured-guided win.** Grounded answers. The bot's responses match the source-of-truth. Customer-facing accuracy is maintained. + +Detail in [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md). + +--- + +## Branching and conditional logic + +How the bot adapts the conversation based on user input. + +**The principle.** The bot's conversation can branch based on user inputs (intent recognized, prior answers, user attributes). Branching makes the conversation feel adaptive. + +**Branching patterns.** + +- **Intent-driven branching.** Different intents lead to different conversation flows. +- **Context-driven branching.** "Are you asking about plan A or plan B?" routes to plan-specific information. +- **User-attribute branching.** Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB. +- **Multi-turn branching.** The conversation deepens over turns; later turns build on earlier context. + +**Branching discipline.** Each branch should add value. Decorative branching (asking for confirmation when none is needed) adds friction. + +**Branching limits.** Bots that branch too deeply lose users. 3-5 turns is often the practical limit before the user wants resolution. + +Detail in [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md). + +--- + +## Fallback patterns + +What happens when intent is unclear or out-of-scope. + +**The principle.** Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." + +**Fallback patterns.** + +- **Clarifying question.** "Can you tell me more about what you are looking for?" Asks the user to refine; sometimes recovers. +- **Suggested intents.** "I can help with X, Y, or Z. Were you asking about one of those?" Surfaces what the bot can do. +- **Resource handoff.** "I cannot answer that, but here is our [documentation page] that covers it." +- **Human escalation.** "Let me connect you with a human who can help." + +**Fallback discipline.** Multiple fallback layers. First, try clarification. If unclear after one round, suggest alternatives or escalate. Do not loop the user through 5 clarification attempts. + +**The fallback-as-honesty principle.** A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers they were given confidently. + +Detail in [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md). + +--- + +## Escalation to human + +When, how, with what context handoff. + +**The principle.** Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. + +**Escalation triggers.** + +- **User-initiated.** "Talk to a human." The bot escalates immediately. +- **Out-of-scope intent.** The bot recognizes the user's intent is outside its scope; escalates with the intent context. +- **Repeated fallback.** After 2-3 unclear exchanges, the bot escalates rather than loop. +- **Sentiment-driven.** The user's sentiment indicates frustration; the bot escalates rather than persist. +- **High-stakes topic.** Sensitive topics (cancellations, complaints, security) escalate by default. + +**Escalation context handoff.** When escalating, the bot passes the conversation history and recognized intent to the human. The human does not start from scratch; they pick up where the bot left off. + +**The escalation-quality test.** Does the human pick up the context smoothly, or do they have to ask the user to repeat everything? The latter signals broken handoff. + +Detail in [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md). + +--- + +## Conversation analytics + +Measuring what the bot is and is not doing well. + +**The principle.** Track the bot's performance per intent, per fallback, per escalation. The data informs maintenance and design improvements. + +**Conversation metrics.** + +- **Intent recognition rate.** What percentage of conversations are correctly classified into intents? +- **Resolution rate per intent.** What percentage of conversations starting with intent X resolve successfully (user gets the answer they needed)? +- **Fallback rate.** What percentage of conversations hit fallback? High fallback rates signal intent gaps. +- **Escalation rate per intent.** What percentage of conversations within each intent escalate? High escalation may signal the intent should not be bot-handled. +- **User satisfaction.** Post-conversation surveys when feasible. Useful but limited; many users do not respond. + +**Diagnostic uses.** + +- High fallback rate: intents missing or unclear; expand or refine intent set. +- Low resolution rate per intent: knowledge base inadequate; improve grounding. +- High escalation rate per intent: the intent may not be appropriate for bot handling. +- High repeat-fallback within conversations: clarifying questions not landing; redesign clarification. + +Detail in [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md). + +- "Bot makes up answers about pricing." Hallucinating-bot pattern; no grounding to pricing source-of-truth. +- "Users say the bot is rigid and unhelpful." Scripted-bot pattern; intents do not cover real questions. +- "Sales is angry that the bot is qualifying leads wrong." Intent recognition or routing logic broken; audit qualification flow. +- "Support tickets increase after chatbot launch." Bot is producing wrong answers that send users to support; audit grounding and resolution. +- "Users abandon mid-conversation." Bot loops or fallback patterns are inadequate. +- "We cannot tell what the bot is actually doing." Analytics missing; instrument before further changes. +- "Bot was great at launch; quality has degraded." Maintenance lapse; knowledge base or intent set out of date. +- "Bot escalates to humans for everything." Escalation logic too permissive; bot should handle more. +- "Bot tries to handle everything itself." Escalation logic too restrictive; bot should escalate more. +- "Users complain the bot does not know what they asked five minutes ago." Conversation context not preserved across turns. + +--- + +## The framework: 12 considerations for chatbot flow design + +When designing or auditing a chatbot, walk these 12 considerations. + +1. **The chatbot decision.** Is a chatbot the right tool for this audience and conversation, or would a different channel serve? +2. **Structured-guided-conversation, not scripted or hallucinating.** Intent architecture; knowledge-base grounding; fallback discipline. +3. **Intent architecture sound.** Named intents with clear scope; coverage targets 70-90 percent of expected conversations. +4. **Knowledge-base grounded.** Responses retrieved from source-of-truth; the bot does not invent answers. +5. **Branching adds value.** Each branch serves a real need; depth limited to 3-5 turns. +6. **Fallback patterns multi-layered.** Clarification, suggested intents, resource handoff, human escalation. +7. **Escalation triggers defined.** User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. +8. **Escalation context handoff clean.** Humans pick up where the bot left off. +9. **Analytics instrumented.** Per-intent recognition, resolution, fallback, escalation rates. +10. **Maintenance cadence defined.** Knowledge base refreshed; intent set audited; bot quality verified. +11. **Brand voice consistent.** The bot sounds like the brand it represents. +12. **Audience-fit honest.** The bot serves the audience it can actually help; out-of-fit audiences get escalated quickly. + +The output of the framework is a chatbot that knows what it knows, grounds its answers in real knowledge, escalates appropriately, and earns trust by being honest about its scope. + +--- + +## Reference files + +- [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md) - When chatbots earn deployment and when they do not. The conditions that warrant the build. +- [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md) - Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. +- [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md) - Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. +- [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md) - How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. +- [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md) - What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. +- [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md) - When, how, with what context. Escalation triggers and handoff quality. +- [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md) - Per-intent metrics. Diagnostic uses. The data that informs maintenance. +- [`references/chatbot-anti-patterns.md`](references/chatbot-anti-patterns.md) - The patterns that look like chatbots but degrade trust. +- [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: chatbots earn deployment when they know what they don't know + +The chatbots that work as compounding assets are the ones the audience trusts. Not because they answer every question. Not because they are infinitely capable. Because they are honest about their scope, ground their answers in real knowledge, and escalate to humans when the bot's job is done. + +That is the bar. Below the bar are scripted-bots (rigid trees that fail edge cases) and hallucinating-bots (LLMs without structure that make things up). Above the bar are structured-guided-conversations where the bot's intent architecture, knowledge-base grounding, fallback discipline, and escalation patterns combine into a tool the audience can rely on. + +The discipline is in the design choices. The intents that define what the bot can do. The knowledge-base grounding that prevents hallucination. The fallback patterns that handle the unknown gracefully. The escalation logic that knows when to step aside. The analytics that surface what is working and what is not. The maintenance discipline that keeps the bot in sync with the brand it represents. diff --git a/skills/chatbot-flow-design/references/branching-and-conditional-logic.md b/skills/chatbot-flow-design/references/branching-and-conditional-logic.md new file mode 100644 index 0000000..7ca9f24 --- /dev/null +++ b/skills/chatbot-flow-design/references/branching-and-conditional-logic.md @@ -0,0 +1,269 @@ +# Branching and conditional logic + +How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. + +The bot's conversation can branch based on user inputs. Branching makes the conversation feel adaptive; over-branching makes it feel labyrinthine. + +--- + +## The adaptive principle + +The bot adapts the conversation to the user's situation. Branching is the mechanism. + +**The win.** A user asks about pricing; the bot recognizes the user is on the enterprise track (from earlier inputs or context); the response includes enterprise-specific information rather than starter-tier information. + +**The fail (no branching).** Every user gets the same response regardless of context. The pricing question gets a generic answer that helps no one specifically. + +**The fail (over-branching).** The conversation branches at every turn; the user feels stuck in a labyrinth; resolution recedes. + +The discipline. Branch when branching adds value. Avoid branching when it adds friction. + +--- + +## Pattern A: Intent-driven branching + +Different intents lead to different conversation flows. + +**How it works.** + +- The bot recognizes the user's intent. +- The conversation flow for that intent kicks in. +- Each intent has its own scripted or templated response pattern. + +**Example.** + +User: "How much does the Pro plan cost?" +Bot recognizes "pricing question" intent. +Bot routes to pricing-conversation flow: +- Retrieves pricing. +- Presents Pro plan pricing. +- Offers follow-up: "Would you like to compare with other tiers, or talk to sales for a custom quote?" + +**Strengths.** + +- Each intent gets a dedicated, optimized flow. +- Easy to maintain (changes to one intent do not affect others). + +**Weaknesses.** + +- Requires intent recognition to work reliably. +- Cross-intent topics may not fit any single flow. + +**When to use.** Default for most chatbots. Intent-driven branching is the foundation. + +--- + +## Pattern B: Context-driven branching + +Branching within an intent based on context. + +**How it works.** + +- Within an intent's flow, the bot asks clarifying questions or branches based on context. +- "Are you asking about plan A or plan B?" routes the rest of the conversation to plan-specific information. + +**Example.** + +User: "How does the API work?" +Bot recognizes "integration question" intent. +Within the integration flow, the bot asks: "Are you looking at REST or GraphQL?" +User: "REST." +Bot routes to REST-specific information. + +**Strengths.** + +- Within-intent precision. +- The user feels heard; the response addresses their specific situation. + +**Weaknesses.** + +- Each clarifying question adds a turn; can frustrate users who want quick answers. + +**The discipline.** Use context-driven branching only when the context genuinely affects the response. Decorative clarifications add friction. + +--- + +## Pattern C: User-attribute branching + +Branching based on user attributes (logged-in status, role, segment). + +**How it works.** + +- The bot accesses user attributes (often from a CRM or session data). +- Responses adapt to those attributes. +- "Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB." + +**Example.** + +User: "Tell me about your pricing." +Bot detects the user is from a domain associated with an enterprise account. +Bot routes to enterprise-specific pricing conversation: "For teams of 200+, we offer a custom Enterprise plan. Here are the typical components..." + +**Strengths.** + +- Highly personalized. +- The right information for the right audience. + +**Weaknesses.** + +- Requires attribute infrastructure (CRM integration, session data). +- Privacy considerations (the bot is using data the user may not have explicitly shared). +- Risk of getting attributes wrong (a freelancer with a corporate domain treated as enterprise). + +**When to use.** When the attribute infrastructure exists and the personalization genuinely improves the experience. + +--- + +## Pattern D: Multi-turn branching + +The conversation deepens over turns. Later turns build on earlier context. + +**How it works.** + +- The bot maintains conversation state across turns. +- Each turn's response considers what was said in previous turns. +- The conversation can pivot, deepen, or refocus based on the cumulative context. + +**Example.** + +Turn 1. +User: "I am evaluating CRMs." +Bot: "What size is your team?" +User: "We have 25 sales reps." + +Turn 2. +Bot: "For a team of 25, our Growth plan often fits. Are you looking at any specific features?" +User: "We need integration with HubSpot." + +Turn 3. +Bot: "Our HubSpot integration supports two-way sync, lead routing, and custom fields. Would you like to see a demo focused on this integration?" + +The conversation deepens. Each turn builds on the previous. + +**Strengths.** + +- Conversation feels natural. +- Bot can handle complex inquiries that require multiple inputs. + +**Weaknesses.** + +- Conversation state management is complex. +- Long conversations risk losing context. +- Users may want resolution faster than multi-turn allows. + +**The discipline.** Limit multi-turn conversations to 3-5 turns before either resolving, escalating, or offering a summary handoff. Beyond that, users abandon. + +--- + +## Branching depth limits + +Bots that branch too deeply lose users. + +**The 3-5 turn principle.** Most users want resolution within 3-5 turns. Beyond that, the bot's value declines. + +**When 3-5 turns is enough.** Most marketing-site Q&A, simple support, qualification. + +**When more turns are needed.** Complex troubleshooting, detailed product configuration. In these cases, the bot should consider escalating to a human or offering a richer interface (form, video walkthrough). + +**Branching as turn-cost.** Each branch adds a turn. Branches that do not resolve within the turn budget should be reconsidered. + +--- + +## Branching design patterns + +How to structure branches. + +**Linear branching.** A then B then C. Simple; fits intent-driven patterns. + +**Tree branching.** A leads to B or C; each leads to further options. Common; fits context-driven and user-attribute patterns. + +**Loop-back branching.** Conversation can return to earlier turns. Useful when users want to compare options. + +**Open-ended branching.** Conversation can take multiple paths from any point. Most flexible; hardest to maintain. + +The choice depends on conversation complexity. Most chatbots benefit from tree branching with limited depth. + +--- + +## Branching and brand voice + +The bot's voice should stay consistent across branches. + +**The principle.** Branching changes the conversation's content; the brand voice stays consistent. + +**Voice failures across branches.** + +- One intent's flow is formal; another is casual. Inconsistent. +- Bot voice shifts based on user attributes in ways that feel performative. +- Branches that adopt different personas confuse the user. + +The discipline. Voice consistent; content adaptive. + +--- + +## Conversation state management + +What the bot remembers across turns. + +**Within-conversation state.** + +- Recognized intent and sub-intent. +- Captured user inputs (company size, role, specific interests). +- Conversation history. +- Pending follow-up actions. + +**Across-conversation state.** When the user returns later (in the same session or a new session), what does the bot remember? + +- Logged-in users: bot may remember previous conversations. +- Anonymous users: bot typically starts fresh; some implementations use cookies for limited memory. +- Privacy considerations: cross-session memory should be transparent and opt-in where appropriate. + +The discipline. State management should serve the user. State that improves the experience is good; state that surprises or feels invasive is bad. + +--- + +## Branching testing + +Test the bot across branching paths. + +**The challenge.** A bot with multiple branching points has many paths through any given conversation. Testing all paths is infeasible; testing critical paths is the discipline. + +**Critical paths.** + +- The most common conversation patterns (most-frequent intents). +- Each major branch point (one path that takes each branch). +- Edge cases (unusual user inputs that could break branching). + +**Testing methods.** + +- Manual testing of critical paths. +- Automated testing where feasible. +- Sampling production conversations to verify branching behavior. + +--- + +## Common branching failures + +**Decorative branching.** Clarifying questions that do not change the response; user feels stuck. + +**Branching without resolution.** Conversation branches but never resolves; user gives up. + +**Branching depth too deep.** 8+ turns without resolution; user abandons. + +**Inconsistent voice across branches.** Different intents speak differently. + +**State loss across turns.** Bot forgets earlier context; conversation feels disjointed. + +**Privacy-violating attribute branching.** Bot uses attributes the user did not consent to share. + +**Untested edge-case branches.** Specific paths break in production. + +--- + +## Methodology-level choices that stay in the public skill + +The adaptive principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Branching depth limits. Branching design patterns. Branching and brand voice. Conversation state management. Branching testing. Common failures. + +## Implementation choices that stay internal + +Specific branching designs for specific bots. Specific state management implementations. Specific tooling for branching and testing. The team's testing protocols. These vary by team. diff --git a/skills/chatbot-flow-design/references/chatbot-anti-patterns.md b/skills/chatbot-flow-design/references/chatbot-anti-patterns.md new file mode 100644 index 0000000..52d7dda --- /dev/null +++ b/skills/chatbot-flow-design/references/chatbot-anti-patterns.md @@ -0,0 +1,224 @@ +# Chatbot anti-patterns + +The patterns that look like chatbots but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The scripted-bot + +The pattern. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. + +The signal. Users complain the bot is rigid; bot fails any conversation that does not match the predefined paths. + +The cost. The user's actual question goes unanswered. The bot pushes the user through paths that do not fit. Audience leaves with a worse experience than no bot. + +The cure. Move from rigid trees to LLM-powered intent recognition with grounded responses. Detail in `references/intent-architecture-patterns.md` and `references/knowledge-base-grounding-patterns.md`. + +--- + +## The hallucinating-bot + +The pattern. LLM-powered with no structure. Confidently answers questions about pricing, policy, capabilities, and frequently makes up answers. + +The signal. Customer complaints about wrong information from the bot; sales or support hearing audiences cite incorrect bot answers. + +The cost. Liability risk. Trust damage. Support burden when wrong answers reach customers. + +The cure. Add intent architecture and knowledge-base grounding. The bot retrieves from sources-of-truth rather than generating from training data. + +--- + +## The bot-that-tries-to-handle-everything + +The pattern. Bot scope is "anything the user asks." No defined intents; no fallback discipline. + +The signal. High hallucination rate; high resolution-rate variability across topics; users get inconsistent experiences. + +The cost. The bot is unreliable. Some conversations work; many do not. Users cannot predict what they will get. + +The cure. Define explicit intent scope. Honest fallback for everything outside scope. Detail in `references/intent-architecture-patterns.md`. + +--- + +## The bot-that-handles-nothing + +The pattern. Bot's intent set is so narrow that most conversations fall to fallback or escalation. + +The signal. High fallback rate; high escalation rate; bot adds little value over a contact form. + +The cost. The build cost was significant; the value delivered is small. + +The cure. Expand the intent set to cover the conversations the audience actually has. Detail in `references/intent-architecture-patterns.md` (intent coverage section). + +--- + +## The bot-that-loops + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. Detail in `references/fallback-pattern-design.md` (fallback loop section). + +--- + +## The bot-that-refuses-rigidly + +The pattern. Bot says "I cannot help with that" without offering paths forward. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer alternatives. Resource handoff or human escalation. The bot's "I cannot help" should be followed by "but here is what might." + +--- + +## The bot-with-no-escalation + +The pattern. Bot tries to handle everything itself; rarely escalates; users get stuck with bot for conversations needing humans. + +The signal. Specific intents have high abandonment; users complaining they could not reach a human; sensitive topics handled poorly by the bot. + +The cost. The user's frustration compounds. The brand earns "you cannot reach a human" reputation. + +The cure. Define escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## The bot-that-escalates-everything + +The pattern. Bot escalates almost every conversation; the bot is not really doing its job. + +The signal. Escalation rate near 100 percent; bot adds friction without value. + +The cost. The bot is decorative. The team built a chatbot when they needed staffing. + +The cure. Either expand the bot's intent handling capability or reconsider whether the chatbot is the right tool. Sometimes the answer is to invest in human chat instead. + +--- + +## The bot-with-broken-handoff + +The pattern. Bot escalates; human picks up; the human starts from scratch because the context was not passed. + +The signal. Users complain about repeating themselves; humans report not knowing what the bot was discussing. + +The cost. The escalation experience is broken. Users feel the bot was wasted effort. + +The cure. Test the handoff. Ensure the human sees the conversation history and recognized intent. Detail in `references/escalation-to-human-patterns.md` (context handoff section). + +--- + +## The bot-with-stale-knowledge + +The pattern. Knowledge base not updated; bot answers reflect outdated reality. + +The signal. Bot answers contradict current product; users notice; sales hears about wrong information. + +The cost. Trust damage. Each wrong answer is a moment the brand lost credibility. + +The cure. Knowledge-base maintenance discipline. Quarterly review at minimum. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## The bot-with-no-citation + +The pattern. Bot generates answers without citing sources. Users cannot verify. + +The signal. Hallucination goes undetected because there is no verification path; users with deeper questions abandon because they cannot follow up. + +The cost. Trust does not compound. Each answer is taken on faith; some are wrong. + +The cure. Citation discipline. Bot cites sources; users can verify. Detail in `references/knowledge-base-grounding-patterns.md` (citation discipline section). + +--- + +## The bot-with-inconsistent-voice + +The pattern. Different intents speak in different voices. Bot voice does not match brand voice elsewhere. + +The signal. Users report the bot feels disjointed; brand voice is fragmented. + +The cost. Brand consistency suffers. The bot is a brand surface that is undermining the brand. + +The cure. Brand voice document including bot examples. Test conversations across intents. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The bot-with-no-analytics + +The pattern. Bot launched without per-intent tracking. Quality is invisible. + +The signal. Cannot diagnose issues; cannot track decay; remediation is guesswork. + +The cost. Quality decays unnoticed. Maintenance happens only when customers complain (too late). + +The cure. Instrument before launch. Per-intent recognition, resolution, fallback, escalation rates. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## The bot-that-pretends-to-be-human + +The pattern. Bot does not disclose it is a bot; users think they are talking to a human. + +The signal. Users feel deceived when they realize; complaints about hidden automation; trust collapse. + +The cost. Trust damage that can be hard to recover. Brand earns "deceptive" descriptors. + +The cure. Disclose that the user is talking to a bot. Modern AI chatbots can be disclosed openly without losing engagement; users often appreciate the honesty. + +--- + +## The bot-with-mobile-broken-UI + +The pattern. Bot works on desktop; UI breaks on mobile. Conversation cramped; input field hidden; responses overflow. + +The signal. Mobile conversation completion is significantly lower than desktop. + +The cost. Mobile audience underserved. Mobile is often the majority of traffic. + +The cure. Mobile-first chatbot UI design. Test on actual devices. + +--- + +## The bot-without-availability-disclosure + +The pattern. Bot escalates to humans without communicating that humans may not be available. + +The signal. Users wait indefinitely for a human; abandonment after escalation; frustration. + +The cost. Escalation creates expectation that is not met. Worse than no escalation. + +The cure. Communicate availability honestly. "Our team is available [hours]." Or offer async alternatives. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active bot, looking specifically for these anti-patterns. + +**Audit questions per bot.** + +- Does the bot have explicit intents (anti-pattern check: bot-that-tries-to-handle-everything, hallucinating-bot)? +- Are responses grounded in source-of-truth (anti-pattern check: hallucinating-bot, bot-with-no-citation)? +- Does fallback have multiple layers including escalation (anti-pattern check: bot-with-no-escalation, bot-that-loops)? +- Does escalation pass context (anti-pattern check: bot-with-broken-handoff)? +- Is the knowledge base maintained (anti-pattern check: bot-with-stale-knowledge)? +- Is brand voice consistent across intents (anti-pattern check: bot-with-inconsistent-voice)? +- Are analytics in place (anti-pattern check: bot-with-no-analytics)? +- Does the bot disclose its nature and human availability (anti-pattern check: bot-that-pretends-to-be-human, bot-without-availability-disclosure)? + +**The retire decision.** Anti-pattern bots often warrant retirement or significant redesign. Patching anti-patterns rarely produces a good bot. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/chatbot-flow-design/references/chatbot-decision-criteria.md b/skills/chatbot-flow-design/references/chatbot-decision-criteria.md new file mode 100644 index 0000000..501d77a --- /dev/null +++ b/skills/chatbot-flow-design/references/chatbot-decision-criteria.md @@ -0,0 +1,163 @@ +# Chatbot decision criteria + +When chatbots earn deployment and when they do not. The conditions that warrant the build, and the funnels where a chatbot adds friction without lift. + +A chatbot is a meaningful build. Intent architecture, knowledge-base grounding, fallback patterns, escalation logic, ongoing maintenance. The chatbot earns this investment only when specific conditions are present. + +--- + +## When chatbots earn deployment + +Five conditions that, when present, make a chatbot a strong investment. + +**The audience asks the same questions repeatedly.** FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. Without recurring question patterns, the bot has nothing to handle reliably. + +**The audience is on the site at hours when humans cannot respond.** Coverage gap that the bot fills meaningfully. Off-hours visitors get something instead of nothing. + +**The bot can ground its answers in real knowledge.** Documentation, product specs, pricing pages, support articles. Without grounding, the bot's answers are at best generic and at worst fabricated. + +**The team can maintain the bot.** Intents drift; knowledge bases need updating; conversation patterns shift. Without maintenance commitment, the bot becomes stale liability. + +**The success metric is defined.** Resolution rate, fallback rate, escalation rate, user satisfaction, downstream conversion. Without the success metric defined, evaluation is impossible. + +When all five are present, the chatbot is a strong investment. When two or fewer are present, a different channel (human chat, structured FAQ, contact form) often serves better. + +--- + +## When chatbots do NOT earn deployment + +Funnels where the chatbot is the wrong tool. + +**The audience expects human conversation.** Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. A chatbot in these contexts may be perceived as an obstacle to the human conversation the audience wants. + +**The team cannot ground the bot in real knowledge.** A bot without grounding either hallucinates (confident wrong answers) or stays so generic it adds no value (vague responses to specific questions). + +**The bot would replace working human channels.** Replacing a high-quality sales chat with a low-quality bot degrades the experience. The bot might be cheaper to operate but more expensive in lost conversions. + +**The audience is small enough that direct human conversation is more efficient.** Niche audiences with low conversation volume often work better with human-first channels; the chatbot's overhead is not justified. + +**The team cannot maintain the bot.** Stale bots produce wrong answers. Without quarterly maintenance commitment, the bot becomes a liability over time. + +**The conversation pattern is too varied to model.** Some audiences ask wildly different questions; the intent architecture cannot meaningfully cover the conversation space; the bot mostly fallbacks anyway. + +The honest assessment matters more than the default. "Should we have a chatbot" is not the question. "Is the chatbot the right tool for this audience and conversation pattern" is. + +--- + +## The opportunity-cost frame + +A chatbot is significant work. Account for the cost honestly. + +**The build cost.** Intent architecture, knowledge-base preparation, RAG pipeline, fallback design, escalation logic, conversation UI, brand-voice tuning, mobile responsiveness, analytics instrumentation. A meaningful chatbot often takes 80-300 engineering hours plus design and content for the knowledge base. + +**The maintenance cost.** Knowledge base updates, intent refinement, hallucination detection, conversation analytics review. Quarterly maintenance often runs 8-20 hours per active bot. + +**The escalation infrastructure cost.** Human handoff requires staffing or routing infrastructure. The bot does not eliminate the need for humans; it changes when humans are involved. + +**The opportunity cost.** What else could the team have built? A better support documentation site, a self-serve help center, a different growth-tooling investment. The chatbot's success has to clear the bar of those alternatives. + +The decision frame. The chatbot earns investment when it produces more value than the alternatives, accounting for build plus maintenance plus escalation infrastructure. + +--- + +## The grounding precondition + +Without knowledge-base grounding, the chatbot is the wrong tool. + +**The check.** Does the team have or can the team build a knowledge base that covers the conversation patterns the bot will handle? + +If yes, the chatbot can be grounded. The bot's responses retrieve from the knowledge base; hallucination risk is contained. + +If no (the team's knowledge is in people's heads, not documented), the chatbot will hallucinate or stay generic. The bot is the wrong tool until the knowledge base exists. + +**Building the knowledge base.** Sometimes the right move is to build the knowledge base first (which itself is valuable as documentation) before deploying the bot. The knowledge base serves users directly even before the bot accesses it. + +--- + +## The decision worked example + +A B2B SaaS company considering a chatbot for the marketing site. + +**Conditions check.** + +- Recurring questions: yes. Visitors ask about pricing, integrations, security, and demo requests recurringly. +- Off-hours coverage gap: yes. The team handles US business hours; international visitors get nothing in their evening hours. +- Knowledge-base grounding possible: yes. Pricing, integrations, security details all documented; FAQ exists; product specs are detailed. +- Maintenance commitment: yes. Marketing operations has capacity for quarterly bot review. +- Success metric defined: yes. Resolution rate per intent, escalation rate, downstream conversion to demo within 14 days. + +**Decision.** Build the chatbot. The conditions warrant it. + +**Intent architecture.** 7 named intents: pricing, integrations, security, demo request, support escalation, integration troubleshooting, account access. + +**Knowledge-base grounding.** RAG pipeline pulling from docs, pricing page, security page, integration catalog. + +**Fallback strategy.** Clarification on first unclear; suggested intents on second unclear; escalation to human on third or sentiment-driven. + +**Escalation handoff.** Bot passes conversation history and recognized intent to the human; the human picks up where the bot left off. + +The decision was not "should we have a chatbot" but "given these conditions, this is the chatbot to build." + +--- + +## The decision worked example: when to choose differently + +The same company considering a chatbot for sales conversations. + +**Conditions check.** + +- Recurring questions: partially. Sales conversations vary widely; while some patterns recur, the conversation often needs nuance. +- Off-hours coverage: not relevant; sales conversations work async via demo bookings already. +- Knowledge-base grounding possible: yes for product info; less so for personalized recommendations. +- Maintenance commitment: yes. +- Success metric: hard to define. Sales conversion is the goal; the bot's contribution is hard to attribute. + +**Decision.** Do not build a sales-focused chatbot. The audience expects human sales conversation; the bot would add friction. Use the bot for marketing-site Q&A and demo qualification; route demo requests to human sales. + +The decision was "is this chatbot right for this conversation" and the answer was "for some conversations yes, for others no." The bot's scope was constrained accordingly. + +--- + +## The audience-fit precondition + +The chatbot's audience must be willing to interact with chatbots. + +**Audiences that engage with chatbots well.** + +- Self-service-oriented users who want quick answers without human contact. +- Off-hours visitors who would otherwise get nothing. +- Users with specific factual questions (pricing, hours, policies). + +**Audiences that resist chatbots.** + +- Users who explicitly want to talk to a human (often signaled in the conversation opening). +- Sales-focused enterprise buyers expecting white-glove human attention. +- Users in distress (frustration, urgency) who need empathy not automation. + +**The discipline.** The chatbot should serve the audiences who engage well and escalate the audiences who do not. Trying to serve everyone with the bot fails both groups. + +--- + +## When to retire a chatbot + +Chatbots can be wrong even after being right initially. + +**Retire when:** + +- Resolution rate has dropped below an acceptable threshold consistently. +- Escalation rate climbs as intents fail to keep pace with audience evolution. +- The knowledge base maintenance burden exceeds the bot's value. +- A redesigned support model (better docs, expanded human team, different tooling) makes the bot unnecessary. +- The team can no longer commit to maintenance. + +The retiring discipline is part of the program. Stale bots produce wrong answers; honest retirement protects the brand. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant chatbot deployment. The conditions that argue against. The opportunity-cost frame. The grounding precondition. The audience-fit precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific chatbot scope decisions for specific audiences. The team's capacity benchmarks. Specific tooling for chatbot platforms, RAG pipelines, and analytics. Specific success-metric baselines. These vary by team. diff --git a/skills/chatbot-flow-design/references/common-chatbot-failures.md b/skills/chatbot-flow-design/references/common-chatbot-failures.md new file mode 100644 index 0000000..35d1c67 --- /dev/null +++ b/skills/chatbot-flow-design/references/common-chatbot-failures.md @@ -0,0 +1,187 @@ +# Common chatbot failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the bot is hallucinating" or "users complain the bot is unhelpful" or "we cannot tell what the bot is doing." + +--- + +## "Bot makes up answers about pricing." + +**The diagnosis.** Hallucinating-bot pattern. No grounding to pricing source-of-truth. + +**The cure.** Add knowledge-base grounding for pricing. The bot retrieves from the pricing page or pricing knowledge base; answers reflect the source. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## "Users say the bot is rigid and unhelpful." + +**The diagnosis.** Scripted-bot pattern. Intents do not cover real questions; bot fails when users phrase things unexpectedly. + +**The cure.** Move from rigid trees to LLM-powered intent recognition. Define more flexible intents. Add fallback that handles unexpected phrasings. Detail in `references/intent-architecture-patterns.md`. + +--- + +## "Sales is angry that the bot is qualifying leads wrong." + +**The diagnosis.** Intent recognition or routing logic broken. The bot is recognizing leads as one type when they should be another. + +**The cure.** Audit the qualification flow. Verify intent recognition with realistic test cases. Tighten routing logic. Add human review for edge cases. + +--- + +## "Support tickets increase after chatbot launch." + +**The diagnosis.** Bot is producing wrong answers that send users to support after the fact. Worse than no bot. + +**The cure.** Audit grounding and resolution. Identify the intents producing bad answers. Either improve grounding or escalate those intents to humans. Detail in `references/knowledge-base-grounding-patterns.md` and `references/escalation-to-human-patterns.md`. + +--- + +## "Users abandon mid-conversation." + +**The diagnosis.** Bot loops or fallback patterns are inadequate. Users get stuck without resolution path. + +**The cure.** Review fallback patterns. Limit clarification rounds. Add multi-layered fallback ending in human escalation. Detail in `references/fallback-pattern-design.md`. + +--- + +## "We cannot tell what the bot is actually doing." + +**The diagnosis.** Analytics missing. Without instrumentation, quality is invisible. + +**The cure.** Instrument per-intent recognition, resolution, fallback, and escalation rates before any further changes. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot was great at launch; quality has degraded." + +**The diagnosis.** Maintenance lapse. Knowledge base or intent set out of date. + +**The cure.** Quarterly maintenance review. Update knowledge base; refine intents; verify grounding. Set the maintenance trigger so updates happen alongside product changes. + +--- + +## "Bot escalates to humans for everything." + +**The diagnosis.** Escalation logic too permissive, or the bot's intent handling is so weak that everything ends up at humans. + +**The cure.** Audit which intents escalate most. If the bot can handle them with better grounding, fix that. If the bot truly cannot handle them, reconsider whether they should be in scope. + +--- + +## "Bot tries to handle everything itself." + +**The diagnosis.** Escalation logic too restrictive. Bot stays with conversations it should not. + +**The cure.** Add escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Users complain the bot does not know what they asked five minutes ago." + +**The diagnosis.** Conversation context not preserved across turns. Bot treats each message as standalone. + +**The cure.** Implement conversation state management. Bot remembers earlier turns within the same conversation; later responses build on that context. Detail in `references/branching-and-conditional-logic.md` (conversation state management section). + +--- + +## "Bot gives different answers to the same question." + +**The diagnosis.** Either grounding is inconsistent (different retrievals for similar queries), or the LLM generation has variability that produces different answers. + +**The cure.** Review grounding pipeline. Verify retrieval consistency. Tune generation parameters for consistency. Audit specific cases. + +--- + +## "We tried the bot in our pricing page; conversion went down." + +**The diagnosis.** Bot may be adding friction to a flow that worked. Some pages benefit from chatbots; some do not. + +**The cure.** A/B test bot presence vs absence on the affected pages. The data informs whether the bot is the right tool there. + +--- + +## "Bot ignores the user when sentiment is negative." + +**The diagnosis.** No sentiment-driven escalation. Bot continues handling conversations where the user is frustrated. + +**The cure.** Add sentiment-driven escalation. Recognize frustration signals; escalate to human. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Sales team finds qualification bot data unreliable." + +**The diagnosis.** Bot's qualification logic does not match sales-team criteria, or recognition is misclassifying leads. + +**The cure.** Align bot qualification with sales criteria. Audit recognition with sales feedback. Update intents and routing. + +--- + +## "We added a chatbot; our overall site conversion dropped." + +**The diagnosis.** Bot may be displacing higher-converting paths (direct CTAs, contact forms). Bot is the wrong tool for this audience or page. + +**The cure.** A/B test bot presence vs absence at the funnel level. If the bot reduces conversion, reconsider its placement or scope. + +--- + +## "Bot answers correctly but conversation never closes." + +**The diagnosis.** No clear conversation-end pattern. Bot keeps offering more help; user does not know when to stop. + +**The cure.** Add explicit conversation closing. "Anything else I can help with?" "If not, [next step option]." Detail in fallback patterns. + +--- + +## "We migrated platforms; the bot quality dropped." + +**The diagnosis.** Platform migration may have broken intent recognition, knowledge base integration, or escalation routing. + +**The cure.** Test the migrated bot end-to-end before declaring it ready. Critical paths first. Roll back if quality dropped significantly. + +--- + +## "Mobile conversations end with no resolution." + +**The diagnosis.** Mobile UI may be breaking; or the bot's responses may be too long for mobile screens. + +**The cure.** Mobile UI testing. Audit response lengths. Mobile-specific UI adjustments. + +--- + +## "We cannot tell which intents need work." + +**The diagnosis.** Analytics aggregated rather than per-intent. The intent-level signal is hidden. + +**The cure.** Per-intent analytics. Recognition rate, resolution rate, escalation rate, hallucination rate per intent. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot's voice does not sound like our brand." + +**The diagnosis.** Bot is using generic LLM voice; brand voice was not specifically tuned. + +**The cure.** Brand voice document including bot examples. Tune bot prompts and response patterns to match. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The pattern across failures + +Most chatbot failures fall into one of three patterns. + +**Pattern 1: The bot does not have proper architecture.** Hallucinating, scripted, no grounding, no fallback discipline. The fix is structural. + +**Pattern 2: The bot does not match the audience or context.** Bot in wrong context, wrong voice, wrong scope for audience. The fix is matching the bot to where it serves. + +**Pattern 3: The bot decays.** Knowledge base stale, intent set frozen, no maintenance. The fix is maintenance discipline. + +The metric pattern: chatbot failures often look fine on conversation count alone. The signal is in resolution rate per intent, hallucination rate, escalation quality, downstream conversion. Programs that track only conversation counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (architecture, audience-context match, decay). The principle that conversation count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/chatbot-flow-design/references/conversation-analytics-patterns.md b/skills/chatbot-flow-design/references/conversation-analytics-patterns.md new file mode 100644 index 0000000..5775305 --- /dev/null +++ b/skills/chatbot-flow-design/references/conversation-analytics-patterns.md @@ -0,0 +1,272 @@ +# Conversation analytics patterns + +Per-intent metrics. Diagnostic uses. The data that informs maintenance. + +Conversation analytics is the bot's diagnostic system. Without analytics, maintenance is guesswork; intent gaps go unnoticed; hallucination patterns persist; the bot's quality decays without anyone seeing the decay. + +--- + +## The instrumentation principle + +Track the bot's performance per intent, per fallback, per escalation. The data informs every maintenance decision. + +**The minimum tracking.** + +- Conversation start (a user opens the bot). +- Intent recognition (which intent the bot classified). +- Conversation outcome (resolved, fallback, escalation, abandoned). +- Per-turn data (each user message, each bot response). + +**The derived metrics.** + +- Intent recognition rate. +- Resolution rate per intent. +- Fallback rate. +- Escalation rate per intent. +- Abandonment rate. + +Without instrumentation, none of this data exists. Set up tracking before launch. + +--- + +## Intent recognition rate + +What percentage of conversations are correctly classified. + +**The metric.** Of conversations where the user expressed intent, what percentage did the bot recognize correctly? + +**Measurement methods.** + +- **Sample auditing.** Periodically sample conversations and verify intent classification manually. +- **User feedback signals.** Conversations where users complain or escalate often correlate with misrecognized intent. +- **Conversation outcome correlation.** Conversations resolved successfully often had correct intent recognition. + +**Diagnostic uses.** + +- Low recognition rate: intent set may not cover real conversations; recognition logic may be brittle. +- Specific intents misrecognized: those intents may be poorly defined or overlap with others. + +**Target ranges.** 80-90 percent recognition is achievable for well-designed chatbots. Below 70 percent suggests significant intent or recognition issues. + +--- + +## Resolution rate per intent + +What percentage of conversations starting with intent X resolve successfully. + +**Resolution definition.** The user got the answer they needed and the conversation ended successfully (no escalation, no abandonment, no follow-up indicating frustration). + +**Measurement methods.** + +- **Conversation completion plus user signal.** User explicitly says "thanks" or rates the conversation positively. +- **No follow-up issues.** User does not return with the same question or escalate later. +- **Direct survey.** Post-conversation survey asking if the user got what they needed. + +**Diagnostic uses.** + +- Low resolution per intent: the bot's grounding or response pattern for that intent is weak. +- Some intents have higher resolution than others: variation may signal intent design quality differences. + +**Target ranges.** 70-85 percent resolution per intent is reasonable. Lower for complex intents; higher for simple intents. + +--- + +## Fallback rate + +What percentage of conversations hit fallback at any point. + +**The metric.** Conversations where the bot's intent recognition failed or the bot's response did not address the user's need, requiring fallback. + +**Diagnostic uses.** + +- High fallback rate (above 25-30 percent): intent set may be missing common conversations. +- Specific fallback layers triggered disproportionately: that layer needs review. +- Fallback rate trending up: audience evolving away from current intent set. + +**Per-layer breakdown.** Track which fallback layers (clarification, suggested intents, resource handoff, human escalation) trigger most. Each tells a different story. + +--- + +## Escalation rate per intent + +What percentage of conversations within each intent escalate to humans. + +**The metric.** Of conversations classified as intent X, what percentage ended with human escalation? + +**Diagnostic uses.** + +- High escalation rate per intent: the intent may not be appropriate for bot handling; consider removing from bot scope. +- Low escalation rate per intent: bot may be over-handling; some conversations may benefit from earlier escalation. +- Specific intents with rising escalation: maintenance lapse or audience evolution. + +**The 100-percent-escalation intent.** An intent where the bot always escalates is not a bot intent; it should be a "tell me about [topic]; we will get back to you" intent or removed entirely. + +--- + +## Abandonment rate + +What percentage of conversations end without resolution or escalation (the user just leaves). + +**The metric.** Conversations where the user stops responding without indicating resolution. + +**Diagnostic uses.** + +- High abandonment: bot is failing to satisfy users; review fallback patterns and conversation flows. +- Abandonment concentrated at specific turn or intent: that point in the flow is breaking. +- Mid-conversation abandonment vs first-turn abandonment: different diagnostic implications. + +--- + +## User satisfaction + +When measurable, satisfaction is the highest-value metric. + +**Measurement methods.** + +- **Post-conversation rating.** "How was that conversation?" with 1-5 stars or thumbs up/down. +- **Post-conversation survey.** Brief survey after the conversation ends. +- **Sentiment analysis.** Programmatic analysis of conversation sentiment. + +**Diagnostic uses.** + +- Low satisfaction: bot is failing the user even when conversations technically complete. +- Satisfaction-resolution mismatch: bot resolves but users are unhappy; quality of resolution is poor. + +**Limitations.** + +- Many users do not respond to satisfaction surveys. +- Satisfaction can be biased (frustrated users more likely to respond than satisfied ones). +- Sentiment analysis can miss nuance. + +The metric is valuable but not the only signal. + +--- + +## Conversation length distribution + +How many turns the average conversation takes. + +**The metric.** Distribution of conversation turn count. + +**Diagnostic uses.** + +- Long average length: bot may be over-clarifying; conversations should resolve faster. +- Bimodal distribution (very short or very long): some conversations resolve quickly; others get stuck. +- Increasing trend: bot quality may be declining; users having to work harder. + +**Target ranges.** 2-5 turns for typical resolution. Longer for complex intents; shorter for simple ones. + +--- + +## Response time + +How quickly the bot responds. + +**The metric.** Time between user message and bot response. + +**Diagnostic uses.** + +- Slow response: user perceives the bot as sluggish; abandonment may climb. +- Variable response time: inconsistent experience; users unsure what to expect. + +**Target ranges.** Under 2 seconds for most responses. Longer responses (when retrieving or generating) should show typing indicators. + +--- + +## Hallucination tracking + +Specifically tracking when the bot generates wrong answers. + +**Detection methods.** + +- Sample auditing of bot responses against source-of-truth. +- User reports ("the bot said X; that is not right"). +- Citation verification (programmatic check that cited sources contain the cited content). + +**Diagnostic uses.** + +- Specific intents with hallucination rate: those intents need grounding review. +- Specific topics within intents: knowledge base may have gaps. +- Hallucination trend: if rate is rising, model or grounding may be drifting. + +**The honesty discipline.** Track hallucination explicitly. Teams that hide hallucination from themselves ship worse bots. + +--- + +## Conversation funnel + +Track conversations as a funnel from start to resolution. + +**The funnel.** + +- Conversation started. +- Intent recognized. +- First response delivered. +- User continued. +- Resolution achieved (or escalation, or abandonment). + +**Diagnostic uses.** Drop-off at each stage points to specific issues. + +- Drop-off after intent recognition: bot's first response is not engaging or is wrong. +- Drop-off mid-conversation: branching or follow-ups are not landing. +- Drop-off near resolution: closing or call-to-action is weak. + +--- + +## Per-segment analytics + +Different audience segments may experience the bot differently. + +**Segments.** + +- New visitors vs returning. +- Logged-in vs anonymous. +- Mobile vs desktop. +- Source of arrival (paid, organic, referral). + +**Diagnostic uses.** + +- Segments with worse outcomes signal segment-specific issues. +- Sometimes the right answer is segment-specific bot behavior. + +--- + +## Analytics review cadence + +How often to look at the data. + +**Weekly review.** For high-volume bots or recently launched bots. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable bots. Tracks trends and surfaces gradual decay. + +**Quarterly review.** For all active bots as part of the broader bot audit. + +**Triggered review.** When intent set changes, when knowledge base updates, when team escalation patterns shift. Ad-hoc reviews catch specific issues. + +--- + +## Common analytics failures + +**No instrumentation.** Bot launched without per-intent tracking; quality is invisible. + +**Vanity metrics.** Tracking conversation count without tracking outcome quality. + +**Aggregate-only tracking.** Conversation rate tracked but not per-intent; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; intent renames or schema changes broke the tracking. + +**Confounded data.** Multiple changes deployed simultaneously; cannot attribute changes to any one update. + +**No segment-level data.** Aggregate hides segment-specific issues. + +**No hallucination tracking.** Bot wrongness goes unnoticed until customers complain. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation principle. Intent recognition rate. Resolution rate per intent. Fallback rate. Escalation rate per intent. Abandonment rate. User satisfaction. Conversation length distribution. Response time. Hallucination tracking. Conversation funnel. Per-segment analytics. Analytics review cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific bots. Specific tooling for analytics implementation. Specific target ranges for the team's audience. The team's audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/references/escalation-to-human-patterns.md b/skills/chatbot-flow-design/references/escalation-to-human-patterns.md new file mode 100644 index 0000000..429ba8d --- /dev/null +++ b/skills/chatbot-flow-design/references/escalation-to-human-patterns.md @@ -0,0 +1,209 @@ +# Escalation to human patterns + +When, how, with what context. Escalation triggers and handoff quality. + +Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. Escalation done well preserves the conversation's momentum; escalation done poorly resets the user. + +--- + +## The escalation principle + +Escalation is part of the bot's job. A bot that knows when to step aside earns more trust than a bot that tries to handle everything. + +**The win.** The bot recognizes its scope is exceeded; escalates with the conversation context; the human picks up where the bot left off. + +**The fail (no escalation).** The bot tries to handle everything; produces wrong answers; the user has to start over with a human eventually. + +**The fail (broken escalation).** The bot escalates but the human starts from scratch; the user has to repeat everything. + +The discipline. Escalation triggers defined; context handoff clean. + +--- + +## Escalation triggers + +When the bot escalates. + +**User-initiated.** "Talk to a human." "I need to speak with someone." "Get me a person." + +The bot escalates immediately. Do not try to handle the request first; the user has been explicit. + +**Out-of-scope intent.** The bot recognizes the user's intent is outside its scope. + +The bot escalates with the intent context. "Looks like you have a [intent type] question; let me connect you with the team." + +**Repeated fallback.** After 2-3 unclear exchanges, the bot escalates rather than loop. + +The bot acknowledges: "I am having trouble understanding your question; let me get a human who can help." + +**Sentiment-driven.** The user's sentiment indicates frustration. + +The bot recognizes frustration signals (negative phrasing, repeated complaints, exclamation patterns) and escalates. + +**High-stakes topic.** Sensitive topics escalate by default. + +Account security, cancellations, complaints, signs of distress. The bot does not try to handle these; immediate escalation. + +**Complexity-driven.** The user's question requires deep customization or analysis the bot cannot provide. + +The bot acknowledges: "This needs a more detailed look; let me connect you with our team." + +--- + +## The context handoff + +When escalating, the bot passes context to the human. + +**What to pass.** + +- The conversation history (full transcript). +- The recognized intent (what the bot thought the user wanted). +- The user's situation (any captured attributes: company, role, source). +- The reason for escalation (user-initiated, out-of-scope, sentiment, etc.). +- Any pending follow-up actions. + +**The handoff format.** + +- Visible to the human in their tool of choice (CRM, support ticket system, chat panel). +- Structured so the human can scan it quickly. +- Accurate (the recognized intent matches what the user actually said). + +**The handoff failure.** The human picks up the conversation but does not see the context; they ask the user to repeat everything; the user feels the escalation was for nothing. + +The discipline. Test the handoff. The human should pick up the context smoothly. The user should feel the escalation moved them forward, not backward. + +--- + +## Escalation user experience + +What the user sees during escalation. + +**The pattern.** + +- Bot acknowledges the escalation: "Let me connect you with someone who can help." +- Bot provides expectation: "Someone from our team will be with you in [timeframe]." +- If the wait will be long, bot offers alternatives: "If you do not want to wait, you can [book a call / email us / submit a ticket]." +- Conversation transitions to human cleanly when the human joins. + +**The escalation-as-transition principle.** The user should feel the conversation continued, not started over. The transition from bot to human is part of the experience. + +--- + +## Escalation and human availability + +What happens when no human is available. + +**During business hours.** The bot escalates; a human picks up within the expected response time. + +**Off-hours.** The bot acknowledges: "Our team is available [hours]. I can take your information and have someone respond when they are back." + +**During high-volume.** The bot acknowledges the wait: "We are seeing high volume right now; expected wait is about [time]." + +**The honest framing.** The bot communicates availability honestly. Pretending humans are available when they are not creates frustrated users. + +**Asynchronous escalation.** When the user is willing, async escalation (email, ticket) is often better than waiting in chat. The bot can offer this option proactively. + +--- + +## Escalation routing + +Which human gets the conversation. + +**Routing patterns.** + +- **Single team.** All escalations go to one team (often support). Simple but may not match all conversation types. +- **Intent-based routing.** Different intents route to different teams (sales escalations to sales; support to support). +- **Tier-based routing.** Different user tiers route to different teams (enterprise to enterprise account managers; SMB to general support). +- **Context-based routing.** Routing combines intent, tier, and other attributes. + +**Routing failures.** + +- Wrong team gets the escalation; they have to re-route; user waits longer. +- Routing logic stale; teams have changed but the bot has not. +- Round-robin without consideration of expertise; users get inconsistent quality. + +**Routing maintenance.** Quarterly review of routing logic alongside team structure changes. + +--- + +## Escalation measurement + +Track escalation rate and quality. + +**Metrics.** + +- **Escalation rate.** What percentage of conversations escalate? +- **Escalation rate per intent.** Some intents may escalate more often than others. +- **Time-to-human-pickup.** How quickly does the human respond after escalation? +- **Resolution after escalation.** What percentage of escalated conversations resolve? +- **User satisfaction post-escalation.** When measurable. + +**Diagnostic uses.** + +- High escalation rate per intent: that intent may not be appropriate for bot handling. +- Long time-to-human: staffing or routing issues. +- Low resolution after escalation: handoff quality may be poor or the team may not have the resources. + +The data informs both bot maintenance and human team capacity planning. + +--- + +## Bot-to-human transition design + +The moment the human joins the conversation. + +**Pattern A: Visible transition.** The user sees a message: "Hi, I am [name] from the team. I see you were asking about [topic]; how can I help?" + +The transition is explicit; the user knows they are now with a human. + +**Pattern B: Continuous transition.** The conversation continues without explicit handoff; the bot's voice fades; the human's voice picks up. + +Less common; can confuse users about who they are talking to. + +**Pattern C: Bot stays available.** The bot remains in the conversation alongside the human; can be called on for specific information retrieval while the human leads. + +Useful for complex conversations; rare in simple chatbot deployments. + +**Pattern A is the default.** Explicit transitions reduce confusion. + +--- + +## Escalation back to bot + +Sometimes the conversation can return to the bot after a human handoff. + +**When this works.** The human resolves the immediate issue; the user has a follow-up question that is bot-handlable; the bot can pick back up. + +**When this fails.** The user expected human attention; returning to the bot feels like demotion. + +**The discipline.** Bot-after-human transitions need user consent. "Is there anything else? I can connect you with our chatbot for quick questions, or keep you with me." Let the user choose. + +--- + +## Common escalation failures + +**No escalation logic.** Bot tries to handle everything; produces wrong answers; users escalate to support after the fact (worse than escalating upfront). + +**Escalation without context handoff.** Human starts from scratch; user repeats everything. + +**Escalation to unavailable humans.** Bot creates expectation that is not met; user waits indefinitely or abandons. + +**Wrong-team routing.** Escalation goes to a team that cannot help; rerouting adds friction. + +**Sensitive topics not escalated.** Bot tries to handle account security, cancellations, complaints; makes things worse. + +**Escalation triggers too restrictive.** Bot rarely escalates; users get stuck. + +**Escalation triggers too permissive.** Bot escalates everything; the bot is not really doing its job. + +**No escalation user experience.** Transition to human is jarring; user is confused about whether they are still with the bot. + +--- + +## Methodology-level choices that stay in the public skill + +The escalation principle. Escalation triggers (6 patterns). Context handoff discipline. Escalation user experience. Escalation and human availability. Escalation routing. Escalation measurement. Bot-to-human transition design (3 patterns). Escalation back to bot. Common failures. + +## Implementation choices that stay internal + +Specific escalation routing for specific teams. Specific handoff formats and integration with CRM or support tools. Specific brand-voice transition copy. The team's staffing and SLA decisions. These vary by team. diff --git a/skills/chatbot-flow-design/references/fallback-pattern-design.md b/skills/chatbot-flow-design/references/fallback-pattern-design.md new file mode 100644 index 0000000..32163d1 --- /dev/null +++ b/skills/chatbot-flow-design/references/fallback-pattern-design.md @@ -0,0 +1,257 @@ +# Fallback pattern design + +What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. + +Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." Done well, fallback earns trust through honesty; done poorly, fallback frustrates users into abandonment. + +--- + +## The honesty principle + +A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers given confidently. + +**The win.** A user asks about a topic outside the bot's scope. The bot says "I cannot help with that, but [here is the right resource or human contact]." The user gets routed to value; the brand earns trust. + +**The fail (faked confidence).** The bot generates an answer from training data because it has no scope discipline. The answer is wrong; the user finds out later; the brand earns "lying bot" reputation. + +**The fail (rigid refusal).** The bot says "I cannot help with that" and offers no alternative. The user has nowhere to go. + +The discipline. Honest about limits; helpful about alternatives. + +--- + +## Multi-layered fallback + +Multiple fallback patterns, sequenced. + +**Layer 1: Clarifying question.** "Can you tell me more about what you are looking for?" + +When to use: when the user's intent is unclear and clarification might resolve. + +When it fails: when the user has already been clear; clarification feels patronizing. + +The discipline: ask clarification once, not repeatedly. + +**Layer 2: Suggested intents.** "I can help with X, Y, or Z. Were you asking about one of those?" + +When to use: when clarification did not work, or when the user asked something the bot can almost handle. + +When it fails: when the suggestions do not match what the user wanted. + +The discipline: suggest the bot's actual capabilities, not generic options. + +**Layer 3: Resource handoff.** "I cannot answer that, but here is our [documentation page] that covers it." + +When to use: when the bot cannot help but a self-serve resource exists. + +When it fails: when the resource is not actually relevant. + +The discipline: route to genuinely relevant resources; do not deflect to generic help. + +**Layer 4: Human escalation.** "Let me connect you with a human who can help." + +When to use: when self-serve will not work or the user has expressed frustration. + +When it fails: when no human is available; the escalation creates an expectation that does not get met. + +The discipline: escalate to humans only when humans are available; otherwise communicate the wait. + +--- + +## Layer sequencing + +The order matters. + +**Standard sequence.** + +1. Recognize intent. If recognized, handle. +2. If not recognized, try clarification (Layer 1). +3. If clarification fails, suggest intents (Layer 2). +4. If suggestions fail, offer resources (Layer 3). +5. If resources do not match, escalate (Layer 4). + +**Sequence variations.** + +- High-stakes topics may skip to Layer 4 immediately. +- User-initiated escalation ("talk to a human") goes to Layer 4 immediately. +- Frustrated sentiment may trigger Layer 4 sooner. + +--- + +## Anti-pattern: fallback loop + +Multiple clarification attempts that go nowhere. + +**The pattern.** Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again; loop. + +**The signal.** Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +**The cost.** The user feels stuck. The brand earns "frustrating bot" reputation. + +**The cure.** Limit clarification to one round. After that, escalate or offer alternatives. The bot's job is to resolve or hand off, not to keep asking the same question. + +--- + +## Anti-pattern: rigid refusal + +Bot says "I cannot help" and offers no path forward. + +**The pattern.** User asks something out of scope; bot says "I cannot help with that"; conversation ends. + +**The signal.** Users complain that the bot is unhelpful; abandonment. + +**The cost.** The bot fails the user without offering recovery. + +**The cure.** Always offer an alternative. Resource handoff or human escalation. The bot's "I cannot help" should be followed immediately by "but here is what might." + +--- + +## Fallback copy discipline + +What the fallback messages say. + +**Helpful fallback copy.** + +- "I am not sure I caught that. Are you asking about [option 1] or [option 2]?" +- "I can answer questions about pricing, integrations, or features. Was your question about one of those?" +- "I cannot answer that specifically. Our team can help; would you like me to connect you?" + +**Unhelpful fallback copy.** + +- "I do not understand." +- "Please rephrase." +- "Sorry, I cannot help with that." + +**The voice discipline.** Fallback copy should sound like the brand. Apologetic but not groveling; honest but not curt; helpful but not desperate. + +--- + +## Fallback for sensitive topics + +Some topics warrant immediate escalation regardless of bot capability. + +**Sensitive triggers.** + +- Account security ("my account was hacked," "I think I was charged wrong"). +- Cancellation ("I want to cancel my subscription"). +- Complaints ("I want to speak to a manager"). +- Crises (any indication of user distress). + +**The pattern.** The bot recognizes the sensitive topic and escalates immediately rather than attempting to handle. + +**Why this matters.** Sensitive topics need human empathy. A bot trying to handle them often makes things worse. Immediate escalation protects the user and the brand. + +--- + +## Fallback during human unavailability + +What happens when the user wants a human but no human is available. + +**The honest options.** + +- "Our team is available [hours]. Can I take a message they can respond to when they are back?" +- "We are not available right now. You can [submit a ticket / book a call / email us]." +- "I can help with [list of topics]; for [out-of-scope topic], please reach out to [channel] directly." + +**The dishonest option.** + +- Pretending a human is available when they are not. The user waits, gets frustrated, abandons. + +The discipline. Communicate availability honestly. Set the expectation upfront if humans cannot respond immediately. + +--- + +## Fallback measurement + +Track fallback rate as a key metric. + +**The metric.** What percentage of conversations hit fallback at any point? + +**Diagnostic uses.** + +- High fallback rate (above 25-30 percent): intents are missing or recognition is poor. +- Specific fallback layers triggered disproportionately: that layer needs design review. +- Fallback escalation rate (what percentage of fallbacks lead to human escalation): high rates may signal the bot is doing less than it should; low rates may signal users abandoning rather than escalating. + +**The fallback-as-signal principle.** Fallback is not failure; it is the bot honestly recognizing limits. The signal is in the fallback patterns and what they reveal about intent gaps. + +--- + +## Fallback maintenance + +Fallback decays. + +**What decays.** + +- Suggested intents that no longer reflect the bot's actual capabilities. +- Resource links that have moved or broken. +- Escalation routing that no longer matches the team structure. + +**Maintenance cadence.** Quarterly review of fallback messages, suggested intents, resource links, and escalation routing. + +**The drift indicator.** User feedback about unhelpful fallback responses; broken links in the fallback flow; escalations going to wrong teams. + +--- + +## Fallback and brand voice + +Fallback responses are an opportunity for brand voice. + +**The principle.** Fallback is when the bot is most likely to lose the user. Brand voice in fallback can recover the moment. + +**Voice in fallback.** + +- Acknowledge the limitation honestly. +- Maintain warmth (do not become cold or robotic when failing to help). +- Offer the path forward with the same voice as the rest of the conversation. + +**The voice failure.** Fallback messages that sound generic; bot loses voice exactly when voice matters most. + +--- + +## Fallback testing + +Test the fallback flow as carefully as the success flow. + +**Test cases.** + +- User asks something clearly out of scope. +- User asks something on the edge of scope. +- User asks something within scope but phrased unusually. +- User explicitly asks for a human. +- User shows frustration in their messages. +- User asks during off-hours. + +**The testing discipline.** Each fallback layer should be tested with realistic triggers. + +--- + +## Common fallback failures + +**No fallback patterns.** Bot has no rehearsed responses for unknown intents; generates whatever the LLM produces. + +**Single-layer fallback.** Only "I do not understand" without alternatives. + +**Fallback loops.** Bot keeps asking clarification; user gets stuck. + +**Rigid refusal.** Bot says "I cannot help" without offering paths. + +**Generic fallback copy.** Fallback messages do not match brand voice. + +**Stale resource links.** Resource handoff points to broken URLs. + +**Wrong escalation routing.** Bot escalates to teams that are not appropriate. + +**Hidden human availability.** Bot does not communicate when humans are or are not available. + +**Sensitive topics not escalated.** Bot tries to handle topics that need human empathy. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Multi-layered fallback (4 layers with when to use). Layer sequencing. Anti-patterns (fallback loop, rigid refusal). Fallback copy discipline. Fallback for sensitive topics. Fallback during human unavailability. Fallback measurement. Fallback maintenance. Fallback and brand voice. Fallback testing. Common failures. + +## Implementation choices that stay internal + +Specific fallback messages for specific bots. Specific suggested intents and resource links. Specific escalation routing logic. The team's brand-voice fallback templates. These vary by team. diff --git a/skills/chatbot-flow-design/references/intent-architecture-patterns.md b/skills/chatbot-flow-design/references/intent-architecture-patterns.md new file mode 100644 index 0000000..2733529 --- /dev/null +++ b/skills/chatbot-flow-design/references/intent-architecture-patterns.md @@ -0,0 +1,238 @@ +# Intent architecture patterns + +Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. + +The intent architecture is the bot's scope definition. Bad architecture produces bots that try to handle everything (and hallucinate) or bots that handle so little they fail audience expectations. Good architecture defines explicit scope and routes the rest to fallback. + +--- + +## The named-intent principle + +The bot has a defined set of intents it can handle. Each intent has a name, a scope, and a conversation pattern. + +**The win.** A user asks "what does the Pro plan include?" The bot recognizes this as the "pricing question" intent. The conversation pattern for that intent retrieves from the pricing knowledge base, generates a response, and offers follow-up. + +**The fail (no named intents).** The bot tries to handle every question with the same generic flow. Some questions get good answers; some get hallucinated answers; the bot cannot reason about its own scope. + +The discipline. Define the intents explicitly. The bot's behavior at each intent is intentional; behavior outside the intents is fallback. + +--- + +## Common intent patterns + +Patterns that recur across marketing-site and support chatbots. + +**Pricing question.** "How much does the Pro plan cost?" "What is included in the Enterprise tier?" "Do you offer discounts for nonprofits?" + +Conversation pattern: retrieve from pricing knowledge base, present the relevant tier or comparison, offer follow-up (talk to sales, see comparison, view full pricing page). + +**Feature comparison.** "What is the difference between A and B?" "Does feature X include Y?" + +Conversation pattern: retrieve from feature documentation, present comparison or specific feature details, offer follow-up. + +**Integration question.** "Do you integrate with Salesforce?" "How does the API work?" + +Conversation pattern: retrieve from integration catalog or API docs, present specific integration or API details, offer follow-up. + +**Support escalation.** "I need help with my account." "Something is broken." + +Conversation pattern: capture the issue context, escalate to human support with the captured context. + +**Demo request.** "Can I see a demo?" "I want to talk to sales." + +Conversation pattern: qualify the request (capture company size, use case, timeline), route to sales with the qualified context. + +**Account access.** "I forgot my password." "How do I access my account?" + +Conversation pattern: route to account-recovery flow or self-serve help. + +**General question.** "Tell me more about [topic]." "What can you help with?" + +Conversation pattern: present overview of bot capabilities; ask what specifically the user wants. + +--- + +## Intent hierarchy + +Top-level categories with sub-intents. + +**The pattern.** "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question," "annual vs monthly." + +**Strengths.** + +- Hierarchy mirrors how audiences think. +- Each sub-intent can have specific knowledge-base grounding and conversation pattern. +- Easier to maintain than flat intent set. + +**Weaknesses.** + +- More complex to build. +- Risk of over-decomposition (sub-intents that nobody triggers). + +**When to use.** When the bot's scope is broad enough that a flat intent set becomes unwieldy. Most production chatbots benefit from hierarchy. + +--- + +## Intent boundaries + +Each intent has clear scope. Out-of-scope topics route to fallback. + +**The principle.** The intent definition specifies what the intent covers and what it does not. + +**Example: "Pricing question" intent.** + +In scope: tier prices, plan inclusions, discount inquiries, billing-cycle questions. + +Out of scope: sales-specific negotiations (escalate to sales), custom pricing requests (escalate to sales), historical pricing (out-of-scope, fallback). + +**The boundary discipline.** Without clear boundaries, the bot tries to handle topics it should not. Boundaries are part of the intent definition. + +--- + +## Intent coverage + +The bot's intents should cover 70-90 percent of expected conversations. + +**The principle.** Trying to cover 100 percent often produces bloated intent sets the bot cannot handle reliably. Aiming for 70-90 percent leaves room for honest fallback on the remaining edge cases. + +**Coverage measurement.** + +- After launch, sample conversations and classify them by intent. +- The percentage classified into named intents is coverage. +- The percentage falling to fallback is the gap. + +**Coverage targets by use case.** + +- Marketing-site Q&A: 80-90 percent coverage achievable. +- Support: 60-80 percent coverage typical; support questions are more varied. +- Sales qualification: 70-85 percent coverage; depending on audience. + +**The over-coverage trap.** Pursuing 100 percent coverage often means adding intents that fire rarely. The maintenance overhead is significant; the value is low. Honest fallback for rare cases is often better than rarely-triggered intents. + +--- + +## Intent design discipline + +Designing each intent. + +**Step 1: Name the intent.** Specific name that reflects the conversation pattern. + +**Step 2: Scope the intent.** What topics in, what topics out. + +**Step 3: Identify the knowledge base.** What knowledge sources the intent grounds in. + +**Step 4: Design the conversation pattern.** Opening response, possible follow-ups, success state, escalation conditions. + +**Step 5: Define the success criterion.** What does success look like for this intent? User got the answer? User clicked through to a relevant page? User completed a follow-up action? + +**Step 6: Define escalation triggers.** When does this intent escalate to a human? + +The discipline. Each intent is designed deliberately. Generic conversation patterns produce generic results. + +--- + +## Intent recognition + +How the bot determines which intent the user is in. + +**LLM-based intent recognition.** The LLM classifies the user's message into one of the named intents. Common in modern chatbots. + +**Rule-based intent recognition.** Keywords or patterns trigger intent assignment. Older approach; brittle but predictable. + +**Hybrid.** LLM as primary; rules for high-confidence overrides. Common middle ground. + +**The recognition challenge.** Users phrase the same intent in many ways. "How much?" "What does it cost?" "Is there a free tier?" all map to "pricing question." The intent recognition has to handle the variety. + +**Recognition failure modes.** + +- Misclassification (intent A treated as intent B). +- Over-classification (too many intents recognized; conversation gets confusing). +- Under-classification (intents go unrecognized; conversations fall to fallback). + +The discipline. Test intent recognition with realistic user messages. Tune until the classification matches user intent reliably. + +--- + +## Intent maintenance + +Intents drift. Audiences shift; products evolve; conversation patterns change. + +**Maintenance signals.** + +- Specific intents see declining resolution rates. +- New conversation patterns emerge that no intent covers. +- Sub-intents become more or less common over time. + +**Maintenance cadence.** Quarterly review of intent performance. Add new intents when new patterns emerge consistently; retire intents that fire rarely. + +**The intent-maintenance audit.** + +- For each intent: trigger rate, resolution rate, escalation rate. +- Identify intents that are over-triggering (capture too much) or under-triggering (rarely fire). +- Identify gaps (conversations that should have an intent but do not). + +--- + +## Intent and brand voice + +Each intent's conversation pattern should sound like the brand. + +**The principle.** The bot's voice in each intent matches the brand voice. Consistent across intents; consistent with the brand's other surfaces. + +**Brand-voice failures.** + +- Different intents speaking in different voices. +- Bot voice that does not match the brand's other surfaces. +- Generic LLM voice (no brand personality). + +**The cure.** Voice guidance specific to the bot. Brand voice document that includes bot-specific examples. Test conversations to verify voice consistency. + +--- + +## Intent-architecture worked example + +A B2B SaaS chatbot for a project management tool. + +**Top-level intents.** + +1. Pricing question (sub-intents: tier comparison, discount inquiry, billing question, annual vs monthly) +2. Feature inquiry (sub-intents: specific feature, comparison to competitor, roadmap question) +3. Integration question (sub-intents: specific integration, API question, custom integration) +4. Demo request (sub-intents: standard demo, enterprise demo, technical deep-dive) +5. Support escalation (sub-intents: bug report, account issue, billing problem, general help) +6. Account access (sub-intents: password reset, account login, organization-level access) +7. General overview (sub-intent: introductory tour) + +**Coverage estimate.** 80-85 percent of expected conversations. + +**Fallback for the remaining 15-20 percent.** Multi-layered fallback (clarification, suggested intents, resource handoff, human escalation). + +The architecture is explicit. Each intent has scope, knowledge-base grounding, conversation pattern, and escalation triggers. + +--- + +## Common intent failures + +**Too few intents.** Bot tries to handle everything with generic flow; hallucinates or stays generic. + +**Too many intents.** Intents that rarely fire; maintenance overhead with no value. + +**Overlapping intents.** Two intents claiming the same conversations; recognition becomes ambiguous. + +**Unclear intent boundaries.** Bot handles topics out of scope; quality drops. + +**Intent recognition unreliable.** Misclassification rate high; users get wrong responses. + +**No intent maintenance.** Intent set frozen at launch; audiences evolve away from it. + +**Brand voice inconsistent.** Each intent speaks differently; bot feels disjointed. + +--- + +## Methodology-level choices that stay in the public skill + +The named-intent principle. Common intent patterns. Intent hierarchy. Intent boundaries. Intent coverage. Intent design discipline. Intent recognition approaches. Intent maintenance. Intent and brand voice. Worked example. Common failures. + +## Implementation choices that stay internal + +Specific intent sets for specific bots. Specific conversation patterns and copy. Specific recognition implementations. Specific knowledge-base mappings per intent. The team's audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md b/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md new file mode 100644 index 0000000..4ba9fb1 --- /dev/null +++ b/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md @@ -0,0 +1,263 @@ +# Knowledge-base grounding patterns + +Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. The bot's responses must come from real knowledge, not made-up confidence. + +Without grounding, the bot hallucinates. With grounding, the bot retrieves and presents. The difference is the gap between hallucinating-bot and structured-guided-conversation. + +--- + +## The grounding principle + +The bot's response generation should reference a structured knowledge base. The bot does not invent answers; it retrieves and presents. + +**The win.** A user asks "what is included in the Pro plan?" The bot retrieves the current pricing page, extracts the Pro plan inclusions, and presents them. The answer matches the source-of-truth. + +**The fail (hallucinating).** A user asks the same question. The bot has no grounding; the LLM generates a response from training data or pattern-matching. The response sounds confident but may be wrong (outdated, fabricated, partially correct). + +The discipline. Every response that could be wrong if invented must be grounded. + +--- + +## Pattern A: Retrieval-augmented generation (RAG) + +The bot searches a knowledge base for relevant content before generating a response. + +**How it works.** + +- The user's message is converted to a query. +- The query searches the knowledge base (often via vector embedding similarity). +- Relevant content chunks are retrieved. +- The LLM generates a response grounded in the retrieved content. + +**Strengths.** + +- Responses reflect current knowledge base content. +- Bot answers questions about specific topics it has been trained on. +- Easier to update than retraining a model; updating the knowledge base updates the bot. + +**Weaknesses.** + +- Retrieval quality depends on knowledge-base structure and embedding quality. +- Bot may still hallucinate if retrieval returns nothing or if generation strays from retrieved content. +- Latency increases (retrieval + generation). + +**When to use.** Default pattern for grounded chatbots. Most production bots use some form of RAG. + +--- + +## Pattern B: Source-of-truth design + +Defining the knowledge base as the canonical source. + +**The principle.** The knowledge base is the canonical source for the bot's responses. When the source-of-truth changes, the bot's answers change. + +**Source-of-truth examples.** + +- Pricing page = source for pricing answers. +- Documentation = source for feature and integration answers. +- Support knowledge base = source for support answers. +- Security and compliance docs = source for security answers. + +**Source-of-truth discipline.** + +- Each topic has a single source-of-truth. +- The bot retrieves from that source. +- When the source updates, the bot's answers update automatically (depending on the RAG pipeline). + +**The fragmented-source failure.** Multiple sources for the same topic produce inconsistent answers. The bot might cite one source; the user might rely on another. Confusion. + +The cure. Single source-of-truth per topic. If multiple documents cover the same topic, designate one as canonical and reference the others. + +--- + +## Pattern C: Citation discipline + +The bot can cite the source of its answer. + +**The principle.** Audiences benefit from knowing where the answer came from. Citation builds trust and lets the user verify. + +**Citation patterns.** + +- **Inline citation.** "Based on our pricing page, the Pro plan is $X per user per month." +- **Source link.** "You can see the full plan comparison [here]." +- **Source attribution at end.** "Source: [document name or link]" + +**Why citation matters.** + +- Trust-building. Users can verify the answer. +- Hallucination protection. If the bot cannot cite, the answer may be fabricated. +- User self-service. Users with deeper questions can follow the link. + +**Citation failures.** + +- Bot generates an answer without citation; the user cannot verify. +- Bot cites a source that does not actually contain the answer (citation hallucination). +- Bot cites a moved or deleted source; the link breaks. + +The discipline. Citations must point to real sources that contain the cited content. + +--- + +## Pattern D: Boundary disclosure + +The bot tells the user when it is operating outside its grounding. + +**The principle.** When the bot's response is not grounded (the question is outside the knowledge base), the bot says so explicitly. + +**Disclosure patterns.** + +- "I do not have information on that specific topic; would you like me to connect you with our team?" +- "Our pricing details are on the [pricing page]; the specific scenario you are asking about may need a custom quote from sales." +- "I can answer questions about our integrations; for product roadmap, you may want to contact our team." + +**The disclosure-as-honesty principle.** A bot that admits limitations earns more trust than a bot that fakes confidence on out-of-scope questions. + +--- + +## Knowledge-base structure + +How the knowledge base is organized affects retrieval quality. + +**Chunking.** Knowledge base content is broken into chunks for retrieval. Chunk size affects retrieval precision and context. + +- **Too small chunks.** Retrieval returns isolated facts without context. The bot may miss surrounding nuance. +- **Too large chunks.** Retrieval returns too much; relevant content is buried; generation may stray. +- **Right chunks.** Topically coherent units (a pricing tier description, a feature explanation, a support article section). + +**Metadata.** Each chunk has metadata (source document, section, last-updated date, topic tags). Metadata supports filtering and citation. + +**Embeddings.** Chunks are embedded for similarity search. Embedding quality affects retrieval relevance. + +**Index updates.** When the source-of-truth changes, the index must update. Stale index produces stale answers. + +--- + +## Knowledge-base scope + +What goes into the knowledge base. + +**In scope.** + +- Pricing and plan details. +- Feature and capability documentation. +- Integration catalog and API documentation. +- Support FAQs. +- Security and compliance information. +- Company overview, team, contact information. + +**Out of scope.** + +- Confidential information (internal-only docs, sensitive data). +- Information that changes too rapidly to keep current (real-time inventory, live availability). +- Information that requires personalization the bot cannot do (account-specific data). + +**Boundary discipline.** Sensitive or personalization-required topics should not be in the bot's knowledge base. The bot should escalate or route to authenticated channels for those. + +--- + +## Knowledge-base maintenance + +The knowledge base decays. Maintenance is part of the bot's lifecycle. + +**What decays.** + +- Pricing changes that did not propagate to the knowledge base. +- Features added or removed without docs being updated. +- Integration partners changing names or capabilities. +- Support articles that became outdated. + +**Maintenance cadence.** + +- Monthly review of high-traffic content (pricing, features). +- Quarterly review of broader knowledge base. +- Triggered review when the product or pricing changes (the change includes a knowledge-base update task). + +**Maintenance ownership.** Someone owns the knowledge base. Without owner, it decays. + +**Decay indicators.** + +- Bot answers that contradict current product reality. +- User complaints about wrong information from the bot. +- Sales or support hearing audiences cite outdated bot information. + +--- + +## Hallucination detection + +Even with grounding, bots can hallucinate. Detection is part of the discipline. + +**Detection methods.** + +- **Sample auditing.** Periodically sample bot conversations and verify the responses against source-of-truth. +- **User feedback signals.** "This response was not helpful" feedback often correlates with hallucination. +- **Citation verification.** Programmatic checks that cited sources actually contain the cited content. +- **Anomaly detection.** Conversations where the bot's response diverges significantly from retrieved content. + +**Remediation.** + +- Hallucinated content reported promptly. +- Knowledge base or grounding logic updated to prevent recurrence. +- Specific intent or topic may need re-design. + +**The honesty discipline.** Acknowledge hallucination when it happens. The team that hides hallucination from itself ships worse bots over time. + +--- + +## Knowledge-base and brand voice + +The knowledge base content informs the bot's voice. + +**The principle.** Source documents written in brand voice produce bot responses in brand voice. Source documents written generically produce generic bot responses. + +**The discipline.** When preparing source documents for the knowledge base, write in the brand voice. The bot will reflect what it retrieves. + +**Brand-voice editing.** Some teams edit retrieved content for the bot's response. This adds brand voice but risks drifting from the source-of-truth. Trade-off worth considering. + +--- + +## Multi-source grounding + +When the bot needs to combine information from multiple sources. + +**The pattern.** The bot retrieves from multiple sources and synthesizes a response. + +**Strengths.** + +- Bot can answer questions that span topics. +- Richer responses possible. + +**Weaknesses.** + +- Synthesis can introduce hallucination. +- Citation becomes more complex (multiple sources). +- Quality control harder. + +**The discipline.** Use multi-source grounding sparingly. When used, ensure the synthesis is grounded in retrieved content, not generated from training data. + +--- + +## Common grounding failures + +**No grounding.** Bot generates from training data; hallucinations are routine. + +**Stale grounding.** Knowledge base not updated; bot answers reflect outdated reality. + +**Fragmented grounding.** Multiple sources for same topic; bot answers are inconsistent. + +**Citation hallucination.** Bot cites sources that do not contain the cited content. + +**Generic content in knowledge base.** Source documents are not in brand voice; bot responses are generic. + +**Out-of-scope grounding.** Bot retrieves from sources that should not be in scope (confidential, personalized). + +**Boundary blur.** Bot answers questions outside its grounding without disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The grounding principle. Patterns A through D (RAG, source-of-truth, citation, boundary disclosure). Knowledge-base structure. Knowledge-base scope. Knowledge-base maintenance. Hallucination detection. Knowledge-base and brand voice. Multi-source grounding. Common grounding failures. + +## Implementation choices that stay internal + +Specific knowledge bases for specific bots. Specific RAG pipelines and embedding choices. Specific chunking and indexing approaches. Specific tooling for hallucination detection. The team's maintenance calendars. These vary by team. diff --git a/skills/code-review-web/SKILL.md b/skills/code-review-web/SKILL.md new file mode 100644 index 0000000..0edae47 --- /dev/null +++ b/skills/code-review-web/SKILL.md @@ -0,0 +1,213 @@ +--- +name: code-review-web +description: "Review web application code for bugs, security issues, performance problems, and stack-specific anti-patterns. Use this skill whenever the user wants to review code, debug a production issue, investigate a build failure, audit security, or check a PR before merging. Triggers on code review, review my code, debug, build error, broken, not working, why is X failing, check this code, security check, PR review, audit code, refactor. Also triggers when investigating 4xx or 5xx errors, deploy failures, environment variable issues, and CMS integration problems." +category: development +catalog_summary: "PR review, build error diagnosis, security and quality checks" +display_order: 1 +--- + +# Code Review for Web + +Review and debug web application code with a focus on the patterns that actually break production. Stack-agnostic principles in SKILL.md. Stack-specific patterns in references. + +--- + +## When to use + +- Reviewing a pull request before merging +- Debugging a production issue +- Investigating a build failure +- Auditing security or performance of existing code +- Investigating environment variable or configuration issues +- Triaging a "the site is broken" report + +## When NOT to use + +- Writing a new feature spec (use `pm-spec-writing`) +- Pre-launch QA against the running site (use `qa-testing`) +- Performance deep-dive on Core Web Vitals (use `performance-optimization`) +- Deep accessibility compliance review (use `accessibility-audit`) + +--- + +## Required inputs + +- The code, PR, error message, or symptom under review +- Access to logs (build logs, function logs, server logs) if debugging +- The stack (framework, hosting, database) - even at high level + +If just a symptom is provided ("the site is broken"), the workflow's first step is gathering enough context to investigate. + +--- + +## The framework: 5 review dimensions + +Every code review covers five dimensions. Pick the depth based on the situation. + +### 1. Correctness + +Does the code do what it claims to do? + +- Logic matches the intent stated in the spec or PR description +- Edge cases handled (empty states, error states, network failures) +- Off-by-one errors, null/undefined handling, async race conditions +- Tests exist for the change, or there's a reason they don't +- The change does not break existing functionality (regression risk) + +### 2. Security + +Does the code expose anything sensitive or open an attack surface? + +- **Secrets handling.** No secrets, API keys, or service-role credentials in client-side code or version control +- **Auth checks.** Every mutation endpoint validates the caller before acting +- **Input validation.** User input sanitized before use in queries, file paths, or HTML +- **External requests.** Outbound URLs validated; no SSRF on user-controlled inputs +- **CSRF protection.** State-changing requests require a token or same-origin policy +- **Rate limiting.** Public-facing mutation endpoints have rate limits +- **HTTPS-only.** No HTTP in production code paths +- **Cookies.** Session cookies have `Secure`, `HttpOnly`, `SameSite` attributes set +- **Environment variables.** Server-only secrets are not prefixed with anything that exposes them to the client bundle + +### 3. Performance + +Will this code scale and stay fast? + +- **Database queries.** No N+1 patterns. Joins or batch fetches preferred over loops with queries. +- **Pagination.** Large result sets paginated, never loaded entirely. +- **Caching.** Appropriate cache strategy for the data freshness needs. +- **Bundle size.** Client-side dependencies justified. Tree-shaking working. +- **Image handling.** Modern formats, lazy loading, explicit dimensions. +- **Background work.** Slow operations moved off the request path. +- **Cold start sensitivity.** Cold paths optimized if frequently triggered. + +### 4. Reliability + +What happens when this fails? + +- **Error handling.** Caught and handled, not swallowed. Errors logged with context. +- **Retries.** Network calls have retry logic for transient failures. +- **Timeouts.** External calls have explicit timeouts (no infinite waits). +- **Graceful degradation.** Failure of non-critical paths does not crash the page. +- **Idempotency.** Mutations that might be retried are safe to retry. +- **Logging.** Enough context in logs to diagnose without reproducing. + +### 5. Maintainability + +Will the next person (or future you) understand this in six months? + +- **Naming.** Functions and variables named for what they do, not how. +- **Comments.** Explain why, not what. The code says what. +- **Complexity.** Functions do one thing. If a function takes 200 lines, it's doing too much. +- **Duplication.** Same logic in multiple places gets extracted. +- **Dependencies.** New dependencies justified. Each one is a maintenance burden. +- **Magic values.** No literal `60000` in code. Use named constants. + +--- + +## Common bug patterns (stack-agnostic) + +Patterns that recur across stacks and are worth checking on every review. + +### Build and deploy + +- **Build-time data fetches that timeout.** Routes that query a database during static generation can fail at scale. Mark them as runtime-rendered if the data must be fresh. +- **Environment variables not propagating.** A var that works locally but breaks in production usually means it was not added to the production environment. +- **Mismatched env between preview and production.** Deploys that work in preview but break on the production domain often have stack-specific URLs hardcoded. + +### URL and domain issues + +- **Canonical pointing at staging or preview URL.** Caused by client-exposed environment variables that pick up the wrong domain. Canonical domain should come from a server-only environment variable. +- **API URL pointing at the main domain that loops back.** After a DNS cutover, the main domain may now serve a different application. APIs should live on dedicated subdomains. +- **HTTPS upgrade issues.** Mixed content (HTTP resources loaded into HTTPS pages) breaks browsers' security model. + +### Cache invalidation + +- **Stale content after deploy.** Either the cache was not invalidated, or the invalidation requires a manual trigger that did not run. +- **CDN serving old asset under same filename.** Always use a new filename or cache-bust query string when replacing assets. +- **Cache headers too aggressive.** Long max-age on resources that change frequently leads to users seeing stale content for hours or days. + +### Database and data + +- **N+1 queries.** Loop with a query inside the loop. Replace with batch fetch or join. +- **Missing limits on table scans.** Forgetting `LIMIT` on queries that hit large tables. +- **Connection pool exhaustion.** Too many concurrent connections, often from build-time fetches in parallel routes. +- **Schema migration without backfill.** Adding a NOT NULL column without populating it for existing rows. + +### Image handling + +- **Image not loading after upload.** CDN cached the previous filename. Use new filenames for replacements. +- **Layout shift from images.** Missing width/height attributes. Always specify both. +- **Slow LCP from large images.** Hero images not optimized for size or format. + +### External integrations + +- **Bot mitigation blocking server-to-server calls.** CDN or firewall is challenging legitimate automated traffic. Whitelist server IPs or disable challenges for API endpoints. +- **API rate limit triggered in production.** Worked locally where traffic was tiny. Add backoff and rate limiting awareness. + +### Security + +- **Unprotected revalidation or admin endpoints.** Always require a secret token. +- **PII in URLs.** Visible in server logs, browser history, referrer headers. +- **Secrets exposed in client bundle.** Anything that gets sent to the browser is public. + +--- + +## Workflow + +1. **Gather context.** What stack? What's broken or under review? Logs available? +2. **Pick the depth.** Quick scan for a small PR. Full review for a major change. Deep dive for a production incident. +3. **Run through the 5 dimensions.** Note issues by severity (blocker, important, minor). +4. **Check stack-specific patterns.** Reference the appropriate stack guide. +5. **For incidents:** identify the smallest hypothesis-driven fix. Reproduce locally if possible. +6. **Write the review.** Use the template in [`references/review-template.md`](references/review-template.md) for formal reviews. + +--- + +## Failure patterns + +- **"Looks good to me" on a 500-line PR.** If the review takes 5 minutes on a large PR, the review didn't happen. +- **Reviewing without running the code.** Some bugs only surface at runtime. Pull the branch and run it. +- **Over-indexing on style.** Bikeshedding on formatting while missing logic bugs. +- **Skipping security review on "internal" features.** Internal becomes external faster than expected. +- **Treating warnings as decoration.** Build warnings often become production errors after a dependency update. +- **Debugging without reading the full error message.** First line of the stack trace is often not the actual cause. Read all of it. + +--- + +## Debugging workflow + +When a production issue is reported: + +1. **Read the full error message.** Including the stack trace. +2. **Check hosting build and function logs.** The exact failing line is usually here. +3. **Identify the last working version.** `git log --oneline` and check recent commits. +4. **Reproduce locally.** Confirms it's a code issue and not an environment issue. +5. **Check environment variables.** Especially after deploys or DNS changes. +6. **Check cache state.** Force a cache invalidation before concluding it's a code bug. +7. **Make the minimal fix.** Big refactors during incidents create more incidents. +8. **Verify in production.** Check the actual fix worked, not just that the deploy succeeded. +9. **Document.** What was the root cause? What would have prevented it? File the learnings. + +--- + +## Output format + +For PR reviews: comments inline on the PR, plus a summary if needed. + +For formal code reviews: a markdown document at `code-review-[date].md` with: +1. Scope (what was reviewed) +2. Summary (overall assessment) +3. Critical issues (blockers) +4. Important issues +5. Minor issues +6. Suggestions for follow-up + +For incidents: a postmortem document. See `after-action-report` for that format. + +--- + +## Reference files + +- [`references/review-template.md`](references/review-template.md) - Markdown template for formal code reviews. +- [`references/nextjs-patterns.md`](references/nextjs-patterns.md) - Stack-specific patterns for Next.js (App Router, ISR, Server Components, common bugs). +- [`references/wordpress-headless-patterns.md`](references/wordpress-headless-patterns.md) - Stack-specific patterns for headless WordPress integrations. diff --git a/skills/code-review-web/references/nextjs-patterns.md b/skills/code-review-web/references/nextjs-patterns.md new file mode 100644 index 0000000..0989e7c --- /dev/null +++ b/skills/code-review-web/references/nextjs-patterns.md @@ -0,0 +1,360 @@ +# Next.js Patterns + +Stack-specific patterns and anti-patterns for Next.js projects. Covers App Router and Pages Router. Stack-agnostic principles live in [SKILL.md](../SKILL.md). + +--- + +## App Router specific + +### Server vs client components + +**Default to server components.** Reach for `"use client"` only when interactivity, browser APIs, or React state hooks are required. + +```typescript +// Server component (default) - runs on server, no hydration cost +// app/page.tsx +export default async function Page() { + const data = await fetchData(); + return <Article data={data} />; +} + +// Client component - hydrates in browser +// app/components/InteractiveButton.tsx +"use client"; +export default function InteractiveButton() { + const [count, setCount] = useState(0); + return <button onClick={() => setCount(c => c + 1)}>{count}</button>; +} +``` + +**Anti-pattern:** Marking parent components as `"use client"` when only a leaf component needs it. This pulls everything below into the client bundle. + +### ISR and revalidation + +Pick the right rendering strategy per route: + +```typescript +// Static (default) - rendered at build, served from CDN +export default async function Page() { ... } + +// ISR (revalidate periodically) - rendered at build, regenerated on schedule +export const revalidate = 3600; // 1 hour + +// Dynamic (rendered on every request) - never cached +export const dynamic = "force-dynamic"; + +// Common combination: dynamic with cache hint for downstream +export const dynamic = "force-dynamic"; +export const revalidate = 3600; +``` + +### Build timeout failures + +Common error: +``` +Failed to build /route after 3 attempts because it took more than 60 seconds +``` + +**Cause:** A static route that queries a database or external API at build time, and the call exceeds the build timeout. + +**Fix:** Add `dynamic = "force-dynamic"` to defer rendering to request time: + +```typescript +export const dynamic = "force-dynamic"; +export const revalidate = 3600; + +export async function GET() { + try { + const data = await dbQuery(); + return generateResponse(data); + } catch (e) { + console.error("Route error:", e); + return new Response("", { status: 200 }); // empty but valid + } +} +``` + +### TypeScript errors in scripts directory + +If you have a `scripts/` folder with one-off scripts, exclude it from the build: + +```json +// tsconfig.json +{ + "exclude": ["node_modules", "scripts"] +} +``` + +### Canonical URL configuration + +The canonical domain must come from a server-only environment variable. Never expose with `NEXT_PUBLIC_` prefix. + +```typescript +// next.config.ts +const config = { + env: { + SITE_URL: process.env.SITE_URL ?? "https://yourdomain.com", + }, +}; +export default config; +``` + +```typescript +// Where the canonical is set +const url = process.env.SITE_URL; // server-only, never exposed to browser +``` + +**Anti-pattern:** Using `NEXT_PUBLIC_SITE_URL`. Vercel preview deploys will pick up the preview URL and pollute production canonicals. + +--- + +## Pages Router specific + +### getStaticProps timeouts + +Same fundamental issue as App Router build timeouts. Solution is `getServerSideProps` for routes that need fresh data: + +```typescript +// pages/dynamic-page.tsx +export async function getServerSideProps(context) { + const data = await dbQuery(); + return { props: { data } }; +} +``` + +Or ISR: + +```typescript +export async function getStaticProps() { + const data = await dbQuery(); + return { + props: { data }, + revalidate: 3600, + }; +} +``` + +--- + +## Common patterns across both routers + +### API routes / route handlers + +**Authentication on mutations:** + +```typescript +// app/api/protected/route.ts (App Router) +export async function POST(req: Request) { + const secret = req.headers.get("authorization"); + if (secret !== `Bearer ${process.env.API_SECRET}`) { + return new Response("Unauthorized", { status: 401 }); + } + // ... handle the request +} +``` + +**Revalidation endpoint protection:** + +```typescript +// app/api/revalidate/route.ts +import { revalidatePath } from "next/cache"; + +export async function POST(req: Request) { + const url = new URL(req.url); + const secret = url.searchParams.get("secret"); + + if (secret !== process.env.REVALIDATE_SECRET) { + return Response.json({ error: "Unauthorized" }, { status: 401 }); + } + + const path = url.searchParams.get("path") ?? "/"; + revalidatePath(path); + + return Response.json({ revalidated: true, path }); +} +``` + +### Image optimization + +Use the framework's built-in image component for proper optimization: + +```typescript +import Image from "next/image"; + +<Image + src="/photo.jpg" + alt="Descriptive alt text" + width={800} + height={600} + loading="lazy" // explicit even though lazy is default for below-fold +/> +``` + +For external image domains, configure `next.config.ts`: + +```typescript +const config = { + images: { + remotePatterns: [ + { protocol: "https", hostname: "cms.yourdomain.com" }, + ], + }, +}; +``` + +### Environment variables + +Three categories. Be explicit about which is which. + +``` +Server-only secrets (never prefix with NEXT_PUBLIC_): + DATABASE_URL + API_SECRET + STRIPE_SECRET_KEY + REVALIDATE_SECRET + SITE_URL (use server-only even for canonical, despite being a "public" value) + +Client-safe variables (NEXT_PUBLIC_ prefix exposes to browser): + NEXT_PUBLIC_GA_ID + NEXT_PUBLIC_DEFAULT_LANGUAGE + NEXT_PUBLIC_FEATURE_FLAGS + +Build-time only: + ANALYZE_BUNDLE + NODE_ENV (set automatically) +``` + +**Red flags during review:** +- Any secret with `NEXT_PUBLIC_` prefix +- Canonical or site URL set to a preview/staging URL in production +- Service role keys exposed to the browser + +--- + +## Common bugs and fixes + +### Page renders partially after deploy + +**Symptom:** Hero loads but content below is missing or stale. + +**Cause:** Stale ISR cache from before the deploy. + +**Fix:** Force revalidation: + +```bash +curl -X POST "https://yourdomain.com/api/revalidate?path=/&secret=$REVALIDATE_SECRET" +``` + +If the issue persists, check server logs for rendering errors during regeneration. + +### CMS API redirects to main domain after DNS cutover + +**Symptom:** API calls to the CMS return 302 redirects or 403 errors. + +**Cause:** API URL points at the main domain, which now serves the Next.js app instead of the CMS. + +**Fix:** Use a dedicated CMS subdomain: + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json # correct +WP_API_URL=https://yourdomain.com/wp-json # loops back to Next.js +``` + +### Images return 502 after domain change + +**Cause:** Image optimizer fetching from a domain that no longer hosts the source images. + +**Fix:** Update `images.remotePatterns` in `next.config.ts` to match the new image origin. Rewrite media URLs in data fetches to point at the correct origin. + +### Client component re-renders excessively + +**Cause:** Inline object or function as prop. New reference on every render triggers re-render in the child. + +**Fix:** Memoize: + +```typescript +// Before (creates new object each render) +<Child config={{ foo: "bar" }} /> + +// After +const config = useMemo(() => ({ foo: "bar" }), []); +<Child config={config} /> +``` + +--- + +## Performance patterns + +### Avoid request waterfalls + +```typescript +// Bad: sequential fetches +const user = await getUser(); +const posts = await getPostsByUser(user.id); +const comments = await getCommentsForPosts(posts.map(p => p.id)); + +// Good: parallel where possible +const user = await getUser(); +const [posts, settings] = await Promise.all([ + getPostsByUser(user.id), + getSettingsForUser(user.id), +]); +``` + +### Database query patterns + +```typescript +// Bad: N+1 +for (const post of posts) { + const author = await db.user.findUnique({ where: { id: post.authorId } }); +} + +// Good: batch fetch with relation +const posts = await db.post.findMany({ + include: { author: true }, +}); + +// Always limit large scans +const data = await db.post.findMany({ + where: { ... }, + take: 100, +}); +``` + +### Streaming with Suspense + +For App Router, stream slow content to improve perceived performance: + +```typescript +// app/page.tsx +import { Suspense } from "react"; +import FastContent from "./FastContent"; +import SlowContent from "./SlowContent"; + +export default function Page() { + return ( + <> + <FastContent /> + <Suspense fallback={<Loading />}> + <SlowContent /> + </Suspense> + </> + ); +} +``` + +--- + +## Code review checklist for Next.js + +- [ ] Server components default; `"use client"` only where needed +- [ ] ISR routes have appropriate `revalidate` value +- [ ] Database-querying routes have `force-dynamic` if they can timeout at build +- [ ] Canonical/site URL uses server-only env var +- [ ] No secrets in `NEXT_PUBLIC_` variables +- [ ] API routes have auth checks on mutations +- [ ] Revalidation endpoint protected with secret +- [ ] Images use the `Image` component, with explicit width/height +- [ ] External image domains in `images.remotePatterns` +- [ ] Scripts directory excluded from tsconfig if causing type errors +- [ ] Suspense boundaries for slow content where streaming helps diff --git a/skills/code-review-web/references/review-template.md b/skills/code-review-web/references/review-template.md new file mode 100644 index 0000000..35bcea4 --- /dev/null +++ b/skills/code-review-web/references/review-template.md @@ -0,0 +1,141 @@ +# Code Review: [PR Title or Scope] + +**Reviewer:** [Name] +**Date:** [YYYY-MM-DD] +**PR or commit:** [Link or hash] +**Author:** [Name] +**Scope:** [Files reviewed, lines changed] + +--- + +## Summary + +[2 to 3 sentences. Overall assessment. Recommend merge, request changes, or block.] + +**Recommendation:** [Approve / Approve with comments / Request changes / Block] + +**Critical issues:** [N] +**Important issues:** [N] +**Minor issues:** [N] +**Suggestions:** [N] + +--- + +## Critical issues (blockers) + +[Issues that must be fixed before merge.] + +### 1. [Issue title] +- **File:** [path/to/file.ext] +- **Line:** [Line number or range] +- **Issue:** [What's wrong] +- **Why critical:** [Impact if shipped] +- **Suggested fix:** [Specific recommendation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Issues that should be addressed but might not block merge.] + +### 1. [Issue title] +- **File:** +- **Line:** +- **Issue:** +- **Suggested fix:** + +--- + +## Minor issues + +[Polish items, style consistency, naming.] + +- **[file:line]** [Description and suggestion] +- **[file:line]** [Description and suggestion] +- **[file:line]** [Description and suggestion] + +--- + +## Suggestions for follow-up + +[Things worth doing in a follow-up PR, not in this one.] + +- [Suggestion] +- [Suggestion] + +--- + +## Dimension scorecard + +| Dimension | Pass | Issues | +|---|---|---| +| Correctness | ☐ | [Notes] | +| Security | ☐ | [Notes] | +| Performance | ☐ | [Notes] | +| Reliability | ☐ | [Notes] | +| Maintainability | ☐ | [Notes] | + +--- + +## Specific checks + +### Correctness +- [ ] Logic matches PR description +- [ ] Edge cases handled (empty, null, error) +- [ ] No off-by-one or async race conditions +- [ ] Tests exist or are not needed (with reason) +- [ ] No regressions in existing functionality + +### Security +- [ ] No secrets in client-side code +- [ ] Auth checks on mutations +- [ ] Input validated before use +- [ ] No new SSRF surface +- [ ] Cookies have appropriate attributes +- [ ] Server-only env vars not exposed to client + +### Performance +- [ ] No N+1 queries +- [ ] Pagination on large result sets +- [ ] Cache strategy appropriate +- [ ] Bundle size impact reasonable +- [ ] Images handled correctly + +### Reliability +- [ ] Errors caught and handled +- [ ] Network calls have timeouts +- [ ] Graceful degradation for non-critical paths +- [ ] Mutations idempotent if retried +- [ ] Sufficient logging for diagnosis + +### Maintainability +- [ ] Naming clear +- [ ] Functions focused (one thing well) +- [ ] No unjustified duplication +- [ ] No magic values (use constants) +- [ ] Comments explain why, not what + +--- + +## Stack-specific checks (if applicable) + +[Reference the stack-specific guide for the project. Note any stack-specific patterns or anti-patterns worth flagging.] + +--- + +## Notes for the author + +[Encouraging or contextual notes. What was done well. What's a learning opportunity.] + +--- + +## Sign-off + +**Approval status:** [Approved / Approved with comments / Changes requested / Blocked] +**Date:** [YYYY-MM-DD] + +If changes were requested, link to the follow-up PR or commit when resolved: +- [Link or hash] diff --git a/skills/code-review-web/references/wordpress-headless-patterns.md b/skills/code-review-web/references/wordpress-headless-patterns.md new file mode 100644 index 0000000..cddd929 --- /dev/null +++ b/skills/code-review-web/references/wordpress-headless-patterns.md @@ -0,0 +1,265 @@ +# WordPress Headless Patterns + +Stack-specific patterns for WordPress as a headless CMS, integrated with a separate frontend (Next.js, Astro, Eleventy, custom, etc.). + +The principles in [SKILL.md](../SKILL.md) apply universally. This file covers the WordPress-specific patterns that recur in headless setups. + +--- + +## Architecture + +A headless WordPress setup typically looks like: + +``` +cms.yourdomain.com → WordPress backend (admin, REST API, media) +yourdomain.com → Frontend (renders content fetched from CMS API) +``` + +WordPress serves the data and admin. The frontend serves the user-facing site. The two are decoupled. + +This separation matters for several patterns below. + +--- + +## Always use a CMS subdomain + +**Pattern:** All API calls go to a dedicated subdomain. + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json +``` + +**Anti-pattern:** API calls to the main domain. + +``` +WP_API_URL=https://yourdomain.com/wp-json # this will break after DNS cutover +``` + +**Why:** When the main domain points to the frontend (post-DNS cutover), API calls to the main domain hit the frontend instead of WordPress. The frontend has no `/wp-json` route, so calls fail. + +The CMS subdomain remains a stable, dedicated endpoint regardless of where the main domain points. + +--- + +## Site URL configuration in WordPress + +After moving to a subdomain, WordPress needs to know its real URL. Otherwise the admin redirects to the main domain. + +In `wp-config.php`: + +```php +define("WP_HOME", "https://cms.yourdomain.com"); +define("WP_SITEURL", "https://cms.yourdomain.com"); +``` + +**Symptom if missing:** Logging into `cms.yourdomain.com/wp-admin` redirects to `yourdomain.com/wp-admin`, which hits the frontend (no admin), returning a 403 or 404. + +--- + +## Media URL handling + +WordPress generates media URLs based on the configured site URL. When fetched through the API, they will reference the CMS subdomain. The frontend needs to handle these correctly. + +### Pattern 1: Reference media at the CMS subdomain (simplest) + +The frontend renders images directly from the CMS subdomain: + +```html +<img src="https://cms.yourdomain.com/wp-content/uploads/photo.jpg" alt="..." /> +``` + +**Pros:** Simple. No URL rewriting. +**Cons:** Browser makes requests to a different origin. Need to allow that origin in image optimizer config. + +### Pattern 2: Rewrite media URLs to the frontend domain + +Strip the CMS prefix and serve media via the frontend's image optimizer: + +```typescript +// Convert CMS media URL to a pattern the frontend image optimizer accepts +function rewriteMediaUrl(url: string): string { + return url.replace("https://cms.yourdomain.com", ""); +} +``` + +Configure the frontend image optimizer to allow the CMS subdomain as a remote source. + +### Anti-pattern: Hardcoded media URLs in content + +If editors paste full URLs into the content (`<img src="https://cms.yourdomain.com/...">`), changing the CMS subdomain later breaks every reference. Use relative paths or template-rendered URLs instead. + +--- + +## Permalinks and post URLs + +WordPress posts have a `link` field in the API response that returns the WordPress-rendered URL (e.g., `https://cms.yourdomain.com/post-slug/`). This is wrong for the public-facing site. + +**Anti-pattern:** Using the `link` field directly. + +```typescript +// Wrong - shows the CMS URL +<a href={post.link}>{post.title}</a> +``` + +**Pattern:** Construct the public URL from the slug. + +```typescript +// Right - build the URL the frontend serves +<a href={`/blog/${post.slug}`}>{post.title}</a> +``` + +--- + +## Caching and revalidation + +The frontend caches API responses. When content changes in WordPress, the cache must be invalidated. + +### Pattern 1: Time-based revalidation + +Cache responses for a fixed period. Simple but content can be stale up to that period. + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { revalidate: 3600 }, // 1 hour +}); +``` + +### Pattern 2: On-demand revalidation via webhook + +WordPress fires a webhook on save. The webhook calls a frontend endpoint that invalidates the cache. + +WordPress side (mu-plugin or theme function): + +```php +add_action('save_post', function ($post_id) { + $post = get_post($post_id); + if ($post->post_status !== 'publish') return; + + wp_remote_post('https://yourdomain.com/api/revalidate', [ + 'body' => json_encode([ + 'secret' => REVALIDATE_SECRET, + 'path' => '/blog/' . $post->post_name, + ]), + 'headers' => ['Content-Type' => 'application/json'], + ]); +}); +``` + +Frontend side: an endpoint that invalidates the cache for the given path. + +### Pattern 3: Tag-based invalidation + +Tag fetches with semantic identifiers, then invalidate by tag when relevant content changes. + +```typescript +const posts = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { tags: ["posts"] }, +}); + +// Later, invalidate +revalidateTag("posts"); +``` + +--- + +## Authentication for the API + +For private content or write operations, the API requires authentication. + +### Application passwords (built into WordPress) + +WordPress supports application passwords for API authentication. Generate one in the admin under user profile. + +```typescript +const auth = btoa(`${username}:${appPassword}`); + +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + headers: { + Authorization: `Basic ${auth}`, + }, +}); +``` + +**Anti-pattern:** Hardcoding credentials in client-side code. Application passwords go in server-only environment variables. + +### JWT (via plugin) + +JWT plugins offer a more standard auth flow but add a plugin dependency. + +--- + +## Common bugs and fixes + +### "API returns 403 from server-side fetch" + +**Cause 1:** A bot mitigation service (Cloudflare's "Attack Challenge Mode" or similar) is challenging the server-to-server request. + +**Fix:** Disable bot mitigation challenges for the CMS API path, or whitelist the frontend's server IPs. + +**Cause 2:** The API requires authentication and the request is unauthenticated. + +**Fix:** Add an `Authorization` header with application password or JWT. + +### "Posts list is paginated and we're only getting 10" + +**Cause:** WordPress default per-page is 10. + +**Fix:** Use `per_page` parameter and handle pagination: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?per_page=100`); +const total = parseInt(res.headers.get('x-wp-total') ?? '0'); +const totalPages = parseInt(res.headers.get('x-wp-totalpages') ?? '0'); +``` + +For very large content sets, paginate explicitly rather than fetching all at once. + +### "Custom fields are missing from the API response" + +**Cause:** Advanced Custom Fields (ACF) or custom post meta is not exposed by default. + +**Fix:** Use the ACF to REST API plugin, or register custom fields with `register_rest_field`: + +```php +add_action('rest_api_init', function () { + register_rest_field('post', 'custom_field_name', [ + 'get_callback' => function ($post) { + return get_post_meta($post['id'], 'custom_field_name', true); + }, + ]); +}); +``` + +### "Featured image is missing from the API response" + +**Cause:** The API returns the image ID, not the full media object. + +**Fix:** Use `_embed=true` to inline media: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?_embed=true`); +// Now post._embedded["wp:featuredmedia"][0] has the full image data +``` + +### "Slug-only URLs return wrong content after rename" + +**Cause:** WordPress slug changes don't redirect the old slug. Frontend caches lock to the old slug. + +**Fix:** +1. WordPress: install a redirection plugin or maintain a redirects table +2. Frontend: handle 404s on slug routes by falling back to a search-by-title + +--- + +## Code review checklist for headless WordPress + +- [ ] All API calls use the CMS subdomain (no main domain references) +- [ ] WP_HOME and WP_SITEURL set in wp-config.php +- [ ] Media URLs handled correctly (either CMS-direct or rewritten) +- [ ] Post URLs constructed from slug, not the WordPress `link` field +- [ ] Cache invalidation strategy in place (time-based, webhook, or tag) +- [ ] Authentication credentials in server-only env vars +- [ ] API responses include needed embedded data (`_embed=true` where relevant) +- [ ] Pagination handled for large post lists +- [ ] Error handling for API failures (CMS down should not crash the frontend) +- [ ] Custom fields exposed via REST API where needed diff --git a/skills/comparison-tool-design/SKILL.md b/skills/comparison-tool-design/SKILL.md new file mode 100644 index 0000000..051888d --- /dev/null +++ b/skills/comparison-tool-design/SKILL.md @@ -0,0 +1,261 @@ +--- +name: comparison-tool-design +description: "Designing side-by-side comparison tools (plan-compare, product-compare, alternative-compare) that help users decide rather than just listing features. Axis selection, default-comparison logic, recommendation discipline. Honest about feature-list-dump (every feature in a row, no decision support), hidden-recommendation (biased comparison pretending to be neutral), and honest-comparison-with-guidance (genuine comparison plus opinionated recommendation) patterns. Triggers on comparison tool, plan compare, product compare, alternative compare, vs page, decision support tool. Also triggers when conversion through comparison stages is poor, when users are abandoning at the comparison step, or when a comparison tool is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing comparison tools that help users decide. Distinguishes feature-list-dump (every feature in a row, no decision support) from hidden-recommendation (biased comparison pretending to be neutral) from honest-comparison-with-guidance (genuine comparison plus opinionated recommendation)" +display_order: 11 +--- + +# Comparison Tool Design + +A senior product marketing director's playbook for designing side-by-side comparison tools that help users decide rather than just listing features. Plan-compare, product-compare, alternative-compare. Axis selection, default-comparison logic, recommendation discipline. The discipline of building a comparison tool that earns the user's trust. + +Most comparison tools fail in one of two ways. They dump every feature into a giant grid (4 options × 40 features = 160 cells) and ask the user to weigh everything against everything. The user leaves without choosing. Or they pretend to be neutral comparisons but are actually sales pitches with biased defaults and weighted framing; the user catches the bias and trust collapses. + +The comparison tools that work do something different. Genuine like-for-like comparison plus an explicit opinionated recommendation. "For X audience, choose Y." The recommendation is visible, defended, and not the only path; users can override. The tool helps the user decide rather than asking them to decide alone. + +The voice is the senior product marketing director who has watched comparison tools double conversion when redesigned with honest recommendations and watched them collapse when feature grids grew without decision support. Practical, opinionated about which axes matter, willing to call out when the comparison is decoration. + +When to use this skill: scoping a comparison tool for the first time, auditing a feature-grid comparison that produces no conversion lift, designing recommendation logic that is honest about the recommendation, or deciding which axes earn placement in a comparison tool. + +--- + +## What this skill covers + +This skill spans side-by-side comparison tools. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number. This skill is comparing known options. +- `quiz-and-assessment-design` is quizzes that give a category. This skill is comparing options the user already knows about. +- **`comparison-tool-design` (this skill)** is axis selection, default-comparison logic, recommendation engine, filter-and-toggle UX. +- `landing-page-copy` is pricing-page copy; one specific application of comparison tools is the pricing page. +- `content-strategy` is upstream; what topics warrant comparison content. + +The audience: product marketers, growth marketers, content marketers running vs-pages and decision-support tooling, agencies running comparison work for clients. + +Out of scope: calculator design (covered by `calculator-design`); quiz design (covered by `quiz-and-assessment-design`); the engineering implementation; specific Webflow/Framer/CMS configurations (those stay implementation-side). + +--- + +## The comparison-tool decision: when comparison tools earn investment + +Before designing the tool, decide whether a comparison tool is the right answer. + +**Comparison tools earn investment when:** + +- The audience is at a decision moment between known options (vs unknown options where a quiz or recommendation tool fits better). +- The options have meaningful differences that warrant side-by-side analysis. +- The brand can articulate honest distinctions between options without becoming sales pitch. +- The audience benefits from decision support, not just feature listing. + +**Comparison tools do NOT earn investment when:** + +- Options are too similar to compare meaningfully. +- The brand cannot make honest distinctions without creating sales-pitch dynamics. +- A simple comparison table or written content would serve. +- The audience does not actually face this decision (manufactured comparisons). + +The decision is not "should we have a comparison tool"; it is "is the comparison tool the right tool for this decision." + +Detail in [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md). + +--- + +## Feature-list-dump vs hidden-recommendation vs honest-comparison-with-guidance + +The keystone framing. + +**Feature-list-dump.** Every option's every feature in a giant grid. No decision support. The user is asked to weigh 40 cells against each other; most leave without choosing. Cost: design effort wasted on a grid that does not produce decisions; the audience perceives the grid as overwhelming. + +**Hidden-recommendation.** "Comparison" tool that is actually a sales pitch. Defaults favor one option; framing weights the answer; the recommendation is invisible but baked in. Trust erodes when users notice the bias. Cost: short-term conversion may look fine; long-term brand damage from "manipulative" reputation. + +**Honest-comparison-with-guidance.** Genuine like-for-like comparison plus an explicit opinionated recommendation ("For X audience, choose Y"). The recommendation is visible, defended, and not the only path; users can override. Cost: design effort upfront is significant; conversion typically improves because users feel respected and helped. + +The litmus test. Does the tool tell the user what to choose for their specific situation, with reasoning? If yes, honest-comparison-with-guidance. If it dumps features without guidance, feature-list-dump. If it says "the right answer is obviously [our preferred option]" without acknowledgment, hidden-recommendation. + +--- + +## Axis selection: which dimensions matter, which are noise + +The single most consequential decision in comparison tool design. + +**The principle.** Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision, not every feature available. + +**Strong axes.** + +- **Decision-relevant capabilities.** Features that materially affect the audience's outcome. +- **Cost dimensions.** Price, total cost of ownership, hidden costs. +- **Constraint dimensions.** Capacity, scale, integration support. +- **Service dimensions.** Support quality, onboarding, SLA. +- **Risk dimensions.** Vendor stability, security, compliance. + +**Weak axes.** + +- **Marketing checkboxes.** Features that exist on every option; checkmarks across the row. +- **Nice-to-haves.** Features the audience does not actually weigh. +- **Vendor-specific terminology.** Features named differently by each vendor; comparison becomes label confusion. +- **Decoration features.** Features added to the grid because the brand has them and competitors do not. + +**The 8-12 axis rule.** Most production comparison tools work well with 8-12 axes. Beyond that, decision paralysis sets in. + +Detail in [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md). + +--- + +## Default-comparison logic + +Which options compare by default, and why. + +**The principle.** Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; biased defaults shape conclusions. + +**Default options.** + +- Audience-fit defaults. The options the audience most commonly considers. +- Stage-fit defaults. The options that match the audience's stage of decision. +- Inferred defaults. Based on referral source, query, or prior interaction. + +**Default axes.** + +- The axes most relevant to the typical audience. +- Audience can expand to additional axes if interested. + +**Bias-flattering defaults.** + +- Defaults set so brand always wins on visible axes. +- Defaults that hide axes where competitors win. +- Defaults that frame in brand's terminology. + +The discipline. Defaults serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +Detail in [`references/default-comparison-logic.md`](references/default-comparison-logic.md). + +--- + +## Recommendation engine design + +When to recommend, how to defend the recommendation. + +**The principle.** Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible. + +**Recommendation patterns.** + +- **Single recommendation.** "For [audience], choose [option] because [reasons]." Clear; opinionated. +- **Multi-segment recommendation.** "If you are [A], choose X. If you are [B], choose Y." Honest about audience-fit. +- **Conditional recommendation.** "If [factor] matters most, X. If [other factor] matters most, Y." Helps the user decide based on priorities. + +**Recommendation defense.** + +- The reasoning shown. +- The audience for the recommendation explicit. +- The override path visible. + +**Anti-pattern: hidden recommendation.** Tool that defaults to one option's victory through axis selection and framing, without explicit recommendation. Users feel manipulated when they catch the pattern. + +Detail in [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) and [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md). + +--- + +## Filter and toggle UX + +What users can adjust, what should stay fixed. + +**Filterable elements.** + +- Which options to compare (user adds or removes options). +- Which axes to show (user filters to relevant dimensions). +- Audience or use case (user signals their context; tool adapts). + +**Fixed elements.** + +- Methodology disclosure (always visible). +- Recommendation reasoning (always findable). +- Source citations (always linkable). + +**The filter-fatigue trap.** Too many filters; user paralyzed. + +**The under-filtered trap.** Tool too rigid; user cannot match their context. + +The discipline. Filters that materially help; not filters for the sake of customization. + +Detail in [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md). + +--- + +## Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +**Pattern 1: Too many cells.** 40 features × 5 options = 200 cells; cognitive overload. + +**Pattern 2: All-checkmarks rows.** Every option has the feature; the row produces no signal. + +**Pattern 3: Inconsistent axis terminology.** Each vendor names features differently; user confused. + +**Pattern 4: Hidden costs.** Pricing visible; fees, overage, integrations not surfaced. + +**Pattern 5: Apples-to-oranges options.** Comparing genuinely different things; no axis applies cleanly. + +**Pattern 6: No recommendation.** Tool lists; user must decide; user does not. + +The cumulative effect. The tool produces no decision; users default to the brand they already heard of. + +Detail in [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-comparison-failures.md`](references/common-comparison-failures.md). + +- "Tool gets traffic; conversion is unchanged." Likely feature-list-dump; no decision support. +- "Sales says competitor leads cite our tool as biased." Hidden-recommendation pattern; trust damage. +- "Mobile users do not engage with the tool." Comparison grids do not work well on mobile; design for it. +- "Power users criticize axis selection." Audience knows these features; tool may have used easy axes rather than decision-relevant. +- "Tool was great at launch; conversion declined over time." Features changed; comparison stale. +- "Audience says 'this is helpful' but does not convert." Recommendation absent or weak; users get information without decision support. +- "Comparison shows every option as 'good' for something." Dilution; no clear recommendation. +- "Adding more features to the comparison reduced conversion." Crossed the cell-count threshold; cognitive overload. + +--- + +## The framework: 12 considerations for comparison tool design + +When designing or auditing a comparison tool, walk these 12 considerations. + +1. **The comparison-tool decision.** Is a tool the right answer, or does written content serve? +2. **Honest-comparison-with-guidance, not feature-list-dump or hidden-recommendation.** Genuine compare plus opinionated rec. +3. **Axis selection.** 8-12 decision-relevant axes; cut decoration features. +4. **Default-comparison logic.** Honest defaults; not bias-flattering. +5. **Recommendation engine designed.** Visible; defended; not the only path. +6. **Filter and toggle UX.** Filters that help; not filters for customization theater. +7. **Methodology disclosed.** Source data, axis weighting, audience definition. +8. **Mobile parity.** Tool works on the devices the audience uses. +9. **Maintenance discipline.** Comparison stays current as options change. +10. **Honest about competitor strengths.** When competitors win on an axis, say so. +11. **Audience-fit measured.** Per-segment conversion through the tool. +12. **Conversion as success metric.** Not just engagement; downstream choice and retention. + +The output of the framework is a comparison tool that earns the user's trust by helping them decide, with recommendation that is honest and defensible. + +--- + +## Reference files + +- [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md) - When comparison tools earn the build vs when written content serves. +- [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md) - Strong axes, weak axes, the 8-12 rule. +- [`references/default-comparison-logic.md`](references/default-comparison-logic.md) - Honest defaults vs bias-flattering defaults. +- [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) - When to recommend, how to defend, override path. +- [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md) - Filterable vs fixed elements; filter-fatigue trap. +- [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md) - Why most comparisons fail to produce decisions. +- [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md) - The discipline that distinguishes hidden from honest recommendations. +- [`references/comparison-anti-patterns.md`](references/comparison-anti-patterns.md) - The patterns that look like comparisons but degrade trust. +- [`references/common-comparison-failures.md`](references/common-comparison-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: comparison tools earn the choice when they earn the user's trust + +The comparison tools that work as compounding assets are the ones the audience trusts to help them decide. Not because the tool flatters the brand. Not because the tool dumps features. Because the tool genuinely helps the user pick the option that fits their situation, and is honest about which option that is. + +That is the bar. Below the bar are feature-list-dump (no decision support; user leaves without choosing) and hidden-recommendation (biased pretending to be neutral; trust collapses when caught). Above the bar are honest-comparison-with-guidance tools where axis selection, default logic, recommendation engine, and filter UX work together to produce decisions the audience trusts. + +The discipline is in the design choices. The decision to build a comparison at all. The axes that earn placement. The defaults that serve the audience. The recommendation that is visible and defended. The filters that help the user match their context. The methodology that is disclosed. The maintenance that keeps the comparison current. diff --git a/skills/comparison-tool-design/references/axis-selection-patterns.md b/skills/comparison-tool-design/references/axis-selection-patterns.md new file mode 100644 index 0000000..299644d --- /dev/null +++ b/skills/comparison-tool-design/references/axis-selection-patterns.md @@ -0,0 +1,185 @@ +# Axis selection patterns + +Strong axes, weak axes, the 8-12 rule. + +Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision. Done well, axes produce decisions; done poorly, they produce overwhelm. + +--- + +## The decision-relevance principle + +Each axis should affect the audience's decision. Axes that do not are decoration. + +**The win.** A comparison tool with 10 axes covering capability, pricing, integration, support quality. Each axis materially affects whether the audience would choose. + +**The fail.** Same tool with 35 axes including marketing-checkbox features. User overwhelmed; many cells provide no signal. + +The discipline. Axes earn placement through decision relevance. + +--- + +## Strong axes + +Patterns that earn placement. + +**Decision-relevant capabilities.** The 5-7 capabilities the audience explicitly evaluates. + +**Cost dimensions.** Price, total cost of ownership, hidden costs. + +**Constraint dimensions.** Capacity, scale ceilings, integrations, geography. + +**Service dimensions.** Support quality, onboarding, SLA. + +**Risk dimensions.** Vendor stability, security, compliance. + +**Time dimensions.** Time to value, implementation timeline. + +**The selection discipline.** Each axis answers "will this matter to the audience?" If no, cut. + +--- + +## Weak axes + +Patterns that fail. + +**Marketing checkboxes.** Features on every option; checkmarks across the row. No signal. + +**Nice-to-haves.** Features the audience does not weigh. + +**Vendor-specific terminology.** Features named differently by each vendor; label confusion. + +**Decoration features.** Added because brand has them. + +**Generic checkmarks.** "Customer support: yes/yes/yes." Not differentiating. + +--- + +## The 8-12 axis rule + +Most production comparison tools work well with 8-12 axes. + +**Why 8-12.** + +- Below 8: comparison thin. +- Above 12: cognitive overload. + +**Exceptions.** + +- Highly technical audiences may absorb 15-20. +- Consumer audiences may tolerate 6-8. + +**The over-12 trap.** Each axis beyond 12 reduces engagement. + +--- + +## Axis ordering + +Within the comparison, order matters. + +**Strong order.** Most decision-relevant first. + +**Weak order.** Random; alphabetical; feature-category without importance weighting. + +**The first-axis discipline.** First axis should be one of the most important; users may skim past later axes. + +--- + +## Axis grouping + +When axes group naturally. + +**Grouping patterns.** Capability axes together; cost together; service together; risk together. + +**Strengths.** Easier to scan. + +**Weaknesses.** Group dividers add visual complexity. + +**When to use.** When axis count justifies (10+ axes). + +--- + +## Axis content per cell + +What each cell shows. + +**Beyond checkmarks.** "Yes/no" rarely produces decisions. Numbers, descriptions, comparisons add depth. + +**Examples.** + +- Cost: "$X/month" not just "Yes" to "has pricing." +- Capacity: "Up to 1000 users" not just "Yes" to "scales." +- Support: "24/7 chat plus phone" not just "Yes" to "support." + +The cell content discipline. Depth where decisions need it. + +--- + +## Axis defaults + +Which axes show by default; which behind toggle. + +**Default-shown axes.** The 8-12 most decision-relevant. + +**Toggle-shown axes.** Less critical; audience can expand. + +**The hide-bias trap.** Hiding axes where brand loses; detection eventual. + +**The honest-default principle.** Defaults reflect audience importance; not brand strength. + +--- + +## Axis updates + +Axes decay. + +**What decays.** + +- Axes that lost relevance. +- Axes that gained relevance. +- Axis content stale. + +**Maintenance cadence.** Quarterly review. + +--- + +## Axis testing + +Validate axes with the audience. + +**Methods.** + +- User research: which axes do they consider? +- A/B test: different axis sets. +- Sales-call mining: which axes do prospects ask about? + +The validation discipline. Axes are hypotheses; validate. + +--- + +## Common axis failures + +**Too many axes.** Cognitive overload. + +**Too few axes.** Comparison thin. + +**Wrong axes.** Audience does not weigh them. + +**Marketing-checkbox axes.** No signal. + +**Vendor-specific terminology.** Label confusion. + +**Hidden axes where brand loses.** Bias detected. + +**Stale axis content.** Pricing or features outdated. + +**Axis ordering ignores importance.** First axes are not most critical. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relevance principle. Strong axes (6 patterns). Weak axes (5 patterns). The 8-12 rule. Axis ordering. Axis grouping. Cell content. Axis defaults. Updates. Testing. Common failures. + +## Implementation choices that stay internal + +Specific axes for specific tools. Specific cell content. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/common-comparison-failures.md b/skills/comparison-tool-design/references/common-comparison-failures.md new file mode 100644 index 0000000..6dafdbb --- /dev/null +++ b/skills/comparison-tool-design/references/common-comparison-failures.md @@ -0,0 +1,179 @@ +# Common comparison failures + +8+ failure patterns with diagnoses and cures. + +--- + +## "Tool gets traffic; conversion is unchanged." + +**The diagnosis.** Likely feature-list-dump; no decision support. + +**The cure.** Add recommendation. Cut decoration axes. Detail in `references/recommendation-engine-design.md`. + +--- + +## "Sales says competitor leads cite our tool as biased." + +**The diagnosis.** Hidden-recommendation pattern; trust damage. + +**The cure.** Honest recommendation discipline (`references/honest-recommendation-discipline.md`). Acknowledge competitor strengths. + +--- + +## "Mobile users do not engage with the tool." + +**The diagnosis.** Comparison grids do not work well on mobile. + +**The cure.** Mobile-first design. Stacked layout. Reduced axis count for mobile. + +--- + +## "Power users criticize axis selection." + +**The diagnosis.** Audience knows these features; tool may have used easy axes rather than decision-relevant. + +**The cure.** Audit axes against real audience decisions. Replace marketing-checkbox axes with decision-relevant ones. + +--- + +## "Tool was great at launch; conversion declined over time." + +**The diagnosis.** Features changed; comparison stale. + +**The cure.** Quarterly maintenance. + +--- + +## "Audience says 'this is helpful' but does not convert." + +**The diagnosis.** Recommendation absent or weak. + +**The cure.** Add recommendation with reasoning and clear next-step CTA. + +--- + +## "Comparison shows every option as 'good' for something." + +**The diagnosis.** Dilution; no clear recommendation. + +**The cure.** Take a stand. Recommendation should be opinionated; tradeoffs acknowledged. + +--- + +## "Adding more features to the comparison reduced conversion." + +**The diagnosis.** Crossed the cell-count threshold; cognitive overload. + +**The cure.** Cut back. 8-12 axes is the working range. + +--- + +## "Sales says many leads come through the tool but bounce on demo." + +**The diagnosis.** Tool's framing oversells; reality on demo does not match. + +**The cure.** Honest tool produces honest leads. Audit framing for sales-pitch dynamics. + +--- + +## "Audience-segment recommendations feel stereotyped." + +**The diagnosis.** Segment definitions based on assumptions rather than research. + +**The cure.** Validate audience segments with research. Refine recommendations based on real needs. + +--- + +## "Specific competitor is missing; users ask why." + +**The diagnosis.** Competitor omitted from comparison. + +**The cure.** Include relevant competitors. If intentionally excluded, disclose why ("we focus on X category; competitor Y is in different category"). + +--- + +## "Tool methodology questioned by analyst or journalist." + +**The diagnosis.** Methodology hidden or weakly defended. + +**The cure.** Detailed methodology disclosure. Be ready to defend specific axis choices and weights. + +--- + +## "Tool conversion is fine; sales conversion does not match." + +**The diagnosis.** Tool optimizes for tool-conversion; downstream not aligned. + +**The cure.** Track downstream metrics. Optimize for downstream conversion, not just tool engagement. + +--- + +## "Filter use is low; users see default comparison only." + +**The diagnosis.** Filters added but not promoted; users do not realize they exist. + +**The cure.** Promote filters; or accept that defaults serve and reduce filter complexity. + +--- + +## "Filters produce empty result combinations." + +**The diagnosis.** Filter logic does not constrain combinations to those producing comparable options. + +**The cure.** Smart filter logic. When filters would produce empty result, surface alternatives. + +--- + +## "Recommendation fires for one option always." + +**The diagnosis.** Hidden-recommendation; bias-flattering logic. + +**The cure.** Test the recommendation engine across audience scenarios. Ensure competitors win when fit warrants. + +--- + +## "Audience tells us the comparison feels accurate but the recommendation feels off." + +**The diagnosis.** Comparison data accurate; recommendation engine logic does not match audience priorities. + +**The cure.** Validate recommendation logic. Audience research on what they weigh vs what the tool weights. + +--- + +## "We A/B tested adding axes; conversion went down." + +**The diagnosis.** Crossed the cell-count threshold. + +**The cure.** Maintain axis discipline. More is not always better. + +--- + +## "Tool produces good conversion for new visitors; returning visitors do not engage." + +**The diagnosis.** Tool optimized for first-time-decision audience; returning visitors have other needs. + +**The cure.** Different surfaces for different stages. Returning visitors may want simpler reference rather than full tool. + +--- + +## The pattern across failures + +Most comparison tool failures fall into one of three patterns. + +**Pattern 1: No decision support.** Feature-list-dump, no-recommendation, dilution. The fix is clear, defensible recommendation. + +**Pattern 2: Bias damages trust.** Hidden-recommendation, contradiction, omitted competitors, stereotypes. The fix is honest recommendation discipline. + +**Pattern 3: Friction.** Over-filtered, mobile-broken, fatigue patterns. The fix is reducing cognitive load and matching audience use. + +The metric pattern: comparison failures often look fine on engagement alone. The signal is in conversion, downstream metrics, audience trust. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (no-decision-support, bias, friction). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-anti-patterns.md b/skills/comparison-tool-design/references/comparison-anti-patterns.md new file mode 100644 index 0000000..35ec8f0 --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-anti-patterns.md @@ -0,0 +1,218 @@ +# Comparison anti-patterns + +The patterns that look like comparisons but degrade trust. Easy to ship; cost shows up in conversion, brand reputation, and audience trust. + +--- + +## The feature-list-dump comparison + +The pattern. Every feature × every option. No decision support. + +The signal. Users skim; do not choose; tool produces no conversion lift. + +The cure. Cut to 8-12 decision-relevant axes. Add recommendation. + +--- + +## The hidden-recommendation comparison + +The pattern. Defaults bias toward brand without disclosure. + +The signal. Sophisticated audiences notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest defaults; explicit recommendation; acknowledge competitor strengths. + +--- + +## The all-checkmarks comparison + +The pattern. Every option has every feature; checkmarks across the rows. + +The signal. Rows produce no signal; users skim. + +The cure. Cut generic-checkmark rows. Replace with specifics that differentiate. + +--- + +## The terminology-confused comparison + +The pattern. Each vendor's terminology used in their column; user cannot tell if features match. + +The signal. Users confused; comparison breaks semantically. + +The cure. Normalize terminology. Vendor names in subtext; functional descriptions in main label. + +--- + +## The hidden-cost comparison + +The pattern. Headline pricing visible; overage, fees, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cure. Total cost of ownership surfaced. + +--- + +## The apples-to-oranges comparison + +The pattern. Options compared that are genuinely different things. + +The signal. Comparison feels strained; axes do not apply cleanly. + +The cure. Compare options the audience actually considers together. Separate tools for separate categories if needed. + +--- + +## The no-recommendation comparison + +The pattern. Tool lists; user decides alone. + +The signal. High abandonment; conversion lift absent. + +The cure. Add recommendation with reasoning. + +--- + +## The contradicts-itself comparison + +The pattern. Comparison shows competitor winning on most axes; tool recommends brand anyway. + +The signal. Users notice the contradiction; trust collapses. + +The cure. Recommendation aligns with comparison; or recommendation defends the contradiction explicitly. + +--- + +## The stale comparison + +The pattern. Information from 6+ months ago. + +The signal. Users notice; trust drops. + +The cure. Quarterly maintenance. + +--- + +## The over-filtered comparison + +The pattern. 12+ filters; user paralysis at filter step. + +The signal. High drop-off before the comparison loads. + +The cure. Reduce filter count; default-heavy. + +--- + +## The under-filtered comparison + +The pattern. Tool too rigid; one fixed view. + +The signal. Specific segments convert poorly. + +The cure. Add filters where audiences split. + +--- + +## The mobile-broken comparison + +The pattern. Grid designed for desktop; mobile cramped or scroll-required. + +The signal. Mobile conversion much lower. + +The cure. Mobile-first design. + +--- + +## The methodology-hidden comparison + +The pattern. Tool shown without explaining how comparison was built. + +The signal. Sophisticated users question the tool. + +The cure. Methodology disclosure. + +--- + +## The audience-stereotype comparison + +The pattern. Audience-segment recommendations rely on stereotypes ("enterprise = big and slow"). + +The signal. Users in those segments feel mis-served. + +The cure. Audience-segment recommendations based on real needs, not assumptions. + +--- + +## The over-recommend comparison + +The pattern. Tool recommends in cases where genuine differentiator does not exist. + +The signal. Users notice the recommendation feels arbitrary. + +The cure. "We cannot rank these for you" is sometimes the honest answer. + +--- + +## The competitor-omission comparison + +The pattern. Important competitor missing from the comparison. + +The signal. Users ask "where is X?" or feel comparison is incomplete. + +The cure. Include relevant competitors. If a competitor is omitted intentionally, disclose why. + +--- + +## The bias-flattering-axis-selection comparison + +The pattern. Axes chosen where brand wins; axes hidden where brand loses. + +The signal. Sophisticated audiences notice axis selection. + +The cure. Honest axis selection. Detail in `references/axis-selection-patterns.md`. + +--- + +## The marketing-checkbox comparison + +The pattern. Every option's marketing checkboxes laid out as comparison. + +The signal. Comparison reads like marketing brochures rather than analysis. + +The cure. Replace marketing checkboxes with specific functional capabilities. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +**Audit questions per tool.** + +- Is the tool feature-list-dump (anti-pattern check)? +- Does the recommendation acknowledge competitor strengths (anti-pattern check: hidden-recommendation)? +- Are rows differentiating (anti-pattern check: all-checkmarks)? +- Is terminology normalized (anti-pattern check: terminology-confused)? +- Are total costs surfaced (anti-pattern check: hidden-cost)? +- Are options apples-to-apples (anti-pattern check: apples-to-oranges)? +- Is recommendation present (anti-pattern check: no-recommendation)? +- Does recommendation align with comparison (anti-pattern check: contradicts-itself)? +- Is information current (anti-pattern check: stale)? +- Are filters calibrated (anti-pattern check: over-filtered, under-filtered)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Is methodology disclosed (anti-pattern check: methodology-hidden)? + +**The retire decision.** Tools failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-fatigue-patterns.md b/skills/comparison-tool-design/references/comparison-fatigue-patterns.md new file mode 100644 index 0000000..10e5a0f --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-fatigue-patterns.md @@ -0,0 +1,190 @@ +# Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Most comparison tools accumulate cognitive load until users abandon without choosing. Comparison-fatigue patterns are the failure modes that make this happen. + +--- + +## Pattern 1: Too many cells + +The pattern. 40 features × 5 options = 200 cells. + +The signal. Users skim; pick the brand they already heard of; tool produces no decision. + +The cost. Comparison work is invisible because users cannot process the volume. + +The cure. Reduce cells. 8-12 axes × 3-5 options = 24-60 cells. The comparison density is comprehensible. + +--- + +## Pattern 2: All-checkmarks rows + +The pattern. Every option has the feature; the row produces checkmarks across. + +The signal. Users skim past; row provides no signal. + +The cost. Row earns space without earning attention. + +The cure. Cut the row, or replace generic checkmarks with specifics that differentiate. + +--- + +## Pattern 3: Inconsistent axis terminology + +The pattern. Each vendor names features differently; comparison becomes label confusion. + +The signal. User confusion; cannot tell if "Pro Workspace" and "Premium Studio" are the same thing. + +The cost. Comparison breaks at semantic level; users cannot weigh. + +The cure. Normalize terminology. Use functional descriptions; vendor labels in subtext. + +--- + +## Pattern 4: Hidden costs + +The pattern. Pricing visible; fees, overage, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cost. Trust damage when discovered. + +The cure. Surface total cost of ownership. Acknowledge fees, overage, expected add-ons. + +--- + +## Pattern 5: Apples-to-oranges options + +The pattern. Comparing genuinely different things; no axis applies cleanly. + +The signal. Comparison feels strained; users cannot tell why these options are being compared. + +The cost. Tool exists but produces no useful decision support. + +The cure. Compare options the audience would actually consider together. If options are too different, separate tools may serve better. + +--- + +## Pattern 6: No recommendation + +The pattern. Tool lists; user must decide; user does not. + +The signal. High abandonment; conversion rate low. + +The cost. The tool's information work does not produce decisions. + +The cure. Add explicit recommendation with reasoning. Detail in `references/recommendation-engine-design.md`. + +--- + +## Pattern 7: Stale information + +The pattern. Comparison content from 6+ months ago; competitors have updated; brand has updated. + +The signal. Users notice the staleness; trust drops. + +The cost. Tool produces decisions based on outdated information. + +The cure. Quarterly maintenance. Triggered updates when major competitor or brand changes happen. + +--- + +## Pattern 8: Bias-flattering framing + +The pattern. Comparison content frames in brand's favor (showing brand's most expensive plan vs competitors' cheap; using brand's terminology for axes). + +The signal. Sophisticated users notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest framing. Acknowledge competitor strengths. Use neutral terminology where possible. + +--- + +## Pattern 9: Decision paralysis at filter step + +The pattern. Tool requires extensive filter setup before showing comparison; users abandon at filter step. + +The signal. High drop-off before the comparison loads. + +The cost. Comparison work is invisible; users never see it. + +The cure. Default-heavy. Show comparison immediately; filters available but optional. + +--- + +## Pattern 10: Mobile illegibility + +The pattern. Comparison grid designed for desktop; on mobile, cells cramped or scroll-required. + +The signal. Mobile conversion much lower than desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design. Stacked layout for mobile; reduced axis count. + +--- + +## Pattern 11: No methodology disclosure + +The pattern. Comparison shown without explaining how it was assembled. Users do not know if it is honest. + +The signal. Users question the comparison; sales hears about doubts. + +The cost. Trust degrades; comparison's authority unclear. + +The cure. Disclose methodology. Where data came from; how axes were chosen; when last updated. + +--- + +## Pattern 12: Recommendation contradicts comparison + +The pattern. Comparison shows option B winning on most axes; tool recommends option A. + +The signal. Users notice the contradiction; trust collapses. + +The cost. Tool internally inconsistent; users cannot rely on it. + +The cure. Recommendation aligns with comparison. If recommendation favors A despite axis losses, defend explicitly ("Option A wins despite [losses] because [audience-specific reasoning]"). + +--- + +## The cumulative effect + +Most comparison tools fail at multiple of these patterns simultaneously. The cumulative effect: tool produces no decisions; users default to the brand they already heard of; comparison work is wasted. + +The cure. Audit each pattern. Each pattern fixed reduces cumulative friction. + +--- + +## How to audit comparison fatigue + +Quarterly review. + +**Audit questions per tool.** + +- Cell count: is it under 100? +- Are any rows all-checkmarks? +- Is terminology normalized across options? +- Are total costs surfaced? +- Are options apples-to-apples? +- Is recommendation present and visible? +- Is information current? +- Is framing honest? +- Is filter step lightweight? +- Does mobile work? +- Is methodology disclosed? +- Does recommendation match comparison? + +**The retire decision.** Tools failing multiple patterns warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 fatigue patterns. Signal-pattern-cost framing. Cures. The cumulative effect. Audit questions. + +## Implementation choices that stay internal + +Specific fatigue patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md b/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md new file mode 100644 index 0000000..527087f --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md @@ -0,0 +1,132 @@ +# Comparison-tool decision criteria + +When comparison tools earn the build vs when written content serves. + +A comparison tool is meaningful work. Axis selection, default logic, recommendation engine, filter UX, ongoing maintenance. The tool earns this investment only when specific conditions are present. + +--- + +## When comparison tools earn the build + +Five conditions that, when present, make a comparison tool a strong investment. + +**The audience is at a decision moment between known options.** They know the options exist; they need help choosing. Audiences who do not yet know the options need different tools (quizzes, recommendations). + +**The options have meaningful differences.** Comparing two options that differ only in branding produces nothing useful. + +**The brand can articulate honest distinctions.** Without becoming sales pitch. + +**The audience benefits from decision support.** Some audiences want a tool that helps them decide rather than weigh tradeoffs themselves. + +**The success metric is defined.** Conversion through the tool, downstream conversion, choice quality. + +When all five are present, a comparison tool is strong investment. When two or fewer are present, written content often serves better. + +--- + +## When comparison tools do NOT earn the build + +Funnels where comparison tools add cost without lift. + +**Options too similar.** Comparing genuinely interchangeable options produces no decision support. + +**Options apples-to-oranges.** Comparison axes do not apply across both. + +**Brand cannot make honest distinctions.** Tool will become hidden-recommendation; trust suffers. + +**A simple table or article would serve.** Static comparison content is cheaper. + +**The audience does not face this decision.** Manufactured comparisons feel forced. + +--- + +## Comparison tools vs written vs-pages + +Both compare options; differ in interactivity. + +**Written vs-pages strengths.** Cheap; SEO-friendly; easy to update. + +**Written vs-pages weaknesses.** Static; no recommendation logic. + +**Comparison tool strengths.** Adaptive; surfaces recommendations dynamically; lets users explore. + +**Comparison tool weaknesses.** Build cost; maintenance burden. + +**The combined approach.** Many production teams use both: vs-pages for SEO; tools for decision support. + +--- + +## The opportunity-cost frame + +Comparison tools are significant work. + +**Build cost.** Axis curation, recommendation logic, filter UX, methodology disclosure, mobile responsiveness. 30-100 engineering hours plus design and content. + +**Maintenance cost.** Quarterly updates run 4-8 hours. + +**Opportunity cost.** What else could the team have built? Better vs-pages, calculator, quiz. The tool has to clear those alternatives. + +The decision frame. Comparison tools earn investment when they produce more decision lift than alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering a comparison tool against 3 named competitors. + +**Conditions check.** + +- Decision moment: yes. +- Meaningful differences: yes; pricing, features, integration vary. +- Brand can articulate honest distinctions: yes. +- Audience benefits: yes. +- Success metric defined: yes. + +**Decision.** Build the comparison tool. + +**Architecture.** 10 axes; 4 options; honest recommendation per audience segment. + +The decision was deliberate. + +--- + +## Decision worked example: when written serves + +A consumer-facing financial product considering a comparison tool against generic bank accounts. + +**Conditions check.** + +- Decision moment: yes. +- Meaningful differences: somewhat; many banks similar. +- Brand articulate distinctions: yes for specific competitors. +- Audience benefits: somewhat. +- Success metric: signup; harder to attribute. + +**Decision.** Written vs-pages plus a brief comparison table. Full tool not warranted. + +The decision was right-sized. + +--- + +## When to retire a comparison tool + +Tools can become wrong over time. + +**Retire when:** + +- Conversion declined consistently. +- Options changed enough that comparison is misleading. +- Competitors deprecated. +- A redesigned vs-page produces equivalent results. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant comparison tools. The five conditions that argue against. Comparison tools vs written vs-pages. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tool decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/comparison-tool-design/references/default-comparison-logic.md b/skills/comparison-tool-design/references/default-comparison-logic.md new file mode 100644 index 0000000..07c542a --- /dev/null +++ b/skills/comparison-tool-design/references/default-comparison-logic.md @@ -0,0 +1,169 @@ +# Default-comparison logic + +Honest defaults vs bias-flattering defaults. + +Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; bias-flattering defaults shape conclusions in ways that erode trust when caught. + +--- + +## The honest-default principle + +Defaults should serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +**The win.** Default comparison shows the brand alongside 2-3 commonly-considered competitors. Default axes are the 8-12 most decision-relevant. Default audience profile (if pre-selected) reflects the visitor's likely segment. + +**The fail.** Default comparison shows the brand alongside the 2 weakest competitors. Default axes are the ones where the brand wins. Audience defaults assume the brand's ideal customer. + +The discipline. Defaults make the comparison fair as a starting point; users can adjust. + +--- + +## Default options + +Which options compare by default. + +**Audience-fit defaults.** The options the audience most commonly considers. + +How to determine. Sales-call mining (which competitors do prospects mention?), referral analysis, user research. + +**Stage-fit defaults.** The options that match the audience's stage. + +How. Awareness audiences may compare against generic categories; decision audiences against specific products. + +**Inferred defaults.** Based on referral source or query. + +How. Visitor from "X vs Y" search query gets X and Y as defaults; visitor from generic landing gets default comparison set. + +--- + +## Default axes + +Which axes show by default. + +**The most-critical-axes default.** Top 8-12 axes by decision relevance. + +**Audience-relevant axes.** Default to axes most relevant to the inferred or stated audience. + +**The hide-where-we-lose anti-pattern.** Defaulting to axes where the brand wins; hiding where it loses. Detection by analytical audiences eventual; trust damage permanent. + +The cure. Defaults reflect audience importance, not brand strength. Honest about competitor strengths. + +--- + +## Default audience or use case + +When the tool asks (or infers) the audience. + +**Pattern A: Pre-selected.** Tool selects an audience based on referrer or query. + +Strengths. Lower friction; tool seems intelligent. + +Weaknesses. Inference can be wrong. + +**Pattern B: Asked upfront.** Tool asks "what is your role?" or "what is your team size?" + +Strengths. Accurate; user controls. + +Weaknesses. Adds friction; some audiences skip. + +**Pattern C: No audience selection.** Tool shows comparison; user can filter. + +Strengths. Lowest friction; works for all audiences. + +Weaknesses. Generic; no per-audience recommendation. + +The choice depends on the tool's complexity and the audience's diversity. + +--- + +## Default recommendation + +What the tool recommends by default. + +**Pattern A: Single default recommendation.** "For most teams, [option] is the best choice." + +Strengths. Clear; opinionated. + +Weaknesses. May not fit all visitors. + +**Pattern B: Audience-conditional default.** Recommendation changes based on audience selection. + +Strengths. Fits different audiences. + +Weaknesses. More complex. + +**Pattern C: No default recommendation.** Tool requires user to specify before recommending. + +Strengths. User commits; recommendation is matched. + +Weaknesses. Higher friction. + +The discipline. Whatever default, the recommendation is honest about who it is for. + +--- + +## Bias-flattering defaults: the failure + +Patterns that destroy trust. + +**Defaults set for brand victory.** Comparison tool defaults to axes where the brand wins, hides where it loses. + +**Defaults that frame in brand's terminology.** Other options compared in vocabulary that favors the brand's positioning. + +**Defaults that misrepresent competitor pricing.** Showing competitor's most expensive plan vs brand's mid-tier. + +**Defaults that show outdated competitor info.** Listing features competitors have updated. + +**The audience reaction.** Sophisticated audiences notice; trust collapses; brand earns "manipulative" reputation. + +--- + +## Honest defaults with disclosure + +When the brand legitimately stands out, honest framing matters. + +**The pattern.** "Default view shows the comparison most relevant to teams of [size]. Your situation may differ; use filters to adjust." + +**Disclosure where defaults are brand-favorable.** "We are highlighting [axis] because we think it matters most for [audience]. Let us know if you weigh things differently." + +The honest framing earns trust where bias-flattering loses it. + +--- + +## Default maintenance + +Defaults decay. + +**What decays.** + +- Default options no longer match audience consideration. +- Default axes no longer the most relevant. +- Default audiences shifted. + +**Maintenance cadence.** Quarterly review. Update as competitive landscape and audience composition shift. + +--- + +## Common default failures + +**Hide-where-we-lose.** Bias detected; trust collapses. + +**Stale defaults.** Competitor info outdated. + +**Wrong default audience.** Inference produces unfit comparison for visitor. + +**No default at all.** Tool requires extensive setup before showing comparison. + +**Default obscures methodology.** Defaults look like neutral; methodology is biased. + +**Default ignores recent competitor changes.** Defaults from 6 months ago. + +--- + +## Methodology-level choices that stay in the public skill + +The honest-default principle. Default options. Default axes. Default audience or use case. Default recommendation. The bias-flattering failure pattern. Honest defaults with disclosure. Default maintenance. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific comparison tools. Specific audience inference logic. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/filter-and-toggle-patterns.md b/skills/comparison-tool-design/references/filter-and-toggle-patterns.md new file mode 100644 index 0000000..2d5addb --- /dev/null +++ b/skills/comparison-tool-design/references/filter-and-toggle-patterns.md @@ -0,0 +1,225 @@ +# Filter and toggle patterns + +What users can adjust, what should stay fixed. The filter-fatigue trap. + +Filters and toggles let users adapt the comparison to their context. Done well, filters help users match the tool to their situation; done poorly, filters become customization theater that adds complexity without value. + +--- + +## The help-don't-customize principle + +Filters earn placement when they help users match the comparison to their context. Filters for the sake of customization options add complexity without lift. + +**The win.** Tool offers 3 filters: audience size, use case, must-have integrations. Each filter materially adapts the recommendation. Users find their context quickly. + +**The fail.** Tool offers 15 filters across multiple dimensions. Decision paralysis at the filter step; users abandon before reaching the comparison. + +The discipline. Filters that help; not filters for theater. + +--- + +## Filterable elements + +What users can adjust. + +**Options to compare.** User adds or removes options. + +**Axes to show.** User filters to relevant dimensions. + +**Audience or use case.** User signals their context; tool adapts. + +**Pricing model preference.** User selects monthly vs annual; per-seat vs flat. + +**Region or geography.** User selects where they operate; tool adapts to applicable options. + +--- + +## Fixed elements + +What should not be filterable. + +**Methodology disclosure.** Always visible. + +**Recommendation reasoning.** Always findable. + +**Source citations.** Always linkable. + +**Honest framing.** Tool is honest about its biases regardless of filter state. + +--- + +## Filter UI patterns + +How filters appear. + +**Pattern A: Top-of-page filters.** + +How it works. Filter row at top; user adjusts; comparison below updates. + +Strengths. Visible; familiar. + +Weaknesses. Takes screen space; mobile-challenging. + +**Pattern B: Sidebar filters.** + +How it works. Filter panel on the side; comparison main area. + +Strengths. Persistent; works on desktop. + +Weaknesses. Mobile-broken; takes space. + +**Pattern C: Inline filters.** + +How it works. Filters appear within the comparison (per-axis filtering, per-option toggling). + +Strengths. Contextual. + +Weaknesses. Visual complexity. + +**Pattern D: Wizard-style.** + +How it works. Tool asks 2-3 filter questions; then shows comparison. + +Strengths. Less overwhelming. + +Weaknesses. Adds friction upfront. + +The choice depends on filter complexity and audience preferences. + +--- + +## Filter count + +How many filters earn placement. + +**3-5 filters.** Sweet spot. Each filter helps; cumulative friction manageable. + +**6-8 filters.** Acceptable for complex tools; require strong UX. + +**10+ filters.** Almost always too many. Decision paralysis at filter step. + +**1-2 filters.** Often too few; tool feels rigid. + +--- + +## Filter defaults + +What filters are pre-set. + +**Honest defaults.** Reflect typical audience. + +**Audience-detected defaults.** Inferred from referral or context. + +**No defaults (user must select).** Adds friction but ensures intentionality. + +The default discipline. Defaults reflect audience importance; not brand strength. + +--- + +## Filter combinations + +When filters interact. + +**Independent filters.** Each filter changes one dimension; combinations multiply. + +**Conditional filters.** Some filters appear only after others are set. + +**Smart filters.** Tool suggests filters based on earlier selections. + +The discipline. Combinations should produce meaningful comparisons; not empty cells. + +--- + +## The filter-fatigue trap + +Too many filters; user paralyzed. + +**The pattern.** Tool offers 12 filters. User feels they need to set them all to get meaningful comparison. User leaves before completing. + +**The signal.** Drop-off at the filter step; users do not reach the comparison. + +**The cost.** Comparison tool's main value (the comparison) is invisible. + +**The cure.** Reduce filter count. Default-heavy. Optional filters behind a "more options" toggle. + +--- + +## The under-filtered trap + +Tool too rigid; user cannot match context. + +**The pattern.** Tool shows one fixed comparison; no way to adapt. + +**The signal.** Users complain the tool does not fit them; specific segments convert poorly. + +**The cost.** Tool serves only the audience the default fits. + +**The cure.** Add filters where audience genuinely splits. + +--- + +## Filter mobile design + +Filters on mobile have specific considerations. + +**Mobile-specific patterns.** + +- Filters in a collapsible drawer rather than always-visible panel. +- Reduced filter count on mobile (defer non-critical filters). +- Touch-friendly toggles. + +**Mobile-broken patterns.** + +- Sidebar filters cramping the comparison. +- Top-of-page filters that scroll off and require scrolling back. +- Filter modals that take over the screen. + +The mobile discipline. Filters work on mobile or do not exist there. + +--- + +## Filter analytics + +Track filter use. + +**Metrics.** + +- Per-filter use rate. +- Filter abandonment (started filtering; left without completing). +- Filter combinations that produce no results. + +**Diagnostic uses.** + +- Filter rarely used: it may not earn placement. +- Filter abandonment high: too many filters or bad defaults. +- No-result combinations: filter logic may have gaps. + +--- + +## Common filter failures + +**Too many filters.** Filter fatigue. + +**Too few filters.** Tool too rigid. + +**Filters with no value.** Filters that do not change anything meaningful. + +**Filters that produce empty results.** Combinations show no options. + +**Mobile-broken filters.** Filters work on desktop, fail mobile. + +**Filter UX inconsistent.** Mix of patterns; users confused. + +**Default filters bias-flattering.** Defaults make brand look better than reality. + +**No filter analytics.** Cannot tell which filters earn their place. + +--- + +## Methodology-level choices that stay in the public skill + +The help-don't-customize principle. Filterable vs fixed elements. Filter UI patterns A through D. Filter count. Filter defaults. Filter combinations. The filter-fatigue and under-filtered traps. Filter mobile design. Filter analytics. Common failures. + +## Implementation choices that stay internal + +Specific filters for specific tools. Specific filter UI implementations. Specific defaults. The team's mobile testing benchmarks. These vary by team. diff --git a/skills/comparison-tool-design/references/honest-recommendation-discipline.md b/skills/comparison-tool-design/references/honest-recommendation-discipline.md new file mode 100644 index 0000000..37df188 --- /dev/null +++ b/skills/comparison-tool-design/references/honest-recommendation-discipline.md @@ -0,0 +1,201 @@ +# Honest recommendation discipline + +The discipline that distinguishes hidden from honest recommendations. + +Recommendations are powerful. Honest ones earn trust; hidden ones erode it. The discipline is to know which kind your tool produces. + +--- + +## The litmus test + +A sophisticated user from the target audience tests the tool by selecting a clearly wrong-fit scenario for the brand. Does the tool recommend a competitor when fit warrants? + +**The win.** Tool recommends competitor X for the wrong-fit scenario, with reasoning. The sophisticated user trusts the tool because it is willing to recommend against the brand. + +**The fail.** Tool always recommends the brand regardless of scenario. The sophisticated user catches the pattern; trust collapses. + +The discipline. The tool's willingness to recommend competitors when warranted is the trust marker. + +--- + +## What honest recommendation looks like + +Five marks of honesty. + +**Mark 1: Brand does not always win.** When competitors fit better, tool says so. + +**Mark 2: Reasoning is specific and verifiable.** "Option B has X capability that Option A lacks" rather than "B is better." + +**Mark 3: Audience-fit is articulated.** "For [audience] with [needs], choose X. For different audience, choose Y." + +**Mark 4: Tradeoffs acknowledged.** "Option X wins on capability A but loses on capability B." + +**Mark 5: Methodology disclosed.** Users can see how the recommendation was generated. + +When all five are present, the recommendation is honest. When any are absent, hidden-recommendation dynamics creep in. + +--- + +## What hidden recommendation looks like + +Five marks of hidden bias. + +**Mark 1: Brand always wins regardless of scenario.** + +**Mark 2: Reasoning is generic ("best in class") without specifics.** + +**Mark 3: Audience-fit not articulated; one recommendation for all.** + +**Mark 4: Tradeoffs not acknowledged; brand presented as superior on all axes.** + +**Mark 5: Methodology hidden or vague.** + +When these patterns combine, the tool is hidden-recommendation regardless of whether the team intended bias. + +--- + +## The acknowledge-competitor-strengths principle + +Honest recommendation tools acknowledge where competitors are stronger. + +**The pattern.** "Competitor X has the strongest [capability]. We win on [different capability]. For audiences prioritizing [first], X. For audiences prioritizing [second], us." + +**Why it works.** Acknowledging strengths signals honesty. Audiences trust the recommendation more because the tool is willing to lose on specific axes. + +**The reluctant-acknowledgment failure.** Acknowledging competitor strengths only when forced; minimizing them where possible. Detection by sophisticated audiences eventual. + +--- + +## The recommendation-defense quality + +How well the tool defends its recommendation. + +**Strong defense.** + +- Specific to audience. +- Tied to specific axes where the recommended option wins. +- Includes tradeoffs. +- Cites data or sources. + +**Example.** + +"For mid-market teams (50-200 users): Option B. Reasons: B's pricing scales better at 200+ users, B's [specific feature] is unmatched, B's support response time is fastest. Tradeoff: B's onboarding is longer than Option A's. For under-50-user teams, Option A may serve better." + +**Weak defense.** + +- "B is the best choice." +- "Most teams choose B." +- Generic claims. + +The defense earns trust through specificity and acknowledged tradeoffs. + +--- + +## Audience-segment recommendations + +Different audiences may warrant different recommendations. + +**Patterns.** + +- "Solo and small teams: choose A." +- "Mid-market: choose B." +- "Enterprise: choose C." + +**Why this works.** Audiences self-identify; tool serves each. + +**The single-recommendation-fits-all failure.** One recommendation for diverse audiences misses fit. + +The discipline. When audiences differ, recommendations differ. + +--- + +## When the recommendation should be no-recommendation + +Sometimes "we cannot tell which is best for you" is the honest answer. + +**Patterns.** + +- "Both options fit teams in your situation; differentiator is [factor] you should weigh personally." +- "If [criterion] matters most to you, X. If [criterion] matters most, Y. We cannot rank for you." + +**Why this works.** Honest about the limits of recommendation; respects user agency. + +**The over-recommend failure.** Recommending in cases where genuine differentiator does not exist; trust suffers when users notice. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +**Disclosure patterns.** + +- "We weight [axes] heavily because [reasons]." +- "If you weigh different axes, your recommendation may differ." +- "Our methodology is described here." + +**The audience that questions.** Some users will dig. Methodology should hold up. + +--- + +## The recommendation-audit pattern + +Periodically test the tool's honesty. + +**Audit method.** + +- Test scenarios where competitors should win. +- Test scenarios where brand should win. +- Test edge cases. + +**Audit findings.** + +- Tool always recommends brand: hidden-recommendation; redesign. +- Tool sometimes recommends competitors: honest; verify the recommendations make sense. +- Tool refuses to recommend: may be appropriate for genuine ties; should not be default. + +The audit catches drift. Honest tools at launch can become hidden-recommendation through small changes over time. + +--- + +## Honest recommendation maintenance + +Honest recommendations decay. + +**What decays.** + +- Reasoning based on outdated capabilities. +- Audience-segment definitions that no longer fit. +- Methodology that no longer matches the tool's logic. + +**Maintenance cadence.** Quarterly review. Verify reasoning still holds; verify methodology matches implementation. + +--- + +## Common honest-recommendation failures + +**Brand always wins.** Hidden-recommendation; trust risk. + +**No defense.** Recommendations without reasoning. + +**Generic recommendations.** "Best for most teams" without specificity. + +**Single recommendation for diverse audiences.** Missed fit. + +**Tradeoffs hidden.** Brand presented as superior on all axes. + +**Methodology vague.** Users cannot inspect. + +**No competitor-strength acknowledgment.** Trust suffers. + +**Stale recommendation.** Reasoning based on outdated info. + +--- + +## Methodology-level choices that stay in the public skill + +The litmus test. Five marks of honest recommendation. Five marks of hidden recommendation. The acknowledge-competitor-strengths principle. Recommendation defense quality. Audience-segment recommendations. When no-recommendation is honest. Recommendation transparency. The audit pattern. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific recommendation logic for specific tools. Specific audience-segment mappings. Specific methodology copy. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/recommendation-engine-design.md b/skills/comparison-tool-design/references/recommendation-engine-design.md new file mode 100644 index 0000000..28b7c77 --- /dev/null +++ b/skills/comparison-tool-design/references/recommendation-engine-design.md @@ -0,0 +1,172 @@ +# Recommendation engine design + +When to recommend, how to defend, override path. + +Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible, visible, and not the only path. + +--- + +## The visible-defended-overridable principle + +Recommendations are most useful when: + +- Visible. Users can see what the tool recommends. +- Defended. Reasoning is explicit. +- Overridable. Users who weigh things differently can choose otherwise. + +**The win.** Tool recommends "Option B for mid-market teams prioritizing scale." Recommendation prominent; reasoning shown; user can switch audience or pick differently. + +**The fail.** Tool dumps features; user must decide alone. + +The discipline. Recommend with reasoning; respect override. + +--- + +## Recommendation patterns + +Common patterns. + +**Pattern A: Single recommendation.** "For [audience], choose [option] because [reasons]." Clear; opinionated. + +**Pattern B: Multi-segment recommendation.** "If [A], choose X. If [B], choose Y." + +**Pattern C: Conditional recommendation.** "If [factor] matters most, X. If [other], Y." + +**Pattern D: Recommendation with caveat.** "We think X fits most teams in your situation, with these caveats." + +**Pattern E: No recommendation.** Rarely the right choice. + +--- + +## Defending the recommendation + +The reasoning shown. + +**Strong defense.** Specific reasons tied to recommended option's strengths; audience-fit articulated; tradeoffs acknowledged. + +**Example.** "For mid-market teams: Option B. B's pricing scales better at 200+ users (X% vs Y%), B's integration with [tool] is faster, B's support response is shortest in this tier. Tradeoff: B's interface is less polished than Option A; A wins for teams under 50." + +**Weak defense.** "B is our recommendation"; "B is best for most teams"; generic claims. + +The defense earns trust through specificity. + +--- + +## The override path + +How users can choose otherwise. + +**Visible alternative paths.** + +- Toggle to switch recommended audience. +- Filter to weight axes differently. +- Direct selection of different option. + +**Friction balance.** + +- Override findable in 1-2 clicks. +- Override does not require restart. +- Override preserves user context. + +The discipline. Override is honest; users who disagree are not punished. + +--- + +## Recommendation framing + +How recommendations are worded. + +**Strong framing.** Specific to audience; tied to reasoning; acknowledges tradeoffs; inviting override. + +**Weak framing.** "Obviously X is best"; "most experts agree X"; "X is the only choice for serious teams." + +What works. Specificity, humility, agency for the user. + +--- + +## Audience-fit recommendations + +Different audiences may warrant different recommendations. + +**The pattern.** Tool detects or asks about audience; recommendation adapts. + +**Detection methods.** + +- Referrer or query. +- Stated input. +- Inferred from context. + +The discipline. Audience signals inform recommendation; do not stereotype. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +**Methodology disclosure.** + +- "We weight [axes] heavily because [reasons]." +- "If you weigh [factor] differently, your recommendation may differ." + +The audience that questions. Some users will dig; methodology should hold up. + +--- + +## The recommendation-bias risk + +Recommendations are powerful; biased ones damage trust. + +**Common biases.** + +- Recommending brand in all cases. +- Recommendations always benefit recommender. +- Hidden weighting toward brand strengths. + +**The trust-collapse.** When users catch bias, they stop trusting entirely. + +**The cure.** Acknowledge competitor strengths. Recommend competitors when fit warrants. Honest about who is recommending whom. + +--- + +## Recommendation testing + +Validate. + +**Methods.** + +- User research: do recommendations match what audiences would have chosen with full information? +- Cohort analysis: do recommendation-followers retain better? +- Sales feedback: do recommended-option leads convert at higher rates? + +The discipline. Recommendation is hypothesis until validated. + +--- + +## Common recommendation failures + +**No recommendation.** Tool lists; users decide alone. + +**Hidden recommendation.** Tool defaults bias toward one option without disclosure. + +**Generic recommendation.** "Best for most teams" without specificity. + +**Single recommendation for diverse audiences.** Missed fit. + +**Recommendation without defense.** Authoritative without reasoning. + +**No override path.** Users who disagree have no clear alternative. + +**Recommendation always favors brand.** Trust collapses. + +**Stale recommendation.** Reasoning based on outdated capabilities. + +--- + +## Methodology-level choices that stay in the public skill + +The visible-defended-overridable principle. Patterns A through E. Defending the recommendation. The override path. Framing. Audience-fit recommendations. Transparency. The bias risk. Testing. Common failures. + +## Implementation choices that stay internal + +Specific recommendation engines for specific tools. Specific audience-segment mappings. Specific reasoning copy. The team's validation processes. These vary by team. diff --git a/skills/competitor-experience-audit/SKILL.md b/skills/competitor-experience-audit/SKILL.md new file mode 100644 index 0000000..0eee8fd --- /dev/null +++ b/skills/competitor-experience-audit/SKILL.md @@ -0,0 +1,191 @@ +--- +name: competitor-experience-audit +description: "Audit the brand, UX, and site design of the leading sites in a vertical as a set of observable cross-site patterns, producing the experience bar a new build must meet or beat. Use this skill whenever the user wants to assess the competitive design field, capture vertical conventions, identify the design and UX bar of a category, or set the experience standard before a build. Triggers on competitor experience audit, UX audit, site design audit, brand audit, design conventions, what makes these sites good, vertical conventions, storefront patterns, merchandising patterns, layout density, primary task, design bar, category conventions, retail vs marketing register, what does the field do. Also triggers when an audit of the competitive field has captured technical signals (SEO, accessibility) but never named the brand, UX, or design conventions, and the build downstream will read as off-vertical without that bar." +category: research +catalog_summary: "Cross-site experience patterns and gaps across a vertical" +display_order: 6 +--- + +# Competitor Experience Audit + +Capture the brand, UX, and site design that the leading sites in a vertical observably share, and where they fall short. The output is the experience bar a new build must meet or beat, grounded in cross-site patterns rather than aesthetic opinion. + +Stack-agnostic. Works on any SiteShape (ecommerce-catalog, inventory-listing, hospitality-food, b2b-manufacturer, and so on). Auto-parts catalogs are the first test case, not the only target. + +This skill is the brand / UX / design counterpart to a technical audit like `seo-onpage` or `accessibility-audit`. Technical findings are objective (a missing canonical is missing). Design is more subjective, so this skill is deliberately written to make the subjective assessable: every dimension is judged by observable questions about what the leading sites actually do, reported as patterns and gaps, and marked `not_assessable` whenever the evidence does not support a judgment. + +--- + +## When to use + +- Setting the experience bar for a new build in a vertical you have not built in before +- Capturing the design and UX conventions a credible site in the category is expected to carry +- Auditing the competitive field for a critic or strategy review where SEO and accessibility have been covered but design and experience have not +- Naming the positioning opportunity that recurs across the leaders (the gap even the leaders share) +- Pairing with a technical audit (SEO, accessibility) so the competitor review captures both axes + +## When NOT to use + +- Rating a single page or one brand's design taste in isolation (use `design-standards` or `brand-style-guide` for production design decisions on a known build) +- Backlink, keyword, or SERP-overlap competitive analysis (use `seo-competitor`) +- Generating a creative direction from scratch for a new brand (use `creative-direction` and `brand-discovery`) +- User research with real participants on your own product (use `ux-research`, `usability-testing`) +- Auditing a single page's on-page SEO or accessibility against the audit suite (use `seo-onpage`, `accessibility-audit`) + +--- + +## Required inputs + +- The vertical and a list of the leading sites in it (3 to 6 sites; more than 6 stops surfacing new patterns) +- Access to the rendered sites (a real browser view, not just static HTML; see "Static vs rendered" below) +- The site shape the audit feeds, if known (ecommerce-catalog, inventory-listing, etc.); this scopes which dimensions to weight +- Any explicit constraint on the build downstream (the brand voice, the audience, the conversion the build will own) + +If the list of leading sites is unknown, ask. Picking the wrong field produces an experience bar against the wrong vertical. + +### Static vs rendered + +Some dimensions can be partially assessed from static HTML (primary navigation, the catalog/category surface count, the presence of search). Most cannot. Layout density, brand register, motion, trust-signal prominence, and the rendered hierarchy of the first viewport all need the rendered page to judge honestly. If you only have static HTML for a site, mark every rendered-only dimension `not_assessable` for that site rather than guessing. + +--- + +## The framework: 7 experience dimensions + +Each dimension is judged by observable questions across the leading sites in the field, then reported as a cross-site pattern plus the gap (where the leaders converge, and where even they fall short). + +Score each dimension as `Pattern present` (the field converges on a recognizable convention), `Mixed` (the field splits across two or three approaches), or `Gap` (no convention emerges, or every leader misses it). Mark `not_assessable` when the evidence cannot support a judgment. + +Never write `Good design` or `Bad design` or any aesthetic verdict. The dimensions are about what the field observably does, not whether you like it. + +### 1. Primary-task prominence + +Does the site lead with the visitor's primary job, or bury it? + +- What is the largest, earliest interactive element on the first viewport? (For auto-parts: typically a fitment selector. For hospitality-food: a menu or reservation entry.) +- How many clicks or scrolls to the core task? +- Does the site protect the primary task from competing CTAs in the hero? + +Observable signal: count the elements that compete for first attention, identify which one the layout actually privileges, name what the field converges on as the primary task. + +### 2. Layout register and density + +Is the layout retail-dense, editorial, or marketing-airy? Cross-reference `creative-direction` aesthetic positions (editorial restrained, polished standard, controlled maximalist, expressive maximalist) for vocabulary; do not redefine that here. + +- How many distinct modules appear above the fold? +- What is the content-per-viewport ratio (dense storefront, calm editorial, generous marketing)? +- Does the page read as a storefront, a catalog, a landing page, or a brochure? + +Observable signal: count modules above the fold across the field; describe the register the leaders share, not whether you find it attractive. + +### 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape? + +- How many category, collection, or entry-point modules appear before scroll? +- How is depth signaled (mega-menu, grid, side rail, faceted search)? +- Is the surface flat (one tier visible) or hierarchical (parent plus child categories shown together)? + +Observable signal: count the category entry points and describe the navigation depth pattern the field uses. + +### 4. Primary navigation and search paths + +Do the sites serve both the know-what-I-want path and the browse path? + +- Is search prominent and primary, secondary, or absent? +- What paths are offered (by category, by brand, by attribute, by vehicle, by location, by occasion)? +- Where does the primary nav sit (top, side, sticky, mega-menu)? + +Observable signal: list the paths the field offers, score whether each path is primary, secondary, or missing. + +### 5. Brand register and conviction + +What brand posture do the leading sites take, and is it consistent across the page? + +- Color, type, imagery: utilitarian, premium, friendly, institutional, technical, expressive? +- Voice in headings and microcopy: direct, persuasive, technical, warm, plain? +- Trust signals: institutional (long-standing, association badges), social (reviews, community), or operational (in-stock, warranty, fitment confirmation)? + +Cross-reference the `creative-direction` and `brand-archetype-system` skills for the vocabulary. Report the register the field converges on. Do not rate the taste; describe what posture the leaders take. + +### 6. Trust and conversion signals + +What recurring trust and conversion conventions does the field use? + +- Reviews, guarantees, social proof, badges +- Pricing transparency (price visible, no surprises, total cost surfaced) +- Stock and availability signals +- Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it) +- Return, shipping, or service-level promises + +Observable signal: which signals appear across the field, where they appear, and which the leaders share. + +### 7. Recurring vertical conventions (the synthesis) + +The patterns that recur across the leaders and define what a credible site in this vertical is expected to have. This is the synthesis of dimensions 1 through 6 into a short list of "if your build does not do this, it will read as off-vertical." + +Observable signal: which conventions recur on 3 of N or more of the leading sites; which are absent across the field (the gap that a positioning opportunity exploits). + +--- + +## The honesty guardrail (load-bearing) + +This is not negotiable. The credibility of an experience audit erodes the moment it slides into taste: + +- Report what the leading sites observably do and where they observably fall short, as cross-site patterns. Do not render personal aesthetic judgments ("this is ugly", "good design", "the typography is clean"). Aesthetic verdicts belong in `art-direction` or `design-standards`, not here. +- When the evidence does not support a judgment, say so plainly and mark the dimension `not_assessable` for that site or that pattern. Common cases: layout and density cannot be judged from un-rendered static HTML; motion and animation cannot be judged from a screenshot; brand voice cannot be judged from a single page. +- Do not name a convention from one site. A pattern is a recurrence across the field (3 of N or more); one site doing something distinctive is a single-site observation, not a convention. +- The output is a grounded experience bar: the conventions and gaps of the field, usable as a standard a build must meet. It is not an opinion piece. + +If the user asks "is this design good", redirect to observable patterns ("the leading sites in the field share X, Y, Z; this build does X and W but not Y or Z; that is the gap"). If the user asks for an aesthetic call, point them at `design-standards` or `art-direction`. + +--- + +## Workflow + +1. **Confirm the vertical and the leading sites.** Ask if either is unclear; an audit against the wrong field is worse than no audit. +2. **Render and view each site as a user would.** Open in a real browser, on the device class the field's visitors use (desktop and mobile for ecommerce; mobile-first for hospitality-food; etc.). Do not work from static HTML alone for any dimension marked rendered-only. +3. **Assess each dimension across the field.** Use [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) to score each site on each dimension. Mark `not_assessable` wherever the evidence is thin. +4. **Synthesize cross-site patterns.** For each dimension, name the recurring convention (or the split, or the gap). Distinguish patterns the field converges on from single-site moves. +5. **Name the gap (the positioning opportunity).** Where do even the leaders fall short? That is where a new build's positioning can exploit the field. +6. **Write the bar.** Use the template in [`references/audit-template.md`](references/audit-template.md). Default output is a markdown experience bar, generalized to pattern-level if it will feed a public showcase workup (no named competitors in the public version). +7. **Hand the bar to the build skills.** The output is the standard `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill (`landing-page-copy`, `frontend-component-build`) read as the experience bar to meet. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Rate the design of these sites."** Vague. Redirect to observable patterns: what the leading sites in the field do across the seven dimensions, not whether you like it. +- **Judging un-rendered pages for layout, density, or motion.** Mark `not_assessable` and get the rendered view. Static HTML supports only partial assessment; do not guess at design quality you cannot see. +- **Naming a convention from one site.** A pattern is a recurrence across the field. One site doing something distinctive is a single-site observation; flag it that way, not as a convention. +- **Substituting personal taste for field patterns.** "I think the colors are good" is not an audit finding. "The field converges on a navy-and-rust register; this site uses it" is. +- **Aesthetic verdicts dressed as observations.** Watch for "clean", "modern", "professional", "premium-feeling" with no observable signal underneath. If you cannot point at a specific observable thing, you are giving taste, not a pattern. +- **Skipping the gap.** An audit that names only what the leaders do well is half the value. The recurring weakness across the field is where a positioning opportunity lives; name it. +- **Generalizing too soon.** A 2-site sample is not the field. If you can only render 2 of 5 leaders, mark the audit `partial` and call out what is assessed vs what is not. + +--- + +## Output format + +Default output is a markdown experience bar at `experience-audit-[vertical-slug].md` in the project root. Structure: + +1. Vertical and the field surveyed (sites assessed, what could not be rendered) +2. Score per dimension across the field +3. Cross-site patterns (the conventions the leaders converge on) +4. Gaps (where the field falls short, the positioning opportunity) +5. The experience bar (the synthesis: what a credible build in this vertical must do) +6. `Not_assessable` items (what could not be judged and why) + +Keep the bar under 1500 words. If a dimension needs deeper treatment, link to a deeper appendix rather than expanding inline. + +### Scrub for showcase use + +If the audit will feed a public showcase workup, scrub for named competitors before publishing. The named version stays operated-side; the public workup carries the patterns and the gaps in generalized form. This mirrors how Basano's competitor review already handles named sites in its model-backed audit. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable experience-audit template, copy and use. Generalized and named variants both present. +- [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) - The observable questions per dimension, in scoring order. diff --git a/skills/competitor-experience-audit/references/audit-template.md b/skills/competitor-experience-audit/references/audit-template.md new file mode 100644 index 0000000..d244e9a --- /dev/null +++ b/skills/competitor-experience-audit/references/audit-template.md @@ -0,0 +1,136 @@ +# Competitor Experience Audit: [Vertical] + +**Site shape:** [ecommerce-catalog / inventory-listing / directory-marketplace / local-service-booking / subscription-app / hospitality-food / institution-mission / b2b-manufacturer / ecommerce-standout / hospitality-experience] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Field assessed:** [N sites] +**Rendered:** [N of N] **Static-only:** [N of N] + +--- + +## Field surveyed + +| Site | Rendered | Notes | +|---|---|---| +| [Site 1] | [yes/no] | [any access caveat] | +| [Site 2] | [yes/no] | | +| [Site 3] | [yes/no] | | +| [Site 4] | [yes/no] | | +| [Site 5] | [yes/no] | | + +If publishing the audit publicly, prepare a generalized version that drops the named column; the named version stays operated-side. + +--- + +## Summary + +[Two to three sentences. The cross-site picture: what the field converges on, where it falls short, what the positioning opportunity is. Generalized; no aesthetic verdicts.] + +| Dimension | Score | One-line pattern | +|---|---|---| +| Primary-task prominence | [Pattern present / Mixed / Gap / Not assessable] | | +| Layout register and density | | | +| Merchandising and category surface | | | +| Primary navigation and search paths | | | +| Brand register and conviction | | | +| Trust and conversion signals | | | +| Recurring vertical conventions | | | + +--- + +## Cross-site patterns + +### 1. Primary-task prominence + +[What the field converges on as the primary task; what element carries it; how protected the task is from competing CTAs. Observable signal: what is the largest, earliest interactive element, and what is the click count to the core task.] + +**Pattern:** [The field's convention] +**Outliers:** [Any leader that breaks the pattern, and what they do instead] + +### 2. Layout register and density + +[The register the field shares (retail-dense, editorial, marketing-airy, hybrid). Cross-reference `creative-direction` aesthetic positions for vocabulary.] + +**Pattern:** [The field's register] +**Outliers:** [Any leader that uses a different register] + +### 3. Merchandising and category surface + +[How much of the offering is surfaced before scroll; the navigation depth pattern; mega-menu vs grid vs side rail.] + +**Pattern:** +**Outliers:** + +### 4. Primary navigation and search paths + +[Which paths the field offers (search-first, by-category, by-brand, by-attribute, by-vehicle, by-location). Score each path as primary / secondary / absent.] + +**Pattern:** +**Outliers:** + +### 5. Brand register and conviction + +[The brand posture the leaders converge on. Cross-reference `creative-direction` and `brand-archetype-system`.] + +**Pattern:** +**Outliers:** + +### 6. Trust and conversion signals + +[Which signals appear across the field (reviews, guarantees, pricing transparency, stock, fitment confirmation, return policy). Where they appear.] + +**Pattern:** +**Outliers:** + +### 7. Recurring vertical conventions + +[The synthesis. The conventions a credible site in this vertical is expected to have, named explicitly. A build that ignores these will read as off-vertical.] + +**Conventions:** +- [Convention 1] +- [Convention 2] +- [Convention 3] +- ... + +--- + +## Gaps (the positioning opportunity) + +[Where even the leaders fall short. The recurring weakness across the field. This is the wedge a new build's positioning can exploit. Observable, not speculative.] + +- **[Gap 1]:** [The weakness the field shares; how it shows up across N of the N leaders; what a build that fixes it would look like.] +- **[Gap 2]:** +- **[Gap 3]:** + +--- + +## The experience bar (the build standard) + +A credible build in this vertical, against this field, must: + +- [Bar item 1 - usually maps to a recurring convention from dimension 7] +- [Bar item 2] +- [Bar item 3] +- ... + +Optional positioning move: + +- [The build's wedge - exploit one or more of the gaps above] + +Hand this bar to `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill so they read as the standard to meet, not as suggestions. + +--- + +## Not assessable + +[Dimensions or sites that could not be judged honestly. Common reasons: site not renderable, motion not capturable, brand voice not derivable from a single page, depth of the category surface only visible after authentication.] + +- **[Dimension or site]:** [Why it cannot be judged from the evidence available. What evidence would be needed to assess it.] +- **[Dimension or site]:** +- ... + +--- + +## Generalized version (for showcase / public use) + +If this audit will feed a public showcase workup or a published critique, copy the sections above into a generalized form that drops the named-competitor column and the Outliers callouts. Patterns and gaps are publishable; named-and-rated competitor breakdowns are not. The named version stays operated-side. diff --git a/skills/competitor-experience-audit/references/experience-dimensions-checklist.md b/skills/competitor-experience-audit/references/experience-dimensions-checklist.md new file mode 100644 index 0000000..8313356 --- /dev/null +++ b/skills/competitor-experience-audit/references/experience-dimensions-checklist.md @@ -0,0 +1,134 @@ +# Experience Dimensions Checklist + +Score each leading site on each dimension using the observable questions below. Mark `not_assessable` whenever the evidence does not support a judgment; do not guess. The audit's value rests on honest observation. + +The rule for every dimension: name what is observably true across the field, not whether you like it. If you cannot point at a specific observable thing, you are giving taste, not a pattern. + +--- + +## 1. Primary-task prominence + +The visitor arrives with a primary job. The leading sites either lead with that job or bury it. + +- [ ] What is the largest, earliest interactive element on the first viewport? +- [ ] Does that element correspond to the visitor's primary task in the vertical? (Auto-parts: a fitment selector. Hospitality-food: a menu or reservation entry. Inventory-listing: a search or filter. Local-service-booking: a "book now" or service picker.) +- [ ] How many clicks or scrolls from arrival to completing the core task? +- [ ] How many competing CTAs share the hero with the primary task? +- [ ] Is the primary task reachable from a sticky element on scroll? + +Rendered required: **partial.** The primary task can usually be identified from a static fetch (it is in the markup), but its visual dominance and protection from competitors requires the rendered view. + +--- + +## 2. Layout register and density + +Storefront, editorial, marketing-airy, hybrid. Cross-reference `creative-direction` aesthetic positions (editorial-restrained, polished-standard, controlled-maximalist, expressive-maximalist) for vocabulary. + +- [ ] How many distinct modules appear above the fold on a standard desktop viewport? +- [ ] How many on a mobile viewport? +- [ ] What is the content-per-viewport ratio: dense (a catalog or storefront), calm (an editorial), generous (a landing page or brochure)? +- [ ] Where does the page read as a storefront vs a marketing page? +- [ ] Does the whitespace ratio match a retail or a publication register? + +Rendered required: **yes.** Static HTML cannot tell you what users see in the first viewport. + +--- + +## 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape. + +- [ ] How many category, collection, or entry-point modules appear before scroll? +- [ ] How is depth signaled (mega-menu hover, fly-out, side rail, faceted search, breadcrumb expansion)? +- [ ] Is the surface flat (one tier visible) or hierarchical (parent plus child)? +- [ ] Are the categories shown as text, icon, image, or hybrid? +- [ ] Is a search-first path offered alongside the category-first path? + +Rendered required: **partial.** Counts and structure show up in static markup; visual emphasis and reveal patterns need rendering. + +--- + +## 4. Primary navigation and search paths + +The know-what-I-want path and the browse path. Both, or only one. + +- [ ] Is a search input prominent (in the header, large input), secondary (small, in a side panel), or absent? +- [ ] Which paths does the primary nav offer (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience)? +- [ ] Score each available path: primary / secondary / absent. +- [ ] Where does the primary nav sit (top bar, side drawer, mega-menu, sticky)? +- [ ] On mobile, does the primary nav collapse into a hamburger or stay flat? + +Rendered required: **partial.** Path inventory is in the static markup; visual prominence and primary-vs-secondary judgment needs the rendered view. + +--- + +## 5. Brand register and conviction + +The posture the leading sites take and whether they hold it across the page. + +- [ ] Color palette: muted / saturated; warm / cool; monochrome / multi-hue. +- [ ] Typography: humanist / geometric / serif-led / display-led; one face or paired. +- [ ] Imagery: photographic (studio, lifestyle, editorial); illustrated; abstract; none. +- [ ] Voice in headings: direct, persuasive, technical, warm, plain, institutional. +- [ ] Voice in microcopy and CTAs: matches the heading voice or breaks from it. +- [ ] Brand posture: utilitarian / premium / friendly / institutional / technical / expressive. + +Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; use those terms rather than inventing new ones. + +Rendered required: **yes.** Brand register is a visual judgment; static HTML alone cannot support it. + +--- + +## 6. Trust and conversion signals + +The recurring conventions a credible commercial page in this vertical carries. + +- [ ] Reviews / ratings present (where, how prominent, count or average shown). +- [ ] Guarantees (return policy, money-back, warranty) surfaced or hidden. +- [ ] Pricing transparency: price visible without interaction; total cost surfaced before checkout; "starting at" or full? +- [ ] Stock or availability signals (in stock, low stock, lead time). +- [ ] Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it). +- [ ] Shipping or service-level promises (ETA, free over $X, same-day). +- [ ] Institutional trust signals (years in business, association badges, certifications). +- [ ] Social proof (logos of customers, press mentions, testimonials). + +Rendered required: **partial.** Many trust signals are visible in markup; placement and emphasis are rendered judgments. + +--- + +## 7. Recurring vertical conventions (synthesis) + +The patterns that recur across the field define what a credible site in this vertical is expected to have. This is not a new measurement; it is the synthesis of dimensions 1 through 6. + +- [ ] Which conventions appear on 3 of N or more of the leaders? +- [ ] Which appear on fewer than 3 (single-site moves, not conventions)? +- [ ] Which are absent across the field (the gap a positioning opportunity exploits)? + +The output of this dimension is a short list: "If your build does not do X, Y, Z, it will read as off-vertical." That list is what goes into the experience bar. + +--- + +## Scoring rubric + +For each dimension, score the field (not a single site): + +- **Pattern present.** 3 of N or more leaders converge on a recognizable convention. Name it. +- **Mixed.** The field splits across two or three distinct approaches. Name each, and note which the new build should adopt. +- **Gap.** No convention emerges, or every leader misses the dimension. Often this is the positioning opportunity. +- **Not assessable.** The evidence does not support a judgment. Name what evidence would be needed. + +For each site (operated-side only; the public version drops named scores): + +- Mark each dimension `pattern-aligned`, `outlier`, or `not assessable`. + +--- + +## What this checklist will not do + +- Rate a single site's design taste. Use `design-standards` for production design review. +- Tell you which vertical your build belongs in. The vertical and field are inputs to this skill, not outputs. +- Replace user research. Use `ux-research` and `usability-testing` for real-user assessment. +- Generate creative direction from scratch. Use `creative-direction` and `brand-discovery` for that. +- Produce a SERP or backlink competitive analysis. Use `seo-competitor`. + +This checklist names patterns and gaps so a downstream build has a real bar to meet. Everything else is out of scope. diff --git a/skills/content-and-copy/SKILL.md b/skills/content-and-copy/SKILL.md new file mode 100644 index 0000000..e8a1f80 --- /dev/null +++ b/skills/content-and-copy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: content-and-copy +description: "Write or edit website copy, blog content, and editorial pieces with attention to voice, structure, and goal. Use this skill whenever the user wants to write an article, draft website copy, edit existing content for clarity or voice, write a blog post, or produce general editorial content. Triggers on write a blog post, draft an article, write copy for, edit this, rewrite this, write content, write a guide, draft a how-to, write web copy. Also triggers when content has been outlined and now needs to be written, or when existing content needs voice or clarity edits." +category: content +catalog_summary: "Website copy, blog content, content production frameworks" +display_order: 3 +--- + +# Content and Copy + +Write or edit content that serves a specific reader and goal. Stack-agnostic. This skill is for general content production. Specialized skills exist for landing pages (`landing-page-copy`) and email (`email-sequences`). + +--- + +## When to use + +- Writing a blog post or article +- Drafting website copy (homepage sections, about, services) +- Editing existing content for voice or clarity +- Writing how-to guides, listicles, or explainers +- Producing knowledge base or help center articles +- Adapting brand voice to a specific piece + +## When NOT to use + +- Landing pages with conversion goals (use `landing-page-copy`) +- Email campaigns or sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- SEO keyword research (use `seo-keyword`) +- Content strategy and planning (use `content-strategy`) + +--- + +## Required inputs + +- The piece to be written or edited +- The target reader (specific audience segment) +- The goal of the piece (inform, convert, rank, retain, entertain) +- The brand voice (or willingness to define it) +- Length target and any structural constraints + +If brand voice is undefined, run `brand-voice` first or use a working voice and document it as you go. + +--- + +## The framework: 5 dimensions + +Strong content is strong on all five. Weakness on any one drags the rest down. + +### 1. Hook + +The opening earns the read. Most readers decide whether to continue within 3 to 5 seconds. + +**Strong hooks do one of:** + +- **Promise specific value.** "By the end, you'll know exactly which X to pick for your situation." +- **Surface a tension.** "Most advice on X is wrong. Here's why." +- **Open a loop.** A question or scenario the rest of the piece resolves. +- **State a contrarian point.** Provided you can defend it. +- **Show, don't summarize.** A specific moment or scenario the reader recognizes. + +**Weak hooks:** + +- Throat-clearing ("In today's fast-paced world...") +- Dictionary-definition openers ("X is a type of Y that...") +- Stating the obvious ("Many people struggle with X.") +- Vague promises ("This article will explore X.") + +### 2. Structure + +The reader follows the flow without effort. + +**Common structures:** + +- **Problem → Solution → Proof.** Most non-fiction. +- **List + reasoning.** Listicles with substance, not filler. +- **How-to (numbered steps).** Procedural content. +- **Compare → Contrast → Recommend.** Comparison and review content. +- **Story → Lesson.** Narrative non-fiction. +- **Question → Answer → Implication.** Explainers and analysis. + +Pick a structure. Stick to it. Most weak content fails because the writer drifted between structures. + +### 3. Voice + +The piece sounds like the brand. + +- Voice attributes consistent throughout (per `brand-voice` definition) +- Tone shifts appropriately for context (a serious topic gets a serious tone, even from a playful brand) +- Vocabulary preferences honored +- Grammar and style standards followed (contractions, em dashes, sentence length) +- Reads aloud like the brand would actually talk + +**Test:** Read a paragraph aloud. Does it sound like the brand? If it sounds like AI, generic marketing, or someone else's voice, edit until it doesn't. + +### 4. Substance + +The piece earns its length. Every paragraph adds something. + +**Substance comes from:** + +- **Specifics.** "Roughly 40 percent" beats "many." Names, numbers, examples, data. +- **Original perspective.** Your take, not a summary of everyone else's. +- **Actionable detail.** What the reader does with this information. +- **Honest tradeoffs.** What's NOT true, what doesn't work, what's overhyped. +- **Real examples.** Specific scenarios, real customers, real failures. + +**Lack of substance shows up as:** + +- Padding ("It's important to note that...") +- Restating the same point in three different paragraphs +- Generalities that anyone in the category could write +- Word counts hit by stretching, not depth + +### 5. Closing + +The piece ends with intention. + +**Strong closings:** + +- **Resolve the loop opened in the hook.** +- **Issue a specific next action.** What does the reader do now? +- **Land a memorable line.** Something quotable. +- **Return to the opening.** Echo or invert the first line. + +**Weak closings:** + +- Summary that restates the article +- "Hope this helps!" or equivalent +- A wall of CTAs from unrelated programs +- Trailing off with no clear ending + +--- + +## Workflow + +### For new pieces + +1. **Confirm the brief.** Reader, goal, length, voice. If the brief is vague, do not write yet. +2. **Outline.** Structure first. Headlines and section purposes only. Skip prose until the structure is sound. +3. **Open with the hook.** Write the opening before anything else. If the hook isn't working, the rest won't either. +4. **Draft for substance.** First draft is about getting the substance down. Voice comes in editing. +5. **Edit for voice.** Read aloud. Tighten sentences. Cut padding. Apply brand voice. +6. **Edit for clarity.** Each paragraph: does it earn its place? Each sentence: is the meaning unambiguous? +7. **Pre-publish checks.** Headers in order, no skipped levels, internal links present, image alt text written, SEO basics applied (title, meta, slug). + +### For editing existing content + +1. **Read the whole piece first.** Do not edit on first read. Understand it before changing it. +2. **Identify what's working.** Note the strong sections so you don't damage them. +3. **Identify what's broken.** Voice mismatches, weak structure, vague claims, padding. +4. **Edit by priority.** Structure first (move sections, cut sections). Then substance (strengthen claims). Then voice. Then sentence-level polish. +5. **Read aloud.** Catch awkward phrasing the eye misses. + +--- + +## Failure patterns + +- **Writing without a brief.** Without reader, goal, and voice defined, the piece drifts. +- **Burying the lead.** The most important thing is in paragraph 8 because the writer "got there." +- **Padding to hit word count.** Length should serve the reader, not the production schedule. +- **Generic voice.** Sounds like every other article in the category. Brand voice neutralized. +- **Weak transitions.** Sections feel disconnected. Reader has to do the work the writer should have done. +- **No closing.** The piece runs out instead of ending. +- **Edit by adding.** Fixing weak content by piling on more words. Strong editing usually cuts. +- **Ignoring the headers.** Headers carry navigation weight. Bad headers fail readers who scan. + +--- + +## Output format + +Default output is a markdown document at `[content-slug].md` ready to import into the CMS. + +Structure: +```markdown +# [H1: matches the title or tightly paraphrases] + +[Hook paragraph. Earns the read in 3 to 5 seconds.] + +[Body content with H2 sections, H3 subsections where useful.] + +## [H2 section heading - descriptive, not clever] + +[Section content.] + +### [H3 if needed] + +[Subsection content.] + +## [H2 section heading] + +[Section content.] + +## [Closing section] + +[Closing that resolves and points to next action.] +``` + +Front-matter for SEO and CMS: +```yaml +--- +title: [SEO title, 50 to 60 chars] +description: [Meta description, 120 to 160 chars] +slug: [url-slug] +author: [author] +date: [YYYY-MM-DD] +last_updated: [YYYY-MM-DD] +tags: [tag1, tag2] +category: [category] +--- +``` + +--- + +## Reference files + +- [`references/content-brief-template.md`](references/content-brief-template.md) - The brief that should exist before any content is written. +- [`references/content-edit-checklist.md`](references/content-edit-checklist.md) - Pre-publish editing checklist. diff --git a/skills/content-and-copy/references/content-brief-template.md b/skills/content-and-copy/references/content-brief-template.md new file mode 100644 index 0000000..d1bc428 --- /dev/null +++ b/skills/content-and-copy/references/content-brief-template.md @@ -0,0 +1,242 @@ +# Content Brief Template + +Every piece of content needs a brief before writing. Without one, the piece will drift, miss the audience, or fail the goal. + +A brief takes 15 minutes to write. Saves hours of rewrites later. + +--- + +## Template + +```markdown +# Brief: [Working title] + +## Reader + +Who specifically is this for? Be precise. + +- Primary audience segment: [from content strategy] +- What they currently know: [their starting point] +- What they want to know: [the question they're bringing] +- What they need to do after: [the action this enables] + +## Goal + +What does this piece accomplish? + +- Primary goal: [Inform / Convert / Rank / Retain / Entertain] +- Specific outcome: [What measurable thing should happen] +- Success metric: [How we know it worked] + +## Pillar / Strategy fit + +- Content pillar this serves: [from content strategy] +- Cornerstone or supporting: [Cornerstone / Supporting] +- Internal links to / from: [related pieces] + +## Angle + +What's the take? Why does this piece exist when others on the topic already do? + +- The angle: [One sentence] +- Why ours is different: [Specific differentiator] +- The contrarian or surprising element: [If any] + +## Format + +- Type: [Article / Guide / Listicle / Comparison / Case study / How-to / Tutorial / Explainer] +- Length: [Word count or range] +- Reading level: [Beginner / Intermediate / Advanced] +- Required elements: [Images, tables, video, downloads, code blocks] + +## Structure + +Section-by-section outline. Headlines + 1 sentence on what each section does. + +### [H1: Working title] + +[Hook approach: how the piece will earn the read in 3 to 5 seconds] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Closing section] +[How the piece resolves and what action it points to] + +## Voice + +- Apply: [Brand voice attributes] +- Tone for this piece: [How tone adjusts for the topic] +- Specific cues: [Anything to lean into or avoid for this topic] + +## Sources and citations + +- Required sources: [Specific data, studies, or experts to cite] +- Internal data: [Anything we have that competitors don't] +- Quotes from: [SMEs, customers, founders to include] + +## SEO + +- Primary keyword: [from keyword research] +- Secondary keywords: [supporting terms] +- Search intent: [Informational / Commercial / Transactional / Navigational] +- Target SERP feature (if any): [Featured snippet / People also ask / etc.] +- Title tag (50-60 chars): [Draft] +- Meta description (120-160 chars): [Draft] +- URL slug: [Draft] + +## Distribution + +Where and how this piece gets seen after publishing. + +- Newsletter inclusion: [Yes/No] +- Social posts: [Number of variations and channels] +- Outreach: [Specific people or sites to ping] +- Internal links to add from: [Existing pieces that should link to this] + +## Constraints and notes + +- Deadline: [Date] +- Word count: [Target] +- Required approvals: [Who needs to sign off] +- Things to avoid: [Anything off-limits for this piece] + +## Out of scope + +What this piece is explicitly NOT about. Prevents scope creep during writing. + +- [Topic not in this piece] +- [Topic not in this piece] +``` + +--- + +## Filled example + +```markdown +# Brief: How to choose between SQL and NoSQL for a startup + +## Reader + +- Primary audience segment: Technical founders or first engineers at early-stage startups (under 20 employees) +- What they currently know: Basics of databases, used both SQL and NoSQL casually +- What they want to know: Which to pick for their specific situation, what they'll regret in 18 months +- What they need to do after: Make the database choice and feel confident enough to commit + +## Goal + +- Primary goal: Inform (with rank as a secondary) +- Specific outcome: Reader makes the decision and references this piece when others ask +- Success metric: Top 3 ranking on "SQL vs NoSQL for startups" within 6 months; 5+ minute average read time + +## Pillar / Strategy fit + +- Content pillar: Startup engineering decisions +- Cornerstone or supporting: Cornerstone for the pillar +- Internal links: from "Founder's guide to technical debt" and to "When to migrate your database" + +## Angle + +- The angle: Most articles compare SQL and NoSQL on technical features. We compare on regret-likelihood at 18 months in production. +- Why ours is different: Built around real failure modes, not theoretical capabilities +- Surprising element: Most startups regret choosing NoSQL for the wrong reasons, not the right ones + +## Format + +- Type: Long-form decision guide +- Length: 2,500 to 3,500 words +- Reading level: Intermediate +- Required elements: Decision flowchart, 2-3 case examples, comparison table + +## Structure + +### H1: How to choose between SQL and NoSQL for a startup + +Hook: Open with a specific founder's regret moment from a real conversation. + +### H2: The wrong question (and the right one) +Most teams ask "which is faster" or "which scales." Reframe to "what will I regret in 18 months." + +### H2: When SQL is the right call +Specific scenarios with examples. + +### H2: When NoSQL is the right call +Narrower scenarios than most articles claim. + +### H2: The hybrid that works +Real-world pattern: SQL primary, targeted NoSQL for specific use cases. + +### H2: A decision flowchart +The actionable diagram. The piece's main asset. + +### H2: What to do if you've already chosen wrong +Migration realism, with specific signals it's time to switch. + +### H2: Closing +Return to the opening founder. Where they ended up. The decision framework as the takeaway. + +## Voice + +- Apply: Direct, experienced, not-academic +- Tone: Slightly weary about industry overcomplication +- Specific cues: First-person plural ("we"), war-story examples preferred over textbook explanations + +## Sources + +- Internal: Conversations with [N] startup CTOs +- External: [List of specific studies, posts, papers] +- Quotes: [Names if any] + +## SEO + +- Primary keyword: SQL vs NoSQL startup +- Secondary: SQL vs NoSQL for small teams, when to use NoSQL, NoSQL mistakes startups +- Search intent: Informational with commercial undertone +- Target SERP feature: Featured snippet for "when to use NoSQL" +- Title tag: SQL vs NoSQL for Startups: How to Avoid 18-Month Regret +- Meta: A practical guide to picking a database when you're 5 engineers, deciding fast, and don't want to migrate twice. Includes a decision flowchart. +- URL slug: sql-vs-nosql-startup + +## Distribution + +- Newsletter: Feature in next issue +- Social: 3 LinkedIn variations, 1 X thread +- Outreach: Email to 5 startup engineering newsletter writers +- Internal links: Add from /resources/cto-decisions and /technical-debt-guide + +## Constraints + +- Deadline: [Date] +- Word count: 3,000 target +- Approvals: Editorial lead and one technical SME +- Avoid: Vendor-specific recommendations (we're not selling a product) + +## Out of scope + +- Specific NoSQL database comparisons (CouchDB vs MongoDB) - separate piece +- Schema design tutorials - separate piece +- ORM choice - separate piece +``` + +--- + +## When to skip the brief + +The brief is required for: +- Cornerstone content +- Anything over 1500 words +- Anything with a conversion goal +- Anything written by someone other than the editorial lead + +The brief can be lighter for: +- Short newsletter blurbs +- Social posts +- Pieces written by the editorial lead with the strategy fully internalized + +But "lighter" is not "absent." Even a 100-word note covering reader / goal / angle saves time. diff --git a/skills/content-and-copy/references/content-edit-checklist.md b/skills/content-and-copy/references/content-edit-checklist.md new file mode 100644 index 0000000..4e1f906 --- /dev/null +++ b/skills/content-and-copy/references/content-edit-checklist.md @@ -0,0 +1,147 @@ +# Content Edit Checklist + +A pre-publish checklist for editing content. Run it line by line before any piece of content goes live. + +The checklist catches the regular mistakes. Editing for substance is a separate pass. + +--- + +## Pass 1: substance + +Before sweating commas, confirm the piece does its job. + +- [ ] **The brief is satisfied.** Re-read the content brief. Does this piece deliver against every objective? +- [ ] **The audience is the right one.** Who is the reader? Are they assumed correctly? +- [ ] **The single takeaway is clear.** If a reader skims and remembers one thing, what is it? Is it what we wanted? +- [ ] **The first 50 words earn the next 50.** Cut throat-clearing intros. Get to the point. +- [ ] **Every paragraph earns its place.** If a paragraph could be removed without loss, remove it. +- [ ] **The structure serves the reader.** Headers form a meaningful outline. Skim test passes. +- [ ] **There is one CTA per piece, and it is unmissable.** Or zero, if the piece is purely informational. +- [ ] **No claim is unsupported.** Every fact, statistic, or assertion has a source or is hedged. +- [ ] **Examples are concrete.** Specific numbers, named scenarios, real artifacts beat vague "many users" generalizations. + +--- + +## Pass 2: voice and tone + +- [ ] **Voice matches the brand voice document.** Read aloud. If a stranger could not place this as our brand, voice is too generic. +- [ ] **Tone matches the context.** Promotional vs editorial vs technical vs support. Different content, different tone shifts. +- [ ] **Pronouns are consistent.** "You" / "we" / "our" stay stable across the piece. +- [ ] **No internal voice leaked into customer-facing copy.** Jargon, project names, internal team names removed. +- [ ] **No first-person commentary in instructional content.** ("I think you should..." → "Do this because...") + +--- + +## Pass 3: structure and scannability + +- [ ] **Headings are descriptive, not clever.** "How to add a payment method" beats "Money matters." +- [ ] **Heading hierarchy is correct.** One H1, then H2s for top-level sections, H3s under H2s. No skipping levels. +- [ ] **Paragraphs are tight.** Default 2-4 sentences per paragraph for web. One-sentence paragraphs are allowed for emphasis. +- [ ] **Lists are used where they fit.** Bullets for parallel items, numbered for sequenced steps. +- [ ] **Bold and italic used sparingly.** Bold for the term being defined, italic for emphasis. Not both. Not often. +- [ ] **Code blocks for code.** Inline code for short references. +- [ ] **Tables for tabular data.** Not for layout. + +--- + +## Pass 4: clarity at the sentence level + +- [ ] **Active voice by default.** Passive voice for specific reasons (focus on object, unknown actor, polite distancing). +- [ ] **Concrete nouns and verbs.** "We process" beats "processing is performed by us." +- [ ] **Average sentence length under 20 words.** Vary the rhythm with shorter sentences for emphasis. +- [ ] **No nominalizations.** "Decide" beats "make a decision." "Implement" beats "carry out the implementation of." +- [ ] **No throat-clearing phrases.** Cut "It is important to note that," "In order to," "At the end of the day." +- [ ] **No filler intensifiers.** Cut "very," "really," "quite," "actually," "basically." Each weakens the word it modifies. +- [ ] **No hedge words where you mean something specific.** "May," "might," "could" are honest when uncertain, weak when specific. + +--- + +## Pass 5: jargon and accessibility + +- [ ] **Jargon defined on first use.** Or replaced if the audience would not know it. +- [ ] **Acronyms spelled out on first use.** Then acronym is fine. +- [ ] **No insider language.** Project codenames, internal team references, deprecated product names. +- [ ] **Idioms checked for global audiences.** "Hit it out of the park" reads strange to non-US English readers. +- [ ] **Reading level appropriate.** Use a tool (Hemingway, Readable) to spot-check. For most audiences, target Grade 8-10. +- [ ] **No ableist or exclusionary language.** "Crazy" → "wild," "blacklist" → "blocklist," gendered defaults checked. + +--- + +## Pass 6: SEO basics + +If the piece is for organic search: + +- [ ] **Primary query target identified.** One phrase per piece. +- [ ] **Title tag drafted.** Distinct from H1, 50-60 characters, primary query near front. +- [ ] **Meta description drafted.** 140-160 characters, value-led, includes primary query naturally. +- [ ] **H1 is unique on the site and includes the primary query.** +- [ ] **Internal links added.** 2-5 contextual links to related content on the site. +- [ ] **External links added.** Link out where it adds value or substantiates a claim. +- [ ] **Images have descriptive alt text.** Decorative images get `alt=""`. +- [ ] **URL slug is short, lowercase, hyphenated, includes primary query.** +- [ ] **Schema considered.** Article, FAQ, HowTo, etc. - whichever fits the format. + +--- + +## Pass 7: facts and claims + +- [ ] **Numbers verified.** Especially statistics, dates, prices, version numbers. +- [ ] **Names spelled correctly.** People, products, companies, places. +- [ ] **Quotes verified verbatim.** Speaker name, attribution, context correct. +- [ ] **Dates checked.** "Last updated" reflects the actual edit date. +- [ ] **Links work and go where they say.** No 404s, no redirect chains, no link rot to dead resources. +- [ ] **Screenshots are current.** Older screenshots show outdated UI; refresh or remove. +- [ ] **Claims about competitors are fair and current.** Or removed. + +--- + +## Pass 8: legal and compliance + +- [ ] **Trademarked terms used correctly.** Capitalization, ™ or ® where required by license. +- [ ] **Disclaimers present where needed.** Affiliate disclosures, regulated industry disclaimers, advisory caveats. +- [ ] **Customer permissions secured for testimonials.** Case studies, quotes, photos. +- [ ] **No confidential or pre-announcement information.** Product roadmaps, unannounced pricing, internal team names. +- [ ] **Image rights clear.** Licensed stock, original photography, or in-house illustration. + +--- + +## Pass 9: cross-channel consistency + +If the piece appears in more than one place: + +- [ ] **Web vs email vs social variants align in message.** Tone may shift; substance does not contradict. +- [ ] **Excerpts and meta descriptions match the piece.** No bait-and-switch. +- [ ] **CTAs point to current destinations.** Landing page is live, has matching messaging, is not stale. + +--- + +## Pass 10: final mechanical sweep + +- [ ] **Spellcheck.** Twice. Once with autocorrect off so it does not silently fix names. +- [ ] **Grammar check.** Tool-assisted, then human-verified. +- [ ] **Punctuation consistent.** Oxford comma, smart quotes, dashes - per the style guide. +- [ ] **No double spaces.** Find-and-replace. +- [ ] **No trailing whitespace at line ends.** +- [ ] **No placeholder text left in.** "Lorem ipsum," "TBD," "[INSERT QUOTE]," "TKTK." +- [ ] **No commented-out drafts in the source.** Especially in CMS HTML view. + +--- + +## Sign-off + +| Pass | Editor | Date | +|---|---|---| +| Substance | | | +| Voice and tone | | | +| Structure | | | +| Sentence-level | | | +| Jargon and accessibility | | | +| SEO | | | +| Facts and claims | | | +| Legal and compliance | | | +| Cross-channel | | | +| Mechanical | | | + +Final approval: [Name, date] + +Ready to publish: [ ] diff --git a/skills/content-brief-authoring/SKILL.md b/skills/content-brief-authoring/SKILL.md new file mode 100644 index 0000000..85733df --- /dev/null +++ b/skills/content-brief-authoring/SKILL.md @@ -0,0 +1,252 @@ +--- +name: content-brief-authoring +description: "How to author a content brief that actually guides a writer (human or AI) to produce a piece that ranks, converts, or both. Per-piece editorial brief: target keyword and cluster, search intent, audience and JTBD, heading structure, entity coverage for AEO/GEO, internal linking strategy, success criteria. The middle path between thin briefs (a keyword and a deadline) and thick briefs (a 4-page document nobody reads). Triggers on content brief, brief the writer, brief the article, brief authoring, content brief template, brief audit, per-piece brief, editorial brief, target keyword brief, search intent brief. Also triggers when briefing a human writer or an AI agent on a single content piece." +category: content +catalog_summary: "Per-piece editorial brief: target keyword, intent, audience, outline, entity coverage, internal linking, success criteria, and the discipline that distinguishes useful briefs from bloat" +display_order: 2 +--- + +# Content Brief Authoring + +A senior content strategist's playbook for authoring per-piece content briefs that actually guide writers to produce content worth publishing. + +Most content briefs are some flavor of broken. The thin version is a keyword, a word count, and a deadline; the writer fills in everything else from scratch and the output is generic. The thick version is a 4-page document nobody reads, that the writer skims for the headline and the outline and ignores the rest. Either way, the brief failed at its job: making the writer's work easier and the output more predictable. + +This skill is the middle path. It defines the 12 fields that earn their keep in a content brief, the fields that bloat without helping, and the discipline of writing briefs that route a writer (human or AI) toward a content piece that ranks for its target keyword, gets cited by AI engines, converts the right reader, or whatever the success criteria say. It assumes you have decided what to write (see `content-strategy` for program-level decisions) and now you are briefing each piece. The piece itself gets written separately (see `content-and-copy`). + +When to use this skill: briefing a writer (human or AI) on an individual content piece, auditing existing briefs that are not producing good content, building a brief template for a content program, or running a brief-generation pipeline through Frase, AirOps, or another tool. + +--- + +## What this skill is for + +This skill spans the per-piece editorial brief discipline. It composes with three sister skills, and the distinction between them is what keeps each one sharp. + +- `creative-brief` is a project brief. It bridges discovery to execution at the project level: a new website, app, brand, or campaign. Audience, goals, scope, success at project scope. +- `content-strategy` is a program-level editorial strategy. Pillars, calendar, topic clusters, governance. What to produce across a quarter or a year. +- `content-and-copy` is the writing itself. Voice, structure, edit pass, tone calibration. Execution scope for general editorial. +- This skill is the per-piece brief between `content-strategy` (program decided) and `content-and-copy` (piece gets written). It briefs a single content artifact: keyword, intent, audience, outline, entities, success criteria. + +The clean reading order: `content-strategy` decides what to produce; this skill briefs each piece; `content-and-copy` writes it. If the team is briefing a redesign or a new brand build, that is `creative-brief`, not this skill. + +The audience: content strategists, SEO content marketers, editorial leads, content ops managers, agencies running content programs at scale, and any PM or marketer briefing a writer (human or AI). The voice is senior content strategist to junior content marketer. Specific, opinionated, honest about what makes a brief useful versus useless. + +--- + +## Thin vs thick vs effective briefs + +The keystone distinction. Three concrete shapes. + +**Thin brief.** Keyword, word count target, deadline. Maybe a one-line summary of the angle. The writer fills in everything else from scratch. Output is generic, drifts off-topic, does not rank, and does not convert. The cost is the rewrite cycle: editor spends two hours rewriting because the writer chose the wrong intent, the wrong audience, or the wrong outline. + +**Thick brief.** A 4-page document with executive summary, brand-guidelines refresher, comprehensive competitive analysis, voice guidelines, plus the actual brief somewhere in the middle. The writer skims for the outline, ignores the rest. Output is not materially better than from a thin brief because the writer never read most of the document. The cost is the authoring time: the strategist spends three hours producing pages of context the writer will never absorb. + +**Effective brief.** One to two pages. Every field earns its keep. Writer reads all of it because there is no fluff. Output is predictable enough that the editor does not have to rewrite the lede. The cost is the discipline of cutting fields that do not change writer behavior. + +The discipline. Every field in the brief has a job. If you can remove the field without degrading the output, remove it. The brief is the contract between editorial leader and writer; vague contracts produce vague output, overstuffed contracts produce output that reflects only the parts the writer read. + +Most briefs that are not working are thin, not thick. The instinct to add more usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +--- + +## The 12 fields of an effective brief + +A useful brief has 12 fields. Skip any of them and the writer fills the gap from priors; the gap is where output drifts. + +1. **Target keyword + supporting cluster.** Primary keyword plus 3 to 5 supporting keywords from the same cluster. The cluster is what tells the writer the topic has range; the primary is what the piece optimizes for. +2. **Search intent classification.** Informational, navigational, commercial, or transactional. Plus the dominant SERP format check (article, listicle, comparison, video, tool). The intent decides what kind of piece this is; the format decides the shape. +3. **Target audience.** Specific role and sophistication level. Not "anyone interested in X." A senior data engineer at a 500-person SaaS company is a target; "data people" is not. +4. **Job to be done.** The problem the reader is trying to solve when they land on the piece. One sentence. Specific. +5. **Word count / depth target.** Calibrated to the SERP, not to a content quota. If the top 10 are all 1,200 words, briefing 3,000 wastes effort; if the top 10 are all 4,000 words, briefing 1,500 produces a piece that cannot rank. +6. **Heading structure outline.** H2s and H3s explicit, ordered logically. The outline is where the writer reads the brief most carefully; spend time here. +7. **Required entities, statistics, citations.** For AEO and GEO, the named tools, methods, experts, and statistics the piece must cover. The entity gap is the agent's prioritization signal. +8. **Internal linking strategy.** 3 to 5 pages this piece should link out to with anchor text; 1 to 3 existing pages that should link back to this piece after publish. +9. **External proof points.** Required citations, sources, expert quotes. Not optional. +10. **Anti-patterns.** What not to do. Off-topic tangents the writer might wander into, off-brand voice, AI clichés the brief explicitly forbids by listing them in a do-not-use list (the standard set of overused corporate-speak adjectives, throat-clearing openers, and verbs that signal AI generation). +11. **Success criteria.** What good looks like. Rank for the target keyword in 90 days. Get cited by ChatGPT for the cluster within 60 days. Drive 50 trial signups in the first 30 days. Measurable, time-bound, tied to the program goal. +12. **Author voice and tone reference.** Link to the brand-voice guide. If the piece needs a tone shift from the default voice, note it here in one sentence. + +The fields that do not earn their keep, and should be omitted from briefs unless the writer is brand new to the program: + +- Long executive summary (the brief itself is the executive summary) +- Brand-guidelines refresher (link to it; do not repeat) +- Comprehensive competitive landscape (link to research; do not dump) +- Brief history of the publication, company, or brand (irrelevant to this piece) + +Detail and templates per content type in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## Search intent classification + +The four standard intents: + +- **Informational.** The reader wants to learn. SERP usually shows articles, guides, explainers. +- **Navigational.** The reader wants a specific brand or page. SERP usually shows the brand site at #1; ranking against navigational intent is mostly impossible unless you are the brand. +- **Commercial.** The reader is researching a purchase. SERP usually shows comparisons, reviews, "best X" listicles. +- **Transactional.** The reader is ready to buy. SERP usually shows product pages, pricing pages, signup flows. + +The dominant SERP format check. After classifying intent, scan the SERP top 10 and tag the dominant format: article, listicle, comparison, video, tool, hybrid. The dominant format tells you the shape of the piece, which is more decisive than the intent label. + +The override pattern. When the intent feels informational but the SERP shows mostly listicles, write the listicle. When the intent feels commercial but the SERP shows mostly long-form articles, write the article. The SERP is the source of truth, not your priors. Rankings come from matching the SERP's accepted shape; deviating costs ranking. + +The AEO/GEO consideration. AI engines tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. Mismatched format is a citation risk in addition to a ranking risk. + +Detail in [`references/search-intent-classification.md`](references/search-intent-classification.md). + +--- + +## Heading structure design + +Heading hierarchy patterns the brief should specify: + +- H2 sections that match common follow-up questions for the keyword. The reader's mental model is a series of questions; the H2s answer them in order. +- H3s under H2s only when they add navigational value. No orphan H3s. No H2-H3-H4 cascades that nobody scrolls through. +- Featured snippet bait pattern: a 40 to 60 word answer paragraph immediately following an H2 question. Google often pulls this paragraph as the snippet; AI engines often quote it as the citation. +- H2 ordering that matches the reader's mental model, not the writer's enthusiasm. Put the obvious answer first; the writer's clever angle goes in H2 #4, not H2 #1. + +Anti-patterns the brief should explicitly forbid: + +- H2s that all start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. +- Buried lede: H2 #4 has the actual answer. The reader bounced at H2 #2. +- Section length wildly uneven: H2 #1 is 1,500 words, H2 #2 is 80 words. The 80-word section reads as a placeholder. + +Detail in [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md). + +--- + +## Entity coverage for AEO and GEO + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that mentions the entities the SERP top-ranking pages mention, includes specific statistics with sources, contains citation-formatted proof points, and demonstrates topical depth via entity coverage. + +The entity discovery pattern, run before briefing the piece: + +1. Pull SERP top 10 for the target keyword. +2. Identify entities mentioned across multiple pages: named tools, named methods, named experts, named data sources, named statistics. +3. Identify entities mentioned by 1 to 2 pages but not in your existing content. This is the entity gap. +4. Add the gap entities to the brief as required coverage. + +The brief lists the entities the writer must mention, with light context on why each matters. The writer is not expected to research each entity from scratch; the brief includes a one-line note ("CUPED is the variance-reduction technique used by data-warehouse-experimentation teams; mention in the methodology section") so the writer can integrate without breaking flow. + +Tools that automate this: Frase has entity-gap analysis built in; AirOps composes the same analysis through its workflow builder; Surfer SEO ships entity coverage scoring. The skill is tool-agnostic; the workflow is what matters. + +Detail in [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md). + +--- + +## Internal linking strategy + +The brief should specify two link directions: + +- **Outbound from this piece.** 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer should not be deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. +- **Inbound to this piece, post-publish.** 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +The orphan-content failure mode: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. Prevented by upstream-link planning in the brief. + +The self-cannibalization check: if this piece would compete with an existing piece for the same keyword cluster, the brief flags it explicitly. The options are consolidate (merge into the existing piece), differentiate (the brief sharpens the angle so the two do not compete), or kill one. Flagging late, after the piece is written, costs more than flagging in the brief. + +Detail in [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md). + +--- + +## Brief templates by content type + +Different content types call for different brief shapes. The 12 fields are constant; the weight of each field shifts. + +- **Pillar piece.** Comprehensive coverage of a topic, 3,000 words plus, anchors a topic cluster. Brief emphasizes structure, comprehensiveness, internal links to and from supporting pieces. +- **Supporting / cluster piece.** Narrower topic, 1,000 to 2,000 words, links up to the pillar. Brief emphasizes specificity, single-question scope. +- **Comparison piece (X vs Y).** Commercial intent, structured comparison, decision framework. Brief emphasizes objectivity (or honest positioning if the brand is one of X or Y), table structure, "when X wins" / "when Y wins" framing. +- **Listicle.** Informational or commercial intent, scannable, ranked or unranked. Brief emphasizes selection criteria, ordering rationale, depth-per-item. +- **How-to guide.** Informational, step-by-step, screenshots. Brief emphasizes step granularity, prerequisites, troubleshooting section. +- **Thought leadership / opinion.** Commercial or branding, distinctive POV, signal of expertise. Brief emphasizes thesis, supporting arguments, anticipated counter-arguments. + +Each template gets a worked example in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## The brief-to-writer handoff + +Whether the writer is human or AI, the handoff has the same shape. + +- Brief delivered with all 12 fields populated. +- Writer asks clarifying questions before drafting (or the AI agent surfaces ambiguities in the brief as the first response). +- Writer or agent acknowledges the success criteria explicitly. +- First draft references the brief: "this draft hits 4 of the 5 required entities; the 5th is missing because the SERP coverage was thin and I could not find a reliable source." +- Editor reviews against the brief, not against personal taste. "The brief said X; the draft did Y" is the review framing. + +For AI handoff specifically, the brief becomes a structured prompt or a tool input. Frase, AirOps, and similar tools structure briefs as YAML or JSON for machine consumption; the same 12 fields apply. The structured format is the only difference; the contract is the same. + +Detail in [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md). + +--- + +## Brief governance + +Versioning. Every brief has a version. Significant changes (target keyword change, audience shift, scope expansion) bump the version; cosmetic edits do not. The writer always works from the current version, not a stale draft pasted into Slack three weeks ago. + +Approval. The brief approver is the editorial owner of the content program. Single approver, not a committee. The approver is also the editor on the back end, so the same person is responsible for both the contract and the review. Splitting these roles is how briefs and reviews drift apart. + +Archival. After publish, the brief is archived alongside the content piece (Notion database row, dbt model, content management system metadata, whatever the team's source of truth is). Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, a content audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +Detail in [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses and fixes in [`references/common-brief-failures.md`](references/common-brief-failures.md). + +- "The brief was too thin." Fill all 12 fields or accept generic output. +- "The brief was too thick." Every field needs a job; remove the rest. +- "The writer ignored the brief." Anchor success criteria to the brief; review against the brief. +- "The brief had the wrong target keyword." SERP-validate before briefing. +- "The piece does not match the SERP intent." SERP intent override applies; do not write an article when the SERP wants a listicle. +- "The piece has no internal links." Internal linking belongs in the brief, not as an afterthought. +- "The piece is generic; could have been written about anything." Entity coverage and POV missing from brief. +- "The brief is comprehensive but the piece does not rank." Brief was right; SERP was harder than expected; iterate based on real performance, not by adding fields to the brief. +- "We never went back to evaluate." Success criteria measured 30 / 60 / 90 days post-publish. +- "Different writers produce wildly different output from the same brief." Brief was actually too vague; tighten anti-patterns and voice notes. + +--- + +## The framework: 12 considerations for brief authoring + +When authoring or auditing a content brief, walk these 12 considerations. + +1. **Target keyword + cluster.** Primary plus 3 to 5 supporting. +2. **Search intent + dominant SERP format.** Match the SERP, not your priors. +3. **Target audience + JTBD.** Specific role and problem, not "anyone interested in X." +4. **Word count calibrated to SERP.** Not to a content quota. +5. **Heading structure.** Explicit H2s and H3s, ordered to match reader mental model. +6. **Entity coverage.** Entities the SERP top 10 mention; gap entities added explicitly. +7. **Internal linking.** 3 to 5 outbound links specified; 1 to 3 inbound updates queued. +8. **External proof points.** Citations and sources required. +9. **Anti-patterns.** What not to do, including AI clichés and off-brand voice. +10. **Success criteria.** Measurable, time-bound, tied to original program goals. +11. **Brief versioning + approval.** Single approver; version bumps for material changes. +12. **Brief stays under 2 pages.** Every field earns its keep; remove fields that do not. + +The output of the framework is a brief document the writer can absorb in 5 minutes and execute against in the next 5 hours. + +--- + +## Reference files + +- [`references/brief-templates.md`](references/brief-templates.md) - Pillar, supporting, comparison, listicle, how-to, and thought-leadership brief templates with field-weight notes per type. +- [`references/search-intent-classification.md`](references/search-intent-classification.md) - Four-intent framework, SERP format check, override patterns. +- [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md) - H2 and H3 patterns, featured snippet bait, anti-patterns. +- [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md) - Entity discovery from SERP, gap analysis, AEO/GEO citation drivers. +- [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md) - Outbound and inbound linking patterns, orphan prevention, self-cannibalization check. +- [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md) - Human-writer handoff, AI-agent handoff, success-criteria anchoring. +- [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md) - Versioning, approval, archival, audit trail. +- [`references/common-brief-failures.md`](references/common-brief-failures.md) - Ten-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: the brief is the contract + +A content brief is the contract between editorial leader and writer. If the contract is vague, the output is vague. If the contract is overstuffed, the output reflects only the parts the writer read. The discipline is writing contracts the writer can absorb in 5 minutes and execute against in the next 5 hours; that is the entire job. + +Most briefs that are not working are thin, not thick. The instinct to add more pages usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +When in doubt about whether a brief is ready, ask: are all 12 fields populated, do they each earn their keep, is the SERP intent matched, are the entities listed, are the internal links specified, is the success criteria measurable, and is the document under 2 pages? If yes to all of those, ship the brief and let the writer work. diff --git a/skills/content-brief-authoring/references/brief-governance-patterns.md b/skills/content-brief-authoring/references/brief-governance-patterns.md new file mode 100644 index 0000000..725b669 --- /dev/null +++ b/skills/content-brief-authoring/references/brief-governance-patterns.md @@ -0,0 +1,104 @@ +# Brief governance patterns + +Versioning, single-approver, archival alongside the published piece, audit trail. + +--- + +## Versioning + +Every brief has a version. Significant changes bump the version; cosmetic edits do not. + +**Version-bump triggers:** +- Target keyword change (the piece is now optimizing for a different keyword) +- Audience shift (the JTBD has changed) +- Scope expansion or contraction (word count target moves by 50%+; new H2s added or removed) +- Success criteria change (the metric the piece is being measured against shifts) + +**No version bump for:** +- Typo fixes +- Anchor text adjustments on internal links +- Adding a sentence of clarification to an existing field +- Reformatting + +The writer always works from the current version. If a writer is mid-draft when the brief bumps from v2 to v3, the strategist tells the writer immediately and decides whether to restart, integrate the changes, or freeze the v2 draft. + +The brief has a version field at the top: `brief_version: 3`. The version is the contract identifier. + +--- + +## Single approver + +The brief approver is the editorial owner of the content program. Single approver, not a committee. + +**Why single approver:** +- A committee bog dilutes the brief. Each member adds a field; nobody removes fields. The brief grows from 1 page to 4 pages and stops being readable. +- A committee splits accountability. When the published piece misses, no single person owns the brief that produced it. +- A single approver enforces taste. The program has a consistent editorial voice because one person is gatekeeping. + +**The approver is also the editor.** The same person who approves the brief reviews the draft. This prevents the gap between "what the brief asked for" and "what the editor wants"; the same person owns both sides. + +Splitting these roles is how briefs and reviews drift apart. The strategist who briefed the piece sees the gap; an external editor reads the draft and changes the lede because of personal taste, not because of the brief. + +**The exception:** for high-stakes pieces (pillar content, thought leadership with named author, comparison pieces involving competitors), a second reader is useful. The second reader provides input but does not approve. The single approver still decides. + +--- + +## Archival + +After publish, the brief is archived alongside the content piece. + +**Common archival patterns:** +- **Notion database row.** Brief and published-piece URL on the same row. Custom fields for brief version, approver, publish date, success-criteria results. +- **dbt model with content metadata.** For warehouse-native content tracking; brief stored as JSON in the model's seed data. +- **CMS metadata fields.** Contentful, Sanity, and similar CMSs allow custom metadata fields; the brief lives in a "brief" field on the content entry. +- **Git repo.** For docs sites and developer-facing content programs; brief in a sibling markdown file to the published piece. + +**Why archival matters.** Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, an audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +The audit question is "did we ship what we briefed, and did the briefed piece achieve its success criteria?" Both halves need source-of-truth records: the brief for what was asked, the published piece for what was delivered, the metrics for what the piece achieved. + +--- + +## Audit trail + +A content program that runs at scale needs an audit trail. The audit trail answers four questions per piece: + +1. **What did we brief?** The archived brief, with version history. +2. **What did we publish?** The published URL, with publish date and last-update date. +3. **How did the piece perform against the success criteria?** Rank position at 30 / 60 / 90 days; AI citation count if measured (Profound, Frase, AirOps); conversion data from the analytics stack. +4. **What did we learn?** A short post-publish note: what worked, what did not, what to brief differently next time. + +The audit trail compounds. After 50 pieces, the program can see patterns: pillar pieces with comprehensive outlines outperform pieces with thin outlines; comparison pieces with explicit "when X wins" / "when Y wins" framing outperform pieces with implicit positioning; entity-coverage scores above 80 correlate with citation count. + +The audit trail is what turns content production from a per-piece activity into a learning system. Without the trail, every piece is a one-off; with the trail, the program improves quarter over quarter. + +--- + +## The "post-mortem on a failed piece" pattern + +When a piece misses its success criteria, the post-mortem walks the brief. + +1. Read the brief. Was it complete? Were the 12 fields populated? +2. Read the published piece. Did it follow the brief? +3. Identify the gap. Was the brief wrong (target keyword too competitive, intent misclassified)? Was the execution off (writer drifted from outline, entities missed)? Was the SERP harder than expected (well-executed brief, well-written piece, still no rank)? +4. Update the brief template if the failure is systemic (next time, run a deeper SERP check before briefing). +5. Update the writer-handoff if the failure is communication (next time, the brief is read aloud at handoff). +6. Accept the failure if the failure is variance (some pieces miss; the program does not chase every miss). + +The post-mortem is short, half a page. It feeds the audit trail and informs the next brief. It does not turn into a multi-page analysis that nobody reads. + +--- + +## Brief field: governance metadata + +The brief carries governance metadata at the top: + +> **Brief metadata** +> - Brief version: 3 +> - Approver: editorial-lead@team.com +> - Approval date: 2026-04-22 +> - Writer assigned: J. Smith (or AI agent: Frase v4) +> - Target publish date: 2026-05-15 +> - Archive location: Notion content-pipeline database, row #847 + +The metadata is six lines, not a paragraph. It identifies the contract; the rest of the brief is the contract terms. diff --git a/skills/content-brief-authoring/references/brief-templates.md b/skills/content-brief-authoring/references/brief-templates.md new file mode 100644 index 0000000..5f9c94a --- /dev/null +++ b/skills/content-brief-authoring/references/brief-templates.md @@ -0,0 +1,87 @@ +# Brief templates by content type + +Six templates. The 12 fields are constant; the weight of each field shifts based on the content type. Each template names the fields that lean heavier and the fields that lean lighter for that type. + +--- + +## Pillar piece + +Comprehensive coverage of a topic, 3,000+ words, anchors a topic cluster. The piece other content links up to. + +**Heavier fields:** heading structure (the outline is the spine), entity coverage (a pillar that misses entities loses credibility), internal linking (links to and from the supporting cluster pieces), word count (calibrated to top SERPs, often long). + +**Lighter fields:** anti-patterns (the writer assigned to a pillar usually knows the topic), tone reference (default brand voice; tone shifts are rare for pillars). + +**Brief shape:** 2 pages. The H2 outline takes ~40% of the brief because pillar structure is decisive. Entity list is long (15 to 25 entities). Internal-link section names every cluster piece that should link in or out. + +**Worked example.** Target keyword: "experimentation analytics dashboards." Cluster: experimentation methodology. Intent: commercial-investigation. SERP format: long-form articles plus comparison tables. Word count target: 2,800 to 3,400. Outline: H2 #1 "what an experimentation dashboard does," H2 #2 "platform-native vs warehouse-native," H2 #3 "the metrics that earn their keep," H2 #4 "build vs buy," H2 #5 "common dashboards that ship trusted results." Entities: lift, p-value, MDE, CUPED, sequential testing, Statsig, PostHog, Optimizely, dbt, Mixpanel, Snowflake. Internal links: 5 supporting pieces queued. + +--- + +## Supporting / cluster piece + +Narrower topic, 1,000 to 2,000 words, links up to the pillar. One question, one answer. + +**Heavier fields:** target keyword (specific long-tail), search intent (cluster pieces have to match SERP precisely), JTBD (one specific reader problem), internal linking (must link up to pillar with anchor text matching the pillar's target). + +**Lighter fields:** entity coverage (smaller scope, fewer entities required), thought-leadership POV (cluster pieces serve the cluster, not the writer's opinion). + +**Brief shape:** 1 page. JTBD in one sentence. H2 outline is 3 to 5 sections. Entity list is short (5 to 10). The "links up to pillar" specification is mandatory; an orphan cluster piece is a wasted slot. + +**Worked example.** Target keyword: "CUPED variance reduction." Pillar: experimentation analytics dashboards. Intent: informational. JTBD: data analyst wants to apply CUPED in a dbt model and needs the formula plus the gotchas. Outline: H2 "what CUPED does," H2 "the formula," H2 "implementing in dbt," H2 "common pitfalls." Internal link up to pillar with anchor "experimentation analytics dashboards." + +--- + +## Comparison piece (X vs Y) + +Commercial intent, structured comparison, decision framework. The reader wants help choosing. + +**Heavier fields:** anti-patterns (snark and trash-talk are the failure mode), heading structure (table-style comparison plus "when X wins" / "when Y wins" sections), success criteria (commercial intent piece; the metric is signups or sales-qualified leads, not traffic alone). + +**Lighter fields:** word count flex (top-ranking comparison pieces vary widely; SERP-calibrate). + +**Brief shape:** 1 to 2 pages. The comparison criteria are listed in the brief, not invented by the writer. If the brand is one of X or Y, the brief specifies honest positioning: what the brand wins on, what the competitor wins on. The brief explicitly forbids "X is the worst, Y is the best" framing. + +**Worked example.** Target keyword: "Statsig vs PostHog." Intent: commercial. SERP format: comparison tables plus prose. Comparison criteria: pricing model, MAU thresholds, MCP support, custom-metric depth, frontend visual editor, mobile SDK. "When Statsig wins": teams with strong custom-metric needs, teams that already pay for Snowflake. "When PostHog wins": product analytics-led teams, teams that want session replay alongside experimentation. Anti-pattern explicitly listed: do not write "PostHog is the clear winner" or "Statsig is overpriced." Honest comparison or do not write the piece. + +--- + +## Listicle + +Informational or commercial intent, scannable, ranked or unranked list. "10 best X" or "7 ways to Y." + +**Heavier fields:** selection criteria (why are these 10 the chosen ones; the writer needs to defend the list), ordering rationale (why is item #1 first; explicit ranking criteria), depth-per-item (how many words per item; even depth is the discipline). + +**Lighter fields:** narrative arc (listicles have minimal narrative; the list itself is the structure). + +**Brief shape:** 1 page. The selection criteria are listed in the brief. The order is suggested in the brief, with note that the writer can reorder if the research warrants. Depth-per-item is specified (e.g., 150 words each for 10 items, plus 200-word intro and 150-word conclusion = ~1,850 words). + +**Worked example.** Target keyword: "best feature flag tools 2026." Intent: commercial. Selection criteria: official MCP support, free tier exists, hosting model. The 10 items pre-listed in the brief: LaunchDarkly, Statsig, PostHog, GrowthBook, Optimizely, VWO FME, Split.io, Kameleoon, Flagsmith, Unleash. Depth: 150 words per tool covering pricing, MCP status, when this tool wins. + +--- + +## How-to guide + +Informational intent, step-by-step, screenshots, prerequisites, troubleshooting. The reader wants to do something specific. + +**Heavier fields:** step granularity (each step is one action, not three), prerequisites (what the reader needs before starting), troubleshooting section (common failure modes the reader will hit). + +**Lighter fields:** thought-leadership POV (how-to guides serve the task, not the writer's perspective on it). + +**Brief shape:** 1 to 2 pages. The brief lists the steps in outline form so the writer can spot missing prerequisites or merged steps before drafting. The screenshot list is queued (which screens, in what state). Troubleshooting bullets are listed; the writer expands each into a paragraph. + +**Worked example.** Target keyword: "how to set up a Statsig experiment." Prerequisites: Statsig account, SDK installed, exposure events instrumented. Steps: H2 "create the experiment in the console," H2 "define the assignment unit," H2 "configure the metrics," H2 "set the duration and MDE," H2 "launch and monitor." Troubleshooting: SRM check failure, exposure events not firing, metric definition mismatch. + +--- + +## Thought leadership / opinion + +Commercial or branding intent, distinctive POV, signal of expertise. The piece exists to differentiate the brand voice in the category. + +**Heavier fields:** thesis (one sentence; the whole piece defends it), anticipated counter-arguments (what would a smart skeptic say; the piece must address them), tone reference (often a sharper voice than default; the brief specifies the shift). + +**Lighter fields:** SERP entity coverage (thought leadership often deliberately diverges from SERP consensus; entity coverage is a softer requirement). + +**Brief shape:** 1 page. The thesis is one sentence at the top. The supporting arguments are listed (3 to 5). The anticipated counter-arguments are listed with notes on how the piece responds to each. The brief explicitly names the writer or contributor; thought leadership has authorship, not anonymous editorial. + +**Worked example.** Thesis: "warehouse-native experimentation is the right default for any team running 50+ experiments per quarter." Supporting arguments: cost crossover at scale, custom metric flexibility, audit trail, data-team integration. Counter-arguments to address: setup cost, time-to-first-experiment, missing UI tooling. Tone shift: sharper, more declarative than default brand voice. Author: named senior data leader. diff --git a/skills/content-brief-authoring/references/common-brief-failures.md b/skills/content-brief-authoring/references/common-brief-failures.md new file mode 100644 index 0000000..b9c2cf9 --- /dev/null +++ b/skills/content-brief-authoring/references/common-brief-failures.md @@ -0,0 +1,123 @@ +# Common brief failures + +Ten-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "The brief was too thin" + +**Symptom.** Brief contains target keyword, word count, deadline, maybe a one-line angle. Writer fills in everything else from priors. Output is generic, drifts off-topic, does not rank. + +**Diagnosis.** The strategist treated the brief as a task assignment instead of a contract. The 12 fields were not populated; the writer's defaults filled the gaps; the defaults were not aligned with the program's intent. + +**Fix.** Populate all 12 fields. If a field cannot be populated (the success criteria is genuinely unknown, the SERP is too volatile to call), name the gap explicitly and flag it as "writer's call, defend the choice in the first draft." + +--- + +## "The brief was too thick" + +**Symptom.** Brief is 4 pages with executive summary, brand-voice refresher, comprehensive competitive landscape, plus the actual brief. Writer skims for the outline. Output is not better than from a thin brief. + +**Diagnosis.** Strategist optimized for brief authorship instead of brief consumption. Each field added felt important; nobody asked "would the writer behave differently if this field were missing?" + +**Fix.** Cut fields that do not change writer behavior. Brand-voice refresher: link, do not repeat. Competitive landscape: link to research, do not summarize. Executive summary: the brief is the executive summary. Target: 1 to 2 pages. + +--- + +## "The writer ignored the brief" + +**Symptom.** The published piece misses the SERP intent, drops required entities, ignores internal-link guidance. Editor's review surfaces the gap. + +**Diagnosis.** No success-criteria acknowledgment at handoff. The writer read the brief once at the start, drafted from memory plus priors, never re-read. + +**Fix.** Require acknowledgment at handoff (see `writer-handoff-protocols.md`). The acknowledgment restates the success criteria in the writer's voice. Saying it is what keeps it load-bearing. + +--- + +## "The brief had the wrong target keyword" + +**Symptom.** The piece publishes; the target keyword turns out to have search volume of 50/month, or to be navigational (a brand wins position 1 forever), or to have a SERP the team cannot win. The piece does not rank. + +**Diagnosis.** SERP not validated before briefing. The strategist assumed the keyword was good without pulling the SERP and the volume. + +**Fix.** SERP-validate before briefing. Pull the keyword volume (Ahrefs, Semrush, GSC). Pull the SERP top 10. If the SERP looks unwinnable for the brand at current authority, pick a different keyword. + +--- + +## "The piece does not match the SERP intent" + +**Symptom.** SERP shows mostly listicles; the briefed piece is a long-form article. Or SERP shows long-form articles; the briefed piece is a listicle. Either way, the piece does not rank. + +**Diagnosis.** SERP intent override was not applied. The strategist's priors about what the keyword "should" look like overrode what the SERP actually shows. + +**Fix.** Apply the SERP override pattern (see `search-intent-classification.md`). The format choice line in the brief must match the dominant SERP format. + +--- + +## "The piece has no internal links" + +**Symptom.** Piece publishes with zero internal links to other pages on the site. Or with one or two links that the writer added arbitrarily. + +**Diagnosis.** Internal linking was treated as an afterthought. The brief did not specify outbound links; the writer added some at the end without strategic intent. + +**Fix.** Specify 3 to 5 outbound links in the brief, with anchor text and target page. Queue 1 to 3 inbound updates as post-publish tasks (see `internal-linking-strategy.md`). + +--- + +## "The piece is generic; could have been written about anything" + +**Symptom.** Reading the piece, you cannot tell what brand it came from, what makes it different from the SERP top 10, or why this piece exists. The piece reads as AI-generated even when a human wrote it. + +**Diagnosis.** Entity coverage and POV were missing from the brief. The writer hit the target keyword but did not differentiate; the piece blends into SERP consensus. + +**Fix.** Specify gap entities (entities mentioned by 1 to 2 SERP pages but not by the rest). Specify a POV for the piece: what the brand argues that the rest of SERP does not. Generic content has no POV; effective content makes a specific claim. + +--- + +## "The brief is comprehensive but the piece does not rank" + +**Symptom.** Brief had all 12 fields. Writer followed the brief. Piece is well-written, hits the entities, follows the outline. Three months post-publish: position 47. + +**Diagnosis.** The SERP was harder than expected. The brief was right; the keyword was over-competitive at the brand's current authority. This is variance, not failure. + +**Fix.** Do not iterate by adding fields to the brief. Iterate by SERP-validating more carefully next time, by accepting that some keywords are out of reach until the brand earns more authority, or by pivoting to a less-competitive long-tail variant. + +--- + +## "We never went back to evaluate" + +**Symptom.** Pieces publish; nobody checks performance at 30 / 60 / 90 days. The program runs without feedback. + +**Diagnosis.** Success criteria were defined in the brief but no measurement task was queued at publish time. + +**Fix.** Make 30 / 60 / 90 day check-ins part of the publish checklist. The check-in is a 5-minute task: read the rank, the citation count, the conversion data; update the audit trail (see `brief-governance-patterns.md`). Not optional. + +--- + +## "Different writers produce wildly different output from the same brief" + +**Symptom.** Two writers given the same brief produce pieces that read like they came from two different programs. The brief was supposedly identical; the output is not. + +**Diagnosis.** The brief was actually too vague. Different writers filled gaps with their own priors; the gaps were where the divergence lives. + +**Fix.** Tighten the anti-patterns and the voice notes. The brief explicitly forbids common writer drifts (off-topic tangents, off-brand tone, AI clichés). The voice reference is specific (not "use brand voice" but "use the voice of section 3 of the voice guide; default tone, no sharper"). + +--- + +## "The piece succeeded but we cannot tell why" + +**Symptom.** A piece outperforms expectations: top-3 rank, high citation count, conversion above target. The team cannot explain what made it work. + +**Diagnosis.** The brief and the published piece have multiple distinguishing features (specific outline, gap entities, sharp POV); without controlled comparison, the team cannot isolate the cause. + +**Fix.** Document hypotheses about why the piece worked in the post-publish note. Test the hypotheses by briefing the next 3 pieces with the same pattern. If the pattern replicates, it is the cause; if not, the success was variance. The audit trail compounds (see `brief-governance-patterns.md`); patterns emerge over 20+ pieces. + +--- + +## "We approved the brief but the writer wrote a different piece" + +**Symptom.** The brief was for a comparison piece; the writer delivered a thought-leadership piece. The brief was for 1,800 words; the writer delivered 3,400 words. The brief was for a senior data engineer audience; the writer wrote for a non-technical CMO. + +**Diagnosis.** The handoff acknowledgment was skipped. The writer read the brief, drafted from a different mental model, and did not surface the divergence early. + +**Fix.** Require acknowledgment that restates the brief's parameters: word count, audience, format. If the writer's acknowledgment misstates anything, the strategist catches it before drafting starts. After 1,500 words of writing, restarting is expensive; before drafting, restating is cheap. diff --git a/skills/content-brief-authoring/references/entity-coverage-checklist.md b/skills/content-brief-authoring/references/entity-coverage-checklist.md new file mode 100644 index 0000000..54ada43 --- /dev/null +++ b/skills/content-brief-authoring/references/entity-coverage-checklist.md @@ -0,0 +1,91 @@ +# Entity coverage checklist + +Entity discovery from SERP, gap analysis, AEO and GEO citation drivers. + +--- + +## Why entity coverage matters + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that: + +- Mentions the entities the SERP top-ranking pages mention +- Includes specific statistics with sources +- Contains citation-formatted proof points +- Demonstrates topical depth via entity coverage + +Entities are the named things the topic depends on: tools, methods, experts, datasets, statistics, brands, frameworks, standards, organizations. A piece on "experimentation analytics" that does not mention CUPED, sequential testing, p-values, or named platforms (Statsig, PostHog, Optimizely) reads as thin both to humans and to ranking systems. + +Traditional SEO has known about entity coverage for years (Google's Hummingbird and BERT updates emphasized it). AEO and GEO double the stakes: AI engines explicitly use entity coverage as a citation signal because they can extract the entity graph from the page and assess topical depth at retrieval time. + +--- + +## The entity discovery workflow + +Run before authoring the brief; do not delegate to the writer. + +**Step 1.** Pull the SERP top 10 for the target keyword. + +**Step 2.** For each top-10 page, extract the named entities. Tools that automate this: Frase (built-in entity gap analysis), AirOps (workflow builder runs the same analysis), Surfer SEO (entity coverage scoring), or manual extraction with a structured prompt. + +**Step 3.** Tag each entity by frequency: +- Mentioned by 7+ of 10 pages: required coverage. The brief lists these. +- Mentioned by 3 to 6 pages: standard coverage. The brief lists these with shorter notes. +- Mentioned by 1 to 2 pages: gap entities. The brief includes these as differentiation opportunities. +- Mentioned by 0 pages but relevant: brand-owned entities the team knows matter even if SERP misses them. + +**Step 4.** For each required and standard entity, write a one-line note in the brief explaining why it matters and where to mention it. Example: + +> **CUPED.** Variance-reduction technique mentioned by 9 of 10 SERP pages. Mention in the methodology H2 with the formula. Required. + +**Step 5.** Add the gap entities (1 to 2 page mentions) as differentiation opportunities. The writer can choose to include them; they add depth without crowding the required entities. + +--- + +## AEO and GEO citation drivers + +Beyond entity coverage, AI engines weight several other signals when deciding what to cite. + +**Specific statistics with sources.** "Statsig charges per MAU starting at 100K MAU" cites better than "Statsig is expensive at scale." Numbers with sources are higher-citation; vague qualifiers are lower-citation. + +**Named experts or quotes.** "As Ronny Kohavi noted in his book Trustworthy Online Controlled Experiments, the most common SRM diagnosis is..." cites better than "experts agree that SRM diagnoses are common." Named attribution earns citation; anonymous attribution does not. + +**Direct definitions.** "CUPED stands for Controlled-experiment Using Pre-Existing Data" cites better than a passage that uses CUPED without defining it. AI engines extract definitions and use them as the canonical answer when users ask "what is CUPED." + +**Comparison tables.** Tables with explicit columns and rows cite better than prose comparisons. AI engines extract structured data preferentially. + +**Specific tool names with version numbers.** "dbt Cloud (v1.7+)" cites better than "dbt." Specificity is the citation signal. + +--- + +## Brief field: how to populate entity coverage + +The brief lists the required entities, the standard entities, and the gap entities, with one-line notes per entity. + +> **Required entities (mention all)** +> +> - **CUPED:** variance-reduction technique (9/10 SERP pages). Mention in methodology H2 with formula. +> - **Sequential testing:** confidence-adjustment for peeking (8/10). Mention in pitfalls H2. +> - **MDE (minimum detectable effect):** power-calculation input (10/10). Mention in setup H2. +> - **Statsig, PostHog, Optimizely:** named platforms (10/10 mention at least one). Brief should mention all three with one-sentence positioning. +> +> **Standard entities (mention if relevant)** +> +> - **A/A test:** sanity check (5/10). Mention in pitfalls H2. +> - **Bonferroni correction:** multiple-testing adjustment (4/10). Mention in pitfalls H2. +> +> **Gap entities (differentiation opportunity)** +> +> - **CUPAC:** successor to CUPED (1/10). Mention in methodology H2 as the next-generation technique. Differentiates the piece from SERP consensus. +> - **Bayesian inference:** alternative to frequentist hypothesis testing (1/10; mentioned occasionally in advanced experimentation content). Mention in advanced section if word budget allows. + +The "Bayesian inference" entity is the example: it is a specific technical concept that some advanced experimentation content covers, where most SERP top-10 pieces stop at frequentist hypothesis testing. Adding the gap entity differentiates the piece without crowding the required-coverage list. + +--- + +## The entity-coverage failure mode + +The most common failure: the writer mentions all the required entities once each, in passing, without weight. The piece passes the entity-coverage check on a string-match basis but does not actually demonstrate topical depth. + +The fix in the brief: specify weight per entity. "Mention CUPED in passing in H2 #2; develop CUPED with formula and example in H2 #4." The brief is not just a list of entities to include; it is a placement plan. + +The writer's draft references the brief's entity placement plan. The editor reviews against placement, not just against presence. diff --git a/skills/content-brief-authoring/references/heading-structure-patterns.md b/skills/content-brief-authoring/references/heading-structure-patterns.md new file mode 100644 index 0000000..e89841b --- /dev/null +++ b/skills/content-brief-authoring/references/heading-structure-patterns.md @@ -0,0 +1,102 @@ +# Heading structure patterns + +H2 patterns, H3 sub-section patterns, featured-snippet bait, and the anti-patterns the brief should explicitly forbid. + +--- + +## H2 patterns that work + +**Question-style H2s.** "What is CUPED?" "How does CUPED reduce variance?" "When should I use CUPED?" These match how readers think and how Google's "People Also Ask" box surfaces queries. They are also the easiest format for AI engines to extract as citation candidates. + +**Declarative H2s.** "CUPED reduces variance by adjusting for pre-experiment covariates." "The formula uses a regression coefficient computed before assignment." Declarative H2s work for pieces that have a strong thesis or that summarize before they explain. + +**Comparison H2s.** "Platform-native: faster, narrower, opinionated." "Warehouse-native: slower, broader, custom-metric capable." Symmetrical H2s pair to set up a comparison; the reader sees the structure on the table of contents alone. + +**Imperative H2s.** "Configure the assignment unit." "Define the metrics." "Set the duration and MDE." Common for how-to guides; each H2 is one action. + +The discipline: pick one pattern and use it consistently within a piece. Mixing question + declarative + imperative reads as inconsistent and signals AI generation when the mixing is random. + +--- + +## H3 patterns under H2s + +H3s should add navigational value, not just structure for its own sake. + +**When to add H3s:** +- The H2 covers a topic with 3 to 5 sub-topics that the reader might want to jump to +- The H2 section is long enough (700+ words) that scanning needs sub-anchors +- The piece has a table of contents that benefits from sub-entries + +**When not to add H3s:** +- The H2 is short (under 400 words) +- The H3s would be a cosmetic enumeration that does not add navigation +- The piece is short overall (under 1,200 words); H3s are usually unnecessary + +**No orphan H3s.** Every H2 either has zero H3s or 2+ H3s. A single H3 under an H2 reads as a typo or an aborted edit. + +**No H2-H3-H4 cascades.** If a section needs H4s, the structure is wrong. Either the H2 is too broad and should split into two H2s, or the H4 is decoration that should be a paragraph. + +--- + +## The featured snippet bait pattern + +Place a 40 to 60 word answer paragraph immediately following the H2 question. Google often pulls this paragraph as the featured snippet; AI engines often quote it as the citation. + +**Example.** + +> ## What is CUPED? +> +> CUPED (Controlled-experiment Using Pre-Existing Data) is a variance-reduction technique that adjusts experimental measurements using pre-treatment covariates. The covariate's regression coefficient against the outcome is computed before assignment, then used to subtract baseline variance from the experiment's measurement, increasing statistical power without changing the experiment's design. + +The paragraph is self-contained: read alone, it answers the H2 question completely. The rest of the section expands on the answer with examples, formulas, edge cases. + +The discipline: the snippet paragraph is the most important paragraph in the section. Write it first; expand the section around it. + +--- + +## H2 ordering + +H2s should match the reader's mental model, not the writer's enthusiasm. + +**The standard order for informational pieces:** +1. What is it (definition, plain language) +2. Why does it matter (why the reader cares) +3. How does it work (mechanism, technical depth) +4. When to use it (decision criteria) +5. Common pitfalls (what goes wrong) +6. Wrap-up or call-to-action + +**The buried-lede anti-pattern.** H2 #4 has the actual answer the reader came for. The reader bounced at H2 #2. + +**The fix.** Put the obvious answer first. The writer's clever angle goes in H2 #4 or H2 #5, not H2 #1. + +--- + +## Anti-patterns the brief should forbid explicitly + +**Repetitive H2 structure.** All H2s start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. Vary the patterns within a piece, but keep one dominant pattern. + +**Buried lede.** The actual answer is in H2 #4. The brief specifies which H2 carries the keystone answer; usually H2 #1 or H2 #2. + +**Section length unevenness.** H2 #1 is 1,500 words; H2 #2 is 80 words. The 80-word section reads as a placeholder. Briefs should specify approximate word counts per H2 to enforce balance. + +**H3-only enumeration.** A section that is just an H2 plus a list of H3s with one paragraph each. Either the H2 should hold all the content, or the H3s deserve more depth. The half-and-half shape is a sign of incomplete thinking. + +**Misnumbered H2s in numbered series.** "5 ways to Y" with 6 H2s, or with 4. The mismatch reads as careless. + +--- + +## Brief field: how to populate the heading structure + +The brief lists the H2s in order with one-line notes. H3s only when they earn their keep. + +> **Heading structure outline** +> +> - H2 #1: "What is X?" (snippet paragraph mandatory; ~250 words section) +> - H2 #2: "Why X matters" (~300 words; one specific reader scenario) +> - H2 #3: "How X works" (~600 words; H3s: "the formula," "the assumption," "the implementation"; show the math) +> - H2 #4: "When to use X" (~400 words; decision-criteria list) +> - H2 #5: "Common pitfalls" (~400 words; 3 to 5 specific pitfalls with diagnoses) +> - H2 #6: "Wrap-up" (~150 words; call-to-action to related cluster piece) + +The writer follows the outline; deviations are flagged in the first draft for editor review. diff --git a/skills/content-brief-authoring/references/internal-linking-strategy.md b/skills/content-brief-authoring/references/internal-linking-strategy.md new file mode 100644 index 0000000..85918ae --- /dev/null +++ b/skills/content-brief-authoring/references/internal-linking-strategy.md @@ -0,0 +1,97 @@ +# Internal linking strategy + +Outbound and inbound linking patterns, orphan-content prevention, self-cannibalization check. + +--- + +## Two link directions to specify + +Every brief specifies links in two directions. + +**Outbound from this piece.** 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer is not deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. + +**Inbound to this piece, post-publish.** 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +--- + +## Outbound link selection + +The cluster pieces. The brief lists the supporting cluster pieces this piece should link to, with anchor text that matches each target's primary keyword. + +**Example for a pillar piece on "experimentation analytics dashboards":** + +> **Outbound links (writer integrates)** +> +> 1. Link to "CUPED variance reduction" (cluster piece) using anchor "CUPED" or "variance reduction with CUPED" in the methodology H2. +> 2. Link to "warehouse-native experimentation" (sister pillar) using anchor "warehouse-native experimentation" in the platform-vs-warehouse comparison H2. +> 3. Link to "feature flag tools comparison" (commercial-intent piece) using anchor "feature flag tools" in the deployment H2. +> 4. Link to "data warehouse setup" (foundation piece) using anchor "data warehouse" in the prerequisites H2. + +The discipline: anchor text matches the target's primary keyword. Generic anchors ("click here," "this article") do not pass ranking signals; keyword anchors do. + +--- + +## Inbound link queue + +The brief queues 1 to 3 existing pages that should add a link to the new piece after it publishes. The strategist updates these as part of the publish checklist. + +**Example continuing the same pillar:** + +> **Inbound link updates (post-publish task)** +> +> 1. Update "feature flagging" pillar to link to the new piece in the "measuring feature impact" section using anchor "experimentation analytics dashboards." +> 2. Update "PostHog vs Statsig" comparison to link to the new piece in the analytics-comparison H2. +> 3. Update homepage "Resources" section to add the new piece to the "Pillars" list. + +The inbound queue prevents the orphan-content failure mode. + +--- + +## The orphan-content failure mode + +Symptom: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. + +Cause: internal linking was an afterthought, handled by the writer or by SEO at publish time without strategic intent. The writer linked out to 3 pages because the brief said to; nobody linked back in because nobody owned that task. + +Fix: the brief queues the inbound updates explicitly. The publish checklist includes the inbound updates as a tracked task. Without a tracked task, the inbound updates do not happen; without inbound links, the piece is an orphan. + +The "5-link rule" diagnostic. Every published piece should have at least 5 internal links pointing to it within 30 days of publish. If a piece has fewer than 5 inbound links at the 30-day check, audit the inbound queue and add the missing links. + +--- + +## The self-cannibalization check + +Before briefing a new piece, check whether it would compete with an existing piece for the same keyword cluster. + +**The check.** Search the site for the target keyword. If an existing piece is in the top 5 of internal search results, flag it. + +**Three options when self-cannibalization is detected:** + +1. **Consolidate.** Merge the planned piece into the existing piece. Update the existing piece with the new angle, the new entities, the new examples. Keep one URL ranking; do not split ranking authority across two URLs. +2. **Differentiate.** Sharpen the angle of the new piece so it does not compete. The existing piece covers "what is feature flagging"; the new piece covers "feature flag rollout strategies for enterprise teams." Different intent, different audience, different SERP target. +3. **Kill one.** Determine which piece serves the cluster better. Redirect the loser to the winner. This is rare and usually signals the program does not have clear pillar structure. + +The discipline: flag self-cannibalization in the brief, not after the piece is written. Late detection is the expensive failure mode; the writer has already invested hours that now have to be either rewritten or thrown away. + +--- + +## Brief field: how to populate internal linking + +> **Internal linking** +> +> **Outbound (3 specified, 2 optional)** +> - Required: link to "CUPED variance reduction" with anchor "CUPED" in methodology H2 +> - Required: link to "warehouse-native experimentation" with anchor "warehouse-native" in comparison H2 +> - Required: link to "feature flag tools 2026" with anchor "feature flag tools" in deployment H2 +> - Optional: link to "data warehouse setup" with anchor "data warehouse" in prerequisites H2 (writer's call based on flow) +> - Optional: link to "experiment-design skill" with anchor "experiment design" in introduction (writer's call) +> +> **Inbound (post-publish, queued)** +> - Update "feature flagging" pillar (insert link in section 4) +> - Update "PostHog vs Statsig" comparison (insert link in analytics-comparison H2) +> +> **Self-cannibalization check** +> - Existing pieces on adjacent keywords: "experiment dashboards introduction" (different angle, no conflict) +> - No conflict; proceed with brief + +The brief is explicit about what is required, what is optional (writer chooses), and what is queued for post-publish. Three layers of discipline. diff --git a/skills/content-brief-authoring/references/search-intent-classification.md b/skills/content-brief-authoring/references/search-intent-classification.md new file mode 100644 index 0000000..eeaf7ce --- /dev/null +++ b/skills/content-brief-authoring/references/search-intent-classification.md @@ -0,0 +1,68 @@ +# Search intent classification + +Four-intent framework, dominant SERP format check, override patterns when intent and format mismatch. + +--- + +## The four standard intents + +**Informational.** The reader wants to learn. Queries: "what is CUPED," "how does feature flagging work," "experimentation analytics explained." SERP usually shows articles, guides, explainers, sometimes videos. Conversion is downstream (the reader signs up for the newsletter or returns to the site weeks later); ranking is the immediate goal. + +**Navigational.** The reader wants a specific brand, product, or page. Queries: "Statsig pricing," "LaunchDarkly login," "PostHog docs." SERP usually shows the brand site at #1 and a sitelinks block. Ranking against navigational intent is mostly impossible unless you are the brand. The exception: the reader-bypass pattern where adjacent brands rank for "competitor X login" by writing comparison content; play this carefully because it can read as bait. + +**Commercial.** The reader is researching a purchase. Queries: "best feature flag tools," "Statsig vs LaunchDarkly," "Optimizely review." SERP usually shows comparisons, reviews, "best X" listicles, sometimes detailed guides. The reader is in active evaluation; this is the highest-conversion intent for B2B SaaS content. + +**Transactional.** The reader is ready to buy. Queries: "Statsig signup," "buy LaunchDarkly," "PostHog free trial." SERP usually shows product pages, pricing pages, signup flows. Editorial content does not rank here; brand-owned commercial pages do. + +--- + +## The dominant SERP format check + +After classifying intent, scan the SERP top 10 and tag the dominant format. + +- **Article.** Long-form prose, single-author voice. Common for informational intent. +- **Listicle.** "10 best X," "7 ways to Y." Common for commercial-investigation intent. +- **Comparison.** Side-by-side X vs Y, table-heavy, decision frameworks. Common for high-funnel commercial intent. +- **Video.** YouTube embeds dominate the top of SERP. Common for how-to and tutorial queries. +- **Tool.** Calculator, generator, interactive tool. Common for "X calculator" or "X generator" queries. +- **Hybrid.** SERP shows a mix; usually tells you the keyword is contested or the intent is split. + +The dominant format tells you the shape of the piece, which is more decisive than the intent label. An informational keyword whose SERP is mostly listicles wants a listicle, not a long-form article. + +--- + +## The override pattern + +When intent and format mismatch, the format wins. + +**Case 1.** The intent feels informational ("how to design an A/B test") but the SERP shows mostly listicles ("7 steps to designing an A/B test"). Write the listicle. The SERP is the source of truth, not your priors about what the intent "should" look like. + +**Case 2.** The intent feels commercial ("best feature flag tools") but the SERP shows mostly long-form articles that mention many tools without ranking them. Write the long-form article. Listicle format would feel out of place against the SERP. + +**Case 3.** The SERP is genuinely split: half listicles, half long-form articles. Either format can rank. Pick based on the brand's voice and the piece's role in the cluster. + +The reason. Rankings come from matching the SERP's accepted shape; deviating costs ranking. Google's ranking algorithm is partly trained on what users click and stay on, which is selected from existing top-ranking content. Existing top-ranking content sets the shape; new content has to match the shape to compete. + +--- + +## The AEO and GEO consideration + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. + +A piece that mismatches the SERP format faces two problems: it is harder to rank in traditional search, and it is less likely to be cited by AI engines. The mismatch is a double cost. + +The exception: thought leadership that deliberately diverges. A piece arguing "the listicle format is misleading for this category; here is why" can rank by drawing traffic on the controversy and earning citations on the contrarian thesis. This is rare and risky; do not default to it. + +--- + +## Brief field: how to populate intent + format + +The brief field reads like this: + +> **Search intent + SERP format** +> Intent: commercial-investigation +> Dominant SERP format: long-form article + comparison table hybrid (top 5 are articles with embedded comparison tables; positions 6 to 10 are pure listicles) +> Format choice for this piece: long-form article with one comparison table at the midpoint +> SERP intent override: none (format choice matches dominant) + +The "format choice" line is decisive. The writer reads this line first and shapes the piece around it. diff --git a/skills/content-brief-authoring/references/writer-handoff-protocols.md b/skills/content-brief-authoring/references/writer-handoff-protocols.md new file mode 100644 index 0000000..ca3be09 --- /dev/null +++ b/skills/content-brief-authoring/references/writer-handoff-protocols.md @@ -0,0 +1,101 @@ +# Writer handoff protocols + +Human-writer handoff, AI-agent handoff, success-criteria anchoring. + +--- + +## The handoff has the same shape regardless of writer + +Whether the writer is a human freelancer, a staff editor, an internal SME, or an AI agent (Claude, ChatGPT, a Frase brief-runner, an AirOps workflow), the brief-to-writer handoff has the same five-step shape. + +1. Brief delivered with all 12 fields populated. +2. Writer asks clarifying questions before drafting (or the agent surfaces ambiguities as the first response). +3. Writer or agent acknowledges the success criteria explicitly. +4. First draft references the brief: which fields the draft addresses, which fields it could not address, why. +5. Editor reviews against the brief, not against personal taste. + +The shape is the same; the medium differs. Human writers acknowledge in Slack or email; AI agents acknowledge in the first message of the agent thread. Both cases: the acknowledgment is required, not optional. + +--- + +## Human-writer handoff + +**Step 1: brief delivery.** The brief is delivered as a single document (Notion page, Google Doc, dbt-style markdown file in the repo). The writer can read it in 5 minutes; if reading takes longer, the brief is too thick and should be cut. + +**Step 2: clarifying questions.** Before drafting, the writer asks clarifying questions. Common ones: + +- Is the target audience right? Is the JTBD specific enough to write to? +- Is the SERP intent classification right? Do I write a listicle or an article? +- Are these entities really required, or are some optional? +- Is the success criteria measurable from my side, or is it a downstream-only metric? + +The strategist answers questions in the same document; clarifications are versioned with the brief, not pasted into Slack and lost. + +**Step 3: acknowledgment.** The writer acknowledges in writing: "I have read the brief. I am writing to the success criteria of [X]. I will hit all required entities. I am clear on the SERP format choice." Acknowledgment is a 3-line message, not a treatise. + +**Step 4: first draft with reference.** The first draft is delivered with a reference note: "Hit 4 of 5 required entities; the 5th (CUPAC) was not in the SERP coverage I could find sources for, so I substituted the standard CUPED treatment per the brief's gap-entity guidance." The reference note tells the editor what to focus on in review. + +**Step 5: editor review against brief.** The editor reads the brief first, the draft second. The review framing is "the brief said X; the draft did Y; gap is Z." Personal taste comes after brief review, not before. + +--- + +## AI-agent handoff + +The shape is the same; the medium is structured. + +**Step 1: brief delivery as structured input.** The brief becomes a YAML or JSON object the agent ingests. Frase, AirOps, and similar tools structure briefs in their own schema; the same 12 fields appear regardless. Example minimal YAML structure: + +```yaml +target_keyword: experimentation analytics dashboards +supporting_cluster: + - CUPED variance reduction + - sequential testing + - feature flag rollout +search_intent: commercial-investigation +serp_format: long-form-article-with-comparison-table +target_audience: senior data engineer at 500-person SaaS +jtbd: choose between platform-native and warehouse-native experimentation +word_count_target: 2800 +heading_outline: + - { level: 2, text: "What an experimentation dashboard does" } + - { level: 2, text: "Platform-native vs warehouse-native" } + - { level: 2, text: "Metrics that earn their keep" } + - { level: 2, text: "Build vs buy" } + - { level: 2, text: "Common dashboards that ship trusted results" } +required_entities: + - { name: "CUPED", note: "mention with formula in methodology H2" } + - { name: "Statsig, PostHog, Optimizely", note: "mention all three" } +internal_links: + outbound: + - { target: /skills/cuped, anchor: "CUPED" } + - { target: /skills/warehouse-native, anchor: "warehouse-native experimentation" } + inbound_queued: + - { source: /pillars/feature-flagging, anchor: "experimentation analytics dashboards" } +anti_patterns: + - "do not use the team's do-not-use word list (see brand voice guide)" + - "do not write a listicle; SERP wants long-form" +success_criteria: + - "rank top 10 for target keyword in 90 days" + - "cited by ChatGPT for 'experimentation dashboard' queries within 60 days" +voice_reference: /brand/voice-guide +brief_version: 2 +brief_approver: editorial-lead@team.com +``` + +**Step 2: ambiguity surfacing.** The agent's first response surfaces ambiguities. "The brief lists CUPED as required, but the SERP top 10 only mention CUPED in 6 of 10 results; should I emphasize it or treat it as standard coverage?" The strategist answers; the brief gets versioned with the answer. + +**Step 3: acknowledgment.** The agent acknowledges in structured output: "Reading brief version 2. Target: 2,800 words. Format: long-form with comparison table. Will hit 4 required entities; need clarification on CUPED weight." Single message, machine-readable. + +**Step 4: first draft with reference.** The agent's draft is delivered with a structured note: which fields the draft addressed, which entities are present and where, what success criteria the draft is targeting. + +**Step 5: editor review.** The editor reviews the agent's draft using the same brief-first framing. Tools like Frase highlight which entities are present in the draft; the editor scans the highlights to confirm coverage. + +--- + +## Success-criteria anchoring + +The most-skipped handoff step is success-criteria acknowledgment. The writer or agent reads the brief, drafts the piece, delivers it; the success criteria sit in the brief unread. + +The fix: every handoff acknowledgment includes the success criteria verbatim. "I am writing to the success criteria: rank top 10 for 'experimentation analytics dashboards' in 90 days; get cited by ChatGPT for the topic within 60 days; drive 50 trial signups in the first 30 days." + +The acknowledgment is the contract restated in the writer's voice. Saying it out loud is what keeps it load-bearing during drafting. diff --git a/skills/content-distribution/SKILL.md b/skills/content-distribution/SKILL.md new file mode 100644 index 0000000..eeb09a6 --- /dev/null +++ b/skills/content-distribution/SKILL.md @@ -0,0 +1,307 @@ +--- +name: content-distribution +description: "Content distribution as a discipline. Owned channels (newsletter, blog, social), earned channels (PR, syndication, mentions), paid channels (boosted posts, syndication networks), and the channel-fit decisions that distinguish strategic distribution from spam-everywhere. Audience-channel matching, content-channel matching, distribution cadence. Triggers on content distribution, channel strategy for content, owned earned paid channels, content amplification, content promotion, audience-channel matching, content-channel matching, distribution cadence, syndication strategy, organic distribution. Also triggers when content is publishing but reach is low, when the team is distributing on every channel without strategy, or when the content program needs a distribution discipline rather than just publication." +category: content +catalog_summary: "Content distribution discipline: owned, earned, and paid channels matched to audience and content type. Channel-fit decisions, distribution cadence, the strategic alternative to spam-everywhere or hope-and-pray" +display_order: 12 +--- + +# Content Distribution + +A senior editorial leader's playbook for content distribution as a discipline. Owned, earned, and paid channels matched to audience and content type, with the channel-fit decisions that distinguish strategic distribution from spam-everywhere or hope-and-pray. + +Content distribution is half the work and gets a fraction of the attention. Most programs spend 90% of capacity on production and 10% on distribution; the resulting ratio of effort-to-reach is consistently poor. The teams producing content that reaches audiences are the ones who treat distribution as a real discipline: channels chosen for fit, cadence calibrated to audience attention, owned-earned-paid balance set by program strategy, and effectiveness measured per channel. + +This skill is the channel discipline. Different from `content-repurposing` (which turns one piece into many formats), this skill is about getting content TO audiences via the right channels. The two skills compose: repurpose first, then distribute the right format on the right channel. + +The voice is the senior editorial leader who has watched programs underperform because distribution was treated as posting-after-publishing rather than as the equal half of the work. + +When to use this skill: building a distribution discipline for a content program, auditing why content publishes consistently but reach is low, calibrating owned-earned-paid balance, designing channel-fit decisions for a multi-format program. + +--- + +## What this skill is for + +This skill spans channel selection, audience-channel matching, content-channel matching, and distribution cadence. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes pieces. +- `editorial-qa` verifies before publish. +- `content-repurposing` turns one piece into many formats (transformation). +- **`content-distribution` (this skill)** gets content TO audiences via channels (channel work). + +The distinction from `content-repurposing` is load-bearing. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. Distribution is channel work: getting content to audiences via the right channels. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content programs that need reach, agencies running distribution for clients. + +What is not in scope: paid acquisition for purposes other than content amplification (covered by `paid-media-strategy`), the specific email channel discipline (covered by `email-sequences`), the AI-search optimization layer that sits across distribution channels (covered partially by `seo-aeo-geo`). + +--- + +## Hope-and-pray vs spam-everywhere vs channel-fit + +The keystone framing. + +**Hope-and-pray.** Publish and assume readers will find it. The piece goes live; the team links it on the blog homepage; maybe shares it once on social; assumes search and word of mouth will carry it. Output: most pieces reach a fraction of their potential audience because no deliberate distribution work was done. The program produces good content that nobody encounters. + +**Spam-everywhere.** Blast every piece on every channel regardless of fit. Every piece on LinkedIn, Twitter/X, Facebook, Threads, Mastodon, Bluesky, plus 5 emails to the full list, plus paid promotion on every platform. Audience tunes out; channels deprioritize the program; trust degrades. AI tooling has made spam-everywhere cheap and increasingly common, which makes the audience reaction sharper. + +**Channel-fit.** Distribute through channels matched to audience and content type. Specific channels chosen for specific pieces. Cadence calibrated to each channel's audience attention rhythm. Owned-earned-paid balance set by program strategy. Output: each distribution choice produces engagement from audiences who actually want the content; the program's distribution capacity is concentrated where it produces value. + +The litmus test. Ask of any distribution decision: which audience is this piece for, where does that audience consume content, does the piece's format fit that channel's conventions, and at what cadence does the channel reward presence? If the answers are specific, the distribution is channel-fit. If the answers are "everyone, everywhere, every channel, all the time," the distribution is spam-everywhere. + +--- + +## Channel taxonomy + +Three categories with sub-types within each. + +**Owned channels.** Channels the program owns and controls. + +- **Newsletter and email.** Direct relationship with subscribers. High control over reach (every subscriber receives the email); lower scale than social. +- **Blog and content site.** Owned property where pieces live. Search and direct traffic; the canonical version of pieces. +- **Social channels owned by the program.** LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account. Owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. +- **Communities and forums owned by the program.** Slack communities, Discord servers, dedicated discussion forums. Direct relationship with members. + +**Earned channels.** Channels where content reaches audiences via third-party amplification, not paid placement. + +- **PR and press coverage.** Journalists, podcasters, newsletter operators who cover the program's content because it is newsworthy or insightful. +- **Syndication.** Other publications republishing or excerpting the program's content (with appropriate attribution and canonical signaling). +- **Mentions and citations.** Other content marketing programs, industry analysts, AI search engines citing the program's content. +- **Word of mouth and shares.** Audiences sharing pieces with their networks; the program's content becoming part of conversations. + +**Paid channels.** Channels where paid spending amplifies content. + +- **Boosted social posts.** Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. +- **Promoted newsletter sends.** Sponsored placements in third-party newsletters. +- **Syndication networks.** Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. +- **Search advertising for content.** Paying for clicks on content pieces (less common; usually content is the organic side and paid is the conversion side). +- **Sponsored podcast or content placements.** Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Detail in [`references/channel-taxonomy.md`](references/channel-taxonomy.md). + +--- + +## Audience-channel matching + +Where the target audience actually consumes content. The distribution decision starts here. + +**The audit.** + +- Identify the audience for the program (or for the specific piece). +- Map where that audience spends time in their professional or consumer life. +- Identify the channels in that audience map where the audience is genuinely engaged (not just present). +- Match content distribution to those channels. + +**Common audience-channel maps.** + +- **B2B technical audiences.** LinkedIn high engagement; X moderate engagement (specific communities); industry newsletters; specific industry forums; podcasts in their domain. +- **B2B executive audiences.** LinkedIn high engagement; specific executive newsletters and podcasts; conferences and analyst-influence channels. +- **Consumer mass audiences.** Instagram, TikTok, YouTube, Facebook depending on demographic; broad email if subscribed. +- **Niche specialist audiences.** Specific subreddits, Discord servers, specialized newsletters, niche podcasts. Often higher engagement on smaller channels than on broad social. +- **Developer audiences.** GitHub, Hacker News, specific subreddits, dev-focused podcasts and newsletters, Twitter/X for parts of the community. + +**The mismatch failure.** Distributing on channels where the audience is present but not engaged produces low reach and low engagement. A B2B technical program publishing TikToks may technically reach audiences on TikTok but engage few of them; the audience is on TikTok for entertainment, not for technical learning. + +Detail in [`references/audience-channel-matching.md`](references/audience-channel-matching.md). + +--- + +## Content-channel matching + +Which formats fit which channels. Beyond audience match, the format must fit the channel's conventions. + +**Format-channel fit examples.** + +- Long-form analytical text fits blog, newsletter, LinkedIn long posts, X threads (for the right communities). Does not fit TikTok, Instagram Reels, or short-form video platforms. +- Short-form video fits TikTok, Reels, Shorts, increasingly LinkedIn video. Does not fit newsletter (where text leads) or owned blog (where written long-form leads). +- Statistic-driven content fits social with quote-graphics, AI search snippets, podcast mentions. Does not fit (as primary format) newsletter where context develops the stat. +- Conversational expert content fits podcasts, video interviews, possibly long social threads. Does not fit short-form video or single-post-format social. + +**The mismatch failure.** Distributing a format on a channel where the format does not fit produces low engagement. A 5,000-word whitepaper on TikTok (even repurposed) may not fit the format expectations of TikTok audiences regardless of audience overlap. + +**The compose-with-repurposing pattern.** When the audience is on a channel but the format does not fit, the right answer is often to repurpose into a format that does fit (see `content-repurposing`), then distribute. The composition is "repurpose for fit, distribute on channel." + +Detail in [`references/content-channel-matching.md`](references/content-channel-matching.md). + +--- + +## Distribution cadence + +How often, what mix, sustaining vs campaign rhythm. + +**Cadence axes.** + +- **Frequency per channel.** How often the program posts to each channel. +- **Mix.** What proportion of distribution is owned vs earned vs paid; what proportion is original vs derivative. +- **Rhythm.** Sustaining baseline cadence vs campaign spikes around flagship launches. + +**Common cadence patterns.** + +- **B2B program with content-led demand generation.** Newsletter weekly. Blog 2-4 posts per week. LinkedIn 3-5 posts per week. X 5-10 posts per week. Quarterly campaign spikes for flagship launches. +- **Consumer brand with broad-audience reach goals.** Daily Instagram content. Weekly newsletter. TikTok 2-4 posts per week. Owned blog 1-2 posts per week. Continuous paid amplification. +- **Niche specialist program with concentrated audience.** Newsletter weekly or bi-weekly. Owned blog 1-2 posts per month. Social on specific platforms 2-3 posts per week. Earned channels prioritized over paid. + +**Sustaining vs campaign.** + +- **Sustaining cadence.** The baseline rhythm. Audiences expect this cadence; deviation (long pauses or sudden spikes) affects engagement. +- **Campaign rhythm.** Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +**The cadence audit.** Programs that publish in fits and starts (3 posts in one week, then nothing for 3 weeks) underperform programs with steady cadence. Audience attention rewards predictability. + +Detail in [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md). + +--- + +## Owned-channel discipline + +Owned channels are the program's most reliable distribution. The discipline keeps them effective. + +**Newsletter.** Direct subscriber relationship; near-100% delivery to inboxes (modulo spam filtering). Cadence consistency matters: weekly is the most common cadence for B2B; bi-weekly works for higher-investment formats. Each send earns the next; sloppy sends lose subscribers. + +**Blog.** Canonical home for long-form content. SEO compounds over time; internal linking earns authority. The blog is where pieces persist; social and email send audiences to the blog. + +**Social channels owned by the program.** LinkedIn, X, Instagram, etc. Reach is platform-controlled (not the program's), but the program controls what publishes and when. Algorithmic favor varies; content that the platform's algorithm rewards gets reach beyond the follower base. + +**Podcast.** Owned distribution is the show feed; subscribers receive new episodes. Episodes also live on the blog with show notes; the show notes are an SEO asset. + +**Communities.** Slack, Discord, forums where the program facilitates discussion. The community is the audience the program is most directly engaged with; distribution to the community is the most reliable engagement signal. + +**The owned-channel anti-pattern: starvation.** Programs that under-invest in owned channels become dependent on third-party distribution. When platforms change algorithms, when paid costs rise, when earned channels go quiet, the program's reach collapses. Owned-channel investment is the durable foundation. + +Detail in [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md). + +--- + +## Earned-channel work + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real. + +**PR and press.** Pitching journalists, podcasters, newsletter operators on the program's content. Effective when the content is genuinely newsworthy or insightful; ineffective when pitches feel like blast emails. + +**Syndication.** Negotiating with other publications to republish or excerpt the program's content with appropriate attribution and canonical signaling. The syndication earns reach; the canonical link preserves SEO value. + +**Mentions and citations.** Earning mentions in other programs' content. Often happens when the program's pieces are genuinely useful as references; pieces that are generic or surface-level rarely get cited. + +**AI search citation.** Earning citations from AI search engines. Increasingly important as AI search grows; pieces designed for citation (see `content-repurposing`'s AEO extraction patterns) get cited at higher rates. + +**Word of mouth and shares.** Audiences sharing pieces with their networks. The hardest to earn deliberately; pieces that are genuinely valuable get shared. + +**The earned-channel investment.** Earned channels require relationship-building, pitch quality, and content quality. Programs that try to "do PR" with mass-blast pitches earn nothing; programs that invest in genuine relationships earn ongoing channel access. + +Detail in [`references/earned-channel-work.md`](references/earned-channel-work.md). + +--- + +## Paid promotion of organic content + +When boosting organic content earns its keep. + +**The pattern.** A piece publishes organically; some pieces show strong engagement signals; the program boosts those pieces with paid spend to extend reach. The paid spend is on content that the audience has already validated. + +**When boosting fits.** + +- The piece has demonstrated organic engagement (high CTR, high time-on-page, organic shares). +- The audience addressable through paid amplification overlaps with the program's target audience. +- The piece's value is clear enough that paid amplification produces engagement, not just impressions. + +**When boosting fails.** + +- Boosting low-engagement pieces because the calendar said so. Paid spend on content the audience does not engage with produces wasted budget. +- Boosting pieces that drive volume but not value. Pieces that produce clicks but not engagement may be drawing the wrong audience; paid amplification compounds the wrong-audience problem. +- Treating paid content amplification as a substitute for organic distribution. Paid amplifies what organic validated; paid alone produces transactional reach without the audience relationship organic builds. + +**The mix.** Most strong programs allocate 0-20% of distribution capacity to paid content amplification. Programs heavily dependent on paid promotion are usually programs that have not yet built owned and earned distribution. + +Detail in [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md). + +--- + +## Distribution measurement + +Which channels actually drive value. The discipline that prevents distribution-theater. + +**Per-channel metrics.** + +- **Reach.** How many people the channel surfaces the content to. +- **Engagement.** Click-through, time-on-page, scroll depth, completion rate (varies by format). +- **Conversion.** Newsletter signups, content downloads, qualified-lead actions, sales-cycle progression. +- **Attribution.** Which channels drove the audience members who eventually converted. + +**Channel-level analysis.** + +- Which channels produce the highest engagement-per-distribution-effort? Some channels look impressive (high reach) but produce low engagement. +- Which channels produce the highest conversion? Reach without conversion is vanity; conversion is value. +- Which channels' performance is changing over time? Algorithm shifts, audience migrations, and competitive landscape changes affect channel effectiveness. + +**Cross-channel attribution.** The same audience member encounters the program on multiple channels before converting. Single-touch attribution misrepresents which channels matter; multi-touch attribution is more accurate but harder to implement. + +**The measurement-honest program.** Cuts channels that consistently underperform. Increases investment in channels that consistently produce. Adjusts cadence based on engagement patterns, not on arbitrary publishing schedules. + +Detail in [`references/distribution-measurement.md`](references/distribution-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-distribution-failures.md`](references/common-distribution-failures.md). + +- "We publish but reach is low." Hope-and-pray pattern; no deliberate distribution work happening. +- "We post on every channel and engagement is flat." Spam-everywhere pattern; distribution capacity diluted across channels where the audience is not engaged. +- "Newsletter open rates are dropping." Cadence may be wrong, or list quality declining, or content not earning the open. Investigate. +- "Our LinkedIn engagement keeps falling." Possible algorithm shift; possible content-channel mismatch; possible cadence issue. +- "Our PR pitches are getting ignored." Mass-blast pitching; relationships not built; pitches not specific to recipient. +- "We invest heavily in paid but engagement is low." Paid amplifying low-organic-engagement content; paid as substitute for owned development. +- "We do not know which channels are working." Measurement absent; program operating on channel-presence rather than channel-effectiveness. +- "Content publishes but audiences do not see it." Distribution treated as posting; cadence wrong; channels mismatched to audience. +- "We launched campaign distribution but it landed quietly." Campaign rhythm not earned by sustaining cadence; audiences not primed to attention-spike. +- "Our owned audience is small." Long-term investment in owned channels skipped; program dependent on third-party distribution. +- "Earned channels are not producing." Treating earned as automatic; relationships not built; pitches not earning. +- "Paid distribution costs are rising." Auction dynamics on paid platforms; programs heavily dependent on paid see costs rise without offsetting owned/earned investment. + +--- + +## The framework: 12 considerations for content distribution + +When designing or auditing a distribution program, walk these 12 considerations. + +1. **Channel-fit, not hope-and-pray or spam-everywhere.** Specific channels for specific audiences and formats. +2. **Channel taxonomy understood.** Owned, earned, paid; sub-types within each; which channels the program actually uses. +3. **Audience-channel matching.** Where the target audience actually engages, not just where they are present. +4. **Content-channel matching.** Format fits the channel's conventions and audience expectations. +5. **Distribution cadence calibrated.** Per-channel frequency, owned-earned-paid mix, sustaining-vs-campaign rhythm. +6. **Owned-channel discipline.** Newsletter, blog, social channels owned by the program, possibly podcast and community. Long-term investment. +7. **Earned-channel work.** PR, syndication, mentions, AI-search citation. Relationship investment. +8. **Paid promotion of organic content.** Boost pieces that have organic engagement; do not substitute paid for owned. +9. **Cross-channel attribution.** How audiences encounter the program across channels before converting. +10. **Per-channel measurement.** Reach, engagement, conversion. Channels that underperform get cut. +11. **Sustaining-vs-campaign rhythm.** Baseline cadence plus campaign spikes for flagship launches. +12. **Distribution capacity allocation.** Real budget; not done in the cracks. + +The output of the framework is a distribution program where each channel choice is deliberate, each cadence decision matches audience attention, each measurement informs the next decision, and the program's reach grows because the work is concentrated where it produces value. + +--- + +## Reference files + +- [`references/channel-taxonomy.md`](references/channel-taxonomy.md) - Owned, earned, paid with sub-types. Newsletter, blog, social, communities, PR, syndication, mentions, boosted social, syndication networks, sponsored placements. +- [`references/audience-channel-matching.md`](references/audience-channel-matching.md) - Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction. +- [`references/content-channel-matching.md`](references/content-channel-matching.md) - Format-channel fit. The compose-with-repurposing pattern. The format-mismatch failure mode. +- [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md) - Frequency, mix, rhythm. Sustaining vs campaign. Common cadence patterns by program type. +- [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md) - Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. +- [`references/earned-channel-work.md`](references/earned-channel-work.md) - PR, syndication, mentions, AI-search citation, word of mouth. Relationship investment. +- [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md) - Boosting organic content. When paid amplification fits and when it fails. The paid-as-substitute anti-pattern. +- [`references/distribution-measurement.md`](references/distribution-measurement.md) - Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. +- [`references/common-distribution-failures.md`](references/common-distribution-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: distribution is half the work + +Most content programs are production-heavy and distribution-light. The teams producing flagship pieces typically spend 90% of capacity producing and 10% distributing; the resulting reach matches the inverse ratio. Pieces that took 60 hours to produce reach a fraction of their potential audience because the 6 hours allocated to distribution were not enough to do the channel work. + +The discipline is not "distribute more"; it is "distribute deliberately." Channel-fit decisions concentrate distribution work where it produces value. Owned-channel investment builds durable foundations. Earned-channel relationships accumulate over years. Paid promotion amplifies what organic validated. Measurement informs what to keep and what to cut. + +When in doubt about whether a distribution program is ready, ask: are channels chosen for fit, is audience-channel matching deliberate, do formats fit channels, is cadence calibrated, is owned-channel investment in place, are earned-channel relationships being built, is paid amplification on organically-validated pieces, is measurement informing the next decisions? If yes to all of those, the program is real. If no to any, the gap is where reach will fall short of what the production work earned. diff --git a/skills/content-distribution/references/audience-channel-matching.md b/skills/content-distribution/references/audience-channel-matching.md new file mode 100644 index 0000000..c1d5753 --- /dev/null +++ b/skills/content-distribution/references/audience-channel-matching.md @@ -0,0 +1,172 @@ +# Audience-channel matching + +Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction that prevents distributing on channels where the audience is technically present but not actually paying attention. + +The first and most consequential distribution decision is which channels to invest in. Most programs over-invest in channels with high audience presence but low audience engagement, and under-invest in smaller channels where the audience is genuinely paying attention. The audit shifts capacity to where engagement happens. + +--- + +## The presence-vs-engagement distinction + +A channel where the audience is present is not necessarily a channel where the audience is engaging. + +**Presence.** Members of the target audience have accounts on the platform. They could see the program's content if they encountered it. + +**Engagement.** Members of the target audience are actively using the platform for the kind of content the program produces. They click; they comment; they share; they convert. + +**The mismatch failure mode.** A B2B technical program publishing TikTok content. The audience may have TikTok accounts (presence), but the audience is on TikTok for entertainment, not for B2B technical learning (low engagement for the program's content). The presence creates a false signal that the channel might work; the engagement reality is that distribution capacity goes to a low-return channel. + +**The audit question.** Not "is the audience on this channel?" but "is the audience consuming this kind of content on this channel?" + +--- + +## Common audience-channel maps + +Mappings that show up repeatedly across program types. Programs should still validate against their own audience research; the maps below are starting points. + +### B2B technical audiences + +Engineers, technical decision-makers, developer-influencers, technical product managers. + +**High engagement.** LinkedIn (especially long-form posts and articles); X/Twitter (specific technical communities); industry-specific newsletters; specialized podcasts; specific subreddits and Discord servers; GitHub for code-adjacent content; technical conferences and analyst-influenced channels. + +**Moderate engagement.** YouTube for tutorial and conference-talk content; Hacker News for specific topics; vendor-platform community sites (AWS, Azure, GCP forums; specific tool communities). + +**Low engagement.** TikTok, Instagram, Facebook for the program's primary content. Some technical professionals consume these for entertainment but rarely for technical content. + +### B2B executive audiences + +C-suite, VPs, senior strategy leaders. + +**High engagement.** LinkedIn (long-form posts, articles, sometimes video); specific executive newsletters and podcasts; analyst-influence channels (Gartner, Forrester); event-driven media (high-quality conferences, executive roundtables). + +**Moderate engagement.** Industry-specific publications; some podcasts; X/Twitter for specific topics with executive commentary. + +**Low engagement.** Most consumer-focused social platforms. Executives often have low time for content consumption; the channels where they engage are concentrated. + +### Consumer mass audiences + +Broad consumer demographics for B2C brands. + +**High engagement.** Instagram, TikTok, YouTube, Facebook (varies by demographic age and interest). Email newsletter for engaged subscribers. Pinterest for visual-product categories. Specific subreddits for interest-driven topics. + +**Moderate engagement.** X/Twitter (declining for many consumer demographics). LinkedIn (low for most consumer use cases). + +**Low engagement.** Most B2B-oriented channels. + +### Niche specialist audiences + +Concentrated audiences within specific domains (cybersecurity professionals, fertility-tracking enthusiasts, specific hobby communities). + +**High engagement.** Specific subreddits, Discord servers, specialized newsletters and podcasts. Often higher engagement on smaller channels than on broad platforms. + +**Moderate engagement.** Domain-specific Twitter/X communities; some LinkedIn; YouTube for educational content. + +**Low engagement.** Broad social platforms where the audience is small fraction of total platform population. + +### Developer audiences + +Software developers across stacks and seniority levels. + +**High engagement.** GitHub (code-adjacent content); Hacker News (specific topics); specific subreddits; Twitter/X for parts of the dev community; dev-focused podcasts and newsletters; YouTube for tutorial content. + +**Moderate engagement.** LinkedIn for senior developers; Stack Overflow for Q&A-driven content (different distribution model than programs typically use); Discord servers for specific tools. + +**Low engagement.** TikTok, Instagram, Facebook, Pinterest for primary content. + +### Founder and startup audiences + +Founders, startup operators, early-stage investors. + +**High engagement.** Twitter/X (the founder community has historically been engaged here); LinkedIn for some segments; specific newsletters (Lenny's, Substack-based founder newsletters); specific podcasts; YC-adjacent forums. + +**Moderate engagement.** YouTube for some long-form content; specific subreddits. + +**Low engagement.** Most mass-consumer platforms. + +--- + +## The audience-channel audit + +A short framework for matching audience to channels. + +1. **Define the target audience specifically.** Not "marketers" but "B2B SaaS marketing leaders at companies with 50-500 employees, primarily in North America and Western Europe." Specificity unlocks the matching. +2. **Map where this audience spends time professionally.** Where do they get news, learn new ideas, hear from peers, encounter products? +3. **Map where this audience spends time consuming the kind of content the program produces.** Different from professional time generally; specific to the content type. +4. **Identify channels where the audience engages.** Not just where they have accounts. Engagement signals: comments, shares, conversion behaviors. +5. **Score channels by engagement potential.** High, moderate, low. The high-engagement channels get primary distribution capacity. + +--- + +## Audience-research methods for the audit + +How to actually identify where audiences engage. + +**Customer interviews.** Ask existing customers where they consume content related to the program's topic. The answers are the audience's revealed-preference distribution map. + +**Audience surveys.** Quantitative confirmation of channel-engagement patterns. Surveys can over-represent platforms respondents feel they should use; the customer interviews ground-truth the survey data. + +**Existing program data.** Where does the program's existing audience come from? Referral data, UTM analysis, conversion attribution. Channels that produce existing audience are channels where the audience is engaging with the program. + +**Competitive analysis.** Where do competing programs distribute? Where do they appear to earn engagement (visible signals: comments, shares, mentions)? Competitive distribution patterns inform but should not dictate the program's choices. + +**Industry research.** Some industry research firms publish channel-engagement data by audience segment. Useful as starting points; should be triangulated with the program's own data. + +--- + +## The audience-channel mismatch failure mode + +The pattern when audience-channel matching is skipped. + +**The symptom.** The program publishes consistently on multiple channels. Engagement is flat or declining. Distribution capacity is spread thin. The team cannot identify which channels are working because none of them are working clearly. + +**The diagnosis.** Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +**The cure.** Run the audience-channel audit. Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. The total distribution capacity stays the same; the allocation shifts. + +**Recovery time.** Cutting underperforming channels and concentrating capacity on engaging channels typically produces visible engagement improvements within 4-8 weeks. + +--- + +## When audience-channel maps shift + +Audiences move across channels over time. Maps that fit a program 3 years ago may not fit now. + +**Common shifts.** + +- Twitter/X engagement has declined for many B2B audiences as the platform has changed; LinkedIn has absorbed some of the shifted attention. +- TikTok has expanded into demographics it did not initially serve. +- Newsletter consumption has grown across most audience types as inbox-based content consumption has become more accepted. +- AI-search citation has emerged as a distribution channel that did not exist meaningfully before 2024. + +**The audit cadence.** Run the audience-channel audit at least annually. Maps that have not been refreshed for 18+ months are likely outdated. + +--- + +## The audience-channel-content-type triangle + +Audience-channel matching is one of three matching decisions; content-channel matching is another (see `content-channel-matching.md`); the third is content-audience matching (the source piece is for the right audience in the first place). + +**The triangle.** + +- Audience matches channel. +- Content matches channel. +- Content matches audience. + +**The failure modes.** + +- Audience-channel mismatch: distribution where the audience is not engaged. +- Content-channel mismatch: format does not fit the channel's conventions. +- Content-audience mismatch: the piece is not actually for the channel's audience even if both fit individually. + +The triangle is what produces channel-fit distribution. All three matchings need to hold for distribution to produce engagement. + +--- + +## Methodology-level choices that stay in the public skill + +The presence-vs-engagement distinction, the common audience-channel maps, the audience-channel audit, audience-research methods, the mismatch failure mode, the map-shift recognition, the audience-channel-content-type triangle. + +## Implementation choices that stay internal + +Specific audience-research surveys and interview templates. Specific UTM tracking and attribution conventions. Specific competitive analysis tooling. Specific channel-engagement scoring rubrics. The team's own audience-segment definitions. These vary by team, audience, and tooling. diff --git a/skills/content-distribution/references/channel-taxonomy.md b/skills/content-distribution/references/channel-taxonomy.md new file mode 100644 index 0000000..c826a25 --- /dev/null +++ b/skills/content-distribution/references/channel-taxonomy.md @@ -0,0 +1,215 @@ +# Channel taxonomy + +Owned, earned, paid with sub-types. The full taxonomy that grounds channel-fit decisions. + +Programs that distribute well think in terms of the taxonomy. Programs that distribute poorly think in terms of "social media" or "content marketing" without distinguishing the categories. The distinction matters because owned, earned, and paid channels have different cost structures, different reach characteristics, and different roles in a program's distribution mix. + +--- + +## Owned channels + +Channels the program owns and controls. + +### Newsletter and email + +The most direct owned distribution. + +**Characteristics.** Direct relationship with subscribers. The program controls what sends, when, and to whom. Near-100% delivery to inboxes (modulo spam filtering and engagement-based deliverability adjustments). + +**Strengths.** No platform algorithm between the program and the audience. Engagement is cleanly measured. Audience commitment signal is strong (people who subscribe and stay subscribed are valuable signal). + +**Weaknesses.** Slow to grow vs broad-reach social channels. Each subscriber is real work to acquire and retain. + +**The newsletter discipline.** Cadence consistency, content quality matching subscriber expectations, single-CTA-per-send, deliverability hygiene. See `email-sequences` for the email-specific discipline. + +### Blog and content site + +The program's content home. + +**Characteristics.** Owned property where pieces live as canonical versions. Search traffic compounds over years. Internal linking earns authority. Direct traffic from audiences who know the property. + +**Strengths.** Compounding asset. Content that earns search position keeps producing traffic indefinitely. Full design and presentation control. + +**Weaknesses.** Slow to start producing meaningful traffic. SEO investment is multi-year. Without distribution to the blog, pieces sit unread. + +**The blog discipline.** Architecture and technical SEO foundations (see `seo-technical`); pillar and cluster organization (see `pillar-content-architecture`); refresh discipline (see `content-refresh-system`); on-page optimization (see `seo-onpage`). + +### Social channels owned by the program + +LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account, etc. + +**Characteristics.** The program runs the account; the platform controls reach via algorithms. Reach varies by platform algorithm changes, audience size, content engagement signals. + +**Strengths.** Larger potential audience than newsletter. Algorithmic favor can produce reach beyond follower base when content earns engagement signals. + +**Weaknesses.** Platform-controlled reach. Algorithm shifts can dramatically reduce reach without warning. Audiences are renting the platform; the program does not own the relationship the way newsletter signals ownership. + +**The owned-social discipline.** Per-platform conventions; cadence calibrated to platform attention rhythm; content adapted for platform; engagement-signal optimization; account-health hygiene. + +### Podcast + +Owned audio distribution. + +**Characteristics.** The show feed is owned; subscribers receive new episodes through their podcast app. Episodes also live on the blog with show notes; cross-platform distribution (Spotify, Apple Podcasts, YouTube) extends reach. + +**Strengths.** Intimate audience relationship. High engagement when audience is loyal. Long-form context for substantive content. Show notes are SEO assets. + +**Weaknesses.** Production cost is real (audio quality, editing, hosting). Discoverability depends on platform algorithms and word-of-mouth. + +**The podcast discipline.** See podcast-specific format conventions; show notes as derivative format; consistent episode cadence; cross-platform distribution for reach. + +### Communities + +Slack communities, Discord servers, dedicated discussion forums. + +**Characteristics.** Direct relationship with members. The program facilitates discussion; members engage with each other and with program content. + +**Strengths.** Highest-engagement audience the program has. Community feedback informs content and product. Members become advocates. + +**Weaknesses.** Community management is meaningful work. Communities require continuous facilitation; abandoned communities decay and signal decline. + +**The community discipline.** Active moderation; sustained value-delivery to members; integration with the broader content program (members get access; program content is shared in community). + +--- + +## Earned channels + +Channels where content reaches audiences via third-party amplification, not paid placement. + +### PR and press coverage + +Journalists, podcasters, newsletter operators who cover the program's content. + +**Characteristics.** Third parties cover the program's content because it is newsworthy, insightful, or fits their editorial agenda. The program does not pay for coverage; the value exchange is editorial fit. + +**Strengths.** External authority signal. Reach into audiences the program does not have direct relationships with. Often higher trust signal than program's own distribution. + +**Weaknesses.** Hard to predict; relationship-dependent; pitches that miss editorial fit produce nothing. + +**The PR discipline.** Genuine relationship-building with relevant journalists. Pitches specific to recipient and to actual newsworthy content. Quality over quantity; mass-blast pitches earn no coverage and damage future relationship potential. + +### Syndication + +Other publications republishing or excerpting the program's content. + +**Characteristics.** Programs negotiate with other publications to republish or excerpt their content. Canonical link signaling preserves SEO value. Attribution is mandatory. + +**Strengths.** Reach into the syndication partner's audience. Some pieces reach more readers via syndication than via owned distribution. + +**Weaknesses.** Negotiation overhead. Risk of authority dilution if canonical signaling is wrong. Partners may discontinue syndication; the program cannot rely on syndication as primary distribution. + +**The syndication discipline.** Canonical link tags; clear attribution; partner relationship management; selective syndication (not every piece warrants syndication). + +### Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +**Characteristics.** External programs reference the program's content as a source. The program's authority signal compounds with each citation. + +**Strengths.** Compounding authority. Long-term backlink and citation profile that informs SEO and AI-search positioning. + +**Weaknesses.** Largely outside the program's direct control. The program can produce citation-worthy content (specific data, framework introductions, primary research) but cannot force citation. + +**The citation-earning discipline.** Produce content with citation hooks: original data, named frameworks, primary research, contrarian-but-defensible positions. Pieces that are generic rarely get cited; pieces that are specifically valuable do. + +### Word of mouth and shares + +Audiences sharing pieces with their networks. + +**Characteristics.** The program's content becomes part of conversations beyond the program's distribution. Most valuable when sharing happens in private channels (DMs, Slack channels, internal corporate emails) where the program cannot directly track. + +**Strengths.** Highest-trust distribution. A piece shared by a colleague carries more weight than the same piece in a feed. + +**Weaknesses.** Hard to measure; hard to engineer deliberately. Pieces that earn word-of-mouth are pieces that are genuinely valuable to the audience. + +**The word-of-mouth discipline.** Produce content that audiences want to share. Specific, useful, citation-worthy. Avoid generic content that nobody bothers to share even if they read it. + +--- + +## Paid channels + +Channels where paid spending amplifies content. + +### Boosted social posts + +Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. + +**Characteristics.** The program pays the platform to show the post to additional audiences (often defined by audience targeting parameters). The post still appears as an owned post; the paid spend extends its reach. + +**Strengths.** Quick to deploy; extends reach of pieces that have demonstrated organic engagement; measurable. + +**Weaknesses.** Costs accumulate; auction dynamics drive prices up over time; pieces that performed organically may not maintain engagement at scaled paid reach. + +**The boost discipline.** Boost pieces with strong organic engagement signals; do not boost pieces that did not earn engagement organically; treat boost spend as amplification of validation, not as substitute for organic. + +### Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +**Characteristics.** The program pays a third-party newsletter to feature its content. The newsletter audience sees the program's content alongside the newsletter's editorial content. + +**Strengths.** Reach into newsletter audiences with strong attention rhythms. Often higher engagement than broad social paid amplification. + +**Weaknesses.** Requires negotiation; sponsorship feels different from editorial; price-per-send varies. + +**The sponsored-newsletter discipline.** Match the newsletter's audience and tone; sponsored content that fits the newsletter feels like value; sponsored content that clashes feels like an ad. + +### Syndication networks + +Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. + +**Characteristics.** Programs pay per click; content appears on third-party sites in "you may also like" or "recommended for you" placements. + +**Strengths.** Volume reach at variable cost; geographic and audience targeting. + +**Weaknesses.** Quality of audience varies; engagement often low; reputation challenges (some networks have brand-safety concerns). + +**The syndication-network discipline.** Test cautiously; measure beyond clicks (engagement, time-on-page); some networks fit some programs and not others. + +### Search advertising for content + +Paying for clicks on content pieces. + +**Characteristics.** Less common; usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +**Strengths.** High-intent audiences; quick reach for high-value content. + +**Weaknesses.** Cost-per-click on competitive queries; content that converts via paid clicks usually has clear conversion signals. + +**The content-search-ads discipline.** Reserve for content with clear conversion or lead-capture goals; measure paid traffic against owned-traffic comparison; high-value content only. + +### Sponsored podcast or content placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +**Characteristics.** The program pays to be featured in a third-party podcast or newsletter, often via host-read endorsement. + +**Strengths.** Host-read endorsements carry strong trust signal. Audiences of niche podcasts and newsletters are highly engaged. + +**Weaknesses.** Cost varies; production quality matters; mismatched host-program fit damages both. + +**The sponsored-placement discipline.** Match host audience to program audience; provide hosts with substantive talking points; measure on engagement signals beyond impressions. + +--- + +## Channel mix evolution over program maturity + +Programs at different stages have different channel mixes. + +**Early-stage programs.** Heavy owned-channel investment (newsletter, blog). Limited earned (relationships not yet built). Limited paid (budget often constrained). The early program is building the foundation. + +**Mid-stage programs.** Owned channels producing reliable distribution. Earned channels developing (PR relationships, syndication, mentions accumulating). Paid amplification of best organic pieces. + +**Mature programs.** Owned channels are reliable foundations. Earned channels are significant traffic and authority sources. Paid amplification is strategic, not load-bearing. + +**The maturity audit.** Programs heavily dependent on paid distribution often have under-invested in owned and earned. The dependency is visible: when paid budgets cut, reach collapses; when paid costs rise (as they do over time on auction-based platforms), program effectiveness degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The owned/earned/paid taxonomy with sub-types, the characteristics and disciplines per sub-type, the channel mix evolution by program maturity, the maturity audit. + +## Implementation choices that stay internal + +Specific platform tooling per channel. Specific community management software. Specific PR-relationship CRMs. Specific paid-platform configurations and bidding strategies. Specific syndication-network vendor selections. The team's own conventions for channel-mix targets at different program stages. These vary by team, budget, and program shape. diff --git a/skills/content-distribution/references/common-distribution-failures.md b/skills/content-distribution/references/common-distribution-failures.md new file mode 100644 index 0000000..92119ff --- /dev/null +++ b/skills/content-distribution/references/common-distribution-failures.md @@ -0,0 +1,193 @@ +# Common distribution failures + +Twelve-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most distribution failures share a single root, which is treating distribution as posting-after-publishing rather than as the equal half of the work. + +--- + +## Failure 1: Hope-and-pray (publish and wait) + +**Symptom.** The program publishes consistently. Reach is low. The team is unclear why; the content seems strong. + +**Diagnosis.** No deliberate distribution work. Publishing is treated as the end of the work; audiences are expected to find the content via search, social, and word of mouth without proactive distribution. + +**Cure.** Apply the channel-fit discipline. Identify which channels the audience engages on; distribute deliberately on those channels with appropriate format adaptation. Treat distribution as half the work. + +**Capacity recovery.** Programs that shift from hope-and-pray to deliberate distribution typically see 2-5x reach improvements within 8-12 weeks. + +--- + +## Failure 2: Spam-everywhere + +**Symptom.** The program posts on every channel: LinkedIn, X, Facebook, Threads, Bluesky, Instagram, TikTok, plus 5 emails per week, plus paid promotion on every platform. Engagement is flat across all channels. + +**Diagnosis.** Distribution capacity diluted across channels where the audience is not engaged. Each channel gets cursory attention; none gets enough to produce real engagement. + +**Cure.** Apply the audience-channel matching discipline. Cut channels where the audience is present but not engaged. Concentrate capacity on channels that produce engagement. + +**Recovery time.** Cutting underperforming channels and concentrating capacity typically produces visible engagement improvements within 4-8 weeks. + +--- + +## Failure 3: Newsletter open rates declining + +**Symptom.** The newsletter open rate has declined from 35% to 22% over 6 months. Subscribers are not opening sends. + +**Diagnosis.** Multiple possible causes. Cadence may be wrong (too aggressive or too sparse). List quality may be declining (lapsed subscribers depressing engagement signal). Subject lines may not be earning the open. Content may not be matching subscriber expectations. + +**Cure.** Diagnose first. Pull cohort data: are recent subscribers opening at higher rates than long-term subscribers (suggests content fit decline)? Are sends with specific subject-line patterns performing better (suggests subject line issue)? Is open rate consistent across send-times (rules out timing)? + +Apply the relevant fix: list pruning for lapsed subscribers; subject-line improvement; cadence adjustment; content recalibration. + +--- + +## Failure 4: LinkedIn engagement falling + +**Symptom.** LinkedIn engagement on the program's posts has declined. Comments, shares, and reach signals all lower than 6 months ago. + +**Diagnosis.** Multiple possible causes. Algorithm shift; content-channel mismatch; cadence issue; account-health degradation. LinkedIn algorithm changes have affected many programs over the past several years. + +**Cure.** Audit content quality (does it match what worked previously?). Audit cadence (within platform-rewarded range?). Check account-health signals (engagement on others' content, not just own posts; profile completeness; consistent branding). If algorithm shifts are the cause, content patterns may need recalibration to fit current algorithmic preferences. + +--- + +## Failure 5: PR pitches ignored + +**Symptom.** The program pitches journalists for coverage. Most pitches get ignored. Coverage is rare. + +**Diagnosis.** Mass-blast pitching, or relationships not built before pitching, or pitches not specific to recipient. + +**Cure.** Apply the relationship-first PR principle (see `earned-channel-work.md`). Build relationships with relevant journalists over months before pitching. Pitch specific to recipient with reference to their recent work. Reduce pitch volume; increase pitch quality. + +**Timeline.** PR relationships build over 1-3 years. Programs in mass-blast mode cannot fix this in a quarter; the cure is multi-year. + +--- + +## Failure 6: Heavy paid investment, low engagement + +**Symptom.** The program spends significantly on paid amplification. Engagement metrics are low. Cost-per-engagement keeps rising. + +**Diagnosis.** Paid amplification is amplifying low-organic-engagement content. Or paid is substituting for owned-channel investment. Or both. + +**Cure.** Apply the boost-organic pattern. Only boost pieces that have demonstrated organic engagement. Reduce paid spend on pieces without organic validation. Reallocate capacity toward owned-channel investment for long-term durability. + +--- + +## Failure 7: No measurement + +**Symptom.** The team operates on intuition about which channels are working. Different team members have different intuitions. Decisions about cadence, channel mix, and capacity are not informed by data. + +**Diagnosis.** No measurement infrastructure or no measurement-to-decision discipline. + +**Cure.** Establish per-channel metrics; channel-level analysis; cross-channel attribution. Quarterly measurement reviews that produce specific decision changes. See `distribution-measurement.md` for the discipline. + +--- + +## Failure 8: Posting without distribution + +**Symptom.** Content publishes. The piece appears on the blog and is shared once on social. The team considers distribution complete. + +**Diagnosis.** Distribution is treated as the act of posting. The work of getting content TO audiences is not happening. + +**Cure.** Plan distribution at production time. Each piece has a distribution plan: which channels, what cadence, what cross-channel co-promotion. Distribution is part of the production work, not an afterthought. + +--- + +## Failure 9: Campaign launches landing quietly + +**Symptom.** The team prepared a flagship launch with significant cross-format coordination. Launch day arrives. Engagement is muted. + +**Diagnosis.** Sustaining cadence was insufficient before the launch. Audiences were not warm; the campaign moment did not feel like a campaign moment because no audience habit primed it. + +**Cure.** Build sustaining cadence first. Campaign rhythm is earned by sustaining cadence. Programs that try to spike attention without sustaining baseline produce limited campaign engagement. + +--- + +## Failure 10: Owned audience small after years + +**Symptom.** After 2-3 years of program operation, the newsletter has 800 subscribers; the blog gets 5,000 monthly visits; the community is small. + +**Diagnosis.** Long-term investment in owned channels was skipped. Program reach (if there is reach) is rented from third parties. + +**Cure.** Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +--- + +## Failure 11: Earned channels not producing + +**Symptom.** The program has occasional coverage from third parties but no reliable earned-channel reach. Mentions are rare; syndication is informal; AI-search citation rates are low. + +**Diagnosis.** Earned channels are being treated as automatic. Relationship investment, pitching discipline, and citation-hook content design are not in place. + +**Cure.** Apply the earned-channel investment discipline. Specific capacity to relationship-building, pitching, syndication, citation tracking. Investment compounds over years. + +--- + +## Failure 12: Paid distribution costs rising + +**Symptom.** Paid amplification was producing acceptable cost-per-engagement 12-18 months ago. Costs have risen 50-100% since then. Engagement is similar; costs are higher. + +**Diagnosis.** Auction dynamics on paid platforms. Programs heavily dependent on paid see costs rise without offsetting owned/earned investment that would reduce paid dependence. + +**Cure.** Build owned and earned channels to reduce paid dependence. Within paid, focus on the highest-ROI placements; cut lower-performing paid spend. Recognize that paid costs typically rise over time on auction-based platforms; budget assumptions should account for this. + +--- + +## Failure 13: Channels mismatched to audience + +**Symptom.** The program is present on multiple channels. Engagement is low across most of them. The team is confused because the channels seemed obvious choices. + +**Diagnosis.** Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +**Cure.** Run the audience-channel audit (see `audience-channel-matching.md`). Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. + +--- + +## Failure 14: Cadence too aggressive + +**Symptom.** Email subscribers are unsubscribing at higher rates. Social engagement is declining despite increased posting volume. The team is producing more content per week than ever; reception is worse. + +**Diagnosis.** Cadence has exceeded audience attention norms. The team is over-publishing. + +**Cure.** Reduce cadence to channel norms. Test reduced frequency for 6-8 weeks; observe whether engagement improves and unsubscribes slow. Most programs benefit from disciplined cadence rather than maximal cadence. + +--- + +## Failure 15: Cadence inconsistent + +**Symptom.** The program publishes 3 times in a week, then nothing for 3 weeks, then 5 times in 4 days. Audiences cannot develop habit. + +**Diagnosis.** No cadence discipline. Production happens when capacity allows; distribution follows production rather than following audience-attention rhythm. + +**Cure.** Establish cadence targets per channel. Build content calendars that smooth publication across the period. Capacity that produces content unevenly should distribute the publication evenly even if production was uneven (held pieces release on schedule). + +--- + +## Failure 16: No campaign rhythm + +**Symptom.** The program runs sustained cadence consistently. Flagship launches happen. The launches receive routine treatment; no campaign coordination produces outsized attention. + +**Diagnosis.** Campaign rhythm has not been built. The program has sustained cadence but no concentrated moments. + +**Cure.** Plan 4-12 campaign moments per year. Each campaign concentrates cross-format distribution for 4-6 weeks. The campaigns are earned by the sustaining cadence; together they produce the rhythm strong programs use. + +--- + +## The cross-cutting pattern + +Most distribution failures share a single root: treating distribution as posting-after-publishing rather than as the equal half of the work. + +Posting-after-publishing thinking treats publication as the end of the work. The piece goes live; minimal distribution work follows; reach is whatever happens organically. Output: most pieces reach a fraction of their potential audience. + +Distribution-as-half-the-work thinking treats distribution as a discipline equal to production. Channel choices are deliberate; cadence is calibrated; owned-earned-paid mix is strategic; measurement informs decisions. Output: pieces reach engaged audiences because the distribution work earned the reach. + +The fix for almost any distribution failure is the same: treat distribution as a real discipline, not as posting. Allocate capacity proportionate to its importance. The capacity required is significant; the value extracted is also significant. + +--- + +## Methodology-level choices that stay in the public skill + +The sixteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the distribution-as-half-the-work framing. + +## Implementation choices that stay internal + +Specific tooling for distribution tracking. Specific reporting templates for distribution outcomes. Specific reviewer training on per-channel conventions. Specific automation that flags distribution gaps. The team's own conventions for failure-pattern detection in their distribution program. These vary by team and tooling. diff --git a/skills/content-distribution/references/content-channel-matching.md b/skills/content-distribution/references/content-channel-matching.md new file mode 100644 index 0000000..6fcbf13 --- /dev/null +++ b/skills/content-distribution/references/content-channel-matching.md @@ -0,0 +1,181 @@ +# Content-channel matching + +Format-channel fit decisions. The compose-with-repurposing pattern. The format-mismatch failure mode that produces low engagement even when audience and channel match. + +Audience-channel matching answers "where is the audience?" Content-channel matching answers "does this format fit this channel?" Both must hold for distribution to produce engagement. + +--- + +## Format-channel fit examples + +How specific formats land on specific channels. + +### Long-form analytical text + +**Strong fit.** Newsletter (long-form-tolerant subscribers expect depth). Owned blog (long-form is the blog's native register). LinkedIn long posts (the platform rewards substantive long content). X threads (when the community fits and the thread is well-paced). + +**Weak fit.** Instagram (the format does not support text-driven content as primary). TikTok (audiences come for short-form video, not long text). Most podcast platforms (audio is the format; long-form text is not what audiences came for). + +### Short-form video + +**Strong fit.** TikTok, Reels, YouTube Shorts (the platforms' native formats). Increasingly LinkedIn video (the platform has invested in video). Twitter/X video for some communities. + +**Weak fit.** Newsletter (where text leads and video is a supplement). Owned blog (where written long-form leads). Most podcast platforms (audio-only consumption). + +### Statistic-driven content + +**Strong fit.** Social with quote-graphic visual treatment (LinkedIn, X, Instagram with the right design). AI search snippets (search engines weight statistics with named sources). Podcast mentions (host-read statistic + source citation works well). + +**Weak fit.** As primary format on owned blog (where context develops the stat; the stat alone is thin). Newsletter as the entire content (the stat without development underdelivers). + +### Conversational expert content + +**Strong fit.** Podcasts (the format is conversational by design). Video interviews (long-form video supports the conversational depth). Long social threads on platforms where substantive content is rewarded. + +**Weak fit.** Short-form video (the conversational depth does not fit 60-second windows). Newsletter (where edited prose fits better than conversational transcript). + +### Reference content (definitions, glossaries, FAQs) + +**Strong fit.** Owned blog and FAQ pages (canonical home). AI search snippets (citation-ready). Documentation sites (where reference is the format). + +**Weak fit.** Most social channels (reference content does not earn engagement on attention-driven feeds). Podcasts (reference content does not work in audio). + +### Visual narrative content (case studies with custom visuals, illustrated guides) + +**Strong fit.** Instagram (visual-first). Pinterest (visual reference). Owned blog with strong design treatment. + +**Weak fit.** Podcast (audio cannot carry visual content). Newsletter (most newsletters do not support rich visual treatment). + +--- + +## The compose-with-repurposing pattern + +When the audience is on a channel but the source format does not fit, the right answer is often to repurpose into a format that does fit. + +**The pattern.** + +- Source piece: 5,000-word whitepaper. +- Audience: present and engaged on TikTok (consumer-oriented program; younger demographic). +- Direct distribution: 5,000-word whitepaper does not fit TikTok. +- Compose-with-repurposing: produce 60-second video derivatives from the whitepaper's key claims, framed for TikTok conventions. Distribute the derivatives on TikTok; keep the whitepaper as the source for audiences who want depth. + +**The discipline.** Distribution is downstream of repurposing. A program with strong audience-channel matching but weak content-channel matching solves it through repurposing, not through distributing inappropriate formats. + +**See `content-repurposing`** for the cross-format adaptation discipline. The two skills compose: repurpose first to fit the channel; then distribute on the channel. + +--- + +## The format-mismatch failure mode + +The pattern when content-channel matching is skipped. + +**The symptom.** The program is present on the right channels (audience-channel matching held). Engagement is still low. The team is confused because the channels seem right but the content is not landing. + +**The diagnosis.** The format does not fit the channel even though the audience is there. The audience is on the channel for a different kind of content; the program's content does not match the channel's content expectations. + +**The cure.** Identify the format-channel mismatches. For channels with strong audience-channel match but weak content-channel match, repurpose to fit. For channels where neither matching holds, cut the channel. + +**Recovery time.** Format-mismatch fixes through repurposing typically produce visible engagement improvements within 4-12 weeks as the new format derivatives accumulate. + +--- + +## Format conventions per channel + +Beyond the strong/weak fit, each channel has specific conventions that distinguish good fit from forced fit. + +### LinkedIn long-form posts + +- 800-2,500 character body. +- First 1-3 lines must hook (truncation point). +- Short paragraphs, white space, occasional emphasis. +- Specific argument or position; vague observations underperform. +- Engagement-earning closes (questions, polarizing claims, specific examples). + +### X/Twitter threads + +- 5-15 posts typical for substantive threads. +- First post must hook; the thread is read sequentially. +- Each post is a complete thought, not a 280-character split of a longer thought. +- Conclusion specific. + +### Newsletter (substantive content) + +- 200-800 words for typical sends; 1,500-3,000 for engaged-audience long-form newsletters. +- Subject line and preheader bear most engagement load. +- Plain prose paragraphs render reliably. +- Single clear CTA per send. + +### Podcast + +- Spoken-language sentence structure. +- Conversational pacing with examples and asides. +- Show notes with links and structured summary. +- Consistent episode length; audiences develop expectations. + +### Owned blog + +- Format depends on the source-piece type; long-form articles, listicles, definitive guides, case studies, etc. +- SEO conventions: target keyword in title and headings, internal linking, schema markup. +- Visual rhythm appropriate to length. + +### TikTok / Reels / Shorts + +- 60-90 seconds typical. +- Hook in first 1-2 seconds. +- Captions essential. +- Single specific point. +- Visual variation, motion, or text-on-screen design. + +### Instagram (feed posts) + +- Visual-first; images carry the post's immediate impact. +- Caption supplements; not all viewers expand caption. +- Conventions vary by subgenre (educational carousels, product photography, lifestyle imagery). + +### YouTube (long-form) + +- 8-30 minutes typical for substantive content. +- Pacing for spoken delivery. +- Visual variation. +- Audio quality matters more than video quality. +- Thumbnail and title bear most click-through load. + +### AI-search snippets + +- 40-80 words for FAQ-style; 100-200 words for paragraph-style. +- Standalone meaning. +- Named-source citations. +- Specific framings. +- Schema markup where applicable. + +--- + +## Format adaptation per channel within a single source + +A worked example: a research report that distributes across multiple channels. + +**Source.** 8,000-word research report on B2B paid media benchmarks. + +**Distribution by channel with content adaptation.** + +- **Owned blog.** Full report as the canonical version. Schema-marked. Internal-linked from related pieces. Sections support deep linking. +- **Newsletter (substantive subscribers).** A 1,200-word digest sending the report's key findings, with a clear CTA to read the full report. +- **LinkedIn long posts.** 4-6 long-form posts, each developing one finding from the report. Each post includes the report's most relevant statistic with named-source attribution. +- **X threads.** 2-3 threads from the report, each focused on a specific finding. Threads link to the report. +- **Podcast.** One episode interviewing a practitioner who has applied the report's findings, with the report as the show's spine. +- **TikTok / Reels.** Statistic-driven 60-second videos, one per key statistic. Custom graphic treatment for each. +- **AI-search snippets.** 15-20 FAQ extractions from the report. Schema-marked FAQ page on the owned property. +- **Promoted newsletter.** Sponsored placement in 1-2 industry newsletters whose audience overlaps with the report's target. +- **Boosted social.** Boost the LinkedIn posts that earn the highest organic engagement. + +The example shows the compose-with-repurposing pattern in practice. The source is one piece; the distribution adapts per channel. The cross-format set composes with the channel choices to produce engagement appropriate to each channel's conventions. + +--- + +## Methodology-level choices that stay in the public skill + +The format-channel fit examples, the compose-with-repurposing pattern, the format-mismatch failure mode, the format conventions per channel, the worked example of multi-channel distribution from one source. + +## Implementation choices that stay internal + +Specific platform tooling for format-specific publishing. Specific design templates per channel-format combination. Specific automation for cross-channel scheduling. The team's own conventions for format-fit decisions when ambiguous. These vary by team, tooling, and brand voice. diff --git a/skills/content-distribution/references/distribution-cadence-patterns.md b/skills/content-distribution/references/distribution-cadence-patterns.md new file mode 100644 index 0000000..cc20c8b --- /dev/null +++ b/skills/content-distribution/references/distribution-cadence-patterns.md @@ -0,0 +1,183 @@ +# Distribution cadence patterns + +Frequency, mix, rhythm. Sustaining vs campaign rhythm. Common cadence patterns by program type. The audit that catches cadence mismatches. + +Cadence is the rhythm of a program's distribution: how often each channel publishes, what mix of owned-earned-paid, and how steady-state baseline relates to campaign spikes. The wrong cadence produces predictable engagement decline: too aggressive exhausts audiences; too sparse loses connection; mismatched to channel attention rhythm produces underperformance at any frequency. + +--- + +## Cadence axes + +Three axes that together define a program's distribution cadence. + +**Frequency per channel.** How often the program publishes to each channel. Newsletter weekly vs bi-weekly. LinkedIn 3 posts per week vs 1 per week. X 5-10 posts per week vs occasional. The frequency per channel is calibrated to the channel's audience attention rhythm. + +**Mix.** What proportion of distribution is owned vs earned vs paid. What proportion of pieces are original vs derivative. The mix reflects program strategy: owned-heavy programs invest in long-term audience-building; paid-heavy programs prioritize immediate reach. + +**Rhythm.** Sustaining baseline cadence vs campaign spikes. Most programs have a steady-state rhythm punctuated by occasional campaign moments around flagship launches. The rhythm shape determines how audiences experience the program. + +--- + +## Common cadence patterns by program type + +Cadences that show up repeatedly across program shapes. + +### B2B program with content-led demand generation + +**Newsletter.** Weekly. Substantive sends; subscribers expect depth. + +**Blog.** 2-4 posts per week. Mix of new pieces, refresh updates, and cross-format derivatives. + +**LinkedIn.** 3-5 posts per week. Mix of long-form posts, link drops to blog content, occasional video. + +**X/Twitter.** 5-10 posts per week. Higher cadence than LinkedIn; mix of original observations, links, and replies. + +**Podcast.** Bi-weekly or weekly episodes. + +**Earned channels.** Pitches and PR work continuous; coverage when earned. + +**Paid amplification.** Boost of best-performing organic pieces; occasional sponsored newsletter sends. + +**Campaign rhythm.** Quarterly spikes around flagship launches: cross-format wave for 4-6 weeks per launch. + +### Consumer brand with broad-audience reach goals + +**Newsletter.** Weekly or 2x weekly depending on subscriber engagement. + +**Blog or content site.** 1-2 posts per week. + +**Instagram.** Daily content (often a mix of feed posts, stories, and reels). + +**TikTok.** 2-4 posts per week. + +**YouTube.** Weekly long-form video plus shorts. + +**Earned channels.** PR for major moments; influencer relationships continuous. + +**Paid amplification.** Continuous; brands often run paid amplification on most major content as part of standard practice. + +**Campaign rhythm.** Heavier campaign spikes around product launches, seasonal moments, and brand events. + +### Niche specialist program with concentrated audience + +**Newsletter.** Weekly or bi-weekly. Substantive sends; the audience is concentrated and engaged. + +**Blog.** 1-2 posts per month. Quality-focused; depth over volume. + +**Specific platforms (one or two).** 2-3 posts per week on the platforms where the niche audience engages. + +**Podcast (if applicable).** Bi-weekly or monthly episodes. + +**Earned channels.** High prioritization; relationships with niche publications and influencers compound. + +**Paid amplification.** Selective; most niche programs benefit more from earned-channel investment than from paid amplification. + +**Campaign rhythm.** Less pronounced than broader programs; sustaining cadence is the dominant rhythm. + +### Founder-led brand with personal-brand element + +**Newsletter.** Weekly; founder-voice register; personal insight alongside program content. + +**LinkedIn.** Daily posts (or near-daily). Founder voice; personal observations alongside program content. + +**X/Twitter.** Daily posts with conversation engagement. + +**Podcast.** Often the founder hosts; weekly episodes. + +**Earned channels.** Founder builds relationships personally; PR coverage often person-driven. + +**Paid amplification.** Selective; the program builds on organic reach earned by founder authority. + +**Campaign rhythm.** Less formal campaigns; the program reads more as continuous founder voice than as discrete campaign moments. + +--- + +## Sustaining vs campaign rhythm + +The relationship between baseline cadence and campaign spikes. + +**Sustaining cadence.** The baseline rhythm. Audiences expect this cadence; deviations affect engagement. Sustaining cadence builds audience habit (subscribers who expect a Tuesday send keep paying attention; subscribers who get inconsistent sends start ignoring even the good ones). + +**Campaign rhythm.** Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +**The relationship.** Campaign rhythm is earned by sustaining cadence. Programs without sustaining cadence cannot run effective campaigns; the audiences are not warm. Campaigns that spike out of nowhere produce limited engagement because no audience habit primes the moment. + +**The balance.** Strong programs run mostly sustaining cadence with occasional campaign spikes. The campaign spikes are 4-6 weeks total, 4-12 times per year. Programs running continuous "campaign" rhythm exhaust audiences; programs running only sustaining without campaigns miss the moments where flagship work could earn outsized attention. + +--- + +## Per-channel cadence tuning + +Each channel rewards different cadences. Cadence tuning matches channel-specific norms. + +**Newsletter.** Weekly is the most common B2B cadence. Bi-weekly works for higher-investment formats. Daily works for highly-engaged subscriber bases. The cadence should be predictable: subscribers should know roughly when to expect sends. + +**LinkedIn.** Algorithmic favor rewards 1-2 posts per day for individual accounts; company pages typically post less frequently (2-5 posts per week). Lower cadences (1-2 per week) work but limit reach. + +**X/Twitter.** The platform rewards higher cadence than other platforms. 5-15 posts per day is normal for engaged accounts; less can work but limits reach. + +**Instagram.** 1 post per day is common for engaged consumer accounts; 3-5 per week works for B2B and niche programs. Stories and reels often have higher cadence than feed posts. + +**TikTok.** Algorithmic recommendation rewards higher cadence; 1+ posts per day typical for accounts trying to grow. + +**YouTube.** Weekly long-form video is the upper-frequency norm; many channels publish less frequently. Shorts can publish more often (multiple per week). + +**Podcast.** Weekly is the most common cadence; bi-weekly works for higher-investment shows; daily works for high-volume formats (news-style podcasts). + +**Owned blog.** SEO programs benefit from regular publishing (2-4 posts per week typical for active programs); less frequent publishing limits the program's compounding traffic potential. + +--- + +## The cadence audit + +A short framework for auditing a program's cadence. + +1. **Pull current cadence per channel over the last 90 days.** What is the program actually doing? Often differs from the program's stated cadence target. +2. **Compare to channel-specific norms.** Are channel cadences within the engagement-rewarding range, or are they too sparse or too aggressive? +3. **Identify cadence inconsistencies.** Are there gaps where the program goes silent for weeks, then spikes? Inconsistency damages audience habit even when total volume is similar. +4. **Match cadence to capacity.** Is the program able to sustain the current cadences, or is it running unsustainably? +5. **Identify the campaign rhythm.** When were the last 3 flagship launches? Did sustaining cadence support them? Did campaigns earn outsized attention? + +The audit produces a calibration plan: which cadences to maintain, which to adjust, where the program is over-investing or under-investing. + +--- + +## Cadence anti-patterns + +**Inconsistent cadence.** 3 posts in one week, then nothing for 3 weeks. Audiences cannot develop habit; the program disappears between bursts. + +**Volume-driven cadence.** "We need to post X times per week" without reference to channel norms or audience attention. Volume without engagement is presence; presence without engagement is wasted capacity. + +**Identical cadence across channels.** Treating LinkedIn, X, TikTok, and newsletter all on the same cadence ignores channel-specific norms. Each channel has a different attention rhythm. + +**No campaign rhythm.** Pure sustaining cadence with no spikes. Flagship launches receive routine treatment; the moments where the program could earn outsized attention pass without the campaign coordination they warrant. + +**Continuous campaign rhythm.** Pure campaign rhythm with no sustaining baseline. Audiences never develop habit; every "launch" feels like another launch in a continuous stream of launches. + +**Cadence beyond capacity.** The team commits to LinkedIn daily, X 10x per day, newsletter twice weekly. Capacity cannot sustain; cadence drifts; audiences notice the drift. + +--- + +## When to adjust cadence + +Signals that cadence needs change. + +**Engagement declining steadily on a channel.** May indicate cadence too aggressive (audience fatigue) or too sparse (audience disengagement) or content-fit issues (different problem). Investigate. + +**Subscriber unsubscribes spiking on newsletter.** Cadence too aggressive, or content quality declining, or both. Cure depends on diagnosis. + +**Algorithm changes on a platform.** Some platform algorithm shifts reward different cadences. Adjust based on observed engagement signals. + +**Capacity changes.** Team grows or shrinks; cadence should match sustainable capacity. Programs with shrinking teams that maintain prior cadence often produce drift in quality. + +**Audience-research findings.** New data about audience attention rhythms. Adjust cadence to fit revealed audience patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The cadence axes, common cadence patterns by program type, sustaining-vs-campaign rhythm, per-channel cadence tuning, the cadence audit, the cadence anti-patterns, the signals for cadence adjustment. + +## Implementation choices that stay internal + +Specific scheduling tools the team uses. Specific cadence-tracking dashboards. Specific cadence-by-channel calendars. The team's own conventions for cadence-vs-quality tradeoffs when capacity is constrained. These vary by team, tooling, and program shape. diff --git a/skills/content-distribution/references/distribution-measurement.md b/skills/content-distribution/references/distribution-measurement.md new file mode 100644 index 0000000..c1d73f9 --- /dev/null +++ b/skills/content-distribution/references/distribution-measurement.md @@ -0,0 +1,203 @@ +# Distribution measurement + +Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. The discipline that prevents distribution-theater and turns distribution into a learning system. + +Distribution without measurement runs on assumption. Channels stay in the mix because they have always been in the mix; cadence stays at current levels because nobody has asked whether it is right; paid spend continues because budget exists. Measurement is the discipline that surfaces what is actually working and what is not. + +--- + +## Per-channel metrics + +Metrics organized by what they reveal about a channel's effectiveness. + +**Reach metrics.** + +- Impressions: how many times the content was shown. +- Unique reach: how many unique people saw the content. +- Audience growth: how the channel's owned audience size is changing. + +**Engagement metrics.** + +- Click-through rate (CTR): clicks divided by impressions. +- Time-on-page: how long visitors stay on the linked content. +- Scroll depth: how far down the content visitors scroll. +- Completion rate: for video and audio, what percentage finishes. +- Comment, share, and reaction signals on social. +- Reply rate on email. + +**Conversion metrics.** + +- Newsletter signups attributed to the channel. +- Content downloads attributed to the channel. +- Qualified-lead actions (form submissions, demo requests, free-trial starts). +- Sales-cycle progression for B2B programs. +- Attributed revenue for revenue-tracked programs. + +**Channel-health metrics.** + +- Audience retention rate (subscribers staying vs unsubscribing). +- Engagement-rate trend over time (rising, stable, falling). +- Algorithm-favor signals (for platform-controlled channels). +- Deliverability rate (for email). + +--- + +## Channel-level analysis + +Aggregating metrics into channel effectiveness assessments. + +**Engagement-per-distribution-effort.** + +- Some channels look impressive (high reach numbers) but produce low engagement. +- Some channels produce moderate reach but very high engagement. +- The channels that compound value are usually the engagement-heavy ones, not the reach-heavy ones. + +**Conversion-per-channel.** + +- Reach without conversion is vanity. Conversion is value. +- Channels driving conversion at favorable cost (whether owned-channel investment cost or paid-channel spend) earn their place in the mix. +- Channels driving impressive reach but no conversion may be building brand awareness (which is real value) or producing nothing of value (which is wasted capacity). + +**Trend over time.** + +- Channels' performance changes. Algorithm shifts, audience migrations, competitive landscape changes affect channel effectiveness. +- A channel that was effective 18 months ago may be underperforming now. +- A channel that was marginal 18 months ago may be the program's strongest now. +- Quarterly review of channel-level trends catches these shifts. + +**The relative-effectiveness audit.** + +Rank channels by engagement-per-effort and by conversion-per-effort. Channels at the top of both rankings are the program's strongest; channels at the bottom of both are candidates for cutting or restructuring. + +--- + +## Cross-channel attribution + +The audience member encounters the program on multiple channels before converting. Attribution should reflect this reality. + +**Single-touch attribution failures.** + +- **Last-touch attribution.** Credits the last channel before conversion. Misrepresents which channels actually drove the audience relationship; usually overweights the conversion channel (often newsletter or direct site visit) and underweights the discovery channels. +- **First-touch attribution.** Credits the first channel of contact. Misrepresents the role of nurturing channels; usually overweights discovery channels and underweights nurturing channels. + +**Multi-touch attribution patterns.** + +- **Linear attribution.** Equal weight to all touchpoints. Simple; usually a step up from single-touch. +- **Time-decay attribution.** More weight to touchpoints closer to conversion. Reflects the commonsense intuition that recent touches matter more than distant ones. +- **Position-based attribution.** Significant weight to first and last touch; remaining weight distributed across middle touches. Reflects the importance of discovery and conversion moments. +- **Data-driven attribution.** Algorithmic weighting based on observed conversion patterns. Most accurate; requires sufficient data and tooling. + +**The attribution honesty discipline.** + +- Attribution models are simplifications. None is "correct"; all are useful approximations. +- Programs should pick an attribution model and stay consistent. Switching attribution models produces apparent performance changes that are not real. +- Cross-reference attribution data with other signals (subscriber surveys, sales conversation reports). Triangulation is more honest than relying on attribution data alone. + +--- + +## The measurement-honest program + +Discipline that turns measurement into a decision-making input rather than into reporting theater. + +**Cuts channels that consistently underperform.** + +- A channel underperforming for 2-3 quarters is a real signal, not noise. +- Cutting underperforming channels reallocates capacity to channels that produce. +- The decision is hard because cutting feels like admitting failure; programs that cut decisively outperform programs that maintain everything indefinitely. + +**Increases investment in channels that consistently produce.** + +- Strong channels deserve disproportionate investment. +- Programs often spread investment evenly across channels regardless of performance; the measurement-honest discipline allocates investment to where return is highest. + +**Adjusts cadence based on engagement patterns.** + +- Cadence that is too aggressive shows up in declining engagement and rising unsubscribes. +- Cadence that is too sparse shows up in audience-habit decay. +- Engagement patterns inform cadence adjustments. + +**Calibrates paid spend based on organic validation.** + +- Boost what organic validates. +- Reduce or eliminate paid spend on content that does not earn organic engagement. +- Paid spend should be a function of organic signal, not a function of available budget. + +--- + +## The measurement-theater anti-pattern + +When measurement is performed without informing decisions. + +**The pattern.** The team produces quarterly reports with channel-level metrics. Reports are presented to leadership. Decisions are not changed based on the reports. Underperforming channels stay in the mix; over-performing channels do not get additional investment. The program continues as it would have continued without the measurement. + +**Why it happens.** + +- Measurement is treated as performance theater rather than as decision input. +- Leadership signals that all channels should continue (political pressure, sunk cost, brand reasons). +- The team has measurement capacity but lacks decision-authority over distribution. + +**The cure.** Tie measurement to specific decisions. Each quarter, the measurement review produces a list of changes: cuts, additions, cadence adjustments, capacity reallocations. Reviews without decisions are theater. + +--- + +## Common measurement failures + +**No measurement.** Distribution runs on assumption. Channels stay in the mix because they always have. Cadence and capacity allocation persist regardless of effectiveness. + +**Measurement without action.** Measurement is performed; decisions are not changed. The program runs as if no measurement happened. + +**Vanity metrics.** Reach and impressions reported as primary success metrics. Engagement and conversion underreported. The program looks like it is working when it may not be. + +**Single-touch attribution dominance.** All attribution analysis runs on last-touch or first-touch. The realities of multi-touch journeys are missed. + +**No trend analysis.** Channel performance reported in quarterly snapshots; trends across quarters are not surfaced. Channel decay is detected late. + +**Cross-program comparison failures.** The program compares itself to industry benchmarks without context. Benchmark numbers from other industries or audience segments may not apply; comparison produces false signals. + +--- + +## Measurement infrastructure + +The tooling and processes that support measurement. + +**Analytics platform.** Web analytics that tracks per-channel traffic, engagement, and conversion. Standard requirement for any program with a content site. + +**Email analytics.** Open rates, click-through rates, unsubscribe rates, deliverability rates. Standard for any program with a newsletter. + +**Social analytics.** Per-platform analytics from each social platform; supplemented by social-listening tools where the program tracks mentions and shares beyond direct posts. + +**Attribution tooling.** From simple UTM tracking and Google Analytics multi-touch reports to sophisticated attribution platforms (depending on program scale and complexity). + +**Channel-specific dashboards.** Programs often build per-channel dashboards that surface the metrics most relevant to that channel's optimization. + +**Cross-channel rollup.** A program-level dashboard that aggregates channel-level data into a coherent view of distribution effectiveness. + +The infrastructure cost is real; the alternative (running distribution without measurement) is more expensive over time because capacity gets allocated to wrong places. + +--- + +## Measurement cadence + +When to measure what. + +**Continuous.** Some metrics update daily or weekly: website traffic, social engagement, email opens. The team monitors these continuously. + +**Weekly.** Per-channel summaries of recent performance. Catches sharp decay or sharp improvements early. + +**Monthly.** Channel-level rollup. Detects trends developing across multiple weeks. + +**Quarterly.** Strategic measurement review. Decisions about channel cuts, additions, cadence adjustments, capacity reallocations. + +**Annual.** Program-level measurement review. Strategic shifts in channel mix, attribution-model adjustments, capacity reallocations across the program. + +The cadence should match the decision cadence. Programs with monthly capacity-allocation decisions need monthly measurement; programs with quarterly decisions need quarterly measurement. + +--- + +## Methodology-level choices that stay in the public skill + +The per-channel metric categories, channel-level analysis approaches, cross-channel attribution patterns, the measurement-honest discipline, the measurement-theater anti-pattern, common measurement failures, infrastructure requirements, measurement cadence. + +## Implementation choices that stay internal + +Specific analytics platforms (the team's chosen GA configuration, alternative platforms, attribution tools). Specific dashboard designs and reporting templates. Specific UTM tagging conventions. Specific attribution-model parameters tuned for the program. The team's own conventions for benchmark comparisons. These vary by team, tooling, and program scale. diff --git a/skills/content-distribution/references/earned-channel-work.md b/skills/content-distribution/references/earned-channel-work.md new file mode 100644 index 0000000..690d86b --- /dev/null +++ b/skills/content-distribution/references/earned-channel-work.md @@ -0,0 +1,172 @@ +# Earned-channel work + +PR, syndication, mentions, AI-search citation, word of mouth. The relationship investment that compounds over years. The pitching discipline that earns coverage rather than burning relationships. + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real: relationships built over years, pitches that demonstrate the program's value, content that earns citation. Programs treating earned channels as automatic produce nothing; programs investing in the relationships earn ongoing channel access. + +--- + +## PR and press + +Journalists, podcasters, newsletter operators who cover the program's content. + +**The relationship-first principle.** Coverage follows relationships. Cold pitches from unknown senders get ignored at high rates; warm pitches from known senders get read. Programs that build relationships before they need coverage are the programs that earn coverage when they have flagship work to share. + +**Building relationships.** + +- Read the journalists, podcasters, and operators in the program's space. Know what they cover, what their angles are, what they have written or aired recently. +- Engage substantively before pitching. Comment thoughtfully on their work; share their pieces with attribution; respond if they ask for input. +- Build the relationship to a level of mutual recognition before the first pitch. + +**Pitching when the relationship exists.** + +- Pitch specific to the recipient. Reference their recent work; explain why the program's content fits their angle. +- Lead with the angle, not with the company. Recipients care about the story, not about the program's brand. +- Provide everything the recipient needs: the source piece, key statistics, possible quotes, a clear point of contact. +- Make it easy to say yes; make it easy to say no. + +**The mass-blast pitching anti-pattern.** + +- Identical pitches sent to dozens of recipients. Recipients detect mass-blast quickly; relationships are damaged not built. +- Pitches focused on the program rather than on the story. Recipients filter these as ads. +- Follow-up pressure. Excessive follow-ups damage future relationship potential. + +**The PR investment timeline.** Real PR relationships build over 1-3 years. Programs without prior PR investment cannot generate coverage on a deadline; programs with sustained investment have relationships that produce ongoing coverage. + +--- + +## Syndication + +Other publications republishing or excerpting the program's content with appropriate attribution. + +**The syndication exchange.** The program provides quality content; the partner provides reach into their audience. Both parties win when the exchange is fair. + +**Negotiation patterns.** + +- **Republishing with canonical link.** The partner runs the full piece; canonical link tag points to the program's version for SEO. Reach extends; SEO authority preserves. +- **Excerpt with link.** The partner runs an excerpt with a link to the full piece on the program's site. Less full reach but stronger funnel back to the program. +- **Republishing without canonical.** Less common; risks SEO duplication issues; should be avoided unless specifically negotiated with the partner about which version is canonical. + +**Common syndication failures.** + +- Canonical link mishandling. The piece appears on the partner's site as the canonical version; the program's version drops in rankings. +- Partner relationships not maintained. Syndication partners that stop running the program's content; the channel goes silent. +- Indiscriminate syndication. Every piece syndicated regardless of fit; partner audiences see content that does not match their interests; partner removes the program from rotation. + +**The selective-syndication discipline.** Not every piece warrants syndication. Match piece-to-partner: which pieces fit which partners; which partners' audiences will engage with which pieces. Selective syndication produces stronger partner relationships than blanket syndication. + +--- + +## Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +**Citation as compounding authority.** Each citation increases the program's authority signal. Citations from authoritative sources weight more than citations from less authoritative ones. Citation accumulation over years is one of the most durable signals of program quality. + +**Earning citations.** + +- Produce content with citation hooks. Original data; named frameworks; primary research; contrarian-but-defensible positions. +- Build identifiable phrasings or term coinages. If the program names a concept, others citing the concept cite the program. +- Make content discoverable when others are researching the topic. SEO and AI-search visibility matter for citation discoverability. + +**The generic-content-no-citation problem.** Pieces that do not have specific citation hooks rarely get cited even if they are well-written. The hook is what other writers reach for. + +**AI-search citation specifically.** AI engines cite content that matches their retrieval criteria. See `content-repurposing`'s AEO extraction patterns for the discipline of producing AI-citation-friendly content. Programs that design for AI citation earn more citations than programs that publish without that consideration. + +--- + +## Word of mouth and shares + +Audiences sharing pieces with their networks. + +**The hardest channel to engineer.** Word of mouth follows from genuine usefulness. Pieces that audiences want to share are pieces that are genuinely valuable; pieces that are generic do not get shared even if they are read. + +**Patterns that earn shares.** + +- Specific, useful content. Audiences share pieces that help them or that they think will help others. +- Citation-worthy content. Audiences share pieces they want to point to as references. +- Provocative-but-defensible content. Audiences share pieces that take a position they want to amplify. +- Memorable framings. Audiences share pieces that introduce concepts or framings they find useful. + +**Patterns that do not earn shares.** + +- Generic content. Pieces that say what every other piece on the topic says do not earn the share. +- Surface-level coverage. Pieces that scratch the surface without substantive depth do not feel worth sharing. +- Defensive content. Pieces that hedge every position do not earn the share because they do not say anything specific. + +**The measurement challenge.** Word-of-mouth sharing often happens in private channels (DMs, internal Slack, work emails) where the program cannot directly measure. Indirect signals: referral traffic from unknown sources, audience members reporting "a colleague sent me this," conversion-without-tracked-attribution. + +--- + +## Earned-channel investment + +The capacity allocation question. + +**Programs without earned-channel investment.** Treat earned channels as automatic. Coverage that happens, happens; coverage that does not happen, does not. Output: limited earned reach; the program is dependent on owned and paid distribution. + +**Programs with strategic earned-channel investment.** Allocate specific capacity to relationship-building, pitching, syndication negotiation, citation tracking. Output: earned channels become reliable distribution over years. + +**The investment shape.** + +- **PR work.** A specific person owns relationships and pitching. Investment level varies by program: from 5% of one person's time at smaller programs to dedicated PR roles at larger programs. +- **Syndication negotiation.** Periodic outreach to potential partners; relationship maintenance; canonical-link verification. +- **Citation tracking.** Monitoring where the program is being cited; engaging with those citations (thanking citers; building relationships with frequent citers). +- **AI-search citation.** Tracking AI engine citation rates; iterating on AEO extraction patterns based on what gets cited. + +**The investment payoff timeline.** Earned-channel investment compounds over 2-5 years. Year 1 produces limited returns; years 3-5 produce significant returns if the investment was sustained. + +--- + +## Common earned-channel failures + +**Mass-blast pitching.** Pitches sent to dozens of recipients identical or near-identical. Recipients detect; relationships damaged; future coverage potential reduced. + +**No relationship investment.** The program tries to "do PR" only when it has flagship work to share. Without prior relationship investment, pitches go cold even when the content is genuinely strong. + +**Syndication mishandled.** Canonical-link issues; partner relationships not maintained; SEO authority drained to partner sites. + +**No citation hooks.** Pieces produced without elements that earn citation. Mentions and AI-search citation rates stay low because nothing in the content prompts citation. + +**Earned channel as automatic.** Treating earned channels as if they happen on their own. Without investment, they do not. + +**Limited PR scope.** Pitching only the same 3-5 trade publications repeatedly. The relationship gets over-extended; coverage drops; broader earned-channel work is not happening. + +--- + +## Earned-channel measurement + +Earned channels are harder to measure than owned or paid, but measurement is still possible. + +**PR coverage.** + +- Volume: how many pieces of coverage per quarter. +- Quality: which publications, which authors, what reach those publications have. +- Sentiment: positive coverage, neutral, critical. +- Attribution: traffic and conversions sourced from coverage moments. + +**Syndication.** + +- Reach via partner: traffic and engagement on partner-published versions. +- Funnel back: traffic from partner content to program's own site. +- Authority preservation: SEO position holding given canonical link signaling. + +**Mentions and citations.** + +- Citation count over time. Tools that track mentions across the web help here. +- Citing-source quality. Citations from high-authority sources weight more. +- AI-search citation rates. Tools that track AI engine citations are emerging; the measurement infrastructure is improving. + +**Word of mouth.** + +- Indirect signals: referral traffic from unknown sources, audience reports, sustained organic growth without proportional paid amplification. +- Survey data: when audience members are asked how they discovered the program, word-of-mouth signals appear. + +--- + +## Methodology-level choices that stay in the public skill + +The relationship-first PR principle, the syndication exchange and selective-syndication discipline, the citation-earning patterns, the word-of-mouth observations, the earned-channel investment shape and timeline, the common failures, the measurement approaches. + +## Implementation choices that stay internal + +Specific PR-relationship CRM tooling. Specific pitching templates and tracking. Specific syndication negotiation conventions. Specific citation tracking software. Specific AI-search citation tracking infrastructure. The team's own conventions for relationship-investment cadence. These vary by team, budget, and program scope. diff --git a/skills/content-distribution/references/owned-channel-discipline.md b/skills/content-distribution/references/owned-channel-discipline.md new file mode 100644 index 0000000..3b3adbb --- /dev/null +++ b/skills/content-distribution/references/owned-channel-discipline.md @@ -0,0 +1,156 @@ +# Owned-channel discipline + +Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. The patterns that turn owned channels from posting infrastructure into durable distribution foundations. + +Owned channels are the most reliable distribution a program has. The newsletter delivers to every subscriber's inbox; the blog persists indefinitely; the owned social accounts run on the program's terms (within platform constraints). Programs that under-invest in owned channels become dependent on third-party distribution; when platforms change, when paid costs rise, when earned channels go quiet, the dependent program's reach collapses. + +--- + +## Newsletter discipline + +The most direct owned distribution. + +**The discipline shape.** + +- **Cadence consistency.** Subscribers develop expectations. Weekly send on Tuesdays gets opened more reliably than weekly send that drifts to Thursday or Wednesday or Friday. +- **Content quality matching subscriber expectations.** What subscribers signed up for; the program delivers it. Drift in quality (or in topic) produces unsubscribes. +- **Single CTA per send.** Multi-CTA emails dilute. Subscribers process one action; competing actions reduce all of them. +- **Deliverability hygiene.** Spam-trigger words, unbalanced text-to-image ratios, technical configuration (SPF, DKIM, DMARC) all affect deliverability. Programs that ignore deliverability watch open rates decline. +- **List health.** Engaged subscribers vs lapsed subscribers; pruning lapsed segments improves overall deliverability and engagement metrics. + +**Common newsletter failures.** + +- Cadence drift. The "weekly" newsletter that becomes bi-weekly, then monthly, then sporadic. Subscribers stop expecting; engagement decays. +- Subject lines that announce instead of earning the open. "Newsletter for week of November 14" performs worse than specific subject lines tied to the email's content. +- Multi-topic emails that try to cover everything the program produced this week. Single-topic focus produces stronger engagement. +- No segmentation. The same email goes to every subscriber regardless of interest patterns. Programs with multiple distinct content streams benefit from segmented sends. + +**See `email-sequences`** for the email-specific discipline including subject-line patterns, sequence design, and lifecycle campaigns. + +--- + +## Blog discipline + +The owned content home. + +**The discipline shape.** + +- **Architecture and technical SEO foundations.** Crawlability, indexability, page speed, schema markup. Without these, the blog cannot earn search traffic regardless of content quality. +- **Pillar and cluster organization.** Topical hubs that compound authority over years. See `pillar-content-architecture`. +- **Refresh discipline.** Library does not decay into staleness. See `content-refresh-system`. +- **Internal linking.** Strong internal-link graph that distributes authority and earns rankings. +- **On-page optimization.** Per-page SEO discipline. See `seo-onpage`. + +**Common blog failures.** + +- Publishing without distribution to the blog. The blog is the destination; if no traffic flows to it from owned and earned distribution, only the slowly-compounding search traffic builds. +- Architectural neglect. The blog's information architecture rots; URL structures change without redirects; old content drags down newer pages' authority. +- Refresh starvation. The library accumulates stale pieces; new pieces have to compete with the team's own decaying content for rankings. +- No design investment. The blog reads as a content dump rather than as a property; visitors do not return. + +**The blog as compounding asset.** A well-disciplined blog produces traffic for years. Programs that invest in blog foundations early earn compounding returns; programs that under-invest never earn the compounding effect. + +--- + +## Owned social discipline + +LinkedIn company page, X account, YouTube channel, Instagram account, etc. + +**The discipline shape.** + +- **Per-platform conventions.** Each platform rewards different content shapes. LinkedIn rewards substantive long-form posts; X rewards conversation; YouTube rewards specific topic and audio quality; Instagram rewards visuals. +- **Cadence calibrated to platform attention rhythm.** Daily on platforms that reward daily; weekly on platforms that work weekly. Mismatch reduces reach regardless of content quality. +- **Engagement-signal optimization.** Algorithmic recommendation rewards content that earns engagement signals (comments, shares, time-watched, click-through). Content designed for these signals reaches more. +- **Account-health hygiene.** Posting consistency; authentic engagement (not spam-replies); profile completeness; consistent branding. + +**Common owned-social failures.** + +- Cross-posting identical content across platforms. Each platform has different conventions; identical posts perform poorly on all platforms. +- Generic posting templates. Audiences detect template-driven posting; engagement decays. +- No engagement with the audience. Posting without responding to comments or engaging with industry conversations reduces algorithmic favor over time. +- Reliance on a single platform. Platform algorithms shift; programs dependent on one platform's reach are exposed to algorithm risk. + +**Owned vs platform-controlled.** Owned-social channels are owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. The distinction matters for risk: programs treating owned-social as fully owned underestimate platform-algorithm risk. + +--- + +## Podcast discipline + +Owned audio distribution. + +**The discipline shape.** + +- **Audio quality.** Listeners tolerate uneven video far more than uneven audio. Audio investment returns more than video investment up to a point. +- **Consistent episode cadence.** Weekly is most common; bi-weekly works for higher-investment shows. Drift undermines listener habit. +- **Show notes as derivative format.** Show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as their own derivative format with quality discipline. +- **Cross-platform distribution.** Apple Podcasts, Spotify, YouTube, Google Podcasts. Each is a discoverability surface. +- **Format consistency within the show.** Listeners develop expectations; format changes can lose listeners. + +**Common podcast failures.** + +- Production quality drift. The first 10 episodes are well-produced; episodes 30+ show production decay. +- No cross-platform distribution. The show lives on one platform; potential listeners on other platforms cannot find it. +- Show notes treated as afterthought. Thin show notes reduce SEO value and listener navigation. +- Cadence inconsistency. Drift between episodes undermines listener habit. + +**The podcast as relationship channel.** Engaged listeners feel connected to the host(s); the audience relationship is intimate. Podcasts produce trust signal that other channels often cannot match. + +--- + +## Community discipline + +Slack communities, Discord servers, dedicated discussion forums. + +**The discipline shape.** + +- **Active moderation.** Communities require continuous facilitation. Spam, off-topic content, and unaddressed conflict damage community health. +- **Sustained value-delivery.** Members come and stay because the community delivers value. Value can be peer connection, expert access, content access, or product feedback. +- **Integration with the broader content program.** Members get early access; program content is shared in the community; community feedback informs program decisions. +- **Member-driven content.** Strong communities have member-to-member interaction beyond program-to-member broadcasting. + +**Common community failures.** + +- Abandonment. Communities launched with fanfare and then under-staffed. Members leave; the community decays into a ghost town signaling the program's decline. +- Broadcast-only. The program posts to the community as if it were another social channel; no facilitation of member interaction. +- Membership-quality drift. Open communities accumulate members who do not contribute; the signal-to-noise ratio degrades. +- No moderation policy. Conflict, spam, or off-brand content erodes the community's character. + +**Community as audience-relationship multiplier.** The community is often the program's most engaged audience segment. Investment in the community returns at multiple points: feedback, advocacy, product input, content participation. + +--- + +## The starvation anti-pattern + +Programs that under-invest in owned channels become dependent on third-party distribution. + +**The pattern.** The program invests heavily in paid acquisition or in social platforms it does not own. Reach grows on those channels. The program does not build newsletter, blog, or community in proportion. When platforms change algorithms or paid costs rise, reach collapses; the program has no owned channels to fall back on. + +**The visibility.** Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscribes, account creations, community memberships). The reach is rented, not owned. + +**The cure.** Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +**Prevention.** Programs in early stages should over-invest in owned channels relative to the reach those channels initially produce. The investment compounds over years; the alternative is decade-long dependency on third-party distribution. + +--- + +## The owned-channel investment timeline + +Owned channels reward long investment. + +**Year 1.** Newsletter and blog established; cadence consistent; subscriber count and traffic both small. The investment feels like it is producing little; the cadence is the foundation. + +**Year 2-3.** Newsletter list grows; blog accumulates SEO traffic; community starts to form (if part of the strategy). The investment starts to compound; engagement signals improve. + +**Year 4+.** Owned channels are reliable distribution. Newsletter sends produce predictable engagement; blog earns substantial organic traffic; community is a meaningful audience asset. The early investment compounds. + +**The patience cost.** Owned-channel investment is multi-year; the visible returns lag the investment. Programs that abandon owned-channel investment in years 1-2 because returns feel small often regret it in years 3-5 when peers who sustained the investment are reaping the compounding effect. + +--- + +## Methodology-level choices that stay in the public skill + +The owned-channel disciplines (newsletter, blog, social, podcast, community), the common failures per channel type, the starvation anti-pattern, the investment timeline. + +## Implementation choices that stay internal + +Specific newsletter platforms and templates. Specific blog CMS and design systems. Specific social-publishing tools. Specific podcast hosting and editing tools. Specific community-management software (Slack, Discord, custom forums). The team's own conventions for cadence and quality thresholds. These vary by team, budget, and program scope. diff --git a/skills/content-distribution/references/paid-promotion-patterns.md b/skills/content-distribution/references/paid-promotion-patterns.md new file mode 100644 index 0000000..43dbd94 --- /dev/null +++ b/skills/content-distribution/references/paid-promotion-patterns.md @@ -0,0 +1,181 @@ +# Paid promotion patterns + +When boosting organic content earns its keep. The paid-as-substitute anti-pattern. The disciplines that distinguish strategic paid amplification from spending budget on content that did not validate organically. + +Paid promotion of organic content is an amplification layer. The pattern works when paid spend extends the reach of content that organic engagement has already validated; the pattern fails when paid spend substitutes for organic validation or for owned-channel investment. + +--- + +## The boost-organic pattern + +The most common and effective form of paid content amplification. + +**The shape.** A piece publishes organically. Some pieces show strong engagement signals: high CTR, high time-on-page, organic shares, comment engagement. The program boosts those validated pieces with paid spend to extend reach. + +**Why it works.** The content has audience validation. Audiences engage with the boosted content because it is genuinely engaging. The paid spend amplifies what already worked rather than gambling on what might work. + +**Implementation patterns.** + +- **Engagement-threshold boosting.** Pieces that exceed defined engagement thresholds in the first 24-48 hours get boosted. The thresholds (CTR, share rate, comment volume) vary by program. +- **Editorial-judgment boosting.** Editorial reviews recent organic pieces and selects which ones merit boost spend based on broader strategic fit, not just engagement metrics. +- **Hybrid.** Engagement-threshold boost for tactical amplification; editorial-judgment boost for strategic amplification of pieces that align with program goals beyond engagement metrics. + +**Capacity allocation.** Most strong programs allocate 5-20% of distribution capacity to paid amplification of organic content. Higher allocations often signal under-investment in owned channels. + +--- + +## Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +**The shape.** The program pays a third-party newsletter to feature its content. The newsletter's audience sees the program's content alongside the newsletter's editorial content. + +**Why it works.** Newsletter audiences have strong attention rhythms; sponsored content placed in a newsletter the audience reads gets meaningful attention. + +**Implementation patterns.** + +- **Single-send sponsorship.** The program pays for one prominent placement in a single send. Strongest engagement; highest cost per send. +- **Multi-send package.** The program pays for placements across multiple sends. Weaker per-send engagement; lower cost per send. +- **Co-marketing.** The program partners with the newsletter on a co-produced piece; both parties benefit. Often the most effective format when it fits both audiences. + +**Selection criteria.** + +- Audience overlap with target audience. +- Newsletter editorial fit (content tone matches the program's voice). +- Engagement metrics (open rates, click-through rates, sponsor performance history). +- Cost relative to alternative paid options. + +**Common newsletter-sponsorship failures.** + +- Mismatched audience. The newsletter has reach but does not match the program's target audience. +- Mismatched tone. Sponsored content clashes with the newsletter's voice; readers tune out. +- Generic sponsored content. Sponsored placements that read as ads underperform sponsorships that read as editorial fit. + +--- + +## Syndication networks (Outbrain, Taboola, native networks) + +Paid placement on third-party sites via "you may also like" or "recommended for you" units. + +**The shape.** Programs pay per click; content appears on third-party sites in recommendation units. + +**Implementation patterns.** + +- **Bid management.** Per-piece bidding; cost-per-click optimization. +- **Geographic and audience targeting.** Some networks support targeting; others are broader. +- **Brand-safety controls.** Choose where the content appears; some networks have brand-safety concerns about co-placement. + +**Effectiveness.** Variable. Some programs see meaningful traffic with reasonable cost-per-engagement; others see high traffic numbers but low engagement once visitors land on the program's content. The audience quality varies significantly across networks. + +**Common syndication-network failures.** + +- Click optimization without engagement measurement. The program optimizes for cost-per-click; clicks arrive; engagement is low; the audience is the wrong audience. +- Brand-safety incidents. Content appears in unwanted contexts; brand association damaged. +- Treating syndication networks as primary distribution. The networks supplement; they do not substitute for owned and earned channels. + +**The cautious-test discipline.** Test syndication networks at small budget; measure beyond clicks (engagement, time-on-page, conversion); expand only if the audience quality matches expectations. + +--- + +## Search advertising for content + +Paying for clicks on content pieces via search ads. + +**The shape.** Less common than other paid content amplification. Usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +**When it fits.** + +- High-value content with clear conversion or lead-capture goals. +- Pieces targeting queries where organic ranking is hard to achieve. +- Time-sensitive content where waiting for organic ranking is not an option. + +**When it fails.** + +- Routine blog posts boosted via search ads. Cost-per-click usually exceeds the value of the click. +- Content that does not have clear conversion paths. Paid traffic without conversion produces sunk cost. +- Competitive queries where ad costs are high. Programs may be unable to justify cost-per-click in highly contested categories. + +**The selective-discipline.** Reserve search ads for content with clear conversion goals; measure paid traffic against owned-traffic comparison; high-value content only. + +--- + +## Sponsored podcast placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts. + +**The shape.** Programs pay to be featured in third-party podcasts. Often via host-read endorsement; sometimes via produced ads. + +**Why host-read works.** The podcast host's voice carries trust signal; audiences hearing the host endorse content engage at higher rates than they engage with produced ads. Host-read endorsements are often the highest-engagement paid content amplification available. + +**Selection criteria.** + +- Host audience alignment with the program's target. +- Host content alignment with the program's voice. +- Per-episode reach and download numbers (with verification; some self-reported numbers are inflated). +- Cost relative to expected engagement. + +**Common podcast-sponsorship failures.** + +- Mismatched host. The host's audience does not match the program's audience. +- Mismatched content. The host reads the program's pitch awkwardly because the content does not fit the host's editorial voice. +- Production quality issues. Poorly produced sponsored segments damage the host's show; future sponsorship opportunities reduce. + +**The host-collaboration discipline.** Provide the host with substantive talking points, not scripted ad copy. Hosts read better when they have material they can adapt to their voice. The collaboration produces stronger sponsorships than rigid scripts. + +--- + +## The paid-as-substitute anti-pattern + +When paid promotion substitutes for organic validation or for owned-channel investment. + +**The pattern.** The program does not invest in newsletter, blog, community, or earned channels. Paid amplification produces visible reach; the program looks like it is working. Underlying owned-channel growth is minimal; the program is rented reach without owned-audience growth. + +**Why it fails over time.** + +- Paid costs rise. Auction dynamics on paid platforms drive prices up; the program's cost-per-engagement increases. +- Algorithm shifts. Paid platforms change targeting; previously-effective audiences become harder to reach or more expensive. +- Audience saturation. Audiences encountering the program's paid content develop ad-blindness; engagement decays. +- No compounding effect. Each paid impression is paid for separately; nothing compounds the way newsletter or blog growth compounds. + +**The visibility.** Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscriptions, account creations, community memberships). The reach is rented, not owned. + +**The cure.** Reallocate capacity. Reduce paid spend; increase newsletter, blog, and community investment. Recovery is multi-year; programs in paid-substitute state cannot rebuild quickly. + +--- + +## Paid amplification of low-organic-engagement content + +Boosting pieces that did not earn engagement organically. + +**The pattern.** A piece publishes organically. Engagement is low. The team boosts the piece anyway, reasoning that more reach will produce more engagement. + +**Why it fails.** Audiences who did not engage organically rarely engage when shown the same content via paid amplification. The piece's value proposition is not landing; paid amplification compounds the problem. + +**The cure.** Boost organically-validated content; do not substitute paid for organic validation. Pieces that did not engage organically should be evaluated for whether they should be refreshed (see `content-refresh-system`) or whether they were the wrong piece for the audience. + +**Exception cases.** Some content may be specifically targeted at audiences who do not see the organic version (different geographic markets, different audience segments). In those cases, paid amplification to specific audiences may be appropriate even without organic validation in the original audience. The rule is "validate within the addressable audience"; not necessarily "validate organically before any paid spend." + +--- + +## Capacity allocation for paid promotion + +Most programs benefit from a clear capacity allocation. + +**Capacity guidelines.** + +- **0-5% of distribution capacity to paid.** Programs with strong owned and earned channels; paid is selective amplification of best organic pieces. +- **5-20% of distribution capacity to paid.** Programs balancing organic-first with strategic paid amplification. +- **20-50% of distribution capacity to paid.** Programs with explicit paid-amplification strategy; usually B2C brands or programs with strong conversion-funnel logic. +- **50%+ of distribution capacity to paid.** Often signals under-investment in owned and earned; should be reviewed against the paid-as-substitute anti-pattern. + +**The allocation review.** Quarterly, review actual spend allocation. Programs drifting toward paid-heavy allocation should consider whether the drift reflects strategy or under-investment in alternatives. + +--- + +## Methodology-level choices that stay in the public skill + +The boost-organic pattern, sponsored newsletter discipline, syndication network cautious-test discipline, search advertising selective discipline, sponsored podcast host-collaboration discipline, paid-as-substitute anti-pattern, paid amplification of low-organic-engagement failure, capacity allocation guidelines. + +## Implementation choices that stay internal + +Specific paid platform configurations and bidding strategies. Specific engagement-threshold values for boost decisions. Specific newsletter sponsorship vendor selections. Specific syndication network testing protocols. Specific podcast sponsorship measurement infrastructure. The team's own conventions for paid-vs-organic capacity tradeoffs. These vary by team, budget, and platform mix. diff --git a/skills/content-migration/SKILL.md b/skills/content-migration/SKILL.md new file mode 100644 index 0000000..6f19225 --- /dev/null +++ b/skills/content-migration/SKILL.md @@ -0,0 +1,259 @@ +--- +name: content-migration +description: "Move content between platforms, domains, or URL structures while preserving SEO equity, user bookmarks, and integrations. Use this skill when planning a CMS migration, replatforming, consolidating sites, changing URL structures, or merging content from multiple sources. Triggers on content migration, replatform, CMS migration, domain migration, URL restructure, redirect map, site merge, content consolidation, migration plan, post-migration drop. Also triggers when planning a launch that involves moving existing content." +category: cross-cutting +catalog_summary: "Platform migrations with SEO equity preservation" +display_order: 2 +--- + +# Content Migration + +Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic. + +--- + +## When to use + +- Migrating from one CMS to another (e.g., WordPress to a headless setup) +- Consolidating multiple sites into one +- Splitting one site into multiple +- Changing URL structures +- Domain migration (one brand to another, mergers, rebrands) +- Migrating from a custom build to a platform (or vice versa) +- Content audit-driven cleanup as part of a larger move + +## When NOT to use + +- A net-new site with no existing content (no migration needed) +- Single-page edits or content updates within an existing site (use `content-and-copy`) +- Performance or technical SEO improvements without URL changes (use `seo-technical`) +- Routine content audits (use `seo-content-audit`) + +--- + +## Required inputs + +- The source: current platform, current URL structure, current content inventory +- The destination: target platform, target URL structure, target capabilities +- The reason for migration (drives priority of what to preserve) +- Constraints (timeline, budget, downtime tolerance) +- Stakeholders (SEO, content, dev, comms, support) + +--- + +## The framework: 6 phases + +Every content migration follows the same arc. Skipping a phase is how migrations go badly. + +### Phase 1: Inventory + +You can't migrate what you don't know. Build a complete map of what exists. + +For each piece of content: +- URL +- Title +- Content type (article, landing page, product, doc, etc.) +- Status (live, draft, archived, scheduled) +- Last modified +- Author or owner +- Traffic (last 12 months) +- Backlinks (top external referrers) +- Internal links pointing to it +- Embedded assets (images, video, downloads) + +Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool. + +The inventory is a spreadsheet. It's the source of truth for the rest of the migration. + +### Phase 2: Audit and decide + +For each piece of content, decide: + +- **Keep:** migrate as-is +- **Update:** migrate with edits (refresh, expand, fix) +- **Merge:** combine with another piece, redirect both old URLs to the new +- **Redirect:** don't migrate; redirect to a related page +- **Delete:** don't migrate, no redirect (use sparingly; only for clearly low-value pages) + +This is `seo-content-audit` work. The migration is the time to do it; not the time to skip it. + +For each "Update" or "Merge," document the specific changes. + +### Phase 3: Map URLs + +The URL map is the most important migration artifact. + +| Old URL | New URL | Status code | Reason | +|---|---|---|---| +| /old/path | /new/path | 301 | Direct equivalent | +| /old/page-1, /old/page-2 | /new/merged | 301 | Merged content | +| /old/deprecated | /related/replacement | 301 | Closest replacement | +| /old/junk | (none) | 410 | Intentionally gone | + +Rules: +- 301 (permanent redirect) for content that has a new home +- 410 (gone) for intentionally deleted content +- Avoid 404 (not found) where 410 is more accurate +- Never redirect everything to the homepage; specific is always better +- Map every URL with traffic or backlinks; lower-priority URLs can be patterned + +For domain migrations, use a 1:1 path mapping by default (`old.com/page` → `new.com/page`) with specific overrides where structure changes. + +### Phase 4: Build and stage + +Build the destination. Don't skip a staging environment. + +- Set up the new platform with the new content +- Implement the URL map (most platforms support a redirect file or rule) +- Verify a representative sample of redirects work +- Test critical user flows (signup, purchase, contact) +- Validate analytics, monitoring, and integrations +- Test from search engine perspective: robots.txt, sitemap, canonicals + +If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip. + +### Phase 5: Cut over + +The actual switch. Plan it like a launch (and use `launch-runbook` alongside this skill). + +Pre-cutover: +- Comms to stakeholders (date, expected impact) +- Comms to users if downtime expected +- Support team prepped for likely questions +- Lower DNS TTL the day before (1-3 days for safety) +- Backup of source platform (in case rollback is needed) + +Cutover: +- Redirect rules go live +- DNS changes go live +- New sitemap submitted to search engines +- Old sitemap removed or updated +- Internal links audited and updated to point to new URLs (where possible) +- Status page or banner if user-visible disruption + +Immediately post-cutover: +- Smoke test top 50 pages from the inventory +- Verify redirects are 301 (not 302) +- Verify search console for errors +- Watch real-time traffic for unexpected drops +- Watch error logs for missing assets, broken integrations + +### Phase 6: Monitor and recover + +The migration isn't done at cutover. The next 30-90 days reveal problems. + +Watch: +- **Traffic:** expect a temporary drop (10-30% is common); should recover in 4-8 weeks. A persistent drop beyond that is a problem. +- **Indexing:** new URLs should be crawled and indexed. Check coverage in search console. +- **Rankings:** track top keywords. A position drop is normal; a position cliff is a sign of a redirect or canonical problem. +- **Backlinks:** check that linked-from-elsewhere pages still resolve to the right destination. +- **404s:** any URL getting 404s that should have been redirected? Add to the map. +- **User reports:** support tickets, social media. Are users finding their old links? + +Common 30-day fixes: +- Add missed redirects from 404 patterns +- Update internal links you missed +- Re-submit sitemap if indexing stalls +- Investigate and fix any crawl errors + +--- + +## Workflow + +### Step 1: Set the scope + +What's in scope? What's out? Write it down. Migrations expand if not bounded. + +### Step 2: Build the inventory + +Pull every URL, traffic, backlinks, internal links. The spreadsheet is the artifact. + +### Step 3: Decide per piece + +Keep, update, merge, redirect, delete. Document decisions. + +### Step 4: Map URLs + +The complete redirect map. Reviewed by SEO and content stakeholders. + +### Step 5: Build the destination + +In a staging environment. Real content (or representative content). Real redirects. + +### Step 6: Test + +- Sample of redirects (top 20 by traffic, top 20 by backlinks, edge cases) +- Critical flows (signup, checkout, contact) +- Analytics and monitoring +- Search-engine perspective (robots.txt, sitemap, canonicals) + +### Step 7: Cut over + +Following the cutover checklist. Have rollback ready. + +### Step 8: Monitor + +Daily for the first week. Weekly for the first month. Monthly through 90 days. + +### Step 9: Document the result + +What worked. What didn't. Lessons. (See `after-action-report`.) + +--- + +## Failure patterns + +**No URL inventory.** Migration team thinks they have everything. They don't. Old PDFs, archived posts, marketing landing pages with backlinks. Build the inventory. + +**302 redirects instead of 301.** 302 is temporary. SEO equity doesn't reliably pass. Use 301 unless you have a specific reason. + +**Redirecting everything to the homepage.** "We'll let users find their way." They won't. They'll bounce. Map specifically. + +**Long redirect chains.** /a → /b → /c → /d. Each hop loses a little equity and adds latency. Collapse to /a → /d. + +**Forgetting non-HTML URLs.** PDFs, images, downloads. They have URLs too. They have backlinks too. Include in the map. + +**Forgetting query strings.** `/page?id=123` is a different URL than `/page`. Patterns or specific maps for query string variants. + +**Ignoring trailing slashes.** `/page` and `/page/` are different to most servers. Pick one canonical form. Redirect the other. + +**No staging.** The first time the migration runs is in production. Things break. Stage and test. + +**Stage that's too different from production.** Different DNS, different CDN, different platform. Tests pass on staging, fail on production. Stage as close to prod as feasible. + +**Leaving the source live.** Two sites serving the same content. Duplicate content, split equity, user confusion. Take down the source after confirming the destination is solid. + +**Leaving the source domain unrenewed.** Domain expires, redirects break, traffic dies. Renew the source domain for a long time, even if you're not using it. + +**Big-bang migration with no rollback plan.** Something goes wrong. Now what? Plan rollback before cutover. + +**Cutover during a busy period.** End of quarter, holiday season, big campaign. Bad timing. Pick a quiet period. + +**No comms.** Users find their bookmarks broken with no warning. Some won't come back. Communicate. + +**Migration as a one-time event.** It's not done at cutover. Monitor for 30-90 days. Fix what surfaces. + +**Treating migration as just a dev project.** SEO, content, support, comms all need to be involved. Cross-functional from day one. + +--- + +## Output format + +A migration plan document includes: + +- **Scope:** what's in, what's out +- **Inventory:** the URL spreadsheet +- **Audit decisions:** keep, update, merge, redirect, delete +- **URL map:** old to new, with status codes +- **Architecture:** new platform setup, redirect implementation +- **Cutover plan:** the runbook for switch day +- **Rollback plan:** if it goes wrong +- **Monitoring plan:** what's watched, for how long +- **Comms plan:** internal and external +- **Owners and timeline:** who does what when + +--- + +## Reference files + +- [`references/migration-runbook.md`](references/migration-runbook.md): Step-by-step runbook for cutover day, including pre-flight checks, the actual switch, immediate verification, and the first 24 hours of monitoring. diff --git a/skills/content-migration/references/migration-runbook.md b/skills/content-migration/references/migration-runbook.md new file mode 100644 index 0000000..c63c24e --- /dev/null +++ b/skills/content-migration/references/migration-runbook.md @@ -0,0 +1,351 @@ +# Migration Cutover Runbook + +A step-by-step runbook for the day of a content migration cutover. Pair this with `launch-runbook` for general launch protocol. + +The runbook is read by tense people watching the clock. Optimize for clarity. + +--- + +## Roles + +Assign these before the day: + +| Role | Responsibility | Person | +|---|---|---| +| Migration lead | Calls the cutover, makes go/no-go decisions | | +| Tech lead | Executes DNS and redirect changes | | +| QA lead | Runs verification scripts and manual checks | | +| SEO lead | Monitors search and indexing | | +| Comms lead | Sends notifications, updates status page | | +| Support lead | Watches tickets, escalates user reports | | +| Backup decision maker | Authorizes rollback if needed | | + +--- + +## T-7 days: prep + +- [ ] Inventory verified complete +- [ ] URL map signed off by SEO and content +- [ ] Destination tested in staging +- [ ] Sample of 50 redirects verified +- [ ] Rollback plan documented and rehearsed +- [ ] Cutover date and window communicated to all stakeholders +- [ ] Support team briefed on common questions +- [ ] DNS TTL lowered to 300 seconds (5 minutes) +- [ ] Monitoring dashboards built and tested +- [ ] Search console verified for both old and new domains (if domain change) + +--- + +## T-1 day + +- [ ] Final inventory pull (any new content added since the freeze?) +- [ ] Final URL map review +- [ ] Backup of source platform (full, restorable) +- [ ] Test rollback procedure in staging +- [ ] Confirm everyone on the team is available during the window +- [ ] Status page draft prepared +- [ ] Internal comms draft prepared +- [ ] Customer comms draft prepared (if applicable) + +--- + +## T-2 hours + +- [ ] All stakeholders in the cutover channel (chat or call) +- [ ] Status: source platform writeable lock (no new content during cutover) +- [ ] Final smoke test on staging +- [ ] Final confirmation: GO or NO-GO + +NO-GO triggers: +- Critical bug found in destination +- Key person unavailable +- Source data integrity issue +- External factors (e.g., source platform outage) + +If NO-GO, reschedule. Don't push through. + +--- + +## T-0: cutover + +Time-box each step. If a step takes 2x its expected duration, pause and assess. + +### Step 1: Final source backup + +Time: 5-15 minutes depending on volume. + +``` +[Specific backup commands or steps] +``` + +Verify backup integrity. Continue only on success. + +### Step 2: Deploy destination to production + +If the destination has been on staging only: + +``` +[Deploy commands] +``` + +Verify the destination is responding correctly on its production address (which may not yet have DNS pointed at it). + +### Step 3: Deploy redirect rules + +The redirect rules go on whatever the source platform uses to redirect (htaccess, edge worker, CDN rule, server config). + +``` +[Deploy redirect rules] +``` + +Test 5 redirects manually: + +```bash +curl -I https://oldhost.com/path1 +curl -I https://oldhost.com/path2 +# Expected: 301 to https://newhost.com/path1 +``` + +### Step 4: DNS cutover (if domain change) + +Update DNS to point the new domain to the destination. + +``` +[DNS update steps] +``` + +Verify resolution from multiple regions: + +```bash +dig +short newhost.com @8.8.8.8 +dig +short newhost.com @1.1.1.1 +``` + +DNS propagation usually completes within minutes (with the TTL lowered earlier). Some resolvers may lag. + +### Step 5: Submit new sitemap + +``` +[Submit to search engines] +``` + +For Google: search console → sitemaps → submit. +For Bing: webmaster tools → sitemaps → submit. + +### Step 6: Update internal references + +If the source has links to itself (or hardcoded references), update the source to point at the new URLs (helps tools that haven't picked up the redirects yet). + +If the source is being decommissioned entirely, this step is moot. + +### Step 7: Update integrations + +External integrations that reference URLs: +- Email templates with absolute URLs +- Social profiles with bio links +- Partner sites with deep links +- Marketing automation +- Analytics goals (URL-based goals may break) +- Saved CRM links + +Update each. Document in the comms plan. + +--- + +## T+15 minutes: smoke test + +- [ ] Top 50 URLs from inventory each return correct status +- [ ] Redirects return 301 (not 302) +- [ ] Critical user flows work (signup, contact form, checkout if applicable) +- [ ] Search engines can crawl (robots.txt, sitemap) +- [ ] Analytics is firing on new pages +- [ ] Monitoring is showing the new endpoints + +If any check fails: triage. Fix forward if simple; rollback if complex. + +--- + +## T+1 hour: stakeholder check-in + +- [ ] Status page updated +- [ ] Internal comms sent +- [ ] Customer comms sent (if applicable) +- [ ] Support has not seen unusual ticket volume +- [ ] Real-time analytics shows expected traffic patterns + +--- + +## T+24 hours + +- [ ] Search console shows crawls of new URLs +- [ ] Search console "Indexing" tab not showing major issues +- [ ] No spike in 404s or 5xx errors in logs +- [ ] Backlink-bearing pages confirmed to redirect correctly +- [ ] Monitoring dashboards normal +- [ ] No major customer reports + +--- + +## Rollback decision criteria + +Rollback if: +- Critical functionality broken on the destination +- Significant data corruption discovered +- Security issue introduced by the migration +- Search indexing catastrophically failing (rare; usually fixable forward) + +Do NOT rollback for: +- Normal traffic dip (expected, recovers) +- Individual broken redirects (fix forward) +- Minor visual issues (fix forward) +- Slow pages (fix forward) + +Rollback procedure: + +### Step R1: Reverse DNS (if domain change) + +``` +[Revert DNS] +``` + +### Step R2: Disable redirect rules + +Take redirects offline so source URLs serve source content again. + +``` +[Disable redirects] +``` + +### Step R3: Unlock source platform + +Remove the writeable lock on the source. + +### Step R4: Restore from backup if needed + +If data corruption: restore. See `backup-and-disaster-recovery`. + +### Step R5: Comms + +- [ ] Status page updated (rolled back) +- [ ] Internal comms (rolled back, next steps) +- [ ] Customer comms if applicable (apology, next steps) + +### Step R6: Schedule retrospective + +Within 5 business days. See `after-action-report`. + +--- + +## First-week monitoring + +Daily checks: + +| Metric | Target | Action if off | +|---|---|---| +| Top-10 page traffic | Within 80% of baseline | Investigate redirects, check indexing | +| Conversion rate | Within 90% of baseline | Investigate UX changes, check analytics implementation | +| 404 rate | Below 1% of requests | Add missing redirects | +| Crawl errors | Decreasing | Check robots.txt, sitemap, canonicals | +| Indexing rate | Increasing toward old volume | Submit URLs manually if stalled | +| Search rankings (top 20 keywords) | No cliff drops | Investigate canonicals, redirects, content parity | + +--- + +## First-month monitoring + +Weekly checks: + +| Metric | Target | +|---|---| +| Total organic traffic | Recovering toward baseline (typically 4-8 weeks) | +| Indexed pages | At or above pre-migration count | +| Backlink-pointed-to pages | All resolving correctly | +| 410 vs 404 ratio | Pages that should be gone return 410, not 404 | + +--- + +## After 90 days + +- [ ] Full performance review vs pre-migration baselines +- [ ] Document what worked, what didn't (after-action report) +- [ ] Decommission source platform if not already done +- [ ] Renew source domain (long-term, even if not in use, to preserve redirects) +- [ ] Archive the migration documentation for future reference + +--- + +## Common surprises + +**Backlinks pointing to URLs not in inventory.** Old marketing pages, archived posts, removed-but-still-linked content. Add to the map after cutover. + +**Trailing slash inconsistencies.** Server treats `/page` and `/page/` differently. One redirects, the other 404s. Fix with a normalizing redirect. + +**Search engines slow to update.** Old URLs still appear in search for weeks. Normal. Don't redirect to homepage to "speed it up." + +**Analytics goals broken.** URL-based goals don't match new URLs. Update the goals; backfill if possible. + +**Hardcoded absolute URLs in email templates.** Old links in transactional emails. Update templates. + +**Schema.org or canonical tags pointing wrong.** Crawlers follow canonical even after redirects. Verify canonical tags on the destination point to the destination. + +**Sitemap caching.** Some platforms cache sitemaps aggressively. Force a refresh. + +**robots.txt forgot the new sitemap.** Add the new sitemap to robots.txt. + +--- + +## Post-cutover comms template + +### Internal (to team) + +Subject: Migration cutover complete + +``` +The migration to [new platform/URL/etc.] is complete as of [time]. + +Status: +- [N] redirects in place +- All critical flows verified +- Monitoring shows expected traffic patterns + +We'll watch closely over the next 24 hours and the first week. Report any issues in [channel]. + +Next steps: +- [Specific monitoring action] +- [Specific follow-up] + +Thanks to everyone who made this happen. +``` + +### External (to users, if applicable) + +Subject: We've moved [or rebranded, or restructured] + +``` +Hi [name], + +[Brief reason for the change.] + +What this means for you: +- [Specific user-facing change 1] +- [Specific user-facing change 2] + +Old links should redirect automatically. If you find a broken link, please let us know at [contact]. + +Thanks for your patience as we make this transition. +``` + +--- + +## Document the result + +Within a week of cutover, write up: + +- What was migrated +- What worked +- What broke and how it was fixed +- What we'd do differently +- Lessons for the next migration + +This becomes input to `after-action-report` and to future migration playbooks. diff --git a/skills/content-refresh-system/SKILL.md b/skills/content-refresh-system/SKILL.md new file mode 100644 index 0000000..a7f8fa1 --- /dev/null +++ b/skills/content-refresh-system/SKILL.md @@ -0,0 +1,255 @@ +--- +name: content-refresh-system +description: "Systematic content refresh discipline. Quarterly audits, refresh prioritization (which pieces, when, how deep), refresh-vs-merge-vs-delete decisions, the lifecycle that distinguishes intentional refresh from set-and-forget decay. Builds on the refresh sections of pillar-content-architecture and editorial-qa with a program-level discipline. Triggers on content refresh, content decay, content audit, refresh prioritization, content lifecycle, refresh strategy, traffic decay, ranking drop, content freshness, evergreen content, content maintenance. Also triggers when traffic is eroding silently across an aging content library, when teams cannot decide which pieces to refresh, or when refresh work is happening but the impact is unclear." +category: content +catalog_summary: "Systematic content refresh: quarterly audits, refresh prioritization, refresh-vs-merge-vs-delete decisions, the lifecycle discipline that distinguishes intentional programs from set-and-forget decay" +display_order: 10 +--- + +# Content Refresh System + +A senior editorial leader's playbook for systematic content refresh. The discipline that distinguishes intentional refresh programs from set-and-forget decay, and the prioritization framework that prevents both over-refresh (refresh-everything-on-calendar) and under-refresh (refresh-nothing-until-traffic-collapses). + +Content decays. Search behavior shifts; SERP intent reshapes; facts go stale; competitors publish stronger pieces; the brand's own positioning evolves past what older pieces represent. Programs that ignore this reality watch traffic erode silently across the library. Programs that overreact (rewriting everything on calendar) burn editorial capacity that should be producing new flagship work. The discipline is in the middle: refresh what matters when signals say so, and document the decisions so the program is auditable. + +This skill is the program-level refresh discipline across the whole content library. It builds on `pillar-content-architecture`'s hub-level refresh consideration (refresh as ONE consideration in hub design) and `editorial-qa`'s pre-publish quality gate (this skill is post-publish lifecycle, not pre-publish QA). Together those skills cover content quality at the moments quality decisions get made; this skill covers the moments between, when content is in the field and decaying or holding. + +The voice is the senior editorial leader who has watched refresh programs fail in both directions and who has shipped the systems that produced durable refresh discipline. + +When to use this skill: building a refresh program from scratch, auditing why refresh work is happening but traffic is not responding, designing the prioritization that keeps refresh tractable across a 200-piece or 2,000-piece library, or fixing a refresh program that is eating editorial capacity without clear results. + +--- + +## What this skill covers + +This skill spans the post-publish lifecycle of content. The content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is HUB scope; refresh appears as ONE consideration in hub design. +- `content-brief-authoring` is per-piece scope at production time. +- `content-and-copy` is execution scope at production time. +- `editorial-qa` is gate scope: pre-publish verification. +- **`content-refresh-system` (this skill)** is lifecycle scope: program-level refresh discipline across the whole content library, after pieces are in the field. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content libraries of 50-5,000+ pieces, agencies maintaining client content programs across years. + +What is not in scope: writing the refreshed pieces themselves (that is `content-and-copy`), the brief that drives the refresh (that is `content-brief-authoring`), the pre-publish gate on the refreshed piece (that is `editorial-qa`). This skill is the prioritization and lifecycle discipline; the actual content work plugs into the existing skills. + +--- + +## Refresh-everything vs refresh-nothing vs triaged-refresh + +The keystone framing. Two failure modes plus the discipline. + +**Refresh-everything.** Full rewrites on calendar. Every piece gets a refresh on a 12-month or 18-month rotation regardless of signals. Output: editorial capacity consumed by maintenance work that often was not needed, while strong pieces are touched into worse versions and weak pieces consume the same effort as flagship pieces. Cost: opportunity cost on new flagship production; maintenance fatigue in the editorial team; some pieces that were performing well get diluted by unnecessary edits. + +**Refresh-nothing.** Set-and-forget. Pieces ship and never get touched again. Output: traffic decays silently across the library as facts go stale, competitors publish stronger pieces, and SERP intent shifts away from the piece's framing. The library's compounding value erodes invisibly until an algorithm update or a competitor's flagship piece exposes the rot. Cost: cumulative traffic loss that nobody attributes to refresh failure because the loss is gradual; trust loss when readers find stale facts in pieces they expected to be current. + +**Triaged-refresh.** Refresh what matters when signals say so. Audit cadence catches decay early; prioritization concentrates effort on high-value-decaying pieces; weak pieces get refresh-vs-merge-vs-delete dispositions instead of automatic refresh; the program is auditable because every refresh decision was a deliberate response to specific signals. Output: editorial capacity preserved for new production; the library's compounding value protected; refresh work is seen, understood, and measured. + +The litmus test. Ask of any refresh decision: what signal triggered this refresh, what depth of refresh did the signal warrant, what outcome do we expect, and how will we measure whether the refresh worked? If the answer is "it was scheduled" or "we always refresh after 12 months," the program is on calendar rather than on signal. + +--- + +## Refresh signals + +Five categories of signal that trigger refresh consideration. Pieces that show no signals do not need refresh; pieces that show multiple signals are higher priority. + +**Traffic decay.** Organic traffic to the piece is trending down over a 90+ day window beyond the seasonal baseline. The decay can be slow (5-10% over a year) or sharp (40%+ in a month after an algorithm update). Slow decay typically indicates content drift; sharp decay typically indicates external change. + +**Ranking drops.** The piece is losing position on its target keywords. Drops from page 1 to page 2-3 are particularly consequential; drops within page 1 (position 3 to position 7) are less so but still tracked. Persistent ranking drops over 30+ days indicate a real shift, not search-result volatility. + +**Factual staleness.** The piece contains statistics, references, examples, or claims that are dated. A 2018 stat in a 2026 piece on a fast-moving topic is staleness; a piece that references defunct products or platforms is staleness; a piece that uses pre-shift framings ("AI is starting to influence search" in 2026) is staleness. + +**SERP intent shift.** The dominant SERP format for the target keyword has changed. The piece was written when articles ranked for the keyword; now the SERP wants product comparisons, video, or AI-overview-style answers. The piece may still rank but increasingly for the wrong reason. + +**Content drift.** The piece's positioning no longer matches the brand's current positioning. Voice has evolved; the brand's POV on the topic has sharpened or shifted; the piece reads as the brand-of-three-years-ago. Internal signal more than external; readers may not notice but the team will. + +The audit. Every piece in the library can be characterized by which signals it shows. Pieces with zero signals are stable; pieces with one or two signals warrant attention; pieces with three or more signals are typically in active decay. + +Detail in [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md). + +--- + +## The audit cadence + +How often to look. Two cadences with different tradeoffs. + +**Quarterly audit.** A formal review of the content library every 90 days. The team pulls traffic, ranking, and recency data; reviews each piece against the signals; assigns dispositions (refresh, merge, delete, or leave alone). Output: a refresh queue with priorities and a backlog of merge/delete decisions. + +- Strength: predictable, auditable, fits naturally into editorial calendar planning. +- Weakness: 90-day delay in detecting sharp decay; piece that lost 40% traffic in week 2 of a quarter is in decay for 75 days before the audit catches it. + +**Continuous monitoring.** Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. Pieces that lose more than X% traffic in Y days trigger a review. + +- Strength: catches sharp decay early; allows fast response to algorithm updates. +- Weakness: requires monitoring infrastructure; can produce alert fatigue if thresholds are too tight; misses slow decay that does not cross thresholds. + +**The hybrid pattern.** Most strong refresh programs run both. Quarterly audits catch slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. The two cadences cover different failure modes. + +Detail in [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md). + +--- + +## Refresh prioritization + +Prioritization is the discipline. Most libraries have more pieces showing signals than the team has capacity to refresh. Prioritization concentrates effort on the pieces where refresh produces the most value. + +The 2x2 matrix: piece value (high vs low) crossed with traffic state (decaying vs stable). + +**High-value, decaying.** Top priority. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. Refresh these first; the traffic loss compounds and the lost equity is hard to recover. + +**High-value, stable.** Monitor; do not refresh proactively. Pieces that are performing should not be touched without clear signal; refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. + +**Low-value, decaying.** Audit for merge or delete. Pieces with low traffic that are decaying further are usually candidates for merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling). Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. + +**Low-value, stable.** Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. Detail in [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md). + +--- + +## Refresh depth options + +Not every refresh is the same kind of work. Four depth levels. + +**Light edit.** Update statistics, replace dead links, fix factual errors, swap dated examples. Keeps the piece's structure and argument intact. Time investment: 30-90 minutes per piece. Use when the piece is structurally sound and only the surface details have aged. + +**Substantial revision.** Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that emerged after the piece was written. Time investment: 2-4 hours per piece. Use when the piece's structure is sound but specific sections have become weak. + +**Full rewrite.** Keep the URL and topic; rewrite the piece end-to-end. Time investment: similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. Use when the piece's structure no longer fits the current SERP intent or the brand's positioning has shifted enough that the piece needs to be re-conceived. + +**Structural redesign.** Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Time investment: a multi-piece project. Use when refresh is part of a larger structural change in the content library (a hub being rebuilt, a category being consolidated). + +The depth-decision discipline. Match depth to signal strength. Sharp decay or major SERP intent shift may warrant full rewrite; slow decay with stale stats may warrant only a light edit. Treating every refresh as a full rewrite is refresh-everything energy in a different shape. + +Detail in [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md). + +--- + +## Refresh vs merge vs delete decisions + +Not every piece in decay should be refreshed. Three dispositions. + +**Refresh.** The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +**Merge.** Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +**Delete.** The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. Delete and redirect to the closest sibling or, if no sibling exists, to the relevant hub or category page. + +The decision criteria. Refresh when the piece has demand and a path back. Merge when authority is being split. Delete when there is no path forward and the piece is not worth maintaining. + +The under-recognized failure mode: refreshing pieces that should have been merged or deleted. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. + +Detail in [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md). + +--- + +## Refresh execution patterns + +Who does the work, how it ships. + +**Ownership.** A single owner per refresh, not a committee. The owner is accountable for the outcome and runs the work through to ship. Refreshes that pass through multiple hands without an accountable owner often get partially done and then stall. + +**Editorial integration.** Refreshes typically run through the same editorial workflow as new pieces (brief, draft, edit, QA gate, publish), scaled to the depth chosen. A light edit may skip the brief and go straight to edit; a full rewrite goes through every step. + +**Capacity allocation.** Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff: a team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. The split varies by program maturity (older libraries often need 30-40% refresh allocation; newer libraries may need 5-10%). + +**Refresh batching.** Some teams batch refresh work into dedicated weeks or sprints; others integrate one refresh per week into the steady-state production cadence. Batching produces focus but interrupts new production; integration sustains new production but slows refresh velocity. Either works; the failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence. + +Detail in [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md). + +--- + +## Re-promotion after refresh + +Refreshed pieces need to signal to search engines and audiences that they have been updated. + +**To search engines.** Update the modified date in schema markup. Update the published-or-modified-date in the visible metadata. Submit the URL for re-crawl through Search Console. Some teams update the URL minimally (e.g., adding a year to the slug for evergreen pieces), but URL changes carry redirect risk and should be reserved for substantial-revision or full-rewrite refreshes. + +**To audiences.** Re-share the refreshed piece on the channels where the original landed: newsletter, social, syndication partners. Treat the refresh as a publication event, not as silent maintenance. The re-promotion is part of the refresh's value proposition: the piece earns new attention as well as preserved search position. + +**Internal linking refresh.** Pieces that link to the refreshed piece may benefit from anchor-text updates if the refreshed piece's positioning shifted. Sister pieces that should now link to the refreshed piece can be updated to do so. + +**The refresh that nobody tells anyone about.** A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement. + +Detail in [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md). + +--- + +## Refresh tracking and effectiveness measurement + +The discipline that prevents refresh-theater: tracking which refreshes worked, which did not, and what the patterns reveal. + +**Per-refresh tracking.** Each refresh is logged with: the signals that triggered it, the depth chosen, the date shipped, the predicted outcome, the actual outcome at 30 days and 90 days post-refresh. The log is the refresh program's evidence base. + +**Effectiveness metrics.** The primary metrics depend on the refresh's purpose. Traffic-decay refreshes track post-refresh traffic recovery; ranking-drop refreshes track post-refresh ranking position; content-drift refreshes track post-refresh engagement metrics (time on page, return visits) more than search metrics. + +**Pattern detection.** The log reveals patterns over time. Some signal types produce reliable recovery; others rarely produce recovery and indicate a deeper problem (the topic itself is dying; the brand's positioning on the topic is wrong; competitors are too strong to displace). The patterns inform program-level decisions. + +**The refresh-that-did-not-work review.** Refreshes that did not produce the expected recovery should get a structured review. Was the depth wrong? Was the merge or delete decision the right disposition that we did not take? Did the underlying problem turn out to be something refresh cannot fix? + +Detail in [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-refresh-failures.md`](references/common-refresh-failures.md). + +- "We refresh every piece annually and traffic is still declining." Refresh-everything pattern; the calendar-based work is not catching the actual decay signals. +- "We have not touched the library in 18 months and traffic has eroded 30%." Refresh-nothing pattern; the decay went uncaught. +- "We refresh pieces but the traffic does not come back." Wrong disposition; the pieces were merge or delete candidates, not refresh candidates. +- "Our refresh queue is 200 pieces deep and growing." No prioritization; everything that shows any signal goes in the queue regardless of value. +- "We refreshed a flagship piece and traffic dropped." Refresh damaged a piece that was performing; the refresh was triggered by calendar rather than signal. +- "The team is exhausted from refresh work." Capacity allocation is wrong; either refresh ratio is too high, or new production is suffering, or the depth choices are over-investing. +- "We do not know if our refreshes are working." No tracking; refresh work happens but its effectiveness is invisible. +- "Some pieces always get refreshed; others never do." The signal triage is informal and inconsistent; some pieces are getting attention because they are visible, not because they are most decayed. +- "We refreshed a piece and forgot to re-promote it." Refresh-without-re-promotion; the piece's modified date updated but no audience or channel re-engagement happened. +- "Our quarterly audit catches things 75 days late." Quarterly cadence alone is missing sharp decay; add continuous monitoring for traffic-loss thresholds. +- "We refresh sister pieces but the hub orchestration is unchanged." Pieces refreshed in isolation when the hub-level architecture also needed updating; coordinate with `pillar-content-architecture` discipline. + +--- + +## The framework: 12 considerations for content refresh + +When designing or auditing a refresh program, walk these 12 considerations. + +1. **Triaged-refresh, not refresh-everything or refresh-nothing.** Refresh on signal, not on calendar. +2. **Signal categories named.** Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. +3. **Audit cadence committed.** Quarterly audit plus continuous monitoring; both running. +4. **Prioritization matrix applied.** High-value-decaying first; low-value-decaying audited for merge or delete. +5. **Depth matched to signal.** Light edit, substantial revision, full rewrite, structural redesign. +6. **Disposition decided per piece.** Refresh, merge, or delete; not all decay warrants refresh. +7. **Single ownership per refresh.** Accountable owner runs the work to ship. +8. **Capacity allocation explicit.** Refresh ratio of editorial capacity is a real number, planned. +9. **Re-promotion built into the workflow.** Schema, visible date, search-engine resubmit, audience re-share. +10. **Per-refresh tracking.** Signals, depth, outcomes logged for pattern detection. +11. **Effectiveness measurement.** Recovery tracked at 30 and 90 days; patterns inform program decisions. +12. **The-refresh-that-did-not-work review.** Failed refreshes get structured review; lessons compound. + +The output of the framework is a refresh program that is auditable, capacity-respecting, and producing visible value for the library's compounding equity. + +--- + +## Reference files + +- [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md) - Five signal categories with detection patterns. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. The audit pattern that surfaces signals across the library. +- [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md) - Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, alert-threshold design. +- [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md) - 2x2 matrix with quadrant strategies. High-value-decaying as top priority; low-value-decaying audited for merge or delete; the discipline of NOT refreshing the high-value-stable quadrant. +- [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md) - Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, depth-creep anti-pattern. +- [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md) - Disposition criteria. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged. +- [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md) - Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. +- [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md) - Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. +- [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md) - Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. +- [`references/common-refresh-failures.md`](references/common-refresh-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: refresh is content's immune system + +A content library is a long-running system. The pieces in it interact with search algorithms that change, audiences that shift, brands that evolve, and competitors that publish. Set-and-forget treats the library as a static asset and watches it decay. Refresh-everything treats it as a maintenance project and burns capacity that should be producing new flagship work. + +The discipline is the immune system: signals are detected early, prioritization concentrates effort where the value is highest, depth matches signal strength, dispositions include merge and delete (not just refresh), and the work is tracked so the program learns. Programs that run this discipline preserve the library's compounding value. Programs that do not watch the library erode and discover the loss only when an algorithm update or a competitor's flagship piece exposes how far the rot has spread. + +When in doubt about whether a refresh program is ready, ask: does the program detect signals, prioritize on value, match depth to signal, decide between refresh and merge and delete, allocate capacity explicitly, re-promote the refreshed pieces, and track effectiveness? If yes to all of those, the program is real. If no to any, the gap is where decay will compound. diff --git a/skills/content-refresh-system/references/audit-cadence-patterns.md b/skills/content-refresh-system/references/audit-cadence-patterns.md new file mode 100644 index 0000000..4667597 --- /dev/null +++ b/skills/content-refresh-system/references/audit-cadence-patterns.md @@ -0,0 +1,162 @@ +# Audit cadence patterns + +Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, and alert-threshold design. + +The audit cadence determines how quickly decay signals turn into refresh decisions. Programs that audit annually catch decay 9-12 months late; programs that monitor continuously without an audit layer catch sharp decay early but miss the slow-drift and content-drift signals that need human review. The hybrid pattern is the standard for mature programs. + +--- + +## The quarterly audit + +A formal review of the content library every 90 days. + +**The mechanics.** + +- The team blocks 1-3 days per quarter for the audit. +- Pull data: traffic per URL over the last 90 and 180 days, rankings on target keywords, last-modified dates, target-keyword SERP samples. +- Run each piece through the five-signal checklist (see `refresh-signals-checklist.md`). +- Assign each piece a disposition: refresh (with depth), merge, delete, monitor, no action. +- Output a refresh queue prioritized by the prioritization matrix. + +**Strengths.** + +- Predictable. The team knows when audit work happens and can plan around it. +- Auditable. Each quarter's decisions are documented; patterns over multiple quarters become visible. +- Comprehensive. The signal types that need human judgment (content drift, SERP intent shift) get reviewed; continuous monitoring cannot detect these without human eyes. +- Capacity-aware. Audit work happens at known times; new production schedules can flex around it. + +**Weaknesses.** + +- 90-day delay in detecting sharp decay. A piece that lost 40% traffic in week 2 of the quarter is in decay for 75 days before the audit catches it. +- Heavy lift. Auditing 200-2,000 pieces in 1-3 days requires structured tooling; teams without tooling burn out. +- Focus on the audit moment can crowd out continuous attention. "We will catch it next quarter" becomes the answer to issues that warrant immediate response. + +--- + +## Continuous monitoring + +Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. + +**The mechanics.** + +- Define thresholds for sharp decay: e.g., traffic drop of 25%+ in 14 days, ranking drop of 5+ positions in 14 days. +- Automated monitoring runs daily or weekly, comparing current data to baseline. +- Alerts route to the editorial owner of the affected piece (or to a refresh queue triage owner if pieces do not have individual owners). +- Triage decides whether the alert warrants immediate refresh, addition to the next quarterly audit's queue, or dismissal as noise. + +**Strengths.** + +- Catches sharp decay early. Algorithm-update fallout, technical regressions, and dramatic SERP intent shifts get attention within days, not 75-90 days. +- Allows fast response. A piece that lost 50% traffic on a specific date can be investigated while the cause is fresh. +- Reduces audit-day exhaustion. Sharp signals are handled in real time; the quarterly audit focuses on the slower signals. + +**Weaknesses.** + +- Requires monitoring infrastructure. Teams need rank tracking, traffic monitoring, and alerting that can route to specific URL owners. +- Alert fatigue if thresholds are too tight. Daily alerts on minor fluctuations train the team to ignore the alerts; thresholds need calibration. +- Misses slow decay. Pieces declining 5-8% per quarter never cross thresholds; they accumulate decay invisibly. The quarterly audit is what catches these. +- Misses non-traffic signals. Continuous monitoring on traffic and rankings cannot detect content drift or factual staleness. + +--- + +## The hybrid pattern + +Most strong refresh programs run both. The quarterly audit catches slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. + +**Integration shape.** + +- Continuous monitoring runs daily or weekly with a small set of well-calibrated thresholds. +- Quarterly audit runs the full signal checklist on the whole library. +- Pieces that triggered continuous-monitoring alerts during the quarter get fast-track disposition; the quarterly audit reviews the rest. +- The continuous-monitoring log feeds into the quarterly audit so the team can see whether thresholds are calibrated correctly (too many false alerts, too few real ones). + +**Capacity split.** A typical hybrid pattern might allocate 5-10% of editorial capacity to continuous-monitoring response (a few hours per week) and a concentrated 1-3 days per quarter to the audit. The split scales with library size and decay rates. + +--- + +## Alert-threshold design + +Calibrating continuous-monitoring thresholds is its own discipline. + +**Threshold goals.** + +- High precision: when the threshold is crossed, the alert is usually a real signal, not noise. +- Reasonable recall: catches the sharp-decay events that matter; does not need to catch every minor fluctuation (the audit catches those). +- Sustainable cadence: alerts arrive at a frequency the team can triage without fatigue. + +**Threshold patterns that work.** + +- Traffic: 25%+ drop in 14 days, sustained over 21 days. The sustainment requirement filters volatility. +- Ranking: 5+ position drop on a tracked keyword, sustained over 14 days. Single-day drops are noise; sustained drops are signal. +- Indexing: any unexpected change in indexed status (200 to non-200 status, sudden noindex tag, sudden disappearance from index). These are usually technical regressions and warrant immediate attention. +- Schema validation: schema breaking or warnings appearing on a piece that previously validated cleanly. Often indicates a CMS update or template change. + +**Threshold patterns that fail.** + +- 10% traffic drop alerts produce far too many false positives; teams stop reading the alerts. +- Single-day rank drop alerts produce noise; SERP volatility within a few positions is normal. +- Aggregate-traffic alerts on whole categories rather than per-URL alerts hide which specific pieces are decaying. + +**Threshold tuning.** Run alerts in shadow mode for 4-6 weeks before committing. Track whether alerts correspond to real signals on review. Adjust thresholds based on the precision-recall observed. + +--- + +## When to audit more frequently + +Some programs warrant more than quarterly audits. + +**Programs in active rebuild.** Content libraries undergoing structural redesign or hub reorganization benefit from monthly audits during the rebuild phase. The signal volume is higher and the decisions need faster cycle time. + +**Post-algorithm-update period.** In the 30-90 days after a major algorithm update, signal volume spikes. Some teams run a special audit at the 30-day post-update mark in addition to the regular quarterly cadence. + +**Programs with rapid topic evolution.** Topics that move quickly (AI tools, evolving regulatory environments, tactical playbooks in fast-moving fields) may benefit from monthly factual-staleness checks even when traffic and ranking signals are stable. + +--- + +## When to audit less frequently + +Some programs can run on lighter cadence. + +**Small libraries (under 50 pieces) with stable performance.** Bi-annual audits may be sufficient if continuous monitoring is in place and the library has shown stable decay rates over multiple cycles. + +**Libraries dominated by evergreen pieces.** When the topical mix is heavily evergreen (foundational concepts that move slowly), quarterly audits may produce limited signal volume. Combine with continuous monitoring; reduce audit frequency. + +The discipline. Cadence should match decay rate, not be fixed by convention. Programs that decay quickly need faster cadence; programs that decay slowly can run longer audit cycles. + +--- + +## Audit anti-patterns + +**Annual audit as the only cadence.** Catches decay 9-12 months late; the library is in significant erosion before the audit runs. + +**Continuous monitoring without quarterly audit.** Catches sharp decay; misses slow decay, content drift, and SERP intent shifts that need human review. + +**Audit happening but no follow-through.** The team runs the audit, produces a queue, then loses momentum on actually executing the refreshes. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +**Audit without prioritization.** The output is a list of every piece showing any signal, with no value-weighted prioritization. The team does the cheapest refreshes first regardless of value, leaving high-value-decaying pieces in the backlog. + +**Audit without depth assignment.** Pieces are tagged "refresh" without specifying depth. Refresh execution defaults to whatever depth the team has time for, which is often light edit even when substantial revision is needed. + +--- + +## Audit governance + +Who runs the audit, who approves dispositions, how the queue routes to execution. + +**Single audit owner.** A specific person runs the audit each quarter, accountable for signal quality and disposition recommendations. + +**Disposition review.** Refresh, merge, and delete dispositions are reviewed by a content lead or director. Delete dispositions in particular need approval because they are irreversible (pieces deleted and not redirected can lose authority that did not need to be lost). + +**Queue routing.** The refresh queue routes to specific editorial owners based on capacity, expertise, and the depth of work required. Light edits route to anyone with capacity; full rewrites route to the writer or editor best matched to the topic. + +**Audit log.** Each quarter's audit, dispositions, and outcomes are logged. The log feeds the next quarter's review (which dispositions actually shipped, which produced recovery, which patterns are emerging). + +--- + +## Methodology-level choices that stay in the public skill + +The quarterly audit mechanics, continuous monitoring mechanics, hybrid pattern, alert-threshold design principles, audit-cadence variations, audit governance shape, and the anti-patterns. + +## Implementation choices that stay internal + +Specific monitoring tools the team uses (rank trackers, analytics platforms, alerting systems). Specific threshold values calibrated to the team's data. Specific dashboards and reporting templates. Specific ticketing or queue systems for refresh routing. Specific automation scripts that pull data into audit-ready formats. The team's own audit-day rituals and tooling. These vary by team, tooling, and library size. diff --git a/skills/content-refresh-system/references/common-refresh-failures.md b/skills/content-refresh-system/references/common-refresh-failures.md new file mode 100644 index 0000000..df86203 --- /dev/null +++ b/skills/content-refresh-system/references/common-refresh-failures.md @@ -0,0 +1,169 @@ +# Common refresh failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear across programs of different sizes, library ages, and editorial team compositions; the underlying causes are rarely about people and almost always about discipline, prioritization, or measurement gaps. + +--- + +## Failure 1: Refresh-everything-on-calendar + +**Symptom.** Every piece gets refreshed on a 12-month or 18-month rotation regardless of signals. Editorial capacity is consumed by maintenance work that often was not needed. + +**Diagnosis.** The program treats refresh as a calendar event rather than as a signal-driven decision. Pieces that were performing get touched into worse versions; pieces that were decaying are scheduled for refresh whenever their rotation comes up rather than when the decay signals warrant. + +**Cure.** Replace calendar-driven refresh with the prioritization matrix and the signal-driven audit cadence. Refresh on signals; leave stable pieces alone. + +**Capacity recovery.** Programs that abandon refresh-everything typically recover 30-50% of their refresh capacity for higher-value work or for new production. + +--- + +## Failure 2: Set-and-forget + +**Symptom.** The team has not touched the library in 18+ months. Traffic has eroded across the library; the team is uncertain how much loss is from refresh failure vs other causes. + +**Diagnosis.** The program lacks both audit cadence and continuous monitoring. Decay accumulates silently because no system is detecting it. + +**Cure.** Establish the hybrid audit pattern: quarterly audit plus continuous monitoring. The first audit will surface a large queue (typical when starting from set-and-forget); the queue should be triaged by the prioritization matrix and worked through over multiple quarters rather than tackled all at once. + +--- + +## Failure 3: Refresh that should have been merge or delete + +**Symptom.** The team spends hours refreshing pieces that even at their best will not produce meaningful recovery. The same pieces appear in queue across multiple audits. + +**Diagnosis.** The disposition decision was wrong. Refresh was the default disposition because it felt less destructive than merge or delete; the actual right disposition was merge into a stronger sibling or delete with redirect. + +**Cure.** Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. Train the audit owner on the disposition decision flow (see `refresh-vs-merge-vs-delete.md`). + +--- + +## Failure 4: Unprioritized refresh queue + +**Symptom.** The refresh queue is 200 pieces deep and growing. The team works through the queue in order of arrival or in order of "easiest first" rather than by value. + +**Diagnosis.** No prioritization matrix is being applied. Every piece showing any signal goes in the queue regardless of value. + +**Cure.** Apply the 2x2 matrix (value × traffic state). Queue entries get tagged by quadrant. Work focuses on high-value-decaying first; low-value-decaying gets disposition decisions (often merge or delete) rather than refresh; stable quadrants get monitor or no action. + +--- + +## Failure 5: Refresh-on-stable-piece regression + +**Symptom.** A flagship piece was performing well. The team refreshed it because it was the next piece in the rotation. After the refresh, traffic dropped 30% and rankings dropped 5 positions. + +**Diagnosis.** Refresh-everything-on-calendar damaged a stable piece. The refresh introduced changes that shifted the SERP signals or the piece's structural fit; the new version performs worse than the original. + +**Cure.** Stop refreshing high-value-stable pieces by default. Pieces in this quadrant get monitor disposition unless content drift is severe enough to warrant the regression risk. When refreshing a stable piece is genuinely warranted, plan for fast revert if regression occurs. + +**Recovery.** Some refresh regressions can be partially reversed by going back to a closer-to-original version of the piece. Some cannot. The lesson informs future stable-piece refresh decisions. + +--- + +## Failure 6: Capacity overcommitment + +**Symptom.** The team is exhausted from refresh work. New-piece production is suffering. The team complains of refresh fatigue. + +**Diagnosis.** Capacity allocation to refresh is too high (or new-production commitments are too high; the result is the same). The team is being asked to do more total work than capacity allows. + +**Cure.** Right-size the allocation. Reduce refresh queue intake by tightening prioritization (only highest-value items enter the queue); or reduce new-production commitments; or temporarily increase capacity. The status quo is unsustainable. + +**Sustainability check.** Capacity is real. Programs that pretend capacity is infinite produce burnout, quality drift, and team turnover. The capacity audit (see `refresh-execution-patterns.md`) is what catches this before burnout. + +--- + +## Failure 7: Effectiveness invisible + +**Symptom.** "We do not know if our refreshes are working." Refresh work happens but its effectiveness is not tracked or reviewed. + +**Diagnosis.** No per-refresh tracking is in place. The program runs without learning data. + +**Cure.** Establish the minimum log (see `effectiveness-measurement.md`). Backfill the log for recent refreshes if possible. Establish 30-day and 90-day measurement windows. Run quarterly pattern-detection reviews. + +**Adoption.** Logging adds overhead. Programs that resist logging often discover later that the program's effectiveness has been declining for quarters and they cannot tell why because the data was not captured. The overhead of logging is small compared to the cost of running the program blind. + +--- + +## Failure 8: Inconsistent refresh attention + +**Symptom.** Some pieces always get refreshed; others never do. The pattern correlates with which writers prefer which topics, not with which pieces need refresh most. + +**Diagnosis.** The signal triage is informal and inconsistent. Pieces are getting attention because they are visible to certain people, not because they are most decayed. + +**Cure.** Formalize the audit so signal detection is data-driven rather than memory-driven. The matrix and the audit log force visibility on the whole library, not just on the pieces individual team members happen to think of. + +--- + +## Failure 9: Refresh-without-re-promotion + +**Symptom.** Refreshes ship. Modified dates update. The team waits for traffic recovery. Recovery is marginal at best. The team concludes refresh does not work. + +**Diagnosis.** Re-promotion was skipped. Search engines saw the modified date but audiences did not engage; the recovery curve that re-promotion typically produces did not happen. + +**Cure.** Build re-promotion into the workflow as a non-skippable step. Match re-promotion intensity to refresh depth (see `re-promotion-after-refresh.md`). The refresh is not "done" when published; the refresh is "done" when re-promotion has executed. + +--- + +## Failure 10: Audit without follow-through + +**Symptom.** The team runs the quarterly audit; produces a queue; the queue largely sits unworked; the next quarter's audit shows the same pieces in queue. + +**Diagnosis.** No owner-of-owners is keeping the queue moving. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +**Cure.** Assign an owner-of-owners role for the refresh program as a whole. Their job is queue movement, escalation of stalled refreshes, and program-level reporting. Without this role, even good audits do not produce execution. + +--- + +## Failure 11: Quarterly cadence too slow for sharp decay + +**Symptom.** The quarterly audit catches a piece in significant decay. The traffic loss has been accumulating for 75 days before the audit caught it. The recovery is harder because the decay has compounded. + +**Diagnosis.** Quarterly cadence alone is missing sharp decay. The lag between decay and detection is too long. + +**Cure.** Add continuous monitoring for traffic-decay and ranking-drop thresholds. Sharp decay alerts route to fast-track triage; the quarterly audit focuses on slower signals that continuous monitoring cannot detect (content drift, factual staleness, SERP intent shift). + +--- + +## Failure 12: Refresh in isolation when hub orchestration changed + +**Symptom.** Pieces are refreshed individually but the hub-level architecture also needed updating. The refreshes ship; the hub-level decay continues because the architecture problem was unaddressed. + +**Diagnosis.** Piece-level refresh is being done without coordination with hub-level architecture. Some refresh queues need to escalate to structural-redesign disposition rather than be addressed at piece level. + +**Cure.** Coordinate with `pillar-content-architecture` discipline. When piece-level refresh is bumping against architecture-level issues, escalate to a structural-redesign project. Some refresh attempts cannot succeed without the hub-level work. + +--- + +## Failure 13: Stalled refreshes accumulating + +**Symptom.** The refresh queue contains zombie items: pieces assigned months ago that have not shipped and are not progressing. Everyone knows they are stalled; nobody is removing them. + +**Diagnosis.** No stalled-refresh recovery process. Refreshes that get stuck stay stuck because there is no review mechanism to escalate or reassign. + +**Cure.** Build stalled-refresh review into each quarterly audit. Refreshes that have been in queue more than two cycles get reviewed: reassign owners, re-scope depth, or remove from queue if the disposition was wrong. The review prevents zombie accumulation. + +--- + +## Failure 14: Light-edit-as-default + +**Symptom.** Most refreshes are light edits regardless of signal strength. The light edits do not move the needle on pieces that needed substantial revision; the team concludes "refresh does not work" when the actual issue is depth mismatch. + +**Diagnosis.** Depth assignment is defaulting to light edit because light edits are the easiest to schedule. Substantial revision and full rewrite are being skipped because they are harder to fit into capacity. + +**Cure.** Match depth to signal strength explicitly. Depth-light when signals support light edit; depth-deeper when signals warrant. Capacity allocation should account for depth distribution; if the team consistently has capacity only for light edits, the allocation needs adjustment, not the depth assignment. + +--- + +## The cross-cutting pattern + +Most refresh failures share a single root: shortcuts in discipline. Calendar-refresh shortcuts the signal analysis. No-measurement shortcuts the learning. Refresh-as-default shortcuts the disposition decision. Light-edit-as-default shortcuts the depth decision. No-re-promotion shortcuts the audience-engagement work. Each shortcut feels like it is saving capacity; each shortcut is actually shifting capacity to lower-value work. + +The fix for almost any refresh failure is the same: surface the discipline that was being shortcutted, and pay the cost of running the discipline. The capacity recovered from eliminating low-value refreshes typically more than pays for the discipline overhead. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the discipline-as-cure observation. + +## Implementation choices that stay internal + +Specific tooling for stalled-refresh detection. Specific reporting templates for owner-of-owners updates. Specific reviewer training on disposition decisions. Specific automation that catches refresh-without-re-promotion. The team's own conventions for capacity recalibration when overcommitment is detected. These vary by team, tooling, and program structure. diff --git a/skills/content-refresh-system/references/effectiveness-measurement.md b/skills/content-refresh-system/references/effectiveness-measurement.md new file mode 100644 index 0000000..7e6d0d3 --- /dev/null +++ b/skills/content-refresh-system/references/effectiveness-measurement.md @@ -0,0 +1,150 @@ +# Effectiveness measurement + +Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. The discipline that prevents refresh-theater and turns the refresh program into a learning system. + +Refresh effectiveness measurement is the difference between a program that learns and a program that runs. Programs without measurement run the same patterns indefinitely, including the patterns that do not work; programs with measurement see which refreshes produce recovery, which do not, and what the patterns reveal about depth, signal interpretation, and disposition decisions. + +--- + +## Per-refresh tracking + +Each refresh is logged with the data needed to evaluate it. + +**The minimum log.** + +- **URL.** The refreshed piece. +- **Date shipped.** When the refresh published. +- **Signals that triggered the refresh.** Which of the five signal categories were active; signal severity. +- **Disposition.** Refresh, merge, delete (with target URLs for merge). +- **Depth.** Light edit, substantial revision, full rewrite, structural redesign. +- **Owner.** Who shipped the refresh. +- **Capacity spent.** Hours of editorial time invested. +- **Predicted outcome.** What the team expected the refresh to produce (recovery within X% in Y days, or qualitative expectation). +- **Actual outcome at 30 days.** Traffic, ranking, engagement metrics post-refresh vs pre-refresh. +- **Actual outcome at 90 days.** Same metrics extended to 90 days. +- **Notes.** Qualitative observations on what happened, surprising patterns, questions raised. + +**Why the minimum log.** Each field is load-bearing for pattern detection. Without signals, you cannot tell whether decay-driven refreshes recover differently from drift-driven refreshes. Without depth, you cannot tell whether full rewrites outperform substantial revisions. Without capacity, you cannot evaluate ROI. + +**The log as program memory.** Across years, the log becomes the program's accumulated learning. A team that has logged 200 refreshes can answer questions like "what is the typical recovery curve for substantial-revision refreshes on traffic-decayed pieces?" with data; a team without the log answers the same question with anecdote. + +--- + +## 30-day recovery measurement + +The first measurement window post-refresh. + +**What the 30-day window shows.** + +- **Schema and indexing recognition.** Search engines have crawled the updated piece and registered the modified date. +- **Initial ranking response.** Some ranking shifts happen within days as the search engine re-evaluates; others take longer. +- **Audience engagement spike.** Re-promotion produces traffic from newsletter, social, and syndication. The 30-day window captures the immediate engagement. +- **Quick wins or regressions.** If the refresh broke something (regressions in indexing, schema, or ranking), the 30-day window catches it. + +**What the 30-day window does not show.** + +- **Sustained recovery.** Initial spikes from re-promotion fade; the 30-day window cannot distinguish sustained recovery from re-promotion afterglow. +- **Algorithm-update response.** If an algorithm update happens after the refresh, the 30-day measurement may be confounded. +- **Long-tail keyword recovery.** Some long-tail rankings move slowly; the 30-day window may show only head-term response. + +**The 30-day pattern.** Most refreshes that will produce sustained recovery show some signal at 30 days: ranking improvement, traffic uptick, engagement spike. Refreshes that show no signal at 30 days are not necessarily failures, but they warrant attention; the 90-day measurement will resolve the question. + +--- + +## 90-day recovery measurement + +The longer-window measurement that confirms or refutes the 30-day signal. + +**What the 90-day window shows.** + +- **Sustained recovery.** Initial spikes have faded; what remains is the refresh's durable contribution. +- **Algorithm-update integration.** Most algorithm updates have been digested; the 90-day data reflects the new state. +- **Long-tail keyword response.** Slower-moving rankings have settled. +- **Engagement-based metrics.** Time on page, return visits, scroll depth post-refresh vs pre-refresh. + +**The 90-day pattern.** + +- **Strong recovery.** Traffic and rankings are above pre-refresh baseline by 20%+. The refresh worked. +- **Modest recovery.** Traffic and rankings are 5-20% above pre-refresh baseline. The refresh helped but did not produce dramatic improvement. +- **No recovery.** Traffic and rankings are within 5% of pre-refresh baseline. The refresh was not effective. +- **Regression.** Traffic or rankings are below pre-refresh baseline. The refresh damaged the piece. + +The 90-day measurement is the primary effectiveness measurement. The 30-day is the early-warning; the 90-day is the verdict. + +--- + +## Pattern detection across refreshes + +Individual refresh measurements are noisy. Patterns across refreshes are signal. + +**Patterns the log reveals.** + +- **Depth-effectiveness.** Are full rewrites producing better recovery than substantial revisions on similar signals? If yes, the team should consider deeper depth on similar future cases. +- **Signal-effectiveness.** Are traffic-decay refreshes recovering more reliably than content-drift refreshes? If yes, the program may benefit from prioritizing traffic-decay queue and being more selective about content-drift refresh. +- **Disposition-effectiveness.** Are pieces in the high-value-decaying quadrant recovering when refreshed, or are they continuing to decay? If continuing decay, the disposition may be wrong (merge or delete may have been better) or the underlying cause is structural (the topic is dying; competitors too strong). +- **Owner-effectiveness.** Are some owners producing better recovery than others on similar refreshes? Possibly skill differential, possibly capacity issues, possibly random variation that needs more data. +- **Topic-effectiveness.** Are refreshes on some topics recovering reliably while others do not? Some topics may be in structural decline; the program may need to reduce investment in those topics rather than increase refresh effort. + +**Pattern detection cadence.** Quarterly review of accumulated refresh data. Year-over-year reviews on multi-year programs. The patterns inform program-level decisions about allocation, prioritization, and disposition defaults. + +--- + +## The refresh-that-did-not-work review + +Refreshes that did not produce recovery are the program's most valuable learning data. + +**The review questions.** + +- **Was the depth wrong?** Did the refresh need more depth than was applied? Light edit when substantial revision was needed produces no recovery on substantial-decay signals. +- **Was the disposition wrong?** Should the piece have been merged or deleted instead of refreshed? Refreshing a piece that should have been merged produces ongoing decay because the underlying authority-splitting was not addressed. +- **Was the signal interpretation wrong?** Did the team read decay as content-drift when it was actually competitor-displacement? Refresh on the wrong cause does not produce recovery. +- **Is the topic in structural decline?** Some topics decline structurally; refresh cannot recover what the topic itself has lost. The right disposition may be to reduce investment in the topic and reallocate capacity. +- **Did re-promotion happen?** Refresh-without-re-promotion underperforms; some "did not work" cases are actually "did not get re-promoted." + +**The review output.** Each non-recovery refresh produces either: a re-disposition (try merge or delete), a depth re-attempt (next quarter try the deeper depth), or an acknowledgment that the topic is in decline and the program should reduce investment. + +**The review's program impact.** Without the review, non-recovery refreshes accumulate as silent program failures. With the review, the patterns surface and the program adjusts. + +--- + +## Effectiveness metrics by refresh purpose + +Different refresh purposes warrant different primary metrics. + +**Traffic-decay refreshes.** Primary metric: post-refresh traffic recovery vs pre-refresh baseline at 90 days. Secondary: ranking position recovery on target keywords. + +**Ranking-drop refreshes.** Primary metric: ranking position recovery on target keywords at 90 days. Secondary: traffic recovery (rankings without traffic recovery suggest CTR issues that ranking alone does not capture). + +**Factual-staleness refreshes.** Primary metric: less straightforward; the refresh's purpose is correctness, not recovery. Track that the staleness was caught before reader-detected errors compound. Secondary: any traffic recovery is bonus. + +**SERP-intent-shift refreshes.** Primary metric: ranking on target keywords (rankings reflect format-fit). Secondary: engagement metrics (the refresh changed format; does the new format engage better?). + +**Content-drift refreshes.** Primary metric: engagement metrics (time on page, return visits, conversions). Secondary: voice consistency review (qualitative; the refresh purpose was alignment with current brand positioning). + +The metric should match the purpose. Programs that measure every refresh by traffic recovery miss the value of refreshes whose purpose was correctness or alignment rather than recovery. + +--- + +## Common measurement failures + +**No measurement at all.** Refreshes ship; outcomes are not tracked; the program runs without learning. Each refresh is a fresh prediction with no accumulated evidence. + +**Measurement at the wrong window.** Measuring at 7 days captures only re-promotion afterglow; measuring at 6 months conflates many other variables. 30 and 90 days are the workable windows. + +**Single-metric measurement.** Measuring only traffic ignores ranking, engagement, and conversion metrics. Different refresh purposes warrant different metrics. + +**Measurement without context.** Comparing post-refresh metrics to pre-refresh metrics without accounting for seasonality, algorithm updates, or competitor activity produces noisy attribution. + +**No pattern detection.** Per-refresh measurement happens but never gets aggregated into pattern review; the program does not learn across refreshes. + +**No non-recovery review.** Successful refreshes get celebrated; failed refreshes get forgotten. The asymmetry hides the program's most valuable learning. + +--- + +## Methodology-level choices that stay in the public skill + +The minimum per-refresh log fields, the 30-day and 90-day measurement windows, the pattern-detection cadence, the refresh-that-did-not-work review, the metric-by-purpose mapping, the common measurement failures. + +## Implementation choices that stay internal + +Specific analytics dashboards that pull refresh metrics. Specific log structure in the team's project-management or content system. Specific seasonality models the team uses to baseline. Specific competitor-activity tracking that contextualizes attribution. Specific reviewer workflow for non-recovery refreshes. The team's own pattern-detection rituals. These vary by team, tooling, and analytics setup. diff --git a/skills/content-refresh-system/references/re-promotion-after-refresh.md b/skills/content-refresh-system/references/re-promotion-after-refresh.md new file mode 100644 index 0000000..1f20605 --- /dev/null +++ b/skills/content-refresh-system/references/re-promotion-after-refresh.md @@ -0,0 +1,159 @@ +# Re-promotion after refresh + +Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. The patterns that signal a refresh to search engines and audiences. + +A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement that re-promotion produces. Programs that ship refreshes silently leave value on the table. + +--- + +## Signal to search engines + +What the search engine needs to see to recognize the refresh. + +**Modified-date in schema markup.** Schema.org Article (and related types) include a `dateModified` field. Update this when the refresh ships. Many CMS platforms update this automatically on save; verify the automation is working. Schemas with stale modified dates signal that the refresh is technical rather than substantive. + +**Visible modified-date on the page.** The page should display "Updated [date]" or similar visible signal. Some templates show "Published [date]" without an updated date; these should be updated to surface the refresh date. + +**Sitemap update.** The XML sitemap's `lastmod` field for the URL should reflect the refresh date. Most sitemap generators handle this automatically; verify after the refresh ships. + +**Search Console URL inspection and resubmission.** For high-priority refreshes, use Search Console's URL inspection tool and request indexing. This signals the refresh to the index without waiting for the next crawl. Use sparingly; bulk resubmission of every refresh can throttle. + +**Internal-link-graph signals.** When sister pieces add or update links to the refreshed piece, the additional internal-link signals reinforce that the URL is current and load-bearing. Refresh that updates internal linking from sister pieces sends stronger signals than refresh that does not. + +--- + +## Substantive vs cosmetic modifications + +Search engines distinguish between substantive content changes and cosmetic touch-ups. + +**Substantive changes.** Body content edits, section additions or removals, lede or closing rewrites, factual updates, restructuring. The refresh has changed what the piece says. + +**Cosmetic changes.** Date stamp updates without content changes. CSS or template changes. Whitespace edits. These do not constitute refresh; updating the modified date without substantive change is signaling a refresh that did not happen. + +**Why the distinction matters.** Search engines that detect the modified-date signal as cosmetic rather than substantive can devalue the signal. Programs that bump modified dates without substantive change to chase the refresh signal are running a tactic that has been increasingly detected and discounted. The honest signal is a real refresh; the tactic of date-bumping without change is short-lived value at best. + +**The audit.** Refreshes should produce diff'able content changes. If the refresh ships without diff'able changes, it is not a refresh. + +--- + +## Signal to audiences + +The other half of re-promotion: re-engaging the audiences who saw the original. + +**Newsletter re-share.** For pieces that originally went to the newsletter, a refreshed piece deserves a re-share. The framing is "we updated this with [specific updates]," not "here is a piece you may have seen before." Specificity earns re-engagement; vague re-shares feel like filler. + +**Social re-share.** For pieces that originally landed on social channels, the refresh is a social moment. New angle, new pull-quote, new visual, framing the refresh as the news the piece now carries. + +**Syndication partner update.** For pieces syndicated to partner platforms, the refresh may warrant communication with syndication partners about the updated version. Some partners pull the latest content automatically; some do not. The refresh communication closes the loop. + +**Email-list segmentation.** For programs with sophisticated email-list segmentation, refreshed pieces can be sent to segments that did not see the original or that engaged with the original and may benefit from the updated version. + +**Re-share cadence discipline.** Not every refresh deserves the same re-share intensity. Light edits typically do not warrant social re-share; substantial revisions or full rewrites do. Calibrate re-share to depth. + +--- + +## Internal linking refresh + +Pieces that link to the refreshed piece may benefit from anchor-text updates. + +**When anchor-text update fits.** The refreshed piece's positioning shifted, and the anchor text on sister pieces should now describe the piece differently. A piece that linked to the refreshed piece as "our guide to programmatic SEO" may now want to link as "our guide to programmatic SEO durability" if the refreshed piece's framing is now durability-focused. + +**When sister pieces should now link to the refreshed piece.** Some refreshes add coverage of topics that sister pieces discuss. Pieces discussing those topics that did not previously link to the refreshed piece may now warrant new internal links. + +**The internal-link-refresh pass.** Some programs run a quick pass after each substantial refresh: search the library for pieces mentioning the refreshed piece's topic, audit whether the existing anchor text and link presence are correct, update where warranted. + +**The over-linking failure.** Refreshes that trigger 30 internal-link updates across the library can create maintenance overhead disproportionate to value. The internal-link refresh should be targeted, not exhaustive. + +--- + +## URL preservation vs URL change + +Most refreshes preserve the URL. Some warrant URL change. + +**Preserve the URL when:** + +- The refresh is light edit, substantial revision, or most full rewrites. +- The existing URL has authority worth preserving (rankings, backlinks, internal-link references). +- The URL slug fits the refreshed piece's framing reasonably well even if not perfectly. + +**Change the URL when:** + +- The refresh is a structural redesign and the URL slug no longer fits. +- The piece is being merged with a sibling and the consolidated piece needs a new URL. +- The original URL was a structural mistake (wrong category, awkward slug) that the refresh is correcting. + +**The URL-change cost.** Even with 301 redirects, URL changes incur authority transfer cost; some authority does not survive the redirect. URL changes should be earned by structural rationale, not chosen for cosmetic reasons. + +**The URL-preservation discipline.** Most refreshes should preserve URLs. The default disposition is preserve; URL change is the exception requiring rationale. + +--- + +## The refresh that nobody told anyone about + +The pattern when re-promotion is skipped. + +**The symptom.** A refresh ships. Modified date updates. Schema validates. The piece sits in the library with the refresh complete on paper. Traffic recovers marginally if at all. The team concludes refresh does not work. + +**The actual cause.** Re-promotion was skipped. The refresh signaled to the search engine but did not signal to audiences. New-piece-style audience engagement (newsletter, social, syndication) did not happen. The refresh produced search-engine recognition without the audience-engagement spike that often drives broader recovery. + +**The cure.** Build re-promotion into the refresh workflow as a non-skippable step. The refresh is not "done" when the piece is published; the refresh is "done" when the re-promotion has been executed. Define re-promotion intensity per depth (light edit may need only modified-date and schema; substantial revision needs newsletter and social re-share; full rewrite needs full re-promotion treatment). + +--- + +## Re-promotion checklist by depth + +A short framework matching re-promotion to refresh depth. + +**Light edit re-promotion.** + +- Modified date in schema and visible. +- Sitemap lastmod. +- No audience re-share required for routine light edits. +- Internal-link audit only if specific anchor text changes warranted. + +**Substantial revision re-promotion.** + +- Modified date and visible date. +- Sitemap lastmod. +- Newsletter re-share with framing on what was updated. +- Social re-share to channels that originally promoted the piece. +- Internal-link audit on sister pieces with relevant topics. + +**Full rewrite re-promotion.** + +- All of the above. +- Search Console URL inspection and resubmission. +- Syndication partner update where applicable. +- Email-list segment send to engaged segments. +- Visual asset refresh for social and newsletter (new pull-quote graphics, new hero image if applicable). + +**Structural redesign re-promotion.** + +- All of the above. +- Coordination with the broader hub or category being redesigned (see `pillar-content-architecture`). +- Cross-piece internal-link audit across the affected hub or category. +- Possible launch communication if the redesign represents a major program milestone. + +--- + +## Re-promotion failure modes + +**Skipping re-promotion entirely.** The refresh produces marginal recovery; the team concludes refresh does not work; the program loses momentum. + +**Bulk-resubmitting every refresh URL to Search Console.** Search Console's URL submission has implicit rate limits; bulk submission of low-value refreshes throttles the team's submission capacity for the cases that warrant it. + +**Re-share without specificity.** "We refreshed this piece; here it is" lacks the specific framing that earns re-engagement. Specific framing ("we added the 2026 data and a new section on X") earns clicks; vague re-shares get ignored. + +**Anchor-text updates that proliferate.** Internal-link refresh that touches every mention of the topic across the library is over-investment. Target specifically; touch sparingly. + +**Modified-date bumping without content change.** The signal that gets discounted by search engines and signals to careful auditors that the team is gaming the metric rather than producing substantive refresh. + +--- + +## Methodology-level choices that stay in the public skill + +The signal-to-search-engine patterns, the substantive-vs-cosmetic distinction, the audience re-promotion patterns, the internal-link refresh discipline, the URL-preservation default, the re-promotion checklist by depth, the re-promotion failure modes. + +## Implementation choices that stay internal + +Specific schema markup automation in the team's CMS. Specific newsletter and social-publishing tooling and templates. Specific Search Console workflow conventions. Specific internal-link-audit automation. Specific syndication-partner communication channels. The team's own depth-to-re-promotion-intensity mappings. These vary by team, stack, and channel mix. diff --git a/skills/content-refresh-system/references/refresh-depth-decision.md b/skills/content-refresh-system/references/refresh-depth-decision.md new file mode 100644 index 0000000..4e55045 --- /dev/null +++ b/skills/content-refresh-system/references/refresh-depth-decision.md @@ -0,0 +1,174 @@ +# Refresh depth decision + +Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, the depth-creep anti-pattern. + +Refresh depth is one of the most consequential decisions in the program. The wrong depth produces predictable failure: light edits on pieces that needed substantial revision produce no recovery; full rewrites on pieces that only needed factual updates burn capacity. The discipline is matching depth to signal strength. + +--- + +## Depth 1: Light edit + +**The work.** Update statistics. Replace dead links. Fix factual errors. Swap dated examples. Update product or platform references. Verify external links still resolve and still go where they should. + +**Time investment.** 30-90 minutes per piece for typical pieces. Longer for research-heavy pieces with many external citations. + +**The piece's structure stays intact.** Section weights, lede, closing, archetype, voice, claims-and-arguments are all preserved. The light edit is surface maintenance. + +**Use when.** + +- Factual staleness is the only or dominant signal. +- Traffic is stable or only slightly decayed. +- The piece's structural framing still fits current SERP intent and brand positioning. +- The piece is performing well enough that significant changes would risk performance. + +**Common failures.** + +- Light-editing when substantial revision is warranted. Surface fixes do not address the structural reasons for decay; the piece continues to decay after the light edit ships. +- Light edits that touch more than they should. A "light edit" that becomes 4 hours of work because the editor kept finding things has lost the depth discipline; either commit to substantial revision or stop at the originally scoped scope. + +--- + +## Depth 2: Substantial revision + +**The work.** Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that have emerged since the piece was written. Restructure 1-3 H2 sections without redesigning the piece's overall shape. + +**Time investment.** 2-4 hours per piece for typical pieces. Longer for pieces with extensive new sections to add. + +**The piece's spine stays intact.** The archetype, the central thesis, and most sections survive. Specific sections are rewritten or added. + +**Use when.** + +- Traffic has decayed moderately but not catastrophically. +- Specific sections of the piece have aged badly (often the introduction, closing, or a section on a topic that has shifted). +- New topics have emerged that the piece needs to cover to stay current. +- The piece's structural framing is mostly fine but needs targeted updates. + +**Common failures.** + +- Substantial revision drifting into full rewrite. The "substantial revision" that becomes 8 hours of work has crossed into full-rewrite territory; either commit to full rewrite or scope back to the original substantial-revision plan. +- Substantial revision that rewrites the introduction without rewriting the closing, leaving the piece structurally inconsistent (the introduction promises one shape; the closing delivers a different one). +- Rewriting sections without auditing whether the rewrites match each other in voice and density. + +--- + +## Depth 3: Full rewrite + +**The work.** Keep the URL and topic; rewrite the piece end-to-end. New lede, new structure (possibly new archetype), new closing. The new piece occupies the old piece's URL and connects to the existing internal-link graph. + +**Time investment.** Similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. 8-16 hours for typical long-form rewrites. + +**The piece's spine changes.** New archetype possible. New positioning possible. The connection to the URL and the existing topical authority is what is being preserved; everything else can change. + +**Use when.** + +- Traffic has decayed sharply or persistently. +- The piece's structural framing no longer fits current SERP intent. +- The brand's positioning has shifted enough that the piece needs to be re-conceived. +- Light edit and substantial revision have already been tried and did not produce recovery. + +**Common failures.** + +- Full rewrite that loses what worked. The original piece had specific strengths (a memorable lede, a particular section that drew links). The rewrite that does not preserve those strengths can perform worse than the original even if the rewrite is technically stronger. +- Full rewrite that breaks internal linking. Section IDs change, anchor links from sister pieces break, the internal-link graph that supported the piece's authority is disrupted. +- Full rewrite that ignores the URL constraint. The team rewrites as if writing a new piece, then realizes the URL is locked and the new framing does not fit the existing slug. Either accept the slug mismatch (suboptimal) or change the URL (incurring redirect cost). + +--- + +## Depth 4: Structural redesign + +**The work.** Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Often part of a larger structural change in the content library: a hub being rebuilt, a category being consolidated, a topic cluster being reorganized. + +**Time investment.** A multi-piece project. 1-3 weeks for a hub-level restructure involving multiple pieces. + +**Multiple URLs and pieces are affected.** The piece being refreshed is one node in a graph that is being reshaped. + +**Use when.** + +- Refresh of an individual piece is bumping against architecture-level issues that cannot be addressed at the piece level. +- A hub is being redesigned and pieces within the hub need to be reconceived as part of the redesign. +- Multiple pieces are competing for the same query and a consolidated piece would produce stronger authority than any of the individual pieces. + +**Common failures.** + +- Treating structural redesign as a refresh exercise rather than as a project. The work scope is project-scope; treating it as a refresh queue item leads to under-resourcing. +- Structural redesign without coordination with `pillar-content-architecture` discipline. The hub-level work and the piece-level work need to compose; doing them separately produces friction. +- Redirect plans that do not account for all the URLs being consolidated. Some authority is lost in transit because some redirects were missed. + +--- + +## Signal-to-depth matching + +A short framework for choosing depth from the signals. + +**Light edit when:** + +- Factual staleness is the dominant signal. +- Traffic stable or only slightly decayed (under 10%). +- Rankings stable or only slightly drifted. +- No SERP intent shift detected. +- No content drift detected. + +**Substantial revision when:** + +- Multiple signal types present (factual + content drift, or traffic decay + ranking drops). +- Traffic decayed moderately (10-25%). +- Rankings drifted but still on page 1. +- Specific sections have aged badly while others are sound. +- SERP intent has not shifted dramatically. + +**Full rewrite when:** + +- Traffic decayed sharply (25%+). +- Rankings dropped from page 1 to page 2 or beyond. +- SERP intent has shifted substantially (the dominant SERP format has changed). +- Brand positioning has shifted enough that the piece reads as the brand-of-multiple-years-ago. +- Light edit or substantial revision already attempted without recovery. + +**Structural redesign when:** + +- The piece's issues are architecture-level rather than piece-level. +- A hub or category is being reorganized. +- Multiple sibling pieces are competing for the same query and consolidation would produce stronger authority. + +--- + +## The depth-creep anti-pattern + +Refreshes that grow during execution from their planned depth into a deeper depth that was not budgeted. + +**The pattern.** A refresh planned as a light edit becomes substantial revision because the editor "kept finding things." The substantial revision becomes a full rewrite because once you are restructuring two sections you might as well restructure the rest. The piece ships 6 weeks after planned, having consumed 4x the planned capacity. + +**Why it happens.** Editors and writers are pattern-matchers; once they start working on a piece, they see all its problems and want to fix all of them. The discipline of staying at the planned depth is not natural to editorial work. + +**The cure.** Two options. + +1. **Stop at scope.** When the editor finds work beyond the planned depth, log it but do not do it. The next quarter's audit can decide whether the piece needs deeper work; this refresh ships at the planned depth. +2. **Re-scope explicitly.** When the editor discovers the planned depth is wrong, halt the refresh and re-scope formally. The capacity allocation gets adjusted; the timing gets adjusted; the team is aware the refresh became a bigger project. + +The failure mode is the third option: keep going at deeper depth without explicit re-scoping. That produces capacity overruns and missed timelines that affect other work. + +--- + +## Multi-depth refresh sequences + +Some pieces benefit from a sequence of refreshes at different depths over time. + +**The pattern.** + +- Light edit ships first to address factual staleness while broader investigation continues. +- Substantial revision follows in the next quarter once SERP intent shift has been analyzed and the right structural changes are clear. +- Full rewrite follows in 2-3 quarters if the substantial revision did not produce recovery. + +**When this pattern fits.** High-value-decaying pieces where the right disposition is unclear and the team wants to avoid premature commitment to a full rewrite. Light-edit-first preserves what works while buying time for analysis. + +**When this pattern fails.** Programs that always start with light edit on high-value-decaying pieces, regardless of signal strength, because light edit is the easiest depth to schedule. The light edit does not move the needle, and the next quarter's audit shows the same piece in the same queue. + +--- + +## Methodology-level choices that stay in the public skill + +The four depth levels with their work, time investment, and use cases. The signal-to-depth matching framework. The depth-creep anti-pattern with its cure. The multi-depth refresh sequence pattern. + +## Implementation choices that stay internal + +Specific time-tracking that captures actual depth per refresh. Specific scope-confirmation tooling that flags depth-creep. Specific writer or editor assignment patterns by depth (some writers are stronger at light edits; some at full rewrites). Specific brief templates per depth in the team's writing system. These vary by team and tooling. diff --git a/skills/content-refresh-system/references/refresh-execution-patterns.md b/skills/content-refresh-system/references/refresh-execution-patterns.md new file mode 100644 index 0000000..9cee5bb --- /dev/null +++ b/skills/content-refresh-system/references/refresh-execution-patterns.md @@ -0,0 +1,154 @@ +# Refresh execution patterns + +Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. The execution patterns that turn audit queues into shipped refreshes. + +The audit produces a queue. The execution patterns turn the queue into shipped work. Programs that produce strong audits but weak execution end up with documentation of what should have been refreshed rather than refreshed pieces. + +--- + +## Single owner per refresh + +Each refresh has one owner accountable for shipping it. + +**The pattern.** When a refresh is assigned, one person is named as the owner. The owner runs the work end-to-end: confirming the depth, doing or coordinating the actual editorial work, running the QA gate, shipping, re-promoting, logging the outcome. + +**Why single ownership matters.** Refreshes that pass through multiple hands without a clear owner often get partially done and then stall. One person believes another is finishing the work; the work sits between them; the audit's next pass shows the piece still in queue. The accountability gap is the failure mode. + +**Owner selection.** Typically the writer or editor best matched to the topic. For light edits, the owner can be anyone with capacity; for substantial revision and full rewrite, ownership matches expertise. For structural redesign, ownership often sits with a content lead because the work spans multiple pieces. + +**Owner-of-owners.** A single person owns the refresh program as a whole. Their job is keeping the queue moving, escalating stalled refreshes, ensuring effectiveness measurement is happening, and reporting on the program's health to leadership. Without this role, the program drifts even if individual refreshes have owners. + +--- + +## Editorial-workflow integration + +Refreshes typically run through the same editorial workflow as new pieces, scaled to the chosen depth. + +**Light edit workflow.** May skip the brief and go straight to edit. The editor pulls the piece, identifies the specific updates, makes them, runs a QA pass, and ships. 30-90 minutes of editorial time; minimal coordination. + +**Substantial revision workflow.** Brief, draft, edit, QA gate, publish. The brief covers the targeted sections being rewritten; the draft is partial-rewrite; the edit and QA gate match new-piece discipline. 2-4 hours of editorial time; coordination similar to a short blog post. + +**Full rewrite workflow.** Brief, draft, edit, QA gate, publish. Full new-piece workflow with the additional constraint of preserving the URL and existing internal-link integration. 8-16 hours of editorial time; coordination at long-form-piece scale. + +**Structural redesign workflow.** Project-scope coordination. Multiple briefs, multiple drafts, redirect plans, internal-link audits. Multi-week timeline; coordination at flagship-project scale. + +The integration discipline. Refreshes are not a separate workflow; they plug into the existing editorial workflow at the appropriate depth. Teams that build a parallel refresh workflow create coordination overhead and quality drift; teams that integrate refresh into the standard workflow benefit from the workflow's existing discipline. + +--- + +## Capacity allocation + +Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff. + +**Allocation patterns.** + +- **Newer libraries (under 100 pieces, under 2 years old):** 5-15% of capacity to refresh. Most pieces are still relatively current; signals are limited. +- **Mid-stage libraries (100-500 pieces, 2-5 years old):** 15-30% of capacity to refresh. Decay rates have built up; high-value-decaying queue is meaningful. +- **Mature libraries (500+ pieces, 5+ years old):** 25-40% of capacity to refresh. Cumulative decay is significant; without sustained refresh capacity, the library erodes. + +**The capacity-vs-new-production tradeoff.** + +A team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. Or 8 to refresh, 12 to new. The split affects program shape: heavy-refresh programs preserve existing equity; heavy-new-production programs build new topical authority. + +**Right-sizing the allocation.** + +- If refresh queues are growing quarter-over-quarter, allocation is too low. +- If new-production output is dropping or the team complains of refresh fatigue, allocation may be too high. +- If high-value-decaying pieces stay in queue across multiple audits, allocation is misallocated (volume of work, not allocation share, may be the issue, but allocation review is the first step). + +**The capacity audit.** Quarterly, review the actual refresh time spent vs the planned allocation. Programs that consistently exceed their allocation are signaling that the queue's growth rate exceeds the allocation; either grow allocation, narrow the prioritization, or accept slower queue cycle times. + +--- + +## Batching vs integration + +Two patterns for how refresh work fits into the cadence. + +**Batching.** Dedicated weeks or sprints for refresh work. The team blocks 1-2 weeks per quarter for concentrated refresh execution. + +- **Strength.** Focus. The team is in refresh mode; context-switching costs are low; throughput on refresh work is high. +- **Weakness.** Interrupts new production. New-piece workflows pause during refresh sprints; pieces in the new-production pipeline stall. +- **Fits.** Mid-stage libraries with manageable refresh queues; teams that prefer focused work blocks; programs with predictable seasonality where new production has natural pauses. + +**Integration.** One refresh per week (or similar steady cadence) integrated into the regular production cadence. + +- **Strength.** Sustains new production. New-piece work continues without pauses. +- **Weakness.** Slower refresh velocity per piece; context-switching costs are higher; refresh work can get deprioritized in favor of "more urgent" new-piece work. +- **Fits.** Mature libraries with continuous refresh queues; teams that prefer sustained pacing; programs where new production has tight commitments. + +**Hybrid.** A baseline integration cadence plus periodic batching for the high-priority queue. + +- **Strength.** Sustained refresh on lower-priority work; periodic concentration on high-value-decaying queues. +- **Weakness.** Coordination overhead; the team manages both modes. +- **Fits.** Mature programs with sophisticated capacity planning. + +The discipline. Pick a pattern. The failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence and a queue that never clears. + +--- + +## The refresh that needs to happen now + +Some refreshes cannot wait for the next allocation slot. + +**Trigger conditions.** + +- Sharp decay (40%+ traffic loss in 30 days) on a high-value piece. +- Algorithm-update fallout affecting a high-value piece. +- Factual error producing reputational risk. +- Broken page state (indexing failure, schema regression, redirect loop). + +**The fast-track pattern.** + +- Continuous monitoring detects the issue. +- The owner-of-owners decides whether the issue warrants fast-track. +- Fast-track refreshes get pulled out of the queue and shipped within days. +- The refresh skips some workflow steps if necessary (briefer brief, faster QA) but does not skip the QA gate; pieces that ship without QA produce regressions that compound. + +**Fast-track capacity.** Teams need a small reserve for fast-track work. The reserve is typically 5-10% of total capacity. Without reserve, fast-track work pushes other work out and produces cascade delays. + +--- + +## Stalled refresh recovery + +Refreshes that have been in queue for more than two audit cycles need intervention. + +**Common causes.** + +- Owner is over-committed; the refresh is not the highest priority on their plate. +- The refresh's depth was wrong (planned as light edit, actually needed substantial revision); the owner stalled rather than escalate. +- The refresh's disposition was wrong (planned as refresh, should have been merge); the owner is uncertain how to proceed. + +**The recovery pattern.** + +- Owner-of-owners reviews stalled refreshes at each audit. +- Reassign owners where capacity is the issue. +- Re-scope where depth was wrong; re-disposition where the disposition was wrong. +- For refreshes stalled because the analysis revealed a deeper issue, escalate to a content lead for decision. + +The stalled-refresh review prevents the queue from accumulating zombie items that everyone knows are not getting done but nobody is removing. + +--- + +## Common execution failures + +**No single owner.** Refreshes are assigned to "the team"; nobody is accountable; the refresh stalls. + +**Workflow shortcuts.** The refresh skips the QA gate or the brief. Quality drifts; regressions compound. + +**Capacity overcommitment.** The team plans 20% capacity for refresh; actual refresh work consumes 35%; new production suffers; team burns out. + +**Refresh queue without owner-of-owners.** The queue grows; nobody is reporting on its health; the program drifts toward set-and-forget within the formal-program shape. + +**Fast-track without reserve.** Urgent refreshes push planned work out; cascade delays affect downstream pieces. + +**Stalled refreshes accumulating.** The queue has zombie items in it; the queue's reported health does not match the queue's actual state. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner discipline, editorial-workflow integration shapes by depth, capacity allocation patterns by library stage, batching vs integration vs hybrid tradeoffs, the refresh-that-needs-to-happen-now pattern, the stalled-refresh recovery pattern. + +## Implementation choices that stay internal + +Specific project-management tooling for the refresh queue. Specific notification systems for refresh assignments. Specific time-tracking for capacity audits. Specific reserves and fast-track triage workflows. The team's own conventions for owner reassignment. These vary by team, tooling, and program shape. diff --git a/skills/content-refresh-system/references/refresh-prioritization-matrix.md b/skills/content-refresh-system/references/refresh-prioritization-matrix.md new file mode 100644 index 0000000..8b4649b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-prioritization-matrix.md @@ -0,0 +1,148 @@ +# Refresh prioritization matrix + +The 2x2 prioritization matrix with quadrant strategies. The discipline of NOT refreshing the high-value-stable quadrant. The under-recognized failure of treating low-value-decaying as automatic refresh candidates. + +Most libraries have more pieces showing signals than the team has capacity to refresh. Without prioritization, refresh work happens on the cheapest pieces or the most visible pieces, leaving high-value-decaying pieces in the backlog while editorial capacity goes to pieces that would not have produced recovery worth the effort. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. + +--- + +## The two axes + +**Piece value.** A composite of business value, traffic value, and strategic role. + +- **Business value.** Pieces that drive conversions, qualified leads, or specific business outcomes. Sometimes measurable directly (pieces that close a defined funnel step), sometimes attributed (pieces that influence subsequent conversions). +- **Traffic value.** Pieces that drive meaningful organic traffic, especially on commercial-intent keywords or topical-authority-building queries. +- **Strategic role.** Pieces that anchor a hub, that establish the brand's POV on a flagship topic, or that earn external citations and links. Strategic role can outweigh raw traffic; a 500-traffic flagship piece is high-value if it is the canonical statement of the brand's position. + +Pieces are classified as high-value (HV) or low-value (LV). The line between HV and LV is judgment-driven; teams typically settle the criteria by establishing tiers (top 10% by value, next 30%, bottom 60%, or similar). + +**Traffic state.** A composite of recent and trending traffic. + +- **Stable.** Traffic over the last 90 days is within 10-15% of the prior 90-day baseline, accounting for seasonality. +- **Decaying.** Traffic over the last 90 days is down meaningfully (15%+ beyond seasonal baseline), or trending consistently down over multiple quarters. + +Pieces are classified as stable or decaying. The classification is the easier of the two axes because traffic data is cleanly measurable. + +--- + +## Quadrant 1: High-value, decaying + +**Top priority.** + +**The pieces.** Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. + +**The strategy.** Refresh first; the traffic loss compounds and the lost equity is hard to recover. These pieces are usually worth substantial-revision or full-rewrite refresh depth because the value at stake justifies the work. + +**The disposition decision.** Almost always refresh. Merge candidates in this quadrant exist (a high-value piece that is decaying because a sister piece is competing for the same query) but are uncommon. Delete is essentially never the right disposition for a high-value piece. + +**Capacity allocation.** This quadrant gets the largest share of refresh capacity. Many programs allocate 60-70% of total refresh capacity to high-value-decaying pieces. + +**Expected outcomes.** Recovery measured at 30 and 90 days. Strong refreshes on this quadrant typically produce 20-50% traffic recovery within 90 days; full rewrites can produce more. + +**Common failures.** + +- Treating this quadrant as "save for later" because the work is heavy. The traffic loss continues during the delay. +- Light-editing high-value-decaying pieces when substantial revision is warranted. The light edit does not move the needle and the team concludes refresh does not work. +- Not investigating the cause. A piece that is decaying because a competitor published a better resource needs different work than a piece decaying because of SERP intent shift. + +--- + +## Quadrant 2: High-value, stable + +**Monitor; do not refresh proactively.** + +**The pieces.** Pieces that are performing strongly and showing no decay signals. + +**The strategy.** Leave alone. Refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. Pieces that are working should not be touched without clear signal. + +**The disposition decision.** No action; monitor through continuous monitoring for emerging decay; review at quarterly audits for content drift signals. + +**The discipline.** This is the quadrant that calendar-refresh programs damage most. A piece ranking position 2 with stable traffic gets refreshed because it is the next piece in the rotation; the refresh introduces minor changes that shift the SERP signals; ranking drops to position 5; traffic drops 30%. The refresh that was meant as maintenance was actually destruction. + +**When to revisit.** Monitor for emerging signals. If traffic starts decaying or rankings drop, the piece moves to high-value-decaying. If content drift becomes pronounced (the piece is performing but the team sees positioning misalignment), substantial revision may be warranted but only if the team is willing to risk the performance. + +**Common failures.** + +- Refresh-on-calendar damaging stable pieces. +- Treating stable rankings as a refresh target because the team wants to "improve" the piece. Improvement on stable pieces is a high-risk operation. +- Touching the URL, schema, or core copy of a stable piece without strong rationale. + +--- + +## Quadrant 3: Low-value, decaying + +**Audit for merge or delete.** + +**The pieces.** Pieces with low traffic that are decaying further. Pieces that never had strong demand and are now losing what little they had. + +**The strategy.** The default disposition is NOT refresh. Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. The actual disposition is usually merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling or relevant hub). + +**The disposition decision.** + +- **Merge** when a sibling piece on a related topic is performing better and could absorb the failing piece's content. Merging consolidates authority and produces a stronger consolidated piece. The merged URLs redirect to the survivor. +- **Delete** when no merge candidate exists, the topic is not load-bearing for the program, and the piece's residual value (small as it is) does not justify maintenance. Delete and redirect to the closest sibling piece or hub. +- **Refresh** is occasionally warranted: when the piece has clear strategic role (anchors a small but important sub-topic) and the decay is recoverable. Rare in this quadrant. + +**Capacity allocation.** This quadrant gets the smallest share of refresh capacity but a meaningful share of disposition work (merges and deletes are real work, less than full rewrites but more than light edits). + +**Common failures.** + +- Refreshing pieces in this quadrant by default. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. +- Skipping the merge analysis. Pieces that should have been merged get refreshed in isolation, leaving the authority-splitting problem intact. +- Avoiding deletes because deleting feels destructive. Maintaining a library of low-value pieces forever costs ongoing audit attention and dilutes overall library quality. + +--- + +## Quadrant 4: Low-value, stable + +**Leave alone.** + +**The pieces.** Pieces with low traffic that are not actively decaying. They are at the floor. + +**The strategy.** Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +**The disposition decision.** No action. Pieces that have been low-traffic-stable for multiple audits are candidates for batch consideration: do they collectively represent a topic that is no longer load-bearing for the program? If yes, a structural decision (delete the topic cluster, merge into a hub, archive) may be warranted at program level. If no, leave alone. + +**When the strategy fails.** If a low-value-stable piece starts decaying further (moves to low-value-decaying), the disposition is reconsidered. Usually merge or delete. + +**Common failures.** + +- Refresh-on-calendar touching this quadrant. Pure capacity waste. +- Treating low-traffic as a problem to be solved. Low traffic on a low-value piece is the right outcome; not every piece needs to drive significant traffic. Some pieces serve narrow but real strategic roles at low volume. + +--- + +## Capacity allocation by quadrant + +A typical refresh program's capacity might split as: + +- **High-value, decaying:** 60-70% of refresh capacity. The largest share, on the highest-value work. +- **Low-value, decaying:** 15-20% of capacity, mostly on merge and delete dispositions, occasional refresh on strategically important pieces. +- **High-value, stable:** 5-10% of capacity, on the rare cases where content drift warrants substantial revision despite stable performance. +- **Low-value, stable:** 0-5% of capacity. Mostly batch reviews to identify topic-level decisions. + +The allocation varies by library age and decay rates. Newer libraries with limited decay have less work in the decaying quadrants and may invest more in continuous-monitoring infrastructure. Older libraries with significant decay have more work to do across quadrants. + +--- + +## Common matrix failures + +**The "every piece is high-value" trap.** Teams that classify too many pieces as high-value lose the prioritization signal. A library where 60% of pieces are "high-value" is essentially unprioritized; the matrix fails to discriminate. + +**The traffic-only value classification.** Classifying value purely by traffic misses strategic-role pieces that have lower traffic but high importance. A flagship manifesto that earns 800 visits a month but drives external citations and brand recognition is high-value despite lower traffic. + +**The "refresh = recovery" assumption.** Some pieces in the high-value-decaying quadrant cannot be recovered through refresh. The topic is genuinely declining; competitors are too strong; SERP intent has shifted away from any format the brand can produce. The matrix prioritizes refresh; it does not promise refresh will work. The effectiveness measurement (see `effectiveness-measurement.md`) catches the cases where refresh is not producing recovery. + +**Static classification.** Value and traffic state both shift over time. A piece in low-value-stable that suddenly draws traffic from an emerging keyword moves to high-value-stable; a piece in high-value-decaying that fully recovers moves to high-value-stable. The matrix is not a one-time classification; it is the framework run at each audit. + +--- + +## Methodology-level choices that stay in the public skill + +The two axes (value, traffic state), the four quadrants with strategies, the capacity allocation guidance, the common matrix failures, the dynamic-classification discipline. + +## Implementation choices that stay internal + +Specific value-classification rubrics the team uses (revenue attribution models, strategic-role tagging, traffic-tier definitions). Specific scripts that classify pieces into quadrants from data pulls. Specific dashboards that visualize the matrix at audit time. The team's own conventions for high-value-stable refresh decisions when content drift is pronounced. These vary by team, business model, and analytics setup. diff --git a/skills/content-refresh-system/references/refresh-signals-checklist.md b/skills/content-refresh-system/references/refresh-signals-checklist.md new file mode 100644 index 0000000..bddf11b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-signals-checklist.md @@ -0,0 +1,164 @@ +# Refresh signals checklist + +Five signal categories that trigger refresh consideration, with detection patterns and the audit shape that surfaces signals across the library. + +Pieces that show no signals do not need refresh. Pieces that show one or two signals warrant attention. Pieces that show three or more signals are typically in active decay and should be high in the prioritization queue. The signal taxonomy below is what distinguishes triaged refresh from calendar refresh. + +--- + +## Signal 1: Traffic decay + +Organic traffic to the piece is trending down over a 90+ day window beyond seasonal baseline. + +**Detection patterns.** + +- Pull traffic data per URL over rolling 90-day windows. +- Compare current 90 days to prior 90 days, accounting for known seasonality. +- A drop of more than 15-20% beyond seasonality on a piece that previously had stable traffic is a real signal. +- A drop of more than 40% in a 30-day window is a sharp signal warranting urgent review. + +**What the signal usually means.** + +- **Slow decay (5-10% over a year):** content drift. The piece is gradually losing relevance as the topic evolves or the brand's voice shifts. +- **Moderate decay (15-30% in a quarter):** ranking position drift, or SERP intent shifting, or competitor publication. +- **Sharp decay (40%+ in a month):** algorithm update, indexing issue, dramatic SERP intent shift, or technical regression on the URL. + +**Diagnostic next steps.** When traffic decay is detected, check ranking positions for the piece's target keywords (signal 2 may also be active), check for technical issues (indexability, page speed, broken redirects), and check the SERP for intent shift (signal 4). + +**Anti-patterns in detection.** + +- Comparing month-over-month rather than 90-day windows over-attributes seasonal noise to decay. +- Ignoring known seasonality (holiday traffic, B2B dropping in late December) produces false positives. +- Looking only at total traffic instead of organic specifically blurs the signal with referral or paid changes. + +--- + +## Signal 2: Ranking drops + +The piece is losing position on its target keywords. + +**Detection patterns.** + +- Track each piece's primary 3-10 target keywords with rank tracking. +- Drops from page 1 to page 2-3 are particularly consequential because click-through rates fall sharply at the page-1-to-page-2 boundary. +- Drops within page 1 (position 3 to position 7) reduce clicks but are less existential. +- Persistent drops over 30+ days are real shifts; week-over-week volatility within a few positions is normal. + +**What the signal usually means.** + +- A piece that was at position 3 and is now at position 8 has been displaced by stronger competing pieces. The displacement is informative; review what is now ranking and what those pieces have that this piece does not. +- A piece that was at position 5 and is now at position 35 has likely been algorithm-affected, indexing-affected, or technically regressed. Investigate before refresh; refreshing a piece with an indexing issue does not solve the indexing issue. +- Drops on long-tail keywords with simultaneous gains on broader head terms can indicate the piece's focus has broadened beneficially. Not always a refresh signal. + +**Diagnostic next steps.** Pull the SERP for each target keyword. Examine what is ranking. Identify whether the new rankings are stronger pieces (refresh signal: improve the piece) or different SERP intent (signal 4: SERP intent shift, possibly different format needed). + +**Anti-patterns in detection.** + +- Treating any rank movement as a refresh signal produces refresh-on-noise; require persistence over 30+ days. +- Tracking only branded keywords misses the meaningful organic ranking signal. +- Ignoring keyword cannibalization (multiple pieces competing for same keyword) treats split rankings as a refresh signal when the actual disposition is merge. + +--- + +## Signal 3: Factual staleness + +The piece contains statistics, references, examples, or claims that are dated. + +**Detection patterns.** + +- Annual review of statistics in the piece. Any stat older than 3 years on a fast-moving topic is a candidate for staleness flagging. +- Reference checks for defunct products, platforms, services, or companies named in the piece. +- Example checks for examples that have aged poorly (a 2019 case study of a company that has since gone bankrupt or changed direction). +- Framing checks for claims that no longer match current reality ("AI is starting to influence search" in 2026 is anachronistic). + +**What the signal usually means.** + +- Factual staleness alone is often a light-edit signal: update the stats, replace dead links, swap dated examples. The piece's structure may be sound. +- Factual staleness combined with traffic decay or ranking drops is a stronger signal that the piece's broader framing has aged, not just the surface details. +- Factual staleness on a flagship piece is more urgent than on a low-traffic piece because flagship pieces are read by more people who notice the staleness. + +**Diagnostic next steps.** List the specific stale facts, references, and examples. Estimate the light-edit time required to refresh them. If the structural framing is also stale, the depth required is substantial revision rather than light edit. + +**Anti-patterns in detection.** + +- Treating every old stat as stale when the stat may still be current (some stats genuinely have not changed in 3 years) produces unnecessary refresh. +- Ignoring framing-level staleness while updating individual stats produces pieces that are technically current in stats but feel old in voice. + +--- + +## Signal 4: SERP intent shift + +The dominant SERP format for the target keyword has changed. + +**Detection patterns.** + +- Pull the current SERP for each target keyword. What format is dominating? Articles? Listicles? Videos? Product comparisons? AI overviews? +- Compare to the piece's format. If the piece is an article and the SERP wants product comparisons, intent has shifted. +- Watch for new SERP features that did not exist when the piece was written: AI overviews, generative answers, knowledge panels, featured-snippet shifts. + +**What the signal usually means.** + +- The piece may still rank but increasingly for the wrong reasons. Click-through rates fall as the SERP signals the piece is not the dominant intent match. +- The piece may need format restructuring (full rewrite or substantial revision rather than light edit) to fit the new dominant intent. +- Sometimes the right disposition is to write a NEW piece in the new dominant format and either consolidate the old piece into it or keep the old piece for the residual intent it still serves. + +**Diagnostic next steps.** Read the top-ranking pieces for the target keyword. What format are they? What questions do they answer that the piece does not? Decide whether refresh in the new format will recover the position, or whether a new piece in the new format is the better disposition. + +**Anti-patterns in detection.** + +- Ignoring AI-overview presence on the SERP. AI overviews change click-through rates substantially and may indicate the piece needs restructuring for AI search citation. +- Assuming SERP intent is stable. Some keywords have stable intent for years; others shift quarterly. The audit should be active. + +--- + +## Signal 5: Content drift + +The piece's positioning no longer matches the brand's current positioning. + +**Detection patterns.** + +- The piece's voice reads as the brand-of-three-years-ago. Vocabulary, tone, level of conviction. +- The piece's POV on the topic has not kept up with how the brand now thinks. The brand has sharpened a position the piece treats with old hedging. +- The piece's framing fits the audience the brand had then, not the audience the brand has now. +- The piece's calls-to-action, internal linking, and product references reflect older brand offerings that have since changed. + +**What the signal usually means.** + +- Content drift is internal signal. Readers may not consciously notice, but the team will, and over time the library's voice incoherence weakens the brand. +- Content drift is often paired with the team's discomfort about which pieces in the library represent the brand best when sharing externally. +- Content drift is rarely the sole driver of a refresh decision (because traffic and rankings may be fine), but it determines depth: a content-drift refresh is usually substantial revision or full rewrite, not light edit. + +**Diagnostic next steps.** Identify which sections drift hardest from current positioning. If drift is concentrated in introduction, closing, and CTAs, substantial revision can address it. If drift is throughout, full rewrite is the cleaner disposition. + +**Anti-patterns in detection.** + +- Treating every voice evolution as drift triggers calendar refresh of pieces that are still serving readers. +- Ignoring drift because the piece is performing in search produces a library that performs but no longer represents the brand. + +--- + +## The library audit + +Running the signal taxonomy across the whole library. + +**Audit shape.** + +- Pull a per-URL data set: traffic over time, rankings, last-modified date, target keywords, business-value tag (high/medium/low). +- For each URL, run the five signal checks. Mark each signal as present or absent. +- Pieces with zero signals: stable; no action. +- Pieces with one or two signals: candidate queue; review individually for disposition. +- Pieces with three or more signals: active-decay queue; high priority for disposition decision. + +**Output.** A spreadsheet or database of pieces with their signals and the resulting disposition (refresh, merge, delete, monitor). The output feeds the prioritization matrix and the refresh queue. + +**Cadence.** Full audit quarterly. Continuous monitoring for traffic-decay and ranking-drop signals; manual signal checks (factual staleness, SERP intent shift, content drift) at quarterly cadence. + +--- + +## Methodology-level choices that stay in the public skill + +The five signal categories with detection patterns and what each signal means; the audit shape across the library; the cadence; the anti-patterns in detection. The signal-to-disposition mapping that informs prioritization. + +## Implementation choices that stay internal + +Specific data pulls from the team's analytics platform. Specific rank-tracking thresholds. Specific automation that runs continuous monitoring. Specific reviewer dashboards that surface signals. Specific seasonality models the team uses to baseline traffic. The team's own tags for business-value classification. These vary by team, tooling, and analytics setup. diff --git a/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md b/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md new file mode 100644 index 0000000..e1b242b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md @@ -0,0 +1,137 @@ +# Refresh vs merge vs delete + +The disposition decision. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged or deleted. + +Most refresh programs default to refresh as the disposition. The default is wrong. Some pieces should be merged into stronger siblings; some should be deleted and redirected. The disposition decision is upstream of the depth decision: a piece getting deleted does not need depth, and a piece being merged is doing a different kind of work than refresh. + +--- + +## Refresh + +The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +**Criteria for refresh disposition.** + +- The piece has demonstrated demand: it draws meaningful traffic now or did historically. +- The topic is one the brand wants to own; the piece's existence is strategically warranted. +- A path to recovery exists: refresh of the right depth has a reasonable chance of producing improvement. +- No sister piece is competing for the same query in a way that splits authority. +- The piece's URL has accumulated authority worth preserving. + +**When refresh fits but might not.** + +- Sometimes a refresh-eligible piece is also a merge candidate. A high-value-decaying piece that is decaying because a sister piece is stronger may produce more value through merge than through refresh of either piece alone. +- Sometimes refresh has been tried and did not produce recovery. The first failed refresh shifts disposition consideration toward merge or full-rewrite-with-new-positioning rather than another refresh attempt. + +**Refresh failure modes.** + +- Refreshing pieces that are not recoverable. The topic is dying; the brand cannot win against the competition; the SERP intent has shifted to a format the brand does not produce. Refresh in these cases is theater. +- Refreshing without resolving the underlying issue. If a piece is decaying because a sister piece is competing for the same query, refresh of the original piece does not solve the cannibalization. Both pieces continue to underperform. + +--- + +## Merge + +Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +**Criteria for merge disposition.** + +- Two or more pieces target the same primary query or a closely overlapping query cluster. +- Combined authority across the pieces is meaningful; merging would produce a piece with stronger authority than any individual piece has. +- The pieces' coverage overlaps enough that consolidation produces a coherent piece, not a Frankenstein of mismatched sections. +- The team can identify which URL the survivor occupies (typically the one with strongest existing authority) and which URLs redirect to the survivor. + +**The merge decision in detail.** + +- **Identify the survivor URL.** Usually the URL with strongest existing rankings, traffic, and backlinks. The survivor inherits the consolidated content; other URLs redirect to it. +- **Plan the consolidated content.** Outline the merged piece. Decide which sections come from which source piece. Plan the gaps where new content will fill what neither piece had. +- **Author the consolidated piece.** Write or rewrite as needed. The consolidated piece is usually stronger than any of the source pieces because it is built from the strongest components plus targeted new content. +- **Implement redirects.** 301 redirects from the merged URLs to the survivor. Redirects need to be implemented at publish time, not after; the merged URLs going to 404 or 410 produces traffic loss that did not need to happen. +- **Update internal links.** Pieces that linked to the merged URLs should be updated to link to the survivor. + +**Merge failure modes.** + +- Merging without redirects. The merged URLs go to 404; the consolidated authority does not transfer; traffic is lost. +- Merging pieces that did not actually compete. If two pieces target different intents, merging them produces a piece that does neither well. +- Frankenstein merges. The consolidated piece reads as multiple pieces stitched together rather than as a unified piece. Cure: rewrite the consolidated piece as a piece in its own right, using the source pieces as input rather than as components. + +--- + +## Delete + +The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. + +**Criteria for delete disposition.** + +- The piece draws minimal traffic and has minimal residual authority. +- The topic is not load-bearing for the program; the brand does not need to own it. +- No merge candidate exists; the piece's content does not consolidate cleanly into any stronger piece. +- Maintaining the piece costs ongoing audit attention without proportional return. + +**The delete decision in detail.** + +- **Identify the redirect target.** The deleted URL should redirect to the closest sibling piece, or to the relevant hub or category page, or to the homepage if no other target fits. Deleting without redirect (returning 404 or 410) is correct only when the piece's residual authority is genuinely zero, which is rare. +- **Implement the redirect.** 301 redirect to the chosen target. +- **Update internal links.** Pieces that linked to the deleted URL should be updated to link to the redirect target directly. The redirect chain still works but direct links are cleaner. +- **Document the deletion.** The audit log should capture the delete decision, the rationale, and the redirect target. Future audits can reference the log if a question arises about the URL. + +**Delete failure modes.** + +- Avoiding delete because deleting feels destructive. The library accumulates low-value pieces forever, costing ongoing audit attention and diluting overall library quality. +- Delete without redirect. The URL returns 404; whatever residual authority existed is lost; users who linked to the URL or bookmarked it find a dead link. +- Delete of pieces that should have been merged. The piece's content had value the team did not recognize; merging would have preserved it. Delete is appropriate when no merge candidate exists, not as the easy path to avoid the merge analysis. + +--- + +## The disposition decision flow + +A short framework for choosing. + +1. **Does the piece have demonstrated demand?** Traffic, rankings, conversions, or strategic role. If yes, continue. If no, the disposition is likely delete (or merge if there is a candidate). +2. **Is there a sibling piece competing for the same query?** If yes, evaluate merge. The merged piece has a strong chance of outperforming both original pieces. +3. **Is the topic load-bearing for the brand?** If no, refresh disposition is unlikely to be the right answer; consider merge into a stronger sibling or delete. +4. **Has refresh been tried recently without recovery?** If yes, the next disposition should be merge or full-rewrite-with-new-positioning, not another refresh attempt. +5. **What is the cheapest disposition that addresses the actual problem?** Refresh is often defaulted to because it feels less destructive; merge and delete are sometimes the cheaper paths to the actual outcome. + +--- + +## The under-recognized failure: refreshing what should have been merged or deleted + +The pattern that costs refresh programs the most capacity. + +**How it shows up.** The team spends 4 hours refreshing a low-value-decaying piece that even at its best will not draw meaningful traffic. The refresh ships. The piece ranks slightly better for two weeks, then drifts back down. Three months later the piece is in the same audit queue. + +**Why it happens.** + +- Refresh feels less destructive than merge or delete. +- The merge analysis takes time; refresh feels like the immediate action. +- Delete requires team agreement; refresh can be done by a single owner. +- The team has not internalized that some pieces should not be refreshed. + +**The cure.** Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. The audit is not "which pieces to refresh"; it is "what disposition each piece should get." Refresh becomes one option among several rather than the default. + +**The capacity recovery.** Programs that adopt the merge-and-delete-as-first-class-dispositions discipline typically recover 20-40% of refresh capacity for higher-value work. The pieces that were getting refreshed but should have been merged or deleted stop consuming capacity; the freed capacity goes to high-value-decaying pieces that produce real recovery. + +--- + +## Disposition decisions that need approval + +Some dispositions are higher-risk than others and warrant approval beyond the audit owner. + +**Delete dispositions.** Always need approval. Deletes are essentially irreversible without significant work to undelete; the redirect strategy is consequential; the team should be aligned on the decision. + +**Merge dispositions involving high-value pieces.** Need approval. Merging into a survivor URL means the non-survivor URLs lose their identity. If the non-survivor pieces had high-value characteristics, the merge needs review. + +**Refresh dispositions on stable high-value pieces.** Need approval. Touching a stable high-value piece is a high-risk operation; the audit owner should not unilaterally decide to refresh. + +**Light edit and substantial revision on decaying pieces.** Usually do not need approval beyond the audit owner. The risk-reward is straightforward. + +--- + +## Methodology-level choices that stay in the public skill + +The three dispositions and their criteria, the disposition decision flow, the under-recognized failure of refreshing what should have been merged or deleted, the merge and delete mechanics, the dispositions that need approval. + +## Implementation choices that stay internal + +Specific redirect implementation in the team's CMS or hosting layer. Specific internal-link update automation that catches links to merged or deleted URLs. Specific approval workflows for high-risk dispositions. Specific audit-log templates that capture disposition rationale. These vary by team, tooling, and CMS. diff --git a/skills/content-repurposing/SKILL.md b/skills/content-repurposing/SKILL.md new file mode 100644 index 0000000..be7ced8 --- /dev/null +++ b/skills/content-repurposing/SKILL.md @@ -0,0 +1,298 @@ +--- +name: content-repurposing +description: "Cross-format content adaptation. Turning one substantial piece into many derivative formats (blog series, email sequences, social posts, webinars, podcasts, video shorts) without losing the original's value or producing AI-slop variants. The discipline of adaptation per medium rather than mass-blast distribution. Triggers on content repurposing, content adaptation, cross-format content, content atomization, content multiplication, content distribution across formats, source-piece-to-derivative, video shorts from blog, email from whitepaper, podcast from article, blog series from research. Also triggers when a flagship piece is shipping but the team has not planned how to extend it across formats, when repurposing is happening but the derivatives feel mass-produced, or when AI-assisted repurposing is producing slop variants of strong source pieces." +category: content +catalog_summary: "Cross-format content adaptation: one piece becomes many (blog series, email, social, webinar, podcast, video) with per-format adaptation rather than mass-blast that ignores medium constraints" +display_order: 11 +--- + +# Content Repurposing + +A senior editorial leader's playbook for cross-format content adaptation. The discipline of turning one substantial piece into many derivative formats without losing the original's value or producing slop variants. + +Most content programs underspend on repurposing. A flagship piece costs 40-80 hours to produce; the program publishes it once, shares it on three channels, and moves on. The same piece could have produced a blog series, an email sequence, a webinar, a podcast episode, a dozen social posts, video shorts, and FAQ extractions for AI search visibility. The work to extend the source piece across formats is small relative to the value extracted; programs that skip repurposing leave most of the value unrealized. + +The failure mode in the other direction is mass-blast: the same content reposted across channels without adaptation. A blog post pasted into LinkedIn as a long-text post; the email newsletter is the blog's first three paragraphs with "read more" tacked on; the YouTube video is a slideshow of the article text read aloud. Mass-blast respects neither the medium nor the audience. AI-assisted repurposing has made mass-blast cheap; the result is a wave of derivative content that performs poorly across every channel because it was adapted to none of them. + +This skill is the discipline of adaptation per medium. Each format has constraints, conventions, and reader expectations the source piece does not have. Repurposing that respects those constraints produces work that earns engagement on the new format; repurposing that ignores them produces filler. + +When to use this skill: planning the extension of a flagship piece across formats, auditing a repurposing pipeline that is producing low-engagement derivatives, calibrating an AI-assisted repurposing workflow that is producing slop, or designing the cross-format adaptation conventions for a content program. + +--- + +## What this skill is for + +This skill spans cross-format adaptation work after a source piece has been produced. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes the original piece in any single format. +- **`content-repurposing` (this skill)** turns one piece INTO many formats. +- `content-distribution` gets content TO audiences via channels. +- `editorial-qa` verifies pre-publish, including derivatives. +- `ai-content-collaboration` is the workflow layer; AI participation rules apply within repurposing. + +The distinction from `content-distribution` is load-bearing. Distribution is channel work: getting content to audiences via the right channels. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running multi-format programs, agencies producing derivative content for clients, anyone planning to extend a flagship piece across formats. + +What is not in scope: the original piece's production (covered by `content-and-copy` and the long-form skills), the channels themselves (covered by `content-distribution`), the editorial QA on derivatives (covered by `editorial-qa`). + +--- + +## One-and-done vs mass-blast vs adapt-by-format + +The keystone framing. + +**One-and-done.** Publish once on the source format; never reuse. The piece took 60 hours to produce; it generates traffic for 90 days; it gets shared three times; it goes silent. The team treats publication as the end of the piece's life. Output: most of the source piece's value goes unrealized; the team is always producing new flagship work because old flagship work is not being extended. + +**Mass-blast.** Same content reposted across channels without adaptation. Blog post text pasted into LinkedIn as a long post. Email newsletter is the blog's first three paragraphs. The YouTube version is a slideshow of the text read by AI voice. Output: low engagement on every channel because nothing was adapted to any channel's conventions. Audiences perceive the cross-channel sameness as low-effort filler. AI-assisted repurposing has made this pattern cheap and common. + +**Adapt-by-format.** Per-medium adaptation that respects each format's constraints and conventions. The blog series breaks the source piece into chapters with new ledes and closings per chapter. The email sequence builds on the source's framework with sender-voice adjustments. Social posts use platform-native conventions. The webinar adds Q&A and live elements. Output: each derivative earns engagement on its medium because it was made for that medium; the source piece's value compounds across formats. + +The litmus test. Read each derivative as if you had not seen the source piece. Does it stand on its own? Does it use the medium's conventions? Would it earn engagement if it were the only thing the audience saw of this work? If yes to all three, the adaptation succeeded. If the derivative reads as "I should have read the original instead," the adaptation failed. + +--- + +## Source-piece selection + +Not every piece is worth repurposing. Selection is the first discipline. + +**Strong source-piece characteristics.** + +- The source has a clear central argument or framework that travels across formats. +- The source has standalone sections, examples, or sub-arguments that work as derivative pieces. +- The source's audience overlaps with the audiences on the target formats. +- The source's voice is distinctive enough that derivative voice can stay coherent. +- The source has accumulated demand: traffic, links, mentions, social shares. + +**Weak source-piece characteristics.** + +- The source is a tightly-integrated argument where every section depends on context. +- The source is a list-style piece where the items do not have standalone weight. +- The source's value depended on being read end-to-end (a narrative arc, a layered argument with payoff). +- The source's audience does not exist on most target formats. +- The source's voice is generic; derivative voice has nothing to anchor. + +**The selection audit.** Run candidate pieces through these questions before committing to repurposing. Pieces that fail the audit may still be valuable but as one-and-done; programs that try to repurpose unsuitable pieces produce derivatives that feel forced. + +Detail in [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md). + +--- + +## Format adaptation patterns + +Eight common source-to-derivative adaptations with worked examples. + +**Long-form to blog series.** A 6,000-word whitepaper becomes 4-6 standalone blog posts, each developing one of the whitepaper's sub-arguments with new ledes and closings. + +**Blog post to email sequence.** A 1,500-word blog post on a multi-step framework becomes a 5-email sequence, one email per step, with sender-voice adaptation and per-email engagement hooks. + +**Whitepaper to webinar.** Substantive whitepaper becomes a 30-45 minute webinar with the whitepaper's framework as the spine, plus live Q&A, plus interactive elements that print do not support. + +**Long-form to social posts.** Pull-quote-style posts, framework summaries, key-question posts, contrarian-claim posts. Each social post is one moment from the source, framed for the platform's conventions. + +**Article to podcast episode.** Article becomes the episode's spine; the host adds context, examples, and conversational elaboration; sometimes a guest interview drives the episode while the article is the show notes. + +**Long-form to video shorts.** 60-90 second video clips on individual claims, examples, or framework elements from the source. Each short is a standalone unit; series-of-shorts can extend the source over weeks of social posting. + +**Research report to FAQ extractions.** Specific Q&A extractions from the source piece, formatted for AI search citation and snippet capture. + +**Multi-piece source to ebook.** Several related pieces (blog posts, articles, even social threads) consolidated into an ebook, with new connective tissue, an introduction that frames the body, and a conclusion that synthesizes. + +Detail in [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md). + +--- + +## Per-format constraints + +Each medium demands and forbids specific things. Repurposing that ignores the constraints produces derivatives that fail the medium. + +**Email.** + +- Subject line and preheader bear most of the engagement load. +- Plain prose paragraphs work; complex formatting often breaks across email clients. +- Length tolerance varies by audience; 200-800 words common. +- Single clear CTA per email; multiple competing CTAs underperform. + +**Social posts (text-driven platforms).** + +- Hook in the first 1-2 lines; readers decide to expand or scroll. +- Platform-specific conventions (LinkedIn long-post structure differs from X/Twitter thread structure). +- Visual or quote-graphic options to break up text. +- One specific point per post; multi-point posts dilute. + +**Video (long-form).** + +- Pacing differs from print; spoken delivery requires different sentence structure. +- Visuals carry information print does not need; talking-head video alone for 30+ minutes underperforms. +- Audio quality matters more than video quality up to a point; bad audio kills retention. + +**Video (short-form).** + +- 60-90 second window for most platforms; 15-30 seconds for some. +- Captions essential; many viewers watch without sound. +- Hook in the first 1-2 seconds; algorithmic recommendation rewards retention from second 1. +- One specific point or moment per short. + +**Podcast.** + +- Spoken-language sentence structure; print-style sentences read aloud sound stilted. +- Conversational pacing rewards examples and asides; tightly-argued print sections feel stiff. +- Show notes do the print work the audio cannot; treat show notes as a derivative format too. + +**Webinar.** + +- Live element: Q&A, polls, interactive moments. Static webinar is a video; interactive webinar earns the format. +- Slide design matters; text-heavy slides fail. +- Length: 30-60 minutes typical; longer requires high engagement design. + +Detail in [`references/per-format-constraints.md`](references/per-format-constraints.md). + +--- + +## Voice consistency across formats + +The source piece's voice anchors the derivatives. The discipline is staying recognizable through the format shifts. + +**What stays constant.** + +- The brand's POV on the topic. +- Distinctive vocabulary, specific framings, recognizable phrasings. +- The level of conviction or hedging the brand uses. +- The audience-respect register (talking up to, down to, alongside the audience). + +**What adapts per format.** + +- Sentence length and structure (spoken voice differs from written). +- Density (visual formats can carry less per minute than text). +- Conversational vs declarative register (podcasts are conversational; whitepapers declarative). +- Direct-address frequency ("you" usage varies by format). + +**The voice audit per derivative.** Read or watch the derivative. Does it sound like the brand? Could a reader who knows the source piece tell the derivative is from the same source? If voice has drifted to AI-default or to the platform's default register, the adaptation lost the voice. + +**The AI-repurposing voice problem.** AI-assisted repurposing is particularly prone to voice drift. The source piece may have specific voice characteristics; AI generation of derivatives without strong voice prompts produces derivatives that sound more generic than the source. See `ai-content-collaboration` for the voice-preservation discipline that applies to repurposing workflows. + +Detail in [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md). + +--- + +## Sequencing and cadence + +When to release derivatives relative to the source, and at what pace. + +**Sequencing patterns.** + +- **Source-first, derivatives following.** Source publishes; derivatives roll out over the following 2-12 weeks. The source carries authority; derivatives extend reach. +- **Derivatives-first, source as anchor.** Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship. Less common; works for built-up audiences who follow the program. +- **Simultaneous launch.** Source and a wave of derivatives publish on the same day. Maximum splash; risks audience fatigue if every channel is firing the same day. + +**Cadence within the rollout.** + +- **Concentrated.** Most derivatives ship within 4-6 weeks of source. Maximum momentum from the source's authority; minimum time for individual derivatives to land. +- **Distributed.** Derivatives ship over 3-6 months. Each derivative has space to land; the program is extracting value over a longer window; risks losing connection to source if the gap grows too long. +- **Indefinite.** Derivatives keep being created from the source as long as the source remains relevant. Common for evergreen flagship pieces; rare otherwise. + +**The pacing audit.** Match cadence to the source's traffic curve. Pieces with sharp early traffic (trending topics) benefit from concentrated rollout; pieces with sustained evergreen traffic can support distributed rollout over many months. + +Detail in [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md). + +--- + +## Cross-promotion across derivatives + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. + +**Linking patterns.** + +- **Derivative back to source.** Each derivative includes a link or reference to the source piece for readers who want depth. The source's traffic compounds. +- **Source forward to derivatives.** The source piece is updated to include links to derivatives as they ship. The source becomes the hub for the cross-format extension. +- **Derivatives across.** Where appropriate, derivatives link to other derivatives in the cross-format set. The series feeling helps audiences engage with multiple pieces. + +**Attribution within derivatives.** When a derivative is clearly drawn from a source piece, acknowledge: "This is adapted from our recent piece on X." Attribution earns reader trust; uncredited derivatives can feel like the same work being recycled without acknowledgment. + +**Co-promotion across channels.** A blog post derivative can be re-shared on social where the original blog post was; a social post derivative can be promoted in the email newsletter. Cross-channel flow extends each derivative's reach. + +Detail in [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md). + +--- + +## Repurposing for AI search visibility + +A specific repurposing pattern worth its own treatment. + +**FAQ extraction.** Pull specific question-answer pairs from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries that can be cited by AI search engines. + +**Snippet design.** Identify standalone paragraphs in the source that answer specific queries cleanly. These paragraphs can be quoted, schema-marked, and presented in derivative pieces or in dedicated FAQ pages. + +**Statistic extractions.** AI engines weight statistics with named sources. Extract specific stats from the source (with citations to the underlying primary research) into format that AI can cite cleanly. + +**Definition and entity extractions.** Source pieces often define specific terms or describe specific entities authoritatively. Extract these as standalone definitions in glossaries, FAQ pages, or knowledge-base entries. + +**The AI-search-derivative discipline.** Treat AI-search optimization as a derivative format with its own conventions: specific question framings, named-source citations, standalone-paragraph design. Pieces that do this well earn AI citations; pieces that do not still get cited but at lower rates and with less control over framing. + +Detail in [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md). + +- "Our derivatives feel like AI slop." Mass-blast pattern; AI-assisted repurposing without per-format adaptation. Cure: add adaptation discipline, voice prompts, per-format review. +- "We repurposed but engagement is low." Format constraints ignored. Cure: audit each derivative against per-format conventions. +- "The blog post derivative outperforms the source." Either the source was the wrong format for the topic (the derivative format fits better), or the derivative cannibalizes the source. Investigate. +- "We never reuse pieces." One-and-done pattern; the program is leaving 70-90% of source-piece value unrealized. +- "Our LinkedIn posts are blog-post text dumps." Mass-blast on a platform with specific conventions. Cure: rewrite for platform-native structure. +- "The email newsletter is the blog's first paragraphs with 'read more' tacked on." Mass-blast email pattern. Cure: rewrite as a standalone email with engagement hooks. +- "Our podcast episodes are articles read aloud." Print-to-audio without spoken-language adaptation. Cure: rewrite for spoken delivery; add conversational pacing. +- "We extracted FAQ pages but they are not getting cited by AI search." Format may be wrong (snippets not standalone) or content may not be authoritative enough; audit against AI-search norms. +- "Our voice drifts across derivatives." AI-repurposing voice failure. Cure: stronger voice prompts; per-derivative voice audit. +- "We launched 12 derivatives in a week and audiences were exhausted." Concentrated cadence too aggressive. Cure: distributed cadence with engagement-driven sequencing. +- "Our derivatives compete with the source for the same query." Cannibalization. Cure: clear primary-keyword assignment per piece; consolidate or restructure. + +--- + +## The framework: 12 considerations for content repurposing + +When designing or auditing a repurposing program, walk these 12 considerations. + +1. **Adapt-by-format, not mass-blast or one-and-done.** Each derivative respects its medium. +2. **Source-piece selection.** Strong sources have travelable arguments and standalone sections. +3. **Format adaptation patterns chosen.** Match source-piece characteristics to derivative formats. +4. **Per-format constraints respected.** Each medium's conventions, length norms, and reader expectations. +5. **Voice consistency across formats.** Brand POV stays; sentence structure adapts. +6. **Sequencing and cadence planned.** Source-first vs simultaneous; concentrated vs distributed. +7. **Cross-promotion across derivatives.** Linking, attribution, co-promotion. +8. **AI-search extraction.** FAQ, snippet, statistic, entity extractions designed deliberately. +9. **Cannibalization avoided.** Derivatives complement the source; do not compete for the same query. +10. **Engagement-per-format measured.** Derivatives evaluated on each medium's metrics. +11. **AI-assisted repurposing with voice discipline.** Voice prompts, per-derivative review, slop prevention. +12. **Capacity allocation explicit.** Repurposing is real work; budgeted, not done in the cracks. + +The output of the framework is a repurposing program that turns each strong source piece into a coherent multi-format extension, with each derivative earning engagement on its medium. + +--- + +## Reference files + +- [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md) - Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. +- [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md) - Eight source-to-derivative adaptations with worked examples. Long-form to blog series, blog to email, whitepaper to webinar, etc. +- [`references/per-format-constraints.md`](references/per-format-constraints.md) - What each medium demands and forbids. Email, social, video, podcast, webinar, AI search. Length norms, conventions, hooks. +- [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md) - What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem. +- [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md) - Source-first vs simultaneous vs derivative-first. Concentrated vs distributed cadence. Pacing audits. +- [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md) - Linking patterns, attribution, co-promotion across channels. +- [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md) - FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. +- [`references/repurposing-pipeline-templates.md`](references/repurposing-pipeline-templates.md) - Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. +- [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: adaptation is craft, not duplication + +Repurposing is widely treated as a content multiplication problem to be solved with AI: feed the source into a tool, get derivatives out. The output of that approach is mass-blast, slop, and audiences that learn to ignore the program. The teams producing repurposing that earns engagement are the ones treating each derivative as a piece in its own right, adapted for its medium, written with the source's voice but the format's craft. + +Adaptation is craft, not duplication. The source piece is the starting material; the derivative is its own work. Programs that hold this discipline get value compounding across formats; programs that skip it produce a wall of derivative content that performs worse, not better, than publishing only the source. + +When in doubt about whether a repurposing program is ready, ask: does each derivative respect its medium's conventions, does voice stay consistent across the set, are derivatives cross-promoting and linking back to the source, is AI-search extraction part of the plan, is cannibalization being managed, is the cadence pacing earning engagement? If yes to all of those, the program is real. If no to any, the gap is where the derivatives will read as filler and audiences will tune out. diff --git a/skills/content-repurposing/references/aeo-extraction-patterns.md b/skills/content-repurposing/references/aeo-extraction-patterns.md new file mode 100644 index 0000000..3ec2330 --- /dev/null +++ b/skills/content-repurposing/references/aeo-extraction-patterns.md @@ -0,0 +1,205 @@ +# AEO extraction patterns + +FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. The repurposing pattern that turns long-form content into AI-search-ready derivatives. + +AI search engines (the citation-driven generative answer engines) cite content in specific shapes. Pieces that are designed for citation get cited at higher rates and with better framing control; pieces that are not designed for citation still get cited but at lower rates and with less control over how the citation appears. + +The AEO (answer engine optimization) extraction is its own derivative format with its own conventions. Treating it as a derivative is the discipline. + +--- + +## The AEO extraction frame + +AI engines retrieve and cite content paragraph-by-paragraph or snippet-by-snippet. They favor content that: + +- Has standalone meaning (the snippet works without surrounding context). +- Cites named sources within the snippet (specific authority). +- Uses specific phrasings (queryable framings). +- Has structural signals (FAQ schema, headings, lists where appropriate). + +Source pieces written without these properties may have the same content but in shapes the engines do not cite cleanly. AEO extraction restructures the content into citation-ready shape. + +--- + +## Pattern 1: FAQ extraction + +The most common AEO extraction pattern. + +**The shape.** Specific question-answer pairs derived from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries. + +**Question framing.** + +- Use phrasings users actually search. "What is X?" "How does X work?" "Why does X matter?" "When should I use X?" +- Avoid phrasings users do not search. "What are the considerations around X?" rarely matches search intent. +- Specific is better than generic. "How long should a B2B sales email be?" performs better than "What length should sales emails be?" + +**Answer framing.** + +- Standalone meaning. The answer works as a paragraph; no pronoun references that depend on outside context. +- Named source within the answer where applicable. "According to a 2025 Forrester study, B2B sales emails between 75 and 150 words have the highest reply rates" performs better than "Studies show shorter emails work better." +- Specific framings, not hedged. "The strongest length is 75-150 words" performs better than "Generally, shorter tends to be better." +- Length: 40-80 words typical. Longer answers get truncated or cited partially; shorter answers may not have enough substance to cite. + +**Where the FAQ lives.** + +- A dedicated FAQ section at the bottom of the source piece, schema-marked with FAQPage. +- A standalone FAQ page that aggregates multiple FAQs across topics, deeply linked to source pieces. +- Inline within the source piece as a callout box, surfacing the Q&A while the surrounding prose develops the topic. + +--- + +## Pattern 2: Snippet design + +Standalone paragraphs in the source piece designed to be citation-ready. + +**The shape.** A paragraph (100-200 words typical) that answers a specific query cleanly and can be cited as a unit. + +**Snippet framing.** + +- Opens with a specific claim or definition. Snippets that open with throat-clearing rarely get cited cleanly. +- Includes named source citations where the claims need authority. +- Uses specific framings. "B2B sales emails between 75 and 150 words have a 32% reply rate, compared to 18% for emails over 250 words" is citation-ready; "shorter emails tend to do better" is not. +- Stands alone. The paragraph's meaning does not depend on the prior or following paragraphs. + +**Where snippets live.** + +- Throughout the source piece as load-bearing paragraphs that incidentally meet snippet criteria. +- As deliberately-designed snippets in specific positions (often after each H2 question for AEO-optimized pieces; see `editorial-qa`'s SEO/AEO compliance for the answer-paragraph discipline). +- As standalone snippets in derivative pieces (FAQ pages, glossaries, knowledge-base entries). + +--- + +## Pattern 3: Statistic extractions + +AI engines weight statistics with named sources at high citation rates. + +**The shape.** Specific statistic with named source, framed for citation. + +**Statistic framing.** + +- The number is specific. "32% of B2B buyers" performs better than "around a third of buyers." +- The source is named. "According to the 2025 Salesforce State of Marketing report" performs better than "according to a recent study." +- The context is clear. "Among B2B SaaS buyers in the $50M-500M revenue band" rather than just "among buyers." +- The currency is specified. The stat's date matters for AI engines deciding which sources to cite as current. + +**Where statistic extractions live.** + +- Throughout the source piece where data supports claims. +- In dedicated "key statistics" callouts that schema-mark the stats. +- As standalone tweet-graphic-style social derivatives (the stat on its own with the source citation). +- In FAQ-style answers that frame "what does the data say about X?" + +**The citation-laundering avoidance.** Statistic extractions that cite secondary sources (other content marketing pieces) rather than primary sources reduce citation rates. AI engines increasingly detect citation laundering and discount it. + +--- + +## Pattern 4: Definition and entity extractions + +Source pieces often define specific terms or describe specific entities authoritatively. + +**The shape.** Standalone definitions or entity descriptions that can serve as canonical references. + +**Definition framing.** + +- "X is [definition], typically [characterization], distinguished from [related concept] by [distinction]." +- 50-150 words for substantive definitions. +- Specific authority signals: who developed the concept, when, in what context. + +**Entity framing.** + +- For products, companies, frameworks: who, what, when, why, where used. +- Specific dates, named people, named organizations. +- Source attribution where the entity claim depends on authority. + +**Where definition and entity extractions live.** + +- Glossary pages. Many programs underuse glossaries; they are AI-search valuable real estate. +- Knowledge-base entries. +- Schema-marked definitions within source pieces (Article schema with appropriate sub-types). +- Wikipedia and similar entity authorities where the entity is significant enough to warrant external listings (different from on-property AEO but related; AI engines weight cross-source consistency). + +--- + +## Pattern 5: Comparison extractions + +Source pieces that compare options, frameworks, or approaches produce comparison-extraction derivatives. + +**The shape.** Side-by-side or table comparisons with specific axes, citation-ready. + +**Comparison framing.** + +- Defined axes (price, feature set, fit, scale). +- Specific values per axis per option. +- Tradeoff summary that AI can quote. +- Recommendation framing where the source piece commits a position. + +**Where comparison extractions live.** + +- Tables within the source piece, schema-marked where appropriate. +- Standalone comparison pages. +- FAQ-style answers framing "How does X compare to Y?" +- Decision-guide derivatives that walk readers through the comparison. + +--- + +## Pattern 6: How-to extractions + +Source pieces with sequential instructions produce how-to extractions. + +**The shape.** Step-by-step instructions that AI can cite as a procedure. + +**How-to framing.** + +- Numbered steps in a clear sequence. +- Each step is a complete instruction (not "do this, then that" run together). +- Schema-marked with HowTo where the source is an instructional piece. + +**Where how-to extractions live.** + +- Within source pieces as schema-marked procedures. +- Standalone how-to pages on specific tasks. +- Tutorial derivatives in video format. + +--- + +## AEO extraction failures + +**Generic FAQs.** Questions that do not match user search phrasings get little citation. Cure: query research; phrase questions in user voice. + +**Context-dependent answers.** Answers that reference "this approach" or "the method described above" do not cite cleanly. Cure: each answer is rewritten to stand alone with full context. + +**Hedged answers.** "Generally, in some cases, depending on context, X might work" rarely gets cited. AI engines prefer specific framings. Cure: where the source piece is genuinely uncertain, scope the answer to the specific case where the answer is specific. + +**Missing schema.** FAQs and snippets without schema markup do not signal cleanly to engines. Cure: add appropriate schema (FAQPage, HowTo, Article) where formats fit. + +**No source citations within answers.** Statistics and specific claims without named sources within the answer paragraph get cited at lower rates. Cure: include source citations within the answer body, not just in surrounding context. + +**Citation laundering.** FAQs citing other content marketing pieces rather than primary sources. Cure: trace claims to primary sources; cite the primary. + +**Over-extraction.** Producing 50 FAQs from a 5,000-word source piece dilutes; not every question deserves a standalone FAQ. Cure: extract the 10-15 highest-value questions; let the rest live within the source's prose. + +--- + +## AEO extraction integration with the cross-format set + +AEO extractions integrate with other derivatives. + +**FAQ pages link to the source.** The FAQ page is a derivative; the source piece is the canonical version. Cross-promotion follows the standard pattern. + +**Statistic extractions appear in social posts.** Each stat with its source citation can become a social post (often with quote-graphic visual treatment). + +**Definition extractions appear in glossaries that the source piece links to.** The glossary entry serves as the canonical definition for the term across the program. + +**Comparison extractions appear in decision-guide derivatives.** The comparison from the source becomes the spine of a separate decision-guide piece. + +**The integration discipline.** AEO extraction is one derivative type among several; the cross-format set's coordination includes the AEO extractions, not as a separate workflow but as part of the rollout plan. + +--- + +## Methodology-level choices that stay in the public skill + +The six AEO extraction patterns, the question/answer/snippet framing principles, the schema markup integration, the AEO extraction failures, the integration with the broader cross-format set. + +## Implementation choices that stay internal + +Specific schema markup automation. Specific FAQ-page templates in the team's CMS. Specific glossary-page architecture. Specific statistic-extraction tooling. Specific monitoring of AI citation rates per piece. The team's own conventions for FAQ length within the bands. These vary by team, CMS, and AI-citation tracking infrastructure. diff --git a/skills/content-repurposing/references/common-repurposing-failures.md b/skills/content-repurposing/references/common-repurposing-failures.md new file mode 100644 index 0000000..63412eb --- /dev/null +++ b/skills/content-repurposing/references/common-repurposing-failures.md @@ -0,0 +1,175 @@ +# Common repurposing failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most repurposing failures share a single root, which is treating repurposing as content multiplication rather than as cross-format craft. + +--- + +## Failure 1: Mass-blast (same content reposted across channels) + +**Symptom.** Blog post text pasted into LinkedIn as a long post. Email is the blog's first three paragraphs with "read more." YouTube version is a slideshow of the article text read aloud. + +**Diagnosis.** Repurposing without per-format adaptation. The team is treating "more channels" as the goal rather than treating each derivative as a piece adapted for its medium. + +**Cure.** Apply the per-format constraints discipline (see `per-format-constraints.md`). Each derivative gets rewritten for the target format. AI-assisted repurposing without strong format prompts produces this failure; the cure includes voice prompts and per-format instructions. + +--- + +## Failure 2: AI-slop derivatives + +**Symptom.** Derivatives feel like AI slop. Generic, derivative, signal-less. Voice has drifted from the source. + +**Diagnosis.** AI-assisted repurposing without voice discipline. AI generation regresses to model defaults; multiple derivatives generated without voice anchor compound the drift. + +**Cure.** Apply the voice-consistency-across-formats discipline (see `voice-consistency-across-formats.md`). Voice prompts including sample text from the source. Per-derivative voice review. Reject the bland; rewrite generic sentences in voice. See also `ai-content-collaboration` for the broader voice-preservation discipline. + +--- + +## Failure 3: One-and-done + +**Symptom.** Source pieces publish; never get repurposed. The team produces new flagship work continuously while older flagship work sits unused. + +**Diagnosis.** No repurposing discipline; the team treats publication as the end of the piece's life. Most of the source-piece value goes unrealized. + +**Cure.** Establish source-piece tiering (see `source-piece-selection-criteria.md`). Tier 1 and Tier 2 pieces get cross-format extension plans at production time. Capacity allocation for repurposing becomes a real budget line. + +--- + +## Failure 4: Repurposing the wrong pieces + +**Symptom.** Repurposing capacity goes to pieces that resist extension. The derivatives feel forced; engagement is low. + +**Diagnosis.** Source-piece selection is choosing pieces by availability rather than by suitability. Pieces with tightly-integrated arguments, list-style structure, or no demand signal are being repurposed when they should stay one-and-done. + +**Cure.** Apply the selection audit. Run candidates through the strong vs weak source-piece characteristics. Some pieces stay one-and-done; that is the right disposition for them. + +--- + +## Failure 5: Format constraints ignored + +**Symptom.** Derivatives feel awkward on their target formats. Engagement is low. Audiences scroll past or unsubscribe. + +**Diagnosis.** Each medium has constraints; the derivatives violate them. LinkedIn long posts as walls of text; emails as image-only layouts; podcasts as articles read aloud. + +**Cure.** Apply the per-format constraints discipline. Each format has demand-and-forbid lists. Derivatives must respect them, even at cost of departing from the source's surface. + +--- + +## Failure 6: Derivative outperforms source (cannibalization) + +**Symptom.** A blog-post derivative outperforms the source whitepaper for the source's target keyword. Authority is splitting between the two pieces. + +**Diagnosis.** Either the source was the wrong format for the topic (the derivative format fits SERP intent better), or the derivative is targeting the same keyword as the source and cannibalizing. + +**Cure.** Two options. If the source was the wrong format, consider whether the derivative should become the canonical piece (with the source decommissioned or repositioned). If the derivative is cannibalizing, reassign primary keywords: the source keeps the high-value head term; the derivative gets a long-tail variant. + +--- + +## Failure 7: Voice drift across the cross-format set + +**Symptom.** Each derivative is fine alone but the cross-format set reads as voice variants. Audiences who follow the program notice the inconsistency. + +**Diagnosis.** Multiple writers or AI generators produced derivatives without voice coordination. Voice drifted across producers. + +**Cure.** Single voice owner across the cross-format set. Voice library with examples. Calibration sessions where multiple writers reconcile voice expectations. AI tools include the same voice prompts across all derivative generations. + +--- + +## Failure 8: Cadence too aggressive + +**Symptom.** Cross-format set ships a wave of 12 derivatives in one week. Audiences disengage by day 3. Most derivatives produce minimal engagement. + +**Diagnosis.** Concentrated cadence too tight for the audience attention rhythm. The cross-format presence on a single week exhausts rather than reinforces. + +**Cure.** Apply the sequencing-and-cadence discipline. Match cadence to source's traffic curve and audience attention norms. Most cross-format sets benefit from concentrated-but-not-collapsed pacing (4-6 weeks rather than 1 week). + +--- + +## Failure 9: No cross-promotion + +**Symptom.** Derivatives ship in isolation. No links to source. No links between derivatives. No mention of the cross-format set on the channels where audiences could discover it. + +**Diagnosis.** Cross-promotion was treated as optional or as an afterthought. The compounding effects of cross-linking and co-promotion are missing. + +**Cure.** Apply the cross-promotion discipline (see `cross-promotion-patterns.md`). Every derivative includes a derivative-to-source link. The source piece is updated to reference derivatives. Co-promotion across channels is planned at rollout time. + +--- + +## Failure 10: AEO extraction skipped or generic + +**Symptom.** The cross-format set ships without FAQ extractions or with generic FAQ extractions. AI-search citation rates are low. + +**Diagnosis.** AEO extraction was not part of the plan, or the FAQ questions do not match user search phrasings, or the answers are context-dependent rather than standalone. + +**Cure.** Apply the AEO extraction patterns. Treat FAQ extraction, snippet design, and statistic extractions as derivative formats with their own conventions. Schema-mark where appropriate. + +--- + +## Failure 11: No source-piece updating after rollout + +**Symptom.** The source piece publishes; derivatives ship; the source piece is never updated to reference the derivatives. The source remains static. + +**Diagnosis.** The forward-promotion from source to derivatives was skipped. The source's role as cross-format hub is wasted. + +**Cure.** Plan source-piece updates as part of the rollout. As each derivative ships, the source's "related" or "see also" section gets updated. The source becomes a navigation hub for the cross-format set. + +--- + +## Failure 12: Capacity underestimation + +**Symptom.** The team planned 30 hours for a whitepaper repurposing pipeline; actual cost is 70 hours. New production suffers; team burns out. + +**Diagnosis.** Capacity estimates were based on optimistic assumptions or on prior pipelines that were not as substantial. + +**Cure.** Track actual capacity per pipeline (see `repurposing-pipeline-templates.md`). Calibrate estimates over time. Some pipelines genuinely cost more than the team has budget for; the right answer may be to reduce scope rather than to overrun. + +--- + +## Failure 13: No measurement + +**Symptom.** Cross-format sets ship; the team has a vague sense some perform better than others; the program does not learn. + +**Diagnosis.** No per-pipeline or per-derivative tracking. Outcomes are anecdotal rather than data-driven. + +**Cure.** Establish a minimum log per pipeline run: source piece, derivatives planned vs delivered, capacity spent, outcomes per derivative, lessons learned. Pattern-detect across pipelines to inform future ones. + +--- + +## Failure 14: Pipeline dogmatism + +**Symptom.** The team applies the same pipeline template to every source piece regardless of the source's characteristics or the audience overlap. Some derivatives consistently underperform; the team keeps producing them anyway. + +**Diagnosis.** Treating templates as fixed shapes rather than as starting points to customize. + +**Cure.** Customize pipelines per source piece. Audience characteristics, source characteristics, and capacity should adjust the cross-format set. Drop derivatives that consistently underperform for the program's audience mix. + +--- + +## Failure 15: AI repurposing as the strategy + +**Symptom.** "We use AI to repurpose, so we can scale." The output is a wave of low-engagement derivatives across many channels. The team is producing more derivative content than ever; engagement is flat or declining. + +**Diagnosis.** AI is being treated as a substitute for the craft of cross-format adaptation. Volume is being prioritized over quality. + +**Cure.** AI is a tool within the workflow, not the workflow itself. The discipline of adaptation per medium is still the work; AI accelerates parts of it. See `ai-content-collaboration` for the workflow discipline that prevents AI-assisted repurposing from drifting into mass-blast and slop. + +--- + +## The cross-cutting pattern + +Most repurposing failures share a single root: treating repurposing as content multiplication rather than as cross-format craft. + +Multiplication thinking treats each derivative as another item in a quota: more channels, more pieces, more reach. The output is mass-blast and slop because adaptation is skipped. + +Craft thinking treats each derivative as a piece in its own right, adapted for its medium, holding the source's voice while respecting the format's conventions. The output is a coherent cross-format set where each derivative earns engagement on its medium. + +The fix for almost any repurposing failure is the same: stop multiplying, start adapting. The capacity required for craft-driven repurposing is higher than multiplication-driven repurposing; the value extracted is also higher, often by an order of magnitude. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the multiplication-vs-craft framing. + +## Implementation choices that stay internal + +Specific tooling for derivative tracking. Specific reporting templates for cross-format outcomes. Specific reviewer training on per-format conventions. Specific automation that flags voice drift across derivatives. The team's own conventions for failure-pattern detection in their pipelines. These vary by team and tooling. diff --git a/skills/content-repurposing/references/cross-promotion-patterns.md b/skills/content-repurposing/references/cross-promotion-patterns.md new file mode 100644 index 0000000..e775ee6 --- /dev/null +++ b/skills/content-repurposing/references/cross-promotion-patterns.md @@ -0,0 +1,170 @@ +# Cross-promotion patterns + +Linking patterns, attribution, and co-promotion across channels. The mechanics that turn a cross-format set into a coordinated extension rather than scattered derivatives. + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. The cross-promotion discipline is small per-derivative but compounds significantly across the set. + +--- + +## Derivative back to source + +Each derivative includes a link or reference to the source piece for readers who want depth. + +**The pattern.** + +- Blog-post derivative includes "This is one of six pieces drawing from our recent whitepaper on X. Read the full whitepaper here." +- Email derivative ends with "Want the full framework? Read the original piece here." +- Social-post derivative includes a link to the source in profile, in comments, or as part of a multi-post thread. +- Podcast episode show notes link to the source article. +- Video description links to the source. + +**Why it works.** The source's traffic compounds. Audiences who engage with a derivative and want depth click through; the source piece earns continued traffic from the cross-format set. The source's authority benefits from the inbound links from derivative pieces. + +**The discipline.** Every derivative includes a derivative-to-source link as a non-negotiable element of the format adaptation. The link is not buried; it is positioned where readers who want more naturally find it. + +--- + +## Source forward to derivatives + +The source piece is updated to include links to derivatives as they ship. + +**The pattern.** + +- A "related" or "see also" section at the end of the source piece, updated as derivatives ship. +- Inline links from specific source sections to corresponding derivatives that develop those sections. +- A dedicated "this piece's extensions" callout linking to the cross-format set. + +**Why it works.** The source becomes the hub for the cross-format extension. Audiences who land on the source can navigate to derivatives that match their preferred format. The source's role as canonical anchor strengthens. + +**The discipline.** Update the source piece as the cross-format set rolls out. Stale source pieces that do not reference their derivatives miss the cross-promotion opportunity. + +--- + +## Derivatives across + +Where appropriate, derivatives link to other derivatives in the cross-format set. + +**The pattern.** + +- Blog post 3 in a series links to blog posts 1, 2, 4, 5, 6 either inline or in a "more in this series" footer. +- Email 5 in a sequence references email 4's framework or previews email 6. +- Podcast episode show notes link to a related video, blog series, or webinar. +- Webinar registration page links to the relevant blog series and the underlying source piece. + +**Why it works.** The series feeling helps audiences engage with multiple pieces. Internal linking compounds across the set. SEO benefits accrue when derivatives strengthen each other's authority. + +**The discipline.** Plan the cross-derivative link graph at production time. Each derivative's link plan is part of the production work, not an afterthought. + +--- + +## Attribution within derivatives + +When a derivative is clearly drawn from a source piece, acknowledge. + +**The pattern.** + +- "This is adapted from our recent piece on X." +- "Drawing from our research on [topic]." +- "Originally published as [source piece title]." +- For social posts: "From our recent whitepaper on X, [insight]." + +**Why it works.** Attribution earns reader trust. Uncredited derivatives can feel like the same work being recycled without acknowledgment; audiences notice and discount the program's perceived effort. + +**The discipline.** Attribution is honest about the derivative status. The format adaptation is the value-add; pretending the derivative is independent work overstates the production effort and reads as low-trust positioning. + +**Anti-pattern: hiding derivatives.** Some teams treat derivatives as if they were independent pieces, with no acknowledgment that they draw from a source. Audiences who follow the program detect the recycling and the cross-format coherence is lost. + +--- + +## Co-promotion across channels + +Derivatives can be promoted on channels other than the channel where they natively live. + +**The pattern.** + +- A blog post derivative gets re-shared on social where the original blog post might not have been re-shared without the derivative pretext. +- A social post derivative gets mentioned in the email newsletter as "our latest LinkedIn post on X." +- A podcast episode gets promoted on social, in the email, and on the blog. +- A video derivative gets embedded in a blog post or shared via email. + +**Why it works.** Each derivative's reach extends beyond its native channel. Audiences encountering a derivative through cross-channel promotion discover both the derivative and the channel where it lives. + +**The discipline.** Plan cross-channel promotion as part of the rollout. Each derivative has a primary channel (where it lives natively) and a secondary channel set (where it gets promoted from). The plan is explicit, not improvised. + +--- + +## Internal linking refresh on related pieces + +Pieces in the library that are related to the source's topic may benefit from updated internal linking when the source's cross-format set rolls out. + +**The pattern.** + +- Sister pieces that mention the source's topic get updated to link to the source piece (if they did not already) and possibly to the most relevant derivative. +- Pieces in the same hub or category get updated where the cross-format set makes new linking opportunities sensible. +- Anchor text on existing internal links may benefit from refresh if the source's positioning shifted. + +**Why it works.** The source's authority benefits from internal links across the library. Derivatives benefit from being part of the link graph rather than orphaned. + +**The discipline.** Run a brief internal-linking audit when the cross-format set rolls out. The audit catches obvious linking opportunities; over-investing in this pass is the failure mode (touching too many pieces, producing diminishing returns). + +--- + +## The cross-promotion graph + +Visualizing the cross-promotion structure as a graph helps catch gaps. + +**Nodes.** The source piece and each derivative. + +**Edges.** + +- Source-to-derivative links. +- Derivative-to-source links. +- Derivative-to-derivative links. +- Cross-channel co-promotion (each channel promoting each piece). + +**Audit.** Each derivative should connect to the source. Each derivative should connect to at least one other derivative where format-appropriate. Each derivative should be co-promoted on at least one secondary channel where audience overlap exists. + +**Output of the audit.** A planned link and promotion graph for the cross-format set, with the gaps identified before the rollout begins. + +--- + +## Common cross-promotion failures + +**Derivatives shipping in isolation.** Each derivative ships without links to source or to other derivatives. The cross-format set reads as scattered pieces; the compounding effect of cross-linking is lost. + +**Source piece not updated.** Source publishes; derivatives ship; the source piece is never updated to reference the derivatives. The hub function of the source is wasted. + +**Attribution skipped.** Derivatives ship without acknowledging the source. Audiences detect the recycling; trust degrades. + +**Cross-channel co-promotion skipped.** Each derivative stays on its native channel. Reach is limited to the audiences who happen to be on each channel. + +**Internal-linking refresh skipped.** Existing pieces in the library do not get linked to the new source piece. The library's internal-link graph stays static; the source piece's authority does not benefit. + +**Over-investment in cross-promotion.** Internal-link refresh that touches 50+ pieces in the library produces diminishing returns and maintenance overhead. Cure: target the highest-value linking opportunities; skip the marginal ones. + +--- + +## Cross-promotion in mature programs + +Programs with established cross-promotion discipline accumulate compounding effects over time. + +**The pattern in mature programs.** + +- Every flagship piece has an established cross-format extension plan. +- Every derivative has documented linking and promotion structure. +- The library's internal-link graph reflects accumulated cross-promotion across multiple cross-format sets over years. +- Audiences trust that pieces from the program connect; navigation between pieces feels intuitive. + +**The compounding effect.** Older flagship pieces continue to draw traffic because their cross-format sets extended their reach; their derivatives continue to draw traffic because their cross-promotion brought audiences in. The library's traffic profile reflects accumulated cross-format work, not just individual-piece performance. + +**The maturity audit.** Do new flagship pieces' cross-format sets connect to older flagship pieces' cross-format sets where topics overlap? Mature programs cross-promote across time; immature programs treat each cross-format set as isolated. + +--- + +## Methodology-level choices that stay in the public skill + +The cross-promotion link patterns, attribution discipline, co-promotion across channels, internal linking refresh, the cross-promotion graph, the common failures, the maturity-audit pattern. + +## Implementation choices that stay internal + +Specific link-graph tooling. Specific automation that surfaces missing cross-format links. Specific channel-promotion calendars. Specific internal-link audit tools. The team's own conventions for attribution language. These vary by team, CMS, and tooling. diff --git a/skills/content-repurposing/references/format-adaptation-patterns.md b/skills/content-repurposing/references/format-adaptation-patterns.md new file mode 100644 index 0000000..18b376f --- /dev/null +++ b/skills/content-repurposing/references/format-adaptation-patterns.md @@ -0,0 +1,202 @@ +# Format adaptation patterns + +Eight source-to-derivative adaptations with worked examples. The patterns that distinguish thoughtful adaptation from mass-blast. + +Each pattern below is a recurring shape: a particular source-piece type adapting into a particular derivative format. The patterns are not the only adaptations; they are the most common, with the most predictable success and failure modes. + +--- + +## Pattern 1: Long-form to blog series + +**Source.** A 4,000-8,000 word whitepaper, definitive guide, or research report. + +**Derivatives.** 4-6 standalone blog posts. Each post takes one of the source's H2 sections (or one of its sub-arguments) and develops it as a piece in its own right. + +**Adaptation work.** + +- New lede per post. The source's lede establishes the whole piece's thesis; each derivative needs its own lede that establishes its standalone scope. +- New closing per post. Source closing addresses the whole piece's argument; derivative closings address the post's specific argument. +- Connective tissue. Each derivative briefly references the source piece ("This is one of six pieces drawing from our recent whitepaper on X") and links forward to other derivatives in the series and back to the source. +- SEO targeting per derivative. The source piece may target one primary keyword cluster; each derivative can target a more specific long-tail keyword. + +**Example.** A whitepaper "The complete framework for content distribution" with H2 sections on owned, earned, paid channels, audience-channel matching, content-channel matching, and distribution measurement. Derivatives: 6 blog posts, one per section, each developing the section into a standalone piece (typically 1,200-1,800 words each). + +**Common failures.** + +- Derivative posts that are paste-ins of source sections without rewriting. Reads as duplicate content; SEO penalty risk; voice flatness. +- Derivative posts that compete with the source for the same keyword (cannibalization). Cure: explicit primary-keyword assignment per piece, with derivatives on long-tail variants. +- Derivative posts that drop the source's voice. Cure: voice prompts and review per derivative. + +--- + +## Pattern 2: Blog post to email sequence + +**Source.** A 1,200-2,500 word blog post on a multi-step framework, methodology, or process. + +**Derivatives.** 3-7 emails delivered over 1-3 weeks. Each email develops one step or section of the source's framework with sender-voice adaptation. + +**Adaptation work.** + +- Sender voice. Email voice is more direct and conversational than blog voice. Sentences shorter; "you" usage higher; more direct address. +- Engagement hooks per email. Subject line and preheader carry most of the email's open-rate burden. Hooks need to be earned per email. +- One CTA per email. Email format rewards single clear CTAs; multi-CTA emails underperform. +- Sequential building. Each email assumes the prior emails have been read; the sequence builds; the final email synthesizes. + +**Example.** A blog post on "the 5-step framework for product launches" becomes a 6-email sequence: introduction email, one email per step, synthesis email. Each email is 200-500 words with a single CTA. + +**Common failures.** + +- Emails that are blog paragraphs with "read more" links. Mass-blast pattern. +- Emails that lose voice consistency. Cure: voice anchored to source's distinctive register; per-email review. +- Sequences that are too long. 12-email sequences from a 1,500-word source are over-extension; audiences disengage. Cure: match sequence length to source's actual content depth. + +--- + +## Pattern 3: Whitepaper to webinar + +**Source.** A substantive whitepaper or research report. + +**Derivatives.** A 30-45 minute webinar with the whitepaper's framework as the spine, plus live elements that print does not support: Q&A, polls, interactive moments, possibly guest appearances. + +**Adaptation work.** + +- Spine selection. The webinar typically takes the whitepaper's 3-5 most load-bearing sections as its spine. Lower-priority sections from the source become spoken asides or get cut. +- Spoken-language adaptation. Print-style sentences read aloud sound stilted. The webinar script (or speaker notes) is rewritten in spoken voice. +- Interactive design. Polls, Q&A, audience prompts. Webinar without interactivity is a video; webinar with interactivity earns the format. +- Slide design. Text-heavy slides fail; the visual layer carries the audience's attention while the speaker delivers the content. +- Recording and follow-up. Most webinars become video derivatives after the live session; the recording extends value indefinitely. + +**Example.** A 6,000-word research report on B2B paid media benchmarks becomes a 40-minute webinar: 25-minute walkthrough of the report's framework with the speaker's commentary, 10-minute Q&A, 5-minute conclusion with specific recommendations. The recording is later cut into derivative video clips. + +**Common failures.** + +- Webinars that read the whitepaper aloud. The whitepaper is published; the webinar adds nothing. +- No interactivity. Live audiences disengage when the format is one-way. +- Text-heavy slides that compete with the speaker. Cure: visuals carry the design; speaker carries the content. + +--- + +## Pattern 4: Long-form to social posts + +**Source.** A long-form piece (whitepaper, definitive guide, research report). + +**Derivatives.** 8-30 social posts across the platforms where the audience exists. Each post is one specific moment from the source: a pull quote, a framework summary, a key statistic, a contrarian claim. + +**Adaptation work.** + +- Platform-specific structure. LinkedIn long-post structure differs from X/Twitter thread structure differs from Threads structure. Adaptation is per platform. +- Hook in the first 1-2 lines. Social readers decide to expand or scroll within seconds; the hook earns expansion. +- Visual or quote-graphic options. Many social posts benefit from accompanying visuals (quote graphics, statistic graphics, framework diagrams). +- One specific point per post. Multi-point social posts dilute; one clear point earns engagement. +- Series cadence. Posts shipped over weeks rather than dumped in one day; audiences engage with each post if they are spaced. + +**Example.** A whitepaper on AI search optimization becomes 18 social posts: 6 framework-summary posts, 4 statistic posts (with custom graphics), 4 contrarian-claim posts, 4 question-prompt posts. Distributed over 6 weeks across LinkedIn and X. + +**Common failures.** + +- Posts that are quote graphics with no context. The graphic is decoration; the post needs text that earns engagement. +- Posts that read as blog-text paste-ins. Mass-blast on social. +- Cadence too aggressive. 18 posts in one week exhausts audiences; distributed cadence performs better. + +--- + +## Pattern 5: Article to podcast episode + +**Source.** A substantive article (1,500-3,500 words). + +**Derivatives.** A podcast episode with the article as spine, plus host commentary, examples, and possibly guest interviews. + +**Adaptation work.** + +- Spoken-language adaptation. Article sentences read aloud sound stiff. The episode script (or talking-points outline) is in spoken voice. +- Conversational pacing. Examples and asides that print would cut earn their place in audio because the conversation needs space to breathe. +- Show notes as derivative format. The show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as a derivative in their own right. +- Guest dynamics where applicable. Some podcast episodes pair the article's framework with guest perspective; the article is the show's structured input, the guest adds expert commentary. + +**Example.** An article on programmatic SEO durability becomes a podcast episode: 5-minute introduction by the host, 30-minute interview with a practitioner who has run programmatic operations, 10-minute synthesis by the host. Show notes link to the source article and to several mentioned references. + +**Common failures.** + +- Episodes that read the article aloud. The article is published; the episode adds nothing. +- Episodes without spoken-language adaptation. Stilted delivery; low completion rates. +- Show notes that are afterthoughts. Show notes that fail their own format reduce the episode's discoverability and value. + +--- + +## Pattern 6: Long-form to video shorts + +**Source.** A long-form piece with travelable elements (specific examples, framework moments, contrarian claims). + +**Derivatives.** 6-20 short-form video clips, 30-90 seconds each. Each short is one standalone moment. + +**Adaptation work.** + +- Hook in seconds 1-2. Algorithmic recommendation rewards retention from second 1; openings must earn continued viewing. +- Captions essential. Many viewers watch without sound; captions carry the message. +- Visual presence. Talking-head shorts work for some audiences; many short-form platforms reward visual variation, motion, or text-on-screen design. +- Single specific point per short. Short-form does not support multi-point delivery; one moment per clip. +- Platform-specific aspect ratios and conventions. TikTok shorts, Instagram Reels, YouTube Shorts each have specific norms. + +**Example.** A research report becomes 12 video shorts: 4 statistic shorts (text-on-screen with audio narration), 4 framework moment shorts (whiteboard-style explanation), 4 contrarian-claim shorts (talking head). Distributed across LinkedIn video, YouTube Shorts, Instagram Reels. + +**Common failures.** + +- Shorts without strong opening hooks. Algorithmic feed deprioritizes; reach is minimal. +- Shorts without captions. 50%+ of audience cannot consume the content. +- Shorts that try to cover too much in 60 seconds. Cure: one moment, one point, one short. + +--- + +## Pattern 7: Research report to FAQ extractions + +**Source.** A research report or definitive guide with specific Q&A-able material. + +**Derivatives.** Standalone FAQ entries (40-80 words each), formatted for AI search citation, possibly aggregated into FAQ pages or schema-marked snippets within the source piece. + +**Adaptation work.** + +- Question framing. AI search engines cite content that matches likely user-query phrasings. FAQ questions need to use the phrasings users actually search. +- Standalone answer paragraphs. Each FAQ answer must work as a standalone paragraph; AI engines cite paragraphs, not contextual passages. +- Source attribution within the answer. Statistics and specific claims need named sources within the answer paragraph; AI engines weight named-source claims at higher rates. +- Schema markup. FAQPage schema where the FAQ aggregates as a dedicated page; structured data signals the format to search engines. + +**Example.** A research report on content distribution effectiveness becomes 15 FAQ extractions: "What channels produce highest engagement for B2B content?" "How does audience size affect channel selection?" "What is the typical engagement rate decay across channel types?" Each Q&A is 40-80 words with named-source citations. + +**Common failures.** + +- Questions that do not match how users phrase queries. Cure: query research; phrase questions in user voice. +- Answers that depend on context outside the answer paragraph. AI engines may not cite cleanly; paragraphs need to stand alone. +- Missing schema markup. The FAQ format does not signal cleanly to search engines without schema. + +--- + +## Pattern 8: Multi-piece source to ebook + +**Source.** Several related pieces (blog posts, articles, social threads) that together cover a topic. + +**Derivatives.** An ebook with the multi-piece content as the bulk, plus new connective tissue: introduction, chapter framings, conclusions, and possibly new chapters that fill gaps the source pieces did not cover. + +**Adaptation work.** + +- Topic synthesis. The multi-piece source covers the topic in scattered ways; the ebook needs to organize the content into a coherent sequence. +- New connective tissue. Introductions, chapter prefaces, transitions, conclusion. Often 20-30% of the ebook is new content not present in the source pieces. +- Voice consolidation. Pieces written over months may have voice variation; the ebook needs to read as one unified work, which often means rewriting passages to match a target voice. +- Design and production. Ebook format expectations: chapter design, table of contents, possibly downloadable PDF. Higher production cost than other repurposing patterns. + +**Example.** Twelve blog posts on a topical theme, written over 18 months, are consolidated into a 22,000-word ebook. New material includes a 1,500-word introduction, chapter framings totaling 3,000 words, a 1,500-word conclusion, and a 2,500-word new chapter that fills a gap the original posts did not address. + +**Common failures.** + +- Ebook that reads as posts stitched together. Cure: rewrite for unity; the ebook is a piece in its own right. +- No new connective tissue. The ebook adds no value over reading the source pieces. +- Voice inconsistency. Voice drift across pieces becomes visible when consolidated; cure: unified voice editing pass. + +--- + +## Methodology-level choices that stay in the public skill + +The eight adaptation patterns with their work, examples, and common failures. The recurring lesson: adaptation is per-format craft, not source-text recycling. + +## Implementation choices that stay internal + +Specific platform automation tooling. Specific design templates per derivative format. Specific tooling for video clip extraction from longer videos. Specific show-notes templates. Specific schema markup patterns the team uses for FAQ extractions. The team's own conventions for connective-tissue length in ebook consolidation. These vary by team, stack, and platform mix. diff --git a/skills/content-repurposing/references/per-format-constraints.md b/skills/content-repurposing/references/per-format-constraints.md new file mode 100644 index 0000000..df75a32 --- /dev/null +++ b/skills/content-repurposing/references/per-format-constraints.md @@ -0,0 +1,192 @@ +# Per-format constraints + +What each medium demands and forbids. Length norms, conventions, hooks, and the underlying observation: derivatives that ignore the medium's constraints fail the medium even when the source content was strong. + +Each format below has specific reader expectations. Pieces that meet expectations earn engagement; pieces that violate expectations get scrolled past or ignored regardless of content quality. Repurposing capacity goes to waste when derivatives fail the format-specific tax. + +--- + +## Email + +**Length norms.** 200-800 words per email for most B2B and consumer audiences. Newsletter-style emails can run longer (1,500-3,000 words) for engaged audiences but shorter is generally safer. + +**What email demands.** + +- A subject line that earns the open. Most engagement happens or fails at the subject-line level. +- A preheader that supports the subject line. The preheader is the second-most-read element of the email and most templates underuse it. +- Plain prose paragraphs that render reliably. Many email clients break complex formatting; tables, columns, and rich layouts can fail. +- A single clear CTA. Multi-CTA emails dilute; readers process one action at a time. +- Mobile-first design. 60-70% of email opens are on mobile; readability on small screens is essential. + +**What email forbids.** + +- Image-only emails. Many clients block images by default; image-only emails arrive blank. +- Link-laden text dumps. More than 3-4 links in body text dilutes attention. +- Multi-CTA layouts that compete for the click. +- Subject lines that announce the topic without earning the open ("Newsletter for week of X"). + +**Adaptation discipline.** Email derivatives need new ledes (the source's lede does not transfer); spoken-direct voice (more "you" usage; shorter sentences than blog voice); a single CTA per email even when the source piece had multiple potential actions. + +--- + +## LinkedIn (long-form text post) + +**Length norms.** 800-2,500 characters typical; long-form posts up to ~3,000 characters. The character count matters because the platform truncates with "see more"; the truncation point is the hook. + +**What LinkedIn demands.** + +- A first line that earns the "see more" click. The first 1-3 lines determine whether readers expand the post. +- Clear structure: short paragraphs, white space, occasional emphasis. Walls of text get scrolled past. +- A specific point or argument. Narrative-style posts that take time to land work; vague observations do not. +- Engagement hooks: questions, polarizing claims, specific examples that invite comment. +- Original perspective. Repurposed content marked clearly as such; uncredited recycling reads as low effort. + +**What LinkedIn forbids.** + +- Walls of text without paragraph breaks. +- Generic motivational content; the platform has decreasing tolerance for this. +- Posts that read as ads with no substantive content. +- Heavy use of emoji decoration without purpose. + +**Adaptation discipline.** Source content needs to be restructured for LinkedIn rhythm: short opening hook, body with paragraph breaks every 2-3 sentences, specific examples or stakes, possibly a question at the close that invites comment. + +--- + +## X/Twitter (single post and threads) + +**Length norms.** Single post: 280 characters (or up to 4,000 for premium accounts; conventions vary). Thread: 5-15 posts typical for substantive threads. + +**What X demands (single post).** + +- Tight phrasing. Each character matters; specific framings that fit the format earn engagement. +- Stand-alone meaning. Tweets that depend on context outside the tweet often fail. +- Specific points or claims. Vague observations underperform. + +**What X demands (threads).** + +- A first post that earns the next click. Threads are read sequentially; the first post must hook. +- One coherent argument across the thread. Threads that wander get abandoned mid-way. +- Reasonable length. Threads longer than 15-20 posts often lose readers; very long threads may be better as a blog post linked from a shorter thread. + +**What X forbids.** + +- Threads that read as a blog post split into 280-character chunks. The platform's conversational rhythm is different. +- Hashtags-as-content. Heavy hashtag usage signals SEO chasing rather than communication. + +**Adaptation discipline.** Source content for threads needs to be re-paced: each post a complete thought, the thread building, the conclusion specific. + +--- + +## Long-form video (YouTube, in-depth content) + +**Length norms.** 8-30 minutes typical for substantive content. Some categories support longer (45-90 minutes for deep technical content); the algorithm rewards retention over duration. + +**What long-form video demands.** + +- Pacing for spoken delivery. Print-style sentences read aloud sound stilted; video scripts need spoken voice. +- Visual variation. Talking-head video alone for 30+ minutes underperforms; cuts, b-roll, on-screen text, illustrations carry attention. +- Audio quality. Bad audio kills retention faster than bad video; audio investment usually returns more than video investment. +- A specific topic. The video's title and thumbnail need to communicate scope; vague titles underperform in algorithmic recommendation. + +**What long-form video forbids.** + +- Slideshows of text read aloud. Mass-blast pattern in video form. +- No editing. Filler words, long pauses, and unedited rambling reduce retention. +- Talking head only with no visual variation across long durations. + +**Adaptation discipline.** Source content for video needs scripting in spoken voice (or talking-points for unscripted delivery), visual planning per segment, and an opening that earns the next 30 seconds of viewing. + +--- + +## Short-form video (TikTok, Reels, Shorts) + +**Length norms.** 60-90 seconds typical; 15-30 seconds for some platforms. Algorithmic recommendation typically rewards retention from second 1. + +**What short-form demands.** + +- Hook in seconds 1-2. Viewers scroll past the opening if it does not earn the next 5 seconds. +- Captions. Many viewers watch without sound; captions carry the message. +- A single specific point. Short-form does not support multi-point delivery. +- Visual presence. Motion, text-on-screen, or visual variation within the short. Static talking heads underperform. + +**What short-form forbids.** + +- Content that takes 10+ seconds to land. Viewers leave before the point. +- Long-form video clipped without re-pacing. The pacing assumed in the source piece does not match short-form expectations. +- Captions that lag the audio. Mistimed captions distract. + +**Adaptation discipline.** Source content for shorts needs extreme compression: one moment, one point, one short. Each short is a standalone unit. + +--- + +## Podcast + +**Length norms.** 20-90 minutes typical for substantive content. Daily-news-style podcasts can be shorter (8-15 minutes); deep-interview podcasts can run 90-180 minutes. + +**What podcast demands.** + +- Spoken-language sentence structure. Print-style sentences read aloud sound stiff. +- Conversational pacing. Examples, asides, and natural speech earn engagement; tightly-argued print sections feel cold. +- Audio quality. Listening is intimate; bad audio breaks the connection. Better audio than video matters here. +- Show notes that do the print work the audio cannot. Links, structured summary, citations, references. + +**What podcast forbids.** + +- Reading articles aloud without adaptation. +- Scripts that sound scripted (over-rehearsed delivery, no conversational rhythm). +- Episodes without show notes or with thin show notes. +- Inconsistent episode length within a series; audiences develop expectations. + +**Adaptation discipline.** Source content for podcasts becomes the show's spine; the host adds context, examples, and conversational elaboration. Show notes are a distinct derivative format with their own constraints. + +--- + +## Webinar + +**Length norms.** 30-60 minutes typical. Longer webinars (90+ minutes) require very high engagement design or strong specific draws (like premiere announcements). + +**What webinars demand.** + +- A live element. Q&A, polls, interactive moments. Static webinars are videos; interactive webinars earn the format. +- Slide design that supports rather than competes with delivery. Text-heavy slides distract; visual slides with the speaker carrying the content work. +- Pacing for live audience attention. Audience attention dips in the middle; engagement design needs to address the dip. +- Recording strategy. Most webinars become video assets after the live session; the recording extends value indefinitely. + +**What webinars forbid.** + +- Reading slides aloud. The audience can read; the speaker should add the value the slides cannot carry. +- No engagement design. Audiences disengage in pure one-way webinars. +- Webinars that try to cover too much in 30 minutes. Cure: narrow the topic to what 30 minutes can deliver. + +**Adaptation discipline.** Source content for webinars typically takes the source's 3-5 most load-bearing sections as the spine, plus interactive moments, plus Q&A. + +--- + +## AI-search snippet (for citation by AI engines) + +**Length norms.** 40-80 words per snippet for FAQ-style extractions; 100-200 words for paragraph-style extractions. + +**What AI-search snippets demand.** + +- Standalone meaning. The snippet works without the surrounding context; AI engines extract paragraphs, not full pieces. +- Named-source citations within the snippet. AI engines weight named-source claims; "according to a 2025 Forrester study" performs better than "studies show." +- Specific framings. Vague phrasings rarely get cited; specific phrasings do. +- Schema markup where applicable. FAQPage and similar schemas signal the format. + +**What AI-search snippets forbid.** + +- Floating claims without sources. +- Pronoun references that depend on outside context ("This is why..." with no clear referent within the snippet). +- Hedged language on claims that can be specific. + +**Adaptation discipline.** Source content for AI snippets needs to be extractable as standalone paragraphs with internal citations and specific framings. Often the source piece needs additions specifically designed for snippet citation. + +--- + +## Methodology-level choices that stay in the public skill + +The format constraints by medium, the length norms, the demand-and-forbid lists, the adaptation discipline per format. The underlying observation: medium constraints are non-negotiable. + +## Implementation choices that stay internal + +Specific platform automation. Specific design templates per format. Specific captioning workflows. Specific schema markup patterns. Specific A/B testing of format-specific elements (subject lines, hooks, opening lines). The team's own conventions on length within the bands. These vary by team and platform mix. diff --git a/skills/content-repurposing/references/repurposing-pipeline-templates.md b/skills/content-repurposing/references/repurposing-pipeline-templates.md new file mode 100644 index 0000000..9325d2f --- /dev/null +++ b/skills/content-repurposing/references/repurposing-pipeline-templates.md @@ -0,0 +1,237 @@ +# Repurposing pipeline templates + +Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. The repeatable shapes that turn ad-hoc repurposing into a predictable program. + +Repurposing without templates produces ad-hoc workflows: each cross-format extension is invented from scratch, capacity estimates are unreliable, quality varies. Templates make repurposing a known production shape, with predictable capacity and predictable quality. + +The templates below are recurring shapes; teams adapt them to specific source pieces and program contexts. + +--- + +## Pipeline 1: Whitepaper + +**Source.** A 4,000-8,000 word whitepaper or definitive guide. + +**Cross-format set (typical).** + +- 4-6 blog posts (one per major section). +- 5-7 email sequence. +- 1 webinar. +- 12-18 social posts across LinkedIn, X, possibly Instagram or Threads. +- 6-12 video shorts. +- 10-15 FAQ extractions for AI search. +- Possibly 1 podcast episode. + +**Production sequence.** + +- Week 0: Source piece publishes. +- Week 1: First social posts ship; email teaser sends. FAQ extractions ship as part of the source piece (or as an immediately-following FAQ page). +- Weeks 2-6: Blog posts ship at 1-per-week cadence. Email sequence sends in parallel. More social posts ship from each blog post's release. +- Weeks 4-8: Webinar runs. Webinar recording becomes additional video derivatives. +- Weeks 6-10: Video shorts ship. Podcast episode (if applicable) records and releases. + +**Capacity.** Typical whitepaper pipeline costs 30-60 hours of editorial and production work across 8-10 weeks, on top of the source piece's production cost. + +**Owner structure.** Single owner-of-extensions for the whitepaper. Specific derivative owners by format (blog series owner, email sequence owner, social owner, video owner). The owner-of-extensions coordinates timing and ensures cross-promotion happens. + +--- + +## Pipeline 2: Blog post (substantive) + +**Source.** A 1,500-2,500 word substantive blog post on a multi-step framework or substantive topic. + +**Cross-format set (typical).** + +- 5-7 email sequence (if the source has a multi-step framework). +- 4-8 social posts. +- 2-4 video shorts. +- 3-5 FAQ extractions. +- Possibly 1 podcast episode segment (not full episode). + +**Production sequence.** + +- Week 0: Blog post publishes. +- Week 1: First social posts ship; email teaser if part of a sequence; FAQ extractions added to the post. +- Weeks 2-4: Email sequence sends. Additional social posts. Video shorts ship. +- Weeks 4-6: Long-tail social and AI-search-snippet refinement. + +**Capacity.** Typical substantive blog post pipeline costs 8-15 hours of additional work across 4-6 weeks. + +**Owner structure.** Often one owner runs the full extension for blog-post-tier sources because the work is small enough to coordinate in one head. + +--- + +## Pipeline 3: Research report + +**Source.** A 4,000-12,000 word research report with primary data. + +**Cross-format set (typical).** + +- 5-8 blog posts (one per major finding or section). +- 7-10 email sequence. +- 1-2 webinars (often a launch webinar plus a deeper-dive webinar). +- 20-30 social posts (research reports produce many statistic-driven social derivatives). +- 8-15 video shorts (statistic-focused). +- 15-25 FAQ extractions. +- 1-2 podcast episodes. +- Possibly an interactive data visualization or microsite. + +**Production sequence.** + +- Week -2 to Week 0: Pre-launch promotion teasers (research findings preview). +- Week 0: Source report publishes; launch webinar announces; first wave of statistic-focused social ships. +- Weeks 1-4: Heavy email sequence; blog posts ship; webinars run; social posts continue. +- Weeks 4-12: Video shorts roll out; podcast episodes record and release; FAQ extractions get refined as AI-search citations are tracked; second webinar runs for deeper-dive audience. +- Indefinitely: Statistics from the report continue to be cited in subsequent program pieces; the report becomes a reference asset. + +**Capacity.** Research report pipelines are the highest-investment repurposing efforts. Typical cost: 60-150 hours of additional work across 8-16 weeks, on top of the report's production cost. + +**Owner structure.** Owner-of-extensions plus dedicated derivative owners. Often a research report's cross-format extension is treated as a project with its own project manager rather than as a routine repurposing pipeline. + +--- + +## Pipeline 4: Multi-piece consolidation (ebook) + +**Source.** Multiple existing pieces (blog posts, articles, social threads) on a related topic. + +**Cross-format set (typical).** + +- 1 ebook (the primary consolidation). +- New introduction, chapter framings, conclusion within the ebook (often 20-30% new content). +- 4-7 promotional blog posts (potentially excerpting chapters or introducing the ebook). +- 5-8 email sequence promoting the ebook. +- 1 webinar based on the ebook's framework. +- 8-15 social posts promoting the ebook and its chapters. +- 3-6 video shorts. + +**Production sequence.** + +- Months 1-3: Source-piece selection and consolidation. Identify which existing pieces fit; outline the ebook; write new connective tissue; consolidate and edit for unified voice. +- Month 3-4: Production: design, layout, possibly PDF generation, gating setup if applicable. +- Month 4: Ebook launches. First promotional blog posts and emails ship. Webinar runs. +- Months 5-8: Promotional cadence continues. Video shorts and social posts roll out. + +**Capacity.** Multi-piece consolidation pipelines often cost 60-120 hours of consolidation and production work, plus the standard derivative production. Total: 80-180 hours across 4-8 months. + +**Owner structure.** A consolidation lead drives the editorial work; standard derivative owners run the promotional set. The consolidation lead often is a senior editor because the unified-voice editing is substantial. + +--- + +## Pipeline 5: Trending topic editorial + +**Source.** A 1,000-2,500 word editorial piece on a trending or news-driven topic. + +**Cross-format set (typical, lighter than evergreen).** + +- 4-7 social posts (concentrated in the first week to ride the trend). +- 1-2 video shorts. +- 1-2 FAQ extractions if the topic supports it. +- Often no email sequence (trending topics may not justify a multi-email investment). +- Often no webinar (production cycle is too long for trending topics). + +**Production sequence.** + +- Day 0: Source piece publishes. +- Days 1-7: Social posts ship rapidly to ride the trend. Video shorts ship if production cycle allows. +- Weeks 2-4: Long-tail social and AI-search-snippet refinement if the topic has staying power. +- After 4 weeks: Pipeline typically winds down as the trend fades. + +**Capacity.** Trending topic pipelines are deliberately light: 4-10 hours of additional work across 1-2 weeks. + +**Owner structure.** Often one owner runs the full extension because timeliness matters more than coordinated multi-format depth. + +--- + +## Pipeline 6: Case study + +**Source.** A 2,000-4,000 word case study with real specifics. + +**Cross-format set (typical).** + +- 3-5 blog posts pulling specific lessons or framework moments from the case. +- 3-5 email sequence (if the case study has clear teachable steps). +- 6-10 social posts (often statistic-driven from the case's outcomes). +- 1-3 video shorts (often featuring the case's customer if available, with their consent). +- 3-5 FAQ extractions. +- Possibly 1 webinar featuring the customer. + +**Production sequence.** + +- Week 0: Case study publishes. +- Week 1: First social posts ship; FAQ extractions added. +- Weeks 2-6: Blog posts and emails ship. Webinar runs (if part of the plan, often with customer participation). +- Weeks 4-10: Video shorts and additional social. + +**Capacity.** Typical case study pipeline costs 15-30 hours of additional work, plus customer coordination time for any derivatives featuring the customer. + +**Owner structure.** Customer-coordination owner plus standard derivative owners. The customer-coordination owner manages the relationship; derivative owners produce the work; the customer reviews customer-facing derivatives before they ship. + +--- + +## Pipeline customization + +Templates are starting points; programs adapt them. + +**Customization based on audience.** + +- B2B technical audiences: more LinkedIn, more whitepaper-driven; less TikTok and Instagram. +- Consumer audiences: more video and visual social; less long-form. +- Vertical-specific audiences: platform mix may differ (YouTube heavy in some industries; Twitter/X heavy in others). + +**Customization based on capacity.** + +- Smaller teams may execute Pipeline 1 with reduced scope (3 blog posts instead of 6, 6 social posts instead of 18). +- Larger teams may extend pipelines with additional derivatives the templates do not include (interactive tools, microsites, dedicated landing pages). + +**Customization based on source characteristics.** + +- Highly visual source pieces benefit from heavier video and visual-social investment. +- Voice-distinctive source pieces benefit from heavier email and podcast investment (where voice carries). +- Citation-rich source pieces benefit from heavier AEO-extraction investment. + +--- + +## Pipeline tracking + +Each pipeline run produces data that informs future pipelines. + +**The minimum log per pipeline.** + +- Source piece title, type, length, traffic at launch. +- Cross-format set planned vs delivered. +- Capacity spent (hours per derivative type). +- Outcomes per derivative (engagement, traffic, conversion, citation rates). +- Lessons learned (what worked, what failed, what to change next time). + +**Pattern detection across pipelines.** + +- Are some pipeline templates outperforming others on similar source types? +- Are some derivative types consistently outperforming others? +- Are capacity estimates accurate, or do certain pipelines consistently overrun? +- Are some channels consistently underperforming for the program's audience mix? + +The log informs program-level decisions: which pipelines to invest in more deeply, which to drop, which to redesign. + +--- + +## Common pipeline failures + +**Pipeline-as-checklist.** The team treats the pipeline as a checklist to complete rather than as a coordinated plan. Each derivative gets produced; nothing connects to the others; cross-promotion is missing. + +**Capacity underestimation.** Teams plan a Pipeline 1 expecting 30 hours; actual cost is 70 hours; new production suffers. Cure: track actual capacity per pipeline; calibrate estimates. + +**Pipeline dogmatism.** Treating the template as a fixed shape regardless of source-piece characteristics. Some source pieces fit the template; some need customization. Cure: customize pipelines per source. + +**No tracking.** Pipelines run; outcomes are not measured; the program does not learn. Cure: minimum log per pipeline. + +**No owner-of-extensions.** Pipelines run with derivative owners but no overall coordination. Cross-promotion gaps; cadence drift; no single accountable person. Cure: assign an owner-of-extensions per pipeline. + +--- + +## Methodology-level choices that stay in the public skill + +The six pipeline templates with cross-format set, sequencing, capacity, and ownership structures. The pipeline customization framework. The pipeline tracking log. The common pipeline failures. + +## Implementation choices that stay internal + +Specific project-management templates per pipeline. Specific calendar tooling for cross-format scheduling. Specific time-tracking that captures pipeline capacity. Specific reporting templates for pipeline outcomes. The team's own conventions for which pipelines apply to which source-piece tiers. These vary by team, tooling, and program scale. diff --git a/skills/content-repurposing/references/sequencing-and-cadence-patterns.md b/skills/content-repurposing/references/sequencing-and-cadence-patterns.md new file mode 100644 index 0000000..0678d1e --- /dev/null +++ b/skills/content-repurposing/references/sequencing-and-cadence-patterns.md @@ -0,0 +1,198 @@ +# Sequencing and cadence patterns + +When to release derivatives relative to the source. Concentrated vs distributed cadence. Pacing audits. The patterns that match cadence to the source's traffic curve and audience attention. + +The release sequence and cadence determine how the cross-format set lands. The wrong sequencing can produce a wave of derivatives that exhausts audiences, or a trickle that loses connection to the source's authority. The right sequencing matches the source's traffic curve and the audiences' attention rhythm. + +--- + +## Sequencing patterns + +Three patterns for how derivatives sequence relative to the source. + +### Source-first, derivatives following + +**The pattern.** The source piece publishes; derivatives roll out over the following 2-12 weeks. The source carries the initial authority and traffic spike; derivatives extend reach and re-engage audiences over time. + +**Strengths.** + +- The source piece's launch is concentrated, earning the full attention of the program's audiences. The launch is a moment. +- Derivatives reference the source's authority. Each derivative can link back to the source as the canonical version; the source's ranking and authority compounds. +- Audiences who engaged with the source are primed for derivatives; the first derivative often performs well because the audience is warm. + +**Weaknesses.** + +- The source needs to support the launch with strong promotion. If the source publishes quietly, the launch moment is muted. +- Audiences who missed the source see derivatives without context; the derivatives need to stand alone. + +**Fits.** Most programs. The default sequencing pattern. + +### Simultaneous launch + +**The pattern.** Source and a wave of derivatives publish on the same day. Multiple channels fire at once. + +**Strengths.** + +- Maximum splash. The cross-format presence on a single day signals significance to audiences. +- Cross-channel reinforcement. Audiences encountering the program on multiple channels in one day register the significance more strongly than serial encounters. + +**Weaknesses.** + +- Risks audience fatigue. If every channel is firing the same day, audiences may tune out before they engage with any individual piece. +- Heavy production load on launch day. All derivatives must be ready simultaneously, which can compress quality. +- Less time for individual derivatives to land. Each derivative competes for attention with every other derivative on the same day. + +**Fits.** Major flagship launches where the moment itself is part of the value (annual research reports, ebook releases, manifesto-style pieces). Tier 1 source pieces. + +### Derivatives-first, source as anchor + +**The pattern.** Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship after the buildup. + +**Strengths.** + +- Builds anticipation. Audiences who engage with the early derivatives expect the source piece. +- The source piece publishes into a primed audience. + +**Weaknesses.** + +- Less common; works only for built-up audiences who follow the program closely. +- Risks giving away too much before the source. If the early derivatives expose the source's argument, the source publishes into an audience that feels they have already read it. +- Coordination overhead. The cross-format buildup needs to land at the right cadence to support the source's launch. + +**Fits.** Programs with engaged audiences and strong social presence. Less common than source-first; specific to programs that have earned anticipation. + +--- + +## Cadence within the rollout + +Three pacing patterns within the chosen sequencing. + +### Concentrated cadence + +**The pattern.** Most derivatives ship within 4-6 weeks of source. + +**Strengths.** + +- Maximum momentum from the source's authority. The source's traffic curve is highest in the first 2-4 weeks; derivatives launching during that window benefit from the source's freshness. +- The cross-format set feels coherent. Audiences see the program everywhere within a short window; the campaign feeling earns engagement. +- Easier to coordinate. Production and scheduling concentrate; the team is in launch mode for a defined period. + +**Weaknesses.** + +- Limited time for individual derivatives to land. A derivative in week 5 has less attention available than the source did in week 1. +- Audience fatigue risk. Audiences may disengage before week 4-6 if the cadence feels relentless. +- Less long-tail value. After week 6, the cross-format set largely stops producing new touchpoints. + +**Fits.** Tier 1 and Tier 2 source pieces. Programs running flagship launches where the campaign nature is part of the strategy. + +### Distributed cadence + +**The pattern.** Derivatives ship over 3-6 months. + +**Strengths.** + +- Each derivative has space to land. No internal competition for audience attention. +- Long-tail value. The program continues to produce touchpoints over a longer window. +- Sustainable. The team is not in launch mode for months; production fits steady-state cadence. + +**Weaknesses.** + +- Risk of losing connection to source. By month 3, the source piece may be background context rather than the active reference. +- Less momentum. The campaign feeling fades; each derivative is a standalone moment rather than part of a coherent push. +- Coordination overhead extended. Owners and producers need to maintain focus across months. + +**Fits.** Evergreen flagship pieces with sustained traffic curves. Programs with smaller production capacity that cannot sustain concentrated cadence. + +### Indefinite cadence + +**The pattern.** Derivatives keep being created from the source as long as the source remains relevant. + +**Strengths.** + +- Maximum long-term value extraction. +- Adapts to audience response. Derivatives that perform well inform what to produce next; the program learns from the cross-format set's reception. + +**Weaknesses.** + +- Most programs cannot sustain indefinite attention to a single source. Discipline tends to decay. +- Risk of voice drift. Derivatives produced 12 months apart may have voice variation that the original launch cadence avoided. +- Less coherent campaign feel. Audiences see scattered derivatives over a long window without a clear narrative. + +**Fits.** Truly evergreen sources whose value compounds for years. Rare; usually reserved for major flagship pieces (defining manifestos, definitive research reports). + +--- + +## Pacing audits + +Match cadence to the source's traffic curve and the audience's attention rhythm. + +**The source's traffic curve.** + +- **Sharp early traffic, fast decay.** Trending-topic pieces, news-driven analysis. Concentrated cadence; the audience is paying attention for a short window. +- **Sustained high traffic for weeks.** Flagship reports on hot topics. Concentrated to mid-distributed cadence; the audience attention extends but eventually fades. +- **Slow build, sustained traffic for months.** Evergreen flagship pieces, definitive guides. Distributed cadence; the audience encounter is continuous over time. +- **Sustained low traffic with occasional spikes.** Reference pieces that get rediscovered. Indefinite cadence works if the production capacity supports it. + +**The audience's attention rhythm.** + +- **Email subscribers.** Engagement varies; sequences spaced 5-7 days work for most B2B; daily for high-engagement consumer audiences. +- **Social audiences.** Platform-specific. LinkedIn rewards 1-2 posts per week from program accounts; X rewards higher frequency; Instagram somewhere in between. +- **Podcast audiences.** Episodic; weekly cadence common; bi-weekly works for higher-production-effort shows. +- **YouTube audiences.** 1-2 videos per week typical for active channels; long-form video can be less frequent. + +**The pacing decision.** Match the source's traffic curve and the audiences' attention rhythm. If they conflict, the source's curve usually wins; the cross-format set's coherence depends on the source's authority window. + +--- + +## Sequencing and cadence per derivative type + +Some derivatives have natural sequencing within the rollout. + +**Derivatives that should ship early.** + +- Email teaser or preview email. Sets up the source's launch with the email audience. +- Social posts that announce the source. Visibility on launch day. +- Short-form video that introduces the topic. Algorithmic recommendation responds best when the content is fresh. + +**Derivatives that should ship 1-3 weeks in.** + +- First blog post in a series. The source piece is still drawing traffic; the blog post benefits from internal linking and the audience's continued interest. +- Webinar based on the source. Allows time for audience registration and promotion. +- First batch of social pull-quote posts. The source's themes are familiar; the pull quotes resonate. + +**Derivatives that should ship 1-3 months in.** + +- Podcast episode. Production cycle is longer; podcast audience overlap with source audience may be partial. +- Subsequent blog posts in a series. Distributed cadence; each post earns its own attention. +- Email sequence (if not the immediate teaser). The sequence develops the source's framework over time. + +**Derivatives with flexible timing.** + +- FAQ extractions and AI-search snippets. These can ship at source-launch or any time after; AI search citation accumulates over months. +- Ebook consolidation. Often ships 6-12 months after source pieces accumulate; the consolidation work itself takes time. + +--- + +## Common sequencing and cadence failures + +**All-at-once dumping.** A wave of 12 derivatives in 5 days. Audiences disengage by day 3; most derivatives produce little engagement. Cure: distributed cadence with audience-attention spacing. + +**Source quietly publishing while derivatives ship loudly.** The derivatives carry the launch but the source piece itself launches without the attention it deserves. Cure: source-first launch with promotion focused on the source; derivatives follow. + +**Source publishing months after promised derivatives.** Derivatives that previewed a coming source piece ship; the source publishes 4 months later. Audiences have lost connection. Cure: tighten production schedule or flip the sequencing to source-first. + +**Cadence too aggressive for the audience.** Email subscribers receiving daily emails for 2 weeks unsubscribe. Cure: match cadence to audience attention norms; email audiences typically tolerate 1-2 sends per week from a program. + +**Cadence too slow.** Distributed cadence stretched too long; by month 4, audiences have forgotten the source. Cure: bring cadence closer to source's traffic curve; consider indefinite cadence only when the source genuinely supports it. + +**No sequencing plan.** Derivatives ship as they happen to be ready, with no coordination. Cross-format set feels random; audiences see scattered touchpoints with no coherent narrative. Cure: even rough sequencing planning at production time produces better outcomes than no plan. + +--- + +## Methodology-level choices that stay in the public skill + +The three sequencing patterns, the three cadence patterns, the pacing audit, the per-derivative-type sequencing, the common failures. + +## Implementation choices that stay internal + +Specific calendar tooling. Specific automation that schedules derivatives across channels. Specific coordination workflows between producers and channel owners. Specific A/B testing of cadence variants. The team's own conventions for fast-track vs queued derivatives. These vary by team and tooling. diff --git a/skills/content-repurposing/references/source-piece-selection-criteria.md b/skills/content-repurposing/references/source-piece-selection-criteria.md new file mode 100644 index 0000000..70e61ac --- /dev/null +++ b/skills/content-repurposing/references/source-piece-selection-criteria.md @@ -0,0 +1,125 @@ +# Source-piece selection criteria + +Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. The discipline that prevents repurposing capacity from being spent on pieces that will not extend cleanly across formats. + +Not every piece is worth repurposing. Selection is the first decision, and getting it wrong produces derivative work that feels forced, fails to engage on the new formats, and consumes capacity that would have produced better return on stronger source pieces. + +--- + +## Strong source-piece characteristics + +A piece that extends cleanly across formats usually has several of the following. + +**Clear central argument or framework.** The piece has a thesis, a framework, or a structured set of positions that survives translation. The reader of any derivative can extract the argument; the reader of the source can recognize it. + +**Standalone sections.** The piece's H2 sections work as standalone units. A reader who only sees one section can still get value; the section does not depend on the cumulative context of preceding sections to make sense. Pieces with this property produce blog-series and social-post derivatives easily. + +**Travelable examples and case studies.** The piece contains specific examples, case studies, or worked illustrations that can stand alone. These travel into video shorts, social posts, and podcast episodes as natural anchors. + +**Audience overlap with target formats.** The source's audience exists on the platforms where derivatives will live. A B2B technical whitepaper extends well into LinkedIn long-form posts and into podcast episodes; less well into TikTok shorts. + +**Distinctive voice.** The piece has voice characteristics specific enough that derivative voice can stay coherent. Pieces in generic voice produce derivatives that sound like AI-default; pieces in distinctive voice anchor derivatives to recognizable register. + +**Accumulated demand.** The source has demonstrated reader interest: traffic, links, mentions, shares, citations. Pieces with traction support derivatives because the demand is real; pieces without traction produce derivatives that draw on no underlying interest. + +**Multi-angle topic.** The topic has multiple angles, sub-questions, or applications. Pieces on narrow single-angle topics produce few derivatives; pieces on broader topics with sub-questions produce more. + +--- + +## Weak source-piece characteristics + +Pieces that resist repurposing usually have several of the following. + +**Tightly-integrated argument.** The piece is a layered argument where every section depends on the cumulative context. Extract any section and it loses meaning. Whitepapers with this structure (high-rigor analytical pieces) often resist clean derivative extraction; the value is in reading end-to-end. + +**List-style without standalone weight.** The piece is a list of items where individual items are not substantial enough to support derivatives. "Top 10 marketing tips" with one-paragraph items per tip cannot produce strong derivatives because no single item justifies a derivative piece. + +**Narrative-arc dependence.** The piece's value comes from the unfolding narrative; reading any segment alone misses the arc. Some narrative case studies and feature-style longform have this property. Derivatives can summarize but cannot replace. + +**Audience-format mismatch.** The source's audience does not exist (or exists thinly) on most target formats. A regulatory-technical whitepaper for compliance officers extends poorly to TikTok; the audience is not there. + +**Generic voice.** The source piece reads in default-AI or generic-content-marketing voice. Derivatives generated from a generic source compound the genericness. Without a distinctive source voice, derivatives drift further from any recognizable register. + +**No demand signal.** The source piece has not earned traffic, links, or shares. Repurposing rarely creates demand that did not exist; pieces without demand should be evaluated for whether they should have been published in the first place. + +**Highly time-bound.** The source piece is about a specific event, news cycle, or moment that will not be relevant in the cadence's timeframe. Derivatives that ship 4-6 weeks after the source may already be out of date. + +--- + +## The selection audit + +A short framework for evaluating a candidate source piece. + +1. **Read the piece's central argument or framework.** Can you state it in one sentence? If not, the piece may not extend cleanly. If yes, the argument is the spine that derivatives will extend. +2. **Identify standalone sections.** Which H2 sections work alone? If most sections work alone, blog-series and social derivatives are natural. If only one section works alone, fewer derivative formats fit. +3. **List travelable elements.** Specific examples, case studies, statistics, or claims that could anchor derivatives. Pieces with 5-10 travelable elements support multi-format extension; pieces with 0-2 do not. +4. **Check audience-format overlap.** For each candidate derivative format, is the source's audience present on the format? If most candidate formats fail this check, the source may not be a multi-format candidate. +5. **Audit voice distinctiveness.** Read three paragraphs from different sections. Could a reader who knows the brand identify this as the brand's work? If yes, derivatives have voice anchor. If no, derivatives will drift. +6. **Check demand signal.** Has the source earned traffic, links, mentions, or shares? Pieces without demand signal do not transmit demand to derivatives. +7. **Estimate extraction yield.** Given the above, how many derivative pieces could the source plausibly support? Pieces yielding 1-2 derivatives may not be worth a formal repurposing plan; pieces yielding 6-12 are clear repurposing candidates. + +--- + +## Pieces that should stay one-and-done + +Some pieces are valuable but resist repurposing. Recognizing them prevents wasted effort. + +**Tightly-argued analytical whitepapers.** Pieces whose value is in the cumulative argument. Often valuable as flagship content but produce few clean derivatives. The right disposition: ship the source piece; create one or two derivative pieces (a summary blog post, an email teaser); accept that most of the value is in the source itself. + +**Highly specific case studies.** Pieces about a single specific situation that does not generalize cleanly. The case is valuable; abstraction loses the specifics that gave the case its weight. The right disposition: ship the case study; create derivative pieces only where the case has clear teachable moments that travel. + +**Time-bound editorial.** Pieces about a specific event, news cycle, or moment. The piece may be valuable in the moment but the moment passes. The right disposition: ship; minimal repurposing during the moment; archive after. + +**Highly visual source pieces.** Pieces whose value is primarily in custom visuals (data dashboards, illustrated guides, complex diagrams). Text derivatives often cannot carry the visual value. The right disposition: derivative video and visual-format extensions only; text derivatives often underperform. + +**Niche-audience pieces.** Pieces for a small specific audience that does not exist on most other formats. The right disposition: minimal repurposing; the audience is concentrated where the source already published. + +--- + +## Tier-based selection + +Programs with regular flagship production benefit from explicit tiering of source pieces by repurposing intensity. + +**Tier 1: Major flagship (1-3 per year).** The source piece is treated as the spine of a multi-month repurposing campaign. 8-15 derivative pieces planned. Cross-format extension covers blog series, email sequence, webinar, podcast, social waves, video shorts, AI-search extractions. Capacity allocation is significant; the source's value is being maximally extracted. + +**Tier 2: Standard flagship (4-12 per year).** Source piece supports 4-8 derivative pieces. Cross-format extension covers a subset of formats: blog series or email sequence (not both), social posts, FAQ extractions for AI search. Capacity allocation is moderate. + +**Tier 3: Routine substantive piece (12-50 per year).** Source piece supports 1-3 derivative pieces. Often a social-post wave, an email mention, an internal-link refresh on related pieces. Minimal additional capacity. + +**Tier 4: One-and-done (the majority of pieces).** Source piece publishes; appears in newsletter once; shares on social once; no derivative pieces planned. Capacity allocation only on the source. + +The tiering discipline. Most programs have too few Tier 1 and Tier 2 pieces and too many Tier 3 and Tier 4 pieces masquerading as flagship work. The audit shifts capacity allocation toward the few pieces that genuinely warrant multi-format extension. + +--- + +## When a piece grows into stronger source-piece status + +Some pieces start as Tier 4 and earn promotion based on performance. + +**The signal.** A piece that was published as routine starts drawing significant traffic, earning links, getting mentioned externally, or producing reader engagement disproportionate to its production tier. + +**The response.** Promote the piece into a higher tier. Plan derivatives. Some of the strongest source pieces in mature programs are pieces that performed unexpectedly well after publication; recognizing them quickly extracts the additional value. + +**The audit.** Quarterly review of pieces' performance. Pieces showing strong demand that have not been repurposed are candidates for retroactive extraction; pieces showing weak demand that were originally tiered as flagship may need their derivative plans reduced or canceled. + +--- + +## Common selection failures + +**Repurposing every piece.** Treating all pieces as repurposing candidates spreads capacity thin. Most programs benefit from concentrating capacity on 10-20% of pieces and accepting one-and-done for the rest. + +**Repurposing the wrong pieces.** Selecting source pieces because they are easy (recent, fresh in mind) rather than because they are strong source-piece candidates. The selection audit catches this. + +**Ignoring weak-source-piece signals.** Pushing through repurposing on pieces with tightly-integrated argument, list-style structure, or no demand signal produces derivatives that fail. + +**Static tiering.** Pieces tiered at production never get re-tiered based on performance. Strong sleeper pieces never get repurposed; weak flagship pieces consume planned derivative capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The strong vs weak source-piece characteristics, the selection audit, the one-and-done dispositions, the tiering framework, the dynamic-tiering discipline, the common selection failures. + +## Implementation choices that stay internal + +Specific scoring rubrics the team uses to score source pieces. Specific dashboards that surface high-performing pieces for retroactive promotion. Specific calendar templates that allocate repurposing capacity by tier. The team's own thresholds for when a routine piece warrants Tier 2 promotion. These vary by team and program shape. diff --git a/skills/content-repurposing/references/voice-consistency-across-formats.md b/skills/content-repurposing/references/voice-consistency-across-formats.md new file mode 100644 index 0000000..8435836 --- /dev/null +++ b/skills/content-repurposing/references/voice-consistency-across-formats.md @@ -0,0 +1,146 @@ +# Voice consistency across formats + +What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem and the discipline that prevents it. + +Voice is the most visible casualty of careless repurposing. The source piece may have specific voice characteristics; derivatives generated without strong voice discipline drift toward AI-default or platform-default register. Audiences detect the drift even when they cannot articulate it; the cross-format set reads as work from different brands rather than as a coherent program. + +--- + +## What stays constant + +The brand-voice elements that should survive every format adaptation. + +**The brand's POV on the topic.** If the source piece argues a specific position, the derivatives carry the same position. A derivative that hedges where the source committed, or that takes a different angle than the source, breaks the cross-format coherence. + +**Distinctive vocabulary.** Brand-specific terms, framings, and phrasings that signal "this is from this brand." If the source uses a particular word for a concept, derivatives use the same word. If the source has a recognizable phrase, derivatives carry the phrase. + +**Level of conviction or hedging.** Brands have characteristic stance positions. Some brands commit; some hedge thoughtfully; some are confrontational. The derivatives carry the brand's stance pattern even when format conventions might pull toward different stance defaults. + +**Audience-respect register.** Brands address audiences in specific ways: peer-to-peer, expert-to-novice, alongside-the-reader. The register stays consistent across formats; derivatives that suddenly talk down to the audience break voice coherence. + +**Anti-patterns the brand avoids.** If the brand does not use particular framings (motivational filler, generic-content-marketing voice, hype-driven language), derivatives also avoid them. Anti-pattern adherence is part of voice. + +--- + +## What adapts per format + +Voice elements that should adjust to the medium. + +**Sentence length and structure.** Spoken voice differs from written. Email voice differs from blog voice. Social-post voice differs from email voice. The brand's voice characteristics survive through these adaptations, but the surface-level sentence patterns change. + +- Print: medium sentences with occasional layered constructions. +- Email: shorter sentences, more direct address. +- Spoken (podcast, video): conversational rhythm with natural pauses and asides. +- Social: tight phrasing in first lines, paragraph breaks frequent. + +**Density.** Visual formats can carry less per minute than text formats. A short video cannot fit the density of a paragraph; the same point in video form has more breathing room. + +**Conversational vs declarative register.** Podcasts are conversational; whitepapers are declarative. The brand's POV stays the same in both; the framing register adapts. + +**Direct-address frequency.** "You" usage varies by format. Emails often use "you" frequently; whitepapers may use "the reader" or "marketers" more often. The shift is appropriate; pulling email voice into a whitepaper or vice versa would feel off. + +**Visual element usage.** Some formats use visuals heavily (social, video); others rely on text (email, long-form). Voice adapts to whether visuals are doing some of the work. + +--- + +## The voice audit per derivative + +A short framework for verifying voice consistency. + +1. **Read or watch the derivative as if encountering it cold.** Could a reader who knows the brand identify this as the brand's work? If yes, voice is working. +2. **Compare to the source piece.** Does the derivative carry the source's POV, vocabulary, and stance? Where it differs, is the difference appropriate format adaptation or unwanted drift? +3. **Check against the brand's voice anti-patterns.** Is the derivative slipping into framings the brand normally avoids? AI-default voice often slips in through derivatives. +4. **Check sentence-level patterns.** Sentence length, paragraph length, direct-address frequency, vocabulary. Are they format-appropriate but brand-recognizable? +5. **Read aloud (for written derivatives) or read the script (for spoken derivatives).** Does it sound like the brand's voice as the brand would speak it? + +The voice audit is one of the easiest to skip and one of the most consequential. Pieces that pass everything else but fail voice audit damage the cross-format coherence. + +--- + +## The AI-repurposing voice problem + +AI-assisted repurposing is particularly prone to voice drift. + +**The pattern.** The source piece has specific voice characteristics. AI generation of derivatives is asked to "summarize this for LinkedIn" or "turn this into emails." The AI produces derivatives that are technically related to the source but written in AI-default voice rather than the source's distinctive voice. + +**Why it happens.** AI generation regresses to model defaults unless the writer actively pulls it back. Without strong voice prompts, the derivatives sound like the AI's voice using the source's content. Multiple derivatives generated without voice anchor compound the drift; by the tenth derivative the cross-format set has lost the source's voice entirely. + +**The cure.** + +- **Voice guidelines as prompt input.** Every AI generation includes the brand voice guidelines as context. Generic prompts produce generic outputs. +- **Sample text as voice anchor.** Feed the AI 2-3 paragraphs of the source piece in their original voice. AI mimics what it sees more than what it is told. +- **Per-derivative voice review.** Each derivative gets a voice audit. Drift detected gets revision. The audit is non-negotiable. +- **Rewrite the bland.** Any sentence that could appear in any other piece on the topic gets rewritten in voice. Voice lives in the specific. + +See `ai-content-collaboration` for the broader voice-preservation discipline that applies across AI-assisted content workflows. The repurposing-specific application is that voice drift compounds across multiple derivatives in ways that single-piece AI generation does not. + +--- + +## When format conventions pull against brand voice + +Sometimes a format's conventions push toward voice that does not match the brand. + +**LinkedIn motivational tone.** LinkedIn rewards a particular kind of motivational and personal-narrative content. Brands with crisp analytical voice may resist the convention; the right answer is usually to maintain voice rather than to drift into LinkedIn-default motivational tone, even at cost of platform-specific engagement. + +**TikTok's high-energy delivery.** TikTok rewards high-energy short-form delivery. Brands with measured analytical voice may not fit naturally; the right answer may be to skip TikTok rather than to produce content that sounds wrong for the brand. + +**Podcast-host conversational warmth.** Some podcast styles reward warm conversational delivery; a brand with confrontational analytical voice may struggle to produce derivatives that fit. The right answer may be to format-fit (use a different format) or to produce derivatives that hold the brand's voice even at engagement cost. + +**The discipline.** Format-fit decisions are upstream of voice-adaptation decisions. If a format genuinely cannot accommodate the brand's voice, skipping the format is sometimes the right answer; voice integrity matters more than universal cross-format presence. + +--- + +## Voice prompts for AI-assisted repurposing + +When AI generates derivatives, the prompts should carry voice instructions. + +**Components of a voice prompt.** + +- 2-3 paragraphs of the source piece in original voice as anchor. +- A short voice description (3-5 specific characteristics). +- A short anti-pattern list (3-5 framings the brand avoids). +- Per-format adjustments (sentence length, register, direct-address frequency). + +**A worked prompt example pattern.** "The source piece below is in the brand's voice. Convert it into [target format]. The voice characteristics to preserve: [specific characteristics]. The anti-patterns to avoid: [specific anti-patterns]. The format adaptations: [format-specific]. Source piece: [text]." + +The discipline is including the voice instructions in every derivative generation, not assuming the AI will infer voice from the source alone. AI tools differ in how well they infer voice from samples; the safest discipline is explicit voice instruction. + +--- + +## Voice consistency across multiple writers or AI generators + +Programs with multiple writers or AI generators producing derivatives have a multi-source voice drift problem. + +**The risk.** Writer A produces three derivatives in slightly different voice from writer B's four derivatives, plus AI generates two more in default voice. The cross-format set has three voice variants, none of them quite the source's voice. + +**The discipline.** + +- **Single voice owner.** One person reviews all derivatives in the cross-format set for voice consistency. Catches drift across writers. +- **Voice library.** Documented brand voice with examples; all writers and AI generators reference the same library. +- **Calibration sessions.** Periodically, multiple writers (or writers plus the editorial lead) review derivatives together and reconcile voice expectations. + +Programs with sophisticated voice discipline can run multi-writer derivative production without losing voice; programs without discipline produce voice variants that audiences notice. + +--- + +## Common voice failures in repurposing + +**AI-default drift.** Derivatives sound like the AI's voice rather than the brand's voice. Cure: stronger voice prompts; per-derivative review. + +**Platform-default drift.** Derivatives sound like the platform's default register rather than the brand's voice. Cure: voice-over-platform-fit discipline; sometimes skip the platform. + +**Cross-derivative drift.** Each derivative is fine alone but the cross-format set reads as voice variants. Cure: single voice owner across the set. + +**Source-voice loss.** Derivatives carry the source's content but not the source's voice characteristics. Cure: voice anchor with sample text from the source. + +**Voice-only-on-source.** The source piece has voice; the derivatives default to generic. Cure: voice discipline applies to derivatives, not just to the source. + +--- + +## Methodology-level choices that stay in the public skill + +The constant-vs-adapting voice elements, the voice audit, the AI-repurposing voice problem and its cure, the format-vs-voice tension, the multi-writer voice discipline, the common voice failures. + +## Implementation choices that stay internal + +Specific voice-prompt templates per AI tool. Specific voice-library documentation in the team's writing system. Specific calibration session formats. Specific reviewer dashboards that surface cross-derivative voice variation. The team's own conventions for voice-vs-format tradeoffs. These vary by team, AI tooling, and brand voice maturity. diff --git a/skills/content-strategy/SKILL.md b/skills/content-strategy/SKILL.md new file mode 100644 index 0000000..dce5d9e --- /dev/null +++ b/skills/content-strategy/SKILL.md @@ -0,0 +1,211 @@ +--- +name: content-strategy +description: "Develop a content strategy covering editorial positioning, content pillars, formats, calendar, governance, and topical authority planning. Use this skill whenever the user wants to plan a content program, define content pillars, build an editorial calendar, structure topic clusters, set up content governance, or align content production with broader brand and SEO goals. Triggers on content strategy, content plan, editorial strategy, content pillars, content calendar, editorial calendar, topical authority, topic clusters, content governance, content roadmap, content production. Also triggers when the user is about to start producing content without a strategic plan." +category: strategy-and-discovery +catalog_summary: "Editorial strategy, content calendar, topical authority planning" +display_order: 5 +--- + +# Content Strategy + +Plan what content to produce, why, when, and how. Stack-agnostic. Works for blogs, knowledge bases, marketing sites, newsletters, and product content surfaces. + +This skill is the strategic layer. Tactical execution sits in `content-and-copy`, `landing-page-copy`, and `email-sequences`. SEO-driven content planning sits in `seo-keyword`. This skill stitches those together into a coherent program. + +--- + +## When to use + +- Planning a new content program or relaunching an existing one +- Defining editorial positioning and content pillars +- Building an editorial calendar +- Structuring topic clusters and content hubs +- Establishing content governance (review, approval, lifecycle) +- Aligning content with broader brand and revenue goals + +## When NOT to use + +- Writing specific content pieces (use `content-and-copy`) +- Writing landing pages or sales copy (use `landing-page-copy`) +- Writing email sequences (use `email-sequences`) +- Pure keyword research (use `seo-keyword`, then return here for strategic planning) +- Auditing existing content for keep/update/delete decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- Brand positioning and audience (from `brand-discovery` or `creative-brief`) +- Business goals the content needs to serve (traffic, leads, brand authority, retention) +- Existing content inventory (if any) +- Keyword research output (from `seo-keyword`) if SEO-driven +- Production capacity (writers, budget, cadence) + +If brand positioning is unclear, run `brand-discovery` first. If audience is undefined, do that work before strategy. + +--- + +## The framework: 5 layers + +A content strategy has five layers. Skip layers and the program drifts. + +### 1. Editorial positioning + +What this content program stands for. The "why we write" statement. + +**Components:** +- **Mission.** Why this content exists. One sentence. +- **Audience.** Who it serves. Specific. +- **Promise.** What readers get from us they cannot get elsewhere. +- **Distinction.** What makes this content different from the 50 other publications in the same space. + +**Example structure:** + +> We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +A strong editorial positioning forces choices. If you cannot complete the sentence, the positioning is too vague. + +### 2. Content pillars + +The 3 to 5 themes the program owns. Every piece of content belongs to a pillar. + +**Per pillar, define:** +- **Theme.** One sentence describing the topic territory. +- **Why we own it.** Audience need + brand authority + competitive opportunity. +- **Sub-topics.** 5 to 15 sub-topics that fit under the pillar. +- **Cornerstone content.** The 1 to 2 pieces that anchor the pillar (long-form, comprehensive, link-worthy). +- **Supporting content.** Articles, videos, tools, comparisons that reinforce and link to the cornerstone. + +**Pillar selection criteria:** +- Audience cares about it (research-backed, not assumed) +- Brand has credibility or can earn it +- Topical authority is achievable (you can plausibly become a top-3 source) +- Connects to revenue (directly or indirectly) +- Distinguishes you from competitors + +3 to 5 pillars is the sweet spot. Fewer than 3 risks brittleness. More than 5 dilutes focus. + +### 3. Content formats and types + +The shapes the content takes. + +**Format dimensions:** + +- **Length.** Short (under 500 words), medium (500 to 1500), long (1500 to 3000), epic (3000+) +- **Depth.** Surface (overview) vs. deep (comprehensive) +- **Type.** Article, guide, comparison, listicle, case study, interview, data study, tool, video, podcast, newsletter, social +- **Originality.** Aggregation (summarizing existing knowledge) vs. original research (new data or insight) +- **Evergreen vs. timely.** Lasting value vs. moment-driven + +**Format selection criteria:** + +- Match the audience's preferred consumption (do they read, watch, listen?) +- Match the topic (some topics demand depth; others demand brevity) +- Match production capacity +- Match distribution channels (LinkedIn favors short; YouTube favors video; SEO favors long evergreen) + +A content program typically has 3 to 5 formats it returns to consistently. More than that fragments production and brand recognition. + +### 4. Editorial calendar + +When content publishes. + +**Cadence options:** + +- **High frequency** (3+ pieces per week): builds momentum, requires significant production capacity +- **Medium frequency** (1 to 2 per week): sustainable for most teams, builds steady audience +- **Low frequency** (1 to 4 per month): each piece must be high-impact; longer production cycles +- **Burst-then-pause** (10 pieces in a month, then 3 months off): launches and campaigns + +**Calendar structure:** + +- **Pillar rotation.** If you have 4 pillars and publish weekly, each pillar gets one piece per month. +- **Content type mix.** Within a month, blend types (e.g., 2 articles + 1 case study + 1 video). +- **Timely opportunities.** Reserve flex slots for newsjacking, seasonal content, launches. +- **Updates and refreshes.** Plan time for updating existing high-performing content. + +**Common failure:** publishing whatever happens to get written. Without a calendar, the program drifts toward the topics easiest to write, not the ones the audience needs most. + +### 5. Governance and lifecycle + +How content gets made, reviewed, published, measured, and retired. + +**Production workflow:** + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +**Per stage, define:** + +- Who owns it +- What inputs they need +- What outputs they produce +- What the quality bar is +- How long it should take + +**Roles:** + +- **Editorial lead.** Owns positioning, calendar, quality bar. +- **Writers.** Produce drafts. May be in-house, freelance, or AI-assisted. +- **Subject matter experts.** Provide expertise, review for accuracy. +- **Editors.** Polish, ensure voice consistency, fact-check. +- **SEO lead.** Keyword optimization, internal linking, schema. +- **Publishers.** Ship the content (CMS, scheduling, distribution). + +**Lifecycle decisions:** + +- **Update cadence.** Top-performing evergreen content reviewed every 6 to 12 months. +- **Retire criteria.** Content that no longer serves the audience or hurts the site (use `seo-content-audit`). +- **Republishing.** Updated content republished as fresh, not buried as an update. + +--- + +## Workflow + +1. **Confirm inputs.** Brand positioning, audience, business goals, capacity. If any are missing, surface that first. +2. **Draft editorial positioning.** Mission, audience, promise, distinction. Stress-test the positioning by trying to complete the "We help X" sentence. +3. **Define content pillars.** 3 to 5. Each with a theme, justification, sub-topics, and planned cornerstone content. +4. **Choose formats.** 3 to 5 formats the program returns to consistently. +5. **Build the calendar.** Cadence, pillar rotation, format mix, flex slots. +6. **Set up governance.** Roles, workflow, quality bar, lifecycle rules. +7. **Document.** Use the template in [`references/content-strategy-template.md`](references/content-strategy-template.md). +8. **Operationalize.** Set up the editorial calendar in whatever tool the team uses (CMS, Notion, Airtable, etc.). + +--- + +## Failure patterns + +- **Strategy without capacity.** A 3-piece-per-week plan with one part-time writer fails. Match strategy to actual production capacity. +- **Pillars chosen for SEO alone.** Pillars must serve the audience and the brand, not just keyword opportunity. SEO is a downstream filter, not the strategy itself. +- **Too many pillars.** 7 pillars dilute the brand. The audience cannot remember what you stand for. +- **Calendar without governance.** Content gets produced but quality drifts. Without a quality bar, the program loses authority. +- **No update plan.** Top-performing content goes stale. Competitors with fresher versions overtake. +- **Vanity metrics.** Pageviews and follower counts without conversion tracking. Define what success looks like in business terms. +- **Strategy that lives in a doc.** A strategy document that doesn't translate to the editorial calendar and the production workflow is decoration. Operationalize or it doesn't exist. + +--- + +## Output format + +Default output is a strategy document at `content-strategy.md` plus an editorial calendar in whatever tool the team uses. + +Strategy document structure: +1. Editorial positioning +2. Content pillars (3 to 5, each detailed) +3. Formats +4. Calendar (cadence and structure, not the specific items) +5. Governance (roles, workflow, lifecycle) +6. Measurement plan (metrics, review cadence) +7. Production capacity and budget + +Editorial calendar (separate, ongoing): +- One row per planned content piece +- Columns for: title, pillar, format, target keyword (if SEO-driven), publish date, owner, status + +--- + +## Reference files + +- [`references/content-strategy-template.md`](references/content-strategy-template.md) - Strategy document template. +- [`references/editorial-calendar-template.md`](references/editorial-calendar-template.md) - Spreadsheet column definitions and calendar structure. diff --git a/skills/content-strategy/references/content-strategy-template.md b/skills/content-strategy/references/content-strategy-template.md new file mode 100644 index 0000000..2cee093 --- /dev/null +++ b/skills/content-strategy/references/content-strategy-template.md @@ -0,0 +1,259 @@ +# Content Strategy: [Brand or Site Name] + +**Version:** [X.Y] +**Last updated:** [YYYY-MM-DD] +**Owner:** [Editorial lead] +**Review cadence:** [Quarterly / Annually] + +--- + +## Editorial positioning + +### Mission + +[One sentence. Why this content program exists.] + +### Audience + +**Primary:** +[Specific audience segment with the depth of detail your discovery work earned.] + +**Secondary:** +[Additional segments, if any.] + +**Anti-personas:** +[Who this content is NOT for.] + +### Promise + +[What readers get from us that they cannot get elsewhere. One paragraph.] + +### Distinction + +We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +--- + +## Content pillars + +### Pillar 1: [Pillar name] + +- **Theme:** [One sentence] +- **Why we own it:** + - Audience need: [Specific need] + - Brand authority: [Why we're credible] + - Competitive opportunity: [Why this is winnable] +- **Sub-topics** (5 to 15): + - [Sub-topic] + - [Sub-topic] + - [Sub-topic] +- **Cornerstone content** (the 1 to 2 pieces that anchor this pillar): + - [Title or working title] + - [Title or working title] +- **Supporting content** (article types that link back to cornerstone): + - [Type and quantity, e.g., "5 deep-dive articles per quarter"] + +### Pillar 2: [Pillar name] +[Same structure] + +### Pillar 3: [Pillar name] +[Same structure] + +[Continue for all pillars; aim for 3 to 5] + +--- + +## Formats + +The program returns to these formats consistently. + +### Format 1: [Name, e.g., "In-depth guides"] +- **Description:** [What it is] +- **Length:** [Word count or duration range] +- **Cadence:** [How often we produce one] +- **Use case:** [When this format wins] + +### Format 2: [Name] +[Same structure] + +### Format 3: [Name] +[Same structure] + +[Continue for all formats; aim for 3 to 5] + +--- + +## Editorial calendar structure + +### Cadence + +**Frequency:** [N pieces per week/month] + +**Reasoning:** [Why this cadence; what it can sustainably support] + +### Pillar rotation + +[How pillars rotate through the calendar. Example: 4 pillars, weekly publishing, each pillar gets one piece per month.] + +### Format mix + +[Within a typical month, what's the format breakdown?] + +Example: +- 2 articles +- 1 case study or interview +- 1 longer guide or data study +- Plus: 1 newsletter (ongoing, separate cadence) + +### Flex slots + +[How much of the calendar is reserved for timely content, news jacking, or campaign launches?] + +Typical: 70% planned, 20% flex, 10% updates to existing content. + +### Updates and refreshes + +[Plan for refreshing top-performing content. Typically every 6 to 12 months for evergreen pillars.] + +--- + +## Governance + +### Roles + +| Role | Owner | Responsibility | +|---|---|---| +| Editorial lead | [Name] | Strategy, calendar, quality bar | +| Writer (in-house or freelance) | [Name(s) or agency] | Drafts | +| Subject matter expert | [Name(s)] | Expertise, accuracy review | +| Editor | [Name] | Polish, voice consistency, fact-check | +| SEO lead | [Name] | Keyword optimization, internal linking, schema | +| Publisher | [Name] | CMS publication, scheduling, distribution | + +### Production workflow + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +| Stage | Owner | Inputs | Outputs | Quality bar | Time estimate | +|---|---|---|---|---|---| +| Idea | | | | | | +| Brief | | | | | | +| Outline | | | | | | +| Draft | | | | | | +| Edit | | | | | | +| Review | | | | | | +| Publish | | | | | | +| Measure | | | | | | +| Update or retire | | | | | | + +### Quality bar + +Every piece of published content meets these standards: +- [ ] Aligned with a defined content pillar +- [ ] Targets a specific audience need +- [ ] Voice and tone consistent with brand standards +- [ ] Factually accurate (sources cited where appropriate) +- [ ] SEO basics handled (title, meta, headers, internal links) +- [ ] Schema applied for the content type +- [ ] Edited by someone other than the writer +- [ ] Reviewed by the editorial lead + +### Lifecycle rules + +- **Update trigger:** A top-performing evergreen piece reviewed when [trigger, e.g., "stats are 12 months old" or "competitive landscape shifts"] +- **Retire trigger:** A piece is retired (deleted, redirected, or merged) when [trigger, e.g., "no traffic for 12 months and no backlinks"] +- **See also:** `seo-content-audit` for the keep/update/merge/redirect/delete framework + +--- + +## Measurement plan + +### Primary metrics + +| Metric | Target | Reporting cadence | +|---|---|---| +| Organic traffic | | Monthly | +| Email subscribers | | Monthly | +| Conversions from content | | Monthly | +| [Custom metric] | | | + +### Secondary metrics (signals) + +- Engaged sessions (sessions over 60 seconds) +- Scroll depth on long-form content +- Internal click-through from articles to commercial pages +- Backlinks earned per piece +- Time on page distribution +- Returning reader rate + +### Review cadence + +- **Weekly:** Calendar status check +- **Monthly:** Performance metrics review, calendar adjustments +- **Quarterly:** Strategy review, pillar performance, capacity check +- **Annually:** Full strategy refresh, audience research re-validation + +--- + +## Production capacity and budget + +### Capacity + +- Writers: [number, FTE or freelance, hours per week] +- Editors: [number, hours per week] +- Subject matter experts: [availability] +- Designers/illustrators (if needed): [availability] + +### Budget + +- Internal labor: [budget] +- Freelance writers: [per piece or per month] +- Subject matter expert honoraria (if external): [per piece] +- Imagery, illustration, video: [per piece or monthly] +- Tools and platforms: [monthly] + +### Output capacity at this budget + +[Realistic monthly output given the budget. Better to plan conservatively and exceed it than over-promise and under-deliver.] + +--- + +## Distribution + +Content does not earn its audience by being published. List the distribution channels and the standard process for promoting each piece. + +### Channels + +- Owned: site, email, social profiles +- Earned: PR, partnerships, expert mentions +- Paid (if budget): boosted social, sponsored newsletter slots + +### Per-piece distribution checklist + +When a new piece publishes: + +- [ ] Posted to social channels with [N] variations +- [ ] Included in next newsletter +- [ ] Sent to relevant internal stakeholders for sharing +- [ ] Outreach to [N] external mentions or backlink targets +- [ ] Submitted to relevant communities (forums, niche aggregators) +- [ ] Internal link added from [related cornerstone content] + +--- + +## Open questions + +[Things that still need to be decided before this strategy is fully operational.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Version history + +| Version | Date | Changes | +|---|---|---| +| 1.0 | YYYY-MM-DD | Initial strategy | diff --git a/skills/content-strategy/references/editorial-calendar-template.md b/skills/content-strategy/references/editorial-calendar-template.md new file mode 100644 index 0000000..15509c3 --- /dev/null +++ b/skills/content-strategy/references/editorial-calendar-template.md @@ -0,0 +1,214 @@ +# Editorial Calendar Template + +A spreadsheet column definition and calendar structure for content planning. Use as a setup spec for a new editorial calendar in any tool (Sheets, Airtable, Notion, Linear, Asana). + +The calendar is not the strategy. The calendar is the strategy made operational. If a strategy decision is missing, the calendar will reveal it. + +--- + +## Calendar structure + +### Single source of truth + +The editorial calendar is one document. Not five. If the team uses multiple tools (writing in Notion, scheduling in Buffer, etc.), one tool is the source of truth and the others mirror it. + +The source of truth answers, at a glance: + +- What is being published this week? +- What is in production right now? +- What is committed for the next quarter? +- What is the backlog? +- Who owns each piece? + +--- + +## Required columns + +Every row is one piece of content. Every column below is required. + +| Column | Type | Description | +|---|---|---| +| **ID** | Text or auto-number | Unique identifier per piece. Used in cross-references. | +| **Title (working)** | Text | Working title. Final title can change at publish. | +| **Type** | Pick list | Article / guide / case study / video / podcast / email / social series / landing page / etc. | +| **Topic cluster** | Pick list | Which content cluster this piece belongs to (from the strategy doc). | +| **Stage of funnel** | Pick list | Awareness / Consideration / Decision / Retention / Advocacy. | +| **Primary audience** | Pick list | Maps to defined segments. | +| **Primary keyword** | Text | The query target if SEO-relevant. | +| **Search intent** | Pick list | Informational / commercial / navigational / transactional. (See `seo-keyword/references/intent-classification-guide.md`.) | +| **Primary CTA** | Text | What action should the reader take? | +| **Channels** | Multi-select | Web, email, organic social, paid, partnerships. | +| **Owner (writer)** | Person | Who drafts. | +| **Editor** | Person | Who reviews. | +| **Reviewer (SME)** | Person | Subject matter expert if needed. | +| **Approver** | Person | Who signs off before publish. | +| **Status** | Pick list | See status workflow below. | +| **Brief due date** | Date | When the brief should be ready. | +| **Draft due date** | Date | When the draft should be ready. | +| **Edit due date** | Date | When edits should be done. | +| **Publish date (target)** | Date | The intended publish date. | +| **Publish date (actual)** | Date | When it actually went live. | +| **Brief link** | URL | Link to the content brief document. | +| **Draft link** | URL | Link to the working draft. | +| **Final link** | URL | Live URL after publish. | +| **Performance notes** | Text | Updated 30 / 60 / 90 days post-publish. | + +--- + +## Optional but recommended columns + +| Column | Description | +|---|---| +| **Estimated effort (hours)** | For capacity planning. | +| **Tag(s)** | Cross-cutting tags beyond cluster (e.g., "originals research," "thought leadership," "evergreen"). | +| **Related pieces** | IDs of companion pieces (series, follow-ups, redirects). | +| **Distribution plan link** | Specific plan for how this piece is amplified post-publish. | +| **Repurpose plan** | What this becomes downstream (newsletter, social cuts, video). | +| **Source / inspiration** | Where the idea came from (data, customer ask, competitor gap, etc.). | +| **Cost** | If freelance or paid placement. | + +--- + +## Status workflow + +Every piece moves through these statuses, in this order. + +| # | Status | Meaning | Exit criteria | +|---|---|---|---| +| 1 | **Idea** | Captured but not committed. | Idea passes the prioritization screen. | +| 2 | **Backlog** | Committed for some future quarter. | Scheduled for a specific quarter. | +| 3 | **Scheduled** | Targeted for a publish week. | Brief assigned. | +| 4 | **In brief** | Brief being written. | Brief approved. | +| 5 | **In draft** | Writer is drafting. | Draft submitted to editor. | +| 6 | **In edit** | Editor reviewing. | Edits accepted by writer. | +| 7 | **In review** | SME and approver reviewing. | All approvals received. | +| 8 | **Ready to publish** | Final, scheduled in CMS. | Publish date arrives. | +| 9 | **Published** | Live. | (Terminal) | +| 10 | **Killed** | Decided not to ship. | (Terminal, with reason recorded) | + +### Why this matters + +If 30 pieces are sitting in "In draft" for 6 weeks, the bottleneck is writers. If 20 are in "In review," the bottleneck is approvers. The calendar exposes pipeline health, not just publish dates. + +--- + +## Calendar views + +The same data, sliced different ways. Each view answers a different question. + +### Calendar view (by week) + +Columns: weeks. Rows: channels (web, email, social). + +Used for: planning rhythm, spotting overlap and gaps. + +### Pipeline view (by status) + +Columns: status. Rows: pieces. + +Used for: identifying bottlenecks. + +### Owner view (by writer / editor) + +Columns: people. Rows: pieces. + +Used for: workload balancing. + +### Cluster view (by topic cluster) + +Columns: clusters. Rows: pieces in pipeline + already published. + +Used for: ensuring topical authority is being built coherently. + +### Funnel view (by funnel stage) + +Columns: stage. Rows: pieces. + +Used for: ensuring balance across funnel. + +### Performance view (post-publish) + +Columns: traffic, conversions, time on page, social shares. Rows: published pieces. + +Used for: retrospective and topic prioritization for next cycle. + +--- + +## Cadence rituals + +The calendar is reviewed on a rhythm. + +| Ritual | Cadence | Attendees | Purpose | +|---|---|---|---| +| **Daily standup** | Daily, 15 min | Editorial team | What is shipping today, blockers. | +| **Weekly editorial planning** | Weekly | Content lead + writers | Confirm next 2 weeks, surface blockers, accept new ideas. | +| **Monthly review** | Monthly | Content team + marketing lead | Look at last month's pipeline, performance, and adjust the next month. | +| **Quarterly planning** | Quarterly | Content team + cross-functional | Plan the next quarter's content based on strategy and last quarter's data. | +| **Annual review** | Annually | All stakeholders | Review the year's themes, performance, and rebuild the strategy. | + +--- + +## Capacity planning + +Use the calendar to plan capacity, not just track output. + +### Throughput math + +- **Available writer time per week:** writers × hours allocated to writing +- **Average effort per piece:** hours from "Idea" to "Ready to publish" +- **Throughput:** available time ÷ effort + +If planned output exceeds throughput, the calendar will reveal it as drift (slipped dates, deferred backlog). + +### Buffer + +Real teams hit 70-80% of planned throughput. Plan to 70%. Treat the remaining 30% as buffer for inevitable surprises (priority shifts, sick days, longer-than-expected reviews). + +--- + +## Backlog management + +The backlog is not a wishlist. It is a curated set of committed-but-not-scheduled ideas. + +- Cap the backlog at 3-6 months of throughput. Beyond that, ideas go stale. +- Re-rank quarterly using the strategy doc's prioritization criteria. +- Kill backlog items that no longer match the strategy. Killing is a feature, not a failure. + +--- + +## Killed pieces + +When a piece is killed, record: + +- Date +- Reason (strategy shifted, owner left, evidence the piece would not perform, redundant with another piece) +- What happens to the brief or partial draft (archive, salvage for another piece, delete) + +Killed pieces inform future filtering. + +--- + +## Performance review + +For every published piece, update the calendar with performance at 30 / 60 / 90 days. Capture: + +- Sessions / pageviews +- Conversion events (CTAs clicked, signups, purchases) +- Time on page or read depth +- Social shares +- Backlinks earned +- Notes on what worked or did not + +Aggregate quarterly to inform the next quarter's plan. + +--- + +## Sign-off + +Calendar setup approved by: + +- Content lead: [Name, date] +- Marketing lead: [Name, date] +- Tooling owner: [Name, date] + +Calendar lives at: [URL] diff --git a/skills/cost-optimization/SKILL.md b/skills/cost-optimization/SKILL.md new file mode 100644 index 0000000..2f44efb --- /dev/null +++ b/skills/cost-optimization/SKILL.md @@ -0,0 +1,339 @@ +--- +name: cost-optimization +description: "Audit and reduce infrastructure and tooling costs without sacrificing reliability or velocity. Use this skill when reviewing monthly cloud or SaaS spend, finding unused resources, rightsizing infrastructure, negotiating vendor contracts, deciding what to consolidate, or planning for budget cuts. Triggers on cost optimization, cloud spend, SaaS spend, rightsizing, unused resources, FinOps, infrastructure audit, vendor consolidation, budget cut, cost review. Also triggers when finance flags rising costs or when a contract renewal is up." +category: cross-cutting +catalog_summary: "Infrastructure spend audits, rightsizing, contract negotiation" +display_order: 5 +--- + +# Cost Optimization + +Audit cloud, SaaS, and infrastructure spend. Cut what's not earning its keep. Rightsize what's oversized. Negotiate what's negotiable. Without breaking what works. + +--- + +## When to use + +- Quarterly or annual cost review +- Finance flags rising spend +- Vendor contract renewal coming up +- Budget cut required +- New leadership wants the numbers +- Migrating between providers (cost is part of the case) +- Audit before scaling significantly (catch waste before it scales) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Performance issues that happen to involve infrastructure (use `performance-optimization`) +- Vendor evaluation for a new purchase (use `vendor-evaluation`) +- Personnel or org costs (out of scope for this skill) + +--- + +## Required inputs + +- Current cost (monthly, ideally for the last 12 months) +- Cost broken down by service or vendor +- Inventory of cloud resources (instances, databases, storage, etc.) +- Inventory of SaaS subscriptions +- Owners per cost line (who decided to spend this, who uses it) +- Constraints (compliance, performance, contract terms) + +--- + +## The framework: 5 levers + +Every cost optimization opportunity falls into one of these levers. + +### Lever 1: Eliminate + +Stop paying for things that aren't used. + +- Idle resources (instances, databases, environments running but unused) +- Subscriptions where no one logs in +- Duplicate tools (multiple tools doing the same job) +- Old projects still incurring cost +- Test environments that should have been torn down +- Forgotten domains, backups, snapshots, logs + +This is usually the largest opportunity in the first audit. Often 10-30% of spend. + +### Lever 2: Rightsize + +Pay for what you actually use, not what you provisioned for the worst case three years ago. + +- Oversized instances (CPU and memory utilization low) +- Over-provisioned databases (storage and throughput far above usage) +- Over-purchased SaaS seats +- Premium plans where standard would suffice +- High-availability setups for non-critical systems + +Rightsizing requires real usage data, not theoretical needs. + +### Lever 3: Restructure + +Use cheaper structures for the same workload. + +- Reserved or committed-use pricing (1-3 year commitments at 30-70% discount) +- Spot or preemptible instances for fault-tolerant work +- Cold storage for data accessed rarely +- Tiered storage (hot/warm/cold) by access pattern +- CDN caching to reduce origin load +- Compression and deduplication +- Serverless for spiky workloads +- Reserved instances for steady workloads + +The right structure depends on the access pattern. Mismatch costs money. + +### Lever 4: Negotiate + +Pay less for the same thing. + +- Annual contracts at lower rates than monthly +- Volume discounts at higher tiers +- Multi-year commitments for predictable workloads +- Bundle deals (consolidating services with one vendor) +- Renewal negotiation (vendors expect you to ask) +- RFP / competitive bid (using alternatives as leverage) + +Most enterprise vendors negotiate. Most SaaS vendors don't, except at higher tiers. Consumer-tier services usually don't. + +### Lever 5: Reframe + +Change the question. + +- Build vs buy: maybe in-house is cheaper at scale +- Buy vs build: maybe outsourcing is cheaper at small scale +- Different architecture (e.g., monolith vs microservices) has different cost profiles +- Different audience (do all customers need the same tier?) +- Different stack (open source vs commercial) + +Reframe is the longest-lead lever. Worth thinking about even if not actionable now. + +--- + +## Workflow + +### Step 1: Pull the spend data + +Get monthly costs by service, vendor, and (where possible) team or project. + +For cloud (AWS, GCP, Azure): the billing console and cost-explorer tools. +For SaaS: each vendor's billing portal, plus an SaaS-management tool if available. +For everything else: bank statements and accounting export. + +12 months minimum. Trends matter as much as absolute numbers. + +### Step 2: Categorize + +Organize spend into categories: + +- **Hosting / compute** +- **Storage** +- **Database** +- **Networking / CDN** +- **Monitoring / observability** +- **Email** +- **CMS / hosting platforms** +- **Analytics / marketing** +- **Productivity / collaboration** +- **Development tools** +- **Security / compliance** +- **Other** + +The categories vary by business. The point is: similar costs grouped, easy to compare. + +### Step 3: Identify the biggest line items + +80/20 rule. Usually 20% of vendors account for 80% of spend. + +Focus the audit on the top 80%. The long tail can be cleaned up but rarely yields big savings per item. + +### Step 4: Apply the 5 levers + +For each major line item, walk the levers: + +| Lever | Question | +|---|---| +| Eliminate | Is it used? Could we stop using it? | +| Rightsize | Are we paying for capacity we don't use? | +| Restructure | Is there a cheaper pricing model or service tier? | +| Negotiate | When was the last renewal? Did we negotiate? | +| Reframe | Is this even the right approach? | + +Document the opportunity, the effort, the risk, and the savings estimate. + +### Step 5: Prioritize + +Plot opportunities on a 2x2: +- Y axis: savings +- X axis: effort + +Quadrants: +- High savings, low effort: do first +- High savings, high effort: plan +- Low savings, low effort: do as time allows +- Low savings, high effort: skip + +Also consider risk: +- Eliminate something used by no one: low risk +- Rightsize a database: medium risk (test in staging first) +- Replace a critical dependency: high risk (plan carefully) + +### Step 6: Execute the easy wins + +For each easy-win opportunity: +- Document the change +- Get owner approval +- Make the change +- Monitor for unexpected impact +- Confirm cost reduction in next billing cycle + +Easy wins typically include: +- Canceling unused subscriptions +- Tearing down idle resources +- Switching off dev environments outside business hours +- Moving cold data to cheaper storage tiers + +### Step 7: Plan the larger work + +For higher-effort opportunities: +- Spec the change (use `pm-spec-writing` for the plan) +- Test in staging +- Roll out incrementally +- Validate cost impact + +Examples: +- Migrating to reserved instances +- Consolidating monitoring vendors +- Migrating from one CMS to another with cost benefit + +### Step 8: Set up ongoing visibility + +Optimization isn't one-time. Costs creep back up. + +- Monthly cost review (at least) +- Cost dashboard (current, trend, by category) +- Alerts on cost spikes (e.g., daily spend exceeds threshold) +- Tagging or labeling on cloud resources (cost by team or project) +- Quarterly deeper review + +### Step 9: Negotiate at renewal + +For vendor contracts up for renewal: +- Start the conversation 60-90 days before renewal +- Have alternatives identified (even if you don't switch) +- Ask for a multi-year discount +- Ask about volume tiers +- Ask if usage rightsizing is possible +- Be willing to walk (most vendors find a way to keep you) + +Pre-pandemic, many vendors auto-renewed at increases. Post-pandemic, many are hungry for retention. Ask. + +### Step 10: Document the policy + +Going forward: +- New vendor evaluation requires cost justification +- Resource provisioning has approval thresholds +- Tagging and labeling are required for cloud resources +- Quarterly review is calendared +- Cost attribution is clear + +Without policy, costs creep. + +--- + +## Common opportunities by category + +### Hosting and compute + +- Reserved or committed-use pricing for predictable workloads (30-70% off) +- Spot or preemptible for fault-tolerant batch +- Auto-scaling for variable loads +- Right instance family (compute-optimized, memory-optimized, etc.) +- Dev/staging instances stopped outside business hours + +### Storage + +- Lifecycle policies to move old data to cheaper tiers +- Delete old logs, backups, snapshots +- Compression for archival +- Object versioning costs (every version is a stored object) + +### Database + +- Right size based on actual CPU/memory usage +- Reserved capacity for predictable workloads +- Read replicas for read-heavy workloads (cheaper than scaling primary) +- Drop unused indexes (indexes cost storage and write performance) +- Old data archived or deleted + +### Networking and CDN + +- CDN reduces origin egress costs (often the biggest cost category) +- Compression on the wire +- Image and video optimization +- Region-aware routing + +### Monitoring and observability + +- Sample logs (don't ingest 100% of high-volume sources) +- Retention policies (do you need 90 days or 30?) +- Consolidate tools where possible +- Free or open-source tooling for non-critical needs + +### SaaS + +- Audit logins per seat (inactive users on $X/seat = $X waste) +- Renegotiate at renewal +- Move to annual billing for the discount +- Consolidate overlapping tools + +--- + +## Failure patterns + +**Cost-cutting that breaks something.** Aggressive rightsizing without testing causes outages. The cost of an outage is usually larger than the savings. + +**Optimization that takes more time than it saves.** A team spends a quarter saving $5K/year. Math doesn't work. Focus on opportunities where savings exceed effort. + +**Renewal autopilot.** Annual renewals go through without review. Calendar them. + +**No tagging.** Cloud spend grows; no one knows whose. Tag everything from day one. + +**Free tier overruns.** "It's on the free tier." Then it's not, and bills surprise. Set alerts on free-tier services. + +**No environment differentiation.** Production-grade staging "to match prod." Costs as much as prod. Often unnecessary. + +**Untouched legacy.** "The old project still runs." Why? Often: nothing actually uses it. Audit and shut down. + +**Premium tiers for non-premium needs.** Enterprise plan because someone wanted a feature that's been since added to lower tiers. Recheck. + +**Vendor lock-in justifying cost.** "We can't switch." That's not a reason to overpay; it's a strategic problem to plan around. + +**Optimizing the small stuff while ignoring the big stuff.** Saving $50/month on tools while $5K/month sits in oversized infrastructure. Top-down first. + +**Penny-wise, pound-foolish.** Cutting a useful tool to save $20/month, then losing hours to manual work. Tools that pay for themselves shouldn't be cut. + +**No reinvestment.** Every dollar saved goes to bottom line; nothing reinvested in upgrades or capacity. Saved costs and improved capability aren't either/or. + +--- + +## Output format + +A cost optimization document includes: + +- **Current state:** total spend, by category, trended +- **Top line items:** the biggest costs +- **Opportunities:** by lever (eliminate / rightsize / restructure / negotiate / reframe) +- **Prioritized list:** with savings, effort, risk +- **Action plan:** owners, dates +- **Easy wins executed:** what's already done, results +- **Ongoing governance:** dashboard, review cadence, tagging, approval thresholds + +--- + +## Reference files + +- [`references/cloud-audit-checklist.md`](references/cloud-audit-checklist.md): A practical walkthrough for auditing a cloud account (compute, storage, database, network, monitoring) for waste and rightsizing opportunities. diff --git a/skills/cost-optimization/references/cloud-audit-checklist.md b/skills/cost-optimization/references/cloud-audit-checklist.md new file mode 100644 index 0000000..1265c60 --- /dev/null +++ b/skills/cost-optimization/references/cloud-audit-checklist.md @@ -0,0 +1,292 @@ +# Cloud Audit Checklist + +A practical walkthrough for auditing a cloud account for waste and rightsizing opportunities. Stack-agnostic in principle; the categories apply across AWS, GCP, Azure, and others. + +Allow about a half-day for a first audit. Subsequent audits go faster. + +--- + +## Setup + +- [ ] Pull the last 12 months of billing data +- [ ] Pull current resource inventory (compute, storage, database, networking) +- [ ] Identify owners per service or project +- [ ] Note any compliance or contractual constraints + +--- + +## Compute + +### Identify idle and underused + +- [ ] Instances with CPU utilization below 10% over 30 days +- [ ] Instances stopped but still incurring some charges (storage, IPs, etc.) +- [ ] Instances running 24/7 that only need business hours +- [ ] Instances forgotten from old projects +- [ ] Instances spun up for a one-time task and never deleted + +For each: identify owner. Confirm it's not needed. Stop or delete. + +### Rightsize active instances + +- [ ] Instances with CPU peaks under 40% (probably oversized) +- [ ] Instances with memory underused +- [ ] Instances of older generation (newer generations often cheaper for same performance) +- [ ] Instances of wrong family (compute-optimized when memory-optimized would be cheaper) + +For each: test smaller size in staging. Roll out gradually. + +### Pricing structure + +- [ ] On-demand instances with stable load (candidates for reserved or savings plans) +- [ ] Workloads that could tolerate interruption (candidates for spot/preemptible) +- [ ] Long-running workloads with no commitment (candidate for committed-use discounts) + +Reserved/committed: 30-70% discount for 1-3 year commitment. +Spot/preemptible: 60-90% discount, can be terminated by provider. + +### Auto-scaling + +- [ ] Auto-scaling configured for variable workloads (vs always-on at peak size) +- [ ] Scaling policies actually scale down (some only scale up) +- [ ] Min size set appropriately (not over-provisioned) + +--- + +## Storage + +### Identify unused + +- [ ] Snapshots not used in 6+ months +- [ ] Disks unattached to any instance +- [ ] Buckets accessed never or rarely (per access logs) +- [ ] Old log archives no one queries +- [ ] Old backups beyond retention requirements + +For each: confirm it's not needed. Delete or archive. + +### Lifecycle policies + +- [ ] Hot data only for recent access +- [ ] Move data to warm tier after [N] days +- [ ] Move to cold/archive tier after [M] days +- [ ] Delete after [P] days (if compliant) + +Lifecycle policies are set-once, save-forever. High ROI for the time invested. + +### Storage class + +- [ ] Verify storage class matches access pattern + - Frequently accessed: standard + - Infrequent: IA / nearline + - Rarely: cold / archive + - Compliance-only: deep archive + +Mismatched storage class is a common waste category. + +### Versioning + +- [ ] Object versioning is on intentionally (not accidentally) +- [ ] Old versions cleaned up via lifecycle policy +- [ ] Soft-delete retention is finite (not indefinite) + +Versioned buckets can accumulate massive cost from old versions. + +--- + +## Database + +### Identify underused + +- [ ] Databases with low CPU/memory usage over 30 days +- [ ] Databases with low connection counts +- [ ] Databases that could be smaller instance class +- [ ] Read replicas no longer needed +- [ ] Databases for old projects + +### Rightsize storage + +- [ ] Storage allocated far above used +- [ ] Auto-scaling on for storage (avoid manual oversizing) +- [ ] Old logs and audit data cleaned up + +### Backup retention + +- [ ] Backup retention matches RPO (not aspirational, not excessive) +- [ ] Manual snapshots cleaned up (often outlive their purpose) + +### Pricing structure + +- [ ] Reserved capacity for steady workloads +- [ ] Spot/preemptible for non-critical analytics + +### Indexes + +- [ ] Unused indexes dropped (each index costs storage and write performance) +- [ ] Indexes match query patterns (use database tooling to identify) + +--- + +## Networking + +### Egress + +Egress (data leaving the cloud or moving across regions) is often the most surprising cost. + +- [ ] Egress to internet (largely user traffic; CDN can reduce) +- [ ] Egress between regions (often unintended; check architecture) +- [ ] Egress between availability zones (matters at scale) +- [ ] NAT gateway charges (per-GB; can be huge for high-traffic egress) + +Reduce egress with: +- CDN caching (origin egress drops dramatically) +- Compression +- Multi-region only when needed (single-region egress is often cheaper) +- VPC endpoints for cloud-internal traffic (avoid going out and back in) + +### Load balancers + +- [ ] Idle or unused load balancers +- [ ] Load balancer count appropriate (don't run 5 when 1 works) +- [ ] Load balancer type matches use (application LB vs network LB; pricing differs) + +### Public IPs + +- [ ] Idle elastic IPs (charged when not attached) +- [ ] Public IPs that should be private + +### CDN + +- [ ] CDN in front of high-traffic origin +- [ ] Cache hit rate measured (low cache hit = wasted CDN, untrained origin) +- [ ] Compression and image optimization on at the CDN + +--- + +## Monitoring and logs + +### Log volume + +- [ ] Logs ingested but never queried +- [ ] Verbose logging in production (debug level by accident) +- [ ] Logs from low-importance services at full volume + +Sample or filter where possible. High-volume logs can dominate observability bills. + +### Retention + +- [ ] Retention matches need (do you query 90-day-old logs?) +- [ ] Compliance retention separate from operational retention (compliance can use cheaper storage) +- [ ] Aggregated metrics retained longer than raw logs (cheaper, often sufficient) + +### Tooling + +- [ ] Multiple monitoring tools doing the same job +- [ ] Premium tier when standard would suffice +- [ ] Per-host pricing on tools where utilization is low + +--- + +## Specialty services + +### Search (Elasticsearch, Algolia, etc.) + +- [ ] Indexes for old data still queried? +- [ ] Replicas appropriate for traffic +- [ ] Tier matches need + +### Cache (Redis, Memcached) + +- [ ] Cache hit rate measured (low hit = expensive cache delivering little value) +- [ ] Cache size appropriate +- [ ] TTLs reasonable + +### Queue / streaming (Kafka, Kinesis, SQS) + +- [ ] Throughput matches actual load +- [ ] Retention matches need +- [ ] Idle streams or topics cleaned up + +### Email / SMS / push + +- [ ] Volume matches projection +- [ ] Per-message pricing tier appropriate +- [ ] Old or low-engagement contacts removed (don't pay to send to non-recipients) + +--- + +## Account-level + +### Multiple accounts + +- [ ] Account count matches need (separation of concerns is good; sprawl is wasteful) +- [ ] Consolidated billing enabled (volume discounts across accounts) +- [ ] Inactive accounts decommissioned + +### Tagging + +- [ ] Tags applied to all resources +- [ ] Tags consistent (team, project, environment, cost center) +- [ ] Untagged resources have owners identified + +### Budgets and alerts + +- [ ] Budget alerts configured (e.g., alert at 80% of monthly target) +- [ ] Anomaly detection enabled (alert on unusual cost spikes) +- [ ] Per-team or per-project budgets where possible + +--- + +## Findings document + +For each finding, capture: + +| Field | Example | +|---|---| +| Description | "Production database is 8xlarge; CPU peaks at 25%" | +| Category | Compute / storage / database / network / etc. | +| Lever | Eliminate / rightsize / restructure / negotiate / reframe | +| Estimated savings | $/month | +| Effort | Hours/days | +| Risk | Low / medium / high | +| Owner | Person or team | +| Action | Specific next step | + +--- + +## Prioritization + +After all findings: + +| Priority | Description | +|---|---| +| P0 | Easy, high savings, low risk: do this week | +| P1 | Medium effort, high savings: plan this quarter | +| P2 | Easy, low savings: do as time allows | +| P3 | High effort, low savings: deprioritize | + +Reserved instances and committed-use discounts often appear as P0/P1: high savings, structured effort. + +--- + +## Tracking + +After acting, track: +- Savings achieved (compare next billing cycle to baseline) +- Issues caused (any rollbacks needed?) +- Time spent +- Lessons for next audit + +Cost reductions sometimes appear gradually (e.g., reserved purchase smooths in). Track over 2-3 billing cycles. + +--- + +## Maintenance + +- [ ] Set monthly cost review (15-30 min, look at trends) +- [ ] Set quarterly deeper audit (this checklist, abbreviated) +- [ ] Set annual full audit (this checklist, full) +- [ ] Set renewal calendar (each major contract, with reminder 90 days out) +- [ ] Tag governance (new resources require tags, untagged flagged) + +Cost optimization is ongoing, not one-time. Without maintenance, savings reverse. diff --git a/skills/creative-brief-selector/SKILL.md b/skills/creative-brief-selector/SKILL.md new file mode 100644 index 0000000..64d4a99 --- /dev/null +++ b/skills/creative-brief-selector/SKILL.md @@ -0,0 +1,112 @@ +--- +name: creative-brief-selector +description: "Produce a creative brief grounded in live reference sites and deliberately distinct from existing demos, for any new brand build. Composes with brand-archetype-system and creative-direction. Use this skill at the start of any brand or microsite build when the result needs to land in a specific aesthetic position and not drift into a default house style. Triggers on creative brief, design brief, build brief, brand direction, where should this brand sit, what should this site look like, reference sites for, archetype for, distinct from our other brands, divergence from prior, not the same as. Also triggers when prior builds have come out as siblings and a systematic divergence approach is needed." +category: brand +catalog_summary: "Live-reference-grounded creative briefs with divergence check against prior builds" +display_order: 6 +--- + +# Creative Brief Selector + +A starting-point selector for brand and microsite builds. Given a business spec (name, vertical, shape, one-line vibe, optional list of shipped demos), produces a creative brief grounded in three things: + +1. An archetype position from `brand-archetype-system`, picked or composed to be deliberately distinct from the shipped demos. +2. A small set of live reference sites for that archetype-and-vertical combination, drawn from a curated bank plus optional per-build discovery. +3. A divergence check against the shipped demos that flags palette, voice, structural pattern, and section-shape overlap before the brief is handed off. + +The brief output is concrete tokens, not abstract families, including explicit section-shape choices (hero shape and footer shape) as first-class outputs alongside palette and voice. It is meant to be loaded by downstream build skills as the single creative artifact for the build. + +--- + +## When to use + +- Starting any new brand or microsite build that should land in a specific aesthetic position. +- The first build in a portfolio (no prior builds to diverge from yet, but the divergence schema can be seeded for the next one). +- The second through nth build in a portfolio, where the risk of sibling output is real. +- After a portfolio audit that surfaced sibling builds: this skill is the systemic fix for the pattern. +- When a build's creative direction is being chosen between two adjacent archetypes and the call needs a reference-grounded reason. + +## When NOT to use + +- The user wants pure aesthetic methodology guidance (use `creative-direction`). +- The user has a finished archetype and a finished brief and is asking for execution (skip to the downstream build skills). +- The user wants a logo or a finished identity (use `logo-design`, `brand-identity`). +- The user wants to define voice for an existing brand (use `brand-voice`). +- Defining brand strategy from zero positioning (use `brand-ideation` first, then return to this skill). + +--- + +## How this composes with other skills + +This skill works upstream of build-time skills and parallel to the aesthetic methodology layer: + +- **`brand-archetype-system`** (upstream input). The archetype catalog this skill picks from. The skill names the archetype in the rendered brief; it does not redefine the archetype's defaults. +- **`creative-direction`** (parallel input). The four-axis vocabulary the archetypes reference. If the consumer needs the full axis brief, run `creative-direction` first; this skill's brief consumes its outputs. +- **`brand-identity`** (downstream). Once the brief is approved, brand-identity turns it into a finished identity system. +- **`landing-page-copy`, `content-and-copy`, `art-direction`** (downstream). Every downstream skill that produces aesthetic output references this skill's brief. + +Direct verbatim copying of an archetype's default palette into a new brand is the failure mode this skill exists to prevent. The brief shifts the archetype's defaults toward the business spec's specifics. + +--- + +## The framework: five steps, three rules, one hybrid bank + +1. **Locate the design space.** Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. +2. **Run input-side divergence.** Read the shipped-demos signatures. Discard candidates that would land sibling to anything shipped. Record what was rejected and why. +3. **Pull references.** From the curated reference bank under `references/reference-bank/`, load the file(s) matching the chosen archetype-and-vertical. Augment with one to two discovered live references if the bank is sparse. Add discovered references back to the bank in the build PR. +4. **Adapt.** Shift the chosen archetype's defaults (palette, type, voice, layout, imagery direction) toward the business spec. The brief lands as concrete tokens, not abstract families. +5. **Render and verify.** Render the brief using the template in [`references/02-brief-template.md`](references/02-brief-template.md). Run output-side divergence. Output the brief plus the references list plus the divergence-check result. + +Full step-by-step in [`references/01-process.md`](references/01-process.md). The divergence schema and its three overlap rules are in [`references/03-divergence-check.md`](references/03-divergence-check.md). + +--- + +## The hybrid references model + +A curated bank that grows with each build. Each file under `references/reference-bank/` covers one archetype-and-vertical combination and holds three to six live reference URLs, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations covering western-boot maker, heritage barbershop, and balloon-ride experience. + +When a build draws from a sparse combination, the build is expected to commit the live references it discovered back to the bank as part of its build PR. The bank gets denser with use. + +--- + +## The divergence schema + +Each shipped demo carries a signature with seven fields: + +- `slug` +- `archetype` (the canonical archetype name from `brand-archetype-system`) +- `dominant_hue_family` (the recognizable colour family, e.g. leather-bone-saddle, dawn-navy-coral, dark-linen-amber) +- `voice_register` (e.g. story-forward third-person, atmospheric second-person, fitment-first technical) +- `primary_structural_pattern` (e.g. shoppable-grid-product-forward, arc-timeline-hero, fitment-selector-then-rails) +- `hero_shape` (e.g. dual-column-image-and-text, wide-photograph-with-band-below, full-bleed-image-with-overlay; canonical vocabulary in `references/05-section-shapes-vocabulary.md`) +- `footer_shape` (e.g. single-line-strip, multi-column-sitemap, type-only-no-links; same vocabulary file) + +Overlap rules (full set in [`references/03-divergence-check.md`](references/03-divergence-check.md)): + +- Two demos share archetype AND share dominant_hue_family => **SIBLING (block)**. +- Two demos share archetype AND share voice_register AND share primary_structural_pattern => **SIBLING (block)**. +- Two demos share only dominant_hue_family across different archetypes => **WARN**. +- The candidate's hero_shape matches the hero_shape of two or more shipped demos => **WARN**. +- The candidate's hero_shape matches three or more shipped demos AND any share an archetype family => **BLOCK**. +- The candidate's footer_shape matches three or more shipped demos => **WARN**. + +A worked example file of seven signatures lives at [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) for illustration; the live signatures file for any consuming project lives in that project, not in this skill. + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands, following the convention of `brand-archetype-system`. Live reference sites are cited as exemplars using nominative attribution language: "exemplified by [URL]", "characteristic of", "in the register of". This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## Reference files + +- [`references/00-overview.md`](references/00-overview.md) - The case for the skill, the hybrid references model, the two-direction divergence, the trademark posture. +- [`references/01-process.md`](references/01-process.md) - The five-step process, each step concrete enough to execute. +- [`references/02-brief-template.md`](references/02-brief-template.md) - The fillable brief template with section-by-section guidance. +- [`references/03-divergence-check.md`](references/03-divergence-check.md) - The signature schema and the overlap rules. +- [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) - Worked example signatures file with seven demos. +- [`references/05-section-shapes-vocabulary.md`](references/05-section-shapes-vocabulary.md) - Canonical open vocabulary of hero and footer section shapes plus archetype affinities. + +The curated reference bank lives in a `reference-bank/` subdirectory under `references/`. The bank ships with a README plus three seed archetype-and-vertical files: `premium-dtc-maker-western-boots.md`, `heritage-local-service-barbershop.md`, and `hospitality-experience-balloon-ride.md`. The bank's purpose and extension procedure are documented in its README; the seed files each carry three to four positive live references and one to two negative references for the chosen position. Load the bank file matching the build's archetype-and-vertical at step 3 of the process. diff --git a/skills/creative-brief-selector/references/00-overview.md b/skills/creative-brief-selector/references/00-overview.md new file mode 100644 index 0000000..337ea91 --- /dev/null +++ b/skills/creative-brief-selector/references/00-overview.md @@ -0,0 +1,79 @@ +# Overview + +The case for the skill, the references model, and the trademark posture. + +--- + +## The problem this skill exists for + +Portfolios of brand work drift toward house style. The first demo establishes a default; the second demo borrows it; the third has the same skeleton with a different name. Without a deliberate intervention at brief time, every new build leans on the same palette, the same micro-label tracking, the same hero gradient, the same voice register. The output is competent and sibling. + +This pattern is observable in any portfolio that has shipped more than two builds. The symptoms show up at the imagery stage, when a stone-and-amber palette that worked for one shape suddenly reads as the brand's signature across three shapes that should not share a signature. The fix is upstream: pick the position before the build starts, and verify it stays distinct as the build renders. + +This skill is the deliberate creative direction at brief time. + +--- + +## The hybrid references model + +Two parts: + +### The curated bank + +Files under `reference-bank/`, one per archetype-and-vertical combination. Each file holds three to six live reference URLs that exemplify the position, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations and grows as new combinations are built against. + +The bank is the institutional memory of the portfolio. A new build for an archetype-and-vertical combination that has been done before loads the existing references and adapts. A new build for a sparse combination supplies new references during discovery and commits them back as part of its build PR. + +### Per-build discovery + +When the bank is sparse for a chosen combination, the build's first pass searches the live web for three to six exemplars. Curation rules are in [`reference-bank/README.md`](reference-bank/README.md). The discovered references serve the current build and seed the bank for future builds in the same combination. + +This is not a static reference list. The bank is supposed to drift over time as the portfolio grows; the discipline is that the bank reflects what was actually used in real builds. + +--- + +## The two-direction divergence check + +The skill runs divergence twice: once on input, once on output. + +### Input-side divergence + +Before any references are pulled, the skill loads the shipped-demos signatures file (a project artifact, not part of this skill; see [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md) for the illustrative format). Candidate archetypes are checked against the signatures. If a candidate would land sibling to a shipped demo, it is discarded and the rejection is recorded. + +The rejection record is itself useful output: it documents what the build was deliberately NOT. + +### Output-side divergence + +After the brief is rendered, the skill computes the brief's own signature (archetype, dominant hue family, voice register, primary structural pattern) and compares against the shipped signatures one more time. This catches adaptations that drifted back toward sibling territory during step 4 (the adapt step). + +The check produces one of three outcomes: `passed`, `warn-with-reasons`, or `block-with-reasons`. A `block` result means the brief cannot ship in its current form and needs adaptation before the next attempt. + +--- + +## Why two directions + +Input-side alone catches the obvious overlaps: picking an archetype that another demo already uses with the same palette family. Output-side catches the subtle drift: an archetype was picked clean of any sibling demo, but during adaptation the palette quietly converged on the recurring house family. + +The recurring stone-and-amber family is the worked example of this drift. The first build picked it intentionally; the second build adopted it because it was in the air; the third build adopted it because it felt like the brand. Without an output-side check, the brief itself becomes the carrier of the drift. + +--- + +## Trademark and attribution + +This skill follows the `brand-archetype-system` convention. Archetypes are named for aesthetic families ("Premium DTC Maker," "Heritage Local Service") not for brands. Live reference sites are cited as exemplars using nominative attribution language: + +- "exemplified by [URL]" +- "characteristic of [URLs]" +- "in the register of [URL]" + +This is descriptive and nominative fair use. A reference that pivots its identity does not invalidate the archetype it once exemplified, but it should be removed from the bank when the URL no longer shows what it was cited for. + +--- + +## What this skill is not + +- **Not a logo designer.** The brief includes a logo direction note ("type-led wordmark with a saddle-tan rule," "graphic mark in the dawn palette") but does not produce the mark itself. +- **Not an identity system.** The brief is the input to `brand-identity`, which produces the system. +- **Not a finished design.** The brief describes tokens; it does not lay them out into a finished page. +- **Not a positioning exercise.** The business spec is assumed to have positioning already. If positioning is open, run `brand-ideation` first. +- **Not a taste machine.** A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. Taste is upstream of this skill. diff --git a/skills/creative-brief-selector/references/01-process.md b/skills/creative-brief-selector/references/01-process.md new file mode 100644 index 0000000..95c441e --- /dev/null +++ b/skills/creative-brief-selector/references/01-process.md @@ -0,0 +1,143 @@ +# The five-step process + +Each step concrete enough to execute. Run in order. Do not skip the divergence steps. + +--- + +## Inputs + +The skill takes a business spec: + +- **Name** (the brand name to be used in the brief) +- **Vertical** (e.g. western-boot maker, neighborhood barbershop, balloon-ride operator) +- **Shape** (the site shape: ecommerce-catalog, ecommerce-standout, local-service-booking, hospitality-experience, hospitality-food, institution-mission, inventory-listing, subscription-app, b2b-manufacturer, directory-marketplace) +- **One-line vibe** (a sentence describing what the brand wants to feel like) +- **Shipped-demos signatures file** (optional; the project artifact listing prior builds' signatures) + +If the shipped-demos file is absent, the build is the first in the portfolio. Run the divergence steps anyway and seed the signatures file with the rendered brief's signature. + +--- + +## Step 1. Locate the design space + +Read the business spec. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. + +**How to pick:** + +- Read the vertical and shape against the 12 core archetypes. Most verticals have two or three plausible candidates; the shape narrows it. +- A western-boot maker maps plausibly to Luxe Considered (heritage premium), Rugged Utilitarian (workwear and craft), or Editorial Restrained (boutique editorial). The shape (ecommerce-standout, with a small editorial collection) narrows toward Luxe Considered with a Rugged Utilitarian secondary. +- A neighborhood barbershop maps plausibly to Warm Conversational (everyday-craft), Retro Nostalgic (period-specific), or Documentary Honest (real-people-real-work). The shape (local-service-booking, with a booking action) narrows toward Warm Conversational with a Retro Nostalgic secondary. +- A balloon-ride operator maps plausibly to Documentary Honest (landscape-and-light), Luxe Considered (aspirational-experience), or Warm Conversational (small-operator-warm). The shape (hospitality-experience, with a named arc and a booking flow) narrows toward Documentary Honest with a Luxe Considered secondary. + +**Output of this step:** + +- Primary candidate archetype (name) +- Optional secondary candidate archetype (name) with a note on which leads +- Two-sentence rationale tying each candidate to the vertical and shape + +--- + +## Step 2. Run input-side divergence + +Read the shipped-demos signatures file. Compare each candidate against every shipped demo using the rules in [`03-divergence-check.md`](03-divergence-check.md). + +**Procedure:** + +- For each candidate (primary, then secondary if present): + - For each shipped demo: + - If archetype matches AND dominant_hue_family matches => discard the candidate as SIBLING. + - If archetype matches AND voice_register matches AND primary_structural_pattern matches => discard the candidate as SIBLING. +- If all candidates are discarded, return to step 1 and pick fresh candidates from a different position on the four creative-direction axes. + +**Output of this step:** + +- The surviving candidate (the chosen archetype) +- A rejection log listing any discarded candidates with the reason (which shipped demo collided and on which fields) + +The rejection log is part of the brief output. It documents what the build was deliberately NOT. + +--- + +## Step 3. Pull references + +From `reference-bank/`, load the file matching the chosen archetype-and-vertical. Read the positive references and the negative references. + +**If the bank has the combination:** + +- Pull three to four positive references from the bank's list. Prefer the ones marked as canonical or most-recent. +- Read the negative references; they tell the build what register to avoid. + +**If the bank is sparse for the combination:** + +- Pull whatever positive references are available (one or two if that is all the bank has). +- Augment with one to two discovered live references that exemplify the position. Search the web for the vertical with the archetype's signal terms (e.g. for Luxe Considered DTC western boots: "premium western boot maker editorial photography prices visible"). +- Note the discovered references with the same format as the bank (URL plus one-line why). Add them back to the bank as part of the build PR. + +**Output of this step:** + +- A list of three to four live reference URLs, each with a one-line why +- A note on which references came from the bank versus which were discovered +- A list of negative references (registers to avoid) + +--- + +## Step 4. Adapt + +Take the chosen archetype's defaults from `brand-archetype-system` (palette, type, voice, layout, imagery direction). Shift them toward the business spec's specifics. + +**Adaptations to document:** + +- **Palette.** Pick 6 to 8 specific hex values that fit the brand. Name each with a token name (e.g. `Bone cream #f5ecd7`, `Saddle tan #a8753a`, `Pre-dawn navy #1a1f3a`). Each token gets a role (page background, primary text, primary CTA, accent, etc.). +- **Type system.** Pick the display family (often a serif from the archetype), the body family (often Inter or similar), and the micro-label treatment (tracking, casing, weight). Document the explicit differentiators from shipped demos (e.g. "tight uppercase tracking 0.04em on micro-labels, distinct from the loose 0.18em tracking the hospitality-experience build uses"). +- **Voice.** Pick the voice register (e.g. story-forward third-person; atmospheric second-person; fitment-first technical). Write five to ten voice samples in this voice using the brand name. +- **Layout.** Pick the structural pattern (e.g. shoppable-grid-product-forward; arc-timeline-hero; fitment-selector-then-rails). Describe the spine moves the homepage will run (four to six numbered moves). +- **Section shapes.** Pick a `hero_shape` and a `footer_shape` from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). The hero shape carries the most visual weight on the page; pick it deliberately based on archetype, audience, and the shapes already shipped in the portfolio. Document the rejected shapes in the brief with one-line reasons. Skipping this step means the engine inherits the most recently built hero shape regardless of brief specification, which is the drift signal this skill exists to catch. +- **CTA grammar.** Pick the verb register (e.g. "Shop the collection," "Book a dawn," "See the morning"). Verb-first, shape-appropriate. +- **Imagery direction.** Describe the shoot's register (e.g. "warm-bone studio seamless, three-quarter angle, soft overhead, products fill 70 percent of frame"). Specify aspect ratios per page slot. + +**Each adaptation choice gets a sentence of why.** The brief is a referenceable artifact; it should explain itself. + +**Output of this step:** + +- The full adaptation set, ready to render into the brief template. + +--- + +## Step 5. Render and verify + +Render the brief using the template in [`02-brief-template.md`](02-brief-template.md). + +After rendering, compute the brief's own signature and run output-side divergence: + +- `archetype`: the chosen archetype (from step 1) +- `dominant_hue_family`: derived from the palette tokens +- `voice_register`: from the voice section +- `primary_structural_pattern`: from the spine moves +- `hero_shape`: from the section-shapes choice in step 4 +- `footer_shape`: from the section-shapes choice in step 4 + +Compare this signature against every shipped demo using the full rule set in [`03-divergence-check.md`](03-divergence-check.md). The check now runs seven rules: the original three pairwise rules (archetype/hue, archetype/voice/pattern, recurring hue across archetypes) plus the three aggregate shape rules (hero shape collision warn at two matches, hero shape archetype-collision block at three matches with shared family, footer shape warn at three matches). + +**Possible outcomes:** + +- **passed.** No overlaps. The brief is ready to hand off. +- **warn-with-reasons.** The brief shares a single field (most commonly dominant_hue_family) with a shipped demo, but not enough to be sibling. Surface the warn with the matched fields so the consumer can make a deliberate call. +- **block-with-reasons.** The brief is sibling to a shipped demo. Return to step 4 and adapt further before re-rendering. Common fixes: swap the dominant accent colour, restructure one of the spine moves, shift the voice register. + +**Output of this step:** + +- The rendered brief +- The references list (from step 3) +- The divergence-check result with all matched fields if any +- A one-line summary suitable for the build PR's description + +--- + +## Failure modes + +- **Skipping step 2.** Picking the archetype that "feels right" without checking against shipped demos is how the portfolio drifts toward house style. +- **Skipping step 5.** Adapting in step 4 without re-checking on output is how the brief itself becomes the carrier of drift. +- **Verbatim copying from the archetype's default palette.** The archetypes provide anchor points, not endpoints. If the brief's palette is the archetype's palette unchanged, the brief is the archetype, not a build. +- **Citing references without why-lines.** A reference URL without a one-line why is decoration. The why is what makes the reference usable in step 4. +- **Hand-waving the divergence check.** The check is not a vibe call. It is a mechanical comparison against the schema. If it produces a block, the adaptation is incomplete. +- **Treating the rejection log as overhead.** The rejection log is part of the deliverable. It tells the next build what is already taken. diff --git a/skills/creative-brief-selector/references/02-brief-template.md b/skills/creative-brief-selector/references/02-brief-template.md new file mode 100644 index 0000000..96ac397 --- /dev/null +++ b/skills/creative-brief-selector/references/02-brief-template.md @@ -0,0 +1,190 @@ +# The brief template + +A fillable markdown skeleton. Fill every section. A section left blank is a section the build will fill with the house default, which is exactly the drift this skill exists to prevent. + +The template is modeled on the structure proven by real shipped builds. The worked example link at the bottom of this file shows the structure rendered against a real build. + +--- + +## Template + +```markdown +# Creative direction: <Brand Name> as <archetype position> + +A reusable brief for the <Brand Name> build. <One-sentence purpose: what shape is this, what position is this, why this brief>. + +Use this brief for: + +- <Specific use case 1> +- <Specific use case 2> + +Do NOT use this brief for: + +- <Adjacent shape that should NOT use this brief> +- <Adjacent position that should NOT use this brief> + +## The <N> spine moves + +1. **<Move 1 name>.** <One paragraph describing the move, specific to the shape>. +2. **<Move 2 name>.** <One paragraph>. +3. **<Move 3 name>.** <One paragraph>. +4. **<Move 4 name>.** <One paragraph>. +<continue 5, 6 if the shape calls for them> + +## Register + +- **Positive reference frame**: <one sentence describing what the brand IS, with named exemplars in nominative attribution> +- **Negative reference frame**: <one sentence describing what the brand is NOT, with named non-exemplars> + +## Live reference sites + +The references this brief draws from. Each is a real site exemplifying the chosen position. + +- [<URL 1>] - <one-line why; what specifically this site does that the brief inherits> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional> + +Negative references (do NOT pull from): + +- [<URL>] - <one-line why this register is the wrong one> + +## Section shapes (hero and footer; first-class brief outputs) + +Pick a `hero_shape` and a `footer_shape` from [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Document the choice with rationale; the choice is not optional and a brief without these fields does not pass the divergence check. + +### `hero_shape`: <chosen shape label, e.g. `wide-photograph-with-band-below`> + +<One paragraph: why this shape, what the chosen shape signals to the visitor that the alternatives do not, what shapes were rejected and why. Reference the section-shapes vocabulary by label.> + +Rejected shapes: + +- `<rejected shape 1>` - <one-line why this shape was wrong for this brief> +- `<rejected shape 2>` - <one-line why this shape was wrong for this brief> + +### `footer_shape`: <chosen shape label, e.g. `single-line-strip`> + +<One paragraph: why this footer shape, what it does for the page that alternatives do not.> + +Rejected shapes: + +- `<rejected shape>` - <one-line why> + +## Palette token shape (specific to this brand; do not reuse across brands) + +| Token | Hex | Role | +|---|---|---| +| <Token 1 name> | `#hex` | <Role> | +| <Token 2 name> | `#hex` | <Role> | +| <Token 3 name> | `#hex` | <Role> | +| <Token 4 name> | `#hex` | <Role> | +| <Token 5 name> | `#hex` | <Role> | +| <Token 6 name> | `#hex` | <Role> | +| <Token 7 name> | `#hex` | <Role, optional> | +| <Token 8 name> | `#hex` | <Role, optional> | + +Do NOT re-use <named hue family from a shipped demo, e.g. "stone-50 + amber-300 (the hospitality-experience default from the X build)">. + +## Type system + +- **Display.** <Family choice with stack notation>, <weight>, <tracking>. +- **Body.** <Family choice>, <weight>. +- **Brand wordmark.** <Family, case, tracking>. Distinct from <named shipped demo's wordmark treatment, e.g. "the loose 0.22em tracking used on the hospitality build">. +- **Micro-labels.** <Family, case, tracking>. <One-line on the explicit differentiator from shipped demos>. +- **Numerics.** <Family, tabular-nums or proportional, treatment for prices>. + +## CTA grammar + +- **Primary on home.** "<Verb-first label>". <One-line on why this verb>. +- **Secondary on home.** "<Verb-first label>". <One-line on why this verb>. +- **On product or detail page.** "<Label>". Verb-shape-appropriate. +- **On craft or about page.** "<Label>". Should close back to the primary action. + +## Image-ready spine + +The structure must be image-ready before any imagery pass runs. Per page slot: + +| Page | Aspect | Count | Source | +|---|---|---|---| +| <Page slot 1> | <e.g. 5:6 portrait> | 1 | <e.g. the signature product> | +| <Page slot 2> | <e.g. 4:5 portrait> | <e.g. one per product> | <e.g. each product, on its own card> | +| <Page slot 3> | <e.g. 16:9 wide> | 1 | <e.g. one lifestyle scene supporting the craft band> | +| <continue for every page> | | | | + +Each slot uses a placeholder during Phase A and is filled by the imagery pass in Phase B. Placeholders carry the alt text the final image will carry, so the swap is structurally drop-in. + +## Voice samples + +Five to ten lines in the brand's voice, used downstream by content-and-copy and landing-page-copy. + +- <Sample 1> +- <Sample 2> +- <Sample 3> +- <Sample 4> +- <Sample 5> +- <Sample 6, optional> +- <Sample 7, optional> + +## Honesty contract (unchanging across the portfolio) + +- <Functional element, e.g. cart, booking form> is real client-side, <demo surface, e.g. checkout, payment> is a clearly labelled demo that processes nothing. +- Fictitious brand disclosure in the footer and in any JSON-LD `description` field. +- Demo-only labelling on any demo surface in the brand's primary accent colour. +- All prices and figures fictitious. No promotional cadence, no fabricated reviews, no fabricated press quotes. +- No real brand mark. The logo pass, if any, is a separate later run. + +## Acceptance checklist (Phase A criteria) + +A build matches this brief if: + +- [ ] <Move 1 acceptance criterion> +- [ ] <Move 2 acceptance criterion> +- [ ] <Move 3 acceptance criterion> +- [ ] <Move 4 acceptance criterion> +- [ ] Palette is documentable as <N> tokens, distinct from any shipped demo's tokens. +- [ ] Type micro-labels have a distinct treatment from <named shipped demo's treatment>. +- [ ] Per-page image slots are wired with descriptive alt text, ready for a Phase B drop-in. +- [ ] Honesty contract intact. + +## Divergence-check result + +- **Archetype**: <chosen archetype name from brand-archetype-system> +- **Dominant hue family**: <derived from palette, e.g. "leather-bone-saddle"> +- **Voice register**: <e.g. "story-forward third-person"> +- **Primary structural pattern**: <e.g. "shoppable-grid-product-forward"> +- **Hero shape**: <chosen label from 05-section-shapes-vocabulary.md> +- **Footer shape**: <chosen label from 05-section-shapes-vocabulary.md> + +**Input-side divergence**: <passed | warn-with-reasons | block-with-reasons>. <If anything was rejected at step 2, list it here: rejected <archetype> because it collided with <shipped demo slug> on <field>>. + +**Output-side divergence**: <passed | warn-with-reasons | block-with-reasons>. <If warn or block, list the matched fields and the colliding demo. Rules 4 and 6 surface as warns; Rule 5 surfaces as a block; Rules 1, 2, 3 surface per their definitions in 03-divergence-check.md.> + +--- +``` + +--- + +## Worked example + +The Pinto Mesa Boots store-spine brief at `rampstackco-app/progress/ecommerce-standout-store-spine-brief.md` is a faithful render of this template against a real shipped build (ecommerce-standout shape; Luxe Considered with Rugged Utilitarian influence). It demonstrates: + +- The five spine moves (product-forward hero, shoppable grid, honest wayfinding, craft as supporting band, premium trust signals). +- The leather-forward palette with explicit do-not-reuse against the prior hospitality build's stone-and-amber. +- The type differentiation (tight uppercase microlabel tracking, distinct from the prior hospitality build's loose tracking). +- The image-ready spine with per-page aspect / count / source. +- The acceptance checklist as Phase-A criteria. + +Use the worked example as a structural reference when rendering new briefs. + +--- + +## Common section failures + +- **Skipping the "Do NOT use this brief for" section.** The negative-use section is what keeps the brief from being mis-applied to an adjacent shape. +- **Spine moves that are abstract.** "Lead with the product" is not a spine move. "Lead with the signature product shown large at 5:6 with one primary CTA and price-forward entry" is. +- **Palette without explicit do-not-reuse lines.** The do-not-reuse line is what makes the divergence check checkable. +- **Type system without the explicit differentiator from shipped demos.** This is the single field most likely to drift if not pinned. +- **CTA grammar in mood words.** "Welcoming" is not CTA grammar. "Shop the collection" is. +- **Image-ready spine without aspect ratios.** Without the aspect ratios the imagery pass cannot generate to the right shape. +- **Honesty contract treated as boilerplate.** The contract is part of what makes the brand demo-honest; cut and paste it but verify each line still applies to the specific build. +- **Acceptance checklist as motivational language.** The checklist is the build's pass/fail criteria, not a vibe statement. diff --git a/skills/creative-brief-selector/references/03-divergence-check.md b/skills/creative-brief-selector/references/03-divergence-check.md new file mode 100644 index 0000000..8374b0f --- /dev/null +++ b/skills/creative-brief-selector/references/03-divergence-check.md @@ -0,0 +1,229 @@ +# The divergence check + +The signature schema, the overlap rules, and the comparison procedure. + +--- + +## Signature schema + +Each shipped demo carries a signature with seven fields. The schema is small on purpose: any field that takes judgment to populate gets argued about; a small mechanical schema gets used. + +```yaml +- slug: <kebab-case slug, e.g. pinto-mesa-boots> + archetype: <canonical archetype name from brand-archetype-system, e.g. luxe-considered> + dominant_hue_family: <named hue family, e.g. leather-bone-saddle> + voice_register: <named register, e.g. story-forward-third-person> + primary_structural_pattern: <named pattern, e.g. shoppable-grid-product-forward> + hero_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. dual-column-image-and-text> + footer_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. single-line-strip> +``` + +The last two fields (`hero_shape` and `footer_shape`) are the latest schema additions. The canonical vocabulary for both lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +### slug + +The kebab-case slug for the shipped build. Used to identify the demo in rejection logs and warn or block reasons. + +### archetype + +The canonical archetype name from `brand-archetype-system`. Use the file slug from `references/core-archetypes/` (e.g. `luxe-considered`, `documentary-honest`, `warm-conversational`). If the demo composes two archetypes, record both as a hyphenated pair with the lead first (e.g. `luxe-considered-rugged-utilitarian`). + +### dominant_hue_family + +The recognizable colour family the demo reads as, in three to four words. Examples: + +- `leather-bone-saddle` (Pinto Mesa Boots v2) +- `dawn-navy-coral` (Drift & Dawn after the dawn retune) +- `dark-linen-amber` (Pho Heights) +- `warm-walnut-brass` (Iron & Rye) +- `forest-green-cream` (Clearflow Initiative) +- `slate-and-amber` (the original Drift & Dawn pre-retune, kept for historical reference) +- `stone-and-amber` (the recurring family the imagery passes surfaced as the drift signal) + +The naming convention: two to four colour terms separated by hyphens, lowercase. The terms should be specific enough that two demos with materially different palettes get different families even if they share an undertone. + +### voice_register + +The brand's voice in three to four words. Examples: + +- `story-forward-third-person` +- `atmospheric-second-person` +- `fitment-first-technical` +- `evidence-and-mission-first` +- `restrained-citation-bearing` +- `warm-everyday-craft` + +The naming convention: hyphenated phrase that names the register the voice samples in the brief operate in. + +### primary_structural_pattern + +The structural pattern the homepage runs, in three to five words. Examples: + +- `shoppable-grid-product-forward` +- `arc-timeline-hero-with-packages-strip` +- `fitment-selector-then-rails` +- `editorial-hero-then-courses-grid` +- `barber-roster-then-services-menu` +- `theory-of-change-hero-then-evidence-band` + +The naming convention: name the homepage's primary spine in a way another build can recognize from the rendered page. + +### hero_shape + +The shape of the hero section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `dual-column-image-and-text` +- `wide-photograph-with-band-below` +- `full-bleed-image-with-overlay` +- `type-led-prose` +- `centered-single-column` +- `asymmetric-large-image-small-text` +- `grid-of-elements` +- `data-table-or-spec-led` + +A build that needs a shape not in the vocabulary documents and proposes a new label per the extension procedure in `05-section-shapes-vocabulary.md`. + +### footer_shape + +The shape of the footer section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `single-line-strip` +- `multi-column-sitemap` +- `type-only-no-links` +- `editorial-colophon-with-masthead` +- `newsletter-band-with-credits` +- `dark-cta-then-credits` + +--- + +## Overlap rules + +The comparison is mechanical. The skill applies these rules in order; the first rule that fires determines the outcome for that pair. + +### Rule 1: Same archetype + same dominant_hue_family + +If two demos share `archetype` AND share `dominant_hue_family`, they are **SIBLING (block)**. + +Two demos in the same archetype with the same hue family will read as the same brand at a glance. The block forces an adaptation in either archetype or palette before the brief can ship. + +### Rule 2: Same archetype + same voice_register + same primary_structural_pattern + +If two demos share `archetype` AND share `voice_register` AND share `primary_structural_pattern`, they are **SIBLING (block)**. + +This catches the case where the palettes diverge but the underlying skeleton is identical. The build will look different on first glance and identical on the second. + +### Rule 3: Same dominant_hue_family across different archetypes + +If two demos share `dominant_hue_family` but their `archetype` differs, the outcome is **WARN**. + +A recurring hue family across different archetypes is the most common drift signal in a portfolio. The warn surfaces the recurrence so the consumer can choose to break the pattern or accept it as the portfolio's signature. + +### Rule 4: Hero shape collision (warn) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of two or more shipped demos, the outcome is **WARN**. + +The warn surfaces a deliberation note listing every shipped demo using the same shape. The brief author either justifies the repeat (and records that justification in the brief's section-shapes rationale) or picks a different shape from the vocabulary. Two demos sharing a hero shape is acceptable for a portfolio of nine to twelve demos; three or more is the point where the shape starts reading as the engine's house default. + +### Rule 5: Hero shape archetype-collision (block) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of three or more shipped demos AND any of those matching demos share an archetype family with the proposed brief, the outcome is **BLOCK**. + +This catches the case where the brief is heading toward the strongest sibling result possible: the same hero shape AND a related archetype. The block forces the brief to choose differently on at least one dimension (a different hero shape, or a different archetype lead, or a documented justification that escalates to the deliberation notes with explicit reasoning). + +Archetype-family overlap is computed by comparing the lead archetype tokens. Composed archetypes share a family if either of their tokens matches. For example, `editorial-restrained` and `editorial-restrained-documentary-honest` share the `editorial-restrained` family; `documentary-honest-luxe-considered` and `rugged-utilitarian-documentary-honest` share the `documentary-honest` family. + +### Rule 6: Footer shape collision (warn) + +If the candidate's proposed `footer_shape` matches the `footer_shape` of three or more shipped demos, the outcome is **WARN**. + +Footers tolerate more repetition than heroes since they carry less visual weight and are more functional than expressive. The threshold (three matching demos for a warn, not two) is correspondingly higher. There is no block-level rule for footer shapes at this scope; if a portfolio-wide footer shape emerges as the house default, it becomes part of the portfolio's signature rather than a per-build distinctness failure. + +### Rule 7: Anything else + +If no rule above fires, the outcome is **PASSED**. + +--- + +## Why shapes carry weight + +Heroes carry the most visual weight on a page and the most signal to the visitor. Hero-shape repetition across a portfolio compresses the perceived distance between builds even when palette, voice, and structural pattern diverge. The early showcase portfolio surfaced this drift signal: most builds shipped a `dual-column-image-and-text` or `full-bleed-image-with-overlay` hero regardless of brief specification, because the engine pattern-matched the most recently built shape. + +Footers carry less weight and are typically more functional than expressive. They tolerate more repetition before the repetition becomes a distinctness cost. + +Rules 4, 5, and 6 exist to make hero-shape and footer-shape choice an explicit selection at brief time rather than an implicit inheritance from the most recently built demo. + +--- + +## Comparison procedure + +``` +# Pairwise rules (run on every candidate-shipped pair): +for candidate in candidates: + for shipped in shipped_demos: + if rule_1(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'dominant_hue_family']) + continue + if rule_2(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'voice_register', 'primary_structural_pattern']) + continue + if rule_3(candidate, shipped): + record_warn(candidate, shipped, fields=['dominant_hue_family']) + continue + +# Aggregate rules (run once per candidate against the full set): +for candidate in candidates: + hero_matches = [s for s in shipped_demos if s.hero_shape == candidate.hero_shape] + if len(hero_matches) >= 3 and any(shares_archetype_family(candidate, s) for s in hero_matches): + record_block(candidate, hero_matches, fields=['hero_shape', 'archetype']) # rule 5 + elif len(hero_matches) >= 2: + record_warn(candidate, hero_matches, fields=['hero_shape']) # rule 4 + + footer_matches = [s for s in shipped_demos if s.footer_shape == candidate.footer_shape] + if len(footer_matches) >= 3: + record_warn(candidate, footer_matches, fields=['footer_shape']) # rule 6 +``` + +The check produces three lists: blocks, warns, and a passed flag (true iff blocks and warns are both empty). + +### Input-side outcome + +- If any block was recorded against the primary candidate, discard it. If the secondary candidate also blocks, return to step 1 and pick fresh candidates. +- Warns at input-side are surfaced in the rejection log but do not discard the candidate. + +### Output-side outcome + +After the brief is rendered, the brief's own signature is checked against every shipped demo using the same rules. The outcome is one of: + +- **passed**: no blocks, no warns. The brief is ready to hand off. +- **warn-with-reasons**: warns only. The brief shares a single field (most commonly `dominant_hue_family`) with a shipped demo. Surface the warn with the matched fields so the consumer can make a deliberate call. +- **block-with-reasons**: at least one block. The brief is sibling to a shipped demo. Return to step 4 of the process and adapt further before re-rendering. + +--- + +## What changes a block to a warn or a pass + +Concretely: + +- **Shift the dominant_hue_family.** Swap the dominant accent colour, change the page background's temperature, or change the accent colour family (saddle to oxblood to navy). Recompute the family. +- **Shift the primary_structural_pattern.** Change which move leads the page. A "product-forward" pattern becomes "story-forward" by reordering the spine moves. Recompute the pattern. +- **Shift the voice_register.** Change the voice from third-person to second-person, or from atmospheric to technical. Recompute the register. +- **Compose a different archetype pair.** If the chosen archetype is locked, change the secondary archetype to shift the brief's centre of mass. + +Each adaptation should be a deliberate choice, recorded in the brief's adaptation notes (step 4 of the process). + +--- + +## The signatures file + +The signatures file is a project artifact, not part of this skill. The consuming project maintains it (typically as `progress/shipped-demos-signatures.yml` or similar). The illustrative format is in [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md). + +Whenever a new build ships, append its signature to the file. The signatures grow with the portfolio; the divergence check stays current. + +--- + +## Failure modes + +- **Filling fields with vibe words.** "vibrant-modern" is not a hue family; "saddle-bone-walnut" is. The schema works because the field values are specific. Vague values produce vague checks. +- **Re-using the same family across builds without recomputing.** When a build's palette shifts during step 4, the dominant_hue_family must shift with it. A stale signature is worse than a missing signature. +- **Treating warns as ignorable.** A warn is the portfolio's drift early-warning. Three consecutive warns on the same hue family is the portfolio adopting a house signature, which is the failure mode this skill exists to prevent. +- **Hand-waving the rules.** The rules are mechanical. If a candidate blocks under rule 1, it blocks; the answer is to adapt, not to argue with the rule. diff --git a/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md b/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md new file mode 100644 index 0000000..b770582 --- /dev/null +++ b/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md @@ -0,0 +1,141 @@ +# Shipped-demos signatures: worked example + +An illustrative signatures file with seven worked entries. This file is example-only; the live signatures file for any consuming project lives in that project (typically at `progress/shipped-demos-signatures.yml`), not in this skill. + +The schema is defined in [`03-divergence-check.md`](03-divergence-check.md). Each entry has seven fields: `slug`, `archetype`, `dominant_hue_family`, `voice_register`, `primary_structural_pattern`, `hero_shape`, `footer_shape`. The last two (`hero_shape`, `footer_shape`) are the latest additions; their canonical vocabulary lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +The seven entries below are illustrative records of seven sibling-shape demos a portfolio might ship. They are written here as a worked example of what the file looks like in practice. The archetype values reference the canonical names from `brand-archetype-system`. + +--- + +## Example signatures + +```yaml +demos: + - slug: fitfirst-parts + archetype: technical-precise + dominant_hue_family: slate-and-amber + voice_register: fitment-first-technical + primary_structural_pattern: fitment-selector-then-rails + hero_shape: dual-column-image-and-text + footer_shape: multi-column-sitemap + + - slug: iron-and-rye-barbershop + archetype: warm-conversational-retro-nostalgic + dominant_hue_family: warm-walnut-brass + voice_register: warm-everyday-craft + primary_structural_pattern: barber-roster-then-services-menu + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: pho-heights + archetype: documentary-honest-luxe-considered + dominant_hue_family: dark-linen-amber + voice_register: chef-essay-first-person + primary_structural_pattern: editorial-hero-then-signatures-menu + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: volta-robotics + archetype: technical-precise + dominant_hue_family: graphite-and-signal-orange + voice_register: spec-forward-technical + primary_structural_pattern: product-strip-then-spec-table + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: clearflow-initiative + archetype: editorial-restrained + dominant_hue_family: forest-green-cream + voice_register: restrained-citation-bearing + primary_structural_pattern: theory-of-change-hero-then-evidence-band + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: pinto-mesa-boots + archetype: luxe-considered-rugged-utilitarian + dominant_hue_family: leather-bone-saddle + voice_register: story-forward-third-person + primary_structural_pattern: shoppable-grid-product-forward + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: drift-and-dawn + archetype: documentary-honest-luxe-considered + dominant_hue_family: dawn-navy-coral + voice_register: atmospheric-second-person + primary_structural_pattern: arc-timeline-hero-with-packages-strip + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip +``` + +--- + +## Why each field is what it is + +### fitfirst-parts (ecommerce-catalog) + +- **archetype**: `technical-precise`. The build leads with a YMM (year-make-model) fitment selector. Grids, monospace numerics, system-feeling. +- **dominant_hue_family**: `slate-and-amber`. Cool slate ground with warm amber accents on safety and action surfaces. +- **voice_register**: `fitment-first-technical`. The voice asks "does it fit your vehicle" before anything else. +- **primary_structural_pattern**: `fitment-selector-then-rails`. The home leads with the selector, then rails of parts filtered by the confirmed vehicle. + +### iron-and-rye-barbershop (local-service-booking) + +- **archetype**: `warm-conversational-retro-nostalgic`. Heritage barbershop register; walnut and brass; period-specific cues. +- **dominant_hue_family**: `warm-walnut-brass`. Walnut wood and brass hardware are the recognizable palette. +- **voice_register**: `warm-everyday-craft`. The voice is the shop talking about its work in plain terms. +- **primary_structural_pattern**: `barber-roster-then-services-menu`. Roster (initials) leads, services menu follows, atmosphere gallery threads the page. + +### pho-heights (hospitality-food) + +- **archetype**: `documentary-honest-luxe-considered`. Dark linen photography, real-food register, premium restraint. +- **dominant_hue_family**: `dark-linen-amber`. Dark linen background dominates; amber surfaces as the accent. +- **voice_register**: `chef-essay-first-person`. The chef-partner essay is the page's voice. +- **primary_structural_pattern**: `editorial-hero-then-signatures-menu`. Edge-to-edge hero, chef essay, signatures section with image-led cards. + +### volta-robotics (b2b-manufacturer) + +- **archetype**: `technical-precise`. Industrial spec-table register. Same archetype as fitfirst-parts but a different hue family and a different structural pattern (so rule 1 does not fire on this pair). +- **dominant_hue_family**: `graphite-and-signal-orange`. Industrial graphite with hazard-orange accents on action surfaces. +- **voice_register**: `spec-forward-technical`. Specs lead, narrative supports. +- **primary_structural_pattern**: `product-strip-then-spec-table`. Product strip up top, deep spec tables follow. + +### clearflow-initiative (institution-mission) + +- **archetype**: `editorial-restrained`. Counsel-restrained register; numbers before adjectives; citation-bearing voice. +- **dominant_hue_family**: `forest-green-cream`. Deep forest green sections with warm cream surfaces. +- **voice_register**: `restrained-citation-bearing`. Third-person about the org, low-register confidence, numbers leading. +- **primary_structural_pattern**: `theory-of-change-hero-then-evidence-band`. Theory of change in the hero, evidence band (lives reached, water systems built) follows. + +### pinto-mesa-boots (ecommerce-standout) + +- **archetype**: `luxe-considered-rugged-utilitarian`. Premium DTC maker register with workwear and craft secondary. +- **dominant_hue_family**: `leather-bone-saddle`. Bone cream ground with saddle tan and walnut accents; oxblood as the demo-only chip. +- **voice_register**: `story-forward-third-person`. The brand talks about itself in the third person, with material before adjectives. +- **primary_structural_pattern**: `shoppable-grid-product-forward`. Product-forward hero, six-boot shoppable grid on the home, by-last wayfinding. + +### drift-and-dawn (hospitality-experience) + +- **archetype**: `documentary-honest-luxe-considered`. Photography-led, atmospheric, aspirational. Same composed archetype as pho-heights but a different vertical and a different hue family (so rule 1 does not fire on this pair). +- **dominant_hue_family**: `dawn-navy-coral`. Pre-dawn navy with coral and pale-gold accents, deliberately distinct from the hospitality-experience stone-and-amber default the original build used. +- **voice_register**: `atmospheric-second-person`. The brand walks the visitor through the morning in second person. +- **primary_structural_pattern**: `arc-timeline-hero-with-packages-strip`. Hero with arc preview, packages strip with named prices, six-moment timeline on the experience page. + +--- + +## What this example exercises + +The seven entries are constructed to exercise the divergence rules: + +- **Rule 1 not firing**: `fitfirst-parts` and `volta-robotics` share `archetype: technical-precise` but differ on `dominant_hue_family` (`slate-and-amber` vs `graphite-and-signal-orange`). No block. +- **Rule 1 not firing**: `pho-heights` and `drift-and-dawn` share `archetype: documentary-honest-luxe-considered` but differ on `dominant_hue_family` (`dark-linen-amber` vs `dawn-navy-coral`). No block. The deliberate retune from the original `slate-and-amber` to `dawn-navy-coral` is what kept this pair from blocking. +- **Rule 3 historical case**: the original `drift-and-dawn` (pre-retune, hue family `slate-and-amber`) would have triggered rule 3 against `fitfirst-parts` (also `slate-and-amber`) across different archetypes. The retune resolved the recurring family. + +--- + +## How to use this example + +Copy the YAML block to a `progress/shipped-demos-signatures.yml` file in the consuming project. Edit the entries to match the actual shipped builds. Append new entries as builds ship. The divergence check in [`03-divergence-check.md`](03-divergence-check.md) reads from this file. + +This file is example-only. The skill does not parse this example file at runtime; it parses the consuming project's signatures file. The example exists to show what the file should look like. diff --git a/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md b/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md new file mode 100644 index 0000000..0195584 --- /dev/null +++ b/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md @@ -0,0 +1,151 @@ +# Section shapes vocabulary + +A canonical, open vocabulary of section shapes the brief picks from for the hero and footer sections (with optional later extension to trust-strip, CTA-close, and how-it-works sections). The vocabulary is a starting point, not a closed enum. Builds can document and propose a new shape if none of the listed labels fits. + +Section shapes are first-class brief outputs. The brief picks a shape per section explicitly and records the rationale next to palette and voice rationale. Two new fields per signature record (`hero_shape` and `footer_shape`) let the divergence check fire against shape collision across shipped demos. + +The divergence rules for shapes are in [`03-divergence-check.md`](03-divergence-check.md) (Rules 4, 5, 6). + +--- + +## Hero shapes (open list, starting set) + +### `dual-column-image-and-text` + +Image on one side of the hero, heading and lede and CTAs on the other. CSS grid with two columns (often around 1.1fr / 1fr). The engine's house default and the shape most prone to overuse in a portfolio that grows without explicit shape selection. + +- **When it fits**: brands where the photograph and the type carry roughly equal weight and the eye is meant to ricochet between them. Premium DTC product hero is the canonical fit; a single product on the image side and a price-and-CTA on the type side. +- **References**: [allbirds.com](https://allbirds.com), [tecovas.com](https://tecovas.com). +- **Archetype affinities**: Luxe Considered, Warm Conversational, Editorial Restrained (mild). + +### `wide-photograph-with-band-below` + +Single full-width hero photograph (aspect 16:9 or wider) spanning the content width, with structured content (search rail, CTA pair, lede, filter chips) stacked vertically below the photograph. The photograph carries the page; the band below carries the affordances. + +- **When it fits**: inventory marketplaces, regional specialists, sites where the photograph signals what the marketplace is for and the band carries the controls. Also fits magazine-style editorial registers where one strong image opens an article. +- **References**: [bringatrailer.com](https://bringatrailer.com), [icon4x4.com](https://icon4x4.com). +- **Archetype affinities**: Rugged Utilitarian, Documentary Honest, Editorial Restrained. + +### `full-bleed-image-with-overlay` + +Image fills the section (or near-fills, often at `object-cover` with `absolute inset-0`), with type overlaid via a gradient. Dramatic, cinema-poster register. Strongest visual signal of all hero shapes; correspondingly the easiest to over-saturate. + +- **When it fits**: hospitality experiences where the place is the product (balloon ride, restaurant, hotel), mission-driven nonprofits where the documentary photograph is the evidence, premium B2B where the product is photographed at scale. Atmospheric and cinematic. +- **References**: [bombasses.com](https://bombasses.com) (hospitality), [charitywater.org](https://charitywater.org) (institution-mission). +- **Archetype affinities**: Documentary Honest, Luxe Considered (composed with Documentary Honest), Editorial Restrained. + +### `type-led-prose` + +No image in the hero. The H1 and lede do the work; image (if any) appears below the hero as a supporting element. Editorial publication register. The whitespace and the type carry the page. + +- **When it fits**: editorial publications, ideas-led brands, B2B SaaS where the proposition is conceptual, premium consultancies, law and finance where understated credibility is the play. +- **References**: [nytimes.com](https://nytimes.com), [stripe.com](https://stripe.com) (mild type-led, with type leading and a subtle product render below). +- **Archetype affinities**: Editorial Restrained, Technical Precise (mild). + +### `centered-single-column` + +Narrow content column centered on the page, H1 and lede only, minimal. Often paired with atmospheric brand registers where the centered alignment signals "considered, not loud." + +- **When it fits**: portfolio brands, atmospheric or contemplative registers, single-product brands where the page is essentially a long-scroll story and the hero is just the opening line. +- **References**: [linear.app](https://linear.app), [framer.com](https://framer.com) (both run centered single-column heroes at times). +- **Archetype affinities**: Editorial Restrained, Luxe Considered. + +### `asymmetric-large-image-small-text` + +One element dominates the hero (usually an image at 70 to 80 percent of width), the other is caption-scale beside or below it. Distinct from `dual-column-image-and-text` by the imbalance: the dual-column is roughly balanced, the asymmetric leans heavily. + +- **When it fits**: magazine cover style, photography portfolios, single-product hero where the product carries everything and the type is a caption-scale credit line. +- **References**: [magnum.com](https://magnum.com), [aesop.com](https://aesop.com) (varies; some pages use asymmetric layouts). +- **Archetype affinities**: Luxe Considered, Documentary Honest, Editorial Restrained. + +### `grid-of-elements` + +The hero IS a grid: product tiles, listing cards, directory entries, no single anchor image. The inventory or directory itself is the hero. Distinct from `wide-photograph-with-band-below` by having no single dominant image; the grid carries the meaning. + +- **When it fits**: directory and marketplace shapes where the breadth of the catalog is the value, ecommerce catalog shapes where shoppability above the fold is the conversion lever. +- **References**: [airbnb.com](https://airbnb.com) (search results hero is the grid), [unsplash.com](https://unsplash.com). +- **Archetype affinities**: Technical Precise, Editorial Restrained (with restraint), Rugged Utilitarian (if the directory is the working catalog). + +### `data-table-or-spec-led` + +A data table or spec block is the hero element. The numbers and the comparison carry the page. Technical Precise register, B2B engineering context, comparison-led purchase decisions. + +- **When it fits**: B2B engineering procurement, hardware comparison sites, financial product comparison, anywhere the buyer is data-anchored before they care about photography. +- **References**: [parametric-portfolios.com](https://parametric-portfolios.com), [substack.com/pricing](https://substack.com/pricing) (pricing-table-as-hero variants). +- **Archetype affinities**: Technical Precise, Editorial Restrained. + +--- + +## Footer shapes (open list, starting set) + +### `single-line-strip` + +One row carrying the brand disclosure paragraph and the footer nav, no multi-column structure. Mobile and desktop render the same content reflowed. The default across most demos in the showcase portfolio. + +- **When it fits**: small-collection brands, single-purpose microsites, demo and showcase contexts, brands where the footer is meant to be functional chrome rather than navigation in its own right. +- **References**: most editorial brand sites with a small surface area. +- **Archetype affinities**: any; this is the chrome default. + +### `multi-column-sitemap` + +Three to six columns of links plus brand info. Common on larger commerce sites where the footer carries category navigation, popular searches, account shortcuts, customer service, about-the-company, and resources. + +- **When it fits**: ecommerce catalog with deep category trees, multi-tenant marketplaces with seller-side and buyer-side links, B2B sites with documentation libraries. +- **References**: [amazon.com](https://amazon.com), [shopify.com](https://shopify.com), most large retailers. +- **Archetype affinities**: Technical Precise, Rugged Utilitarian (if functional), any commerce-heavy archetype. + +### `type-only-no-links` + +Minimal editorial footer, copyright and disclosure only, no nav. The footer is essentially a colophon. + +- **When it fits**: ideas-led brands, single-page narratives, publications where the nav lives in the top chrome and the bottom is just the credit line. +- **References**: [pitchfork.com](https://pitchfork.com) (varies; minimal footer), portfolio sites. +- **Archetype affinities**: Editorial Restrained, Luxe Considered. + +### `editorial-colophon-with-masthead` + +Masthead-style footer naming the editorial team or contributors. Fits publication register where the footer credits the people behind the work. + +- **When it fits**: publications, magazine sites, editorial collectives, organizations where the people are the brand. +- **References**: [theatlantic.com](https://theatlantic.com), [theverge.com](https://theverge.com). +- **Archetype affinities**: Editorial Restrained, Documentary Honest. + +### `newsletter-band-with-credits` + +Newsletter signup as the dominant footer element, with credits below. The newsletter is the conversion goal; the footer is the conversion surface. + +- **When it fits**: content sites, newsletter-first publications, brands where the newsletter is the customer-relationship channel. +- **References**: [substack.com](https://substack.com), most content sites operating newsletter-led growth. +- **Archetype affinities**: Editorial Restrained, Warm Conversational. + +### `dark-cta-then-credits` + +Two-row footer with a dark CTA band on top and a credits strip below. The CTA band acts as the page-bottom conversion surface; the credits strip is the actual footer. + +- **When it fits**: conversion-led sites where the bottom of the page is the second-most-attended surface (after the hero), marketing sites, B2B with a sign-up funnel. +- **References**: [vercel.com](https://vercel.com), [linear.app](https://linear.app). +- **Archetype affinities**: Technical Precise, any conversion-led register. + +--- + +## Optional extensions (not formally checked at this dispatch's scope) + +The framework can grow to cover additional section shapes as the portfolio surfaces them. Currently documented loosely; not part of the divergence check fields. + +- **Trust-strip shapes**: four-signal block, two-paragraph narrative band, logo wall, citation row. +- **CTA-close shapes**: dark band with single CTA, gradient band with pair of CTAs, image-backed close, newsletter close. +- **How-it-works shapes**: three-card strip, numbered list with images, flow diagram, timeline. + +When a brief's shape choice for one of these sections proves load-bearing for the build's distinctness, a future framework dispatch can promote the section to a checked field. + +--- + +## How to extend the vocabulary + +A build that discovers a section shape not present in the vocabulary: + +1. Documents the shape in the brief with a name (kebab-case), a one-paragraph description, and one or two real-world references. +2. Adds the shape to this file under the appropriate section (hero or footer) with the same format the existing shapes use. +3. Commits the vocabulary addition in the build PR. + +The vocabulary grows with the portfolio. Stale shapes (no demo uses them, no live references remain) can be retired in subsequent dispatches. diff --git a/skills/creative-brief-selector/references/reference-bank/README.md b/skills/creative-brief-selector/references/reference-bank/README.md new file mode 100644 index 0000000..dbaf928 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/README.md @@ -0,0 +1,114 @@ +# Reference bank + +The bank holds curated live reference sites for archetype-and-vertical combinations the portfolio has built against. Each file covers one combination, with positive references (sites that exemplify the position) and negative references (sites in the same vertical but in the WRONG register). + +The bank is the institutional memory of the portfolio. A new build for a combination that has been done before loads the existing file and adapts. A new build for a sparse combination supplies discovered references and commits them back to the bank as part of its build PR. + +--- + +## File naming convention + +`<archetype>-<vertical-specific-tag>.md` + +Examples: + +- `premium-dtc-maker-western-boots.md` +- `heritage-local-service-barbershop.md` +- `hospitality-experience-balloon-ride.md` + +The archetype prefix is the canonical name from `brand-archetype-system` (composed archetypes are hyphenated with the lead first). The vertical-specific tag is the narrowest description of the vertical the file covers (not the broad shape; the specific category within it). + +--- + +## File structure + +Each file has the same structure: + +```markdown +# <Archetype>, <Vertical> + +- **Archetype**: <Canonical archetype name, with composition note if any>. +- **Vertical**: <Broad shape> (specifically <narrow category>). +- **Position summary**: <One-line position the references collectively exemplify>. + +## Positive references + +- [<URL 1>] - <one-line why; what specifically this site does that a build in this position should inherit> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional but encouraged> + +## Negative references + +- [<URL or named category>] - <one-line why this register is the wrong one for this position> + +## Extension note + +- <When was this file last updated and against which build> +``` + +--- + +## Adding references + +A build that uses this skill on a combination that has a file already: + +1. Loads three to four references from the existing file in step 3 of the process. +2. If the build discovered any new live references in addition (because the bank's references were stale or the build needed more breadth), append them to the positive references list in the same file with a one-line why. +3. Commit the file edit as part of the build PR. + +A build that uses this skill on a combination with no existing file: + +1. Creates a new file under `reference-bank/` named per the convention above. +2. Fills the file with three to six positive references discovered during the build's step 3. +3. Fills negative references with one to two categories or named sites that the build should not pull from. +4. Commits the file as part of the build PR. + +--- + +## Reference quality bar + +Each positive reference should be a real live site that: + +- Exemplifies the chosen position observably (palette, layout, voice, imagery, or all four). +- Is operating at a quality level the build can credibly aspire to. +- Has been live recently (within the past year if possible; older references are acceptable if they remain the canonical example). + +Each negative reference should be a real live site or a named category that: + +- Sits in the same vertical but in a different register. +- Helps the build understand what to NOT pull from. + +The one-line why for each reference is what makes the reference usable in step 4 of the process. A URL without a why is decoration; the why is what tells the next build what specifically to inherit or avoid. + +--- + +## When to retire a reference + +A reference should be removed from the bank when: + +- The URL stops showing what it was cited for (brand redesign, site shutdown, paywall changed the visible register). +- A more canonical example for the same position emerges. +- The build that originally cited the reference has been superseded and the new build uses different references. + +Retirement is a normal part of bank maintenance. The bank reflects what is currently usable, not what was once usable. + +--- + +## Seeded combinations + +Eleven combinations live in the bank: + +- [`premium-dtc-maker-western-boots.md`](premium-dtc-maker-western-boots.md) - Premium DTC maker register applied to a small-collection western-boot maker. +- [`heritage-local-service-barbershop.md`](heritage-local-service-barbershop.md) - Heritage local-service register applied to a neighborhood barbershop. +- [`hospitality-experience-balloon-ride.md`](hospitality-experience-balloon-ride.md) - Documentary-honest hospitality-experience register applied to a scenic-flight operator. +- [`editorial-restrained-documentary-honest-specialty-coffee-subscription.md`](editorial-restrained-documentary-honest-specialty-coffee-subscription.md) - Editorial-restrained subscription-app register applied to a single-origin specialty coffee subscription. +- [`rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md`](rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md) - Rugged-utilitarian inventory-listing register applied to a regional used-truck-and-SUV marketplace. +- [`editorial-restrained-literary-quarterly.md`](editorial-restrained-literary-quarterly.md) - Editorial-restrained editorial-publication register applied to a themed literary and ideas quarterly. +- [`luxe-considered-editorial-restrained-residential-architectural-brokerage.md`](luxe-considered-editorial-restrained-residential-architectural-brokerage.md) - Luxe-considered-editorial-restrained inventory-listing register applied to a residential brokerage of architecturally significant homes (the first same-shape divergence test against the rugged-utilitarian regional-used-vehicle-marketplace entry). +- [`bold-confident-editorial-restrained-aaa-game-studio.md`](bold-confident-editorial-restrained-aaa-game-studio.md) - Bold-confident-editorial-restrained corporate-portfolio register applied to a AAA-adjacent action game studio (the first portfolio entry in Bold Confident; the gentler entry into the bold register before a game-title demo). +- [`bold-confident-vibrant-saturated-single-ip-game-title.md`](bold-confident-vibrant-saturated-single-ip-game-title.md) - Bold-confident-vibrant-saturated single-IP marketing register applied to a post-launch AAA action game title (the first single-IP marketing entry; the title side of the game-studio pair, claiming the saturated leap the studio brief reserved). +- [`minimal-essentialist-documentary-honest-trades-directory.md`](minimal-essentialist-documentary-honest-trades-directory.md) - Minimal-essentialist-documentary-honest directory-marketplace register applied to a homeowner-facing local-trades directory (the first directory-marketplace shape and the first multi-provider entry; encodes the multi-provider conventions and the no-fabricated-reviews resolution). +- [`luxe-considered-curated-stays-directory.md`](luxe-considered-curated-stays-directory.md) - Pure-luxe-considered directory-marketplace register applied to an aspirational curated short-term-stays marketplace (the second directory-marketplace entry; the same-shape divergence partner to the trades directory, showing the shape across two opposite registers; reframes the multi-provider conventions for hosts and stays). + +Each seed file was built against a real shipped demo or shipped brief and reflects the references that build drew from. As the portfolio grows, the bank grows with it. diff --git a/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md b/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md new file mode 100644 index 0000000..3717ecd --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md @@ -0,0 +1,23 @@ +# Bold-confident-editorial-restrained, AAA-adjacent action game studio + +- **Archetype**: `bold-confident` with `editorial-restrained` as the composition secondary. The lead is the cinematic-confident register of AAA-adjacent action studios; the secondary is chrome restraint (the platform-versus-content distinction from the gaming and entertainment vertical file: a studio is the chrome around its games, so the chrome composes while the game key art carries the saturation). The composition is the explicit chrome-restraint dial: pure Bold Confident or composed-with-Vibrant-Saturated is reserved for single-game-title demos. +- **Vertical**: Corporate-portfolio (specifically AAA-adjacent action game studio: a content-creator studio that builds large-scale action games and presents itself as a serious craft-and-scale shop). +- **Position summary**: A studio whose chrome is composed and dark-mode-first, where each fictitious title's key art carries the saturation and energy. Cinematic full-bleed hero, titles portfolio strip, type-led studio band, careers band as the load-bearing conversion surface, dark CTA close. + +## Positive references + +- [bungie.net](https://bungie.net) - The canonical AAA-action studio chrome register: cinematic full-bleed key-art hero, dark-mode-first ground, restrained type chrome that lets the game art carry. Inherit the cinematic hero treatment, the dark ground, and the chrome restraint. +- [insomniac.com](https://insomniac.com) - Insomniac Games. The studio chrome at composed-cinematic; the titles portfolio surfaced with care. Inherit the titles-portfolio anatomy and the craft-proud-without-arrogance voice. +- [naughtydog.com](https://naughtydog.com) - Naughty Dog. The restrained-cinematic studio register; type-led studio band with the team presented at masthead density. Inherit the studio-band convention and the restrained-cinematic chrome. +- [remedygames.com](https://remedygames.com) - Remedy Entertainment. The composed-cinematic register at the studio level, with a smaller portfolio presented with editorial discipline. Inherit the title-detail-page-as-small-monograph anatomy. + +## Negative references + +- [steampowered.com](https://steampowered.com) - Steam. Platform chrome that hosts third-party content. Wrong vertical (platform, not studio); the platform chrome reads totally different from a studio's content-creator brand. +- [itch.io](https://itch.io) - Itch.io. Indie game platform; minimal chrome; wrong register and wrong vertical. +- Mobile and casual free-to-play studio sites (the bright-saturated multi-hue cartoon register of casual-mobile studio brands). Wrong register; a AAA-adjacent action studio is not casual-mobile. +- Streaming-service sites (netflix.com, hbomax.com). Adjacent Bold-Confident-leaning register but wrong vertical (streaming distribution vs studio creation). Netflix's content-as-hero treatment is a useful inheritance for the cinematic hero; the rest of Netflix's chrome is platform-distributor, not studio. + +## Extension note + +- Seeded from the Ironhold AAA-adjacent action studio brief (first portfolio entry in Bold Confident; first portfolio entry in the corporate-portfolio shape applied to a game studio). The brief is the gentler entry into Bold Confident in the showcase portfolio; the upcoming game-title demo is the leap into the saturated single-IP register. The studio composes with Editorial Restrained as the chrome-restraint dial so the title-demo can pull saturation further without colliding. The brief documents a Rule 4 WARN override on the full-bleed-image-with-overlay hero (the canonical AAA-studio cinematic treatment, four shipped matches but no archetype-family share so Rule 5 does not block; the override is justified by the new archetype carrying the shape into a completely different visual reading). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md b/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md new file mode 100644 index 0000000..a3e23c8 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md @@ -0,0 +1,24 @@ +# Bold-confident-vibrant-saturated, single-IP game-title marketing site + +- **Archetype**: `bold-confident` with `vibrant-saturated` as the composition secondary. The lead is the cinematic-confident register of AAA action titles; the secondary is the saturated leap (palette depth, type at title-card scale, key art as the load-bearing surface). This is the expressive content-brand end of the gaming and entertainment vertical, distinct from the studio-portfolio chrome that publishes the title. The pair to `bold-confident-editorial-restrained-aaa-game-studio`: the studio composes with Editorial Restrained chrome restraint, the single title composes with Vibrant Saturated to claim the saturation the studio reserved. +- **Vertical**: Single-IP marketing (specifically a post-launch AAA action game title: the marketing site where one shipped game lives, distinct from the studio portfolio that publishes it). The shape generalizes to any single published work (a single film, album, book, or show); the references here are the game-title instance. +- **Position summary**: A single published title's own brand, dark-mode-first, world-forward, where the world's own palette and the key art carry the saturation. Cinematic launch-poster hero, a trailer or curated key-art sequence, a world-immersion surface, a systems surface, a media gallery, and a follow-or-storefront conversion close. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (dark-mode-first, world-forward, saturated, cinematic) and pulls NO trade dress, layout, scroll behavior, font choice, or animation language from any specific real-game marketing site. Marketing-site mimicry is as off-limits as in-game resemblance. + +- [marathonthegame.com](https://marathonthegame.com) - The saturated single-IP marketing register at its most committed: a published title's own brand, dark-mode-first, with the title's palette and art carrying the saturation rather than the publisher's chrome. Inherit the world-forward saturated register; do NOT pull the flat-graphic identity or layout. +- [deathstranding.com](https://deathstranding.com) - Single-IP world-immersion marketing: the site immerses the visitor in one world (the setting, the lore) in the game's own voice rather than the studio's. Inherit the world-as-protagonist surface; do NOT pull the atmospheric scroll, type, or identity. +- [cyberpunk.net](https://cyberpunk.net) - Saturated single-IP launch register: type at title-card scale, palette depth carrying the world's own tones. Inherit the type-at-scale and palette-depth treatment; do NOT pull the neon-magenta identity. +- [eldenring.bandainamcoent.com](https://eldenring.bandainamcoent.com) - Single-IP lore-immersion marketing: a world page that treats the world as the protagonist with deep lore in the title's voice. Inherit the lore-immersion surface; do NOT pull the dark-fantasy identity. + +## Negative references + +- Studio and publisher portfolio sites ([bungie.net](https://bungie.net), [naughtydog.com](https://naughtydog.com), and the paired `bold-confident-editorial-restrained-aaa-game-studio` register) - The studio chrome composes and recedes to let many titles share a body of work. The single-IP title's register is the saturated content brand, distinct from the publisher's chrome; a single title is not a portfolio. +- Platform-chrome sites ([steampowered.com](https://steampowered.com), [store.epicgames.com](https://store.epicgames.com), [itch.io](https://itch.io)) - Platforms host third-party content and lean restrained to let the content carry. A single-IP marketing site is the content's own brand, not the platform that distributes it. +- Casual and mobile single-game marketing sites (the bright multi-hue cartoon register of casual-mobile single-game brands) - Wrong register; an AAA cinematic title is dark-mode-first and world-forward, not bright-cartoon. + +## Extension note + +- Seeded from the Mariner's Gauntlet single-IP marketing brief (first portfolio entry in the single-IP marketing shape; the title side of the Ironhold pair; the first portfolio entry composing with Vibrant Saturated). The title claims the saturated single-IP register that the paired studio brief (`bold-confident-editorial-restrained-aaa-game-studio`) deliberately reserved as forward-divergence headroom. The brief documents the framework's first Rule 5 BLOCK against a same-pair shipped demo: `full-bleed-image-with-overlay` is blocked (five shipped matches plus a shared Bold Confident family with the publisher Ironhold), so the title selects `centered-single-column` as a cinematic launch-poster hero, the intended divergence-within-the-pair. Footer is `newsletter-band-with-credits` (the follow-the-title conversion). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md new file mode 100644 index 0000000..6e98079 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md @@ -0,0 +1,22 @@ +# Editorial-restrained, documentary-honest, specialty coffee subscription + +- **Archetype**: `editorial-restrained` with `documentary-honest` as the composition secondary. The lead is editorial type-led restraint (low-saturation, generous whitespace, considered typography); the secondary is documentary farm and bean photography that grounds the single-origin claim. Premium but approachable; not luxury, not mass-market. +- **Vertical**: DTC food and beverage (specifically specialty coffee subscriptions; the references generalise to tea and other consumable single-origin subscriptions in adjacent registers). +- **Position summary**: A specialty single-origin coffee subscription in the editorial-restrained register. Subscriber-first commerce (cadence picker, pause and swap surfaced as features, not buried in account settings). Named farms, named processes, named roast dates. Documentary farm photography supports the type rather than leads. + +## Positive references + +- [drinktrade.com](https://drinktrade.com) - Subscriber-first commerce explicit: cadence picker on the home, match-quiz to find your roast, pause and swap surfaced as features rather than buried in account settings. Editorial-restrained type-led layout with documentary product photography. +- [counterculturecoffee.com](https://counterculturecoffee.com) - Specialty roaster with subscription surfaced; documentary photography of farms and farmers carries the page; editorial type. The canonical reference for "farm-direct specialty roaster with a subscription option." +- [onyxcoffeelab.com](https://onyxcoffeelab.com) - Editorial-restrained register at its most refined: type-led, considered photography, premium-but-approachable. Useful as the type-system reference (small-caps, restrained tracking, editorial serifs). +- [atlascoffeeclub.com](https://atlascoffeeclub.com) - Subscriber-first explicitly with a world-coffee-journey narrative. The closest match to the "one origin a month, named farm, named process" positioning. Useful for how to surface the rotation as the value prop. + +## Negative references + +- [starbucks.com](https://starbucks.com) - Mass-market grocery register; frappuccino lifestyle photography; promotional cadence dominates the homepage. The register a specialty roaster must not pull from. +- [folgers.com](https://folgers.com) - Commodity grocery brand; blue-can heritage but no specialty register. The bottom of the grocery shelf, conceptually. +- Generic lifestyle-influencer subscription boxes (BarkBox, FabFitFun, Allure Beauty Box and similar) - Lifestyle-spectacle subscription register where the unboxing is the product; the box itself is supposed to be a surprise. Wrong register entirely for a specialty-coffee subscription where the named farm and the roast date are the value, not the unboxing reveal. + +## Extension note + +- Seeded by the Northbound Coffee Co. brief (Phase 2 live pressure-test of the creative-brief-selector skill, rampstack/rampstackco-app PR #131). The brief was the first live invocation of the selector and discovered these references during step 3 because the bank had no seed for the specialty-coffee-subscription combination. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md new file mode 100644 index 0000000..a6c7c02 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md @@ -0,0 +1,25 @@ +# Editorial-restrained, literary quarterly + +- **Archetype**: `editorial-restrained` (pure, no composition secondary). The lead is the literary quarterly tradition: typography carries the page, the considered editorial register, the restrained accent, and the absence of marketing inflation. +- **Vertical**: Editorial publication (specifically themed literary and ideas quarterly with multi-author masthead, each issue organized around a single question or theme). +- **Position summary**: A themed literary quarterly where each issue is a single question, the table of contents reads as variations on the question across disciplines, the design is restrained-considered with one literary accent colour. Not politically situated, not generationally branded, not topical, not single-author. The audience is literary readers across disciplines. + +## Positive references + +- [aeon.co](https://aeon.co) - Multidisciplinary ideas register. Considered design, restrained palette (warm-grey ground with deep type and a single accent), essays at substantial length, multiple disciplines per surface. Inherit the ideas-led register, the considered-but-not-luxe typography, the absence of marketing inflation. +- [thepointmag.com](https://thepointmag.com) - Themed multi-author essay structure at length. The closest peer on the audience axis (broadly literary readers across disciplines). Inherit the multi-author themed-issue treatment and the essay-length expectation. +- [cabinetmagazine.org](https://cabinetmagazine.org) - The closest structural anchor in the field: each issue is organized around a single thematic question rendered with editorial restraint. Inherit the single-theme-per-issue structure and the question-as-masthead treatment. +- [canopycanopycanopy.com](https://canopycanopycanopy.com) - Triple Canopy. Themed digital-first sequenced issues with editorial restraint. Inherit the digital-first design discipline and the sequenced-issue numbering. + +## Negative references + +- [thedriftmag.com](https://thedriftmag.com) - Politically situated, generationally branded, identity-forward. A considered quarterly must avoid the political-statement register on conversion architecture, palette, and voice. +- [nplusonemag.com](https://nplusonemag.com) - Institutional NY cultural authority register. A considered quarterly should not borrow the geographic or generational positioning. +- [laphamsquarterly.org](https://laphamsquarterly.org) - Historical-source-driven format (passages from historical writing assembled around a theme). A different format entirely; canonical to that publication and not transferable. +- [believermag.com](https://believermag.com) - McSweeney's-adjacent geometric illustration identity. A type-led quarterly should not borrow the illustration-led visual treatment. +- [atavist.com](https://atavist.com) - Single-essay-per-issue reportage register. A multi-essay themed quarterly is a different shape. +- [themarginalian.org](https://themarginalian.org) - Single-author blog register. A multi-author themed quarterly is a different shape. + +## Extension note + +- Seeded from the Caesura editorial-publication brief (the first portfolio entry in the editorial-publication shape, using the extended creative-brief-selector framework with hero_shape and footer_shape as first-class outputs). The pure `editorial-restrained` archetype combined with the type-led-prose hero and editorial-colophon-with-masthead footer renders as the natural literary-publication fit; the framework's extended rules align with the register's tradition rather than fighting it. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md b/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md new file mode 100644 index 0000000..ec9fae5 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md @@ -0,0 +1,20 @@ +# Heritage local service, barbershop + +- **Archetype**: `warm-conversational` with `retro-nostalgic` as the composition secondary. The lead is warm-everyday-craft (real-room atmosphere, social proof from genuine reviews, real-team page); the secondary is period-specific cues (walnut wood, brass fittings, marble counters, restrained palette). +- **Vertical**: Hospitality and local service (specifically neighborhood barbershops). +- **Position summary**: A heritage neighborhood shop with craft-and-space-led atmosphere, real-people-real-work proof, social proof drawn from review aggregates rather than fabricated testimonials. Initials over fabricated portraits when fictitious-brand demos cannot ethically render faces. + +## Positive references + +- [therosemontbarbers.com](https://therosemontbarbers.com) - Cuts gallery, interior atmosphere, social-proof badge, real team page in the heritage register. +- [speakeasybarberlounge.com](https://speakeasybarberlounge.com) - Atmosphere-led, period-specific cues (lounge fittings, warm interior), interior photography carries the page. +- [franksdenver.com](https://franksdenver.com) - Heritage register at a higher-end price point; restrained palette, considered editorial layout. +- [alfanisbarbershop.com](https://alfanisbarbershop.com) - Small-operator heritage, atmosphere-forward, real-team page. + +## Negative references + +- The chain barbershop register (Great Clips, Supercuts, Sport Clips and the like) - High-volume operational chains in the same vertical but in a fundamentally different register: utility-led, promotion-driven, no atmosphere. A heritage maker pulling from this register loses the position. + +## Extension note + +- Seeded from the Iron and Rye Barbershop atmosphere imagery pass. The seed positive references were used as register cross-checks during the build's still-life and interior shots. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md b/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md new file mode 100644 index 0000000..3b4fced --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md @@ -0,0 +1,20 @@ +# Hospitality experience, balloon ride + +- **Archetype**: `documentary-honest` with `luxe-considered` as the composition secondary. The lead is photography-led documentary realism (real landscape, real light, the morning as it actually looks); the secondary is aspirational-experience polish (named arc, named prices, named safety signals). +- **Vertical**: Hospitality experience (specifically scenic flight or ride experiences, with the balloon ride as the worked example). +- **Position summary**: A photography-led experience operator with the morning arc surfaced explicitly, named packages with named prices above the fold, four trust signals (FAA certification, lead pilot hours, weather posture, cancellation) surfaced as the booking-confidence layer. No fabricated identifiable faces; environmental imagery only. + +## Positive references + +- [napavalleyaloft.com](https://napavalleyaloft.com) - Regional operator, atmosphere-forward, dawn-palette imagery. +- [aerogelichotairballooning.com](https://aerogelichotairballooning.com) - Atmosphere-led, ride arc surfaced, photography drives the page. +- [rainbowryders.com](https://rainbowryders.com) - Multi-region operator, photography-led, named packages with prices. +- [sundanceballoons.com](https://sundanceballoons.com) - Multi-region operator, considered-warm register, ride-arc framing. + +## Negative references + +- Generic adventure-tour aggregators (Viator, GetYourGuide, and similar) - Stock photography pile, undifferentiated palette, transactional layout. A photography-led operator pulling from this register loses the atmosphere that justifies the price. + +## Extension note + +- Seeded from the Drift and Dawn imagery pass and the audited-field competitor set used during that build's Stage 1. The dawn-palette retune was driven by the gap between the original stone-and-amber default and the actual dawn light these references carry. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md b/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md new file mode 100644 index 0000000..52aff00 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md @@ -0,0 +1,33 @@ +# Luxe-considered, curated short-term-stays directory-marketplace + +- **Archetype**: `luxe-considered` (pure; no composition secondary). The aspirational curated-stays register the hospitality vertical file names as Aman and Four Seasons: serif-led, understated authority, image-forward, the stay as a designed object. The escapist warmth is carried by a warm palette and a host-voice convention, not by a second archetype. Documentary Honest (the mass-market Airbnb register and a recurring portfolio secondary), Editorial Restrained (another build's exact luxe composition string), and Warm Conversational (the review-platform register) were each considered and rejected as secondaries; pure Luxe is the fit. +- **Vertical**: Directory-marketplace (specifically an aspirational curated short-term-rental marketplace of many independent hosts' standout stays). The second directory-marketplace entry in the bank; with the trades-directory entry it shows the shape across two opposite registers (functional-tool versus escapist-aspirational). +- **Position summary**: A small, curated marketplace a traveler dreams through, where the property photography carries the page and the stay is the product. Image-forward, escapist, design-forward; inventory grouped into curated collections; trust built on a stated verification claim rather than a fabricated-metric arms race. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (curated collections, image-forward discovery, the property-as-monograph, restrained booking affordances) and pulls NO palette, type, trade dress, photography style, or grid treatment from any specific real platform. + +- [plumguide.com](https://plumguide.com) - The curated-design short-term-stay register: a small vetted collection rather than the long tail, each stay presented with editorial care. Inherit the curated-collection posture and the property-as-monograph anatomy; do NOT pull the palette, type, or the specific listing-grid treatment. +- [boutique-homes.com](https://boutique-homes.com) - The design-led curated-stays register: architecturally distinctive properties grouped by design feeling. Inherit the design-forward collection grouping and the generous property gallery; do NOT pull the trade dress. +- [onefinestay.com](https://onefinestay.com) - The upper-curated hospitality register: a small set of standout homes with a hotel-grade presentation. Inherit the restrained-confident chrome and the aspirational photo direction; do NOT pull the palette or the brand identity. + +## Negative references + +- Functional-tool consumer directories (the trustworthy-direct-functional trades-directory neighbourhood; the same directory-marketplace shape in the opposite register). The functional tool a user controls is the deliberate opposite of the escapist marketplace a traveler dreams through; the shape and the multi-provider conventions are shared, the register is inverted. +- Single-operator hospitality-experience brands (one operator selling its own arc). The count axis differs: a curated-stays marketplace lists many independent hosts, not one operator's owned experience. +- Mass-market transactional rental platforms (the high-volume long-tail booking engines with urgency banners, opaque ranking, and dense result grids). Wrong register: a curated marketplace presents a small standout set as a publication, not the whole inventory as a funnel. + +## Multi-provider conventions (reframed for hosts and stays) + +The directory-marketplace shape's multi-provider conventions (first encoded by the trades-directory entry) carry forward, reframed from providers to hosts and stays: + +- **Brand versus host voice.** The marketplace brand's voice is the site voice throughout; each property carries a short host voice (a one-line note on why the place is worth the trip) only inside its card and detail, set with a typographic voice-shift. The brand never speaks as a host; hosts never speak as the brand. +- **Discoverability is the spine, image-forward.** The home is a search-and-browse surface where the property photography carries the page (the aspirational counterpart to the functional-categorical discovery of a trades directory). The hero is image-forward, not a functional tile grid. +- **Listing density, organized as collections.** Curated themed collections (coastal escapes, design landmarks, mountain retreats) rather than flat categories; roughly 4 to 6 collections with 4 to 8 properties each (24 to 40 properties). The collection is itself an editorial act. +- **Comparison surface.** Properties comparable within a collection on a small honest set (location, sleeps, stay-type, a demo-only rate band), with a within-collection compare view. +- **Reviews-and-ratings honesty resolution.** A demo-only Verified Host badge with its meaning stated plainly, plus an explicit "Demo: no reviews shown" placeholder slot and an aggregate-rating placeholder. The full trust UX is visible without fabricating a single review, rating, or superhost-style metric. Hosts are represented by their properties and a one-line voice, NOT by fabricated headshots; properties are set in fictitious locations; no real platform is named, even in negation. + +## Extension note + +- Seeded from the Lodestar curated-stays marketplace brief (the fifteenth and final showcase demo; the second directory-marketplace shape and the same-shape divergence partner to the trades-directory entry, running maximal-distance mode within the shape). Anchored to the hospitality and travel vertical file (`12-hospitality-travel.md`), which names pure Luxe Considered as the aspirational-hospitality register and Documentary Honest as the mass-market Airbnb register. The styled-aspirational property photography carries a real drift profile for the imagery pass: real-listing-platform aesthetic mimicry and fabricated-location-resemblance, both flagged for the build's NEGATIVE_GUARDRAILS, plus no real brand marks in any property image. The palette must read warm-aspirational (a design-hotel sandstone-clay-brass family) and must not reuse the trades-directory's cool functional family or any shipped warm-hospitality family. Last updated: 2026-05-29. diff --git a/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md b/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md new file mode 100644 index 0000000..aaf9c53 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md @@ -0,0 +1,23 @@ +# Luxe-considered-editorial-restrained, residential architectural brokerage + +- **Archetype**: `luxe-considered` with `editorial-restrained` as the composition secondary. The lead is the gallery-monograph register: premium, considered, type-and-photography-led, design-literate. The secondary is design-publication restraint: listings rendered as small monographs, the architect-and-year credit at byline weight, the brokerage represented as a practice rather than as a roster of agents. +- **Vertical**: Inventory-listing (specifically residential brokerage of architecturally significant homes: modernist, mid-century, architect-designed new builds, design-forward renovations). +- **Position summary**: A luxe residential brokerage that treats each architecturally significant home as a small monograph. The architect, the design year, the materials, the siting, and the light are first-class fields on every listing. The brokerage speaks as a design-literate practice rather than as a roster of individual agents. + +## Positive references + +- [themodernhouse.com](https://themodernhouse.com) - The canonical reference for the design-led residential brokerage register at editorial-restrained tier. Each listing reads as a small monograph; the architect is named in the listing card; the photography is disciplined. Inherit the listing-as-monograph anatomy and the considered-restraint voice. (Cited as a register anchor, not for trade dress copy; the negative-reference frame governs which brokerages a build must not pull trade dress from.) +- [phillips.com](https://phillips.com/design) - Phillips's design auction catalog register. The monograph treatment per lot (designer, year, materials, provenance) transfers cleanly to a residential listing. Inherit the per-lot monograph anatomy. +- [dezeen.com](https://dezeen.com) - The architectural press register. Listing-style architecture coverage with architect credits, year, materials, photography. Inherit the architecture-press literacy and the credit-line convention. +- [architecturaldigest.com](https://architecturaldigest.com) - The design-publication register with residential homes covered as design objects. Inherit the photography sensibility and the design-publication restraint. + +## Negative references + +- [zillow.com](https://zillow.com) - Mass-market portal; algorithmic listing presentation, estimated-value overlays, financing-first conversion. The register a luxe-considered brokerage must avoid on conversion architecture, palette, and voice. +- [realtor.com](https://realtor.com) - Same mass-market portal register; broker-listing-syndication shape, generic photography presentation. +- [redfin.com](https://redfin.com) - Mass-market portal with light brokerage layer; price-anxiety scoring, financing partnerships surfaced as primary CTAs. +- High-volume luxury brokerages whose primary surface is personality-led agent funnels. The architectural-monograph register is a practice, not a personal brand; the no-fabricated-agent-headshots line in the honesty contract is the structural rationale. + +## Extension note + +- Seeded from the Datum residential-brokerage brief (the first portfolio entry in luxe-residential-architectural-brokerage and the first same-shape divergence test in the portfolio; second inventory-listing build, the first being the rugged-utilitarian Treeline Motors marketplace). The brief documents the Section Shapes Rule 5 block on the two obvious luxe-architectural defaults (full-bleed-image-with-overlay and dual-column-image-and-text) and the resulting selection of asymmetric-large-image-small-text as the hero shape. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md b/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md new file mode 100644 index 0000000..5083d66 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md @@ -0,0 +1,34 @@ +# Minimal-essentialist-documentary-honest, local-trades directory + +- **Archetype**: `minimal-essentialist` with `documentary-honest` as the composition secondary. The lead is the functional-tool register (clean, organized, content-forward, reduced chrome; the page is the directory and the chrome recedes to let the listings carry). The secondary is honest-transparency trust (a stated verification claim, honest placeholders where reviews would render, real-context provider photography). The marketplace platform-versus-provider principle is the structural rationale: the directory brand must not compete with the provider identities, so restraint wins. +- **Vertical**: Directory-marketplace (specifically a homeowner-facing local-trades directory of many independent providers across real trade categories: plumbing, electrical, HVAC, carpentry, painting, roofing). The first multi-provider entry in the bank. +- **Position summary**: A clean, trustworthy directory tool the homeowner controls, light-mode-first, where the categories and the providers are the page. Discoverability is the spine, comparison is core, and the trust is built on honest transparency rather than on warmth or on clinical authority. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (search-first discovery, category browse, provider listings, a comparison surface, a verification claim) and pulls NO palette, trade dress, logo language, or conversion-funnel pattern from any specific real directory. + +- [angi.com](https://angi.com) - The modern consolidated home-services directory register: category-and-location search, provider listings, the lead-handoff conversion. Inherit the search-first discovery spine and the category structure; do NOT pull the orange-and-green palette, the match-now funnel, or any trade dress. +- [thumbtack.com](https://thumbtack.com) - The matched-services register: structured by trade and location, provider profiles with comparable fields. Inherit the comparable-provider-profile anatomy; do NOT pull the blue palette or the get-matched interstitial funnel. +- [houzz.com](https://houzz.com) - The visual-services-directory register: real work photography carrying the provider listings. Inherit the documentary work-in-context photography direction (a trade in progress, a finished job), not glamour shots; do NOT pull the green-and-orange palette or the social-feed product framing. + +## Negative references + +- Warm-conversational single-provider service brands (a neighbourhood barbershop, a single local shop's site; the heritage-local-service register). Wrong register and wrong count: that is a single provider speaking warmly about itself, not a directory of many providers in a functional-trust tool. A trades directory must not read as one warm shop with extras. +- Magazine-editorial services-content sites (a home-improvement publication, a services-advice editorial). Wrong register: a directory is a functional tool, not a magazine pretending to be a directory; the editorial-publication register buries the listing density behind a narrative. +- Bold-cinematic or saturated AAA visual registers (a cinematic full-bleed experiential hero). Wrong register entirely: a directory reads functional, not experiential; an image-and-overlay cinema-poster hero is the opposite of the page-is-the-directory discovery spine. + +## Multi-provider conventions (new ground; inherited by future directory-marketplace briefs) + +The directory-marketplace shape is the first multi-provider register in the portfolio. These conventions are first-class and carry forward: + +- **Brand versus provider voice.** The directory brand's voice is the site voice throughout; each provider has its own short voice only inside its listing card (a one-line how-we-work statement). The directory speaks as the trustworthy tool; the providers speak as themselves inside their cards. (Single-provider builds never had to navigate this distinction.) +- **Discoverability is the spine.** The home page is a search-and-browse surface (category-and-location search, category tiles, provider cards), not a hero-and-essay narrative. A `grid-of-elements` hero fits naturally; a type-led or image-and-overlay hero does not. +- **Listing density.** A meaningful directory reads as real only at sufficient density: roughly 4 to 6 categories with 4 to 8 providers each (16 to 48 total). Fewer reads as a single-provider demo with extras; more risks bloat. +- **Comparison surface.** Providers within a category are comparable on a small honest set of dimensions (service area, specialties, years in business), not on an opaque ranking score. Comparison is core to the pattern. +- **Reviews and ratings are the canonical fabrication risk, and the resolution is honest UX without fabricated content.** A directory conventionally shows aggregate ratings, review counts, and written reviews; a demo cannot fabricate any of them. The resolution: an explicit "Demo: no reviews shown" placeholder slot where review content and an aggregate rating would render, plus a demo-only "Verified Pro" badge (the directory's own badge, meaning stated, not a real accreditation) where earned. The directory's full trust UX is visible without a single fabricated review, rating, license number, or certification. +- **Real categories, fictitious providers.** The trade categories are real; the providers within them are demo-fictitious, with names vetted against recognizable businesses (a proprietor-surname-plus-trade format), set in a fictitious city, with schematic service-area maps and no fabricated license numbers, certifications, or accreditation marks. + +## Extension note + +- Seeded from the Tradepost local-trades directory brief (the first directory-marketplace shape and the first multi-provider demo in the portfolio; the seventh selector-led build). The brand-archetype-system has no dedicated home-services, local-services, or trades vertical file; this build used `16-marketplace.md` (the two-sided-platform register) as the closest anchor, and the gap is flagged for a future skill-extension dispatch to add a dedicated local-services-and-trades vertical file. Tradepost runs maximal-distance mode; it is the same-shape divergence partner to a forthcoming vacation rental marketplace (the Browse-AI attended capstone), and the two diverge naturally because the verticals differ. The palette deliberately avoids the recognizable real-brand directory colours (Angi orange-and-green, Thumbtack blue, HomeAdvisor orange, Yelp red, Houzz green-and-orange, Yellow Pages yellow-and-black). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md b/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md new file mode 100644 index 0000000..8a7d341 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md @@ -0,0 +1,22 @@ +# Premium DTC maker, western boots + +- **Archetype**: `luxe-considered` with `rugged-utilitarian` as the composition secondary. The lead is premium-considered (editorial layout, prices visible, restrained merchandising); the secondary is workwear-and-craft (heritage materials, hand-welt construction, made-to-last positioning). +- **Vertical**: DTC fashion (specifically western boots). +- **Position summary**: A premium small-collection western-boot maker, leather-forward, product-photographed, prices visible, no discount cadence, no SKU-strip-above-the-fold. Confident, not promotional. + +## Positive references + +- [tecovas.com](https://tecovas.com) - The elevated-DTC reference: product-forward hero, named prices visible, restrained merchandising. No discount banners above the fold. +- [lucchese.com](https://lucchese.com) - Heritage register; serif-led, craft narrative as a supporting band rather than the lead. +- [oldgringoboots.com](https://oldgringoboots.com) - Smaller-maker, leather-forward photography, restrained editorial set instead of catalog density. +- [ranchroadboots.com](https://ranchroadboots.com) - Small-operator boutique competing in the same position; useful for cross-checking how a peer maker handles wayfinding on a small collection. + +## Negative references + +- [durangoboots.com](https://durangoboots.com) - Catalog-dense big-box texture; discount cadence, SKU-strip-above-the-fold, sale-badge pile. Not the register a premium small maker should pull from. +- [justinboots.com](https://justinboots.com) - Same big-box texture in a different brand; promotional banners and grid density dominate. +- [bootbarn.com](https://bootbarn.com) - Multi-brand retailer rather than a maker; merchandising-led rather than craft-led. + +## Extension note + +- Seeded from the Pinto Mesa Boots store-spine brief (the worked example of the brief template). Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md b/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md new file mode 100644 index 0000000..b260e05 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md @@ -0,0 +1,24 @@ +# Rugged-utilitarian-documentary-honest, regional used-vehicle marketplace + +- **Archetype**: `rugged-utilitarian` with `documentary-honest` as the composition secondary. The lead is workwear-and-craft (Mountain West heritage utility register); the secondary is data-forward documentary (transparency-first listings, real photography, real source attribution). +- **Vertical**: Inventory-listing (specifically regional used-truck-and-SUV marketplace serving working-vehicle buyers, not full passenger-car market). +- **Position summary**: A regional working-vehicle specialist marketplace, transparency-first on every listing, documentary photography of vehicles in working context, plain-direct voice that speaks with familiarity of the terrain its audience drives. Specialist, not generalist; transparent, not promotional; regional, not national. + +## Positive references + +- [bringatrailer.com](https://bringatrailer.com) - The canonical listing-detail transparency reference: full ownership history, mileage timeline, photograph density (forty to one hundred photographs per lot is typical), a comments thread that adds provenance. Inherit the listing-detail anatomy and the source-attributed transparency posture. Diverge from the auction format; a fixed-price marketplace borrows the transparency without the closing-clock. +- [icon4x4.com](https://icon4x4.com) - Editorial documentary register applied to working vehicles. Inherit the photography direction (vehicles photographed in landscape and at work, not glamour shots on a studio seamless), the considered editorial type, and the absence of promotional banners. +- [filson.com](https://filson.com) - Mountain West heritage workwear register. Inherit the palette tendency (granite, evergreen, oxblood, aspen gold; cool ground with restrained accents), the documentary photography that supports the type rather than fighting it, and the plain-direct voice. +- [patagonia.com](https://patagonia.com) - The adjacent outdoor-utility register, useful as the second positive on voice (plain-direct, no marketing inflation, the audience treated as competent). + +## Negative references + +- [cargurus.com](https://cargurus.com) - Mass-market national passenger-car register; price-anxiety scoring as the hero, financing-first conversion architecture. The register a specialist regional marketplace must avoid on conversion architecture, palette, and voice. +- [cars.com](https://cars.com) - Same mass-market national register; promotional banner cadence, broad-inventory generalist posture. +- [carvana.com](https://carvana.com) - DTC mass-market with vending-machine theatrics, financing-first. The register to avoid on theatrics and on conversion-flow priority. +- [autotempest.com](https://autotempest.com) - Meta-aggregator with no editorial voice; utility-only search-across-the-others. A specialist marketplace must not read as utility-only. +- [edmunds.com](https://edmunds.com) - Research-led advisory; content-heavy editorial sitting adjacent to a marketplace. A specialist marketplace must not read as a magazine pretending to be a marketplace. + +## Extension note + +- Seeded from the Treeline Motors inventory-listing brief (the second batch-two build using the creative-brief-selector skill end to end). The Bring a Trailer reference is dual-positioned: positive on listing-detail transparency, negative on format (auction vs fixed-price marketplace). Last updated: 2026-05-27. diff --git a/skills/creative-brief/SKILL.md b/skills/creative-brief/SKILL.md new file mode 100644 index 0000000..8e18b1c --- /dev/null +++ b/skills/creative-brief/SKILL.md @@ -0,0 +1,158 @@ +--- +name: creative-brief +description: "Create or refine a creative brief that bridges discovery and execution. Use this skill whenever the user is starting a new project, kicking off a website, beginning a brand build or redesign, briefing a designer or developer or AI agent, or trying to align a team before building. Triggers on creative brief, design brief, brand brief, project kickoff, kicking off, briefing the team, project intake, design direction, brief the designer, brief the dev, where do we start, how do we start, write a brief, project overview, scope this project, align on direction. Also triggers when the user has a vague idea and needs to make it concrete enough to hand off, even if they do not say 'brief' explicitly." +category: strategy-and-discovery +catalog_summary: "Project briefs that align stakeholders before work starts" +display_order: 2 +--- + +# Creative Brief + +Bridges discovery and execution. Translates "we want a website" into a brief a designer, developer, or AI agent can actually run with. + +--- + +## When to use + +- Starting a new project (website, app, brand, campaign) +- Kicking off a redesign or rebrand +- Handing work to a designer, developer, or AI agent +- Aligning a team that has drifted off course +- Turning a vague idea into something buildable + +## When NOT to use + +- The user is asking a one-off design question (use `design-standards`) +- The user wants a PRD or dev ticket (use `pm-spec-writing`) +- The user is doing initial research and has not decided what they are building (use `brand-discovery` first) +- The user just wants you to write copy (use `content-and-copy`) +- The user already has scope and constraints settled and needs deeper aesthetic direction specifically (use `creative-direction` for the structured aesthetic axes) + +--- + +## Required inputs + +A brief needs answers to ten questions. Before writing, confirm you have answers (or can elicit them) for: + +1. What is the project? +2. Why does it exist? What problem does it solve? +3. Who is the audience? +4. What do you want them to do, feel, or know? +5. What is the personality? How does it sound? +6. What is the visual direction? How does it look? +7. What is in scope? What is out? +8. What are the constraints (time, budget, technical, brand)? +9. What does success look like? +10. Who approves? + +If you have fewer than five of these, run a quick intake first. See "Eliciting missing info" below. + +--- + +## The framework: brief structure + +Output a markdown brief with these ten sections. Keep each section tight. A good brief is two pages, not ten. + +### 1. Snapshot +One paragraph answering: what, who, why, when. The kind of thing you would say at a kickoff in thirty seconds. + +### 2. Audience +Primary audience first. Include who they are, what they are trying to do, what is blocking them today, and where you reach them. Add secondary audiences only if they materially change the work. + +### 3. Objectives +What success looks like. Pair every objective with a measurable signal. + +> Objective: drive trial signups. +> Signal: 3 percent conversion from homepage to signup within 30 days of launch. + +### 4. Key message +The one thing you want a visitor to walk away knowing. If they see only the homepage hero and bounce, what should they remember? One sentence. + +### 5. Voice and tone +Pick three to five adjectives. Pair each with what you are NOT (e.g. "confident, not arrogant"). See [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) for frameworks and worked examples. + +### 6. Visual direction +Mood, palette, type, and imagery direction. Three to five reference URLs are worth more than 500 words. Note what you like AND what you would reject. + +### 7. Scope and deliverables +A bulleted list of what is being made. Be specific. "Homepage" is not a deliverable. "Homepage with hero, three feature blocks, testimonial carousel, and contact CTA" is. + +### 8. Constraints +Time. Budget. Technical (existing stack, required integrations, hosting). Brand (logo, colors, fonts that must be used). Legal (compliance, accessibility level required). + +### 9. Inspiration and competitors +Three to five sites or brands you want to feel like, three to five you want to feel different from. Note WHY for each. + +### 10. Approval +Who signs off. What artifact triggers sign-off (a Figma file, a staging URL, a PDF). What happens if there is no sign-off by a deadline. + +--- + +## Eliciting missing info + +If the user comes with a partial answer (e.g., "I want a website for my coffee shop"), do not just write a generic brief. Ask. Use these prompts. + +**For audience** +- Who is the single most likely person to land on this site? Walk me through their day. +- If you could pick one type of customer to fill your inbox, who? +- Who do you NOT want to attract? + +**For objectives** +- Pretend it is six months after launch. What number tells you it worked? +- What is the one action you most want a visitor to take? + +**For voice** +- Pick three brands or people whose tone you would want to borrow. +- If your site were a person at a dinner party, what would they sound like? + +**For visuals** +- Show me three sites you love. What do you love about them? +- Show me one site you hate. Why? + +**For scope** +- If you only got one page, which one? +- What would you cut if the budget were halved? + +Do not ask all of these. Pick the ones that fill the actual gaps. + +--- + +## Workflow + +1. **Read the conversation.** Pull every fact already given. Do not ask questions you can answer from context. +2. **Identify gaps.** Which of the ten required inputs are missing or thin? +3. **Run intake.** Ask three to five targeted questions to fill the gaps. Group related questions to keep the conversation tight. +4. **Draft the brief.** Use [`references/creative-brief-template.md`](references/creative-brief-template.md) as the structure. Keep it under 1500 words. +5. **Stress-test.** Before delivering, check the brief against the failure patterns below. If any apply, revise before showing the user. +6. **Deliver.** Save as `creative-brief.md` in the project root. Offer to make it a Word doc or PDF if the user wants something to share with stakeholders. +7. **Hand off for aesthetic depth (optional).** For projects where sections 5 (voice and tone) and 6 (visual direction) need more rigor than this brief surfaces, run `creative-direction` next. It produces a structured aesthetic brief using four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) that content, copy, and art-direction skills consume directly. + +--- + +## Failure patterns + +When the user's input matches one of these patterns, push back before writing. + +- **"We want to be the [giant brand] of [our niche]."** Ask what specifically about that brand they want to borrow. Probably one or two things, not the whole thing. +- **Audience as "men and women 18-65."** This is not an audience. Ask for the single most valuable customer type and start there. +- **"Increase awareness" with no metric.** Awareness of what, by whom, measured how? Push for a number. +- **"Modern, clean, minimalist."** These words are meaningless. Ask for three specific URLs they think look right. +- **Twenty pages of context, no clear ask.** Ask: "If a designer reads only one paragraph, what should it be?" Then make that the snapshot. + +--- + +## Output format + +Default output is a markdown file at `creative-brief.md` in the project root. Structure follows the template exactly. + +If the project is large, split: keep the main brief under 1500 words and put detail in linked appendices (`audience-research.md`, `brand-guidelines.md`, etc.). Briefs that try to be everything end up read by no one. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Fillable template. Copy and use as the starting point. +- [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) - Voice frameworks, brand archetypes, and worked patterns. +- [`references/example-brief.md`](references/example-brief.md) - A worked example for a fictional B2B SaaS, showing what a "good" filled brief looks like. + +Read the template before drafting. Read the voice guide if the user has not already specified a voice. Read the example if you are unsure how filled-out a section should be. diff --git a/skills/creative-brief/references/creative-brief-template.md b/skills/creative-brief/references/creative-brief-template.md new file mode 100644 index 0000000..7d57fc3 --- /dev/null +++ b/skills/creative-brief/references/creative-brief-template.md @@ -0,0 +1,185 @@ +# Creative Brief: [Project Name] + +**Date:** [YYYY-MM-DD] +**Author:** [Who wrote this brief] +**Stakeholders:** [Who needs to sign off] +**Status:** Draft / In review / Approved + +--- + +## 1. Snapshot + +[One paragraph. What is this project, who is it for, why does it exist, and when does it need to be done? Aim for 3 to 5 sentences.] + +**Quick facts** +- Project type: [Website / app / brand / campaign / other] +- Launch target: [Date or quarter] +- Budget tier: [Range or "to be confirmed"] +- Stack constraints: [Required tech or "open"] + +--- + +## 2. Audience + +**Primary audience** + +Who: [One specific persona, not a demographic range] + +What they are trying to do: [The job they are hiring this product to do] + +What is blocking them today: [The friction they are experiencing now] + +Where you reach them: [Channels: search, social, referral, paid, etc.] + +**Secondary audience** (only if it changes the work) + +[Same structure, briefer.] + +**Anti-personas** + +- [Type of customer you do NOT want to attract, and why] + +--- + +## 3. Objectives + +| Objective | Measurable signal | Timeframe | +|---|---|---| +| [What you want to achieve] | [How you know it worked, with a number] | [When you measure] | +| | | | +| | | | + +--- + +## 4. Key message + +[One sentence. If a visitor saw only the hero and bounced, what should they remember?] + +--- + +## 5. Voice and tone + +**We sound:** [3 to 5 adjectives] + +**We do not sound:** [The mirror image of each adjective] + +| We are | We are NOT | +|---|---| +| [Adjective] | [What it could tip into if overdone] | +| | | +| | | + +**Examples of our voice in the wild** + +- [Brand or writer 1, and what specifically about them] +- [Brand or writer 2, and what specifically about them] + +--- + +## 6. Visual direction + +**Mood:** [3 to 5 words] + +**Palette direction:** [Light/dark, warm/cool, saturated/muted, plus any required brand colors] + +**Type direction:** [Serif/sans, display vs body, formal vs casual] + +**Imagery direction:** [Photography style, illustration style, iconography] + +**Reference sites we want to feel like** + +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] + +**Reference sites we want to feel different from** + +- [URL]: [What we are rejecting] +- [URL]: [What we are rejecting] + +--- + +## 7. Scope and deliverables + +**In scope** + +- [Specific deliverable 1, with detail] +- [Specific deliverable 2, with detail] +- [Specific deliverable 3, with detail] + +**Out of scope** + +- [Things explicitly not being built in this project] + +--- + +## 8. Constraints + +**Timeline** + +- [Milestone 1]: [Date] +- [Milestone 2]: [Date] +- [Launch]: [Date] + +**Budget** + +- [Range or specific number, plus what it covers] + +**Technical** + +- Existing stack: [What is already in place] +- Required integrations: [Analytics, CRM, payment, etc.] +- Hosting: [If specified] + +**Brand** + +- Required: [Logo, colors, fonts, marks that must be used] +- Available: [Brand assets the team can pull from] + +**Legal and compliance** + +- Accessibility level: [WCAG AA / AA+ / AAA] +- Privacy: [GDPR / CCPA / other] +- Industry: [Any sector-specific requirements] + +--- + +## 9. Inspiration and competitors + +**Inspiration (the feel we want)** + +| Site / brand | What we love | +|---|---| +| [URL] | [Specific element] | +| [URL] | [Specific element] | +| [URL] | [Specific element] | + +**Competitors (in our category)** + +| Site / brand | How we differ | +|---|---| +| [URL] | [Where we want to position differently] | +| [URL] | [Where we want to position differently] | + +--- + +## 10. Approval + +**Sign-off owner:** [Name, role] + +**Sign-off artifact:** [What needs to be approved: brief, comps, staging URL, etc.] + +**Sign-off deadline:** [Date] + +**If no sign-off by deadline:** [Default action: ship anyway, escalate, pause, etc.] + +--- + +## Appendix (optional) + +Link out to anything that would otherwise bloat the brief. + +- [Audience research] [link] +- [Competitive analysis] [link] +- [Brand guidelines] [link] +- [Technical requirements] [link] diff --git a/skills/creative-brief/references/example-brief.md b/skills/creative-brief/references/example-brief.md new file mode 100644 index 0000000..cef9a7f --- /dev/null +++ b/skills/creative-brief/references/example-brief.md @@ -0,0 +1,206 @@ +# Creative Brief: Plumb + +**Date:** 2026-04-15 +**Author:** Maria Chen, Founder +**Stakeholders:** Maria Chen (sign-off), Devon Park (engineering), Sasha Williams (design lead) +**Status:** Approved + +--- + +## 1. Snapshot + +Plumb is infrastructure observability built for small DevOps teams. We are launching a marketing site and product trial flow to support our public beta in Q3 2026. The site needs to convert technical buyers from a homepage visit to a trial signup, and clearly position us as the "right-sized" option against the heavy enterprise incumbents. Target launch: July 15, 2026. + +**Quick facts** +- Project type: Marketing website + trial signup flow +- Launch target: July 15, 2026 +- Budget tier: $25K design + dev, plus internal team time +- Stack constraints: Next.js + Vercel, with Supabase for the trial flow + +--- + +## 2. Audience + +**Primary audience** + +Who: A staff or principal engineer at a 20 to 200 person startup, currently the unofficial owner of the team's monitoring stack. They got handed Datadog two years ago, the bill is now embarrassing, and they want a defensible alternative they can sell internally. + +What they are trying to do: Cut the monitoring bill by at least 40 percent without taking on a tool that requires a dedicated SRE to operate. + +What is blocking them today: Datadog is too expensive and too sprawling. Grafana is technically free but burns engineering time on maintenance. Both feel built for someone three sizes bigger. + +Where you reach them: Hacker News, the changelog blog, lobste.rs, technical Twitter, dev-focused podcasts (Changelog, Software Engineering Daily), and search ("alternative to datadog", "self-hosted monitoring small team"). + +**Secondary audience** + +Engineering managers and CTOs at the same companies, who sign the invoice. They land later in the journey but need the pricing page and the ROI math to be airtight. + +**Anti-personas** + +- Enterprise procurement teams. We do not want to attract Fortune 500 inbound. The product is not built for that scale and we do not want to spend cycles on RFPs. +- Hobbyists who want a free forever tier. We have a generous trial but no free tier. Bargain hunters churn. + +--- + +## 3. Objectives + +| Objective | Measurable signal | Timeframe | +|---|---|---| +| Drive trial signups from organic and content channels | 200 trial signups per month within 90 days of launch | By Oct 15, 2026 | +| Convert trials to paid | 12 percent trial-to-paid conversion | By end of Q4 2026 | +| Establish technical credibility | 50+ inbound mentions on HN, lobste.rs, or dev Twitter referencing the site or docs | By end of Q3 2026 | +| Reduce sales cycle for inbound | Pricing page transparent enough that 80 percent of inbound deals close without a sales call | Ongoing | + +--- + +## 4. Key message + +Plumb is observability that fits a 50-person engineering team, priced for a 50-person engineering team. + +--- + +## 5. Voice and tone + +**We sound:** Direct, technical, confident, dry-witted, practical. + +**We do not sound:** Cute, hand-wavy, salesy, corporate, or condescending. + +| We are | We are NOT | +|---|---| +| Direct | Blunt or rude | +| Technical | Inaccessible to a non-expert reader | +| Confident | Boastful | +| Dry-witted | Trying to be funny | +| Practical | Boring | + +**Examples of our voice in the wild** + +- Stripe docs, for the rhythm and the way they assume reader competence without showing off. +- Tailscale's blog, for the dry technical wit and willingness to admit tradeoffs. +- 37signals' product copy, for short sentences that earn their place. + +--- + +## 6. Visual direction + +**Mood:** Calm, confident, technical, slightly opinionated. A senior engineer's notebook, not a stadium. + +**Palette direction:** Predominantly light with strong dark-mode parity. Single accent color (deep teal). Charts and diagrams in muted, accessible color ramps. No gradients, no glow effects. + +**Type direction:** Geometric sans for display (Inter or similar), monospace for code and metrics (JetBrains Mono or similar). Generous line height. Comfortable for long-form reading. + +**Imagery direction:** Real screenshots of the product, annotated. Architecture diagrams drawn in a consistent simple style. No stock photos. No abstract 3D illustrations. No people in headsets pointing at laptops. + +**Reference sites we want to feel like** + +- linear.app: For the calm density and how every pixel feels intentional. +- planetscale.com: For technical credibility without enterprise stuffiness. +- fly.io: For the dry voice and the unapologetic technical depth on the homepage. + +**Reference sites we want to feel different from** + +- datadoghq.com: Too dense, too many product lines, screams "we will sell you everything." +- newrelic.com: Too corporate, too gradient-heavy, feels like 2018. + +--- + +## 7. Scope and deliverables + +**In scope** + +- Homepage with hero, three feature blocks, social proof, pricing teaser, footer CTA +- Pricing page with transparent tiers, calculator, and FAQ +- Product page with annotated screenshots and one short demo video +- About page (founder story, team, hiring CTA) +- Trial signup flow (3 steps: email + workspace name + first project setup) +- Docs index page that links into the existing docs site (separate property) +- Blog index and post template (engineering writing, changelog posts) +- 404 and other error pages + +**Out of scope** + +- Customer logos page (we do not have permissioned logos yet) +- Comparison pages (Datadog vs Plumb, etc.) - saved for Q4 once we have data +- Localization (English only at launch) +- Marketing automation integrations beyond a single newsletter capture + +--- + +## 8. Constraints + +**Timeline** + +- Brief approved: April 15, 2026 +- Wireframes: April 30 +- High-fi design: May 20 +- Dev complete: June 30 +- QA and content load: July 1 to July 12 +- Launch: July 15 + +**Budget** + +- $25K total: $15K design, $10K dev contractor for trial flow integration. Internal team handles content, brand assets, deploy. + +**Technical** + +- Next.js App Router on Vercel +- Trial flow writes to Supabase (existing project) +- Plausible for analytics (no Google Analytics) +- All pages must score 95+ on Lighthouse performance and accessibility +- Mobile baseline: 375px + +**Brand** + +- Logo: existing wordmark + glyph (provided) +- Colors: deep teal (#0F4C5C), slate gray scale, white. Single accent only. +- Type: Inter for display, JetBrains Mono for code + +**Legal and compliance** + +- Accessibility: WCAG 2.1 AA +- Privacy: GDPR compliant. EU users get a banner. Data residency in US-East. +- No customer testimonials with full names without written consent + +--- + +## 9. Inspiration and competitors + +**Inspiration** + +| Site / brand | What we love | +|---|---| +| linear.app | Density without clutter; type system; restraint | +| planetscale.com | How they explain technical concepts in the hero | +| fly.io | Voice, blog rhythm, code samples on the homepage | +| stripe.com/docs | The annotated examples pattern (we want to borrow this for the product page) | + +**Competitors** + +| Site / brand | How we differ | +|---|---| +| datadoghq.com | We are smaller, opinionated, and priced for teams under 200 | +| newrelic.com | We avoid enterprise sprawl. Single product, clear pricing | +| grafana.com | We are managed and easier to operate. We charge for the time savings | + +--- + +## 10. Approval + +**Sign-off owner:** Maria Chen + +**Sign-off artifacts:** +- Wireframes: review by April 30, async approval in Figma +- High-fi design: review by May 20, in-person review meeting + 48-hour async window +- Pre-launch site (staging URL): review by July 10, all stakeholders sign off in writing + +**Sign-off deadline:** Each stage above has a 48-hour async window after the review meeting. After 48 hours of no objection, the stage is approved and we proceed. + +**If no sign-off by deadline:** Default to ship. Maria has final say on any post-launch revision. + +--- + +## Appendix + +- [Audience research notes](./audience-research.md) +- [Competitive teardown](./competitive-analysis.md) +- [Brand guidelines](./brand-guidelines.md) diff --git a/skills/creative-brief/references/voice-and-tone-guide.md b/skills/creative-brief/references/voice-and-tone-guide.md new file mode 100644 index 0000000..a8fb49d --- /dev/null +++ b/skills/creative-brief/references/voice-and-tone-guide.md @@ -0,0 +1,200 @@ +# Voice and Tone Guide + +Voice is who you are. Tone is how you sound right now. Voice stays constant. Tone shifts with context (a 404 page sounds different from an onboarding email, even if the voice is the same). + +This guide gives you frameworks for picking a voice and adapting tone, plus worked examples. + +--- + +## Framework 1: Four dimensions (Nielsen Norman) + +Pick a position on each axis. Together they describe the voice. + +| Dimension | One end | Other end | +|---|---|---| +| Formality | Formal | Casual | +| Seriousness | Serious | Funny | +| Respectfulness | Respectful | Irreverent | +| Enthusiasm | Matter-of-fact | Enthusiastic | + +A bank: formal, serious, respectful, matter-of-fact. +A craft soda brand: casual, funny, irreverent, enthusiastic. +A premium watch brand: formal, serious, respectful, matter-of-fact. +A coding bootcamp: casual, serious, respectful, enthusiastic. + +If you cannot pick a position on each axis, the voice is not defined yet. + +--- + +## Framework 2: Brand archetypes + +Twelve archetypes from Jung-derived brand theory. Pick one primary and one secondary. + +| Archetype | Promise | Voice notes | Example brands | +|---|---|---|---| +| Innocent | Safety, simplicity | Warm, plain, reassuring | Dove, Coca-Cola | +| Sage | Truth, wisdom | Authoritative, considered, measured | Google, BBC, The Economist | +| Explorer | Freedom, discovery | Adventurous, restless, vivid | Patagonia, Jeep, Subaru | +| Outlaw | Disruption | Rebellious, blunt, anti-establishment | Harley-Davidson, Liquid Death | +| Magician | Transformation | Visionary, mysterious, evocative | Apple, Tesla | +| Hero | Mastery, courage | Bold, confident, action-driving | Nike, FedEx | +| Lover | Intimacy, beauty | Sensual, warm, indulgent | Chanel, Godiva | +| Jester | Joy, fun | Playful, irreverent, witty | Old Spice, Mailchimp, Slack | +| Everyman | Belonging | Friendly, plain, relatable | IKEA, Target | +| Caregiver | Service, compassion | Nurturing, warm, supportive | Johnson & Johnson, Volvo | +| Ruler | Control, prestige | Commanding, polished, exclusive | Rolex, Mercedes | +| Creator | Self-expression | Imaginative, articulate, craft-focused | Lego, Adobe | + +Two archetypes give you range. A primary "Sage" with secondary "Hero" is authoritative AND action-driving. A primary "Caregiver" with secondary "Sage" is supportive AND wise. + +--- + +## Framework 3: We are X, not Y + +The fastest voice exercise. Pick three to five adjectives. For each, name what it could tip into if overdone. + +> **Confident**, not arrogant. +> **Direct**, not blunt. +> **Warm**, not saccharine. +> **Witty**, not sarcastic. +> **Smart**, not condescending. + +The "not" half is what saves you. "Confident" alone leads writers to swagger. "Confident, not arrogant" tells them where the line is. + +--- + +## Tone shifts by context + +Voice stays. Tone shifts. Map the high-frequency moments and decide how each one sounds. + +| Moment | Tone shift | +|---|---| +| Onboarding | Warmer, more enthusiastic | +| Error message | Calmer, more matter-of-fact | +| Success state | Brief celebration, quickly redirect to next action | +| Empty state | Helpful, slightly playful, suggests action | +| 404 / not found | Self-aware, light, points the way home | +| Account deletion | Quiet, respectful, no jokes | +| Pricing page | Direct, clear, confidence-inspiring | +| Legal copy | Plain language version of the legal copy, sitting next to the legal copy | + +--- + +## Practical patterns + +Voice shows up in concrete choices. These are the dials. + +**Sentence length** + +- Short sentences = punchy, confident. (Apple, Stripe, Liquid Death.) +- Medium sentences = considered, professional. (Most B2B SaaS.) +- Long sentences = literary, premium, slow. (The New Yorker, premium watch brands.) + +**Vocabulary** + +- Plain (most words 1-2 syllables) = approachable, mass-market. +- Domain-specific = signals expertise to insiders, alienates outsiders. +- Coined or invented = builds a worldview but high risk if not earned (Apple's "Retina", Slack's "huddle"). + +**Pronouns** + +- "We" = the company speaking. +- "You" = the customer being addressed. +- "I" = a person speaking, not a company. Strong on personal brands and creator products. Weird on enterprise. + +**Contractions** + +- Use them = casual. +- Avoid them = formal. + +**Punctuation** + +- Em dashes = literary, breath-taking pauses. +- Semicolons = considered, formal, slightly old-school. +- Periods only = punchy, confident. +- Exclamation points = exuberant; lose credibility past one or two. +- Em dashes are popular but polarizing. Many writers and brands ban them outright; some lean on them. Pick a side. + +**Rhythm** + +Read your copy out loud. If you stumble, the rhythm is off. Vary sentence length. A page of all-short sentences feels staccato. A page of all-long sentences feels lecture-y. + +--- + +## Worked example: B2B SaaS + +**Voice** + +> **Direct**, not blunt. +> **Confident**, not cocky. +> **Practical**, not boring. +> **Smart**, not academic. + +**Archetype** + +Primary: Sage. Secondary: Hero. + +**Patterns** + +- Sentence length: short to medium. Lead with the headline, deliver the proof, exit. +- Vocabulary: plain, with domain terms when precision earns its keep. +- Pronouns: "we" for the company, "you" for the reader. Avoid "users." +- Contractions: yes. +- Em dashes: no. + +**Tone shifts** + +- Onboarding: warmer. Lean into "you can do this." +- Error: matter-of-fact. State what happened, what to do, no apology theater. +- Pricing: direct. List the number, list what's included, stop. + +**Sample** + +Bad (vague, hedged, overwrought): +> Our innovative platform leverages cutting-edge technology to revolutionize how teams collaborate on data-driven workflows. + +Good (direct, plain, confident): +> Move data between tools without writing code. Connect your stack in minutes. Built for teams that have outgrown spreadsheets. + +--- + +## Worked example: D2C food brand + +**Voice** + +> **Playful**, not goofy. +> **Honest**, not blunt. +> **Crave-worthy**, not gluttonous. +> **Curious**, not academic. + +**Archetype** + +Primary: Jester. Secondary: Everyman. + +**Patterns** + +- Sentence length: short. Hit the joke, get out. +- Vocabulary: plain. Sensory words land. +- Pronouns: "we" and "you," very conversational. +- Contractions: always. +- Punctuation: light. Periods do the work. + +**Sample** + +Bad (corporate, distant): +> We are committed to providing high-quality artisanal granola made with the finest organic ingredients sourced from trusted partners. + +Good (playful, sensory, confident): +> Crunchy. Honey-roasted. Made with oats from one farm in Wisconsin. We tried adding more stuff. It got worse. So we stopped. + +--- + +## When voice is locked + +A voice is locked when you can: + +1. State it in one sentence ("We sound like a senior engineer explaining something to a junior, with patience.") +2. Cite three brands or writers it borrows from, and what specifically. +3. Show a piece of copy and a critic could say "that does/does not sound like us" without arguing. + +If you cannot do all three, keep working on the voice. diff --git a/skills/creative-direction/SKILL.md b/skills/creative-direction/SKILL.md new file mode 100644 index 0000000..0545b60 --- /dev/null +++ b/skills/creative-direction/SKILL.md @@ -0,0 +1,153 @@ +--- +name: creative-direction +description: "Walk the user through four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) and produce a structured aesthetic brief that downstream content, copy, design, and art-direction skills consume as required input. The aesthetic depth layer, distinct from `creative-brief` (operational kickoff: scope, audience, deliverables, constraints). Use when a project needs aesthetic coherence across many small decisions and the user has only a vague feeling, or when multiple downstream aesthetic-producing skills need a shared brief. Triggers on creative direction, aesthetic direction, set the aesthetic, define the visual direction, what's the vibe, what's the tone, the four axes. Does NOT fire for a general kickoff brief (use `creative-brief`), tactical single-piece work, already-documented direction, purely functional output, or locked production-stage work." +category: strategy-and-discovery +catalog_summary: "Four-axis aesthetic brief (tone, aesthetic, audience, sensory ambition) for cross-skill coherence" +display_order: 3 +--- + +# Creative Direction + +Frameworks produce competent output. Coherent output requires a brief. + +This skill turns vague creative intent into a structured brief that downstream skills can reference. It does not generate taste. It captures direction, so the dozens of small decisions a project requires (word choice, image selection, white space, sequencing, what to leave out) all answer to the same question. + +--- + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## When to use + +- The start of a multi-touchpoint project (website, brand, campaign, product launch) where aesthetic coherence matters +- Before running multiple downstream skills that need to share a unified voice and look +- When inheriting a project that has competent execution but feels generic or incoherent +- Recalibrating an existing project that has drifted aesthetically over time +- When the user is a non-curator who knows what feeling they want but cannot articulate the decisions that produce it + +## When NOT to use + +- Use `creative-brief` instead when the user needs a general kickoff brief covering scope, audience, deliverables, and constraints. This skill goes deeper on aesthetic axes specifically, not on the operational layer. +- Use `art-direction` instead when briefing a specific creative deliverable (photo shoot, illustration set, video, campaign). This skill produces project-wide aesthetic direction; `art-direction` extends that direction into specific creative work. +- Tactical single-piece work (one tweet, one error message, one button label) +- Projects where the user has complete aesthetic direction documented already (skip to downstream skills) +- Purely functional output (data tables, form labels, system status text) +- Production-stage execution where direction is already locked +- When the goal is to develop taste; this skill codifies intent, it does not develop judgment + +--- + +## Required inputs + +- Project name and one-paragraph description +- Target audience (rough is fine; full audience profiles come from `brand-discovery`) +- Business goal (what changes if this project works) +- Optional but high-value: 2 to 4 reference URLs (sites, brands, or pieces) the user admires, with a sentence on what specifically resonates +- Optional: existing brand assets if the project is a refresh, not greenfield +- Constraints worth declaring (parent brand voice, regulatory tone requirements, accessibility floors) + +--- + +## The framework: 4 directional axes + +A creative brief sits at the intersection of four axes. Each axis is a spectrum, not a binary. The user picks a position on each, knowing that the choice excludes adjacent positions for this project. + +### 1. Tone Register + +How formal is the work? How much heat does the language carry? + +**Positions:** + +- **Professional.** Measured, precise, low-register. Trusts the reader to do work. Restraint is the signal. +- **Conversational.** Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking. +- **Playful.** Wit, surprise, willingness to break form for effect. Risks the reader missing the point if not earned. +- **Provocative.** Pointed, opinionated, willing to take a position other brands will not. Risks alienating people who do not share the position. + +**How to choose:** What does the audience already get too much of, and what too little? If the category is dry, conversational or playful is differentiation. If the category is loud, professional restraint is differentiation. + +### 2. Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +**Positions:** + +- **Editorial Restrained.** Generous white space, single definitive image instead of grids, considered typography, low color count. Signals confidence and patience. +- **Polished Standard.** Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions. Signals competence and professionalism. +- **Controlled Maximalist.** High visual density where every element is intentional. Loud but engineered. Signals craft and conviction. +- **Expressive Maximalist.** Visual abundance, willingness to be loud, willing to clash. Signals energy and ambition. Hardest to execute well. + +**How to choose:** What is the project saying about the brand's relationship to attention? Restrained earns attention by deserving it. Maximalist captures attention by not letting it leave. + +### 3. Audience Relationship + +How does the brand position itself relative to the reader? + +**Positions:** + +- **Authority.** We tell you what is true. Implicit hierarchy, expertise on display, reader is the learner. +- **Peer.** We are figuring this out together. Equal footing, shared vocabulary, reader is the co-thinker. +- **Companion.** We walk with you. Lower hierarchy than authority, more presence than peer, reader is the protagonist of their own work. +- **Coach.** We challenge you. The brand pushes the reader toward something they would not push themselves toward alone, reader is the trainee. + +**How to choose:** What does the audience need most? Audiences who feel lost want authority or coach. Audiences who feel patronized want peer or companion. The wrong choice patronizes or abandons the reader. + +### 4. Sensory Ambition + +How much is the work asking of the reader emotionally? + +**Positions:** + +- **Functional.** Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity. Most utility tools live here. +- **Considered.** Reader notices the craft. Aesthetic choices are visible without being the point. Most premium brands live here. +- **Resonant.** Reader feels something specific the brand architected. Aesthetics carry meaning. Hardest to produce. Most editorial and narrative brands aspire here. + +**How to choose:** What does the audience deserve from this experience? Functional respects time. Resonant respects feeling. The wrong choice either wastes attention or fails to deliver utility. + +--- + +## Workflow + +1. **Gather inputs.** Project name, description, audience, goal, references. +2. **Walk through each axis as a question.** One axis at a time. For each, present the positions, surface tradeoffs, and capture the user's selection plus reasoning. +3. **Capture inspiration references.** For each provided reference URL, ask what specifically resonates. The answer often clarifies which axis position fits better than abstract description does. +4. **Surface tensions.** Some combinations are difficult to execute well. Functional + Provocative is rare since provocation usually requires emotional engagement that pure functional work resists. Authority + Functional often slides into preachy without warming up at least slightly. Flag tensions and ask the user to confirm or reconsider. +5. **Synthesize.** Write a one-paragraph synthesis describing what this combination produces in practice. +6. **Output the brief.** Markdown format using the structure in [`references/brief-template.md`](references/brief-template.md). The brief becomes a project artifact (typically saved as `BRIEF.md` at the project root). +7. **Hand off.** Reference the brief in any downstream skill that produces aesthetic output. Required reading before `landing-page-copy`, `art-direction`, `content-and-copy`, `brand-style-guide`, or any other skill where coherence matters. + +--- + +## Failure patterns + +- **Using this to develop taste.** This skill codifies intent. It does not produce judgment. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. +- **Skipping inspiration references.** The references calibrate what the axis positions mean in practice. A user picking "Editorial Restrained" without examples often means something different than what an art director means by it. +- **Treating positions as absolute.** A project at "Conversational" still has moments of authority and play. Position is the gravitational center, not a fence. +- **Brief drift mid-project.** The most common failure. The brief gets written, then ignored. Discipline: every downstream skill checks the brief before producing output. If a skill wants to violate the brief, the violation is a decision the user makes consciously, not an accident. +- **Picking incompatible combinations without flagging.** Functional + Provocative is technically valid but very hard. The skill should surface that the combination is rare and ask the user to confirm. +- **Producing a brief no one references.** A brief that does not change downstream output is decoration. The test of a good brief is whether the output would be different if a different brief were used. + +--- + +## Output format + +Default output is a markdown brief, typically saved as `BRIEF.md` at the project root. + +Structure: + +1. **Project header.** Name, one-paragraph description, target audience, business goal. +2. **The four axis selections.** Each axis with the position selected and a one-sentence rationale. +3. **Synthesis paragraph.** What this combination produces in practice. Written in present tense, not aspirational ("This brief produces work that..." not "This brief will help us..."). +4. **Inspiration references.** The provided URLs with notes on what specifically each one demonstrates. +5. **Rejection list.** What this brief explicitly says no to. Often the most useful section. Examples: "No testimonial walls. No stock photography. No exclamation marks." +6. **Open questions.** Anything still unresolved that downstream skills will need to know. + +The brief is reference material for the project's life, not a one-time deliverable. Update it when the project's direction genuinely changes. Resist the urge to update it when execution is hard; usually that means execute harder, not loosen the brief. + +--- + +## Reference files + +- [`references/axes-explained.md`](references/axes-explained.md) - The four axes in depth, with positions, signals, and short brand examples per position to calibrate the user's eye. +- [`references/brief-template.md`](references/brief-template.md) - Blank template for the brief output. +- [`references/example-aesthetic-brief.md`](references/example-aesthetic-brief.md) - A fully completed brief from a representative project, showing how the abstract axes translate into concrete creative direction. diff --git a/skills/creative-direction/references/axes-explained.md b/skills/creative-direction/references/axes-explained.md new file mode 100644 index 0000000..b49c833 --- /dev/null +++ b/skills/creative-direction/references/axes-explained.md @@ -0,0 +1,235 @@ +# The Four Axes Explained + +Each axis is a spectrum. Pick a position knowing it excludes adjacent positions for this project. Reference brands are illustrative, not prescriptive. + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## Axis 1: Tone Register + +How formal is the language? How much heat does it carry? + +### Professional + +Measured, precise, low-register. Trusts the reader to do the work of meaning. Restraint is the signal. + +**What this signals:** Seriousness, expertise, established status. The brand does not need to perform to be taken seriously. + +**Reference examples:** Stripe's documentation. The Economist. McKinsey's published thinking. Bloomberg's editorial style. + +**When to pick this:** The audience is making high-stakes decisions and needs to feel they are dealing with peers, not pitchpeople. Or, the category is loud and your differentiation is calm. + +**Common failure:** Sliding into stiffness. Professional is not robotic. It is restrained and warm, not cold. + +### Conversational + +Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking, not an institution speaking. + +**What this signals:** Approachability without sacrificing competence. A brand that respects the reader as a person, not a target. + +**Reference examples:** Linear's product copy. Vercel's marketing voice. Notion's onboarding. MailChimp's voice in their early years. + +**When to pick this:** Default for most modern B2B and prosumer brands. The audience appreciates human voice but still needs to trust the brand's competence. + +**Common failure:** Sliding into casual. Conversational is still considered. "Hey friend!" is not conversational, it is performed informality. + +### Playful + +Wit, surprise, willingness to break form for effect. Visible craft in the language itself. + +**What this signals:** Confidence, creative ambition, willingness to risk being misread. The brand is having fun and inviting the reader to as well. + +**Reference examples:** Slack's early voice. Old Spice campaigns. Bumble. Mailchimp at its peak. + +**When to pick this:** The audience expects beige and wants color. The category is mature and differentiation through craft is available. The brand has the cultural permission to be funny without it reading as forced. + +**Common failure:** Forcing humor that does not earn its place. Playful only works when it is actually funny. Otherwise it reads as desperate. + +### Provocative + +Pointed, opinionated, willing to take a position other brands will not. Says what others soften. + +**What this signals:** Conviction. The brand stands for something specific and is willing to lose the audience that disagrees in order to bond more deeply with the audience that agrees. + +**Reference examples:** Patagonia's political voice. Liquid Death's entire premise. Oatly's category-baiting copy. The early Apple "Think Different" era. + +**When to pick this:** Strong opinion exists and hiding it is more expensive than expressing it. The brand can defend the position over the long term, not just at launch. + +**Common failure:** Performing provocation without conviction. Audiences detect this in seconds. Either the position is real or the voice fails. + +--- + +## Axis 2: Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +### Editorial Restrained + +Generous white space, single definitive image instead of grids, considered typography, low color count, deliberate slowness. + +**What this signals:** Confidence and patience. The brand is willing to under-fill space because it trusts the reader to fill it with attention. + +**Reference examples:** Aesop's website. Apple's product pages in their classic era. Jacquemus. Phaidon's editorial work. Most luxury fashion houses. + +**When to pick this:** The audience is fatigued by visual noise. The brand is premium or aspirational. The product or work itself benefits from being viewed slowly. + +**Common failure:** Restraint that reads as absence. Restraint earns its place when every remaining element is exquisite. Strip too much and the page reads as unfinished. + +### Polished Standard + +Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions, conventional component patterns. + +**What this signals:** Competence, professionalism, current. The brand belongs in its category without standing out. + +**Reference examples:** Most modern B2B SaaS sites. Stripe's marketing pages. Linear. Notion's marketing. Vercel. + +**When to pick this:** The audience expects the category's visual conventions and the brand's differentiation is in the product, not the wrapper. Default for most B2B work. + +**Common failure:** Producing work indistinguishable from competitors. Polished Standard is safe. Safe is forgettable. + +### Controlled Maximalist + +High visual density where every element is intentional. Loud, but engineered. The page is full because each thing earns its place. + +**What this signals:** Craft and conviction. The brand has thought about every pixel and chose density on purpose. + +**Reference examples:** BUCK's portfolio site. Ueno's work. Pentagram's case study pages. Many top-tier creative agency sites. Some Nike campaign work. + +**When to pick this:** The audience expects boring and the brand wants to demonstrate creative ambition. Differentiation through visible craft is available. The team has the design capacity to execute it. + +**Common failure:** Density without intent. Controlled Maximalist requires every element to defend its existence. Lazy density reads as cluttered, not crafted. + +### Expressive Maximalist + +Visual abundance, willingness to be loud, willing to clash. Energy over restraint. + +**What this signals:** Energy, ambition, irreverence. The brand is having a moment and the work is the moment. + +**Reference examples:** Adult Swim. Cards Against Humanity. Some Heinz creative work. Liquid Death's loudest moments. Music festival branding. + +**When to pick this:** The audience is energetic and seeks brands that match. Cultural permission for loudness is high in the category. The brand can sustain the energy over time. + +**Common failure:** This is the hardest position to execute well. Expressive Maximalism that lacks craft reads as chaotic, not exciting. Most attempts fail. + +--- + +## Axis 3: Audience Relationship + +How does the brand position itself relative to the reader? + +### Authority + +We tell you what is true. Expertise on display. Hierarchy implicit and accepted. + +**What this signals:** Earned expertise. The reader came here to learn from someone who knows more than they do. + +**Reference examples:** Bloomberg. McKinsey's published frameworks. Bain's reports. The Economist. Some of Apple's product copy. + +**When to pick this:** The audience explicitly came for expertise. The brand has the credibility to back the position. The category rewards authoritative voice. + +**Common failure:** Authority without earned credibility reads as arrogance. The brand needs to actually know more than the reader. + +### Peer + +We are figuring this out together. Equal footing, shared vocabulary. + +**What this signals:** Mutual respect. The reader is treated as a co-thinker, not a learner. + +**Reference examples:** Linear. Most developer-focused brands. GitHub. Some of Notion's voice. Most modern B2B SaaS. + +**When to pick this:** The audience is sophisticated and reacts badly to being talked down to. The work is genuinely collaborative and acknowledging the reader's expertise serves the relationship. + +**Common failure:** False peering. If the brand actually does know more, hiding that to seem peer-like reads as condescending. + +### Companion + +We walk with you. Lower hierarchy than authority, more presence than peer. + +**What this signals:** Sustained accompaniment. The brand is here for the long arc, not just the transaction. + +**Reference examples:** Headspace. Calm. Stitch Fix. Some healthcare brands. Anthropic's voice in some moments. + +**When to pick this:** The audience is going through something difficult, ongoing, or uncertain. They need presence more than expertise. The relationship is about being with them, not directing them. + +**Common failure:** Companion without substance reads as performative warmth. The brand needs to actually do something useful to earn the relationship. + +### Coach + +We challenge you. The brand pushes the reader toward something they would not push themselves toward alone. + +**What this signals:** Productive friction. The brand assumes the reader wants growth and is willing to be pushed. + +**Reference examples:** Strava. Whoop. Crossfit's brand voice. Apple Fitness+. Some founder-focused programs. + +**When to pick this:** The audience explicitly wants to be challenged. The brand has the credibility to push without being dismissed. The product or service requires effort that the brand is asking of the reader. + +**Common failure:** Coaching without permission. The brand needs to be invited into that role. Pushing readers who did not ask to be pushed reads as preachy. + +--- + +## Axis 4: Sensory Ambition + +How much is the work asking of the reader emotionally? + +### Functional + +Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity, not feeling. + +**What this signals:** Respect for time. The brand assumes the reader has somewhere else to be. + +**Reference examples:** Wikipedia. Craigslist. Most documentation sites. Government services that work well. IRS forms when they are well-designed. + +**When to pick this:** The reader is in transactional mode. The work's value is utility, not feeling. Asking for emotional engagement would be presumptuous. + +**Common failure:** Confusing functional with bare. Functional work is still well-designed. It is just designed for clarity over resonance. + +### Considered + +Reader notices the craft. Aesthetic choices are visible without being the point. + +**What this signals:** Attention to detail without flexing it. The brand cares, and the reader can tell. + +**Reference examples:** Apple's product pages. Notion's marketing. Linear's interface. Aesop's product photography. Most premium SaaS. + +**When to pick this:** The audience appreciates craft when they encounter it but does not require an emotional payoff. The work needs to feel premium without demanding emotion. + +**Common failure:** Considered work that drifts toward decorative. If the craft is visible without earning its place, it reads as fussy. + +### Resonant + +Reader feels something specific the brand architected. Aesthetics carry meaning. The work is asking the reader to feel. + +**What this signals:** Ambition. The brand is trying to do more than communicate. It is trying to move. + +**Reference examples:** Hermes. Patagonia at their narrative best. Some Apple campaigns ("Think Different," "Shot on iPhone"). Aesop's editorial work. Most editorial publications. + +**When to pick this:** The audience came for feeling, not utility. The brand has the craft to deliver it. The work is significant enough to warrant the emotional ask. + +**Common failure:** This is the hardest position. Resonance that is forced reads as manipulation. Resonance that is mistargeted reads as melodrama. Resonance that is vague reads as pretentious. Most attempts fail. + +--- + +## Combinations to flag + +Some combinations are common, some are rare-but-doable, some are contradictory. + +**Common combinations:** + +- Conversational / Polished Standard / Peer / Considered = the modern B2B SaaS default +- Professional / Editorial Restrained / Authority / Considered = premium consultancy default +- Conversational / Polished Standard / Companion / Considered = wellness or healthcare default + +**Rare but powerful:** + +- Provocative / Editorial Restrained / Coach / Resonant = the "Patagonia at full conviction" register +- Conversational / Controlled Maximalist / Peer / Resonant = the "top creative agency" register +- Provocative / Controlled Maximalist / Coach / Resonant = the "high-stakes brand revival" register + +**Difficult combinations to flag:** + +- Functional + Provocative = rare. Provocation usually requires emotional engagement that pure functional work resists. +- Editorial Restrained + Expressive Maximalist = unreachable by selection. These are both positions on Axis 2 (Aesthetic Philosophy), so the user picks one or the other, not both. +- Authority + Functional = possible but flat. Often slides into "we are right and you should know that," which is hard to hold without warming up at least slightly. + +When the user picks a difficult combination, surface the difficulty. Ask them to confirm or reconsider. Sometimes the difficulty is the point. diff --git a/skills/creative-direction/references/brief-template.md b/skills/creative-direction/references/brief-template.md new file mode 100644 index 0000000..ffdd108 --- /dev/null +++ b/skills/creative-direction/references/brief-template.md @@ -0,0 +1,74 @@ +# Brief Template + +Save this as `BRIEF.md` at the project root. Update when direction genuinely changes; otherwise hold the line. + +--- + +# [Project Name] Brief + +## Project + +**Name:** [Project name] + +**Description:** [One paragraph describing what the project is, what it produces, who it serves.] + +**Target audience:** [Rough description. A full audience profile from `brand-discovery` is a separate document.] + +**Business goal:** [What changes if this project works. The actual outcome that defines success.] + +--- + +## The four axes + +### Tone Register: [Position] + +[One sentence rationale for why this position fits this audience and goal.] + +### Aesthetic Philosophy: [Position] + +[One sentence rationale.] + +### Audience Relationship: [Position] + +[One sentence rationale.] + +### Sensory Ambition: [Position] + +[One sentence rationale.] + +--- + +## Synthesis + +[One to two paragraphs describing what this combination produces in practice. Written in present tense. "This brief produces work that..." not "This brief will help us...". Concrete enough that downstream skills can check their output against it.] + +--- + +## Inspiration references + +[For each reference URL or brand the user provided, document what specifically resonates and which axis it informs.] + +- **[Reference 1]** - [What this demonstrates and which axis it calibrates.] +- **[Reference 2]** - [What this demonstrates and which axis it calibrates.] +- **[Reference 3]** - [What this demonstrates and which axis it calibrates.] + +--- + +## Rejection list + +This brief explicitly says no to: + +- [Specific decision the brief rejects, e.g. "No testimonial walls."] +- [Another specific decision, e.g. "No stock photography of people."] +- [Another, e.g. "No exclamation marks in body copy."] + +The rejection list is often the most useful section. The choices a brief excludes are as important as the choices it commits to. + +--- + +## Open questions + +[Anything still unresolved that downstream skills will need to know. Better to surface uncertainty than to leave it implicit.] + +- [Question 1] +- [Question 2] diff --git a/skills/creative-direction/references/example-aesthetic-brief.md b/skills/creative-direction/references/example-aesthetic-brief.md new file mode 100644 index 0000000..6e52131 --- /dev/null +++ b/skills/creative-direction/references/example-aesthetic-brief.md @@ -0,0 +1,83 @@ +# Example Aesthetic Brief + +A representative completed brief, modeled on a realistic project. Showing how the abstract axes translate into concrete creative direction. + +> The brief below is a worked example for "Conversational + Editorial Restrained + Peer + Considered" applied to a developer-tool marketing site. Compare it against any rendered marketing site that hits these axis positions to see how the abstract axes translate into concrete decisions: copy register, typographic restraint, image treatment, page density, and rejection list. + +--- + +# Observatory Marketing Site Brief + +## Project + +**Name:** Observatory marketing site redesign + +**Description:** Rebuild the marketing site for an open-source observability tool aimed at senior infrastructure engineers. The current site reads like every other developer SaaS site (gradient hero, "trusted by" logo wall, three-column feature grid, code snippet, testimonials, signup CTA). The new site needs to feel like the team behind it actually understands the problem space, not like a marketing team built a site about a tool they have not used. + +**Target audience:** Senior platform engineers, infrastructure leads, and SRE managers at companies with 50 to 500 engineers. They evaluate observability tools for their team. They are skeptical of marketing claims and value technical depth. They will read documentation before they evaluate the product. + +**Business goal:** Increase qualified evaluation requests from engineering decision-makers, where "qualified" means the requester has authority to influence vendor selection and is in active evaluation. Volume of low-intent signups is not the goal. Quality and intent are. + +--- + +## The four axes + +### Tone Register: Conversational + +The audience is fatigued by both stiff vendor copy ("enterprise-grade reliability") and aggressive performance copy ("10x your observability"). Conversational treats the reader as a peer engineer who can read between the lines. + +### Aesthetic Philosophy: Editorial Restrained + +The category is visually loud. Dashboards, gradient heroes, neon accents, animated charts. The differentiation is opposite: low color count, generous white space, considered typography, single definitive image instead of dashboard screenshots above the fold. The site reads like documentation that decided to be a marketing site, not the other way around. + +### Audience Relationship: Peer + +These engineers do not need to be educated on observability. They need to be respected as practitioners. Authority voice would be condescending. Companion voice would be saccharine. Peer voice acknowledges that we and they are figuring out the same hard problems. + +### Sensory Ambition: Considered + +Functional would underdeliver; the audience expects a marketing site to be more than a feature list. Resonant is too much; this is not a brand campaign, it is a tool evaluation. Considered means the craft is visible (typography, restraint, the right photograph in the right place) without the site asking for an emotional response. + +--- + +## Synthesis + +This brief produces a marketing site that reads like a thoughtful engineering blog post the team happened to design well. Body copy is in first-person plural, contractions are fine, and technical terms appear without quotation marks (the audience uses them naturally, the site should too). Visual density is intentionally low, with a single hero image instead of a product screenshot grid, and pages that breathe rather than fill. There is no logo wall above the fold. There are no testimonials styled as ad copy. The product makes its case through clear documentation links, an honest comparison page, and a "how this differs from what you are already using" section that is willing to say what the tool is not for. + +The site refuses several conventions of the category. No animated dashboard hero. No "trusted by" logos as the second module. No three-column feature grid with checkmarks. No popup. No newsletter modal. The site assumes the reader will find the product if it is genuinely useful, and that the marketing's job is to be clear, not to be loud. + +--- + +## Inspiration references + +- **Linear's marketing site (linear.app)** - Demonstrates Conversational + Polished Standard + Peer well. The Observatory site borrows the calm density and the willingness to write in first person, but pushes further toward Editorial Restrained on the aesthetic axis. +- **Vercel's marketing pages** - Useful for how they handle technical depth without overwhelming. The product surfaces in code, not in dashboard mockups. +- **Stripe's documentation** - The reference for how documentation can be a marketing asset. Observatory's marketing site borrows the sense that good docs are a brand decision, not just a product decision. +- **The Economist's editorial design** - Aesthetic reference for restraint, considered typography, and the use of a single editorial photograph as a hero treatment instead of a dashboard screenshot. + +--- + +## Rejection list + +This brief explicitly says no to: + +- No "trusted by" logo wall, especially above the fold +- No gradient hero. Solid color or a single restrained photograph instead +- No three-column feature grid with checkmark icons +- No product dashboard mockup as the hero image +- No animated chart components scattered through the page +- No exit-intent modal, newsletter popup, or any popup of any kind +- No testimonials with headshots arranged in a grid +- No marketing-speak: "enterprise-grade," "blazing fast," "world-class," "industry-leading" +- No "AI-powered" framing. The product uses ML; that is not the lead +- No corporate stock photography of people in offices +- No vague "join the future" CTAs. Specific verbs only + +--- + +## Open questions + +- The comparison page is committed to but the comparators are not yet selected. Decision needed before `landing-page-copy` runs on that page. +- The hero image needs custom photography or commissioned illustration. Considered Restrained does not support stock. Budget question for the team. +- The pricing page is not yet scoped. Brief should be confirmed before that page is built; pricing pages have their own conventions. +- Author bylines are part of the documentation but not the marketing site yet. Worth deciding whether marketing pieces carry author attribution. diff --git a/skills/cro-optimization/SKILL.md b/skills/cro-optimization/SKILL.md new file mode 100644 index 0000000..d1ea82f --- /dev/null +++ b/skills/cro-optimization/SKILL.md @@ -0,0 +1,271 @@ +--- +name: cro-optimization +description: "Run conversion rate optimization through hypothesis-driven testing including audit, hypothesis generation, test design, statistical analysis, and rollout decisions. Use this skill whenever the user wants to optimize conversion, run A/B tests, audit a funnel, generate test hypotheses, design experiments, or analyze test results. Triggers on conversion optimization, CRO, A/B test, split test, multivariate test, hypothesis, conversion funnel, funnel audit, experiment design, statistical significance, lift, optimization. Also triggers when the user has a conversion problem and isn't sure where to start, or when test results are ambiguous and need interpretation." +category: growth +catalog_summary: "Hypothesis-driven testing, conversion optimization" +display_order: 2 +--- + +# CRO Optimization + +Run conversion rate optimization as a structured discipline: audit → hypothesize → test → decide. Stack-agnostic. Tool-agnostic. + +This skill is for running tests against existing pages and flows. For writing landing page copy from scratch, use `landing-page-copy`. For setting up the analytics that make CRO possible, use `analytics-strategy`. + +--- + +## When to use + +- Converting traffic at lower rate than expected +- Specific funnel step has high drop-off +- Pages with high traffic that could move the needle if optimized +- A/B testing infrastructure exists (or can be set up) +- Statistical significance and sample size questions + +## When NOT to use + +- Without sufficient traffic to test (under ~5,000 monthly conversions per variant) +- Pre-launch (no users to test on yet) +- Strategy or messaging-level questions that need qualitative research first +- Brand-defining choices (CRO can't optimize a fundamentally wrong brand) + +--- + +## Required inputs + +- The page or flow under optimization +- Current conversion rate and traffic volume +- Access to analytics (event tracking, funnel data) +- An A/B testing tool (or willingness to set one up) +- Time and budget for testing (typically 2 to 8 weeks per test) + +--- + +## The framework: 4 phases + +### 1. Audit + +Diagnose before treating. + +**Quantitative audit:** + +- **Funnel data.** Where are users dropping off? The biggest drop is the biggest opportunity. +- **Segmentation.** Does the funnel perform differently by source, device, geography, audience type? +- **Performance data.** Are slow pages dragging conversions? +- **Search Console / on-site search.** What are users looking for that they can't find? + +**Qualitative audit:** + +- **Session replay.** Watch 20+ sessions of users on the target flow. Note friction, confusion, hesitation. +- **Heatmaps.** Where do users click? Where do they scroll? Where do they not? +- **User interviews / surveys.** Why did users not convert? Survey people who started but abandoned. +- **Form analytics.** Which fields cause abandonment? Which cause errors? +- **Customer support tickets.** What conversion-related questions come in? + +**Heuristic audit:** + +- Apply CRO heuristics to the flow: + - Is the value proposition clear in 5 seconds? + - Is there a single primary CTA per page? + - Is the form length appropriate to the offer? + - Is the trust/social proof present? + - Are objections handled? + - Is the page accessible? (Accessibility issues hurt conversion silently.) + +The audit produces a list of suspected friction points. Each becomes a hypothesis candidate. + +### 2. Hypothesis + +A testable statement. + +**Hypothesis structure:** + +> Because [observation from audit], we believe that [change] will produce [predicted outcome] for [user segment], because [reason]. + +**Example:** + +> Because session replays show users abandoning at the shipping step (audit), we believe that adding visible shipping cost to the product page (change) will increase add-to-cart conversion by 5 percent (outcome) for desktop users (segment), because users are surprised by shipping cost and abandon (reason). + +**Hypothesis quality criteria:** + +- Specific change (not "improve the design") +- Measurable outcome (with a target) +- Grounded in evidence (audit, research, prior tests) +- Tied to a known mechanism (why would this work?) + +**Hypothesis prioritization (ICE or PIE):** + +- **Impact:** How much could this move the metric? +- **Confidence:** How likely is the hypothesis to be right? +- **Ease:** How easy to test? (Time, complexity, risk) + +Score each 1 to 10. Highest combined scores test first. + +### 3. Test design + +A test that produces an unambiguous answer. + +**Sample size and duration:** + +Use a sample size calculator (most A/B tools have one) before launching. Inputs: + +- Baseline conversion rate +- Minimum detectable effect (the smallest lift you'd care about) +- Statistical power (typically 80%) +- Significance level (typically 95%) + +This produces required sample size per variant. Run the test until that sample is reached, OR for a minimum duration that captures full business cycle (typically 2 weeks minimum, to cover weekends and weekly patterns). + +**Common test setup mistakes:** + +- Stopping the test the moment significance is hit (peeking) +- Running tests for too short to capture a full business cycle +- Running multiple overlapping tests on the same flow +- Testing during atypical periods (Black Friday, holidays, major campaigns) +- Excluding mobile when 50%+ of traffic is mobile (or vice versa) +- Testing on too small a slice of traffic (low statistical power) +- Not segmenting analysis (overall lift can hide negative impact on a segment) + +**Test parameters to define before launch:** + +- Primary metric (one) +- Guardrail metrics (do not go down) +- Sample size +- Duration (minimum and maximum) +- Decision criteria (when to ship, when to kill, when to extend) +- Segments to analyze in addition to overall + +### 4. Decide + +After the test concludes. + +**Decision framework:** + +| Outcome | Decision | +|---|---| +| Variant clearly wins (>95% significance, exceeds minimum effect) | Ship variant. Document. Continue testing. | +| Variant clearly loses | Kill. Capture the lesson. Iterate hypothesis. | +| Inconclusive (neither significant) | Larger test, different angle, or move on. Don't ship "tied" variants. | +| Small lift, lots of variance | Probably not worth shipping. Even if "winner," may not replicate. | +| Wins overall, loses for important segment | Investigate segment. Consider segment-specific solution. | + +**Anti-patterns:** + +- "It looks like it's winning, ship it" before reaching significance +- Shipping a variant because the team wants to (HiPPO - highest paid person's opinion) +- Killing tests too early because they look bad +- Re-running tests until they "win" (false positive risk) +- Not capturing the learning when a test loses + +--- + +## Statistical foundations + +### Significance and confidence + +A 95% significance level means: if there were truly no difference between variants, there's only a 5% chance you'd see results this extreme by chance. + +That's not the same as "95% chance the variant wins." + +Most CRO tools report Bayesian probabilities ("95% chance of being best"). Read the methodology your tool uses. + +### Sample size + +Conversion testing needs more sample than people intuit. Quick reference: + +| Baseline rate | Minimum detectable effect | Sample per variant | +|---|---|---| +| 2% | 10% relative lift | ~75,000 | +| 2% | 20% relative lift | ~19,000 | +| 5% | 10% relative lift | ~30,000 | +| 5% | 20% relative lift | ~7,500 | +| 10% | 10% relative lift | ~14,000 | +| 10% | 20% relative lift | ~3,500 | + +(Approximate. Use a calculator.) + +If your monthly conversions per variant don't reach these numbers, A/B testing won't produce reliable results. Iterate via design and qualitative research instead. + +### Multiple testing + +The more variants and metrics tested simultaneously, the more false positives. Adjust significance thresholds for multiple comparisons (Bonferroni or similar). + +--- + +## Workflow + +1. **Audit.** Quantitative + qualitative + heuristic. +2. **Generate hypotheses.** From audit findings. Apply hypothesis structure. +3. **Prioritize.** ICE or PIE. Top 3 to 5 to test next. +4. **Design the test.** Sample size, duration, primary and guardrail metrics, decision criteria. +5. **Implement.** Build variants. QA carefully (broken variants invalidate tests). +6. **Run.** Don't peek. Don't stop early. +7. **Analyze.** Overall and by segment. Note interesting patterns regardless of significance. +8. **Decide.** Ship, kill, or extend. +9. **Document.** Hypothesis, design, results, decision, lesson. +10. **Compound.** Apply lessons to next round of hypotheses. + +--- + +## Failure patterns + +- **Testing without audit.** Random changes, random results. +- **Vague hypotheses.** "Make it better" is not a hypothesis. +- **Peeking and early stopping.** Bias toward false positives. +- **Underpowered tests.** Not enough sample for a real conclusion. +- **HiPPO override.** Highest paid person's opinion overrides the data. +- **Testing during atypical periods.** Holidays distort results. +- **Single metric obsession.** Conversion ups but average order value craters. Net loss. +- **No guardrail metrics.** Testing for one outcome, missing damage to others. +- **Documentation gap.** Wins captured, losses forgotten. Same hypothesis re-tested 3 times. +- **Treating each test in isolation.** Compounding learning across tests is where CRO programs really win. + +--- + +## Output format + +Default output: a markdown test plan at `cro-test-[hypothesis-slug].md` per test. After the test runs, append the results section. + +Structure: + +```markdown +# Test: [Hypothesis short name] + +## Hypothesis +Because [observation], we believe that [change] will produce [outcome] for [segment], because [reason]. + +## Audit evidence +[What evidence supports this hypothesis] + +## Test design +- Primary metric: +- Guardrail metrics: +- Sample size required: +- Duration: minimum X, maximum Y +- Variant traffic split: +- Segments to analyze: + +## Decision criteria +- Ship if: [conditions] +- Kill if: [conditions] +- Extend if: [conditions] + +## Results (filled after test) +- Sample reached: +- Duration actual: +- Primary metric: [variant vs control + significance] +- Guardrail metrics: [results] +- Segment analysis: [findings] + +## Decision +[Ship / Kill / Extend / Iterate] - [Why] + +## Lesson +[What this teaches us, regardless of outcome] +``` + +--- + +## Reference files + +- [`references/hypothesis-library.md`](references/hypothesis-library.md) - Common high-impact hypothesis patterns by funnel stage. diff --git a/skills/cro-optimization/references/hypothesis-library.md b/skills/cro-optimization/references/hypothesis-library.md new file mode 100644 index 0000000..89fbae6 --- /dev/null +++ b/skills/cro-optimization/references/hypothesis-library.md @@ -0,0 +1,313 @@ +# Hypothesis Library + +Common high-impact CRO hypothesis patterns by funnel stage. Use as starting points; adapt to the specific product and audience. Each pattern includes the typical evidence that supports it and the typical mechanism behind why it works. + +--- + +## Top of funnel: hero and value proposition + +### H1: Outcome-led headline beats feature-led + +**Hypothesis:** Replacing a feature-led headline ("Advanced workflow automation") with an outcome-led headline ("Ship 30% faster") will increase scroll-past-hero rate and CTA clicks. + +**Evidence to look for:** +- Session replays show users bouncing within 3 seconds +- Heatmaps show low engagement below the hero +- The current headline names a feature, not a benefit + +**Mechanism:** Users grant 3 to 5 seconds to decide whether to continue. Outcome language is processed faster than feature language. + +**Test design:** Hero-only swap. Control vs variant. Primary metric: scroll past hero + CTA click. + +--- + +### H2: Specific number beats vague claim + +**Hypothesis:** Replacing "Save time on month-end close" with "Close in 3 days, not 2 weeks" will increase signup rate. + +**Mechanism:** Specific numbers are more credible and more memorable than vague claims. + +--- + +### H3: Customer-facing ID over jargon + +**Hypothesis:** Replacing internal/industry jargon ("ETL pipeline orchestration") with customer language ("Move data between your tools without engineering") will improve hero engagement. + +**Mechanism:** Industry insiders use jargon. Most prospects are not industry insiders. + +--- + +### H4: Real customer photo beats stock + +**Hypothesis:** Replacing stock-photo hero imagery with photos of actual customers using the product will increase signup rate. + +**Mechanism:** Stock photos are pattern-recognized as marketing fluff. Real customer photos signal authenticity. + +--- + +## Mid-funnel: feature blocks and social proof + +### H5: Specific named customer logos beat unnamed + +**Hypothesis:** Replacing "Trusted by 1,000+ companies" with named logos will improve trust and conversion. + +**Evidence:** Heatmaps show users hovering near social proof but not converting. + +**Mechanism:** Named logos provide verifiable trust. Numbers without names are easily fabricated and users know it. + +--- + +### H6: Specific outcome quote beats generic praise + +**Hypothesis:** Replacing "We love this product!" with "Reduced our onboarding time by 40 percent in three months" will increase trust score and conversion. + +**Mechanism:** Specific outcomes are credible because they're quantifiable. Generic praise is dismissed as cherry-picked. + +--- + +### H7: Founder quote at scale stage + +**Hypothesis:** Adding a founder quote and photo on the homepage will increase early-stage trust signals. + +**Evidence:** Brand is unknown. No major customer logos to display yet. + +**Mechanism:** Personal accountability from a named person beats anonymous brand voice when trust signals are scarce. + +--- + +### H8: Comparison table for competitive categories + +**Hypothesis:** Adding a comparison table against named competitors will increase conversion for prospects in active evaluation. + +**Mechanism:** Users in evaluation mode are comparing anyway. Honest comparison reduces objection-handling work. + +**Risks:** Can backfire if comparison feels biased or if competitors are smaller than you (gives them oxygen). + +--- + +## Form and signup + +### H9: Fewer form fields wins + +**Hypothesis:** Reducing signup fields from 7 to 3 will increase signup conversion. + +**Evidence:** Form analytics show high abandonment, especially on optional fields. + +**Mechanism:** Each form field is friction. Optional fields without value to the user feel like data collection for company benefit. + +--- + +### H10: Progressive profiling beats upfront fields + +**Hypothesis:** Moving non-essential signup fields to a post-signup onboarding flow will increase initial signup conversion without hurting profile completion. + +**Mechanism:** Users commit incrementally. The hardest "yes" is the first one. + +--- + +### H11: Social signup options reduce friction + +**Hypothesis:** Adding "Sign up with Google" alongside email signup will increase signup rate. + +**Risks:** OAuth providers can also reduce signups for users uncomfortable with social login. Test, don't assume. + +--- + +### H12: Visible password requirements reduce errors + +**Hypothesis:** Showing password requirements (8 chars, etc.) above the field instead of as error messages will reduce form errors and abandonment. + +**Mechanism:** Errors after submission feel like punishment. Pre-emptive guidance feels like assistance. + +--- + +### H13: Trust signals near form + +**Hypothesis:** Adding "Free for 14 days. No credit card." adjacent to the CTA will increase form completion. + +**Mechanism:** Reduces perceived risk at the point of commitment. + +--- + +## Pricing page + +### H14: Annotated tiers beat unannotated + +**Hypothesis:** Adding "Best for" labels on each pricing tier ("Best for solo founders," "Best for teams of 10+") will increase plan selection clarity. + +**Mechanism:** Users self-select faster when given decision shortcuts. + +--- + +### H15: Annual emphasis beats monthly default + +**Hypothesis:** Defaulting the pricing toggle to annual (with savings highlighted) will increase annual plan adoption. + +**Mechanism:** Defaults stick. Loss-framed savings ("Save $X") are more compelling than gain-framed. + +--- + +### H16: Clear "what's included" reduces confusion + +**Hypothesis:** Adding a checkmark feature comparison below the pricing tiers will reduce sales-assist requests and improve self-service conversion. + +**Mechanism:** Many prospects abandon when they can't quickly verify a needed feature is in their tier. + +--- + +### H17: Social proof on pricing page + +**Hypothesis:** Adding tier-specific customer testimonials ("Why we picked Team plan") will increase plan upgrade rate. + +**Mechanism:** Tier-specific proof reduces fear of overpaying or under-buying. + +--- + +## Checkout / cart + +### H18: Free shipping threshold visible + +**Hypothesis:** Adding a "$X away from free shipping" message in the cart will increase average order value. + +**Evidence:** Cart abandonment correlated with sub-threshold orders. + +**Mechanism:** Goal gradient. Users near a goal accelerate toward it. + +--- + +### H19: Guest checkout option + +**Hypothesis:** Adding a guest checkout option will increase conversion of first-time buyers. + +**Mechanism:** Account creation is friction at the worst possible moment (when the user has just decided to buy). + +--- + +### H20: Multiple payment methods + +**Hypothesis:** Adding [PayPal / Apple Pay / Google Pay / etc.] at checkout will increase mobile conversion. + +**Mechanism:** Saved payment methods reduce friction. Mobile typing is painful. + +--- + +### H21: Visible total throughout checkout + +**Hypothesis:** Showing the running total persistently in the checkout flow will reduce abandonment. + +**Evidence:** Step-by-step abandonment shows users dropping after seeing fees. + +**Mechanism:** Surprise cost is the #1 cause of cart abandonment. + +--- + +### H22: Trust badges at checkout + +**Hypothesis:** Adding security badges (SSL, PCI, money-back guarantee) at the payment step will increase completion. + +**Mechanism:** Security concerns peak at payment entry. + +--- + +## Onboarding (post-signup) + +### H23: Single first action vs feature tour + +**Hypothesis:** Replacing a feature tour with a single guided first action will increase activation. + +**Mechanism:** Feature tours teach. First actions deliver value. Users who experience value retain better than users who learn features. + +--- + +### H24: Sample data on first login + +**Hypothesis:** Pre-loading the new user's account with sample data will increase first-week retention. + +**Mechanism:** Empty states are demotivating. Pre-populated data shows "what good looks like." + +--- + +### H25: Time-to-value reduction + +**Hypothesis:** Reducing the steps from signup to first valuable action from 12 to 4 will increase activation rate. + +**Evidence:** Funnel analysis shows huge drops in the middle of the onboarding flow. + +**Mechanism:** Each step is a chance to bounce. Fewer steps = more activations. + +--- + +## Email and notifications + +### H26: Subject line specificity + +**Hypothesis:** Replacing "Update from [Brand]" with a specific benefit-led subject ("Your invoice is ready" or "Save 20% this week") will increase open rate. + +**Mechanism:** Inbox is competitive. Specificity earns the open. + +--- + +### H27: Single CTA per email + +**Hypothesis:** Reducing email CTAs from 3 to 1 will increase click-through to primary action. + +**Mechanism:** Choice paralysis. Multiple CTAs dilute the primary action. + +--- + +### H28: Personalization beyond name + +**Hypothesis:** Personalizing email body content based on user behavior (last action, product viewed) will increase reactivation rate. + +**Mechanism:** Generic emails feel like spam. Behaviorally relevant emails feel like service. + +--- + +## Mobile-specific + +### H29: Tap target sizing + +**Hypothesis:** Increasing tap targets to meet 44x44 minimum will reduce mobile bounce rate. + +**Evidence:** Mobile heatmaps show mis-taps and rage clicks. + +**Mechanism:** Small targets fail more often than large ones. + +--- + +### H30: Sticky CTA on mobile + +**Hypothesis:** Adding a sticky bottom CTA on mobile pages will increase conversion. + +**Mechanism:** Long mobile pages bury CTAs. Sticky keeps the action available. + +**Risks:** Can cover content. Test for accessibility issues. + +--- + +### H31: Mobile-specific headlines + +**Hypothesis:** Shortening headlines for mobile viewports (vs desktop) will reduce bounce rate. + +**Mechanism:** Long headlines on mobile become walls of text. Short headlines preserve hierarchy. + +--- + +## Compounding tests + +The biggest CRO wins come from compounding learnings. After running 5 to 10 tests, you should know: + +- What kind of headlines win in your category +- How long your forms should be +- Which trust signals move your audience +- Which features matter to your buyer +- What price framing converts + +These insights compound across tests. Document each test's lesson, even when the test loses. + +A pattern to watch: +- **Test #1:** Outcome-led headline wins +- **Test #5:** Outcome-led email subject wins +- **Test #10:** Outcome-led ad copy wins + +You haven't just run 10 tests. You've discovered that "outcome-led messaging" is your audience's preference, broadly. That insight is worth more than any single test. diff --git a/skills/data-warehouse-experimentation/SKILL.md b/skills/data-warehouse-experimentation/SKILL.md new file mode 100644 index 0000000..f4a424f --- /dev/null +++ b/skills/data-warehouse-experimentation/SKILL.md @@ -0,0 +1,389 @@ +--- +name: data-warehouse-experimentation +description: "Running experiments out of the data warehouse instead of via dedicated experiment platforms. SQL-based assignment, exposure logging discipline, metric definitions in dbt models, statistical analysis in SQL or Python, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms like Statsig and Optimizely. Triggers on warehouse-native experimentation, run experiments in BigQuery, run experiments in Snowflake, dbt experiments, SQL t-test, CUPED variance reduction, exposure log, sample ratio mismatch, sequential testing, mSPRT, doubly robust estimation, build vs buy experimentation. Also triggers when the team is choosing between platform and warehouse, building warehouse-native experiment infrastructure, auditing one, or running an experiment with a custom metric the platform cannot handle." +category: product +catalog_summary: "Run experiments out of the warehouse: SQL assignment, exposure logs, dbt metric definitions, statistical analysis, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms" +display_order: 9 +--- + +# Data Warehouse Experimentation + +A senior data scientist's playbook for running experiments natively out of BigQuery, Snowflake, or any modern data warehouse, with metric definitions in dbt and statistical analysis in SQL or Python. + +Most companies that run experiments at scale use a dedicated platform. Statsig, Optimizely, LaunchDarkly with experimentation, PostHog, Amplitude Experiment. The platforms are good. They handle assignment, instrumentation, and analysis in one product, and the SQL-savvy data team does not have to reinvent the variance reduction wheel. + +There is a different operational model that mature data teams increasingly choose: warehouse-native experimentation. Assignment happens in code or via feature flags. Exposure events fire to the warehouse like any other event. Metrics are defined as dbt models. Statistical analysis runs as SQL or in a Python notebook against warehouse data. The "experiment platform" is just your existing data stack. + +This skill covers when warehouse-native is the right call, the architecture, and the specific techniques that make it work: assignment patterns, exposure logging discipline, metric definitions in dbt, t-tests and CUPED in SQL, sequential testing, and the pitfalls that take down homegrown setups. + +When to use this skill: deciding between platform vs warehouse-native, building a warehouse-native experiment infrastructure, auditing an existing one, or running a specific experiment when the platform of record cannot handle a custom metric or segmentation. + +--- + +## What this skill is for + +This skill spans the operational execution model for warehouse-native experimentation. It does not replace the methodology and interpretation skills; it composes with them. + +- `experiment-design` covers methodology: hypotheses, sample size, randomization unit, primary metric. Tool-agnostic. Read it first to design the experiment correctly regardless of where it runs. +- `experimentation-analytics` covers interpretation: confidence intervals, p-values, effect size, decision frameworks. Tool-agnostic. Read it when results land. +- `experimentation-platform-orchestrator` covers the platform-vs-warehouse decision in detail. Read it to decide whether to use a platform or this skill. +- `feature-flagging` covers assignment infrastructure when not running through a platform. Read it for the flag-management discipline that this skill assumes. +- This skill (`data-warehouse-experimentation`) covers the operational execution: SQL-based assignment, exposure logging, metric definitions in dbt, statistical analysis in SQL or Python, variance reduction, sequential testing. + +The distinction is between "what to do" (the methodology and interpretation skills) and "how to do it without a vendor platform" (this skill). Read this skill after you have decided warehouse-native is the right call. If you are still deciding, start with `experimentation-platform-orchestrator`. + +--- + +## When warehouse-native is the right call + +Six factors push the decision toward warehouse-native. + +1. **Cost at volume.** Platforms charge per MAU or per event. At 10K MAU the platform is cheap; at 1M MAU the bill becomes a real budget item. Warehouse-native runs on infrastructure you already pay for. +2. **Custom metrics.** If your primary metric is a complex business metric (revenue with refund-aware logic, cohort LTV, retention bracket, multi-event composites), platforms can struggle. Warehouse-native expresses any metric you can write in SQL. +3. **Custom segmentation.** Enterprise customers, account-tier crosscuts, complex behavioral segments. Platforms have segmentation features; the depth varies. dbt models compose without limit. +4. **Trust requirements.** Regulated industries (healthcare, finance, government) need full transparency into the math. Warehouse-native gives you every step of the calculation auditable in SQL. +5. **Existing data team strength.** If you have data engineers and data scientists, you have most of the infrastructure. Adding experimentation discipline on top costs less than adopting a new platform. +6. **Iteration on metric definitions.** Platforms ship metric updates on their own cadence. Warehouse-native iterates as fast as your dbt deployments. + +Five factors push toward platform. + +1. **Frontend visual experiments.** Optimizely's bread and butter. Variant code injected via a script tag, with WYSIWYG editing. +2. **Sub-week iteration speed.** Some platforms set up an experiment in 30 minutes; warehouse-native often takes a day or more for the first run of a new metric pattern. +3. **Teams without strong data infrastructure.** If you do not have a warehouse, dbt, and analysts, do not start with warehouse-native. The platform is the right call. +4. **Mobile experimentation.** SDK-based assignment with offline support is the platform's job, not the warehouse's. +5. **Out-of-the-box sequential testing with strict guarantees.** Statsig and Eppo ship mSPRT with calibrated alpha-spending. Building this in-house is real work. + +Detail and a decision tree in [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md). Many mature teams use both; warehouse-native for the hard cases, platform for fast iteration on standard experiments. + +--- + +## The architecture + +Four components, in order of data flow. + +1. **Assignment.** How users get bucketed into variants. Hash function, feature flag, or randomized assignment table. +2. **Exposure logging.** A discrete event fired the first time a user is exposed to the experiment, written to the warehouse like any other event. +3. **Metric definitions.** SQL queries (or dbt models) that compute the primary and secondary metrics from warehouse events. +4. **Analysis.** Statistical computation in SQL or Python that joins exposure to metrics and produces effect estimates with confidence intervals. + +The flow. User visits the product. Assignment determines the bucket (control or treatment). If the user is exposed to the variant (sees the treatment-specific behavior), an exposure event fires to the warehouse. The user takes actions, generating metric events to the same warehouse. At analysis time, exposure joins to metrics on the assignment unit (typically `user_id`); the analysis computes lift and produces a decision. + +The exposure-event pattern is critical. Without it you can compute only an "intent-to-treat" analysis (everyone assigned, regardless of whether they saw the variant). With it you compute the "exposed" analysis on the population that actually experienced the variant. The latter is usually what you want, especially when the variant only affects a subset of the assigned users (e.g., users who reached a specific page). + +--- + +## Assignment patterns + +Three approaches. + +**Deterministic hash assignment.** The default for warehouse-native. + +```sql +MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 +``` + +The salt (`'exp_button_color_v1'`) ensures different experiments produce uncorrelated assignments for the same user. Reproducible (same input always produces the same bucket), no service dependency, salt isolation across experiments. The assignment can be computed inline in any SQL query. + +**Feature flag assignment.** Rely on a feature flag service (LaunchDarkly, Statsig flags, Unleash, internal) to do bucketing; the warehouse just records the assignment that the flag service chose. + +```sql +-- Read assignment from the flag service's logs +SELECT user_id, variant_id, assigned_at +FROM flag_service.assignments +WHERE flag_key = 'exp_button_color_v1' +``` + +This works when the flag service is the source of truth for assignment and the warehouse mirrors the assignment table. Useful when assignment must respect flag-service rules (e.g., percentage rollouts, targeting rules) that are inconvenient to replicate in SQL. + +**Randomized assignment table.** Pre-randomize users into a table at experiment start. + +```sql +CREATE TABLE exp_button_color_v1_assignments AS +SELECT + user_id, + CASE WHEN RAND() < 0.5 THEN 'control' ELSE 'treatment' END AS variant_id +FROM dim_users +WHERE eligible = true; +``` + +Less common; useful when the eligibility set is fixed at experiment start and you want assignment to be deterministic and explicit (e.g., for compliance audit). The downside: new users joining mid-experiment are not in the table; either skip them or fall back to hash assignment. + +The deterministic hash approach is the default for warehouse-native because it requires no service dependency and produces stable, auditable assignments. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## The exposure log + +The single most important discipline in warehouse-native experimentation. + +Required exposure event schema: + +| Field | Type | Notes | +|---|---|---| +| `experiment_id` | string | Unique identifier per experiment. | +| `variant_id` | string | The variant the user was bucketed into. | +| `user_id` | string | The assignment unit. | +| `exposed_at` | timestamp | ISO 8601 UTC. The moment exposure fired. | +| `context_*` | various | Optional context properties: device, page, account_id. | + +Fire exposure exactly when the user has seen the variant-specific behavior. Not at page load. Not at session start. Not at app open. + +The "delayed exposure" trap. If the variant only matters at button click and you fire exposure at page load, every page-load user enters the analysis whether or not they ever saw the variant. The control group includes users who never reached the button; the treatment group does too. The analysis dilutes the real effect. + +Worked example. The treatment shows a new pricing page; the control shows the old one. Fire exposure when the pricing page loads, not when the user lands on the homepage. Users who never reach the pricing page are not exposed to either variant; they should not be in the analysis. + +The "always-fire" trap. Some implementations fire exposure on every variant-specific interaction. The user clicks the button five times; exposure fires five times. The exposure log is now five times larger than it should be, and analysis tools that count distinct user_ids in exposure handle this correctly while tools that count rows do not. + +The discipline. Fire exactly one exposure event per user per experiment, at the moment of first variant-specific exposure. Use a deterministic flag in the client (or a server-side cache) to enforce single-fire. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## Metric definitions in dbt models + +Defining metrics as dbt models gives you four things. + +1. **Version control on metric definitions.** Every change to a metric is a git commit. The history is queryable. +2. **Testability.** dbt tests on the metric output catch regressions. +3. **Composability.** The same `fct_orders` model feeds the board dashboard, the experiment analysis, and the executive report. Aligned definitions, no drift. +4. **Single source of truth.** When the experiment says X and the board says Y, the answer is in the dbt model, not in two unrelated SQL files. + +Pattern. + +```sql +-- models/experiments/exp_metrics_revenue.sql +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + MIN(occurred_at) AS first_purchase_at +FROM {{ ref('fct_orders') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' +GROUP BY user_id +``` + +The experiment analysis joins this to the exposure log on `user_id` and computes group means. + +The variance discipline. The same metric definition is used in board dashboards AND in experiment analysis. No "experiment-specific revenue calculation" that is slightly different. Otherwise you get the "the experiment said the revenue lifted but the board did not move" problem, which is almost always a metric-definition mismatch. + +The namespace pattern. Use `exp_metrics_*` for experiment-shaped models that group by `user_id` and produce one row per user. Use `fct_*` for the underlying fact tables that feed both metric models and dashboards. Detail in [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md). + +--- + +## Statistical analysis in SQL + +The basic two-sample Welch's t-test in SQL. + +```sql +WITH metric_by_variant AS ( + SELECT + e.variant_id, + COUNT(*) AS n, + AVG(m.net_revenue_cents) AS mean, + VAR_SAMP(m.net_revenue_cents) AS variance + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' + GROUP BY e.variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic +FROM + (SELECT * FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment +``` + +Convert the t-statistic to a p-value or confidence interval using a SQL function (BigQuery: a UDF; Snowflake: native or a stored procedure) or compute in Python on the result of the SQL query. + +The SQL pattern is fine for simple t-tests on continuous metrics. For proportions tests, swap variance for `p * (1 - p)`. For non-parametric tests (Mann-Whitney), the SQL gets ugly fast; switch to Python. + +Anything more complex than a simple t-test (CUPED, bootstrap, doubly robust estimation, sequential testing) is easier in Python. Use SQL for the SUM-and-AVG aggregations; ship the result to Python for the statistical math. Detail in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Statistical analysis in Python + +The Python pattern, typically in a Jupyter or Hex notebook. + +```python +import pandas as pd +import numpy as np +from scipy import stats + +# Pull aggregated data from the warehouse +df = warehouse.query(""" + SELECT user_id, variant_id, net_revenue_cents + FROM exp_results + WHERE experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].net_revenue_cents +treatment = df[df.variant_id == 'treatment'].net_revenue_cents + +# Welch's t-test +t, p = stats.ttest_ind(treatment, control, equal_var=False) + +# Confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} cents (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"p-value: {p:.4f}") +``` + +Python gives you access to the full statistical ecosystem (`scipy`, `statsmodels`, `numpy`) for techniques SQL cannot easily express. + +The notebook pattern. One notebook per experiment, parameterized by `experiment_id`. Version-controlled in git or as Hex projects. Each notebook produces a written-up decision document at the end, archived in a queryable repository (Notion, GitHub markdown, or a dedicated experiment-results table in the warehouse). + +Detail and bootstrap templates in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Variance reduction: CUPED and beyond + +The most powerful variance reduction technique for warehouse-native experimentation: **CUPED** (Controlled-experiment Using Pre-Experiment Data). Originally from Microsoft. + +The intuition. If you can predict a user's metric behavior from pre-experiment data, you can subtract out that predicted variance, leaving a smaller residual to test on. + +```python +# Pre-experiment metric for each user (e.g., last 28 days revenue) +pre = pre_period_revenue(user_id) + +# Theta is the regression coefficient of the metric on the pre-period +theta = np.cov(metric, pre)[0, 1] / np.var(pre) + +# Adjusted metric +adjusted_metric = metric - theta * (pre - pre.mean()) +``` + +Run the t-test on the adjusted metric instead of the raw metric. The mean is preserved (CUPED does not change the point estimate) but the variance is smaller, so the confidence interval is narrower. + +CUPED typically reduces variance by 30 to 50 percent on engagement metrics. That is equivalent to running an experiment 1.5x to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +Other variance reduction techniques. + +- **Stratification.** Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. +- **Regression adjustment.** Fit an OLS regression with covariates; the residual analysis has lower variance. Generalizes CUPED to multiple covariates. +- **Doubly robust estimation.** Combines outcome modeling and propensity-score weighting. Useful in observational and quasi-experimental settings where randomization was imperfect. Outside the scope of typical A/B tests; pointer to academic references in the variance-reduction reference file. + +Detail with worked examples in [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md). + +--- + +## Pre-experiment power analysis + +Before running, compute required sample size. + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Solve for sample size given desired MDE +n_per_arm = tt_ind_solve_power( + effect_size=0.05, # Cohen's d + nobs1=None, + alpha=0.05, + power=0.8 +) + +# Or solve for MDE given sample size +mde = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8 +) +``` + +The "we need 10x more users than we thought" lesson. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10% lift; the actual effect is 1%, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. + +The fix. Use the historical distribution of past experiments' observed effects to set realistic MDE expectations. If the median observed effect across the last 30 experiments is 0.5%, plan for a 0.5% MDE on new experiments. The optimism asymmetry is real; correcting it requires looking at the actual distribution of effects, not the wished-for distribution. + +Detail in [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md). + +--- + +## Sequential testing patterns + +The "peeking" problem. Looking at experiment results before completion inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. + +Three approaches. + +- **mSPRT** (mixture Sequential Probability Ratio Test). Used by Optimizely and Statsig. Provides an always-valid p-value that survives peeking. Implementation in Python via `statsmodels` or custom code; not natively in SQL. +- **Always-Valid Inference** with confidence sequences. Howard et al. Confidence intervals that are valid at any sample size. Implementation requires careful Python; not for the data team that has not read the paper. +- **Group sequential designs** (O'Brien-Fleming boundaries). Pre-specified interim analysis points with calibrated alpha-spending. The classic frequentist approach. + +For warehouse-native, the practical recommendation is mSPRT in Python. Document the alpha-spending function used. Train one team member on the math; do not rely on a black-box implementation. + +The honest version. If you do not have someone on the team who understands sequential testing math, just do not peek. Pre-register sample size, run to completion, analyze once. Sequential testing is statistically correct only when implemented correctly; an incorrect implementation is worse than no peeking discipline at all. + +Detail in [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md). + +--- + +## Common pitfalls + +Eleven patterns recur in warehouse-native experimentation. Detail in [`references/common-pitfalls.md`](references/common-pitfalls.md). + +- "Our exposure log fires at page load." Should fire when the variant-specific behavior is shown, not at page load. The "delayed exposure" trap dilutes the effect. +- "We see lift in control, not treatment." Assignment-hash collision or salt reuse. Audit the salt; check that different experiments produce different bucket assignments for the same user. +- "P-value is 0.04, we are shipping." Probably underpowered plus multiple comparisons plus peeking. Compute the test at the planned sample size only; correct for multiple secondary metrics. +- "Experiment shows 30% lift." Almost certainly a bug. Effects that big rarely exist; first action is to audit the exposure log and metric definitions before celebrating. +- "Treatment users are different." Sample ratio mismatch (SRM). The assignment hash is broken or the exposure log is biased. Check the SRM before computing any metric. +- "We cannot reproduce yesterday's number." Non-deterministic queries (window functions without explicit ORDER BY, sampling without a seed) or floating-point issues in aggregations. Make queries deterministic; document the random seed if any. +- "Custom metric definition disagrees with the board metric." Bad. Align them by using the same dbt model. Otherwise nobody trusts either number. +- "We never finished the experiment." Pre-register stop criteria; honor them. Experiments that drift indefinitely waste team time and produce ambiguous decisions. +- "iOS users converted 3x in treatment." Segment effect or instrumentation bug. Check if iOS instrumentation differs from the rest. Beware over-claiming on small segments. +- "It worked on phase 1, broke on phase 2." Simpson's paradox from cohort mix shift. The aggregate trend reverses when the underlying segments are weighted differently across phases. +- "Statistical significance but tiny effect." Large sample inflated power. The p-value is below 0.05 but the effect is 0.3%. Consider practical significance: is 0.3% worth shipping? + +--- + +## The framework: 12 considerations for warehouse-native experimentation + +When designing or running a warehouse-native experiment, walk these 12 considerations. + +1. **Platform vs warehouse decision.** Cost, custom metrics, segmentation, trust, team strength. Read `experimentation-platform-orchestrator` if undecided. +2. **Assignment unit.** User, account, session, device. Pick once at experiment start and stick to it. +3. **Assignment salt.** Unique per experiment to prevent correlation with prior experiments. Document the salt convention. +4. **Exposure logging discipline.** Fire when the variant matters, not at page load. One exposure event per user per experiment. +5. **SRM check.** Sample ratio mismatch indicates assignment bugs. Check before computing any metric. +6. **Metric definition reuse.** Same dbt model for board and experiment. No experiment-specific calculations that drift from canonical metrics. +7. **Pre-experiment power analysis.** Realistic MDE based on the historical distribution of past observed effects. +8. **Variance reduction.** CUPED for engagement metrics. 30 to 50 percent variance reduction is worth the engineering for any team running 5+ experiments per quarter. +9. **Statistical method.** Welch's t-test as default. Bootstrap for skewed distributions. Doubly robust estimation for quasi-experiments. +10. **Sequential testing.** mSPRT or stop-at-N. Document alpha-spending. If you cannot implement correctly, do not peek. +11. **Multiple comparisons.** Bonferroni or Benjamini-Hochberg correction across secondary metrics. +12. **Decision documentation.** Write the result up. Archive in a queryable repository. The next experiment will benefit from the institutional memory. + +The output of the framework is an experiment record. Pre-registered sample size and stop criteria, the assignment salt, the exposure log specification, the dbt metric model, the analysis notebook, and a written-up decision. The record lives in version control or in a dedicated experiment-tracking system; the analysis is reproducible from the record. + +--- + +## Reference files + +- [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md) - When each operational model is the right call. Cost considerations at different scales. Hybrid patterns. Migration patterns. +- [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md) - Hash assignment SQL templates for BigQuery and Snowflake. Salt naming conventions. Exposure event schema. SRM check SQL. +- [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md) - dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. +- [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md) - SQL and Python templates for Welch's t-test, proportions test, Mann-Whitney, bootstrap. Notebook structure. +- [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md) - CUPED math and Python implementation with worked example. Stratification. Regression adjustment. Doubly robust estimation primer. +- [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md) - MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. +- [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md) - mSPRT, confidence sequences, group sequential designs. Honest framing on when to peek. +- [`references/common-pitfalls.md`](references/common-pitfalls.md) - Eleven failure patterns with diagnoses and fixes. + +--- + +## Closing: the build-vs-buy decision is real + +Warehouse-native experimentation is powerful but expensive in engineering time. A first-year experimentation team should almost always start with a platform; the platform handles 90 percent of cases and lets you focus on hypotheses, not infrastructure. The team that graduates to warehouse-native does so because their volume, custom metric needs, or trust requirements outgrew what platforms offer. + +If you are building warehouse-native because "platforms cost too much" without first running the math: you are underestimating the cost of your team's engineering time. The platform fee that looks expensive on a procurement form is often cheaper than three months of a data engineer's time spent reinventing CUPED. + +If you are building it because the platform cannot handle your specific needs: you are probably right and the investment will pay back. Platforms are general; your business is specific. The custom metric the platform cannot express is often the metric that matters most for your decisions. + +Honest middle ground: many mature teams use both. The platform for fast iteration on standard experiments where time-to-result matters more than custom depth. Warehouse-native for the hard cases where the platform's metric library or segmentation cannot reach. The hybrid is operationally complex; document the rule for which experiments go where, and revisit annually. diff --git a/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md b/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md new file mode 100644 index 0000000..a043446 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md @@ -0,0 +1,230 @@ +# Assignment and exposure patterns + +Hash assignment SQL templates. Salt naming conventions. Exposure event schema. The delayed-exposure trap. Sample ratio mismatch (SRM) check. + +--- + +## Hash assignment SQL templates + +### BigQuery + +```sql +-- 50/50 split for experiment exp_button_color_v1 +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Snowflake + +```sql +-- 50/50 split using SHA1 hash and modulo +SELECT + user_id, + CASE + WHEN MOD(ABS(HASH(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Postgres + +```sql +-- 50/50 split using md5 hash; convert hex to integer +SELECT + user_id, + CASE + WHEN ('x' || SUBSTRING(MD5(user_id || 'exp_button_color_v1'), 1, 8))::bit(32)::int % 100 < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Three-arm split + +```sql +-- 33/33/34 split (control / variant_a / variant_b) +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 33 + THEN 'control' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 66 + THEN 'variant_a' + ELSE 'variant_b' + END AS variant_id +FROM dim_users; +``` + +### Sub-sampling for opt-in experiments + +```sql +-- 10% of users in the experiment, 50/50 split among them +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_eligibility'))), 100) >= 10 + THEN 'not_in_experiment' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +Note the two different salts: one for eligibility, one for assignment. This ensures the eligibility decision is independent of the variant decision. + +--- + +## Salt naming conventions + +Three rules. + +1. **Unique per experiment.** Reuse the same salt across experiments and you correlate assignments. A user in control of experiment A is more likely to be in control of experiment B; the experiments interfere. +2. **Stable across the experiment lifecycle.** Do not change the salt mid-experiment. Changing the salt re-randomizes existing users; the analysis becomes uninterpretable. +3. **Versioned.** When semantics change, append `_v2`. The old experiment data remains queryable; the new salt produces independent assignments. + +Convention. + +``` +{prefix}_{descriptor}_{version} +``` + +Examples. + +- `exp_button_color_v1` +- `exp_pricing_test_v1` (eligibility salt) +- `exp_pricing_test_assign_v1` (assignment salt within eligible) +- `exp_recommendation_model_v2` (version 2 of an existing experiment) + +Document the salt convention. Add it to the experiment record. + +--- + +## Exposure event schema + +The required fields. + +| Field | Type | Required | Notes | +|---|---|---|---| +| `experiment_id` | string | Required | Unique identifier per experiment. | +| `variant_id` | string | Required | The variant the user was bucketed into. | +| `user_id` | string | Required | The assignment unit. | +| `exposed_at` | timestamp | Required | ISO 8601 UTC. Server-stamped. | +| `assigned_at` | timestamp | Optional | When the user was first assigned (may differ from exposed). | +| `device_type` | string | Optional | mobile, web, desktop. | +| `app_version` | string | Optional | For change-tracking when version-specific bugs surface. | +| `account_id` | string | Optional | For B2B; the account context. | +| `session_id` | string | Optional | For session-level path analysis. | + +The minimum schema is the four required fields. Optional fields support segmentation and debugging. + +### Storage pattern + +Either as a dedicated `experiment_exposures` table or as an event in the main events table with `event_name = 'experiment_exposed'`. + +Dedicated table is cleaner for analysis. Main events table is simpler for instrumentation. Pick one and stick to it. + +--- + +## The delayed-exposure trap + +The single most common warehouse-native experimentation bug. + +**The setup.** The treatment shows a new pricing page; the control shows the old one. The team fires exposure at homepage load. + +**The problem.** Many users land on the homepage but never click through to the pricing page. They are counted as "exposed" to the experiment but never saw the variant. The control group includes users who never reached the pricing page; the treatment group does too. + +**The result.** The analysis dilutes the real effect. The treatment may have produced a 20 percent lift among users who actually saw the pricing page, but the analysis shows a 2 percent lift because 90 percent of "exposed" users never reached the variant. + +**The fix.** Fire exposure exactly when the user has seen the variant-specific behavior. + +```javascript +// Wrong: fires at every page load +function onHomepageLoad(user) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: getVariant(user), + user_id: user.id, + }); +} + +// Right: fires when the pricing page renders the variant-specific UI +function onPricingPageLoad(user) { + const variant = getVariant(user); + if (variant === 'treatment') { + renderNewPricingPage(); + } else { + renderOldPricingPage(); + } + // Fire once per user per experiment + if (!hasExposureFired(user, 'exp_pricing_v1')) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: variant, + user_id: user.id, + }); + markExposureFired(user, 'exp_pricing_v1'); + } +} +``` + +The discipline. Fire exposure when the variant-specific UI renders or the variant-specific code path executes. Use a single-fire flag (client-side cache or server-side state) to ensure exposure fires exactly once per user per experiment. + +--- + +## Sample ratio mismatch (SRM) check + +Before computing any metric, check that the assignment is balanced. + +```sql +-- For a 50/50 split, expect roughly equal counts in control and treatment +SELECT + variant_id, + COUNT(*) AS n, + COUNT(*) * 1.0 / SUM(COUNT(*)) OVER () AS share +FROM exposures +WHERE experiment_id = 'exp_button_color_v1' +GROUP BY variant_id; +``` + +Expected output. + +| variant_id | n | share | +|------------|--------|-------| +| control | 50,123 | 0.501 | +| treatment | 49,877 | 0.499 | + +If the share deviates from the expected 50 percent by more than 1 percentage point at large samples, you have an SRM. The chi-squared test detects this formally. + +```python +from scipy.stats import chi2_contingency + +observed = [50123, 49877] # control, treatment +expected_ratio = [0.5, 0.5] +chi2, p, dof, _ = chi2_contingency([observed, [sum(observed) * r for r in expected_ratio]]) +print(f"SRM chi-squared p-value: {p:.4f}") +# p < 0.001 indicates SRM +``` + +If you have an SRM. Do not analyze the experiment. The assignment is broken (hash collision, biased exposure logging, instrumentation that fires for one variant but not the other). Fix the bug; restart the experiment. + +The honest pattern. Run an SRM check at the top of every experiment analysis notebook. If SRM is detected, abort with a clear error message; do not let the analysis proceed. + +--- + +## Common assignment and exposure mistakes + +- **Salt reuse across experiments.** A user in control of experiment A is correlated with control of experiment B. Use unique salts per experiment. +- **Changing the salt mid-experiment.** Re-randomizes existing users. The analysis becomes a mix of two different assignment functions. Pre-register the salt; freeze it at experiment start. +- **Firing exposure on every event.** Inflates the exposure log by 10 to 100x. Use single-fire enforcement. +- **Server-side fire when only client renders the variant.** Server-side fires for every API call; client-side fires only when the user reaches the variant-specific UI. Match exposure to where the variant matters. +- **Eligibility check in the wrong place.** Eligibility (e.g., paid users only) checked client-side after assignment produces biased exposure (only paid users in the log). Check eligibility before assignment, server-side. diff --git a/skills/data-warehouse-experimentation/references/common-pitfalls.md b/skills/data-warehouse-experimentation/references/common-pitfalls.md new file mode 100644 index 0000000..5e96609 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/common-pitfalls.md @@ -0,0 +1,143 @@ +# Common pitfalls + +Eleven failure patterns that recur in warehouse-native experimentation. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Exposure log fires at page load + +**Symptom.** The experiment shows a 1 percent lift; the team expected 10 percent. The lift is real but diluted because most exposed users never saw the variant. + +**Root cause.** Exposure fires at page load (or session start) regardless of whether the user reaches the variant-specific code path. The control group includes users who never saw the variant; the treatment group does too. + +**Fix.** Move exposure firing to the moment the variant-specific UI renders or the variant-specific code path executes. Re-run the experiment with corrected logging. + +**Prevention.** Document the exposure-firing rule in the experiment record. Code review the implementation. Check the exposure-to-metric ratio (if exposure count is much higher than expected metric count, exposure is firing too broadly). + +--- + +## 2. Lift in control, not treatment + +**Symptom.** The control group has a higher mean than the treatment group. The team is confused because the variant-specific changes should have increased the metric. + +**Root cause.** Assignment hash collision or salt reuse with a prior experiment. Users in control of the new experiment are correlated with users in treatment of an old experiment that also affected the metric. + +**Fix.** Audit the salt. Use a unique salt per experiment. Re-run with corrected assignment. + +**Prevention.** Salt naming convention with version suffix. Code review for new experiments. Run a chi-squared test of independence between the new experiment's assignment and recent prior experiments' assignments before launching. + +--- + +## 3. P-value is 0.04, we are shipping + +**Symptom.** The primary metric p-value is 0.04. The team declares victory and ships. Three months later the metric in production has not moved. + +**Root cause.** Some combination of underpowered experiment, multiple comparisons without correction, and peeking. Each of these inflates the false-positive rate; together they make a 0.04 p-value uninformative. + +**Fix.** Re-run with a pre-registered sample size, single primary metric, no peeking. If the lift is real, the second experiment will confirm it. If not, the first result was a false positive. + +**Prevention.** Pre-register the sample size, the primary metric, and the analysis method. Do not peek. Apply Bonferroni or BH correction across secondary metrics. Treat 0.04 with much more skepticism than 0.001. + +--- + +## 4. Experiment shows 30 percent lift + +**Symptom.** The treatment shows a 30 percent lift on the primary metric. The team is excited. + +**Root cause.** Almost certainly a bug. Effects that big rarely exist outside truly novel features. Common bugs: exposure log fires only for treatment users (control is missing); metric model has a join error that double-counts treatment events; assignment is non-random and treatment is over-represented in heavy users. + +**Fix.** Audit the exposure log balance, the assignment ratio, and the metric model. Compare metric values to the historical baseline; if the treatment metric is higher than the all-users historical metric, something is wrong. + +**Prevention.** Skepticism about large effects. Run an SRM check before any analysis. Compare exposed-treatment metric to the historical baseline as a sanity check. + +--- + +## 5. Treatment users are different (sample ratio mismatch) + +**Symptom.** The exposure log shows 52,000 control users and 48,000 treatment users for a planned 50/50 split. The chi-squared test rejects the null at p < 0.001. + +**Root cause.** Assignment is not balanced. Possible causes: hash function bug, biased exposure logging, instrumentation that fires for one variant but not the other, eligibility check that runs differently across variants. + +**Fix.** Do not analyze the experiment. Find and fix the assignment bug. Restart. + +**Prevention.** Run the SRM check at the top of every analysis notebook. Abort with a clear error message if SRM is detected. Code review the exposure logging for both variants. + +--- + +## 6. Cannot reproduce yesterday's number + +**Symptom.** Yesterday's analysis showed 5.2 percent lift; today's shows 4.8 percent. Same query, same data, same notebook. The team cannot tell which is "the" answer. + +**Root cause.** Non-deterministic queries. Window functions without explicit `ORDER BY` produce different results on different runs. Sampling without a seed produces different samples. Floating-point aggregations on large datasets produce slight numeric differences depending on the order of summation. + +**Fix.** Make queries deterministic. Add explicit `ORDER BY` to window functions. Set a seed for any sampling. For floating-point precision, sum integers (cents) instead of floats; convert to dollars only at display time. + +**Prevention.** Code review for non-determinism. Save the query plan or the result set; compare across runs to detect drift early. + +--- + +## 7. Custom metric definition disagrees with board metric + +**Symptom.** The experiment says revenue lifted 5 percent; the board's revenue dashboard shows revenue flat. The team cannot tell which is right. + +**Root cause.** Two different SQL queries computing "revenue" with subtly different rules. The experiment query may include or exclude refunds, internal users, test orders, or specific time windows in different ways than the board. + +**Fix.** Align via shared dbt models. The board's revenue dashboard and the experiment's revenue metric reference the same `fct_orders` model with the same filters. + +**Prevention.** Schema discipline. Every metric used in an experiment is also used somewhere in the board or weekly review. Drift between the two is a code smell that should be caught at code review. + +--- + +## 8. We never finished the experiment + +**Symptom.** The experiment has been running for 8 weeks. The team has looked at the dashboard three times. Each time the result was inconclusive. The team keeps running it hoping for a clear answer. + +**Root cause.** No pre-registered stop criteria. The experiment was launched without a clear "we will stop when X" rule. The team is implicitly peeking and refusing to call it. + +**Fix.** Set a stop date and honor it. Analyze once on the stop date; report the result (which may be inconclusive). Document the inconclusive result and the design improvements needed for the next attempt. + +**Prevention.** Pre-register the sample size, the stop date, and the decision rule. Honor them. + +--- + +## 9. iOS users converted 3x in treatment + +**Symptom.** The aggregate treatment lift is small (1 percent), but the iOS segment shows a 3x lift. The team wants to ship the variant for iOS specifically. + +**Root cause.** Three possibilities. (a) Real segment effect: iOS users genuinely prefer the variant. (b) Instrumentation bug: iOS metric tracking differs from the rest. (c) Multiple comparisons: among many segments, one shows a large effect by chance. + +**Fix.** Investigate. Compare iOS metric tracking to other platforms (is the same event firing the same way?). Check the iOS sample size (if small, the 3x is high variance). Re-run the experiment with iOS as the primary segment if the team genuinely wants iOS-specific results. + +**Prevention.** Pre-register segments of interest. Apply multiple-comparisons correction across segments. Treat unexpected segment effects as hypotheses to confirm in a follow-up experiment, not as ship signals. + +--- + +## 10. Worked on phase 1, broke on phase 2 + +**Symptom.** Phase 1 of a staged rollout showed a clear positive lift. Phase 2 (broader audience) shows a much smaller or negative lift. The team is confused. + +**Root cause.** Simpson's paradox from cohort mix shift. Phase 1's audience is enriched in a segment where the treatment works well; phase 2 includes more of a segment where the treatment works poorly. The aggregate result reverses. + +**Fix.** Decompose by segment. The phase 2 result is the truer estimate (broader audience), but the phase 1 result tells you which segments respond. Consider a segment-specific rollout if the segment-level economics support it. + +**Prevention.** Run the experiment on the full target audience from the start, not on a phase-1 sub-audience. If staged rollout is operationally required, plan for the cohort mix shift in the analysis. + +--- + +## 11. Statistical significance but tiny effect + +**Symptom.** The p-value is 0.001. The lift is 0.3 percent. The experiment is statistically significant but the team is unsure whether to ship. + +**Root cause.** Large sample inflated the test's power. The test detects effects much smaller than the team's practical significance threshold. + +**Fix.** Apply the practical-significance check. If the team's threshold is "ship at 1 percent or larger," 0.3 percent does not meet the bar regardless of the p-value. Document the result; do not ship. + +**Prevention.** Pre-register the practical-significance threshold (the MDE) at experiment design time. Treat statistical significance below the MDE as inconclusive, not as a ship signal. + +--- + +## The pattern across all eleven + +Most warehouse-native experimentation failures share one root cause: the team did not pre-register enough discipline before the experiment started. Pre-registered sample size prevents underpowered analysis. Pre-registered exposure rule prevents the delayed-exposure trap. Pre-registered primary metric prevents multiple-comparisons fishing. Pre-registered stop criteria prevent the experiment-runs-forever pattern. + +The fix at the meta level. Treat each experiment as a contract. Before launching, write down the assignment unit, the salt, the exposure rule, the primary metric, the secondary metrics with multiple-comparisons correction, the sample size, the stop criteria, the practical-significance threshold. The contract is reviewed at launch. Deviations from the contract during the experiment require explicit re-registration. The discipline is the only thing that scales as the team runs more experiments. diff --git a/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md b/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md new file mode 100644 index 0000000..7ecfb76 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md @@ -0,0 +1,229 @@ +# Metric definitions in dbt + +dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. Aligning with board metrics. + +The principle. Define experiment metrics as dbt models so they are version-controlled, testable, and aligned with board metrics. The same source of truth for both surfaces eliminates the "experiment said X but the board says Y" problem. + +--- + +## The namespace pattern + +Three layers in a typical dbt project. + +- `stg_*`: staging models. Light cleanup of source data. One per source table. +- `fct_*` and `dim_*`: marts models. Business-logic transformations. Joined and enriched data ready for consumption. +- `exp_metrics_*`: experiment-shaped models. One row per assignment unit (typically `user_id`) with the metrics needed for analysis. + +Example structure. + +``` +models/ + staging/ + stg_orders.sql + stg_users.sql + stg_events.sql + marts/ + fct_orders.sql + fct_sessions.sql + dim_users.sql + experiments/ + exp_metrics_revenue.sql + exp_metrics_engagement.sql + exp_metrics_retention.sql +``` + +The `fct_*` models feed both the board dashboard and the experiment metrics. The `exp_metrics_*` models pivot to one row per user with the metrics joined or aggregated. + +--- + +## Pattern 1: revenue metric + +```sql +-- models/experiments/exp_metrics_revenue.sql +{{ config(materialized='table') }} + +WITH order_data AS ( + SELECT + user_id, + occurred_at, + amount_cents, + refunded + FROM {{ ref('fct_orders') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +) +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + SUM(amount_cents) AS gross_revenue_cents, + COUNT(*) AS order_count, + MIN(occurred_at) AS first_order_at +FROM order_data +GROUP BY user_id; +``` + +Note the `var()` references for experiment start and end dates. The variables come from the dbt project's variables file or are passed at run time. + +The same `fct_orders` model feeds the board's revenue dashboard. Aligned definitions. + +--- + +## Pattern 2: engagement metric + +```sql +-- models/experiments/exp_metrics_engagement.sql +{{ config(materialized='table') }} + +WITH event_data AS ( + SELECT + user_id, + occurred_at, + event_name + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' + AND event_name IN ('content_created', 'content_edited', 'content_shared') +) +SELECT + user_id, + COUNT(*) AS engagement_event_count, + COUNT(DISTINCT DATE(occurred_at)) AS active_day_count, + SUM(CASE WHEN event_name = 'content_shared' THEN 1 ELSE 0 END) AS shares_count +FROM event_data +GROUP BY user_id; +``` + +The metric definition specifies exactly which events count as engagement. The board's "weekly active users" dashboard uses the same event filter via the same `fct_events` model. + +--- + +## Pattern 3: retention metric (bracket retention) + +```sql +-- models/experiments/exp_metrics_retention_w2.sql +{{ config(materialized='table') }} + +WITH user_first_activity AS ( + SELECT user_id, MIN(occurred_at) AS first_active_at + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + GROUP BY user_id +), +week2_activity AS ( + SELECT DISTINCT u.user_id + FROM user_first_activity u + JOIN {{ ref('fct_events') }} e ON e.user_id = u.user_id + WHERE e.occurred_at >= u.first_active_at + INTERVAL '7 days' + AND e.occurred_at < u.first_active_at + INTERVAL '14 days' +) +SELECT + u.user_id, + CASE WHEN w2.user_id IS NOT NULL THEN 1 ELSE 0 END AS retained_w2 +FROM user_first_activity u +LEFT JOIN week2_activity w2 USING (user_id); +``` + +Bracket retention (week 2 = days 7 to 13 from first activity) is more stable than N-day retention. The metric is binary: 1 if retained, 0 if not. + +--- + +## Pattern 4: ratio metric (delta method required) + +Some metrics are ratios (conversion rate, click-through rate). They require the delta method for correct variance estimation. + +```sql +-- models/experiments/exp_metrics_conversion.sql +{{ config(materialized='table') }} + +SELECT + user_id, + COUNT(*) AS impressions, + SUM(CASE WHEN converted THEN 1 ELSE 0 END) AS conversions +FROM {{ ref('fct_funnel_events') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +GROUP BY user_id; +``` + +The model produces numerator and denominator per user. The analysis layer (Python) computes the ratio and applies the delta method for variance. + +```python +# Per-user numerator and denominator +df = warehouse.query("SELECT * FROM exp_metrics_conversion") + +# Group means +control = df[df.variant_id == 'control'] +treatment = df[df.variant_id == 'treatment'] + +# Conversion rate per group +control_rate = control.conversions.sum() / control.impressions.sum() +treatment_rate = treatment.conversions.sum() / treatment.impressions.sum() + +# Delta method variance (skipping the math here; see statistical-analysis-templates.md) +# ... +``` + +Do not compute the ratio per user and average it. That undercounts heavy users; the delta method is the correct treatment. + +--- + +## Versioning metric definitions + +Same versioning pattern as elsewhere. When the metric definition changes meaningfully, append `_v2`. + +``` +exp_metrics_revenue.sql <- v1, fires alongside v2 during transition +exp_metrics_revenue_v2.sql <- new semantics +``` + +The transition is the same: ship v2 alongside v1, migrate experiments to v2 over 90 days, deprecate v1. + +dbt's built-in versioning (the `models:` config with `versions:`) is also useful here; lets you serve both versions from the same model name with explicit version selection. + +--- + +## Aligning experiment metrics with board metrics + +The variance discipline. The same dbt model feeds both surfaces. + +If the board reports "monthly revenue" by summing `amount_cents` from `fct_orders` and excluding refunded orders, the experiment's revenue metric does the same. No special "experiment revenue" calculation that subtly differs. + +The mechanism. Both the board dashboard's SQL and the `exp_metrics_revenue` model reference the same `fct_orders` table with the same filters. dbt tests verify the table contains the expected rows. + +The check. When an experiment lands and the team reports "revenue lifted 5 percent in treatment," the team can pull the same numbers from the board and compare. If the board's revenue is flat or the experiment's lift is much larger than the board's revenue trend, the metric definitions disagree somewhere. Investigate. + +--- + +## Testing experiment metrics + +dbt tests on the metric models catch regressions. + +```yaml +# models/experiments/_experiments.yml +version: 2 + +models: + - name: exp_metrics_revenue + columns: + - name: user_id + tests: + - not_null + - unique + - name: net_revenue_cents + tests: + - not_null + - dbt_utils.expression_is_true: + expression: ">= 0" +``` + +The `unique` test on `user_id` confirms the model produces one row per user (no accidental duplicates from a bad join). The `>= 0` test confirms revenue is non-negative (refunds are subtracted, never additive). + +--- + +## Common metric-definition mistakes + +- **Drift between board and experiment.** "Experiment revenue" is computed differently from "board revenue." Align via shared dbt models. +- **Wrong time window.** The experiment runs for 14 days but the metric model includes 30 days of data. The control and treatment numbers are similar because the variant signal is diluted. +- **One row per event instead of one row per user.** Joining the metric to exposure on `user_id` produces a row explosion. Always aggregate to one row per user before joining. +- **Forgetting to handle nulls.** Users with no activity should appear with metric = 0, not be missing from the model. Use `LEFT JOIN` from exposure or include all eligible users in the metric model. +- **Non-deterministic queries.** Window functions without explicit `ORDER BY`, sampling without a random seed. The same query produces different numbers on different days. diff --git a/skills/data-warehouse-experimentation/references/power-analysis-calculations.md b/skills/data-warehouse-experimentation/references/power-analysis-calculations.md new file mode 100644 index 0000000..c7008f5 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/power-analysis-calculations.md @@ -0,0 +1,169 @@ +# Power analysis calculations + +Pre-experiment power analysis. MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. + +The principle. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10 percent lift; the actual effect is 1 percent, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. Power analysis prevents this by forcing a concrete decision about how big the lift needs to be before the experiment starts. + +--- + +## The four parameters + +Power analysis ties together four numbers. Fix any three; the fourth is determined. + +1. **Effect size (or MDE, minimum detectable effect).** The smallest lift the experiment can reliably detect. Expressed as a relative percentage, an absolute difference, or Cohen's d (effect size in standard deviations). +2. **Sample size per arm.** Number of users in each variant. +3. **Alpha (significance level).** Default 0.05. The false-positive rate. +4. **Power.** Default 0.8. One minus the false-negative rate. The probability of detecting a real effect. + +The standard practice. Fix alpha at 0.05, power at 0.8, decide on either the MDE (and solve for sample size) or the sample size (and solve for MDE). + +--- + +## Solving for sample size given MDE + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Continuous metric, two-sample t-test +# Cohen's d = (mean_treatment - mean_control) / pooled_std + +cohens_d = 0.05 # 5 percent of one standard deviation + +n_per_arm = tt_ind_solve_power( + effect_size=cohens_d, + nobs1=None, + alpha=0.05, + power=0.8, + ratio=1.0 # equal sample sizes per arm +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a Cohen's d of 0.05 (small effect), expect roughly 6,300 users per arm. For 0.1 (still small), roughly 1,600 per arm. For 0.2 (medium), roughly 400 per arm. + +### Solving for proportions + +```python +from statsmodels.stats.power import zt_ind_solve_power + +# Binary metric, proportions test +# baseline conversion rate = 5 percent; target lift = 5 percent relative +baseline_p = 0.05 +relative_lift = 0.05 +treatment_p = baseline_p * (1 + relative_lift) + +# Cohen's h for proportions +import numpy as np +def cohens_h(p1, p2): + return 2 * np.arcsin(np.sqrt(p1)) - 2 * np.arcsin(np.sqrt(p2)) + +h = cohens_h(treatment_p, baseline_p) + +n_per_arm = zt_ind_solve_power( + effect_size=h, + nobs1=None, + alpha=0.05, + power=0.8 +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a 5 percent relative lift on a 5 percent baseline conversion rate, expect roughly 60,000 users per arm. Small relative lifts on small baselines need very large samples. + +--- + +## Solving for MDE given sample size + +The reverse calculation. Given the available sample (e.g., 8,000 users per arm), what is the smallest effect the experiment can detect? + +```python +from statsmodels.stats.power import tt_ind_solve_power + +mde_cohens_d = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8, + ratio=1.0 +) +print(f"MDE in Cohen's d: {mde_cohens_d:.4f}") + +# Convert to relative MDE assuming the metric's standard deviation +metric_std = 50.0 # in cents, for example +metric_mean = 200.0 +mde_absolute = mde_cohens_d * metric_std +mde_relative = mde_absolute / metric_mean +print(f"MDE absolute: {mde_absolute:.2f}") +print(f"MDE relative: {mde_relative:.2%}") +``` + +If the available sample yields an MDE of 8 percent and the team expects only a 2 percent lift, the experiment is underpowered. Either secure more sample (run longer or expand the audience) or accept that the experiment will produce an inconclusive result. + +--- + +## Calibrating effect-size assumptions from historical experiments + +The most common power-analysis mistake is over-optimistic effect-size estimates. Three patterns help calibrate. + +### Pattern 1: pull the historical distribution + +For the last 30 (or however many) experiments, pull the observed lifts. Compute the median, 25th percentile, and 75th percentile. + +```python +df = warehouse.query(""" + SELECT experiment_id, observed_relative_lift + FROM experiment_results + WHERE shipped = true + ORDER BY ended_at DESC + LIMIT 30 +""") + +print(f"Median observed lift: {df.observed_relative_lift.median():.2%}") +print(f"P25: {df.observed_relative_lift.quantile(0.25):.2%}") +print(f"P75: {df.observed_relative_lift.quantile(0.75):.2%}") +``` + +The median observed lift is the realistic expectation for the next experiment. If past experiments show a median lift of 1 percent, planning for a 5 percent lift on the next experiment is optimistic. + +### Pattern 2: stratify by experiment type + +Pricing experiments often produce larger lifts than UI experiments. Onboarding experiments often produce larger lifts than feature-discovery experiments. Pull the distribution by experiment type to set type-specific expectations. + +### Pattern 3: ask the team about prior experiments they remember + +The "we usually see X" estimate from team members is anchored on memorable experiments (the wins, the disasters). Compare against the actual distribution; the memorable estimate is usually too high. + +The honest conversation. "Our last 30 experiments had a median observed lift of 0.5 percent. We are planning this experiment for a 5 percent MDE. Either the experiment is going to produce an inconclusive result, or we are expecting an unusually large effect. Which is it?" + +--- + +## When the math says "we cannot run this" + +Three escalation paths when the available sample is insufficient. + +1. **Run longer.** The default. If the experiment needs 60,000 users per arm and you have 10,000 per week, plan for a 6-week run. Document the duration before starting. +2. **Expand the audience.** If the experiment is targeting only paid users (10 percent of the user base), consider running on all users. The result is generalizable to a broader population, but the intervention may need to work for the broader population too. +3. **Accept inconclusive.** Some experiments cannot be powered with the available sample. Document the MDE; design the experiment to detect a larger effect or accept that it will be inconclusive. The discipline of saying "we cannot reliably answer this with our sample" is hard but honest. + +--- + +## The underpowered-experiment cost + +A team running 12 experiments per quarter, 4 of which are underpowered. The cost. + +- Underpowered experiments produce inconclusive results. The team learns nothing. +- Engineering and design effort spent on the experiment is wasted. +- Stakeholders treat inconclusive as "no effect"; later experiments that would have shown the same effect at a larger sample also produce inconclusive, reinforcing the false belief that no effect exists. +- The team's experimentation discipline degrades because the visible track record looks bad. + +Power analysis at the design stage prevents most of this. The cost is 30 minutes of work; the benefit is avoiding multi-week runs of experiments that cannot answer the question. + +--- + +## Common power-analysis mistakes + +- **Optimistic effect-size assumption.** Plan for a 10 percent lift; observe a 1 percent lift. The experiment is 100x underpowered. +- **Forgetting variance from the historical metric.** Power calculations use Cohen's d, which depends on the metric's standard deviation. A high-variance metric requires a larger sample for the same MDE than a low-variance metric. +- **Computing power on aggregate when the assignment unit is something else.** If the assignment unit is user but the metric is per-event, the per-event variance includes within-user correlation. Use the user-level variance for the calculation. +- **Skipping the calculation for "small" experiments.** "We will just see what happens" is the path to a quarter of inconclusive experiments. +- **Confusing statistical significance with practical significance.** A p-value below 0.05 with a 0.3 percent effect on a 100,000-user experiment is statistically significant but may not be worth shipping. Use the MDE as the practical-significance threshold; a 0.3 percent effect is below most teams' MDE. diff --git a/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md b/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md new file mode 100644 index 0000000..401eb49 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md @@ -0,0 +1,148 @@ +# Sequential testing patterns + +mSPRT, confidence sequences, group sequential designs. Plus an honest framing on when to peek. + +The principle. Looking at experiment results before completion (peeking) inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. The honest middle ground: if you do not understand the math, do not peek. + +--- + +## The peeking problem + +The standard t-test assumes a fixed sample size pre-registered before the experiment runs. When the team peeks early, the test is implicitly running multiple times; some of those peeks will hit p < 0.05 by chance even when no effect exists. + +A team that peeks daily on a 4-week experiment runs the test roughly 28 times. The implicit false-positive rate becomes much higher than the nominal 5 percent. Estimates suggest 30 percent or more in this case; the experiment is more likely to show a fake significant result than a real one. + +The four solutions. + +1. **Do not peek.** Pre-register the sample size; analyze once. +2. **mSPRT.** Always-valid p-values that survive peeking. +3. **Confidence sequences.** Always-valid confidence intervals via the Howard et al construction. +4. **Group sequential designs.** Pre-specified interim analyses with calibrated alpha-spending. + +Each solution requires implementation discipline. Incorrect implementation is worse than no peeking solution at all (the team thinks the math is correct and ships based on inflated false-positives). + +--- + +## mSPRT (mixture Sequential Probability Ratio Test) + +The most commonly deployed sequential testing method. Used by Optimizely, Statsig. + +The intuition. Compute a Bayes-factor-like statistic that updates as data arrives. The statistic crosses a fixed threshold when the evidence is strong enough to reject the null; it never crosses by chance under the null (with the correct calibration). + +### Python implementation sketch + +```python +import numpy as np + +def mSPRT(treatment, control, prior_var=1.0, alpha=0.05): + """ + Mixture SPRT for two-sample mean difference. + Returns the always-valid p-value at the current sample. + """ + n_t = len(treatment) + n_c = len(control) + diff = treatment.mean() - control.mean() + pooled_var = (treatment.var() / n_t + control.var() / n_c) + se = np.sqrt(pooled_var) + + # Test statistic + z = diff / se + + # Mixture prior with variance prior_var + # Always-valid p-value via the mixture-likelihood ratio + n_eff = (n_t * n_c) / (n_t + n_c) + weight = np.sqrt(prior_var / (prior_var + 1.0 / n_eff)) + log_lr = 0.5 * z**2 * (1 - weight**2) - 0.5 * np.log(1.0 / weight**2) + p_always_valid = min(1.0, np.exp(-log_lr)) + + return p_always_valid +``` + +Note: the implementation above is a sketch for illustration. Production implementations should use a peer-reviewed library or expert review. Do not deploy this verbatim. + +The honest version. Use a maintained library (`sequential` in R, custom Python adapted from peer-reviewed papers like Johari et al 2017). Have a statistician on the team review the implementation. + +--- + +## Confidence sequences (Always-Valid Inference) + +The Howard et al construction. Confidence intervals that are valid at any sample size; the team can peek arbitrarily often without inflating the false-positive rate. + +The math is more involved than mSPRT. Useful when the team needs not just always-valid p-values but always-valid confidence intervals (effect size with uncertainty). + +References. + +- Howard, Ramdas, McAuliffe, Sekhon (2021), "Time-uniform, nonparametric, nonasymptotic confidence sequences." +- Code: `sequential` package in R, or custom Python. + +For most warehouse-native teams, mSPRT is enough. Confidence sequences are for teams with a statistician who has read the paper and validated the implementation. + +--- + +## Group sequential designs + +The classical frequentist approach. Pre-specified interim analysis points (e.g., at 25 percent, 50 percent, 75 percent of the planned sample) with calibrated alpha-spending boundaries. + +The most common boundary is **O'Brien-Fleming**. Conservative early (high effect size required to stop early); lenient late (lower effect size required to stop at the final analysis). + +```python +# Hypothetical O'Brien-Fleming boundaries for 4 interim analyses +# Z-values; if observed Z exceeds, reject the null and stop +boundaries = { + 0.25: 4.05, + 0.50: 2.86, + 0.75: 2.34, + 1.00: 2.02, +} +``` + +The discipline. + +1. Pre-register the interim analysis points and the boundary values. +2. At each interim point, compute the test statistic. +3. If the statistic exceeds the boundary, stop the experiment and reject the null. +4. If the statistic does not exceed any boundary by the final analysis, fail to reject (treat as inconclusive or as "no effect detected"). + +Group sequential designs require commitment up front. Adding interim analyses after the experiment starts is post-hoc peeking and inflates the false-positive rate. + +--- + +## When to peek and when not to + +Three scenarios. + +### Scenario 1: small team, no statistician, simple experiments + +Do not peek. Pre-register the sample size; analyze once at completion. The discipline is simpler than implementing sequential testing correctly, and the cost (running for the full pre-registered duration) is usually small. + +### Scenario 2: high-volume team running many experiments, has a statistician + +Implement mSPRT. The peeking is operationally useful (early stops free up the testing infrastructure for the next experiment) and the math is well-understood. Train the team on the implementation; review periodically. + +### Scenario 3: regulated industry, strong audit requirements + +Group sequential design. Pre-registered interim analyses with calibrated boundaries. The audit trail is clean: every interim analysis was specified before the experiment started; the boundaries are reproducible from the design document. + +--- + +## Common sequential testing mistakes + +- **Implementing mSPRT without understanding the math.** A wrong implementation produces inflated false-positives that the team trusts. Worse than no peeking. +- **Adding interim analyses after the experiment starts.** Group sequential designs require pre-registration. Post-hoc interim analyses are just peeking. +- **Mixing methods.** Compute mSPRT for some peeks and a standard t-test for others. The latter inflates false-positives; the former does not. Pick one method per experiment and stick to it. +- **Using mSPRT but reporting the standard p-value.** The mSPRT p-value is always-valid; the standard p-value is not. Reporting the standard p-value while peeking is the same as not using mSPRT at all. +- **Stopping early on a tiny effect.** mSPRT may show "significant" before the team has enough evidence on practical significance. The effect is real but small; shipping it may not be worth the engineering complexity. + +--- + +## The honest recommendation + +For most warehouse-native experimentation teams, the right answer is "do not peek." + +- Pre-register the sample size based on power analysis. +- Run to the pre-registered sample. +- Analyze once at completion. + +The cost is some early stops the team would have liked. The benefit is no implementation risk in sequential testing math, no false-positives from mis-implemented peeking, and a clean audit trail. + +Move to sequential testing when the team has the statistical expertise to implement correctly and the operational pressure to peek (high-volume infrastructure where early stops materially affect the next experiment's timeline). diff --git a/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md b/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md new file mode 100644 index 0000000..c1b1137 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md @@ -0,0 +1,241 @@ +# Statistical analysis templates + +SQL and Python templates for the most common warehouse-native analyses. t-test, proportions test, Mann-Whitney, bootstrap. Plus the recommended notebook structure. + +--- + +## Welch's t-test (continuous metrics) + +The default for continuous metrics where group variances may differ. + +### SQL + +```sql +WITH joined AS ( + SELECT e.variant_id, m.net_revenue_cents + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +), +metric_by_variant AS ( + SELECT + variant_id, + COUNT(*) AS n, + AVG(COALESCE(net_revenue_cents, 0)) AS mean, + VAR_SAMP(COALESCE(net_revenue_cents, 0)) AS variance + FROM joined + GROUP BY variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic, + -- Standard error of the mean difference + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS se, + control.n AS control_n, + treatment.n AS treatment_n +FROM + (SELECT * FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment; +``` + +The query returns the t-statistic and standard error. Convert to p-value and confidence interval via a UDF or in Python. + +### Python + +```python +import pandas as pd +from scipy import stats +import numpy as np + +df = warehouse.query(""" + SELECT e.variant_id, COALESCE(m.net_revenue_cents, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +t_stat, p_value = stats.ttest_ind(treatment, control, equal_var=False) + +# 95 percent confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"t = {t_stat:.3f}, p = {p_value:.4f}") +``` + +--- + +## Proportions test (binary metrics) + +For binary outcomes (converted vs not, retained vs not). + +### Python + +```python +from statsmodels.stats.proportion import proportions_ztest, proportion_confint + +# Counts and totals per variant +control_conv = 1240 +control_n = 25000 +treatment_conv = 1390 +treatment_n = 25000 + +# Z-test +z_stat, p_value = proportions_ztest( + [control_conv, treatment_conv], + [control_n, treatment_n] +) + +# Confidence intervals on each proportion +control_ci = proportion_confint(control_conv, control_n, method='wilson') +treatment_ci = proportion_confint(treatment_conv, treatment_n, method='wilson') + +# Lift +control_rate = control_conv / control_n +treatment_rate = treatment_conv / treatment_n +relative_lift = (treatment_rate - control_rate) / control_rate + +print(f"Control: {control_rate:.4f}, CI: {control_ci}") +print(f"Treatment: {treatment_rate:.4f}, CI: {treatment_ci}") +print(f"Relative lift: {relative_lift:.2%}") +print(f"z = {z_stat:.3f}, p = {p_value:.4f}") +``` + +The Wilson score interval is more accurate than the normal approximation for small samples or extreme proportions. + +--- + +## Mann-Whitney U test (non-parametric) + +For metrics with skewed distributions (revenue, time-on-site) where the t-test's normal-distribution assumption is violated. + +```python +from scipy.stats import mannwhitneyu + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +u_stat, p_value = mannwhitneyu(treatment, control, alternative='two-sided') + +# Mann-Whitney tests stochastic dominance, not the mean. +# Report median lift alongside. +median_lift = treatment.median() - control.median() +print(f"Median lift: {median_lift:.2f}") +print(f"U = {u_stat:.0f}, p = {p_value:.4f}") +``` + +The Mann-Whitney U test is the standard non-parametric alternative. Use when the metric distribution is skewed and the t-test's assumption fails. + +--- + +## Bootstrap confidence interval + +For metrics where the analytic distribution is unclear or unusual (e.g., retention bracket, complex composite metrics). + +```python +import numpy as np + +def bootstrap_ci(treatment, control, n_iterations=10000, alpha=0.05): + diffs = [] + for _ in range(n_iterations): + t_sample = treatment.sample(n=len(treatment), replace=True) + c_sample = control.sample(n=len(control), replace=True) + diffs.append(t_sample.mean() - c_sample.mean()) + diffs = np.array(diffs) + return np.quantile(diffs, [alpha / 2, 1 - alpha / 2]) + +ci_low, ci_high = bootstrap_ci(treatment, control) +diff = treatment.mean() - control.mean() +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +``` + +10,000 bootstrap iterations is the standard. More iterations produce tighter intervals at the cost of compute time. + +--- + +## Notebook structure + +The recommended structure for an experiment analysis notebook. + +### Cell 1: parameters + +```python +EXPERIMENT_ID = 'exp_button_color_v1' +EXPERIMENT_START = '2026-04-01' +EXPERIMENT_END = '2026-04-15' +PRIMARY_METRIC = 'net_revenue_cents' +SECONDARY_METRICS = ['order_count', 'session_count'] +ALPHA = 0.05 +``` + +Parameters at the top. Parametrize the notebook so the same template runs for any experiment. + +### Cell 2: SRM check + +```python +df_exposures = warehouse.query(f""" + SELECT variant_id, COUNT(*) AS n + FROM exposures + WHERE experiment_id = '{EXPERIMENT_ID}' + GROUP BY variant_id +""") + +# Chi-squared test against expected ratio +from scipy.stats import chi2_contingency +observed = df_exposures.n.values +expected = [observed.sum() / len(observed)] * len(observed) +chi2, p, _, _ = chi2_contingency([observed, expected]) +assert p > 0.01, f"SRM detected (p = {p:.4f}). Aborting analysis." +print(f"SRM check passed (p = {p:.4f})") +``` + +Abort the notebook if SRM is detected. Do not proceed to metric analysis with broken assignment. + +### Cell 3: pull data + +```python +df = warehouse.query(f""" + SELECT + e.variant_id, + e.user_id, + COALESCE(m.{PRIMARY_METRIC}, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = '{EXPERIMENT_ID}' +""") +``` + +### Cell 4: primary analysis + +t-test, proportions test, or bootstrap depending on the metric. + +### Cell 5: secondary metrics + +Loop over secondary metrics; apply Bonferroni correction for multiple comparisons. + +### Cell 6: written-up decision + +A markdown cell with the conclusion. Ship, kill, or inconclusive. Include the lift, the CI, the p-value, the SRM result, and any caveats. This cell is the deliverable. + +--- + +## Common analysis mistakes + +- **No SRM check.** Analyzing an experiment with broken assignment produces meaningless numbers. +- **Equal-variance t-test on unequal-variance data.** Use Welch's (`equal_var=False`) by default. +- **t-test on heavily skewed metrics.** Use bootstrap or Mann-Whitney instead. +- **Per-user ratios for ratio metrics.** Heavy users get under-weighted. Use the delta method. +- **Multiple secondary metrics without correction.** With 5 secondary metrics at alpha 0.05, expect a 25 percent chance of a false positive somewhere. Bonferroni or BH correction. +- **Stop-on-significance peeking.** Inflates the false-positive rate. Either pre-register the sample size or use a sequential testing method correctly. diff --git a/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md b/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md new file mode 100644 index 0000000..daa2693 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md @@ -0,0 +1,179 @@ +# Variance reduction techniques + +CUPED is the most powerful variance reduction technique for warehouse-native experimentation. Stratification, regression adjustment, and doubly robust estimation cover specific cases. + +The principle. Variance reduction makes confidence intervals narrower at the same sample size. A 30 to 50 percent variance reduction (typical with CUPED on engagement metrics) is equivalent to running the experiment 1.5 to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +--- + +## CUPED: the workhorse + +**CUPED** stands for Controlled-experiment Using Pre-Experiment Data. Originally from Microsoft (Deng et al, 2013). + +The intuition. If you can predict a user's metric behavior from pre-experiment data (their behavior before the experiment started), you can subtract that prediction from the metric, leaving a smaller residual to test on. The mean is preserved (CUPED does not change the point estimate of the lift), but the variance shrinks because predictable variance has been removed. + +### The math + +For each user, compute a pre-experiment covariate (e.g., revenue in the 28 days before the experiment started). Call this `pre_metric`. The CUPED-adjusted metric is: + +``` +adjusted_metric = metric - theta * (pre_metric - mean(pre_metric)) +``` + +where `theta` is the regression coefficient of `metric` on `pre_metric`: + +``` +theta = cov(metric, pre_metric) / var(pre_metric) +``` + +Run the t-test on `adjusted_metric` instead of `metric`. The mean difference between treatment and control is preserved; the variance is reduced. + +### Python implementation + +```python +import pandas as pd +import numpy as np + +# df has columns: user_id, variant_id, metric, pre_metric +df = warehouse.query(""" + SELECT + e.user_id, + e.variant_id, + COALESCE(m.net_revenue_cents, 0) AS metric, + COALESCE(p.pre_net_revenue_cents, 0) AS pre_metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + LEFT JOIN pre_experiment_revenue p USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +# Compute theta from the entire dataset (control and treatment combined) +theta = np.cov(df.metric, df.pre_metric)[0, 1] / np.var(df.pre_metric) + +# CUPED-adjusted metric +df['adjusted_metric'] = df.metric - theta * (df.pre_metric - df.pre_metric.mean()) + +# Run t-test on the adjusted metric +from scipy import stats +control_adj = df[df.variant_id == 'control'].adjusted_metric +treatment_adj = df[df.variant_id == 'treatment'].adjusted_metric +t_stat, p_value = stats.ttest_ind(treatment_adj, control_adj, equal_var=False) + +# Compare to unadjusted variance +unadjusted_var = df.metric.var() +adjusted_var = df.adjusted_metric.var() +variance_reduction = 1 - adjusted_var / unadjusted_var +print(f"Variance reduction: {variance_reduction:.1%}") +``` + +### When CUPED works well + +- Engagement metrics with strong autocorrelation. Pre-experiment activity strongly predicts in-experiment activity. +- Revenue metrics on consumer products with repeat customers. +- Retention metrics where past retention predicts future retention. + +### When CUPED works poorly + +- New users (no pre-experiment data). They drop out of the analysis or are imputed. +- Metrics with weak temporal autocorrelation. The pre-period does not predict the in-period. +- Metrics that are zero for most users (highly skewed binary outcomes). The t-test's normal-distribution assumption fails; CUPED on top inherits the failure. + +### Pre-experiment window length + +A 28-day pre-experiment window is the typical default. Longer windows (60 to 90 days) capture more of the user's behavior pattern and may reduce variance more, but also reduce eligibility (users who joined within the window have no pre-period). + +The discipline. Pre-register the pre-period length when designing the experiment. Do not change it after looking at results. + +--- + +## Stratification + +Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. + +```python +# Stratify by device +strata = df.device_type.unique() +stratum_estimates = [] +for s in strata: + sub = df[df.device_type == s] + diff = sub[sub.variant_id == 'treatment'].metric.mean() - sub[sub.variant_id == 'control'].metric.mean() + stratum_estimates.append({ + 'stratum': s, + 'n': len(sub), + 'diff': diff, + }) + +# Pool: weighted average by stratum size +total_n = sum(s['n'] for s in stratum_estimates) +pooled_diff = sum(s['diff'] * s['n'] / total_n for s in stratum_estimates) +``` + +The variance of the pooled estimate is lower than the unpooled t-test when the strata have different baseline metrics (the across-stratum variance is removed). + +The downside. Stratification by too many covariates produces small per-stratum samples, which inflates per-stratum variance. Use stratification on one or two strong predictors, not on every covariate available. + +--- + +## Regression adjustment (covariate adjustment via OLS) + +A generalization of CUPED to multiple covariates. + +```python +import statsmodels.api as sm + +# X: covariates (pre_metric, device_type encoded, region encoded) +X = pd.get_dummies(df[['pre_metric', 'device_type', 'region']], drop_first=True) +X['variant_treatment'] = (df.variant_id == 'treatment').astype(int) +X = sm.add_constant(X) +y = df.metric + +# OLS regression +model = sm.OLS(y, X).fit() +print(model.summary()) + +# The coefficient on 'variant_treatment' is the adjusted effect estimate. +# Its standard error is typically smaller than the unadjusted t-test SE. +``` + +Regression adjustment is more flexible than CUPED but requires more care: collinearity among covariates, model misspecification, and overfitting on small samples are all possible failure modes. + +For most warehouse-native experiments, CUPED with a single pre-period covariate is enough. Regression adjustment with multiple covariates is for edge cases. + +--- + +## Doubly robust estimation + +Useful in observational and quasi-experimental settings where randomization was imperfect (geo experiments, switchback designs, natural experiments). + +The intuition. Combine an outcome model (predict the metric from covariates) with a propensity-score model (predict the probability of treatment from covariates). The combined estimator is unbiased if either of the two models is correct (hence "doubly robust estimation"). + +For the standard A/B test where assignment is random, doubly robust estimation does not help. The benefit is in observational settings where the assignment mechanism may be confounded. + +The implementation requires `causalml`, `dowhy`, or a custom implementation. Outside the scope of the typical experiment notebook; pointer to the academic literature for full treatment. + +References. + +- Bang and Robins (2005), "Doubly Robust Estimation in Missing Data and Causal Inference Models." +- Funk et al. (2011), "Doubly Robust Estimation of Causal Effects." + +--- + +## When to invest in variance reduction + +Three signals. + +1. **Running 5+ experiments per quarter.** The amortized engineering investment in CUPED pays back across many experiments. +2. **The team is power-constrained.** Experiments routinely run too long or hit inconclusive results because of insufficient sample size. CUPED extends the effective sample size by 30 to 50 percent. +3. **The team has data scientists who understand the math.** CUPED is straightforward but easy to implement incorrectly (theta computed on the wrong subset, pre-period window misaligned, regression diagnostics ignored). Without someone on the team who can audit the implementation, the variance reduction may not be real. + +The order of investment. CUPED first; it is the highest ROI. Stratification second; useful for one or two strong predictors. Regression adjustment third; for edge cases where multiple covariates matter. Doubly robust estimation last; for genuine quasi-experiments. + +--- + +## Common variance reduction mistakes + +- **Computing theta on treatment data only.** Theta should be computed on the combined dataset (control plus treatment) for unbiased estimation. Computing on treatment alone re-introduces the bias CUPED is trying to remove. +- **Pre-period contamination.** The pre-period overlaps with the experiment period. Users in the experiment have already been exposed when their "pre-period" metric is measured. The pre-metric is not actually pre. +- **CUPED on heavily skewed binary metrics.** CUPED reduces variance but does not change the metric's distribution. A binary metric where 99 percent of users are 0 is still skewed after CUPED; the t-test is still misspecified. +- **Stratification on a post-experiment covariate.** The covariate must be measured before the experiment, otherwise the stratification creates selection bias. Use only pre-experiment covariates for stratification. +- **Forgetting to validate that variance actually decreased.** Run both adjusted and unadjusted analyses; verify the adjusted variance is smaller. If it is not, CUPED is not helping for this metric and pre-period. diff --git a/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md b/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md new file mode 100644 index 0000000..21e0222 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md @@ -0,0 +1,145 @@ +# Warehouse vs platform decision + +Side-by-side comparison. Cost considerations at scale. Hybrid patterns. Migration patterns. Decision tree. + +The principle. Both operational models are valid. The right choice depends on team strength, volume, custom-metric needs, and how much engineering time you are willing to invest in experimentation infrastructure. + +--- + +## Side-by-side comparison + +| Dimension | Platform (Statsig, Optimizely, etc.) | Warehouse-native | +|---|---|---| +| Time to first experiment | Hours to days | Days to weeks | +| Custom metric depth | Limited to platform's metric library | Anything you can write in SQL | +| Custom segmentation | Platform-specific filters | dbt models compose without limit | +| Cost shape | Per-MAU or per-event subscription | Existing warehouse compute | +| Engineering investment | Low | Medium to high | +| Sequential testing | Out of the box | Build it yourself or skip | +| Frontend visual editing | Optimizely, VWO ship this | Not applicable | +| Mobile SDK assignment | Out of the box | Build it yourself | +| Trust and audit | Platform's math is a black box | Every step is auditable SQL | +| Iteration speed on metric definitions | Platform release cadence | dbt deploy cadence | +| Ecosystem integration | Platform's connectors | Warehouse already has the data | + +--- + +## Cost considerations at scale + +Approximate costs as of 2025-2026. Verify with vendor pricing. + +### 10K MAU + +- Platform (mid-tier): $0 to $500 per month. Free tiers from PostHog, Statsig, Amplitude cover this. +- Warehouse-native: warehouse compute already paid for. Engineering time cost: 1 to 2 weeks of a data engineer's time to set up infrastructure. + +Recommendation. Platform. The engineering time on warehouse-native at this scale does not pay back. + +### 100K MAU + +- Platform (mid-tier): $1K to $10K per month. Statsig, PostHog paid tiers; Optimizely contract. +- Warehouse-native: same warehouse compute; engineering time amortized over more experiments. + +Recommendation. Either. Depends on team strength and custom-metric needs. Many teams stay on a platform; some graduate to warehouse-native. + +### 1M MAU + +- Platform: $10K to $80K per month, often more for enterprise contracts. Optimizely Enterprise can hit $200K+ per year. +- Warehouse-native: same warehouse compute. The engineering investment pays back at this scale. + +Recommendation. Warehouse-native is increasingly attractive. Many enterprise data teams run warehouse-native primary, with a platform for specific use cases (frontend visual experiments). + +### 10M+ MAU + +- Platform: enterprise contracts at $200K to $1M+ per year. +- Warehouse-native: dominant pattern at this scale. Custom infrastructure plus dbt plus Python notebooks. + +Recommendation. Warehouse-native, often with a thin platform for fast frontend iteration. + +--- + +## Hybrid patterns + +Three common hybrid patterns. + +### Pattern 1: platform for product, warehouse-native for analytics + +The platform handles assignment and exposure for product experiments. The warehouse handles analysis for the same experiments by reading the platform's exposure data. + +Why. The platform's analysis is fine for standard cases; warehouse-native analysis allows custom metrics and segmentation the platform cannot express. + +Operational shape. The platform's exposure events flow to the warehouse (typically via webhook or scheduled export). dbt models compute custom metrics; the analyst runs the t-test in Python against the joined data. + +### Pattern 2: warehouse-native for backend, platform for frontend + +Warehouse-native handles backend experiments where assignment is server-side (pricing, recommendations, ML model variants). The platform handles frontend visual experiments (button colors, copy, layout). + +Why. Frontend visual experiments benefit from the platform's WYSIWYG editor and script-tag injection. Backend experiments benefit from warehouse-native's metric flexibility. + +Operational shape. Two separate experiment registries. Each team picks the right tool for the experiment type. + +### Pattern 3: platform for fast iteration, warehouse-native for hard cases + +The platform handles experiments where time-to-result matters more than custom depth. Warehouse-native handles experiments where the platform cannot express the metric. + +Why. Most experiments are standard; the platform is faster. The 10 percent that are not standard need the warehouse. + +Operational shape. Default to platform; escalate to warehouse-native when the platform fails to support the experiment design. + +--- + +## Migration patterns + +### Platform to warehouse-native + +Triggered by cost (the platform bill became a budget item) or capability (the platform cannot handle a specific experiment design that matters). Typical effort: 6 to 12 engineer-weeks for the first warehouse-native experiment with full infrastructure; later experiments amortize the investment. + +Steps. Build the assignment hash function. Build the exposure logging discipline. Define the first metric in dbt. Run a parallel experiment on the platform and warehouse-native; verify results match within statistical noise. Migrate experiments one at a time; retire the platform when the last in-flight experiment completes. + +### Warehouse-native to platform + +Triggered by team contraction (the data engineer who built the infrastructure left) or by velocity needs (experiments are taking too long to set up). Typical effort: 2 to 4 engineer-weeks; the platform handles the heavy lifting. + +Steps. Pick the platform. Wire up assignment and exposure. Migrate the metric library to the platform's format. Run the first experiment on the platform; verify results align with what warehouse-native would have produced. + +The frequent reverse migration. Companies that move to warehouse-native and discover the engineering investment is too much. The migration back is usually faster than the migration out. + +--- + +## Decision tree + +``` +Is your team running 5+ experiments per quarter? +├── No → Platform. Warehouse-native does not pay back at low volume. +└── Yes → Continue. + │ + Do you have a data engineer and a data scientist? + ├── No → Platform. Warehouse-native requires both roles. + └── Yes → Continue. + │ + Are your experiments primarily frontend visual? + ├── Yes → Platform (Optimizely, VWO). Warehouse-native cannot match. + └── No → Continue. + │ + Do you need custom metrics the platform cannot express? + ├── Yes → Warehouse-native. The custom metric is the use case. + └── No → Continue. + │ + Is the platform bill exceeding 10x the cost of the engineering time? + ├── Yes → Warehouse-native. The math justifies it. + └── No → Platform. The simplicity is worth the cost. +``` + +The defaults. New teams: platform. Mature teams with strong data infrastructure and high volume: hybrid or warehouse-native primary. The decision is never permanent; revisit annually. + +--- + +## When the math is wrong + +Two situations where teams misjudge the build-vs-buy. + +**Underestimating engineering cost.** "We can build this in a week" rarely holds. The first experiment takes weeks; the second takes days; the long tail of pitfalls (CUPED, sequential testing, SRM checks, dashboard reconciliation) adds up to months of engineering investment. Budget realistically. + +**Overestimating platform limitations.** "The platform cannot handle our metric" is sometimes true and sometimes a workflow problem. Verify with the vendor; many platforms have advanced features (Cortex Analyst on Snowflake, custom SQL metrics on Statsig) that solve the apparent limitation. + +The honest test. Run a 30-day proof of concept on the platform with the actual experiment you say it cannot handle. If the platform truly fails, warehouse-native is justified. If the platform works (even if imperfectly), the cost-benefit shifts back toward the platform. diff --git a/skills/dependency-management/SKILL.md b/skills/dependency-management/SKILL.md new file mode 100644 index 0000000..4ea6220 --- /dev/null +++ b/skills/dependency-management/SKILL.md @@ -0,0 +1,326 @@ +--- +name: dependency-management +description: "Manage third-party libraries, runtimes, and SaaS dependencies. Use this skill when setting an update cadence, responding to security advisories, dealing with deprecated dependencies, evaluating new dependencies, auditing what's installed, or unblocking a dependency upgrade. Triggers on dependency, package update, security patch, lockfile, deprecated, breaking change, supply chain, dependency audit, npm audit, dependabot, renovate. Also triggers when a build breaks after an update or when an advisory is published for a used package." +category: cross-cutting +catalog_summary: "Package updates, security patches, lockfile hygiene" +display_order: 4 +--- + +# Dependency Management + +Decide what to depend on, keep dependencies current, respond to advisories, and reduce supply chain risk. Stack-agnostic principles; specifics vary by package manager. + +--- + +## When to use + +- Setting up dependency hygiene for a new or existing project +- Responding to a security advisory +- Major version upgrade of a key dependency +- Adding a new dependency (evaluation, decision) +- Removing a dependency (cleanup) +- Audit of what's installed and what's actually used +- Setting an update cadence and policy +- Diagnosing a broken build after an update + +## When NOT to use + +- General code review (use `code-review-web`) +- Vulnerability scanning of infrastructure (use `security-baseline`) +- Pinning vendor or service contracts (use `vendor-evaluation`) +- Performance impact of dependencies (use `performance-optimization`) + +--- + +## Required inputs + +- Package manager and lockfile in use (npm, yarn, pnpm, pip, gem, composer, etc.) +- Current dependency list (production and dev) +- Current advisories (run audit; check service like Snyk, Dependabot) +- Update history (when were major dependencies last updated) +- Risk profile (production criticality, change tolerance) + +--- + +## The framework: 4 categories of dependency + +Every dependency falls into one of these. The category drives the policy. + +### Category 1: Critical runtime + +Code that runs in production and would break the system if it failed. + +Examples: framework, database driver, payment SDK, authentication library. + +Policy: +- **Update cadence:** monthly minor, quarterly major (with planning) +- **Security:** patch within 24-72 hours of advisory, 24h for critical +- **Pinning:** exact version pins or narrow ranges +- **Vetting:** thoroughly evaluated before adoption + +### Category 2: Supporting runtime + +Code that runs in production but is replaceable or non-critical. + +Examples: utility libraries, formatting, non-core integrations. + +Policy: +- **Update cadence:** monthly together with critical +- **Security:** patch within a week of advisory +- **Pinning:** narrow ranges acceptable (e.g., `^1.2.3`) +- **Vetting:** moderate evaluation; alternatives considered + +### Category 3: Dev/build + +Code that runs only during development or build, not in production. + +Examples: bundlers, linters, test frameworks, type checkers. + +Policy: +- **Update cadence:** quarterly +- **Security:** patch within a week (still matters; supply chain attacks target build tools) +- **Pinning:** ranges acceptable +- **Vetting:** lighter; broken dev tools surface fast + +### Category 4: Optional/dev-only-personal + +Tools individual developers use that aren't part of shared dev environment. + +Not really managed at the project level. Mentioned for completeness. + +--- + +## The framework: 5 risk dimensions + +When evaluating a dependency, consider: + +### Dimension 1: Maintenance health + +- Last commit date (months ago is concerning) +- Open issue count and age +- Number of maintainers +- Sponsorship or commercial backing +- Roadmap visibility + +A dependency abandoned a year ago is a liability waiting to surface. + +### Dimension 2: Surface area + +- Size of the package +- Number of transitive dependencies +- Footprint in the bundle (for client-side) +- Privileges required (file system, network, etc.) + +A small dependency that pulls in 50 transitive packages has the surface area of all 50. + +### Dimension 3: Replaceability + +- How hard would it be to remove? +- Are there alternatives? +- Could the functionality be implemented in-house? +- Is the API standard or idiomatic? + +A dependency you can't replace is leverage you've granted to its maintainer. + +### Dimension 4: Trust + +- Reputation of the maintainer or organization +- Code quality (skim the source) +- License (GPL, MIT, BSD, proprietary, none) +- History of security issues +- Supply chain practices (signed releases, 2FA on publishes) + +### Dimension 5: Cost + +- Time to evaluate, integrate, maintain +- Risk of breaking changes +- Lockfile entropy +- Potential security exposure +- Bundle size impact (for client-side) + +Every dependency has a cost. Free packages aren't free. + +--- + +## Workflow + +### Step 1: Inventory + +Run a dependency listing: + +```bash +# npm/yarn/pnpm +npm ls --all --json + +# pip +pip list + +# gem +bundle list +``` + +For each top-level dependency, categorize (critical / supporting / dev). For transitives, you generally don't manage individually unless one becomes a problem. + +### Step 2: Audit + +Run the security audit: + +```bash +npm audit +yarn audit +pip-audit +bundle audit +``` + +For each finding: +- Severity (critical, high, medium, low) +- Package and version +- Fix available? +- Used directly or transitively? + +### Step 3: Categorize and prioritize + +| Severity | Direct dep | Indirect dep | +|---|---|---| +| Critical | Patch today | Patch this week (if a fix exists; track if not) | +| High | Patch this week | Patch this month | +| Medium | Patch this month | Track; patch with next round | +| Low | Track | Track | + +Critical and high in production code are emergencies. Low and medium are scheduled work. + +### Step 4: Test before merging fixes + +Even patch-level updates can break things. For critical dependencies: +- Run the full test suite +- Smoke-test in staging +- Watch the monitoring after rollout + +For supporting and dev: +- Run the test suite +- A failed test is OK to investigate; don't merge a known-broken update + +### Step 5: Plan major version upgrades + +Major versions break things. Plan rather than rush. + +For each major upgrade: +- Read the changelog and migration guide +- Estimate the migration effort +- Schedule the work (don't do it under deadline pressure) +- Branch and test thoroughly +- Plan a staged rollout if it's a critical dependency + +Don't sit on major versions indefinitely. The longer you wait, the more painful the upgrade. + +### Step 6: Set the policy + +Document: +- Update cadence (e.g., monthly review, quarterly upgrades) +- Security response SLA (e.g., critical within 24h) +- Approval for new dependencies (who signs off) +- Removal criteria (when do we drop a dependency) +- Pinning strategy (exact, narrow range, broad range) + +The policy is what survives team turnover. Without it, dependency management becomes chaotic ad hoc work. + +### Step 7: Automate + +- **Renovate** or **Dependabot** for automatic update PRs +- CI runs audit on every PR +- Block merges on critical advisories (with override path for false positives) +- Notify on advisories for installed packages +- Lockfile diff in PR review + +Automation reduces toil. Manual checking doesn't scale. + +### Step 8: Audit usage periodically + +Quarterly: +- Dependencies installed but not imported anywhere (run a tool like `depcheck`) +- Major versions behind (more than 1-2 majors behind = upgrade plan needed) +- Unmaintained packages (last commit over a year ago = consider replacing) +- License audit (anything that's changed terms?) + +Remove what's not used. Replace what's unmaintained. + +--- + +## New dependency evaluation + +Before adding a new dependency, answer: + +- [ ] What problem does this solve? +- [ ] Could we solve it without a dependency? (Often yes for small problems.) +- [ ] What alternatives exist? +- [ ] Is the package actively maintained? +- [ ] What's the install size and bundle impact? +- [ ] What are the transitive dependencies? (Worth a quick scan.) +- [ ] What's the license? +- [ ] What's the security history? +- [ ] How replaceable is it? + +Default: don't add. Add only when the value clearly exceeds the cost. The cost includes ongoing maintenance, not just installation. + +--- + +## Dependency removal + +When removing a dependency: + +- [ ] Identify all usages (search the codebase) +- [ ] Replace each usage (with native code, another dependency, or a no-op) +- [ ] Remove from package.json or equivalent +- [ ] Update lockfile (run install) +- [ ] Verify tests pass +- [ ] Verify build size went down (or stayed the same) +- [ ] Document the removal in the changelog + +Removed dependencies sometimes leave config files, CI hooks, or imports behind. Search broadly. + +--- + +## Failure patterns + +**No update cadence.** Dependencies drift. When you finally upgrade, it's painful. Set a cadence. + +**Audit disabled in CI.** "Too noisy." Tune the audit, don't disable it. Whitelist known false positives explicitly. + +**Pinning everything to exact versions.** Stops automatic patches. Misses security fixes. Use narrow ranges with a lockfile. + +**Unpinned floating versions.** `latest` in production. Builds aren't reproducible. Lockfile required. + +**Adding dependencies without review.** "I just needed a quick utility." Now there are 50 unused dependencies. Require review for new dependencies. + +**Ignoring transitive dependencies.** A direct dependency pulls in 50 indirect ones. Each is supply chain surface. Audit the tree, not just the top level. + +**Patching with major version bumps.** "Updating to fix a bug" but the update is a major version. Now you have unrelated breaking changes too. Be deliberate about the version of the fix. + +**Vendor-bundled libraries.** Some dependencies vendor copies of other dependencies. They're not visible to the audit. Periodically check. + +**Build-time dependencies treated as zero-risk.** Build tools have access to your code and credentials. Supply chain attacks target them. Treat with appropriate care. + +**Fork without rebase plan.** Forking a dependency to fix something. Then you own it. Plan how to rebase or merge upstream changes, or commit to maintaining the fork. + +**No license audit.** Project ships with a GPL dependency in a commercial product. Compliance issue. Audit licenses on add and quarterly. + +**Update PRs piling up.** Dependabot PRs go unmerged for months. Either tune to fewer PRs or commit time to merging them. + +--- + +## Output format + +A dependency policy document includes: + +- **Inventory:** current dependencies by category +- **Audit status:** open advisories, severity, plan +- **Policies:** cadence, SLA, pinning, approval +- **Tooling:** what's automated (Renovate, Dependabot, audit in CI) +- **License audit:** any concerns +- **Quarterly review schedule:** when this gets revisited + +--- + +## Reference files + +- [`references/upgrade-checklist.md`](references/upgrade-checklist.md): Step-by-step checklist for performing a major version upgrade of a critical dependency, from changelog reading to staged rollout. diff --git a/skills/dependency-management/references/upgrade-checklist.md b/skills/dependency-management/references/upgrade-checklist.md new file mode 100644 index 0000000..f9e6929 --- /dev/null +++ b/skills/dependency-management/references/upgrade-checklist.md @@ -0,0 +1,290 @@ +# Major Version Upgrade Checklist + +Step-by-step checklist for upgrading a critical dependency to a new major version. The work is in the prep, not the install. + +--- + +## Phase 1: Decide whether to upgrade + +- [ ] Read the changelog from current version to target version +- [ ] Read the migration guide (most major libraries publish one) +- [ ] Skim issues filed against the new version (early adopters surface problems) +- [ ] Note any other dependencies that may need to upgrade in tandem +- [ ] Estimate effort (hours, days, weeks?) +- [ ] Estimate risk (low/medium/high) +- [ ] Estimate value (security fix, new features, ecosystem support, etc.) + +Decision: GO, DEFER, or SKIP. + +**GO triggers:** +- Security fix only available in new major +- Current version losing support +- New version unblocks a needed feature +- Effort and risk are manageable + +**DEFER triggers:** +- New version released within last 30 days (let early adopters surface bugs) +- Conflicts with active development +- No urgent driver + +**SKIP triggers:** +- Maintenance discontinued; replace the dependency instead +- Migration effort exceeds the value +- A different replacement is the better path + +--- + +## Phase 2: Prepare + +### Branch + +- [ ] Create a feature branch named for the upgrade (e.g., `upgrade/library-v3`) +- [ ] Don't mix the upgrade with other work; isolate it + +### Read the changelog carefully + +- [ ] List every breaking change between current and target version +- [ ] Note deprecations that affect your code +- [ ] Note new patterns or APIs you'll use after the upgrade + +For each breaking change: +- Where does this affect our code? +- What's the migration path? +- Is there a codemod available? + +### Search for usages + +- [ ] Grep for every API surface used (function names, import paths) +- [ ] Identify call sites that need attention +- [ ] Identify tests that may break + +For complex libraries, this can be the longest step. Be thorough. + +### Check the ecosystem + +- [ ] Plugins or related packages that depend on the library: do they support the new version? +- [ ] TypeScript types: are they updated? +- [ ] Documentation and examples in the wild: have they caught up? + +--- + +## Phase 3: Upgrade + +### Install + +- [ ] Update the version in package.json (or equivalent) +- [ ] Update related packages (plugins, types, etc.) to compatible versions +- [ ] Run install, generate fresh lockfile +- [ ] Verify the install completes without errors + +```bash +# Example +npm install library@^3.0.0 +``` + +### Initial build + +- [ ] Run the build +- [ ] Note every error and warning +- [ ] Don't fix anything yet; just inventory + +### Inventory the breakage + +Categorize each error: +- **Type errors:** API signatures changed +- **Import errors:** module structure changed +- **Runtime errors:** behavior changed +- **Test failures:** assumed behavior changed +- **Lint warnings:** patterns deprecated + +This list is your work plan. + +--- + +## Phase 4: Migrate + +### Apply codemods first + +If the library publishes codemods: + +```bash +npx codemod-name path/to/code +``` + +Codemods handle the mechanical parts (renamed APIs, restructured imports). They're not perfect, but they reduce toil. + +- [ ] Run codemods +- [ ] Review the diff (codemods can over-apply or under-apply) +- [ ] Commit the codemod changes separately + +### Fix manual issues + +For each remaining issue: +- [ ] Identify the root cause (what changed in the new version?) +- [ ] Apply the fix per the migration guide +- [ ] Verify tests pass for that area +- [ ] Commit incrementally (small commits, easy to revert) + +### Update tests + +- [ ] Tests using deprecated patterns: update to new patterns +- [ ] Tests that fail because behavior is different: investigate. Is the new behavior correct? +- [ ] Add tests for any new behavior you depend on + +### Update documentation + +- [ ] README references to the old version +- [ ] Internal docs and runbooks +- [ ] Comments referencing the old behavior + +--- + +## Phase 5: Verify + +### Local + +- [ ] All tests pass (unit, integration, E2E) +- [ ] Build succeeds without warnings (or with only acceptable warnings) +- [ ] Lint passes +- [ ] Type check passes (if typed) +- [ ] No console warnings in dev mode that weren't there before + +### Visual + +For UI-affecting libraries: +- [ ] Visual regression tests (Chromatic, Percy, or similar) clean +- [ ] Manual smoke test of key user flows +- [ ] Check on multiple browsers/devices + +### Performance + +- [ ] Bundle size: comparable or better +- [ ] Build time: comparable +- [ ] Runtime performance: comparable on key paths + +If bundle size or performance regresses meaningfully, investigate before merging. + +### Compatibility + +- [ ] Browser compatibility (if relevant) maintained +- [ ] Node version compatibility (if relevant) maintained +- [ ] Other dependencies still work with the new version + +--- + +## Phase 6: Stage + +For critical dependencies, don't go straight to production. + +- [ ] Deploy to a staging environment +- [ ] Run automated tests against staging +- [ ] Smoke-test critical flows manually +- [ ] Watch monitoring for new errors +- [ ] Watch performance metrics for regressions +- [ ] Let it bake for at least 24 hours (longer for critical systems) + +--- + +## Phase 7: Roll out + +Strategy depends on the dependency and the risk: + +### Low risk: standard deploy + +- [ ] Merge the PR +- [ ] Deploy to production +- [ ] Watch monitoring for the next few hours +- [ ] Be ready to rollback + +### Medium risk: feature flag or canary + +- [ ] Behind a feature flag if applicable +- [ ] Deploy with traffic splitting (1% to new, 99% to old, if infrastructure supports) +- [ ] Gradually increase traffic +- [ ] Watch metrics at each step + +### High risk: parallel run + +- [ ] Run old and new side by side +- [ ] Compare outputs +- [ ] Switch over only when confident + +--- + +## Phase 8: Monitor + +For at least one week post-rollout: + +- [ ] Error rates (compare to pre-upgrade baseline) +- [ ] Performance metrics +- [ ] User-reported issues +- [ ] Any unexpected behavior + +If issues appear: +- [ ] Triage by severity +- [ ] Fix forward (most common) +- [ ] Or rollback (if severe) +- [ ] Document the issues for the next upgrade + +--- + +## Phase 9: Document + +After the upgrade is stable: + +- [ ] Note the upgrade in the changelog +- [ ] Document any non-obvious migrations for future reference +- [ ] Update internal docs that referenced the old version +- [ ] If the upgrade was painful, write a note for next time +- [ ] Thank anyone who helped (especially open-source maintainers if they helped) + +--- + +## Common gotchas + +**Bundle size grows unexpectedly.** New version pulls in additional code or dependencies. Check the bundle analysis. + +**Tests that "passed but didn't actually run."** Test infrastructure breaks silently in some upgrades. Verify tests are running, not just exiting clean. + +**TypeScript types don't match runtime.** Sometimes types are updated but runtime isn't (or vice versa). Test runtime behavior, not just types. + +**Server-side rendering breaks.** New version uses browser-only APIs. Check SSR if applicable. + +**Tree-shaking changes.** Bundle includes more or different code. Verify what's actually shipped. + +**Peer dependency conflicts.** Library A wants version X, library B wants version Y. Resolve carefully; sometimes requires upgrading multiple in tandem. + +**Breaking changes in transitive dependencies.** The upgrade pulls in a new major of a transitive. The transitive's breaking changes affect you indirectly. + +**API changes that compile but behave differently.** Same function name, different default behavior. Read the changelog. + +**Migration guide assumes specific framework or stack.** If you use the library in a non-standard way, the guide may not cover your case. Adapt. + +--- + +## When to abort + +It's OK to abort an upgrade. Better to abort than ship a broken version. + +Abort triggers: +- Migration effort blowing past estimate by 5x+ +- Discovering critical incompatibilities mid-migration +- Finding that the new version has bugs blocking your use case +- Realizing the dependency itself is the problem (consider replacement) + +After aborting: +- Keep the branch around for reference +- Document what you learned +- Schedule a retry when conditions are better, or pivot to replacement + +--- + +## Reference for next time + +After every major upgrade, capture: +- Total effort (hours) +- Surprises encountered +- Things that worked well +- Things to do differently + +This becomes input to estimating the next major upgrade. Major upgrades happen periodically; the team gets better at them with practice and notes. diff --git a/skills/design-standards/SKILL.md b/skills/design-standards/SKILL.md new file mode 100644 index 0000000..ee3d5dd --- /dev/null +++ b/skills/design-standards/SKILL.md @@ -0,0 +1,213 @@ +--- +name: design-standards +description: "Apply production-grade design standards when building or reviewing pages, components, or UI. Use this skill whenever the user asks to build a page, design a component, lay out a section, review the UI, fix the layout, or check design quality. Triggers on build a page, create a component, design a section, hero, card, CTA, layout, review the UI, fix the design, design system, design tokens, spacing, typography scale, button standards, mobile design. Also triggers for any production design decision where contrast, accessibility, spacing, or visual hierarchy matters." +category: design +catalog_summary: "Production-grade page and component design standards" +display_order: 2 +--- + +# Design Standards + +Production design standards for any web project. Stack-agnostic. Tool-agnostic. Covers tokens, contrast, hierarchy, spacing, mobile rules, and the pre-ship checklist. + +This skill complements `brand-identity` (which defines the visual system) and `brand-style-guide` (which documents it). This skill is for the day-to-day work of applying those standards in real components and pages. + +--- + +## When to use + +- Building a new page, section, or component +- Reviewing UI for quality, accessibility, or consistency +- Setting up design tokens for a new project +- Fixing layout, contrast, or hierarchy issues +- Establishing a button or form standard +- Pre-ship design review + +## When NOT to use + +- Defining a brand identity from scratch (use `brand-identity`) +- Documenting a finished brand system (use `brand-style-guide`) +- Building a formal component library (use `design-system`) +- Frontend code architecture (use `frontend-component-build`) +- Accessibility-only audits with WCAG remediation (use `accessibility-audit`) + +--- + +## Required inputs + +- The page or component being built or reviewed +- The brand's design tokens (colors, type, spacing) - or willingness to define them +- The target devices and viewports + +If brand tokens are undefined, define a working set first using the template in [`references/design-tokens-template.md`](references/design-tokens-template.md). + +--- + +## The framework: 6 standards + +Six standards apply to every piece of UI. Hold the line on these and most design problems disappear. + +### 1. Design tokens + +Every project needs tokens defined before any UI gets built. Tokens are the source of truth. + +**Color tokens** (minimum): +- Primary brand color +- Primary hover (typically 15 to 25 percent darker) +- Background variants (surface, alt-section, hero/dark, footer) +- Text scale (heading, body, muted, on-dark) +- Semantic (success, warning, error, info) + +**Spacing tokens:** +- A consistent scale (e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96) +- Page max-width +- Section vertical padding (large, medium, small) +- Card padding +- Grid gaps + +**Type tokens:** +- Display, H1 through H4, body large, body, small, caption +- Each with size, weight, line height, letter spacing +- Font fallback stacks + +**Radius tokens:** +- Tight (cards, badges) +- Standard (buttons, inputs) +- Round (avatars, pill buttons) + +Document the tokens once. Reference them everywhere. Hardcoded values are technical debt. + +### 2. WCAG AA contrast (non-negotiable) + +Contrast is not a preference. It is a baseline. A design that fails AA is broken, regardless of how it looks to designers with full vision. + +| Element | Required ratio | +|---|---| +| Normal body text | 4.5:1 | +| Large text (18pt regular or 14pt bold) | 3:1 | +| UI components and graphical elements | 3:1 | + +Common failures to avoid: +- Light gray body text on white that calculates to 2 to 4:1 +- Brand color used for body text without a darker variant +- Light borders on form fields that compute under 3:1 +- Bright orange or yellow on white at small sizes + +For the math, the contrast checker, and brand-color strategies, see `brand-identity/references/contrast-and-accessibility.md`. + +### 3. Visual hierarchy + +A well-designed page has a clear scan order. Hierarchy comes from: + +- **Size.** The largest element gets noticed first. +- **Weight.** Bold beats regular at the same size. +- **Color.** Saturated beats neutral. High-contrast beats low. +- **Spacing.** What sits alone gets emphasis. What gets crowded recedes. +- **Position.** Top-left and center get weight. Edges and corners recede. + +Apply hierarchy intentionally. Every visual element should be reachable through the hierarchy. If three things compete for primary attention, none of them wins. + +**Common failures:** +- Multiple elements styled as the "primary" CTA (creates ambiguity) +- Body text and headlines too close in size +- Hero image fighting the hero text for attention +- Icon, headline, and image at similar visual weight + +### 4. Spacing and rhythm + +Spacing is what separates a polished layout from a cluttered one. + +**Rules:** +- Use the spacing scale, not arbitrary values +- Related elements sit closer together than unrelated ones (proximity principle) +- Section breathing room: minimum 64px desktop, 48px mobile +- Card padding: minimum 24px desktop, 16px mobile +- Form field spacing: minimum 16px between fields +- Touch targets: minimum 44 by 44 pixels + +**Common failures:** +- Inconsistent spacing within similar contexts (one card has 24px padding, the next has 32px) +- Cramped sections that bleed into each other +- Touch targets under 44 pixels on mobile +- Headline butted directly against subheadline with no rhythm + +### 5. Mobile rules + +Most users are on mobile. Designing for desktop first guarantees mobile failures. + +**Standards:** +- Test on a 375 to 390 pixel viewport before declaring complete +- All interactive elements minimum 44 by 44 pixels +- Sticky bottom bars: page wrapper needs bottom padding equal to bar height +- No fixed pixel widths without max-width constraint +- Text never smaller than 14 pixels for body content +- Tap targets get 8 pixels of spacing minimum on all sides +- Modal and popover content scrolls; body locks +- Form inputs: at least 16px text size to prevent iOS auto-zoom + +**Common failures:** +- Designs that work in browser dev tools but break on real devices +- Sticky navigation eating 80px of viewport without compensation +- Horizontal scroll appearing because of one over-wide element +- Tap targets that are visually fine but impossibly close to other tap targets + +### 6. Component consistency + +The same thing should look the same everywhere. Variations should be intentional. + +**Common consistency principles:** +- Buttons: one primary style, one secondary style, one ghost style. Not five. +- Cards: one base card pattern with variants. Not bespoke cards per page. +- Icons: one stroke weight, one corner style across the icon set +- Avatars and brand marks: one shape rule (rounded-lg or fully round, pick one and stick to it) +- Form inputs: one set of input states (default, focus, error, disabled) used everywhere + +**Common failures:** +- Three different "primary buttons" used inconsistently across pages +- Some cards with rounded-2xl corners, others with rounded-xl +- Iconography style drifting between sections +- Brand avatar that switches between square and round depending on the page + +--- + +## Workflow + +1. **Confirm tokens.** If tokens are not yet defined, define a working set first. Document them. +2. **Sketch hierarchy.** Before writing markup, identify the primary action, secondary actions, and supporting content. Confirm the scan order makes sense. +3. **Build mobile-first.** Lay out for the smallest target viewport before scaling up. +4. **Apply tokens.** All values come from the token set. No hardcoded colors, sizes, or spacing. +5. **Run contrast checks.** Every text-on-background combination passes AA. Every UI element passes 3:1. +6. **Test at viewport breakpoints.** 375, 768, 1024, 1440 minimum. Confirm nothing breaks. +7. **Run the pre-ship checklist** in [`references/preship-checklist.md`](references/preship-checklist.md). + +--- + +## Failure patterns + +- **Designing without tokens.** Hardcoded colors and spacing. Hard to maintain. Inconsistent at scale. +- **Skipping contrast checks.** Especially on brand colors used for text. Most brand colors fail AA. +- **Designing only for desktop.** Mobile reveals every layout sin. Test mobile first or last, but always. +- **Rounded-everything.** Treating "modern" as "rounded all the things." Rounded corners are a tool, not a default. +- **Visual hierarchy mush.** Three things competing as primary. Reader does not know where to look. +- **Touch target violations.** Visually nice 32px buttons that fail finger ergonomics on real devices. +- **Component drift.** Each page rebuilds the card or button from scratch. Design system erodes. + +--- + +## Output format + +This skill produces design decisions and review notes more than artifacts. Outputs include: + +- **Design tokens file** (when starting a project): `design-tokens.md` or equivalent +- **Component or page review**: markdown notes scored against the 6 standards, with specific fixes +- **Pre-ship checklist results**: pass/fail across the checklist with notes + +When generating component code (HTML, CSS, framework-specific markup), the SKILL.md remains stack-agnostic. Stack-specific patterns live in reference files. + +--- + +## Reference files + +- [`references/design-tokens-template.md`](references/design-tokens-template.md) - Template for setting up tokens for any project. +- [`references/preship-checklist.md`](references/preship-checklist.md) - Final design review checklist before shipping. +- [`references/tailwind-patterns.md`](references/tailwind-patterns.md) - Optional. Tailwind-specific component patterns (hero, cards, buttons, data rows) for projects on that stack. diff --git a/skills/design-standards/references/design-tokens-template.md b/skills/design-standards/references/design-tokens-template.md new file mode 100644 index 0000000..7e96765 --- /dev/null +++ b/skills/design-standards/references/design-tokens-template.md @@ -0,0 +1,248 @@ +# Design Tokens Template + +Tokens are the source of truth for color, spacing, typography, and other design decisions. Define them once at the start of the project. Reference them everywhere. + +This template is stack-agnostic. Adapt the syntax to your project: CSS custom properties, Tailwind config, design system JSON, Style Dictionary, Figma variables - the values stay the same. + +--- + +## Color tokens + +### Primary (brand) + +``` +brand/primary #XXXXXX /* signature brand color */ +brand/primary-hover #XXXXXX /* 15-25% darker, for hover states */ +brand/primary-text #XXXXXX /* darker variant if primary fails AA on white */ +``` + +### Background + +``` +bg/surface #FFFFFF /* default page background */ +bg/surface-alt #F9FAFB /* alternating section background */ +bg/hero #1A1D23 /* dark section for heroes, footers */ +bg/footer #111827 /* footer specifically */ +``` + +### Text scale + +Document each with the contrast ratio against the background it sits on. + +``` +text/heading #111827 /* heading on white = 16.9:1 */ +text/body #374151 /* body on white = 10.3:1 */ +text/muted #4B5563 /* muted on white = 7.6:1 PASS AA */ +text/subtle #6B7280 /* subtle on white = 5.1:1 PASS AA */ +text/on-dark #FFFFFF /* white on hero bg = 15.8:1 */ +text/on-dark-muted #D1D5DB /* on hero bg = 11.4:1 */ +``` + +Avoid going lighter than the muted/subtle colors above on white. Lighter grays fail AA. + +### Semantic + +``` +semantic/success #059669 /* on white = 4.5:1 PASS AA */ +semantic/warning #D97706 /* on white = 4.5:1 PASS AA */ +semantic/error #DC2626 /* on white = 4.7:1 PASS AA */ +semantic/info #2563EB /* on white = 5.6:1 PASS AA */ +``` + +For each semantic color, also define a tinted background and a darker text variant for badges and alert blocks. + +### Border and divider + +``` +border/default #E5E7EB /* default borders, subtle dividers */ +border/strong #D1D5DB /* form fields, interactive borders */ +border/focus #2563EB /* focus rings */ +``` + +--- + +## Spacing tokens + +A consistent scale prevents arbitrary values. + +``` +space/0 0 +space/1 4px +space/2 8px +space/3 12px +space/4 16px +space/5 20px +space/6 24px +space/8 32px +space/10 40px +space/12 48px +space/16 64px +space/20 80px +space/24 96px +space/32 128px +``` + +### Layout-specific spacing + +``` +layout/page-max-width 1280px (or 1440px for spacious designs) +layout/page-padding-x 16px mobile / 24px tablet / 32px desktop +layout/section-py-large 80px desktop / 64px mobile +layout/section-py-medium 48px desktop / 32px mobile +layout/section-py-small 32px desktop / 24px mobile +layout/card-padding 24px to 32px +layout/grid-gap 24px to 32px +``` + +--- + +## Typography tokens + +### Font families + +``` +font/display "[Display typeface]", system-ui, sans-serif +font/body "[Body typeface]", system-ui, sans-serif +font/mono "[Mono typeface]", ui-monospace, monospace +``` + +### Type scale + +| Token | Size | Weight | Line height | Letter spacing | Use | +|---|---|---|---|---|---| +| type/display-1 | 64px | 700 | 1.0 | -0.02em | Hero headlines | +| type/display-2 | 48px | 700 | 1.05 | -0.01em | Section heroes | +| type/h1 | 36px | 700 | 1.1 | 0 | Page titles | +| type/h2 | 28px | 600 | 1.2 | 0 | Section titles | +| type/h3 | 22px | 600 | 1.3 | 0 | Sub-sections | +| type/h4 | 18px | 600 | 1.4 | 0 | Component titles | +| type/body-large | 18px | 400 | 1.5 | 0 | Lead paragraphs | +| type/body | 16px | 400 | 1.6 | 0 | Default body | +| type/body-small | 14px | 400 | 1.5 | 0 | Captions, metadata | +| type/caption | 12px | 400 | 1.4 | 0.01em | Footnotes, labels | +| type/eyebrow | 12px | 600 | 1.4 | 0.08em | Uppercase eyebrows | + +### Mobile adjustments + +Mobile typography is typically 1 to 2 steps smaller for display sizes: + +``` +display-1: 64px desktop → 40px mobile +display-2: 48px desktop → 32px mobile +h1: 36px desktop → 28px mobile +``` + +Body sizes stay the same on mobile; never go below 14px. + +--- + +## Radius tokens + +``` +radius/none 0 +radius/sm 4px /* small badges, tags */ +radius/md 8px /* default for inputs */ +radius/lg 12px /* buttons, alerts */ +radius/xl 16px /* cards (small) */ +radius/2xl 20px /* cards (default) */ +radius/3xl 24px /* cards (prominent), modals */ +radius/full 9999px /* pill buttons, fully rounded */ +``` + +### Conventions for shapes + +``` +buttons (default): radius/full (pill) OR radius/lg (rounded rect) +buttons (form/utility): radius/md +inputs: radius/md or radius/lg +cards: radius/2xl +icon containers: radius/xl (NOT radius/full unless avatar) +avatars (people): radius/full +brand avatars/logos: radius/lg (matches favicon convention) +modals: radius/3xl (top corners on mobile sheets) +``` + +Pick the conventions, document them, and stick to them. Inconsistent radius is one of the most common visual drift patterns. + +--- + +## Shadow tokens + +``` +shadow/none none +shadow/sm 0 1px 2px rgba(0,0,0,0.05) +shadow/md 0 4px 6px rgba(0,0,0,0.08) +shadow/lg 0 10px 15px rgba(0,0,0,0.10) +shadow/xl 0 20px 25px rgba(0,0,0,0.10) +shadow/2xl 0 25px 50px rgba(0,0,0,0.15) +``` + +### Shadow conventions + +``` +default cards: shadow/sm +hover state cards: shadow/md +elevated content: shadow/lg +modals/dropdowns: shadow/xl +``` + +--- + +## Z-index tokens + +A documented z-index scale prevents the "9999 wars." + +``` +z/below -1 +z/base 0 +z/raised 10 /* sticky elements, fixed nav */ +z/dropdown 20 /* popovers, dropdowns */ +z/overlay 30 /* page-level overlays, scrims */ +z/modal 40 /* modals, dialogs */ +z/toast 50 /* toasts, top-of-everything notifications */ +``` + +--- + +## Motion tokens + +``` +motion/duration-fast 100ms /* hover state, simple feedback */ +motion/duration-base 200ms /* most UI transitions */ +motion/duration-slow 300ms /* enter/exit animations */ +motion/duration-slower 500ms+ /* dramatic brand moments */ + +motion/ease-default cubic-bezier(0.4, 0, 0.2, 1) +motion/ease-in cubic-bezier(0.4, 0, 1, 1) +motion/ease-out cubic-bezier(0, 0, 0.2, 1) +motion/ease-bounce cubic-bezier(0.68, -0.55, 0.27, 1.55) +``` + +Always provide `prefers-reduced-motion` alternatives that disable or shorten animations for users who request it. + +--- + +## Breakpoints + +``` +breakpoint/sm 640px +breakpoint/md 768px +breakpoint/lg 1024px +breakpoint/xl 1280px +breakpoint/2xl 1536px +``` + +Test the design at viewport widths matching each breakpoint, and at 375px (smaller phone), 390px (default iPhone), and 1440px (default laptop). + +--- + +## How to use this template + +1. **Copy** the structure into your project. +2. **Fill in values** per the brand identity. +3. **Verify contrast** for every text/background combination using a contrast checker. +4. **Document edge cases** (e.g., the darker brand variant for text contexts). +5. **Reference everywhere.** No hardcoded values in components. +6. **Update once.** When tokens change, the whole product reflects the change. + +The token file is canonical. Anything in the codebase using a hardcoded value instead of a token is technical debt waiting to surface. diff --git a/skills/design-standards/references/preship-checklist.md b/skills/design-standards/references/preship-checklist.md new file mode 100644 index 0000000..14cd7fd --- /dev/null +++ b/skills/design-standards/references/preship-checklist.md @@ -0,0 +1,180 @@ +# Pre-Ship Design Checklist + +Run before declaring any page or component complete. Most production design defects come from skipping these. + +--- + +## Tokens and consistency + +- [ ] All colors come from the token set (no hardcoded hex values) +- [ ] All spacing comes from the spacing scale (no arbitrary px values) +- [ ] All typography uses defined type tokens +- [ ] All radii use the defined radius tokens +- [ ] Shadows use defined shadow tokens +- [ ] No more than one variant per component type (e.g., one primary button style across the page) + +--- + +## Contrast (WCAG AA) + +- [ ] All body text passes 4.5:1 against its background +- [ ] All large text passes 3:1 +- [ ] All UI elements (icons, borders, focus rings) pass 3:1 +- [ ] Brand colors used for text use the darker text variant if the signature color fails +- [ ] No light gray text under #6B7280 on white backgrounds +- [ ] Dark mode (if implemented) tested against dark surfaces, not just light + +Use a contrast checker for every pairing. Visual judgment is unreliable. + +--- + +## Visual hierarchy + +- [ ] One clear primary action per page (one primary CTA) +- [ ] Secondary actions visually subordinate to primary +- [ ] Headline larger and heavier than body text by enough to be unambiguous +- [ ] Section breaks visible without effort (spacing or background change) +- [ ] Images do not visually compete with primary content + +--- + +## Typography + +- [ ] Exactly one H1 per page +- [ ] No skipped header levels (H2 followed by H4) +- [ ] Body text minimum 14px (16px preferred) +- [ ] Line length controlled (45 to 75 characters per line for body text) +- [ ] Line height appropriate (1.4 to 1.6 for body, 1.0 to 1.2 for display) +- [ ] No fake italics or fake bold (use real font weights) + +--- + +## Spacing and rhythm + +- [ ] Consistent padding inside same-type containers (all cards, all sections) +- [ ] Section breathing room: 64px+ desktop, 48px+ mobile +- [ ] Form fields spaced minimum 16px apart vertically +- [ ] Related elements visually grouped (proximity principle) +- [ ] No cramped sections that bleed into each other + +--- + +## Buttons and CTAs + +- [ ] Primary button uses brand primary color +- [ ] Hover state visible and distinct +- [ ] Focus state visible (focus ring or equivalent) +- [ ] Disabled state visible and accessible +- [ ] Touch target minimum 44 by 44 pixels +- [ ] Button text descriptive (not "click here" or "submit") + +--- + +## Forms + +- [ ] Every input has a visible label (placeholder is not a label) +- [ ] Required fields marked clearly +- [ ] Error states have text descriptions, not just color +- [ ] Help text positioned below or beside the field, not as placeholder +- [ ] Input height accommodates touch (minimum 44px) +- [ ] Form inputs use 16px+ text on iOS to prevent zoom + +--- + +## Images and media + +- [ ] All meaningful images have descriptive alt text +- [ ] Decorative images have empty alt (`alt=""`) +- [ ] Images have explicit width and height to prevent layout shift +- [ ] Modern formats used where supported (WebP, AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] No images stretched or pixelated due to wrong sizing + +--- + +## Interactive elements + +- [ ] All interactive elements have hover states (where pointer is supported) +- [ ] Focus rings visible (do not use `outline: none` without a replacement) +- [ ] Tap targets minimum 44 by 44 pixels +- [ ] Tap targets at least 8 pixels of spacing on all sides from other tap targets +- [ ] Cursor styles correct (`pointer` for clickable, `text` for inputs, etc.) + +--- + +## Mobile (375 to 390 pixel viewport) + +- [ ] Tested on real device or device-mode in browser +- [ ] No horizontal scroll +- [ ] No fixed-width elements breaking layout +- [ ] Sticky bottom bars do not overlap content (page wrapper has bottom padding) +- [ ] Sticky top bars do not eat critical content +- [ ] Mobile menu works on touch +- [ ] All text remains readable (no truncated headlines) +- [ ] Tap targets remain 44px minimum + +--- + +## Tablet (768 to 1024 pixel viewport) + +- [ ] Layout transitions cleanly between mobile and desktop breakpoints +- [ ] No awkward in-between sizing +- [ ] Multi-column layouts adapt sensibly + +--- + +## Desktop (1280+ pixel viewport) + +- [ ] Page max-width prevents content from stretching too wide +- [ ] Typography does not break (line lengths still controlled) +- [ ] Whitespace remains balanced + +--- + +## Performance signals (visual) + +- [ ] No visible layout shift after initial render +- [ ] Images load progressively (no blank-then-pop) +- [ ] No flash of unstyled text (FOUT) for primary fonts +- [ ] No render-blocking elements above the fold + +(For deep performance audits, use `performance-optimization`.) + +--- + +## Brand and consistency + +- [ ] Logo placed correctly (per brand-style-guide rules) +- [ ] Brand colors used per brand-style-guide rules +- [ ] Imagery direction matches brand-style-guide +- [ ] Voice (in any UI text) matches brand-voice +- [ ] No off-brand stock photography or generic illustrations + +--- + +## Accessibility (basic checks; for deeper audits use `accessibility-audit`) + +- [ ] Page operable by keyboard alone +- [ ] Logical tab order +- [ ] Form fields have associated labels (`for`/`id` or `aria-labelledby`) +- [ ] Buttons and links use semantic elements (not `<div onClick>`) +- [ ] Skip links present for long pages +- [ ] Page language declared (`<html lang="...">`) + +--- + +## Pre-launch sanity + +- [ ] No placeholder text remaining ("Lorem ipsum," "TODO," "[Replace this]") +- [ ] No broken images +- [ ] No broken links (test 5 random links) +- [ ] No console errors in browser dev tools +- [ ] No accessibility errors in browser audit tools + +--- + +## Sign-off + +When all boxes check, the design is ready to ship. If any box fails, document the failure, decide whether it is a launch blocker, and either fix or file a known-issue ticket before shipping. + +The checklist is the floor, not the ceiling. Great design exceeds it. diff --git a/skills/design-standards/references/tailwind-patterns.md b/skills/design-standards/references/tailwind-patterns.md new file mode 100644 index 0000000..7b8b004 --- /dev/null +++ b/skills/design-standards/references/tailwind-patterns.md @@ -0,0 +1,287 @@ +# Tailwind Component Patterns + +Optional reference. Tailwind-specific component patterns for projects on that stack. The principles in [`SKILL.md`](../SKILL.md) are stack-agnostic; this file translates them into Tailwind utilities. + +If you are not using Tailwind, skip this file. The patterns translate to any utility framework or CSS approach with minor changes. + +--- + +## Page wrapper + +The standard container pattern: + +```jsx +<main className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> + {/* page content */} +</main> +``` + +Token equivalents: +- `max-w-7xl` = page max width (1280px) +- `mx-auto` = horizontal centering +- `px-4 sm:px-6 lg:px-8` = responsive horizontal padding + +For wider designs, swap `max-w-7xl` for `max-w-[1440px]`. + +--- + +## Section spacing + +```jsx +{/* Large section (heroes, major content) */} +<section className="py-20 md:py-28"> + +{/* Medium section (most content) */} +<section className="py-12 md:py-16"> + +{/* Small section (compact content) */} +<section className="py-8 md:py-12"> +``` + +Always include the mobile-first variant. Mobile sections use shorter padding to preserve viewport efficiency. + +--- + +## Dark hero + +```jsx +<section className="bg-gray-900 py-20 md:py-28"> + <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center"> + {/* Breadcrumb - text-gray-300 minimum on dark for AA */} + <nav className="text-sm text-gray-300 mb-6" aria-label="Breadcrumb"> + <a href="/" className="hover:text-white transition-colors">Home</a> + <span className="mx-2" aria-hidden="true">/</span> + <span className="text-white">Current Page</span> + </nav> + + {/* Eyebrow */} + <p className="text-xs font-semibold uppercase tracking-wider text-blue-400 mb-3"> + Section Label + </p> + + {/* H1 - exactly one per page */} + <h1 className="text-4xl md:text-6xl font-extrabold tracking-tight text-white mb-4"> + Main <span className="text-blue-400">Headline</span> + </h1> + + {/* Supporting */} + <p className="text-lg text-gray-300 max-w-2xl mx-auto"> + Supporting description that gives context. + </p> + </div> +</section> +``` + +Contrast notes: +- White on `bg-gray-900` = 17.4:1 PASS +- `text-gray-300` on `bg-gray-900` = 11.2:1 PASS AA +- `text-gray-400` on `bg-gray-900` = 7.6:1 PASS AA (still readable) +- `text-gray-500` on `bg-gray-900` = 5.5:1 PASS AA borderline; prefer 300 or 400 for body on dark + +--- + +## Feature card grid + +```jsx +<div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6"> + <div className="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm hover:shadow-md transition-shadow"> + {/* Icon container - rounded-xl, NOT rounded-full unless avatar */} + <div className="w-10 h-10 rounded-xl bg-blue-50 text-blue-600 flex items-center justify-center mb-4"> + <Icon className="w-5 h-5" /> + </div> + <h3 className="font-semibold text-gray-900 mb-2">Card Title</h3> + <p className="text-sm text-gray-600">Card description that explains the feature.</p> + </div> + {/* repeat */} +</div> +``` + +Conventions: +- `rounded-2xl` for cards (consistent radius across all cards on the site) +- `rounded-xl` for icon containers (not `rounded-full` unless it's an avatar) +- `text-gray-600` is the muted-text floor on white (passes AA at 7.6:1) + +--- + +## Data row (key-value display) + +```jsx +<div className="flex justify-between items-center rounded-xl bg-gray-50 px-4 py-3 text-sm"> + <span className="text-gray-600 font-medium">Label</span> + <span className="font-semibold text-gray-900">Value</span> +</div> +``` + +Stack rows in a `space-y-2` container for vertically grouped data. + +--- + +## Inline CTA banner + +```jsx +<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 rounded-xl border border-blue-100 bg-blue-50 px-5 py-4"> + <div> + <p className="font-semibold text-gray-900">CTA Headline</p> + <p className="text-sm text-gray-600 mt-0.5">Supporting context</p> + </div> + <a + href="#" + className="shrink-0 bg-blue-600 hover:bg-blue-700 text-white text-sm font-semibold px-4 py-2.5 rounded-full transition-colors whitespace-nowrap" + > + Action Text + </a> +</div> +``` + +The `flex-col sm:flex-row` pattern stacks on mobile, sits side-by-side on tablet+. Standard across all banner-style CTAs. + +--- + +## Author byline + +```jsx +<div className="flex items-center gap-3"> + {/* Brand/author avatar - rounded-lg matches favicon shape */} + <div className="w-9 h-9 rounded-lg bg-blue-600 flex items-center justify-center text-white text-sm font-bold flex-shrink-0"> + {authorInitial} + </div> + <div className="min-w-0"> + <a + href={`/author/${slug}`} + className="text-sm font-medium text-gray-900 hover:text-blue-700 transition-colors block truncate" + > + {authorName} + </a> + <p className="text-xs text-gray-600 truncate">{authorRole}</p> + </div> +</div> +``` + +Convention: brand and author identifiers use `rounded-lg`, not `rounded-full`. Reserve `rounded-full` for actual person photographs (people-photo avatars). + +--- + +## Buttons + +```jsx +{/* Primary - pill shape, brand color */} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold transition-colors"> + Primary Action +</a> + +{/* Secondary - outline */} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full border border-blue-600 text-blue-600 hover:bg-blue-50 font-semibold transition-colors"> + Secondary Action +</a> + +{/* Ghost - text only */} +<a className="inline-flex items-center gap-2 px-4 py-2 text-blue-600 hover:text-blue-700 font-semibold transition-colors"> + Ghost Action +</a> + +{/* Disabled state */} +<button + disabled + className="px-6 py-3 rounded-full bg-gray-200 text-gray-500 font-semibold cursor-not-allowed" +> + Disabled +</button> +``` + +Pick pill (`rounded-full`) or rounded-rect (`rounded-lg`) for buttons. Use one consistently across the entire site. + +--- + +## Form inputs + +```jsx +{/* Input with label */} +<div className="space-y-1.5"> + <label htmlFor="email" className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + id="email" + type="email" + className="w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-base shadow-sm focus:border-blue-600 focus:ring-2 focus:ring-blue-600/20 focus:outline-none" + placeholder="you@example.com" + /> + <p className="text-xs text-gray-600">We'll never share your email.</p> +</div> + +{/* Error state */} +<div className="space-y-1.5"> + <label className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + type="email" + aria-invalid="true" + aria-describedby="email-error" + className="w-full rounded-lg border border-red-500 px-3.5 py-2.5 text-base shadow-sm focus:border-red-600 focus:ring-2 focus:ring-red-600/20 focus:outline-none" + /> + <p id="email-error" className="text-xs text-red-600"> + Please enter a valid email address. + </p> +</div> +``` + +Notes: +- Always use `text-base` (16px) on inputs to prevent iOS zoom on focus +- `py-2.5` gives ~44px height with text, hitting the touch target minimum +- Error states need text, not just color (color blindness consideration) + +--- + +## Mobile sticky bar + +```jsx +<> + {/* Page wrapper needs bottom padding to compensate for the bar */} + <main className="pb-20 md:pb-0"> + {/* page content */} + </main> + + {/* Sticky bar - mobile only */} + <div className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-200 px-4 py-3 md:hidden z-30"> + <a + href="#" + className="block w-full text-center px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold" + > + Mobile CTA + </a> + </div> +</> +``` + +The `pb-20 md:pb-0` on the wrapper is critical. Without it, the sticky bar covers the bottom of the page content. + +--- + +## Common Tailwind contrast values + +Quick reference for which gray text colors pass AA on white: + +| Class | Hex | Contrast on white | AA pass | +|---|---|---|---| +| `text-gray-300` | #D1D5DB | 1.6:1 | FAIL (decorative only) | +| `text-gray-400` | #9CA3AF | 2.85:1 | FAIL | +| `text-gray-500` | #6B7280 | 4.6:1 | PASS (borderline; prefer 600) | +| `text-gray-600` | #4B5563 | 7.6:1 | PASS | +| `text-gray-700` | #374151 | 10.3:1 | PASS | +| `text-gray-800` | #1F2937 | 14.6:1 | PASS | +| `text-gray-900` | #111827 | 16.9:1 | PASS | + +Use `text-gray-600` as the floor for body text on white. Anything lighter requires verification against the specific background. + +For dark backgrounds: + +| Class | Hex | Contrast on `bg-gray-900` | AA pass | +|---|---|---|---| +| `text-white` | #FFFFFF | 17.4:1 | PASS | +| `text-gray-300` | #D1D5DB | 11.2:1 | PASS | +| `text-gray-400` | #9CA3AF | 7.6:1 | PASS | +| `text-gray-500` | #6B7280 | 5.5:1 | PASS borderline | +| `text-gray-600` | #4B5563 | 3.8:1 | FAIL for body | + +Use `text-gray-300` as the floor for body text on `bg-gray-900`. Reserve lighter grays for headlines and primary content. diff --git a/skills/design-system/SKILL.md b/skills/design-system/SKILL.md new file mode 100644 index 0000000..9ae0401 --- /dev/null +++ b/skills/design-system/SKILL.md @@ -0,0 +1,202 @@ +--- +name: design-system +description: "Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer." +category: design +catalog_summary: "Component library, design tokens, design system documentation" +display_order: 1 +--- + +# Design System + +Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer. + +This skill is for building the system. For applying a system to specific pages or components, use `design-standards`. For brand visual identity, use `brand-identity`. + +--- + +## When to use + +- Building a design system from scratch +- Auditing an existing system for gaps or fragmentation +- Defining design tokens at the system level +- Structuring a component library +- Establishing contribution and governance models +- Migrating from ad-hoc components to a documented system + +## When NOT to use + +- Designing a single page or component (use `design-standards`) +- Brand identity work (use `brand-identity`) +- Component-level frontend implementation (use `frontend-component-build`) +- Pure design documentation for marketing (use `brand-style-guide`) + +--- + +## Required inputs + +- The brand identity (tokens, voice, imagery direction) +- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools) +- The team and its working tools (Figma, code framework, doc platform) +- Existing components, even if undocumented +- Constraints (accessibility requirements, performance targets, browser support) + +If brand identity is undefined, run `brand-identity` first. + +--- + +## The framework: 5 layers + +A complete design system has five layers, stacked. Each layer feeds the layer above. + +### 1. Foundations (tokens) + +The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints. + +**Why this layer matters:** +- Tokens are the source of truth for everything above +- Token changes propagate everywhere automatically +- Without tokens, the system has no foundation + +**Output:** +- A documented token set (see `design-standards/references/design-tokens-template.md`) +- Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.) +- Token implementation in Figma (variables and styles) +- A primer doc explaining what tokens to use when + +**Common patterns:** +- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: `color-blue-600` (base) + `color-text-link` (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base. + +### 2. Elements (atoms) + +The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers. + +**Per element, document:** +- Visual variants (primary, secondary, ghost, etc.) +- Size variants (small, medium, large) +- States (default, hover, focus, active, disabled, error, loading) +- Anatomy (the parts that make up the element) +- Spacing and proportions +- Accessibility (keyboard support, screen reader behavior, ARIA) +- Code usage (props, examples) + +**Output:** +- Element library in Figma +- Element components in code +- Per-element documentation + +### 3. Components (molecules + organisms) + +Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers. + +**Per component:** +- Composition (which elements it uses) +- Variants and configurations +- Use cases (when to reach for this vs. an alternative) +- Layout behavior (responsive, contained, full-bleed) +- Anti-patterns (when NOT to use it) + +**Output:** +- Component library +- Per-component documentation with usage guidance + +### 4. Patterns (templates) + +Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections. + +**Per pattern:** +- The structure and components used +- The user journey it supports +- Layout grid and spacing +- Responsive behavior +- Variants (e.g., "with sidebar," "fullscreen," "modal") + +**Output:** +- Pattern library or page templates +- Documentation showing complete examples + +### 5. Documentation and governance + +How the system gets used, contributed to, and maintained. + +**Documentation includes:** +- Getting started guide for new team members +- How to use vs. how to extend +- Contribution model +- Versioning policy +- Migration paths when breaking changes happen +- Decision log for major system choices + +**Governance includes:** +- Who owns the system (a team or rotation) +- How new components get proposed and approved +- How conflicts get resolved +- How the system evolves vs. stays stable +- Cadence of review and updates + +--- + +## Workflow + +### For a new design system + +1. **Inventory the existing UI.** Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope. +2. **Identify the duplicates.** Same component built 5 different ways across the product. These are your high-value consolidation targets. +3. **Define foundations.** Token set, with both base and semantic layers. Document each. +4. **Audit elements.** From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set. +5. **Build the element library.** Figma + code. Document each element. +6. **Identify priority components.** The 10 to 15 components that appear most often. Build those first. +7. **Document patterns.** Page-level templates that show the system in use. +8. **Establish governance.** Owner, contribution model, review cadence. +9. **Roll out.** Migrate existing surfaces to the system progressively. + +### For an existing design system audit + +1. **Inventory what exists.** What's documented, what's in Figma, what's in code, what's actually used in production. +2. **Map gaps.** Where the system is incomplete. Where teams build outside the system because the system can't serve their need. +3. **Map fragmentation.** Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams). +4. **Identify decay.** Components that have drifted from the documented standard. +5. **Prioritize fixes.** Foundation gaps first. High-use component drift second. Rarely-used component cleanup last. +6. **Plan rollout.** Major changes need migration paths. + +--- + +## Failure patterns + +- **Building the system before the brand is set.** Tokens depend on brand. Set brand first. +- **Atoms-up extreme.** Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively. +- **One-person system.** A system without governance fails as soon as the original designer leaves. Establish ownership early. +- **Stale documentation.** A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs. +- **Versioning everything.** Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes. +- **Adopting "atomic design" dogmatically.** Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism. +- **Building in a vacuum.** A system designed without input from the teams using it gets ignored. Co-design with consumers. +- **No deprecation path.** Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly. +- **Token explosion.** Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have. + +--- + +## Output format + +A design system has multiple deliverables. Typically: + +- **Documentation site** (Notion, dedicated site, GitHub Pages, Storybook addon, etc.) +- **Figma library** (or equivalent design tool) +- **Code library** (npm package, monorepo workspace, copy-paste components) +- **Decision log** (system-level decisions and the reasoning) +- **Roadmap and changelog** + +For a design system audit, output is a markdown report at `design-system-audit.md`: + +1. Inventory of what exists (foundations, elements, components, patterns) +2. Gap analysis +3. Fragmentation analysis +4. Drift analysis +5. Prioritized remediation plan +6. Governance recommendations + +--- + +## Reference files + +- [`references/system-architecture.md`](references/system-architecture.md) - The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs. +- [`references/system-audit-template.md`](references/system-audit-template.md) - Template for auditing an existing design system. +- [`references/governance-playbook.md`](references/governance-playbook.md) - Contribution model, ownership, and decision process for an active system. diff --git a/skills/design-system/references/governance-playbook.md b/skills/design-system/references/governance-playbook.md new file mode 100644 index 0000000..8d72e3b --- /dev/null +++ b/skills/design-system/references/governance-playbook.md @@ -0,0 +1,303 @@ +# Design System Governance Playbook + +A design system without governance decays. This playbook covers the operating model: who owns it, how changes happen, and how the system stays alive. + +--- + +## Ownership models + +Three common models. Pick based on team size and maturity. + +### Model 1: Dedicated team + +A standing team owns the system full-time. 2 to 5 people typically: a lead designer, a lead engineer, and supporting roles. + +**Strengths:** +- Highest velocity for system improvements +- Clear ownership, fast decisions +- Can take on big system-level initiatives + +**Weaknesses:** +- Expensive +- Risk of disconnection from product teams +- Risk of building what the team finds interesting vs. what consumers need + +**When to use:** Organizations with 10+ designers and 50+ engineers, where system inconsistency is a real cost. + +### Model 2: Federated / contribution model + +System is maintained by multiple teams contributing changes. A small core team (or one lead) reviews contributions and maintains the foundation. + +**Strengths:** +- Distributed effort +- Component owners are the people closest to the use case +- Prevents the "system team builds for itself" problem + +**Weaknesses:** +- Coordination overhead +- Inconsistent velocity +- Requires strong contribution norms or quality drifts + +**When to use:** Mid-sized teams (5 to 15 designers, 20 to 100 engineers), where multiple teams need a shared system but no single team can dedicate full-time effort. + +### Model 3: Single owner / part-time + +One person owns the system as part of their broader role. Common in startups and small teams. + +**Strengths:** +- No coordination cost +- Decisions happen instantly +- Cheap + +**Weaknesses:** +- System decays when owner is busy +- Bus factor of one +- Hard to scale + +**When to use:** Early-stage teams. Plan to migrate to Model 1 or 2 as the team grows. + +--- + +## Contribution model + +How new components, variants, or changes get added to the system. + +### Stages + +1. **Proposal.** A team that needs a new component or variant proposes it. Proposal includes: the use case, examples in the wild, why existing components don't suffice. + +2. **Triage.** System owner(s) decide: + - **Accept:** add to the system. Assign owner. + - **Adapt existing:** existing component should grow to cover this use case. + - **Defer:** valid request but not prioritized now. + - **Reject:** doesn't fit the system. Solve in a one-off way. + +3. **Design.** Component is designed in the system's style. Includes all states, variants, and accessibility requirements. + +4. **Review.** System owner reviews against system standards. Iterate. + +5. **Build.** Component is built in code (and Figma if not built there first). + +6. **Document.** Usage doc, API doc, examples, anti-patterns. + +7. **Release.** Versioned release. Changelog entry. Announcement to consumers. + +### Proposal template + +```markdown +# Component Proposal: [Name] + +## Use case +[What we're building. The user problem this UI element solves.] + +## Examples in the wild +[3 to 5 places where teams have built ad-hoc versions of this. Screenshots.] + +## Why existing components don't fit +[Specific reasons existing components are insufficient.] + +## Proposed component +[Sketch or description of the proposed component, variants, states.] + +## Owner +[Who will design, build, and maintain this component.] + +## Timeline +[When this is needed. Hard deadlines vs. nice-to-have.] +``` + +--- + +## Decision-making + +### Type 1: Reversible decisions + +Most component-level decisions. Made by the component owner with light input from the system team. + +Examples: a new variant, a tweak to a state, an additional prop on an existing component. + +Process: lightweight. Propose in the team channel, get one or two reactions, ship. + +### Type 2: One-way doors + +Decisions that affect the foundation or ripple across many components. + +Examples: changing a base token, deprecating a component, changing the naming convention. + +Process: written proposal, formal review, broader stakeholder input, documented decision in the decision log. + +### Decision log + +Every Type 2 decision gets logged: + +```markdown +# DSDR-001: [Decision title] + +**Date:** YYYY-MM-DD +**Status:** [Proposed / Approved / Rejected / Implemented] +**Author:** [Name] + +## Context +[What situation led to this decision.] + +## Options considered +1. [Option] - pros, cons +2. [Option] - pros, cons +3. [Option] - pros, cons + +## Decision +[What was decided.] + +## Reasoning +[Why this option won.] + +## Consequences +[What changes as a result. What new constraints exist.] + +## Revisit when +[Trigger condition that would warrant reopening this decision.] +``` + +This log becomes the institutional memory. Future system owners can understand why things are the way they are. + +--- + +## Versioning + +### Semantic versioning + +For systems shipped as code packages, semver works well: + +- **Major (1.0.0 → 2.0.0):** breaking changes. API changes. Visual changes that consumers must adapt to. +- **Minor (1.0.0 → 1.1.0):** new components or variants. Backward-compatible. +- **Patch (1.0.0 → 1.0.1):** bug fixes. Backward-compatible. + +### Release cadence + +Three patterns: + +- **Continuous:** ship as ready. Best for teams that can absorb frequent updates. +- **Periodic:** weekly or biweekly batched releases. Best for systems with many consumers. +- **Major releases:** quarterly major versions, with weekly patches between. Best for systems with breaking changes that need migration time. + +### Communication + +For each release: +- Changelog entry (what changed, why) +- Migration guide for breaking changes +- Internal announcement (Slack, email, internal newsletter) +- Demo or office hours for major changes + +--- + +## Deprecation + +Components get retired. Manage retirement explicitly. + +### Deprecation stages + +1. **Warning.** Component is marked deprecated. Documentation gains a deprecation notice. Build emits a console warning. + +2. **Migration period.** Defined window (typically 1 to 2 quarters) for consumers to migrate. Migration guide published. + +3. **Removal.** Component removed. Code deleted. Documentation archived (not deleted, for historical reference). + +### Deprecation notice template + +```markdown +> ⚠️ Deprecated: [Component] is deprecated as of [version]. +> Replacement: [link to replacement component] +> Removal: scheduled for [version / date] +> Migration guide: [link] +``` + +--- + +## Quality bar + +Every component or change must meet the bar before merging. + +### Functional +- [ ] Works at the documented breakpoints +- [ ] All variants and states implemented +- [ ] Keyboard navigation works +- [ ] Screen reader announces correctly +- [ ] Focus indicators visible +- [ ] Touch targets at least 44px +- [ ] Color contrast passes AA + +### Documentation +- [ ] Usage doc (when to use, when not to) +- [ ] API doc (props, types, defaults) +- [ ] Examples (basic, advanced, edge cases) +- [ ] Anti-patterns (what to avoid) + +### Consistency +- [ ] Uses tokens (no hardcoded values) +- [ ] Follows naming conventions +- [ ] Visual style matches the system +- [ ] Behavior matches similar components + +### Test +- [ ] Unit tests for component logic +- [ ] Visual regression test +- [ ] Accessibility test + +--- + +## Metrics + +Track the health of the system. + +### Adoption + +- Percentage of product UI built from system components vs. one-offs +- Per-team adoption rate +- Component usage frequency + +### Velocity + +- Time from proposal to release +- Number of accepted contributions per month +- Open proposals in queue + +### Quality + +- Open bugs against system components +- Accessibility issues count +- Drift incidents (components used in unsupported ways) + +### Consumer satisfaction + +- Internal survey: how useful is the system? +- What's missing? What blocks adoption? + +Run satisfaction survey at least annually. Use results to guide system priorities. + +--- + +## Sustaining the system + +A design system is a living thing. Without maintenance, it dies. + +### Weekly +- Triage incoming proposals +- Review consumer questions and feedback +- Address bugs + +### Monthly +- Release notes for any changes +- Office hours for consumer teams +- Component audit (one or two components reviewed in depth) + +### Quarterly +- Roadmap review +- Foundation review (token health, naming consistency) +- Adoption metrics review + +### Annually +- Strategic review (is the system serving its purpose?) +- Consumer satisfaction survey +- Major version planning + +The system is never finished. It evolves with the product, the team, and the brand. diff --git a/skills/design-system/references/system-architecture.md b/skills/design-system/references/system-architecture.md new file mode 100644 index 0000000..113081c --- /dev/null +++ b/skills/design-system/references/system-architecture.md @@ -0,0 +1,275 @@ +# System Architecture + +How the four layers of a design system relate, and how to decide where new things belong. + +--- + +## The four layers, top to bottom + +``` +┌──────────────────────────────────────────────────────────────┐ +│ TEMPLATES (full screens, complete flows) │ +│ Optional layer. Use when the same screen pattern recurs. │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PATTERNS (composed components solving a UI problem) │ +│ Examples: form layouts, modal dialogs, navigation, tables │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PRIMITIVES (smallest reusable elements) │ +│ Examples: button, input, checkbox, badge, icon, link │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ TOKENS (atomic named values) │ +│ Examples: color-text-primary, space-md, radius-card │ +└──────────────────────────────────────────────────────────────┘ +``` + +Higher layers consume lower layers. A primitive uses tokens. A pattern composes primitives (and tokens). A template assembles patterns. + +A token never references a primitive. A primitive never references a pattern. The dependency direction is one-way. + +--- + +## When to add at each layer + +### Add a token when: +- A value appears in 3+ places +- The value has a clear semantic purpose +- Changing the value should propagate everywhere it appears + +**Example:** "Card border radius" - if 12 components use 12px corner radius, that's a token. + +**Counter-example:** A one-off radius for a single decorative element. Hard-code it. + +### Add a primitive when: +- The same combination of HTML/JSX/View elements recurs in 3+ places +- The element has an internal state machine (open/closed, default/hover/disabled) +- Centralized accessibility logic helps consumers + +**Example:** Button. Recurs everywhere. Has states. Accessibility (focus, keyboard, ARIA) is non-trivial. + +**Counter-example:** A specific marketing hero block that only appears on the homepage. Not a primitive. Build it inline. + +### Add a pattern when: +- Multiple teams keep building the same composition +- The composition involves non-obvious decisions (z-index, focus management, scroll behavior, animation) +- A central pattern reduces accessibility risk + +**Example:** Modal dialog. Hard to get right (focus trap, escape, scroll lock). Pattern centralizes the hard parts. + +**Counter-example:** A specific dashboard layout used only on the analytics page. Not a pattern. Build it inline as a screen. + +### Add a template when: +- A full screen recurs across products or sections +- New product features want a starting point that already follows system rules + +**Example:** Settings page layout (left nav, content area, save bar). If the team builds 5 settings sections, the template saves time. + +**Counter-example:** A unique landing page. Not a template. + +--- + +## Decision tree: where does this belong? + +``` +Is it a value? ────── Yes ────── Token + │ + └── No + +Is it a single element? ── Yes ── Primitive + │ + └── No + +Is it composed of primitives? ─ Yes ─ Pattern + │ + └── No + +Is it a full screen? ──────── Yes ── Template +``` + +--- + +## Token tiering + +Most systems benefit from at least two tiers. Three is the maximum without diminishing returns. + +### Tier 1: Primitives + +Raw values, no semantic meaning attached. + +``` +color-blue-50 = #EFF6FF +color-blue-100 = #DBEAFE +color-blue-500 = #3B82F6 +color-blue-900 = #1E3A8A + +space-1 = 4px +space-2 = 8px +space-4 = 16px +space-8 = 32px + +radius-sm = 4px +radius-md = 8px +radius-lg = 12px +``` + +### Tier 2: Semantic + +Purpose-named, mapped to primitives. + +``` +color-text-primary = color-gray-900 +color-text-secondary = color-gray-600 +color-text-link = color-blue-700 +color-bg-surface = color-white +color-bg-elevated = color-white +color-border-default = color-gray-200 + +space-stack-tight = space-2 +space-stack-default = space-4 +space-stack-loose = space-6 +``` + +### Tier 3 (optional): Component-specific + +Component-tied, mapped to semantic tokens. + +``` +button-padding-x = space-stack-default +button-padding-y = space-stack-tight +button-radius = radius-md +button-bg-primary = color-bg-action-primary +``` + +**Rule of thumb:** Stop at Tier 2 unless the system is large enough to justify Tier 3 maintenance. Tier 3 adds clarity but multiplies token count. + +--- + +## Naming conventions + +Pick one and stay. The most common patterns: + +### Pattern A: Hierarchical with hyphens +``` +color-text-primary +color-text-secondary +color-bg-surface +space-stack-md +``` + +### Pattern B: Object/dot notation (often in JSON or JS) +``` +color.text.primary +color.bg.surface +space.stack.md +``` + +### Pattern C: Flat with prefix +``` +text-color-primary +bg-color-surface +stack-space-md +``` + +Hierarchical-with-hyphens (Pattern A) is the most common for CSS variable contexts. Pick once, document, never deviate. + +--- + +## Naming for the semantic layer + +Names should describe purpose, not appearance. "Color is what it is, name is what it does." + +**Good:** +- `color-text-primary` (what role does it play?) +- `color-bg-action-destructive` (what action is this for?) +- `space-stack-section` (where does it apply?) + +**Bad:** +- `color-blue-medium` (semantic name should not encode the value; that's the primitive layer's job) +- `color-pretty-blue` (subjective, not purpose) +- `color-button-text` (OK at component layer; too specific for semantic layer) + +--- + +## Versioning + +Use semantic versioning: `major.minor.patch`. + +- **Patch:** Bug fixes, no API changes. Bump for any defect fix. +- **Minor:** Additive changes. New tokens, new components, non-breaking API additions. +- **Major:** Breaking changes. Removed tokens, renamed APIs, behavioral changes consumers must adapt to. + +For breaking changes, provide: + +1. Deprecation warning in the previous minor version +2. Migration guide +3. Codemod or scripted migration path where possible +4. A timeline for sunset (typically 1 to 2 quarters) + +--- + +## Anti-patterns + +### Color sprawl +- 200 named colors instead of a tight palette of 30 to 50. +- Symptom: every designer adds the color they need. +- Fix: enforce primitive layer review before new colors land. + +### Spacing chaos +- 17 different spacing values, half of them within 2px of each other. +- Symptom: each design uses unconstrained spacing. +- Fix: a defined scale. New spacing values require a real reason. + +### Naming inconsistency +- `colorPrimary`, `color-primary`, `primary-color`, `primaryColor` all in the same system. +- Symptom: tokens added by different people without convention. +- Fix: pick one convention, document, automate validation. + +### Tokens without consumers +- 200 tokens defined, 50 actually used. +- Symptom: aspirational tokens added "for the future." +- Fix: only add tokens with current or near-future consumers. + +### Components without docs +- 30 components in the library, 5 have docs. +- Symptom: docs treated as separate work, deprioritized. +- Fix: docs blocking the merge of new components. + +### Patterns over-built +- A "DataTable" pattern with 47 props supporting every imaginable variation. +- Symptom: Trying to anticipate every use. +- Fix: ship narrow first. Expand based on real demand. Hard to remove options once shipped; easy to add. + +--- + +## Dependency directions + +A healthy system has these dependency rules: + +- Tokens depend on nothing. +- Primitives depend on tokens. +- Patterns depend on primitives and tokens. +- Templates depend on patterns, primitives, and tokens. +- Application code depends on any layer. + +Violations to flag: + +- A token referencing another token at a different tier (sometimes OK, often a smell). +- A primitive referencing a pattern. Wrong direction. +- A pattern not using primitives, building from raw HTML. Bypasses the system. +- Application code defining its own colors instead of using tokens. Bypasses the system. + +--- + +## How to introduce a system to an existing codebase + +If the codebase has no system today: + +1. **Audit.** Inventory existing UI. Find duplicates and inconsistencies. +2. **Tokens first.** Establish the token foundation. Migrate hard-coded values gradually. +3. **Primitives second.** Replace ad-hoc components with system primitives. Highest-impact ones first (button, input, modal). +4. **Patterns third.** Once primitives are established, codify patterns. +5. **Migrate over multiple quarters.** Rip-and-replace fails. Coexistence with gradual migration succeeds. + +Plan for the system to take 2 to 4 quarters to fully replace ad-hoc UI in a medium-sized product. Plan for it to never be "done" - it evolves with the product. diff --git a/skills/design-system/references/system-audit-template.md b/skills/design-system/references/system-audit-template.md new file mode 100644 index 0000000..625f9f5 --- /dev/null +++ b/skills/design-system/references/system-audit-template.md @@ -0,0 +1,258 @@ +# Design System Audit Template + +A template for auditing an existing design system. Use this to take stock of what exists, what is missing, what is duplicated, and what is silently broken. + +The output is an honest report, not a grade. The goal is a backlog the team can act on. + +--- + +## When to use this template + +- Before a major redesign or rebrand (knowing the starting state shapes the plan). +- When the system feels heavy or inconsistent and no one can articulate why. +- When a new owner takes over and needs ground truth. +- Quarterly, as a regular health check. + +--- + +## Audit scope + +Decide upfront what is in and out of scope. A full audit covers all four layers (tokens, primitives, patterns, templates) plus governance and adoption. A focused audit covers one or two. + +| Layer / area | In scope | Out of scope | +|---|---|---| +| Tokens | | | +| Primitives | | | +| Patterns | | | +| Templates | | | +| Documentation | | | +| Governance | | | +| Adoption | | | + +--- + +## Layer 1: Tokens + +### Inventory + +List every token category in the system. For each, count, source of truth, and platforms supported. + +| Category | Count | Source of truth | Platforms supported | +|---|---|---|---| +| Color | | | | +| Typography (font, size, weight, line-height) | | | | +| Spacing | | | | +| Radius | | | | +| Shadow | | | | +| Motion (duration, easing) | | | | +| Z-index | | | | +| Breakpoints | | | | +| Other | | | | + +### Findings + +- [ ] Are tokens named by role (`color-text-primary`) or by value (`gray-900`)? Role-based scales better. +- [ ] Is there a single source of truth (one file, one tool) or multiple sources that drift? +- [ ] Are tokens versioned? How are breaking token changes communicated? +- [ ] Are there duplicate tokens (`color-blue-primary` and `color-action`)? List them. +- [ ] Are there orphan tokens (defined but unused)? List them. +- [ ] Are dark mode / theme variants modeled at the token layer or elsewhere? + +### Token risks + +- **Hardcoded values in code:** grep the codebase for raw hex, raw px values, raw font sizes. Note where tokens were skipped. +- **Token sprawl:** more than 20 named colors, more than 8 spacing values, or more than 6 font sizes is usually a smell. +- **Naming inconsistency:** `color-text` vs `text-color` vs `textColor` across categories. + +--- + +## Layer 2: Primitives + +### Inventory + +List every primitive component the system ships. For each, status and consumer count. + +| Primitive | Status (Production / Beta / Deprecated) | Consumers (rough count) | Notes | +|---|---|---|---| +| Button | | | | +| Input | | | | +| Checkbox | | | | +| Radio | | | | +| Select | | | | +| Textarea | | | | +| Badge | | | | +| Avatar | | | | +| Icon | | | | +| Link | | | | +| (etc.) | | | | + +### Findings + +- [ ] Are primitives accessible (keyboard, screen reader, focus management)? List failures. +- [ ] Are all primitives token-driven, or do some hardcode values? +- [ ] Are there duplicate primitives that do almost the same thing (`Button` and `IconButton` and `LinkButton`)? Could they consolidate? +- [ ] Are primitives documented (props, states, variants, accessibility)? +- [ ] Are there one-off primitives in product code that should be promoted to the system? + +--- + +## Layer 3: Patterns + +Patterns are composed components solving a specific UI problem. + +### Inventory + +| Pattern | Status | Used by (rough page or feature count) | Notes | +|---|---|---|---| +| Form layout | | | | +| Modal dialog | | | | +| Toast / notification | | | | +| Navigation (top, side) | | | | +| Empty state | | | | +| Pagination | | | | +| Data table | | | | +| Card | | | | +| (etc.) | | | | + +### Findings + +- [ ] Are patterns built from primitives, or do they reach around the primitives layer? +- [ ] Do multiple patterns solve the same problem with different APIs? +- [ ] Are patterns flexible enough for real product needs, or are teams forking them? + +--- + +## Layer 4: Templates + +Templates are full screens or flows. Optional layer. + +### Inventory + +| Template | Status | Used by | Notes | +|---|---|---|---| +| Marketing landing | | | | +| App shell | | | | +| Settings page | | | | +| Onboarding flow | | | | +| Empty product state | | | | +| (etc.) | | | | + +### Findings + +- [ ] Do templates exist at all? Many systems skip this layer. +- [ ] Are templates a starting scaffold or a rigid spec? +- [ ] Are template layouts responsive, or do teams reimplement responsive behavior each time? + +--- + +## Documentation + +### Inventory + +- **Documentation site:** [URL or "none"] +- **Last meaningful update:** [Date] +- **Component coverage:** [What % of shipped components are documented?] +- **Code examples for every component:** [Yes / partial / no] +- **Accessibility notes for every interactive component:** [Yes / partial / no] +- **Migration / changelog:** [Yes / no] + +### Findings + +- [ ] Is the documentation in sync with the shipped code, or has it drifted? +- [ ] Can a new engineer onboard from the docs alone, or do they need tribal knowledge? +- [ ] Is there a "do / do not" pattern with examples for each component? +- [ ] Are deprecated components clearly marked, with a migration path? + +--- + +## Governance + +- **Ownership model:** [Dedicated team / federated / single owner / unowned] +- **Contribution process:** [Documented / informal / nonexistent] +- **Review cadence:** [How often do owners look at incoming requests, bugs, drift?] +- **Decision log:** [Where are major design system decisions recorded? Or are they not?] +- **Communication channel:** [Slack channel / mailing list / standing meeting / none] + +### Findings + +- [ ] Who decides when a new component enters the system? +- [ ] Who decides when a component is deprecated? +- [ ] Who handles requests from product teams? What is the SLA? +- [ ] What happens when a product team needs something the system does not provide? + +--- + +## Adoption + +### Measurement + +| Measure | Today | Target | +|---|---|---| +| % of UI built with system components | | | +| % of new features using system | | | +| Number of one-off components in product code | | | +| Number of token overrides in product code | | | +| Number of open issues against the system | | | + +### Findings + +- [ ] Where is adoption strongest? Why? +- [ ] Where is adoption weakest? Why? (Often: missing components, too rigid, undocumented, or onboarding gap.) +- [ ] Are there teams actively forking or working around the system? + +--- + +## Risk register + +List the top 5 risks the audit surfaced. For each: severity (high / medium / low), affected area, and a one-line recommendation. + +| # | Risk | Severity | Affected area | Recommendation | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | +| 3 | | | | | +| 4 | | | | | +| 5 | | | | | + +--- + +## Backlog + +Translate findings into a prioritized backlog. Keep items concrete and assignable. + +### Critical (block adoption or accessibility) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### High (consistent friction or duplication) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Medium (improvement, not blocking) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Low (polish) + +- [ ] [Item, owner, target date] + +--- + +## Audit summary + +Three sentences. What is the overall state, what is the single most important thing to fix, and what should the team start now. + +> [State summary] +> [Most important fix] +> [Start now] + +--- + +## Sign-off + +Audit conducted by: [Name(s), date] +Reviewed with: [Stakeholders] +Next audit scheduled: [Date] diff --git a/skills/discovery-research-synthesis/SKILL.md b/skills/discovery-research-synthesis/SKILL.md new file mode 100644 index 0000000..be007e8 --- /dev/null +++ b/skills/discovery-research-synthesis/SKILL.md @@ -0,0 +1,265 @@ +--- +name: discovery-research-synthesis +description: "Turning research artifacts into actionable PM insight. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the decisions they are meant to inform. The discipline of moving from raw discovery data to clear product direction without losing signal in the synthesis or fabricating insight that was not actually there. Triggers on research synthesis, customer interview synthesis, user research analysis, discovery readout, research insights, sales call analysis, support ticket analysis, qualitative data analysis. Also triggers when a team has done research but cannot turn it into decisions, when synthesis is producing pretty decks but no roadmap movement, or when an upcoming PM decision needs to be grounded in research already conducted." +category: research +catalog_summary: "Synthesizing customer interviews, research notes, and support tickets into actionable PM decisions. Distinguishes data-dump (no synthesis) from insight-theater (overpolished narrative) from actionable synthesis (decision-grade clarity)" +display_order: 4 +--- + +# Discovery Research Synthesis + +A senior PM's playbook for turning research artifacts into decisions. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the product direction they are meant to inform. + +Most discovery research never produces decisions. The team conducts interviews; the transcripts pile up; a researcher hands product the raw artifacts (data-dump) or builds a polished readout deck (insight-theater); the deck gets a 30-minute review meeting and is never referenced again. Two months later the team is making the same product decisions that the research was supposed to inform, with the same gut-feel inputs the research was supposed to displace. + +The discipline is in the synthesis. Synthesis is where research earns its keep: where transcripts become tagged observations, observations cluster into patterns, patterns get named, named patterns surface product implications, and implications drive specific decisions. Without that sequence, research is performance art. + +This skill covers one-off discovery research projects: a 12-week customer development sprint, a sales-call review for an onboarding redesign, a support-ticket audit informing a roadmap quarter. Different from `user-feedback-aggregation`, which covers ongoing feedback streams; different from `jtbd-framing`, which is a specific framing technique often applied within synthesis but narrower in scope. + +The voice is the senior PM or staff product researcher who has run synthesis well and seen plenty of teams fail at it. Honest about where polish becomes performance and where pattern-naming slides into pattern-fabrication. + +When to use this skill: synthesizing a recent batch of customer interviews, auditing why prior research has not produced product decisions, designing the synthesis output for a multi-week discovery sprint, or establishing the synthesis discipline a team currently lacks. + +--- + +## What this skill is for + +This skill spans research-to-decision synthesis. The PM-skill distinction: + +- **`discovery-research-synthesis` (this skill)** is one-off research synthesis: turning a discrete batch of artifacts into a discrete set of decisions. +- `user-feedback-aggregation` is ongoing feedback streams: continuous synthesis across always-on channels (support, NPS, in-app, sales). +- `jtbd-framing` is a framing technique often applied during synthesis; this skill is broader. +- `pm-spec-writing` is downstream: specs use synthesized insights as input. +- `roadmap-planning` is downstream: roadmap uses synthesized priorities as input. +- `experiment-design` is the quantitative-validation discipline that often follows qualitative synthesis. + +The audience: senior PMs, product directors, in-house product teams, agencies running discovery work for clients, researchers handing off to product teams. + +What is not in scope: conducting the research itself (interview design, recruiting, moderation), the broader discovery strategy that decides which research to commission, or the long-running feedback channels that user-feedback-aggregation covers. + +--- + +## Data-dump vs insight-theater vs actionable-synthesis + +The keystone framing. Two failure modes plus the discipline. + +**Data-dump.** Research artifacts handed to the product team raw. "Here are 47 transcripts and a spreadsheet of tags; figure it out." No synthesis, no signal-finding, no implications drawn. The product team either does the synthesis itself (often badly, often months later) or skips it (the most common outcome). Output: a research investment that produced artifacts but not insight. + +**Insight-theater.** Overpolished synthesis dressed as insight. Pretty quote walls, designed personas, branded readout decks, no decision-driving conclusions. The research deck that gets a 30-minute review and never gets referenced. Synthesis that performed for the executive audience but did not inform the product audience. Cost: real research budget converted into a slide deck; the organization "did the research" without doing the research. + +**Actionable-synthesis.** Synthesis that drives decisions. Each pattern has a "so what" attached; each finding leads to a product implication; the document gets referenced in roadmap discussions, spec drafts, prioritization debates. The synthesis is short, opinionated, and load-bearing. Six months later, team members can quote the patterns that shaped what shipped and what got cut. + +The litmus test. Three months after a synthesis ships, can team members name the decisions the synthesis informed? If yes, the synthesis was actionable. If team members remember the deck but cannot name the decisions, it was insight-theater. If nobody remembers anything because the synthesis never happened, it was data-dump. + +--- + +## Discovery research types + +Five common research types, each with different artifacts and synthesis needs. + +**Customer interviews.** 30-90 minute structured or semi-structured conversations. Transcripts plus moderator notes plus recordings. Highest-quality qualitative data; most expensive to collect; most rewarding to synthesize when done well. Typical batch: 8-15 interviews per discovery cycle. + +**Support ticket reviews.** Auditing recent support tickets for patterns. Lower per-artifact richness than interviews; higher volume; surfaces the friction users actually hit (not just what they say in interviews). Typical batch: 100-500 tickets per audit. + +**Sales call analysis.** Recording or transcript review of recent sales calls. Surfaces objections, pricing-conversation patterns, competitive mentions, and the gap between marketing positioning and what sales actually leads with. Typical batch: 15-30 calls per audit. + +**Survey data.** Quantitative responses with optional qualitative comments. Best for validating qualitative patterns at scale; weak as primary discovery (surveys reveal what users say, not what they do). Typical batch: 100-2,000 responses. + +**In-app feedback.** Users submitting feedback through in-product channels. Volume is high; quality varies; signal lives in patterns across many low-effort submissions. Typical batch: ongoing; synthesized in periodic audits. + +Different research types compose. A discovery cycle often pairs interviews (depth) with support ticket review (volume) with survey data (validation at scale). The synthesis combines them. + +Detail in [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md). + +--- + +## The synthesis sequence + +Six stages from raw artifacts to decisions. Skipping stages is where synthesis fails. + +**1. Transcribe and prepare.** Convert artifacts into a synthesizable format. Interview recordings to transcripts; sales calls to summaries; support tickets to a tagged dataset. The prep work is unglamorous; teams that skip it never reach the later stages. + +**2. Tag at the artifact level.** Read each transcript or ticket and tag it with the topics, problems, and quotes that surface. First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. Tags are messy; that is fine. + +**3. Cluster across artifacts.** Group tags into themes. Multiple users mentioned the same friction; multiple tickets reference the same workflow; multiple interviews returned to the same struggling moment. The clusters surface the patterns. + +**4. Name patterns.** Each cluster becomes a named pattern. The naming is the work: a pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references. "Onboarding configuration friction" is a pattern name; "users had trouble" is not. + +**5. Infer product implications.** For each pattern, what does this imply for the product? Implications are the bridge from observation to decision. A pattern without an implication is a finding; a pattern with an implication is actionable input. + +**6. Name the so-what.** For each implication, the specific decision it informs. "Should we prioritize the onboarding redesign in Q2?" The so-what is what makes the synthesis decision-grade. + +The sequence is non-negotiable. Teams that skip tagging and jump to pattern naming hallucinate patterns; teams that skip implications produce findings without product direction; teams that skip so-what produce documentation, not synthesis. + +Detail in [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md). + +--- + +## Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. + +**Tag at the artifact level first; do not pre-design the taxonomy.** Tags emerge from the artifacts. Teams that arrive with a pre-built tag taxonomy ("we will tag for usability, performance, pricing, support") force artifacts into categories that may not fit the data, and miss patterns the taxonomy did not anticipate. + +**Allow tag proliferation; collapse later.** Early tagging may produce 80-150 tags across a batch. That is correct. The clustering stage collapses them. Premature consolidation ("we had 4 onboarding tags; let me merge them") loses distinctions that turn out to matter. + +**Cluster on patterns, not on tag overlap.** Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation: are these the same struggling moment, or do they share a tag because the tag was loose? + +**Name the cluster after clustering, not before.** The cluster name comes from the data, not from a hypothesis. Teams that arrive with named clusters and slot data into them produce confirmation; teams that name clusters from the data produce discovery. + +**Tag dissent and contradictions explicitly.** Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. Tag the dissent so the synthesis can address it. + +Detail in [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md). + +--- + +## Pattern naming + +The work that distinguishes synthesis from documentation. + +**A pattern name is not a category label.** "Onboarding" is a category. "Users abandon configuration before reaching the success state because the third configuration step requires data they do not have on hand" is a pattern. The pattern names the specific behavior the data reveals. + +**The name should make the implication legible.** A reader who sees only the pattern name should be able to guess the product implication. If the name is too abstract, the reader cannot reach the implication; if the name is too concrete, the synthesis becomes a list of micro-observations. + +**Avoid category bloat.** Synthesis with 30 named patterns is usually under-clustered: many of those patterns are variations on a smaller number of underlying patterns. Synthesis with 4 named patterns is often the right number; 6-8 is common; more than 12 is usually category bloat. + +**Avoid naming the obvious.** "Users want fast performance" is not a pattern; it is a truism. A pattern is a specific observation that the product team did not already know. If the pattern name reads as something everyone could have said before the research, the pattern is not a pattern. + +**Name with conviction.** Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly; they invite challenge and produce decisions. + +Detail in [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md). + +--- + +## From pattern to product implication + +The bridge from observation to decision. + +**Pattern-to-implication is the writer's analytical work, not what the user said.** Users do not state product implications; they describe their experience. The PM doing synthesis interprets the pattern and proposes the implication. The interpretation is where synthesis adds value beyond transcription. + +**Each pattern can have multiple implications.** A pattern about onboarding friction might imply a redesign of the configuration flow, or default-data pre-population, or staged onboarding. The synthesis surfaces the options; the prioritization decision picks one. + +**Implications should be falsifiable.** A vague implication ("we should improve onboarding") is not actionable. A specific implication ("staged onboarding that defers the third configuration step until after the user reaches the first success state") is. Specific implications can be debated, scoped, prioritized. + +**Implications should acknowledge cost.** Patterns suggest solutions; solutions cost product capacity. Synthesis that implies 30 product changes without acknowledging that delivering them all is impossible is not synthesis; it is a wishlist. + +**Some patterns imply not-acting.** Sometimes the pattern reveals friction the team should not address: it affects too few users, it represents segment misfit, addressing it would compromise other priorities. Naming the not-act implication is honest synthesis. + +Detail in [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md). + +--- + +## Writing for decisions, not deck performance + +Synthesis output should be optimized for decision use, not for presentation. + +**Document, not deck.** Deck format is poor for synthesis: slides cannot carry argument density; readers cannot reference slides later; decks decay into icons and bullet points. A short document (4-12 pages) carries more usable synthesis than a 60-slide deck. + +**Lead with patterns and implications; relegate evidence to appendix.** A reader scanning for decision input wants the patterns and implications first. Evidence (quotes, ticket excerpts, data tables) supports the patterns but does not lead. Decks that lead with quote walls have inverted the reader's needs. + +**One section per pattern.** Each pattern gets a short section: pattern name, evidence summary (2-3 sentences with link to full evidence in appendix), implication, so-what decision input. + +**Be opinionated.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. Synthesis that commits positions invites challenge and produces decisions. The PM doing synthesis is making a recommendation; readers can disagree, but disagreement is the point. + +**Include a decision-input section.** What does this synthesis recommend the team do? Where should priorities shift? Which roadmap items does this validate, which does it challenge? The decision-input section is the synthesis's reason for existing. + +Detail in [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md). + +--- + +## The synthesis review and validation loop + +How the synthesis gets pressure-tested before it drives decisions. + +**Internal review with the research participants where possible.** Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? Misrecognition signals the synthesis fabricated patterns or projected interpretations the data did not support. + +**Adjacent-team review.** Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? Adjacent teams catch synthesis errors that the research team missed. + +**Quantitative validation where possible.** Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. The pattern says X; does the data confirm X happens at the frequency and severity the pattern implies? See `experiment-design` and `product-analytics-setup` for the quantitative methodology. + +**The "challenge the synthesis" session.** A specific session where adjacent teams try to find the patterns the synthesis missed, the implications the synthesis overstated, the decisions the synthesis is railroading. Productive disagreement strengthens the synthesis. + +**Iterate before publishing.** Synthesis goes through revision based on the review loop. Synthesis that ships in the first draft state usually carries unacknowledged blind spots. + +Detail in [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md). + +--- + +## When to halt and gather more data + +Synthesis sometimes reveals that the research did not collect enough. + +**Pattern thinness.** A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. Either name the pattern as tentative pending more data, or pause synthesis and gather more research. + +**Segment under-representation.** The research overrepresents one user segment and underrepresents another that matters for the decision. Patterns from the represented segment may not apply to the underrepresented one. + +**Contradictory clusters.** Two clusters point in opposite directions and the data does not resolve the contradiction. Often signals a sub-segment difference that the research did not investigate enough. + +**Decision time pressure.** Synthesis revealing data gaps but the decision has to ship before more research can happen. Honest path: name the data gap explicitly in the synthesis, make the recommendation with the gap acknowledged, plan the follow-up research that would validate or revise. + +**The "we have enough" trap.** Teams that have invested in research often want to declare the data sufficient even when the synthesis reveals gaps. The discipline is naming gaps even when uncomfortable. + +Detail in [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md). + +- "We did the research but never made decisions from it." Data-dump or insight-theater; synthesis sequence skipped or stopped at findings. +- "Our synthesis deck got a polite review and was never referenced again." Insight-theater; output was performative rather than load-bearing. +- "We have 30 named patterns and no clear priorities." Category bloat; under-clustering; cure: re-cluster to 4-8 underlying patterns. +- "Every pattern reads as something we already knew." The synthesis named truisms, not patterns. Re-examine the data for what was actually surprising. +- "The patterns contradict each other and we cannot reconcile them." Often segment misfit; consider whether the contradictions reveal sub-segments with different needs. +- "Research participants did not recognize themselves in our synthesis." Synthesis fabricated patterns or projected interpretations not in the data. Restart with closer evidence-tracking. +- "The synthesis is detailed but the team cannot tell what to do." Implications missing or vague; cure: each pattern gets a specific falsifiable implication. +- "We hedged every pattern and the synthesis reads as wishy-washy." Hedge stacking; the synthesis avoided commitment. Rewrite with conviction. +- "Our quote walls were impressive but the deck was 60 slides." Insight-theater; cure: 8-page document with quotes in appendix. +- "The synthesis recommended 20 product changes; we shipped one." Wishlist synthesis; did not acknowledge cost; cure: prioritize within the synthesis. +- "Adjacent teams disagreed with our patterns and we did not engage." Review loop skipped; cure: make adjacent-team review non-negotiable before shipping. + +--- + +## The framework: 12 considerations for discovery synthesis + +When designing or auditing a synthesis output, walk these 12 considerations. + +1. **Actionable-synthesis, not data-dump or insight-theater.** Synthesis that drives decisions. +2. **Research types matched to questions.** Interviews, support, sales calls, surveys, in-app combined deliberately. +3. **The synthesis sequence: transcribe, tag, cluster, name, imply, so-what.** No stage skipped. +4. **Tags emerge from artifacts; taxonomy not pre-designed.** +5. **Tag proliferation allowed; clustering collapses.** +6. **Patterns named with conviction; not categories or truisms.** +7. **Each pattern produces a specific falsifiable product implication.** +8. **Each implication has a so-what tied to a real decision.** +9. **Output is a document, not a deck.** Patterns lead; evidence in appendix. +10. **Synthesis is opinionated.** Hedges flagged; conviction shown. +11. **Review loop before publish.** Participants, adjacent teams, quantitative validation where available. +12. **Data gaps named, not buried.** Where research did not support a position, the synthesis says so. + +The output of the framework is a synthesis the team can act on: short, opinionated, evidence-grounded, decision-driving, accountable to challenge. + +--- + +## Reference files + +- [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md) - Five research types with synthesis implications. Composition patterns across types within a discovery cycle. +- [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md) - The six-stage sequence with worked example. Stage outputs, common skip-failures, time investment per stage. +- [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md) - Tag-at-artifact-level discipline, allow tag proliferation, cluster on patterns not overlap, name after clustering, tag dissent. +- [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md) - Pattern names that work and fail. Avoiding category bloat, naming-with-conviction, the implication-legibility test. +- [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md) - The bridge from pattern to implication. Falsifiability, multi-implication patterns, cost acknowledgment, the not-act implication. +- [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md) - Document over deck, patterns lead, evidence appendix, opinionated voice, decision-input section. +- [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md) - Participant review, adjacent-team review, quantitative validation, the challenge-the-synthesis session, iteration before publish. +- [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md) - Pattern thinness, segment under-representation, contradictory clusters, decision time pressure, the we-have-enough trap. +- [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: synthesis is where research earns its keep + +Discovery research is one of the most expensive activities a product team commissions. The expense is mostly hidden: customer time, researcher time, the opportunity cost of the discovery cycle itself, the management overhead of recruiting and scheduling. Most of that expense gets spent before synthesis even begins. + +The teams that earn returns on the research investment are the teams that take synthesis seriously: the sequence is run end-to-end, the patterns are named with conviction, the implications are falsifiable, the so-what ties to specific decisions, the output is a load-bearing document the team references for months. The teams that do not earn returns produce data-dumps or insight-theater; their research becomes documentation of work done rather than the input to work to come. + +When in doubt about whether a synthesis is ready, ask: are the patterns named with conviction, do they reach product implications, do the implications tie to specific decisions, has the synthesis been reviewed by participants and adjacent teams, are the data gaps named honestly? If yes to all of those, the synthesis is real. If no to any, the gap is where the research investment will fail to convert into decisions. diff --git a/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md b/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md new file mode 100644 index 0000000..a7b35c6 --- /dev/null +++ b/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md @@ -0,0 +1,193 @@ +# Common discovery synthesis failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most synthesis failures share a single root, which is treating synthesis as documentation work rather than as decision work. + +--- + +## Failure 1: We did the research but never made decisions from it + +**Symptom.** Discovery cycle completed; transcripts and notes filed; the team's roadmap discussions in the following months never reference the research. + +**Diagnosis.** Data-dump or insight-theater pattern. Synthesis sequence either skipped entirely (data-dump) or stopped at findings without reaching decisions (insight-theater). + +**Cure.** Run the synthesis sequence end-to-end on the existing artifacts. Even months after the original research, retroactive synthesis can produce decisions the original research was meant to inform. + +**Prevention.** Before commissioning the next research cycle, name the decisions the research is intended to inform. Build the synthesis sequence into the discovery plan, not as an afterthought. + +--- + +## Failure 2: Our synthesis deck got a polite review and was never referenced again + +**Symptom.** A polished readout deck. A 30-minute presentation. Positive feedback in the meeting. Six months later nobody references the synthesis in product decisions. + +**Diagnosis.** Insight-theater. Output was performative rather than load-bearing. Optimized for the presentation moment, not for reference use. + +**Cure.** Convert the deck content into a document with patterns leading, evidence in appendix, decision-input section. Recirculate as a reference document. + +**Prevention.** Future synthesis ships as documents, not decks. The presentation is a deck if needed; the synthesis is the document. + +--- + +## Failure 3: We have 30 named patterns and no clear priorities + +**Symptom.** The synthesis lists many patterns. The team agrees they are interesting but cannot prioritize. The synthesis fails to drive a roadmap shift. + +**Diagnosis.** Category bloat. Under-clustering produced inflation. Many of the 30 patterns are variations on a smaller number of underlying patterns. + +**Cure.** Re-cluster. Take the pattern list back to the clustering stage and look for the 4-8 underlying patterns the data actually supports. Synthesize from the consolidated list. + +**Prevention.** Cap pattern count at 4-8 for typical synthesis. When more than 8 patterns emerge, that is a signal to recluster, not to ship with bloat. + +--- + +## Failure 4: Every pattern reads as something we already knew + +**Symptom.** The synthesis names patterns that read as truisms. Team members who attended the readout could have produced the patterns without the research. + +**Diagnosis.** Pattern names captured truisms rather than the specific observations the research surfaced. The analytical work of pattern naming was skipped. + +**Cure.** Re-examine the data for what was actually surprising. Often the strongest patterns surface in the contradictions, the unexpected sub-segments, the workarounds users built. Pattern names should commit positions the team would not have committed before the research. + +**Prevention.** During pattern naming, apply the "what the team did not know" test. Patterns that read as common-knowledge are probably under-named. + +--- + +## Failure 5: The patterns contradict each other and we cannot reconcile them + +**Symptom.** Two patterns point in opposite directions. The synthesis is silent on the contradiction or hand-waves it. + +**Diagnosis.** Often segment misfit: different segments have different needs, and the synthesis did not surface the segment distinction. Sometimes context misfit: different use contexts produce different patterns. + +**Cure.** Re-examine the data for the segment or context dimension that explains the contradiction. The contradiction often becomes the most valuable finding once explained. + +**Prevention.** Tag dissent and contradictions explicitly during the tagging stage. Surface them through clustering. Address them in synthesis rather than burying them. + +--- + +## Failure 6: Research participants did not recognize themselves in our synthesis + +**Symptom.** When shown the synthesis, participants say "I did not say that" or "this does not match my experience." + +**Diagnosis.** Synthesis fabricated patterns or projected interpretations not in the data. The pattern naming reached for what the team wanted to find rather than what the participants actually said. + +**Cure.** Restart with closer evidence-tracking. Each pattern should be traceable to specific moments in specific artifacts. Patterns that cannot be traced are projections, not observations. + +**Prevention.** Build participant review into the synthesis process. Synthesis that participants do not recognize fails the validation; revise before publishing. + +--- + +## Failure 7: The synthesis is detailed but the team cannot tell what to do + +**Symptom.** Patterns are clear and well-supported. The team agrees on the patterns. The team cannot derive the product implications. + +**Diagnosis.** Implications missing or vague. The synthesis stopped at observations without bridging to product responses. + +**Cure.** Add implications to each pattern. Each implication should be specific, falsifiable, cost-acknowledged, and tied to a specific decision. + +**Prevention.** The synthesis sequence's implication stage is non-negotiable. Synthesis that ships without implications is incomplete. + +--- + +## Failure 8: We hedged every pattern and the synthesis reads as wishy-washy + +**Symptom.** "Users may sometimes occasionally seem to indicate." Every claim caveated. The synthesis avoids commitment. + +**Diagnosis.** Hedge stacking. The researcher did not commit to what the data showed. + +**Cure.** Rewrite with conviction. Name patterns as if the data supports them. If the data does not support the position, name a smaller position the data does support; do not hedge an oversized claim. + +**Prevention.** During pattern naming, apply the conviction test. Hedge stacking signals a pattern that should either be sharpened or dropped. + +--- + +## Failure 9: Our quote walls were impressive but the deck was 60 slides + +**Symptom.** Beautiful quote pulls; designed personas; 60 slides. Readers admired the deck. Few remember the patterns. + +**Diagnosis.** Insight-theater. Evidence dominated; analysis receded. Quote walls without analytical bridge. + +**Cure.** Restructure as a document. Patterns lead; evidence in appendix. Quote walls converted into evidence-summary paragraphs supporting each pattern. + +**Prevention.** The format choice is upstream. Default to documents; reserve decks for short executive summaries paired with substantive documents. + +--- + +## Failure 10: The synthesis recommended 20 product changes; we shipped one + +**Symptom.** Synthesis presents many implications. Team picks the easiest or most-vocal one to ship. The rest sit in the synthesis document unaddressed. + +**Diagnosis.** Wishlist synthesis. Implications did not acknowledge cost or prioritize within themselves. The synthesis offloaded prioritization to the team without giving them a starting point. + +**Cure.** Re-prioritize within the synthesis. Each implication gets a cost note. The synthesis recommends a sequence: which implications to address now, which to defer, which to drop. The team has a starting point for prioritization. + +**Prevention.** During implication writing, surface cost. The synthesis owner uses available context to estimate cost; pairs with engineering for harder estimates. Cost-blind synthesis is incomplete. + +--- + +## Failure 11: Adjacent teams disagreed with our patterns and we did not engage + +**Symptom.** Synthesis ships. Support team says "this does not match what we see in tickets." Sales team says "our prospects say something different." The synthesis fails to align with the teams closest to the customer. + +**Diagnosis.** Adjacent-team review skipped or compressed. The synthesis reached publication without surfacing perspectives the research team did not have. + +**Cure.** Pause publication. Run the adjacent-team review even after the fact. Revise based on inputs. + +**Prevention.** Build adjacent-team review into the synthesis workflow. Make it non-negotiable. The teams closest to the customer have ground-truth observations the research team needs. + +--- + +## Failure 12: Data gaps buried in the synthesis + +**Symptom.** Synthesis presents conclusions where the data did not support them. The recommendations sound confident; the data is thin in places the synthesis did not name. + +**Diagnosis.** The we-have-enough trap. Sunk-cost reasoning suppressed honest gap-naming. + +**Cure.** Audit each pattern for data sufficiency. Where gaps exist, name them explicitly. Where recommendations rest on under-supported patterns, downgrade or hedge them honestly. + +**Prevention.** The synthesis owner's job is to be honest about what the data can and cannot support. The team relies on the synthesis owner for this honesty. + +--- + +## Failure 13: Synthesis sequence stages skipped + +**Symptom.** Synthesis arrives at "patterns" without going through the tagging and clustering stages. Patterns feel imposed on the data rather than emerging from it. + +**Diagnosis.** Stages skipped. Researcher jumped to pattern-naming based on impressions from reading transcripts. + +**Cure.** Restart the sequence from tagging. Patterns from skipped sequences are usually projections; tagging-grounded patterns are observations. + +**Prevention.** The sequence is non-negotiable. Every synthesis runs through transcribe, tag, cluster, name, imply, so-what. + +--- + +## Failure 14: Synthesis owner became defensive in the review + +**Symptom.** Adjacent teams raise concerns; synthesis owner argues against each one; the review session produces no revisions; synthesis ships unchanged. + +**Diagnosis.** Defensive review posture. The owner treated review as defense of the synthesis rather than as input to it. + +**Cure.** Owner takes notes; does not defend in the moment; revises based on inputs over the following days. Reviewer concerns surface in the revision; the synthesis improves. + +**Prevention.** Establish the review session's purpose explicitly: input, not approval. The synthesis owner's job in the session is to listen. + +--- + +## The cross-cutting pattern + +Most synthesis failures share a single root: treating synthesis as documentation work rather than as decision work. + +Documentation work prioritizes capturing the research; producing a deliverable; performing for an audience. Output: artifacts that look like synthesis but do not drive decisions. + +Decision work prioritizes producing direction; committing positions; informing prioritization. Output: synthesis that team members reference for months, that drives roadmap shifts, that earns the research investment. + +The fix for almost any synthesis failure starts with the same question: what decision is this synthesis supposed to inform? When the answer is clear, the synthesis becomes load-bearing. When the answer is "we should document the research," the synthesis fails as decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting documentation-vs-decision pattern. + +## Implementation choices that stay internal + +Specific reviewer training on synthesis-failure detection. Specific automation that flags synthesis structures (e.g., document length checks, hedge-frequency analysis). Specific reviewer dashboards. The team's own conventions for catching synthesis failures pre-publish. These vary by team. diff --git a/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md b/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md new file mode 100644 index 0000000..1ed2d6b --- /dev/null +++ b/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md @@ -0,0 +1,192 @@ +# From pattern to product implication + +The bridge from observation to decision. Implications are where synthesis adds value beyond transcription. + +A pattern without an implication is a finding. A finding describes the world; an implication proposes action. Synthesis stops at findings; actionable synthesis reaches implications. + +--- + +## Implications are the writer's analytical work, not what the user said + +**The principle.** Users describe their experience; PMs interpret what experience implies for the product. + +**Why this matters.** A common synthesis failure is presenting implications as if they came from users. "Users want X" treated as an implication. But users do not always know what would actually solve their problem; they describe symptoms, not solutions. + +**Worked example.** A pattern: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +- What users said: "I had to stop and find my credit card." +- What users want (per their own description): "Make signup not require credit card details." +- What the implication actually is (PM analytical work): defer the credit-card-requiring step to after first success state, OR remove the credit card requirement at signup, OR allow signup without credit card and request it before paid features. + +The implication options surface from analytical interpretation, not from user prescription. Users said the symptom; the PM proposes the system response. + +**The discipline.** Frame implications as the team's analytical position grounded in the pattern, not as user requests. "The pattern implies X" rather than "Users want X." + +--- + +## Each pattern can have multiple implications + +**The principle.** Synthesis surfaces options; the prioritization decision picks one. + +**Worked example.** A pattern: "Free users hit the upgrade prompt before experiencing paid value." + +Possible implications: + +- Delay the upgrade prompt until after the user has experienced the value-realization moment. +- Show the upgrade prompt earlier but reframe it as exploratory rather than transactional. +- Add a value-realization moment earlier in the free experience to align with the existing prompt timing. +- Remove the upgrade prompt entirely; let users discover paid features through usage. + +Each implication is a different product response. The synthesis presents the options; the team's prioritization debate picks one (or sequences several). + +**Why multi-implication matters.** Single-implication synthesis presents the synthesizer's preferred solution as if it were the only solution. Multi-implication synthesis surfaces options the team can debate. + +**The presentation.** Per pattern, surface 2-4 candidate implications. Acknowledge tradeoffs between them. Recommend if the data supports a recommendation; otherwise present the options for prioritization. + +--- + +## Implications should be falsifiable + +**The principle.** A vague implication cannot be acted on or debated. A specific implication can. + +**Vague implications.** + +- "We should improve onboarding." +- "Pricing should be reconsidered." +- "Mobile experience needs attention." + +These are too vague to drive decisions. The team agrees to "improve onboarding" without committing to any specific change. + +**Falsifiable implications.** + +- "Defer configuration step 3 to after first success state." +- "Add a value-realization moment within the first 90 seconds of signup." +- "Make the homepage hero copy lead with B2B use cases." + +These commit specific positions. The team can debate them, scope them, kill them, prioritize them. + +**The test.** For each implication, ask: could the team disagree with this and explain why? If the implication is vague enough that disagreement is impossible, the implication is too vague to be useful. + +--- + +## Implications should acknowledge cost + +**The principle.** Patterns suggest solutions; solutions cost product capacity. Synthesis that ignores cost produces wishlists. + +**The pattern that fails.** Synthesis recommends 30 product changes without acknowledging that delivering them all is impossible. The team takes one or two; the rest sit. The synthesis produced no actionable input because the team had no help prioritizing. + +**The pattern that works.** Each implication includes an estimated cost dimension and a recommendation about whether the cost is justified. + +- "Defer configuration step 3 (medium engineering cost; high expected impact on signup conversion)." +- "Pre-populate step 3 with sensible defaults (low engineering cost; medium expected impact)." +- "Remove credit card requirement entirely (high cost across systems; uncertain impact)." + +The cost annotations help the team prioritize without re-doing the synthesis work. + +**The discipline.** PMs doing synthesis usually have enough context to estimate cost roughly. If they do not, they can pair with engineering to estimate. Cost-blind synthesis is incomplete. + +--- + +## Some patterns imply not-acting + +**The principle.** Sometimes the pattern reveals friction the team should not address. + +**When not-acting is honest.** + +- The friction affects too few users to justify the engineering cost. +- The friction reveals segment misfit; the affected users are not the team's target. +- Addressing the friction would compromise other priorities or product positioning. +- The friction is real but the proposed solutions are worse than the problem. + +**Worked example.** A pattern: "Enterprise users want admin controls that small-team users do not need." + +Implications: + +- Build the admin controls (high cost, expands target market). +- Build the admin controls only for the enterprise tier (medium cost, segment-specific). +- Do not build (acknowledges enterprise as not the target segment). + +If the team is committed to small-team users as the target market, the not-act implication is honest; building enterprise admin controls would dilute focus. + +**The naming discipline.** When the synthesis recommends not-acting, name it explicitly. "The pattern is real but the recommended response is to not address it because [reason]." Buried not-act implications get overlooked; the team adds the unaddressed friction to the next quarter's roadmap because nobody surfaced the not-act case. + +--- + +## Implications that bridge to specific decisions + +**The principle.** The strongest implications point to a specific decision the team is making. + +**Implication-to-decision mapping.** + +- Implication: "Defer configuration step 3." + - Decision input: should the Q2 roadmap include the onboarding redesign? (Yes, with this approach.) +- Implication: "Add B2B-leading homepage hero." + - Decision input: should the homepage redesign be prioritized this quarter? (Yes, with positioning shift.) +- Implication: "Do not address enterprise admin controls." + - Decision input: should enterprise tier be in this year's roadmap? (No; small-team focus continues.) + +**Why decision-mapping matters.** Implications floating free of decisions produce a list the team must connect to its prioritization work themselves. Implications mapped to decisions produce direct input. + +--- + +## Implication strength and confidence + +**The principle.** Not all implications are equally well-supported. + +**Strong implications.** + +- Pattern is supported by multiple research types (interviews + tickets + survey). +- Implication has a clear analytical bridge from the pattern. +- Cost is reasonable relative to expected impact. +- Decision input is clear. + +**Weaker implications.** + +- Pattern is supported by limited evidence (3 interviews; thin volume). +- Implication is one of several plausible options without clear analytical bridge. +- Cost is uncertain. +- Decision input is hedged. + +**The discipline.** Synthesis labels implications by strength. Strong ones get presented as recommendations; weaker ones as options for further investigation. The team can prioritize confidently when it knows which implications carry weight. + +--- + +## Common pattern-to-implication failures + +**Implications that restate the pattern.** "The pattern shows X. The implication is X." No analytical bridge; no value added. + +**Wishlist implications.** Synthesis recommends 30 changes; the team cannot prioritize; one or two ship; the rest sit. + +**Implications buried in narrative.** The synthesis discusses the pattern at length; the implication is one sentence at the end. Readers miss it. + +**No cost acknowledgment.** Implications presented as if all are equal cost; team has to do the cost analysis itself. + +**Skipping the not-act implication.** Synthesis recommends action on every pattern; some patterns warrant not-acting; the synthesis fails to surface this honestly. + +**Implications that prescribe specific designs.** Implications should propose product responses, not detailed designs. Detailed designs are for spec writing; implications are the upstream input. + +--- + +## The implication-quality audit + +A short framework for auditing implications. + +1. Is each implication an analytical proposition, not a user request? +2. Are multiple candidate implications surfaced where appropriate? +3. Is each implication specific enough to be falsifiable? +4. Does each implication acknowledge cost? +5. Where the data supports not-acting, is that surfaced honestly? +6. Does each implication map to a specific decision? +7. Is implication strength labeled? + +Synthesis that passes this audit converts research into decisions. Synthesis that fails it produces findings that look like decisions but do not drive them. + +--- + +## Methodology-level choices that stay in the public skill + +The implication-as-analytical-work principle. Multi-implication patterns. Falsifiability. Cost acknowledgment. The not-act implication. Decision mapping. Implication strength. Common failures. The audit. + +## Implementation choices that stay internal + +Specific document templates that surface implications. Specific cost-estimation conventions. Specific cross-functional review patterns for cost validation. The team's own conventions for implication-strength labeling. These vary by team. diff --git a/skills/discovery-research-synthesis/references/pattern-naming-patterns.md b/skills/discovery-research-synthesis/references/pattern-naming-patterns.md new file mode 100644 index 0000000..26d6aac --- /dev/null +++ b/skills/discovery-research-synthesis/references/pattern-naming-patterns.md @@ -0,0 +1,178 @@ +# Pattern naming patterns + +Pattern naming is the work that distinguishes synthesis from documentation. A pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references for months. + +The naming is not formatting. It is analytical work that surfaces what the data actually shows. Most synthesis underperforms because the pattern names did not do this work. + +--- + +## A pattern name is not a category label + +**The principle.** Categories describe topics; patterns describe specific observations the data reveals. + +**Examples.** + +- Category: "Onboarding." +- Pattern: "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." + +- Category: "Pricing." +- Pattern: "Free users hit the upgrade prompt before they have experienced the paid value, producing churn instead of conversion." + +- Category: "Mobile." +- Pattern: "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +**Why categories fail as pattern names.** Categories are containers. The synthesis with category-named patterns is a list of containers, not a list of observations. Readers cannot tell what the data showed; only what topic it concerned. + +**The test.** Does the pattern name commit a position about what the data reveals, or does it merely name a topic the data covered? Position-committing names are patterns; topic-naming labels are categories. + +--- + +## The name should make the implication legible + +**The principle.** A reader who sees only the pattern name should be able to guess the product implication. + +**Examples that pass the test.** + +- "Users abandon configuration step 3 because credit card details are not accessible during signup." + - Implication a reader can guess: defer configuration step 3 to after first success state, or remove credit card requirement at signup. +- "Sales prospects assume the product is for B2C because the homepage hero shows consumer use cases." + - Implication a reader can guess: revise homepage positioning to lead with B2B use cases. + +**Examples that fail the test.** + +- "Onboarding has issues." +- "Users have feedback about pricing." +- "There is mobile-related friction." + +**Why implication-legibility matters.** Synthesis exists to drive decisions. Pattern names that obscure implications force readers to do the analytical work themselves; many readers will not, and the synthesis fails to inform decisions. + +--- + +## Avoid category bloat + +**The principle.** Strong synthesis has 4-8 named patterns. Synthesis with 30 patterns is usually under-clustered: many of those are variations on a smaller number of underlying patterns. + +**Diagnosis of bloat.** + +- Look at the pattern list. Are some patterns sub-cases of others? If yes, the under-cluster is producing inflation. +- Are there patterns that always co-occur with other patterns? If yes, they may be the same pattern viewed from different angles. +- Are there patterns supported by 1-2 artifacts only? If yes, they may be noise being elevated to pattern status. + +**The cure.** Re-cluster. Take the 30-pattern list back to clustering and look for the 4-8 underlying patterns the data actually supports. + +**Why bloat fails.** Synthesis with 30 patterns produces no decision direction: the team cannot prioritize 30 things. Synthesis with 4-8 patterns surfaces what to focus on. + +--- + +## Avoid naming the obvious + +**The principle.** A pattern is a specific observation that the product team did not already know. Pattern names that read as truisms ("users want fast performance") are not patterns. + +**The truism trap.** + +- "Users want better performance." +- "Users find some aspects confusing." +- "Pricing is a consideration in the decision." +- "Mobile usage is increasing." + +These are descriptive of the universe; they do not describe what the research revealed. + +**The cure.** For each pattern name, ask: would this name have been just as accurate without the research? If yes, the pattern is a truism. The research must have surfaced something more specific; rewrite the name to capture it. + +**The "what the team did not know" test.** Strong pattern names commit a position the team would not have made before the research. Weak pattern names commit positions the team already held. + +--- + +## Name with conviction + +**The principle.** Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly. + +**Hedging vs precision.** + +- Hedged: "Some users may experience occasional difficulty in some configuration steps." +- Precise: "Users abandon configuration step 3 in 40% of signup attempts." + +The precise name is also commitment-bearing: it claims a specific behavior at a specific frequency. If the data does not support 40%, the name is wrong; the researcher should restate. The hedged name avoids being wrong by avoiding being specific. + +**Why conviction matters.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. Readers cannot debate hedged patterns; they cannot prioritize them; they cannot act on them. Conviction-named patterns invite challenge, which strengthens synthesis. + +**The discipline.** Name as if the data fully supports the position. If it does not, name a smaller position the data does support. Do not pad an under-supported position with hedging. + +--- + +## Pattern naming structures that work + +Several structures recur across strong synthesis. + +**The behavioral observation: "Users [do specific action] because [specific cause]."** + +Example: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +This structure forces specificity in both behavior and cause. + +**The contradiction: "Users [say X] but [do Y]."** + +Example: "Users in interviews report wanting more configuration options, but in support tickets request defaults that match their actual usage." + +This structure surfaces the gap between stated preference and revealed preference. + +**The segment difference: "[Segment A] [does X], while [Segment B] [does Y]."** + +Example: "Free users hit the upgrade prompt before experiencing paid value, while paid users encounter it after the value-realization moment." + +This structure surfaces sub-segment patterns the research revealed. + +**The mismatch: "[Team's framing] does not match [user's framing]."** + +Example: "Marketing positions the product as B2C-friendly; sales prospects evaluating for B2B use assume the product is consumer-only based on the homepage." + +This structure surfaces positioning gaps. + +**The frequency-specific: "[Specific behavior happens at frequency X across segment Y]."** + +Example: "30% of new users hit the configuration friction within 5 minutes of signup; the friction correlates with day-7 churn." + +This structure pairs qualitative observation with quantitative validation. + +--- + +## The pattern-name editing pass + +Strong synthesis runs a final editing pass focused only on pattern names. + +**For each pattern name, the editing questions.** + +1. Is this a category or a pattern? +2. Can a reader guess the implication from the name alone? +3. Is this a truism or a specific observation? +4. Does the name commit a position with conviction? +5. Does the name match what the data actually shows (no overstatement)? +6. Could this be split into multiple patterns or merged with another? + +**The editing investment.** 1-2 hours of focused name-editing on a 4-8 pattern set. The investment pays off in synthesis usability. + +--- + +## Common pattern-naming failures + +**Categories disguised as patterns.** "Onboarding patterns" as a section heading; nothing in the section actually names a pattern. + +**Patterns that hedge into nothing.** "Users may sometimes experience difficulty"; the name commits no position. + +**Truism patterns.** "Users want fast performance"; the name describes the universe, not the data. + +**Vague specificity.** "Configuration step 3 is problematic"; specific enough to seem like a pattern, vague enough to not be one. + +**Pattern bloat.** 30 named patterns; the synthesis loses focus and produces no priorities. + +**Patterns named without evidence ties.** Synthesis where readers cannot trace each pattern to specific artifacts and quotes. Patterns become assertions rather than observations. + +--- + +## Methodology-level choices that stay in the public skill + +The category-vs-pattern distinction. The implication-legibility test. The avoid-bloat principle. The avoid-truism principle. The conviction principle. The pattern-name structures that work. The editing pass. Common naming failures. + +## Implementation choices that stay internal + +Specific document templates that surface pattern names prominently. Specific reviewer rubrics for editing pattern names. Specific A/B testing of pattern name variants for clarity. The team's own conventions for pattern count within the bands. These vary by team. diff --git a/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md b/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md new file mode 100644 index 0000000..341f05f --- /dev/null +++ b/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md @@ -0,0 +1,221 @@ +# Research types and when each fits + +Five common discovery research types, what each surfaces, what synthesis they support, and how to compose them within a single discovery cycle. + +Research-type selection is upstream of synthesis. The wrong types collected for the question produce data that synthesis cannot rescue. The right types collected, even at modest scale, produce synthesis that drives decisions. + +--- + +## Customer interviews + +**Format.** 30-90 minute conversations, structured or semi-structured. Often one-on-one, sometimes in pairs or small groups for specific contexts. + +**Artifacts.** Recordings, transcripts, moderator notes, sometimes follow-up email exchanges. + +**What this surfaces.** + +- Why users do what they do (motivation, context, constraints). +- The struggling moments and workarounds users have built. +- The mental model behind user behavior. +- The trade-offs users are weighing that the team did not anticipate. +- The vocabulary users actually use (often different from internal product language). + +**What this does not surface.** + +- What users actually do in practice (interview self-report differs from behavioral data). +- Patterns that emerge only at scale (a single interview is one data point). +- Pricing willingness to pay (interview answers about price are notoriously unreliable). + +**Synthesis implications.** + +- Highest per-artifact richness; warrants careful per-transcript tagging. +- Best paired with other research types that quantify the qualitative patterns. +- Pattern thinness risk: 8-15 interviews surfaces patterns; 3-5 surfaces hypotheses that need more validation. + +**Typical batch size.** 8-15 interviews per discovery cycle. Larger batches saturate (most patterns emerge by interview 8-10 in a focused topic). + +--- + +## Support ticket reviews + +**Format.** Audit of recent support tickets, often spanning a defined time window or a defined product area. + +**Artifacts.** Tagged ticket dataset, agent-conversation transcripts, sometimes recorded support calls. + +**What this surfaces.** + +- The friction users actually hit (revealed by ticket volume). +- The vocabulary users use to describe broken experiences. +- The disconnect between intended user flow and actual user behavior. +- Repeated workflows that produce confusion or errors. +- Documentation and onboarding gaps. + +**What this does not surface.** + +- Why users got there (the ticket starts at the problem; the path before is not visible). +- The experience of users who did not contact support (silent struggling). +- Users who succeed without friction. + +**Synthesis implications.** + +- Lower per-artifact richness; higher volume; signal lives in patterns across many tickets. +- Best for surfacing concrete friction points; weak for understanding motivation. +- Often pairs with interviews (interviews explain why; tickets document where). + +**Typical batch size.** 100-500 tickets per audit, often filtered by topic or product area. + +--- + +## Sales call analysis + +**Format.** Recording or transcript review of recent sales calls. Often pairs with sales team feedback on patterns they hear repeatedly. + +**Artifacts.** Call recordings, sales notes, CRM-tagged objections, deal-stage data. + +**What this surfaces.** + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Use cases prospects describe (sometimes different from how marketing describes the product). +- Words prospects use to describe their situation (vocabulary signal). + +**What this does not surface.** + +- Existing-customer experience (sales calls are pre-purchase). +- Why prospects who did not buy did not buy (lost-deal analysis is a separate research mode). + +**Synthesis implications.** + +- Pairs well with positioning and pricing decisions. +- Useful for marketing-product alignment work. +- Sales teams often have synthesis hypotheses already; the research either confirms or challenges those. + +**Typical batch size.** 15-30 calls per audit. + +--- + +## Survey data + +**Format.** Quantitative responses to structured questions, often with optional qualitative comments. + +**Artifacts.** Response dataset, segmented by audience attributes. + +**What this surfaces.** + +- The frequency and severity of patterns identified through other research. +- Segment differences (do Pro users and Free users have different needs). +- Quantitative validation of qualitative hypotheses. +- Aggregate satisfaction or NPS-style sentiment. + +**What this does not surface.** + +- Why users responded the way they did (closed-ended responses do not explain). +- Patterns that the survey questions did not anticipate (surveys cannot find what they did not ask about). +- Behavior (surveys reveal what users say, not what they do). + +**Synthesis implications.** + +- Best as validation of qualitative patterns at scale, not as primary discovery. +- Survey design biases (leading questions, response order effects, satisficing) compromise data; treat with skepticism. +- Open-ended comments are often the highest-value section of a survey. + +**Typical batch size.** 100-2,000 responses, depending on segment specificity. + +--- + +## In-app feedback + +**Format.** Users submitting feedback through in-product channels (feedback widgets, NPS prompts, post-task surveys, error-state feedback forms). + +**Artifacts.** Submitted feedback corpus, often timestamped and contextualized by where in the product the feedback was triggered. + +**What this surfaces.** + +- Friction at the moment users encounter it (high context fidelity). +- Patterns across many low-effort submissions. +- Feature requests grounded in specific usage moments. +- Bugs and broken experiences not captured by support. + +**What this does not surface.** + +- Users who did not bother to submit feedback (silent majority). +- Why users hit the friction (the feedback names the problem; not always the cause). +- Patterns from users who do not actively use the feedback channels. + +**Synthesis implications.** + +- Volume varies widely; some products see high in-app feedback volume, others minimal. +- Often pairs with support tickets (similar surface area; different submission channels). +- Useful as ongoing signal; this skill is more about the periodic-audit case (`user-feedback-aggregation` covers continuous synthesis). + +**Typical batch size.** Ongoing; synthesized in periodic audits over defined windows. + +--- + +## Composition across types + +Strong discovery cycles combine research types deliberately. + +**The pair-and-validate pattern.** + +- Interviews (depth, ~12 conversations) provide qualitative patterns. +- Support tickets (volume, ~300 tickets) document where friction surfaces in practice. +- Survey (validation, ~500 responses) quantifies the patterns at scale. +- Synthesis weaves all three: interview patterns ground the why, tickets ground the where, survey grounds the how-many. + +**The triangulate-the-decision pattern.** + +- A specific decision (should we redesign onboarding) gets evidence from three sources. +- Interviews surface the experience of recent signups. +- Sales calls surface what prospects say onboarding will look like. +- Support tickets surface what new users actually hit. +- Synthesis converges three perspectives on the same decision. + +**The single-type sufficiency pattern.** + +- Some discovery questions only need one type. A pricing review might need only sales call analysis. A support-volume reduction effort might need only ticket analysis. +- Discipline: do not commission research types that will not contribute to the decision. + +**The wrong-pairs to avoid.** + +- Interviews + survey only, with no behavioral data: both are self-report; both can be wrong in the same direction. +- Survey only, no qualitative: the survey assumes the questions are right. +- Sales calls only, no customer voice: the prospect view is one segment; existing-customer voice may differ. + +--- + +## Research-type pitfalls per type + +**Interview pitfalls.** Recruiting bias (the easiest-to-recruit users are not always representative). Leading questions. Confirming the team's prior hypothesis rather than challenging it. Small-batch over-generalization. + +**Support ticket pitfalls.** Survivorship bias (only users who contacted support are visible; users who silently churned are not). Tag quality (poor tagging compounds in synthesis). Time-window choice (a window that misses recent product changes can mislead). + +**Sales call pitfalls.** Stage selection (early-stage discovery calls and late-stage closing calls reveal different things). Sales-team interpretation (sales reps' framings can color how calls are tagged). Anonymization vs detail (privacy needs can erase the specifics that matter). + +**Survey pitfalls.** Response bias (who responds is not representative of who is asked). Question wording. Ordering effects. Satisficing (respondents click through without engaging). Falsely-precise quantitative output from low-quality data. + +**In-app feedback pitfalls.** Channel bias (the kinds of users who submit in-app feedback differ from those who do not). Volume-driven prioritization (loudest categories get attention; quieter ones get missed). + +--- + +## When to commission what + +A short framework. + +1. **Decision driving the research.** What product decision is this research meant to inform? +2. **Best research type for that decision.** Discovery (interviews lead), validation (survey or quantitative leads), friction-mapping (support and in-app feedback lead), positioning (sales call analysis leads). +3. **Composition.** Which secondary types triangulate the primary? +4. **Capacity.** What can be collected within the time and budget the decision allows? +5. **Existing data check.** Has the team already collected research that would answer the question? Mining existing artifacts often produces value before commissioning new research. + +--- + +## Methodology-level choices that stay in the public skill + +The five research types and what each surfaces. The composition patterns. The wrong-pairs to avoid. The pitfalls per type. The when-to-commission framework. The principle that research-type selection is upstream of synthesis quality. + +## Implementation choices that stay internal + +Specific recruiting platforms and incentive structures. Specific transcription tooling. Specific support-ticket platforms and their tagging schemas. Specific survey tools and statistical-significance configurations. Specific in-app feedback widgets and integration patterns. The team's own conventions for sample sizes within the bands. These vary by team, budget, and tooling. diff --git a/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md b/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md new file mode 100644 index 0000000..4043285 --- /dev/null +++ b/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md @@ -0,0 +1,177 @@ +# Synthesis review and validation + +How synthesis gets pressure-tested before it drives decisions. Review and validation surface synthesis errors that the research team missed: fabricated patterns, projected interpretations, missing dissent, segment misreads. + +The discipline is making review non-negotiable. Synthesis that ships without review carries unacknowledged blind spots; review compresses those blind spots before the synthesis becomes the team's working document. + +--- + +## Internal review with research participants where possible + +**The principle.** Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? + +**Why participant review matters.** + +- Participants are the only authoritative source on whether the synthesis represents their experience. +- Misrecognition signals fabrication: the synthesis projected interpretations the data did not support, or named patterns that did not match what participants actually said. +- Recognition validates the synthesis: participants endorse the patterns as accurate representations. + +**The mechanics.** + +- Send the synthesis (or relevant excerpts) to 3-5 research participants for review. +- Ask: "Do these patterns reflect your experience? Anything missing? Anything the synthesis got wrong?" +- Build participant recognition into the research design from the start (with consent for follow-up review). + +**The exception.** Some research types (large-scale survey, anonymous in-app feedback) do not support participant review at the individual level. For those, validation depends on aggregate quantitative checks (the next section). + +**The honest disclosure.** When participant review surfaces misrecognition, the synthesis revises rather than dismissing the feedback. Synthesis that dismisses participant pushback is reverting to confirmation bias. + +--- + +## Adjacent-team review + +**The principle.** Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? + +**Why adjacent-team review matters.** + +- Adjacent teams have ground-truth observations the research did not access. Support sees the friction users hit every day; sales hears prospect objections; engineering knows which problems are technically tractable. +- Adjacent teams catch synthesis errors that the research team missed: patterns that contradict what support handles daily, implications that ignore engineering constraints. +- Adjacent teams' alignment with synthesis affects whether the synthesis drives decisions: if support disagrees with the support-related patterns, the synthesis loses authority. + +**The mechanics.** + +- Share the synthesis with relevant adjacent-team leads for review. +- Hold a structured review session where adjacent teams can challenge, validate, or extend the patterns. +- Capture adjacent-team observations as inputs to synthesis revision. + +**Common adjacent-team feedback patterns.** + +- Support: "Your synthesis names X as a pattern, but support tickets show Y is also load-bearing and not in the synthesis." +- Sales: "Prospects do say what your synthesis claims, but the patterns you missed are the pricing-conversation friction." +- Engineering: "The implication you propose has a constraint the synthesis did not account for." + +The synthesis revises in light of these inputs. + +--- + +## Quantitative validation where possible + +**The principle.** Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. + +**The validation pattern.** + +- Synthesis says: "Users abandon configuration step 3 because credit card details are not accessible at signup." +- Quantitative validation: pull analytics on configuration step 3 abandonment rate. Does the data confirm 40% abandonment that the pattern implies? Does abandonment correlate with the credit card requirement (versus other possible causes)? +- If the data confirms: the pattern is strongly supported. +- If the data does not confirm: the pattern needs revision; the qualitative signal may not generalize. + +**Why validation matters.** + +- Qualitative patterns can overstate frequency; small-sample interview signal does not always match large-sample reality. +- Quantitative validation grounds synthesis in scaled data without requiring the synthesis to be quantitative-only. +- Validation reveals which patterns are strong enough to act on and which need more investigation. + +**See `experiment-design`** for rigorous A/B testing as quantitative validation. **See `product-analytics-setup`** for the instrumentation that makes validation possible. + +**The honest disclosure.** When quantitative validation contradicts qualitative patterns, the synthesis adjusts. Patterns the analytics does not support get downgraded or removed. Synthesis that ignores quantitative pushback in favor of qualitative claims is unrigorous. + +--- + +## The "challenge the synthesis" session + +**The principle.** A specific session where adjacent teams try to find what the synthesis missed, overstated, or railroaded. + +**The session structure.** + +- Synthesis owner presents the patterns and implications (15-30 minutes). +- Adjacent-team participants challenge: "What patterns did the research miss? What implications overstate the data? What decisions is the synthesis trying to railroad?" +- Synthesis owner takes notes; does not defend; the session is for surfacing concerns, not for resolution in the moment. +- Synthesis owner revises based on the inputs over the following days; revised synthesis circulates back. + +**Why this works.** + +- Productive disagreement strengthens synthesis. The team that surfaces concerns is contributing to better synthesis, not undermining the research investment. +- The session creates space for honest pushback that quieter review formats sometimes suppress. +- The session signals that synthesis is open to challenge, which strengthens the team's trust in the synthesis once it ships. + +**The anti-pattern.** Synthesis owners who treat the session as defense of the synthesis rather than as input to the synthesis. The owner pushes back on every challenge; adjacent teams disengage; synthesis ships unrevised. + +**The discipline.** The synthesis owner's job in the session is to listen and capture, not to defend. Defense happens in the revision; pushback happens later, after considering the input. + +--- + +## Iterate before publishing + +**The principle.** Synthesis goes through revision based on the review loop. Synthesis that ships in first-draft state usually carries unacknowledged blind spots. + +**The iteration cycle.** + +- First draft from the synthesis owner. +- Participant review (where possible). +- Adjacent-team review (always). +- Challenge-the-synthesis session. +- Revision based on inputs. +- Final review by senior product leader for clarity and quality. +- Publication. + +**Time investment.** The review-and-iteration loop adds 1-2 weeks to the synthesis timeline. That investment is small relative to the cost of publishing synthesis with blind spots that produce wrong decisions. + +**Common iteration outputs.** + +- Patterns split (the original pattern was actually two patterns adjacent teams distinguished). +- Patterns merged (the original separation was not load-bearing). +- Patterns revised (the framing did not match the data on closer review). +- Implications expanded (additional implications surfaced during review). +- Implications narrowed (some implications overstepped what the data supports). +- Decision input refined (the original was too vague to drive decisions). + +--- + +## When the review loop reveals the synthesis cannot be saved + +**The honest case.** Sometimes review surfaces synthesis problems too deep to fix in revision: patterns built on insufficient data, projections the data did not support, framing that adjacent teams flatly contradict. + +**The response.** + +- Stop. Do not publish synthesis with known significant problems. +- Re-examine: was the underlying research adequate? Was the synthesis sequence run completely? Were the patterns named with conviction or projected? +- Restart from where the breakdown happened. Often returns to clustering or pattern-naming. +- Sometimes returns to gathering more research. The honest case is acknowledging that the discovery cycle did not produce sufficient input for reliable synthesis. + +**The cost calibration.** Restarting synthesis costs PM time. Publishing flawed synthesis costs the team's trust in research output, plus the wrong decisions the flawed synthesis drives. The latter is usually more expensive. + +--- + +## What review does not do + +**Review does not validate every synthesis.** Some synthesis fails review and should not ship; some passes with revision; some passes with minor adjustment. Review is the discipline that distinguishes the cases. + +**Review does not eliminate disagreement.** Adjacent teams may continue to disagree even after review. The synthesis owner makes the final call after considering inputs. Disagreement preserved in the published synthesis is fine and honest; pretended consensus is not. + +**Review does not slow shipping artificially.** A 1-2 week review loop on substantive synthesis is appropriate. Quick-turn synthesis (short audits, focused interview batches) can run a lighter review (asynchronous comments from 2-3 reviewers; adjacent-team check; ship). + +--- + +## Common review-and-validation failures + +**Skipping participant review.** Synthesis ships without participants ever seeing the patterns; participants would have caught misrecognitions; the synthesis carries projection. + +**Skipping adjacent-team review.** The team most likely to know the data is wrong did not see the synthesis before publication. + +**Defensive review sessions.** The synthesis owner argues against challenges instead of capturing them; the session produces defense rather than input. + +**Quantitative validation skipped.** The qualitative patterns went unchallenged by available analytics data; the synthesis overstates patterns the data does not support. + +**Iteration compressed to one round.** First draft + one review + ship. Most synthesis benefits from two rounds of revision: first round on substance, second round on presentation. + +**Review feedback dismissed.** Adjacent teams raise concerns; synthesis owner notes them but does not revise. Synthesis ships as if the feedback did not happen. + +--- + +## Methodology-level choices that stay in the public skill + +The participant review pattern. The adjacent-team review pattern. Quantitative validation. The challenge-the-synthesis session. Iteration discipline. The cannot-be-saved escalation. What review does and does not do. Common review failures. + +## Implementation choices that stay internal + +Specific reviewer pairings and roles. Specific session formats and facilitation. Specific revision tracking. Specific publication conventions. Specific quantitative validation pipelines. The team's own conventions for review-loop length. These vary by team. diff --git a/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md b/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md new file mode 100644 index 0000000..5a9b6f3 --- /dev/null +++ b/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md @@ -0,0 +1,229 @@ +# Synthesis sequence walkthrough + +The six-stage synthesis sequence with worked example. Stage outputs, common skip-failures, time investment per stage. + +The sequence is non-negotiable. Teams that skip stages produce findings that look like synthesis but are not: untagged transcripts, unclustered tags, unnamed patterns, patterns without implications, implications without decisions. Each stage builds on the previous; skipping any stage breaks the chain. + +--- + +## The six stages + +1. **Transcribe and prepare.** Convert artifacts into a synthesizable format. +2. **Tag at the artifact level.** First-pass descriptive tagging. +3. **Cluster across artifacts.** Group tags into themes. +4. **Name patterns.** Each cluster becomes a named pattern. +5. **Infer product implications.** What does each pattern imply. +6. **Name the so-what.** The decision input. + +--- + +## Stage 1: Transcribe and prepare + +**The work.** Convert artifacts into a format you can read, mark up, and search. + +**Outputs.** + +- Interview transcripts, time-stamped, speaker-labeled. +- Support ticket dataset, exported to a workable format with relevant fields (subject, body, resolution, tags, dates). +- Sales call summaries or transcripts. +- Survey data with open-ended responses extracted into a reviewable format. + +**Time investment.** Often underestimated. A 60-minute interview takes 60-90 minutes to transcribe (with AI tools) plus 30-60 minutes to clean. Eight interviews: 12-20 hours of prep before tagging starts. + +**Common skip-failures.** + +- Skipping transcription on the assumption that the recordings are sufficient. Reality: tagging from audio is impractical at any meaningful batch size. +- Cleaning to the point of distortion (removing the messy parts that contain signal). +- Skipping speaker labels (collapsed dialog loses critical context). + +**The unglamorous-but-essential principle.** Teams that skip prep work never reach the later stages because the artifacts are not workable. The investment in prep pays back across every later stage. + +--- + +## Stage 2: Tag at the artifact level + +**The work.** Read each transcript or ticket and tag it with topics, problems, quotes, and observations. + +**Outputs.** + +- Tagged artifacts (transcripts, tickets, etc.) with descriptive tags inline. +- A tag list (often 80-150 tags per batch by the end of this stage). +- Quote pulls (specific sentences worth referencing later). + +**Approach.** + +- First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. +- Allow tag proliferation. Do not force consolidation in this stage; that is for clustering. +- Tag dissent and contradictions explicitly. "User reports liking the onboarding" alongside other users reporting friction is signal; tag it. +- Mark quotes worth pulling. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. + +**Time investment.** Per artifact: 30-90 minutes for an interview transcript, 1-3 minutes per support ticket, 15-30 minutes per sales call. A typical batch (12 interviews + 200 tickets + 20 sales calls) might run 25-40 hours of focused tagging work. + +**Common skip-failures.** + +- Pre-designing the tag taxonomy and forcing artifacts into it. +- Tagging from memory after reading the transcript rather than during reading. +- Premature consolidation (collapsing tags during this stage instead of later). +- Skipping the contradictions (only tagging the dominant pattern). + +**The artifact-level discipline.** Each tag is grounded in a specific moment in a specific artifact. Tags floating free of evidence are a stage-2 failure that compounds in later stages. + +--- + +## Stage 3: Cluster across artifacts + +**The work.** Group tags into themes that surface the patterns the data reveals. + +**Outputs.** + +- A cluster list (often 6-15 clusters from the 80-150 tags). +- Per-cluster tag membership. +- Per-cluster artifact source list (which artifacts contributed to this cluster). + +**Approach.** + +- Cluster on the underlying observation, not on tag overlap. Two tags that co-occur may not be the same pattern. +- Iterate: first-pass clustering will reveal that some tags belong in multiple clusters; some clusters are too broad; some need to split. +- Use the artifact-source list to test cluster strength. A cluster with 8 supporting artifacts is stronger than one with 2. +- Track the dissent: which clusters have countervailing evidence the synthesis must address. + +**Time investment.** 4-8 hours of clustering work for a batch this size. Often done collaboratively with another reviewer to surface alternative groupings. + +**Common skip-failures.** + +- Clustering on assumed categories rather than emergent themes. +- Stopping at first-pass clustering without iterating. +- Ignoring artifact-source counts (clusters with thin support get weighted equally with strong ones). +- Forcing every tag into a cluster (some tags are noise; that is fine). + +--- + +## Stage 4: Name patterns + +**The work.** Each cluster becomes a named pattern that captures what the underlying observation actually is. + +**Outputs.** + +- A pattern list (typically 4-8 patterns from a strong synthesis). +- Per-pattern name, evidence summary, and source-artifact list. + +**Approach.** + +- Pattern name is specific enough that a reader can guess the implication. +- Pattern names commit a position: name what the data shows, not a category the data sits in. +- Avoid truisms: pattern names that read as something everyone could have said before the research are not patterns. +- Limit pattern count: 4-8 strong patterns serve synthesis better than 15 weak ones. + +**Time investment.** 2-4 hours of pattern-naming work. Often the highest-impact stage; investment in good pattern names pays off in implications and decisions. + +**Common skip-failures.** + +- Pattern names that are category labels (Onboarding, Pricing, Support). +- Pattern names that are truisms (Users want fast performance). +- Hedge-stacked pattern names (Users sometimes seem to occasionally maybe). +- Too many patterns (under-clustering manifests as pattern bloat). + +See `pattern-naming-patterns.md` for detail. + +--- + +## Stage 5: Infer product implications + +**The work.** For each pattern, name what this implies for the product. + +**Outputs.** + +- Per-pattern implication list (often 1-3 implications per pattern). +- Per-implication: specific, falsifiable, cost-acknowledged. + +**Approach.** + +- Each pattern can have multiple implications. Surface the options; do not pre-prioritize. +- Implications are the writer's analytical work, not what users said. Users describe experience; PMs interpret what experience implies. +- Make implications falsifiable. "We should improve onboarding" is not an implication; "Move the third configuration step to after first success state" is. +- Acknowledge cost. Implications that ignore implementation cost produce wishlists. +- Some patterns imply not-acting. Naming the not-act implication is honest synthesis. + +**Time investment.** 3-6 hours of implication work. + +**Common skip-failures.** + +- Vague implications that cannot be acted on or debated. +- Wishlist implications that do not acknowledge cost. +- Skipping the not-act implication when it would be honest. +- Implications that are restatements of the pattern (no analytical bridge). + +See `from-pattern-to-product-implication.md` for detail. + +--- + +## Stage 6: Name the so-what + +**The work.** For each implication, the specific decision it informs. + +**Outputs.** + +- Per-implication so-what statement tied to a real decision. +- An overall recommendation section: what should change as a result of this synthesis. + +**Approach.** + +- Map each implication to a decision the team is making (or should make). +- Be specific: "Should the Q2 roadmap include the onboarding redesign?" rather than "Onboarding should be considered." +- Surface the synthesis's overall recommendation: where to invest, where to deprioritize, where to gather more data before deciding. +- Acknowledge the decisions the synthesis cannot resolve: data gaps, contested patterns, decisions outside the synthesis's scope. + +**Time investment.** 2-4 hours of so-what work. + +**Common skip-failures.** + +- So-whats that are too abstract to drive decisions. +- Skipping the overall recommendation section (each pattern stands alone; the synthesis does not aggregate). +- Buried data gaps (the synthesis presents conclusions where the data did not support them). + +--- + +## Worked example + +A discovery cycle with 12 customer interviews + 250 support tickets + a sales call audit, focused on a possible onboarding redesign. + +**Stage 1 (prep).** 18 hours. Interview transcripts cleaned; ticket dataset extracted; sales call transcripts pulled. + +**Stage 2 (tagging).** 32 hours. 110 tags emerged across the artifacts. Quote pulls captured. + +**Stage 3 (clustering).** 6 hours. Clusters emerged: configuration-step friction, value-state delay, onboarding length, mobile-context onboarding, role-based mismatch, support-deflectable confusion. Six clusters with varying artifact support. + +**Stage 4 (pattern naming).** 3 hours. Six patterns named, including: + +- "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." +- "Free users reach the success state at half the rate of paid users because the configuration burden is the same but the value reveal is gated." +- "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +**Stage 5 (implications).** 4 hours. Per-pattern implications. Example for the configuration-step pattern: + +- Implication: defer configuration step 3 to after first success state, with a "complete your setup" prompt later. +- Cost: medium engineering investment; affects existing flows for users who completed step 3 historically. +- Alternative implication: pre-populate step 3 with sensible defaults from step 2 data where possible. +- Not-act implication: keep the current flow but improve docs (probably insufficient given the friction severity). + +**Stage 6 (so-what).** 3 hours. Decision input: yes, prioritize onboarding redesign in Q2; staged-onboarding approach; mobile parity is a sub-track within the redesign; configuration-step deferral is the headline change. + +**Total synthesis time.** 66 hours over the six stages. Roughly 1.5-2 weeks of focused synthesis work for one PM. + +--- + +## Time-investment patterns + +Synthesis sequences that go shorter than this are usually skipping stages. Sequences that go longer are usually over-investing in tagging or under-deciding in implications. The 60-80 hour range for a substantial discovery synthesis is typical. + +Programs that have not budgeted synthesis time often discover it after research ships and the synthesis stalls. The discipline is budgeting synthesis at the start of the discovery cycle, not as an afterthought. + +--- + +## Methodology-level choices that stay in the public skill + +The six-stage sequence with stage outputs and time investments. The worked example. The non-negotiability of the sequence. Common skip-failures per stage. + +## Implementation choices that stay internal + +Specific transcription tools. Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific document templates per output. Specific time-tracking conventions for synthesis budgeting. These vary by team and tooling. diff --git a/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md b/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md new file mode 100644 index 0000000..b09da20 --- /dev/null +++ b/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md @@ -0,0 +1,140 @@ +# Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. Tagging and clustering done badly produces bad patterns; tagging and clustering done well produces patterns that drive decisions. + +The discipline is in five principles that apply across both stages. + +--- + +## Principle 1: Tag at the artifact level first; do not pre-design the taxonomy + +**The pattern.** Tags emerge from the artifacts. The researcher reads each transcript and tags what is actually there. + +**The anti-pattern.** Researchers arrive at tagging with a pre-built taxonomy: "we will tag for usability, performance, pricing, support." Artifacts get forced into the categories. Patterns the taxonomy did not anticipate get missed. + +**Why pre-built taxonomies fail.** + +- The taxonomy reflects what the team already thinks; tagging confirms what the team already thinks; synthesis does not reveal anything new. +- Artifacts that do not fit the taxonomy categories get skipped or shoehorned in. +- Tags that emerge in the data but were not in the taxonomy do not get captured. + +**The exception.** Some categorical metadata is fine to apply consistently (user segment, source channel, recency). The semantic tagging that drives synthesis should still emerge from the data. + +**The recovery.** Mid-tagging, if the team realizes the pre-built taxonomy is constraining, it can be discarded and tagging restarted with descriptive tags emerging from artifacts. Better to restart than to publish synthesis grounded in a constraining taxonomy. + +--- + +## Principle 2: Allow tag proliferation; collapse later + +**The pattern.** First-pass tagging produces 80-150 tags across a batch. That is correct. Premature consolidation loses distinctions that turn out to matter. + +**The anti-pattern.** Researchers consolidating tags during the tagging stage. "We had four onboarding tags; let me merge them into one." The merge happens before the researcher has seen whether the four tags actually represent different patterns. + +**Why proliferation matters.** + +- Some distinctions only become visible after seeing many artifacts. Two tags that seem similar at artifact 3 may turn out to be different patterns by artifact 12. +- Granular tags can always be collapsed in the clustering stage; collapsed tags cannot be unmerged once the tagging is done. +- Proliferation supports the discovery posture; consolidation supports the confirmation posture. + +**The volume calibration.** A batch of 12 interviews + 250 tickets + 20 sales calls might end with 80-150 tags. Fewer than that often signals premature consolidation; more than that may signal undisciplined tagging. + +--- + +## Principle 3: Cluster on patterns, not on tag overlap + +**The pattern.** Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation, not on statistical co-occurrence. + +**The anti-pattern.** Tools that auto-cluster by co-occurrence. They produce statistical groupings that do not always match the patterns the researcher needs. + +**Why pattern-clustering matters.** + +- "Slow onboarding" and "configuration friction" might co-occur because both are common; that does not mean they are the same pattern. They might be the same (configuration is what makes onboarding feel slow) or different (there is friction in configuration AND there is a perception of length independent of configuration). +- The researcher's interpretation of the artifact-level tags is what surfaces the pattern; tools can suggest groupings but cannot determine them. + +**The work.** For each candidate cluster, ask: are the underlying observations the same, or do they share a tag because the tag was loose? If the latter, split the cluster. + +--- + +## Principle 4: Name the cluster after clustering, not before + +**The pattern.** The cluster name comes from the data after the clustering work is done. + +**The anti-pattern.** Researchers arriving with named clusters and slotting data into them. The clusters become hypothesis-confirmation rather than discovery. + +**Why post-cluster naming matters.** + +- Pre-named clusters bias the clustering: tags get assigned to clusters they fit linguistically rather than substantively. +- Post-cluster naming reveals patterns the team did not anticipate (the highest-value patterns). +- The naming itself is part of the synthesis work; rushing the naming compresses the analytical work into a label without thought. + +**The discipline.** First-pass clustering produces unnamed clusters. The researcher then names each cluster based on what the underlying observations actually show. Names emerge after the clustering, not before. + +--- + +## Principle 5: Tag dissent and contradictions explicitly + +**The pattern.** Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. + +**The anti-pattern.** Tagging only the dominant pattern; ignoring the contradictions; or tagging contradictions but not following them through to clustering and synthesis. + +**Why dissent matters.** + +- Contradictions reveal sub-segments. "Most users find configuration confusing; experienced users find it efficient" might mean the pattern is segment-specific, not universal. +- Contradictions reveal pattern strength. A pattern with no countervailing evidence is suspicious; a pattern with some dissent that the synthesis can explain is stronger. +- Synthesis that ignores dissent reads as researcher confirmation bias. + +**The discipline.** Each major pattern in synthesis has a "but consider" section: contradictions in the data, segment differences, edge cases. The synthesis is more honest with these sections; readers trust patterns that engage their counterevidence. + +--- + +## Tagging tactics that work + +A short list of tactics that improve tagging quality. + +**Read the artifact end-to-end before tagging.** Tagging while reading on first pass produces fragmentary tags. Reading first, then tagging on a second pass, produces tags grounded in the artifact's full context. + +**Tag specific moments, not summaries.** "User struggles" is a summary. "User abandons configuration step 3 because credit card details are not accessible during signup" is a specific moment. Specific moments support stronger pattern naming later. + +**Pull quotes during tagging.** Synthesis output includes evidence; the evidence comes from quotes selected during tagging. Marking quote-worthy moments during tagging prevents re-reading later. + +**Tag motivation alongside behavior.** "User clicked X" is behavior; "User clicked X because they thought it would Y" is motivation. Motivation tags surface what users were trying to accomplish, which informs implications more than behavior alone. + +**Tag emotional valence sparingly.** "User was frustrated" is fine; tagging every artifact for emotional state produces noise. + +--- + +## Clustering tactics that work + +**Iterate clustering at least twice.** First-pass clustering is rough; second-pass clustering refines; third-pass clustering catches what the first two missed. + +**Use artifact-source counts.** A cluster supported by 8 artifacts is stronger than one supported by 2. The source count does not determine pattern importance, but it informs synthesis weighting. + +**Test cluster boundaries.** Take a tag from one cluster and ask: could this fit in another cluster instead? If yes, the cluster boundaries are unclear; refine. + +**Surface the leftovers.** Tags that do not fit any cluster are signal. They might be noise (one-off observations not generalizing). They might be edge-case patterns worth naming separately. They might point to a cluster the researcher missed. + +**Cluster collaboratively where possible.** A second reviewer surfaces alternative groupings the first reviewer did not see. Two reviewers usually produces better clustering than one. + +--- + +## Common tagging-and-clustering failures + +**Tagging by memory, not by reading.** Researchers reading transcripts and then tagging from recall. Loses specifics; produces general tags that cluster poorly. + +**Tag exhaustion.** Researchers running through too many artifacts in one session, tag quality decaying as fatigue sets in. Reduce session length; pace the tagging across days. + +**Confirming the team's prior hypothesis.** Researchers entering tagging with a hypothesis the research is meant to confirm. Tags get assigned to support the hypothesis; counterevidence gets minimized. + +**Cluster collapsing to fit a target count.** Researchers feeling they should have N clusters and forcing the data to that count. Either over-collapsing (losing distinctions) or under-collapsing (preserving noise as signal). + +**Skipping the dissent.** Tagging only the dominant pattern; clustering only the supporting tags. Synthesis publishes patterns without their counterevidence; reviewers later catch the gap. + +--- + +## Methodology-level choices that stay in the public skill + +The five principles (tag at artifact level, allow proliferation, cluster on patterns, name after clustering, tag dissent). The tagging tactics. The clustering tactics. The common failures. + +## Implementation choices that stay internal + +Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific session-length conventions for tagging. Specific reviewer pairings. The team's own conventions for tag-count thresholds. These vary by team and tooling. diff --git a/skills/discovery-research-synthesis/references/when-to-gather-more-data.md b/skills/discovery-research-synthesis/references/when-to-gather-more-data.md new file mode 100644 index 0000000..5ba1b81 --- /dev/null +++ b/skills/discovery-research-synthesis/references/when-to-gather-more-data.md @@ -0,0 +1,212 @@ +# When to gather more data + +Synthesis sometimes reveals that the research did not collect enough. The discipline is naming gaps explicitly and deciding whether to halt synthesis, ship with named gaps, or restart with more research. + +The discomfort of acknowledging gaps is the source of bad synthesis. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals it was not. The discipline is honesty about what the research can and cannot support. + +--- + +## Pattern thinness + +**The signal.** A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. + +**Why it happens.** + +- The discovery cycle had a defined batch size; some patterns emerged with limited support. +- The pattern is real but rare; the research did not encounter enough cases to characterize it. +- The pattern is segment-specific; the research overrepresented other segments. + +**The honest options.** + +- Name the pattern as tentative pending more data. Synthesis ships with this pattern flagged as preliminary; the team treats it as a hypothesis rather than a finding. +- Pause synthesis to gather more research. If the pattern is decision-load-bearing, the additional research investment may be worthwhile. +- Drop the pattern. If the pattern is not decision-relevant or the data is too thin to be useful, do not include it. Inflating thin patterns to fill space is a synthesis failure. + +**The dishonest option to avoid.** Naming the thin pattern as if it had full support. Readers cannot distinguish well-supported from thinly-supported patterns; decisions get made as if all patterns are equal weight; the team gets surprised when the thin-pattern decisions do not pan out. + +--- + +## Segment under-representation + +**The signal.** The research overrepresents one user segment and underrepresents another that matters for the decision. + +**Why it happens.** + +- Recruiting bias produces segment skew (the easiest-to-recruit users are usually a specific segment). +- The research was scoped before the team realized which segments mattered most for the decision. +- Available research artifacts (existing tickets, prior interviews) skew toward certain segments. + +**The honest options.** + +- Synthesize for the represented segment; flag explicitly that the patterns may not apply to underrepresented segments. +- Pause to recruit and conduct research with the underrepresented segment. +- Use existing data sources (analytics, support data) to validate patterns in the underrepresented segment indirectly. + +**Worked example.** A discovery cycle on B2B onboarding interviews 12 users, all from companies of 50-500 employees. The synthesis surfaces strong patterns for that segment. The product team is also considering enterprise (1000+ employees) and small business (1-50). The synthesis should: + +- Name patterns for the 50-500 segment with confidence. +- Acknowledge that enterprise and small business patterns are not represented. +- Recommend either separate research for the missing segments or scoping the decision to the segment the data covered. + +--- + +## Contradictory clusters + +**The signal.** Two clusters point in opposite directions and the data does not resolve the contradiction. + +**Why it happens.** + +- Sub-segment differences the research did not investigate explicitly. +- Different use contexts producing different needs (mobile vs desktop, new vs returning users). +- One cluster reflects what users say; the other reflects what users do; the contradiction is real and revealing. + +**The honest options.** + +- Investigate the contradiction. Often the contradiction itself becomes the most valuable finding: it surfaces a sub-segment or context distinction the team did not anticipate. +- Pause synthesis to gather targeted research that resolves the contradiction. +- Ship synthesis with the contradiction named and the recommendation to gather more data before committing decisions in this area. + +**Worked example.** Interviews with new users surface that they want simpler onboarding. Support tickets from new users in the same week surface frequent requests for more configuration options during onboarding. The contradiction may reveal: + +- New users say "simpler" but mean "fewer required steps before value"; configuration options are fine if not blocking. +- The interview sample skewed casual users; the support tickets came from power users. +- The contradiction needs more investigation before driving onboarding redesign. + +--- + +## Decision time pressure + +**The signal.** Synthesis revealing data gaps but the decision has to ship before more research can happen. + +**Why it happens.** + +- Roadmap commitments do not flex for data gaps. +- The decision is upstream of work that has already been committed. +- The cost of waiting exceeds the value of additional data. + +**The honest path.** + +- Name the data gap explicitly in the synthesis. Do not pretend the gap does not exist. +- Make the recommendation with the gap acknowledged. "Given current data, we recommend X. The gap that may revise this recommendation is Y." +- Plan the follow-up research that would validate or revise the recommendation. +- Build instrumentation that will validate the recommendation post-launch (so the team can detect if the recommendation was wrong). + +**The path to avoid.** Pretending the data is sufficient when it is not. Synthesis under time pressure that treats partial data as complete data produces decisions the team will not be able to recover from cleanly when the gap surfaces later. + +--- + +## The "we have enough" trap + +**The pattern.** Teams that have invested in research want to declare the data sufficient even when the synthesis reveals gaps. + +**Why it happens.** + +- Sunk-cost reasoning: the team has spent the research budget; restarting feels like waste. +- Timeline pressure: the research was scheduled before synthesis; more research means schedule slip. +- Status concerns: declaring the research insufficient feels like admitting the discovery work was inadequate. + +**Why it produces bad synthesis.** + +- The data gaps still exist whether or not the team acknowledges them. Decisions made on incomplete data still suffer from the incompleteness. +- Synthesis that papers over gaps trains the team to treat synthesis as performative rather than load-bearing. +- The next discovery cycle will repeat the same scoping mistakes because the team did not name them honestly. + +**The discipline.** + +- Naming gaps is the synthesis owner's job. The team relies on the synthesis owner to be honest about what the research can and cannot support. +- The cost of naming gaps is short-term discomfort; the cost of pretending they do not exist is bad decisions. +- "We have enough" should be the conclusion of synthesis review, not the assumption. + +--- + +## When more research is the right call + +**The criteria.** + +- The decision is load-bearing for product direction. +- The gap is large enough that synthesis would be misleading without addressing it. +- The cost of additional research is bounded and feasible. +- The cost of deciding now and being wrong is high. + +**Examples that warrant more research.** + +- A pricing decision where current research underrepresents the segment that drives revenue. +- An onboarding redesign where the synthesis cannot distinguish what new users want from what they need. +- A positioning shift where existing-customer voice is in the data but prospect voice is missing. + +**Examples that do not warrant more research.** + +- Minor decisions where the gap's resolution would not change the recommendation materially. +- Decisions where the cost of waiting exceeds the value of additional data. +- Decisions that can be reversed easily based on post-launch data. + +--- + +## When to ship synthesis with named gaps + +**The criteria.** + +- Decision time pressure makes more research infeasible. +- The gap is named honestly so the team can weigh the recommendation accordingly. +- Post-launch instrumentation will detect if the recommendation was wrong. + +**The discipline.** + +- The named gap is in the synthesis prominently, not buried. +- The recommendation acknowledges what the gap might change. +- The follow-up research plan is specific and committed. + +**Worked example.** "Recommendation: prioritize the onboarding redesign in Q2. Caveat: our research underrepresents enterprise users; if enterprise represents a significant share of new signups, the redesign should include enterprise-specific paths we have not validated. Follow-up: enterprise-specific user research in Q1 to validate the redesign approach for that segment before Q2 ships." + +--- + +## When to drop the pattern entirely + +**The criteria.** + +- The supporting data is too thin to commit a position even tentatively. +- The pattern, if false, would mislead the team in directions hard to recover from. +- The pattern is not load-bearing for the synthesis's primary recommendations. + +**The discipline.** + +- Some thin patterns warrant dropping rather than flagging. Not every observation needs to make it into the synthesis. +- Dropping is honest synthesis; inflating is not. + +--- + +## Common gather-more-data failures + +**Inflating thin patterns.** Patterns supported by 2 artifacts presented as if supported by 12. Readers cannot distinguish strength. + +**Hiding segment gaps.** Synthesis presents recommendations as universal when they apply only to the segment researched. + +**Pretending contradictions resolved.** Synthesis writes around the contradiction rather than naming it; readers later discover it on their own. + +**Decision-pressure denial.** Synthesis treats time pressure as if it makes data complete. The decision is made; the wrong-decision cost is paid later. + +**The "we have enough" trap.** Sunk cost and status protect the synthesis from honest gap-naming. + +**Endless research.** The opposite failure: every gap triggers more research; synthesis never ships; the team paralyzes on data-gathering. + +--- + +## The data-sufficiency calibration + +A short framework. + +1. **Is the gap load-bearing for the recommendations?** If yes, address it. If no, name and proceed. +2. **Is more research feasible within the decision timeline?** If yes, gather. If no, ship with named gaps. +3. **Can post-launch instrumentation catch wrong decisions?** If yes, ship-with-instrumentation is reasonable. If no, more caution warranted. +4. **What is the cost of being wrong vs cost of waiting?** Compare; choose the lower-cost path. +5. **Is the team's commitment to follow-up research credible?** If named gaps will trigger real follow-up, ship-with-gaps works. If named gaps will be ignored, gather now. + +--- + +## Methodology-level choices that stay in the public skill + +The pattern thinness signal. Segment under-representation. Contradictory clusters. Decision time pressure. The we-have-enough trap. When more research is and is not the right call. When to ship with named gaps. When to drop patterns. Common gather-more-data failures. The data-sufficiency calibration. + +## Implementation choices that stay internal + +Specific recruiting pipelines for follow-up research. Specific instrumentation for post-launch validation. Specific synthesis-revision workflows when gaps are named. The team's own conventions for "thin pattern" thresholds. These vary by team. diff --git a/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md b/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md new file mode 100644 index 0000000..6291907 --- /dev/null +++ b/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md @@ -0,0 +1,207 @@ +# Writing for decisions, not decks + +Synthesis output should be optimized for decision use, not for presentation. The format choice (document vs deck), the structure (patterns lead, evidence appendix), the voice (opinionated), and the closing (decision input section) compose to produce synthesis the team actually references. + +--- + +## Document, not deck + +**The principle.** Deck format is poor for synthesis. + +**Why decks fail.** + +- Slides cannot carry argument density. A pattern, its evidence summary, its implications, and its decision input do not fit on one slide; spreading them across slides loses coherence. +- Readers cannot reference slides later. A pattern needs to be findable; decks decay into icons and bullet points that are hard to search and cite. +- Decks are presentation artifacts; synthesis needs to be a reference artifact that the team uses for months. +- The deck format encourages summarization that loses precision. + +**Why documents work.** + +- A 4-12 page document can carry the pattern, evidence, implications, and decision input in connected prose. +- Documents are searchable, linkable, and citable. +- Documents accommodate density without overwhelming; readers can scan headings and dive into sections. +- Documents read as load-bearing analytical work; decks read as presentation. + +**The exception.** A short executive summary deck (5-8 slides) can pair with a substantive document. The deck summarizes; the document carries the work. + +**The discipline.** If the synthesis is being optimized for a single 30-minute readout meeting, the format will fail when the team needs to reference the synthesis in week 6 of execution. Optimize for the reference use, not the presentation moment. + +--- + +## Lead with patterns and implications; relegate evidence to appendix + +**The principle.** Readers scanning for decision input want patterns and implications first. + +**The reader's question.** "What does this synthesis tell me to do?" Patterns and implications answer it. Evidence supports the answer but is not the answer. + +**The structure that works.** + +- Executive summary (1 page): the patterns, the recommendations, the decision input. +- Pattern sections (1-3 pages per pattern): pattern name, evidence summary in 2-3 sentences, implications, decision input. +- Recommendations section (1 page): overall synthesis recommendation; what should change. +- Appendix: detailed evidence, quote pulls, methodology notes, full transcripts or links to them. + +**The structure that fails.** + +- Decks that lead with quote walls. Readers admire the quotes; they do not extract decisions. +- Documents that bury the patterns under methodology and background. Readers stop reading before reaching the patterns. +- Synthesis that mixes evidence and analysis throughout. Readers cannot tell where observation ends and recommendation begins. + +**The discipline.** Each pattern section is short (2-4 paragraphs of synthesis text); evidence linked or summarized briefly; the appendix is where evidence depth lives. Readers who want depth follow the link; readers who want decisions stay in the body. + +--- + +## One section per pattern, parallel structure + +**The principle.** Synthesis with 4-8 patterns has 4-8 parallel sections, each with the same structure. + +**Per-section structure.** + +- Pattern name (the heading). +- Evidence summary (2-3 sentences naming the artifacts and the dominant signals). +- Implication (1-3 implications with cost notes). +- Decision input (specific decision the implication informs). + +**Why parallel structure works.** + +- Readers learn the structure from the first section and can scan subsequent ones. +- Comparison across patterns is easier when each is presented the same way. +- Editing for completeness is easier (each section either has the elements or it does not). + +**The variation.** Some patterns warrant longer treatment (richer evidence, more complex implications); some are shorter. Length variation is fine; structural variation is not. + +--- + +## Be opinionated + +**The principle.** Synthesis that hedges every pattern reads as a researcher avoiding accountability. + +**Hedged synthesis.** + +- "Users may sometimes occasionally seem to indicate possible difficulty." +- "It might be considered to potentially explore some adjustments." +- "There could be benefits to investigating opportunities." + +These commit nothing. Readers cannot debate or decide on hedged synthesis. + +**Opinionated synthesis.** + +- "Users abandon configuration step 3 in 40% of signup attempts because credit card details are not accessible at signup." +- "The Q2 roadmap should prioritize the onboarding redesign over the dashboard expansion." +- "The not-act recommendation is to defer enterprise admin controls until small-team segment growth stabilizes." + +These commit positions. Readers can disagree; disagreement produces decisions. + +**The discipline.** Write synthesis as a recommendation. The PM doing synthesis is making analytical claims; readers may push back, but pushback is the point. Hedging avoids pushback by avoiding claim. + +**The exception for honest uncertainty.** When the data genuinely does not support a position, name the uncertainty explicitly: "The evidence supports two possible interpretations; we recommend gathering more data before deciding." This is honest uncertainty, not hedging. Hedging is dressing up uncertainty as if it were synthesis. + +--- + +## Include a decision-input section + +**The principle.** What does this synthesis recommend the team do? + +**The section's role.** The decision-input section connects the synthesis to the team's prioritization work. Without it, the synthesis presents patterns and implications but does not aggregate them into recommendations. + +**What the section addresses.** + +- Where should priorities shift based on this synthesis? +- Which roadmap items does the synthesis validate? Which does it challenge? +- Which decisions can the team make now with this synthesis as input? +- Which decisions need more research before making? +- What is the synthesis's overall view of where the product should focus? + +**The section's voice.** Direct, specific, opinionated. The team can disagree, but the section should commit a recommendation. + +**The discipline.** Without this section, synthesis is a collection of patterns; with this section, synthesis is decision input. The section is what makes the synthesis load-bearing for the team's strategic work. + +--- + +## Length calibration + +**The principle.** Synthesis should be as short as possible without losing the load-bearing content. + +**Typical lengths.** + +- Discovery cycle synthesis from a meaningful research batch: 6-12 pages. +- Smaller-scale synthesis from a single research type (e.g., support audit alone): 3-6 pages. +- Quick-turn synthesis from a focused interview batch: 2-4 pages. + +**Length anti-patterns.** + +- Synthesis padded to 30+ pages. Readers stop reading; the load-bearing content gets lost. +- Synthesis compressed to 1 page. Density too high; specifics get lost. +- Synthesis stretched across multiple documents without clear primacy. Readers do not know which document is the synthesis. + +**The discipline.** Edit for length. Each pattern section should be tight; each implication should be specific; the recommendation should be concise. Readers will engage with a 6-page synthesis they can finish in 20 minutes; readers will skim a 30-page synthesis and miss the recommendations. + +--- + +## The reference-after-shipping test + +**The principle.** Synthesis that gets referenced months after publication has earned its keep. + +**The test.** Six months after a synthesis ships, can the team: + +- Name the patterns the synthesis surfaced? +- Cite the synthesis in roadmap discussions? +- Use the synthesis as input for related decisions that came up after publication? + +**Failures the test reveals.** + +- Synthesis nobody can name suggests insight-theater (presented but not absorbed). +- Synthesis nobody references suggests document-shelf-syndrome (filed away after readout). +- Synthesis the team contradicts in later decisions suggests the synthesis was not load-bearing in their actual prioritization work. + +**Recovery.** When prior synthesis fails the test, the next synthesis should adjust: shorter, more opinionated, more directly tied to specific decisions. Each round of synthesis should be more usable than the prior. + +--- + +## Visual elements in synthesis documents + +**The discipline.** Visuals should carry argumentative load the prose alone cannot. + +**Visuals that work.** + +- A pattern-to-implication-to-decision diagram showing how the synthesis connects to product work. +- A frequency chart for patterns supported by quantitative data. +- A segment comparison table where patterns differ across segments. +- An evidence map showing artifact-source distribution per pattern. + +**Visuals that fail.** + +- Stock images decorating section breaks. +- Quote walls without context. +- Word clouds (rarely informative). +- Persona illustrations (decorative; not synthesis output). + +**The frequency.** Visual elements every 2-3 pages of synthesis is typical. More than that risks decoration; fewer is fine if the prose carries the work. + +--- + +## Common synthesis-writing failures + +**Format choice.** Deck instead of document; the synthesis decays into bullets that lose precision. + +**Buried recommendations.** Patterns are clear; the recommendation is one sentence on page 11. Readers miss it. + +**Hedge-stacking.** Every claim caveated; readers cannot extract a position. + +**No decision-input section.** Synthesis presents patterns; team has to aggregate them into decisions on their own; usually does not. + +**Length excess.** 30 pages of synthesis where 8 would have served. Readers skim; load-bearing content gets lost. + +**Length compression.** 1 page of synthesis where 6 were needed. Density too high; specifics lost. + +**Quote-wall presentation.** Evidence dominates; analysis recedes; readers admire the quotes and miss the synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The document-not-deck principle. The patterns-lead-evidence-appendix structure. The parallel-section discipline. The opinionated voice. The decision-input section. Length calibration. The reference-after-shipping test. Visual element discipline. Common failures. + +## Implementation choices that stay internal + +Specific document templates and styles. Specific document hosting (Notion, Coda, Google Docs, Confluence). Specific link conventions for evidence. Specific reviewer workflows. Specific archive practices. The team's own conventions for synthesis length within the bands. These vary by team and tooling. diff --git a/skills/documentation-strategy/SKILL.md b/skills/documentation-strategy/SKILL.md new file mode 100644 index 0000000..1b65361 --- /dev/null +++ b/skills/documentation-strategy/SKILL.md @@ -0,0 +1,428 @@ +--- +name: documentation-strategy +description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long." +category: process-and-team +catalog_summary: "Documentation systems, what to document, maintenance cadence" +display_order: 2 +--- + +# Documentation Strategy + +Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases. + +--- + +## When to use + +- Setting up documentation for a new team or product +- Auditing existing documentation +- Fixing stale or scattered docs +- Choosing a documentation tool or platform +- Defining what gets documented and what doesn't +- Establishing maintenance cadence +- Scoping technical writing work +- Designing onboarding documentation (use alongside `team-onboarding-playbook`) + +## When NOT to use + +- Writing the actual content of a single document (use `content-and-copy`) +- Customer-facing knowledge base copy (use `content-strategy`) +- Code comments and inline documentation (covered by `code-review-web`) +- One-off blog posts or articles (use `content-and-copy`) + +--- + +## Required inputs + +- The audience (internal, external, customer, dev, exec) +- Existing docs and their state (where, what shape, last updated) +- Team size and growth trajectory +- The kinds of work that produce documentation (engineering, product, ops, support) +- Tools currently in use + +--- + +## The framework: 4 categories of documentation + +Different categories of doc serve different purposes. Conflating them is how docs get bad. + +### Category 1: Reference + +What things are. Looked up when needed. + +Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries. + +Properties: +- Comprehensive +- Fact-checked, kept accurate +- Searchable +- Stable structure (links don't break) +- Version-aware where relevant + +### Category 2: How-to + +How to do specific tasks. Procedural. + +Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill." + +Properties: +- Step-by-step +- Tested by someone who didn't write it +- Includes the prerequisites +- Includes troubleshooting +- Versioned to the system it documents + +### Category 3: Explanation + +Why things are the way they are. Conceptual. + +Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents. + +Properties: +- Narrative +- Captures context (the why) +- Often historical (why we built it this way) +- Links to evidence + +### Category 4: Tutorial + +Learning-oriented. Walks someone from zero to capable. + +Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways. + +Properties: +- Sequenced from simple to complex +- Hands-on +- Doesn't assume prior knowledge in scope +- Has clear completion criteria + +(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.) + +--- + +## The framework: 5 tiers of doc + +Different docs serve different audiences with different stakes. + +### Tier 1: Customer-facing + +Public docs, customer KBs, API references. High visibility, slow change. + +Standards: +- Editorial review +- Version control +- Clear ownership +- High freshness bar +- Tied to release + +### Tier 2: Cross-team / shared + +Docs used across teams: shared APIs, common services, company-wide processes. + +Standards: +- Cross-team ownership clear +- Update obligations on changes +- Mid-to-high freshness bar + +### Tier 3: Team-internal + +Docs for the team that owns them: how the team works, runbooks, decisions. + +Standards: +- Team-owned, team-maintained +- Mid freshness bar +- Useful for the next person joining + +### Tier 4: Personal scratchpad + +Notes, drafts, work-in-progress. Not for others. + +Standards: +- Low maintenance +- Don't link from official docs +- Promote to higher tier when valuable + +### Tier 5: Auto-generated + +Docs derived from code: API references generated from comments, schemas, etc. + +Standards: +- Generation is automated, runs in CI +- Single source of truth (the code) +- Reviewed for usability, not freshness (that's automatic) + +The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable. + +--- + +## Workflow + +### Step 1: Audit current state + +- What docs exist? +- Where do they live? (often: scattered) +- Who owns each? +- How fresh are they? +- Are they actually used? (check page views or referrals if measurable) + +The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize. + +### Step 2: Categorize and tier + +For each doc: +- Category (reference / how-to / explanation / tutorial) +- Tier (customer / shared / team / scratchpad / generated) + +Some docs are mixed. Note the dominant category. + +### Step 3: Identify gaps + +What documentation does the team need that doesn't exist? + +Common gaps: +- "How does X actually work?" no answer +- Onboarding for the role no one's onboarded recently +- Runbook for a system that's never broken (yet) +- Decision rationale for "why are we doing it this way" + +Ask people what they wish were documented. They know. + +### Step 4: Identify dead weight + +Docs that are: +- Out of date and not getting updated +- Duplicated across places (one is canonical, others should redirect or be deleted) +- About things that no longer exist +- Drafts abandoned long ago + +Delete or archive. Stale docs are worse than missing docs (people might trust them). + +### Step 5: Pick the home(s) + +Where docs live affects whether they're maintained. + +Common locations: +- **Code repo (markdown):** for docs tightly coupled to code (READMEs, ADRs, runbooks for the service) +- **Wiki / Notion / Confluence:** for cross-team and team-internal +- **Docs site (Docusaurus, Mintlify, custom):** for customer-facing +- **Tickets / decision logs:** for ephemeral records + +Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?" + +### Step 6: Establish ownership + +Every doc has an owner. Without an owner, it goes stale. + +Owner can be: +- A team +- A role (the on-call rotation, the PM, the EM) +- A person, with a backup + +If an owner isn't obvious, the doc may not deserve to exist. + +### Step 7: Establish maintenance cadence + +Per tier: + +| Tier | Review cadence | +|---|---| +| Customer-facing | Per release, plus quarterly | +| Cross-team | Quarterly | +| Team-internal | Quarterly | +| Personal scratchpad | None | +| Auto-generated | On every change | + +Maintenance includes: +- Verify accuracy +- Update for changed systems +- Archive what's no longer relevant +- Address user feedback + +### Step 8: Make doc updates part of work + +Documentation isn't a separate project. It's part of the work that produces it. + +- New feature: docs are part of the feature +- New process: doc is part of the rollout +- Decision made: ADR or decision-log entry filed +- Bug postmortem: runbook updated +- New hire: onboarding doc updated based on their experience + +The team that ships features without docs has less than they think they have. + +### Step 9: Make docs discoverable + +Even great docs are useless if no one finds them. + +- Search that actually works (most platforms; some better than others) +- Index pages for major topics +- Cross-links between related docs +- Search aliases for common alternative phrasings +- Pinning the most-used docs + +### Step 10: Measure + +What's measurable depends on the platform: +- Page views +- Search queries (and zero-result queries) +- "Was this helpful?" feedback +- Time on page +- Referral patterns + +For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear). + +--- + +## Specific patterns + +### README per project + +Every code repo has a README that answers: +- What is this? +- How do I run it? +- How do I contribute? +- Where do I find more info? + +Five sentences each, often. Length isn't the goal. The READ-it-ME promise is. + +### ADR (Architecture Decision Record) + +Per significant decision: + +``` +# ADR-NNN: [Title] + +Status: [Proposed / Accepted / Deprecated / Superseded] +Date: [Date] + +## Context +[What's the situation? What forces are at play?] + +## Decision +[What was decided?] + +## Consequences +[What happens because of this decision? Both good and bad.] +``` + +ADRs accumulate. They become the explanation layer for "why are we doing it this way." + +### Runbook + +Per system: +- What it is +- How to access it +- Common operations (with commands) +- Common failure modes +- Restore from backup procedure +- Escalation contacts + +See `incident-response` and `backup-and-disaster-recovery` for runbook standards. + +### Onboarding pathway + +Per role: +- Day 1 +- Week 1 +- Month 1 +- 90 days + +See `team-onboarding-playbook`. + +### Decision log + +Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony. + +### Glossary + +Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later). + +--- + +## Tooling + +The tool is less important than the discipline. That said: + +| Tool category | Examples | Best for | +|---|---|---| +| Wiki | Notion, Confluence, GitBook | Cross-team, internal | +| Markdown in code | GitHub, GitLab, Bitbucket | READMEs, ADRs, technical | +| Docs sites | Docusaurus, Mintlify, ReadMe | Customer-facing, public docs | +| Internal sites | MkDocs, custom | Team-specific patterns | + +Considerations: +- Search quality (a poor search makes everything worse) +- Editor quality (people won't write in painful editors) +- Version control (can you see history?) +- Permissions (right people can read and write) +- API and integration (for automation) +- Cost at your scale + +For small teams: a single wiki tool is plenty. For larger: tiered tools. + +--- + +## AI-related notes + +LLMs and AI assistants increasingly read documentation. Some considerations: + +- Clear, consistent structure helps both humans and AI +- A glossary of terms helps both +- File-level metadata (front matter) helps tools +- Public docs may be read by AI crawlers; consider an `llms.txt` if relevant +- AI-generated drafts are a starting point, not a final answer; humans review + +--- + +## Failure patterns + +**Documentation as a "later" task.** Always written later. Later means never. Make docs part of the work. + +**One mega-doc for everything.** Wiki page that's 8,000 words. No one reads it. Break by category and topic. + +**Stale docs that nobody trusts.** "Probably out of date" is the thought that kills documentation. Either keep current or archive. + +**Docs everyone agrees should exist but no one writes.** The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific. + +**Wikis that are graveyards.** Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set. + +**Docs separated from code.** API docs in a wiki, code in a repo. They drift. Co-locate. + +**Docs without examples.** Reference without examples is hard to use. Examples make it concrete. + +**Examples that don't run.** Code examples that worked once, drifted. Test examples in CI where possible. + +**Long-form when reference would do.** A 2,000-word doc explaining what a 30-row table would. Use the right form. + +**Multiple sources of truth.** Same info in three places, all slightly different. Pick canonical, redirect others. + +**Doc tools no one uses.** Adopted because of a feature; team doesn't actually use it. Pick tools the team will use. + +**Doc style guide that's longer than the docs.** Process beats product. Guide should be short. + +**No way to mark docs as deprecated.** Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status. + +**No analytics.** No idea what's being used or what's missing. Even basic page views inform priorities. + +**Docs that read like specifications.** Dense, formal, hard to scan. Write for the reader. + +--- + +## Output format + +A documentation strategy document includes: + +- **Audit:** what exists, where, in what state +- **Tiering and categorization:** the framework applied to existing docs +- **Gap list:** what should exist but doesn't +- **Tool decisions:** where each kind of doc lives +- **Ownership map:** who owns what +- **Maintenance cadence:** what's reviewed when +- **Style guide (brief):** consistency standards +- **Roadmap:** prioritized work to fill gaps and close out dead weight + +--- + +## Reference files + +- [`references/doc-types-guide.md`](references/doc-types-guide.md): Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each. diff --git a/skills/documentation-strategy/references/doc-types-guide.md b/skills/documentation-strategy/references/doc-types-guide.md new file mode 100644 index 0000000..badadbf --- /dev/null +++ b/skills/documentation-strategy/references/doc-types-guide.md @@ -0,0 +1,451 @@ +# Doc Types Guide + +The four categories of documentation, what each is for, and a template for each. Based on the Diátaxis framework (well-known in technical writing). + +The categories aren't interchangeable. Mixing them is the most common failure in documentation: a "tutorial" that's actually reference, a "how-to" that's secretly explanation, a "reference" that meanders into tutorial territory. + +--- + +## The four types + +| Type | Purpose | Reader needs | Style | +|---|---|---|---| +| Reference | Look up facts | "What is the value of X?" | Comprehensive, terse | +| How-to | Solve a specific problem | "How do I do Y?" | Step-by-step, focused | +| Explanation | Understand the why | "Why does Z work this way?" | Discursive, narrative | +| Tutorial | Learn from zero | "How do I get started?" | Hands-on, sequenced | + +A useful diagram of how they relate: + +``` + Practical (action) + | + HOW-TO ───────────|─────────── REFERENCE + | + | + Theoretical (understanding) + | + TUTORIAL ───────────|─────────── EXPLANATION + | + Study (acquiring skill) Work (applying skill) +``` + +- Tutorial and how-to are practical (the reader is doing something) +- Reference and explanation are theoretical (the reader is understanding something) +- Tutorial and explanation are study-oriented (acquiring skill or understanding) +- How-to and reference are work-oriented (applying skill) + +--- + +## Reference + +### What it is + +The complete catalog of facts about something. Looked up when needed. + +### Examples + +- API reference (every endpoint, every parameter, every response) +- Configuration options (every flag, every default, every effect) +- Glossary (every term, definition) +- Error code catalog +- Component library docs + +### What makes it good + +- Comprehensive (covers everything) +- Accurate (verified against the actual system) +- Consistently structured (each entry follows the same pattern) +- Searchable (people find what they need quickly) +- Stable links (entries don't move or disappear without redirects) + +### What makes it bad + +- Editorializing ("This is the best way...") +- Tutorials interleaved (reader looking up a fact gets a wall of explanation) +- Inconsistent depth (some entries thorough, others sparse) +- Out of date (single most common reference failure) + +### Template + +``` +# [Function / Endpoint / Setting / Term] + +**Type:** [function / endpoint / configuration / etc.] +**Since:** [version introduced] +**Status:** [stable / beta / deprecated] + +## Description + +[1-2 sentences. What this is.] + +## [Parameters / Inputs / Properties] + +| Name | Type | Default | Description | +|---|---|---|---| +| [name] | [type] | [default] | [description] | + +## [Returns / Output] + +[Description of return value or output.] + +## Examples + +[Minimum useful example.] + +## Notes + +- [Edge case] +- [Gotcha] +- [Related: link to related reference] +``` + +--- + +## How-to + +### What it is + +A guide to accomplishing a specific task. The reader has a problem; the how-to gives the solution. + +### Examples + +- "How to deploy to production" +- "How to reset a forgotten password" +- "How to add a new locale" +- "How to migrate data from system A to system B" + +### What makes it good + +- Goal-oriented (solves a specific problem) +- Sequential (steps in order) +- Tested (someone other than the author followed it) +- Includes prerequisites +- Includes troubleshooting for known issues +- Realistic (uses real values, not placeholders that confuse) + +### What makes it bad + +- Mixed with explanation (the reader wants to act, not understand the design) +- Too generic (steps don't apply cleanly to the actual situation) +- Out of date (commands no longer work) +- Missing prerequisites (reader gets stuck on step 2 because of an unstated dependency) +- Too many branches ("If X then..., else if Y then..."; usually means it should be split into multiple how-tos) + +### Template + +``` +# How to [Specific Task] + +## Goal + +[1 sentence: what the reader will accomplish.] + +## Before you start + +- [Prerequisite 1] +- [Prerequisite 2] +- [Prerequisite 3] + +## Steps + +### 1. [First step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 2. [Second step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 3. [Third step] + +[...] + +## Verify + +[How to confirm the task succeeded.] + +## Troubleshooting + +**Problem: [Common issue]** + +[Cause and resolution.] + +**Problem: [Common issue]** + +[Cause and resolution.] + +## See also + +- [Related how-to] +- [Related reference] +``` + +--- + +## Explanation + +### What it is + +The why. Discursive. Helps the reader understand the design, the rationale, the tradeoffs. + +### Examples + +- Architecture documents +- Design rationale +- Decision records (ADRs) +- "Why we don't support feature X" +- Strategy documents +- Conceptual overviews + +### What makes it good + +- Captures the why (not just the what) +- Honest about tradeoffs (every design choice has a cost) +- Includes alternatives considered +- Time-stamped (so readers know when this was true) +- Connects to other concepts + +### What makes it bad + +- Lecture-y (reader feels talked down to) +- Ahistorical (no context of why decisions were made) +- Marketing voice (everything is "great" and "exciting") +- Buried in how-to (reader is trying to do something; explanation slows them down) + +### Template (ADR specifically) + +``` +# ADR-NNN: [Title of decision] + +**Status:** [Proposed / Accepted / Deprecated / Superseded by ADR-MMM] +**Date:** [YYYY-MM-DD] +**Deciders:** [Who was involved] + +## Context + +[What's the situation? What's the problem? What forces are at play?] + +[Include enough context that a reader new to this can understand. Don't assume the present-day context will be obvious in the future.] + +## Decision + +[What was decided. State it clearly.] + +## Alternatives considered + +### Alternative A: [Name] + +[Description, why not chosen.] + +### Alternative B: [Name] + +[Description, why not chosen.] + +## Consequences + +### Positive + +- [What's better as a result] +- [What's better as a result] + +### Negative + +- [What's worse or constrained as a result] +- [What's worse or constrained as a result] + +### Neutral / mixed + +- [Tradeoffs that aren't clearly good or bad] + +## Notes + +[Anything else relevant. Links to discussion threads, prototypes, related decisions.] +``` + +### Template (general explanation doc) + +``` +# [Topic] + +## What this is + +[2-3 sentences orienting the reader.] + +## Background + +[The context. What was true before. Why this came up.] + +## How it works + +[The substance. Walk through the design, the model, the structure. Use diagrams.] + +## Why this approach + +[The rationale. What we considered. What we chose and why.] + +## Tradeoffs + +[Honest accounting of what's good and bad about this approach.] + +## See also + +[Related explanation, related decisions, related reference.] +``` + +--- + +## Tutorial + +### What it is + +Learning by doing. The reader starts with no knowledge of the topic and finishes capable of using it. + +### Examples + +- "Getting started with our SDK" +- "Your first deployment" +- Onboarding pathways for new team members +- "Building your first integration" + +### What makes it good + +- Sequenced from simple to complex +- Hands-on (the reader does things, not just reads) +- Concrete (real values, real commands, real outcomes) +- Has clear completion criteria +- Builds on a single thread (one project, one example) +- Acknowledges where the reader is (beginner) + +### What makes it bad + +- Reference dressed up as tutorial (no thread, no completion) +- Skips steps "for brevity" (reader gets stuck) +- Uses placeholders like `<your-value-here>` without making them concrete +- Assumes prior knowledge that wasn't stated as prerequisite +- Branches early ("if you want X, do this; if Y, do this") instead of staying focused + +### Template + +``` +# Getting started with [Thing] + +## What you'll build + +[1-2 sentences describing the end state. Maybe a screenshot or example output.] + +## Time required + +[Realistic estimate, e.g. "30-45 minutes"] + +## Before you start + +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] + +## Step 1: [First milestone] + +[Plain-English description of what we're doing in this step.] + +[Concrete instructions:] + +``` +[Specific command] +``` + +[What you should see:] + +``` +[Expected output] +``` + +If something different happens, see [Troubleshooting section]. + +## Step 2: [Second milestone] + +[Same pattern.] + +## Step 3: [Third milestone] + +[Same pattern.] + +[...] + +## What you've built + +[Recap. The reader should feel: I get it now.] + +## Where to go next + +- [Next tutorial] +- [Reference for what you just used] +- [How-to for related task] + +## Troubleshooting + +**[Specific problem someone might hit]** + +[Cause and resolution.] +``` + +--- + +## How to use this in practice + +### When writing new docs + +Identify which type before starting. Don't mix. + +If a doc has tutorial sections AND reference sections AND explanation sections, it's three docs. Split. + +### When auditing existing docs + +For each existing doc, ask: which type is this trying to be? + +If it's mixed, split. The split is usually: keep the dominant type in the original, link to the other types. + +### When linking between types + +The four types reinforce each other: +- Tutorials link to reference for the things they introduce +- How-tos link to reference for the commands they use +- Reference links to explanation for the why +- Explanation links to how-to for "to do this, see..." + +A connected web of all four serves the reader well. + +### When choosing the type for a need + +| Reader is asking | Type | +|---|---| +| "What does X mean?" | Reference | +| "What's the syntax for X?" | Reference | +| "How do I do Y?" | How-to | +| "How do I solve [specific problem]?" | How-to | +| "Why does Z work this way?" | Explanation | +| "What did we decide about W?" | Explanation (ADR) | +| "I'm new; where do I start?" | Tutorial | + +If the answer is "all of the above," the reader actually needs multiple docs, not one mega-doc. + +--- + +## Anti-patterns to recognize + +- **The "everything" doc:** tries to be all four types. Reads like all four poorly. +- **The "guide" doc:** vague title, vague purpose. Often a how-to that lost focus. +- **The "manual" doc:** monolithic. Unmaintainable. Split. +- **The "wiki page that became sacred:** historical accumulation. Past usefulness. Audit and split or archive. diff --git a/skills/domain-strategy/SKILL.md b/skills/domain-strategy/SKILL.md new file mode 100644 index 0000000..568e44d --- /dev/null +++ b/skills/domain-strategy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: domain-strategy +description: "Plan, manage, and optimize a domain portfolio. Use this skill for DNS architecture decisions, redirect strategies, registrar choice, parking unused domains, multi-site setups, and domain consolidation or split planning. Triggers on DNS, domain, registrar, redirect, parking, subdomain, apex, www vs non-www, multi-site, portfolio, hreflang setup, domain migration. Also triggers when planning a new site that needs domain decisions made before launch." +category: operations +catalog_summary: "DNS architecture, redirects, registrars, multi-domain portfolios" +display_order: 4 +--- + +# Domain Strategy + +Decide how domains, subdomains, and DNS work across a portfolio. Stack-agnostic. Works for one site or one hundred. + +--- + +## When to use + +- Setting up DNS for a new site (apex vs www, primary vs aliases) +- Choosing or switching registrars +- Planning redirects across multiple domains (parked, retired, consolidated) +- Deciding subdomain vs subfolder vs separate domain for a new product line +- Consolidating multiple sites into one +- Splitting one site into multiple +- Setting up DNS for email, security records, third-party services + +## When NOT to use + +- Migrating content between platforms with URL changes (use `content-migration`) +- Email authentication setup specifically (use `email-deliverability`) +- Security headers or HTTPS config (use `security-baseline`) +- Internationalization domain choices (use `internationalization`) + +--- + +## Required inputs + +- Current domain inventory (every domain you own or operate) +- Status of each (live, parked, redirected, retired) +- Strategic role of each (primary brand, sub-brand, defensive registration, campaign) +- Current DNS provider and registrar for each +- Email and third-party service dependencies + +--- + +## The framework: 5 decisions + +Every domain decision falls into one of these buckets. Address them in order. + +### Decision 1: Apex vs www as canonical + +Pick one. Redirect the other to it. Pick before launch. Changing later is painful. + +- **Apex (example.com):** cleaner, more memorable, the modern default. +- **www (www.example.com):** historically standard, easier to add CDN-level CNAME records (apex CNAME is technically forbidden but most providers offer ALIAS or ANAME). + +Whichever you pick, the other must 301 to it. Both serving content is duplicate content and a soft signal of poor setup. + +### Decision 2: Subdomain vs subfolder vs separate domain + +For a new product, blog, or content section: + +| Pattern | Use when | +|---|---| +| Subfolder (`example.com/blog`) | Same brand, want SEO equity to flow, default choice | +| Subdomain (`blog.example.com`) | Different stack or platform, organizationally separate but related | +| Separate domain (`exampleblog.com`) | Different brand, different audience, intentional separation | + +Default to subfolder. The case for subdomain or separate domain has to be made. + +### Decision 3: Registrar strategy + +The registrar is where the domain is registered. The DNS provider is where DNS records live. They can be the same or different. + +Decisions: +- **Single registrar vs multiple:** single is simpler. Multiple makes sense for redundancy at scale. +- **Lock and 2FA:** non-negotiable. Domain hijacking is real and costly. +- **Auto-renew:** on for everything you care about. Off only for intentional drops. +- **WHOIS privacy:** on by default. Free at most modern registrars. +- **Transfer lock:** on except during planned transfers. + +### Decision 4: DNS provider + +The DNS provider controls how domains resolve. Critical for performance, reliability, and security. + +Pick a provider that gives you: +- Fast global resolution (anycast network) +- DNSSEC support +- API access for automation +- Reasonable record limits +- Good audit logs + +Default DNS records every domain needs: +- A or AAAA records (or CNAME) for the apex and www +- MX records (even just nullified if no email) +- TXT for domain verification, SPF +- CAA records (locks down which certificate authorities can issue certs for the domain) + +### Decision 5: Parked domain strategy + +Domains you own but aren't actively using. Three valid strategies: + +1. **Redirect to a primary site.** Best for defensively registered domains close to your main brand. 301 every path to the primary's homepage or matching path. +2. **Hold blank.** A simple page or DNS NXDOMAIN. Acceptable for domains you may use later. +3. **Park with a landing page.** Generic "coming soon" page. Lowest value. Avoid registrar default parking pages (often serve ads against your brand). + +Anti-pattern: letting parked domains serve duplicate or near-duplicate content from your main site. This is an SEO liability. + +--- + +## Workflow + +### Step 1: Inventory + +Pull every domain you own from every registrar. Build a single sheet: + +| Domain | Registrar | DNS provider | Status | Role | Renewal date | Notes | +|---|---|---|---|---|---|---| + +If you can't account for every domain, the strategy can't be accurate. + +### Step 2: Classify by role + +Each domain gets one role: +- **Primary** (the main site for a brand) +- **Alias** (redirects to a primary) +- **Defensive** (registered to prevent others from getting it; usually parked) +- **Campaign** (short-term, specific use) +- **Retired** (no longer active; either drop at expiry or redirect permanently) + +The classification drives the configuration. + +### Step 3: Audit current configuration + +For each domain check: +- Is the canonical (apex vs www) consistent with the strategy? +- Are redirects 301 (permanent) where intended? +- Is HTTPS enforced on every variant? +- Are DNS records minimal and intentional? +- Is the registrar locked? +- Is auto-renew on? +- Is 2FA on the registrar account? + +Document gaps. Each gap is a ticket. + +### Step 4: Set the canonical pattern + +For new domains and any that need fixing: + +- Pick apex or www as canonical +- Configure 301 redirect for the non-canonical +- Force HTTPS for both +- Verify with curl: `curl -I http://example.com`, `curl -I http://www.example.com`, `curl -I https://www.example.com`. All should chain to a single 200 on the canonical. + +### Step 5: Document the redirect map + +Across the portfolio, document every redirect: + +| Source | Destination | Type | Reason | Date set | +|---|---|---|---|---| + +This is invaluable when something breaks or when planning consolidations. + +### Step 6: Set up monitoring + +Monitor: +- DNS resolution (alert on NXDOMAIN or wrong IP) +- HTTPS certificate expiration (alert at 30, 14, 7 days out) +- Redirect chains (alert if a 301 starts returning 200 or 404) +- Renewal dates (alert at 90, 30, 7 days out) + +This is the bridge between domain strategy and `monitoring-and-alerting`. + +### Step 7: Document and revisit + +Domain strategy is a quarterly review topic. Renewals, consolidations, and new launches change the picture. Without scheduled review, the portfolio drifts. + +--- + +## Failure patterns + +**Both apex and www serve content.** Duplicate content. Pick one, redirect the other. + +**302 redirects where 301 was intended.** 302 is temporary. 301 is permanent. SEO equity passes through 301, not (reliably) through 302. + +**HTTPS not enforced.** HTTP variant serving content alongside HTTPS. Force HTTPS at the edge or the load balancer. + +**Registrar default parking pages.** Parked domains serving registrar ads. Free for the registrar, bad for you. Replace with a redirect or your own page. + +**Domains in multiple registrars by accident.** Migrations that didn't fully complete. Consolidate. + +**No CAA records.** Anyone with a misconfigured ACME client can issue a cert for your domain. CAA limits which CAs can issue. Add it. + +**Auto-renew off "to save money."** Domain accidentally drops, gets snapped up, costs ten times more (or is unrecoverable). Auto-renew is cheap insurance. + +**Subdomains used where subfolders would have been better.** SEO equity gets fragmented across hostnames. The case for a subdomain has to be made; the default is subfolder. + +**Parked domains with thin content "for SEO."** Search engines don't reward this. They penalize doorway pages. Either redirect or leave blank. + +--- + +## Output format + +A domain strategy document includes: + +- **Inventory:** the spreadsheet of every domain +- **Classification:** the role of each +- **Canonical decisions:** apex vs www, locked +- **Redirect map:** every redirect in the portfolio +- **DNS standards:** the default record set +- **Registrar standards:** locked, 2FA, auto-renew +- **Monitoring:** what's watched, where alerts go +- **Renewal calendar:** the next 12 months +- **Review cadence:** when this gets revisited + +--- + +## Reference files + +- [`references/dns-record-reference.md`](references/dns-record-reference.md): Common DNS records explained, with the syntax for the most useful ones (A, AAAA, CNAME, MX, TXT, CAA, SRV, etc.) and when each is needed. diff --git a/skills/domain-strategy/references/dns-record-reference.md b/skills/domain-strategy/references/dns-record-reference.md new file mode 100644 index 0000000..62edfff --- /dev/null +++ b/skills/domain-strategy/references/dns-record-reference.md @@ -0,0 +1,252 @@ +# DNS Record Reference + +A quick reference to the DNS records every domain operator should understand. Stack-agnostic. The syntax is the same across DNS providers. + +--- + +## Address records + +### A record + +Maps a name to an IPv4 address. + +``` +example.com. 300 IN A 192.0.2.1 +www.example.com. 300 IN A 192.0.2.1 +``` + +Use for the apex and any subdomain that resolves to a specific IPv4. + +### AAAA record + +Maps a name to an IPv6 address. + +``` +example.com. 300 IN AAAA 2001:db8::1 +``` + +If your infrastructure supports IPv6, set AAAA records alongside A records. Many ISPs prefer IPv6. + +### CNAME record + +Maps a name to another name (which must resolve to A or AAAA). + +``` +www.example.com. 300 IN CNAME example.com. +shop.example.com. 300 IN CNAME shopify-store.myshopify.com. +``` + +CNAME cannot be used at the apex (e.g., `example.com.` cannot be a CNAME). Most providers offer ALIAS or ANAME records as a workaround for apex. + +CNAME at a name conflicts with any other record at the same name. You can't have both a CNAME and an MX at the same name, for example. + +--- + +## Mail records + +### MX record + +Specifies mail servers for the domain. Priority is the first number; lower wins. + +``` +example.com. 300 IN MX 10 mx1.mailprovider.com. +example.com. 300 IN MX 20 mx2.mailprovider.com. +``` + +Even if the domain doesn't send or receive email, set a "null MX" to prevent spoofing: + +``` +example.com. 300 IN MX 0 . +``` + +This is the "this domain doesn't accept mail" signal, defined in RFC 7505. + +### TXT record (for SPF, DKIM, DMARC) + +TXT records hold arbitrary text. The most common use is email authentication. + +**SPF (Sender Policy Framework):** declares which servers can send mail for the domain. + +``` +example.com. 300 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +``` + +Only one SPF record per domain. Multiple SPF records break SPF entirely. + +**DKIM (DomainKeys Identified Mail):** publishes the public key for signing outgoing email. + +``` +selector1._domainkey.example.com. 300 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +The selector is set by your mail provider. Different providers use different selectors. + +**DMARC (Domain-based Message Authentication):** tells receivers what to do with mail that fails SPF or DKIM. + +``` +_dmarc.example.com. 300 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +``` + +Start with `p=none` for monitoring, then move to `p=quarantine` and finally `p=reject` once aligned. See `email-deliverability` skill for the full progression. + +--- + +## Security records + +### CAA record + +Certificate Authority Authorization. Restricts which CAs can issue certificates for the domain. + +``` +example.com. 300 IN CAA 0 issue "letsencrypt.org" +example.com. 300 IN CAA 0 issuewild "letsencrypt.org" +example.com. 300 IN CAA 0 iodef "mailto:security@example.com" +``` + +Without CAA, any public CA can issue a cert for your domain. With CAA, only the listed CAs can. Add CAA for any domain you care about. + +The `iodef` directive specifies where to email reports of unauthorized issuance attempts. + +### TLSA record + +Used with DNSSEC for DANE (DNS-based Authentication of Named Entities). Pins the TLS certificate or public key in DNS. + +``` +_443._tcp.example.com. 300 IN TLSA 3 1 1 abc123def456... +``` + +Niche. Most operators won't need TLSA. Useful for high-security applications. + +### DNSKEY, DS, RRSIG (DNSSEC) + +DNSSEC signs DNS responses cryptographically, preventing spoofing. Setup is provider-specific. Most modern DNS providers offer one-click DNSSEC. Enable it if available. + +--- + +## Service discovery + +### SRV record + +Specifies the location of services (priority, weight, port, target). + +``` +_sip._tcp.example.com. 300 IN SRV 10 60 5060 sip-server.example.com. +``` + +Used for SIP, XMPP, and similar. Most websites don't need SRV records. + +### NS record + +Specifies authoritative name servers for the domain (or a delegated subdomain). + +``` +example.com. 300 IN NS ns1.dns-provider.com. +example.com. 300 IN NS ns2.dns-provider.com. +``` + +NS records are usually managed by the registrar (for the apex) or by you (for delegated subdomains). + +### SOA record + +Start of Authority. Contains administrative info about the zone. + +``` +example.com. 300 IN SOA ns1.dns-provider.com. admin.example.com. 2024010101 7200 3600 1209600 300 +``` + +Auto-managed by most DNS providers. The serial number (2024010101) increments on every zone change. + +--- + +## TTL guidance + +TTL is how long a record can be cached by resolvers, in seconds. + +| Record type | Recommended TTL | Reason | +|---|---|---| +| A, AAAA on stable infrastructure | 3600 (1 hour) to 86400 (1 day) | Reduces lookup load | +| A, AAAA during a migration | 300 (5 min) | Fast cutover | +| CNAME | 3600 to 86400 | Stable mappings | +| MX | 86400 (1 day) | Mail rarely changes | +| TXT (SPF, DMARC) | 3600 | Quick to update if needed | +| CAA | 86400 | Rarely changes | + +Lower TTL during migrations. Raise it back after. + +--- + +## Common record patterns + +### A new website, single domain + +``` +example.com. 3600 IN A 192.0.2.1 +example.com. 3600 IN AAAA 2001:db8::1 +www.example.com. 3600 IN CNAME example.com. +example.com. 3600 IN MX 10 mx.mailprovider.com. +example.com. 3600 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +_dmarc.example.com. 3600 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +example.com. 86400 IN CAA 0 issue "letsencrypt.org" +example.com. 86400 IN CAA 0 iodef "mailto:security@example.com" +``` + +### A domain that doesn't send mail + +Same as above but replace MX records with the null MX: + +``` +example.com. 86400 IN MX 0 . +``` + +And the SPF can be: + +``` +example.com. 3600 IN TXT "v=spf1 -all" +``` + +### A redirect-only domain + +For a parked or alias domain that only redirects to a primary: + +``` +parked-example.com. 3600 IN A 192.0.2.10 +parked-example.com. 86400 IN MX 0 . +parked-example.com. 3600 IN TXT "v=spf1 -all" +parked-example.com. 86400 IN CAA 0 issue "letsencrypt.org" +``` + +The A record points to whatever serves the redirect. The null MX and SPF prevent the domain from being used for email spoofing. + +--- + +## Common mistakes + +**Multiple SPF records.** Only one SPF record per domain is allowed. Two or more break SPF entirely. To "include" multiple senders, combine them in a single `v=spf1` record. + +**CNAME at the apex.** Forbidden by the DNS spec. Use ALIAS or ANAME (provider-specific) or just use an A record. + +**TTL too low long-term.** Sub-300 TTLs cause unnecessary DNS query load. Use low TTLs only during migrations. + +**Forgotten CAA record after switching CAs.** If you switch from Let's Encrypt to another CA but the CAA record only lists Let's Encrypt, the new CA can't issue. Update CAA before issuing. + +**No null MX on non-mail domains.** Domain becomes a target for spoofing. Cheap to add the null MX. + +**Manual records that should be provider-managed.** Many providers manage records for their services automatically (e.g., Vercel, Cloudflare). Manual records can drift and conflict. + +--- + +## Tooling + +For testing DNS: +- `dig` (command line, the standard) +- `nslookup` (older but widespread) +- Online tools: dnschecker.org, mxtoolbox.com, intodns.com (good for sanity-checking a fresh setup) + +For testing email auth specifically: +- mail-tester.com +- dmarcian.com +- mxtoolbox.com (deliverability tab) + +For monitoring DNS in production: +- Most monitoring services include DNS checks (uptime providers, observability platforms) +- See `monitoring-and-alerting` skill for setting these up. diff --git a/skills/editorial-qa/SKILL.md b/skills/editorial-qa/SKILL.md new file mode 100644 index 0000000..0f99207 --- /dev/null +++ b/skills/editorial-qa/SKILL.md @@ -0,0 +1,334 @@ +--- +name: editorial-qa +description: "Pre-publish QA framework for content. Brief adherence, voice consistency, fact accuracy, structure and clarity, AI-content audit, SEO and AEO compliance, internal linking and schema validation, QA at scale via sampling, the QA workflow, and the discipline that distinguishes catch-problems QA from checkbox QA. Triggers on editorial QA, content review, pre-publish review, content audit, content QA process, AI-content audit, hallucination check, content sampling, programmatic QA, voice consistency check, brief adherence check. Also triggers when a content team is shipping sloppy work, when AI-co-authored content is reaching publish unaudited, when a QA process burns reviewers out, or when a programmatic SEO set needs sampling discipline." +category: content +catalog_summary: "Pre-publish QA framework: brief adherence, voice consistency, fact accuracy, AI-content audit, AEO/SEO compliance, sampling at scale, and the workflow that distinguishes catch-problems QA from process theater" +display_order: 7 +--- + +# Editorial QA + +A senior editor's playbook for pre-publish content QA. The discipline that catches problems BEFORE content ships, not after. + +Most content QA is broken in one of two directions. The thin version is "did I read it once and is the spelling OK," which catches typos but misses brief drift, voice inconsistency, hallucinated facts, AI tells, and structural problems that reach readers as "this is fine but not memorable." The thick version is a 47-item checklist that nobody completes honestly because it is process theater: checkboxes nobody actually believes catch problems. + +This skill is the discipline of catch-problems QA. Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Checks the production volume cannot sustain get redesigned (sampling instead of full audit, automated instead of manual). The QA framework is what is left when you remove the theater. + +The skill covers three production shapes: single editorial pieces (one at a time, full QA), AI-generated drafts (with the AI-content audit that did not exist as prominently 2 years ago), and programmatic SEO sets at scale (sampling discipline, threshold gating). Each needs its own QA shape; the underlying methodology composes across all three. + +When to use this skill: building a content QA process from scratch, auditing an existing QA process that ships sloppy work or burns out the team, designing QA gates for an AI-assisted workflow, or building sampling discipline for programmatic SEO sets. + +--- + +## What this skill is for + +This skill spans pre-publish quality control. It plugs in at the END of every other content skill's output. The six-skill content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. +- `content-brief-authoring` is per-piece scope: briefs each piece. +- `content-and-copy` is execution scope: writes each piece. +- `programmatic-seo` is scaled scope: generates many pages from data. +- This skill is gate scope: verifies before publish. + +Every skill above produces a draft. This skill is what gets drafts to publishable. It is the gate where quality is actually enforced. + +The audience: editorial leads, content directors, in-house content QA, agencies with production lines, content ops managers, anyone running a writer (human or AI) and accountable for what ships. The voice is senior editor to junior editor or content marketer. Specific, opinionated, honest about where QA earns its keep versus where it becomes process theater. + +--- + +## Catch-problems QA vs checkbox QA + +The keystone distinction. Two failure modes plus the discipline. + +**Thin QA (typo-checking dressed as quality control).** "I read it once, it is fine." Catches obvious mistakes; misses brief drift, voice inconsistency, hallucinated facts, structural problems, AI tells. Output: shipped content that is "fine but not memorable." Cost: invisible until a brand misstep, a hallucinated statistic, or a competitor's content compounds and the thin set falls behind. + +**Thick QA (47-item checklist nobody completes honestly).** Every conceivable check listed; no triage. Reviewers either skim and check boxes (theater) or burn out under the cognitive load. Output: shipped content slightly more polished than thin QA produces, but the team's review velocity collapses. Cost: throughput drops; reviewers leave; the checklist atrophies into a few checks that actually run. + +**Catch-problems QA (the discipline).** Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Production volume drives sampling versus full-audit decisions. Reviewers are accountable for what they caught, not for box-completion. + +The litmus test. If the team can name the last 3 problems each QA check caught, the check earns its keep. If a check has not caught anything in 6 months, it is theater. Cut it; reallocate the attention to checks that catch real problems. + +--- + +## Brief adherence check + +Did the writer execute the brief? The check is straightforward when the brief is well-authored (see `content-brief-authoring`). + +The brief-adherence checks: + +- **Target keyword and cluster.** Present in title, first paragraph, headings. +- **Search intent and SERP format.** Piece matches the dominant SERP format (article when SERP wants article, listicle when SERP wants listicle). +- **Target audience.** Piece reads as written FOR the named audience, not for a generic reader. +- **Heading structure.** Piece follows the H2 / H3 outline in the brief, or has a documented reason for deviation. +- **Required entities.** Every entity flagged in the brief appears in the piece. +- **Internal links.** Outbound links specified in the brief are present with the right anchor text. +- **Anti-patterns.** Piece avoids the off-limits language and structures named in the brief. +- **Success criteria acknowledged.** Piece is shaped to MEASURE against the success criteria. + +The brief-adherence check is the cheapest, fastest, highest-value QA gate. It runs first in the QA sequence because catching a brief-adherence failure early saves the editor from spending time on voice and structure on a piece that will need to restart. + +If briefs are vague, this check is impossible. Fix briefs first; the QA process cannot enforce a contract that does not exist. + +Detail in [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md). + +--- + +## Voice consistency check + +Does the piece sound like the brand? + +- **Vocabulary.** Brand-specific terms used correctly; off-brand terms absent. +- **Sentence rhythm.** Matches brand voice (short and punchy versus measured and layered versus colloquial). +- **Stance.** The piece takes positions consistent with brand POV. +- **Register.** Formal or casual matches the surface (blog versus whitepaper versus help doc). +- **Voice drift in long pieces.** 3,000-word pieces often start in brand voice and drift to generic by section 4. Sample paragraphs from start, middle, end. + +For AI-co-authored pieces, voice drift is the dominant failure mode. AI assistants regress to a model-default voice unless the writer actively pulls them back. The QA check needs to read for the brand voice as much as for the words. + +Detail in [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md). + +--- + +## Fact accuracy and citation discipline + +Every claim in the piece needs to be true. The check: + +- **Statistics.** Every number sourced or removed if no source. +- **Quotes.** Every quote attributed to a real person who actually said it. +- **Case studies.** Every example refers to a real company or scenario, or labeled clearly as hypothetical. +- **Dates and timelines.** Verified, not approximate. +- **Named experts.** Real people who consented to attribution. +- **Product claims.** Matches actual product behavior, not future-tense roadmap or marketing aspiration. + +Hallucination is the dominant failure mode in AI-assisted writing. AI assistants generate plausible statistics, plausible quotes, plausible case studies, none of which are real. The fact-accuracy check is the gate that catches them. If you skip this gate on AI-generated content, you ship hallucinations. + +Citation discipline: + +- Inline citations link to authoritative sources (academic papers, industry reports, primary sources). +- Avoid citing other content marketing pages (citation laundering). +- Date the source; sources older than 3 years for fast-moving topics need refresh. + +Detail in [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md). + +--- + +## Structure and clarity check + +Does the piece work as a piece? + +- **Lede.** First 200 words answer the user's likely query (for SEO/AEO pieces) OR establish the thesis (for thought leadership). +- **Sectioning.** H2s map to user mental model, not writer enthusiasm. +- **Section length.** Even-ish across H2s. One massive section plus four 80-word sections signals broken structure. +- **Reading flow.** Paragraphs connect, sentences vary in length. +- **Specificity vs abstraction.** Claims are concrete, not vague. +- **Endings.** Piece concludes with something specific (action, question, idea), not throat-clearing filler. + +Detail in [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md). + +--- + +## AI-content audit + +The QA check that did not exist as prominently 2 years ago. AI-co-authored content has detectable patterns even when written by a competent human editor. + +**AI tells (pattern recognition).** + +- Excessive em-dashes (model-default punctuation) +- Predictable opening phrasings (throat-clearing openers that announce what the piece is about to do; the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener) +- Predictable concluding paragraphs (throat-clearing wrap-ups, "By following these steps") +- Bullet-list overuse where prose would serve +- "On the other hand" / "However" overuse +- Forced bilateral framing (always "two sides" even when one side is right) +- Sentence-end filler ("...and more.", "...among other things.", "...for example.") +- Repetitive sentence-rhythm (every paragraph 2-3 sentences, similar lengths) +- Generic openings (descriptive paragraphs that could open any article on the topic) +- Bridging fluff ("That said", "With that in mind", "Moving on") +- Hedge stacking ("typically", "generally", "often") on claims that should be specific + +**Hallucination patterns (factual errors).** + +- Statistics that look authoritative (specific decimal places, named source) but the source does not exist or does not say that +- Quotes attributed to real people who did not say it +- Case studies about companies that do not exist +- Citations to URLs that 404 or never existed +- "Studies show" claims with no actual study behind them +- Made-up product features + +**Voice drift.** + +- Piece starts in brand voice, drifts to generic by section 4 +- Vocabulary regresses to model defaults +- Stance becomes diplomatic ("there are good arguments on all sides") when brand stance was clear + +The audit shape. Read with these patterns top-of-mind. Flag any match. The bar is not "AI was used" (it almost always is now); the bar is "would a careful human editor have shipped this." If the patterns above are present, the piece needs another revision pass with the patterns called out. + +Detail in [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md). + +--- + +## SEO and AEO compliance check + +Does the piece serve search engines AND answer engines? + +**SEO checks.** + +- Target keyword in title, H1, first paragraph, slug +- Heading hierarchy clean (no orphan H3s, no H4 without H3) +- Image alt text descriptive +- Meta description compelling and keyword-aware +- Internal links specified in brief are present +- External links open in new tab (typically) and have rel attributes appropriate +- URL slug short and descriptive + +**AEO checks.** + +- 40 to 60 word answer paragraph immediately following each H2 question +- TL;DR section present (for pillar pieces) +- FAQ section with FAQPage schema (for pieces where Q and A format applies) +- Specific statistics with cited sources (AI engines weight statistics with sources) +- Named entities (experts, methods, tools) consistently mentioned (entity coverage signals) +- Distinctive POV that is attributable to the brand + +Detail in [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md). + +--- + +## Internal linking and schema validation + +**Internal linking.** + +- Outbound links specified in brief are present with correct anchor text +- Anchor text varies (avoid every link being "click here" or every link being the exact-match target keyword) +- Link targets are live (no 404s, no links to deprecated pages) +- Internal link count appropriate to length (3 to 7 for typical 1,500-word piece, 8 to 15 for pillars) +- Self-cannibalization check: piece does not compete with existing pieces for same target keyword + +**Schema validation.** + +- Article schema present on most pieces; HowTo schema on instructional pieces; FAQPage schema where Q and A applies +- Schema validates against schema.org definitions (no missing required fields, no malformed JSON-LD) +- Schema is consistent with on-page content (do not claim 5-star rating in schema if no rating on page) + +Detail in [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md). + +--- + +## QA at scale + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. Sampling discipline replaces it. + +**Sampling strategy.** + +- Random sample 50 to 200 pages per audit cycle +- Balance the sample across data shape (sparse versus dense records, recent versus old generation, popular versus niche categories) +- Fixed sample percentage as set grows; absolute count plateaus around 200 once the set is large + +**Automated checks at scale.** + +- Heading structure validation +- Schema markup validation +- Word count (flag pages below the floor, e.g. 600 words) +- Duplicate content check (compare each page against the rest of the set) +- Broken-link check +- Image-presence check (where templates expect images) + +**Manual checks on sampled pages.** + +- Brief-adherence equivalent (template-adherence check: does the page execute the template?) +- Top-200-word answer quality +- Whether the page would satisfy a human user's likely query +- Whether the page reads as distinctive versus templated +- Spot-check for AI hallucination if AI was in the loop + +**Threshold gating.** + +- If more than 5% of sampled pages fail the manual review, halt new generation +- Fix the template OR data quality issue before resuming +- Document the threshold breach in the QA log so patterns become visible + +Detail in [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md). + +--- + +## The QA workflow + +Ownership and sequencing. + +**Single QA owner per piece**, not a committee. The owner is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +**Sequencing.** Brief-adherence, then fact-accuracy, then structure, then AI-content audit, then voice, then SEO/AEO, then internal linking, then schema. Brief-adherence first because it is the cheapest gate; SEO/AEO checks last because they are easiest to fix and rarely halt-conditions. + +**Halt vs flag vs auto-fix.** + +- Brief-adherence and fact-accuracy can HALT (return to writer). +- Voice and structure FLAG with suggestions; editor judgment decides whether to halt or revise inline. +- SEO/AEO and schema typically auto-fix (slug, meta description, schema markup are mechanical edits the editor or a script can ship without writer involvement). + +**Escalation.** When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +Detail in [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-qa-failures.md`](references/common-qa-failures.md). + +- "Our QA process is a 47-item checklist nobody completes." Checkbox theater; cut to the checks that earned their keep. +- "We caught zero problems in QA last quarter." Either the process is broken or the writers are extraordinary; investigate. +- "Editor and writer disagree on voice." Voice guidelines are vague; document brand voice with concrete examples. +- "AI hallucinations made it to publish." Fact-accuracy gate skipped or rushed; reinstate as halt-condition. +- "Our pSEO set is shipping thin pages." Sampling discipline missing or thresholds not honored. +- "QA takes longer than the writing." Wrong sequencing; brief-adherence early catches problems before voice/structure investment. +- "Reviewers burn out." Checks that do not catch problems are taxing reviewer attention; cut them. +- "Voice drifts halfway through long pieces." Sample mid-piece paragraphs, not just open and close. +- "We never go back to evaluate." QA log archives feed pattern detection; quarterly review. +- "Different editors apply different standards." Calibration sessions where editors review the same piece independently and reconcile. +- "We ship and discover problems on social." QA was not catching the problem class that is reaching readers; add a check for that class. + +--- + +## The framework: 12 considerations for editorial QA + +When designing or auditing a QA process, walk these 12 considerations. + +1. **Catch-problems vs checkbox.** Every check earns its keep by catching a class of failure. +2. **Brief-adherence first.** Cheapest, fastest, highest-value gate. +3. **Fact-accuracy as halt-condition.** AI hallucinations do not ship to readers. +4. **Voice consistency including mid-piece sampling.** Long pieces drift; sample throughout. +5. **AI-content audit.** Pattern recognition for AI tells, hallucinations, voice drift. +6. **Structure and clarity.** Lede, sectioning, even-ish length, specific endings. +7. **SEO and AEO compliance.** Answer paragraphs, schema, entity coverage. +8. **Internal linking and schema validation.** Outbound links live, anchor text varies, schema validates. +9. **Sampling at scale.** Programmatic and high-volume sets need sampling, not full-audit. +10. **Threshold gating.** Failure rate above threshold halts generation; document breaches. +11. **Single QA owner per piece.** Accountability not diffused across committee. +12. **Sequencing.** Brief-adherence to fact-accuracy to structure to AI-audit to voice to SEO/AEO to linking to schema. + +The output of the framework is a QA process the team can run repeatably: each check named, each owner named, each halt-condition documented, each sampling rule specified for programmatic surfaces. + +--- + +## Reference files + +- [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md) - Every brief field as a QA check, with how to verify and what failure looks like. +- [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md) - Vocabulary, rhythm, stance, register, mid-piece sampling discipline for long pieces. +- [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md) - Verification methodology, hallucination detection, citation rules, source-age guidelines. +- [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md) - Lede patterns, sectioning principles, endings, structural anti-patterns. +- [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md) - 11 AI tells, 6 hallucination patterns, voice drift detection, worked example with revision. +- [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md) - SEO and AEO checks combined into one workflow. +- [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md) - Link discipline, anchor text variation, schema patterns and validation. +- [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md) - Sampling strategy, automated checks, manual review at scale, threshold gating. +- [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md) - Ownership, sequencing, halt versus flag versus auto-fix, escalation patterns. +- [`references/common-qa-failures.md`](references/common-qa-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: QA is where quality gets enforced + +Every other skill in the content suite produces drafts. QA is the discipline that turns drafts into publishable work. It is also where every previous decision (brief shape, voice guidelines, hub architecture, programmatic template) gets tested against actual output. Skipping QA is not "moving fast"; it is shipping the failure modes of every upstream decision unfiltered. + +The QA process is the immune system of the content program: invisible when it is working, catastrophic in its absence. + +When in doubt about whether a QA process is ready, ask: does each check name a class of failure it catches, has each check actually caught something in the last 6 months, is brief-adherence first in the sequence, is fact-accuracy a halt-condition, is the AI-content audit included, does sampling discipline apply to scaled surfaces? If yes to all of those, the process is real. If no to any, the gap is where readers will encounter the failure that QA did not catch. diff --git a/skills/editorial-qa/references/ai-content-audit-patterns.md b/skills/editorial-qa/references/ai-content-audit-patterns.md new file mode 100644 index 0000000..57337e9 --- /dev/null +++ b/skills/editorial-qa/references/ai-content-audit-patterns.md @@ -0,0 +1,119 @@ +# AI-content audit patterns + +The 11 AI tells, the 6 hallucination patterns, voice drift detection, a worked example. The QA check that did not exist as prominently 2 years ago and is now load-bearing for any program with AI in the loop. + +--- + +## The 11 AI tells + +Pattern recognition. Read with these top-of-mind; flag any match. + +**1. Excessive em-dashes.** Model-default punctuation. A piece with 8 em-dashes per 1,000 words is almost certainly AI-drafted. The fix: replace with periods, semicolons, or rephrase the sentence. + +**2. Predictable opening phrasings.** Throat-clearing openers that announce what the piece is about to do (the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener). These openings appear in AI output across topics; pattern-match against the team's curated do-not-use list and cut. + +**3. Predictable concluding paragraphs.** Throat-clearing wrap-ups. "By following these steps." "By implementing these strategies." "Now you have a comprehensive understanding of." All cut. + +**4. Bullet-list overuse.** AI defaults to bullets when prose would serve. Bullets fragment reading flow and signal AI drafting. Convert to prose where prose makes the connection between items clearer. + +**5. "On the other hand" / "However" overuse.** Forced bilateral framing pattern. Used 4+ times in 1,500 words is the AI tell. + +**6. Forced bilateral framing.** "While X has its advantages, Y also has merits." Always two sides given equal weight even when one side is right. The fix: pick a position; defend it; let the contrary view get one short acknowledgment. + +**7. Sentence-end filler.** "...and more." "...among other things." "...for example." All padding. Cut. + +**8. Repetitive sentence-rhythm.** Every paragraph 2 or 3 sentences of similar length. Read aloud: monotonous. The fix: deliberate variation in sentence length and paragraph shape. + +**9. Generic openings.** Descriptive paragraphs that could open any article on the topic. "Customer experience is more important than ever in today's competitive landscape." Cut; replace with a specific opening tied to the piece's thesis or the reader's specific query. + +**10. Bridging fluff.** "That said." "With that in mind." "Moving on." Throat-clearing transitions; cut. + +**11. Hedge stacking.** "Typically," "generally," "often" stacked on claims that should be specific. AI hedges to avoid being wrong; the result is content that says nothing definite. Replace hedges with specifics or cut the hedge. + +--- + +## The 6 hallucination patterns + +Factual errors that AI assistants generate and how to detect each. + +**1. Specific decimal places, named source, source does not exist.** "According to a 2024 Forrester report, 67.3% of B2B buyers..." The decimal place plus named source is the AI tell. Detection: search the source. If it does not exist or does not say that, cut the claim. + +**2. Quotes attributed to real people the person did not say.** "As Marc Benioff said in his 2024 keynote..." Plausible because Benioff gives keynotes. Detection: search for the quote in actual transcripts; verify against original source. If the quote does not match a real source, cut. + +**3. Case studies about companies that do not exist.** "Acme Innovations reduced their cycle time 40% using..." Detection: search the company name. If it does not appear in business directories, news coverage, or LinkedIn, the case study is fake. + +**4. Citations to URLs that 404 or never existed.** Detection: click every external link. 404s and dead links are signals; multiple dead links signal multiple unverified claims. + +**5. "Studies show" claims with no actual study.** "Studies show that 45% of marketers..." with no link, no journal, no year. Detection: ask for the study. If the writer cannot produce it, cut the claim. + +**6. Made-up product features.** "Product X now supports automatic Y" when the product does not. Detection: verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Voice drift detection + +The mid-piece drift pattern in AI-co-authored content. + +**The pattern.** Piece starts in brand voice (because the writer set up the opening prompt with brand voice cues). By section 4, the voice has drifted to model-default. The drift is gradual; the start and end pass voice review while the middle fails. + +**Detection methodology.** + +1. Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. +2. Compare each sample to the brand voice doc's vocabulary, rhythm, stance, register. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. + +**The fix.** Send back with the drifted sections highlighted. Specific note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes from the voice doc]." + +--- + +## Worked example: AI tells in a 4-paragraph excerpt + +Original AI-drafted excerpt (with AI tells in bold for the audit): + +> **In today's fast-paced digital landscape**, content marketing has become more important than ever. **Whether you're a small business owner or a Fortune 500 executive**, understanding the nuances of effective content strategy is crucial for success. +> +> There are many factors to consider when developing a content strategy. **On one hand**, you need to focus on creating high-quality content that resonates with your audience. **On the other hand**, you also need to ensure that your content is optimized for search engines, social media platforms, **and more**. +> +> **It's important to note** that successful content marketing requires a balance between creativity and analytics. **Studies show** that companies that prioritize data-driven decision-making see significant improvements in their content performance metrics. +> +> **By following these steps**, you'll be well on your way to creating a content strategy that drives results. Remember that consistency is key, and that great content takes time to produce. + +The audit tags 9 AI tells in 4 paragraphs (more than 2 per paragraph). + +Revised excerpt (AI tells removed, voice tightened, specifics added): + +> Content marketing produces results when the strategy answers two questions: who are we writing for, and what do they need to do after reading. The B2B SaaS team writing for senior data engineers asks different questions than the consumer brand writing for first-time buyers. Both work; conflating them does not. +> +> The trade-off most teams get wrong is craft against measurement. Pieces optimized for search rankings often read as templated; pieces optimized for craft often miss the structural patterns that earn rankings. The fix is not balance; it is sequencing. Brief the structural patterns first; write to craft within them. +> +> Companies that ship measurable content programs share three patterns: a brief discipline that survives writer changes, a voice doc specific enough to enforce, and a fact-check gate that does not compromise under deadline pressure. Companies that miss any of the three produce inconsistent output regardless of writer talent. +> +> The next step is auditing your current process against those three patterns. If the brief is vague, fix the brief. If the voice doc is aspirational, tighten it with concrete examples. If the fact-check gate is optional, make it a halt-condition. + +The revision removed AI tells, added specifics (the two audience examples, the three patterns), and replaced the closing throat-clearing with a concrete next-step. + +--- + +## The audit checklist + +For each AI-co-authored draft, walk this checklist. + +1. Read the first 200 words. Does the opening match any of the 11 AI tells? Flag. +2. Sample 2 paragraphs from the middle. Does either match AI tells? Does the voice match the brand voice doc? Flag. +3. Read the last 200 words. Does the closing match any of the 11 AI tells? Flag. +4. Search the piece for em-dashes; count. More than 5 in a 1,500-word piece is suspicious. +5. Search for forced bilateral framing patterns. Count. +6. Verify every statistic, quote, case study, citation, and product claim per the fact-accuracy methodology. +7. Sample 3 to 5 internal links; verify they go where the brief specified and the targets exist. + +If 3+ items flag, halt the piece and return for revision with the specific items called out. + +--- + +## Methodology-level choices that stay in the public skill + +The 11 AI tells, the 6 hallucination patterns, voice drift detection methodology, the worked example revision pattern, the 7-step audit checklist. + +## Implementation choices that stay internal + +The specific tooling for automated AI-tell detection (regex patterns, classifier models, prompt-based audits). The specific brand voice doc that drives voice-drift comparison. The specific archive of past AI-tell catches that informs ongoing pattern recognition. The specific revision workflow when AI tells are detected (writer's editing tool, AI assistant configured for revision-not-drafting, human-only revision). These vary by team and tooling preferences. diff --git a/skills/editorial-qa/references/brief-adherence-checklist.md b/skills/editorial-qa/references/brief-adherence-checklist.md new file mode 100644 index 0000000..3f711e9 --- /dev/null +++ b/skills/editorial-qa/references/brief-adherence-checklist.md @@ -0,0 +1,137 @@ +# Brief adherence checklist + +Every brief field as a QA check, with how to verify and what failure looks like. + +The brief-adherence check is the first QA gate in sequence. It is the cheapest gate to run and the highest-value gate to pass: catching a brief-adherence failure early saves the editor from spending review time on voice, structure, and fact-accuracy on a piece that will need to restart. + +This check assumes the brief was authored under the discipline of `content-brief-authoring`. If briefs are vague or thin, fix briefs first; the brief-adherence check enforces a contract that has to exist. + +--- + +## The checklist + +For each piece, walk these 8 fields. + +### 1. Target keyword and cluster + +**Verify.** Pull the brief's primary keyword and 3 to 5 supporting cluster keywords. Search the piece for each. + +**Pass.** Primary keyword appears in title, H1 (if separate), first paragraph, and at least one H2. Supporting keywords appear naturally across the piece without stuffing. + +**Fail patterns.** + +- Primary keyword missing from title or first paragraph +- Cluster keywords absent (piece read like a generic article on the topic) +- Keyword stuffing: same exact-match phrase repeated 8+ times in 1,500 words + +### 2. Search intent and SERP format + +**Verify.** Pull the brief's intent classification and dominant SERP format. Compare to the piece's shape. + +**Pass.** Piece shape matches the format the brief specified: long-form article when SERP wants long-form, listicle when SERP wants listicle, comparison when SERP wants comparison. + +**Fail patterns.** + +- Brief specified listicle; piece is long-form prose +- Brief specified commercial-investigation intent; piece reads as informational with no purchase decision support +- Brief flagged the SERP intent override; piece ignored the override + +### 3. Target audience + +**Verify.** Read the first 200 words and the closing 200 words with the brief's audience description in mind. + +**Pass.** Piece reads as written FOR the named audience: vocabulary, examples, and assumed knowledge match the audience's level. + +**Fail patterns.** + +- Brief specified senior data engineers; piece explains "what is a database" in the introduction +- Brief specified non-technical CMOs; piece uses unexplained jargon +- Piece reads as written for a generic reader rather than the named audience + +### 4. Heading structure + +**Verify.** Compare the piece's H2 / H3 outline to the brief's specified outline. + +**Pass.** Piece follows the brief's outline. Where the writer deviated, the brief's deviation note explains why or the writer's first-draft note flags the deviation for editor review. + +**Fail patterns.** + +- Brief specified 6 H2s; piece has 4 or 9 with no documented reason +- H2 order changed without explanation +- Sections from the outline missing entirely + +### 5. Required entities + +**Verify.** Pull the brief's required-entity list. Search the piece for each. + +**Pass.** Every required entity appears in the piece, ideally in the section the brief specified. Standard entities are covered. Gap entities (the differentiation opportunity) are present where the brief committed to them. + +**Fail patterns.** + +- Brief required mentioning CUPED in the methodology section; CUPED is not in the piece +- Required entities mentioned in passing once each; depth-of-coverage requirements not met +- Gap entities skipped because they were "optional" (they were not; the brief committed to them) + +### 6. Internal links + +**Verify.** Pull the brief's outbound internal-link list with anchor text. Check the piece for each link. + +**Pass.** Every required outbound link is present with the specified anchor text. Optional outbound links are either present or noted as skipped with reason. + +**Fail patterns.** + +- Brief specified 4 required outbound links; piece has 2 +- Anchor text differs from the specified anchor text without reason +- Links to deprecated pages (the writer copied old anchor links from a stale draft) + +### 7. Anti-patterns + +**Verify.** Pull the brief's anti-pattern list. Read the piece looking for each pattern. + +**Pass.** Piece avoids every named anti-pattern. The do-not-use word list, off-brand voice, off-topic tangents, AI clichés, and structural patterns the brief explicitly forbade are absent. + +**Fail patterns.** + +- Anti-pattern words from the do-not-use list present (e.g., the writer slipped into corporate-speak adjectives) +- Off-topic tangents the brief warned against (the writer wandered into adjacent facets the cluster covers separately) +- Voice drifted toward a register the brief excluded + +### 8. Success criteria acknowledged + +**Verify.** Read the piece with the brief's success criteria in mind. Does the piece's shape support the criteria? + +**Pass.** Piece is shaped to MEASURE against the success criteria: ranking-targeted pieces have keyword-aware structure, citation-targeted pieces have answer paragraphs and statistics, conversion-targeted pieces have CTAs and decision-support content. + +**Fail patterns.** + +- Brief said "rank top 10 for [keyword]"; piece misses the structural patterns that earn ranking (no answer paragraphs, no entity coverage, no internal-link plan) +- Brief said "drive 50 trial signups in 30 days"; piece has no clear CTA path to signup +- Success criteria treated as an afterthought rather than a design parameter + +--- + +## What halt-condition looks like + +Brief-adherence failures are halt-conditions: return the piece to the writer with the specific failures named. + +The return note is short. "This piece misses the brief in 3 places: [field 1], [field 2], [field 3]. The brief specified [X]; the piece does [Y]. Please revise and return for round 2." + +Editors who try to fix brief-adherence failures themselves end up rewriting the piece. Better to halt cleanly, return to the writer, and let the writer execute the contract that already existed in the brief. + +--- + +## When briefs are too vague to enforce + +Sometimes the brief itself is the problem. The brief specified "engineers" without naming the seniority level. The brief specified "informational intent" without checking the SERP. The brief specified entities without depth-of-coverage requirements. + +When the brief is too vague, brief-adherence cannot enforce anything. The fix is upstream: tighten brief authoring discipline (see `content-brief-authoring`). The brief is the contract; vague contracts produce vague output regardless of writer skill. + +--- + +## Methodology-level choices that stay in the public skill + +The 8-field checklist, the halt-condition discipline, the upstream-fix observation when briefs are vague. + +## Implementation choices that stay internal + +The specific format the team uses for return notes (Slack message template, Notion row, ticketing system field structure). The specific tooling that stores brief metadata for diff-checking against pieces. The specific automation (if any) that surfaces brief-adherence failures before manual review. These vary by team and stack. diff --git a/skills/editorial-qa/references/common-qa-failures.md b/skills/editorial-qa/references/common-qa-failures.md new file mode 100644 index 0000000..9f97eac --- /dev/null +++ b/skills/editorial-qa/references/common-qa-failures.md @@ -0,0 +1,168 @@ +# Common QA failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: QA either drifted into theater (checks that do not catch problems but cost reviewer attention) or skipped the gates that catch the problems readers actually encounter. The fix is upstream: cut theater checks, reinstate gates that actually catch problems. + +--- + +## "Our QA process is a 47-item checklist nobody completes" + +**Symptom.** The checklist exists. Nobody completes it honestly. Reviewers either skim and check boxes or burn out under the cognitive load. + +**Diagnosis.** Checkbox theater. The checklist accumulated over time as new failures appeared and got added; nothing was ever removed. The list grew past what reviewer attention can sustain. + +**Fix.** Audit the checklist. For each item, ask: when did this last catch a problem? If the answer is "never" or "more than 6 months ago," cut it. The remaining items are the catch-problems checks; the cut items were theater. + +**Prevention.** Quarterly review of the checklist. Each new check earns its keep by catching at least one problem within 90 days; checks that do not catch problems get cut. + +--- + +## "We caught zero problems in QA last quarter" + +**Symptom.** No QA returns. No halt-conditions. No revision rounds. Pieces ship clean every time. + +**Diagnosis.** Either the writers are extraordinary or the process is broken. Almost always the latter. + +**Fix.** Audit recently-shipped pieces independently of the original QA. Find the problems QA missed: hallucinated statistics, voice drift in long pieces, broken links, schema validation failures. Document each. Reinstate the QA gate that should have caught the failure. + +**The pattern.** When QA catches nothing for a quarter, reviewers have stopped reading carefully. The fix is not "trust the writers"; it is reinstating the discipline that was nominally still running. + +--- + +## "Editor and writer disagree on voice" + +**Symptom.** Editor returns the piece with voice notes; writer pushes back; edits go back and forth without convergence. + +**Diagnosis.** Voice guidelines are vague. Both editor and writer are interpreting the brand voice doc differently because the doc does not specify enough. + +**Fix.** Update the voice doc with concrete examples of the disputed dimension. If the dispute was about sentence rhythm, add 5 paired examples (the rhythm we want, the rhythm we do not want). The voice doc gets sharper; future disputes resolve by reference to the examples. + +**Prevention.** Quarterly voice calibration sessions (see `voice-consistency-patterns.md`) where editors review the same piece independently and reconcile. + +--- + +## "AI hallucinations made it to publish" + +**Symptom.** A statistic, quote, citation, or product claim in a published piece turns out to be invented. Reader (or competitor) flags it. + +**Diagnosis.** The fact-accuracy gate was skipped or rushed. + +**Fix.** Two parts. + +- Immediate: correct the published piece, document the failure in the QA log. +- Process: reinstate fact-accuracy as a halt-condition. AI hallucinations do not progress past this gate. If the gate is too slow, automate the easy parts (named-entity extraction, statistic detection) so manual verification focuses on the hard parts. + +**Prevention.** Fact-accuracy gate runs second in the QA sequence (after brief-adherence). Detail in `fact-accuracy-and-citation-discipline.md`. + +--- + +## "Our pSEO set is shipping thin pages" + +**Symptom.** Programmatic pSEO set is producing pages with insufficient data; pages render at 200 to 400 words of templated boilerplate; algorithm risk compounds. + +**Diagnosis.** Sampling discipline missing or thresholds not honored. The set was generating pages without QC checking the quality at the data-shape level. + +**Fix.** Implement the sampling discipline (see `qa-at-scale-patterns.md`). Set the 5% failure threshold; halt new generation when breached. Audit the existing set; noindex or remove pages below the data depth threshold. + +**Prevention.** Sampling and threshold gating built into the program at design time, not retrofitted. + +--- + +## "QA takes longer than the writing" + +**Symptom.** The team's writers ship drafts in 4 hours; QA cycle takes 6 hours. The bottleneck is review. + +**Diagnosis.** Wrong sequencing. The team is running expensive checks (voice, structure) before cheap checks (brief-adherence, fact-accuracy). When a piece fails at gate 1, the time spent on gates 5 to 8 is wasted. + +**Fix.** Reorder the sequence. Brief-adherence first; fact-accuracy second; halt-conditions short-circuit the rest of the gates. Voice and SEO checks last because they are easiest to fix and rarely halt-conditions. + +**Prevention.** The sequencing discipline is documented in `qa-workflow-templates.md`; new editors get the sequence in their onboarding. + +--- + +## "Reviewers burn out" + +**Symptom.** Editors who used to review carefully now skim. The catch rate drops. Editors leave the team. + +**Diagnosis.** The QA load exceeds reviewer capacity. Often because checks that do not catch problems are taxing reviewer attention. + +**Fix.** Cut theater checks (the same fix as the 47-item checklist failure). Burn-out reduces with the cognitive load. + +**Also.** Verify that production volume matches reviewer capacity. If the team is shipping 30 pieces a week with 1 editor, the volume is wrong. Either reduce volume, add reviewers, or accept lower quality with eyes open. + +--- + +## "Voice drifts halfway through long pieces" + +**Symptom.** 3,000-word pillar pieces start in brand voice; by section 4 they read generic. + +**Diagnosis.** Voice review only sampled the start and end. Mid-piece drift went undetected. + +**Fix.** Mid-piece sampling discipline (see `voice-consistency-patterns.md`). Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. AI-co-authored pieces especially need this. + +**Prevention.** Voice review template explicitly requires mid-piece sampling. + +--- + +## "We never go back to evaluate" + +**Symptom.** QA process exists. QA log accumulates. Nobody reviews the log. + +**Diagnosis.** The log is an artifact, not a feedback mechanism. Patterns the log surfaces never reach the editorial process owner. + +**Fix.** Quarterly QA log review. The owner reads the log; pattern observations get translated into process changes (brief tweaks, writer feedback, workflow adjustments, automation additions). + +**Prevention.** The quarterly review is calendar-anchored. Skipping it is the failure mode. + +--- + +## "Different editors apply different standards" + +**Symptom.** A piece shipped under editor A would be returned under editor B (or vice versa). Writers receive inconsistent feedback. Quality varies by which editor caught the piece. + +**Diagnosis.** Voice and structural standards have drifted between editors. Without calibration, individual editors apply individual taste. + +**Fix.** Calibration sessions. Three editors review the same piece independently; the team reads the three assessments together and reconciles. The consensus updates the voice doc and the QA process; future reviews stay consistent. + +**Prevention.** Calibration sessions quarterly minimum. Onboarding new editors includes a calibration round before they review live pieces solo. + +--- + +## "We ship and discover problems on social" + +**Symptom.** Readers (or competitors, or critics on social) flag problems that QA did not catch. + +**Diagnosis.** QA was not catching the problem class that is reaching readers. The class might be hallucinations, voice drift, structural problems, factual errors, or off-brand tone. + +**Fix.** Identify the class of failure that reached readers. Add a QA check that catches that class. Document the addition in the QA log so the pattern becomes visible. + +**Prevention.** The QA process evolves with feedback from shipped pieces. New failure classes that reach readers feed new QA checks. + +--- + +## "AI tells slipped through" + +**Symptom.** Published piece reads as AI-generated despite a human editor reviewing it. Readers or AI-detection tools flag it. + +**Diagnosis.** The AI-content audit either was not run or ran without the pattern recognition the editor needed. + +**Fix.** Add the AI-content audit as a named gate in the QA sequence (see `ai-content-audit-patterns.md`). Train the editor on the 11 AI tells; provide the worked example as reference. The audit becomes a 5-minute discipline rather than an unstructured "does this read OK" check. + +**Prevention.** Every AI-co-authored piece runs through the audit. The audit is a named gate, not an implicit step. + +--- + +## The pattern across most failures + +Most QA failures are designed-in. The process either drifted into theater (cuts needed) or skipped gates that should have been there (gates needed). The discipline is upstream: design the QA process around catch-problems, not around process appearance, and the operational discipline at scale becomes manageable. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the prevention guidance, the upstream-discipline observation. + +## Implementation choices that stay internal + +The specific QA log format and tooling. The specific calibration session cadence and team composition. The specific automation that supports each gate (statistic detection, hallucination flagging, schema validation, link audit). The specific escalation pathways within the team's structure. These vary by team and tooling. diff --git a/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md b/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md new file mode 100644 index 0000000..17d8d83 --- /dev/null +++ b/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md @@ -0,0 +1,113 @@ +# Fact accuracy and citation discipline + +Verification methodology, hallucination detection, citation rules, source-age guidelines. + +Fact accuracy is a halt-condition QA gate. Hallucinations from AI-assisted writing reach readers if the gate is skipped or rushed. The discipline below is what makes the gate work at production speed without becoming the bottleneck. + +--- + +## What gets fact-checked + +Every claim that could be wrong. The categories. + +**Statistics.** Every number in the piece needs a source. "23% of feature flag rollouts include a kill switch" needs a source link to the survey, report, or dataset that produced the 23%. Without a source, the number is either removed or replaced with sourced equivalent. + +**Quotes.** Every quote attributed to a real person needs verification: the person said it, the quote is verbatim or correctly paraphrased, the attribution is accurate, the person consents to attribution. + +**Case studies.** Every example refers to a real company or scenario, OR is labeled clearly as hypothetical. "Acme Corp reduced churn by 40% using this method" needs verification that Acme exists, the method was used, the 40% is real. If the example is hypothetical, the piece labels it: "Imagine a SaaS company..." + +**Dates and timelines.** Verified, not approximate. "Google launched feature X in March 2025" needs verification of the exact month and year. + +**Named experts.** Real people who consented to being attributed. The piece should not attribute claims to "Ronny Kohavi" without verifying the attribution traces to actual published work or direct consent. + +**Product claims.** Match actual product behavior. The product does what the piece says it does, in the way the piece says it does, today, in production. Future-tense roadmap items get clearly labeled as roadmap; marketing aspirations get cut. + +--- + +## The verification methodology + +For each claim in the piece, the editor follows one of three paths. + +**Path 1: in-line citation present.** Click through the citation. Does the source exist? Does the source actually say the claimed thing? Is the source the original (not a citation-of-citation)? + +**Path 2: claim has no citation but is a known fact.** Editor verifies via authoritative source (academic paper, primary government data, official company announcement). Add the citation; do not let the piece ship with uncited claims. + +**Path 3: claim has no citation and is not a known fact.** Halt. Return to writer with the claim flagged. Either the writer adds verification, or the claim gets removed. + +The discipline. No claim ships without verification. "I'm pretty sure I read this somewhere" is not verification. + +--- + +## Hallucination detection + +AI-assisted writing produces plausible-but-fake claims at scale. The patterns to recognize. + +**Pattern 1: specific decimal places, named source, source does not exist.** "According to a 2024 Forrester report, 67.3% of B2B buyers prefer..." Sounds authoritative. The Forrester report does not exist, or exists but does not say that. The decimal place is the AI tell; AI assistants generate false precision to sound credible. + +**Pattern 2: quotes attributed to real people the person did not say.** "As Marc Benioff said in his keynote..." Plausible because Benioff gives keynotes. The specific quote is fabricated. Verify quotes against the actual recording, transcript, or primary source. + +**Pattern 3: case studies about companies that do not exist.** "Acme Innovations reduced their cycle time 40% using..." The company does not appear in any business directory; the case study is invented. Search the company name; if it does not surface in legitimate sources, the case study is fake. + +**Pattern 4: citations to URLs that 404 or never existed.** Click every external link. 404s and dead links are signals; a piece with multiple dead links has multiple unverified claims. + +**Pattern 5: "Studies show" claims with no actual study.** "Studies show that..." with no link, no journal, no year. Either the writer provides the study or the claim gets cut. + +**Pattern 6: made-up product features.** "[Product] now supports automatic X" when the product does not. Verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Citation discipline + +When citations are present, they need to be the right kind. + +**Authoritative sources.** + +- Academic papers (peer-reviewed journals) +- Industry reports from established research firms (Forrester, Gartner, McKinsey, IDC) when verified +- Primary government data (BLS, Census, SEC filings) +- Original company announcements (the company's own blog, press release, official documentation) +- First-party data the brand owns and has published + +**Avoid citation laundering.** + +Citing another content marketing page that itself cites a primary source is laundering. The chain of attribution gets murky; the claim's accuracy degrades through each hop. Cite the primary source directly. + +**Date the source.** + +Sources older than 3 years for fast-moving topics need refresh. "According to a 2018 Gartner report" is a yellow flag for content about a 2026 topic; the data might still be true but probably is not. Either find a more recent source or note the date and explain why the older source still applies. + +--- + +## When the writer disputes the fact-check + +Sometimes the editor flags a claim and the writer pushes back. "I read it in the original source; here's the link." Two outcomes. + +**Outcome 1: writer's source verifies the claim.** Add the citation; ship the piece. The QA process worked. + +**Outcome 2: writer's source does not verify the claim.** This is where the conversation gets uncomfortable. The writer thought they had a source; the source does not say what they thought. The fix is the same: cut the claim or find a verifying source. Do not ship the unverified claim because the writer is sure it is true. + +--- + +## Fact-check log + +Maintain a log of fact-check failures across pieces. Patterns surface over time. + +**Log fields.** Piece, claim, failure type (hallucination / wrong citation / outdated source / unverifiable), writer (if naming patterns), resolution (cut / re-sourced / verified). + +**Patterns the log surfaces.** + +- One writer repeatedly produces hallucinations: writer needs feedback or different work +- One topic area produces frequent hallucinations: that topic needs more verification time built in +- AI-co-authored pieces fail at higher rates than human-authored: AI workflow needs additional guardrails + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The verification methodology, the 6 hallucination patterns, the citation discipline rules, the fact-check log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing the fact-check log (spreadsheet, database, Notion). The specific automation (if any) for surfacing claims that need verification (named-entity extractors, statistic detectors). The specific verification workflow when the editor does not have the bandwidth to fact-check personally (assistant-powered verification, fact-checking service integration). These vary by team scale and tooling preferences. diff --git a/skills/editorial-qa/references/internal-linking-and-schema-validation.md b/skills/editorial-qa/references/internal-linking-and-schema-validation.md new file mode 100644 index 0000000..bce4dd4 --- /dev/null +++ b/skills/editorial-qa/references/internal-linking-and-schema-validation.md @@ -0,0 +1,125 @@ +# Internal linking and schema validation + +Link discipline, anchor text variation, schema patterns and validation. + +The internal-linking and schema layer is where SEO compounds. Each piece's link contribution and schema contribution feeds the program's overall ranking and citation signal. QA enforces the discipline so individual pieces do not drift from the program's link graph and schema standards. + +--- + +## Internal linking + +### Outbound links specified in brief + +- **The brief named X outbound links.** Verify each is present in the piece. +- **Anchor text matches the brief's specification.** "Click here" is dead anchor text; the brief should specify keyword-aware anchor text per link. +- **Links go where the brief said.** The link target is the page the brief specified, not a deprecated alternate or a different page that happens to share the topic. + +### Anchor text variation + +The "every link has the same anchor text" anti-pattern. + +**Pattern.** A piece links to the pillar 3 times. All 3 links use the exact-match keyword as anchor. This signals manipulation to ranking systems and dilutes the anchor's signal. + +**Fix.** Vary the anchor across the 3 links. One uses the exact-match keyword; one uses a descriptive natural-language phrase; one uses a brand-mention anchor or a context-driven phrase. + +**The audit.** For each piece, count the outbound links to the same target. If multiple links to the same target use identical anchor text, vary at least one. + +### Link-target liveness + +- **Every internal link target exists.** No 404s. The link goes to a live page on the site. +- **No links to deprecated pages.** If a target page was retired, the link should redirect (via 301) or the link itself should be replaced. +- **External links work.** Click them; verify they resolve and lead to the intended source. + +The external-link audit catches hallucinated citations (see `fact-accuracy-and-citation-discipline.md`) and link rot. + +### Internal link count + +- **3 to 7 internal links for a typical 1,500-word piece.** Below 3 signals under-linked (orphan-shaped). Above 10 signals link-stuffing. +- **8 to 15 for a pillar piece.** Pillars carry more outbound links to their cluster. +- **The link count should be by design, not by accident.** The brief specifies the link count; the writer should hit it; QA verifies. + +### Self-cannibalization check + +- **The piece does not compete with an existing piece for the same target keyword.** Search the site for the primary keyword. If an existing piece is in the top 5 internal results, flag the new piece. + +The flag triggers a decision: consolidate, differentiate, or kill one. Detail in `pillar-content-architecture/references/internal-linking-architecture.md` for the broader internal linking discipline. + +--- + +## Schema validation + +### Schema type matches content + +- **Article schema for editorial pieces.** Default for blog posts, long-form articles, thought leadership. +- **HowTo schema for instructional pieces.** Step-by-step guides with explicit steps that the schema can structure. +- **Product schema for product pages.** Programmatic pSEO pages rendering products usually use Product schema. +- **LocalBusiness schema for location-based pages.** Programmatic pSEO for geographic categories. +- **FAQPage schema for genuine FAQ sections.** As an embedded schema within the page, not as the page's primary schema (unless the page is FAQ-shaped throughout). +- **BreadcrumbList schema for navigation context.** Most pages benefit; pillar pages especially. + +### Schema validates + +- **Schema validates against schema.org definitions.** No missing required fields. No malformed JSON-LD. No invalid field types. +- **Validation method.** Run the schema through a validator (Google's Structured Data Testing Tool, schema.org's validator, or equivalent). Failures appear as errors with field-specific messages. + +### Schema is consistent with on-page content + +- **Schema reflects what the page actually shows.** Do not claim 5-star rating in schema if there is no rating on the page. Do not claim a HowTo with 7 steps if the page only walks through 4. Mismatch between schema and content can trigger manual penalties. + +### Optional schema fields earn their keep + +- **Populated optional schema fields signal depth.** Programmatic pages with comprehensive schema (`aggregateRating`, `additionalProperty`, `areaServed`, etc.) score higher with AI engines than pages with bare-minimum schema. +- **The trade-off.** Filling optional fields requires data. If the data does not exist, do not fabricate it; either populate genuinely or leave the field absent. + +--- + +## The link audit pattern + +For each piece in QA: + +1. **Outbound links present.** Match against brief. +2. **Anchor text variation.** Same-target links use varied anchor text. +3. **Targets live.** No 404s, no deprecated pages. +4. **Link count in band.** 3 to 7 for typical, 8 to 15 for pillar. +5. **Self-cannibalization.** No competition with existing pieces. +6. **Inbound links queued for post-publish update.** The brief queued 1 to 3 existing pages that should add links to this piece after publish; the QA log queues those updates. + +The 6-step audit takes 5 minutes per piece. Worth the time; under-linked or stuffed pieces fail to compound. + +--- + +## The schema audit pattern + +For each piece in QA: + +1. **Schema type appropriate.** Article, HowTo, Product, LocalBusiness, FAQPage, or BreadcrumbList per content shape. +2. **Schema validates.** Run through a validator; resolve errors before publish. +3. **Schema matches content.** No false claims (false ratings, false step counts). +4. **Optional fields populated.** Where data exists, fields populate; the page signals depth. +5. **Multiple schema types when appropriate.** Article + FAQPage + BreadcrumbList is common for pillar pieces with FAQ sections. + +The schema audit takes 3 to 5 minutes per piece (less with automation; more on first-pass for new content types). + +--- + +## Common failures + +**Brief specified link, writer skipped it.** Halt and return; brief-adherence catches this earlier in the QA sequence. + +**Anchor text identical across links.** Auto-fix in the editor pass; vary the anchor on at least 2 of every 3 same-target links. + +**Schema fails validation.** Auto-fix; the editor or a script ships the corrected schema. + +**Schema claims rating that is not on the page.** Halt and return; this is the manual-penalty risk. + +**Internal link count below brief.** Flag and return for the writer to add the missing links per the brief's specification. + +--- + +## Methodology-level choices that stay in the public skill + +The 6-step link audit, the 5-step schema audit, the anchor variation rule, the schema-content consistency rule, the optional-field discipline. + +## Implementation choices that stay internal + +The specific schema validation tooling (Google's tool, schema.org's tool, custom CI integration). The specific link checker (Screaming Frog, custom Puppeteer script, headless browser audit). The specific CMS integration that auto-populates schema from page metadata. The specific deployment pipeline that runs schema validation on every publish. These vary by stack and team. diff --git a/skills/editorial-qa/references/qa-at-scale-patterns.md b/skills/editorial-qa/references/qa-at-scale-patterns.md new file mode 100644 index 0000000..cd443d8 --- /dev/null +++ b/skills/editorial-qa/references/qa-at-scale-patterns.md @@ -0,0 +1,184 @@ +# QA at scale patterns + +Sampling strategy, automated checks, manual review at scale, threshold gating. + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. The discipline below is sampling plus automated checks plus threshold gating. It is the same shape as the QA section in `programmatic-seo` but applied to the editorial QA gate specifically. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle. The sample is stratified. + +**Stratification dimensions.** + +- **Sparse vs dense data.** Sample some records with minimum-required fields; sample some with most-fields-populated. Sparse pages fail differently from dense pages; the sample needs both. +- **Recent vs old.** Sample some pages generated in the last 30 days; sample some generated 12+ months ago. Recent pages catch template drift; old pages catch data drift. +- **Popular vs niche categories.** Sample some pages from high-traffic parent categories; sample some from low-traffic ones. The popular categories carry the program's traffic; the niche ones surface long-tail-specific failures. +- **Different cohort versions.** If the template has shipped revisions, sample some pages from each cohort. Cohort-specific failures only surface if the sample includes the cohort. + +**Sample size by set size.** + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +**Cycle frequency.** Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks at scale + +Run on every page on a cadence; surface failures as a queue. + +### Heading-structure validation + +- One H1 per page, in the right place +- H2 sequence reasonable (not orphan H3s, not H4 without H3) +- Heading text length within bounds (no 200-character H2s) + +### Schema markup validation + +- Schema type present and matches the page's content type +- Required fields populated +- JSON-LD parses without errors +- Schema does not claim things absent from the page + +### Word count + +- Pages below the floor (typically 600 words for editorial; varies for programmatic templates) get flagged +- Pages above an upper bound (typically 8,000+ words on programmatic templates) get flagged for review + +### Duplicate content + +- Hash-similarity comparison across the set +- Pages with >80% content overlap with another page in the set get flagged +- Common cause: comparison-pivot pages (X vs Y inverse) without canonicalization + +### Broken links + +- Crawl outbound and internal links +- 404s and 5xx responses get flagged +- Both internal links to deleted pages and external links to dead URLs surface + +### Image presence + +- Pages where the template expects images but the image slot is empty +- Programmatic pages with missing image fields render visibly broken + +--- + +## Manual checks on sampled pages + +For sampled pages, the human review covers what automation misses. + +### Brief or template adherence + +- For editorial pages: did the writer execute the brief? +- For programmatic pages: did the page execute the template? + +### Top-200-word answer quality + +- Read the first 200 words. Does the page answer the user's likely query? +- Is the answer self-contained (could be cited as the canonical answer to the query)? + +### Distinctive vs templated + +- Compare the sampled page to two siblings in the same template cohort. Could you tell them apart on substance, not just on identifiers? +- Templated pages that look identical signal weak data depth or weak template variable density. + +### User-intent satisfaction + +- If a real user landed on this page from the target SERP, would they stay or bounce? +- The bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +### AI hallucination spot-check + +- For pages that involved AI in drafting or generation, spot-check 3 to 5 statistics, citations, or factual claims per sampled page. +- Hallucination patterns surface in patterns; one bad page often signals a template-level or pipeline-level issue. + +### AI-tell pattern check + +- Sample a paragraph from the middle of the sampled page. +- Does it match the AI tells from `ai-content-audit-patterns.md`? +- Mid-page drift in programmatic pages signals the generation pipeline's output drifted; investigate. + +--- + +## Threshold gating + +If more than 5% of sampled pages fail the manual review, halt new generation. Fix the template OR data quality issue before resuming. + +**The 5% threshold is empirical.** Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +**What "halt" means.** + +- New page generation stops. +- The template or data fix is shipped. +- The next sample audit confirms the fix improved the failure rate before generation resumes. + +**Why halt instead of "fix as you go."** Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +**The threshold is not negotiable.** "Just ship the next batch and we will fix later" is the failure mode. The pattern produces sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another. That signals a template change or data quality drift; investigate. + +**Cohort cuts.** + +- Pages from a given month +- Pages from a given template version +- Pages from a given data-source version + +**Drift signals.** + +- **Cohort A pages rank top 10; cohort B pages rank position 30.** Template or data changed between cohorts; identify the change. +- **Cohort A pages get cited; cohort B pages do not.** Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- **Cohort A pages have stable engagement; cohort B pages have decaying engagement.** Cohort B may have a data freshness problem. + +Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically. + +--- + +## QA log + +Document each cycle's audit. The log compounds into pattern detection. + +**Log fields.** Cycle date, sample size, failure count, failure types, cohort distribution, threshold breach if any, halt action if triggered, fix shipped if applicable. + +**The patterns the log surfaces over time.** + +- Recurrent failure types (always the answer paragraph; always the schema; always the data freshness) +- Cohort-specific patterns (cohort B always fails harder than cohort A) +- Template versions that solved one problem and introduced another +- Data sources that drift faster than expected + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## When the sample reveals the program is broken + +Sometimes QC at scale reveals the underlying program is wrong, not just that individual pages need fixes. + +**Signals.** + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole there; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. + +--- + +## Methodology-level choices that stay in the public skill + +The stratified sampling strategy, the 5% threshold, the automated check categories, the manual review checklist, the cohort tracking discipline, the QA log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing and querying the QA log (database table, Notion, dbt model, BI tool). The specific automated check pipeline (CI integration, scheduled crawls, data warehouse queries). The specific sampling implementation (random ID selection script, weighted sampling logic). The specific dashboard or visualization for surfacing cohort patterns. These vary per team scale and tooling. diff --git a/skills/editorial-qa/references/qa-workflow-templates.md b/skills/editorial-qa/references/qa-workflow-templates.md new file mode 100644 index 0000000..ad175af --- /dev/null +++ b/skills/editorial-qa/references/qa-workflow-templates.md @@ -0,0 +1,153 @@ +# QA workflow templates + +Ownership, sequencing, halt vs flag vs auto-fix, escalation patterns. + +The QA workflow is the operational shape of how QA actually runs. Templates below name the patterns; teams adapt the implementation to their own tooling. + +--- + +## Ownership: single QA owner per piece + +The principle. One person is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +**Common ownership models.** + +- **Editor-owns-piece.** The editor who reviews the piece is also accountable for what shipped. The same person sees the brief, reads the draft, runs QA checks, ships. +- **Editor + dedicated QA.** Editor reviews voice and structure; dedicated QA runs fact-checks, link audits, schema validation. The editor is still the single point of accountability for ship-decision. +- **Rotating editor pool.** Larger teams have multiple editors; each piece gets one named owner from the pool. The pool is calibrated quarterly so individual editors apply consistent standards. + +**Anti-pattern.** Committee review where 4 reviewers comment, nobody decides, the writer revises against contradictory feedback. The fix: name the decision-maker; treat other input as advisory. + +--- + +## The sequencing template + +Run QA gates in this order. Each gate is cheaper than the next; running them in order saves the editor's time on pieces that should restart. + +1. **Brief-adherence.** First. Cheapest to run. Catches the largest class of failures. +2. **Fact-accuracy.** Second. Halt-condition; AI hallucinations do not progress past this gate. +3. **Structure and clarity.** Third. Identifies pieces that need structural revision before voice and SEO checks make sense. +4. **AI-content audit.** Fourth. Catches AI tells, hallucinations not caught at gate 2, voice drift. +5. **Voice consistency.** Fifth. Mid-piece sampling for long pieces. +6. **SEO and AEO compliance.** Sixth. Most failures here are auto-fixable; rarely halt-conditions. +7. **Internal linking and schema validation.** Seventh. Mostly auto-fix or flag. +8. **Final read.** The last full read before publish. Catches anything the gate-by-gate review missed. + +The early gates (brief, fact, structure) save the most time; running them first means a piece that fails brief-adherence does not consume voice/SEO review time. + +--- + +## Halt vs flag vs auto-fix taxonomy + +Each QA gate has a default action when failures appear. + +**Halt-conditions (return to writer).** + +- Brief-adherence failures. The contract was not executed. +- Fact-accuracy failures (hallucinations, unverifiable claims). Cannot ship false claims. +- Structural failures that require rewriting (buried lede, mismatched intent, missing facets). Cannot fix in editor pass. +- Voice drift that requires rewriting sections. Cannot fix inline. + +**Flag-and-revise (editor flags; writer or editor revises).** + +- Voice consistency issues that are correctable inline. +- Structural issues that need paragraph-level revision (sentence variety, transition smoothing). +- AI tells that need targeted rewriting. +- Specificity gaps where the writer needs to add the missing concrete claim. + +**Auto-fix (editor or script ships the correction without writer involvement).** + +- Slug, meta description, image alt text. +- Schema markup formatting issues. +- Anchor text variation when same-target links share identical anchors. +- Heading structure mechanical fixes (closing orphan H3s). +- Typos and minor grammar. + +The discipline. Most pieces have a mix: some auto-fix items, some flag-and-revise items, sometimes a halt-condition. The editor processes them in the right order: handle auto-fixes inline, batch flag-and-revise items into one return note, halt early if a halt-condition appears. + +--- + +## Escalation patterns + +When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +### Brief-level patterns + +- Multiple writers fail brief-adherence on the same brief field. The brief is unclear about that field; tighten the brief template. +- Multiple briefs surface the same gap (always missing the audience specification, always missing the success criteria). The brief authoring process needs feedback. + +### Writer-level patterns + +- One writer repeatedly produces pieces that fail at the same gate. The writer needs targeted feedback or different work. +- One writer's pieces consistently need substantial revision. Either the briefs the writer receives need to be tighter, or the writer-fit is wrong for the work. + +### Process-level patterns + +- AI-content audit catches similar tells across pieces. The AI workflow needs additional guardrails. +- Fact-accuracy gates catch repeated hallucinations on the same topic. The verification step for that topic needs more time. +- Schema validation fails consistently on the same content type. The CMS template for that type needs updating. + +The escalation. Pattern goes to the editorial process owner with a short summary: "Across the last 12 pieces, 5 failed at [gate] for [reason]. Recommend [action]." The owner decides whether to update the brief template, retrain a writer, change the workflow, or document the pattern as known and accepted. + +--- + +## QA review templates + +Common formats for capturing QA findings. + +### Halt-condition return note + +Short. The note specifies what failed and what needs to change. + +> "This piece needs revision before round 2. Three failures: [field 1] missing the brief specification of [X], [field 2] contains an unverified statistic on line [N], [field 3] reads as model-default voice in section 4. Revise per the brief and the voice doc." + +### Flag-and-revise inline review + +Inline comments in the editing tool. Each comment is short and actionable. + +- "[Brief required] Add internal link to [X] with anchor '[Y]' here." +- "[Voice drift] This paragraph reads generic; pull back to brand voice." +- "[Specificity] 'Many companies' is vague; add the source or remove the claim." + +### Auto-fix log entry + +The editor logs what was auto-fixed for the writer's awareness without requiring writer action. + +> "Auto-fixed during review: meta description tightened, schema markup field [X] added, anchor text varied on 2 links to [target]. No writer action required." + +### Escalation note + +Short summary to the editorial process owner. + +> "Pattern: 5 of 12 recent pieces have failed AI-content audit on em-dash count. The writer using AI assistance is shipping mid-stage drafts without final em-dash cleanup. Recommend a final-pass revision guideline added to the AI-co-author workflow doc." + +--- + +## QA cycle time + +The discipline keeps QA cycle time tractable. + +**Typical times for a 1,500-word piece.** + +- Brief-adherence: 5 minutes +- Fact-accuracy: 10 to 30 minutes (depending on claim density) +- Structure and clarity: 10 minutes +- AI-content audit: 5 minutes +- Voice consistency: 5 minutes +- SEO and AEO compliance: 10 minutes +- Internal linking and schema: 5 minutes +- Final read: 5 minutes + +**Total.** 55 to 75 minutes for a healthy piece. Pieces that halt at gate 1 or gate 2 take less editor time because the early gates short-circuit the rest. + +**The "QA takes longer than the writing" failure.** Usually means the wrong sequencing (running expensive checks before cheap ones). Fix the sequence; the cycle time drops. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner principle, the gate sequencing, the halt/flag/auto-fix taxonomy, the escalation patterns, the review templates, the cycle-time targets. + +## Implementation choices that stay internal + +The specific editing tool the team uses (Google Docs, Notion, Markdown PRs, headless CMS draft mode). The specific commenting and review workflow within that tool. The specific tracking system for QA logs and escalations (Notion, Linear, Jira, custom database). The specific reporting cadence and format for editorial process owners. These vary per team and tooling. diff --git a/skills/editorial-qa/references/seo-aeo-compliance-checklist.md b/skills/editorial-qa/references/seo-aeo-compliance-checklist.md new file mode 100644 index 0000000..e3e31e6 --- /dev/null +++ b/skills/editorial-qa/references/seo-aeo-compliance-checklist.md @@ -0,0 +1,113 @@ +# SEO and AEO compliance checklist + +SEO and AEO checks combined into one workflow. The two-engine optimization principle holds: pieces that earn search rankings are largely the same pieces that earn AI citations. + +This checklist runs late in the QA sequence (after brief-adherence, fact-accuracy, structure, AI-content audit, voice). SEO and AEO failures are mostly auto-fixable; halting on them is rarely the right call. + +--- + +## SEO checks + +### Title and headings + +- **Target keyword in title.** The brief's primary keyword appears in the page title; the title is 50 to 65 characters; the title reads naturally rather than keyword-stuffed. +- **H1 present and matches title intent.** Some CMSs use the title as H1; some have separate H1. Either way, one H1 per page that establishes the topic. +- **Heading hierarchy clean.** No orphan H3s (every H3 sits under an H2). No H4 without H3. The hierarchy is tree-shaped, not arbitrary. +- **H2 keyword variation.** Supporting cluster keywords appear naturally across H2s without forcing. + +### Meta and URL + +- **Meta description compelling and keyword-aware.** 140 to 160 characters; includes the primary keyword without stuffing; reads as a benefit-statement that earns the click from SERP. +- **URL slug short and descriptive.** Hyphens, lowercase, keyword-aware, date-free, under 60 characters. Generic example: `/feature-flag-rollout/kill-switches/`. +- **Canonical URL set.** The piece has a canonical URL pointing to itself (or to the canonical version if this piece is a duplicate-by-design like an X vs Y comparison page). + +### On-page + +- **Image alt text descriptive.** Every image has alt text that describes the image's content, not "image of [thing]" or generic placeholders. +- **External links open appropriately.** Most external links open in a new tab; rel attributes (`noopener`, `noreferrer`, `sponsored`, `nofollow`) match the link's purpose. +- **Internal link count appropriate.** 3 to 7 internal links for a 1,500-word piece; 8 to 15 for a pillar piece. Below the floor signals under-linked; well above signals link-stuffing. + +--- + +## AEO checks + +The AEO surface complements the SEO surface. AI engines weight different patterns; the checks below catch what AI engines specifically reward. + +### Answer paragraphs at H2 level + +- **40 to 60 word answer paragraph immediately following each H2 question.** AI engines extract these as citation candidates. The paragraph is self-contained: read alone, it answers the H2's specific question completely. +- **Snippet-bait pattern repeats throughout.** Not just the top of the piece. Every H2 gets one. + +### TL;DR section + +- **Pillar pieces include a TL;DR section near the top.** 150 to 250 words. Self-contained. The most-cited section by AI engines for pillar-shaped content. +- **TL;DR placement.** After the hero, before the table of contents. The reader sees TL;DR within the first scroll. + +### FAQ schema + +- **FAQ section with FAQPage schema.** Pieces that contain FAQ-shaped content (genuine reader questions with answers) mark the FAQ section with FAQPage structured data. Perplexity especially cites FAQPage content heavily. +- **Genuine FAQs only.** Do not mark fake FAQs (questions nobody actually asks) with FAQPage schema. Search engines and AI engines detect fabricated FAQs and deprioritize. + +### Statistics with sources + +- **Specific statistics with cited sources.** AI engines weight statistics with sources higher than vague qualifiers. "23% of B2B buyers cite [specific source]" beats "many B2B buyers." +- **The numbers are real.** Verify in the fact-accuracy gate; do not let hallucinated statistics ship just because they would help SEO/AEO. + +### Named entities + +- **Entity coverage matches brief.** The required entities from the brief are present; the standard entities are present where relevant; the gap entities are present where the brief committed to them. +- **Entities mentioned with weight.** Pass the brief's depth-of-coverage requirement: not just "CUPED is mentioned in passing" but "CUPED is developed in the methodology H2 with the formula and an example." + +### Distinctive POV + +- **The piece takes a position.** AI engines preferentially cite content with attributable claims. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. +- **The POV is consistent with brand stance.** Voice doc specified the brand stance; the piece's POV aligns. + +--- + +## Auto-fix vs flag vs halt + +Most SEO/AEO failures are auto-fixable: the editor or a script can fix slug, meta description, image alt text, schema markup without writer involvement. + +Some require flag-and-revise: heading structure, internal link count, answer paragraph patterns. The editor flags; the writer revises. + +Halt-conditions are rare for SEO/AEO. The typical case where halt makes sense: the piece is structurally wrong for the target SERP (brief specified listicle; piece is long-form prose). That is a brief-adherence failure that surfaced late; route back to the brief-adherence gate. + +--- + +## The combined SEO/AEO audit + +Run as one pass. The checks overlap (both reward heading structure, both reward depth, both reward freshness). Treating SEO and AEO as separate workflows doubles the audit time without doubling the catch rate. + +The discipline. One audit, one checklist, two-engine optimization mindset. The piece serves both surfaces or it serves neither well. + +--- + +## Pillar-specific extensions + +Pillar pieces have additional SEO/AEO requirements. + +- **TL;DR section** (covered above) +- **Comprehensive entity coverage.** Pillar pieces should mention 15 to 25 entities across the topic; cluster pieces have lower bars. +- **Internal links to cluster pieces.** Pillar links out to each cluster piece via contextual anchors, not via a footer dump. +- **Schema includes BreadcrumbList.** Tells crawlers and AI engines that this is the hub of a topical cluster. + +--- + +## Programmatic-page-specific extensions + +For programmatic SEO pages, SEO/AEO checks adapt. + +- **Top-200-word answer.** First 200 words answer the user's specific query directly. AI engines cite programmatic data pages for factual queries primarily. +- **Schema population at scale.** Every page has Article, Product, LocalBusiness, or other type-appropriate schema; schema fields populate from the same data that renders the visible page. +- **Sampling discipline.** Full-audit SEO/AEO checks are infeasible at scale; sample 50 to 200 pages per cycle (see `qa-at-scale-patterns.md`). + +--- + +## Methodology-level choices that stay in the public skill + +The combined SEO/AEO check sequence, the auto-fix/flag/halt taxonomy, the pillar-specific extensions, the programmatic-specific extensions. + +## Implementation choices that stay internal + +The specific tooling for automated SEO/AEO checks (Lighthouse audits, schema validators, headless-CMS-specific plugins). The specific schema-validation library or service. The specific staging environment where pre-publish checks run. The specific deployment pipeline that gates publish on SEO/AEO compliance. These vary by stack and team. diff --git a/skills/editorial-qa/references/structure-and-clarity-review.md b/skills/editorial-qa/references/structure-and-clarity-review.md new file mode 100644 index 0000000..aebad76 --- /dev/null +++ b/skills/editorial-qa/references/structure-and-clarity-review.md @@ -0,0 +1,128 @@ +# Structure and clarity review + +Lede patterns, sectioning principles, endings, structural anti-patterns. + +Structure determines whether the piece works as a piece. The discipline below is about making structure visible enough to QA repeatably without becoming process theater. + +--- + +## The lede + +The first 200 words. Two valid patterns depending on intent. + +**For SEO/AEO pieces.** The lede answers the user's likely query directly. The reader landed from a SERP looking for a specific answer; the lede provides it within the first 200 words. The rest of the piece develops the answer with depth. + +**For thought leadership.** The lede establishes the thesis. The reader is investing attention; the lede tells them the argument the piece will defend. The rest of the piece builds the case. + +**Lede failure patterns.** + +- **Welcome-to-our-blog throat-clearing.** The lede announces what the piece is about to do instead of doing it. +- **Buried lede.** The actual answer or thesis appears in section 4. The reader bounced at section 2. +- **Vague opening.** Generic descriptive paragraph that could open any article on the topic. +- **History dump.** "Since the dawn of [topic]..." Cuts the throat-clearing; ledes do not need a history. + +--- + +## Sectioning + +**The check.** H2s map to user mental model, not writer enthusiasm. + +**User mental model.** What questions does the reader bring? What questions follow naturally from the first answer? What does the reader want to know next? The H2 sequence answers these in order. + +**Writer enthusiasm.** What does the writer find interesting? Where does the writer want to dig deep? Writer enthusiasm produces sections that are well-written but mistargeted; the reader did not come for that section and skips it. + +**The audit.** Read the H2 list as a sequence of questions or topics. Does the sequence match what the reader's mind would ask in order? If H2 #4 has the answer the reader landed for, the structure has buried lede; promote H2 #4 to H2 #1. + +--- + +## Section length + +**The check.** Even-ish across H2s. + +**Why even-ish matters.** One massive section followed by four 80-word sections signals broken structure. The massive section is doing real work; the 80-word sections are placeholders or filler. + +**The fix.** + +- If the 80-word sections are placeholders: cut them or expand them to the section's natural depth. +- If the massive section is two facets bundled: split it into two H2s. +- If the structure is genuinely uneven (one section needs to be twice as long for substantive reasons): document the rationale; ship with the imbalance acknowledged rather than hidden. + +--- + +## Reading flow + +**The check.** Paragraphs connect; sentences vary in length. + +**Paragraph flow.** Each paragraph extends the previous one or pivots intentionally. Disconnected paragraphs read as bullet-points-pretending-to-be-prose. The fix: explicit connective tissue between paragraphs (the connection is implicit in the sequence, or the writer adds a one-sentence transition that does the work). + +**Sentence variety.** Reading aloud is the audit. Do all the sentences run the same length? That is a tell of AI-assisted writing or rushed drafting. Vary sentence length across the paragraph; mix short declarative sentences with longer ones that build through clauses. + +--- + +## Specificity vs abstraction + +**The check.** Claims are concrete, not vague. + +**Concrete.** Named tools, named methods, named statistics with sources, named experts, named scenarios. Concrete claims earn citations from AI engines and trust from readers. + +**Abstract.** "Many companies struggle with X." "Studies show Y." "Industry leaders agree Z." Vague claims read as content marketing filler; AI engines and readers both deprioritize. + +**The fix.** Replace each abstract claim with a specific one. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research the writer did not do, halt and request the research before shipping. + +--- + +## Endings + +**The check.** Piece concludes with something specific. + +**Specific endings.** + +- An action the reader can take now +- A specific question that frames the next step +- A concrete idea that lands as the takeaway +- A direct call to action with a specific destination + +**Filler endings to cut.** + +- Wrap-up paragraphs that summarize what the piece just said +- Wrap-up frames that announce the ending instead of arriving at it (the conclusion should land as a conclusion, not declare itself) +- Vague "join us as we explore" closings +- Marketing-tone CTAs that do not match the piece's voice + +The ending is the last thing the reader reads; it is the moment of conversion or memory. Filler endings waste the moment. + +--- + +## Structural anti-patterns + +The patterns that surface in QA, with the fix for each. + +**Bullet-list overuse.** When prose would serve, the writer used bullets. Bullets fragment the reading flow and signal AI-assisted drafting. Convert bullets to prose where prose makes the connection between items clearer. + +**Subheading-fest.** Every paragraph has its own H3 subheading. Reads as outline-converted-to-content rather than written content. Cut subheadings to the structural ones; let prose carry between subheadings. + +**Repetitive paragraph structure.** Every paragraph is 2 or 3 sentences of similar length. Vary the structure: some paragraphs are one long sentence; some are 4 short sentences; some are a sentence and a fragment. + +**Forced bilateral framing.** "On one hand X, on the other hand Y" pattern repeated throughout. AI-tell. Pick a position; defend it; let the contrary position get one sentence rather than equal weight when the position is genuinely strong. + +**Throat-clearing transitions.** "That said," "With that in mind," "Moving on," "Now let us look at..." All filler. Cut them; the section heading does the transition work. + +--- + +## The read-aloud audit + +The fastest structure check. Read the piece aloud (or silently with attention to rhythm). + +**Signals.** Where does the rhythm break? Where do you stumble? Where does the reading energy drop? Each break is a structural signal. Sometimes the fix is sentence-level; sometimes it is structural. + +**The discipline.** The read-aloud audit takes 10 minutes for a 1,500-word piece. It catches problems that line-by-line review misses. Build it into the QA workflow. + +--- + +## Methodology-level choices that stay in the public skill + +The lede patterns, the sectioning principles, the section-length discipline, the reading-flow audit, the specificity rule, the endings discipline, the structural anti-patterns, the read-aloud audit. + +## Implementation choices that stay internal + +The specific format the team uses for structural feedback (inline comments versus written summary versus structural diff). The specific tooling for documenting structural decisions on a piece (CMS metadata, brief addendum, separate review doc). The specific surface conventions per content type (the team's own blog vs help doc vs landing page structural patterns). These vary by team and stack. diff --git a/skills/editorial-qa/references/voice-consistency-patterns.md b/skills/editorial-qa/references/voice-consistency-patterns.md new file mode 100644 index 0000000..3a0ba06 --- /dev/null +++ b/skills/editorial-qa/references/voice-consistency-patterns.md @@ -0,0 +1,108 @@ +# Voice consistency patterns + +Vocabulary, rhythm, stance, register. Mid-piece sampling discipline for long pieces. The voice-drift failure mode in AI-co-authored content. + +Voice is the most subjective QA dimension and often the easiest one to skip. The discipline below makes voice-consistency checking concrete enough to run repeatably. + +--- + +## Vocabulary + +**The check.** Brand-specific vocabulary used correctly; off-brand vocabulary absent. + +**Brand vocabulary.** Each brand has a set of terms it uses (or refuses) consistently. Apple says "Mac," not "PC." Stripe says "developers," not "engineers." A B2B SaaS company might say "customers," not "users." A consumer brand might say "members," not "subscribers." + +**The audit.** Pull the brand voice doc's vocabulary section. Check the piece for each preferred term and each forbidden term. Failures: off-brand terms slipped in (the writer or AI assistant defaulted to industry-standard vocabulary instead of brand-specific). + +**Forbidden terms list.** Every brand has a list. Common patterns: corporate-speak adjectives, throat-clearing phrases, generic descriptors that flatten distinctive voice. The list is short (10 to 30 terms typically); reviewers should know it cold. + +--- + +## Sentence rhythm + +**The check.** Sentence rhythm matches brand voice. + +**Three common rhythms.** + +- **Short and punchy.** Short sentences. Frequent paragraph breaks. Dramatic emphasis through structural choices. +- **Measured and layered.** Longer sentences with subordinate clauses. Paragraphs build through accumulation. Conversational but considered. +- **Colloquial.** Conversational rhythm with mid-sentence asides, contractions, and direct reader address. Reads like a smart person talking. + +**The audit.** Read 3 paragraphs aloud. Does the rhythm match the brand's voice doc? Common drift: AI-assisted pieces regress to a uniform medium-length sentence rhythm regardless of the brand's specified rhythm. + +--- + +## Stance + +**The check.** The piece takes positions consistent with brand POV. + +**Brand stance varies.** Some brands are diplomatic and surface multiple sides without endorsing one. Others are opinionated and take clear positions. Others are coach-style and challenge the reader directly. + +**The audit.** Pick 3 to 5 places in the piece where the writer made a stance choice (a recommendation, a warning, an evaluation). Does each match the brand's stance pattern? + +**Voice drift signal.** AI-assisted pieces regress toward "diplomatic" stance even when the brand stance is opinionated. "There are good arguments on all sides" is the AI default; opinionated brands need to push the AI back toward conviction explicitly. + +--- + +## Register + +**The check.** Formal versus casual matches the surface. + +**Surface determines register.** A whitepaper takes one register; a blog post takes another; a help doc takes a third. The brand voice doc usually specifies registers per surface type. + +**The audit.** Identify the surface this piece will publish on (blog, knowledge base, whitepaper, marketing page, product help). Check the piece's register against the surface-appropriate register. + +**Common drift.** Blog pieces drift formal (they read like watered-down whitepapers). Whitepapers drift casual (they read like long blog posts). Help docs drift either direction. The brand voice doc establishes register expectations; the QA check enforces them. + +--- + +## Mid-piece sampling + +**The discipline.** Long pieces drift; sample throughout, not just at start and end. + +**Why drift happens.** Writers (human or AI) start in brand voice because that is what the brief, the opening prompt, and the recent context established. By section 4 of a 3,000-word piece, the writer's working memory has shifted to the topic at hand and the voice has drifted toward a generic baseline. AI-assisted pieces drift faster because the model's defaults reassert without continuous reinforcement. + +**The sampling pattern.** + +- **Start sample.** First 200 words. Voice should be strongest here. +- **Middle samples.** Two paragraphs from the middle 60% of the piece. Voice should hold. +- **End sample.** Last 200 words. Voice should match the start. + +If the start and end samples show brand voice and the middle samples show generic voice, the piece has voice drift. Send it back with the drifted sections highlighted. + +--- + +## The voice-drift signal in AI-co-authored content + +Voice drift is the dominant voice failure in 2025-2026 content. AI assistants produce drafts that pass the start-and-end check (because the writer set up the opening prompt with brand voice cues) but fail the mid-piece check (because the model defaults reasserted in the middle). + +**The detection pattern.** + +- Mid-piece paragraphs use vocabulary not in the brand voice doc +- Mid-piece sentence rhythm regresses to medium-length uniformity +- Mid-piece stance becomes diplomatic where brand stance was opinionated +- Mid-piece register drifts toward "professional neutral" regardless of the surface's intended register + +**The fix.** When mid-piece drift is detected, the revision pass needs to explicitly pull the voice back. The editor's note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes]." + +--- + +## Voice calibration sessions + +Different editors apply voice judgment differently. Quarterly calibration sessions reduce the drift between editors. + +**The session.** Three editors review the same piece independently. Each writes a one-paragraph voice assessment. The team reads the three assessments together; differences in interpretation surface; the team reconciles to a shared standard. + +**The output.** A short addendum to the brand voice doc capturing the calibration consensus on whatever was contested. Over time the addenda accumulate into a sharper, more specific voice doc. + +**Why calibration matters.** Without it, voice judgment varies by editor; writers receive inconsistent feedback; voice drift compounds across the program. The calibration session is preventative; once the team is calibrated, individual reviews stay consistent. + +--- + +## Methodology-level choices that stay in the public skill + +The 4-dimension voice check (vocabulary, rhythm, stance, register), the mid-piece sampling discipline, the AI voice-drift detection pattern, the calibration session methodology. + +## Implementation choices that stay internal + +The specific brand voice doc format (Notion page, Markdown file, internal wiki page). The specific vocabulary list and the specific forbidden-term list (these are brand-specific and live in the brand's own documentation). The specific calibration session cadence and team composition. The specific tooling for archiving voice assessments. These vary per brand and team. diff --git a/skills/email-deliverability/SKILL.md b/skills/email-deliverability/SKILL.md new file mode 100644 index 0000000..aca68b1 --- /dev/null +++ b/skills/email-deliverability/SKILL.md @@ -0,0 +1,283 @@ +--- +name: email-deliverability +description: "Make sure email actually reaches inboxes. Use this skill when setting up email authentication (SPF, DKIM, DMARC), diagnosing emails landing in spam, planning a domain reputation strategy, monitoring sender reputation, or hardening against email spoofing. Triggers on email deliverability, SPF, DKIM, DMARC, spam folder, sender reputation, mailbox provider, soft bounces, bounce rate, BIMI, MTA-STS, deliverability audit. Also triggers when a marketing or transactional email isn't reaching users." +category: operations +catalog_summary: "DMARC, SPF, DKIM, sender reputation, deliverability monitoring" +display_order: 8 +--- + +# Email Deliverability + +Get email into inboxes, not spam folders. Set up authentication. Monitor reputation. Diagnose problems before they hurt the business. + +--- + +## When to use + +- Setting up email for a new domain +- A meaningful percentage of email is going to spam +- Customers report they're not receiving emails +- Setting up DMARC, SPF, or DKIM +- Hardening against domain spoofing +- Migrating email service providers +- Sender reputation has dropped +- Pre-launch audit before sending volume increases + +## When NOT to use + +- Writing the email content itself (use `email-sequences`) +- Designing the email program strategy (use `email-sequences`) +- DNS records in general (use `domain-strategy`) +- Outbound spam coming FROM your account (different problem; investigate compromised credentials) + +--- + +## Required inputs + +- The sending domain(s) +- The email service provider (ESP, transactional service, mail server) +- Current DNS records (or access to them) +- Email volume (transactional vs marketing, daily volume) +- Current deliverability state (if known: bounce rate, spam complaints) + +--- + +## The framework: 3 pillars + +Email deliverability rests on three pillars. Weakness in any one limits the others. + +### Pillar 1: Authentication + +Mailbox providers verify email is actually from who it claims to be from. Three records. + +**SPF (Sender Policy Framework)** + +Lists which servers are authorized to send mail for the domain. Published as a TXT record at the apex. + +``` +v=spf1 include:_spf.mailprovider.com -all +``` + +- `include:` adds another sender's authorized list +- `-all` (hard fail): mail from unlisted senders fails authentication +- `~all` (soft fail): unlisted senders are suspicious but pass; useful during rollout +- `+all`: never use; allows anyone to send + +Only one SPF record per domain. Multiple SPF records break SPF entirely. Combine senders into a single record. + +SPF has a 10-DNS-lookup limit. Each `include:` may use multiple lookups. Hit the limit and SPF stops working. Watch this carefully. + +**DKIM (DomainKeys Identified Mail)** + +A cryptographic signature on each outgoing email. The mail server signs with a private key; the public key is published in DNS. + +``` +selector1._domainkey.example.com TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +Selectors differ by ESP. Some use `default._domainkey`, some use unique selectors per service. Most ESPs walk you through publishing the records. + +DKIM proves the message wasn't modified in transit and that the sender controls the domain. + +**DMARC (Domain-based Message Authentication, Reporting, and Conformance)** + +The policy layer. Tells receivers what to do when SPF or DKIM fails, and where to send reports. + +``` +_dmarc.example.com TXT "v=DMARC1; p=reject; rua=mailto:dmarc-aggregate@example.com; ruf=mailto:dmarc-forensic@example.com; pct=100; adkim=s; aspf=s" +``` + +Components: +- `p=`: policy. `none`, `quarantine`, or `reject`. +- `rua=`: aggregate reports (daily, summary). Always set this. +- `ruf=`: forensic reports (per-message). Optional, can be high volume. +- `pct=`: percentage of failing mail subject to the policy. Useful for gradual rollout. +- `adkim=`, `aspf=`: alignment mode. `s` (strict), `r` (relaxed). Strict means From: domain must match exactly. + +DMARC is the most important record. It's what makes spoofing your domain hard. + +### Pillar 2: Reputation + +Mailbox providers (Gmail, Outlook, Yahoo) score every sender. Reputation drives delivery. + +Reputation factors: +- **Authentication pass rates** (SPF, DKIM, DMARC) +- **Engagement signals** (opens, replies, marking as not-spam) +- **Negative signals** (spam complaints, deletions without opens, blocking) +- **List hygiene** (low bounce rates, no spam traps) +- **Volume consistency** (sudden spikes look like spam) +- **Content patterns** (link reputation, attachment patterns) +- **IP and domain history** + +Reputation is per (sending domain × mailbox provider). Gmail's view of you is independent of Outlook's. + +### Pillar 3: List quality and engagement + +Authentication and reputation rest on list quality. Bad list = bad reputation eventually. + +- Only send to people who explicitly opted in +- Confirmed (double) opt-in for marketing wherever feasible +- Honor unsubscribes immediately and reliably +- Remove hard bounces immediately +- Sunset disengaged contacts (no opens in 6 months: reduce frequency or remove) +- Avoid third-party lists, scraped emails, or "purchased opt-ins" + +The single biggest deliverability lever for most senders is list hygiene. + +--- + +## Workflow + +### Step 1: Audit current state + +Check the current DNS records: + +```bash +dig +short txt example.com +dig +short txt selector1._domainkey.example.com +dig +short txt _dmarc.example.com +``` + +Also check: +- Current bounce rate (target: under 2%) +- Current spam complaint rate (target: under 0.1%) +- Current open rate (varies by industry; falling trend is a warning) +- Current sending volume + +Tools: mxtoolbox.com, dmarcian.com, mail-tester.com (for individual messages). + +### Step 2: Fix authentication + +If any of SPF, DKIM, DMARC is missing or misconfigured, fix first. + +**SPF fix order:** +1. Identify all legitimate senders (transactional ESP, marketing ESP, support tools, etc.) +2. Get the `include:` value or IP for each +3. Combine into a single SPF record +4. Verify lookup count is under 10 +5. Use `-all` for hard fail (or `~all` if rolling out gradually) + +**DKIM fix order:** +1. Generate a new selector per sending service +2. Publish the public key in DNS +3. Configure the ESP to sign with the private key +4. Verify with a test send (check headers for `dkim=pass`) + +**DMARC fix order:** +1. Publish DMARC with `p=none` initially (monitoring mode) +2. Set up an aggregate report endpoint (use a DMARC analytics service or your own) +3. Watch reports for at least 2-4 weeks +4. Identify any legitimate senders failing alignment; fix them +5. Move to `p=quarantine` with `pct=10`, gradually increase +6. Move to `p=reject` once confidence is high + +The full progression typically takes 2-3 months. Rushing causes legitimate mail to bounce. + +### Step 3: Set up monitoring + +Ongoing visibility: + +- **DMARC aggregate reports**: parsed daily. Watch for new sources, alignment failures, volume changes. +- **Bounce rate**: per ESP dashboard. Target under 2% for transactional, under 5% for marketing. +- **Spam complaint rate**: target under 0.1%. +- **Reputation tools**: Google Postmaster Tools (free), Microsoft SNDS, Talos, Sender Score. +- **Blacklist monitoring**: most ESPs include this; otherwise mxtoolbox.com or hetrixtools.com. + +### Step 4: Address list hygiene + +- Remove hard bounces from your sending lists immediately (most ESPs do this; verify) +- Set up suppression lists (unsubscribes, manual blocks, deliverability sinkholes) +- Sunset disengaged contacts (re-engagement campaigns or just remove) +- Review opt-in flows: do people know what they're signing up for? + +### Step 5: Content and pattern audit + +If reputation is good and authentication passes, check content: + +- HTML-only emails (no plain-text alternative) raise flags +- Heavy image-to-text ratios raise flags +- Suspicious link patterns (bare IPs, URL shorteners, hijacked domains) +- Specific spam-trigger words in subject lines (less important than it used to be, still real) +- Lots of mismatched domains in URLs +- Generic from-name like "info@" rather than a real-sounding sender + +### Step 6: Plan for growth + +Email volume affects reputation. Sudden spikes look like spam. + +- Warm up new sending IPs gradually (start at 50/day, 2x daily) +- Warm up new domains gradually (similar pattern) +- Spread sends throughout the day +- Don't switch ESPs the week before a big launch + +### Step 7: Set up BIMI (optional but valuable) + +BIMI (Brand Indicators for Message Identification) shows your logo next to authenticated emails in supporting clients (Gmail, Apple Mail, Yahoo, others). + +Requires: +- DMARC at `p=quarantine` or `p=reject` (so this comes after the DMARC progression) +- A trademarked logo as an SVG (specific format requirements) +- A Verified Mark Certificate (VMC) from a CA, for Gmail and others +- A `_bimi` DNS record pointing to the SVG and VMC + +BIMI improves trust signals and engagement. Worth doing once DMARC enforcement is in place. + +### Step 8: Document and revisit + +Document the email architecture: +- Sending domains and subdomains +- Each ESP and what it sends +- DNS records for each +- Monitoring setup +- Escalation if deliverability degrades + +Revisit quarterly or when a new ESP is added. + +--- + +## Failure patterns + +**Multiple SPF records.** Two or more SPF records on the same domain breaks SPF. Combine into one. + +**SPF DNS lookup limit exceeded.** Too many `include:` directives or chained includes. Flatten or simplify. + +**DMARC at `p=none` forever.** Monitoring without enforcement. Spoofing remains easy. Move to enforcement. + +**DMARC at `p=reject` too quickly.** Legitimate mail bounces because alignment wasn't verified. Use the gradual rollout. + +**Sending from a different domain than the From: address.** Causes alignment failures. Fix the From: domain or ensure proper alignment. + +**Using a shared ESP IP without ESP-specific configuration.** Some ESPs don't sign with your DKIM by default; the signature is the ESP's, not yours. Configure custom DKIM. + +**Sending from a domain that also sends marketing.** A spam complaint on a marketing email hurts transactional deliverability. Use a subdomain for transactional (`transactional.example.com`) or marketing (`mail.example.com`). + +**No bounce monitoring.** Hard bounces accumulate, reputation tanks, deliverability cliff-falls. Monitor. + +**Bought lists or scraped contacts.** Spam traps in those lists destroy reputation. Don't. + +**No double opt-in for marketing.** Single opt-in lets bots and typos onto the list. Bots generate spam complaints, destroy reputation. + +**Ignoring DMARC reports.** Reports show problems early. Set up a parser. Look weekly. + +**Treating "marked as not-spam" as the goal.** The goal is to never land in spam in the first place. Once reputation is bad, recovery takes months. + +--- + +## Output format + +A deliverability audit document includes: + +- **Domain inventory:** every sending domain +- **Authentication status:** SPF, DKIM, DMARC per domain +- **Sender inventory:** every ESP or service that sends mail, what's configured +- **Reputation status:** per major mailbox provider where measurable +- **List hygiene:** bounce rate, complaint rate, opt-in process +- **Findings:** prioritized issues +- **Roadmap:** SPF/DKIM/DMARC fixes, BIMI plan, monitoring plan +- **Monitoring setup:** what's watched, where alerts go + +--- + +## Reference files + +- [`references/dmarc-rollout-playbook.md`](references/dmarc-rollout-playbook.md): Step-by-step for moving from no DMARC to `p=reject`, with timing, monitoring, and how to handle problems found along the way. diff --git a/skills/email-deliverability/references/dmarc-rollout-playbook.md b/skills/email-deliverability/references/dmarc-rollout-playbook.md new file mode 100644 index 0000000..bc3d319 --- /dev/null +++ b/skills/email-deliverability/references/dmarc-rollout-playbook.md @@ -0,0 +1,294 @@ +# DMARC Rollout Playbook + +A staged, low-risk path from no DMARC to full `p=reject` enforcement. Typical duration: 2-3 months. Rushing breaks things. + +--- + +## Why DMARC matters + +Without DMARC at enforcement, anyone can send email claiming to be from your domain. Phishing campaigns can spoof your brand to your customers, your investors, your own employees. + +DMARC at `p=reject` means mailbox providers will reject mail that fails authentication. The spoofing attacks fail. + +The goal of this playbook: get to `p=reject` without losing legitimate mail. + +--- + +## Prerequisites + +Before starting: + +- [ ] SPF is published, single record, under 10 lookups +- [ ] DKIM is published, every legitimate sender signs with your domain's key +- [ ] You have a DMARC report destination (a parsing service or your own endpoint) +- [ ] You have access to make DNS changes +- [ ] You know who is responsible for fixing email-related issues + +If any of these are missing, fix them first. DMARC enforcement on top of broken SPF or DKIM means losing legitimate mail. + +--- + +## Stage 1: Monitor (Week 1-2) + +### Goal +Discover every legitimate sender of mail from your domain. Many will be unexpected. + +### Action + +Publish DMARC at `p=none`: + +``` +v=DMARC1; p=none; rua=mailto:dmarc-aggregate@example.com; pct=100; adkim=r; aspf=r +``` + +Notes: +- `p=none`: no enforcement; mailbox providers report but take no action +- `rua=`: where aggregate reports go. Use a DMARC analytics service or your own endpoint +- `adkim=r`, `aspf=r`: relaxed alignment (less strict; eases initial rollout) + +### What to watch + +Aggregate reports start arriving from major mailbox providers within 24-48 hours. Reports are XML, daily, summarized. + +Look for: +- Every IP and sender sending mail "From: yourdomain" +- Pass/fail rates for SPF and DKIM +- Volume per sender +- Unexpected senders (often: a marketing tool, a customer support tool, a forgotten old service) + +### Common discoveries + +- Marketing ESP signing with their domain, not yours +- Internal tools sending email through unauthorized servers +- Help desk forwarding mail in a way that breaks alignment +- A SaaS notification service no one remembered +- Compromised accounts (rare but real) +- Spoofers trying to phish + +### Exit criteria + +- All legitimate senders identified +- All legitimate senders pass SPF or DKIM (ideally both) +- The volume of failing legitimate mail is well understood + +--- + +## Stage 2: Quarantine 10% (Week 3-4) + +### Goal +Begin enforcement on a small percentage. Watch for legitimate mail being affected. + +### Action + +Update DMARC to: + +``` +v=DMARC1; p=quarantine; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +Now 10% of failing mail goes to spam at supporting providers. 90% still passes through. + +### What to watch + +- Aggregate reports continuing to flow +- Customer reports of legitimate mail in spam +- Internal complaints (your own team is often the canary) + +### What to do if problems + +If a known-legitimate sender starts having mail quarantined: + +1. Identify the sender and the failure (SPF? DKIM? Alignment?) +2. Fix the sender (add to SPF, configure DKIM, fix alignment) +3. Verify the fix in subsequent reports +4. Continue + +If an unknown legitimate sender starts having mail quarantined: + +1. Investigate. Is this real legitimate use? (Internal tool? New SaaS?) +2. If yes, fix the authentication for it +3. If no, this is the spoofing DMARC is meant to stop + +### Exit criteria + +- Reports show no legitimate mail being quarantined +- Sustained for at least one week with no surprises + +--- + +## Stage 3: Quarantine 100% (Week 5-6) + +### Goal +Enforce quarantine for all failing mail. Build confidence before reject. + +### Action + +``` +v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 2 but expect higher volume of spam-foldered mail. Most should be illegitimate. + +### Exit criteria + +- No legitimate mail quarantined for at least one week +- Spoofing volume in reports is clearly visible (this is what DMARC is catching) + +--- + +## Stage 4: Reject 10% (Week 7-8) + +### Goal +Start rejecting failing mail. Fail-mode is harder than quarantine; legitimate mail that fails is bounced, not delivered to spam. + +### Action + +``` +v=DMARC1; p=reject; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +10% of failing mail is rejected. The other 90% goes to quarantine (the previous policy applies). + +### What to watch + +- Bounce rates from your sending tools (transactional and marketing) +- Customer reports of "I never got the email" +- Reports of legitimate mail being rejected + +If bounces spike, something legitimate is failing. Investigate immediately and consider rolling back. + +### Exit criteria + +- No spike in bounces or "didn't receive email" reports +- Sustained for at least one week + +--- + +## Stage 5: Reject 50% (Week 9-10) + +### Action + +``` +v=DMARC1; p=reject; pct=50; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 4. Legitimate failures will be more visible at higher percentage. + +### Exit criteria + +Same as Stage 4. No spike in legitimate mail rejection. + +--- + +## Stage 6: Reject 100% (Week 11+) + +### Goal +Full enforcement. Spoofing is now blocked. + +### Action + +``` +v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Continue monitoring reports. New senders, configuration drift, and changes in the email infrastructure can introduce new failures over time. + +### Maintenance + +- Review reports at least weekly +- Audit sender list quarterly +- Re-verify SPF and DKIM after any infrastructure change + +--- + +## Optional: Strict alignment + +After `p=reject` is stable, consider tightening alignment: + +``` +v=DMARC1; p=reject; pct=100; rua=...; adkim=s; aspf=s +``` + +Strict alignment requires the From: domain to match exactly (not just a parent domain). This catches subdomain spoofing too. + +Verify in monitoring mode (back to `p=none` with `adkim=s; aspf=s`) before enforcing. + +--- + +## Subdomain policy + +DMARC includes `sp=` for subdomain policy. Without it, subdomains inherit the main policy. + +For high-security applications: + +``` +v=DMARC1; p=reject; sp=reject; ... +``` + +This rejects spoofs on subdomains too. Important for parked or unused subdomains; an attacker can pick any subdomain by default. + +--- + +## Edge cases + +### Forwarders and mailing lists + +When mail is forwarded (e.g., user@oldcompany.com forwards to user@newcompany.com), SPF often fails (the forwarder is now the sender from SPF's view). + +DKIM survives forwarding if the message body isn't modified. Mailing lists that modify headers or add footers can break DKIM. + +Solutions: +- ARC (Authenticated Received Chain): restores authentication across forwards. Major providers support it. +- DKIM only (don't rely on SPF for DMARC alignment): if DKIM passes, DMARC passes regardless of SPF +- Mailing list software that's DMARC-aware + +### Bulk transactional providers + +Some providers (notification services, password reset emails) have hundreds of customers sharing IP space. Authentication usually requires custom domain setup; the default shared sending often fails alignment. + +Solution: configure the provider to use your domain for DKIM and From: address. Most providers offer "custom domain" or "sender authentication" features. + +### Email-on-acid testing services + +If you use email testing services that "send on your behalf" but don't authenticate, those will fail. Either configure them or accept the failure (they're not user-facing). + +--- + +## What can go wrong + +**Legitimate mail starts bouncing.** Roll back to the previous stage immediately. Investigate the failure. Fix. Try again. + +**Spoofing complaints rise.** Counterintuitively, after DMARC enforcement, you may see a temporary rise in complaints because spoofing that was previously delivered (silently spoofed your customers) now bounces (and the spoofer gets a bounce notification, then sometimes complains to the wrong place). This usually settles within a week. + +**Volume of reports overwhelms.** Reports are voluminous from large mailbox providers. Use a DMARC analytics service rather than parsing manually. + +**Forensic reports (`ruf=`) flooding.** Forensic reports include full message content of failures and can be high volume. Many use `rua=` (aggregate) only, especially after Stage 1. + +--- + +## Tools + +- **Reporting/Analytics:** Postmark, dmarcian, EasyDMARC, Valimail, Cloudflare Email Routing (free for some scenarios), or roll your own with a DMARC parser library. +- **Testing:** mxtoolbox.com, mail-tester.com, dmarcian.com. +- **Lookups:** `dig +short txt _dmarc.example.com`. + +--- + +## Timing summary + +| Stage | Policy | Duration | What you're doing | +|---|---|---|---| +| 1 | `p=none` | 1-2 weeks | Discovery | +| 2 | `p=quarantine; pct=10` | 1-2 weeks | Initial enforcement | +| 3 | `p=quarantine; pct=100` | 1-2 weeks | Full quarantine | +| 4 | `p=reject; pct=10` | 1-2 weeks | Initial rejection | +| 5 | `p=reject; pct=50` | 1-2 weeks | Half rejection | +| 6 | `p=reject; pct=100` | Ongoing | Full enforcement | + +Total: 6-12 weeks. Don't shortcut. The cost of moving slowly is low; the cost of breaking legitimate mail is high. diff --git a/skills/email-sequences/SKILL.md b/skills/email-sequences/SKILL.md new file mode 100644 index 0000000..e735886 --- /dev/null +++ b/skills/email-sequences/SKILL.md @@ -0,0 +1,282 @@ +--- +name: email-sequences +description: "Design and write email campaigns and sequences including onboarding flows, lifecycle campaigns, transactional emails, newsletters, broadcast sends, and launch and announcement emails. Use this skill whenever the user wants to write email copy, plan an email sequence, design an onboarding drip, or set up lifecycle email campaigns. Triggers on email sequence, drip campaign, onboarding email, lifecycle email, welcome email, transactional email, newsletter, email broadcast, launch email, announcement email, nurture sequence, abandoned cart, re-engagement, win-back. Also triggers when planning email automation flows or writing email subject lines for campaigns." +category: content +catalog_summary: "Onboarding flows, lifecycle campaigns, transactional copy" +display_order: 5 +--- + +# Email Sequences + +Plan and write email campaigns. Sequences (multi-message flows triggered by events) and broadcasts (one-off sends). Stack-agnostic. Works with any email service provider. + +--- + +## When to use + +- Writing welcome and onboarding email sequences +- Planning lifecycle campaigns (activation, retention, win-back) +- Writing transactional emails (receipts, password resets, notifications) +- Newsletter design and writing +- Abandoned-cart or re-engagement flows +- Writing a one-off broadcast, launch announcement, or news email +- Drafting email subject lines and preview text for any send + +## When NOT to use + +- Landing pages and conversion pages (use `landing-page-copy`) +- Long-form articles (use `content-and-copy`) +- Brand voice work (use `brand-voice`) +- Analytics setup for email (use `analytics-strategy`) + +--- + +## Required inputs + +- The audience (segment or list) +- The trigger or context (signup, purchase, abandonment, time-based, manual) +- The goal of the email or sequence +- Brand voice +- Any technical constraints (provider, deliverability requirements) + +If the audience is undefined, define it before writing. Generic emails to "everyone" perform worse than targeted ones. + +--- + +## The framework: 6 sequence types + +Most email programs run a handful of standard sequence patterns. Each has its own goals, structure, and pitfalls. + +### 1. Welcome / onboarding + +Triggered by signup. Goal: get the user to first value. + +**Typical structure (5 emails over 14 days):** + +- **Email 1 (immediate):** Welcome. Confirm they're in. State what happens next. Single CTA: the next obvious action. +- **Email 2 (day 1 or 2):** First-value step. Help them get to a quick win or core action. +- **Email 3 (day 4 or 5):** Education. Show them something they probably haven't discovered yet. +- **Email 4 (day 8):** Social proof. Customer story or use case relevant to their segment. +- **Email 5 (day 14):** Outcome reminder. Where they could be in 30/60/90 days. Soft commercial cue. + +**Common failure:** Front-loading product features. Users don't care about features yet; they care about getting to value. + +### 2. Lifecycle / activation + +Time- or behavior-triggered. Goal: move users from signup to engaged user. + +**Patterns:** +- Sent when a user completes a milestone (first project, first invite, first export) +- Or sent when a user has NOT completed a milestone after N days +- Each email targets a specific next step + +**Best practice:** Trigger on behavior, not just time. A user who has done 3 onboarding steps doesn't need an email telling them to get started. + +### 3. Retention / engagement + +Ongoing. Goal: keep active users engaged. + +**Patterns:** +- Newsletter (weekly or monthly) +- Product updates +- Tips and tutorials +- Customer-only content (community, behind-the-scenes) + +**Cadence rule:** Frequency that earns the read, not frequency that fills the calendar. Weekly newsletter that is genuinely useful beats daily newsletter that gets archived. + +### 4. Re-engagement / win-back + +Triggered by inactivity. Goal: pull a lapsed user back. + +**Typical structure (3 emails):** + +- **Email 1:** "We miss you" framing or value reminder. What's new since they were last active. +- **Email 2:** Specific incentive (discount, feature unlock, content offer). +- **Email 3:** "Last call" or list-cleaning email. "We'll stop emailing you unless you click this." + +**Best practice:** Honor the unsubscribe. Aggressive win-back damages deliverability. A clean list of engaged subscribers beats a large list of inactive ones. + +### 5. Transactional + +Triggered by actions: receipts, password resets, notifications, order confirmations, shipping updates. + +**Best practices:** +- Confirm the action that triggered the email at the top +- Include all relevant detail without padding +- Use plain language ("Your order shipped" not "Your shipment notification") +- One primary CTA (track package, view receipt, view account) +- Subject line states the action ("Your receipt for order #12345") + +**Highest open rates** of any email type. Use sparingly for marketing nudges; over-marketing transactional emails damages trust. + +### 6. Broadcast + +One-off sends. Announcements, launches, news, time-sensitive campaigns. + +**Best practices:** +- Subject line earns the open +- Single clear message per send +- Specific audience targeting (do not blast the entire list for narrow announcements) +- Clear CTA in the first screen-height +- Mobile-optimized (most opens are mobile) + +--- + +## The 5 components of every email + +Regardless of sequence type, every email has the same components. + +### 1. Subject line + +The deciding factor for whether the email gets opened. + +**Patterns:** +- **Specific** ("Your week 1 progress: 3 of 5 steps done") +- **Curiosity** ("The mistake most teams make in week 2") +- **Direct** ("Your invoice #12345") +- **Personal** ("Quick question, [name]") +- **Urgency** ("Last day for the team plan discount") - use sparingly + +**Avoid:** +- ALL CAPS +- Excessive punctuation (!!!) +- Click-bait that doesn't deliver +- Generic ("Newsletter #23") + +**Length:** 30 to 50 characters. Mobile clients truncate longer. + +### 2. Preview text (preheader) + +The line that appears below or beside the subject in most email clients. + +**Best practice:** +- Treat as the subject's wingman +- Add what the subject line couldn't fit +- Avoid wasting it on "View this email in browser" +- 50 to 90 characters + +### 3. Opening + +The first line of the email body. The reader is deciding whether to keep reading. + +**Strong openings:** +- Reference the trigger ("You signed up yesterday for...") +- Get to the point ("Here's what changed this week...") +- Personal ("Saw your team just hit milestone X. Nice work.") + +**Weak openings:** +- "I hope this email finds you well." +- "Welcome to our amazing platform." +- Long throat-clearing before the actual content + +### 4. Body + +The substance. + +**Length guide:** +- Welcome and transactional: under 100 words +- Lifecycle and activation: 100 to 250 words +- Newsletter: 200 to 800 words depending on format +- Sales sequences: 250 to 500 words + +**Structure:** +- One core message per email (avoid "while we have you...") +- Short paragraphs (2 to 3 lines) +- Bullets or lists when content is enumerable +- Mobile-first formatting + +### 5. CTA + +The action the email is asking for. + +**Best practices:** +- One primary CTA per email (multiple CTAs split attention) +- Button or clearly-styled link, not buried in prose +- Action verb + specific outcome ("See your dashboard" not "Click here") +- Above the fold AND repeated at the end of longer emails +- Plain text link as a fallback for users who block buttons + +--- + +## Workflow + +### For a new sequence + +1. **Define the trigger.** What event starts this sequence? (Signup, purchase, abandonment, manual.) +2. **Define the goal.** What does success look like at the end of the sequence? +3. **Map the journey.** What does the recipient need to know, do, or feel between trigger and goal? +4. **Outline emails.** One purpose per email. Sequence them across appropriate timing. +5. **Draft email 1.** Subject, preview, opening, body, CTA. +6. **Draft remaining emails.** Each builds on the previous. +7. **Test the sequence.** Send to yourself. Read on mobile. Time the gaps. +8. **Set up triggers.** Configure in the email service provider. +9. **Measure.** Open rate, click rate, completion rate per email. Sequence completion rate. + +### For a single broadcast + +1. **Define the audience.** Specific segment, not the whole list. +2. **Define the goal.** One thing this email accomplishes. +3. **Draft subject + preview.** Generate 5 to 10 variations. +4. **Draft body.** Single message, clear CTA. +5. **Test on mobile.** Most opens are mobile. +6. **Schedule.** Day and time matched to audience behavior. +7. **Measure.** Open rate, click rate, downstream conversions. + +--- + +## Failure patterns + +- **Sending to "everyone."** Generic broadcasts to the full list have lower engagement than targeted segments. +- **Too many CTAs in one email.** Splits attention. Pick one. +- **Subject line clickbait that doesn't deliver.** Crashes the trust the email program is trying to build. +- **Sequences that ignore behavior.** Sending day-3 onboarding email to a user who already activated wastes the touch. +- **Mobile-broken layouts.** 60 to 70 percent of opens are on mobile. Test there first. +- **Long pre-text.** Burying the message under "I hope this email finds you well" wastes the read. +- **Aggressive win-back.** Emailing dormant users 5 times damages deliverability and brand trust. +- **No measurement.** Without tracking opens, clicks, and downstream conversion, you can't iterate. +- **Ignoring deliverability.** Sender reputation, authentication (SPF, DKIM, DMARC), list hygiene. Skip these and emails go to spam regardless of how good the content is. + +--- + +## Output format + +Default output is a markdown document per email or sequence: + +```markdown +# Sequence: [Name] + +**Trigger:** [What starts this sequence] +**Goal:** [Outcome at completion] +**Audience:** [Specific segment] +**Length:** [N emails over X days] + +## Email 1 - [Subject working title] + +**Send:** [Trigger / Day N] +**Subject:** [text] +**Preview:** [text] + +[Body] + +**Primary CTA:** [text] +**CTA URL:** [destination] + +--- + +## Email 2 - [Subject working title] + +[Same structure] + +--- + +[etc.] +``` + +For a single broadcast, just one email block. + +--- + +## Reference files + +- [`references/subject-line-patterns.md`](references/subject-line-patterns.md) - Subject line patterns with examples for each sequence type. +- [`references/sequence-templates.md`](references/sequence-templates.md) - Skeleton templates for the 6 sequence types. diff --git a/skills/email-sequences/references/sequence-templates.md b/skills/email-sequences/references/sequence-templates.md new file mode 100644 index 0000000..ac0ca87 --- /dev/null +++ b/skills/email-sequences/references/sequence-templates.md @@ -0,0 +1,252 @@ +# Sequence Templates + +Starter outlines for the 5 standard sequence types. These are scaffolds. Adapt the cadence, voice, and content to the specific brand and audience. + +--- + +## Onboarding sequence (SaaS, 7 emails over 14 days) + +### Email 1 - Welcome +**Send:** Immediately on signup +**Subject:** Welcome to [Product]. Here's your first step. +**Body skeleton:** +- One-line welcome +- Restate the outcome they signed up for +- ONE clear next step +- Optional: founder note for early-stage products + +### Email 2 - First action tutorial +**Send:** T+1 day +**Subject:** [Specific first task] in 5 minutes +**Body skeleton:** +- Hook: Why this first task matters +- 3 to 5 numbered steps +- Visual or screenshot +- CTA back to the product + +### Email 3 - Build on first +**Send:** T+3 days +**Subject:** Now that [first task done], try [second task] +**Body skeleton:** +- Acknowledge progress (works even if user hasn't done first task; it primes them) +- Introduce next capability +- Show what it unlocks +- CTA + +### Email 4 - Use case spotlight +**Send:** T+5 days +**Subject:** How [persona] uses [Product] to [outcome] +**Body skeleton:** +- Specific persona description +- Their workflow with the product +- Specific result +- "Try this approach" CTA + +### Email 5 - Common questions +**Send:** T+7 days +**Subject:** Quick answers to questions new users ask +**Body skeleton:** +- 3 to 5 FAQs with brief answers +- Links to fuller help docs +- CTA: open help center or chat with support + +### Email 6 - Re-engagement check +**Send:** T+10 days (only if user is dormant) +**Subject:** Need a hand getting started? +**Body skeleton:** +- Acknowledge they may be busy +- Offer a 10-minute call or specific resource +- One simple action they can take in <2 minutes + +### Email 7 - Hand-off to ongoing comms +**Send:** T+14 days +**Subject:** You're set up. Here's what to expect from us. +**Body skeleton:** +- Confirm onboarding complete +- Set expectations for future emails (frequency, content type) +- Offer preferences center +- Light next-step CTA + +--- + +## Lifecycle (triggered, individual emails) + +### Anniversary (annual) +**Subject:** Hard to believe - it's been a year +**Body:** Celebrate the milestone, surface specific achievements ("You shipped X projects this year"), suggest next-level use case. + +### Plan upgrade nudge +**Subject:** You're hitting your [Plan] limits +**Body:** Specific data showing usage approaching limits, value of next tier, painless upgrade path. + +### Inactivity check (30 days dormant) +**Subject:** We haven't seen you for a bit +**Body:** Light touch, restate value, surface a recent improvement, easy way to come back. + +### Power user celebration (Y key actions) +**Subject:** You've crossed [Y] [actions]. Nice. +**Body:** Acknowledge the milestone, share advanced tips, invite to community or beta. + +### Feature announcement (when relevant feature ships) +**Subject:** New: [feature] +**Body:** What it does, why we built it, how to start using it. Brief. + +--- + +## Sales nurture (B2B, 9 emails over 28 days) + +### Email 1 - Deliver the asset +**Send:** Immediately on opt-in +**Subject:** Your [asset name] +**Body:** Direct download link, brief intro to what's inside. + +### Email 2 - Educational angle +**Send:** T+2 days +**Subject:** [Specific question the audience asks] +**Body:** Useful content piece tied to their problem. No pitch. + +### Email 3 - Educational angle (different facet) +**Send:** T+4 days +**Subject:** [Adjacent question] +**Body:** Different angle on the same problem space. + +### Email 4 - Customer story +**Send:** T+7 days +**Subject:** How [Customer] [achieved specific outcome] +**Body:** Specific company, specific outcome, specific approach. Their story, with brand as supporting role. + +### Email 5 - Objection handling +**Send:** T+10 days +**Subject:** "I'm not sure [common objection]" +**Body:** Address the most common reason this audience hesitates. Honest, non-defensive. + +### Email 6 - Demo invitation +**Send:** T+14 days +**Subject:** Want to see [Product] in action? +**Body:** 20-minute personalized demo offer. Specific outcome the demo will show. + +### Email 7 - Strong proof + soft pitch +**Send:** T+18 days +**Subject:** [Specific result] in [specific time] +**Body:** Strongest case study, direct invitation to start a trial or call. + +### Email 8 - Urgency +**Send:** T+21 days +**Subject:** [Deadline or limited offer] +**Body:** Clear offer with deadline. Real urgency only - manufactured urgency damages trust. + +### Email 9 - Goodbye +**Send:** T+28 days +**Subject:** Last note from us +**Body:** Acknowledge the silence. Offer one last resource or chance to opt back in. Then suppress or move to long-term nurture list. + +--- + +## Transactional templates + +### Order confirmation +**Subject:** Your order #[number] is confirmed +**Body:** +- Order summary (items, totals, shipping address) +- Estimated delivery +- Order tracking link +- Support contact + +Keep marketing minimal. People are looking for specific info. + +### Password reset +**Subject:** Reset your password +**Body:** +- Brief acknowledgment of the request +- Reset link (with expiration time stated) +- "Did not request this?" instruction +- Support contact + +No marketing in transactional. Keep it clean. + +### Email verification +**Subject:** Verify your email +**Body:** +- One-line ask +- Big verify button +- "If you did not sign up..." opt-out +- Expiration time + +### Abandoned cart +**Subject:** You left these in your cart +**Body:** +- Items left in cart with images +- Quick-resume link +- Optional: incentive (free shipping, small discount) +- Support contact + +Send 1 email at T+1 hour, optional second at T+24 hours, NO third email (annoyance penalty exceeds recovery). + +--- + +## Win-back (5 emails over 20 days) + +### Email 1 - We miss you +**Subject:** Hey, it's been a while +**Body:** Acknowledge the lapse, brief reminder of what's possible, soft re-engage CTA. + +### Email 2 - What's new +**Subject:** A few things have changed since you were last here +**Body:** Updates, new features, recent improvements. Specific. + +### Email 3 - Specific incentive +**Subject:** Come back: [specific offer] +**Body:** Concrete incentive (discount, bonus, free month). Deadline. + +### Email 4 - Last chance +**Subject:** Last call: [offer ends X] +**Body:** Final reminder of the offer. Clear deadline. + +### Email 5 - Sunset +**Subject:** We'll miss you +**Body:** Acknowledge they're not coming back, confirm we're stepping down sends, leave the door open. + +After this email: suppress from active sends. Optional: move to a quarterly "big news only" list. + +--- + +## Cadence rules across all sequence types + +- **Default time of day:** 8 to 10 AM in the recipient's timezone for non-time-sensitive sends. +- **Avoid send fatigue:** Cap at 2 emails per week from the same brand to the same person across all programs. +- **Respect engagement:** If a user has opened zero of the last 5 emails, throttle frequency or sunset. +- **Honor unsubscribes immediately:** Same-day, all programs, no exceptions. +- **Test sending:** Send tests to 5+ devices before any sequence goes live. + +--- + +## Subject line patterns that work + +- **Specific question:** "Why your churn rate isn't moving" +- **Specific number:** "47% of B2B buyers do this before purchasing" +- **Personal/conversational:** "Quick question about [topic]" +- **Curiosity gap:** "The mistake we see in 80% of pricing pages" +- **Negative framing (sparingly):** "Don't make this mistake on your next launch" +- **Direct value:** "Free template: 90-day onboarding checklist" + +Avoid: + +- Subject lines that look like spam (all caps, multiple exclamations) +- Misleading subject lines (mentions in subject that aren't in body) +- Tricks ("Re:" or "Fwd:" on cold sends) +- Subject lines longer than 50 characters where avoidable + +--- + +## Metrics to track per sequence + +| Metric | Target benchmark (rough) | +|---|---| +| Open rate | 20 to 35% (varies wildly by industry) | +| Click-through rate | 2 to 5% | +| Conversion to goal | Sequence-specific | +| Unsubscribe rate per email | <0.5% | +| Spam complaint rate | <0.1% | +| Reply rate (for cold/B2B) | 1 to 3% | + +Below benchmark: investigate the weakest emails in the sequence first. Above: capture what worked and apply to other sequences. diff --git a/skills/email-sequences/references/subject-line-patterns.md b/skills/email-sequences/references/subject-line-patterns.md new file mode 100644 index 0000000..2df7648 --- /dev/null +++ b/skills/email-sequences/references/subject-line-patterns.md @@ -0,0 +1,298 @@ +# Subject Line Patterns + +Subject lines are the deciding factor for opens. A great email with a weak subject gets archived unread. + +These patterns are tools, not formulas. Apply them, then make them sound like the brand. + +--- + +## Universal rules + +- **Length:** 30 to 50 characters. Mobile clients truncate longer. +- **No ALL CAPS.** Reads as shouting and triggers spam filters. +- **No excessive punctuation.** "!!!" reads as desperate. +- **Match the body.** A subject that doesn't deliver in the body kills trust. +- **Sentence case** is more readable than Title Case in inboxes. +- **Skip the prefix conventions** ("Newsletter #23"). Subscribers ignore them. + +--- + +## Pattern 1: Specific outcome + +Names what the reader gets. + +**Examples:** +- "The 5 questions to ask before hiring a designer" +- "Your team's productivity numbers for September" +- "How to cut your invoicing time in half" +- "What changed in your competitor's pricing this month" + +**Strengths:** Clear value. Easy to evaluate whether to open. + +**When to use:** Newsletters, content emails, value-driven sends. + +--- + +## Pattern 2: Curiosity gap + +Opens a loop the email body closes. + +**Examples:** +- "The mistake most teams make in week 2" +- "Why your best customers are leaving" +- "The one habit your top performers share" +- "What I wish I'd known before scaling to 50 people" + +**Strengths:** High open rates when the gap is genuine. + +**Risks:** Becomes click-bait if the body doesn't deliver. Erodes trust over time. + +**When to use:** Sparingly. The body must deliver real insight. + +--- + +## Pattern 3: Personal / direct + +Speaks as if to a friend. + +**Examples:** +- "Quick question, [name]" +- "Saw this and thought of you" +- "Got 5 minutes?" +- "Are you still using [tool]?" + +**Strengths:** Feels human. Cuts through marketing-speak. + +**Risks:** Used by every spam email. Authentic context required for it to work. + +**When to use:** 1:1 sends, personalized cold outreach, founder-to-customer emails. + +--- + +## Pattern 4: Direct / no-mystery + +States exactly what the email is about. + +**Examples:** +- "Your receipt for order #12345" +- "Password reset link" +- "Invoice for September" +- "Meeting confirmation: Tuesday 2pm" + +**Strengths:** High trust. High open rates for transactional content. + +**When to use:** Transactional emails. Always be direct. + +--- + +## Pattern 5: Question + +Poses the question the reader is asking. + +**Examples:** +- "Should you hire a generalist or specialist first?" +- "Is your pricing too cheap?" +- "What's the ROI of customer service?" +- "Are you measuring the wrong KPIs?" + +**Strengths:** Aligns with the reader's mental state. Strong for educational content. + +**When to use:** Newsletters and educational sequences. + +--- + +## Pattern 6: Number / list + +Promises a specific quantity of items. + +**Examples:** +- "3 things to do this week to retain customers" +- "7 signs your team is about to burn out" +- "The 4-step checklist for a clean handoff" + +**Strengths:** Sets clear expectations. Easy to scan. + +**Risks:** Overused. Can read as listicle filler. + +**When to use:** When the content genuinely is a list and the count matters. + +--- + +## Pattern 7: Time-bound / urgency + +Signals the email is time-sensitive. + +**Examples:** +- "Last day: free shipping on your order" +- "Webinar starts in 2 hours" +- "Pricing changes Thursday" + +**Strengths:** Drives immediate action. + +**Risks:** Overuse trains subscribers to ignore urgency cues. Reserve for genuine deadlines. + +**When to use:** Real time-sensitive sends only. Never fake urgency. + +--- + +## Pattern 8: News / update + +States what's new. + +**Examples:** +- "New: instant export to spreadsheets" +- "Just launched: team mode" +- "Update on the integration you asked for" + +**Strengths:** Useful for product update emails. + +**When to use:** Real product announcements that the recipient signed up to hear about. + +--- + +## Pattern 9: Personal anecdote / story + +Hints at a story. + +**Examples:** +- "I almost didn't ship this" +- "What happened when we tried [thing]" +- "The phone call that changed our hiring process" + +**Strengths:** Strong for narrative-driven brand newsletters. + +**When to use:** When the brand voice supports storytelling. + +--- + +## Pattern 10: Reference to recipient's behavior + +Acknowledges what they did. + +**Examples:** +- "Saw you tried [feature] - here's what's next" +- "Welcome back. Here's what you missed." +- "You completed week 1. Here's week 2." + +**Strengths:** Personalization that actually feels personal. + +**When to use:** Behavior-triggered emails. Lifecycle and onboarding sequences. + +--- + +## Subject lines by sequence type + +### Welcome / onboarding + +``` +Email 1: Welcome to [Brand], [name] +Email 2: The first thing to do in [Brand] +Email 3: How [audience] use [Brand] (3 examples) +Email 4: Did this happen for you? +Email 5: 30 days in: where you could be +``` + +### Lifecycle / activation + +``` +Trigger: completed milestone +"Nice work hitting [milestone]. Here's what's next." + +Trigger: stalled on a step +"Quick question about your setup" +``` + +### Re-engagement / win-back + +``` +Email 1: Hey [name], we miss you +Email 2: Here's [specific incentive] +Email 3: Last email - should we say goodbye? +``` + +### Newsletter + +``` +Curiosity: "The metric most teams ignore" +Specific: "September wrap: what we shipped, what we learned" +Question: "Should you raise your prices?" +Number: "3 reads from this week" +``` + +### Transactional + +``` +"Your order is on the way (#12345)" +"Receipt for your subscription" +"Your password was changed" +"Action required: confirm your email" +``` + +### Broadcast + +``` +Launch: "Just shipped: [feature]" +Event: "Live this Thursday: [topic]" +Update: "Our pricing changed today. Here's what it means for you." +``` + +--- + +## A/B test ideas + +Subject lines are the easiest thing to test. For any meaningful send, generate 2 to 4 variations along these axes: + +- **Specific vs. curiosity:** Does the audience prefer to know what they're getting, or to be intrigued? +- **Personal vs. direct:** Does first-person ("I just shipped this") work better than third-person ("Just launched")? +- **Length:** Short (under 30 chars) vs. medium (30 to 50 chars). +- **Punctuation:** Question vs. statement. +- **Personalization:** With name vs. without. + +Track open rates and click-through rates. Open alone is incomplete; some subject patterns get opened but discarded. + +--- + +## What to avoid + +### "Just checking in" +Empty. Adds no value. Reads as nag. + +### "Following up" +Same problem. The reader knows you're following up. Tell them why. + +### "Thoughts?" +A request without context. Comes across as lazy. + +### "Hi" +Just don't. Even from someone you know. + +### Excessive emojis +🎉🚀✨ does not signal value. Often signals spam to filters. + +### Re: when it's not actually a reply +Deceptive. Damages trust. + +### Personalization gone wrong +"{first_name} wanted to chat" with the variable un-rendered. Test send before broadcast. + +--- + +## Preview text (preheader) + +The line that appears next to or below the subject. Often more important than the subject for engagement. + +**Best practice:** +- Use it as the subject's continuation +- 50 to 90 characters +- Don't waste it on "View in browser" or boilerplate +- Add the detail the subject didn't fit + +**Examples of subject + preview pairs:** + +| Subject | Preview | +|---|---| +| "Your week 1 progress" | "3 of 5 steps complete. Here's what's next." | +| "The mistake most teams make" | "(It's not the obvious one)" | +| "Just shipped: team mode" | "Invite up to 50 teammates and assign roles." | + +A weak preview wastes prime real estate. A strong preview can save a mediocre subject. diff --git a/skills/evidence-based-reviews/SKILL.md b/skills/evidence-based-reviews/SKILL.md new file mode 100644 index 0000000..5f0a4f2 --- /dev/null +++ b/skills/evidence-based-reviews/SKILL.md @@ -0,0 +1,161 @@ +--- +name: evidence-based-reviews +description: "Produce honest product reviews and buying guides without fabricated first-hand experience, using disclosed evidence tiers: verified specs, owner-experience synthesis at scale, expert triangulation, and hands-on only when true. Use this skill whenever the user wants to write product reviews or buying guides without hands-on access, set up a review methodology, add evidence disclosure to review content, align reviews with Google's reviews system or FTC affiliate disclosure expectations, or decide when Review and Product schema are honest to use. Triggers on product review, buying guide, best-of list, review methodology, evidence basis, hands-on testing, we tested, affiliate review site, review disclosure, methodology block, original research, reviews system. Also triggers when review content claims testing that did not happen, or when an affiliate site needs a trust mechanism that survives scrutiny." +category: content +catalog_summary: "Evidence tiers, methodology disclosure, honest review claims" +display_order: 13 +--- + +# Evidence-Based Reviews + +Produce product reviews and buying guides whose claims match their evidence. The method is evidence synthesis with a disclosed basis, and one rule anchors everything: never claim hands-on time that did not happen. + +Most review sites fail this rule quietly. "We tested" appears above content assembled from spec sheets, and readers have learned to smell it. The honest alternative is stronger, not weaker: synthesis of owner experience at scale, verified specifications, and triangulated expert sources is demonstrable original analysis, and disclosing it builds the trust that fabricated testing destroys. + +--- + +## When to use + +- Writing product reviews or buying guides when hands-on access is partial or absent +- Setting up the review methodology for a new review or affiliate site +- Adding evidence disclosure to existing review content +- Auditing review content for claims its evidence cannot support +- Deciding whether Review or Product schema is honest for a given piece +- Aligning review content with Google's reviews system and FTC disclosure expectations + +## When NOT to use + +- General content writing and editing (use `content-and-copy`; this skill governs the evidence and claims layer of review content specifically) +- Defining how the brand sounds (use `brand-voice`) +- Optimizing the review page itself for search (use `seo-onpage`) +- Per-piece editorial briefs (use `content-brief-authoring`) +- Instructional how-to content that teaches a procedure or concept to a first-time reader, such as a tutorial or an explainer: a teaching piece of this kind is owned by its writing, its structure, and its search craft, with the evidence discipline riding alongside as a constraint on its claims, so this skill is one input among several rather than the single choice for it + +If genuine hands-on testing at scale exists, with instrumentation and protocols, this skill still applies: the tiers do not change, the methodology block simply states tier 4 and the testing protocol becomes the disclosed basis. + +--- + +## Required inputs + +- The product category and the pieces planned (reviews, buying guides, or both) +- Access to evidence sources: manufacturer pages, retailer review corpora, forums or owner communities, expert publications +- The brand's disclosure language, if one exists (this skill supplies a template if not) +- An honest inventory of what hands-on experience genuinely exists, if any + +--- + +## The framework: one rule, four evidence tiers + +The anchor rule: never claim hands-on time that did not happen. Every other part of the method exists to make honest content strong enough that the lie is unnecessary. + +### Tier 1: verified manufacturer specs + +Specifications cited to the maker's own page, not to aggregator copies that drift. The verification step is the work: cross-check the spec against the manufacturer's current listing, note the date, and flag discrepancies between sources instead of picking one silently. A spec table built this way is a fact layer; a spec table pasted from another review site is a rumor layer. + +When it suffices: factual comparisons, fit and compatibility answers, price-tier groupings. It never supports a quality verdict on its own. + +### Tier 2: owner-experience synthesis at scale + +Retailer review corpora, forum threads, warranty and return patterns, read across sources and summarized honestly. Honest synthesis means: + +- Recurring complaints and recurring praise, not the loudest single anecdote +- Sample-size candor: "across roughly 1,400 owner reviews" reads differently from "owners say," and the reader deserves the number +- No cherry-picking: if owners split, the split is the finding +- Source naming: which corpora, which communities, over what period + +When it suffices: durability and reliability verdicts, real-world quirks specs never show, satisfaction patterns by use case. This tier is the workhorse of honest no-hands-on reviewing, and it is genuine original analysis when done at scale. + +### Tier 3: expert-source triangulation + +Named expert sources compared against each other. Triangulation means surfacing agreement and disagreement, not averaging verdicts into mush. When two credible testers reach opposite conclusions, the honest move is to say so and explain the conditions that might account for it. Anonymous "experts agree" is not a tier; it is decoration. + +When it suffices: performance claims that require instrumentation the site lacks, technique-dependent judgments, category context. + +### Tier 4: hands-on, only when true + +Stated only when it happened, flagged as such, with the extent quantified: what was done, how much, under what conditions. When hands-on experience arrives later for a piece published on tiers 1 to 3, the piece is upgraded and the update is marked with what changed. Never backfilled to look like it was always hands-on; the upgrade trail is itself a trust signal. + +--- + +## The methodology block + +Every review and buying guide carries a short disclosure block naming its evidence basis, placed with the criteria, written for readers rather than lawyers. The fillable template and a worked example live in [`references/methodology-block-template.md`](references/methodology-block-template.md). + +The block names: the criteria in the order they were weighted, the tiers actually used (specifically, with sources), what was done hands-on or the words "none claimed," and the update line. A block that claims a tier the piece did not use is the same lie the anchor rule bans, in smaller type. + +--- + +## Structure discipline the method implies + +- **Criteria stated and ordered before picks.** A verdict the reader cannot trace to a stated criterion is an opinion wearing a methodology costume. +- **A named drawback per recommended pick.** Every product has one; a review that finds none has not looked. Consistent placement makes the honesty visible. +- **Update transparency.** Dated updates with what changed. Stale best-of content silently rotting is one of the most common failures in the category, and a dated what-changed line beats the field. + +--- + +## Google reviews-system alignment + +The guidance asks for demonstrated first-hand experience OR demonstrable original research and analysis. The second branch is this skill's lane, and "original analysis" means concrete work product: + +- The synthesis itself: owner-experience patterns no single source contains +- Comparative tables built from verified data, structured around the stated criteria +- Decision frameworks: who each pick fits and who it does not +- What paraphrased spec sheets are not: rearranging a manufacturer's bullet points is neither experience nor analysis, and ranks accordingly + +A site that does tier 2 and 3 work honestly is doing original analysis by the guidance's own definition. The methodology block is how the work shows. + +--- + +## FTC alignment + +Affiliate relationships are disclosed in plain language, placed where the recommendation is, not in a footer. The disclosure travels with the monetized content: near the picks, in body-size text, before or beside the first affiliate link a reader can act on. "Plain language" means a reader who has never heard the word affiliate understands that the site earns a commission and that the price they pay does not change. Euphemisms ("partner links," "support the site") fail the plain-language test. + +--- + +## Schema judgment + +Markup is a claim. Apply the same honesty to structured data as to prose: + +- **Review and Product markup** only when the piece's claims support what the markup asserts. Review markup asserts an evaluative review of an item the reviewer assessed; a tier 1-to-3 buying guide asserting hands-on style review markup is making a machine-readable version of the banned claim. +- **Buying guides without hands-on** use guide-shaped markup: ItemList for the picks, Article for the piece. +- When tier 4 is real and stated, Review markup becomes honest; add it then, per piece, not as a template default. + +--- + +## Workflow + +1. **Inventory the evidence honestly.** What tiers are actually available for this category? What hands-on exists, if any? +2. **Set the criteria first.** Ordered, before any product is examined, so the criteria cannot quietly bend toward a favored pick. +3. **Gather per tier.** Verify specs at the source. Pull owner corpora at scale and note sample sizes. Collect named expert sources, including the disagreements. +4. **Synthesize.** Findings per criterion, drawbacks per pick, splits surfaced. +5. **Write the methodology block** from what was actually done, not from what sounds good. +6. **Match the markup to the claims.** ItemList and Article by default; Review only where tier 4 is true. +7. **Maintain.** Date updates, state what changed, upgrade pieces when hands-on arrives, and mark the upgrade. + +--- + +## Failure patterns + +- **"We tested" inflation.** The anchor-rule violation. It is also unnecessary: honest synthesis outperforms fake testing once readers compare the work. +- **Aggregator specs.** Spec tables copied from other reviews, drift included. Verify at the maker's page or do not publish the number. +- **Anecdote dressed as synthesis.** Three forum posts is not owner experience at scale. State the sample or downgrade the claim. +- **Averaged experts.** Splitting the difference between conflicting expert verdicts erases the most useful information: that credible testers disagree, and why. +- **The drawback-free pick.** A recommendation with no named drawback reads as advertising because it is structured like advertising. +- **Backfilled hands-on.** Quietly rewriting an old synthesis piece as if it had been tested all along. The upgrade-and-mark pattern exists so this never has to happen. +- **Footer disclosure.** An affiliate disclosure the reader has to hunt for fails both the FTC's placement expectations and the trust purpose it exists to serve. +- **Schema overreach.** Review markup on synthesis content. The piece's prose is honest and its markup lies. + +--- + +## Output format + +For a methodology setup: a short methodology standard the site adopts (the tiers, the block template filled with the site's sources, the schema policy), suitable for docs or an editorial guide. + +For a piece-level engagement: the methodology block for that piece, the criteria list, the evidence file (sources gathered per tier with sample sizes), and the claims audit if the piece existed before this skill did. + +--- + +## Reference files + +- [`references/evidence-tiers.md`](references/evidence-tiers.md) - The four tiers in depth: verification steps, synthesis honesty, triangulation practice, and the upgrade-and-mark pattern. +- [`references/methodology-block-template.md`](references/methodology-block-template.md) - The fillable per-piece disclosure block, a worked example, and placement rules. diff --git a/skills/evidence-based-reviews/references/evidence-tiers.md b/skills/evidence-based-reviews/references/evidence-tiers.md new file mode 100644 index 0000000..b348f67 --- /dev/null +++ b/skills/evidence-based-reviews/references/evidence-tiers.md @@ -0,0 +1,46 @@ +# The four evidence tiers, in depth + +The tiers are not a ladder of prestige; they are different kinds of knowledge with different verification work and different claims they can support. A strong piece usually combines two or three, and says which. + +## Tier 1: verified manufacturer specs + +**The verification step.** Cite the specification to the manufacturer's own current product page. Aggregators, retailer listings, and other reviews drift: units get converted wrong, superseded model years linger, and one site's typo becomes the category's consensus number. When the manufacturer's page and a retailer listing disagree, note the discrepancy in the piece; the disagreement is information. + +**Date the pull.** Specs change across model years. A spec table that says when its numbers were verified survives the next revision; one that does not becomes silently wrong. + +**What tier 1 supports:** factual comparison (weights, dimensions, capacities, materials), compatibility and fit answers, price-tier groupings. **What it cannot support:** any quality verdict. A spec sheet cannot tell you the thing rattles. + +## Tier 2: owner-experience synthesis at scale + +The workhorse tier for review work without hands-on access, and the one most often done dishonestly. The honest version: + +**Scale and candor.** Read across sources: retailer review corpora, owner forums, warranty and return discussions. State the scale in the piece ("across roughly 1,400 retailer reviews and two seasons of forum threads"). If the sample is small, say so and weaken the claim to match. + +**Recurrence over volume.** The finding is the pattern that recurs across independent sources, not the most dramatic single report. One catastrophic failure post is an anecdote; the same failure described by unrelated owners across two sites is a finding. + +**Splits are findings.** When owners divide (half love the trigger, half send it back), the split is the most useful thing the piece can report, usually with the variable that explains it (hand size, draw weight, use case). + +**No cherry-picking.** Deciding the verdict first and quoting only supporting owners is fabrication with extra steps. The synthesis is written from the pattern, not toward a pick. + +**Name the corpora.** Which retailers, which communities, what period. This is what makes the synthesis auditable and what makes it original analysis rather than vibes. + +## Tier 3: expert-source triangulation + +**Named sources only.** "Experts agree" without names is decoration. Name the publication or tester, and link where possible. + +**Triangulate, never average.** Three credible sources agreeing is strong signal; two credible sources disagreeing is stronger content. Surface the disagreement and look for the condition that explains it: different test protocols, different units, different use assumptions. Averaging opposite verdicts into "mixed reviews" throws away exactly what the reader came for. + +**Independence check.** Three reviews that all trace to the same press kit are one source wearing three hats. + +## Tier 4: hands-on, only when true + +**Quantify the experience.** "We shot it" hides more than it tells. The honest form states extent and conditions: how many arrows or hours or miles, over what period, in what setting, with what comparison points. The quantification is what separates a real claim from a vibe. + +**Flag it.** On a site where synthesis is the norm, hands-on time is the exception worth marking. Flagging it does double duty: it strengthens the piece that has it and keeps every other piece honest by contrast. + +**The upgrade-and-mark pattern.** When hands-on experience arrives for a piece originally published on tiers 1 to 3: + +1. Update the piece with the hands-on findings. +2. Update the methodology block: the hands-on line changes from "none claimed" to the quantified statement. +3. Mark the update with the date and what changed ("Updated [date]: added hands-on findings after six weeks with the production unit; the durability verdict held, the comfort note changed"). +4. Never rewrite history. The piece does not pretend it was always hands-on; the visible upgrade is itself evidence the site's claims mean something. diff --git a/skills/evidence-based-reviews/references/methodology-block-template.md b/skills/evidence-based-reviews/references/methodology-block-template.md new file mode 100644 index 0000000..7ac4b6b --- /dev/null +++ b/skills/evidence-based-reviews/references/methodology-block-template.md @@ -0,0 +1,33 @@ +# The methodology block: template, example, placement + +The per-piece disclosure block. Short, placed with the criteria, written for readers. It names what the piece's verdicts rest on, and it never claims a tier the piece did not use. + +## The template + +> **How we reviewed this** +> **Criteria:** [the 3 to 5 criteria, in the order they were weighted, stated before the picks]. +> **Evidence:** [the tiers actually used, specifically: verified manufacturer specs (noting where and when); owner-experience synthesis at scale (name the corpora and the rough sample size); expert-source triangulation (name the sources)]. +> **Hands-on:** [what was physically done, quantified, or the words "none claimed for this piece"]. +> **Updated:** [date]: [what changed and why]. + +## A worked example (generic category) + +> **How we reviewed this** +> **Criteria:** noise under load, durability across a season, build quality, price against the field, in that order. +> **Evidence:** manufacturer specs verified against each maker's current product page (May 2026); owner-experience synthesis across roughly 1,400 retailer reviews and two seasons of forum threads from three owner communities; expert triangulation across two named publications, whose durability verdicts disagreed (the disagreement and the likely cause are discussed under pick 2). +> **Hands-on:** none claimed for this piece. +> **Updated:** June 2026: replaced the budget pick after recurring owner reports of a failed adjustment mechanism; previous pick moved to the skip-it section with the evidence. + +## Placement rules + +- The block sits with the criteria, before or immediately after the picks summary, never below the fold of a long piece and never in a footer. +- Body-size text. A disclosure styled to be skipped is a disclosure in name only. +- The hands-on line is mandatory even when the answer is "none claimed." The absence stated plainly is the trust mechanism; the absence omitted is the lie of implication. +- The affiliate disclosure is a sibling, not a substitute: it travels with the recommendation per FTC expectations and says in plain language that the site earns a commission and that the reader's price does not change. The methodology block discloses the evidence; the affiliate block discloses the money. A piece with affiliate links carries both. + +## Anti-patterns + +- A block that lists every tier the site has ever used instead of the tiers this piece used. +- "Extensive research" as the evidence line. Name the corpora or do not claim the scale. +- A block written in legal register. The reader should finish it trusting the piece more, not feeling warned. +- The block as template default with fields unfilled. An unfilled block is a claim generator; every line must be true per piece. diff --git a/skills/experiment-design/SKILL.md b/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..c858add --- /dev/null +++ b/skills/experiment-design/SKILL.md @@ -0,0 +1,255 @@ +--- +name: experiment-design +description: A discipline for designing experiments (A/B tests, multivariate, holdouts) so the results actually answer the question you asked. Hypothesis writing, sample size, duration, segment analysis, interpretation, decision-making, and the common failure modes that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Hypothesis to decision: sample size, duration, segment analysis, interpretation, and the failure modes that produce wrong shipping calls" +display_order: 4 +--- + +# Experiment Design + +A senior product manager's playbook for running experiments that produce trustworthy decisions. + +The default state of experimentation in most companies is sloppy. PMs run tests against vague hypotheses, look at results too early, ignore guardrails, stratify into noise, and ship features whose lift is mostly measurement error. The cost is real: ship the wrong thing, kill the right thing, learn the wrong lesson, repeat. + +This skill is the discipline that prevents most of those mistakes. It assumes you have a working experimentation platform (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon; the platform does not matter for the principles). It assumes you have product-design and engineering pipelines that can deliver real treatment changes. The hard part is the thinking, and that is what is here. + +When to use this skill: any time you are about to design or interpret an experiment. Read the relevant section before you start, not after the test is running. + +--- + +## What this skill covers + +The skill spans the full experiment lifecycle. Pre-experiment readiness (is this thing even worth testing). Hypothesis design (cause, effect, magnitude, mechanism). Sample size and minimum detectable effect (do you have enough traffic to learn anything). Duration (how long is long enough, when does the cycle bias the result). Running discipline (no peeking, guardrails, sequential testing). Interpretation (the three buckets and the inconclusive case). Decision-making (matching the result to a pre-committed rule). + +The skill does not cover feature flag operational mechanics; those live in the `feature-flagging` skill, which handles flag taxonomy, environment management, and stale-flag cleanup as a separate discipline. The skill does not cover statistical analysis depth; for delta methods, variance reduction techniques like CUPED, and Bayesian alternatives, see the `experimentation-analytics` skill. The skill does not cover platform-specific tooling; for MCP commands, auth models, and platform-specific configuration, consult the chosen platform's official documentation. This skill produces the experiment design; the platform implements it. + +For the orchestration layer above (which experiments to run, in what order, with what cadence), see the forthcoming `experimentation-platform-orchestrator` skill. That skill schedules; this skill designs. + +--- + +## The framework: 12 considerations for trustworthy experiment results + +A defensible experiment design sits at the intersection of twelve considerations. Each is covered in detail in its own section below. + +1. **Hypothesis discipline.** Cause, effect, magnitude, and mechanism. The hypothesis names what is being tested, what should move, by how much, and why. +2. **Sample size and minimum detectable effect (MDE).** Whether the test has enough traffic to detect the effect at the chosen power. Refuse to run underpowered tests. +3. **Test duration.** Longer of the sample-size-hit duration and a full weekly cycle. UI/UX changes need at least 14 days regardless. +4. **What NOT to A/B test.** UX bugs, legal-required changes, brand-philosophy questions, decisions already made, designs whose randomization cannot be clean. +5. **Segment analysis.** Pre-registered segments are evidence; post-hoc segments are noise mining. The multiple comparisons problem is real. +6. **Interaction effects.** Concurrent tests on the same surface can interfere. Mutex enforcement or coordination required. +7. **Ratio metrics and variance estimation.** Naive variance estimators on ratios understate uncertainty. Confirm the platform uses a ratio-aware estimator. +8. **Network effects and two-sided markets.** Treatment can leak into control via interference. Cluster randomization, switchback, or geographic isolation when needed. +9. **Sequential testing and the peeking problem.** Daily peeking inflates false positive rates. Use sequential testing methods when available; pre-commit otherwise. +10. **Pre-commitment vs p-hacking.** Write down the primary metric, MDE, duration, segments, and decision rule before launch. Apply mechanically when results come in. +11. **Reading results and making the call.** Three buckets: clear win, clear loss, inconclusive. The inconclusive bucket exists for a reason; resist the pull to ship anyway. +12. **Common failures and fixes.** A short rapid-fire pattern catalog, expanded in [`references/common-failures.md`](references/common-failures.md). + +The sections below cover each consideration in turn. Read the relevant section before running the experiment, not after. + +--- + +## Hypothesis discipline + +The most important section in the skill. Most experiment failures trace back to a vague hypothesis. + +A real hypothesis has four parts: cause, effect, magnitude, mechanism. Cause is the change you are making. Effect is the metric you expect to move. Magnitude is how much you expect it to move and from what baseline. Mechanism is why you expect this change to produce this effect. + +Bad hypothesis, common shape: "We think the new pricing page will increase conversions." What is wrong with it: no magnitude (how much), no mechanism (why), and the metric is "conversions" rather than a specific event with a clear definition. The team will run this test, look at the result, and argue about what counts as a win. Pre-commitment is impossible because nothing was committed. + +Good hypothesis, same domain: "Replacing the three-tier pricing comparison with a single recommended tier will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe." Cause is the tier replacement. Effect is signup-to-paid conversion, defined as the user reaches the paywall and completes payment within seven days. Magnitude is 8 percent relative lift, taking the rate from 12 to 13 percent absolute. Mechanism is decision friction reduction. Now the team has something to test, a number to hit, and a story to falsify. + +Primary metric vs guardrails. The primary metric is the thing you are trying to move. Guardrails are the things that must not break: revenue, retention, support ticket volume, page load time, error rates. Pick exactly one primary metric. Pick three to five guardrails. Multiple primary metrics destroy the discipline because they let you cherry-pick the favorable one when results come in. + +Falsifiability test. Before launching the experiment, write down what would make you NOT ship this. If the answer is "nothing, we are committed to the change regardless," the hypothesis is not real and the experiment is theater. Skip the test, save the engineering time, and just ship the change. + +Directional vs magnitude distinction. Knowing the change moves the needle is different from knowing it moves the needle enough to matter. A 0.3 percent absolute lift on signup conversion may be statistically significant with enough traffic and still not justify the engineering cost of maintaining the change. Magnitude matters as much as direction; the hypothesis names the magnitude that would justify shipping. + +For templates and worked examples across common metric types, see [`references/hypothesis-templates.md`](references/hypothesis-templates.md). + +--- + +## Sample size and minimum detectable effect + +Sample size grows with the inverse square of the effect you want to detect. Detecting a 1 percent lift requires roughly one hundred times the sample needed to detect a 10 percent lift. Most PMs underestimate this. + +The basic decision rule: if your minimum detectable effect (MDE) at current traffic and a reasonable test duration is greater than 5 percent absolute lift, you probably need a bigger MDE. Tiny changes that need huge samples to detect are usually not worth shipping anyway. The change is small either because the underlying mechanism is weak or because the implementation is timid. A weak mechanism is not worth a launch. A timid implementation should be made bolder before testing. + +The "we do not have enough traffic" trap. Real for very small products. Lazy for everyone else. If you have ten thousand users a week and you are trying to detect a half-percent absolute lift, you are not running an experiment, you are sampling noise. Pick changes whose expected effect is large enough to detect at your traffic level. If the change is genuinely small, ship it without a test (small upside, small downside, low cost) or do not ship it at all. + +Power. The test's ability to detect an effect that is actually present. The conventional floor is 80 percent. Below that, you are rolling dice; the test will frequently miss real effects. Higher power costs more sample. Most platforms default to 80; if you change it, document why. + +One-sided vs two-sided. Most PM tests are two-sided despite the temptation to claim otherwise. A one-sided test says "I only care about the positive direction; if the change makes things worse, I do not need to detect it." That is rarely true. If the new pricing page tanks conversion, you want to know. Default to two-sided. If you genuinely want one-sided, document the asymmetry before running. + +For pre-calculated sample size tables across common conversion rate baselines and MDEs, see [`references/sample-size-tables.md`](references/sample-size-tables.md). The tables are starting points, not substitutes for running the math against your specific traffic and metric. + +--- + +## Test duration + +Minimum duration is the longer of two constraints. Constraint one: the sample size hits the calculated requirement. Constraint two: the test runs at least one full weekly cycle. Testing only Monday through Wednesday misses weekend behavior, which on most consumer products differs meaningfully from weekday behavior. + +Novelty effects. New things attract attention. The first few days of a winning test often overstate the lift. Users notice the change, click it, and produce a temporary effect that fades as the novelty wears off. Run long enough to see if the lift survives the novelty period. Two weeks is the conventional minimum for any UI/UX experiment, even if the sample size hits faster. + +Primacy effects. The opposite problem. Existing users may resist the change in week one and adapt by week three. Common in UI rearrangement tests. Killing the test in week one because the result looks negative misses the point that primacy is bigger than the underlying effect at that timescale. + +Holdout periods. If the experiment changes a permanent feature (notification frequency, default settings, search ranking), keep a holdout group OFF the new behavior for at least a month after launch. The holdout measures long-term effect, not just the day-1 lift. Long-term effects are often different from short-term effects: a notification change that increases day-1 engagement may decrease month-three retention. + +Maximum duration. Usually four to six weeks. Beyond that, the world changes around the test. Seasonality shifts. Marketing campaigns launch. The product evolves. The comparison between treatment and control stops being clean because the underlying user population is no longer comparable across the test window. If the test needs to run longer than six weeks to hit power, the MDE is probably wrong; the change is too small to detect cleanly. + +--- + +## What NOT to A/B test + +This is a section many discussions of experimentation skip. Worth being direct about. + +UX bug fixes. If the current behavior is objectively broken (button does not work, copy says the wrong thing, accessibility fails), fix it. A/B testing it is theater. The right answer is not "let's see if our users prefer a working button"; the right answer is to ship the working button. + +Legal-required changes. GDPR consent flows, accessibility compliance, regulatory disclaimers. Ship them. The lift is irrelevant; the compliance is the point. A/B testing whether to comply with the law is not a serious question. + +Strategic or philosophical brand questions. "Should our voice be playful or serious?" is not an A/B test question; it is a brand strategy question that needs to be made by humans with context, weighed against brand equity, audience expectation, and long-term positioning. Picking the variant with the higher click-through rate does not answer it because click-through rate was not the brand decision. Use the experiment data as one input to the brand decision, not as the decision itself. + +Things you have already decided. If leadership has committed to a direction regardless of test result, do not run an experiment. A/B testing as theater (running tests where the outcome does not change the decision) corrodes trust in the experimentation discipline overall. Other PMs see the test, see the result ignored, and conclude that experiment results do not matter at this company. Then they stop pre-committing. Then the discipline collapses. + +Things where the test design is impossible. Cross-device experiences, network effects, internal tooling for a ten-person ops team, anything where the sample size is fundamentally too small or the randomization is fundamentally contaminated. Sometimes the right answer is qualitative research, longitudinal cohort analysis, or just shipping and watching. An experiment that cannot be designed cleanly will not produce a clean answer. + +--- + +## Segment analysis + +Pre-registered segments versus post-hoc segments. Declaring before the test runs that "we will look at the result for new users versus returning users" is fine. Discovering after the test that "users from California who signed up on Tuesdays via mobile" had a huge lift is almost always noise mining. + +The multiple comparisons problem. Every additional segment you analyze increases the probability of finding a "significant" result by chance. With twenty independent segments at p equals 0.05, you expect one false positive purely by chance. With fifty segments, two or three. Do not analyze fifty segments and report the one that hit significance. + +When stratification helps versus misleads. Stratification is useful when three things are true. The segment was pre-registered. There is a real prior reason to expect different behavior in this segment. There is enough sample within the segment to detect the effect at the chosen power. If any of the three is missing, stratification is noise mining. The default posture should be: report the overall result. Report pre-registered segments as additional context. Do not report unplanned segments. + +The "weighted average" reframe. If a treatment is positive for one segment and negative for another, the right question is "what is the weighted average effect across the population we will actually ship to" not "let's just ship to the segment where it works." Shipping to a segment usually requires UI complexity, audience targeting infrastructure, and ongoing maintenance that the segment-specific lift does not justify. The bias against segment-specific shipping is healthy. + +--- + +## Interaction effects + +The classic problem: you are running five concurrent A/B tests on the checkout flow. Each test individually shows a small lift. Together, the combinations may not multiply cleanly. They may not even sum cleanly. They may interfere in ways the individual tests cannot reveal. + +Pre-experiment hygiene. Before launching a new experiment, check what other experiments are running on the same surface. Ask the other PM owners. Coordinate on which tests are mutually exclusive and which can overlap. + +Mutex (mutually exclusive) experiment groups. Most platforms support exclusion rules so users in test A are not also in test B. Use them when interactions are likely. The cost is sample size; the benefit is interpretable results. For a small set of high-stakes tests, mutex is the right call. For dozens of lower-stakes tests, full mutex is impractical; coordinate and document overlap instead. + +The "we will analyze it later" fallacy. Post-hoc detangling of overlapping experiments is hard, expensive, and usually inconclusive. The factorial design that would isolate interaction effects requires sample sizes most products do not have. Coordinate up front rather than untangle afterwards. + +--- + +## Ratio metrics and the delta method + +The trap. Conversion rate is a ratio: conversions divided by users. Standard deviation calculations for raw counts do not apply directly to ratios. A naive variance estimate on a ratio metric tends to be too narrow, leading to overstated confidence and false-positive ship decisions. + +Why it matters. Many experimentation platforms quietly use the delta method (or bootstrap, or some other ratio-aware estimator) for ratio metrics. If yours does not, your confidence intervals are wrong. Wrong in the direction that matters: you ship things that look significant but are not. + +How to check. Ask your platform vendor: "What is your variance estimator for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (converted yes or no, with one row per user). If the answer is "delta method" or "bootstrap with re-sampling at the user level" or "linearization with Taylor expansion," that is correct. Other reasonable answers exist; the test is whether the platform team can articulate a ratio-aware estimator at all. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. RPU lift estimates that do not use a ratio-aware estimator tend to overstate confidence. A 5 percent reported lift with p equals 0.04 might actually be a 5 percent point estimate with no statistical significance once the variance is computed correctly. Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production. + +For deeper coverage of variance reduction (CUPED, stratified sampling, control variates), see the `experimentation-analytics` skill when it ships. + +--- + +## Network effects and two-sided markets + +The interference problem. In a two-sided marketplace (Uber, Airbnb, eBay, DoorDash, any platform with buyers and sellers), a treatment for buyers may affect sellers regardless of which group is in the test. A treatment that increases buyer demand changes seller behavior. The "control" buyers, who are competing for the same sellers, see different supply because of treatment buyers' actions. The test no longer measures the treatment effect cleanly; it measures treatment effect plus interference. + +Common pattern. Marketplace experiments where the control group is contaminated. The test reports a small effect because half the effect leaked into the control. The team underestimates the true effect, kills a winning idea, and learns the wrong lesson. + +Mitigations, none perfect. Cluster randomization assigns whole markets (cities, regions, market segments) to treatment or control rather than individual users. Eliminates within-cluster interference but reduces effective sample size by orders of magnitude. Switchback experiments alternate the entire population between treatment and control across time windows (week 1 treatment, week 2 control, week 3 treatment, etc.). Eliminates cross-user interference but requires careful temporal modeling. Geographic isolation runs the experiment in one city while keeping the rest of the network on the original behavior. Eliminates interference but is expensive and slow. + +When to call qualitative. If interference is severe and randomization cannot isolate it, the test will not tell you what you want to know. Switch to user research, longitudinal cohort analysis, or a phased rollout with careful instrumentation. The decision is "do we believe this works enough to invest in the rollout monitoring" rather than "did the lift hit significance." + +--- + +## Sequential testing and the peeking problem + +The peeking problem. If you check results every day and stop the test as soon as you see significance, your false positive rate is much higher than the nominal 5 percent. Standard statistical tests assume one analysis at the end of the test. Multiple analyses inflate alpha. + +The math. With one analysis, false positive rate is 5 percent (at alpha equals 0.05). With three analyses spread across the test, false positive rate climbs toward 14 percent. With daily peeking on a 28-day test, false positive rate can exceed 30 percent. You will see "significant" results that are not real, ship them, and watch them fail to replicate in production. + +Sequential testing methods. Most modern platforms (Statsig, Eppo, parts of PostHog, GrowthBook with mSPRT) support sequential testing that adjusts the math to allow daily peeking without inflating alpha. The methods include sequential probability ratio tests, group sequential designs, and always-valid p-values via mixture sequential probability ratio tests (mSPRT). Use them when the platform offers them. They cost some statistical power in exchange for valid mid-test inference. + +Pre-registered stopping rules. If the platform does not support sequential testing, declare the planned analysis date before the test runs. Save the pre-commitment. Do not look at results until that date. If you must look (some platforms make it hard not to), do not make decisions based on what you see. The decision happens at the pre-committed analysis date, not when the early peek looks favorable. + +The "ship early because results look great" trap. Results almost always look more dramatic on day 3 than they do at day 14. Regression to the mean kicks in. Novelty fades. The metric stabilizes. The tests that survive the full window and still look great are the ones worth shipping. The ones that "looked great early" and were shipped early are disproportionately the ones that disappointed in production. + +--- + +## Pre-commitment vs p-hacking + +The p-hacking inventory. Things people do, often unconsciously, when results do not come out the way they hoped: + +- Run additional segments until something hits significance +- Drop "outliers" until the headline result moves +- Switch the primary metric mid-flight +- Extend the test duration "just a bit longer" +- Reframe the hypothesis to match what the data showed +- Combine multiple inconclusive tests into a "directional pattern" that justifies shipping + +Each individually feels like a small judgment call. Cumulatively they destroy the discipline. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +The pre-commitment fix. Before the test runs, write down: the primary metric and how it is computed; the MDE you are powered to detect; the duration in calendar days; the segments you will analyze (if any); the decision rule that maps each possible result to a ship or kill. Save the pre-commitment somewhere with a timestamp. The PR description that ships the experiment configuration. A signed Slack message. A pinned ticket. Anywhere that makes it immutable. + +When the results come in, follow the pre-commitment. If the result was clean and you want to ship, file the launch. If the result was bad and you want to kill, kill. If the result was inconclusive, follow the inconclusive resolution path described below; do not invent new analyses. + +The "we learned so much" trap. If the test ran and produced an inconclusive result, the answer is "inconclusive." Not "we learned that the underlying mechanism is more nuanced than expected" or "we discovered a fascinating segment dynamic." Inconclusive is inconclusive. The lesson, if there is one, is for the next hypothesis, not retrofitted onto this one. + +--- + +## Reading results and making the call + +Three buckets. Clear win: ship. Clear loss: kill. Inconclusive: the hardest case. + +Inconclusive resolution paths, ranked from most acceptable to least: + +1. Ship anyway because the change is cheap and reversible (defensible only if guardrails are clean and you genuinely have no information that the change is harmful). The bar here is high; "the directional movement was favorable" is not enough. +2. Run a bigger version: more traffic, longer duration, larger MDE if the change can be made bolder. Use the inconclusive result as evidence that the original was underpowered or the effect is smaller than expected. +3. Kill the idea. The most common right answer; the hardest to do because PMs have invested in the hypothesis. +4. Iterate the hypothesis and re-test. Use the inconclusive result to refine the mechanism. The new test is a new test, not a continuation; pre-commit again. + +Bayesian thinking layer. If your prior was strong (this should obviously work, given everything we know about user behavior), an inconclusive result should still update your belief somewhat. The prior was wrong, or the effect is smaller than expected, or the implementation was too timid to capture it. If your prior was weak (we genuinely had no idea what would happen), an inconclusive result means inconclusive; the prior was already uncertain and the result did not narrow it. + +The hardest version. Positive primary metric, ambiguous guardrail. Revenue went up but support tickets ticked up. Conversion went up but session length went down. Use the pre-committed decision rule. If you did not pre-commit on the guardrail trade-off, default to "do not ship." The guardrails exist because you cared about them before you saw the result. Do not lower the bar after the fact. + +For a step-by-step results-reading checklist, see [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). + +--- + +## Common failures and fixes + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-failures.md`](references/common-failures.md). + +- "We did not have enough traffic" means the MDE was too small. Pick bigger changes worth detecting. +- "The lift disappeared after launch" means the test ran for 5 days and caught a novelty effect. Run longer next time; minimum two weeks for UI changes. +- "It worked for new users but not returning users" means the segment was post-hoc, probably noise. Ship to all or kill, do not ship to the segment. +- "The p-value crept up to 0.04 after 12 days of peeking" means the false-positive rate is much higher than nominal. Pre-commit and use sequential testing. +- "Revenue went up but retention went down" means a guardrail was violated. Do not ship. +- "We cannot replicate the result" means the original was probably noise or platform-bug. Investigate before re-running. +- "Conversion went up but only because of the bot traffic from the new ad campaign" means the result was confounded by an external event. Pause campaigns during sensitive tests, or stratify by acquisition source. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped" means you ignored your own discipline. The inconclusive bucket exists for a reason; do not let directional patterns substitute for evidence. + +--- + +## Reference files + +- [`references/hypothesis-templates.md`](references/hypothesis-templates.md). Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test, with worked examples across conversion, engagement, revenue, retention, and funnel-step metric types. +- [`references/sample-size-tables.md`](references/sample-size-tables.md). Pre-calculated sample size tables for the most common conversion-rate experiments, with how-to-use guidance and the common pitfalls in sample-size planning. +- [`references/common-failures.md`](references/common-failures.md). Fifteen anti-patterns that produce wrong shipping decisions, each with symptom, root cause, fix, and prevention. +- [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). Step-by-step checklist for reading results, the three-bucket decision matrix (win, loss, inconclusive), and the post-launch monitoring discipline. +- [`references/platform-comparison.md`](references/platform-comparison.md). Profiles of the major experimentation platforms (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon) with strengths, gotchas, and a decision matrix for choosing. +- [`references/pre-experiment-readiness-checklist.md`](references/pre-experiment-readiness-checklist.md). Ten-item go/no-go checklist run through before launch. +- [`references/post-experiment-decision-framework.md`](references/post-experiment-decision-framework.md). The moment-of-decision framework: confirm pre-commitment, apply rule mechanically, route to ship/kill/inconclusive paths, write the post-mortem within a week. + +--- + +## Closing: when in doubt + +Default conservative posture. When results are unclear, do not ship. The cost of a false negative (you did not ship a real win) is usually smaller than the cost of a false positive (you shipped something that does not actually work and now you have to maintain it forever). The maintenance cost compounds; the missed-opportunity cost does not, because you can always test again. + +The discipline of experiment design is the discipline of saying "I do not know" out loud when you do not know. Saying it is often the most consequential thing a PM does in a given week. The instinct is to pretend the result is more conclusive than it is, ship to look decisive, and absorb the failure quietly when the change does not work in production. The discipline is to say "the test was inconclusive, here is what I would change to get a real answer, here is the new test plan." Saying that is professional. Pretending otherwise is theater. + +For platform-specific patterns (which platform handles which experiment type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the operational layer below this skill (managing flags, retiring stale ones, coordinating environments), see the `feature-flagging` skill. For the analytical layer above this skill (variance reduction, Bayesian alternatives, sequential testing math), see the `experimentation-analytics` skill. diff --git a/skills/experiment-design/references/common-failures.md b/skills/experiment-design/references/common-failures.md new file mode 100644 index 0000000..ba75be0 --- /dev/null +++ b/skills/experiment-design/references/common-failures.md @@ -0,0 +1,183 @@ +# Common failures and fixes + +Anti-patterns that produce confidently wrong shipping decisions, with the symptom you observe, the root cause, the fix that resolves it, and the prevention that stops it from recurring. + +--- + +## 1. The vague hypothesis + +**Symptom.** "We think the new pricing page will increase conversions." The team runs the test, the result is ambiguous, and a heated meeting follows about whether to ship. + +**Root cause.** The hypothesis lacks magnitude and mechanism. When the result comes in, there is no pre-committed bar to compare against, so the decision becomes political. + +**Fix.** Rewrite the hypothesis with the cause-effect-magnitude-mechanism format from [SKILL.md](../SKILL.md). Save it before launching. + +**Prevention.** Make hypothesis review part of the experiment kickoff. A peer reads the hypothesis and confirms all four parts are present before the test launches. + +--- + +## 2. The novelty effect ship + +**Symptom.** Test ran for 5 days, lift looked great, the team shipped, and the lift disappeared in production within two weeks. + +**Root cause.** Users notice new things and click them disproportionately during the novelty window. The early lift was novelty, not durable preference. + +**Fix.** Re-test the change with at least a two-week test window. Most novelty effects fade in 7-10 days. If the lift survives 14 days, it is likely durable. + +**Prevention.** Set minimum test duration of 14 days for any UI/UX change, regardless of how fast sample size hits. Document the rule and enforce it. + +--- + +## 3. The post-hoc segment win + +**Symptom.** Test was inconclusive overall, but "users from California who signed up via mobile on Tuesdays" had a huge lift. The team wants to ship to that segment. + +**Root cause.** Multiple comparisons. With enough segments analyzed, one will hit "significance" by chance. The California-mobile-Tuesday segment is almost certainly noise. + +**Fix.** Do not ship to the segment. Either ship to all (if guardrails hold), or kill, or re-test with the segment pre-registered as a hypothesis. + +**Prevention.** Pre-register the segments to be analyzed. Limit to three to five segments per test, each with a real prior reason to differ from the population. + +--- + +## 4. The peeking creep + +**Symptom.** P-value drifted around 0.06 for the first week, then crept to 0.04 on day 12, the team called it significant and shipped. + +**Root cause.** The platform did not use sequential testing. Daily peeking inflated the false positive rate. The "significance" on day 12 was a peeking artifact. + +**Fix.** Either use a platform with sequential testing, or pre-commit to a single end-of-test analysis. If you peeked and the test is over, treat the result as inconclusive and consider rerunning. + +**Prevention.** If your platform supports sequential testing (mSPRT, group sequential), enable it. If not, set up the test with calendar reminders for the analysis date, not before. + +--- + +## 5. The guardrail violation overlook + +**Symptom.** Primary metric (revenue) went up. Retention dropped. The team shipped because revenue was the headline metric. + +**Root cause.** Guardrails were defined but not treated as binding. When the primary metric looked favorable, the team rationalized the guardrail violation as acceptable. + +**Fix.** Do not ship. Investigate the retention drop. The change may be capturing short-term revenue at the cost of long-term value, which is a worse trade than no change at all. + +**Prevention.** Pre-commit on the guardrail trade-off. Write down explicitly: "We will not ship if retention drops by more than X." If you cannot specify the bar in advance, you do not understand the trade-off well enough to test it. + +--- + +## 6. The non-replicable result + +**Symptom.** Test reported a 5 percent lift. The team shipped. A month later the same change tested with a holdout group shows no effect. + +**Root cause.** Could be many things: original test was a false positive, platform bug, external event during the test window, contamination. Without investigation, you do not know which. + +**Fix.** Stop, investigate, find the cause. Possible findings: the metric was computed differently in the test versus production; the test exposure was lower than reported; an unrelated change confounded the result. Do not "just rerun and hope." + +**Prevention.** Schedule a post-launch holdout test for any change with a reported lift greater than 3 percent. Confirm the production behavior matches the test before declaring the win. + +--- + +## 7. The campaign confound + +**Symptom.** Test launched the same week as a major marketing campaign. Test reported a huge lift. The team shipped. The lift was the campaign's traffic mix, not the treatment. + +**Root cause.** The campaign brought a different user mix into the test population: higher-intent visitors, different geographies, different device types. Treatment and control both saw the campaign traffic, but the campaign-driven users may have responded differently to the variants than the baseline population would. + +**Fix.** Pause campaigns during sensitive tests, or stratify the analysis by acquisition source so campaign traffic is analyzed separately from baseline traffic. + +**Prevention.** Coordinate with the marketing team before launching tests. Maintain a calendar of upcoming campaigns and avoid launching experiments on the same surfaces during major pushes. + +--- + +## 8. The directional ship + +**Symptom.** Test was inconclusive. Primary metric trended up but did not hit significance. The team shipped because "the trend was directional." + +**Root cause.** Directional trend without significance is noise that happens to point in a flattering direction. Treating it as evidence is exactly the discipline failure that erodes experimentation rigor. + +**Fix.** Do not ship based on directional trends. Either run a bigger test (more traffic, longer duration), kill, or accept inconclusive as the answer. + +**Prevention.** Pre-commit to the decision rule. "Inconclusive" as a category requires acceptance, not creative reframing. + +--- + +## 9. The interaction effect blind spot + +**Symptom.** Five concurrent tests on the checkout flow. Each individually reported a small lift. Combined, total checkout conversion did not move. + +**Root cause.** Interactions between concurrent tests. The lifts did not multiply or even sum. Some may have canceled out, some may have interfered with each other. + +**Fix.** Roll back, run tests with mutex enforcement, or run them sequentially. Re-test the combination as a multivariate. + +**Prevention.** Maintain an experiment registry per surface. Before launching a new test, check which others are running on the same surface and coordinate. Use mutex when interactions are likely. + +--- + +## 10. The selection bias ship + +**Symptom.** ARPU went up. The team shipped. After launch, MAU dropped because the lowest-revenue users churned. + +**Root cause.** The treatment caused selection: lower-value users left, higher-value users stayed. ARPU went up arithmetically because the denominator shrank, not because anyone made more money. + +**Fix.** Pair ARPU primary metrics with retention or MAU guardrails. Investigate the source of the lift before shipping. + +**Prevention.** When the primary metric is a ratio, always pair with absolute count guardrails. ARPU plus revenue. Conversion rate plus conversion count. Engagement rate plus DAU. + +--- + +## 11. The internal traffic contamination + +**Symptom.** Test reported strong lift in the first week. Investigation showed half the test users were internal employees clicking around the new feature. + +**Root cause.** Internal traffic was not excluded from the test population. Employees behave differently from real users. + +**Fix.** Re-bucket the test excluding internal IPs and employee accounts. Re-analyze. + +**Prevention.** Maintain an internal-traffic exclusion list at the platform level. Apply it to all experiments by default. Audit the user counts on test launch to confirm internal traffic is excluded. + +--- + +## 12. The metric definition mismatch + +**Symptom.** Test reported a 5 percent lift in "conversion." Production analytics reported a 0.5 percent lift. The team blamed the platform. + +**Root cause.** The conversion event was defined differently in the test platform versus production analytics. Different conversion windows, different deduplication rules, different user-identity logic. + +**Fix.** Reconcile the metric definitions before re-running. Document the canonical definition and confirm both systems produce matching numbers on a known historical period. + +**Prevention.** Maintain a metric dictionary. Before adding a metric to an experimentation platform, document the canonical definition and validate against production analytics. Treat the metric definition as a versioned artifact. + +--- + +## 13. The ratio metric variance error + +**Symptom.** Test reported a "significant" lift in revenue per user with p equals 0.04. Production rollout produced no measurable change. + +**Root cause.** The platform used a naive variance estimator on a ratio metric. Confidence interval was too narrow; the "significance" was an artifact of bad math. + +**Fix.** Switch to a platform that uses a ratio-aware estimator (delta method, bootstrap). Re-run the test or confirm via holdout. + +**Prevention.** Audit your platform's variance estimator. Ask the vendor what they use for ratio metrics. If the answer is "standard t-test on proportions" for anything other than simple binary conversion, plan a workaround. + +--- + +## 14. The "we will fix it later" rollout + +**Symptom.** Test was inconclusive but engineering had already deployed the change. Rolling back was hard. The team shipped because the cost of rollback was higher than the expected cost of shipping. + +**Root cause.** The rollout was not gated on the experiment result. Engineering shipped to production before the test had concluded. + +**Fix.** Roll back if possible. If not, accept the change is shipped and instrument production carefully to confirm whether it actually works. + +**Prevention.** Gate rollouts behind experiment conclusions. Use feature flags so the change can be toggled off without a code revert. Coordinate engineering schedules with experiment timelines. + +--- + +## 15. The retroactive hypothesis + +**Symptom.** Test was set up to validate "the new homepage increases signups." Result showed signups flat but engagement up. The team rewrote the hypothesis as "the new homepage drives engagement" and shipped. + +**Root cause.** Hypothesis was changed after the result was visible. This is p-hacking even if no statistical math was changed. + +**Fix.** The original hypothesis was inconclusive on signups. Either kill, or run a new test with the engagement hypothesis pre-registered. + +**Prevention.** Pre-commit the primary metric and stick with it. If the data suggests a different metric is more interesting, treat that as the hypothesis for the next test, not a rewrite of the current one. diff --git a/skills/experiment-design/references/hypothesis-templates.md b/skills/experiment-design/references/hypothesis-templates.md new file mode 100644 index 0000000..18e3584 --- /dev/null +++ b/skills/experiment-design/references/hypothesis-templates.md @@ -0,0 +1,95 @@ +# Hypothesis templates + +Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test from [SKILL.md](../SKILL.md). Each template names the right shape, shows two or three worked examples in different domains, and calls out the most common mistakes specific to that template type. + +The unifying format across all templates: replace [bracketed slots] with concrete project-specific values. If a slot reads as a vague phrase after replacement, the hypothesis is not specific enough. + +--- + +## Template 1: Conversion rate change + +**Format.** Replacing [current treatment] with [new treatment] will increase [conversion event] by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +**Worked example, e-commerce.** Replacing the multi-step shipping selector with an inline shipping summary on the cart page will increase cart-to-purchase conversion by 6 percent (currently 14.2 percent, target 15.1 percent) by reducing the cognitive load at the moment users are deciding whether to complete checkout. + +**Worked example, SaaS.** Replacing the three-tier pricing comparison with a single recommended tier on the pricing page will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe. + +**Worked example, marketplace.** Replacing the "browse all categories" landing page with a personalized recommendation grid will increase landing-to-listing-click conversion by 12 percent (currently 18 percent, target 20.2 percent) by surfacing relevant inventory before users have to specify intent. + +**Common mistakes specific to this template.** +- Naming the metric as "conversions" without specifying the conversion event. "Conversion" alone is ambiguous; cart-to-purchase, signup-to-paid, and landing-to-listing-click are different metrics with different baselines and different relevant timescales. +- Stating relative lift without absolute. "10 percent lift" sounds bigger than "1 percent absolute lift on a 10 percent baseline" but is the same thing; state both so the reader knows what is being claimed. +- Skipping the mechanism. "Will increase conversion by 8 percent" is a target, not a hypothesis. The why is what makes it falsifiable. + +--- + +## Template 2: Engagement metric change (DAU, sessions, time-on-task) + +**Format.** Adding [new feature or affordance] will increase [engagement metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, content product.** Adding a "save for later" button to article cards will increase weekly active users by 5 percent (currently 1.2 million, target 1.26 million) by giving users a reason to return to articles they have started reading. + +**Worked example, productivity tool.** Adding inline comments on document blocks will increase sessions per week per active team by 15 percent (currently 4.2, target 4.8) by enabling asynchronous collaboration that previously required separate communication channels. + +**Common mistakes specific to this template.** +- Engagement metrics are not always good. A feature that increases sessions but decreases task completion is making the product worse, not better. Pair engagement primary metrics with task-completion guardrails. +- "Time on task" is ambiguous. More time can mean engagement or confusion. Specify whether longer or shorter is the desired direction and why. +- Treating engagement lift as a leading indicator without evidence that it is. Increased DAU does not always lead to increased revenue; sometimes it lags it, sometimes it has no relationship. + +--- + +## Template 3: Revenue metric change (ARPU, AOV, RPU) + +**Format.** Implementing [new pricing or merchandising change] will increase [revenue metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, subscription product.** Adding an annual prepay option at 10 percent discount will increase average revenue per user by 4 percent (currently $87, target $90.50) by shifting price-sensitive users from monthly to annual billing, which has lower churn. + +**Worked example, e-commerce.** Adding a "frequently bought together" bundle on product detail pages will increase average order value by 8 percent (currently $42, target $45.40) by surfacing relevant add-on items at the moment of purchase decision. + +**Common mistakes specific to this template.** +- Revenue is a ratio metric (revenue divided by users or orders). Naive variance estimators understate the variance and overstate confidence. Confirm your platform uses the delta method or an equivalent ratio-aware estimator. +- ARPU lifts can come from selection effects: if the treatment moves the lowest-revenue users away (they churn), ARPU goes up without anyone making more money. Pair ARPU primary metrics with retention guardrails. +- Revenue lifts can be driven by a small number of high-value users. Confidence intervals are wide. Run longer than you think you need to. + +--- + +## Template 4: Retention metric change + +**Format.** Changing [interaction or feature] will increase [retention metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +**Worked example, mobile app.** Changing the day-3 push notification copy from generic to personalized recommendations will increase day-7 retention by 3 percent (currently 38 percent, target 39.1 percent) by reminding users of specific value they can return to. + +**Worked example, SaaS onboarding.** Replacing the static onboarding checklist with a guided in-product tour will increase day-30 active retention by 5 percent (currently 22 percent, target 23.1 percent) by getting more users to the activation event during their first session. + +**Common mistakes specific to this template.** +- Retention takes time to measure. A test of day-30 retention requires at least 30 days of treatment exposure plus the test duration. Plan accordingly. +- Day-N retention is a moving definition. Day-7 active means different things in different products; specify the activity that defines "active" before running. +- Retention lifts often shrink over time. A treatment that improves day-7 retention may have no effect on day-90 retention. Decide which timescale matters for the business and measure that, not just the convenient short one. + +--- + +## Template 5: Funnel-step abandonment reduction + +**Format.** Modifying [specific funnel step] will reduce abandonment at that step by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +**Worked example, signup funnel.** Removing the phone number field from the signup form will reduce signup-form abandonment by 20 percent (currently 35 percent, target 28 percent) by removing a high-friction field that is not required for account creation. + +**Worked example, checkout funnel.** Adding guest checkout above the account creation prompt will reduce account-creation-step abandonment by 25 percent (currently 18 percent, target 13.5 percent) by giving purchase-intent users a path that does not require account creation. + +**Common mistakes specific to this template.** +- Reducing abandonment at one step often shifts abandonment to the next step. The right metric is downstream conversion, not just step-level abandonment. Pair step-level primary metrics with full-funnel guardrails. +- Signup abandonment can be measured noisily; users who abandon the form may return later. Define the conversion window (5 minutes, 24 hours, 7 days) before testing. +- Reducing friction is not always good. A signup form that is too short produces low-quality signups: trial users who never return, fake accounts, support load. Pair friction-reduction tests with downstream-quality guardrails. + +--- + +## Anti-templates: hypotheses that should be rejected + +Examples of hypotheses that fail the format and should be rewritten before launching: + +- "We think the new pricing page will increase conversions." Missing magnitude, mechanism, and a specific conversion event. Rewrite using Template 1. +- "Users will love the redesign." Missing everything. Not testable. Pick a metric. +- "The new flow is faster, so more people will complete it." Missing baseline, target, and a defined "complete" event. The mechanism (faster) is plausible but not specific. +- "We want to see if dark mode improves engagement." Vague metric (engagement), no magnitude, and dark mode is binary not a multivariate. Pick a specific engagement metric and pre-register the segments where dark mode users are likely to differ from light-mode users (mobile evening sessions, for example). + +If your draft hypothesis sounds like one of the anti-templates, rewrite it using one of the five templates above before running the test. diff --git a/skills/experiment-design/references/platform-comparison.md b/skills/experiment-design/references/platform-comparison.md new file mode 100644 index 0000000..f435e29 --- /dev/null +++ b/skills/experiment-design/references/platform-comparison.md @@ -0,0 +1,133 @@ +# Platform comparison + +A practical guide to choosing an experimentation platform. Each platform has a distinct profile (statistical defaults, primary audience, integration model, pricing shape). Picking well saves quarters of friction; picking badly creates ongoing pain. + +This reference assumes the team is in the position of choosing or reconsidering. For platform-specific MCP commands, auth models, and example prompts, consult the chosen platform's official documentation. + +--- + +## Statsig + +**Profile.** Modern feature management plus experimentation platform. Built CUPED-first, holdouts as a first-class concept, warehouse-native with optional event ingestion. Fast-growing customer base including OpenAI, Notion, Brex, Whatnot. + +**Strengths.** CUPED variance reduction is the default, not an opt-in. Strong holdout analysis with built-in long-term measurement. Mature MCP exposing full CRUD across experiments, gates, dynamic configs, layers, and segments. Setup guides for ChatGPT, Cursor, Claude Code, Codex. + +**Best for.** Fast-growing companies that want one platform for both feature flags and experiments. Engineering-led teams comfortable with code-first configuration. Teams that need to run many concurrent experiments and care about variance reduction. + +**Gotchas.** Pricing scales with events, which can compound for high-traffic products. The breadth of the MCP can crowd context windows on smaller models; scoping helps. Best-in-class statistical defaults are nice but require the team to actually understand them. + +**MCP setup.** Statsig publishes setup guides for ChatGPT, Cursor, Claude Code, and Codex; consult the Statsig docs for the current MCP server URL and auth model. + +--- + +## PostHog + +**Profile.** Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics in one platform. Self-host or cloud. Customer base skews toward PLG products and developer tools. + +**Strengths.** Combines analytics and experimentation in one platform, eliminating the metric-definition mismatch between systems. Full event-level data in the warehouse. 200+ MCP tools across the entire product, the largest surface of any vendor in this list. + +**Best for.** Product-led growth products that benefit from full-funnel context across analytics, experiments, and session replays. Teams that want one platform for everything rather than a stack of specialized tools. + +**Gotchas.** The breadth of the MCP requires scoping with `?features=` query parameters; without scoping, the agent gets 200+ tools and tool selection accuracy degrades on smaller models. Self-host adds operational complexity. Some experiment features lag behind specialized platforms. + +**MCP setup.** PostHog's MCP scopes via `?features=` query parameters; without scoping, the agent gets 200+ tools and tool-selection accuracy degrades on smaller models. Consult the PostHog docs for current scoping syntax. + +--- + +## GrowthBook + +**Profile.** Open-source warehouse-native experimentation. Runs SQL on the team's existing data warehouse. Customer base skews data-mature: Dropbox, Khan Academy, Mistral. Claims the first open-source production MCP for experimentation. + +**Strengths.** Data stays in the team's warehouse; no event ingestion to a vendor. Strong cost control because the math runs on infrastructure the team already pays for. 100 percent open source under MIT, with self-host or cloud options. + +**Best for.** Data-mature teams that already own a warehouse (Snowflake, BigQuery, Redshift, ClickHouse, Postgres). Regulated industries where data residency matters. Teams that want full control over the statistical math. + +**Gotchas.** More setup overhead than hosted platforms. Requires SQL fluency for advanced analyses. Smaller community than the bigger commercial vendors. + +**MCP setup.** GrowthBook ships an open-source MCP for self-host or cloud; consult the GrowthBook docs for the current binary and auth model. + +--- + +## Optimizely + +**Profile.** Long-time enterprise leader in personalization and experimentation. Web Experimentation and Feature Experimentation as separate but linked products. Customer base skews enterprise marketing and e-commerce. + +**Strengths.** Deep targeting, audience management, multivariate testing. Visual editor accessible to non-technical users (marketers can build variants without engineering). Mature personalization and recommendation engine. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth. + +**Best for.** Marketing-led organizations where non-technical teams need to author variants. Enterprises with deep personalization needs. E-commerce sites with established A/B testing programs. + +**Gotchas.** Expensive at the enterprise tier. Visual editor produces JS that ships at runtime, which can affect page performance. Less ergonomic for engineering-led teams that prefer code-first configuration. + +**MCP setup.** Optimizely's hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth; consult Optimizely docs for the current server URL. + +--- + +## Amplitude + +**Profile.** Behavioral analytics platform with experiments and feature flags layered on top. Customer base skews product analytics teams that adopted Amplitude before adding experimentation. + +**Strengths.** Deep cohort analysis and behavioral segmentation. Native ChatGPT connector. Hosted MCP available to all customers including the free tier. Integrates tightly with the analytics layer that PMs already use. + +**Best for.** Teams that already use Amplitude for analytics and want to add experiments without introducing a new platform. Product analytics teams that need behavioral cohort segmentation as part of the experiment workflow. + +**Gotchas.** Experiments are a secondary feature, not the platform's center of gravity. Variance reduction options are more limited than dedicated experimentation platforms. Beta status of the MCP means the API surface may evolve. + +**MCP setup.** Amplitude's hosted MCP is available to all customers including the free tier and ships a native ChatGPT connector; consult the Amplitude docs for the current setup steps. + +--- + +## Eppo + +**Profile.** Warehouse-native experimentation platform with strong statistical defaults. Customer base skews data-team-led organizations: Twitch, DraftKings, Perplexity. Best-in-class statistical rigor. + +**Strengths.** Best-in-class statistical defaults: variance reduction, sequential testing, contextual bandits, lifecycle experimentation. Warehouse-native means data stays in the team's stack. Strong explainability features for tracing reported lifts back to underlying SQL. + +**Best for.** Data-team-led organizations where data scientists own the experimentation discipline. Companies with mature warehouses and strict statistical rigor requirements. Teams running contextual bandits or other advanced experiment designs. + +**Gotchas.** No first-party MCP server as of May 2026. Programmatic access is REST API only; teams that want agentic workflows today need to build a custom MCP adapter or wait. Pricing reflects the data-science-focused product positioning. + +**MCP setup.** No first-party MCP server as of mid-2026; teams that want agentic workflows today either build a custom MCP adapter on top of Eppo's REST API or wait for the official server. Consult Eppo's docs and roadmap for current status. + +--- + +## Kameleoon + +**Profile.** AI-driven personalization platform with a specialized MCP focused on the convert-and-promote workflow. The MCP pulls raw variation code from winning experiments and helps refactor it into production-ready React components. + +**Strengths.** Sharp, narrow MCP (seven specialized tools) focused on a specific job: take a winning marketing-site variation and ship it as permanent product code. Hosted MCP via OAuth. Avoids the broad-CRUD complexity that crowds context windows on other platforms. + +**Best for.** Teams that test on the marketing site and need to convert wins into permanent React components. Hybrid marketing-and-product setups where the experiment lives in JS/CSS and the win needs to ship as a product feature. + +**Gotchas.** The narrow MCP scope is intentional but limits broader CRUD work. For everyday flag management, teams use the Kameleoon dashboard or REST API rather than the MCP. + +**MCP setup.** Kameleoon's hosted MCP via OAuth ships a narrow seven-tool surface focused on the convert-and-promote workflow; consult Kameleoon's docs for the current server URL. + +--- + +## Decision matrix + +A short matrix for the first-pass platform decision. Tradeoffs are oversimplified; verify against the team's specific constraints. + +| Situation | Pick | +|---|---| +| Pure SaaS, fast-growing, want one platform for flags + experiments | Statsig or PostHog | +| Open-source preference, warehouse-native | GrowthBook or Eppo | +| Enterprise, marketing-led, non-technical variant authoring | Optimizely | +| Already using Amplitude for analytics, want experiments without new platform | Amplitude | +| Convert marketing-site experiment wins into permanent product code | Kameleoon | +| Data-team-led, statistical rigor is non-negotiable, can wait for MCP | Eppo | +| Open-source AND warehouse-native AND need MCP today | GrowthBook | + +Beyond these defaults, the right choice depends on the team's existing stack, the experimentation maturity, and the budget. The "best" platform for one team is wrong for another; pick based on the team's actual constraints, not the platform's marketing. + +--- + +## Switching costs + +Once a team has adopted a platform, switching is expensive. Existing experiments need to be re-run on the new platform. The metric definitions need to be reconciled. The team needs to retrain on a new tool. Plan accordingly: + +- **Easy switches.** Visual A/B testing tools that ship JS at runtime (Optimizely Web, AB Tasty, VWO classic). Switching is mostly tag-replacement. +- **Medium switches.** Warehouse-native to warehouse-native (GrowthBook to Eppo, or vice versa). The data layer is shared; the configuration migrates. +- **Hard switches.** Anything to or from event-ingestion platforms (Statsig, Amplitude). The historical event data does not transfer cleanly; the team starts fresh on metric history. + +If the team is choosing now and might need to switch later, lean toward warehouse-native options. Data ownership is the most expensive thing to switch. diff --git a/skills/experiment-design/references/post-experiment-decision-framework.md b/skills/experiment-design/references/post-experiment-decision-framework.md new file mode 100644 index 0000000..6354a66 --- /dev/null +++ b/skills/experiment-design/references/post-experiment-decision-framework.md @@ -0,0 +1,91 @@ +# Post-experiment decision framework + +The moment-of-decision framework for what to do when a test ends. Each step builds on the prior; do not skip ahead. The discipline at this stage is what separates teams that learn from experiments from teams that confirm their priors. + +--- + +## Step 1: Confirm pre-commitment was followed + +Before reading the results, pull up the pre-commitment document. Verify: +- The test ran for the pre-committed duration (not stopped early, not extended). +- The primary metric was the one pre-committed (not silently swapped). +- The segments analyzed were the ones pre-committed (not new ones discovered post-hoc). +- The guardrails are the ones pre-committed (not narrowed or widened after the fact). + +If any item failed the check, the result is compromised. Treat as inconclusive at minimum; consider re-running. + +--- + +## Step 2: Apply the pre-committed decision rule mechanically + +The pre-commitment mapped each possible result to a ship-or-kill decision. Find the bucket the result falls into. Apply the rule. + +Resist the temptation to add new analysis "just to be sure." If new analysis is required to make a decision, the pre-commitment was inadequate; the lesson is for next time, not a license to dig until the answer feels right. + +The mechanical-application discipline is the most important habit at this step. Teams that deliberate about whether to follow their own pre-commitment have already lost the discipline. Apply the rule. Document any second-guessing as feedback for the next pre-commitment. + +--- + +## Step 3a: If decision is "ship" + +1. File the launch ticket. Include: the test ID, the primary metric lift, confidence interval, guardrails status, segments status, and a link to the pre-commitment. +2. Schedule post-launch monitoring at +7 days, +30 days, +60 days. Calendar reminders, not "I'll check it later." +3. Confirm the launch removes the experiment infrastructure (the flag, the variant code paths) on the schedule the team has for stale-flag cleanup. See the `feature-flagging` skill for the cleanup discipline. +4. Post a brief launch summary to the team's experiment log. + +--- + +## Step 3b: If decision is "kill" + +1. Document the learning. What did the team predict? What happened? What is the most likely reason for the gap? +2. Propose a follow-up hypothesis if applicable. The hypothesis can be "we should not test this idea again" if the test was definitive in the negative direction. It can be "let's iterate the mechanism" if the test was inconclusive and the team has a clearer story now. +3. Archive the experiment infrastructure: remove the flag, clean up the variant code, remove instrumentation that was specific to this test. +4. Post the kill summary to the team's experiment log. Killed experiments are as valuable as winning experiments; they prevent the team from repeating the mistake. + +--- + +## Step 3c: If decision is "inconclusive" + +The inconclusive path is the hardest. The temptation is to ship anyway because the team has invested in the hypothesis. Resist it. + +Run through the resolution paths in order: + +1. **Was the MDE realistic?** If the test was underpowered (you needed a 5 percent lift to be detectable, and you got a 2 percent point estimate with a confidence interval crossing zero), the right answer may be to redesign the test with a bolder change and rerun. Do not extend the existing test; that produces a peeking artifact. Plan a new test, pre-commit, run. +2. **Was the test contaminated?** If a confounder (campaign, outage, instrumentation bug) is identifiable, fix and rerun. Do not handwave the confounder. +3. **Is the change cheap and reversible?** If the change is small, easy to maintain, and easy to roll back, shipping despite an inconclusive result is defensible. The bar is high; the change has to be genuinely cheap, and the guardrails have to be clean. If the change is expensive to maintain (additional UI complexity, additional code paths, additional analytics surface), ship is the wrong call. +4. **Otherwise: kill, document, move on.** The discipline of accepting inconclusive results as inconclusive is what makes experimentation a learning system. Treating every inconclusive result as a "we just need more data" justification destroys the discipline. + +--- + +## Step 4: Write the post-mortem within one week + +Regardless of the decision, write a short post-mortem within one week. The post-mortem covers: + +- The hypothesis (cause, effect, magnitude, mechanism) +- The pre-commitment (primary metric, MDE, duration, decision rule) +- The result (lift, CI, guardrails, segments) +- The decision (ship / kill / inconclusive) +- The action taken (launch, archive, redesign) +- The learning (what would the team do differently next time) + +Keep post-mortems short: half a page is plenty. Long post-mortems do not get written; short ones do. The compounding value of a written experiment log over years is enormous; the compounding value of a vague memory of past tests is zero. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. + +Schedule a review at: + +- **Day 7.** Production metric matches the experiment lift within reasonable tolerance. If it does not, investigate before declaring the launch successful. +- **Day 14.** Lift has not decayed (which would suggest novelty effect that the test underweighted) or amplified (which would suggest the change interacts with something the test could not capture). +- **Day 30.** Long-term metrics (retention, downstream conversion, support load) are not eroding. The change continues to deliver value, not just an initial bump. + +If the production behavior diverges materially from the test behavior at any review: + +1. Quantify the divergence. Is it within statistical noise, or is it a real effect? +2. Investigate the cause. Common ones: novelty wore off, segment distribution shifted, instrumentation bug, interaction with another concurrent change. +3. Decide: roll back, hot-fix, or accept and document. Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. + +The 30-day rule prevents the "we shipped, it worked, then it stopped working but nobody noticed" failure mode. Most teams skip post-launch monitoring; the ones that do it consistently learn faster. diff --git a/skills/experiment-design/references/pre-experiment-readiness-checklist.md b/skills/experiment-design/references/pre-experiment-readiness-checklist.md new file mode 100644 index 0000000..5a0e44a --- /dev/null +++ b/skills/experiment-design/references/pre-experiment-readiness-checklist.md @@ -0,0 +1,108 @@ +# Pre-experiment readiness checklist + +A go/no-go decision checklist to run through before launching any experiment. If any item is "no," delay the launch until it is "yes." Running an experiment without these in place produces results that cannot be defended, decisions that get second-guessed, and a long-term erosion of trust in the experimentation discipline. + +The checklist takes ten to fifteen minutes per experiment. The cost of skipping it is much higher. + +--- + +## 1. Hypothesis written in cause-effect-magnitude-mechanism format + +The hypothesis names: what change is being made (cause), what metric will move (effect), how much you expect it to move with what baseline and target (magnitude), and why you expect this change to produce this effect (mechanism). + +If the draft hypothesis is missing any of the four parts, rewrite using one of the templates from `hypothesis-templates.md` before launch. + +--- + +## 2. Primary metric defined with success threshold + +Exactly one primary metric. Specified with the same precision the platform's metric configuration requires (event name, deduplication window, user identity logic). Success threshold pre-committed: the lift you would consider sufficient to ship. + +If multiple metrics feel "primary," collapse to one and demote the others to guardrails. + +--- + +## 3. Guardrails defined (3 to 5) + +Three to five guardrail metrics that must not break: revenue, retention, support tickets, page load time, error rate, satisfaction scores. Each with a tolerance threshold pre-committed. + +Avoid: more than five guardrails (creates analysis paralysis), or zero guardrails (the test cannot detect collateral damage), or vague guardrails like "user happiness" (not measurable). + +--- + +## 4. Sample size calculated for chosen MDE + +The required sample size for the chosen minimum detectable effect, at standard alpha (0.05) and power (0.80), through your platform's calculator or via a stats library. Documented in the pre-commitment. + +If the math says "you need 200,000 users to detect this lift and you have 5,000 a week," accept a larger MDE or do not run the test. Do not run an underpowered test and hope for the best. + +--- + +## 5. Duration committed (longer of sample-size-hit and full weekly cycle) + +Calendar duration committed in advance. The longer of: time to hit the calculated sample size at expected daily traffic, or one full weekly cycle (typically 7 days). UI/UX changes get a 14-day minimum regardless. + +If the duration is "we will see how long it takes," that is not a duration. Pick a date. + +--- + +## 6. Segments pre-registered (if any) + +If you plan to analyze segment-level results, name the segments before launch. Three to five maximum, each with a real prior reason to expect different behavior in that segment. + +If you do not plan to analyze segments, write that down too. The pre-commitment to "no segment analysis" is itself a defense against post-hoc segment mining. + +--- + +## 7. Decision rule pre-committed (saved with timestamp) + +Map each possible result to a decision: +- Result above target threshold + guardrails clean: ship +- Result below MDE: kill +- Result inconclusive (point above zero, CI crosses zero): default to do not ship; document next-step options +- Guardrail violation: do not ship regardless of primary + +Save the decision rule somewhere immutable: the PR description, a pinned ticket, a signed Slack message, anywhere with a timestamp. + +--- + +## 8. No conflicting concurrent experiments on the same surface + +Check the experiment registry for what else is running on the same surface (checkout flow, signup form, pricing page). If there are interactions, set up mutex enforcement so users in this test are not also in the others. + +If you cannot enforce mutex (sample size constraints), document the overlap and accept the interpretability cost. Do not pretend there is no overlap. + +--- + +## 9. Instrumentation tested with a small canary + +Before launching to the full population, expose a small canary group (5 to 10 percent) and confirm: +- Treatment users actually see the treatment +- Events fire correctly for both groups +- The platform reports the right exposure counts +- Internal traffic is excluded +- The metric definitions match between the platform and production analytics + +Catching instrumentation bugs in canary saves a wasted full test run. + +--- + +## 10. Stakeholders aligned on what each outcome means + +The PM, the engineering lead, the design lead, and any other decision-maker have all agreed: if the test wins, we ship; if it loses, we kill; if it is inconclusive, we follow the inconclusive path documented in the decision rule. + +If a stakeholder is going to dispute the result regardless of what it shows, the experiment is theater. Resolve the strategic question first; run the experiment only if the result genuinely changes the decision. + +--- + +## Decision + +If all ten items are "yes," launch. + +If any item is "no": +- Items 1, 2, 3 (hypothesis, metric, guardrails): blocking. Fix before launch. +- Items 4, 5, 7 (math, duration, decision rule): blocking. Fix before launch. +- Items 6, 8, 9 (segments, mutex, canary): worth fixing but launch can proceed if the fix is impractical and the team accepts the risk. +- Item 10 (stakeholder alignment): blocking. An experiment that cannot change the decision is theater. + +The cost of delaying a launch by a day to fix a checklist item is small. The cost of running a test that produces an indefensible result is much higher. diff --git a/skills/experiment-design/references/results-interpretation-checklist.md b/skills/experiment-design/references/results-interpretation-checklist.md new file mode 100644 index 0000000..32d3006 --- /dev/null +++ b/skills/experiment-design/references/results-interpretation-checklist.md @@ -0,0 +1,112 @@ +# Results interpretation checklist + +A step-by-step checklist for reading experiment results and arriving at a defensible decision. Run through it in order. Do not skip steps because the result "looks obvious"; the obvious-looking results are often the ones that fail in production. + +--- + +## Step 1: Did the test run for the pre-committed duration? + +**What to look for.** The test ended on the date pre-committed at launch, with the planned analysis happening on that date. + +**Red flags.** The test was stopped early because results "looked great." The test was extended past the pre-commitment because results "had not stabilized." The test ran for an arbitrary duration not tied to the pre-commitment. + +**When to escalate.** If the duration was changed after launch without documented rationale, the result is compromised. Treat as inconclusive and consider re-running. + +--- + +## Step 2: Did all guardrails stay within tolerance? + +**What to look for.** Each pre-defined guardrail (revenue, retention, support tickets, page load time, error rate) within its acceptable range. Confidence intervals around guardrail metrics that exclude the threshold of concern. + +**Red flags.** A guardrail moved in the wrong direction even if the change was not "significant." Wide confidence intervals on guardrails (the test was underpowered for the guardrail). A guardrail you did not pre-define being raised post-hoc. + +**When to escalate.** A guardrail violation should be treated as binding. The fix is "do not ship," not "the primary metric was good enough to outweigh the guardrail." If the guardrail was poorly chosen, that is a lesson for next time, not a license to ignore it on this test. + +--- + +## Step 3: Did the primary metric move beyond the MDE? + +**What to look for.** The point estimate of the primary metric exceeds the pre-committed minimum detectable effect, and the confidence interval excludes zero (or excludes the no-effect threshold for one-sided tests). + +**Red flags.** Point estimate is above MDE but the confidence interval crosses zero. The "significance" comes from a peeking artifact (interim analysis that became the headline). The lift comes from a small number of outlier users. + +**When to escalate.** If the primary metric is significant but the lift is below MDE, the test was overpowered for the question; the result is technically real but practically too small to matter. Do not ship a 0.3 percent lift just because p equals 0.001. + +--- + +## Step 4: Was the confidence interval clean? + +**What to look for.** A confidence interval around the lift estimate that is well-bounded and not crossing zero. Symmetric (or appropriately skewed for the metric type). + +**Red flags.** Very wide CI (test was underpowered). Skewed CI hinting at distributional weirdness (a few outliers drove the result). CI computed without ratio-aware variance for ratio metrics. + +**When to escalate.** If the CI is wide enough that the practical lift could be anywhere from "not worth shipping" to "amazing," the test does not support a confident ship decision. Run longer or accept inconclusive. + +--- + +## Step 5: Are the results consistent across pre-registered segments? + +**What to look for.** The pre-registered segments show effects in the same direction as the overall result. Magnitude can vary; direction should not flip. + +**Red flags.** Some segments show effects opposite to the overall result. The overall lift comes from one segment and the rest are flat or negative. + +**When to escalate.** If one segment is driving the entire effect and others are negative, the right ship decision is "ship to the segment where it works" only if the targeting infrastructure exists and is worth the maintenance cost. More often the right answer is to redesign the change so it works for the whole population. + +Reminder: this step covers PRE-REGISTERED segments only. Post-hoc segments are noise mining; do not re-analyze the data through new segments looking for an interpretation. + +--- + +## Step 6: Did any external events potentially confound the results? + +**What to look for.** A timeline of events during the test window: marketing campaigns, product launches, outages, news cycles, holidays, seasonality shifts. + +**Red flags.** A campaign launched mid-test that brought a different user mix. A product release mid-test that changed user behavior. An outage during the test that affected one variant differently from the other. + +**When to escalate.** If a confounder is identified, isolate it. Stratify the analysis by acquisition source (excludes campaign-driven users), or by date (excludes the outage day), or rerun. Do not handwave the confounder; either fix it or accept that the result is tainted. + +--- + +## Step 7: Is the magnitude practically significant, not just statistically significant? + +**What to look for.** The lift is large enough to matter for the business. A 0.3 percent absolute lift on a 30 percent baseline is statistically significant with enough sample but may not justify the engineering cost of maintaining the change. + +**Red flags.** "Statistically significant" being used as the only justification. No conversation about whether the lift is large enough to be worth the implementation, maintenance, and complexity cost. + +**When to escalate.** If the magnitude is small, ask: "Is this worth the code surface area, the testing surface area, and the cognitive load on the team?" Often the answer is no. Do not ship marginal lifts unless the change is also cheap to maintain. + +--- + +## Step 8: Does the decision match the pre-committed rule? + +**What to look for.** The pre-commitment document mapped each possible result to a ship-or-kill decision. The result fits clearly into one of those buckets. + +**Red flags.** The result does not fit cleanly. The team is debating which bucket applies. Someone is proposing a new analytical knob to clarify the bucket. + +**When to escalate.** If the result is genuinely ambiguous, default to "do not ship" and document why. Inconclusive is a valid outcome; treating it as one is the discipline. + +--- + +## Decision matrix + +After running through the checklist, the result fits one of three buckets: + +| Bucket | Conditions | Action | +|---|---|---| +| Clear win | Primary moved past MDE, CI excludes zero, guardrails clean, segments consistent, no confounders | Ship. File launch. Schedule post-launch monitoring at +30 and +60 days. | +| Clear loss | Primary moved against expected direction with significance, OR guardrail violated | Kill. Document the learning. Propose follow-up hypothesis if applicable. | +| Inconclusive | Anything else | Default to do not ship. Run a bigger version, kill, or iterate the hypothesis. | + +The inconclusive bucket is the most common and the hardest. The discipline is to recognize it and resist the pull to ship anyway. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. Schedule a review at day 7, day 14, and day 30. + +What to check at each review: +- Day 7: Production metric matches the experiment lift within reasonable tolerance. +- Day 14: Lift has not decayed (novelty effect) or amplified (the change interacts with something the test could not capture). +- Day 30: Long-term metrics (retention, downstream conversion) are not eroding. + +If the production behavior diverges materially from the test behavior, the right call is to roll back and investigate, not to "wait and see." Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. diff --git a/skills/experiment-design/references/sample-size-tables.md b/skills/experiment-design/references/sample-size-tables.md new file mode 100644 index 0000000..5a74eea --- /dev/null +++ b/skills/experiment-design/references/sample-size-tables.md @@ -0,0 +1,88 @@ +# Sample size tables + +Pre-calculated sample size tables for the most common experimentation scenarios. These tables are starting points, not substitutes for running the math against your specific traffic and metric. The math depends on the variance of the metric, the desired power, the alpha threshold, and the test design (one-sided, two-sided, sequential). + +Use these tables to: +- Sanity-check a sample size estimate from your platform's calculator +- Decide whether the planned test is feasible given your traffic +- Choose an MDE that is realistic for your traffic level + +For exact figures, run the math through your platform's calculator (most experimentation platforms expose one) or use a stats library (`scipy.stats`, R's `pwr` package, or an online calculator). + +--- + +## How to use these tables + +Each table assumes: +- Two-sided test (the standard default for PM experiments) +- Alpha equals 0.05 (5 percent false positive rate) +- Power equals 0.80 (80 percent chance of detecting an effect that is really there) +- Equal group sizes (50/50 split) + +Total sample size is the sum across both groups. Per-group sample is half the total. + +If you change any of those assumptions, multiply by the indicated factor: +- Power 0.90 instead of 0.80: multiply sample size by ~1.34 +- Alpha 0.01 instead of 0.05: multiply sample size by ~1.49 +- One-sided test: multiply by ~0.79 + +Worked example for using Table 1: a product has a baseline conversion rate of 10 percent and wants to detect a 1 percent absolute lift (target 11 percent). Total sample size required is roughly 31,400 users. With 1,000 daily new users in the test population, the test needs about 31 days plus one full weekly cycle. If you can only run it for 14 days, the MDE you can detect at this traffic is closer to 1.5 percent absolute. Pick the change you can detect; do not run an underpowered test. + +--- + +## Table 1: Conversion rate experiments + +Total sample size required (across both groups) for a two-sided test, alpha 0.05, power 0.80. + +| Baseline rate | MDE 1% abs | MDE 2% abs | MDE 5% abs | MDE 10% abs | +|---|---|---|---|---| +| 5% | 14,800 | 4,400 | 1,000 | 360 | +| 10% | 31,400 | 8,400 | 1,700 | 540 | +| 20% | 51,800 | 13,400 | 2,500 | 720 | +| 30% | 65,600 | 16,600 | 3,000 | 800 | +| 50% | 78,400 | 19,600 | 3,200 | 800 | + +**Reading the table.** A product with 30 percent baseline conversion that wants to detect a 2 percent absolute lift (target 32 percent) needs ~16,600 users total, ~8,300 per group. Numbers are approximate and rounded. + +**Choosing an MDE that matches traffic.** If you have 5,000 weekly users in the test population: +- One week of traffic supports detection of ~5 percent absolute lift on a 30 percent baseline (3,000 users, MDE 5 percent matches) +- Two weeks supports ~3 percent absolute lift +- Four weeks supports ~2 percent absolute lift +- Six weeks supports ~1.5 percent absolute lift + +Beyond six weeks the test runs into seasonality and product-evolution problems described in [SKILL.md](../SKILL.md). If the change you want to test would only produce a 1 percent absolute lift and your traffic supports 5 percent MDE in a reasonable window, the test is not worth running. Pick a bigger change. + +--- + +## Table 2: Mean comparison experiments (continuous metrics) + +For continuous metrics like time-on-task, session length, page views per session, the math depends on the metric's standard deviation, which varies by product. The table below shows sample sizes assuming a coefficient of variation (standard deviation divided by mean) of 1.0, which is typical for engagement metrics. + +| Baseline mean | MDE 5% rel | MDE 10% rel | MDE 20% rel | +|---|---|---|---| +| Any (CoV ~1.0) | 12,600 | 3,200 | 800 | +| Any (CoV ~2.0) | 50,400 | 12,600 | 3,200 | + +For revenue metrics the CoV is often higher (2.0 to 3.0) because revenue is concentrated in a small fraction of users. Run your variance through the platform calculator before committing to a sample size; the table is illustrative, not authoritative. + +--- + +## Common pitfalls in sample size planning + +- **Forgetting to count exposure, not allocation.** If 1,000 users see the experiment per day but only 200 reach the surface where the variant is rendered, your effective sample is 200 per day. Use exposure counts, not bucketing counts. +- **Treating session-level and user-level differently.** Some metrics are evaluated per session (page views per session), others per user (day-7 retention). Sample size requirements differ. Specify which level the metric is evaluated at and use the matching count. +- **Forgetting variance reduction.** Methods like CUPED, stratified sampling, and control variates can reduce required sample size by 30 to 50 percent for the same power. If your platform supports them, use them. Sample size tables ignoring variance reduction overstate what you actually need. +- **Underestimating the weekly cycle requirement.** A test that hits sample size in three days still needs to run a full week to capture cycle effects. Sample size hit is necessary but not sufficient. +- **Assuming traffic is stable.** If a marketing campaign launches mid-test, the user mix changes and the test may no longer be a clean comparison. Coordinate with marketing before launching tests on user-acquisition-sensitive surfaces. + +--- + +## When the math says "you cannot detect this" + +Sometimes the table reads "you need 200,000 users to detect this lift and you have 5,000 a week." Three options: + +1. **Accept a larger MDE.** Pick a bigger change worth detecting. A 3 percent absolute lift may be detectable in two weeks; a 0.3 percent lift may take a year. Test the bigger change. +2. **Find a more sensitive metric.** Sometimes the metric is the constraint, not the change. Switching from "purchases" to "add-to-cart" gives you a higher-frequency event with more sample. The trade-off is that ATC is less directly tied to revenue; pair the more-sensitive primary with a revenue guardrail. +3. **Skip the test.** If the change is small but cheap and reversible, ship without testing. If it is small and expensive to maintain, do not ship. Running an underpowered test produces noise dressed up as evidence; that is worse than no test. + +The discipline is to refuse to run tests that cannot answer the question. An underpowered test is not "better than nothing"; it is worse than nothing because it produces a result that feels meaningful but is not. diff --git a/skills/experimentation-analytics/SKILL.md b/skills/experimentation-analytics/SKILL.md new file mode 100644 index 0000000..eb34627 --- /dev/null +++ b/skills/experimentation-analytics/SKILL.md @@ -0,0 +1,333 @@ +--- +name: experimentation-analytics +description: How to read experiment results without fooling yourself. Confidence intervals, p-values, multiple testing, sequential testing, CUPED, heterogeneous treatment effects, ratio metrics, network effects, dashboard reconciliation, and the interpretation failures that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Read result panels without fooling yourself: confidence intervals, p-values, multiple testing, sequential testing, CUPED, ratio metrics, network effects, dashboard reconciliation" +display_order: 6 +--- + +# Experimentation Analytics + +A data-team-mentor's playbook for interpreting experiment results without fooling yourself. + +The result panel is the moment-of-truth for an experiment. The numbers on it determine whether you ship, kill, or iterate. They also expose every shortcut taken in the design phase: an underpowered test produces wide confidence intervals; a peeked test produces a too-narrow p-value; a ratio metric without delta-method correction produces overconfident lift estimates. Most ship-the-wrong-thing decisions trace back to misreading the result panel. + +This skill is the discipline that prevents misreading. It assumes the experiment was designed well (see the `experiment-design` skill). It assumes the platform's results panel is technically correct (most modern platforms are; some older ones are not). It assumes you can read a number off a screen. The hard part is knowing what each number actually means and what it does not, and that is what is here. + +When to use this skill: any time you are reading an experiment result panel and about to make a ship, kill, or iterate decision. + +--- + +## What this skill is for + +This skill covers result interpretation, the statistical concepts that make the numbers trustworthy, and the dashboard reconciliation work that prevents executive-level confusion when the experiment number does not match the BI number. The audience is product managers and data analysts who read experiment results together and need a shared vocabulary that does not paper over the dangerous parts of statistics. + +Companion skills cover the adjacent territory. The `experiment-design` skill covers pre-experiment thinking: hypothesis, sample size, MDE, segments, what NOT to test. Read it before designing the test; read this skill when reading the result. The `feature-flagging` skill covers the operational mechanics of flag management, environment promotion, and stale-flag cleanup. Together the three skills span the experimentation lifecycle from intent through interpretation. For platform-specific MCP commands, consult the chosen platform's docs; Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, and Kameleoon all expose rich analytics surfaces that this skill informs how to read. + +--- + +## The result panel: what every modern platform should expose + +A result panel that omits any of the following is a black box. Treat results from black-box platforms with extra skepticism, and consider exporting raw assignment and event data into a notebook where you can compute the missing pieces yourself. + +What a competent platform exposes: + +- Variants and traffic allocation (e.g., 50/50, 33/33/33). Allocation drift across the test window indicates assignment bugs. +- Per-variant primary metric: point estimate, confidence interval (or credible interval for Bayesian), sample size at the variant level. +- Lift: variant minus control, expressed as both absolute change and relative percent. Both numbers matter; relative is intuitive, absolute is what shows up in revenue calculations. +- Statistical significance: p-value (frequentist) or probability of being best (Bayesian). The methodology should be labeled clearly so you know which interpretation rules apply. +- Variance reduction technique applied: CUPED, post-stratification, regression adjustment. If the platform applies these silently, ask which. +- Guardrail metric statuses: each guardrail labeled green, amber, or red against its tolerance. The tolerance was set at design time; the panel just enforces it. +- Per-segment results for pre-registered segments only. Post-hoc segment slicers are tempting and dangerous. +- Test status: running, ended, decision filed. +- A time series of the lift across the test window. This is where novelty effects, primacy effects, and assignment bugs become visible. + +If you are looking at a result panel that hides any of these, the first move is to surface them, not to ship. + +--- + +## Confidence intervals: the most important number + +The single most important number on the result panel is the confidence interval (CI) on the lift. More important than the point estimate. More important than the p-value. The CI tells you what you actually know. + +What a 95% CI of [+2%, +6%] means: under repeated sampling, the true effect would fall in this range 95% of the time. The true effect is most likely somewhere near the middle, but the extremes are entirely consistent with the data. + +What it does not mean: it does not literally mean "there is a 95% chance the true effect is between +2% and +6%." That is the Bayesian credible interval, which often gives similar numerical answers but is conceptually different. PMs can usually live with the loose intuition; analysts should know the precise version when defending a number to a skeptic. + +The width of the CI matters more than the center for most ship decisions. A wide CI means you do not know much yet. A narrow CI means you know with precision. The point estimate is your best guess; the width is your humility. + +Practical decision rules, in order of importance: + +1. If the CI includes zero AND a meaningful positive number (say [-1%, +5%]), you do not have enough data to ship. Period. The point estimate may look favorable, but the data is consistent with no effect and consistent with a meaningful win. You cannot tell which. +2. If the CI is all-positive (lower bound greater than zero, e.g., [+1%, +4%]), there is a real effect. Now evaluate magnitude: is the lower bound large enough to be worth the implementation cost? +3. If the CI is all-negative (upper bound less than zero, e.g., [-5%, -1%]), there is real harm. Kill the test. +4. If the CI straddles zero but is narrow (e.g., [-0.5%, +0.5%]), this is a real null result. The effect is small enough to call essentially zero. Useful information; do not ship the change for "lift" reasons (you found none) but do not panic about harm either. +5. If the CI straddles zero and is wide (e.g., [-5%, +8%]), the test is inconclusive. The data is consistent with a moderate win, no effect, or a moderate loss. Run longer, run bigger, or accept that the question cannot be answered at the available traffic. + +For a worked-example cheatsheet, see [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). + +--- + +## P-values: what they mean and what they do not + +The p-value is the probability of observing the lift you saw (or a larger one) IF the true effect were zero. A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. + +What the p-value does not mean, despite frequent abuse: + +- It does not mean "there is a 96% chance the treatment works." That sentence has no defensible interpretation; the p-value is computed under the assumption that the treatment does NOT work, so it cannot tell you the probability that it does. +- It does not mean "the effect is large." A tiny effect tested against a huge sample can produce a vanishingly small p-value. The p-value is about the strength of evidence against the null, not the size of the effect. +- It does not mean "the result will replicate." A p-value of 0.04 is associated with replication rates well below 50% in most published research; statistical significance is not reproducibility. + +The 0.05 cutoff is convention, not law. If you pre-committed to alpha equals 0.05, follow it; the discipline of pre-commitment is more valuable than the specific threshold. If you did not pre-commit, p equals 0.06 is not categorically different from p equals 0.04, and treating it as such is theater. + +Always read the CI alongside the p-value. The p-value tells you about the null hypothesis; the CI tells you about the magnitude. Both matter; neither is sufficient alone. A p-value of 0.001 with a CI of [+0.1%, +0.3%] is a real but practically tiny effect; a p-value of 0.08 with a CI of [-1%, +12%] is a noisy estimate that could be huge or zero. The former is technically significant and not worth shipping; the latter is technically not significant and you might still want to dig deeper. + +The peeking problem applies to p-values directly. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Modern platforms with sequential testing report "always-valid" or "anytime-valid" p-values that survive peeking; older platforms do not. Know which you are looking at. See [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md) for deeper coverage. + +--- + +## Multiple testing corrections + +The problem in one sentence: with twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty comparisons, two or three. With a hundred, five. + +Where multiple testing creeps in unintentionally: + +- Multiple variants: A vs B vs C vs D is three pairwise comparisons against control, not one. +- Multiple metrics: tracking primary plus six guardrails plus three secondary metrics is ten chances to find significance somewhere. +- Multiple segments: ten segments times three metrics is thirty chances. +- Multiple time windows: looking at week 1, week 2, week 3, and the full test is four chances per metric per segment. + +Two correction methods you should know: + +- Bonferroni correction. Divide alpha by the number of comparisons. Conservative; controls the family-wise error rate (the probability of even one false positive across the family of tests). Use when false positives are catastrophic. +- Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (the expected proportion of false positives among the things called significant). Better for exploratory analysis. + +Most modern platforms support these natively as a configuration option. Configure them, or know which the platform applies by default. Some platforms apply corrections silently to the displayed p-values; others report uncorrected numbers and expect you to do the math. + +The PM-friendly heuristic: pre-register your primary metric and primary segment. Treat everything else as exploratory. Findings in non-primary metrics or non-primary segments require larger effects, replication in a follow-up test, or both before they justify shipping. The discipline of designating primary up front protects you from the multiple-testing trap better than any correction formula. + +--- + +## Sequential testing math + +The peeking problem revisited from the analytics side. Classical t-tests, z-tests, and proportion tests assume one analysis at the end of a test. If you analyze the data five times during the test and stop the moment you see significance, your false positive rate is much higher than the nominal 5%. With daily peeking on a four-week test, false positive rate can climb above 30%. + +Sequential testing methods adjust the math to allow continuous monitoring without inflating false positives. The names you will encounter: + +- mSPRT (mixture sequential probability ratio test). Produces "always-valid" p-values: you can look any time, and the false positive rate stays at the nominal alpha. Common in modern platforms. +- Group sequential designs. Plan a fixed set of interim analyses (say, three) with adjusted significance thresholds at each. Less flexible than mSPRT but well-understood. +- Anytime-valid confidence intervals. The CI version of always-valid p-values. Wider than fixed-horizon CIs by design; the cost of peek-safety is some statistical efficiency. + +Modern platforms with sequential testing built in: Statsig (always-valid by default), Eppo (sequential CIs as a configuration), parts of PostHog (depending on the experiment type), GrowthBook (mSPRT supported). If your panel says "always-valid p-value" or "anytime-valid CI," that is sequential. If it says "p-value" with no qualifier, it is probably fixed-horizon and peeking inflates false positives. + +If your platform does not support sequential testing, the discipline is: pre-commit to a single analysis date at launch, do not peek, and if you must peek, do not make decisions based on the peek. Save the decision-making for the pre-committed date. This is hard. Sequential testing makes it easier. + +The trade-off: sequential tests have wider CIs and less aggressive p-values than fixed-horizon tests at the same sample size. The cost is real but usually worth it for PM contexts where the discipline of not peeking is impractical. + +--- + +## CUPED variance reduction + +CUPED (Controlled-experiment Using Pre-Experiment Data) uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. The result is the same point estimate with a much narrower confidence interval, often 30% to 50% narrower, which is equivalent to roughly doubling your effective sample size for free. + +When CUPED helps: + +- Metrics with high pre-experiment baseline variance: revenue per user, sessions per user, engagement minutes, content consumption. +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When CUPED does not help: + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline (a user either signs up or does not; there is nothing to subtract). +- Tests where pre-experiment behavior is essentially uncorrelated with the metric being moved. + +How to read CUPED-adjusted results: the point estimate is roughly the same as the unadjusted estimate; the CI is narrower. If a result switched from "significant with CUPED" to "not significant without CUPED," that is normal and the CUPED-adjusted version is the more powerful test. If a result went the other way (significant without CUPED, not significant with), the unadjusted result was probably noise that CUPED correctly removed. + +A common confusion: "CUPED made our lift smaller, so we should ship the unadjusted version." This is wrong. CUPED reduces variance, not point estimates. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. Trust the adjusted version. + +Platform support: Statsig, Eppo, GrowthBook, parts of PostHog, Amplitude (Experiment product). Optimizely has equivalent variance reduction. If your platform offers CUPED, turn it on for any metric where pre-experiment data exists. + +For deeper coverage of CUPED, the delta method, and other statistical methods, see [`references/statistical-method-reference.md`](references/statistical-method-reference.md). + +--- + +## Heterogeneous treatment effects (HTE) and segments + +A heterogeneous treatment effect is when the treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. This is common, often interesting, and easy to over-read. + +Why HTE is tempting: "let us just ship to new users." Why it is dangerous: post-hoc segment discovery is often noise; targeting infrastructure costs are real; UI complexity from per-segment behavior compounds over time. + +The right way to handle HTE: + +- Pre-register the segments you care about before launching. Two or three is plenty; ten is overfitting waiting to happen. +- If a pre-registered segment shows a meaningfully different effect, treat it as evidence worth following up. Not as a green light to ship to that segment alone. +- Before shipping segment-only behavior, ask: is the segment large enough to matter, is the effect large enough to justify the targeting work, and can we build the targeting cleanly in production? +- If the segment was discovered post-hoc by slicing the data many ways, treat the finding as a hypothesis for a follow-up test. Do not ship based on one observation. + +HTE versus simple averaging: when segments have meaningfully different effects, the average underrepresents both. A treatment that is +10% for half the population and -5% for the other half averages to +2.5%, which understates the win for half and ignores the loss for the other. The average is still the right number for "ship to everyone" decisions; per-segment numbers are the right inputs for "should we invest in segment-specific targeting" decisions. + +Practical heuristic: if pre-registered segments show meaningfully different effects, write a follow-up hypothesis. Run a follow-up test that confirms the segment behavior with appropriate power. Then decide on segment-specific shipping. The cost of the follow-up test is much smaller than the cost of shipping segment-targeted behavior that does not actually work. + +--- + +## Ratio metrics and the delta method + +Most "rate" metrics are ratios. Conversion rate equals conversions divided by users. Click-through rate equals clicks divided by impressions. Revenue per user equals revenue divided by users. Average order value equals revenue divided by orders. + +Why this matters for analytics: standard variance estimation for sums does not apply directly to ratios. Naive variance estimation on ratios produces incorrectly narrow confidence intervals and inflated false positive rates. You ship things that look significant but are not, because the math under the hood was wrong. + +Two correct approaches: + +- Delta method. A calculus-based correction (Taylor expansion linearization) that produces correct CIs and p-values for ratio metrics. Fast, well-understood, what most modern platforms use. +- Bootstrap. A simulation-based alternative: resample users with replacement many times, compute the ratio each time, and read off the empirical distribution. Distribution-free and intuitive; slower than delta method. + +How to verify your platform: ask "what variance estimator do you use for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (one row per user, converted yes or no). If the answer is "delta method," "linearization," or "bootstrap," correct. + +Most modern platforms (Statsig, Eppo, PostHog, Optimizely, GrowthBook) handle this correctly. Older or homegrown platforms often do not. The risk is silent: the panel shows confidence intervals that look reasonable but are too narrow, and you ship changes that do not produce the claimed effect. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. Suppose treatment shows a 5% lift with a CI that excludes zero under the wrong (naive) variance estimator. Under the correct delta-method estimator, the same point estimate has a CI that includes zero. The wrong math says "significant, ship." The correct math says "inconclusive, run longer or accept noise." Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production, then puzzling over why the launch did not move the dashboard. + +--- + +## Bayesian vs frequentist results panels + +Frequentist panels (most older platforms, parts of most modern ones) show p-values, confidence intervals, and "statistically significant" labels. Bayesian panels (Eppo by default, Statsig as an option, parts of PostHog) show probability of being best, credible intervals, and posterior distributions. + +For most PM contexts, both approaches produce similar ship-or-kill decisions when the experiment was designed correctly. The vocabulary differs; the underlying judgment is similar. + +Bayesian advantages: + +- Natural multi-variant comparison: "variant B has 87% probability of being best" reads more naturally than the equivalent Bonferroni-corrected p-value soup. +- Peek-safe by construction: posterior probabilities are valid at any time without sequential corrections. +- More intuitive for stakeholders unfamiliar with hypothesis testing. +- Allows informative priors when you have prior knowledge (rare in practice for shipping decisions). + +Frequentist advantages: + +- Better-understood: most analytics teams have stronger frequentist training. +- Clearer pre-registration semantics: "alpha equals 0.05, MDE equals 5%, decision rule X" is unambiguous. +- Longer track record in regulated contexts. + +Mixing them within a single experiment is fine. Most platforms (Eppo, Statsig) let you toggle. Pick one per experiment and stick with it; do not switch mid-flight to chase a more favorable interpretation. That is the Bayesian-frequentist version of p-hacking and corrodes the discipline. + +--- + +## Network effects and SUTVA violation + +SUTVA (Stable Unit Treatment Value Assumption) is the technical name for "one user's treatment does not affect another user's outcome." When SUTVA holds, standard A/B test math works. When it is violated, the math systematically understates or overstates the true effect. + +When SUTVA is violated: + +- Two-sided marketplaces. Changes to buyers shift seller behavior, which affects control buyers competing for the same supply. Treatment buyers' actions leak into the control group's experience. +- Social products. A treatment user's changed behavior affects the experience of users they interact with, regardless of which group those friends are in. +- Supply-constrained features. When supply is limited, treatment users compete with control users for the same scarce resource, and the test cannot cleanly separate treatment effect from substitution. +- Notification systems. A treatment that increases notification volume changes user behavior across the whole platform, not just in the treatment cell. + +The "interference dampens lift" pattern is the most common version. In marketplace experiments, if your treatment looks small, the true effect (in the absence of interference) may be 2x to 3x larger than what the standard A/B test reports. Killing a winning test because the leaked-into-control lift looked small is a common mistake. + +Detection methods: + +- Switchback experiments. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control, etc.). Eliminates cross-user interference within each window; requires careful temporal modeling. +- Cluster randomization. Assign whole units (cities, markets, friend groups) rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. +- Geographic experiments. Launch in some regions, hold others. Slow and expensive but interference-clean. + +When in doubt about whether interference is present, run a small cluster-randomized version as a check. If the cluster-randomized lift is much larger than the user-randomized lift, you have evidence of interference and should rerun the main test as cluster-randomized. + +--- + +## Dashboard metric vs experiment metric reconciliation + +The scenario: your business intelligence dashboard shows revenue grew 8% last week. Your experiment platform shows the treatment lifted revenue 2%. How can both be true? + +Likely answers, ranked by frequency: + +- Different denominators. The dashboard shows all users; the experiment shows just enrolled users. Most experiments enroll a subset; the lift only applies to that subset. +- Different time windows. The dashboard is rolling 7 days; the experiment is fixed start to end. The two windows can move independently. +- External effects. Marketing campaigns, seasonality, competitor activity, news cycles. The experiment correctly excludes these by random assignment; the dashboard reflects them. +- Selection effects. Who gets enrolled in the experiment matters. New users only? Logged-in users only? Users who passed a feature flag check? Each filter changes the population the lift applies to. +- Different metric definitions. "Revenue" might be gross in one place and net of refunds in another. "Conversions" might count differently across systems. + +Reconciliation discipline: never report experiment results as "the feature drove $X in revenue this week." Always report as "the feature lifted enrolled-user revenue Y% during the test period." The first phrasing implies a company-wide impact that the experiment cannot measure; the second phrasing is precise about what the experiment actually showed. + +The "blended attribution" trap is the most common reconciliation failure. PM takes the experiment lift (say +2% revenue per user) and multiplies by the total user base for a company-wide impact estimate ("$10M in incremental revenue"). This is wrong twice over. The lift only applies to enrolled users (typically 10% to 50% of the base). Even within the enrolled group, the lift was measured during the test conditions; long-term and at full scale, the effect can be different. The right phrasing is "during the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control." Then leadership can do the careful arithmetic of how that translates at full launch. + +For deeper reconciliation patterns and stakeholder-facing language, see [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). + +--- + +## Long-term effect estimation + +Most A/B tests run for two to four weeks. Many feature decisions need a thirty- to ninety-day understanding because behavior changes over longer windows: novelty fades, primacy fades, retention impacts emerge, network effects compound. + +Three patterns for long-term measurement: + +- Holdout groups. Keep a percentage of users (often 5% to 10%) on the control treatment for thirty or more days post-launch. Compare their long-term behavior to the launched-to users. The comparison measures the long-term effect cleanly because the holdout was randomized at the same time as the original test. +- Geo experiments. Launch the change in some markets and hold others. Measure long-term differences across market pairs. Slow, expensive, and the markets need to be comparable, but interference-clean and capable of measuring effects that user-randomization cannot. +- Difference-in-differences (diff-in-diff). Pre-launch versus post-launch measurement in a treated market versus a control market. Useful when you cannot randomize at all (regulatory rollouts, partner-specific changes). Weaker than randomized methods but defensible when randomization is impossible. + +Practical heuristic: any feature with novelty risk (new UI, new mechanic, new pricing, new notification cadence) deserves a thirty-day holdout. Set it up at launch, not later; setting it up later requires unwinding the launch and is rarely done in practice. The cost of the holdout is small (a small percentage of users on the old experience for a month); the value is the ability to detect long-term degradation before it compounds. + +--- + +## Common interpretation failures + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "P equals 0.04, ship it." No consideration of CI width, magnitude, or guardrails. Significance is a necessary condition, not a sufficient one. +- "We saw +5% on day 3, ending early." Peeking, novelty effect, or both. Day-3 lifts are routinely larger than day-14 lifts; ending early ships noise. +- "The new flow worked for power users (post-hoc segment)." Noise mining. The segment was found by slicing the data multiple ways; the apparent lift will not replicate. +- "Our experiment said +2%, but launch only delivered +0.5%." Often the experiment was correct: the lift applied to enrolled users in test conditions, and at full launch the effect is diluted by non-enrolled users, novelty fade, or interference effects the test could not capture. +- "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail violation that was reframed as "no signal." If retention is a guardrail, the guardrail is binding; "we did not see a clear signal" is not the same as "we have evidence of safety." +- "We CUPED-adjusted away a real treatment effect." CUPED reduces variance, not the point estimate. If the lift looked smaller after CUPED, the unadjusted lift was probably noise that CUPED correctly removed. Trust the adjusted version. +- "Two segments showed opposite effects; we shipped to the better segment." Likely overfitting unless both segments were pre-registered and the targeting infrastructure exists. Re-test before shipping. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped." Inconclusive is inconclusive. Directional patterns are not evidence; they are wishful reading of noise. + +--- + +## The framework: 14 considerations for trustworthy experiment interpretation + +Trustworthy interpretation sits at the intersection of fourteen considerations. Each is covered in detail in its own section above. + +1. **Result panel completeness.** The panel exposes variants, allocation, per-variant metrics, lifts, significance, variance reduction, guardrails, segments, time series, and status. Missing pieces are red flags. +2. **Confidence interval reading.** Width matters more than center. Five practical decision rules cover the cases where CI excludes zero, includes zero narrowly, and includes zero widely. +3. **P-value semantics.** The probability of seeing the lift if the null is true. Not the probability that the treatment works. Always read alongside the CI. +4. **Multiple testing corrections.** Bonferroni for family-wise control, BH for false discovery rate. Pre-register primary metrics and segments; treat the rest as exploratory. +5. **Sequential testing math.** Always-valid p-values and anytime-valid CIs survive peeking. Fixed-horizon p-values inflate false positives under daily monitoring. +6. **CUPED variance reduction.** Same point estimate, narrower CI. Use whenever pre-experiment data is available and informative. +7. **Heterogeneous treatment effects.** Pre-register segments. Treat post-hoc segment effects as hypotheses for follow-up tests, not as ship signals. +8. **Ratio metrics.** Use delta method or bootstrap. Naive proportion estimators understate variance and inflate false positives. +9. **Bayesian vs frequentist.** Pick one per experiment and stick with it. Both produce similar ship decisions when the experiment was designed correctly. +10. **Network effects and SUTVA.** Marketplace and social products often violate SUTVA. Cluster randomization, switchback, or geographic experiments when interference is suspected. +11. **Dashboard reconciliation.** Different denominators, time windows, external effects, and metric definitions explain most disagreements between BI dashboards and experiment panels. +12. **Long-term effect estimation.** Holdouts, geo experiments, and diff-in-diff for effects that emerge over thirty to ninety days. +13. **Common interpretation failures.** A pattern catalog of the most frequent ways smart teams ship wrong things. +14. **The discipline of inconclusive.** The hardest call is "we do not have enough signal to ship." It is often the right call. + +The sections above expand each consideration in turn. Read the relevant section before making the decision, not after. + +--- + +## Reference files + +- [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). How to read a CI, what to ignore, the five decision rules with worked examples for each. +- [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md). What it means, what people pretend it means, the 0.05 convention, the peeking problem, and the multiple-testing context. +- [`references/statistical-method-reference.md`](references/statistical-method-reference.md). CUPED, the delta method, sequential testing methods (mSPRT, group sequential, anytime-valid), HTE handling, multiple testing corrections, cluster randomization. The technical reference for analysts. +- [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). Why the BI number does not match the experiment number, the blended-attribution trap, and how to communicate the difference to non-statistical stakeholders. +- [`references/result-presentation-templates.md`](references/result-presentation-templates.md). Five templates for stakeholder communication: clear win, clear loss, inconclusive (the most common, hardest), mixed (positive primary with ambiguous guardrail), and long-term holdout report. +- [`references/analytics-platform-comparison.md`](references/analytics-platform-comparison.md). Profiles of seven major platforms (Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, Kameleoon) covering what each exposes, what each hides, and the gotchas in each. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). Fifteen-plus failure patterns: name, symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it inconclusive + +Most experiment results are not clear ship-or-kill. They are inconclusive: lift exists but the CI straddles zero; lift is real but does not justify the implementation cost; lift is significant but a guardrail is concerning; lift looks great in one segment but the segment is small or the targeting infrastructure does not exist. + +The hardest decision a PM makes in a given week is often "we do not have enough signal to ship." The temptation to lower the bar after seeing the result is enormous. The discipline of saying "inconclusive" is the discipline of caring about being right more than being decisive. + +The same discipline applies to analysts. The temptation to slice the data one more way until something looks significant, to apply one more variance reduction technique, to switch from frequentist to Bayesian mid-test, is constant. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +Inconclusive is a valid outcome. The lesson, if there is one, is for the next hypothesis: the effect is smaller than expected, the segment matters, the test was underpowered, the metric was the wrong one. Use the inconclusive result to design a better next test. Do not retrofit a story onto the current one. + +For pre-experiment design discipline, see the `experiment-design` skill. For the operational mechanics of feature flags that deliver the variants, see the `feature-flagging` skill. For platform-specific MCP commands and example prompts, consult the chosen platform's documentation. diff --git a/skills/experimentation-analytics/references/analytics-platform-comparison.md b/skills/experimentation-analytics/references/analytics-platform-comparison.md new file mode 100644 index 0000000..a8c3504 --- /dev/null +++ b/skills/experimentation-analytics/references/analytics-platform-comparison.md @@ -0,0 +1,147 @@ +# Analytics platform comparison + +Profiles of seven major experimentation platforms covering what each exposes, what each hides, and the gotchas in each. For MCP setup, auth, and example prompts, consult each platform's official documentation. + +The categorization below is for analytics surface area specifically. All seven platforms are competent at running experiments; the difference is what they expose on the result panel and how the math under the hood handles edge cases. + +--- + +## Statsig + +**Statistical defaults.** Among the most rigorous in the category. Always-valid p-values (sequential testing) by default. CUPED variance reduction available and easy to enable. Delta method for ratio metrics. Comprehensive HTE analysis with pre-registered and exploratory modes. + +**What is exposed.** Per-variant metrics with CIs, lift point estimate, always-valid p-value, sample size, variance reduction technique applied, guardrail status, segment results for pre-registered segments, time series of the lift across the test window. + +**What can be hidden by default.** Some advanced configuration is buried in the UI; defaults are sensible but worth confirming. The "topline metrics" view simplifies away the CI in some contexts. + +**Gotchas.** + +- Always-valid p-values are wider than fixed-horizon by design. Teams new to sequential testing sometimes interpret "less significant" as "weaker effect" rather than "peek-safe math." +- The auto-generated guardrail metrics catch some categories well (latency, error rate) and miss others (business-critical metrics specific to your product). Augment with custom guardrails. +- The "experiment hub" view groups results across multiple experiments and can mask single-experiment subtlety. + +**Where it shines.** Mid-stage to late-stage product teams running many concurrent experiments where peek-safety and variance reduction matter. The default rigor saves teams from common mistakes without requiring statistical expertise. + +--- + +## PostHog + +**Statistical defaults.** Solid for the open-source experimentation category. Frequentist by default; Bayesian available. Variance reduction via "stats engine" configuration. Sequential testing in some experiment types. + +**What is exposed.** Per-variant metrics, CIs, p-values, sample size, time series, segment results. + +**What can be hidden.** The newer "stats engine" updates change defaults across versions; what you see depends on the deployment version. Older deployments may use less-rigorous defaults. + +**Gotchas.** + +- Self-hosted vs cloud can differ in stats engine version. Confirm the version when interpreting numbers. +- The "winner" badge can appear on results that are technically significant but practically tiny. Always read the CI. +- Bayesian and frequentist views can coexist for the same experiment; use one consistently per experiment. + +**Where it shines.** Teams that want experimentation embedded in their analytics platform rather than separate. PostHog's strength is the integration of feature flags, experiments, session recording, and product analytics in one place. + +--- + +## Optimizely + +**Statistical defaults.** Enterprise-grade rigor. Stats Engine includes sequential testing, ratio-aware variance estimation, and configurable significance thresholds. Long track record in the category. + +**What is exposed.** Comprehensive per-variant statistics, configurable significance thresholds, sequential testing labels, sample size, segment analysis with pre-registration. + +**What can be hidden.** Configuration depth means defaults vary by account setup. Confirm with the platform admin which defaults are in play for your project. + +**Gotchas.** + +- The classic Optimizely product (Web Experimentation) and the newer products (Feature Experimentation, Personalization) have different stats engines. Know which product your team is on. +- Enterprise pricing can mean limited license seats; non-statistician PMs sometimes work from screenshots taken by analysts, which loses interactive panel context. +- The "lift" display can default to relative percent without the absolute number; both matter. + +**Where it shines.** Larger organizations with established experimentation practices, regulated contexts where the rigorous track record matters, and teams that need extensive personalization alongside experimentation. + +--- + +## GrowthBook + +**Statistical defaults.** Open-source-first, warehouse-native. Explicit choice between Bayesian and frequentist. Sequential testing via mSPRT. CUPED supported. + +**What is exposed.** Per-variant metrics with CIs, lift, significance, variance reduction, guardrails, segment results. + +**What can be hidden.** Because GrowthBook runs on top of your data warehouse, the metric definitions live in your SQL; verify them when reading results. A subtle metric query change can shift results without anyone noticing. + +**Gotchas.** + +- Warehouse latency affects how fresh the result panel is. A daily batch is common; treat panel data as up to one day stale. +- Custom metrics defined in SQL can drift from dashboard definitions of the same metric. Reconcile carefully. +- The "experiment health checks" surface assignment imbalance and other quality issues; pay attention when they fire. + +**Where it shines.** Engineering-led teams that want experimentation tied directly to the warehouse and version-controlled metric definitions. The open-source core means full transparency on the math. + +--- + +## Eppo + +**Statistical defaults.** Best-in-class statistical defaults among the platforms. Bayesian and frequentist supported, with Bayesian as the default for most use cases. Sequential CIs available. CUPED supported. Delta method for ratio metrics. Strong HTE analysis. + +**What is exposed.** Per-variant metrics with credible intervals (Bayesian) or CIs (frequentist), probability of being best, posterior distributions, lift, guardrails, segments. + +**What can be hidden.** The Bayesian default produces "probability variant B is best" rather than a p-value, which can confuse stakeholders trained on frequentist conventions. Switch to frequentist if your team's vocabulary is p-value-based; do not switch mid-experiment. + +**Gotchas.** + +- Bayesian probabilities and frequentist p-values answer different questions; do not translate one into the other naively. +- Eppo's "decision support" feature recommends actions based on the result; treat the recommendation as input, not as the decision. +- Warehouse-native like GrowthBook; same caveats about metric definition drift. + +**Where it shines.** Data-team-led organizations that want statistical rigor as a default. Eppo's design philosophy is "make it hard to do the wrong thing"; the defaults reflect that. + +--- + +## Amplitude (Experiment) + +**Statistical defaults.** Behavioral analytics first, experimentation second. Frequentist defaults; sequential testing available. Variance reduction supported. + +**What is exposed.** Per-variant metrics with CIs, p-values, sample size, segment analysis, guardrails. Tightly integrated with Amplitude's behavioral analytics surface. + +**What can be hidden.** Some statistical configuration options are less prominent than in Statsig or Eppo; defaults are reasonable but worth confirming. + +**Gotchas.** + +- Strength is the integration with behavioral analytics, not the rigor of the experimentation engine. For teams that prioritize statistical sophistication, the engine is competent but not the strongest. +- Amplitude's "insights" auto-generate from event data; the same flexibility that makes them useful makes it easy to slice into noise. +- Experiment results can be viewed alongside cohort and funnel analyses; this is powerful and risky (post-hoc cohort definitions are noise mining). + +**Where it shines.** Product teams already invested in Amplitude for behavioral analytics. The integration of experiment results with the broader product analytics is the differentiator. + +--- + +## Kameleoon + +**Statistical defaults.** Frequentist with Bayesian options. CUPED and sequential testing supported. Strong personalization and AI-driven optimization features. + +**What is exposed.** Per-variant metrics with CIs, p-values, lift, segments, guardrails. + +**What can be hidden.** The personalization and AI optimization features can take experiment results and apply them automatically; verify which of your "experiments" are actually fully randomized A/B tests vs personalization rollouts. + +**Gotchas.** + +- The boundary between experiment and personalization can blur. Personalization decisions made by an AI engine are not the same as ship decisions made from a randomized A/B test. +- Less common in the US than the European market; documentation and community resources are more limited than for Statsig, PostHog, or Optimizely. +- Some advanced statistical features require specific subscription tiers. + +**Where it shines.** Teams running heavy personalization alongside experimentation, particularly in the European market. The personalization features are differentiated; the experimentation engine is competent. + +--- + +## Quick comparison + +| Platform | Sequential testing | CUPED | Delta method | Bayesian option | Strongest for | +|---|---|---|---|---|---| +| Statsig | Default | Yes | Yes | Yes | Multi-team experimentation rigor | +| PostHog | Some types | Configurable | Yes | Yes | Embedded analytics + experiments | +| Optimizely | Yes | Yes | Yes | No (frequentist Stats Engine) | Enterprise + personalization | +| GrowthBook | Yes (mSPRT) | Yes | Yes | Yes | Warehouse-native, open source | +| Eppo | Yes | Yes | Yes | Default | Statistical rigor by default | +| Amplitude | Yes | Yes | Yes | Yes | Behavioral analytics integration | +| Kameleoon | Yes | Yes | Yes | Yes | Personalization-heavy contexts | + +The platform choice is rarely the bottleneck on getting experimentation right. All seven are competent. The bottleneck is the design discipline (covered in the `experiment-design` skill), the interpretation discipline (covered in this skill), and the operational discipline of the flag layer (covered in the `feature-flagging` skill). Pick the platform that fits the team's existing stack and skill mix; spend the effort on the disciplines. diff --git a/skills/experimentation-analytics/references/common-interpretation-failures.md b/skills/experimentation-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..86c27fb --- /dev/null +++ b/skills/experimentation-analytics/references/common-interpretation-failures.md @@ -0,0 +1,203 @@ +# Common interpretation failures + +Fifteen-plus failure patterns that produce confidently wrong shipping decisions. Each pattern is described as: name, symptom (what it looks like in the panel or the discussion), root cause (why it happens), fix (what to do this time), prevention (how to avoid it next time). + +--- + +## Pattern 1: P-value worship + +**Symptom.** "P equals 0.04, ship it." No discussion of CI width, magnitude, or guardrails. + +**Root cause.** Treating statistical significance as a binary truth. The p-value answers one specific question (how surprising is this data under the null) and people use it to answer all questions. + +**Fix.** Always pair the p-value with the CI on the lift and the guardrail status. A significant p-value with a wide CI that includes practically tiny effects is not a ship signal. + +**Prevention.** Pre-commitment includes the MDE, not just the alpha. The decision rule should reference the lift magnitude relative to the MDE, not just the p-value. + +--- + +## Pattern 2: Early stop on a peek + +**Symptom.** Test ended on day 3 or day 5 because the result "looked great." Headline lift is 5% to 10%; later analysis shows the effect was much smaller. + +**Root cause.** Standard p-values inflate under peeking. Early-test lifts are systematically larger than late-test lifts due to regression to the mean and novelty effects. + +**Fix.** Re-run the test to the pre-committed end date. Treat the early result as suggestive only. If the platform supports always-valid p-values, those are peek-safe; otherwise, do not stop early. + +**Prevention.** Pre-commit the analysis date at launch. If the platform offers sequential testing, enable it. If not, do not look at intermediate results. + +--- + +## Pattern 3: Post-hoc segment mining + +**Symptom.** "The new flow worked for power users on Android in the EU on weekends." The segment was discovered by slicing the data many ways looking for an effect. + +**Root cause.** Multiple comparisons. With enough segments, some will show a "significant" effect purely by chance. The pattern is real for the test data; it does not replicate. + +**Fix.** Treat the post-hoc segment finding as a hypothesis for a follow-up test, not as a ship signal. Pre-register the segment in the new test and run it cleanly. + +**Prevention.** Pre-register segments at design time. Two or three is plenty; ten is overfitting waiting to happen. Treat any segment not in the pre-registration list as exploratory. + +--- + +## Pattern 4: Launch dilution misread + +**Symptom.** "Our experiment said +2%, but launch only delivered +0.5%. The experiment was wrong." + +**Root cause.** The experiment lift applied to enrolled users in test conditions. Launch dilution from non-enrolled users, novelty fade, and interference effects routinely produce smaller production effects than test effects. The experiment was usually correct; the production measurement is correctly capturing the diluted effect. + +**Fix.** Compare apples to apples: the launch effect on the same enrolled-user population, in the same conditions. If the launch effect on enrolled users matches the test, the experiment was right; the dashboard sees a smaller number because the dashboard includes everyone. + +**Prevention.** Communicate experiment results in enrolled-user terms, not extrapolated to the full base. The blended-attribution trap is the source of most "experiment wrong" complaints. + +--- + +## Pattern 5: Guardrail reframing + +**Symptom.** "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail movement that was reframed as "no signal" rather than treated as binding. + +**Root cause.** The guardrail was pre-committed but the team did not pre-commit a clear rule for "what counts as a guardrail violation." A wide CI on the guardrail leaves room for interpretation; the interpretation usually favors shipping. + +**Fix.** If retention is a guardrail, the guardrail binds. "We did not see a clear signal" is not the same as "we have evidence of safety." A wide guardrail CI means the test was underpowered for the guardrail; the right answer is more sample, not "ship anyway." + +**Prevention.** At pre-commitment, define guardrail rules as: "ship only if the CI on the guardrail clearly excludes a [X percent] degradation." Then apply the rule mechanically when results come in. + +--- + +## Pattern 6: CUPED misinterpretation + +**Symptom.** "We CUPED-adjusted away a real treatment effect. Let us report the unadjusted version." OR "The unadjusted lift is bigger; CUPED is hiding our win." + +**Root cause.** Misunderstanding what CUPED does. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior. + +**Fix.** Trust the CUPED-adjusted estimate. If the estimate is smaller and the CI is narrower, the CUPED estimate is closer to the true effect. + +**Prevention.** Educate the team on what CUPED does before enabling it. The first time the unadjusted and adjusted numbers diverge, walk through why. + +--- + +## Pattern 7: Opposite-segment shipping + +**Symptom.** "Two segments showed opposite effects; we shipped to the better segment." Often without re-testing or without infrastructure to support segment-specific behavior. + +**Root cause.** Post-hoc segment discovery (most common) or pre-registered segments where the targeting infrastructure does not exist. Either way, segment-only shipping is a significant commitment that requires more evidence than a single observation. + +**Fix.** Treat the segment finding as a hypothesis for a follow-up test. Confirm the effect with an appropriately powered re-test. Build the targeting infrastructure with eyes open about ongoing maintenance cost. + +**Prevention.** Pre-register segments. Build the targeting infrastructure separately, before any segment-specific shipping decision; do not let the decision force the infrastructure into existence under deadline pressure. + +--- + +## Pattern 8: Directional ship + +**Symptom.** "The result was technically inconclusive, but the trend was directional so we shipped." + +**Root cause.** Inconclusive is hard to communicate; directional language sounds more decisive. The team substitutes the appearance of evidence for actual evidence. + +**Fix.** Inconclusive is inconclusive. The directional pattern is wishful reading of noise. Do not ship; either run a bigger test or kill the hypothesis. + +**Prevention.** Pre-commit decision rules that map each possible result to a ship-or-kill decision. The inconclusive case should map to "do not ship" by default. Discussions of "directional" outcomes are a sign that pre-commitment was incomplete or is being ignored. + +--- + +## Pattern 9: Mid-test methodology switch + +**Symptom.** Test was running with frequentist analysis; results were ambiguous; team switched to Bayesian (or vice versa) and the new view "shows we should ship." + +**Root cause.** Different methodologies can produce different ship recommendations on the same data, particularly near the significance threshold. Switching mid-flight to find the more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +**Fix.** Stick with the methodology pre-committed at launch. If the result is ambiguous under the pre-committed method, that is the result. + +**Prevention.** Pre-commit the methodology along with the metric and the alpha. Document the choice in the experiment configuration so the change is visible if anyone tries. + +--- + +## Pattern 10: Ratio metric without delta method + +**Symptom.** Conversion rate or revenue per user with a CI that looks suspiciously narrow. The result panel shows significance that does not replicate at launch. + +**Root cause.** Naive variance estimation on ratio metrics produces incorrectly narrow CIs and inflated false positive rates. The platform did not use delta method, bootstrap, or another ratio-aware estimator. + +**Fix.** Re-analyze with a ratio-aware estimator. If the platform does not support one, export raw data and compute correctly in a notebook. + +**Prevention.** Verify your platform's variance estimator for ratio metrics during onboarding. If the answer is "standard t-test on proportions," consider migrating or implementing the correction yourself. + +--- + +## Pattern 11: Marketplace interference undercount + +**Symptom.** Marketplace experiment shows a small lift; team kills the test as not worth the effort. Later, a feature implemented for other reasons shows a much larger effect on the same metric. + +**Root cause.** SUTVA violation. In two-sided marketplaces, treatment users compete with control users for the same supply; the lift "leaks" into control. The standard A/B test undercounts the true effect, often by a factor of 2x to 3x. + +**Fix.** Re-run as cluster randomized (whole markets to treatment or control) or switchback. Compare the results to the user-randomized version to estimate the interference factor. + +**Prevention.** Identify SUTVA violation risk at design time. For marketplace, social, and supply-constrained features, default to cluster randomization or switchback unless interference is demonstrably negligible. + +--- + +## Pattern 12: Definition drift between systems + +**Symptom.** Experiment result shows +X% on conversion. Dashboard shows the launch having no effect on conversion. Investigation reveals the two systems define "conversion" differently. + +**Root cause.** Metric definitions live in different places (experiment platform, BI dashboard, data warehouse) and drift over time. Each definition individually makes sense; the comparison is meaningless. + +**Fix.** Reconcile the definitions before the next post-launch report. Pick one canonical definition and align both systems. + +**Prevention.** Centralize metric definitions (semantic layer, dbt model, shared SQL library). Audit all "the same metric" usages quarterly. + +--- + +## Pattern 13: Confounded test window + +**Symptom.** Test ran during a marketing campaign, a product launch, an outage, or a holiday. The result is reported without acknowledging the external event. + +**Root cause.** Random assignment usually handles external events (treatment and control are equally affected). But if the external event affects the metric definition (campaign brings different user mix), the populations stop being comparable. + +**Fix.** Stratify the analysis by the relevant covariate (acquisition source for campaigns, date for outages). If the stratified analysis differs meaningfully from the pooled analysis, report the stratified version and explain. + +**Prevention.** Maintain a calendar of marketing campaigns, product launches, and known external events. Avoid scheduling sensitive tests during these windows. If unavoidable, plan the stratification at design time. + +--- + +## Pattern 14: Long-tail metric overweighted by outliers + +**Symptom.** Revenue per user shows a large lift driven by a few high-value users. The lift is "significant" but unstable across re-samples. + +**Root cause.** Long-tailed distributions (revenue, session length, content engagement) have a few users contributing disproportionately. Random assignment of those users to treatment or control can drive large apparent effects that do not represent the underlying treatment effect. + +**Fix.** Winsorize the metric (cap extreme values at the 99th percentile, for example) and re-analyze. If the winsorized result is materially different from the raw result, the outliers were driving the effect. + +**Prevention.** Pre-commit to a winsorization threshold for long-tailed metrics. Apply the same threshold across treatment and control. Document the choice. + +--- + +## Pattern 15: Significance from sample size, not effect + +**Symptom.** "P equals 0.001, very significant." CI on the lift is [+0.1%, +0.3%]. Magnitude is tiny. + +**Root cause.** With enough sample, even tiny effects produce small p-values. Significance is not the same as magnitude. Shipping a 0.2% lift because "p was tiny" is a misuse of the framework. + +**Fix.** Read the CI alongside the p-value. If the practical lift is too small to matter, do not ship regardless of significance. + +**Prevention.** Pre-commit to an MDE (minimum detectable effect) as part of the design. If the observed lift is below the MDE, the test was overpowered and the result, while real, is not actionable. + +--- + +## Pattern 16: Overcorrection panic + +**Symptom.** Result shows a clean lift on the primary metric. Team adds five new metrics post-hoc and applies Bonferroni correction across all of them. Now the primary metric is "not significant." + +**Root cause.** Multiple testing corrections apply to pre-registered comparisons, not to post-hoc analyses meant to "stress-test" the result. Adding metrics after seeing the result and then correcting is statistically incoherent. + +**Fix.** Apply corrections only to the pre-registered comparison set. Post-hoc metrics are exploratory and should be reported as such, without claiming to update the primary inference. + +**Prevention.** Pre-register the metric set at design time. Treat any metric not on the list as exploratory. + +--- + +## The pattern behind the patterns + +Most of these failures share a common shape: the team had a hypothesis they wanted to confirm, the result was less clean than hoped, and the team applied an analytical knob (slice, switch methodology, drop outliers, reframe the guardrail, peek early) to make the result look cleaner. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. + +The defense against this pattern is pre-commitment. The defense against pre-commitment being weakened over time is documenting the pre-commitment somewhere immutable (PR description, signed Slack message, pinned ticket) and applying it mechanically when results come in. The pre-commitment is not the team's enemy; it is the team's protection from its own future motivated reasoning. diff --git a/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md b/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md new file mode 100644 index 0000000..1f3e1ec --- /dev/null +++ b/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md @@ -0,0 +1,107 @@ +# Confidence interval cheatsheet + +The CI on the lift is the single most important number on the result panel. This cheatsheet covers what it means, what to ignore, and the five decision rules that map a CI to a ship, kill, or wait decision. + +--- + +## What the CI is + +A 95% confidence interval (CI) on a lift estimate is a range of values that, under repeated sampling of the experiment, would contain the true effect 95% of the time. The point estimate (the center) is your best single guess at the true effect. The width is your humility about how much you actually know. + +Three common CI shapes you will see on result panels: + +- Symmetric. Lift estimate +3% with CI [+1%, +5%]. The middle is the best guess; the bounds are equidistant. +- Skewed. Lift estimate +3% with CI [-0.5%, +8%]. Common with small samples or distributions with long tails. The point estimate is still the best guess; the asymmetry tells you the data is consistent with a wider range on the upside than the downside. +- Always-valid (sequential). Same shape as a normal CI but wider by design. Survives daily peeking. If your panel says "anytime-valid CI," that is what you are looking at. + +--- + +## What to read first + +Width before center. A narrow CI tells you a lot about the true effect; a wide CI tells you very little, regardless of where it is centered. A point estimate of +5% with CI [+4.5%, +5.5%] is a precise estimate of a real lift. A point estimate of +5% with CI [-3%, +13%] is essentially "we have no idea, somewhere between a meaningful loss and a huge win." + +The position of zero relative to the CI. If zero is well outside the CI on the positive side, you have a real positive effect. If zero is well outside on the negative side, you have a real harm. If zero is inside the CI, you cannot rule out "no effect." + +--- + +## What to ignore + +The point estimate alone. Without the CI, the point estimate is a single number with no honesty about how much it could move under different sampling. Reading "lift was +3%" without the CI is reading half the result. + +The p-value alone. P-values tell you about the strength of evidence against the null; CIs tell you about the magnitude of the effect. Both matter. A tiny lift with p equals 0.001 is technically significant and not worth shipping. A big lift with p equals 0.10 is technically inconclusive and worth a follow-up test. + +The "statistically significant" label as a binary. Most platforms color-code significance as a green check or a red X. The label is fine as a heuristic; the underlying CI is what you should defend the decision on. + +--- + +## The five decision rules + +### Rule 1: CI all-positive, lift above MDE. Ship. + +**Example.** MDE was 2%; CI is [+3%, +6%]. + +The lower bound of the CI exceeds the MDE you committed to detect. The data is inconsistent with no effect AND inconsistent with a trivial effect. Confidence is high, magnitude is meaningful. Ship. + +Confirm guardrails are clean before filing the launch. + +### Rule 2: CI all-positive, lift below MDE. Probably do not ship. + +**Example.** MDE was 5%; CI is [+0.5%, +1.2%]. + +The lift is real (CI excludes zero) but small (entire CI is below the MDE). The test was overpowered for the question, or the effect is smaller than expected. Real but tiny lifts are rarely worth shipping; the engineering, testing, and cognitive surface area exceeds the gain. + +The exception: changes that are essentially free to ship and maintain. A copy tweak with a +0.5% lift might be worth shipping; a feature requiring ongoing infrastructure with the same lift is not. + +### Rule 3: CI all-negative. Kill. + +**Example.** CI is [-4%, -1%]. + +The data is inconsistent with no effect and inconsistent with a positive effect. The change made things worse with high confidence. Kill the test. Document the lesson if the result is surprising; sometimes the lesson is "users wanted what we already had." + +### Rule 4: CI straddles zero, narrow. Real null result. + +**Example.** CI is [-0.5%, +0.8%]. + +Zero is inside the CI, but so is everything else within a small range. The data is consistent with no effect and inconsistent with any meaningful positive or negative effect. This is a real "we tested and it does not move the metric" result. Useful information; do not ship for "lift" reasons (you found none) but do not panic about harm either. + +The product question becomes: does the change have value beyond the metric we measured (brand consistency, code maintainability, accessibility)? If yes, ship for those reasons. If no, do not ship. + +### Rule 5: CI straddles zero, wide. Inconclusive. + +**Example.** CI is [-5%, +8%]. + +Zero is inside the CI and so is a wide range of meaningful effects in both directions. The data does not distinguish "moderate win" from "no effect" from "moderate loss." The test was underpowered for the question. + +Three follow-up paths: + +- Run longer or run bigger to narrow the CI. +- Make the treatment bolder so the expected effect is larger and detectable at the available traffic. +- Accept that the question cannot be answered cleanly and move on. + +The temptation is to ship anyway because "the point estimate was favorable." The point estimate is not evidence when the CI is this wide. Resist. + +--- + +## Pairing the CI with guardrails + +The CI on the primary metric is where the ship decision lives. The CI on each guardrail is where the safety check lives. Read both. + +A guardrail CI that excludes the threshold of concern is clean. For example, if retention is a guardrail and you require it to not drop more than 1%, a guardrail CI of [-0.3%, +0.4%] is clean. A CI of [-2%, +0.5%] is not clean even though it includes zero, because the lower bound exceeds the threshold. + +Wide guardrail CIs mean the test was underpowered for the guardrail. That is a real problem: you cannot claim safety on a metric you did not measure precisely. The fix is more sample, not "the point estimate looked fine." + +--- + +## Worked example: the "looks great" trap + +**Setup.** PM running a checkout redesign. Pre-committed primary: revenue per visitor. MDE: 3%. Guardrail: refund rate not increasing by more than 0.5%. + +**Day 5.** Result panel shows revenue per visitor +6%, p equals 0.03, CI [+0.5%, +11.5%]. Refund rate +0.3%, CI [-0.4%, +1.0%]. + +**The temptation.** Both metrics moved favorably; the headline is significant. PM proposes ending the test early. + +**The CI read.** Revenue CI [+0.5%, +11.5%] has a lower bound (+0.5%) below the MDE (+3%). The data is consistent with a real but tiny lift, not just the headline +6%. The guardrail CI [-0.4%, +1.0%] has an upper bound (+1.0%) that exceeds the threshold (+0.5%); the test cannot rule out a guardrail violation. + +**The right call.** Do not ship yet. Run to the pre-committed end date. Both CIs need to narrow before the ship case is defensible. The day-5 read is suggestive but not decisive; it is exactly the case the pre-commitment discipline was designed to handle. + +**Common variant.** PM ships anyway because "the trend is positive." Three weeks later the launch shows a refund rate increase that wipes out the revenue gain. The day-5 CI was warning of this exact possibility; the team did not read the width. diff --git a/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md b/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md new file mode 100644 index 0000000..072b959 --- /dev/null +++ b/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md @@ -0,0 +1,87 @@ +# Dashboard vs experiment reconciliation + +The scenario: the BI dashboard shows revenue grew 8% last week, the experiment platform shows the treatment lifted revenue 2%, and an executive asks how both can be true. This reference covers the common reasons numbers disagree, the blended-attribution trap, and how to communicate the difference. + +--- + +## Why numbers disagree (in order of frequency) + +**Different denominators.** The dashboard is computed across all users (or all sessions, or all transactions). The experiment is computed across enrolled users only. If 30% of users are enrolled in the experiment, the experiment lift applies to roughly 30% of the metric base; the dashboard sees the entire base. A 2% lift on the enrolled 30% looks like roughly 0.6% on the dashboard, even if everything is working perfectly. + +**Different time windows.** The dashboard shows rolling seven days; the experiment shows fixed start to end. Comparing a moving window to a fixed window is comparing two different summaries of overlapping but distinct data. + +**External effects.** Marketing campaigns, seasonality, news cycles, competitor moves, weather. The experiment correctly excludes these by random assignment (treatment and control see the same external effects, so they cancel in the lift estimate). The dashboard reflects them in full. The dashboard moving up has nothing to do with the experiment moving up. + +**Selection effects in enrollment.** Who is enrolled matters. New users only? Logged-in only? Users who passed a feature flag check? Each filter changes the population the experiment lift applies to, and changes how that population's behavior compares to the dashboard total. + +**Different metric definitions.** "Revenue" might be gross in the dashboard and net of refunds in the experiment. "Conversions" might count differently across systems (does a re-purchase count? a subscription renewal? a free trial activation?). Definitional drift between systems is common and almost always under-investigated. + +**Pipeline lag.** The dashboard is real-time or near-real-time. The experiment is computed on a daily batch with attribution windows that delay the metric by hours or days. Comparing a real-time number to a batched-and-attributed number is comparing two different versions of the truth. + +**Different attribution models.** First-touch vs last-touch vs multi-touch attribution can produce wildly different "revenue" numbers from the same underlying events. The dashboard and the experiment might use different models without anyone realizing. + +--- + +## The blended attribution trap + +The most common reconciliation failure: take the experiment lift and multiply by the total user base for company-wide impact. + +**The wrong calculation.** Experiment shows +2% revenue per user. Total active users: 5 million. "The feature drove $X million in incremental revenue." + +**Why it is wrong, twice over.** + +- The lift only applies to enrolled users, not the total base. If 30% of users are enrolled, the in-test impact is roughly 30% of what the multiplication suggests. +- Even within enrolled users, the lift was measured during the test conditions. Long-term and at full scale, the effect can be smaller (novelty fade, interference effects, market saturation) or sometimes larger (network effects that compound, learning effects). + +**The right framing.** "During the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control. Extrapolating to a full launch requires assumptions about how the effect translates at scale; the simple multiplication ignores those assumptions." + +The right framing is longer. Stakeholders sometimes push back on the precision. The precision is the point: the simple version is wrong, and shipping based on the simple version produces forecasts that do not materialize. + +--- + +## How to communicate to non-statistical stakeholders + +The temptation is to translate the experiment result into a single number that sounds like the dashboard. The translation is usually wrong because the two numbers are answering different questions. + +**Better framings:** + +- "The experiment is asking 'does this change move the metric for users who see it?' The dashboard is asking 'how is the metric trending overall?' Both can move independently and both can be true at the same time." +- "The experiment lift applies to enrolled users, in test conditions, during the test window. Translating to a launch forecast requires assumptions about scale, novelty, and interference." +- "If we ship to everyone, we expect the dashboard to move by roughly [X percent of the lift], plus or minus [a wide range], because of [specific assumptions]." + +**Worse framings to avoid:** + +- "The feature drove $X million in revenue this week." (Conflates the experiment lift with the dashboard movement.) +- "We hit our target." (When the target was set against the dashboard but the result is from the experiment.) +- "The lift was bigger in production than in the test." (Usually a sign of confounding, not vindication.) + +--- + +## When to dig into discrepancies vs accept them + +**Dig in when:** + +- The experiment shows a big effect and the dashboard shows nothing. The experiment is making a claim that the launch did not deliver. Either the experiment was wrong (selection effect, pipeline bug, confounder) or the launch is being measured wrong. +- The experiment shows nothing and the dashboard shows a big effect. The experiment is missing a real movement. Either the test was underpowered, the wrong population was enrolled, or the dashboard movement is from external factors. +- The directions disagree (experiment positive, dashboard negative). Almost always indicates a definitional drift or pipeline issue that needs investigation. + +**Accept the discrepancy when:** + +- The magnitudes are different but the directions agree. Usually a denominator or selection issue; document the explanation and move on. +- The dashboard is volatile and the experiment is stable. The dashboard reflects external noise the experiment correctly excludes. +- The dashboard is stable and the experiment showed a small effect. The launch effect is too small to detect in the dashboard's noise. + +--- + +## A reconciliation checklist for the moment of confusion + +When a stakeholder asks "why do these numbers not match?", run through this: + +1. **Same metric definition?** Confirm the experiment and dashboard are computing the metric the same way. Check the definitional doc for both. Ask the data team if there is no doc. +2. **Same denominator?** Confirm the experiment population and the dashboard population. Often they differ. +3. **Same time window?** Confirm the experiment window and the dashboard window are aligned (or explain why they are not). +4. **Any external events?** List campaigns, launches, outages, holidays during the test window. The dashboard reflects them; the experiment cancels them. +5. **Any pipeline lag?** Confirm both numbers are using the same attribution and the same data freshness. +6. **Any selection effects?** Who got enrolled and how? If enrollment was non-random (by feature flag check, by cohort), the experiment population is not representative of the dashboard population. + +If all six check out and the numbers still disagree by a meaningful amount, escalate to data engineering. There is probably a pipeline bug in one of the two systems. diff --git a/skills/experimentation-analytics/references/p-value-interpretation-guide.md b/skills/experimentation-analytics/references/p-value-interpretation-guide.md new file mode 100644 index 0000000..55e87f5 --- /dev/null +++ b/skills/experimentation-analytics/references/p-value-interpretation-guide.md @@ -0,0 +1,118 @@ +# P-value interpretation guide + +The p-value is the most-mentioned and most-misunderstood number on the result panel. This guide covers what it actually means, what people pretend it means, when the 0.05 cutoff binds and when it does not, and how to read p-values alongside the CI. + +--- + +## What the p-value is + +The p-value is the probability of observing the lift you saw (or one larger in magnitude), IF the true effect were zero. It is computed under the assumption that the treatment had no effect; the value tells you how surprised you should be by the observed data under that assumption. + +A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. A p-value of 0.001 means it would happen 0.1% of the time. Smaller p-values are stronger evidence against the null; larger p-values are weaker evidence. + +That is the whole technical definition. Everything else is interpretation, and most of it is wrong. + +--- + +## What the p-value is not + +These are the most common misinterpretations. Each one is wrong for a specific reason. + +**"P equals 0.04 means 96% chance the treatment works."** No. The p-value is computed under the assumption that the treatment does NOT work; it cannot tell you the probability that it does. The Bayesian probability of the alternative depends on the prior, which the p-value does not contain. + +**"P equals 0.001 means the effect is huge."** No. P-values are about the strength of evidence against the null, not the size of the effect. A tiny effect tested against a very large sample produces a tiny p-value. The CI tells you the size; the p-value tells you the certainty. + +**"A significant result will replicate."** Not necessarily. A p-value of 0.05 is associated with replication rates well below 50% in most published research. Statistical significance is one piece of evidence; reproducibility requires confirmation. + +**"P greater than 0.05 means there is no effect."** No. P-values cannot prove the null. A non-significant result means "we do not have enough evidence to reject no-effect," which is weaker than "no-effect is true." The CI tells you the practical conclusion: a wide CI straddling zero is "we do not know," while a narrow CI around zero is "the effect is small enough to call zero." + +**"P equals 0.06 is much worse than p equals 0.04."** No. The 0.05 cutoff is convention; the underlying evidence is roughly the same. Treating 0.06 as categorically different from 0.04 is theater unless you pre-committed to the cutoff. + +--- + +## The 0.05 convention + +Alpha equals 0.05 is the standard significance threshold by historical convention, not because the math says 0.05 is special. The convention is useful because it provides a shared reference point, and pre-committing to a threshold prevents post-hoc rationalization. + +Two valid uses of the threshold: + +- **Pre-committed alpha.** You declared at design time that you would ship if p was less than 0.05 and the CI excluded zero. Now apply the rule mechanically. If the result hit 0.04, follow the pre-commitment. +- **Convention reference point.** When communicating with stakeholders, "significant at the conventional 5% threshold" is a familiar phrasing. Use it as long as the underlying CI is also reported. + +Two invalid uses: + +- **Post-hoc threshold games.** Result is p equals 0.06; you decide that 0.10 is "good enough this time." This is p-hacking. +- **Treating the threshold as a binary truth.** Result is p equals 0.04; you ship without reading the CI. The threshold is necessary but not sufficient evidence to ship. + +--- + +## Always read the CI alongside the p-value + +The p-value tells you about the null hypothesis. The CI tells you about the magnitude. They answer different questions, and decisions need both answers. + +| Scenario | P-value | CI on lift | Decision | +|---|---|---|---| +| Real, meaningful effect | 0.001 | [+3%, +6%] | Ship if guardrails clean | +| Real but tiny effect | 0.001 | [+0.2%, +0.4%] | Probably do not ship; magnitude too small | +| Suggestive but uncertain | 0.08 | [-0.5%, +12%] | Inconclusive; run longer or kill | +| Inconclusive null | 0.30 | [-1%, +1%] | Real null result; do not ship for lift reasons | +| Inconclusive wide | 0.30 | [-7%, +9%] | Underpowered; not enough information | + +Reading just the p-value loses the magnitude. Reading just the CI loses the certainty calibration. Both are routine on every result panel; both deserve attention. + +--- + +## The peeking problem + +Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. + +The math: at one analysis, alpha equals 5% means 5% false positive rate. At three analyses, it climbs toward 14%. At daily peeking on a four-week test, it can exceed 30%. The "significant" results you find by peeking are disproportionately false positives that will not replicate. + +Two fixes: + +- **Sequential testing methods.** Modern platforms (Statsig, Eppo, GrowthBook with mSPRT, parts of PostHog) report "always-valid" or "anytime-valid" p-values that survive peeking. The math is wider by design; the cost of peek-safety is some statistical efficiency. +- **Pre-commitment.** If your platform does not support sequential testing, declare the analysis date at launch and do not peek. If you must peek (some platforms make it hard not to), do not make decisions on intermediate peeks. + +If your panel says "p-value" without a qualifier, assume fixed-horizon. Treat early-peek results as suggestive only. + +--- + +## Multiple testing context + +A p-value of 0.05 means a 5% false positive rate per comparison. With twenty comparisons, you expect one false positive purely by chance. + +Where this matters: + +- Multiple variants (A vs B vs C vs D is three pairwise tests). +- Multiple metrics (primary plus six guardrails plus three secondary is ten chances). +- Multiple segments (ten segments times three metrics is thirty chances). + +Pre-register the primary metric and primary segment. Treat the rest as exploratory. A "significant" finding in a non-primary metric or non-primary segment requires either a larger effect, a follow-up test, or both before it justifies shipping. The discipline of pre-registration protects you from the multiple-testing trap better than any correction formula. + +When the platform applies a correction (Bonferroni, Benjamini-Hochberg) silently, the p-values you see have already been adjusted. Know which the platform applies by default; otherwise you may double-correct in your interpretation. + +--- + +## Bayesian alternatives + +Some platforms (Eppo by default, Statsig as a configuration option) report Bayesian probabilities rather than frequentist p-values. The vocabulary differs: + +- "Probability variant B is best": the Bayesian equivalent of multi-variant frequentist comparison. +- "Probability of beating control by at least X%": directly answers the magnitude question that frequentist p-values dance around. +- "Posterior credible interval": the Bayesian analogue of the confidence interval, with an interpretation closer to lay intuition ("there is a 95% chance the true effect is in this range"). + +For most PM contexts, both approaches produce similar ship decisions when the experiment was designed correctly. Pick one per experiment and stick with it. Switching mid-flight to chase a more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +--- + +## Communicating p-values to non-technical stakeholders + +Stakeholders often want a one-sentence summary. The temptation is "p equals 0.04, so we should ship." The temptation is wrong because it loses the magnitude. + +Better one-liners: + +- "We saw a 4% lift in revenue per visitor; the data rules out no-effect and is consistent with a 2% to 6% true lift." +- "The test was inconclusive: the lift could be anywhere from a small loss to a moderate win." +- "We measured a small but real effect: about 0.5% lift, which is statistically detectable but probably not worth shipping." + +Each names the magnitude, the uncertainty, and the decision implication. None reduces the question to a p-value threshold check. diff --git a/skills/experimentation-analytics/references/result-presentation-templates.md b/skills/experimentation-analytics/references/result-presentation-templates.md new file mode 100644 index 0000000..a89bd8e --- /dev/null +++ b/skills/experimentation-analytics/references/result-presentation-templates.md @@ -0,0 +1,123 @@ +# Result presentation templates + +Five templates for stakeholder communication on experiment results. Each names the structure, the vocabulary, what to emphasize, and what to omit. Use the right template for the result you have, not the one that flatters the team. + +--- + +## Template 1: Clear win + +**When to use.** Primary metric moved past MDE, CI on lift excludes zero, all guardrails clean, pre-registered segments consistent. + +**Structure.** + +1. **Headline.** "We are shipping [feature]. The test showed a [X percent] lift in [primary metric] with [Y percent] confidence. Guardrails are clean." +2. **The number.** Point estimate of the lift, with the CI in parentheses. "Revenue per visitor lifted 4.2% (CI [+2.8%, +5.6%])." +3. **Magnitude in business terms.** "At our enrolled traffic, that is roughly [$Z] in incremental [period] revenue from this cohort. Full-launch impact depends on rollout assumptions." +4. **Guardrails.** One line per guardrail confirming it stayed within tolerance. +5. **Decision and timing.** "Filing the launch this week. Post-launch monitoring at days 7, 14, and 30." + +**Vocabulary to use.** "Real lift," "high confidence," "exceeds the threshold we committed to," "shipping." + +**Vocabulary to avoid.** Superlatives ("dramatic," "unprecedented," "transformative"). The number speaks; superlatives do not add to it. + +**What to omit.** Long discussion of why the test worked, deep statistical detail, exhaustive caveats. The headline result is clean; the writeup should be too. + +--- + +## Template 2: Clear loss + +**When to use.** Primary metric moved against expected direction with significance, OR a guardrail was violated. + +**Structure.** + +1. **Headline.** "We are not shipping [feature]. The test showed [a negative effect / a guardrail violation]." +2. **The number.** Point estimate and CI. Be precise about which metric showed the issue. +3. **Likely cause, if known.** Brief diagnosis: "Conversion dropped because users did not understand the new flow. Session recordings confirm confusion at step three." +4. **What we learned.** One or two sentences naming the lesson for the next hypothesis. +5. **Decision and follow-up.** "Killing the test. Filing the learning in the team retrospective. Considering [follow-up direction] as a next test." + +**Vocabulary to use.** "The test showed," "killing," "the change made things worse on [metric]," "we learned." + +**Vocabulary to avoid.** "Failed" applied to the team. "Setback." Defensive language. The test produced a clear answer; the team did its job. + +**What to omit.** Speculation about what would have happened with a different design. Excessive postmortem detail. The kill is the right decision; do not over-justify it. + +--- + +## Template 3: Inconclusive (the most common, hardest) + +**When to use.** Primary metric did not clearly move past MDE, CI is wide, OR guardrails are clean but signal is weak. The most frequent real outcome and the hardest to communicate without slipping into "we should ship anyway." + +**Structure.** + +1. **Headline.** "The test was inconclusive. We do not have enough signal to ship and we do not have enough signal to kill." +2. **The number.** Point estimate and the wide CI. Name the width: "Lift was +1.8%, but the CI is [-2.1%, +5.7%]; the data is consistent with a moderate win, no effect, or a moderate loss." +3. **What we know vs what we do not.** "We can rule out a large negative effect. We cannot distinguish a small positive effect from no effect. We cannot say whether shipping would help or hurt." +4. **The three resolution paths.** + + - Run bigger or longer: extend the test to narrow the CI. Cost: [time and traffic]. Benefit: a clearer answer. + - Make the treatment bolder: redesign with a larger expected effect, then re-test. Cost: design and engineering effort. Benefit: addresses the underlying mechanism rather than the measurement. + - Kill the idea: accept that the change does not produce a meaningfully detectable effect at our traffic. Cost: closing the hypothesis. Benefit: team time freed for higher-signal work. +5. **Recommendation.** Pick one path and explain why. +6. **Decision.** "Going with [path]. Re-evaluating in [timeframe]." + +**Vocabulary to use.** "Inconclusive," "the data does not distinguish," "we cannot confidently say," "the right call is to [chosen path]." + +**Vocabulary to avoid.** "Trending positive," "directional improvement," "looks promising." These are the phrases that get teams to ship inconclusive tests; they are wishful reading of noise. + +**What to omit.** Pleas to ship "since we are already here." Optimistic projections of what the lift "would be" with more sample. Alternative analyses that conveniently show significance. + +The hardest version of this template is the case where the team has invested in the hypothesis and the result is inconclusive. The temptation is to find a way to justify shipping. The discipline is to use the structure above and let the inconclusive result be inconclusive. + +--- + +## Template 4: Mixed result (positive primary, ambiguous guardrail) + +**When to use.** Primary metric moved past MDE with clean significance, but a guardrail metric showed concerning movement that did not clearly violate tolerance. + +**Structure.** + +1. **Headline.** "The primary metric moved as expected. A guardrail showed concerning movement; we are [shipping with monitoring / holding for further investigation]." +2. **Primary metric result.** Point estimate and CI. "Conversion lifted 5.1% (CI [+3.4%, +6.8%])." +3. **Guardrail concern.** Specific. "Refund rate point estimate moved +0.4%, with CI [-0.1%, +0.9%]. Pre-committed tolerance was no more than +0.5%. The CI does not clearly violate tolerance, but the upper bound is right at the threshold." +4. **The interpretation question.** "Pre-committed decision rule was 'do not ship if the guardrail CI excludes safe behavior.' The CI does not exclude safe behavior, but it does not exclude a violation either." +5. **Recommendation with reasoning.** Two valid paths: + + - Ship with extra monitoring: production behavior at +1, +2, +4 weeks specifically watching the guardrail. Roll back if it crosses tolerance in production. Acceptable when the primary lift is large and the guardrail risk is reversible. + - Hold and re-test: extend the test to narrow the guardrail CI. Acceptable when the primary lift is marginal or the guardrail is hard to monitor in production. +6. **Decision.** Pick the path. Document the guardrail-specific monitoring or the re-test plan. + +**Vocabulary to use.** "The guardrail CI does not clearly exclude tolerance," "shipping with intensified monitoring," "the pre-committed rule was." + +**Vocabulary to avoid.** "The guardrail did not move significantly" (when the CI does not exclude movement, do not pretend it did). "The primary lift outweighs the guardrail concern" (the guardrail was set as binding for a reason). + +**What to omit.** Reframing the guardrail as a "secondary metric" that does not need to bind. The guardrail was set during pre-commitment; it binds. + +--- + +## Template 5: Long-term holdout report (30 / 60 / 90 days post-launch) + +**When to use.** Reporting back on a feature that shipped with a holdout group, after the holdout period has elapsed. + +**Structure.** + +1. **Headline.** "[Feature] post-launch holdout report at [day count]. Long-term effect [confirms / diverges from / disconfirms] the test result." +2. **Test result reminder.** What the test showed at launch. "At launch, the test measured a +4% lift in [metric]." +3. **Long-term result.** What the holdout shows now. "At day 30, the launched cohort shows a +3.2% lift over the holdout (CI [+1.8%, +4.6%])." +4. **Comparison.** Direct: "The long-term effect is [in line with / smaller than / larger than] the test estimate. [If smaller: the difference is consistent with novelty fade / interference / dilution. If larger: the difference is consistent with network effects / learning effects.]" +5. **Decision implications.** "[Continue the launch as is / revisit the design / consider rollback]." +6. **Holdout disposition.** "[Releasing the holdout into the launched cohort / extending the holdout for another 30 days]." + +**Vocabulary to use.** "Long-term effect," "confirms / diverges from," "novelty fade," "we observe." + +**Vocabulary to avoid.** "Vindication" or "we were right." Long-term reports are about updating the prior, not declaring victory. + +**What to omit.** Excessive celebration of a confirmed lift. Excessive panic about a divergent lift. The report is information for the next decision; let the information drive it. + +--- + +## A note on the "we should report this differently" temptation + +When a result is inconclusive or mixed, there is always a way to slice the data, frame the writeup, or pick the chart that makes the result look more decisive. Resist. + +The cost of overstating an inconclusive result is shipping changes that do not work, eroding trust in the experimentation discipline, and accumulating production complexity for no gain. The cost of accurately reporting an inconclusive result is one round of disappointment from stakeholders who wanted a cleaner answer. The first cost compounds; the second does not. Use the right template for the actual result. diff --git a/skills/experimentation-analytics/references/statistical-method-reference.md b/skills/experimentation-analytics/references/statistical-method-reference.md new file mode 100644 index 0000000..bb11a4f --- /dev/null +++ b/skills/experimentation-analytics/references/statistical-method-reference.md @@ -0,0 +1,150 @@ +# Statistical method reference + +The technical reference for analysts. Covers the methods named in the [SKILL.md](../SKILL.md) with enough depth to verify a platform's implementation, recognize when a method is needed, and explain the choice to a skeptical reviewer. + +--- + +## CUPED (Controlled-experiment Using Pre-Experiment Data) + +**What it does.** Uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. Same point estimate as the unadjusted analysis; narrower CI. + +**The math, in one paragraph.** For each user, take their in-experiment metric value Y and their pre-experiment metric value X. Compute the regression coefficient theta that relates X to Y in the control group. Replace Y with Y minus theta times (X minus X-bar) for every user. Run the analysis on the adjusted Y. The variance of the adjusted Y is lower than the variance of Y by a factor proportional to the squared correlation between X and Y, which directly narrows the CI. + +**Variance reduction in practice.** Typical reduction is 30% to 50% for engagement metrics, 20% to 40% for revenue metrics, near zero for one-time conversions. Effective sample size roughly doubles when variance halves. + +**When to use.** + +- Metrics with high pre-experiment baseline variance (revenue per user, sessions per user, engagement minutes). +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +**When NOT to use.** + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline. +- Tests where pre-experiment behavior is uncorrelated with the metric being moved (a notification redesign rarely correlates with prior revenue, for example). + +**How to verify your platform implements it correctly.** Ask: "Do you compute theta on control only, or on the pooled population?" Pooled is technically wrong (induces bias). Control-only is correct. "What pre-experiment window do you use?" Common defaults are 14 to 28 days; the choice should be documented. + +**Common confusion.** "CUPED made our lift smaller, so we should report the unadjusted version." Wrong. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. + +--- + +## The delta method + +**What it does.** Provides correct variance estimation for ratio metrics. Naive variance estimation on ratios produces incorrectly narrow CIs and inflated false positive rates. + +**Why ratios are special.** Standard variance formulas assume sums of independent observations. Ratios are functions of two correlated sums (numerator and denominator). The variance of a ratio depends on the variance of the numerator, the variance of the denominator, AND the covariance between them. Naive estimators ignore the denominator variance and the covariance. + +**The math, in one paragraph.** For a ratio R equals N divided by D, the delta method approximates the variance of R using a first-order Taylor expansion around the means of N and D. The result expresses Var(R) as a function of Var(N), Var(D), Cov(N, D), and the means. The approximation is excellent when the sample size is moderate to large, which it is for almost any A/B test. + +**When to use.** + +- Conversion rate (conversions per user, when users can have multiple events). +- Click-through rate (clicks per impression). +- Revenue per user. +- Average order value. +- Any metric expressible as numerator divided by denominator where users can contribute multiple values. + +**When the simple formula is fine.** + +- Per-user binary conversion (one row per user, converted yes or no). The standard proportion variance formula is correct here. + +**Bootstrap as an alternative.** Resample users with replacement many times, compute the ratio each time, read off the empirical CI. Distribution-free; slower than delta method. Both produce similar CIs for typical A/B test sizes. + +**How to verify your platform.** Ask "what variance estimator do you use for ratio metrics?" Acceptable answers: delta method, linearization, bootstrap with user-level resampling. Unacceptable: standard t-test on proportions (wrong for non-binary ratios), bootstrap with row-level resampling (ignores within-user correlation). + +--- + +## Sequential testing methods + +**The peeking problem.** Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Daily peeking on a four-week test can push false positive rate above 30%. + +**Group sequential designs (GSD).** Plan a fixed set of interim analyses (often three) with adjusted significance thresholds at each. The thresholds are computed so the overall false positive rate stays at the nominal alpha. Well-understood; less flexible than always-valid methods. + +**Mixture sequential probability ratio test (mSPRT).** Produces "always-valid" p-values: the false positive rate stays at nominal alpha regardless of how many times you analyze. Common in modern platforms. The math: define a likelihood ratio between the alternative and null hypotheses, integrated over a prior on the effect size. The test rejects when the ratio exceeds 1/alpha. + +**Anytime-valid confidence intervals.** The CI version of always-valid p-values. Produced by taking the inverse of the always-valid test family. Wider than fixed-horizon CIs; the cost of peek-safety is some statistical efficiency, typically 10% to 30% wider. + +**Implementation across platforms.** + +- Statsig: always-valid by default for sequential metrics. +- Eppo: sequential CIs available as a configuration. +- GrowthBook: mSPRT supported. +- PostHog: depends on the experiment type and configuration. +- Optimizely: supports sequential via Stats Engine. +- Amplitude (Experiment): supports sequential testing. + +**How to read the panel.** "Always-valid p-value" or "anytime-valid CI" labels indicate sequential. "P-value" with no qualifier is fixed-horizon; treat early peeks as suggestive only. + +--- + +## Heterogeneous treatment effects (HTE) + +**What HTE is.** The treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. + +**Pre-registered vs post-hoc.** Pre-registered HTE analysis is one of the segment definitions you committed to at design time, with sample size budgeted for the segment. Post-hoc HTE discovery is finding a segment whose effect is large by mining the data; this is noise mining and the apparent lift will not replicate. + +**When to ship segment-only.** Three conditions must all hold: + +- The segment was pre-registered. +- The effect within the segment is large enough to justify shipping. +- The targeting infrastructure exists (or is cheap to build) and the maintenance cost is acceptable. + +If any condition fails, do not ship segment-only. Either ship to everyone (taking the average effect) or do not ship. + +**Methods for principled HTE detection.** + +- Causal forests: machine learning method for estimating heterogeneous treatment effects across many features. +- Conditional average treatment effects (CATE) with regression: model the effect as a function of covariates. +- Pre-registered segment analysis: simpler, more defensible, and sufficient for most PM contexts. + +For most A/B tests, pre-registered segment analysis is the right level of sophistication. Causal forests are useful for marketplace and personalization research where the effect is genuinely expected to vary across many dimensions. + +--- + +## Multiple testing corrections + +**The problem.** With twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty, two or three. + +**Bonferroni correction.** Divide alpha by the number of comparisons. With 20 comparisons, use alpha equals 0.0025 per comparison. Conservative; controls the family-wise error rate (probability of any false positive across the family). + +**Benjamini-Hochberg (BH) correction.** Less conservative; controls the false discovery rate (expected proportion of false positives among the things called significant). Better for exploratory analysis where some false positives are tolerable. + +**When to use which.** + +- Small number of pre-registered comparisons with high stakes: Bonferroni. +- Larger exploratory analysis where some false positives are acceptable: BH. +- Single pre-registered primary metric: no correction needed (one comparison). + +**How platforms apply corrections.** Some platforms apply corrections silently to displayed p-values; others report uncorrected numbers. Know which your platform does. The "5 of 12 metrics significant" headline means very different things depending on whether the p-values were corrected. + +--- + +## Cluster randomization + +**When SUTVA is violated.** SUTVA (Stable Unit Treatment Value Assumption) says one user's treatment does not affect another user's outcome. Violated in two-sided marketplaces, social products, supply-constrained features, and notification systems. + +**Cluster randomization as a fix.** Assign whole units (cities, markets, friend groups, sessions) to treatment or control rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. + +**Trade-off.** A cluster of 1000 users behaves more like one observation than 1000 independent observations. Effective sample size is roughly the number of clusters times the within-cluster correlation factor. Cluster randomization with 50 clusters has roughly the power of a user-randomized test with 200 to 500 users, even if the clusters contain millions of users total. + +**Designing for cluster randomization.** Choose the cluster boundary so that interference happens within clusters but not across them. Cities work for marketplace experiments. Friend groups work for social products. Sessions work for some notification studies. + +**Switchback experiments as an alternative.** Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control). Eliminates cross-user interference within each window. Requires careful temporal modeling because the windows are not independent (carryover effects, day-of-week effects). + +**Detection of SUTVA violation without redesign.** Compare a small cluster-randomized version to the user-randomized version. If the cluster-randomized lift is much larger than the user-randomized lift, the user-randomized test is leaking treatment into control via interference. The user-randomized test is undercounting the effect. + +--- + +## Variance reduction beyond CUPED + +**Stratified sampling.** Pre-stratify users by a known covariate (geography, segment, signup cohort) and randomize within strata. Reduces variance from imbalanced randomization at the cost of slightly more complex analysis. + +**Post-stratification.** Run normal randomization, then adjust the analysis for known covariates after the fact. Similar variance reduction to CUPED for the right covariates. + +**Regression adjustment.** Include covariates as controls in the regression that estimates the treatment effect. Equivalent to post-stratification for one covariate; generalizes to multiple. + +**Doubly robust estimation.** Combines regression adjustment with inverse-probability weighting. Robust to misspecification of either the outcome model or the propensity model. Overkill for most A/B tests; useful for observational analysis and some quasi-experiments. + +For most PM contexts, CUPED plus pre-registered segment analysis covers the variance reduction needs. The methods above are the next step up when the standard tools are insufficient. diff --git a/skills/experimentation-platform-orchestrator/SKILL.md b/skills/experimentation-platform-orchestrator/SKILL.md new file mode 100644 index 0000000..ea765c9 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/SKILL.md @@ -0,0 +1,286 @@ +--- +name: experimentation-platform-orchestrator +description: "A platform decision framework for experimentation. When to use Statsig vs PostHog vs GrowthBook vs Optimizely vs Amplitude vs Eppo vs Kameleoon. How to migrate between them. How to coordinate when multi-platform is genuinely warranted. The decisions that compound for years and the ones you can defer. Triggers on which experimentation platform, choose Statsig vs PostHog, evaluate experimentation tools, switch experimentation platform, migrate from Optimizely, consolidate experimentation tools, multi-platform experimentation, experimentation platform decision, ab test platform selection, feature flag platform vs experiment platform, warehouse-native experiments, vendor lock-in experimentation. Also triggers when a team is asking about cost, governance, or migration cost across experimentation tools, or when an evaluation is starting." +category: product +catalog_summary: "Pick the right experimentation platform, migrate when wrong, coordinate when multi-platform: a decision framework for Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon" +display_order: 7 +--- + +# Experimentation Platform Orchestrator + +A senior product and engineering leader's playbook for making the experimentation platform decision and recovering from making it wrong. + +Picking an experimentation platform is one of those decisions that looks easy at the start and compounds for years afterward. The wrong choice costs you in lost experiments (because the team avoids the painful workflow), in cost (because the wrong pricing model penalizes your usage shape), in vendor lock-in (because migration is real engineering work, not a config change), and in cultural drift (because the platform's defaults shape what your team thinks experimentation is). + +This skill is the discipline that makes the decision well the first time and the migration plan when you didn't. + +When to use this skill: choosing a platform from scratch, evaluating whether to switch, deciding whether to consolidate from multi-platform to single, or planning a migration that has already been approved. + +--- + +## What this skill is for + +This skill spans platform selection, multi-platform decisions, migration planning, and governance setup. It does not cover experiment design (use `experiment-design`), result interpretation (use `experimentation-analytics`), or feature flag operations (use `feature-flagging`). Pair this skill with the relevant integrations microsite when you need platform-specific MCP details. + +The audience is a PM, engineering leader, or data lead who is making the decision or recovering from a previous one. The voice is decisive. There is no "it depends, evaluate them all yourself." The decision space has real shape, and a senior advisor can map your situation to a defensible answer in an afternoon. + +--- + +## The 7 considerations for the platform decision + +Every platform evaluation walks the same seven questions. Answer them honestly first, then read the per-platform profiles, then consult the decision matrix. The order matters: data architecture and statistical rigor are foundational; the rest are layered on top. + +1. **Data architecture.** Where does experiment data live? Three patterns. Vendor-native (Statsig, Optimizely) keeps the data in the vendor's storage. Product-suite (PostHog, Amplitude) combines analytics and experiments behind one event pipeline. Warehouse-native (GrowthBook, Eppo) runs SQL on your existing data warehouse. The pattern dictates security review depth, residency, statistical depth, and cost shape. + +2. **Statistical rigor.** Does the platform implement CUPED, sequential testing, the delta method for ratio metrics, and multiple testing corrections? Cheap to verify in a sales call: ask "what variance estimator do you use for ratio metrics?" and "do you support always-valid p-values?" Modern platforms (Statsig, Eppo, parts of PostHog) have these. Older or homegrown platforms often do not. + +3. **MCP availability.** All seven platforms covered here have a first-party or hosted MCP except Eppo (as of May 2026). MCP availability matters more for agentic workflows where AI agents create and read experiments end to end. It matters less for traditional human-driven experimentation. Worth weighting if your team is AI-forward. + +4. **Feature flag integration.** Do experiments and feature flags live in the same platform? Statsig, Optimizely, GrowthBook, and PostHog all unify them. Eppo is experiment-only. Kameleoon is creative-personalization-focused. If you also need feature flag operations as production infrastructure, check `feature-flagging` for the operational discipline; the platform choice has to support both surfaces or you accept a second tool. + +5. **Analytics depth.** Can you see funnels, retention, and cohorts in the same surface as experiment results? PostHog and Amplitude are strongest here (analytics-first products). Statsig has a strong analytics overlay. Optimizely and GrowthBook are experiment-first, with analytics as a supplementary feature. + +6. **Governance and audit.** Who can change targeting in production, who can ship experiments, who can read sensitive metrics? Enterprise tiers (Optimizely, LaunchDarkly Federal) handle this with maturity. Open-source platforms (GrowthBook, PostHog self-hosted) require self-built governance. For regulated industries (healthcare, finance, public sector), this question is the deciding factor. + +7. **Cost shape.** Vendor-native scales with events. Warehouse-native scales with seats and warehouse compute. Product-suite scales with combined event volume across all features. Match the pricing shape to your actual usage shape. A high-traffic startup pays vendor-native pricing differently from a lower-traffic enterprise; pick the shape that is friendly to your trajectory, not just your current month. + +--- + +## Statsig + +Modern experimentation and feature management combined in one platform. CUPED and sequential testing built in. Strong PM-led ergonomics. Used by OpenAI, Notion, Brex, Figma. + +**Strengths.** Fast time to first experiment. Combined experiments and feature flags eliminate the second-tool tax. Statistical rigor is current with the literature. The MCP exposes full CRUD across experiments, gates, dynamic configs, and metrics. + +**Gotchas.** Pricing scales with events, which can become expensive at high scale. The platform has strong opinions about how experiments should run; teams that want a custom statistical workflow will fight the defaults. Self-host is not a first-class option. + +**Ideal customer.** Fast-growing SaaS that wants one platform for flags and experiments, values out-of-the-box statistical depth, and is comfortable with vendor-native data architecture. + +--- + +## PostHog + +Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics. Free tier available. + +**Strengths.** Full-funnel context. Experiments live next to the analytics that contextualize them. The MCP exposes 200+ tools (use scoping like `?features=` to keep the agent context tight). Self-host option is mature. Open-source license keeps you outside the vendor lock-in trap. + +**Gotchas.** Combined event volume across all features can make pricing surprising at scale. The breadth of features can make onboarding feel busy. Statistical depth in experiments is good but a step behind dedicated experiment platforms (Statsig, Eppo) on advanced features like CUPED defaults. + +**Ideal customer.** Product-led-growth SaaS that wants analytics, experiments, and feature flags in one surface, values open-source flexibility, and is comfortable with the breadth. + +--- + +## GrowthBook + +Open-source warehouse-native experimentation. Data stays in your warehouse (Snowflake, BigQuery, Redshift, Postgres). Self-host or cloud. + +**Strengths.** Data sovereignty. Cost control at scale because the warehouse is already paid for. First open-source production MCP for experimentation per their announcement. Mature statistical defaults including Bayesian and frequentist toggles. Bring-your-own metrics from the warehouse means experiment metrics match analytics metrics by definition. + +**Gotchas.** Setup overhead is higher than vendor-native. You own the warehouse compute cost (this is usually a feature, not a bug, but it shows up in different finance line items). Smaller community than Statsig or PostHog. UI polish lags vendor platforms by half a step. + +**Ideal customer.** Data-mature teams that already run a warehouse, regulated industries that need data residency, and teams that prefer open-source for the exit option. + +--- + +## Optimizely + +Long-time enterprise leader. Web Experimentation plus Feature Experimentation. Strong personalization and visual editing for non-technical users. + +**Strengths.** Enterprise governance is mature. Visual editing lets marketers ship experiments without engineer help. Strong customer success organization. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai. + +**Gotchas.** Expensive. Pricing targets marketing budgets, not engineering budgets. The product has decades of accumulated features; navigating it takes time. Statistical defaults are conservative but the platform is not the place to look for the latest variance reduction techniques. + +**Ideal customer.** Marketing-led organizations, enterprises with mature experimentation programs, and teams where non-technical experiment creation is a hard requirement. + +--- + +## Amplitude + +Behavioral analytics platform with experiments and feature flags as additional features. Hosted MCP available to all customers including the free tier. + +**Strengths.** If your team already lives in Amplitude for analytics, adding experiments is the path of least resistance. Cohort and behavioral segmentation are excellent. Free tier (10M events/month) is generous. + +**Gotchas.** Experiments are a secondary feature, not the headline. Statistical depth is moderate. If experimentation is your team's primary discipline, Amplitude is rarely the right choice; if experimentation is a supporting capability and analytics is the headline, it works. + +**Ideal customer.** Analytics-first teams that need experiments as a supplementary capability, not the centerpiece. Pre-PMF teams that want a free tier with analytics and experiments together. + +--- + +## Eppo + +Warehouse-native, statistically rigorous, used by Twitch, DraftKings, Perplexity. Strong statistical defaults including Bayesian and frequentist toggles, sequential testing, and CUPED. + +**Strengths.** Statistical correctness is the headline. The team is heavy on data scientists and statisticians, and it shows in the defaults. Warehouse-native architecture matches the pattern data-mature teams already run. Reporting is clear and oriented to decisions. + +**Gotchas.** No first-party MCP as of May 2026. REST API only. If your workflow depends on AI agents reading and writing experiments, Eppo is currently a gap. Track for a future MCP release. Pricing is enterprise; no meaningful free tier. + +**Ideal customer.** Data-team-led organizations where statistical correctness is paramount, the warehouse is already the system of record, and AI agent workflows are a future concern rather than a current requirement. + +--- + +## Kameleoon + +Specialty platform focused on the winning-experiment-to-production-code workflow. AI-driven personalization. Hosted MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. + +**Strengths.** Converts marketing-site experiment wins into permanent React components, which is a real workflow that other platforms force teams to handle manually. AI-driven personalization for content sites. The MCP is purpose-built for the win-to-code path. + +**Gotchas.** Narrower than the others. Not a replacement for Statsig or Optimizely on product experiments. Often shows up alongside another platform rather than as the primary. + +**Ideal customer.** Teams running experiments on marketing or content sites that need the winning variant to become permanent code. Almost always layered with a primary product-experiment platform. + +--- + +## Decision matrix: which platform for which context + +The matrix lives in [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) with worked examples. The summary: + +- Pure SaaS, fast-growing, want one platform for flags and experiments. Choose Statsig. Choose PostHog if you also want analytics. +- Open-source preference, want data sovereignty, warehouse-native. Choose GrowthBook or Eppo. +- Enterprise, marketing-led, deep personalization. Choose Optimizely. +- Already deeply on Amplitude for analytics. Stay on Amplitude unless statistical depth becomes the bottleneck. +- Data-team-led, statistical correctness paramount, MCP not yet required. Choose Eppo. +- Need to convert marketing-site wins into production code. Add Kameleoon alongside your primary platform. +- Regulated industry (HIPAA, FedRAMP), self-hosting required. Choose GrowthBook self-hosted. PostHog self-hosted is also viable. +- Pre-PMF startup, low traffic, need a free tier. Use PostHog free tier or Statsig free tier; defer the real decision until traffic justifies the cost calculation. +- 100M+ events per month, cost control is the headline constraint. Choose GrowthBook or Eppo. Warehouse-native pricing scales better at this volume. +- AI-forward team, MCP-first workflow. Choose Statsig, PostHog, or Optimizely. Defer Eppo until its MCP ships. + +--- + +## Multi-platform: when warranted, when a mess + +Multi-platform is warranted when the surfaces are genuinely different and the platforms overlap zero. Marketing site personalization on Kameleoon plus product experiments on Statsig is a clean split: different surface, different audience, different metric set, no overlap. The cost of the second tool is justified because the workflows do not collide. + +Multi-platform is a mess when the surfaces overlap. Running both Statsig and Optimizely for product experiments creates duplicate cost, split data, and a "which one is the source of truth" problem that surfaces in the worst possible moment, which is when a leadership disagreement needs an answer. + +The 80/20 rule. Eighty percent of teams should pick one platform and consolidate. The 20% with genuine multi-surface needs (marketing site plus product app plus content site) can justify multi-platform with clear ownership boundaries. + +When multi-platform is genuine, three coordination patterns are non-negotiable. An ownership matrix names which platform owns which surface. Shared metric definitions ensure that "activation rate" computes the same way in both platforms (this is hard, and it is the reason most multi-platform setups quietly drift). Reconcilable dashboards let you see the same metric across both platforms with the same definitions. Detail in [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md). + +--- + +## Migration patterns + +Migration is the unglamorous engineering work that makes the platform decision recoverable. Five common paths. + +**Statsig to PostHog.** Typical when a company outgrows pure experimentation and wants analytics plus experiments combined. Effort: 3 to 5 engineer-weeks. Parallel-run for 4 to 8 weeks, validate experiments produce the same results on both, cut over once trust is established. + +**Optimizely to Statsig.** Typical under budget pressure or modernization. Effort: 4 to 8 engineer-weeks. Audit for feature parity first (Optimizely has personalization features Statsig does not). Migrate experiments before flags. Retire Optimizely only after all in-flight experiments complete on the old platform. + +**PostHog to Eppo.** Typical when statistical rigor becomes the binding constraint and the warehouse is already the system of record. Effort: 6 to 10 engineer-weeks. Often results in PostHog staying for analytics and Eppo running experiments. Plan for the dual-platform end state, not a clean replacement. + +**GrowthBook to Eppo.** Typical when commercial support and deeper statistical features become worth the price. Effort: 2 to 4 engineer-weeks because both are warehouse-native; the data already lives in your stack. + +**Any to Statsig.** Typical consolidation move from multi-platform mess. Effort scales with the number of platforms and in-flight experiments; a clean consolidation can run 6 to 12 engineer-weeks. + +The migration discipline is in [`references/migration-playbook.md`](references/migration-playbook.md). Three rules apply to every migration: do not parallel-run forever, do not big-bang switch, and do not retire the old platform before all in-flight experiments complete. + +--- + +## The cost reality + +Plain talk. Vendor-native (Statsig, Optimizely) bills on events, typically $0.10 to $0.50 per million events. Easy to predict at small scale, painful at very high scale. Warehouse-native (Eppo, GrowthBook paid) bills on seats and warehouse compute; $5K to $50K per year is the typical range for paid tiers, with warehouse compute showing up on a different finance line. Product-suite (PostHog, Amplitude) bills on combined event volume across all features; often the most cost-effective when used heavily and the most expensive when only experiments are needed. + +Free tiers. PostHog gives 1M events per month free. Statsig gives 1M events free. Amplitude gives 10M events per month free with basic features. GrowthBook is free open-source. Optimizely and Eppo do not have meaningful free tiers. + +The trap. Optimizing for sticker price ignores total cost. Total cost includes engineer time, statistical correctness (a wrong-result experiment can cost more than a year of platform fees), governance overhead, and migration risk. Sticker price matters for finance; total cost matters for product velocity. Detail and finance conversation patterns in [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md). + +--- + +## Governance and team fit + +Permission tiers, approval workflows, audit trails, and environment promotion are the four pillars of governance. Who creates experiments, who modifies targeting in production, who reads sensitive metrics, who approves a rollout. Enterprise tiers handle these out of the box. Open-source self-hosted requires you to build them, which is fine if you have the engineering capacity and a dealbreaker if you do not. + +Team fit shapes the decision more than most evaluations admit. PostHog and GrowthBook suit engineer-led and PLG teams. Optimizely suits marketing-led teams. Eppo and GrowthBook suit data-team-led teams. Statsig suits PM-led teams. The platform's defaults will pull your team's experimentation culture in the direction of its primary user; pick the alignment that matches who you actually want running experiments. + +Onboarding cost. How long until a new PM can ship their first experiment? Statsig and PostHog: hours to days. Optimizely: days to weeks. Eppo and GrowthBook: depends on whether the warehouse and metrics are already wired in (days if yes, weeks if no). Detail in [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md). + +--- + +## The MCP capability layer + +For AI-forward teams, the MCP capability layer is becoming the deciding factor. The current state as of May 2026: + +- All seven covered platforms have first-party or hosted MCPs, with the exception of Eppo. Eppo offers REST API only. +- Capability differs by an order of magnitude. PostHog exposes 200+ tools; Kameleoon exposes 7. More is not better; the right size depends on your workflow. +- For agentic workflows where AI agents run experiments end to end, prefer platforms with full CRUD via MCP: Statsig, PostHog, GrowthBook, Optimizely. +- For human-driven workflows where MCP supplements human action, any of the seven works (Eppo via the REST path). + +MCP availability is evolving fast. Check the current state of any platform before committing. Eppo is worth tracking for a future MCP release that would close its current gap. Side-by-side capability matrix in [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md). + +--- + +## When to defer the decision + +Sometimes the right answer is "not now." Four cases. + +Pre-PMF. Experimentation infrastructure is premature. Use a free tier (PostHog or Statsig) to remove blockers, defer the real decision until you have enough traffic to make any platform meaningful. + +Single-experiment validation. Do not pick a platform for one experiment. Use whatever is free and easy. The platform decision is for the team that runs experiments as a discipline, not the team running its first. + +No experimentation culture yet. Tooling does not fix culture. If your team is not running experiments, picking a fancy platform will not change that. Build the culture first; the platform decision becomes obvious once experiments are flowing. + +Pending acquisition or major pivot. Defer until the dust settles. The acquirer will likely have a preferred platform anyway. + +--- + +## Common mistakes + +Twelve patterns recur across platform decisions. The short version: + +- Picked the cheapest. Total cost dominates sticker price. +- Picked the most-featured. Features you do not use are technical debt. +- Tried multi-platform first. Almost always becomes a consolidation project later. +- Outgrew the platform but stayed for migration cost. The platform tax compounds; migration cost is fixed. +- Picked based on a demo. Demos optimize for the show; real usage reveals real tradeoffs. +- Did not check governance. Discovered after rollout that anyone can modify production targeting. +- Picked a platform that does not fit team type. PM-led team on a marketing-led platform is constant friction. +- Underestimated the warehouse setup. Warehouse-native platforms expect the warehouse to already be there. +- Skipped statistical depth review. Then a critical experiment surfaced a wrong-result decision. +- Ignored MCP trajectory. Picked a platform without MCP for an AI-forward team. +- Locked the brief on the demo, not the trial. Brief assumptions did not survive contact with real usage. +- Renewed without re-evaluating. The market changed; the brief did not. + +Detail in [`references/common-mistakes.md`](references/common-mistakes.md) with symptoms, root causes, fixes, and prevention. + +--- + +## The framework: 11 considerations for sustainable platform choice + +When choosing or evaluating an experimentation platform, walk these 11 considerations. Answer each one before reaching a recommendation. Skipping any of them is how teams end up in a migration project a year later. + +1. **Data architecture.** Vendor-native, product-suite, or warehouse-native. The pattern is downstream of every other decision. +2. **Statistical rigor.** CUPED, sequential testing, delta method for ratio metrics, multiple testing corrections. Verify at the sales-call level; do not assume. +3. **MCP availability.** Current capability and trajectory. Weight higher if your team is AI-forward. +4. **Feature flag integration.** Same platform or separate. Decide once and live with the implications. +5. **Analytics depth.** Funnels, retention, cohorts in the same surface. Decides whether you need a second tool for the analytics layer. +6. **Governance.** Permissions, audit, approval workflows, environment promotion. Non-negotiable for regulated industries. +7. **Cost shape.** Events vs seats vs warehouse compute. Match the shape to your usage trajectory. +8. **Team fit.** PM-led, engineer-led, data-led, marketing-led. The platform's defaults will pull your culture in the direction of its primary user. +9. **Onboarding cost.** Time to first experiment for a new team member. Faster is better; varies wildly across platforms. +10. **Migration cost.** What is the exit plan if you choose wrong. Higher migration cost means higher confidence required at decision time. +11. **Multi-platform fit.** Does this layer cleanly with platforms you already have, or does it create overlap. + +The output of this framework is one of three answers. A primary recommendation with reasoning. A short list of two if the situation is genuinely ambiguous. A "defer" if a precondition is not met (no traffic, no culture, pending pivot). + +--- + +## Reference files + +- [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) - Context-to-platform matrix with worked examples for the most common decision contexts. +- [`references/migration-playbook.md`](references/migration-playbook.md) - Step-by-step migration patterns for the five common migrations including effort estimates and validation approaches. +- [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md) - Side-by-side MCP capability matrix across the seven platforms. +- [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md) - Ownership boundaries, shared metric definitions, and reconciliation dashboards for genuine multi-platform setups. +- [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md) - Pricing shapes, real-world cost ranges at different traffic tiers, and finance conversation patterns. +- [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md) - Permission tiers, audit trail requirements, environment promotion rules, and team fit assessment. +- [`references/common-mistakes.md`](references/common-mistakes.md) - Twelve failure patterns with symptom, root cause, fix, and prevention for each. + +--- + +## Closing: when in doubt, pick boring + +When the analysis is genuinely ambiguous, pick the boring choice. Boring means mature, well-documented, large user base, and a recoverable migration if you turn out to be wrong. Statsig is boring for SaaS. PostHog is boring for product-led growth. Optimizely is boring for enterprise. GrowthBook is boring for warehouse-native. + +Boring is not the optimum, but it is almost never wrong. The optimum can come later, when the situation has clarified and the team has the experience to know what it actually needs. The cost of picking boring is a small efficiency tax. The cost of picking exotic and being wrong is a migration project that interrupts a year of product work. + +If the team disagrees on which boring choice is the right one, that is a data signal: the situation is not yet clear enough for any answer to be obviously correct. Run a 30-day trial on the top two, evaluate against the 11-consideration framework with real usage data, and pick. Do not skip the trial; demos lie about real usage in ways that only the trial reveals. diff --git a/skills/experimentation-platform-orchestrator/references/common-mistakes.md b/skills/experimentation-platform-orchestrator/references/common-mistakes.md new file mode 100644 index 0000000..bbf1200 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/common-mistakes.md @@ -0,0 +1,155 @@ +# Common mistakes + +Twelve failure patterns that recur in platform decisions. For each: name, symptom, root cause, fix, and prevention. + +--- + +## 1. Picked the cheapest + +**Symptom.** Six months in, the team is paying more in engineer time than they saved on the platform fee. Velocity is below the pre-decision projection. + +**Root cause.** Sticker-price optimization without a total-cost frame. Engineer time, statistical correctness, and migration risk were not priced in. + +**Fix.** Run a total-cost-of-ownership review. If TCO is materially worse, plan a migration to a better-fit platform. Counter-intuitively, paying more in platform fees can save more in engineer time. + +**Prevention.** Use the total cost frame at decision time. The cheapest sticker price is rarely the cheapest TCO. See `cost-and-pricing-models.md` for the framing. + +--- + +## 2. Picked the most-featured + +**Symptom.** The team uses 20% of the platform's features. The other 80% are noise that complicates onboarding and inflates the bill. + +**Root cause.** Demo-driven feature comparison. The platform's depth was impressive in the demo and translated into a "more features means more value" assumption. + +**Fix.** Audit feature usage. If 80% of the platform is unused, evaluate whether a simpler platform serves the team better. Migrating to a smaller-surface platform reduces operational complexity. + +**Prevention.** Build a "features needed" list before evaluating platforms. Use the list to filter out features you do not need; do not let demo-time enthusiasm expand it. + +--- + +## 3. Tried multi-platform first + +**Symptom.** Two platforms running, both partially used, neither fully embraced. Stakeholders cannot tell which one is the source of truth. + +**Root cause.** "Best of both worlds" thinking. The team picked two platforms hoping to combine their strengths, but the integration cost exceeded the combined benefit. + +**Fix.** Plan a consolidation. See `multi-platform-orchestration.md` for when consolidation is the right answer (almost always for teams in this state). + +**Prevention.** Default to single-platform unless the surfaces genuinely do not overlap. Multi-platform is a 20% case, not the default. + +--- + +## 4. Outgrew the platform but stayed for migration cost + +**Symptom.** The team is hitting limits the platform cannot serve (statistical depth, governance, scale). They know it. They have not migrated because the migration project feels expensive. + +**Root cause.** Migration cost is overweighted relative to the ongoing platform tax. The platform tax compounds; migration cost is fixed. + +**Fix.** Run the migration. Set a 90-day window. Use the migration playbook. + +**Prevention.** Do an annual platform fit review. If the platform is not the right fit, the answer is to migrate, not to defer. Deferral makes the migration harder, not easier. + +--- + +## 5. Picked based on a demo + +**Symptom.** Real usage reveals workflows that did not show up in the demo. Team velocity is below expectations. Frustration is mounting. + +**Root cause.** Demos optimize for the show. Real usage reveals real tradeoffs. The decision was made before the team had data on actual workflows. + +**Fix.** Run a 30-day trial on the next-best alternative. Compare real-usage friction. If the alternative is materially better, plan the migration. + +**Prevention.** Always run a real trial, never just a demo. The trial should ship at least one experiment end to end on each platform under evaluation. + +--- + +## 6. Did not check governance + +**Symptom.** Discovered after rollout that anyone with platform access can modify production targeting. A bad change shipped because no review was required. + +**Root cause.** Governance was not part of the evaluation. The team assumed defaults would be acceptable; they were not. + +**Fix.** Build the governance layer immediately. Permission tiers, approval workflows, audit trails, environment promotion. See `governance-and-team-setup.md`. + +**Prevention.** Make governance a non-negotiable evaluation criterion. For any platform under consideration, document the permission model, audit capabilities, and approval workflow before signing. + +--- + +## 7. Picked a platform that does not fit team type + +**Symptom.** Constant friction in experiment authoring. The team that should be shipping experiments is instead filing tickets. Experiment volume is below target. + +**Root cause.** Team-fit mismatch. A PM-led team on a marketing-led platform, or vice versa. The platform's defaults pull the workflow in a direction the team cannot follow. + +**Fix.** Either change the team's workflow to match the platform, or migrate to a platform that matches the team. The migration is usually the right answer because team workflow is hard to change quickly. + +**Prevention.** Assess team fit explicitly. See the team-fit framework in `governance-and-team-setup.md`. + +--- + +## 8. Underestimated the warehouse setup + +**Symptom.** Picked a warehouse-native platform. Three months in, still not running experiments because the warehouse layer is not ready. + +**Root cause.** Warehouse-native platforms expect the warehouse to already be the system of record with metrics defined and refresh cadences in place. The team did not have that foundation. + +**Fix.** Either complete the warehouse setup (real engineering project) or migrate to a vendor-native platform that does not require it. + +**Prevention.** Verify warehouse readiness before committing to warehouse-native. The platform decision should follow the warehouse decision, not lead it. + +--- + +## 9. Skipped statistical depth review + +**Symptom.** A critical experiment surfaced a wrong-result decision. The platform's defaults did not catch the issue (peeking, ratio metric, multiple testing, network effects). + +**Root cause.** Statistical depth was not part of the evaluation. The team assumed all platforms compute the same numbers correctly; they do not. + +**Fix.** Add the missing rigor. Either configure the current platform's advanced features (sequential testing, CUPED, delta method) or migrate to a platform with stronger defaults. Pair with the `experimentation-analytics` skill to interpret results going forward. + +**Prevention.** Verify statistical depth at evaluation time. Ask specifically about CUPED, sequential testing, delta method for ratio metrics, and multiple testing corrections. Do not accept "we have statistical features" without specifics. + +--- + +## 10. Ignored MCP trajectory + +**Symptom.** AI-forward team picked a platform without MCP. Six months later, the team is hitting the limit of agent-driven workflows and the platform is the bottleneck. + +**Root cause.** MCP trajectory was not weighted in the decision. The platform's strengths in other areas were assumed to make up for the gap. + +**Fix.** Either wait for the platform to ship an MCP (uncertain timeline) or migrate to a platform with mature MCP. Eppo specifically is worth tracking for a future MCP release. + +**Prevention.** For AI-forward teams, MCP availability is a primary criterion, not a tiebreaker. See `mcp-capability-comparison.md` for current state. + +--- + +## 11. Locked the brief on the demo, not the trial + +**Symptom.** Brief-time assumptions did not survive contact with real usage. The platform is technically capable but operationally uncomfortable in ways the demo did not reveal. + +**Root cause.** The decision was made on the strength of the demo, with the trial running as a formality afterward. Real-usage signals were not weighted. + +**Fix.** Do another trial of the next-best alternative. If the alternative removes the operational discomfort, migrate. + +**Prevention.** Run the trial first. Use trial outcomes to update the brief, not the other way around. Demos are useful for screening; trials are required for committing. + +--- + +## 12. Renewed without re-evaluating + +**Symptom.** Renewal cycle came up. The team renewed because the platform was working "well enough." Six months later, an alternative shipped a feature that would have changed the decision. + +**Root cause.** Renewal treated as a status-quo extension. The platform market changes faster than annual contracts, and a yearly renewal without re-evaluation drifts away from the optimal choice. + +**Fix.** Run the platform decision framework at every renewal. If the answer is the same platform, renew with confidence. If the answer is different, plan a migration. + +**Prevention.** Build the annual platform review into the team's calendar. Tie it to the renewal date so the review informs the renewal decision rather than competing with it. + +--- + +## The pattern across all twelve + +Most platform mistakes share one root cause: under-investment in the decision itself. A two-week evaluation that catches all twelve patterns is cheaper than a year on the wrong platform. + +The fix at the meta level. Treat the platform decision as a real engineering project. Allocate time. Run trials. Audit governance. Verify statistical depth. Check MCP trajectory. Document the decision and the reasoning. Review annually. diff --git a/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md b/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md new file mode 100644 index 0000000..146f835 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md @@ -0,0 +1,125 @@ +# Cost and pricing models + +Pricing shapes per platform, real-world cost ranges at different traffic tiers, the total cost frame, and finance conversation patterns. + +Pricing on experimentation platforms is rarely transparent on the public site for paid tiers. The numbers below are typical ranges from real customer conversations as of May 2026. Verify with each vendor before committing. + +--- + +## The three pricing shapes + +**Vendor-native (event-based).** Statsig, Optimizely. Billing scales with the number of events sent to the platform. Easy to predict at small scale: events per month times rate per million. Painful at very high scale because the rate per million does not always decrease quickly. + +**Warehouse-native (seat plus warehouse compute).** GrowthBook (paid), Eppo. Billing scales with the number of seats and the warehouse compute the platform consumes. Warehouse compute is your existing line item, so the marginal cost of more experiments is small once the platform is paid for. Less elastic on team size, more elastic on experiment volume. + +**Product-suite (combined event volume).** PostHog, Amplitude. Billing scales with combined event volume across all features (analytics, experiments, replays, error tracking, surveys). Often the most cost-effective when used heavily; can be the most expensive when only one feature is needed. + +--- + +## Free tiers + +Free tiers exist for the early-stage and pre-PMF cases. The numbers below are current as of May 2026. + +| Platform | Free tier shape | +|---|---| +| PostHog | 1M events per month free across all features | +| Statsig | 1M events per month free; full feature access | +| Amplitude | 10M events per month free with basic features (some advanced features paid) | +| GrowthBook | Free open-source self-hosted; cloud has a free tier with 3 users and 5 active experiments | +| Optimizely | No meaningful free tier | +| Eppo | No meaningful free tier | +| Kameleoon | No meaningful free tier; free trial only | + +For pre-PMF and early-stage teams, the free-tier choice is between PostHog and Statsig. Both work. Pick the one whose product surface matches your needs (PostHog if you also want analytics; Statsig if you want experiments and flags primarily). The decision is reversible at low cost while you are still on the free tier. + +--- + +## Real-world cost ranges + +Approximate ranges for paid tiers. Bands are wide because pricing varies by contract size, sales discount, and feature mix. + +### Vendor-native (events per month) + +| Volume | Statsig (typical) | Optimizely (typical) | +|---|---|---| +| 1M to 10M | $0 (free) to $1K/month | Custom contract; rarely under $30K/year | +| 10M to 100M | $1K to $8K/month | $30K to $100K/year | +| 100M to 1B | $8K to $40K/month | $100K to $400K/year | +| 1B+ | $40K+/month with custom negotiation | $400K+/year with custom negotiation | + +Optimizely consistently sits at a higher absolute price point than Statsig for the same volume. The premium pays for the marketing-led ergonomics, the visual editor, and the personalization features. Whether the premium is justified is a per-team judgment. + +### Warehouse-native (seats and compute) + +| Team size | Eppo (typical) | GrowthBook paid (typical) | +|---|---|---| +| 5 to 10 seats | $20K to $40K/year | $5K to $15K/year | +| 10 to 30 seats | $40K to $120K/year | $15K to $50K/year | +| 30+ seats | Custom contract | Custom contract | + +Plus warehouse compute. For a Snowflake-based setup running 100 to 300 active experiments per year, expect $2K to $20K/year of additional warehouse compute attributable to experimentation queries. The exact number depends on metric complexity and refresh cadence. + +### Product-suite (combined events) + +| Volume | PostHog (typical) | Amplitude (typical) | +|---|---|---| +| 1M to 10M | $0 (free) to $500/month | $0 (free) to $2K/month | +| 10M to 100M | $500 to $5K/month | $2K to $20K/month | +| 100M to 1B | $5K to $30K/month | $20K to $100K/month | +| 1B+ | Custom negotiation | Custom negotiation | + +PostHog is consistently more cost-effective for combined product analytics plus experiments. Amplitude charges a premium for the depth of its behavioral analytics; if experiments are the primary use, PostHog is hard to justify against. + +--- + +## The total cost frame + +Sticker price is one input to the cost decision. Total cost is the right frame. + +**Engineer time.** Wiring, maintenance, dashboard upkeep, debugging integration issues. Ranges from 5% to 30% of an engineer's time depending on platform and team size. Vendor-native is usually lower; warehouse-native is usually higher (more setup); multi-platform is usually highest. + +**Statistical correctness.** A single wrong-result experiment can cost more than a year of platform fees. If a platform's defaults produce confidently-wrong recommendations, the cost is the experiment that shipped wrong, not the platform fee. Worth a real review at platform decision time. + +**Governance overhead.** Self-hosted open-source platforms require self-built governance (audit, permissions, approval workflows). For regulated industries, this is hours of compliance review per quarter. Enterprise tiers absorb this overhead in their pricing. + +**Migration risk.** What is the cost if you choose wrong and need to migrate? See `migration-playbook.md` for engineer-week ranges. Multiply by the probability you will need to migrate, and that is the migration risk component of total cost. + +**Cultural drift.** The platform's defaults shape what the team thinks experimentation is. PM-led platforms produce PM-led cultures. Marketing-led platforms produce marketing-led cultures. The drift is hard to price but real. + +--- + +## Finance conversation patterns + +Three patterns that work when justifying a platform decision to finance. + +### Pattern 1: cost per experiment + +Compute the all-in cost per experiment shipped: platform fees plus engineer time amortized across experiments per year. This converts platform cost into a unit that finance understands. A team running 50 experiments per year on a $40K platform fee is paying $800 per experiment in platform alone, plus engineer time. A team running 200 experiments on the same fee is paying $200 per experiment. + +The frame: more experiments per year reduces unit cost. Justify investment by showing a path to higher experiment throughput. + +### Pattern 2: avoided wrong-result experiments + +Estimate the cost of a wrong-result decision. For revenue experiments, this is often $50K to $500K (the value of the experiment shipped wrong). Multiply by the rate of wrong-result decisions before and after a platform change. + +The frame: a more rigorous platform avoids wrong-result decisions. A few avoided wrong-results per year easily justify the platform premium. + +### Pattern 3: total cost of ownership across alternatives + +Build a 3-year TCO model for the top two or three candidates. Include platform fees, engineer time, migration costs, and governance overhead. Show the comparison. + +The frame: the cheapest sticker price is rarely the cheapest TCO. The platform that minimizes engineer time often wins on TCO even if it costs more per month. + +Use whichever pattern matches finance's mental model. Pattern 1 works for ROI-focused finance leaders. Pattern 2 works for risk-focused leaders. Pattern 3 works for procurement-focused leaders. + +--- + +## Negotiation tips + +Three patterns work in vendor negotiations. + +1. **Multi-year commits unlock 15 to 30% discounts.** If the team is confident in the platform, lock in the discount. +2. **Event volume tiers are negotiable.** The published pricing is the starting position. Custom contracts at scale always run below it. +3. **Bundle features for unit-cost reduction.** Combining experiments and feature flags in one contract often costs less than the same features separately. + +Do not negotiate from desperation. If the team is in a "we have to migrate this quarter" position, the vendor knows and the discount evaporates. Negotiate from a position of optionality: keep the trial of the alternative platform live until the contract closes. diff --git a/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md b/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md new file mode 100644 index 0000000..f7db5ca --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md @@ -0,0 +1,133 @@ +# Governance and team setup + +Permission tiers, approval workflows, audit trail requirements, environment promotion, team fit assessment, and onboarding playbooks. + +Governance is the unglamorous discipline that prevents the worst outcomes. A team that ships fast without governance will eventually have an "anyone can modify production targeting" incident. This reference is the structure that prevents it. + +--- + +## The four governance pillars + +### Permission tiers + +A typical permission model has four tiers. + +1. **Read.** See experiments, flags, and results. Default for analysts, partners, and read-only stakeholders. +2. **Author.** Create and modify experiments and flags in non-production environments. Default for PMs and engineers shipping experiments. +3. **Production.** Modify production targeting. Reserved for senior engineers, leads, or designated experiment owners. +4. **Admin.** Manage users, billing, integrations. Reserved for engineering leadership and platform owners. + +Map roles to tiers. Document who has which tier. Review quarterly. Remove access proactively when someone changes roles. + +For platforms that do not natively support fine-grained permissions (some open-source self-hosted setups), build the permission model in the deployment process. For example, only certain CI/CD pipelines can push to production targeting. + +### Approval workflows + +Production-impacting changes go through review. The minimum approval workflow has three steps. + +1. The author proposes the change (new experiment, modified targeting, rollout to higher percentage). +2. A second person reviews. The reviewer is not the author. +3. The change is logged with actor, timestamp, before-and-after, and reason. + +Lighter approval is acceptable for low-risk experiments (5% rollout to internal users). Stricter approval applies to high-risk experiments (revenue, billing, security-adjacent). + +Some platforms (Optimizely Enterprise, Statsig Enterprise) build the approval workflow into the platform. Others require self-built workflows in your deployment process or change management tool. + +### Audit trails + +Every change logged. The log includes actor, timestamp, before state, after state, and reason. The log is immutable and queryable. + +Audit trails matter for two reasons. The first is compliance: regulated industries require them. The second is post-incident analysis: when a wrong-result decision ships, the audit trail tells you exactly when and why the experiment was modified. + +For platforms that do not natively log every change (smaller open-source setups), build the audit at the deployment-pipeline level. Every push to the experimentation platform's API runs through a logging proxy. + +### Environment promotion + +Experiments and flags promoted through environments: dev, staging, production. The promotion is not automatic. Each promotion is a deliberate decision. + +The minimum environment model is dev plus production. The fuller model is dev, staging, production. Larger organizations add a pre-production environment that mirrors production traffic for risk-free smoke testing. + +Promotion rules. Experiments are tested in dev first. The experiment definition (targeting, variants, metrics) is identical across environments. Only the user population differs. Promotion to production requires approval. + +--- + +## Team fit assessment + +The platform's defaults shape the team's experimentation culture. Pick the alignment that matches who you actually want running experiments. + +**PM-led culture.** PMs author and own experiments. Engineers wire metrics and SDK changes. The platform should have a low-overhead experiment authoring surface, clear analytics, and good metric documentation. + +Best fit: Statsig, PostHog. Both have PM-friendly authoring surfaces. + +**Engineer-led culture.** Engineers author and own experiments. PMs review and prioritize. The platform should have a code-first authoring surface and good SDK ergonomics. + +Best fit: PostHog, GrowthBook. Both have strong code-first paths. + +**Data-team-led culture.** Analysts and data scientists author experiments. The platform should have warehouse-native architecture, deep statistical defaults, and SQL-first metric definitions. + +Best fit: Eppo, GrowthBook. Both are warehouse-native. + +**Marketing-led culture.** Marketing teams author experiments without engineer involvement. The platform should have a visual editor and non-technical experiment authoring. + +Best fit: Optimizely, Kameleoon. Both have mature visual editors. + +The wrong fit is constant friction. A PM-led team on a marketing-led platform will struggle with the visual-editor-first authoring surface. A marketing-led team on an engineer-led platform will not be able to ship without filing engineering tickets. + +--- + +## Onboarding cost + +Time to first experiment for a new team member is a real metric. Track it after platform decisions. + +**Statsig and PostHog.** Hours to days. The authoring surfaces are PM-friendly; new team members can ship a low-risk experiment in a single afternoon with documentation. + +**Optimizely.** Days to weeks. The visual editor is approachable for non-engineers, but the platform's depth means navigation takes time. New marketing team members can ship faster than new engineering team members. + +**Eppo and GrowthBook.** Days if the warehouse and metrics are already wired in. Weeks if not. The setup overhead is in the warehouse layer, not the platform itself. + +**Amplitude.** Hours if the team is already using Amplitude for analytics. The experiments surface is a small extension of the analytics surface. New team members already familiar with Amplitude pick it up quickly. + +**Kameleoon.** Hours for the visual editor. Days for the win-to-code workflow. The specialty workflow has its own learning curve. + +--- + +## Onboarding playbook + +A repeatable onboarding playbook for a new PM or engineer joining an experimentation discipline. + +### Day 1: orientation + +- Read the platform documentation overview (1 hour). +- Walk through one completed experiment in the platform with the team owner (30 minutes). +- Review the team's metric definitions and ownership matrix (30 minutes). +- Get permissions provisioned at the Author tier (varies; aim for same day). + +### Day 2 to 5: shadow + +- Sit in on one experiment review meeting. +- Read the last 3 to 5 experiment writeups. +- Pair with a senior team member on a low-risk experiment. + +### Week 2: ship + +- Author and ship a low-risk internal experiment (5% rollout to internal users). +- Write up results. +- Get feedback from a senior team member. + +### Week 3 to 4: own + +- Take ownership of a backlogged experiment. +- Ship it end to end. +- Present results to stakeholders. + +After week 4, the new team member is fully onboarded. Track the time to first experiment as a metric. Investigate when it exceeds two weeks; that is a signal of either platform friction or onboarding-process drift. + +--- + +## Common governance failures + +Three patterns recur. + +1. **Permission creep.** Everyone gets Production tier "for convenience." Six months later, no one knows who can modify production targeting. The fix is quarterly access reviews and a strict default to Read or Author tier. +2. **Approval theater.** Changes go through an approval workflow but reviewers do not actually review. The fix is to require a substantive comment on every approval, not just a click. +3. **Audit log drift.** The audit log exists but no one reads it. The fix is to surface audit log highlights (high-risk changes, unusual targeting modifications) in a weekly digest. diff --git a/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md b/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md new file mode 100644 index 0000000..2c25bfc --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md @@ -0,0 +1,97 @@ +# MCP capability comparison + +Side-by-side capability matrix across the seven covered platforms. Current as of May 2026. MCP capability evolves quickly; verify before committing. + +The matrix is organized by capability category. Read it as "if my workflow needs X, which platforms support it." If your workflow needs every capability across the board, the answer is Statsig, PostHog, or Optimizely (the most mature MCPs). If your workflow needs a specific subset, smaller MCPs may be a better fit. + +--- + +## Capability matrix + +| Capability | Statsig | PostHog | GrowthBook | Optimizely | Amplitude | Eppo | Kameleoon | +|---|---|---|---|---|---|---|---| +| Read feature flags | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Create or update feature flags | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Read experiments | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Create or update experiments | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Read experiment results | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Query analytics or events | Yes | Yes (200+ tools) | Limited | Limited | Yes | No (REST) | No | +| Manage segments and audiences | Yes | Yes | Yes | Yes | Yes | No (REST) | Yes | +| Governance actions (permissions, audit) | Partial | Partial | No | Yes | Partial | No | No | +| Code generation (variant to component) | No | No | No | No | No | No | Yes | +| Hosting model | First-party (managed) | First-party + self-host | First-party + OSS self-host | Hosted Remote | Hosted | n/a (REST) | Hosted Remote | +| Auth method | API key | API key | API key | OAuth | API key | n/a | OAuth | +| Approximate tool count | ~30 | 200+ | ~25 | ~20 | ~15 | n/a | 7 | +| Recommended scoping | Default | `?features=` to scope | Default | Default | Default | n/a | Default | + +--- + +## Notes per platform + +### Statsig + +The MCP is mature and covers the full Statsig surface (gates, dynamic configs, experiments, holdouts, layers). The tool count is moderate, which keeps the agent context window tight without sacrificing capability. Authentication is API-key based; provision a service account for agent workflows so the audit trail is clean. + +Recommended for AI-forward teams that want full CRUD without context window concerns. + +### PostHog + +The MCP is the most expansive of any platform here. 200+ tools cover analytics, experiments, flags, surveys, replays, and more. The breadth comes with a cost: without scoping, the agent's context window fills with tool definitions before it can do useful work. + +Use the `?features=` scoping parameter to load only the surfaces you need. For an experimentation-focused workflow, scope to flags, experiments, and analytics; skip replays, surveys, and error tracking unless they are part of the workflow. + +Recommended for AI-forward teams that need broad coverage and are willing to invest in scoping discipline. + +### GrowthBook + +The MCP is the first open-source production MCP for experimentation. It covers the GrowthBook surface (experiments, flags, metrics, segments). Tool count is moderate. Self-host means you can run the MCP inside your network for data sovereignty. + +Recommended for OSS-preferring teams and regulated industries that need the MCP inside their VPC. + +### Optimizely + +The hosted Remote MCP works in browser-based ChatGPT and Claude.ai. Authentication is OAuth, which integrates cleanly with enterprise SSO. Tool count is moderate. Coverage is solid on Web Experimentation and Feature Experimentation; Personalization features are accessed via the same surface. + +Recommended for enterprise teams that need OAuth and SSO compatibility for compliance. + +### Amplitude + +The hosted MCP is available to all customers including the free tier. Tool count is smaller than Statsig or PostHog. Coverage is strongest on analytics queries (cohorts, funnels, retention) and adequate on experiments and flags. + +Recommended for teams that primarily need analytics queries and use experiments as a supplementary capability. + +### Eppo + +No first-party MCP as of May 2026. REST API is the integration path. Workflows that depend on agent-driven experiment creation need a custom adapter or a wait until Eppo ships an MCP. + +Track for a future MCP release. The platform has the underlying API; an MCP wrapper is a likely future development. + +### Kameleoon + +Hosted Remote MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. The tool surface is purpose-built for the win-to-code workflow. The smallest MCP in this matrix and the most opinionated. + +Recommended for teams running the marketing-site-to-product-code workflow. Layer with another MCP if your needs go beyond that scope. + +--- + +## Choosing by workflow + +**Agent-driven full experiment lifecycle (create, run, monitor, conclude).** Statsig, PostHog, GrowthBook, or Optimizely. All four support full CRUD via MCP. + +**Agent-driven analytics queries plus light experiment work.** PostHog (with scoping) or Amplitude. Both have strong analytics MCP coverage. + +**Agent-driven win-to-code conversion.** Kameleoon. The only platform with this workflow as a primary feature. + +**Human-driven workflow where MCP is supplementary.** Any of the seven. Eppo via REST works for the supplementary case. + +**Compliance-sensitive workflow (SSO, audit, data residency).** Optimizely (OAuth, hosted) or GrowthBook self-hosted (data residency, OSS auditable). + +--- + +## Things to check before committing + +1. **Tool count and scoping.** Verify the agent context window is comfortable with the platform's tool surface. PostHog without scoping fills the window fast. +2. **Auth model.** API key is faster to provision; OAuth is required for compliance-sensitive deployments. +3. **CRUD coverage.** Read-only MCPs limit your workflow. Verify create and update are supported for your target objects. +4. **Hosting model.** Hosted is faster to start; self-host is required for data sovereignty. +5. **Trajectory.** MCP capability evolves monthly. Check the platform's changelog before committing for a future-sensitive workflow. diff --git a/skills/experimentation-platform-orchestrator/references/migration-playbook.md b/skills/experimentation-platform-orchestrator/references/migration-playbook.md new file mode 100644 index 0000000..94c8ec8 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/migration-playbook.md @@ -0,0 +1,139 @@ +# Migration playbook + +Five common migration paths with effort estimates, the first 30 days plan, the 30-90 day cutover plan, and what NOT to do. + +The discipline applies to every migration. Three rules are non-negotiable: + +1. Do not parallel-run forever. Set a cutover date and hold to it. +2. Do not big-bang switch. The risk of a silent miscount is too high; you cannot tell whether the new platform is computing correctly without overlap. +3. Do not retire the old platform before all in-flight experiments complete. + +--- + +## Statsig to PostHog + +Trigger. Company has outgrown a pure experimentation platform and wants analytics, experiments, and feature flags in one surface. Often coincides with consolidating away from a separate analytics tool. + +Effort. 3 to 5 engineer-weeks. Add 2 to 4 weeks if you are also consolidating analytics. + +First 30 days plan. +- Week 1: Provision PostHog. Wire the SDK alongside Statsig. Verify event volume matches. +- Week 2: Recreate the top 5 metrics in PostHog. Compare totals against Statsig over a 7-day window. Investigate any variance over 1%. +- Week 3: Recreate 1 active experiment in PostHog as a parallel experiment. Run both for 7 to 14 days. Confirm results agree within statistical noise. +- Week 4: Decision review. Either commit to migration or roll back to Statsig only. Document the decision. + +30-90 day cutover plan. +- Migrate experiments one at a time. New experiments start in PostHog. Existing experiments complete in Statsig. +- Migrate feature flags by service. Highest-risk services move last. +- Build dashboards in PostHog before retiring Statsig dashboards. +- Final week: retire Statsig SDK from the codebase. Remove credentials. + +What NOT to do. +- Parallel-run the SDKs for more than 90 days. The dual cost compounds; the integration tax distracts. +- Migrate flags before experiments. Flags are operational; experiments are time-bound. Flag migration creates production risk that overshadows the migration value. +- Skip the metric reconciliation. Discovering a metric definition mismatch a month into the migration is the worst possible time. + +--- + +## Optimizely to Statsig + +Trigger. Budget pressure or modernization push. Often coincides with a CFO-led cost review. + +Effort. 4 to 8 engineer-weeks. Add weeks proportional to how heavily personalization features are used (Optimizely has personalization that Statsig does not match). + +First 30 days plan. +- Week 1: Feature parity audit. List every Optimizely feature in active use. Mark which ones Statsig covers, which it does not, and which need a workaround. +- Week 2: Migrate the simplest 3 experiments. Validate results match. +- Week 3: Address the personalization gap. If personalization is heavy, plan a hybrid (Statsig for product experiments, Optimizely retained for personalization, with a retirement date in 6 to 12 months). +- Week 4: Decision review. Commit to full migration or hybrid. + +30-90 day cutover plan. +- Migrate experiments first, flags second. Personalization last (or retain in Optimizely). +- Communicate clearly with non-engineering experiment authors. The visual editor change is the friction point. +- Train non-engineering authors on Statsig's experiment definition format. +- Final phase: cancel Optimizely contract on its renewal date. Do not cancel mid-term; the savings rarely justify the early-termination friction. + +What NOT to do. +- Underestimate the non-engineering author retraining. Marketing-led teams will resist the platform change harder than engineering-led teams. +- Force personalization into Statsig if the use case does not fit. A hybrid setup is cheaper than a forced consolidation that the team cannot use. +- Cancel the Optimizely contract before all in-flight experiments complete on the old platform. + +--- + +## PostHog to Eppo + +Trigger. Statistical rigor becomes the binding constraint. A data team has joined or grown, and a critical experiment surfaced a wrong-result decision that PostHog's defaults did not catch. + +Effort. 6 to 10 engineer-weeks. The migration is harder because PostHog includes session replay, error tracking, and analytics that Eppo does not replace. Plan for a dual-platform end state. + +First 30 days plan. +- Week 1: Define the scope. Eppo replaces experiments. PostHog stays for analytics, replay, and tracking. Document which surface owns what. +- Week 2: Wire Eppo SDK alongside PostHog. Configure metric definitions in the warehouse. +- Week 3: Run one parallel experiment. Compare statistical conclusions. Investigate any disagreement; this is where the rigor difference shows up. +- Week 4: Decision review. Commit to the dual-platform end state or rethink scope. + +30-90 day cutover plan. +- New experiments start in Eppo. Existing experiments complete in PostHog. +- Build the metric definition layer in the warehouse so both platforms can agree on what "activation" means. +- Set up reconciliation dashboards. The two platforms will disagree on edge metrics; surface those proactively rather than letting stakeholders find them. + +What NOT to do. +- Try to retire PostHog. The non-experiment features (replay, tracking, analytics) do not have a clean Eppo replacement. +- Skip the warehouse metric layer. Without it, the two platforms compute metrics differently and stakeholders lose trust in both. +- Use Eppo for the small experiments where statistical depth is overkill. The analyst overhead per experiment is higher in Eppo than in PostHog. + +--- + +## GrowthBook to Eppo + +Trigger. Team growth and a desire for commercial support, deeper Bayesian and sequential testing features, and decision-oriented reporting. + +Effort. 2 to 4 engineer-weeks. This is the easiest migration in the playbook because both platforms are warehouse-native; the data already lives in your stack. + +First 30 days plan. +- Week 1: Provision Eppo. Reuse the warehouse connection. +- Week 2: Recreate metric definitions. Most translate cleanly. +- Week 3: Run 1 to 2 parallel experiments to validate. +- Week 4: Cutover. New experiments in Eppo. In-flight in GrowthBook complete on GrowthBook. + +30-90 day cutover plan. +- Migrate active flag rollouts to Eppo if Eppo's flag features are sufficient. +- Retire GrowthBook 30 to 60 days after the last in-flight experiment completes. + +What NOT to do. +- Migrate flags if Eppo's flag features do not match. Run a separate flag platform if needed. +- Cancel GrowthBook before all dashboards are recreated. + +--- + +## Any to Statsig (consolidation) + +Trigger. Multi-platform mess. Common when a company has accumulated 2 to 3 platforms over time and wants to consolidate. + +Effort. 6 to 12 engineer-weeks, scaling with the number of platforms and in-flight experiments. + +First 30 days plan. +- Week 1: Inventory. List every experiment, flag, and dashboard across all platforms. Identify the canonical source of truth where they disagree. +- Week 2: Statsig provisioning. Configure metrics. Validate event volume matches. +- Week 3: Migrate the simplest 5 experiments. Validate results. +- Week 4: Migration plan with explicit retirement dates per old platform. + +30-90 day cutover plan. +- Per-platform retirement. Pick one of the old platforms to retire first (usually the smallest user base). +- Communicate retirement dates clearly. Stakeholders need 30 days of warning per platform. +- Build dashboards before retiring; never after. + +What NOT to do. +- Try to retire all old platforms at once. Sequential retirement is slower but lower risk. +- Skip the inventory step. Discovering a forgotten experiment in production after retirement is the failure mode. +- Underestimate the team training cost. Multi-platform teams have built workflow muscle memory across all of them; consolidation requires retraining. + +--- + +## Validation: how to know the migration succeeded + +Three signals that the migration is complete and successful. + +1. **All in-flight experiments completed on the original platform.** No experiment was stranded mid-test. +2. **Metric values match within statistical noise on the new platform** for at least 30 days post-cutover. Variance over 1 to 2% needs investigation. +3. **The team is shipping experiments at the pre-migration rate or faster** within 60 days of cutover. If velocity has not recovered, retraining or workflow changes are still needed. diff --git a/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md b/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md new file mode 100644 index 0000000..9553bc5 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md @@ -0,0 +1,99 @@ +# Multi-platform orchestration + +When multi-platform is genuine, three coordination patterns are non-negotiable: an ownership matrix, shared metric definitions, and reconciliable dashboards. + +This reference is for the 20% of teams whose surfaces genuinely warrant more than one platform. The 80% should consolidate. If you are not sure which group you are in, the test is whether the platforms overlap. Zero overlap is a candidate for multi-platform; any overlap is a candidate for consolidation. + +--- + +## When multi-platform is warranted + +The pattern is: different surface, different audience, different metric set, no overlap. + +**Marketing site plus product app.** Kameleoon for personalization on the marketing site. Statsig for product experiments. The marketing site's metrics (conversion to signup, page-level engagement) do not collide with the product app's metrics (activation, retention, revenue). The two surfaces are run by different teams with different cadences. + +**Content site plus product app.** Optimizely or Kameleoon for content experiments. PostHog or Statsig for product. Same pattern: different surface, different audience. + +**Pre-acquisition multi-tool reality.** Two products from two acquired companies on different platforms. Multi-platform is the temporary reality; consolidation is the eventual answer. Plan a retirement date during the integration project. + +**Specialized statistical needs.** A core product on Statsig plus a specialized statistical workload (causal inference, network effects analysis) running on a separate tool. Rare but legitimate when the specialty platform has capabilities the primary platform lacks. + +--- + +## When multi-platform is a mess + +Three signals that the multi-platform setup has drifted into a consolidation candidate: + +1. **The same experiment can be defined on more than one platform.** Stakeholders ask "which one are we using?" and the answer is unclear. +2. **Metrics differ between platforms.** "Activation rate" computes one way in Statsig and another way in PostHog. Stakeholders see two numbers and trust neither. +3. **Operational overhead exceeds the value of platform diversity.** Engineers spend more time keeping platforms in sync than they save by using each platform's strengths. + +If two of three apply, plan a consolidation. + +--- + +## The ownership matrix + +The first artifact of a multi-platform setup is an explicit ownership matrix. It names which platform owns which surface, which metrics, and which experiments. Disagreements between platforms are resolved against the matrix. + +| Surface | Primary platform | Secondary platform (if any) | Owner | +|---|---|---|---| +| Marketing site | Kameleoon | None | Marketing team | +| Product app | Statsig | None | Product team | +| Mobile app | Statsig | None | Mobile team | +| Email | None | None | n/a | +| Pricing page | Kameleoon | Statsig (revenue metrics) | Marketing team primary, product team consulted | + +Where two platforms touch the same surface (the pricing page row), name a primary and clarify what the secondary is responsible for. Ambiguity here is the source of every multi-platform drift. + +The ownership matrix lives in a single document, version-controlled, reviewed quarterly. Stakeholders refer to it instead of arguing. + +--- + +## Shared metric definitions + +The second artifact is a shared metric definitions document. The same metric should compute the same way across platforms. + +Example. "Activation rate" might be defined as: percentage of users who completed onboarding within 7 days of signup. The definition includes the event name, the time window, the denominator population, and any exclusions. Both platforms reference the same definition. + +In practice, sharing definitions across platforms is hard. Three approaches. + +**Single source warehouse layer.** Define metrics in your warehouse using a metrics layer (dbt, Cube, Metricflow). Both platforms query the warehouse. This is the strongest pattern. It works if both platforms support warehouse-native metrics (GrowthBook, Eppo) or have warehouse integration paths. + +**Documented definitions with periodic reconciliation.** Each platform has its own metric. The definitions document records what each is supposed to compute. A weekly or monthly reconciliation job compares the two and surfaces variance. This works for vendor-native platforms that do not share a warehouse. + +**Tolerance for variance.** Accept that the two platforms compute slightly differently and document the expected variance range. Over 1 to 2% triggers an investigation. Under 1% is treated as noise. This works when the platforms are used for different surfaces and the metrics are not directly compared across them. + +The wrong approach is no approach. Without one of these three patterns, the platforms drift, and a leadership disagreement surfaces in the worst possible moment. + +--- + +## Reconciliable dashboards + +The third artifact is dashboards that surface the same metrics from both platforms side by side. The point is not that the numbers always agree (they will not). The point is that disagreements are visible and explainable. + +A reconciliation dashboard has three columns per metric: the value from platform A, the value from platform B, and the variance with a threshold. Variance over the threshold triggers a notification. Owners investigate and either explain the variance or fix the underlying definition mismatch. + +Reconciliation runs daily for high-stakes metrics, weekly for everything else. Outputs go to a shared channel where the team sees them; do not let reconciliation reports live in a folder no one reads. + +--- + +## The "primary platform" rule + +In every multi-platform setup, one platform is canonical. If the platforms disagree, the canonical answer wins. Pick the canonical platform once, document it, and stop arguing. + +The canonical platform is usually the one that owns the surface where the metric originates. Revenue metrics: the warehouse is canonical. Product engagement: the product analytics platform is canonical. Marketing-site conversion: the marketing experiment platform is canonical. + +Without a canonical, every disagreement becomes a debate. With a canonical, disagreements become investigations into why the non-canonical platform diverged. + +--- + +## When to consolidate + +Three signals that consolidation is overdue: + +1. **The reconciliation dashboard reports variance more often than not.** The platforms drift faster than the team can reconcile. The cost of staying multi-platform exceeds the cost of consolidating. +2. **A leadership disagreement surfaces a "which one is the source of truth" debate.** Multi-platform is meant to support different surfaces, not different versions of the same answer. If the same answer has two values, consolidation is the fix. +3. **The team is spending more than 10% of its experimentation operational time on platform coordination.** That time should be on experiments, not platform plumbing. + +When consolidation is the right answer, see `migration-playbook.md` for the patterns. The consolidation move is almost always to whichever platform is closest to the canonical for the highest-stakes surface. diff --git a/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md b/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md new file mode 100644 index 0000000..1025a1f --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md @@ -0,0 +1,61 @@ +# Platform decision matrix + +A context-to-platform map. The left column is the situation. The center column is the recommendation. The right column is the reasoning and the common alternative. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. The remaining rows are useful as cross-checks rather than primary picks. + +--- + +## The matrix + +| Situation | Primary recommendation | Reasoning and common alternative | +|---|---|---| +| Pure SaaS, fast-growing, want one platform for flags and experiments | Statsig | Combined feature flags and experiments, modern statistical defaults, fast time to first experiment. Alternative: PostHog if you also want analytics. | +| Product-led growth, want analytics and experiments together | PostHog | Full-funnel context, free tier covers early growth, mature MCP for AI workflows. Alternative: Amplitude if analytics depth matters more than experiment depth. | +| Open-source preference, data sovereignty, warehouse-native | GrowthBook | Data stays in your warehouse, OSS license avoids vendor lock-in, mature statistical defaults. Alternative: PostHog self-hosted if you also need analytics. | +| Enterprise, marketing-led, deep personalization | Optimizely | Visual editing for non-engineers, mature governance, decades of features. Alternative: Adobe Target if you are already on the Adobe stack. | +| Already deep on Amplitude for analytics | Amplitude | Adding experiments is the path of least resistance. Alternative: layer Statsig or Eppo only if statistical depth becomes the binding constraint. | +| Data-team-led, statistical correctness paramount, MCP not yet required | Eppo | Strongest statistical defaults among warehouse-native platforms, decision-oriented reporting. Alternative: GrowthBook if open-source is non-negotiable. | +| Convert marketing-site wins into permanent code | Kameleoon | Purpose-built for the win-to-code path; the only platform with this workflow as a primary feature. Use alongside a primary product-experiment platform. | +| Regulated industry (HIPAA, FedRAMP, healthcare), self-hosting required | GrowthBook self-hosted | Full data residency, audit-friendly, OSS auditable. Alternative: PostHog self-hosted if you also need analytics. | +| Pre-PMF, low traffic, need free tier | PostHog free or Statsig free | Both free tiers cover the early phase. Defer the real platform decision until you have the traffic to make any platform meaningful. | +| 100M+ events per month, cost control is the binding constraint | GrowthBook or Eppo | Warehouse-native pricing scales better than vendor-native at this volume. Alternative: negotiate a custom contract with Statsig or PostHog; only worth it if vendor-native features justify the premium. | +| AI-forward team, MCP-first workflow important | Statsig, PostHog, GrowthBook, or Optimizely | All four have mature MCPs with full CRUD coverage. Avoid Eppo for now (REST only). | +| Mid-market SaaS, governance important, single tool preference | Statsig | Enterprise governance is mature, combined flags and experiments simplify the operational surface. Alternative: Optimizely if marketing-led, GrowthBook if open-source preferred. | +| Web-only personalization, content site, no product app | Kameleoon or Optimizely | Both are strong on visual editing and personalization. Kameleoon for the win-to-code workflow; Optimizely for enterprise governance. | +| Data warehouse already in place (Snowflake, BigQuery), small data team | Eppo | Statistical defaults are decision-grade, warehouse compute is already a line item, low operational burden. Alternative: GrowthBook if commercial support is not required. | +| Solo founder or pre-seed startup | PostHog free or Statsig free | Both work, both are free at this stage. Pick whichever you are more familiar with; the decision is reversible. | + +--- + +## Worked examples + +### Example 1: Series B SaaS, 5M events/month, PM-led, considering Statsig vs PostHog + +The team has feature flags in LaunchDarkly already, has analytics in Amplitude, and is considering experiments. The PM-led culture wants experiments shipped weekly with low engineer overhead. + +**Recommendation.** Statsig. The PM-led culture matches Statsig's defaults. The 5M event volume is comfortably in the free tier or a small paid contract. Combined flags and experiments will likely cause a LaunchDarkly migration in 12 to 18 months, but that is a future decision, not a current one. PostHog is the alternative if the team also wants to consolidate analytics, but Amplitude is already paid for and migrating analytics is a bigger project than starting experiments. + +### Example 2: 50-person fintech, regulated industry, need data residency + +The team needs HIPAA-equivalent controls (financial regulations), data must stay in their VPC, and the engineering team is comfortable with a more hands-on platform. + +**Recommendation.** GrowthBook self-hosted. Data residency is a hard requirement and rules out all vendor-native options. The engineering team has the capacity to operate self-hosted. PostHog self-hosted is the alternative if analytics is also needed. + +### Example 3: Marketing-led brand, want non-engineer-shipped experiments + +The team is a marketing organization with a small engineering function. The marketing leads want to ship experiments without filing engineering tickets. + +**Recommendation.** Optimizely. Visual editing for non-engineers is a hard requirement. Statsig and PostHog can be used by non-engineers but require more comfort with structured experiment definitions. Kameleoon is the alternative if the win-to-code workflow is important. + +### Example 4: Data-team-led, 100M events/month, statistical depth required + +The data science team owns experimentation, runs the warehouse, and has been burned by misleading results from a less rigorous platform. + +**Recommendation.** Eppo. Statistical correctness is the headline. The 100M event volume makes warehouse-native pricing more attractive. The lack of MCP is acceptable because the team's workflow is data-scientist-driven, not agent-driven. GrowthBook is the alternative if open-source is required. + +### Example 5: Pre-PMF startup, 200K events/month + +The team has a product but no product-market fit. They want to start experimenting to find the wedge. + +**Recommendation.** PostHog free tier. Free covers the volume. Analytics plus experiments in one place lets the team learn. Defer the real platform decision until traffic is 10x higher and the platform tax becomes a real number. diff --git a/skills/feature-flagging/SKILL.md b/skills/feature-flagging/SKILL.md new file mode 100644 index 0000000..c0fa267 --- /dev/null +++ b/skills/feature-flagging/SKILL.md @@ -0,0 +1,281 @@ +--- +name: feature-flagging +description: Operational discipline for feature flags as production infrastructure. Flag types, naming, targeting rules, rollout strategy, lifecycle, governance, stale flag management, and the technical debt patterns that bite teams who weren't deliberate about it. +category: product +catalog_summary: "Flags as production infrastructure: types, naming, lifecycle, targeting, rollout, stale flag cleanup, governance" +display_order: 5 +--- + +# Feature Flagging + +A senior engineer's playbook for using feature flags well, not just frequently. + +Feature flags are infrastructure. Treated as such, they enable kill switches, gradual rollouts, A/B experiments, permission gates, and operational toggles without redeploys. Treated casually, they become the largest accumulating technical debt in your codebase: thousands of dead flags, conflicting evaluation logic, brittle targeting, and a permission surface no one fully understands. + +This skill is the discipline that prevents the second outcome. It assumes you have a feature flag platform (LaunchDarkly, Flagsmith, Split.io, VWO FME, GrowthBook, Statsig, PostHog, Optimizely; the platform does not matter for the principles). It assumes your engineering team can implement targeting rules and SDK integration. The hard part is the operational discipline, and that is what is here. + +When to use this skill: any time you are about to introduce a flag, modify a flag, audit existing flags, or design a flag-related governance policy. + +--- + +## What this skill is for + +The skill spans the operational lifecycle of a flag from creation through retirement. Flag types and the discipline of not mixing them. Naming conventions that survive code review. Lifecycle expectations baked in at creation, not bolted on later. Targeting rules that compose without fragility. Rollout strategies that match the risk profile of the launch. Stale flag management on a quarterly cadence. Governance and permissions that balance access with audit. Performance considerations so flags do not become a latency tax. Testing patterns that cover both branches. Rollback discipline. Observability across rollouts. + +The skill does not cover experiment design; for hypothesis writing, sample size, MDE, and the discipline of arriving at a defensible decision, see the `experiment-design` skill. It does not cover statistical analysis or variance reduction; those live in the `experimentation-analytics` skill. It does not cover platform-specific tooling; for MCP commands, auth, and platform-specific configuration, consult the chosen platform's documentation. This skill produces the operational shape; the platform implements it. + +--- + +## The five flag types + +Mixing flag types is the root cause of most flag mess. A flag is one of five things; commit at creation and do not let it drift. + +**Release flag.** Code is in production but disabled. The new feature ships dark, gets toggled on for a percentage, then ramps to 100. Lifetime: short, days to weeks. Lifecycle: clean removal after launch. Common name prefix: `release_`. + +**Experiment flag.** Users are randomly assigned to variants; conversion is measured. The flag controls which variant a user sees. Lifetime: medium, one to six weeks. Lifecycle: variant chosen, code paths consolidated, flag removed. Common name prefix: `exp_`. + +**Operational flag.** A kill switch or circuit breaker that lets ops disable a misbehaving feature without a redeploy. Lifetime: long-lived, often years. Lifecycle: usually never removed; remains as standby. Common name prefix: `ops_`. + +**Permission flag.** Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. Lifetime: long-lived. Lifecycle: managed alongside billing and access infrastructure. Common name prefix: `perm_`. + +**Configuration flag.** Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account. Lifetime: long-lived. Lifecycle: governed by sales and product agreements. Common name prefix: `cfg_`. + +Each type has different lifecycle, governance, and removal expectations. Mixing them in one flag (the flag is both a kill switch AND a permission gate AND now we are using it for an experiment) is the most common source of flag mess. When the flag's purpose changes, create a new flag and migrate. Do not overload an existing one. + +--- + +## Flag naming conventions + +A flag name encodes type, owner, and purpose. Without that encoding, a flag list at month nine is unreadable and the cleanup playbook from [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md) cannot tell what is safe to remove. + +The convention this skill recommends is `<type>_<owner>_<semantic_name>_<version_or_date>`: + +- `release_checkout_redesign_2026q2` +- `exp_billing_pricing_v2` +- `ops_search_circuit_breaker` +- `perm_enterprise_audit_log` +- `cfg_tenant_acme_custom_dashboard` + +Pick snake_case or kebab-case once, organization-wide, and stick with it. Mixing both in the same platform produces typo-driven bugs that bite at 3 AM. Vague names die a slow death: `new_feature`, `temp_toggle`, `test_flag`, `pricing_update_v3`. Within months, no one knows which `pricing_update` shipped and which is dead. + +For deeper coverage including the table of typed prefixes, owner conventions, and the migration plan for existing badly-named flags, see [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md). + +--- + +## The flag lifecycle + +Every flag has five life phases. Each phase has explicit entry and exit criteria. Skipping phases is how flag mess accumulates. + +**Birth.** Flag created with explicit metadata: owner, type, target removal date (for release and experiment flags), rollout plan, monitoring approach. The metadata is not optional; without it the flag has no end-of-life. + +**Adolescence.** The feature behind the flag is being built. Code paths exist for both the disabled (current production) branch and the enabled (new) branch. Both are tested. The flag remains off in production. + +**Launch.** Production rollout begins. Percentage starts low (1 or 5 percent), monitored at each step, ramps if metrics hold. Ramp gates documented in [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +**Maturity.** The flag is at 100 percent rollout. The new code path is the production path. Monitoring continues for at least 30 days to catch issues that did not show up during the ramp. + +**Death.** The flag is removed from code (PR that deletes the gating logic) and removed from the platform. The audit trail records the removal. + +The asymmetry: birth is fast (one PR creates the flag and gates the new code), death requires intentional cleanup. Most flag mess is unfinished death. Birth-and-death have to be planned together; the death plan is part of the birth metadata. + +For the per-phase checklist, see [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md). + +--- + +## Targeting rules and segmentation + +A targeting rule is the boolean expression that determines whether a user, account, or request gets the treatment branch. There are four useful target dimensions: + +- **User attributes.** `user.email_domain == "acme.com"`, `user.signup_date > "2026-01-01"`, `user.plan == "enterprise"`. +- **Account attributes.** `account.tier == "enterprise"`, `account.region == "EU"`, `account.feature_x_enabled == true`. +- **Request attributes.** `request.country == "US"`, `request.device_type == "mobile"`, `request.api_version >= 3`. +- **Time-based.** `time > "2026-06-01T00:00:00Z"`, `time < "2026-12-31T23:59:59Z"`. + +Compose with AND, OR, and NOT. Keep the expressions simple. If your rule needs three nested clauses, your taxonomy is wrong. Either define a segment (a named group of users with shared attributes) and target the segment, or split into multiple flags. + +The most common pitfall: targeting on attributes that change frequently. If the rule is `user.last_login_date > "2026-04-01"`, a user who logs in on May 1 sees the treatment, then their value changes the next day, and they see the control again. The user experience whiplashes. Volatile attributes belong in segments computed off snapshots, not in live targeting rules. + +For pattern catalog and anti-patterns, see [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md). + +--- + +## Rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile. + +**Percentage rollout.** The default for release flags. Start at 1 or 5 percent. Watch error rates, latency, and the primary success metric for at least one peak hour. If clean, ramp to 10. Watch. Ramp to 25, then 50, then 100. Total elapsed time depends on traffic, but a typical pattern is 1 percent for one day, then 10 percent for two days, then 50 for two days, then 100. Production rollouts that complete in under four hours are usually rolling too fast. + +**Cohort rollout.** Internal employees first, then beta customers, then free tier, then paid. Each cohort is a named segment; the flag advances through them in sequence. Use this for risky launches where the blast radius matters more than rollout speed. + +**Geo-staged rollout.** One region at a time. The default for compliance-sensitive features (data residency, regulatory disclosures, region-specific UX). Pair with the platform's region targeting capability so the rule does not have to be hand-written. + +**Time-based rollout.** Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment. Watch the timezone; midnight Eastern is not midnight UTC. Avoid time-based rollouts on holidays unless you have weekend on-call coverage. + +The "ramp and watch" rule: at each percentage step, monitor the system for at least one peak hour before advancing. The peak hour is when the rate of any new failure mode is highest; if the system holds at peak for an hour, the next step is safe. If you ramp during off-peak and immediately advance, you have not actually tested the change. + +For full strategy detail and a worked example for a checkout redesign, see [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +--- + +## Stale flag management + +Every live flag adds runtime cost: evaluation overhead, two code paths to maintain, mental overhead for engineers who read the code. One flag is fine. Two hundred dead flags is a productivity tax that compounds. + +Most platforms support stale flag reporting: flags that have not been evaluated in N days. Threshold defaults: 30 days for release flags and experiment flags, 90 days for operational and permission flags. A flag that has not been evaluated in 30 days is either retired in production (no users in the targeting rule) or completely dead in code (the gating call has been removed but the flag itself was never deleted). + +The cleanup playbook is mechanical: + +1. Generate the stale flag report from the platform. +2. For each flag: identify owner, last evaluation, type, recommended action. +3. Triage in a quarterly meeting: keep, remove, or investigate. +4. Open one PR per flag for code-side removal. One per PR is reviewable; bundling ten is not. +5. Delete from the platform after the PR merges. + +The reason cleanup does not happen by default: removing a flag is a code change PR with review, testing, and deploy overhead. PMs do not reward it (the feature already shipped). SREs eventually get fed up with the noise. The fix is to make removal part of the launch checklist, not a separate effort. When a flag is created, the removal date is in the metadata. The launch ticket has a follow-up sub-ticket scheduled 30 days out that says "remove flag X." If the launch goes well, the sub-ticket gets done. + +For the full quarterly cadence including ownership rotation for orphan flags, see [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md). + +--- + +## Governance and permissions + +Different roles need different access. Engineering can create flags broadly. Product can author targeting rules in dev and staging. Production targeting changes deserve a smaller set of approvers. + +Recommended permission tiers: + +- **Viewer.** Read-only across all environments. Includes most of engineering, product, support. +- **Editor.** Can create and modify flags in dev and staging. Includes the team that owns the flag. +- **Approver.** Can promote flag changes from staging to production. Smaller group; usually the team lead and the on-call engineer. +- **Admin.** Full control including deleting flags, modifying permissions, and accessing audit logs. Smallest group; platform team plus a backup. + +Production-impacting flag changes go through review like deploys, not chat. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review; the rule does not silently appear in production because someone clicked a button. + +Audit trail: every flag change logged with actor, timestamp, before/after rule, reason. Most platforms expose this; configure it to write to the central log aggregator alongside other infrastructure events. + +Environment promotion: rules tested in dev, promoted to staging, promoted to production. Authoring a production rule directly in production skips both staging tests and the review gate. Treat it as a deploy: dev → staging → production, with the same review and approval at each stage. + +Emergency override: who can flip the kill switch at 3 AM? Document, test in incident drills, and confirm the override path actually works. A kill switch nobody can find is not a kill switch. + +--- + +## Flag dependencies and conflicts + +Two failure modes that come from flags interacting: + +**Dependency.** Flag B's code path requires flag A to be on. Hard to model in most platforms; the SDK does not know about the inter-flag relationship. Avoid where possible; if you need to express it, document in the flag description and add a unit test that fails if A is off and B is on. + +**Conflict.** Two flags target the same surface, last-write-wins. The result depends on evaluation order, which depends on SDK implementation, which depends on platform internals. Detect via shared-key audit: any two flags whose targeting rules overlap on the same code path is a conflict candidate. The platform usually does not flag this; the team has to audit. + +Cross-team conflict is the dangerous version: team Alpha's release flag for the checkout redesign interacts with team Bravo's experiment on the pricing page. The interaction is invisible until production users see broken UI because both flags fired. The fix is up-front coordination via the experiment registry described in `experiment-design`. Discover before launch via planning, not via a 2 AM incident. + +For mutually exclusive experiment groups (where the platform enforces that a user is in either test A or test B but never both), see the experiment-design skill's coverage of mutex enforcement. + +--- + +## Performance considerations + +A flag evaluation is a function call (cheap) plus possibly a network call to the platform (expensive). The performance question is how much you spend in the latter. + +Cache aggressively. Most server-side SDKs cache flag values per request, per session, or per user; configure the cache so the network call happens once per relevant scope, not on every flag check. A request that evaluates fifty flags should hit the platform once at request start, not fifty times. + +Bulk evaluation: most platforms support evaluating all flags for a user or context in one call. Use it. The latency cost of "fifty individual flag checks" is fifty times the per-check overhead; the latency cost of "one bulk evaluation that returns all fifty" is one round trip plus a fast lookup per check. + +SDK selection: server-side SDKs are usually preferable to client-side for sensitive logic where latency, security, and freshness matter. Client-side SDKs are appropriate for UI-only behavior where the user can see the flag value in DevTools anyway. Mixing the two creates inconsistencies; if a user gets a different flag value on the server than the client, the UI breaks. + +Latency budget: evaluating fifty flags per request should add no more than 5 ms in the typical case. If it adds more, the SDK is misconfigured (no caching, no bulk evaluation, evaluating in a hot loop). Audit before scaling. + +--- + +## Testing flag-gated code + +Both branches need tests. The disabled branch is the existing production behavior; the enabled branch is the new code. Unit tests cover both with explicit flag overrides at test setup. + +Test the transition. What happens to a user mid-session when their flag value changes? In most well-behaved systems, the user finishes their current request with the value they had at request start, then sees the new value on the next request. Document the assumption explicitly. If your system mid-flips a user inside a session, that is usually a bug. + +Integration tests with flag overrides: most platforms support test-only flag overrides that do not affect production. Use them for end-to-end tests that exercise both branches. Without test overrides, integration tests have to share the production flag config, which means you cannot test new features that are still gated off in production. + +Common failure: shipping a "wins" experiment but only the test environment had the right targeting rules. The test environment let in 100 percent of test users via a permissive rule; production rules are stricter and let in only 20 percent. The lift you measured does not translate. Catch via staged rollout: the first 1 percent in production should match the test result before you ramp further. + +--- + +## Rollback discipline + +Flags are useful for instant rollback of the gated change. They are not a substitute for code rollback. If a bug ships in code that is not flag-gated (a fix to the existing path, an unrelated change in the same deploy), flipping the flag does nothing. Treat flag rollback as one tool among several, not as the only tool. + +If flipping the flag does work, document the rollback. If it does not work, the bug is in non-flag-gated code or in flag dependencies. Diagnose accordingly; do not assume the flag failed. + +Speed matters. How fast can you flip a flag in production? The target is under 60 seconds via UI or MCP, under 5 minutes via API plus auth. If your platform takes 15 minutes to propagate a flag change, that is a real incident-response constraint and the team should know. + +Practice. Include flag rollback in incident drills. The first time you flip a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. + +--- + +## Observability on flags + +Log flag evaluations alongside other request data. The flag value at evaluation time goes on the request log as a contextual field. When you investigate a slow request or an error, the log shows which flag values were active. + +Alert on flag evaluation rate changes. If a flag's evaluation rate suddenly drops, the rule is misconfigured (no users matching) or the SDK is broken. Either way, the team should know within minutes. + +Build dashboards for production rollouts. What percentage of users see treatment versus control, broken down by region, plan, device, etc. Without the dashboard, the rollout is a black box; with it, the team can answer "are we actually rolling out evenly across segments?" without writing a SQL query. + +Connect to error tracking. When errors spike during a rollout, the dashboard should show whether errors correlate with the flag value. Spike on treatment branch = roll back the flag. Spike on both branches = the issue is unrelated and the flag rollback will not help. + +--- + +## Common failures (rapid-fire) + +A short pattern catalog. Detail in `references/`. + +- "We launched but 90 percent of users still see the old version" means the rollout rule is wrong. Audit the rule against actual user attributes. +- "We disabled the flag but the bug is still happening" means the affected code path is not flag-gated, or there is a cached value, or a dependent flag is still on. +- "We have 400 dead flags and removing them is too risky" means cleanup never happened. Start the quarterly cadence now; one PR per flag. +- "Two flags target the same code path and we don't know which wins" means a conflict. Audit shared keys, decide one of them is canonical, retire the other. +- "Our flag evaluator is causing latency spikes" means bulk evaluation or caching is missing. Audit the SDK config. +- "We need to give finance access to feature toggles but they shouldn't change production rules" means permission tiering. Viewer for finance, editor for the owning team, approver for the team lead. + +--- + +## The framework: 14 considerations for sustainable feature flagging + +When designing or auditing feature flags, walk these 14 considerations: + +1. **Type clarity.** Release, experiment, operational, permission, or configuration. Pick one at creation; do not let it drift. +2. **Naming.** Typed prefix, owner prefix, semantic name. Avoid vague. +3. **Lifecycle planning.** Birth and death committed at creation. Removal date in metadata. +4. **Targeting taxonomy.** User, account, request, or time-based. Avoid volatile attributes. +5. **Rule simplicity.** AND, OR, NOT only. Three nested clauses means the taxonomy is wrong. +6. **Rollout match.** Strategy matches the risk profile. Percentage for low risk, cohort for medium, geo for compliance, time-based for coordinated launches. +7. **Ramp discipline.** One peak hour at each percentage step. No four-hour rollouts. +8. **Stale flag cadence.** Quarterly cleanup. One PR per removal. Make removal part of the launch checklist. +9. **Permission tiering.** Viewer / editor / approver / admin. Fewer admins than approvers, fewer approvers than editors. +10. **Environment promotion.** Dev to staging to production with review gates. Production rules are not authored in production. +11. **Conflict audit.** Two flags on the same surface = conflict. Detect via shared-key audit; coordinate cross-team via the experiment registry. +12. **Performance budget.** Bulk evaluation, caching, server-side SDKs for sensitive logic. 5 ms total budget for fifty flag checks. +13. **Branch testing.** Both code paths covered by tests. Transition behavior documented. +14. **Observability.** Every flag evaluation logged. Every rollout dashboarded. Errors correlated with flag value during incidents. + +--- + +## Reference files + +The following reference files extend this skill: + +- [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md): typed prefixes, owner prefixes, semantic naming patterns, and the migration plan for existing badly-named flags. +- [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md): birth-to-death checklist organized by lifecycle phase. +- [`references/flag-types-reference.md`](references/flag-types-reference.md): the five flag types in detail with worked examples and common pitfalls. +- [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md): quarterly cleanup process and the orphan-ownership pattern. +- [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md): common patterns and anti-patterns for targeting rules. +- [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md): percentage, cohort, geo, time-based, and combination strategies with a worked example. +- [`references/governance-and-permissions.md`](references/governance-and-permissions.md): permission tiers, environment promotion, approval workflows, and emergency override. + +--- + +## Closing: when to remove a flag + +The default disposition for any flag should be removal. Flags that earn permanent residence in the codebase (operational kill switches, permission flags tied to billing, configuration flags tied to contracts) are exceptions, not norms. Most release and experiment flags should be removed within 30 days of the launch decision. + +The cost of leaving them is real: every dead flag is two code paths to maintain, two test suites to keep green, and one more line of mental overhead for the engineer who reads the file next quarter. The cost compounds across hundreds of flags. + +The discipline of removing them is the discipline of caring about the codebase you will work in next quarter. It is the same discipline behind cleaning up after a deploy, removing dead imports, and writing a post-mortem within a week of the incident. None of it ships features today. All of it makes shipping features tomorrow easier. + +For platform-specific patterns (which platform handles which flag type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the experiment-design layer above this skill (hypothesis discipline, sample size, decision-making), see the `experiment-design` skill. For the analytical layer below this skill (variance reduction, sequential testing math, Bayesian alternatives), see the `experimentation-analytics` skill. diff --git a/skills/feature-flagging/references/flag-lifecycle-checklist.md b/skills/feature-flagging/references/flag-lifecycle-checklist.md new file mode 100644 index 0000000..619adb8 --- /dev/null +++ b/skills/feature-flagging/references/flag-lifecycle-checklist.md @@ -0,0 +1,119 @@ +# Flag lifecycle checklist + +A phase-by-phase checklist for the operational discipline of a flag from creation through removal. Run through the phase the flag is currently in; do not skip ahead. + +--- + +## Phase 1: Birth (creation) + +Before merging the PR that introduces a new flag: + +- [ ] Type committed. Release, experiment, operational, permission, or configuration. Pick one. +- [ ] Name follows the convention from `flag-naming-conventions.md`. +- [ ] Owner assigned. The team or person responsible for the flag's lifecycle. +- [ ] Target removal date set in metadata (release flags: 30-60 days; experiment flags: end of test plus 14 days; operational/permission/configuration flags: "long-lived, review annually"). +- [ ] Rollout plan attached. Percentage, cohort, geo, or time-based; abort criteria defined. +- [ ] Monitoring approach attached. What metric is being watched? What alert fires if the rollout breaks something? +- [ ] Both code branches tested. The disabled branch (existing production) and the enabled branch (new code). +- [ ] Default value confirmed off in production. +- [ ] Removal sub-ticket created and scheduled (release/experiment flags only). + +If any item is no, do not merge. + +--- + +## Phase 2: Adolescence (pre-launch) + +The feature behind the flag is being built in dev and staging. The flag remains off in production. + +- [ ] Feature complete in code, both branches tested. +- [ ] QA sign-off on enabled branch. +- [ ] Staging rule mirrors planned production rule (does not have to match exactly; should be representative). +- [ ] Telemetry confirmed. Logs include flag value as a contextual field. Dashboards exist for the metrics the rollout will watch. +- [ ] Rollout plan reviewed by approver. + +--- + +## Phase 3: Launch (rollout) + +Production rollout begins. Each percentage step has its own gate. + +For each step (typical: 1% → 10% → 50% → 100%): + +- [ ] Apply rule change via platform UI, MCP, or API. +- [ ] Confirm rule applied. Flag evaluation rate matches expected percentage. +- [ ] Watch primary success metric, error rate, latency p95 for at least one peak hour. +- [ ] If clean, advance to next step. +- [ ] If degraded, hold or roll back. Document what was observed. + +At 100%: + +- [ ] Hold for 7 days at 100% before declaring launch complete. +- [ ] Confirm metrics stable across the full holding period. +- [ ] Schedule the 30-day review (calendar reminder for the owner). + +--- + +## Phase 4: Maturity (post-launch) + +Flag is at 100% rollout. Both code paths still exist. The new path is production. + +- [ ] 30-day review: any regressions detected? Any rollbacks needed? +- [ ] Confirm the removal sub-ticket created at birth still exists and is scheduled. +- [ ] Confirm no unexpected dependencies on the flag from other code paths. + +If the flag is operational, permission, or configuration, the lifecycle ends here. The flag is permanent. + +If the flag is release or experiment, proceed to Phase 5. + +--- + +## Phase 5: Death (removal) + +The flag has reached its target removal date or its purpose is complete. + +Code-side: + +- [ ] Open a single PR that removes the flag's gating logic. One flag per PR. +- [ ] Delete the disabled branch (the old code path). Keep only the enabled branch. +- [ ] Delete tests that targeted the disabled branch. +- [ ] Update any documentation that referenced the flag. +- [ ] Confirm CI passes; tests still cover the new (now permanent) code path. +- [ ] Merge the PR. + +Platform-side (after PR merges): + +- [ ] Confirm the flag has zero evaluations in the platform's dashboard for at least 24 hours. +- [ ] Archive or delete the flag from the platform. +- [ ] Audit log entry confirms deletion with actor, timestamp, reason. + +Documentation: + +- [ ] Close the original removal sub-ticket created at birth. +- [ ] Update any team-level flag inventory the team maintains. + +--- + +## Phase 6: Audit (quarterly) + +Even with the discipline above, some flags will slip through. The quarterly audit catches them. + +- [ ] Generate stale flag report from the platform (>30 days unevaluated for release/experiment, >90 days for operational). +- [ ] Triage in a meeting: keep, remove, or investigate per flag. +- [ ] Open removal PRs (one per flag) for the "remove" pile. +- [ ] Investigate the "investigate" pile; usually the answer is remove or rename. + +For the full audit pattern, see `stale-flag-cleanup-playbook.md`. + +--- + +## Common slips + +The phases above describe the disciplined path. Common slips: + +- Birth without removal date. Fix: require the removal date as part of the flag-creation form or PR template. +- Launch without monitoring. Fix: the rollout plan review at end of Phase 2 catches this. +- Maturity skipped (rolled to 100%, never reviewed). Fix: the 30-day review reminder is in the launch ticket. +- Death skipped (flag forgotten). Fix: the quarterly audit catches it. + +The slips compound. A skipped death today is one more flag to clean up at quarter end. A hundred skipped deaths over a year is the productivity tax described in `stale-flag-cleanup-playbook.md`. diff --git a/skills/feature-flagging/references/flag-naming-conventions.md b/skills/feature-flagging/references/flag-naming-conventions.md new file mode 100644 index 0000000..c5daa6d --- /dev/null +++ b/skills/feature-flagging/references/flag-naming-conventions.md @@ -0,0 +1,128 @@ +# Flag naming conventions + +A flag name encodes type, owner, and purpose. Encoding makes flag lists readable at month nine and lets the cleanup playbook tell what is safe to remove. This reference documents the conventions, shows worked examples, and provides the migration plan for existing badly-named flags. + +--- + +## The format + +`<type>_<owner>_<semantic_name>_<version_or_date>` + +Each segment is mandatory for new flags except the version/date suffix, which is recommended but optional for short-lived release flags. + +--- + +## Typed prefixes + +| Prefix | Type | Lifetime | Example | +|---|---|---|---| +| `release_` | Release flag | Days to weeks | `release_checkout_redesign_2026q2` | +| `exp_` | Experiment flag | 1-6 weeks | `exp_billing_pricing_v2` | +| `ops_` | Operational flag | Long-lived | `ops_search_circuit_breaker` | +| `perm_` | Permission flag | Long-lived | `perm_enterprise_audit_log` | +| `cfg_` | Configuration flag | Long-lived | `cfg_tenant_acme_custom_dashboard` | + +Pick one prefix style organization-wide. Mixing `release_` with `release-` produces typo bugs that bite during 3 AM rollbacks. + +--- + +## Owner prefix + +The owner segment is the team or component that owns the code behind the flag. It does not have to be the team that created the flag. + +Examples: +- `checkout` for the checkout team +- `billing` for the billing team +- `search` for the search team +- `growth` for the growth team +- `infra` for platform/SRE work + +Organizations with many small teams may use a two-segment owner like `growth_signup` or `infra_db_failover`. Organizations with a single product team may use a component-level owner like `pricing`, `dashboard`, `api`. + +--- + +## Semantic name + +The semantic name describes what the flag controls. It should read naturally to someone who has not seen the flag before. + +Good semantic names: +- `redesign` (the team is redesigning a surface) +- `ml_recommendations` (the feature is ML-driven recommendations) +- `circuit_breaker` (the flag is a circuit breaker, an operational kill switch) +- `audit_log` (the feature behind the flag is an audit log) +- `single_step_billing` (a specific UX pattern the flag controls) + +Bad semantic names: +- `new_feature` (which feature?) +- `temp_toggle` (temporary for what?) +- `test_flag` (for testing what?) +- `pricing_update_v3` (which version was v3? was there a v2?) + +--- + +## Version or date suffix + +For experiment flags and release flags that may iterate, include a version or date suffix so old and new variants are distinguishable. + +- `release_checkout_redesign_2026q2`: quarter-stamped release +- `exp_pricing_test_v2`: second iteration of a pricing test +- `release_signup_form_v3_2026_05`: third iteration, May 2026 + +Operational, permission, and configuration flags usually do not need a version suffix; they are stable infrastructure. + +--- + +## Worked examples (good) + +``` +release_checkout_redesign_2026q2 +release_signup_passwordless_2026_06 +exp_billing_pricing_v2 +exp_homepage_hero_copy_test_v1 +ops_search_circuit_breaker +ops_db_failover_manual_override +perm_enterprise_audit_log +perm_eu_data_residency +cfg_tenant_acme_custom_dashboard +cfg_white_label_partner_xyz +``` + +Each name says: what type of flag, who owns it, what it controls, and (where applicable) which iteration. + +--- + +## Worked examples (bad) + +``` +new_pricing // bad: no type, no owner, no version +temp_homepage_test // bad: "temp" promises removal that never happens +billing_flag_2 // bad: vague semantic, what does flag_2 do? +killswitch // bad: which feature does this kill? +enterprise_features // bad: ambiguous, is this permission or configuration? +beta_users_only // bad: targeting concept in the flag name; rule should target, not name +``` + +--- + +## Migration plan for badly-named flags + +If the existing platform has hundreds of badly-named flags, do not rename them all at once. The pattern is to rename on touch: + +1. Establish the convention. Document it; share with the team. +2. New flags follow the convention. No exceptions. +3. Existing flags get renamed when touched: when the rule changes, when the rollout advances, when ownership transfers, when removal is scheduled. +4. Quarterly cleanup includes a "rename batch" of the 5-10 worst-named flags, especially ones that are confusing during the cleanup itself. +5. After 6-12 months, the platform stabilizes on the convention. + +Bulk renames can be scripted via the platform's API, but renaming forces a code change in every place the flag key is referenced. Bundle renames with refactors, not as standalone PRs. + +--- + +## Anti-pattern: targeting in the name + +Do not put targeting concepts in the flag name. The flag name describes what the flag controls; the targeting rule describes who sees it. + +Bad: `enterprise_users_audit_log` (the "enterprise_users" is targeting) +Better: `perm_audit_log` (the flag is a permission flag for the audit log; the rule targets enterprise users) + +If the targeting rule changes (audit log opens up to all paid customers), the flag does not need to be renamed. The rule does the work. diff --git a/skills/feature-flagging/references/flag-rollout-strategies.md b/skills/feature-flagging/references/flag-rollout-strategies.md new file mode 100644 index 0000000..3b13fdc --- /dev/null +++ b/skills/feature-flagging/references/flag-rollout-strategies.md @@ -0,0 +1,150 @@ +# Flag rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile of the change. The five patterns below cover most cases; combine them when needed. + +--- + +## Percentage rollout + +The default for release flags. The flag advances through fixed percentage steps with a monitoring gate at each step. + +Typical sequence: + +| Step | Percentage | Hold time | +|---|---|---| +| 1 | 1% | At least one peak hour | +| 2 | 10% | At least 24 hours | +| 3 | 50% | At least 48 hours | +| 4 | 100% | Hold for 7 days before declaring complete | + +Hold times are minimums. If the metric being watched takes longer than 24 hours to stabilize (retention, downstream conversion), extend the holds accordingly. + +Abort criteria at each step: +- Error rate exceeds baseline by 10 percent. +- Latency p95 exceeds baseline by 20 percent. +- Primary success metric trends materially negative. +- Any P1 alert fires that traces back to the flag. + +If any abort criterion fires, hold or roll back. Do not advance. + +--- + +## Cohort rollout + +For risky launches where the blast radius matters. Each cohort is a named segment; the flag advances through cohorts in sequence. + +Typical sequence: + +1. Internal employees only. Bugs surface from the team that can fix them quickly. +2. Beta customers (opt-in). Engaged users who tolerate roughness in exchange for early access. +3. Free-tier customers. Larger population; risk to revenue is bounded because they are unpaid. +4. Paid customers, smaller plans first. Tier-by-tier escalation. +5. Paid customers, enterprise. Last; highest revenue impact, lowest tolerance for issues. + +Each cohort hold is at least one full business cycle (5-7 days). Compress only with strong upstream confidence (the change has already shipped through internal and beta with zero issues). + +Abort criteria same as percentage rollout, plus: support ticket volume from the cohort exceeds baseline. + +--- + +## Geo-staged rollout + +Default for compliance-sensitive features (data residency, region-specific regulations, locale-specific UX). One region at a time. + +Typical sequence: + +1. Single test region (often the team's home region; US-East or EU-West for most products). +2. English-speaking regions (US, CA, UK, AU, NZ). +3. Western Europe (DE, FR, ES, IT, NL, etc.). +4. APAC (JP, SG, AU, etc.). +5. LATAM and remaining regions. + +Hold per region depends on the product. For compliance features, hold long enough to detect any regulatory complaint or support escalation; for UX features, one full business cycle suffices. + +Abort criteria same as cohort, plus: any region-specific regulatory escalation. Compliance issues are non-negotiable rollback triggers. + +--- + +## Time-based rollout + +Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment (a press release, a partner co-launch, a planned downtime window). + +Pattern: + +1. The flag has a `time > $LAUNCH_TIMESTAMP` condition. +2. Internal QA confirms the timestamp is correct in the platform UI. +3. The launch hour arrives; the flag flips automatically. +4. The team monitors the same metrics as a percentage rollout but at the full population from minute one. + +Watch the timezone. Coordinate the timestamp explicitly: midnight Eastern is not midnight UTC; "Friday at 9 AM" is ambiguous across timezones. Use UTC in the rule and let the platform UI display in the user's local time. + +Avoid time-based rollouts: +- On weekends, unless weekend on-call exists. +- On major holidays, unless the launch is the holiday itself (rare). +- Overlapping with other major launches or known marketing campaigns; the metrics get confounded. + +--- + +## Combination strategies + +The strategies above compose. Common combinations: + +**Percentage within cohort.** "Roll out to 50 percent of beta customers, then ramp to 100 percent of beta, then start the cohort rollout to free tier." Useful when the blast radius matters even within a single cohort. + +**Geo within percentage.** "Roll out to 1 percent of users in US-East only, then 10 percent of US-East, then expand to other regions." Useful when geo isolation is important for incident containment. + +**Time-based gated by cohort.** "At time T, the flag turns on, but only for the beta cohort. The rollout to other cohorts happens later." Useful when the public announcement matters but the broader rollout should still be cautious. + +--- + +## Worked example: checkout redesign launch + +A team is launching a redesigned checkout flow. The change is high-risk (revenue surface, complex code, third-party payment integrations). + +Rollout plan: + +| Day | Stage | Rule | Hold | Watch | +|---|---|---|---|---| +| 1 | Internal | `user.email_domain == "yourcompany.com"` | 24 hours | Bug reports from team | +| 2-4 | Internal extended | Same | 72 hours | Conversion, error rate | +| 5 | Beta | `user.beta_opted_in == true` | 24 hours | Conversion, error rate, support | +| 6-8 | Beta extended | Same | 72 hours | Conversion, primary funnel metrics | +| 9 | Production 1% | `rollout 1% of all users` | 24 hours (must include peak) | Full alerting | +| 10 | Production 10% | `rollout 10%` | 24 hours | Full alerting | +| 11 | Production 50% | `rollout 50%` | 48 hours | Full alerting | +| 13 | Production 100% | `rollout 100%` | 7 days | Full alerting | +| 20 | Launch declared complete | Same rule | n/a | 30-day review scheduled | +| 50 | 30-day review | Same rule | n/a | Decide on flag removal | +| 60-80 | Flag removal PR | Code path consolidated | n/a | n/a | + +Abort criteria at every stage: +- Checkout completion rate drops more than 1 percent absolute. +- Payment failure rate increases at all. +- Error rate (any 5xx) increases by more than 10 percent. +- Support ticket volume on checkout increases. + +Total time from launch to flag-removed: about 80 days. The work to remove the flag at day 60-80 is part of the launch plan, not an afterthought. + +--- + +## When to compress + +The cadences above are conservative defaults. Compress only with strong upstream confidence: + +- The change has already shipped behind a feature flag for an extended period (release-as-experiment-as-release). +- The blast radius is genuinely small (an internal admin tool, a low-traffic settings page). +- A previous similar launch went through the full cadence with zero issues, and the new launch is structurally analogous. + +Even with strong confidence, do not skip the production 1 percent stage. The first 1 percent in production is the only stage where production-specific issues (real user agents, real network conditions, real account distributions) surface. + +--- + +## When to extend + +Extend the cadence when: + +- The metric being watched is slow (retention measured at day-7 or day-30 cannot be observed at a 24-hour hold). +- The change involves a third party (payment processor, email provider, analytics vendor) whose behavior under load is unknown. +- The team is new to flag rollouts and benefits from the slower pace as a learning exercise. + +Extension is cheaper than incident response. Conservative defaults are correct defaults. diff --git a/skills/feature-flagging/references/flag-types-reference.md b/skills/feature-flagging/references/flag-types-reference.md new file mode 100644 index 0000000..f0a1325 --- /dev/null +++ b/skills/feature-flagging/references/flag-types-reference.md @@ -0,0 +1,83 @@ +# Flag types reference + +The five flag types in detail. Mixing them in one flag is the most common source of flag mess; commit at creation and do not let the type drift. + +--- + +## Release flag + +**Definition.** A flag that gates a new feature so the code can ship to production while disabled. The team toggles it on for a percentage, ramps to 100, then removes the flag. + +**Lifetime.** Days to weeks. Most release flags should be removed within 30 days of reaching 100 percent rollout. + +**Lifecycle pattern.** Birth (PR adds gated code), adolescence (testing in dev/staging), launch (gradual percentage ramp in production), maturity (100 percent, monitor for 30 days), death (removal PR consolidates code paths). + +**Worked example.** `release_checkout_redesign_2026q2` gates a new checkout flow. Created when the new flow PR merges. Toggled on for 1 percent of users on day 1; ramps to 10 percent on day 2, 50 percent on day 4, 100 percent on day 6. Removed on day 36 after the 30-day review confirms no regressions. + +**Common pitfalls.** Skipping the removal step (the most common). Conflating with an experiment flag (the team wants to A/B test the rollout instead of just ramping it; that is a different type). Leaving the flag at 50 percent forever because the team is "watching" it (either ramp to 100 or roll back; do not park). + +--- + +## Experiment flag + +**Definition.** A flag that randomly assigns users to variants for an A/B or multivariate test. The platform tracks conversion per variant; the team decides which variant wins, then ships the winner. + +**Lifetime.** One to six weeks. Tied to the duration of the test. + +**Lifecycle pattern.** Birth (PR adds the variants behind the flag), adolescence (canary in dev/staging), launch (test runs at the full target audience), maturity (test ends, decision made), death (winning variant code consolidated; flag removed). + +**Worked example.** `exp_billing_pricing_v2` tests two pricing page layouts. 50/50 split. Test runs for 21 days, hits the pre-committed sample size. Variant B wins. The PR removes the flag and the variant A code path; only variant B remains in production. + +**Common pitfalls.** Letting the experiment flag persist after the decision (the most common). Treating an inconclusive result as "let's keep the test running" instead of "kill or redesign." Mixing experiment with release: the team uses an experiment flag to gradually ramp a feature; if it is a ramp, it is a release flag. + +--- + +## Operational flag + +**Definition.** A kill switch or circuit breaker. Lets ops disable a misbehaving feature without a code redeploy. The flag is on by default in production; flipped off only during incidents. + +**Lifetime.** Long-lived. Often years. Removed only when the underlying feature is removed. + +**Lifecycle pattern.** Birth (PR adds the kill switch around a risk surface), maturity (the flag sits at "on" indefinitely), occasional use during incidents. + +**Worked example.** `ops_search_circuit_breaker` wraps the search service. If the search service starts returning errors at high rates during a 3 AM incident, on-call flips the flag off, and the search bar shows a graceful fallback message until the underlying issue is fixed. + +**Common pitfalls.** No incident drill (the first time the kill switch is used should not be at 3 AM). Wrapping logic that does not need a kill switch (every feature does not need one; pick the high-risk surfaces). Conflating with a release flag (the team uses the kill switch as a rollout control; if it is a ramp, the new code path needs its own release flag, and the kill switch wraps the larger feature). + +--- + +## Permission flag + +**Definition.** Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. The flag is the access control mechanism. + +**Lifetime.** Long-lived. Tied to the business model. + +**Lifecycle pattern.** Birth (PR adds the gate around a paid feature), maturity (the flag stays in production indefinitely), evolution (the rule changes as plans evolve, but the flag remains). + +**Worked example.** `perm_enterprise_audit_log` controls access to the audit log feature. Only accounts on the enterprise plan see it. When the plan structure changes (audit log opens up to the team plan too), the rule changes; the flag remains. + +**Common pitfalls.** Putting permission logic in code instead of in the flag (so the team has to deploy when plans change). Conflating with configuration: permission flags govern access by plan/role; configuration flags govern behavior per tenant contract. Permission flags use the same evaluation surface as release flags but the lifecycle is fundamentally different. + +--- + +## Configuration flag + +**Definition.** Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account, partner integrations. + +**Lifetime.** Long-lived. Tied to the contract or regulatory requirement. + +**Lifecycle pattern.** Birth (PR adds the configuration switch for a specific tenant or partner), maturity (the flag remains as long as the contract is active), evolution (the rule changes as new tenants come on or existing ones renegotiate). + +**Worked example.** `cfg_tenant_acme_custom_dashboard` enables a custom dashboard for Acme Corp because their contract specifies it. The flag's targeting rule is `account.tenant_id == "acme"`. The flag remains in production as long as Acme is a customer. + +**Common pitfalls.** Configuration sprawl: every tenant request becomes a new flag, the platform has hundreds, no one can audit. Mitigation: use segments and tenant-attribute targeting on a smaller set of feature flags rather than per-tenant flags. Conflating with permission: configuration governs custom behavior per tenant contract; permission governs access by plan tier. + +--- + +## Anti-pattern: type drift + +A flag created as a release flag gets repurposed as an experiment, then later as a permission gate. The name still says `release_`. The targeting rule is now multi-purpose. The lifecycle expectation is unclear. Removing the flag breaks something somewhere. + +The fix is to refuse type drift. When the purpose changes, create a new flag of the new type and migrate the rule. The original flag is removed once nothing depends on it. This is more work than just changing the rule on the existing flag, but it preserves the type-clarity discipline. + +The recovery for an existing type-drifted flag: rename to one of the five types, document the current actual purpose, and treat the flag as that type from now on. The original mixed history is grandfathered; the going-forward behavior is single-typed. diff --git a/skills/feature-flagging/references/governance-and-permissions.md b/skills/feature-flagging/references/governance-and-permissions.md new file mode 100644 index 0000000..a56582d --- /dev/null +++ b/skills/feature-flagging/references/governance-and-permissions.md @@ -0,0 +1,115 @@ +# Governance and permissions + +Different roles need different access to the flag system. Engineering needs broad ability to create flags. Product needs to author targeting rules in dev and staging. Production targeting changes deserve a smaller approver pool. The pattern below balances access with audit. + +--- + +## Permission tiers + +Four tiers cover most cases. Not every organization needs all four. + +| Tier | Scope | Typical members | +|---|---|---| +| Viewer | Read-only across all environments | Most of engineering, product, support, finance, executive | +| Editor | Create and modify flags in dev and staging | The team that owns the flag's surface | +| Approver | Promote flag changes from staging to production | Team lead, on-call engineer, designated approvers | +| Admin | Delete flags, modify permissions, access audit logs | Platform team plus a backup | + +Smaller organizations may collapse Editor and Approver into a single "Engineer" tier. Larger organizations may add a fifth tier ("Owner") for cross-cutting governance. + +--- + +## Environment-based permissions + +Permissions vary by environment. The same person can have Editor in dev/staging and Viewer in production. The environment-based scope is the second axis after role. + +| Environment | Default access | Notes | +|---|---|---| +| Dev | Editor for engineering, Viewer for everyone else | Sandbox; mistakes are cheap | +| Staging | Editor for the owning team, Viewer for everyone else | Pre-production; mistakes are detectable | +| Production | Approver for the owning team, Viewer for everyone else | Live; mistakes are expensive | + +Production changes go through review like deploys. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review. The rule does not silently appear in production because someone clicked a button. + +--- + +## Approval workflow + +For production-impacting changes: + +1. Editor authors the change in staging. +2. Editor tests the change in staging (the rule applies, the metric moves as expected). +3. Editor opens a change request in the platform (most platforms have a built-in change-request workflow; if not, a Slack channel with a bot suffices). +4. The request includes: rule diff, rollout plan, abort criteria, link to relevant ticket/PR, link to staging test results. +5. An approver reviews. If clean, applies. If not, comments and the editor revises. +6. The change applies in production with the audit trail attached. + +For low-risk operational changes (a kill switch flip during an incident), the workflow can be compressed: the approver applies directly without a separate change request, and the audit trail captures the change with the incident reference. Document this exception explicitly so emergencies do not produce unexplained audit entries. + +--- + +## Audit trail + +Every flag change must be logged with: + +- Actor (who applied it, by user identity). +- Timestamp. +- Before-state and after-state (the rule diff). +- Reason (free-text or linked ticket). + +Most platforms do this automatically. Configure the audit log to also write to the central log aggregator (Datadog, Splunk, ELK, the team's choice). The platform's audit log is fine for routine inspection; the centralized log is where investigation happens during incidents. + +Audit retention: at least one year. Two years for organizations with regulatory obligations. + +--- + +## Emergency override + +An emergency override is the path that lets on-call flip a kill switch at 3 AM without going through the standard approval workflow. + +The pattern: + +1. A small group has Approver permission on the operational kill switches specifically. +2. The group includes the on-call rotation; on-call inherits Approver for the duration of their shift. +3. Emergency overrides apply with the standard audit trail; the reason field includes the incident reference. +4. After the incident, the override is reviewed in the post-mortem. + +Test the override in incident drills. The first time on-call flips a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. If the drill reveals the override path is broken (the on-call's account does not have the right permission, the platform's UI is confusing, the mobile app does not let you change rules), fix it immediately. + +--- + +## Service accounts + +Automation needs flag access too. CI/CD pipelines may flip flags as part of deploys; monitoring systems may flip kill switches based on alerts; orchestration agents may modify flags via MCP. + +Service accounts: + +- Each automation has its own service account with a clearly named identity (`ci_pipeline`, `monitoring_alert_bot`, `agent_orchestrator`). +- Service accounts have the minimum permission needed for their scope. The CI account that flips release flags after deploy does not need permission to delete flags. +- Service account credentials rotate on a schedule (90 days for production access). +- Audit log entries from service accounts are clearly marked so they can be filtered separately from human changes. + +Mixing human and service-account credentials in the same identity is the most common audit-trail mistake. The investigation question "who changed this flag at 2 AM" should not have the answer "an automation, but we are not sure which one because it was authenticated as a human admin." + +--- + +## The "production console freeze" anti-pattern + +Some organizations respond to a production flag incident by tightening access so much that every flag change requires a ticket, a meeting, and a 24-hour delay. The result is over-correction: routine flag changes get queued, the team starts authoring rules in code instead of in the platform, and the platform stops being load-bearing. + +The fix is not to freeze access. The fix is to: + +- Tighten the approval workflow (require change requests for production). +- Tighten the audit log (capture every change with reason). +- Tighten the emergency override (drill it). +- Loosen the day-to-day workflow so editors can do their jobs without paperwork. + +Bureaucracy substitutes for trust. Trust is built via the audit log and the approval workflow. Once the audit log is solid, day-to-day editing can stay fast. + +--- + +## Cross-team coordination + +When a flag's surface overlaps with another team's work, coordinate before the change. The experiment registry pattern from the `experiment-design` skill applies here too: maintain a shared list (in the platform, in a wiki, in a shared doc) of flags currently being modified or rolled out per surface. Before launching a flag rollout, check the registry for conflicts. + +Cross-team coordination does not have to be heavy. A 5-minute Slack check ("we're rolling out flag X on the checkout flow tomorrow at 1 PM, anyone working on adjacent flags?") is enough for most cases. The cost of skipping the check is the cross-team conflict scenario from the [SKILL.md](../SKILL.md), where two flags interact and produce broken UI. diff --git a/skills/feature-flagging/references/stale-flag-cleanup-playbook.md b/skills/feature-flagging/references/stale-flag-cleanup-playbook.md new file mode 100644 index 0000000..a4e2670 --- /dev/null +++ b/skills/feature-flagging/references/stale-flag-cleanup-playbook.md @@ -0,0 +1,116 @@ +# Stale flag cleanup playbook + +A quarterly cadence for keeping the flag inventory healthy. Without it, dead flags compound: every quarter adds 20-50 release/experiment flags that never got removed, and after two years the platform has hundreds of dead entries that nobody can confidently delete. + +The playbook is mechanical. Run it every quarter, the same way. Resist the urge to skip a quarter because the platform "looks fine." + +--- + +## What counts as stale + +| Flag type | Stale threshold | +|---|---| +| Release | 30 days without evaluation | +| Experiment | 30 days without evaluation | +| Operational | 90 days without evaluation | +| Permission | Annual review; not "stale" by evaluation count | +| Configuration | Annual review; tied to contract status | + +Most platforms expose a "stale flag" report or a "last evaluated" timestamp per flag. If yours does not, the SDK can be configured to emit evaluation events to an analytics destination, and the analytics database becomes the source of truth. + +--- + +## Quarterly process + +### Step 1: Generate the report + +Pull the stale flag list from the platform. Filter by type-specific threshold above. Output: a list of flags with last-evaluation timestamp, owner, type, current rule. + +### Step 2: Owner triage + +For each flag in the list, route to the owner. The owner has three options per flag: + +- **Remove.** The flag is dead. Open a code-side removal PR. +- **Keep.** The flag is still load-bearing for a real reason (operational kill switch that has not fired in 90 days but should remain; permission flag for a feature whose rule is being audited annually). Document the reason; remove from this quarter's list. +- **Investigate.** The owner does not know why the flag exists or what it controls. Spawn a sub-task to investigate; the flag stays in next quarter's list. + +If a flag has no owner (the original owner left, ownership was never assigned, the flag predates the convention), rotate to the platform/SRE team for a forced decision in step 3. + +### Step 3: Triage meeting + +A 30-minute meeting per quarter. Attendees: representative from each team that owns flags, the platform/SRE team, the engineering lead. + +Walk the list. For each flag: + +- Confirm the owner's recommendation. +- For "investigate" flags, decide a deadline: investigation completes by next month or the flag is force-removed. +- For orphan flags (no owner, force-routed to platform), the platform team makes the call: remove if there is no evidence of active use, keep with documentation if there is. + +The meeting produces three artifacts: a remove list, a keep list with reasons, an investigate list with deadlines. + +### Step 4: Removal PRs + +One PR per flag. Bundle is tempting; resist it. One-flag-per-PR has three advantages: + +1. The reviewer can confirm the flag is genuinely dead by inspecting only the removed code paths. +2. If a flag was not actually dead (a code path uses it that the search missed), the rollback is a single revert. +3. The PR title and description reference the specific flag, which produces a clean audit trail. + +Each PR: + +- Removes the flag's evaluation calls from code. +- Consolidates the gated branches: usually keeps the "on" branch as permanent code and deletes the "off" branch. +- Removes any tests that targeted only the removed branch. +- Updates documentation that referenced the flag. + +### Step 5: Platform deletion + +After the removal PR merges and ships: + +- Wait 24 hours for the new code to fully roll out. +- Confirm the platform shows zero evaluations of the flag for the full 24-hour window. +- Archive or delete the flag from the platform. +- Audit log entry confirms deletion with actor, timestamp, reason ("quarterly cleanup, removal PR #NNNN"). + +### Step 6: Verification + +A week after platform deletion: + +- Spot-check the codebase for any remaining references to the flag's key (string-grep). Should be zero. +- Spot-check the platform for the flag's reappearance (sometimes platforms restore archived flags via API automation; rare but worth checking). + +--- + +## Orphan flags + +Orphan flags (no owner) are the hardest case. The original owner left the company, the team that owned the area dissolved, the flag predates the ownership convention. + +The pattern: + +1. Default ownership routes to the platform/SRE team. +2. The platform team asks: "Is this flag's targeting rule consistent with documented product behavior? Would removing it change observable behavior for any user?" +3. If no observable change, remove. If yes, escalate to the team most plausibly impacted. +4. If no team can be identified and no observable change is detectable, the flag is a candidate for removal in the next quarterly meeting; document the orphan status and remove on a 60-day delay so any silent dependency can be discovered. + +The 60-day delay is a hedge against unknown dependencies. In most cases, no one notices and the flag is safely removed. In the rare cases where a forgotten cron job or a downstream service was depending on the flag, the issue surfaces during the delay window. + +--- + +## Tooling + +Most platforms provide some automation: + +- LaunchDarkly: Code References finds usages in the codebase, flags candidates for removal. +- Statsig: Stale Gates report. +- GrowthBook: stale flag dashboard. +- Flagsmith: change request workflow integrates removal with governance. + +The automation reduces manual work but does not replace the triage meeting. The meeting is where humans make the keep/remove decision, which is the part automation cannot do. + +--- + +## Make removal part of the launch checklist + +The most important pattern is upstream: make flag removal part of the launch checklist, not a separate quarterly effort. When a release flag is created, the launch ticket has a sub-ticket scheduled 30 days out: "Remove flag X." When the launch goes well and the flag reaches 100 percent, the sub-ticket gets done as part of post-launch hygiene. + +Quarterly cleanup is the safety net for everything that slips past the upstream discipline. The discipline reduces the safety-net workload from "300 dead flags" to "5 dead flags," which is the difference between a 30-minute triage meeting and a multi-day project. diff --git a/skills/feature-flagging/references/targeting-rule-patterns.md b/skills/feature-flagging/references/targeting-rule-patterns.md new file mode 100644 index 0000000..edabbe0 --- /dev/null +++ b/skills/feature-flagging/references/targeting-rule-patterns.md @@ -0,0 +1,183 @@ +# Targeting rule patterns + +Common patterns and anti-patterns for flag targeting rules. The patterns work; the anti-patterns produce flag mess that takes quarters to unwind. + +--- + +## Pattern: percentage rollout + +Default: flag off (0 percent). Override: flag on for a percentage of the user population. + +``` +Default rule: off +Override: rollout 10% of all users +``` + +The platform handles the bucketing (usually a stable hash on user ID, so the same user gets the same value across requests). Use this for release flags during ramps. + +Variation: percentage within a segment. `Default off; rollout 50% of users where account.tier == "enterprise"`. Useful when the rollout should reach only a subset of the population. + +--- + +## Pattern: internal-only + +Restrict the flag to internal employees first. The flag is on for `@yourcompany.com` emails; everyone else sees the disabled state. + +``` +Default rule: off +Override: on if user.email_domain == "yourcompany.com" +``` + +Use this for the first stage of a sensitive release. Internal users find bugs without external exposure. + +--- + +## Pattern: opt-in beta + +Users who have opted into beta features see the flag on. Implementation requires an opt-in mechanism somewhere in the product (settings page, signup flow, support request). + +``` +Default rule: off +Override: on if user.beta_opted_in == true +``` + +Use this for risky features that need engaged-user feedback. The opt-in is the consent mechanism; the flag is the access mechanism. + +--- + +## Pattern: cohort-based + +Target a named segment defined elsewhere in the platform. The segment captures the cohort logic so the flag rule stays simple. + +``` +Default rule: off +Override: on if user IN segment "early_access_2026q2" +``` + +Use this when the cohort is shared across multiple flags (the same set of "early access" users sees several features). The segment is the single source of truth; flags reference it. + +--- + +## Pattern: geo-staged + +Target users by region. The country or region attribute usually comes from the request (IP-based geolocation) or the account profile. + +``` +Default rule: off +Override: on if request.country IN ("US", "CA") +``` + +Use this for compliance launches (data residency regulations, region-specific UX). Stage the rollout: US first, then EU, then APAC. + +--- + +## Pattern: time-based scheduled flip + +The flag turns on at a specific time. Useful for marketing-coordinated launches. + +``` +Default rule: off +Override: on if time > "2026-06-01T12:00:00Z" +``` + +Watch the timezone. Avoid scheduling on weekends or holidays unless on-call coverage exists for the rollout window. + +--- + +## Pattern: composition (cohort within percentage) + +A percentage of a cohort. Useful when the rollout should be slow even within an opt-in group. + +``` +Default rule: off +Override: on if user.beta_opted_in == true AND rollout 25% of those users +``` + +Order matters: the percentage applies to the cohort, not the full population. The platform's rule editor usually makes this clear. + +--- + +## Anti-pattern: volatile-attribute targeting + +Targeting on attributes that change frequently produces user-experience whiplash. + +Bad: +``` +Override: on if user.last_login_date > "2026-04-01" +``` + +A user's last_login_date changes every time they log in. They see the treatment one day, the control the next. The experience flickers; conversion data is noise. + +Fix: target on stable attributes. Or, snapshot the attribute at a fixed point (`user.first_login_date_was_after_2026_04_01`) and use the snapshot. + +--- + +## Anti-pattern: deeply nested AND/OR + +If your rule has three levels of nesting, the taxonomy is wrong. + +Bad: +``` +Override: on if ( + (user.country == "US" AND user.signup_date > "2026-01-01") + OR + (account.tier == "enterprise" AND NOT user.churned) + OR + (user.beta_opted_in == true AND request.device == "mobile") +) +``` + +The intent is unclear, the rule is fragile, and reviewing it during incidents is slow. + +Fix: define a segment that captures the intent (e.g., "eligible_for_new_dashboard") and use the segment in the flag rule. Or split into multiple flags (one for the US/recent-signup case, one for the enterprise case, one for the mobile-beta case) and let the calling code combine them. + +--- + +## Anti-pattern: production rules drift from staging + +The team tests the flag in staging with rule X. The rule that ships in production is rule Y, written directly in the production console without re-testing in staging. + +Result: the staging tests do not predict production behavior. The first 1 percent rollout in production reveals the gap, and the team scrambles to align. + +Fix: rules go through environment promotion. Author in staging, test in staging, promote to production via the platform's promotion workflow. If the platform does not have promotion, copy the rule from staging to production via a documented process and confirm the rule is identical in both before flipping production on. + +--- + +## Anti-pattern: targeting in the flag name + +Bad: `flag_name = "enterprise_audit_log"` with rule `account.tier == "enterprise"`. + +When the rule changes (audit log opens up to team-tier accounts), the flag name lies. + +Fix: name the flag for what it controls (`perm_audit_log`), let the rule do the targeting work. The rule can change without renaming the flag. + +--- + +## Anti-pattern: kill switch with a complex rule + +A kill switch (operational flag) should have a simple rule: `on for everyone` or `off for everyone`. If your kill switch's rule is `on for everyone except a specific cohort with these conditions`, you are using an operational flag as a permission gate. + +Fix: use a permission flag for the per-cohort access; use a separate operational flag (`ops_feature_x_killswitch`) for the universal kill. The operational flag wraps the entire feature; the permission flag wraps the access to the feature. + +--- + +## Pattern: explicit ramp gate + +Some platforms let you tag a flag's rule with explicit "stages." The flag advances through stages on a button press, with each stage having its own rule. + +``` +Stage 1: rollout 1% +Stage 2: rollout 10% (advance from stage 1 manually) +Stage 3: rollout 50% (advance from stage 2 manually) +Stage 4: rollout 100% (advance from stage 3 manually) +``` + +Use this when the platform supports it. The explicit stages make rollout history readable: you can see when each stage advanced, by whom, with what observed metrics. + +--- + +## Composition rule of thumb + +If a flag's rule reads naturally to a non-engineer ("on for enterprise customers in the US"), the rule is simple enough. If the rule requires a five-minute explanation, it is too complex; refactor into segments or split into multiple flags. + +The rule is read more times than it is written. Optimize for readability. diff --git a/skills/feature-launch-playbook/SKILL.md b/skills/feature-launch-playbook/SKILL.md new file mode 100644 index 0000000..119e651 --- /dev/null +++ b/skills/feature-launch-playbook/SKILL.md @@ -0,0 +1,340 @@ +--- +name: feature-launch-playbook +description: "The operational playbook for launching a feature well. Positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring with pre-defined rollback triggers, post-launch measurement against spec hypotheses, and the discipline that distinguishes shipping from releasing from actually launching. Triggers on launch plan, feature launch, launch checklist, ship vs release, rollout strategy, gradual rollout, sales enablement, support readiness, launch announcement, post-launch measurement, launch failure, declared victory too early. Also triggers when planning a launch (any size, any segment), auditing an existing launch process, fixing the we shipped it but the metric did not move problem, or building a launch checklist for the team." +category: product +catalog_summary: "The operational discipline of launching a feature well: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement" +display_order: 10 +--- + +# Feature Launch Playbook + +A veteran PM-leader's playbook for launching features well, not just shipping them. + +Most teams conflate shipping, releasing, and launching. Shipping means engineering work is complete. Releasing means users can access it, even if it is behind a flag at 1 percent. Launching is the discipline of positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement that turns "feature exists" into "feature lands." + +A feature that ships without launching costs you the same engineering investment but captures a fraction of the value. Sales does not know how to sell it. Support does not know how to help with it. Customers do not notice it. The metric you said you would move does not move because nobody knows the feature is there. + +This skill is the operational playbook. It assumes you have already written the spec (`pm-spec-writing`), prioritized it onto the roadmap (`roadmap-planning`), instrumented it (`product-analytics-setup`), and possibly tested it (`experiment-design`). The launch is the next discipline: how to actually get the feature in front of the right users, with the right context, in a way that lets you measure whether it worked. + +When to use this skill: planning a launch (any size, any segment), auditing an existing launch process, fixing the "we shipped it but the metric did not move" problem, or building a launch checklist for the team. + +--- + +## What this skill is for + +This skill spans the operational launch discipline. It composes with the rest of the Product skill suite. + +- `pm-spec-writing` defines the launch hypotheses; this skill validates them. +- `roadmap-planning` provides the launch context (what came before, what comes next). +- `product-analytics-setup` is the instrumentation prerequisite; without it you cannot measure the launch. +- `experiment-design` and `data-warehouse-experimentation` provide the methodology for testing whether the launch worked. +- `feature-flagging` provides the rollout infrastructure this skill depends on. + +This skill does not cover pricing decisions, brand campaigns, or full GTM strategy. Those need a marketing team partner; this is the PM operational playbook for the engineering and product side. + +The audience is broad: every PM ships features, every PM has launched poorly at least once, every PM benefits from a checklist that stops the worst failure modes from recurring. The voice is veteran PM-leader to PM. Specific, opinionated, honest about what discipline matters at what stage. + +--- + +## Ship vs release vs launch + +The keystone distinction. Three definitions. + +**Shipping** means engineering completes the work. Code is on production. No users can access it yet, or only internal users via a flag. The PR is merged and deployed. + +**Releasing** means users can access it. Could be 1 percent rollout, could be 100 percent. The feature is "live" in some technical sense. The flag is on for at least one user. + +**Launching** means positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement are all in flight. The feature has been introduced to the people who would benefit from it, with the context they need to use it. + +The pathology. PMs report "we shipped feature X" when what happened is engineering completed the work. The feature might be released to 1 percent of users with no announcement, no documentation, no sales enablement, no measurement plan. From a value-capture perspective, that is an unlaunched feature. + +The discipline. Use precise vocabulary. "Engineering shipped on Tuesday. We are releasing to 25 percent on Thursday. We are launching publicly next month." The vocabulary forces honest accounting of what has and has not happened. + +Most "feature failed" diagnoses turn out to be "feature was unlaunched." This skill is structured around the launch dimension because that is where most teams under-invest. + +--- + +## Launch tiers + +Not every feature needs the full playbook. Match the work to the feature. + +**Tier 1 (full launch).** Net-new product, major feature reshaping the product narrative, pricing change, breaking change. Full playbook: positioning, all comms channels, sales enablement, customer success briefing, dedicated post-launch measurement, executive announcement. + +**Tier 2 (focused launch).** Meaningful improvement that materially affects user value or competitive positioning. Subset of the playbook: in-app comms, blog post or release note, support readiness, rollout strategy, post-launch measurement. + +**Tier 3 (release note).** Incremental improvement, bug fix made positive, polish. Minimal: changelog entry, release note, light monitoring. + +The trap on either side. + +- Treating every release as Tier 1 produces comms fatigue. Customers tune out the announcement firehose; your real Tier 1 launches lose signal in the noise. +- Treating every release as Tier 3 produces unlaunched features. The feature ships, the metric does not move, the team concludes "users do not want this" when the actual cause is "users were not told." + +Match the tier to the feature. This skill primarily covers Tier 1 and Tier 2. Tier 3 is mostly the changelog discipline; the launch playbook applies but compressed to the changelog entry plus light monitoring. + +Detail in [`references/launch-tier-decision.md`](references/launch-tier-decision.md). + +--- + +## Pre-launch: positioning + +Positioning answers: who is this for, what problem does it solve, why now, and what is the user-visible promise. + +The positioning canvas. One page, filled out before any comms drafting. + +- **Target user.** Segment, role, jobs-to-be-done. Specific enough that a sales rep could describe the customer profile in one sentence. +- **Problem it solves.** Specifically, in user words. Not "we improve productivity"; instead "the customer support manager who needs to triage 200 tickets a day cannot tell which are urgent without opening each one." +- **Current alternative.** What users do today without this. The status quo is the real competition. +- **User-visible promise.** One sentence. The promise the user will hear when they encounter the feature in the wild. +- **Proof points.** Three to five specific capabilities or outcomes. Concrete, not adjectives. +- **Anti-positioning.** What this is NOT, what it does not try to do. Prevents over-promising. + +The most common positioning failure is a vague target user. "It is for PMs" is not a target. "It is for B2B SaaS PMs at companies with 50 to 500 customers who need to coordinate roadmap discussions across engineering and customer success" is a target. The specificity is what lets sales, marketing, and support speak the same language about who this is for. + +Detail in [`references/positioning-canvas.md`](references/positioning-canvas.md). + +--- + +## Pre-launch: internal alignment + +Stakeholders who need to know before launch. + +- **Engineering leadership.** Capacity for follow-ups, support escalations, post-launch fixes. +- **Sales leadership.** Revenue forecast updates, deal coaching, pipeline impact. +- **Customer success leadership.** Proactive customer notifications, deal saves at risk, expansion conversations. +- **Marketing leadership.** Paid spend coordination, blog calendar, social timing. +- **Support leadership.** Training, FAQ, escalation paths. +- **Executive sponsor.** Visibility, public messaging, investor or board reporting. + +The discipline. A single internal launch brief, distributed two to four weeks before launch (Tier 1) or one week before (Tier 2). The brief contains a one-page summary, an FAQ, a decision log of choices already made, and the launch calendar. The brief should answer "what do I need to do differently because of this launch." + +The most common internal alignment failure: launching without sales knowing. Sales finds out from a customer asking about it. Trust erodes for the next launch. The fix is the launch brief plus a sales-specific briefing one to two weeks before customer-facing launch. + +Detail in [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md). + +--- + +## Pre-launch: customer comms plan + +Channels and decision factors. + +- **In-app.** Highest reach for active users; right for product-internal features. Tooltips, banners, modals. +- **Email (transactional or campaign).** High reach across active and inactive users; right for material changes that affect existing workflows. +- **Blog post.** SEO plus lead gen plus narrative; right for Tier 1 launches with external story. +- **Release notes.** Discoverable, archived, queryable; right for every Tier 2 and above. Often the canonical reference customers find later. +- **Social (LinkedIn, X, Bluesky).** Reach beyond existing customers; right when launch has external narrative or competitive angle. +- **Webinar or customer call.** Depth for enterprise customers; right for Tier 1 with material customer impact. +- **Sales-led briefing.** High-touch for top accounts; right when launch affects pricing, contracts, or strategic positioning. + +For each channel: who drafts, who approves, what is the timing, what is the call to action. + +The comms calendar pattern. A single document with all channels and dates, distributed in the internal launch brief. Prevents the "blog post went out before sales got the briefing" failure. Ordering typically goes: sales briefing first, support training second, customer success outreach to top accounts third, public comms fourth. + +Detail in [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md). + +--- + +## Pre-launch: sales enablement (B2B) + +For B2B products, sales enablement is not optional for Tier 1 and most Tier 2 launches. The deliverables. + +- **One-page battlecard.** Positioning, target customer, top objections, proof points. Sales can read it in two minutes and pitch the feature in five. +- **Demo script and recorded demo.** A repeatable demo the rep can run with a customer; the recorded version is the fallback for reps who join after the launch. +- **Pricing change documentation** if applicable. Sales reps cannot answer pricing questions accurately without explicit guidance. +- **Deal coaching guide.** Which deals does this unblock, which does it complicate. Specific named accounts where appropriate. +- **Internal training session** live or recorded, with Q&A archived. Sales reps need the chance to ask questions before they take the feature to a customer. + +The "shadow launch" failure. Feature ships, sales hears about it from product team Slack, no battlecard, sales reps either ignore it or misrepresent it to customers. Customers churn because the feature was promised in a way that did not match reality. + +For B2C and PLG products, this section is mostly skipped. The user is the buyer; there is no sales motion. Note this explicitly so PMs in those contexts do not feel they are missing the discipline. + +Detail in [`references/sales-enablement-template.md`](references/sales-enablement-template.md). + +--- + +## Pre-launch: support readiness + +Support is often the first to encounter the failure modes of a new feature. They need. + +- **Training** live or recorded, with Q&A. The same content as the sales training adapted to support workflows. +- **FAQ document** covering known questions, known limitations, and known bugs at launch. The FAQ updates daily during the first week as new questions surface. +- **Escalation path** for issues that need engineering or PM. Named owners and turnaround time commitments. +- **Monitoring access** or a way to ask for it. Support reps should be able to verify whether a customer's issue is feature-specific. + +The discipline. The support team's confusion is the test customer's confusion. If support does not understand the feature, neither will customers. Train support before customer-facing launch comms go out. + +Detail in [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md). + +--- + +## Launch day: rollout strategy + +Four common patterns matched to feature type. + +**All-at-once (big bang).** Zero to 100 percent in a single deploy. Right for marketing-coordinated launches where the announcement IS the rollout. Risky for anything where bugs would affect a meaningful customer base. Use sparingly. + +**Gradual percentage rollout.** 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days, monitored at each step. Right for most feature launches; the default unless there is a reason to deviate. + +**Flag-gated cohort rollout.** Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Right for features with cohort-specific risk profiles. + +**Phased launch (multi-week).** Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Right for Tier 1 launches with high uncertainty about user reception. + +The decision framework. Feature blast radius times confidence in correctness times external commitments. + +- High blast radius plus low confidence plus no external commitment: phased. +- Low blast radius plus high confidence plus external launch date: all-at-once. +- The middle (most launches): gradual percentage rollout. + +Detail in [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md). + +--- + +## Launch day: monitoring + +Pre-launch, define what you will monitor and what alerts you. Common dimensions. + +- **Error rates.** Overall plus feature-specific. +- **Latency.** Overall plus feature-specific. +- **Feature usage rate.** People who SHOULD use it actually do. +- **Funnel completion.** Users complete the new flow. +- **Support ticket volume.** Especially feature-specific tags. +- **Customer satisfaction signals.** NPS comments, feedback widget mentions. + +Define the rollback trigger explicitly before launch. Examples. + +- "Error rate above 1 percent sustained for 5 minutes triggers rollback." +- "Support tickets mentioning the feature exceed 50 in the first hour triggers escalation." +- "Funnel completion drops below 50 percent of pre-launch baseline for any cohort triggers paused rollout." + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate; the rule fires automatically and the team executes the rollback. + +Detail in [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md). + +--- + +## Launch day: comms execution + +The comms calendar from the customer comms section executes on launch day. Each channel has a clear owner, a clear time, and a clear sequence. + +- In-app banner activates when rollout reaches X percent. +- Email sends after a 4-hour stability check. +- Blog post publishes at the time announced internally. +- Sales briefing happens one day before public comms. +- Support training happens one week before launch. + +The "comms misfire" failure. Blog post auto-publishes at the scheduled time, but the rollout was paused two hours earlier due to an issue. Customers click through to a feature that is behind a flag for them. They lose trust; the launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +--- + +## Post-launch: measurement against spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses about what the feature would change. The launch measurement plan validates or invalidates each. + +Four measurement dimensions. + +1. **Adoption.** Did the right users actually use it? The reach question. Is the feature visible to the target segment, and are they trying it. +2. **Engagement.** Did users who tried it come back? The stickiness question. First use is necessary but not sufficient. +3. **Outcome.** Did the metric the spec said this would move actually move? The effect question. The hypothesis the spec made. +4. **Side effects.** Did any other metric move that was not supposed to? The safety question. Sometimes the feature works but breaks something else. + +Time horizons. Most launches need two to four weeks of post-launch data for engagement signals, four to eight weeks for outcome signals. Do not declare success or failure too early. + +The "no measurement plan" failure. Feature ships; the team moves on; six months later nobody knows if it worked. The feature becomes maintenance debt; the team cannot decide whether to invest in it further. + +Detail in [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md). + +--- + +## Post-launch: iteration and follow-ups + +Within the first four weeks post-launch, expect. + +- Bug discoveries that did not surface in QA or limited rollout. +- Usability issues that did not surface in user research. +- Adoption gaps in cohorts you did not expect to under-adopt. +- Feature requests for adjacent capabilities. + +The discipline. Document every issue, triage weekly, prioritize fixes against the original measurement plan. + +If adoption is below target, the question is. Is it a marketing problem (users do not know about the feature)? A usability problem (users try the feature and bounce)? A value problem (users try the feature and do not see value)? A wrong-segment problem (the target was not who we thought)? + +Each diagnosis maps to a different fix. + +- Marketing problem: more comms, repeat comms, sales reactivation. +- Usability problem: design or onboarding fix. +- Value problem: feature redesign or repositioning. +- Wrong-segment problem: re-target the comms to a different audience. + +The "we declared victory" failure. The launch metric hits target in week 1 (often due to the launch announcement spike); the team moves on; the metric falls back to baseline by week 4. The launch was reported as successful but the feature did not actually land. + +The fix. Declare success or failure based on a stable post-launch trend, not the launch-week spike. Most launches need at least a four-week stable trend before the success or failure call is reliable. + +--- + +## Common failure modes + +Twelve patterns recur across feature launches. Detail in [`references/common-launch-failures.md`](references/common-launch-failures.md). + +- "We shipped it but nothing happened." Unlaunched. No comms plan, no internal alignment, no measurement. +- "Sales is confused and selling it wrong." No enablement. Battlecard, demo, training were skipped or rushed. +- "Support is overwhelmed." No training, no FAQ. Support is encountering the feature for the first time when customers ask. +- "We rolled out and immediately rolled back." No rollout strategy, no health check. The big-bang deploy hit production and broke. +- "The blog post went out but the feature is broken." Comms misfire. The comms were not gated on rollout health. +- "Adoption was great in week 1, now it is flat." Declared victory on the launch spike. The metric reverted to baseline. +- "We do not know if it worked." No measurement plan tied to spec hypotheses. +- "Customers say we did not tell them." Comms did not reach the right segments. Email went to active users only; inactive users were not notified. +- "Enterprise customers found out from their account manager three days late." No high-touch tier in comms. Top accounts deserve sales-led briefing before public comms. +- "Our metric moved but it was actually because of a different launch that week." No isolation. Cannot attribute the metric movement to this launch versus other concurrent changes. +- "We launched the wrong feature." Positioning unclear. Customers expected something different from what shipped; the gap between expectation and reality reads as a failed launch even though the feature works. +- "It worked but nobody knew about it internally." No internal alignment. Sales did not capitalize on the feature in deals; customer success did not save accounts that were churning over the gap this feature now closes. + +--- + +## The framework: 12 considerations for a real launch + +When planning a launch, walk these 12 considerations. Skipping any of them produces one of the failure modes above. + +1. **Tier the launch.** Tier 1, Tier 2, or Tier 3. Match the effort to the feature. +2. **Position it.** Target user, problem, promise, proof points, anti-positioning. +3. **Align internally.** Single launch brief, distributed two to four weeks before launch. +4. **Plan customer comms.** Channel mix, calendar, owners, gates. +5. **Enable sales.** Battlecard, demo, training, deal coaching (B2B only). +6. **Ready support.** Training, FAQ, escalation paths, monitoring access. +7. **Pick a rollout strategy.** All-at-once, gradual, flag-gated, or phased. +8. **Define monitoring.** Metrics, alerts, rollback triggers. Pre-defined, not in-the-moment. +9. **Sequence comms execution.** Gated on health checks. Never auto-fire if the rollout is paused. +10. **Tie measurement to spec hypotheses.** Adoption, engagement, outcome, side effects. +11. **Iterate post-launch.** Weekly triage. Distinguish marketing, usability, value, and segment problems. +12. **Declare success or failure on a stable trend.** Not the launch-week spike. + +The output of the framework is a launch plan document. The positioning canvas, the internal launch brief, the comms calendar, the rollout strategy with health-check gates, the monitoring spec with rollback triggers, and the post-launch measurement plan tied to the spec hypotheses. The plan is reviewed two weeks before launch; gaps are filled before the launch date. + +--- + +## Reference files + +- [`references/launch-tier-decision.md`](references/launch-tier-decision.md) - Tier 1, 2, 3 decision framework with worked examples. +- [`references/positioning-canvas.md`](references/positioning-canvas.md) - One-page positioning template with B2B SaaS, B2C, and developer feature examples. +- [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md) - Stakeholders, brief structure, distribution timing by tier. +- [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md) - Channels, calendar, owners, gates. +- [`references/sales-enablement-template.md`](references/sales-enablement-template.md) - Battlecard, demo, deal coaching, training (B2B). Skip note for B2C and PLG. +- [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md) - Training, FAQ, escalation, monitoring access. +- [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md) - Four patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. +- [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md) - Metrics dimensions, alert thresholds, pre-defined rollback triggers. +- [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md) - Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. +- [`references/common-launch-failures.md`](references/common-launch-failures.md) - Twelve failure patterns with diagnoses and fixes. + +--- + +## Closing: most failed launches are unlaunched + +When a feature "fails," the most common diagnosis is not that the feature was wrong. It is that the launch was incomplete. Sales did not know. Customers were not told. Support could not help. The metric did not move because the launch did not reach the people who would have moved it. + +Before declaring a feature failed, audit the launch against this playbook. Half the time the feature was fine; the launch never happened. + +The discipline of separating shipping from releasing from launching is the single most useful PM vocabulary upgrade. Use it explicitly. Use it in stand-ups, in roadmap reviews, in launch retrospectives. The team that uses precise language about what has happened catches unlaunched features before declaring them failed and reallocates the engineering investment toward features that would actually capture value. + +When in doubt about whether a launch is ready, ask: is the launch brief written and distributed? Has sales seen the battlecard? Does support have the FAQ? Is the rollout strategy chosen and the rollback trigger defined? Are the comms gated on a health check? Is the measurement plan tied to the spec hypotheses? + +If any of those answers is no, the launch is not ready. Delaying the launch by a week to close the gaps is cheaper than launching incomplete and capturing a fraction of the value the feature could have delivered. diff --git a/skills/feature-launch-playbook/references/common-launch-failures.md b/skills/feature-launch-playbook/references/common-launch-failures.md new file mode 100644 index 0000000..987206f --- /dev/null +++ b/skills/feature-launch-playbook/references/common-launch-failures.md @@ -0,0 +1,181 @@ +# Common launch failures + +Twelve patterns that recur across feature launches. For each: name, symptom, root cause, fix, prevention. Cross-references to other reference files. + +--- + +## 1. We shipped it but nothing happened + +**Symptom.** The team reports "we shipped feature X." Three weeks later, nobody is using it. The metric the spec said this would move has not moved. Internal stakeholders ask if the feature is live; nobody is sure. + +**Root cause.** Unlaunched. Engineering completed the work; the team did not execute the launch. No comms plan, no internal alignment, no measurement plan tied to spec hypotheses. + +**Fix.** Treat it as a re-launch. Audit against the playbook: positioning, internal alignment, customer comms, sales enablement, support readiness, measurement plan. Distribute the launch brief. Sequence comms. Re-measure at the four-week checkpoint. + +**Prevention.** The launch brief is the artifact that prevents this. Without a brief, the launch defaults to engineering completion plus silence. With a brief, the launch has a calendar, owners, and measurement. + +See: `internal-alignment-checklist.md`, `customer-comms-playbook.md`, `post-launch-measurement-framework.md`. + +--- + +## 2. Sales is confused and selling it wrong + +**Symptom.** Customers ask sales questions sales cannot answer. Reps over-promise capabilities the feature does not have. Customers churn because the feature was sold wrong. + +**Root cause.** No sales enablement. Battlecard, demo, training were skipped or rushed. Reps are improvising in front of customers. + +**Fix.** Pause the launch (pause public comms; let in-app and release notes continue). Run the sales enablement playbook in compressed form: write the battlecard, record the demo, hold the training. Resume public comms after sales is enabled. + +**Prevention.** Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. Battlecard plus 30-minute training plus recorded demo. The investment is small; skipping it is the largest avoidable launch cost. + +See: `sales-enablement-template.md`. + +--- + +## 3. Support is overwhelmed + +**Symptom.** Support ticket volume doubles or triples on launch day. Tickets pile up. Customer wait times balloon. Support reps escalate everything to the PM. + +**Root cause.** No training, no FAQ, or both. Support is encountering the feature for the first time when customers ask about it. They cannot answer questions; they escalate; the queue grows. + +**Fix.** Emergency FAQ. PM and support lead spend 4 hours documenting every question that has come in. FAQ updates push to support immediately. Re-train if needed (a short refresher). + +**Prevention.** Support training one week before launch. FAQ written before launch, not during. Estimate support volume realistically; staff for elevated volume. + +See: `support-readiness-checklist.md`. + +--- + +## 4. We rolled out and immediately rolled back + +**Symptom.** Big-bang deploy hit production. Within minutes, error rate was up. The team rolled back. Customers experienced a broken feature for 30 minutes; some saw error states. + +**Root cause.** Wrong rollout strategy. All-at-once was used when gradual was the right pattern. + +**Fix.** Audit the rollback. What was the bug; what would have caught it earlier in a gradual rollout. Pre-mortem the next launch. + +**Prevention.** Default to gradual percentage rollout for most launches. Use all-at-once only when the marketing-coordinated launch makes it unavoidable, AND the team has high confidence in correctness, AND the blast radius is low. + +See: `rollout-strategy-patterns.md`. + +--- + +## 5. The blog post went out but the feature is broken + +**Symptom.** Blog post auto-published at the announced time. Rollout had been paused two hours earlier due to an issue. Customers click through; 75 percent of them do not have the feature; they report "broken" feature that is actually a paused rollout. + +**Root cause.** Comms not gated on rollout health. Auto-fire schedule executed regardless of rollout state. + +**Fix.** Pull or update the blog post. Communicate transparently: "We hit an issue in our rollout; the feature is paused while we resolve. Your account will get access once we resume." + +**Prevention.** Make external comms manually triggered, gated on health check. Auto-fire is convenient but brittle. + +See: `customer-comms-playbook.md`. + +--- + +## 6. Adoption was great in week 1, now it is flat + +**Symptom.** The launch announcement drove a spike of users trying the feature. By week 4, adoption has dropped back to near-baseline. The team had declared victory in week 1. + +**Root cause.** Declared victory on the launch spike. The metric reverted because the launch announcement was the only driver of usage; users tried the feature once but did not come back. + +**Fix.** Re-evaluate as if the launch is unfinished. Diagnose: was it an awareness problem (users forgot the feature exists), a usability problem (users tried and bounced), a value problem (users tried and did not see value), a wrong-segment problem (the audience was wrong). Iterate based on the diagnosis. + +**Prevention.** Declare success or failure on the stable post-launch trend, not the launch-week spike. Minimum measurement window is four weeks. + +See: `post-launch-measurement-framework.md`. + +--- + +## 7. We do not know if it worked + +**Symptom.** Six months after launch, the team cannot answer "did feature X work?" Nobody measured. The feature is now maintenance debt. + +**Root cause.** No measurement plan tied to spec hypotheses. The launch did not commit to specific metrics with specific decision rules. + +**Fix.** Retroactive measurement. Pull the data; compare to a pre-launch baseline (if one exists); compute the lift. The retroactive measurement is less rigorous than a planned one but better than nothing. + +**Prevention.** Every launch has a measurement plan. The plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +See: `post-launch-measurement-framework.md`. + +--- + +## 8. Customers say we did not tell them + +**Symptom.** A customer reaches out asking why nobody told them about a feature that has been live for two months. The customer was on the email list; the email was sent; the customer missed it. + +**Root cause.** Comms did not reach the right segments. Email went to active users only; inactive users were not notified. Or the email subject line was generic and customers archived without reading. + +**Fix.** Re-send to the cohort that missed it. Use a different channel (in-app banner, account-manager outreach for top accounts). Improve the discoverability for new visitors (pricing page mention, feature-tour highlight). + +**Prevention.** Channel-mix analysis. For each launch, plan which channels will reach which cohorts. Inactive users need a different reach plan than active users. + +See: `customer-comms-playbook.md`. + +--- + +## 9. Enterprise customers found out from their account manager three days late + +**Symptom.** Enterprise customer hears about a launch from their account manager three days after public comms went out. The customer is annoyed; their AM is embarrassed; trust erodes. + +**Root cause.** No high-touch tier in comms. Public comms hit before account managers had been briefed. + +**Fix.** Apologize to the affected customer. Brief their AM immediately with the full context. Adjust process for the next launch. + +**Prevention.** Sales-led briefing for top accounts before public comms. Account managers should know about the feature one to three days before customers do, with talking points for the customer conversation. + +See: `customer-comms-playbook.md`, `sales-enablement-template.md`. + +--- + +## 10. Metric moved but it was actually because of a different launch that week + +**Symptom.** Outcome metric is up 8 percent in the four weeks post-launch. Team celebrates. Then someone notices a different launch happened the same week, and a price test concluded, and a marketing campaign ran. The 8 percent cannot be attributed to this specific feature launch. + +**Root cause.** No isolation. Multiple changes hit production in the same window; effects are confounded; the team cannot tell which change drove which metric. + +**Fix.** Run a follow-up isolated test. Roll back the feature for a cohort; measure the gap. If the gap is large, the feature was driving the metric. If the gap is small, other concurrent changes were the driver. + +**Prevention.** Stagger launches. Major launches should not coincide with each other; at minimum two weeks of separation for measurement isolation. For experiments, use the warehouse-native experimentation framework to isolate. + +See: `data-warehouse-experimentation` skill. + +--- + +## 11. We launched the wrong feature + +**Symptom.** The launch goes out. Customers respond with "this is great but it does not solve the problem we asked you to solve." The feature works; it just was not what customers expected. + +**Root cause.** Positioning unclear. The customer expected something different from what shipped because the spec, the comms, or both implied a different scope. + +**Fix.** Re-position. Re-write the comms to match what the feature actually does. Acknowledge the gap to customers who feel misled. Plan a follow-up that addresses the original ask. + +**Prevention.** The positioning canvas plus anti-positioning section forces explicit definition of what the feature is and is not. Review the canvas with sales and customer success before launch; their pushback often catches the positioning gap. + +See: `positioning-canvas.md`. + +--- + +## 12. It worked but nobody knew about it internally + +**Symptom.** The metric moved. Customer adoption was strong. The launch was a success. Six weeks later, sales is not pitching the feature, customer success is not using it as a save argument, and the executive team has forgotten about it. + +**Root cause.** No sustained internal awareness. The launch hit; the team moved to the next thing; internal momentum did not carry. + +**Fix.** Re-brief internal stakeholders at the four-week checkpoint. Share the metrics. Highlight customer use cases. Make the feature part of the next sales kickoff or company all-hands. + +**Prevention.** Internal launch is not a one-time event. After the four-week measurement, revisit. Share the win story. Update the sales playbook. The launch is not over until the feature is part of the team's vocabulary for at least a quarter. + +See: `internal-alignment-checklist.md`. + +--- + +## The pattern across all twelve + +Most launch failures share one root cause. The team treated the launch as a single event (the day the feature ships) rather than a multi-week discipline (the period when the feature lands). + +The shipping vs releasing vs launching distinction names this. Shipping is a moment; releasing is a moment; launching is a discipline that spans the four to eight weeks before and after. Teams that invest in the discipline catch most failure modes early; teams that treat the launch as a moment hit failure modes late or never. + +The fix at the meta level. Pre-launch checklist. Launch-day standup. Post-launch measurement at four-week and eight-week checkpoints. The discipline is the only thing that produces consistent launches across many features. diff --git a/skills/feature-launch-playbook/references/customer-comms-playbook.md b/skills/feature-launch-playbook/references/customer-comms-playbook.md new file mode 100644 index 0000000..739ade4 --- /dev/null +++ b/skills/feature-launch-playbook/references/customer-comms-playbook.md @@ -0,0 +1,148 @@ +# Customer comms playbook + +Channels, decision factors, calendar template, comms misfire failure mode. + +The principle. Every channel has a different reach, latency, and cost. Pick the channels that match the feature's audience and tier; sequence them so the highest-touch channels fire first and the highest-reach channels fire last. + +--- + +## Channel-by-channel + +### In-app + +**Reach.** Active users only. Highest engagement among the people who already use the product. + +**Latency.** Real-time once the rollout reaches them. + +**Right for.** Product-internal features. Tooltips, banners, modals. Discoverability prompts. + +**Decision factors.** Are users active enough to encounter the in-app surface within the launch window? If your DAU is 10 percent of MAU, in-app reaches one in ten users in the first week. + +**Anti-pattern.** Modal interrupting the user mid-task. Use banners, tooltips, or empty-state prompts that the user notices but does not have to dismiss. + +### Email (transactional or campaign) + +**Reach.** All users who opted in. Higher than in-app for inactive users. + +**Latency.** Hours from send to read. Delays for users who batch-read email. + +**Right for.** Material changes that affect existing workflows. Pricing changes. Breaking changes that need user awareness. + +**Decision factors.** Is the change material enough to justify an email? If the user can discover the feature on their next visit, email may be unnecessary. If the change affects their billing or their workflow, email is the right channel. + +**Anti-pattern.** Sending email for every release. Customers unsubscribe; the channel decays. + +### Blog post + +**Reach.** External traffic plus existing customers who read the blog. Best for SEO, lead gen, narrative. + +**Latency.** Hours to days from publish to traffic peak. + +**Right for.** Tier 1 launches with external story. Competitive positioning announcements. Major narrative shifts. + +**Decision factors.** Is there a story worth telling beyond "we shipped a feature"? Blog posts about feature ships read as marketing churn; blog posts about category narrative shifts read as substantive. + +### Release notes + +**Reach.** Customers who actively check release notes. Discoverable later via search. + +**Latency.** Real-time on publish; the long-tail value comes from search-engine and customer-search traffic over the following months. + +**Right for.** Every Tier 2 and above. The canonical reference customers find later when they encounter the feature in the wild. + +**Decision factors.** Always. Release notes are the cheapest comms channel; the cost of writing one is small; the long-tail value is real. + +### Social (LinkedIn, X, Bluesky) + +**Reach.** Beyond existing customers. Mostly other PMs, engineers, prospects. + +**Latency.** Hours to days from post to engagement. + +**Right for.** Launches with external narrative or competitive angle. Founder-led marketing. + +**Decision factors.** Does the launch have a story that a non-customer would care about? If no, social is filler. If yes, social can drive net-new pipeline. + +### Webinar or customer call + +**Reach.** Limited to attendees, but high engagement per attendee. + +**Latency.** Days to weeks from announcement to event. + +**Right for.** Tier 1 launches with material customer impact. Enterprise customers who need depth. + +**Decision factors.** Does the feature need explanation that a blog post or email cannot deliver? If yes, webinar. If the feature is self-evident, skip. + +### Sales-led briefing + +**Reach.** Top accounts only. Highest-touch channel. + +**Latency.** Days from scheduling to delivery. + +**Right for.** Launches affecting pricing, contracts, or strategic positioning. Top accounts hear about the feature from their account executive before they hear from any other channel. + +**Decision factors.** Does the launch affect the top 10 to 20 accounts in a way that requires a personal conversation? If yes, sales-led briefing is non-negotiable. + +--- + +## The comms calendar + +A single document with all channels and dates. Distributed in the internal launch brief. + +| Date | Channel | Owner | Status | Notes | +|---|---|---|---|---| +| T minus 14 days | Sales briefing scheduled | Sales lead | Pending | 30-min training | +| T minus 7 days | Support training delivered | Support lead | Pending | Live + recorded | +| T minus 3 days | CS outreach to top 20 accounts | CS lead | Pending | Email plus call | +| T minus 1 day | Sales briefing delivered | Sales lead | Pending | Q&A captured | +| T minus 1 day | Support FAQ published internally | Support lead | Pending | | +| T plus 0 (launch day, AM) | In-app banner activates | Eng | Auto on rollout | Gated on health | +| T plus 0 (launch day, AM) | Release notes publish | PM | Manual on health | | +| T plus 0 (launch day, PM) | Email send to all customers | Marketing | Manual on health | After 4-hr stability | +| T plus 1 day | Blog post publishes | Marketing | Manual on health | | +| T plus 1 day | Social posts | Marketing + founder | Manual on health | | +| T plus 7 days | Webinar (Tier 1 only) | PM + Marketing | Scheduled | | +| T plus 14 days | First post-launch checkpoint | PM | Recurring | Adoption review | + +The calendar names every channel, every date, every owner. Gaps in the calendar signal channels that are not covered (intentionally or accidentally). + +--- + +## Sequencing principles + +**Highest-touch first.** Sales-led briefing for top accounts before public comms. The top customer hearing about a feature from their account manager before they hear from a blog post is a trust win; the inverse is a trust loss. + +**Internal before external.** Sales training before sales is asked customer questions. Support training before customers ask support questions. Internal launch brief before any customer-facing channel fires. + +**Health-check gates on auto-fire channels.** In-app banners, scheduled emails, scheduled blog posts should be gated on a rollout health check. Manual triggers preferred for any channel that would be embarrassing if the rollout is paused. + +**Lower-reach to higher-reach.** Release notes and in-app first; email second; blog and social last. The lower-reach channels catch initial issues; the higher-reach channels amplify after stability. + +--- + +## The comms misfire failure + +The most common comms execution failure. + +**The setup.** The blog post is scheduled to auto-publish at the announced launch time. The rollout starts at 9 AM. At 11 AM, an issue is detected and the rollout is paused at 25 percent. The blog post auto-publishes at noon as scheduled. + +**The result.** Customers click through to the new feature page. 75 percent of them do not see the feature (the rollout has not reached them). They report bugs that are actually rollout-paused state. The launch story breaks. + +**The fix.** Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +The pattern. Auto-fire is convenient but brittle. Manual triggers are slightly more work but catch issues that auto-fire cannot. + +--- + +## Channel-mix rules of thumb by feature type + +| Feature type | Recommended channel mix | +|---|---| +| New feature for active users (Tier 2) | In-app + release notes | +| Major feature launch (Tier 1, B2B) | All channels: in-app, email, blog, release notes, social, sales-led briefing for top accounts | +| Pricing change | Email + blog + sales-led briefing + executive comms; in-app for affected users | +| Breaking change | Email + in-app prominent banner + release notes + (B2B) sales-led briefing | +| Performance improvement | Release notes + (Tier 2) in-app + (Tier 1) blog post | +| New integration | Release notes + email + blog + co-marketing with the integration partner | +| Enterprise-only feature | Sales-led briefing + customer success outreach + release notes; skip blog and social | + +The pattern. The channel mix is not "all channels" by default. It is the subset of channels that match the audience and the tier. Skipping the wrong channel hurts; firing on the wrong channel also hurts. diff --git a/skills/feature-launch-playbook/references/internal-alignment-checklist.md b/skills/feature-launch-playbook/references/internal-alignment-checklist.md new file mode 100644 index 0000000..13637c1 --- /dev/null +++ b/skills/feature-launch-playbook/references/internal-alignment-checklist.md @@ -0,0 +1,144 @@ +# Internal alignment checklist + +Stakeholders, brief structure, distribution timing. The launch brief is the single document that aligns everyone before customer comms go out. + +The principle. Internal alignment fails silently. The team does not know they are misaligned until a customer asks sales a question that sales cannot answer, or a customer escalates an issue support did not know existed. The launch brief catches misalignment before customers do. + +--- + +## Stakeholders by org type + +### Small startup (under 50 employees) + +- Engineering lead. Capacity for fixes, support escalation handling. +- Sales lead (if B2B). Pipeline impact, deal coaching. +- Customer success / support lead. Often the same person at this size. +- Marketing or content lead (if exists). Comms execution. +- Executive sponsor. Usually CEO at this size. + +The brief is shorter at this size; the meeting is faster; but the discipline still matters. The "small team did not need a launch brief" assumption is a frequent source of small-launch failures. + +### Mid-size (50 to 500 employees) + +- Engineering leadership. +- Sales leadership and at least one regional sales lead. +- Customer success leadership. +- Marketing leadership. +- Support leadership. +- Executive sponsor (VP-level for most launches; C-level for Tier 1). + +The brief is longer. The launch meeting includes a Q&A. Decision log captures the questions and answers; the log is part of the brief. + +### Enterprise (500+ employees) + +- Engineering leadership. +- Sales leadership across regions and segments. +- Customer success leadership. +- Marketing leadership including PMM (product marketing manager). +- Support leadership. +- Legal, security, and compliance (for features touching pricing, data, or regulated workflows). +- Executive sponsor (C-level for Tier 1). + +At this size, the launch brief is a formal document with sections owned by different functions. PMM often co-owns the brief with the PM. + +--- + +## The launch brief + +A single document distributed two to four weeks before Tier 1 launch, one week before Tier 2 launch. + +### Section 1: one-page summary + +Top of the brief. The PM writes it. The reader should be able to answer "what is launching, when, who is it for, why now" after one minute. + +### Section 2: positioning + +The positioning canvas (from the positioning-canvas reference) embedded directly. Target user, problem, current alternative, user-visible promise, proof points, anti-positioning. + +### Section 3: launch calendar + +Every channel and every date. In-app banner activation, email send, blog post publish, social post times, sales briefing, support training, customer success outreach windows. Owners named for each. + +### Section 4: what each function needs to do differently + +The most important section for the readers. Each function gets a paragraph. + +- **Sales.** Battlecard link. Demo recording link. Top objections and answers. Deals to revisit. Training session date. +- **Customer success.** Top accounts to brief. Talking points for the briefing. Escalation contact during launch week. +- **Support.** Training session date. FAQ link. Escalation path. Ticket tagging convention. +- **Marketing.** Channel list, dates, message variants by channel. +- **Engineering.** On-call coverage during launch. Rollback authority. Health-check dashboard link. + +If a function does not have a paragraph, the launch was not designed with that function in mind; revisit before distributing. + +### Section 5: FAQ + +The questions that have already come up internally, with answers. The FAQ updates daily during the first week of distribution as new questions surface. + +### Section 6: decision log + +Choices already made. Includes the rationale for non-obvious decisions. Future questions ("why did we pick that rollout strategy?") get answered by reading the log instead of re-litigating the decision. + +--- + +## Distribution timing + +| Tier | Timing | Channel | +|---|---|---| +| Tier 1 | 2 to 4 weeks before launch | Email plus async meeting plus 1:1 follow-ups for sales and CS | +| Tier 2 | 1 week before launch | Email plus async meeting | +| Tier 3 | Day of launch or as part of a weekly release digest | Email or shared doc | + +The pattern. Launch brief lands first. Sales briefing, support training, customer success outreach all happen after the brief lands and before the public comms fire. + +--- + +## The pre-launch meeting + +For Tier 1 launches, hold a 30-minute pre-launch meeting one week before launch. + +Agenda. + +1. PM walks through the positioning canvas and the calendar (10 minutes). +2. Each function lead confirms their readiness (10 minutes). +3. Open Q&A captured in the decision log (10 minutes). + +The meeting is not for re-litigating the launch. It is for confirming readiness and catching last-minute gaps. If functions are not ready, the launch is delayed. The PM has authority to delay; the executive sponsor confirms. + +--- + +## The launch-day standup + +For Tier 1 launches, hold a brief launch-day standup at the start of launch day. Five to ten minutes. + +Agenda. + +1. Confirm rollout health check is green. +2. Confirm comms are gated on the health check (the social post will not auto-fire if the rollout is paused). +3. Confirm support is staffed for the launch window. +4. Confirm escalation contacts are reachable. +5. Open the post-launch monitoring channel. + +The launch-day standup catches "the marketing person took the day off and the social post is set to auto-fire" the morning of launch instead of in the moment. + +--- + +## Common internal alignment failures + +- **Launching without sales knowing.** Sales finds out from a customer. Trust erodes for the next launch. Fix: launch brief plus sales-specific briefing one to two weeks before public comms. +- **Sales briefing is the launch brief.** Sales reads a 12-page document. Their actual takeaway is partial. Fix: separate one-pager for sales (the battlecard) plus the full brief for reference. +- **Support is trained the day of launch.** Support cannot internalize a new feature in one morning. Fix: train support one week before customer-facing launch. +- **Customer success outreach happens after public comms.** Top accounts hear about the feature from the email blast like everyone else. Fix: customer success briefs top accounts one to three days before public comms. +- **Executive sponsor is surprised on launch day.** The executive read the brief but did not internalize it; on launch day they see press coverage and ask the team questions that should have been answered in the brief. Fix: brief executives in person, not just via document. + +--- + +## When the brief reveals misalignment + +The brief is the artifact that surfaces misalignment. Common signals. + +- The positioning canvas does not match how sales describes the customer profile. Misalignment between PM and sales on who the customer is. +- The launch calendar does not give sales enough time. Misalignment on what enablement requires. +- The FAQ has questions nobody can answer. Misalignment on what the feature actually does. + +The pattern. Surface misalignment before launch; resolve before launch. The brief is the tool that forces the conversation. A team that drafts the brief carefully and finds it easy to write probably has no misalignment. A team that struggles to write the brief has misalignment that the brief is now revealing; resolve it before customer comms go out. diff --git a/skills/feature-launch-playbook/references/launch-tier-decision.md b/skills/feature-launch-playbook/references/launch-tier-decision.md new file mode 100644 index 0000000..dab6ffc --- /dev/null +++ b/skills/feature-launch-playbook/references/launch-tier-decision.md @@ -0,0 +1,137 @@ +# Launch tier decision + +Tier 1 / Tier 2 / Tier 3 decision framework. Worked examples. Anti-patterns on both sides. + +The principle. Match launch effort to feature scope. Treating every release as Tier 1 produces comms fatigue; treating every release as Tier 3 produces unlaunched features. + +--- + +## The tiers + +### Tier 1: full launch + +**Scope.** Net-new product, major feature reshaping the product narrative, pricing change, breaking change. + +**Effort.** Full playbook. Positioning, all comms channels, sales enablement (B2B), customer success briefing, dedicated post-launch measurement, executive announcement. Two to four weeks of pre-launch work; four to eight weeks of post-launch monitoring. + +**Examples.** + +- A new product surface (Slack adds Canvas; Figma adds FigJam; Notion adds Sites). +- A pricing model change (per-seat to consumption; introducing a new tier). +- A foundational replatforming with user-visible impact (a new UI architecture, a new permissions model). +- A flagship competitive feature (the thing the sales team has been asking for, the thing the analyst report compared you on). + +### Tier 2: focused launch + +**Scope.** Meaningful improvement that materially affects user value or competitive positioning. + +**Effort.** Subset of the playbook. In-app comms, blog post or detailed release note, support readiness, rollout strategy, post-launch measurement. One to two weeks of pre-launch work; two to four weeks of post-launch monitoring. + +**Examples.** + +- A new export format that customers have been requesting. +- A redesigned core flow (e.g., a new onboarding experience). +- An integration with a major third-party (Slack notifications, Salesforce sync). +- A meaningful performance improvement (page loads twice as fast on a flagship surface). + +### Tier 3: release note + +**Scope.** Incremental improvement, bug fix made positive, polish. + +**Effort.** Minimal. Changelog entry, release note, light monitoring. Hours of pre-launch work; passive monitoring post-launch. + +**Examples.** + +- A new keyboard shortcut. +- A small UI polish (better empty states, refined typography). +- A minor configuration option (toggle to disable a non-default behavior). +- A bug fix that improves reliability for a small cohort. + +--- + +## Decision framework + +When unsure between two tiers, ask three questions. + +1. **Will sales need to talk about this?** If yes, at least Tier 2. If sales is selling against this gap today, Tier 1. +2. **Will customers be confused if we do not tell them?** If yes, at least Tier 2. +3. **Will the metric this is meant to move show up in board reporting?** If yes, Tier 1. If yes but only at the team level, Tier 2. + +If all three answers are no, the feature is Tier 3. + +--- + +## Worked examples + +### Example 1: a new export-to-PDF capability + +A B2B SaaS product adds export-to-PDF to its reporting feature. + +- Will sales talk about this? Yes; this has been a top sales objection. +- Will customers be confused without comms? No; the feature is discoverable in the existing UI. +- Will the metric move at board level? Probably not directly; might unblock some deals. + +**Tier 2.** Sales enablement (battlecard plus a one-paragraph deal-coaching note). Blog post. Release note. In-app banner on the reporting page. Light monitoring. + +### Example 2: a new pricing tier with consumption-based billing + +A SaaS company adds a usage-based tier alongside its existing per-seat plans. + +- Will sales talk about this? Yes; pricing changes always involve sales. +- Will customers be confused without comms? Yes; existing customers will wonder if they should switch. +- Will the metric move at board level? Yes; revenue mix and ARR composition are board-level. + +**Tier 1.** Full positioning canvas. Internal launch brief 4 weeks ahead. Sales enablement including pricing change documentation. Email to existing customers explaining what is and is not changing for them. Blog post. Webinar for top accounts. Phased rollout starting with new customers, then existing customer opt-in. + +### Example 3: a keyboard shortcut for a power-user action + +A consumer app adds Cmd+K for quick navigation. + +- Will sales talk about this? No; consumer product, no sales motion. +- Will customers be confused without comms? No; the feature is purely additive and discoverable. +- Will the metric move at board level? No; small UX improvement. + +**Tier 3.** Changelog entry. Maybe a tweet from the product team. No further work. + +### Example 4: an enterprise SSO integration + +A B2B SaaS adds SAML SSO support. + +- Will sales talk about this? Yes; SSO is a hard requirement for many enterprise deals. +- Will customers be confused without comms? Existing self-service customers no; enterprise prospects yes. +- Will the metric move at board level? Indirectly; SSO unblocks enterprise deals worth real ARR. + +**Tier 1 if SSO unlocks the enterprise segment for the first time, otherwise Tier 2.** Sales enablement is the highest-impact piece (the deal-coaching note for previously SSO-blocked accounts). Customer success outreach to top enterprise prospects. Blog post focused on the security and IT audience. Quiet rollout for self-service customers (changelog only). + +--- + +## Anti-pattern: everything is Tier 1 + +Symptom. Every release gets a blog post, an email, a sales briefing. Customers tune out the announcement firehose. Real Tier 1 launches lose signal in the noise. Sales reps stop reading the briefings because they assume every one is minor. + +Fix. Be honest about which features are major. If you ship five "major" launches per quarter, three of them are Tier 2 or Tier 3 in disguise. The Tier 1 budget should be one to three per quarter for most companies. + +--- + +## Anti-pattern: everything is Tier 3 + +Symptom. Features ship without comms. Sales does not know what is new. Customers are surprised when they discover a feature six months after launch. Metrics do not move because users do not know the feature exists. + +Fix. Tier honestly. Most B2B SaaS releases are Tier 2; defaulting them to Tier 3 leaves value on the table. The minimum Tier 2 effort (release note plus in-app banner plus support FAQ) is small; the marginal value capture is large. + +--- + +## How tier affects the rest of the playbook + +| Section | Tier 1 | Tier 2 | Tier 3 | +|---|---|---|---| +| Positioning canvas | Required | Required | Skip | +| Internal launch brief | 2 to 4 weeks ahead | 1 week ahead | Skip | +| Customer comms | All channels | In-app + blog + release note | Release note | +| Sales enablement (B2B) | Full battlecard + demo + training | One-page note + Q&A | Skip | +| Support readiness | Full training | Brief + FAQ | FAQ if applicable | +| Rollout strategy | Phased or gradual | Gradual | Either | +| Monitoring | Full + rollback triggers | Standard + alerts | Passive | +| Post-launch measurement | 4 to 8 weeks | 2 to 4 weeks | Light | + +The pattern. Tier 1 is the full playbook. Tier 2 is the playbook compressed. Tier 3 is the changelog plus passive monitoring. Each section's depth scales with tier. diff --git a/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md b/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md new file mode 100644 index 0000000..6770c30 --- /dev/null +++ b/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md @@ -0,0 +1,185 @@ +# Monitoring readiness checklist + +Metrics dimensions, alert thresholds, pre-defined rollback triggers. The "no rollback trigger" failure mode. + +The principle. Monitoring catches launch issues before they compound into customer pain. The discipline is defining what to watch and what to do BEFORE launch, so the team executes rather than debates during the launch window. + +--- + +## What to monitor + +Six dimensions for most launches. + +### 1. Error rates + +- **Overall error rate.** The baseline. Has the deploy increased errors across the application. +- **Feature-specific error rate.** Errors in code paths the new feature touches. Often the first signal of a feature-specific bug. +- **Per-cohort error rate.** Errors broken down by user segment, plan, region. Catches cohort-specific bugs. + +### 2. Latency + +- **Overall P50, P95, P99.** Has the deploy slowed the application. +- **Feature-specific latency.** New code paths often have unoptimized queries; latency tracking catches them. +- **Database query latency.** New features often add new queries; database load can spike. + +### 3. Feature usage rate + +- **Reach.** Of users in the rollout cohort, how many actually trigger the feature within their first session post-rollout. +- **Frequency.** Of users who used the feature once, how many used it again. +- **The expected vs actual gap.** Pre-launch projections vs actual numbers. Large gaps in either direction need investigation. + +### 4. Funnel completion + +- **End-to-end completion of the workflow the feature is part of.** Did users complete the flow at the same rate as pre-launch. +- **Step-by-step drop-off.** Where in the flow are users abandoning. Compare pre-launch to post-launch step-by-step. +- **Per-cohort completion.** Cohort-specific drop-off can hide in aggregate metrics. + +### 5. Support ticket volume + +- **Overall ticket volume.** Has the team's support load increased. +- **Feature-tagged tickets.** Tickets where the customer mentions the feature. +- **Ticket sentiment.** Frustrated tickets vs informational tickets vs positive tickets. + +### 6. Customer satisfaction signals + +- **NPS comments.** Mentions of the feature in NPS responses. +- **Feedback widget.** In-product feedback explicitly about the feature. +- **Social mentions.** Twitter or LinkedIn posts about the launch. + +--- + +## Alert thresholds + +For each dimension, pre-defined thresholds that fire alerts. + +### Error rates + +- **Yellow.** Overall error rate up by more than 25 percent vs pre-launch baseline. Investigate without escalation. +- **Orange.** Overall error rate up by more than 50 percent vs baseline. Escalate to PM and engineering on-call. +- **Red.** Overall error rate above 1 percent absolute. Trigger rollback. + +### Latency + +- **Yellow.** P95 up by 25 percent vs baseline. Investigate. +- **Orange.** P95 up by 50 percent. Escalate. +- **Red.** P95 doubled or worse. Trigger rollback if sustained for 10 minutes. + +### Feature usage rate + +- **Yellow.** Below 50 percent of pre-launch projection. Investigate (probably comms or discovery problem). +- **Orange.** Below 25 percent of projection. Escalate; the launch may not be reaching users. +- **Red.** Near zero usage. Likely an instrumentation bug; the feature is not firing or the metric is not capturing. + +### Funnel completion + +- **Yellow.** Down by 10 percent from pre-launch baseline. Investigate. +- **Orange.** Down by 25 percent. Escalate; the feature may be breaking the flow. +- **Red.** Down by 50 percent for any cohort. Trigger rollback for that cohort or pause the rollout. + +### Support volume + +- **Yellow.** Feature-tagged tickets exceed 10 in the first hour. Investigate. +- **Orange.** Feature-tagged tickets exceed 50 in the first hour. Escalate. +- **Red.** Feature-tagged tickets exceed 100 in the first hour. Trigger rollback or pause; the feature has a real problem. + +The numbers above are illustrative. Calibrate to the team's actual support volume and the feature's expected reach. + +--- + +## Pre-defined rollback triggers + +A rollback trigger is a rule that fires automatically. The team executes the rollback without re-litigating whether to. + +### Examples + +**For a feature touching the checkout flow.** + +- Error rate above 1 percent sustained for 5 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline. +- Stripe API errors increase by 100 percent. + +**For a new internal tool.** + +- Error rate above 5 percent sustained for 5 minutes (higher tolerance because internal users provide more context). +- Adoption near zero after 24 hours (instrumentation bug or feature not deployed). + +**For a pricing change.** + +- Subscription cancellation rate increase by 50 percent in the first 48 hours. +- Customer service contact rate about pricing increase by 200 percent. +- Revenue forecast adjustment indicates a 10 percent quarterly miss. + +The pattern. Each rollback trigger names a specific metric, a specific threshold, and a specific time window. The team rehearses what to do when the trigger fires. + +### What rollback means + +Rollback can be one of several things. + +- **Full rollback.** Flag off, code reverted, user-visible state returns to pre-launch. +- **Pause at current rollout percentage.** Flag stays on for users who already have it; no new users get the feature. +- **Cohort-specific rollback.** Flag off for the cohort showing issues; flag on for cohorts that look healthy. +- **Fix-forward.** A small fix is deployed; rollout continues at the previous percentage. Risky; only use when the fix is high-confidence. + +The team should know which rollback path applies to which trigger before launch. + +--- + +## The on-call rotation + +For Tier 1 launches, the on-call rotation should include. + +- **Primary engineering on-call.** Standard rotation. Receives alerts, executes rollbacks. +- **Secondary engineering on-call.** Backup if primary is unreachable. +- **PM contact.** The PM who owns the launch is reachable during the launch window. +- **Support escalation contact.** The support lead responsible for routing customer issues to the right team. +- **Marketing contact.** For comms decisions if the rollout pauses. + +Reachability hours for Tier 1 launches: 24/7 for the first 48 hours, business hours plus on-call after that. + +--- + +## The "no rollback trigger" failure + +The pattern. + +- Launch goes sideways. Error rate is up; support volume is high; engineering is investigating. +- The team debates whether to roll back. The debate takes an hour. +- During the debate hour, more users encounter the issue. Support tickets pile up. The press notices. Trust erodes. +- The team eventually rolls back, but the recovery is now harder than it would have been one hour earlier. + +The fix. Pre-define the rollback triggers. Write them down. Get team agreement before launch. When a trigger fires, execute the rollback. Debate the appropriateness of the trigger after the rollback, not during the incident. + +The discipline. The cost of a wrong rollback (the team rolls back when the feature was actually fine) is small (a paused launch and a re-rollout). The cost of a delayed rollback (the team debates while the issue compounds) is large (customer impact, reputation, recovery cost). Bias toward fast rollback. + +--- + +## Post-rollback retrospective + +After any rollback, hold a retrospective within 48 hours. + +Agenda. + +1. What was the trigger that fired. +2. What was the actual problem. +3. Was the rollback the right call (almost always yes; even false positives that catch nothing teach the team about the system). +4. What is the path to re-launch (fix the bug, test it, validate the test, schedule a new rollout). +5. What did we learn that updates the next launch's monitoring. + +The retrospective is not a blame session. It is an investment in the next launch's monitoring quality. + +--- + +## Health check before each rollout step + +For gradual percentage rollouts, define a health check that gates each step. + +The health check passes when. + +- All Yellow thresholds clear for the prior percentage step's full duration. +- No Orange or Red alerts in the prior step. +- Support volume stable. +- Customer feedback (NPS, social) neutral or positive. + +The health check fails when any of the above conditions does not hold. The rollout pauses at the current step until the health check passes. + +The pattern. The rollout proceeds when the system is healthy; it does not proceed on a schedule. Schedule-driven rollouts that ignore health checks are how launches go sideways. diff --git a/skills/feature-launch-playbook/references/positioning-canvas.md b/skills/feature-launch-playbook/references/positioning-canvas.md new file mode 100644 index 0000000..4ab4b54 --- /dev/null +++ b/skills/feature-launch-playbook/references/positioning-canvas.md @@ -0,0 +1,132 @@ +# Positioning canvas + +The one-page positioning template. Worked examples for B2B SaaS, B2C, and developer features. The vague-target-user failure mode. + +The principle. Positioning is the foundation of the launch. Without it, comms drift, sales improvise, and customers come away with a different understanding of the feature than the team intended. Filled out before any comms drafting; reviewed by sales, support, and an executive sponsor before launch. + +--- + +## The canvas + +One page. Six sections. Filled out by the PM with input from sales, customer success, and design. + +### 1. Target user + +**Segment.** What kind of company or individual. + +**Role.** What is their job title or function. + +**Jobs-to-be-done.** What is the user trying to accomplish in their work or life that this feature serves. + +**Specificity test.** Could a sales rep describe the customer profile in one sentence? Could marketing target ads at this segment? If no to either, the target user is too vague. + +### 2. Problem it solves + +**The current pain.** In the user's words. What is hard, slow, error-prone, or impossible today. + +**The cost of the pain.** Time, money, errors, missed opportunities. Quantified where possible. + +**Specificity test.** Is the problem stated in concrete terms or in abstract language? "Productivity is low" is abstract. "The customer support manager spends 3 hours per day triaging tickets that an automated system could route" is concrete. + +### 3. Current alternative + +**What users do today without this.** The status quo, the workaround, the competing product, the manual process, the spreadsheet. + +The status quo is the real competition. A feature that is better than nothing but worse than the user's existing workaround does not get adopted. + +### 4. User-visible promise + +**One sentence.** The promise the user will hear when they encounter the feature. + +**Specificity test.** Can sales repeat it without changing words? Can support repeat it without paraphrasing? If no, it is too long or too abstract. + +### 5. Proof points + +**Three to five specific capabilities or outcomes.** Concrete, not adjectives. + +Examples of bad proof points: "fast," "easy," "secure," "intelligent." These are claims, not proof. + +Examples of good proof points: "exports a 200-page report in under 5 seconds," "supports 14 languages including right-to-left," "SOC 2 Type II audited by Deloitte 2025." + +### 6. Anti-positioning + +**What this is NOT.** What it does not try to do. + +Anti-positioning prevents over-promising. If the feature does not handle enterprise scale, say so. If it does not work offline, say so. If it does not replace the customer's existing tool, say so. + +The anti-positioning protects the team from sales reps who hear about the feature and embellish. It protects support from customers who expected something the feature does not do. + +--- + +## Worked example 1: B2B SaaS feature + +A B2B project management tool ships a new automated routing feature. + +| Section | Content | +|---|---| +| Target user | Customer support managers at SaaS companies with 10 to 100 support reps. JTBD: triage incoming tickets and route them to the right team without reading every ticket. | +| Problem it solves | Current manual triage takes 2 to 3 hours of a support manager's day. Tickets sit in the queue waiting for routing while customers grow impatient. The cost is 10+ hours per week of manager time plus 30 to 60 minute response delays on simple tickets. | +| Current alternative | Manual triage by a senior support rep, or basic keyword routing rules in their existing helpdesk that produce 30 to 40% misroutes. | +| User-visible promise | "Route incoming tickets to the right team in under 30 seconds with 95% accuracy." | +| Proof points | (1) ML model trained on 90 days of historical ticket routing decisions. (2) Accuracy benchmarks: 95% routing accuracy at launch, retraining weekly. (3) Override and feedback flow lets support managers correct routes; corrections feed back into the model. (4) Audit log of every routing decision for compliance. (5) Configurable confidence threshold; below the threshold, the ticket falls back to manual routing. | +| Anti-positioning | This is not a full ticket-resolution AI. It does not draft replies, identify duplicate tickets, or detect sentiment. It only routes. | + +The anti-positioning protects the team from sales reps who would otherwise pitch this as "AI customer support." + +--- + +## Worked example 2: B2C feature + +A consumer note-taking app ships AI-generated summaries. + +| Section | Content | +|---|---| +| Target user | Students and knowledge workers who maintain long-form notes. Specifically users with 50+ notes longer than 500 words. JTBD: quickly recall the key points of a note without re-reading it. | +| Problem it solves | Long notes get written then forgotten. The user cannot recall what is in them without scrolling and re-reading. Cost: hours per week of search-and-rediscover, plus the worse cost of acting on stale information. | +| Current alternative | Manual TLDRs the user writes themselves (rare). Highlighted text within the note (common but unreliable). Re-reading the full note (default; expensive). | +| User-visible promise | "See a summary of any note in two seconds." | +| Proof points | (1) Summaries appear at the top of every note over 500 words. (2) Summary regenerates when the note is meaningfully edited. (3) Click any summary point to jump to its source paragraph in the note. (4) Generates in under 2 seconds for notes up to 5,000 words. | +| Anti-positioning | This is not a research assistant; it does not pull in outside context or related notes. It summarizes the note in front of you, nothing more. | + +--- + +## Worked example 3: developer feature + +A developer tools company ships a new CLI command. + +| Section | Content | +|---|---| +| Target user | Backend engineers using the platform's CLI for deploys. Specifically engineers who run more than 5 deploys per week. JTBD: deploy faster and roll back when something breaks. | +| Problem it solves | Rollbacks today require digging through deploy history, finding the prior version, and running a deploy command with the version pinned. Takes 2 to 5 minutes; under incident pressure, the time matters. | +| Current alternative | Manual deploy command with version pin. Some teams script this; most do it from memory under pressure. | +| User-visible promise | "Roll back to the last known good deploy with one command." | +| Proof points | (1) Single command: `acme deploy rollback`. (2) Defaults to the most recent successful deploy that is older than the current. (3) Confirmation prompt shows what will be rolled back; passes through to the existing deploy flow. (4) Logged as a rollback in deploy history (not as a fresh deploy) for clean audit trail. | +| Anti-positioning | This does not auto-detect bad deploys. The engineer still decides when to roll back. | + +--- + +## The vague-target-user failure mode + +The most common positioning failure. The PM writes "It is for PMs" or "It is for engineers" or "It is for marketers." + +Why it fails. Different PMs, engineers, and marketers have different jobs. A B2B PM at a 50-person startup has a different job from a B2C PM at a 5,000-person company. A backend engineer has a different job from a frontend engineer. The vague target prevents sales from filtering, prevents marketing from targeting ads, prevents support from anticipating questions. + +The fix. Specificity layers. + +- Industry or company type. (B2B SaaS at 50 to 500 customers.) +- Role and function. (Customer support manager, not just "support.") +- Jobs-to-be-done. (Triage incoming tickets, not "improve productivity.") + +Three layers of specificity move the target from useless to actionable. If you cannot fill in all three, the team has not yet decided who the feature is for. + +--- + +## Reviewing the canvas + +Before launch, review the positioning canvas with three audiences. + +1. **Sales review.** Can sales pitch this in 30 seconds? Does the language match how customers ask about the problem? +2. **Support review.** Can support answer the obvious questions (what does it cost, how do I turn it on, what are the limits) using only the canvas? +3. **Executive review.** Does the positioning fit the company narrative? Will it confuse customers who are mid-purchase on a different feature? + +If any of the three review groups push back, fix the canvas before launch comms drafting begins. Drafting comms on top of weak positioning produces comms that look fine in isolation but contradict each other across channels. diff --git a/skills/feature-launch-playbook/references/post-launch-measurement-framework.md b/skills/feature-launch-playbook/references/post-launch-measurement-framework.md new file mode 100644 index 0000000..3475f47 --- /dev/null +++ b/skills/feature-launch-playbook/references/post-launch-measurement-framework.md @@ -0,0 +1,181 @@ +# Post-launch measurement framework + +Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. The "declared victory on launch spike" failure mode. + +The principle. The launch measurement plan answers "did this work." Without it, the team moves on without knowing. + +--- + +## Four measurement dimensions + +### 1. Adoption (the reach question) + +Did the right users actually use the feature. + +**Metrics.** + +- Reach: of users in the rollout cohort, what fraction has tried the feature. +- Time to first use: of users who tried the feature, how long after rollout. +- Distribution by cohort: are the right segments (per the positioning canvas) the ones using the feature. + +**Signal interpretation.** + +- High reach plus right cohorts: the launch reached the target audience. +- High reach plus wrong cohorts: the launch reached the wrong audience; positioning or comms missed the target. +- Low reach: comms problem or discovery problem. Investigate which channel users would have learned about the feature from. + +### 2. Engagement (the stickiness question) + +Did users who tried the feature come back. + +**Metrics.** + +- Retention: of users who tried the feature once, what fraction used it again within 7, 14, 30 days. +- Frequency: how many times per week did adopters use the feature. +- Depth: did adopters use the full feature or only the first step. + +**Signal interpretation.** + +- High first-time use plus high retention: the feature is delivering value. +- High first-time use plus low retention: the feature failed to deliver on the first-use experience. Usability or value-prop problem. +- Low first-time use plus high retention among the few who tried: the feature is valuable to a niche; reach the niche better, or accept that it serves a smaller audience. + +### 3. Outcome (the effect question) + +Did the metric the spec said this would move actually move. + +**Metrics.** + +- The primary metric from the spec. Usually a business metric (revenue, retention, support deflection, conversion rate). +- The lift relative to a pre-launch baseline. +- The statistical significance of the lift, if a controlled comparison is available. + +**Signal interpretation.** + +- Metric moved as predicted: the feature delivered the value the team committed to. +- Metric moved less than predicted: partial success; the feature works but did not have the size of impact the team expected. Investigate why (smaller cohort than expected, smaller per-user impact, or simply optimistic projection). +- Metric did not move: the launch did not deliver the promised value. Investigate before declaring failure (could be measurement timeline, isolation issues, or the feature genuinely failing). + +### 4. Side effects (the safety question) + +Did any other metric move that was not supposed to. + +**Metrics.** + +- Cohorts adjacent to the target: did the feature affect users it was not designed for. +- Adjacent metrics: did related metrics move (positively or negatively). +- Support volume on adjacent topics: did the feature confuse customers about other parts of the product. + +**Signal interpretation.** + +- No side effects: clean launch. +- Positive side effects: the feature delivered value beyond the target. Document for the next iteration. +- Negative side effects: the feature broke something else. Triage urgently; this is a launch quality issue regardless of whether the primary metric moved. + +--- + +## Time horizons + +Different signals stabilize at different times. + +| Signal type | Stable at | +|---|---| +| Adoption (reach) | 1 to 2 weeks post-launch | +| Engagement (retention) | 4 weeks for week-2 retention; 8 weeks for week-4 retention | +| Outcome | 4 to 8 weeks for most business metrics; longer for retention or LTV | +| Side effects | 2 to 4 weeks | + +The rule. Do not declare success or failure on the outcome metric before week 4. The launch-week spike is unrepresentative; the metric needs time to stabilize at its post-launch level. + +--- + +## Tying back to spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses. The launch measurement plan validates each. + +Example hypotheses from a hypothetical spec. + +- "We expect this feature to be used by 40 percent of paid users within 30 days of rollout." (Adoption hypothesis.) +- "Of users who try the feature, we expect 60 percent to use it again within 7 days." (Engagement hypothesis.) +- "We expect this feature to reduce support tickets in the X category by 25 percent." (Outcome hypothesis.) +- "We do not expect this feature to affect billing-related support volume." (Side-effect hypothesis.) + +The measurement plan validates each. + +| Hypothesis | Measurement | Decision rule | +|---|---|---| +| 40% paid user adoption in 30 days | Cohort: paid users in rollout. Metric: distinct user count using the feature divided by cohort size. | Above 30% acceptable; below 20% requires intervention. | +| 60% week-1 retention | Cohort: users who tried the feature in week 1. Metric: fraction of cohort using the feature again in week 2. | Above 50% acceptable; below 40% indicates value or usability problem. | +| 25% reduction in X-category support tickets | Pre-launch baseline 30 days; post-launch 30 days. Compare ticket volumes. | Above 15% reduction acceptable; below 10% indicates the feature is not solving the right problem. | +| No effect on billing support | Billing ticket volume pre vs post. | Volume change above 20% requires investigation. | + +The measurement plan is written before launch. The decision rules are pre-committed; the team does not move the goalposts after seeing the data. + +--- + +## The "declared victory on launch spike" failure + +The pattern. + +- Week 1: adoption is high. The team announced the feature; users tried it; the metric is up. +- Week 2: adoption flat. The launch announcement spike has passed; the new users have tried the feature. +- Week 3: adoption declining. Users who tried the feature once are not coming back. +- Week 4: adoption near pre-launch baseline. The metric has reverted. +- The team had already declared the launch a success in week 1 and moved on. + +The cost. The team's roadmap is now built on a launch that did not actually work. The next quarter's plan assumes the metric is at the elevated level; when it does not stay there, the plan does not deliver. + +The fix. Declare success or failure based on the stable post-launch trend, not the launch-week spike. The minimum measurement window is four weeks; for retention or LTV signals, eight to twelve weeks. + +The discipline. The four-week checkpoint is on the calendar before launch. The team holds itself accountable to revisit; the executive sponsor holds the team accountable to revisit. Launches that are reported as successful in week 1 and never revisited are silent failures. + +--- + +## The "no measurement plan" failure + +The pattern. + +- Feature ships. +- Team moves on to the next feature. +- Six months later, someone asks "did feature X work?" Nobody knows. +- The feature becomes maintenance debt; the team cannot decide whether to invest in iteration. + +The cost. The team accumulates features whose value is unknown. Roadmap decisions get harder because the historical track record is opaque. Engineering investment is wasted on features that did not work; the team does not learn from them because they did not measure. + +The fix. Every launch has a measurement plan. The plan is short (one page); it names the four dimensions, the metrics, the time horizons, and the decision rules. The plan is reviewed at week 4 and again at week 8 or 12 depending on the signal. + +The discipline. The measurement plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +--- + +## When the metric did not move + +If the outcome metric did not move at week 4, the next investigation. + +1. **Is adoption strong?** If adoption is below target, the launch may be a comms or discovery problem, not a feature problem. +2. **Is engagement strong?** If engagement is below target among adopters, the value is not landing for the right reasons. +3. **Is the metric correctly attributed?** Did another concurrent change interfere with the measurement. +4. **Did the side-effects analysis catch a counterweight?** A negative side effect could be cancelling the positive primary effect. + +Each diagnosis maps to a different fix. + +- Adoption problem: more comms, repeat comms, deeper sales reactivation, in-app discovery surface. +- Engagement problem: usability or value-prop iteration. The feature may need redesign. +- Attribution problem: re-run measurement after the concurrent change has been accounted for. +- Side-effect counterweight: fix the side effect, then re-measure the primary. + +--- + +## When the launch worked but quietly + +Sometimes the launch works at every level (adoption strong, engagement strong, outcome metric moved) but the team does not feel like it succeeded. Usually the gap is internal awareness. + +Signs. + +- Sales is not using the feature in pitches. +- Customer success is not mentioning it in customer calls. +- The product narrative has not updated to include the feature. + +The fix. Internal launch effectiveness is part of the launch playbook. Even successful feature launches need ongoing internal advocacy. + +The discipline. After the four-week checkpoint, briefly re-engage internal stakeholders. Share the metrics. Highlight customer use cases. The internal awareness is not a one-time event at launch; it is sustained for a quarter or more. diff --git a/skills/feature-launch-playbook/references/rollout-strategy-patterns.md b/skills/feature-launch-playbook/references/rollout-strategy-patterns.md new file mode 100644 index 0000000..a7e0c83 --- /dev/null +++ b/skills/feature-launch-playbook/references/rollout-strategy-patterns.md @@ -0,0 +1,185 @@ +# Rollout strategy patterns + +Four rollout patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. + +The principle. The rollout is the mechanism by which users actually encounter the feature. The pattern depends on what would happen if the feature breaks, how confident the team is in correctness, and whether external comms are tied to a specific date. + +--- + +## Pattern 1: all-at-once (big bang) + +**Mechanism.** Zero to 100 percent of eligible users in a single deploy. No gradual rollout. + +**Right for.** + +- Marketing-coordinated launches where the announcement IS the rollout. The press is briefed for a specific date; the feature has to be live for everyone at that moment. +- Low-blast-radius features. The feature affects a small portion of the user experience; even if it breaks, the customer impact is limited. +- High-confidence releases. The feature has been tested thoroughly, used internally, validated with a beta cohort. + +**Risky for.** + +- High-traffic critical paths (checkout, login, primary navigation). Any bug affects a meaningful share of users immediately. +- Features without a clean rollback path. If the deploy breaks, recovery is hard. +- Features with cohort-specific risk (works for free users, breaks for enterprise). The cohort variance is not exposed before launch. + +**Operational shape.** One deploy. Health check after deploy. Rollback path ready but rarely used. Monitoring tightens for 24 hours post-deploy. + +--- + +## Pattern 2: gradual percentage rollout + +**Mechanism.** 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days. Health checks at each step. + +**Right for.** + +- Most feature launches. The default unless there is a reason to deviate. +- Features touching critical paths. The 1 percent rollout catches errors before they affect a meaningful share of users. +- Features with uncertain interaction effects. Other systems may behave differently when the feature is on; gradual rollout surfaces interactions safely. + +**Risky for.** + +- Marketing-coordinated launches with a fixed announcement date. The press writes about a feature that 90 percent of users do not have yet. + +**Operational shape.** + +- 1 percent to 10 percent: 4 to 24 hours. Watch error rates, latency, feature usage rate. +- 10 percent to 25 percent: 24 to 48 hours. Watch the same metrics plus support volume. +- 25 percent to 50 percent: 48 to 72 hours. Watch all metrics plus customer feedback. +- 50 percent to 100 percent: 24 to 72 hours. + +The pace is configurable. Faster for low-risk features; slower for high-risk. + +The rollback at any step. If a metric breaches a threshold, the rollout pauses. If the issue is severe, rollback to 0 percent. If the issue is minor, fix forward at the current percentage. + +--- + +## Pattern 3: flag-gated cohort rollout + +**Mechanism.** Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Specific named accounts first, then broad rollout. + +**Right for.** + +- Features with cohort-specific risk profiles. A pricing change affects existing customers differently from new customers; roll out to new customers first. +- Features that need cohort-specific configuration. Enterprise customers may need a setup step; roll out to them after they are configured. +- Features where the cost of a bad rollout varies by cohort. Bug in front of a Fortune 500 prospect costs more than a bug in front of a free-tier user. + +**Operational shape.** + +- The flag service controls which cohorts have the feature enabled. +- Cohorts are defined explicitly: account tier, account ID list, region, signup date range. +- Each cohort gets its own monitoring slice. Issues affecting one cohort do not pause the rollout to other cohorts. + +**Risky for.** + +- Features that interact across cohorts. If enterprise customers can see what free-tier customers create, a partial cohort rollout exposes a feature inconsistency that breaks workflows. + +--- + +## Pattern 4: phased launch (multi-week) + +**Mechanism.** Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Multi-week timeline. + +**Right for.** + +- Tier 1 launches with high uncertainty about user reception. Pricing changes often launch this way. +- Major UX redesigns. The team needs to learn what users do with the new design before broader rollout. +- Features that depend on user behavior change. The team needs to see whether users adopt before declaring readiness. + +**Operational shape.** + +- Phase 1: limited rollout (5 to 10 percent of eligible users). 1 to 2 weeks. Heavy feedback collection. +- Phase 2: iteration based on phase 1 feedback. Could be days; could be weeks. +- Phase 3: expanded rollout (25 to 50 percent). 1 to 2 weeks. +- Phase 4: general availability. + +The total timeline is 4 to 8 weeks for a typical phased launch. Longer for major UX changes; shorter for feature additions. + +**Risky for.** + +- Features that need to be all-on for users to encounter them naturally. A change to the homepage hero needs to be either visible or not; phased rollout creates inconsistent experiences across users. + +--- + +## The decision framework + +Three factors. Pick the rollout that matches. + +### Factor 1: blast radius + +What happens if the feature breaks for a meaningful share of users? + +- **Low.** Optional new tool that users opt into. Bug affects only users who tried the new tool. +- **Medium.** New surface in an existing flow. Bug affects users mid-flow but not users on other paths. +- **High.** Critical path change. Bug affects most active users immediately. + +### Factor 2: confidence in correctness + +How confident is the team that the feature works. + +- **Low.** First time the team has built this kind of feature. Edge cases unknown. +- **Medium.** The team has built similar features before. Most edge cases anticipated. +- **High.** Iterative refinement of an existing feature. Behavior well-understood. + +### Factor 3: external commitments + +Is the launch date tied to external press, partner coordination, or a public commitment. + +- **None.** Internal team knows the rough timeline; no external coordination. +- **Soft.** Marketing has scheduled comms but the date can shift by a few days. +- **Hard.** Press is briefed for a specific day. Partner is coordinating launches. The date is fixed. + +### The decision matrix + +| Blast radius | Confidence | External commitment | Recommended pattern | +|---|---|---|---| +| Low | High | Hard | All-at-once | +| Low | High | Soft or none | All-at-once or gradual | +| Low | Medium | Any | Gradual | +| Low | Low | Any | Gradual or phased | +| Medium | High | Hard | Gradual fast | +| Medium | High | Soft or none | Gradual | +| Medium | Medium | Any | Gradual | +| Medium | Low | Any | Phased | +| High | High | Any | Gradual slow | +| High | Medium | Any | Gradual or flag-gated | +| High | Low | Any | Phased | + +The defaults. Most launches use gradual percentage rollout. The other patterns are for specific situations. + +--- + +## Cohort-specific rollout sequencing + +When using flag-gated cohort rollout, the sequence matters. + +**Internal users first.** Eat your own dog food. Catch the obvious issues before any external user sees them. + +**Free or trial users next.** Lower-stakes; if the feature has issues, the cost of a bad experience is lower than for paying customers. + +**Self-service paid users.** Customers who use the product without a sales rep. They will encounter the feature naturally; their feedback is high-quality. + +**Top accounts last (with sales-led briefing first).** Top accounts hear about the feature from their account executive before encountering it. By the time they have access, the feature is stable. + +Reverse the sequence in specific cases. + +- A feature designed specifically for enterprise customers should roll out to those customers first; the feedback is the design feedback. +- A feature gated by configuration that only enterprise customers complete should roll out to them first; otherwise the feature is invisible to the cohort that can use it. + +--- + +## What "rollback trigger" means + +A pre-defined rule that determines when the team rolls back without further debate. + +Examples. + +- Error rate above 1 percent sustained for 5 minutes. +- Latency above the pre-launch P95 by 50 percent for 10 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline for any cohort. +- Support tickets mentioning the feature exceed 50 in the first hour. + +The trigger fires automatically; the team executes the rollback without re-litigating whether to do it. + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate. + +The discipline. Define the trigger before launch. Write it down. Rehearse the rollback. Make the trigger automatic where possible (alerting plus on-call paging); make the rollback execution one command, not a multi-step process. diff --git a/skills/feature-launch-playbook/references/sales-enablement-template.md b/skills/feature-launch-playbook/references/sales-enablement-template.md new file mode 100644 index 0000000..07b7cca --- /dev/null +++ b/skills/feature-launch-playbook/references/sales-enablement-template.md @@ -0,0 +1,173 @@ +# Sales enablement template + +Battlecard, demo script, deal coaching, training session structure. For B2B; skip for B2C and PLG. + +The principle. Sales reps cannot pitch a feature they were briefed on yesterday. Enablement is the structured way to give sales the language and the mechanics they need to talk about the feature accurately and quickly. + +--- + +## When to skip this section + +For B2C products and PLG products without a sales motion, this section does not apply. The user is the buyer; there is no rep in the middle. Skip ahead to the support readiness checklist. + +For B2B products, this section is non-negotiable for Tier 1 launches and most Tier 2 launches. + +--- + +## The battlecard + +One page. Sales can read it in two minutes and pitch the feature in five. + +### Section 1: positioning summary + +Two to three sentences. The user-visible promise plus the target customer profile plus the differentiator vs the status quo. Pulled directly from the positioning canvas. + +### Section 2: target customer profile + +The specifics sales needs to qualify. Industry, company size, role of the buyer, role of the user (often different), use case, current pain. + +### Section 3: top objections and answers + +Three to five expected objections with the answer for each. The answers are written, not improvised; reps should be able to quote them back. + +Example. + +| Objection | Answer | +|---|---| +| "We already have a routing solution that works fine." | "Most solutions are keyword-based. Ours uses ML trained on the customer's actual routing decisions, so it adapts to their specific team structure. Customers report 95 percent accuracy vs 60 to 70 percent on keyword-based systems." | +| "How is this different from what [Competitor] just shipped?" | "Both products do automated routing. The difference: ours retrains weekly on the customer's data; theirs uses a fixed model. Customers with non-standard team structures see materially better routing on our system." | +| "What if the model gets it wrong?" | "Below the configurable confidence threshold, the ticket falls back to manual routing. Manager corrections feed back into the model, so accuracy improves over time." | + +### Section 4: proof points + +The same proof points from the positioning canvas. Three to five concrete capabilities or outcomes. + +### Section 5: deal coaching + +Specific guidance on how this affects deals. + +- **Deals to revisit.** Customers in the pipeline who were blocked by the gap this feature now closes. Names where appropriate. +- **Deals it complicates.** Customers on the existing pricing or feature set who may need migration support. Names where appropriate. +- **Common pricing questions.** What customers ask about cost; the answers reps should give. + +### Section 6: where to learn more + +Links to the demo recording, the full launch brief, the FAQ, the support documentation, and the PM contact for sales questions. + +--- + +## The demo script + +A repeatable demo the rep can run with a customer. + +### Structure + +**Open (1 minute).** State the customer's pain in their language. Reference what they told the rep in discovery (use a generic placeholder if the rep is in a first-call demo). + +**Show the problem (2 minutes).** Demonstrate the status quo workflow that the feature replaces. The rep walks through the manual process, naming the friction points. + +**Show the feature (5 minutes).** Walk through the feature solving the same workflow. Highlight the proof points. Pause at the moments where the customer would feel the difference. + +**Show the safety net (2 minutes).** Walk through the failure mode. What happens when the feature does not work perfectly. The customer needs to trust the safety net before they trust the feature. + +**Close (1 minute).** Summarize the value. Ask the customer what they think. Surface objections. + +**Total.** 11 minutes. Demos longer than 15 minutes lose attention; demos shorter than 7 minutes feel rushed. + +### The recorded demo + +For reps who join after the launch or who want a refresher, a recorded version of the demo. Same structure. Annotated with timestamps. Stored where reps can find it (sales enablement platform, shared drive, internal wiki). + +The recorded demo is not a substitute for the live demo with a customer. It is reference material for the rep. + +--- + +## Deal coaching guide + +Beyond the battlecard's deal-coaching section, a longer-form guide for the top sales scenarios. + +### Scenario 1: deal blocked by missing capability + +The rep has a customer in the pipeline who was blocked by a feature gap that this launch closes. Coaching. + +- Confirm the gap was the actual blocker via discovery questions before pitching the new feature. +- Reference the customer's specific pain in the demo. +- If the deal stalled with a competitor, address the competitor head-on with the differentiator section of the battlecard. +- Time the outreach. Reach out one to three days after public launch comms; the customer will already be aware of the announcement. + +### Scenario 2: existing customer expansion + +The rep has an existing customer using a smaller plan; this launch could justify expansion. Coaching. + +- The customer success team should brief the customer first if the customer is in a top-account tier. +- The rep follows up with an upgrade conversation tied to the specific value the customer gets from the new feature. +- Pricing change documentation if applicable; reps should not improvise pricing. + +### Scenario 3: defensive against churn + +The rep has a customer at risk of churning to a competitor whose product had the feature this launch adds. Coaching. + +- The customer success team should flag the at-risk customer; the rep delivers the briefing in coordination. +- Acknowledge the gap that existed; explain the timeline of the launch; show the feature. +- Offer migration support if the customer was already starting to evaluate the competitor. + +### Scenario 4: net-new pipeline + +The rep is targeting net-new prospects for whom the launch is a relevant capability. Coaching. + +- Lead with the launch as the recent product update; reference the blog post or release. +- Tie the feature to the buyer's expected pain. +- The launch announcement is the conversation starter; the demo is the conversion. + +--- + +## The training session + +Live, 30 minutes, with Q&A. Recorded for reps who cannot attend. + +### Structure + +**0 to 5 minutes.** PM walks through the positioning canvas. Target user, problem, promise, proof points, anti-positioning. + +**5 to 15 minutes.** PM (or sales-engineering partner) demos the feature using the demo script. Reps see what the rep version of the demo looks like. + +**15 to 25 minutes.** Q&A. Reps ask the questions they expect customers to ask. The answers feed back into the FAQ. + +**25 to 30 minutes.** Coaching on top deal scenarios. Brief discussion of which named accounts in the pipeline are affected. + +### After the session + +- Recording posted to the sales enablement platform. +- Q&A captured in the launch brief's FAQ section. +- Battlecard finalized with any new objections that surfaced. +- Demo script updated with any clarifications from the live demo. + +--- + +## What to skip + +Do not. + +- Hand sales a 12-page document and call it enablement. +- Train sales the morning of public launch. +- Skip the recorded demo because "we can do it live." +- Assume sales will read the launch brief before the customer call. + +The discipline. Sales enablement is short, opinionated, and rehearsed. Reps internalize it once and pitch the feature naturally for the rest of the launch period. + +--- + +## The "shadow launch" failure + +The pattern. + +- Feature ships. +- Sales hears about it from product team Slack. +- No battlecard. +- No demo recording. +- Sales reps either ignore the feature in customer conversations (because they cannot pitch it) or misrepresent it (because they are improvising). +- Customers churn or escalate when the feature does not match what they were told. + +The cost. Engineering investment is captured at zero or negative value. The next product team launch is met with sales skepticism. + +The fix. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. The battlecard takes a half day to write. The training session takes 30 minutes. The recorded demo takes an hour. The investment is small relative to the engineering investment behind the feature. diff --git a/skills/feature-launch-playbook/references/support-readiness-checklist.md b/skills/feature-launch-playbook/references/support-readiness-checklist.md new file mode 100644 index 0000000..50f031c --- /dev/null +++ b/skills/feature-launch-playbook/references/support-readiness-checklist.md @@ -0,0 +1,137 @@ +# Support readiness checklist + +Training, FAQ, escalation paths, monitoring access. The pattern of training support before customer-facing launch comms. + +The principle. Support is the first to encounter the failure modes of a new feature. They need the same context as sales but oriented toward post-purchase questions and incident resolution. + +--- + +## The four deliverables + +### 1. Training + +Live or recorded, with Q&A. + +The same content as the sales training, adapted for support workflows. Differences. + +- Sales pitches the feature; support solves problems with it. The training emphasizes how to diagnose customer issues, not how to position the feature. +- Sales sees the happy path; support sees the failure modes. The training includes the FAQ of expected support tickets and the escalation paths for unexpected ones. +- Sales has a 30-minute training; support often has 60 minutes because the breadth of expected questions is larger. + +Schedule. Support training one week before customer-facing launch comms. Recorded for reps who cannot attend live. + +### 2. FAQ document + +The questions that support expects customers to ask, with the answers. + +Categories. + +- **What does the feature do.** The basic explanation. Same content as the user-visible promise plus a short "how it works" paragraph. +- **How do I turn it on.** Configuration steps. Permissions required. Plan tier required. +- **What are the limits.** Rate limits, size limits, supported regions, supported plans. +- **What if it does not work.** Troubleshooting steps. When to escalate. +- **How do I turn it off.** For users who tried it and want to revert. Often forgotten until the first customer asks. +- **Pricing or billing questions.** If the feature affects billing, support needs the answer. + +The FAQ updates daily during the first week of launch as new questions surface. Support reps add questions they encountered to the FAQ; the PM reviews and approves daily. + +### 3. Escalation path + +When support cannot answer a question or solve an issue, who do they escalate to and how fast. + +The escalation contract. + +- **Tier 1 (in-product issue).** Support resolves with the customer using the FAQ and product knowledge. Target response: under 1 hour during business hours. +- **Tier 2 (product question support cannot answer).** Escalate to the PM. Target response from PM: same day during business hours. +- **Tier 3 (product is broken for the customer).** Escalate to engineering on-call. Target response from engineering: under 2 hours regardless of hours during launch week. + +For Tier 1 launches, the on-call rotation should include a launch-week PM contact in addition to the regular engineering on-call. + +### 4. Monitoring access + +Support reps should be able to verify whether a customer's issue is feature-specific. + +The minimum. + +- A dashboard showing feature health (overall error rate, feature-specific error rate, rollout percentage). +- A way to look up whether a specific customer is in the rollout cohort. (For flag-gated rollouts; some customers will not have access to the feature on launch day, and support needs to be able to confirm that.) +- A way to look up the customer's recent feature usage (or the lack thereof). + +Without monitoring access, support reps escalate every feature-related ticket to engineering or the PM. The escalation queue gets noisy; real Tier 3 issues get drowned in Tier 2 questions. + +--- + +## The training-before-comms rule + +The discipline. Support training happens before customer-facing comms launch. + +The reason. Customers will start asking support about the feature within minutes of the public announcement. Support needs to be ready before customers ask, not while customers are asking. + +The pattern. + +- Day T minus 7: support training delivered. FAQ published internally. Escalation paths confirmed. +- Day T minus 1: support team huddle. Last-minute questions. FAQ refresh. +- Day T (launch day): support staffed for elevated volume. PM and engineering on-call paths confirmed open. + +The "training day-of" failure. Support is trained the morning of public launch. By the afternoon, they have already encountered three customer questions they cannot answer well. The support team's confidence with the feature degrades; customers feel the rep does not know the product. Trust loss. + +--- + +## The "support is overwhelmed" failure + +The setup. The launch generates more support volume than the team expected. The feature is novel; customers ask many basic questions; the FAQ does not anticipate the actual questions; support reps escalate everything to the PM. + +The signs. + +- Support ticket queue length doubles or triples on launch day vs the prior week. +- Tickets tagged with the feature exceed the support team's capacity for new conversations. +- The PM's Slack is full of support questions that should have FAQ answers. + +The fix. + +- Pre-launch: estimate support volume. Look at ticket volume from prior comparable launches; double the estimate. +- Pre-launch: staff support for the launch window. Pull in cross-functional help if needed. +- Pre-launch: write the FAQ deeper than feels necessary. Most launches have 20 to 30 expected questions; document them all in advance. +- Launch day: PM is available for FAQ updates throughout the day. New questions get answers within an hour and propagate to support. + +--- + +## What support needs that sales does not + +Two specific differences. + +**Failure modes documentation.** Support needs to know what happens when the feature breaks. The error messages users see, the recovery flows, the limitations. Sales does not need this depth; support requires it. + +**Customer-facing language for limits.** Sales pitches the feature and addresses the limits at the negotiation stage. Support encounters the limits the moment a customer hits them. Support reps need pre-written language for "the feature supports up to X; for higher volumes, contact your account manager." + +Without these two, support is improvising at the moment of customer pain. Improvisation produces inconsistent answers across reps; customers compare notes and lose trust. + +--- + +## The post-launch FAQ refresh cycle + +For two to four weeks post-launch, the FAQ refreshes daily. + +- Support reps log new questions they encountered, with the answers they gave. +- PM reviews daily, approves or corrects answers, adds them to the canonical FAQ. +- Support team gets a daily summary of new FAQ entries. + +After two to four weeks, the FAQ stabilizes. The refresh moves to weekly, then monthly. + +The cost of the daily refresh is small. The benefit is that support builds confidence with the feature in the first month, instead of struggling for the first quarter. + +--- + +## When support flags an issue larger than a question + +Sometimes the support volume on a feature reveals a real problem with the feature, not just a need for better FAQ. + +Signs. + +- Many customers ask the same question, and the answer is "the feature does not do that." The customers expected something the feature does not deliver. Positioning was misaligned. +- Many customers report the same bug. The bug is real and affects a meaningful share of users. +- Support tickets cluster on a specific cohort (e.g., users on a specific plan, in a specific region). The feature does not work correctly for that cohort. + +The pattern. Support is the early-warning system for launch quality. The PM should review the support ticket digest daily during the first week and at least weekly thereafter. If the support volume reveals a feature problem, the launch may need to pause for a fix before further rollout. + +The discipline of treating support as a quality signal is the cheapest way to catch launch problems before they show up in revenue or churn metrics. diff --git a/skills/form-strategy/SKILL.md b/skills/form-strategy/SKILL.md new file mode 100644 index 0000000..75b63cb --- /dev/null +++ b/skills/form-strategy/SKILL.md @@ -0,0 +1,257 @@ +--- +name: form-strategy +description: "Design forms that convert, validate well, resist spam, and integrate cleanly with downstream systems. Use this skill when designing or auditing any form (contact, signup, checkout, multi-step, embedded), planning validation logic, fighting spam, choosing form tooling, or improving form conversion. Triggers on form design, form validation, form conversion, multi-step form, form spam, captcha, honeypot, form abandonment, signup form, contact form. Also triggers when form completion rates are low or spam is overwhelming." +category: cross-cutting +catalog_summary: "Form design, validation patterns, spam prevention, conversion tuning" +display_order: 1 +--- + +# Form Strategy + +Forms are where intent becomes action. Design them well or lose conversions, frustrate users, and drown in spam. Stack-agnostic. + +--- + +## When to use + +- Designing or redesigning a form +- Conversion is dropping on a key form +- Spam volume is overwhelming the inbox or database +- Auditing forms across a site +- Planning validation logic +- Choosing form tooling (form service, custom build, no-code) +- Integrating forms with CRM, email, or other downstream systems +- Multi-step form decisions + +## When NOT to use + +- Generic conversion optimization (use `cro-optimization`) +- The copy on the form (use `landing-page-copy`) +- Backend handling beyond form-specific concerns (use `frontend-component-build`, `code-review-web`) +- General accessibility (use `accessibility-audit`) + +--- + +## Required inputs + +- The form's purpose (what action, what outcome) +- Current form (URL, screenshot, or fields) +- Current performance (completion rate, spam rate, conversion to next step) +- Downstream system (where submissions go: CRM, email, database, support tool) +- Business context (volume, urgency of leads, cost of false vs missed signups) + +--- + +## The framework: 5 dimensions + +Every form decision falls into one of these dimensions. + +### Dimension 1: Field strategy + +The biggest lever. Every additional field reduces conversion. + +**Questions to ask for each field:** +- Is this required to deliver value to the user? +- Is this required to deliver value to the business? +- Can it be inferred from another source (email domain, behavior, context)? +- Can it be asked later (after first contact, on second visit, on settings page)? + +**Default rule:** ask for the minimum to make the next step happen. Everything else later. + +For a B2B contact form: name and email get you started. Phone, company size, role are nice-to-haves that often hurt conversion more than they help qualification. + +For a checkout: country, postal code, address, name, payment. Anything else (referral source, marketing opt-in, account creation) is optional or moved to post-purchase. + +### Dimension 2: Field design + +How each field looks and behaves. + +- **Labels above inputs** beat placeholders. Placeholder labels disappear when typing. +- **Inline labels** (floating labels) work for very compact forms. +- **Single column** for almost every form. Eyes flow vertically. +- **Logical grouping** with visible spacing. Don't put unrelated fields next to each other. +- **Right input type:** `email` for emails, `tel` for phone, `number` for numbers, `date` for dates. Mobile keyboards adapt. +- **Autocomplete attributes:** `autocomplete="email"`, `autocomplete="given-name"`, etc. Browsers and password managers fill them in. +- **Sensible defaults** for fields where one applies (country pre-selected by IP, etc.). Don't default to anything that would mislead if wrong. + +### Dimension 3: Validation + +Tell users what's wrong, when, and how to fix it. + +- **Validate on blur, not on every keystroke.** Inline errors that appear as someone types are jarring. +- **Re-validate on submit** (catch fields the user skipped). +- **Specific messages:** "Email must include @" beats "Invalid email." +- **Position errors next to the field** they refer to. +- **Don't submit a form when there are errors.** Highlight the first errored field. Scroll to it. +- **Validate server-side too.** Client validation is UX. Server validation is correctness. + +For format-flexible fields (phone numbers, postal codes), validate liberally. Reject only what's clearly wrong, not what's "non-standard." Many phone formats exist. + +### Dimension 4: Spam defense + +Public forms attract spam. Plan for it from day one. + +**Layered defense:** + +1. **Honeypot field.** A hidden field that humans don't fill in but bots do. If it's filled, reject silently. Free, low-friction, surprisingly effective for low-effort spam. +2. **Time-based detection.** Reject submissions completed in under 2-3 seconds (bots) or after very long delays (suspicious sessions). +3. **Rate limiting.** Reject if the same IP submits too many times. +4. **CAPTCHA as a last resort.** Modern invisible CAPTCHAs (hCaptcha, reCAPTCHA v3, Turnstile) are low-friction. Old image CAPTCHAs are conversion-killers. +5. **Behavioral signals.** Did the cursor move? Was there scroll? Modern services track this. +6. **Content filtering.** Reject obvious spam content (links, foreign-language content if your audience is local, common spam words). +7. **Server-side review.** A queue rather than direct delivery to inboxes for high-spam-target forms. + +For most contact forms: honeypot + time check + Turnstile (or similar) is sufficient. + +### Dimension 5: Submission flow + +What happens after submit. + +- **Inline success message** for short forms. Don't redirect just to confirm. +- **Confirmation page** for high-value submissions (to provide next steps, set expectations). +- **Email confirmation** for signups, purchases, RSVPs. Always. +- **Save data on errors** so the user doesn't re-enter everything. +- **Optimistic UI** (show success before the server confirms) for low-stakes forms; risky for high-stakes. + +For multi-step forms: +- Show progress (3 of 5) +- Save state between steps (in case of refresh or navigation) +- Allow back navigation without losing data +- Validate per step, not just at the end + +--- + +## Workflow + +### Step 1: Audit current state + +For each form on the site: +- What's its purpose? +- Number of fields, required vs optional +- Current completion rate +- Current spam rate +- Validation rules +- What happens after submit +- Where the data goes downstream + +### Step 2: Define success per form + +Different forms have different success metrics: +- Lead form: qualified leads (defined by sales) +- Newsletter: confirmed subscriptions (after double opt-in) +- Contact: substantive replies (not just submissions) +- Checkout: successful payments + +Track the metric that matters, not just submissions. + +### Step 3: Cut fields ruthlessly + +Apply the field strategy filter. For each field, answer: +- Required to deliver value? Keep. +- Nice to have? Move to optional or later. +- Used for routing or qualification? Often can be inferred. + +A 7-field form becomes a 3-field form. Conversion rises. + +### Step 4: Set up spam defense + +Before launching a public form: +- Add a honeypot field +- Add time-based detection +- Add rate limiting +- Add a modern CAPTCHA if the form is high-traffic or high-spam + +After launch, monitor. Tune layers based on what's actually getting through. + +### Step 5: Improve validation + +Walk through each field: +- Is validation specific? +- Does it run at the right time (blur or submit, not on keystroke)? +- Are error messages actionable? +- Is server-side validation matching client-side? + +### Step 6: Verify accessibility + +Critical baseline: +- Every input has an associated label (visually visible or `aria-label`) +- Errors are associated with inputs (`aria-describedby`, `aria-invalid`) +- Focus order matches visual order +- Color isn't the only way to indicate errors +- Form is fully keyboard-navigable + +See `accessibility-audit` for the full WCAG audit. + +### Step 7: Test downstream + +Submit the form. Verify: +- Data lands where it should +- Required fields are populated correctly +- Spam defenses are working (test with a script) +- The user gets the confirmation they expect +- Internal notification is timely + +Forms break silently when downstream systems change. Test after any integration update. + +### Step 8: Monitor + +- Completion rate over time +- Spam rate over time +- Errors per submission (high errors = bad UX) +- Drop-off field (where do people abandon?) + +--- + +## Failure patterns + +**Too many fields.** Most B2B contact forms have 3x more fields than they need. Cut. + +**Validation that fires while typing.** Annoying. Causes errors before the user has finished. + +**Generic error messages.** "Invalid input." Where? Why? Be specific. + +**Required fields not marked.** Users discover they're required only after submission fails. Mark required (or, for short forms, mark optional). + +**Autocomplete disabled.** "For security." It's almost never a security improvement and always a UX cost. Leave autocomplete on. + +**Tab order is broken.** Tab key skips fields or jumps backward. Set `tabindex` only when necessary; use natural DOM order. + +**Submit button below the fold.** Especially on mobile. Users don't see it. + +**No save on error.** User submits, has one error, returns to the form, all fields empty. Nightmare. Save the state. + +**Captcha as the only spam defense.** Captchas are friction. Layered defense beats brute-force friction. + +**Captcha visible by default.** Modern CAPTCHAs (Turnstile, reCAPTCHA v3) are invisible most of the time and only escalate when needed. Use those. + +**Newsletter signup that's actually a marketing list.** Honor opt-in scope. If the user signed up for product updates, don't add them to the marketing newsletter. + +**Confirmation page that's a dead end.** "Thanks for submitting" with no next step. What now? Provide an action (read related content, return to homepage, follow on social). + +**No double opt-in for marketing email.** Bots and typos pollute the list. See `email-deliverability` for why this matters. + +**Email field accepting `name@` as valid.** Browser spec validation is loose. Validate against an actual format. + +**Custom date pickers worse than native.** The native `<input type="date">` is now good on most platforms. Don't reinvent unless you have a specific reason. + +**Forms that lose state on refresh.** For long forms, save to localStorage and restore on load. + +--- + +## Output format + +A form audit document includes: + +- **Form inventory:** every form on the site +- **Per-form review:** purpose, fields, performance +- **Recommendations:** field cuts, validation improvements, spam defense, design changes +- **Spam defense plan:** layers per form +- **Accessibility status:** WCAG compliance per form +- **Downstream integration map:** where each form's data goes +- **Monitoring plan:** what's tracked + +--- + +## Reference files + +- [`references/form-anatomy-checklist.md`](references/form-anatomy-checklist.md): A field-by-field, behavior-by-behavior checklist for auditing or designing a form, covering structure, accessibility, validation, and spam defense. diff --git a/skills/form-strategy/references/form-anatomy-checklist.md b/skills/form-strategy/references/form-anatomy-checklist.md new file mode 100644 index 0000000..14f651f --- /dev/null +++ b/skills/form-strategy/references/form-anatomy-checklist.md @@ -0,0 +1,243 @@ +# Form Anatomy Checklist + +A field-by-field, behavior-by-behavior checklist for auditing or designing a form. Walk through it for any form before shipping. + +--- + +## Overall structure + +- [ ] **Purpose is clear** from headline, subheadline, or surrounding context +- [ ] **Single column** layout (multi-column forms are slower to scan and complete) +- [ ] **Form is reasonably short** (cut fields you don't strictly need) +- [ ] **Required vs optional** is clear (mark one or the other based on which is shorter) +- [ ] **Logical grouping** of related fields with visible spacing +- [ ] **Submit button** is visible without scrolling on common viewports +- [ ] **Submit button text** is specific to the action ("Get the report" beats "Submit") + +--- + +## Per-field checklist + +For each field, verify: + +### Label + +- [ ] Has a visible label (or, for compact forms, a clearly associated visible cue) +- [ ] Label is **above** the input (preferred) or floats (acceptable for compact) +- [ ] Label is descriptive (not just the field name from the database) +- [ ] Label is associated with the input via `for=` and `id=` or a wrapping `<label>` + +### Input type + +- [ ] Uses semantic input type: + - `email` for emails + - `tel` for phone + - `number` for numeric (when not formatted, like a count or amount) + - `date` for dates + - `url` for URLs + - `text` for general +- [ ] Native input where possible (date, color, range) before custom widgets +- [ ] `inputmode` attribute set when it differs from type (e.g., `inputmode="decimal"` on a price) + +### Autocomplete + +- [ ] `autocomplete=` attribute set with the appropriate value + - `name`, `given-name`, `family-name` + - `email` + - `tel` + - `street-address`, `address-line1`, `postal-code`, `country` + - `cc-name`, `cc-number`, `cc-exp`, `cc-csc` + - `current-password`, `new-password` +- [ ] Doesn't disable autocomplete without good reason + +### Validation + +- [ ] Validates on blur, not on every keystroke +- [ ] Validates again on submit (in case fields were skipped) +- [ ] Error message is specific ("Email must include @" not "Invalid") +- [ ] Error message appears next to the field +- [ ] Error state is visually distinct (not just color; also icon or pattern) +- [ ] `aria-invalid="true"` on errored fields +- [ ] `aria-describedby` linking the field to its error message + +### Server-side validation + +- [ ] Server validates everything client validates (client validation is UX, server is correctness) +- [ ] Server validates fields the client can't (uniqueness, business rules, etc.) +- [ ] Server returns specific error messages +- [ ] Server is the source of truth for "save" + +### Hint text + +- [ ] If a field needs explanation, hint text is below the field (not in placeholder) +- [ ] Hint text uses `aria-describedby` to associate with the input +- [ ] Hint text doesn't contain critical info that would be missed if not read + +### Required vs optional + +- [ ] Marked clearly (consistently use either "required" markers or "optional" markers, not both) +- [ ] `required` attribute set on truly required fields +- [ ] Required fields announced to assistive tech (the `required` attribute does this) +- [ ] Field has a fallback if accidentally skipped (server validation catches it gracefully) + +### Width + +- [ ] Field width matches expected input length (don't make a postal code field as wide as a name field) +- [ ] Mobile field width is full-width minus reasonable margins + +### Specific field types + +**Password:** +- [ ] `autocomplete="current-password"` for login, `"new-password"` for signup +- [ ] Toggle to show password (not in lieu of, but in addition to, dots) +- [ ] Length and complexity hints visible before typing +- [ ] Allow long passphrases (no max length under 64+ chars) + +**Email:** +- [ ] `type="email"` and `autocomplete="email"` +- [ ] Server validates format more strictly than the browser default +- [ ] Confirms for high-stakes use (with a second email field) or relies on confirmation email + +**Phone:** +- [ ] `type="tel"` and `autocomplete="tel"` +- [ ] Liberal validation (accept various formats) +- [ ] Country code handling if international + +**Date:** +- [ ] `type="date"` for native picker, or a well-tested custom picker +- [ ] Timezone handling thought through (server side) + +**Address:** +- [ ] Multiple fields (line 1, line 2, city, region, postal code, country) +- [ ] `autocomplete` on each +- [ ] Validation by country (US ZIP differs from UK postcode) +- [ ] Optional autocomplete via address API for high-conversion forms + +**File upload:** +- [ ] Accepted types declared with `accept=` +- [ ] Size limit communicated and enforced (client and server) +- [ ] Drag-and-drop and click-to-browse both work +- [ ] Selected file feedback (name, size, preview if image) +- [ ] Progress indicator for slow uploads +- [ ] Server scans uploads if user-generated content goes public + +**Select / dropdown:** +- [ ] Native `<select>` for short lists (under ~15 options) +- [ ] Custom searchable component for long lists +- [ ] Default option that's not selectable (e.g., "Select a country") +- [ ] Sort by likelihood (popular options first), or alphabetical, not random + +**Radio buttons:** +- [ ] Use for 2-7 mutually exclusive options +- [ ] All options visible (no scrolling) +- [ ] One option pre-selected only if a sensible default exists + +**Checkboxes:** +- [ ] Use for boolean choices and multi-select +- [ ] Label is clickable (associated with checkbox) +- [ ] Marketing opt-ins are off by default (legal requirement in many regions) +- [ ] Terms-of-service is unchecked by default (active acceptance) + +**Multi-step forms:** +- [ ] Progress indicator (3 of 5) +- [ ] State saved between steps (refresh-resilient) +- [ ] Back navigation doesn't lose data +- [ ] Validation per step +- [ ] Final review step before submit (high-stakes only) + +--- + +## Spam defense + +- [ ] Honeypot field (hidden, must remain empty) +- [ ] Time-based detection (reject very fast or very slow submissions) +- [ ] Rate limiting per IP / per session +- [ ] Modern CAPTCHA (Turnstile, hCaptcha invisible, reCAPTCHA v3) if needed +- [ ] Server-side spam content filtering for high-volume forms +- [ ] Logging of rejected submissions for tuning + +--- + +## Accessibility + +- [ ] Form is fully keyboard-navigable (Tab, Shift+Tab, Enter to submit) +- [ ] Tab order matches visual order +- [ ] Focus is visible (don't remove the focus outline) +- [ ] Form errors are announced to screen readers +- [ ] Color contrast meets WCAG (4.5:1 for text, 3:1 for UI) +- [ ] Errors aren't communicated only by color +- [ ] Form works at 200% zoom +- [ ] Touch targets at least 44px on mobile +- [ ] No time limits without warning and the option to extend + +--- + +## Submission + +- [ ] Submit button is disabled while submission is in flight (prevent double-submit) +- [ ] Loading state on the button or near the form +- [ ] Success state is clear (inline message, redirect to confirmation page, or both) +- [ ] Failure state is clear (specific reason, what to do, support contact) +- [ ] State preserved on submission failure (user doesn't lose data) +- [ ] Email confirmation sent for signups, purchases, RSVPs +- [ ] Internal notification (if applicable) is timely + +--- + +## Privacy and compliance + +- [ ] Privacy notice or link visible near the form +- [ ] Terms of service link if relevant +- [ ] Marketing consent (where required by jurisdiction) is explicit and unchecked by default +- [ ] Data sent over HTTPS only +- [ ] Sensitive fields (passwords, payment) not autofilled by URL params (don't appear in browser history) + +--- + +## Performance + +- [ ] Form loads quickly (lazy-load any heavy assets like CAPTCHAs until needed) +- [ ] Submit handler doesn't block the UI +- [ ] No unnecessary fetches on field interaction +- [ ] CAPTCHA loads asynchronously + +--- + +## Monitoring + +- [ ] Completion rate tracked +- [ ] Field-level drop-off tracked (where do people abandon?) +- [ ] Errors tracked (which fields cause the most errors?) +- [ ] Spam rate tracked (compare layers of defense over time) +- [ ] Submission failures tracked (server errors, integration failures) + +--- + +## Pre-launch test + +Before publishing a form publicly: + +- [ ] Submit successfully with valid data +- [ ] Submit unsuccessfully with bad data (verify error UX) +- [ ] Submit with no data (verify required-field UX) +- [ ] Submit with the honeypot filled (verify silent rejection) +- [ ] Submit very fast (verify time-based rejection) +- [ ] Submit on mobile (verify mobile UX) +- [ ] Submit with keyboard only (verify accessibility) +- [ ] Submit with a screen reader (verify announcements) +- [ ] Submit with autocomplete enabled (verify it works) +- [ ] Verify data lands in the correct downstream system +- [ ] Verify confirmation email arrives (if applicable) +- [ ] Verify internal notification arrives (if applicable) +- [ ] Try to submit duplicate (verify deduplication if applicable) + +--- + +## Post-launch review (after first week) + +- [ ] Completion rate vs target +- [ ] Spam rate (tune defense if needed) +- [ ] Errors (most common errors? could be UX problems) +- [ ] Drop-off (which field loses people?) +- [ ] Downstream system happy? (CRM data clean, no broken integrations) +- [ ] Customer reports (anyone reporting a broken form?) diff --git a/skills/frontend-component-build/SKILL.md b/skills/frontend-component-build/SKILL.md new file mode 100644 index 0000000..fb5f5f7 --- /dev/null +++ b/skills/frontend-component-build/SKILL.md @@ -0,0 +1,184 @@ +--- +name: frontend-component-build +description: "Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with proper states and accessibility. Triggers on build a component, create a button, create a modal, create a form input, component API, props design, component states, refactor component, accessible component. Also triggers when implementing UI from a design that needs to be reusable." +category: development +catalog_summary: "Component architecture, props design, accessibility from the start" +display_order: 2 +--- + +# Frontend Component Build + +Build production-ready components. Stack-agnostic principles. Most patterns translate to React, Vue, Svelte, or vanilla web components. + +This skill is about implementing a component well. For broader system design see `design-system`. For day-to-day visual decisions see `design-standards`. + +--- + +## When to use + +- Building a new component from scratch +- Refactoring an existing component +- Designing a component API (props, slots, events) +- Adding accessibility to an existing component +- Implementing a component from a design + +## When NOT to use + +- Building a full design system (use `design-system`) +- Page-level design decisions (use `design-standards`) +- Backend or data work (use `code-review-web`) +- Performance-only optimization (use `performance-optimization`) + +--- + +## Required inputs + +- The component's purpose (what UI need it serves) +- The design (or willingness to design it) +- The framework or technical context +- The states the component must support +- Accessibility requirements + +--- + +## The framework: 6 dimensions + +A complete component handles six dimensions. Skip any one and the component is incomplete. + +### 1. Anatomy + +Identify the parts that make up the component before writing any markup. + +**Common anatomies:** +- Button: container + label + (optional) icon + (optional) loading indicator +- Modal: backdrop + container + header + body + footer + close affordance +- Form input: label + input + (optional) help text + (optional) error message +- Card: container + (optional) header + body + (optional) footer + (optional) media + +Naming the parts up front makes the API obvious. + +### 2. Variants + +What variations does the component support? + +- **Visual variants** (primary, secondary, ghost, danger) +- **Size variants** (small, medium, large) +- **Functional variants** (with icon, without icon, icon-only) + +Variants should be a managed set, not a free-for-all. Document the supported set; reject requests for new variants without a real use case. + +### 3. States + +What states must the component handle? + +- **Default** +- **Hover** (when pointer is supported) +- **Focus** (always - keyboard navigation requires it) +- **Active / pressed** +- **Disabled** +- **Loading** (where applicable) +- **Error** (for inputs, forms, validation-bound components) +- **Empty** (for components that display data) + +Every state needs visual treatment AND accessibility treatment. + +### 4. Props / API + +Design the component's contract. + +**API design principles:** + +- **Required props minimal.** What's truly needed every time? That's required. Everything else has a sensible default. +- **Boolean props are red flags.** Three booleans means seven combinations. Prefer enum strings: `variant: "primary" | "secondary" | "ghost"` over `primary={true} ghost={false}`. +- **Children > props.** Where content is content, accept children. Don't invent `headerText` and `bodyText` props when slots work. +- **Composition > configuration.** A component that does 5 things via 12 props often should be 5 smaller components. +- **Type the props.** TypeScript or PropTypes or JSDoc. The type is documentation that won't go out of date. + +### 5. Accessibility + +Build it accessible from the start. Adding accessibility later is 5x harder. + +**Universal:** +- Semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<form>`, etc.) over generic `<div>` +- Keyboard navigable (Tab, Shift+Tab, Enter/Space for buttons) +- Focus visible +- Tap targets minimum 44 by 44 pixels +- ARIA only where semantic HTML is insufficient + +**Component-specific:** + +- **Button:** use `<button>`. Don't fake one with a `<div>`. +- **Modal:** focus trap, ESC to close, returns focus to trigger on close, `role="dialog"` and `aria-labelledby`. +- **Form input:** label associated via `for`/`id` or `aria-labelledby`. Error messages linked via `aria-describedby`. `aria-invalid` when in error state. +- **Toggles:** `<button>` with `aria-pressed` for two-state, or `role="switch"` for on/off. +- **Tabs:** `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected` and arrow-key navigation. +- **Tooltips and popovers:** triggered by focus AND hover. Dismissible with ESC. +- **Loading states:** announce with `aria-live` so screen readers know something changed. + +### 6. Tests + +Verify the component works before declaring it done. + +**Test types by priority:** + +1. **Visual regression.** Renders correctly across variants and states. (Storybook + visual diff tools, or manual screenshots.) +2. **Accessibility.** Passes axe or equivalent automated checks. +3. **Keyboard navigation.** Tab, Enter, Escape, arrow keys all work as expected. +4. **Component logic.** Props produce expected output. Events fire correctly. (Unit tests.) +5. **Integration.** Component works inside its expected parent contexts. + +A component without at least automated accessibility testing is not done. + +--- + +## Workflow + +1. **Understand the use case.** What UI need does this component serve? Where will it appear? Adjacent components? +2. **Sketch the anatomy.** Name the parts. +3. **List variants and states.** Match the design system or define new ones if needed. +4. **Design the API.** Required props, optional props, children, events. Type it. +5. **Build the markup with semantic HTML.** Choose the right elements. Avoid generic `<div>` for interactive things. +6. **Style with tokens.** No hardcoded colors, spacing, or sizes. +7. **Add interaction.** Focus management, keyboard handlers, ARIA. +8. **Add states.** Hover, focus, active, disabled, loading, error. +9. **Test.** Automated accessibility, keyboard navigation, visual regression. +10. **Document.** Usage, API, examples, anti-patterns. + +--- + +## Failure patterns + +- **Building with `<div onClick>`.** Loses keyboard accessibility, screen reader semantics, and focus. Use `<button>` or `<a>`. +- **Hardcoding colors and sizes.** Tokens exist for a reason. Hardcoded values resist theming and consistency. +- **Boolean prop explosion.** `<Button primary large rounded fullWidth disabled icon />`. Too many booleans means you actually need fewer variants designed more thoughtfully. +- **Forgetting focus states.** Hover gets attention; focus gets neglected. Keyboard users see invisible buttons. +- **Skipping disabled-state thought.** A disabled button should look obviously disabled AND be `aria-disabled` AND not respond to clicks. +- **Inventing ARIA.** ARIA roles and properties have specific behaviors. Made-up ARIA is worse than no ARIA. Use semantic HTML first. +- **Loading state that doesn't announce.** Screen readers don't know the spinner appeared. Use `aria-live="polite"` or `role="status"`. +- **Tooltip-only critical content.** Hover-only content is invisible to keyboard and touch users. Critical content goes in the visible UI. +- **Component without docs.** Future-you, your teammate, or the next maintainer cannot use what they cannot understand. + +--- + +## Output format + +A complete component delivery includes: + +- **Component code** (in the appropriate framework) +- **Storybook (or equivalent) entry** showing all variants and states +- **Documentation:** + - Anatomy diagram or description + - Props/API table + - Usage examples (basic, advanced, edge cases) + - When to use vs. when to use an alternative + - Anti-patterns (what to avoid) + - Accessibility notes +- **Tests** (visual regression + accessibility + logic) + +--- + +## Reference files + +- [`references/component-spec-template.md`](references/component-spec-template.md) - Template for documenting a component (props, states, accessibility, edge cases) before building. +- [`references/component-api-patterns.md`](references/component-api-patterns.md) - Common patterns for designing flexible component APIs (compound components, controlled vs uncontrolled, polymorphic `as` prop, render props, slots). +- [`references/accessibility-patterns.md`](references/accessibility-patterns.md) - ARIA patterns for common interactive components. diff --git a/skills/frontend-component-build/references/accessibility-patterns.md b/skills/frontend-component-build/references/accessibility-patterns.md new file mode 100644 index 0000000..d32ab58 --- /dev/null +++ b/skills/frontend-component-build/references/accessibility-patterns.md @@ -0,0 +1,354 @@ +# Accessibility Patterns + +ARIA patterns for common interactive components. Each follows the WAI-ARIA Authoring Practices guidelines. + +When in doubt, use semantic HTML. Reach for ARIA only when semantic HTML cannot express what's needed. + +--- + +## Button + +```html +<button type="button"> + Click me +</button> +``` + +That's it. Don't reinvent it. + +**For buttons that toggle a state:** +```html +<button type="button" aria-pressed="false"> + Bookmark +</button> +``` +Toggle `aria-pressed` between `"true"` and `"false"` on click. + +**For buttons that disclose content:** +```html +<button type="button" aria-expanded="false" aria-controls="menu-1"> + Menu +</button> +<ul id="menu-1" hidden>...</ul> +``` +Toggle `aria-expanded` and `hidden` together. + +**Anti-patterns:** +- `<div onClick>` instead of `<button>` +- Buttons that look like buttons but use `<a href="#">` +- Missing `type="button"` (defaults to `type="submit"` inside forms, causing accidental submits) + +--- + +## Link + +```html +<a href="/destination"> + Link text +</a> +``` + +**For external links opening in new tab:** +```html +<a href="https://external.com" target="_blank" rel="noopener noreferrer"> + External site +</a> +``` + +**Anti-patterns:** +- `<a>` without `href` (breaks keyboard navigation; use `<button>` instead) +- `<a href="#">` for buttons (causes URL pollution and unexpected behavior) +- Generic link text ("click here," "read more") + +--- + +## Form input with label + +```html +<div> + <label for="email">Email address</label> + <input id="email" type="email" name="email" required /> + <p id="email-help">We'll never share your email.</p> +</div> +``` + +**With help text linked:** +```html +<input id="email" type="email" aria-describedby="email-help" /> +<p id="email-help">We'll never share your email.</p> +``` + +**With error state:** +```html +<input + id="email" + type="email" + aria-invalid="true" + aria-describedby="email-error" +/> +<p id="email-error" role="alert">Please enter a valid email.</p> +``` + +**Anti-patterns:** +- Placeholder as label (placeholder disappears on input, leaving field unlabeled) +- Label not associated (visual proximity isn't enough) +- Error indicated by color only (color-blind users miss it) + +--- + +## Modal / dialog + +```html +<div + role="dialog" + aria-modal="true" + aria-labelledby="dialog-title" + aria-describedby="dialog-description" +> + <h2 id="dialog-title">Confirm action</h2> + <p id="dialog-description">Are you sure you want to delete this?</p> + <button type="button" data-close>Cancel</button> + <button type="button" data-confirm>Delete</button> +</div> +``` + +**Behavior requirements:** +- Trap focus inside the modal while open +- Return focus to the trigger element on close +- Close on Escape key +- Close on backdrop click (optional, but expected) +- Background content should be inert (`inert` attribute or `aria-hidden`) +- Body scroll locked while modal is open + +**Anti-patterns:** +- Modal without focus trap (Tab escapes to background page) +- Modal without `aria-modal` and `role="dialog"` +- Modal that doesn't return focus on close +- Background content remains tabbable + +--- + +## Disclosure (accordion section) + +```html +<button + type="button" + aria-expanded="false" + aria-controls="section-1" +> + Section title +</button> +<div id="section-1" hidden> + Section content... +</div> +``` + +For full accordion (multiple disclosures, optionally limit one open at a time), repeat the pattern. + +--- + +## Tabs + +```html +<div role="tablist" aria-label="Settings sections"> + <button + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0" + > + Profile + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1" + > + Notifications + </button> +</div> + +<div role="tabpanel" id="panel-1" aria-labelledby="tab-1"> + Profile content... +</div> +<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden> + Notifications content... +</div> +``` + +**Behavior requirements:** +- Arrow keys navigate between tabs +- Active tab has `aria-selected="true"` and `tabindex="0"` +- Inactive tabs have `aria-selected="false"` and `tabindex="-1"` +- Selecting a tab shows the corresponding panel +- Home / End keys jump to first / last tab + +--- + +## Toggle switch + +```html +<button + type="button" + role="switch" + aria-checked="false" + id="darkmode-toggle" +> + <span class="visually-hidden">Dark mode</span> +</button> +<label for="darkmode-toggle">Dark mode</label> +``` + +Toggle `aria-checked` between `"true"` and `"false"` on click. + +**Alternatively, use a real checkbox styled as a switch:** +```html +<label> + <input type="checkbox" role="switch" /> + Dark mode +</label> +``` + +--- + +## Combobox / autocomplete + +```html +<label for="city">City</label> +<input + id="city" + type="text" + role="combobox" + aria-autocomplete="list" + aria-controls="city-listbox" + aria-expanded="false" + autocomplete="off" +/> +<ul id="city-listbox" role="listbox" hidden> + <li role="option" id="city-1" aria-selected="false">London</li> + <li role="option" id="city-2" aria-selected="false">Lagos</li> +</ul> +``` + +**Behavior requirements:** +- Down arrow opens listbox +- Arrow keys navigate options +- Enter selects highlighted option +- Escape closes listbox +- `aria-activedescendant` on the input points to highlighted option +- Type-ahead filtering + +This is one of the most complex patterns. Test thoroughly with screen readers. + +--- + +## Menu / menubar + +```html +<button + type="button" + aria-haspopup="menu" + aria-expanded="false" + aria-controls="user-menu" +> + Account +</button> +<ul role="menu" id="user-menu" hidden> + <li role="menuitem" tabindex="-1"><a href="/profile">Profile</a></li> + <li role="menuitem" tabindex="-1"><a href="/settings">Settings</a></li> + <li role="menuitem" tabindex="-1"><a href="/logout">Sign out</a></li> +</ul> +``` + +**Behavior requirements:** +- Down arrow / up arrow navigate menu items +- Escape closes menu +- Click outside closes menu +- Focus returns to trigger on close + +**Important:** `role="menu"` is for command-style menus (like a desktop application's File menu). For navigation, use `<nav>` with regular links instead. + +--- + +## Loading and live regions + +```html +<div role="status" aria-live="polite"> + Loading results... +</div> +``` + +Use `role="status"` (or `aria-live="polite"`) for non-urgent updates. +Use `role="alert"` (or `aria-live="assertive"`) for urgent errors. + +**Anti-patterns:** +- Spinners with no announcement (screen readers don't know anything changed) +- Live regions that announce too aggressively (`aria-live="assertive"` for non-critical updates) + +--- + +## Skip link + +```html +<a href="#main-content" class="skip-link">Skip to main content</a> +... +<main id="main-content">...</main> +``` + +CSS: +```css +.skip-link { + position: absolute; + top: -100px; + left: 0; +} +.skip-link:focus { + top: 0; +} +``` + +The skip link should be the first focusable element on the page. Visible only when focused. + +--- + +## Visually hidden but available to screen readers + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +Use for content that screen readers need but sighted users don't (e.g., the label of an icon-only button). + +```html +<button type="button"> + <SearchIcon aria-hidden="true" /> + <span class="visually-hidden">Search</span> +</button> +``` + +**Anti-pattern:** `display: none` or `visibility: hidden` removes content from the accessibility tree too. Use `visually-hidden` for content meant for screen readers only. + +--- + +## Generic notes + +- **Test with a real screen reader.** VoiceOver (macOS, iOS) and NVDA (Windows) are free. +- **Test with keyboard alone.** Unplug the mouse. Can you accomplish the task? +- **Run automated tests.** axe DevTools, Lighthouse, WAVE catch the basics. +- **Don't fake elements that exist.** A `<div role="button">` is worse than a `<button>`. +- **Less ARIA is more.** Most components need little or no ARIA. Semantic HTML does the work. + +For deep accessibility audits, use `accessibility-audit`. diff --git a/skills/frontend-component-build/references/component-api-patterns.md b/skills/frontend-component-build/references/component-api-patterns.md new file mode 100644 index 0000000..96283bc --- /dev/null +++ b/skills/frontend-component-build/references/component-api-patterns.md @@ -0,0 +1,311 @@ +# Component API Patterns + +Common patterns for building flexible, predictable component APIs. Examples assume React idioms but the patterns translate to Vue, Svelte, and Web Components. + +--- + +## Pattern 1: Compound components + +Multi-part components where each part is a separate sub-component sharing state via context. + +**Use when:** +- The component has distinct, repeating sub-parts (header, body, footer) +- Consumers need flexibility in arrangement and content +- Internal state needs to coordinate across parts + +```jsx +<Card> + <Card.Header>Title</Card.Header> + <Card.Body> + <Text>Content</Text> + </Card.Body> + <Card.Footer> + <Button>Action</Button> + </Card.Footer> +</Card> +``` + +**Pros:** +- Highly composable +- Consumers control arrangement +- Internal state stays encapsulated + +**Cons:** +- More API surface to maintain +- Less guidance for the consumer (any arrangement is "valid") + +--- + +## Pattern 2: Slots / render children + +A single component that accepts content through specific slots. + +**Use when:** +- The component has one or two specific insertion points +- Compound components feel like overkill + +```jsx +<Modal + title="Confirm action" + footer={<Button>Confirm</Button>} +> + <p>Are you sure?</p> +</Modal> +``` + +In Web Components: `<slot name="title">`. In Vue: named slots. In React: prop-as-element. + +**Pros:** +- Smaller API surface than compound components +- Clear insertion points + +**Cons:** +- Less flexible if the consumer wants to vary arrangement + +--- + +## Pattern 3: Render props / function as children + +The component provides state, the consumer provides UI. + +**Use when:** +- The component has reusable behavior (e.g., dropdown logic) +- Multiple visual variations should share the behavior +- Headless component libraries (Radix, Headless UI) use this heavily + +```jsx +<Dropdown> + {({ isOpen, toggle, items }) => ( + <> + <button onClick={toggle}>Menu</button> + {isOpen && <ul>{items.map(item => <li>{item}</li>)}</ul>} + </> + )} +</Dropdown> +``` + +**Pros:** +- Maximum flexibility +- Behavior and presentation cleanly separated + +**Cons:** +- Steeper learning curve +- More boilerplate at the call site + +--- + +## Pattern 4: Headless components + +Components that ship behavior and accessibility without prescribing visual style. + +**Use when:** +- Multiple consumers want different looks +- Accessibility is hard and worth centralizing +- Building a primitive layer + +```jsx +// Headless: behavior + accessibility, no visual style +<Listbox value={selected} onChange={setSelected}> + <Listbox.Button>{selected}</Listbox.Button> + <Listbox.Options> + {options.map(option => ( + <Listbox.Option key={option} value={option}>{option}</Listbox.Option> + ))} + </Listbox.Options> +</Listbox> +``` + +The consumer styles each part however they want. + +**Pros:** +- Reusable across visual styles +- Accessibility hard work centralized + +**Cons:** +- Consumers must style every part +- Less batteries-included + +--- + +## Pattern 5: Controlled vs uncontrolled + +Two modes: + +**Uncontrolled** (component owns its state): +```jsx +<Input defaultValue="initial" onChange={handleChange} /> +``` + +**Controlled** (consumer owns the state): +```jsx +<Input value={value} onChange={setValue} /> +``` + +**Pattern:** Support both. Uncontrolled is convenient for simple cases. Controlled is required when state needs to live in the parent. + +```jsx +function Input({ value, defaultValue, onChange, ...props }) { + const isControlled = value !== undefined; + const [internalValue, setInternalValue] = useState(defaultValue); + const currentValue = isControlled ? value : internalValue; + + const handleChange = (e) => { + if (!isControlled) setInternalValue(e.target.value); + onChange?.(e); + }; + + return <input value={currentValue} onChange={handleChange} {...props} />; +} +``` + +**Convention:** `value` for controlled, `defaultValue` for uncontrolled. Documented behavior when both are provided (typically: warn, treat as controlled). + +--- + +## Pattern 6: Polymorphic components (the `as` prop) + +A component that can render as different HTML elements while preserving its API. + +**Use when:** +- Visual style should apply to multiple HTML elements (e.g., a Heading that could be h1, h2, etc.) +- Consumers occasionally need to override the rendered element + +```jsx +<Text as="h1">Page title</Text> +<Text as="span">Inline text</Text> +<Text as="a" href="/path">Link</Text> +``` + +**Pros:** +- Style and semantics decoupled when needed + +**Cons:** +- Type complexity (TypeScript polymorphic types are non-trivial) +- Easy to misuse (rendering an h1 styled as a span breaks structure) + +Use sparingly. The default rendered element should fit most cases. + +--- + +## Pattern 7: Context for cross-component state + +When sub-components in a tree need shared state, use context. Don't drill props. + +```jsx +const TabContext = createContext(); + +function Tabs({ children, defaultIndex = 0 }) { + const [activeIndex, setActiveIndex] = useState(defaultIndex); + return ( + <TabContext.Provider value={{ activeIndex, setActiveIndex }}> + {children} + </TabContext.Provider> + ); +} + +function Tab({ index, children }) { + const { activeIndex, setActiveIndex } = useContext(TabContext); + return ( + <button + role="tab" + aria-selected={activeIndex === index} + onClick={() => setActiveIndex(index)} + > + {children} + </button> + ); +} +``` + +**Convention:** Context tied to a specific component family. Don't overload one context across unrelated components. + +--- + +## Pattern 8: forwardRef and ref forwarding + +Components should pass refs through to their underlying DOM element when reasonable. + +```jsx +const Button = forwardRef(function Button({ children, ...props }, ref) { + return <button ref={ref} {...props}>{children}</button>; +}); +``` + +**Why:** +- Consumers need DOM access (focus, measure, scroll) +- Form libraries need refs to inputs +- Animation libraries need refs to elements + +**Convention:** Forward refs on any component that wraps a single primary DOM element. Document where the ref attaches. + +--- + +## Pattern 9: Variant / size enums via discriminated unions + +Use string enums for variant and size props. + +```typescript +type ButtonProps = { + variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; + size?: 'sm' | 'md' | 'lg'; + // ... +}; +``` + +**Why:** +- Self-documenting +- Type-safe +- Consumers see options via autocomplete + +**Anti-pattern:** Boolean variant props. + +```typescript +// Bad +type ButtonProps = { + primary?: boolean; + secondary?: boolean; + danger?: boolean; +}; +``` + +Boolean variants permit invalid combinations (`primary={true} danger={true}`). + +--- + +## Pattern 10: Event handler conventions + +| Convention | Example | +|---|---| +| `onX` for events | `onClick`, `onChange`, `onClose` | +| `onXChange` for state changes | `onValueChange`, `onOpenChange` | +| Pass event object as first arg | `onClick(event)` | +| For state changes, pass new state as first arg | `onOpenChange(isOpen)` | + +**Anti-patterns:** +- `handleClick` as a prop name (consumer confusion - this is the implementation, not the API) +- `change` instead of `onChange` +- Passing transformed event without the original + +--- + +## API audit checklist + +Before shipping a component: + +- [ ] Default behavior is reasonable with zero props +- [ ] Variant prop uses string enum, not booleans +- [ ] Size prop uses string enum, not numbers (when sizes are constrained) +- [ ] Event handlers use `onX` convention +- [ ] Required props are minimal (ideally zero, often one) +- [ ] Optional props document defaults +- [ ] Component is forwardable (refs work) +- [ ] Polymorphic only where genuinely useful +- [ ] No boolean explosion (more than 5 booleans is a smell) +- [ ] State is controllable when it makes sense (controlled/uncontrolled support) +- [ ] Accessibility props are first-class (`aria-label`, `aria-describedby`, etc.) +- [ ] className/style override pattern documented +- [ ] All variants have visual examples in docs +- [ ] All states have visual examples in docs +- [ ] Keyboard interactions documented + +If any item fails, the API needs another pass before ship. diff --git a/skills/frontend-component-build/references/component-spec-template.md b/skills/frontend-component-build/references/component-spec-template.md new file mode 100644 index 0000000..bae7d3f --- /dev/null +++ b/skills/frontend-component-build/references/component-spec-template.md @@ -0,0 +1,250 @@ +# Component Spec Template + +Fillable template for documenting a component before writing code. The cost of writing a spec is small. The cost of building, shipping, and rebuilding a component because the API was wrong is large. + +Fill every section. If a section is "N/A", say why. + +--- + +## Identity + +**Component name:** [PascalCase. e.g., `Button`, `DatePicker`, `DropdownMenu`] +**Layer:** [Primitive / Pattern / Template] +**Status:** [Proposal / Draft / In review / Production] +**Owner:** [Name] +**Related components:** [Sibling components, parent components, components this composes or replaces] + +--- + +## Purpose + +One paragraph. What this component does, who uses it, and why it exists at all. + +If you cannot articulate why this is a system component (vs a one-off in product code), it should not be in the system yet. + +> [Purpose statement] + +--- + +## Use cases + +List the real, concrete use cases this component must serve. If the list is empty or hypothetical, the component is premature. + +1. [Specific scenario, e.g., "Submit a form on the checkout page"] +2. [Specific scenario] +3. [Specific scenario] + +### Anti-use cases + +When NOT to use this component. Helps consumers pick the right primitive. + +- [Scenario, e.g., "Triggering navigation - use `Link` instead"] +- [Scenario] + +--- + +## API + +### Props + +| Prop | Type | Default | Required | Description | +|---|---|---|---|---| +| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | No | Visual treatment | +| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | No | | +| `disabled` | `boolean` | `false` | No | | +| `loading` | `boolean` | `false` | No | Shows spinner; auto-disables interaction | +| `leadingIcon` | `ReactNode` | - | No | | +| `trailingIcon` | `ReactNode` | - | No | | +| `as` | `ElementType` | `'button'` | No | Polymorphic root element | +| `onClick` | `(e: MouseEvent) => void` | - | No | | +| `children` | `ReactNode` | - | Yes | Visible label | +| (etc.) | | | | | + +### Slots / composition + +If this is a compound component, describe each sub-component and its role. + +| Slot / sub-component | Purpose | Required | +|---|---|---| +| `Card.Header` | Title and optional icon | No | +| `Card.Body` | Main content | Yes | +| `Card.Footer` | Actions | No | + +### Events + +| Event | Payload | When fires | +|---|---|---| +| `onChange` | `{ value: string }` | User changes value, on blur or on each keystroke depending on `mode` prop | + +### Refs / imperative handles + +If the component exposes imperative methods, list them. + +| Method | Signature | Purpose | +|---|---|---| +| `focus` | `() => void` | Move focus to the component's primary interactive element | + +--- + +## States + +List every state the component can be in. Each state needs a visual treatment. + +| State | Visual | Trigger | +|---|---|---| +| Default | | Initial render | +| Hover | | Pointer over (non-touch) | +| Focus | | Keyboard focus | +| Active / pressed | | Mouse down or `Enter`/`Space` | +| Disabled | | `disabled` prop true | +| Loading | | `loading` prop true | +| Error | | Error context (validation failure, API error) | +| Empty / no data | | (For data-bearing components) | +| Read-only | | (For form inputs) | + +### State combinations + +Some states combine. Document the priority rules. + +- Loading + disabled: spinner shows, looks disabled. +- Error + focus: focus ring shows in error color. +- (etc.) + +--- + +## Accessibility + +This section is non-negotiable. Every interactive component has an accessibility section. If the component is decorative, say so explicitly. + +### Role and semantics + +- **Native element:** [What HTML element is the root, e.g., `<button>`, `<input type="text">`] +- **ARIA role (if not native):** [e.g., `role="dialog"`] +- **Label requirement:** [How is the accessible name set? `aria-label`, visible label, etc.] + +### Keyboard interaction + +| Key | Action | +|---|---| +| `Tab` | | +| `Shift + Tab` | | +| `Enter` | | +| `Space` | | +| `Escape` | | +| `Arrow keys` | | +| `Home / End` | | + +### Screen reader behavior + +- What is announced on focus? +- What is announced on state change (loading, error)? +- Are there `aria-live` regions for status updates? + +### Focus management + +- Where does focus go on mount? On unmount? +- Is focus trapped (e.g., modals)? +- Is focus visible (focus ring)? + +### Color contrast + +Confirm WCAG AA at minimum (3:1 for non-text, 4.5:1 for body text, 3:1 for large text). Note any state where contrast is at risk (disabled state often fails AA on purpose; document the choice). + +### Touch target size + +- Minimum 44x44px on mobile (WCAG 2.5.5). +- Document if smaller and why. + +--- + +## Edge cases + +The cases that always come up after launch. Document them now. + +- [ ] **Empty content:** What if `children` is empty? +- [ ] **Very long content:** What if the label is 200 characters? Truncate, wrap, or expand? +- [ ] **No data:** For data-bearing components, what does the empty state look like? +- [ ] **Loading:** What does the loading state look like? Skeleton? Spinner? Disabled? +- [ ] **Error:** Inline error? Toast? Both? +- [ ] **Disabled with tooltip:** A disabled `<button>` cannot receive focus, so a tooltip explaining why it is disabled needs special handling. +- [ ] **Right-to-left:** Does the layout flip correctly? +- [ ] **High zoom (200%):** Does the layout hold? +- [ ] **Dark mode:** Are tokens used so dark mode works automatically? +- [ ] **Reduced motion:** Are animations disabled when `prefers-reduced-motion: reduce`? + +--- + +## Variants and customization + +### Built-in variants + +What variants ship out of the box (`size`, `variant`, etc.). Document each. + +### Customization API + +How can consumers customize without forking? `className` pass-through? Style props? Slots? CSS custom properties? + +### What is NOT customizable + +Be explicit about what consumers cannot override. This is the system's stance, not a bug. + +--- + +## Internationalization + +- [ ] Text is via prop or children (not hardcoded) +- [ ] Plural and count formatting uses `Intl.PluralRules` +- [ ] Date / time formatting uses `Intl.DateTimeFormat` +- [ ] Layout works in RTL (logical properties: `margin-inline-start`, `padding-inline-end`) +- [ ] Bidirectional text (mixed LTR / RTL strings) handled + +--- + +## Performance + +- **Bundle weight target:** [KB compressed] +- **Render cost:** [Should be cheap. If expensive, document why.] +- **Re-render risk:** [Memoize? Stable callbacks expected from consumers?] +- **Lazy-loadable:** [Yes / no] + +--- + +## Testing + +### Unit tests + +- [ ] Renders default state +- [ ] Renders all variants +- [ ] Fires events on interaction +- [ ] Respects disabled / loading state +- [ ] Forwards refs + +### Accessibility tests + +- [ ] Axe passes on default state +- [ ] Axe passes on each variant +- [ ] Keyboard navigation tested +- [ ] Screen reader pass (manual or automated) + +### Visual regression tests + +- [ ] Each variant snapshot +- [ ] Each state snapshot +- [ ] RTL snapshot +- [ ] Dark mode snapshot + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +- Design approved: [Name, date] +- Engineering approved: [Name, date] +- Accessibility reviewed: [Name, date] +- Ready for production: [Date] diff --git a/skills/funnel-flow-architecture/SKILL.md b/skills/funnel-flow-architecture/SKILL.md new file mode 100644 index 0000000..ffa49be --- /dev/null +++ b/skills/funnel-flow-architecture/SKILL.md @@ -0,0 +1,306 @@ +--- +name: funnel-flow-architecture +description: "Architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. Honest about silo-funnels (every tool standalone), kitchen-sink-funnels (every audience squeezed through one path), and matched-funnels (architecture matched to audience-and-stage) patterns. Triggers on funnel design, conversion architecture, marketing funnel, growth funnel, lifecycle architecture, nurture sequence design, multi-tool funnel orchestration. Also triggers when the team's growth tools are working individually but not together, when audience segments share one nurture path, or when a funnel is being architected from scratch." +category: growth-tooling +catalog_summary: "Architecting cross-tool conversion flows that match audience and stage. Distinguishes silo-funnels (every tool standalone) from kitchen-sink-funnels (every audience squeezed through one path) from matched-funnels (architecture matched to audience-and-stage)" +display_order: 6 +--- + +# Funnel Flow Architecture + +A senior growth practitioner's playbook for architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. The discipline of building a funnel architecture, not just collecting tools. + +Most growth programs accumulate tools without architecture. A chatbot, a calculator, a quiz, a lead magnet, a newsletter signup, a demo CTA. Each tool works individually; none of them work together. Visitors hit one tool, leave, and never enter the broader nurture sequence. The funnel is a collection of orphans. + +The growth programs that compound do something different. They architect the funnel deliberately. Different entry points lead to different nurture sequences. Different stages get different CTAs. Different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. + +This skill is the architecture skill that orchestrates the other 5 growth-tooling skills (lead-magnet-design, calculator-design, quiz-and-assessment-design, multi-step-form-design, chatbot-flow-design). Where those skills zoom into specific tool design, this skill zooms out to the cross-tool architecture that determines whether the tools compound. + +The voice is the senior growth practitioner who has watched funnels architecture compound and watched siloed funnel collections produce engagement metrics with no business impact. Practical, opinionated about the difference between collecting tools and architecting funnels, willing to call out when a team's growth program needs architecture rather than another tool. + +When to use this skill: architecting a funnel from scratch, auditing a growth program where tools work individually but conversion is flat, designing the cross-tool data flow that captures audience signal across touchpoints, or deciding which segments warrant which funnel paths. + +--- + +## What this skill covers + +This skill spans cross-tool funnel architecture. The growth-tooling distinctions: + +- `lead-magnet-design`, `calculator-design`, `quiz-and-assessment-design`, `multi-step-form-design`, `chatbot-flow-design` are tools that LIVE INSIDE the funnel architecture this skill designs. They zoom into specific tool design. +- `content-distribution` covers how content reaches audiences. This skill is what audiences DO once they reach content. +- `experiment-design` validates funnel changes. This skill designs the architecture; experiment-design tests it. +- `landing-page-copy` covers page-level copy. This skill is the cross-page architecture. +- **`funnel-flow-architecture` (this skill)** is audience-and-stage segmentation, entry-point architecture, tool-to-funnel mapping, nurture sequence architecture, cross-tool data flow. + +The audience: growth marketing leads, product marketing leads, marketing directors at SMB and mid-market companies, agencies running funnel architecture for clients, founders architecting growth programs from scratch. + +Out of scope: specific tool design (covered by the 5 sister growth-tooling skills); content distribution mechanics (covered by `content-distribution`); A/B testing methodology (covered by `experiment-design`); page-level copy (covered by `landing-page-copy`). + +--- + +## Silo-funnels vs kitchen-sink-funnels vs matched-funnels + +The keystone framing. + +**Silo-funnels.** Each tool (chatbot, calculator, lead magnet, quiz) lives independently. No coordinated flow; users hit one tool, leave, never enter the broader nurture sequence. Tools as orphans. Cost: each tool's investment does not compound; the audience that interacts with one tool is not connected to any next step; the team has tools but no architecture. + +**Kitchen-sink-funnels.** One funnel for everyone. Same nurture sequence regardless of audience or entry point. SMB and enterprise get the same emails. New visitors and bottom-of-funnel get the same CTAs. Conversion rates regress to mediocre on every segment. Cost: the funnel optimizes for the average; no segment is well-served; downstream conversion is uniformly low. + +**Matched-funnels.** Funnel architecture matches audience and stage. Different entry points lead to different nurture sequences; different stages get different CTAs; different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. Cost: the design effort upfront is significant; the maintenance is real; downstream conversion is meaningfully higher per segment. + +The litmus test. Pick a recent visitor to the site. Can the team explain which segment the visitor falls into, which entry point they used, which nurture sequence they are in, and what the next-step CTA they will see is? If yes, the funnel is matched. If the answer is "they got the same flow as everyone else," the funnel is kitchen-sink. If the answer is "they used the calculator but I do not know what comes next," the funnel is silo. + +--- + +## Audience and stage segmentation + +The foundation. + +**The principle.** Funnel architecture starts with audience and stage segmentation. Without segmentation, every visitor goes through the same path; the funnel cannot match. + +**Audience dimensions.** + +- **Company size or buyer type.** Solo, SMB, mid-market, enterprise. +- **Industry or vertical.** Healthcare, finance, retail, technology. +- **Use case.** What the audience is trying to accomplish. +- **Role.** Founder, PM, marketer, executive, IC. +- **Source.** Paid traffic, organic, referral, partner. + +**Stage dimensions.** + +- **Awareness.** Just discovered the brand or the topic. +- **Consideration.** Evaluating options actively. +- **Decision.** Choosing between specific options. +- **Customer.** Already a customer; ongoing relationship. + +**The intersection.** Audience x stage produces the matrix the funnel architecture serves. An enterprise PM in consideration is a different segment from an SMB founder in awareness; each warrants a different path. + +**Segmentation discipline.** Start with 3-5 audiences and 3 stages. 9-15 cells in the matrix. Some cells may share paths; some may have unique paths. The discipline is naming the segments deliberately rather than treating "everyone" as the audience. + +Detail in [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md). + +--- + +## Entry-point architecture + +How visitors land vs how they're routed. + +**The principle.** The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). + +**Common entry points.** + +- **Paid landing page.** Visitor arrives via ad; high intent; specific to the ad's promise. +- **Organic content page.** Visitor arrives via search or content discovery; awareness or research stage. +- **Direct.** Visitor arrives by typing URL or via bookmark; often returning. +- **Referral.** Visitor arrives via partner or word-of-mouth; warmer than paid. +- **Social.** Visitor arrives via social post; awareness or interest. +- **Tool entry.** Visitor arrives via a calculator, quiz, or chatbot directly. + +**Entry-point routing.** + +- Each entry point has expected segments and stages. +- The first action available at the entry point should match likely segment and stage. +- Different entry points may route to different downstream tools and sequences. + +**Worked example.** A visitor arriving via a paid ad about "B2B SaaS pricing" is likely in consideration stage looking for pricing information. The landing page should serve that need (clear pricing, comparison, calculator); the next-step offer should match consideration (demo, talk to sales). Same visitor arriving via an organic blog post about "B2B SaaS pricing strategy" is likely in awareness stage; the landing page should serve education (depth on pricing strategy); the next-step offer should match awareness (subscribe to content, get the framework). + +Detail in [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md). + +--- + +## Tool-to-funnel mapping + +Which tools serve which entry points. + +**The principle.** Each tool in the growth toolkit has a place in the funnel architecture. The tool serves specific segments at specific stages from specific entry points. + +**Mapping examples.** + +- **Lead magnet.** Often serves awareness-to-consideration transition. Captured email leads to nurture sequence. +- **Calculator.** Often serves consideration stage. The audience evaluating options uses the calculator to defend a specific decision. +- **Quiz.** Can serve any stage depending on design. Awareness quizzes for content marketing; consideration quizzes for product matching; decision quizzes for plan selection. +- **Multi-step form.** Often serves decision or qualification stage. The form captures qualified intent. +- **Chatbot.** Cross-cutting. Can serve any stage with intent recognition routing. + +**The tool-segment fit.** Tools should serve segments that match their value proposition. A calculator for solo founders may need different inputs and outputs than a calculator for enterprise buyers; the same calculator cannot serve both well. + +**The portfolio approach.** A team often has multiple tools serving different segments. The architecture maps each tool to its specific segments and stages. + +Detail in [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md). + +--- + +## Nurture sequence architecture + +Per-segment, per-stage. + +**The principle.** Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. + +**Sequence variation by stage.** + +- **Awareness sequence.** Educational; broad value; brand-building. Soft offers if any. +- **Consideration sequence.** Comparative; specific value; product-fit signals. Demo or trial CTAs. +- **Decision sequence.** Confidence-building; risk-reversal; urgency cues. Direct purchase or commitment CTAs. + +**Sequence variation by audience.** + +- Enterprise audiences get different content (white papers, case studies, ROI analysis) than SMB audiences (templates, quick wins, peer testimonials). +- Different roles get different framing (founder content emphasizes business outcomes; IC content emphasizes practitioner depth). +- Different industries get different examples and language. + +**The kitchen-sink sequence failure.** One sequence for everyone. Generic enough to send to all; specific enough for none. Conversion uniformly mediocre. + +**The matched sequence win.** Sequence specific to segment-and-stage. The audience perceives the brand as understanding their situation; conversion compounds. + +Detail in [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md). + +--- + +## Cross-tool data flow + +Capturing context from tool to tool. + +**The principle.** When the audience moves from one tool to another in the funnel, the audience signal travels with them. The chatbot conversation context informs the calculator's defaults; the calculator inputs inform the lead-magnet sequence; the quiz result informs the demo-request prefill. + +**Cross-tool data flow patterns.** + +- **Identity threading.** When the audience is identified at any point (logged in, opted in, identified by email), their identity carries forward across tools. +- **Context capture.** Inputs from one tool (calculator values, quiz results, form submissions) feed into the next interaction. +- **Segment tagging.** Each interaction tags the audience with segment information that informs future routing. +- **Sequence-tool integration.** Email sequences include links to specific tools matched to the audience's segment. + +**The siloed-tool failure.** Each tool captures its own data; nothing flows between them. The chatbot conversation is forgotten when the user opens the calculator; the calculator inputs are forgotten when the user opens the lead magnet. + +**The integrated-funnel win.** Data flows. The audience experiences continuity; the brand can match content and offers to the audience's specific journey. + +Detail in [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md). + +--- + +## Funnel measurement + +What to measure, what is noise. + +**The principle.** Funnel measurement should reveal architecture quality, not just tool quality. + +**Architecture-level metrics.** + +- **Cross-tool conversion.** What percentage of audience that hits tool A then engages with tool B? +- **Sequence-to-tool conversion.** What percentage of nurture sequence subscribers engage with downstream tools? +- **Segment-level downstream conversion.** Per-segment conversion to the program's main goal (trial, demo, purchase). +- **Funnel-stage progression.** What percentage of audience moves from awareness to consideration to decision over time? + +**Tool-level metrics.** + +- Conversion rate per tool (covered by each tool's skill). + +**Architecture-level vs tool-level.** Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. Both matter; architecture is often the missing measurement. + +Detail in [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md). + +--- + +## Funnel iteration discipline + +When to redesign, when to refine. + +**The principle.** Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +**Refine when:** + +- Specific tools are underperforming relative to baseline. +- Specific segments have lower conversion than peer segments. +- Specific transitions in the funnel are producing drop-off. +- Sequence engagement is declining for specific cohorts. + +**Redesign when:** + +- Audience composition has fundamentally shifted. +- Product or service strategy has changed. +- Competitive landscape has shifted significantly. +- Multiple refine cycles have not produced expected results, suggesting architectural issues. + +**Continuous-redesign trap.** Teams that constantly redesign never benefit from architectural compounding. Each redesign resets the learning; nothing accumulates. + +**Frozen-architecture trap.** Teams that never iterate watch their architecture decay as audiences and markets evolve. + +The middle ground. Refine continuously; redesign infrequently and deliberately. + +Detail in [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md). + +--- + +## Architecture anti-patterns + +Patterns that look like funnel architecture but degrade conversion. + +**The silo-funnels pattern.** Tools as orphans; no architecture. + +**The kitchen-sink-funnels pattern.** One funnel for everyone. + +**The over-segmented funnel.** So many segments that maintenance is impossible; segments are not actually distinguishable. + +**The unmaintained-funnel.** Architecture designed once, never reviewed; decay accumulates. + +**The tool-driven-architecture.** Architecture organized around tools rather than around audience-and-stage; each tool gets its own funnel regardless of whether that serves the audience. + +**The metric-blind-architecture.** Architecture without measurement; cannot diagnose where it works and where it does not. + +**The single-tool-funnel.** Architecture that depends on one tool (just the calculator, just the chatbot); no resilience if that tool underperforms. + +**The hand-off-broken-funnel.** Tools work individually but the transitions between them break. + +Detail in [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md). + +--- + +## The framework: 12 considerations for funnel flow architecture + +When designing or auditing a funnel architecture, walk these 12 considerations. + +1. **Matched-funnels, not silo or kitchen-sink.** Architecture matches audience-and-stage; each tool is part of the architecture, not a standalone artifact. +2. **Audience and stage segmentation defined.** 3-5 audiences x 3 stages; the matrix the architecture serves. +3. **Entry-point architecture mapped.** Each entry point routed to expected segments and stages. +4. **Tool-to-funnel mapping documented.** Each tool serves specific segments at specific stages. +5. **Nurture sequence architecture per segment.** Sequences vary by audience and stage; not one sequence for everyone. +6. **Cross-tool data flow integrated.** Context travels across tools; the audience experiences continuity. +7. **Architecture-level metrics tracked.** Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion. +8. **Funnel iteration discipline.** Refine continuously; redesign deliberately; avoid both extremes. +9. **Tool portfolio balanced.** Multiple tools serving different segments; not over-reliant on any single tool. +10. **Audience-fit honest.** The architecture serves the segments the brand can actually serve; out-of-fit audiences are filtered or routed elsewhere. +11. **Maintenance ownership clear.** Someone owns the architecture; quarterly review is calendared. +12. **Expansion plan defined.** When adding new tools, the architecture says where they fit; new tools earn their place rather than being added decoratively. + +The output of the framework is a funnel architecture that compounds over time, matches audience-and-stage segments, integrates tool data flows, and produces measurable downstream conversion. + +--- + +## Reference files + +- [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md) - The foundation. Audience dimensions, stage dimensions, the intersection matrix. +- [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md) - How visitors land vs how they're routed. Common entry points and their routing. +- [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md) - Which tools serve which entry points and segments. +- [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md) - Per-segment, per-stage sequence variation. The matched sequence win. +- [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md) - Identity threading, context capture, segment tagging, sequence-tool integration. +- [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md) - Architecture-level vs tool-level metrics. What to measure, what is noise. +- [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md) - When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. +- [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md) - The patterns that look like funnel architecture but degrade conversion. +- [`references/common-funnel-architecture-failures.md`](references/common-funnel-architecture-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: funnels are architecture, not collections + +The growth programs that compound are the ones that architect their funnels deliberately. Not collect tools. Not optimize one-tool-at-a-time. Architect. + +The architecture is the difference between tools that produce engagement and a funnel that produces business outcomes. The chatbot, the calculator, the quiz, the lead magnet, the multi-step form: each one is a tool. None of them are a funnel. The funnel is the architecture that makes them work together. + +That is the bar. Below the bar are silo-funnels (tools as orphans) and kitchen-sink-funnels (one path for everyone). Above the bar are matched-funnels where audience-and-stage segmentation drives entry-point routing, tool-to-funnel mapping, nurture sequence design, cross-tool data flow, and architecture-level measurement. + +## Closing: funnels earn investment when they compose + +Each tool in the growth toolkit costs investment to build and maintain. The investment compounds when the tools compose; the investment dilutes when the tools sit in silos. Architecture is the discipline of composition. + +The compounding mechanism. A visitor arrives. The architecture routes them based on entry point and observable signals. The first tool they encounter serves their segment-and-stage. The data they generate informs the next tool they encounter. The sequence they enter matches their context. Each interaction deepens the brand's understanding of the audience; each tool's contribution compounds with the others. + +When in doubt, ask: does each tool in the program serve a defined segment-and-stage, do the tools share data and context, can the team explain the architecture in one diagram, and does the team measure architecture-level outcomes (not just tool-level metrics)? If yes to all of those, the funnel is real architecture. If no to any, the gap is where the program's tools are failing to compose. diff --git a/skills/funnel-flow-architecture/references/architecture-anti-patterns.md b/skills/funnel-flow-architecture/references/architecture-anti-patterns.md new file mode 100644 index 0000000..6595f7a --- /dev/null +++ b/skills/funnel-flow-architecture/references/architecture-anti-patterns.md @@ -0,0 +1,198 @@ +# Architecture anti-patterns + +The patterns that look like funnel architecture but degrade conversion. Anti-patterns are easy to ship; the cost shows up in downstream conversion, lead quality, and brand reputation over time. + +--- + +## The silo-funnels pattern + +The pattern. Tools as orphans. No coordinated flow. + +The signal. Each tool's metrics look fine individually; cross-tool metrics non-existent or near-zero. Downstream conversion does not match the sum of tool conversions. + +The cost. Each tool's investment does not compound. The audience that interacts with one tool is not connected to any next step. The team has tools but no architecture. + +The cure. Add cross-tool data flow and explicit funnel architecture. Detail in `references/cross-tool-data-flow-patterns.md` and the broader skill. + +--- + +## The kitchen-sink-funnels pattern + +The pattern. One funnel for everyone. Same nurture sequence regardless of audience or entry point. + +The signal. Conversion rates regress to mediocre on every segment. No segment is well-served. + +The cost. The funnel optimizes for the average; downstream conversion is uniformly low. + +The cure. Segment-and-stage architecture. Different paths for different cells in the matrix. Detail in `references/audience-and-stage-segmentation.md` and `references/nurture-sequence-architecture.md`. + +--- + +## The over-segmented funnel + +The pattern. So many segments that maintenance is impossible. 60 cells in the matrix; 60 distinct paths; nobody can keep up. + +The signal. Specific paths get little attention; maintenance backlog grows; specific cells are theoretical with no real visitors. + +The cost. The architecture exists on paper but not in execution. Tools and sequences for theoretical cells cost effort without producing value. + +The cure. Reduce to 9-15 cells. Start with the minimum viable matrix; expand only when data justifies. Detail in `references/audience-and-stage-segmentation.md`. + +--- + +## The unmaintained-funnel + +The pattern. Architecture designed once, never reviewed. Decay accumulates. + +The signal. Conversion declines slowly; tools age; sequences go stale; segments shift; the architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; the brand falls behind. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## The tool-driven-architecture + +The pattern. Architecture organized around tools rather than around audience-and-stage. Each tool gets its own funnel regardless of whether that serves the audience. + +The signal. The site has many tool-specific landing pages; users navigate to tools rather than tools serving users; the architecture is organized for the team, not the audience. + +The cost. Audiences cannot find what they need; tools cannibalize each other; the architecture cannot scale because each tool is its own funnel. + +The cure. Reorganize around audience-and-stage. The matrix drives the architecture; tools serve the matrix. + +--- + +## The metric-blind-architecture + +The pattern. Architecture without measurement. Cannot diagnose where it works and where it does not. + +The signal. Decisions made on intuition; no data to validate; iteration is guesswork. + +The cost. The architecture cannot improve through measurement; refinement is random; redesign happens reactively. + +The cure. Architecture-level metrics. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## The single-tool-funnel + +The pattern. Architecture that depends on one tool. Just the calculator. Just the chatbot. No resilience if that tool underperforms. + +The signal. The tool's quarterly performance dictates overall funnel performance. A bad month for the tool is a bad month for the funnel. + +The cost. The architecture is fragile. Tool failures cascade; redesigns of the central tool are high-risk. + +The cure. Portfolio approach. Multiple tools serving different segments. The architecture's resilience comes from diversification. + +--- + +## The hand-off-broken-funnel + +The pattern. Tools work individually but the transitions between them break. + +The signal. Each tool's metrics look fine; cross-tool conversion is low. The architecture's transitions are silently failing. + +The cost. The audience experiences the funnel as disconnected. Downstream conversion suffers because the bridges between tools are broken. + +The cure. Audit transitions. Cross-tool data flow. Sequence-tool integration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## The continuous-redesign funnel + +The pattern. Architecture redesigned every quarter. Each iteration starts over. + +The signal. Conversion does not improve over time. Each redesign resets the learning. Tools never reach maturity. + +The cost. Investment dilutes across redesigns. Compounding does not happen. + +The cure. Refine continuously; redesign infrequently and deliberately. Detail in `references/funnel-iteration-discipline.md` (continuous-redesign trap). + +--- + +## The frozen-architecture funnel + +The pattern. Architecture designed once; never iterated; treated as finished. + +The signal. Conversion declines slowly; tools and sequences feel dated; segments no longer match the audience. + +The cost. The architecture's value erodes; the brand becomes uncompetitive. + +The cure. Set refinement cadences. Quarterly audits. Detail in `references/funnel-iteration-discipline.md` (frozen-architecture trap). + +--- + +## The vanity-metric architecture + +The pattern. Architecture measured by surface metrics (tool engagement, total visitors, email signups) without measuring downstream outcomes. + +The signal. Metrics report looks healthy; business outcomes do not match. + +The cost. The team optimizes for the wrong metrics; the architecture appears successful while underperforming on what matters. + +The cure. Measure downstream conversion. Per-segment downstream conversion. Architecture-level metrics rather than tool-level activity. + +--- + +## The over-personalized funnel + +The pattern. Architecture designed for personalization the team cannot actually deliver. Many entry points; many sequences; many tools; team capacity exceeded. + +The signal. Personalization in design; generic in execution. Specific paths exist on paper; default to generic in practice. + +The cost. The team built complexity that does not get used. Maintenance burden without payoff. + +The cure. Match architecture complexity to team capacity. Start simple; add personalization where it produces meaningful lift; do not personalize for its own sake. + +--- + +## The under-personalized funnel + +The pattern. Architecture treats every visitor the same when meaningful personalization would lift conversion. + +The signal. Specific segments underperform; the audience's actual differences are not reflected in the funnel. + +The cost. Conversion stays at the average; no segment exceeds. + +The cure. Add personalization where data shows it would help. Start with segment-level differentiation; refine over time. + +--- + +## The orphan-tool architecture + +The pattern. Tools added to the funnel without explicit segment-and-stage assignment. Each new tool exists; no architecture says where it fits. + +The signal. The funnel's tool count grows; the architecture's clarity does not. + +The cost. Tools compete for the same audience; users see overlapping options; conversion fragments. + +The cure. Each tool earns its place. Architecture documents which segments and stages the tool serves. New tools are added with explicit mapping. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of the architecture, looking specifically for these anti-patterns. + +**Audit questions.** + +- Do the tools work together (anti-pattern check: silo, hand-off-broken)? +- Is there segment-and-stage architecture (anti-pattern check: kitchen-sink, tool-driven)? +- Is the matrix maintainable (anti-pattern check: over-segmented, over-personalized)? +- Are tools mapped to specific segments (anti-pattern check: orphan-tool, single-tool, under-personalized)? +- Are architecture-level metrics tracked (anti-pattern check: metric-blind, vanity-metric)? +- Is there iteration discipline (anti-pattern check: continuous-redesign, frozen-architecture, unmaintained)? + +**The retire decision.** Anti-pattern architectures often warrant redesign. Patching anti-patterns rarely produces a good architecture. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md b/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md new file mode 100644 index 0000000..f2ce571 --- /dev/null +++ b/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md @@ -0,0 +1,200 @@ +# Audience and stage segmentation + +The foundation. Audience dimensions, stage dimensions, the intersection matrix. + +Funnel architecture starts with audience and stage segmentation. Without it, every visitor goes through the same path; the funnel cannot match. With it, the architecture has a definable map of who the audience is and where they are in their journey. + +--- + +## The segmentation principle + +The funnel cannot be tailored without segments. Segments are the architecture's unit of design. + +**The discipline.** Define 3-5 audience segments and 3 stages. The intersection produces 9-15 cells; each cell is a potential funnel path. + +**The trap.** Over-segmenting. Defining 12 audiences x 5 stages produces 60 cells; the team cannot maintain that many distinct paths. Most cells end up sharing paths or being indistinguishable. + +**The discipline boundary.** Start with the minimum viable segmentation. 3-5 audiences and 3 stages is enough to start. Expand only if the data shows meaningful differentiation that justifies more cells. + +--- + +## Audience dimensions + +The dimensions that distinguish meaningful audience segments. + +**Company size or buyer type.** Solo founders, SMB (10-50), mid-market (50-500), enterprise (500+). Different sizes have different buying processes, different budgets, different needs. + +**Industry or vertical.** Healthcare, finance, retail, technology, education. Different industries have different language, regulations, examples, competitors. + +**Use case.** What the audience is trying to accomplish. "Customer support automation," "sales pipeline management," "content production at scale." + +**Role.** Founder, PM, marketer, sales lead, executive, IC. Different roles have different perspectives and different content preferences. + +**Source or channel.** Paid traffic, organic search, content referral, partner referral, direct. Different sources signal different intent and stage. + +**Geography or language.** Domestic vs international; English-first vs other-language audiences. May warrant different funnels for compliance, currency, or cultural reasons. + +The audience dimensions to use depend on the brand's strategy. Most B2B brands segment primarily by company size and use case; most consumer brands segment by demographic and behavioral attributes. + +--- + +## Stage dimensions + +The dimensions that distinguish where the audience is in their journey. + +**Awareness.** Just discovered the brand or the topic. Has not yet committed to research or evaluation. The audience is open but uncommitted. + +Content fit: educational, broad value, brand-building. +CTAs that fit: subscribe to content, get a framework, follow. +CTAs that do not fit: book a demo, start a trial, buy now. + +**Consideration.** Evaluating options actively. Has identified a need; comparing solutions. The audience is engaged but not yet decided. + +Content fit: comparative, specific value, product-fit signals. +CTAs that fit: see a calculator, take a quiz, download a comparison, book a demo. +CTAs that do not fit: just-published-content awareness asks; or hard sell. + +**Decision.** Choosing between specific options. The audience has narrowed the field; selecting is imminent. + +Content fit: confidence-building, risk-reversal, urgency cues. +CTAs that fit: start a trial, talk to sales, sign up. +CTAs that do not fit: top-of-funnel awareness; long-form education. + +**Customer.** Already a customer; ongoing relationship. Often left out of growth-funnel architecture even though it matters for retention and expansion. + +Content fit: success-deepening, capability-expanding, community. +CTAs that fit: upgrade, refer, join community, attend event. + +The four stages cover most audiences. Some programs combine awareness-and-consideration or consideration-and-decision into 2-stage models; the principle is the same. + +--- + +## The intersection matrix + +Audience x stage produces the matrix the funnel architecture serves. + +**Example matrix for a B2B SaaS company.** + +| Audience | Awareness | Consideration | Decision | +|----------|-----------|---------------|----------| +| Solo founder | Path A | Path B | Path C | +| SMB team | Path D | Path E | Path F | +| Mid-market | Path G | Path H | Path I | +| Enterprise | Path J | Path K | Path L | + +12 cells. Some may share paths (Path A and Path D might be similar awareness content for solo and SMB). The matrix is the architecture's map. + +**Cell-sharing patterns.** + +- Awareness paths often share more than decision paths (broad content can serve multiple audience segments). +- Consideration paths often diverge by audience (the comparison content for enterprise differs significantly from SMB). +- Decision paths almost always diverge (the offer for enterprise is different from SMB). + +The matrix shows where the funnel architecture invests in unique paths and where it shares. + +--- + +## Segmentation discipline + +The discipline boundaries. + +**Discipline 1: Define segments before designing paths.** Without segments, paths are arbitrary. Always start with the matrix. + +**Discipline 2: Name segments specifically.** "Solo founder pre-launch" beats "small business." Specific names reflect specific audiences. + +**Discipline 3: Validate segments with data.** A segment that does not appear in actual audience data is theoretical. Validate against site analytics, sales data, or audience research. + +**Discipline 4: Maintain the matrix.** Audiences shift; the matrix should be reviewed quarterly. Segments may merge or split over time. + +**Discipline 5: Avoid over-segmentation.** 60-cell matrices are not maintainable. Start with 9-15 cells; expand only with justification. + +--- + +## Segmentation worked example + +A B2B SaaS analytics platform. + +**Audiences (4).** + +- Data analysts at SMB companies (50-200 employees). +- Data leaders at mid-market companies (200-1000 employees). +- Engineering leaders at enterprise companies (1000+ employees). +- Solo data practitioners and consultants. + +**Stages (3).** + +- Awareness (researching the analytics topic). +- Consideration (evaluating analytics platforms). +- Decision (selecting and signing up). + +**Matrix (12 cells).** + +| Audience | Awareness | Consideration | Decision | +|----------|-----------|---------------|----------| +| Data analyst SMB | Educational content | Calculator, quiz | Trial, demo | +| Data leader mid-market | Strategic content | Comparison, ROI calc | Demo, custom quote | +| Engineering enterprise | Technical depth | Technical demo, security | Custom evaluation | +| Solo practitioner | Practical content | Self-serve resources | Free tier signup | + +Each cell has a defined path. The architecture invests where the cells need unique treatment; shares where the cells can use the same path. + +--- + +## Segmentation maintenance + +Segments decay. + +**What decays.** + +- Audience definitions that no longer match actual visitors. +- Stage definitions that have shifted as buying processes evolved. +- Cells that have become empty (no visitors fit the segment). +- Cells that have become bloated (too many visitors fit one segment; needs sub-segmentation). + +**Maintenance cadence.** Quarterly review of the matrix against actual audience data. + +**The drift indicator.** Sales reports that the funnel-sourced leads do not match expected segments; analytics show segments combining or splitting unexpectedly. + +--- + +## Segmentation and the rest of the architecture + +How segmentation drives the rest of the architecture. + +**Entry-point architecture.** Each entry point routes to expected segments. The matrix tells the architecture where each entry point's traffic likely lands. + +**Tool-to-funnel mapping.** Each tool serves specific cells in the matrix. The matrix tells the architecture which tools belong where. + +**Nurture sequence architecture.** Each cell may have its own sequence (or sequences may be shared across similar cells). The matrix is the sequence design map. + +**Cross-tool data flow.** As the audience moves through the matrix (awareness to consideration to decision), data flows with them. The matrix tracks the journey. + +**Funnel measurement.** Per-cell conversion is the architecture-level metric. The matrix is the measurement framework. + +--- + +## Common segmentation failures + +**No segmentation.** "Everyone" treated as the audience. Funnel cannot match. + +**Theoretical segments.** Segments defined that do not exist in actual audience data. + +**Over-segmentation.** 60-cell matrix that the team cannot maintain. + +**Under-segmentation.** 4-cell matrix when the audience genuinely splits into more meaningful segments. + +**Stale segmentation.** Matrix designed once; audience shifted; matrix not updated. + +**Segments without paths.** Matrix defined but no funnel paths designed for the cells; segmentation is decorative. + +**Paths without segments.** Funnel paths designed without clear segment mapping; treatments are arbitrary. + +--- + +## Methodology-level choices that stay in the public skill + +The segmentation principle and discipline boundaries. Audience dimensions. Stage dimensions. The intersection matrix. Segmentation discipline (5 disciplines). Worked example. Segmentation maintenance. Segmentation and the rest of the architecture. Common failures. + +## Implementation choices that stay internal + +Specific segments for the team's audience. Specific tooling for segment tagging and analysis. The team's matrix maintenance calendar. Specific path designs per cell. These vary by team. diff --git a/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md b/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md new file mode 100644 index 0000000..8f45320 --- /dev/null +++ b/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md @@ -0,0 +1,179 @@ +# Common funnel architecture failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the funnel is not converting" or "tools work individually but conversion is flat" or "we cannot tell where the funnel is broken." + +--- + +## "Tools work individually; conversion is flat." + +**The diagnosis.** Silo-funnels pattern. Tools as orphans; no architecture connects them. + +**The cure.** Add cross-tool data flow; map tools to specific segments; design transitions between tools. Detail in `references/cross-tool-data-flow-patterns.md` and `references/tool-to-funnel-mapping.md`. + +--- + +## "Every audience gets the same nurture sequence." + +**The diagnosis.** Kitchen-sink-funnels pattern. One sequence for everyone. + +**The cure.** Segment-and-stage sequences. Different cells in the matrix get different sequences. Detail in `references/nurture-sequence-architecture.md`. + +--- + +## "We have 12 tools and no clear architecture." + +**The diagnosis.** Tool-driven architecture. Tools accumulated without explicit segment mapping. + +**The cure.** Build the matrix; map each tool to specific cells; retire tools that do not have a mapping or that compete with better-mapped alternatives. + +--- + +## "Specific segments convert at half the rate of others." + +**The diagnosis.** Architecture for those segments may be broken. Or the segments may not be served by the current tools and sequences. + +**The cure.** Audit those segments' funnel paths. Are tools mapped to them? Are sequences designed for them? If not, build for those segments. If yes, refine the existing path. + +--- + +## "We cannot tell which tools or sequences are driving conversion." + +**The diagnosis.** Architecture-level metrics not tracked. Cannot attribute outcomes to architecture choices. + +**The cure.** Instrument cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## "We redesign every quarter; nothing improves." + +**The diagnosis.** Continuous-redesign trap. Each redesign resets learning; nothing compounds. + +**The cure.** Establish "no major redesign for X months" discipline. Refine continuously; redesign deliberately and rarely. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "The funnel was great at launch; now conversion has dropped 40 percent." + +**The diagnosis.** Frozen-architecture trap. Designed once; never iterated; decay accumulated. + +**The cure.** Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "Specific transitions in the funnel have high drop-off." + +**The diagnosis.** Hand-off-broken pattern. Tools work but the bridges between them break. + +**The cure.** Audit transitions. Add cross-tool data flow so context travels. Promote downstream tools at upstream tools' exits. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Our chatbot, calculator, and quiz all serve consideration-stage audiences." + +**The diagnosis.** Tool overlap without differentiation. Three tools competing for the same audience. + +**The cure.** Differentiate the tools' purposes. Calculator for ROI questions; quiz for product matching; chatbot for FAQ. Or consolidate to fewer tools with clearer roles. + +--- + +## "Sales says quiz-sourced leads, calculator-sourced leads, and lead-magnet-sourced leads are different qualities." + +**The diagnosis.** Tools may be attracting different segments; the architecture's segmentation is working but the tools are not all matched to high-quality segments. + +**The cure.** Investigate which tools attract which segments. Optimize tool placement and design for the segments the brand serves best; deprioritize tools that attract low-quality segments. + +--- + +## "We added a new tool last quarter; it does not seem to help conversion." + +**The diagnosis.** Orphan-tool pattern. Tool added without architecture mapping. + +**The cure.** Map the new tool to specific segments. Decide where it fits in the matrix. Promote it where it fits; remove it from places it does not. + +--- + +## "Our funnel has 8 stages; visitors only complete 2." + +**The diagnosis.** Funnel may be over-architected. Too many steps; audience cannot or will not progress through them all. + +**The cure.** Simplify the funnel. Combine stages; remove unnecessary tools; align the funnel length to the audience's likely journey. + +--- + +## "Cross-tool tracking is broken; we cannot tell who used what." + +**The diagnosis.** Identity threading or event tracking issue. Architecture's measurement infrastructure is broken. + +**The cure.** Audit identity threading. Verify event tracking. Fix the infrastructure before further iteration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Audiences arriving from paid traffic and organic traffic perform completely differently." + +**The diagnosis.** Either entry-point routing is not differentiating, or the funnel paths are not serving paid and organic audiences differently. + +**The cure.** Different routing for different entry points. Specific landing pages and sequences for paid vs organic. Detail in `references/entry-point-architecture-patterns.md`. + +--- + +## "The team built personas; the funnel does not reflect them." + +**The diagnosis.** Segments defined but not implemented in the funnel architecture. Decorative segmentation. + +**The cure.** Map personas to funnel cells. Build paths for the cells. The personas should drive the architecture, not sit in a deck. + +--- + +## "Our sequence-to-trial conversion is high; trial-to-paid is low." + +**The diagnosis.** Architecture handles funnel up to trial well; the trial-to-paid stage may need its own architecture (or may be a product issue rather than funnel issue). + +**The cure.** Treat trial-to-paid as its own funnel-stage progression. Build paths for trial users; nurture toward paid conversion. + +--- + +## "We have 15 lead magnets; 3 produce most of the leads." + +**The diagnosis.** Magnet portfolio not maintained. Most magnets are dead but still on the site. + +**The cure.** Audit and retire dead magnets. Free capacity for the strong ones. Detail in `lead-magnet-design`. + +--- + +## "We built a fancy architecture; the team cannot maintain it." + +**The diagnosis.** Over-architecture. Architecture exceeds team capacity. + +**The cure.** Simplify. Match architecture complexity to team capacity. Expand only when capacity grows. + +--- + +## "Funnel-sourced leads are different from sales-sourced leads." + +**The diagnosis.** Likely fine. Funnel and direct sales serve different segments and stages. Both can be valuable. + +**The action.** Track them separately. Optimize each for its specific path. + +--- + +## The pattern across failures + +Most funnel architecture failures fall into one of three patterns. + +**Pattern 1: Tools without architecture.** Silo, kitchen-sink, tool-driven, orphan-tool. The fix is to add explicit architecture (matrix, mapping, data flow). + +**Pattern 2: Architecture without measurement.** Metric-blind, vanity-metric, broken tracking. The fix is to instrument architecture-level metrics. + +**Pattern 3: Architecture without maintenance.** Frozen, decayed, unmaintained. The fix is iteration discipline (refine continuously, redesign rarely). + +The metric pattern: funnel architecture failures often look fine on tool-level metrics. The signal is in cross-tool conversion, segment-level outcomes, and funnel-stage progression. Programs that track only tool metrics keep shipping the same architectural patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (tools-without-architecture, architecture-without-measurement, architecture-without-maintenance). The principle that tool-level metrics alone are insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific architecture-level dashboards. Specific cures the team applies. The team's audit and redesign processes. These vary by team. diff --git a/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md b/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md new file mode 100644 index 0000000..a74f62a --- /dev/null +++ b/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md @@ -0,0 +1,252 @@ +# Cross-tool data flow patterns + +Identity threading, context capture, segment tagging, sequence-tool integration. + +When the audience moves from one tool to another in the funnel, the audience signal travels with them. Done well, cross-tool data flow makes the audience experience continuous and lets the brand match content to the audience's specific journey. Done poorly, every tool starts from scratch and the audience signal is lost. + +--- + +## The continuity principle + +The audience experience should feel continuous across tools. Their interactions in one tool inform their experience in the next. + +**The win.** A visitor takes a quiz; the quiz tags them as "mid-market mid-funnel." When they later open the calculator, the defaults reflect mid-market context. When they download a lead magnet, the sequence delivered matches the segment. The visitor experiences a coordinated brand journey. + +**The fail.** The same visitor takes the quiz; the calculator does not know they took it; the lead magnet sequence is generic. Each tool is an island. The audience signal captured in one tool is wasted in the next. + +The discipline. Data flows. Each tool's interactions inform subsequent interactions. + +--- + +## Pattern A: Identity threading + +When the audience is identified, their identity carries forward across tools. + +**How it works.** + +- The audience opts in (email submission, account creation, login). +- Subsequent interactions are associated with that identity. +- Tools across the funnel access the identity record to personalize. + +**Strengths.** + +- Most powerful continuity mechanism. +- Lets all tools share context for the same person. + +**Weaknesses.** + +- Requires identity infrastructure (CRM, data warehouse, customer data platform). +- Privacy considerations (handling identity data carefully). + +**When to use.** When the program has identity infrastructure and the audience is willing to be identified (typically post lead-magnet download or account creation). + +--- + +## Pattern B: Context capture + +Inputs from one tool feed into the next interaction. + +**How it works.** + +- Tool A captures specific inputs (calculator values, quiz answers, form responses). +- Those inputs are stored with the identity (or with an anonymous session token). +- Tool B reads the inputs; uses them as defaults or context. + +**Example.** + +- Quiz captures "team size: 75." +- Calculator's defaults reflect team size 75. +- Lead magnet's recommended resource matches team size 75. + +**Strengths.** + +- Concrete continuity; the audience sees their inputs reflected. +- Reduces re-entry friction. + +**Weaknesses.** + +- Requires structured data capture (not just behavioral signals). +- Inputs from different tools must align (no conflict if quiz and calculator both capture team size). + +**When to use.** When tools capture overlapping or related context that benefits from shared use. + +--- + +## Pattern C: Segment tagging + +Each interaction tags the audience with segment information that informs future routing. + +**How it works.** + +- Tool A determines the audience's segment based on inputs (the quiz result; the calculator's input pattern). +- The segment tag attaches to the audience record. +- Subsequent tools and sequences route based on the tag. + +**Example.** + +- Quiz result: "Mid-market operator." +- Tag: segment = mid-market. +- Subsequent: lead magnet sequence is the mid-market sequence; calculator defaults are mid-market; chatbot routing is mid-market-aware. + +**Strengths.** + +- Lightweight. The tag is small; the routing logic uses it. +- Compatible with most marketing automation. + +**Weaknesses.** + +- Tag accuracy depends on the source tool's accuracy. +- Tags can conflict (different tools assign different segments). +- Tag staleness (the audience's segment may change over time). + +**When to use.** Default pattern for cross-tool routing. + +--- + +## Pattern D: Sequence-tool integration + +Email sequences include links to specific tools matched to the audience's segment. + +**How it works.** + +- Sequence email includes a CTA: "based on your situation, this calculator can help you compare." +- The CTA link includes parameters that pre-fill the calculator with the audience's known context. +- Audience clicks; calculator opens with their context already populated. + +**Strengths.** + +- Explicit cross-tool connection; the audience sees the journey. +- Reduces friction at the calculator (audience does not re-enter known information). + +**Weaknesses.** + +- Requires tooling for parameterized links and pre-fill. +- The pre-fill must respect what the audience consented to share. + +**When to use.** When the sequence is steering the audience toward specific tools and pre-fill would meaningfully reduce friction. + +--- + +## Conflict and source-of-truth + +When different tools capture different values for the same attribute. + +**The pattern.** The quiz says team size 75; the multi-step form says team size 60. Which is correct? + +**Approaches.** + +- **Latest wins.** The most recent capture overrides earlier captures. +- **Source authority.** Specific tools are designated as authoritative for specific attributes (form > quiz for verified data). +- **User confirmation.** Conflict surfaces a confirmation prompt: "We have you down as 75; is that still correct?" + +**The discipline.** Define source-of-truth for important attributes. Latest-wins is simple but can lose data; source authority is more disciplined but requires explicit definition. + +--- + +## Privacy and consent + +Cross-tool data flow involves handling user data. Consent matters. + +**The principle.** The audience should know what data flows where. Pre-filling a calculator with previously captured information is fine if the audience expects it; surprising them with knowledge they did not consent to share breaks trust. + +**Consent patterns.** + +- Explicit opt-in to identity tracking ("save my progress"). +- Disclosure of data flow ("we use your quiz answers to personalize subsequent recommendations"). +- Easy data deletion or account closure. + +**Privacy regulations.** GDPR, CCPA, and other regulations affect what data can flow and how. Compliance is essential; the architecture must respect the regulations applicable to the audience. + +--- + +## Anonymous-session continuity + +When the audience is not yet identified. + +**The pattern.** Browser-based continuity (cookies, local storage) lets tools share context within the same session even before identity capture. + +**Strengths.** + +- Continuity without requiring early opt-in. +- Smooth experience across same-session tool interactions. + +**Weaknesses.** + +- Lost when the audience switches devices or clears cookies. +- Limited persistence (typically days, not weeks). +- Privacy considerations (cookies-based tracking has its own complications). + +**When to use.** As a supplement to identity-based continuity; for early-funnel interactions before opt-in. + +--- + +## Cross-tool data flow architecture + +How to design the data flow at the architecture level. + +**The data layer.** A single data layer (CRM, customer data platform, data warehouse) holds the audience records. All tools read from and write to this layer. + +**The integration layer.** Tools integrate with the data layer either directly (API) or through a middleware (Zapier, Segment). + +**The privacy layer.** Consent and data-control mechanics live across the architecture; the data layer respects them. + +**Architecture-level discipline.** Cross-tool data flow is infrastructure work, not just tool work. Building the infrastructure is part of the funnel architecture investment. + +--- + +## Cross-tool measurement + +Track how data flows across tools. + +**Metrics.** + +- **Cross-tool engagement.** What percentage of subscribers who engaged with tool A also engaged with tool B? +- **Identity capture rate.** What percentage of visitors who interact with tools become identified? +- **Pre-fill usage.** When pre-fill is offered, what percentage of users engage with the pre-filled tool? +- **Segment tag accuracy.** Sample-based audit of whether segment tags match actual audience profiles. + +Diagnostic uses. Low cross-tool engagement signals tools are not connecting in the audience's journey; low pre-fill usage signals the pre-fill is not visible or not valued. + +--- + +## Cross-tool data flow audit + +Periodically audit the data flow. + +**The audit.** + +- Walk through critical journeys end-to-end. Does data actually flow? +- Verify identity threading works (logged-in user is recognized across tools). +- Verify context capture works (inputs in tool A appear in tool B as expected). +- Verify segment tagging works (quiz result tag triggers correct downstream sequences). +- Verify sequence-tool integration works (sequence links pre-fill correctly). + +**The drift.** Integrations break silently. Tool updates change data formats. Audit catches the drift. + +--- + +## Common data flow failures + +**No data flow.** Each tool isolated; identity and context lost between tools. + +**Identity threading broken.** Logged-in user not recognized across tools; same person treated as new visitor multiple times. + +**Context capture incomplete.** Tool A captures inputs but tool B does not access them. + +**Segment tag conflicts.** Different tools tag the same person differently; downstream routing inconsistent. + +**Pre-fill broken.** Sequence link includes parameters but the tool does not honor them; audience re-enters known information. + +**Privacy violations.** Cross-tool data flow happens without consent; audience surprised; trust damaged. + +**Stale data.** Audience's situation has changed but tools still use old captured data. + +--- + +## Methodology-level choices that stay in the public skill + +The continuity principle. Patterns A through D (identity, context, segment, sequence-tool integration). Conflict and source-of-truth. Privacy and consent. Anonymous-session continuity. Cross-tool data flow architecture. Cross-tool measurement. Audit cadence. Common failures. + +## Implementation choices that stay internal + +Specific data layer choices for the team's stack. Specific integration tooling. Specific consent flows and privacy disclosures. The team's audit calendars. These vary by team. diff --git a/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md b/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md new file mode 100644 index 0000000..d3cb1a1 --- /dev/null +++ b/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md @@ -0,0 +1,190 @@ +# Entry-point architecture patterns + +How visitors land vs how they're routed. Common entry points and their routing. + +The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). Without entry-point architecture, every visitor goes through the same first experience regardless of where they came from. + +--- + +## The entry-routing principle + +Each entry point has expected segments and stages. The first action available at the entry point should match those expectations. + +**The win.** A visitor arrives via an ad about "B2B SaaS pricing." The landing page serves consideration-stage pricing content. The first available action is a pricing calculator and a demo CTA. The entry point's routing matches the visitor's likely intent. + +**The fail.** Same visitor arrives via the same ad. The landing page is the homepage. The visitor lands in awareness-stage content with no clear next step. The mismatch costs the conversion. + +The discipline. Each entry point's first experience matches the visitor's likely segment and stage. + +--- + +## Common entry points + +The entry points most growth programs work with. + +**Paid landing page.** Visitor arrives via paid ad (search, social, display). High intent; specific to the ad's promise. + +Expected segment: usually narrow (the ad targeted specific audience). +Expected stage: usually consideration or decision (paid traffic is rarely awareness-stage). +Routing: landing page should serve the ad's specific promise; next-step action should match consideration or decision stage. + +**Organic content page.** Visitor arrives via search or content discovery; awareness or research stage. + +Expected segment: variable (organic search may surface multiple audience types). +Expected stage: usually awareness or early consideration (research-driven). +Routing: content should serve the search intent; secondary CTAs offer movement toward consideration. + +**Direct or returning visitor.** Visitor arrives by typing URL or via bookmark; often returning. + +Expected segment: variable (depends on prior interactions). +Expected stage: variable (could be any stage). +Routing: homepage should provide multiple entry paths to different segments and stages; navigation matters more than single CTA. + +**Referral.** Visitor arrives via partner or word-of-mouth; warmer than paid. + +Expected segment: variable (depends on referral source). +Expected stage: usually consideration or decision (referrals indicate active interest). +Routing: page should match the referral context; next-step action should reflect the warmth (free trial, demo, talk to sales often work). + +**Social.** Visitor arrives via social post; awareness or interest. + +Expected segment: variable (depends on social audience). +Expected stage: usually awareness (social discovery is rarely buying intent). +Routing: page should serve the social post's promise; soft CTAs (follow, subscribe, learn more) often work better than hard sells. + +**Tool entry.** Visitor arrives via a calculator, quiz, or chatbot directly (often via shared link or specific tool URL). + +Expected segment: matches the tool's audience. +Expected stage: usually consideration (the tool is a consideration-stage artifact). +Routing: tool should serve its specific value; next-step actions should connect tool output to broader funnel. + +--- + +## Entry-point routing patterns + +How to route each entry point. + +**Pattern A: Direct match.** Entry point routes directly to a specific landing page and CTA. Simple; works when the entry point's segment and stage are well-defined. + +**Pattern B: Routing layer.** Entry point routes to a routing page that asks 1-2 questions and then sends to the matched destination. Useful when the entry point's segment is variable. + +**Pattern C: Personalized landing.** Entry point routes to a landing page that adapts based on visitor attributes (source, behavior, profile). Sophisticated; requires personalization infrastructure. + +**Pattern D: Quiz-as-router.** Entry point routes to a quiz that segments and recommends. Detail in `quiz-and-assessment-design`. + +The choice depends on entry-point variability and infrastructure. Most programs start with Pattern A and add complexity as data shows the need. + +--- + +## Entry-point and segment matching + +Each entry point likely surfaces specific segments. + +**The discipline.** For each entry point, document the expected segments. The first experience should serve those segments. + +**Worked example.** + +- Entry point: paid ad targeting "data analytics for SaaS." +- Expected segments: data analysts and data leaders at SaaS companies. +- Expected stage: consideration. +- Routing: landing page on data analytics for SaaS; calculator showing ROI; CTA to demo. + +The match is deliberate. Visitors arriving via this entry point get a first experience that fits their segment and stage. + +--- + +## Entry-point and stage matching + +The first experience should match the visitor's likely stage. + +**Common mismatches.** + +- Awareness-stage visitor lands on a hard-sell decision-stage page; bounces because not ready. +- Decision-stage visitor lands on awareness-stage content; bounces because oversold on what they already know. +- Consideration-stage visitor lands on either; serves the wrong intent. + +**The cure.** Match the entry point's expected stage to the page's stage. Awareness pages serve awareness traffic; decision pages serve decision traffic. + +--- + +## Multi-entry funnels + +When the same visitor arrives via different entry points across visits. + +**The pattern.** A visitor sees an ad on Tuesday (paid entry); reads a blog post on Wednesday (organic entry); types the URL on Thursday (direct entry). Each entry point may surface a different first experience. + +**Architecture implications.** + +- Personalization across visits requires identity threading. +- Nurture sequences may need to acknowledge prior visits. +- Cross-channel attribution becomes important. + +**The discipline.** Architecture should accommodate multi-entry without confusion. The visitor's progression through the funnel respects their cumulative interactions, not just the latest entry. + +--- + +## Entry-point measurement + +Track per-entry-point performance. + +**The metric.** Per entry point: visitors, segment composition, stage composition, conversion to next action. + +**Diagnostic uses.** + +- Entry points with low conversion: routing may be mismatched. +- Entry points with high conversion: investigate what is working; replicate to other entries. +- Entry points whose segment composition does not match expectations: the source may have shifted; review. + +--- + +## Entry-point and audience-segment audit + +Periodically audit entry-point routing. + +**The audit.** + +- For each entry point: what segments and stages are arriving? +- Does the first experience match those segments and stages? +- Is conversion at this entry point above or below baseline? + +**The drift.** Entry points decay as ad targeting shifts, content rankings change, partners evolve. Quarterly audit catches the drift. + +--- + +## Entry-point anti-patterns + +**The single-funnel-for-every-entry.** All visitors go through the same first experience regardless of entry. Routing not matching segments or stages. + +**The over-personalized-entry.** Entry routing so specific that maintenance is impossible; many entries route to landing pages that exist only for one entry source. + +**The mismatched-entry.** Entry expects one segment; landing page serves a different one. Conversion suffers. + +**The unmeasured-entry.** Per-entry data not tracked; routing decisions are guesswork. + +**The orphan-entry.** Entry point exists; no landing page or routing defined; visitors land somewhere generic. + +--- + +## Common entry-point failures + +**One landing page for everyone.** Different entry points get the same first experience; routing not matching variability. + +**Wrong stage routing.** Awareness traffic gets decision-stage CTAs; decision traffic gets awareness content. + +**Personalization without infrastructure.** Architecture designed for personalization that the team cannot actually implement. + +**Entry-point drift.** Entry sources shifted; routing not updated. + +**Single-tool entry.** Only one tool serves an entry point; if the tool fails, the entry has no recovery. + +**Entry-conversion attribution missing.** Cannot tell which entry points produce which downstream conversion. + +--- + +## Methodology-level choices that stay in the public skill + +The entry-routing principle. Common entry points (6 patterns). Entry-point routing patterns (4 patterns). Entry-point and segment matching. Entry-point and stage matching. Multi-entry funnels. Entry-point measurement. Audit cadence. Anti-patterns. Common failures. + +## Implementation choices that stay internal + +Specific entry points for specific programs. Specific routing logic per entry. Specific landing pages per entry. The team's audit calendars. These vary by team and program. diff --git a/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md b/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md new file mode 100644 index 0000000..22a62e8 --- /dev/null +++ b/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md @@ -0,0 +1,189 @@ +# Funnel iteration discipline + +When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. + +Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +--- + +## The compound-vs-reset distinction + +Refinement compounds. Redesign resets. + +**Refinement.** Targeted changes to specific tools, sequences, or transitions within the existing architecture. The architecture's bones stay; the muscles get stronger. + +**Redesign.** Overhaul of the architecture. Segments redefined; tool-to-funnel mapping changed; sequences rebuilt. The architecture restarts. + +**The discipline.** Refine continuously; redesign deliberately and rarely. Constant redesign prevents compounding; never iterating allows decay. + +--- + +## When to refine + +Five conditions that signal refinement is appropriate. + +**Specific tools are underperforming relative to baseline.** A calculator with declining conversion benefits from input adjustment, default updates, or methodology refinement. The architecture is fine; the tool needs attention. + +**Specific segments have lower conversion than peer segments.** A segment that converts at 4 percent while peer segments convert at 10 percent has a fixable architecture issue. Refine the segment's path. + +**Specific transitions in the funnel are producing drop-off.** The transition from quiz to recommended product page has high drop-off. Audit the transition; fix. + +**Sequence engagement is declining for specific cohorts.** Newer subscribers to a sequence engage less than older subscribers. The sequence may have decayed; refresh content. + +**Specific entry points are routing wrong segments.** A paid ad source has shifted; visitors arriving from it no longer match the segment the landing page serves. Adjust the routing. + +These are refinements. The architecture is sound; specific elements need attention. + +--- + +## When to redesign + +Four conditions that signal redesign is appropriate. + +**Audience composition has fundamentally shifted.** The brand pivots; the target audience changes; the segments are no longer accurate. The matrix needs redesign. + +**Product or service strategy has changed.** The brand offers a fundamentally different product line; the funnel that served the old products no longer fits. Redesign. + +**Competitive landscape has shifted significantly.** A new competitor reshapes the buying process; the funnel needs to respond. Redesign may follow. + +**Multiple refine cycles have not produced expected results.** The team has refined repeatedly; conversion has not moved. The issue may be architectural rather than tactical. Redesign worth considering. + +These are redesigns. The architecture's fundamentals need to change. + +--- + +## The continuous-redesign trap + +Teams that constantly redesign never benefit from architectural compounding. + +**The pattern.** Every quarter, the team rethinks the funnel. New segments; new tools; new sequences. Each redesign is partially built before the next redesign starts. + +**The signal.** Conversion does not improve over time. Each iteration starts over. Learning does not accumulate because the structure keeps changing. + +**The cost.** The team's investment dilutes across redesigns. Tools never reach maturity. Sequences never stabilize. + +**The cure.** Redesign infrequently. Refine continuously between redesigns. Set a "no major redesign for X months" discipline if needed. + +--- + +## The frozen-architecture trap + +Teams that never iterate watch their architecture decay. + +**The pattern.** The funnel was designed once; the team treats it as finished. No refinement; no redesign; no audit. + +**The signal.** Conversion declines slowly over months and years. Tools age; sequences go stale; segments shift. The architecture does not respond. + +**The cost.** The architecture's value erodes. Audiences move on; competitors improve; the brand falls behind. + +**The cure.** Set refinement cadences. Quarterly audit; targeted refinements based on data. Acknowledge that no architecture stays optimal forever. + +--- + +## The middle ground + +Refine continuously; redesign infrequently and deliberately. + +**Refinement cadence.** Monthly or quarterly. Targeted; data-driven; small enough to test in isolation. + +**Redesign cadence.** Annually at most. Often longer. Major triggers (audience pivot, product change, competitive shift) drive redesign rather than calendar. + +**The discipline.** Both rhythms running in parallel. Refinement maintains; redesign responds to fundamental change. + +--- + +## Refinement workflow + +How to iterate productively. + +**Step 1: Identify the gap.** Data-driven; specific to a tool, segment, transition, or sequence. + +**Step 2: Hypothesize the cause.** What might explain the gap? + +**Step 3: Design a treatment.** What change would address the hypothesis? + +**Step 4: Test if possible.** A/B test or before-after measurement when feasible. + +**Step 5: Validate.** Did the metric move? Did downstream metrics also benefit? + +**Step 6: Roll out or roll back.** Successful refinements stick; unsuccessful ones revert. + +The discipline. Each refinement is hypothesis-driven and validated. Random changes do not compound. + +--- + +## Redesign workflow + +How to redesign without resetting everything. + +**Step 1: Articulate why.** What has fundamentally changed that warrants redesign? + +**Step 2: Preserve what works.** Identify elements of the current architecture that are still appropriate. Do not throw away learning. + +**Step 3: Design the new architecture.** Segment matrix; entry-point routing; tool-to-funnel mapping; sequence architecture. Document everything. + +**Step 4: Plan migration.** How to transition existing audience and tools to the new architecture without losing momentum. + +**Step 5: Pilot before full rollout.** Test the new architecture with a subset of audience or one segment before full deployment. + +**Step 6: Migrate.** Roll out the new architecture; retire the old one. + +**Step 7: Monitor closely.** Architecture-level metrics in the first months show whether the redesign delivered. + +The discipline. Redesign is a project, not a flip of a switch. Plan it; pilot it; migrate; monitor. + +--- + +## The decay-driven redesign signal + +How to know decay has accumulated to redesign level. + +**Signals.** + +- Multiple refine cycles have not moved the metric. +- Segments no longer describe the audience accurately. +- Tools designed for one segment are being used by others (mapping has drifted). +- The architecture diagram no longer matches the actual experience visitors have. +- Quarterly audits surface the same issues quarter after quarter without fix. + +When these signals accumulate, refinement is not enough. Redesign is needed. + +--- + +## Iteration measurement + +How to know iterations are working. + +**The metric.** Architecture-level metrics improving over time. Cross-tool conversion rising; segment-level conversion rising; funnel-stage progression accelerating. + +**The trap.** Improving one metric while others decline. A refinement that lifts cross-tool conversion but tanks lead quality is not net positive. + +**The discipline.** Watch the portfolio of metrics, not individual ones. Refinement should improve the architecture's overall outcomes, not just one measure. + +--- + +## Common iteration failures + +**Continuous redesign.** Architecture never stabilizes; learning does not compound. + +**Frozen architecture.** Architecture never iterates; decay accumulates. + +**Random refinement.** Changes without hypothesis or testing; results are noise. + +**Refinement without measurement.** Cannot tell if changes are working. + +**Redesign without preserving learning.** Throws away what was working alongside what was not. + +**Redesign without migration plan.** Audience and tools left in transition; experience suffers. + +**Iteration without portfolio metrics.** Improving one metric while damaging others. + +--- + +## Methodology-level choices that stay in the public skill + +The compound-vs-reset distinction. When to refine (5 conditions). When to redesign (4 conditions). The continuous-redesign trap. The frozen-architecture trap. The middle ground. Refinement workflow. Redesign workflow. The decay-driven redesign signal. Iteration measurement. Common failures. + +## Implementation choices that stay internal + +Specific iteration calendars for the team. Specific refinement and redesign processes. Specific tooling for testing iterations. The team's iteration history and lessons. These vary by team. diff --git a/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md b/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md new file mode 100644 index 0000000..d23c914 --- /dev/null +++ b/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md @@ -0,0 +1,222 @@ +# Funnel measurement patterns + +Architecture-level vs tool-level metrics. What to measure, what is noise. + +Funnel measurement should reveal architecture quality, not just tool quality. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. + +--- + +## The architecture-vs-tool measurement distinction + +Two layers of measurement. + +**Tool-level metrics.** Each tool's individual performance (calculator conversion, quiz completion, lead-magnet downloads). Detail in each tool's skill. + +**Architecture-level metrics.** How the tools and sequences compose. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. + +**The discipline.** Measure both layers. Architecture-level metrics are often the missing measurement. + +--- + +## Architecture-level metric: Cross-tool conversion + +What percentage of audience that hits tool A then engages with tool B. + +**The metric.** Count the visitors who interact with tool A (calculator, quiz, lead magnet, etc.). Of those, how many subsequently interact with tool B? + +**Why it matters.** Cross-tool engagement signals whether the funnel is composing. High cross-tool conversion means the architecture is working; low cross-tool conversion means tools are silos. + +**Measurement methods.** + +- Identity-based tracking (same identified user across tools). +- Session-based tracking (same session sees multiple tools). +- Cohort analysis (cohorts entering through tool A and their downstream tool engagement). + +**Diagnostic uses.** + +- Low cross-tool conversion: tools may not be promoted to each other's audiences; transitions may be broken. +- Specific tool pairs underperforming: those transitions need design attention. + +--- + +## Architecture-level metric: Sequence-to-tool conversion + +What percentage of nurture sequence subscribers engage with downstream tools. + +**The metric.** Count subscribers in a sequence. Of those, how many click through to a tool the sequence promoted? + +**Why it matters.** Sequences should drive subscribers toward tools matched to their segment-and-stage. Low sequence-to-tool conversion signals that the sequences are not effectively bridging to tools. + +**Diagnostic uses.** + +- Specific sequence emails with low click-through: the email's tool promotion may not match the audience. +- Specific tools with low sequence-driven traffic: the sequences may not be promoting those tools enough. + +--- + +## Architecture-level metric: Segment-level downstream conversion + +Per-segment conversion to the program's main goal. + +**The metric.** For each segment in the matrix: what percentage convert to the main goal (trial, demo, purchase) within a defined timeframe? + +**Why it matters.** Different segments will convert at different rates; segments significantly underperforming relative to peers signal architecture issues. + +**Diagnostic uses.** + +- Segments with low downstream conversion: the funnel architecture for that segment may be broken or under-developed. +- Segments with high downstream conversion: investigate what is working; replicate to other segments. + +--- + +## Architecture-level metric: Funnel-stage progression + +What percentage of audience moves from awareness to consideration to decision over time. + +**The metric.** Track audience as they progress through stages. Awareness audience this month; what percentage are in consideration next month; what percentage in decision the following. + +**Why it matters.** The funnel's job is to progress audience through stages. Low progression signals the nurture sequences and tools are not advancing the relationship. + +**Diagnostic uses.** + +- Slow progression: sequences may be too educational without enough advancement; or the audience may be getting stuck. +- Fast progression but low conversion: progression without quality. + +--- + +## Tool-level metrics + +Each tool has its own metrics. Detail in each tool's skill. + +**Calculator.** Conversion rate per visitor; tier-2 (email gate) conversion; downstream conversion of calculator-sourced leads. + +**Quiz.** Completion rate; per-segment downstream conversion; recommendation click-through. + +**Lead magnet.** Download rate; sequence engagement; downstream conversion of magnet-sourced subscribers. + +**Multi-step form.** Completion rate; per-step drop-off; lead quality. + +**Chatbot.** Resolution rate per intent; escalation rate; downstream conversion. + +The tool-level metrics tell you whether each tool is doing its job. The architecture-level metrics tell you whether the tools are doing the funnel's job. + +--- + +## What is noise + +Metrics that look important but are not. + +**Total tool engagements.** Volume without context. A tool with 10000 engagements per month tells you nothing without conversion context. + +**Email open rate alone.** Open rate is a leading indicator at best; sequence-to-conversion is the metric that matters. + +**Time on page or session length.** Often correlates with confusion as much as engagement. + +**Bounce rate alone.** High bounce rate on awareness content may be normal; on decision content may signal a problem; aggregate bounce rate is noise. + +The discipline. Measure outcomes, not activity. Activity metrics are noise unless connected to outcome metrics. + +--- + +## Measurement granularity + +How granular to measure. + +**Per-tool measurement.** Standard. Each tool tracked. + +**Per-segment-per-tool measurement.** Measure each tool's performance per segment. Surfaces segment-specific tool issues. + +**Per-segment-per-stage measurement.** Measure progression and conversion per cell in the matrix. + +**Per-cohort measurement.** Track cohorts (groups arriving in the same period) over time. Surfaces evolution and decay. + +**The discipline.** Granularity matters when it informs decisions. Per-segment-per-stage is often where the diagnostic value lives; per-cohort surfaces decay. + +--- + +## Attribution + +Connecting outcomes to specific tools and sequences. + +**The challenge.** Audiences interact with multiple tools and sequences. Which one drove the conversion? + +**Approaches.** + +- **First-touch attribution.** Credit goes to the first interaction. +- **Last-touch attribution.** Credit goes to the most recent interaction. +- **Multi-touch attribution.** Credit distributed across interactions. +- **Position-based attribution.** Credit weighted by position (often U-shaped or W-shaped). + +**The honest framing.** Attribution is a model. No model is perfectly accurate. Choose a model deliberately; understand its biases; report consistently. + +--- + +## Measurement and architecture decisions + +How metrics inform architecture changes. + +**The pattern.** Metrics surface gaps; architecture decisions address them; subsequent metrics validate. + +**Examples.** + +- Cross-tool conversion low: redesign transitions; promote tool B in tool A's exit; measure improvement. +- Specific segment underperforming: review segment's funnel path; adjust tools or sequences; measure. +- Funnel-stage progression slow: review sequence design; add or refine; measure. + +**The discipline.** Metrics inform decisions; decisions are tested; results validated. Without measurement, architecture changes are guesswork. + +--- + +## Measurement instrumentation + +What needs to be in place. + +**Identity tracking.** Identified users tracked across tools. +**Event tracking.** Each tool interaction logged with event data. +**Funnel definition.** The funnel stages and segments defined in the analytics tool. +**Cohort capability.** Ability to define and track cohorts. +**Reporting.** Dashboards or reports that surface architecture-level metrics. + +**The discipline.** Instrumentation should be in place before launch, not added later. Retrofitting measurement is harder than building it in. + +--- + +## Measurement cadence + +How often to look at architecture-level metrics. + +**Weekly review.** For high-velocity programs or recently launched architectures. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable programs. Tracks trends and surfaces gradual decay. + +**Quarterly review.** Comprehensive architecture audit. Per-cell analysis; segment-level deep dive; funnel-stage progression. + +**Triggered review.** When tools change, when segments shift, when external factors (market, competition) change. + +--- + +## Common measurement failures + +**Tool-level only.** Architecture-level metrics not tracked; cannot diagnose composition issues. + +**Vanity metrics.** Volume metrics without conversion context. + +**No segment-level granularity.** Aggregate metrics hide segment-specific issues. + +**Attribution model not chosen.** Reports inconsistent because attribution is ad-hoc. + +**No cohort tracking.** Cannot see decay or evolution. + +**Metrics without action.** Metrics reviewed but no decisions follow. + +**Confounded data.** Multiple changes deployed without isolation; cannot attribute outcomes to changes. + +--- + +## Methodology-level choices that stay in the public skill + +The architecture-vs-tool measurement distinction. Architecture-level metrics (cross-tool, sequence-to-tool, segment-level, funnel-stage). Tool-level metrics (cross-reference). What is noise. Measurement granularity. Attribution approaches. Measurement and architecture decisions. Instrumentation requirements. Measurement cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific programs. Specific tooling for measurement. Specific attribution models. The team's reporting conventions. These vary by team. diff --git a/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md b/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md new file mode 100644 index 0000000..6469028 --- /dev/null +++ b/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md @@ -0,0 +1,256 @@ +# Nurture sequence architecture + +Per-segment, per-stage sequence variation. The matched sequence win. + +Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. Done well, sequences compound the brand's relationship with the audience; done poorly, sequences treat everyone the same and convert no one well. + +--- + +## The matched-sequence principle + +Each segment-and-stage cell warrants a sequence designed for that cell. Different cells get different sequences. + +**The win.** An SMB consideration-stage subscriber gets a 5-email sequence focused on SMB-relevant comparison content, ROI examples from similar SMB customers, and a soft demo invitation. The sequence reads as if written for them. + +**The fail (kitchen-sink sequence).** Every subscriber regardless of segment or stage gets the same 5-email sequence. The content is generic enough to send to all; specific enough for none. SMB subscribers see enterprise examples; enterprise subscribers see SMB examples; conversion uniformly low. + +The discipline. Sequences vary by segment and stage. The matrix from `audience-and-stage-segmentation` is the sequence design map. + +--- + +## Sequence variation by stage + +Stage-specific sequence patterns. + +**Awareness sequence.** + +- Goal: build relationship; deepen brand association with the topic. +- Content: educational, broad value, brand-building. +- Frequency: typically lower (weekly to bi-weekly); the audience is not in active research. +- Soft offers: subscribe to newsletter, follow on social, attend webinar. +- Hard offers: rare; awareness audiences are not buying yet. + +**Consideration sequence.** + +- Goal: move from "evaluating" to "selecting." +- Content: comparative, specific value, product-fit signals. +- Frequency: higher (every 3-7 days); audience is actively evaluating. +- Soft offers: see comparison guide, take quiz, calculator. +- Hard offers: demo, trial, talk to sales (toward end of sequence). + +**Decision sequence.** + +- Goal: commit; sign up; purchase. +- Content: confidence-building, risk-reversal, urgency cues, case studies of similar customers. +- Frequency: high (every 2-4 days); audience is close to deciding. +- Soft offers: rarely; mostly hard offers. +- Hard offers: trial, signup, talk to sales, custom quote. + +**Customer sequence (often missed).** + +- Goal: deepen success; expand and retain. +- Content: feature deep-dives, success stories from similar customers, community invitations. +- Frequency: ongoing; matches product cadence. +- Soft offers: attend events, refer others. +- Hard offers: upgrade, add-on, expansion. + +--- + +## Sequence variation by audience + +Audience-specific sequence patterns. + +**SMB audience.** + +- Tone: practical, fast-execution, peer-to-peer. +- Examples: SMB customers; focus on quick wins and resource constraints. +- Content depth: shorter, scannable, action-oriented. + +**Mid-market audience.** + +- Tone: strategic, considered, multi-stakeholder. +- Examples: mid-market customers; focus on team adoption and process change. +- Content depth: moderate; depth where it matters; summaries for executives. + +**Enterprise audience.** + +- Tone: rigorous, evidence-based, formal. +- Examples: enterprise customers; focus on security, scale, integration. +- Content depth: deep; white papers, technical documentation, case studies with metrics. + +**Solo or creator audience.** + +- Tone: personal, founder-to-founder. +- Examples: similar solo practitioners; focus on individual impact and time savings. +- Content depth: practical; templates and how-tos over strategy. + +--- + +## Sequence design discipline + +How to design each sequence. + +**Step 1: Define the goal.** What conversion does this sequence drive? Awareness to consideration; consideration to demo; demo to decision; decision to purchase. + +**Step 2: Define the audience.** Which segment-and-stage cell does this sequence serve? + +**Step 3: Outline the arc.** What is the email-by-email progression? Each email should have a purpose; cumulatively the arc moves the subscriber toward the goal. + +**Step 4: Match content to arc.** What specific content (template, case study, framework, demo invitation) fits each step? + +**Step 5: Define triggers and cadence.** What triggers the sequence (lead magnet download, demo request, behavior signal)? What is the spacing? + +**Step 6: Define the soft and hard offers.** Where do soft offers appear? Where do hard offers appear? At what point does the sequence make a direct ask? + +**Step 7: Define the exit.** When does the sequence end? Where do subscribers go after (newsletter, segment-specific stream, retired)? + +The output is a documented sequence ready to build and ship. + +--- + +## Sequence cadence + +How frequently to send. + +**Awareness cadence.** Weekly to bi-weekly typical. The audience is not in active research; over-sending feels intrusive. + +**Consideration cadence.** Every 3-7 days typical. The audience is actively evaluating; cadence matches their consideration pace. + +**Decision cadence.** Every 2-4 days typical. The audience is close to deciding; cadence reflects urgency. + +**Customer cadence.** Variable. Match product cadence and customer engagement patterns. + +The cadence-too-frequent risk. Daily sends can fatigue; unsubscribe rates climb. + +The cadence-too-infrequent risk. Weekly sends to consideration audiences can lose momentum; the audience moves on. + +--- + +## Sequence content sourcing + +Where the content for sequences comes from. + +**Repurposed content.** Existing blog posts, case studies, white papers can populate sequences. Cost-effective; benefits from existing content investments. + +**Sequence-original content.** Content written specifically for the sequence. More effort; can be highly tailored to the audience and arc. + +**Hybrid.** Most sequences mix repurposed and original. Original content for the key arc moments; repurposed content for supplementary value. + +The discipline. Sequence content should fit the sequence's audience and stage; off-fit content (even good content) weakens the sequence. + +--- + +## Sequence triggers + +What launches the sequence. + +**Trigger types.** + +- **Lead magnet download.** Most common trigger. +- **Calculator completion.** With segment data captured. +- **Quiz completion.** With segment matched to result. +- **Multi-step form submission.** Demo request, qualification. +- **Behavior signal.** Visited specific pages, viewed pricing, abandoned cart. +- **Manual addition.** Sales team adds a contact. + +**The trigger discipline.** The trigger informs which sequence the subscriber enters. A lead-magnet download for an awareness-stage resource enters the awareness sequence; a calculator completion with consideration-stage signals enters the consideration sequence. + +**Trigger-segment routing.** Multiple triggers can route to multiple sequences based on captured segment information. The trigger is one signal; segment is another. + +--- + +## Sequence intersection and routing + +When subscribers might enter multiple sequences. + +**The challenge.** A subscriber downloads two lead magnets in the same week. Each magnet has its own sequence. Should they enter both? + +**Approaches.** + +- **Override.** Latest trigger overrides; subscriber enters the latest sequence and exits prior ones. +- **Concatenate.** Subscriber completes the first sequence, then enters the next. +- **Pause.** Active sequence pauses other triggers; subscriber returns to queue after current sequence. +- **Multi-path.** Subscriber enters multiple sequences simultaneously (risk of frequency overload). + +The choice depends on subscriber experience and sequence design. Most programs benefit from override or pause patterns to avoid frequency overload. + +--- + +## Sequence and offer alignment + +The offers in the sequence must match the audience. + +**The principle.** A sequence for SMB consideration-stage subscribers should pitch SMB-appropriate offers. Pitching enterprise offers in this sequence wastes the audience signal. + +**Offer alignment failures.** + +- Magnet attracts SMB; sequence pitches enterprise. +- Awareness sequence pitches hard sales offers prematurely. +- Decision sequence pitches awareness content the subscriber outgrew. + +**The cure.** Sequence offers reflect the audience and stage the sequence serves. + +--- + +## Sequence measurement + +Per-sequence metrics. + +**Open rate.** Per email; per sequence overall. + +**Click-through rate.** Per email; per sequence. + +**Conversion to next step.** What percentage of subscribers in this sequence completed the desired conversion? + +**Unsubscribe rate.** Per email; per sequence. + +**Sequence-to-customer conversion.** What percentage of subscribers in this sequence eventually became customers? + +Diagnostic uses. Low open rates per email signal subject-line issues; low click-through signals content fit issues; high unsubscribe rates signal cadence or content problems. + +--- + +## Sequence maintenance + +Sequences decay. + +**What decays.** + +- Content references go stale (outdated case studies, retired products). +- Offers change (new products, new pricing, new programs). +- Audience composition shifts; sequence content no longer fits. +- Email deliverability changes; subject lines that worked stop working. + +**Maintenance cadence.** Quarterly review of every active sequence. Update content; refresh offers; verify links. + +**The drift indicator.** Sequence performance declining over time signals decay; specific cohorts (newer subscribers vs older) performing differently signals audience shift. + +--- + +## Common sequence failures + +**One sequence for everyone.** Kitchen-sink pattern; matches no segment specifically. + +**Sequence-trigger mismatch.** The trigger captured one segment; the sequence is designed for another. + +**Offer misalignment.** Sequence pitches offers that do not match the audience. + +**Cadence wrong for stage.** Awareness cadence on consideration audience; consideration cadence on awareness audience. + +**No trigger logic.** Subscribers enter the same default sequence regardless of how they were captured. + +**Sequence-orphan magnets.** Lead magnets without follow-up sequences; subscribers go cold. + +**Stale sequence content.** Sequence designed once; content no longer reflects the brand or product. + +**No sequence measurement.** Sequence performance unknown; maintenance is guesswork. + +--- + +## Methodology-level choices that stay in the public skill + +The matched-sequence principle. Sequence variation by stage (4 stages). Sequence variation by audience (4 audiences). Sequence design discipline (7 steps). Sequence cadence. Sequence content sourcing. Sequence triggers. Sequence intersection and routing (4 approaches). Sequence and offer alignment. Sequence measurement. Sequence maintenance. Common failures. + +## Implementation choices that stay internal + +Specific sequences for specific segments. Specific email content in brand voice. Specific tooling for sequence automation and measurement. The team's cadence baselines. These vary by team. diff --git a/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md b/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md new file mode 100644 index 0000000..61de4bf --- /dev/null +++ b/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md @@ -0,0 +1,225 @@ +# Tool-to-funnel mapping + +Which tools serve which entry points and segments. Each tool in the growth toolkit has a place in the funnel architecture; the mapping makes the place explicit. + +Without explicit mapping, tools end up serving everyone (and serving no one well) or getting deployed where they do not fit. With explicit mapping, each tool serves the segments where it adds the most value. + +--- + +## The mapping principle + +Each tool serves specific segments at specific stages from specific entry points. The mapping is documented, not implicit. + +**The win.** A team's calculator is mapped to consideration-stage SMB and mid-market visitors arriving via organic content. The calculator's design (inputs, defaults, methodology) reflects this segment. Other segments do not see the calculator featured prominently; they see tools matched to their segment. + +**The fail.** A team's calculator is featured on every page for every visitor. The calculator's design is generic to serve everyone. SMB visitors see enterprise inputs; enterprise visitors see SMB defaults. The calculator serves nobody well. + +The discipline. Each tool has a defined place. The architecture documents which segments and stages and entry points the tool serves. + +--- + +## Common tool-to-funnel mappings + +How each growth tool typically maps. + +**Lead magnet.** Often serves awareness-to-consideration transition. + +- Audience: awareness-stage visitors who would benefit from a focused resource. +- Entry points: blog posts, content discovery, paid ads on educational topics. +- Position in funnel: captures email; routes to nurture sequence that bridges to consideration. +- Detail in `lead-magnet-design`. + +**Calculator.** Often serves consideration stage. + +- Audience: visitors evaluating options who need to defend a specific decision. +- Entry points: pricing pages, comparison content, paid ads on solution-evaluation. +- Position in funnel: provides defensible numeric output; routes to demo or trial CTA. +- Detail in `calculator-design`. + +**Quiz.** Variable depending on design. + +- Awareness quizzes: content marketing, brand-building. Captures email; routes to broad nurture sequence. +- Consideration quizzes: product matching, fit assessment. Captures email; routes to product-specific sequence. +- Decision quizzes: plan selection, configuration. Captures email and routes to specific sales motion or signup. +- Detail in `quiz-and-assessment-design`. + +**Multi-step form.** Often serves decision or qualification stage. + +- Audience: visitors with high intent who need to provide structured information. +- Entry points: demo CTAs, talk-to-sales pages, application flows. +- Position in funnel: captures qualified intent; routes to sales or to next-stage automation. +- Detail in `multi-step-form-design`. + +**Chatbot.** Cross-cutting; can serve any stage with intent recognition routing. + +- Audience: any visitor who has questions the bot can handle. +- Entry points: any page where conversation might add value. +- Position in funnel: handles in-conversation routing; escalates to humans for complex cases. +- Detail in `chatbot-flow-design`. + +--- + +## Mapping examples by audience segment + +How tools map for specific segments. + +**Solo founder, awareness stage.** + +- Lead magnet: practical template they can use today. +- Quiz (optional): "what stage of growth are you in" with matched recommendations. +- Chatbot: yes, for FAQ; lightweight routing. +- Calculator, multi-step form: probably not at this stage. + +**SMB team, consideration stage.** + +- Calculator: ROI estimate matched to SMB context. +- Lead magnet: comparison guide or worked example. +- Multi-step form: demo request capture. +- Chatbot: yes, for product-specific questions. +- Quiz (optional): plan recommendation. + +**Mid-market team, consideration-to-decision.** + +- Calculator: ROI estimate with mid-market context. +- Multi-step form: demo request with qualification. +- Chatbot: yes, with escalation to sales for complex questions. +- Lead magnet (optional): white paper or case study. +- Quiz: probably not (mid-market buyers often skip quizzes). + +**Enterprise, decision stage.** + +- Multi-step form: enterprise demo request with detailed qualification. +- Chatbot: lightweight; escalation-heavy. +- Custom calculator: with enterprise-specific inputs and ROI factors. +- Lead magnet, quiz: usually not (enterprise buyers expect direct human attention). + +The mapping is segment-aware. Tools that fit one segment may not fit another. + +--- + +## Mapping examples by stage + +How tools map for specific stages. + +**Awareness stage.** + +- Lead magnets prominent. Quizzes can serve. Calculators less common (consideration is when calculators earn their value). Chatbots support. +- Goal: capture awareness-stage email; route to nurture sequence. + +**Consideration stage.** + +- Calculators central. Quizzes useful for product matching. Lead magnets can deepen value. Chatbots support specific questions. +- Goal: convert consideration into qualified intent; route to demo or trial. + +**Decision stage.** + +- Multi-step forms central (demo requests, qualified intent capture). Calculators support specific decisions. Chatbots route to sales. +- Goal: convert decision-stage intent into commitment. + +**Customer stage.** + +- Onboarding flows (which can use multi-step forms). Chatbots for support. Lead magnets and quizzes less central; replaced by in-product education. +- Goal: deepen customer success; expand and retain. + +--- + +## Mapping discipline + +How to make the mapping rigorous. + +**Discipline 1: Document the mapping.** Write down which tools serve which segments and stages. The document is the architecture's reference. + +**Discipline 2: Match tool design to mapping.** A tool serving SMB should have SMB-relevant inputs and defaults; a tool serving enterprise should reflect enterprise context. + +**Discipline 3: Promote tools where they fit.** Show calculators on consideration-stage pages; show lead magnets on awareness-stage pages. Generic tool placement on every page dilutes their value. + +**Discipline 4: Retire tools that do not fit.** A tool that does not have a mapping is decorative. Either find its place or retire it. + +**Discipline 5: Audit the mapping quarterly.** Mappings decay as audience composition shifts. Quarterly review catches drift. + +--- + +## Multi-tool segments + +Some segments use multiple tools across their journey. + +**The pattern.** A consideration-stage SMB visitor uses a lead magnet (awareness arrival), a calculator (consideration depth), then a multi-step demo form (decision intent). Three tools across the journey. + +**Architecture implications.** + +- Each tool serves a specific moment in the visitor's journey. +- Cross-tool data flow lets each tool benefit from earlier interactions. +- Tools should not duplicate each other's value. + +**The discipline.** Tools complement, not duplicate. Each tool earns its place in the segment's journey. + +--- + +## Tool overlap and choice + +When multiple tools could serve the same segment-and-stage cell. + +**The pattern.** A team has both a calculator and a quiz that could serve consideration-stage SMB. + +**The decision.** Choose the tool that serves the segment best, or use both with clear differentiation. + +- Calculator: when the consideration involves a specific calculation (ROI, savings, sizing). +- Quiz: when the consideration involves categorization or product matching. +- Both: when the segment benefits from both, with clear positioning of when each helps. + +The discipline. Avoid having multiple tools competing for the same segment without clear differentiation. Audiences pick the most prominent; the others underperform. + +--- + +## Tool gaps + +When the mapping reveals gaps. + +**The pattern.** The architecture documents which tools serve which segments. Some cells in the matrix have no tool; the audience there has no relevant tool to engage with. + +**The decision.** Either build a tool to fill the gap, or accept that some cells use generic content rather than tools. + +- Build when the segment is high-value and the tool would meaningfully improve conversion. +- Accept when the segment is small or the tool would not earn its build cost. + +The architecture surfaces gaps; the team decides what to do about them. + +--- + +## Tool-mapping audit + +Periodically audit which tools serve which segments and how well. + +**The audit.** + +- For each tool: which segments does it currently serve? Which segments does it actually attract? +- For each cell in the matrix: which tools are mapped to it? Are they performing? +- Are any tools serving segments outside their intended mapping (drift)? + +**The drift indicators.** Tool conversion drops; tool's audience composition changes; tool gets traffic from segments it was not designed for. + +--- + +## Common mapping failures + +**No mapping.** Tools deployed without explicit segment-and-stage assignment. + +**Mismatched mapping.** Tool serving segments it was not designed for; tool's design does not fit the audience. + +**Decorative mapping.** Mapping documented but not enforced; tool appears everywhere regardless of mapping. + +**Stale mapping.** Mapping designed once; not updated as tools or audiences evolved. + +**Tool overlap without differentiation.** Multiple tools competing for the same segment; audience splits; none performs well. + +**Mapping gaps unaddressed.** Cells in the matrix have no tool support; the architecture has holes. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle. Common tool-to-funnel mappings (5 tools). Mapping examples by audience segment (4 examples). Mapping examples by stage (4 examples). Mapping discipline (5 disciplines). Multi-tool segments. Tool overlap and choice. Tool gaps. Tool-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific tool-to-segment mappings for specific programs. Specific tool placement decisions on specific pages. The team's audit calendars. These vary by team and program. diff --git a/skills/incident-response/SKILL.md b/skills/incident-response/SKILL.md new file mode 100644 index 0000000..f484749 --- /dev/null +++ b/skills/incident-response/SKILL.md @@ -0,0 +1,260 @@ +--- +name: incident-response +description: "Manage active production incidents through detection, triage, mitigation, communication, and resolution with structured roles and decision-making. Use this skill whenever the user has an active incident, a production issue, a service outage, a security incident, or needs to plan incident response procedures. Triggers on incident response, production incident, outage, service down, site down, P0, P1, severity, downtime, on-call, incident commander, status page, postmortem prep. Also triggers when something is actively broken in production and the user is figuring out what to do." +category: operations +catalog_summary: "Incident triage, comms, mitigation, escalation" +display_order: 2 +--- + +# Incident Response + +Manage active production incidents from detection to resolution. Stack-agnostic. Tool-agnostic. + +This skill is for active incidents and incident process. For after-the-fact analysis, use `after-action-report`. For planned launches, use `launch-runbook`. + +--- + +## When to use + +- An active incident is happening +- Building incident response procedures +- Defining severity levels +- Setting up on-call rotations +- Training a team on incident response + +## When NOT to use + +- Post-incident retrospective (use `after-action-report`) +- Planned launches (use `launch-runbook`) +- Pre-launch issue triage (use `qa-testing`) + +--- + +## Required inputs + +- Awareness of the incident (alert, customer report, internal observation) +- Access to production systems and monitoring +- Roles and authorities clearly defined +- Communication channels operational + +--- + +## The framework: 5 phases + +### 1. Detection + +How the incident becomes known. + +**Detection sources:** + +- Automated alerts (monitoring, SLO violations, error rate spikes) +- Customer reports (support tickets, social media, status page subscribers) +- Internal observation (engineer notices something off) +- Third-party (security researchers, partners) + +**On detection:** + +- Acknowledge within target time (typically 5 to 15 minutes for critical) +- Assess severity (see severity rubric below) +- Page the on-call if not already paged +- Open the incident channel + +### 2. Triage + +Establish severity and impact. + +**Severity rubric:** + +| Severity | Definition | Response | +|---|---|---| +| SEV-1 (Critical) | Major customer-facing functionality broken. Data integrity at risk. Security breach. | All-hands. Incident commander. Active war room. Public communication required. | +| SEV-2 (Major) | Significant degradation. Some customers affected. Revenue impact. | Incident commander assigned. Active response. Internal communication. May or may not need public communication. | +| SEV-3 (Minor) | Limited impact. Workaround available. Affecting a small group of users. | Standard on-call response. Single owner. | +| SEV-4 (Low) | Cosmetic, edge-case, or low-frequency. No urgent action needed. | Tracked as bug. Addressed in normal queue. | + +Severity can change. Re-evaluate as more info emerges. + +### 3. Mitigation + +Stop the bleeding before fixing the cause. + +**Mitigation patterns (faster than full fix):** + +- **Rollback** (revert recent deploy) +- **Feature flag off** (disable the broken feature without deploy) +- **Failover** (route to healthy replica or region) +- **Scale up** (more capacity to absorb the load) +- **Throttle** (reject some traffic to protect the rest) +- **Graceful degradation** (turn off non-essential features to keep core functional) +- **Maintenance mode** (last resort, blocks all users) + +**Mitigation principle:** Stop user impact first. Cause analysis second. + +### 4. Communication + +Three audiences during an incident: + +**Internal team:** +- Real-time updates in incident channel +- Cadence: every 15 minutes minimum during active incident +- Format: timestamped status updates with what we know, what we're doing, ETA + +**Internal stakeholders:** +- Higher-level updates to broader org +- Cadence: every 30 to 60 minutes +- Format: business-impact framing, not technical detail + +**External / customers:** +- Status page updates +- Cadence: every 30 minutes minimum during active incident +- Format: plain language, no blame, what users are experiencing, what to expect + +**Communication principles:** +- Acknowledge before you have answers ("We're aware and investigating") +- Update on schedule even if no progress ("Still investigating, no new information") +- Never speculate publicly about cause +- Confirm resolution explicitly when restored + +### 5. Resolution + +Verified fix, customers restored, incident closed. + +**Resolution criteria:** + +- Mitigation in place and verified +- Root cause identified (or explicitly deferred to AAR) +- All affected systems back to normal +- Customers can resume normal use +- Final status update posted (internal and external) +- Incident channel can be closed (or archived for AAR) + +After closure: +- Schedule AAR within 1 to 2 weeks +- Capture initial timeline while memories are fresh +- Track follow-up action items + +--- + +## Roles during an incident + +| Role | Responsibility | +|---|---| +| Incident commander (IC) | Owns the response. Calls decisions. Assigns work. Not necessarily the most technical person; needs to coordinate. | +| Communications lead | Owns internal and external messaging. Reduces IC's communication burden. | +| Operations lead | Drives the technical investigation and mitigation. Often the most senior on-call engineer. | +| Scribe | Captures the timeline as the incident unfolds. Critical for AAR. | +| Subject matter experts | Pulled in as needed. Service owners, database experts, security experts. | + +For small teams or low-severity incidents, one person can hold multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Decision-making during an incident + +**The IC's authority:** + +- Call rollback or other mitigations +- Pull additional people in +- Escalate severity +- Make the call when unclear options exist + +**Non-decisions to avoid:** + +- "Let's wait and see" when mitigations are available and impact is occurring +- Discussing root cause while users are actively impacted (mitigate first) +- Premature resolution announcements before verification +- Death-by-committee (pull in lots of people, no one decides) + +When in doubt: act. A wrong action that can be rolled back beats inaction while users suffer. + +--- + +## Status page communication patterns + +**Initial:** +> "We are investigating reports of [issue]. Updates to follow." + +**Identified:** +> "We have identified the issue affecting [scope]. Engineers are working on a fix. Next update by [time]." + +**Monitoring:** +> "A fix has been applied. We are monitoring to confirm resolution. Next update by [time]." + +**Resolved:** +> "This incident has been resolved. Service has been restored. A full incident report will be posted within [timeframe]." + +Patterns to avoid: + +- Vague language ("experiencing some issues" - what kind?) +- Missing affected scope ("login is down" - everywhere or just one region?) +- Missing time commitments +- "Should be resolved soon" without verification +- Using "back up" before verification + +--- + +## Workflow + +1. **Acknowledge.** First responder acknowledges within target time. +2. **Assess severity.** Use the rubric. Open the appropriate response channel. +3. **Assign roles.** IC, comms, ops at minimum. +4. **Communicate.** Initial status update. Internal channel active. +5. **Investigate.** Logs, metrics, recent changes. The four most common causes: a recent deploy, a configuration change, a third-party dependency change, a load spike. +6. **Mitigate.** Stop the bleeding. Don't wait for full root cause. +7. **Verify mitigation.** Don't trust dashboards alone; test the user flow. +8. **Communicate resolution.** Internal and external. +9. **Close incident.** Final timeline noted. Action items tracked. +10. **Schedule AAR.** Within 1 to 2 weeks. + +--- + +## Failure patterns + +- **No clear IC.** Multiple people debugging in parallel, no coordination. Slower to mitigate, easier to make conflicting changes. +- **Skipping mitigation, going straight to root cause.** Users keep suffering while engineers debug. +- **Premature "all clear."** Announcing resolution before verification. +- **Communication silence.** Users don't know if anyone is working on it. +- **Status updates too vague.** "We're working on it" with no detail. +- **Speculating publicly about cause.** Often wrong, always damaging trust. +- **Pulling in too many people.** Coordination overhead exceeds value. +- **No scribe.** The timeline gets lost. AAR has to reconstruct from chat logs. +- **Skipping AAR for "minor" incidents.** Patterns get missed. Lessons get re-learned. +- **Blame culture.** People hide mistakes, incidents take longer. + +--- + +## Output format + +During an active incident: incident channel updates and status page updates as per the framework above. + +After incident close: a brief incident summary feeding into the AAR. + +```markdown +# Incident: [Brief title] + +**Date:** [YYYY-MM-DD] +**Severity:** [SEV-1 / 2 / 3 / 4] +**Duration:** [Detection to resolution] +**Customer impact:** [Who, how many, how] + +## Summary +[1 to 2 paragraphs] + +## Timeline +[Timestamped events] + +## Mitigation +[What was done] + +## Action items +[Follow-ups, with owners] + +## AAR scheduled for +[Date] +``` + +--- + +## Reference files + +- [`references/incident-playbook.md`](references/incident-playbook.md) - Severity definitions, roles, status page templates, decision rubrics. diff --git a/skills/incident-response/references/incident-playbook.md b/skills/incident-response/references/incident-playbook.md new file mode 100644 index 0000000..b960f45 --- /dev/null +++ b/skills/incident-response/references/incident-playbook.md @@ -0,0 +1,280 @@ +# Incident Playbook + +The reference document during an incident. Severity definitions, role responsibilities, communication templates, and decision rubrics. + +--- + +## Severity rubric + +### SEV-1: Critical + +**Definition:** +- Major customer-facing functionality completely broken +- Data loss or data integrity at risk +- Active security breach or vulnerability being exploited +- Significant revenue impact ongoing + +**Response:** +- All-hands response activated +- Incident commander assigned (within 10 minutes of detection) +- War room (video call) opened +- Public status page updated immediately +- Executive notification within 15 minutes +- Customer-facing communication within 30 minutes + +**Acknowledgment SLA:** 5 minutes +**Update cadence:** Every 15 minutes +**Resolution target:** As fast as humanly possible + +### SEV-2: Major + +**Definition:** +- Significant degradation affecting many users +- Important feature unavailable +- Performance severely degraded +- Revenue impact, but limited + +**Response:** +- Incident commander assigned (within 30 minutes) +- Active investigation in incident channel +- Status page updated +- Internal communication to broader org +- Public communication if customer-facing + +**Acknowledgment SLA:** 15 minutes +**Update cadence:** Every 30 minutes +**Resolution target:** Within hours + +### SEV-3: Minor + +**Definition:** +- Limited impact (specific feature, specific user segment) +- Workaround available +- No revenue impact, or minor + +**Response:** +- Single owner assigned +- Standard on-call response +- No status page update unless customer-facing +- No public communication unless trending + +**Acknowledgment SLA:** 1 hour +**Update cadence:** As progress dictates +**Resolution target:** Within a day + +### SEV-4: Low + +**Definition:** +- Cosmetic issue +- Edge case affecting few users +- No customer impact + +**Response:** +- Track as bug, not incident +- Address in normal queue + +**Acknowledgment SLA:** Next business day +**Resolution target:** As prioritized + +--- + +## Roles + +### Incident Commander (IC) + +**Responsibilities:** +- Owns the response +- Makes decisions when options exist +- Assigns work to others +- Decides when to escalate severity +- Decides when to declare resolution +- Coordinates without doing technical work themselves + +**NOT the IC's job:** +- Doing the actual debugging +- Speculating about cause publicly +- Writing status page updates (delegates to comms lead) + +**Selection criteria:** Calm under pressure, good at coordination, clear communicator. Does not need to be the most senior or most technical. + +### Communications Lead + +**Responsibilities:** +- Posts internal updates on schedule +- Drafts status page updates +- Coordinates with customer support +- Drafts executive notifications +- Manages external messaging + +**Removes:** Communication burden from IC and ops lead. + +### Operations Lead + +**Responsibilities:** +- Drives the technical investigation +- Identifies the cause +- Identifies and applies mitigations +- Coordinates with subject matter experts +- Verifies fixes + +### Scribe + +**Responsibilities:** +- Captures the timeline as the incident unfolds +- Records decisions and rationale +- Records actions taken +- Provides material for the AAR + +**Often filled by:** A junior engineer (good learning experience), someone not in the active investigation, or anyone tasked specifically with note-taking. + +### Subject Matter Experts (SMEs) + +Pulled in as needed. Service owners, database experts, security experts, third-party vendors. Pulled by IC, not self-deploying. + +--- + +## Status page templates + +### SEV-1 / SEV-2 initial + +> "We are currently investigating reports of [user-facing description of impact]. Affected users may experience [specific symptoms]. We will update by [time, typically +30 minutes]." + +### Identified + +> "We have identified the cause of the issue affecting [scope]. Engineers are deploying a fix. Next update by [time]." + +### Monitoring + +> "A fix has been applied. We are monitoring to confirm full resolution. Next update by [time]." + +### Resolved + +> "This incident has been resolved. All services have returned to normal. A full incident report will be posted within [typically 1 week]. Thank you for your patience." + +### Patterns to avoid + +| Avoid | Why | Use instead | +|---|---|---| +| "Some users may be experiencing issues" | Vague | "Users in [region] may experience [specific symptom]" | +| "We are working on it" | Empty | "Engineers are investigating [hypothesis or symptom]" | +| "Should be resolved shortly" | Speculative | "Next update by [specific time]" | +| "We apologize for the inconvenience" | Hollow | Acknowledge specifically, then state action | +| Technical jargon | Excludes users | Plain language describing user experience | +| Blame language | "Our database vendor failed" | Focus on user impact and our response | + +--- + +## Decision rubrics + +### Should we roll back? + +Roll back if: +- A recent deploy correlates with the start of the incident +- Rollback can be completed safely +- The risk of leaving the broken state exceeds the risk of rollback + +Don't roll back if: +- The incident clearly predates the recent deploy +- Rollback would cause data loss or worse impact +- A targeted fix is available and faster + +When unsure: roll back. Recovery from rollback is usually cheaper than continued debugging in a broken state. + +### Should we declare SEV-1? + +Declare SEV-1 if any are true: +- Most users cannot use the core product +- Revenue is being lost at significant rate +- Data integrity is at risk +- A security breach is happening +- Senior leadership awareness is required + +When unsure between SEV-1 and SEV-2: start with SEV-1. Easier to de-escalate than to scale up. + +### Should we communicate publicly? + +Communicate publicly if any are true: +- Customers are experiencing impact and will notice +- Customer support is receiving inquiries +- The incident is visible externally (status page, social media chatter) +- Regulatory notification may be required (data breach, certain financial systems) + +Don't communicate publicly if: +- Impact is invisible to users +- Confidence is high that it will be resolved before users notice (but lean toward communication) + +When unsure: communicate. Silence on the status page is worse than a brief acknowledgment. + +### Should we escalate? + +Escalate to senior leadership if: +- Severity has reached SEV-1 +- Resolution is taking longer than expected at SEV-2 +- Decisions are needed that exceed the IC's authority +- Reputational risk is material + +--- + +## On-call rotation principles + +A healthy on-call: + +- **Rotates regularly.** Same person on call indefinitely is unsustainable. +- **Has a clear primary and secondary.** Backup if primary is unavailable. +- **Has documented runbooks.** On-call is not pop quiz. +- **Has acknowledgment SLAs that match severity.** A 1-hour SLA on SEV-1 is too slow. +- **Is paid or compensated** in some form. Time on-call has cost. +- **Includes a hand-off ritual.** Outgoing on-call briefs incoming on open issues, recent deploys, hot spots. + +Anti-patterns: + +- One person who is "always on" because they know the system best +- On-call without monitoring (you can only respond to what you know) +- On-call who lacks production access (cannot mitigate) +- No primary/backup, just one person + +--- + +## Common mitigation patterns + +| Symptom | Try first | +|---|---| +| Errors after recent deploy | Roll back the deploy | +| Errors with no recent deploy | Check third-party dependencies, recent config changes | +| Database errors | Check connection pool, recent query changes, capacity | +| Latency spike | Check load, capacity, slow downstream | +| Specific feature broken | Feature flag off if available | +| Security incident | Isolate affected systems, rotate credentials, preserve logs | +| Data integrity issue | Stop writes, snapshot, investigate before continuing | + +When unsure of cause but mitigation is available: mitigate. Investigate cause separately. + +--- + +## After the incident + +Once resolved: + +1. Final status page update (resolved) +2. Final internal update +3. Capture initial timeline (the scribe's notes) +4. Identify obvious follow-up action items, file tickets +5. Schedule AAR within 1 to 2 weeks +6. Hand off any monitoring to normal operations + +In the next 24 to 48 hours, while memory is fresh: + +- Each participant writes their own brief account of what they observed and did +- These individual accounts become primary source material for the AAR +- This avoids reconstruction errors that come from trying to piece together what happened weeks later + +--- + +## Anti-patterns to call out + +- **Hero culture.** One person stays up all night to fix it; gets praised. Real lesson: the system is too brittle, and the team has too little redundancy. +- **Blame in retrospectives.** "Whose fault was this?" produces hidden mistakes next time. +- **Skipping AARs for "minor" incidents.** The minor incidents are often the patterns that predict major ones. +- **Action items that never close.** Action items get filed, never actioned. The same incident recurs. +- **Status pages updated only at start and end.** "Updating every 30 minutes" with the same content is still better than silence. +- **Investigating root cause while users are impacted.** Mitigate first. diff --git a/skills/information-architecture/SKILL.md b/skills/information-architecture/SKILL.md new file mode 100644 index 0000000..b77d8a7 --- /dev/null +++ b/skills/information-architecture/SKILL.md @@ -0,0 +1,254 @@ +--- +name: information-architecture +description: "Design the structure of a website or product including sitemap, navigation, URL structure, content types, taxonomy, and labeling. Use this skill whenever the user asks to plan a sitemap, design navigation, structure URLs, define content types, build taxonomies, design site search, or organize content at the system level. Triggers on sitemap, site structure, navigation, IA, information architecture, URL structure, content types, taxonomy, categorization, breadcrumbs, hub pages, faceted navigation, site search, labeling. Also triggers when content is being created without a structural plan, or when an existing site's structure is being audited or restructured." +category: strategy-and-discovery +catalog_summary: "Sitemap, navigation, URL structure, content types, taxonomy" +display_order: 4 +--- + +# Information Architecture + +Design the structure that holds the content. Stack-agnostic. Applies to marketing sites, product surfaces, knowledge bases, e-commerce, and editorial content. + +A well-designed IA makes the rest of the project easier. A poorly-designed IA forces every downstream decision to fight the structure. + +--- + +## When to use + +- Designing a new site or major section from scratch +- Restructuring an existing site +- Adding a new content type or category +- Designing site navigation or menu systems +- Defining URL structure and slug patterns +- Building taxonomies or tag systems +- Auditing an existing IA for problems + +## When NOT to use + +- Single-page design (use `design-standards`) +- Content production (use `content-and-copy`) +- SEO-driven content planning (use `seo-keyword`) +- Initial brand and audience discovery (use `brand-discovery`) + +--- + +## Required inputs + +- The site or product scope +- The audience and what they're trying to do +- The content that exists or is planned +- Any constraints (parent IA, regulatory, technical) + +If audience is unclear, run `brand-discovery` first. If content scope is unclear, run `content-strategy` first. + +--- + +## The framework: 6 layers + +Information architecture has six layers. Each builds on the one below. + +### 1. Mental models + +Before structure, understand how the audience thinks about the domain. + +- What concepts do they group together naturally? +- What words do they use? (Often different from what the company uses.) +- What is the dominant frame of reference? (By task? By role? By topic? By time?) +- What do they expect to find where, based on conventions in similar products? + +**Methods:** + +- **Card sorting** (open or closed): Give the audience the content items, ask them to group them. Open card sorts surface natural groupings. Closed card sorts validate proposed groupings. +- **Tree testing:** Give a proposed structure, ask users to find specific items. Surfaces where the structure breaks down. +- **First-click testing:** Given a goal, where do users click first? If first clicks are wrong, the labels and structure are wrong. + +### 2. Sitemap + +The map of all pages and how they relate. + +**Sitemap deliverables:** + +- A hierarchy diagram showing parent-child relationships +- Indication of page types (static, dynamic, listing, detail) +- Cross-references showing how pages relate beyond the hierarchy +- Sometimes a separate user-flow overlay for key journeys + +**Sitemap types:** + +- **Hub-and-spoke** (cornerstone content + supporting content): Common for content marketing +- **Tree** (strict hierarchy, every page has one parent): Common for product documentation +- **Faceted** (content lives in many overlapping categories): Common for e-commerce +- **Flat** (everything reachable from the home): Common for small sites + +Most sites blend types. Pick the dominant pattern and document the exceptions. + +### 3. URL structure + +URLs are part of the IA. They are user-facing, indexed by search engines, and shape how content is referenced. + +**URL principles:** + +- Reflect the content hierarchy +- Lowercase, hyphen-separated +- Predictable (same pattern across same content type) +- Stable (URLs don't change without redirects) +- Short (under 60 characters where possible) +- Descriptive (slug indicates the content) +- Free of dates unless time-bound +- Free of session IDs and tracking parameters in canonical form + +**Common patterns:** + +``` +/ home +/[section] section landing +/[section]/[subsection] subsection landing +/[section]/[subsection]/[item] detail page +/blog blog index +/blog/[slug] blog post +/blog/category/[category] category index +/blog/tag/[tag] tag index +/products product catalog +/products/[category] category page +/products/[category]/[product] product detail +``` + +Pick a pattern and stick to it. Inconsistent URL patterns confuse users, crawlers, and analytics. + +### 4. Navigation + +The chrome that gets users where they need to go. + +**Primary navigation:** + +- The top-level structure of the site +- Should reflect what the audience cares about, not what the org chart looks like +- 5 to 7 items maximum (more becomes cognitively heavy) +- Each label is recognizable in 2 to 3 words +- Order matters (left/first gets the most attention) + +**Secondary navigation:** + +- Within-section navigation +- Often shown as sidebars, sub-menus, or in-page tabs +- Supports the primary nav, doesn't duplicate it + +**Utility navigation:** + +- Account, search, login, support +- Visually subordinate to primary nav +- Often top-right (LTR languages) + +**Breadcrumbs:** + +- For nested hierarchies (3+ levels deep) +- Always linked except the current page +- Match the URL hierarchy or the conceptual hierarchy +- Marked up with BreadcrumbList schema + +**Footer navigation:** + +- Comprehensive; sometimes includes everything +- Organized by category for findability +- Includes secondary content (privacy, terms, contact) + +### 5. Taxonomy and metadata + +The classification system applied to content. + +**Categories:** + +- A small, controlled list (typically 5 to 15) +- Mutually exclusive ideal (one item, one category) +- Used for structural navigation + +**Tags:** + +- A larger, often growing list (50+) +- Multi-assignment (one item, many tags) +- Used for cross-cutting connections, related-content, and long-tail discovery + +**Metadata fields:** + +- Author, date, content type, audience segment +- Whatever is useful for filtering, sorting, and surfacing + +**Common failures:** + +- Categories that overlap (item could go in 3 different categories) +- Tags that are unmaintained (sprawl into thousands, become useless) +- Metadata fields that get filled inconsistently +- Different content types using different taxonomies for the same thing (chaos) + +### 6. Labeling + +What you call things. + +**Label principles:** + +- Audience language, not internal language +- Specific enough to be useful, short enough to scan +- Consistent across the site (call it "Product" or "Solutions" but not both) +- Tested with real users (closed card sort or tree test surfaces label problems) + +**Common label problems:** + +- "Solutions" (vague; usually means "products with marketing copy") +- "Resources" (catch-all; everything ends up there) +- Internal jargon ("PRD," "OKRs") that doesn't match user vocabulary +- Labels that change meaning across the site + +--- + +## Workflow + +1. **Understand the audience and content.** Use existing discovery and content strategy if available. +2. **Card sort or interview** to surface mental models. +3. **Draft the sitemap.** Hierarchy, page types, cross-references. +4. **Define URL patterns.** One pattern per content type. +5. **Design navigation.** Primary, secondary, utility, footer, breadcrumbs. +6. **Build taxonomy.** Categories (controlled, small) and tags (open, large). +7. **Validate labels.** Tree test or closed card sort with target users. +8. **Document.** Use the template in [`references/ia-document-template.md`](references/ia-document-template.md). +9. **Hand off to design and development.** IA decisions inform navigation components, URL routing, and taxonomy implementation. + +--- + +## Failure patterns + +- **IA designed by org chart.** "Engineering" and "Marketing" sections make sense to the company, not to the audience. +- **Categories that proliferate.** Every team adds a category for their thing. Becomes unscannable. Hold the line at 5 to 15. +- **Tags that sprawl.** No tag governance. Tags become a junk drawer. +- **Inconsistent URL patterns.** Some posts at /blog/[slug], some at /[slug], some at /articles/[slug]. Pick one. +- **Navigation that hides primary content.** The most important pages should be one click from home. +- **Search as a substitute for IA.** "Just use search" is not a structure. Search supports IA, doesn't replace it. +- **No validation.** Card sorts, tree tests, and first-click tests are cheap and surface huge problems early. +- **Treating IA as a one-time deliverable.** IA evolves with content. Plan for evolution. + +--- + +## Output format + +Default output is an IA document at `information-architecture.md` plus visual assets: + +1. Executive summary +2. Audience and mental models (synthesized) +3. Sitemap (hierarchical diagram) +4. URL structure (per content type) +5. Navigation specification (primary, secondary, utility, footer, breadcrumbs) +6. Taxonomy (categories and tag governance) +7. Labels (validated wording for navigation, categories, content types) +8. Implementation notes for design and development + +Visual deliverables: +- Sitemap diagram (Whimsical, Figma, OmniGraffle, etc.) +- Navigation wireframes for primary surfaces +- Optional: card sort and tree test results + +--- + +## Reference files + +- [`references/ia-document-template.md`](references/ia-document-template.md) - Template for the IA deliverable. +- [`references/url-pattern-library.md`](references/url-pattern-library.md) - URL pattern conventions for common content types. diff --git a/skills/information-architecture/references/ia-document-template.md b/skills/information-architecture/references/ia-document-template.md new file mode 100644 index 0000000..4f7ad12 --- /dev/null +++ b/skills/information-architecture/references/ia-document-template.md @@ -0,0 +1,298 @@ +# Information Architecture Document Template + +A fillable template for the IA deliverable. Captures the sitemap, navigation, content types, taxonomy, and URL conventions. + +The IA document is the single source of truth for "what is this site, structurally." Engineering, design, content, and SEO all reference it. + +--- + +## Project metadata + +**Site / app:** [Name] +**Phase:** [New build / restructure / refresh] +**Date:** [YYYY-MM-DD] +**IA lead:** [Name] +**Status:** [Draft / In review / Approved] + +--- + +## 1. Audience and intent + +The IA serves audience tasks. Start with the tasks. + +### Primary audiences + +| Audience | Top tasks on this site | +|---|---| +| | | +| | | +| | | + +### Top tasks + +The 5-10 things people most commonly want to do or find. + +1. [Task] +2. [Task] +3. [Task] +4. [Task] +5. [Task] + +Each task should be discoverable in 3 clicks or fewer from the homepage. + +--- + +## 2. Sitemap + +The full set of pages the site contains, organized by hierarchy. + +### Top-level navigation + +The 4-7 sections that appear in the main nav. + +``` +Home +├── [Section 1] +├── [Section 2] +├── [Section 3] +├── [Section 4] +├── [Section 5] +└── [Utility nav: Login, Search, Cart, etc.] +``` + +### Full sitemap + +``` +Home (/) +├── Section 1 (/section-1/) +│ ├── Sub-page 1.1 (/section-1/sub-page-1-1/) +│ ├── Sub-page 1.2 (/section-1/sub-page-1-2/) +│ └── Sub-page 1.3 (/section-1/sub-page-1-3/) +├── Section 2 (/section-2/) +│ ├── Category 2.1 (/section-2/category-2-1/) +│ │ └── Detail pages (/section-2/category-2-1/[slug]/) +│ └── Category 2.2 (/section-2/category-2-2/) +├── Section 3 (/section-3/) +├── About (/about/) +├── Contact (/contact/) +├── Legal +│ ├── Privacy (/privacy/) +│ ├── Terms (/terms/) +│ └── Cookies (/cookies/) +└── 404 (/[unmatched]) +``` + +### Pages outside primary nav + +Pages that exist but are not in the top nav. Reachable from footers, contextual links, search, or direct entry. + +| Page | URL | Reached from | +|---|---|---| +| | | | +| | | | + +--- + +## 3. Navigation + +### Primary nav + +- **Items:** [List] +- **Behavior on desktop:** [Always visible / dropdown / mega menu] +- **Behavior on mobile:** [Hamburger / bottom nav / slide-in] +- **Active state indicator:** [Underline / color / weight] +- **Sticky on scroll:** [Yes / no] + +### Secondary nav + +If applicable. Examples: section nav within a section, sidebar nav for docs, breadcrumbs. + +- **Used in:** [Sections] +- **Pattern:** [Sidebar / breadcrumbs / tabs / pills] + +### Utility nav + +Login, search, cart, language switcher, account. Where they live on desktop and mobile. + +### Footer nav + +Comprehensive map of the site, plus legal and contact. + +- **Sections:** [Group names and what is in each] +- **Treatment:** [Links only / links + descriptions / multi-column / single column on mobile] + +--- + +## 4. Content types + +The reusable patterns that pages fall into. Each content type has a defined schema. + +### Content type: [Name, e.g., "Article"] + +- **Purpose:** [What this content type is for] +- **Required fields:** [Title, body, author, publish date, etc.] +- **Optional fields:** [Hero image, related articles, summary] +- **URL pattern:** [`/blog/[slug]/`] +- **Template:** [Which page template renders this] +- **SEO defaults:** [Default title pattern, meta description pattern, schema type] +- **Open Graph defaults:** [OG image source, OG type] + +(Repeat for each content type: page, article, product, case study, landing page, author, category, tag, etc.) + +--- + +## 5. Taxonomy + +How content is organized and tagged for filtering, related-content surfacing, and navigation. + +### Categories (hierarchical) + +The primary classification, often used in URLs. + +- Category 1 + - Subcategory 1.1 + - Subcategory 1.2 +- Category 2 + +Categories are typically mutually exclusive (a piece belongs to one). + +### Tags (flat, multi-select) + +Cross-cutting attributes a piece can have multiple of. + +- [Tag] +- [Tag] +- [Tag] + +### Custom taxonomies + +Domain-specific facets (e.g., for a recipe site: cuisine, dietary, cook time, meal type). + +| Taxonomy | Values | Used by content types | +|---|---|---| +| | | | +| | | | + +--- + +## 6. URL conventions + +See `url-pattern-library.md` for the full URL pattern reference. The IA document captures decisions specific to this site. + +| Type | Pattern | Example | +|---|---|---| +| Home | `/` | `/` | +| Static page | `/[slug]/` | `/about/` | +| Section landing | `/[section]/` | `/products/` | +| Article detail | `/blog/[slug]/` | `/blog/how-to-x/` | +| Product detail | `/products/[slug]/` | `/products/widget/` | +| Category archive | `/category/[slug]/` | `/category/news/` | +| Tag archive | `/tag/[slug]/` | `/tag/announcements/` | +| Author page | `/author/[slug]/` | `/author/jane-doe/` | +| Search results | `/search/?q=[query]` | `/search/?q=widget` | + +### Trailing slash policy + +[All URLs end with trailing slash / no trailing slash. Pick one and enforce via redirect.] + +### Casing + +[Lowercase only. Hyphens for word separation.] + +--- + +## 7. Search + +- **In-site search included?:** [Yes / no] +- **Source of truth:** [Internal index, Algolia, Elasticsearch, native CMS search] +- **Surface in nav:** [Always visible / icon-only / hidden behind utility nav] +- **Result page URL:** [`/search/?q=[query]`] +- **Result types:** [Pages, articles, products, etc.] +- **Filters:** [What filters appear on the result page] +- **Empty-state message:** [Text and suggested actions] + +--- + +## 8. Cross-linking strategy + +How pages link to other pages within the site. + +### Hub-and-spoke + +Pillar pages (hubs) link to related detailed pages (spokes). Spokes link back to the hub. + +| Hub | Spokes | +|---|---| +| `/topic-area/` | `/topic-area/[detail-1]`, `/topic-area/[detail-2]` | + +### Related content blocks + +Where they appear, what populates them. + +- **Article footer:** [Same category / same tag / manually curated] +- **Product detail page:** [Same category, similar price, frequently bought with] +- **Sidebar:** [Trending, recent] + +### Contextual links in body copy + +The single highest-value cross-link mechanism. Editorial guidelines: + +- Link the first natural mention of a related topic +- 2-5 contextual links per article +- Anchor text describes the destination, not "click here" + +--- + +## 9. Pagination, infinite scroll, and load more + +For listing pages (archives, search, category, etc.). + +| Listing type | Pattern | Page size | URL behavior | +|---|---|---|---| +| Article archive | Pagination | 10 per page | `/blog/page/2/` | +| Search results | Load more | 20 per page | URL stays at `/search/?q=...` | +| Product grid | Pagination | 24 per page | `/products/?page=2` | + +Pick deliberately. Each pattern affects SEO, accessibility, and analytics. + +--- + +## 10. Multilingual / multi-region + +If applicable. See `internationalization` skill for full guidance. + +- **Languages supported:** [List] +- **Regions supported:** [List] +- **URL pattern for locale:** [`/en/`, `/es/` subdir / `en.example.com` subdomain / no prefix on default locale] +- **Hreflang strategy:** [How locale alternates are declared] +- **Default locale fallback:** [What happens for unmatched locales] + +--- + +## 11. Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## 12. Change log + +| Date | Change | Approved by | +|---|---|---| +| | | | +| | | | + +--- + +## Sign-off + +IA approved by: + +- IA lead: [Name, date] +- Engineering lead: [Name, date] +- Content lead: [Name, date] +- SEO lead: [Name, date] + +Implementation can begin: [Date] diff --git a/skills/information-architecture/references/url-pattern-library.md b/skills/information-architecture/references/url-pattern-library.md new file mode 100644 index 0000000..75bf052 --- /dev/null +++ b/skills/information-architecture/references/url-pattern-library.md @@ -0,0 +1,377 @@ +# URL Pattern Library + +Conventional URL patterns for common content types. Use as a starting point. Adapt for the specific site. + +URL patterns matter because: +- Users see them in the address bar +- Search engines use them as a relevance signal +- They appear in shared links and citations +- Inconsistent patterns are a structural smell that creates downstream problems + +--- + +## Universal principles + +Apply to every URL on every site: + +- **Lowercase.** `/about` not `/About`. +- **Hyphens, not underscores.** `/blog/getting-started` not `/blog/getting_started`. +- **No trailing slash** for non-folder URLs (or always with trailing slash; pick one and be consistent). +- **No file extensions.** `/about` not `/about.html` or `/about.php`. +- **No query strings in canonical URLs.** Filters and sorts can use query strings, but the canonical version is parameter-free. +- **Stable.** URLs do not change without a 301 redirect from the old URL. +- **Predictable.** Same content type uses the same URL pattern site-wide. + +--- + +## Marketing site patterns + +### Home + +``` +/ +``` + +### Top-level pages + +``` +/about +/contact +/pricing +/careers +/blog +/help +``` + +Avoid generic catch-alls like `/info` or `/page`. + +### Sub-pages within sections + +``` +/about/team +/about/values +/about/history +/careers/engineering +/careers/design +``` + +Two levels deep is the typical maximum for marketing site pages. Beyond that, structure usually breaks down. + +### Marketing landing pages + +``` +/[campaign-slug] short, memorable, often used in print/ads +/lp/[campaign-slug] namespaced under /lp for clarity +/[product]/[campaign] nested under product if relevant +``` + +For high-traffic ad campaigns, a short root-level URL is fine. For evergreen marketing pages, namespace them. + +--- + +## Blog and editorial patterns + +### Blog index + +``` +/blog +``` + +### Blog posts + +``` +/blog/[slug] +``` + +The dominant pattern. Simple, scannable, no dates in the URL (so updates don't change the URL). + +If dates are genuinely required (news sites, time-sensitive content): + +``` +/blog/[year]/[month]/[slug] +``` + +But avoid dates by default. They make URLs longer and stale-looking when content gets updated. + +### Categories and tags + +``` +/blog/category/[category-slug] +/blog/tag/[tag-slug] +``` + +Or, if you prefer cleaner URLs: + +``` +/blog/[category-slug]/[post-slug] embeds category in the post URL +``` + +The embedded version is cleaner but creates URL changes when posts move categories. Pick based on whether posts move categories. + +### Author pages + +``` +/author/[author-slug] +/blog/author/[author-slug] +``` + +The first if authors are site-wide. The second if authors are blog-specific. + +### Archive pages + +``` +/blog/archive/[year] +/blog/archive/[year]/[month] +``` + +Optional, mostly for SEO and historical browsing. Often noindexed if they don't add unique value. + +--- + +## Product / e-commerce patterns + +### Product catalog + +``` +/products +/shop +``` + +Pick one and use site-wide. Don't have both. + +### Categories + +``` +/products/[category] +``` + +### Sub-categories + +``` +/products/[category]/[subcategory] +``` + +Two levels of category is typical maximum. Deeper hierarchies hurt findability. + +### Product detail + +``` +/products/[category]/[product-slug] +/products/[product-slug] if categorization isn't critical +``` + +The first is more SEO-friendly (signals category relevance). The second is cleaner but loses the hierarchy signal. + +### Filters and search + +``` +/products/[category]?filter=value&sort=price-asc filters as query strings +``` + +Canonical URL ignores query strings. Use the bare category URL as the canonical. + +--- + +## Documentation patterns + +### Docs root + +``` +/docs +/help +/support +``` + +### Sections + +``` +/docs/getting-started +/docs/api +/docs/integrations +``` + +### Pages within sections + +``` +/docs/getting-started/installation +/docs/api/authentication +/docs/integrations/slack +``` + +Two to three levels is typical. Deeper hierarchies become hard to navigate. + +### API reference + +``` +/docs/api/[endpoint] +/docs/api/v[N]/[endpoint] versioned APIs +/api-reference/[endpoint] if API docs are separate +``` + +--- + +## Account and product surface patterns + +These are the URLs inside an authenticated product. Not visible to crawlers but still matter for usability and consistency. + +### Dashboard + +``` +/dashboard +/app +/home inside the product, not the marketing site +``` + +### Settings + +``` +/settings +/settings/[section] +/account +/account/[section] +``` + +### Resources within an account + +``` +/projects +/projects/[id] +/projects/[id]/[resource] +/projects/[id]/[resource]/[item-id] +``` + +For e-commerce or SaaS, IDs matter more than slugs since these are user-specific items. + +--- + +## Special URL patterns + +### Search results + +``` +/search?q=[query] +``` + +Or, for SEO-friendly search landing pages: + +``` +/search/[query] +/find/[query] +``` + +The second pattern creates indexable search pages, which can be useful or harmful depending on the site. + +### Filter/facet pages (e-commerce or directory) + +``` +/[category]/[filter-slug] e.g., /running-shoes/men +/[category]?[filter]=[value] filters via query string +``` + +Static filter pages are SEO-friendly. Dynamic query strings are cleaner but don't index. + +### Pagination + +``` +/blog/page/2 +/blog/page/3 +/blog?page=2 via query string +``` + +The path-based version is more SEO-friendly. Either works as long as you canonical correctly. + +### Profile pages + +``` +/u/[username] +/users/[username] +/profile/[username] +/[username] if usernames don't conflict with other paths +``` + +The last (root-level usernames) is the cleanest but requires careful conflict prevention. + +### Internationalization + +``` +/[locale]/[path] e.g., /en/about, /es/about +[subdomain].domain.com/[path] e.g., en.domain.com/about +domain.[ccTLD]/[path] e.g., domain.fr/about +``` + +Each has tradeoffs. Path-based is most flexible. Subdomain is good for cleanly separated content. ccTLD is best for genuine country targeting. + +Use hreflang tags to indicate language pairs regardless of the URL strategy. + +--- + +## URL anti-patterns + +### Anti-pattern: Tracking parameters in canonical URLs + +``` +Bad: /post?utm_source=newsletter +Good: /post (with utm parameters preserved at runtime but stripped from canonical) +``` + +UTM parameters are for analytics, not for canonical URLs. + +### Anti-pattern: Session IDs in URLs + +``` +Bad: /products?sid=ABC123 +Good: /products (session in cookies, not URL) +``` + +URLs should be safe to share. Session IDs in URLs leak sessions when shared. + +### Anti-pattern: Verb-heavy URLs + +``` +Bad: /show-product/[id] +Good: /products/[id] +``` + +URLs are nouns, not verbs. + +### Anti-pattern: Date in URLs for evergreen content + +``` +Bad: /blog/2024/05/how-to-write-headlines +Good: /blog/how-to-write-headlines +``` + +Dates make URLs feel stale. They also break when posts get updated. + +### Anti-pattern: Stop words in URLs + +``` +Acceptable: /the-best-running-shoes +Better: /best-running-shoes +``` + +Removing "the," "and," "of" makes URLs shorter without losing meaning. + +### Anti-pattern: Fragment-only navigation + +``` +Bad: /home#features (no /features page) +Good: /features (real URL) +``` + +Fragments don't index. Real pages do. + +--- + +## Migration considerations + +When changing URL patterns on an existing site: + +1. **Map every old URL to a new URL.** No exceptions. +2. **301 redirect old URLs to new.** Permanent redirect preserves SEO equity. +3. **Avoid redirect chains.** Old URL should redirect directly to the new URL, not to an intermediate. +4. **Update internal links.** Every internal link should point at the new URL, not the old. +5. **Update sitemap.** New URLs only, no legacy URLs. +6. **Wait 90+ days before removing redirects.** Search engines and external sites take time to update. + +See `seo-technical/references/migration-checklist.md` for the full migration playbook. diff --git a/skills/integration-orchestrator/SKILL.md b/skills/integration-orchestrator/SKILL.md new file mode 100644 index 0000000..9a80690 --- /dev/null +++ b/skills/integration-orchestrator/SKILL.md @@ -0,0 +1,171 @@ +--- +name: integration-orchestrator +description: "Generate a phased delivery orchestration plan for creative-direction-driven work: which skills run when, what locks at which gate, how handoffs occur, and how the cadence implements in the team's tools (Jira, Linear, Notion, Figma, GitHub) with AI agents via MCP and CLI. A temporal map of phases, lock points, handoff specs, gate definitions, and QA verification gates. Distinct from `creative-brief` (static project brief) and `creative-direction` (aesthetic direction). Triggers on integration orchestrator, delivery cadence, project orchestration, when does the brief lock, how to phase creative direction, design-development handoff, QA gate, agent-driven QA, and when a creative-direction project is starting, mid-flight with broken cadence, or integrating AI agents into PM workflow. Does NOT fire for project scoping (use `creative-brief`), aesthetic direction (use `creative-direction`), or general project management without a creative-direction throughline." +category: product +catalog_summary: "Sequence creative-direction work across phases, gates, handoffs, and QA verification" +display_order: 3 +--- + +# Integration Orchestrator + +A brief tells a team what to make. Creative direction tells them what it should feel like. Neither tells them when each decision locks, who reviews what, or what stops the next phase from starting before the prior one is done. That is the gap this skill fills. + +The output is a phased orchestration plan the PM can paste into a calendar Monday morning and start running Tuesday. Phases, gates, lock points, handoffs, QA verification rules, and a platform-specific implementation guide for whatever stack the team actually uses (Jira, Linear, Notion, Figma, GitHub, agile sprints). + +--- + +## What this skill is + +A creative-direction project has three layers. The brief layer defines scope, audience, deliverables, constraints, success criteria. The direction layer defines tone, aesthetic, relationship, and sensory ambition. Both produce written artifacts. Neither answers the temporal question: when does the brief lock, when does identity lock, when does copy lock, who reviews each, what gets blocked while a gate is open, what happens when a downstream task discovers the brief is wrong, and what makes "Done" mean tested rather than self-reported. + +This skill produces that temporal layer. Most teams have briefs and creative direction but no orchestration plan. The result, by week 3, is everyone working in parallel with no shared sense of which decisions are still open and which are locked. Brief drift. Re-work. Identity tokens shifted after copy was already drafted against the old ones. Engineering shipping before design had a chance to review. "Done" tickets that were never actually verified. + +The orchestration plan answers all of that. It is not theory. It is a phased timeline with calendar weeks, ticket templates the PM can paste into Jira or Linear, MCP commands for setup, gate definitions with measurable pass criteria, handoff specs with artifact requirements, and QA verification gates with Playwright or Chrome MCP invocations. + +--- + +## When to use + +- Starting a new brand build, rebrand, or campaign and the team needs to sequence the work +- Mid-flight project where the brief is being revisited and downstream work is suffering from constant resets +- Setting up a new team's agent-driven workflow with MCPs and CLI integration +- Multi-team work where handoffs between brand, design, and engineering have broken down +- Establishing QA verification gates so "Done" is measurable, not self-reported +- Migrating from ad-hoc orchestration to a documented cadence +- Onboarding a new PM or design lead onto an existing project that has running tickets but no documented sequencing +- Adding new platforms or tools to an existing workflow and the cadence needs to be re-mapped + +--- + +## When NOT to use + +- Use `creative-brief` instead if the deliverable is the project brief itself: scope, audience, deliverables, constraints, success criteria. The orchestrator skill takes the brief as input. +- Use `creative-direction` if the deliverable is the aesthetic direction: tone, aesthetic, relationship, sensory. The orchestrator schedules the work that answers to the direction; it does not produce the direction. +- Generic project management software is the platform; this skill produces the plan that runs IN the platform. Do not run this skill if the team needs help picking a tool; it assumes the tool stack is already chosen. +- Sprint-planning tactics (story-pointing, retros, velocity charts) live downstream of orchestration. The skill produces the cadence; sprint planning fills it in. + +--- + +## Required inputs + +- **Project type.** New brand build, rebrand, single landing page, campaign, identity refresh, website refresh, microsite, product launch. The type implies a default phase decomposition that the skill adapts to the specific project. +- **Team composition.** Total size and role mix. Solo, small (2-3), medium (4-7), large (8+). Whether AI agents (Claude Code, Claude in Chrome, others) participate in production, QA, or both. +- **Tool stack.** Which of Jira, Linear, Notion, Figma, GitHub the team uses. Plus QA tooling (Playwright, Chrome MCP, Windows MCP, mobile testing harnesses) if known. Plus communication and paging channel (Slack, email, in-tool mention). The output adapts to the actual stack. +- **Timeline target.** Express (compressed timelines, fewer reviewers, accept higher rework risk), standard (typical cadence at the project type's default duration), or thorough (more reviewers, formal phase reviews, lower rework risk at the cost of slower delivery). +- **Existing constraints.** What is already locked? Brief approved, identity locked, platform fixed, brand voice already shipped, content management system non-negotiable. The orchestrator plan handles greenfield and mid-flight equally; the existing constraints input is how mid-flight projects are accommodated. +- **AI agent participation.** Which workflows include agents and at what fidelity. Examples: Claude Code does production tasks against a state file in the repo; Claude in Chrome runs human-readable QA flows on the staging deployment; the agent has access to the Linear MCP and the GitHub MCP but not Jira; the agent can move tickets between Todo, In Progress, Waiting, and Blocked but cannot move to Done (Done requires a human verification step). +- **Risk profile.** Optional input naming the failure modes the team is most worried about: brief drift, parallel-work conflicts, QA gaps, agent runaway. The orchestration plan front-loads mitigations for the named risks. + +--- + +## The framework: 7 considerations for orchestration + +A delivery orchestration plan sits at the intersection of seven considerations. Each filters the choices that follow. + +### 1. Phasing + +How the project decomposes into phases. The standard shape is discovery, direction, identity, production, QA, and launch. Not every project type uses every phase. A campaign skips identity (it inherits the locked brand identity). A landing page collapses discovery and direction into a single brief phase. A rebrand replaces discovery with audit (positioning is known; the audit assesses what to keep). + +The shape of the phases matters less than the explicit answer to two questions per project: which phases run sequentially because the downstream phase cannot start without the prior phase's output, and which phases overlap because their outputs do not depend on each other. Identity must complete before copy starts (copy depends on tone-axis position, which is part of identity). QA must complete before launch. Discovery and audit may overlap with brief drafting, because the brief consumes discovery findings as they emerge. + +### 2. Gates + +A gate is the approval moment that governs phase transition. The standard gates are brief approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, and launch readiness. Each gate has a trigger (the work that opens it), an approver (the person or test suite that passes it), required-to-pass criteria (the measurable thing that says yes or no), what's blocked until the gate passes, and what's already locked from prior gates. + +Gates work when the criteria are measurable. "Brief approved" is too vague; "client signed the brief artifact in writing or in a recorded review" is measurable. "QA passed" is too vague; "Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained" is measurable. Gates that are not measurable become political; gates that are measurable become structural. + +### 3. Lock points + +A lock point is the moment an artifact becomes immutable. The brief locks after direction is approved. Identity tokens lock after the identity gate. Voice rules lock after voice approval. Copy locks per page after copy approval. Once locked, the artifact cannot be changed by downstream work; it can only change via a formal change request that triggers re-review of dependent work. + +Without explicit lock points, every artifact is conceptually editable forever. That is the source of brief drift. The orchestrator plan names what locks at which gate, where the locked artifact lives, who can request a change, and what gets re-reviewed if a change is approved. Locked is not the same as final; locked means "any further change to this triggers downstream review work, so make changes deliberately." + +### 4. Handoffs + +A handoff is the moment work transfers between phases or skills. The standard handoffs are discovery to brief, brief to identity, brief to voice, identity plus voice to copy, identity plus copy to design, design to engineering, engineering to launch. Each transfers specific artifacts and decisions. Each leaves some things open and locks others. + +There is also a cross-cutting handoff: the adjacent observation handoff. While working on the homepage hero, an agent or person notices the footer copy is inconsistent with the new voice. That observation is not the current task. It is filed as an observation in the project triage queue. The PM or tech lead reviews observations on a regular cadence and triages them into proper tickets. This pattern keeps current work focused while not losing the contextually-relevant findings the team would otherwise either drop or derail current work to address. + +### 5. Team-size modulation + +A 2-person team and a 12-person team need different orchestration. Solo work is one person playing every role. Small (2-3) means a single reviewer per gate and async handoffs are fine. Medium (4-7) needs multiple reviewers and async sync points. Large (8+) needs formal phase reviews, a dedicated PM for orchestration, and explicit cross-track sync ceremonies because parallel tracks drift apart without them. + +The orchestration plan output modulates by scale. Solo gets self-review checklists per phase. Small gets per-gate "review by" assignments. Medium gets reviewer rotation and within-phase mini-gates. Large gets formal phase reviews, cross-track sync, and a brief-owner role. The framework is the same; the cadence's review density and ceremony level change. + +### 6. Tool-stack implementation + +Phases and gates exist in concept; they implement in tools. The orchestration plan specifies the implementation per platform: in Jira, phases become Epics with custom fields for "Phase", "Locked", "Approver", and "Gate Status"; in Linear, phases become Projects with cycles and label-driven views; in Notion, the brief becomes a database row with relation properties tying to direction docs, identity specs, voice guides, and copy decks; in Figma, phases become library folders with frame-level review status; in GitHub, phases interact with branch protection, PR templates, and CODEOWNERS-driven review routing. + +Where MCPs exist (Atlassian, Linear, Notion, GitHub), the plan specifies which orchestration setup operations the MCP can execute and which remain manual UI work. Where MCPs are limited (Figma's Dev Mode MCP is dev-mode-focused; the design library setup remains manual), the plan documents the recommendation without claiming end-to-end automation. + +### 7. Automation and QA verification + +The single most consequential discipline in the framework. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The standard status taxonomy is Todo, In Progress, Waiting, Blocked, Done. Blocked is a first-class status, distinct from Waiting. Waiting means the task is paused for normal handoff or scheduled review; Blocked means the task cannot proceed without human resolution of a specific issue. Agents move tasks to Blocked when they cannot autonomously resolve work; this prevents agents from spinning on un-resolvable problems and burning context. + +QA verification gates fire automatically. Playwright MCP runs critical-flow tests; Chrome MCP runs human-readable walkthroughs and captures evidence; Windows MCP handles desktop apps; mobile testing harnesses cover mobile applications. Failure routes to Blocked, files an adjacent observation if the failure surfaced something unrelated, pages the human via the configured channel, and stops. The agent does not retry autonomously. + +--- + +## Common project-type cadences + +Seven templates. Each is a skeletal phase map; the cadence-patterns reference file expands each. + +- **New brand build.** 6 to 8 weeks across 5 phases: Discovery (1 week), Direction (1 week), Identity (1 to 2 weeks), Production (2 to 3 weeks), Launch (1 week). Gates fire after each phase; identity locks before copy starts. +- **Rebrand.** 4 to 6 weeks across 4 phases: Audit (1 week, replaces Discovery), Direction (1 week), Identity (1 to 2 weeks), Production (1 to 2 weeks). Audit assumes positioning and audience are known; the work is assessing what to keep, drop, or refresh. +- **Single landing page.** 1 to 2 weeks across 3 phases: Brief (2 to 3 days), Production (5 to 7 days), QA-Launch (1 to 2 days). Identity is assumed locked. Voice is assumed locked. The work is page-specific copy, design, and engineering. +- **Campaign.** 2 to 4 weeks across 4 phases: Brief (3 to 5 days), Production (1 to 2 weeks), QA (3 to 5 days), Launch (1 to 2 days). Campaign assumes brand identity and voice exist and are locked. +- **Identity refresh.** 3 to 4 weeks across 3 phases: Audit (1 week), Identity (1 to 2 weeks), Production (1 week). Skips discovery and positioning. The output is a refreshed identity system that goes into production for application examples. +- **Website refresh.** 4 to 8 weeks across 4 phases: Audit (1 week), Direction (1 week), Production (2 to 4 weeks), QA-Launch (1 to 2 weeks). Direction may produce a refreshed brief if the audit surfaces positioning gaps. +- **Microsite or product launch.** 3 to 5 weeks across 4 phases: Brief (3 to 5 days), Production (2 to 3 weeks), QA (3 to 5 days), Launch (2 to 3 days). The microsite or product launch usually has a fixed launch date that drives backward planning. + +Each cadence reads as if the PM could paste it into a calendar and start running. Phase boundaries align with calendar weeks where possible, because that is how teams actually plan. + +--- + +## Failure patterns + +The orchestration plan exists to prevent these. Each is a real failure mode, observed in the wild on real projects. + +- **Brief becomes a write-once doc.** The brief is drafted, signed, then nobody references it again. Downstream work drifts. The fix: lock the brief at a gate and treat any reference to it as a reading, not an edit. +- **Brief gets unfrozen mid-flight without re-reviewing dependent work.** Someone tweaks the brief's audience or positioning; the change does not propagate to identity, voice, or copy that already depend on the old version. The fix: a formal change-request protocol that triggers re-review of dependent artifacts. +- **Identity locks before voice.** The typography is finalized before the voice is approved. Result: the type and the voice register conflict (a friendly voice in austere type, or a serious voice in casual type). The fix: voice approval gate fires before or alongside identity lock. +- **Copy starts before voice locks.** Writers draft against a moving target. Rework is invisible because the original draft never gets compared against the locked voice. The fix: voice approval before copy production. +- **Multiple parallel design tracks lose brief alignment.** Track A and Track B both interpret the brief slightly differently; by week 3 the two tracks read as different brands. The fix: cross-track sync ceremonies and a brief-owner role. +- **Engineering starts before design freeze.** Components get built against design that is still moving. Rework downstream when design lands somewhere else. The fix: design approval gate before engineering starts on the affected surface. +- **Reviews stack at end of phase.** Everyone defers their review to the final day; the gate becomes a 10-hour review marathon and approvers approve under fatigue. The fix: within-phase mini-gates that flatten review demand. +- **Async handoffs without artifact specification.** "Hand the design over to engineering" without specifying what artifacts (Figma file URL, exported tokens, asset library reference, PR draft template) means engineering opens half a dozen Slack threads to find what they need. The fix: explicit artifact specification per handoff. +- **QA gate is self-reported.** "Done" tickets get moved to Done without verification. Bugs land in production. The fix: automated verification that fires before status transitions to Done; failure routes to Blocked. +- **Agents spin on un-resolvable work.** A Claude Code task cannot resolve itself; the agent retries, burns context, runs out of tokens, leaves the work in a worse state than when it started. The fix: Blocked is a first-class status; agents move tasks to Blocked when they cannot autonomously resolve, document the blocker, and stop. + +--- + +## Output format + +Default output is a markdown document, typically saved as `ORCHESTRATION.md` at the project root or in a `docs/` subdirectory. The document contains the full plan and is the canonical reference for the team. + +Structure: + +1. **Project orchestration plan.** Phased timeline with calendar weeks, milestone dates, phase outputs. +2. **Per-phase gate specs.** What enters, what exits, who approves, the measurable pass criteria for each gate including the QA verification gate. +3. **Lock-point register.** What becomes immutable when, where the locked artifact lives, who can request a change, and what re-review work a change triggers. +4. **Tool-stack implementation guide.** Concrete setup for Jira, Linear, Notion, Figma, and GitHub as applicable, with MCP commands or CLI invocations for the parts that automate. +5. **QA verification gate spec.** Which automated tests must pass, which MCPs run them, where evidence attaches, what happens on failure. +6. **Handoff specs.** Artifacts transferred per handoff, locked items, change-request protocols, adjacent-observation routing. +7. **Cross-skill dependency graph.** Which skills run in which phase, what each skill consumes, what each produces. +8. **Risk register.** Cadence-specific risks with mitigations. + +The document is the orchestration plan. The next step after delivery is for the PM to set up the team's tools to match (Jira epics, Linear projects, Notion databases, Figma libraries, GitHub branch protection) and start running the plan. + +--- + +## Reference files + +- [`references/cadence-patterns.md`](references/cadence-patterns.md). The 7 project-type cadences in detail with phase decomposition, timelines, gate definitions, and tool-stack implementation skeletons. +- [`references/gate-definitions.md`](references/gate-definitions.md). Each standard gate with trigger, approver, pass criteria, what's blocked, what's already locked, and change-request protocols. +- [`references/handoff-protocols.md`](references/handoff-protocols.md). The standard handoffs between phases and skills, plus the adjacent observation handoff for filing things noticed while working nearby. +- [`references/platform-implementation.md`](references/platform-implementation.md). How the orchestration maps to Jira, Linear, Notion, Figma, and GitHub, including MCP integration notes per platform and CLI alternatives where MCP is the wrong tool. +- [`references/team-size-modulation.md`](references/team-size-modulation.md). How cadences scale across solo, small, medium, and large teams. +- [`references/automation-and-qa-tooling.md`](references/automation-and-qa-tooling.md). The QA verification gate pattern, MCP vs CLI tradeoffs, session memory and momentum patterns, code-to-ticket linkage, and evidence trails. +- [`references/example-orchestration.md`](references/example-orchestration.md). A complete worked example showing all sections populated for a representative scenario. diff --git a/skills/integration-orchestrator/references/automation-and-qa-tooling.md b/skills/integration-orchestrator/references/automation-and-qa-tooling.md new file mode 100644 index 0000000..d1649a5 --- /dev/null +++ b/skills/integration-orchestrator/references/automation-and-qa-tooling.md @@ -0,0 +1,167 @@ +# Automation and QA tooling + +The QA verification gate, MCP vs CLI tradeoffs at the strategic level, session memory and momentum patterns, code-to-ticket linkage, evidence trails, and failure routing. This file pairs with platform-implementation.md (which covers per-platform specifics) but stays at strategic-pattern level. + +--- + +## Section 1: The QA verification gate + +The single most important pattern in this reference file. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The orchestration plan specifies, per project type: + +- **Which automated tests must pass.** Defined in writing as part of the orchestration plan output. Different project types have different test suites. + - **Web project.** Playwright critical-flow tests covering signup, checkout, contact form, navigation, and any other paths that move money or capture data. Visual regression on key pages (homepage, pricing, top-traffic landing pages). Console error count not exceeding baseline (specify baseline as 0 errors at hero load and during critical flows). Accessibility floor (WCAG AA contrast, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled). Performance budgets (Lighthouse mobile and desktop scores at or above project target, Core Web Vitals at or above project target). + - **Microsite or landing page.** Subset of the above scoped to the page; performance budgets often tighter. + - **Campaign.** Cross-deliverable consistency check (do all assets reference the same brand identity? do all touchpoints use the locked voice?) plus per-deliverable QA. + - **Identity refresh.** Visual regression on the design library plus an audit of downstream files using deprecated components. + +- **Which MCPs run them.** + - **Playwright MCP** for browser-driven user-flow tests. The agent invokes the test suite, captures pass/fail per test, and attaches results to the ticket. + - **Claude in Chrome / Chrome MCP** for human-readable QA flows with screenshot or GIF evidence trails. Useful when the test isn't a deterministic pass/fail (e.g., "does the checkout flow feel right?" requires a human-readable record). Chrome MCP captures the agent's walkthrough as a GIF or screenshot sequence. + - **Windows MCP** for desktop applications. Covers Windows-specific testing scenarios when the project is desktop-app-shaped. + - **Mobile testing MCPs** (Detox-based, Appium variants) for mobile apps when applicable. + +- **What gets verified in a typical web QA pass.** + - Critical user-flow tests (signup, checkout, contact form submission, search if applicable). + - Visual regression on key pages (typically 5-10 pages flagged as critical). + - Console error count not exceeding baseline. + - Accessibility floor (WCAG AA contrast, keyboard navigation, screen reader landmarks). + - Performance budgets (Lighthouse, Core Web Vitals). + +- **Where the evidence attaches.** + - Linked to the ticket as a comment with screenshot or GIF. + - Optionally stored in a `.evidence/` folder in the repo (engineering projects) or a designated cloud bucket (S3, GCS). + +- **What happens on failure.** + - Status moves to Blocked (not back to In Progress). + - The blocker reason is documented in the ticket comment. + - If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. + - The human is paged via the configured channel. + - The agent does NOT keep retrying autonomously; it documents the state and waits. + +--- + +## Section 2: MCP vs CLI tradeoffs at the strategic level + +The platform-implementation reference covers per-platform specifics. This section is the strategic frame for choosing between MCP and CLI as the orchestration's primary interface. + +### MCP excels at + +- Small reads and writes (single ticket update, single comment posting, single page edit). +- Real-time data (current status of a project, current PRs awaiting review). +- API-shaped operations that map cleanly to JSON-in / JSON-out. +- Agent-friendly contracts (structured tool calls with typed responses). +- Navigation queries ("show me all open tickets in this project", "find the PR that touches this file"). +- Status reads (what's the current gate state, what's locked). + +### CLI excels at + +- Bulk content updates (large Confluence pages, multi-page Notion exports, repo-wide search-and-replace). +- File-tree-aware operations (operating on multiple files in a repo, generating a directory of artifacts). +- Git-like workflows (the gh CLI's strengths around branches, PRs, releases). +- Lower token cost on heavy operations. MCP roundtrips become expensive at scale; CLI runs locally with no token cost per operation. +- Scripted automation (CI workflows, deploy pipelines, scheduled jobs). + +### Decision pattern + +- **For setup and orchestration.** Prefer MCP. PM-friendly, declarative, easy to inspect. The agent can explain what it did via tool-call traces. +- **For bulk operations.** Prefer CLI. More efficient, lower token cost, better formatting preservation. +- **For QA verification.** Playwright CLI when the same test runs repeatedly (CI integration, pre-commit hooks). Playwright MCP when verification is ad-hoc and needs to interact with surrounding context (the agent reading a Linear ticket, then running specific tests against the deployed staging site). + +### Hybrid pattern + +Most production setups use both. MCP for the orchestration plan's setup operations and ongoing navigation; CLI for ongoing bulk work, CI integration, and operations the MCP can't handle efficiently. The orchestration plan specifies which interface fires when. + +--- + +## Section 3: Session memory and momentum + +The agent-starts-from-zero problem. Each new Claude Code session re-reads files, re-discovers decisions, re-learns the same gotchas. MCP gives the task list; it doesn't give working momentum. + +Patterns to bridge the gap: + +### Project state file + +Committed alongside code. Typical paths: `CLAUDE.md`, `AGENTS.md`, `.agent/state.md`. Contents: + +- **Last completed task** with brief outcome notes ("RAMP-123: homepage hero rewrite. Shipped in PR #456. Worth noting: the existing copy was longer than the new copy, so the design has extra whitespace below the hero now. May need design follow-up."). +- **Current task in progress** with current status ("RAMP-124: pricing page CTA test. In Progress. Blocking on getting the test variant ID from Mira."). +- **Open decisions awaiting human input** ("Should we use the new monogram on the favicon, or keep the existing letterform-as-symbol? Pending design lead review."). +- **Known gotchas the agent should avoid re-discovering** ("The CMS export step takes 8 minutes. Don't kick it off until you're ready to wait. The export contains stale image references; replace with current image URLs from the asset library before publishing."). +- **Convention reminders specific to the project** ("Branch names use uppercase ticket prefix: feat/RAMP-123-slug. PR descriptions include 'Closes RAMP-123'. Squash merge only."). + +### Per-task observation trail + +After completing each task, the agent records observations: + +- **What was unexpected** ("The CMS API returned a 429 on the first attempt; had to wait 60 seconds before retry succeeded."). +- **What broke before it worked** ("Initial regex for the slug pattern matched too broadly; tightened to require dash separators."). +- **What workaround was found** ("The token export script doesn't handle nested groups in Figma; flattened the groups manually before export."). +- **What pattern might generalize** ("All API endpoints return null when the resource doesn't exist, not 404. Worth refactoring the error handling to assume null rather than 404."). + +### Trail-as-next-task generation + +When N observations accumulate (typically 5 to 10), hand them back as the brief for the next iteration: "here are 10 observations from this week, turn them into improvements." Keeps the agent's capability pointed at code quality and process refinement, not just task completion. + +The orchestrator skill's output bakes these mechanisms into the plan: specifies which state file to use, what content goes in it, when observations get reviewed by the human (typically weekly grooming), how the observation trail informs next-cycle planning. + +--- + +## Section 4: Code-to-ticket linkage + +Standard but worth specifying so the orchestration plan can call out exactly which conventions the team uses. + +- **Branch naming.** `{type}/{ticket-id}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform. +- **PR descriptions.** Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- **Commit messages.** Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. +- **CODEOWNERS.** When set up, PR review routing happens automatically and the orchestration plan's review-by assignments align with platform-native routing. + +The orchestration plan specifies the convention per platform combination (Jira+GitHub uses RAMP-123 prefix style; Linear+GitHub uses LIN-456 or the team's chosen prefix). Without that specification, branch names drift across team members and the auto-linking breaks. + +--- + +## Section 5: Evidence trails and recording + +Some pattern, some practical advice. + +### Recording tools + +- **Claude in Chrome auto-records GIFs** of QA flows. Useful for evidence attached to tickets. Limitations: GIF format is large and not video-quality; for longer flows, prefer MP4 or WebP if the recording tool supports it. +- **Screenshot evidence** is sufficient for most ticket-level QA artifacts. Tools like Playwright auto-capture on test failure; Chrome MCP can take ad-hoc screenshots during human-readable QA. +- **Loom or similar** for human-narrated walkthroughs when the audience needs context (client review of the staging site, stakeholder review of a complex flow). + +### Where evidence lives + +Three options, each with tradeoffs: + +- **Attached directly to the ticket as a comment.** Most discoverable but bloats the ticket. Best for evidence that pairs tightly with a specific ticket. +- **In a designated cloud bucket** (S3, GCS) with a link in the ticket. Ticket stays clean, evidence has a stable URL. Best for projects with high evidence volume. +- **In a `.evidence/` folder in the repo.** Works for engineering-heavy projects but cumbersome for design or copy work. Pairs well with the project state file pattern; evidence and state co-locate. + +### Retention + +Most projects don't need permanent evidence retention beyond the ticket. Specify a retention policy in the orchestration plan: + +- 30 days for QA evidence (passing tests don't need long retention). +- 90 days for bug-related evidence (bug reproduction often resurfaces within 90 days). +- Indefinite for design final approvals (the audit trail matters for years). + +--- + +## Section 6: Failure routing + +When automated verification fails OR an agent hits something it cannot autonomously resolve, the failure follows a defined routing. + +1. **Status moves to Blocked.** Not back to In Progress, not to Waiting. Blocked is a first-class status that means "human action required to unblock". +2. **The blocker reason is documented** in the ticket comment with specifics: which test failed, which file was the locus, which assertion didn't pass, what the agent already tried. +3. **If the failure surfaced something unrelated to the current task,** an adjacent observation gets filed in the project triage queue. +4. **The human is paged via the configured channel.** + - Slack (preferred for in-team work, fastest response). + - Email (for cross-team or external-stakeholder blockers). + - Linear or Jira mention (for in-tool routing when the team prefers a single channel). +5. **The agent does NOT continue retrying.** It documents the state and waits. Retrying is the path that turns a single failure into a context-burning loop. + +This routing is itself part of the orchestration plan output: the skill specifies which channels are configured, who's on the escalation tree, and what response time is expected per blocker severity (typically: P0 blockers paged immediately; P1 paged within a working hour; P2 surfaced at next standup; P3 added to the triage queue without a page). + +The discipline of Blocked-as-first-class-status is what makes agent participation safe at scale. Without it, agents either burn context retrying or silently abandon work; with it, the agent has a clear "I'm stuck" signal that keeps the work visible to the human team. diff --git a/skills/integration-orchestrator/references/cadence-patterns.md b/skills/integration-orchestrator/references/cadence-patterns.md new file mode 100644 index 0000000..e21adb9 --- /dev/null +++ b/skills/integration-orchestrator/references/cadence-patterns.md @@ -0,0 +1,245 @@ +# Cadence patterns + +The 7 project-type cadences in working detail. Each cadence covers phase decomposition, calendar timelines, gate definitions, lock-point map, and tool-stack implementation skeleton. + +## The 5-status taxonomy + +Every cadence in this file uses the same 5-status taxonomy: + +- **Todo.** Work scoped, not yet started. +- **In Progress.** Work being actively done. +- **Waiting.** Work paused for normal handoff or scheduled review. Examples: a ticket waiting for the next standup, a PR waiting for its assigned reviewer, a design awaiting client review at the next scheduled session. +- **Blocked.** Work cannot proceed without human resolution of a specific issue. Distinct from Waiting. An agent moves a task to Blocked when it cannot autonomously resolve and documents the blocker. The agent then stops; it does not retry. +- **Done.** Work complete AND verified. The QA verification gate must pass before transition to Done. Self-reported "I think this works" does not transition to Done; the automated test gate (or, in non-engineering contexts, the explicit reviewer signoff) does. + +Status transitions are restricted at the gate level. The QA gate prevents transition to Done. The approval gates prevent forward progress until the gate passes. Blocked tickets generate a paging signal to the configured channel. + +--- + +## 1. New brand build (6 to 8 weeks) + +The full lifecycle. Greenfield brand or a brand whose existing assets are being replaced wholesale. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Discovery | 1 week | Audience, positioning, competitive landscape, references | +| Direction | 1 week | Creative direction brief (axes locked) | +| Identity | 1 to 2 weeks | Logo system, color, typography, imagery direction, motion | +| Production | 2 to 3 weeks | Voice guide, copy, design system, page builds | +| Launch | 1 week | QA, soft launch, full launch | + +### Gates + +- **End of Discovery.** Brief approval. Required: client signed brief artifact (in writing or recorded review). +- **End of Direction.** Direction approval. Required: axis positions locked, references curated. +- **End of Identity.** Identity approval. Required: logo system, color tokens, typography, imagery direction documented. +- **Mid-Production.** Voice approval. Required: voice guide signed. +- **End of Production.** Copy approval and design approval. Required: per-page copy and design signed. +- **Pre-Launch.** QA verification. Required: Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained. +- **Launch readiness.** Final go/no-go. Required: deployment checklist complete, rollback plan documented. + +### Lock points + +Brief locks at end of Direction. Identity tokens lock at end of Identity. Voice locks mid-Production. Copy locks per page at end of Production. Design tokens lock with identity; design final lock at end of Production. + +### Tool-stack implementation + +- **Jira:** 1 Epic per phase, Stories per work item, custom fields for Phase / Locked / Approver / Gate Status. Workflow scheme with the 5-status taxonomy. +- **Linear:** 1 Project per phase, Cycles per week, Labels per skill (`brand-identity`, `brand-voice`, `landing-page-copy`, etc.). +- **Notion:** Brief database with one row, related databases for direction docs, identity specs, voice guides, copy decks. Phase dashboard views. +- **Figma:** Library structure: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status. +- **GitHub:** Branch protection on `main`. PRs from `phase/{phase-name}/*` branches. + +### Example ticket titles + +- Discovery: "Audience: 5 archetypes interviewed", "Positioning: locate the brand against 3 competitors" +- Direction: "Direction: confirm tone-axis position", "Direction: rejection list signed off" +- Identity: "Identity: logo lockup variants for review", "Identity: color tokens locked" +- Production: "Voice guide: tone-shift table approved", "Copy: homepage hero v3 reviewed" +- Launch: "QA: Playwright critical flow regression green", "Launch: deploy to production" + +--- + +## 2. Rebrand (4 to 6 weeks) + +Existing brand. Audience and positioning known. Audit replaces discovery. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | What to keep, drop, refresh; positioning gaps | +| Direction | 1 week | Creative direction brief | +| Identity | 1 to 2 weeks | Refreshed logo, color, type, imagery | +| Production | 1 to 2 weeks | Updated voice guide, copy, design library, page builds | + +### Gates + +Audit approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, launch readiness. Same gates as new brand build minus the Launch phase (rebrand often launches with the production push rather than a separate phase). + +### Lock points + +Audit findings lock at end of Audit (decisions about what to keep stay in scope; revisiting requires change request). All other lock points match new brand build. + +### Tool-stack implementation + +Same as new brand build. The Audit phase typically uses a Notion database with rows for "Existing asset / Decision (keep/drop/refresh)/Owner / Status". + +--- + +## 3. Single landing page (1 to 2 weeks) + +The brand identity and voice are locked. The work is page-specific copy, design, and engineering. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 2 to 3 days | Page brief, success criteria | +| Production | 5 to 7 days | Copy, design, build | +| QA-Launch | 1 to 2 days | QA, deploy | + +### Gates + +- **End of Brief.** Page brief approval. Required: success metric defined. +- **Mid-Production.** Copy approval. Required: signed against existing voice guide. +- **End of Production.** Design approval and engineering review. Required: design final, build complete. +- **End of QA-Launch.** QA verification and launch readiness combined. Required: Playwright run green, console errors at baseline, deploy executed. + +### Lock points + +Page brief locks at end of Brief. Copy locks mid-Production. Design tokens are inherited from the brand identity (already locked). Design final locks at end of Production. + +### Tool-stack implementation + +- **Jira / Linear:** Single Epic for the page, 5 to 8 Stories. +- **Notion:** Single brief row, one direction artifact (the page brief). +- **Figma:** Working file referencing the brand library; one set of frames. +- **GitHub:** Single feature branch, PR template, branch protection on `main`. + +--- + +## 4. Campaign (2 to 4 weeks) + +Brand identity and voice locked. Multiple deliverables under one campaign theme. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 3 to 5 days | Campaign brief, deliverable list | +| Production | 1 to 2 weeks | Per-deliverable copy, design, build | +| QA | 3 to 5 days | Cross-deliverable QA | +| Launch | 1 to 2 days | Coordinated launch | + +### Gates + +Campaign brief approval, per-deliverable copy approval, per-deliverable design approval, cross-deliverable QA verification, launch readiness. + +### Lock points + +Campaign brief locks at end of Brief. Per-deliverable copy locks at copy approval. Per-deliverable design locks at design approval. Cross-deliverable consistency checked at QA gate (a single change request on the campaign brief triggers re-review across all deliverables). + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic for campaign, 1 Story per deliverable plus per-deliverable subtasks. +- **Notion:** Campaign brief row plus deliverable rows in a related database. +- **Figma:** Library file plus one frame per deliverable. +- **GitHub:** Multiple feature branches off a campaign branch, single PR per deliverable. + +--- + +## 5. Identity refresh (3 to 4 weeks) + +Existing brand. Voice and positioning stay. Identity gets refreshed. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | What stays, what changes | +| Identity | 1 to 2 weeks | Refreshed logo, color, type, imagery | +| Production | 1 week | Application examples (web, signage, social) | + +### Gates + +Audit approval, identity approval, production review. Voice and copy gates skipped (voice stays locked; copy gets light updates if any). + +### Lock points + +Audit findings lock at end of Audit. Identity tokens lock at end of Identity. Application examples lock at end of Production but tokens remain canonical. + +### Tool-stack implementation + +- **Figma:** Refresh of existing library; new component versions; old components deprecated rather than deleted (downstream files still reference them). +- **Notion:** Identity spec row with relations to before/after asset databases. +- **Jira / Linear:** Smaller scope than rebrand; 1 Epic, 8 to 15 Stories. +- **GitHub:** Library updates land via versioned PR; downstream consumers update on their own cadence. + +--- + +## 6. Website refresh (4 to 8 weeks) + +Existing site. Either a partial refresh (specific sections) or a full overhaul. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Audit | 1 week | Current site assessment, gaps, priorities | +| Direction | 1 week | Refreshed brief if positioning has shifted | +| Production | 2 to 4 weeks | Voice updates, copy, design, build | +| QA-Launch | 1 to 2 weeks | Cross-page QA, soft launch, full launch | + +### Gates + +Audit approval, direction approval (if direction phase happens; some refreshes skip), per-section copy approval, per-section design approval, QA verification, launch readiness. + +### Lock points + +Audit findings lock at end of Audit. Direction (if produced) locks at end of Direction. Per-section copy locks at copy approval per section. Design tokens lock with the design library; design final per section locks at design approval. + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic per phase, sub-Epics per section if the site is large. +- **Notion:** Brief plus per-section page in a database. +- **Figma:** Library refresh plus per-section design files. +- **GitHub:** Per-section feature branches, branch protection, CI gates per section. + +--- + +## 7. Microsite or product launch (3 to 5 weeks) + +Fixed launch date. Plan backward from the launch. + +### Phase decomposition + +| Phase | Duration | Output | +|---|---|---| +| Brief | 3 to 5 days | Launch brief, microsite scope | +| Production | 2 to 3 weeks | Copy, design, build, integrations | +| QA | 3 to 5 days | Cross-flow QA | +| Launch | 2 to 3 days | Coordinated launch sequence | + +### Gates + +Launch brief approval, copy approval, design approval, QA verification, launch readiness. + +### Lock points + +Launch brief locks at end of Brief. Copy locks at copy approval. Design locks at design approval. The launch date is the hardest lock; if QA fails, the launch slips rather than launching with bugs. + +### Tool-stack implementation + +- **Jira / Linear:** 1 Epic, multiple Stories per surface (microsite, supporting pages, integrations). +- **Notion:** Launch brief plus dependency table (assets, integrations, third parties). +- **Figma:** Microsite design file referencing brand library. +- **GitHub:** Microsite feature branch plus per-surface sub-branches; branch protection plus pre-launch CI gate. + +--- + +## How to use this file + +Pick the cadence whose project type matches yours. Follow the phase decomposition for your team size (use the team-size-modulation reference for adjustments). Implement in your tool stack using the platform-implementation reference for per-platform setup. Configure the QA verification gate using the automation-and-qa-tooling reference. The pieces compose; this file is the cadence skeleton. diff --git a/skills/integration-orchestrator/references/example-orchestration.md b/skills/integration-orchestrator/references/example-orchestration.md new file mode 100644 index 0000000..c481fb5 --- /dev/null +++ b/skills/integration-orchestrator/references/example-orchestration.md @@ -0,0 +1,267 @@ +# Example orchestration + +A complete worked example showing all sections of the orchestration plan populated for a representative scenario. The PM should be able to read this Monday morning and start setting up tools Tuesday. + +## Scenario + +A 4-person team is doing a rebrand for a 15-year-old hospitality brand. The existing brand has a loyal customer base and recognizable identity assets, but the visual register has aged poorly and the digital surfaces haven't been updated since 2019. + +- **Team.** PM (Mira), design lead (Karim), copy lead (Jess), senior engineer (Dax). +- **Timeline.** 6 weeks. +- **Tool stack.** Jira (existing, the team's main work tracker) + Figma + GitHub. Notion is not used by this team. Slack for communication. Loom for client review walkthroughs. +- **AI agent participation.** Claude Code participates in production phase tasks (component library updates, page builds). Claude in Chrome runs QA gates on the staging deployment. Agents have access to the Atlassian MCP and GitHub MCP. Agents move tickets between Todo, In Progress, Waiting, and Blocked but do NOT move to Done; Done requires human verification. +- **Client.** Hospitality brand owner is non-technical. Reviews happen via Loom-recorded walkthroughs scheduled at end of each phase. + +--- + +## 1. Project orchestration plan + +### Phased timeline + +- **Week 1 (Audit).** Existing brand assessment. Audience already known; the audit assesses what to keep, drop, refresh. Output: audit findings document. +- **Week 2 (Direction).** Refreshed creative direction brief. Tone, aesthetic, relationship, sensory positions confirmed. Output: direction artifact. +- **Weeks 3-4 (Identity).** Refreshed logo lockup, color tokens, typography selections, imagery direction. Output: locked identity tokens published to Figma library, identity spec document. +- **Weeks 5-6 (Production).** Voice guide refresh, copy update for top 8 pages, design final per page, engineering implementation, QA verification, launch. + +### Calendar boundaries + +Week 1: Mon-Fri Audit, Friday phase review with brand owner via Loom walkthrough. +Week 2: Mon-Fri Direction, Friday phase review. +Weeks 3-4: Mon-Fri Identity, mid-Week 4 voice approval gate, Friday Week 4 identity approval gate plus Loom walkthrough. +Weeks 5-6: Mon-Tue Week 5 copy approval per page, Wed-Fri Week 5 design final per page (rolling), Mon-Wed Week 6 engineering implementation (rolling), Thu Week 6 QA verification, Fri Week 6 launch. + +--- + +## 2. Per-phase gate specs + +### Audit approval gate (end of Week 1) + +- **Trigger.** All Audit tasks transitioned to Done. Audit findings document complete. +- **Approver.** Brand owner (via Loom walkthrough plus email signoff). Mira reviews internally first. +- **Required to pass.** Audit findings document complete (existing assets categorized as keep / drop / refresh, gaps identified). Brand owner signed off in writing. +- **Blocks until passed.** Direction phase work. + +### Direction approval gate (end of Week 2) + +- **Trigger.** Tone, aesthetic, relationship, sensory positions selected. References curated. Rejection list documented. +- **Approver.** Brand owner plus Karim (design lead). +- **Required to pass.** All four axis positions confirmed in writing. Reference brand list documented. Rejection list signed off. +- **Blocks until passed.** Identity phase production work. + +### Voice approval gate (mid Week 4) + +- **Trigger.** Refreshed voice guide drafted by Jess against locked direction. +- **Approver.** Brand owner plus Jess (copy lead). +- **Required to pass.** Voice guide complete (attributes, tone shifts, vocabulary, paired examples). At least 3 paired examples per major content type. +- **Blocks until passed.** Copy production for shipping pages. + +### Identity approval gate (end of Week 4) + +- **Trigger.** Refreshed logo, color tokens, typography, imagery direction documented and rendered. +- **Approver.** Brand owner plus Karim. +- **Required to pass.** Logo lockup variants reviewed. Selected variants documented. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented. +- **Blocks until passed.** Design production at scale. + +### Copy approval gate (per page, Week 5) + +- **Trigger.** Per-page copy drafted against locked voice guide. +- **Approver.** Brand owner (via Loom walkthrough for top 3 pages; email approval for the other 5) plus Jess. +- **Required to pass.** Copy matches voice guide. Calls-to-action consistent with success criteria. +- **Blocks until passed.** Design final for that page. + +### Design approval gate (per page, Week 5-6) + +- **Trigger.** Design final rendered against locked copy and locked identity tokens. +- **Approver.** Karim plus Mira. +- **Required to pass.** Design references locked identity tokens. Copy reflected exactly as approved. Responsive states designed. Empty/loading/error states accounted for. +- **Blocks until passed.** Engineering of that page. + +### QA verification gate (Thu Week 6) + +- **Trigger.** Engineering signaled complete; ticket transitioned to QA status. +- **Approver.** Automated test suite (Playwright via MCP) plus Claude in Chrome walkthrough; human review on test failure. +- **Required to pass.** Playwright critical-flow suite green. Console error count at 0 for hero load and during critical flows. Accessibility floor maintained (WCAG AA contrast, keyboard navigation, screen reader landmarks). Lighthouse mobile score at or above 85, desktop at or above 95. Visual regression on top 8 pages within tolerance. +- **Blocks until passed.** Status transition to Done. Launch readiness for the affected page. + +### Launch readiness gate (Fri Week 6) + +- **Trigger.** All 8 affected pages have passed QA verification. +- **Approver.** Mira (project owner) plus Dax (launch coordinator). +- **Required to pass.** Deployment checklist complete. Rollback plan documented. On-call coverage assigned for the launch window. Brand owner notified. + +--- + +## 3. Lock-point map + +- **Audit findings lock at end of Week 1.** Existing-asset decisions cannot be revisited without change request triggering re-review of Direction work. +- **Direction locks at end of Week 2.** Axis positions cannot be revisited without change request triggering re-review of Identity, Voice, and Copy work. +- **Identity tokens lock at end of Week 4.** Color tokens, typography selections, logo lockup committed to Figma library v2.0. Downstream design and engineering work references the locked library version. +- **Voice rules lock mid Week 4.** Voice guide v2.0 committed to canonical Confluence page. Downstream copy production references the locked voice guide. +- **Per-page copy locks at copy approval gate (Week 5).** Each page's copy locks individually as it passes its approval gate; design final for that page can begin. +- **Per-page design locks at design approval gate (Week 5-6).** Each page's design locks individually; engineering for that page can begin. +- **Code merges to main (Week 5-6, rolling).** Branch protection prevents direct pushes; PRs merge after CODEOWNERS review and CI gates pass. + +--- + +## 4. Handoff specs + +- **Audit to Direction (Friday Week 1).** Audit findings document URL, summary of gaps and opportunities. Filed in Jira as a Confluence page link in the Direction phase Epic description. +- **Direction to Identity (Friday Week 2).** Direction artifact URL, axis positions documented, reference brand list, rejection list. Filed in Jira as Confluence page links in the Identity phase Epic description. +- **Direction to Voice (Friday Week 2, parallel to Direction-to-Identity).** Same artifacts; Voice phase work begins in parallel with Identity. +- **Identity plus Voice to Copy (Mid-Week 5).** Locked identity tokens (Figma library v2.0 URL), locked voice guide (Confluence URL), per-page scope (Jira tickets). Filed in Jira as Story descriptions per page. +- **Identity plus Copy to Design (Per page, Week 5).** Locked copy (Confluence URL with "approved" marker), locked identity tokens (Figma library v2.0 URL). Filed in Jira as the design-phase Story description per page. +- **Design to Engineering (Per page, Week 5-6).** Final design (Figma frame URL), exported asset library (cloud bucket URL), responsive notes (Figma annotations), motion specifications. Filed in Jira as the engineering-phase Story description per page. +- **Engineering to QA (Per page, Week 6).** Verified deployed-to-staging surface, QA evidence (Playwright run results URL, accessibility audit URL), deployment checklist URL. + +### Adjacent observation routing + +The team's triage queue is a Jira project labeled "Project triage". Filed observations route there without an assignee. Mira triages every Monday and Thursday at standup. Observation content includes: what was observed, why it might matter, link to the work that was happening when noticed, suggested triage priority. The agent uses the Atlassian MCP to file observations. + +--- + +## 5. Tool-stack implementation + +### Jira + +Issue type scheme: +- **Epic:** one per phase (Audit, Direction, Identity, Production-Voice, Production-Copy, Production-Design, Production-Engineering, Production-QA, Launch). +- **Story:** one per work item within a phase. +- **Task:** subtasks under stories. +- **Bug:** for issues filed during QA. + +Custom fields: +- Phase (single-select with the 8 phase names). +- Locked (checkbox). +- Approver (user picker). +- Gate Status (single-select with the 8 standard gates). + +Workflow scheme: 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) with workflow validators preventing premature transitions to Done without QA verification. + +Confluence space: +- Brief page (rebrand brief). +- Direction page (creative direction artifact). +- Audit findings page. +- Identity spec page (logo, color, typography, imagery). +- Voice guide page. +- Copy doc per page (top 8 pages). +- Orchestration plan page (this document, committed to the project space). + +MCP setup: +- Atlassian MCP configured with OAuth credentials (admin one-time setup). +- Initial Epic creation: 8 epics, one per phase, populated by the agent on Day 1. +- Initial Story creation per phase: agent populates from the orchestration plan. + +### Figma + +Library file structure: +- "Tokens" page: color, typography, spacing, motion. +- "Components" page: identity components (logo, badges, branded UI elements). +- "Patterns" page: page-level patterns (hero variants, card patterns, footer). +- "Page templates" page: top 8 page templates for the rebrand. +- "Working files" page: per-page design working files. + +Library publish discipline: +- v1.0 published at start of Week 3 (existing identity, used as baseline). +- v2.0 published at end of Week 4 (refreshed identity, locks at identity gate). +- Per-page working files reference v2.0 starting Week 5. + +### GitHub + +Repository: existing repo for the brand's website. + +Branch protection on main: +- Require PR reviews (1 reviewer minimum). +- Require status checks (lint, type-check, build, accessibility audit, Playwright run). +- Require linear history (squash merges only). + +CODEOWNERS: +- Frontend code: Dax. +- Design tokens: Karim. +- Copy markdown: Jess. + +PR template: +- Ticket reference (Closes RAMP-XXX or Refs RAMP-XXX). +- Summary. +- Test plan. +- Screenshots/GIFs for UI changes. +- QA evidence URL. + +GitHub MCP setup: +- GitHub MCP configured with the repo's PAT. +- Initial PR template committed via MCP. +- CODEOWNERS file committed via MCP. + +--- + +## 6. Automation and QA verification + +### Playwright test suite spec + +Critical flows to test: +- Homepage hero loads and renders. +- Reservation flow (the brand's primary conversion path) end-to-end through booking confirmation. +- Contact form submission (validation, submission, success state). +- Newsletter signup. +- Top-traffic landing pages render without console errors. + +Visual regression on top 8 pages: +- Homepage, About, Reservations, Locations, Menu, Press, Contact, Loyalty. + +Accessibility audit per page using axe-core or equivalent: +- WCAG AA contrast. +- Keyboard navigation reaching all interactive elements. +- Screen reader landmarks present and labeled. + +### Chrome MCP walkthrough scenarios + +For Loom-recorded brand owner reviews and ad-hoc human-readable QA: +- Reservation flow walkthrough with screenshots at each step. +- Brand consistency walkthrough (top 8 pages, evaluating typography and color consistency). +- Mobile responsive walkthrough (the brand's audience is heavily mobile). + +### Evidence trail policy + +- QA evidence (test results, screenshots, GIFs) attached to each ticket as comments. +- 90-day retention for engineering-related evidence. +- Indefinite retention for design final approvals (committed to Confluence with the design spec page). + +### Failure routing + +- Slack channel #project-rebrand-launch is the team's coordination channel. Blockers page Mira via Slack mention. +- P0 blockers (broken reservation flow): page Dax immediately via direct Slack mention. +- P1 blockers (broken page render): surface at next standup. +- P2-P3 blockers: file as adjacent observation in the triage queue. + +--- + +## 7. Risk register + +Cadence-specific risks and mitigations. + +### Risk 1: Brand owner availability for Loom reviews + +The brand owner is busy and may delay phase reviews, slipping the timeline. Mitigation: Mira schedules Loom reviews 1 week in advance with calendar holds. Backup reviewer for direction approval gate is the head of marketing on the brand owner's team (Mira identified this person at project kickoff). + +### Risk 2: Identity refresh expectations vs reality + +The brand owner may expect a more dramatic refresh than the audit recommends, OR may reject the refresh as too dramatic. Mitigation: Karim shares 3 directional moodboards at end of Week 1 to align expectations BEFORE Direction phase locks in. The moodboards are not the final identity; they're directional samples to confirm the team and the brand owner are pointing in the same direction. + +### Risk 3: Engineering surface area + +The website has 8 pages but also a custom CMS, a reservation integration, and an email pipeline. The 6-week timeline assumes only the page surface gets touched. Mitigation: Mira confirmed at project kickoff that CMS, reservations, and email pipeline are out of scope. Documented in the brief. If the brand owner requests adding any of these mid-flight, formal change request triggers timeline review. + +### Risk 4: Agent coordination overhead + +Claude Code participates in production tasks; Claude in Chrome runs QA gates. The agents access the Atlassian and GitHub MCPs. Risk: agent action and human action collide on the same ticket; human commits something the agent had also drafted. Mitigation: agents are not assigned tickets; they take tickets from the "Available for agent" queue (a Jira label). Humans take tickets from the "Available for human" queue. Mira moves tickets between queues at standup. + +### Risk 5: QA verification baseline drift + +Console error baseline is set at start of project. If a third-party script (analytics, heatmap, customer support chat) lands during the project and adds console errors, the baseline shifts. Mitigation: console error baseline is reset weekly during standup. Any new errors that appear get triaged immediately as either an accepted change to baseline (third-party expected) or a regression that needs fixing. + +--- + +## How to use this example + +This example is the format the orchestration plan output takes. Real outputs differ in specifics (different team, different timeline, different stack, different risks) but the structure is the same. The PM reads through, sets up the tools to match, and starts running the plan Tuesday. + +The discipline that makes this work: every section is specific. Generic plans fail. "QA gate must pass" is not a plan; "Playwright critical flows pass, console errors at baseline 0, accessibility floor WCAG AA, Lighthouse mobile at or above 85, visual regression on top 8 pages within tolerance" is a plan. diff --git a/skills/integration-orchestrator/references/gate-definitions.md b/skills/integration-orchestrator/references/gate-definitions.md new file mode 100644 index 0000000..74ea2ff --- /dev/null +++ b/skills/integration-orchestrator/references/gate-definitions.md @@ -0,0 +1,119 @@ +# Gate definitions + +The 8 standard gates. Each gate includes its trigger, approver, pass criteria, what's blocked until passing, what's already locked from prior gates, and the change-request protocol if the gate is failed or reopened later. + +A gate is the moment a phase transition gets approved. Gates work when their pass criteria are measurable. "Approved" is too vague; "client signed the artifact in writing or in a recorded review" is measurable. The orchestration plan specifies measurable criteria per gate. + +--- + +## 1. Brief approval gate + +Closes the Discovery phase (or Audit phase, on rebrand projects) and opens Direction. + +- **Trigger.** All Discovery tasks transition to Done. The brief artifact is drafted. +- **Approver.** Project owner (typically the client or the founder). For internal work, the senior stakeholder. +- **Required to pass.** The brief artifact is complete (audience, positioning, deliverables, constraints, success criteria all populated). Approver signed in writing OR a recorded review session captured agreement. The brief artifact is committed to its canonical location (Notion brief database row, Confluence page, or repo file). +- **Blocks until passed.** Direction phase work, identity phase work, voice phase work, copy work. +- **Already locked.** Nothing yet; this is the first gate. +- **Change-request protocol.** If the brief is reopened after this gate, the project re-enters Discovery briefly to assess what changed, then re-runs Direction starting from the updated brief. Identity, voice, copy, and design work that depends on the changed brief sections gets re-reviewed. + +--- + +## 2. Direction approval gate + +Closes Direction phase and opens Identity. + +- **Trigger.** Axis positions selected (tone, aesthetic, relationship, sensory). References curated. Rejection list documented. +- **Approver.** Project owner plus the design lead. +- **Required to pass.** All four axis positions confirmed in writing. Reference brands documented with one-line rationale each. Rejection list signed off (what the brief explicitly says no to). +- **Blocks until passed.** Identity phase production work. Voice production work. Any copy production. +- **Already locked.** The brief. +- **Change-request protocol.** If a direction axis is changed after this gate, identity work and voice work that depend on the changed axis get re-reviewed. Tone changes ripple to voice; aesthetic changes ripple to identity; relationship changes ripple to copy register; sensory changes ripple to motion and rhythm decisions. + +--- + +## 3. Identity approval gate + +Closes Identity phase. Opens production at full volume. + +- **Trigger.** Logo system, color tokens, typography selections, imagery direction documented and rendered. +- **Approver.** Project owner plus design lead. +- **Required to pass.** Logo lockup variants reviewed (typically 6 to 12). Selected variants documented with rationale. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented (style, palette, treatment). +- **Blocks until passed.** Design production at scale (component library, page designs). Engineering work that depends on design tokens. +- **Already locked.** Brief, direction. +- **Change-request protocol.** If identity tokens change after this gate, design files that reference the tokens get re-rendered. Engineering work that consumed the old tokens gets reviewed. Voice work is typically unaffected unless typography selection changes the implied tone register. + +--- + +## 4. Voice approval gate + +Closes voice production. Opens copy production at scale. + +- **Trigger.** Voice guide drafted. Tone-shift table populated. Vocabulary list compiled. Paired examples written. +- **Approver.** Project owner plus copy lead. +- **Required to pass.** Voice guide complete (attributes, tone shifts, vocabulary, grammar, paired examples). At least 3 paired examples per major content type (hero copy, body, microcopy). Voice signed off in writing. +- **Blocks until passed.** Copy production for shipping pages. +- **Already locked.** Brief, direction, identity (or identity in progress; voice can lock alongside identity if both phases overlap). +- **Change-request protocol.** If voice rules change after this gate, all copy that has been drafted against the old rules gets re-reviewed. The copy rework varies by scope: a vocabulary substitution is light; a tone-shift table change can mean rewriting from scratch. + +--- + +## 5. Copy approval gate + +Per-page or per-deliverable. Closes copy production for that page or deliverable. + +- **Trigger.** Copy drafted against the locked voice guide. Internal review complete. +- **Approver.** Project owner plus copy lead. For per-page copy, the page owner if different. +- **Required to pass.** Copy matches the voice guide (verifiable by running the voice-guide checklist). All sections complete. Microcopy populated. Calls-to-action consistent with the brief's success criteria. +- **Blocks until passed.** Design final for that page or deliverable. Engineering of the copy-dependent surface. +- **Already locked.** Brief, direction, identity, voice. +- **Change-request protocol.** Per-page copy changes after this gate trigger re-review of the design final for that page (because design length, hierarchy, and rhythm depend on copy length). Engineering work for that page may need to be revisited if the copy change affects layout. + +--- + +## 6. Design approval gate + +Per-page or per-deliverable. Closes design production for that page or deliverable. + +- **Trigger.** Design final rendered against locked copy and locked identity tokens. +- **Approver.** Design lead plus project owner. +- **Required to pass.** Design references the locked identity tokens (no off-token color, type, or spacing values). Copy is reflected exactly as approved (no copy edits hidden in the design). Responsive states designed. Empty states, loading states, error states accounted for. +- **Blocks until passed.** Engineering of the design-dependent surface. +- **Already locked.** Brief, direction, identity, voice, copy. +- **Change-request protocol.** Design changes after this gate trigger engineering re-review for the affected surface. The change-request protocol routes through the design lead to assess scope (token-level changes are light; component or layout changes are heavy). + +--- + +## 7. QA verification gate + +Per-surface. Closes engineering and verification, opens launch readiness for that surface. + +- **Trigger.** Ticket transitions to "QA" status (developer signaled engineering complete). +- **Approver.** Automated test suite, with human review on test failure or ambiguous result. +- **Required to pass.** Defined Playwright critical-flow test suite green. Console error count at or below baseline (specify the baseline per project; for a typical web app, 0 errors at hero load, 0 errors during critical flows). Accessibility floor maintained: WCAG AA contrast ratios on all text, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled. Performance budgets met (Lighthouse mobile score at or above project target, Core Web Vitals at or above project target). Visual regression on key pages within tolerance. +- **Blocks until passed.** Status transition to Done. Launch readiness for the affected surface. +- **Already locked.** Code merged to main, design tokens, copy, identity, voice, direction, brief. +- **Change-request protocol.** Failure routes the ticket to Blocked status (not back to In Progress). The blocker reason is documented in the ticket comment. If the failure surfaced something unrelated to the ticket's scope (e.g., a regression in a sibling page), an adjacent observation is filed in the project triage queue. The human is paged via the configured channel. The agent does NOT continue retrying autonomously. + +--- + +## 8. Launch readiness gate + +Closes the project (or the launch phase of a multi-phase project). + +- **Trigger.** All affected surfaces have passed the QA verification gate. +- **Approver.** Project owner plus the launch coordinator (typically the PM or the senior engineer on rotation). +- **Required to pass.** Deployment checklist complete (environment variables set, secrets rotated, third-party integrations live, monitoring active, alerting configured). Rollback plan documented (which command, who runs it, where logs go). Launch communications drafted (internal: who knows the launch is happening; external: any customer-facing announcement). On-call coverage assigned for the launch window. +- **Blocks until passed.** The actual production deploy. +- **Already locked.** Everything: brief, direction, identity, voice, copy, design, code, QA evidence. +- **Change-request protocol.** Launch readiness failure typically delays the launch rather than reopening upstream gates. If the failure is severe (a critical bug found in pre-launch QA), the affected surface returns to In Progress for fix, then re-runs through Engineering and QA verification before launch can proceed. + +--- + +## How gates compose + +Gates are not isolated. Each gate locks artifacts that downstream gates assume are stable. A QA verification failure that traces to a copy bug means the copy approval gate produced bad output, which traces back to either a voice rule that wasn't applied or a brief that wasn't reflected. The gate chain is the audit trail. + +When a gate is reopened, the change-request protocol cascades downstream. The orchestration plan specifies the protocol per gate so the team knows in advance what re-review work a change triggers. The cost of a change is visible at the moment it's requested, not discovered after the fact. + +The QA verification gate is the gate that does the most work for the team. It is the gate that prevents "Done" from being self-reported. Configure it carefully; trust it once configured. diff --git a/skills/integration-orchestrator/references/handoff-protocols.md b/skills/integration-orchestrator/references/handoff-protocols.md new file mode 100644 index 0000000..0fd39c5 --- /dev/null +++ b/skills/integration-orchestrator/references/handoff-protocols.md @@ -0,0 +1,143 @@ +# Handoff protocols + +A handoff is the moment work transfers between phases or skills. Without explicit handoff specs, the receiving phase opens a half-dozen Slack threads to find what they need. With them, the work moves cleanly because the receiving phase knows exactly what artifacts to expect, what's locked, and what's still open. + +This file covers the 7 standard handoffs plus an 8th cross-cutting handoff: the adjacent-observation routing. + +--- + +## 1. Discovery to Brief + +The first handoff. Discovery findings transfer to brief drafting. + +- **What's transferred.** Audience research notes (interview summaries, persona documents, audience-side observations). Positioning notes (competitive landscape, differentiation hypotheses). Reference materials gathered during discovery (brands, articles, examples that surfaced). +- **What's locked.** Nothing yet. Everything is still open. +- **What stays open.** All of it. Discovery is input, not decision. +- **Common breakdown.** Discovery findings get summarized too aggressively; the brief drafter loses the nuance. Mitigation: hand off the full notes plus a synthesis, not just the synthesis. +- **Artifact specification.** Discovery findings live in a Notion database, a Google Doc, or a folder of markdown files. The handoff includes a link plus a one-paragraph synthesis. +- **Platform support.** Notion: relation property from brief row to discovery findings. Jira: linked issue. Linear: project relationship. + +--- + +## 2. Brief to Identity + +After brief approval. The identity work begins against the locked brief. + +- **What's transferred.** Approved brief (audience, positioning, deliverables, constraints). Direction artifact (axis positions). Reference brand list. Rejection list. +- **What's locked.** Brief is locked. Direction is locked. Audience and positioning cannot be revisited without change request. +- **What stays open.** Everything inside the identity scope: logo system, color, typography, imagery direction, motion. The identity team picks within the constraints the brief and direction set. +- **Common breakdown.** The identity team interprets the rejection list loosely. A "no laurel mark" rejection becomes "well, our laurel is different". Mitigation: rejection-list adherence is a gate criterion at identity approval. +- **Artifact specification.** Brief lives in its canonical location (Notion brief row, Confluence page, or repo file). Direction artifact is a sibling document. Both URLs go in the identity-phase Epic or Project description. +- **Platform support.** Jira: Epic description with links. Linear: Project description with attached docs. Notion: relation properties. + +--- + +## 3. Brief to Voice + +In parallel with Brief-to-Identity. Voice work begins against the locked brief and direction. + +- **What's transferred.** Approved brief. Direction artifact (specifically the tone-axis position). Reference voice samples (other brands the team likes for their voice). +- **What's locked.** Brief, direction. +- **What stays open.** Voice attributes, tone-shift rules, vocabulary choices, grammar rules, paired examples. +- **Common breakdown.** Voice gets started without referencing the locked tone-axis position; the writer drafts in their natural voice rather than the project's. Mitigation: voice production opens with a tone-axis check ("the brief says Provocative; here is what Provocative implies for vocabulary, sentence shape, and rejection list"). +- **Artifact specification.** Tone-axis position from direction artifact. Reference voice samples as a Notion subpage or a markdown file with quoted samples. +- **Platform support.** Same as Brief-to-Identity. + +--- + +## 4. Identity plus Voice to Copy + +After identity approval and voice approval. Copy production begins. + +- **What's transferred.** Identity tokens (typography selections, color tokens, spacing). Voice guide (attributes, tone shifts, vocabulary, paired examples). Page or deliverable scope (which pages, which sections, what each section needs). +- **What's locked.** Brief, direction, identity tokens, voice rules. +- **What stays open.** Per-page copy choices within the locked voice. Calls-to-action language. Section ordering decisions where the design has not yet been finalized. +- **Common breakdown.** Copy is drafted for length without the typography in mind, and lands in design as either too long or too short for the rendered hero. Mitigation: copy production references the typography selection from the start; the writer drafts knowing which weight and size the copy will live in. +- **Artifact specification.** Identity tokens published in Figma library or in a tokens markdown file. Voice guide as a Notion page or markdown file. Page scope as a Jira/Linear ticket per page. +- **Platform support.** Figma library is the canonical token source. Jira/Linear ticket per page or section. + +--- + +## 5. Identity plus Copy to Design + +After copy approval per page. Design final begins for that page. + +- **What's transferred.** Locked copy (final approved text). Identity tokens (typography, color, spacing). Voice guide (for microcopy and any error or empty states the design generates). +- **What's locked.** Brief, direction, identity, voice, copy for the affected page. +- **What stays open.** Design layout decisions, responsive breakpoint behavior, motion design, empty/loading/error states. +- **Common breakdown.** Design starts before copy locks. Length, rhythm, and hierarchy get designed against placeholder text; when copy lands, the design has to be reworked. Mitigation: copy locks per page before design final starts. If parallel work is needed, design produces a wireframe with placeholder copy AND a flag noting "real copy pending; layout subject to revision". +- **Artifact specification.** Locked copy in the canonical copy doc with an explicit "approved" marker. Identity tokens in Figma library. Page scope from copy-phase ticket. +- **Platform support.** Figma frame per page, linked to ticket in Jira/Linear. + +--- + +## 6. Design to Engineering + +After design approval per page. Engineering builds the page. + +- **What's transferred.** Final design (Figma file URL). Tokens (referenced from Figma library). Asset library (images, icons, illustrations exported and named per convention). Component specifications (any new components designed). Responsive behavior notes. Motion specifications (entry, exit, hover, loading states). +- **What's locked.** Brief, direction, identity, voice, copy, design final. +- **What stays open.** Implementation choices (state management, framework patterns, accessibility implementation, performance optimization). Component naming if new components. +- **Common breakdown.** Asset exports happen ad-hoc as engineering needs them, leading to inconsistent file names, missing variants, and back-and-forth Slack messages. Mitigation: design phase exports a complete asset library (using the team's naming convention) before handoff. Engineering pulls from the library, does not request new exports during build unless missing. +- **Artifact specification.** Figma URL, exported asset folder (cloud bucket or repo path), responsive notes as Figma annotations or a sibling markdown doc. +- **Platform support.** Figma URL in the engineering ticket. Asset folder URL or path in the ticket. PR template references the design ticket. + +--- + +## 7. Engineering to Launch + +After QA verification per surface. The surface goes to launch. + +- **What's transferred.** Verified surface (deployed to staging, tested). QA evidence (Playwright run results, accessibility audit results, performance audit results, console error counts). Deployment checklist for this surface. Rollback plan. +- **What's locked.** Everything: brief, direction, identity, voice, copy, design, code merged to main, QA evidence. +- **What stays open.** Launch coordination (which surface launches first, monitoring during launch window, on-call coverage). +- **Common breakdown.** Launch happens before all surfaces have passed QA verification. Result: one surface launches with bugs, recoverable with rollback if monitoring catches it. Mitigation: launch readiness gate requires ALL surfaces to have passed QA verification, not just the most-prominent surface. +- **Artifact specification.** QA evidence linked to ticket (screenshots, GIFs, test result logs). Deployment checklist as a runbook document. Rollback plan as a sibling runbook document. +- **Platform support.** GitHub PR with QA artifact attachments or evidence URL. Linear or Jira ticket with the runbook URL. + +--- + +## 8. Adjacent observation handoff (cross-cutting) + +The handoff that fires when an agent or person, while working on Task X, notices something about Task Y or Surface Z that is not the current task but is contextually adjacent. + +### Examples + +- Working on copy for the homepage hero, the writer notices the footer copy is inconsistent with the new voice. Filing the footer inconsistency as an observation, not stopping the homepage work. +- Running QA on the pricing page, an agent notices the contact form on the about page has a console error. Filing the contact form error as an observation, not pausing the pricing-page QA. +- Updating the Figma design library, the designer notices a deprecated component is still being used in the dashboard mockups. Filing a usage-cleanup observation, not modifying the dashboard mockup. +- Reviewing a PR, an engineer notices a typo in a docstring in an unrelated file. Filing a typo observation, not blocking the PR review on it. + +### Why this handoff matters + +Without it, the team has two bad options. Option one: stop the current work and address the observation, derailing focus. Option two: ignore it, lose the context, never come back to it. The adjacent-observation handoff lets the current work proceed while preserving the finding for triage. + +### Routing + +The observation gets filed in a project triage queue, NOT directly assigned to anyone. The triage queue is reviewed on a regular cadence (typically daily standup or weekly grooming). The PM or tech lead triages the observation: discard if it's not relevant, file as a normal ticket if it is, attach to an existing ticket if it's a fragment of larger work. + +### Content of the observation + +Each filed observation includes: + +- **What was observed.** A specific factual statement (the footer says "Get in Touch" while the new voice would say "Reach out"). +- **Why it might matter.** A brief rationale (voice consistency, user-facing inconsistency, latent bug). +- **Where it was noticed.** A link to the work that was happening when the observation surfaced (the PR, the Figma frame, the Notion page). +- **Suggested triage priority.** The reporter's gut call (low / medium / high). The triager makes the actual call; the suggestion is just signal. + +### Platform support + +- **Jira.** A separate "triage" project or a labeled queue inside the main project. Observations get filed without an assignee; the triager assigns at triage time. +- **Linear.** A "Triage" inbox is built into Linear and works exactly for this purpose. +- **Notion.** A triage database; the assignee field stays empty until triage. +- **GitHub.** Observations filed as issues without an assignee; CODEOWNERS may auto-route the issue to the relevant team for triage. + +The orchestration plan specifies which platform's triage queue is the canonical one for the project (typically the same platform as the main work) and the triage cadence (daily standup or weekly grooming). Without those specifics, observations either pile up untriaged or scatter across channels and get lost. + +--- + +## How handoffs compose with gates + +A gate closes a phase. A handoff opens the next phase's work against the gate's locked output. The two patterns reinforce each other: gates make sure nothing premature ships; handoffs make sure the receiving work has what it needs to start. + +A failed gate triggers a handoff backward (rework the prior phase). A failed handoff (artifact missing, scope unclear) is itself often the symptom of a gate that didn't enforce its pass criteria. When a handoff goes wrong, audit the prior gate's criteria. diff --git a/skills/integration-orchestrator/references/platform-implementation.md b/skills/integration-orchestrator/references/platform-implementation.md new file mode 100644 index 0000000..f62ee1b --- /dev/null +++ b/skills/integration-orchestrator/references/platform-implementation.md @@ -0,0 +1,174 @@ +# Platform implementation + +How the orchestration plan implements in each platform. Per platform: workflow representation (how phases, gates, lock points, and handoffs map), MCP integration notes (what AI agents can do via the platform's MCP), and CLI alternatives (where the CLI is the better tool than MCP). + +For setup screenshots and additional team patterns, consult each platform's official documentation alongside this file. + +--- + +## Jira / Atlassian + +### Workflow representation + +- **Phase representation.** Each phase becomes an Epic. Stories or Tasks live within the Epic. Custom fields tag the Phase explicitly. +- **Gate representation.** Workflow status. The 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) maps to Jira's workflow statuses, with workflow validators or transitions enforcing gate rules. A custom "Gate Status" field tracks gate state separately from issue status. +- **Lock-point representation.** Custom field "Locked" (boolean) on the parent artifact (Epic for phase locks, Story for per-page locks). Locked issues display a visible label so reviewers know not to make untracked changes. +- **Handoff representation.** Issue link types ("Blocks", "Is blocked by", "Relates to"). Linked Confluence page for the artifact (brief, direction, voice guide, copy doc). +- **Concrete setup snippet.** Issue type scheme: Epic, Story, Task, Subtask, Bug. Custom fields: Phase (single-select with phase names), Locked (checkbox), Approver (user picker), Gate Status (single-select with the 8 standard gates). Workflow scheme: 5-status taxonomy with validators preventing premature transitions. + +### MCP integration notes + +- **Availability.** Official remote MCP server, launched 2025. +- **References.** [Atlassian's Remote MCP Server announcement](https://www.atlassian.com/blog/announcements/remote-mcp-server) and [github.com/atlassian/atlassian-mcp-server](https://github.com/atlassian/atlassian-mcp-server). +- **Capabilities.** Jira issue CRUD, status transitions, comment posting, JQL queries, Confluence page operations (read, write, update). Authentication via OAuth or API token. +- **What the orchestrator skill can populate via MCP.** Initial epic structure from the orchestration plan (one epic per phase). Initial issue tree (stories per work item). Custom field values from the orchestration plan (Phase, Approver, Gate Status). Comments documenting handoffs and gate transitions. Confluence pages for the brief, direction artifact, voice guide, and orchestration plan itself. +- **Practical limits.** Workflow scheme creation typically requires admin-level UI setup; MCP is better at populating against an existing scheme than at configuring the scheme from scratch. Heavy Confluence content edits lose Atlassian Document Format (ADF) details through MCP roundtrips when the content is rich (tables, callouts, complex code blocks). For simple page content, MCP roundtrips work; for heavily-formatted content, edit in the UI or use the CLI. + +### CLI alternatives and when to use them + +- **Atlassian official CLI (acli)** plus community alternatives (jira-cli, etc.). +- **When CLI is the better choice.** + - Bulk operations across many tickets (200+ issues). MCP roundtrips become token-expensive at scale; CLI is more efficient. + - Heavy Confluence content edits where ADF formatting matters. CLI tools that parse and write ADF directly preserve formatting better than MCP roundtrips. + - Scripted reporting (export issues to CSV, generate burndown reports, run JQL across multiple projects). + - CI integration (running JQL in a CI step to validate that all blockers are resolved before deploy). +- **Pattern note.** Some teams mirror Jira and Confluence content as local markdown files in a `.atlassian/` folder, syncing periodically via CLI. This pattern trades simplicity for power. Document it as one viable approach for engineering-heavy teams; PMs will rarely need it. + +--- + +## Linear + +### Workflow representation + +- **Phase representation.** Each phase becomes a Project. Cycles (Linear's time-boxed sprints) sit within the project for week-by-week granularity. +- **Gate representation.** Project status workflow plus issue status workflow. Linear's status workflow customizes to the 5-status taxonomy. Labels mark gate state per issue (e.g., "gate:identity-approved", "gate:qa-pending"). +- **Lock-point representation.** Labels (e.g., "locked:identity-tokens", "locked:voice"). Locked issues stay visible in their project but cannot be reopened without an explicit label removal. +- **Handoff representation.** Project relationships (predecessor / successor projects), issue dependencies, and Linear's automatic mention parsing for cross-references. +- **Concrete setup snippet.** Project template per project type (new brand build, rebrand, etc.) with phases pre-populated as projects, cycles configured, label taxonomy defined. Status workflow customized to include Blocked as a first-class status (Linear ships with Backlog, Todo, In Progress, Done, Cancelled by default; add Waiting and Blocked). + +### MCP integration notes + +- **Availability.** Official, well-supported. +- **Reference.** [linear.app/docs/mcp](https://linear.app/docs/mcp). +- **Capabilities.** Issues, projects, cycles, teams, labels, comments, attachments. Full CRUD on most entities; webhooks for event-driven workflows. +- **What the orchestrator skill can populate via MCP.** Project setup with cycles. Label taxonomy from the orchestration plan. Initial issue population per phase. Project description and milestones. Status workflow customization. Initial assignee and reviewer assignments per the orchestration plan's review-by routing. +- **Coverage note.** Linear's MCP coverage is the most complete of the 5 platforms. For teams running a Linear-based stack with AI agents, this MCP is the recommended starting point. The agent can do almost everything programmatically. + +### CLI alternatives and when to use them + +- **CLI status.** No widely-adopted Linear CLI. The MCP coverage is sufficient that CLI is rarely needed. +- **API direct calls** remain an option for scripted setup if MCP isn't available in the runtime context. +- **When the API is the better choice.** Bulk import scripts when migrating from another platform. Scheduled reports run from CI. Webhook handlers for event-driven external integrations. + +--- + +## Notion + +### Workflow representation + +- **Phase representation.** Brief database with one row per project. Related databases for direction docs, identity specs, voice guides, copy decks. Each related database has its own rows; relation properties tie everything to the canonical brief. +- **Gate representation.** Status property on each artifact row. Phase view filters the database by status to surface what's open vs locked. +- **Lock-point representation.** A "Locked" checkbox or status property on each artifact row. Filtered views surface locked vs unlocked artifacts. +- **Handoff representation.** Relation properties between databases. The brief row relates to the direction row, which relates to the identity spec row, which relates to the voice guide row, etc. +- **Concrete setup snippet.** Brief database schema: Title, Status, Phase, Locked, Approver, Owner, Notes. Related databases: Direction, Identity, Voice, Copy, Design, QA Evidence. Relation properties tie each related row back to the brief. Dashboard view per phase. + +### MCP integration notes + +- **Availability.** Official. +- **Reference.** [developers.notion.com/guides/mcp/overview](https://developers.notion.com/guides/mcp/overview). +- **Capabilities.** Database queries, page CRUD, property updates, block-level reads, search. +- **What the orchestrator skill can populate via MCP.** Brief-as-database-row schema creation (with the property set from the orchestration plan). Relation property setup between briefs and project artifacts. Initial brief content population from the orchestration plan. Dashboard view configuration where the view config supports it (with caveats; some view configurations remain UI-only). +- **Practical limits.** Workspace-level permissions and team membership remain UI-driven; MCP is most useful AFTER initial workspace setup. Some view types (calendar views, certain board views with custom grouping) cannot be created via MCP and must be set up in the UI. + +### CLI alternatives and when to use them + +- **Community CLIs.** notion-cli and similar tools exist but are less mature than the MCP. +- **When the CLI is the better choice.** Exporting databases for backup. Bulk content migration from another tool. Scripted database schema changes (adding properties across hundreds of rows). +- **For most teams.** The MCP is sufficient. CLI tools become useful only for specialized operations the MCP can't handle. + +--- + +## Figma + +### Workflow representation + +- **Phase representation.** Library file with frame folders per phase: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status surfaces in the Figma comments and frame metadata. +- **Gate representation.** Frame status (Ready for review / In review / Approved). Components versioned in the library; outdated components marked as deprecated rather than deleted (downstream files still reference them). +- **Lock-point representation.** Library publish state. Once a library version is published, dependent files reference that version. Token changes ship as a new library version, which downstream files explicitly opt into. +- **Handoff representation.** Frame URL plus exported assets. Engineering handoff uses Dev Mode for token export and component spec. +- **Concrete setup snippet.** Library file structure: top-level pages for "Tokens", "Components", "Patterns", "Page templates", "Working files". Within each, frame folders per phase. Frame-level review status set via Figma's standard comment-and-status workflow. Library publish discipline: identity tokens publish at the identity gate; the library version is the lock point. + +### MCP integration notes + +- **Availability.** Figma Dev Mode MCP exists but is dev-mode-focused (component inspection, code generation, design token export). +- **Reference.** Figma's [Dev Mode documentation](https://www.figma.com/dev-mode/). +- **Capabilities (Dev Mode MCP).** Component property reads. Design token export (color, typography, spacing). Frame inspection (layer tree, properties, constraints). Component variant queries. +- **What the orchestrator skill can populate via MCP.** Limited. Library structure recommendations and frame organization remain primarily manual setup. The MCP is more useful for downstream developer handoff than upstream design ops. +- **Practical limits.** Design library creation, frame organization, library-level permissions, and team membership are UI-driven. Treat the orchestrator skill's Figma recommendations as documentation for the design lead, not as automation targets. + +### CLI alternatives and when to use them + +- **Figma API.** Can be invoked via custom scripts for token export, asset download, and metadata queries. No first-party CLI for design ops. +- **When the API is the better choice.** Token export scripts that run in CI to update a design system repository. Asset download automation for engineering handoffs. Metadata reporting (audit how many frames are in review status across the library). +- **For most cases.** The design lead implements Figma orchestration manually following the skill's recommendations. Automation is layered in only when the project is large enough to warrant the engineering investment. + +--- + +## GitHub + +### Workflow representation + +- **Phase representation.** Issues for non-engineering tracking (when GitHub is the canonical platform; otherwise Jira/Linear lead). Branches per feature with naming convention `{type}/{ticket}-{slug}`. PRs for design and engineering review. +- **Gate representation.** Branch protection on `main`. PR review requirements. CODEOWNERS for review routing. GitHub Actions for CI gates (lint, test, build, deploy preview). +- **Lock-point representation.** Branch state. Once code is merged to main, it's locked unless a follow-up PR amends it. Tags mark release lock points. +- **Handoff representation.** PR description references the originating ticket. PR review by CODEOWNERS routes to the right reviewer. PR merge triggers ticket auto-transition (configured per platform combination). +- **Concrete setup snippet.** Branch protection: require PR reviews before merge, require status checks (CI), require linear history (rebase or squash, no merge commits). CODEOWNERS file routes PRs to the relevant team. PR template requires ticket reference, summary, test plan, screenshots/GIFs for UI changes. GitHub Actions workflow runs CI gates on every PR. + +### MCP integration notes + +- **Availability.** Official. +- **Reference.** [github.com/github/github-mcp-server](https://github.com/github/github-mcp-server). +- **Capabilities.** PR ops (create, comment, review, merge). Issue ops (create, comment, close, label). File content (read, write). Branch protection (read; configuration is mostly UI/API-driven). Repository search. Code search. Workflow runs (read). +- **What the orchestrator skill can populate via MCP.** PR template files. Issue templates. CONTRIBUTING.md and review-protocol docs. Initial issue tree from the orchestration plan when GitHub is the canonical work tracker. CODEOWNERS file. GitHub Actions workflow files committed to `.github/workflows/`. +- **Practical limits.** Branch protection rulesets are typically configured via GitHub UI or repository settings API (not MCP); the orchestrator skill's branch protection recommendations remain documentation rather than automation. Repository creation, team membership, and organization-level settings are UI-driven. + +### CLI alternatives and when to use them + +- **gh CLI.** The dominant tool for GitHub operations. Officially maintained, broadly adopted. +- **When to prefer gh CLI over MCP.** + - Bulk PR operations (merging 20 dependabot PRs in a single sweep). + - Scripted workflows (a deploy script that creates a release, tags, and updates a changelog). + - Repository setup automation (create a new repo, push initial commits, set up labels and branch protection). + - When token cost matters on heavy operations. The CLI is more efficient than MCP roundtrips for repetitive tasks. +- **Hybrid pattern.** Most production setups use both. MCP for navigation and orchestration ("show me open PRs assigned to me", "comment on PR #123 with this summary"); gh CLI for transactional and bulk operations ("create a PR from this branch with these reviewers", "merge these 10 dependabot PRs"). The two tools complement each other. + +--- + +## Cross-platform patterns + +### Code-to-ticket linkage + +The standard convention for linking PRs and commits back to tickets: + +- **Branch naming.** `{type}/{ticket}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform (RAMP for the team's main project in Jira, LIN for Linear, etc.). +- **PR descriptions.** Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- **Commit messages.** Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. + +### Status synchronization + +When a PR merges, the linked ticket auto-transitions. Configure via the linked platform's automation: + +- **Jira automation.** "When PR merged, transition issue to Done" (with QA verification gate enforced upstream so this is safe). +- **Linear's auto-transition.** Linear-GitHub integration auto-moves issues based on PR state. +- **GitHub Actions.** A workflow that runs on PR merge and posts a comment to the linked Linear/Jira issue. Useful when the platform's native integration doesn't cover the team's exact transition rules. + +### Multi-platform stacks + +Common combinations: + +- **Linear + GitHub.** Most common for tech teams. Linear's MCP is mature; GitHub's MCP is mature. The two integrate well via Linear's GitHub integration plus PR/branch naming conventions. +- **Jira + GitHub.** Most common for enterprise. Atlassian remote MCP plus GitHub MCP cover the orchestration; workflow setup is more involved than Linear because Jira's workflow flexibility means more setup decisions. +- **Notion + Linear + GitHub.** PM-led with engineering sub-tracking. Notion holds the brief and creative artifacts; Linear holds the engineering work; GitHub holds the code. Notion-Linear linking is via relation property pointing to the Linear issue URL; Linear-GitHub linking is via Linear's native integration. +- **Notion + Figma + GitHub.** Creative-led with engineering handoff. Notion holds the brief; Figma holds the design; GitHub holds the code. This combination has the lightest engineering tooling and works for design-led projects with simple production paths. + +The orchestration plan specifies the canonical platform for each work type and the linkage convention between platforms. Without that specification, work scatters across platforms and links break. diff --git a/skills/integration-orchestrator/references/team-size-modulation.md b/skills/integration-orchestrator/references/team-size-modulation.md new file mode 100644 index 0000000..246ba2f --- /dev/null +++ b/skills/integration-orchestrator/references/team-size-modulation.md @@ -0,0 +1,65 @@ +# Team-size modulation + +A 2-person team and a 12-person team need different orchestration. The framework (phases, gates, lock points, handoffs) is the same; the cadence's review density, sync ceremony, and tool-stack adjustments scale with team size. + +This file covers four scales: solo, small (2-3), medium (4-7), large (8+). For each: review density, sync cadence, handoff formality, risk profile, tool-stack adjustments, and AI agent participation pattern. + +--- + +## Solo (1 person) + +Everything is the same person playing every role. The brief author, identity designer, voice writer, copy writer, design lead, and engineer are all you. + +- **Review density.** Self-review only. Per-phase self-review checklists replace formal gates. The risk is that nothing actually catches mistakes; the discipline is to step away from the work between drafting and reviewing (overnight is best, an afternoon walk is the minimum). +- **Sync cadence.** Daily plan, weekly review against the orchestration plan. Document the daily plan and the weekly review in a project state file (CLAUDE.md, AGENTS.md, or .agent/state.md). +- **Handoff formality.** Inline. Self-handoffs document themselves in the project state file rather than as separate artifacts. +- **Risk profile.** Phases blur together. Lock points get unfrozen without ceremony. The brief that was approved last week becomes "well, I had a better idea, let me just edit it" and downstream work drifts. +- **Tool-stack adjustments.** Skip Jira workflow validators, Linear cycle ceremony, formal review routing. Use the simplest tool the project needs (often Notion or markdown files in a repo). Resist setting up tooling beyond what's actually used; solo projects fail more often from over-tooling than from under-tooling. +- **AI agent participation pattern.** Heavy. Solo work benefits most from agent participation because the agent is the second pair of eyes that solo work otherwise lacks. The agent runs QA verification gates, reviews copy against the locked voice, runs accessibility audits, and surfaces patterns the solo person might miss. The orchestration plan output specifies which agent runs at which gate. + +--- + +## Small (2-3 people) + +Single reviewer per gate. Async handoffs are fine. Daily standup is sufficient for sync. + +- **Review density.** One reviewer per gate. The team picks a primary reviewer per phase based on expertise (design lead reviews identity gates, copy lead reviews voice and copy gates, the senior engineer reviews QA verification and launch readiness). +- **Sync cadence.** Daily 15-minute standup. Weekly 60-minute phase review. Async messaging in between. +- **Handoff formality.** Documented but inline (a Notion page comment, a Linear issue description, a Slack message in the project channel). The small team can rely on shared context that larger teams cannot. +- **Risk profile.** The single reviewer becomes a bottleneck. When the design lead is the only person who can pass the identity approval gate and they're on PTO, the project blocks. Mitigation: the orchestration plan specifies a backup reviewer per gate. +- **Tool-stack adjustments.** Light tool setup. Linear's default workflow is fine; Jira can run with a basic workflow scheme; Notion runs with basic database schemas. Don't set up complex automations until the team feels the lack of them. +- **AI agent participation pattern.** Moderate. Agents handle production tasks, QA verification, and adjacent observation filing. Humans handle reviews, gate approvals, and decisions that require taste or political judgment. The orchestration plan specifies which roles agents fill and which stay human. + +--- + +## Medium (4-7 people) + +Multiple reviewers, async sync points, weekly phase reviews. The team is large enough that shared context erodes; documentation matters more. + +- **Review density.** Two reviewers per gate (one primary, one secondary for cross-check). Reviewer rotation across phases prevents one person from becoming the bottleneck. +- **Sync cadence.** Daily standup. Weekly phase review. Bi-weekly cross-track sync if there are parallel tracks. Async messaging in between with explicit channels per phase. +- **Handoff formality.** Documented in the canonical platform (Jira issue, Linear project, Notion database row). Slack threads are fine for discussion but the canonical record lives in the work-tracking platform. +- **Risk profile.** Review density becomes the gating factor. Reviewers stack up at end of phase, leading to fatigue reviews and rubber-stamped approvals. Mitigation: within-phase mini-gates that flatten review demand. Instead of reviewing 8 deliverables on phase-end Friday, review 2 mid-week and 6 at phase-end. +- **Tool-stack adjustments.** Custom fields, labels, and automation start to matter. Set up workflow validators that prevent premature transitions. Set up custom views per role (designer view, engineer view, PM view) so each person sees only what's relevant to them. +- **AI agent participation pattern.** Agents handle QA verification gates, surface adjacent observations, and run reports (which tickets are stuck, which gates are open, which assignees are overloaded). Humans handle reviews and approvals. The agent's role expands from "do production work" to "monitor the orchestration plan and surface drift". + +--- + +## Large (8+ people) + +Formal phase reviews, dedicated PM for orchestration, multiple parallel tracks. Cross-track drift is the dominant risk. + +- **Review density.** Three or more reviewers per gate. Phase reviews become formal meetings with prepared agendas. Reviewer rotation is mandatory; the project cannot rely on any one person. +- **Sync cadence.** Daily standup per track. Weekly cross-track sync. Bi-weekly project-wide review. Monthly stakeholder review for projects spanning multiple months. +- **Handoff formality.** Strict. Every handoff specifies artifacts, locked items, and change-request protocols in writing. Async handoffs without artifact specification break large teams; the receiving track wastes a week trying to figure out what was actually handed off. +- **Risk profile.** Cross-track drift. Track A and Track B both interpret the brief differently; by week 3 the two tracks read as different brands. Mitigation: a dedicated brief-owner role whose job is to maintain the brief as canonical reference, plus cross-track sync ceremonies and explicit change-request protocols. Brief drift is a leading indicator; the brief-owner role exists to catch it before it becomes track drift. +- **Tool-stack adjustments.** Full workflow scheme with validators. Custom fields tracking phase, gate status, approver, locked status. Multiple boards or views per track. Automation rules for status synchronization across linked platforms (Jira-GitHub, Linear-GitHub). Reporting dashboards. +- **AI agent participation pattern.** Agents become orchestration monitors. The agent's role is to track phase status across tracks, surface drift, run cross-track sync prep (which tracks are on schedule, which are slipping), file adjacent observations across track boundaries, and run QA verification gates. The agent is most valuable at the cross-track surface where humans cannot easily hold all the context. + +--- + +## How to choose your scale's pattern + +Match the cadence to actual team size. The most common mistake is to use a small-team cadence on a medium-team project, which leads to the single-reviewer bottleneck, OR to use a large-team cadence on a small-team project, which leads to ceremony overhead that nothing earns. + +When the team scales mid-project (a 2-person small team grows to 5 people during production phase, for example), the orchestration plan should specify the transition: at what point does the cadence shift, what new reviewers come online, what additional ceremonies start. The plan's risk register should flag scaling moments as a known risk because cadence transitions are themselves a source of drift. diff --git a/skills/interactive-product-tour/SKILL.md b/skills/interactive-product-tour/SKILL.md new file mode 100644 index 0000000..59256aa --- /dev/null +++ b/skills/interactive-product-tour/SKILL.md @@ -0,0 +1,251 @@ +--- +name: interactive-product-tour +description: "Designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. Honest about tooltip-spam (visual noise that users develop blindness to), one-and-done (help invisible at the moment of need), and contextual-when-needed (surfaces help at the moment friction occurs) patterns. Triggers on product tour, in-product tooltip, contextual help, walkthrough, feature tour, hint system, in-app guidance, tour platform. Also triggers when feature adoption is low, when users miss key product capabilities, or when an in-product help system is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing in-product tours and contextual help. Distinguishes tooltip-spam (every button has a tour stop) from one-and-done (tour shows once, never seen again) from contextual-when-needed (surfaces help at the moment friction occurs)" +display_order: 8 +--- + +# Interactive Product Tour + +A senior product marketing director's playbook for designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. The discipline of building help systems that surface at moments of need and disappear when not needed. + +Most product tours fail in one of two ways. They paint every button, link, and feature with "click for tour" hints until the visual noise is so great that users develop blindness to the dots. Or they show a single first-login tour the user skips or skims, after which the same help never re-surfaces when the user actually hits a moment of friction. Help that is invisible at the moment of need is help that does not exist. + +The tours that work do something different. They trigger when the user is at a moment of friction, not all the time. They surface contextual hints when the user enters a section they have not explored, clicks into a feature requiring setup, or returns after a long absence. The system knows what the user knows and surfaces help at the right moment. + +The voice is the senior product marketing director who has watched feature adoption double when tours were redesigned and watched it collapse when more tooltips were piled onto every surface. Practical, opinionated about the trigger logic that distinguishes useful help from visual noise, willing to call out when no in-product tour at all is the right answer. + +When to use this skill: scoping an in-product help system for the first time, auditing a tour system that produces engagement metrics with no adoption lift, designing the trigger logic that decides when help surfaces, or deciding which features warrant tours vs documentation. + +--- + +## What this skill covers + +This skill spans in-product tours, tooltips, and contextual help. The growth-tooling distinctions: + +- `onboarding-wizard-design` is the sequential first-run experience. This skill is contextual help WITHIN the product, surfacing across the lifecycle. +- `chatbot-flow-design` is conversational help. This skill is non-conversational tour and tooltip help. +- **`interactive-product-tour` (this skill)** is trigger logic, tour architecture, contextual placement, completion tracking, and the discipline of being absent until needed. +- `discovery-research-synthesis` is research that informs tour content. Input, not part of. +- `pm-spec-writing` is the spec for engineers building the tour. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams, agencies running activation work for SaaS clients. + +Out of scope: first-run wizards (covered by `onboarding-wizard-design`); conversational help (covered by `chatbot-flow-design`); the engineering implementation; specific Userpilot/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The tour decision: when tours earn vs when documentation suffices + +Before designing the tour system, decide whether tours are the right tool. + +**Tours earn investment when:** + +- The product has features users genuinely miss without prompting. Specific functionality buried in menus, advanced workflows that require sequence, integrations users do not know exist. +- The audience benefits from in-context guidance more than out-of-context documentation. Tours teach in the place the user will use the feature; docs require context-switching. +- The team can maintain tours as the product evolves. Tour content decays; without maintenance commitment, tours point to deprecated UI. +- The success metric is defined. Feature adoption, time-to-value for specific capabilities, reduction in support tickets for tour-covered features. + +**Tours do NOT earn investment when:** + +- The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. +- The audience prefers self-directed discovery. Some audiences resent in-product guidance and prefer to explore. +- The team cannot maintain tours alongside product changes. Stale tours are worse than no tours. +- The product changes frequently. Tour maintenance can exceed tour value if the product churns rapidly. + +The decision is not "should we have a tour system"; it is "is in-product tour the right tool for this product and audience." + +Detail in [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md). + +--- + +## Tooltip-spam vs one-and-done vs contextual-when-needed + +The keystone framing. + +**Tooltip-spam.** Every button, link, and feature has a "click for tour" hint or pulsing dot. Visual noise. Users develop blindness to the dots; the tour system fails as a teaching surface. Cost: the design effort produces help nobody perceives; the visual clutter degrades the product overall. + +**One-and-done.** A single tour shown on first login. Users skip or skim. The same tour never re-surfaces when the user actually hits a moment of friction. Cost: help that is invisible at the moment of need does not help. Feature adoption stays low; support tickets persist for features the tour covered. + +**Contextual-when-needed.** Tours and tooltips trigger when the user is at a moment of friction (entered a section they have not explored, clicked into a feature requiring setup, returned after a long absence, hit a feature flag's first activation). The system knows what the user knows and surfaces help at the right moment. Cost: trigger logic is meaningful work; payoff is help that compounds adoption over time. + +The litmus test. Watch a user encounter a feature for the first time. Does the help system surface useful guidance at that moment, or did it surface guidance at first-login that the user has long forgotten? If the former, contextual-when-needed. If the latter, one-and-done. If the help is competing with 14 other tooltip dots scattered across the page, tooltip-spam. + +--- + +## Trigger logic: event-based vs time-based vs state-based + +The mechanism that decides when help surfaces. + +**Event-based triggers.** Help appears in response to a user action. Clicked a feature for the first time, entered a new section, completed a flow. + +When to use. Default for most contextual help. The user did something; help responds. + +**Time-based triggers.** Help appears after time elapsed. Returned to the product after 30 days of absence; been on this page for 60 seconds without acting. + +When to use. Time can signal need (long absence; stuck on a page). Use sparingly; time alone is a noisy signal. + +**State-based triggers.** Help appears based on user state. New user vs power user; account size; feature usage history. + +When to use. When the help differs by user segment. State-based triggers personalize help. + +**Combined triggers.** Most production tour systems combine all three. Event-driven, with time and state modulating frequency and content. + +The discipline. The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. + +Detail in [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md). + +--- + +## Tour architecture: single tour vs branched vs library of micro-tours + +How help is organized. + +**Single tour.** One linear tour covering the product. Simple; rigid; rarely fits how users actually explore. + +**Branched tour.** Tour adapts based on user choices or path through the product. More relevant; more complex. + +**Library of micro-tours.** Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. Most flexible; most maintenance. + +**The choice.** Most modern systems use the micro-tour library approach. Single tours feel canned; branched tours are hard to maintain at scale; a library of contextual micro-tours matches how users actually explore. + +Detail in [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md). + +--- + +## Contextual placement: where help appears, how it dismisses + +The visual design of help. + +**Placement patterns.** + +- **Tooltip on hover.** Help appears next to the element on hover. Lightweight; familiar. +- **Spotlight overlay.** Element highlighted, help appears alongside. More prominent; more disruptive. +- **Sidebar.** Help appears in a side panel. Can persist while the user works. +- **Inline.** Help appears in the page flow. Non-disruptive; harder to dismiss. + +**Dismissal mechanics.** + +- **Click X.** Standard close. Always available. +- **Click outside.** Help dismisses if the user interacts with anything else. Implies non-modal help. +- **Auto-dismiss.** Help fades after a few seconds. Risky; users may not have read it. +- **Persistent until acted on.** Help stays until the user takes the suggested action. Powerful for guided flows; intrusive otherwise. + +**Non-intrusion principle.** Help should be findable when wanted, ignorable when not. Modal help that blocks the screen is intrusive; help that disappears too easily fails to teach. + +Detail in [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) and [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md). + +--- + +## Completion tracking and re-trigger logic + +Knowing what each user has seen, deciding when to show again. + +**Per-user state tracking.** + +- Which tours has the user completed? +- Which tours has the user dismissed? +- Which tours has the user seen but not completed? +- Time since last interaction. + +**Re-trigger logic.** + +- Completed tours: usually do not re-show. +- Dismissed tours: respect the dismissal; possibly re-show after a long delay if the feature becomes relevant again. +- Skipped tours: re-show at moments of relevance. +- Long-absent users: re-orient with abbreviated help. + +**The over-trigger trap.** Showing the same tour to users who have completed it. Trust degrades; users disable tours. + +**The under-trigger trap.** Tours never re-surfacing when the user hits the same friction again. Help fails at the moment of need. + +Detail in [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md). + +--- + +## Power-user vs new-user differentiation + +Different users need different help. + +**The principle.** Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference. + +**Differentiation signals.** + +- Feature usage history (has the user used this feature before?). +- Tenure (how long has the user been on the product?). +- Engagement frequency (active daily vs returning monthly). +- Self-reported skill level (rare; usually inferred). + +**Differentiation patterns.** + +- Power users see help only on new features. +- New users see help on the features matching their stage of exploration. +- Returning users see re-orientation help if their last session was long ago. + +**The over-helping trap.** Helping power users with features they mastered. Trust degrades. + +**The under-helping trap.** Treating all users as power users. New users miss critical help. + +Detail in [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-tour-failures.md`](references/common-tour-failures.md). + +- "Tours show but feature adoption does not improve." Help may be visually present but not contextually relevant. Audit trigger logic. +- "Users disable tours globally." The system is annoying users. Audit frequency, dismissal, and over-triggering. +- "First-login tour completion is 80 percent; feature adoption is unchanged." One-and-done pattern; tour content not retained at moment of need. +- "Tooltips appear everywhere; nobody clicks them." Tooltip-spam; rebalance to contextual triggers. +- "Tour content references features we deprecated 6 months ago." Maintenance lapse. +- "Power users complain about pop-ups for things they already know." No power-user differentiation. +- "Tours work on desktop, break on mobile." Mobile UX of help system not tested. +- "Some teams ship tours; others don't bother. Inconsistent." No tour governance; some teams build, others ignore. +- "Tours triggered correctly but users do not act on the suggestion." Help content unclear or call-to-action absent. + +--- + +## The framework: 12 considerations for product tour design + +When designing or auditing an in-product tour system, walk these 12 considerations. + +1. **The tour decision.** Are tours the right tool, or does documentation suffice? +2. **Contextual-when-needed, not tooltip-spam or one-and-done.** Help surfaces at moments of friction. +3. **Trigger logic sound.** Event-based primary, with time and state modulation. +4. **Tour architecture matches usage.** Library of micro-tours preferred for most products. +5. **Contextual placement non-intrusive.** Help findable when wanted, ignorable when not. +6. **Dismissal mechanics honest.** Standard close, click-outside dismiss, no auto-dismiss before reading. +7. **Completion tracking instrumented.** Per-user state, per-tour status. +8. **Re-trigger logic respectful.** Completed tours do not re-show; dismissed tours respected. +9. **Power-user vs new-user differentiation.** Help calibrated to user state. +10. **Mobile parity.** Help works on the devices the audience uses. +11. **Maintenance discipline.** Tours updated alongside product changes; quarterly audit. +12. **Adoption as success metric.** Not just tour completion; feature adoption is the metric that matters. + +The output of the framework is a tour system that earns the user's attention by being absent until needed, surfaces help at moments of relevance, and produces feature adoption. + +--- + +## Reference files + +- [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md) - When tours earn the build vs when documentation suffices. +- [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md) - Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. +- [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md) - Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. +- [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) - Tooltip, spotlight, sidebar, inline. Placement and visual design. +- [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md) - Per-user state, re-trigger logic, the over-trigger and under-trigger traps. +- [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md) - Differentiation signals and patterns. The over-helping and under-helping traps. +- [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md) - Dismissal mechanics. The non-intrusion principle. +- [`references/tour-anti-patterns.md`](references/tour-anti-patterns.md) - The patterns that look like tours but degrade the product. +- [`references/common-tour-failures.md`](references/common-tour-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: tours earn the user's attention by being absent until needed + +The tour systems that work as compounding assets are the ones the user does not perceive as a tour system. Help surfaces at the moment of friction; disappears when the friction passes; never piles up as visual noise. The user encounters a feature for the first time, sees a brief contextual hint, takes the suggested action, and moves on. The system did its job; the user did not have to think about the system. + +That is the bar. Below the bar are tooltip-spam (visual noise that users develop blindness to) and one-and-done (help invisible at the moment of need). Above the bar are contextual-when-needed systems where trigger logic, tour architecture, contextual placement, and re-trigger respect work together to make help feel ambient rather than imposed. + +The discipline is in the design choices. The decision to build a tour system at all, or rely on documentation. The trigger logic that decides when help surfaces. The architecture that organizes micro-tours by feature and workflow. The placement and dismissal that make help non-intrusive. The completion tracking that prevents re-showing what users already know. The power-user differentiation that respects expertise. The maintenance cadence that keeps tours in sync with the product. diff --git a/skills/interactive-product-tour/references/common-tour-failures.md b/skills/interactive-product-tour/references/common-tour-failures.md new file mode 100644 index 0000000..09a5d4d --- /dev/null +++ b/skills/interactive-product-tour/references/common-tour-failures.md @@ -0,0 +1,171 @@ +# Common tour failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Tours show but feature adoption does not improve." + +**The diagnosis.** Help may be visually present but not contextually relevant. Tour content may be unclear or call-to-action absent. + +**The cure.** Audit trigger logic (`references/trigger-logic-patterns.md`). Verify tours fire at moments of friction. Audit content; ensure tours have clear CTAs. + +--- + +## "Users disable tours globally." + +**The diagnosis.** The system is annoying users. Audit frequency, dismissal, over-triggering. + +**The cure.** Frequency caps (`references/dismissal-and-non-intrusion-patterns.md`). Per-user state tracking (`references/completion-tracking-and-re-trigger.md`). Audit cumulative exposure per session. + +--- + +## "First-login tour completion is 80 percent; feature adoption is unchanged." + +**The diagnosis.** One-and-done pattern. Tour content not retained at moment of need. + +**The cure.** Move from single first-login tour to library of contextual micro-tours. Detail in `references/tour-architecture-patterns.md`. + +--- + +## "Tooltips appear everywhere; nobody clicks them." + +**The diagnosis.** Tooltip-spam. Visual blindness has set in. + +**The cure.** Audit triggers. Remove tooltips that are not earning their place. Reserve hints for moments of friction. + +--- + +## "Tour content references features we deprecated 6 months ago." + +**The diagnosis.** Maintenance lapse. + +**The cure.** Quarterly tour audit. Tag tours by feature; deprecate tours when features deprecate. + +--- + +## "Power users complain about pop-ups for things they already know." + +**The diagnosis.** No power-user differentiation. + +**The cure.** Add feature-usage gating. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tours work on desktop, break on mobile." + +**The diagnosis.** Mobile UX of help system not tested. + +**The cure.** Mobile-first design and testing. Different placement patterns for mobile. + +--- + +## "Some teams ship tours; others don't bother. Inconsistent." + +**The diagnosis.** No tour governance. Some teams build tours, others ignore them. + +**The cure.** Tour ownership. Designate who maintains the system. Tour authoring guidelines. + +--- + +## "Tours triggered correctly but users do not act on the suggestion." + +**The diagnosis.** Help content unclear or call-to-action absent. + +**The cure.** Audit tour content. Each tour should have a clear, actionable CTA matched to the user's likely intent. + +--- + +## "Tour completion looks fine; adoption is mixed by feature." + +**The diagnosis.** Some tours work, others do not. Per-tour adoption tracking surfaces which. + +**The cure.** Per-tour adoption-lift measurement. Retire or redesign tours that do not produce adoption lift. + +--- + +## "We added more tours; user complaints went up." + +**The diagnosis.** Cumulative frequency overload. Each tour reasonable; total exposure too much. + +**The cure.** Per-session frequency caps. Audit cumulative exposure. + +--- + +## "Returning users miss new features we shipped during their absence." + +**The diagnosis.** No re-orientation help for long-absent users. + +**The cure.** Returning-user re-orientation pattern. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tour analytics broke after the last release." + +**The diagnosis.** Instrumentation drift. + +**The cure.** Verify analytics after every release. Add to deployment smoke test. + +--- + +## "Tour fires but user is mid-task; they abandon." + +**The diagnosis.** Trigger logic does not respect ongoing tasks. + +**The cure.** Detect mid-task state; defer tour. Trigger at moments of natural pause. + +--- + +## "We A/B tested tour content; adoption did not move." + +**The diagnosis.** Content was not the issue. Could be trigger, audience, or feature design. + +**The cure.** Test variables that matter. Trigger logic, audience targeting, feature design itself. Sometimes the tour cannot save a bad feature. + +--- + +## "Tours are clear; adoption is good; users still file support tickets." + +**The diagnosis.** Tours covered the feature but not the edge cases. Documentation is needed for depth. + +**The cure.** Tours plus docs. Tours teach the common case; docs cover edge cases. + +--- + +## "Power users say tours feel patronizing." + +**The diagnosis.** Copy tone wrong; or tours fire on features power users have mastered. + +**The cure.** Match copy to brand voice (treat users as adults). Add power-user differentiation. + +--- + +## "Tour platform broke after last platform update." + +**The diagnosis.** Tour platform changes (Userpilot/Pendo/Appcues SDK updates) can break existing tours. + +**The cure.** Test after platform updates. Have a rollback plan. + +--- + +## The pattern across failures + +Most tour failures fall into one of three patterns. + +**Pattern 1: The tour does not surface at the right moment.** Tooltip-spam, one-and-done, over-trigger, under-trigger. The fix is trigger logic. + +**Pattern 2: The tour does not match the audience or device.** No power-user differentiation, mobile-broken, patronizing. The fix is matching to user state. + +**Pattern 3: The tour decays.** Stale references, broken triggers, deprecated features still tour-covered. The fix is maintenance. + +The metric pattern: tour failures often look fine on completion alone. The signal is in feature adoption, support ticket reduction, user retention. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (trigger, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md b/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md new file mode 100644 index 0000000..fd7a8d5 --- /dev/null +++ b/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md @@ -0,0 +1,203 @@ +# Completion tracking and re-trigger + +Per-user state, re-trigger logic, the over-trigger and under-trigger traps. + +Knowing what each user has seen, deciding when to show again. Done well, tours feel ambient; done poorly, tours either re-show endlessly or fail to re-surface when needed. + +--- + +## The state-aware principle + +The tour system should know what each user has seen, completed, dismissed, and ignored. Decisions about whether to show, re-show, or skip a tour should be based on this state. + +**The win.** A user who completed the advanced filtering tour does not see it again. A user who skipped it might see it again at a moment of more relevance. A user who dismissed all tours sees nothing. + +**The fail.** Users see the same tour every time they log in. Users who dismissed tours globally still get them. Users who would benefit from a re-shown tour at the right moment never see it again. + +The discipline. Track state per user per tour; use state to inform re-trigger logic. + +--- + +## Per-user state tracking + +What to track. + +**Per tour, per user.** + +- Has the user seen this tour? +- Did they complete it? +- Did they dismiss it without completing? +- When did they last interact with it? +- Did they take the suggested action after the tour? + +**Globally per user.** + +- Are tours globally enabled or disabled? +- What is their tenure on the product? +- What user state attributes apply (plan, role, segment)? + +**Aggregate.** + +- Tour completion rate. +- Tour dismissal rate. +- Action-taken-after-tour rate. + +The data informs both individual and system decisions. + +--- + +## Re-trigger logic + +When to re-show. + +**Completed tours.** + +- Default: do not re-show. The user got what they needed. +- Exception: re-show if the feature changed materially. The tour is no longer the same tour. + +**Dismissed tours.** + +- Respect the dismissal. +- If the feature becomes relevant again much later (60+ days, significant feature change), consider gentle re-surfacing with respect. + +**Skipped tours (saw but did not complete).** + +- Re-trigger at moments of more relevance. The user did not commit; help may land better contextually. +- After 2-3 skip events, treat like dismissed; respect the pattern. + +**Ignored tours (saw but did not interact).** + +- Treat similarly to skipped. +- Re-trigger at moments of higher friction. + +--- + +## The over-trigger trap + +Showing the same tour to users who have completed it. + +**The pattern.** No completion tracking; tours fire on every page load. + +**The signal.** Users complain about repeat tours; users disable tours globally; trust drops. + +**The cost.** The tour system loses credibility. Users who would have benefited from new tours dismiss them along with the over-triggered repeats. + +**The cure.** Track completion. Tours that have been completed do not re-fire (with rare exceptions for material feature changes). + +--- + +## The under-trigger trap + +Tours never re-surfacing when the user hits the same friction again. + +**The pattern.** First-login tours that show once and never come back. + +**The signal.** Users hit the same feature later; have forgotten the tour; ask support; the help failed at the moment of need. + +**The cost.** The tour system was decorative; the help did not compound adoption. + +**The cure.** Re-trigger logic at moments of need. Even completed tours can re-surface in abbreviated form when the user hits the relevant feature months later. + +--- + +## Re-trigger conditions + +Specific conditions that warrant re-triggering. + +**Material feature change.** The feature the tour covers has changed enough that the tour content is materially different. Re-show with "this feature has changed; here is what is new." + +**Long absence.** User returned after 60+ days; subset of tours can re-surface as re-orientation. + +**Plan change.** User upgraded plan; tours for previously-locked features become relevant. + +**Role change.** User's role changed (e.g., promoted to admin); admin-relevant tours become applicable. + +**Time-based decay.** Some tours benefit from periodic refreshers (rare; use carefully). + +The discipline. Each re-trigger condition should be deliberate, not default. + +--- + +## Frequency limits + +Even thoughtful re-triggers can over-fire. + +**Per-tour frequency.** + +- Default: never re-show after completion. +- Re-trigger conditions: maximum once per condition met. + +**Per-session frequency.** + +- Maximum tours per session (cumulative across all tours): often 1-3. +- Beyond that, defer additional tours to next session. + +**Per-week frequency.** + +- Some users encounter many features in a week; the system should not fire 20 tours. +- Cap weekly tour exposure to maintain attention. + +The discipline. Audit cumulative tour exposure per session and per week. Individual tour decisions are not enough. + +--- + +## Dismiss vs disable distinction + +Two different signals. + +**Dismiss.** User closed a specific tour. Tells the system "this tour is not for me right now." + +**Disable.** User turned off all tours via settings. Tells the system "I do not want any tours." + +**Treatment.** + +- Dismiss: respect for that tour; consider re-trigger at moments of higher relevance. +- Disable: respect globally; do not show any tours. + +**The disable-respect failure.** Some tour systems override the global disable for "important" tours. This breaks user trust. Disable should mean disable (compliance triggers excepted, with disclosure). + +--- + +## Tour analytics for completion + +Track what each tour produces. + +**Per-tour metrics.** + +- Trigger rate (how often does this tour fire?). +- Completion rate (of users who saw it, how many completed?). +- Dismissal rate (how many dismissed without completing?). +- Action-taken rate (how many took the suggested action after?). +- Adoption lift (do users who saw the tour adopt the feature at higher rates than those who did not?). + +The metrics inform whether the tour is earning its place. + +**The adoption-lift question.** If users who saw the tour adopt the feature at the same rate as users who did not, the tour is not adding value. Either redesign or retire. + +--- + +## Common completion-tracking failures + +**No tracking.** Tours fire repeatedly; users complain. + +**Tracking exists but ignored.** State stored but trigger logic does not use it; over-trigger persists. + +**Stale state.** User dismissed tour 6 months ago; product changed; tour does not re-show despite being newly relevant. + +**Cross-device gaps.** State tracked per device; user switches device and re-encounters every tour. + +**Disable not respected.** Global disable ignored for "important" tours; user trust collapses. + +**No adoption-lift measurement.** Tours track completion but not whether they produced adoption; weak tours persist. + +**Re-trigger overzealous.** Re-trigger conditions fire too liberally; users see tours they completed re-appear without justification. + +--- + +## Methodology-level choices that stay in the public skill + +The state-aware principle. Per-user state tracking. Re-trigger logic. The over-trigger and under-trigger traps. Re-trigger conditions. Frequency limits. Dismiss vs disable distinction. Tour analytics. Common failures. + +## Implementation choices that stay internal + +Specific tracking implementations. Specific re-trigger logic per tour. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/skills/interactive-product-tour/references/contextual-placement-patterns.md b/skills/interactive-product-tour/references/contextual-placement-patterns.md new file mode 100644 index 0000000..9887927 --- /dev/null +++ b/skills/interactive-product-tour/references/contextual-placement-patterns.md @@ -0,0 +1,245 @@ +# Contextual placement patterns + +Tooltip, spotlight, sidebar, inline. Placement and visual design. + +The placement decides whether help feels ambient or imposed. Done well, help is findable when wanted, ignorable when not. Done poorly, help blocks the user or disappears before they read it. + +--- + +## The non-imposition principle + +Help should be findable when wanted, ignorable when not. Help that demands the user's full attention is help that costs trust. + +**The win.** A tooltip appears next to a feature, visible but not blocking. The user reads if interested, dismisses or ignores if not. The interaction is brief and respectful. + +**The fail.** A modal overlay blocks the entire screen, demanding the user click to dismiss before continuing. The user loses momentum; resents the interruption. + +The discipline. Match placement intensity to help importance. Most help should be lightweight. + +--- + +## Pattern A: Tooltip on hover + +Help appears next to the element on hover. + +**How it works.** + +- User hovers over the element. +- Tooltip appears next to it. +- Tooltip dismisses when hover ends. + +**Strengths.** + +- Lightweight. +- Familiar pattern. +- Non-intrusive. + +**Weaknesses.** + +- Mouse-only by default; keyboard users may miss. +- Limited content (cannot fit much in a tooltip). +- Dismisses too easily for content the user needs to read. + +**When to use.** Brief hints, definitions, quick clarifications. Not for multi-step guidance. + +--- + +## Pattern B: Spotlight overlay + +Element highlighted; help appears alongside. + +**How it works.** + +- The relevant element is highlighted (often via dimmed surrounding area). +- A help card appears nearby explaining the element. +- User clicks "Got it" or similar to dismiss. + +**Strengths.** + +- More prominent; harder to miss. +- Can fit more content than tooltip. +- Good for feature-specific tours. + +**Weaknesses.** + +- More disruptive. +- Dimming the page can frustrate users who wanted to do something else. + +**When to use.** Feature-specific tours, the kind of help that warrants the user's full attention briefly. + +--- + +## Pattern C: Sidebar + +Help appears in a side panel. + +**How it works.** + +- Help opens in a panel (often right side of screen). +- User can read while the main content remains accessible. +- Panel persists until dismissed. + +**Strengths.** + +- Persistent reference; user can refer back. +- Does not block main content. +- Can fit substantial content. + +**Weaknesses.** + +- Takes screen space. +- May not work on mobile. + +**When to use.** When the help is reference material the user may want to consult while working. Multi-step guides where the user is doing the steps in the main content. + +--- + +## Pattern D: Inline + +Help appears in the page flow. + +**How it works.** + +- Help is embedded directly in the page content. +- Often appears as a banner, inline hint, or contextual section. +- User scrolls past or interacts with it. + +**Strengths.** + +- Non-disruptive. +- Always findable (does not appear and disappear). +- Works well on mobile. + +**Weaknesses.** + +- Can be missed entirely. +- Adds page length. + +**When to use.** Empty states, contextual hints that should always be visible, supplementary information that some users want. + +--- + +## Pattern E: Modal overlay + +Help blocks the screen until dismissed. + +**How it works.** + +- A full-screen or large modal appears. +- User must dismiss to continue. + +**Strengths.** + +- Highest visibility. +- Forces attention on critical messages. + +**Weaknesses.** + +- Most disruptive. +- Easily abused; produces annoyance. +- Should be reserved for critical messages. + +**When to use.** Compliance-critical messages, terms updates, data-loss warnings. Almost never for routine help. + +--- + +## Placement choice by content type + +What pattern fits what content. + +**Brief hints (1 sentence):** tooltip on hover. + +**Feature explanations (2-3 sentences plus example):** spotlight overlay. + +**Multi-step guides (3-5 steps):** spotlight overlay sequence or sidebar. + +**Reference material (multiple paragraphs):** sidebar. + +**Empty states and contextual hints:** inline. + +**Compliance / critical messages:** modal overlay. + +The match between content and placement is part of the design discipline. + +--- + +## Visual design discipline + +How help looks. + +**Visual weight.** + +- Tooltips: light, almost invisible until needed. +- Spotlights: medium; visible but not aggressive. +- Modals: heavy; demand attention. + +**Brand consistency.** + +- Help styling matches the product's design system. +- Tone matches brand voice. +- Colors should not feel "this is a tour"; they should feel like part of the product. + +**Iconography.** + +- Help often uses small icons (info, lightbulb) to signal "this is help." +- Icons should be consistent across help surfaces. + +--- + +## Animation discipline + +How help appears and disappears. + +**Subtle animation.** Fade in, slight slide. Reinforces transition without distracting. + +**Aggressive animation.** Bounce, attention-grabbing motion. Useful sparingly; abused, becomes annoyance. + +**No animation.** Instant appear/disappear. Snappy; some users prefer it. + +**Prefers-reduced-motion.** Respect user system preferences. No bouncing for users who configured reduced motion. + +--- + +## Mobile placement considerations + +Mobile changes everything. + +**Tooltips.** Hover does not exist on mobile; tooltips need touch alternative. Often replaced with tap-to-show. + +**Spotlights.** Spotlight overlays need to fit mobile screens. Smaller content; fewer steps. + +**Sidebars.** Often impossible on mobile; replaced with full-screen modals or omitted. + +**Inline.** Works well on mobile. Usually the safest mobile-first pattern. + +**Modal overlays.** Take over the screen on mobile; even more disruptive than on desktop. + +The mobile discipline. Test help on actual devices. Mobile help should be lighter and more inline-oriented. + +--- + +## Common placement failures + +**Wrong pattern for content.** Modal for a brief hint; tooltip for a multi-step guide. + +**Visual weight wrong.** Aggressive animation for routine help; invisible animation for critical messages. + +**Mobile broken.** Tooltips that do not work on touch; sidebars that take over the mobile screen. + +**Brand-inconsistent.** Help styled differently from the rest of the product; feels bolted on. + +**Animation distracting.** Bouncing tooltips that draw the eye constantly. + +**No reduced-motion respect.** Animations fire regardless of system preferences. + +**Help blocks the action it is teaching.** Spotlight overlays the very element the user needs to click. + +--- + +## Methodology-level choices that stay in the public skill + +The non-imposition principle. Patterns A through E. Placement choice by content type. Visual design discipline. Animation discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific placement designs for specific tours. Specific tooling. Specific brand styles. The team's mobile testing benchmarks. These vary by team and product. diff --git a/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md b/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md new file mode 100644 index 0000000..ea74d3c --- /dev/null +++ b/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md @@ -0,0 +1,229 @@ +# Dismissal and non-intrusion patterns + +Dismissal mechanics. The non-intrusion principle. + +How tours close, how they respect the user's path, how they avoid becoming friction. The discipline that makes tours feel ambient rather than imposed. + +--- + +## The non-intrusion principle + +Help should be findable when wanted, ignorable when not. Tours that demand the user's full attention earn user resentment quickly. + +**The win.** A tooltip appears next to a feature. The user reads, dismisses, moves on. Two seconds total. The interaction was brief. + +**The fail.** A modal blocks the screen. The user has to read or dismiss before continuing. The interruption costs momentum and trust. + +The discipline. Match intensity to importance. Most tours should be light. + +--- + +## Dismissal patterns + +How tours close. + +**Pattern A: Click X.** + +How it works. A standard close button (often X or "Close") dismisses the tour. + +When to use. Default. Always available; users always know how to dismiss. + +**Pattern B: Click outside.** + +How it works. Tour dismisses if the user clicks anywhere outside the help element. + +When to use. For non-modal tooltips; lightweight help. + +**Pattern C: Auto-dismiss.** + +How it works. Tour fades after a few seconds of no interaction. + +When to use. Sparingly. Risky because users may not have read it. Best for very brief notifications. + +**Pattern D: Persistent until acted on.** + +How it works. Tour stays until the user takes the suggested action. + +When to use. For guided flows where the user is meant to perform the action. Discouraged for routine help (intrusive). + +**Pattern E: Dismiss-and-don't-show-again.** + +How it works. Dismissing offers an explicit "don't show me this again" option. + +When to use. For tours users may want to never see again (low-priority recurring tips). + +--- + +## Dismiss prominence + +How visible the dismiss is. + +**Equal prominence.** Dismiss and primary action have similar visual weight. + +**Primary-prominent.** Primary action ("Got it" or "Try it") is bold; dismiss is secondary. + +**Hidden dismiss.** Dismiss requires clicking outside or finding a small X. Discouraged; users feel trapped. + +The discipline. Dismiss should be findable in under 2 seconds without searching. + +--- + +## Click-outside dismissal + +When the user clicks elsewhere, what happens. + +**Pattern: Dismiss fully.** Tour closes; user continues with what they were doing. + +**Pattern: Pause and resume.** Tour pauses; if the user comes back, it resumes. Rarely the right choice; introduces unpredictability. + +**Pattern: Block click.** Tour stays; click outside is captured but does not pass through. Most intrusive; reserved for compliance. + +The discipline. Click-outside should usually dismiss. Users want to continue; let them. + +--- + +## Auto-dismiss design + +When help fades automatically. + +**Time-based.** Help disappears after N seconds. + +- 3-5 seconds: too short for anything but a single sentence. +- 8-12 seconds: reasonable for short help. +- 15+ seconds: probably too long; users have moved on. + +**Action-based.** Help disappears when the user takes the suggested action. + +- Useful for guided steps. +- Risk: user does something else; help disappears confusingly. + +**Hover-based.** Help disappears when hover ends. + +- Tooltip default. +- Brief by nature. + +**The auto-dismiss risk.** Users who needed the help may have been reading slowly; auto-dismiss takes the help away before they finish. + +The cure. Either give enough time, or let users explicitly dismiss. + +--- + +## Frequency caps for non-intrusion + +How many tours can fire in a session. + +**Per-session caps.** + +- Maximum tours per session: 1-3 typical. +- Beyond that, additional tours defer to next session. + +**Per-page caps.** + +- Maximum tours per page load: usually 1. +- Multiple tooltips on a page can stack; visual noise climbs. + +**Per-day caps.** + +- For users who use the product all day, daily caps prevent fatigue. + +The discipline. Cumulative exposure matters as much as individual tour quality. + +--- + +## Spacing and animation + +How tours appear and disappear. + +**Subtle entry.** Fade in; slight slide. Reinforces transition without distracting. + +**Aggressive entry.** Bounce, pulse, shake. Gets attention; abused, becomes annoyance. + +**Subtle exit.** Fade out; quick. + +**The animation discipline.** Subtle entries and exits. Save aggressive animation for rare attention-needed moments. + +--- + +## Spatial respect + +Where the help appears matters. + +**Avoid blocking the action.** Help should not cover the element it is teaching. + +**Avoid blocking critical content.** Help should not obscure the user's primary work area. + +**Avoid covering navigation.** Help that hides nav prevents the user from leaving. + +**Allow scroll.** If the user needs to scroll while help is visible, scroll should still work. + +--- + +## Help dismissal preserves user state + +When the user dismisses, what is preserved. + +**Form data:** preserved. Dismissing help should not reset form inputs. + +**Page state:** preserved. Dismissing help should not navigate away. + +**User progress:** preserved. Dismissing help should not undo work. + +**The state-loss failure.** Help dismissal that resets the page or loses inputs costs trust catastrophically. + +--- + +## Power-user dismissal patterns + +Power users want to dismiss faster. + +**Keyboard dismissal.** ESC closes help. Power users use keyboard. + +**Click-anywhere-to-dismiss.** Allows fast dismissal without targeting the X. + +**Settings to disable globally.** Allows opting out of all tours. + +The discipline. Power users should be able to dismiss in under a second. + +--- + +## New-user dismissal patterns + +New users may need more time. + +**Persistent tooltips for guided flows.** Help stays visible during the flow it is teaching. + +**Linked help.** Dismissing help leaves a way to find it again ("Need help? Check our guides"). + +**Contextual reminders.** Help re-surfaces if the user struggles with the same area later. + +The discipline. New users should not lose access to help permanently from a single dismissal. + +--- + +## Common dismissal failures + +**Dismiss too prominent.** User dismisses before reading; misses the help. + +**Dismiss hidden.** User cannot find the dismiss; feels trapped. + +**Auto-dismiss too short.** Help disappears before reading; user does not know what was there. + +**Dismiss does not respect.** Tour reappears after dismiss. + +**Dismiss loses state.** Form inputs reset; user loses work. + +**No keyboard dismiss.** Power users cannot dismiss quickly. + +**Modal blocks until dismissed.** User cannot continue without engaging. + +**Help blocks the action.** Spotlight covers the very element being taught. + +--- + +## Methodology-level choices that stay in the public skill + +The non-intrusion principle. Patterns A through E for dismissal. Dismiss prominence. Click-outside dismissal. Auto-dismiss design. Frequency caps. Spacing and animation. Spatial respect. State preservation on dismiss. Power-user vs new-user dismissal patterns. Common failures. + +## Implementation choices that stay internal + +Specific dismissal designs for specific tours. Specific animation timings. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md b/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md new file mode 100644 index 0000000..646a365 --- /dev/null +++ b/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md @@ -0,0 +1,204 @@ +# Power-user vs new-user patterns + +Differentiation signals and patterns. The over-helping and under-helping traps. + +Different users need different help. The discipline is to know which user is which and tailor the help system to their state. + +--- + +## The state-respect principle + +Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference and respect both. + +**The win.** A power user encounters a newly-shipped feature; sees a brief tour. A new user encounters a feature for the first time; sees the same tour. A power user encounters a feature they have used 50 times; sees nothing. + +**The fail.** Both users see the same tour every time. Power users disable tours; new users miss critical help when they need it most. + +The discipline. Tour visibility should depend on user state, not user category alone. + +--- + +## Differentiation signals + +What lets the system know which user is which. + +**Feature usage history.** Has the user used this feature before? + +- Most reliable signal. +- Tracks per-feature, per-user state. +- Updates in real time as the user uses the feature. + +**Tenure on the product.** How long has the user been a customer? + +- Approximate signal; new accounts vs old accounts. +- Useful when feature usage data is missing. + +**Engagement frequency.** Daily active vs returning monthly. + +- Active users tend to know the product better. +- Returning users may need re-orientation. + +**Plan or role.** Free vs paid; admin vs end-user; user vs viewer. + +- Different roles use different feature sets. +- Plan changes can unlock new features. + +**Self-reported skill level.** Rare; usually inferred. + +- Some products ask during signup. +- Useful but unreliable; people self-assess inaccurately. + +The discipline. Combine signals. Single signals are noisy. + +--- + +## Differentiation patterns + +How to surface different help. + +**Pattern A: Feature-usage gating.** + +How it works. Each tour has a "show only if user has not used this feature" condition. Power users with usage history skip; new users see. + +When to use. Default for feature-specific tours. Most reliable. + +**Pattern B: Tenure-based filtering.** + +How it works. New users (under 7 days) see all relevant tours. Established users (over 30 days) see tours only for newly-shipped features. + +When to use. When feature usage data is incomplete or unavailable. + +**Pattern C: Engagement-based modulation.** + +How it works. Daily active users see fewer tours; returning monthly users may see re-orientation help. + +When to use. When engagement frequency predicts product knowledge. + +**Pattern D: Role-based differentiation.** + +How it works. Admins see admin-specific tours; end-users see end-user tours. + +When to use. When the product has materially different surfaces for different roles. + +**Pattern E: Newly-shipped feature highlighting.** + +How it works. New feature ships; tour fires for ALL users (power users and new users) because everyone is new to this feature. + +When to use. Feature launches. Power users benefit from the tour just as much as new users for this case. + +--- + +## The over-helping trap + +Helping power users with features they have mastered. + +**The pattern.** Tours fire regardless of user state; power users see tours they do not need. + +**The signal.** Power user complaints; tour disable rate climbs; trust degrades. + +**The cost.** Power users disable tours globally; the system loses access to them for genuinely new features. + +**The cure.** Add feature-usage gating. Respect tenure and engagement signals. + +--- + +## The under-helping trap + +Treating all users as power users. + +**The pattern.** Tours fire only on first-login or never. New users miss help when they need it. + +**The signal.** Feature adoption stays low among new users; support tickets persist for tour-covered features. + +**The cost.** New users churn or stay underactivated. + +**The cure.** Tours fire when users encounter features for the first time, regardless of how long they have been on the product. + +--- + +## Returning-user re-orientation + +Long-absent users may need re-orientation. + +**The pattern.** User has not logged in for 60+ days. On return, abbreviated re-orientation help surfaces. + +**Design.** + +- Brief (2-3 steps max). +- Highlights what changed in the user's absence. +- Easy to dismiss for users who do not need it. + +**The over-helping risk.** Users returning from a 1-week absence do not need re-orientation. Set the absence threshold appropriately. + +--- + +## Newly-shipped feature handling + +When a feature ships, the help system has new content. + +**The pattern.** A new tour ships with the feature. Trigger fires for all users (power and new alike) because everyone encounters this feature for the first time. + +**Discipline.** + +- Tag the tour as "new feature." +- Fire on first encounter regardless of user tenure. +- After most users have seen it (e.g., 80 percent of monthly active users), the tour can transition to standard new-user-only logic. + +**Power-user respect.** Even new feature tours should be brief. Power users will read what they need; do not slow them with five-step explanations. + +--- + +## Plan or role change handling + +User state can change. + +**Plan upgrade.** User moves from free to paid; new features become available; relevant tours become applicable. + +**Role change.** User promoted to admin; admin tours become applicable. + +**The discipline.** Re-evaluate tour eligibility on state change. Plan upgrade triggers a "you have new features available" re-orientation. + +--- + +## Inferred vs asked differentiation + +When to ask the user vs when to infer. + +**Ask sparingly.** Asking adds friction; users tire of being categorized. + +**Infer when possible.** Behavioral signals usually outperform self-report. + +**When to ask.** + +- Onboarding (use case, role). +- Major plan changes that affect tour eligibility. + +**When not to ask.** + +- After onboarding; let behavior speak. + +--- + +## Common power-user vs new-user failures + +**No differentiation.** All users see all tours; over-helping power users. + +**Differentiation only by tenure.** New accounts vs old; misses that some new accounts have power users (came from competitor) and some old accounts have casual users. + +**No re-orientation for returning users.** Users who left 90 days ago re-encounter as if first-time; they remember enough to skip re-orientation; but the help fails when they hit a changed feature. + +**Newly-shipped features not flagged.** Tour does not surface for power users who have used adjacent features; they miss the new capability. + +**Plan upgrade not triggering re-evaluation.** User upgrades; new features available; tours for those features do not surface. + +**Inferring poorly.** Inference logic mistakes user state; help is wrong for the user. + +--- + +## Methodology-level choices that stay in the public skill + +The state-respect principle. Differentiation signals (5 signals). Patterns A through E. The over-helping and under-helping traps. Returning-user re-orientation. Newly-shipped feature handling. Plan or role change handling. Inferred vs asked differentiation. Common failures. + +## Implementation choices that stay internal + +Specific differentiation rules for specific products. Specific signals weighted by team. The team's plan and role mapping. These vary by team and product. diff --git a/skills/interactive-product-tour/references/tour-anti-patterns.md b/skills/interactive-product-tour/references/tour-anti-patterns.md new file mode 100644 index 0000000..752725d --- /dev/null +++ b/skills/interactive-product-tour/references/tour-anti-patterns.md @@ -0,0 +1,224 @@ +# Tour anti-patterns + +The patterns that look like tours but degrade the product. Easy to ship; the cost shows up in feature adoption, user trust, and brand reputation. + +--- + +## The tooltip-spam tour + +The pattern. Every button, link, and feature has a "click for tour" hint or pulsing dot. + +The signal. Users develop blindness to the dots; click rates collapse; tour completion rates near zero. + +The cost. The visual clutter degrades the product; users learn to ignore all tooltips, including useful ones. + +The cure. Audit triggers. Reserve hints for moments of genuine friction. Detail in `references/trigger-logic-patterns.md`. + +--- + +## The one-and-done tour + +The pattern. A single first-login tour. Never re-surfaces. + +The signal. Users skip or skim; help unavailable at moments of later need. + +The cost. Feature adoption suffers; support tickets persist for tour-covered features. + +The cure. Library of micro-tours triggered contextually. Detail in `references/tour-architecture-patterns.md`. + +--- + +## The mega-tour + +The pattern. A single tour with 25 steps covering the whole product. + +The signal. High abandonment mid-tour; high skip rate; activation does not lift. + +The cost. Tutorial-overload pattern applied to tours. Users abandon; help fails. + +The cure. Break into micro-tours, each tied to a specific feature. + +--- + +## The over-trigger tour + +The pattern. Tour fires on every page load; no completion tracking. + +The signal. Repeat exposure; user complaints; tours globally disabled. + +The cost. Tour system loses credibility. + +The cure. Per-user state tracking. Completed tours do not re-fire. + +--- + +## The under-trigger tour + +The pattern. Tour fires only on first-login. Users hit the same friction later; help does not return. + +The signal. Specific features show low adoption among long-tenured users; help failed at the moment of need. + +The cost. The tour system was decorative for everyone after their first session. + +The cure. Re-trigger logic at moments of relevance, even for tours seen long ago. + +--- + +## The dismissive-of-disable tour + +The pattern. User disabled all tours globally; system fires tours anyway because they are deemed important. + +The signal. User trust collapses; explicit complaints. + +The cost. The tour system overrode the user's clear preference; trust does not recover quickly. + +The cure. Respect the global disable. Use compliance-only triggers for legally required messages, with clear disclosure. + +--- + +## The blocks-the-action tour + +The pattern. Spotlight overlay covers the element it is teaching; user cannot click through. + +The signal. User confusion; users dismiss and abandon the action they were about to take. + +The cost. The tour failed at its job; the user did not learn the feature because the tour blocked the feature. + +The cure. Spotlight placement that highlights without blocking. The user should be able to take the action while the help is visible. + +--- + +## The auto-dismiss-too-fast tour + +The pattern. Help fades after 3 seconds. + +The signal. Users complain about help disappearing before they read it. + +The cost. The help is technically present but functionally absent. + +The cure. Either longer auto-dismiss (8-12 seconds), or let users dismiss explicitly. + +--- + +## The validation-strict tour + +The pattern. Tour requires the user to take a specific action to proceed; the user takes a different valid path. + +The signal. Tour gets stuck; user abandons. + +The cost. Forced linearity penalizes users who explore. + +The cure. Tour either accepts multiple valid paths or dismisses if the user explores elsewhere. + +--- + +## The brand-inconsistent tour + +The pattern. Tour styling looks different from the rest of the product. Generic platform styling rather than brand-aligned. + +The signal. Users perceive the tour as bolted on; brand consistency suffers. + +The cost. The product feels less polished; tours feel like a separate system. + +The cure. Custom-styled tours matching the product's design system. + +--- + +## The mobile-broken tour + +The pattern. Tour designed for desktop; breaks on mobile. + +The signal. Mobile completion rates much lower; mobile-specific complaints. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. Detail in `references/contextual-placement-patterns.md` (mobile section). + +--- + +## The unmaintained tour + +The pattern. Tour built once; product evolved; tour content references deprecated features. + +The signal. Users hit broken steps; references that no longer apply. + +The cost. Trust degrades; users ignore tours expecting them to be wrong. + +The cure. Quarterly maintenance. Product changes trigger tour updates as part of the change. + +--- + +## The orphan-tour + +The pattern. Tour exists for a feature that was deprecated 6 months ago; nobody removed it. + +The signal. Tour fires; clicks lead to 404 or to a removed UI; users confused. + +The cost. The tour points to nothing; user trust degrades. + +The cure. Tour deprecation alongside feature deprecation. + +--- + +## The fake-engagement tour + +The pattern. Tour optimizes for click-through rate by making the action button huge and the dismiss tiny. + +The signal. Click-through rate looks high; downstream feature adoption does not match. + +The cost. Surface metrics look fine; real adoption does not improve. + +The cure. Track adoption as the metric; design honestly. Click-through alone is not enough. + +--- + +## The interrupting tour + +The pattern. Tour fires while the user is mid-task; takes over the screen. + +The signal. User abandonment spikes at the interruption; users complain. + +The cost. The tour cost the user a task completion. + +The cure. Tour triggers should respect ongoing tasks. Detect mid-task state; defer. + +--- + +## The patronizing-copy tour + +The pattern. Tour copy talks down to users. "Welcome! Let me show you around. Here's how to do something simple." + +The signal. Power users dismiss; new users feel patronized. + +The cost. Tone hurts trust. + +The cure. Match copy to brand voice. Treat users as adults. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active tour, looking for these anti-patterns. + +**Audit questions per tour.** + +- Is the tour triggered relevantly (anti-pattern check: tooltip-spam, over-trigger, under-trigger)? +- Does the tour respect dismissal (anti-pattern check: dismissive-of-disable)? +- Does the tour block the action it teaches (anti-pattern check: blocks-the-action)? +- Is auto-dismiss timed appropriately (anti-pattern check: auto-dismiss-too-fast)? +- Does the tour match the brand's design (anti-pattern check: brand-inconsistent)? +- Does the tour work on mobile (anti-pattern check: mobile-broken)? +- Is the tour current (anti-pattern check: unmaintained, orphan)? +- Is adoption tracked (anti-pattern check: fake-engagement)? + +**The retire decision.** Anti-pattern tours often warrant retirement or redesign. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/interactive-product-tour/references/tour-architecture-patterns.md b/skills/interactive-product-tour/references/tour-architecture-patterns.md new file mode 100644 index 0000000..9048eaf --- /dev/null +++ b/skills/interactive-product-tour/references/tour-architecture-patterns.md @@ -0,0 +1,225 @@ +# Tour architecture patterns + +Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. + +The architecture is how help is organized at the system level. Bad architecture produces canned tours that nobody finishes; good architecture matches how users actually explore. + +--- + +## The exploration-fit principle + +The architecture should match how users actually move through the product. Linear architecture fits linear products; library architecture fits exploration. + +**The win.** A library of focused micro-tours, each tied to a specific feature, triggered contextually as users encounter features. Each tour is small (2-4 steps); each fires only at relevant moments. Users feel helped without feeling herded. + +**The fail.** A single linear tour covering 25 features in sequence. Users who care about feature 17 get nothing relevant in the first 16 steps; they skip everything; help fails. + +The discipline. Match architecture to exploration patterns; do not impose linearity on non-linear products. + +--- + +## Pattern A: Single tour + +One linear tour covering the product. + +**How it works.** + +- Tour starts at first-login or via a "Take the tour" prompt. +- Steps cover features in a defined order. +- User completes or skips entirely. + +**Strengths.** + +- Simple to design and maintain. +- Predictable for users. + +**Weaknesses.** + +- Linear; rarely fits how users explore. +- Can become tutorial-overload if comprehensive. +- One-and-done; rarely re-shown. + +**When to use.** Very simple products with linear flows. Rarely the right answer for production tour systems. + +--- + +## Pattern B: Branched tour + +Tour adapts based on user choices or path. + +**How it works.** + +- User selects role/use case at start. +- Subsequent steps adapt based on the selection. +- Different users effectively complete different tours. + +**Strengths.** + +- More relevant than single tour. +- Personalized. + +**Weaknesses.** + +- Complex to build and maintain. +- Hard to instrument cleanly. +- Still linear in execution. + +**When to use.** When the audience splits into 2-3 clear segments with different exploration paths. Use sparingly. + +--- + +## Pattern C: Library of micro-tours + +Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. + +**How it works.** + +- Many small tours (2-4 steps each). +- Each tour is tied to a specific feature, workflow, or moment. +- Trigger logic decides when each fires. +- Users see only the tours relevant to their current exploration. + +**Strengths.** + +- Matches how users actually explore. +- Each micro-tour is small enough to complete. +- Re-trigger logic can re-surface as features become relevant. +- Most flexible. + +**Weaknesses.** + +- Most maintenance. +- Trigger logic complexity. +- Requires per-tour completion tracking. + +**When to use.** Default for production tour systems. Most modern products benefit from this approach. + +--- + +## Pattern D: Hybrid + +Combining patterns. Often a brief opening tour plus a library of micro-tours for ongoing help. + +**How it works.** + +- First-login: brief 3-4 step orientation tour (single). +- Ongoing: library of micro-tours triggered contextually. + +**Strengths.** + +- Orientation for new users + ongoing help for everyone. +- Combines the simplicity of single tour for the moment of arrival with the flexibility of library for the ongoing relationship. + +**Weaknesses.** + +- Two systems to maintain. + +**When to use.** When new users genuinely benefit from an opening orientation AND ongoing contextual help is also valuable. + +--- + +## Architecture choice criteria + +Which pattern fits which product. + +**Use single tour when:** + +- Product is genuinely linear. +- Audience expects guided sequence. +- Maintenance capacity is limited. + +**Use branched tour when:** + +- Audience splits into 2-3 distinct segments. +- Each segment has a different linear path. + +**Use library of micro-tours when:** + +- Product has many features users explore non-linearly. +- Audience is segmented in many ways. +- Maintenance capacity supports many tours. + +**Use hybrid when:** + +- New-user orientation matters AND ongoing help also matters. + +The simplest architecture that fits the product is usually the best choice. + +--- + +## Micro-tour discipline + +Each micro-tour should be small. + +**Size guideline.** 2-4 steps per micro-tour. + +**Why small.** + +- Completable in under a minute. +- Easy to maintain. +- Targeted to a specific feature or moment. +- Less likely to be skipped. + +**Anti-pattern.** Micro-tours that grow into 8-10 steps lose their micro nature; they become single tours that happen to be triggered contextually. Re-scope. + +--- + +## Tour tagging and organization + +When you have a library, organize it. + +**Tagging axes.** + +- Feature (which feature the tour covers). +- Workflow (which user workflow the tour fits in). +- User type (new, power, returning). +- Plan (free, paid, enterprise). + +**Why tagging matters.** + +- Trigger logic can use tags to decide which tour fires. +- Maintenance can find tours by feature when the feature changes. +- Audit can identify orphan tours not tied to current features. + +--- + +## Tour deprecation + +When features change, tours need to retire or update. + +**Retire when:** + +- Feature was deprecated; tour points to nothing. +- Feature changed enough that tour content is wrong; redesign instead of patch. + +**Update when:** + +- Feature changed in details but tour structure still applies. + +**The deprecation hygiene.** Quarterly audit of tours against current product. Tours pointing to deprecated features get retired; tours that still apply but need refresh get updated. + +--- + +## Common architecture failures + +**Single tour for non-linear product.** Users skip; help fails. + +**Branched tour with too many branches.** Maintenance burden; quality degrades per branch. + +**Library without tagging.** Tours accumulate; nobody can find them; some are stale. + +**Mega-tours.** Micro-tours that grew to 10+ steps; lose their micro nature. + +**Orphan tours.** Tours pointing to features that no longer exist; not retired. + +**Inconsistent micro-tour quality.** Some tours polished, others slapdash; users notice. + +--- + +## Methodology-level choices that stay in the public skill + +The exploration-fit principle. Patterns A through D. Architecture choice criteria. Micro-tour discipline. Tour tagging and organization. Tour deprecation. Common failures. + +## Implementation choices that stay internal + +Specific architectures for specific products. Specific tooling for tour authoring and management. The team's tagging conventions. Specific quarterly audit calendars. These vary by team and product. diff --git a/skills/interactive-product-tour/references/tour-decision-criteria.md b/skills/interactive-product-tour/references/tour-decision-criteria.md new file mode 100644 index 0000000..5bdf154 --- /dev/null +++ b/skills/interactive-product-tour/references/tour-decision-criteria.md @@ -0,0 +1,154 @@ +# Tour decision criteria + +When tours earn the build vs when documentation suffices. + +A tour system is meaningful work. Trigger logic, tour architecture, contextual placement, completion tracking, ongoing maintenance. Tours earn this investment only when specific conditions are present. + +--- + +## When tours earn the build + +Five conditions that, when present, make tours a strong investment. + +**The product has features users genuinely miss.** Specific functionality buried in menus, advanced workflows requiring sequence, integrations users do not know exist. Without prompting, users do not find these features. + +**The audience benefits from in-context guidance more than documentation.** Tours teach in the place the user will use the feature; docs require context-switching. Some audiences prefer the immediacy of in-context help. + +**The team can maintain tours.** Tour content decays as the product evolves. Without maintenance commitment, tours point to deprecated UI; users hit broken steps. + +**The success metric is defined.** Feature adoption per tour-covered feature, time-to-value for specific capabilities, reduction in support tickets. Without the metric, evaluation is impossible. + +**The product changes at a sustainable pace.** Tours can keep up. Products that change weekly may have tour-maintenance burden exceeding tour value. + +When all five are present, tours are a strong investment. When two or fewer are present, documentation often serves better. + +--- + +## When tours do NOT earn the build + +Funnels where tours add complexity without value. + +**The product's feature set is small enough that documentation suffices.** A few tooltips on key features may be all that is needed. Building a full tour infrastructure is overkill. + +**The audience prefers self-directed discovery.** Some audiences resent in-product guidance. Developer tools, professional creative tools, specialist software often have audiences who want to explore on their own. + +**The team cannot maintain tours.** Stale tours are worse than no tours. Without commitment, tours decay into liability. + +**The product changes too frequently.** A product churning weekly may have tours that go stale within days of being shipped. The maintenance cost exceeds the tour benefit. + +**The audience is small enough that direct outreach is more efficient.** Onboarding calls, customer success engagement, and direct help may serve a small audience better than tour infrastructure. + +The honest assessment matters. Tours are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Documentation vs tours: the comparison + +Both teach features; they differ in delivery. + +**Documentation strengths.** + +- Stable; changes don't require tour updates. +- Searchable; users find what they need. +- Comprehensive; can cover edge cases. +- Accessible from outside the product (sharing, linking). + +**Documentation weaknesses.** + +- Requires context-switching from product to docs. +- Users may not know to consult docs. +- Static; cannot react to user state. + +**Tour strengths.** + +- In-context; help where the user will use the feature. +- Dynamic; can react to user state and behavior. +- Non-disruptive when designed well. + +**Tour weaknesses.** + +- Maintenance burden. +- Can become tooltip-spam if undisciplined. +- Less comprehensive than docs. + +**The combined approach.** Most production teams use both. Tours for the moments where in-context guidance matters; docs for depth and reference. + +--- + +## The opportunity-cost frame + +Tour systems are significant work. + +**The build cost.** Trigger logic infrastructure, tour authoring, instrumentation, integration with the product, design and copy. A meaningful tour system often takes 60-200 engineering hours plus design and copy per major tour. + +**The maintenance cost.** Quarterly review minimum; product changes trigger tour updates. 4-12 hours per active tour per quarter. + +**The opportunity cost.** What else could the team have built? Direct in-product improvements, better empty states, contextual prompts that do not require tour infrastructure. The tour system has to clear the bar of those alternatives. + +The decision frame. Tours earn investment when they produce more adoption lift than the alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering an in-product tour system. + +**Conditions check.** + +- Features users miss: yes. Advanced analysis modes, custom dashboard creation, integration setup all underused. +- In-context guidance benefits: yes. Users explore in-product; pulling them to docs breaks flow. +- Maintenance commitment: yes. Customer success team owns tours. +- Success metric defined: yes. Feature adoption per tour-covered feature within 30 days of first encounter. +- Product change pace: moderate. Major features ship monthly; minor changes weekly. Tour updates fit the cadence. + +**Decision.** Build the tour system. The conditions warrant it. + +**Architecture.** Library of micro-tours, each tied to a specific feature. Triggered contextually when users first encounter the feature. + +**Maintenance commitment.** CS team reviews quarterly; major product changes trigger tour updates as part of the change. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A developer-tool company considering in-product tours. + +**Conditions check.** + +- Features users miss: somewhat. Some advanced features underused, but the audience tends to find them through docs. +- In-context guidance benefits: weak. Developers strongly prefer docs and prefer not to be interrupted. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined. +- Product change pace: moderate. + +**Decision.** Do not build a full tour system. Invest in better docs, smarter empty states, and a few high-value contextual hints. The audience's preference for self-directed discovery argues against tour infrastructure. + +The decision was right-sized to the audience. + +--- + +## When to retire a tour system + +Tour systems can become wrong over time. + +**Retire when:** + +- Feature adoption (the tour's success metric) has declined consistently and refinements have not moved it. +- Users globally disable tours via settings. +- The product changes have outpaced maintenance; tours are stale. +- A redesigned product surface (better empty states, better contextual prompts) makes tours redundant. +- The team can no longer maintain tours. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant tours. The five conditions that argue against. Documentation vs tours comparison. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tour decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/interactive-product-tour/references/trigger-logic-patterns.md b/skills/interactive-product-tour/references/trigger-logic-patterns.md new file mode 100644 index 0000000..aa489aa --- /dev/null +++ b/skills/interactive-product-tour/references/trigger-logic-patterns.md @@ -0,0 +1,226 @@ +# Trigger logic patterns + +Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. + +The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. Useful triggers surface help at moments of friction. + +--- + +## The relevance principle + +Trigger help when the user is at a moment of friction or genuine need. Do not trigger help when the user is moving through familiar territory. + +**The win.** A user clicks into a feature for the first time. The tour system recognizes this is the user's first encounter and surfaces a brief contextual hint. The user reads, takes the suggested action, moves on. + +**The fail.** Same user, same feature. The tour system has no first-encounter detection; it triggers on every page load. The user has dismissed the same tooltip 12 times; develops blindness to all tooltips. + +The discipline. Each trigger should answer "why this user, why now." + +--- + +## Pattern A: Event-based triggers + +Help appears in response to a user action. + +**How it works.** + +- The user performs an action (clicks a feature, enters a section, completes a flow). +- The trigger fires based on the event. +- Help appears contextually. + +**Examples.** + +- First click into a new section. +- Completed a flow for the first time. +- Hit a state where help would be useful (empty list, no data connected, no teammates invited). + +**Strengths.** + +- Most relevant; help responds to what the user just did. +- Naturally contextual. + +**Weaknesses.** + +- Requires per-event tracking. +- Can over-trigger if events are too granular. + +**When to use.** Default for most contextual help. Events drive the trigger. + +--- + +## Pattern B: Time-based triggers + +Help appears after time elapsed. + +**How it works.** + +- A timer starts when relevant condition is met. +- After a defined interval, help triggers. +- Time can be session time, time on page, time since last action, or time since last login. + +**Examples.** + +- User has been on a page for 60 seconds without acting (signals stuck). +- User returned after 30 days of absence (signals re-orientation needed). +- User has been a customer for 90 days (signals capacity for advanced features). + +**Strengths.** + +- Catches stuck users events alone might miss. +- Useful for re-engagement of long-absent users. + +**Weaknesses.** + +- Time alone is a noisy signal. +- "Stuck" might just be reading. +- Easy to misuse and produce annoyance. + +**When to use.** Sparingly. Time-based triggers should always combine with event or state signals. + +--- + +## Pattern C: State-based triggers + +Help appears based on user state. + +**How it works.** + +- The user has attributes (new vs power; small vs large account; specific role; specific plan). +- Trigger fires based on attribute match. + +**Examples.** + +- Power users see help only on newly-shipped features. +- Enterprise customers see different tour on workspace features than SMB. +- Users on free plan see different upgrade-related help than paid. + +**Strengths.** + +- Personalizes help to user segment. +- Avoids over-helping users who do not need it. + +**Weaknesses.** + +- Requires user-state infrastructure. +- State changes (plan upgrade, role change) need to update triggers. + +**When to use.** When help differs significantly by user segment. State modulates event triggers. + +--- + +## Pattern D: Combined triggers + +Most production tour systems combine event, time, and state. + +**Example combined trigger.** + +"Show tour for advanced filtering feature when: +- User clicks the filter icon for the first time (event). +- User has been on the platform more than 7 days (state, not too new). +- User is on a paid plan (state, feature is paid-only). +- User has not dismissed this specific tour before (state, respect prior dismissal)." + +The combination produces relevant triggers without false positives. + +**The discipline.** Trigger conditions accumulate. Each condition prevents over-triggering. + +--- + +## Trigger frequency limits + +Even relevant triggers can over-fire. + +**Per-tour limits.** + +- Once per user (most tours). +- Once per quarter (re-orientation tours). +- Once per session per page (low-priority hints). + +**Per-session limits.** + +- Cap total tour interruptions per session (e.g., max 2 tours per session). +- Cap total tooltip appearances per session. + +**The cumulative-frequency problem.** Each individual tour may be reasonable; the cumulative count across many tours can become noise. + +The discipline. Audit cumulative triggers per session, not just per tour. + +--- + +## Trigger disabling and respect + +Users may disable tours globally. + +**The pattern.** A settings option lets users disable all tours. + +**The discipline.** Respect the disable. No tour should override the global setting (compliance triggers may be exception). + +**Re-engaging disabled users.** + +- Do not auto-re-enable. +- Surface specific high-value features as one-time prompts that respect the disable. +- Trust that users who disabled know what they want. + +--- + +## Trigger logic and accessibility + +Triggers must work for users with assistive technology. + +**Considerations.** + +- Triggers should not assume mouse hover (keyboard users miss them). +- Triggers should not auto-fire to overwhelm screen readers. +- Triggers should respect prefers-reduced-motion. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Trigger logic testing + +Test triggers across user paths. + +**Test cases.** + +- New user encounters feature: trigger fires. +- Returning user encounters same feature: trigger does not re-fire (respects history). +- Power user encounters newly-shipped feature: trigger fires. +- User who dismissed a tour: dismissed tour does not re-fire. +- User who disabled tours globally: no tours fire. +- User on mobile vs desktop: triggers behave consistently. + +**Production monitoring.** + +- Track trigger fire rate per tour. +- Track tour completion rate per tour. +- Track unique users who saw each tour. +- Anomalies (sudden spike in triggers) often indicate logic issues. + +--- + +## Common trigger logic failures + +**Over-triggering.** Triggers fire on every page load; users develop blindness. + +**Under-triggering.** Triggers fire only on first-login; users miss help when they need it later. + +**No state awareness.** Power users see beginner tours; new users see tours for features they have not unlocked. + +**No frequency limits.** Each individual tour is fine; cumulative triggers per session are noise. + +**Disabled users not respected.** Tours fire despite global disable. + +**Stale triggers.** Triggers reference features deprecated 6 months ago. + +**Untested edge cases.** Specific user paths produce broken triggers; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through D (event, time, state, combined). Trigger frequency limits. Trigger disabling and respect. Accessibility considerations. Trigger testing. Common failures. + +## Implementation choices that stay internal + +Specific trigger configurations for specific tours. Specific tooling for trigger management. The team's testing protocols. Specific frequency baselines. These vary by team and product. diff --git a/skills/internationalization/SKILL.md b/skills/internationalization/SKILL.md new file mode 100644 index 0000000..01f91ab --- /dev/null +++ b/skills/internationalization/SKILL.md @@ -0,0 +1,278 @@ +--- +name: internationalization +description: "Plan and run a multi-language or multi-region site. Use this skill when adding new locales, choosing URL structure for languages (subfolders vs subdomains vs ccTLDs), implementing hreflang, planning translation workflow, handling currency and date formats, designing for RTL languages, or auditing a stalled internationalization rollout. Triggers on internationalization, i18n, localization, l10n, hreflang, multi-language, translation workflow, RTL, locale, ccTLD, subfolder vs subdomain, language switcher. Also triggers when international audiences underperform or translations are stale." +category: cross-cutting +catalog_summary: "Locale strategy, hreflang, translation workflow, RTL design" +display_order: 3 +--- + +# Internationalization + +Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic. + +--- + +## When to use + +- Adding the first non-English (or non-default) language +- Adding additional locales to an existing internationalized site +- Choosing URL structure for languages +- Implementing hreflang tags +- Designing translation workflow +- Handling currency, date, time, and number formats +- Designing or fixing layout for RTL languages +- Auditing an internationalization rollout that's underperforming + +## When NOT to use + +- Single-language site (use other skills) +- Domain strategy that's not language-driven (use `domain-strategy`) +- Content strategy independent of locale (use `content-strategy`) +- Marketing copy production (use `content-and-copy`) + +--- + +## Required inputs + +- The locales in scope (language + region, e.g., `en-US`, `de-DE`, `fr-CA`) +- Business reason per locale (priority, audience size) +- Existing site architecture +- Translation resources (in-house, agency, AI-assisted, community) +- Content volume and update frequency + +--- + +## The framework: 5 layers + +Internationalization touches everything. Five layers, each with their own decisions. + +### Layer 1: URL structure + +How locales are reflected in URLs. + +| Pattern | Example | When | +|---|---|---| +| ccTLD | example.de, example.fr | Strong country focus, distinct legal entities, willing to maintain separate domains | +| Subdomain | de.example.com, fr.example.com | Logical separation, willing to host separately, common for large sites | +| Subfolder | example.com/de/, example.com/fr/ | SEO equity unified, simplest to manage, default for most | +| URL parameter | example.com?lang=de | Avoid; weak SEO signal | + +For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand). + +Within the chosen pattern, decide: +- Language only (`/de/`) or language plus region (`/de-de/`, `/de-at/`, `/de-ch/`)? +- Default locale: at the apex (`example.com`) or in a folder (`example.com/en/`)? + +The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an `x-default` and the canonical for the default language). + +### Layer 2: Content structure + +How content is organized across locales. + +**Pattern A: Mirror.** Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content. + +**Pattern B: Subset.** Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences. + +**Pattern C: Local.** Each locale has its own content largely independent of other locales. Common for media or community sites. + +Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial. + +The pattern affects: +- How content models are designed (does each piece have parent/translation relationships?) +- How translation is managed (workflow assumes the structure) +- How the team coordinates + +### Layer 3: hreflang and canonicals + +Telling search engines what's translated vs distinct. + +**hreflang** specifies the language and optional region for each version. + +```html +<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page"> +<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page"> +<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page"> +<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page"> +``` + +Rules: +- Every page lists every translated equivalent (including itself) +- Pages must reciprocate (page A says page B is its German version; page B says page A is its English version) +- `x-default` is the fallback for users in unspecified regions +- Each page has its own canonical pointing to itself (not to the default language) + +hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small. + +**Canonicals:** +- Self-referential per page +- Don't canonical the German page to the English page (search engines won't index the German page) + +### Layer 4: Translation workflow + +How content gets translated, kept fresh, and quality-controlled. + +**Sources of translation:** +- In-house translators (full-time staff) +- Translation agency (paid per word, professional) +- Community contributors (volunteer, variable quality, free) +- AI-assisted plus human review (cheap, fast, growing in quality) +- AI only (acceptable for some content, not for brand-critical) + +**Workflow stages:** + +1. **Source content authored** in the source language +2. **Translation requested** through a TMS (translation management system) or spreadsheet +3. **Translation produced** with translation memory (avoids retranslating reused phrases) +4. **Review** by a second translator or in-region staff +5. **Localization** beyond translation (currency, units, examples, cultural references) +6. **Publishing** in the destination locale +7. **Update propagation** when source content changes + +The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine. + +**Update propagation is the hardest part.** Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source. + +### Layer 5: Locale-aware UX + +Beyond translation, the experience must adapt. + +**Currency:** display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page. + +**Numbers:** thousand separators and decimals differ. `1,000.50` in en-US is `1.000,50` in de-DE. + +**Dates and times:** format and order vary. `MM/DD/YYYY` in en-US, `DD/MM/YYYY` in en-GB, `YYYY-MM-DD` (ISO) is universal but unfamiliar to many. + +**Names and addresses:** field order and required components differ. Country-aware address forms. + +**Phone numbers:** E.164 international format universally; display formatting per locale. + +**Units:** metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both. + +**Right-to-left (RTL) languages:** Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (`margin-inline-start` instead of `margin-left`) make this manageable. + +**Language switcher:** prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back. + +**Cultural sensitivity:** colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized. + +--- + +## Workflow + +### Step 1: Decide which locales + +Don't add languages just because you can. Each locale has ongoing maintenance cost. + +- Audience research: where are visitors and prospects? +- Business priority: which markets are growth targets? +- Content readiness: do you have the resources to maintain it? +- Legal: do regulations require localization (GDPR, accessibility laws)? + +### Step 2: Pick URL structure + +Subfolder for most. Document the choice and rationale. + +### Step 3: Pick content structure + +Mirror, subset, or local. Be honest about what's sustainable. + +### Step 4: Set up hreflang and canonicals + +Implement before launching the second locale, even if it's just one extra page. + +### Step 5: Set up translation workflow + +Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers. + +### Step 6: Localize beyond translation + +For each locale: +- Currency, numbers, dates, units +- Locale-specific images if needed +- Address forms +- Customer service hours and contact + +### Step 7: Implement language switcher + +- Prominent in the header or footer +- Shows the current locale clearly +- Lists all available locales in their own language +- Persists the choice (cookie or local storage) +- Doesn't auto-redirect based on browser; suggests instead + +### Step 8: Test + +- Each locale renders correctly +- hreflang links are valid (use a checker) +- Canonicals are self-referential per page +- Currency and dates are correct +- RTL layout is correct (for RTL locales) +- Language switcher works and persists +- Search-engine perspective: each locale is crawlable and indexable + +### Step 9: Launch and monitor + +Per locale: +- Indexing rate +- Traffic from intended geographies +- Engagement metrics in the locale +- Translation freshness (when did source content change without translation update?) + +### Step 10: Maintain + +- Translation update cadence (when source changes, when translations follow) +- Quarterly review of locale performance +- Sunset locales that aren't viable (better than maintaining a dead locale poorly) + +--- + +## Failure patterns + +**Auto-redirect based on browser language.** User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect. + +**Single canonical to default language.** Search engines can't index the translations. Self-canonical per page. + +**Reciprocal hreflang missing.** German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed. + +**hreflang language without region when region matters.** `hreflang="es"` is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions. + +**Auto-translated content treated as final.** Machine translation is an acceptable starting point. Human review is necessary for any user-facing content. + +**Currency baked into copy.** "$99/month" in body text breaks for European users. Use templated currency that adapts. + +**Hardcoded date formats.** "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale. + +**Field labels left in source language.** Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization. + +**Untranslated error messages.** User submits a form, gets an error in English on a French page. Frustrating. Translate UI states. + +**Untranslated emails.** Site is in French; transactional emails are English. Translate emails to match. + +**Forgotten locales in CMS.** Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift. + +**Locale switcher that doesn't work mid-flow.** User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale. + +**RTL layouts that don't actually flip.** Margin and padding hardcoded for LTR. Use CSS logical properties. + +**Sunset language without redirect.** Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language. + +--- + +## Output format + +An internationalization plan includes: + +- **Locale list:** with priority and audience rationale +- **URL structure:** chosen pattern and reason +- **Content structure:** mirror, subset, or local +- **hreflang plan:** how it's implemented +- **Translation workflow:** sources, stages, tools +- **Localization checklist:** beyond translation (currency, dates, etc.) +- **Language switcher design:** position, behavior, persistence +- **Test plan:** what's verified per locale +- **Maintenance plan:** update cadence, drift detection + +--- + +## Reference files + +- [`references/locale-checklist.md`](references/locale-checklist.md): Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal). diff --git a/skills/internationalization/references/locale-checklist.md b/skills/internationalization/references/locale-checklist.md new file mode 100644 index 0000000..8bb3bd8 --- /dev/null +++ b/skills/internationalization/references/locale-checklist.md @@ -0,0 +1,233 @@ +# Locale Checklist + +A per-locale checklist of everything that needs to adapt beyond translation. Walk through this for each locale before launch, and revisit when adding new content. + +--- + +## URL and structure + +- [ ] Locale URL pattern chosen and consistent (subfolder, subdomain, or ccTLD) +- [ ] Locale code uses standard format (BCP 47: `en`, `en-US`, `de-DE`, `zh-Hant`) +- [ ] Default locale handling decided (apex vs folder) +- [ ] URL slugs translated where appropriate (e.g., `/products/` → `/produkte/` for German) +- [ ] Or URL slugs kept consistent across locales (acceptable for many sites; prioritizes consistency over native readability) + +--- + +## Search engine signals + +- [ ] hreflang tags present on every page, every locale +- [ ] hreflang reciprocity verified (page A links to B, B links to A) +- [ ] hreflang includes `x-default` pointing to the fallback +- [ ] Canonical tags self-reference (each locale page canonicals to itself) +- [ ] Sitemaps include all locales (one sitemap per locale or a combined sitemap) +- [ ] robots.txt allows all locale paths +- [ ] Schema.org `inLanguage` attribute on appropriate types + +--- + +## Translation completeness + +- [ ] Page content translated +- [ ] Page titles and meta descriptions translated +- [ ] Image alt text translated +- [ ] Form labels translated +- [ ] Form validation messages translated +- [ ] Error pages (404, 500) translated +- [ ] Success messages translated +- [ ] Email templates translated (transactional, marketing) +- [ ] PDF or downloadable assets translated (or alternate version provided) +- [ ] Help and FAQ content translated +- [ ] Legal pages translated (privacy, terms, cookies) + +--- + +## Currency and money + +- [ ] Currency displayed matches the locale (EUR for euro zone, GBP for UK, JPY for Japan, etc.) +- [ ] Currency symbol position correct ($1,000 vs 1.000 €) +- [ ] Decimal separator correct (1,000.50 vs 1.000,50 vs 1 000,50) +- [ ] Thousand separator correct (comma, period, space, or none) +- [ ] Pricing tables localized to native pricing (not direct conversion) +- [ ] Tax handling (inclusive vs exclusive) matches local convention + +--- + +## Numbers and units + +- [ ] Number format follows locale (1,234.56 vs 1.234,56) +- [ ] Negative numbers (-5 vs (5)) follow convention +- [ ] Percentages format correctly (5% vs 5 %) +- [ ] Measurement units match (km vs miles, kg vs lb, °C vs °F) +- [ ] Paper sizes if relevant (A4 vs Letter) + +--- + +## Dates and times + +- [ ] Date format matches (DD/MM/YYYY for most of Europe, MM/DD/YYYY for US, YYYY-MM-DD ISO) +- [ ] Day-of-week localization (Monday vs Lundi vs 月曜日) +- [ ] Month names localized +- [ ] First day of week (Monday in Europe, Sunday in US) +- [ ] Time format (12-hour with AM/PM vs 24-hour) +- [ ] Time zone display where relevant +- [ ] Relative time strings localized ("2 hours ago" → "il y a 2 heures") + +--- + +## Names and addresses + +- [ ] Name field structure matches (single name field for some cultures, given/family for others, family-first ordering for some Asian languages) +- [ ] Address form fields adapt to country + - US: street, city, state, ZIP + - UK: street, town, county, postcode + - Germany: street, postal code, city + - Japan: postal code, prefecture, city, ward, block, building +- [ ] Postal code validation per country +- [ ] State/region/prefecture/county field renamed appropriately +- [ ] Country dropdown ordered by region or alphabetical (avoid US-first if not US-centric audience) + +--- + +## Phone numbers + +- [ ] Country code defaulted appropriately +- [ ] E.164 format stored (+CCNNNNNNNNNN) +- [ ] Display format adapts to country +- [ ] Validation accepts international formats + +--- + +## Imagery and media + +- [ ] Images depict locally relevant people, places, products +- [ ] Avoided imagery that's offensive in the locale (gestures, symbols, color associations) +- [ ] Cultural references in screenshots/examples are appropriate +- [ ] Image text translated (text in images doesn't auto-translate) +- [ ] Video subtitles or dubbing in the locale language + +--- + +## Layout and direction + +- [ ] LTR/RTL handling correct for the script +- [ ] CSS logical properties used (`margin-inline-start` instead of `margin-left`) +- [ ] Icons that imply direction (arrows, chevrons) flip for RTL +- [ ] Numbers display LTR even within RTL text (per Unicode bidi algorithm) +- [ ] Tables and lists adjusted for direction + +--- + +## Typography + +- [ ] Fonts support the script (not all fonts cover Cyrillic, CJK, Arabic, etc.) +- [ ] Font sizes adjusted if needed (some scripts read smaller; CJK often needs slightly larger) +- [ ] Line height appropriate (CJK often needs more) +- [ ] Word breaking handled (no breaking in the middle of CJK characters; break opportunities for Thai) +- [ ] Quotation marks correct ("..." in English, „..." in German, «...» in French, 「...」 in Japanese) + +--- + +## Search and sort + +- [ ] Search handles diacritics ("café" matches "cafe" or doesn't, by design) +- [ ] Sort order respects locale (German sorts ä with a, Swedish sorts ä after z) +- [ ] Search results in the same locale as the user (don't show English results to French users) + +--- + +## Forms and inputs + +- [ ] Input methods supported (IMEs for CJK, etc.) +- [ ] Pasting from clipboard works with non-Latin characters +- [ ] Field validation accepts non-Latin characters where appropriate (names should accept any Unicode) +- [ ] Min/max length constraints work for the script (Japanese names are often shorter; Arabic/Hebrew names use different character counts) + +--- + +## Legal and compliance + +- [ ] Privacy policy adapted to local laws (GDPR for EU, LGPD for Brazil, CCPA for California, etc.) +- [ ] Cookie consent matches local requirements +- [ ] Terms of service in local language and acknowledging local law +- [ ] Required disclaimers present (consumer protection, financial services, healthcare, etc.) +- [ ] Tax handling per locale (display inclusive in EU, exclusive in US, etc.) +- [ ] Local payment methods supported where customer expectations require + +--- + +## Customer support and contact + +- [ ] Support hours displayed in local timezone +- [ ] Support contact options match (phone numbers, chat, email, varies by region) +- [ ] Office address (if shown) is appropriate for the locale +- [ ] Local language support team or clear "support in [language]" indication + +--- + +## Marketing and SEO + +- [ ] Keyword research done in the local language (not just translated keywords) +- [ ] Meta titles and descriptions are locally compelling, not just translated +- [ ] Open Graph tags adapted (translated, locale-appropriate images) +- [ ] Schema.org markup translated where text-based +- [ ] Local search engines considered (Baidu in China, Yandex in Russia) +- [ ] Backlink strategy adapted to local web (local directories, local press) + +--- + +## Testing per locale + +- [ ] Page renders correctly in all major browsers +- [ ] Page renders correctly on mobile +- [ ] All links work and stay within the locale (or correctly switch locale) +- [ ] Forms submit correctly +- [ ] Confirmation flows work end-to-end (form → email → next step) +- [ ] No untranslated strings (search HTML for source-language strings) +- [ ] No broken images +- [ ] No layout breakage from longer or shorter text (German is often longer than English; CJK often shorter; Arabic similar to English in length but different layout) +- [ ] Performance comparable to default locale + +--- + +## Language switcher + +- [ ] Switcher visible on every page +- [ ] Available locales shown in their own language +- [ ] Current locale clearly indicated +- [ ] Switcher preserves the current page (not just sends to homepage) +- [ ] Switcher persists user choice (cookie or local storage) +- [ ] Switcher doesn't auto-redirect on first visit (suggests, doesn't force) + +--- + +## Maintenance + +- [ ] Translation update workflow defined +- [ ] Drift detection in place (when source changes, translation needs update) +- [ ] Per-locale analytics set up +- [ ] Per-locale error monitoring +- [ ] Translation quality reviewed periodically +- [ ] Locale sunset criteria defined (when to retire a poorly-performing locale) + +--- + +## Per-locale metrics to watch + +| Metric | Target | +|---|---| +| Page completion rate | Comparable to default locale | +| Form completion rate | Comparable to default locale | +| Bounce rate | Comparable to default locale | +| Time on page | Comparable to default locale | +| Conversion rate | Comparable to default locale | +| Translation freshness | Source content updates reflected within X days | + +A locale persistently underperforming on user metrics may have: +- Translation quality issues +- Cultural mismatches in copy or imagery +- Missing local payment or contact options +- Slow performance from far hosting +- Unmet user expectations (US e-commerce conventions used in markets that prefer different patterns) + +Investigate before scaling investment. diff --git a/skills/journey-mapping/SKILL.md b/skills/journey-mapping/SKILL.md new file mode 100644 index 0000000..c65508e --- /dev/null +++ b/skills/journey-mapping/SKILL.md @@ -0,0 +1,244 @@ +--- +name: journey-mapping +description: "Build customer journey maps and service blueprints that visualize the end-to-end user experience including touchpoints, emotions, friction, and underlying systems. Use this skill whenever the user wants to map a customer journey, build a service blueprint, identify friction across an experience, align teams on the user experience, or visualize touchpoints and pain points. Triggers on customer journey, journey map, service blueprint, user journey, experience map, touchpoint analysis, friction map, journey audit, end-to-end experience, customer experience map. Also triggers when the team has departmental views of users but no shared map of what the experience actually feels like." +category: research +catalog_summary: "Customer journey maps, service blueprints, friction analysis" +display_order: 3 +--- + +# Journey Mapping + +Build journey maps and service blueprints that surface friction, align teams, and identify opportunities. Stack-agnostic. Tool-agnostic. + +This skill is for mapping the experience. For testing specific touchpoints, use `usability-testing`. For broader generative research, use `ux-research`. For analyzing conversion, use `cro-optimization`. + +--- + +## When to use + +- Departments have different mental models of the customer experience +- Customer experience feels disjointed across touchpoints +- Specific friction or drop-off points need diagnosis +- Strategic planning needs a shared view of the user +- Service design (front-stage and back-stage) needs alignment +- New product or feature needs to be designed in context of broader experience + +## When NOT to use + +- Testing a single touchpoint or page (use `usability-testing`) +- Generative research before journey mapping (use `ux-research`) +- Operational process mapping that doesn't involve users +- Funnel optimization (use `cro-optimization`) + +--- + +## Required inputs + +- Identified user persona or segment to map (one map per segment) +- Existing research and data about that segment +- Cross-functional access (you cannot map back-stage without ops/support/engineering input) +- Time and stakeholder commitment (a real journey map is a project, not an afternoon) + +--- + +## The framework: 3 deliverables + +### 1. Customer journey map + +The user-facing view of the experience. + +**Structure (rows / lanes):** + +- **Phase.** The major stages in the journey (e.g., Awareness, Consideration, Onboarding, Activation, Retention, Advocacy). Phases vary by product type. +- **Steps.** Specific things the user does within each phase. +- **Touchpoints.** Where the user interacts with the product, brand, or service (web, app, email, support, social, in-person). +- **Goals.** What the user is trying to accomplish at this step. +- **Thoughts.** What's going through their mind. +- **Emotions.** The emotional state (often visualized on a curve). +- **Pain points.** Where things go wrong, friction, frustration. +- **Opportunities.** Where the experience could improve. + +**Format:** + +Typically a horizontal timeline with vertical lanes for each row. Phases across the top, touchpoints, thoughts, emotions, etc. underneath. + +### 2. Service blueprint + +The back-stage view that supports the customer-facing experience. + +**Adds these layers below the journey map:** + +- **Front-stage actions.** What employees do that the user sees (sales calls, support chats, in-store interactions). +- **Back-stage actions.** What happens behind the scenes (order fulfillment, data processing, internal handoffs). +- **Supporting processes.** Systems, vendors, infrastructure (CRM, payment processors, fulfillment partners). +- **Lines of visibility.** The line between front-stage (visible to user) and back-stage (invisible). + +The service blueprint shows where customer-facing problems originate in back-stage failures (e.g., the user's "shipping is slow" experience traces to a vendor handoff issue). + +### 3. Synthesized opportunity map + +Output of the mapping work. + +**Captures:** + +- **Top friction points.** Where the experience consistently fails users. +- **Untapped opportunities.** Moments where the experience could surprise and delight. +- **Disconnects.** Where front-stage and back-stage are misaligned. +- **Strategic gaps.** Where competitors have something the brand lacks (or vice versa). +- **Quick wins.** Low-effort, high-impact improvements. +- **Strategic bets.** Higher-effort transformations. + +This is the deliverable that produces decisions. The journey map and service blueprint are inputs; the opportunity map is the output that drives action. + +--- + +## Common phases by product type + +### Most products + +``` +Awareness → Consideration → Decision → Onboarding → Active use → Renewal/Repurchase → Advocacy +``` + +### SaaS + +``` +Trigger → Discovery → Evaluation → Trial → Onboarding → Activation → Habit → Expansion → Renewal → Advocacy +``` + +### Ecommerce + +``` +Need recognition → Discovery → Research → Decision → Purchase → Wait/Anticipation → Receive → Use → Reorder/Recommend +``` + +### Service + +``` +Awareness → Inquiry → Quote → Decision → Service delivery → Resolution → Follow-up → Repeat business +``` + +### Healthcare / high-stakes purchases + +``` +Trigger → Research → Provider selection → Appointment → Treatment → Recovery → Follow-up → Long-term outcome +``` + +Phases are not mandatory. Start with the user's actual experience and let the phases emerge from the steps. + +--- + +## How to gather the inputs + +A good journey map combines multiple sources of truth. + +### From users + +- **In-depth interviews.** Walk users through their actual experience. Ask for specifics from a recent occurrence. +- **Diary studies.** Users log their experience over the duration of the journey. +- **Surveys.** Quantitative signal at scale; less depth. + +### From the business + +- **Internal interviews.** Sales, support, success, ops. They see the experience from different angles than product or design. +- **Operational data.** Funnel data, support ticket categories, NPS responses, churn reasons. +- **System inventory.** What touchpoints exist, what tools support them, what data flows where. + +### Cross-validate + +- The user's experience as they describe it +- The data the business has about their behavior +- The internal team's perception of the experience + +These three views often disagree. The disagreements are themselves findings. + +--- + +## Workflow + +1. **Define scope.** One persona, one journey, one timeframe. Trying to map all users in one map produces a mess. +2. **Gather inputs.** User interviews, internal interviews, operational data. Plan 2 to 4 weeks for inputs. +3. **Draft the journey.** Phases, steps, touchpoints. Get to a working draft fast; iterate. +4. **Add the layers.** Goals, thoughts, emotions, pain points. +5. **Build the service blueprint.** Front-stage, back-stage, supporting processes. +6. **Identify opportunities.** Use the friction points and disconnects. +7. **Validate with users.** Does this match their actual experience? Refine. +8. **Workshop with stakeholders.** Walk teams through the map. Ensure shared understanding. +9. **Translate to action.** Specific projects, owners, timelines. +10. **Maintain.** A journey map is a living document. Revisit annually or after major changes. + +--- + +## Failure patterns + +- **Mapping without research.** A journey map built from internal assumptions reflects assumptions, not users. +- **One map for all users.** The mid-market buyer and enterprise buyer have different journeys. Don't merge. +- **No back-stage layer.** The map shows symptoms, not causes. +- **Beautiful map, no action.** Investment in production value at the expense of decisions. +- **Map as artifact, not tool.** Filed in Figma, never re-opened. +- **Ignoring emotional layer.** The "what" without the "how it feels" misses the point of journey mapping. +- **Vague pain points.** "Frustrating onboarding" - what specifically? When? Why? +- **Quick wins identified, never executed.** Same as research findings that don't ship. +- **Annual exercise without followup.** Year-old journey map describes year-old user. + +--- + +## Output format + +Default outputs: + +1. **Journey map** (visual, typically Figma / FigJam / Miro, plus a markdown narrative version) +2. **Service blueprint** (visual, typically same tool) +3. **Opportunity map** (markdown, prioritized list) + +Markdown narrative version of journey map: + +```markdown +# [Persona] journey map + +## Phase 1: [Phase name] + +### Step: [Step name] +- **Touchpoint:** [Where this happens] +- **Goal:** [What the user wants here] +- **Thoughts:** [What they're thinking] +- **Emotion:** [State on the emotional curve] +- **Pain points:** [Friction] +- **Opportunities:** [Improvement potential] + +### Step: [Step name] +[Same structure] + +## Phase 2: [Phase name] +[Repeat] + +## Service blueprint additions + +### Phase 1 +- **Front-stage actions:** [What employees do user-visibly] +- **Back-stage actions:** [What happens behind the scenes] +- **Supporting processes:** [Systems involved] + +[Repeat per phase] + +## Opportunity map + +### Critical friction +1. [Specific issue, with evidence] +2. [Specific issue, with evidence] + +### Quick wins +1. [Specific opportunity, with effort/impact] + +### Strategic bets +1. [Specific opportunity, with effort/impact] + +### Cross-team disconnects +1. [Specific disconnect, with implication] +``` + +--- + +## Reference files + +- [`references/journey-map-template.md`](references/journey-map-template.md) - Fillable journey map and service blueprint template. diff --git a/skills/journey-mapping/references/journey-map-template.md b/skills/journey-mapping/references/journey-map-template.md new file mode 100644 index 0000000..372ea22 --- /dev/null +++ b/skills/journey-mapping/references/journey-map-template.md @@ -0,0 +1,317 @@ +# Journey Map Template + +Fillable journey map and service blueprint template. Customize phases to fit the specific product or service. + +--- + +## Map metadata + +**Persona / segment mapped:** [Specific persona. Not "users" - "First-time buyers in the 25-40 age range exploring B2B project management tools."] + +**Time horizon mapped:** [Pre-purchase to first 90 days? Full lifetime? Specific feature?] + +**Map version:** [X.Y] + +**Last updated:** [YYYY-MM-DD] + +**Owner:** [Person or team] + +**Source data:** [Interviews, surveys, support tickets, analytics. List with counts.] + +--- + +## Map structure + +| Phase | Step | Touchpoint | Goal | Thoughts | Emotion | Pain points | Opportunities | +|---|---|---|---|---|---|---|---| + +--- + +## Phase 1: [Phase name, e.g., Awareness] + +### Step 1.1: [Step name, e.g., Encounters problem] + +**Touchpoint:** [Where this happens. Could be offline. "Conversation with peer." Or online: "LinkedIn post."] + +**Goal:** [What the user is trying to accomplish at this step] + +**Thoughts:** +- "[Specific thought, ideally a real quote from research]" +- "[Specific thought]" +- "[Specific thought]" + +**Emotion:** [Emotional state, ideally from a defined set: confused, hopeful, frustrated, curious, anxious, confident, etc.] + +**Emotional intensity:** [1 to 5, for plotting on the emotional curve] + +**Pain points:** +- [Specific pain, with evidence] +- [Specific pain, with evidence] + +**Opportunities:** +- [Specific improvement opportunity] +- [Specific improvement opportunity] + +**Time spent at this step:** [Minutes / hours / days / weeks - average and range] + +--- + +### Step 1.2: [Step name] + +[Repeat structure] + +--- + +## Phase 2: [Phase name, e.g., Consideration] + +### Step 2.1: [Step name, e.g., Searches for solutions] + +**Touchpoint:** [e.g., Google search, then 4 to 6 vendor websites] + +**Goal:** [Build a shortlist of options that could fit] + +**Thoughts:** +- "[Quote]" +- "[Quote]" + +**Emotion:** [State] + +**Emotional intensity:** [1 to 5] + +**Pain points:** +- [Specific pain] +- [Specific pain] + +**Opportunities:** +- [Opportunity] + +**Time spent:** [Range] + +--- + +### Step 2.2: [Step name] + +[Repeat] + +--- + +## Phase 3: [Phase name, e.g., Decision] + +[Repeat structure] + +--- + +## [Continue with phases relevant to the journey...] + +--- + +## Emotional curve + +Plot the emotional intensity across the journey. The curve typically reveals the moments of highest joy and highest frustration. + +``` +Emotion +intensity + 5 │ + 4 │ ● + 3 │ ● ● ● + 2 │ ● ● ● ● + 1 │ ● ● + └────────────────────── + 1.1 2.1 3.1 4.1 + Phase / Step +``` + +[Document the emotional curve in your visual tool. Note the peaks (highest joy) and troughs (highest frustration). These are the most strategic points in the journey.] + +--- + +## Service blueprint layers + +For each phase, document the back-stage view. + +### Phase 1: [Phase name] + +**Front-stage actions** (employees in user view): +- [Action] +- [Action] + +**Back-stage actions** (employees behind the scenes): +- [Action] +- [Action] + +**Supporting processes** (systems, tools, vendors): +- [Process / system] +- [Process / system] + +**Lines of visibility issues:** +- [Where back-stage failures cause front-stage problems] + +--- + +### Phase 2: [Phase name] + +[Repeat] + +--- + +## Disconnects and gaps + +The most valuable findings often come from comparing layers. + +### Front-stage / back-stage disconnects + +| Issue | Front-stage symptom | Back-stage cause | +|---|---|---| +| | | | +| | | | + +### Internal team perception vs user reality + +| Internal belief | User reality | Gap | +|---|---|---| +| | | | +| | | | + +### Touchpoint / message inconsistencies + +| Touchpoint A says | Touchpoint B says | Confusion result | +|---|---|---| +| | | | + +--- + +## Persona context (for reference) + +A reminder of who this map represents. + +**Persona:** [Name and one-line description] + +**Demographics:** +- Age range: +- Role / job: +- Company size or context: +- Geography: +- Tech savviness: + +**Goals:** +- [Primary goal] +- [Secondary goal] +- [Secondary goal] + +**Frustrations:** +- [Frustration] +- [Frustration] + +**Behavior patterns:** +- [Pattern] +- [Pattern] + +**Quote that captures them:** +> "[Quote from a research participant who exemplifies this persona]" + +--- + +## Data sources + +Document where the map's claims come from. Builds credibility and traceability. + +| Claim | Source | Evidence | +|---|---|---| +| [Pain point at step 2.1] | 8 of 10 interviews | [Quote samples] | +| [Behavior at step 1.2] | Analytics: 73% drop-off | [Funnel data] | +| [Emotion at step 3.1] | Survey, 45 responses | [Score data] | + +--- + +## Opportunity map + +The output that drives action. + +### Critical friction (fix soon) + +| Friction | Phase / step | Evidence | Recommended action | Effort | Owner | +|---|---|---|---|---|---| +| [Specific] | | | | S/M/L | | +| [Specific] | | | | S/M/L | | + +### Quick wins (low effort, meaningful impact) + +| Opportunity | Phase / step | Recommended action | Effort | Impact | +|---|---|---|---|---| +| [Specific] | | | S | M | + +### Strategic bets (high effort, transformative) + +| Opportunity | Phase / step | Recommended action | Effort | Impact | +|---|---|---|---|---| +| [Specific] | | | L | H | + +### Cross-team alignment opportunities + +[Issues that require multiple teams to coordinate, not single-team fixes.] + +- [Issue, teams involved, recommended approach] +- [Issue, teams involved, recommended approach] + +--- + +## Action plan + +Specific projects from the opportunity map. + +### Immediate (next 30 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Near-term (60 to 90 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Strategic (next 2 to 4 quarters) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +--- + +## Re-mapping schedule + +Journey maps decay. Schedule re-mapping: + +- **Triggering events:** Major product launch, new persona segment, significant business model change, drop in NPS or retention +- **Default cadence:** Annual review, with light updates quarterly + +--- + +## Workshop outputs + +Use this map in stakeholder workshops. Capture outputs: + +**Workshop 1: Validation** +- Date: +- Attendees: +- Findings validated: +- Findings disputed: +- New findings surfaced: + +**Workshop 2: Prioritization** +- Date: +- Attendees: +- Top opportunities agreed: +- Decisions made: +- Open questions: + +--- + +## Companion artifacts + +Often produced alongside a journey map: + +- **Persona document.** Detailed persona that this journey map represents. +- **Quote library.** Direct user quotes organized by phase. Powerful in stakeholder presentations. +- **Highlight reel video.** 5 to 10 minute compilation of user moments mapped to journey phases. +- **Service blueprint.** Detailed back-stage map (this template includes a layer; a full blueprint deserves its own document). +- **Opportunity backlog.** All opportunities, scored and queued for execution. diff --git a/skills/jtbd-framing/SKILL.md b/skills/jtbd-framing/SKILL.md new file mode 100644 index 0000000..56313a8 --- /dev/null +++ b/skills/jtbd-framing/SKILL.md @@ -0,0 +1,260 @@ +--- +name: jtbd-framing +description: "The Jobs-to-be-Done framework as applied product methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity (discovery, prioritization, positioning) and where it becomes performative ritual (job-statement workshops that do not drive decisions, persona-theater disguised as JTBD). Triggers on jobs-to-be-done, JTBD, job statements, struggling moments, hire criteria, fire criteria, switch triggers, functional emotional social jobs, outcome-driven innovation. Also triggers when a team is over-relying on feature-request lists or persona archetypes that do not drive product decisions, when a positioning conversation needs the framing JTBD provides, or when discovery is producing outputs that do not connect to product strategy." +category: product +catalog_summary: "Jobs-to-be-Done framework. Job statements, struggling moments, hire/fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD earns its keep and where it becomes performative" +display_order: 11 +--- + +# Jobs-to-be-Done Framing + +A senior product leader's playbook for the Jobs-to-be-Done framework as applied methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity and where it becomes performative ritual. + +JTBD has become one of the more cited and less practiced frameworks in product. Teams cite it in strategy docs, run job-statement workshops, produce wall-sized artifacts, and continue building from feature requests and persona archetypes the next quarter. The methodology gets the credit; the practice gets skipped. + +This skill is JTBD as applied product methodology. The framework's actual contribution: surfacing what users are trying to ACCOMPLISH (the job) rather than treating users as preference-aggregators (feature requests) or demographic archetypes (persona theater). When the framing is grounded in struggling moments and hire/fire criteria, it produces decisions; when it stops at the job-statement worksheet, it produces ritual. + +This skill is honest about both modes. JTBD genuinely earns its keep in discovery, prioritization, and positioning when applied with rigor. It becomes ceremony when teams treat job statements as deliverables rather than as analytical tools. + +The voice is the senior product leader who has used JTBD well and watched plenty of teams use it badly. Concrete, opinionated about what the framework actually contributes, willing to call out where it gets oversold. + +When to use this skill: applying JTBD to a discovery cycle, replacing persona-driven prioritization with job-driven prioritization, reframing positioning around what users hire the product to do, or auditing whether existing JTBD work in the org is driving decisions. + +--- + +## What this skill is for + +This skill spans JTBD as a framing technique within product work. The PM-skill distinction: + +- `discovery-research-synthesis` is broader synthesis discipline; JTBD is one framing technique within it. +- **`jtbd-framing` (this skill)** is the specific JTBD methodology, its strengths, and its failure modes. +- `pm-spec-writing` is downstream: specs reference jobs as input. +- `creative-direction` is positioning territory; JTBD informs positioning but does not replace creative direction. +- `roadmap-planning` is downstream: roadmap can be organized around jobs rather than features. + +The audience: senior PMs, product directors, product strategists, agencies running discovery and positioning work, in-house teams considering or already using JTBD. + +What is not in scope: other product strategy frameworks (Wardley mapping, North Star, OKRs); the broader synthesis discipline (`discovery-research-synthesis` covers it); the demographic-persona work that sometimes gets confused with JTBD. + +--- + +## Feature-request-list vs persona-theater vs job-framing + +The keystone framing. + +**Feature-request-list.** "Users want X, Y, Z." Treats users as preference-aggregators. The product team builds the most-requested features. Output: a product that satisfies stated preferences but misses what users were actually trying to accomplish. Users do not always know what would solve their problem; they describe symptoms, not solutions. Feature-list-driven products often improve incrementally without becoming meaningfully better. + +**Persona-theater.** Demographic personas with cute names. "Marketing Manager Maria, 35, urban, Pinterest user, drinks oat milk lattes." Decorative, not decision-driving. Persona characteristics rarely correlate with what the user needs from the product; demographic detail substitutes for behavioral insight. Personas in the wild often live as wall posters that nobody references in actual prioritization debates. + +**Job-framing.** Users hire products to do jobs. The job is what the user is trying to accomplish, not who the user is or what features they request. The framing surfaces struggling moments (when do users feel pulled toward an alternative); hire criteria (what makes them adopt a product); fire criteria (what makes them switch away). Output: product decisions grounded in user motivation rather than user description. + +The litmus test. Take a product decision the team is debating. Can JTBD ground the decision? "Should we build feature X?" Reframed: "What job would feature X help users do? What job is currently done badly that this addresses?" If the JTBD framing produces clearer arguments on both sides, the framing is earning its keep. If the JTBD framing just adds vocabulary without resolving the debate, the framing is ritual. + +--- + +## The job statement structure + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." + +**Situation.** The context, trigger, or moment when the job becomes active. Not a demographic; a moment. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck..." +- "When I get a customer escalation outside of business hours..." + +**Motivation.** What the user is trying to do in that situation. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage and respond without disrupting my evening too much..." + +**Outcome.** What success looks like; what the user is trying to achieve by doing the job. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." + +The structure forces specificity at all three levels. Vague situations, vague motivations, or vague outcomes produce job statements that drive nothing. + +Detail in [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md). + +--- + +## Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when the alternative tools they have feel inadequate, when they would actively prefer a different way of doing the job. + +**The signal.** Users describe friction in their current approach. They describe workarounds. They describe wishing they had something better. They describe specific moments when the current approach broke down. + +**The methodology.** Discovery interviews surface struggling moments through specific prompts: "Walk me through the last time you did X." "What was hardest about that?" "What would you have done differently if you could?" Specific recent moments produce richer data than abstracted descriptions of "how I usually do this." + +**The pattern recognition.** Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well in the market. + +**The pitfall.** Teams that interview without grounding in specific moments produce abstracted job descriptions that cannot drive decisions. "Users want to be more productive" is not a struggling moment; "I lost an hour on Tuesday assembling the board metrics from three different dashboards because none of them had the slice I needed" is. + +Detail in [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md). + +--- + +## Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground the framework in real decisions users make. + +**Hire criteria.** + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +**Fire criteria.** + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +**Why hire/fire matters.** + +- Hire criteria reveal what the product needs to be excellent at to win adoption. +- Fire criteria reveal what the product needs to maintain to retain users. +- The two are often different: features that win adoption are not always the features that prevent churn. + +**The methodology.** Customer interviews surface hire/fire through specific prompts: "What were you doing before you adopted X?" "What made you switch?" "If you switched away from X tomorrow, what would the trigger be?" Recent switch decisions are particularly rich; users remember the specific moment. + +Detail in [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md). + +--- + +## Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. + +**Functional dimension.** What the user is mechanically trying to accomplish. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." + +**Emotional dimension.** How the user feels (or wants to feel) doing the job. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." + +**Social dimension.** How the user wants to be perceived doing the job. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." + +**Why three dimensions matter.** + +- Products that win on functional alone often lose to alternatives that also serve emotional and social. +- Some product decisions hinge on emotional dimensions ("the user wants to feel in control"); functional analysis alone misses these. +- Social dimensions inform positioning more than functional descriptions do. + +**The discipline.** For each job statement, ask the three dimensions explicitly. Most early job statements are functional-only; the addition of emotional and social often reveals what the product actually needs to address. + +Detail in [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md). + +--- + +## Where JTBD adds clarity vs where it becomes ritual + +The honest framing. + +**Where JTBD genuinely earns its keep.** + +- **Discovery.** When research is grounded in struggling moments and hire/fire decisions, JTBD surfaces the user motivation that feature-list discovery misses. Discovery interviews structured around jobs produce richer data than ones structured around feature preferences. +- **Prioritization.** When the team is debating which work to prioritize, jobs ground the debate in what users are trying to accomplish. "Does this work help users do an important job better?" cuts through the politics of feature-request prioritization. +- **Positioning.** When marketing or sales is articulating what the product does, jobs frame the product as a way of accomplishing something the customer cares about, rather than as a feature list. + +**Where JTBD becomes ritual.** + +- **Job-statement workshops as deliverables.** The team runs a workshop, produces a wall of job statements, and never references the artifacts in subsequent decisions. The workshop became the deliverable; the analytical work did not happen. +- **Job statements substituted for personas without analytical rigor.** "We have JTBD now" but the team treats job statements as named characters (Job Bob, Job Alice) instead of as analytical tools. +- **Mandatory JTBD for every product question.** Every meeting starts with "what's the job?" Even when the question does not benefit from the framing. The methodology becomes a tax rather than a tool. +- **JTBD as compliance.** The org adopts JTBD because a leadership book or conference talk endorsed it; teams produce JTBD artifacts to show they are using the framework; nobody actually uses the framework to decide. + +**The honest signal.** If the team can show how a recent product decision was different because of JTBD analysis, the framework is earning its keep. If the team uses JTBD vocabulary but cannot trace decisions to JTBD analysis, the framework is ritual. + +--- + +## Applying JTBD to discovery, prioritization, positioning + +The three modes where JTBD genuinely contributes. + +**Discovery.** Structure interviews around recent struggling moments, hire decisions, and fire decisions. Gather job statements after the interviews from the data, not before. Cluster jobs across users. Name jobs from the clusters. Pair with `discovery-research-synthesis` for the broader synthesis discipline. + +Detail in [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md). + +**Prioritization.** When evaluating roadmap candidates, frame each candidate by the job(s) it addresses. Ask: which jobs is the product currently doing badly? Which candidates address those jobs vs adjacent or unrelated work? Pair with `roadmap-planning` for the broader prioritization discipline. + +Detail in [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md). + +**Positioning.** When articulating what the product is for, lead with the job rather than the features. "Help product teams synthesize discovery research into decisions" is a job framing; "AI-powered research synthesis with collaboration tools" is a feature framing. Pair with `creative-direction` and `brand-discovery` for the broader positioning work. + +Detail in [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md). + +- "We did the JTBD workshop but nothing changed in our roadmap." Job-statement workshop as deliverable; no analytical work after the workshop. +- "Our job statements all sound the same." Generic job statements; not grounded in specific struggling moments. Re-ground in interview data. +- "Our jobs read like feature requests." "When I am using product X, I want feature Y" is not a job; the job is what the user was trying to accomplish, independent of the product. +- "We have personas and jobs and they contradict each other." Personas are demographic; jobs are situational. They do not have to align; if they conflict, jobs usually carry more decision weight. +- "JTBD says we should build everything." Without prioritization across jobs, JTBD identifies many opportunities and does not pick. Pair with prioritization discipline. +- "We dropped JTBD because it became theater." Common; the recovery is JTBD as analytical tool, not JTBD as ritual. Use the framework where it earns its keep; do not force it everywhere. +- "Our job statements are functional only." Add emotional and social dimensions; many product decisions hinge on the latter two. +- "We cannot agree on the job." Often signals different segments with different jobs. Surface the segment differences. +- "Our marketing copy uses JTBD vocabulary but our product does not." Positioning-product gap; the marketing claim is not load-bearing in product decisions. + +--- + +## The framework: 12 considerations for JTBD framing + +When applying JTBD or auditing JTBD work, walk these 12 considerations. + +1. **Job-framing, not feature-list or persona-theater.** Users hire products to accomplish jobs. +2. **Job statement structure: situation, motivation, outcome.** Specific at all three levels. +3. **Struggling moments ground the jobs.** Specific recent moments, not abstractions. +4. **Hire criteria identified.** What makes users adopt the product over alternatives. +5. **Fire criteria identified.** What makes users switch away (or would). +6. **Functional, emotional, social dimensions surfaced.** All three; not functional only. +7. **Jobs derived from data, not workshop output.** Job statements emerge from interview data, not from whiteboard sessions. +8. **JTBD applied where it earns its keep.** Discovery, prioritization, positioning. Not as ritual. +9. **Segment differences in jobs surfaced.** When the same product is hired for different jobs by different segments. +10. **Decisions traceable to JTBD analysis.** Each major decision can be explained through the job framing. +11. **JTBD vocabulary not substituted for analytical work.** Vocabulary without analysis is ritual. +12. **Honest assessment of where JTBD does not help.** Some questions do not benefit from the framing; force-fitting produces ritual. + +The output of the framework is product decisions grounded in user motivation rather than user description, with the framing applied where it adds clarity and held back where it would become ritual. + +--- + +## Reference files + +- [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md) - The situation/motivation/outcome structure with worked examples. Common structural failures (vague situations, motivation as feature request, outcome as feature output). +- [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md) - Discovery prompts that surface struggling moments. Pattern recognition across users. The specific-moment vs abstraction distinction. +- [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md) - Methodology for surfacing hire and fire criteria. Why the two are often different. Recent-switch interview discipline. +- [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md) - Three dimensions per job. Why functional-only fails. Worked examples per dimension. Positioning implications of social dimension. +- [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md) - Discovery interview structure around jobs. Job clustering. Naming jobs from data. Pair with discovery-research-synthesis. +- [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md) - Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. Pair with roadmap-planning. +- [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md) - Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pair with creative-direction. +- [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md) - 9+ failure patterns with diagnoses and cures. The cross-cutting pattern: JTBD as ritual vs JTBD as analytical tool. + +--- + +## Closing: jobs over features + +The Jobs-to-be-Done framework is one of the most useful product methodologies available when applied with rigor, and one of the most performative when applied as ritual. The difference is in whether the framework drives decisions or decorates documentation. + +Jobs over features is a real shift in product thinking. Feature-list discovery treats users as preference-aggregators; persona archetypes treat users as demographic categories; job-framing treats users as people trying to accomplish things, where the product is one tool they hire (or fire) for the job. + +The teams that benefit from JTBD are the ones that take the analytical work seriously: grounding jobs in struggling moments, identifying hire and fire criteria, surfacing functional-emotional-social dimensions, deriving jobs from data, and applying the framing where it earns its keep. The teams that adopt JTBD vocabulary without the analytical work produce ritual. + +When in doubt about whether a JTBD application is real or ritual, ask: can a recent product decision be traced to the JTBD analysis, or did the JTBD work happen in parallel with decisions that were made on other grounds? If the former, JTBD is doing its work. If the latter, the framework is decoration. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-discovery.md b/skills/jtbd-framing/references/applying-jtbd-to-discovery.md new file mode 100644 index 0000000..cddb634 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-discovery.md @@ -0,0 +1,211 @@ +# Applying JTBD to discovery + +How JTBD shapes discovery interview structure, job clustering, and naming jobs from data. Pairs with `discovery-research-synthesis` for the broader synthesis discipline. + +JTBD's strongest contribution to discovery is structural: interviews grounded in struggling moments and hire/fire decisions produce richer data than interviews that ask about feature preferences or use cases. + +--- + +## Structuring discovery interviews around jobs + +The JTBD discovery interview structure differs from feature-elicitation interviews. + +**Feature-elicitation interview pattern.** + +- "What problems are you trying to solve?" +- "What features would help?" +- "What is your ideal product?" + +This structure produces user-prescribed solutions: feature requests, ideal-product fictions, and abstracted preferences. The data is hard to act on because users do not always know what would actually help. + +**JTBD interview pattern.** + +- "Walk me through the last time you did [task]. What happened? What was hardest?" +- "What were you doing before you adopted [current solution]? What made you switch?" +- "Tell me about a recent time when [task] went badly. What was different about that time?" +- "If you switched away from [current solution] tomorrow, what would the trigger be?" + +This structure grounds the data in specific moments and real decisions. Users describe their experience; the PM doing synthesis interprets what the experience implies. + +--- + +## Interview prompts that work + +**Recent specific moments.** + +- "Walk me through the most recent time you did [task]." +- "What was the last week when [task] cost you more time than usual?" +- "When was the last time [task] surprised you in a bad way?" + +**Hire decision prompts.** + +- "Tell me about the moment you decided to start using [product]." +- "What were you doing before? What made you switch?" +- "What alternatives did you consider? What ruled them out?" + +**Fire decision prompts (for users who switched).** + +- "Tell me about the moment you decided to switch away from [product]." +- "What was the alternative starting to look better? What tipped you?" +- "Looking back, why didn't you switch sooner?" + +**Workaround prompts.** + +- "What's something you do that takes longer than it should?" +- "What workarounds have you built?" +- "When was the last time you accepted a worse outcome because the better path was too painful?" + +--- + +## Interview prompts that fail + +**Hypothetical prompts.** + +- "What would your ideal product look like?" (produces fiction) +- "If you had a magic wand, what would you change?" (produces wishlist) +- "What features would you like?" (produces feature lists) + +**Abstracted prompts.** + +- "How do you usually do [task]?" (produces averaged descriptions) +- "What's your typical experience?" (loses the specifics) +- "What kind of user are you?" (produces self-categorization) + +**Leading prompts.** + +- "Don't you find [feature] frustrating?" (confirms the team's hypothesis) +- "Wouldn't it be great if [feature]?" (produces agreement, not data) + +--- + +## The interview length and depth + +JTBD interviews benefit from depth. Surface answers come quickly; deeper jobs surface in the second half of an interview. + +**Typical structure.** + +- Minutes 0-15: warm-up, general context, what the user does and how their work fits together. +- Minutes 15-45: the recent specific moments, walk-throughs, struggling moments. The richest data emerges here. +- Minutes 45-60: hire and fire decisions, alternatives considered, switch decisions. +- Minutes 60-75 (when warranted): emotional and social dimensions, how the user wants to be perceived doing the work. +- Minutes 75-90: closing prompts, what the user wishes was different, what they would have done differently. + +**The depth payoff.** Users open up after 30-40 minutes. The struggling moments they describe in the second half are usually richer than the first-half answers. Cutting interviews short at 45 minutes loses the depth. + +**The 90-minute upper bound.** Beyond 90 minutes, fatigue degrades data quality. Schedule for 90; complete in 60-75; leave room for the depth without forcing it. + +--- + +## Job clustering from interview data + +After interviews, jobs emerge through clustering (per the synthesis sequence in `discovery-research-synthesis`). + +**The clustering work.** + +- Tag struggling moments and hire/fire decisions across interviews. +- Cluster moments that share underlying jobs (the user was trying to accomplish the same thing). +- Each cluster becomes a candidate job. +- Name the job from the cluster, not from a pre-built list. + +**Common clustering patterns.** + +- Multiple users described the same kind of friction in similar contexts. The cluster becomes one job. +- Multiple users described different surface-level frictions but the same underlying motivation and outcome. The cluster reveals a job that surfaces differently across users. +- One user's described moment is unique. May be an edge case, may be a job worth surfacing as smaller-segment. + +--- + +## Naming jobs from data + +Jobs are named from the cluster, not from a pre-built taxonomy. + +**The naming process.** + +- Read the cluster's contributing moments. +- Identify the situation, motivation, and outcome that recurred. +- Write the job statement: "When [situation], I want to [motivation], so I can [outcome]." +- Test the statement against the source moments: does it capture what users were trying to accomplish? + +**The iteration discipline.** First-pass job statements are usually too narrow or too broad; refine through iteration. + +**Worked example.** A cluster of moments around quarterly board prep: + +- Multiple users described assembling data from multiple sources. +- Multiple described uncertainty about whether they had the right slice. +- Multiple described the time pressure and the disruption to other work. +- Multiple described wanting to walk into the board with confidence. + +First-pass job statement: "When preparing the board deck, I want to assemble data from multiple sources, so I can present numbers correctly." + +Second-pass refinement: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The second pass captures the situation more specifically (quarterly business reviews, not just any board deck), the motivation more specifically (coherent narrative I can defend, not just data assembly), and the outcome more specifically (answer questions confidently without grinding the night before, not just present numbers correctly). + +--- + +## How many jobs emerge from typical discovery + +Strong discovery cycles often surface 3-8 jobs across the research batch. + +**Smaller numbers (1-2 jobs).** May indicate the discovery scope was narrow (only one user task investigated) or the synthesis under-clustered. + +**Mid numbers (3-8 jobs).** Typical for substantive discovery cycles. Jobs cover the major user motivations the research surfaced. + +**Larger numbers (10+ jobs).** May indicate over-clustering (each cluster is small and the overall synthesis is fragmented) or genuine breadth (the research investigated multiple distinct user contexts). + +The discipline. Job count should reflect the underlying patterns the data reveals, not a target number. Force-fitting to 7 jobs because "that feels right" produces synthesis that does not match the data. + +--- + +## Pairing JTBD discovery with quantitative validation + +Qualitative job patterns often warrant quantitative validation. + +**The pattern.** + +- Job statement claims a specific frequency or severity ("users hit this friction in 40% of attempts"). +- Quantitative data validates: analytics shows configuration step abandonment rate; survey data confirms the segment proportion; product instrumentation captures the in-the-moment frequency. +- If validation confirms: the job statement is strongly supported. +- If validation contradicts: revise the job statement to reflect the data. + +**Pair with `experiment-design`** for rigorous validation methodology and `product-analytics-setup` for the instrumentation that makes validation possible. + +--- + +## When JTBD discovery does not fit + +Some discovery does not benefit from JTBD framing. + +**Greenfield categories.** When the product is a category-defining product, users may not have struggling moments because the alternative is not having the capability at all. JTBD framing is useful but may need to be supplemented with broader product strategy. + +**Highly novel use cases.** When users have not yet developed mental models for the use case (e.g., new technology categories), struggling moments may not exist because the activity itself does not exist. Discovery may need to focus on adjacent activities and what users would do if the new capability existed. + +**Pure positioning research.** When the discovery is about how to position an existing product, hire and fire criteria interviews are useful, but emotional and social dimensions of positioning matter as much as the JTBD-framed jobs. + +**The discipline.** JTBD is a tool, not a mandate. When the discovery question fits the framework, use it. When it does not fit cleanly, supplement with other discovery techniques. + +--- + +## Common JTBD-discovery failures + +**Eliciting feature lists instead of jobs.** Interview prompts ask "what features do you want" rather than "what are you trying to accomplish." Restructure prompts. + +**Pre-built job taxonomy.** Researchers arriving with named jobs and slotting interview data into them. Jobs should emerge from data; pre-built taxonomies confirm what the team already thinks. + +**Skipping struggling moments.** Interviews capture preferences and use-cases without grounding in specific friction events. Add struggling-moment prompts. + +**Skipping hire/fire decisions.** Interviews ask about current usage but not about adoption or switch decisions. Add hire and fire prompts. + +**Job statements written from intuition rather than data.** Researchers writing jobs based on what they think users are trying to do, without grounding in interview clusters. + +**Force-fitting all data to JTBD.** Some interview data does not fit the JTBD framing cleanly; the team forces it in anyway. Better: surface what JTBD captures and supplement with other framings for the rest. + +--- + +## Methodology-level choices that stay in the public skill + +The interview structure that grounds in jobs. Prompts that work and fail. Interview length and depth. Job clustering from interview data. Naming jobs from data. Typical job counts. Pairing with quantitative validation. When JTBD discovery does not fit. Common failures. + +## Implementation choices that stay internal + +Specific interview templates. Specific recording and tagging tools. Specific synthesis tooling for job clustering. Specific recruitment criteria. The team's own conventions for interview cadence and batch sizing. These vary by team. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-positioning.md b/skills/jtbd-framing/references/applying-jtbd-to-positioning.md new file mode 100644 index 0000000..8d40f19 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-positioning.md @@ -0,0 +1,201 @@ +# Applying JTBD to positioning + +Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pairs with `creative-direction` and `brand-discovery` for the broader positioning work. + +JTBD's contribution to positioning is the lead message: positioning that names the job the product helps users accomplish creates affinity in ways feature lists do not. The functional, emotional, and social dimensions of jobs all inform positioning differently. + +--- + +## Job-led vs feature-led positioning + +The two positioning approaches. + +**Feature-led positioning.** + +- "AI-powered analytics with collaborative dashboards and integrations." +- "Cloud-native CRM with automation and reporting." +- "Project management software with timelines, kanban, and integrations." + +Characteristics: lists features; competes on feature comparison; gets compared head-to-head with alternatives that have similar feature lists; produces buyer behavior of feature-checklist evaluation. + +**Job-led positioning.** + +- "Help product teams synthesize discovery research into decisions." +- "The CRM your sales team will actually use because it stays out of their way." +- "Run the project, not the project management tool." + +Characteristics: names what the product helps users accomplish; competes on outcome rather than feature parity; produces buyer behavior of job-fit evaluation; harder to copy because the positioning is built on understanding the job. + +**The trade-off.** Feature-led positioning is easier to write and easier for buyers to evaluate. Job-led positioning is harder to write but produces stronger affinity and is more durable to feature-parity competition. + +--- + +## When job-led positioning works + +Job-led positioning works best when: + +- The product addresses a job that users currently do badly with alternatives. +- The job has emotional or social dimensions that the positioning can serve. +- The user can recognize themselves in the job description. +- The market category is mature enough that feature comparison is no longer differentiating. + +Job-led positioning is less effective when: + +- The product is a new category and users do not yet recognize the job. +- The product is a commodity where job-fit is similar across alternatives. +- The buyer is not the user, and the buyer evaluates on different criteria than job-fit. + +--- + +## The lead message structure + +The lead message is the first thing prospects encounter (homepage hero, ad headline, sales pitch opener). + +**Job-led lead message structure.** + +- "[Product/category] for [user trying to do job in situation], so [outcome]." +- "[Action verb describing the job] without [the friction users currently encounter]." +- "[Outcome the product produces] for [user in situation]." + +**Worked examples.** + +- "Help product teams synthesize discovery research into decisions, not deck performance." +- "Run quarterly business reviews without spending Sunday night reconciling spreadsheets." +- "Onboard new engineers without becoming their full-time guide." + +Each example names a job, an outcome, and either a contrast (without the friction) or a quality (the way the product accomplishes the job). + +--- + +## Functional, emotional, social in positioning + +Positioning leans on different dimensions of the job for different effects. + +**Functional dimension in positioning.** + +- "[Product] does [job]." Direct and informative; lower-affinity. +- Worked example: "Synthesize discovery research from interview transcripts and support tickets." + +Functional dimension positioning is useful for product details, not for lead messages. Lead messages on functional alone compete on feature comparison. + +**Emotional dimension in positioning.** + +- "[Product] lets you do [job] feeling [desired emotional state]." +- Worked example: "Run discovery cycles feeling in control, not buried in transcripts." + +Emotional dimension positioning creates affinity. Users recognize the emotional state they want and connect with positioning that names it. + +**Social dimension in positioning.** + +- "[Product] for [user identity]." +- Worked example: "For PMs who run discovery seriously." + +Social dimension positioning creates identity affinity. Users want to belong to the kind of users the positioning describes. This dimension is often the strongest for positioning because it is hardest to copy and creates the most durable affinity. + +**The composition.** Strong positioning often combines all three dimensions: a functional lead with emotional and social undertones. "Run discovery cycles for PMs who take synthesis seriously, without burying yourself in transcripts." Functional (run discovery cycles), social (PMs who take synthesis seriously), emotional contrast (without burying yourself in transcripts). + +--- + +## Avoiding job-positioning that misses + +Job-led positioning fails when the named job does not match the user's actual situation. + +**The pattern.** Marketing crafts a job-led message that sounds compelling but does not match how target users describe their work. Users do not recognize themselves; the positioning underperforms. + +**Worked failure example.** A productivity SaaS positions as "Eliminate the chaos in your day." + +The pattern. The job named (eliminating chaos) is too abstract; users describe specific frictions ("I cannot find the right meeting notes when I need them; I spend 20 minutes a day reconciling calendar conflicts; I miss commitments because tasks are scattered across tools"). The positioning is generic; users cannot recognize their specific situation. + +**The cure.** Ground positioning in specific job statements that emerged from user research. The positioning should sound like users describing their own work, not like marketing describing users. + +--- + +## Positioning testing for JTBD-led messages + +Job-led positioning benefits from user testing. + +**The test.** Show the positioning to target users. Ask: + +- "Does this describe your work?" +- "Would you keep reading this?" +- "What product would you expect to be behind this positioning?" + +**What good responses look like.** + +- "Yes, that's exactly what I do." (positive recognition) +- "I would want to see what this is." (interest signal) +- "It sounds like a [accurate product description]." (the positioning communicates accurately) + +**What bad responses look like.** + +- "I'm not sure this applies to me." (mismatch) +- "It sounds generic." (not specific enough to the job) +- "I expect this to be a [different product type]." (positioning misleads) + +**The iteration.** Positioning often improves through 2-3 rounds of testing and revision. The ground-truth from target users surfaces the gap between what marketing wrote and what users recognize. + +--- + +## Positioning across multiple jobs + +Many products serve multiple jobs. Positioning must decide whether to lead with one job or surface multiple. + +**Lead-with-one approach.** + +- Pick the most differentiating, most strategically important job. +- Lead with that job in the primary positioning. +- Surface other jobs in secondary positioning (feature pages, segment-specific pages). + +**Worked example.** A productivity SaaS that serves task management, team coordination, and reporting jobs: + +- Primary positioning leads with team coordination (the most strategic, most differentiating job). +- Feature pages address task management for users who land there. +- Reporting positioning lives on a dedicated page for evaluators looking specifically for that job. + +**Lead-with-many approach.** + +- The product genuinely serves several jobs equally; leading with one would mislead. +- Use a multi-job message: "[Product] for [job A], [job B], and [job C]." +- Risk: looks like a feature list dressed in job language. + +**The discipline.** Most products benefit from leading with one job and supplementing. Lead-with-many positioning often collapses into "do everything" messaging that creates no specific affinity. + +--- + +## Positioning for jobs vs positioning for users + +JTBD positioning leads with jobs; persona positioning leads with user identity. + +**Job-led positioning.** "Help product teams synthesize discovery research into decisions." + +**Persona-led positioning.** "For senior product managers at high-growth SaaS companies." + +The two can compose. Strong positioning often pairs job and identity: "Help senior PMs at high-growth SaaS companies synthesize discovery research into decisions." + +**The discipline.** Lead with the job (what the user is trying to do); add identity (who the user is) to create the affinity layer. Identity-only positioning is persona theater; job-only positioning may not create enough affinity. Job + identity is often the strongest form. + +--- + +## Common JTBD-positioning failures + +**Job-led messages that are too abstract.** "Eliminate the chaos in your day" is job-flavored but does not name a specific job. Replace with the specific job from research. + +**Feature-led messages dressed in job language.** "Use our analytics to make better decisions" is feature-led; "make better decisions" is too generic to be a job. + +**Job-led positioning that does not match user vocabulary.** Marketing wrote the positioning without grounding in user research; users do not recognize the language. + +**Lead-with-many positioning that becomes "do everything."** Multiple jobs surfaced equally; positioning loses specificity. + +**Positioning ignores the social dimension.** Strong positioning often leans on social dimension; positioning that omits it competes only on functional and emotional. + +**Positioning not user-tested.** Marketing crafts the positioning in isolation; target users have not validated that they recognize themselves in it. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led vs feature-led distinction. When job-led works and does not. The lead message structure. Functional, emotional, social in positioning. Avoiding job-positioning that misses. Positioning testing methodology. Positioning across multiple jobs. Job vs persona positioning. Common failures. + +## Implementation choices that stay internal + +Specific positioning frameworks the team uses. Specific copy templates. Specific A/B testing setups for positioning variants. Specific user-testing methodologies. The team's own conventions for primary vs secondary positioning. These vary by team and brand discipline. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md b/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md new file mode 100644 index 0000000..57c1a53 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md @@ -0,0 +1,206 @@ +# Applying JTBD to prioritization + +Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. The framing that cuts through feature-list politics. + +JTBD's contribution to prioritization is grounding the debate in user motivation rather than feature requests or stakeholder volume. Pairs with `roadmap-planning` for the broader prioritization discipline. + +--- + +## The job-led prioritization frame + +Each roadmap candidate gets evaluated by the jobs it addresses. + +**The questions.** + +- Which jobs is the product currently doing badly? +- Which roadmap candidates address those jobs vs adjacent or unrelated work? +- Which jobs matter most to the product's strategy and user base? +- What is the cost of addressing each candidate vs the value of the job improvement? + +**Why this frame works.** + +- It grounds prioritization in what users are trying to accomplish, not in what features they happen to have requested. +- It cuts through stakeholder politics: a roadmap candidate's value is measured against jobs, not against who is requesting it. +- It makes "we should not build this" defensible: candidates that do not address a load-bearing job get deprioritized clearly. + +**The compose-with-strategy discipline.** Job-led prioritization is downstream of strategy. The team needs to know which jobs matter for the product's market position; not all jobs are equally strategic. Pair with broader strategy work for the upstream framing. + +--- + +## Identifying jobs the product does badly + +The starting point for job-led prioritization. + +**The methodology.** + +- For each major job the product is meant to serve, evaluate how well it currently does the job. +- Use multiple inputs: user research (struggling moments, fire criteria), support data (where users hit friction), competitive analysis (where alternatives are stronger), in-product analytics (where users abandon). +- Score or rank jobs by how well they are currently served. Jobs done badly are candidates for prioritization investment. + +**Worked example.** A team productivity SaaS evaluating four core jobs: + +- Job A (creating tasks): well-served. Low priority for new investment. +- Job B (collaborating on tasks across teams): partially served. Some friction; alternatives are stronger; users describe workarounds. +- Job C (reporting on team progress): poorly served. High struggling-moment frequency; users export to spreadsheets; competitive products do this better. +- Job D (integrating with external tools): partially served. Friction at scale; mid-size customers describe pain. + +The badly-served jobs (B, C, D) are candidates for prioritization. Job A is not a fertile area for new investment. + +--- + +## Mapping roadmap candidates to jobs + +Each roadmap candidate gets associated with the jobs it addresses. + +**The mapping.** + +- Roadmap candidate: "Build cross-team task assignment with permissions." + - Job addressed: Job B (collaborating across teams). + - Job impact: addresses the core friction users describe; closes the gap with stronger alternatives. + +- Roadmap candidate: "Add custom report builder." + - Job addressed: Job C (reporting on team progress). + - Job impact: enables the reporting users currently export to spreadsheets to do. + +- Roadmap candidate: "Build mobile app for task creation." + - Job addressed: Job A (creating tasks) on mobile context. + - Job impact: extends a well-served job to a context where it currently is not served. Useful but not addressing a struggling job. + +- Roadmap candidate: "Redesign sidebar navigation." + - Job addressed: unclear. Possibly across multiple jobs. + - Job impact: hard to evaluate without clarification on which job this serves. + +**The fourth example signals a problem.** Roadmap candidates that do not clearly address a specific job often get prioritized on internal preferences rather than user value. The job mapping forces clarity: what job does this candidate serve, and how badly is that job currently being done? + +--- + +## The "no job, no priority" discipline + +Roadmap candidates that do not clearly address a job tied to user motivation often should not be prioritized. + +**The pattern.** + +- Candidate: "Migrate to a new internal framework." + - Job addressed: none directly; serves engineering velocity. + - Disposition: may be valuable for engineering reasons; do not prioritize on user-job grounds. If the team values engineering velocity, prioritize it on that basis explicitly. + +- Candidate: "Add dark mode." + - Job addressed: weak (some users describe preference). + - Disposition: low job-priority unless dark mode addresses an emotional dimension of jobs the team is also addressing. + +- Candidate: "Improve admin permissions." + - Job addressed: depends on which segment is asking. For enterprise: addresses fire criteria around compliance. For small teams: weak job impact. + - Disposition: prioritize for the segment whose job it serves; do not generalize. + +**The discipline.** Surface the job each candidate addresses (or does not). Candidates that do not serve jobs may still be valuable but should be prioritized on different grounds. The candidates the team can defend on jobs are the ones with the clearest user-value case. + +--- + +## Prioritization across jobs + +Different jobs have different strategic weights. The roadmap should reflect the strategy. + +**The questions.** + +- Which jobs are most load-bearing for the product's market position? +- Which jobs are most differentiated from competitors? (Where addressing the job better produces lasting advantage.) +- Which jobs serve the segments the strategy is targeting? +- Which jobs are growing in importance based on market trends? + +**Worked example.** A team productivity SaaS in mid-market growth: + +- Job B (cross-team collaboration): high strategic weight. Mid-market customers grow into multi-team workflows; the product needs to scale with them. +- Job C (reporting): high strategic weight. Mid-market customers need reporting that small-team customers did not require. +- Job D (integration): medium strategic weight. Important for retention; less differentiating than B and C. +- Job A (task creation): low strategic weight for new investment. Already served; not where competitors are winning. + +The strategic weighting biases the roadmap: B and C get more capacity than D; D gets more than A. + +--- + +## The "what job is this serving" review for in-flight work + +Job-led prioritization applies to existing work, not just new candidates. + +**The review.** + +- Take in-flight roadmap items. +- For each, ask: what job is this serving? How well does the work address that job? +- Items that cannot articulate a clear job may be candidates for re-scoping or cancellation. + +**The honest case.** Many roadmap programs accumulate work that started for reasons unrelated to user jobs (engineering preference, executive request, "we said we would"). The job review surfaces these and creates space to reconsider. + +**The kindness.** The review is not aimed at blame; sometimes work was committed before the team had the JTBD framing. The cure is reconsidering, not punishing. + +--- + +## Avoiding the JTBD-prioritization-religion failure + +JTBD as prioritization framework can become rigid in ways that hurt the team. + +**Patterns to avoid.** + +- Mandatory job-mapping for every roadmap item, including small bug fixes. The framework becomes overhead for low-value items. +- Treating job-impact estimates as precise numbers. Job-impact is often qualitative; pretending precision misleads. +- Over-weighting JTBD to the exclusion of other prioritization inputs. Strategic, technical, and operational considerations matter alongside jobs. + +**The discipline.** Use JTBD where it adds clarity to prioritization debates. Do not force the framework where it adds overhead without value. + +--- + +## Worked prioritization example + +A quarterly roadmap review at a team productivity SaaS. + +**Available capacity.** 5 large initiatives. + +**Candidates with job mapping.** + +1. Cross-team task assignment with permissions (Job B; high impact; high strategic weight). +2. Custom report builder (Job C; high impact; high strategic weight). +3. Mobile app for task creation (Job A on mobile; medium impact; low strategic weight). +4. Sidebar redesign (no clear job; serves general usability). +5. Slack integration upgrade (Job D; medium impact; medium strategic weight). +6. Onboarding redesign (multiple jobs; high impact on hire criteria for new customers). +7. Admin role overhaul (Job D for enterprise; high impact for that segment; matches enterprise expansion strategy). +8. Migration to new search backend (technical; serves multiple jobs indirectly). + +**Prioritization decision (5 of 8).** + +- Cross-team task assignment (1): yes. Top job priority. +- Custom report builder (2): yes. Top job priority. +- Onboarding redesign (6): yes. High hire-criteria impact. +- Admin role overhaul (7): yes. Enterprise strategy alignment. +- Migration to new search backend (8): yes. Technical foundation; serves multiple jobs. + +**Deferred.** + +- Mobile app for task creation (3): Job A is well-served on desktop; mobile is convenient but not high-priority. +- Sidebar redesign (4): no clear job. Reconsider for next cycle if a specific job emerges. +- Slack integration upgrade (5): Job D is medium-priority; can wait a quarter. + +**The defense.** The decisions can be explained on jobs and strategy. Stakeholders who pushed for items that did not make the cut can hear a clear rationale. The cut items can be reconsidered next quarter against jobs at that point. + +--- + +## Common JTBD-prioritization failures + +**Job-mapping all candidates without segmenting strategic weight.** Jobs treated as equal; the team picks based on impact estimates that obscure which jobs actually matter for strategy. + +**No job assigned to many candidates.** The team treats job mapping as optional; non-mapped candidates get prioritized on volume of requests or stakeholder preference. + +**Job-impact precision theater.** Numerical scores for job impact (Job B: 8/10) when the underlying assessment is qualitative. Decisions look quantitative but are not. + +**Forcing all decisions through JTBD.** Some decisions (technical migrations, strategic bets) do not benefit from JTBD framing. Force-fitting produces bad decisions. + +**JTBD as cover for predetermined prioritization.** The team ranks items by JTBD theater after deciding what to prioritize on other grounds. The framework becomes documentation rather than decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led prioritization frame. Identifying jobs done badly. Mapping candidates to jobs. The "no job, no priority" discipline. Strategic weighting across jobs. The in-flight work review. Avoiding JTBD-religion. Worked prioritization example. Common failures. + +## Implementation choices that stay internal + +Specific roadmap-tracking tools. Specific scoring rubrics for job impact. Specific stakeholder-review formats. Specific job-strategic-weight reviews. The team's own conventions for prioritization meetings. These vary by team and tooling. diff --git a/skills/jtbd-framing/references/common-jtbd-failures.md b/skills/jtbd-framing/references/common-jtbd-failures.md new file mode 100644 index 0000000..a36a25e --- /dev/null +++ b/skills/jtbd-framing/references/common-jtbd-failures.md @@ -0,0 +1,166 @@ +# Common JTBD failures + +Nine-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most JTBD failures share a single root, which is treating JTBD vocabulary as a substitute for analytical work. + +--- + +## Failure 1: We did the JTBD workshop but nothing changed in our roadmap + +**Symptom.** A workshop was held. Job statements were produced. The wall has Post-its. The next quarter's roadmap looks the same as the prior quarter's. + +**Diagnosis.** Job-statement workshop as deliverable. The workshop became the artifact; the analytical work that should have followed never happened. + +**Cure.** Treat job statements as analytical input, not as workshop output. Re-evaluate roadmap candidates against the jobs. Apply the "no job, no priority" discipline. The roadmap should look different than it would have looked without the JTBD work; if it does not, the work is ritual. + +**Prevention.** Do not run JTBD workshops as standalone events. Pair the workshop with prioritization or positioning work that uses the job statements as input. Without downstream application, the workshop produces ritual. + +--- + +## Failure 2: Our job statements all sound the same + +**Symptom.** Multiple job statements share similar situations, motivations, or outcomes. They are hard to distinguish. + +**Diagnosis.** Generic job statements; not grounded in specific struggling moments. The statements were written from intuition rather than from interview data. + +**Cure.** Re-ground in interview data. Each job should be traceable to specific moments in specific interviews. Statements that cannot be traced are projections; rewrite from the ground up. + +**Prevention.** Job statements emerge from clustering, not from whiteboard sessions. The clustering work surfaces the distinctions; whiteboard sessions tend to produce homogeneous statements. + +--- + +## Failure 3: Our jobs read like feature requests + +**Symptom.** Job statements describe what users want from the product, not what users are trying to accomplish. + +**Examples that fail.** + +- "When using the dashboard, I want to see all my metrics on one screen." +- "When in the settings page, I want to configure permissions easily." + +The motivations and outcomes describe product features, not job-doing. + +**Diagnosis.** Product-bound job statements. The motivation is bound to the product; the outcome is feature output. + +**Cure.** Apply the product-independence test. The motivation should make sense without naming any specific product. If the user is "in the dashboard," they are using a product; the underlying job is what they are trying to accomplish that brought them to the dashboard. + +**Prevention.** During job-statement writing, check each statement: could this make sense if the user had no product to use? If no, rewrite the motivation and outcome to describe the underlying job. + +--- + +## Failure 4: We have personas and jobs and they contradict each other + +**Symptom.** The team has both demographic personas and JTBD job statements. Decisions get made differently depending on which framework the conversation invokes. + +**Diagnosis.** Personas are demographic; jobs are situational. They serve different purposes. Conflict often signals confusion about which framework drives which decisions. + +**Cure.** Decide the role of each framework. JTBD is usually better for product decisions (what to build, how to prioritize); demographic personas are sometimes useful for marketing audience targeting (who to advertise to). Use each where it adds clarity; do not require both for every decision. + +**Prevention.** When introducing JTBD, surface the relationship to existing personas. If personas are not driving decisions, consider deprecating them. If personas are useful for specific marketing work, keep them but separate from product decision-making. + +--- + +## Failure 5: JTBD says we should build everything + +**Symptom.** Job statements identify many job-improvement opportunities. The team cannot pick. The roadmap becomes a list of all the jobs to address. + +**Diagnosis.** Without prioritization across jobs, JTBD identifies opportunities but does not pick. The framework is doing its discovery work; it is not doing prioritization work. + +**Cure.** Pair JTBD with strategic weighting (which jobs matter most for the strategy?), capacity constraints (what can the team actually deliver?), and impact estimation (which job improvements move the needle most?). JTBD informs prioritization but does not replace prioritization frameworks. + +**Prevention.** When applying JTBD to roadmap prioritization, surface the strategic-weight question explicitly. Some jobs matter more than others; the team's strategy decides which ones. + +--- + +## Failure 6: We dropped JTBD because it became theater + +**Symptom.** The team adopted JTBD; produced workshop artifacts; never used them in decisions; and concluded JTBD does not work. + +**Diagnosis.** JTBD as ritual produced ritual. The framework was applied without the analytical work. + +**Cure.** Reintroduce JTBD as analytical tool, not as ritual. Apply where it earns its keep (discovery, prioritization, positioning). Skip the artifacts that decorate without informing decisions. Demonstrate the value through specific decisions JTBD informed. + +**Prevention.** When introducing JTBD, frame it as a tool for specific decisions, not as a methodology to be adopted org-wide. Start with one application (one discovery cycle, one prioritization debate) and show value before expanding. + +--- + +## Failure 7: Our job statements are functional only + +**Symptom.** Job statements describe mechanical tasks. The product strategy prioritizes functional features. The product wins on functional dimension and loses to alternatives on emotional and social. + +**Diagnosis.** Functional-only synthesis. The interview prompts and synthesis stayed at the functional dimension; emotional and social dimensions were not surfaced. + +**Cure.** Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing job statements. Re-evaluate strategy considering all three dimensions. + +**Prevention.** Interview structure should explicitly prompt for all three dimensions. Synthesis should surface all three. Single-dimension job statements are usually a sign that prompts or synthesis missed dimensions. + +--- + +## Failure 8: We cannot agree on the job + +**Symptom.** Different team members describe the user's job differently. The team debates the framing; the framing does not converge. + +**Diagnosis.** Often signals different segments with different jobs. The team is right that there is more than one job; they are wrong to think there should be one consensus job. + +**Cure.** Surface the segment differences. The same product may serve different jobs for different segments. Naming the segments and their distinct jobs resolves the disagreement and improves strategy. + +**Prevention.** When defining jobs, ask explicitly: do all target users share this job, or does it differ across segments? Often the answer is "differs"; surface the segments rather than forcing consensus. + +--- + +## Failure 9: Our marketing copy uses JTBD vocabulary but our product does not + +**Symptom.** Marketing positioning describes the job the product helps users accomplish. The product itself is built around feature-list thinking. Users adopt expecting one experience and encounter another. + +**Diagnosis.** Positioning-product gap. The marketing claim is not load-bearing in product decisions; product decisions are still made on feature-list grounds. + +**Cure.** Either align product decisions to the JTBD positioning (apply JTBD to prioritization), or revise the positioning to match what the product actually does. The mismatch erodes trust over time. + +**Prevention.** When introducing JTBD-led positioning, simultaneously apply JTBD to product strategy. Positioning that describes what the product is becoming should drive what the product becomes. + +--- + +## Failure 10: JTBD vocabulary substituted for analytical work + +**Symptom.** The team uses JTBD language ("the job," "struggling moment," "hire criteria") in conversations but cannot trace decisions to specific JTBD analyses. + +**Diagnosis.** Vocabulary without analysis is ritual. The framework provides language; the language does not produce decisions on its own. + +**Cure.** Audit recent decisions: which were grounded in JTBD analysis (specific job statements, specific hire/fire criteria, specific user research)? Which used JTBD vocabulary as decoration around decisions made on other grounds? Re-anchor in analytical work. + +**Prevention.** When the team uses JTBD vocabulary, surface the underlying analytical work explicitly. "What job is this serving?" should produce a specific job statement traceable to research, not a hand-wavy answer. + +--- + +## Failure 11: Force-fitting JTBD where it does not help + +**Symptom.** Every product question gets framed in JTBD. Even questions where the framing adds no clarity. + +**Diagnosis.** JTBD as mandate. The framework gets applied universally; tax for the team; signal-to-noise drops. + +**Cure.** Use JTBD where it earns its keep. Some questions (technical migrations, infrastructure decisions, urgent bug fixes) do not benefit from JTBD framing. Apply other frameworks where they fit better; apply JTBD where it fits. + +**Prevention.** Establish that JTBD is one tool among many. Frame the question first; then pick the framework. Do not start with the framework and look for questions to apply it to. + +--- + +## The cross-cutting pattern + +Most JTBD failures share a single root: treating JTBD vocabulary as a substitute for analytical work. + +The vocabulary is easy: "job," "struggling moment," "hire criteria," "fire criteria," "functional, emotional, social dimensions." Teams adopt the vocabulary and signal that they have adopted JTBD. + +The analytical work is hard: structured interviews, struggling-moment grounding, clustering across users, naming jobs from data, surfacing all three dimensions, applying the framework to specific decisions, validating that the analysis informs decisions. + +When the vocabulary is adopted without the analytical work, JTBD produces ritual. When the analytical work is done with discipline, JTBD produces decisions and the vocabulary is incidental. + +The fix for almost any JTBD failure starts with the same question: where is the analytical work happening, and what decisions is it informing? If the answers are clear, the framework is doing its job. If the answers are vague, the framework is ritual. + +--- + +## Methodology-level choices that stay in the public skill + +The eleven failure patterns with diagnoses and cures. The cross-cutting vocabulary-vs-analysis pattern. The discipline of using JTBD where it earns its keep. + +## Implementation choices that stay internal + +Specific JTBD-application audits. Specific reviewer training on failure detection. Specific tooling that surfaces JTBD ritual vs analytical use. The team's own conventions for catching ritual before it spreads. These vary by team. diff --git a/skills/jtbd-framing/references/functional-emotional-social-dimensions.md b/skills/jtbd-framing/references/functional-emotional-social-dimensions.md new file mode 100644 index 0000000..4460b0b --- /dev/null +++ b/skills/jtbd-framing/references/functional-emotional-social-dimensions.md @@ -0,0 +1,201 @@ +# Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. The omission of emotional and social dimensions is one of the most common JTBD failure modes. + +--- + +## The three dimensions + +### Functional + +What the user is mechanically trying to accomplish. + +**Worked examples.** + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." +- "Prepare a customer-facing announcement for a feature launch." +- "Reconcile vendor payments at month-end." + +**Characteristics.** + +- Describable in task language. +- Often the easiest dimension to surface in interviews. +- Often the dimension product teams default to. + +--- + +### Emotional + +How the user feels (or wants to feel) doing the job. + +**Worked examples.** + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." +- "Comfortable that the announcement will not surprise anyone in a way that lands badly." +- "Confident that the reconciliation is correct without spending the whole week verifying." + +**Characteristics.** + +- Describes the user's internal experience. +- Often surfaces through how users describe what went well or badly. +- Distinguishes products that feel good to use from products that work mechanically but feel exhausting. + +--- + +### Social + +How the user wants to be perceived doing the job. + +**Worked examples.** + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." +- "Seen by customers as transparent and proactive, not evasive." +- "Seen by audit as someone whose work the team can trust without re-checking." + +**Characteristics.** + +- Describes how the user wants others to perceive their work. +- Often the most overlooked dimension. +- Drives positioning more than the other two dimensions. + +--- + +## Why three dimensions matter + +Products that win on functional alone often lose to alternatives that also serve emotional and social. + +**Worked example.** Two analytics tools serving the same functional job. + +- Tool A: technically thorough, full-featured, hard to learn, intimidating-feeling. Functional excellence; weak emotional dimension. +- Tool B: focused on the specific job, faster to confidence, feels manageable. Slightly less functional power; stronger emotional dimension. + +For users who could complete the job with either, Tool B often wins. The emotional dimension (feeling in control, confidence) tipped the decision even though Tool A's functional dimension was technically stronger. + +**Worked example, social dimension.** A board reporting tool serving CFOs. + +- Tool A: produces correct numbers; layout is utilitarian. +- Tool B: produces the same numbers; layout signals "this CFO knows their numbers" through design. + +The social dimension (how the CFO is perceived presenting from this tool) tips many decisions. Tool B is hired in part because it makes the CFO look good in front of the board. + +--- + +## Surfacing emotional and social dimensions in interviews + +Emotional and social dimensions often surface only when the interview prompts for them. + +**Functional prompts.** "Walk me through the task. What did you do?" + +**Emotional prompts.** "How did you feel doing this? What was the most stressful part? When did you feel relieved?" + +**Social prompts.** "Who else was watching this work? How did you want to come across to them? What did you do specifically because of how it would look?" + +**The interview discipline.** Surface all three dimensions; do not assume the functional dimension is the whole job. Many users will not volunteer emotional or social dimensions; the prompts surface them. + +--- + +## When functional alone is sufficient + +Some jobs are dominantly functional and the emotional/social dimensions are minor. + +**Worked example.** A backup utility that runs in the background. The functional dimension (data is backed up correctly) is the whole job; the user does not have an emotional relationship with the tool and is not perceived doing it. + +**The discipline.** Some products are appropriately functional-only. The team's job is to recognize when the dimensions matter and when they do not. Force-fitting emotional and social dimensions onto purely functional jobs produces false signal. + +--- + +## Functional-only failure mode + +The most common JTBD failure: surfacing only the functional dimension. + +**The pattern.** Job statements describe what the user is mechanically doing; the team prioritizes functional features; the product wins on functional excellence and loses on emotional and social. + +**The cure.** Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing jobs. Re-evaluate strategy considering all three dimensions. + +**The signal.** Products that are technically excellent but lose to "lesser" alternatives often have an emotional or social dimension the strategy missed. Investigate. + +--- + +## Emotional dimension and product feel + +The emotional dimension shows up in product feel: the way using the product makes users feel. + +**Examples of emotional dimensions in product design.** + +- A complex configuration interface vs a guided wizard. Both can be functionally equivalent; the wizard often serves the emotional dimension of "feeling in control rather than overwhelmed." +- An error message that explains and offers recovery vs one that just reports the failure. Both can be technically accurate; the explaining one serves the emotional dimension of "feeling supported rather than stuck." +- A success state that celebrates the milestone vs one that proceeds silently. Both can be functionally complete; the celebrating one serves the emotional dimension of "feeling progress rather than grinding." + +**The discipline.** Product designers often instinctively address emotional dimensions; the JTBD work makes this explicit and prioritizable. Emotional dimension can be a deliberate strategy choice rather than a designer's intuition. + +--- + +## Social dimension and positioning + +The social dimension informs positioning more than the other dimensions. + +**Examples of social dimensions in positioning.** + +- "Used by senior engineers at companies that ship reliable software." (positions the user as a senior engineer at a reliable company.) +- "The board reporting tool CFOs at high-growth startups trust." (positions the CFO as someone who works for a high-growth startup.) +- "Built for product teams that ship every week." (positions the product manager as part of a high-velocity team.) + +**Why social dimension is positioning-relevant.** + +- Users want to be perceived as belonging to the kind of teams the positioning describes. +- Positioning that names the social dimension creates affinity; positioning that names only functional features competes on feature comparison. +- The social dimension is durable; functional dimensions can be matched, social dimensions are harder to copy. + +**The discipline.** Positioning work should explicitly identify the social dimension of the jobs the product serves. Positioning that ignores social dimension misses one of the strongest tools available. + +--- + +## Worked synthesis combining all three dimensions + +A job statement enriched with all three dimensions: + +**Job:** "When my team is rolling out a new feature and I need to communicate it to customers, I want to write a clear announcement that explains what changed and why it matters, so I can ship the rollout without flooding support with confusion." + +**Functional dimension:** Write the announcement, distribute it to customers, prepare support for incoming questions. + +**Emotional dimension:** Confident that the announcement will land well, not anxious that it will trigger a wave of confused tickets, in control of the rollout rather than reactive to its fallout. + +**Social dimension:** Seen by the team as someone who handles rollouts smoothly, seen by customers as a brand that communicates clearly about changes, seen by support team as someone whose announcements reduce their workload rather than create it. + +**Product implications.** A tool that helps with this job needs to: + +- Functionally: support drafting, distribution, and support-team coordination. +- Emotionally: provide confidence-inducing review (preview tools, sentiment checks, changelog patterns). +- Socially: produce announcements that carry the brand voice the user wants associated with their rollouts. + +The three-dimensional analysis surfaces product needs the functional analysis alone would miss. + +--- + +## Common dimension-related failures + +**Functional-only synthesis.** Job statements describe mechanical tasks; strategy prioritizes functional features; product loses on feel. + +**Decorative emotional dimension.** Adding "feels good" without specifying which emotional state the product should support. The dimension exists on paper but does not drive design decisions. + +**Missing social dimension.** Strategy and positioning work that ignores how users want to be perceived. Positioning ends up generic; product fails to create affinity. + +**Force-fitting all three to every job.** Some jobs are functional-dominant. Adding emotional and social dimensions where they do not matter produces noise. + +**Treating dimensions as separate jobs.** Functional, emotional, and social dimensions are aspects of the same job, not separate jobs. Treating them separately produces fragmented strategy. + +--- + +## Methodology-level choices that stay in the public skill + +The three dimensions and their characteristics. Worked examples per dimension. Interview prompts per dimension. The functional-only failure mode. Emotional dimension and product feel. Social dimension and positioning. Worked three-dimensional synthesis. Common failures. + +## Implementation choices that stay internal + +Specific interview prompt templates per dimension. Specific synthesis templates that capture all three. Specific design-review patterns that check for emotional dimension. Specific positioning frameworks that lead with social dimension. These vary by team and design practice. diff --git a/skills/jtbd-framing/references/hire-and-fire-criteria.md b/skills/jtbd-framing/references/hire-and-fire-criteria.md new file mode 100644 index 0000000..d3aee67 --- /dev/null +++ b/skills/jtbd-framing/references/hire-and-fire-criteria.md @@ -0,0 +1,189 @@ +# Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground JTBD in real decisions users make. + +Hire and fire criteria are the JTBD methodology's most actionable contribution to product strategy. They surface what the product needs to be excellent at to win adoption (hire) and what the product needs to maintain to retain users (fire). The two are often different; products that win on hire criteria can lose on fire criteria. + +--- + +## Hire criteria + +What makes a user adopt a product. + +**The components.** + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +**Worked example.** A PM user adopting a new analytics tool: + +- Struggling moment: "I was spending hours every week assembling product metrics from three different sources before standup, and I was always uncertain whether I had the right slice." +- Alternatives considered: "Continued the manual spreadsheet approach. Tried to extend the existing BI tool. Considered building an internal dashboard." +- Why this product won: "It connected to all three sources out of the box, the slice I needed was a 30-second config, and the team could share the same view." +- Expected job output: "I would walk into standup with the metrics ready, with no manual reconciliation work the night before." + +**The discovery prompt.** "Tell me about the moment you decided to start using [product]. What were you doing before? What made you switch?" + +--- + +## Fire criteria + +What makes a user switch away. + +**The components.** + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +**Worked example.** A PM user switching away from an analytics tool: + +- Struggling moment: "Once we hit cross-source aggregations the basic config could not handle, I was back to manual workarounds." +- Alternative looking better: "A team I respect started using a different tool that handled cross-source natively." +- Tipping point: "When I had to rebuild a report three weeks in a row because the workaround broke whenever the source schemas changed." +- Failed job output: "The 30-second-config promise did not hold for the analyses that mattered most." + +**The discovery prompt.** "If you switched away from [product] tomorrow, what would the trigger be? What would the alternative need to do that [product] does not?" + +For users who have actually switched: "What was the moment you decided to switch away?" + +--- + +## Why hire and fire are often different + +Hire criteria reveal what the product needs to be excellent at to win adoption. Fire criteria reveal what the product needs to maintain to retain users. The asymmetry is consequential. + +**Examples of the asymmetry.** + +- A product that wins adoption with a fast onboarding (hire criterion) can lose users to depth limitations once they get past onboarding (fire criterion). The product needs both: fast onboarding AND depth that handles harder cases. +- A product that wins adoption with a single integration (hire criterion) can lose users when their tooling stack expands and the product does not keep up (fire criterion). The product needs both: a strong landing integration AND breadth as users grow. +- A product that wins adoption with a low price (hire criterion) can lose users when their budget expands and competitors offer more value at higher tiers (fire criterion). The product needs both: accessible entry AND value at higher tiers. + +**The implication.** Strategy work that focuses only on hire criteria builds for adoption. Strategy work that focuses only on fire criteria builds for retention. Mature strategy addresses both, often through different parts of the product or different lifecycle stages. + +--- + +## Recent-switch interview discipline + +Users who recently switched (in either direction) are particularly rich for JTBD interviews. + +**Why recent switches matter.** + +- The user remembers the specific moment of the switch decision; older switches get smoothed into abstractions. +- The user remembers the alternatives they considered, the criteria they used, the moment of tipping. +- The data is grounded in real decisions, not hypothetical preferences. + +**The recruiting target.** Users who switched in the last 30-90 days are the highest-value recruits for hire/fire interviews. Users who switched 6+ months ago provide weaker data. + +**The interview structure.** + +- Walk through the situation that prompted the switch consideration. +- Identify the alternatives evaluated. +- Surface the criteria the user used to evaluate. +- Identify the tipping moment. +- Compare expected vs realized outcomes after the switch. + +--- + +## Hire and fire across segments + +Different segments often have different hire and fire criteria. + +**Worked example.** A team productivity SaaS: + +- Small-team segment: hire criterion is "fast setup; works without admin"; fire criterion is "team grew and the product feels limiting." +- Mid-size segment: hire criterion is "supports our existing roles and permissions"; fire criterion is "missing reporting and audit features as we standardize." +- Enterprise segment: hire criterion is "compliance and security pass our review"; fire criterion is "vendor responsiveness during incidents." + +**The discipline.** Surface segment differences in hire and fire criteria explicitly. A product that wins on small-team hire criteria but loses on mid-size fire criteria has a known retention pattern that strategy must address. + +--- + +## The "why didn't you switch sooner" question + +A specific prompt that reveals the friction barrier to switching. + +**The prompt.** "Looking back, why didn't you switch sooner?" + +**What it surfaces.** + +- The switching cost the user had to overcome (data migration, team retraining, contract obligations). +- The alternatives that almost won earlier but did not (and why). +- The accumulated frustration that finally broke through the inertia. + +**Why it matters.** + +- High switching costs protect incumbents. Users tolerate friction longer when switching is expensive. +- The pattern of frustration accumulation reveals which fire criteria are load-bearing (the ones users finally cannot tolerate). +- The almost-won alternatives reveal what would have been compelling enough earlier. + +--- + +## Hire and fire criteria for non-switching users + +Not every user has switched. Some users are at the start of their relationship with the product; others have used it for years without considering alternatives. + +**For new users:** focus on hire criteria. The recent decision is the adoption decision; the fire criteria are hypothetical. + +**For long-tenured users:** focus on fire criteria. The hypothetical "what would make you switch" reveals the latent fire criteria even without a switch event. The product can use these to address fire risks before they become switch events. + +**For users who tried and abandoned:** rich data. They evaluated, found the product wanting, and stuck with the prior alternative. The reasons reveal both hire criteria the product failed and fire criteria for the alternative they kept. + +--- + +## Patterns across hire criteria + +Common patterns in hire criteria across product domains. + +**Speed-to-value.** Users hire products that get them to first value quickly. Long onboarding loses adoption races; fast onboarding wins. + +**Specific job fit.** Users hire products that look like they will solve the specific job. Generic products that "could be used for many things" lose to specific products that "solve this exact problem." + +**Confidence in continuity.** Users hire products they trust will be there in 2 years. Established products win on this; startups have to compensate with other criteria. + +**Workflow continuity.** Users hire products that fit their existing workflows. Products that demand workflow change face higher hire bars. + +**Recommendation chain.** Users hire products that someone they trust recommended. Word-of-mouth is often a stronger hire criterion than feature comparison. + +--- + +## Patterns across fire criteria + +Common patterns in fire criteria across product domains. + +**Reliability degradation.** Users fire products that become unreliable. A product that ships bugs faster than it ships fixes loses users. + +**Scaling friction.** Users fire products that get harder to use as they grow. The product that was great for 5 users may be painful at 50. + +**Vendor responsiveness.** Users fire products whose vendors stop responding. Support quality, account management, and incident response all matter. + +**Pricing trajectory.** Users fire products whose pricing escalates faster than the value they get. Enterprise tiers that gate basic functionality drive fire decisions. + +**Competitive pressure.** Users fire products when alternatives reach feature parity plus advantage. Products that stop innovating lose to products that overtake them. + +--- + +## Common hire-and-fire failures + +**Asking only about hire.** The team interviews about adoption decisions but never about switch decisions. The strategy biases toward adoption; retention concerns surface late. + +**Asking only about fire.** The team focuses on churn analysis without understanding hire criteria. New customer acquisition struggles because the team does not know what wins adoption. + +**Treating hire and fire as the same.** The team assumes the criteria match. Strategy ends up optimized for hire-with-no-fire-attention or vice versa. + +**Hypothetical-only fire data.** Long-tenured users describing what they "would" switch over. Useful but weaker than real-switch data. + +**Ignoring segment differences.** Hire and fire criteria collapsed across segments. Strategy that works for one segment fails for another. + +--- + +## Methodology-level choices that stay in the public skill + +The hire and fire criteria components. Why they are often different. The recent-switch interview discipline. Hire and fire across segments. The "why didn't you switch sooner" question. Hire and fire for non-switching users. Patterns across hire and fire criteria. Common failures. + +## Implementation choices that stay internal + +Specific interview templates for hire and fire interviews. Specific recruitment criteria for recent switchers. Specific synthesis tooling for hire and fire data. The team's own conventions for hire-fire balance in strategy work. These vary by team and research practice. diff --git a/skills/jtbd-framing/references/identifying-struggling-moments.md b/skills/jtbd-framing/references/identifying-struggling-moments.md new file mode 100644 index 0000000..a7e8590 --- /dev/null +++ b/skills/jtbd-framing/references/identifying-struggling-moments.md @@ -0,0 +1,176 @@ +# Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when alternatives feel inadequate, when they would prefer a different way of doing the job. + +The struggling moment is the JTBD methodology's most direct contribution to discovery research. Most discovery interviews surface preferences and feature requests; well-structured JTBD interviews surface struggling moments, which produce richer data and clearer jobs. + +--- + +## What a struggling moment is + +A specific moment in time when: + +- The user encountered friction in trying to accomplish something. +- The current approach failed them or felt inadequate. +- They considered or wished for an alternative. +- They built a workaround or accepted suboptimal output. + +**Strong struggling-moment examples.** + +- "Last Tuesday I lost an hour assembling the board metrics from three different dashboards because none of them had the slice I needed. I ended up exporting CSVs and combining them manually, and then second-guessing whether I had pulled the right data." +- "When the customer escalation came in at 9pm, I was at dinner and tried to triage from my phone, but the support tool's mobile experience was unusable. I had to go back to my laptop and the whole evening was disrupted." +- "Last quarter I spent the whole onboarding week pair-programming with the new engineer because our docs assumed knowledge they did not have, and I could not point them anywhere that would work without me there." + +Each example names a specific time, a specific friction, and the workaround or impact. + +**Weak struggling-moment examples.** + +- "I wish dashboards were better." (general; not a moment) +- "It would be nice if the support tool was more mobile-friendly." (preference; not a friction-in-context) +- "Onboarding new engineers takes a lot of time." (abstracted; no specific moment) + +--- + +## Discovery prompts that surface struggling moments + +Specific prompts produce specific data. + +**Prompts that work.** + +- "Walk me through the last time you did [task]. What was hardest about it?" +- "What was the most recent time you wished you had a better way of doing [task]?" +- "When was the last time [task] went badly? What happened?" +- "Describe the last time you considered switching from [current tool] to something else. What triggered that?" +- "What's something you do that takes longer than it should? When was the last time it cost you?" + +The prompts share two characteristics: they ground in recent specific moments, and they invite the user to describe friction without pre-judging it. + +**Prompts that fail.** + +- "What features would you like to see?" (produces feature requests, not jobs) +- "How do you usually do [task]?" (produces abstracted descriptions, not moments) +- "Are you satisfied with [tool]?" (produces preferences, not behaviors) +- "What would your dream solution look like?" (produces fiction, not data) + +--- + +## The recency bias as a feature + +JTBD interviewing exploits recency. Recent moments are remembered with specifics; older moments get smoothed into abstractions. + +**The methodology.** Ask about the last time, the most recent occurrence, the situation that happened this week. Users can recall details from recent moments that they cannot recall from older ones. The details are where the job lives. + +**The trade-off.** Recent moments may not represent the dominant pattern; the most recent occurrence may be an outlier. The mitigation is interview volume: 8-15 interviews each grounded in recent moments produce a pattern; one interview grounded in one moment is one data point. + +--- + +## Pattern recognition across users + +Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well. + +**The clustering work.** + +- Across interviews, struggling moments get tagged with what the user was trying to accomplish, what failed, what alternative they wished for. +- Tags cluster: multiple users describe the same kind of friction in similar contexts. +- Each cluster suggests a job: the underlying thing users were trying to do that the cluster's friction was blocking. + +**Worked example.** Across 12 interviews with PM users: + +- Multiple users describe assembling data from multiple dashboards before quarterly business reviews. +- Multiple describe building Excel exports because their dashboard tool does not produce the right slice. +- Multiple describe second-guessing whether the data they assembled is correct. +- Multiple describe the time pressure and disruption these workarounds create. + +The cluster suggests a job: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The job emerges from the moments; the moments came from the prompts. + +--- + +## Distinguishing struggling moments from venting + +Not every friction users describe is a struggling moment for product purposes. + +**Struggling moments.** + +- Specific friction that interferes with the user accomplishing something they care about. +- The friction is reproducible (other users encounter similar friction in similar contexts). +- The friction has a workaround or alternative the user has tried. + +**Venting that is not a struggling moment.** + +- General complaint without specific friction context ("everything is too slow"). +- Preference for cosmetic differences ("I do not like the color"). +- One-off issues with no pattern across users. + +**The discipline.** Tag specific friction; do not over-weight venting. The struggling moments that drive product decisions are the ones with reproducible context across users. + +--- + +## The "what would you have done differently" question + +A specific prompt that surfaces both struggling moments and the implicit alternative. + +**The prompt.** "If you could have done [task] any way you wanted, how would you have done it?" + +**What it surfaces.** + +- The user's mental model of the ideal approach. +- The gap between current tools and the user's mental model. +- Sometimes the alternative tools the user has used or considered. + +**What it does not surface.** + +- Always-correct product solutions. Users often describe alternatives that would not actually work; the value is in understanding their mental model, not adopting their proposed solution. + +**The interpretation.** The user's described "would have done differently" is informative about the gap, not prescriptive about the fix. Synthesis interprets the gap and proposes product responses; users do not directly produce the responses. + +--- + +## When users do not have struggling moments + +Sometimes the interview reveals that the user is not struggling with the area the team is researching. They have a workable approach; they would not change it; the friction the team thought existed does not exist for this user. + +**The honest interpretation.** The team's hypothesis about a job that needs better tooling may be wrong, or this user may not be in the target segment for the job, or the job may be done well enough by existing solutions that there is no struggle. + +**The discipline.** Surface this finding rather than discounting it. "Some users are not struggling here" is data; ignoring it because it does not match the team's hypothesis is confirmation bias. + +--- + +## Struggling moments by product type + +Different product domains surface different kinds of struggling moments. + +**Tools that fit into existing workflows.** Struggling moments are workflow disruptions: the moment the existing tool failed and the user had to switch to a workaround. + +**Tools that change workflows.** Struggling moments are transition points: the moment the user realized the old workflow was unsustainable and considered changing it. + +**Consumer products.** Struggling moments are often emotional: the moment the user felt frustrated, blocked, or in conflict with their own goals. + +**B2B platforms.** Struggling moments often involve coordination: the moment the user could not align with a colleague, customer, or vendor because the tooling did not support the coordination. + +The discipline. Tailor interview prompts to the kind of struggling moment most likely in the product domain; do not assume one prompt works for all domains. + +--- + +## Common struggling-moment failures + +**Eliciting preferences instead of moments.** "What features do you wish existed?" produces preferences. Reframe: "What's the last task that took longer than it should have?" + +**Abstracting moments to patterns prematurely.** Users describing "what I usually do" instead of specific recent moments. Bring them back to the last specific time. + +**Ignoring countervailing data.** Users who do not struggle in the researched area. Their data is signal; do not discard it. + +**Treating venting as struggling moments.** General complaint without specific context does not produce jobs. + +**Over-relying on the "wish" question.** Users describe ideal alternatives that do not necessarily reflect what would work; treat as gap-revealing data, not as product specs. + +--- + +## Methodology-level choices that stay in the public skill + +What a struggling moment is and is not. Discovery prompts that work and fail. The recency bias as a feature. Pattern recognition across users. Distinguishing struggling moments from venting. The "what would you have done differently" question. When users do not struggle. Domain-specific struggling moment patterns. Common failures. + +## Implementation choices that stay internal + +Specific interview templates and discussion guides. Specific recording and tagging conventions. Specific recruitment criteria for who the team interviews. The team's own conventions for interview length and structure. These vary by team and research practice. diff --git a/skills/jtbd-framing/references/job-statement-structure-patterns.md b/skills/jtbd-framing/references/job-statement-structure-patterns.md new file mode 100644 index 0000000..663b49a --- /dev/null +++ b/skills/jtbd-framing/references/job-statement-structure-patterns.md @@ -0,0 +1,198 @@ +# Job statement structure patterns + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." Each level demands specificity. Vague levels produce job statements that drive nothing. + +--- + +## The three levels + +### Situation + +The context, trigger, or moment when the job becomes active. + +**Strong situation patterns.** + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck the night before the meeting..." +- "When I get a customer escalation outside of business hours..." +- "When a new engineer joins my team mid-quarter..." + +**Weak situation patterns.** + +- "When I am at work..." (too broad) +- "As a marketing manager..." (demographic, not situational) +- "Whenever I need to communicate..." (lacks the specific trigger) + +**Why specificity matters.** Situations name the moment when the job activates. Different situations can produce different jobs even for the same user; collapsing situations together loses the patterns. + +--- + +### Motivation + +What the user is trying to do in that situation. + +**Strong motivation patterns.** + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage the escalation and respond without disrupting my evening too much..." +- "...I want to onboard the new engineer to our codebase without becoming their full-time guide..." + +**Weak motivation patterns.** + +- "...I want to do my job better..." (too vague) +- "...I want to use feature X..." (motivation is a feature, not a goal) +- "...I want to be more productive..." (universal; not actionable) + +**Why specificity matters.** Motivations name what the user is trying to accomplish in their own words. The motivation should describe the job the user is doing, not the product the user is using. "I want to use Slack to communicate" is not a motivation; "I want to coordinate with the team on the rollout" is. + +**The product-independence test.** A good motivation should make sense without naming any specific product. If the motivation is bound to the product, it has slid into feature framing. + +--- + +### Outcome + +What success looks like; what the user is trying to achieve by doing the job. + +**Strong outcome patterns.** + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." +- "...so the new engineer can ship their first PR within two weeks without depending on me for every question." + +**Weak outcome patterns.** + +- "...so I can succeed." (too vague) +- "...so I can use the feature." (outcome is feature use, not user goal) +- "...so I can be efficient." (universal; not specific) + +**Why specificity matters.** Outcomes name what success looks like in the user's terms. Different outcomes for the same situation+motivation can produce different jobs. The outcome anchors the job in the user's success criteria, not the product's metrics. + +--- + +## Worked examples across product domains + +### B2B SaaS for engineering teams + +- "When a production incident is detected and I am the on-call engineer, I want to identify the root cause and roll back if needed, so I can restore service before the SLO breach without escalating unnecessarily." + +### Consumer fitness app + +- "When I have 30 minutes between meetings and I want to use the time well, I want to do a workout that fits the time budget and uses the equipment I have at hand, so I can stay consistent without skipping when life gets busy." + +### Internal tools for finance teams + +- "When the month-end close is starting and I need to reconcile vendor payments, I want to identify discrepancies and document explanations, so the auditors can review without follow-up questions." + +### Creator-tools SaaS + +- "When I am editing a podcast episode the day before publication, I want to remove background noise and balance audio levels across speakers, so the episode sounds professional without spending another two hours on mastering." + +Each example specifies the moment, what the user is trying to do, and what success looks like. Each is product-independent at the motivation level: the user is trying to accomplish the job regardless of which tool they use. + +--- + +## Common structural failures + +### Vague situations + +**Failure.** "When I am at work..." + +**Diagnosis.** The situation does not name the trigger that activates the job. Most users are at work most of the time; the situation should name the specific moment. + +**Cure.** Re-ground in interview data. What was the user actually doing when this job became urgent? Use that moment. + +--- + +### Motivation as feature request + +**Failure.** "...I want to use the dashboard..." + +**Diagnosis.** Motivation is a feature, not a goal. The user does not want to use the dashboard; they want to accomplish something the dashboard supports. + +**Cure.** Ask the why-question. Why does the user want to use the dashboard? What are they trying to learn from it? The answer is the motivation. + +--- + +### Outcome as feature output + +**Failure.** "...so I can see the metrics." + +**Diagnosis.** Outcome is feature output, not user success. Seeing the metrics is intermediate; the user wants something the metrics enable. + +**Cure.** Ask another why. Why does the user want to see the metrics? What does seeing the metrics enable? The answer is the outcome. + +--- + +### Demographic as situation + +**Failure.** "As a marketing manager..." + +**Diagnosis.** Demographic, not situational. Different marketing managers in different moments have different jobs. + +**Cure.** Replace with the specific moment. "When the marketing manager is preparing the quarterly campaign retrospective..." + +--- + +### Universal as motivation or outcome + +**Failure.** "...I want to be more productive, so I can be efficient." + +**Diagnosis.** Universal language; could apply to any user, any job. Says nothing. + +**Cure.** Specificity at both motivation and outcome. What kind of productivity? What does productivity enable? The specifics are the job. + +--- + +## Multiple jobs per situation + +A single situation can produce multiple jobs. Different motivations or outcomes within the same situation are different jobs. + +**Worked example.** + +Situation: "When I am preparing the quarterly board deck..." + +Job A: "...I want to assemble revenue and engagement data into a coherent narrative, so I can answer the board's likely questions before they ask them." + +Job B: "...I want to flag the risks I want the board to engage with, so I can get their input on the calls I cannot make alone." + +Both jobs share the situation but have different motivations and outcomes. They may need different product responses. + +The discipline. Do not collapse multiple jobs into one because they share a situation. The motivation and outcome distinguish them. + +--- + +## Job statements vs alternatives in JTBD literature + +The "When... I want to... so I can..." format is the most widely used job statement structure. Other formats exist (outcome statements in outcome-driven innovation, struggle statements in switch interviews). They each name the same fundamental thing: the user's situation, motivation, and success criteria. + +This skill uses the When/I-want-to/So-I-can structure because it is the most teachable and the most consistently understood. Teams familiar with other JTBD lineages can translate; the underlying principles are the same. + +**The structure-vs-substance discipline.** The structure is a scaffold for analytical work. Job statements written in the right structure but without grounding in interview data are still ritual. Job statements written in slightly different structures but grounded in interview data and driving decisions are still jobs. + +--- + +## The job statement editing pass + +Strong JTBD work runs an editing pass focused on job-statement quality. + +**Per job statement, the editing questions.** + +1. Is the situation specific (a moment, not a demographic)? +2. Is the motivation product-independent and goal-directed? +3. Is the outcome the user's success criterion, not a feature output? +4. Is the statement specific enough that another team could distinguish it from related jobs? +5. Could the team use this job statement to evaluate a product decision? + +**The editing investment.** 1-2 hours per round of revisions on a typical job-statement set. The investment pays off in clarity for downstream applications (discovery, prioritization, positioning). + +--- + +## Methodology-level choices that stay in the public skill + +The three-level structure (situation, motivation, outcome). Strong vs weak patterns at each level. The product-independence test for motivation. Common structural failures and their cures. Multiple-jobs-per-situation discipline. The structure-vs-substance principle. The editing pass. + +## Implementation choices that stay internal + +Specific job-statement templates in the team's writing system. Specific document conventions for job-statement libraries. Specific A/B testing of statement variants in interview prompts. The team's own conventions for how many job statements per discovery cycle. These vary by team. diff --git a/skills/landing-page-copy/SKILL.md b/skills/landing-page-copy/SKILL.md new file mode 100644 index 0000000..cb3defd --- /dev/null +++ b/skills/landing-page-copy/SKILL.md @@ -0,0 +1,260 @@ +--- +name: landing-page-copy +description: "Write landing page copy with attention to the hero, value proposition, social proof, objection handling, and conversion-focused CTAs. Use this skill whenever the user wants to write a landing page, sales page, hero section, or any conversion-focused web copy. Triggers on landing page, sales page, hero copy, value proposition, headline, subheadline, hero section, CTA copy, conversion copy, opt-in page, squeeze page. Also triggers when the user has a marketing campaign or product launch needing dedicated conversion copy." +category: content +catalog_summary: "Landing pages, sales pages, hero-to-CTA flow" +display_order: 4 +--- + +# Landing Page Copy + +Write copy for pages with a single conversion goal: signup, purchase, demo request, download, lead capture. Stack-agnostic. + +This skill is narrower than `content-and-copy`. Landing pages exist to drive a specific action, not to inform broadly. + +--- + +## When to use + +- Writing a hero section for a homepage or product page +- Writing a sales page or long-form sales letter +- Drafting opt-in or lead-capture page copy +- Campaign-specific landing pages +- Pricing page copy +- Demo or signup CTAs + +## When NOT to use + +- Long-form blog content (use `content-and-copy`) +- Email sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- Page design and layout decisions (use `design-standards`) + +--- + +## Required inputs + +- The product, service, or offer +- The target audience and the specific objection they bring +- The conversion goal (one specific action) +- Brand voice +- Existing customer language (testimonials, support tickets, sales calls) +- Any constraints (length, format, regulatory) + +If audience is unclear or objections are unknown, run `brand-discovery` or pull from sales call recordings before writing. + +--- + +## The framework: 7 sections + +A landing page does seven things in sequence. The structure can flex (combine, reorder, expand), but the elements stay constant. + +### 1. Hero + +The first 3 to 5 seconds. Decides whether the visitor stays. + +**Three components:** + +- **Headline.** The promise. Specific, outcome-focused, free of cliche. +- **Subheadline.** The mechanism. How you deliver the promise. +- **Primary CTA.** The action. One button, descriptive label. + +**Strong hero patterns:** + +- **Outcome + audience + mechanism.** "Ship features 3x faster, for engineering teams who hate meetings, with our async-first project tool." +- **Pain reversal.** "Stop losing customers to slow page loads." +- **Surprising claim.** "The note-taking app that gets used. We have data." +- **Direct address.** "You have 47 unread Slack messages. Here's what to do about it." + +**Weak hero patterns:** + +- Generic adjective stacking ("Powerful, intuitive, scalable") +- "Welcome to our platform" +- Brand-name-only headlines ("Acme: The Future of X") +- Vague benefits ("Streamline your workflow") + +### 2. Social proof (early) + +Within the first scroll, prove someone else trusts you. + +**Forms:** +- Customer logos (recognizable beats unknown) +- Quantitative trust signal ("Over 10,000 teams") +- One strong testimonial with name and role +- Press mentions (logos of where you've been featured) + +**Placement:** Right below the hero, before the visitor invests in reading more. + +### 3. Problem / promise + +Establish that you understand the visitor's situation. + +**Pattern:** +- 1 to 3 paragraphs naming the specific problem +- Use the visitor's language (mined from research, not your marketing language) +- Stop before you sell. Resonate first. + +**Test:** Read the problem section aloud. Does the target audience nod? If they don't, you don't understand them yet. + +### 4. Solution / mechanism + +How you solve the problem. The "what we actually do" section. + +**Effective structure:** +- One headline summarizing the solution +- 3 to 5 specific features or capabilities, each with a 1-2 sentence explanation +- Each feature framed as the benefit it produces, not the technical detail +- Visual support (screenshots, illustrations, video clips) + +**Failure mode:** Listing features without translating to outcomes. "Real-time collaboration" is a feature. "Edit together without copying-pasting from email" is the outcome. + +### 5. Proof and detail + +The expanded social proof and case studies section. + +**Components:** +- 1 to 3 detailed case studies (specific customer, specific outcome, specific numbers) +- Multiple testimonials with attribution +- Specific data points (usage stats, success metrics, growth) +- Awards, certifications, or third-party validation + +The deeper proof section is where committed visitors convert. Skim-readers won't make it here, but the ones who do are ready to buy. + +### 6. Objection handling + +Anticipate the reasons people say no. Address them directly. + +**Common objection types:** +- **Price.** "Is this worth it?" +- **Time.** "Will this take forever to set up?" +- **Trust.** "Will this actually work for my situation?" +- **Risk.** "What if I commit and it's wrong?" +- **Comparison.** "How is this different from [competitor]?" +- **Implementation.** "Can my team handle the change?" + +**Handling formats:** +- **FAQ section.** Structured, scannable. +- **Comparison table.** Vs. competitors or vs. alternatives. +- **Risk reversal.** Money-back guarantee, free trial, no-contract terms. +- **Proof of effort needed.** "Setup takes 5 minutes, not 5 weeks." + +### 7. Final CTA + +The closer. Re-state the offer. Re-state the action. + +**Strong final CTAs:** +- Repeat the primary CTA from the hero (consistency) +- Frame in terms of the visitor's situation ("Get your team set up in 5 minutes") +- Remove friction ("No credit card required") +- One action only (avoid offering 5 alternatives that paralyze decision) + +**Avoid:** +- Multiple CTAs competing for attention at the bottom +- New offers introduced only at the bottom (visitor is now confused) +- Long forms that ask for more information than needed for the action + +--- + +## The CTA itself + +Buttons matter. Treat the button copy as a whole-page-worth of attention. + +**Strong CTA patterns:** + +- **Action + outcome.** "Start your free trial," "Get my pricing," "Send me the guide" +- **First-person.** "Show me how" outperforms "Show you how" +- **Specific.** "Book a 15-minute demo" beats "Contact us" +- **Low-friction.** "Free trial, no credit card" reduces commitment cost + +**Weak CTAs:** +- "Submit" (functional but lifeless) +- "Click here" (no value statement) +- "Learn more" (vague; about what?) +- "Get started" (started doing what?) + +--- + +## Workflow + +1. **Confirm the offer.** What exactly is being offered? At what price (if any)? What does the visitor get? +2. **Confirm the audience and objection.** Specific segment. The specific worry they bring. +3. **Mine the language.** Customer testimonials, support tickets, sales calls. Use real customer phrases. +4. **Draft the hero.** Headline, subheadline, CTA. Test 5 to 10 variations. +5. **Build the structure.** All 7 sections in order. Sections can combine for shorter pages. +6. **Draft sections.** Section by section. Don't polish until the structure is sound. +7. **Edit for friction.** Remove every word that doesn't earn its place. Landing pages do not have words to spare. +8. **Test the CTA.** Read the page aloud. By the end, is the visitor's next action obvious? +9. **Pre-publish:** check links, spell-check, mobile preview, SEO basics if SEO is a goal. + +--- + +## Failure patterns + +- **Hero that explains instead of sells.** "We're an X for Y" is description. "Get X without Y" is sell. +- **Feature lists with no outcomes.** Features without benefits read as a spec sheet. +- **Generic testimonials.** "Great product!" is worth less than nothing. "We cut onboarding time from 2 weeks to 4 days" is gold. +- **Multiple competing CTAs.** Pick one primary action. Everything else is noise. +- **Walls of text.** Visitors scan. Use short paragraphs, bullet lists, and visual breakpoints. +- **No social proof.** Trust is the first hurdle. Without proof, the rest of the page does not earn the chance to be read. +- **Mismatched headline and CTA.** Hero promises X, CTA asks for Y. Visitor confused. +- **Writing for everyone.** "Our solution works for any business" appeals to no one. Specificity converts. +- **Ignoring mobile.** Most visitors are on mobile. Test the page at 375px first. + +--- + +## Output format + +Default output is a structured markdown document for the page, with each section labeled. The markdown is ready to import into the CMS or hand to design. + +Structure: + +```markdown +# [Page Title] + +## SECTION: Hero +- Headline: [text] +- Subheadline: [text] +- Primary CTA: [button text] +- Supporting cue: [optional, e.g., "No credit card required"] +- Hero visual notes: [if any] + +## SECTION: Social proof (early) +- Logo bar: [list customer/press logos] +- Trust statistic: [if any] + +## SECTION: Problem / promise +[2 to 3 paragraphs] + +## SECTION: Solution +- Headline: [text] +- Feature 1: [headline + description] +- Feature 2: [headline + description] +- Feature 3: [headline + description] + +## SECTION: Proof +- Case study 1: [customer, outcome, numbers] +- Testimonials: [list] +- Data points: [list] + +## SECTION: Objection handling +- FAQ: [questions and answers] +- OR Comparison table: [vs alternatives] +- OR Risk reversal: [guarantee, terms] + +## SECTION: Final CTA +- Headline: [text] +- Final CTA button: [text] +- Supporting cue: [optional] + +## Variants for testing +- [Alternate headlines] +- [Alternate CTAs] +- [Alternate proof framings] +``` + +--- + +## Reference files + +- [`references/hero-formulas.md`](references/hero-formulas.md) - Patterns and formulas for hero headlines. +- [`references/objection-library.md`](references/objection-library.md) - Common objections by category, with handling strategies. diff --git a/skills/landing-page-copy/references/hero-formulas.md b/skills/landing-page-copy/references/hero-formulas.md new file mode 100644 index 0000000..d14a980 --- /dev/null +++ b/skills/landing-page-copy/references/hero-formulas.md @@ -0,0 +1,230 @@ +# Hero Headline Formulas + +The hero headline is the most-read line on the page. It earns the rest of the read or it doesn't. + +These are not magic templates. They are starting points. Apply them, then make them sound like the brand. + +--- + +## Formula 1: Outcome + audience + mechanism + +**Pattern:** [Specific outcome] for [specific audience] with [specific mechanism] + +**Examples:** +- "Ship features 3x faster, for engineering teams who hate meetings, with async-first project management." +- "Cut payroll processing from days to minutes, for finance teams of 50+, with one connected system." +- "Build a remote team that doesn't burn out, for founders scaling past 20 people, with rituals that actually work." + +**Strengths:** Highly specific. Hard to confuse with a competitor. + +**Weaknesses:** Can become long and clunky. Not always elegant. + +**When to use:** Product is in a crowded category and needs to differentiate quickly. + +--- + +## Formula 2: Pain reversal + +**Pattern:** Stop [specific pain]. Start [specific outcome]. + +**Examples:** +- "Stop losing customers to slow checkout. Start converting at industry-leading speeds." +- "Stop digging through Slack threads. Start finding answers in seconds." +- "Stop guessing what your users want. Start knowing." + +**Strengths:** Direct. Names the visitor's current frustration. + +**Weaknesses:** Depends on the pain being widely felt. If the pain isn't recognized, the headline doesn't connect. + +**When to use:** The audience is actively frustrated by something specific. + +--- + +## Formula 3: Surprising claim + +**Pattern:** A specific claim that contradicts what the audience expects. + +**Examples:** +- "The note-taking app most people actually use." +- "Email outreach that doesn't feel like spam." +- "The CRM that sales reps don't try to escape from." + +**Strengths:** Pattern-breaks. Creates curiosity. + +**Weaknesses:** Must be defensible. A surprising claim with no proof feels like marketing puffery. + +**When to use:** You can back up the claim with evidence in the page below. + +--- + +## Formula 4: Direct address + +**Pattern:** Speak to a specific situation the visitor is in right now. + +**Examples:** +- "You have 47 unread Slack messages. Here's what to do." +- "Your team just lost three candidates this month. Here's why." +- "Your app crashed at 3 AM. We watched your monitoring system miss it." + +**Strengths:** Visitor recognizes themselves immediately. + +**Weaknesses:** Risk of feeling presumptuous if the situation is wrong. + +**When to use:** The audience is highly specific and the scenario is universal among them. + +--- + +## Formula 5: Question they're already asking + +**Pattern:** Pose the question the visitor came to find an answer to. + +**Examples:** +- "How much should you actually spend on Google Ads?" +- "Should you build it or buy it? Here's the framework." +- "Why does your team's productivity drop after lunch?" + +**Strengths:** Aligns with search intent. Strong for SEO landing pages. + +**Weaknesses:** Less common in product hero copy. Better for content-driven landing pages. + +**When to use:** The page answers a specific question the visitor brought. + +--- + +## Formula 6: Comparison (us vs. them) + +**Pattern:** [Our category] without the [familiar pain of the category]. + +**Examples:** +- "CRM software without the bloat." +- "Project management without the meetings." +- "Customer support without the tickets." + +**Strengths:** Defines you in opposition to known alternatives. + +**Weaknesses:** Lazy version becomes "X but better." Specific version requires you to actually deliver on the difference. + +**When to use:** The category has a well-known pain point you avoid. + +--- + +## Formula 7: Number + outcome + +**Pattern:** Specific number that quantifies the value. + +**Examples:** +- "Cut your churn in half within 90 days." +- "Onboard your team in 15 minutes, not 15 weeks." +- "Generate 200 hours of meeting transcripts per month." + +**Strengths:** Specific and credible. + +**Weaknesses:** The number must be defensible. Made-up numbers undermine trust. + +**When to use:** You have real data backing the claim. + +--- + +## Formula 8: First-person promise + +**Pattern:** "Get [specific thing]" or "Find [specific thing]" - speaking as if to a friend. + +**Examples:** +- "Get insurance quotes in 60 seconds. Compare 30 carriers." +- "Find a contractor your neighbors actually recommend." +- "Get back the 6 hours a week you spend on email." + +**Strengths:** Conversational. Low-friction. + +**Weaknesses:** Casual register may not fit every brand. + +**When to use:** Brand voice supports a conversational first-person register. + +--- + +## Subheadline patterns + +The subheadline supports the headline. It usually does one of three jobs: + +### Job 1: Mechanism +The subheadline explains how you deliver the headline's promise. + +> Headline: Ship features 3x faster. +> Subheadline: Our async workflow eliminates the meetings that slow your team down. + +### Job 2: Audience qualifier +The subheadline names the audience precisely. + +> Headline: The simplest way to manage your inventory. +> Subheadline: Built for ecommerce stores doing $1M to $10M in revenue. + +### Job 3: Specificity / proof +The subheadline adds the credible detail. + +> Headline: Stop losing leads. +> Subheadline: Top performers reduce response time from hours to minutes. We help you do the same. + +--- + +## What to avoid in hero copy + +### Generic adjective stacking + +**Bad:** "Powerful. Intuitive. Scalable." + +These adjectives apply to anything. They distinguish nothing. + +### Vague benefits + +**Bad:** "Streamline your workflow with our innovative platform." + +What workflow? What's innovative? What does the visitor actually do? + +### Brand-name-only headlines + +**Bad:** "Acme: The Future of Work." + +The visitor doesn't know what Acme is yet. The headline must tell them. + +### Cleverness over clarity + +**Bad:** "Where productivity meets possibility." + +Sounds nice. Means nothing. Visitors do not have time to decode poetry. + +### "Welcome to" openers + +**Bad:** "Welcome to the [Brand] platform." + +Treats the visitor as a guest rather than a person trying to solve a problem. Wastes the most important real estate on the page. + +--- + +## Testing hero headlines + +Don't ship the first headline you write. Generate 5 to 10 variations using different formulas. Read them aloud. Show them to people. Pick the one that: + +1. A target-audience reader recognizes themselves in +2. Differentiates from at least 3 specific competitors +3. Sets up the rest of the page (the rest of the page must deliver on the headline's promise) +4. Sounds like the brand (not generic marketing speak) +5. Survives the "why now" test (why does this matter to the visitor today) + +If a headline can't survive all five, generate more variations. + +--- + +## CTA patterns to pair with hero headlines + +The headline and CTA must rhyme. If they don't, the visitor's mental model breaks. + +| Hero promise | CTA pattern | +|---|---| +| Get specific outcome | "Get [the outcome]" | +| Save time / money | "Save [the thing]" | +| See how it works | "Watch demo" / "See it in action" | +| Try the product | "Start free trial" / "Try it free" | +| Get information | "Get the guide" / "Show me how" | +| Talk to a person | "Book a call" / "Talk to sales" | + +The CTA copy is part of the hero, not an afterthought. Treat it with the same care as the headline. diff --git a/skills/landing-page-copy/references/objection-library.md b/skills/landing-page-copy/references/objection-library.md new file mode 100644 index 0000000..23ae871 --- /dev/null +++ b/skills/landing-page-copy/references/objection-library.md @@ -0,0 +1,244 @@ +# Objection Library + +Common objections by category, with handling strategies. Use this to pressure-test landing page copy and to make sure each major objection is met somewhere on the page. + +If a landing page does not name and answer the audience's real objections, it will not convert no matter how strong the hero is. + +--- + +## How to use this library + +1. Identify your audience and the specific decision they are facing. +2. Walk this library and flag every objection that applies. +3. For each flagged objection, decide where on the page it gets handled (and whether it gets handled with copy, social proof, a guarantee, an FAQ, or a feature). +4. Pressure-test the page: read it as a skeptical reader. Are the flagged objections answered before the CTA? + +Most pages handle 5-8 objections. Pages that handle 0-2 read as too good to be true. Pages that handle 15+ feel defensive. + +--- + +## Category 1: trust + +The audience does not know if you are real, competent, or honest. + +### "I have never heard of you" + +- **Symptom:** Bounce rate high, low time on page. +- **Handling:** Logo bar of customers, press mentions, founder photo and one-line bio, "since [year]" line, recognizable case study, security badges if relevant. + +### "How do I know this works?" + +- **Symptom:** Visitors read the whole page but do not act. +- **Handling:** Specific case studies with real names and specific outcomes ("X reduced Y by Z%"). Demo or trial. Money-back guarantee. Free assessment. + +### "How do I know you will be around in a year?" + +- **Symptom:** Common in B2B with switching costs, regulated industries, long-term commitments. +- **Handling:** Funding announcements, customer count, years in business, prominent enterprise customers, industry awards or compliance attestations. + +### "Who is behind this?" + +- **Symptom:** Common in personal brands, consultancies, or expertise-based services. +- **Handling:** Founder photo, credentials, prior work, authentic origin story. + +--- + +## Category 2: fit + +The audience cannot tell if this is for them. + +### "Is this for someone like me?" + +- **Symptom:** General-audience visitors converting; specific-segment visitors bouncing. +- **Handling:** Audience-specific copy, role-based or industry-based pages, named segments in the hero ("for [role] at [company size]"), audience-specific case studies. + +### "Will this work for my situation?" + +- **Symptom:** Visitors get to features and bounce. +- **Handling:** Use case sections, conditional FAQ ("if you are X, here is how this works"), filterable case studies, decision tree or quiz. + +### "Is my problem big enough to need this?" + +- **Symptom:** SMB visitors looking at enterprise products, or vice versa. +- **Handling:** Plan or tier comparison, "right-sized for [size]" messaging, alternatives section ("if you have [smaller problem], try [lighter approach]"). + +### "I have already solved this with [alternative]" + +- **Symptom:** Visitors compare and leave. +- **Handling:** Comparison page, "vs [competitor]" page, "in addition to" framing, integrations section. + +--- + +## Category 3: complexity and time + +The audience worries this will be hard, slow, or distracting. + +### "How long will this take to set up?" + +- **Symptom:** Time-on-page high; conversion low. Common in dev tools, SaaS. +- **Handling:** "5 minutes to set up" messaging, video walkthrough showing real timing, testimonials from peers about onboarding, white-glove option. + +### "Will I have to migrate or change what I am doing?" + +- **Symptom:** Switching anxiety. Common in any tool replacement. +- **Handling:** Migration guides, importer features highlighted, "works alongside [current tool]" framing, migration assistance offered. + +### "Will my team need training?" + +- **Symptom:** Buyer is enthusiastic; champion is worried about adoption. +- **Handling:** Onboarding program, in-product training, role-based docs, video library, account manager for enterprise. + +### "Is this going to add to my plate?" + +- **Symptom:** Visitors are already overworked. Common pitch to operators, ICs. +- **Handling:** Time-saving framing with specific numbers ("saves 4 hours per week"), automation highlighted, replace-not-add positioning. + +--- + +## Category 4: cost + +The audience worries about price, value, or hidden costs. + +### "How much does this cost?" + +- **Symptom:** Anyone visiting the pricing page bounces. Conversion only on free trial. +- **Handling:** Transparent pricing on the marketing site (or "starts at" if pricing varies), no "request a quote" for low-tier pricing, ROI calculator. + +### "Is it worth the price?" + +- **Symptom:** Pricing page visited; nothing happens. +- **Handling:** Specific ROI examples ("customers see X return in Y months"), comparison to alternative ("instead of hiring a [role], you get [tool]"), free trial or money-back, value framing throughout. + +### "Are there hidden fees?" + +- **Symptom:** Visitors abandon at checkout or in sales calls when extras come up. +- **Handling:** "No setup fees" line, "no per-seat charges" if true, "all features included" if true, transparent pricing page with all variables surfaced. + +### "I do not have budget right now" + +- **Symptom:** Common in macro slowdowns. Visitors say "interesting, send info." +- **Handling:** Annual discount, smaller plan, free tier, ROI-led copy, ROI calculator, "self-funding within X months" claim if defensible. + +--- + +## Category 5: risk + +The audience fears what happens if this goes wrong. + +### "What if it does not work?" + +- **Symptom:** Visitors explore deeply but do not commit. +- **Handling:** Money-back guarantee, free trial, free pilot, money-back specifically tied to outcome ("if you do not see X, we refund"), case studies of customers who got results. + +### "What if my data is at risk?" + +- **Symptom:** Common in B2B, data tools, financial, healthcare. +- **Handling:** Security page linked from footer (and from sales-relevant pages), compliance badges (SOC 2, ISO 27001, GDPR, HIPAA), data-handling explainer, "your data is yours" framing. + +### "What if I am locked in?" + +- **Symptom:** Visitors ask about export, contracts, cancellation in sales calls. +- **Handling:** "Export your data anytime," "no long-term contract," "cancel any time," month-to-month option visible. + +### "What if my team will not adopt it?" + +- **Symptom:** Champion deals stall. +- **Handling:** Onboarding program, role-based pricing or trials, internal-rollout playbook, customer testimonials from peer companies on adoption. + +--- + +## Category 6: timing + +The audience does not see urgency. + +### "I will get to this later" + +- **Symptom:** Sign-ups but no follow-through. Long sales cycles. +- **Handling:** Cost-of-inaction framing ("each month you wait costs X"), time-bound offer (tasteful, real, not fake), seasonal hook if relevant, before-and-after framing showing time loss. + +### "I am evaluating multiple options" + +- **Symptom:** Pipeline takes 6+ months to close. +- **Handling:** Comparison page, evaluation guide ("how to evaluate [category]"), trial that gets the buyer hands-on quickly, customer references for direct calls. + +--- + +## Category 7: politics and process + +The audience cannot decide alone. + +### "I need to get my boss to approve this" + +- **Symptom:** Champion engagement high; deal stuck above champion's authority. +- **Handling:** Business case template, ROI calculator, exec one-pager, "make the case to [role]" content, customer references at peer companies (named role buying the same tool). + +### "I need legal/security/procurement to review" + +- **Symptom:** Long lag between handshake and contract signature. +- **Handling:** Security questionnaire pre-completed, MSA boilerplate available, vendor onboarding kit, named legal/security contact for buyer-side reviewers. + +### "I need to align with [other team]" + +- **Symptom:** Multi-stakeholder deals stall. +- **Handling:** Team-specific pages, team-specific demos, multi-stakeholder ROI framing, internal advocacy kit (slide deck, FAQ). + +--- + +## Category 8: emotional / status + +The audience worries about how they will look. + +### "What if this is the wrong call?" + +- **Symptom:** Decision-maker stalls. Common with high-visibility purchases. +- **Handling:** Peer customer testimonials ("[Title] at [Recognizable Company] said X"), industry analyst recognition, awards, money-back guarantee that limits downside. + +### "Will this make me look behind / ahead?" + +- **Symptom:** First-mover anxiety or laggard anxiety. Industry-specific. +- **Handling:** "Industry standard now" framing for laggards, "ahead of the curve" framing for first-movers, social proof from peer companies in either case. + +--- + +## How objection handling shows up on the page + +The library is the inventory. The page is where it lands. The most common placements: + +- **Hero:** answers the "is this for me" objection. +- **Logo bar:** answers "are you real." +- **Feature sections:** answer "does this do what I need." +- **Use case sections:** answer "will this work for my situation." +- **Case study sections:** answer "does this work." +- **Comparison sections:** answer "what about alternatives." +- **Pricing section:** answers "what does it cost." +- **FAQ section:** answers the long tail of objections. +- **Guarantee / trial offer:** answers "what if it does not work." +- **Footer trust block:** answers "is my data safe" via compliance badges. + +If an objection from your audience is not answered anywhere on the page, the page is incomplete. + +--- + +## Worked example + +**Audience:** Engineering manager at a series-B startup, 30-50 person engineering org, evaluating an observability tool to replace an in-house Grafana setup. + +**Top 5 objections (filtered from the library):** + +1. *"How long will this take to set up?"* (Category: complexity) +2. *"Will I have to migrate?"* (Category: complexity) +3. *"What does this cost at our scale?"* (Category: cost) +4. *"What if my engineers do not adopt it?"* (Category: risk + politics) +5. *"What if our data is at risk?"* (Category: risk) + +**Page placements:** + +| Objection | Where it gets handled | +|---|---| +| Setup time | Hero ("Live in 10 minutes" + 60-second product video) | +| Migration | Migration section ("imports from Grafana automatically") + case study showing migration story | +| Cost at scale | Pricing page with engineer-count slider, transparent monthly cost | +| Adoption | Adoption section showing in-product onboarding, plus a customer quote ("80% of engineers logged in week one") | +| Data risk | Footer trust block (SOC 2, ISO, GDPR) + a "your data" explainer linked from pricing | + +Page is built around answering these five, in order, from hero to CTA. diff --git a/skills/launch-runbook/SKILL.md b/skills/launch-runbook/SKILL.md new file mode 100644 index 0000000..0fb3e62 --- /dev/null +++ b/skills/launch-runbook/SKILL.md @@ -0,0 +1,236 @@ +--- +name: launch-runbook +description: "Plan and execute a launch runbook covering pre-launch verification, go-live procedures, DNS cutover, post-launch monitoring, and rollback procedures. Use this skill whenever the user is preparing to launch a website or product, planning a DNS cutover, building a go-live checklist, or executing a launch day. Triggers on launch runbook, go-live, launch day, DNS cutover, deploy to production, site launch, product launch, cutover plan, launch checklist, deployment procedure. Also triggers when a launch is approaching and the team needs structured coordination, even if 'runbook' is not explicitly stated." +category: operations +catalog_summary: "Go-live runbook, DNS cutover, deploy day procedures" +display_order: 1 +--- + +# Launch Runbook + +Plan and execute the launch of a website, product, or major release. The runbook is the document everyone uses on launch day. Stack-agnostic. + +This skill is for the launch event. For pre-launch QA, use `qa-testing`. For post-launch incident handling, use `incident-response`. + +--- + +## When to use + +- Launching a new website or major redesign +- Migrating from one platform to another +- Releasing a major product or feature +- Coordinating cross-team launches +- Building a runbook for a recurring deploy + +## When NOT to use + +- Pre-launch testing (use `qa-testing`) +- Post-launch incident response (use `incident-response`) +- After-launch retrospective (use `after-action-report`) + +--- + +## Required inputs + +- The launch scope (what's being launched) +- The launch window (date, time, duration) +- The team (roles, on-call rotation) +- The rollback criteria (when to abort) +- The communication plan (who tells whom what, when) + +--- + +## The framework: 4 phases + +A launch has four phases. The runbook covers all four. + +### Phase 1: Pre-launch (T-30 days to T-1 hour) + +Verify everything is ready before the launch window. + +**T-30 days:** +- Final scope locked +- Cross-team commitments confirmed +- Pre-launch QA scheduled +- Comms plan drafted + +**T-7 days:** +- Pre-launch QA complete +- All critical and major issues resolved +- Performance baseline measured +- Rollback procedures documented and tested +- DNS TTL lowered (if DNS change is part of launch) + +**T-1 day:** +- Final go/no-go meeting +- Roles confirmed +- Communication channels set up +- Backup of current production state + +**T-1 hour:** +- Team assembled in shared communication channel +- Tools and access verified +- Final smoke test on staging + +### Phase 2: Cutover (T-0) + +The actual launch. Sequenced steps with owners and verifications. + +**Standard cutover steps:** + +1. Announce start to internal team +2. Enable maintenance mode (if applicable) +3. Run final database migrations (if applicable) +4. Deploy code to production +5. Verify deploy completed without errors +6. Run smoke tests on production +7. DNS cutover (if applicable) +8. Verify DNS propagation +9. Disable maintenance mode +10. Run full smoke tests on production +11. Announce launch to internal team +12. Begin monitoring window + +Each step has: +- Owner +- Pre-conditions +- Action +- Verification +- Time estimate +- Rollback procedure + +### Phase 3: Verification (T+0 to T+24 hours) + +Confirm the launch is healthy. + +**Within first hour:** +- Critical user flows working (checkout, signup, login) +- No spike in error rates +- Performance within expected ranges +- Analytics tracking firing +- Email and notifications working + +**Within first 24 hours:** +- No regression in key business metrics +- No accumulating error patterns +- Core Web Vitals stable +- Search Console showing no critical issues (if SEO-relevant) + +### Phase 4: Stabilization (T+24 hours to T+7 days) + +Monitor the long tail. + +- Track error rates day over day +- Track performance day over day +- Track key business metrics vs baseline +- Address any non-blocking issues identified +- Plan the AAR (after-action report) + +--- + +## Roles and responsibilities + +A launch has clear role assignments. Ambiguity here is the most common cause of launch chaos. + +| Role | Responsibility | +|---|---| +| Launch lead | Owns the runbook. Calls go/no-go. Calls rollback. | +| Deploy operator | Executes the technical deploy steps. | +| QA lead | Runs verification tests and confirms each milestone. | +| Comms lead | Posts internal updates, manages external messaging. | +| On-call engineer | Available for issues during and after launch. | +| Stakeholder rep | Approves on behalf of business stakeholders. | + +For small teams, one person may fill multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Rollback criteria + +Define before the launch. Decisions are easier to make pre-emptively than under pressure. + +**Automatic rollback triggers:** +- Error rate exceeds X percent of normal +- Critical user flow (defined) is broken +- Database integrity issue +- Security vulnerability discovered post-deploy + +**Discretionary rollback triggers:** +- Performance degradation beyond Y percent +- Significant degradation in key business metric +- Customer-facing error patterns + +**Decision authority:** The launch lead calls rollback. Pre-define who acts as deputy if launch lead is unavailable. + +--- + +## Communication plan + +### Internal channels + +- **Primary launch channel:** Real-time chat for the launch team only +- **Status channel:** Broader internal updates +- **War room:** Optional video call for high-stakes launches + +### Update cadence during launch + +- Every 15 minutes during cutover +- Every hour during verification phase +- Daily during stabilization phase + +### External communication + +- **Customer-facing announcement:** Pre-drafted, scheduled to publish at confirmed-success milestone +- **Status page:** Updated proactively if any user impact +- **Support team:** Briefed in advance on what's launching, common questions, escalation path + +--- + +## Workflow + +1. **Build the runbook 30 days out.** Scope, sequence, roles, rollback criteria, comms plan. +2. **Test the rollback procedure.** Untested rollback is hope, not procedure. +3. **Run a tabletop exercise.** Walk through the runbook with the full team. Find gaps. +4. **Lower DNS TTL** 48 to 72 hours before launch (if DNS change is part of launch). +5. **Day-of:** Run the runbook step by step. Verify each step before moving to next. +6. **Monitor.** First hour, first day, first week. Document anything noteworthy. +7. **Schedule the AAR** within 1 to 2 weeks of launch. + +--- + +## Failure patterns + +- **Runbook written by one person, not reviewed.** Single perspective misses scenarios. +- **No tested rollback.** Discovering rollback is broken at the moment you need it. +- **Vague step descriptions.** "Deploy to production" without specifying which tool, which command, which environment. +- **No verification step after each action.** Errors propagate. +- **Communication gaps.** Team doesn't know launch is happening, or doesn't know it succeeded. +- **Launching at end of day Friday.** Or before a holiday. Reduce the time available to respond. +- **Skipping pre-launch QA** to hit a date. The bugs appear on launch day instead. +- **Launch fatigue.** Long launches without breaks lead to errors. Plan rest cycles for multi-day launches. +- **No on-call for first 24 hours.** Someone must be reachable. + +--- + +## Output format + +Default output: a markdown runbook at `launch-runbook-[project].md` plus supporting checklists. + +Structure: + +1. Launch metadata (what, when, who) +2. Roles and responsibilities +3. Pre-launch checklist (T-30, T-7, T-1, T-1hr) +4. Cutover sequence (numbered steps, owners, verifications) +5. Rollback procedure +6. Rollback criteria (automatic and discretionary) +7. Communication plan +8. Verification checklist (first hour, first day) +9. Stabilization plan (first week) +10. Contacts (escalation paths, on-call) + +--- + +## Reference files + +- [`references/runbook-template.md`](references/runbook-template.md) - Fillable runbook template with example cutover sequences. diff --git a/skills/launch-runbook/references/runbook-template.md b/skills/launch-runbook/references/runbook-template.md new file mode 100644 index 0000000..bd2a9c2 --- /dev/null +++ b/skills/launch-runbook/references/runbook-template.md @@ -0,0 +1,289 @@ +# Launch Runbook Template + +Fillable runbook for a launch. Copy this template, fill in specifics for your launch. + +--- + +## Launch metadata + +**What's launching:** [Specific scope. "New marketing site at example.com replacing the legacy site."] + +**Launch date:** [YYYY-MM-DD] + +**Launch window start:** [Time, timezone] + +**Launch window end:** [Time, timezone] + +**Maintenance window required:** [Yes / No, and if yes, expected duration] + +**Launch lead:** [Name + contact] + +**Deputy launch lead:** [Name + contact, in case primary is unavailable] + +--- + +## Roles + +| Role | Person | Backup | Contact | +|---|---|---|---| +| Launch lead | | | | +| Deploy operator | | | | +| QA lead | | | | +| Comms lead | | | | +| On-call engineer (post-launch) | | | | +| Stakeholder rep | | | | + +--- + +## Pre-launch checklist + +### T-30 days +- [ ] Final scope locked and signed off +- [ ] Cross-team commitments confirmed +- [ ] Pre-launch QA scheduled +- [ ] Communications plan drafted +- [ ] Rollback procedure documented + +### T-14 days +- [ ] Pre-launch QA in progress +- [ ] Performance baseline measured (current production) +- [ ] Critical and major issues triaged +- [ ] Internal launch announcement drafted + +### T-7 days +- [ ] All critical issues resolved +- [ ] All major issues resolved or accepted with mitigation +- [ ] Rollback procedure tested in staging +- [ ] DNS TTL lowered to 60 to 300 seconds (if DNS change is part of launch) +- [ ] Final go/no-go date confirmed + +### T-2 days +- [ ] Final go/no-go meeting held +- [ ] Decision: GO / NO-GO / DEFER +- [ ] All team members confirmed available for launch window +- [ ] Backup of current production state taken +- [ ] Customer support briefed on what's launching + +### T-1 day +- [ ] Final smoke test on staging passes +- [ ] Communication channels set up +- [ ] On-call rotation confirmed for first 24 hours +- [ ] Pre-drafted internal and external messaging ready + +### T-1 hour +- [ ] Team assembled in launch communication channel +- [ ] All required tools and access verified +- [ ] Final smoke test on staging passes +- [ ] Launch lead confirms GO + +--- + +## Cutover sequence + +For each step: +- **Owner:** Person executing +- **Pre-condition:** What must be true to start +- **Action:** What to do +- **Verification:** How to confirm success +- **Estimated time:** How long this should take +- **Rollback:** What to do if this step fails + +--- + +### Step 1: Announce start + +- **Owner:** Comms lead +- **Pre-condition:** Launch lead has confirmed GO +- **Action:** Post in internal status channel: "Starting launch of [scope] at [time]. Expected duration: [X minutes]." +- **Verification:** Message posted, key stakeholders confirmed they saw it +- **Time:** 2 minutes + +### Step 2: Enable maintenance mode + +- **Owner:** Deploy operator +- **Pre-condition:** Step 1 complete +- **Action:** [Specific command or action to enable maintenance mode] +- **Verification:** Visit production URL, confirm maintenance page is showing +- **Time:** 2 minutes +- **Rollback:** Disable maintenance mode + +### Step 3: Final database migrations + +- **Owner:** Deploy operator +- **Pre-condition:** Step 2 complete, database backup confirmed +- **Action:** [Specific migration command] +- **Verification:** Migration log shows success, schema verified +- **Time:** [estimate] +- **Rollback:** Restore from backup taken in T-2 + +### Step 4: Deploy code to production + +- **Owner:** Deploy operator +- **Pre-condition:** Step 3 complete +- **Action:** [Specific deploy command or CI trigger] +- **Verification:** Deploy log shows success, version endpoint returns new version +- **Time:** [estimate based on past deploys] +- **Rollback:** Re-deploy previous version + +### Step 5: Run smoke tests on production + +- **Owner:** QA lead +- **Pre-condition:** Step 4 complete +- **Action:** Run smoke test suite against production +- **Verification:** All smoke tests pass +- **Time:** [estimate] +- **Rollback:** If failures, evaluate severity. Critical failures = rollback to step 4. + +### Step 6: DNS cutover (if applicable) + +- **Owner:** Deploy operator +- **Pre-condition:** Step 5 passes +- **Action:** Update DNS records: [specific records and values] +- **Verification:** Use `dig` or DNS lookup tools to confirm new records propagating +- **Time:** Propagation up to 5 minutes (if TTL was lowered) up to 24+ hours (if not) +- **Rollback:** Revert DNS records to previous values + +### Step 7: Disable maintenance mode + +- **Owner:** Deploy operator +- **Pre-condition:** Step 6 verified +- **Action:** [Specific command to disable maintenance mode] +- **Verification:** Visit production URL, confirm new site loads +- **Time:** 2 minutes + +### Step 8: Full smoke test on production + +- **Owner:** QA lead +- **Pre-condition:** Step 7 complete +- **Action:** Run full smoke test suite (more comprehensive than step 5) +- **Verification:** All tests pass; critical user flows verified manually +- **Time:** [estimate] +- **Rollback:** If failures, evaluate. Critical failures = full rollback. + +### Step 9: Announce success + +- **Owner:** Comms lead +- **Pre-condition:** Step 8 passes +- **Action:** Post in internal status channel: "Launch complete. All checks pass." +- **Verification:** Confirmed by stakeholders +- **Time:** 2 minutes + +### Step 10: Begin monitoring window + +- **Owner:** On-call engineer +- **Pre-condition:** Step 9 complete +- **Action:** Begin elevated monitoring for first 60 minutes. Watch error rates, performance, key business metrics. +- **Verification:** Dashboards open, alerts armed +- **Time:** Continuous + +--- + +## Rollback procedure + +If rollback is called, execute these steps: + +1. Announce rollback in internal status channel +2. Re-enable maintenance mode (if applicable) +3. Revert DNS records to previous values (if changed) +4. Re-deploy previous code version +5. Restore database from backup (if migrations were destructive) +6. Verify previous version is functioning +7. Disable maintenance mode +8. Run smoke tests on rolled-back state +9. Announce rollback complete +10. Schedule post-mortem + +**Estimated total rollback time:** [Estimate, typically 15 to 60 minutes] + +**Authority to call rollback:** Launch lead (or deputy if launch lead unavailable) + +--- + +## Rollback criteria + +### Automatic rollback (no debate, just do it) +- [ ] Production error rate exceeds [X]% above baseline +- [ ] Critical user flow broken: [specify which flows] +- [ ] Database integrity issue detected +- [ ] Security vulnerability discovered + +### Discretionary rollback (launch lead's call) +- [ ] Performance degradation beyond [Y]% +- [ ] Significant degradation in [specific business metric] +- [ ] Customer-facing error pattern emerging + +--- + +## Communication plan + +### Internal updates during launch +- **Cadence:** Every 15 minutes during cutover +- **Channel:** [Specific Slack channel / Teams channel / etc.] +- **Format:** "[Time] - [Step name] - [Status: started / in progress / complete / blocked]" + +### Customer-facing announcement +- **When:** After step 9 (success announce internal) +- **Where:** [Specific channels: blog post, email, social, etc.] +- **Pre-drafted:** [Link to draft] +- **Approver:** [Name] + +### Status page updates +- Pre-launch: [Status set to "Maintenance scheduled"] +- During: [Status set to "Maintenance in progress"] +- Post-success: [Status set to "Operational"] +- If issues: [Status set to "Investigating" or "Identified"] + +### Support team brief +- Pre-launch brief covers: what's launching, what users may notice, common questions, escalation path +- During-launch updates posted to support channel + +--- + +## Verification checklist (first hour) + +- [ ] Homepage loads +- [ ] Critical user flow 1: [specify] - works +- [ ] Critical user flow 2: [specify] - works +- [ ] Critical user flow 3: [specify] - works +- [ ] Sign-up / sign-in - works +- [ ] Payment flow (if applicable) - works +- [ ] Email sending - works +- [ ] Analytics tracking firing +- [ ] Error rate within normal range +- [ ] Performance within normal range +- [ ] No security alerts triggered +- [ ] Search Console shows no critical issues (if SEO-relevant launch) + +--- + +## Verification checklist (first 24 hours) + +- [ ] No regression in key business metrics: [list specific metrics] +- [ ] Error rate stable +- [ ] Performance stable +- [ ] No accumulating error patterns +- [ ] Core Web Vitals stable +- [ ] Customer support volume within normal range + +--- + +## Contacts + +| Role | Name | Phone | Slack | Email | +|---|---|---|---|---| +| Launch lead | | | | | +| Deputy lead | | | | | +| Engineering on-call | | | | | +| Database admin | | | | | +| DNS / infrastructure | | | | | +| Customer support lead | | | | | +| Executive sponsor | | | | | + +--- + +## Post-launch + +- [ ] Schedule AAR within 1 to 2 weeks +- [ ] Document any deviations from runbook +- [ ] Capture metrics: rollback rate, time to launch, issues found, etc. +- [ ] File improvements to runbook for next launch diff --git a/skills/lead-magnet-design/SKILL.md b/skills/lead-magnet-design/SKILL.md new file mode 100644 index 0000000..29da923 --- /dev/null +++ b/skills/lead-magnet-design/SKILL.md @@ -0,0 +1,282 @@ +--- +name: lead-magnet-design +description: "Designing lead magnets that earn the email. The discipline of building gated content (ebooks, templates, checklists, swipe files, mini-courses, free tools) that delivers genuine standalone value while qualifying the lead and warming them for what comes next. Honest about thin-bait (overpromises, underdelivers), kitchen-sink-resource (everything, helps with nothing), and earned-value-magnet (delivers standalone value while qualifying the lead). Triggers on lead magnet, gated content, opt-in offer, ebook, checklist, template, swipe file, mini-course, free tool, content upgrade, freebie, opt-in, list-building offer. Also triggers when an audience is being asked for an email and the offer attached to that ask needs design discipline, when previous lead magnets converted but did not produce qualified leads, or when a lead magnet is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing gated content that earns the email. Distinguishes thin-bait (overpromises, underdelivers) from kitchen-sink-resource (everything, helps with nothing) from earned-value-magnet (delivers standalone value while qualifying the lead)" +display_order: 1 +--- + +# Lead Magnet Design + +A senior growth practitioner's playbook for designing lead magnets that earn the email. Templates, checklists, swipe files, mini-courses, free tools, ebooks. The discipline of building gated content that delivers genuine standalone value while qualifying the lead and warming them for the next conversation. + +Most lead magnets are bait. A vague headline, a thin PDF, an email gate, a follow-up sequence the reader resents. Conversion-rate metrics look fine because the form converted; the email list grows; and the unsubscribe rate climbs because the magnet was a transaction the reader regrets the moment they download. + +The lead magnets that work as compounding assets do something different. They deliver value the reader would have paid for if they had to. They qualify the lead by audience-fit, so the list that grows is the right list. They set up the next conversation honestly, so the follow-up sequence is a continuation rather than an apology. + +This skill is the parent-frame methodology for the growth tooling track. Calculators (`calculator-design`) and quizzes (`quiz-and-assessment-design`) are specific lead-magnet types covered as their own skills. This skill provides the methodology for deciding WHAT to build before deciding WHAT TYPE. + +The voice is the senior growth practitioner who has watched lead magnets earn long-term subscribers and watched them burn list trust within a single send. Practical, opinionated about format selection, willing to tell the reader when a lead magnet is the wrong investment for the goal. + +When to use this skill: scoping a lead magnet for the first time, auditing a lead magnet that converts but does not qualify, deciding which format fits a specific audience and offer, or designing the post-download sequence that turns the magnet into a relationship. + +--- + +## What this skill covers + +This skill spans lead magnet design as the parent discipline. The growth-tooling distinctions: + +- **`lead-magnet-design` (this skill)** is the parent-frame methodology. WHAT a magnet is, when to invest in one, which format fits, how to qualify the lead, how to set up the follow-up. +- `calculator-design` is one specific lead-magnet type with its own methodology (calculation transparency, tiered value, methodology disclosure). +- `quiz-and-assessment-design` is another specific lead-magnet type (scoring algorithms, result categorization, recommendation matching). +- `landing-page-copy` is the page-level discipline that wraps the magnet's offer. +- `content-distribution` is how the magnet reaches its audience. +- `content-strategy` is upstream: the topic decisions that earn investment in any one magnet. + +The audience: growth marketers, in-house product marketers, marketing teams, agencies running list-building work for clients, founders building their own funnels. + +Out of scope: long-form content marketing (covered by `content-strategy`); landing-page copy (covered by `landing-page-copy`); email sequence design at scale (covered by `email-sequences`); the specific tooling configurations that deliver the magnet (those stay implementation-side). + +--- + +## The lead magnet decision: when to build one, when not to + +Before designing the magnet, decide whether a magnet is the right investment. + +**A lead magnet earns investment when:** + +- The audience exists in volume but is not yet on the list. Traffic without conversion is the gap a magnet fills. +- The product or service has a long consideration cycle. The list builds the relationship across the consideration window. +- The audience has a specific, immediate problem that a focused resource can address. Magnets work when the gap they fill is concrete. +- The follow-up sequence has a real purpose. Without a sequence that turns subscribers into something (customers, community members, qualified leads), the magnet is list-building theater. + +**A lead magnet does NOT earn investment when:** + +- The audience would convert directly without a magnet. SaaS with a free trial, ecommerce with a discount code, or freemium with a low-friction signup may not need a magnet between the visitor and the product. +- The team cannot commit to the follow-up. A list without a sequence is a list that decays. +- The topic is too broad to focus a single resource. "Marketing" is not a magnet topic; "the welcome-email template that 4x'd our trial-to-paid rate" is. +- Sales calls or demos are the next step. If the goal is a booked call, design the call-booking flow, not the magnet. + +The decision is not "should we have a magnet"; it is "is the magnet the right next investment for this specific audience and goal." + +Detail in [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md). + +--- + +## Thin-bait vs kitchen-sink-resource vs earned-value-magnet + +The keystone framing. + +**Thin-bait.** "10 tips for X" PDFs that are 200 words of fluff behind an email gate. The headline overpromises; the contents underdeliver. The reader downloads, skims, deletes, and unsubscribes within a week. The conversion-rate metric looks fine; the list quality and brand trust both degrade. Cost: every subscriber acquired through thin-bait costs more than they appear to, because the unsubscribe rate, the reduced sender reputation, and the reduced list-trust each compound. + +**Kitchen-sink-resource.** 80-page "Ultimate Guide" containing everything anyone could want about the topic. Includes nothing the reader actually needs RIGHT NOW. Bookmarked, never read, eventually forgotten. Cost: the magnet does not produce the moment of "I needed this and got it," which is the moment the relationship starts. Subscribers stay on the list out of inertia; the relationship never deepens; future emails get ignored. + +**Earned-value-magnet.** Solves a specific, immediate problem the reader has. Genuine standalone value, the kind that would be worth paying for if it were not free. Qualifies the lead by audience-fit. Warms the reader for a specific related offer that follows. The reader downloads, uses the resource, gets the result, and remembers the brand as the source of that result. + +The litmus test. Hand the magnet to a non-subscriber in the target audience. Watch them use it. Does the resource produce the promised outcome inside the time the reader was willing to spend? If yes, the magnet is earned-value. If the reader downloads and never opens, the magnet is thin-bait or kitchen-sink-resource regardless of how the headline reads. + +--- + +## Format selection + +Magnets come in formats. Each format has strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +**Templates.** A starting artifact the reader fills in or adapts. Strong for audiences who need to produce a specific deliverable (a brief, a spec, a pitch deck, an email). Strong because the value is immediate and concrete. Weak when the template is too generic to feel custom. + +**Checklists.** A sequence of items to verify or complete. Strong for audiences executing a known process where the gap is comprehensiveness, not direction. Strong because the format signals "you can use this in 10 minutes." Weak when the checklist reads as marketing rather than as a working tool. + +**Swipe files.** A curated collection of examples (subject lines, headlines, ad copy, design references). Strong for audiences who learn from examples and need inspiration rather than instruction. Weak when the swipes are stale or unattributed. + +**Mini-courses.** A multi-part email or video sequence delivering structured learning. Strong for audiences willing to invest sequential attention; strong because the sequence creates multiple touchpoints. Weak when the course is filler or when each lesson does not stand on its own. + +**Free tools (calculators, quizzes, generators).** Interactive web tools that produce a result. Strong for audiences who want a personalized output rather than a generic resource. Strong because the interaction qualifies the lead by inputs. Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Ebooks.** Long-form treatment of a topic. Strong for audiences researching a complex decision; strong when the ebook reads as a definitive resource. Weak when used as a default format for topics that would have served the reader better as a checklist or template. + +**Video series.** Sequential video content delivered behind a gate. Strong for topics that benefit from demonstration; strong for audiences who learn from video. Weak when the production overhead exceeds the topic's value or when the audience does not consume video content at the time-of-magnet moment. + +The choice depends on the audience's preferred consumption mode, the topic's natural shape, and the production overhead the team can sustain. A great template often outperforms a mediocre ebook on the same topic. + +Detail in [`references/format-selection-patterns.md`](references/format-selection-patterns.md). + +--- + +## The "would they pay for this" test + +The single test that distinguishes earned-value from thin-bait. + +The question. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails this test is signaling that the value is below the threshold of "I would pay for this," which means the reader's time investment to download and consume it is at the edge of "worth it." + +The test is not perfect. Some valuable resources are hard to price (how much is a great checklist worth?). But the test catches the magnets that exist primarily to capture an email rather than to deliver value. + +Three failure modes the test catches. + +- The 5-page PDF that summarizes blog content. Free elsewhere; not pay-worthy. +- The "Ultimate Guide" that nobody finishes. Pay-worthy in theory; not delivered in usable form. +- The template that is so generic it adds no value over starting from scratch. Pay-worthy framing; thin in execution. + +The test the magnet should pass. + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +If the magnet passes the test, it earns the email. If it fails, redesign before launching. + +Detail in [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md). + +--- + +## Audience-fit qualification + +The magnet as filter, not just bait. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). + +**Filter through the headline.** The headline tells the wrong audience to opt out. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, and consumer-app PMs. The conversion rate from the visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +**Filter through the topic.** A magnet on a niche topic attracts a niche audience. Generic topics attract generic audiences who churn off the list. Specific topics attract specific audiences who stay. + +**Filter through the format.** A 60-minute video course filters out audiences who will not invest 60 minutes. A 2-page checklist filters in audiences who want quick wins. The format signals what the brand expects of the relationship. + +**Filter through the offer adjacent to the magnet.** The follow-up sequence often makes a soft offer for a related product or service. The magnet should be tightly enough scoped that the audience who downloads it is also the audience who would consider the adjacent offer. + +The filtering principle. A magnet that converts 50 percent of visitors but produces 5 percent qualified leads is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. Optimize for the qualified lead, not for the surface conversion rate. + +Detail in [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md). + +--- + +## Title and presentation discipline + +The magnet's title is the conversion lever and the qualification filter at the same time. + +**Title patterns that work.** + +- **Specific outcome + specific audience.** "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." +- **Specific deliverable + specific situation.** "The pricing one-pager for SaaS founders raising a seed round." +- **Specific framework + specific problem.** "The 4-question framework for deciding whether to fire a customer." +- **Specific count + specific value.** "23 onboarding emails, with the open and click rate for each." + +**Title patterns to avoid.** + +- "Ultimate Guide to X." Vague. Promises too much. Underdelivers reliably. +- "The Complete X Playbook." Same failure mode. Promises completeness; delivers volume. +- "Free [Topic] Resource." Generic. Tells the reader nothing about why this resource is the one to download. +- "10 Tips for Better X." Listicle framing signals thin content. + +**Presentation discipline beyond the title.** + +- The cover or preview image should reinforce the specificity. A clean type-driven cover often outperforms a cluttered one. +- The landing page (handled by `landing-page-copy`) should preview the magnet, not just describe it. +- The first page of the magnet should deliver value within the first read, not warm up with author bio and brand-positioning. + +Detail in [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md). + +--- + +## Delivery and follow-up sequence design + +The sequence is the magnet's second act. Without it, the magnet is one transaction; with it, the magnet starts a relationship. + +**The delivery moment.** The reader fills the form and expects the resource immediately. Delivery delay (manual review, scheduled send) breaks the moment. The first email should deliver the asset and confirm the next step. + +**The first 7 days.** The reader is most engaged in the days right after download. The sequence should make use of that window: a follow-up that helps them apply the resource, a related artifact that extends the value, a soft introduction to the brand and the next step. + +**The medium-term.** Days 8 to 30, the sequence transitions from "value-add" to "ongoing relationship." Newsletter signup, related-content rotation, or a soft offer for the adjacent product or service. + +**The honest offer.** When the sequence makes an offer, the offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course; the audience signal would be wasted. + +**The opt-out.** A reader who unsubscribes from the magnet sequence is not a failure; they are a clean filter. The list quality stays higher when the unfit subscribers leave on their own. + +Detail in [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md). + +--- + +## Format-specific quality gates + +Each format has quality gates specific to that format. A great template fails different tests than a great mini-course. + +**Template gates.** Does the reader produce a usable artifact in under 30 minutes? Are the prompts specific enough to feel custom? Is the template adaptable across the segment of the audience or rigidly bound to one situation? + +**Checklist gates.** Is each item actionable today? Does the checklist sequence reflect actual workflow order? Is the checklist scoped narrowly enough to feel comprehensive within scope? + +**Swipe file gates.** Are the swipes attributed (where possible)? Are they current (not 5 years stale)? Is the curation visible (the reader can see why each swipe is included)? + +**Mini-course gates.** Does each lesson deliver standalone value (not "you will learn the answer in lesson 4")? Is the cumulative time commitment honest in the title? Does the course end with a clear next step (not just "thanks for taking the course")? + +**Calculator and quiz gates.** Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Ebook gates.** Is the ebook navigable (table of contents, page numbers, summary boxes) such that a reader who does not finish still extracts value? Is the production quality consistent with the brand it represents? + +**Video series gates.** Is each video shot at a quality the brand can sustain? Is the audio consistently clear? Is the runtime honest in the listing? + +Each format's gates exist because thin-bait can hide in any format. The quality gates make hiding harder. + +Detail in [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md). + +- "Conversion rate is great, list quality is terrible." Thin-bait pattern; magnet attracts the wrong audience or fails to deliver the promised value. +- "We ship a magnet; nothing happens after." No follow-up sequence; the magnet is one transaction rather than the start of a relationship. +- "Our 80-page Ultimate Guide gets downloaded but never read." Kitchen-sink-resource; comprehensive in scope, useless in application. +- "We changed the format from PDF to webinar; conversion rate dropped." Format mismatched to audience; the audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. +- "The magnet works in paid traffic but not organic." The audience reaching the magnet through paid is different from the organic audience; the magnet may fit one but not the other. +- "Subscribers go cold after the first email." Sequence absent or poorly designed; the value evaporates after delivery. +- "We have 5 magnets; one converts well, the others are dead." Magnet portfolio not maintained; audiences move and topics decay; periodic audit missing. +- "The follow-up offer mismatches the magnet's audience." Magnet attracted one segment; offer pitches a different one; conversion to the offer near zero. +- "We cannot tell which traffic source produces qualified leads." Attribution missing or rolled up at the wrong level; lead-quality signal not connected back to source. +- "The team built three magnets last quarter; the team avoids talking about results." Magnets shipped without success metric definition; results ambiguous or quietly underwhelming. + +--- + +## The framework: 12 considerations for lead magnet design + +When designing or auditing a lead magnet, walk these 12 considerations. + +1. **The magnet decision.** Is a magnet the right investment for this audience and goal, or does the funnel work without one? +2. **Earned-value, not thin-bait or kitchen-sink-resource.** The magnet would be worth paying for; it solves a specific problem in usable form. +3. **Format matched to audience and topic.** The format reflects how the audience consumes content and how the topic naturally shapes. +4. **The "would they pay for this" test.** Pass before launching. +5. **Audience-fit qualification.** The magnet filters for the right audience, not just maximum conversion. +6. **Title and presentation discipline.** Specific, honest, signals what is inside. +7. **Delivery in the moment.** First email arrives immediately; the asset is in that email. +8. **Follow-up sequence designed.** The 30 days after download have a purpose, an arc, and a soft offer that matches the audience. +9. **Format-specific quality gates passed.** The format's specific tests verified before launch. +10. **Lead quality measured, not just conversion rate.** What percentage of subscribers fit the audience the magnet was designed for? +11. **Attribution to source.** The team can tell which source produced which leads at which quality. +12. **Audit cadence.** The magnet portfolio gets reviewed periodically; underperformers retired. + +The output of the framework is a lead magnet that earns the email by delivering real value, qualifies the audience by filtering at the headline and topic level, and starts a relationship through a sequence the team has actually designed. + +--- + +## Reference files + +- [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md) - When a lead magnet is the right investment and when it is not. The conditions that make magnets worth the build. +- [`references/format-selection-patterns.md`](references/format-selection-patterns.md) - Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit, conversion baselines. +- [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md) - The pricing thought experiment that distinguishes earned-value from thin-bait. Worked examples and failure modes. +- [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md) - The magnet as filter. Filtering through headline, topic, format, and follow-up offer. +- [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md) - Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. +- [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md) - Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. +- [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md) - Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. +- [`references/lead-magnet-anti-patterns.md`](references/lead-magnet-anti-patterns.md) - The patterns that look like lead magnets but do not behave like them. +- [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: magnets earn the email when they earn the reader's afternoon + +The magnets that work as compounding assets are the ones the reader uses. Not downloads. Not bookmarks. Uses. The reader opens the resource, applies it, and gets a result they would have paid for if they had to. + +That is the bar. Below the bar is thin-bait (the resource is too thin to use) or kitchen-sink-resource (too much to consume). Above the bar is the relationship: the reader remembers the brand as the source of the result, opens the next email, and considers the offer when it comes. + +The discipline is in the design choices upstream of the form. The format matched to the audience and topic. The title that filters and earns. The pricing thought experiment that catches the thin magnets before launch. The follow-up sequence designed before the magnet ships, not after. The audit cadence that retires the magnets that stopped working. + +When in doubt, ask: would the audience pay for this if it were not free, and will the team commit to the sequence after the download? If yes to both, the magnet earns the email. If no to either, redesign or do not ship. diff --git a/skills/lead-magnet-design/references/audience-fit-qualification.md b/skills/lead-magnet-design/references/audience-fit-qualification.md new file mode 100644 index 0000000..7278886 --- /dev/null +++ b/skills/lead-magnet-design/references/audience-fit-qualification.md @@ -0,0 +1,171 @@ +# Audience-fit qualification + +The magnet as filter, not just bait. Filtering through headline, topic, format, and follow-up offer. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). The filtering is the difference between a list that grows and a list that grows in the right direction. + +--- + +## The filtering principle + +The magnet's job is not to maximize email captures. It is to maximize qualified email captures. + +A magnet that converts 50 percent of visitors but produces 5 percent qualified leads (visitors who match the audience the magnet was designed for) is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. The qualified-lead-rate metric matters more than the surface conversion rate. + +The filtering happens at multiple points: the headline, the topic, the format, the landing-page copy, and the follow-up offer. Each is a filter that lets in the right audience and turns away the wrong one. + +--- + +## Filter through the headline + +The headline is the first filter. The right audience self-selects in; the wrong audience self-selects out. + +**Specific outcome plus specific audience.** "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, consumer-app PMs. The conversion rate from visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +**Specific situation.** "The pricing one-pager for SaaS founders raising a seed round" filters out everyone except SaaS founders raising a seed round. That is a tiny audience; the audience that converts is exactly the audience the brand wants. + +**Specific deliverable.** "The 23-email sequence we send to trial signups who go cold" filters in PMs, growth marketers, and founders running SaaS funnels. Filters out everyone else. + +**The headline test.** Read the headline. Who in the broader audience self-selects out? If the answer is "no one, anyone might want this," the headline is not filtering. Generic headlines attract generic audiences; specific headlines attract specific audiences. + +--- + +## Filter through the topic + +The topic itself filters before the headline polishes the message. + +**Niche topics attract niche audiences.** "Pricing for B2B SaaS founders raising a seed round" is a topic that filters by definition. The audience for this topic is small but precise. + +**Generic topics attract generic audiences.** "Marketing tips" attracts everyone, which means it attracts no one specifically. The list grows; the lead quality dilutes. + +**The topic-segmentation question.** What audience segment is this topic specifically valuable for? If the answer is "everyone," the topic is too broad. Narrow until the answer is "the segment we want to serve." + +**Topic-narrowing examples.** + +- Too broad: "Email marketing tips." +- Narrowed: "Welcome-email sequences for B2B SaaS trials." +- Narrowed further: "The 7-email welcome sequence for B2B SaaS trials in the 5-50 employee segment." + +Each narrowing reduces the addressable audience and increases the qualification of those who convert. + +--- + +## Filter through the format + +The format signals what the brand expects of the relationship. + +**A 60-minute video course filters out audiences who will not invest 60 minutes.** This is sometimes the right filter (for high-investment audiences) and sometimes the wrong one (for skim-and-apply practitioners). + +**A 2-page checklist filters in audiences who want quick wins.** This is often the right filter for practitioners executing known processes. + +**A free tool with detailed inputs filters in audiences with concrete situations the tool addresses.** The inputs themselves qualify the lead. + +**An 80-page ebook filters in audiences researching a complex decision.** Filters out audiences seeking quick artifacts. + +The format choice should match the audience the magnet is designed to attract. A mismatch (a 60-minute course for a skim audience, a 2-page checklist for an in-depth research audience) breaks the filter. + +--- + +## Filter through the landing-page copy + +The landing page is the magnet's marketing layer. It filters by amplifying the headline and topic signals. + +**Audience-specific copy.** "For SaaS founders" beats "For founders" beats "For everyone." Each audience-specific cue filters. + +**Situation-specific copy.** "If you are scaling from 100 to 1000 customers, here is the playbook." Filters by situation. + +**Result-specific copy.** "After implementing this template, our trial-to-paid rate moved from 8 percent to 14 percent." Filters by who cares about that result. + +**Anti-filter copy.** "This is for everyone in marketing." Generic. No filter. Attracts the wrong audience and dilutes the list. + +The landing page should sharpen the filter the headline and topic establish, not dilute it. + +--- + +## Filter through the follow-up offer + +The follow-up offer is the late-stage filter. The audience who downloads the magnet and then engages with the offer is the audience the program needs to compound. + +**Offer-magnet alignment.** A magnet on B2B onboarding should be followed by an offer relevant to B2B teams. A misalignment (a magnet on B2B onboarding followed by an offer for consumer-app courses) wastes the qualification the magnet did. + +**Offer-audience alignment.** The offer should fit the audience the magnet attracted. If the magnet attracted SaaS founders and the offer is for enterprise sales teams, the audience signal is wasted. + +**Offer-stage alignment.** A top-of-funnel magnet should be followed by an offer at the right consideration stage (not "buy now" 3 emails after download for a high-ticket product). + +The follow-up offer's conversion rate is the qualification metric that matters most. A list that engages with the offer is a list the magnet qualified well. + +--- + +## The qualified-lead metric + +Beyond conversion rate, qualified-lead rate is the metric the magnet's filter should be measured by. + +**Definition.** Of the subscribers acquired through the magnet, what percentage match the audience profile the magnet was designed for? + +**Measurement methods.** + +- **Self-reported segment data.** Capture audience-segment data on the form (company size, role, industry). Measure the percentage that match. +- **Email engagement.** Measure open and click rates on follow-up emails relevant to the target audience. Low engagement signals audience mismatch. +- **Downstream conversion.** Measure conversion to the next step (trial, demo, purchase). Low downstream conversion despite high upstream engagement signals audience mismatch. + +**The qualified-lead-rate target.** Programs vary, but 40-70 percent of subscribers matching the target audience is a reasonable bar for a well-filtered magnet. Below 30 percent suggests the filter is broken; above 70 percent suggests the filter may be too narrow (and the magnet may be missing audience the brand could serve). + +--- + +## When to widen the filter, when to narrow + +Filter-tuning is part of the magnet's lifecycle. + +**Widen the filter when:** + +- Conversion rate is healthy but the audience the brand serves is broader than the magnet captures. +- The qualified-lead rate is high (suggesting the filter could let in more without sacrificing quality). +- The team is launching a broader product or service that fits a wider audience. + +**Narrow the filter when:** + +- Lead quality is diluting (the magnet attracts subscribers who do not match the brand's offering). +- The follow-up sequence's engagement is low because the audience does not match the offers. +- The team is focusing on a specific segment and wants the magnet to filter for it. + +The discipline. Filter tuning is iterative. The magnet's headline, topic, and follow-up can be adjusted to widen or narrow the filter as the program evolves. + +--- + +## Common filter failures + +**The headline does not filter.** Generic title; attracts everyone; lead quality dilutes. + +**The topic is too broad.** "Marketing" rather than "B2B SaaS pricing." Generic topic; generic audience. + +**The format is mismatched.** A long-form video for a skim audience; the wrong audience self-selects. + +**The landing page softens the filter.** Audience-specific headline followed by generic landing-page copy that anyone could read; the filter weakens. + +**The follow-up offer mismatches.** Magnet attracts one audience; offer pitches a different one; downstream conversion drops. + +**The team measures conversion rate but not lead quality.** The surface metric looks fine; the real metric (qualified-lead rate) is unmeasured; the magnet looks like a success while the list quality degrades. + +The pattern across failures: the team optimizes for the easier metric (conversion rate) and loses the harder metric (qualified-lead rate). The discipline is to measure both and to tune for the lead quality the program needs. + +--- + +## The high-conversion-low-quality trap + +A magnet can convert at exceptional rates while producing terrible lead quality. The trap surfaces when the team celebrates the conversion rate and ignores the downstream signal. + +**The pattern.** A generic, broadly-appealing magnet ("Marketing Tips for 2026") converts at 25 percent. The list grows quickly. The follow-up sequence sees low engagement; the offers convert at near-zero rates; the unsubscribe rate is high. + +**The diagnosis.** The magnet attracted everyone, including audiences the brand cannot serve. The high conversion rate masked the low lead quality. + +**The fix.** Narrow the magnet's filter. The conversion rate will drop; the lead quality will rise; the program's compounding metric (qualified-lead growth) will improve. + +--- + +## Methodology-level choices that stay in the public skill + +The filtering principle. Filter through headline, topic, format, landing-page, and follow-up offer. The qualified-lead metric and how to measure it. When to widen and when to narrow. The high-conversion-low-quality trap. Common filter failures. + +## Implementation choices that stay internal + +Specific filter-tuning conventions for the team's audience. Specific qualified-lead-rate baselines for specific magnets. Specific segment-data capture methods on forms. Specific tooling for engagement and downstream-conversion measurement. These vary by team. diff --git a/skills/lead-magnet-design/references/common-lead-magnet-failures.md b/skills/lead-magnet-design/references/common-lead-magnet-failures.md new file mode 100644 index 0000000..30ea197 --- /dev/null +++ b/skills/lead-magnet-design/references/common-lead-magnet-failures.md @@ -0,0 +1,187 @@ +# Common lead magnet failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the magnet underperformed" or "the list is not converting" or "we cannot tell if the magnet worked." + +--- + +## "Conversion rate is great, list quality is terrible." + +**The diagnosis.** Thin-bait pattern. The magnet attracts the wrong audience or fails to deliver promised value. Conversion-rate metric looks fine because the form converted; the lead quality metric (which is the metric that matters for downstream conversion) is poor. + +**The cure.** Apply the "would they pay for this" test (`references/would-they-pay-for-this-test.md`). Apply audience-fit qualification (`references/audience-fit-qualification.md`). Strengthen the magnet until it earns the email rather than baits it. + +--- + +## "We ship a magnet; nothing happens after." + +**The diagnosis.** No follow-up sequence. The magnet is one transaction rather than the start of a relationship. + +**The cure.** Design the sequence before shipping the magnet (`references/delivery-and-follow-up-sequences.md`). The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## "Our 80-page Ultimate Guide gets downloaded but never read." + +**The diagnosis.** Kitchen-sink-resource pattern. Comprehensive in scope, useless in application. The reader cannot consume the resource in the time they were willing to spend. + +**The cure.** Narrow the topic until the magnet addresses one specific problem in usable form. The 80-page guide often becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## "We changed the format from PDF to webinar; conversion rate dropped." + +**The diagnosis.** Format mismatched to audience. The audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. + +**The cure.** Format selection (`references/format-selection-patterns.md`). Match the format to the audience's preferred consumption mode and the topic's natural shape. The format change might still be right (if the new format better serves a different segment) but the metric drop is signal. + +--- + +## "The magnet works in paid traffic but not organic." + +**The diagnosis.** The audience reaching the magnet through paid is different from the organic audience. The magnet may fit one but not the other. + +**The cure.** Understand the audience differences. Paid traffic often has different intent and different audience composition than organic. The magnet may need a separate version for each, or the magnet may need to be retitled to match the actual audience reaching it. + +--- + +## "Subscribers go cold after the first email." + +**The diagnosis.** Sequence absent or poorly designed. The value evaporates after delivery. + +**The cure.** Design the first-7-days arc to add value progressively (`references/delivery-and-follow-up-sequences.md`). Each email should add something the reader can use; the cumulative arc deepens the relationship. + +--- + +## "We have 5 magnets; one converts well, the others are dead." + +**The diagnosis.** Magnet portfolio not maintained. Audiences move and topics decay; the periodic audit is missing. + +**The cure.** Audit the portfolio (`references/lead-magnet-anti-patterns.md`, "How to detect anti-patterns in the portfolio"). Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## "The follow-up offer mismatches the magnet's audience." + +**The diagnosis.** Magnet attracted one segment; offer pitches a different one. The audience signal the magnet captured was wasted. + +**The cure.** Align the offer to the audience the magnet attracts (`references/delivery-and-follow-up-sequences.md`, "The offer-magnet alignment"). If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## "We cannot tell which traffic source produces qualified leads." + +**The diagnosis.** Attribution missing or rolled up at the wrong level. Lead-quality signal is not connected back to source. + +**The cure.** Capture source attribution at the form level. Measure lead quality (audience-fit, downstream conversion) per source. The diagnostic data informs which sources warrant further investment. + +--- + +## "The team built three magnets last quarter; the team avoids talking about results." + +**The diagnosis.** Magnets shipped without success metric definition. Results ambiguous or quietly underwhelming. + +**The cure.** Define the success metric before building (`references/lead-magnet-decision-criteria.md`, "The success metric is defined"). What does "the magnet worked" look like? Without the definition, evaluation is impossible and underperformers do not get retired. + +--- + +## "Downloads are high; trial signups are unchanged." + +**The diagnosis.** The magnet captures emails but does not move the downstream metric the team cares about. Either the magnet's audience does not match the trial-buying audience, or the sequence does not bridge to the offer. + +**The cure.** Trace the funnel from magnet download to trial signup. Identify the drop. The drop is often at the offer step (audience misalignment) or at the sequence step (no clear path from magnet to offer). + +--- + +## "The magnet got shared on social; we got 1000 subscribers; none converted." + +**The diagnosis.** The magnet's distribution outpaced its audience-fit. A viral magnet attracts an audience that does not match the brand's offer. + +**The cure.** This is a design tradeoff. Shareable magnets are great for reach but often produce diluted lead quality. Either accept the dilution and have a long path to qualification, or design the magnet to be less shareable but more audience-specific. + +--- + +## "We tried 12 different titles; conversion rate did not move." + +**The diagnosis.** Title testing without addressing the underlying audience-fit. The title is the surface; the audience-fit is the substance. If the substance is wrong, no title fixes it. + +**The cure.** Step back from title testing. Apply the audience-fit qualification (`references/audience-fit-qualification.md`). The title can amplify a strong audience-fit; it cannot create one. + +--- + +## "The magnet's references are stale and conversion is dropping." + +**The diagnosis.** Magnet decay. Screenshots, statistics, tooling references go out of date. The reader notices and engagement drops. + +**The cure.** Maintenance discipline (`references/lead-magnet-decision-criteria.md`, "When to retire a magnet"). Quarterly review for active magnets. Update or retire when references decay. + +--- + +## "We have a great magnet; the landing page does not convert." + +**The diagnosis.** The magnet is strong but the landing page (which is `landing-page-copy`'s domain) does not preview the value, frame the audience, or close the visitor. + +**The cure.** Apply landing-page-copy discipline. Show pages from inside the magnet. Frame the audience explicitly. Make the conversion action obvious and the friction minimal. + +--- + +## "The magnet got featured in [a major newsletter]; we lost the signal we built." + +**The diagnosis.** A traffic spike from a misaligned audience can dilute the qualified-lead-rate metric. The featured audience may not match the brand's offer. + +**The cure.** Distinguish "qualified subscriber" from "any subscriber" in the metric. The traffic spike grew the list; the qualified list grew less. The signal is intact; the metric needs disaggregation. + +--- + +## "We cannot keep the sequence content fresh." + +**The diagnosis.** The sequence's content needs ongoing maintenance. The team did not budget for it. + +**The cure.** Either reduce the sequence to evergreen content the team can sustain, or accept the maintenance cost as part of the magnet's true cost. Quarterly review of every active sequence (`references/delivery-and-follow-up-sequences.md`, "The maintenance discipline"). + +--- + +## "The magnet had great reviews; the lead-quality metric is mediocre." + +**The diagnosis.** Reviews are signal about the resource's quality. Lead quality is signal about the audience-fit. The two are different. A great resource for the wrong audience produces good reviews and mediocre lead quality. + +**The cure.** Audience-fit qualification (`references/audience-fit-qualification.md`). The magnet may need a tighter filter at the title and topic level, even if the resource itself is strong. + +--- + +## "We built a magnet for our PMM team's pet topic; nobody downloaded." + +**The diagnosis.** Vanity-magnet pattern. The topic was chosen for internal interest, not audience need. + +**The cure.** Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. + +--- + +## "The team ships magnets every quarter; conversion rate is the only metric we track." + +**The diagnosis.** Single-metric tracking misses lead quality, sequence engagement, downstream conversion, and retention. The conversion rate can look fine while the broader signal is weak. + +**The cure.** Multi-metric tracking. Conversion rate, qualified-lead rate, sequence engagement, downstream conversion, and unsubscribe rate together tell the story. Single-metric tracking misleads. + +--- + +## The pattern across failures + +Most lead magnet failures fall into one of three patterns. + +**Pattern 1: The magnet does not deliver value.** Thin-bait, kitchen-sink, undelivered-promise. The fix is to strengthen or kill the magnet. + +**Pattern 2: The magnet attracts the wrong audience.** Everyone-magnet, viral-but-misaligned, vanity-magnet. The fix is to tighten the filter or reframe the audience. + +**Pattern 3: The relationship after the download fails.** Orphan-magnet, sequence-too-short, misaligned-offer, follow-up-spam. The fix is to design the sequence with as much care as the magnet itself. + +The metric pattern: lead magnet failures often look fine on the conversion rate. The signal is in the lead quality, the sequence engagement, and the downstream conversion. Programs that track only the conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, relationship). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md b/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md new file mode 100644 index 0000000..1354ac6 --- /dev/null +++ b/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md @@ -0,0 +1,188 @@ +# Delivery and follow-up sequences + +Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. The sequence is the magnet's second act; without it, the magnet is one transaction. + +A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams that build the magnet but skip the sequence capture emails that go cold. + +--- + +## The delivery moment + +The reader fills the form and expects the resource immediately. The first email confirms the moment. + +**What the delivery email should do.** + +- Deliver the asset directly (link, attachment, or in-line content). The reader did not opt in to wait. +- Confirm the audience-fit signal. Acknowledge what the reader is here for. +- Set up the next email. "I will send you [related artifact] tomorrow" creates a hook for the next touchpoint. +- Avoid friction. No double opt-in unless required by jurisdiction. No survey-before-asset. The reader gets the resource first. + +**What the delivery email should NOT do.** + +- Make an offer. The reader has not yet experienced the magnet's value; offering anything is premature. +- Bury the asset. The link or attachment should be near the top, not after three paragraphs of brand-positioning. +- Apologize for the email. "Thanks for downloading, here is your resource" without filler is honest. + +**Delivery delay risk.** Delays of more than 5 minutes break the moment. Manual review, scheduled sends, or batch processing all introduce delay. Automate the delivery to minimize lag. + +--- + +## The first 7 days arc + +The reader is most engaged in the days right after download. The sequence should make use of that window. + +**Day 0: Delivery.** Asset in hand. The reader can act on the magnet immediately. + +**Day 1-2: Application help.** A follow-up that helps the reader apply the resource. "The 3 things people miss when implementing the [magnet]" or "the worked example we use ourselves." Adds value to the magnet without yet pitching anything. + +**Day 3-4: Adjacent value.** A related artifact, case study, or insight that extends the magnet's value. Reinforces the brand as a source of useful resources. + +**Day 5-7: Soft introduction to the brand.** Who the team is, what they work on, what kinds of problems they solve. Soft framing of the next step (newsletter signup, related product, demo). + +**The 7-day arc principle.** Every email in the first 7 days should add value, not extract. The relationship is being built; extraction breaks the trust the magnet earned. + +--- + +## The medium-term sequence + +Days 8-30, the sequence transitions from "value-add" to "ongoing relationship." + +**The transition options.** + +- **Newsletter signup.** Move the subscriber to the regular newsletter cadence. The relationship continues at the brand's normal pace. +- **Related-content rotation.** A series of additional resources, case studies, or insights related to the magnet's topic. The subscriber stays engaged in the topic area. +- **Soft offer for the adjacent product or service.** A demo invitation, a trial signup, a case study of a similar customer. The offer matches the audience the magnet attracted. + +**The honest offer principle.** The offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course. The audience signal would be wasted. + +**The hard-sell trap.** Some sequences pivot too early to hard selling, before the reader has had time to recognize the value. The early hard sell breaks trust. The discipline is to earn the right to pitch through demonstrated value first. + +--- + +## The offer-magnet alignment + +The offer that follows the magnet must match the audience the magnet attracted. + +**Worked example: aligned offer.** + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: SaaS founders, growth marketers, and PMs running SaaS funnels. +The offer: a B2B SaaS lifecycle email tool with a 14-day trial. + +The audience the magnet attracted is the audience the offer serves. The conversion to trial is high relative to baseline. + +**Worked example: misaligned offer.** + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: as above. +The offer: a marketing analytics platform aimed at enterprise marketing teams. + +The audience the magnet attracted is not the audience the offer serves. The conversion to demo is near zero. The audience signal was wasted. + +**The alignment discipline.** Before designing the magnet, identify the offer the magnet's audience will be pitched. If the offer does not exist or does not match, redesign the magnet (or the offer) before shipping. + +--- + +## The clean opt-out + +A reader who unsubscribes from the magnet sequence is not a failure. They are a clean filter. + +**The principle.** The list quality stays higher when the unfit subscribers leave on their own. A subscriber who is not the right audience for the offer is a subscriber whose engagement will be low; their unsubscribe is signal, not loss. + +**The mechanics.** + +- Make unsubscribe easy. One-click is honest; multi-step is friction the brand pays for in trust. +- Do not interrogate on the way out. "We are sorry to see you go, please answer 3 questions" is friction. +- Acknowledge the unsubscribe gracefully. The reader was a subscriber; they should leave with the brand intact. + +**The unsubscribe-as-feedback loop.** High unsubscribe rates after specific emails signal that the email did not match the audience or the value proposition. The signal informs sequence revision. + +--- + +## Sequence cadence considerations + +How frequently to send. + +**Day 0-7: daily or every-other-day is honest.** The reader just downloaded; engagement is high; the sequence can use the window without feeling spammy. + +**Day 8-30: 2-4 emails per week is reasonable.** Frequency depends on the value being delivered; if each email adds value, higher frequency is sustained. + +**Day 30+: settle into the brand's normal cadence.** Newsletter weekly, monthly, or per-publication. Whatever the brand sustains. + +**Cadence-too-frequent risk.** Daily emails for 30+ days exhaust the reader. The unsubscribe rate climbs. + +**Cadence-too-infrequent risk.** Weekly cadence in the first 7 days lets the magnet's momentum fade. The reader downloads, applies, and forgets the brand. + +--- + +## Sequence-engagement measurement + +The sequence's metrics surface whether the magnet did its qualifying job. + +**Open rates.** The audience opens what is interesting to them. Low open rates after the first email signal audience mismatch or sequence-content mismatch. + +**Click-through rates.** Clicks signal interest in specific content or offers. Low click-through on the offer email signals offer-magnet misalignment. + +**Conversion to next step.** Trials, demos, purchases. The downstream metric that matters most. Low conversion despite high engagement signals offer mismatch or pricing-mismatch. + +**Unsubscribe rates.** A reasonable rate (2-5 percent over the first 30 days) is normal. Higher rates signal cadence mismatch or audience mismatch. + +The metrics together tell the story. The sequence either qualifies and converts the audience the magnet attracted, or it surfaces the mismatch the magnet missed. + +--- + +## When the sequence fails + +The sequence sends; engagement drops; conversion is low. The diagnosis often surfaces magnet-side failures. + +**Diagnosis: the magnet attracted the wrong audience.** The sequence's content is right for the audience the magnet was designed for, but the audience the magnet actually attracted is different. The fix is upstream: tighten the magnet's filter. + +**Diagnosis: the offer is misaligned.** The audience is right; the offer does not match. The fix is to change the offer (or the magnet, if the offer is fixed). + +**Diagnosis: the sequence is too long or too frequent.** Engagement starts strong and drops as fatigue sets in. The fix is to trim the sequence or space the emails. + +**Diagnosis: the sequence's value drops off.** The first emails added value; the later emails became repetitive or extractive. The fix is to redesign the later emails to continue adding value. + +**Diagnosis: the sequence's tone shifted.** The early emails were honest; the later emails became salesy. The fix is to restore the honest tone. + +The sequence is part of the magnet's design. Failures in the sequence often surface as conversion-rate or engagement metrics, but the fix is sometimes upstream in the magnet itself. + +--- + +## The maintenance discipline + +Sequences decay. Email links break, references go stale, offers change. + +**The maintenance cadence.** Quarterly review of every active sequence. Are links working? Are references current? Does the offer at the end still match the brand's current product or service? + +**Stale-sequence risk.** A subscriber who clicks a broken link or sees a reference to a discontinued product disengages immediately. The brand looks careless. + +**The retire decision.** Sequences for retired magnets should be retired. Subscribers acquired through the magnet should be moved to the appropriate ongoing sequence (newsletter or other). + +--- + +## Common sequence failures + +**No sequence.** The magnet ships; subscribers download; nothing follows. The list goes cold. + +**Sequence too short.** 2-3 emails and done. The relationship does not deepen. + +**Sequence too long.** 30+ emails over months. Subscribers fatigue. + +**Sequence pivots to hard sell too early.** The trust the magnet earned gets spent before the value has been demonstrated. + +**Offer misaligned.** Magnet attracts one audience; offer pitches another. + +**Stale references.** Links break; product names changed; case studies outdated. + +**Cadence mismatch.** Too frequent or too infrequent for the engagement the audience can sustain. + +--- + +## Methodology-level choices that stay in the public skill + +The delivery moment principles. The first-7-days arc. The medium-term transition. The offer-magnet alignment principle. The clean opt-out. Cadence considerations. Sequence-engagement measurement. Diagnostic patterns when the sequence fails. The maintenance discipline. + +## Implementation choices that stay internal + +Specific email copy for specific magnets. Specific sequence templates the team uses. Specific tooling for delivery automation, sequence platforms, and engagement measurement. The team's cadence baselines. Specific offer-design choices for specific products. These vary by team. diff --git a/skills/lead-magnet-design/references/format-selection-patterns.md b/skills/lead-magnet-design/references/format-selection-patterns.md new file mode 100644 index 0000000..97e7ce8 --- /dev/null +++ b/skills/lead-magnet-design/references/format-selection-patterns.md @@ -0,0 +1,245 @@ +# Format selection patterns + +Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +A great template often outperforms a mediocre ebook on the same topic. The format is half the design decision; the topic is the other half. + +--- + +## Templates + +A starting artifact the reader fills in or adapts. + +**Strengths.** + +- Immediate, concrete value. The reader produces a usable artifact in minutes. +- High perceived value because the artifact is practical. +- Strong audience signal: people who download templates are people who execute, not just consume. +- Sustainable production: a single template, well-designed, can serve thousands of downloads with minimal updating. + +**Weaknesses.** + +- Generic templates feel useless; the bar for "custom enough" is high. +- The format does not work when the deliverable is non-standardizable (the reader's context varies too much for a template to fit). +- Distribution can be tricky if the template requires specific tools (a Notion template is unusable to teams not on Notion). + +**Audience-fit signals.** + +- Strong fit: practitioners who produce specific deliverables (specs, briefs, plans, decks, sequences). +- Weak fit: strategic readers who want frameworks rather than artifacts. + +**Conversion-rate baseline.** Templates often convert 3-12 percent on landing pages with reasonable traffic-fit. The high end is for templates that signal exceptional specificity in the title. + +**Production overhead.** Moderate. A polished template often takes 8-20 hours including design, instructions, and worked example. + +--- + +## Checklists + +A sequence of items to verify or complete. + +**Strengths.** + +- Fast to consume, fast to apply. Reader gets value in 10-20 minutes. +- Format signals "you can use this today." +- Strong for processes where the gap is comprehensiveness rather than direction (the reader knows what to do; the checklist verifies they did not miss steps). + +**Weaknesses.** + +- Easy to make thin. A 12-item generic checklist reads as marketing rather than a working tool. +- Sequence matters; an unordered checklist on a process is less useful than the same items in workflow order. +- Limited topic range; checklists fit verification-style tasks, not strategy-style decisions. + +**Audience-fit signals.** + +- Strong fit: practitioners executing known processes who need verification (launch checklists, audit checklists, onboarding checklists). +- Weak fit: strategic decisions where each situation differs. + +**Conversion-rate baseline.** Strong checklists convert 5-15 percent. The format signals quick wins, which lifts conversion. + +**Production overhead.** Low to moderate. 4-12 hours including design and field-testing. + +--- + +## Swipe files + +A curated collection of examples (subject lines, headlines, ad copy, design references, email templates). + +**Strengths.** + +- High perceived value. The reader gets a body of work to study and adapt. +- Strong for audiences who learn from examples rather than instruction. +- Often shareable; readers tell peers about a strong swipe file. + +**Weaknesses.** + +- Requires curation discipline; a 200-item swipe file with no commentary is less useful than 30 swipes with curation notes. +- Decays faster than templates or frameworks; swipes go stale as conventions change. +- Attribution matters; uncredited swipes can be perceived as theft. + +**Audience-fit signals.** + +- Strong fit: copywriters, designers, marketers, and creators who need inspiration plus example. +- Weak fit: audiences seeking instruction or process. + +**Conversion-rate baseline.** Strong swipe files convert 4-12 percent. + +**Production overhead.** Moderate to high. 12-30 hours including curation, attribution, and commentary. + +--- + +## Mini-courses + +A multi-part email or video sequence delivering structured learning. + +**Strengths.** + +- Multiple touchpoints, which deepens the relationship. +- Sequential structure can take the reader from "novice" to "competent" on a topic. +- The course format can charge implicit time investment, which qualifies the lead as serious. + +**Weaknesses.** + +- Each lesson must stand on its own; "the answer is in lesson 4" loses the reader by lesson 2. +- Production overhead is significant. +- Completion rates are honestly low (often 10-30 percent finish), which limits the cumulative value delivered. + +**Audience-fit signals.** + +- Strong fit: audiences willing to invest sequential attention and seeking structured learning. +- Weak fit: audiences who want quick wins or specific artifacts. + +**Conversion-rate baseline.** 3-10 percent. Lower than templates or checklists because the perceived time commitment is higher. + +**Production overhead.** High. 30-100 hours for a 5-7 lesson course depending on format. + +--- + +## Free tools (calculators, quizzes, generators, configurators) + +Interactive web tools that produce a personalized result. + +**Strengths.** + +- Highest perceived value among magnet types when the tool genuinely helps. +- Personalization makes the result feel custom. +- Often shareable; results can drive earned traffic. +- Lead-quality signal embedded in the inputs (a calculator's inputs reveal the lead's situation). + +**Weaknesses.** + +- Build cost is significant; a quality tool is engineering work, not just copy. +- Maintenance is ongoing as inputs and methodology evolve. +- Easy to fall into vanity-tool patterns (inputs and outputs that do not produce a meaningful result). + +**Audience-fit signals.** + +- Strong fit: audiences with concrete decisions or calculations the tool can address. +- Weak fit: topics that do not naturally produce a personalized output. + +**Conversion-rate baseline.** Wide range, 5-25 percent depending on tool quality and audience-fit. + +**Production overhead.** High. 40-150+ hours for a polished tool. + +Detail in `calculator-design` and `quiz-and-assessment-design`. + +--- + +## Ebooks + +Long-form treatment of a topic. + +**Strengths.** + +- Comprehensive coverage when comprehensiveness matters. +- Authority signal; a well-produced ebook positions the brand as a definitive source. +- Bookmarkable; readers may return over time. + +**Weaknesses.** + +- Easy to default to ebook for topics that would have been better as a checklist or template. +- Completion rates are honestly low; many ebooks are downloaded and never read. +- Production overhead and design overhead are high. +- The format invites kitchen-sink-resource patterns ("we have to cover everything"). + +**Audience-fit signals.** + +- Strong fit: audiences researching a complex decision who want depth. +- Weak fit: practitioners who want immediate-use artifacts. + +**Conversion-rate baseline.** 2-8 percent. Lower than other formats because the perceived time investment to read is high and many readers know they will not finish. + +**Production overhead.** High. 40-120 hours for a 30-50 page ebook. + +--- + +## Video series + +Sequential video content delivered behind a gate. + +**Strengths.** + +- Strong for topics that benefit from demonstration (UI walkthroughs, design critique, code review). +- Personality and brand presence land more directly in video than in text. +- Audiences who prefer video learning are well-served. + +**Weaknesses.** + +- Production overhead is high; video quality has to match the brand it represents. +- Audiences who do not consume video at the moment of magnet delivery underuse the resource. +- Updates require re-recording, which is more expensive than updating text. + +**Audience-fit signals.** + +- Strong fit: audiences who consume video for learning and have time to watch. +- Weak fit: practitioners who want skim-and-apply content. + +**Conversion-rate baseline.** 3-9 percent. + +**Production overhead.** Very high. 50-200+ hours for a 4-6 video series at quality. + +--- + +## Hybrid formats + +Some magnets combine formats. A template plus a worked-example video. A checklist plus a 5-day email mini-course that walks through it. + +**Strengths.** + +- Multiple consumption modes serve broader audience preferences. +- The hybrid often outperforms either format alone. + +**Weaknesses.** + +- Production overhead compounds. +- Risk of confusing the reader about what they are getting. + +**When hybrids work.** When the second format genuinely extends the first. A template that includes a video walkthrough adds value; a template that includes a 60-page ebook the reader did not ask for adds bloat. + +--- + +## Format-decision frame + +When choosing the format for a specific topic and audience. + +**Step 1: Audience consumption mode.** How does this audience consume content? Do they read long-form? Skim PDFs? Watch video? Use templates? + +**Step 2: Topic shape.** Does the topic naturally produce an artifact (template), a verification (checklist), inspiration (swipe), instruction (course), a calculation (tool), depth (ebook), or demonstration (video)? + +**Step 3: Production capacity.** What can the team sustain? A great template the team can ship beats a mediocre ebook the team is straining to finish. + +**Step 4: Conversion-rate target.** Templates and checklists generally convert higher; ebooks and courses convert lower. The expected conversion rate informs the topic-volume calculation. + +**Step 5: Maintenance overhead.** Some formats decay faster than others. Swipes go stale; templates with software-specific instructions decay; videos with UI screenshots decay. Choose formats the team can maintain. + +The right format is the one that fits the topic, the audience, the team's capacity, and the maintenance reality. There is no universal best format; there is only the format that fits the situation. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format strengths, weaknesses, audience-fit signals, conversion-rate baselines, and production overhead. The hybrid format consideration. The format-decision frame. The principle that there is no universal best format. + +## Implementation choices that stay internal + +Specific format choices for specific topics in the team's catalog. Specific production benchmarks for the team's capacity. Specific tooling for each format. The team's audit baselines for conversion rate and lead quality. These vary by team, topic, and audience. diff --git a/skills/lead-magnet-design/references/format-specific-quality-gates.md b/skills/lead-magnet-design/references/format-specific-quality-gates.md new file mode 100644 index 0000000..b781609 --- /dev/null +++ b/skills/lead-magnet-design/references/format-specific-quality-gates.md @@ -0,0 +1,196 @@ +# Format-specific quality gates + +Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. Each format has gates specific to that format. A great template fails different tests than a great mini-course. + +The quality gates exist because thin-bait can hide in any format. The gates make hiding harder. Apply them before launch; if the magnet fails a gate, redesign before shipping. + +--- + +## Template gates + +A template earns the email when the reader produces a usable artifact in minimal time. + +**Gate 1: Time-to-usable-artifact.** Can the reader produce a usable artifact in under 30 minutes? If the template requires hours of customization to be useful, the format is failing. + +**Gate 2: Specificity of prompts.** Are the prompts specific enough to feel custom? "Insert your unique value proposition here" is too generic. "What is the specific outcome your customer needs in the first week" is specific enough to guide the reader. + +**Gate 3: Adaptability across the segment.** Is the template adaptable across the segment of the audience, or rigidly bound to one situation? A template for "B2B SaaS pricing one-pager" should work across multiple B2B SaaS situations; a template that only fits one company's exact circumstances is too rigid. + +**Gate 4: Worked example included.** Does the template include a worked example showing what a completed version looks like? Worked examples reduce the time-to-usable-artifact and signal that the template was real-tested. + +**Gate 5: Tooling honesty.** If the template requires specific tools (a Notion template, a Figma file, an Airtable base), is the tool dependency honestly disclosed in the title? Surprise dependencies frustrate readers who do not have the tool. + +--- + +## Checklist gates + +A checklist earns the email when each item is actionable today. + +**Gate 1: Each item actionable today.** No "consult your team about X" or "decide on the strategy for Y." Each item should be something the reader can verify or complete. + +**Gate 2: Workflow order.** Does the checklist sequence reflect actual workflow order? An out-of-order checklist forces the reader to mentally re-sort, which costs the speed advantage the format promised. + +**Gate 3: Scope discipline.** Is the checklist scoped narrowly enough to feel comprehensive within scope? "Pre-launch checklist for B2B SaaS" is narrower than "Pre-launch checklist for any product" and produces a tighter, more useful resource. + +**Gate 4: Item count sanity.** Strong checklists are usually 12-30 items. Fewer than 8 items often signals thin-bait; more than 50 often signals that the format should have been an ebook or playbook instead. + +**Gate 5: Verification cues.** Does each item include enough cue for the reader to know they actually verified it? "Email sequence tested in production" is verifiable; "Email sequence reviewed" is not. + +--- + +## Swipe file gates + +A swipe file earns the email when the swipes are real, attributed, and curated. + +**Gate 1: Real swipes.** The swipes should be examples actually used in the wild, not invented for the magnet. Real swipes have specificity that invented ones lack. + +**Gate 2: Attribution where possible.** Each swipe attributed to source where the source is public. Unattributed swipes can read as theft. + +**Gate 3: Currency.** Are the swipes current? Swipes from 5 years ago may have specific dating cues that signal staleness. Periodic refresh is part of the swipe-file discipline. + +**Gate 4: Curation visible.** Is the curation visible? The reader can see why each swipe is included? A 200-swipe dump with no commentary is less useful than 30 curated swipes with notes on why each was included. + +**Gate 5: Categorization.** Are the swipes categorized by use case (subject lines, headlines, ad copy, design references)? A flat list of unsorted swipes is harder to extract value from than a categorized collection. + +--- + +## Mini-course gates + +A mini-course earns the email when each lesson stands on its own and the cumulative arc adds up. + +**Gate 1: Each lesson standalone.** A reader who only completes lesson 1 should still extract value. "You will learn the answer in lesson 4" loses readers who do not make it to lesson 4. + +**Gate 2: Cumulative time honesty.** Is the total time commitment honestly disclosed in the title or landing page? "5-day course" should mean 5 days of meaningful engagement, not 5 days of one paragraph emails. + +**Gate 3: Production consistency.** Are all lessons at consistent production quality? Courses that decay in production quality across lessons signal that the team ran out of capacity. + +**Gate 4: Clear next step at end.** Does the course end with a clear next step (related product, related resource, ongoing community)? "Thanks for taking the course" without a next step is a missed opportunity. + +**Gate 5: Completion tracking.** Does the course include progress markers ("Lesson 3 of 5") so the reader knows where they are? Lack of progress markers correlates with low completion. + +**Gate 6: Each lesson's central insight.** Can the team articulate the central insight of each lesson in one sentence? Lessons without a central insight are filler. + +--- + +## Free tool gates + +Free tools (calculators, quizzes, generators) earn the email when the result is meaningful. + +**Gate 1: Meaningful result.** The output should help the reader make a decision or understand a situation. "Your score is 73" without interpretation is meaningless. Detail in `calculator-design` and `quiz-and-assessment-design`. + +**Gate 2: Calculation transparency or methodology disclosure.** Detail in `calculator-design`. + +**Gate 3: Email-capture honesty.** Detail in `calculator-design`. + +--- + +## Ebook gates + +An ebook earns the email when the resource produces value for readers who do not finish. + +**Gate 1: Navigability.** Table of contents, page numbers, summary boxes. A reader who jumps to chapter 3 should be able to extract value without reading 1 and 2. + +**Gate 2: Production quality consistent with the brand.** A poorly-produced ebook (typos, inconsistent formatting, low-resolution images) signals that the brand did not invest. The reader's expectation of the brand drops. + +**Gate 3: Length honesty.** Is the page count honestly disclosed? "30-page guide" should mean 30 pages of substance, not 30 pages including 12 of brand-positioning. + +**Gate 4: Chapter summaries.** Each chapter ends with a summary that lets a reader who skimmed extract the key insight. Summaries reduce the cost of skimming, which raises the value the reader gets even if they do not finish. + +**Gate 5: First-chapter discipline.** The first chapter should deliver value, not warm up. Author bio and brand-positioning belong in the appendix or the about-the-author note, not chapter 1. + +--- + +## Video series gates + +A video series earns the email when production quality and consumption shape match the audience. + +**Gate 1: Production quality consistent.** Audio clear, video stable, lighting reasonable. Production quality the brand can sustain across all videos. + +**Gate 2: Runtime honesty.** Total runtime disclosed honestly. "5-video series" with one video 30 seconds and another 45 minutes is dishonest. + +**Gate 3: Audio-first viability.** Many video viewers consume in audio-only contexts (commutes, exercise). Does the video work as audio? If the video has heavy on-screen reading required, the audio-only viewer loses the value. + +**Gate 4: Transcripts available.** A transcript reaches the audience that prefers reading and improves accessibility. + +**Gate 5: Each video standalone.** Same as the mini-course gate. A viewer who only watches video 1 should extract value. + +--- + +## Cross-format gates + +Some gates apply regardless of format. + +**Gate A: The "would they pay for this" test.** Detail in `references/would-they-pay-for-this-test.md`. + +**Gate B: Audience-fit signal.** Does the magnet attract the audience the brand serves? Detail in `references/audience-fit-qualification.md`. + +**Gate C: Title-content alignment.** Does the magnet deliver on the title's specific promise? Detail in `references/title-and-presentation-discipline.md`. + +**Gate D: First-impression quality.** Whatever the format, does the first impression (first page, first lesson, first calculator output) deliver something useful immediately? + +**Gate E: Update cadence.** Is the magnet updated when references go stale, screenshots change, or methodology evolves? Stale magnets degrade the brand. + +--- + +## When a magnet fails a gate + +The magnet fails a gate. Now what. + +**Option 1: Fix the magnet.** Add the worked example, narrow the scope, improve the production quality. Often the right answer. + +**Option 2: Change the format.** Sometimes the topic is wrong for the chosen format. A topic that fails ebook gates might pass checklist gates. + +**Option 3: Do not ship.** Some magnets should not exist. Killing the magnet at the gate stage is honest; shipping a failing magnet costs more than killing it. + +The team's response to gate failures is the discipline marker. Strong programs fix or kill at the gate; weak programs ship despite failed gates and accept the downstream cost. + +--- + +## The gate review process + +Gates are most useful when applied as a structured pre-launch review. + +**The review.** + +- Identify the format. +- List the gates for that format (plus the cross-format gates). +- For each gate, score pass / fail / marginal. +- Marginal gates warrant strengthening before launch. +- Failed gates require redesign before launch. + +**Who reviews.** + +- The magnet's author should self-review. +- A second person (outside the magnet's authoring team) should also review. Outside-in honesty catches what the authoring team rationalizes. + +**Document the review.** A short note on which gates passed and which were strengthened. Useful for future magnet design and team learning. + +--- + +## Common gate failures + +**Templates.** Generic prompts; no worked example; tool dependency hidden. + +**Checklists.** Items that are not actionable; out-of-workflow order; thin item count. + +**Swipe files.** Invented swipes; no attribution; uncategorized dump. + +**Mini-courses.** Lessons that depend on each other; production quality decays; no clear next step. + +**Free tools.** Vanity outputs without interpretation; misleading methodology; manipulative gates. + +**Ebooks.** Poor navigability; production quality below brand standard; length padded with brand-positioning. + +**Video series.** Inconsistent production; no transcripts; long runtime hidden. + +The pattern across formats: the gates surface the failures that conversion-rate metrics hide. A magnet can convert at high rates while failing the gates; the gate failures show up downstream as poor lead quality and poor sequence engagement. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format quality gates with specific tests. Cross-format gates. The gate review process. The decision tree when a magnet fails a gate. Common gate failures. + +## Implementation choices that stay internal + +Specific gate-scoring conventions for the team. Specific review processes and reviewers. Specific worked-example libraries. Specific production-quality benchmarks. Specific update-cadence calendars. These vary by team. diff --git a/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md b/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md new file mode 100644 index 0000000..e2d1f8f --- /dev/null +++ b/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md @@ -0,0 +1,197 @@ +# Lead magnet anti-patterns + +The patterns that look like lead magnets but do not behave like them. Anti-patterns are easy to ship and easy to celebrate; the cost shows up in lead quality, sequence engagement, and brand trust over time. + +--- + +## The thin-bait magnet + +The pattern. A vague-headline PDF that contains 200 words of fluff behind an email gate. + +The signal. Conversion-rate metric looks fine; unsubscribe rate after delivery is high; subsequent email open rates collapse. + +The cost. Every subscriber acquired through thin-bait costs more than they appear to. Reduced sender reputation, reduced list trust, and the brand reputation as a source of bait all compound. + +The cure. Apply the "would they pay for this" test before launch. Strengthen the resource until it would be worth paying for. If it cannot be strengthened, do not ship. + +--- + +## The kitchen-sink-resource magnet + +The pattern. An 80-page "Ultimate Guide" that covers everything anyone could want about the topic. Nothing the reader needs RIGHT NOW. + +The signal. Strong conversion rate (the title sounds comprehensive); low usage rate (the resource is too long to consume); no traceable downstream conversion. + +The cost. The magnet does not produce the moment of "I needed this and got it." The relationship never starts. Subscribers stay on the list out of inertia; future emails get ignored. + +The cure. Narrow the topic until the magnet addresses one specific problem. The 80-page guide becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## The undelivered-promise magnet + +The pattern. A title that promises a specific outcome ("the framework that doubled our conversion rate") followed by a magnet that delivers something less specific ("here is general advice on conversion rate optimization"). + +The signal. Reader downloads, opens, encounters the gap, and unsubscribes (or stays subscribed but disengages). + +The cost. The brand becomes the source of the gap. Future titles by the same brand are less trusted; conversion rates on future magnets decay. + +The cure. Either deliver on the title's promise (which often requires strengthening the magnet) or revise the title to be honest about what the magnet contains. + +--- + +## The bait-and-switch magnet + +The pattern. The magnet promises one resource and delivers another. "Free template" that turns out to be a 10-email mini-course; "calculator" that turns out to be a contact-sales form. + +The signal. Reader engagement collapses; the brand earns "deceptive" descriptors in support tickets and social mentions. + +The cost. Trust damage that extends beyond the magnet. The brand becomes harder to trust on any future offering. + +The cure. Match the title to what the magnet actually delivers. If the team wants to deliver a mini-course, title the magnet as a mini-course. If the team wants to gate a sales form, do not call it a calculator. + +--- + +## The orphan-magnet (no sequence) + +The pattern. The magnet ships; subscribers download; nothing follows. No sequence, no offer, no relationship-building. + +The signal. List grows; engagement on subsequent emails (when they happen) is low; downstream conversion to anything is near zero. + +The cost. The list is a list of cold contacts. The brand has the email but not the relationship. + +The cure. Design the sequence before shipping the magnet. The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## The misaligned-offer magnet + +The pattern. The magnet attracts one audience; the follow-up offer pitches a different one. Magnet on B2B onboarding; offer for consumer-app courses. + +The signal. Magnet conversion is fine; offer conversion is near zero; the audience signal the magnet captured was wasted. + +The cost. The team builds the magnet, runs the sequence, and gets no downstream conversion. The investment does not pay back. + +The cure. Align the offer to the audience the magnet attracts. If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## The dead-magnet portfolio + +The pattern. The team has shipped 12 magnets over 3 years. 3 still convert; 9 are dead but still on the site. Maintenance attention spreads thin; nothing is great. + +The signal. Aggregate conversion-rate metrics look fine; per-magnet metrics show 75 percent of the portfolio underperforming. + +The cost. Maintenance overhead on dead magnets; brand looks cluttered; team capacity diluted across underperformers. + +The cure. Audit the portfolio. Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## The everyone-magnet + +The pattern. A magnet titled to attract "everyone in marketing" or "any founder." Generic by design. + +The signal. Conversion rate may be high; lead quality is low; downstream engagement is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly because the audience is not aligned to any specific offer. + +The cure. Narrow the magnet's audience. Specific magnets attract specific audiences who convert well to specific offers. The everyone-magnet is the wrong tool for any specific goal. + +--- + +## The vanity-magnet + +The pattern. A magnet built because the team wanted to ship a magnet, not because the audience needed one. The topic was chosen for "we should write about this" rather than "the audience would download this." + +The signal. Low conversion rate; few signs that the audience cares about the topic; the magnet collects dust. + +The cost. Sunk effort; team morale drop; the team learns that magnets do not work (when in fact this specific magnet did not work because the topic was wrong). + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. Vanity-magnets often fail at the topic-validation step. + +--- + +## The follow-up-spam magnet + +The pattern. The magnet ships; the sequence follows; the sequence is 30 emails over 14 days, all of them sales-driven. + +The signal. Strong unsubscribe rate; high spam-complaint rate; the brand earns "spammy" descriptors. + +The cost. Sender reputation damage that affects all future emails. The brand's email program degrades. + +The cure. Redesign the sequence to add value rather than extract it. Cadence should match the audience's tolerance; content should be honest. + +--- + +## The interrogation-form magnet + +The pattern. The form before the magnet asks for 12 fields (name, company, role, company size, current tools, biggest challenge, etc.) before delivering the resource. + +The signal. Conversion rate collapses; the audience self-selects out at the form. + +The cost. The magnet's reach drops dramatically. The team gets rich data on the few who convert; the team loses the broader audience the magnet could have served. + +The cure. Ask only for what is needed (often just an email). Capture additional data later in the sequence as the relationship deepens. + +--- + +## The hidden-cost magnet + +The pattern. The magnet promises a free resource; the resource includes upselling, integrated ads, or links to paid offerings on every page. + +The signal. Reader downloads expecting a resource; experiences the upsells as bait; engagement collapses. + +The cost. The magnet is perceived as commercial-disguised-as-resource. Trust damages. + +The cure. Keep the magnet substantive. Soft offers can appear at the end or in the follow-up sequence; the body of the magnet should deliver the promised value. + +--- + +## The unfindable-asset magnet + +The pattern. The magnet is delivered as a link to a Google Drive folder, a Notion page, or some other location that the reader has to navigate to find the actual asset. The asset is buried 2-3 clicks away. + +The signal. Reader downloads the email link; cannot find the asset; abandons. + +The cost. The download metric counts but the consumption metric collapses. The reader's experience is friction. + +The cure. Deliver the asset directly (attachment or in-line link). Click count from email to asset should be 1. + +--- + +## The team-pat-on-the-back magnet + +The pattern. The magnet is content the team wanted to make (a thought-leadership piece, a brand statement, a manifesto) gated behind a form. The audience may not specifically want it. + +The signal. Conversion rate underwhelms; the team rationalizes ("brand-building is hard to measure"); the magnet does not produce relationship signal. + +The cost. The team builds the wrong thing for the audience and learns the wrong lesson. + +The cure. Design magnets for the audience's needs, not for the team's preferences. Brand-building content can exist as ungated content; gated content should be magnet-shaped. + +--- + +## How to detect anti-patterns in the portfolio + +Audit cadence. Quarterly review of every active magnet, looking specifically for these anti-patterns. + +**Audit questions per magnet.** + +- Is the conversion rate consistent with the audience-fit, or is it suspiciously high (suggesting thin-bait or everyone-magnet)? +- Is the lead quality consistent with the audience the magnet was designed for, or is it diluted (suggesting weak filters)? +- Does the sequence's engagement match the magnet's promise, or is there a drop (suggesting an undelivered-promise or misaligned-offer)? +- Is the asset usable in the form delivered, or is it hard to find (suggesting unfindable-asset)? +- Does the magnet have a sequence at all, or is it orphaned? + +**The retire decision.** Anti-pattern magnets often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-magnet plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md b/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md new file mode 100644 index 0000000..9fd5b1f --- /dev/null +++ b/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md @@ -0,0 +1,137 @@ +# Lead magnet decision criteria + +When a lead magnet is the right investment for the funnel and when it is not. The conditions that make magnets worth the build, and the funnels where the magnet is friction the audience does not need. + +A lead magnet is a long-lived asset. The build cost is upfront; the conversion lift compounds across visitors. But the long-lived asset only compounds if the audience and the goal warrant it. Magnets built without the conditions in place become dead PDFs in CMS folders. + +--- + +## When a magnet earns the build + +Five conditions that, when present, make a magnet a strong investment. + +**Traffic exists but conversion is missing.** The audience reaches the site (organic, paid, referral, social) but does not convert to the primary action (signup, purchase, demo). The magnet fills the gap between "interested enough to land" and "ready to commit." Without traffic, the magnet has no audience; without a conversion gap, the magnet adds friction. + +**The consideration cycle is long.** B2B SaaS, high-ticket services, and considered consumer purchases share the trait that buyers research over weeks or months before committing. The list-building motion lets the brand stay present across the consideration window. Short-cycle purchases (impulse ecommerce, low-stakes signups) often do not need a magnet between visitor and conversion. + +**The audience has a specific, immediate problem the magnet can address.** Generic problems do not focus a magnet. "Improve my marketing" is too broad; "the email sequence I send to trial signups who go cold" is specific enough to focus a checklist or template. The magnet lives or dies on specificity. + +**The team can commit to the follow-up sequence.** A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams without sequence-building capacity should fix that before building the magnet. + +**The success metric is defined.** What does "the magnet works" look like? List growth at quality, lead-quality signal, conversion to the next step, downstream revenue attribution. Without a defined success metric, the magnet's results cannot be evaluated, and underperformers do not get retired. + +When all five are present, the magnet is a strong investment. When two or fewer are present, the magnet is probably the wrong tool. + +--- + +## When a magnet does NOT earn the build + +Funnels where the magnet adds friction the audience does not need. + +**Frictionless conversion already exists.** A SaaS with a 14-day free trial, no credit card required, may not need a magnet between the visitor and the trial. The magnet adds a step where the trial alone would convert. + +**The next step is a sales call or demo.** When the goal is a booked call, design the call-booking flow rather than a magnet that delays the call. The magnet might still serve a separate audience (top-of-funnel readers not ready for a call), but the primary funnel is the call. + +**The audience is too small for list-building economics.** Building, hosting, and maintaining a magnet (plus the sequence) costs ongoing time. For very small target audiences, direct outreach or a simpler conversion path may be more efficient. + +**The team has no sequence capacity.** If the team cannot design and maintain the post-download sequence, the magnet captures emails that decay into unsubscribes. The list grows on paper and shrinks in trust. + +**No specific topic that focuses a magnet.** When the topic is "we do everything," no single magnet focuses. The honest move is to narrow the audience first (which produces the topic that focuses) rather than build a generic magnet. + +**The current funnel is already converting at a rate the magnet would not improve.** If the visitor-to-customer rate is already strong, the magnet adds steps without lifting the outcome. + +The honest assessment matters more than the default. "Should we have a lead magnet" is not the question. "Is the magnet the right investment for this audience and goal" is. + +--- + +## The opportunity-cost frame + +A magnet's cost is not just the build. It is the build plus the maintenance plus the sequence plus the team attention diverted from other work. + +**The build cost.** Format selection, copy, design, asset production, landing page, form integration, delivery automation. A meaningful magnet often takes 20-80 hours from scoping to launch. + +**The maintenance cost.** Magnets decay. References go stale, screenshots get outdated, the topic moves on. Maintenance often runs 2-4 hours per quarter per active magnet. + +**The sequence cost.** The post-download sequence is itself a build. 5-12 emails, copy and integration. 10-30 hours upfront. + +**The opportunity cost.** What else could the team have built with that time? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The magnet's success has to clear the bar of those alternatives. + +The decision frame. The magnet earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The audience precondition + +Without an audience, the magnet has no one to convert. + +The chicken-and-egg pattern. Teams sometimes build magnets to "drive traffic." That works only if the magnet itself is shareable enough to attract traffic (rare) or if the team has a separate plan to drive traffic to the magnet's landing page. + +The realistic frame. The magnet converts traffic that already exists. Driving traffic is a separate problem (covered by `content-distribution`, paid media, SEO, and partnerships). Build the magnet for the traffic that already lands; do not expect the magnet to do the traffic-driving work. + +The exception. Genuinely shareable magnets (free tools, viral calculators, definitive industry reports) can drive their own traffic. But these are the minority of magnets, and the design effort to reach shareability is significant. + +--- + +## The portfolio frame + +A team often has multiple magnets, not one. The portfolio earns more thought than any individual magnet. + +**The audience-segmentation frame.** Different magnets for different audience segments. The B2B SaaS founder magnet does not need to also serve the consumer marketer; segment-specific magnets often outperform generic ones. + +**The funnel-stage frame.** Magnets for top-of-funnel readers, magnets for middle-of-funnel evaluators, magnets for bottom-of-funnel near-buyers. Each stage has different value to deliver and different next-step offers. + +**The maintenance frame.** A portfolio of 4-6 active magnets is often more sustainable than 12 mediocre ones. Periodic audit retires the underperformers and frees capacity for the strong magnets. + +**The cross-magnet promotion frame.** The follow-up sequence from one magnet can promote another. Subscribers who downloaded the templates checklist may also want the pricing one-pager. + +The portfolio approach amplifies the value of each strong magnet and makes maintenance manageable. + +--- + +## The decision worked example + +A B2B SaaS targeting product managers at mid-market companies. + +**Conditions check.** + +- Traffic: 8000 monthly organic visitors, 1200 paid visitors. Yes. +- Consideration cycle: typical PM tool evaluation takes 6-12 weeks. Yes. +- Specific problem: PMs at mid-market companies struggle to define product metrics that the engineering team can instrument quickly. Yes. +- Sequence capacity: marketing team has built two prior sequences; capacity exists. Yes. +- Success metric: list growth at audience-fit (PMs at 50-500 person companies), conversion to product trial within 60 days. Yes. + +**Decision.** Build the magnet. The conditions warrant it. + +**Format selection.** Template plus worked example. The PM produces a usable artifact (the metric definition spec) inside 30 minutes. + +**Sequence.** 7-email arc over 21 days. Email 1 delivers the asset. Emails 2-4 deepen the value with related artifacts. Email 5 introduces the product as the next step. Emails 6-7 case study and offer. + +**Audit cadence.** Quarterly review of conversion rate, lead quality, sequence open and click rates, downstream trial conversion. + +The decision was not "should we have a magnet" but "given these conditions, this is the magnet to build." + +--- + +## When to retire a magnet + +Magnets decay. Retiring them is part of the discipline. + +**Retire when:** + +- Conversion rate has dropped below baseline for two consecutive quarters. +- The topic has shifted (the audience no longer cares about the problem the magnet solves). +- A newer magnet on the same topic is outperforming and the older one is cannibalizing. +- The follow-up sequence is no longer maintained and the leads go cold. +- The references and screenshots are stale and updating them costs more than retiring. + +The retiring discipline frees capacity. A portfolio of dead magnets costs maintenance attention without producing results. Honest retirement is part of the program. + +--- + +## Methodology-level choices that stay in the public skill + +The decision conditions for whether to build a magnet. The opportunity-cost frame. The audience precondition. The portfolio frame. The retirement discipline. The decision worked example. The honest "no" cases where a magnet adds friction. + +## Implementation choices that stay internal + +Specific magnet topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence work. Specific tooling for landing pages, forms, delivery, and sequence. Specific success-metric definitions and baselines. The team's portfolio composition and audit calendar. These vary by team and audience. diff --git a/skills/lead-magnet-design/references/title-and-presentation-discipline.md b/skills/lead-magnet-design/references/title-and-presentation-discipline.md new file mode 100644 index 0000000..f3b990f --- /dev/null +++ b/skills/lead-magnet-design/references/title-and-presentation-discipline.md @@ -0,0 +1,190 @@ +# Title and presentation discipline + +Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. + +The magnet's title is the conversion lever and the qualification filter at the same time. Beyond the title, the cover, the landing-page preview, and the first page each carry signal about whether the resource will deliver. Get any of these wrong and the rest of the magnet's design effort is wasted. + +--- + +## Title patterns that work + +Specific, honest, signals what is inside. + +**Specific outcome plus specific audience.** "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." + +What works: the specific outcome (3x'd, 14-day activation), the specific audience (SaaS founders), the specific deliverable (email sequence). The reader knows exactly what they get and can predict whether it applies. + +**Specific deliverable plus specific situation.** "The pricing one-pager for SaaS founders raising a seed round." + +What works: the artifact (pricing one-pager), the situation (raising a seed round). Niche by design; the audience that converts is exactly the audience the brand wants to engage. + +**Specific framework plus specific problem.** "The 4-question framework for deciding whether to fire a customer." + +What works: the framework's structure (4 questions), the specific decision (fire a customer). Promises a tool, not a treatise. + +**Specific count plus specific value.** "23 onboarding emails, with the open and click rate for each." + +What works: the count (signals scope), the value-add (real metrics, not just templates). The reader knows the resource includes evidence. + +**Specific transformation.** "The audit that took our trial-to-paid rate from 8 percent to 14 percent." + +What works: the before-state (8 percent), the after-state (14 percent), the mechanism (the audit). The reader can imagine running their own version. + +--- + +## Title patterns to avoid + +Vague, overpromising, or generic. These titles correlate with thin-bait and kitchen-sink-resource patterns. + +**"Ultimate Guide to X."** Vague. Promises completeness; underdelivers reliably. The "Ultimate" qualifier signals that the team did not narrow the topic. + +**"The Complete X Playbook."** Same failure mode. Promises volume; suggests the resource is big and unfocused. + +**"Free X Resource."** Generic. Tells the reader nothing about what makes this resource the one to download. The "free" framing implies the resource has to apologize for asking for the email. + +**"10 Tips for Better X."** Listicle framing signals thin content. "10 tips" is rarely a useful resource; "the 1 specific change that doubled our X" is. + +**"X 101" or "Beginner's Guide to X."** Targets a low-investment audience. The list that grows from these titles tends to convert poorly to anything beyond the magnet. + +**"The Definitive X Resource."** Self-aggrandizing. Definitive is the reader's judgment, not the marketer's claim. + +**Vague verbs.** "Master," "Unlock," "Transform." Without specificity about what or how, these are filler. + +--- + +## The honesty discipline in titles + +The title should not promise more than the magnet delivers. + +**The check.** Read the title. Then open the magnet. Does the magnet deliver on the title's specific promise? If yes, the title is honest. If the title overpromises, redesign the title (or strengthen the magnet) before launching. + +**The consequence of dishonesty.** Readers download, find the gap between title and content, and unsubscribe. Worse, they remember the brand as the source of the gap. The conversion-rate metric looks fine; the brand reputation degrades. + +**The conservative title.** A title that slightly under-promises and then delivers more is better than a title that overpromises and disappoints. + +--- + +## Cover and visual presentation + +The cover is the second visual the reader processes (after the landing page hero). It should reinforce the title's specificity. + +**Strong cover patterns.** + +- **Type-driven covers.** The title in clean, large type. Color-blocked. Reads at thumbnail size. +- **Single-image covers.** A specific image (a screenshot, a diagram, a person) that signals what the magnet contains. +- **Brand-consistent covers.** Visual style matches the brand the magnet represents. + +**Weak cover patterns.** + +- **Stock-image covers.** Generic stock photos signal generic content. +- **Cluttered covers.** Too many visual elements; the title gets lost. +- **Off-brand covers.** Cover that does not match the brand the reader saw on the landing page; signals inconsistency. + +**The cover-as-thumbnail test.** The cover will be displayed at thumbnail size in social shares, in landing-page previews, and in delivery emails. Does it read at thumbnail size? If not, redesign. + +--- + +## Landing-page preview + +The landing page (which is the `landing-page-copy` skill's domain) should preview the magnet, not just describe it. + +**Strong preview patterns.** + +- **Show pages from inside.** Screenshots of actual pages from the magnet. The reader sees the resource before they download. +- **Show worked examples.** A specific page from the template, the checklist, or the swipe file. Concreteness lifts conversion. +- **Show the table of contents.** For longer magnets, show what is inside. The reader can predict whether the resource will help. + +**Weak preview patterns.** + +- **Stock-image hero only.** The landing page shows nothing of the actual magnet. The reader has to trust the marketing without evidence. +- **Generic descriptions.** "Learn the framework that..." without showing the framework. +- **Hidden contents.** "You will learn..." without showing what learning looks like in the resource. + +The preview is the second-best evidence that the magnet delivers (the best evidence is post-download, but the preview is the pre-download proxy). Strong previews lift conversion and reduce post-download disappointment. + +--- + +## First-page discipline + +The first page of the magnet is what the reader sees on opening. It sets the expectation for the rest. + +**The first page should deliver value within the first read.** The reader has just downloaded; they are most engaged in the first 30 seconds. Use the first page to deliver the headline insight, the first checklist item, the template's first prompt, the calculator's first input. + +**The first page should NOT.** + +- Warm up with author bio. The reader did not download the magnet to read about the author. +- Spend space on brand-positioning. The reader knows whose brand they downloaded from; they want the value. +- Recap the marketing. The landing page already sold the magnet; the first page should deliver, not re-sell. +- Defer the value. "In Chapter 3, you will learn..." loses the reader who wanted the value now. + +**The first-page test.** Open the magnet. Does the first page deliver something useful? If yes, the first-page discipline holds. If no, redesign the first page to deliver value upfront. + +--- + +## Title-magnet alignment audit + +Periodically audit titles against the magnets they represent. Drift accumulates: titles get polished while magnets remain unchanged, and the gap between promise and delivery widens. + +**The audit.** + +- For each active magnet, read the title and open the magnet. +- Does the magnet deliver on the title's specific promise? +- If not, the gap is either a title that overpromises (fix the title) or a magnet that underdelivers (strengthen the magnet). + +**The audit cadence.** Quarterly is reasonable for active magnets. Drift detection is part of magnet portfolio maintenance. + +--- + +## Worked title revisions + +**Original title: "Marketing Automation Guide."** + +Failure: vague, generic, overpromises (which guide?). + +**Revised title: "The 7-email re-engagement sequence we send to trial signups who go cold (with open and click rates)."** + +What changed: specific deliverable (7-email sequence), specific situation (trial signups who go cold), specific evidence (open and click rates). + +**Original title: "B2B Lead Generation Playbook."** + +Failure: "Playbook" suggests volume without focus. "B2B Lead Generation" is too broad to focus a single resource. + +**Revised title: "The cold-email template for B2B SaaS founders selling into mid-market product teams."** + +What changed: specific format (template), specific audience (B2B SaaS founders), specific buyer (mid-market product teams). Niche by design. + +**Original title: "The Complete Pricing Guide."** + +Failure: "Complete" overpromises; "Pricing Guide" suggests volume; the guide will likely be a kitchen-sink-resource. + +**Revised title: "The pricing one-pager template for SaaS founders raising a seed round."** + +What changed: specific deliverable (one-pager template), specific situation (raising a seed round). Tight scope; usable immediately. + +The pattern: replace vague nouns and adjectives with specific deliverables, audiences, and situations. The revision often shrinks the addressable audience and improves the qualified-lead rate. + +--- + +## Common title and presentation failures + +**Title overpromises.** The reader downloads, opens, finds less than expected, and unsubscribes. + +**Title is generic.** Anyone could want this; no one specifically wants it. + +**Cover signals stock content.** Generic visual; reader's expectation drops before opening. + +**Landing page hides the magnet.** The reader has no evidence the resource will deliver; conversion suffers. + +**First page warms up instead of delivering.** Author bio, brand statement, table of contents. The reader's engagement drops. + +**Drift between title and content.** The title was strong at launch; the magnet has not been updated; the gap has widened over time. + +--- + +## Methodology-level choices that stay in the public skill + +Title patterns that work and fail. The honesty discipline. Cover and visual presentation patterns. Landing-page preview discipline. First-page discipline. The title-magnet alignment audit. Worked title revisions. Common failures. + +## Implementation choices that stay internal + +Specific titles for the team's magnets. Specific cover-design conventions and brand application. Specific landing-page templates and layout choices. Specific first-page templates and brand voice. The team's audit calendar and revision processes. These vary by team. diff --git a/skills/lead-magnet-design/references/would-they-pay-for-this-test.md b/skills/lead-magnet-design/references/would-they-pay-for-this-test.md new file mode 100644 index 0000000..3b1db15 --- /dev/null +++ b/skills/lead-magnet-design/references/would-they-pay-for-this-test.md @@ -0,0 +1,158 @@ +# The "would they pay for this" test + +The pricing thought experiment that distinguishes earned-value from thin-bait. A single test the magnet either passes or fails before launch. + +The question is simple. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails the test is signaling that the value is below "I would pay for this," which means the reader's time investment to download and consume is at the edge of "worth it." The unsubscribe rate, the reduced trust, and the wasted email gate all follow from a failed test. + +--- + +## How to apply the test + +The test is a thought experiment, not a market study. Run it before the magnet ships. + +**Step 1: Imagine a stranger in the target audience.** Not the team's existing customer; not someone already on the list. A stranger who has not yet committed to the brand. + +**Step 2: Imagine showing them the magnet (the actual content, not the marketing).** Not the landing page; not the headline; the resource itself in the form they would receive it. + +**Step 3: Ask: would this person, having seen this resource, pay something for it?** A small amount, an honest amount. + +**Step 4: Be specific about the price.** Would they pay 5 dollars? 25 dollars? 100 dollars? The specific number forces an honest answer. + +The test fails when the honest answer is "no, they would not pay for this; they would expect it to be free or to come bundled with something else." The test passes when the honest answer is "yes, this is worth paying for, even at a small price, because the value is concrete." + +--- + +## What the test catches + +Three failure modes the test catches reliably. + +**The 5-page PDF that summarizes blog content.** Free elsewhere, available without a gate, worth 0 dollars in a paid context. Fails. + +**The "Ultimate Guide" that nobody finishes.** Pay-worthy in theory (comprehensive coverage), not delivered in usable form. The reader pays for the resource and never extracts the value because the resource is too long to consume. The test surfaces this when the team imagines whether the reader would actually use what they paid for. + +**The template that is so generic it adds no value over starting from scratch.** Pay-worthy framing (templates feel valuable), thin in execution (the template's content is "Insert your value here" 30 times). The test catches this when the team imagines the reader's reaction on opening the template. + +The test catches these failures because the question forces honesty about the resource's actual value rather than the resource's marketing claim. + +--- + +## What the test the magnet should pass looks like + +A magnet that passes is one where: + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +The first criterion is about value. The second is about usability. The third is about uniqueness or curation. A magnet that hits all three earns the email reliably. + +**Worked example: A passing magnet.** + +The B2B SaaS founder magnet "the welcome-email template that 4x'd our trial-to-paid rate." + +- Pay-worthy: a SaaS founder would pay 25-50 dollars for a template that demonstrably 4x'd a real trial-to-paid rate. The specificity (4x, real metric, real source) makes the payment plausible. +- Usable: 7 emails, copy-paste ready, with sender-side context for each. A founder can implement in 60 minutes. +- Unique: the specific template plus the specific result is not freely available elsewhere. + +The magnet passes. It is worth the email. + +**Worked example: A failing magnet.** + +The "Marketing Trends 2026" PDF. + +- Pay-worthy: a generic trends roundup is not worth paying for. Freely available analyses cover the same ground. The specificity is missing. +- Usable: a 30-page PDF of trend descriptions does not produce a result; it produces awareness, which the reader could have gotten elsewhere. +- Unique: marketing trend roundups are commoditized; this one is not differentiated. + +The magnet fails. It captures emails that decay because the resource did not earn the relationship. + +--- + +## When the test surfaces "almost passes" + +Sometimes the answer is "they might pay 5 dollars but not 25 dollars." This is signal, not failure. + +**The action.** Strengthen the resource until the answer becomes "yes, they would pay 25 dollars." This often means adding the specific worked example, the specific case study, or the specific tooling that makes the resource concretely useful. + +**The risk of skipping.** Shipping the "5 dollar" version saves time but produces conversion-rate metrics that look fine and lead-quality metrics that disappoint. The strengthened version costs more upfront and pays back in lead quality and downstream conversion. + +The test surfaces the gap between the magnet as built and the magnet at value-strong. The work to close the gap is often the difference between thin-bait and earned-value-magnet. + +--- + +## When the test surfaces "this should not be a magnet" + +Sometimes the honest answer is that the resource would not be paid for at any price. + +**The action.** Do not ship the magnet. Either redesign the resource until it would be paid for, or accept that the resource is content (not a magnet) and publish it ungated. + +**The release valve.** Not every piece of content has to be gated. Free, ungated content has its own value (SEO, distribution, brand). Forcing a gate onto thin content costs more than it adds. + +The test sometimes leads to "this should not be a magnet at all." That outcome is fine; it prevents shipping a thin-bait magnet that costs list trust. + +--- + +## When the test surfaces "this is so valuable we should sell it" + +Occasionally the honest answer is that the resource would be paid for at a meaningful price (200 dollars, 500 dollars). + +**The decision.** The team has a choice. Sell the resource (and use a different, more right-sized magnet for list-building) or use the high-value resource as the magnet (which signals exceptional generosity and often produces strong conversion at high lead quality). + +**The high-value-as-magnet pattern.** Some brands give away exceptionally valuable resources as magnets specifically to signal expertise and generosity. The conversion to paid offerings often increases because the magnet establishes credibility. + +The test surfaces this opportunity. The team's decision depends on the broader strategy. + +--- + +## The team-honesty discipline + +The test only works if the team answers honestly. Pressure to ship, sunk cost in production, attachment to the magnet's framing all bias the answer toward "yes." + +**The discipline.** + +- Have someone outside the magnet's authoring team apply the test. Outside-in honesty often catches what the authoring team rationalizes. +- Show the actual resource, not the marketing. The pretty landing page is not the test; the PDF or the template is. +- Be specific about the price. "Would they pay something" is too vague; "would they pay 25 dollars" forces specificity. +- Take the answer seriously. If the team applies the test and answers no, do not ship the magnet without redesign. + +The test's value is in the honesty it surfaces. A team that applies it and ignores the answer is worse off than a team that does not apply it at all. + +--- + +## What to do when the test fails + +The magnet fails the test. Now what. + +**Option 1: Strengthen the magnet.** Add the specific worked example, case study, tooling, or framework that brings the value to pay-worthy. This is often the right answer. + +**Option 2: Redesign as a different format.** The topic might not be magnet-shaped in the current format. A 30-page ebook on a topic might fail; a 2-page checklist on the same topic might pass. + +**Option 3: Reframe the audience.** The magnet's value depends on the audience. A magnet that fails for the broad audience might pass for a narrower segment that genuinely needs the resource. + +**Option 4: Do not ship.** Some magnets should not exist. Killing the magnet is honest; shipping a thin one costs more in list trust than killing it costs in sunk effort. + +The team's response to a failed test is the discipline marker. Strong programs redesign or kill; weak programs ship anyway. + +--- + +## Common test failure modes + +**The team rationalizes the failure.** "It is good enough; readers will appreciate it being free." This is the path to thin-bait. + +**The team applies the test to the wrong audience.** "Would a generalist marketer pay for this" when the magnet is for SaaS founders. The test must use the actual target audience. + +**The team applies the test to the marketing, not the resource.** The landing page sounds great; the resource is thin. The test surfaces this when applied to the actual content. + +**The team skips the test under deadline pressure.** The magnet ships, the metrics look fine, the unsubscribe rate quietly climbs. The test was the protection against this; skipping it costs trust. + +--- + +## Methodology-level choices that stay in the public skill + +The test as a thought experiment with specific steps. The failure modes the test catches. The criteria a passing magnet meets. The team-honesty discipline. The decision tree when the test fails. The test failure modes. + +## Implementation choices that stay internal + +Specific magnets the team has tested and the outcomes. Specific price-point conventions for the team's audience. The team's outside-team review process. Specific redesign patterns the team uses for failing magnets. These vary by team and audience. diff --git a/skills/logo-design/SKILL.md b/skills/logo-design/SKILL.md new file mode 100644 index 0000000..75d1e26 --- /dev/null +++ b/skills/logo-design/SKILL.md @@ -0,0 +1,206 @@ +--- +name: logo-design +description: "Generate logo variants for a brand, producing multiple production-grade marks across different architectures (wordmark, lockup, symbol-only, letterform-as-symbol, monogram) with rationale, application specs, and decision-ready presentation. Distinct from `brand-identity`, which produces the complete system (logo plus color, type, voice, applications). Goes deep on the logo specifically: typographic register, symbol approach, application-context discipline (16px favicon, embroidery, signage, motion), and production specs (SVG-ready, single-color, reverse). Triggers on logo design, design a logo, wordmark, monogram, lockup, mark variants, logo iterations, redesign or refine the logo, logo refresh, letterform-as-symbol, and exploring mark variants for an established brand. Does NOT fire for full brand identity (use `brand-identity`), positioning or strategy (use `brand-discovery`), project-wide creative direction (use `creative-direction`), or one-off illustration." +category: brand +catalog_summary: "Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol), with rationale and application specs" +display_order: 5 +--- + +# Logo Design + +A logo is a system of marks, not a single drawing. This skill produces multiple production-grade variants exploring different architectural approaches, each with rationale, application specs, and a clear position on what it signals and rejects. + +The output is decision material, not a finished logo. The brand owner selects from the variants and the skill produces production refinement on the chosen direction. + +--- + +## When to use + +- The brand has a name and tonal direction; the deliverable is logo work specifically +- Generating 6 to 12 variants for client review and selection +- Refining a wordmark to production: kerning, optical adjustments, weight selection +- Exploring symbol options to pair with an existing wordmark +- Designing a monogram from a longer name for use in constrained contexts +- Adapting an existing logo across application contexts (small-size, signage, motion, embroidery) +- The brand owner has reviewed a first round and wants iteration on a specific direction + +## When NOT to use + +- Use `brand-identity` instead when the deliverable is the complete identity system (logo plus color plus type plus voice plus applications). This skill is the logo-specific layer; brand-identity is the system layer. +- Use `brand-discovery` for brand positioning, audience, and voice work. A logo without strategy is a drawing. +- Use `creative-direction` for project-wide aesthetic direction. Creative direction calibrates many decisions; logo design produces specific marks. +- One-off illustration, icon, or pictogram work +- Designing brand patterns, textures, or supporting graphics +- Pure typographic exploration unrelated to a brand name + +--- + +## Required inputs + +- **Brand name.** Exact spelling. Capitalization and punctuation preferences if any. Whether the name has a category descriptor that travels with it (e.g., "Atlas Coffee" vs just "Atlas"). +- **Industry or category.** Legal firm, consumer goods, B2B SaaS, hospitality, etc. Category implies defaults that can be honored or broken. +- **Audience.** Who sees the logo, where, in what state of mind. The audience-side perception drives selection more than the founder-side aesthetic. +- **Tonal direction.** Where on the formal-to-casual axis. Where on the restrained-to-expressive axis. Where on the heritage-to-modern axis. +- **Application contexts.** Common set: web header, mobile app icon (28px), favicon (16 to 32px), business card, letterhead, email signature, social profile picture, signage (large format), embroidery patch (1.5 inch), single-color print, video motion lockup, merch (apparel, hats, totes). +- **Reference logos liked**, with a sentence each on what specifically resonates. The reference clarifies which architecture and register fit better than abstract description does. +- **Reference logos disliked**, with a sentence on what to avoid. Negative space sharpens positive selection. +- **Hard constraints.** Must include element X. Must avoid color Y due to industry conventions. Must reproduce in single color. Must work as a 16px favicon. Must survive embroidery. +- **Optional**: existing brand assets if the project is a refresh, not greenfield. Existing wordmark if the work is symbol-only. Existing color palette if it must remain locked. + +--- + +## The framework: 5 considerations for logo design + +A logo decision sits at the intersection of five considerations. Each one filters subsequent choices. + +### 1. Mark architecture + +What IS the logo, structurally? + +**Architectures:** + +- **Wordmark only.** The logo is the brand name set in a chosen typeface, possibly with custom letterforms. Stripe, Google, Pinterest. The discipline is letter-by-letter, with kerning, optical adjustments, sometimes a single distinguishing custom character. Strongest when the name is distinctive enough to own as type. +- **Lockup (wordmark plus symbol).** Standard architecture for most brands. The wordmark and symbol are positioned in a fixed relationship. Slack, Airbnb, Asana. Variants: symbol left of wordmark, symbol above wordmark, symbol right (rare). Each lockup may also have a stacked alternate for square contexts. +- **Symbol only.** The mark is a single symbol with no wordmark. Apple, Twitter, Target. Earned over decades through brand recognition. New brands rarely succeed with symbol-only as the primary mark, though most mature brands eventually develop a symbol-only fallback. +- **Letterform-as-symbol.** A single letter from the name (often the first) becomes the symbol. Beats by Dre's "b", McDonald's "M", Underscore's "_". Cleanest path to symbol when the wordmark is too long for a tight lockup or when the name has a letter that lends itself to visual play. +- **Monogram.** Multiple letters combined as a symbol. CN (Chanel), GG (Gucci), HBO, MN (a hypothetical Morgan Northrop monogram for an institutional financial firm). Common in legal, financial, hospitality, and heritage brands. Can read as initials or as ligature. + +**How to choose:** What does the brand need to do at small sizes? At 16px, most lockups fail. A favicon-grade mark needs either a strong symbol component or a letterform-as-symbol fallback. Lockups also need stacked alternates for square contexts (social profile pictures, app icons). A pure wordmark works only if the brand has another mark that can stand in at small sizes, often a letterform-as-symbol or monogram. + +A common production setup is: primary lockup for most contexts, monogram for square contexts, letterform-as-symbol for favicon and embroidery. All three derive from the same wordmark and share visual DNA. + +### 2. Typographic register + +If wordmark or lockup, what typographic family carries the type? + +**Registers:** + +- **Geometric sans.** Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde. Built from circles and verticals. Reads modern, considered, often optimistic. Risks reading cold or generic-tech-startup if not warmed up by color, custom letterform, or context. +- **Humanist sans.** Gill Sans, Optima, Frutiger, Source Sans, Inter at higher optical sizes. Has serif-like calligraphic gestures without serifs. Reads professional but warm. Excellent neutral choice when the category demands restraint with personality. +- **Neo-grotesque sans.** Helvetica, Inter, Aktiv Grotesk, Söhne, GT America. The modern professional default. Reads competent and contemporary. Risks reading generic if not paired with strong color or symbol. +- **Transitional serif.** Source Serif, Charter, Lyon, IBM Plex Serif. Modern serifs with high contrast and readability. Reads editorial, considered, intellectual. Good for legal, publishing, financial, editorial brands. +- **Old-style serif.** Garamond, Caslon, Sabon, Adobe Garamond. Classical serifs with low contrast and warm shapes. Reads heritage, traditional, institutional. Common in academic, legal, financial, and heritage brands. +- **Slab serif.** Sentinel, Adelle, Roboto Slab, Tisa. Heavy structural serifs. Reads strong, declarative, sometimes journalistic. Common in editorial and publishing. +- **Display custom.** A custom-drawn or heavily-modified typeface. Reads distinctive but expensive in time. Justified when the brand needs a wordmark no one else has and the budget supports drawing one. + +**How to choose:** What does the brand reject? Most categories have a default register. Legal firms default to old-style or transitional serif. Tech startups default to geometric or neo-grotesque sans. Choosing within the category default reads as competence; choosing outside reads as positioning. A boutique legal firm in geometric sans signals "modern, accessible". A SaaS startup in old-style serif signals "we take ourselves seriously". + +### 3. Symbol approach + +If the architecture includes a symbol (lockup, symbol-only, letterform-as-symbol), what KIND of symbol? + +**Approaches:** + +- **Literal.** The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. Fast recognition, low ambiguity. Risks reading as cliche if the depiction is generic. Saved by distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. +- **Abstract gesture.** The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity". Slower recognition, higher distinctiveness. Risks reading as arbitrary if the gesture is too abstract. Saved by clear formal logic and consistent visual vocabulary. +- **Geometric reduction.** The symbol is a formal abstraction with no specific referent. A hexagon, a triangle, a stack of horizontal lines, a circle bisected by a vertical. Reads modern and confident. Risks reading as identical to many other geometric-reduction marks. Saved by specific proportions, considered execution, and pairing with a distinctive wordmark. +- **Letterform-derived.** The symbol is built from the name's letterforms. The "M" of McDonald's, the "b" of Beats, a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. Strong wordmark-symbol coherence. Risks reading as wordmark-only if the letterform isn't emphasized enough. Saved by exaggerated character: the letter must read as both the letter AND the visual metaphor. +- **Monogram.** Multiple initials combined. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). Common in legal, financial, hospitality. Risks reading as old-fashioned if the type treatment is too conservative. Saved by modern execution within traditional architecture. + +**How to choose:** What does the brand name already do? Descriptive names (Atlas, Forge, Pulse, Anchor) invite literal symbols and letterform-as-symbol approaches. Abstract names (Stripe, Anthropic, Linear) demand abstract or geometric-reduction symbols. Heritage names (a founder's surname, a place name) often use monograms. The wrong approach disconnects symbol from name. + +### 4. Application context discipline + +A logo is not a single drawing. It must work in every context the brand touches. + +**Contexts and their constraints:** + +- **16px favicon.** The most aggressive small-size test. Lockups usually fail here; the symbol or letterform-as-symbol carries. Plan a fallback mark for this context from the start. +- **28px app icon.** Slightly more headroom than favicon. Still demands strong silhouette. Often uses the symbol or monogram, not the lockup. +- **1.5 inch embroidery patch.** Limits color count (often 4 to 6 max), demands clean shapes without fine detail. Eliminates gradient and photographic elements. Tests the mark's reproducibility in a tactile medium. +- **Single-color reproduction.** Etching, foil stamp, single-color print, fax. All gradient and color-dependent decisions must collapse cleanly to one color. Test by converting the design to pure black on white. +- **Reverse (light on dark).** Many marks fail when reversed. Test on the brand's expected dark backgrounds early. Gradient marks particularly struggle here. +- **Large-format signage.** Requires sharp vector with no rasterization. Tests construction grid quality. Tests whether thin strokes survive scaling. +- **Motion lockup.** Tests whether the logo has natural entry and exit animation. Wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts. +- **Social profile picture (square).** Lockups need a stacked alternate or monogram fallback. Symbol-only works natively. +- **Apparel embroidery (thread on fabric).** Tighter constraints than patch embroidery. Fine letterforms and detail die here. The mark needs a chunky-friendly variant. +- **Foil stamp on paper or leather.** Single-color, no gradients, requires substantial line weight to survive the impression. + +**The discipline:** Every variant must pass the application-context test before it's a contender. Generate each variant, then mentally test each context. If a variant fails three or more contexts, it's not a primary mark; it might still serve as a secondary or display lockup but it isn't carrying the brand. Build a fallback hierarchy: primary lockup, secondary monogram, favicon-grade letterform-as-symbol. + +### 5. Restraint discipline + +Most logo failure happens through over-design. The discipline is subtractive. + +**Tests:** + +- **Silhouette test.** Squint at the logo. If you cannot identify it from silhouette alone (with type stripped), the silhouette is too generic. Apple, Nike, Twitter pass. Most generic SaaS marks fail. +- **Distinctiveness test.** Search Google Images for "[your category] logo". If your candidate looks identical to three or more existing logos, it's not distinctive enough. Especially watch out for geometric-reduction marks that have already been done a thousand times. +- **Sketchability test.** A 7-year-old draws the logo from memory after 30 seconds of looking. If they can't, it's too detailed to live in cultural memory. +- **Single-color test.** Strip all color. Does it still read? If no, color is doing too much work. +- **Reproducibility test.** Print at 1 inch on a black-and-white printer. Is it still recognizable? If no, the mark won't survive embroidery, foil stamps, or low-resolution applications. +- **The two-second test.** Show the logo to someone unfamiliar with the brand for two seconds. Ask what they remember. The features they recall are the ones doing real work; the rest is noise. + +The discipline doesn't reject all detail. It rejects detail that doesn't earn its place. Every visual element should pass the question "does this read at the smallest application size?". + +--- + +## Workflow + +1. **Gather inputs.** Required inputs above. If the user has reference logos, walk through what specifically resonates in each. The references calibrate which architecture and register actually fit. + +2. **Establish primary architecture.** Wordmark-only? Lockup? Letterform-as-symbol? Monogram? This is the foundational decision; everything else flows from it. For most new brands with a distinctive descriptive name, the right architecture is lockup with literal or letterform-derived symbol, plus a monogram fallback for square contexts. + +3. **Generate typographic explorations.** Produce 3 to 4 wordmark-only variants exploring different typographic registers. Each variant should be a complete, kerned, optically-adjusted wordmark. These serve as both standalone candidates and as the foundation for subsequent symbol pairing. + +4. **Generate symbol explorations** (if architecture includes a symbol). For each typographic exploration, generate 1 to 2 symbol pairings using different symbol approaches (literal, abstract gesture, letterform-derived, monogram). The symbol must visually agree with the wordmark's type weight, optical density, and tonal register. A heavy slab wordmark needs a chunky symbol; a hairline geometric wordmark needs a thin symbol. + +5. **Test each variant against application contexts.** For each candidate, walk through 16px favicon, 1.5 inch embroidery, single-color reproduction, square stacked alternate. Eliminate variants that fail more than two contexts. Document which contexts each variant excels in versus needs a fallback for. + +6. **Pick top candidates for client review.** Typically 6 to 12 final variants. Each variant must be visually distinct from the others. Variants that are too similar dilute the review and frustrate the client (they cannot tell why they should pick one over the other). + +7. **Document each variant.** Per-variant: descriptive name (e.g., "01, Light geometric wordmark, Avenir Next"), architecture, typography, symbol approach if applicable, color tokens, application notes, signals (what it communicates), rejects (what it explicitly is NOT). + +8. **Provide production specs** for the top 3 candidates. SVG-ready construction notes, color hex codes (primary plus single-color black plus single-color white plus reverse), sizing guidelines (minimum sizes per medium), motion entry and exit recommendation, embroidery and foil-stamp adaptations. + +9. **Provide application mockups.** Render each top candidate in 3 to 5 representative contexts: web header, business card, favicon at 16 and 32px, embroidery patch, signage. Mockups can be image-generated or schematic. The point is to show the client how the mark lives across contexts, not to deliver finished marketing material. + +10. **Hand off.** Output is decision material. The brand owner selects a direction. The skill (or a follow-up iteration) then produces production refinement on the chosen path: cleaner construction, refined kerning, color system finalization, application library. + +--- + +## Failure patterns + +- **Designing for the founder's taste, not the audience's perception.** The founder sees the logo every day; the audience sees it for 3 seconds in a bad mood. The audience-side test wins. +- **Skipping the silhouette test.** Logos that fail silhouette die at small sizes and in motion. Test early. +- **Ignoring small-size legibility.** A favicon test at 16px is the single most overlooked discipline. Most lockups fail here. Plan a fallback symbol or letterform-as-symbol mark from the start. +- **Trying to depict everything the brand does.** Logos can hold one idea, sometimes two. Three is too many. Symbols stuffed with multiple metaphors read as committee work. +- **Picking a typeface for trend.** Monoline geometric sans (Cabinet Grotesk, GT Pressura) read as "2024 startup" in a way that ages quickly. Pick for category-fit and longevity, not for design-trend currency. +- **Over-customizing letterforms.** Custom letterforms should solve a specific problem (a flat-bottomed "g" that conflicts with a descender, an "a" that breaks the rhythm, an "A" that becomes a mountain peak). Custom for novelty's sake reads as gimmicky. +- **Lockups that fall apart at certain sizes.** Test the lockup at 200%, 100%, 50%, 25%. If proportions break or elements clash at any size, the lockup needs adjustment. +- **Color-dependent marks.** A logo that requires color to be recognizable cannot survive single-color reproduction. Color is the last layer, not the foundation. +- **Letterform-as-symbol marks that fail the silhouette test for the underlying letter.** An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. +- **Reviewing too many similar variants.** Showing a client 10 wordmark variants in different geometric sans typefaces dilutes the decision. Show 3 architectures, with 2 to 3 typographic options each. The client can see the architectural choice clearly. +- **Skipping the embroidery test.** Many brands eventually want a hat or a polo. A logo with fine detail or photographic gradients cannot be embroidered cleanly. Test before client signoff. + +--- + +## Output format + +Default output is a markdown spec with multiple variants, typically saved as `logo-variants.md` at the project root or in a `design/` subdirectory. The spec is paired with rendered images for each variant, saved alongside (typically in `design/logo-variants/`). + +Per-variant structure: + +1. **Variant name.** Descriptive identifier with index (e.g., "01, Light geometric wordmark, Avenir Next" or "07, Mountain peak A lockup, IBM Plex Sans"). +2. **Architecture.** Wordmark / Lockup / Symbol / Letterform-as-symbol / Monogram. +3. **Typography.** Specific typeface name and weight. Custom letterform notes if any. Tracking and kerning treatments. +4. **Symbol description** (if applicable). Approach (literal / abstract gesture / geometric reduction / letterform-derived / monogram) and visual description. Construction grid notes if relevant. +5. **Color tokens.** Hex codes for primary palette, single-color black version, single-color white version, reverse-on-dark treatment. +6. **Application notes.** Which contexts the variant excels in (e.g., "strong at large signage and letterhead") and which contexts need a fallback mark (e.g., "favicon falls back to letterform-as-symbol at 16px"). Embroidery adaptation notes if relevant. +7. **Signals.** What this variant communicates about the brand. The features it foregrounds. +8. **Rejects.** What this variant explicitly is NOT. The negative space the variant creates. +9. **Mockups.** Rendered in 3 to 5 application contexts. At minimum: web header, business card, favicon. Bonus: embroidery patch, large-format signage, social profile. + +The spec is decision material. The next step after delivery is selection plus production refinement on the chosen direction. + +--- + +## Reference files + +- [`references/architectures-explained.md`](references/architectures-explained.md). The 5 mark architectures with examples, when each fits, when each fails, and how to combine them in a primary plus fallback hierarchy. +- [`references/typographic-registers.md`](references/typographic-registers.md). The typographic registers with named typefaces, category-fit notes, and example brands per register. +- [`references/symbol-approaches.md`](references/symbol-approaches.md). The 5 symbol approaches with pattern examples, calibrating the agent's vocabulary for symbol generation. +- [`references/application-contexts.md`](references/application-contexts.md). The contexts every logo must pass, with constraint specs (favicon size, embroidery color count, single-color rules, motion entry recommendations). +- [`references/category-conventions.md`](references/category-conventions.md). A survey of common conventions across major brand categories, with defaults that work, conventions worth honoring, conventions worth breaking for positioning, and category-specific application contexts. +- [`references/example-variant-spec.md`](references/example-variant-spec.md). A complete example showing all nine per-variant fields filled in for a representative project. +- [`references/client-package.md`](references/client-package.md). The package format clients expect at delivery: file format matrix, variant matrix, folder structure, naming convention, documentation layer (usage guide plus brand colors plus license), delivery mechanisms, and the failure patterns that send the client back asking for a missing variant. diff --git a/skills/logo-design/references/application-contexts.md b/skills/logo-design/references/application-contexts.md new file mode 100644 index 0000000..a9cba88 --- /dev/null +++ b/skills/logo-design/references/application-contexts.md @@ -0,0 +1,312 @@ +# Application contexts + +A logo is not a single drawing. It is a system of marks that must work in every context the brand touches. Most logo failure happens because a designer optimized for one context (typically the web header at 200px wide) and never tested the others. This file expands the application contexts in [SKILL.md](../SKILL.md) with specific constraint specs, common failure modes, and mitigation patterns. Use it as the working checklist for every variant before declaring a candidate ready for review. + +The discipline is to design for the smallest, harshest application FIRST, then scale up. Most brand systems do the opposite: they design at the marketing scale and discover at production time that the mark cannot survive its smaller, harsher applications. + +--- + +## 16px favicon + +The most aggressive small-size test. The mark renders inside a 16x16 pixel grid (some browsers go to 32x32, but 16x16 is the historical baseline and still the test that reveals construction problems first). + +### Constraints + +- 16x16 pixels means roughly 4 to 6 distinguishable visual elements maximum +- No fine detail; lines under 2px disappear +- No gradients (gradients render as muddy color washes at this scale) +- No more than 3 to 4 colors before the rendering algorithm dithers +- Symbol or letterform must read at thumbnail scale, not as a logo + +### Failure modes + +- Lockups (wordmark plus symbol) almost always fail; the wordmark becomes illegible +- Fine letterform details (custom serifs, decorative crossbars) disappear +- Multi-color symbols dither into pixel noise +- Symbols with internal cutouts or fine negative space lose the cutout at 16px +- Geometric reductions with multiple primitives blur together + +### Mitigation patterns + +- Ship a dedicated 16x16 favicon-grade asset, not a downscaled version of the lockup +- Use a single element from the lockup (the symbol alone, the letterform-as-symbol, or the monogram) at favicon scale +- Test the favicon on actual browser tabs (Chrome, Safari, Firefox) at the operating system level; the rendering differs from a Photoshop preview +- If the favicon-grade asset cannot be derived from the lockup, the lockup itself is over-detailed; redesign the lockup so a clean 16x16 fallback exists + +--- + +## 28px app icon + +iOS, Android, and PWA app icons. Slightly more headroom than favicon (28x28 to 60x60 depending on rendering context) but still demanding strong silhouette. + +### Constraints + +- 28x28 to 60x60 pixels (varies by OS rendering context: notification badge, home screen, settings menu) +- Must work inside rounded-square or circle masks (iOS), rounded-square (Android) +- 4 to 8 distinguishable visual elements maximum +- Background color matters: app icons have visible bounds, so the mark either fills the icon background or sits inside a colored field +- No fine detail; lines under 3px disappear at the smallest rendering scales + +### Failure modes + +- Lockups fail at this scale almost as often as at favicon scale +- Symbols with thin strokes lose definition +- Multi-color symbols clash with the icon background fill +- Marks that depend on negative-space cutouts lose those cutouts +- Marks designed for a square ratio fail when rendered inside a circle mask + +### Mitigation patterns + +- Design the app icon as a separate asset, not a downscaled lockup +- Use the symbol or monogram, not the wordmark +- Pick a strong fill color that supports the symbol (not a generic white background) +- Test the app icon at every required size (29, 40, 60, 76, 80, 87, 120, 152, 167, 180, 1024 for iOS) and at every mask shape (rounded-square iOS, circle for some Android launchers) +- Ship a "monochrome" or "tinted" variant for iOS dark mode and tinted home screen modes (a single-color silhouette of the app icon) + +--- + +## 1.5 inch embroidery patch + +Tactile reproduction at small scale. Embroidered patches for hats, jackets, polos, and merchandise. The most demanding physical reproduction context. + +### Constraints + +- 1.5 inch diameter is the common patch size (some go to 2 or 2.5 inches) +- Color count: 4 to 6 maximum (each thread color is a separate setup cost) +- Minimum stroke weight: roughly 1mm (depends on the embroidery machine and thread weight) +- No gradients, no photographic elements, no fine textures +- Letterforms below 2mm tall do not embroider cleanly +- Sharp inside corners and acute angles fail under the needle path + +### Failure modes + +- Marks with more than 6 colors require expensive multi-step embroidery or get simplified by the embroiderer in ways the brand owner did not approve +- Fine letterforms (Garamond at small sizes, Helvetica Light) become muddy or fall apart +- Gradient marks fail entirely; the embroiderer either drops the gradient (changes the brand) or refuses the job +- Symbols with thin internal lines lose those lines under the thread weight +- Marks designed for screen do not anticipate the chunky construction embroidery requires + +### Mitigation patterns + +- Design an embroidery-grade variant of the mark from the start: simplified silhouette, chunky stroke weights, 4 colors maximum +- Test the variant against an actual embroidery sample (not a screen preview) before committing +- Pick a typeface for the wordmark that survives embroidery (slab serifs, heavy sans-serifs, custom thick letterforms work; thin sans-serifs and Garamond do not) +- For brands that anticipate substantial merchandise (apparel brands, hospitality brands, sports teams), build the embroidery-grade variant into the primary system, not as an afterthought + +--- + +## Single-color reproduction + +The mark must render in a single color, on any background, for any reproduction medium that does not support color. Etching, foil stamp, single-color print (offset or letterpress), faxed documents (still happens for legal and financial), engraving, screen printing limited to a single color. + +### Constraints + +- Pure black on white, pure white on black, or single ink color +- No gradients (must collapse to flat color) +- No color-dependent meaning (a symbol that means one thing in red and another in blue fails) +- No subtle color contrasts (a symbol with two shades of gray loses information when reduced to one color) + +### Failure modes + +- Color-dependent marks (the brand identity is the color, not the form) cannot be reproduced +- Gradients become muddy in single-color etching or foil +- Multiple-color symbols collapse to a single shape that does not read as the original +- Marks that rely on color-coded brand meaning (red = action, blue = trust) lose meaning +- Embossed or debossed reproductions test the construction grid; thin lines fail under embossment + +### Mitigation patterns + +- Test the design as a pure black-on-white silhouette early; if it does not read in monochrome, color is doing too much work +- Build a dedicated single-color version of the mark with stroke weights and proportions adjusted for monochrome reproduction +- Make sure the single-color version reads as the brand without color +- Pick application contexts that match the single-color variant (foil stamp on letterhead, engraved signage, etched glass, leather embossing, single-color print) + +--- + +## Reverse on dark + +The mark on a dark background. The brand's web header in dark mode. The signage at night. The product photography on a black field. The letterhead variant for black envelopes. Many marks fail when reversed because the negative space and stroke balance shift. + +### Constraints + +- Light strokes on dark background; the form is what is visible, not what is empty +- Gradient marks particularly struggle (the gradient direction may need to invert) +- Color contrast must remain readable (a brand color that works on white may disappear on black) +- Negative-space marks (where the brand identity is the empty space, like FedEx's hidden arrow) require careful inversion handling + +### Failure modes + +- Marks designed for light backgrounds invert into something that looks like a different mark +- Color contrast fails (yellow on black is fine; pale yellow on black is illegible) +- Thin strokes optimized for white-on-black render too heavy when inverted to black-on-white +- Symbols with internal cutouts work in one direction but not the other +- Brand color decisions made for one direction read wrong in the other + +### Mitigation patterns + +- Test every mark on dark backgrounds early in the process, not at production time +- Build dedicated reverse-on-dark variants where stroke weights or proportions are adjusted +- For marks that must work on both light and dark, design the construction grid so it is direction-neutral (Apple's apple, Nike's swoosh) +- For marks that cannot be neutral, ship two variants: light-on-dark and dark-on-light, with construction tuned for each + +--- + +## Large-format signage + +The mark at building scale. Storefront signage, lobby walls, conference signage, billboard, vehicle wrap. The opposite end of the scale spectrum from favicon. + +### Constraints + +- Sharp vector with no rasterization; print resolution must support 12+ feet output +- Construction grid integrity matters at every scale (proportional adjustments that work at 1 inch may not work at 12 feet) +- Thin strokes that survive at marketing scale may look anemic at signage scale +- Color reproduction differs (a brand color that prints clean on paper may print different on backlit acrylic, vinyl, or painted aluminum) +- Distance reading: the mark must read at street scale (50 to 200 feet) + +### Failure modes + +- Wordmarks with thin strokes look anemic at 12 feet +- Fine letterform details that read at marketing scale disappear at signage scale +- Color decisions based on screen rendering do not match the actual material (vinyl, paint, acrylic, illuminated channels) +- Lockups designed for desktop scale crowd or stretch when forced into signage's typical aspect ratios + +### Mitigation patterns + +- Test the mark at 8 to 12 feet wide as a printed mock-up before committing +- Build signage-grade variants where stroke weights are adjusted for distance reading +- Specify Pantone colors (not RGB or hex) for signage color reproduction +- For illuminated signage (channel letters, backlit acrylic), test the mark with the illumination direction the actual sign will use (front-lit, halo-lit, edge-lit each render differently) + +--- + +## Motion lockup + +The mark in animation. Brand entry sequences in video, app launches, motion identity. The mark is no longer static; it moves, scales, fades, transforms. + +### Constraints + +- The mark must have a natural entry and exit animation +- The construction must support stage-by-stage reveal (wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts) +- Frame rate: 30 to 60 fps for web, 24 fps for film +- Total animation duration: typically 1 to 3 seconds for brand entry; 0.5 to 1 second for app launch +- Easing curves must feel intentional, not generic + +### Failure modes + +- Marks with arbitrary construction have no natural animation; they snap into place rather than assembling +- Wordmarks animated with random letter entrance look generic; the entrance must follow the letterform construction +- Symbols animated with rotation or scale alone read as obvious; the animation should reveal something about the symbol's construction +- Animation duration too long becomes annoying; too short and the mark does not register + +### Mitigation patterns + +- Design the mark with animation in mind: the construction should suggest its own assembly +- Specify the motion direction: how does the mark enter, hold, and exit? +- Build a 1-second motion identity that works for app launch, video brand entry, and social media +- Test the motion at the actual deployment surface (app launch screen, social video, in-product brand entry) + +--- + +## Social profile picture (square) + +The mark in a square crop, usually inside a circle mask (Twitter, Instagram, LinkedIn, most social platforms). Lockups need a stacked alternate or symbol-only fallback. Symbol-only marks work natively. + +### Constraints + +- Square aspect ratio (often 400x400 to 800x800 pixels for social profile) +- Often rendered inside a circle mask, so the corners of the square are cropped +- Small enough size that fine detail disappears +- Must read in the user's notification feed at thumbnail scale (60-80 pixels) +- Color contrast against various background colors (light and dark mode platforms) + +### Failure modes + +- Horizontal lockups crop badly inside square; the wordmark loses its left and right edges +- Marks not designed for circle masking lose corners and read as cropped +- Detail that survives at 200x200 disappears at the 60-80 pixel notification feed scale +- Color choices that work on white backgrounds clash with the platform's darker UI + +### Mitigation patterns + +- Design a stacked alternate (symbol above wordmark, centered) for square contexts +- Use the symbol-only or monogram fallback for the social profile +- Test the mark inside a circle mask, not just inside a square +- Verify the mark reads at notification feed scale (60-80px), not just at the profile picture display scale (200-400px) + +--- + +## Apparel embroidery + +Thread on fabric, smaller scale than patch embroidery. Polo shirts, hats, beanies, t-shirts, aprons. The mark is embroidered directly into the fabric, often without a patch backing. + +### Constraints + +- Color count: 4 to 6 maximum (each thread color is a setup cost) +- Minimum stroke weight: 1.5mm to 2mm (heavier than patch embroidery because the fabric is the substrate) +- No gradients, no fine detail, no photographic elements +- Letterforms below 2.5mm tall do not embroider cleanly +- Fabric texture affects the read (cotton vs polyester vs wool render differently) +- The mark must survive washing (thread that bleeds or unravels on first wash is a quality failure) + +### Failure modes + +- Fine wordmark letterforms become muddy or fall apart +- Multi-color marks become expensive or get simplified without approval +- Marks with thin strokes do not survive washing cycles +- Marks not designed for fabric look pasted-on rather than embroidered + +### Mitigation patterns + +- Design a dedicated apparel-embroidery variant with chunky stroke weights and minimal color +- Specify thread colors (Madeira, Robison-Anton, or other professional embroidery thread brands) rather than CMYK or hex +- Test the variant on the actual fabric weight and color before committing +- Pick the variant of the mark that survives apparel embroidery (the symbol alone, the monogram, the simplified lockup) + +--- + +## Foil stamp on paper or leather + +Single-color metallic stamping. Business cards, letterhead, bound books, leather portfolios, signet rings, wax-seal-style stamps. The mark is impressed into the substrate with metallic foil. + +### Constraints + +- Single color (gold, silver, copper, black foil, etc.); no gradients +- Substantial line weight required (1mm+ minimum for gold or silver foil) +- No fine letterforms; thin serifs disappear under the foil impression +- The substrate matters (matte vs glossy paper, leather vs vellum); each renders differently +- The mark must read in metallic, not as a flat color + +### Failure modes + +- Thin letterforms disappear or look uneven under the foil +- Marks that depend on color contrast lose meaning in single-color metallic +- Heavy fills require more foil and may bleed at the edges +- Marks designed for screen rendering do not translate to the tactile, reflective surface of foil + +### Mitigation patterns + +- Design a foil-stamp variant with chunky stroke weights +- Specify foil color (PMS gold, silver, copper) and finish (matte vs glossy foil) +- Test the variant against the actual substrate (the brand's letterhead paper, the brand's leather portfolio cover) before committing +- Treat foil-stamp applications as a hierarchy decision: which mark goes here, given the constraints? + +--- + +## The discipline, restated + +Every variant under consideration must pass the application context test before it is a contender. The working checklist: + +1. **16px favicon.** Does the mark survive at smallest scale? +2. **28px app icon.** Does the mark work inside rounded-square or circle masks? +3. **1.5 inch embroidery patch.** Can the mark be embroidered with 4-6 colors and chunky strokes? +4. **Single-color reproduction.** Does the mark read in pure black on white? +5. **Reverse on dark.** Does the mark hold up inverted on a dark background? +6. **Large-format signage.** Does the mark survive scaling to 12 feet? +7. **Motion lockup.** Does the mark have a natural entry and exit animation? +8. **Social profile picture.** Does the mark work inside a circle mask at 80px? +9. **Apparel embroidery.** Does the mark survive thread on fabric? +10. **Foil stamp.** Does the mark survive single-color metallic impression? + +If a candidate fails three or more of these, it is not a primary mark. It might still serve as a secondary or display lockup, but it is not carrying the brand. The brand needs a fallback hierarchy: primary lockup, secondary monogram or symbol-only, tertiary letterform-as-symbol or simplified mark for the harshest applications. + +The hierarchy is the system. The system is what makes the brand readable across every context the audience encounters. diff --git a/skills/logo-design/references/architectures-explained.md b/skills/logo-design/references/architectures-explained.md new file mode 100644 index 0000000..4eac4c8 --- /dev/null +++ b/skills/logo-design/references/architectures-explained.md @@ -0,0 +1,165 @@ +# Mark architectures explained + +The architectural decision is the foundational one. Every other choice (typographic register, symbol approach, application context discipline) flows from it. This file expands the five architectures listed in [SKILL.md](../SKILL.md) with reference brands, fit and failure modes, and a working pattern for combining them in a primary-plus-fallback hierarchy. + +--- + +## Wordmark only + +The logo is the brand name set in a chosen typeface, possibly with custom letterform interventions. No standalone symbol. The wordmark IS the mark. Stripe, Google, Pinterest, FedEx, eBay, Coca-Cola, Visa. + +The discipline is letter-by-letter. Kerning is not optional. Optical adjustments matter at every weight. A wordmark earns its place when the brand name is distinctive enough that the type alone carries identity. Stripe's wordmark uses a single-character optical adjustment on the lowercase "r" that makes the word read as a unit; without it, the word fragments visually. FedEx hides an arrow in the negative space between the "E" and the "x", a famous earned detail that the brand's audience finds and remembers. Google's wordmark redrew its own custom geometric sans (Product Sans) so the brand owns the wordmark's specific letterforms. + +Wordmark-only works hardest at small sizes. The full wordmark fails at favicon scale almost universally. A wordmark-only brand still needs a fallback mark for 16px contexts, embroidery, and stacked square applications, even if that fallback never appears in the primary lockup hierarchy. + +### When this fits + +- The name is short (4 to 8 letters works best; 9 to 12 is the upper edge) +- The name has at least one distinguishing letter or letter combination +- The brand has high enough recognition that the wordmark alone signals identity +- The category rewards type-led restraint (editorial, financial, professional services) +- There is room and willingness to pay for custom letterform work + +### When this fails + +- The name is long (10+ letters) and the wordmark cannot fit common contexts +- The category demands instant visual recognition (consumer goods at shelf, app icons) +- The wordmark's letterforms are generic and the brand cannot afford custom drawing +- The brand has no fallback mark for square contexts, social profiles, embroidery +- The wordmark looks identical to many other brands' wordmarks in the same category + +### Combining in a hierarchy + +Wordmark-only as the primary requires a separate symbol-grade asset for square and small contexts. The most common production setup pairs a wordmark with a letterform-as-symbol fallback. Pinterest does this: the wordmark is the primary, the "P" inside a circle is the avatar mark. Stripe does this with a custom geometric "S" for the favicon. The fallback shares visual DNA with the wordmark (same weight class, same custom letterform language) so the system reads as one mark with two surfaces. + +--- + +## Lockup (wordmark plus symbol) + +A wordmark and a symbol locked into a fixed relationship. Slack, Airbnb, Asana, Spotify, MasterCard. This is the default architecture for most brands because it covers the widest range of application contexts with the fewest fallbacks. + +Lockups have variants. Symbol-left-of-wordmark is most common (left-to-right reading languages naturally pull the eye to the symbol first, then the wordmark). Symbol-above-wordmark works when the symbol is tall and narrow or when the lockup must fit a vertically constrained space. Symbol-right-of-wordmark is rare and usually reserved for editorial or signature treatments. Each lockup also tends to have a stacked alternate (symbol above wordmark, centered) for square contexts and an isolated symbol-only fallback for the smallest applications. + +The construction discipline is geometric. The symbol's optical weight should match the wordmark's stroke weight. The space between symbol and wordmark should be tied to the wordmark's x-height or cap height (e.g., the gap equals one x-height of the wordmark). Slack's lockup uses a tightly proportioned hash symbol whose stroke matches the wordmark's stroke at every weight, and the gap is sized to the wordmark's x-height. Without this geometric discipline, lockups fall apart at scale: stretched at large sizes, crowded at small ones. + +### When this fits + +- The brand needs a symbol-grade asset alongside the wordmark +- The wordmark alone is not distinctive enough at small sizes +- The category benefits from a symbol's ability to travel beyond text contexts (apps, signage, branded merchandise) +- The brand will deploy both the symbol and the lockup in different contexts +- The brand has the budget for two finished assets (symbol and wordmark) instead of one + +### When this fails + +- The lockup falls apart at small sizes because the symbol carries detail that disappears +- Symbol and wordmark visually compete (different weight class, different optical density) +- The lockup has no stacked alternate for square contexts +- The brand uses the lockup at favicon scale, where the symbol-only or letterform-as-symbol fallback should carry +- The symbol is too literal or too abstract for the wordmark's tonal register + +### Combining in a hierarchy + +The most common production hierarchy: lockup primary, symbol-only fallback for square and small contexts (social profile, app icon, favicon at 24-32px), letterform-as-symbol or monogram for embroidery and 16px favicon. Slack ships exactly this: the lockup for marketing surfaces, the hash symbol alone for app icons, a simplified hash for favicon and embroidery. The hierarchy is one identity expressed across three asset grades. + +--- + +## Symbol only + +The mark is a symbol with no accompanying wordmark in the primary asset. Apple, Twitter (the bird era and the X era), Target, Nike's swoosh, Mercedes-Benz, Mastercard's circles. This is the highest-recognition tier and is almost never available to new brands. + +Symbol-only as the primary mark requires brand recognition the audience already holds. Apple did not start as symbol-only; the original Apple logo was a Newton-under-an-apple-tree illustration with the word "Apple Computer Co." beside it. The bitten apple symbol earned its standalone status across decades of advertising, product placement, and cultural ubiquity. New brands that try to launch as symbol-only typically fail to break through the recognition barrier and end up adding their wordmark back into the primary lockup. + +The exception is brands launching with massive marketing budgets that can purchase recognition directly. Some legacy financial and luxury brands (Mercedes-Benz, Mastercard) achieved symbol-only status by spending decades and billions on awareness. New brands attempting the same path almost always fail. + +### When this fits + +- The brand has decades of recognition and the symbol carries the brand alone +- The brand is in a category where symbols travel further than wordmarks (sports apparel, automotive, luxury goods) +- The symbol is distinctive enough that no other brand uses anything similar +- The brand has secondary contexts (signage, packaging, apparel) where wordmark space is not available +- The brand can afford the multi-decade investment in recognition + +### When this fails + +- The brand is new and lacks the recognition required for symbol-only to read as the brand +- The symbol is generic (a hexagon, a triangle, a circle) and could belong to thousands of other brands +- The brand has not invested in recognition through advertising or distribution +- Symbol-only is chosen as the primary because the wordmark is too long, when the real solution is a different architecture entirely +- The category demands wordmark presence (B2B SaaS, professional services, anything where the brand name needs to register before the symbol does) + +### Combining in a hierarchy + +Symbol-only is rarely the only asset. Even Apple ships a wordmark for legal contexts, contractual documents, marketing surfaces where the wordmark adds clarity. The hierarchy for symbol-only-primary brands is: symbol primary, wordmark for legal and contextual surfaces, lockup for select marketing applications. The symbol carries; the wordmark plays a supporting role. + +--- + +## Letterform-as-symbol + +A single letter from the brand name (often the first) is treated as the symbol. The letter is custom-drawn or aggressively styled to read as both letter and visual element. Beats by Dre's "b", McDonald's "M", Underscore's "_", a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. + +The cleanest path to symbol when the full wordmark is too long for a tight lockup, when the name has a letter that lends itself to visual play, or when the brand wants the symbol and the wordmark to share construction. Beats's "b" inside a circle is the exact "b" weight and proportion as the rest of the wordmark; the symbol IS the same lettering language. McDonald's "M" reads as the golden arches and as the letter; both readings are simultaneous and reinforce each other. + +The discipline is the silhouette test on the underlying letter. If the letterform is over-styled and the silhouette no longer reads as the letter, the symbol fails one direction of its job. If the letterform is under-styled and reads as just a typed letter, the symbol fails the other direction. The custom letterform must do double duty. + +### When this fits + +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to read as one identity +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands +- The brand needs a small-size and embroidery-friendly fallback that derives from the wordmark + +### When this fails + +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it +- The brand uses the letterform-as-symbol at sizes where it is illegible + +### Combining in a hierarchy + +A common setup: lockup primary, letterform-as-symbol for square contexts and embroidery, full wordmark for legal and large-format contexts. Beats does this. The letterform-as-symbol is the favicon, the app icon, the embroidered patch on Beats apparel. The wordmark in lockup is the marketing primary. The hierarchy makes one identity across asset grades. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol is the initials, often with ligature treatment, tight kerning, geometric framing (ring, shield, diamond), or stacked composition. CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent). + +Common in legal, financial, hospitality, fashion, and heritage brands where institutional gravity is the positioning. A monogram says "we have a long name" and "we own the initials of that name". It also says "we are old enough that abbreviating is acceptable", which is a positioning move. + +Monograms come in three flavors. Pure ligature (the letters share strokes; CN and GG are ligatures). Stacked or geometrically framed (the letters sit inside a ring, shield, or diamond; HBO is framed; YSL is geometrically composed). Tight kerning with no framing (the letters are simply set together with optical adjustments; VW reads as initials without frame). + +### When this fits + +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit (M and N, C and N, V and W work; I and J or O and U are harder) +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +### When this fails + +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials +- The brand uses the monogram alone in contexts where the audience does not yet recognize the initials + +### Combining in a hierarchy + +The classic hierarchy is: full wordmark for marketing primary, monogram for square contexts (social profile, embroidery, foil stamp, signet, wax seal), lockup with both wordmark and monogram for transitional surfaces (letterhead, business card, signage). Chanel, Gucci, and most luxury houses ship exactly this. The monogram is the most-applied mark on physical goods (apparel, hardware, bottles), the wordmark is the most-applied mark on digital and marketing surfaces, and the lockup is reserved for specific institutional surfaces. + +--- + +## Putting it together: the three-asset working pattern + +For most brands, the working asset hierarchy is three marks: + +1. **Primary lockup** for marketing, web, packaging, signage. Wordmark plus symbol locked into a fixed relationship. +2. **Stacked or square alternate** for social profiles, app icons, square contexts. Same elements as the lockup but recomposed for square. +3. **Small-grade fallback** for favicon, embroidery, foil stamps. A single element (symbol-only, letterform-as-symbol, or monogram) that derives from the lockup. + +All three must share visual DNA. Same letterform language, same construction grid, same optical weight class. A brand whose three marks read as three different brands has a system problem, not a logo problem. The discipline is to design the small-grade fallback FIRST, before the lockup, so the constraints of the smallest application drive the construction of the largest. diff --git a/skills/logo-design/references/category-conventions.md b/skills/logo-design/references/category-conventions.md new file mode 100644 index 0000000..6533083 --- /dev/null +++ b/skills/logo-design/references/category-conventions.md @@ -0,0 +1,489 @@ +# Category conventions + +Every category has a default visual register the audience expects. Working inside the default signals competence; the brand reads as belonging. Working outside the default signals positioning; the brand reads as making a deliberate move. Both are legitimate. The trap is doing either by accident. + +This file surveys ten major brand categories at parity. For each: the defaults that work, the conventions worth honoring, the conventions worth breaking for positioning, the cliches to avoid, the application contexts unique to the category, and reference brands as visual shorthand. + +--- + +## 1. Legal firms + +The category is dominated by heritage positioning. White-shoe firms, century-old partnerships, names tied to founding partners' surnames. The audience reading the logo is general counsel, founders raising or selling, CFOs in industries where the wrong attorney is materially expensive. The buyer brings high stakes and trusts visual signals of institutional gravity. + +### Defaults that work + +- **Old-style or transitional serif typography** for the wordmark. Garamond, Caslon, Sabon, Source Serif. The serif reads as institutional and serious. +- **Lockup with monogram** OR **wordmark with monogram fallback**. The full firm name is often long (multiple partner surnames) so the monogram does heavy lifting in constrained contexts. +- **Restrained color palette.** Navy, deep charcoal, oxblood, deep forest green. No primary red, no bright blue, no anything that reads as casual. +- **Single-color reproduction** built into the system from day one (court filings reproduce in black on white, foil stamps on letterhead are common, embossed signage on lobby walls). + +### Conventions worth honoring + +- Heritage signaling through old-style serif type and monogram architecture +- Single-color reproducibility for court filings and formal documents +- Geometric framing (ring, shield) only in restrained executions; heavy ornament reads as fake heritage + +### Conventions worth breaking for positioning + +- Geometric sans for the wordmark signals "modern, accessible" (boutique firms, tech-adjacent practices, plaintiff-side firms) +- Lighter color palette signals approachability (firms competing for client comfort, not gravity) +- Asymmetric lockup signals contemporary execution (firms positioning against the traditional white-shoe model) + +### Common cliches to avoid + +- The Roman-pillar-as-justice. Pillars are exhausted. +- The scales-of-justice icon. Done thousands of times; signals nothing. +- The gavel. Cliche. +- The lady-Justice silhouette. Same. + +### Application contexts unique to the category + +- Court filings (single-color black on white at small scale) +- Embossed letterhead and business cards (the foil-stamp test is real) +- Lobby and conference room signage (engraved brass, etched glass) +- Email signatures with the firm wordmark and individual attorney name +- Billable-hours invoices (the wordmark must look reproducible at low quality) + +### Reference brands + +- **Latham & Watkins** (LW monogram in serif, conservative palette) +- **Wachtell, Lipton, Rosen & Katz** (full firm name as wordmark, no symbol; positioning as "we don't need a symbol") +- **Skadden, Arps, Slate, Meagher & Flom** (Skadden monogram, restrained sans) + +--- + +## 2. Consumer goods / CPG + +The category is dominated by retail competition. The mark must register at shelf distance (10 to 15 feet), at thumbnail scale (online product imagery), and at rapid scan speed (the shopper has 2 seconds per shelf section). Distinctiveness is survival. + +### Defaults that work + +- **Custom display typography** for the wordmark. The brand owns its letterforms because the wordmark is on every package. +- **Lockup with literal symbol** OR **strong wordmark only**. The symbol depicts what the brand is about; the wordmark carries the brand name. +- **Bold color palettes.** Bright colors register at distance. Restraint is the exception. +- **Pattern systems** that extend the brand identity onto packaging surfaces. + +### Conventions worth honoring + +- Distinctiveness at small scale (online product thumbnails, 80x80 pixels) +- Single-color or simplified versions for embossed packaging, foil stamps, hot-metal printing +- Color recognition: the brand color is the first signal on shelf, before the wordmark even reads + +### Conventions worth breaking for positioning + +- Restrained typography signals premium positioning (Method, Brandless, Aesop) +- Black-and-white-only signals minimalist or anti-CPG positioning +- Hand-drawn or organic letterforms signal craft or small-batch positioning + +### Common cliches to avoid + +- The swoosh-as-growth. Borrowed from Nike. +- The leaf-as-natural. Done thousands of times in wellness and organic. +- The dot-or-circle-as-modernity. The 2010s startup tier. +- The hand-drawn brushstroke under the wordmark. Saturated. + +### Application contexts unique to the category + +- Retail packaging at shelf scale +- Online product thumbnails (80x80 to 200x200 pixels) +- Print catalog imagery (offset print, sometimes single-color) +- In-store signage and end-cap displays +- Branded merchandise (hats, totes, t-shirts the brand sells) + +### Reference brands + +- **Method** (custom geometric sans, restrained palette, premium positioning in a category dominated by aggressive color) +- **Hu Chocolate** (hand-drawn wordmark, organic typography, craft positioning) +- **Brandless** (anti-brand brand: minimalist sans, monochrome, the wordmark IS the absence of conventional branding) + +--- + +## 3. B2B SaaS + +The category is dominated by visual interchangeability. Most B2B SaaS brands use neo-grotesque sans typography, geometric reduction symbols, and a primary color in the blue-to-purple range. The mark blurs into the category default unless the brand makes deliberate distinguishing choices. + +### Defaults that work + +- **Neo-grotesque sans typography** (Inter, Söhne, GT America, custom). The default register reads as competent and contemporary. +- **Lockup with abstract or geometric-reduction symbol**. The symbol carries small-size and app-icon contexts. +- **Single-accent color palette.** A primary brand color plus monochrome, no busy palette. +- **Custom letterform** in the wordmark to escape the interchangeable default. + +### Conventions worth honoring + +- Screen rendering optimization (the wordmark must read at every screen size and DPI) +- App icon construction (the symbol must work inside rounded-square and circle masks) +- Monochrome reproducibility (single-color and reverse-on-dark should both work) + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in SaaS; positions against the modern startup tier) +- Bright primary color (red, orange, yellow) signals energy in a category that defaults to blue and gray +- Custom display typography signals long-term brand investment in a category where most brands look interchangeable + +### Common cliches to avoid + +- The geometric hexagon. The most overused symbol in tech. +- The three-bars stacked horizontally. The 2018-2020 SaaS tier. +- The triangle pointing right. Done. +- The bisected circle. Same. +- The single-letter-inside-circle without distinctive letterform construction. + +### Application contexts unique to the category + +- App icons (iOS, Android, web app, browser extension) +- Marketing site at desktop scale +- Documentation site at small scale (favicon, header, footer) +- In-product brand display (loading screens, empty states, account avatars) +- Slack and email integration logos (small thumbnails) + +### Reference brands + +- **Stripe** (custom Sohne wordmark, abstract gesture symbol, restrained palette) +- **Linear** (Inter wordmark, geometric reduction symbol, signature single-color execution) +- **Vercel** (custom Geist wordmark, geometric reduction triangle, bold black-and-white) +- **Notion** (custom letterform with notebook reference) + +--- + +## 4. Hospitality (hotels, restaurants, resorts) + +The category sits between heritage luxury and contemporary craft. The audience experiences the brand across many surfaces simultaneously: building exteriors, interior signage, room key cards, menus, uniforms, towels, sheets, packaging. Multi-surface coherence is the discipline. + +### Defaults that work + +- **Custom display typography** OR **transitional serif** for the wordmark. The brand often becomes the visual identity of the property. +- **Lockup with monogram fallback**. The monogram appears on towels, sheets, room keys, embroidered uniforms. +- **Restrained palette** with a single signature color. The palette extends to interior design, materials, lighting. +- **Embroidery-grade variant** built into the system from day one. + +### Conventions worth honoring + +- Embroidery on uniforms, towels, robes, sheets (the monogram does this work) +- Foil-stamp on stationery, room key cards, room service menus +- Engraved or etched signage on building exteriors and interior wayfinding +- Restraint in palette (heritage hospitality avoids loud color) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "boutique, design-forward" (Ace Hotel, Standard Hotels) +- Bold color signals contemporary or playful positioning +- Asymmetric lockup signals contemporary execution +- Display custom typography signals investment in a unique brand identity + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in heritage hospitality. +- The shield-with-year-founded. Every craft beer label uses this. +- The crossed-keys (Hermes-derived). Done. +- The mountain-or-palm-tree literal symbol for resort properties. Done. + +### Application contexts unique to the category + +- Building exterior signage (channel letters, illuminated) +- Room key cards (foil stamp on plastic or paper) +- Towels, robes, sheets (embroidery) +- Glassware, china, silverware (etched, engraved) +- Stationery (letterhead, envelopes, business cards, foil stamp) +- Uniforms (embroidered name tags and lapel pins) +- Bag tags and luggage labels + +### Reference brands + +- **Aman Resorts** (restrained typographic identity, Asian-influenced design discipline) +- **Soho House** (custom display typography, monogram primary, modern member-club positioning) +- **Ace Hotel** (custom display typography, contemporary boutique positioning, regional variation across properties) + +--- + +## 5. Healthcare + +The category is dominated by trust signaling. The audience may be anxious, stressed, or grieving. The brand must read as competent and calm without reading as cold or clinical. Trust is built through restraint, not through aggressive visual claims. + +### Defaults that work + +- **Humanist sans typography** for the wordmark. The calligraphic warmth carries trust. +- **Lockup with abstract gesture symbol**. The symbol suggests care, balance, or healing without depicting it literally. +- **Calm color palette.** Blue, green, soft warm neutrals dominate. +- **Plenty of whitespace** in the brand system. Density reads as anxiety. + +### Conventions worth honoring + +- Accessibility floor: WCAG AA contrast ratios on every brand color combination +- Restrained palette: no aggressive red (reads as emergency or alarm) +- Avoid imagery that could be misread (a symbol that suggests a religious cross when the brand is secular, a symbol that suggests a specific medical specialty when the brand is generalist) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "tech-forward primary care" (One Medical, Forward) +- Warmer color palette (coral, peach, soft yellow) signals "we are not your old doctor's office" +- Custom display typography signals contemporary positioning (rare in legacy healthcare) + +### Common cliches to avoid + +- The medical cross. Trademark-protected by the Red Cross in some uses; otherwise generic. +- The caduceus (snakes around a staff). Misread by audiences as Hermes; not actually the medical symbol. +- The heartbeat-line. Saturated in fitness and healthcare. +- The blue-and-green gradient. The default healthcare palette to a fault. + +### Application contexts unique to the category + +- Wayfinding signage in clinics and hospitals +- Patient-facing materials (intake forms, appointment reminders, billing statements) +- Medical equipment branding (the wordmark on a screen, on a printed report) +- Insurance and billing communications (the wordmark on bills the patient hopes are accurate) +- Clinic uniforms and badges + +### Reference brands + +- **One Medical** (humanist sans wordmark, simplified circle symbol, restrained palette, primary care positioning) +- **Forward** (custom display typography, geometric reduction symbol, tech-forward primary care) +- **Hims** (custom geometric sans, single-color execution, modern men's health positioning) + +--- + +## 6. Financial services + +The category splits between heritage and fintech-modern. Heritage banks (Goldman Sachs, JPMorgan, Morgan Stanley) lean into old-style serif and institutional gravity. Fintech challengers (Ramp, Mercury, Stripe) lean into neo-grotesque sans and modern restraint. The split is itself a positioning decision. + +### Defaults that work + +- **Old-style serif** OR **neo-grotesque sans** (the heritage-vs-fintech axis) +- **Lockup with monogram fallback** (heritage) OR **wordmark with abstract symbol** (fintech) +- **Restrained palette.** Navy, gold, deep green for heritage. Black, white, single-accent for fintech. +- **Single-color reproducibility** built into the system (foil stamps, embossed checks, single-color regulatory documents) + +### Conventions worth honoring + +- Single-color reproducibility (foil stamps, regulatory filings, embossed checks) +- Trust signals through restraint and material quality (heavy paper, foil stamps) +- Color choice signals heritage (navy, gold, deep green) vs fintech (black, white, electric accent) + +### Conventions worth breaking for positioning + +- Modern geometric sans in heritage financial services signals "boutique, contemporary" (rare and high-stakes) +- Bright color in heritage financial services signals "we are not your father's bank" (high-risk positioning) +- Old-style serif in fintech signals "we take regulatory compliance seriously" (positions against fast-and-loose fintech) + +### Common cliches to avoid + +- The eagle-as-strength. Heritage cliche. +- The shield-as-security. Cliche across heritage and fintech. +- The bull-as-bullish. Wall Street cliche. +- The geometric chevron pointing up. Fintech cliche. +- The blue-and-gold gradient. Heritage default that reads as visually unconsidered. + +### Application contexts unique to the category + +- Embossed credit and debit cards (the mark is impressed, not printed) +- Regulatory filings and disclosures (single-color reproduction) +- Bank checks (single-color print, MICR-encoded routing numbers) +- Branch signage (channel letters, illuminated) +- ATM screens and branded interfaces + +### Reference brands + +- **Goldman Sachs** (old-style serif wordmark, restrained palette, heritage positioning) +- **Ramp** (custom Söhne wordmark, abstract symbol, modern restrained palette) +- **Mercury** (custom geometric sans, abstract gesture symbol, fintech positioning with restraint) + +--- + +## 7. Editorial / publishing + +The category is dominated by typography. The masthead IS the logo. Most editorial brands have no separate symbol; the wordmark in a specific custom serif IS the entire identity. The discipline is letterform and proportional refinement. + +### Defaults that work + +- **Custom display typography** OR **old-style serif** OR **transitional serif** for the wordmark +- **Wordmark only** OR **wordmark with monogram fallback** +- **Black-on-white** as the default reproduction (newsstand, print, digital header) +- **Restrained palette** (typically a single accent color, often the brand's signature) + +### Conventions worth honoring + +- Single-color reproducibility (every newspaper masthead must work in black on white at masthead scale) +- Custom letterform investment (the masthead is the brand's most-rendered asset) +- Typographic heritage (the masthead often references the publication's founding-era typography) + +### Conventions worth breaking for positioning + +- Geometric sans signals contemporary editorial (Vox, BuzzFeed, Vice attempted versions of this) +- Bold color signals contemporary positioning (rare in legacy editorial) +- Modern asymmetric layouts signal contemporary craft + +### Common cliches to avoid + +- The blackletter masthead. Saturated for newspapers; reads as German tabloid. +- The decorative initial cap drop. Editorial cliche. +- The pen-nib symbol for writing or journalism brands. Cliche. +- The book-and-ribbon. Cliche. + +### Application contexts unique to the category + +- Newsstand at street scale (the masthead must read at 50 to 100 feet) +- Print body and headline typography (the wordmark sits at the top of every printed page) +- Digital masthead at desktop and mobile scale +- Subscription and renewal direct mail (single-color print) +- Cover photography (the masthead overlays photographic backgrounds) + +### Reference brands + +- **The Atlantic** (custom transitional serif, restrained palette, editorial heritage) +- **The New Yorker** (custom Caslon-derived masthead, the mark is unmistakable) +- **Cereal** (custom display sans, considered minimalism, contemporary editorial) + +--- + +## 8. Tech / AI + +The category is dominated by abstract gesture and geometric reduction. Most AI and tech brands lean into one of two modes: either neo-grotesque sans with abstract gesture symbol (Anthropic's flower, OpenAI's geometric mark) or aggressive geometric reduction (every blockchain logo, every web3 brand). Visual fatigue in the category is real. + +### Defaults that work + +- **Neo-grotesque sans** OR **custom geometric sans** for the wordmark +- **Lockup with abstract gesture or geometric reduction symbol** +- **Single-accent color palette.** Often the brand's "signature color" plus monochrome. +- **Construction grid discipline** in the symbol + +### Conventions worth honoring + +- Screen rendering optimization (the brand lives on screens at every size) +- App icon construction (rounded-square and circle masks, every iOS/Android size) +- Monochrome and reverse-on-dark variants + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in tech, signals against the dominant aesthetic) +- Hand-drawn or organic letterforms signal craft or human-centered positioning +- Bright primary color signals energy in a sea of muted palettes + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain. The most overused symbol in crypto. +- The neural-network-circles symbol for AI brands. Done thousands of times. +- The brain-with-circuit-traces. Cliche. +- The triangle-with-an-eye. Cliche. +- The default purple gradient. The 2018-2022 tech tier. + +### Application contexts unique to the category + +- Developer documentation sites (the wordmark sits in dense technical contexts) +- API and CLI integrations (the brand appears in terminal output, error messages, log lines) +- Loading screens and empty states in product +- Open-source repository profile pictures +- Conference talk slide branding + +### Reference brands + +- **Anthropic** (custom display typography, abstract gesture symbol, restrained palette) +- **OpenAI** (custom geometric mark, simple wordmark, monochrome execution) +- **Hugging Face** (custom emoji-as-symbol, distinctive in a category that doesn't usually allow it) + +--- + +## 9. Outdoor / lifestyle / apparel + +The category sits at the intersection of illustration, heritage, and embroidery. Many outdoor brands use illustration-driven marks with hand-drawn or vintage-inspired execution. The application context is frequently embroidered (apparel, hats, packs) so the mark must survive thread on fabric. + +### Defaults that work + +- **Custom display typography** OR **slab serif** for the wordmark +- **Lockup with literal symbol** depicting the brand's outdoor world (mountain, river, tree, animal silhouette) +- **Heritage color palette.** Earth tones, warm reds, deep greens, cream-and-coffee +- **Embroidery-grade variant** built into the primary system + +### Conventions worth honoring + +- Embroidery on apparel, hats, and packs (the mark must survive 4-6 colors on thread) +- Patch-friendly construction for hats and uniforms +- Hand-drawn or vintage-inspired execution that signals craft and authenticity +- Color palette referencing the brand's outdoor environment + +### Conventions worth breaking for positioning + +- Modern geometric sans signals contemporary outdoor (Topo Designs, Outdoor Voices) +- Bright color signals younger or athletic positioning +- Wordmark-only signals premium or design-led positioning (rare) + +### Common cliches to avoid + +- The bear silhouette. Saturated for outdoor and lifestyle. +- The mountain peak with a sun rising. Done. +- The compass rose. Saturated for travel and outdoor. +- The Pacific-Northwest cabin aesthetic. Saturated since 2015. +- The tent silhouette. Cliche. + +### Application contexts unique to the category + +- Apparel embroidery (hats, polos, jackets, packs) +- Patch embroidery (jackets, packs, vests) +- Heat-transfer printing on technical fabrics +- Hangtags and care labels on apparel +- Retail signage at small specialty stores + +### Reference brands + +- **Patagonia** (custom display typography, Fitz Roy mountain silhouette, signature gradient palette) +- **REI** (custom slab serif wordmark, the wedge symbol, outdoor heritage positioning) +- **Filson** (custom slab serif, monogram and shield treatments, heritage workwear positioning) +- **Topo Designs** (custom display typography, contemporary outdoor positioning, designed in Colorado) + +--- + +## 10. Fashion / luxury + +The category is dominated by monogram and ligature conventions. Most heritage luxury brands use monograms (Chanel CN, Gucci GG, Yves Saint Laurent YSL, Louis Vuitton LV). Modern accessible-luxury brands lean toward custom display typography (The Row, Aimé Leon Dore, Jacquemus). The split is the positioning question. + +### Defaults that work + +- **Old-style serif** OR **custom display typography** OR **ligature monogram** for the primary mark +- **Lockup with monogram fallback** OR **wordmark with monogram on goods** +- **Restrained palette.** Black, white, gold, and the brand's signature accent +- **Embroidery-grade variant** for apparel and accessories + +### Conventions worth honoring + +- Embroidery on apparel and accessories (the monogram does this work) +- Foil stamp and emboss on packaging (the wordmark or monogram impressed in metallic foil) +- Material quality (heavy paper, leather, metallic foil) +- Restraint in palette and ornamentation + +### Conventions worth breaking for positioning + +- Modern geometric sans signals accessible-luxury (The Row, Aimé Leon Dore lean restrained-modern) +- Bright color signals contemporary or playful luxury (rare and risky) +- Hand-drawn or expressive letterforms signal craft positioning + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in fashion and hospitality. +- The decorative monogram with filigree. Reads as Renaissance Faire, not as Hermès. +- The shield-with-year-founded. Done. +- The gold-foil-with-Old-English-typeface. Cliche fake-heritage. + +### Application contexts unique to the category + +- Apparel embroidery (logos, monograms, signatures stitched into garments) +- Hardware embossing (buttons, rivets, zipper pulls, leather goods) +- Foil stamp on packaging (boxes, dust bags, ribbon) +- Engraved or etched hardware (jewelry, watches) +- Vellum and tissue paper printing (gift wrap, bag liners) +- Window displays at flagship stores + +### Reference brands + +- **Chanel** (CN monogram, no symbol beyond initials, the most institutionally consistent fashion brand) +- **Gucci** (GG monogram, custom display typography for the wordmark) +- **The Row** (custom display typography, restrained accessible-luxury positioning) +- **Aimé Leon Dore** (custom display typography, contemporary heritage positioning, restrained monogram on apparel) + +--- + +## How to use this file + +When designing for a category not your own, start with the defaults. They exist because they work. The audience reads them as competence. + +When designing for a category you want to position against, identify which convention you are breaking and why. The break should be deliberate and supported by the rest of the brand system. A boutique law firm in geometric sans signals modern positioning IF the rest of the brand (color, photography, voice, materials) also signals modern positioning. Breaking type without breaking the rest of the system reads as random. + +When designing without category context, the defaults are still the right starting point. Most brands sit inside a category. Most brands benefit from being recognizable inside that category before they push for distinctiveness. Distinctiveness without belonging reads as outsider; belonging without distinctiveness reads as forgettable. The discipline is to start with the category default and earn each departure. diff --git a/skills/logo-design/references/client-package.md b/skills/logo-design/references/client-package.md new file mode 100644 index 0000000..e41adf0 --- /dev/null +++ b/skills/logo-design/references/client-package.md @@ -0,0 +1,187 @@ +# Logo client package + +The package format clients expect when handing logo work back. The discipline here is doing the boring work upfront so the client never has to ask for "the SVG version" or "a small one for favicons" or "white-on-dark for the slide deck." + +## When this applies + +- Final delivery of logo work to a client (internal or external) +- Mid-project handoff where another team needs to start building against the mark +- Brand-refresh deliverables where existing applications need to update + +## When this does NOT apply + +- Concept presentation. Concept stage is for direction-setting, not delivery. Concept decks include 2-3 mark variations with rationale, not a full package. +- Style-guide level brand systems. The client package is the deliverable for the mark itself; a brand-style-guide is a separate concern covering color, type, voice, photography, motion. See the brand-style-guide skill. +- Individual application-specific exports. If the client needs a 2400x1260 LinkedIn cover image with the mark composed against a photo, that is a one-off design request, not a package update. + +## The package format + +### File formats (the matrix) + +Every variant ships in formats that cover the contexts the client will actually use: + +| Format | Use case | Notes | +|---|---|---| +| SVG | Web, scalable applications, modern email clients | Primary delivery format. Vector. | +| AI or EPS | Editable source for designers | Source file. Layered if the mark has multiple components. | +| PDF | Print, vector applications, archival | Vector. Embedded fonts or outlined. | +| PNG (transparent) | Web, slide decks, raster contexts where background is unknown | Multiple sizes: 64, 128, 256, 512, 1024, 2048. | +| JPG | Email signatures, contexts where transparency is not supported | Solid background; usually white. Single size, 1024px wide. | +| ICO | Favicon | Multi-resolution: 16x16, 32x32, 48x48 packed into one file. | +| Apple touch icon (PNG) | iOS home-screen bookmarks | Single size, 180x180. | + +The asymmetry matters. Vector formats (SVG, AI, PDF) are the source of truth; raster formats (PNG, JPG, ICO) are derived from the vector source at delivery time. Never deliver only raster; clients eventually need to scale up and they cannot. + +### Variant matrix + +The client gets every meaningful combination of the variant axes: + +**Color treatment:** +- Primary (full color, the canonical mark) +- Reverse (white on dark, for dark backgrounds) +- Mono black (single black, for grayscale or low-fidelity contexts) +- Mono white (single white, for full-bleed dark photography) +- Mono brand (single color in the brand color, for one-color print) + +**Composition (where the mark has multiple lockups):** +- Primary lockup (the canonical composition, usually horizontal) +- Stacked (vertical, for narrow contexts like favicons or app tiles) +- Symbol-only (when the wordmark is unavailable or unnecessary, like profile avatars) +- With tagline (where a tagline is part of the mark system) +- Without tagline + +The client gets every relevant combination. A simple wordmark might have 5 variants total (primary across 5 color treatments). A complex lockup with tagline plus symbol variants might have 30+. Either way: the matrix is exhaustive within the system, not arbitrary. + +### Folder structure + +Organized so the client can find what they need without thinking: + +``` +{brand-name}-logo-package/ +├── 01-primary/ +│ ├── primary-color.svg +│ ├── primary-color.ai +│ ├── primary-color.pdf +│ ├── primary-color-2048.png +│ ├── primary-color-1024.png +│ ├── primary-color-512.png +│ ├── primary-color-256.png +│ ├── primary-color-128.png +│ ├── primary-color-64.png +│ └── primary-color.jpg +├── 02-reverse/ +│ └── (same format set, white-on-dark) +├── 03-mono/ +│ ├── mono-black/ (full set) +│ ├── mono-white/ (full set) +│ └── mono-brand/ (full set) +├── 04-stacked/ +│ └── (same format set, vertical lockup) +├── 05-symbol/ +│ └── (symbol-only variants if applicable) +├── 06-favicon/ +│ ├── favicon.ico +│ ├── apple-touch-icon.png +│ ├── favicon-16.png +│ ├── favicon-32.png +│ └── favicon-48.png +├── 07-applications/ +│ ├── business-card-mockup.pdf +│ ├── letterhead-mockup.pdf +│ ├── email-signature.png +│ └── social-avatar.png +├── 08-documentation/ +│ ├── usage-guide.pdf +│ ├── brand-colors.pdf +│ └── license.pdf +└── README.md +``` + +Numbered prefixes ensure the client opens folders in the order that matches how they will use them. Documentation last because nobody reads it first; applications second-to-last because they are reference, not deliverable. + +### File naming convention + +Inside each folder, files follow this pattern: + +``` +{variant}-{color}-{size or context}.{ext} +``` + +Examples: +- `primary-color.svg` +- `primary-color-2048.png` +- `reverse-white.svg` +- `mono-black-1024.png` +- `stacked-color.pdf` +- `symbol-color.svg` + +Consistent naming means the client can guess a filename before looking. + +## The documentation layer + +Inside `08-documentation/`: + +### usage-guide.pdf + +Covers: +- **Clear space**: minimum padding around the mark, expressed as a multiple of a recurring element (often the x-height of the wordmark or the diameter of the symbol) +- **Minimum size**: smallest legible application, with explicit size for digital (px) and print (mm or in) +- **Do's**: contexts where the mark works +- **Don'ts**: stretching, recoloring outside the variant set, rotating, applying effects (drop shadow, gradient, embossed), placing on busy photography without sufficient contrast, replacing the typography in a wordmark +- **Co-branding rules**: how the mark composes with partner marks, including spacing and order + +A usage guide that just lists the variants is documentation theater. The do's-and-don'ts section is what protects the mark in the wild. + +### brand-colors.pdf + +Color values for every meaningful representation: +- Hex (web) +- RGB (digital) +- CMYK (print) +- Pantone (spot color print) +- HSL (where the brand has a programmatic color system) + +If the mark uses gradients, document the gradient stops and direction explicitly. Gradients vary in unpredictable ways across rendering engines; precise documentation is the only protection. + +### license.pdf + +Covers: +- Who owns the mark (usually the client) +- Who the designer is (for attribution, if required) +- Usage terms (typically: client has full and exclusive use; designer retains the right to display in portfolios) +- Modification rights (typically: client cannot modify without designer consent during a defined warranty period; after that, all rights to modify pass to the client) +- Successor terms (what happens if the client sells the brand or merges with another company) + +License documentation is the part most independent designers skip and most agencies overformat. The middle path is a 1-page document that names the parties, defines usage, and is signed. + +## Delivery mechanisms + +Three patterns, in increasing formality: + +**ZIP archive over email.** Smallest projects. The client gets a single `.zip`, downloads, expands, drops into their workspace. Works for packages under ~50 MB. Watch out for email size limits. + +**Cloud storage link.** Most common pattern. Drive, Dropbox, Box, OneDrive. Client gets a link, downloads at leisure, can re-share within their organization. Set link to view-only with download enabled. Set an expiration date if warranty terms are time-bound. + +**Brand portal.** Largest projects. Paid tools like Frontify, Brandfolder, Brandkit. The portal becomes the canonical source of truth; the client gets logins for stakeholders. Worth the cost when there are 10+ internal stakeholders downloading assets ad hoc, or when the brand system has dozens of marks (parent plus sub-brands). + +Match the mechanism to the client's actual workflow, not their stated preference. Clients will say they want a brand portal, then download the ZIP and never log in to the portal again. + +## Failure patterns + +**Delivering only raster.** PNG-only or JPG-only packages mean the client cannot scale up cleanly. Always include vector. If the work was done in raster (rare for logo work, but it happens), trace to vector before delivery. + +**Delivering only the primary variant.** A primary-mark-only package fails the moment the client needs to put the mark on a dark background or print it in one color. The variant matrix is the deliverable, not an optional extra. + +**Delivering source files without a license document.** Clients who paid for the work expect to own it. Source files (AI/EPS) without an explicit license create ambiguity that surfaces during acquisitions or partnerships. Always include the license PDF. + +**Variant naming drift across the package.** `Primary_Logo_Color.svg` in one folder and `primary-color.svg` in another means the client's tooling (CMS, design system) will not recognize the assets consistently. Pick a convention; apply it everywhere. + +**Skipping the favicon.** Almost every client will host a website. The website needs a favicon. Adding the favicon variant adds one folder; omitting it means the client comes back asking for it. + +**Embedding fonts in the SVG without confirming licensing.** SVG with embedded font glyphs is fine when the font is open-source. When the font is licensed (e.g., a Monotype or Adobe Fonts file), embedding the glyphs may violate the license. Outline the font in the SVG before delivery; the visual remains identical, and the licensing risk disappears. + +## What "done" looks like + +The client opens the ZIP (or the cloud link), sees a numbered folder structure, opens `01-primary/primary-color.svg`, and ships the mark to production within 5 minutes. + +If the client emails back asking "do you have a white version?" or "is there an SVG?" or "can you send the favicon?", the package was incomplete. diff --git a/skills/logo-design/references/example-variant-spec.md b/skills/logo-design/references/example-variant-spec.md new file mode 100644 index 0000000..111b6b2 --- /dev/null +++ b/skills/logo-design/references/example-variant-spec.md @@ -0,0 +1,100 @@ +# Example variant spec + +A fully populated single-variant spec for a fictitious brand, **Atlas Coffee**. Atlas is a hypothetical specialty coffee company sourcing single-origin beans from Latin American producers, roasting in small batches, retailing through a single flagship cafe and an online subscription. The brand brief calls for considered craft positioning, outdoor adjacency without literal outdoor imagery, warmth without rusticity. + +This file shows what one variant looks like when documented for client review. A complete deliverable contains 6 to 12 such variants. The agent uses this format as the per-variant template; the client uses it to evaluate, compare, and select. + +--- + +## Variant 07, Mountain peak A lockup, IBM Plex Sans + +### Architecture + +Lockup. The wordmark sits to the right of a custom letterform-as-symbol "A". The "A" reads as both the first letter of "Atlas" and as a stylized mountain peak. The lockup also has a stacked alternate (the "A" centered above the wordmark) for square contexts and a symbol-only fallback (the "A" alone) for favicon, embroidery, and stamping. + +### Typography + +- **Wordmark typeface.** IBM Plex Sans, Medium weight (500), tracking +5 (10 units, on a 1000-unit em). +- **Custom letterform.** The "A" is a custom drawing, not IBM Plex Sans. The crossbar is replaced with a single horizontal stroke at 38 percent height; the apex rises to a sharp peak; the legs are slightly splayed (8 degrees from vertical) to suggest mountain base width without exaggeration. The custom "A" replaces the typed "A" in the wordmark "Atlas Coffee" so the entire wordmark reads as a unit. +- **Wordmark composition.** "Atlas Coffee" set as one word, with a small visual gap between "Atlas" and "Coffee" (one half x-height of additional spacing) so the eye reads both words as parallel parts of the same name without forcing a hyphen or stacked composition. +- **Optical adjustments.** The "t" of "Atlas" is shortened by 4 units to balance against the rising "A" to its left. The "f" of "Coffee" has its terminal pulled inward by 3 units to prevent it from reading as an extra bar. + +### Symbol description + +The custom "A" is the symbol. The construction is built on a 4-unit grid: + +- Apex height: 4 units, sharp peak +- Crossbar: at 1.5 unit height, single horizontal stroke +- Leg width at base: 4 units, splayed 8 degrees from vertical +- Stroke weight: matches the wordmark's stroke weight at the chosen Medium weight (approximately 90 units on a 1000-unit em) + +The peak silhouette is ungenerous on the apex (sharp, not rounded). The crossbar is single-stroke (no double bars). The legs end with a flat foot, not a serif. At every scale, the silhouette reads first as a peak, then as the letter A. The double-reading test passes. + +### Color tokens + +- **Primary.** Warm charcoal `#2A2521`. The wordmark and the "A" symbol both use this color in standard reproduction. +- **Accent.** Rust `#B85C38`. The accent appears in marketing surfaces (web header backgrounds, packaging trim) but not in the lockup itself. +- **Single-color black.** `#000000`. For court filings is irrelevant; for embossed letterhead, foil stamp on paper, single-color print, fax (yes, still). The mark renders as pure black on white. +- **Single-color white.** `#FFFFFF`. For reverse-on-dark applications (web header in dark mode, signage at night, embossed on dark leather). +- **Reverse-on-dark variant.** White on a dark background; the symbol's negative space inversion is direction-neutral so the mark reads identically in either direction. + +### Application notes + +The variant excels at: +- Large-format signage. The peak silhouette reads at street scale; the wordmark holds at 8 to 12 feet wide. +- Retail packaging. The lockup at coffee bag scale (4 inches wide) is the natural size; the symbol carries the front, the wordmark anchors the side. +- Mug and ceramic stamping. The lockup with stacked alternate works on cylindrical surfaces. +- Embossed letterhead. The custom "A" embossed at the top, the wordmark printed below in standard color. +- Web header at desktop scale (200 to 400 pixels wide). The lockup reads cleanly at this size. + +The variant needs fallbacks at: +- 16 px favicon. The full lockup fails; the symbol-only "A" carries. +- 1.5 inch embroidery patch. The lockup is too wide; the symbol-only "A" with the wordmark stacked below in a chunky weight (e.g., IBM Plex Sans Bold) is the patch variant. +- App icon at 28 to 60 pixels. The symbol-only "A" inside a colored field (warm charcoal background, white "A") is the app icon variant. +- Square social profile. The stacked alternate (the "A" above the wordmark, centered) is the social profile variant. + +Embroidery adaptation: thread color matched to the warm charcoal primary (Madeira Polyneon `1842` is the closest match for the primary, with `1338` for the rust accent). The embroidery-grade variant of the symbol-only "A" requires a 3 unit minimum stroke weight scaled for 1.5 inch patch reproduction. + +### Signals + +- **Considered craft.** The wordmark's optical adjustments (shortened "t", pulled-in "f") signal that the brand has thought about every letterform, which signals that the brand thinks about every other detail. +- **Outdoor / adventure adjacency without literal outdoor imagery.** The mountain peak silhouette references outdoor without depicting a trail, a tree, or a campsite. The audience associates the brand with adventure-adjacent positioning without the brand becoming a Pacific-Northwest cliche. +- **Warmth without rusticity.** The warm charcoal primary and rust accent read as warm but considered. The palette avoids the heritage-coffee browns and the third-wave-minimalist whites; the in-between space signals contemporary craft. +- **Single-origin discipline.** The restrained execution (one symbol, one wordmark, one accent color) signals that the brand chooses few things deliberately. The same discipline appears in single-origin coffee sourcing. + +### Rejects + +- **Not a typical coffee shop laurel mark.** Atlas does not use a laurel wreath, a coffee bean, a coffee cup, or any direct depiction of coffee. The brand is about the experience and origin, not the commodity. +- **Not a third-wave-minimalist wordmark with no symbol.** Many specialty coffee brands have moved toward wordmark-only with no symbol. Atlas chooses a lockup because the brand wants a symbol-grade asset for embroidery, hardware stamping, and merchandise. +- **Not a literal coffee bean.** No bean, no berry, no plant in the symbol. The category cliche is rejected. +- **Not a Pacific-Northwest-cabin aesthetic.** No tree silhouette, no compass rose, no flannel-pattern background. The brand's outdoor adjacency is structural (peak silhouette in the letter), not stylistic. + +### Mockups + +The mockups would be rendered as image assets in a complete deliverable. Described in prose: + +1. **Storefront signage at street scale.** The lockup as channel letters above the cafe entrance, illuminated, mounted on stained wood paneling. The peak silhouette reads from across the street; the wordmark anchors the brand name as visitors approach. + +2. **Retail bag at shelf scale.** The 12 oz coffee bag with the lockup printed at 4 inches wide on the front, the wordmark-only with origin information on the side panel. The symbol's peak references the high-altitude growing regions where Atlas sources beans. + +3. **Espresso cup at table scale.** Double-walled glass cup with the symbol-only "A" stamped in warm charcoal at 1 inch tall on the cup wall. The lockup is on the saucer rim. The customer sees both marks during a 4-minute espresso experience. + +4. **Embroidered apron.** Black cotton apron with the symbol-only "A" embroidered in rust on the chest pocket. The wordmark is embroidered on the back at the lower hem, in warm charcoal thread, smaller scale. The aprons are durable goods that get washed weekly; the embroidery is built for that. + +5. **Social profile picture as stacked mark.** The stacked alternate (the "A" above the wordmark, centered, white on warm charcoal background) renders cleanly inside Twitter/Instagram circle masks at 80 to 400 pixel display sizes. + +--- + +## Notes for the agent reading this file + +This single-variant spec is one of typically 6 to 12 in a complete deliverable. The brand owner reads through all variants, marks preferences, asks questions, and selects 1 to 3 finalists for production refinement. + +The discipline in writing the spec: + +- **Be specific.** "IBM Plex Sans Medium with tracking +5" is specific. "Modern sans-serif" is not. +- **Show the system.** Each variant is a primary mark plus its fallbacks. Document the fallback hierarchy, not just the primary. +- **Justify with signals and rejects.** What does the variant communicate? What does it explicitly NOT communicate? The negative space in the rejects sharpens the positive selection. +- **Render mockups, in image or in prose.** The brand owner needs to see the mark in context to evaluate. A spec without mockups is half-finished. +- **Prepare for production.** The color tokens, embroidery thread color matches, foil stamp specifications, and minimum sizes are production information. The spec is the bridge from decision to manufacture. + +The output of this skill is decision material. The next step after delivery is selection. The step after that is production refinement on the chosen direction: cleaner construction, refined kerning, color system finalization, application library. diff --git a/skills/logo-design/references/symbol-approaches.md b/skills/logo-design/references/symbol-approaches.md new file mode 100644 index 0000000..a0a1027 --- /dev/null +++ b/skills/logo-design/references/symbol-approaches.md @@ -0,0 +1,266 @@ +# Symbol approaches + +A symbol is the part of the logo that does the most work outside of literacy. It travels where wordmarks cannot fit (favicon, embroidery, app icon, signet) and where wordmarks would not register (signage at distance, motion lockups, square contexts). The symbol approach is the question of WHAT KIND of symbol the brand needs. This file expands the five approaches in [SKILL.md](../SKILL.md) with reference brands, pattern vocabulary, decision criteria, and the cliches each approach has to escape. + +--- + +## Literal + +The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. A bicycle for a bicycle maker. A dog silhouette for a dog food brand. The mark and the meaning are tied together: see the mark, name the thing, recall the brand. + +Literal symbols deliver fast recognition and low ambiguity. The audience does not have to learn what the symbol means. They have to learn that THIS specific peak, rocket, leaf, or bird is THIS specific brand. That is a smaller cognitive load than abstract or geometric-reduction approaches require, which is why literal symbols often work for new brands without large marketing budgets. + +The risk is cliche. Every coffee shop has used a coffee bean. Every sustainable brand has used a leaf. Every fitness brand has used a flexed arm. Generic literal symbols disappear into the category background. The save is distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. Patagonia's mountain peaks (the Fitz Roy silhouette) are literal but read as Patagonia because no other outdoor brand uses that specific silhouette in that specific gradient. The execution carries the distinctiveness; the symbol approach is just the starting point. + +### Reference examples + +- **Apple's apple** (literal but with the bite, which is the distinctive execution) +- **Patagonia's Fitz Roy mountain silhouette** (literal landscape, specific peak) +- **Twitter's bird era** (literal bird, specific Larry-the-bird construction) +- **Shell's shell** (literal scallop shell, custom construction now near-symbol-only) +- **Burger King's burger** (literal but stylized; the bun, patty, and bun stack render as a unit) + +### Pattern vocabulary + +- Single-object silhouettes (peak, rocket, leaf, bird, fish, tree, building) +- Stylized object reductions (the apple bite, the burger as stacked rectangle, the shell as fan) +- Object-plus-frame compositions (the mountain inside a circle, the tree inside a shield) +- Repeated-object patterns (multiple stylized peaks, paired forms) +- Object combined with letterform (the mountain silhouette that doubles as a letter, see Letterform-derived approach below) + +### Decision criteria + +Literal symbols fit when: +- The brand name is descriptive (Atlas, Forge, Pulse, Anchor) and depicting the thing the name refers to is a natural move +- The category benefits from fast recognition (consumer goods at shelf, retail signage at street scale) +- The brand wants to feel approachable rather than abstract or institutional +- The audience reads symbols faster than they read wordmarks (younger audiences, retail audiences, audiences in low-literacy contexts) + +Literal symbols fail when: +- The brand name is abstract (Stripe, Anthropic, Linear) and forcing a literal symbol creates a metaphor the name does not invite +- The category has been saturated with literal symbols (every wellness brand using a leaf) +- The literal symbol cliches the category (every blockchain logo using a literal chain) +- The brand needs to feel institutional or premium and the literal depiction reads as childlike + +### Common cliches to avoid + +- **The leaf-as-natural** for any sustainability, wellness, or organic brand. The leaf is exhausted. +- **The swoosh-as-growth** for any growth-stage brand. Borrowed from Nike but watered down. +- **The mountain-as-aspiration** for any wellness or productivity brand. The mountain has been climbed. +- **The bullseye-as-precision** for any analytics or targeting brand. Done. +- **The shield-as-security** for any security or finance brand. Shields are everywhere. + +The escape is specific execution. A brand that uses a leaf must draw a specific leaf with specific construction (the maple leaf with eight points, drawn at this specific angle, with this specific stroke weight) so the audience reads "this leaf" not "a leaf". + +--- + +## Abstract gesture + +The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity" or "cycle". A spiral for "expansion". The symbol does not show the thing the brand does; it shows the quality the brand wants to be associated with. + +Abstract gesture marks read slower than literal marks but distinctively higher. The audience cannot name the thing in the symbol because there is no specific thing. Instead, the audience associates the symbol with the brand through repetition: see the symbol, recall the brand. Once associated, abstract gesture marks deliver more brand-specific recognition than literal marks because no other brand can use the same specific gesture. + +The risk is arbitrariness. A swoosh that suggests motion is fine. A swoosh that suggests motion AND innovation AND momentum AND speed is over-loaded. Abstract gesture marks work when the gesture is single, clear, and consistent. They fail when the gesture is multi-layered, when the symbol's construction does not visibly support the claimed gesture, or when the gesture is too abstract to register as anything at all. + +### Reference examples + +- **Nike's swoosh** (abstract gesture for motion, originally inspired by the wing of Nike, the Greek goddess of victory) +- **Mastercard's circles** (two overlapping circles, abstract gesture for connection or transaction) +- **Audi's four rings** (abstract gesture for the four merged companies, rendered geometrically) +- **Adidas's three stripes** (abstract gesture for ascension, originally a sports performance reference) +- **The PBS logo** (multiple human silhouettes implying community) + +### Pattern vocabulary + +- Arcs and curves (rising arc, descending arc, S-curve, spiral) +- Repeated forms (multiple stripes, multiple circles, multiple bars) +- Opposing forms (two halves meeting, mirrored shapes, yin-yang variants) +- Implied motion (lines that read as flow, shapes that suggest movement) +- Geometric primitives at scale (a single triangle, a single square, a single hexagon used as the gesture) + +### Decision criteria + +Abstract gesture fits when: +- The brand name is abstract and a literal symbol would feel forced +- The brand wants to claim a quality (motion, balance, growth, connection) without depicting it +- The category rewards distinctiveness over fast recognition (B2B, professional services, established mature brands) +- The brand has the recognition runway to teach the audience that this gesture means this brand + +Abstract gesture fails when: +- The brand is new and does not have the recognition to associate the gesture with the brand +- The gesture is borrowed from a saturated visual vocabulary (every fintech using a rising arc) +- The construction does not support the claim (a swoosh that does not actually swoop) +- The gesture is over-complicated and the audience cannot extract a single quality from it + +### Common cliches to avoid + +- **The swoosh-as-growth** for SaaS, fintech, or productivity brands. Swooshes are saturated. +- **The geometric-hexagon-as-blockchain** for crypto, web3, or distributed systems. Hexagons are the new dot-com blue. +- **The three-bars-as-tech-startup** for SaaS or developer tools. Three bars (or two, or four) are the most common geometric reduction in tech and now read as generic. +- **The infinity-as-continuous** for any "always-on" brand. Infinity loops are exhausted. +- **The ascending-arc-as-progress** for any analytics, growth, or financial services brand. Ascending arcs are the visual language of every dashboard ever. + +The escape is specific construction. A brand that uses a swoosh must draw a specific swoosh with specific weight, angle, and proportion so the gesture is identifiable as the brand's, not as a category default. + +--- + +## Geometric reduction + +The symbol is a formal abstraction with no specific referent. A hexagon. A triangle. A stack of horizontal lines. A circle bisected by a vertical. A square with a corner removed. The symbol is constructed from primitive geometric shapes with no narrative meaning attached. + +Geometric reduction reads modern and confident. The discipline of pure geometry signals "we made deliberate constructive choices". The risk is identical-to-everyone: thousands of brands use hexagons, triangles, circles, and squares. The reduction is so far from a specific narrative that the audience cannot distinguish one brand's geometric reduction from another's. + +The save is specific proportions, considered execution, and pairing with a distinctive wordmark. Microsoft's four-square mark is geometric reduction (four colored squares in a 2x2 grid) but works because the specific proportions, colors, and four-pane reference are unmistakably Microsoft. Pinterest's "P" inside a circle is geometric reduction but works because the specific letterform, the specific circle proportions, and the cultural recognition are Pinterest. Geometric reduction without distinctiveness in proportions or pairing reads as interchangeable. + +### Reference examples + +- **Microsoft's four-square** (four colored squares, the geometric reduction works because of color and arrangement) +- **Adidas's three stripes (geometric reduction reading)** (also abstract gesture, depending on read; the geometric reduction reading is three parallel diagonals) +- **Mastercard's two circles** (two overlapping geometric primitives) +- **Audi's four rings** (four overlapping circles) +- **Various B2B SaaS marks** (Linear's stacked horizontal bars, Slab's geometric construction) + +### Pattern vocabulary + +- Polygons (hexagon, octagon, triangle, square, diamond) +- Primitive intersections (overlapping circles, intersecting squares) +- Linear primitives (stacked bars, parallel lines, grids) +- Single primitives at scale (a single hexagon, a single triangle, a single square as the entire mark) +- Negative-space primitives (a hexagon defined by what surrounds it, a triangle defined by negative space) + +### Decision criteria + +Geometric reduction fits when: +- The brand has a budget for distinctive construction (the proportions and pairing must be specific enough to escape the category default) +- The brand wants to feel modern, technical, infrastructural +- The category rewards reduction over expression (B2B SaaS, infrastructure, fintech, distributed systems) +- The wordmark is distinctive enough that the geometric symbol can be quietly supportive rather than narratively loaded + +Geometric reduction fails when: +- The brand is new and the construction is generic +- The geometric primitive is the most common one in the category (every blockchain logo using a hexagon) +- The reduction is too far from any narrative the brand wants to tell +- The geometric symbol is not paired with a distinctive wordmark and the system reads as interchangeable + +### Common cliches to avoid + +- **The geometric hexagon-as-blockchain** for any crypto, web3, or distributed systems brand. Hexagons are the most overused geometric primitive in tech. +- **The triangle-as-direction** for any productivity, navigation, or strategy brand. Triangles point everywhere now. +- **The square-as-foundation** for any platform or infrastructure brand. Squares are the new shipping container. +- **The stacked-three-bars-as-tech-startup** for any SaaS brand. The three bars (or four) are the new dot-com gradient. +- **The bisected-circle-as-balance** for any wellness, productivity, or balance-claiming brand. Done. + +The escape is proportional specificity. A brand that uses a hexagon must use specific proportions (the regular hexagon vs the wide hexagon vs the tall hexagon, drawn at this specific angle, with this specific stroke or fill discipline) and pair it with a specific wordmark so the symbol is identifiable as the brand's specific reduction, not as a category default. + +--- + +## Letterform-derived + +The symbol is built from the name's letterforms. A custom letter, often the first, that doubles as a visual element. The "M" of McDonald's that reads as the golden arches and as a letter. The "b" of Beats inside a circle that reads as both a "b" and a stylized headphone. A custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. The Underscore brand's "_" that IS the symbol. + +Letterform-derived symbols deliver strong wordmark-symbol coherence. The wordmark and the symbol share construction language because they ARE the same construction language. The risk is that the letterform reads as just-a-typed-letter and adds nothing. The save is exaggerated character: the letter must read as both the letter AND the visual metaphor simultaneously. + +The discipline is the silhouette test on the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. The double-reading is what separates letterform-derived from wordmark-only or from literal symbols. + +### Reference examples + +- **McDonald's "M"** (the golden arches read as a letter and as the architectural arches of the original restaurant signage) +- **Beats by Dre's "b"** (the lowercase "b" inside a circle reads as a "b" and as a stylized headphone) +- **Underscore's "_"** (the underscore character IS the brand mark, read as a punctuation mark and as a structural element) +- **The Hoover Dam's "H"** (architectural lettering on signage that doubles as monumental ornament) + +### Pattern vocabulary + +- First-letter exaggeration (a custom "A", "B", "M", "S" that reads as both letter and shape) +- Letter-inside-frame (a letter inside a circle, square, or shield that reads as identity) +- Punctuation-as-symbol (an underscore, an asterisk, an ampersand used as the entire mark) +- Letter-as-object (a letter drawn so it doubles as a recognizable object: the M as arches, the A as a peak) +- Stacked or overlapping letterforms (one letter rendered on top of another, ligature-style) + +### Decision criteria + +Letterform-derived fits when: +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to share construction +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands + +Letterform-derived fails when: +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it + +### Common cliches to avoid + +- **The "letter inside circle"** as the universal letterform-derived solution. Beats works because the specific b-shape and the specific circle proportion are distinctive; copies of "letter inside circle" in B2B SaaS read as generic. +- **The "letter with an angled corner"** as a cheap attempt at distinctiveness. The angled corner does not read as a metaphor; it reads as decoration. +- **The "letter with extreme styling"** that no longer reads as the letter. If the styling is so heavy that the letterform fails the silhouette test, the metaphor is not earning its place. + +The escape is specific letterform decisions that produce a double reading. The "A as mountain peak" must work both ways. The "M as arches" must work both ways. The double reading is the only thing that justifies the custom drawing investment. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent), AOL. + +Monograms come in three flavors: +- **Pure ligature.** The letters share strokes; the two letters are drawn as one shape. CN and GG are ligatures. +- **Geometrically framed.** The letters sit inside a ring, shield, or diamond. HBO, with its rectangular framing. YSL, with its stacked geometric composition. +- **Tight kerning, no framing.** The letters are simply set together with optical adjustments and read as a unit. VW, with its overlapping V and W. AOL, set tight. + +Monograms signal institutional gravity. The audience reads "we have a long name" and "we own the initials of that name" and "we are old enough that abbreviating is acceptable". For brands wanting heritage, financial competence, hospitality polish, or luxury exclusivity, monograms are often the right architectural choice. + +### Reference examples + +- **Chanel's CN** (pure ligature, two letters share a counter) +- **Gucci's GG** (pure ligature, mirrored) +- **HBO** (geometrically framed inside a rectangle) +- **YSL** (stacked geometric composition, the three letters set as a tower) +- **Volkswagen's VW** (tight kerning, overlapping) + +### Pattern vocabulary + +- Ligature pairs (CN, GG, MN, AB, SR with shared counters or strokes) +- Stacked initials (the top letter above the bottom letter, often with a horizontal divider) +- Framed initials (letters inside a ring, shield, diamond, oval) +- Overlapping initials (the V and W of Volkswagen, the H and B of various heritage brands) +- Crowned or filigreed monograms (heritage luxury treatment with ornamental frame elements) + +### Decision criteria + +Monograms fit when: +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +Monograms fail when: +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials + +### Common cliches to avoid + +- **The "monogram inside a heavy ring"** for any brand wanting heritage. Heavy rings around initials read as fake-heritage logo template; rings work when they are restrained, geometrically specific, and earn their place. +- **The "heritage shield with a year"** for any brand wanting legacy. Founded-in-1923 shields look like every craft beer label. +- **The "ornamental monogram with filigree"** for any brand attempting traditional luxury. Heavy ornamentation reads as Renaissance Faire, not as Hermès. +- **The "monogram with a serif crown"** for any boutique heritage attempt. Crowns are exhausted. + +The escape is restrained execution. A monogram that earns its place uses specific letterform construction, specific kerning, and minimal framing. The discipline is what makes Chanel's CN read as Chanel and not as a costume version of Chanel. + +--- + +## How to choose, in summary + +Match the symbol approach to the brand name and the category positioning. + +- **Descriptive names invite literal or letterform-derived symbols.** Atlas, Forge, Pulse, Anchor, Falcon, Mountain. The name suggests something to depict. +- **Abstract names demand abstract or geometric-reduction symbols.** Stripe, Anthropic, Linear, Notion. The name does not point at anything specific, so the symbol cannot either. +- **Heritage names default to monograms.** A founder's surname, a place name, a multi-word firm. The monogram turns the long name into a positioning statement. +- **Tech-modern names often default to geometric reduction.** Anthropic's hex grid, OpenAI's flower, the universe of B2B SaaS marks built from primitives. The risk is interchangeability; the save is specific proportions and pairing. + +The wrong approach disconnects symbol from name. A literal peak on Stripe would read as a brand mistake. A geometric reduction on Atlas Coffee would feel cold. The approach is downstream of the name, the category, and the positioning intention. diff --git a/skills/logo-design/references/typographic-registers.md b/skills/logo-design/references/typographic-registers.md new file mode 100644 index 0000000..1d22e57 --- /dev/null +++ b/skills/logo-design/references/typographic-registers.md @@ -0,0 +1,263 @@ +# Typographic registers + +Type carries the wordmark. Type carries half the lockup. Type drives more of a logo's read than any other single decision because type is the voice of the brand, frozen. This file expands the seven registers listed in [SKILL.md](../SKILL.md) with named typefaces, category-fit notes, example brands, pairing guidance, and the failure mode each register tends toward. + +--- + +## Geometric sans + +Built from circles and verticals. Letterforms are constructed from primitive geometric shapes (circle, square, triangle) with consistent stroke weight and minimal optical adjustment. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde, Gotham, Proxima Nova. + +Geometric sans reads modern, considered, often optimistic. The discipline of the geometry signals "we made deliberate choices". Used well, it carries restraint. Used poorly, it reads as cold or interchangeable with every other modern startup. + +Futura was the original (1927, Paul Renner). Avenir is Adrian Frutiger's warmer, more humanist take on the same idea (1988). Avenir Next is the modern release with broader weights and language coverage. Cabinet Grotesk is a recent geometric sans that became a signature of the 2020-2023 startup wave (and now reads dated for that reason). Gotham (Tobias Frere-Jones) is the American-vernacular geometric sans, derived from New York signage; warmer than Futura, more grounded than Avenir. + +### Categories that default to geometric sans + +- Tech startups (the modern default; risk of looking like every other startup) +- Architecture and design firms (where the geometry signals craft) +- Modern hospitality (boutique hotels, restaurant groups built post-2010) +- Wellness and fitness brands at the considered end (not the energetic end) +- Real estate at the modern positioning end (urban, design-forward) + +### Example brands + +- Spotify (custom geometric sans, derived from Circular) +- Airbnb (Cereal, custom geometric sans by Dalton Maag) +- Headspace (Apercu Pro, geometric humanist sans) +- Nike's wordmark (custom Futura-derived) + +### Pairing notes + +Geometric sans pairs well with old-style serifs (the contrast between modern geometry and classical curves reads as intentional) and with slab serifs of similar weight class (both are structurally heavy, the contrast is in the silhouette). Avoid pairing geometric sans with neo-grotesque sans; the two registers are too close in feel and the pairing reads as indecisive. + +### Common pitfalls + +- The trend-chasing risk. Cabinet Grotesk became "2022-2023 startup typeface"; using it now codes the brand as late to a trend. +- The cold-tech risk. Pure geometric sans can feel emotionally distant. Warming requires color, custom letterform, or strong context. +- The interchangeability risk. Geometric sans wordmarks all start to look the same after a category saturates. Distinctiveness comes from custom letterforms or weight/proportion choices, not just typeface selection. + +--- + +## Humanist sans + +Has serif-like calligraphic gestures without serifs. The strokes vary in weight (subtle thick-thin contrast). The letterforms have movement, not just geometry. Gill Sans, Optima, Frutiger, Source Sans Pro, Inter at higher optical sizes, Hermann Zapf's Kabel, Jeremy Tankard's Bliss. + +Humanist sans reads professional but warm. The calligraphic origin gives the type a hand, where geometric sans has none. Excellent neutral choice when the category demands restraint with personality. Old enough to feel timeless; not old enough to feel dated. + +Gill Sans (Eric Gill, 1928) is the original British humanist sans, derived from Edward Johnston's London Underground typeface. Optima (Hermann Zapf, 1958) is the most calligraphic of the humanist sans, with strong thick-thin contrast that reads as sophisticated. Frutiger was designed for Charles de Gaulle airport signage in 1976 and has been the workhorse humanist sans for transit and wayfinding ever since. Source Sans Pro is Adobe's open-source humanist sans (Paul Hunt, 2012); Inter (Rasmus Andersson) crosses humanist and neo-grotesque registers depending on optical size. + +### Categories that default to humanist sans + +- Professional services (consulting, agencies, professional partnerships) +- Education and academic publishing +- Healthcare at the calm end (One Medical, Forward) +- Civic and institutional work (museums, libraries, public services) +- Editorial brands at the modern restrained end + +### Example brands + +- BBC (Gill Sans) +- BMW Group's corporate identity (custom humanist sans, derived from Helvetica with humanist warming) +- One Medical (FF Tisa Sans, humanist with slab adjacency) +- Various university identities (Penn, Stanford, MIT all use humanist or near-humanist marks) + +### Pairing notes + +Humanist sans pairs well with old-style serifs (the calligraphic origins of both registers complement each other) and with transitional serifs (humanist sans for body, transitional serif for display creates a coherent editorial system). Avoid pairing humanist sans with geometric sans; the calligraphic warmth of humanist clashes with the geometric coldness. + +### Common pitfalls + +- The "British civic" risk. Gill Sans is so coded as British civic that using it for a non-British brand can feel anachronistic. +- The dated risk for old humanist sans. Frutiger reads as 1990s transit unless deployed deliberately. Optima reads as 1970s pharmaceutical unless restored to its original sophistication. +- The lukewarm risk. Humanist sans is the safest choice; it can also be the most forgettable. Distinctiveness still requires custom letterform or strong color discipline. + +--- + +## Neo-grotesque sans + +The modern professional default. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America, Univers, Akzidenz-Grotesk. Neo-grotesque is descended from 19th-century grotesque sans typefaces but rationalized for the modern era. Even stroke weight, closed apertures, neutral letterform construction. + +Neo-grotesque reads competent and contemporary. It is the typographic equivalent of a black t-shirt: tasteful, defensible, easy to specify. The trade-off is that everyone else is wearing the same black t-shirt. Without strong color, distinctive symbol, or considered execution, a neo-grotesque wordmark blends into the category default. + +Helvetica (Max Miedinger, 1957) is the prototype. Akzidenz-Grotesk preceded it (1898) but Helvetica became the dominant version. Söhne (Klim Type Foundry, 2019) is the modern revival of the neo-grotesque tradition, with sharper detailing and broader weights. GT America (Grilli Type) crosses American grotesque and Swiss neo-grotesque traditions. Inter (Rasmus Andersson, 2016) is the modern open-source workhorse, designed for screen rendering at every size. + +### Categories that default to neo-grotesque sans + +- B2B SaaS (the unmistakable default; nearly every modern SaaS brand uses Inter, Söhne, or a custom neo-grotesque) +- Modern financial services (Stripe, Mercury, Ramp all use neo-grotesque or near-neo-grotesque) +- Tech at scale (Apple's San Francisco is a neo-grotesque-influenced humanist; Google's Product Sans is neo-grotesque-influenced geometric) +- Modern professional services rejecting the humanist sans default +- Editorial brands at the contemporary end (Bloomberg, modern news brands) + +### Example brands + +- Stripe (custom Sohne Mono and Sohne Schmal) +- Ramp (Söhne) +- Linear (Inter) +- Vercel (Inter, then custom Geist) +- Notion (Söhne) + +### Pairing notes + +Neo-grotesque sans pairs well with serif typefaces of similar weight class (both transitional and old-style serifs work), creating a clean modern-classical contrast for editorial systems. Avoid pairing neo-grotesque with geometric sans or humanist sans; the registers are too close and the pairing reads as indecisive. Custom-drawn neo-grotesque (Söhne, Geist) pairs especially well with stencil display faces, slab serifs, or condensed display sans for brand-system contrast. + +### Common pitfalls + +- The interchangeability risk is highest in this register. Neo-grotesque B2B SaaS wordmarks blur together. The brand that uses neo-grotesque without custom letterforms or strong supporting elements risks becoming visually identical to its category. +- The Helvetica problem. Helvetica is so over-used and so neutral that it now reads as "we did not make a typographic decision". Modern alternatives (Inter, Söhne, GT America) carry similar discipline with more current detailing. +- The screen-versus-print problem. Some neo-grotesque cuts are optimized for screen and look thin at print sizes; others are optimized for print and look chunky at small screen sizes. Pick based on primary application. + +--- + +## Transitional serif + +Modern serifs with high contrast (thick stems, thin transitions, sharp brackets). Source Serif, Charter, Lyon, IBM Plex Serif, Mrs Eaves, Caslon Pro at smaller sizes. Transitional serif sits between old-style serif (low contrast, organic) and modern Didone serif (extreme contrast, geometric). + +Transitional serif reads editorial, considered, intellectual. It carries the long-form heritage of book typography while reading as contemporary. Excellent for legal, publishing, financial, and editorial brands that want serif gravity without the heritage signal of old-style serif. + +Source Serif (Frank Grießhammer, 2014) is Adobe's open-source transitional serif, designed for both print and screen. Charter (Matthew Carter, 1987) is the original screen-optimized transitional serif, designed for low-resolution rendering before high-DPI displays existed; still excellent. Lyon (Kai Bernau, Commercial Type) is the contemporary editorial transitional serif of choice, used by The New York Times Magazine and many editorial brands. IBM Plex Serif (Mike Abbink, IBM, 2017) is IBM's open-source corporate serif, deployed across IBM's global identity. + +### Categories that default to transitional serif + +- Modern legal firms wanting serif gravity without old-fashioned positioning +- Editorial brands and publications (NYT Magazine, The Atlantic in some treatments, Cereal magazine) +- Financial services at the considered end +- Academic publishing (university presses, scholarly journals) +- Modern luxury at the editorial end (not the heritage-luxury end) + +### Example brands + +- The Atlantic (custom transitional serif, derived from Mrs Eaves and Filosofia) +- Vox Media (Lyon) +- Apple's editorial type (custom New York, transitional serif) +- IBM's identity system (Plex Serif) + +### Pairing notes + +Transitional serif pairs well with neo-grotesque sans (the modern-classical contrast is clean and editorial) and with humanist sans (both share calligraphic origins). The classic pairing for editorial is transitional serif for headlines and body, neo-grotesque sans for captions and metadata. Avoid pairing transitional serif with old-style serif; the readers will register the contrast as a mistake rather than an intention unless the deployment is deliberate. + +### Common pitfalls + +- The "magazine logo" trap. Transitional serif is so coded as editorial that using it for non-editorial brands can feel like the brand is trying to wear an editorial costume. +- The screen-rendering problem. Transitional serif's thin strokes can break at small screen sizes if the typeface wasn't optimized for low-DPI rendering. Pick a screen-optimized cut (Charter, Source Serif, Plex Serif) or set the wordmark large enough that the thin strokes survive. +- The "trying too hard" risk. Transitional serif communicates considered restraint; over-styling (italic, weight contrast, custom ligatures) can flip the register to ornate and undermine the restraint signal. + +--- + +## Old-style serif + +Classical serifs with low contrast and warm, organic shapes. Garamond, Caslon, Sabon, Adobe Garamond, Bembo, Janson Text. The letterforms reference 16th-18th century book typography. Diagonal stress, bracketed serifs, gentle thick-thin variation. + +Old-style serif reads heritage, traditional, institutional. It carries weight that newer registers cannot. Used in legal firms whose history runs to a partner's name from 1923, in academic institutions that predate the country, in luxury brands whose claim is centuries-long craft. Used poorly, it reads as a fake heritage costume. + +Garamond (Claude Garamond, mid-1500s) is the prototype; Adobe Garamond (Robert Slimbach, 1989) is the most-deployed modern revival. Caslon (William Caslon, 1722) is the British equivalent, long called "the safe choice for legal documents". Sabon (Jan Tschichold, 1967) is a modernized Garamond designed for industrial typesetting. Bembo (Stanley Morison's revival of Aldus Manutius's 1495 type) is the Italian Renaissance reference. All four predate every other typeface in this file by centuries. + +### Categories that default to old-style serif + +- Legal firms with heritage positioning (white-shoe firms, partnerships founded before 1950) +- Academic institutions (universities, presses, scholarly journals) +- Heritage luxury brands (centuries-old jewelers, watchmakers, fashion houses) +- Editorial brands with literary positioning (literary magazines, book publishers) +- Whiskey, wine, and other categories where "we have been doing this for generations" is the marketing claim + +### Example brands + +- The Economist (custom Caslon-derived display) +- The New Yorker (custom Caslon-derived masthead and ITC New Baskerville for body) +- Most university press identities (Yale, Oxford, Princeton) +- Most heritage law firm identities (Wachtell, Cravath, Latham use serifs derived from this register) + +### Pairing notes + +Old-style serif pairs well with humanist sans (both share calligraphic origins) and with neo-grotesque sans for editorial systems wanting modern-classical contrast. Avoid pairing old-style serif with geometric sans; the registers fight each other (geometric coldness vs old-style warmth). Avoid pairing old-style serif with transitional serif; the contrast is too subtle to register as intentional. + +### Common pitfalls + +- The dated risk. Old-style serif used without deliberate restraint reads as old-fashioned, which can be the goal (heritage) or the failure (trying to look serious by using old-looking type). +- The thin-stroke screen problem. Old-style serif's hairline serifs and thin strokes can disappear at small screen sizes. Either pick a screen-optimized old-style cut (Adobe Garamond Pro, EB Garamond) or accept that the wordmark must be set large. +- The fake-heritage risk. Using Garamond on a brand founded last year reads as costume, not heritage. The audience is not fooled by typography alone; the rest of the brand system has to carry the heritage claim. + +--- + +## Slab serif + +Heavy structural serifs with strong thick-thin uniformity. The serifs are blocky, rectangular, often nearly equal in weight to the stems. Sentinel, Adelle, Roboto Slab, Tisa, Rockwell, Archer, Vitesse. The visual register is strong, declarative, sometimes journalistic. + +Slab serif reads strong, structural, declarative. It carries authority without the heritage baggage of old-style serif. Common in editorial work, sports brands, journalistic identities, and brands that want serif weight without the ornament of transitional or old-style serifs. + +Sentinel (Hoefler & Frere-Jones, 2009) is the modern editorial slab. Adelle (TypeTogether, 2009) is the screen-optimized slab serif of choice for digital editorial. Roboto Slab is Google's open-source slab. Rockwell (Frank Hinman Pierpont, 1934) is the British slab serif of railway and industrial heritage. Tisa (Mitja Miklavčič) is the modern slab with humanist warming, used in editorial systems. + +### Categories that default to slab serif + +- Editorial and publishing (when the brand wants more weight than transitional serif provides) +- Sports brands (the typographic equivalent of athletic gravity) +- Journalistic identities (some newspapers, news magazines) +- Industrial and engineering brands (the structural quality reads as "we make real things") +- Outdoor and adventure brands (Filson, Patagonia in some treatments, REI's wordmark) + +### Example brands + +- Mailchimp's wordmark (custom slab-derived script) +- The Wall Street Journal (in older treatments) +- Various sports league identities (NFL teams, college athletics) +- Filson's wordmark (custom slab serif) + +### Pairing notes + +Slab serif pairs well with neo-grotesque sans (the structural similarity reads as one design language at different ornament levels) and with geometric sans (both are constructed registers). Avoid pairing slab serif with old-style serif; the contrast between structural and organic serifs reads as system inconsistency. + +### Common pitfalls + +- The "newspaper from 1985" risk. Some slab serifs read as 1980s editorial unless paired with current typographic systems. +- The clunky risk. Slab serifs' structural weight can feel heavy at large sizes; the wordmark needs to be sized carefully so the slabs do not overpower the letterforms. +- The genre-trapping risk. Slab serifs are so coded for sports, journalism, or industrial that using them outside those categories can feel like the brand is borrowing the register's gravity rather than earning its own. + +--- + +## Display custom + +Custom-drawn or heavily-modified typeface designed specifically for the brand. Reads distinctive but expensive in time and budget. The wordmark uses letterforms that exist nowhere else. + +Custom display is the highest distinctiveness tier. Stripe's wordmark, Google's Product Sans, Pinterest's custom geometric, Spotify's Circular variant, Airbnb's Cereal. Each is a custom typeface drawn to solve a specific problem in the brand's wordmark or identity system. + +The justification is when the brand needs a wordmark no one else has and the budget supports drawing one. Custom display is rarely justified for new brands without significant marketing investment because the brand has not yet earned the recognition that makes the custom letterforms register as distinctive. For mature brands, custom display is the ceiling of typographic discipline. + +### Categories where custom display fits + +- Mature brands at scale where custom letterforms become a competitive moat +- Tech-led brands with budget for type design partnerships +- Heritage luxury brands whose wordmark must be unique (not Garamond plus a name) +- Editorial brands with recognizable masthead type (The New York Times, The New Yorker) +- Sports leagues and major sports brands + +### Example brands + +- Stripe (custom Sohne, then Söhne plus custom optical adjustments on the wordmark) +- Google (Product Sans, custom geometric) +- Spotify (Circular variant, then custom Spotify Mix) +- Airbnb (Cereal, custom geometric humanist by Dalton Maag) +- Pinterest (custom geometric for the wordmark) + +### Pairing notes + +Custom display is rarely paired in lockup; the custom typeface IS the wordmark. The pairing decision is which body and metadata typefaces support the custom display in larger system applications. The body typeface is typically chosen for legibility at small sizes (a screen-optimized neo-grotesque or humanist sans) rather than for visual harmony with the custom display. + +### Common pitfalls + +- The cost risk. Custom letterform drawing is expensive (5-figure to 6-figure engagements depending on scope). The investment must match the brand's recognition trajectory. +- The over-customization risk. Custom letterforms should solve specific problems, not announce themselves. The custom "g" that reads as cleverly drawn rather than as just-the-letter-g signals committee work. +- The aging risk. Custom display typefaces age with the era they were drawn in. The Spotify wordmark from the 2010s reads as 2010s; the brand has had to update the system multiple times. Plan for redrawing every 5-10 years. + +--- + +## How to choose, in summary + +The choice flows from category default and positioning intention. + +- **In-category choice signals competence.** Legal in old-style serif, SaaS in neo-grotesque sans, sports in slab serif. The audience reads "this brand understands the category". +- **Out-of-category choice signals positioning.** Legal in geometric sans signals "we are modern". SaaS in old-style serif signals "we take the work seriously". Outdoor in geometric sans signals "we are not your grandfather's outdoor brand". The shift is intentional and the rest of the brand system has to support it. +- **Custom display is reserved for mature brands** with recognition that earns the investment. +- **Pairing logic** combines the wordmark register with body and metadata registers to build the system. The pairing should read as one design intention, not as two competing ones. + +The wrong typographic register is not always obvious in isolation. It becomes obvious in deployment: the wordmark on the business card, the lockup at retail, the favicon at 16px. Test the chosen register against the brand's actual application contexts before committing. diff --git a/skills/long-form-content-frameworks/SKILL.md b/skills/long-form-content-frameworks/SKILL.md new file mode 100644 index 0000000..b80133a --- /dev/null +++ b/skills/long-form-content-frameworks/SKILL.md @@ -0,0 +1,311 @@ +--- +name: long-form-content-frameworks +description: "Patterns for individual long-form content pieces. Case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials. The structural disciplines that distinguish publication-quality long-form from bloggy-long padding or academic bloat. Different from pillar-content-architecture (which covers hub structure); this skill covers individual deep-dive pieces. Triggers on long-form content, case study writing, whitepaper, research report, definitive guide, ebook, manifesto, long-form tutorial, deep-dive article, anchor piece, foundational article, structural archetypes. Also triggers when a piece is over 3,000 words and the team is unsure how to structure it, when a long-form draft feels padded or saggy, or when a flagship asset needs the depth to actually earn the length." +category: content +catalog_summary: "Structural patterns for individual long-form pieces (case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials) that distinguish publication-quality work from bloggy-long padding or academic bloat" +display_order: 9 +--- + +# Long-Form Content Frameworks + +A senior editorial leader's playbook for individual long-form content pieces. The structural disciplines that distinguish publication-quality work from bloggy-long padding or academic bloat. + +Long-form is where most content programs lose their nerve or lose their way. Teams either stretch a 1,500-word post to 5,000 with filler (the bloggy-long failure mode), or they over-document the topic with no editorial spine (the academic-bloat failure mode). The pieces that earn their length are the ones where each section justifies its weight, the lede sets a thesis the body actually delivers, and the closing leaves the reader with something specific. + +This skill covers the individual long-form piece: the case study, the whitepaper, the research report, the manifesto, the ebook chapter or full ebook, the definitive guide, the long-form tutorial. Different from `pillar-content-architecture` (which covers HUB architecture: how a pillar plus cluster system fits together), this skill covers the long-form PIECE itself, regardless of whether it sits at the center of a hub or stands alone. + +The voice is the senior editorial leader who has shipped dozens of flagship long-form assets and watched plenty of others fail. Honest about which formats earn their length, which structural archetypes fit which problems, and where long-form most often goes wrong. + +When to use this skill: planning a flagship long-form piece, structuring a draft that feels saggy, reviewing a long-form piece that is technically correct but emotionally flat, or auditing a content library to find the long-form pieces that should have been blog posts. + +--- + +## What this skill is for + +This skill spans individual long-form content pieces. The content suite distinction: + +- `content-strategy` is program scope: what to produce across the program. +- `pillar-content-architecture` is HUB scope: pillar plus cluster as a topical hub system. +- **`long-form-content-frameworks` (this skill)** is PIECE scope for long-form: individual deep-dive pieces, standalone or as pillars. +- `content-and-copy` is execution scope at any length: writing the words. +- `content-brief-authoring` is per-piece brief scope at any length: the contract. +- `editorial-qa` is gate scope: pre-publish verification. +- `ai-content-collaboration` is workflow scope: how humans and AI compose. + +A pillar page IS often a long-form piece. The two skills compose: pillar-content-architecture decides the hub shape and which pieces sit where; this skill is how you structure the long-form pieces themselves so they earn the length they take up. + +The audience: editorial leads, content directors, in-house teams shipping flagship long-form, agencies producing whitepapers and research reports, anyone planning a piece that will run 3,000+ words and need to hold a reader to the end. + +What is not in scope: blog-post-length writing (covered by `content-and-copy`), the brief itself (covered by `content-brief-authoring`), the hub architecture around a long-form piece (covered by `pillar-content-architecture`), or the pre-publish QA pass (covered by `editorial-qa`). + +--- + +## Bloggy-long vs academic-bloat vs publication-quality + +The keystone framing. Two failure modes plus the discipline. + +**Bloggy-long.** A regular blog post stretched to 5,000 words via padding. Same structural shape as 1,500 words, just inflated: more transitional paragraphs, more "before we get into it," more recap sections, more bullet expansions of single ideas. The reader notices within 600 words and skims. Output: a piece that ranked because it was long, never gets read all the way through, never gets shared, never earns links because nobody finished it. + +**Academic-bloat.** Exhaustive coverage that loses the thread. 8,000 words where 4,500 would have served. Every adjacent topic surveyed; every definition restated; every caveat documented. Reader respects the effort and skims for the parts they need. Output: a "comprehensive" piece that nobody reads end-to-end, that does not change anyone's mind, that performs in search but underperforms in trust. + +**Publication-quality.** Structural depth that earns the length. Each section justifies its weight. The lede establishes a thesis the body delivers. The closing is specific. Reading flow varies in density, register, and rhythm so the piece sustains attention. The piece reads as the work of someone who had something specific to say and the discipline to say it well at length. + +The litmus test. Ask of any long-form draft: would cutting this section weaken the argument, or would it just make the piece shorter? If cutting strengthens it, the section was filler. The piece earns its length when each section is doing structural work the argument requires. + +--- + +## Long-form formats and when each fits + +Seven formats, each with a different structural shape and a different reader contract. + +**Case study.** A specific company, project, or initiative with quantified outcomes. Reader contract: "Show me what worked and why, with specifics." Length: 2,000 to 4,000 words typical. Structural archetype: usually problem-solution. The case-study tax: real numbers, real names, real specificity. Generic case studies signal nothing. + +**Whitepaper.** A position document on a substantive topic, typically with original analysis. Reader contract: "Take me through your reasoning on this question with the rigor I would expect from a serious source." Length: 3,000 to 8,000 words. Structural archetype: layered argument or comparative analysis. Often gated. The whitepaper tax: original synthesis, not survey of existing literature. + +**Research report.** Original primary research presented with methodology, findings, implications. Reader contract: "Show me the data, how you collected it, what it means." Length: 4,000 to 12,000 words. Structural archetype: taxonomic survey or comparative analysis. The research-report tax: actual primary research, not "we surveyed 300 marketers" with leading questions. + +**Definitive guide.** Comprehensive coverage of a topic for a specified audience. Reader contract: "Be the canonical resource on this." Length: 4,000 to 10,000 words. Structural archetype: taxonomic survey. The definitive-guide tax: actual comprehensiveness; gaps reveal that the guide is not actually definitive. + +**Manifesto.** A position paper on what the writer believes and why, often confrontational. Reader contract: "Tell me what you think and convince me." Length: 1,500 to 6,000 words. Structural archetype: layered argument or narrative arc. The manifesto tax: actual conviction, not diplomatic hedging. + +**Ebook.** Multi-chapter long-form, often a sequence of related pieces with introduction and conclusion. Reader contract: "Take me through a body of work." Length: 8,000 to 30,000+ words. Structural archetype: usually narrative arc across chapters. The ebook tax: each chapter earns its place; the table of contents is not padding. + +**Long-form tutorial.** Instructional content where the reader is following along. Reader contract: "Take me from where I am to where I want to be, step by step." Length: 3,000 to 8,000 words. Structural archetype: problem-solution with sequential steps. The long-form-tutorial tax: every step actually works; gaps in the sequence break the reader. + +Detail in [`references/format-decision-framework.md`](references/format-decision-framework.md). + +--- + +## Structural archetypes + +Five archetypes that fit different long-form problems. + +**Problem-solution.** State the problem with weight; develop why it matters; present the solution; show how it works; address objections. Fits case studies, long-form tutorials, manifestos with a clear opposition. Risk: feels formulaic if every piece uses it. + +**Narrative arc.** Beginning, middle, end. A protagonist (often the company, sometimes a person, sometimes the reader) faces a complication and resolves it. Fits ebooks, some case studies, longer manifestos. Risk: forced narrative on topics that are not actually stories. + +**Layered argument.** Position stated; layer 1 evidence; layer 2 evidence; counter-arguments addressed; synthesis. Fits whitepapers, manifestos, position pieces. Risk: feels academic if the layers do not build to a real synthesis. + +**Taxonomic survey.** A topic mapped into categories; each category explored; relationships among categories surfaced. Fits definitive guides, research reports surveying a landscape. Risk: feels like a list with subheads if the taxonomy is not actually load-bearing. + +**Comparative analysis.** Multiple options, frameworks, or positions compared along defined axes; tradeoffs surfaced; the writer's recommendation argued. Fits whitepapers, decision-guide research reports, technology comparisons. Risk: feels like a feature matrix if the analysis is shallow. + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. A whitepaper might be a layered argument with comparative-analysis sections. A definitive guide might be a taxonomic survey with problem-solution chapters. The archetype is the spine; variation prevents the piece feeling formulaic. + +Detail in [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md). + +--- + +## Section weight calibration + +How long sections should be relative to each other, varying by format. + +The general principle: section weights match how much load the section is bearing in the argument. Throat-clearing introductions get cut. Setup sections are short. Argument-bearing middle sections are longest. Closings are specific and tight. + +**Whitepaper / research report typical weights.** Introduction 8-12% (thesis stated, scope set). Methodology or framing 10-15% (how the analysis works). Body 60-70% (the actual argument or findings, divided into 3-5 weighted sections). Implications 10-15%. Closing 3-5%. + +**Case study typical weights.** Setup and context 15-20% (the company, the problem, why it mattered). Solution narrative 50-60% (what was done, in sequence). Outcomes 15-20% (quantified results, what worked, what did not). Reflection 5-10% (what the team would change). + +**Manifesto typical weights.** Position 5-10% (what is believed, stated early and clearly). Argument 70-80% (why, with the layers building intensity). Call 10-15% (what should change as a result). + +**Definitive guide typical weights.** Introduction 5-8% (what the guide covers, who it serves). Body across taxonomic sections 80-85% (each section roughly even). Closing and additional resources 7-10%. + +**Long-form tutorial typical weights.** Setup 10-15% (what the reader will achieve, what they need). Sequential steps 70-80% (each step its own subsection). Troubleshooting and edge cases 10-15%. + +The audit. If one section is more than 3x the length of another bearing similar argumentative load, the piece is structurally unbalanced. Either the long section needs to be split, or the short section needs to be deepened, or the imbalance reflects an actual content problem the writer has not surfaced. + +Detail in [`references/section-weight-calibration.md`](references/section-weight-calibration.md). + +--- + +## Lede patterns for long-form + +Long-form ledes do different work than blog-post ledes. + +A blog-post lede answers the user's likely query in the first 200 words. A long-form lede establishes a thesis the next 5,000 words will deliver, sets the reader's expectations for the piece's depth, and earns the reader's attention for the time investment ahead. + +**Patterns that work.** + +- **The contested-claim opener.** A surprising or contested position stated cleanly, then the rest of the piece argues for it. Fits manifestos, opinionated whitepapers. +- **The problem-with-stakes opener.** A problem stated with the stakes made tangible. Fits case studies, problem-solution pieces. +- **The data-anomaly opener.** A piece of data that does not fit the consensus, framed as the question the piece will answer. Fits research reports, analytical whitepapers. +- **The scene opener.** A specific moment, person, or scene that grounds the abstract topic. Fits narrative-arc pieces, magazine-style longform. +- **The orientation opener.** What this piece covers, who it is for, what reading it costs and pays. Fits definitive guides and tutorials where the reader's first question is "is this the right resource for me." + +**Patterns that fail.** + +- The throat-clear opener ("Content marketing has changed dramatically over the past decade. In this article, we will explore...") signals filler ahead. +- The dictionary-definition opener ("According to Merriam-Webster, X is defined as...") signals an unwillingness to commit a position. +- The history-of-the-topic opener (paragraphs of background before the argument starts) loses readers before the thesis lands. +- The "in this article we will discuss" tour opener flattens the piece into an outline before the writer has earned attention. + +The first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. Spending it on filler is the most common long-form failure. + +Detail in [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md). + +--- + +## Sustaining attention across 5,000+ words + +Long pieces that hold readers vary their density, register, and rhythm. Pieces that lose readers feel uniform: same paragraph length, same sentence rhythm, same density of claim, page after page. + +**Density variation.** Some sections argue tightly (claim, evidence, claim, evidence). Others reflect, illustrate, or breathe. The argument-tight sections earn the breathing sections; the breathing sections give readers room to absorb. + +**Register variation.** Most long-form pieces sustain a primary register (analytical, narrative, instructional) while occasionally shifting to a secondary register (anecdotal, reflective, declarative) for variation. A whitepaper that is purely analytical for 6,000 words exhausts the reader; a whitepaper with a mid-piece anecdote or a closing reflection lands harder. + +**Rhythm variation.** Sentence length variation matters more in long-form than short. Strings of 25-word sentences blur; strings of 8-word sentences fragment. The pattern that holds attention: medium sentences with occasional short punches and occasional layered longer constructions. + +**Visual rhythm.** Subheads, pull quotes, callouts, charts, illustrations break the page into navigable units. Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. The rhythm: visual element every 600-1,000 words on average, varied in type. + +**Mid-piece micro-thesis.** Around the 40-60% mark, restate the central claim with new framing. Long-form readers' attention naturally dips mid-piece; the mid-piece restatement reorients them and refreshes engagement. + +Detail in [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md). + +--- + +## Citations and source authority + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. + +**Source hierarchy for long-form.** + +- Primary research: original studies, datasets, interviews, the writer's own data work. Highest authority. +- Authoritative secondary sources: peer-reviewed papers, government data, established research firms, primary reporting from credible outlets. +- Industry-credible sources: vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners. +- Linked-aware secondary sources: reputable blogs and publications where the source is verifying claims, not just amplifying them. +- Avoid: citation laundering through other content marketing pieces, "studies show" claims with no link, anonymous "experts," reposts of reposts. + +**Citation density.** Long-form arguments need citations roughly proportional to claim density. A piece making 30 falsifiable claims needs 30 citations; a piece making 5 strong claims with extensive elaboration may need 5. The audit: every falsifiable claim is either cited or attributed to the writer's own analysis. + +**Source freshness.** Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. The "85% of marketers" stat from 2018 in a 2026 piece signals stale research. + +**Inline vs endnote citations.** Long-form on the web typically uses inline links to authoritative sources. For research-heavy pieces, endnote-style citations (numbered footnotes) signal academic rigor; for editorial whitepapers, inline links keep momentum. Either works; pick one and stay consistent within the piece. + +Detail in [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md). + +--- + +## Visualization and breakouts + +Long-form earns visual breakouts; blog posts often do not. The discipline is which breakouts earn their place. + +**Visual element types.** + +- Charts and graphs: data visualization that the prose alone cannot convey efficiently. +- Diagrams: relationships, flows, architectures, taxonomies that benefit from visual structure. +- Pull quotes: moments where a single sentence deserves visual weight. +- Sidebars: tangential but valuable context that does not fit the main thread. +- Tables: comparison data, structured reference material. +- Inline callouts: definitions, warnings, "if you only read one section" pointers. + +**Earned-position rule.** Each visual element earns its place by carrying argumentative load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. + +**Production tax.** Each visual element costs design time, accessibility work (alt text, screen-reader-friendly tables), and revision overhead when the underlying content changes. Long-form pieces with 25 charts each take meaningful production time to maintain. Plan visual count against production capacity, not against ideal-world maximalism. + +**Anti-pattern: the stock-image header.** Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. Either commission specific visual work (custom illustrations, branded data visualizations, scene photography) or skip the hero image. + +Detail in [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md). + +--- + +## Closing patterns + +Long-form pieces with strong closings get shared, get linked, and get remembered. Pieces with throat-clearing closings disappear after the last subhead. + +**Closings that work.** + +- **The specific call.** What should the reader do, decide, or change as a result of reading this. Concrete, not generic. +- **The reframed thesis.** The opening claim restated with the weight the body has now earned, often inverted or sharpened. +- **The open question.** The question this piece's findings raise but do not answer, framed as the next investigation. +- **The personal reflection.** The writer's stake in the topic surfaced briefly. Fits manifestos, opinionated long-form. +- **The provocation.** A challenge to the reader, the field, or the consensus. Fits manifestos. + +**Closings that fail.** + +- The recap closing ("In this piece we covered X, Y, Z") signals the writer ran out of energy. +- The "more research is needed" closing on every research report signals the writer did not commit a position. +- The throat-clear closing ("As we have seen, content is important and only getting more so") delivers no payload. +- The CTA-as-closing ("Book a demo") on a long-form piece breaks the editorial contract; if a CTA belongs, it sits below the closing, not as the closing. + +The audit. Ask of any long-form closing: does this leave the reader with something specific to do, decide, or think about, or does it just signal the piece is ending? If the latter, rewrite. + +Detail in [`references/closing-patterns.md`](references/closing-patterns.md). + +--- + +## Distribution implications for long-form + +Long-form's distribution shape differs from blog-post distribution. The format choices echo through how the piece reaches readers. + +**Gated vs ungated.** Whitepapers and research reports often gate behind a form to capture leads; ebooks frequently do; case studies sometimes do. The tradeoff: gating cuts reach by 70-90%; the gated audience is qualified but small. Manifestos and definitive guides typically stay ungated to maximize reach and link equity. The decision turns on whether the piece's primary value is reach (ungated) or qualified-lead capture (gated). + +**Format choices.** Long-form web page (HTML), downloadable PDF, mixed (web with PDF download option), interactive (web with embedded tools or visualizations). Web pages earn search traffic; PDFs earn email-shareable assets; mixed maximizes both. The production cost rises with format count. + +**Syndication and excerpting.** Long-form pieces lend themselves to chapter excerpts, summary blog posts, and email-newsletter serializations. Plan the excerpting at piece-design time so the chapters or sections are excerpt-ready. See `content-repurposing` for the cross-format adaptation discipline. + +**Refresh schedule.** Long-form pieces with research components need annual or quarterly refresh on the data; long-form pieces with timeless framings need lighter touch. See `content-refresh-system` for refresh prioritization. + +The decision sequence: format first, distribution shape second. A research report's distribution shape (often gated, often PDF, often paired with a webinar) follows from the format choice; trying to retrofit distribution onto a piece that was written for the wrong shape produces friction. + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-long-form-failures.md`](references/common-long-form-failures.md). + +- "We wrote 5,000 words and traffic is flat." Bloggy-long: stretched to length, no structural depth. Cut to 1,800 words or rewrite as publication-quality. +- "Our whitepaper looked authoritative but nobody finished it." Academic-bloat: comprehensive but not load-bearing. Cut sections that did not move the argument. +- "The lede took 800 words to get to the thesis." Throat-clearing opener; rewrite to land the position in the first 150-250 words. +- "Each section is the same length and rhythm." No section weight calibration; sections all bearing the same argumentative load suggests an undifferentiated piece. +- "The piece sags around the 60% mark." Standard mid-piece attention dip; add a mid-piece micro-thesis and rhythm variation. +- "The closing repeated the introduction." Recap closing; rewrite to a specific call, reframed thesis, or open question. +- "Citations are mostly other blog posts." Citation laundering; replace with primary or authoritative secondary sources. +- "We commissioned 12 charts, the team is exhausted, traffic is the same." Visual count exceeded production capacity and earned-position discipline; cut to charts that bear argumentative load. +- "The case study has no specifics." Generic case-study failure; the case-study tax is real numbers, real names, real specificity. Without those, the format does not work. +- "Our manifesto reads as diplomatic." Manifesto failure: the format demands conviction; if the writer cannot commit, write a different format. +- "The definitive guide has obvious gaps." Definitive-guide failure: the format requires actual comprehensiveness. Either fill the gaps or rename the piece. + +--- + +## The framework: 12 considerations for long-form content + +When planning or auditing a long-form piece, walk these 12 considerations. + +1. **Format fits the work.** Case study, whitepaper, research report, definitive guide, manifesto, ebook, or long-form tutorial. Format chosen for reader contract, not arbitrary length. +2. **Structural archetype selected.** Problem-solution, narrative arc, layered argument, taxonomic survey, or comparative analysis as the spine. +3. **Lede earns the next 30 minutes.** Thesis stated, stakes set, position committed within the first 150-250 words. +4. **Section weights calibrated to argumentative load.** No section 3x another bearing similar load; throat-clearing sections cut. +5. **Density variation.** Argument-tight sections balanced with reflective or illustrative sections. +6. **Register variation.** Primary register sustained with secondary-register moments for variation. +7. **Rhythm variation.** Sentence and paragraph length varies; visual breakouts every 600-1,000 words. +8. **Mid-piece micro-thesis.** Central claim restated around the 40-60% mark. +9. **Citations match claim density.** Falsifiable claims cited; primary or authoritative sources preferred; sources fresh. +10. **Visual elements earn position.** Each chart, diagram, sidebar carries load the prose alone cannot. +11. **Closing is specific.** Specific call, reframed thesis, open question, or provocation. Not recap. +12. **Distribution shape matches format choice.** Gating, format mix, syndication plan, refresh schedule planned at piece-design time. + +The output of the framework is a long-form piece that earns its length: every section justified, every page sustaining attention, every claim verifiable, every closing specific. + +--- + +## Reference files + +- [`references/format-decision-framework.md`](references/format-decision-framework.md) - When each long-form format fits. Reader contracts, length norms, structural archetype tendencies, format-specific taxes. +- [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md) - Five archetypes (problem-solution, narrative arc, layered argument, taxonomic survey, comparative analysis) with worked examples and combination patterns. +- [`references/section-weight-calibration.md`](references/section-weight-calibration.md) - Typical weight ratios by format. Whitepaper, case study, manifesto, definitive guide, long-form tutorial profiles. The 3x audit. +- [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md) - Five patterns that work, four that fail. The first-paragraph sales-pitch frame. +- [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md) - Density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis discipline. +- [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md) - Source hierarchy, citation density, freshness, inline vs endnote conventions, citation-laundering anti-pattern. +- [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md) - Visual element types, earned-position rule, production-tax discipline, the stock-image-header anti-pattern. +- [`references/closing-patterns.md`](references/closing-patterns.md) - Five closings that work, four that fail. The specific-call, reframed-thesis, open-question, personal-reflection, provocation patterns. +- [`references/common-long-form-failures.md`](references/common-long-form-failures.md) - 11+ failure patterns with diagnoses, including bloggy-long, academic-bloat, throat-clearing leads, visual-count overruns, citation laundering, format-tax failures. + +--- + +## Closing: long-form earns its length or it does not + +Length is not a virtue. A 5,000-word piece is only worth more than a 1,500-word piece if those extra 3,500 words carry structural and argumentative load the shorter version could not. Most long-form content underperforms because the team chose length first and structural depth second. + +The discipline is the inversion. Decide what the piece needs to deliver, choose the format and archetype that fit, calibrate sections to actual argumentative load, and let the length follow. Pieces written that way earn their length and read as the work of someone who had something to say. Pieces written length-first read as filler, no matter how many subheads dress them up. + +When in doubt about whether a long-form piece is ready, ask: does each section justify its weight, does the lede earn the next 30 minutes, does the closing leave the reader with something specific, are claims cited, do visuals carry load, does the mid-piece micro-thesis refresh attention? If yes to all of those, the piece is publication-quality. If no to any, the gap is where the reader stops reading. diff --git a/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md b/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md new file mode 100644 index 0000000..90a251c --- /dev/null +++ b/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md @@ -0,0 +1,129 @@ +# Attention-sustaining techniques + +How long-form pieces hold readers across 5,000+ words. The patterns that keep reader attention across the time investment, and the underlying observation: readers leave because pieces feel uniform. + +The pieces that lose readers in long-form are the ones that feel monotone. Same paragraph length, same sentence rhythm, same density of claim, page after page. Even competent writing reads as exhausting under that pattern. The pieces that hold readers vary their density, register, and rhythm so the reader's attention has somewhere to recover and somewhere to engage. + +--- + +## Density variation + +Long-form pieces should alternate between argument-tight sections and breathing sections. + +**Argument-tight sections.** Claim, evidence, claim, evidence. Specific, direct, intellectually demanding. The reader is doing work to follow the argument. + +**Breathing sections.** Reflection, illustration, anecdote, restatement. Lower density of new claims; higher density of integration with what was just argued. + +The pattern that holds. After an argument-tight section, a breathing section gives the reader room to absorb. After a breathing section, the reader returns to argument-tight work refreshed. Pieces that are argument-tight throughout exhaust readers; pieces that breathe throughout never feel substantive. + +The audit. For each section, characterize it as argument-tight or breathing. If the sequence is all argument-tight, the piece is dense and exhausting. If the sequence is all breathing, the piece is shallow despite its length. The mix is the discipline. + +--- + +## Register variation + +Most long-form pieces sustain a primary register while shifting briefly to secondary registers for variation. + +**Primary registers.** + +- Analytical: claim-evidence-implication, measured tone, distance from the topic. +- Narrative: scene-driven, character-driven, time-progressive. +- Instructional: do-this-then-this, addressed to the reader directly. +- Declarative: positions stated, opinions committed, weight on conviction. + +**Secondary registers.** Anecdotal moments inside an analytical piece. Reflective moments inside an instructional piece. A specific scene inside a declarative manifesto. A measured analytical section inside a narrative. + +The pattern that holds. A whitepaper sustained in analytical register for 6,000 words exhausts readers; the same whitepaper with a mid-piece anecdote and a closing reflection lands harder. A long-form tutorial sustained in instructional register for 5,000 words feels mechanical; the same tutorial with a brief reflective section on common failures and a personal note from the writer feels human. + +The discipline. Choose the primary register first; insert secondary-register moments at section transitions where the shift will refresh attention rather than disorient. + +--- + +## Rhythm variation + +Sentence and paragraph length variation matters more in long-form than in short. + +**Sentence length.** + +- Strings of 25-word sentences blur. The reader's eye glides over the text without the cognitive checkpoints short sentences create. +- Strings of 8-word sentences fragment. The text reads as choppy, and the reader's attention is interrupted constantly. +- The pattern that holds: medium sentences with occasional short punches and occasional layered longer constructions. + +**Paragraph length.** + +- Long paragraphs (8+ sentences) feel academic. Suitable for argument-tight sections; exhausting if sustained. +- Short paragraphs (1-2 sentences) feel staccato. Suitable for emphasis and for breaking dense passages; fragmenting if sustained. +- The pattern that holds: most paragraphs 3-5 sentences with occasional shorter ones for emphasis and occasional longer ones for layered argument. + +**Heading rhythm.** H2 every 600-1,200 words on average. H3 within H2 sections to break navigation. Headings that come at uniform intervals feel mechanical; headings that follow the actual structural breaks feel natural. + +The audit. Read the piece aloud. Does the rhythm vary, or does every sentence and paragraph land with the same beat? If the latter, the piece needs rhythm work even if every individual sentence is competent. + +--- + +## Visual rhythm + +Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. + +**The norm.** A visual element every 600-1,000 words on average. Visual elements include subheads, pull quotes, callouts, charts, diagrams, sidebars, tables, and images. + +**Variation in type.** All-subheads-no-charts feels under-designed for the piece's length. All-charts-no-pull-quotes feels like a research dump. The visual rhythm should vary: a subhead, then 800 words of prose, then a chart, then 600 words of prose, then a pull quote, then 700 words of prose, then a callout, then 900 words and the next subhead. + +**The earned-position rule.** Each visual element earns its place by carrying load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. See `breakouts-and-visualization.md` for the discipline. + +**Mobile reading reality.** Long-form on mobile gets read in landscape stretches. Subheads should be visible without scrolling on each major section transition; pull quotes should be visible early to preview the piece's depth; charts should be readable without horizontal scrolling. + +--- + +## Mid-piece micro-thesis + +Long-form readers' attention naturally dips around the 40-60% mark. Pieces that survive the dip have a structural move that refreshes engagement at that point. + +**The micro-thesis pattern.** Around the midpoint, restate the central claim with new framing. The restatement does three things at once: it reorients readers who have been following sections, it gives drifting readers a checkpoint to re-engage, and it sets up the second half of the piece. + +**Worked example.** A whitepaper opens with the claim "Most teams treating content marketing as a volume problem will continue to underperform." At the midpoint, after the structural argument and the first empirical layer, the writer restates: "The pattern across the data is consistent. The teams that broke the volume-first cycle did not produce more; they produced less, and committed harder to what they produced." The reader is reoriented; the second half of the piece can build on the restatement. + +**Anti-pattern: the recap micro-thesis.** Restating "as we have seen so far, content marketing is changing" is filler, not micro-thesis. The micro-thesis should add framing or sharpen the claim, not recap. + +**Where the micro-thesis sits structurally.** Often at the boundary between two body sections, especially the boundary between the first and second halves of a layered argument or the boundary between the third and fourth chapters of an ebook. + +--- + +## Combining the techniques + +A 6,000-word whitepaper using all five techniques. + +- **Lede.** Contested-claim opener, declarative register, short paragraphs for opening punch. +- **Setup section.** Analytical register, medium-density argument, 3-5 sentence paragraphs. +- **First body section.** Argument-tight density, analytical register sustained, longer paragraphs as the argument layers. +- **Mid-piece micro-thesis.** A short paragraph that restates the claim with new framing. Brief register shift to declarative. +- **Second body section.** Argument-tight density, but with a worked example inserted as a breathing pause. Worked example shifts briefly to narrative register. +- **Counter-argument section.** Argument-tight again, analytical register, with the counter-arguments engaged seriously. +- **Synthesis.** Density lower, register declarative, paragraphs short and emphatic. +- **Closing.** Declarative, short, specific. + +The piece reads as varied across its length even though it is a single sustained argument. + +--- + +## Common attention-loss patterns + +Patterns that show up when readers drop off mid-piece. + +**The mid-piece sag.** Around the 50% mark, the piece becomes harder to follow. Cause: no micro-thesis, no rhythm variation, the reader is exhausted from sustained argument-tight density. Cure: add micro-thesis at the section boundary nearest the midpoint; insert a breathing section. + +**The wall-of-text section.** A 1,500-word body section with no subheads, no visuals, no rhythm variation. Cause: the writer was deep in the argument and stopped attending to the reader. Cure: identify the natural sub-structure within the section, add subheads or visuals at the boundaries. + +**The abstract drift.** The piece's specifics decrease as it progresses. Concrete examples in the early sections; vague generalizations in the later sections. Cause: the writer ran low on specific examples; padded with abstraction. Cure: cut to the depth where specificity holds; better a shorter piece with sustained specificity than a longer piece that drifts abstract. + +**The energy-decline closing.** The closing reads as a writer who ran out of energy. Cause: writers fatigue before readers do. Cure: write the closing first or revise the closing last with fresh attention; the closing is too important to deliver tired. + +--- + +## Methodology-level choices that stay in the public skill + +The five techniques (density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis), the combining pattern, the common attention-loss patterns and their cures, the read-aloud audit. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags rhythm patterns. Specific reading-time analytics that detect mid-piece drop-off in the team's content. Specific paragraph-length analyzers in the team's writing tool. Specific A/B testing of structural variants. The team's own conventions for visual-element budgets per long-form piece. These vary by team, stack, and analytics setup. diff --git a/skills/long-form-content-frameworks/references/breakouts-and-visualization.md b/skills/long-form-content-frameworks/references/breakouts-and-visualization.md new file mode 100644 index 0000000..f361487 --- /dev/null +++ b/skills/long-form-content-frameworks/references/breakouts-and-visualization.md @@ -0,0 +1,147 @@ +# Breakouts and visualization + +Visual element types for long-form, the earned-position rule, the production-tax discipline, and the stock-image-header anti-pattern. The patterns that distinguish visual rhythm from visual clutter. + +Long-form earns visual breakouts; blog posts often do not. A 1,500-word blog post can carry one image; a 5,000-word whitepaper can carry six or eight visual elements before they feel like clutter. The discipline is not visual count but earned position: which visuals carry argumentative load, and which are decoration. + +--- + +## Visual element types + +Six categories, each with different work to do. + +**Charts and graphs.** Data visualization that conveys patterns the prose alone cannot convey efficiently. Line charts for time series, bar charts for comparisons, scatter plots for correlations, distributions for spread. The chart's value is showing the pattern; if the prose can summarize the pattern in one sentence and the chart adds nothing, the chart is decoration. + +**Diagrams.** Relationships, flows, architectures, taxonomies that benefit from visual structure. Process diagrams, system architectures, hierarchical relationships, decision trees. The diagram's value is making structure visible; topics with simple linear structure rarely need diagrams. + +**Pull quotes.** Moments where a single sentence deserves visual weight. Used sparingly for emphasis; one or two per long-form piece typical. The pull quote's value is signaling "this matters"; using pull quotes too often dilutes the signal. + +**Sidebars.** Tangential but valuable context that does not fit the main thread. Background detail, related concepts, optional deeper coverage. The sidebar's value is letting the main thread stay focused while preserving context for readers who want it. + +**Tables.** Comparison data, structured reference material. Side-by-side option comparisons, parameter listings, multi-axis evaluations. The table's value is making parallel data scannable; tables for non-parallel data are confusing. + +**Inline callouts.** Definitions, warnings, "if you only read one section" pointers. Short, focused, specific. The callout's value is interrupting flow for a specific purpose; callouts without specific purpose are decoration. + +--- + +## The earned-position rule + +Each visual element earns its place by carrying argumentative load the prose alone cannot. + +**Earned visuals.** + +- A chart that shows a pattern the prose can only summarize in vague terms ("increasing over time" becomes specific with the line chart). +- A diagram that makes a complex relationship instantly visible (a system architecture; a process flow with decision points). +- A pull quote that captures a position the writer wants to stand alone for emphasis. +- A sidebar with context that would derail the main thread if inline. +- A table that makes parallel comparison instant when the prose would require careful reading. + +**Decorative visuals.** + +- A chart that restates a number the prose just stated (the chart adds visual interest, not information). +- A diagram of a relationship the prose described in one sentence ("the marketing funnel" diagrammed, when the prose said "marketing has stages"). +- A pull quote of a sentence that did not deserve standalone weight. +- A sidebar with information that should have been cut entirely or integrated into the main thread. +- A table where the rows or columns are not actually parallel. +- A stock image at the top of the piece that signals only that the writer wanted a hero image. + +The audit. For each visual, ask: does cutting this visual lose information or capability that the prose alone cannot replace? If yes, the visual is earned. If no, the visual is decoration. + +--- + +## Production tax + +Visual elements cost more than writers often estimate. + +**Per-visual costs.** + +- Design time. Even simple charts require choices about color, scale, labeling, formatting. +- Accessibility work. Charts need alt text or alternative-format descriptions; tables need proper header markup; complex visuals need text equivalents. +- Revision overhead. When the data changes, the chart changes. When the framing changes, the diagram changes. Visual elements that go stale because they were not updated when the underlying content changed are worse than no visuals. +- Production review. Editors review prose; design or production review visuals. Pieces with many visuals need more review cycles. + +**The capacity audit.** Before committing to a visual count for a piece, check: does the team have the design capacity, the data-engineering capacity (for charts based on data), and the maintenance capacity to keep this number of visuals current? Pieces that ship with 12 visuals and decay because nobody updates them are worse than pieces that ship with 4 visuals that stay current. + +**The MVP-visuals approach.** Plan the minimum viable visual count: which visuals are load-bearing for the argument, which would be nice to have, which would be decoration. Ship the load-bearing ones. Add nice-to-haves only if capacity permits and the piece is genuinely long enough to need more visual rhythm. + +--- + +## The stock-image-header anti-pattern + +Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. + +**The pattern.** A whitepaper opens with a generic stock photo of "diverse business team meeting around laptop with charts." The image conveys nothing specific; readers tune it out within milliseconds. + +**Why it fails.** Long-form's value proposition includes signaling that the work is serious. Stock imagery undermines the signal: a serious piece would have commissioned specific visual work or skipped the hero image. Stock imagery says "we wanted a hero image and did not invest in one." + +**The cure options.** + +- Commission specific visual work. Custom illustration matched to the piece's argument. Branded data visualization based on the piece's findings. Scene photography directly related to the piece's case study. +- Skip the hero image entirely. Long-form pieces can open without a hero image; many of the strongest editorial pieces do. +- Use a content-specific opening visual. The first chart in the piece appears at the top, doing dual duty as hero image and load-bearing visual. + +The discipline. If the piece's hero image could be on any other piece on the same general topic, it is generic and should be cut or replaced. + +--- + +## Chart conventions for long-form + +Charts in long-form pieces have specific expectations. + +**Title and caption.** Every chart should have a title that describes what the chart shows and a caption that explains the source of the data. Charts without titles or captions read as decoration. + +**Source attribution.** The data behind the chart should be cited. "Source: 2024 Industry Survey, n=412, methodology in appendix" or similar. Charts without source attribution are unverifiable. + +**Mobile readability.** Charts should be readable on mobile without horizontal scrolling. Wide charts should be redesigned for mobile or marked as "view on desktop for full detail." Charts that are unreadable on mobile lose mobile readers. + +**Color and contrast.** Charts should pass accessibility contrast guidelines (WCAG AA minimum). Color-coded charts need either patterns or labels for readers with color-blindness. Charts that rely on color alone fail accessibility. + +**Data integrity.** Truncated y-axes that exaggerate effects, cherry-picked time ranges, and apples-to-oranges comparisons violate the implicit chart contract. Long-form readers who notice deceptive charts lose trust in the entire piece. + +--- + +## Diagram conventions for long-form + +Diagrams should make structure visible without becoming the main attraction. + +**Simplicity.** A diagram with 30 boxes and 50 arrows is a diagram nobody reads. Diagrams should be visually parse-able in seconds. Complex topics may need multiple simple diagrams rather than one comprehensive one. + +**Labeling.** Every box, arrow, and group should be labeled clearly. Diagrams with unlabeled elements assume the reader can infer the labels from context, which often fails. + +**Reading order.** Diagrams should have an obvious reading order (top to bottom, left to right, or numbered steps). Diagrams without obvious reading order leave readers uncertain how to traverse them. + +**Mobile rendering.** Wide diagrams that work on desktop become unreadable on mobile. Either redesign for mobile, accept that mobile readers will scroll, or split into multiple smaller diagrams. + +--- + +## Sidebar conventions + +Sidebars should be visually distinct from the main thread but not overwhelming. + +**Length.** Most sidebars run 100-300 words. Sidebars longer than 500 words probably should have been their own section in the main thread or their own piece. + +**Visual treatment.** Background color or border that distinguishes the sidebar from main prose. Different typography weight or font (where the design system supports it). + +**Skip-readability.** Sidebars should be skippable without losing the main argument. If the main argument depends on the sidebar's content, that content belongs in the main thread, not in a sidebar. + +--- + +## Pull-quote discipline + +Pull quotes should be earned moments, not decoration. + +**Selection.** A pull quote is a sentence the writer wants to stand alone for emphasis. It should be a sentence whose weight justifies the visual treatment. Generic sentences pulled into pull-quote treatment dilute the device. + +**Frequency.** One or two pull quotes per long-form piece is typical. Three or four can work for very long pieces (8,000+ words). More than that and the device loses meaning. + +**Attribution within pull quotes.** Pull quotes from interviews or external sources need attribution; pull quotes of the writer's own sentences do not need attribution but should still earn the visual weight. + +--- + +## Methodology-level choices that stay in the public skill + +The six visual element types and their work, the earned-position rule, the production-tax discipline, the stock-image-header anti-pattern, the chart conventions, the diagram conventions, the sidebar and pull-quote discipline, the MVP-visuals approach. + +## Implementation choices that stay internal + +Specific design tokens for charts in the team's brand system. Specific charting libraries the team uses. Specific accessibility-checking automation. Specific design-review workflow for visual elements. Specific custom-illustration commissioning processes. Specific stock-photo blocklist or sourcing guidelines. The team's own visual-budget conventions per format. These vary by team, design capacity, and tooling. diff --git a/skills/long-form-content-frameworks/references/citation-and-source-authority.md b/skills/long-form-content-frameworks/references/citation-and-source-authority.md new file mode 100644 index 0000000..5e961f6 --- /dev/null +++ b/skills/long-form-content-frameworks/references/citation-and-source-authority.md @@ -0,0 +1,130 @@ +# Citation and source authority + +Source hierarchy for long-form, citation density discipline, freshness norms, inline vs endnote conventions, and the citation-laundering anti-pattern. + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. Pieces that fail at citation discipline read as if the writer wanted authority without paying the verification cost. + +--- + +## Source hierarchy + +Sources are not interchangeable. The same claim cited from a peer-reviewed paper carries different weight than the same claim cited from a vendor blog post. + +**Tier 1: Primary research.** Original studies, datasets, interviews, the writer's own data work. The writer is producing the data, not citing it. Highest authority. Pieces with primary research signal that the writer or team did the work. + +**Tier 2: Authoritative secondary sources.** Peer-reviewed papers, government data (BLS, Census, equivalent), established research firms (Gartner, Forrester, Pew, IDC, etc.), primary reporting from credible outlets. The writer is citing rigorous secondary work where the source's reputation does the verification work. + +**Tier 3: Industry-credible sources.** Vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners with track records. The writer is citing sources that practitioners in the field would recognize as substantive even if they are not academically rigorous. + +**Tier 4: Linked-aware secondary sources.** Reputable blogs, publications, and commentary where the source is verifying claims rather than just amplifying them. The writer is citing sources that did some level of verification work, even if the source is a blog post rather than a study. + +**Tier 5 and below: Avoid.** Other content marketing pieces (citation laundering), "studies show" claims with no link, anonymous "experts," reposts of reposts, vendor marketing pages cited as research, AI-generated synthesis cited as primary source. + +The discipline. Long-form arguments should cite from tiers 1-3 wherever possible. Tier 4 is fine for color and context but should not bear primary argumentative load. Tier 5 sources signal the writer did not do the verification work. + +--- + +## Citation density + +Citations should be roughly proportional to claim density. + +**A piece making 30 falsifiable claims.** Roughly 30 citations or attributions to primary analysis. Each claim either points to a verifiable source or is identified as the writer's own analysis (in which case the analysis itself should be defended). + +**A piece making 5 strong claims with extensive elaboration.** May need only 5 citations if the elaboration is reasoning rather than fact-claim. Manifestos and position pieces often work this way: a small number of central claims, deeply argued, with citations supporting the claims rather than every elaboration. + +**The audit.** Mark every falsifiable claim in the piece. For each claim, check: is it cited, is it identified as the writer's own analysis, or is it floating? Floating claims are the failure mode. Either cite, attribute to the writer, or cut. + +**The over-citation failure.** Some long-form pieces cite every sentence as if academic rigor were the goal. The result reads as a literature review, not a piece of editorial writing. Citations should support the argument, not perform credibility theater. + +--- + +## Source freshness + +Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. + +**Fast-moving topics.** Technology, marketing tactics, AI capabilities, software stacks, social platforms. A 2018 stat in a 2026 piece on these topics signals stale research unless the writer is citing it specifically as historical context. + +**Stable topics.** Behavioral psychology research, structural economics, mathematical results, established scientific consensus. A 2015 stat on these topics may be perfectly current. + +**The acknowledgment pattern.** When citing older data on a fast-moving topic deliberately, acknowledge it: "A 2018 survey, the most recent rigorous data on the question, found..." The acknowledgment signals the writer knows the data is old and chose to cite it anyway, with reasoning. + +**The hidden-stale-data failure.** Citing a "2024 study" that turns out to be a 2024 republication of 2019 data. Verify primary publication date before citing. + +--- + +## Inline vs endnote citations + +Two conventions for how citations appear. + +**Inline links.** The cited source appears as a hyperlink within the prose. Reader clicks to verify. Common in editorial long-form, content marketing whitepapers, and most web-published research reports. + +- Strength: keeps reader momentum; the prose flows without numerical interruptions. +- Weakness: harder to verify without leaving the page; less academically formal. + +**Endnote-style citations.** Numbered footnotes at the end of the piece, with each citation numbered in the prose. Common in academic-influenced research reports, policy whitepapers, and some long-form published with print-style conventions. + +- Strength: signals academic rigor; preserves the citation list for verification. +- Weakness: interrupts reading flow; readers rarely follow endnotes in web reading. + +**The convention rule.** Pick one and stay consistent within the piece. Mixing conventions (some claims inline-linked, some endnoted) reads as inconsistent. The choice depends on audience expectations: B2B technical research often expects endnotes; editorial whitepapers usually expect inline. + +**Hybrid: inline + bibliography.** Inline links throughout the piece plus a "sources" or "further reading" section at the end. Common compromise. Works well when the piece has both casual references and core sources. + +--- + +## The citation-laundering anti-pattern + +Citing other content marketing pieces as authoritative when the cited piece itself does not have primary support. + +**The pattern.** Piece A claims X with a citation. Piece B cites A as the source for X. Piece C cites B. The original claim X may have been weak, made-up, or misinterpreted; each successive citation amplifies the appearance of authority without adding verification. + +**How it happens.** A writer searching for support for a claim finds another content marketing piece making the same claim and links to it. The writer feels they have cited a source. The source is itself unsourced or weakly sourced. The chain of laundering can run several pieces deep. + +**The cure.** When citing, follow the chain back. If the cited piece does not have primary or authoritative-secondary support, do not cite it. Either find a primary source, or remove the claim, or attribute it as the writer's own observation. + +**Why it matters in long-form.** The reader is investing time. Citation laundering produces pieces that read as authoritative because of citation count but fall apart under verification. Readers who verify discover the laundering; readers who do not develop a slow-decaying trust in the writer. + +--- + +## The own-analysis citation + +When the writer is making a claim from their own analysis rather than citing a source, the claim should be visibly the writer's analysis with the analytical work shown. + +**The pattern.** "Looking at the data across [scope], the pattern that emerges is X." The pattern claim is the writer's; the data is cited; the analytical work is described. + +**The discipline.** Own-analysis claims still need defensibility. The writer should be able to defend, if challenged: where the data came from, how the analysis was performed, what alternative interpretations were considered. + +**The hidden-claim failure.** Sentences that read as fact ("The reality is that programmatic SEO is dying") without acknowledgment that the claim is the writer's interpretation. If the claim is contested, frame it as the writer's view; if the claim is empirical, cite a source. The hidden middle (claim presented as fact when it is interpretation) is where readers lose trust. + +--- + +## Quote attribution + +Long-form pieces often include quotes from named experts, executives, or practitioners. + +**Verification.** Every quote should be from a real person who actually said the words attributed to them. Hallucinated quotes (especially in AI-assisted long-form) are an ethical failure regardless of whether the position is plausibly something the named person might say. See `editorial-qa`'s fact-accuracy reference for the discipline. + +**Context.** Quotes work best when the person's role is identified, the context of the statement is clear (interview, public statement, prior writing), and the quote earns its place by saying something specific. + +**The throwaway-quote failure.** A generic quote ("Content is king," John Smith, CEO) that does not advance the argument. If the quote does not say something specific the prose alone cannot convey, cut it. + +--- + +## Citation in research reports specifically + +Research reports have particularly strict citation expectations because they are claiming primary research authority. + +- **Methodology disclosed.** Sample size, recruitment method, dates, instrument design. Without these, the research is not verifiable. +- **Sample limits acknowledged.** What the sample does and does not represent. A sample of 300 marketers in B2B SaaS does not represent "marketers"; the report should not claim it does. +- **Statistical limits acknowledged.** Confidence intervals, margins of error, significance tests where applicable. Reports presenting cherry-picked data points without distribution context are weak research. +- **Original data made available.** Where possible, the underlying data should be shareable for verification. Reports that hide the data behind the headline findings invite skepticism. + +--- + +## Methodology-level choices that stay in the public skill + +The source hierarchy and tier definitions, the citation-density principle, the freshness rule and acknowledgment pattern, the inline-vs-endnote convention rule, the citation-laundering anti-pattern, the own-analysis discipline, the quote-attribution rules, the research-report citation expectations. + +## Implementation choices that stay internal + +Specific citation management tools the team uses. Specific bibliography generators integrated with the team's writing system. Specific link-checking automation that catches dead links and stale data. Specific data-publication conventions for research reports the team produces. The team's own internal source-tier classification when sources are ambiguous. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/closing-patterns.md b/skills/long-form-content-frameworks/references/closing-patterns.md new file mode 100644 index 0000000..34995e0 --- /dev/null +++ b/skills/long-form-content-frameworks/references/closing-patterns.md @@ -0,0 +1,161 @@ +# Closing patterns + +Five closings that work, four that fail, and the underlying frame: the closing is the writer's last opportunity to leave the reader with something specific. Closings that do not leave anything specific signal a writer who ran out of energy, and the piece is remembered accordingly. + +Long-form pieces with strong closings get shared, get linked, get remembered. Pieces with throat-clearing closings disappear after the last subhead. The closing is one of the most consequential 200-400 words of any long-form piece, and one of the easiest places for writers to under-invest. + +--- + +## The underlying frame + +The closing has three jobs at once. + +1. **Resolve the piece.** Whatever the lede promised, the closing delivers (or acknowledges what was not delivered). +2. **Leave the reader with something specific.** A specific call, a sharpened framing, a question to consider. The reader should be different at the closing than they were at the lede. +3. **Earn the reader's attention for next time.** The closing is the reader's last impression. Readers who finish a piece with a strong closing think of the writer as someone who delivers; readers who finish a piece with a weak closing think of the writer as someone who runs out of energy. + +Closings that do all three are memorable. Closings that do none are forgettable. Closings that do one or two are common and produce pieces that are technically complete but emotionally flat. + +--- + +## Pattern 1: The specific call + +**Shape.** What should the reader do, decide, or change as a result of reading this. Concrete, not generic. + +**Fits.** Most long-form pieces. Particularly strong for problem-solution archetype, manifestos, decision-guide research reports, long-form tutorials. + +**Worked example.** A 5,000-word whitepaper on content distribution closes: "If your team is producing content faster than you can distribute it, the bottleneck is not your production rate. It is your channel-fit decisions. Audit one piece you shipped in the last quarter against the channel-fit framework. Find the one channel where the audience-content match was strongest but the piece never reached that channel. That gap is where the next quarter's distribution work should focus." + +**Why it works.** The reader has a specific action. The action is grounded in the piece's framework, so the framework keeps working after the reading is over. + +**The discipline.** The call must be specific to the piece. Generic calls ("rethink your content strategy") signal that the writer did not commit to a specific recommendation. + +--- + +## Pattern 2: The reframed thesis + +**Shape.** The opening claim restated with the weight the body has now earned, often inverted, sharpened, or made more specific. + +**Fits.** Layered-argument pieces. Whitepapers. Manifestos. Pieces where the body's evidence justifies a stronger version of the opening claim. + +**Worked example.** A whitepaper that opens "Most teams treating content marketing as a volume problem will continue to underperform" closes: "The volume problem is not actually a content problem. It is a strategy problem the team has chosen to express through content. Teams that solve the strategy problem produce less content and more value; teams that try to solve the strategy problem with more content produce more content and less value. The path forward is not better content production. It is harder strategy decisions." + +**Why it works.** The reframed thesis lands the argument with weight the lede could not have carried. The body has done the work; the closing collects the payoff. + +**The discipline.** The reframing must be earned by the body. Pieces that restate the lede unchanged are recapping; pieces that restate it with sharpened framing the body justifies are doing the closing's work. + +--- + +## Pattern 3: The open question + +**Shape.** The question this piece's findings raise but do not answer, framed as the next investigation. + +**Fits.** Research reports. Analytical whitepapers. Pieces where the writer has gone as far as the available evidence allows but the topic continues. + +**Worked example.** A research report on AI search citation patterns closes: "The data is clear that statistics with named sources earn citations at 4x the rate of unsourced claims. The data does not tell us why. The hypothesis worth testing in the next research cycle: do AI engines weight named sources because they are training on a corpus that itself weights named sources, or because the engine providers have built explicit credibility-weighting into the retrieval logic? The answer matters because the answer changes how content programs should respond." + +**Why it works.** The reader is left with intellectual momentum. The piece does not pretend to have answered everything; it acknowledges what it did not answer and frames that as productive rather than as a limit. + +**The discipline.** The open question must be a real question, not a rhetorical one. "What does the future hold?" is rhetorical filler. "Is the citation pattern downstream of the training corpus or of explicit retrieval logic?" is a real question. + +--- + +## Pattern 4: The personal reflection + +**Shape.** The writer's stake in the topic surfaced briefly. What the writer thinks the piece illustrates beyond its specific argument. + +**Fits.** Manifestos. Opinionated long-form. Pieces where the writer has personal authority on the topic. Some case studies where the writer was personally involved. + +**Worked example.** A manifesto on content marketing's drift toward generic AI-assisted output closes: "I have been writing about content for a decade. The pattern that worries me is not that AI is involved; the pattern that worries me is that teams have stopped noticing when their content stopped sounding like them. The discipline this piece argues for is not anti-AI. It is pro-craft. The teams holding the line on craft will be readable in five years. The teams not holding the line will not be." + +**Why it works.** The personal stake adds weight to the argument. The writer's investment in the topic is the closing's payoff: the reader sees that the argument is not abstract for the writer. + +**The discipline.** The personal reflection must be earned by the writer's actual position. Personal reflections from writers without a real stake feel performed. + +--- + +## Pattern 5: The provocation + +**Shape.** A challenge to the reader, the field, or the consensus. Often paired with a refusal to soften the position. + +**Fits.** Manifestos. Position pieces. Long-form criticism. Pieces where the writer is staking out an unpopular or contested position deliberately. + +**Worked example.** A manifesto on programmatic SEO closes: "The teams that will survive the next three years of search-algorithm pressure are the ones that stop treating programmatic as a volume strategy and start treating it as a depth strategy. Most programmatic operations will not make this change. They will not survive. This piece is for the few that will." + +**Why it works.** The provocation establishes that the writer means it. The reader either accepts the provocation and reads the piece as a call to action, or rejects it and reads the piece as wrong; either response is engaged. The middle response (mild interest, no engagement) is what kills long-form's reach. + +**The discipline.** The provocation must be defensible. Provocations the body did not actually argue for read as posturing. Provocations the body argued for and the closing committed to with conviction read as serious. + +--- + +## Failure 1: The recap closing + +**Shape.** "In this piece, we covered X, Y, Z. As we have seen, content is important and only getting more so..." + +**Why it fails.** Signals the writer ran out of energy. Recap is what the table of contents does; the closing should add weight, not summarize. Readers who just spent 30 minutes reading do not need the recap; they need the writer to land the argument. + +**The cure.** Cut the recap. Replace with one of the five working patterns. The closing is not a tour through what the piece said; it is the writer's final position. + +--- + +## Failure 2: The "more research is needed" closing + +**Shape.** Most research reports default to "More research is needed in this area" as a closing. + +**Why it fails.** Signals the writer did not commit a position even when the data warranted one. "More research is needed" is the default closing of academic papers because academic papers have specific norms about hedging; editorial long-form does not have those norms, and the default reads as evasive. + +**The cure.** If the data does support a position, commit the position. If the data does not support a position, frame the closing as an open question (Pattern 3) rather than a generic call for more research. + +--- + +## Failure 3: The throat-clear closing + +**Shape.** "As we have seen, [topic] is important. Going forward, [generic platitude about the topic continuing to evolve]. Teams that [generic recommendation] will be best positioned to [generic outcome]." + +**Why it fails.** Delivers no payload. Every word could appear in any other piece on the same topic. The reader's response is "I read 5,000 words for this?" + +**The cure.** Strip the closing of every generic phrase. What is left is usually nothing; rewrite from scratch with one of the working patterns. + +--- + +## Failure 4: The CTA-as-closing + +**Shape.** The closing is "Book a demo with us today" or "Sign up for our newsletter" or "Download the full report." + +**Why it fails.** Breaks the editorial contract. Long-form readers who reached the closing have invested 30+ minutes in editorial content; pivoting to a sales call reads as bait-and-switch. Trust is damaged. + +**The cure.** If a CTA belongs in the piece, place it after the closing, visually distinct, framed as an offer rather than as the closing itself. The piece's editorial closing does its work first; the CTA appears afterward as a separate element. + +--- + +## The closing audit + +A short framework for auditing a draft closing. + +1. **Does the closing leave the reader with something specific to do, decide, or think about?** If not, rewrite. +2. **Could this closing appear at the end of any other piece on this topic?** If yes, the closing is generic. Rewrite to be specific to this piece. +3. **Does the closing have approximate weight to the piece?** A 5,000-word piece with a 50-word closing under-invests; a 1,500-word piece with a 600-word closing over-invests. +4. **Read the closing aloud. Does it have energy?** Closings that read as tired signal the writer was tired. The reader registers the energy. Rewrite when fresh. +5. **Does the closing match one of the five working patterns?** If it matches one of the failure patterns, rewrite using a working pattern. + +--- + +## When to write the closing first + +Some long-form writers write the closing first and write the body toward it. + +**The argument for closing-first.** Knowing where the piece lands clarifies what the body needs to argue. Writers who draft the body without knowing the closing often discover at the closing that the body did not actually support the planned closing, and have to rework substantial sections. + +**The argument against closing-first.** Some pieces' closings emerge from the body's argument; predetermining the closing constrains where the body can go. Research reports particularly may benefit from following the data and writing the closing once the analysis is complete. + +**The middle path.** Draft a target closing before writing the body. Revisit the target after the body draft. The target may stand, or the body may have produced a stronger closing than the target predicted. + +--- + +## Methodology-level choices that stay in the public skill + +The five working patterns and the four failure patterns, the underlying frame, the closing audit, the closing-first discussion, and the CTA-vs-editorial-closing distinction. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags closing patterns. Specific style guides on closing length and weight in the team's editorial system. Specific A/B testing of closing variants for engagement metrics. Specific conventions for whether and where CTAs appear after closings. These vary by team, audience, and analytics setup. diff --git a/skills/long-form-content-frameworks/references/common-long-form-failures.md b/skills/long-form-content-frameworks/references/common-long-form-failures.md new file mode 100644 index 0000000..2310a3b --- /dev/null +++ b/skills/long-form-content-frameworks/references/common-long-form-failures.md @@ -0,0 +1,179 @@ +# Common long-form failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear repeatedly across long-form drafts, regardless of topic, format, or writer experience. Diagnosing them early saves the rewrite work that catches them late. + +The pattern across most failures: writers reaching for length without doing the structural work that justifies it, and writers under-investing in the structural decisions that make long-form land. + +--- + +## Failure 1: Bloggy-long + +**Symptom.** A 5,000-word piece reads as a 1,500-word piece stretched. Padding paragraphs. Recap sections. "Before we get into it" preludes. Bullet expansions of single ideas. The reader notices within 600 words and skims. + +**Diagnosis.** The writer chose length first and structural depth second. The piece needed to be longer than 1,500 words for SEO or marketing reasons but did not have 5,000 words of substantive content. + +**Cure.** Two options. Cut to actual substantive length (often 1,800-2,500 words). Or expand the structural depth: add original analysis, primary research, case study specificity, or comparative dimensions that justify the length. + +**Prevention.** Choose length based on substantive content, not based on competitor length or SEO targets. SEO algorithms are getting better at detecting padded length; the strategy of "outranking by being longer" is increasingly counterproductive. + +--- + +## Failure 2: Academic-bloat + +**Symptom.** A 7,000-word whitepaper that is exhaustive but loses the thread. Every adjacent topic surveyed. Every definition restated. Every caveat documented. Reader respects the effort and skims for the parts they need. + +**Diagnosis.** The writer aimed for comprehensiveness rather than for argumentative load. The piece treats inclusion as the metric instead of treating each section's contribution as the metric. + +**Cure.** Apply the section-weight audit: which sections are actually load-bearing, which are surveying. Cut surveying sections that do not support specific claims in the load-bearing sections. Often takes 7,000 words to 4,500 with the argument intact. + +**Prevention.** Outline the argument before drafting. Each section should answer: what does this section contribute to the argument? If a section's answer is "comprehensive coverage" rather than a specific contribution, question whether the section earns its place. + +--- + +## Failure 3: Throat-clearing lede + +**Symptom.** The lede took 800 words to get to the thesis. Multiple paragraphs of "content marketing has changed dramatically" before the piece's actual claim appears. + +**Diagnosis.** The writer was warming up. Drafts often have throat-clearing ledes; finished pieces should not. + +**Cure.** Cut the first 400-700 words of the lede. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clearing draft. + +**Prevention.** After drafting, ask: where does the piece's specific argument actually start? Whatever appears before that point is throat-clearing and can usually be cut. + +--- + +## Failure 4: Even-section padding + +**Symptom.** All H2s come within 10% of each other in word count. Each section running 800-1,000 words regardless of its argumentative load. + +**Diagnosis.** The writer treated section length as a quota. Long sections were padded; short sections were either padded or not deepened. + +**Cure.** Identify which sections are actually load-bearing. Let them grow. Cut filler from non-load-bearing sections. + +**Prevention.** Plan section weights in the outline based on argumentative load, not on parallel structure. Allow 2x or 3x weight differences between sections doing different amounts of work. + +--- + +## Failure 5: Mid-piece sag + +**Symptom.** The piece sags around the 60% mark. Reader-attention analytics show drop-off at this point. + +**Diagnosis.** Standard mid-piece attention dip, untreated. No micro-thesis, no rhythm variation; the reader is exhausted from sustained density. + +**Cure.** Add a mid-piece micro-thesis at the section boundary nearest the midpoint. Insert a breathing section (anecdote, illustration, or reflective moment) into a stretch of argument-tight prose. Vary visual rhythm in the mid-piece section. + +**Prevention.** During outlining, mark the midpoint and plan the micro-thesis explicitly. During drafting, audit the middle third for rhythm variation. + +--- + +## Failure 6: Recap closing + +**Symptom.** The closing repeated the introduction. "In this piece we covered X, Y, Z. As we have seen, content is important..." + +**Diagnosis.** The writer ran out of energy. The closing was drafted last, in fatigue, and it shows. + +**Cure.** Rewrite the closing using one of the five working patterns: specific call, reframed thesis, open question, personal reflection, or provocation. + +**Prevention.** Write the closing first, or revise the closing last with fresh attention. Closings deserve disproportionate effort because they are disproportionately consequential. + +--- + +## Failure 7: Citation laundering + +**Symptom.** Citations are mostly other content marketing pieces rather than primary or authoritative-secondary sources. + +**Diagnosis.** The writer searched for support for claims and found other content marketing pieces making the same claims. Citing them feels like sourcing; it is not. + +**Cure.** Follow each citation chain back to the original. If the chain ends at a primary source, cite the primary source. If the chain ends at unsourced or weakly sourced content marketing, either find a primary source for the claim or cut the claim. + +**Prevention.** Default to Tier 1-3 sources (primary research, authoritative secondary, industry-credible). Only cite Tier 4 sources for color and context, never for argumentative load. + +--- + +## Failure 8: Visual-count overrun + +**Symptom.** The piece commissioned 12 charts. The team is exhausted from production. Six months later, charts are stale because nobody updated them. Traffic is the same as it would have been with 4 charts. + +**Diagnosis.** Visual count exceeded production capacity and earned-position discipline. + +**Cure.** Cut to the visuals that bear argumentative load the prose alone cannot. Update them on a maintainable cadence. Future pieces budget visuals against capacity rather than against ideal-world maximalism. + +**Prevention.** Apply the MVP-visuals approach: which visuals are load-bearing, which would be nice to have, which would be decoration. Ship the load-bearing ones first; add others only if capacity permits. + +--- + +## Failure 9: Generic case study + +**Symptom.** The case study has no specifics. "A leading enterprise SaaS company" rather than the company name. "Significant revenue growth" rather than the actual percentage. "Several months" rather than the timeline. + +**Diagnosis.** The case study format failed at its primary tax: specificity. Either the case was too confidential to share specifics, or the specifics were never gathered. + +**Cure.** Get specifics. Negotiate with the customer for what can be shared. If specifics genuinely cannot be shared, abandon the case study format and write a different format (general thought-leadership piece on the lessons learned, with the specific case relegated to background). + +**Prevention.** Do not commit to the case study format until specifics are confirmed shareable. Generic case studies fail the format and are less valuable than honest pieces about the lessons without claiming case-study authority. + +--- + +## Failure 10: Diplomatic manifesto + +**Symptom.** The manifesto reads as diplomatic. "Both sides have valid points." "The answer probably lies somewhere in the middle." Hedge stacking on positions that should be specific. + +**Diagnosis.** The writer chose the manifesto format but could not commit to the conviction the format requires. Often reflects organizational risk-aversion: the manifesto's bold framing was approved but its actual conviction was edited out. + +**Cure.** Either rewrite to commit a position (the format demands it), or change the format. A diplomatic position paper that is not pretending to be a manifesto is fine; a manifesto that hedges is broken. + +**Prevention.** Before committing to the manifesto format, confirm the writer (and the organization) actually has a contested position to argue. If hedging is required, write a different format. + +--- + +## Failure 11: Definitive guide with gaps + +**Symptom.** The "definitive" guide has obvious sub-topic gaps that the audience would notice. The piece claims comprehensiveness but does not deliver it. + +**Diagnosis.** The format implies coverage that the piece does not have. Either the gaps reflect topics the writer did not cover deliberately (and should have flagged), or the writer did not realize the gaps existed. + +**Cure.** Either fill the gaps or rename the piece. "The definitive guide to X" with gaps is broken; "A practitioner's guide to X" with the same content but without the comprehensiveness claim is fine. + +**Prevention.** Before claiming definitive-ness, audit against the audience's likely sub-topic expectations. Confirm coverage or change the framing. + +--- + +## Failure 12: Wrong archetype + +**Symptom.** The piece is fighting itself. The writer is trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. The reader senses the structural friction even when they cannot articulate it. + +**Diagnosis.** Archetype-format mismatch or archetype-topic mismatch. The writer chose an archetype that does not fit the work. + +**Cure.** Identify the natural archetype for the topic and the format. Restructure. This is often a substantial revision because the archetype is the spine; changing it changes how sections fit together. + +**Prevention.** Choose archetype before drafting. Confirm the archetype fits the format and the topic. Do not commit to draft until the archetype-format-topic combination is coherent. + +--- + +## Failure 13: Format-tax unpaid + +**Symptom.** The piece is published in a long-form format but does not pay the format's specific tax. A whitepaper without original synthesis. A research report without primary research. A long-form tutorial with broken steps. + +**Diagnosis.** The writer reached for the format's authority without paying the cost the format demands. + +**Cure.** Either pay the tax (do the original work the format requires) or change the format. A piece published in the wrong format reads as a category error to readers familiar with the format. + +**Prevention.** Confirm the format-tax is payable before committing to the format. Format choice is a downstream decision from "what work is the team prepared to do." + +--- + +## The cross-cutting pattern + +Most long-form failures share a single root: the writer chose length, format, or visual ambition first, and chose the structural and substantive depth second. The pieces that read as publication-quality are the ones where the inverse choice is made: substantive depth first, then length, format, and visual ambition follow from the depth. + +The fix for almost any long-form failure starts with the same audit: what is the piece actually doing, what is each section actually contributing, what does the format require, what does the topic need? When those questions get clear answers, the piece either earns its length or shrinks to a length that fits its substance. + +--- + +## Methodology-level choices that stay in the public skill + +The thirteen-plus failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the prevention discipline. + +## Implementation choices that stay internal + +Specific draft-review checklists the team uses. Specific failure-pattern detection in the team's editing tools. Specific reviewer training on the patterns. Specific case-study negotiation templates for getting customer specifics. The team's own conventions for archetype-format fit confirmation. These vary by team, format mix, and tooling. diff --git a/skills/long-form-content-frameworks/references/format-decision-framework.md b/skills/long-form-content-frameworks/references/format-decision-framework.md new file mode 100644 index 0000000..c624e14 --- /dev/null +++ b/skills/long-form-content-frameworks/references/format-decision-framework.md @@ -0,0 +1,139 @@ +# Format decision framework + +When each long-form format fits, what reader contract it implies, and the format-specific taxes that distinguish credible work from filler dressed in the format's clothes. + +Format selection is the first long-form decision. The wrong format produces predictable failure: a thinly-researched whitepaper reads as a blog post in formal clothing; a manifesto written diplomatically reads as a position paper that committed nothing. Each format has a reader contract. Failing the contract is what readers detect even when they cannot articulate why a piece is not landing. + +--- + +## Case study + +**Reader contract.** "Show me what worked, what did not, and the specifics that let me apply lessons to my own situation." + +**Length norm.** 2,000 to 4,000 words. Shorter feels like a marketing snippet; longer feels padded unless the case is unusually rich. + +**Structural archetype tendency.** Problem-solution, sometimes narrative arc. + +**Format-specific tax.** Specifics. Real company names (or, where confidential, well-disclosed anonymization with enough context to verify the case is real). Real numbers. Real timelines. Real failures alongside successes. Generic case studies that read like marketing collateral fail because the format's value proposition was specificity. + +**Common failures.** Anonymized to the point of meaninglessness ("a leading enterprise SaaS company saw 3x growth"); uncritical success narrative with no failures or surprises; missing methodology (what was measured, how, over what period); no reflection (what would the team change, what limits the lesson's applicability). + +**When the format does not fit.** When the case is too thin to support 2,000+ words of specificity, write a short customer story instead. When the case is so confidential that real numbers cannot be shared, the case study format is the wrong choice. + +--- + +## Whitepaper + +**Reader contract.** "Take me through your reasoning on this question with the rigor I would expect from a serious source. Make an argument I have not seen elsewhere." + +**Length norm.** 3,000 to 8,000 words. + +**Structural archetype tendency.** Layered argument or comparative analysis. + +**Format-specific tax.** Original synthesis. A whitepaper that surveys what other sources already said is not a whitepaper; it is a literature review. The whitepaper format implies the writer is contributing analysis, framing, or synthesis the reader cannot find elsewhere. + +**Common failures.** Survey of the field with no original argument; vendor-thinly-disguised pitch document; methodological hand-waving on the data the argument rests on; conclusion that hedges the position the introduction stated. + +**When the format does not fit.** When the writer does not have an original synthesis to contribute, write a different format. A survey-style "state of the industry" report is a research report, not a whitepaper. A vendor pitch is a pitch deck, not a whitepaper. Calling either a whitepaper to borrow the format's authority is the genre-mismatch failure mode. + +--- + +## Research report + +**Reader contract.** "Show me the data, how you collected it, what it means." + +**Length norm.** 4,000 to 12,000 words. Often longer when methodology and full data appendices are included. + +**Structural archetype tendency.** Taxonomic survey or comparative analysis. + +**Format-specific tax.** Actual primary research. Survey data with disclosed methodology, sample sizes, dates, and limits. Interview data with sample composition disclosed. Original quantitative work the writer did or commissioned. Citing other firms' research and calling the result a research report fails the contract. + +**Common failures.** "We surveyed 300 marketers" with leading questions and no methodology disclosure; cherry-picked data points presented without distribution or variance; methodology paragraph that gestures at rigor without delivering it; findings overstated relative to the sample's actual representativeness. + +**When the format does not fit.** When primary research budget is unavailable. Calling a literature synthesis a research report is genre fraud; write a whitepaper or a definitive guide instead. + +--- + +## Definitive guide + +**Reader contract.** "Be the canonical resource on this topic for the audience the piece names." + +**Length norm.** 4,000 to 10,000 words. + +**Structural archetype tendency.** Taxonomic survey. + +**Format-specific tax.** Actual comprehensiveness. A definitive guide that has obvious topic gaps fails the format. The audience the piece names matters: a definitive guide for senior practitioners and a definitive guide for newcomers are different pieces; trying to be definitive for both audiences usually fails both. + +**Common failures.** Comprehensive on the easy parts of the topic, thin on the hard parts; outdated when published because the format suggests timeless authority but the topic moves quickly; not actually definitive because key sub-topics are missing or treated as out-of-scope without justification. + +**When the format does not fit.** When the topic is too broad for a single piece to cover canonically (then write a hub: see `pillar-content-architecture`). When the topic is so specialized that "definitive" is a category of one and the format's value disappears. + +--- + +## Manifesto + +**Reader contract.** "Tell me what you believe, why, and convince me. Take a position I can argue with." + +**Length norm.** 1,500 to 6,000 words. + +**Structural archetype tendency.** Layered argument or narrative arc. + +**Format-specific tax.** Conviction. The manifesto format demands the writer commit a position with weight. Diplomatic hedging produces a piece that reads as a manifesto in form but a position paper in substance. Readers detect the gap. + +**Common failures.** "Both sides have valid points" framings that the manifesto format does not support; hedge-stacked claims ("typically", "generally", "often") on positions that should be specific; closing that walks back the opening's strength; fear of alienating audience segments producing a piece that alienates everyone by committing to nothing. + +**When the format does not fit.** When the writer does not actually have a contested position to argue. Calling a survey of consensus views a manifesto is a category error. Write a whitepaper or a position paper if hedging is required. + +--- + +## Ebook + +**Reader contract.** "Take me through a body of work as a sequence of related pieces." + +**Length norm.** 8,000 to 30,000+ words across multiple chapters. + +**Structural archetype tendency.** Narrative arc across chapters, with each chapter using its own archetype. + +**Format-specific tax.** Each chapter earns its place. A 12-chapter ebook with 3 chapters that should have been cut signals the format was reached for to add length, not because the work justified the format. Table of contents reading reveals the discipline: are the chapters distinct contributions, or is the ebook one argument padded into 12 pieces? + +**Common failures.** Repetitive chapters covering the same ground from slightly different angles; introduction and conclusion that are throat-clearing rather than load-bearing; missing connective tissue between chapters that leaves the reader uncertain how the chapters fit; no reason for the work to be an ebook rather than a long-form whitepaper. + +**When the format does not fit.** When the work fits in 6,000 words. Stretching a long-form whitepaper to ebook length usually weakens it. Write the long-form whitepaper. + +--- + +## Long-form tutorial + +**Reader contract.** "Take me from where I am to where I want to be, step by step, and make sure every step works." + +**Length norm.** 3,000 to 8,000 words. + +**Structural archetype tendency.** Problem-solution with sequential steps. + +**Format-specific tax.** Every step works. Long-form tutorials fail catastrophically when one step is broken: the reader stops there, cannot continue, and the rest of the tutorial is wasted. The tutorial-tax is verification that each step in the sequence delivers the result the next step assumes. + +**Common failures.** Skipped steps that were obvious to the writer but blocking to the reader; outdated steps that worked when written but no longer (especially common with tutorials referencing fast-moving tools); broken sequences where step 6 assumes a configuration step 4 did not actually create. + +**When the format does not fit.** When the topic does not have a clean sequential path. Branching tutorials where the path varies by reader context are usually better as a hub of shorter pieces (see `pillar-content-architecture`) than as one long-form tutorial trying to handle every branch. + +--- + +## The format-fit decision + +A short framework for choosing. + +1. **What is the reader contract?** What is the reader investing 30+ minutes to get? Specifics (case study)? Original analysis (whitepaper)? Original data (research report)? Comprehensive coverage (definitive guide)? Conviction (manifesto)? A body of work (ebook)? Sequential instruction (long-form tutorial)? +2. **Can the team pay the format-specific tax?** If the format demands specifics and the case is too confidential to share specifics, the format does not fit. If the format demands conviction and the writer wants to hedge, the format does not fit. +3. **Is there an original contribution?** Whitepapers, manifestos, and research reports particularly require original contribution. Definitive guides and tutorials can be valuable as comprehensive synthesis without original argument. +4. **Does the audience expect this format?** Some audiences expect whitepapers (B2B technical), some manifestos (founder-led brands), some research reports (analyst-influenced markets). Format choice signals genre-fit to the audience. +5. **Is the production capacity available?** Long-form tutorials with verified sequential steps cost meaningful verification time. Research reports cost primary-research budget. Format choice must match capacity, or the format-tax goes unpaid and the piece reads as the format-it-pretended-to-be. + +--- + +## Methodology-level choices that stay in the public skill + +The seven format definitions and their reader contracts. The format-specific taxes that distinguish credible work from filler dressed in the format. The decision framework that matches format to work. The genre-mismatch failure modes. The when-the-format-does-not-fit handling. + +## Implementation choices that stay internal + +Specific case study templates the team uses. Specific whitepaper layouts in the brand's design system. Specific research-report data presentation conventions matching the team's design tokens. Specific PDF production tooling. Specific gating workflow integrations with the team's marketing automation. Specific tutorial step-verification scripts that match the stack the tutorials cover. These vary by team, brand, and tooling; methodology applies regardless. diff --git a/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md b/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md new file mode 100644 index 0000000..0e357f1 --- /dev/null +++ b/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md @@ -0,0 +1,148 @@ +# Lede patterns for long-form + +Five patterns that work, four that fail, and the underlying frame: the first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. + +Long-form ledes do different work than blog-post ledes. A blog-post lede answers the user's likely query in the first 200 words for SEO. A long-form lede earns attention for the time investment ahead. Both can be true at once (an SEO-driven long-form piece needs to do both), but the long-form discipline is the harder of the two: the lede that answers a query in 200 words is not necessarily the lede that earns 30 minutes of reader attention. + +--- + +## The underlying frame + +Treat the first 150-250 words of a long-form piece as the writer's pitch to the reader. The reader is deciding, paragraph by paragraph, whether the time investment is going to be worth it. The lede has to: + +- Establish that the writer has something specific to say (not a survey). +- Set the thesis or central question the body will deliver. +- Earn enough attention to get the reader past the first H2. + +If the lede does not do these three things, readers leave at the first H2 boundary, before the body has a chance to deliver. + +--- + +## Pattern 1: The contested-claim opener + +**Shape.** A surprising or contested position stated cleanly, then the rest of the piece argues for it. + +**Fits.** Manifestos. Opinionated whitepapers. Position pieces. Long-form analysis where the writer has a specific view. + +**Example shape.** "Most teams treating content marketing as a volume problem will continue to underperform their budget through the end of the decade. The discipline that produces durable content programs is the one most teams skip: deciding what NOT to publish." + +**Why it works.** The reader's response is "wait, why?" The piece exists to answer that. The contested claim earns the reader's attention because the reader is now invested in seeing whether the argument holds. + +**The discipline.** The contested claim must actually be defensible across the piece. Lede claims that the body fails to support produce broken contracts; readers feel deceived. + +--- + +## Pattern 2: The problem-with-stakes opener + +**Shape.** A problem stated with the stakes made tangible. The reader sees themselves or their situation in the problem and wants the solution. + +**Fits.** Case studies. Problem-solution pieces. Long-form tutorials. Manifestos with a clear opposition. + +**Example shape.** "Three months after the migration, organic traffic was down 38%, the team had spent four hundred hours on the project, and nobody could explain where the loss was coming from. The migration had been planned for six months. Every checklist item had been completed. And the search-console graph was still pointing the wrong direction." + +**Why it works.** Stakes ground the abstract. The reader feels the problem before reading any solution, which earns attention for the solution that follows. + +**The discipline.** The stakes must be real, not invented for dramatic effect. Inflated stakes ("the future of marketing is at stake") read as filler. Specific stakes ("the migration cost $400K and three quarters of trust with the executive team") read as honest. + +--- + +## Pattern 3: The data-anomaly opener + +**Shape.** A piece of data that does not fit the consensus, framed as the question the piece will answer. + +**Fits.** Research reports. Analytical whitepapers. Evidence-driven long-form. + +**Example shape.** "The median programmatic SEO program in 2025 generated more than 80% of its traffic from fewer than 5% of its pages. The pattern held across e-commerce, B2B SaaS, marketplaces, and travel. This piece is about why." + +**Why it works.** The data point creates a specific question. The reader wants the answer. The body's job is to deliver the answer with the analytical depth the question deserves. + +**The discipline.** The data point must be load-bearing. If the body's argument does not actually flow from the opening data, the lede was decoration rather than scaffolding. + +--- + +## Pattern 4: The scene opener + +**Shape.** A specific moment, person, or scene that grounds the abstract topic. The reader enters the piece through a concrete situation, and the abstract argument follows. + +**Fits.** Narrative-arc pieces. Magazine-style longform. Pieces where human stakes are part of the argument. Some manifestos. + +**Example shape.** "On a Tuesday morning in September 2024, two engineers stood in front of a whiteboard covered in arrows and tried to explain to the new VP what the data pipeline actually did. The VP had been at the company three weeks. The whiteboard had been there four years. Neither of them could finish a sentence without contradicting the other." + +**Why it works.** Specific scenes hold attention. Readers complete narrative-arc pieces at higher rates than other archetypes; the scene opener uses that pull from the first paragraph. + +**The discipline.** The scene must connect to the piece's argument. Scene openers that are decorative ("imagine you are a marketer in 2026...") rather than load-bearing waste reader attention on prelude. + +--- + +## Pattern 5: The orientation opener + +**Shape.** What this piece covers, who it is for, what reading it costs and what it delivers. Orientation, not throat-clearing. + +**Fits.** Definitive guides. Long-form tutorials. Reference-type long-form where the reader's first question is "is this the right resource for me." + +**Example shape.** "This guide is for engineering leaders deciding whether to migrate from a service mesh to a sidecar-less alternative. It assumes familiarity with Kubernetes and basic mesh concepts. Reading it costs about 30 minutes. It will not cover the original arguments for adopting a mesh; that is a different question. It will cover the migration decision: when it makes sense, what to expect, what fails." + +**Why it works.** Reference-type readers self-select on relevance. The orientation opener saves the wrong reader's time and earns the right reader's attention. Pieces that the right reader does not finish often fail because the wrong readers came in and the right readers left. + +**The discipline.** The orientation must be honest. Guides that overpromise relevance ("for anyone interested in cloud infrastructure") draw wrong readers; guides that underpromise lose right readers. + +--- + +## Failure 1: The throat-clear opener + +**Shape.** "Content marketing has changed dramatically over the past decade. In this article, we will explore how to..." + +**Why it fails.** Filler signal. The reader knows the piece is about content marketing because of the title; restating it wastes attention. The "in this article we will explore" frame is a tour, not an argument; readers respond to arguments more than to tours. + +**The cure.** Cut the throat-clear paragraphs entirely. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clear draft. + +--- + +## Failure 2: The dictionary-definition opener + +**Shape.** "According to Merriam-Webster, X is defined as..." + +**Why it fails.** Signals an unwillingness to commit a position. The reader assumes the writer does not have a specific framing of their own and is hiding behind the dictionary's framing. For long-form, this is fatal: long-form earns reader attention through specific framing. + +**The cure.** State the writer's framing. If the writer needs to disambiguate the term, do so in their own words after stating their position. + +--- + +## Failure 3: The history-of-the-topic opener + +**Shape.** Three or four paragraphs of background before the argument starts. + +**Why it fails.** Long-form readers tolerate background but only after they know why they should care. Front-loading background means the reader leaves before the thesis lands. The history-of-the-topic opener typically reflects the writer's research process leaking into the piece structure: the writer learned the history while researching, so they put it first, even though the reader does not need it first. + +**The cure.** Move history into the body where it supports specific claims. Lead with the thesis or the question the piece answers. + +--- + +## Failure 4: The "in this article we will discuss" tour opener + +**Shape.** "In this article, we will discuss A, then B, then C, then D, then conclude with E." + +**Why it fails.** Flattens the piece into an outline before the writer has earned attention. Tours signal a writer who is not confident the body will hold the reader, so they preview it. The preview itself is what loses the reader: outlines are less interesting than the argument they describe. + +**The cure.** Trust the body to deliver. If the piece needs a navigation aid, use a table of contents or jump links, not an opening tour. + +--- + +## The lede audit + +A short framework for auditing a draft lede. + +1. **Does the first paragraph establish a specific position, problem, data point, scene, or orientation?** If it does general throat-clearing instead, cut. +2. **By the end of the first 250 words, has the thesis or central question of the piece been stated?** If not, the lede is too long. +3. **Does the lede earn the reader's next 30 minutes?** Read the lede as a stranger to the topic. Would you keep reading? If you would skim, the lede is filler. +4. **Does the body deliver on the lede's promise?** Some failed ledes are technically fine but make promises the body does not keep. The audit happens after the body is drafted: does the lede's framing match what the piece actually argues? + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns and the four failures, the underlying frame, the lede audit, the format-tendency mapping, and the lede-body integrity discipline. + +## Implementation choices that stay internal + +Specific lede templates the team has built. Specific draft-review tooling that flags throat-clearing language patterns automatically. Specific A/B testing of lede variants against engagement metrics. The team's own conventions for lede-length norms within the bands. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/section-weight-calibration.md b/skills/long-form-content-frameworks/references/section-weight-calibration.md new file mode 100644 index 0000000..9a95f94 --- /dev/null +++ b/skills/long-form-content-frameworks/references/section-weight-calibration.md @@ -0,0 +1,128 @@ +# Section weight calibration + +How long sections should be relative to each other, varying by format. The audit pattern that catches structural imbalance, and the underlying principle that section weight should match argumentative load. + +Most long-form pieces fail at section weight before they fail at any other dimension. A 6,000-word whitepaper with seven sections of similar length signals that the writer treated each H2 as a quota rather than as an argument-bearing unit. The pieces that read as publication-quality are the ones where some sections breathe and others compress, where argumentative load is reflected in word count, and where filler sections were cut rather than evened out. + +--- + +## The underlying principle + +Section weight should match how much argumentative load the section is bearing. + +Throat-clearing introductions get cut or compressed. Setup sections that orient the reader without making the argument yet are short. Body sections that are doing the actual work of the piece are longest. Closings are specific and tight. When section weights deviate from this, the piece is either padded (sections doing too little for their length) or under-developed (sections doing too much for their length). + +The audit is straightforward. For each section, ask: what argumentative work is this section doing, and is the word count proportional to that work? Sections doing little work that take up much space are filler. Sections doing much work that take up little space are under-developed. + +--- + +## Whitepaper / research report typical weights + +For a 5,000-word whitepaper or research report. + +- **Introduction.** 8-12%. Roughly 400-600 words. Thesis stated, scope set, why the piece exists. +- **Methodology or framing.** 10-15%. Roughly 500-750 words. How the analysis works, what data the argument rests on, what the reader should know about how the writer arrived at the position. +- **Body.** 60-70%. Roughly 3,000-3,500 words. Divided into 3-5 weighted sections. The actual argument or findings. The largest body sections are the load-bearing ones; smaller body sections support or transition. +- **Implications.** 10-15%. Roughly 500-750 words. What the argument means for the reader's situation. +- **Closing.** 3-5%. Roughly 150-250 words. Specific call, reframed thesis, or open question. + +--- + +## Case study typical weights + +For a 3,000-word case study. + +- **Setup and context.** 15-20%. Roughly 450-600 words. The company, the problem, why the problem mattered, what was at stake. +- **Solution narrative.** 50-60%. Roughly 1,500-1,800 words. What the team did, in sequence, with the decision points that mattered. +- **Outcomes.** 15-20%. Roughly 450-600 words. Quantified results, what worked beyond expectations, what did not work as planned. +- **Reflection.** 5-10%. Roughly 150-300 words. What the team would change, what limits the case's applicability. + +The case-study weight discipline. The setup and the outcomes can be roughly even; the solution narrative is the longest section because it is doing the most work; the reflection is short because it is concentrated honest assessment. + +--- + +## Manifesto typical weights + +For a 3,500-word manifesto. + +- **Position.** 5-10%. Roughly 175-350 words. What is believed, stated early and clearly. Manifestos that bury the position lose readers before the argument starts. +- **Argument.** 70-80%. Roughly 2,450-2,800 words. Why, with the layers building intensity. The argument's later layers should be more intense, more specific, or more confrontational than the earlier layers; intensity that flattens loses momentum. +- **Call.** 10-15%. Roughly 350-525 words. What should change as a result of accepting the position, who should change it, what the writer asks of the reader. + +The manifesto weight discipline. Position is short and load-bearing. Argument is long and intensifies. Call is specific and demands action or position-taking from the reader. + +--- + +## Definitive guide typical weights + +For a 7,000-word definitive guide. + +- **Introduction.** 5-8%. Roughly 350-560 words. What the guide covers, who it serves, what reading it costs and pays. +- **Body across taxonomic sections.** 80-85%. Roughly 5,600-5,950 words. Each category in the taxonomy treated with parallel structure. The categories should be roughly even in length unless the taxonomy itself implies asymmetry (some categories are more important than others). +- **Closing and additional resources.** 7-10%. Roughly 490-700 words. Synthesis, recommendation about which categories matter most, pointers to next steps. + +The definitive-guide weight discipline. Most of the weight is in the body categories. The introduction is short because the guide's value is in the taxonomy treatment, not in extended setup. The closing's value is synthesis, not recap. + +--- + +## Long-form tutorial typical weights + +For a 5,000-word long-form tutorial. + +- **Setup.** 10-15%. Roughly 500-750 words. What the reader will achieve, what they need to start, what the success state looks like. +- **Sequential steps.** 70-80%. Roughly 3,500-4,000 words. Each step its own subsection. Steps doing more work get more words; trivial steps stay short. The temptation to even out step lengths produces tutorials that feel padded on simple steps and rushed on hard ones. +- **Troubleshooting and edge cases.** 10-15%. Roughly 500-750 words. What goes wrong, what to do about it, when the reader has likely diverged from the success path. + +The tutorial weight discipline. Steps are weighted by actual difficulty, not by parallel structure. The troubleshooting section is load-bearing because tutorials fail at the failure-points; documenting them is the difference between a tutorial that works and one that strands readers. + +--- + +## Ebook typical weights + +For a 20,000-word ebook with 8 chapters. + +- **Introduction.** 3-5%. Roughly 600-1,000 words. Why the ebook exists, who it serves, how the chapters fit together. +- **Each chapter.** 10-13%. Roughly 2,000-2,600 words per chapter. Chapter weights can vary; a load-bearing chapter at the center may run 3,500 words while a transitional chapter runs 1,500. The variation should reflect actual content load, not arbitrary balancing. +- **Closing chapter or synthesis.** 5-8%. Roughly 1,000-1,600 words. What the body of work amounts to. + +The ebook weight discipline. Chapter weights match chapter load; introduction and closing earn their place by doing connective work the body chapters cannot. + +--- + +## The 3x audit + +A practical heuristic for catching section-weight problems. + +Compare any two sections bearing similar argumentative load. If one is more than 3x the length of the other, the piece is structurally unbalanced. Three responses: + +1. **Split the long section.** If the long section is genuinely doing 3x the work, it is probably actually two or three sections that should be separated for the reader's navigation. +2. **Deepen the short section.** If the long section's length is correct, the short section is probably under-developed and the argument it is making is being skipped. +3. **Acknowledge the imbalance.** If the asymmetry reflects an actual content reality (one category in the taxonomy genuinely matters 3x as much as another), the piece can keep the imbalance but should signal it to the reader so the structure does not feel arbitrary. + +--- + +## Common section-weight failures + +Patterns that show up repeatedly in long-form drafts. + +**Even-section padding.** All H2s come out within 10% of each other in word count. Signal: writer is treating section length as a quota. Cure: identify which sections are actually load-bearing and let them grow while cutting the filler ones back. + +**Front-loaded setup.** Introduction is 25% of the piece. Signal: writer was not confident enough in the thesis to commit it early; spent the first quarter of the piece warming up. Cure: cut the introduction by half, lead with the thesis. + +**Body imbalance.** One body section is 50% of the piece while three others are 10% each. Signal: either the long section is actually multiple sections that should be separated, or the short sections are filler that should be cut. + +**Missing closing.** Closing is 1-2% of the piece. Signal: writer ran out of energy. Cure: rewrite the closing to actual proportional weight; specific call, reframed thesis, or open question. + +**Throat-clearing across sections.** Each section starts with 100-200 words of "as we discussed in the previous section" before getting to the section's actual work. Signal: writer is over-managing reader navigation. Cure: trust the reader; cut the recap paragraphs. + +**Bullet inflation.** A section's word count comes mostly from bulleted lists where each bullet is one expanded sentence. Signal: writer is using bullets to inflate length without doing the integration work. Cure: rewrite the bullets as prose if the integration matters; cut to a tighter list if the items are genuinely parallel. + +--- + +## Methodology-level choices that stay in the public skill + +The underlying principle (weight matches argumentative load), the format-specific weight profiles, the 3x audit, the common section-weight failure patterns and their cures. + +## Implementation choices that stay internal + +Specific word-count tracking tools the team uses to audit drafts. Specific outline templates with weight targets per section in the team's writing system. Specific reviewer dashboards that surface section-weight imbalance for editorial review. The team's own conventions for which formats run shorter or longer than the typical bands. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/structural-archetype-patterns.md b/skills/long-form-content-frameworks/references/structural-archetype-patterns.md new file mode 100644 index 0000000..1e56d54 --- /dev/null +++ b/skills/long-form-content-frameworks/references/structural-archetype-patterns.md @@ -0,0 +1,145 @@ +# Structural archetype patterns + +Five archetypes that fit different long-form problems, with worked examples and the patterns for combining archetypes within a single piece. + +The archetype is the spine of a long-form piece. It determines how the argument unfolds, how the reader's attention is structured, and which structural moves feel natural versus which would jar. Selecting the wrong archetype produces a piece that fights itself: the writer trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. + +--- + +## Archetype 1: Problem-solution + +**Shape.** State the problem with weight. Develop why it matters and who is affected. Present the solution. Show how it works in detail. Address objections. Close with implications. + +**Fits.** Case studies. Long-form tutorials. Manifestos with a clear opposition. Pieces where the writer has a specific recommendation and a specific framing of what the recommendation answers. + +**Worked example: a 3,500-word case study.** + +- Setup: the company, the problem, why the problem mattered (15-20% of the piece). +- The solution narrative: what the team did, in sequence, with the decision points that mattered (50-60%). +- Outcomes: quantified results, what worked beyond expectations, what did not work as planned (15-20%). +- Reflection: what the team would change, what limits the case's applicability (5-10%). + +**Strengths.** Direct, action-oriented, satisfies readers looking for "show me how to solve this." Clear forward momentum prevents reader drift. + +**Risks.** Feels formulaic when overused (every case study reading the same shape). Tempts oversimplification: real situations rarely fit a clean problem-solution arc, and forcing them to flattens the case's interest. + +--- + +## Archetype 2: Narrative arc + +**Shape.** Beginning establishing characters and stakes. Middle developing complications. End resolving (or refusing to resolve) the central tension. Time progresses; events follow each other. + +**Fits.** Ebooks across chapters. Some case studies, particularly founder stories, transformation cases, multi-year initiatives. Magazine-style longform. Manifestos where the writer's own journey is part of the argument. + +**Worked example: a 6,000-word transformation case study.** + +- Opening: a specific scene that grounds the abstract topic (the Monday-morning meeting where the problem became inescapable). +- Rising action: the situation getting worse before it gets better, the failed attempts, the false starts. +- Turning point: the specific decision or insight that shifted the trajectory. +- Resolution: what the new state looks like, what the team learned, what is still in progress. +- Coda: the writer's broader observation about what the story illustrates. + +**Strengths.** Most engaging archetype for sustained attention. Readers complete narrative-arc pieces at higher rates than other archetypes. Memorable; readers tell other readers. + +**Risks.** Forced narrative on topics that are not stories. A whitepaper trying to be a narrative arc usually fails because the topic does not naturally have characters, complication, and resolution. The forcing is detectable. + +--- + +## Archetype 3: Layered argument + +**Shape.** Position stated. Layer 1 evidence supporting the position. Layer 2 evidence, often deeper or addressing a different aspect. Layer 3, often counter-arguments or caveats. Synthesis tying the layers together. + +**Fits.** Whitepapers. Manifestos. Position pieces. Analytical long-form. Pieces where the writer is making a case that requires building support across multiple distinct kinds of evidence. + +**Worked example: a 5,000-word whitepaper.** + +- Position: the central claim, stated cleanly in the first 200 words (10%). +- Layer 1: the structural argument (why the position follows from how the system works). 25%. +- Layer 2: the empirical argument (what data supports the position). 25%. +- Layer 3: counter-arguments engaged seriously and answered. 20%. +- Synthesis: what the layers together imply, including implications the position-statement alone did not surface. 15%. +- Closing: specific call or reframed thesis. 5%. + +**Strengths.** Rigorous, defensible, persuasive to skeptical readers. Readers engaging seriously with the position find their objections engaged in the counter-argument layer. + +**Risks.** Feels academic if the synthesis is weak. Layers that do not actually build to a synthesis read as three separate articles stacked. The audit: cut one layer; does the synthesis still work? If yes, that layer was filler. + +--- + +## Archetype 4: Taxonomic survey + +**Shape.** A topic mapped into categories. Each category explored. Relationships among categories surfaced. Sometimes a recommendation about which categories matter most, often a synthesis about what the taxonomy reveals. + +**Fits.** Definitive guides. Research reports surveying a landscape. Long-form tutorials covering a topic with parallel rather than sequential structure. Comparative pieces. + +**Worked example: a 7,000-word definitive guide.** + +- Introduction: what the guide covers, who it serves, what reading it costs and pays (5-8%). +- Taxonomy framing: how the topic divides, why these categories rather than other possible categories (8-12%). +- Category 1, 2, 3, 4 (etc.): each treated with parallel structure (definition, examples, when-it-fits, how-it-works) so readers can navigate. 70-75% across all categories. +- Synthesis: what the taxonomy reveals about the topic as a whole; which categories the writer thinks matter most and why. 7-10%. +- Closing: what to do with the taxonomy. 3-5%. + +**Strengths.** Reference-friendly. Readers come back to taxonomic surveys multiple times to look up specific categories. SEO-friendly because each category often answers a discrete query. + +**Risks.** Feels like a list with subheads if the taxonomy is not actually load-bearing. The audit: does the taxonomy reveal something that a list of items would not? If no, the piece is a list pretending to be a taxonomy. + +--- + +## Archetype 5: Comparative analysis + +**Shape.** Multiple options, frameworks, or positions. Defined axes of comparison. Each option scored or characterized along each axis. Tradeoffs surfaced. The writer's recommendation argued. + +**Fits.** Whitepapers comparing approaches. Decision-guide research reports. Technology comparisons. Evaluations. Pieces where the reader's question is "which of these should I choose." + +**Worked example: a 4,500-word technology comparison.** + +- Setup: the decision the reader is making, why it matters, who this comparison serves (8-10%). +- Comparison axes: the dimensions the writer chose to compare on, with justification for why these axes (5-8%). +- Each option treated along the axes: parallel structure so readers can compare at-a-glance. 50-60%. +- Tradeoff synthesis: what the comparison reveals about which option fits which context. 15-20%. +- Recommendation: the writer's view, with the conditions under which the recommendation holds. 8-10%. +- Closing: how to decide. 3-5%. + +**Strengths.** Decision-useful. Readers facing the decision the comparison addresses get clear input. Pairs well with comparison tables and side-by-side data. + +**Risks.** Feels like a feature matrix if the analysis is shallow. The axes matter: shallow axes (price, speed, ease) produce shallow analysis. Deep axes (failure modes under load, what the platform optimizes for, what the platform forces you to give up) produce useful comparison. + +--- + +## Combination patterns + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. + +**Layered argument with comparative-analysis sections.** A whitepaper arguing a position with a comparative-analysis section showing how the position handles edge cases that competing positions do not. + +**Taxonomic survey with problem-solution chapters.** A definitive guide where each category in the taxonomy includes a problem-solution treatment of how to apply it. + +**Narrative arc with layered-argument moments.** An ebook where the narrative carries the reader through a transformation while individual chapters argue for specific positions encountered along the way. + +**Problem-solution with taxonomic-survey frame.** A long-form tutorial that introduces a taxonomy of failure modes and then walks through the solution sequentially. + +**Comparative analysis with case-study illustration.** A whitepaper comparing approaches with a case study embedded for one of the approaches to ground the analysis. + +The discipline. One archetype as spine; another as variation. Pieces using three archetypes simultaneously fragment; pieces using one archetype rigidly feel formulaic. + +--- + +## Selecting the archetype + +A short framework. + +1. **What is the reader's relationship to the question?** "Tell me how" suggests problem-solution. "Tell me what happened" suggests narrative arc. "Convince me" suggests layered argument. "Map the landscape" suggests taxonomic survey. "Help me decide" suggests comparative analysis. +2. **What does the topic naturally have?** Topics with a clear protagonist, complication, and resolution naturally fit narrative arc. Topics with parallel categories naturally fit taxonomic survey. Topics with a contested position naturally fit layered argument or manifesto-flavored layered argument. +3. **What does the format expect?** Case studies expect problem-solution or narrative arc; whitepapers expect layered argument or comparative analysis; definitive guides expect taxonomic survey. Format-archetype mismatch is detectable to readers even when they cannot articulate it. +4. **What is the writer's strength?** Different writers have different archetype strengths. A writer who naturally argues should not force themselves into narrative-arc longform; a writer who naturally narrates should not force themselves into taxonomic surveys. Assign archetype to writer skill where possible. + +--- + +## Methodology-level choices that stay in the public skill + +The five archetype shapes, the worked examples, the combination patterns, the selection framework, the format-archetype fit tendencies, the writer-skill matching consideration. + +## Implementation choices that stay internal + +Specific archetype templates the team has built for repeat formats. Specific section-length scaffolds the team uses. Specific document templates per archetype in the team's writing tool. Specific archetype tagging in the team's content calendar so editorial mix can be reviewed. The decision rubric the team uses for archetype assignment when multiple writers are working on the same format. These are team-specific operationalizations of the methodology. diff --git a/skills/media-asset-management/SKILL.md b/skills/media-asset-management/SKILL.md new file mode 100644 index 0000000..85511d5 --- /dev/null +++ b/skills/media-asset-management/SKILL.md @@ -0,0 +1,305 @@ +--- +name: media-asset-management +description: "Plan and run a media pipeline for images, video, and downloadable assets. Use this skill when designing image storage and delivery, choosing formats (WebP, AVIF), setting up responsive images, picking a video host, organizing a brand asset library, or auditing a slow image pipeline. Triggers on image pipeline, asset library, DAM, image optimization, WebP, AVIF, responsive images, video hosting, image CDN, asset workflow, media management. Also triggers when images are slow, broken, or scattered across systems." +category: operations +catalog_summary: "Image pipelines, video hosting, asset libraries, format selection" +display_order: 9 +--- + +# Media Asset Management + +Design how images, video, and downloadable files get stored, processed, organized, and served. Stack-agnostic. The principles apply whether you're running a custom pipeline or using a hosted service. + +--- + +## When to use + +- Designing or redesigning the image and media pipeline +- Choosing a media CDN or image service +- Setting up responsive image delivery +- Planning a digital asset management (DAM) system +- Auditing media performance issues +- Picking video hosting and embedding strategy +- Setting up workflows for designers and writers to upload assets +- Migrating media from one platform to another + +## When NOT to use + +- Performance optimization beyond media (use `performance-optimization`) +- Brand identity or photography direction (use `brand-identity`, `art-direction`) +- Content production strategy (use `content-strategy`) +- Single-image optimization (covered in `performance-optimization`) + +--- + +## Required inputs + +- Current media inventory: where assets live, in what formats +- Volume: how many assets, how much storage, how much traffic +- Sources: who creates and uploads media (designers, writers, automated tools) +- Platforms: where media is consumed (web, email, app, partners) +- Performance baseline: current image sizes, load times +- Budget reality: hosted services have monthly costs + +--- + +## The framework: 4 stages + +The media pipeline has four stages. Each has its own decisions. + +### Stage 1: Source + +Where assets enter the system. + +**Sources:** +- Designers (Figma exports, Photoshop, Illustrator) +- Photographers (RAW or JPEG from camera) +- Stock photo libraries +- AI-generated images +- User-generated content (uploads) +- Automated systems (e.g., screenshots, generated thumbnails) + +**At source, decide:** +- File formats accepted (RAW, TIFF, PSD, AI vs delivered formats) +- Naming conventions +- Required metadata (alt text, captions, credits, rights) +- Maximum source resolution (high enough to derive any size; not so high it's wasteful) +- Where source files live (separate from delivered assets) + +**Anti-pattern:** sources and delivered assets in the same place. Hard to find masters. Hard to regenerate. Hard to audit usage. + +### Stage 2: Process + +Transforming source files into delivery formats. + +**Processing decisions:** +- Resize to standard sizes (e.g., a fixed set of widths: 320, 640, 960, 1280, 1920, 2560) +- Compress (lossy or lossless, with quality targets) +- Convert formats (JPEG, WebP, AVIF for raster; SVG for vector) +- Generate thumbnails and previews +- Strip metadata (EXIF, GPS) unless intentionally retained +- Color profile management (sRGB for web) + +**Process options:** +- **Build-time:** Static assets processed during deploy. Predictable, fast at runtime, hard to vary. +- **On-demand:** A service generates the right format/size when requested. Flexible, requires a processing layer. +- **Hybrid:** Static processed sizes plus on-demand for edge cases. + +For sites with many image variants and ongoing change, on-demand wins. For tightly controlled marketing sites, build-time can be simpler. + +### Stage 3: Deliver + +Getting assets to users efficiently. + +**Delivery decisions:** +- CDN: required for any non-trivial volume. Edge caching, global distribution. +- Format negotiation: serve AVIF to browsers that support it, WebP otherwise, JPEG as fallback. Use the `<picture>` element or content negotiation. +- Responsive images: `srcset` and `sizes` attributes so browsers pick the right size for the viewport. +- Lazy loading: `loading="lazy"` for below-the-fold images. +- Async decoding: `decoding="async"` for non-critical images. +- Width and height attributes: always set, prevents layout shift. + +**Modern HTML pattern:** + +```html +<img + src="/image-1280.jpg" + srcset="/image-640.jpg 640w, /image-960.jpg 960w, /image-1280.jpg 1280w, /image-1920.jpg 1920w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +Or for format negotiation: + +```html +<picture> + <source type="image/avif" srcset="/image.avif"> + <source type="image/webp" srcset="/image.webp"> + <img src="/image.jpg" alt="Descriptive alt text" width="1280" height="720"> +</picture> +``` + +### Stage 4: Manage + +Keeping the system organized and useful over time. + +**Management decisions:** +- Asset library or DAM (digital asset management): centralized place for the team to find assets +- Tagging and search +- Version control (designers updating an asset, old version still in use) +- Rights and licensing tracking +- Audit and cleanup (what's not used anymore?) +- Permissions (who can upload, edit, delete) + +A simple shared folder works at low scale. A real DAM is necessary above a few thousand assets or with multiple teams. + +--- + +## Format reference + +For typical web use: + +| Format | Use for | Avoid for | +|---|---|---| +| AVIF | Photographs, complex images. Best compression. | Browser support edge cases (rare in 2026, ubiquitous now) | +| WebP | Photographs, illustrations. Good compression. Wide support. | Print, archival | +| JPEG | Photographs (fallback). Universal support. | Sharp-edged graphics, transparent backgrounds | +| PNG | Sharp-edged graphics, transparent backgrounds, screenshots. Lossless. | Photographs (file size) | +| SVG | Logos, icons, simple illustrations. Scalable. | Photographs, complex art | +| GIF | Effectively obsolete. Use video formats for animation. | Anything modern | +| MP4 (H.264) | Video, universal support. | Static content | +| WebM (VP9 / AV1) | Video, better compression. | Older browsers | + +For most sites: serve AVIF/WebP for modern browsers, JPEG/PNG fallback. SVG for vector. MP4 for video. + +--- + +## Workflow + +### Step 1: Inventory + +What assets exist? Where? In what state? + +- Image count and total storage +- Average sizes (KB) per format +- Image-related performance metrics +- Number of pages with broken or missing images +- Source files vs delivered files + +### Step 2: Audit performance + +For a sample of pages: +- Image weight per page (target: under 500KB total for marketing pages) +- Number of image requests +- Are responsive images used? +- Are modern formats served? +- Is there layout shift from missing dimensions? + +Tools: Lighthouse, WebPageTest, your CDN's analytics. + +### Step 3: Pick the pipeline + +Three reasonable patterns: + +**Pattern A: Static, build-time** +- Assets in repo or storage bucket +- Build process generates sizes and formats +- Served via CDN +- Good for: static sites, low asset churn, tight performance control + +**Pattern B: Image CDN with on-demand** +- Source uploads to a bucket or service +- An image CDN (Cloudinary, imgix, Cloudflare Images, Bunny, etc.) processes on-demand via URL parameters +- Good for: mid-to-large sites, frequent asset changes, multiple variants + +**Pattern C: Headless CMS with built-in image API** +- CMS holds source assets +- CMS provides image API for resizing, format conversion +- Good for: content-heavy sites, non-technical content uploaders, when CMS is already chosen + +The patterns aren't mutually exclusive. Big sites often use Pattern A for design assets, Pattern B for content images. + +### Step 4: Define standards + +Document: +- Naming conventions +- Required metadata (alt text, attribution) +- Maximum source dimensions +- Minimum source dimensions per use case +- Approved formats +- File size targets + +Make these enforceable through tooling where possible (CI checks on file sizes, alt text required by CMS). + +### Step 5: Set up workflows + +For each source type: + +| Source | Workflow | +|---|---| +| Designer | Export from Figma, drop into bucket, automated processing handles the rest | +| Writer | Upload through CMS, CMS prompts for alt text | +| Photographer | RAW into source bucket, designer or automation creates web variants | +| User upload | Pass through the image service, automatic moderation if applicable | + +Document who does what. Workflows that aren't documented break. + +### Step 6: Build the asset library + +For all but the smallest sites: +- Centralized DAM or shared library +- Tag taxonomy (subject, style, brand, campaign, etc.) +- Search across tags and metadata +- Documented rights for each asset (stock license, custom commission, work-for-hire, etc.) +- Sunset workflow (rights expire, asset retires) + +### Step 7: Monitor and audit + +- Performance metrics on image-heavy pages +- Storage costs +- CDN costs +- Broken image alerts (404 on referenced media) +- Unused asset cleanup (storage costs accumulate) + +### Step 8: Document the pipeline + +A pipeline document covers: +- Diagram of source → process → deliver → manage +- Tools used at each stage +- Standards and naming conventions +- Workflows for common cases +- Escalation when something breaks + +--- + +## Failure patterns + +**Source files in the delivery bucket.** 50MB RAW files served to users. Fix: separate sources from delivered. + +**Single image format for every browser.** JPEG-only when AVIF could be 30-50% smaller. Use format negotiation. + +**Missing width and height attributes.** Causes layout shift, hurts CLS metric. Set always. + +**Lazy loading hero images.** Above-the-fold images shouldn't be lazy-loaded. Lazy below the fold. + +**Eager loading everything.** All images load on page load. Use `loading="lazy"` for below-fold. + +**No responsive images.** Mobile gets the desktop image. Wasteful, slow. Use `srcset` and `sizes`. + +**One source resolution.** Source is the delivery resolution. Can't generate retina or larger. Source should be 2-3x the largest delivered size. + +**Stripping all metadata.** Removes alt text, removes attribution. Strip GPS and personal EXIF; keep semantic metadata. + +**Random naming.** `IMG_4823.jpg`, `Screenshot 2024-03-15.png`. Hard to find later. Use a naming convention. + +**No alt text.** Accessibility failure, SEO failure. Make alt text required at upload. + +**Storage growing unbounded.** Old, unused assets pile up. Quarterly cleanup or automated lifecycle policies. + +**One person knows the pipeline.** When they're out, no one can fix issues or onboard new sources. Document. + +--- + +## Output format + +A media pipeline document includes: + +- **Inventory:** current asset count, formats, storage +- **Pipeline diagram:** source → process → deliver → manage with tools at each stage +- **Format and size standards:** what gets generated, when +- **Naming and metadata conventions:** with examples +- **Workflows by source type:** designer, writer, photographer, user +- **Performance baseline and targets:** weight per page, format adoption, etc. +- **Asset library:** tool, taxonomy, search, rights tracking +- **Monitoring:** performance, costs, broken assets +- **Roadmap:** improvements over the next 1-2 quarters + +--- + +## Reference files + +- [`references/responsive-image-patterns.md`](references/responsive-image-patterns.md): Copy-paste HTML patterns for common responsive image scenarios (hero, content, art-directed, format negotiation), with explanations. diff --git a/skills/media-asset-management/references/responsive-image-patterns.md b/skills/media-asset-management/references/responsive-image-patterns.md new file mode 100644 index 0000000..721f670 --- /dev/null +++ b/skills/media-asset-management/references/responsive-image-patterns.md @@ -0,0 +1,373 @@ +# Responsive Image Patterns + +Copy-paste HTML patterns for common image scenarios. Each pattern is annotated with what it does and when to use it. + +The principles work across stacks. The HTML is the same whether you're in Next.js, WordPress, Webflow, or vanilla HTML. + +--- + +## Pattern 1: Simple responsive image + +The default for most content images. Same image at different sizes. + +```html +<img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w, + /img/photo-1920.jpg 1920w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +**What's happening:** +- `src`: fallback for browsers that don't support srcset (rare today, still good practice) +- `srcset`: list of available sizes with their widths +- `sizes`: tells the browser how wide the image will display at different viewport widths +- `width`/`height`: prevents layout shift; the browser reserves space before the image loads +- `loading="lazy"`: delays loading until near the viewport +- `decoding="async"`: doesn't block rendering on this image +- `alt`: accessibility and SEO + +**When to use:** Most content images, blog post bodies, article illustrations. + +--- + +## Pattern 2: Hero image (above the fold) + +The hero image needs special handling because it's critical to first paint. + +```html +<img + src="/img/hero-1920.jpg" + srcset=" + /img/hero-640.jpg 640w, + /img/hero-960.jpg 960w, + /img/hero-1280.jpg 1280w, + /img/hero-1920.jpg 1920w, + /img/hero-2560.jpg 2560w + " + sizes="100vw" + width="1920" + height="1080" + fetchpriority="high" + decoding="async" + alt="Descriptive alt text"> +``` + +**Differences from Pattern 1:** +- No `loading="lazy"` (hero must load immediately) +- `fetchpriority="high"` (hint to load this first) +- Larger size options for full-width displays +- `sizes="100vw"` (image takes full viewport width) + +Optionally preload the hero in the document head: + +```html +<link + rel="preload" + as="image" + href="/img/hero-1280.jpg" + imagesrcset="/img/hero-640.jpg 640w, /img/hero-960.jpg 960w, /img/hero-1280.jpg 1280w, /img/hero-1920.jpg 1920w, /img/hero-2560.jpg 2560w" + imagesizes="100vw"> +``` + +This tells the browser to start the request before HTML parsing reaches the `<img>`. + +**When to use:** The single hero or banner at the top of a page. Don't preload more than one image; it competes with critical resources. + +--- + +## Pattern 3: Format negotiation + +Serve modern formats to browsers that support them, fall back to JPEG. + +```html +<picture> + <source + type="image/avif" + srcset=" + /img/photo-640.avif 640w, + /img/photo-960.avif 960w, + /img/photo-1280.avif 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <source + type="image/webp" + srcset=" + /img/photo-640.webp 640w, + /img/photo-960.webp 960w, + /img/photo-1280.webp 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +**What's happening:** +- The browser tries each `<source>` in order +- The first one with a supported `type` is used +- The `<img>` is the fallback if no `<source>` matches +- The `<img>` also provides the alt text and dimensions for all formats + +**When to use:** Whenever your pipeline can produce multiple formats. AVIF is now well-supported; WebP is universal. JPEG is the safe fallback. + +**Easier alternative:** A modern image CDN can do format negotiation server-side based on the `Accept` header. The HTML stays as Pattern 1; the CDN serves the right format. Often the better approach. + +--- + +## Pattern 4: Art direction (different crops at different breakpoints) + +Sometimes you want a different image (not just a different size) on mobile vs desktop. + +```html +<picture> + <source + media="(max-width: 768px)" + srcset=" + /img/portrait-640.jpg 640w, + /img/portrait-960.jpg 960w + " + sizes="100vw"> + <source + media="(min-width: 769px)" + srcset=" + /img/landscape-1280.jpg 1280w, + /img/landscape-1920.jpg 1920w + " + sizes="100vw"> + <img + src="/img/landscape-1280.jpg" + width="1920" + height="1080" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +**What's happening:** +- On screens 768px wide or less, use the portrait crop +- On larger screens, use the landscape crop +- Different aspect ratios per device + +**When to use:** Marketing pages where the image composition matters at each breakpoint. Often for hero images of people or products. + +**Caution:** Set explicit dimensions to match each crop, or be careful about layout shift between crops. CSS aspect-ratio can help. + +--- + +## Pattern 5: Background images + +For decorative backgrounds set in CSS, use `image-set()` for responsive selection: + +```css +.hero { + background-image: image-set( + url('/img/hero-1280.jpg') 1x, + url('/img/hero-2560.jpg') 2x + ); +} +``` + +For format negotiation in CSS: + +```css +.hero { + background-image: image-set( + url('/img/hero.avif') type('image/avif'), + url('/img/hero.webp') type('image/webp'), + url('/img/hero.jpg') type('image/jpeg') + ); +} +``` + +**Note:** Background images are decorative. If the image carries meaning, it should be an `<img>` with alt text, not a CSS background. + +--- + +## Pattern 6: SVG (vectors) + +For logos, icons, simple illustrations: + +```html +<img + src="/img/logo.svg" + width="200" + height="40" + alt="Brand name"> +``` + +Or inline for icons (better for theming with CSS): + +```html +<svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true"> + <path d="..."/> +</svg> +``` + +**Notes:** +- SVG is resolution-independent. No `srcset` needed. +- For decorative icons, use `aria-hidden="true"`. For meaningful icons, provide a label. +- Inline SVG can be styled with CSS. Linked SVG cannot. + +--- + +## Pattern 7: Lazy-loaded video + +Treat video like a heavy image: + +```html +<video + width="1280" + height="720" + poster="/img/video-poster.jpg" + preload="metadata" + controls> + <source src="/video/clip.webm" type="video/webm"> + <source src="/video/clip.mp4" type="video/mp4"> + <track kind="captions" src="/video/clip-captions.vtt" srclang="en" label="English"> + Your browser does not support the video tag. +</video> +``` + +**Notes:** +- `poster`: image shown before play, sized to match video +- `preload="metadata"`: only loads enough to know duration, not the whole file +- `<track>`: captions for accessibility (always include for non-decorative video) +- Multiple `<source>`: browser picks the first supported format + +**For autoplay video** (decorative, no audio): + +```html +<video + autoplay + muted + loop + playsinline + poster="/img/poster.jpg" + preload="auto"> + <source src="/video/loop.mp4" type="video/mp4"> +</video> +``` + +`muted` and `playsinline` are required for autoplay on most browsers. Be cautious about autoplay; many users disable it or find it annoying. + +--- + +## Pattern 8: User-uploaded images + +For images uploaded by users (avatars, content), set defensive defaults: + +```html +<img + src="/uploads/avatar-medium.jpg" + width="200" + height="200" + loading="lazy" + decoding="async" + alt="" + onerror="this.style.display='none'"> +``` + +**Notes:** +- Process uploads through a moderation step before serving (especially for public sites) +- Generate consistent sizes (small, medium, large) +- Strip EXIF (GPS, etc.) for privacy +- Have a fallback (default avatar, broken image hidden) +- alt text from user-provided context where possible + +--- + +## Pattern 9: Image with caption + +Use `<figure>` for semantically grouped image and caption. + +```html +<figure> + <img + src="/img/photo-1280.jpg" + srcset="/img/photo-640.jpg 640w, /img/photo-960.jpg 960w, /img/photo-1280.jpg 1280w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> + <figcaption>Caption visible to all users.</figcaption> +</figure> +``` + +**Notes:** +- alt text describes the image for users who can't see it +- caption provides context for everyone +- They serve different purposes; both are useful when there's a caption + +--- + +## Anti-patterns + +**Lazy-loading the hero image.** Above-the-fold images should load immediately. + +**Missing width and height.** Causes layout shift. Always set. + +**Same image, different file extensions.** `image.jpg` and `image.JPG` for the same content. Pick one convention. + +**Tracking pixels masquerading as images.** Use proper analytics, not 1x1 GIFs. + +**Decorative images with descriptive alt text.** A decorative pattern with `alt="ornamental swirl background"` is noise for screen readers. Use `alt=""` for purely decorative. + +**Decorative images with no alt attribute at all.** Screen readers may announce the filename. Use `alt=""` (empty, not missing). + +**Inline base64 images for non-trivial sizes.** Bloats HTML. Use a URL. + +**Forgetting captions in non-English contexts.** Captions and alt text need translation just like any other content. + +--- + +## Alt text guidelines + +- **Decorative:** `alt=""` (empty) +- **Functional (e.g., a search button icon):** describes the action: `alt="Search"` +- **Informative:** describes the content the user is missing: `alt="Hand holding a coffee cup at a wooden desk"` +- **Complex (charts, infographics):** brief alt + a fuller description in nearby text or `aria-describedby` + +Alt text should: +- Convey what the image conveys, not what it depicts +- Be concise (typically under 125 characters) +- Not start with "Image of" or "Picture of" (screen readers say that already) +- Include important text that's part of the image + +--- + +## Tooling notes + +Most modern frameworks have an `<Image>` component that wraps these patterns. Examples include Next.js Image, Astro Image, Nuxt Image. They handle: + +- Format negotiation automatically +- Responsive sizes +- Lazy loading defaults +- Width/height enforcement + +If you're using a framework with such a component, prefer it over hand-rolling the HTML. The framework version usually includes optimizations the hand-rolled version misses. + +If you're not using a framework, the patterns here are the right baseline. diff --git a/skills/monitoring-and-alerting/SKILL.md b/skills/monitoring-and-alerting/SKILL.md new file mode 100644 index 0000000..971d963 --- /dev/null +++ b/skills/monitoring-and-alerting/SKILL.md @@ -0,0 +1,256 @@ +--- +name: monitoring-and-alerting +description: "Design and run a monitoring system for a website or web app. Use this skill when setting up uptime checks, defining SLOs, configuring error tracking, choosing what to alert on, designing on-call rotations, or fixing alert fatigue. Triggers on monitoring, alerts, uptime, SLO, SLA, error rate, on-call, pager, alert fatigue, observability, dashboards, what should we monitor. Also triggers when an incident reveals a gap in monitoring." +category: operations +catalog_summary: "SLO design, uptime checks, alert routing, on-call rotations" +display_order: 5 +--- + +# Monitoring and Alerting + +Decide what to watch, what to alert on, and how to make sure the right person finds out when things break. + +--- + +## When to use + +- Setting up monitoring on a new site or service +- Defining SLOs (service level objectives) and error budgets +- Choosing which alerts page someone vs which go to a quiet channel +- Designing or fixing on-call rotation +- Diagnosing alert fatigue +- Filling monitoring gaps revealed by an incident +- Migrating monitoring vendors + +## When NOT to use + +- Responding to an active incident (use `incident-response`) +- Writing the post-mortem (use `after-action-report`) +- Designing analytics dashboards for product metrics (use `analytics-strategy`) +- Performance optimization itself (use `performance-optimization`) + +--- + +## Required inputs + +- The system you're monitoring (URLs, services, dependencies) +- Existing monitoring tools (uptime, errors, logs, APM) +- Business hours and team timezone(s) +- Who is on-call or available for incidents +- Existing SLOs or success metrics, if any + +--- + +## The framework: 4 layers + +Monitoring works in layers. Skip a layer and you'll miss a class of problems. + +### Layer 1: Availability + +Is the site up? The simplest, most important layer. + +- HTTP checks from multiple regions (every 1-5 minutes) +- DNS resolution checks +- Certificate expiration checks +- Status code checks (alert on 5xx, not just timeout) + +Threshold: any sustained downtime (more than 2 consecutive failed checks) pages. + +### Layer 2: Correctness + +The site is up, but is it serving the right thing? + +- Synthetic checks (a script that loads the homepage, clicks a button, validates expected text) +- Critical user journeys (signup, checkout, search) +- Content presence checks (homepage hasn't gone blank) +- API contract checks (response shape and key fields are present) + +Threshold: failures of critical-path synthetics page. Non-critical page-level synthetics alert during business hours only. + +### Layer 3: Performance + +The site is up and correct, but is it fast enough? + +- Core Web Vitals (LCP, INP, CLS) from real users (RUM) +- Synthetic performance (Lighthouse, WebPageTest, custom) +- API response times (p50, p95, p99) +- Database query times for slow queries +- Dependency response times (third-party APIs) + +Threshold: regressions from baseline (e.g., p95 doubled in 5 minutes). Don't alert on absolute thresholds without baselines. + +### Layer 4: Errors and anomalies + +The site is up, correct, and fast for most, but errors are happening. + +- Error rate (% of requests returning 5xx) +- Client-side error rate (uncaught JS exceptions) +- Log error volume (unexpected spikes) +- Anomaly detection (traffic falling off a cliff) +- Background job failures +- Queue depth + +Threshold: rate-based, not count-based. "Error rate above 1% for 5 minutes" beats "more than 100 errors per minute." + +--- + +## SLOs and error budgets + +A Service Level Objective is the target for reliability. Common form: "99.9% of homepage requests succeed in under 2 seconds, measured over 30 days." + +The components: +- **The thing you're measuring** (homepage requests) +- **The success criterion** (returns 2xx in under 2 seconds) +- **The target** (99.9% of them) +- **The window** (over 30 days) + +The error budget is the inverse: 0.1% of requests can fail. If you've used the whole budget, slow down on risky changes. + +### Picking SLOs + +Don't aim for 100%. Don't aim for "five nines" (99.999%) unless you really need it. Each nine costs an order of magnitude more. + +| SLO | Allowed downtime per month | +|---|---| +| 99% | 7 hours, 18 minutes | +| 99.9% | 43 minutes | +| 99.95% | 21 minutes | +| 99.99% | 4 minutes, 22 seconds | +| 99.999% | 26 seconds | + +For most marketing sites, 99.9% is plenty. For SaaS, 99.95% is reasonable. Anything higher needs significant infrastructure investment. + +### Using error budgets + +When the budget is healthy, ship aggressively. When the budget is half-spent, slow down. When the budget is exhausted, freeze risky changes until reliability recovers. + +This is what makes SLOs useful: they create a feedback loop between reliability and velocity. + +--- + +## Workflow + +### Step 1: Inventory what's already monitored + +What tools are in place? What checks exist? What dashboards? What alerts? + +Many teams have a tangle of half-configured tools. The first job is the inventory. + +### Step 2: Map the system + +Draw the architecture. Front-end, back-end, database, third-party APIs, queues, workers. Each box is a candidate for monitoring. + +For each box, ask: +- What does "up" mean? +- What does "correct" mean? +- What does "fast" mean? +- What's the most common failure mode? + +### Step 3: Define the SLOs + +Pick 3-5 SLOs. They should be: +- Tied to user-visible behavior (not internal metrics) +- Achievable with current infrastructure +- Measured automatically +- Reviewed at least quarterly + +### Step 4: Set up checks across the 4 layers + +For each box, configure checks at each layer. Some boxes won't have all four; that's fine. + +| Box | Availability | Correctness | Performance | Errors | +|---|---|---|---|---| +| Homepage | HTTP check | Synthetic | LCP/INP | JS errors | +| Login API | HTTP check | Synthetic flow | p95 latency | 5xx rate | + +### Step 5: Decide what pages and what doesn't + +Three tiers: + +1. **Page (wakes someone up):** site down, critical flow broken, error rate spike, security incident. +2. **Notify (during business hours):** non-critical synthetic failure, performance regression, slow query, dependency degradation. +3. **Log (no notification):** anomalies for later review, low-priority warnings, info-level events. + +Anything in tier 1 must be: +- Actionable (the on-call can do something about it) +- Important (it represents real impact) +- Rare (less than 1-2 per week is the goal) + +If tier 1 alerts fire frequently, alert fatigue sets in. People stop responding. + +### Step 6: Configure routing + +Where do alerts go? + +- Tier 1: paging system (e.g., PagerDuty, Opsgenie). Direct to on-call. +- Tier 2: chat channel (Slack, Teams). Tagged with the area. +- Tier 3: dashboard or log only. + +Each tier should have a documented escalation path. If the on-call doesn't ack within 5-15 minutes, escalate. + +### Step 7: Build dashboards + +One dashboard per audience: + +- **Real-time ops dashboard:** current health, recent alerts, error rates, throughput +- **SLO dashboard:** SLO status and error budget consumption +- **Per-service dashboards:** detail for individual services or pages +- **Executive dashboard:** uptime over weeks/months, key business metrics + +Dashboards are different from alerts. Alerts say "look now." Dashboards say "here's what's happening." + +### Step 8: Run an alert audit + +Every quarter, audit: +- Which alerts fired? Were they actionable? +- Which alerts didn't fire when they should have? +- Are any alerts noisy (more than once a week, low actionability)? +- Are runbooks up to date? +- Have SLOs been met? Any consistently breached? + +Tune the system. Monitoring drifts without active maintenance. + +--- + +## Failure patterns + +**Alert on cause, not symptom.** "CPU is high" is a cause. "Users are slow" is a symptom. Alert on symptoms; investigate causes. + +**Alert without a runbook.** If the on-call doesn't know what to do, the alert is useless. Every paging alert needs a runbook (even a one-line one). + +**No baselines for "normal."** Alerting on "more than 100 errors per minute" sounds reasonable but a busy day might exceed that without anything being wrong. Use rate-based and anomaly-based alerts. + +**Single-region monitoring.** Your monitoring service in the same region as your site means you'll miss regional outages and you'll get woken up when monitoring itself has issues. + +**Monitoring the monitoring.** Or rather, not. If your alerting platform is down, who tells you? Most paging services offer their own status feeds. Subscribe. + +**Too many tiers of severity.** P0/P1/P2/P3/P4 with different SLAs becomes a sorting exercise. Three tiers (page, notify, log) is plenty. + +**Synthetics that don't match reality.** A synthetic that hits the homepage every minute tests "is the homepage up." It doesn't test "is the actual user flow working." Build synthetics for the journeys that matter. + +**Static thresholds that never get tuned.** Traffic grows, behavior changes, thresholds set last year are wrong. Review thresholds quarterly. + +**On-call rotation with no handoffs.** Each new on-call has to figure out the system. Document. Run weekly handoff meetings or async updates. + +**Pager fatigue.** If on-call is paged more than once or twice a week, something is wrong. Audit the alerts. Reduce, tune, or fix the underlying issues. + +--- + +## Output format + +A monitoring plan includes: + +- **System map:** what's being monitored +- **SLOs:** the 3-5 reliability targets +- **Checks per layer:** availability, correctness, performance, errors +- **Alert tiering:** what pages, what notifies, what logs +- **Routing:** where alerts go, escalation paths +- **Dashboards:** what audiences see +- **Runbooks:** linked from each paging alert +- **Audit cadence:** when this gets reviewed + +--- + +## Reference files + +- [`references/slo-design-guide.md`](references/slo-design-guide.md): Detailed walkthrough of writing SLOs, error budget policies, and common SLO mistakes for web services. diff --git a/skills/monitoring-and-alerting/references/slo-design-guide.md b/skills/monitoring-and-alerting/references/slo-design-guide.md new file mode 100644 index 0000000..1f5ec49 --- /dev/null +++ b/skills/monitoring-and-alerting/references/slo-design-guide.md @@ -0,0 +1,246 @@ +# SLO Design Guide + +A walkthrough for designing Service Level Objectives that are useful, achievable, and aligned to user experience. + +--- + +## What an SLO is and isn't + +A Service Level Objective is a target for reliability, expressed as a percentage of "good" events out of all events, measured over a specific time window. + +An SLO is: +- A reliability target the team commits to +- Measured automatically +- Tied to user-visible behavior +- Reviewed and adjusted over time + +An SLO is not: +- A guarantee (that's an SLA, which has contractual consequences) +- A goal to maximize (100% is the wrong target) +- A vanity metric (uptime alone tells you almost nothing) +- Permanent (revise as the system evolves) + +--- + +## The structure of a good SLO + +Every SLO has four components: + +1. **The thing being measured (the SLI - Service Level Indicator)** +2. **The success criterion (what counts as "good")** +3. **The target (the percentage of events that should be "good")** +4. **The window (the time period over which to measure)** + +Example: + +> "99.9% of homepage requests return a 2xx status code in under 2 seconds, measured over a rolling 30-day window." + +Breaking it down: +- SLI: latency and status of homepage requests +- Good event: 2xx response in under 2 seconds +- Target: 99.9% +- Window: rolling 30 days + +If the system serves 1 million homepage requests in 30 days, this SLO allows 1,000 bad events. That's the error budget. + +--- + +## Picking SLIs + +The SLI is what you measure. Pick SLIs that reflect what users actually experience. + +### Good SLI categories + +**Availability:** the proportion of valid requests that succeed. +- "% of HTTP requests that return non-5xx" +- "% of API calls that complete without error" + +**Latency:** the proportion of requests that complete fast enough. +- "% of homepage requests with TTFB under 600ms" +- "% of search queries returning results in under 1 second" + +**Quality:** the proportion of requests that produce correct results. +- "% of recommendations served from the personalized model (vs fallback)" +- "% of search queries returning at least one result" + +**Freshness:** the proportion of data that's fresh enough. +- "% of cached pages updated within the last 24 hours" +- "% of analytics data ingested within 15 minutes of event" + +**Throughput:** the proportion of time the system handles required load. +- "% of minutes during which queue depth was below 1000" + +### Bad SLI patterns + +**CPU or memory utilization.** These are causes of problems, not symptoms users feel. Don't make them SLIs. + +**Number of incidents.** Too coarse. One nasty incident can blow it for the whole window. + +**Average response time.** Averages hide tail latency. P95 or P99 is closer to user experience. + +**Internal metrics that don't map to user impact.** "Database replica lag." Useful to monitor. Not a great SLO unless it directly affects users. + +--- + +## Picking targets + +Target percentages have specific implications. Here's the practical math: + +| Target | Allowed bad time per 30 days | Allowed bad events per million | +|---|---|---| +| 90% | 3 days | 100,000 | +| 99% | 7 hours, 18 minutes | 10,000 | +| 99.9% | 43 minutes, 30 seconds | 1,000 | +| 99.95% | 21 minutes, 48 seconds | 500 | +| 99.99% | 4 minutes, 22 seconds | 100 | +| 99.999% | 26 seconds | 10 | + +Each "9" added is roughly 10x harder. Pick the lowest target that's acceptable to users. + +### How to pick + +1. **Look at current performance.** What's the system actually achieving? Use that as the floor. +2. **Look at user expectations.** What do users tolerate? For a marketing site, occasional slow pages are fine. For a payment system, they're not. +3. **Look at competitive bar.** What do similar services achieve? +4. **Pick something achievable but slightly aspirational.** If the current achievement is 99.5%, set the SLO at 99.7%. Don't jump to 99.99%. + +### Common mistakes + +**Setting the SLO at 100%.** Impossible. Wastes infrastructure. Creates false promises. + +**Setting the SLO based on what marketing wants to advertise.** If marketing says "99.99% uptime!" but engineering can't deliver, the SLO is fiction. + +**Setting different SLOs for different teams without coordination.** End-to-end user experience depends on all of them. If one team has a 99.9% SLO and another has 99%, the combined experience is worse than either. + +--- + +## Picking windows + +The window affects how SLOs feel. + +**Calendar windows:** "99.9% in March." Resets at month boundaries. Good for reporting, bad for operating (the budget can be exhausted on March 1 with nothing you can do until April). + +**Rolling windows:** "99.9% over the last 30 days." Always current. Better for operations because the budget continuously updates. + +Common windows: +- 7 days: too short, noise dominates +- 28-30 days (rolling): the sweet spot for most operations +- 90 days: better for SLAs and stability assessment, worse for fast feedback + +For most teams: 30-day rolling. + +--- + +## Error budgets + +The error budget is `1 - SLO`. If your SLO is 99.9%, your error budget is 0.1%. + +The budget is what allows for change. Every release, every config change, every dependency update consumes some budget. The budget exists so the team can ship. + +### Error budget policy + +A written policy that says what happens when the budget is at different levels. Example: + +| Budget remaining | What's allowed | +|---|---| +| > 50% | Normal operation. Ship features, run experiments. | +| 25-50% | Caution. Postpone risky migrations. Prefer smaller releases. | +| 10-25% | Slow down. Only ship reliability fixes and security patches. Defer feature releases. | +| < 10% | Freeze. No non-urgent changes. Focus on reliability. | + +This is the operationally useful part of SLOs. It connects reliability to product velocity in a measurable way. + +### Burning the budget + +If the budget burns at a rate of, say, 10% in an hour, that's a fast burn. Alert on fast burns: "we'll exhaust the budget in 4 hours at this rate." + +Slow burn alerts catch sustained low-grade issues. Fast burn alerts catch acute incidents. + +### Refilling the budget + +The budget refills as the rolling window moves forward. If today is the last day of a bad month, tomorrow the worst day rolls off and the budget recovers slightly. + +Don't "make up" budget by tightening the SLO temporarily. SLOs are user-facing commitments. Don't move them to make numbers look better. + +--- + +## Multi-tier SLOs + +For complex systems, one SLO isn't enough. Multi-tier SLOs cover different aspects. + +A typical web app might have: + +1. **Availability SLO:** 99.95% of requests return non-5xx. +2. **Latency SLO:** 99% of requests complete in under 1 second. +3. **Critical flow SLO:** 99.9% of checkout flows complete successfully. + +Each has its own error budget and policy. + +For products with multiple tiers of importance, you can also have different SLOs per tier: + +- Critical pages (homepage, checkout): 99.95% +- Standard pages (product, category): 99.9% +- Long-tail pages (search, archive): 99% + +This reflects user impact: a slow checkout matters more than a slow archive page. + +--- + +## Reviewing and revising SLOs + +SLOs aren't set-and-forget. Review: + +- **Quarterly:** is the SLO still right? Has the system or user expectation changed? +- **After major incidents:** did the SLO catch it? Should the SLO be tighter? +- **After major launches:** did the new feature change the math? +- **Annually:** big-picture review of all SLOs. + +Common revisions: +- Tightening (e.g., 99.9% → 99.95%) when the system has improved and the team can sustain it +- Loosening (e.g., 99.95% → 99.9%) when the previous target was too aggressive (rare, requires justification) +- Splitting an SLO into multiple (e.g., one combined SLO becomes separate availability and latency SLOs) +- Retiring SLOs that no longer reflect what matters + +--- + +## Example: a marketing site + +For a typical marketing site: + +| SLO | Target | Window | +|---|---|---| +| Homepage availability (2xx response) | 99.9% | 30-day rolling | +| Homepage latency (TTFB < 800ms) | 95% | 30-day rolling | +| Form submission success | 99.5% | 30-day rolling | +| Critical-page availability (top 10 pages 2xx) | 99.9% | 30-day rolling | + +Error budget policy: +- Above 50% budget: ship freely +- 10-50% budget: defer risky changes +- Below 10%: freeze non-essential changes + +This is a reasonable starting point. Tune based on actual operating history. + +--- + +## Example: a SaaS product + +For a SaaS product with paying customers: + +| SLO | Target | Window | +|---|---|---| +| API availability (non-5xx) | 99.95% | 30-day rolling | +| API latency (p95 under 500ms) | 99% | 30-day rolling | +| Login success | 99.99% | 30-day rolling | +| Critical action success (e.g., save data) | 99.95% | 30-day rolling | +| Background job completion within 1 hour | 99% | 7-day rolling | + +Error budget policy is stricter (paying customers have higher expectations). Below 25% budget triggers a slowdown; below 10% triggers a freeze with executive approval needed to override. + +--- + +## When you don't have an SLO yet + +Start small. Pick one SLO that maps to the most important user-facing behavior. Live with it for a quarter. Add more once the team is comfortable. + +Trying to roll out 10 SLOs at once usually fails. Trying to roll out 1 SLO and using it well usually succeeds. diff --git a/skills/multi-step-form-design/SKILL.md b/skills/multi-step-form-design/SKILL.md new file mode 100644 index 0000000..5e53791 --- /dev/null +++ b/skills/multi-step-form-design/SKILL.md @@ -0,0 +1,332 @@ +--- +name: multi-step-form-design +description: "Designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. Honest about kitchen-sink-single-page (overwhelms before the user starts), progress-theater (steps without genuine staging), and genuinely-staged (each step earns its own page) patterns. Triggers on multi-step form, multi-page form, form wizard, signup wizard, lead form, application form, intake form, configurator, onboarding form. Also triggers when a long form is converting poorly, when an audience is dropping off mid-form, or when a multi-step form is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing multi-step forms that respect cognitive load while maintaining completion intent. Distinguishes kitchen-sink-single-page (overwhelms) from progress-theater (steps without genuine staging) from genuinely-staged (each step earns its own page)" +display_order: 4 +--- + +# Multi-Step Form Design + +A senior growth practitioner's playbook for designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. + +Most multi-step forms are either kitchen-sink-single-pages dressed up as steps or arbitrary chunking that adds friction without adding clarity. The form looks more sophisticated; the completion rate does not move; the audience is no better served than before. + +The multi-step forms that work do something different. Each step represents a coherent unit of cognitive work the user can complete with confidence. Progress indicators reinforce momentum. Conditional logic responds to earlier answers and removes irrelevant fields. The form feels like a guided process, not an obstacle course. + +The voice is the senior growth practitioner who has watched multi-step forms convert at twice the single-page rate and watched them collapse to half. Practical, opinionated about when steps add value and when they add friction, willing to call out arbitrary chunking that does not earn its complexity. + +When to use this skill: scoping a multi-step form for the first time, auditing a long single-page form that converts poorly, deciding when to break a form into steps and when to keep it on one page, or designing the conditional logic that makes the form feel adaptive. + +--- + +## What this skill covers + +This skill spans multi-step form design across acquisition, onboarding, and intake contexts. The growth-tooling distinctions: + +- `lead-magnet-design` covers lead-magnet methodology; forms are one delivery surface for lead magnets but this skill is about the form itself. +- `landing-page-copy` is the page wrapping the form. This skill is the form itself. +- `accessibility-audit` covers accessibility deeply; forms have specific accessibility requirements; this skill references but does not replace accessibility-audit. +- `pm-spec-writing` is the spec for engineers building the form. This skill is about WHAT to build; pm-spec-writing is about communicating it. +- **`multi-step-form-design` (this skill)** is the form's structure, step architecture, progression, and validation. + +The audience: growth marketers, product marketers, marketing teams designing acquisition forms, in-house teams designing onboarding flows, agencies running form-based growth tooling for clients. + +Out of scope: form-builder platform configurations (those stay implementation-side); deep accessibility audits (covered by `accessibility-audit`); landing-page copy that wraps the form (covered by `landing-page-copy`). + +--- + +## The multi-step decision: when to break into steps vs keep single-page + +Before designing the steps, decide whether the form should be multi-step at all. + +**Multi-step earns the build when:** + +- The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. +- The fields naturally group into logical categories. Personal info, then situation, then preferences. Steps that reflect real groupings respect cognitive load. +- The audience benefits from progressive commitment. Each step builds investment; the user is more likely to complete after they have engaged with step 2 than they would have been if they had seen step 5's complexity upfront. +- Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page. + +**Multi-step does NOT earn the build when:** + +- The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. +- The fields do not group naturally. Arbitrary chunking is friction. +- The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. +- The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes; the maintenance overhead is real. + +The decision is not "should the form be multi-step"; it is "is multi-step the right structure for this specific data collection and audience." + +Detail in [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md). + +--- + +## Kitchen-sink-single-page vs progress-theater vs genuinely-staged + +The keystone framing. + +**Kitchen-sink-single-page.** 30 fields on one page. Overwhelms before the user even starts. Drop-off near 100 percent on anything beyond a contact form. The audience scrolls, sees the length, and leaves. Cost: the form's data collection scope is correct; the structure is wrong; nobody completes it. + +**Progress-theater.** The form is broken into 5 steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone. Step 4: company. Step 5: role." The progress bar exists; the staging logic does not. Cost: the form feels broken; users reach step 3 wondering why they did not just fill a single page; the completion rate may be slightly better than kitchen-sink but the audience perceives the format as gimmicky. + +**Genuinely-staged.** Each step represents a coherent unit of cognitive work. The user finishes a step and feels they accomplished something. Steps progress from low-friction to higher-commitment as intent compounds. Cost: the design effort upfront is significant; the maintenance is real; the conversion rate often outperforms both alternatives meaningfully. + +The litmus test. Ask a user who completed step 2 what they just did. Can they describe the unit of work as something coherent ("I gave you the basics about my company") or is the answer atomized ("I typed my company name in a field")? Coherent answers signal genuinely-staged; atomized answers signal progress-theater. + +--- + +## Step architecture: what belongs on each step + +The structure that makes steps coherent. + +**The principle.** Each step should represent a coherent unit of work from the user's perspective. + +**Common step patterns.** + +- **Identity step.** Who the user is. Name, email, basic role. Low-friction; opens the form. +- **Context step.** What the user's situation is. Company size, industry, current setup. Medium-friction; user shares context. +- **Need step.** What the user is trying to accomplish. Goals, challenges, priorities. Higher-friction; user articulates intent. +- **Detail step.** Specifics needed to act on the user's request. Budget, timeline, specific requirements. Highest-friction; saved for last. +- **Confirmation step.** Review and submit. Summarizes what the user provided. + +**Step sequencing principle.** Low-friction first; commitment compounds; high-friction at the end after the user has invested. + +**Step coherence test.** Can each step be described in one sentence as a unit of work? "Step 2: tell us about your company's situation" beats "Step 2: company name, size, industry, and revenue range." + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## Progress indicator design + +When to show progress, what to show, how it builds momentum. + +**The principle.** Progress indicators reinforce momentum and reduce uncertainty about how much is left. + +**Progress indicator patterns.** + +- **Step counter.** "Step 2 of 4." Simple, common, effective for short forms (3-6 steps). +- **Progress bar.** Visual fill showing percentage complete. Effective for forms with variable-length steps where step count alone is misleading. +- **Step list.** Named steps shown with the current one highlighted. Useful when the user benefits from seeing what comes next. +- **No indicator.** Sometimes appropriate for very short forms (2-3 steps) where the indicator overhead exceeds its value. + +**Progress indicator failures.** + +- **Indicator that shifts mid-form.** "Step 4 of 5" becomes "Step 4 of 7" because conditional logic added steps. The user feels misled. +- **Indicator that hides remaining work.** Showing "almost done" when 5 fields remain on the next step. +- **Indicator that is decorative without being honest.** Progress that looks fast but the next step is the longest one. + +**Progress indicator discipline.** The indicator must reflect the actual remaining work, not flatter the user. + +Detail in [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md). + +--- + +## Conditional logic + +Branching that responds to earlier answers. + +**The principle.** Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +**Conditional logic patterns.** + +- **Show or hide fields based on previous answers.** "If user selected 'enterprise,' show enterprise-specific fields." +- **Skip entire steps.** "If user does not have a current CRM, skip the 'CRM details' step." +- **Adapt the language.** "If user is in healthcare, use healthcare-specific terminology in subsequent fields." +- **Adapt the destination.** "If user selected 'integration question,' route to the integration team after submission." + +**Conditional logic strengths.** + +- Removes irrelevant friction. +- Makes the form feel adaptive and intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +**Conditional logic risks.** + +- Maintenance complexity grows quickly. +- Testing becomes harder (more paths through the form). +- Progress indicators must adapt or honestly disclose the variability. + +**The simplicity preference.** Add conditional logic only when it produces real value. Conditional logic for decoration adds maintenance without lift. + +Detail in [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md). + +--- + +## Save-and-resume mechanics + +When to offer save-and-resume, how to communicate trust. + +**The principle.** Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. + +**When save-and-resume helps.** + +- Forms that require document uploads or specific information (W-2, financial details, technical configurations). +- Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms). +- Forms where the user benefits from coming back to verify or update. + +**When save-and-resume does not help.** + +- Quick lead-capture forms (under 60 seconds to complete). +- Single-session forms where save-and-resume adds complexity without lift. + +**Save-and-resume mechanics.** + +- **Email-link recovery.** "Save your progress; we will email you a link to continue." The most common pattern. +- **Account-based persistence.** Forms that require account creation persist by default. +- **Anonymous-session save.** Browser-based save without identification. Lowest friction but limited to the same browser/device. + +**Trust communication.** Users hesitate to save partial sensitive information. The form should communicate clearly: what is saved, how long it persists, who can access it, how to resume. + +Detail in [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md). + +--- + +## Validation strategy + +Per-step vs end-only. + +**Per-step validation.** Each step's fields are validated before allowing progression. The user catches errors early. + +**Strengths.** + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +**Weaknesses.** + +- Can feel intrusive if validation is too strict on every keystroke. +- May block the user from progressing when they want to revise later. + +**End-only validation.** All validation runs at submission. + +**Strengths.** + +- User completes uninterrupted. +- Validation logic is simpler. + +**Weaknesses.** + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. + +**The hybrid pattern.** Required-field validation per step; full validation at end. The user gets immediate feedback on critical issues; nuanced validation runs at submission. + +**Validation message discipline.** + +- Helpful messages: "Phone number must include area code" beats "Invalid phone number." +- Inline placement: errors appear next to the field, not in a banner. +- Specific guidance: "Try a value between 1 and 1000" beats "Out of range." + +Detail in [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon, and how to fix it. + +**Step-by-step drop-off tracking.** Track the percentage of users who reach each step and the percentage who complete it. The diagnostic data informs which steps need redesign. + +**Common drop-off points.** + +- **First field.** User clicked into the form, looked at it, and left. Often signals the form is too long or the value of completing is not clear. +- **Mid-form.** User abandoned mid-process. Often signals fatigue, sensitive questions, or unclear progress. +- **Final submission.** User completed all fields but did not submit. Often signals submission anxiety, validation error fear, or unclear next-step. + +**Remediation patterns.** + +- **First-field drop-off.** Reduce form length; clarify the value of completing; add social proof or trust signals. +- **Mid-form drop-off.** Audit the specific step where drop-off concentrates; add progress indicator; reduce field count on that step; reword sensitive questions. +- **Final-submission drop-off.** Add a confirmation step; reduce final-step requirements; clarify what happens after submission. + +**The instrumentation requirement.** Without per-step tracking, drop-off remediation is guesswork. Set up tracking before the form launches. + +Detail in [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md). + +--- + +## Form anti-patterns + +Patterns that look like multi-step forms but degrade conversion. + +**The kitchen-sink-single-page.** 30 fields on one page. Detail in keystone framing. + +**The progress-theater form.** Steps without genuine staging. Detail in keystone framing. + +**The arbitrary-chunking form.** Each step has 1-2 fields; user wonders why this is multi-step. + +**The hidden-length form.** No progress indicator; user does not know how long the form is; abandonment climbs. + +**The interrogation-form-with-steps.** 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +**The validation-strict form.** Validation that rejects too aggressively, frustrating users with valid inputs. + +**The mobile-broken form.** Form works on desktop, breaks on mobile. + +**The trust-broken form.** Save-and-resume offered without clear trust communication; user does not save because they distrust persistence. + +**The variable-step form.** Conditional logic that changes the step count visibly; user feels misled about remaining work. + +Detail in [`references/form-anti-patterns.md`](references/form-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md). + +- "Form converts at 4 percent; we expected 12 percent." Likely too long, or the value of completing is not clear, or the form is mobile-broken. +- "Drop-off concentrates at step 3." Specific-step issue; audit step 3's field count, sensitivity, and clarity. +- "Mobile completion is half of desktop." Mobile design issue; audit form behavior on actual devices. +- "Validation rejects valid inputs." Validation strictness; relax the validation or improve the input formats accepted. +- "Users abandon at submission." Final-step anxiety; add confirmation, reduce final requirements, clarify next step. +- "Save-and-resume is offered but nobody uses it." Trust communication missing; users do not save because they distrust persistence. +- "We added conditional logic; the form feels confusing." Conditional logic complexity outweighs benefit; simplify. +- "We split the form into more steps; conversion did not change." Steps were not coherent; progress-theater pattern. +- "Progress indicator shifts mid-form." Conditional logic added steps unexpectedly; either fix the indicator or fix the conditional logic. + +--- + +## The framework: 12 considerations for multi-step form design + +When designing or auditing a multi-step form, walk these 12 considerations. + +1. **The multi-step decision.** Is multi-step the right structure for this data and audience, or would single-page serve? +2. **Genuinely-staged, not kitchen-sink or progress-theater.** Each step represents a coherent unit of work from the user's perspective. +3. **Step architecture sound.** Identity, context, need, detail, confirmation. Low-friction first; commitment compounds. +4. **Progress indicator honest.** Reflects actual remaining work; does not shift mid-form. +5. **Conditional logic adds value.** Removes irrelevant fields without adding maintenance overhead. +6. **Save-and-resume mechanics fit the form.** Offered when the form length warrants; trust clearly communicated. +7. **Validation strategy matched to form.** Per-step for required fields; end-only for nuanced validation. +8. **Drop-off measurement instrumented.** Per-step tracking from launch. +9. **Mobile experience tested.** Form works on the devices the audience uses. +10. **Field count audited.** Each field necessary; non-essential fields removed. +11. **Final-step clear.** Submission action obvious; what happens after submission communicated. +12. **Maintenance discipline.** Quarterly review of conversion, drop-off, validation, and conditional logic. + +The output of the framework is a multi-step form that respects cognitive load, maintains completion intent, and converts the audience into the action the form is designed to capture. + +--- + +## Reference files + +- [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md) - When to break into steps vs keep single-page. The conditions that warrant the multi-step structure. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. +- [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md) - Step counter, progress bar, step list. When each works. Indicator failures. +- [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md) - Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. +- [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md) - When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. +- [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md) - Per-step vs end-only vs hybrid. Validation message discipline. +- [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md) - Step-by-step tracking. Common drop-off points and remediation patterns. +- [`references/form-anti-patterns.md`](references/form-anti-patterns.md) - The patterns that look like multi-step forms but degrade conversion. +- [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: multi-step forms earn completion when each step earns its place + +The multi-step forms that work as compounding assets are the ones the audience completes without resentment. Not because the form is short. Not because the steps are decorative. Because each step represented a coherent unit of cognitive work the user could complete with confidence, and the cumulative experience felt guided rather than obstructed. + +That is the bar. Below the bar are kitchen-sink-single-pages (overwhelm before the user starts) and progress-theater forms (decorative steps without coherence). Above the bar are genuinely-staged forms where the structure earns its complexity. + +The discipline is in the design choices upstream of the form. The decision to make the form multi-step (or not). The step architecture that makes each step coherent. The progress indicator that reflects honest progress. The conditional logic that removes friction without adding confusion. The validation that catches errors helpfully. The drop-off measurement that informs ongoing improvement. diff --git a/skills/multi-step-form-design/references/common-multi-step-form-failures.md b/skills/multi-step-form-design/references/common-multi-step-form-failures.md new file mode 100644 index 0000000..7281d88 --- /dev/null +++ b/skills/multi-step-form-design/references/common-multi-step-form-failures.md @@ -0,0 +1,187 @@ +# Common multi-step form failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the form did not convert" or "audiences abandon mid-form" or "we cannot tell what is going wrong." + +--- + +## "Form converts at 4 percent; we expected 12 percent." + +**The diagnosis.** Likely one of: too long, value of completing not clear, mobile-broken, or the audience-fit is wrong. + +**The cure.** Audit the form length (`references/multi-step-decision-criteria.md`); audit the value proposition on the landing page (`landing-page-copy`); test on mobile devices; verify the audience matches the form's purpose. + +--- + +## "Drop-off concentrates at step 3." + +**The diagnosis.** Specific-step issue. Audit step 3's field count, sensitivity, and clarity. + +**The cure.** Per-step audit. Reduce field count if step 3 has too many; reword sensitive questions; clarify why step 3 is needed; consider whether step 3's content belongs there at all. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## "Mobile completion is half of desktop." + +**The diagnosis.** Mobile design issue. The form was designed for desktop and breaks on mobile. + +**The cure.** Mobile-first redesign. Touch-friendly inputs, single question per screen on long steps, sliders sized for thumb interaction, progress indicator visible without scroll. Test on actual devices. + +--- + +## "Validation rejects valid inputs." + +**The diagnosis.** Validation strictness. Rules are over-specified, rejecting inputs the system can handle. + +**The cure.** Audit validation rules (`references/validation-strategy-patterns.md`). Email with plus-signs, international phone formats, non-Latin names should all pass. + +--- + +## "Users abandon at submission." + +**The diagnosis.** Final-step anxiety. The CTA is unclear; the user does not know what happens; the final field requires information they did not have. + +**The cure.** Clarify the CTA ("Get my PDF" beats "Submit"). Add post-submission preview. Add a confirmation step. Move final-field demands earlier if the user needs time to gather info. + +--- + +## "Save-and-resume is offered but nobody uses it." + +**The diagnosis.** Trust communication missing. Users do not save because they distrust persistence. + +**The cure.** Trust copy alongside the save option. What is saved, how long, who can access. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## "We added conditional logic; the form feels confusing." + +**The diagnosis.** Conditional logic complexity outweighs benefit. Either too many rules or rules that change the user's experience visibly without explanation. + +**The cure.** Simplify the conditional logic. Remove rules that do not justify their value. Communicate variability if it remains. Detail in `references/conditional-logic-patterns.md`. + +--- + +## "We split the form into more steps; conversion did not change." + +**The diagnosis.** Steps were not coherent. Progress-theater pattern. Splitting fields without grouping them into meaningful units does not produce the multi-step benefit. + +**The cure.** Restructure into genuinely-staged steps. Each step should represent a coherent unit of cognitive work. Detail in `references/step-architecture-patterns.md`. + +--- + +## "Progress indicator shifts mid-form." + +**The diagnosis.** Conditional logic added or removed steps unexpectedly. + +**The cure.** Either fix the indicator to handle conditional steps honestly, or fix the conditional logic to not change step counts visibly. Detail in `references/progress-indicator-patterns.md`. + +--- + +## "We cannot tell where users abandon." + +**The diagnosis.** Instrumentation missing. No per-step tracking. + +**The cure.** Add per-step tracking before any further changes. Without data, remediation is guesswork. Detail in `references/drop-off-measurement-and-remediation.md` (instrumentation requirement). + +--- + +## "Conversion is fine; lead quality is poor." + +**The diagnosis.** The form is converting the wrong audience. Either the audience-fit on the landing page is broad, or the form does not filter for the audience the team needs. + +**The cure.** Tighten the audience-fit upstream. The form may need fewer fields (less interrogation) but more qualifying fields (audience-segmentation). Detail in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Conversion was strong at launch; it has declined 30 percent over a year." + +**The diagnosis.** Form decay. Stale references, broken integrations, validation rules that no longer match reality. + +**The cure.** Quarterly maintenance audit. Update references, fix broken integrations, refresh validation rules. + +--- + +## "We A/B tested adding a progress indicator; conversion did not change." + +**The diagnosis.** Either the form was already short enough that an indicator was not needed, or the indicator was poorly designed (dishonest, hidden, or confusing). + +**The cure.** Audit the indicator's design. If the form is genuinely short (3-4 steps), the indicator may not lift conversion much. If the form is longer, the indicator should help; redesign if it is not. + +--- + +## "The form looks great in QA; users complain it is broken." + +**The diagnosis.** QA tested with the team's devices and browsers; users have different setups. + +**The cure.** Cross-browser, cross-device, cross-network testing. Consider real-world conditions (slow connections, older devices, accessibility tools). + +--- + +## "The form's submit button is gray; we cannot figure out why." + +**The diagnosis.** Validation logic is preventing submission but the error is not surfaced. Common cause: a hidden required field or a cross-field validation that fails silently. + +**The cure.** Surface all validation errors visibly. Submit button state should follow form state visibly; the user should see why submit is disabled. + +--- + +## "We added save-and-resume; nobody resumes." + +**The diagnosis.** Either users save but the recovery link does not arrive, or the resume experience is broken, or the form's value did not persist (the user's interest faded). + +**The cure.** Test the recovery email deliverability. Test the resume experience end-to-end. Consider whether save-and-resume is genuinely needed or whether it is decorative. + +--- + +## "Sales says the form-sourced leads are wrong type." + +**The diagnosis.** Audience-fit mismatch. The form is converting the wrong segment. + +**The cure.** Audit the form's qualifying fields and the landing page that drives traffic. Either tighten the audience filter at the landing page, or add qualifying fields to the form that route based on segment. + +--- + +## "We made the form shorter; submissions went up but lead quality went down." + +**The diagnosis.** The fields removed were qualifying fields. Conversion improved because friction dropped; quality dropped because the qualifying signal was lost. + +**The cure.** Decide whether quality or quantity matters more. Restore qualifying fields if quality matters; accept the lower quality if volume is the priority. Often the right answer is to restore some fields and accept some conversion impact. + +--- + +## "The form works on Chrome desktop; it crashes on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The form was tested on the team's primary platform. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use. + +--- + +## "We translated the form to Spanish; conversion is half what English is." + +**The diagnosis.** Translation quality, cultural mismatch, or audience-fit issue specific to the Spanish-speaking audience. Often a combination. + +**The cure.** Audit the translation quality (idiomatic vs literal). Audit cultural assumptions (date formats, phone formats, name conventions). Verify the audience matches. + +--- + +## The pattern across failures + +Most multi-step form failures fall into one of three patterns. + +**Pattern 1: The form is the wrong structure.** Kitchen-sink-single-page, progress-theater, arbitrary-chunking, hidden-length. The fix is structural. + +**Pattern 2: The form does not match the audience or the device.** Mobile-broken, validation-strict-against-international-inputs, audience-fit weak. The fix is matching the form to where the audience actually is. + +**Pattern 3: The form decays.** Stale references, broken integrations, drift in conditional logic, instrumentation drift. The fix is maintenance discipline. + +The metric pattern: form failures often look fine on submission count alone. The signal is in completion rate, drop-off per step, lead quality, and downstream conversion. Programs that track only submission counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (structure, audience-device match, decay). The principle that submission count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/multi-step-form-design/references/conditional-logic-patterns.md b/skills/multi-step-form-design/references/conditional-logic-patterns.md new file mode 100644 index 0000000..c24901b --- /dev/null +++ b/skills/multi-step-form-design/references/conditional-logic-patterns.md @@ -0,0 +1,270 @@ +# Conditional logic patterns + +Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. + +Conditional logic responds to earlier answers and removes irrelevant fields. Done well, it makes the form feel adaptive and intelligent. Done poorly, it adds maintenance complexity without improving the user experience. + +--- + +## The relevance principle + +Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +**The principle's win.** A user who answered "no, I do not have a CRM today" should not be asked "what CRM do you use today" three steps later. The conditional logic removes the friction. + +**The principle's risk.** Conditional logic adds maintenance complexity. Each branch has to be tested. Each branch can break. The simplicity preference: add conditional logic only when it produces real value. + +--- + +## Pattern A: Show or hide fields based on previous answers + +The most common conditional logic pattern. + +**How it works.** + +- A field appears or disappears based on the answer to an earlier question. +- "If user selected 'enterprise,' show enterprise-specific fields." +- "If user selected 'has current solution,' show 'current solution name' field." + +**Example.** + +Question: "Do you currently use a CRM?" +- Yes → show field "Which CRM do you use today?" +- No → hide that field; show "What is your current process for managing customer data?" + +The form adapts to the user's situation in real time. + +**Strengths.** + +- Removes irrelevant fields. +- Makes the form feel intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +**Weaknesses.** + +- Each branch needs testing. +- Late additions to the form can break conditional logic in unexpected ways. + +**When to use.** When showing all fields would be confusing or when irrelevant fields cause significant drop-off. + +--- + +## Pattern B: Skip entire steps + +Conditional logic at the step level. + +**How it works.** + +- Based on early answers, an entire step is skipped or included. +- "If user does not have a current CRM, skip the 'CRM details' step entirely." +- "If user is in healthcare, include the 'compliance requirements' step." + +**Strengths.** + +- Removes whole sections of irrelevant content. +- Form length adapts to the user. + +**Weaknesses.** + +- Progress indicators must adapt or honestly disclose variability. +- The user may notice the form's variability and feel confused. + +**When to use.** When entire categories of fields are irrelevant to some users (e.g., enterprise-only fields for non-enterprise users). + +--- + +## Pattern C: Adapt the language + +Conditional logic that changes terminology based on user context. + +**How it works.** + +- The form's wording adapts to the user's industry, role, or context. +- "If user is in healthcare, use 'patient' terminology in subsequent fields." +- "If user is technical, use technical terms; if non-technical, use plain language." + +**Strengths.** + +- Form feels personalized. +- Reduces cognitive load on the user (they see terminology that matches their context). + +**Weaknesses.** + +- Significantly more copy to maintain. +- Risk of inconsistent or awkward language. + +**When to use.** When the audience spans contexts where terminology genuinely differs (B2C vs B2B, technical vs non-technical, regulated vs unregulated industries). + +--- + +## Pattern D: Adapt the destination + +Conditional logic that affects what happens after submission. + +**How it works.** + +- Based on answers, the form routes to different teams or triggers different follow-ups. +- "If user selected 'integration question,' route to the integration team after submission." +- "If user selected 'enterprise,' trigger an enterprise-sales follow-up sequence." + +**Strengths.** + +- The user gets matched to the right team or sequence. +- Sales and support efficiency improve. + +**Weaknesses.** + +- Routing complexity grows; failure modes (wrong team, missed routing) increase. +- The user does not see the routing logic; mistakes are invisible to the user but visible in downstream impact. + +**When to use.** When the form serves multiple downstream paths and the routing materially affects the user's experience. + +--- + +## Pattern E: Branching forms + +Different paths through the form for different users. + +**How it works.** + +- Based on early answers, the user takes a different path entirely. +- "If user selects 'individual,' show the individual flow; if 'team,' show the team flow." + +**Strengths.** + +- Highly tailored experience. +- Each user only sees fields relevant to them. + +**Weaknesses.** + +- Significantly more complex to build and test. +- Hard to compare paths because users took different forms. +- Maintenance is hard. + +**When to use.** When the audience genuinely splits into distinct groups that need fundamentally different forms. Use sparingly. + +--- + +## The simplicity preference + +Add conditional logic only when it produces real value. + +**The discipline.** For each piece of conditional logic, ask: +- Does this remove genuine friction? +- Is the maintenance cost justified by the friction removed? +- Could a simpler approach (single-page with sectioned design) achieve the same goal? + +**The over-conditional form.** A form with 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively, the form is fragile and hard to maintain. + +**The cure.** Audit conditional logic periodically. Remove rules that do not justify their maintenance overhead. + +--- + +## Conditional logic and progress indicators + +The interaction matters. + +**The challenge.** A form with conditional steps may have variable total step count. The progress indicator must accommodate. + +**Approaches.** + +- **Variable indicator.** "Step 2 of 5-7" or "Step 2 (about halfway)." Communicates the variability. +- **Range indicator.** "Step 2 of about 5." Approximate but honest. +- **Dynamic indicator.** Updates as the user's answers determine the path. Risk of feeling unstable. +- **Step-list indicator.** Shows all possible steps; current step highlighted. Variability visible upfront. + +The discipline. Choose an approach that does not lie about progress. + +--- + +## Conditional logic testing + +Test every branch of conditional logic. + +**The challenge.** A form with 5 conditional rules has 32 possible paths through the form. Testing all paths is infeasible at scale; testing critical paths is the discipline. + +**Critical paths.** + +- The most common path (most frequent user type). +- Each conditional rule's branch (one path that triggers it, one that does not). +- Edge cases (combinations that could produce unexpected behavior). + +**Testing methods.** + +- **Manual testing.** Walk through critical paths. +- **Automated testing.** Programmatic tests for each branch. +- **User testing.** Watch users complete the form; surface confusion or paths that break. + +**Production monitoring.** Track which paths users take. Sudden shifts may indicate logic issues. + +--- + +## Conditional logic and analytics + +Track which conditional branches trigger. + +**Why.** Understanding which branches are common informs maintenance priorities. A branch nobody triggers may not be worth maintaining; a branch everyone triggers may not need to be conditional. + +**The metric.** Per-branch trigger rate. Per-branch conversion rate. + +**The discipline.** Periodically review the data. Retire conditional rules that do not pay off. + +--- + +## Conditional logic and form maintenance + +Conditional logic decays. + +**What decays.** + +- Rules that point to fields that have been renamed or removed. +- Rules that produce paths now unused as the audience shifts. +- Rules whose triggering questions have been reworded. + +**Maintenance cadence.** Quarterly audit alongside the broader form audit. + +**The drift indicator.** Bug reports about specific paths failing; analytics showing unexpected branching behavior; testing surfaces broken rules. + +--- + +## Common conditional logic failures + +**Hidden complexity.** Many rules silently affecting many fields; the form's behavior is hard to reason about. + +**Unintended interactions.** Two rules that work individually but conflict when combined. + +**Stale rules.** Rules that point to fields no longer in the form. + +**Dead branches.** Conditional paths nobody triggers; maintenance overhead with no payoff. + +**Indicator-rule mismatch.** Progress indicator that does not handle conditional step count. + +**Untested edge cases.** Unusual answer combinations that produce broken paths. + +**Rule-driven layout shifts.** Fields appearing and disappearing causing visual jumpiness. + +**Over-conditional forms.** 25+ rules across the form; the maintenance burden exceeds the friction-reduction value. + +--- + +## When NOT to use conditional logic + +Some situations work better without conditional logic. + +**Short forms.** Adding conditional logic to a 5-field form rarely justifies the complexity. + +**Forms with stable audiences.** When everyone takes roughly the same path, conditional logic adds variability without value. + +**Forms in early stages.** A new form benefits from simplicity before adding complexity. Launch simple; add conditional logic when data shows where it would help. + +**Forms with high maintenance constraints.** Teams that cannot maintain complex forms should default to simpler designs. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. The simplicity preference. Conditional logic and progress indicators. Conditional logic testing. Conditional logic and analytics. Maintenance considerations. Common failures. When NOT to use conditional logic. + +## Implementation choices that stay internal + +Specific conditional rules for specific forms. Specific tooling for rule implementation and testing. The team's audit calendars and rule-retirement processes. These vary by team. diff --git a/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md b/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md new file mode 100644 index 0000000..7f88000 --- /dev/null +++ b/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md @@ -0,0 +1,263 @@ +# Drop-off measurement and remediation + +Step-by-step tracking. Common drop-off points and remediation patterns. + +Drop-off is where the form fails. Measuring drop-off per step is the diagnostic that informs every other improvement. Without per-step tracking, drop-off remediation is guesswork. + +--- + +## The instrumentation requirement + +Set up per-step tracking before the form launches. + +**The minimum tracking.** + +- **Step start.** User landed on this step. +- **Step completion.** User completed this step (clicked Next). +- **Step abandonment.** User left without completing. + +**The derived metrics.** + +- **Step completion rate.** Of users who reached this step, what percentage completed it? +- **Step drop-off rate.** Of users who reached this step, what percentage abandoned at this step? +- **Funnel completion rate.** Of users who started the form, what percentage submitted? + +**Why instrumentation matters.** Drop-off remediation requires knowing where users abandon. Aggregate "the form converts at 8 percent" tells you something is wrong; per-step data tells you where. + +--- + +## Common drop-off points + +Three patterns recur across multi-step forms. + +**First-field drop-off.** User clicked into the form, looked at it, and left at the first field. + +Common causes. +- Form is too long; user saw the length and bounced. +- The value of completing is not clear; user does not know what they get. +- Form is mobile-broken; user could not interact. +- Form looks suspicious or untrustworthy. + +**Mid-form drop-off.** User abandoned partway through. + +Common causes. +- Fatigue; the form is too long and the user lost interest. +- Sensitive question they did not want to answer. +- Confusion about what is being asked. +- Loading delay or technical issue. +- The form's value did not justify the continued effort. + +**Final-submission drop-off.** User completed all fields but did not submit. + +Common causes. +- Submission anxiety; the user is not sure what happens next. +- Validation errors at submission lost them. +- The submission CTA is not clear. +- Final field requires information they did not have ready. + +--- + +## Remediation: first-field drop-off + +When users abandon at the first field. + +**Diagnostic questions.** + +- Is the form's value proposition clear at the start? +- Is the form length visible (creating bounce-on-length behavior)? +- Does the form work on mobile? +- Are trust signals present (privacy policy, security badges where appropriate)? + +**Remediation patterns.** + +- **Clarify the value.** "Get a personalized PDF in 5 minutes" beats "Fill out this form." +- **Hide the length.** Multi-step forms hide subsequent steps; the user does not see "this will take 20 minutes" upfront. +- **Add social proof.** "Trusted by 5000 teams" or "Used by [recognizable customer]" reduces hesitation. +- **Add trust signals.** Privacy assurance, security indicators, or testimonial near the form. +- **Reduce form to single page.** Sometimes the right answer is to revert from multi-step to single-page. + +**The diagnostic test.** A/B test variations. The treatment that improves first-field completion validates the diagnosis. + +--- + +## Remediation: mid-form drop-off + +When users abandon partway through. + +**Diagnostic.** + +- Which specific step has the highest drop-off? +- Are there sensitive questions on that step? +- How long does that step take to complete? +- Is the step's relevance clear? + +**Remediation patterns.** + +- **Reduce field count on the high-drop-off step.** Audit each field; remove non-essential fields. +- **Reword sensitive questions.** "How much do you spend on this today" beats "What is your annual budget?" Soft framing reduces abandonment. +- **Add progress indicator if missing.** Users abandon less when they know how much remains. +- **Add encouragement at the high-drop-off step.** "You are halfway there; just a few more questions to get your personalized result." +- **Restructure the step architecture.** If step 3 is a drop-off black hole, the architecture may be wrong; reconsider whether step 3's content belongs there at all. + +**The diagnostic test.** Watch real users complete the form (usability testing). The behavior often reveals the cause. + +--- + +## Remediation: final-submission drop-off + +When users complete fields but do not submit. + +**Diagnostic.** + +- Is the submission CTA clear? +- Does the user know what happens after submission? +- Are there validation errors at submission? +- Is the final field demanding information they did not have ready? + +**Remediation patterns.** + +- **Clarify the submission CTA.** "Get my personalized PDF" beats "Submit." The CTA should describe what the user gets. +- **Add post-submission preview.** "When you submit, we will email you within 5 minutes with..." sets expectations. +- **Move final-field demands earlier.** If the final field requires hard-to-find information, move it earlier so users gather it during the form. +- **Add a confirmation step.** A review-and-submit step where the user verifies their inputs reduces submission anxiety. +- **Validation pre-submission.** Surface errors before the user clicks Submit; do not let submission fail with surprise errors. + +--- + +## Tracking conditional-logic paths + +Multi-step forms with conditional logic have multiple paths through the form. + +**Per-path tracking.** + +- Tag each user's path through the form. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +**Path-specific remediation.** + +- A path that drops off at step 4 may need step-4 redesign for users on that path. +- A path that drops off rarely may not need attention. + +**The instrumentation challenge.** Conditional-logic paths multiply quickly. Track at the granularity that informs decisions, not at the granularity that overwhelms. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +**Segment-level tracking.** + +- Tag users by source, device, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +**Common segment patterns.** + +- Mobile users drop off more at long steps; desktop users push through. +- Paid-traffic users drop off earlier than organic; the audience-fit may be weaker. +- New visitors drop off more than returning visitors; trust matters. + +**Remediation by segment.** Sometimes the right answer is segment-specific. Mobile users may benefit from a shorter form variant; paid traffic may benefit from stronger trust signals. + +--- + +## Drop-off and time-of-completion + +Some drop-off correlates with how long the form takes. + +**Time-to-complete tracking.** + +- Average time per step. +- Total time across the form. +- Time-to-completion distribution. + +**Patterns.** + +- Forms taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Distribution skew (some users fast, some users slow) often signals usability issues that affect the slow users. + +**Remediation by time.** Forms taking too long should be shortened; steps taking too long should be split or simplified. + +--- + +## Drop-off audit cadence + +How often to audit drop-off data. + +**Weekly review.** For high-volume forms or recently launched forms. Catches regressions and informs rapid iteration. + +**Monthly review.** For stable forms. Tracks trends and surfaces gradual decay. + +**Quarterly review.** For all active forms as part of the broader form audit. + +**Triggered review.** When form structure changes, when traffic source shifts, or when conversion drops. Ad-hoc reviews catch specific issues. + +The cadence depends on traffic volume and the form's importance. High-traffic forms warrant more frequent attention. + +--- + +## A/B testing for drop-off remediation + +Test remediation hypotheses rather than guessing. + +**The discipline.** Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall conversion. + +**Common test types.** + +- Form length: shorter vs longer. +- Step count: fewer vs more steps. +- Field count: fewer vs more fields per step. +- Validation strictness: stricter vs looser. +- Progress indicator: present vs absent. +- Trust signals: present vs absent. + +**Test discipline.** + +- One treatment variable per test. +- Long enough to capture statistical significance. +- Measure both the targeted metric and downstream metrics. + +The data informs which remediation actually moves the metric. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +**The signal.** The wrong audience self-selecting out is honest filtering. A multi-step form that drops 60 percent of visitors but produces 5x the qualified leads vs a single-page form is doing its job. + +**The discipline.** Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream metrics (lead quality, conversion to next step) reveal which is happening. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. Sometimes the right answer is to accept higher drop-off in exchange for higher qualification. + +--- + +## Common measurement failures + +**No instrumentation.** Form launched without per-step tracking; drop-off data unavailable. + +**Aggregate-only tracking.** Conversion rate tracked but not step-by-step; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; field renames or step changes broke the tracking. + +**Confounded data.** Multiple changes deployed simultaneously; cannot attribute conversion change to any one change. + +**Vanity metrics.** Tracking number of starts without tracking completion; the high-volume forms look successful even when conversion is poor. + +**Segment-blind tracking.** Aggregate data hides segment-specific issues. + +**Time-blind tracking.** No data on time-to-complete; cannot diagnose fatigue-driven drop-off. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points (first-field, mid-form, final-submission) with diagnoses and remediation patterns. Tracking conditional-logic paths. Drop-off and audience segmentation. Drop-off and time-of-completion. Audit cadence. A/B testing for drop-off remediation. When drop-off is signal not failure. Common measurement failures. + +## Implementation choices that stay internal + +Specific drop-off baselines for specific forms. Specific tooling for tracking and analysis. Specific A/B test designs and treatments. The team's audit calendars. These vary by team and form. diff --git a/skills/multi-step-form-design/references/form-anti-patterns.md b/skills/multi-step-form-design/references/form-anti-patterns.md new file mode 100644 index 0000000..999e4c7 --- /dev/null +++ b/skills/multi-step-form-design/references/form-anti-patterns.md @@ -0,0 +1,224 @@ +# Form anti-patterns + +The patterns that look like multi-step forms but degrade conversion. Anti-patterns are easy to ship; the cost shows up in completion rates, lead quality, and brand reputation over time. + +--- + +## The kitchen-sink-single-page + +The pattern. 30 fields on one page. Overwhelms before the user starts. + +The signal. First-field drop-off near 100 percent on anything beyond a contact form. Users scroll, see the length, and leave. + +The cost. The form's data collection is correct; the structure is wrong; nobody completes it. + +The cure. Multi-step the form; group fields into coherent steps. Detail in `references/multi-step-decision-criteria.md` and `references/step-architecture-patterns.md`. + +--- + +## The progress-theater form + +The pattern. The form is broken into steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone." + +The signal. Completion rate marginally better than kitchen-sink; users feel the form is gimmicky; some abandon mid-form because each step feels pointless. + +The cost. The build effort produced a form that is no better than the alternative. The audience perceives the format as decorative. + +The cure. Restructure into genuinely-staged steps. Detail in `references/step-architecture-patterns.md`. + +--- + +## The arbitrary-chunking form + +The pattern. Each step has 1-2 fields; the user wonders why this is multi-step. + +The signal. Quick completions but high abandonment; the format adds friction without value. + +The cost. The user perceives the form as gimmicky; trust degrades. + +The cure. Either consolidate to single-page (if the form has only 4-6 fields) or expand the staging to coherent units (if the form has more fields that group naturally). + +--- + +## The hidden-length form + +The pattern. No progress indicator; the user does not know how long the form is. + +The signal. Mid-form drop-off climbs as users lose patience; abandonment correlates with time spent. + +The cost. Users who would have completed if they knew the length abandon out of uncertainty. + +The cure. Add an honest progress indicator. Detail in `references/progress-indicator-patterns.md`. + +--- + +## The interrogation-form-with-steps + +The pattern. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The signal. Drop-off at every step; cumulative completion rate is poor; the form earns "interrogation" reputation. + +The cost. The audience that completes is over-disclosed and may resent the friction; the audience that does not complete walks away with a negative impression. + +The cure. Audit the field set. Remove fields that are not necessary for the form's purpose. The right field count is often half what teams initially design. + +--- + +## The validation-strict form + +The pattern. Validation rejects valid inputs because the rules are over-specified. Email validation rejects plus-sign aliases; phone validation rejects international formats; name validation rejects non-Latin characters. + +The signal. Users with valid but unusual inputs abandon when validation fails. Reports of "the form would not let me submit." + +The cost. The form filters out valid users. The team perceives the form as working because submissions look clean; the team does not see the audience that could not get past validation. + +The cure. Audit validation rules against actual business requirements. Detail in `references/validation-strategy-patterns.md`. + +--- + +## The mobile-broken form + +The pattern. Form works on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; touch targets too small. + +The signal. Mobile completion drops to half of desktop or worse. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. + +--- + +## The trust-broken form + +The pattern. Save-and-resume offered without clear trust communication. Users do not save because they distrust persistence. + +The signal. Save-rate is low; users abandon mid-form rather than save. + +The cost. The save mechanism's investment produces no value; the audience that would have saved instead leaves permanently. + +The cure. Trust communication. What is saved, what is not, how long it persists, who can access it. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## The variable-step form + +The pattern. Conditional logic that changes the step count visibly. "Step 4 of 5" becomes "Step 4 of 7" mid-form. + +The signal. Users feel misled; abandonment climbs at the moment the indicator shifts. + +The cost. Trust damage. The user trusted the indicator; the indicator lied. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). Detail in `references/progress-indicator-patterns.md`. + +--- + +## The submission-anxiety form + +The pattern. The submit button is unclear, or the user does not know what happens after submission, or the final step demands information they did not have ready. + +The signal. Final-submission drop-off is high; users completed all fields but did not submit. + +The cost. The form gets near-completion and loses the conversion at the last step. + +The cure. Clear submission CTA, explicit post-submission preview, optional confirmation step. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## The popup-interrupted form + +The pattern. The user is mid-form; a popup appears (newsletter signup, chat invitation, special offer). The user's flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about the interruption. + +The cost. The form's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Suppress popups during form completion. Save promotional content for after submission or for the next visit. + +--- + +## The reset-on-error form + +The pattern. The user submits; validation fails; the form resets, losing the user's inputs. + +The signal. Users who hit the error do not retry; they leave. + +The cost. The form treats errors punitively. Trust collapses. + +The cure. Preserve inputs on error. Show the error inline; let the user fix and resubmit without re-entering everything. + +--- + +## The slow-validation form + +The pattern. Real-time validation that lags. The user types; validation runs; the form feels sluggish. + +The signal. Users feel the form is slow; abandonment climbs at long-validation steps. + +The cost. The form's perceived performance damages the brand. + +The cure. Move validation to on-blur (when the user leaves the field) instead of on every keystroke. Reserve real-time validation for instant checks (format, character count). + +--- + +## The incompatible-with-autofill form + +The pattern. Form does not support browser autofill. The user has to type every field manually. + +The signal. Mobile completion is worse than desktop; users with password managers abandon. + +The cost. The form treats users as if autofill does not exist. Friction without justification. + +The cure. Support standard autofill attributes. Use semantic HTML input types. Test with browser autofill enabled. + +--- + +## The save-but-lose-on-resume form + +The pattern. Save-and-resume offered; user saves; resume returns the user to the start of the form, losing their progress. + +The signal. Resume rate is high (users click the recovery link) but completion rate from resume is low (users abandon when they see they have to redo work). + +The cost. The save mechanism's apparent value disappears at resume; trust collapses worse than if save had not been offered. + +The cure. Test the resume experience. Verify that resuming returns the user to their actual progress with inputs preserved. Detail in `references/save-and-resume-mechanics.md` (resume experience section). + +--- + +## The over-conditional form + +The pattern. 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively the form is fragile and hard to maintain. + +The signal. Bug reports about specific paths failing; testing surfaces broken rules; conditional logic decays unnoticed. + +The cost. Maintenance burden compounds. Form behavior becomes hard to reason about. + +The cure. Audit conditional logic. Remove rules that do not justify their maintenance overhead. Detail in `references/conditional-logic-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active form, looking specifically for these anti-patterns. + +**Audit questions per form.** + +- Does the form have natural step groupings (anti-pattern check: progress-theater, arbitrary-chunking)? +- Is the progress indicator honest and stable (anti-pattern check: hidden-length, variable-step)? +- Does each field affect the form's outcome (anti-pattern check: interrogation-form)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Does the form work on mobile (anti-pattern check: mobile-broken)? +- Is save-and-resume tested end-to-end (anti-pattern check: save-but-lose-on-resume, trust-broken)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is conditional logic maintained (anti-pattern check: over-conditional)? + +**The retire decision.** Anti-pattern forms often warrant retirement or redesign. Maintaining broken forms costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/multi-step-form-design/references/multi-step-decision-criteria.md b/skills/multi-step-form-design/references/multi-step-decision-criteria.md new file mode 100644 index 0000000..92ced61 --- /dev/null +++ b/skills/multi-step-form-design/references/multi-step-decision-criteria.md @@ -0,0 +1,159 @@ +# Multi-step decision criteria + +When to break a form into steps vs keep it on a single page. The conditions that warrant the multi-step structure, and the funnels where multi-step adds friction without lift. + +A multi-step form is a meaningful build. Step architecture, progress indicators, conditional logic, validation, save-and-resume, drop-off instrumentation. The multi-step form earns this investment only when specific conditions are present. + +--- + +## When multi-step earns the build + +Five conditions that, when present, make multi-step the right structure. + +**The form has more than 8-10 fields.** Single-page forms beyond this point overwhelm the audience visually. The user scrolls, sees the length, and leaves. Multi-step breaks the visual length into manageable pieces. + +**The fields naturally group into logical categories.** Personal info, then situation, then preferences, then specifics. Steps that reflect real groupings respect cognitive load. Arbitrary chunking does not. + +**The audience benefits from progressive commitment.** Each step builds investment. The user is more likely to complete after engaging with step 2 than they would have been if they had seen step 5's complexity upfront. + +**Different paths through the form make sense based on early answers.** Conditional logic that adapts the form to the user is hard to do on a single page; multi-step makes the adaptation feel natural. + +**The success metric warrants the build.** Higher completion rate, lower drop-off, better lead quality, faster review for the receiving team. Without a defined success metric, the build is hard to justify. + +When all five are present, multi-step is a strong structure. When two or fewer are present, single-page often serves better. + +--- + +## When multi-step does NOT earn the build + +Funnels where multi-step is the wrong structure. + +**The form has 4-6 fields.** A single-page form is faster to complete and faster to maintain. Multi-step adds friction (step transitions, progress indicators, save-and-resume mechanics) without adding clarity. + +**The fields do not group naturally.** Arbitrary chunking is friction. "Step 1: name. Step 2: email. Step 3: phone." The user wonders why this is multi-step and the question itself signals friction. + +**The audience expects speed.** Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. The multi-step format implies "this will take a while," which depresses high-intent users. + +**The team cannot maintain the multi-step complexity.** Multi-step forms have more failure modes (conditional logic bugs, progress indicator drift, validation issues across steps). The maintenance overhead is real; teams that cannot commit to it should choose single-page. + +**The form is a follow-up to a hot conversation.** A demo-request form right after a sales call should be quick. Multi-step here adds friction the audience is not ready for. + +The honest assessment matters more than the default. "Should the form be multi-step" is not the question. "Is multi-step the right structure for this specific data collection and audience" is. + +--- + +## The opportunity-cost frame + +A multi-step form is meaningful work. Account for the cost honestly. + +**The build cost.** Step architecture, progress indicators, conditional logic, save-and-resume, validation across steps, drop-off instrumentation. A meaningful multi-step form often takes 30-80 engineering hours plus design. + +**The maintenance cost.** Steps decay as the brand evolves; conditional logic bugs surface; progress indicators need updating. Quarterly review and maintenance run 2-6 hours per active form. + +**The opportunity cost.** What else could the team have built? A simpler form that converts adequately, a different growth-tooling investment, a content piece. The multi-step form's success has to clear the bar of those alternatives. + +The decision frame. The multi-step form earns investment when it produces more conversion than the single-page alternative, accounting for the full cost of build plus maintenance. + +--- + +## The grouping precondition + +Without natural field groupings, multi-step is arbitrary. + +**The check.** Can the fields be grouped into 3-5 coherent categories? Each category representing a unit of cognitive work the user can describe in one sentence? + +If yes, multi-step has natural step boundaries. + +If no (the fields do not group; the only structure is "first half" and "second half"), multi-step will feel arbitrary. Either restructure the data collection (some fields may not be needed) or choose single-page. + +**Examples of natural groupings.** + +- Identity (name, email, role) + Context (company size, industry, current setup) + Need (goal, challenge, timeline) + Confirmation. +- Personal info + Loan details + Property details + Financial verification + Submission (mortgage application). +- Account info + Use case + Plan selection + Payment + Confirmation (signup wizard). + +**Examples of forced groupings.** + +- Page 1 (name, email, phone) + Page 2 (company, role, source, industry, size). The page break is arbitrary; nothing groups these fields meaningfully. +- Page 1 (most fields) + Page 2 (one final field). The split is purely decorative. + +The discipline. If the team cannot articulate the unit of work each step represents, the steps are arbitrary; either rework the steps or use single-page. + +--- + +## The decision worked example + +A B2B SaaS company considering whether to make a "Talk to sales" form multi-step. + +**Conditions check.** + +- Field count: 12 fields (name, work email, company name, company size, industry, role, current solution, primary use case, timeline, budget range, source attribution, additional context). Above the 8-10 threshold; multi-step is on the table. +- Natural groupings: yes. Identity (name, email, role), company context (name, size, industry), current state (current solution, use case), buying intent (timeline, budget), additional (source, context). 5 natural groups. +- Progressive commitment: yes. The audience giving budget at the end after engaging with the early steps is more likely to give it than if asked upfront. +- Conditional logic value: yes. If the audience selects "evaluating" timeline, additional fields appear; if "active project," different additional fields appear. +- Success metric: defined. Conversion rate to submission, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo within 21 days. + +**Decision.** Build multi-step. The conditions warrant it. + +**Step architecture.** 5 steps: Identity, Company, Current State, Buying Intent, Submission Confirmation. + +**Maintenance commitment.** Quarterly audit of conversion, drop-off per step, and conditional logic. + +The decision was not "should we make this multi-step" but "given these conditions, this is the multi-step structure to build." + +--- + +## The single-page worked example + +The same B2B SaaS company considering whether to make a "Subscribe to newsletter" form multi-step. + +**Conditions check.** + +- Field count: 2 fields (email, name). Below the 8-10 threshold. +- Natural groupings: no. Two fields do not group. +- Progressive commitment: no. The audience subscribing benefits from speed. +- Conditional logic value: no. No branching needed. +- Success metric: simple conversion rate. + +**Decision.** Single-page. Multi-step would add friction without value. + +The decision was "what is the right structure" and the answer was single-page even though multi-step was nominally available. + +--- + +## The hybrid pattern + +Some forms work best with a "main" single-page form plus one optional follow-up step. + +**The pattern.** A short single-page form (3-5 fields) gets the user committed; an optional follow-up appears after submission for users who want personalization. + +**When this works.** When the primary action is fast (signup, lead-capture) but a richer follow-up benefits some users. + +**When this does not work.** When the follow-up has to be required for the primary action to be useful. + +The hybrid avoids both kitchen-sink-single-page and forced multi-step. It serves the speed-seeking audience and the depth-seeking audience separately. + +--- + +## When to retire a multi-step form (or convert to single-page) + +Multi-step forms can become wrong as the form evolves. + +**Retire-or-convert when:** + +- Field count has dropped below 6 over time as fields were removed. +- Conditional logic has been simplified out, leaving the steps with no real differentiation. +- Drop-off concentrates uniformly across steps, suggesting the staging is not working. +- A simpler single-page form might convert better. + +**The conversion-to-single-page move.** Sometimes the right answer is to revert. The multi-step format earned the build at one point; conditions changed; single-page is now better. Honest reversion is part of the discipline. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant multi-step. The opportunity-cost frame. The grouping precondition. The decision worked example. The single-page worked example. The hybrid pattern. The retire-or-convert decision. + +## Implementation choices that stay internal + +Specific multi-step decisions for specific forms. The team's capacity benchmarks for build and maintenance. Specific tooling for form engineering. Specific success-metric definitions and baselines. These vary by team. diff --git a/skills/multi-step-form-design/references/progress-indicator-patterns.md b/skills/multi-step-form-design/references/progress-indicator-patterns.md new file mode 100644 index 0000000..2051213 --- /dev/null +++ b/skills/multi-step-form-design/references/progress-indicator-patterns.md @@ -0,0 +1,289 @@ +# Progress indicator patterns + +Step counter, progress bar, step list. When each works. Indicator failures. + +The progress indicator reinforces momentum and reduces uncertainty about how much is left. Bad indicators flatter or mislead; good indicators reflect honest progress. + +--- + +## The honesty principle + +The progress indicator must reflect actual remaining work. Indicators that flatter the user or hide remaining complexity break trust. + +**The honest indicator.** "Step 3 of 5" when there are exactly 5 steps and the user is on step 3. + +**The dishonest indicator.** + +- "Almost done" when 5 fields remain on the next step. +- Progress bar that fills to 80 percent when 50 percent of fields remain. +- Step counter that shifts from "5 of 7" to "5 of 9" because conditional logic added steps. + +The honesty discipline. Match the indicator to the actual work; do not flatter; communicate variability when it exists. + +--- + +## Pattern A: Step counter + +"Step 2 of 4." Simple, common, effective for short forms. + +**How it works.** + +- The current step number is shown. +- The total step count is shown. +- The format is consistent across the form. + +**Strengths.** + +- Easy to implement. +- Easy to understand. +- Compact. + +**Weaknesses.** + +- Does not reflect within-step progress. +- Misleading when step lengths vary significantly. +- Breaks if conditional logic changes the total step count. + +**When to use.** Forms with 3-6 steps where step lengths are roughly similar. + +--- + +## Pattern B: Progress bar + +Visual fill showing percentage complete. + +**How it works.** + +- A bar fills from left to right (or follows other visual progression). +- The fill represents percentage of fields completed (or percentage of weight in some weighted scheme). +- Optionally includes a percentage label. + +**Strengths.** + +- Reflects continuous progress. +- Handles variable-length steps better than step counter. +- Visually engaging. + +**Weaknesses.** + +- More complex to design and implement. +- Risk of dishonest fill (bar fills fast, last 10 percent represents most of the remaining work). + +**When to use.** Forms with variable step lengths or where the user benefits from continuous-progress signal. + +--- + +## Pattern C: Step list + +Named steps shown with the current one highlighted. + +**How it works.** + +- All step names visible (often in a sidebar or header). +- Current step highlighted. +- Completed steps marked (checkmark or different color). +- Future steps indicated. + +**Strengths.** + +- Shows the user the full form path. +- Reduces uncertainty about what is coming. +- Lets the user navigate back to specific steps. + +**Weaknesses.** + +- Takes more screen real estate. +- Can overwhelm if there are many steps. +- Forces the form to commit to step names upfront. + +**When to use.** Forms with 3-7 well-named steps where the user benefits from seeing the structure. + +--- + +## Pattern D: No indicator + +Sometimes appropriate for very short forms. + +**When to use.** + +- Forms with 2-3 steps where the indicator overhead exceeds its value. +- Forms where the user's expectation is "this is short" and the indicator would imply length. + +**Risks.** + +- Without indication, longer forms can feel endless. +- Users may abandon because they cannot predict the form's length. + +**The discipline.** No indicator is rarely the right answer for forms with more than 3 steps. + +--- + +## Pattern E: Hybrid + +Combining patterns. A step counter plus a progress bar; or a step list plus a percentage. + +**Strengths.** + +- Multiple signals reinforce each other. +- Different users benefit from different indicators. + +**Weaknesses.** + +- Visual complexity grows. +- Risk of redundant or conflicting signals. + +**When to use.** Long forms (5+ steps) where rich indication helps the user understand the form's shape. + +--- + +## Indicator failures + +Patterns that break trust. + +**Failure 1: Indicator that shifts mid-form.** + +The form starts as "Step 4 of 5"; conditional logic adds steps; the form is now "Step 4 of 7." The user feels misled. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). + +**Failure 2: Indicator that hides remaining work.** + +"Almost done" when 5 fields remain on the next step. The user trusted the indicator and now feels betrayed. + +The cure. Calibrate the indicator to reflect remaining fields, not just remaining steps. + +**Failure 3: Indicator that fills fast and slows down.** + +Progress bar fills to 70 percent in the first 2 steps; the remaining 30 percent takes the next 5 steps. The user expects the form to end soon and is frustrated when it does not. + +The cure. Weight the progress bar by actual work, not just step count. If step 5 represents most of the remaining work, the bar should reflect that. + +**Failure 4: Indicator with no current-step context.** + +The progress bar shows 50 percent but the user does not know what the current step is about. Reduces orientation. + +The cure. Include both progress (where you are) and current-step name (what you are doing). + +**Failure 5: Indicator that is decorative without being honest.** + +Progress that looks fast but the next step is the longest one. The indicator misleads about pacing. + +The cure. Honest pacing. The indicator should reflect actual time-to-complete, not just step count. + +--- + +## Indicator placement + +Where the indicator lives on the page. + +**Top placement.** Above the form fields. Common; user sees it on every step. + +**Sidebar placement.** Alongside the form. Good for step-list patterns; takes more space. + +**Bottom placement.** Below the form fields. Less common; user has to scroll to see it on long steps. + +**Sticky placement.** Indicator stays visible as the user scrolls within a step. Useful for long steps. + +The choice depends on form length per step and visual hierarchy. Top placement is the safe default. + +--- + +## Indicator and mobile + +The indicator must work on mobile. + +**Mobile-specific considerations.** + +- Step counter: easy to mobile (small footprint). +- Progress bar: easy (full-width fits). +- Step list: harder; may need to collapse to step counter on mobile. +- Hybrid: simplify on mobile; do not stack multiple indicators. + +**The mobile discipline.** Ensure the indicator is visible without scrolling. Mobile users should see "Step 2 of 5" or the progress bar without searching for it. + +--- + +## Indicator messaging + +Optional language alongside the indicator. + +**Encouragement messages.** "Halfway there!" or "Almost done!" Can boost motivation; can also feel patronizing. + +**Time estimates.** "About 2 minutes left." Useful when honest; misleading when wrong. + +**Step-name labels.** "Step 2: Your Company." Useful when steps have meaningful names. + +**The discipline.** Encouragement and estimates should be honest. Patronizing or wrong messaging breaks trust faster than no messaging. + +--- + +## Indicator updating + +When the indicator updates. + +**On step transition.** The indicator updates as the user moves to the next step. Common pattern. + +**On field completion.** The indicator updates as fields within a step are filled. More granular; less common. + +**Smooth animation.** Subtle animation on transition reinforces progress. + +**No animation.** Instant update is fine; flashy animation can be distracting. + +--- + +## When indicators add no value + +Some forms work without indicators. + +**Very short forms.** 2-step forms often do not need indication. The user knows it is short. + +**High-frequency forms.** Forms the user fills repeatedly may not need indication after the first time. + +**Single-action forms.** A subscription form with email and submit does not need a progress indicator. + +The discipline. Default to including an indicator for multi-step forms. Skip only when the form is genuinely simple enough that the indicator adds noise. + +--- + +## Indicator audit + +Periodically audit the indicator. + +**The audit.** + +- Read the indicator on each step. Does it reflect honest progress? +- Test the form with conditional logic. Does the indicator handle the variability? +- Check mobile rendering. Does the indicator work on touch devices? +- Check accuracy. Does "almost done" actually mean almost done? + +**The drift.** Indicators decay as forms evolve. Steps get added; conditional logic gets added; the indicator falls out of sync. + +**The cure.** Quarterly audit alongside form audit. Update the indicator when the form structure changes. + +--- + +## Common indicator failures + +**No indicator on a long form.** User does not know how much remains; abandons. + +**Indicator shifts mid-form.** Conditional logic surprised the user. + +**Dishonest pacing.** Bar fills fast, work remains slow. + +**Indicator without current-step context.** Progress without orientation. + +**Indicator overflowing on mobile.** Step list designed for desktop; cramped on mobile. + +**Patronizing language.** "Almost done" repeatedly when the user is at step 2 of 6. + +**Wrong time estimates.** "About 1 minute left" when 5 minutes remain. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. Indicator failures (5 patterns). Indicator placement, mobile considerations, messaging, updating. When indicators add no value. Indicator audit. Common failures. + +## Implementation choices that stay internal + +Specific indicator designs for specific forms. Specific tooling for indicator implementation. Specific brand-voice messaging alongside indicators. The team's mobile testing benchmarks. These vary by team. diff --git a/skills/multi-step-form-design/references/save-and-resume-mechanics.md b/skills/multi-step-form-design/references/save-and-resume-mechanics.md new file mode 100644 index 0000000..dc1b7a3 --- /dev/null +++ b/skills/multi-step-form-design/references/save-and-resume-mechanics.md @@ -0,0 +1,267 @@ +# Save-and-resume mechanics + +When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. + +Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. Done well, it earns the user's trust and recovers what would otherwise be lost completions. + +--- + +## When save-and-resume helps + +Three conditions that, when present, make save-and-resume valuable. + +**Form length warrants it.** Forms taking more than 5 minutes to complete benefit. Below 5 minutes, the user can usually push through; above, the cost of starting over is high. + +**Information may not be at hand.** Forms requiring documents, technical configurations, or specific data the user may need to gather. Save-and-resume lets the user collect the information and return. + +**Multi-session use is expected.** Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms, complex onboarding). Save-and-resume is required, not optional. + +When all three are present, save-and-resume is a strong investment. When none are present, the mechanic adds complexity without lift. + +--- + +## When save-and-resume does not help + +**Quick lead-capture forms.** Under 60 seconds to complete. The save mechanic adds complexity; the audience does not need it. + +**Single-session forms.** Forms designed to be completed in one sitting. Save-and-resume can encourage abandonment ("I will come back later") that becomes permanent. + +**Forms that require trust.** Sensitive information may not be safe to persist; the user may not save because they distrust persistence. Adding save-and-resume without addressing trust degrades the form. + +**Forms with strict expiration.** Application deadlines or session timeouts may make save-and-resume confusing or counterproductive. + +--- + +## Pattern A: Email-link recovery + +The most common save-and-resume pattern. + +**How it works.** + +- The user clicks "Save and resume later." +- A form appears asking for an email address. +- The user enters email; a recovery link is sent. +- The user opens the email later, clicks the link, returns to the form with progress preserved. + +**Strengths.** + +- Familiar pattern; users understand it. +- Works across devices (user can save on desktop, resume on mobile). +- Simple to implement. + +**Weaknesses.** + +- Requires the user to give an email address before completing the form (which may itself be friction). +- Depends on email deliverability. +- Recovery link can expire or get lost. + +**When to use.** Default for most save-and-resume needs. The familiar UX reduces friction. + +--- + +## Pattern B: Account-based persistence + +Forms that require account creation persist by default. + +**How it works.** + +- The user creates an account at the start. +- Form progress saves automatically as the user completes fields. +- The user logs back in to resume. + +**Strengths.** + +- Persistence is automatic; user does not have to choose to save. +- Works across devices. +- Account integration may extend to other features beyond the form. + +**Weaknesses.** + +- Account creation is significant friction at the start. +- Adds engineering complexity. +- May not be appropriate for one-shot forms. + +**When to use.** Forms that are part of an account-based product or service where account creation is justified by ongoing use. + +--- + +## Pattern C: Anonymous-session save + +Browser-based save without identification. + +**How it works.** + +- Form progress saves to browser local storage as the user completes fields. +- The user returns to the same browser, picks up where they left off. + +**Strengths.** + +- Lowest friction; no email or account required. +- Automatic; user does not have to choose to save. + +**Weaknesses.** + +- Works only on the same browser/device. +- Lost if the user clears cookies or switches devices. +- Limited persistence (typically days, not weeks). + +**When to use.** Forms where the audience likely returns from the same device within a short window. Often used as a fallback or supplement to other patterns. + +--- + +## Pattern D: Hybrid + +Combining patterns. Anonymous-session save by default; email-link recovery as a backup. + +**How it works.** + +- Form auto-saves to browser as user completes. +- A "save and resume from any device" option offers email-link recovery. + +**Strengths.** + +- Lowest-friction default; user benefits even without explicit action. +- Cross-device option for users who want it. + +**Weaknesses.** + +- More complex to design and explain. +- Multiple save mechanisms can confuse the user. + +**When to use.** Forms with significant length where many users return same-device but some need cross-device. + +--- + +## Trust communication + +Users hesitate to save partial sensitive information. The form must communicate clearly. + +**What to communicate.** + +- **What is saved.** "Your answers so far will be saved." +- **What is not saved.** "We do not save passwords or payment information until submission." +- **How long it persists.** "Your progress will be available for 7 days." +- **Who can access it.** "Only you can access your saved progress through the link we email you." +- **How to delete.** "You can clear your saved progress by completing or abandoning the form." + +**Trust copy patterns.** + +- "We never share your saved information." +- "Your progress is encrypted at rest." +- "You control whether to come back." + +**Trust copy that fails.** + +- Generic privacy boilerplate. +- Long legal text the user will not read. +- Vague reassurances without specifics. + +The discipline. Trust copy should be specific, scannable, and honest. Generic privacy text does not earn trust. + +--- + +## When in the form to offer save-and-resume + +Timing matters. + +**Pattern: Always available.** A "Save and resume" link visible on every step. The user can save at any moment. + +**Pattern: Triggered by inactivity.** After 60-90 seconds of inactivity, prompt the user to save. Risk: the prompt feels intrusive. + +**Pattern: Offered at logical breakpoints.** Save prompts at the end of each step or at known long-pause points. Less intrusive than continuous availability. + +**Pattern: Offered before high-friction steps.** "The next step requires document uploads. You can save now and come back when you have your documents." + +The choice depends on form length and the audience's likely pause points. Always-available is the safe default for long forms. + +--- + +## Resume experience + +The user clicks the recovery link or logs in. What happens next. + +**The principle.** The resume experience should be uninterrupted. The user lands on the step they were on; their previous answers are preserved; they can continue without re-doing work. + +**The resume page.** + +- Welcome back message confirming the resume. +- Preserved progress visible (the user sees what they had done). +- Clear path to continue (button to proceed to current step). + +**Resume failures.** + +- The user lands at the start; previous answers lost. Trust collapses. +- The user lands at the right step but answers are wrong. Worse than starting over. +- The recovery link expires; the user is told their progress is gone. The save mechanism failed. + +The discipline. Test the resume experience as carefully as the form itself. A broken resume is worse than no save. + +--- + +## Save-and-resume measurement + +Track how many users save and resume. + +**The metrics.** + +- **Save rate.** What percentage of users who reach the save option choose to save? +- **Resume rate.** What percentage of users who saved actually resume? +- **Resume-to-completion rate.** What percentage of users who resumed complete the form? + +**Diagnostic uses.** + +- Low save rate: the option is not visible or trust is missing. +- Low resume rate: the recovery email failed or the user lost interest. +- Low resume-to-completion: the resume experience is broken or the form is too long. + +**The decision.** If save-and-resume is offered but rarely used, audit whether the offering is justified or whether the mechanic adds complexity without payoff. + +--- + +## Save-and-resume for sensitive information + +Some forms collect sensitive information. Save-and-resume requires extra care. + +**The principle.** Sensitive information may not be safe to persist. Audit what is saved and what is not. + +**Common patterns.** + +- **Save non-sensitive only.** Names, emails, situational information saved; passwords, SSNs, payment details not saved. +- **Encrypt at rest.** Saved data encrypted in storage; only retrievable through recovery flow. +- **Limit persistence window.** Sensitive forms may save only for 24-48 hours rather than 7+ days. + +**Compliance considerations.** + +- Some jurisdictions or regulations restrict what can be persisted. +- The form's save behavior should be reviewed against applicable compliance. +- Trust copy should disclose persistence honestly. + +The discipline. Sensitive forms warrant more conservative save behavior. The convenience of save-and-resume is not worth privacy or compliance risk. + +--- + +## Common save-and-resume failures + +**Save offered without trust communication.** Users do not save because they distrust persistence. + +**Recovery link expires too quickly.** User receives the link, intends to come back, finds the link expired by the time they do. + +**Resume to wrong step.** User clicks recovery link, lands at the start, has to redo everything. + +**Saved answers corrupted.** User resumes, answers are wrong or partial. + +**Save mechanic decays.** Storage backend changes; saved data becomes inaccessible. + +**Multiple save mechanisms confuse.** Anonymous-session and email-link both offered; user does not know which to use. + +**Save offered on a form that does not need it.** Quick form gets save mechanic; complexity without payoff. + +--- + +## Methodology-level choices that stay in the public skill + +When save-and-resume helps and does not. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Trust communication discipline. Timing of save offering. Resume experience. Measurement. Save-and-resume for sensitive information. Common failures. + +## Implementation choices that stay internal + +Specific save-and-resume implementations for specific forms. Specific persistence backends and expiration policies. Specific trust copy in brand voice. The team's compliance review processes. These vary by team. diff --git a/skills/multi-step-form-design/references/step-architecture-patterns.md b/skills/multi-step-form-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..de0e936 --- /dev/null +++ b/skills/multi-step-form-design/references/step-architecture-patterns.md @@ -0,0 +1,279 @@ +# Step architecture patterns + +What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. + +The architecture is the structure that makes steps coherent. Bad architecture produces progress-theater (decorative steps); good architecture produces genuinely-staged forms (each step is a coherent unit of work). + +--- + +## The coherence principle + +Each step should represent a coherent unit of work from the user's perspective. + +**The test.** Can the user describe what they just did at the end of the step in one sentence? + +- Coherent: "I told you the basics about my company." +- Atomized: "I typed my company name in a field." + +Coherent answers signal genuinely-staged. Atomized answers signal progress-theater. + +The discipline. Each step should bundle related fields into a single cognitive unit. The user processes the step as a whole, not as 5 isolated fields. + +--- + +## Common step patterns + +Patterns that recur across acquisition, onboarding, and intake forms. + +**Identity step.** Who the user is. + +- Fields: name, email, role. +- Friction level: low. +- Position: opens the form. +- The user provides minimal commitment; the form earns the right to ask for more. + +**Context step.** What the user's situation is. + +- Fields: company size, industry, current setup, current tools. +- Friction level: medium. +- Position: after Identity, before Need. +- The user shares context that lets the form (or the receiving team) understand them. + +**Need step.** What the user is trying to accomplish. + +- Fields: goal, challenge, timeline, urgency. +- Friction level: medium-to-high. +- Position: middle of the form. +- The user articulates intent. This step often includes the highest-value fields for the receiving team. + +**Detail step.** Specifics needed to act on the user's request. + +- Fields: budget, specific requirements, constraints, integrations. +- Friction level: high. +- Position: late in the form. +- The user shares specifics. By this point, commitment is built; the user is more willing to share. + +**Confirmation step.** Review and submit. + +- Fields: review summary, submission action, optional final fields (preferences, follow-up). +- Friction level: low. +- Position: last. +- The user reviews what they provided and submits. + +--- + +## Sequencing principles + +The order of steps matters as much as the steps themselves. + +**Principle 1: Low-friction first.** The opening step should be easy to complete. The user invests their first 30-60 seconds in something simple; commitment compounds. + +**Principle 2: Commitment compounds.** Each step builds on the previous. The user who completed step 2 is more invested than they were before step 1; later steps can ask for more. + +**Principle 3: High-friction at the end.** The most demanding fields (budget, specific requirements, sensitive info) belong later. By that point, the user has invested enough to push through. + +**Principle 4: Confirmation explicit.** A final review-and-submit step lets the user verify their inputs. Reduces submission anxiety. + +**Anti-pattern: high-friction first.** Asking for budget in step 1 depresses completion. The user has not yet committed; the high-friction question feels premature. + +**Anti-pattern: commitment-resetting.** A late step that requires the user to make decisions they thought they had already made. The user feels their earlier work was wasted. + +--- + +## Step coherence test + +For each step, ask: can this step be described in one sentence as a unit of work? + +**Coherent step examples.** + +- "Step 1: tell us who you are." (Identity) +- "Step 2: tell us about your company." (Context) +- "Step 3: tell us what you are trying to accomplish." (Need) +- "Step 4: tell us the specifics so we can help." (Detail) +- "Step 5: review and submit." (Confirmation) + +Each step has a coherent description. The user can predict what is coming and feel they accomplished something at the end of each step. + +**Incoherent step examples (progress-theater).** + +- "Step 1: name and email." +- "Step 2: phone and company." +- "Step 3: role and industry." + +Each step is two fields. The fields are unrelated. The grouping is arbitrary. The user wonders why this is multi-step. + +--- + +## Field count per step + +How many fields per step is too many or too few. + +**Too few.** 1-2 fields per step often signals over-staging. The user wonders why this needed its own step. + +**Right range.** 3-7 fields per step. Enough to represent a coherent unit of work; few enough to complete in 30-60 seconds. + +**Too many.** 10+ fields per step starts to recreate the kitchen-sink-single-page problem within a step. Audit for non-essential fields. + +**The variance.** Some steps may have more fields than others; that is fine if each step's fields cohere. The Detail step often has more fields than the Identity step because it captures more specific information. + +--- + +## Step length variability + +Steps do not have to be the same length. + +**The pattern.** Identity step: 3 fields. Context step: 5 fields. Need step: 4 fields. Detail step: 7 fields. Confirmation step: 1 action. + +The variability is fine because each step represents a coherent unit. The user does not expect equal length; they expect coherence. + +**The progress indicator implication.** A step counter ("Step 2 of 5") may not reflect time-to-complete accurately when steps vary. A progress bar based on percentage of fields complete reflects the variability better. + +--- + +## Conditional step inclusion + +Some forms include or exclude steps based on earlier answers. + +**The pattern.** "If user has a current CRM, include the 'CRM details' step. If not, skip it." + +**Strengths.** + +- Removes irrelevant fields entirely. +- Makes the form feel adaptive. + +**Risks.** + +- Progress indicators must accommodate the variability honestly. +- The user may notice the variability and feel confused. + +**The discipline.** Use conditional steps when the variability genuinely benefits the user; communicate the dynamic nature in the progress indicator if it shifts. + +--- + +## Step transitions + +How the user moves from one step to the next. + +**The forward transition.** A clear "Next" or "Continue" button. Validation runs before the transition. + +**The backward transition.** A "Back" or "Previous" button. The user can return to earlier steps without losing later inputs. + +**The skip transition.** Some forms allow skipping optional steps. Use sparingly; skipping creates inconsistent paths. + +**Transition friction.** Each transition should feel snappy. Loading delays at transitions break the flow. + +**Transition cues.** Brief visual confirmation that the step changed (slide animation, fade transition). Helps the user understand the navigation. + +--- + +## Step naming + +Each step should have a clear name visible to the user. + +**Strong step names.** + +- "Tell us about you." +- "About your company." +- "What you are looking for." +- "The details." +- "Review and submit." + +**Weak step names.** + +- "Step 1," "Step 2," "Step 3." (Numbers without names; user does not know what each represents.) +- "Personal Info," "Company Info," "Other Info." (Generic; does not signal what the step is about.) +- "Contact," "Business," "Submission." (Truncated; does not warm the user.) + +**The voice match.** Step names should match the brand voice. Casual brands use casual names; serious brands use serious names. + +--- + +## Step architecture for specific use cases + +How the architecture varies by form purpose. + +**Lead-capture form (5-8 fields).** + +- Identity (name, email) +- Context (company, role) +- Need (use case, urgency) + +3 steps; the form moves quickly. + +**Demo-request form (10-15 fields).** + +- Identity (name, work email, role) +- Company (name, size, industry) +- Current state (current solution, key pain points) +- Buying intent (timeline, budget range) +- Confirmation + +5 steps; meaningful staging. + +**Application form (20+ fields with documents).** + +- Identity +- Eligibility (qualifying questions) +- Personal details +- Financial details +- Document upload +- Review +- Submit + +7+ steps; long form benefits significantly from staging. + +**Onboarding wizard (configuration-driven).** + +- Welcome +- Account setup +- Use-case selection +- Preferences +- Connect-your-tools +- Confirmation + +6 steps; each step represents a coherent setup unit. + +--- + +## Step architecture audit + +Periodically audit the step architecture. + +**The audit.** + +- Read each step's name. Does it represent a coherent unit? +- Read each step's fields. Do they cohere? +- Check field count per step. Within the 3-7 range? +- Check conversion per step. Are some steps disproportionately drop-off-heavy? + +**The drift.** Steps decay as the form evolves. New fields get added to the wrong step; steps become incoherent; field counts drift. + +**The cure.** Quarterly audit. Re-group fields into the right steps; remove non-essential fields; restructure if the original architecture no longer fits. + +--- + +## Common architecture failures + +**Arbitrary chunking.** Steps that group fields by visual length rather than coherence. + +**Atomized steps.** Each step has 1-2 fields; the user wonders why it is multi-step. + +**Field-count overload.** Some steps have 15+ fields; recreates the kitchen-sink problem within a step. + +**High-friction-first.** Budget or sensitive question in step 1; user is not committed enough to push through. + +**Commitment-resetting steps.** Late steps that require the user to make decisions they thought were already made. + +**Generic step names.** "Step 1, Step 2" without descriptive names; user cannot predict the form. + +**No confirmation step.** Form ends at the data-collection step; user is not given the chance to review. + +--- + +## Methodology-level choices that stay in the public skill + +The coherence principle. Common step patterns. Sequencing principles. The step-coherence test. Field count per step. Step length variability. Conditional step inclusion. Step transitions. Step naming. Step architecture for specific use cases. Step-architecture audit. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific forms. Specific step naming in brand voice. Specific tooling for step transitions and validation. The team's audit calendars. These vary by team and form. diff --git a/skills/multi-step-form-design/references/validation-strategy-patterns.md b/skills/multi-step-form-design/references/validation-strategy-patterns.md new file mode 100644 index 0000000..2c53366 --- /dev/null +++ b/skills/multi-step-form-design/references/validation-strategy-patterns.md @@ -0,0 +1,288 @@ +# Validation strategy patterns + +Per-step vs end-only vs hybrid. Validation message discipline. + +The validation strategy determines when errors are caught and how they are communicated. Done well, validation catches errors helpfully and protects the form from invalid submissions. Done poorly, validation rejects valid inputs or surfaces errors at the worst time. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. Errors caught too early feel intrusive; errors caught too late waste the user's investment. + +**The win.** A user enters an invalid email; inline validation catches it immediately; the user fixes it and continues. + +**The fail (too early).** A user is mid-typing an email; "must contain @" appears before they have finished typing. + +**The fail (too late).** A user completes 5 steps; submission fails because of a step-1 error they did not see flagged. + +The strategy choice depends on the form's length, the audience, and the validation complexity. + +--- + +## Pattern A: Per-step validation + +Each step's fields are validated before allowing progression to the next step. + +**How it works.** + +- The user completes the current step. +- Validation runs on all fields in the step. +- If errors exist, they are shown; the Next button does not advance. +- The user fixes errors and proceeds. + +**Strengths.** + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +**Weaknesses.** + +- Can feel intrusive if validation is too strict on every step transition. +- May block the user from progressing when they want to revise the field later. + +**When to use.** Default for most multi-step forms. Each step's data is validated as a coherent unit. + +--- + +## Pattern B: End-only validation + +All validation runs at submission. + +**How it works.** + +- The user completes all steps. +- Validation runs only when the user clicks Submit. +- All errors surface at once. + +**Strengths.** + +- User completes uninterrupted. +- Validation logic is simpler (one validation pass). + +**Weaknesses.** + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. +- Errors that span multiple steps are confusing to surface. + +**When to use.** Rarely. Sometimes appropriate for very short forms where per-step validation overhead is not worth it. + +--- + +## Pattern C: Hybrid + +Required-field validation per step; full validation at end. + +**How it works.** + +- Per-step: critical errors (missing required fields, malformed email format) catch immediately. +- End: nuanced validation (cross-field consistency, business rules) catches at submission. + +**Strengths.** + +- Combines the responsiveness of per-step with the simplicity of end-only. +- The user gets immediate feedback on critical issues. +- Complex validation logic does not interrupt the flow. + +**Weaknesses.** + +- More complex to design (two validation tiers). +- Risk of inconsistent user experience if the tiers are not well-coordinated. + +**When to use.** When validation has both critical-immediate components (required fields, format checks) and nuanced-end components (cross-field rules, business logic). The default pattern for most multi-step forms with significant validation needs. + +--- + +## Pattern D: Real-time validation + +Validation runs as the user types or interacts with each field. + +**How it works.** + +- As the user types, validation runs on the field. +- Errors appear inline as soon as they are detectable. +- Some implementations validate on field blur (when the user leaves the field) rather than every keystroke. + +**Strengths.** + +- Earliest possible error detection. +- User sees the result of their input immediately. + +**Weaknesses.** + +- Can feel intrusive if validation appears before the user finishes typing. +- Real-time validation on complex rules can lag. +- Easy to surface errors prematurely. + +**When to use.** When the validation is simple enough to run instantly (format checks) and when the audience benefits from immediate feedback. Best practice: validate on blur rather than every keystroke. + +--- + +## Validation message discipline + +The error messages themselves matter. + +**Helpful messages.** + +- "Phone number must include area code" (specific guidance). +- "Try a value between 1 and 1000" (specific range). +- "Email must include @ and a domain" (specific format). +- "This field is required" (when blank). + +**Unhelpful messages.** + +- "Invalid input" (generic). +- "Error" (no information). +- "Out of range" (no range specified). +- "You must enter..." (scolding tone). + +**Tone discipline.** Messages should be helpful, not scolding. "Try a value between 1 and 1000" beats "You must enter a value between 1 and 1000." + +**Specificity.** "Phone number must be 10 digits" beats "Invalid phone number." Specific guidance lets the user fix the issue immediately. + +--- + +## Inline placement + +Where errors appear matters. + +**Inline placement.** Errors appear next to the field that triggered them. The user sees the error in context. + +**Banner placement.** Errors appear in a banner at the top of the step. Easy to miss; less helpful. + +**Mixed placement.** Some errors inline, some in a banner. Confusing. + +The discipline. Inline placement is the default. Banners can supplement (summarizing all errors on the step) but should not replace inline. + +--- + +## Validation timing + +When validation triggers. + +**On blur.** Validation runs when the user leaves the field. Default for most field types. + +**On change.** Validation runs as the user types. Useful for some real-time feedback (password strength, character count) but intrusive for most validation. + +**On submit.** Validation runs when the user clicks the Next or Submit button. Always required as the final check. + +The combination matters. Most fields work well with on-blur for individual validation plus on-submit for final check. + +--- + +## Cross-field validation + +Validation that depends on multiple fields. + +**Examples.** + +- "End date must be after start date." +- "Sum of allocations must equal 100 percent." +- "If selected 'enterprise,' company size must be above 200." + +**The challenge.** Cross-field validation does not fit per-field timing. The validation can only run when both fields have values. + +**Approaches.** + +- **End-only validation for cross-field rules.** The cross-field check runs at submission. +- **End-of-step validation.** The cross-field check runs when the step containing both fields is completed. +- **Reactive cross-field validation.** Each time either field changes, the cross-field check runs. + +The choice depends on the form's complexity and the user's likely workflow. + +--- + +## Validation strictness + +How aggressively to reject inputs. + +**Too strict.** Rejects valid inputs because the validation is over-specified. "Email format invalid" for an email with a plus-sign alias. + +**Too loose.** Accepts invalid inputs that fail at submission. The user finds out late. + +**The right strictness.** Match validation rules to actual business requirements. Do not reject inputs the system can handle; do not accept inputs the system will choke on. + +**Common over-strictness mistakes.** + +- Email validation that rejects plus-sign aliases. +- Phone validation that rejects international formats. +- Name validation that rejects non-Latin characters. +- Address validation that rejects valid international addresses. + +The discipline. Validation should reflect what the system actually requires, not what is stereotypical. + +--- + +## Validation and accessibility + +Validation must work for users with assistive technology. + +**Screen reader announcements.** Errors should be announced when they appear. ARIA live regions for inline errors; focus management for error summaries. + +**Keyboard navigation.** Users should be able to navigate to error messages with keyboard alone. + +**Visual cues alongside text.** Color-coding for errors should not be the only signal; text labels and icons help users who cannot perceive color. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Validation and mobile + +Mobile validation has specific considerations. + +**Touch-friendly error states.** Error indicators should be visible without pinch-zoom. + +**Inline placement on mobile.** Errors appearing below or above the field; do not push critical content off-screen. + +**Mobile keyboards.** Use input types (email, tel, number) so mobile keyboards adapt; this also helps validation. + +**Real-time validation latency.** On mobile, real-time validation can lag and feel sluggish; default to on-blur for performance. + +--- + +## Validation testing + +Test validation across edge cases. + +**Test cases to include.** + +- Empty required fields. +- Format-invalid inputs (malformed emails, invalid phone numbers). +- Format-valid but business-invalid inputs (email without account, valid date in the past for a future-only field). +- Boundary inputs (minimum, maximum, just-outside). +- Special characters and international inputs. + +**The discipline.** Validation should pass valid inputs and reject invalid ones consistently. Test with realistic edge cases the audience will encounter. + +--- + +## Common validation failures + +**Generic error messages.** "Invalid input" without guidance. + +**Over-strict validation.** Rejecting valid inputs that fall outside narrow expectations. + +**Late validation.** Errors caught only at submission for issues that should have surfaced earlier. + +**Banner-only error placement.** User cannot see which field has the issue. + +**Validation that rejects internationally.** US-only formatting rules applied to international audiences. + +**Inconsistent validation rules.** Same field validated differently in different contexts. + +**Validation without accessibility.** Errors invisible to screen readers; color-only cues. + +**Validation that interrupts typing.** Real-time validation surfacing errors before the user finishes typing. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Validation message discipline (helpful vs unhelpful). Inline placement. Validation timing. Cross-field validation. Validation strictness. Validation and accessibility (cross-reference). Validation and mobile. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific forms. Specific tooling for validation implementation. Specific brand-voice error messages. The team's accessibility review processes. These vary by team. diff --git a/skills/okr-design/SKILL.md b/skills/okr-design/SKILL.md new file mode 100644 index 0000000..83f3ea1 --- /dev/null +++ b/skills/okr-design/SKILL.md @@ -0,0 +1,310 @@ +--- +name: okr-design +description: "OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the difference between sandbagged OKRs (always 100%) and aspirational OKRs (always 30%) and stretch OKRs (genuine ambition with quarterly accountability). Triggers on OKR design, OKR setting, key result design, OKR scoring, mid-quarter recalibration, OKR cascading, outcomes vs outputs, quarterly planning, goal setting. Also triggers when a team's OKRs are always hit and producing no learning, when OKRs are demoralizing because they were set as fantasy, or when the team uses OKR vocabulary but the practice has decayed." +category: product +catalog_summary: "OKR design discipline. Outcome statements, key results, scoring, mid-quarter recalibration. Distinguishes sandbagged OKRs (always hit, useless) from aspirational fantasy (impossible, demoralizing) from stretch OKRs (genuine ambition with quarterly accountability)" +display_order: 12 +--- + +# OKR Design + +A senior product leader's playbook for OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the practical disciplines that distinguish OKRs from quarterly to-do lists or impossible-fantasy goal-setting. + +OKRs are accountability infrastructure. When designed well, they produce a quarterly rhythm of ambitious goal-setting, mid-quarter learning, end-of-quarter scoring, and adjustment for the next quarter. When designed badly, they become a tax on the team that produces no signal: sandbagged OKRs that always hit 100% (no ambition, no learning), aspirational fantasy OKRs that nobody can hit (demoralizing, ignored after week 2), or vague OKRs that the team scores generously regardless of outcome. + +This skill is OKR design as practical methodology. The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, key results that actually measure the outcome, scoring honestly even when uncomfortable, recalibrating mid-quarter when warranted, and using the OKR review cadence to drive learning rather than performance theater. + +The voice is the senior product leader who has run OKRs in healthy organizations and watched the practice decay in others. Concrete, opinionated about what actually works, willing to call out the failure modes that conference talks gloss over. + +When to use this skill: designing OKRs for the next quarter, auditing why current OKRs are not driving decisions, recalibrating an OKR practice that has decayed, or onboarding a team to OKRs that has never used them. + +--- + +## What this skill is for + +This skill spans OKR design and the operational rhythm around them. The PM-skill distinction: + +- **`okr-design` (this skill)** is outcomes (results to be achieved). +- `roadmap-planning` is outputs (features and initiatives sequenced). +- `feature-launch-playbook` is post-ship execution. +- `product-analytics-setup` is measurement infrastructure (the metrics that key results depend on). +- `experiment-design` is the discipline for testing whether specific initiatives produce outcomes. +- `discovery-research-synthesis` informs which outcomes to pursue. + +The audience: senior PMs, product directors, engineering leaders, executives setting org-wide OKRs, in-house teams operating in OKR-driven cultures. + +What is not in scope: the broader strategic planning that decides which outcomes matter (other strategy frameworks); the execution of specific initiatives toward OKRs (covered by roadmap-planning, pm-spec-writing, feature-launch-playbook); the analytics infrastructure (covered by product-analytics-setup, analytics-strategy). + +--- + +## Sandbagged vs aspirational-fantasy vs stretch + +The keystone framing. + +**Sandbagged.** OKRs designed to hit 100%. The key results target outcomes the team is already on track to deliver. End of quarter: 100% scores across the board. The team celebrates; nobody learns anything. Output: an OKR practice that produces no signal. The team has the same OKRs every quarter dressed in different vocabulary because nothing pushes them past where they would have gone anyway. + +**Aspirational-fantasy.** OKRs that nobody can hit. 1000% growth in 90 days. Demoralizing, performative, ignored after week 2. Teams that ship aspirational-fantasy OKRs typically discover by week 6 that no realistic effort path produces the targets; they disengage; the OKRs become decoration on the planning doc that nobody references. + +**Stretch.** Genuine ambition with quarterly accountability. Designed to hit 60-70% on average. Hits and misses both teach something. The 60% case ("we hit 60% of our key results") is informative about what the team can deliver in a quarter; the 100% case is rare and usually signals sandbagging in retrospect; the 30% case signals either fantasy or the team encountered something unexpected (which is also informative). + +The litmus test. Look at the team's last four quarters of OKRs. If the average score is 95%+, the OKRs are sandbagged. If the average is below 30%, they are fantasy. If the average is 50-75%, the design is in the stretch zone. Adjust upcoming OKRs to bring the practice into stretch territory. + +--- + +## Objective design + +Objectives are outcome statements. They name what the team is trying to achieve in the quarter. + +**Strong objective characteristics.** + +- Outcome-focused, not output-focused. "Improve activation for new sign-ups" is an outcome; "Ship the new onboarding flow" is an output. +- Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. +- Inspiring without being fantasy. The team should feel pulled toward the objective, not crushed by it. +- Few in number. Most teams should have 2-4 objectives per quarter; more than 5 dilutes focus. + +**Worked examples.** + +- "Improve activation for new sign-ups so that more reach the value-realization moment within the first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +**Weak objective characteristics.** + +- Output-disguised-as-outcome. "Ship the activation redesign" is an output; the objective should be the result the redesign is meant to produce. +- Too vague. "Improve user experience" is too broad to focus quarterly work. +- Too tactical. "Refactor the auth service" is a tactical decision, not a quarterly objective. +- Too many. 8 objectives produces no focus; the team works on too many things and excels at none. + +Detail in [`references/objective-design-patterns.md`](references/objective-design-patterns.md). + +--- + +## Key result design + +Key results measure progress toward the objective. They are the quantitative or testable indicators that show whether the objective is being achieved. + +**Strong key result characteristics.** + +- Measurable. There is a specific number or testable threshold. +- Outcome-aligned. Achieving the key result actually moves the objective forward. +- Within team influence. The team can affect the key result through their work. +- Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +**Worked example.** Objective: "Improve activation for new sign-ups." + +Strong key results: + +- "Increase the percentage of new sign-ups reaching the value-realization moment within their first week from 32% to 45%." +- "Reduce the median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on the onboarding flow (up from 64%)." + +Each key result is measurable, ties to activation, the team can influence it through onboarding redesign work, and is time-bounded to the quarter. + +**Weak key results.** + +- Vague: "Improve activation significantly." +- Output: "Ship 5 onboarding redesign initiatives." (counts work done, not outcomes produced.) +- Outside influence: "Increase total signups by 50%." (signups are mostly upstream of activation work.) +- Vanity: "Reach 1M users." (impressive number; not directly tied to activation outcome.) + +**The 3-5 key results rule.** Most objectives benefit from 3-5 key results. One key result is fragile (single measurement may not capture the outcome); 6+ key results dilute focus. + +Detail in [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md). + +--- + +## Cascading OKRs across the org + +When and how to cascade OKRs from leadership to teams. + +**The trade-off.** + +- Cascaded OKRs ensure team work aligns with company priorities. The product team's objective derives from the company's objective; the engineering team's objective derives from the product team's. +- Strict cascading produces top-down OKRs that miss bottom-up insight. The team closer to the work sometimes knows what to prioritize better than the layer above. +- Too-loose cascading produces team OKRs that do not connect to company priorities; teams optimize locally without contributing to org goals. + +**The middle path.** + +- Company-level OKRs set quarterly. Team-level OKRs set with reference to company OKRs but with team-level autonomy on how to contribute. +- Each team's OKRs explicitly identify which company OKRs they ladder up to. +- Some team OKRs may be team-specific (technical debt, infrastructure, experimentation infrastructure) without direct company-OKR ladders. Surface these explicitly so the team's full work is visible. + +**When to cascade strictly.** Early-stage companies aligning around a small number of company priorities. Times of strategic shift where the org needs to move in a coordinated direction. + +**When to cascade loosely.** Mature organizations with established team mandates. Cross-functional teams where strict cascading would over-constrain. + +**The honest disclosure.** Cascading is harder than conference talks suggest. Most orgs over-cascade in the first few cycles and learn to relax it; some never learn and produce OKRs that are increasingly performative as they propagate down. + +Detail in [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md). + +--- + +## Scoring discipline + +End-of-quarter scoring is where OKR practice succeeds or decays. + +**The 0.0-1.0 scale.** Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +**The 60-70% target.** Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. Higher average suggests sandbagging; lower suggests fantasy or unexpected disruption. + +**Scoring honesty.** + +- Score the actual outcome, not the effort. The team that worked hard but did not move the metric scores low; the team that got lucky and moved the metric without much effort scores high. The score reflects outcome. +- Do not round up. A key result at 0.55 is 0.55, not 0.6. Honest scoring produces honest signal. +- Acknowledge what changed mid-quarter. Some misses reflect priority shifts; surface those without using them as excuses. + +**What 100% means.** 100% scores warrant scrutiny. Either the OKR was sandbagged (under-set), the team had a great quarter (informative), or the team is rounding up. Investigate which. + +**What 30% means.** 30% scores warrant scrutiny. Either the OKR was fantasy (over-set), the team encountered unexpected disruption (informative), or the work was deprioritized mid-quarter (also informative). Investigate which. + +**The compensation question.** OKRs work best when not directly tied to compensation. When OKRs determine bonuses, sandbagging incentives become severe; teams set OKRs they know they can hit. Most healthy OKR cultures separate goal-setting from compensation. + +Detail in [`references/scoring-discipline.md`](references/scoring-discipline.md). + +--- + +## Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. + +**The default.** OKRs hold for the quarter. Teams adapt their tactics to the OKR; OKRs do not change to match what the team is doing. + +**When to recalibrate.** + +- Strategic shift. The company's strategy changed materially mid-quarter; OKRs that no longer reflect the strategy are no longer the right targets. +- Major external disruption. A market change, regulatory event, or significant outage warrants resetting the quarter's targets. +- Information that invalidates the OKR. The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +**When NOT to recalibrate.** + +- The team is not on track. OKRs that are missing should remain as set; the miss is the signal. +- The OKR is uncomfortable. Teams uncomfortable with stretch OKRs should not lower them mid-quarter to feel better. +- Easier OKRs would feel achievable. The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +**The recalibration discipline.** Recalibration should be rare (1-2 quarters out of 8). Frequent recalibration signals OKR design failure: either too aggressive or not strategically aligned. The recalibration itself should be transparent: surface what changed, why, and what the new targets are. + +Detail in [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md). + +--- + +## The OKR review cadence + +OKRs benefit from a structured review rhythm. + +**Weekly check-ins.** + +- Team reviews progress on each key result. 15-30 minutes. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Not for adjusting OKRs; for adjusting tactics to keep moving toward them. + +**Mid-quarter review.** + +- Roughly week 6 of the quarter. 60-90 minutes. +- Honest assessment of trajectory: which key results are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +**End-of-quarter review.** + +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +**Quarterly retrospective.** + +- Distinct from the scoring review. The retrospective examines the OKR practice itself: were the OKRs the right ones, did the cadence work, what should change. +- Often combined with the next-quarter OKR setting session. + +Detail in [`references/review-cadence-templates.md`](references/review-cadence-templates.md). + +--- + +## OKRs vs roadmap items vs metrics + +Three concepts often conflated. Each serves a different purpose. + +**OKRs.** Outcome targets for the quarter. "Improve activation for new sign-ups" is an OKR; "Increase first-week activation rate from 32% to 45%" is a key result. + +**Roadmap items.** Initiatives the team is building or doing. "Onboarding redesign" is a roadmap item. Roadmap items contribute to OKRs but are not the OKRs themselves. + +**Metrics.** Ongoing measurements the team tracks. "First-week activation rate" is a metric. Metrics inform key results (which are quarterly targets on metrics) and are tracked continuously regardless of whether the team has an OKR aimed at them. + +**The relationship.** + +- OKR: "Improve activation for new sign-ups." +- Key result: "First-week activation rate from 32% to 45%." +- Metric: "First-week activation rate" (tracked continuously). +- Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +**Common conflations.** + +- Treating roadmap items as OKRs. "Ship the onboarding redesign" as an OKR; the OKR should be the outcome the redesign is meant to produce. +- Treating every metric as needing an OKR. Some metrics matter for the team to track without setting quarterly targets on them. +- Treating OKRs as roadmap commitments. OKRs name outcomes; the team is committed to pursuing them but may shift tactics; treating OKRs as roadmap commitments locks in tactics that may need to change. + +Detail in [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-okr-failures.md`](references/common-okr-failures.md). + +- "Our OKRs are always 100% and produce no signal." Sandbagged. Set with stretch ambition; expect 60-70% scores. +- "Our OKRs are always 30% and demoralizing." Fantasy. Recalibrate to genuine stretch; investigate whether the targets are achievable in any realistic effort path. +- "Our key results measure work, not outcomes." Output-disguised-as-outcome. Rewrite key results to measure the result, not the work. +- "We have 12 OKRs and the team is working on 47 things." Too many OKRs; cap at 2-4 objectives, 3-5 KRs each. +- "Our OKRs are vague." Lack measurable targets; rewrite key results with specific numbers and thresholds. +- "Our cascading produces team OKRs that do not match team work." Strict cascading mismatched to team mandate; loosen cascading or change team mandate. +- "We never recalibrate even when the strategy shifts." Recalibration too tightly avoided; surface strategic-shift criteria and use them. +- "We recalibrate every quarter." Recalibration too easy; OKR design is failing; investigate. +- "Our weekly check-ins became status reports." Tactical-discussion missing; reform the check-in format. +- "Our scoring rounds up." Scoring discipline missing; commit to honest scoring. +- "OKRs and bonuses are tied; people sandbag." Predictable; decouple OKRs from compensation. + +--- + +## The framework: 12 considerations for OKR design + +When designing or auditing OKRs, walk these 12 considerations. + +1. **Stretch, not sandbagged or fantasy.** 60-70% average score target. +2. **Objectives are outcomes, not outputs.** What we are trying to achieve. +3. **Few objectives, well-focused.** 2-4 per team per quarter. +4. **Key results are measurable.** Specific numbers or testable thresholds. +5. **Key results are outcome-aligned.** Achieving them moves the objective forward. +6. **Key results are within team influence.** Not entirely dependent on external factors. +7. **3-5 key results per objective.** Single key results are fragile; many dilute focus. +8. **Cascading explicit but not over-constrained.** Team OKRs ladder up but with autonomy on how. +9. **Scoring honest, not rounded.** 0.0-1.0 reflects actual outcomes. +10. **Recalibration rare.** OKRs hold absent strategic shift or major disruption. +11. **Review cadence weekly + mid-quarter + end-of-quarter.** Tactical, then strategic, then scoring. +12. **OKRs separate from roadmap items and metrics.** Each serves a different purpose. + +The output of the framework is OKRs that produce quarterly accountability infrastructure: ambitious goal-setting, mid-quarter learning, end-of-quarter scoring honest enough to inform the next quarter. + +--- + +## Reference files + +- [`references/objective-design-patterns.md`](references/objective-design-patterns.md) - Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. +- [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md) - Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. +- [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md) - When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. +- [`references/scoring-discipline.md`](references/scoring-discipline.md) - The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. +- [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md) - When to recalibrate vs adapt tactics. Strategic shift vs uncomfortable OKRs. The recalibration discipline. +- [`references/review-cadence-templates.md`](references/review-cadence-templates.md) - Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. +- [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md) - The three concepts and their relationships. Common conflations. The complete picture across all three. +- [`references/okr-anti-patterns.md`](references/okr-anti-patterns.md) - 8+ anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling. +- [`references/common-okr-failures.md`](references/common-okr-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: OKRs are accountability infrastructure + +OKRs at their best produce quarterly accountability that informs the org's strategic learning. The team commits to outcomes; works toward them; scores honestly; learns from the gap between target and outcome; designs the next quarter's OKRs better. + +OKRs at their worst produce ritual that consumes time without producing signal. Sandbagged OKRs that always hit. Fantasy OKRs that nobody can. Vague OKRs that score generously regardless of outcome. The vocabulary persists; the practice has decayed. + +The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, measurable key results, stretch ambition, scoring honesty, recalibration only when warranted, and the review cadence that drives learning rather than performance theater. + +When in doubt about whether an OKR practice is working, ask: do the OKRs drive decisions about what to prioritize, do the scores produce learning that informs the next quarter, are key results actually measuring outcomes the team can influence, is the average score in the 60-70% range that stretch OKRs target? If yes to all of those, the practice is real. If no to any, the gap is where the OKR work is failing to produce the accountability infrastructure it is meant to provide. diff --git a/skills/okr-design/references/cascading-okrs-decisions.md b/skills/okr-design/references/cascading-okrs-decisions.md new file mode 100644 index 0000000..9ce7eb6 --- /dev/null +++ b/skills/okr-design/references/cascading-okrs-decisions.md @@ -0,0 +1,187 @@ +# Cascading OKRs decisions + +When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. + +Cascading is one of the most contested OKR practices. Conference talks describe clean ladders from company to team to individual; in practice, strict cascading produces over-constrained team OKRs, while loose cascading produces team work disconnected from company priorities. The middle path is harder than the talks suggest. + +--- + +## The trade-off + +Cascading exists on a spectrum. + +**Strict cascading.** + +- Company sets OKRs. +- Each function (product, engineering, sales) cascades to function-level OKRs. +- Each team cascades to team OKRs. +- Each individual cascades to personal OKRs. +- All ladders trace cleanly upward. + +**Loose cascading.** + +- Company sets OKRs. +- Teams set their own OKRs informed by company priorities but with autonomy on scope and contribution. +- Teams may set OKRs not directly tied to company OKRs (technical debt, team-specific work). +- Individual OKRs often skipped. + +**The trade-off.** + +- Strict produces alignment but over-constrains. Teams set OKRs they think leadership wants rather than OKRs they can credibly commit to. +- Loose produces autonomy but risks misalignment. Team work optimizes locally without contributing to org goals. + +--- + +## When to cascade strictly + +**Early-stage companies aligning around small priorities.** When the company has 2-3 critical priorities and everyone needs to focus on them, strict cascading enforces the focus. + +**Times of strategic shift.** When the company is changing direction (new market, new segment, new product line), strict cascading helps the org turn together. + +**Crisis or focus periods.** When the company faces a specific challenge requiring all hands, strict cascading ensures everyone is rowing the same direction. + +**Common to these cases:** strategic clarity is high, alignment is more valuable than autonomy, and the org has fewer concurrent priorities to balance. + +--- + +## When to cascade loosely + +**Mature organizations with established mandates.** Teams have clear scope; their OKRs naturally fit company priorities through team mandate; strict cascading adds overhead without value. + +**Cross-functional teams where strict cascading would over-constrain.** Teams that span functions cannot cleanly ladder to a single function-level OKR; loose cascading lets them pursue cross-functional outcomes. + +**High-trust environments.** Teams trusted to set their own OKRs and credibly commit to them; the org accepts the autonomy in exchange for the engagement and creativity it produces. + +**Common to these cases:** team mandates are clear, autonomy is more valuable than tight alignment, and the org tolerates some local optimization in exchange for team engagement. + +--- + +## The middle path + +Most healthy OKR cultures sit between strict and loose. + +**The pattern.** + +- Company sets 3-5 OKRs at the start of the quarter. +- Teams set OKRs that explicitly identify which company OKRs they ladder up to (when applicable). +- Teams have autonomy on how to contribute (which key results, which initiatives, what scope). +- Some team OKRs are team-specific (technical debt, infrastructure, experimentation foundations) without direct company ladders. Surface these explicitly. +- Individual OKRs are usually skipped; commitment is at the team level. + +**The "explicit ladder when applicable" rule.** Each team OKR either: + +- Explicitly identifies the company OKR it ladders to. +- Explicitly identifies that it is team-specific without a company ladder. + +Both are honest; the failure mode is implicit ambiguity where the team is not sure whether their OKR connects to anything. + +--- + +## Worked example: middle path + +Company OKRs for Q3: + +1. Improve net new ARR through enterprise segment growth. +2. Improve activation for self-serve sign-ups. +3. Reduce infrastructure costs through architecture optimization. + +Product team OKRs: + +- "Improve activation for new sign-ups" (ladders to company OKR 2). +- "Establish enterprise-readiness foundations" (ladders to company OKR 1). +- "Reduce technical debt in the activation funnel" (team-specific; does not ladder directly). + +Engineering team OKRs: + +- "Ship onboarding redesign by week 6" (ladders to company OKR 2 via product team OKR). +- "Migrate to new search architecture" (ladders to company OKR 3). +- "Strengthen test coverage in critical paths" (team-specific). + +Sales team OKRs: + +- "Close 8 enterprise deals in Q3" (ladders to company OKR 1). +- "Improve discovery-call to demo conversion from 24% to 35%" (ladders to company OKR 1). +- "Build the design partner program" (team-specific). + +The pattern. Most team OKRs ladder up; some are team-specific. Each ladder is explicit. Teams have autonomy on how they contribute (which KRs, which initiatives). + +--- + +## Cascading anti-patterns + +**Strict cascading enforced top-down without team input.** Team OKRs become wishlist receivers from leadership; commitment is shallow because the team did not author what they are committing to. + +**Loose cascading without explicit ladders.** Team OKRs are set without any visible connection to company priorities. Some team work happens to align; some does not. Leadership cannot tell what is contributing to company OKRs. + +**Cascade theater.** OKR documents include ladders that look connected but do not actually drive anything. The team's work shows up the same regardless of which company OKR they "ladder to." + +**Over-cascading.** Every team OKR is required to ladder to a company OKR. Teams contort their work to fit. Team-specific work (technical debt, infrastructure) gets dressed up as ladder work or gets de-prioritized despite being important. + +**Personal OKRs as default.** Individual OKRs cascaded down. Most OKR cultures find this produces overhead without proportional value; commitment at team level is usually sufficient. + +--- + +## Cascading and team mandate + +Teams whose OKRs do not naturally ladder to company priorities often have a team-mandate problem. + +**The signal.** A team consistently sets OKRs that are team-specific. None of their work ladders to company priorities. + +**The interpretation.** + +- Possibly the team's mandate does not match the company's current priorities. Either the mandate should change (broader scope, different focus) or the team's work is not strategically critical (consider deprioritizing or restructuring). +- Possibly the team's work is foundational and supports many company priorities indirectly (platform teams, infrastructure teams). Their OKRs may legitimately be team-specific. + +**The audit.** Annually, review whether team mandates match company strategy. Teams whose mandates have drifted from strategy benefit from explicit redirection. + +--- + +## Cascading frequency + +The cascading work happens at OKR-setting time (start of quarter) and is generally locked for the quarter. + +**Quarterly cascading.** Most common. Company OKRs set; teams cascade; quarter executes. + +**Mid-quarter cascade revision.** Rare. Strategic shift mid-quarter may warrant rewriting team OKRs. See `mid-quarter-recalibration.md`. + +**The honest frequency.** Most orgs over-cascade in the first few quarters of OKR adoption (treating cascading as a thing to perfect) and learn to relax it. Some orgs never relax and produce increasingly performative cascading. Recognize the pattern; loosen when it stops adding value. + +--- + +## Cascading and individual goals + +Individual goals are usually a separate practice from OKRs. + +**Common patterns.** + +- Team OKRs commit at team level; individual contributors work toward team OKRs without separate personal OKRs. +- Individual goals (career development, skill-building, role expectations) live in performance management, separate from OKRs. +- Some orgs do cascade to individual OKRs; most find this produces overhead without value and stop after a few cycles. + +**The discipline.** Be intentional about whether to cascade to individuals. The default should be "no, commit at team level"; individual cascading should be justified rather than assumed. + +--- + +## Common cascading failures + +**Top-down enforced cascading.** Teams receive OKRs from leadership; commitment is shallow. + +**Implicit cascading.** Team OKRs do not explicitly identify their ladders; alignment is ambiguous. + +**Over-cascading.** Every team OKR forced to ladder to company; team-specific work dressed up artificially. + +**Cascade theater.** Ladders documented but not driving anything. + +**Personal-OKR overhead.** Individual cascading without proportional value. + +**Mandate-strategy drift.** Teams with mandates disconnected from current strategy producing OKRs that ladder to nothing. + +--- + +## Methodology-level choices that stay in the public skill + +The cascading trade-off. When to cascade strictly and loosely. The middle path with explicit ladders. Worked example. Cascading anti-patterns. Team mandate considerations. Cascading frequency. Individual goals separation. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that visualize ladders. Specific cascade-review meeting formats. Specific role-based templates. The team's own conventions for surfacing team-specific OKRs. These vary by org and tooling. diff --git a/skills/okr-design/references/common-okr-failures.md b/skills/okr-design/references/common-okr-failures.md new file mode 100644 index 0000000..675ddb3 --- /dev/null +++ b/skills/okr-design/references/common-okr-failures.md @@ -0,0 +1,205 @@ +# Common OKR failures + +Eleven-plus failure patterns with diagnoses and cures. Cross-references the OKR anti-patterns reference; this file covers operational failures that arise during the OKR cycle. + +The cross-cutting pattern: most OKR failures share a single root, which is treating OKRs as ceremony rather than as accountability infrastructure. + +--- + +## Failure 1: Our OKRs are always 100% and produce no signal + +**Symptom.** End-of-quarter scoring shows the team hitting 95%+ on every KR. The OKR practice feels positive but does not produce learning. + +**Diagnosis.** Sandbagging. Targets set at or below the team's natural trajectory. The OKR practice has decayed into "what we know we can hit." + +**Cure.** Set targets above the historical trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The target should be meaningfully above that. + +**Prevention.** Track the average score over multiple quarters. Drift toward 0.85+ is a sandbagging signal; intervene before the practice fully decays. + +--- + +## Failure 2: Our OKRs are always 30% and demoralizing + +**Symptom.** End-of-quarter scoring shows the team consistently missing OKRs. Team disengages from OKRs by mid-quarter. + +**Diagnosis.** Aspirational fantasy. Targets have no realistic effort path. The OKR practice has decayed into "inspirational numbers nobody believes." + +**Cure.** Recalibrate to genuine stretch. Validate against the effort-path test: can the team identify specific initiatives that would produce the target? + +**Prevention.** During OKR setting, require effort-path reasoning. If the team cannot articulate what work would produce the target, the target is fantasy. + +--- + +## Failure 3: Our key results measure work, not outcomes + +**Symptom.** KRs read as roadmap items. "Ship X by Y." "Run Z interviews." + +**Diagnosis.** Output-disguised-as-outcome. The team is committing to work, not to results. + +**Cure.** Rewrite each output KR to measure the outcome the output is meant to produce. The output itself lives in the roadmap. + +**Prevention.** During KR drafting, apply the outcome test: is this measuring a result, or counting work? + +--- + +## Failure 4: We have 12 OKRs and the team is working on 47 things + +**Symptom.** Quarterly OKRs span many objectives and KRs; the team's work is scattered across many priorities. + +**Diagnosis.** OKR proliferation. Too many objectives produces no focus. + +**Cure.** Cap at 2-4 objectives, 3-5 KRs each. Surface deferred work explicitly so the team can see what they are choosing not to commit to. + +**Prevention.** Cap OKRs at the start of the cycle. Adding "just one more" OKR is a recurring pressure that should be resisted. + +--- + +## Failure 5: Our OKRs are vague + +**Symptom.** Objectives like "improve user experience" or KRs like "make activation better." Cannot be scored honestly. + +**Diagnosis.** Lack of measurable specificity. + +**Cure.** Rewrite KRs with specific numbers, baselines, and targets. "Increase first-week activation rate from 32% to 45%" instead of "improve activation." + +**Prevention.** During KR review, apply the specificity test: could two reasonable people disagree on whether this KR was hit at end of quarter? If yes, it is too vague. + +--- + +## Failure 6: Our cascading produces team OKRs that do not match team work + +**Symptom.** Team OKRs cascade to company OKRs but the team's actual capacity and mandate produce different work. + +**Diagnosis.** Strict cascading mismatched to team mandate. + +**Cure.** Loosen cascading; allow team-specific OKRs that do not directly ladder. Or change team mandate if it does not match strategy. + +**Prevention.** Use the middle path on cascading. Surface team-specific OKRs explicitly. + +--- + +## Failure 7: We never recalibrate even when the strategy shifts + +**Symptom.** The org's strategy changed mid-quarter. Team OKRs no longer reflect strategy. The team holds them anyway. + +**Diagnosis.** Recalibration too tightly avoided. + +**Cure.** Surface the strategic shift; recalibrate the affected OKRs explicitly. Document the trigger. + +**Prevention.** Make strategic-shift criteria for recalibration explicit. The team should know when recalibration is appropriate. + +--- + +## Failure 8: We recalibrate every quarter + +**Symptom.** OKRs get revised mid-quarter routinely. The team uses recalibration to soften uncomfortable OKRs. + +**Diagnosis.** Recalibration too easy. OKR design is failing or stretch ambition is being avoided. + +**Cure.** Hold OKRs absent the recalibration triggers (strategic shift, major disruption, invalidating information). Investigate why frequent recalibration is happening. + +**Prevention.** Track recalibration frequency. Drift toward "every quarter recalibrates" is a signal to intervene. + +--- + +## Failure 9: Our weekly check-ins became status reports + +**Symptom.** Weekly OKR check-ins lost their tactical decision focus; they became "here's what I did this week" updates. + +**Diagnosis.** Check-in format drift. The session is no longer producing tactical adjustments. + +**Cure.** Reform the format. Per KR: trajectory, blockers, planned work for the upcoming week. End with explicit commitments. + +**Prevention.** The team lead facilitates the check-in's tactical scope. Status reports happen elsewhere. + +--- + +## Failure 10: Our scoring rounds up + +**Symptom.** End-of-quarter scoring shows 0.85 average. Closer inspection shows scores were rounded up across most KRs. + +**Diagnosis.** Generous scoring. Honesty has decayed. + +**Cure.** Commit to honest scoring. A 0.55 KR scores 0.55, not 0.6. Document context; the context surfaces what produced the actual outcome regardless of the number. + +**Prevention.** Surface the rounding pattern explicitly. The team should know that rounding up is the failure mode. + +--- + +## Failure 11: OKRs and bonuses are tied; people sandbag + +**Symptom.** OKR scores directly determine bonuses. Targets set conservatively; scoring round up; stretch ambition gone. + +**Diagnosis.** Compensation coupling. + +**Cure.** Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs. + +**Prevention.** Establish from the start that OKRs are accountability infrastructure, not performance management. Compensation tied loosely or not at all. + +--- + +## Failure 12: OKRs were set but never referenced + +**Symptom.** OKRs documented at start of quarter. Mid-quarter prioritization debates ignore them. End-of-quarter scoring is generous because nobody tracked rigorously. + +**Diagnosis.** OKR theater. The practice produces overhead without value. + +**Cure.** Reform the cadence. Weekly check-ins reference OKRs explicitly. Mid-quarter review uses OKRs as the assessment lens. Scoring informs next quarter. + +**Prevention.** Tie OKRs to specific decisions. If OKRs are not load-bearing for prioritization, surface the disconnect and reform or abandon. + +--- + +## Failure 13: KRs depend on factors outside team influence + +**Symptom.** KRs miss because of external factors the team could not affect (market conditions, sales execution, infrastructure issues). The team cannot credibly own the KR. + +**Diagnosis.** KR design failure. Targets set on outcomes the team cannot meaningfully drive. + +**Cure.** Rewrite to focus on what the team can move. The team's contribution to a larger outcome may be the right KR, not the larger outcome itself. + +**Prevention.** During KR design, validate that the team can identify how their work moves the KR. + +--- + +## Failure 14: Cross-team OKRs produce coordination failures + +**Symptom.** Multiple teams have KRs aimed at the same outcome. Teams pursue independently; the outcome lags because nobody owns the integration. + +**Diagnosis.** Cross-team coordination missing. Either single ownership should have been assigned, or split KRs need stronger coordination. + +**Cure.** Establish single ownership for outcome OKRs that span multiple teams. Or use split-KR pattern where each team's KR is their specific contribution. + +**Prevention.** During OKR design, surface cross-team dependencies. Decide single-owner or split-KR explicitly. + +--- + +## Failure 15: OKRs are roadmap commitments to stakeholders + +**Symptom.** Stakeholders treat OKRs as commitments to specific work. Mid-quarter tactical adjustments feel like broken promises. + +**Diagnosis.** OKR-as-roadmap conflation. Stakeholders interpret outcomes as outputs. + +**Cure.** Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Both are visible; the OKR is the accountability; the roadmap is the team's current best guess at what work will produce the outcome. + +**Prevention.** When communicating OKRs to stakeholders, explicitly surface the distinction. Use different vocabulary. + +--- + +## The cross-cutting pattern + +Most OKR failures share a single root: treating OKRs as ceremony rather than as accountability infrastructure. + +Ceremony focuses on the appearance of OKR practice: documents produced, meetings held, scores generated. Accountability focuses on the work the practice is meant to support: stretch goal-setting, mid-quarter learning, end-of-quarter scoring honesty, next-quarter improvement. + +The fix for almost any OKR failure starts with the same question: what decision is this OKR practice supposed to inform? When the answer is clear, the practice becomes load-bearing. When the answer is "we should follow the OKR process," the practice becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-accountability pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/okr-design/references/key-result-design-patterns.md b/skills/okr-design/references/key-result-design-patterns.md new file mode 100644 index 0000000..8ad33d3 --- /dev/null +++ b/skills/okr-design/references/key-result-design-patterns.md @@ -0,0 +1,242 @@ +# Key result design patterns + +Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. + +Key results are where the OKR practice succeeds or fails operationally. Objectives can be inspiring without measurable; key results have to be measurable. Most OKR failure at the operational level shows up in the key result design. + +--- + +## The four characteristics of strong key results + +**Measurable.** A specific number, percentage, or testable threshold. + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." + +**Outcome-aligned.** Achieving the key result actually moves the objective forward. + +- For the activation objective, the key results above are aligned: they all measure aspects of activation. +- A key result like "ship the onboarding redesign" is not outcome-aligned; it measures the work, not the activation outcome. + +**Within team influence.** The team can affect the key result through their work. + +- "First-week activation rate" is influenced by onboarding design, welcome email content, in-product guidance. The team can affect it. +- "Total signups" depends primarily on marketing acquisition; the activation team's onboarding work affects it weakly. Not a strong key result for the activation team. + +**Time-bounded.** The measurement window is the quarter (or appropriate sub-window). + +- "Increase first-week activation rate from 32% to 45% by end of Q3." +- "Reach 80% completion rate by week 10 of the quarter." + +The four characteristics together produce key results the team can commit to credibly and measure honestly. + +--- + +## Strong key result examples by objective + +**Objective: "Improve activation for new sign-ups so more reach value-realization in week one."** + +Strong KRs: + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." +- "Reduce signup-to-first-key-action time from 8 minutes to under 4 minutes." + +Each measures an aspect of activation. The team can influence each through their work. Each has a baseline and target. + +**Objective: "Make support experience deflect predictable issues."** + +Strong KRs: + +- "Reduce ticket volume on the top 3 deflection-eligible categories by 40%." +- "Increase self-service resolution rate from 22% to 38%." +- "Maintain CSAT at or above 4.4/5 (no degradation while deflecting)." + +The third KR matters: deflecting tickets without protecting CSAT could damage the experience; the KR keeps both in scope. + +**Objective: "Establish enterprise-readiness foundations."** + +Strong KRs: + +- "Pass SOC 2 Type II audit with zero high-severity findings." +- "Complete admin role and permissions overhaul; reach 95% of enterprise-prospect compliance checklist items." +- "Onboard 3 design partners from the enterprise segment to the alpha enterprise build." + +Each measures a foundation outcome the enterprise readiness depends on. + +--- + +## Weak key result examples + +**Vague.** + +- "Improve activation significantly." +- "Reduce ticket volume." + +No specific number; cannot be scored honestly. + +**Output disguised as outcome.** + +- "Ship 5 onboarding redesign initiatives." +- "Run 12 customer interviews." + +Counts work done, not outcomes produced. The team can hit these by doing work without producing the outcome the objective targets. + +**Outside influence.** + +- "Increase total signups by 50%." +- "Maintain market share." + +Total signups are upstream of activation work; market share depends on competitive dynamics largely outside the team's control. + +**Vanity.** + +- "Reach 1M users." +- "Reach 10K NPS responses." + +Impressive numbers; not directly tied to the outcome the objective targets. + +**Single-data-point dependent.** + +- "Have one customer reference our product publicly." + +Fragile; a single data point may not represent progress. + +--- + +## The 3-5 key results rule + +Most objectives benefit from 3-5 key results. + +**Why not 1.** Single key results are fragile. If the metric does not move for reasons outside the team's tactical choices, the team has no way to show progress on the objective. Multiple KRs triangulate. + +**Why not 6+.** Too many KRs dilute focus. The team scatters attention across many metrics; trade-offs across KRs become impossible because all are claimed as priority. + +**The 3-5 sweet spot.** + +- Enough KRs to triangulate the outcome. +- Few enough that the team can pay attention to each. +- Allows for KRs that protect against unintended degradation (e.g., deflect tickets while protecting CSAT). + +**The KR composition.** + +- 1-2 KRs measure the primary outcome. +- 1-2 KRs measure secondary aspects of the outcome. +- 0-1 KRs protect against unintended consequences. + +--- + +## Baseline and target setting + +Each KR needs a baseline and target. + +**Baseline.** The current value of the metric. Pulled from analytics or recent measurement; should be honest, not aspirational. + +**Target.** The value the team commits to reaching by end of quarter. + +**Setting the target.** + +- Stretch: target a value that requires real work to reach. Should hit 60-70% of the time on average across KRs. +- Not sandbagged: target should not be where the team would land without focused effort. +- Not fantasy: target should be reachable through realistic effort paths the team can identify. + +**The historical-trajectory test.** Look at the metric over the past 4 quarters. Where would the metric be at end of next quarter on its current trajectory? The target should be meaningfully above that trajectory; otherwise, the OKR is sandbagged. + +**The effort-path test.** Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, the target is fantasy. + +--- + +## Leading vs lagging key results + +Key results can measure leading indicators (early signals) or lagging indicators (final outcomes). + +**Lagging.** The outcome the team ultimately wants. "First-week activation rate" measures the activation outcome. + +**Leading.** Early signals that the lagging outcome will move. "Onboarding flow completion rate" leads first-week activation rate. + +**The blend.** + +- Some KRs measure leading indicators (so the team has signal early in the quarter). +- Some KRs measure lagging indicators (so the team is accountable to the actual outcome). +- A blend produces both early signal and end-of-quarter accountability. + +**The lagging-only failure.** OKRs that only measure lagging indicators produce no mid-quarter signal. The team cannot tell if they are on track until end of quarter. + +**The leading-only failure.** OKRs that only measure leading indicators produce no end-of-quarter accountability. Leading indicators can move without lagging indicators following. + +--- + +## When binary KRs are appropriate + +Most KRs are quantitative (a number to reach). Some are binary (a milestone to achieve). + +**When binary works.** + +- Audit-pass milestones: "Pass SOC 2 Type II with zero high-severity findings." +- Foundational milestones: "Complete admin role overhaul." +- Launch milestones: "Ship the activation redesign to all users." + +**When binary fails.** + +- Used for KRs that should be quantitative. "Successfully implement activation improvements" is binary disguised as outcome; should be quantitative. +- Used to dodge measurement. Binary KRs that are not actually milestones become "we did it" claims without underlying outcome verification. + +**The discipline.** Use binary KRs sparingly and only when the milestone genuinely is the outcome. Most outcome KRs benefit from quantitative measurement. + +--- + +## KRs across teams + +When multiple teams contribute to the same outcome, KRs need careful design. + +**The split-KR pattern.** Each team has KRs that contribute to the cross-team outcome. + +- Product team KR: "Increase first-week activation rate from 32% to 45%." +- Engineering team KR: "Ship onboarding redesign by week 6 of the quarter." +- Customer success team KR: "Reduce activation-related support ticket volume by 30%." + +Each team is accountable for its contribution; the cross-team outcome benefits from all. + +**The single-owner pattern.** One team owns the outcome KR; other teams support without explicit KRs on the same metric. + +- Product team owns the activation KR. +- Engineering and CS support without separate KRs. +- Cross-team coordination happens outside the OKR structure. + +**The discipline.** Pick a pattern. Hybrid approaches (sometimes shared KRs, sometimes single-owner) produce confusion about accountability. + +--- + +## Common KR design failures + +**Output KRs.** Counts of work shipped instead of outcomes produced. Cure: rewrite. + +**Vague KRs.** Lack measurable targets. Cure: specify number and threshold. + +**Out-of-influence KRs.** Depend on factors the team cannot affect. Cure: rewrite to what the team can move. + +**Vanity KRs.** Impressive numbers not tied to outcome. Cure: tie to the actual outcome. + +**Too few KRs.** Single KR fragility. Cure: 3-5 KRs per objective. + +**Too many KRs.** 6+ KRs dilute focus. Cure: cap at 5. + +**No baseline.** "Reach X" without naming current value. Cure: include baseline. + +**Sandbagged targets.** Targets at or below current trajectory. Cure: stretch beyond what the team would do without focus. + +**Fantasy targets.** Targets with no realistic effort path. Cure: validate against effort-path test. + +**Lagging-only.** No leading indicators. Cure: add leading-indicator KRs. + +--- + +## Methodology-level choices that stay in the public skill + +The four characteristics. Strong and weak KR examples. The 3-5 KR rule. Baseline and target setting. Leading vs lagging KRs. Binary KRs when appropriate. Cross-team KR patterns. Common failures. + +## Implementation choices that stay internal + +Specific KR templates. Specific metrics tooling and dashboards. Specific historical-trajectory analysis. Specific KR scorecards. The team's own conventions for KR wording. These vary by team and tooling. diff --git a/skills/okr-design/references/mid-quarter-recalibration.md b/skills/okr-design/references/mid-quarter-recalibration.md new file mode 100644 index 0000000..91b96a0 --- /dev/null +++ b/skills/okr-design/references/mid-quarter-recalibration.md @@ -0,0 +1,214 @@ +# Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. Strategic shift vs uncomfortable OKRs. The recalibration discipline. + +The default is that OKRs hold for the quarter. Teams adapt their tactics; OKRs do not change to match what the team is doing. Recalibration is the exception, not the rule. Recalibrating frequently signals OKR design failure. + +--- + +## The default: OKRs hold + +OKRs are quarterly commitments. The team commits at the start of the quarter and works toward them through the quarter regardless of whether progress feels comfortable. + +**Why holding matters.** + +- OKRs are accountability infrastructure. Changing them mid-quarter weakens the accountability. +- Stretch OKRs are uncomfortable by design. The discomfort is the work. +- Teams that recalibrate when uncomfortable train themselves to recalibrate as a coping mechanism. + +**Adapting tactics, not OKRs.** + +- The OKR target stays. +- The team's tactics for reaching the target adapt as they learn what works. +- New initiatives may be launched; existing ones may be scrapped; the OKR remains the destination. + +--- + +## When to recalibrate + +Three conditions warrant recalibration. + +### Strategic shift + +The company's strategy changed materially mid-quarter. OKRs that no longer reflect the strategy are no longer the right targets. + +**Examples.** + +- The company pivoted to a new market segment; OKRs aimed at the prior segment are no longer strategic. +- A major acquisition or restructure changed the team's mandate. +- Leadership announced a new strategic priority that supersedes the quarter's OKRs. + +**The handling.** Recalibrate explicitly. Document what changed strategically and how OKRs are revised. Communicate to stakeholders so the recalibration is visible and intentional. + +### Major external disruption + +A market change, regulatory event, or significant outage warrants resetting the quarter's targets. + +**Examples.** + +- A major outage consumed weeks of engineering capacity that was meant for OKR work. +- Regulatory changes required compliance work that displaced planned OKRs. +- Market conditions shifted dramatically (recession, supply chain disruption) and the OKRs no longer reflect realistic ambition for the new conditions. + +**The handling.** Recalibrate explicitly. Surface the disruption and its impact. Set new targets that reflect the post-disruption reality. + +### Information that invalidates the OKR + +The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +**Examples.** + +- Analytics work revealed that the activation metric the team was targeting is not the right measure of activation success; a better metric exists. +- Customer research revealed that the user segment the team was prioritizing is smaller or less important than expected. +- Technical investigation revealed that the planned approach to an OKR has fatal limitations that were not visible at planning time. + +**The handling.** Recalibrate explicitly. Document what was learned. Set new OKRs reflecting the new understanding. + +--- + +## When NOT to recalibrate + +Three patterns that look like recalibration triggers but are not. + +### The team is not on track + +OKRs that the team is missing should remain as set; the miss is the signal. + +**Why.** Stretch OKRs are designed to miss sometimes. Hitting 60-70% on average means roughly 30-40% of KRs miss the target. The miss is informative; lowering the target to match the trajectory eliminates the signal. + +**The cure.** Hold the OKR. Score honestly at end of quarter. Use the miss to inform next quarter's design. + +### The OKR is uncomfortable + +Teams uncomfortable with stretch OKRs sometimes want to recalibrate to feel better. + +**Why.** Stretch is uncomfortable by design. Teams that learn to lower OKRs when uncomfortable lose the stretch discipline; OKRs drift toward sandbagging quarter over quarter. + +**The cure.** Hold the OKR. Acknowledge the discomfort. Surface what the team would need to push toward the target. Use the discomfort productively rather than recalibrating it away. + +### Easier OKRs would feel achievable + +The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +**Why.** Hard OKRs are the point. Swapping for easier ones removes the accountability infrastructure stretch OKRs provide. + +**The cure.** Hold the OKR. If the original was genuinely fantasy (no realistic effort path), recalibrate per the strategic-shift pattern. If the original was genuine stretch but uncomfortable, hold. + +--- + +## The recalibration discipline + +When recalibration is warranted, the discipline matters. + +**Surface the trigger.** What changed? Strategic shift, external disruption, or invalidating information. Be specific. + +**Document the original target and the revised target.** The history of recalibration is part of the OKR record. Future audits should be able to see what changed. + +**Explain the new target.** Why this revised target? What effort path produces it? How does it reflect the new reality? + +**Communicate to stakeholders.** Recalibration is visible. Stakeholders who expected the original target should know it changed and why. + +**Score against the revised target at end of quarter.** The recalibrated OKR is the OKR for scoring purposes. Do not score against the original. + +--- + +## Frequency of recalibration + +Recalibration should be rare. + +**Healthy frequency.** 1-2 quarters out of 8 may include recalibration on at least one OKR. Most quarters should have no recalibrations. + +**Concerning frequency.** Every quarter includes recalibration on some OKR. This signals either: + +- The OKR design is consistently aggressive (fantasy targets). +- The strategy is shifting too frequently (lack of strategic stability). +- The team has learned to recalibrate as a coping mechanism for stretch. + +**The diagnosis.** Frequent recalibration is a signal to investigate, not a feature to lean into. The investigation surfaces whether the issue is OKR design, strategic stability, or team behavior. + +--- + +## Recalibration as honest tool vs avoidance + +The line between honest recalibration and avoidance. + +**Honest recalibration.** + +- The trigger is specific and external (strategic shift, disruption, invalidating information). +- The revised target reflects the new reality, not the team's preference. +- The recalibration is documented and visible. + +**Avoidance dressed as recalibration.** + +- The trigger is vague ("things changed"). +- The revised target is conveniently achievable. +- The recalibration happens when the OKR is uncomfortable, not when external conditions warrant it. + +**The honest test.** If a stakeholder asked the team to defend the recalibration, could the team point to a specific external trigger? If the answer is "we just thought the target was too ambitious," the recalibration is avoidance. + +--- + +## Recalibration in the OKR system + +How recalibration affects the broader OKR practice. + +**Trust effects.** + +- Recalibration that is rare and well-justified preserves trust in OKRs. +- Recalibration that is frequent or poorly justified erodes trust; stakeholders learn to expect targets to slide. + +**Org-wide signaling.** + +- One team's recalibration affects how other teams perceive recalibration norms. +- Leaders that recalibrate strict targets signal to teams that recalibration is acceptable; teams take the cue. +- Leaders that hold targets even when uncomfortable signal that stretch is real; teams take that cue. + +**The practice's calibration over time.** Recalibration norms accumulate. Healthy practices stay disciplined; decaying practices loosen. The annual review of OKR practice should look at recalibration frequency as one signal of practice health. + +--- + +## Communicating recalibration + +When recalibration happens, communication matters. + +**To the team.** + +- Surface the trigger before the recalibration is decided. The team should understand what changed. +- Discuss the revised target before committing. The team should be able to commit credibly to the new target. +- Document the change in the OKR system. + +**To stakeholders.** + +- Notify stakeholders explicitly. Do not let recalibration appear as a quiet edit. +- Explain the trigger and the revised target. +- Invite questions; stakeholder concerns may surface issues with the recalibration that warrant further discussion. + +**To the org.** + +- Recalibration patterns inform org-wide OKR discussion. If multiple teams recalibrate in the same quarter, surface the pattern; the strategic clarity may be lacking. + +--- + +## Common recalibration failures + +**Recalibration as the default.** Teams routinely revise OKRs mid-quarter. The OKR system collapses into rolling targets that always reflect current state. + +**Recalibration to avoid stretch discomfort.** Teams revise when OKRs feel uncomfortable; targets drift toward sandbagging. + +**Recalibration without trigger documentation.** OKRs change without surfaced reason; the change becomes invisible to stakeholders. + +**Refusal to recalibrate when warranted.** Teams hold OKRs even when strategy genuinely shifted; quarter ends with OKRs disconnected from strategy. + +**Recalibration to avoid scoring low.** Teams revise targets in the last weeks of the quarter to make the score look better. Scoring loses honesty. + +**Org-wide recalibration cascade.** One team's recalibration triggers others; the whole quarter resets; the OKR system loses meaning. + +--- + +## Methodology-level choices that stay in the public skill + +The default-to-hold principle. When to recalibrate (strategic shift, major disruption, invalidating information). When not to recalibrate (uncomfortable, off-track, easier-feels-better). The recalibration discipline. Frequency norms. Honest vs avoidance recalibration. Communication. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that capture recalibration history. Specific approval workflows for recalibration. The team's own conventions for recalibration communication. These vary by org. diff --git a/skills/okr-design/references/objective-design-patterns.md b/skills/okr-design/references/objective-design-patterns.md new file mode 100644 index 0000000..e1fc8fa --- /dev/null +++ b/skills/okr-design/references/objective-design-patterns.md @@ -0,0 +1,191 @@ +# Objective design patterns + +Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. + +Objectives are the outcome statements that name what the team is trying to achieve in the quarter. Most OKR failure begins at the objective level: outputs disguised as outcomes, vague aspirations, or too many objectives diluting focus. Getting the objective right is upstream of everything else. + +--- + +## Outcome vs output + +The most consequential distinction. + +**Output objectives.** Describe work the team plans to do. + +- "Ship the activation redesign." +- "Migrate to the new auth service." +- "Run 12 customer interviews." + +**Outcome objectives.** Describe results the team is trying to achieve. + +- "Improve activation for new sign-ups so more reach value-realization in week one." +- "Establish auth foundations that support enterprise compliance review." +- "Build a research-grounded picture of how mid-market customers actually use the product." + +**Why the distinction matters.** Outputs can be shipped without producing outcomes. The activation redesign ships; activation rate stays the same. The auth migration completes; compliance review still fails. The interviews happen; the team cannot point to decisions that changed. + +**The output-as-outcome failure.** Output objectives shift the team's incentives toward shipping rather than achieving. The team optimizes for the work; the work gets done; the underlying goal goes unachieved. + +**The cure.** Each output objective gets rewritten to name the outcome the output is meant to produce. If the team cannot name the outcome, the output's value is unclear and may not warrant quarterly priority. + +--- + +## Strong objective characteristics + +**Outcome-focused.** Names the result, not the work. + +**Specific to the quarter.** Vague aspirations ("be more user-focused") do not focus quarterly work. The objective should be specific enough that the team knows when they have moved it forward. + +**Inspiring without being fantasy.** The team should feel pulled toward the objective. Fantasy demoralizes; sandbag bores. Stretch motivates. + +**Few in number.** 2-4 objectives per team per quarter. More dilutes focus; the team works on too many things and excels at none. + +**Connected to strategy.** Objectives ladder up to company-level priorities or to the team's strategic mandate. Disconnected objectives produce work that does not contribute to the org's direction. + +**Within team influence.** The team can affect the outcome through their work. Objectives entirely dependent on external factors are not the team's to commit to. + +--- + +## Weak objective characteristics + +**Output-disguised-as-outcome.** "Ship the redesign" is the work; the outcome should be the result the redesign produces. + +**Too vague.** "Improve user experience" is too broad to focus a quarter's work. What aspect of UX, in what part of the product, for which users? + +**Too tactical.** "Refactor the auth service" is a tactical decision the team makes within larger initiatives, not a quarterly objective. + +**Too many.** 8 objectives produces no focus. Each objective gets less attention; trade-offs become impossible because everything is priority. + +**Disconnected from strategy.** Objectives that do not ladder to company priorities or team mandate produce work that does not contribute. + +**Outside team influence.** "Total revenue grows 30%" may not be the product team's to commit to if revenue depends on sales execution, market conditions, and product work combined. + +--- + +## Worked objective examples by domain + +### B2B SaaS product team + +- "Improve activation for new sign-ups so that more reach the value-realization moment within their first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +### Consumer mobile app team + +- "Increase retention through the first month so users build habit before the typical churn window." +- "Improve performance and reliability so the experience matches the brand's reputation." + +### Internal platform team + +- "Reduce the time it takes engineering teams to ship a new service from days to under a day." +- "Eliminate the top three reasons engineering teams escalate to platform support." + +### Marketing-product team + +- "Convert more product trial users to paid by removing friction in the upgrade path." +- "Position the product clearly enough that prospects evaluating against alternatives understand the differentiation." + +Each objective is outcome-focused, specific to the quarter, and within the team's ability to influence. The work that produces these outcomes is multiple roadmap items; the OKR is the result, not the work. + +--- + +## The few-objectives discipline + +Most teams should have 2-4 objectives per quarter. The discipline produces focus. + +**Why fewer is better.** + +- Each objective gets serious attention. The team thinks about it weekly, makes trade-offs against it, surfaces blockers. +- Trade-offs are possible. With 3 objectives, the team can decide that work on objective A takes priority over work on objective C this week. With 12 objectives, all work claims priority. +- The team can credibly commit. 3 objectives are credible; 12 are not. + +**Why more feels tempting.** + +- Multiple stakeholders want their priorities reflected. Adding objectives feels like accommodating; capping objectives feels like saying no. +- The team sees many things they could pursue. Picking 3 means deferring others. +- Past quarters' OKRs sometimes accumulate; teams forget to retire objectives that no longer fit. + +**The discipline.** + +- Cap objectives. 4 is the upper bound for most teams. +- Surface what is being deferred. The objectives that did not make the cut get named explicitly; the team's choice to defer is transparent. +- Retire objectives quarter-over-quarter. Objectives are quarterly; they do not carry over by default. + +--- + +## Objectives across an org + +When the org has multiple teams, objectives should compose without overlap or contradiction. + +**Cross-team coordination.** + +- Objectives that depend on multiple teams should name the dependencies explicitly. The product team's objective may depend on engineering hiring; the engineering team's objective may depend on product prioritization. +- Objectives that conflict across teams need resolution before the quarter starts. Teams pulling in opposite directions waste capacity. + +**Team mandate alignment.** + +- Each team's objectives should fit the team's mandate. Product team objectives are product outcomes; engineering team objectives are engineering outcomes; design team objectives are design outcomes. +- Cross-functional outcomes (e.g., "improve activation") require multiple teams to commit. The lead team owns the OKR; the supporting teams commit dependencies in their own OKRs. + +--- + +## Objective writing process + +How objectives get drafted. + +**Draft sources.** + +- Strategy work that named the priorities for the quarter or year. +- Discovery synthesis that identified user-job priorities. +- Roadmap-planning work that surfaced major initiatives. +- Performance review that identified gaps from the prior quarter. + +**Draft method.** + +- Start from the outcome the team is trying to produce. +- Surface multiple draft phrasings. +- Test each: is this an outcome or an output? Is it specific enough? Is it within team influence? +- Iterate to a 2-4 objective set that the team can commit to and that ladders to strategy. + +**Stakeholder review.** + +- Draft objectives circulate to stakeholders before commit. Surfaces dependencies and conflicts. +- Stakeholder feedback informs revisions; the team owns the final commit. + +**The commitment.** Objectives published and visible to the org. The team is on the hook for them. + +--- + +## Objective revision through the quarter + +Objectives generally hold for the quarter. See `mid-quarter-recalibration.md` for when revision is appropriate. + +**The default.** Objectives stay; tactics adapt to keep moving toward them. + +**The exception.** Strategic shift, major external disruption, or invalidating information warrants revision. Rare. + +--- + +## Common objective design failures + +**Output objectives.** "Ship X" instead of "Achieve outcome Y through X." Cure: name the outcome. + +**Vague objectives.** "Improve experience" without specifying what or where. Cure: specificity. + +**Too many objectives.** 8+ per team per quarter. Cure: cap at 4. + +**Tactical objectives.** Specific implementation decisions framed as objectives. Cure: tactical decisions belong in roadmap items, not OKRs. + +**Strategic-disconnect.** Objectives that do not ladder to company or team priorities. Cure: explicit ladder before commit. + +**Out-of-influence.** Objectives entirely dependent on factors the team does not control. Cure: rewrite to focus on what the team can affect. + +--- + +## Methodology-level choices that stay in the public skill + +The outcome-vs-output distinction. Strong and weak objective characteristics. Worked examples across domains. The few-objectives discipline. Cross-team coordination. The drafting and review process. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools the team uses. Specific document templates for objectives. Specific stakeholder-review formats. The team's own conventions for objective wording within the principles. These vary by team and tooling. diff --git a/skills/okr-design/references/okr-anti-patterns.md b/skills/okr-design/references/okr-anti-patterns.md new file mode 100644 index 0000000..f70fe2f --- /dev/null +++ b/skills/okr-design/references/okr-anti-patterns.md @@ -0,0 +1,249 @@ +# OKR anti-patterns + +Eight-plus anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling, and others. Each anti-pattern names a recurring failure mode that decays OKR practice over time. + +--- + +## Anti-pattern 1: OKR-as-roadmap + +**The pattern.** OKRs are written as a list of features the team plans to ship. + +**Examples.** + +- "Objective: Ship the activation redesign. KR: Activation redesign launched by week 8. KR: Welcome email v2 launched by week 4." + +**Why it fails.** + +- Outputs disguised as outcomes. The team is committing to work, not to results. +- The outcome the work is meant to produce goes unspecified; the team can ship the redesign without producing the activation outcome. +- OKRs become roadmap commitments to stakeholders; mid-quarter tactical changes feel like broken promises. + +**The cure.** Each OKR names the outcome the work is meant to produce. The work itself lives in the roadmap. + +--- + +## Anti-pattern 2: Sandbagging + +**The pattern.** OKRs designed to hit 100%. Targets at or below the team's current trajectory. + +**How it manifests.** + +- KR targets within 5% of current values. +- KR targets achievable on standard execution without focused effort. +- Average end-of-quarter scores at 95%+. +- Team consistently celebrates "hitting all our OKRs." + +**Why it fails.** + +- No stretch; no learning. The team did not commit to ambition; the OKR practice produced no signal beyond what the team would have done anyway. +- Sandbagging compounds. Teams that sandbag once learn that sandbagging is safe; subsequent quarters get worse. +- Stakeholder trust degrades. Stakeholders learn that "hitting OKRs" does not mean ambitious work was done. + +**The cure.** Set targets above the team's current trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The OKR target should be meaningfully above that. + +--- + +## Anti-pattern 3: Aspirational fantasy + +**The pattern.** OKRs that nobody can hit. Targets with no realistic effort path. + +**How it manifests.** + +- KR targets at 5x or 10x current values without underlying capacity changes. +- Targets set for inspiration rather than commitment. +- Average end-of-quarter scores at 30% or below. +- Team disengages from OKRs by week 3-4 of the quarter. + +**Why it fails.** + +- Demoralizing. Teams cannot hit fantasy targets; the targets become decoration. +- Loss of meaning. When OKRs cannot be hit, scoring loses meaning; teams stop tracking. +- Compensation distortion. If OKRs are tied to compensation, fantasy targets create unfairness; teams cannot earn rewards regardless of effort. + +**The cure.** Validate against the effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, recalibrate. + +--- + +## Anti-pattern 4: Vanity metrics + +**The pattern.** KRs that measure impressive numbers not tied to the outcome. + +**Examples.** + +- "Reach 1M users." +- "Generate 10K leads." +- "Reach 500K social followers." + +**Why it fails.** + +- Numbers can be moved without producing the outcome the OKR was meant to address. +- Vanity targets often correlate with marketing or acquisition spend rather than with product outcomes. +- The team can hit vanity KRs while the underlying outcome (engagement, retention, revenue) does not improve. + +**The cure.** Each KR should connect to the outcome the OKR targets. If the connection is unclear, the KR is probably vanity. Replace with a KR that more directly measures the outcome. + +--- + +## Anti-pattern 5: OKR theater + +**The pattern.** OKRs are documented and presented but do not drive decisions. + +**How it manifests.** + +- OKRs are set at the start of the quarter and not referenced again until end of quarter. +- Mid-quarter prioritization decisions ignore OKRs. +- The team makes the same prioritization choices that they would have made without OKRs. +- OKR scores are produced at end of quarter but do not inform the next quarter's planning. + +**Why it fails.** + +- The OKR practice produces overhead without value. The team spends time on OKR ceremony without changing what they would have done. +- Stakeholder skepticism builds. Stakeholders learn that OKRs are not load-bearing. +- The practice decays further over time as the team rationalizes that the ceremony does not matter. + +**The cure.** Tie OKRs to specific decisions. Mid-quarter prioritization debates should reference OKRs. Roadmap items should map to OKRs. Scoring should inform the next quarter. If none of these happen, the OKR practice is theater; reform or abandon. + +--- + +## Anti-pattern 6: Compensation coupling + +**The pattern.** OKR scores directly determine bonuses or performance ratings. + +**Why it fails.** + +- Sandbagging incentives become severe. Teams set OKRs they know they can hit to protect their compensation. +- Honest scoring suffers. Teams round scores up to avoid compensation impact. +- Stretch ambition disappears. The OKR practice collapses to "what we are confident we can hit." +- Team trust in OKRs degrades; the practice becomes performance management theater. + +**The cure.** Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs (manager assessment, peer feedback, role expectations); OKR scores may be one input but should not be dominant. + +**The transition.** Orgs that have coupled OKRs and compensation need explicit decoupling communication. Teams need to trust that scoring honestly will not affect bonuses; the trust takes 2-3 cycles to establish. + +--- + +## Anti-pattern 7: OKR proliferation + +**The pattern.** Teams set 8-12 OKRs per quarter. Every team member's work is reflected in some OKR. + +**Why it fails.** + +- Focus dilutes. The team works on too many things; trade-offs become impossible because everything is priority. +- Tracking burden grows. Weekly check-ins become status reports across too many KRs. +- Scoring becomes performative. Teams cannot honestly score 40+ KRs at end of quarter. + +**The cure.** Cap OKRs. 2-4 objectives per team; 3-5 KRs per objective. Surface what is not in OKRs as deferred work that the team is choosing not to commit to this quarter. + +--- + +## Anti-pattern 8: Cascade theater + +**The pattern.** OKR documents include cascading ladders that look connected but do not actually drive work. + +**How it manifests.** + +- Team OKRs claim ladders to company OKRs but the team's actual work would have happened regardless. +- Cascading documents look impressive but do not coordinate cross-team work. +- The cascade is performed for stakeholders rather than for execution. + +**Why it fails.** + +- Cascading work is overhead without value. +- Cross-team coordination does not actually happen through the cascade. +- Stakeholders learn that the cascade is theater. + +**The cure.** Make ladders explicit only when they genuinely connect. Loosen cascading where strict ladders produce theater. See `cascading-okrs-decisions.md` for the discipline. + +--- + +## Anti-pattern 9: Mid-quarter recalibration as default + +**The pattern.** OKRs get revised mid-quarter routinely. The team uses recalibration to soften OKRs that feel uncomfortable. + +**Why it fails.** + +- OKRs lose accountability. Teams learn that revising mid-quarter is acceptable; commitment loosens. +- Stretch ambition disappears. Discomfort triggers recalibration rather than effort. +- Targets drift toward sandbagging quarter over quarter. + +**The cure.** Hold OKRs absent strategic shift, major disruption, or invalidating information. See `mid-quarter-recalibration.md` for the discipline. + +--- + +## Anti-pattern 10: Output-only KRs + +**The pattern.** Key results count work shipped rather than measure outcomes produced. + +**Examples.** + +- "Ship 5 onboarding initiatives." +- "Run 12 customer interviews." +- "Publish 8 marketing pieces." + +**Why it fails.** + +- Counts work, not outcomes. The team can hit these by doing work without producing the outcome. +- Optimizes for shipping volume rather than impact. +- Loses the connection between work and result. + +**The cure.** For each output KR, identify the outcome the output is meant to produce. Replace the count with a measurement of the outcome. + +--- + +## Anti-pattern 11: KRs entirely outside team influence + +**The pattern.** KRs depend on factors the team cannot control. + +**Examples.** + +- "Total revenue grows 30%" (depends on sales execution and market conditions, not just product work). +- "Maintain market share" (depends on competitive dynamics). +- "Reach Series B" (depends on investor decisions outside the team). + +**Why it fails.** + +- The team cannot credibly commit. Effort does not produce predictable outcomes. +- Failure is not informative. Misses do not reveal what the team should have done differently. +- Demoralizing. Teams hit fail OKRs they had little ability to affect. + +**The cure.** Rewrite KRs to focus on what the team can move. Total revenue may not be the team's KR; the team's contribution to revenue (e.g., product-led acquisition rate) might be. + +--- + +## Anti-pattern 12: Generous scoring + +**The pattern.** End-of-quarter scoring rounds up systematically. + +**How it manifests.** + +- KRs at 0.55 score 0.6 or 0.7. +- KRs at 0.85 score 1.0. +- The team's average score is 0.85+ even when objective outcomes were mid-range. + +**Why it fails.** + +- Honest signal lost. Scoring no longer reflects outcomes. +- Sandbagging compounds. Teams learn that scoring high is rewarded; subsequent quarters drift further. +- Lessons get lost. Misses scored as hits do not inform improvement. + +**The cure.** Hold the discipline of honest scoring. Document context per score; the context surfaces what produced the actual outcome regardless of the number. + +--- + +## The cross-cutting pattern + +Most OKR anti-patterns share a single root: optimizing for the appearance of OKR success rather than for the underlying outcomes. + +Sandbagging optimizes for hitting 100%. Fantasy optimizes for inspirational targets. OKR theater optimizes for documentation. Compensation coupling optimizes for bonus protection. Generous scoring optimizes for end-of-quarter celebration. + +Each anti-pattern produces apparent OKR success while undermining the OKR practice's actual purpose. The fix in every case is the same: focus on the underlying outcomes the practice is meant to produce, not on the OKR ceremony itself. + +--- + +## Methodology-level choices that stay in the public skill + +The twelve anti-patterns with diagnoses and cures. The cross-cutting appearance-vs-outcome pattern. + +## Implementation choices that stay internal + +Specific anti-pattern detection in the team's tracking tools. Specific reviewer training. Specific intervention patterns when anti-patterns are detected. The team's own conventions for catching drift early. These vary by team. diff --git a/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md b/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md new file mode 100644 index 0000000..9f9514c --- /dev/null +++ b/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md @@ -0,0 +1,235 @@ +# OKRs vs roadmap vs metrics + +The three concepts and their relationships. Common conflations. The complete picture across all three. + +OKRs, roadmaps, and metrics are often conflated. Each serves a different purpose; conflating them produces confusion that decays each practice. Distinguishing them clarifies what each is for and how they compose. + +--- + +## OKRs + +Outcome targets for the quarter. + +**Characteristics.** + +- Quarterly time horizon. +- Outcome-focused. +- Stretch-ambition. +- Designed for accountability and learning, not for execution sequencing. + +**Examples.** + +- Objective: "Improve activation for new sign-ups." +- Key result: "Increase first-week activation rate from 32% to 45%." + +**What OKRs are not.** + +- A roadmap. OKRs do not specify which initiatives to ship. +- A metric. OKRs are quarterly targets on metrics; the metrics themselves are tracked continuously regardless of OKRs. +- A commitment to specific work. The team commits to pursuing the outcome; the tactics adapt. + +--- + +## Roadmap items + +Initiatives the team is building or doing. + +**Characteristics.** + +- Variable time horizon (weeks to months per initiative). +- Output-focused (the work being done). +- Sequenced by priority and dependency. +- Designed for execution coordination. + +**Examples.** + +- "Onboarding redesign." +- "Migrate to new auth service." +- "Build admin role overhaul." + +**What roadmap items are not.** + +- OKRs. Roadmap items are work; OKRs are outcomes. +- Metrics. Roadmap items contribute to moving metrics but are not metrics themselves. +- Permanent commitments. Items can be added, dropped, or re-prioritized as circumstances change. + +--- + +## Metrics + +Ongoing measurements the team tracks. + +**Characteristics.** + +- Continuous time horizon (always tracked). +- Quantitative, time-stamped, queryable. +- Designed for monitoring, learning, and OKR target-setting. + +**Examples.** + +- "First-week activation rate." +- "Median time-to-first-value." +- "Onboarding flow completion rate." + +**What metrics are not.** + +- OKRs. Metrics are continuous; OKRs are quarterly targets on metrics. +- Roadmap items. Metrics are measurements; roadmap items are work. +- Targets. Metrics are values; targets on metrics are KRs (or more generally, performance targets). + +--- + +## The relationship + +How the three compose. + +**OKR: "Improve activation for new sign-ups."** + +- Key result: "First-week activation rate from 32% to 45% by end of quarter." + - Underlying metric: "First-week activation rate" (tracked continuously). + - Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +**The composition.** + +- OKR names the outcome. +- Key result quantifies the outcome with a metric and target. +- Metric is the underlying measurement. +- Roadmap items are the work the team does to move the metric. + +**The flow.** + +- Strategy informs OKRs. +- OKRs inform roadmap prioritization (which work moves which OKR). +- Roadmap items get executed. +- Metrics track the impact. +- Scoring at end of quarter assesses the OKR's actual outcome. + +--- + +## Common conflations + +### OKRs treated as roadmap commitments + +**The pattern.** "Ship the onboarding redesign" written as an OKR. + +**The diagnosis.** This is a roadmap item, not an OKR. The OKR is the outcome the redesign is meant to produce. + +**The cure.** Rewrite as outcome: "Improve activation through onboarding redesign that reaches first-week activation 45%." The redesign is the contributing work; the outcome is what the work is meant to produce. + +### Roadmap items treated as OKRs + +**The pattern.** Quarterly OKRs are a list of features the team plans to ship. + +**The diagnosis.** Output disguised as outcome. The team is committing to work, not to results. + +**The cure.** For each output OKR, identify the outcome the output is meant to produce. The OKR is the outcome; the output is roadmap work that contributes. + +### Every metric needing an OKR + +**The pattern.** The team feels every metric they track must have an OKR target. + +**The diagnosis.** Metrics serve monitoring purposes regardless of whether the team is currently driving them. Some metrics are leading indicators the team watches without driving; some are protective metrics the team watches to ensure they do not degrade. + +**The cure.** OKRs select which metrics the team is actively driving this quarter. Other metrics get tracked without OKR targets. + +### OKRs as roadmap commitments to stakeholders + +**The pattern.** Stakeholders ask "what are you committing to ship next quarter?" The team answers with OKRs. + +**The diagnosis.** The team is using OKRs as roadmap; stakeholders interpret them as roadmap commitments; mid-quarter tactical adjustments feel like broken promises. + +**The cure.** Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Stakeholders can see both; the OKR is what the team is accountable for; the roadmap is the team's current best guess at what work will produce the outcome. + +### Treating metrics as OKRs + +**The pattern.** "Maintain CSAT at 4.5" written as an OKR for a quarter when the team has no specific work aimed at CSAT. + +**The diagnosis.** This is metric monitoring, not an OKR. OKRs are stretch outcomes the team is actively pursuing; metric monitoring continues regardless. + +**The cure.** Track CSAT as a metric. Set an OKR if the team is actively driving CSAT improvement; otherwise, the metric is monitored without an OKR. + +--- + +## When the three diverge + +Sometimes OKRs, roadmap, and metrics tell different stories. + +**The pattern.** + +- OKR is on track (KR moving toward target). +- Roadmap items are shipping on schedule. +- A different metric the team tracks is degrading. + +**The interpretation.** The OKR work is succeeding at its target; an unintended consequence may be hurting another metric. The team must decide whether to address the unintended consequence within the quarter or to defer. + +**The discipline.** OKRs are the formal commitment; roadmap items contribute to OKRs; metrics monitor everything (including OKR targets and protective metrics). When the three diverge, the team has decisions to make. + +--- + +## Roadmap-OKR alignment + +How the roadmap maps to OKRs. + +**The mapping.** + +- Each roadmap item gets associated with the OKR(s) it contributes to. +- Items not associated with any OKR are either team-specific work (technical debt, tooling) or candidates for deferral. + +**Worked example.** + +- OKR: "Improve activation for new sign-ups." +- Contributing roadmap items: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +- OKR: "Establish enterprise-readiness foundations." +- Contributing roadmap items: "Admin role overhaul," "SOC 2 audit preparation." + +- Team-specific roadmap items (no OKR ladder): "Migrate to new auth service" (foundational; supports many OKRs), "Strengthen test coverage in critical paths" (engineering health). + +**The discipline.** All roadmap items have either an OKR ladder or an explicit team-specific designation. Items with neither are candidates for deprioritization. + +--- + +## Metric coverage and OKR targets + +How metrics are selected and how OKR targets relate. + +**Metric coverage.** The team tracks metrics that: + +- Reflect strategic outcomes (input metrics for OKRs). +- Monitor protective concerns (metrics that should not degrade). +- Surface leading indicators of larger outcomes. +- Provide diagnostic signal for issues. + +**OKR target selection.** Each quarter, the team selects which metrics to set OKR targets on: + +- Metrics tied to the quarter's strategic priorities. +- Metrics where stretch progress is plausible and meaningful. +- Often a subset of the broader metric set. + +**The remaining metrics.** Tracked without OKR targets. Monitored for movement; surfaced if they shift unexpectedly. + +--- + +## Common failures across the three + +**OKR-as-roadmap.** Quarterly commitments written as features rather than outcomes. + +**Roadmap-as-OKR.** Roadmap items called OKRs; output disguised as outcome. + +**Every-metric-as-OKR.** OKRs proliferate to cover every tracked metric; focus diluted. + +**OKR-without-roadmap-mapping.** OKRs set without identifying which work will move them; teams miss the OKRs because no work is aimed at them. + +**Roadmap-without-OKR-mapping.** Work happens without explicit OKR connection; teams cannot tell what their work is contributing to. + +**Metrics-without-OKR-distinction.** All metrics treated as targets; team cannot prioritize. + +--- + +## Methodology-level choices that stay in the public skill + +The three concepts and their characteristics. The relationship and composition. Common conflations and cures. When the three diverge. Roadmap-OKR alignment. Metric coverage and OKR target selection. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools. Specific roadmap tools. Specific metrics dashboards. Specific integration between OKR system and roadmap system. The team's own conventions for OKR-roadmap-metric documentation. These vary by team and tooling. diff --git a/skills/okr-design/references/review-cadence-templates.md b/skills/okr-design/references/review-cadence-templates.md new file mode 100644 index 0000000..8ca8934 --- /dev/null +++ b/skills/okr-design/references/review-cadence-templates.md @@ -0,0 +1,230 @@ +# Review cadence templates + +Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. + +OKRs benefit from a structured review rhythm. The cadence produces accountability infrastructure: weekly tactical adjustment, mid-quarter strategic assessment, end-of-quarter scoring, and quarterly practice review. Teams that skip the cadence often watch OKRs decay into year-end reckoning that produces no learning. + +--- + +## Weekly check-ins + +The shortest, most frequent review. + +**Format.** + +- 15-30 minutes per team. +- Team reviews progress on each key result. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Decides tactical adjustments for the upcoming week. + +**Structure.** + +- Per KR: current value, trajectory, blockers, planned work for the upcoming week. +- Cross-OKR: any priority shifts, dependencies needing attention. +- Closing: commitments for the week. + +**Purpose.** + +- Tactical adjustment, not OKR adjustment. +- Surface blockers early so they can be addressed. +- Maintain focus on OKRs across the quarter (without weekly check-ins, OKRs get forgotten in the press of immediate work). + +**What this is not for.** + +- Adjusting the OKR or its targets. That is mid-quarter or end-of-quarter work. +- Status reports for stakeholders. Status reports may flow from the check-in but are a separate output. +- Detailed work review. The check-in is OKR-focused; other work happens elsewhere. + +**Common failures.** + +- Becoming status reports. The check-in turns into "here's what I did this week"; OKR-driven decisions get crowded out. Reform the format. +- Becoming OKR adjustment sessions. Teams uncomfortable with OKRs sometimes use weekly check-ins to soften them. Hold to tactical scope. +- Skipping when busy. Weeks where the check-in feels less urgent are exactly when discipline is needed. Skip rarely. + +--- + +## Mid-quarter review + +A longer, more strategic review. + +**Format.** + +- 60-90 minutes per team. +- Roughly week 6 of the quarter (mid-point). +- Honest assessment of trajectory: which KRs are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +**Structure.** + +- Per OKR: current state vs target, trajectory analysis, on-track or off-track assessment. +- Cross-OKR: priority adjustments, capacity reallocations, blockers requiring escalation. +- Recalibration check: is any OKR a candidate for revision per the strategic-shift / disruption / invalidating-information criteria? (See `mid-quarter-recalibration.md`.) +- Closing: tactical decisions for the second half of the quarter. + +**Purpose.** + +- Strategic assessment of OKR progress. +- Course correction before end-of-quarter when there is still time. +- Surface OKRs that may need recalibration (with the discipline that recalibration should be rare). + +**What this is not for.** + +- Routine recalibration. Most mid-quarter reviews end with no recalibration; tactical adjustments are the typical output. +- Scoring. Scoring is end-of-quarter; mid-quarter assesses trajectory toward the score. +- Postmortem. Postmortems are for completed work; mid-quarter is for live work in progress. + +**Common failures.** + +- Becoming a recalibration session. Teams uncomfortable with stretch use mid-quarter review to lower OKRs. Hold to the rare-recalibration discipline. +- Becoming a status meeting. The session becomes a presentation rather than a decision-making review. Reform format to surface decisions. +- Skipping. Teams that skip mid-quarter review often discover at end of quarter that they could have course-corrected; the missed opportunity is the cost. + +--- + +## End-of-quarter scoring + +The OKR-cycle closing review. + +**Format.** + +- 60-90 minutes per team. +- Last week of the quarter. +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +**Structure.** + +- Per KR: actual outcome, score (0.0-1.0), context (what produced this score). +- Per objective: average KR score, context. +- Cross-OKR: average score across all OKRs (informs whether the quarter was stretch, sandbag, or fantasy). +- Lessons: what this quarter's scoring reveals about OKR design, team capacity, or strategic clarity. +- Closing: insights to carry into next quarter's OKR setting. + +**Purpose.** + +- Honest scoring of outcomes. +- Learning from the gap between target and outcome. +- Input to the next quarter's OKR design. + +**What this is not for.** + +- Compensation discussions. OKRs work best decoupled from compensation; scoring should not feel like a performance evaluation. +- Blame allocation. Misses are informative; the discussion is about what produced the gap, not who failed. +- Setting next quarter's OKRs. That is a separate session. + +**Common failures.** + +- Generous scoring. Scores rounded up; the team protects feelings; honest signal lost. Hold the discipline. +- Skipping context. Scores published without explanation of what produced them. Lessons get lost. +- Treating scores as performance. Compensation coupling produces sandbagging in subsequent quarters. +- Not informing next quarter. Scores reviewed but lessons do not influence the next OKR setting. The cycle does not learn. + +--- + +## Quarterly retrospective + +A separate review focused on the OKR practice itself. + +**Format.** + +- 60-90 minutes per team or org. +- After end-of-quarter scoring. +- Reviews the OKR practice, not the OKR outcomes. +- Often combined with the next-quarter OKR setting session. + +**Structure.** + +- What worked in this quarter's OKR practice (cadence, format, design)? +- What did not work? +- What should change in the next cycle? +- What patterns are emerging across multiple quarters? + +**Purpose.** + +- Improve the OKR practice itself. +- Surface decay or drift in OKR discipline. +- Inform process changes for the next cycle. + +**What this is not for.** + +- Scoring or recalibrating current OKRs. That is end-of-quarter work. +- Setting next quarter's OKRs. That is a separate session that uses the retrospective's inputs. + +**Common patterns surfaced.** + +- Sandbagging or fantasy drift. Average score patterns over multiple quarters reveal practice decay. +- Cadence breakdown. Weekly check-ins becoming status reports; mid-quarter reviews becoming recalibration sessions. +- Cascading misalignment. Teams setting OKRs that do not ladder; cross-team coordination failing. +- Compensation coupling. OKRs becoming performance theater because they are tied to bonuses. + +**Common retrospective failures.** + +- Skipping the retrospective. The OKR practice does not improve; decay accumulates. +- Conflating with next-quarter OKR setting. Both can happen in one session, but the retrospective lens (process review) should be distinct from the OKR design lens (setting). +- Producing recommendations without follow-through. Retrospectives surface improvements; the team must implement them in the next cycle for the retrospective to matter. + +--- + +## The cadence as a system + +The four cadences compose. + +**The system.** + +- Weekly check-ins maintain tactical focus and surface blockers. +- Mid-quarter review provides strategic assessment and rare recalibration opportunity. +- End-of-quarter scoring produces honest signal on outcomes. +- Quarterly retrospective improves the practice over time. + +**The reinforcement.** + +- Weekly check-ins make mid-quarter assessment honest (the team has been tracking trajectory all along). +- Mid-quarter review surfaces issues end-of-quarter scoring will face. +- End-of-quarter scoring informs the retrospective. +- The retrospective informs the next cycle's design. + +**The skip risk.** Teams that skip cadences often skip several. Weekly check-ins falter; mid-quarter review becomes ad-hoc; end-of-quarter scoring becomes generous because the team has not been tracking honestly all along; the retrospective never happens. + +--- + +## Cadence ownership + +Each cadence has a clear owner. + +**Weekly check-ins.** Owned by the team lead (manager, PM, engineering lead). Facilitates the meeting; ensures it stays tactical. + +**Mid-quarter review.** Owned by the team lead, often with cross-functional partners attending. Surfaces strategic decisions. + +**End-of-quarter scoring.** Owned by the team lead. Ensures honest scoring; documents context. + +**Quarterly retrospective.** Owned by the team lead or by a process-focused role (chief of staff, ops lead). Often facilitated by someone slightly outside the team to bring fresh perspective. + +**Cross-team coordination.** When multiple teams have OKRs that compose, coordination across teams happens at the cadence boundaries (typically mid-quarter review). + +--- + +## Common cadence failures + +**Skipping cadences.** Weekly check-ins falter; mid-quarter review becomes ad-hoc; the system breaks. + +**Cadence merging.** Mid-quarter review and end-of-quarter scoring combined into one session. Loses the distinct purposes. + +**Status-report drift.** Weekly check-ins become status reports; tactical decisions get displaced. + +**Recalibration drift.** Mid-quarter review becomes a recalibration session; OKRs lose accountability. + +**Generous-scoring drift.** End-of-quarter scoring rounds up; honest signal lost. + +**Retrospective skipping.** OKR practice does not improve; decay accumulates. + +--- + +## Methodology-level choices that stay in the public skill + +The four cadence formats. Time investment per cadence. Structure and purpose per cadence. The cadence-as-system reinforcement. Ownership. Common failures. + +## Implementation choices that stay internal + +Specific meeting templates. Specific OKR-tracking tools that support each cadence. Specific facilitation conventions. Specific cross-team coordination formats. The team's own conventions for cadence cadence (no pun intended). These vary by team and tooling. diff --git a/skills/okr-design/references/scoring-discipline.md b/skills/okr-design/references/scoring-discipline.md new file mode 100644 index 0000000..b51963d --- /dev/null +++ b/skills/okr-design/references/scoring-discipline.md @@ -0,0 +1,191 @@ +# Scoring discipline + +The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. + +End-of-quarter scoring is where OKR practice succeeds or decays. Honest scoring produces signal: which OKRs the team hit, which they missed, what the gap reveals about the work. Dishonest scoring produces theater: 100% scores claimed regardless of outcome, generous rounding, partial credit for effort rather than outcome. + +--- + +## The 0.0-1.0 scale + +Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +**Key result scoring examples.** + +- KR: "Increase first-week activation rate from 32% to 45%." +- Outcome: rate reached 41%. +- Score: (41 - 32) / (45 - 32) = 9/13 = 0.69. + +- KR: "Reduce median time-to-first-value from 4.2 days to under 2 days." +- Outcome: reduced to 2.6 days. +- Score: (4.2 - 2.6) / (4.2 - 2.0) = 1.6/2.2 = 0.73. + +- KR: "Pass SOC 2 Type II audit with zero high-severity findings." +- Outcome: passed with zero high-severity findings. +- Score: 1.0 (binary KR; achieved). + +**Objective scoring.** Average of the key result scores. + +- Objective with 3 KRs scoring 0.69, 0.73, 1.0: objective scores (0.69 + 0.73 + 1.0) / 3 = 0.81. + +--- + +## The 60-70% target + +Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. + +**Why this target.** + +- Average above 0.85 suggests sandbagging. The team set OKRs they were already on track to deliver. +- Average below 0.4 suggests fantasy. The team set OKRs that no realistic effort path would have produced. +- Average between 0.6-0.7 suggests stretch. The team committed to ambition and delivered most of it. + +**The trajectory check.** Track the team's average score over multiple quarters. Drift toward 0.85+ signals sandbagging is creeping in; drift toward 0.4 signals fantasy. The target zone is 0.55-0.75 over a multi-quarter window. + +**Variance is normal.** Some quarters will hit 0.8 average; some will hit 0.5. The variance reflects the genuine uncertainty in stretch OKRs. Programs that hit 0.65 every single quarter are usually managing scores rather than honestly scoring outcomes. + +--- + +## Scoring honesty + +**Score the actual outcome, not the effort.** A team that worked hard but did not move the metric scores low. A team that got lucky and moved the metric without much effort scores high. The score reflects outcome. + +**Do not round up.** A KR at 0.55 scores 0.55, not 0.6. Honest scoring produces honest signal. Rounding up across multiple KRs accumulates into systemic over-scoring. + +**Acknowledge what changed.** Some misses reflect mid-quarter priority shifts. Surface these without using them as excuses. "We deprioritized this in week 5 to address the security incident" is honest context; "we hit our priorities even though we missed this OKR" is hand-waving. + +**Scoring sessions are honest, not adversarial.** The scoring conversation is for capturing reality, not for blame. Honest low scores are fine; effort recognition happens elsewhere. + +--- + +## What 100% scores mean + +100% scores warrant scrutiny. + +**Possibilities.** + +- The OKR was sandbagged. The team set targets they were already on track to hit. +- The team had a great quarter. Sometimes hitting 100% reflects unusual progress; informative. +- The team is rounding up. The actual outcome was 0.85 but got rounded. +- Binary KRs that hit 1.0. A milestone-based KR that achieves the milestone is 1.0; this is not sandbagging. + +**The investigation.** + +- Compare the target to the historical trajectory. Was the target above what the metric would have done without focused effort? +- Compare the target to other teams setting similar OKRs. Was this target genuinely stretch? +- Look at the work the team did. Did the team push beyond their normal capacity, or did they hit the target on standard execution? + +**The interpretation.** Single-quarter 100% scores are not necessarily problematic. Repeated 100% scores across many KRs across multiple quarters are a sandbagging signal. The next OKR cycle should set targets above the prior quarter's actuals to prevent sandbagging compounding. + +--- + +## What 30% scores mean + +30% scores warrant scrutiny. + +**Possibilities.** + +- The OKR was fantasy. Targets had no realistic effort path; the team could not have hit them. +- Unexpected disruption. A market event, security incident, or priority shift consumed capacity that would have gone to the OKR. +- Mid-quarter deprioritization. The team chose to deprioritize this OKR for other work. +- Underperformance. The team did not execute well; the score reflects the execution gap. + +**The investigation.** + +- Was the target reachable? At setting time, could the team identify effort paths that would produce the target? +- What changed during the quarter that affected the trajectory? +- What did the team actually work on? Did effort match the OKR, or did effort go elsewhere? + +**The interpretation.** 30% scores are informative regardless of cause. Fantasy targets need recalibration in the next quarter. Disruption-driven misses inform what to plan around. Deprioritization-driven misses surface tension between OKRs and other work. Execution gaps surface team-capability or process issues. + +**The non-recovery.** Repeated 30% scores quarter after quarter signal that OKR design is failing. Either the org is consistently setting fantasy targets, or the team is consistently mismatched to its commitments. Investigate. + +--- + +## The compensation question + +OKRs work best when not directly tied to compensation. + +**The problem with compensation-coupling.** When OKRs determine bonuses or reviews, sandbagging incentives become severe. Teams set OKRs they know they can hit. The 60-70% target collapses to 95% target because nobody wants to risk their bonus on stretch. + +**Why decoupling works.** OKRs become genuine accountability infrastructure. The team can stretch without risking compensation. Honest scoring is safe. Misses produce learning rather than punishment. + +**Compensation alternatives.** + +- Compensation tied to overall performance (manager assessment, peer feedback, role expectations) rather than to OKR scores specifically. +- OKR scores inform performance review as one input among many, not as the dominant signal. +- Bonus structures based on company performance rather than team-OKR scores. + +**The transition for orgs already coupled.** Decoupling requires explicit communication. Teams need to trust that scoring honestly will not affect their bonuses. The transition can take 2-3 cycles before teams believe the decoupling is real. + +--- + +## Scoring formats + +How scoring sessions get run. + +**The format.** + +- Team meets at end of quarter (60-90 minutes). +- Each KR scored honestly. +- Each objective scored as the KR average. +- Discussion: what produced the scores, what worked, what did not. +- Output: published scores with brief context per OKR. + +**The discussion content.** + +- For high-scoring OKRs: was this stretch? What worked? What can be replicated? +- For low-scoring OKRs: what got in the way? What does the team need next quarter? +- For mid-scoring OKRs: where did the work land? What was the gap between target and actual? + +**The output.** Scores published to the team and stakeholders. Brief context per OKR. The published record informs the next quarter's setting and the org's broader OKR practice. + +--- + +## Scoring across multiple teams + +When multiple teams cascade to a company OKR, scoring composes. + +**The composition.** + +- Each team scores its KRs independently. +- The company OKR's score reflects the cumulative outcome (not the average of team scores). +- A company OKR can score high even if some contributing team OKRs scored low, depending on which contributions mattered most. + +**Worked example.** Company OKR: "Improve net new ARR through enterprise segment growth." + +- Sales team KR (close 8 enterprise deals): scored 0.85 (closed 7). +- Product team KR (enterprise-readiness foundations): scored 0.7 (achieved most foundations; SOC 2 in progress). +- Marketing team KR (enterprise-segment marketing campaigns): scored 0.5 (delayed launch). + +Company OKR score: depends on the actual ARR outcome, not the average of team scores. If ARR met the target despite the marketing delay (because sales over-delivered), the company OKR scores high. + +**The discipline.** Score outcomes, not averages of inputs. + +--- + +## Common scoring failures + +**Rounding up.** Systemic over-scoring through small individual rounds. + +**Effort-based scoring.** Scoring based on how hard the team worked rather than what was achieved. + +**Compensation-coupled scoring.** Sandbagging incentives produce 95%+ scores. + +**Avoidance of low scores.** Teams reluctant to score low; OKRs renamed or rewritten retroactively to avoid the miss. + +**Aggregate-of-input scoring.** Company OKR scored as average of team scores rather than as the actual outcome. + +**Scoring without context.** Scores published without the conditions that produced them. Lessons get lost. + +**One-quarter-at-a-time view.** Scoring evaluated only against the current quarter; trajectory over multiple quarters not surfaced. + +--- + +## Methodology-level choices that stay in the public skill + +The 0.0-1.0 scale and worked examples. The 60-70% target. Scoring honesty. What 100% and 30% scores mean. The compensation question. Scoring formats. Scoring across teams. Common scoring failures. + +## Implementation choices that stay internal + +Specific scoring tools and dashboards. Specific scoring-session facilitation formats. Specific compensation structures. The team's own conventions for context publishing. These vary by org. diff --git a/skills/onboarding-wizard-design/SKILL.md b/skills/onboarding-wizard-design/SKILL.md new file mode 100644 index 0000000..28ccaa7 --- /dev/null +++ b/skills/onboarding-wizard-design/SKILL.md @@ -0,0 +1,280 @@ +--- +name: onboarding-wizard-design +description: "Designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. Honest about tutorial-overload (dump everything upfront), skip-friendly-empty (skipped onboarding leads to abandoned product), and earned-progressive-disclosure (right things at the right moments) patterns. Triggers on onboarding wizard, product onboarding, first-run experience, signup flow, activation flow, FRX, time-to-value, ah-ha moment design. Also triggers when activation rates are low, when users skip onboarding and never return, when onboarding flows are being scoped for the first time, or when audience research shows users not finding key features." +category: growth-tooling +catalog_summary: "Designing first-run product onboarding wizards. Distinguishes tutorial-overload (dump everything upfront) from skip-friendly-empty (skipped onboarding leads to abandoned product) from earned-progressive-disclosure (right things at the right moments)" +display_order: 7 +--- + +# Onboarding Wizard Design + +A senior product marketing director's playbook for designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. The discipline of building an onboarding sequence the user actually completes. + +Most product onboarding wizards fail in one of two ways. They cram every feature into a 12-step intro the user has not earned the patience for. Or they offer a "skip onboarding" button so prominent that users skip into an empty product with no context, and then churn the next day because they never found the value. The activation rate is the metric that matters, and most wizards are optimizing for the wrong thing. + +The wizards that work do something different. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is balanced against staying engaged. The user reaches the ah-ha moment with a sense that the product respected their time. + +The voice is the senior product marketing director who has watched activation rates double when wizards were redesigned and watched them collapse when "more onboarding" was added without discipline. Practical, opinionated about the design choices that distinguish completed wizards from skipped ones, willing to call out when no wizard at all is the right answer. + +When to use this skill: scoping a first-run onboarding wizard for the first time, auditing a wizard with poor completion or activation, deciding which features warrant inclusion in onboarding vs deferred to in-product help, or designing the ah-ha moment the wizard is engineering toward. + +--- + +## What this skill covers + +This skill spans first-run product onboarding wizards. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access). This skill is post-signup product onboarding. Different phase, different audience state. +- `interactive-product-tour` is contextual help WITHIN the product, surfacing across the lifecycle. This skill is the sequential first-run experience. +- `chatbot-flow-design` is conversational help. This skill is non-conversational sequential setup. +- **`onboarding-wizard-design` (this skill)** is the post-signup wizard's structure, ah-ha moment design, progressive disclosure, skip mechanics, drop-off measurement. +- `pm-spec-writing` is the spec for engineers building the wizard. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams designing activation flows, agencies running activation work for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); in-product contextual tours (covered by `interactive-product-tour`); the engineering implementation; specific Userpilot/Userflow/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The wizard decision: when wizards earn vs when contextual help suffices + +Before designing the wizard, decide whether a wizard is the right tool. + +**Wizards earn investment when:** + +- The product has a meaningful setup step before value emerges. Connect a data source, invite a teammate, configure a workspace. Without setup, the product is empty; the wizard makes setup tractable. +- The ah-ha moment requires multiple actions in sequence. Single-action ah-ha moments (paste a URL, see a result) often work better with contextual prompts than with wizards. +- The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products. Some audiences (consumer, frictionless tools) reject wizard friction. +- The team can maintain the wizard. Wizards decay as the product evolves; without maintenance commitment, the wizard becomes a liability. + +**Wizards do NOT earn investment when:** + +- The product reaches value immediately. Single-input tools, simple consumer products. A wizard adds friction without lift. +- Contextual help would suffice. Tooltips, in-feature hints, and progressive in-product education sometimes serve better than upfront wizards. +- The audience expects no friction. Some audiences abandon at any wizard; meet them where they are. +- The team cannot maintain the wizard alongside product changes. Stale wizards point to deprecated features; users hit broken steps. + +The decision is not "should we have an onboarding wizard"; it is "is the wizard the right tool for this specific product and audience." + +Detail in [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md). + +--- + +## Tutorial-overload vs skip-friendly-empty vs earned-progressive-disclosure + +The keystone framing. + +**Tutorial-overload.** Every feature explained in a 12-step intro before the user has touched the product. Cognitive overload. Users skip if they can; abandon if they cannot. Cost: the wizard's design effort produces a sequence almost nobody completes; activation rate suffers because the user did not reach the value-giving moment. + +**Skip-friendly-empty.** "Skip onboarding" button at every step, so prominent that users always take it. Users skip; arrive at an empty product with no context; churn within hours. Cost: activation rate falls off a cliff because users never set up the basics that make the product functional. + +**Earned-progressive-disclosure.** Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is friction-balanced against staying engaged (e.g., skip places the user in a partially-set-up state with clear callouts to complete setup later). Cost: design effort is significant; activation rate often climbs significantly as a result. + +The litmus test. Watch a new user complete (or skip) the wizard. Did they reach a moment where the product visibly demonstrated value within their first session? If yes, the wizard is earned-progressive-disclosure. If they completed every step but never reached value, tutorial-overload. If they skipped and never returned, skip-friendly-empty. + +--- + +## Step architecture: what belongs in each step, sequence logic + +The structure that makes wizards actually work. + +**The principle.** Each step should move the user one step closer to value. Steps that do not should be cut. + +**Common step patterns.** + +- **Welcome and orientation.** Quick context-setting, often skippable. Sets expectations for what the wizard will do. +- **Identity and account context.** Who are you, what's your role, what brought you here. Often used to personalize subsequent steps. +- **Critical setup step.** The one thing the product cannot work without (connect data source, invite teammates, set primary use case). This is often where wizards justify their existence. +- **First-action step.** Get the user to take a meaningful action that produces visible result. The ah-ha moment lives here or right after. +- **Configuration deferral.** Surface the things that can be set up later but are commonly needed; let the user defer with a clear path back. +- **Confirmation and next steps.** Recap what was set up; surface what to do next; route to in-product home. + +**Step coherence test.** Each step should answer: did this step move the user closer to value? Steps that exist for completeness or feature-pride should be cut. + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## The ah-ha moment design + +What the wizard is actually trying to engineer. + +**The principle.** The ah-ha moment is the moment the user feels "oh, this is what the product does for me." The wizard's structure should engineer toward that moment. + +**Identifying the ah-ha moment.** + +- It is the visible demonstration of value, not just feature explanation. +- It is action-tied, not knowledge-tied. The user did something and saw the result. +- It is single-shot. One clear moment, not a checklist of moments. +- It is honest. The user genuinely got value; not a contrived demo. + +**Design implications.** + +- The wizard's path should converge on the ah-ha moment. Steps that do not contribute should be deferred or cut. +- The ah-ah moment should appear within the user's first session, ideally within 5-10 minutes of signup. Longer time-to-value correlates with churn. +- The ah-ha moment differs by audience. The B2B admin's ah-ha moment differs from the end-user's. Wizards may need to differentiate. + +**Common ah-ha moment patterns.** + +- **First successful query/output.** The user ran something against their data and saw a useful result. +- **First meaningful collaboration moment.** The user shared something with a teammate and saw the response. +- **First saved configuration.** The user set up something they will return to. +- **First value-demonstrating insight.** The user saw a metric, recommendation, or pattern that surprised them. + +Detail in [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md). + +--- + +## Progressive disclosure patterns + +How to surface only what is needed at each step. + +**The principle.** Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +**Pattern A: Default-heavy.** Each step has smart defaults. The user can accept or override. Most users accept; advanced users override. Reduces cognitive load. + +**Pattern B: Required-now, optional-later.** Required fields surface in the wizard; optional configuration surfaces in-product after activation. The wizard stays focused. + +**Pattern C: Expand-on-demand.** Sections collapsed by default; the user expands if interested. Rare; works when the user has agency to explore. + +**Pattern D: Branching.** Different users see different steps based on earlier answers. Powerful but adds maintenance complexity. + +The discipline. Each piece of information shown in the wizard must justify its inclusion. Decorative information adds friction; surface it later. + +Detail in [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md). + +--- + +## Skip and resume mechanics + +When users skip, where they land. When they resume, what they see. + +**The skip principle.** Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +**Skip patterns.** + +- **Soft skip with context.** "Skip for now" deposits the user into a partially-set-up state with clear callouts to complete deferred setup. +- **Skip-and-defer.** Skipped steps are queued for later in-product prompts. +- **Skip-with-warning.** "Skipping setup will limit your experience to X. Continue?" Honest about consequences. +- **No skip.** For wizards that absolutely require completion (compliance forms, paid signups). Use sparingly. + +**Resume patterns.** + +- **Auto-resume on next login.** The user lands at the step they left. +- **Manual resume from in-product entry.** A persistent "Complete setup" surface that returns the user to the wizard. +- **Soft resume.** Wizard fades out as the user completes equivalent actions in-product naturally. + +**The skip-friendly-empty failure.** Skip is too prominent and consequence-free; the user lands in an unconfigured product and has no path back. Activation collapses. + +**The cure.** Skip is honest about consequences and offers a path back. The user who skips knows what they skipped. + +Detail in [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon the wizard, and how to fix it. + +**Per-step instrumentation.** Track step start, step completion, step abandonment for every step. The metrics inform every other improvement. + +**Common drop-off patterns.** + +- **First-step drop-off.** User landed on the wizard, looked at it, left. Often signals the wizard's value proposition is not clear or the audience expected no wizard. +- **Mid-wizard drop-off.** User abandoned mid-process. Audit the specific step; field count, sensitive info, unclear progress. +- **Skip-everything drop-off.** User skipped every available step. Either the wizard is not earning its time or the skip is too prominent. + +**Remediation patterns.** + +- First-step drop-off: clarify the wizard's purpose; reduce upfront fields; consider whether the wizard is needed at all. +- Mid-wizard drop-off: audit the high-drop step; reduce friction; reconsider whether that step belongs in the wizard. +- Skip-everything drop-off: rebalance skip prominence; consider whether the wizard should be replaced with contextual prompts. + +**The instrumentation requirement.** Without per-step tracking, drop-off remediation is guesswork. Set up tracking before launch. + +Detail in [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md). + +--- + +## Wizard variations by user type + +Different users may need different wizards. + +**The admin vs end-user distinction.** Admins set up the workspace; end-users start using it. Wizards aimed at both fail both. Differentiated wizards serve each. + +**The technical vs non-technical distinction.** Technical users skip explanations; non-technical users need them. The wizard's tone and depth should match. + +**The size-of-team distinction.** Solo founders have different setup needs than 50-person teams. Wizards may branch. + +**Differentiation patterns.** + +- **Role-based branching.** First step asks role; subsequent steps adapt. +- **Use-case-based branching.** First step asks use case; wizard tailors. +- **Size-based branching.** Solo, team, enterprise paths differ. + +**The over-differentiated trap.** Too many variants produce unmaintainable wizards. Most wizards work with 2-3 variants at most. + +Detail in [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md). + +- "Activation rate is low; completion rate is high." Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. +- "Skip rate is over 50 percent." Either the wizard is not earning its time or skip is too prominent. Audit both. +- "Users complete the wizard then abandon the product within 24 hours." Time-to-value too long; ah-ha moment not in first session. +- "Wizard works for new users; existing users hit broken steps." Wizard not maintained alongside product; deprecated features still in flow. +- "Different segments complete at very different rates." Audience-fit varies; consider role-based or use-case-based branching. +- "Mobile completion is half of desktop." Mobile UX of the wizard broken. +- "We added more onboarding steps; activation went down." Tutorial-overload pattern; more is not better. +- "Skip mechanics work but users do not return to complete setup." Skip-and-defer not working; in-product prompts to return are missing or ignored. +- "Wizard analytics broke after the last release." Instrumentation drift; track and refresh. + +--- + +## The framework: 12 considerations for onboarding wizard design + +When designing or auditing an onboarding wizard, walk these 12 considerations. + +1. **The wizard decision.** Is a wizard the right tool, or do contextual prompts suffice? +2. **Earned-progressive-disclosure, not tutorial-overload or skip-friendly-empty.** Each step earns one step closer to value. +3. **Step architecture sound.** Each step moves the user closer to value; non-contributing steps cut. +4. **The ah-ha moment engineered.** Single visible value moment, action-tied, in the first session. +5. **Progressive disclosure applied.** Show only what is needed now; defer the rest. +6. **Skip mechanics honest.** Skip exists but does not produce an empty product. +7. **Resume mechanics work.** Skipped users have a path back; instrumented for follow-through. +8. **Drop-off measurement instrumented.** Per-step tracking from launch. +9. **User-type variations balanced.** 2-3 variants max; over-differentiation avoided. +10. **Mobile parity.** Wizard works on the devices the audience uses. +11. **Activation as success metric.** Not just completion rate; the metric is post-wizard product engagement. +12. **Maintenance discipline.** Wizard updated alongside product changes; quarterly audit. + +The output of the framework is an onboarding wizard that gets users to the ah-ha moment, respects their time, and produces activation rates the team can defend. + +--- + +## Reference files + +- [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md) - When wizards earn the build vs when contextual help suffices. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs in each step. Sequence logic. Step coherence test. +- [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md) - Identifying the ah-ha moment; designing the wizard to converge on it. +- [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md) - Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. +- [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md) - Skip patterns and resume patterns. The skip-friendly-empty failure. +- [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md) - Per-step instrumentation. Common drop-off patterns and remediation. +- [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md) - Admin vs end-user, technical vs non-technical, size-based branching. +- [`references/wizard-anti-patterns.md`](references/wizard-anti-patterns.md) - The patterns that look like onboarding but degrade activation. +- [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: wizards earn the user's first session + +The onboarding wizards that work as compounding assets are the ones that get the user to value within their first session. Not because the wizard had every feature explained. Not because the wizard was skipped quickly. Because the wizard engineered the ah-ha moment, respected the user's time, and surfaced the right thing at the right moment. + +That is the bar. Below the bar are tutorial-overload (everything upfront, nobody completes) and skip-friendly-empty (skip too prominent, nobody activates). Above the bar are earned-progressive-disclosure wizards where each step earns the user one step closer to value, skip is honest about consequences, and the activation metric reflects the wizard's actual job. + +The discipline is in the design choices. The decision to build a wizard at all, or defer to contextual help. The step architecture that converges on the ah-ha moment. The progressive disclosure that surfaces the right thing at the right moment. The skip mechanics that protect the user from an empty product. The drop-off instrumentation that informs ongoing improvement. The maintenance cadence that keeps the wizard in sync with the product it represents. + +When in doubt, ask: did the user reach the ah-ha moment in their first session, and did the wizard help or hinder that? If yes to the first and helped on the second, the wizard earned its build. If no to either, redesign. diff --git a/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md b/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md new file mode 100644 index 0000000..0ca8f3e --- /dev/null +++ b/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md @@ -0,0 +1,167 @@ +# Ah-ha moment engineering + +Identifying the ah-ha moment; designing the wizard to converge on it. The single visible moment when the user feels "oh, this is what the product does for me." + +The wizard's job is not completion. It is engineering the ah-ha moment within the user's first session. Without an identifiable ah-ha moment, the wizard has nothing to engineer toward; the result is a sequence that completes without producing activation. + +--- + +## The ah-ha principle + +The ah-ha moment is action-tied, single-shot, and visible. The user did something and saw the value the product promised. The wizard's structure should make that moment likely within the first session. + +**The win.** A new user finishes the wizard and immediately sees their first dashboard with their actual data, with a number that surprises them in a useful way. They get it. + +**The fail.** The user finishes the wizard with a tour of features but never sees the product produce something specifically for them. They completed the wizard; they did not activate. + +--- + +## Identifying the ah-ha moment + +The hardest design step is also the most upstream. + +**Methods.** + +- **Customer research.** Interview activated users (those who returned and engaged) about the moment they felt the product clicked. Patterns emerge. +- **Usage analysis.** Compare cohorts that activated vs cohorts that churned. What action did the activated cohort take that the churned cohort did not? +- **Sales-call mining.** Sales conversations often surface the moment prospects say "now I get it." That moment, in-product, is the ah-ha moment. + +**Signals of a real ah-ha moment.** + +- It is action-tied (the user did something), not knowledge-tied (the user learned something). +- It is single-shot (one specific moment), not a checklist of moments. +- It is visible (the user saw the result), not internal (the user felt understanding). +- It is honest (the user got real value), not contrived (a demo with fake data). + +If the team cannot articulate the ah-ha moment, that is the design problem to solve before building the wizard. + +--- + +## Common ah-ha moment patterns + +By product type. + +**Analytics products.** First successful query against the user's actual data. Not a demo dataset; their data, their result. + +**Collaboration products.** First meaningful interaction with a teammate. A shared comment, a delegated task, a thread that produces a decision. + +**Content products.** First saved item the user returns to. The content was useful enough to revisit. + +**Tooling products.** First completed task that would have taken longer without the tool. The time savings is visible. + +**Marketplace products.** First successful match. Buyer found a seller; seller got a lead. + +**Configurator products.** First saved configuration. The user committed to a setup they want to see again. + +The ah-ha moment varies by product. The discipline (action-tied, single-shot, visible, honest) holds. + +--- + +## Designing the wizard around the ah-ha moment + +The wizard's path should converge on the moment. + +**Step 1: identify the prerequisites.** What does the user need before the ah-ha moment can happen? Connect data, invite teammate, configure workspace. Those steps are mandatory. + +**Step 2: identify the path.** What sequence of actions leads to the moment? The wizard's steps mirror that sequence. + +**Step 3: identify the friction.** What can break the path? Missing inputs, ambiguous decisions, validation errors. The wizard should pre-empt or smooth those. + +**Step 4: place the ah-ha moment intentionally.** The moment should appear at step 3-5 of the wizard, not after a 10-step setup. Earlier is better; aim for the user's first session, ideally first 5-10 minutes. + +--- + +## Time-to-value as design constraint + +The shorter the time to ah-ha, the higher the activation rate. + +**The benchmark.** First session ah-ha moment correlates with strong activation. Multi-session ah-ha (user has to come back) correlates with moderate activation. Multi-day ah-ha (user has to wait or work for it) correlates with poor activation. + +**The design implication.** If the ah-ha moment naturally takes hours or days (e.g., AI training, audit results), the wizard needs an interim ah-ha, something visible the user can see in their first session that signals the eventual ah-ha is coming. + +**Examples.** + +- AI product where training takes 24 hours: interim ah-ha is "see how your data looks; we will message you when training is done." +- Audit product where results take 48 hours: interim ah-ha is "see what we are auditing; preview a partial result." + +The user's first session should produce something visible and meaningful, even if the full ah-ha comes later. + +--- + +## The ah-ha moment for different audiences + +Different users may need different moments. + +**Admin vs end-user.** The admin's ah-ha moment may be configuration-related ("the workspace is set up, the team can use it"). The end-user's ah-ha moment is in-product engagement ("I did the thing I came to do"). Wizards may differentiate. + +**Technical vs non-technical.** Technical users often want depth (see the API work, see the integration succeed). Non-technical users want outcome (see the result, no API). Different ah-ha moments. + +**Solo vs team.** Solo users often want individual productivity. Team users want collaboration moments. The wizard's path may differ. + +The discipline. Identify the ah-ha moment per relevant audience segment. Wizards may branch based on segment. + +--- + +## Anti-patterns in ah-ha moment design + +**Tutorial-as-ah-ha.** Treating "learned about the features" as activation. The user knows what the product does but has not seen it do something specifically for them. Knowledge-tied, not action-tied; not real activation. + +**Demo-as-ah-ha.** Showing a polished demo that does not use the user's data. The user sees what is possible but not what is true for them. Contrived; activation does not stick. + +**Multi-moment ah-ha.** Treating "see all features" as the moment. No single moment lands; the user feels they need to see everything before getting it. + +**Delayed ah-ha.** The ah-ha moment lands two sessions in. The user does not return for the second session. + +**Theoretical ah-ha.** "When users connect their data and run their first analysis, they will love it." Belief without evidence. Without research validating the moment, the wizard is built on theory. + +--- + +## Measuring ah-ha moment effectiveness + +Activation rate is the metric. Completion rate is leading indicator at best. + +**Activation as the metric.** Define activation explicitly (e.g., user returned within 7 days and engaged with feature X). Track it. + +**Wizard completion as leading indicator.** Useful but insufficient. A high completion rate with low activation rate signals the wizard's ah-ha moment is wrong. + +**Time-to-activation.** Hours from signup to activation. Shorter correlates with retention. + +**Per-segment activation.** Different segments may have different activation rates. Surfaces audience-fit issues. + +--- + +## Validating the ah-ha moment + +Once defined, validate. + +**Cohort analysis.** Compare cohorts that hit the moment vs cohorts that did not. Did hitting it correlate with retention? If not, the moment is wrong. + +**User research.** Interview users who hit the moment. Did they recognize it as the ah-ha moment, or just another step? + +**A/B testing.** Test wizard variations that converge on the moment vs variations that do not. Activation rate difference quantifies the moment's value. + +The discipline. The ah-ha moment is a hypothesis until validated. Treat it as such. + +--- + +## Common ah-ha moment failures + +**No defined moment.** Wizard built without identifying the moment; result is decorative. + +**Wrong moment defined.** Moment defined based on intuition; cohort analysis shows it does not predict retention. + +**Moment too late.** Moment lands after multiple sessions; users do not return. + +**Moment requires too much work.** Moment is real but the user has to do significant setup; drop-off before the moment. + +**Moment varies wildly by segment.** Single-moment design fails for an audience with different needs. + +--- + +## Methodology-level choices that stay in the public skill + +The ah-ha principle. Methods for identifying the moment. Common patterns by product type. Designing the wizard around the moment. Time-to-value as design constraint. Audience-specific moments. Anti-patterns. Measurement. Validation. Common failures. + +## Implementation choices that stay internal + +Specific ah-ha moments for specific products. Specific cohort definitions. Specific research methodologies. The team's research capacity. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/common-onboarding-failures.md b/skills/onboarding-wizard-design/references/common-onboarding-failures.md new file mode 100644 index 0000000..63b23a1 --- /dev/null +++ b/skills/onboarding-wizard-design/references/common-onboarding-failures.md @@ -0,0 +1,171 @@ +# Common onboarding failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "activation is low" or "users skip the wizard" or "we cannot tell if the wizard works." + +--- + +## "Activation rate is low; completion rate is high." + +**The diagnosis.** Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. + +**The cure.** Redesign around the ah-ha moment (`references/ah-ha-moment-engineering.md`). Define activation explicitly; verify the wizard produces it; cut steps that do not contribute. + +--- + +## "Skip rate is over 50 percent." + +**The diagnosis.** Either the wizard is not earning its time or skip is too prominent. Audit both. + +**The cure.** Audit step value (each step contribute to ah-ha?). Audit skip prominence (skip too easy?). Detail in `references/step-architecture-patterns.md` and `references/skip-and-resume-mechanics.md`. + +--- + +## "Users complete the wizard then abandon the product within 24 hours." + +**The diagnosis.** Time-to-value too long; ah-ha moment not in first session. + +**The cure.** Move the ah-ha moment earlier. If the moment naturally takes longer, design an interim ah-ha for the first session. + +--- + +## "Wizard works for new users; existing users hit broken steps." + +**The diagnosis.** Wizard not maintained alongside product; deprecated features still in flow. + +**The cure.** Maintenance discipline. Quarterly audit. Product changes trigger wizard updates as part of the change. + +--- + +## "Different segments complete at very different rates." + +**The diagnosis.** Audience-fit varies; consider role-based or use-case-based branching. + +**The cure.** Differentiate by segment where the differentiation produces materially different paths. Detail in `references/user-type-variation-patterns.md`. + +--- + +## "Mobile completion is half of desktop." + +**The diagnosis.** Mobile UX broken or compromised. + +**The cure.** Mobile-first design and testing. Test on actual devices. + +--- + +## "We added more onboarding steps; activation went down." + +**The diagnosis.** Tutorial-overload pattern; more is not better. + +**The cure.** Cut steps that do not contribute to the ah-ha moment. Defer feature explanations to in-product tours. + +--- + +## "Skip mechanics work but users do not return to complete setup." + +**The diagnosis.** Skip-and-defer not working; in-product prompts to return are missing or ignored. + +**The cure.** Audit prompt logic. Ensure prompts trigger at moments of relevance, with frequency limits, and route to the right setup flow. + +--- + +## "Wizard analytics broke after the last release." + +**The diagnosis.** Instrumentation drift; track and refresh. + +**The cure.** Verify analytics after every release. Add a smoke test to the deployment process. + +--- + +## "We A/B tested wizard length; conversion did not change." + +**The diagnosis.** Length alone may not be the issue. Could be step content, skip prominence, or the underlying ah-ha definition. + +**The cure.** Test variables that matter (skip prominence, ah-ha placement, step coherence). Length is one variable; isolate the right one. + +--- + +## "Activation looks good; retention is poor." + +**The diagnosis.** Activation metric may be wrong. Users hit a moment that does not predict retention. + +**The cure.** Validate the ah-ha moment with cohort analysis. Did users who hit it actually retain? If not, the moment is wrong. + +--- + +## "We cannot tell which step needs work." + +**The diagnosis.** Aggregate completion tracked but not per-step. + +**The cure.** Per-step instrumentation (`references/drop-off-measurement-templates.md`). + +--- + +## "Wizard worked great at launch; activation has declined." + +**The diagnosis.** Decay. Audience shifted; product evolved; references stale. + +**The cure.** Quarterly audit. Update what has decayed. + +--- + +## "Sales says the leads from signup are different than they used to be." + +**The diagnosis.** Audience composition shifted; the wizard's segmentation may be obsolete. + +**The cure.** Update branching or differentiation. Audit the audiences arriving and what they need. + +--- + +## "We built a wizard; the team thinks the bot would have been better." + +**The diagnosis.** Possibly. Different products warrant different activation tools. + +**The cure.** Validate. If the bot would serve better, test or migrate. The wizard format is not always the right tool. + +--- + +## "Power users complete the wizard then abandon." + +**The diagnosis.** Wizard does not respect power users' speed. They want to skip ahead. + +**The cure.** Add power-user paths. Skip should be available; advanced configuration should be findable post-wizard. + +--- + +## "We localized the wizard; activation in some locales dropped." + +**The diagnosis.** Translation quality, cultural mismatch, or audience-fit specific to the locale. + +**The cure.** Audit translation. Audit cultural assumptions. Verify audience-fit per locale. + +--- + +## "The wizard works on Chrome; it crashes on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. + +**The cure.** Cross-browser, cross-device testing. + +--- + +## The pattern across failures + +Most onboarding wizard failures fall into one of three patterns. + +**Pattern 1: The wizard does not engineer the ah-ha moment.** Tutorial-overload, decoration steps, demo-as-ah-ha, late ah-ha. The fix is to redefine and converge on the moment. + +**Pattern 2: The wizard does not match the audience.** Skip-friendly-empty, validation-strict, mobile-broken, segment mismatch. The fix is matching the wizard to where the audience actually is. + +**Pattern 3: The wizard decays.** Stale references, broken steps, analytics drift. The fix is maintenance discipline. + +The metric pattern: wizard failures often look fine on completion alone. The signal is in activation, retention, drop-off per step. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (ah-ha, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md b/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md new file mode 100644 index 0000000..6012f5a --- /dev/null +++ b/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md @@ -0,0 +1,230 @@ +# Drop-off measurement templates + +Per-step instrumentation. Common drop-off patterns and remediation. Without per-step tracking, drop-off remediation is guesswork. + +The metrics inform every other improvement. Set up tracking before the wizard launches. + +--- + +## The instrumentation requirement + +Track step start, step completion, step abandonment for every step. + +**Minimum tracking.** + +- Wizard start (user landed on step 1). +- Step start (user reached step N). +- Step completion (user finished step N, advanced to step N+1). +- Step abandonment (user left without completing). +- Wizard completion (user finished all steps, reached end). +- Skip events (per step where applicable). + +**Derived metrics.** + +- Step completion rate (users who reached step / users who completed it). +- Step skip rate (users who reached step / users who skipped). +- Funnel completion rate (started wizard / finished). +- Time per step. + +Without this data, every diagnostic is theoretical. + +--- + +## Common drop-off points + +Three patterns recur across onboarding wizards. + +**First-step drop-off.** User landed on the wizard, looked at it, left. + +Common causes. +- Wizard length visible upfront and intimidating. +- Value proposition unclear. +- Audience expected no wizard. +- Mobile UX broken. + +**Mid-wizard drop-off.** User abandoned mid-process. + +Common causes. +- Specific step too demanding (high field count, sensitive question, ambiguous input). +- Cumulative fatigue (wizard too long). +- Friction at validation or backend processing. +- Time pressure (user expected faster). + +**Late-step drop-off.** User completed most steps but abandoned near the end. + +Common causes. +- Final step requires information the user does not have. +- Wizard length felt longer than expected. +- Submission anxiety (user does not know what happens after). + +--- + +## Remediation patterns + +For each drop-off pattern. + +**First-step drop-off.** + +- Reduce visible upfront length (defer to multi-screen or progressive disclosure). +- Clarify value ("This 5-step setup connects your data and shows your first insight"). +- Reduce step-1 cognitive load (start with the easiest step). +- Test mobile experience. + +**Mid-wizard drop-off.** + +- Audit the high-drop step. Is it too demanding? Sensitive? Ambiguous? +- Reduce field count or split into multiple smaller steps. +- Add progress indicator if missing. +- Add reassurance copy if the step is sensitive. +- Reword ambiguous fields. + +**Late-step drop-off.** + +- Reduce final-step requirements (move some fields earlier). +- Add post-submission preview ("After this, we'll set up your dashboard"). +- Add explicit confirmation step before submission. + +--- + +## Drop-off and skip distinction + +Skip is intentional; drop-off is involuntary. Track them separately. + +**Skip metrics.** + +- Skip rate per step (users who reached step / users who skipped). +- Resume rate per skip (users who skipped step / users who returned to complete). +- Activation rate per skip (users who skipped specific steps and still activated). + +**Drop-off metrics.** + +- Abandonment rate per step (users who reached step / users who left without completing or skipping). +- Time-to-abandonment. +- Re-engagement rate (users who came back to retry the wizard). + +**The diagnostic value.** Skip suggests the user does not value this step right now. Drop-off suggests the wizard failed to engage the user. + +--- + +## Tracking conditional paths + +Wizards with branching logic have multiple paths. + +**Per-path tracking.** + +- Tag each user's path through the wizard. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +**Path-specific remediation.** A path that drops off at step 4 may need step-4 redesign for users on that path. Other paths may not need attention. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +**Segment-level tracking.** + +- Tag users by source, device, role, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +**Common segment patterns.** + +- Mobile users drop off more on long steps. +- Paid-traffic users drop off earlier than organic. +- New users drop off more than returning visitors. + +**Remediation by segment.** Sometimes the right answer is segment-specific (e.g., shorter wizard variant for mobile). + +--- + +## Time-to-completion tracking + +How long the wizard takes. + +**Total time distribution.** Plot the time-to-complete distribution. Median, p25, p75, p95. + +**Per-step time.** Which steps take longest? Are they earning the time? + +**Patterns.** + +- Wizards taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Long-tail completers (p95) often signal usability issues. + +**Remediation by time.** Wizards or steps taking too long should be split or simplified. + +--- + +## A/B testing wizards + +Test changes rigorously. + +**Test design.** Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall activation. + +**Common test types.** + +- Wizard length (shorter vs longer). +- Step ordering (different sequences). +- Field count per step. +- Skip prominence. +- Help text presence/absence. +- Default-heavy vs required-now-optional-later. + +**Test discipline.** One variable at a time. Long enough to capture activation signal. Measure both wizard metrics and downstream activation. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +**The signal.** Wrong audience self-selecting out. A wizard that filters out audiences who would not activate anyway is doing its job. + +**The discipline.** Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream activation metric reveals which. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. + +--- + +## Wizard analytics dashboard + +What to surface. + +**Per-step funnel.** Start rate, completion rate, drop-off rate per step. + +**Skip rates per step.** Where skip is enabled. + +**Time-to-completion distribution.** With percentile breakdown. + +**Activation rate per cohort.** Wizard completers vs non-completers; activation by skip pattern. + +**Trend over time.** Have the metrics changed since the last release? + +--- + +## Common analytics failures + +**No instrumentation.** Wizard launched without tracking; quality is invisible. + +**Aggregate-only tracking.** Wizard completion tracked but not per-step; remediation requires guesswork. + +**Instrumentation drift.** Tracking implemented at launch; field renames or step changes broke the tracking. + +**Skip and drop-off conflated.** Cannot distinguish intentional skip from involuntary drop-off. + +**Activation not tracked.** Wizard metrics in isolation; cannot tell if completion correlates with activation. + +**No segment-level data.** Aggregate hides segment-specific issues. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points and causes. Remediation patterns. Drop-off vs skip distinction. Tracking conditional paths. Per-segment analytics. Time-to-completion. A/B testing. When drop-off is signal. Dashboard composition. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific wizards. Specific tooling. Specific A/B test designs. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md b/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md new file mode 100644 index 0000000..8b831d9 --- /dev/null +++ b/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md @@ -0,0 +1,238 @@ +# Progressive disclosure patterns + +Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Wizards that try to show everything become tutorial-overload. Wizards that defer everything become skip-friendly-empty. Progressive disclosure is the discipline that surfaces what matters when it matters. + +--- + +## Pattern A: Default-heavy + +Each step has smart defaults; the user can accept or override. + +**How it works.** + +- Inputs come pre-filled with sensible defaults. +- The user reviews; accepts most; overrides where their context differs. +- Most users move through quickly; advanced users find the override controls. + +**Strengths.** + +- Reduces cognitive load. +- Faster completion. +- Users without strong preferences proceed; users with strong preferences customize. + +**Weaknesses.** + +- Defaults must be honest. Bias-flattering defaults erode trust. +- Defaults need maintenance as the product evolves. + +**When to use.** Default for most wizards. Smart defaults reduce friction without removing customization. + +--- + +## Pattern B: Required-now, optional-later + +Required fields surface in the wizard; optional configuration surfaces in-product after activation. + +**How it works.** + +- Each step has only required fields. +- Optional configuration appears as in-product prompts after the wizard. +- The wizard stays focused on minimum-viable activation. + +**Strengths.** + +- Shortest possible wizard. +- Optional configuration happens when the user has product context. +- Activation rate improves; configuration completeness rises. + +**Weaknesses.** + +- Requires in-product prompt infrastructure for the deferred configuration. +- Some users may never return to complete deferred setup. + +**When to use.** When the wizard has accumulated optional fields that bloat completion time. The strongest pattern for trimming bloated wizards. + +--- + +## Pattern C: Expand-on-demand + +Sections collapsed by default; the user expands if interested. + +**How it works.** + +- Step shows the minimal interface. +- An "advanced options" or "more details" toggle expands additional fields. +- Most users skip; advanced users explore. + +**Strengths.** + +- Surfaces depth without forcing it. +- Power users get what they need. + +**Weaknesses.** + +- Risk of hiding important fields the user does not realize they need. +- Adds visual complexity to the step. + +**When to use.** When some users genuinely need depth that most do not. Use sparingly; default-heavy plus required-now-optional-later usually serves better. + +--- + +## Pattern D: Branching + +Different users see different steps based on earlier answers. + +**How it works.** + +- Step 1 asks about role, use case, or context. +- Subsequent steps adapt based on the answer. +- Different users effectively complete different wizards. + +**Strengths.** + +- Each user sees only steps that apply to them. +- Wizard feels personalized. + +**Weaknesses.** + +- Significant maintenance complexity. +- Testing burden grows (more paths). +- Analytics must accommodate variable paths. + +**When to use.** When the audience genuinely splits into segments with materially different needs. 2-3 branches max; more becomes unmaintainable. + +--- + +## Pattern E: Hybrid + +Combining patterns. Default-heavy plus required-now-optional-later plus a single branch for major audience split. + +**Strengths.** + +- Reduces friction at multiple levels. +- Different users benefit from different mechanisms. + +**Weaknesses.** + +- Design and maintenance complexity. + +**When to use.** When the wizard's audience and content warrant the combination. Most production wizards land in some hybrid configuration. + +--- + +## What to surface vs defer + +The decision per field. + +**Surface in the wizard.** + +- Fields without which the product cannot work for the user. +- Fields that affect the ah-ha moment. +- Fields that branch downstream steps. +- Fields that personalize the immediate experience. + +**Defer to in-product.** + +- Fields that affect long-term configuration but not immediate value. +- Fields that benefit from product context (the user understands what they are configuring). +- Fields that are commonly skipped anyway; surface them at moments of relevance. + +**The deferable test.** For each wizard field, ask: would the user be better served setting this up after seeing the product, with relevant context? If yes, defer. + +--- + +## Default discipline + +Defaults are powerful. They must be honest. + +**Honest defaults.** + +- Defaults reflect the typical case for the audience. +- Defaults are sourced (from cohort data, common practice, or team judgment). +- Defaults can be overridden visibly. + +**Bias-flattering defaults.** + +- Defaults set to produce favorable signup metrics (cheap plan pre-selected, opt-in checked) without disclosure. +- Defaults that misrepresent the user's real choice. +- Defaults that change over time without user notice. + +The discipline. Defaults reduce friction; they should not extract data or commitment the user did not consent to. + +--- + +## Information density per step + +How much to show. + +**Minimal density.** Just the required fields plus a sentence of context. Shortest, fastest. + +**Moderate density.** Required fields plus brief explanation plus optional toggle. Balanced. + +**Heavy density.** Multiple sections, expandables, detailed help text. Most cognitive load. + +The right density depends on the audience and the step's complexity. Default to minimal; add density only when the step's complexity warrants it. + +--- + +## Help text discipline + +When to include explanatory text. + +**Strong help patterns.** + +- Inline tooltip on non-obvious fields. +- One-sentence explanation per step ("we use this to tailor your dashboard"). +- Examples for fields where the format is ambiguous. + +**Weak help patterns.** + +- Long help text on every field. +- Help text that is marketing rather than explanation. +- Help text that explains things the user already knows. + +The discipline. Help text earns its inclusion when it reduces friction. Help text for the sake of completeness adds clutter. + +--- + +## Mobile considerations + +Progressive disclosure on mobile. + +**Mobile-first defaults.** Default values matter more on mobile because typing is harder. + +**Single question per screen.** Mobile screens are small; multi-field steps cramp. + +**Touch-friendly toggles.** Expand/collapse must be touch-targetable. + +**Minimal help text.** Mobile users skim; long help text is dismissed. + +--- + +## Common progressive disclosure failures + +**No defaults.** Every field blank; the user does work the wizard could have done. + +**Bias-flattering defaults.** Defaults extract commitment the user did not consent to. + +**Over-disclosed.** Every field surfaced; tutorial-overload. + +**Under-disclosed.** Important fields hidden; the user finishes the wizard with a misconfigured product. + +**Branching without need.** Branches that do not produce materially different paths add complexity without benefit. + +**Help text bloat.** Every field has a paragraph of explanation; cognitive load climbs. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns (default-heavy, required-now-optional-later, expand-on-demand, branching, hybrid). Strengths, weaknesses, when-to-use guidance. What to surface vs defer. Default discipline. Information density. Help text discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific wizards. Specific help copy in brand voice. Specific tooling for progressive disclosure. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md b/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md new file mode 100644 index 0000000..b41edba --- /dev/null +++ b/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md @@ -0,0 +1,205 @@ +# Skip and resume mechanics + +Skip patterns and resume patterns. The skip-friendly-empty failure. Honest skip, honest resume. + +When users skip, where they land. When they resume, what they see. Skip mechanics done well let users escape without abandoning; done poorly, they produce skip-friendly-empty wizards where users skip into a useless product and churn. + +--- + +## The skip principle + +Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +**The win.** A user clicks "Skip for now" on a setup step. The product places them in a partially-configured state with a clear callout: "Your workspace needs a connected data source to show insights. Set it up here when you're ready." The user understands; engages later. + +**The fail (skip-friendly-empty).** A user clicks "Skip" on every step. The product places them in an empty state with no context; the user does not know what to do; they leave and never return. + +The discipline. Skip exists, but skip is consequence-honest and recoverable. + +--- + +## Skip patterns + +Common patterns for offering skip. + +**Pattern A: Soft skip with context.** + +How it works. The skip option is available but explains what gets deferred. "Skip for now; we will remind you to connect your data source later." + +When to use. Most wizards. Honest about the consequence; provides a path back. + +**Pattern B: Skip-and-defer.** + +How it works. Skipped steps are queued for later in-product prompts. The wizard does not require completion; the prompts handle re-engagement. + +When to use. When the wizard would otherwise be too long; defer everything that can be deferred. + +**Pattern C: Skip-with-warning.** + +How it works. Skipping triggers an honest warning. "Skipping setup means you won't see [X] until you complete it. Continue?" + +When to use. When skipping has real consequences the user should know about. Use sparingly; warnings on every step desensitize. + +**Pattern D: No skip.** + +How it works. The step must be completed. No skip option. + +When to use. For wizards that absolutely require completion (compliance forms, paid signups, regulatory required steps). Use sparingly; users who cannot skip and cannot complete leave instead. + +--- + +## Skip prominence + +How visible the skip option is. + +**Equal prominence.** Skip and continue have similar visual weight. Honest about both options. Most common. + +**Continue-prominent.** Continue is the visual primary; skip is a secondary link. Encourages completion without forbidding skip. + +**Skip-prominent.** Skip is more visible than continue. Almost never the right choice; produces skip-friendly-empty. + +**Hidden skip.** Skip exists but is hidden behind a "more options" toggle. Discouraged; users cannot find escape if they need it. + +The discipline. Continue-prominent for important steps; equal prominence for most steps; never skip-prominent. + +--- + +## Skip-friendly-empty: the failure mode + +The pattern where skip is too prominent and consequence-free. + +**The pattern.** Every step has a "Skip" button as prominent as "Continue." Skip is consequence-free; users skip every step. + +**The result.** Users land in an empty product; they have no context; they leave. + +**The cost.** Activation rate falls off a cliff. The wizard's design effort produces an experience nobody actually completes. + +**The cure.** Rebalance skip prominence. Make consequences visible. Add resume mechanics so skipped steps can be completed later. + +--- + +## Resume patterns + +Where users land when they return. + +**Auto-resume on next login.** + +How it works. The user returns; the wizard automatically lands at the step they left. + +When to use. When wizard completion is genuinely required for product use. + +**Manual resume from in-product entry.** + +How it works. A persistent "Complete setup" surface in-product returns the user to the wizard. + +When to use. When the wizard is recommended but not required; users can engage with the product partially. + +**Soft resume.** + +How it works. The wizard fades out as the user completes equivalent actions in-product naturally. No explicit re-entry needed. + +When to use. When the in-product experience surfaces equivalent prompts; the wizard becomes redundant. + +**No resume.** + +How it works. Skipped steps are skipped permanently; the wizard runs once. + +When to use. Rarely. Most wizards benefit from some resume mechanism. + +--- + +## Skip-and-defer in-product prompt design + +The prompts that bring users back. + +**Trigger logic.** Prompts trigger based on user behavior, time elapsed, or context. "You have not connected a data source yet; here is how" appears when the user attempts to use a feature requiring data. + +**Frequency limits.** Prompts should not nag. One reminder per session is often enough; some prompts should appear once and dismiss permanently. + +**Dismiss mechanics.** "Don't show this again" is honest. Hidden dismiss options are hostile. + +**Completion routing.** When the user accepts the prompt, route to the right setup flow (often shorter than the original wizard step). + +--- + +## Skip mechanics by step type + +Different steps warrant different skip treatment. + +**Critical setup steps (without which the product cannot work).** Skip should be possible but consequence-warned. Resume mechanics aggressive. + +**Optional configuration steps.** Skip easy and consequence-free; resume mechanics gentle. + +**Identity/personalization steps.** Skip easy; the product can default; resume not necessary. + +**Marketing/data-collection steps.** Skip easy; the product does not need this; resume rarely warranted (skip is a clean signal of opt-out). + +The discipline. Skip prominence and resume aggressiveness should match the step's importance. + +--- + +## Resume measurement + +Track resume effectiveness. + +**Skip rate per step.** What percentage of users skip each step? + +**Resume rate per step.** What percentage of users who skipped a step later return to complete it? + +**Activation rate per skip pattern.** Do users who skipped step X activate at lower rates? + +**Diagnostic uses.** + +- High skip + low resume: wizard losing users who never come back. Audit consequences. +- High skip + high resume: skip-and-defer working. The wizard is producing graceful escapes. +- Low skip overall: wizard is engaging users; check completion and activation as next metrics. + +--- + +## Resume copy discipline + +What the resume prompt says. + +**Helpful resume copy.** + +- "Connect your data source to see insights. It takes 2 minutes." +- "You skipped inviting teammates earlier. Want to do that now?" +- "Almost done. Two steps left to finish setup." + +**Unhelpful resume copy.** + +- "You did not finish onboarding." +- "Complete setup." +- "You missed steps." + +The voice discipline. Resume copy should be helpful, not scolding. The user did not fail; they deferred. + +--- + +## Common skip-and-resume failures + +**Skip too prominent.** Users skip everything; activation collapses. + +**No skip option.** Users who need to escape leave entirely. + +**Hidden skip.** Users cannot find escape; frustration builds; they leave. + +**No resume mechanism.** Skipped users never return to complete; configuration stays incomplete. + +**Aggressive resume prompts.** Prompts every session; users dismiss permanently. + +**Resume routes to wrong place.** User accepts prompt; lands in unrelated flow. + +**Resume copy scolds.** User feels punished for skipping; trust degrades. + +**Skip without consequence-disclosure.** Users skip not knowing what they will miss; abandon when they discover. + +--- + +## Methodology-level choices that stay in the public skill + +The skip principle. Skip patterns (4 patterns). Skip prominence guidance. The skip-friendly-empty failure. Resume patterns (4 patterns). Skip-and-defer prompt design. Skip mechanics by step type. Resume measurement. Resume copy discipline. Common failures. + +## Implementation choices that stay internal + +Specific skip and resume implementations for specific wizards. Specific prompt copy in brand voice. Specific tooling for resume infrastructure. The team's resume measurement baselines. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/step-architecture-patterns.md b/skills/onboarding-wizard-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..b610daf --- /dev/null +++ b/skills/onboarding-wizard-design/references/step-architecture-patterns.md @@ -0,0 +1,225 @@ +# Step architecture patterns + +What belongs in each step. Sequence logic. The step coherence test. + +The architecture is the structure that makes wizards work. Bad architecture produces decorative steps that do not move the user closer to value; good architecture converges on the ah-ha moment with discipline. + +--- + +## The convergence principle + +Each step should move the user one step closer to value. Steps that do not should be cut. + +**The test.** For each step, ask: did this step move the user toward the ah-ha moment? If no, cut it or defer it to in-product help. + +**The discipline.** Wizards accumulate steps over time as teams add "while we have them" requests (collect more data, surface more features, etc.). The discipline is to resist accumulation; the wizard's job is convergence, not feature pride. + +--- + +## Common step patterns + +Patterns that recur across product onboarding wizards. + +**Welcome and orientation.** + +- Purpose: set expectations for what the wizard will do. +- Skippable: usually yes, low cost. +- When to include: when the wizard's purpose is not obvious from context. +- When to skip: when the wizard's purpose is obvious; welcome adds friction without value. + +**Identity and account context.** + +- Purpose: capture who the user is, what brought them here. +- Required fields: minimal. Name and role are often enough. +- When to include: when subsequent steps adapt to identity. +- When to skip: when subsequent steps do not adapt; identity capture is just data collection. + +**Critical setup step.** + +- Purpose: the one thing the product cannot work without. +- Examples: connect data source, invite first teammate, set primary use case. +- This is often where wizards justify their existence. Without this step, the user lands in an empty product. + +**First-action step.** + +- Purpose: get the user to take a meaningful action that produces visible result. +- The ah-ha moment lives here or right after. +- Should be guided enough that success is likely; honest enough that the success is real. + +**Configuration deferral.** + +- Purpose: surface things that can be set up later but are commonly needed. +- Lets the user defer with a clear path back. +- Reduces wizard length without losing coverage. + +**Confirmation and next steps.** + +- Purpose: recap what was set up; surface what to do next; route to in-product home. +- Closes the wizard cleanly. +- Often skipped in design but useful for orientation. + +--- + +## Step sequencing principles + +The order matters as much as the steps themselves. + +**Principle 1: Earn the patience.** Open with low-friction steps; the user invests; deeper setup follows. Critical setup demanding effort works better at step 2-3 than step 1. + +**Principle 2: Ah-ha moment by step 3-5.** If the wizard runs longer than 5 steps before any visible value, drop-off climbs sharply. + +**Principle 3: Deferable last.** Steps that can be deferred should sit late in the wizard, where skip is least costly. + +**Principle 4: Confirmation explicit.** Close the wizard with a clear "you are done; here is what's next" step. Without it, users feel dropped. + +--- + +## Step coherence test + +For each step, can it be described in one sentence as a unit of work that contributes to the ah-ha moment? + +**Coherent steps.** + +- Step 1: tell us about your role so we can tailor what comes next. +- Step 2: connect your data source so we can show you something useful. +- Step 3: run your first query and see a result. +- Step 4: save the result so you can return to it. +- Step 5: optionally invite a teammate; otherwise, you are ready. + +Each step has clear purpose tied to value. + +**Incoherent steps.** + +- Step 1: name and email (already collected at signup; redundant). +- Step 2: tour of features (does not move toward action). +- Step 3: branding preferences (irrelevant to ah-ha moment). +- Step 4: marketing opt-in (data collection, not value). + +Steps without clear purpose should be cut or deferred. + +--- + +## Step count discipline + +How many steps is too many. + +**Sweet spot.** Most effective wizards run 3-7 steps. The user can predict completion time; the convergence is tight. + +**Too few.** 1-2 steps usually means the wizard format is overkill; contextual prompts often serve better. + +**Too many.** 10+ steps signals tutorial-overload. Drop-off climbs sharply; users skip when they can. + +**The deferable test.** For wizards exceeding 7 steps, audit each step. Which can be deferred to in-product? Often half can. + +--- + +## Field count per step + +Within each step, how many fields. + +**3-5 fields per step.** Sweet spot. Coherent unit; completable in 30-60 seconds. + +**1-2 fields per step.** Often signals over-staging. The user wonders why the field needed its own step. + +**6+ fields per step.** Recreates the kitchen-sink problem within a step. Audit; usually some fields can be cut or deferred. + +--- + +## Branching and conditional steps + +When wizards adapt based on earlier answers. + +**The pattern.** First step asks about role or use case; subsequent steps adapt. + +**Strengths.** The wizard feels relevant; users see only what applies to them. + +**Weaknesses.** Maintenance complexity; testing across paths. + +**The discipline.** Branch only when the variability genuinely benefits the user. Decorative branching adds cost without lift. + +--- + +## Step transitions + +How the user moves between steps. + +**Forward transitions.** Clear "Next" or "Continue" CTA. Validation runs before the transition. Snappy; no loading delays. + +**Back transitions.** "Back" or "Previous" available. Returning to earlier steps preserves answers. + +**Skip transitions.** Skip available but honest about consequences. Skip lands the user in a partially-set-up state with clear callouts to complete deferred setup. + +**Loading state.** When the wizard's step requires backend work (connecting data source, processing input), show progress. Silent loading kills momentum. + +--- + +## Step examples by product type + +How architecture varies by product. + +**B2B SaaS analytics.** + +- Welcome → role/use case → connect data source → first query → first saved view → invite team (deferable) → in-product home. + +7 steps; meaningful staging; ah-ha at step 5. + +**Project management tool.** + +- Welcome → workspace setup → first project → first task → invite team → in-product home. + +6 steps; ah-ha around step 4. + +**Marketing automation.** + +- Welcome → connect site → connect data source → first audience → first campaign → in-product home. + +6 steps; ah-ha at first audience visualization. + +**Consumer note-taking.** + +- Probably no wizard. Empty-state prompts and contextual hints serve better. + +The patterns vary. The discipline (each step earns its place; ah-ha moment by step 3-5) holds. + +--- + +## Step architecture maintenance + +Steps decay. Product changes mean wizard updates. + +**Maintenance triggers.** + +- Product feature added that the wizard should reference. +- Product feature deprecated that the wizard still references. +- Setup process changed; wizard steps no longer match. +- Audience composition shifted; old role-branching no longer fits. + +**Maintenance cadence.** Quarterly review minimum; product changes trigger updates as part of the change. + +--- + +## Common architecture failures + +**Decorative steps.** Steps that do not move toward value. + +**Tutorial steps.** Steps explaining features the user has not asked about. + +**Front-loaded effort.** High-friction step first; users abandon at step 1. + +**Late ah-ha moment.** Wizard runs 10 steps before visible value. + +**Mandatory steps that should be deferable.** Forces friction users would have accepted later. + +**No confirmation step.** User finishes the wizard, lands somewhere unclear. + +**Step transitions sluggish.** Loading delays kill momentum. + +--- + +## Methodology-level choices that stay in the public skill + +The convergence principle. Common step patterns. Sequencing principles. The step coherence test. Step count discipline. Field count per step. Branching considerations. Step transitions. Step examples by product type. Maintenance discipline. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific products. Specific copy and tone. Specific tooling. Specific testing protocols. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/user-type-variation-patterns.md b/skills/onboarding-wizard-design/references/user-type-variation-patterns.md new file mode 100644 index 0000000..d274a99 --- /dev/null +++ b/skills/onboarding-wizard-design/references/user-type-variation-patterns.md @@ -0,0 +1,199 @@ +# User type variation patterns + +Admin vs end-user, technical vs non-technical, size-based branching. When one wizard does not serve all users. + +Different users may need different wizards. The discipline is to differentiate where the audience genuinely splits, without producing unmaintainable proliferation. + +--- + +## The differentiation principle + +Differentiate where the audience genuinely splits into segments with materially different needs, language, or paths. Do not differentiate where one wizard serves all. + +**The win.** Admins set up the workspace; end-users start using it. A single wizard tries to serve both and fails both. Differentiated wizards serve each meaningfully. + +**The fail.** A team builds 5 wizard variants for 5 imagined personas. Maintenance burden compounds; the variants diverge over time; no variant is excellent. + +The discipline. Start with one wizard. Differentiate only when data shows segments with different needs and the differentiation produces meaningfully different paths. + +--- + +## Common differentiation axes + +Three axes recur. + +**Admin vs end-user.** + +- Admins set up the workspace, invite teammates, configure integrations. +- End-users start using what admins set up. +- Their first sessions look different; the ah-ha moments differ. + +**Technical vs non-technical.** + +- Technical users want depth (see the API, see the integration succeed, configure deeply). +- Non-technical users want outcome (see the result, no API). +- Tone, content, and step coverage differ. + +**Size of team.** + +- Solo founders configure for one. +- Small teams configure for collaboration. +- Enterprise teams have additional setup (SSO, governance, compliance). + +--- + +## Differentiation patterns + +How to implement. + +**Pattern A: Role-based branching.** + +How it works. First step asks role; subsequent steps adapt. + +When to use. When the role split is clear and produces different paths. + +**Pattern B: Use-case-based branching.** + +How it works. First step asks use case; wizard tailors to that use case. + +When to use. When the product serves multiple use cases that warrant different ah-ha moments. + +**Pattern C: Size-based branching.** + +How it works. First step asks team size; solo, team, enterprise paths differ. + +When to use. When the product has materially different setups for different scales. + +**Pattern D: Inferred branching.** + +How it works. Wizard uses signals (signup source, email domain, prior interaction) to infer the segment without asking. + +When to use. When asking would feel intrusive but the inference is reliable. + +**Pattern E: No branching.** + +How it works. Single wizard for all. + +When to use. Most products. Branching adds maintenance; only branch when the value is clear. + +--- + +## Admin vs end-user wizard design + +How they differ. + +**Admin wizard.** + +- Setup-heavy. Connect data, invite team, configure permissions. +- Ah-ha moment: "the workspace is ready; my team can use it." +- Often longer; admins accept guided setup. + +**End-user wizard.** + +- Action-light. Find the feature, take the first action, see the result. +- Ah-ha moment: "I did the thing I came to do." +- Often shorter; end-users want to start using. + +**Cross-talk.** Admins sometimes also become end-users in single-person teams. The wizard may need to detect and serve both modes. + +--- + +## Technical vs non-technical wizard design + +How they differ. + +**Technical wizard.** + +- API depth visible (configuration shown, integration tested). +- Tone: precise, terse, references documentation. +- Ah-ha moment: "the integration works; my data is flowing." + +**Non-technical wizard.** + +- Outcome visible (result shown, no API exposed). +- Tone: warm, supportive, hides technical complexity. +- Ah-ha moment: "I see the result the product promised." + +**Cross-talk.** Some users are technical for some products and not for others. The wizard may infer rather than ask. + +--- + +## Size-based wizard design + +How they differ. + +**Solo founder wizard.** + +- Single-user setup. +- Skip team-related steps. +- Ah-ha moment: individual productivity. + +**Small team wizard.** + +- Collaboration setup highlighted. +- Invite-team step prominent. +- Ah-ha moment: team coordination. + +**Enterprise wizard.** + +- SSO, governance, compliance setup. +- Often involves admin handoff to IT or security. +- Ah-ha moment: deployment-ready configuration. + +--- + +## When to combine vs separate + +Designing the matrix. + +**Combine when:** + +- The differentiation is small (1-2 different steps). +- Maintenance burden is the bigger concern. +- The audiences overlap significantly. + +**Separate when:** + +- The paths differ in 3+ steps. +- Tone and language differ significantly. +- Audience-fit is critical (B2B SaaS where different roles experience the product very differently). + +**The 2-3 variants max rule.** More than 3 wizard variants becomes unmaintainable. If 4+ variants seem necessary, reconsider whether the segmentation is too granular or whether different wizards should be different products. + +--- + +## Differentiation testing + +Verify the differentiation works. + +**Cohort comparison.** Compare activation rates across variants. Did differentiation help? + +**Per-segment satisfaction.** Survey users post-wizard. Does each segment feel served? + +**Drop-off per variant.** Are some variants dropping off more than others? Which steps? + +The data informs whether the differentiation earned its complexity. + +--- + +## Common differentiation failures + +**Over-differentiation.** Too many variants; maintenance burden; no variant is excellent. + +**Under-differentiation.** One wizard for distinct audiences; everyone feels poorly served. + +**Wrong axis.** Differentiated by an axis that does not predict need (e.g., gender when role would have been the right split). + +**Inferred wrongly.** Inference logic mistakes audience; users see wrong wizard. + +**Stale differentiation.** Audience composition shifted; old branching no longer fits. + +--- + +## Methodology-level choices that stay in the public skill + +The differentiation principle. Common differentiation axes. Patterns A through E. Admin vs end-user design. Technical vs non-technical design. Size-based design. Combine-vs-separate decision. Differentiation testing. Common failures. + +## Implementation choices that stay internal + +Specific wizard variants for specific products. Specific copy per variant in brand voice. Specific inference logic. The team's variant maintenance calendars. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/wizard-anti-patterns.md b/skills/onboarding-wizard-design/references/wizard-anti-patterns.md new file mode 100644 index 0000000..01f9cfc --- /dev/null +++ b/skills/onboarding-wizard-design/references/wizard-anti-patterns.md @@ -0,0 +1,212 @@ +# Wizard anti-patterns + +The patterns that look like onboarding but degrade activation. Anti-patterns are easy to ship; the cost shows up in activation rate, retention, and brand reputation over time. + +--- + +## The tutorial-overload wizard + +The pattern. Every feature explained in a 12-step intro before the user has touched the product. + +The signal. High skip rate; users abandon mid-wizard; activation rate poor. + +The cost. Design effort produces a sequence almost nobody completes. Users who do complete have not seen value; activation suffers. + +The cure. Prune steps to those that contribute to the ah-ha moment. Defer feature explanations to in-product tours and contextual help. + +--- + +## The skip-friendly-empty wizard + +The pattern. "Skip onboarding" button at every step, so prominent that users always take it. + +The signal. Skip rate near 100 percent; users land in unconfigured product; activation rate falls. + +The cost. The product appears empty to users who skipped; they do not know what to do; they leave. + +The cure. Rebalance skip prominence. Add consequence-honest skip warnings. Add resume mechanisms so skipped steps come back as in-product prompts. + +--- + +## The decoration-step wizard + +The pattern. Steps that exist for completeness or feature pride, not for value. + +The signal. Drop-off concentrates on specific steps users perceive as pointless; analytics shows steps users always skip. + +The cost. Wizard length without value; user perceives the wizard as bloated. + +The cure. Audit each step. Cut steps that do not contribute to the ah-ha moment. + +--- + +## The tutorial-as-ah-ha wizard + +The pattern. Treating "learned about features" as activation. Wizard ends; user has seen a tour; team treats this as success. + +The signal. High completion rate, low retention. Users completed the wizard but did not engage afterward. + +The cost. The wizard's success metric is wrong. Real activation never happens. + +The cure. Define the ah-ha moment as action-tied. Redesign the wizard to converge on the moment. + +--- + +## The demo-as-ah-ha wizard + +The pattern. The wizard ends with a polished demo using fake data. + +The signal. Users see what is possible; do not return because their actual data has not been touched. + +The cost. The wizard's value is contrived; activation does not stick because the value was hypothetical. + +The cure. Make the ah-ha moment real. Use the user's actual data. + +--- + +## The over-branched wizard + +The pattern. 5 wizard variants for 5 imagined personas. Maintenance burden compounds. + +The signal. Variants diverge over time; some break; activation per variant is uneven. + +The cost. Maintenance overhead high; quality of any one variant degrades. + +The cure. Reduce variants to 2-3 max. Combine variants where the differentiation does not produce materially different paths. + +--- + +## The under-branched wizard + +The pattern. One wizard for distinct audiences. Admins, end-users, technical, non-technical all see the same flow. + +The signal. Some segments activate well; others do not. Per-segment data shows the gap. + +The cost. The audiences underserved leave; the wizard's design effort produces good outcomes for one segment and bad for others. + +The cure. Differentiate where the audience genuinely splits. + +--- + +## The hidden-skip wizard + +The pattern. Skip exists but is hidden behind a "more options" toggle or appears only after the user struggles. + +The signal. Users who need to escape leave the product entirely instead of skipping. + +The cost. Forced friction loses users who would have engaged later if they had been allowed to defer. + +The cure. Make skip findable. Make consequences clear. Add resume. + +--- + +## The validation-strict wizard + +The pattern. Validation rejects valid inputs because rules are over-specified. + +The signal. Users with valid but unusual inputs cannot proceed; abandon. + +The cost. Filter loses real users. + +The cure. Audit validation. Email plus-aliases, international phone, non-Latin names should pass. + +--- + +## The mobile-broken wizard + +The pattern. Wizard works on desktop; breaks on mobile. + +The signal. Mobile completion half of desktop or worse. + +The cost. Mobile audience underserved; mobile is often majority of traffic. + +The cure. Mobile-first design and testing. + +--- + +## The unmaintained wizard + +The pattern. Wizard built once; product evolved; wizard not updated. + +The signal. Users hit broken steps; references to deprecated features; analytics drift. + +The cost. The wizard becomes liability; current users get worse experience than past users. + +The cure. Quarterly maintenance. Product changes trigger wizard updates as part of the change. + +--- + +## The interrogation-disguised-as-wizard + +The pattern. Wizard asks 12 fields, of which 5 affect product setup. The other 7 are sales-qualification or marketing data. + +The signal. Drop-off climbs at fields that feel like sales forms; users sense the manipulation. + +The cost. Filter loses users who would have engaged with a product-focused wizard. + +The cure. Audit fields. Remove or defer fields that do not contribute to product setup. Capture sales/marketing data later in the relationship. + +--- + +## The popup-interrupted wizard + +The pattern. User is mid-wizard; a popup appears (newsletter, chat, special offer); flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about interruption. + +The cost. Wizard's user experience hostile; brand earns annoying reputation. + +The cure. Suppress popups during wizard completion. Save promotional content for after. + +--- + +## The reset-on-error wizard + +The pattern. User submits; validation fails; wizard resets, losing user inputs. + +The signal. Users who hit error do not retry; they leave. + +The cost. The wizard treats errors punitively; trust collapses. + +The cure. Preserve inputs on error. Show error inline; let the user fix and resubmit. + +--- + +## The wizard-without-activation-metric + +The pattern. Wizard tracked by completion rate alone. Activation not measured. + +The signal. Completion looks fine; team cannot diagnose whether the wizard is producing engaged users. + +The cost. The wizard's success metric is wrong; bad wizards look good in dashboards. + +The cure. Define and track activation explicitly. Wizard completion is leading indicator at best. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active wizard, looking for these anti-patterns. + +**Audit questions per wizard.** + +- Does each step contribute to the ah-ha moment (anti-pattern check: tutorial-overload, decoration)? +- Is skip honest about consequences and recoverable (anti-pattern check: skip-friendly-empty, hidden-skip)? +- Does the wizard match the product's current state (anti-pattern check: unmaintained)? +- Is activation tracked (anti-pattern check: completion-only metrics)? +- Does the wizard work on mobile (anti-pattern check: mobile-broken)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is the audience segmentation right (anti-pattern check: over-branched, under-branched)? + +**The retire decision.** Anti-pattern wizards often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/onboarding-wizard-design/references/wizard-decision-criteria.md b/skills/onboarding-wizard-design/references/wizard-decision-criteria.md new file mode 100644 index 0000000..f1ec10b --- /dev/null +++ b/skills/onboarding-wizard-design/references/wizard-decision-criteria.md @@ -0,0 +1,133 @@ +# Wizard decision criteria + +When wizards earn the build vs when contextual help suffices. The conditions that warrant the wizard format, and the funnels where a wizard adds friction without lift. + +A wizard is meaningful work. Step architecture, ah-ha moment design, progressive disclosure, skip mechanics, drop-off instrumentation, ongoing maintenance. The wizard earns this investment only when specific conditions are present. + +--- + +## When wizards earn the build + +Five conditions that, when present, make a wizard a strong investment. + +**The product has meaningful setup before value emerges.** Connect a data source, invite a teammate, configure a workspace, choose a use case. Without setup, the product is empty; the wizard makes setup tractable. Products that work immediately on signup do not need this. + +**The ah-ha moment requires multiple actions in sequence.** Single-action ah-ah moments (paste a URL, see a result) often work better with contextual prompts. Multi-action ah-ha moments benefit from a guided sequence. + +**The audience expects guided onboarding.** B2B SaaS with technical setup, enterprise software, configurable products often work well with wizards. Some audiences (frictionless consumer tools) reject wizard friction regardless of product complexity. + +**The team can maintain the wizard.** Wizards decay as the product evolves; deprecated features still in flow break the experience. Without maintenance commitment, the wizard becomes a liability. + +**The success metric is defined.** Not just completion rate; activation rate (post-wizard product engagement) and time-to-value. Without the success metric, evaluation is impossible. + +When all five are present, the wizard is a strong investment. When two or fewer are present, contextual prompts often serve better. + +--- + +## When wizards do NOT earn the build + +Funnels where the wizard adds friction without lift. + +**The product reaches value immediately.** Single-input tools, simple consumer products, frictionless utilities. A wizard adds steps where the user could already see value. + +**Contextual help would suffice.** Tooltips, in-feature hints, progressive in-product education sometimes serve better than upfront wizards. The user explores naturally; help surfaces when needed. + +**The audience expects no friction.** Some audiences abandon at any wizard. Consumer-facing high-volume products, embedded tools, prosumer utilities. Meet the audience where they are. + +**The team cannot maintain the wizard.** Stale wizards point to deprecated features; users hit broken steps. Without maintenance capacity, no wizard is better than a stale one. + +**The setup work is genuinely better in-product.** Some setup is better done after the user understands the product. Wizards that try to set up something the user does not yet understand produce poor configuration. + +The honest assessment matters more than the default. "Should we have an onboarding wizard" is not the question. "Is the wizard the right tool for this product and audience" is. + +--- + +## The opportunity-cost frame + +A wizard is significant work. Account for it. + +**The build cost.** Step architecture, copy, design, instrumentation, integration with the product, maintenance scaffolding. A meaningful wizard often takes 40-150 engineering hours plus design and copy. + +**The maintenance cost.** Quarterly review minimum; product changes trigger wizard updates. 4-12 hours per active wizard per quarter. + +**The opportunity cost.** What else could the team have built? Direct in-product improvements, contextual help, documentation, a simpler activation funnel. The wizard's success has to clear the bar of those alternatives. + +The decision frame. The wizard earns investment when it produces more activation lift than the alternatives, accounting for build plus maintenance. + +--- + +## The ah-ha-moment precondition + +Without an identifiable ah-ha moment, the wizard has nothing to engineer toward. + +The check. Can the team articulate the single visible moment when the user feels "oh, this is what the product does for me"? + +If yes, the wizard can be designed to converge on that moment. If no, the team has not yet defined what activation means; the wizard cannot be designed coherently until that is settled. + +**Defining the ah-ha moment is upstream of wizard design.** Sometimes the right move is to spend time identifying the ah-ha moment first (often through customer research) before scoping the wizard. The wizard built without a defined ah-ha moment is the wizard that produces high completion and low activation. + +--- + +## The decision worked example + +A B2B SaaS analytics platform considering an onboarding wizard. + +**Conditions check.** + +- Meaningful setup before value: yes. Connect at least one data source. +- Ah-ha moment multi-action: yes. Connect data, run first query, see useful result. +- Audience expects guided onboarding: yes. Data analysts and data leaders generally accept guided setup. +- Maintenance commitment: yes. Activation team owns the wizard. +- Success metric defined: yes. Activation = ran at least one query within 7 days of signup. + +**Decision.** Build the wizard. The conditions warrant it. + +**Step architecture.** Welcome (skippable) → connect first data source → confirm connection → guided first query → see result (ah-ha moment) → invite teammates (deferable) → in-product home. + +**Maintenance commitment.** Activation team reviews quarterly; product changes trigger wizard updates. + +The decision was not "should we have a wizard" but "given these conditions, this is the wizard to build." + +--- + +## The decision worked example: when to choose differently + +A consumer note-taking app considering an onboarding wizard. + +**Conditions check.** + +- Meaningful setup: no. The user can start typing immediately. +- Ah-ha moment multi-action: no. The ah-ha moment is "I can save a note and find it later," reachable without setup. +- Audience expects guided onboarding: no. Consumer note-taking audiences resist friction. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined (returned within 7 days). + +**Decision.** Do not build a wizard. Contextual prompts (sample notes, brief tooltip on first save, short empty-state prompts) serve better. + +The decision was "is this wizard right for this product" and the answer was no even though the team had capacity. + +--- + +## When to retire a wizard + +Wizards can become wrong even after being right initially. + +**Retire when:** + +- Activation rate has dropped below baseline for two consecutive quarters and refinements have not moved it. +- The product has changed enough that the wizard guides users toward deprecated paths. +- Customer research shows users skipping the wizard and activating fine without it. +- A redesigned in-product activation flow makes the wizard unnecessary. +- The team can no longer maintain the wizard. + +The retiring discipline frees capacity. Stale wizards are worse than no wizards. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant a wizard. The five conditions that argue against. The opportunity-cost frame. The ah-ha-moment precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific wizard scope decisions for specific products. The team's capacity benchmarks. Specific tooling for wizard implementation and instrumentation. Specific success-metric baselines. These vary by team and product. diff --git a/skills/paid-media-strategy/SKILL.md b/skills/paid-media-strategy/SKILL.md new file mode 100644 index 0000000..2d0a67b --- /dev/null +++ b/skills/paid-media-strategy/SKILL.md @@ -0,0 +1,256 @@ +--- +name: paid-media-strategy +description: "A discipline for running paid media that does not light money on fire. Hypothesis writing for paid spend, channel selection, budget allocation, audience targeting, bid strategy, campaign types, what NOT to spend on, attribution reality, and the failure modes that produce expensive lessons. Triggers on paid media strategy, ad budget allocation, channel selection, paid media plan, audit my Google Ads, audit my Meta Ads, scale paid media, kill underperforming campaign, paid media hypothesis, ad spend strategy, attribution reality, performance marketing strategy. Also triggers when a team is asking how to scale paid media, or whether to add a new channel, or how to reallocate spend across channels." +category: marketing +catalog_summary: "Hypothesis to spend: channel selection, budget allocation, audience targeting, bid strategy, attribution reality, and the failure modes that burn agency-scale budgets" +display_order: 1 +--- + +# Paid Media Strategy + +A senior performance marketer's playbook for running paid media that produces real outcomes. + +The default state of paid media is wasted spend. Most accounts have campaigns running because they always have, audiences targeting because the rep suggested it, bid strategies on auto because manual is hard, creative not refreshed because there is no system. The cost compounds. A 20% efficiency gain on a $500K-per-year account is $100K back to the business. A 50% gain on a $5M-per-year account is $2.5M. + +This skill is the discipline that produces those gains. It assumes you have a paid media platform (Google Ads, Meta, LinkedIn, TikTok, or aggregators like Synter) connected. It assumes you have working analytics and conversion tracking. The hard part is the strategic discipline behind the spend, and that is what is here. + +When to use this skill: any time you are designing a paid media plan, evaluating whether to scale or kill a campaign, allocating budget across channels, or auditing an existing account. + +--- + +## What this skill is for + +This skill spans paid media strategy and operations. It does not cover ad creative production (use `ads-creative-development`), result interpretation in depth (use `ads-performance-analytics`), or platform-specific MCP tooling (consult each ad platform's official documentation for current MCP setup, auth, and example prompts). + +The audience is a performance marketer (in-house or agency), a growth lead allocating spend across channels, or a founder making early paid budget decisions. The voice is tactical. There is no "evaluate every option yourself with no opinion." Paid media decisions have shape, and a senior practitioner can map a situation to a defensible plan in an afternoon. + +--- + +## Hypothesis discipline for paid spend + +Most paid media failures start with a vague reason for spending. A real spend hypothesis has five parts: audience, offer, channel, outcome metric, and magnitude. Missing any of them and the campaign cannot be evaluated honestly. + +A bad reason: "We need to scale Google Ads spend." No audience, no outcome metric, no magnitude. Nothing is falsifiable. + +A good hypothesis: "Top-of-funnel SaaS prospects searching for project management tools convert from a free-trial CTA at 3.2% CAC under $80. Increasing Search budget from $40K to $80K per month should hold CAC under $80 and add roughly 500 trial signups based on Q3 search volume." + +That hypothesis names the audience (top-of-funnel SaaS prospects on PM-tool keywords), the offer (free trial), the channel (Google Search), the outcome metric (CAC, trial signups), and the magnitude (500 signups, CAC under $80). It is falsifiable: if CAC blows past $80 or signups come in below 250, the hypothesis is wrong and you pull back. + +Pre-commit the falsification rule. Decide before scale: at what CAC do we hold? At what CAC do we pull back? At what trial-signup count do we kill? Without pre-commit, every result becomes a debate. With pre-commit, the decision is mechanical. + +Primary metric is the one you are optimizing for (CAC, ROAS, CPL). Guardrails are the metrics you do not want to break (LTV, retention, brand search lift). Scaling the primary metric while breaking a guardrail is a Pyrrhic win. + +--- + +## Channel selection: when to use which platform + +Pick the channel where intent matches your offer. Run the wrong channel and your CAC reads as a channel problem when it is actually a fit problem. + +**Google Search.** High-intent demand capture. Best when you have a real product people search for and the query volume justifies the floor. Worst when category awareness is low and no one is searching. Predictable, expensive at scale, the highest floor of any channel. + +**Google Performance Max.** Automated multi-channel within the Google ecosystem. Best when you have a strong product feed (e-commerce) or want to lean into Google's automation. Worst when you need control over placements; PMax is a black box and disagreements with the algorithm cost money. + +**Meta (Facebook plus Instagram).** Broad-targeting demand creation. Best for visual products, lifestyle brands, B2C scale, and direct response with strong creative. Worst when targeting is too narrow (audiences saturate fast) or when the offer is high-consideration B2B. + +**TikTok.** Discovery-mode advertising. Best for native-feeling video creative, younger audiences, and brand awareness. Worst for direct response with high consideration cycles. Spark Ads (boosting organic posts) outperform pure paid creative. + +**LinkedIn.** B2B targeting precision. Best for high-LTV B2B with clear job-title targeting. Worst for low-AOV products; the floor is too high to be efficient. + +**Reddit, Pinterest, Snapchat, X.** Niche or supplementary. Best as scale-out channels after primary channels are working. Worst as starting points; spreading thin across niches before you have proven any channel is the most common waste pattern. + +**YouTube (Google).** Video at scale. Best for awareness or for B2C consideration. Underrated for B2B SaaS in some categories where the buyer-research path includes long-form video. + +The decision rule. Start with the channel where intent matches your offer. Search for high-intent demand capture. Meta or TikTok for demand creation. LinkedIn for B2B precision. Do not run all of them at once until you have proven any of them. Detail in [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md). + +--- + +## Budget allocation: brand vs performance, baseline vs test + +Four splits operate at the same time. Get them all right and the budget compounds. + +**Brand vs performance.** Brand keeps the demand pipeline filled (long term); performance captures it (short term). 70-30 to 80-20 performance-heavy is typical for most B2C. Brand-heavy splits fit high-consideration B2B where the buying cycle is months long and pipeline visibility matters more than week-over-week conversions. + +**Baseline vs test.** 70 to 80% of budget to channels, campaigns, and audiences that are working. 20 to 30% to systematic testing of new channels, new audiences, new creative. Without test budget, you stagnate. Without baseline budget, you have nothing to scale. + +**Primary vs secondary channel.** One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the equal-split temptation; spreading across channels before any one is proven is the most expensive way to learn nothing. + +**Daily vs lifetime budgets.** Daily for ongoing campaigns where you want a stable spend floor. Lifetime for finite tests where the platform should pace itself across the test window. Lifetime budgets prevent runaway spend during testing. + +Budget pacing matters too. Front-load some weeks to test creative aggressively. Back-load others to capture seasonality (holiday, end-of-quarter, category-specific moments). Do not run flat; flat budgets miss the demand peaks. + +Detail and templates in [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md). + +--- + +## Audience targeting: prospecting vs retargeting vs exclusion + +Three audience types. Treat them as separate strategies. + +**Prospecting.** New people who have not heard of you. Lookalike audiences (Meta), in-market audiences (Google), interest stacks, lookalikes seeded from high-LTV customers. Largest budget share for growth-mode brands; this is where new demand comes from. + +**Retargeting.** People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC. Do not bid too aggressively or you train the platform to charge a premium for users who would have converted anyway. + +**Exclusion.** Current customers and recent converters kept out of prospecting and retargeting. Saves spend, keeps frequency low, prevents creative fatigue from people who are already paying you. + +Common mistakes. Prospecting too narrow (not enough audience for the platform to optimize). Retargeting too aggressive (cannibalizing organic conversions). No exclusions (paying to advertise to your own paying customers). Lookalikes off the wrong source (use top-LTV customers, not all customers). + +Detail in [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md). + +--- + +## Bid strategy: when each fits + +Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. + +**Manual CPC or CPM.** Full control, slow to scale. Useful for diagnostics and very early campaigns where you do not trust the platform's machine learning yet. + +**Maximize Conversions.** Platform optimizes for volume within budget; the platform decides CPC. Use when you want as many conversions as possible regardless of cost. Good early-stage strategy while you gather data. + +**Target CPA (tCPA).** Set a max CPA, platform delivers within. Use when CPA is the constraint and you have at least 30 conversions in the recent window for the platform to optimize against. + +**Target ROAS (tROAS).** Set a min ROAS, platform delivers above. Use when revenue per conversion varies and you care about value, not count. + +**Maximum Conversion Value.** Like maximize conversions but optimizes for total revenue, not count. Use when high-value conversions are the goal and you have the conversion-value data wired in. + +**Enhanced CPC.** Manual CPC with platform adjustments. Hybrid; rarely the right answer because it muddies the signal. + +The progression for new campaigns: start manual or maximize conversions to gather data, switch to tCPA or tROAS once you have 30+ conversions, revisit periodically. + +Common mistakes. Using tCPA before you have 30+ conversions (no data to optimize against). Setting tROAS too aggressively (platform throttles delivery). Switching strategies too often (each change resets the learning phase). Detail in [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md). + +--- + +## Campaign types + +For each major platform, the campaign types and when to use them. + +**Google Ads.** Search, Shopping, Performance Max, Display, Video (YouTube), Demand Gen, Discovery, App. Search for direct demand capture. PMax for catalog-driven e-commerce. Display for retargeting. Video for awareness or consideration. + +**Meta.** Sales, Leads, Engagement, Awareness, Traffic, App Promotion. Sales for direct response. Awareness for brand at scale. Leads for B2B with native lead forms. + +**LinkedIn.** Sponsored Content, Message Ads, Conversation Ads, Lead Gen Forms. Format types: Single Image, Carousel, Video. Lead Gen Forms convert hardest because they pre-fill from LinkedIn profile data. Message Ads have stigma in many B2B segments; use carefully. + +**TikTok.** In-Feed, TopView, Spark Ads, Branded Hashtag Challenge. Spark Ads (boost organic posts) outperform pure paid creative because they retain organic-feel signal. Use Spark when you have organic posts performing. + +Detail per platform in [`references/campaign-type-reference.md`](references/campaign-type-reference.md). + +--- + +## What NOT to spend on + +Direct list. Audit any account against these and you will usually find easy savings. + +- **Branded keywords beyond defensive.** When ranking number one organically, branded paid clicks cannibalize free traffic. Some defensive spend is fine to block competitor bidding. Aggressive bidding on your own brand is waste. +- **Display network without targeting.** Broad display drives garbage traffic. Use only for retargeting unless you have specific contextual targeting. +- **Geographic markets you do not serve.** Sounds obvious, fails 30% of accounts. Audit geo targeting quarterly. +- **Hours you cannot service.** For service businesses (legal, B2B, medical). Pause off-hours unless lead form clearly converts asynchronously. +- **Devices that do not convert.** If mobile converts at 1% and desktop at 5% with the same CPC, bid down mobile aggressively. +- **Audiences who never convert.** Pull last 90 days of converters, build exclusion lists for everyone else who repeatedly clicks but never converts. +- **Creative that is tired.** Frequency above 4 with declining CTR means refresh. Refusing to refresh because "it still works ok" is incremental loss. + +The pattern across these is the same. Default settings or accumulated cruft generate spend without producing outcomes. Audit, exclude, and reclaim. + +--- + +## Creative testing: within campaign vs across campaign + +Two modes. Different learning rates, different overhead. + +Within-campaign testing rotates 4 to 6 ad variations and lets the platform optimize delivery to top performers. Lower test risk because all variations live inside one campaign with one budget. Slower learning because the platform's optimization muddies the signal of which variation actually wins. + +Across-campaign testing runs entire campaign concepts (audience plus offer plus creative) against each other. Higher learning rate because each campaign has its own audience and budget. Higher setup overhead and harder to keep apples-to-apples. + +Cadence. Refresh top creative every 30 to 60 days at scale. Weekly for high-frequency campaigns. Keep the top one or two evergreen winners running and rotate others. + +The "winning creative is the floor" principle. Do not kill winners to test new ideas. Test alongside. The downside of running the proven winner is small; the downside of killing it for an unproven concept is large. + +--- + +## Frequency capping + +Ad fatigue is real. Same audience seeing the same creative eight times in a week tunes it out, or worse, develops negative associations. + +Typical caps. Three to four impressions per user per week for Awareness campaigns. Six to eight per week for Direct Response. Lower for B2B (one to two per week per LinkedIn target). Platform defaults are usually too high; set explicit caps. + +Rotation as alternative. If you have enough creative variants, rotate often enough that no individual creative hits fatigue threshold. Rotation plus capping is the strongest pattern for high-spend, long-running campaigns. + +--- + +## Attribution mismatch: platform-reported vs actual + +The trap. Platform-reported conversions are inflated by view-through attribution, generous click attribution windows, and platform self-attribution bias. + +**Last-click in GA vs platform-reported.** Google Ads typically reports 1.3 to 1.5x the conversions GA reports. The gap comes from multi-touch attribution differences and view-through that GA does not credit. + +**iOS 14.5+ impact.** Meta and other platforms underreport iOS conversions because of App Tracking Transparency. Modeled conversions try to fill the gap; they are imperfect. Treat iOS-heavy reporting with extra skepticism. + +**View-through attribution.** Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Useful for awareness; misleading for performance optimization. + +**Cross-platform interference.** Meta retargeting captures users who would have converted from Google Search anyway. Both platforms claim the conversion. You pay for the same conversion twice. + +The discipline. Single source of truth in your warehouse or analytics platform. Report against that for incrementality decisions. Use platform metrics for in-flight optimization only. The deeper interpretation work belongs in `ads-performance-analytics` (forthcoming); this skill names the trap so you do not optimize against the wrong number. + +Per-platform reporting quirks in [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md). + +--- + +## Common failures + +Twelve patterns recur across paid media work. The short version. Detail in [`references/common-failures.md`](references/common-failures.md). + +- "We are scaling but CAC went up." Saturation on the primary audience. Expand the audience or diversify the channel mix. +- "Conversions look fine in the platform, terrible in revenue." Attribution mismatch plus customer quality, not just count. The platform is selecting low-LTV converters because they are easier to find. +- "We A/B tested and one wins, but only by 5%." Within margin of platform noise. Not a real signal. +- "We turned off the underperforming campaign and conversions dropped overall." View-through or assist conversions you were not counting. Test with hold-out, not flat off. +- "Frequency hit 8 last week." Refresh creative. Do not blame the audience. +- "We are trying to scale Meta to $100K per day from $20K per day." That is not scaling, that is a 5x jump. Expect efficiency drop; phase the increase. +- "We tried LinkedIn for our B2C product." Wrong channel for the offer. Not a LinkedIn problem. +- "tROAS will not deliver." You set it too aggressive. Loosen the target or switch strategy. +- "We saw a click-through bump after the Super Bowl ad." That is brand effect on existing demand, not paid attribution. Read it as a brand signal. +- "Search Impression Share dropped." Either competition increased or budget is constrained. Check both before tuning bids. +- "PMax is hard to optimize." Yes. Treat PMax as a tested channel with constrained levers, not a place to fine-tune at the keyword level. +- "Lookalike performance dropped after we expanded to 5%." Wider lookalikes are looser; the floor is lower. Tighten back to 1 to 2% if CAC is the constraint. + +--- + +## The framework: 11 considerations for sustainable paid media + +When designing or auditing paid media, walk these 11 considerations. Skipping any of them is how teams burn budget at scale. + +1. **Hypothesis.** Audience, offer, channel, outcome metric, magnitude. Pre-commit the falsification rule. +2. **Channel fit.** Intent matches offer. Search for capture, Meta and TikTok for creation, LinkedIn for B2B precision. +3. **Budget shape.** Brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. +4. **Audience strategy.** Prospecting, retargeting, exclusion. Treated as separate strategies. +5. **Bid strategy.** Manual, max conversions, tCPA, tROAS, max conversion value. Matched to data state. +6. **Campaign type.** Right type for the platform and the goal. +7. **What not to spend on.** Branded beyond defensive, untargeted display, wrong geos, off-hours, low-converting devices, never-convert audiences, tired creative. +8. **Creative testing.** Within campaign and across campaign, plus refresh cadence. +9. **Frequency capping.** Explicit caps and creative rotation. +10. **Attribution reality.** Single source of truth, platform metrics for in-flight only. +11. **Decision rule.** Pre-committed scale up, hold, or pull back at known thresholds. + +The output of the framework is one of three answers. Scale (the hypothesis is confirmed at the magnitude needed to justify more spend). Hold (results are at the falsification line; gather more data before committing). Kill (the hypothesis is wrong or the campaign is no longer pulling its weight). + +--- + +## Reference files + +- [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md) - Context-to-channel matrix with worked examples for the most common business contexts. +- [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md) - Typical splits and pacing patterns: growth-mode, steady-state, brand-heavy, performance-heavy. +- [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md) - Prospecting, retargeting, exclusion templates plus cross-platform reconciliation. +- [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md) - Each strategy's fit, common mistakes, and migration paths as data accumulates. +- [`references/campaign-type-reference.md`](references/campaign-type-reference.md) - Per-platform campaign type guide with pitfalls. +- [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md) - Platform reporting quirks, attribution differences, and the single-source-of-truth pattern. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, and prevention. + +--- + +## Closing: when in doubt, kill the campaign + +Most paid media decisions reduce to scale, hold, or kill. When the analysis is genuinely ambiguous, default to kill. + +The cost of a campaign that is not clearly working is real money flowing out the door every day. The cost of killing a marginal campaign is mostly just the inconvenience of restarting it later. Asymmetric risk. Default to kill. + +The follow-on rule is symmetric. When the hypothesis is clearly confirmed at the magnitude that matters, scale aggressively. The cost of slow-rolling a working campaign is opportunity cost; competitors compound on the same demand pool. Default to scale once the data justifies it. + +Marginal results are the trap. They invite more analysis, more meetings, more "let us give it another two weeks." Two weeks of marginal CAC is two weeks of lost money. Pre-commit the decision rule and execute it. diff --git a/skills/paid-media-strategy/references/ads-platform-comparison.md b/skills/paid-media-strategy/references/ads-platform-comparison.md new file mode 100644 index 0000000..3a181f8 --- /dev/null +++ b/skills/paid-media-strategy/references/ads-platform-comparison.md @@ -0,0 +1,106 @@ +# Ads platform comparison + +Per-platform reporting quirks, attribution differences, and the single-source-of-truth pattern. + +The platforms do not agree on what counts as a conversion or how long a click should attribute. Reading the platform's reported numbers as truth is the most expensive mistake in paid media. + +--- + +## Google Ads + +**Default attribution model.** Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on the platform's machine learning. Single touch attribution (last-click) is available but no longer the default. + +**Conversion windows.** Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA reports by default, which produces the typical 1.3 to 1.5x conversion overcount versus GA. + +**Quirks to know.** +- DDA gives partial credit to keywords that touched the path even if the user did not click. The reported conversion volume under DDA is higher than under last-click. +- Smart Bidding optimizes against the DDA-reported conversions, not GA-reported. Optimizing for one number while measuring against another produces drift. +- View-through attribution on Display and Video is opt-in; default is off. + +**Reading the numbers.** Compare Google Ads conversions against GA's "Google Ads" channel rather than against total GA conversions. The gap between the two is the attribution-model gap; treat with awareness. + +--- + +## Meta (Facebook + Instagram) + +**Default attribution.** 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +**Conversion windows.** 7-day click is the standard. Wider windows are more generous to Meta; narrower windows are more conservative. + +**iOS 14.5+ impact.** App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated based on aggregated behavior) and Conversions API (server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +**Quirks to know.** +- View-through attribution counts impressions even if the user did not click. Often half the reported conversions are view-through. Treat with skepticism for direct response. +- Modeled conversions are a meaningful share of iOS-reported conversions in 2025-2026. They are statistically estimated, not directly observed; do not trust them with the precision you would trust click-based conversions. +- Conversions API (CAPI) sends server-side events that complement pixel events. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. + +**Reading the numbers.** Disaggregate by attribution window in the Ads Manager (1-day click, 7-day click, 1-day view, 7-day view). The 1-day click number is the most conservative and the closest to incremental. + +--- + +## LinkedIn + +**Default attribution.** 30-day click and 7-day view-through. + +**Conversion windows.** Longer than B2C platforms because B2B buying cycles are longer. The 30-day click window matches the typical B2B consideration cycle for many categories. + +**Quirks to know.** +- LinkedIn's reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair with self-reported attribution surveys for B2B. +- Lead Gen Forms count form submissions as conversions; downstream lead qualification is on you to track. +- Demographic insights (job title, seniority, company size, industry) are unique to LinkedIn and uniquely valuable for B2B audience refinement. + +**Reading the numbers.** Lead Gen conversions are easy to overcount because form friction is low; some leads are accidental. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. + +--- + +## TikTok + +**Default attribution.** 7-day click and 1-day view-through (similar to Meta). + +**Conversion windows.** Adjustable. TikTok also supports a "video view" event that is unique to the platform. + +**Quirks to know.** +- Video-completion-based attribution: TikTok counts conversions even when the user did not click but watched the full video. This is real signal for awareness; it inflates direct-response numbers. +- iOS impact similar to Meta but less mature in the modeling. +- Spark Ads attribution is shared between paid and organic. The same view that drove a conversion shows up in both surfaces; be careful not to double-count when reconciling. + +**Reading the numbers.** Click-based conversions are the most reliable. Video-view-based conversions are real signal but should be reported separately. + +--- + +## Cross-platform interference + +Two platforms claiming the same conversion is the single most common attribution mistake. + +**The classic case.** A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). GA might attribute it to organic if the brand search was not paid. Three different views of one conversion. + +**The defense.** A single source of truth in your warehouse or analytics platform. Multi-touch attribution at the warehouse level distributes credit fairly. Marketing-mix modeling (MMM) at the budget-allocation level cuts through the platform-self-attribution bias. + +--- + +## Single-source-of-truth pattern + +Three layers, each serving a different decision. + +**Layer 1: platform metrics.** Use for in-flight optimization only. Ad set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +**Layer 2: warehouse multi-touch attribution.** Use for cross-platform comparison. Each conversion gets attributed across all platforms that touched the path. Common patterns: last-click, first-click, linear, position-based, time-decay, data-driven. Pick one and standardize across the team. + +**Layer 3: marketing-mix modeling (MMM).** Use for budget allocation across channels. MMM treats spend as an input and revenue as an output, modeling the contribution of each channel net of the others. The strongest defense against platform-self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## What the numbers mean in practice + +A typical mid-stage account has the following attribution gap pattern: + +- Google Ads reports: 1.3 to 1.5x what GA reports for "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA reports for "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform-self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/skills/paid-media-strategy/references/audience-segmentation-patterns.md b/skills/paid-media-strategy/references/audience-segmentation-patterns.md new file mode 100644 index 0000000..9cedf2a --- /dev/null +++ b/skills/paid-media-strategy/references/audience-segmentation-patterns.md @@ -0,0 +1,87 @@ +# Audience segmentation patterns + +Three audience types treated as separate strategies: prospecting, retargeting, exclusion. Plus cross-platform reconciliation patterns and the most common anti-patterns. + +--- + +## Prospecting + +New people who have not engaged with your brand. The largest budget share for growth-mode brands. + +**Lookalike audiences (Meta, TikTok).** Seed from a high-quality source (top 10% LTV customers, paying customers from the last 90 days, repeat purchasers) and ask the platform for similar users. 1 to 2% lookalikes are tightest and convert best at lower volumes; 5 to 10% lookalikes are looser and scale to volume but convert at lower rates. Start narrow, expand only if the floor holds. + +**In-market audiences (Google).** Google's behavioral signals identify users actively researching a category. Pair with category-relevant keywords for capture, or use as broad targeting on Display, Video, and PMax. + +**Interest stacks (Meta).** Stack multiple interest groups within an ad set. The stack approach lets the algorithm find the overlap. Single interests are usually too narrow; flat lists of 30 interests are too broad. Aim for 5 to 10 related interests. + +**Custom intent or affinity (Google).** Build audiences from URL lists or keyword lists. Useful for niche categories where in-market is not a clean fit. + +**Account lists (LinkedIn).** Upload a target account list and target by company. Pair with job-title or seniority filters to narrow further. The strongest pattern for ABM-style B2B paid. + +The prospecting principle. Start with one well-defined audience that matches your hypothesis. Prove CAC. Then expand. Running five prospecting audiences in parallel before any one is proven is the most expensive way to learn nothing. + +--- + +## Retargeting + +People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC if executed correctly. + +**Window splits.** Different windows have different conversion intents. Run three retargeting tiers with different creative. + +| Window | Audience intent | Creative | +|---|---|---| +| 0 to 7 days | Hot. Recent visitors. | Direct conversion offer. Reinforce value prop. | +| 8 to 30 days | Warm. Considered but did not convert. | Address objections. Social proof. Comparison content. | +| 31 to 90 days | Cool. Long consideration cycle or churned interest. | Reactivate with new offers, new content, or value updates. | + +**Cart abandoner specific.** If e-commerce, cart abandonment is its own retargeting tier. Window: 0 to 7 days. Creative: cart contents reminder, often with a small incentive (free shipping, 10% off). CTR and CAC are usually the strongest of any retargeting segment. + +**Page-specific retargeting.** Visitors to high-intent pages (pricing, demo request, product detail) are warmer than homepage visitors. Run page-specific retargeting at higher bids. + +The retargeting trap. Bidding too aggressively trains the platform to charge a premium for users who would have converted anyway. Cap retargeting CPM and CPC; the high CTR and conversion rate produce strong results without aggressive bids. + +--- + +## Exclusion + +The audiences you do not want paying for clicks from. Saves spend and keeps frequency low. + +**Current customers.** Users with active subscriptions, recent purchases, or active accounts. Exclude from prospecting and most retargeting. Exception: lapsed-cart-from-paying-customer retargeting, which can lift add-to-cart-to-purchase rates. + +**Recent converters.** Users who converted in the last 30 to 90 days. Exclude from prospecting. The platform will keep showing them ads otherwise, which produces frequency fatigue and zero new revenue. + +**Failed-conversion audiences.** Users who clicked repeatedly across a 60 to 90 day window without converting. Build an exclusion list from this segment. They have signaled they are not converting from paid; stop paying to show them ads. + +**Employee lists.** Upload employee email lists and exclude from all paid traffic. Employees clicking on company ads inflate spend and pollute attribution. + +**Cross-platform exclusion.** When running both Meta and Google, exclude Meta retargeting from Google retargeting (and vice versa). Two platforms hitting the same user with the same offer produces frequency fatigue and double-billing. + +--- + +## Cross-platform audience reconciliation + +When running multiple platforms, audience definitions should align so attribution comparisons are meaningful. + +**The seed list problem.** If Meta sees a customer file and Google sees a different customer file, the lookalike sources differ. Reconcile by uploading the same customer list to both, segmented identically (top 10% LTV, last 90 days, etc.). + +**The retargeting overlap problem.** A user who visited the site appears in both Meta retargeting and Google retargeting. Both platforms claim the conversion. Reconcile by running one retargeting platform at a time, or by setting platform-specific retargeting budgets that match the actual incremental contribution. + +**The exclusion problem.** A user who converts on Meta should be excluded from Google paid prospecting (and vice versa). Without cross-platform exclusion, you pay to advertise the same offer to the same user twice. Pipe conversions to a unified audience layer (CDP, warehouse, or audience-sync tool like Synter or Hightouch) and push exclusions back to each platform. + +--- + +## Anti-patterns + +Common mistakes that recur across accounts. + +**Prospecting too narrow.** Audience size below the platform's optimization minimum (Meta: roughly 1M users; Google: roughly 100K). The platform cannot optimize against signal that thin. Expand the audience until it has at least 1 to 5 million reachable users (Meta) or in-market scale (Google). + +**Retargeting too aggressive.** Bidding above the value of the incremental conversion. Half the retargeting "conversions" would have happened anyway from organic; if you bid for them at full attribution, you overpay. + +**No exclusions.** The most common audit finding. Current customers, recent converters, and employees all clicking on paid ads. + +**Lookalike from the wrong source.** Building a 5% lookalike from "all customers" (including low-LTV churners). The platform returns users similar to the average, not similar to your best. Always seed from top-LTV or paid-and-retained customers. + +**Too many ad sets per campaign.** Splitting one campaign into 10 ad sets fractures the data the platform needs to optimize. Consolidate into 2 to 4 ad sets per campaign with audience size sufficient for each to learn. + +**Audience overlap across ad sets.** Two ad sets in the same campaign targeting similar users compete with each other and inflate CPC. Audit overlap with the platform's overlap tool; consolidate ad sets that overlap above 30%. diff --git a/skills/paid-media-strategy/references/bid-strategy-reference.md b/skills/paid-media-strategy/references/bid-strategy-reference.md new file mode 100644 index 0000000..f2a4630 --- /dev/null +++ b/skills/paid-media-strategy/references/bid-strategy-reference.md @@ -0,0 +1,104 @@ +# Bid strategy reference + +Each major bid strategy with definition, fit criteria, common mistakes, and the migration path as data accumulates. + +The decision shape. Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. Pick the strategy that fits the current data state, run it long enough to gather signal, then promote. + +--- + +## Manual CPC or CPM + +**Definition.** Set a max cost per click or cost per thousand impressions. The platform charges no more than the cap. + +**When to use.** Diagnostics. Very early campaigns with no data history. Niche audiences where the platform's machine learning would over-broaden. Branded keyword campaigns where you want explicit cost control. + +**When not to use.** Most production campaigns at scale. Manual scales slowly because every adjustment requires a human decision; automated strategies optimize across thousands of micro-decisions per hour. + +**Common mistakes.** Setting CPC caps below the auction floor (the campaign delivers nothing). Switching from manual to automated too early before there is enough data for the automated strategy to optimize against. + +--- + +## Maximize Conversions + +**Definition.** Platform optimizes for conversion volume within the budget. The platform decides CPC. + +**When to use.** Early-stage campaigns where you want as many conversions as possible regardless of unit cost. Good for gathering the conversion data needed to graduate to tCPA later. Good for awareness or list-building campaigns where volume matters more than per-unit cost. + +**When not to use.** Once CAC is the binding constraint. Maximize Conversions does not respect CAC; it just optimizes for count. + +**Common mistakes.** Running Maximize Conversions for too long when CAC is creeping up. Set a cadence to evaluate the migration to tCPA once you have 30+ conversions in the recent window. + +--- + +## Target CPA (tCPA) + +**Definition.** Set a max CPA. Platform delivers conversions within the target. + +**When to use.** Once you have 30+ conversions in the recent 30 day window for the platform to optimize against. Use when CPA is the constraint and you have enough data for the platform's machine learning to converge. + +**When not to use.** Before you have enough conversion data. The platform cannot optimize tCPA without enough signal; it will either underdeliver or learn against noise. + +**Common mistakes.** Setting tCPA below the prior 30-day actual CPA (platform throttles delivery to almost zero). Setting tCPA too aggressive in a thin-data campaign (same effect; throttled delivery and no learning). Switching tCPA targets every week (each change resets the learning phase). Set the target reasonably (within 15% of recent actual) and let it run. + +--- + +## Target ROAS (tROAS) + +**Definition.** Set a min ROAS. Platform delivers conversions above the target. + +**When to use.** When revenue per conversion varies substantially (e-commerce with mixed AOV, marketplaces with mixed take rates). Once you have 50+ conversions and conversion-value tracking is wired in. + +**When not to use.** Before conversion-value tracking is reliable. Without conversion values, tROAS has nothing to optimize against and falls back to behavior similar to Maximize Conversions but with throttled delivery. + +**Common mistakes.** Setting tROAS too aggressively (platform delivers almost nothing). Not feeding accurate conversion values (the platform optimizes for the wrong number). Switching tROAS targets too often. + +--- + +## Maximum Conversion Value + +**Definition.** Like Maximize Conversions, but the platform optimizes for total conversion value rather than count. + +**When to use.** Same conditions as tROAS, but without a fixed target. Good when you want to maximize revenue within budget without specifying the per-unit ROAS floor. + +**When not to use.** Without conversion-value tracking. Without volume confidence; same as tROAS, the platform needs enough conversions to optimize against value. + +**Common mistakes.** Running without conversion values configured (the platform falls back to count). Treating it identically to Maximize Conversions; the value optimization changes which conversions the platform finds. + +--- + +## Enhanced CPC + +**Definition.** Manual CPC with platform adjustments based on conversion likelihood. + +**When to use.** Rarely. The hybrid muddies the signal. If you want manual control, run pure manual CPC. If you want automation, graduate to Maximize Conversions or tCPA. + +**When not to use.** Most situations. The hybrid is a transitional state from a previous platform default; modern campaigns should pick a clear strategy. + +**Common mistakes.** Treating Enhanced CPC as the safe default. It is neither full control nor full automation; the worst of both. + +--- + +## The migration path + +The progression for a new campaign as data accumulates. + +| Data state | Strategy | Rationale | +|---|---|---| +| Day 1 to ~30 conversions | Manual CPC or Maximize Conversions | Gather data. Platform machine learning has nothing to optimize against yet. | +| 30 to 100 conversions | Target CPA | Platform has enough signal to optimize against a CPA target. Set within 15% of recent actual. | +| 100+ conversions, value tracking on | Target ROAS or Max Conversion Value | Optimize for revenue or ROAS rather than count. | +| Mature campaign at scale | Whichever produces best CAC + ROAS | Stay there. Switching strategies on a mature campaign restarts the learning phase. | + +The migration cadence. Evaluate the migration after every 30 days or every 50% conversion volume increase, whichever comes first. Do not switch every week; the learning phase reset cost is real. + +--- + +## When to NOT switch strategy + +Three signals that suggest staying on the current strategy even when something else looks better. + +1. **Recent change.** If you switched strategy in the last 14 days, give it more time. The learning phase needs at least 2 weeks of consistent volume to converge. +2. **Volatile conversion volume.** If conversion volume is bouncing 50%+ week-over-week, the platform's optimization signal is noisy. Stabilize volume before switching. +3. **Active creative test.** If you are mid-test on creative or audience, do not also change bid strategy. One variable at a time. The bid strategy change muddies the creative test signal. + +The rule. Switch strategy when one variable is stable and the data state has clearly progressed. Avoid stacking changes; you cannot tell which change drove the result. diff --git a/skills/paid-media-strategy/references/budget-allocation-templates.md b/skills/paid-media-strategy/references/budget-allocation-templates.md new file mode 100644 index 0000000..9ff0017 --- /dev/null +++ b/skills/paid-media-strategy/references/budget-allocation-templates.md @@ -0,0 +1,107 @@ +# Budget allocation templates + +Four split patterns plus pacing guidance. Pick the template closest to your situation and adapt. + +The splits operate at the same time: brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. + +--- + +## Template 1: Growth-mode allocation + +For brands actively scaling with a working unit economic model. + +| Bucket | Share | Notes | +|---|---|---| +| Prospecting | 70% | New audience reach. Largest share because growth comes from new demand. | +| Retargeting | 20% | Engaged-but-not-converted users. Small audience, high CTR, low CAC. | +| Test | 10% | Systematic tests of new audiences, channels, or creative concepts. | + +Plus brand-vs-performance: 25% brand, 75% performance for B2C. 50-50 for B2B with longer cycles. + +Plus channel: 60-70% to one primary channel that has proven its CAC, 25% to a secondary, 5-15% to scale-out experiments. + +--- + +## Template 2: Steady-state allocation + +For brands holding scale rather than aggressively pushing it. + +| Bucket | Share | Notes | +|---|---|---| +| Prospecting | 50% | Lower share because steady-state needs less new demand. | +| Retargeting | 30% | Higher share because the existing pipeline is the main flow. | +| Test | 20% | Higher share than growth-mode; steady-state is when systematic testing pays off. | + +Plus brand-vs-performance: 40% brand, 60% performance. The brand share is higher than growth-mode because steady-state is about defending position. + +--- + +## Template 3: Brand-heavy allocation + +For categories where brand investment compounds (premium consumer, B2B with long consideration, regulated industries). + +| Bucket | Share | Notes | +|---|---|---| +| Brand | 60% | Awareness, reach, video at scale. Long-term demand pipeline. | +| Performance | 40% | Search and retargeting on the demand the brand creates. | + +Within performance, 60% prospecting and 40% retargeting is typical. Test budget comes out of the brand share. + +--- + +## Template 4: Performance-heavy allocation + +For DTC and direct-response B2C where the unit economics are tight and brand effects are slow to compound. + +| Bucket | Share | Notes | +|---|---|---| +| Brand | 20% | Minimum viable awareness investment. Mostly content and organic. | +| Performance | 80% | Direct-response paid; CAC is the binding metric. | + +Within performance, growth-mode splits apply: 70% prospecting, 20% retargeting, 10% test. + +--- + +## Pacing patterns + +Budgets that run flat through the month miss the demand peaks and overspend during the troughs. Three pacing patterns to layer onto the daily template. + +**Front-load testing weeks.** When launching a new creative concept or a new audience, front-load 60% of the test budget in the first 7 to 10 days. The platform learning phase needs concentrated signal; spreading too thin means slower convergence. + +**Back-load seasonality.** For categories with a seasonal peak (holiday, end-of-quarter, category-specific moments), shift 30 to 50% of monthly budget into the peak two-week window. Flat budgets through Q4 leave money on the table. + +**Front-load for launch.** For new campaigns with no historical data, front-load creative testing in week one. Accept lower efficiency in week one in exchange for picking the winning creative quickly. By week three the winning concept should be running at scale. + +**Steady for evergreen.** For mature campaigns hitting consistent CAC at scale, run flat daily. The platform's learning is stable; introducing pacing variance creates noise that reduces optimization quality. + +--- + +## Daily vs lifetime budgets + +**Daily budget.** Use for ongoing campaigns where you want a stable spend floor. The platform charges up to your daily cap regardless of opportunity, which is what you want for predictable production work. + +**Lifetime budget.** Use for finite tests where the platform should pace itself across a defined window. Lifetime budgets prevent runaway spend during testing; the platform optimizes pacing so the test ends on the planned date with the planned spend. + +Mistakes. Using daily for tests (the test runs forever or stops abruptly when budget is paused). Using lifetime for evergreen campaigns (the platform front-loads or back-loads in ways you do not want). + +--- + +## Channel split mistakes + +The most common channel-budget mistake is the equal split. Spreading $100K across four channels at $25K each produces four underperforming campaigns; one campaign at $80K plus three at $7K each produces one strong learning signal and three quick reads on whether the others are worth scaling. + +The principle. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the temptation to be balanced. Balanced budgets across unproven channels is the most expensive way to learn nothing. + +The exception. After two channels are proven independently, splitting toward equal is fine because each channel has its own efficient scale. Before that point, concentrate. + +--- + +## Reallocation triggers + +Three signals that the current split needs to shift. + +1. **Primary channel CAC drifted up by 25% over two weeks.** The audience is saturating or competition increased. Shift some budget to the secondary channel and drop the primary's daily. +2. **Test budget produced a new winner.** A test channel or audience is hitting CAC equal to or better than baseline. Promote it to baseline at 15% of total budget; the previous baseline holds 55 to 60%. +3. **Frequency exceeded threshold across the prospecting audience.** The audience saw the creative more than the cap. Either rotate creative or expand the audience; if both are constrained, pull back budget. + +Reallocation cadence: monthly review minimum. Weekly during high-spend periods or active scale-up. diff --git a/skills/paid-media-strategy/references/campaign-type-reference.md b/skills/paid-media-strategy/references/campaign-type-reference.md new file mode 100644 index 0000000..2d3e007 --- /dev/null +++ b/skills/paid-media-strategy/references/campaign-type-reference.md @@ -0,0 +1,197 @@ +# Campaign type reference + +Per-platform campaign type guide. For each campaign type: what it is, when it fits, common pitfalls. + +--- + +## Google Ads + +### Search + +**What it is.** Text ads on Google search results pages, triggered by keyword auctions. + +**When to use.** Direct demand capture. Users searching for category, product, or competitor terms. + +**Pitfalls.** Branded over-spend (cannibalizing free traffic). Broad match on weak keywords (drives garbage clicks). Missing negative keyword lists (paying for irrelevant search terms). Audit search-term reports monthly and add negatives. + +### Shopping + +**What it is.** Product listing ads driven by your Google Merchant Center feed. + +**When to use.** E-commerce with a structured catalog. Comparison-shopping intent. + +**Pitfalls.** Bad feed quality (missing GTINs, weak titles, wrong categories). The feed is the bottleneck; clean it before scaling spend. + +### Performance Max (PMax) + +**What it is.** Automated multi-channel campaign that runs across Search, Shopping, Display, YouTube, Discover, and Gmail. The platform decides placement. + +**When to use.** E-commerce with a strong feed. When you want Google's automation to do the placement work. As a complement to Search, not a replacement. + +**Pitfalls.** Black box optimization makes manual tuning hard. Cannibalizes branded Search traffic; exclude branded queries via account-level negatives. Asset group quality drives results; weak creative produces weak results regardless of platform automation. + +### Display + +**What it is.** Banner and image ads on the Google Display Network (millions of partner sites). + +**When to use.** Retargeting (small audiences, defined intent). Specific contextual targeting where you trust the placement list. + +**Pitfalls.** Display without targeting drives garbage traffic. Default placements include low-quality sites that hurt brand. Use only for retargeting unless you have explicit placement controls. + +### Video (YouTube) + +**What it is.** Video ads on YouTube. Various formats (skippable, non-skippable, bumper, in-feed). + +**When to use.** Awareness at scale. B2C consideration. Underrated for B2B SaaS in some categories where buyer research includes long-form video. + +**Pitfalls.** Direct-response on Video rarely works as well as Meta video. Use for awareness or as an upper-funnel layer. Skippable ads with strong first-5-seconds work; non-skippable annoys. + +### Demand Gen + +**What it is.** Successor to Discovery ads. Visual ads across Discover, Gmail, YouTube Shorts, and YouTube in-feed. + +**When to use.** Visual-first products targeting users in discovery mode (not search mode). + +**Pitfalls.** Newer campaign type with less optimization history; results are more volatile than Search or Shopping. Treat as a tested channel. + +### Discovery + +**What it is.** Visual ads across Google's discovery surfaces. Being merged with Demand Gen. + +**When to use.** Largely deprecated in favor of Demand Gen. Migrate existing Discovery campaigns. + +### App + +**What it is.** Universal App Campaigns for app installs and engagement. + +**When to use.** App promotion. Mostly automated; you provide creative and budget. + +**Pitfalls.** Hard to optimize beyond budget and creative inputs. Track post-install events (subscription, retention) not just installs. + +--- + +## Meta (Facebook + Instagram) + +### Sales + +**What it is.** Campaigns optimized for conversions. The default for direct response. + +**When to use.** E-commerce, subscriptions, lead capture with measurable conversion events. + +**Pitfalls.** Wrong conversion event optimization (optimizing for "Add to Cart" when "Purchase" is what matters). Inadequate pixel setup (the conversion data feeding the algorithm is incomplete). + +### Leads + +**What it is.** Campaigns with native lead forms inside Facebook or Instagram. + +**When to use.** B2B with mid-funnel offers (whitepaper, demo request, newsletter signup). Native forms have lower friction than off-platform forms. + +**Pitfalls.** Lead quality is lower than off-platform forms (less friction, more accidental submissions). Build a CRM enrichment step to filter low-quality leads before passing to sales. + +### Engagement + +**What it is.** Optimizes for likes, comments, shares, page follows. + +**When to use.** Building an organic audience. Almost never as a primary objective for performance work. + +**Pitfalls.** Engagement does not predict conversion. Vanity metrics if used as a primary objective for revenue work. + +### Awareness + +**What it is.** Optimizes for reach and frequency. Brand-style budget. + +**When to use.** Brand at scale. New product launches. Competitor-conquest moments. + +**Pitfalls.** No conversion signal feeding the algorithm. Cannot evaluate against CAC. Use as a brand layer, not a performance layer. + +### Traffic + +**What it is.** Optimizes for clicks (link clicks or landing page views). + +**When to use.** Driving traffic to long-form content, blog posts, awareness pages where the user journey is multi-touch. + +**Pitfalls.** Click-optimized traffic does not predict conversion. The platform finds users likely to click, not users likely to convert. Only use for top-funnel content distribution. + +### App Promotion + +**What it is.** App install campaigns within Meta. + +**When to use.** App promotion specifically. Compare against Google App Campaigns. + +**Pitfalls.** iOS 14.5+ tracking restrictions impact attribution; modeled conversions fill the gap imperfectly. + +--- + +## LinkedIn + +### Sponsored Content + +**What it is.** Sponsored posts in the LinkedIn feed. + +**When to use.** B2B awareness and consideration. Native to the LinkedIn experience. + +**Pitfalls.** High floor (CPM 5 to 10x consumer platforms). Justify with B2B LTV; otherwise unprofitable. + +### Message Ads + +**What it is.** Direct messages delivered via LinkedIn InMail. + +**When to use.** High-intent B2B nudges where the message reads as a personal note. + +**Pitfalls.** Stigma in many segments. Treated as spam if the message reads generic. Personalize aggressively or skip. + +### Conversation Ads + +**What it is.** Multi-step interactive messages with branching CTAs. + +**When to use.** Mid-funnel B2B where multiple value propositions need to be tested in one experience. + +**Pitfalls.** Setup complexity. Many teams underuse the branching capability and run them as glorified Message Ads. + +### Lead Gen Forms + +**What it is.** Native lead forms pre-filled from LinkedIn profile data. + +**When to use.** Highest converting LinkedIn objective. Use whenever the offer is a lead capture (demo, whitepaper, content offer). + +**Pitfalls.** Lead quality varies by form length. Shorter forms get more leads; longer forms filter to higher quality. Iterate. + +### Format types + +Single image, carousel, video. Carousel often outperforms single image for product or feature explainers. Video performs best when shot LinkedIn-native with first-3-seconds hook and captions on by default. + +--- + +## TikTok + +### In-Feed + +**What it is.** Standard ads in the For You Page feed. + +**When to use.** Default TikTok format. Most direct-response and awareness work runs here. + +**Pitfalls.** Polished ad creative is rejected by the algorithm; native-feeling content wins. Iterate creative weekly to avoid fatigue. + +### TopView + +**What it is.** Premium first-impression placement when users open the app. + +**When to use.** Brand moments at scale. Product launches. + +**Pitfalls.** Expensive. Only justify with measurable brand lift or product launch impact. + +### Spark Ads + +**What it is.** Boost an existing organic post as an ad. Retains organic engagement and signal. + +**When to use.** Whenever you have organic posts performing. Spark Ads outperform pure paid creative because they retain the organic-feel signal. + +**Pitfalls.** Requires organic content to exist. If the brand has no organic presence, build one first. + +### Branded Hashtag Challenge + +**What it is.** Sponsored hashtag with branded content prompts. + +**When to use.** Major brand campaigns where user-generated participation matters. + +**Pitfalls.** Expensive. Hard to measure direct response. Best for brands with cultural-moment ambitions, not direct response. diff --git a/skills/paid-media-strategy/references/channel-decision-matrix.md b/skills/paid-media-strategy/references/channel-decision-matrix.md new file mode 100644 index 0000000..bf8ec6d --- /dev/null +++ b/skills/paid-media-strategy/references/channel-decision-matrix.md @@ -0,0 +1,56 @@ +# Channel decision matrix + +A context-to-channel map. The left column is the situation. The center columns are the recommended channels. The right column is reasoning and what NOT to start with. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. Use the remaining rows as cross-checks. + +--- + +## The matrix + +| Situation | Primary channel | Secondary channel | Reasoning and what to avoid early | +|---|---|---|---| +| Pre-PMF B2B SaaS | LinkedIn (precision) or Google Search (intent) | Content + organic; defer paid scale | Avoid Meta and TikTok early; the audience is not on those platforms. Avoid PMax; you do not have the data state for it. | +| High-AOV B2B (>$5K LTV) | LinkedIn Sponsored Content + Lead Gen Forms | Google Search on category and intent terms | LinkedIn floor is high but justified at this LTV. Avoid TikTok, Reddit, and broad Meta until the LinkedIn motion is repeating. | +| Low-AOV consumer product (<$50 LTV) | Meta (Sales objective) | TikTok (Spark Ads if organic exists) | Avoid LinkedIn (floor too high). Avoid Search unless category-defining query volume exists. Watch payback period; low LTV with paid CAC is razor-thin. | +| DTC with strong visual brand | Meta (Sales + Reels) | TikTok In-Feed and Spark Ads | Avoid LinkedIn. Avoid Display network. Visual-first creative is the moat; double down on the platforms that surface it. | +| Local services | Google Search + Local Service Ads | Meta with geo radius targeting | Avoid TikTok and LinkedIn (wrong intent). Pause off-hours. Geo-radius is the most important targeting lever. | +| Enterprise SaaS (>$50K ACV) | LinkedIn (job-title precision) | Account-Based Marketing platforms + Google Search on category terms | Avoid Meta and TikTok. Avoid broad Display. Pair with ABM on a target account list; audiences are too small for Meta lookalikes to work. | +| E-commerce with catalog | Google Performance Max + Shopping | Meta (Catalog Sales) | Avoid Search-only spend; PMax includes Search and adds catalog placements. Avoid LinkedIn. Feed quality is the bottleneck; fix the feed before spending on PMax. | +| Subscription consumer | Meta (Sales objective with subscriber LTV) | Google Search on intent + brand terms | Avoid LinkedIn. Watch retention; CAC paid back over multiple months means the unit economics window matters more than first-month CAC. | +| Marketplace (two-sided) | Channel-by-side: Meta for consumer side, LinkedIn or Search for supplier side | Reddit niche communities for the supplier side | Run two separate strategies, not one unified plan. The two sides have different intent and need different channels. | +| Pre-launch waitlist | Meta (Engagement or Lead) | Reddit and TikTok organic + light paid | Avoid Search; no one is searching for an unlaunched product. Avoid LinkedIn unless B2B. Cheap CPL but low intent; expect waitlist conversion under 20%. | + +--- + +## Worked examples + +### Example 1: Series B B2B SaaS, $25K ACV, North American sales motion + +The team has a working sales motion and is scaling outbound. They want paid media to add inbound demand without killing CAC. + +**Recommendation.** LinkedIn Sponsored Content as the primary, plus Google Search on category and competitor terms as secondary. Run Lead Gen Forms within LinkedIn to capture demos. Avoid Meta and TikTok early; the buying committee is on LinkedIn and at the office. Budget split: 60% LinkedIn, 30% Search, 10% test (Reddit B2B subreddits, niche newsletters). Watch CAC against the $25K ACV and a 3:1 LTV-to-CAC target. + +### Example 2: DTC adaptogenic soda, $24 AOV, US-only + +The brand has strong visual identity and an organic TikTok presence with one viral post per month. They want to scale paid. + +**Recommendation.** Meta (Sales objective with Catalog) as the primary. TikTok Spark Ads on the existing organic posts as the secondary. Avoid LinkedIn entirely. Avoid Search unless brand search volume justifies defensive spend. Budget split: 60% Meta, 30% TikTok, 10% test (Pinterest for visual discovery). The viral organic posts are the asset; Spark Ads recycle them at scale. Watch payback period; $24 AOV with paid CAC is razor-thin. + +### Example 3: Local home services, three-state operating area + +The team operates plumbing services across three states. They want predictable lead flow. + +**Recommendation.** Google Search plus Local Service Ads as the primary. Meta with geo radius as the secondary for awareness in the operating area. Avoid LinkedIn and TikTok (wrong intent). Pause off-hours unless 24-hour service is a positioning angle. Budget split: 70% Search and LSAs, 20% Meta geo, 10% test (Nextdoor where available). The geo-radius lever is the most important; a 2% mistargeting rate compounds at scale. + +### Example 4: E-commerce, 2,000 SKU catalog, $80 AOV + +The brand has a working e-commerce operation and wants to scale paid media efficiently. + +**Recommendation.** Google Performance Max as the primary (it includes Search, Shopping, Display, YouTube, Discover all in one). Meta Catalog Sales as the secondary. Avoid LinkedIn. Avoid Search-only campaigns; PMax already includes Search. Feed quality is the bottleneck; clean the feed (titles, categories, attributes, GTINs) before spending on PMax. Budget split: 70% PMax, 25% Meta, 5% test. Audit the geo and device cuts inside PMax weekly until the algorithm stabilizes. + +### Example 5: Pre-PMF B2B SaaS, $300K ARR, founders selling + +The team is pre-PMF. The founders are still doing all sales. They want to test paid media without burning runway. + +**Recommendation.** Defer paid scale. Use small Search budget ($2K to $5K per month) on category terms to capture in-market intent. Use LinkedIn organic plus founder-led content as the primary growth motion until PMF is clearer. The signal you would get from paid spend at this stage is too noisy to act on; the budget is better spent on content and outbound. Revisit paid in 6 months if PMF signals firm up. diff --git a/skills/paid-media-strategy/references/common-failures.md b/skills/paid-media-strategy/references/common-failures.md new file mode 100644 index 0000000..c60f2a8 --- /dev/null +++ b/skills/paid-media-strategy/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across paid media accounts. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Scaling but CAC went up + +**Symptom.** You doubled budget on the primary audience. Conversion volume rose less than 2x. CAC drifted up by 20 to 40%. + +**Root cause.** Audience saturation on the primary segment. The platform finds the easiest converters first; pushing more spend into the same audience produces diminishing returns at higher cost. + +**Fix.** Either expand the audience (broader lookalike, additional interests, geo expansion) or diversify across channels. Do not keep pushing the same audience harder; the marginal CAC will keep climbing. + +**Prevention.** Project the saturation curve before scaling. If a 1.5x spend increase doubled CAC over the prior 90 days, expect another 1.5x to push CAC past your threshold. Plan the diversification before the saturation. + +--- + +## 2. Conversions look fine in the platform, terrible in revenue + +**Symptom.** Platform reports stable conversion volume and CAC. Revenue per conversion or LTV is dropping. + +**Root cause.** Attribution mismatch plus customer-quality drift. The platform optimizes for finding "any conversion." The optimizer drifts toward lower-quality converters because they are easier to find. + +**Fix.** Switch from conversion-count optimization to conversion-value optimization (Maximum Conversion Value or tROAS). Feed accurate conversion values into the platform. Tighten audiences toward higher-LTV proxies. + +**Prevention.** Track LTV cohorts per channel monthly. If channel-LTV diverges from blended LTV by more than 15%, investigate the cohort quality before defending the channel. + +--- + +## 3. A/B test winner by 5% + +**Symptom.** Two variations tested. One wins by 5%. The team wants to ship the winner. + +**Root cause.** 5% is within typical platform noise. Across-campaign tests have higher variance than statistical lift implies. + +**Fix.** Re-run the test with more volume. Or run it longer. Or accept that the difference is not meaningful and pick the one that is easier to maintain (cheaper to produce, easier to refresh). + +**Prevention.** Set the minimum detectable effect (MDE) before testing. If the test cannot detect anything below 10%, do not act on a 5% difference. + +--- + +## 4. Turned off underperformer, total conversions dropped + +**Symptom.** A campaign was reading as underperforming. Pause it. Total account conversions drop more than the campaign's reported conversions would suggest. + +**Root cause.** View-through or assist conversions you were not counting in the campaign's CAC. The campaign was contributing upper-funnel exposure that drove conversions on other campaigns. + +**Fix.** Restart the campaign with a held-out portion of the audience to measure incrementality. Compare the held-out cohort against the exposed cohort over 30 days. + +**Prevention.** Run hold-out tests, not flat off-ons. The flat-off causes a discontinuity that is hard to attribute back to the right campaign. + +--- + +## 5. Frequency hit 8 last week + +**Symptom.** Frequency report shows 8 impressions per user last week. CTR is dropping. + +**Root cause.** Creative fatigue. Audience has seen the creative too many times. + +**Fix.** Refresh creative. Rotate in 3 to 5 new variations. Cap frequency explicitly at 4 to 6 per week. + +**Prevention.** Set explicit frequency caps at campaign launch. Track frequency weekly. Refresh creative on a 30 to 60 day cadence at scale, weekly for high-frequency campaigns. + +--- + +## 6. Trying to scale Meta from $20K to $100K per day + +**Symptom.** Aggressive scale plan. Budget multiplier is 5x in one move. + +**Root cause.** That is not scaling. That is a 5x jump that will crash through the audience at the new spend level. Expect efficiency drop of 30 to 50% in the first 14 days. + +**Fix.** Phase the increase. 25% per week is a typical safe pace. Larger jumps should pair with audience expansion or new channels to absorb the spend. + +**Prevention.** Plan the scale curve before starting. 5x in a month is fine if it is 4 weekly 1.4x increases. 5x in a single move is not fine. + +--- + +## 7. LinkedIn for a B2C product + +**Symptom.** Tested LinkedIn for a $40 AOV consumer product. CAC came in at $200. + +**Root cause.** Wrong channel for the offer. LinkedIn's floor is set for B2B economics; B2C does not justify it. + +**Fix.** Stop. Move budget to Meta, TikTok, or Search. + +**Prevention.** Match channel to offer at the strategy stage. Use the channel decision matrix. Do not try platforms because "we should be on LinkedIn"; be on LinkedIn only when the math supports it. + +--- + +## 8. tROAS will not deliver + +**Symptom.** Set tROAS at 4.0. Platform delivers almost no impressions. + +**Root cause.** tROAS target is too aggressive relative to recent performance. The platform throttles delivery to almost zero rather than deliver below the floor. + +**Fix.** Loosen the target to 110 to 115% of the prior 30-day actual ROAS. Let the platform learn at the new target, then incrementally tighten. + +**Prevention.** Set tROAS based on actual recent performance, not aspirational targets. Aspirational targets shut off delivery; pragmatic targets keep volume flowing while improving efficiency. + +--- + +## 9. Search Impression Share dropped + +**Symptom.** Search Impression Share fell from 70% to 50% over two weeks. Conversions held but you are missing volume. + +**Root cause.** Either competition increased (someone else is bidding more aggressively) or budget is constrained (you ran out of daily budget at peak hours). + +**Fix.** Check both. Compare auction-insight reports for new entrants. Check the time-of-day spend distribution; if budget runs out at noon, raise the daily cap. + +**Prevention.** Track Impression Share weekly. Set alerts on 10%+ week-over-week drops. The signal is leading; conversion drops typically follow within 2 to 3 weeks. + +--- + +## 10. PMax is hard to optimize + +**Symptom.** Performance Max is running. CAC is fine. You want to push it harder but cannot find levers. + +**Root cause.** PMax is by design a black box. The platform manages placements, audiences, and creative weighting. The levers you have are budget, asset groups, and exclusions. + +**Fix.** Treat PMax as a tested channel with constrained levers. Optimize via asset group quality (better creative, more variants), audience signals (Customer Match, in-market lists), and exclusions (branded queries, low-value SKUs). + +**Prevention.** Set expectations at launch. PMax is not a place to fine-tune at the keyword level. It is a place to feed strong inputs and let the platform optimize. + +--- + +## 11. Lookalike performance dropped after expansion + +**Symptom.** Expanded the lookalike from 1% to 5% to add volume. CAC drifted up. + +**Root cause.** Wider lookalikes are looser; the floor is lower. The expansion brought in users less similar to the seed. + +**Fix.** Tighten back to 1 to 2% if CAC is the constraint. Or split into two ad sets: the 1% as the workhorse and the 1 to 5% as a separate scale-out audience with its own budget. + +**Prevention.** When you need volume, expand horizontally (add a new audience type) rather than vertically (loosen the existing audience). The horizontal expansion preserves the working audience's CAC. + +--- + +## 12. Brand search lift after a Super Bowl-style ad + +**Symptom.** Brand search volume jumped after a brand campaign ran. Paid attribution did not credit it. + +**Root cause.** Brand effect on existing demand, surfaced in organic and branded paid search rather than the brand campaign's direct-attribution column. The platform's direct response metrics did not capture it. + +**Fix.** Track brand-search lift as a separate metric. Define a baseline brand-search rate before the campaign. Measure the lift during and after. + +**Prevention.** Plan brand campaigns with brand-search lift as a primary KPI, not direct response. Direct response measurement underrates brand campaigns; using it as the only success metric kills brand investment unfairly. + +--- + +## The pattern across all twelve + +Most paid media failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale CAC at the cost of LTV. Pause an underperformer at the cost of total volume. Expand the audience at the cost of the floor. Optimize one platform without checking incrementality. + +The fix at the meta level. Decide on the success metric (CAC, ROAS, LTV-adjusted) and the guardrails (volume, frequency, creative quality, customer-cohort quality) before scaling. Audit guardrails monthly. Pull back the moment a guardrail breaks, even if the success metric still looks fine. diff --git a/skills/performance-optimization/SKILL.md b/skills/performance-optimization/SKILL.md new file mode 100644 index 0000000..1bac7fb --- /dev/null +++ b/skills/performance-optimization/SKILL.md @@ -0,0 +1,274 @@ +--- +name: performance-optimization +description: "Diagnose and fix web performance issues including Core Web Vitals (LCP, INP, CLS), bundle size, asset optimization, render performance, and runtime efficiency. Use this skill whenever the user wants to improve page speed, fix Core Web Vitals, optimize assets, reduce bundle size, debug slow renders, or systematically improve a site's performance. Triggers on performance, page speed, Core Web Vitals, LCP, INP, CLS, FID, TTFB, bundle size, code splitting, image optimization, lazy loading, render blocking, slow page, performance audit, Lighthouse score. Also triggers when traffic or conversion is dropping due to perceived slowness." +category: development +catalog_summary: "Core Web Vitals, asset optimization, render performance" +display_order: 4 +--- + +# Performance Optimization + +Diagnose web performance issues and produce a remediation plan. Stack-agnostic. Anchored to Core Web Vitals and standard browser performance patterns. + +This skill goes deeper than the performance checks in `qa-testing` and `seo-technical`. Use this when performance itself is the goal. + +--- + +## When to use + +- Fixing Core Web Vitals (LCP, INP, CLS) +- Diagnosing slow page loads +- Reducing JavaScript bundle size +- Optimizing images, fonts, and other assets +- Fixing layout shift, render-blocking resources, jank +- Pre-launch performance verification +- Annual performance health check + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Technical SEO including indexing and crawling (use `seo-technical`) +- Code review for general bugs (use `code-review-web`) + +--- + +## Required inputs + +- The site or page under audit +- Specific performance complaints if any +- Target metrics (Core Web Vitals thresholds, Lighthouse score, custom) +- Browser dev tools access +- Performance monitoring data if available (Real User Monitoring, lab data) + +--- + +## The framework: Core Web Vitals + +Three metrics carry most of the weight for both user experience and SEO: + +### LCP (Largest Contentful Paint) + +**What it measures:** Time until the largest visible content element finishes rendering. + +**Targets:** +- Good: under 2.5 seconds +- Needs improvement: 2.5 to 4.0 seconds +- Poor: over 4.0 seconds + +**Common causes of poor LCP:** +- Slow server response time (TTFB over 800ms) +- Render-blocking JavaScript or CSS +- Large unoptimized images for the LCP element +- Late-loading fonts that delay text render +- Client-side rendering of the LCP element + +**Common fixes:** +- Server-render the LCP element (no client-side render) +- Optimize the LCP image (right format, right size, preloaded) +- Reduce render-blocking resources (defer non-critical CSS and JS) +- Use modern image formats (WebP, AVIF) +- Specify image dimensions to skip layout pass + +### INP (Interaction to Next Paint) + +**What it measures:** Responsiveness to user interactions. Replaces FID as the standard interactivity metric. + +**Targets:** +- Good: under 200ms +- Needs improvement: 200 to 500ms +- Poor: over 500ms + +**Common causes of poor INP:** +- Long-running JavaScript blocking the main thread +- Heavy event handlers +- Excessive React/framework re-renders +- Synchronous operations in event handlers +- Large DOM with expensive layouts + +**Common fixes:** +- Break long tasks into chunks (`scheduler.yield()` or `setTimeout`) +- Memoize expensive computations +- Debounce or throttle high-frequency event handlers (scroll, mousemove, input) +- Avoid synchronous storage or DOM operations in handlers +- Reduce DOM size (under 1500 elements ideal) +- Use CSS over JS for animations where possible + +### CLS (Cumulative Layout Shift) + +**What it measures:** How much the page jumps around as it loads. Unexpected layout shifts hurt usability. + +**Targets:** +- Good: under 0.1 +- Needs improvement: 0.1 to 0.25 +- Poor: over 0.25 + +**Common causes of poor CLS:** +- Images without explicit dimensions +- Ads, embeds, iframes that load late +- Dynamically injected content above existing content +- Web fonts causing FOIT/FOUT (flash of invisible/unstyled text) +- CSS that depends on JS-loaded data + +**Common fixes:** +- Always specify `width` and `height` (or `aspect-ratio`) on images and videos +- Reserve space for ads and embeds before they load +- Use `font-display: optional` or `font-display: swap` thoughtfully +- Avoid injecting content above the fold after initial render +- Preload critical fonts + +--- + +## Beyond Core Web Vitals + +### Time to First Byte (TTFB) + +The server response time. Bad TTFB makes everything else worse. + +**Targets:** under 800ms ideal. + +**Common causes:** +- Slow database queries on the request path +- N+1 query patterns +- Missing caching +- Server geographic distance from users (no CDN) +- Cold starts on serverless + +**Fixes:** +- Cache database queries +- Use a CDN for static and cacheable dynamic content +- Optimize critical-path queries +- Pre-render where possible (SSG, ISR) +- Edge functions for low-latency dynamic content + +### Bundle size + +JavaScript shipped to the browser. + +**Targets:** +- Initial JS under 170KB compressed for typical pages +- Lazy-loaded chunks under 100KB compressed each + +**Common causes of bloat:** +- Importing entire libraries when only one function is used +- Bundling polyfills for modern browsers +- Including dev-only code in production +- Duplicate dependencies (multiple versions of the same library) +- Large client-side state (Redux store snapshots, etc.) + +**Fixes:** +- Tree-shake imports (`import { fn } from 'lib'` not `import lib from 'lib'`) +- Code-split per route +- Lazy-load below-the-fold components +- Audit dependencies; replace heavy ones (e.g., moment.js → date-fns or native Intl) +- Build-time bundle analyzer to spot bloat +- Dynamic imports for rarely-used features + +### Image optimization + +Images are typically 60 to 80 percent of page weight. + +**Best practices:** +- Modern formats: WebP everywhere supported, AVIF where supported +- Responsive images: `srcset` for different viewport sizes +- Lazy loading: `loading="lazy"` for below-the-fold +- Explicit dimensions: prevents CLS +- Right size: don't ship 4000px images for 800px display +- LCP image: preload, never lazy-load + +### Font loading + +Web fonts often delay text render and cause CLS. + +**Best practices:** +- Self-host fonts (avoid third-party blocking) +- Preload critical fonts (`<link rel="preload" as="font">`) +- Use `font-display: swap` for non-critical fonts +- Subset fonts to remove unused glyphs +- Use variable fonts where possible +- Provide system-font fallback that visually matches + +### Third-party scripts + +Third parties (analytics, ads, chat widgets) often dominate performance budgets. + +**Audit each:** +- Is it required? +- Can it load after page interaction (defer)? +- Can it run from a worker (off main thread)? +- Is the third party itself fast? +- Are there lighter-weight alternatives? + +A common pattern: 50 percent of performance issues come from third-party scripts. + +--- + +## Workflow + +1. **Establish a baseline.** Lighthouse scan, WebPageTest run, or Real User Monitoring data. Capture current Core Web Vitals. +2. **Identify the worst offender.** LCP, INP, or CLS - which is failing? Focus there first. +3. **Diagnose specifically.** Browser dev tools (Performance tab, Network tab, Coverage tab). Identify the actual cause of the metric failure. +4. **Plan fixes.** Per identified issue, plan a specific change. Estimate impact and effort. +5. **Implement.** One fix at a time where possible. Easier to measure impact. +6. **Re-measure.** After each major fix, re-run Lighthouse and check Real User Monitoring. +7. **Iterate.** Performance is rarely solved in one pass. Plan for ongoing monitoring and fixes. + +--- + +## Tools + +**Lab tools** (run on demand): +- Lighthouse (built into Chrome DevTools) +- PageSpeed Insights (online) +- WebPageTest (online, more configurable) +- Browser Performance tab (deep flame graph analysis) + +**Field tools** (real user data): +- Chrome User Experience Report (CrUX) - public data for any site +- Real User Monitoring (RUM) - your own users (DataDog, New Relic, custom, etc.) +- Search Console Core Web Vitals report + +Lab tools are useful for diagnosis. Field tools are the source of truth for what users actually experience. + +--- + +## Failure patterns + +- **Optimizing without measuring.** Performance theater without baseline metrics. Always measure first. +- **Optimizing the wrong metric.** A great Lighthouse score with bad real-user metrics means your test conditions don't match users. +- **Over-optimizing.** Spending weeks shaving 10ms off TTFB while CLS is 0.4. Fix the worst offender first. +- **Lighthouse-driven optimization only.** Lighthouse runs in idealized conditions. Always check field data. +- **Single-page optimization.** Performance regressions creep in across the codebase. Build performance budgets and CI checks. +- **Treating every byte as equal.** A render-blocking 100KB script is worse than a deferred 500KB script. +- **Bundle size obsession.** Bundle size matters, but execution time matters more. A small bundle that takes 5 seconds to parse is worse than a larger bundle that runs fast. +- **Ignoring third parties.** "It's the analytics tag, not us." Third parties run on your domain in your users' eyes. Own them. + +--- + +## Output format + +Default output is a performance report at `performance-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools, conditions, sample pages) +3. Current state (Core Web Vitals, Lighthouse scores, RUM data) +4. Critical issues (Core Web Vitals failures) +5. Important issues (sub-optimal but not failing) +6. Polish (further-than-required wins) +7. Remediation roadmap (sequenced) +8. Performance budget recommendations +9. Monitoring plan + +For complex audits, include: +- Per-page Lighthouse exports +- Bundle analysis output +- Network waterfall screenshots +- Specific code snippets to change + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Full performance audit report template. +- [`references/optimization-checklist.md`](references/optimization-checklist.md) - Quick-reference checklist of common optimizations by priority. +- [`references/optimization-playbook.md`](references/optimization-playbook.md) - Symptom-to-fix playbook for the common Core Web Vitals problems (LCP, INP, CLS). diff --git a/skills/performance-optimization/references/audit-template.md b/skills/performance-optimization/references/audit-template.md new file mode 100644 index 0000000..a4b256a --- /dev/null +++ b/skills/performance-optimization/references/audit-template.md @@ -0,0 +1,203 @@ +# Performance Audit Report + +A fillable template for documenting a web performance audit. Fill every section. Empty sections signal an incomplete audit. + +The output is the report. The report is what the team acts on. Weak reports produce no fixes. + +--- + +## Audit metadata + +**Site / app:** [Name and URL] +**Pages audited:** [List the specific URLs, not "the site"] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Devices and conditions tested:** +- Mobile: [Device class, network throttling] +- Desktop: [Network throttling] +- Geographies: [If multi-region tested] +**Tools used:** [Lighthouse, WebPageTest, Chrome DevTools, real-user data source, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall state of performance. +2. Whether the site passes Core Web Vitals at the 75th percentile. +3. The single biggest issue and what it costs. +4. The recommended next move. +5. Estimated effort and impact for the top fix. + +> [Summary] + +--- + +## Core Web Vitals scorecard + +Use field data (CrUX, RUM) where available. Lab data (Lighthouse) is a fallback and a diagnostic, not a final verdict. + +| Metric | Target (good) | Mobile p75 | Desktop p75 | Status | +|---|---|---|---|---| +| LCP (Largest Contentful Paint) | < 2.5s | | | Pass / Needs work / Fail | +| INP (Interaction to Next Paint) | < 200ms | | | Pass / Needs work / Fail | +| CLS (Cumulative Layout Shift) | < 0.1 | | | Pass / Needs work / Fail | +| TTFB (Time to First Byte) | < 800ms | | | Pass / Needs work / Fail | +| FCP (First Contentful Paint) | < 1.8s | | | Pass / Needs work / Fail | + +### Trend + +- [ ] Improving over the past 28 days +- [ ] Stable +- [ ] Regressing + +### Field data source + +[CrUX history, Search Console, Sentry, RUM tool. Note the date range and traffic volume that the data covers.] + +--- + +## Page-level findings + +For each audited page, fill out: + +### Page: [URL or template name] + +**Type:** [Marketing / product / app shell / API-driven] +**Traffic share:** [Rough % of site traffic] +**Field metrics (if available):** +- LCP p75: +- INP p75: +- CLS p75: + +#### Lab metrics (Lighthouse mobile, slow 4G) + +- Performance score: +- LCP: +- INP (or TBT as proxy): +- CLS: +- Total page weight: +- Total requests: +- JS payload (parsed): + +#### Top issues on this page + +| # | Issue | Impact metric | Severity | Effort | +|---|---|---|---|---| +| 1 | | LCP / INP / CLS / TTFB | High / Med / Low | S / M / L | +| 2 | | | | | +| 3 | | | | | + +(Repeat the page block for each audited page.) + +--- + +## Cross-cutting findings + +Issues that affect many pages or the whole site. Often higher leverage than per-page fixes. + +### Asset pipeline + +- [ ] Images served in modern formats (WebP, AVIF)? +- [ ] Images served at appropriate sizes (responsive `srcset`)? +- [ ] Critical above-the-fold images preloaded? +- [ ] Below-the-fold images lazy-loaded? +- [ ] Video uses `preload="none"` or poster image until interaction? +- [ ] Fonts subsetted, woff2, `font-display: swap` (or `optional` for stable layout)? +- [ ] Self-hosted vs third-party fonts considered? + +### JavaScript + +- [ ] Bundle size budget defined? +- [ ] Code splitting per route? +- [ ] Third-party scripts inventoried, justified, and budgeted? +- [ ] Unused JavaScript flagged (Coverage tab in DevTools)? +- [ ] Long tasks (>50ms) inventoried? + +### CSS + +- [ ] Render-blocking CSS minimized? +- [ ] Critical CSS inlined for above-the-fold? +- [ ] Unused CSS flagged? + +### Server / network + +- [ ] HTTPS, HTTP/2 or HTTP/3 enabled? +- [ ] Compression (Brotli or gzip) enabled for text assets? +- [ ] Cache headers correct for static assets (long max-age, immutable)? +- [ ] CDN in front of origin? +- [ ] Origin response time (TTFB) measured and acceptable? + +### Layout stability + +- [ ] Images and embeds have explicit `width` and `height` (or `aspect-ratio`)? +- [ ] No layout shift from late-loading fonts? +- [ ] No layout shift from injected ads or banners? + +### Interactivity + +- [ ] Main-thread blocking under 200ms p75? +- [ ] Heavy listeners debounced or moved off main thread? +- [ ] Hydration cost measured (for SSR / partially hydrated frameworks)? + +### Third-party scripts + +| Vendor | Purpose | Bytes | Main-thread cost | Necessary? | +|---|---|---|---|---| +| | | | | | +| | | | | | + +--- + +## Recommendations + +Prioritized action list. Each item is concrete, owned, and sized. + +### Now (this week) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Next (this sprint or month) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Later (this quarter or beyond) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | + +--- + +## Monitoring and re-test plan + +- **Re-test cadence:** [When will the audit be re-run?] +- **Field data tracking:** [Where will Core Web Vitals be tracked over time? CrUX dashboard, RUM tool, Search Console.] +- **Performance budget:** [Define and link the budget. Example: LCP under 2.0s p75 mobile, JS payload under 200KB compressed per route.] +- **Alert thresholds:** [When does someone get paged?] +- **Owner of ongoing performance:** [Person or team] + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- **Lab tests run:** [Tool, settings, run count] +- **Field data window:** [Date range, traffic volume] +- **Throttling profile:** [Slow 4G, Fast 3G, etc.] +- **Geographies tested:** [List] +- **Caveats:** [Anything that limits the audit's confidence, e.g., no field data, low traffic, single-page sample] diff --git a/skills/performance-optimization/references/optimization-checklist.md b/skills/performance-optimization/references/optimization-checklist.md new file mode 100644 index 0000000..3c53a5a --- /dev/null +++ b/skills/performance-optimization/references/optimization-checklist.md @@ -0,0 +1,138 @@ +# Performance Optimization Checklist + +Quick-reference checklist of common performance optimizations, ordered by typical impact-per-effort. Use it as a triage list, not a script. Skip what does not apply. + +For symptom-to-fix walkthroughs, see `optimization-playbook.md`. For a structured audit report, see `audit-template.md`. + +--- + +## P0: blocks Core Web Vitals at the 75th percentile + +These optimizations almost always pay back. If a site is failing CWV, start here. + +### Images + +- [ ] LCP image is preloaded with `<link rel="preload" as="image" fetchpriority="high">` +- [ ] LCP image is NOT lazy-loaded +- [ ] Images use modern formats (WebP, AVIF) with fallback +- [ ] Images use responsive `srcset` with appropriately sized variants +- [ ] All `<img>` and `<video>` tags have explicit `width` and `height` (or `aspect-ratio` CSS) +- [ ] Below-the-fold images use `loading="lazy"` +- [ ] Decorative images use `decoding="async"` + +### Fonts + +- [ ] Web fonts use `font-display: swap` (or `optional` for layout stability) +- [ ] Font files are woff2 and subsetted to actual glyphs used +- [ ] Critical font files are preloaded +- [ ] Preconnect to font origin if hosted off-domain + +### JavaScript on the critical path + +- [ ] No render-blocking scripts in `<head>` (use `defer` or `async` or move to `<body>` end) +- [ ] Heavy third-party scripts (chat widgets, A/B test tools, analytics) are deferred until interaction or after load +- [ ] Bundle size budget enforced per route +- [ ] Code split per route or feature +- [ ] Unused JavaScript removed (Coverage tab in DevTools) + +### Layout stability + +- [ ] No content insertion above the fold after initial render (banners, ads, popups) +- [ ] Skeleton states or placeholders prevent layout shift on async content +- [ ] Avoid `@font-face` with no fallback chain +- [ ] Avoid web fonts that change metrics significantly between fallback and loaded state (use `size-adjust` and `ascent-override`) + +--- + +## P1: significant gains, moderate effort + +### Server and network + +- [ ] HTTP/2 or HTTP/3 enabled +- [ ] Brotli compression enabled (or gzip if Brotli unavailable) +- [ ] Cache headers correct for static assets: long `max-age` and `immutable` for hashed files +- [ ] CDN in front of origin for static assets (and dynamic where applicable) +- [ ] Origin response time (TTFB) under 800ms at p75 +- [ ] DNS prefetch and preconnect for critical third-party origins + +### Rendering strategy + +- [ ] Above-the-fold content is server-rendered (or static) where possible +- [ ] Critical CSS inlined for above-the-fold +- [ ] Non-critical CSS loaded asynchronously +- [ ] Partial / progressive hydration considered for heavy SPA pages + +### Resource loading + +- [ ] `<link rel="preload">` used for critical assets only (overuse hurts) +- [ ] `<link rel="modulepreload">` used for ESM critical chunks +- [ ] Resource hints (`prefetch`, `prerender`) used for likely next pages on key flows + +### Long tasks + +- [ ] Main-thread tasks over 50ms identified and broken up (`scheduler.yield()`, `requestIdleCallback`, web workers) +- [ ] Hydration cost measured for SSR sites; large components hydrated lazily + +--- + +## P2: smaller gains, useful in aggregate + +### Images and media + +- [ ] Hero video uses `preload="none"` or poster image until interaction +- [ ] Animated GIFs replaced with looped video (smaller, smoother) +- [ ] SVGs optimized (SVGO) and inlined where small +- [ ] Image delivery service (Cloudinary, ImgIX, native CDN image transform) used for on-the-fly resizing + +### Third-party scripts + +- [ ] Each third-party script audited: necessary, budgeted, and optimized +- [ ] Tag manager rules audited; remove unfired or duplicate tags +- [ ] Self-host third parties where licensing allows and origin caching helps + +### CSS + +- [ ] Unused CSS removed +- [ ] CSS specificity audited; avoid expensive selectors (deeply nested, universal) +- [ ] `will-change` and `transform`/`opacity` animations preferred over animating layout properties + +### JavaScript + +- [ ] Tree shaking confirmed working (check final bundle for dead code) +- [ ] Polyfills served only to browsers that need them (differential serving, `module/nomodule` pattern) +- [ ] Date / time / number formatting uses `Intl` instead of large libraries +- [ ] Heavy utility libraries replaced with smaller alternatives or native code where reasonable + +--- + +## P3: polish + +- [ ] Service worker caches critical assets for repeat visits +- [ ] Speculation Rules API used for likely next-page prerender +- [ ] HTTP early hints (103) used for critical preloads +- [ ] Server timing headers exposed for diagnostic visibility +- [ ] Real user monitoring (RUM) feeds CWV dashboard + +--- + +## Anti-patterns to remove + +These appear often, hurt always, and warrant a same-day fix. + +- [ ] Lazy-loaded LCP image +- [ ] Render-blocking analytics or tag manager in `<head>` without `async` +- [ ] Multiple competing fonts (more than 2 families or more than 4 weights) +- [ ] CSS-in-JS that ships runtime style generation to the client without static extraction +- [ ] Hero image larger than its rendered size by more than 2x +- [ ] Synchronous third-party scripts above any user-visible content +- [ ] Layout-shifting cookie banner or consent modal +- [ ] Background images that are CSS-loaded above the fold (preload friendlier as `<img>`) + +--- + +## How to use this checklist + +1. Run a Lighthouse + CrUX read of the 3-5 most important pages. +2. Walk this checklist top to bottom for each page. Mark passes, gaps, and not-applicable. +3. Triage gaps into the audit report (`audit-template.md`) under Now / Next / Later. +4. Re-test after each fix lands. Performance is a moving average, not a snapshot. diff --git a/skills/performance-optimization/references/optimization-playbook.md b/skills/performance-optimization/references/optimization-playbook.md new file mode 100644 index 0000000..b0419cf --- /dev/null +++ b/skills/performance-optimization/references/optimization-playbook.md @@ -0,0 +1,300 @@ +# Optimization Playbook + +A step-by-step playbook for common performance problems. Pick the symptom, follow the steps. + +--- + +## Symptom: LCP failing (>2.5s) + +The largest content element on the page takes too long to paint. + +### Step 1: Identify the LCP element + +In Chrome DevTools Performance panel: +1. Record a page load +2. Find the LCP marker +3. Note which element is the LCP (usually a hero image or large heading) + +### Step 2: Optimize that specific element + +**If LCP element is an image:** +- Use modern format (WebP, AVIF) +- Serve appropriately sized version (don't ship a 4000px image to a 800px container) +- Preload it: `<link rel="preload" as="image" href="hero.webp" fetchpriority="high">` +- Avoid lazy-loading the LCP image (use eager loading) +- Use `fetchpriority="high"` on the image element + +**If LCP element is text/heading:** +- Ensure web fonts don't block rendering (`font-display: swap`) +- Inline critical CSS for the heading section +- Preconnect to font origin: `<link rel="preconnect" href="https://fonts.example.com">` + +**If LCP is loading slowly because the page is slow overall:** +- See "Symptom: TTFB slow" below +- Reduce render-blocking resources +- Reduce total payload before LCP element + +### Step 3: Measure + +Re-test in Lighthouse and DevTools. Verify LCP under 2.5s on a slow connection (Slow 4G simulation in DevTools). + +--- + +## Symptom: INP failing (>200ms) + +Interactions feel sluggish. The page takes too long to respond to user input. + +### Step 1: Find the slow interactions + +In Chrome DevTools Performance panel: +1. Record while clicking, typing, or interacting +2. Look for long tasks (orange bars >50ms) following input events +3. Identify the function calls that take the longest + +### Step 2: Reduce the work + +**For event handlers:** +- Move heavy work out of the synchronous path +- Use `setTimeout` or `requestIdleCallback` to yield to the main thread +- Debounce or throttle frequent events (scroll, mouse move, resize) + +**For component re-renders (React, Vue, etc.):** +- Memoize expensive computations +- Avoid creating new objects/arrays/functions in render that get passed as props +- Use virtualization for large lists (react-window, virtua, or framework equivalent) +- Profile to find which components re-render and why + +**For startup hydration (SSR/SSG frameworks):** +- Defer hydration of non-critical components +- Use island architecture or partial hydration where supported +- Code-split aggressively below-the-fold + +### Step 3: Verify + +INP should be under 200ms at the 75th percentile of real user data. + +--- + +## Symptom: CLS failing (>0.1) + +Content jumps around as the page loads. + +### Step 1: Identify the shifts + +In Chrome DevTools: +1. Open Performance Insights or Performance panel +2. Look for "Layout Shifts" markers +3. Click each to see what shifted + +### Step 2: Reserve space for dynamic content + +**Common offenders and fixes:** + +- **Images without dimensions.** Add `width` and `height` attributes (or `aspect-ratio` CSS). +- **Late-loading ads or embeds.** Reserve a fixed-size container. +- **Web fonts swapping.** Use `font-display: optional` or size-adjust descriptors. +- **Skeleton loaders that don't match final size.** Match dimensions exactly. +- **Animations triggering layout.** Animate only `transform` and `opacity`. +- **Insertion of content above existing content.** Reserve space or insert below. + +### Step 3: Verify + +Run Lighthouse. Real-user CLS at 75th percentile should be under 0.1. + +--- + +## Symptom: TTFB slow (>800ms) + +Server takes too long to respond. + +### Step 1: Check the server response + +Use WebPageTest or `curl -w "@curl-format.txt" -s -o /dev/null https://example.com` to measure just TTFB. + +### Step 2: Identify the bottleneck + +**Common causes:** + +- **No caching at the edge.** Add a CDN. Set Cache-Control headers correctly. +- **Slow database queries.** Run EXPLAIN on slow queries. Add indexes. Eliminate N+1 patterns. +- **Slow third-party API calls in the render path.** Defer to client or precompute. +- **Heavy server-side rendering.** Profile the SSR work. Memoize what's repeated. +- **Cold starts (serverless).** Provisioned concurrency or warming pings. + +### Step 3: Verify + +TTFB under 600ms at the 75th percentile is the target. Under 200ms is excellent. + +--- + +## Symptom: Bundle size too large + +JavaScript payload bloating the page. + +### Step 1: Audit the bundle + +Run a bundle analyzer (Webpack Bundle Analyzer, source-map-explorer, etc.). Sort by size. + +### Step 2: Identify the offenders + +**Common bloat sources:** + +- **Unused dependencies.** Tree-shaking missing or broken. +- **Whole-library imports.** `import { debounce } from 'lodash'` pulls all lodash. Use `import debounce from 'lodash/debounce'`. +- **Polyfills shipped to modern browsers.** Use differential serving. +- **Source maps in production bundle.** Should be separate files, not inline. +- **Moment.js, Lodash, jQuery.** Often replaceable with smaller alternatives or native APIs. +- **Multiple versions of the same library.** Check `npm ls [library]`. Dedupe. + +### Step 3: Reduce + +- Replace heavy libraries with lighter alternatives (date-fns or dayjs instead of moment, native fetch instead of axios) +- Code-split routes +- Code-split heavy components (modals, charts, editors) +- Use dynamic imports for below-the-fold features + +### Step 4: Set a budget + +In your build config or CI, fail builds that exceed the budget. + +--- + +## Symptom: Image-heavy page loads slowly + +### Step 1: Audit images + +- Count images on the page +- Note current sizes and formats +- Note which are above-the-fold (eagerly loaded) vs below (should be lazy) + +### Step 2: Optimize each + +**Format:** +- Photos: WebP or AVIF (with JPEG fallback) +- Graphics: SVG or PNG (with WebP fallback) +- Animations: video (MP4/WebM) instead of GIF for size + +**Sizing:** +- Generate multiple sizes via `srcset` +- Use `sizes` attribute to tell the browser the rendered size + +```html +<img + src="hero-800.webp" + srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1600.webp 1600w" + sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px" + width="1600" + height="900" + alt="Description" + loading="eager" + fetchpriority="high" +/> +``` + +For below-the-fold: +- `loading="lazy"` +- Without `fetchpriority` + +**Compression:** +- Use a build-time image pipeline (sharp, imagemin) to compress automatically +- Quality 75-85 is usually invisible to users while halving file size + +--- + +## Symptom: Web fonts blocking text + +### Step 1: Audit font loading + +In DevTools Network tab, filter by font. Note: +- File size +- When they load relative to first paint +- Whether text is invisible or fallback during load + +### Step 2: Optimize + +- **Use `font-display: swap`** to show fallback text immediately +- **Subset fonts** to only the characters needed (Latin only is much smaller than full Unicode) +- **Self-host critical fonts** instead of CDN where possible +- **Preload critical fonts:** + ```html + <link rel="preload" href="/fonts/regular.woff2" as="font" type="font/woff2" crossorigin> + ``` +- **Use `size-adjust`, `ascent-override`, `descent-override`** in `@font-face` to match metrics with fallback fonts (reduces CLS) + +--- + +## Symptom: Third-party scripts dragging performance + +### Step 1: Inventory third-parties + +In DevTools Network tab, list all third-party domains. For each: +- Size +- Blocking or non-blocking? +- Necessary? + +### Step 2: Decide on each + +For every third-party script, ask: does the business value justify the performance cost? + +**Common offenders:** +- Heavy analytics (audit if all pixels are necessary; consider server-side tagging) +- Customer support chat widgets (load on user intent, not on page load) +- A/B testing tools (defer non-critical experiments) +- Multiple ad networks (consolidate) +- Tag managers loading hundreds of tags + +**Fixes:** +- Remove unused tags +- Defer non-critical scripts (`async` or `defer`) +- Self-host where licensing allows (avoids extra DNS lookup) +- Load chat widgets on user interaction, not on page load +- Consolidate analytics where possible + +### Step 3: Set a third-party budget + +Number of third-party domains, total third-party JS payload. Block-add for new third-parties without explicit performance review. + +--- + +## Performance budget template + +Set hard limits in your CI to prevent regression: + +```yaml +budget: + - resourceSizes: + - resourceType: total + budget: 500 # kilobytes + - resourceType: script + budget: 200 + - resourceType: image + budget: 200 + - resourceType: stylesheet + budget: 50 + - resourceType: font + budget: 100 + - resourceType: third-party + budget: 100 + - timings: + - metric: largest-contentful-paint + budget: 2500 # milliseconds + - metric: cumulative-layout-shift + budget: 0.1 + - metric: total-blocking-time + budget: 200 +``` + +Tools like Lighthouse CI, Calibre, or SpeedCurve can enforce these budgets in CI. + +--- + +## When to call it done + +A page is "performance optimized" when: + +1. Real-user Core Web Vitals at 75th percentile pass thresholds +2. Lighthouse performance score >90 on representative pages +3. Performance budgets enforced in CI +4. Periodic re-audit scheduled (quarterly minimum) + +Performance is not a one-time project. New code adds weight. New features add complexity. Plan for ongoing maintenance. diff --git a/skills/pillar-content-architecture/SKILL.md b/skills/pillar-content-architecture/SKILL.md new file mode 100644 index 0000000..a0bf78d --- /dev/null +++ b/skills/pillar-content-architecture/SKILL.md @@ -0,0 +1,260 @@ +--- +name: pillar-content-architecture +description: "How to design a content hub that earns topical authority. Pillar topic selection, cluster planning, internal linking architecture, URL structure, pillar and cluster page anatomy, topical authority signals for SEO and AEO/GEO, and the maintenance discipline that distinguishes intentional hubs from accidental orphans. Triggers on pillar content, content hub, topic cluster, topical authority, content architecture, hub and spoke, pillar page, cluster page, content silo, internal linking strategy. Also triggers when a content set is not ranking despite individual piece quality, when a pillar was launched without a cluster, or when content has accumulated without an architecture." +category: content +catalog_summary: "Hub-level content architecture: pillar topic selection, cluster planning, internal linking, URL structure, pillar and cluster page anatomy, topical authority signals, refresh discipline" +display_order: 1 +--- + +# Pillar Content Architecture + +A senior content architect's playbook for designing content hubs that earn topical authority. + +Most content programs accumulate accidentally. Pieces ship one at a time, internal linking happens (or does not) in editing, similar topics get covered by multiple pieces with no coordination, and six months later the team has a content set that looks like a sitemap but feels like a yard sale. Search engines see disconnected pages; AI engines see scattered citations; readers cannot tell which piece is the entry point and which is the reference. + +This skill is the discipline of intentional hub architecture. It assumes you have decided which topic areas to invest in (see `content-strategy`) and have keyword data (see `seo-keyword`). It does not write any individual piece (see `content-brief-authoring` for per-piece work and `content-and-copy` for execution). What it does is design the structure: which topic gets a pillar, which subtopics get cluster pieces, how the pieces link to each other, where they live in the URL hierarchy, and what topical authority signals the architecture is engineered to produce. + +When to use this skill: launching a new content hub, restructuring an existing content set into a hub, deciding whether a piece should be a pillar or a cluster, or auditing why a content area is not ranking despite individual piece quality. + +--- + +## What this skill is for + +This skill spans hub-level content architecture. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: multiple topic pillars, editorial calendar, governance, formats. Decides what topic areas to invest in across a quarter or year. +- `seo-keyword` is upstream-input: keyword research that surfaces candidate pillar topics with volume, difficulty, and intent data. +- This skill is hub-scope: one pillar plus its cluster, the architecture that ties them together. The structural decisions, not the per-piece content. +- `content-brief-authoring` is per-piece scope: brief for one content artifact. Each cluster piece (and the pillar itself) gets briefed via that skill. +- `content-and-copy` is execution scope: writing the piece itself. +- `seo-content-gap-audit` is audit-side: finds missing pieces in an existing content set after the fact. This skill prevents the gaps; that skill catches the ones that emerge. + +The clean composition: `content-strategy` decides which topics, `seo-keyword` surfaces opportunities, this skill designs the hub, `content-brief-authoring` briefs each piece, `content-and-copy` writes each piece, `seo-content-gap-audit` later catches what slipped. Six skills, sequential. + +The audience: SEO content strategists, content architects, in-house teams designing content hubs, agencies running topical authority programs. The voice is senior content architect to junior content marketer. Concrete, opinionated, honest about what makes a hub earn authority versus decorate the sitemap. + +--- + +## Pillar vs cluster vs orphan content + +The keystone distinction. Three categories of content in any program. + +**Pillar.** Comprehensive piece covering a major topic area. 2,500 to 5,000 words plus. Anchors the topical authority claim for the topic. Receives links from cluster pieces; links out to cluster pieces selectively, not as a footer dump. The pillar is the entry point for the topic and the reference the cluster orbits. + +**Cluster.** Narrower piece covering a specific facet of the pillar topic. 800 to 2,000 words. Links up to pillar; may link sideways to other clusters in the same hub when a connection is natural. Each cluster answers one specific question within the pillar's scope. + +**Orphan.** Piece that does not connect to a pillar or cluster. May rank or convert on its own merits, but does not compound into topical authority. Some orphans are fine by design (release-note pages, customer stories, one-off campaigns); most orphans are accidents. + +The pathology. Most content programs are 80% orphans, 15% accidental clusters, 5% accidental pillars. The discipline is moving toward 70% intentional clusters, 20% intentional pillars, 10% standalone-by-design. Same total content volume; different architectural outcome. + +The reading model. Search engines and AI engines both read internal-link graphs to infer topical authority. A pillar with 12 well-linked cluster pieces signals depth on a topic. 12 orphans on the same topic signal scattered, less-authoritative coverage. The architecture is the signal. + +Detail and decision tree in [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md). + +--- + +## Topic selection for pillar pages + +Not every topic deserves a pillar. The five-criterion selection framework: + +1. **Search volume justifies the investment.** Pillar topic has enough monthly volume to support a 3,000 to 5,000-word effort plus 8 to 15 cluster pieces. Sub-100 monthly searches usually does not. +2. **Topic has natural facets.** You can identify 8 to 15 distinct subtopics that could each be their own piece. If you can only think of 3, it is probably a cluster, not a pillar. +3. **Commercial relevance.** The topic connects to your business model. A pillar without commercial signal is content marketing for content marketing's sake. +4. **Competitive feasibility.** Top 10 SERP for the pillar keyword is achievable. If the SERP is dominated by Wikipedia, government sites, and Fortune 500 brands, your pillar will rank position 47 no matter how good it is. +5. **Editorial commitment.** The team will maintain the pillar (refresh annually, add new clusters, update statistics). Pillars are not ship-and-forget; they are 5-year commitments. + +The "everything is a pillar" anti-pattern. Teams call any 3,000-word piece a pillar. Length does not make a pillar. The architecture does. Pillar is the role a piece plays in the hub structure, not the word count. + +Detail in [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md). + +--- + +## Cluster planning + +Once a pillar is selected, plan its cluster: + +1. **Cluster size.** Typically 8 to 15 pieces for a strong hub. Below 5 reads thin; above 25 becomes unmanageable; sweet spot is 10 to 12. +2. **Cluster facets.** Each cluster piece covers one facet of the pillar topic. Facets are surfaced from keyword research (long-tail variations of pillar keyword), "people also ask" data, sub-headings in top-ranking pillar pages on the SERP, competitor cluster maps, and first-party customer questions (sales calls, support tickets). +3. **No facet duplication.** Two cluster pieces should not target overlapping queries. If they do, consolidate to one piece. +4. **Cluster heterogeneity.** Clusters should cover the topic from multiple angles (definition, how-to, comparison, examples, common mistakes, costs, alternatives, case studies) rather than 12 variations of "what is X." +5. **Sequence.** Ship pillar first (or alongside the first 3 to 5 clusters). The link graph will not form without the pillar in place; clusters that link to a non-existent pillar are orphans-in-waiting. + +Detail in [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md). + +--- + +## Internal linking architecture + +The hub's internal-link graph is what actually produces topical authority signals. The architecture has three directions: + +**Pillar to cluster (top-down).** Pillar links out to each cluster piece via contextual anchors, typically once per cluster from within the pillar's body. Do not bury cluster links in a "related reading" footer; weave them into the relevant section of the pillar where the reader's curiosity peaks. + +**Cluster to pillar (bottom-up).** Every cluster piece links up to the pillar at least once, typically in the first 200 words and again in the closing section. Bottom-up is the discipline that makes the pillar compound; without it the pillar is just a long article. + +**Cluster to cluster (lateral).** Selective lateral linking when one cluster naturally references another. Do not force lateral links; an "everyone links to everyone" cluster is messy and dilutes anchor text relevance. + +**Anchor text discipline.** Vary the anchor text. "Click here" is dead; exact-match keyword stuffing is dead; descriptive natural-language anchors are alive. The brief for each piece (see `content-brief-authoring`) specifies anchor text per outbound link. + +The "linking inventory" pattern. Maintain a sheet (or database row, or dbt model) tracking every link in the hub, who links to whom, and the anchor text used. Audit quarterly to catch broken links, anchor-text drift, and missing connections that should exist. + +Detail in [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md). + +--- + +## URL structure and information architecture + +URL patterns matter for both crawl clarity and reader navigation. Decision factors: + +**Subfolder vs subdomain.** Subfolder is the default (`example.com/hub-topic/cluster-piece`) for SEO consolidation; both pillar and cluster live on the same domain authority. Subdomain is appropriate only for genuinely distinct properties (`docs.example.com`, `community.example.com`). + +**Hub URL pattern.** `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. Avoid `/blog/cluster-piece/` if the goal is hub authority; the URL itself signals topical grouping to crawlers and readers. + +**Slug conventions.** Short, descriptive, keyword-aware but not stuffed. `/seo-content-strategy/keyword-research-for-pillars/` not `/the-ultimate-guide-to-seo-content-strategy-keyword-research-for-pillar-pages-2026/`. + +**Breadcrumbs.** Surface the hub structure in breadcrumb navigation. Helps readers see where they are; helps crawlers see the hierarchy. + +The "/blog/ trap." Teams put pillar and clusters under `/blog/` because that is where the CMS folder is. This works structurally but loses the URL signal that says "these pieces belong together as a topical hub." + +Detail in [`references/url-structure-patterns.md`](references/url-structure-patterns.md). + +--- + +## Pillar page anatomy + +A pillar page does specific work. The standard sections: + +- **Hero.** Defines the topic, signals scope ("The complete guide to X for Y audience"), establishes authority quickly. +- **TL;DR or executive summary.** 150 to 250 words at the top. AI engines often cite this section verbatim. Treat it as the citation-ready summary, not as a marketing intro. +- **Comprehensive body.** Covers the topic's major facets, with internal-link callouts to cluster pieces for deep dives. The body is not a comprehensive treatment of every facet; it is a guided tour with depth links. +- **Use cases or examples.** Anchor the abstract topic to concrete instances. +- **Common mistakes / FAQ.** AI-citation friendly section with structured Q&A. Pair with FAQ schema markup. +- **Closing or next steps.** Directs reader into the cluster (which piece to read next based on intent). +- **Schema markup.** Article or HowTo schema depending on intent; FAQPage schema for the FAQ section. + +Pillar length. 3,000 to 5,000 words is the typical range. Pillar quality is comprehensiveness AND depth, not just word count. A 6,000-word pillar that covers 3 facets is worse than a 4,000-word pillar that covers 12 facets. + +Detail in [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md). + +--- + +## Cluster piece anatomy + +Cluster pieces have a different shape: + +- **Hero.** Focused on one specific question or task, not broad. +- **Pillar callout.** Link up to pillar in the first 200 words. Typical phrasing: "This piece covers X. For the broader context on Y, see our guide to [pillar topic]." +- **Focused body.** Answers the specific question with depth, but does not expand into adjacent facets (those have their own cluster pieces). +- **Lateral callouts (selective).** When relevant, link to 1 or 2 sibling cluster pieces. +- **Closing.** Link back to pillar OR to the next logical cluster piece in a reader journey. + +Cluster length. 800 to 2,000 words typical. A cluster piece longer than 2,500 words is probably a mini-pillar that should either get promoted to its own pillar or be split into two cluster pieces. + +Detail in [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md). + +--- + +## Topical authority signals + +Signals that make hub architecture compound into authority. The two-engine view: pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +**SEO signals:** + +- Internal-link graph density on the topic (PageRank flow within the hub) +- Comprehensive entity coverage across pillar plus clusters (mentioned entities, statistics, citations) +- URL structure clarity +- Breadcrumb hierarchy +- Schema markup (Article, HowTo, FAQPage as appropriate) +- E-E-A-T signals: author credentials, expertise demonstrated, trust signals on every piece + +**AEO and GEO signals:** + +- Answer-paragraph format directly under H2 headings (40 to 60 words, citation-ready) +- TL;DR section on pillars (highly citable; AI engines extract it verbatim) +- FAQ schema (still cited heavily by AI engines including Perplexity and ChatGPT) +- Specific statistics with cited sources +- Named experts and named methods (entities AI engines weight heavily for citation) +- Distinctive POV that AI engines can attribute to your brand + +The two-engine optimization is complementary, not competing. Both reward depth, structure, and entity coverage. The hub architecture creates more surface area for both signal types than scattered orphan content can. + +Detail in [`references/topical-authority-signals.md`](references/topical-authority-signals.md) and the `seo-aeo-geo` skill for AEO/GEO strategy at the program level. + +--- + +## Maintenance and refresh patterns + +Hubs decay if not maintained. The discipline: + +- **Annual pillar refresh.** Every 12 months, audit the pillar against current SERP, update statistics, add new sections for emerged facets, prune sections that no longer matter, refresh internal-link callouts to cluster pieces (since the cluster has likely grown). +- **Cluster refresh as triggered.** Clusters refresh when keyword performance drops, when a new sub-topic emerges, or when a cluster's links go stale. +- **Cluster expansion.** Add new cluster pieces as the topic surfaces new facets. A hub at year 1 might have 8 clusters; year 3 could have 18. +- **Cluster pruning.** Kill cluster pieces that fail to rank or get cited after 12 months. Redirect to the most-relevant remaining cluster or to the pillar. Pruning is not failure; it is hygiene. +- **Hub lifecycle.** Hubs themselves have a lifespan. After 5 to 7 years, even mature hubs may need wholesale restructuring as the topic landscape shifts. + +The "set and forget" failure. Hub launches, ranks, drives traffic for 2 years, then decays without anyone noticing because nobody owns the hub long-term. Hub ownership is durable: single owner across 3 to 5 year horizons, not "the team that launched it." + +Detail in [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pillar-failures.md`](references/common-pillar-failures.md). + +- "We have 80 blog posts but no rankings." Orphan content; no hub architecture. +- "Our 8,000-word pillar does not rank." Comprehensive but no cluster support; pillar without a hub is just a long article. +- "We launched the pillar, never built the cluster." Architecture half-built signals nothing. +- "Cluster pieces do not link to the pillar." Top-down link graph but no bottom-up; the pillar does not compound. +- "Two cluster pieces target the same keyword." Self-cannibalization; consolidate. +- "Pillar URL is /blog/the-ultimate-guide-to..." Losing the URL hub signal. +- "Our pillar is 12 sections of 'what is X'." Facet homogeneity; covers one angle 12 ways. +- "We cannot tell which piece to refresh first." No maintenance ownership; no signals being tracked. +- "Pillar ranks but does not get cited by AI engines." Missing AEO/GEO signals (no TL;DR, no answer paragraphs, no FAQ schema). +- "Hub launched 3 years ago; nobody owns it now." Lifecycle ownership gap. +- "We have 25 clusters and it is chaos." Over-built; sweet spot was 12. + +--- + +## The framework: 12 considerations for hub architecture + +When designing or auditing a content hub, walk these 12 considerations. + +1. **Topic earns the pillar.** Search volume, facet count, commercial relevance, competitive feasibility, editorial commitment. +2. **Cluster size targets 10 to 12.** Sweet spot, not the maximum. +3. **Facet heterogeneity.** Definition, how-to, comparison, examples, mistakes, costs, alternatives. Not 12 variations of "what is X." +4. **No facet duplication.** Clusters cover distinct queries; consolidate when they overlap. +5. **Pillar to cluster to pillar link graph.** Top-down plus bottom-up plus selective lateral. +6. **Anchor text discipline.** Varied, descriptive, natural-language. No stuffing, no "click here." +7. **URL structure signals the hub.** `/topic/` not `/blog/`. +8. **Pillar anatomy includes TL;DR and FAQ.** Citation-ready sections for AI engines. +9. **Cluster anatomy links UP to pillar early.** First 200 words and closing. +10. **AEO/GEO and SEO together.** Two-engine optimization, complementary not competing. +11. **Annual pillar refresh plus triggered cluster refresh.** Maintenance is part of the architecture. +12. **Hub ownership is durable.** Single owner across 3 to 5 year horizons; not "the team that launched it." + +The output of the framework is an architecture document the team can reference at every stage: pillar selected, cluster planned, links specified, URLs chosen, page anatomies templated, refresh cadence set, owner named. + +--- + +## Reference files + +- [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md) - Pillar vs cluster vs orphan decision tree with worked examples and the "everything is a pillar" anti-pattern. +- [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md) - Five-criterion framework expanded with B2B SaaS, ecommerce, services, and media examples. +- [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md) - Facet sourcing methods, sequencing patterns, heterogeneity check. +- [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md) - Top-down, bottom-up, lateral patterns; anchor text discipline; linking inventory; quarterly audit checklist. +- [`references/url-structure-patterns.md`](references/url-structure-patterns.md) - Subfolder vs subdomain decision; slug conventions; breadcrumbs; the /blog/ trap. +- [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md) - Section-by-section anatomy; TL;DR placement; FAQ schema; internal-link callouts; schema choices; length calibration. +- [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md) - Focused-question framing; pillar callout placement; lateral linking judgment. +- [`references/topical-authority-signals.md`](references/topical-authority-signals.md) - SEO and AEO/GEO signals at hub level; two-engine optimization framing. +- [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md) - Annual pillar refresh; triggered cluster refresh; cluster expansion and pruning; hub lifecycle. +- [`references/common-pillar-failures.md`](references/common-pillar-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: architecture is the moat + +Comprehensive content can be replicated. Authoritative sources can be cited. Individual pieces can be matched in quality by competitors with similar resources. What is harder to replicate is the compounding of an intentional hub built and maintained over years: the link graph, the entity coverage, the maintenance discipline, the topical depth signals that build over a 3 to 5 year horizon. + +That is the moat. Architecture is the only part of content marketing that compounds reliably; everything else is execution that can be matched. + +When in doubt about whether a hub is ready, ask: is the pillar selected against the five criteria, are the 10 to 12 clusters planned with facet heterogeneity, is the link graph specified top-down and bottom-up, is the URL structure clean, is the pillar anatomy templated with TL;DR and FAQ, is the refresh cadence set, and is the durable owner named? If yes to all of those, ship the hub plan and let the per-piece briefs and writers work. diff --git a/skills/pillar-content-architecture/references/cluster-piece-anatomy.md b/skills/pillar-content-architecture/references/cluster-piece-anatomy.md new file mode 100644 index 0000000..85ca692 --- /dev/null +++ b/skills/pillar-content-architecture/references/cluster-piece-anatomy.md @@ -0,0 +1,120 @@ +# Cluster piece anatomy + +Focused-question framing. Pillar callout placement. Lateral linking judgment. + +--- + +## The shape of a cluster piece + +A cluster piece is not a mini-pillar. Different shape, different work. + +### Hero (first 100 to 150 words) + +Focused on one specific question or task. The hero does not introduce the broader topic; the pillar does that. The hero introduces the cluster piece's specific facet. + +- **Title.** Includes the cluster's primary keyword. Often question-form ("What is a feature flag kill switch?") or task-form ("How to design a feature flag kill switch"). +- **Subhead.** One sentence promising the specific answer. + +### Pillar callout (within first 200 words) + +The bottom-up link to the pillar. Required. + +**Pattern.** "This piece covers feature flag kill switches in depth. For the broader context on rollout strategies that include kill switches as one safety mechanism, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +**Why required.** The pillar callout is the structural signal that this cluster belongs to the hub. Without it, the piece reads as a standalone article and the hub does not compound. + +**Why early.** Crawlers and AI engines weight links higher when they appear near the top of the page. The first 200 words is the citation-prime real estate; the pillar callout there has more impact than the same callout in the closing. + +### Focused body (the bulk of the cluster) + +Answers the specific question with depth. Does not expand into adjacent facets. + +**The discipline.** When the writer notices an interesting tangent into an adjacent facet, they note it as a candidate for another cluster piece and stay on topic. The cluster piece does one thing well; expansion belongs in a different piece. + +**Section structure.** 4 to 6 H2 sections covering the cluster's question from different angles. Each H2 has a featured-snippet-bait answer paragraph (40 to 60 words) followed by 200 to 400 words of development. + +### Lateral callouts (selective) + +When the cluster's body naturally references a sibling cluster, link to it. + +**Pattern.** A cluster on percentage rollouts naturally references kill switches in the section on "what happens when the rollout shows problems." A 1-sentence aside with a contextual link to the kill switches cluster. + +**Frequency.** 0 to 3 lateral links per cluster piece. Some clusters need none; some clusters at the topic's center connect to several siblings. + +**Anti-pattern.** Forced lateral linking. If the connection is not natural to the body's flow, the link is decorative and dilutes anchor signal. + +### Closing + +Two equally valid closing patterns. + +**Pattern A: link back to pillar.** "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns." + +**Pattern B: link to next cluster in a journey.** "If you have your kill switches designed and want to think about progressive rollouts, read our [percentage rollout guide](/feature-flag-rollout/percentage-rollouts/) next." + +The choice. Pattern A is the safe default; it reinforces the pillar and works for most cluster pieces. Pattern B is appropriate when the cluster has a clear "next step" in a reader journey (foundational concept → next concept). + +--- + +## Length calibration + +800 to 2,000 words is the typical cluster range. Calibrate to: + +- **The SERP for the cluster's specific keyword.** Top 10 word counts tell you the band. +- **The cluster's place in the hub.** Foundational clusters (definitions, intros) often run shorter; advanced clusters (deep how-tos, comparisons) often run longer. + +**The 2,500-word cluster trap.** A cluster piece longer than 2,500 words is probably a mini-pillar. Two diagnostic questions: + +1. Does it cover 2+ distinct facets? If yes, split into two cluster pieces. +2. Does it have 8+ H2 sections? If yes, it is structurally a pillar; either promote it (with cluster support) or trim. + +**The 600-word cluster trap.** A cluster piece shorter than 800 words is often too thin to rank for its target keyword. Either: + +- Expand to 1,000+ words with deeper coverage of the question. +- Merge with a sibling cluster if the topic does not have enough depth. +- Demote to a non-hub blog post if the piece is just a brief observation. + +--- + +## Featured snippet bait at H2 level + +Cluster pieces benefit from featured-snippet-bait answer paragraphs at every H2, not just at the top. + +**Pattern.** + +> ## What is a feature flag kill switch? +> +> A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. + +The 40 to 60 word answer paragraph is self-contained and citation-ready. AI engines extract these paragraphs as the canonical answers. + +**Frequency.** Every H2 should have a snippet-bait paragraph. The pattern repeats throughout the piece; it is a structural discipline. + +--- + +## Schema markup for clusters + +Cluster pieces typically use Article schema (or HowTo if the cluster is a step-by-step guide). FAQPage schema applies if the cluster has a real FAQ section. + +BreadcrumbList schema is required for cluster pieces; it tells crawlers the cluster is part of the hub. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +--- + +## When the cluster piece is also useful as a standalone + +Some cluster pieces will rank for queries unrelated to the pillar's topic. A cluster on "kill switches" might also rank for queries about software safety patterns generally. + +The decision: keep the cluster piece in the hub even when it ranks for non-hub queries. The pillar callout costs nothing for the standalone-query reader; the hub-traffic reader benefits from the link. Both audiences are served. + +The exception: when the cluster piece's standalone ranking dominates and the pillar context is misleading to the standalone-query reader, consider splitting into two pieces. Rare; usually the pillar callout works fine for both audiences. diff --git a/skills/pillar-content-architecture/references/cluster-planning-patterns.md b/skills/pillar-content-architecture/references/cluster-planning-patterns.md new file mode 100644 index 0000000..ba1195e --- /dev/null +++ b/skills/pillar-content-architecture/references/cluster-planning-patterns.md @@ -0,0 +1,108 @@ +# Cluster planning patterns + +Facet sourcing methods, sequencing patterns, heterogeneity check. + +--- + +## Facet sourcing methods + +A pillar's cluster is built from 8 to 15 facets. Source them deliberately rather than from the writer's imagination. + +### Method 1: keyword research expansion + +Start with the pillar keyword. Pull the long-tail variations from keyword tools (Ahrefs, Semrush, GSC, dataForSEO). Filter by intent: each cluster facet should have its own SERP intent and dominant format. Variations that share intent with the pillar are not separate facets; they belong inside the pillar itself. + +### Method 2: "people also ask" extraction + +Pull the PAA box for the pillar keyword and 3 to 5 supporting keywords. Each unique question is a candidate cluster facet. PAA is the cleanest signal of what readers actually ask in this topic space. + +### Method 3: top-ranking competitor outline mining + +Pull the top 5 SERP results for the pillar keyword. Extract H2 sections from each. Cluster the H2s across the 5 competitors; sections that appear in 3+ competitors are facets the topic objectively requires. Sections unique to 1 or 2 competitors may be differentiation opportunities. + +### Method 4: first-party customer questions + +Sales calls, support tickets, customer success notes, sales enablement Q&A. The questions customers actually ask are facets the pillar needs to address even if SERP signal is weak. First-party questions also produce differentiation: questions your customers ask but that competitor content does not address. + +### Method 5: Frase or AirOps SERP analysis + +Frase's entity gap analysis and AirOps' workflow builder both run versions of methods 1 to 3 in software. The output is a candidate facet list with SERP coverage scores. Use the tool output as the starting point; refine with first-party questions (method 4) for differentiation. + +--- + +## Sequencing patterns + +How to ship the hub over time. + +### Pattern A: pillar first, cluster follows + +Ship the pillar as a 3,000 to 5,000 word piece. Over the next 6 to 12 weeks, ship 1 to 2 cluster pieces per week. By month 3, the hub has the pillar plus 8 to 12 clusters and starts compounding. + +**When this works.** Strong editorial team that can ship a pillar quickly. The pillar drives initial rankings; clusters fill in topical depth as they ship. + +**The risk.** Pillar ranks for 6 weeks before the cluster is complete; AI engines see a thin hub and may not return to crawl when clusters land. Mitigated by including cluster placeholders in the pillar with "coming soon" or by pre-publishing cluster stubs. + +### Pattern B: pillar plus first 5 clusters concurrent + +Ship the pillar and the first 5 clusters within the same 4-week window. The hub launches with the link graph already partially formed; rankings start with depth signals already in place. + +**When this works.** Larger team or agency support. The launch produces a more credible hub on day 1. + +**The cost.** Higher up-front investment. The first 5 clusters lock the team's editorial capacity for the launch window. + +### Pattern C: prove with 3 clusters, then commit to pillar + +Ship 3 cluster pieces under a planned-but-not-yet-shipped pillar slot. Measure performance over 8 to 12 weeks. If the clusters draw traffic and the topic shows commercial signal, commit to the pillar. If not, pivot to a different pillar topic without the sunk cost. + +**When this works.** Uncertain topic where the commercial signal needs validation before the pillar investment. Common in agencies running pillars for clients without strong upfront conviction. + +**The discipline.** The 3 clusters must be writeable as standalones during the validation window; they cannot reference the pillar by name yet because it does not exist. Once the pillar ships, retrofit the cluster pieces with pillar callouts and bottom-up links. + +--- + +## Heterogeneity check + +A cluster passes heterogeneity if its facets cover the topic from multiple distinct angles. The check: + +**Categorize each facet** by primary angle: + +- Definition (what is X) +- How-to (how to do X) +- Comparison (X vs Y) +- Examples (5 examples of X, X case studies) +- Mistakes (common X mistakes) +- Costs (how much X costs, X pricing models) +- Alternatives (alternatives to X) +- Best-of (best X tools, top X providers) +- Use cases (when to use X) +- Niche variants (X for [specific audience]) +- Foundational (related concept Y that supports X) +- Advanced (advanced X techniques) + +**The rule.** A 12-cluster hub should have facets across 6+ distinct angles. If 10 of 12 are "how-to," the cluster is homogeneous and the pillar will look like a how-to series rather than a topical authority hub. + +**The fix.** When facet brainstorming over-indexes on one angle, deliberately add 2 to 3 facets from different angles. The "5 examples of X" cluster piece is often the most under-served angle; teams forget to add concrete-example pieces and over-invest in abstract how-tos. + +--- + +## No facet duplication + +Two cluster pieces should not target overlapping queries. The check: + +- For each cluster piece, list the 3 to 5 keywords it would target. +- For each pair of cluster pieces, check whether their keyword lists overlap by more than 30%. +- Overlapping clusters compete for the same SERP and self-cannibalize. Consolidate to one piece. + +**The most common duplication.** "What is X" and "X explained" and "X definition" are the same facet. Pick one slug and one focus; do not split the foundational definition across three pieces. + +--- + +## When the cluster is too big + +A planned cluster with 25+ pieces is over-built. The hub becomes unmanageable: maintenance burden too high, link graph too dense to audit, reader navigation confusing. + +**Fix 1.** Split into two pillars under a parent pillar. The original pillar covers the broadest topic; sub-pillars cover major sub-territories with their own clusters. Three-level hierarchy is rare but valid for very broad topics. + +**Fix 2.** Trim to the 12 most-impactful facets. Rank facets by combined search volume + commercial relevance + heterogeneity contribution; keep the top 12; archive the rest as future-cluster candidates. + +The 12-cluster sweet spot is empirical. Below 8, the hub looks thin; above 15, maintenance overhead kicks in; 10 to 12 is the band where most healthy hubs sit. diff --git a/skills/pillar-content-architecture/references/common-pillar-failures.md b/skills/pillar-content-architecture/references/common-pillar-failures.md new file mode 100644 index 0000000..9ec094c --- /dev/null +++ b/skills/pillar-content-architecture/references/common-pillar-failures.md @@ -0,0 +1,150 @@ +# Common pillar failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "We have 80 blog posts but no rankings" + +**Symptom.** The team has been publishing for 2+ years; 80 pieces shipped; organic traffic is flat or declining. + +**Diagnosis.** Orphan content; no hub architecture. 80 disconnected pieces produce no topical authority signal regardless of individual quality. + +**Fix.** Audit the 80 pieces. Group by topic. For each major topic group, identify or build a pillar; refactor the existing pieces into clusters by adding pillar callouts and bottom-up links. Some pieces will not fit and become standalone-by-design; some will need consolidation. + +The expected outcome: 4 to 6 hubs, each with a pillar plus 8 to 12 clusters; 15 to 20 standalones; the rest pruned. See `pillar-cluster-decision.md`. + +--- + +## "Our 8,000-word pillar does not rank" + +**Symptom.** Team invested in a long, comprehensive pillar; 6 months in, position 23 on the primary keyword. + +**Diagnosis.** Comprehensive but no cluster support; the pillar is a long article without a hub. Length without architectural support does not signal authority. + +**Fix.** Build the cluster. Plan 10 to 12 cluster pieces under the pillar; ship 3 to 5 in the next 8 weeks; complete the cluster within 6 months. Update the pillar with internal-link callouts to each cluster as they ship. See `cluster-planning-patterns.md`. + +The expected outcome: ranking improves over 3 to 6 months as the cluster matures. The pillar that did not rank standalone will rank as the hub forms. + +--- + +## "We launched the pillar, never built the cluster" + +**Symptom.** Pillar shipped 8 months ago; team's editorial focus shifted; the planned cluster never landed. Pillar has 2 supporting pieces shipped haphazardly. + +**Diagnosis.** Architecture half-built. The 2 supporting pieces are functioning as orphans because the hub is not formed; the pillar gets minimal compounding. + +**Fix.** Either commit to completing the cluster (8 to 10 more pieces over 4 to 6 months) or prune the hub. Half-built hubs are worse than no hub; commit or unwind. If completing, prioritize facets the team can ship within 12 weeks. + +--- + +## "Cluster pieces do not link to the pillar" + +**Symptom.** Hub has pillar plus 12 clusters; pillar links to all clusters; only 4 of 12 clusters link back to the pillar. + +**Diagnosis.** Top-down link graph but no bottom-up. The pillar does not compound. Cluster pieces have not been required to include pillar callouts. + +**Fix.** Audit each cluster; add pillar callouts in the first 200 words and the closing of any cluster that lacks them. Update the brief template to require both pillar callouts on every future cluster piece. See `internal-linking-architecture.md`. + +--- + +## "Two cluster pieces target the same keyword" + +**Symptom.** Cluster includes "what is a feature flag" and "feature flags explained." Both rank position 8 to 12 alternately; neither breaks into the top 5. + +**Diagnosis.** Self-cannibalization. Two pieces competing for the same SERP; PageRank splits across two URLs; neither piece gets enough authority to rank top 5. + +**Fix.** Consolidate. Pick the stronger piece (higher current rank, more inbound links, longer URL history). 301 redirect the weaker piece to the stronger one. Merge any unique content from the weaker into the stronger. Update the linking inventory. + +--- + +## "Pillar URL is /blog/the-ultimate-guide-to..." + +**Symptom.** The pillar lives at `/blog/the-ultimate-guide-to-feature-flag-rollout-strategies/` because the CMS routes everything under `/blog/`. + +**Diagnosis.** Losing the URL hub signal. Crawlers cannot infer hub topology from the URL; readers cannot tell from the URL that this is a pillar. + +**Fix.** Migrate to `/feature-flag-rollout/` for the pillar; cluster pieces to `/feature-flag-rollout/[slug]/`. 301 redirect old URLs. Take a short-term ranking hit; gain long-term hub-signal clarity. See `url-structure-patterns.md`. + +The migration is not always worth it. If the pillar is small or the brand's overall content investment is modest, the cost may exceed the benefit. Score against the hub's commercial value. + +--- + +## "Our pillar is 12 sections of 'what is X'" + +**Symptom.** Pillar covers the topic comprehensively in length but every H2 is a definitional question. "What is X." "What does X do." "What are the parts of X." 12 variations of the same angle. + +**Diagnosis.** Facet homogeneity. The pillar covers one angle 12 ways instead of 12 distinct angles. + +**Fix.** Rewrite the pillar's outline using the heterogeneity check (definition, how-to, comparison, examples, mistakes, costs, alternatives, etc.). Replace 8 of the 12 definitional sections with sections covering different angles. See `cluster-planning-patterns.md`. + +--- + +## "We cannot tell which piece to refresh first" + +**Symptom.** Hub has 14 pieces; team knows refresh is needed; cannot prioritize where to start. + +**Diagnosis.** No maintenance ownership; no signals being tracked. Without per-piece performance data, refresh prioritization is guesswork. + +**Fix.** Assign a hub owner (see `content-refresh-patterns.md`). Track 4 metrics per piece: organic traffic, primary-keyword rank, AI citation count if measurable, last-updated date. Prioritize refresh on pieces with declining traffic, slipping ranks, or oldest update dates. The metrics make the prioritization mechanical. + +--- + +## "Pillar ranks but does not get cited by AI engines" + +**Symptom.** Pillar ranks position 4 on Google; brand mention rate from Profound is unchanged after the pillar shipped. + +**Diagnosis.** Missing AEO/GEO signals. Pillar may have no TL;DR, no answer paragraphs under H2s, no FAQ schema, vague statistics, no named experts. + +**Fix.** Audit the pillar against the AEO/GEO signals checklist (see `topical-authority-signals.md`). Add a 150 to 250 word TL;DR at the top. Add 40 to 60 word answer paragraphs under each H2. Mark FAQ section with FAQPage schema. Replace vague statistics with specific numbers and cited sources. Add named experts where the topic supports them. + +The AEO/GEO refresh is faster than the SEO refresh; expect citation improvement within 4 to 8 weeks of changes propagating. + +--- + +## "Hub launched 3 years ago; nobody owns it now" + +**Symptom.** Hub built by a content lead who left 18 months ago. No formal owner since. Performance has degraded; nobody noticed. + +**Diagnosis.** Lifecycle ownership gap. The "set and forget" failure mode. + +**Fix.** Assign a new owner. Allocate 1 to 2 weeks of editorial time for an emergency refresh: re-validate the SERP, update statistics, prune dead sections, refresh internal links. Set the annual refresh cadence going forward; track ownership renewal in the hub's planning doc. See `content-refresh-patterns.md`. + +Some hubs at this stage are unrecoverable. If the SERP has shifted enough that the original architecture no longer fits, restructure rather than refresh; treat as a year-5+ lifecycle event. + +--- + +## "We have 25 clusters and it is chaos" + +**Symptom.** Hub started at 12 clusters; expanded over 3 years to 25; the linking inventory is unmanageable; new pieces tangle with old pieces; readers cannot find what they need. + +**Diagnosis.** Over-built. The cluster expanded beyond the manageable sweet spot. + +**Fix.** Prune. Apply the cluster pruning criteria (see `content-refresh-patterns.md`): clusters that have not ranked in top 30 after 12 months, clusters with zero search volume, clusters that duplicate other clusters. Aim to trim back to 12 to 15 active clusters; archive the rest with redirects. + +Alternative: split into two pillars under a parent topic. Rare; valid only for genuinely broad topics. + +--- + +## "We did all the SEO work but the AI engines do not cite us" + +**Symptom.** Pillar ranks well; clusters rank well; brand mention rate from Profound is flat. AI engines cite competitors instead. + +**Diagnosis.** Could be either: + +- The hub is structurally fine for SEO but missing AEO/GEO signals (see "pillar ranks but does not get cited" above). +- The hub is missing distinctive POV. AI engines preferentially cite content with attributable claims; content that reads as SEO consensus does not get cited even when it ranks. + +**Fix.** Audit each pillar and high-traffic cluster for distinctive claims. Add at least one strong POV per piece: a position the team is willing to defend, a recommendation that is not "it depends," a specific claim with named experts and statistics behind it. Bland comprehensive content does not get cited; opinionated comprehensive content does. + +--- + +## "We have a hub but conversions are flat" + +**Symptom.** Hub drives traffic, ranks well, gets cited; trial signups attributable to the hub are flat. + +**Diagnosis.** Topical authority is working; commercial conversion is not. The hub's content does not connect cleanly to the buyer journey. + +**Fix.** Audit the pillar and clusters for commercial CTAs. Each cluster should have a clear next step that is NOT just "read another cluster." Trial signup, demo request, content download, newsletter subscription. The hub is producing the audience; the conversion path needs separate design work. + +This failure is outside this skill's scope to fully solve; pair with `landing-page-copy` for conversion-focused next-step pages and `content-strategy` for funnel-aware content planning. diff --git a/skills/pillar-content-architecture/references/content-refresh-patterns.md b/skills/pillar-content-architecture/references/content-refresh-patterns.md new file mode 100644 index 0000000..3517077 --- /dev/null +++ b/skills/pillar-content-architecture/references/content-refresh-patterns.md @@ -0,0 +1,164 @@ +# Content refresh patterns + +Annual pillar refresh checklist. Triggered cluster refresh signals. Cluster expansion patterns. Cluster pruning criteria. Hub lifecycle (5 to 7 year horizon). + +--- + +## Why refresh matters + +Hubs decay. Statistics go stale; SERPs shift; new facets emerge; existing pieces drift from current best practice. A hub that ranks at year 1 often falls to position 12 by year 3 if nobody refreshes it. + +The discipline is built into the architecture: refresh is not an afterthought; it is a budgeted activity. + +--- + +## Annual pillar refresh checklist + +Run every 12 months on each pillar. Allocate 1 to 2 weeks of editorial time per pillar. + +### Step 1: re-validate the SERP + +Pull the current SERP top 10 for the pillar's primary keyword. Compare to the last refresh's top 10. + +- Are new competitors in the top 10? What are they covering that you are not? +- Have existing competitors updated their pillars? What new sections did they add? +- Has the SERP intent shifted (e.g., from informational to commercial-investigation)? + +### Step 2: update statistics + +Find every numeric claim in the pillar. Verify each is still accurate; replace stale numbers with current ones; cite the new source. + +**Common stale numbers.** Industry statistics that were "as of 2023" and now are 2 years old. Pricing references that have shifted. Tool capabilities that have evolved. + +### Step 3: add new sections for emerged facets + +Did the topic surface new facets in the last 12 months? Add H2 sections covering them. Each new section should be 300 to 500 words; if it grows beyond 700, promote it to a new cluster piece and reduce the pillar section to a callout. + +### Step 4: prune sections that no longer matter + +Did old sections become irrelevant? Maybe a tool you covered shut down; maybe a method you described was deprecated. Cut or significantly trim those sections. Pillar bloat from un-pruned content is the most common pillar-decay symptom. + +### Step 5: refresh internal-link callouts to clusters + +The cluster has likely grown since last refresh. Add callouts to any new cluster pieces that did not exist before. Verify all existing callouts still link to live cluster URLs. + +### Step 6: update the TL;DR + +The TL;DR captures the pillar's argument as of the refresh date. Revise to reflect any structural changes: new facets, removed sections, shifted POV. + +### Step 7: bump the last-updated date + +Set the publish-modified date to the refresh completion date. The freshness signal matters; do not skip it. + +### Step 8: re-submit to search engines + +Submit the updated pillar URL to Google Search Console for re-crawl. Some teams also ping AI engine indexing endpoints (Perplexity, Bing for Copilot) where available. + +--- + +## Triggered cluster refresh signals + +Clusters do not need annual refresh; they need triggered refresh when specific signals appear. + +### Trigger 1: keyword performance drops + +The cluster's primary keyword falls 5+ positions in 30 days. The drop is the signal; pull the SERP, identify what is now ranking ahead, and update the cluster to compete. + +### Trigger 2: new sub-topic emerges + +Within the cluster's facet, a new sub-topic appeared (new tool launched, new technique published, new regulation issued). Update the cluster to reference the new sub-topic. + +### Trigger 3: cluster's links go stale + +The quarterly link audit (see `internal-linking-architecture.md`) finds broken outbound links from the cluster. Update the cluster with new links. + +### Trigger 4: AI citation drops + +The cluster was being cited by AI engines and the citation count drops. Check whether content drifted, whether new entities should be added, whether the answer paragraphs need tightening. AI citation drops are slower-moving than ranking drops; act on month-over-month trends, not week-over-week. + +### Trigger 5: customer feedback surfaces a gap + +A sales rep, support agent, or customer success manager flags that the cluster does not cover a question customers actually ask. Add the section. + +--- + +## Cluster expansion patterns + +A hub at year 1 might have 8 clusters. Year 3 could have 18. Expansion happens deliberately, not opportunistically. + +### When to expand + +- A new facet emerges and customer questions confirm demand. +- Competitor analysis shows a facet your hub does not cover. +- Keyword research surfaces new long-tail variations with traffic. +- AI citation patterns show queries your hub does not address. + +### When not to expand + +- Tempting facet but no customer demand. Adds maintenance burden without driving traffic. +- Facet already covered by another piece on the site outside the hub. Either move that piece into the hub or update its links. +- Facet is too narrow (sub-100 monthly searches with no commercial signal). Add as a section to an existing cluster, not as its own cluster. + +### Expansion cap + +Max 20 clusters per pillar. Above that, the hub becomes unmanageable. If the topic genuinely supports 25+ facets, split into two pillars under a parent topic (rare; valid for very broad topics). + +--- + +## Cluster pruning criteria + +Some clusters should die. Pruning is hygiene, not failure. + +### Prune when + +- Cluster has not ranked in top 30 after 12 months despite refresh attempts. +- Cluster's keyword has gone to zero search volume. +- Cluster duplicates another cluster (consolidate). +- Cluster covers a tool, technique, or topic that no longer exists. + +### How to prune + +- 301 redirect the URL to the most-relevant remaining cluster, or to the pillar. +- Remove links from the pillar and other clusters to the pruned URL. +- Update the linking inventory. + +### What not to do + +- Do not delete the URL without redirecting; 404s waste any acquired authority. +- Do not redirect to the homepage; redirect to the most topically-relevant alternative. + +--- + +## Hub lifecycle (5 to 7 year horizon) + +Hubs themselves have lifespans. After 5 to 7 years, the topic landscape often shifts enough that wholesale restructuring becomes appropriate. + +### Signs the hub needs restructuring (vs annual refresh) + +- The pillar's primary keyword has shifted intent (the SERP is now showing a different content type). +- Competitors have rebuilt their hubs around a different angle that better matches current reader needs. +- The cluster has grown unwieldy (25+ pieces) and the topical organization no longer makes sense. +- AI citation patterns suggest readers are asking questions the original hub structure cannot answer. + +### Restructuring approach + +- Treat the restructuring as a new hub launch. Plan the new pillar and cluster shape first. +- 301 redirect old pillar and cluster URLs to new equivalents where possible. +- Archive content that does not fit the new structure rather than force-fitting. +- Communicate the change in a release-note-style post linked from both old and new URLs during the transition. + +The 5-to-7 year cycle is empirical. Some hubs last longer (foundational topics like "what is SEO"); some need restructuring sooner (fast-moving topics like "AI search"). Ownership tracks the lifecycle; the durable hub owner is the one who decides when to restructure. + +--- + +## Maintenance ownership + +The pillar owner is named and durable. Common patterns: + +- **Single editor.** One person owns the hub for a 12-month commitment. Renewed annually. +- **Editor + SEO partner.** Editor owns content; SEO partner owns rankings and link audits. +- **Cross-functional team.** Editor, SEO, product marketing rotate quarterly reviews. Works for large teams; falls apart in small teams (rotation diffuses ownership). + +The "set and forget" failure mode happens when ownership dissolves. The team that launched the hub disbanded, was reorganized, or moved on; nobody picks up maintenance. Six quarters later, the hub has decayed and recovery costs more than the original launch. + +The fix. Assign a durable owner before the hub launches. Renew the assignment annually. Track the owner's continued ownership in the hub's planning doc; surface in quarterly reviews. diff --git a/skills/pillar-content-architecture/references/internal-linking-architecture.md b/skills/pillar-content-architecture/references/internal-linking-architecture.md new file mode 100644 index 0000000..805f61f --- /dev/null +++ b/skills/pillar-content-architecture/references/internal-linking-architecture.md @@ -0,0 +1,100 @@ +# Internal linking architecture + +Top-down, bottom-up, lateral linking patterns. Anchor text discipline. The linking inventory pattern. Quarterly link audit checklist. + +--- + +## The three link directions + +A hub's link graph has three directions; all three need discipline. + +### Top-down: pillar to cluster + +The pillar links out to each cluster piece via contextual anchors woven into the pillar's body. The reader is reading the section on, for example, "kill switches"; that section includes a contextual link to the cluster piece on kill switches. + +**Pattern.** "Most rollouts include a kill switch as a final safety net. For the full pattern including code-level implementations, see [our guide on kill switch design](/feature-flag-rollout/kill-switches/)." + +**Anti-pattern.** A "Related reading" footer at the bottom of the pillar listing 12 cluster links. Footer links pass less topical signal and read as decorative; contextual body links read as load-bearing. + +**Frequency.** One link per cluster from within the pillar. Two links to the same cluster from the pillar is fine if the cluster covers two distinct sections; three links to the same cluster suggests the pillar should reference the cluster more selectively. + +### Bottom-up: cluster to pillar + +Every cluster piece links up to the pillar at least twice. First in the introduction (within the first 200 words); second in the closing. + +**Pattern in introduction.** "This piece covers kill switches in feature flag rollouts. For the broader context on rollout strategies, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +**Pattern in closing.** "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns, or jump to [percentage rollouts](/feature-flag-rollout/percentage-rollouts/)." + +**Why two.** First link tells crawlers and readers the topical context immediately. Second link captures readers who got value from the cluster piece and want to dig deeper into the hub. + +### Lateral: cluster to cluster + +Selective. When one cluster piece naturally references another, link with descriptive anchor text. Do not force lateral links. + +**Pattern.** A cluster on "percentage rollouts" naturally references "kill switches" when discussing what to do if the rollout shows problems. The lateral link is contextual; the reader is at a moment where the related cluster is actually useful. + +**Anti-pattern.** Every cluster piece links to every other cluster piece. The link graph becomes complete-graph-shaped; anchor text relevance dilutes; PageRank flow is undirected and weaker. + +**Frequency.** 1 to 3 lateral links per cluster piece is typical. Some clusters need zero lateral links; some clusters that sit at the center of a topic naturally connect to 5 sibling clusters. + +--- + +## Anchor text discipline + +Anchor text is the signal that tells search engines what the linked-to page is about. The discipline: + +**Vary the anchor text.** Do not link to the pillar with the exact same phrase every time. Use the pillar's primary keyword, secondary keywords, and natural-language phrases that describe the linked page. + +**Descriptive natural-language anchors.** "See our guide to feature flag rollout strategies" beats "click here to read more." The anchor text should make sense if it is the only thing the reader reads. + +**No over-optimization.** Do not stuff every link with exact-match keywords. Anchor text that varies naturally is what a real authority cluster looks like; uniform exact-match anchors signal manipulation to ranking systems. + +**Brand-mention anchors.** Sometimes the right anchor is the brand name or product name when linking to a product page. "RampStack's experimentation skill" is a brand anchor; "experimentation skills documentation" is a descriptive anchor. Mix both. + +**Common dead anchors.** "Click here," "this article," "read more," "more info." All dead. They pass minimal topical signal and waste the link's potential. + +--- + +## The linking inventory pattern + +Maintain an inventory of every link in the hub. The format depends on the team's tooling. + +**Spreadsheet.** Columns: source page slug, target page slug, anchor text, link section (intro / body / closing / sidebar), link direction (top-down / bottom-up / lateral / external). + +**Notion database.** Same columns as relations, queryable per page or per direction. + +**dbt model with content metadata.** For warehouse-native content tracking; the link graph becomes a queryable table that compounds with other content metrics (rank, citation count, conversion). + +**CMS audit fields.** Some CMSs (Contentful, Sanity, custom WordPress) allow per-page metadata fields. Track outbound links per piece; aggregate at the hub level. + +The inventory enables the quarterly audit; without it, the audit becomes a manual scan that misses things. + +--- + +## Quarterly link audit checklist + +Run every 90 days. Catches the failures that compound silently. + +1. **Broken outbound links.** Crawl every cluster piece for 404s on outbound links. Common cause: cluster piece was renamed or moved without redirect. +2. **Missing bottom-up links.** Every cluster should link to the pillar in intro and closing. Audit checks both. +3. **Missing top-down links.** Pillar should link to every cluster from within the body. Audit checks each cluster has at least one body link from the pillar. +4. **Anchor text drift.** Same anchor text used by 5+ links to the same target reads as over-optimized. Vary by editing 2 to 3 of them. +5. **Dead anchors.** "Click here" or "read more" anchors that crept in during writing. Replace with descriptive anchors. +6. **Lateral over-linking.** Cluster pieces linking to 5+ siblings reads as complete-graph noise. Trim to 2 to 3 most-relevant siblings. +7. **Orphan clusters.** Cluster piece that no other piece links to (besides the pillar). The pillar's top-down link is required; ideally 1 to 2 sibling lateral links also exist. +8. **Stale references.** Cluster pieces that reference statistics, products, or pages that no longer exist. Update the references; refresh the piece if the underlying topic shifted. +9. **New cluster integration.** When a new cluster piece ships, audit confirms it received its top-down link from the pillar AND its bottom-up plus lateral links. New clusters often miss the inbound updates that would prevent orphan status. +10. **Anchor diversity.** Pull the inventory; group anchor texts by target page. If 8 of 10 links to a page use the same anchor, edit 3 to 5 to vary. + +The audit takes 1 to 3 hours per hub. The cost is real but smaller than the cost of letting the link graph decay. + +--- + +## When the link graph is too dense + +Some teams over-link. Every cluster piece has 8 outbound contextual links plus 5 lateral plus 3 external. The reader is bombarded; the anchor text relevance dilutes. + +**Heuristic.** A cluster piece with more than 6 outbound internal links per 1,000 words is over-linked. Trim to the 4 to 6 highest-relevance links. + +The trim improves both reader experience and PageRank concentration. Each remaining link gets more weight; the link graph becomes more legible to crawlers. diff --git a/skills/pillar-content-architecture/references/pillar-cluster-decision.md b/skills/pillar-content-architecture/references/pillar-cluster-decision.md new file mode 100644 index 0000000..a5fe670 --- /dev/null +++ b/skills/pillar-content-architecture/references/pillar-cluster-decision.md @@ -0,0 +1,98 @@ +# Pillar vs cluster vs orphan decision + +The decision tree, worked examples, and the "everything is a pillar" anti-pattern. + +--- + +## The decision tree + +When a new piece is being planned, walk these questions in order. + +**Question 1.** Does this topic have 8 to 15 distinct facets that could each be a separate piece? + +- Yes: this might be a pillar. Continue to question 2. +- No: this is not a pillar. Continue to question 4 to test cluster fit. + +**Question 2.** Is the topic competitive enough to require comprehensive coverage to rank? + +- Yes (top 10 SERP shows long-form pillars from authoritative sources): pillar candidate confirmed. Continue to question 3. +- No (top 10 SERP shows short articles or tools): the topic does not need a pillar. A cluster piece probably suffices. + +**Question 3.** Is the team committed to maintaining this pillar for 3 to 5 years (annual refresh, cluster expansion, ownership)? + +- Yes: ship as pillar. Plan the cluster. +- No: do not start. A pillar without maintenance is worse than no pillar; it ranks for a year, then decays. + +**Question 4.** Is there an existing pillar this piece could connect to as a cluster? + +- Yes: ship as cluster. Specify the pillar callout and the bottom-up link in the brief. +- No: continue to question 5. + +**Question 5.** Is this piece intentionally standalone (release note, customer story, one-off campaign, executive announcement)? + +- Yes: ship as standalone. Standalone-by-design is fine. +- No: this is an accidental orphan. Either build the pillar first, or postpone the piece until a pillar exists, or rescope the piece to fit an existing pillar's cluster. + +--- + +## Worked examples + +### Example 1: "Feature flag rollout strategies" + +A B2B SaaS team is planning a piece on feature flag rollout strategies. + +- 8 to 15 facets? Yes: percentage rollout, ring deployment, canary, blue-green, kill switches, automatic rollbacks, rollout per cohort, rollout by geography, rollout by plan tier, etc. ✓ +- Competitive SERP? Top 10 are long-form articles from LaunchDarkly, Statsig, Optimizely. Pillar candidate confirmed. ✓ +- 3 to 5 year commitment? The team plans to expand the cluster as new patterns emerge. ✓ + +Decision: pillar. Plan 10 to 12 cluster pieces around it. + +### Example 2: "How to set up a Statsig experiment" + +The same team is planning a how-to on Statsig experiment setup. + +- 8 to 15 facets? No. The topic is one task with maybe 5 sub-steps. ✗ +- Existing pillar to connect to? Yes: the team has an "experimentation" pillar. + +Decision: cluster. Pillar callout to "experimentation" pillar; link up in first 200 words and closing. + +### Example 3: "Q3 2026 product release notes" + +The marketing team is planning a quarterly release-notes post. + +- 8 to 15 facets? No. ✗ +- Existing pillar to connect to? Not a topical fit; release notes are a different content type. +- Standalone-by-design? Yes; release notes serve customers tracking the product, not topical authority. + +Decision: standalone. Do not force into a hub; serve the customer tracking purpose. + +### Example 4: "What is a feature flag?" + +A piece on the basic definition. + +- 8 to 15 facets? No. The topic is one definition. ✗ +- Existing pillar to connect to? Yes: the "feature flag rollout strategies" pillar from example 1 needs a "what is a feature flag" cluster piece for the foundational facet. + +Decision: cluster under the feature flag rollout pillar. The pillar gets the cluster it needs; the piece gets the topical context it needs. + +--- + +## The "everything is a pillar" anti-pattern + +The symptom. Every 3,000-word piece on the team's site is called a pillar. The marketing team uses the word loosely; the SEO team uses it strictly; nobody agrees on what makes a pillar. + +The diagnosis. Length is being treated as the pillar criterion. Length does not make a pillar. The architectural role does. A 3,000-word piece with no cluster supporting it is a long article, not a pillar. A 1,500-word piece with 12 cluster pieces linking up to it is closer to a pillar than the 3,000-word standalone, even though the word counts are reversed. + +The fix. Use the word "pillar" precisely. Pillar is a piece that anchors a hub. If there is no hub, there is no pillar. Long articles that are not anchoring hubs are just long articles, and that is fine; they do not need to be promoted to "pillar" to justify the investment. + +The diagnostic question. "What pieces link up to this pillar?" If the answer is "none yet" or "we are planning to add some," the pillar is not yet a pillar. It is a planned pillar that becomes a real pillar when the cluster ships. + +--- + +## When the decision is hard + +**The "almost a cluster" case.** A piece is 1,800 words, covers a specific facet of an existing pillar, and would link up to the pillar. Sounds like a cluster. But the piece also stands alone for non-hub queries. Decision: ship as cluster. The pillar callout is cheap; the topical compounding is real. The "standalone-by-design" exception is for pieces that have a different purpose (release notes, customer stories), not for pieces that happen to be readable alone. + +**The "almost a pillar" case.** A piece is 3,500 words, covers a topic with 6 facets (not 8 to 15), and the SERP for the topic is moderately competitive. Decision: ship as a long cluster piece under a broader pillar, or postpone until the topic surfaces more facets. Forcing 3,500 words into a 6-facet topic creates the "pillar with 12 sections of 'what is X'" failure mode. + +**The "we already have 5 standalone pieces on this topic" case.** No pillar exists; 5 orphans cover related facets. Decision: build the pillar, then refactor the 5 orphans into clusters by adding pillar callouts and bottom-up links. The hub is being created from existing content rather than from scratch; this is faster than starting over and works well when the orphans are already decent. diff --git a/skills/pillar-content-architecture/references/pillar-page-anatomy.md b/skills/pillar-content-architecture/references/pillar-page-anatomy.md new file mode 100644 index 0000000..c3ba778 --- /dev/null +++ b/skills/pillar-content-architecture/references/pillar-page-anatomy.md @@ -0,0 +1,144 @@ +# Pillar page anatomy + +Section-by-section anatomy. TL;DR placement and length. FAQ schema. Internal-link callout placement. Schema markup choices. Length calibration. + +--- + +## Section-by-section structure + +A pillar page does specific work across a recognizable set of sections. + +### Hero (first 200 words) + +Defines the topic, signals scope, establishes authority quickly. + +- **Title.** Includes the primary keyword. Reads as comprehensive ("The complete guide to feature flag rollout strategies"). +- **Subhead.** One sentence promising specific value to a specific audience. +- **Author / publish / update line.** Author name with link to bio (E-E-A-T signal); last-updated date (freshness signal). + +### TL;DR or executive summary (150 to 250 words) + +The most important section for AI citation. AI engines extract this verbatim and use it as the canonical answer when users ask the topic question. + +**What goes in.** A self-contained summary of the pillar's argument. Read alone, it answers the topic. Read in context, it sets up the comprehensive body. + +**What does not go in.** Marketing fluff. Throat-clearing meta-commentary that announces what the page is about to do instead of doing it. Cut it. + +**Format.** Either a single dense paragraph (150 to 250 words) or 5 to 7 bullet points. Both work; bullets often extract more cleanly to AI engines. + +### Table of contents + +Auto-generated from H2 and H3 structure. Anchors to each section. Helps readers scan; helps crawlers see structure. + +### Comprehensive body (the bulk of the pillar) + +12 to 20 H2 sections covering the topic's major facets. The body is a guided tour with depth links, not a comprehensive treatment of every facet. + +**Per H2 section.** + +- **Featured snippet bait.** A 40 to 60 word answer paragraph immediately following the H2 question. AI engines often quote this as the citation. +- **Body of the section.** 200 to 600 words developing the answer with examples, formulas, edge cases. +- **Cluster link callout.** When the section maps to a cluster piece, link to the cluster contextually within the body. "For the full pattern including [specific facet], see our [cluster piece guide]." + +### Use cases or examples + +Anchor the abstract topic to concrete instances. 3 to 5 worked examples. Each example named, scoped, and referenced in the body. + +### Common mistakes / FAQ + +Structured Q&A. Each Q is a real question; each A is a 40 to 80 word answer. + +**Pair with FAQPage schema.** Mark the Q&A section with FAQPage structured data. AI engines (Perplexity especially) cite FAQPage content heavily. + +**Anti-pattern.** "Frequently asked questions" that nobody actually asks. The FAQ should source from real customer questions, sales-call transcripts, support tickets. Fabricated FAQs are obvious to readers and to AI engines. + +### Closing or next steps + +Directs the reader into the cluster. "If you are starting fresh, read [intro cluster piece]. If you have rollouts running and need to harden them, read [advanced cluster piece]." + +The closing is also where the second bottom-up pillar reinforcement lands for cluster pieces; for the pillar itself, the closing names the next-best clusters by reader intent. + +--- + +## TL;DR placement and length + +Place immediately after the hero, before the table of contents. The reader sees TL;DR within the first scroll. AI engines scrape from the top of the page; TL;DR placed early gets prioritized. + +**150 words minimum.** Below 150, the TL;DR is too thin to serve as a citation candidate. + +**250 words maximum.** Above 250, the TL;DR loses its punch and starts duplicating the body. + +**Self-contained.** A reader who reads only the TL;DR should walk away with the topic's core. No throat-clearing or hedging; the TL;DR IS the answer. + +--- + +## FAQ schema + +The FAQ section gets FAQPage schema. The format: + +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is a feature flag kill switch?", + "acceptedAnswer": { + "@type": "Answer", + "text": "A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. Kill switches are configured at deploy time and remain available throughout the feature's lifecycle." + } + } + ] +} +``` + +**Common mistake.** FAQPage schema on questions that are not real FAQs. Schema markup that misrepresents page content can trigger manual penalties; mark only genuine FAQ sections. + +--- + +## Internal-link callout placement + +The pillar links to cluster pieces from within the body, not from a "related reading" footer. + +**Pattern.** Inside the H2 section that maps to a cluster, place one contextual link to the cluster piece. Position the link at the moment in the section where the reader's curiosity peaks: typically after the section has set up the question and before the answer goes deep. + +**Example.** In the H2 "What is a kill switch?" section, after the 40 to 60 word answer paragraph, link to the cluster piece on kill switches with the phrase "For the full pattern including code-level implementations, see our [kill switch design guide]." + +**Frequency.** One link per cluster from the pillar. Two if the cluster maps to two distinct sections of the pillar. Avoid more than two; the second link is the reinforcement, not a third or fourth. + +--- + +## Schema markup choices + +The pillar's primary schema depends on intent. + +**Article schema.** Default for most pillars. Marks the page as long-form editorial content. + +**HowTo schema.** When the pillar is a step-by-step guide ("how to launch a feature flag rollout"). HowTo gives Google more structured data to render in SERPs. + +**FAQPage schema.** Always pair with the FAQ section, not the pillar overall. + +**BreadcrumbList schema.** Always include for hub navigation context. + +**Author schema.** Embed Person schema for the author with credentials, bio link, and same-as references to LinkedIn or X. E-E-A-T signal. + +--- + +## Length calibration + +3,000 to 5,000 words is the typical pillar range. Calibrate to the SERP, not to a quota. + +**SERP top 10 average word count tells you the band.** Pull the top 10; tag word counts; aim for the top 3 average. If the top 3 average 4,200 words, your pillar should target 4,000 to 4,500. + +**The depth-vs-length tradeoff.** Pillar quality is comprehensiveness AND depth, not just length. A 6,000-word pillar that covers 3 facets in massive depth is worse than a 4,000-word pillar that covers 12 facets at appropriate depth. Length without breadth is not a pillar; it is a long article. + +**The cluster offload.** Each cluster piece reduces the depth required in the pillar's corresponding section. If kill switches has its own cluster piece, the pillar's kill-switches section can be 300 words pointing to the cluster, not 1,200 words duplicating the cluster. The cluster offload is what keeps the pillar at the right length. + +--- + +## Updates and freshness signals + +The pillar's "last updated" date is a freshness signal. Update it whenever you make material changes (statistics refreshed, new section added, cluster expanded). Do not update it for cosmetic edits; spurious freshness signals are noticed by ranking systems. + +The annual pillar refresh (see `content-refresh-patterns.md`) is the discipline that produces honest freshness signals. diff --git a/skills/pillar-content-architecture/references/topic-selection-criteria.md b/skills/pillar-content-architecture/references/topic-selection-criteria.md new file mode 100644 index 0000000..f5505a5 --- /dev/null +++ b/skills/pillar-content-architecture/references/topic-selection-criteria.md @@ -0,0 +1,104 @@ +# Topic selection criteria + +The five-criterion framework for pillar topic selection, with worked examples across business types. + +--- + +## The five criteria + +A topic earns pillar status only when all five hold. Failing one is a hard signal to stop. + +### 1. Search volume justifies the investment + +The pillar will cost 3 to 6 weeks of editorial effort and 8 to 15 cluster pieces. The topic needs enough monthly search demand to repay the investment over a 3 to 5 year horizon. + +**Heuristic.** Pillar topic with combined volume across the keyword cluster of 1,000+ monthly searches usually justifies a pillar. Below 500 combined monthly searches, the topic is probably a single cluster piece under a broader pillar, not its own pillar. + +**Exception.** High-commercial-value topics with low volume (enterprise B2B SaaS niches, expensive professional services) can justify pillars at lower volumes because each ranking visit is worth more. + +### 2. Topic has natural facets + +A pillar covers a topic with internal structure. The team should be able to brainstorm 8 to 15 distinct subtopics, each capable of being a standalone cluster piece. + +**The test.** Spend 30 minutes listing facets. If the list reaches 12 organically, the topic has the structure. If the list stalls at 5, the topic is a cluster, not a pillar. + +**Common false positive.** Listing 12 keyword variations of "what is X" is not 12 facets. It is one facet (definition) said 12 ways. True facets are dimensionally different (definition, how-to, comparison, mistakes, costs, alternatives, examples, case studies). + +### 3. Commercial relevance + +The topic connects to the business model. A pillar without commercial signal is content marketing for content marketing's sake. + +**The test.** Can you draw a line from "reader lands on this pillar" to "reader becomes customer or contributor of customer-related signal"? If yes, the topic is commercially relevant. If the line requires three hops and a leap of faith, the topic is too far from the business. + +### 4. Competitive feasibility + +Top 10 SERP for the pillar keyword is achievable for the brand at its current authority. If the SERP is dominated by Wikipedia, government sites, and global household-name brands, your pillar will rank position 47 no matter how good it is. + +**The test.** Pull the SERP top 10. Tag each result by domain authority and commercial profile. If the top 10 are all DR 80+ household names and your brand is DR 35, do not start the pillar. Either pick a less-competitive long-tail variant or build authority on adjacent topics first. + +### 5. Editorial commitment + +The team will maintain the pillar for 3 to 5 years: annual refresh, cluster expansion, ownership through team changes. + +**The test.** Name the durable owner. If the owner is "the marketing team" instead of a specific person with a 12-month commitment, the pillar will not get maintained. Pillars without owners decay; the decay is invisible until the traffic drop is unrecoverable. + +--- + +## Worked example: B2B SaaS + +The brand is a feature-flag platform competitor (DR 45). Considering a pillar on "feature flag rollout strategies." + +- Volume: 2,400 combined monthly searches across the cluster. ✓ +- Facets: 14 listed (rollout strategies, naming conventions, lifecycle, governance, kill switches, technical debt, multi-environment, A/B testing integration, etc.). ✓ +- Commercial: pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes LaunchDarkly (DR 78), Statsig (DR 65), and several DR 60+ blogs. Tight but not impossible at DR 45 with strong cluster support. ✓ (with effort) +- Commitment: PM and content lead jointly own; renewal review every 12 months. ✓ + +Decision: pillar candidate. Plan a 12-cluster hub. + +--- + +## Worked example: ecommerce + +A direct-to-consumer skincare brand (DR 38). Considering a pillar on "retinol routine for beginners." + +- Volume: 8,500 combined monthly searches. ✓ +- Facets: 11 listed (intro, how to start, percentages, frequency, side effects, sun pairing, age considerations, mixing with other actives, sensitive-skin variant, pregnancy considerations, troubleshooting). ✓ +- Commercial: high; pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes The Ordinary blog, Paula's Choice, Reddit threads, dermatology sites. Mixed authority; achievable at DR 38 with cluster depth and original photography. ✓ +- Commitment: brand educator owns; refresh every 12 months. ✓ + +Decision: pillar. Plan a 10 to 12 cluster hub. + +--- + +## Worked example: services business + +A regional accounting firm (DR 28). Considering a pillar on "small business tax preparation." + +- Volume: 1,200 combined monthly searches. ✓ +- Facets: 12 listed (deductions, quarterly estimates, software comparison, when to hire vs DIY, common mistakes, audit risk, retirement contributions, payroll tax, sales tax, state-specific notes, multi-state operations, business structure choice). ✓ +- Commercial: very high; readers are local prospective clients. ✓ +- Competitive: top 10 includes Intuit, H&R Block, IRS itself, AICPA. Hard at DR 28. ✗ + +Decision: do not pursue this pillar. Instead, scope to a niche the brand can win: "small business tax preparation in [city]" with a pillar focused on the local-business audience and local SEO signals where DR matters less. + +--- + +## Worked example: media or publishing + +A career-focused publication (DR 55). Considering a pillar on "remote work productivity." + +- Volume: high. ✓ +- Facets: easily 15+. ✓ +- Commercial: ad-driven; pillar traffic monetizes through display and email signups. Indirect but real. ✓ +- Competitive: top 10 is moderately authoritative; achievable. ✓ +- Commitment: senior editor owns. ✓ + +Decision: pillar. Note the commercial-signal pattern is different from B2B SaaS or ecommerce; the funnel is impressions to audience growth rather than impressions to qualified lead. Same architecture, different success metrics. + +--- + +## When to walk away + +If three or more criteria fail, walk away from the pillar idea. If exactly one criterion fails (usually competitive feasibility), see whether a long-tail variant of the topic resolves the failed criterion. The "long-tail variant pivot" is the most common save: instead of "feature flags" (DR 78 incumbents), pick "feature flags for [niche]" (DR 50 incumbents) where the brand can compete. diff --git a/skills/pillar-content-architecture/references/topical-authority-signals.md b/skills/pillar-content-architecture/references/topical-authority-signals.md new file mode 100644 index 0000000..547a43d --- /dev/null +++ b/skills/pillar-content-architecture/references/topical-authority-signals.md @@ -0,0 +1,126 @@ +# Topical authority signals + +SEO and AEO/GEO signals at the hub level. Two-engine optimization framing. + +--- + +## Why hubs produce stronger signals than orphans + +Search engines and AI engines both read internal-link graphs and content patterns to infer topical authority. A hub with 12 connected pieces produces signals an orphan set cannot match: + +- **Density of internal links on the topic.** PageRank flows within the hub; pages reinforce each other. +- **Comprehensive entity coverage across pieces.** The hub mentions more named tools, methods, experts, and statistics than any single piece could. +- **Repeated topical signal at scale.** Multiple pieces with overlapping topical vocabulary, distinct facets, consistent structure. +- **Crawl-rate compounding.** Search engines crawl high-link-density clusters more frequently; AI engines re-index hubs more aggressively. + +Same total content volume; different architectural outcome. 12 orphans on the same topic produce scattered, weaker signals than a 12-piece hub. + +--- + +## SEO signals at the hub level + +### Internal-link graph density + +Google's PageRank algorithm flows authority through internal links. A pillar with 12 cluster pieces linking back to it concentrates PageRank on the pillar; the pillar in turn passes authority to clusters via top-down links. The graph shape compounds. + +**Heuristic.** Compare PageRank on a pillar before and after the cluster ships. Most teams see ranking improvements on the pillar within 3 to 6 months as the cluster matures. + +### Comprehensive entity coverage + +The hub mentions more named entities than any single page could: tools, methods, experts, datasets, frameworks. Search engines extract entity graphs at crawl time; comprehensive coverage signals topical depth. + +**The discipline.** Each piece in the hub mentions the topic's required entities (entities the SERP top 10 share) and the gap entities (entities only 1 or 2 SERP results mention). The hub-level entity graph is the union across all pieces. + +### URL structure clarity + +The `/topic/cluster-piece/` pattern signals topical grouping. Crawlers follow the URL hierarchy and infer the hub structure even before parsing internal links. + +### Breadcrumb hierarchy + +BreadcrumbList schema tells crawlers the hub structure explicitly. Some SERPs surface breadcrumb URLs as rich-result enhancements. + +### Schema markup at scale + +Article, HowTo, FAQPage, BreadcrumbList schema across the hub. Each schema type passes additional structured data to crawlers. The hub is structured for extraction in a way that orphan content rarely is. + +### E-E-A-T signals + +Experience, Expertise, Authoritativeness, Trustworthiness. Google's quality framework. Hub-level E-E-A-T comes from: + +- Author credentials displayed on every piece (with Person schema) +- Expertise demonstrated through depth and accuracy +- Authoritativeness signaled by entity coverage and citations +- Trustworthiness signaled by clear authorship, last-updated dates, and corrections to prior work when relevant + +E-E-A-T is not a discrete signal; it is the aggregate of many small signals. Hubs accumulate E-E-A-T faster than orphans because the signals compound across pieces. + +--- + +## AEO and GEO signals at the hub level + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) cite content based on different patterns than traditional search ranking. Hubs serve AI engines as well as search engines if the right signals are present. + +### Answer-paragraph format under H2 headings + +40 to 60 word self-contained answers immediately following H2 questions. AI engines extract these as citation candidates. The pattern repeats across pillar and clusters; the hub becomes a structured set of citation-ready answers. + +### TL;DR section on pillars + +The pillar's TL;DR (150 to 250 words) is the most-cited section by AI engines. Place it at the top, make it self-contained, write it as the canonical summary. + +### FAQPage schema + +AI engines (Perplexity especially) heavily cite FAQPage-marked content. Pair every pillar's FAQ section with FAQPage schema. Cluster pieces with genuine FAQs also benefit. + +### Specific statistics with cited sources + +"23% of feature flag rollouts include a kill switch (Feature Flag Survey 2025, n=412)" cites better than "many feature flag rollouts include a kill switch." Specific numbers with sources are higher-citation signals; vague qualifiers are lower-citation. + +### Named experts and named methods + +"As Adam Kalai noted in the original CUPED paper" cites better than "experts have shown." Named attribution earns citation; anonymous attribution does not. The hub should mention 5+ named experts or methods across pillar and clusters. + +### Distinctive POV + +AI engines preferentially cite content with a clear, attributable position. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. The hub's POV is the brand's editorial position; consistency across pieces reinforces attribution. + +--- + +## The two-engine optimization + +Pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +**Both reward depth.** Search engines reward comprehensive treatment of a topic. AI engines reward citation-ready depth. Same content; different extraction. + +**Both reward structure.** Search engines parse heading hierarchy for ranking. AI engines parse heading hierarchy for citation extraction. Same structure; different use. + +**Both reward entity coverage.** Search engines use entities for topical relevance. AI engines use entities for retrieval and citation. Same entities; different scoring. + +**Both reward freshness.** Search engines reward recent updates. AI engines re-index recently-updated content more aggressively. Same updates; different cadence. + +The implication. Optimizing for AEO/GEO does not trade off against SEO. The hub architecture that earns search rankings is the same architecture that earns AI citations. Teams that treat them as separate optimizations under-invest in both. + +--- + +## Measuring topical authority signals + +Hub-level metrics worth tracking: + +**Search-side:** + +- Aggregate organic traffic to all pieces in the hub +- Average position for the pillar's primary keyword +- Number of cluster pieces ranking in top 10 for their target keywords +- Internal-link count per cluster piece (from inventory) +- Crawl frequency (Google Search Console) + +**AI-side:** + +- Brand mention rate from Profound, Frase, AirOps, or similar tools +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude) +- Top-cited pieces (which clusters get cited most often) +- AI crawler hit frequency (server logs, Profound Agent Analytics) + +The hub-level dashboard composes these metrics. Tracking at the hub level (not per piece) is what surfaces architecture-level patterns: which clusters drive traffic, which clusters drive citations, which clusters are dead weight. + +See the `seo-aeo-geo` skill for AEO/GEO program-level strategy. diff --git a/skills/pillar-content-architecture/references/url-structure-patterns.md b/skills/pillar-content-architecture/references/url-structure-patterns.md new file mode 100644 index 0000000..1b498c0 --- /dev/null +++ b/skills/pillar-content-architecture/references/url-structure-patterns.md @@ -0,0 +1,105 @@ +# URL structure patterns + +Subfolder vs subdomain decision, slug conventions, breadcrumbs, the /blog/ trap. + +--- + +## Subfolder vs subdomain + +The default for hubs is subfolder. Subdomain has narrow valid use cases. + +**Subfolder pattern.** `example.com/feature-flag-rollout/` for the pillar; `example.com/feature-flag-rollout/kill-switches/` for cluster pieces. Both pillar and cluster live on the same domain authority; PageRank flow is consolidated; the hub compounds within the brand's existing SEO equity. + +**Subdomain pattern.** `docs.example.com`, `community.example.com`, `support.example.com`. Used when the property is genuinely distinct (different audience, different content type, different team ownership). Subdomains receive less of the parent domain's authority signal in most analyses; do not split a hub across subdomains without a strong reason. + +**Decision rule.** Pillar plus cluster always on the same subdomain as the rest of the marketing content. If the brand's marketing content lives at `example.com`, the hub lives at `example.com/[hub]/`. Splitting the hub onto a subdomain treats the hub as a separate property, which is almost never correct. + +--- + +## Hub URL pattern + +The pattern: `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. + +**Why this pattern.** The URL itself signals topical grouping. Crawlers see the path structure and infer that pages under `/feature-flag-rollout/` belong to a topical hub. Readers see the breadcrumb in the URL and know where they are. + +**The /blog/ alternative.** `/blog/feature-flag-rollout/` and `/blog/kill-switches/`. This works structurally; the pieces still rank. But the hub signal is weaker because the URL groups by content type (blog) rather than by topic. Two unrelated blog posts share the `/blog/` path; nothing in the URL says "kill-switches is part of the feature-flag-rollout hub." + +**The fix when migrating off /blog/.** Change the URL pattern via 301 redirects from old to new. Lose some short-term ranking equity during the redirect; gain long-term hub-signal clarity. The migration is worth it for major hubs; not worth it for smaller content sets. + +--- + +## Slug conventions + +**Short, descriptive, keyword-aware but not stuffed.** + +Good: `/feature-flag-rollout/kill-switches/` + +Bad: `/feature-flag-rollout/the-ultimate-guide-to-implementing-kill-switches-in-feature-flag-rollouts-2026/` + +**Why short.** Long slugs read as keyword-stuffed and break in social shares, email previews, and conversational mentions. Search engines do not need every keyword in the URL; they parse the page content. + +**Why descriptive.** The slug should make sense as a standalone string. `/feature-flag-rollout/kill-switches/` is self-describing; `/post-1247/` is not. + +**Keyword-aware.** Include the primary keyword for the cluster piece. Do not include the supporting cluster keywords (those go in the page content, not the URL). + +**Date-free.** Avoid dates in slugs (`/2026-rollout-guide/`). Dated slugs anchor the piece in time; refreshing the piece in 2027 is awkward. Pieces with date-relevant content (annual reports, year-in-review) are exceptions. + +**Hyphens, not underscores.** Search engines treat hyphens as word separators; underscores as part of one word. `kill-switches` reads as two words; `kill_switches` reads as one. + +**Lowercase.** Mixed-case URLs cause case-sensitivity confusion across servers and create duplicate-content issues. + +--- + +## Breadcrumb structure + +Breadcrumbs surface the hub structure in the page UI and the page schema. The pattern: + +`Home > Hub topic > Cluster piece` + +In the UI, breadcrumbs typically render as a small horizontal nav above the title. In schema, BreadcrumbList markup tells crawlers the path. + +**Why breadcrumbs help.** Readers see they are in a hub and can navigate up. Crawlers parse the BreadcrumbList schema and reinforce the hub hierarchy. Some SERPs also surface breadcrumb URLs in rich results. + +**Breadcrumb anti-pattern.** Breadcrumbs that show URL segments instead of human-readable labels. `Home > /feature-flag-rollout > /kill-switches` is the wrong format. Use the hub's display name and the cluster piece's title, not the URL slug. + +**Schema example.** + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +The third item omits "item" because breadcrumbs typically do not link to the current page. + +--- + +## The /blog/ trap + +The symptom. The team's content all lives at `/blog/[slug]/` because that is how the CMS is configured. Pillar and cluster live alongside unrelated blog posts in the same flat URL space. + +The diagnosis. The CMS folder defaulted to `/blog/`. Nobody changed it because changing CMS routing is non-trivial. Hub structure exists in the editorial team's head but not in the URL. + +The cost. Hub signal is weakened; PageRank flow is less topically concentrated; readers cannot tell from the URL that a piece is part of a hub. + +The fix. Change CMS routing to support topic-based subfolders. Migration via 301 redirects from old `/blog/` URLs to new `/[hub]/` URLs. Take a short-term ranking hit during redirect; gain long-term hub authority. + +The "do not migrate" exception. If the existing `/blog/` URL structure is generating significant traffic and the hub investment is small, the migration may not pay back. Score the migration cost against the hub's commercial value; migrate only when the hub justifies it. + +--- + +## Multilingual or multi-region URL patterns + +Hubs that span languages or regions add another structural decision. The two main patterns: + +**Subfolder per locale.** `example.com/en/[hub]/`, `example.com/de/[hub]/`. Cleanest for SEO consolidation; clearest for crawlers. + +**ccTLD per region.** `example.de/[hub]/`, `example.fr/[hub]/`. Stronger for regional ranking but splits domain authority. + +The decision usually depends on the brand's existing internationalization choice; the hub follows the existing pattern. Do not use the hub launch as the moment to switch internationalization strategies. diff --git a/skills/pm-spec-writing/SKILL.md b/skills/pm-spec-writing/SKILL.md new file mode 100644 index 0000000..abb72ad --- /dev/null +++ b/skills/pm-spec-writing/SKILL.md @@ -0,0 +1,226 @@ +--- +name: pm-spec-writing +description: "Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks." +category: product +catalog_summary: "PRDs, user stories, acceptance criteria, dev briefs" +display_order: 1 +--- + +# PM Spec Writing + +Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work. + +--- + +## When to use + +- Translating an idea into a buildable feature spec +- Writing a PRD or product requirement document +- Filing a bug report that someone else can act on +- Scoping a project before kickoff +- Prioritizing a backlog of feature requests +- Writing acceptance criteria for an existing feature +- Breaking a large initiative into shippable increments + +## When NOT to use + +- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`) +- Code review or debugging existing code (use `code-review-web`) +- Design decisions for a feature already specced (use `design-standards`) +- User research to validate an idea (use `ux-research`) + +--- + +## Required inputs + +- The idea, request, or problem being addressed +- The audience or user affected +- Any existing constraints (stack, deadlines, dependencies) +- The success metric (how will you know it worked?) + +If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness. + +--- + +## The framework: 4 phases + +Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary. + +### Phase 1: Clarify the idea + +Before any spec, answer four questions. If any answer is "I don't know," go back to the user. + +1. **What user problem does this solve?** Not "what does it do." The problem comes first; the feature is the proposed solution. +2. **Who specifically benefits?** Be precise. "Users" is not specific. "First-time visitors who don't convert" is. +3. **What is the success metric?** How will you know it worked? Pick one primary metric. +4. **Why now?** What changed that makes this the right time to build it? If "nothing changed," it might not be the right time. + +### Phase 2: Scope by impact and effort + +Plot every candidate idea on the impact/effort grid: + +``` +HIGH IMPACT / LOW EFFORT Ship immediately + Examples: copy fixes, contrast fixes, meta tags, + broken links, missing alt text, redirects + +HIGH IMPACT / HIGH EFFORT Plan and batch + Examples: new page type, new feature, schema overhaul, + major redesign, new integration + +LOW IMPACT / LOW EFFORT Nice-to-have batch + Examples: tooltip improvements, minor copy polish, + cosmetic UX touches + +LOW IMPACT / HIGH EFFORT Skip or defer indefinitely + Examples: rebuilding what already works, exotic + edge case features, premature optimization +``` + +This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions. + +### Phase 3: Write the spec + +Three formats based on the type of work. + +#### Format A: Feature spec (for new features) + +``` +TITLE: [Specific, action-oriented] + +PROBLEM +[1-2 sentences. The user problem and current state.] + +USERS +[Who specifically benefits. Be precise about the user segment.] + +PROPOSAL +[1 paragraph. The proposed solution. Stay at the conceptual level.] + +USER STORIES +- As a [user type], I want to [action], so that [outcome] +- As a [user type], I want to [action], so that [outcome] + +ACCEPTANCE CRITERIA +- Given [context], when [action], then [expected outcome] +- Given [context], when [action], then [expected outcome] + +OUT OF SCOPE +[What this spec explicitly does NOT cover. Important for scope control.] + +DEPENDENCIES +[Other systems, APIs, designs, content needed before this can ship.] + +SUCCESS METRIC +[The one primary metric that tells us this worked. With current baseline if known.] + +ESTIMATED EFFORT +[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)] + +PRIORITY +[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog] +``` + +#### Format B: Dev brief (for handing to a developer or AI agent) + +For tactical, ready-to-build work. Lighter than a full spec. + +``` +CONTEXT: [1-2 sentences explaining why this matters] + +TASK: [Specific files, exact changes needed] + +CONSTRAINTS: [What must NOT change, what to preserve] + +VERIFY: [Exact steps to confirm the work is done correctly] +``` + +The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means. + +#### Format C: Bug report + +``` +URL or context: [Where it happens] + +Symptom: [What the user sees or experiences] + +Expected: [What should happen instead] + +Steps to reproduce: +1. [Specific step] +2. [Specific step] +3. [Specific step] + +Hypothesis: [Likely root cause if known] + +Files to investigate: [Likely files involved if known] + +Priority: + P0 - blocking critical user flow, ship immediately + P1 - degrades UX significantly, fix this sprint + P2 - minor issue, fix when convenient + P3 - nice-to-have improvement + +Browser/device: [If reproducibility might be browser-specific] +``` + +### Phase 4: Sequence and ship + +Specs without sequencing become dust on a shelf. + +For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate. + +For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels. + +--- + +## Workflow + +1. **Clarify.** If the idea is vague, ask the four phase-1 questions before proceeding. +2. **Scope.** Plot the work on the impact/effort grid. +3. **Pick the right format.** Feature spec for new features, dev brief for tactical work, bug report for defects. +4. **Write the spec.** Use the template format. Fill in every section. Empty sections are flags. +5. **Define done.** Verify steps must be unambiguous. "Test it" is not a verify step. +6. **Get buy-in.** Walk through the spec with whoever will build it before they start. +7. **Sequence.** Identify the smallest shippable increment. + +--- + +## Failure patterns + +- **Specs that describe solutions before problems.** Always start with the user problem. The solution is downstream. +- **Specs without a success metric.** Without a metric, you cannot tell if the feature worked. +- **Acceptance criteria that are not testable.** "User experience is improved" is not testable. "User completes signup in under 60 seconds" is. +- **Specs that include the "how" instead of the "what."** Implementation details belong in the dev brief, not the spec. The spec is the desired outcome. +- **No "out of scope" section.** Without explicit boundaries, scope creeps. +- **Bug reports without reproduction steps.** Cannot be acted on. Always include steps. +- **Verify steps that are vague.** "Make sure it works." Useless. Must be specific actions with observable outcomes. +- **Skipping the smallest-shippable-increment exercise.** Leads to 6-month projects that should have been 2-week experiments. + +--- + +## Output format + +Output is one of three formats based on work type, all in markdown: + +- `spec-[feature-name].md` for feature specs +- `brief-[task-name].md` for dev briefs +- `bug-[summary].md` for bug reports + +For larger initiatives, group related specs in a folder: +``` +specs/ + initiative-name/ + spec-feature-1.md + spec-feature-2.md + brief-task-1.md + README.md (overview and sequencing) +``` + +--- + +## Reference files + +- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template. +- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work. +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW. diff --git a/skills/pm-spec-writing/references/dev-brief-template.md b/skills/pm-spec-writing/references/dev-brief-template.md new file mode 100644 index 0000000..289ffef --- /dev/null +++ b/skills/pm-spec-writing/references/dev-brief-template.md @@ -0,0 +1,207 @@ +# Dev Brief Template + +A dev brief is the lightweight version of a spec. Used for tactical work that does not need a full PRD: bug fixes, copy changes, small feature additions, infrastructure tweaks. + +The brief is structured to be handed directly to a developer or AI agent. They should be able to act on it without follow-up questions. + +--- + +## Template + +``` +TASK: [One-sentence summary of what to do] + +CONTEXT +[1 to 2 sentences. Why this matters. What problem it solves.] + +WHAT TO DO +[Specific changes. List the exact files (if known), the exact behavior to change, the exact copy to update. Be unambiguous.] + +CONSTRAINTS +[What must NOT change. What to preserve. What's out of bounds.] + +VERIFY +[Exact steps to confirm the work is done correctly. Each step should produce an observable outcome that proves the change worked.] + +DEPENDENCIES +[Anything that must be done first, or that this depends on.] + +PRIORITY +[P0 / P1 / P2 / P3 with one-line reason] + +ESTIMATED TIME +[Minutes or hours - not days. If it would take days, write a feature spec instead.] +``` + +--- + +## Example: Bug fix brief + +``` +TASK: Fix the broken submit button on the contact form + +CONTEXT +Users reported that the contact form submit button does not respond on mobile Safari. +This is blocking lead capture from a major traffic source. + +WHAT TO DO +- Investigate components/forms/ContactForm.tsx +- Check the onClick handler and form submission logic +- The issue is likely related to a recent change to the button onClick handler; + check git log for the most recent commit touching this component +- Fix so submit fires on tap as well as click + +CONSTRAINTS +- Do not change any other forms in the codebase +- Do not modify the form validation logic +- Preserve the existing visual design of the button + +VERIFY +1. Open contact form on mobile Safari (or device-mode in browser) +2. Fill required fields with valid data +3. Tap submit button +4. Confirm form submits and success message displays +5. Repeat on Chrome and Firefox to ensure no regression +6. Check browser console for errors after submit + +DEPENDENCIES +None. Self-contained fix. + +PRIORITY +P1 - blocking lead capture from primary traffic source + +ESTIMATED TIME +30 to 60 minutes +``` + +--- + +## Example: Copy change brief + +``` +TASK: Update homepage hero copy to match new positioning + +CONTEXT +The marketing team has finalized the new positioning statement. +The current hero copy is from the previous brand iteration and needs updating. + +WHAT TO DO +File: pages/index.tsx (or app/page.tsx in App Router) + +Change the hero H1 from: + "The all-in-one platform for modern teams" +To: + "Move work forward without moving the meeting" + +Change the hero subheadline from: + "Streamline your workflow with our innovative collaboration suite" +To: + "Async-first project management for distributed teams that ship." + +Change the primary CTA button text from: + "Get started" +To: + "Start free trial" + +CONSTRAINTS +- Do not change the hero image +- Do not change the secondary CTA +- Preserve all existing styling and component structure + +VERIFY +1. Reload the homepage in a browser +2. Confirm new H1, subheadline, and CTA text display correctly +3. Confirm visual layout is unchanged (no new layout shifts) +4. Confirm responsive behavior on 375px viewport +5. Run a Lighthouse pass to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P1 - aligned with brand launch on [date] + +ESTIMATED TIME +15 to 30 minutes +``` + +--- + +## Example: Small feature brief + +``` +TASK: Add an estimated reading time to blog post pages + +CONTEXT +Users have asked for an indication of how long a post takes to read. +Improves perceived value and helps users decide whether to start reading. + +WHAT TO DO +- Calculate reading time as word count / 200 words per minute, rounded up +- Display below the post title, alongside the publish date +- Format: "5 min read" (with the minute count appropriate to length) +- Apply to all blog post pages (single post template) + +Suggested implementation: +- Compute server-side from the post body content +- Add to the post component's metadata section +- Style consistently with the existing publish date + +CONSTRAINTS +- Must work for posts of any length (test 1 minute to 30+ minute posts) +- Must not affect SEO (e.g., no JS-rendering for crawlers) +- Must not regress page load performance + +VERIFY +1. Open 3 different blog posts of varying length +2. Confirm reading time displays correctly for each +3. Verify the calculation is right (count words manually for a short post) +4. Check the rendered HTML to confirm the value is server-rendered, not JS +5. Confirm visual styling matches the publish date treatment +6. Run Lighthouse to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P2 - nice user enhancement, no urgency + +ESTIMATED TIME +1 to 2 hours including QA +``` + +--- + +## What makes a good brief + +**Context** answers "why am I doing this?" Without it, the implementer cannot make good judgment calls. + +**What to do** is specific. Names files when known. Quotes exact copy when copy is changing. Describes desired behavior unambiguously. + +**Constraints** prevent scope creep. Especially for AI agents who tend to "improve" things outside the task. + +**Verify** is the most-skipped section and the most important. Each verify step must be: +- Observable (you can see whether it passed or failed) +- Specific (no "make sure it works") +- Sufficient (if all verify steps pass, the work is genuinely done) + +**Dependencies** prevent the implementer from starting work that's blocked. + +**Priority** sets expectations on order. + +**Estimated time** sets expectations on effort. Briefs are for work measured in minutes to a few hours. Days-long work should be a feature spec. + +--- + +## When NOT to use a dev brief + +If the work has any of the following, write a feature spec instead: + +- Multiple stakeholders need to weigh in +- The user-facing behavior needs design review +- The change affects multiple parts of the system +- The estimate exceeds 1 day of work +- The success metric is non-obvious +- The work cannot be verified by a few specific steps + +A dev brief is for "do this exact thing." A feature spec is for "build this product capability." diff --git a/skills/pm-spec-writing/references/feature-spec-template.md b/skills/pm-spec-writing/references/feature-spec-template.md new file mode 100644 index 0000000..48c4447 --- /dev/null +++ b/skills/pm-spec-writing/references/feature-spec-template.md @@ -0,0 +1,192 @@ +# Feature Spec: [Feature Name] + +**Author:** [Name] +**Date:** [YYYY-MM-DD] +**Status:** [Draft / In Review / Approved / In Development / Shipped] +**Target ship:** [Date or sprint] + +--- + +## TL;DR + +[2 to 3 sentences. What this is, who it's for, why it matters. If a stakeholder reads only this section, they should understand the proposal.] + +--- + +## Problem + +[1 to 2 paragraphs. The user problem. The current state and why it's inadequate. Include data if available (analytics, support tickets, user research quotes).] + +### Evidence + +- [Specific data point or research finding] +- [Specific data point or research finding] +- [Specific data point or research finding] + +--- + +## Users + +**Primary user:** [Specific user segment that benefits most] + +**Use cases:** +1. [Specific scenario where this user encounters the problem] +2. [Specific scenario] +3. [Specific scenario] + +**Secondary users:** [Other segments affected] + +**Anti-users:** [Segments this feature is NOT for; helps prevent scope creep] + +--- + +## Proposal + +[1 paragraph at the conceptual level. The solution, not the implementation. Stay at "what" not "how".] + +### How it works (high level) + +[3 to 5 bullets describing the user experience flow. Still high level; not implementation details.] + +1. [User action] +2. [System response] +3. [User action] +4. [System response] + +--- + +## User stories + +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. + +--- + +## Acceptance criteria + +The feature ships when ALL of these are true. + +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] **Given** [context], **when** [action], **then** [expected outcome] +- [ ] [Additional criteria] +- [ ] [Additional criteria] + +Each criterion must be observable and testable. If you cannot verify it with a specific check, rewrite it. + +--- + +## Out of scope + +[Explicit boundaries. What this spec does NOT cover. Critical for scope control.] + +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] + +--- + +## Dependencies + +### Required before development can start +- [ ] [Design completed and approved] +- [ ] [API contracts defined] +- [ ] [Content delivered] +- [ ] [Legal/compliance review if applicable] + +### External systems or services +- [System or service]: [What we depend on] +- [System or service]: [What we depend on] + +### Team dependencies +- Design: [What's needed and who owns it] +- Engineering: [Specific resources and timeline] +- Content: [If applicable] +- Marketing: [If launch-related] + +--- + +## Success metric + +**Primary metric:** [The one metric that tells us this worked] + +**Current baseline:** [If known] + +**Target:** [What success looks like quantitatively] + +**Measurement window:** [When and for how long we measure] + +**Secondary metrics (signals to watch):** +- [Metric] - [why it matters] +- [Metric] - [why it matters] + +**Negative signals (what would tell us this hurt):** +- [Metric] - [threshold for concern] +- [Metric] - [threshold for concern] + +--- + +## Estimated effort + +**Size:** [Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (multiple sprints)] + +**Breakdown:** +- Design: [hours/days] +- Frontend: [hours/days] +- Backend: [hours/days] +- QA: [hours/days] +- Content: [hours/days] +- Total: [estimated] + +--- + +## Priority + +**P0** Launch blocker - must ship before [event/launch] +**P1** Next sprint - high impact, addressable now +**P2** Within quarter - valuable but not urgent +**P3** Backlog - nice-to-have, no commitment + +**This spec:** [P0 / P1 / P2 / P3] + +**Reasoning:** [Why this priority] + +--- + +## Open questions + +[Things that need to be decided before development can start, or before the feature can ship.] + +- [ ] [Question] - **Owner:** [Who decides] - **Decision needed by:** [Date] +- [ ] [Question] - **Owner:** [Who decides] - **Decision needed by:** [Date] + +--- + +## Risks and mitigations + +| Risk | Likelihood | Impact | Mitigation | +|---|---|---|---| +| [Risk description] | High/Med/Low | High/Med/Low | [How we'll mitigate] | +| [Risk description] | | | | + +--- + +## Smallest shippable increment + +**MVP:** What is the simplest version that delivers user value? + +[Description of the MVP. Shippable in 1 to 2 weeks for most features. If you can't describe an MVP that fits, the feature is too big and should be split.] + +**Future iterations** (NOT in MVP, may come later): +- [Iteration 1] +- [Iteration 2] +- [Iteration 3] + +--- + +## Changelog + +| Date | Author | Change | +|---|---|---| +| YYYY-MM-DD | [Name] | Initial draft | diff --git a/skills/pm-spec-writing/references/prioritization-frameworks.md b/skills/pm-spec-writing/references/prioritization-frameworks.md new file mode 100644 index 0000000..0fb7f3d --- /dev/null +++ b/skills/pm-spec-writing/references/prioritization-frameworks.md @@ -0,0 +1,219 @@ +# Prioritization Frameworks + +Beyond the simple impact/effort grid, there are several frameworks for prioritizing work. Each is useful in different situations. None is universally correct. + +--- + +## Impact / Effort matrix + +The simplest and most common. + +**How it works:** plot every candidate on a 2x2 grid. + +``` + Low Effort High Effort + +High Impact Quick wins Major projects + (Ship now) (Plan and batch) + +Low Impact Backlog batch Skip or defer + (When time allows) (Reconsider) +``` + +**Strengths:** Fast. Forces blunt judgment. Useful for triage. + +**Weaknesses:** Subjective. "Impact" and "effort" are estimates that get inflated. + +**When to use:** Triage of a long list. Initial sorting. + +--- + +## RICE + +A weighted scoring method that produces a numeric priority score. + +**How it works:** + +``` +RICE Score = (Reach × Impact × Confidence) / Effort +``` + +- **Reach:** How many users this affects per period (e.g., per quarter). Use real numbers. +- **Impact:** The per-user impact, scored on a fixed scale: + - 3 = Massive (transformative) + - 2 = High (significant lift) + - 1 = Medium (modest lift) + - 0.5 = Low (minor lift) + - 0.25 = Minimal (barely noticeable) +- **Confidence:** How certain you are of the reach and impact estimates, as a percentage. + - 100% = high confidence (data-backed) + - 80% = medium confidence (some evidence) + - 50% = low confidence (mostly intuition) +- **Effort:** Person-months (or person-weeks for smaller work). + +**Example:** + +A new onboarding flow: +- Reach: 5,000 new users per quarter +- Impact: 1 (modest improvement to activation) +- Confidence: 80% +- Effort: 2 person-months + +RICE = (5000 × 1 × 0.8) / 2 = 2,000 + +A bug fix on a rarely-used page: +- Reach: 50 users per quarter +- Impact: 2 (significant for those affected) +- Confidence: 100% +- Effort: 0.25 person-months + +RICE = (50 × 2 × 1) / 0.25 = 400 + +The onboarding flow scores higher. + +**Strengths:** Numeric. Forces explicit estimates. Surfaces the math behind judgment. + +**Weaknesses:** Garbage-in-garbage-out. Reach and impact estimates can be wildly wrong. + +**When to use:** Comparing across many candidate features. When stakeholders disagree on priority. + +--- + +## MoSCoW + +Categorical, used for release scoping. + +**How it works:** every item is one of four: + +- **Must have** - non-negotiable for this release +- **Should have** - important but not critical +- **Could have** - nice if time allows +- **Won't have** - explicitly out of scope (this release) + +**Example for a redesign launch:** + +- **Must:** New navigation, mobile responsive, all P0 pages migrated +- **Should:** New blog template, updated forms +- **Could:** New illustrations on lower-traffic pages +- **Won't:** Internationalization (deferred to phase 2) + +**Strengths:** Clear scope boundaries. Forces explicit "won't have" decisions, which prevent scope creep. + +**Weaknesses:** Not a framework for relative priority within categories. + +**When to use:** Defining the scope of a release. Cutting features when timeline pressure hits. + +--- + +## Cost of Delay / Weighted Shortest Job First + +A framework from lean product development. Optimizes for delivering value sooner. + +**How it works:** + +``` +Priority = Cost of Delay / Job Duration +``` + +- **Cost of Delay:** What is the cost (in revenue, risk, customer impact) of NOT doing this for one more period? +- **Job Duration:** How long will this take? + +The work with the highest "Cost of Delay per unit time" gets done first. + +**Example:** + +A revenue-impacting bug: +- Cost of Delay: $5,000 per week of lost conversions +- Duration: 1 week +- Priority score: 5,000 + +A large feature: +- Cost of Delay: $20,000 per week of unrealized revenue +- Duration: 12 weeks +- Priority score: 1,667 + +Even though the feature has higher absolute cost of delay, the bug ships first because it delivers value faster. + +**Strengths:** Captures urgency. Useful for revenue-sensitive decisions. + +**Weaknesses:** Cost of Delay is hard to estimate. + +**When to use:** Operational backlogs. Revenue-sensitive features. + +--- + +## Value vs Effort with strategic alignment + +A 3-axis variant for when strategic fit matters more than raw impact. + +**How it works:** score each candidate on: + +- **Value** (1 to 5) +- **Effort** (1 to 5, inverted - 5 means low effort) +- **Strategic fit** (1 to 5) + +Composite score: Value + Effort + Strategic fit. + +Candidates with the highest composite score win. + +**Strengths:** Captures that some valuable work is wrong for the company right now. + +**Weaknesses:** Three axes is more complex than most teams can sustain. + +**When to use:** When the team is being pulled toward locally-valuable work that does not advance the strategy. + +--- + +## The "next thing" framework + +The simplest, for solo founders or very small teams. + +**How it works:** ask one question: + +> "What is the single most important thing I could ship in the next two weeks?" + +Ship it. Then ask the question again. + +**Strengths:** Maximum focus. Avoids analysis paralysis. + +**Weaknesses:** Misses opportunities to batch related work. Susceptible to recency bias. + +**When to use:** Solo work. When the backlog is short. When velocity matters more than precision. + +--- + +## Choosing a framework + +| Situation | Framework | +|---|---| +| Long backlog, need triage | Impact / Effort matrix | +| Comparing features for the next quarter | RICE | +| Defining a release scope | MoSCoW | +| Revenue-sensitive operations work | Cost of Delay / WSJF | +| Strategic misalignment risk | Value + Effort + Strategic fit | +| Solo founder, weekly cadence | "Next thing" | + +The frameworks are tools. The output is a prioritized list. If the list is helpful and team agrees, the framework worked. If it's not, try another framework or revisit the inputs. + +--- + +## Common pitfalls + +- **Framework theater.** Spending more time on the framework than the work. Pick one. Move on. +- **Estimate inflation.** Engineers underestimate effort by 2x. PMs overestimate impact by 3x. Calibrate over time. +- **Static prioritization.** A one-time sort that never gets revisited. Re-prioritize at least monthly. +- **Ignoring sunk cost dynamics.** Just because you've worked on something for 3 months does not mean it deserves to ship. Cut your losses if the priority math no longer works. +- **Optimizing the wrong metric.** A framework's output is only as good as the metric you're optimizing for. Make sure that metric is correct. +- **Treating the score as truth.** A RICE score is a directional signal, not a verdict. Use judgment alongside the math. + +--- + +## Recommended default + +For most teams, the default is: + +1. **Impact / Effort matrix** for triage and backlog grooming +2. **RICE** for comparing feature candidates within a quarter +3. **MoSCoW** for release scoping when timeline is fixed + +That covers 90 percent of prioritization decisions a typical product team faces. diff --git a/skills/product-analytics-setup/SKILL.md b/skills/product-analytics-setup/SKILL.md new file mode 100644 index 0000000..926677a --- /dev/null +++ b/skills/product-analytics-setup/SKILL.md @@ -0,0 +1,308 @@ +--- +name: product-analytics-setup +description: "How to actually instrument product analytics correctly. Event taxonomy, property design, naming conventions, schema versioning, identity stitching, funnel design, retention cohorts, North Star metric selection, dashboard hygiene, instrumentation debt, and the failure modes that produce data nobody trusts. Triggers on product analytics setup, event taxonomy, tracking plan, instrumentation, schema versioning, North Star metric, retention cohorts, funnel design, naming conventions, instrument new feature, audit existing analytics, dashboard reconciliation, instrumentation debt, Mixpanel setup, Amplitude setup, PostHog setup, warehouse-native analytics. Also triggers when the team has data but cannot trust it, or when designing instrumentation for a new feature, or when auditing an existing setup that has drifted." +category: product +catalog_summary: "Instrument product analytics correctly: event taxonomy, properties, naming conventions, schema versioning, funnels, retention cohorts, North Star selection, and the instrumentation debt that compounds without discipline" +display_order: 8 +--- + +# Product Analytics Setup + +A senior PM and analyst's playbook for instrumenting product analytics correctly the first time. + +Most product analytics setups are some combination of inherited mistakes, dashboard sprawl, and events nobody trusts. The team launches a new feature; instrumentation gets bolted on under deadline pressure; naming drifts; properties are inconsistent; six months later nobody can answer simple questions because the answer depends on which event you trust. + +This skill is the discipline that prevents that. It assumes you have answered the strategic questions about what to measure (see `analytics-strategy`). It assumes you have a tool connected (Mixpanel, Heap, PostHog, Amplitude, or warehouse-native via BigQuery, Snowflake, or dbt). The hard part is the systematic execution: naming conventions, property design, schema versioning, funnel construction, cohort definitions, retention measurement. + +When to use this skill: setting up product analytics from scratch, auditing an existing instrumentation, fixing a "we have data but cannot trust it" problem, or designing instrumentation for a new feature. + +--- + +## What this skill is for + +This skill spans instrumentation execution. It does not cover measurement strategy (use `analytics-strategy`), experimentation result interpretation (use `experimentation-analytics`), paid media analytics (use `ads-performance-analytics`), or platform decisions (use `experimentation-platform-orchestrator`). Pair this skill with the relevant integrations microsite for your specific tool. + +The clean distinction from analytics-strategy. That skill (Growth category) is strategic: what to measure and why, KPI hierarchy, dashboard architecture, attribution models. This skill (Product category) is execution: how to actually instrument the product correctly. The two compose. Read analytics-strategy first to decide what matters; read this skill to instrument it. + +--- + +## The instrumentation hierarchy + +The mental model. Every analytics setup is a stack of layers. Each layer depends on the one below it being correct. + +- **Events** are the atomic facts: `user_signed_up`, `checkout_completed`, `feature_x_used`. +- **Properties** describe events: who, what, where, when, with what context. +- **Identities** map events to people: `anonymous_id`, `user_id`, `account_id`. +- **Cohorts** are filters across events: "users acquired via paid in March." +- **Funnels** are sequences of events: signup, then activated, then first paid action. +- **Retention** measures repeat behavior: signups still active at week N. + +You cannot construct higher levels without correct lower levels. Garbage events produce garbage funnels. The discipline is bottom-up. Most "we have data but cannot trust it" problems trace back to the bottom two layers. + +--- + +## Event taxonomy design + +Three rules for event design. + +1. **Past tense, action-oriented.** `checkout_completed`, not `checkout_complete` or `completing_checkout`. Past tense reads as "this happened" rather than as a state. +2. **Object-action format.** Noun then verb. `video_played`, `form_submitted`, `email_opened`. Reading the event name aloud should describe what happened. +3. **Granular but not redundant.** Track distinct user actions, not button clicks. Fire `checkout_completed` once at the moment of completion, not `submit_button_clicked` plus `checkout_completed`. UI events are noise; semantic events are signal. + +The verbs vs states trap. + +- Verbs ARE events. `checkout_completed`, `subscription_canceled`, `account_upgraded`. +- States are NOT events; they are properties. `user_status: active` is a property on the user, not an event. Setting state via events ("status_changed_to_active") is a code smell that produces double-counting. + +How many events to design. Thirty to fifty events is the sweet spot for a typical SaaS product. Below twenty means under-instrumented; above one hundred almost always means tracking UI noise or duplicating events in different formats. + +Detail and a canonical event spec in [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md). + +--- + +## Property design: event-level vs user-level + +Two property types, treated separately. + +**Event-level properties** describe THIS event. The `checkout_completed` event has properties like `cart_value`, `item_count`, `payment_method`, `discount_code`. They live on the event payload and are immutable once fired. + +**User-level properties** describe the USER over time. `subscription_tier`, `lifetime_value`, `acquisition_channel`. Set them once on the user profile; the analytics tool joins them onto every event the user fires. They update over time as the user changes. + +The trap. Putting user-level properties on every event. Do not track `subscription_tier` on every event payload; set it once on the user profile and rely on the join. Putting it on the event creates payload bloat, schema drift when the value changes, and reporting confusion when a user upgrades mid-session. + +Data type discipline. + +- **Strings** for enums: status, tier, channel, region. Enumerable values where the set is bounded. +- **Numbers** only for actual numbers: count, value, duration, score. Never use strings for numeric data ("free trial day 7" should be `trial_day: 7`). +- **Booleans** for actual booleans: `is_admin`, `has_trial`, `is_new_user`. Two values; nothing else. +- **Timestamps** in ISO 8601, always. Always. The number of bugs caused by inconsistent date formats is uncountable. +- **Arrays** rarely. An array property is usually a sign you should split into multiple events with one item per event. + +Worked example in [`references/property-design-patterns.md`](references/property-design-patterns.md) showing right and wrong design for a `product_viewed` event. + +--- + +## Naming conventions + +Pick ONE convention and enforce it. Three conventions worth picking. + +- **snake_case** for events and properties: `user_signed_up`, `cart_value`. Most platforms default to this; pushback is rarely worth it. +- **Object-action format** for events: `user_signed_up`, `video_played`. Reading the name should describe what happened. +- **Verb-noun for user properties** (or just nouns): `subscription_tier`, `is_admin`, `last_active_at`. + +What NOT to do. + +- Mixed case across events. `user_signedUp`, `User Signed Up`, `userSignedUp` all coexisting in the same project. Pick one and migrate. +- Spaces in event or property names. "Sign Up Completed" breaks every URL-encoding scenario and confuses every tool. +- Inconsistent verbs. `user_signed_up` plus `completedCheckout` plus `VIEW_PRODUCT` in the same project means nobody can predict an event name without looking it up. +- Brand names in event names. `mailchimp_email_opened` ages badly when you switch to Customer.io. + +The naming convention reference file provides a complete style guide. Cite it in your team's data contract. + +Detail in [`references/naming-convention-reference.md`](references/naming-convention-reference.md). + +--- + +## Schema versioning + +Schema changes are inevitable. The pattern. + +**Additive changes** are safe. New event, new property on an existing event, new value in an enum. Just ship. Existing dashboards continue to work. + +**Breaking changes** require migration. Renamed event, removed property, changed property type, narrowed enum. These break dashboards downstream; the migration plan is part of the change. + +Versioning patterns. + +- Append `_v2` to events when semantics change. `checkout_completed_v2` fires alongside `checkout_completed` during a transition. +- Keep old events firing during the transition (90 days is typical). Both versions fire; analytics queries gradually migrate to v2. +- Migrate dashboards to v2 before retiring v1. Then deprecate v1 explicitly with a documentation note. + +The data contract idea. + +- Document the canonical schema in code: TypeScript interface, JSON Schema, or Protobuf definition. +- Code review every schema change. Schema is product, not afterthought. +- CI lint rejects schema violations before they hit production. The deploy that adds an event with the wrong type fails the build. + +Detail in [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md). + +--- + +## Funnel design + +Funnels measure progression through a sequence. Four rules. + +1. **Order matters.** A then B then C is a different funnel from B then A then C. The platform will compute different conversion rates depending on order. +2. **Time windows matter.** Most funnels use a 1 to 30 day window from the first event. Document the window explicitly; "users who completed signup AND activated" is meaningless without "within 14 days." +3. **Drop-off interpretation is hard.** Eighty percent of users dropping at step 2 might be the funnel design (audience is wrong), might be the audience (timing is wrong), or might be the product (genuine drop-off). Investigate before declaring. +4. **The anchor event pattern.** Every funnel starts with a high-intent action: signup, trial start, key feature use. Not a vanity event like `page_view` or `session_start`. Vanity-event-anchored funnels show 99% drop-off and tell you nothing. + +Common funnel mistakes. + +- Funnels that include events firing automatically. `session_started` happens for every visit; using it as a step inflates the denominator and makes the rest of the funnel meaningless. +- Funnels too long (10+ steps). Break into two or three shorter funnels. A 10-step funnel produces near-zero end-to-end conversion that is hard to interpret. +- Funnels with the same event in multiple positions. The platform handles this poorly; the analyst handles it worse. +- Mixing different time windows in one funnel. "Users who signed up within 7 days AND converted within 30 days" is two different cohort definitions glued together. + +Common funnel shapes and time-window guidance in [`references/funnel-design-templates.md`](references/funnel-design-templates.md). + +--- + +## Cohort definitions + +A cohort is a group of users sharing an attribute or behavior. Useful patterns. + +- **Acquisition cohorts.** Users acquired in month X. The standard for retention analysis. +- **Behavioral cohorts.** Users who completed action Y. Useful for activation analysis ("users who sent first message in week 1"). +- **Property cohorts.** Users with `subscription_tier: pro`. Useful for segment-level analysis. +- **Combined cohorts.** Signup in March AND completed onboarding AND in EU. The most common in real analytics work. + +Cohort discipline. + +- Define cohorts in code (or in your tool's saved-cohort feature) so they are reusable. +- Version them when criteria change. Compare apples-to-apples. +- Do not compare a 30-day-old cohort to a 365-day-old cohort on retention; the older cohort has had more time to retain by definition. + +Detail in [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md). + +--- + +## Retention measurement + +Retention is repeat behavior over time. Three flavors. + +- **N-day retention.** Did user X come back on day 7, day 14, day 30 specifically. High noise on any single day; useful for short-cycle products. +- **Bracket retention.** Did user X come back at any point during the week 7 to 13 window. More stable than N-day; reads cleaner on retention curves. +- **Unbounded (rolling) retention.** Did user X come back any time after signup. Useful for longer-cycle products where weekly cadence is misleading. + +For most SaaS products, bracket retention is the right default. Day-7 is high-noise; week-2 (bracket) is more stable. Day-1 retention is almost always over-indexed to onboarding effects rather than product-market-fit signal. + +Retention curve interpretation. + +- Steep early drop, then plateau. The product has core users; the rest churn fast. Typical for most SaaS products. +- Gradual decay across weeks with no plateau. No one is sticking. Usually a value-prop or onboarding problem; the product is not delivering recurring value. +- Flat line at low percentage. A power-user product with a small but engaged base. Not a problem; just a different shape. + +Detail in [`references/retention-measurement-patterns.md`](references/retention-measurement-patterns.md). + +--- + +## North Star and supporting metrics + +North Star metric (NSM) selection rules. + +- Reflects user value, not company value alone. +- Captures the core action that, if it grows, the business grows. +- Measurable consistently across time. +- Hard to game. + +Bad NSMs. Signups (vanity; many signups never activate). Revenue (lagging; not action-oriented; varies by mix). DAU (only useful for engagement-driven products; misleads on monthly-cadence products). + +Better NSMs. Weekly active editors (Figma). Nights booked (Airbnb). Messages sent per day (Slack). Products created per workspace per week (Linear). Each names a user-value action that maps to business growth. + +Supporting metrics framework. + +- One NSM. +- Three to five input metrics that drive the NSM. For "weekly active editors" these might be: signups per week, signup-to-active conversion rate, week-over-week active retention. +- Five to ten health metrics that warn of problems. Monthly churn rate, account-level concentration, support ticket volume. + +Detail and product-type-specific examples in [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md). + +--- + +## The trustable dashboard principle + +A dashboard is trustable when four things are true. + +1. **Each metric has a clear definition** documented inline. Not "active users" but "users who fired any event in the last 7 days, deduplicated by user_id, excluding employees." +2. **Each metric has a known data source.** Not "from the warehouse" but "from `fct_orders`, last 30 days, joined to `dim_customers`." +3. **Each metric has known caveats.** Modeled iOS conversions excluded. Internal employees excluded. Test users in QA accounts excluded. +4. **Each metric is reproducible.** The same query, run tomorrow, produces the same number for the same time period. + +The stale dashboard failure mode. A dashboard built two years ago is still in use. The underlying schema changed; the dashboard's query points at columns that no longer exist or now mean something different. The team makes decisions on broken numbers and does not realize until something breaks loudly. + +Prevention. Every dashboard has an owner, a refresh cadence, and a quarterly audit. Dashboards without an owner get deprecated. Dashboards that have not been refreshed in 90 days get deprecated. The half-life of a dashboard is shorter than the half-life of the product. + +--- + +## Instrumentation debt + +The compounding cost of cutting corners. + +- New feature ships without instrumentation: 1 hour saved. +- Six months later: nobody can answer "is feature X working?" +- Cost to retroactively instrument: 20 hours (re-deploy, backfill, validate). +- Cost in lost decisions during the gap: untrackable but real. Decisions get made on intuition rather than data; sometimes the intuition is wrong. + +Instrumentation debt is real and compounds like technical debt. The discipline. + +- Every PR for new functionality includes instrumentation. The PR template asks "what events does this fire?" and rejects the PR if the answer is none. +- Quarterly schema audits. Identify orphan events (firing but not used in any dashboard or query) and deprecate them. Identify gaps (features without events) and fill them. +- "If we cannot measure it, we do not ship it" with explicit exceptions for genuinely experimental features where the cost of instrumentation exceeds the value of the data. + +Detail in [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md). + +--- + +## Common failure modes + +Twelve patterns recur across product analytics setups. The short version. + +- "We have data but cannot trust it." Naming and schema drift. Fix is a schema audit plus naming convention enforcement. +- "Our funnel says 80% drop-off but real conversion is fine." Wrong anchor event or wrong window. Fix the funnel definition. +- "Retention curve is flat at 5%." Often not a problem. Power-user products genuinely have small engaged bases. Compare against business reality before treating as a fix-it. +- "Mixpanel says 1000 conversions, warehouse says 800." Attribution plus identity stitching mismatch. Reconcile against warehouse for canonical numbers. +- "Dashboards take 30 seconds to load." Over-broad queries, unindexed properties, or schema bloat. Profile and refactor. +- "Everyone has their own definition of MAU." No canonical metric document. Ship one; force everyone to use the same definition. +- "We track every button click." UI noise. Audit and remove events that are not used by any dashboard or query. +- "Our event names changed three times." No versioning. Migrate to a versioning pattern; freeze further renames. +- "Analytics tool says iOS users converted 3% but warehouse says 5%." iOS Intelligent Tracking Prevention plus modeled conversions. Treat platform iOS data with extra skepticism. +- "We cannot answer simple questions." Under-instrumented or wrong abstraction layer. Audit the events list against the questions the team is asking; fill the gaps. +- "Two analysts compute different MAU." Different identity stitching. Pick one canonical identity layer and make everyone query from it. +- "Numbers are different than last quarter for no reason." Underlying schema changed without versioning. The dashboard quietly broke; nobody noticed until the gap got large. + +Detail in [`references/common-failures.md`](references/common-failures.md). + +--- + +## The framework: 12 considerations for trustable product analytics + +When designing or auditing product analytics, walk these 12 considerations. Skipping any of them is how the team ends up with data nobody trusts. + +1. **Event taxonomy.** Past tense, object-action, granular but not redundant. Verbs are events; states are properties. +2. **Property design.** Event-level vs user-level. Type discipline. ISO 8601 timestamps everywhere. +3. **Naming conventions.** Pick one and enforce it. snake_case wins by default. +4. **Schema versioning.** Additive vs breaking. `_v2` suffix during transitions. Data contract in code. +5. **Identity stitching.** Anonymous to authenticated, cross-device, cross-tool. One canonical identity layer. +6. **Funnel design.** Anchor on high-intent events. Document time windows. No auto-firing events as steps. +7. **Cohort definitions.** Reusable, versioned, apples-to-apples. Defined in code or saved in the tool. +8. **Retention measurement.** Bracket over N-day for stability. Compare cohorts at matched ages. +9. **North Star.** Captures user value. Hard to game. One NSM, three to five inputs, five to ten health metrics. +10. **Dashboard hygiene.** Definitions, sources, owners, refresh cadence. Stale dashboards get deprecated. +11. **Instrumentation debt.** Every PR includes instrumentation. Quarterly audits. +12. **Single source of truth.** Warehouse for board metrics. Tool for in-flight optimization. Reconcile when they disagree. + +The output of the framework is a tracking plan. A list of events with their properties, the canonical user identity, the named cohorts, the named funnels, the retention measurement choice, the named NSM, the dashboard owners. The plan lives in code and gets reviewed like any other product spec. + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Canonical event spec for typical SaaS: account, user, activation, engagement, conversion, retention events with required properties. +- [`references/property-design-patterns.md`](references/property-design-patterns.md) - Event-level vs user-level patterns. Type discipline. Worked example: `product_viewed` right vs wrong. +- [`references/naming-convention-reference.md`](references/naming-convention-reference.md) - Complete style guide. snake_case, past tense, object-action. Boolean prefixes. Money in cents. Timestamps with `_at` suffix. Do/don't side-by-side. +- [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md) - Additive vs breaking changes. `_v2` suffix pattern. Data contract in TypeScript. CI lint patterns. +- [`references/funnel-design-templates.md`](references/funnel-design-templates.md) - Activation, conversion, engagement, feature adoption funnels. Time windows, anchor events, drop-off interpretation. +- [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md) - Acquisition, behavioral, property, combined cohorts. SQL examples plus tool-specific examples. +- [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md) - NSM rules with examples by product type. Anti-patterns. Migration patterns when changing NSM. +- [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md) - Quarterly audit playbook: schema review, volume sanity checks, dashboard freshness, owner audit, deprecation candidates. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: when in doubt, instrument less + +Most product analytics setups are over-instrumented, not under-instrumented. Tracking every button click produces noise that drowns the signal. The discipline of saying "we do not need to track that" is harder than "let us track that just in case." Default to less. + +The data you do not have can be added later. The data you over-collected costs you forever, in dashboard performance, in schema complexity, in signal-to-noise. The team that ships with thirty well-designed events and a small set of named cohorts outperforms the team that ships with two hundred events and no cohort discipline. + +When the team disagrees on whether to add an event, the question is not "could this be useful?" but "what specific decision will this event inform, and is the decision worth the instrumentation cost?" If the answer is "we might want to know" the answer to the question is no. diff --git a/skills/product-analytics-setup/references/cohort-definition-patterns.md b/skills/product-analytics-setup/references/cohort-definition-patterns.md new file mode 100644 index 0000000..1dc8ca5 --- /dev/null +++ b/skills/product-analytics-setup/references/cohort-definition-patterns.md @@ -0,0 +1,202 @@ +# Cohort definition patterns + +Four cohort patterns: acquisition, behavioral, property, combined. With SQL examples for warehouse-native and tool-specific examples for Mixpanel, Amplitude, and PostHog. + +--- + +## Pattern 1: acquisition cohort + +Users acquired in a specific time window. The standard for retention analysis. + +### Definition + +```sql +-- Warehouse-native (BigQuery / Snowflake / Postgres) +SELECT user_id +FROM dim_users +WHERE first_seen_at >= '2026-04-01' + AND first_seen_at < '2026-05-01'; +``` + +### Tool-specific + +**Mixpanel.** Cohort builder, condition: "First time the user did `user_signed_up` was between April 1 and April 30, 2026." + +**Amplitude.** User segment, condition: "First event date between April 1 and April 30, 2026." + +**PostHog.** Cohort, condition: "Person property `first_seen` is between April 1 and April 30, 2026." + +### Use cases + +- Retention analysis. Compare retention curves across acquisition cohorts to detect product or onboarding regressions. +- Onboarding A/B test results. The treatment cohort and control cohort are both acquisition cohorts. +- Cohort revenue tracking. How much did April's signups generate over the next 12 months? + +### Common mistakes + +- Comparing cohorts at different ages. A 30-day-old cohort has lower retention than a 90-day-old cohort by definition. +- Using "user created" vs "first event" inconsistently. Pick one and document it. + +--- + +## Pattern 2: behavioral cohort + +Users who completed a specific action. The standard for activation and engagement analysis. + +### Definition + +```sql +-- Users who fired first_value_action_completed within 14 days of signup +SELECT u.user_id +FROM dim_users u +JOIN fct_events e ON e.user_id = u.user_id +WHERE e.event_name = 'first_value_action_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '14 days'; +``` + +### Tool-specific + +**Mixpanel.** Cohort builder, condition: "User did `first_value_action_completed` at least once where event time was within 14 days of `user_signed_up`." + +**Amplitude.** Behavioral cohort, "Performed event `first_value_action_completed` within 14 days after first event." + +**PostHog.** Cohort, condition: "Person performed event `first_value_action_completed` and the event happened within 14 days of person creation." + +### Use cases + +- Activation funnel: activated users vs non-activated users. +- Feature adopters: users who used feature X. How does their retention compare to non-adopters? +- Power users: users who fired a specific high-value event 5 or more times. + +### Common mistakes + +- Using behavioral cohorts for retention without a time anchor. "Users who completed onboarding" includes users from January and users from October; their retention curves are at different ages. +- Confusing "users who ever did X" with "users who did X recently." Specify the time window. + +--- + +## Pattern 3: property cohort + +Users with a specific property value. The standard for segment-level analysis. + +### Definition + +```sql +SELECT user_id +FROM dim_users +WHERE subscription_tier = 'pro' + AND region = 'us' + AND is_admin = false; +``` + +### Tool-specific + +**Mixpanel.** Cohort, condition: "User properties: `subscription_tier = pro` AND `region = us`." + +**Amplitude.** User segment, condition: "User properties match: `subscription_tier = pro` AND `region = us`." + +**PostHog.** Cohort, condition: "Person properties: `subscription_tier = pro` AND `region = us`." + +### Use cases + +- Segment performance: how does the Pro tier behave differently from the Free tier? +- Geographic analysis: do EU users convert at a different rate than US users? +- Role-based analysis: do admins use the product differently than members? + +### Common mistakes + +- Using event-level properties as if they were user-level. "Users who fired any event with `cart_value > 100`" returns events, not users; use a behavioral cohort for "users who fired a high-value event." +- Snapshot vs current property values. "Users who were Pro in March" vs "users who are Pro now" are different cohorts; some platforms default to current values without warning. + +--- + +## Pattern 4: combined cohort + +Combinations of the above. The most common in real analytics work. + +### Definition + +```sql +-- Users who signed up in March, completed onboarding within 7 days, +-- are in EU, and are on the Pro tier +SELECT u.user_id +FROM dim_users u +WHERE u.first_seen_at >= '2026-03-01' + AND u.first_seen_at < '2026-04-01' + AND u.region = 'eu' + AND u.subscription_tier = 'pro' + AND EXISTS ( + SELECT 1 FROM fct_events e + WHERE e.user_id = u.user_id + AND e.event_name = 'onboarding_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '7 days' + ); +``` + +### Tool-specific + +All three platforms support combined cohorts via boolean composition (AND, OR, NOT). The composition gets unwieldy past 4 or 5 conditions; consider whether the cohort is genuinely useful or whether the team is over-segmenting. + +### Use cases + +- Activation analysis by acquisition channel: "Paid Meta users who signed up in March and activated within 7 days." +- Quality cohorts: "Pro tier users acquired via organic search who reached aha_moment within 14 days." +- Test cohorts: "Treatment group users who completed the onboarding A/B test within 7 days." + +### Common mistakes + +- Cohorts so narrow that the population is too small for analysis. A cohort of 50 users has high variance on every metric. +- Combining conditions that contradict each other. "Pro tier free users" returns nothing. +- Forgetting to time-box. A combined cohort without acquisition or behavioral time bounds drifts as users join and leave. + +--- + +## Cohort discipline + +Three rules that apply across all four patterns. + +### Rule 1: define cohorts in code (or saved in the tool) + +Re-querying the same cohort definition by hand each time produces inconsistencies. Define the cohort once; reuse the definition across analyses. + +In SQL: a `WITH` clause or a saved view. + +```sql +WITH march_cohort AS ( + SELECT user_id + FROM dim_users + WHERE first_seen_at >= '2026-03-01' + AND first_seen_at < '2026-04-01' +) +SELECT COUNT(*) FROM march_cohort; +``` + +In analytics tools: saved cohorts. Every analysis references the saved cohort by name. + +### Rule 2: version when criteria change + +A cohort definition that evolves over time produces non-comparable results. If you change the activation definition, the new cohort is a different cohort. + +Pattern. Append `_v2` to the cohort name when criteria change. Keep the old definition queryable for historical comparison. + +### Rule 3: compare apples-to-apples + +Two cohorts compared at different ages produce misleading conclusions. Always compare at matched ages. + +If comparing March cohort retention against November cohort retention, both should be measured at the same number of days post-acquisition. November cohort at 30 days vs March cohort at 60 days is not a fair comparison. + +--- + +## When to introduce a cohort + +The team has a question that filters on a user attribute or behavior. The question repeats across analyses. The team is computing the same filter 5+ times by hand. + +That is the trigger. Define the cohort once; reuse it. + +--- + +## When to deprecate a cohort + +The cohort has not been queried in 90 days. The cohort criteria no longer match a real product question (e.g., the feature it tracked was deprecated). The team has built a more precise replacement cohort. + +Stale cohorts in the analytics tool produce dropdown clutter and tempt analysts to use them when newer cohorts are appropriate. Deprecate explicitly. diff --git a/skills/product-analytics-setup/references/common-failures.md b/skills/product-analytics-setup/references/common-failures.md new file mode 100644 index 0000000..9e5fa5e --- /dev/null +++ b/skills/product-analytics-setup/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across product analytics setups. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. We have data but cannot trust it + +**Symptom.** The team has years of events. Two analysts run the same query and get different numbers. Stakeholders ask for "the real number" and the answer is "it depends." + +**Root cause.** Naming and schema drift over time. Same event name has slightly different semantics in different code paths. Properties have inconsistent types or values. + +**Fix.** Schema audit. Identify the canonical events; deprecate the duplicates and aliases. Standardize property types. Document the canonical definitions. + +**Prevention.** Schema in code (TypeScript interface or JSON Schema). CI lint that rejects schema violations. Naming convention enforcement. + +--- + +## 2. Funnel says 80% drop-off but real conversion is fine + +**Symptom.** The activation funnel shows 20% conversion. The team knows from revenue numbers that real activation is 60%. + +**Root cause.** Wrong anchor event (using a too-broad event like `page_view` as the start) or wrong time window (asking for activation within 24 hours when the real cycle is 14 days). + +**Fix.** Audit the funnel definition. Anchor on a high-intent event (signup, trial start). Set the time window to match the actual activation cycle. + +**Prevention.** Document the funnel anchor and window in the funnel definition itself, not implicit in dashboard text. Review funnels at each quarterly audit. + +--- + +## 3. Retention curve is flat at 5% + +**Symptom.** Retention curve drops fast then plateaus at 5%. The team panics; only 5% of users are active. + +**Root cause.** Not always a problem. Some products are power-user products with small but engaged bases (developer tools, niche B2B software). The 5% may be the natural shape. + +**Fix.** Compare against business reality. If 5% retention with strong unit economics, the curve is healthy. If 5% retention and the business model assumes 20% retention, then it is a problem and the cohort needs investigation. + +**Prevention.** Set retention targets based on business model assumptions, not industry benchmarks. The right retention for a niche tool is different from the right retention for a consumer app. + +--- + +## 4. Mixpanel says 1000 conversions, warehouse says 800 + +**Symptom.** Two systems report different conversion counts for the same event. + +**Root cause.** Identity stitching mismatch. Mixpanel may stitch anonymous-to-authenticated differently than the warehouse. Server-side and client-side fires of the same event may not deduplicate correctly. Time-window differences (Mixpanel using event time, warehouse using ingest time). + +**Fix.** Pick one source as canonical (warehouse for board metrics, tool for in-flight). Reconcile the gap by understanding the cause. Document the expected gap so stakeholders are not surprised. + +**Prevention.** Identity stitching pattern documented and consistent. Server-side and client-side firing for the same event handled with explicit deduplication. Use a single time field consistently. + +--- + +## 5. Dashboards take 30 seconds to load + +**Symptom.** The team's main dashboard takes 30+ seconds to refresh. Reviewing a metric becomes a coffee break. + +**Root cause.** Over-broad queries (scanning years of data for a 30-day metric). Unindexed properties used as filters. Schema bloat from too many events or too many properties on each event. + +**Fix.** Profile the slow queries. Add date filters. Index the filter properties. Pre-aggregate metrics into a daily summary table; query the summary, not the raw events. + +**Prevention.** Set query budgets per dashboard (target: under 5 seconds). Audit performance during the quarterly audit. Cap the data volume per query. + +--- + +## 6. Everyone has their own definition of MAU + +**Symptom.** Three people compute MAU; three different numbers. + +**Root cause.** No canonical definition. One person counts unique user_ids firing any event. Another counts users who fired a specific qualifying event. Another counts authenticated users only. + +**Fix.** Write a canonical metric document. "MAU is unique user_ids firing any event in the last 30 days, deduplicated, excluding employee accounts (employees identified by email domain) and excluding test accounts (account_type = 'test')." Force everyone to use this definition. + +**Prevention.** Canonical metric document maintained as living documentation. Every dashboard's metric definitions reference the canonical document. Disagreements get resolved by updating the document, not by recomputing on the fly. + +--- + +## 7. We track every button click + +**Symptom.** The event list has 800 events. Many are individual button clicks. Dashboards are slow; analyses produce noise. + +**Root cause.** Tracking UI events (clicks, hovers, page views) rather than semantic events (created, completed, shared). Each button gets its own event "for completeness." + +**Fix.** Audit the event list. Deprecate UI events. Replace with semantic events that capture user intent. + +**Prevention.** Naming convention enforcement (verbs are events; UI states are properties). Code review on new events asks "is this a semantic event or a UI event?" UI events get rejected unless there is a specific use case. + +--- + +## 8. Our event names changed three times + +**Symptom.** `signup_complete`, then `signupCompleted`, then `user_signed_up`. Dashboards reference all three; nobody knows which is current. + +**Root cause.** No versioning. Each rename happened without coordination, leaving old events in the warehouse and old queries in the dashboards. + +**Fix.** Migrate to a single canonical version. Use the `_v2` pattern if semantics changed. Deprecate old versions explicitly. Update all dashboards. + +**Prevention.** Versioning pattern in the schema documentation. Schema review on every PR that adds or modifies an event. CI lint on event names. + +--- + +## 9. Analytics tool says iOS users converted 3% but warehouse says 5% + +**Symptom.** iOS conversion rate looks bad in the analytics tool but fine in the warehouse. + +**Root cause.** iOS Intelligent Tracking Prevention (ITP) blocks third-party cookies, breaking attribution for iOS users. The analytics tool models the missing data; the warehouse uses server-side conversion tracking that is unaffected. + +**Fix.** Treat iOS analytics-tool data with extra skepticism. Use the warehouse for canonical iOS metrics. Set up server-side event tracking (Conversions API for Meta, server-side GA4) where possible. + +**Prevention.** Document the iOS measurement gap. Pair every iOS-specific metric with a note on the data source. + +--- + +## 10. We cannot answer simple questions + +**Symptom.** Stakeholder asks: "How many users came back this week?" Three days of analyst time later, still no clean answer. + +**Root cause.** Under-instrumented or wrong abstraction layer. The events list does not include the right event. The user identity layer does not stitch correctly. The cohort definition is too narrow or too broad. + +**Fix.** Audit the event list against the questions the team actually asks. Fill gaps with new events; fix identity stitching; create canonical cohorts for the most common questions. + +**Prevention.** Quarterly review of the question backlog. Map questions to events; identify gaps. Fill gaps proactively, not after the question goes unanswered. + +--- + +## 11. Two analysts compute different MAU on the same data + +**Symptom.** Same query, same data, different numbers. The discrepancy is not because of a definition disagreement; it is because the queries silently return different rows. + +**Root cause.** Different identity stitching layers. One query uses user_id; another uses anonymous_id with stitching applied at query time. Edge cases (users who logged out and back in, users on multiple devices) get counted differently. + +**Fix.** Pick one canonical identity layer. Build a `dim_users` table in the warehouse that resolves identity once. Force all queries to join through this table. + +**Prevention.** Identity-stitching pattern documented. New queries use the canonical table. Code review rejects queries that bypass the layer. + +--- + +## 12. Numbers different than last quarter for no reason + +**Symptom.** A dashboard's metrics shifted between Q1 and Q2 by 30%. No product change, no instrumentation change... or so it seems. + +**Root cause.** Underlying schema changed without versioning. An event was renamed; the dashboard's query points at the old name and now silently returns nothing or returns a different cohort. Often discovered weeks after the fact. + +**Fix.** Audit the dashboard's query against the current schema. Update to current event names. Check for similar drift in other dashboards. + +**Prevention.** Versioning pattern enforced. CI lint catches event renames before they ship. Quarterly dashboard audit catches drift early. + +--- + +## The pattern across all twelve + +Most product analytics failures share one root cause: cutting corners during instrumentation produces compounded debt that surfaces months later as untrustworthy data. The team that ships without a tracking plan saves an hour at instrumentation time and pays 20+ hours at audit time. + +The fix at the meta level. Treat instrumentation as a first-class engineering concern. Schema in code. Naming convention enforced. Quarterly audits. Single source of truth for canonical metrics. Instrumentation debt is real; the discipline of paying it down regularly is the only thing that keeps the data trustworthy. diff --git a/skills/product-analytics-setup/references/event-taxonomy-template.md b/skills/product-analytics-setup/references/event-taxonomy-template.md new file mode 100644 index 0000000..86bb1df --- /dev/null +++ b/skills/product-analytics-setup/references/event-taxonomy-template.md @@ -0,0 +1,114 @@ +# Event taxonomy template + +A canonical event spec for typical SaaS. Six event categories with the events that belong in each, when they fire, who fires them (client or server), required properties, and common pitfalls. + +The principle. Thirty to fifty events covers most SaaS products. Below twenty is under-instrumented; above one hundred is usually UI noise. The categories below are the durable shape; the specific event names map to your product. + +--- + +## Account events + +Account-level lifecycle. Server-side firing typical because billing is server-side. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `account_created` | A new account (workspace, organization) is provisioned. | `account_id`, `plan_tier`, `seat_count` | Distinct from `user_signed_up` (a user can join an existing account). | +| `account_upgraded` | The account moves to a higher plan tier. | `account_id`, `from_tier`, `to_tier`, `change_reason` | Fires server-side from the billing webhook. | +| `account_downgraded` | The account moves to a lower plan tier. | `account_id`, `from_tier`, `to_tier`, `change_reason` | Same source as upgrade. | +| `account_canceled` | The account cancels and stops renewing. | `account_id`, `cancellation_reason`, `final_term_end_at` | Cancellation reason is critical; capture it from the cancellation flow. | +| `seat_added` | A new seat is provisioned on the account. | `account_id`, `seat_count_after`, `added_by_user_id` | Useful for net-revenue-retention analysis. | +| `seat_removed` | A seat is released from the account. | `account_id`, `seat_count_after`, `removed_by_user_id`, `removal_reason` | | + +Common pitfall. Firing account events client-side from the admin UI. The admin's browser may not be open during the cancellation; server-side from the billing webhook is the right source. + +--- + +## User events + +User-level lifecycle. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `user_signed_up` | A user creates an account or joins an existing account. | `user_id`, `account_id`, `signup_source`, `referrer_source` | Distinct from `account_created`; one account, many users. | +| `user_invited` | An existing user invites a new user. | `inviter_user_id`, `invited_email`, `account_id`, `invitation_role` | The invitation event; `user_signed_up` fires later when the invite is accepted. | +| `user_role_changed` | A user's role within the account changes. | `user_id`, `account_id`, `from_role`, `to_role`, `changed_by_user_id` | | +| `user_logged_in` | A user authenticates after a logged-out state. | `user_id`, `auth_method`, `device_type` | Different from session start. Logged-in across multiple sessions. | +| `user_logged_out` | A user explicitly signs out. | `user_id`, `logout_reason` | Often missed; explicit signout vs session timeout. | +| `user_deactivated` | A user's account is deactivated. | `user_id`, `account_id`, `deactivation_reason` | Soft delete pattern. | + +--- + +## Activation events + +The first-value moment. Critical for activation analysis. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `onboarding_step_completed` | The user completes a step in the onboarding flow. | `user_id`, `step_name`, `step_number`, `time_in_step_s` | Step name is canonical; do not change it without versioning. | +| `onboarding_completed` | The user finishes all onboarding steps. | `user_id`, `total_time_s`, `steps_completed_count` | Distinct from activation; onboarding completion does not equal activation. | +| `first_value_action_completed` | The user does the thing that delivers product value for the first time. | `user_id`, `action_name`, `time_since_signup_s` | Define this carefully per product. For Slack, first message sent. For Figma, first frame created. | +| `aha_moment_reached` | The user crosses the activation threshold. | `user_id`, `threshold_metric`, `threshold_value` | Tied to the activation definition (e.g., "5 messages in week 1"). | + +--- + +## Engagement events + +Recurring product use. The bulk of event volume. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `feature_x_used` | The user invokes feature X. Replace x with the actual feature name. | `user_id`, `feature_name`, `entry_point` | Granularity guidance: one event per feature, not one event per button. | +| `content_y_created` | The user creates a new asset (document, project, message, etc.). | `user_id`, `content_type`, `content_id`, `creation_source` | | +| `content_y_edited` | The user modifies an existing asset. | `user_id`, `content_type`, `content_id`, `edit_type` | High volume; consider sampling if storage is a concern. | +| `content_y_shared` | The user shares an asset externally. | `user_id`, `content_type`, `content_id`, `share_method`, `recipient_count` | Sharing is often the strongest engagement signal. | +| `search_executed` | The user runs an in-product search. | `user_id`, `query_length`, `result_count`, `clicked_result_position` | Capture click-through rates. | + +--- + +## Conversion events + +Money moves. Server-side firing required. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `trial_started` | The user starts a free trial. | `user_id`, `account_id`, `trial_plan`, `trial_length_days` | Server-side from the billing system. | +| `trial_converted` | The trial converts to paid. | `user_id`, `account_id`, `from_plan`, `to_plan`, `mrr_added` | Server-side. The MRR property feeds revenue analysis. | +| `trial_expired_no_conversion` | The trial ends without converting. | `user_id`, `account_id`, `trial_plan`, `usage_during_trial` | Useful for win-back campaigns. | +| `subscription_purchased` | A subscription begins (any path). | `user_id`, `account_id`, `plan_tier`, `mrr_added`, `purchase_source` | Includes trial conversions and direct purchases. | +| `subscription_renewed` | A subscription renews for the next term. | `account_id`, `plan_tier`, `mrr_at_renewal` | | +| `payment_failed` | A payment attempt fails. | `account_id`, `failure_reason`, `attempt_number` | Critical for involuntary churn analysis. | + +--- + +## Retention events + +Repeat behavior markers. Useful for retention curve construction. + +| Event | Fires when | Required properties | Notes | +|---|---|---|---| +| `weekly_active_marker` | The user fires any qualifying event in a given week. | `user_id`, `week_of_year`, `qualifying_event_count` | Some teams compute this in the warehouse rather than fire it as an event; either pattern works. | +| `returned_after_n_days` | The user returns after N days of inactivity. | `user_id`, `inactive_days_count`, `last_active_at` | Useful for resurrection-flow analytics. | + +--- + +## Property requirements across all events + +Every event payload should include: + +- `user_id` (or `anonymous_id` for pre-auth events) +- `account_id` (where applicable; for B2B SaaS especially) +- `timestamp` (ISO 8601, server-stamped) +- `device_type` and `platform` (mobile, web, desktop) +- `app_version` (for change-tracking) +- `session_id` (for path analysis) + +Some platforms inject these automatically. Verify; do not assume. + +--- + +## Common pitfalls in event taxonomy + +- **Tracking page views as the primary engagement signal.** Page views are noise. Track semantic events (created, edited, shared) instead. +- **Treating onboarding completion as activation.** Many users complete onboarding without ever returning. Define activation as a recurring-value action, not as flow completion. +- **Inconsistent fire timing across the funnel.** Some events fire client-side, some server-side. Reconcile by picking one source per event and documenting it. +- **Adding new events without checking existing ones.** Six months in, the event list has three versions of "subscription started." Audit before adding. diff --git a/skills/product-analytics-setup/references/funnel-design-templates.md b/skills/product-analytics-setup/references/funnel-design-templates.md new file mode 100644 index 0000000..f7b110a --- /dev/null +++ b/skills/product-analytics-setup/references/funnel-design-templates.md @@ -0,0 +1,174 @@ +# Funnel design templates + +Common funnel shapes with anchor events, time windows, and drop-off interpretation guidance. + +The principle. Every funnel measures progression through a sequence. The shape of the funnel must match the shape of the user behavior; mismatch produces conversion rates that are uninterpretable. + +--- + +## Activation funnel + +Signup to first value. The most important funnel for product-led growth. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `user_signed_up` | The anchor. High intent. | +| 2 | `onboarding_started` | The user begins the guided onboarding. | +| 3 | `onboarding_completed` | The user finishes onboarding. Note: this is not activation. | +| 4 | `first_value_action_completed` | The user does the action that delivers product value. THIS is activation. | +| 5 | `aha_moment_reached` | Optional. The threshold beyond which retention curves stabilize. | + +### Time window + +7 to 14 days from signup. Longer windows include users who activated after a long delay; shorter windows undercount slow adopters. + +### Anchor selection + +`user_signed_up` is the standard anchor. Avoid `landing_page_viewed` (too noisy) and `email_collected` (too low-intent). + +### Drop-off interpretation + +- 70%+ drop between signup and onboarding_started: the post-signup experience is the problem. Often a friction issue (email verification, account setup steps). +- 30%+ drop between onboarding_completed and first_value_action_completed: onboarding is teaching the wrong thing. Users complete the tour but do not understand the product. +- High drop at first_value_action_completed: the value action is too hard or too far from the user's natural path. Move it earlier in the experience. + +--- + +## Conversion funnel + +Trial to paid. The most important funnel for SaaS subscription businesses. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `trial_started` | The anchor. High intent and ready to evaluate. | +| 2 | `aha_moment_reached` | The user experiences product value. Critical predictor of conversion. | +| 3 | `paywall_viewed` | The user sees the upgrade prompt. | +| 4 | `checkout_started` | The user begins the payment flow. | +| 5 | `subscription_purchased` | The conversion. | + +### Time window + +The trial length plus a 7-day grace period. A 14-day trial uses a 21-day funnel window. Shorter windows undercount last-day conversions. + +### Anchor selection + +`trial_started` is the standard anchor. Funnels that start at signup (rather than trial start) include users who never engaged with the trial; the conversion rate looks lower than it actually is for engaged users. + +### Drop-off interpretation + +- High drop between aha_moment_reached and paywall_viewed: users got value but the paywall did not appear (timing issue) or did not feel relevant. Audit the paywall trigger logic. +- High drop between paywall_viewed and checkout_started: pricing or feature gating is the friction. Often a positioning issue rather than a UX issue. +- High drop between checkout_started and subscription_purchased: payment flow friction. UX audit the checkout pages; check failed-payment rates. + +--- + +## Engagement funnel + +Visit to action. Useful for understanding session-level conversion. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `feature_x_landing_page_viewed` | The anchor. Specific intent (feature page, not homepage). | +| 2 | `feature_x_used` | The user performs the core action. | +| 3 | `feature_x_completed_workflow` | The user finishes the workflow. | +| 4 | `content_y_shared` or similar high-intent action | Optional. Strongest engagement signal. | + +### Time window + +Single session, typically 30 to 60 minutes from the first event. + +### Anchor selection + +A feature-specific landing or entry point. Avoid `homepage_viewed` (too broad) and `session_started` (auto-firing, not intent). + +### Drop-off interpretation + +- High drop from landing to use: the page promises something the feature does not deliver, or the activation friction is too high. +- High drop from use to workflow completion: the workflow has too many steps, or a specific step has UX issues. + +--- + +## Feature adoption funnel + +Awareness to repeat use. Tracks how a feature spreads through the user base. + +### Standard shape + +| Step | Event | Notes | +|---|---|---| +| 1 | `feature_x_announced_to_user` | The anchor. The user saw a notification, prompt, or in-app message about feature X. | +| 2 | `feature_x_first_used` | The user tried feature X for the first time. | +| 3 | `feature_x_used_in_week_2` | The user used feature X again in a different week. | +| 4 | `feature_x_used_in_week_4` | Sustained adoption. | + +### Time window + +4 weeks from announcement. + +### Anchor selection + +The announcement event is the right anchor for measuring rollout effectiveness. For organic discovery (no announcement), use `feature_x_first_used` as the anchor and measure the feature's reach as a denominator. + +### Drop-off interpretation + +- High drop from announcement to first use: the announcement was missed, the announcement was unclear, or the feature was not relevant to the audience. Audit by user segment. +- High drop from first use to repeat use in week 2: the feature did not deliver value on first use. Either the use case was wrong (user tried it for the wrong thing) or the value-prop is weak. +- Adoption stalls at 5% of the user base: the feature is for a niche; this may be expected. Compare against the projected target audience size. + +--- + +## Common funnel design mistakes + +### Mistake 1: vanity-event anchor + +Using `homepage_viewed` or `session_started` as the anchor. The denominator is huge; the conversion rate is tiny; the funnel says nothing about user behavior. + +Fix. Anchor on a high-intent action: signup, trial_started, feature-specific page view. + +### Mistake 2: too long + +Ten or more steps. The end-to-end conversion rate is near zero; the funnel is hard to interpret; small numerator changes look like dramatic shifts. + +Fix. Break into 2 or 3 shorter funnels. An activation funnel plus a conversion funnel beats one 10-step funnel. + +### Mistake 3: auto-firing events as steps + +Including `session_started`, `app_opened`, or any event that fires automatically. The denominator is the entire user base; the meaning of conversion rates is muddled. + +Fix. Use only intentional, semantic events as funnel steps. + +### Mistake 4: same event in multiple positions + +Using `feature_used` at step 2 and step 5. The platform double-counts; the analyst gets confused. + +Fix. Distinguish via different events (`feature_first_used` vs `feature_used_in_week_2`) or via a property filter. + +### Mistake 5: mixed time windows + +The funnel definition allows step 2 within 7 days but step 4 within 30 days. The math becomes interpretable only by the analyst who built it; everyone else gets it wrong. + +Fix. One time window for the entire funnel. Document it explicitly. + +### Mistake 6: forgetting the cohort + +Running the funnel against "all users ever" rather than a specific acquisition cohort. The cohort matters; January users behave differently from November users. + +Fix. Always specify the cohort. "Users who signed up in March, evaluated against the activation funnel within 14 days." + +--- + +## Comparing funnels across cohorts + +The strongest analytical use of funnels is comparing how the funnel performs across cohorts. + +- This month's signup cohort vs last month's: is the funnel stable, or are recent users dropping more? +- Paid acquisition cohort vs organic: are paid users converting at the same rate, or are paid users worse-quality? +- Mobile vs web: is the experience parity issue real? + +Always compare cohorts at matched ages. A 30-day-old cohort vs a 60-day-old cohort has different conversion rates by definition. diff --git a/skills/product-analytics-setup/references/instrumentation-audit-checklist.md b/skills/product-analytics-setup/references/instrumentation-audit-checklist.md new file mode 100644 index 0000000..b481bff --- /dev/null +++ b/skills/product-analytics-setup/references/instrumentation-audit-checklist.md @@ -0,0 +1,119 @@ +# Instrumentation audit checklist + +The quarterly playbook for keeping product analytics trustworthy. Five categories: schema, volume, dashboard freshness, ownership, deprecation. + +The principle. Instrumentation decays without active maintenance. Quarterly audits catch decay early; without them, the team ends up with the "we have data but cannot trust it" problem. + +--- + +## 1. Schema review + +Goal. Ensure the event taxonomy and property schema match the canonical contract. + +Steps. + +- **Pull the event list from the analytics tool.** Mixpanel: Lexicon. Amplitude: Govern. PostHog: Data Management. Or directly from the warehouse if warehouse-native. +- **Compare against the schema definition in code.** Every event in the tool should appear in the schema; every event in the schema should appear in the tool. +- **Flag drift.** Events firing without a schema entry. Schema entries with no events firing in the last 90 days. Property type mismatches between schema and observed values. +- **Audit naming.** Events that do not match the naming convention (snake_case, past tense, object-action). Property names with inconsistent casing or typo variants. +- **Action items.** For each drift item, decide: fix the schema, fix the tracking code, or deprecate the event. Document the decision. + +Cadence. Quarterly. More frequently if the team is shipping rapidly. + +--- + +## 2. Volume sanity check + +Goal. Confirm event volumes match expectations. + +Steps. + +- **Pull weekly event counts** for the last 90 days. Group by event name. +- **Identify volume anomalies.** Sudden drops (deployment broke instrumentation). Sudden spikes (a new code path is firing the event excessively or a bot is hitting the endpoint). Events whose volume drifts steadily down (the feature behind them was deprecated; instrumentation should follow). +- **Check ratios.** If `signup_started` fires 10x more than `signup_completed`, signup completion is broken or the events fire under different conditions than expected. If `checkout_started` fires more than `add_to_cart`, the events are misordered or one fires automatically. +- **Compare against business reality.** The dashboard says 50,000 weekly signups; the warehouse says 38,000 paying customers were acquired in the same period. The gap is fine if the business is in trial mode; alarming if the gap should be smaller. +- **Action items.** For each anomaly, identify the cause. Either the instrumentation is broken (fix it), the business changed (update expectations), or the event semantics drifted (version it). + +Cadence. Quarterly minimum. Real-time alerts on the highest-volume events for major deviations. + +--- + +## 3. Dashboard freshness review + +Goal. Identify dashboards that have rotted. + +Steps. + +- **Pull the dashboard inventory** from the analytics tool or BI platform. +- **Check last-viewed dates.** Dashboards not viewed in the last 90 days are candidates for deprecation. Dashboards not viewed in the last 180 days are almost always stale. +- **Check last-edited dates.** A dashboard last edited 18 months ago whose underlying schema changed is silently broken. Audit whether the dashboard's metrics still compute correctly. +- **Check ownership.** Every dashboard should have a named owner. Dashboards with no owner or with an owner who has left the company need reassignment or deprecation. +- **Spot-check key metrics.** Pick 5 to 10 dashboards. Compute the same metric directly from the warehouse. Compare. Drift over 5% needs investigation. +- **Action items.** Reassign orphan dashboards. Deprecate stale dashboards. Fix or rewrite dashboards that have drifted from underlying truth. + +Cadence. Quarterly. + +--- + +## 4. Owner assignment audit + +Goal. Every event, dashboard, cohort, and saved query has a named owner who can answer questions about it. + +Steps. + +- **Pull the ownership map** for events, dashboards, cohorts, saved queries. Most analytics tools support tagging or property fields for owner. +- **Identify orphans.** Items with no owner. Items whose owner has left the company. +- **Reassign.** For each orphan, assign a new owner or deprecate. Owner means "the person who can explain why this exists and what depends on it." It is not a vanity tag. +- **Document the chain of custody.** If the original owner left and the new owner is unfamiliar with the history, write down what you know. +- **Action items.** Update the ownership tags. Notify owners of items they are now responsible for. Set up a review cycle (every 6 months minimum) for owners to confirm or release ownership. + +Cadence. Quarterly minimum. Whenever someone leaves the team, immediately for their owned items. + +--- + +## 5. Deprecation candidates + +Goal. Identify and remove instrumentation, cohorts, and dashboards that no longer serve a purpose. + +Steps. + +- **Identify candidate events.** Events whose volume is below 10 per week. Events not referenced in any active dashboard or query in the last 90 days. Events that are duplicate or near-duplicate of other events. +- **Identify candidate cohorts and saved queries.** Items not used in the last 90 days. Items whose source data is now stale. +- **Identify candidate dashboards.** Already covered in step 3; gather candidates here. +- **Soft deprecation.** Tag items as deprecated; remove from default views. Wait 30 days. If anyone notices, reverse the deprecation; if nobody notices, hard delete. +- **Communicate.** Post the deprecation list to the data channel. Anyone with a use case has 14 days to push back. +- **Action items.** Soft deprecate. Wait. Hard delete on the next audit if no objections. + +Cadence. Quarterly. Hard deletion happens at the next audit, not the same one. + +--- + +## The audit deliverable + +Each quarterly audit produces a written report with five sections matching the steps above. The report includes. + +- **What changed since the last audit.** Events added, removed, renamed. Schema migrations completed. +- **Drift identified.** Events firing without schema entries. Property type mismatches. Volume anomalies. +- **Decisions made.** What was fixed, what was deprecated, what was deferred. +- **Open items.** Drift not yet resolved. Pending decisions. Owners reassigned but not yet confirmed. +- **Forward planning.** Schema changes anticipated next quarter. Dashboards likely to be migrated. Events likely to be deprecated. + +The report goes to the data team and the eng leads. It does not need to go to the entire company; the value is in the discipline of writing it. + +--- + +## When to skip an audit + +Never. The cost of skipping a quarter compounds. The team that audits twice a year ends up doing 3x the work each audit; the team that audits quarterly maintains a steady state. + +The exception. A team in a 30-day sprint to launch a major product version may defer one audit by 4 to 6 weeks. After that, the audit is overdue and the discipline is at risk. + +--- + +## What the audit is not + +Three things to avoid. + +- **Not a witch hunt.** The audit identifies drift, not blame. Many drift items are produced by good-faith engineering decisions that did not include the analytics-debt cost. +- **Not perfectionism.** Some drift is acceptable. Aim for 95% clean, not 100%. Spending the audit cycle chasing the last 5% leaves real problems unaddressed. +- **Not silent.** The audit produces a deliverable. Without the deliverable, the audit happened in someone's head; it does not transfer to the next quarter or the next team. diff --git a/skills/product-analytics-setup/references/naming-convention-reference.md b/skills/product-analytics-setup/references/naming-convention-reference.md new file mode 100644 index 0000000..c4572a7 --- /dev/null +++ b/skills/product-analytics-setup/references/naming-convention-reference.md @@ -0,0 +1,125 @@ +# Naming convention reference + +A complete style guide. Pick one convention; enforce it via CI lint. + +--- + +## The canonical conventions + +**snake_case** for events and properties. `user_signed_up`, `cart_value`, `trial_day`. + +**Past tense, action-oriented** for events. `checkout_completed`, not `complete_checkout` or `completing_checkout`. + +**Object-action format** for events. Noun then verb. `video_played`, `form_submitted`, `email_opened`. + +**Boolean prefix** for boolean properties. `is_`, `has_`, `can_`. `is_admin`, `has_trial`, `can_invite`. + +**Counting suffix** for count properties. `_count` or `_total`. `seat_count`, `total_purchases`, `signup_count`. + +**Money in smallest unit** with currency named. `price_cents` not `price` (and currency on `currency` property). + +**Timestamp suffix** for date-time properties. `_at` for absolute timestamps. `created_at`, `last_active_at`. `_s` or `_ms` for durations. `time_since_signup_s`. + +**Period suffix** for relative-time properties. `_days`, `_weeks`. `inactive_days_count`, `trial_length_days`. + +--- + +## Do and don't + +| Don't | Do | Why | +|---|---|---| +| `Sign Up Completed` | `signup_completed` | snake_case, no spaces. URL-safe. | +| `userSignedUp` | `user_signed_up` | snake_case wins by default; consistent across the platform. | +| `signup` (event) | `user_signed_up` | Past tense, object-action. Reads as "this happened." | +| `complete_checkout` | `checkout_completed` | Past tense for events. | +| `completing_checkout` | `checkout_completed` | Past tense, not progressive. | +| `Sign Up` | `signup` or `signed_up` | Pick one form for the same concept. Document it. | +| `price: "$19.99"` | `price_cents: 1999` plus `currency: "USD"` | Money in smallest unit. Currency separate. | +| `quantity: "5"` | `quantity: 5` | Numbers as numbers, not strings. | +| `is_premium: "yes"` | `is_premium: true` | Booleans as booleans. | +| `viewed: 1` | `is_viewed: true` | If it is yes/no, it is boolean, not 0/1. | +| `created: "5/5/2026"` | `created_at: "2026-05-05T14:30:00Z"` | ISO 8601, always. UTC. | +| `tags: "a,b,c"` | `tag_list: ["a", "b", "c"]` | Arrays for bounded lists, not delimiter-strings. | +| `signup_source` (one event) plus `source` (another event) | `signup_source` plus `referral_source` | Disambiguate when the same name means different things. | +| `User Signed Up` (event), `signupCompleted` (event), `SIGN_UP` (event) | `user_signed_up` (event), `signup_completed` (event) | Pick one casing, stick to it. | +| `mailchimp_email_opened` | `email_opened` plus `provider: "mailchimp"` property | Brand-neutral event names; vendor as a property. | +| `feature_x_clicked` | `feature_x_used` | Track usage, not button clicks. UI events are noise. | + +--- + +## Boolean property prefixes + +The prefix should make the property read as a yes-or-no question. + +- `is_admin` reads as "is admin?" Yes or no. +- `has_trial` reads as "has trial?" Yes or no. +- `can_invite` reads as "can invite?" Yes or no. +- `should_notify` reads as "should notify?" Yes or no. + +What NOT to do. + +- `admin: true`. Reads as "admin is true." Awkward in queries. +- `premium: 1`. Reads as a count, not a yes-or-no. +- `trial: "yes"`. String, not boolean. + +--- + +## Time, date, and duration suffixes + +| Suffix | Meaning | Example | +|---|---|---| +| `_at` | Absolute timestamp (ISO 8601 UTC) | `created_at`, `last_active_at`, `event_timestamp` | +| `_s` | Duration in seconds | `time_in_step_s`, `session_duration_s` | +| `_ms` | Duration in milliseconds | `response_time_ms` | +| `_days` | Duration in days (integer) | `inactive_days_count`, `trial_length_days` | +| `_weeks` | Duration in weeks (integer) | `weeks_since_signup` | +| `_months` | Duration in months (integer) | `months_active` | + +Mixing units across the schema produces bugs. Pick one unit per concept and document it. + +--- + +## Money + +Two rules. + +1. **Smallest unit, integer.** `price_cents`, `mrr_cents`, `total_revenue_cents`. Float arithmetic on money produces rounding errors. +2. **Currency named separately.** `currency: "USD"`. Do not assume USD; international users break the assumption. + +When the smallest unit varies (yen has no decimals; bitcoin has 8), pick a precision and document it. The integer math discipline still applies. + +--- + +## Identifiers + +Three identifier patterns. + +- **Stable IDs** are immutable. `user_id`, `account_id`, `product_id`. Use UUIDs or a system-generated identifier. +- **Human-readable names** are mutable. `product_name`, `account_name`. Useful for reporting; never use as a join key. +- **Display IDs** are user-visible. `invoice_number`, `order_number`. Often distinct from the database primary key. + +Always include a stable ID in event payloads. Optionally include the human-readable name for reporting convenience. + +--- + +## What NOT to encode in event names + +Three categories of detail belong on properties, not in event names. + +1. **State or status.** Not `user_active`, `user_inactive`. Use `user_signed_in` (event) plus `status` (user property). +2. **Variant or treatment.** Not `signup_variant_a`. Use `user_signed_up` (event) plus `experiment_variant` (property). +3. **Source or channel.** Not `signup_from_facebook`. Use `user_signed_up` (event) plus `acquisition_channel: "facebook"` (property). + +The principle. Event names answer "what happened?" Properties answer "with what context?" + +--- + +## Enforcement + +A naming convention without enforcement decays. Two patterns. + +**CI lint.** A schema definition (TypeScript interface, JSON Schema) plus a CI step that rejects events whose payload does not match. The lint catches new violations before they hit production. + +**Code review checklist.** PRs that add or modify events include a snippet showing the event name, properties, and types. The reviewer compares against the naming convention reference and the existing taxonomy. + +Without enforcement, the convention becomes documentation that nobody reads. With enforcement, it becomes a constraint that the codebase respects. diff --git a/skills/product-analytics-setup/references/north-star-metric-selection.md b/skills/product-analytics-setup/references/north-star-metric-selection.md new file mode 100644 index 0000000..979ffe8 --- /dev/null +++ b/skills/product-analytics-setup/references/north-star-metric-selection.md @@ -0,0 +1,159 @@ +# North Star metric selection + +Rules for picking a North Star metric (NSM), examples by product type, anti-patterns, and migration patterns when changing NSM. + +The principle. The NSM is the single number the team optimizes against. Picking the wrong number focuses the team on the wrong work for as long as the team uses it. + +--- + +## NSM selection rules + +A trustworthy NSM passes four tests. + +1. **Reflects user value, not company value alone.** Revenue is company value; the NSM should track an action that delivers user value. Revenue can be the trailing measure; the NSM is the leading driver. +2. **Captures the core action that, if it grows, the business grows.** The NSM should be cause-correlated with revenue growth, retention, and any other business goal. If you double the NSM and the business does not improve, the NSM is wrong. +3. **Measurable consistently across time.** The definition should not drift. If the NSM definition changes every quarter, year-over-year comparison is impossible. +4. **Hard to game.** The team should not be able to grow the NSM via shortcuts that do not deliver user value. A gameable NSM produces local maxima that the team optimizes toward at the expense of the actual mission. + +--- + +## Examples by product type + +### Engagement-driven products + +The product creates ongoing value through repeated use. + +| Product | NSM | Why it works | +|---|---|---| +| Slack | Messages sent in workspaces of 3+ active users per week | Captures recurring value; harder to game than DAU; size threshold filters out trial-only users. | +| Figma | Weekly active editors | The action that delivers value (creating in Figma); active editors filters out viewers who do not get full product value. | +| Notion | Weekly content blocks created per workspace | Captures the core verb (creating); per-workspace normalizes for team size variance. | +| Linear | Weekly issues created per workspace | The product use case is project tracking; issues created is the load-bearing action. | + +### Transaction-driven products + +The product makes money on each transaction. + +| Product | NSM | Why it works | +|---|---|---| +| Airbnb | Nights booked (not bookings) | Nights captures the value delivered to hosts and guests; bookings count is gameable via short stays. | +| Uber | Rides completed (not requests) | Completion includes the driver-side fulfillment; requests alone misses the supply-side metric. | +| Etsy | GMV per active buyer | GMV per buyer is more stable than total GMV; it tracks user value rather than top-line growth alone. | + +### Conversion-driven products (SaaS subscription) + +The product is sold via subscription; the NSM tracks recurring engagement that drives renewal. + +| Product | NSM | Why it works | +|---|---|---| +| HubSpot | Activated workspaces (defined as workspaces using 3+ products) | Multi-product use is the activation signal that drives expansion revenue. | +| Stripe (developer-side) | Production payments processed per merchant per week | Captures the core transaction; per-merchant per-week filters for active integrations. | +| Calendly | Meetings booked via Calendly per user per week | The exact value delivered (meetings booked) and the recurring cadence. | + +### Content-driven products (media, publishing) + +The product delivers value through content consumption. + +| Product | NSM | Why it works | +|---|---|---| +| Spotify | Hours listened per active user | Hours captures depth of engagement; per active user normalizes for catalog growth. | +| YouTube (creator-side) | Watch time per video per audience cohort | Watch time is the core metric that drives ads and creator earnings. | +| Substack (writer-side) | Paid subscribers added per month | The action that converts to revenue; not just total subscribers (which is lagging). | + +--- + +## Anti-patterns + +Six NSMs that consistently produce the wrong incentives. + +### Bad NSM 1: signups + +Captures top-of-funnel volume, not value. A team optimizing for signups loosens activation criteria and chases low-quality acquisition channels. The NSM grows; the business does not. + +### Bad NSM 2: revenue + +Lagging, not action-oriented. The team can optimize against revenue only by changing pricing or sales tactics. Revenue is the trailing outcome; the NSM should be the leading action that produces revenue. + +### Bad NSM 3: DAU (daily active users) + +Useful for engagement-driven products with a daily cadence. Misleading for products with a longer cadence (weekly, monthly). DAU on a B2B SaaS often shows an unhealthy daily ritual the product does not actually need. + +### Bad NSM 4: page views or sessions + +Captures traffic, not value. A team optimizing for page views or sessions loosens content quality and adds engagement loops that do not deliver user value. + +### Bad NSM 5: feature usage + +The team optimizes for "feature X used" by promoting feature X aggressively. The feature usage grows; the underlying user value may not. NSM should capture cross-cutting value, not feature-specific use. + +### Bad NSM 6: reviews or NPS + +Captures sentiment, not value. NPS is useful as a health metric but a poor NSM because it is heavily influenced by survey design and customer-service interactions, neither of which the product team controls directly. + +--- + +## Supporting metrics framework + +The NSM does not stand alone. Around it lives a framework of input metrics and health metrics. + +### One NSM + +The single number the team optimizes against. + +### Three to five input metrics + +The metrics that drive the NSM. If the input metrics improve, the NSM should follow. + +For "weekly active editors" (Figma's NSM): +- Signups per week (the top of the funnel) +- Signup-to-active conversion rate (the activation step) +- Week-over-week active retention (the repeat-use step) + +For "messages sent in workspaces of 3+ active users per week" (Slack's NSM): +- Workspaces created per week +- Workspaces reaching 3+ active members +- Messages per active workspace per week + +The team's roadmap should map every initiative to one or more input metrics. + +### Five to ten health metrics + +Metrics that warn of problems. They should not regress while the NSM grows. + +- Monthly churn rate +- Account-level concentration (is growth coming from one big customer?) +- Support ticket volume per active user +- Latency or error rate +- Activation rate (signup-to-NSM-action) + +If any health metric regresses while the NSM grows, the team should investigate before declaring success. + +--- + +## Migration patterns when changing NSM + +The NSM should change rarely. When it does, the migration is high-risk. + +### Pattern 1: phased migration + +Run both NSMs in parallel for a quarter. Track team behavior; document where the new NSM produces different incentives. Decide based on real evidence, not speculation. + +### Pattern 2: shadow mode first + +The new NSM is tracked privately by the data team. The team continues to optimize against the old NSM. After 90 days, the data team reports on the divergence. Public switch happens only if the new NSM clearly aligns better with business outcomes. + +### Pattern 3: replace plus reinforce + +The new NSM replaces the old. The old metric becomes a health metric (still tracked, no longer the primary target). Over the next 6 months, ensure the old metric does not regress while the new NSM grows. + +--- + +## When to refuse to change the NSM + +Three signs that a proposed NSM change is wrong. + +1. **The change is reactive to a single quarter's bad numbers.** "Our NSM went down so we should change the NSM" is not a reason to change the NSM. +2. **The proposed new NSM is gameable.** A new NSM that the team can grow without delivering user value is worse than the existing NSM, even if the old one is imperfect. +3. **The change has no concrete decision the team will make differently.** If switching from old NSM to new NSM does not change which initiatives the team prioritizes, the change is theater. + +The NSM should be stable for years. Change it when the business model changes substantively or when the existing NSM is producing demonstrably wrong incentives. diff --git a/skills/product-analytics-setup/references/property-design-patterns.md b/skills/product-analytics-setup/references/property-design-patterns.md new file mode 100644 index 0000000..7c75d02 --- /dev/null +++ b/skills/product-analytics-setup/references/property-design-patterns.md @@ -0,0 +1,168 @@ +# Property design patterns + +Event-level vs user-level properties, with type discipline and a worked example. + +The principle. Event-level properties describe a specific event. User-level properties describe a user across all events. Mixing them up creates payload bloat, schema drift, and reporting confusion. + +--- + +## Event-level vs user-level + +**Event-level properties** belong on the event payload. They describe the specific event, snapshot at the moment it fires. + +- `cart_value` on `checkout_completed` +- `item_count` on `checkout_completed` +- `payment_method` on `checkout_completed` +- `discount_code` on `checkout_completed` +- `referrer_source` on `user_signed_up` + +**User-level properties** belong on the user profile. They describe the user over time. Set them once; the analytics tool joins them onto every event the user fires. + +- `subscription_tier` +- `acquisition_channel` +- `lifetime_value` +- `account_role` +- `is_admin` +- `last_active_at` + +The trap. Putting user-level properties on every event payload. Three problems. + +1. **Payload bloat.** Every event carries the same `subscription_tier` value. Multiplied across millions of events, the storage and bandwidth cost is real. +2. **Schema drift when the value changes.** A user upgrades mid-session. Some events have `subscription_tier: free`; later events have `subscription_tier: pro`. Reporting becomes ambiguous about which value to use. +3. **Reporting confusion.** Analyst writes "WHERE subscription_tier = 'pro'" thinking they are filtering users. The query actually filters events, returning a different cohort. + +The fix. Set user-level properties on the user profile via the platform's identify/track-user API. Let the analytics tool perform the join. + +--- + +## Type discipline + +Property types matter. The analytics tool will accept any value, but the reporting breaks when types are inconsistent. + +**Strings** for enumerable values. + +- `status`, `tier`, `channel`, `region`, `category` +- Bounded sets. Document the allowed values in the schema. +- Wrong: storing numbers as strings. `quantity: "5"` breaks every numeric aggregation. + +**Numbers** for actual numbers. + +- `count`, `value`, `duration_s`, `score` +- Cents (or smallest unit) for money. Never floats. `price_cents: 1999`, not `price: 19.99`. +- Wrong: `trial_day: "day 7"`. Use `trial_day: 7`. + +**Booleans** for actual booleans. + +- `is_admin`, `has_trial`, `is_new_user` +- Two values: `true` and `false`. Nothing else. Not "yes"/"no", not 1/0, not strings. +- Prefix discipline: `is_`, `has_`, `can_`. Reading the property name should suggest a yes/no question. + +**Timestamps** in ISO 8601, always. + +- `created_at`, `last_active_at`, `event_timestamp` +- Format: `2026-05-05T14:30:00Z` (UTC, with the Z suffix). +- Wrong: Unix timestamps as strings, locale-specific formats, or any other variant. ISO 8601 across the entire schema. +- Suffix discipline: `_at` for timestamps, `_s` or `_ms` for durations. + +**Arrays** rarely. + +- An array property usually means you should split into multiple events with one item per event. +- Example: instead of `cart.items: [item_a, item_b, item_c]` on `checkout_completed`, fire one `item_purchased` event per item plus one `checkout_completed` event with the item count. +- Exception: small bounded arrays where the use case is clear (e.g., `tag_list: ["urgent", "billing"]`). + +--- + +## Worked example: product_viewed event + +A `product_viewed` event fires when a user views a product detail page in an e-commerce app. + +### Wrong design + +```json +{ + "event": "Product Viewed", + "user_id": "u_12345", + "product": "Premium Hoodie", + "price": "$49.99", + "category": "Apparel", + "user_subscription_tier": "Premium", + "user_lifetime_purchases": 8, + "user_acquisition_source": "Meta", + "is_premium_user": "true", + "viewed_at": "5/5/2026 2:30 PM", + "tags": "summer, hoodie, sale" +} +``` + +Problems. + +- Event name uses spaces and mixed case. `Product Viewed` should be `product_viewed`. +- `price` is a money string with currency symbol. Should be `price_cents: 4999`. +- User-level properties on the event: `user_subscription_tier`, `user_lifetime_purchases`, `user_acquisition_source`, `is_premium_user`. These belong on the user profile. +- `is_premium_user` is a string `"true"`, not a boolean. +- `viewed_at` is a locale-specific date format. Should be ISO 8601: `2026-05-05T14:30:00Z`. +- `tags` is a comma-delimited string. Should be an array of strings, or split into separate events. +- `product` is the human-readable name; lacks the stable identifier. Should include `product_id`. + +### Right design + +User profile (set via `identify`): + +```json +{ + "user_id": "u_12345", + "subscription_tier": "premium", + "lifetime_purchase_count": 8, + "acquisition_channel": "meta", + "is_premium": true, + "last_active_at": "2026-05-05T14:30:00Z" +} +``` + +Event payload (`product_viewed`): + +```json +{ + "event": "product_viewed", + "user_id": "u_12345", + "product_id": "p_premium_hoodie_v2", + "product_name": "Premium Hoodie", + "price_cents": 4999, + "currency": "USD", + "category": "apparel", + "tag_list": ["summer", "hoodie", "sale"], + "viewed_at": "2026-05-05T14:30:00Z" +} +``` + +Differences. + +- Event name is `snake_case`. +- Money in cents with currency named. +- User-level properties live on the user profile, not the event. The analytics tool joins them. +- Boolean is an actual boolean. +- Timestamp is ISO 8601 UTC. +- Tags are a bounded array (acceptable here because the use case is faceted filtering). +- Stable identifier (`product_id`) included alongside the human-readable name. + +--- + +## When to put a property on every event + +A small set of properties should appear on every event regardless of category. + +- `app_version` and `platform` (web, ios, android, desktop) +- `device_type` and `device_id` +- `session_id` +- `experiment_assignments` if the user is in active experiments + +These are technically event-level (they describe the context of the event) but they are required across every event for path analysis and segmentation. + +--- + +## Common property design mistakes + +- **Property names that are also event names.** `signup` as a property and `signup` as an event creates queries that depend on context. Disambiguate. +- **Free-text properties for things that should be enums.** "Where did you hear about us?" with free-text answers produces 47 unique values that map to 5 actual channels. Force the enum at collection time. +- **Storing PII in properties.** Email addresses, full names, phone numbers should not be in event properties. Use a hashed identifier and look up PII separately. +- **Reusing property names across events with different meanings.** `source` on `user_signed_up` means acquisition source. `source` on `email_opened` means email campaign source. Same name, different meaning, breaks queries. diff --git a/skills/product-analytics-setup/references/schema-versioning-patterns.md b/skills/product-analytics-setup/references/schema-versioning-patterns.md new file mode 100644 index 0000000..cd610a4 --- /dev/null +++ b/skills/product-analytics-setup/references/schema-versioning-patterns.md @@ -0,0 +1,167 @@ +# Schema versioning patterns + +Schema changes are inevitable. The discipline is distinguishing safe changes from breaking ones, then versioning the breaking ones. + +--- + +## Additive vs breaking changes + +**Additive changes** are safe. They preserve existing dashboards and queries. + +- New event. `feature_y_used` ships alongside existing events. Old dashboards continue to work. +- New property on an existing event. `checkout_completed` gains a `discount_code` property. Old dashboards ignore it; new dashboards can use it. +- New value in an enum. The `acquisition_channel` enum gains `"tiktok"`. Old dashboards may filter incorrectly if they hard-code values; usually low-risk. + +**Breaking changes** require migration. + +- Renamed event. `signup_complete` becomes `user_signed_up`. Every dashboard, query, and saved cohort referencing the old name breaks. +- Removed property. `cart_value_cents` is removed because it was redundant with `total_value_cents`. Queries referencing the removed property fail. +- Changed property type. `price` was a string; now it is a number. Existing queries cast or compare differently. +- Narrowed enum. `acquisition_channel` previously had `"organic"` and `"paid"`; the new schema removes `"organic"` and replaces it with `"organic_search"` and `"organic_social"`. Old queries break. +- Changed semantics. The same event name now fires under different conditions. The dashboard reading "weekly active users" silently gets a different number. + +The rule. If old code or old queries continue to work after the change, it is additive. Otherwise, it is breaking. + +--- + +## The `_v2` suffix pattern + +Versioning in the event name makes the change visible at every layer. + +``` +checkout_completed <- v1, fires alongside v2 during transition +checkout_completed_v2 <- new semantics, new schema +``` + +The transition. + +1. **Phase 1: ship v2 alongside v1.** Both events fire. Dashboards continue to read v1. New queries can use v2. +2. **Phase 2: migrate dashboards.** Update every saved query, dashboard tile, and downstream consumer to read v2. Document each migration. +3. **Phase 3: deprecate v1.** Stop firing v1. Mark it deprecated in the schema. Remove from event tracking instrumentation. +4. **Phase 4: cleanup.** Six months after deprecation, remove v1 from any historical reference documentation. Existing v1 data in the warehouse stays for historical analysis but is not used in current dashboards. + +Typical transition window. 90 days from v2 ship to v1 deprecation. Longer if the team is small or the dashboard inventory is large. + +--- + +## The data contract idea + +The canonical schema lives in code, not in the analytics tool. + +### TypeScript interface + +```typescript +// schema/events.ts + +export interface CheckoutCompletedEvent { + event: "checkout_completed"; + user_id: string; + account_id: string; + cart_value_cents: number; + currency: string; + item_count: number; + payment_method: "card" | "paypal" | "apple_pay" | "google_pay"; + discount_code?: string; + event_timestamp: string; // ISO 8601 UTC +} + +export interface UserSignedUpEvent { + event: "user_signed_up"; + user_id: string; + account_id: string; + signup_source: "homepage" | "pricing_page" | "blog" | "invite" | "other"; + referrer_source: string | null; + event_timestamp: string; +} + +export type AnalyticsEvent = + | CheckoutCompletedEvent + | UserSignedUpEvent; + // ... etc. +``` + +The interface is the contract. TypeScript catches type mismatches at compile time. The CI pipeline runs the type check. + +### JSON Schema + +For non-TypeScript projects, JSON Schema serves the same role. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "checkout_completed", + "type": "object", + "required": ["event", "user_id", "account_id", "cart_value_cents", "currency", "item_count", "payment_method", "event_timestamp"], + "properties": { + "event": { "const": "checkout_completed" }, + "user_id": { "type": "string" }, + "account_id": { "type": "string" }, + "cart_value_cents": { "type": "integer", "minimum": 0 }, + "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, + "item_count": { "type": "integer", "minimum": 1 }, + "payment_method": { "enum": ["card", "paypal", "apple_pay", "google_pay"] }, + "discount_code": { "type": "string" }, + "event_timestamp": { "type": "string", "format": "date-time" } + } +} +``` + +A CI step validates events against the schema before they ship. + +--- + +## CI lint patterns + +Three lint rules catch most schema drift. + +1. **Type validation.** Every event payload validates against its declared type. Failed validations fail the build. +2. **Naming convention check.** Event names match snake_case. Property names match snake_case. Boolean properties have `is_`, `has_`, or `can_` prefix. +3. **Forbidden-event check.** Removed or deprecated events do not appear in the codebase. The deploy that adds a deprecated event back fails. + +Implementation. A pre-commit hook plus a GitHub Actions workflow plus a runtime sampling check (random 1% of events validated against the schema in production; failures alert). + +--- + +## Migration patterns for breaking changes + +Three common migration patterns. + +### Pattern 1: rename + +The event name changes. The semantics are the same. + +1. Ship v2 with the new name; old name continues to fire. +2. Migrate dashboards, queries, saved cohorts. +3. Deprecate v1. + +### Pattern 2: split + +One event splits into two or more events with narrower meanings. + +1. Ship the new events; the old event continues to fire alongside. +2. Update tracking code to fire the appropriate new event instead of the old one. +3. Migrate dashboards. +4. Deprecate the old event. + +Example. `subscription_changed` splits into `subscription_upgraded` and `subscription_downgraded`. Both new events provide more analytical power than the old single event. + +### Pattern 3: merge + +Two events merge into one event with a discriminating property. + +1. Ship the new event with the discriminating property. +2. Update tracking code to fire the new event with the appropriate property value. +3. Migrate dashboards (often: queries that filtered on event name now filter on property value). +4. Deprecate the old events. + +Example. `signup_via_facebook` and `signup_via_google` merge into `user_signed_up` with `auth_method: "facebook" | "google"`. + +--- + +## Common schema versioning mistakes + +- **Renaming events without versioning.** The dashboards break overnight; the team blames the analytics tool. +- **Skipping the transition period.** v2 ships and v1 stops firing the same day. Historical analysis of v1 data is fine, but in-flight queries break. +- **Versioning everything pre-emptively.** `event_v3_v2` is overkill. Version when semantics change, not at every iteration. +- **Letting the analytics tool be the schema source of truth.** The tool's "events you have ever fired" list is a graveyard, not a contract. Maintain the schema in code; export to the tool. +- **No CI enforcement.** The discipline becomes an etiquette that decays as the team grows. Enforcement is the only thing that scales. diff --git a/skills/product-configurator-design/SKILL.md b/skills/product-configurator-design/SKILL.md new file mode 100644 index 0000000..593b80c --- /dev/null +++ b/skills/product-configurator-design/SKILL.md @@ -0,0 +1,289 @@ +--- +name: product-configurator-design +description: "Designing build-your-own product configurators (Tesla-style, custom-pricing, plan-builders) with constraint logic, real-time pricing, validation, and save-and-share mechanics. Honest about infinite-options (decision paralysis), canned-bundles-only (no real customization), and guided-configuration (smart defaults plus meaningful constraints plus escape hatches) patterns. Triggers on configurator design, build-your-own, custom configuration, plan builder, product customizer, configuration tool. Also triggers when users abandon mid-configuration, when configurator conversion is poor, or when a configurator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive product configurators. Distinguishes infinite-options (decision paralysis from too many options) from canned-bundles-only (no real customization) from guided-configuration (smart defaults plus meaningful constraints plus escape hatches)" +display_order: 12 +--- + +# Product Configurator Design + +A senior product marketing director's playbook for designing build-your-own product configurators. Tesla-style vehicle configurators, custom-pricing builders, plan-builders, product customizers. Constraint logic, real-time pricing, validation, save-and-share mechanics. The discipline of building a configurator that produces configurations users actually commit to. + +Most configurators fail in one of two ways. They expose every parameter at full granularity (47 toggles, 12 sliders) and produce decision paralysis; users abandon halfway through. Or they pretend to be configurators but are actually three pre-built bundles labeled "Custom"; the configurator framing was marketing while the product is bundles. + +The configurators that work do something different. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations and surface why; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Users feel guided rather than overwhelmed. + +The voice is the senior product marketing director who has watched configurators double conversion when redesigned with smart defaults and watched them collapse when "more options" were added without constraint logic. Practical, opinionated about the constraints that protect users from themselves, willing to call out when canned bundles are the right answer. + +When to use this skill: scoping a build-your-own configurator for the first time, auditing a configurator with high abandonment, designing the constraint logic that prevents invalid combinations, or deciding which parameters earn exposure vs which should default. + +--- + +## What this skill covers + +This skill spans build-your-own product configurators. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number from inputs. This skill builds a product configuration with multiple decisions. +- `comparison-tool-design` is comparing known options. This skill builds a custom option. +- `multi-step-form-design` is data capture. This skill is configuration design. +- **`product-configurator-design` (this skill)** is constraint logic, real-time pricing, validation, save-and-share, and configurator-to-cart handoff. +- `pm-spec-writing` is the spec for engineers building the configurator. + +The audience: product marketers, growth marketers, ecommerce teams, B2B teams shipping configurable products, agencies running configurator work for clients. + +Out of scope: calculator design (covered by `calculator-design`); comparison tools (covered by `comparison-tool-design`); the engineering implementation; specific configurator-platform configurations (those stay implementation-side). + +--- + +## The configurator decision: when configurators earn investment vs when bundles suffice + +Before designing the configurator, decide whether a configurator is the right answer. + +**Configurators earn investment when:** + +- The product has genuinely customizable parameters that affect outcome and cost. +- The audience values customization beyond what bundles offer. +- The team can support the configuration logic (validation, pricing, fulfillment). +- The combinatorial space is meaningful but constrained (not literally infinite). + +**Configurators do NOT earn investment when:** + +- The product is essentially bundles. Calling them "configurations" is marketing, not product. +- The audience does not value customization. Some audiences want to choose from curated options, not build. +- The combinatorial space is so large that no audience can navigate it. +- Customization produces invalid combinations the team cannot prevent. +- A simpler comparison or selection tool would serve. + +The decision is not "should we have a configurator"; it is "is the configurator the right tool for this product and audience." + +Detail in [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md). + +--- + +## Infinite-options vs canned-bundles-only vs guided-configuration + +The keystone framing. + +**Infinite-options.** Every parameter exposed at full granularity. 47 toggle switches and 12 sliders. Decision paralysis. Users abandon halfway through; few complete a configuration. Cost: design effort produces a configurator nobody completes; conversion suffers. + +**Canned-bundles-only.** "Configurator" that is actually three pre-built bundles labeled Basic/Pro/Enterprise. No real customization. The configurator framing was marketing; the product is bundles. Cost: audience that came expecting customization feels deceived; conversion suffers because expectations did not match reality. + +**Guided-configuration.** Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Cost: design effort upfront is significant; conversion typically improves meaningfully because users complete configurations they commit to. + +The litmus test. Hand the configurator to a stranger in the target audience. Do they reach a configuration they would actually buy in under 5 minutes without expert help? If yes, guided-configuration. If they paralyze at the options, infinite-options. If they only see bundles, canned-bundles-only. + +--- + +## Default-configuration design + +The starting point. + +**The principle.** The configurator opens with a sensible default configuration. The user adjusts from there. + +**Default selection.** + +- The configuration most audiences would choose. +- Reflects audience research (sales-call mining, prior configurations). +- Inferable from referrer, query, or stated preference. + +**Default presentation.** + +- Default visible immediately; user sees a complete configuration with price. +- Adjust controls obvious; user knows what is changeable. +- Reset-to-default available; users who experiment can return. + +**The blank-canvas trap.** Configurator opens empty; user must build from scratch. Decision paralysis at the start. + +**The cure.** Default-heavy. The user adjusts; never builds from zero. + +Detail in [`references/default-configuration-design.md`](references/default-configuration-design.md). + +--- + +## Constraint logic + +Preventing invalid combinations; surfacing why. + +**The principle.** The configurator should not let users build invalid configurations (combinations that cannot ship, cannot be priced, or do not work together). When constraints engage, the configurator surfaces why. + +**Constraint patterns.** + +- **Hard constraints.** "Option A and Option B are incompatible." Configurator prevents the combination; explains why. +- **Soft constraints.** "Combining Option A with Option C is unusual but possible." Configurator allows; warns. +- **Implication constraints.** "Selecting Option A requires Option D." Configurator auto-includes D; explains. +- **Capacity constraints.** "This configuration exceeds shipping capacity." Configurator caps; explains. + +**Constraint communication.** + +- Why this constraint engaged. +- What user can do (different option, contact for custom). +- No friction-only blocking; always offer a path. + +**The over-constrained trap.** Too many constraints; user feels boxed in. + +**The under-constrained trap.** User builds configuration that fails at checkout or fulfillment. + +Detail in [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md). + +--- + +## Real-time pricing and impact display + +Pricing that responds to choices. + +**The principle.** Price updates as the user adjusts. The user sees the cost impact of each choice immediately. + +**Strong pricing display.** + +- Total price prominent and updated in real time. +- Per-choice impact visible ("Adds $X" or "Saves $X"). +- Breakdown available ("How is this priced"). +- Currency and locale appropriate. + +**Weak pricing display.** + +- Price hidden until the end. +- Per-choice impact invisible; user does not know what each option costs. +- Breakdown not available; total is opaque. + +**The price-shock trap.** User configures heavily; reaches checkout; sees a price they did not expect; abandons. + +**The cure.** Price visible throughout. No surprises at checkout. + +Detail in [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md). + +--- + +## Validation and error patterns + +When the configurator catches invalid input. + +**The principle.** Validation should be helpful, not punitive. + +**Validation patterns.** + +- **Inline validation.** Error appears next to the invalid choice. +- **Pre-emptive validation.** Constraint logic prevents the error from being possible. +- **Final validation.** Pre-checkout review surfaces any remaining issues. + +**Error communication.** + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +**The validation-strict trap.** Validation rejects valid edge-case inputs. + +**The validation-loose trap.** Configurator accepts inputs that fail downstream. + +Detail in [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md). + +--- + +## Save-and-share mechanics + +Configurations users return to or send to others. + +**The principle.** Configurators that serve real decision-making produce configurations users want to save and share. + +**Save patterns.** + +- **Email-link save.** User enters email; configuration link emailed. +- **Account-based save.** Logged-in users save automatically. +- **Anonymous-session save.** Browser-based persistence. + +**Share patterns.** + +- **Shareable URL.** Configuration encoded in URL; share via any channel. +- **Embed code.** Configuration embeddable on other sites or in proposals. +- **Email share.** Direct email-to-recipient with configuration. + +**Why save-and-share matters.** + +- Multi-decision purchases require deliberation. +- B2B configurations often need stakeholder review. +- Returning users continue rather than restart. + +Detail in [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md). + +--- + +## Configurator-to-cart handoff + +When the user commits. + +**The principle.** Handoff from configurator to cart should preserve the configuration entirely. + +**Handoff patterns.** + +- Configuration becomes the cart item. +- Cart shows the configuration summary. +- Edit-from-cart returns to configurator with state preserved. + +**The handoff failure.** Configuration partially preserved; cart shows a generic SKU; user cannot tell if their custom build is reflected. + +**The cure.** Handoff loop closed. Configuration visible in cart; price matches; edits possible. + +Detail in [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-configurator-failures.md`](references/common-configurator-failures.md). + +- "Users abandon halfway through configuration." Likely infinite-options pattern; too many decisions. +- "Configurator generates valid-looking configs that fail at fulfillment." Under-constrained; constraint logic missing. +- "Users complain about price surprises at checkout." Pricing not real-time or hidden until end. +- "Sales says many users contact for help configuring." Configurator too complex for audience; defaults wrong. +- "Users save configurations but do not return." Save mechanism works but follow-up missing. +- "Configurator works on desktop, breaks on mobile." Mobile UX broken. +- "Audience completes but conversion to purchase is low." Configurator works; commitment friction at handoff. +- "We added more options; abandonment climbed." Crossed the cognitive-load threshold. +- "Constraint engaged but user did not understand why." Communication broken; users feel arbitrarily blocked. + +--- + +## The framework: 12 considerations for configurator design + +When designing or auditing a configurator, walk these 12 considerations. + +1. **The configurator decision.** Is configurator the right tool, or do bundles serve? +2. **Guided-configuration, not infinite-options or canned-bundles-only.** Smart defaults plus meaningful constraints plus escape hatches. +3. **Default configuration sensible.** User adjusts from default; does not build from zero. +4. **Constraint logic prevents invalid combinations.** Hard, soft, implication, capacity constraints. +5. **Constraint communication clear.** Why constraint engaged; what user can do. +6. **Real-time pricing visible.** Price updates with choices; breakdown available. +7. **Validation helpful.** Inline; specific; offers paths. +8. **Save-and-share works.** Multi-session; shareable; B2B-friendly. +9. **Configurator-to-cart handoff preserves state.** Cart shows configuration. +10. **Mobile parity.** Configurator works on the devices the audience uses. +11. **Conversion as success metric.** Not just completion rate; downstream purchase. +12. **Maintenance discipline.** Configurations updated as product changes; quarterly audit. + +The output of the framework is a configurator that earns the configuration that ships, with constraint logic, pricing, and handoff working together to produce commitments users keep. + +--- + +## Reference files + +- [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md) - When configurators earn the build vs when bundles serve. +- [`references/default-configuration-design.md`](references/default-configuration-design.md) - The starting point. Default selection and presentation. +- [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md) - Hard, soft, implication, capacity constraints. Communication patterns. +- [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md) - Price updates with choices. Breakdown and impact display. +- [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md) - Helpful validation. Inline, pre-emptive, final. +- [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md) - Email-link, account, anonymous, shareable URL, embed. +- [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md) - Handoff that preserves configuration; cart visibility; edit-from-cart. +- [`references/configurator-anti-patterns.md`](references/configurator-anti-patterns.md) - The patterns that look like configurators but degrade conversion. +- [`references/common-configurator-failures.md`](references/common-configurator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: configurators earn investment when they earn the configuration that ships + +The configurators that work as compounding assets are the ones that produce configurations users commit to. Not 50-cell decision matrices. Not bundles dressed as configurators. Configurations the user built, priced, validated, saved, and bought. + +That is the bar. Below the bar are infinite-options (decision paralysis; users abandon) and canned-bundles-only (configurator framing without real customization; users feel deceived). Above the bar are guided-configuration tools where smart defaults, meaningful constraints, real-time pricing, validation, and save-and-share work together to produce commitments. + +The discipline is in the design choices. The decision to build a configurator at all. The default configuration that opens the experience. The constraint logic that protects users from invalid combinations. The pricing that updates with choices. The validation that helps without punishing. The save-and-share that supports multi-decision purchases. The cart handoff that preserves the configuration. The maintenance that keeps the configurator in sync with the product it represents. diff --git a/skills/product-configurator-design/references/common-configurator-failures.md b/skills/product-configurator-design/references/common-configurator-failures.md new file mode 100644 index 0000000..2e5c19c --- /dev/null +++ b/skills/product-configurator-design/references/common-configurator-failures.md @@ -0,0 +1,179 @@ +# Common configurator failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Users abandon halfway through configuration." + +**The diagnosis.** Likely infinite-options pattern; too many decisions. + +**The cure.** Smart defaults; reduce option count; escape hatches into deeper customization. + +--- + +## "Configurator generates valid-looking configs that fail at fulfillment." + +**The diagnosis.** Under-constrained; constraint logic missing. + +**The cure.** Add constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## "Users complain about price surprises at checkout." + +**The diagnosis.** Pricing not real-time or hidden until end. + +**The cure.** Real-time pricing throughout. Detail in `references/real-time-pricing-patterns.md`. + +--- + +## "Sales says many users contact for help configuring." + +**The diagnosis.** Configurator too complex for audience; defaults wrong. + +**The cure.** Audit defaults; reduce option exposure; consider canned bundles for simple cases. + +--- + +## "Users save configurations but do not return." + +**The diagnosis.** Save mechanism works but follow-up missing. + +**The cure.** Reminder email after save; nudge before configuration expires. + +--- + +## "Configurator works on desktop, breaks on mobile." + +**The diagnosis.** Mobile UX broken. + +**The cure.** Mobile-first design and testing. + +--- + +## "Audience completes but conversion to purchase is low." + +**The diagnosis.** Configurator works; commitment friction at handoff. + +**The cure.** Audit cart handoff; ensure configuration preserved; reduce checkout friction. + +--- + +## "We added more options; abandonment climbed." + +**The diagnosis.** Crossed cognitive-load threshold. + +**The cure.** Cut options; surface fewer; defer complexity behind escape hatches. + +--- + +## "Constraint engaged but user did not understand why." + +**The diagnosis.** Communication broken. + +**The cure.** Constraint copy specific; explains why; offers paths. + +--- + +## "Configurations frequently differ from cart." + +**The diagnosis.** Handoff broken. + +**The cure.** Test cart handoff. Configuration ID system; single pricing source. + +--- + +## "Sales says enterprise customers want full configurations sales-led." + +**The diagnosis.** Enterprise audience wants white-glove; configurator self-serve does not match expectation. + +**The cure.** Enterprise path: configurator surfaces "Talk to sales for custom" for above-threshold configurations. + +--- + +## "We A/B tested adding more options; conversion went down." + +**The diagnosis.** Crossed the threshold. + +**The cure.** More is not always better. Maintain option discipline. + +--- + +## "Returning users see different prices than they saved." + +**The diagnosis.** Pricing shifted; configurator silently updated. + +**The cure.** Honest about price changes on resume. + +--- + +## "Mobile configuration completion is half of desktop." + +**The diagnosis.** Mobile UX significantly worse. + +**The cure.** Mobile-first redesign; reduce option exposure on mobile. + +--- + +## "Validation rejects valid international inputs." + +**The diagnosis.** Validation too strict. + +**The cure.** Audit validation rules; allow international formats. + +--- + +## "Some configurations work; others fail post-checkout." + +**The diagnosis.** Constraint logic incomplete; some invalid combinations slip through. + +**The cure.** Audit constraints. Add missing rules. + +--- + +## "Configurator's average configuration is more expensive than baseline." + +**The diagnosis.** May not be a problem (real customization adds cost) or may be (default biased toward expensive). + +**The cure.** Audit defaults. Defaults should reflect typical use, not flatter revenue. + +--- + +## "Sales pipeline shrunk after configurator launch; people self-serve." + +**The diagnosis.** Configurator absorbed the audience that would have called. + +**The cure.** This may be intentional (cost reduction) or unintentional (loss of complex deals). Decide if the shift is desired. + +--- + +## "Configurator launched; analytics broke." + +**The diagnosis.** Instrumentation missed. + +**The cure.** Verify analytics post-launch. Per-step instrumentation for diagnostic. + +--- + +## The pattern across failures + +Most configurator failures fall into one of three patterns. + +**Pattern 1: Cognitive overload.** Infinite-options, too many decisions, no defaults. The fix is guided-configuration. + +**Pattern 2: Trust damage.** Hidden pricing, price drift, unclear constraints, lost state. The fix is transparency. + +**Pattern 3: Handoff failures.** Cart loses configuration; checkout disappears it. The fix is loop closure. + +The metric pattern: configurator failures often look fine on engagement. Signal is in completion rate, conversion to purchase, downstream order accuracy. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (cognitive overload, trust damage, handoff). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-anti-patterns.md b/skills/product-configurator-design/references/configurator-anti-patterns.md new file mode 100644 index 0000000..d31b61b --- /dev/null +++ b/skills/product-configurator-design/references/configurator-anti-patterns.md @@ -0,0 +1,193 @@ +# Configurator anti-patterns + +The patterns that look like configurators but degrade conversion. Easy to ship; the cost shows up in completion rates, downstream conversion, and brand trust. + +--- + +## The infinite-options configurator + +The pattern. Every parameter exposed at full granularity. + +The signal. Decision paralysis; high abandonment. + +The cure. Smart defaults; meaningful constraints; escape hatches into deeper customization. + +--- + +## The canned-bundles-only configurator + +The pattern. Three pre-built bundles labeled "Custom." + +The signal. Audience expecting customization feels deceived. + +The cure. Real configuration logic; or honest bundle framing. + +--- + +## The blank-canvas configurator + +The pattern. Configurator opens empty; user must build from scratch. + +The signal. First-step abandonment. + +The cure. Default-heavy. Open with sensible default. + +--- + +## The hidden-pricing configurator + +The pattern. Price not visible until checkout. + +The signal. Users abandon at checkout when total surprises. + +The cure. Real-time pricing throughout. + +--- + +## The under-constrained configurator + +The pattern. User can build invalid configurations that fail downstream. + +The signal. Sales gets calls about failed orders. + +The cure. Constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## The over-constrained configurator + +The pattern. Too many constraints; user feels boxed in. + +The signal. User abandons; sales gets calls for "custom" configurations. + +The cure. Reduce constraints to genuine requirements; offer custom path for edge cases. + +--- + +## The unclear-constraint configurator + +The pattern. Constraint engages without explanation. + +The signal. Users confused; bounce rate climbs. + +The cure. Constraint communication. Why constraint engaged; what user can do. + +--- + +## The lose-state-on-error configurator + +The pattern. Validation engages; configuration resets. + +The signal. Users abandon at first error. + +The cure. Preserve state; errors local. + +--- + +## The mobile-broken configurator + +The pattern. Configurator works on desktop; breaks on mobile. + +The signal. Mobile completion much lower than desktop. + +The cure. Mobile-first design. + +--- + +## The lost-on-cart configurator + +The pattern. Cart shows generic SKU; configuration not visible. + +The signal. Users edit; configurator restarts; abandonment. + +The cure. Cart presentation preserves configuration. + +--- + +## The price-drift configurator + +The pattern. Configurator shows one price; cart shows another. + +The signal. Users feel deceived. + +The cure. Single source of truth for pricing. + +--- + +## The save-mechanism-broken configurator + +The pattern. User saves; recovery link broken; configuration lost. + +The signal. Users complain; abandonment increases on long configurations. + +The cure. Test save mechanism end-to-end. + +--- + +## The validation-strict configurator + +The pattern. Validation rejects valid edge-case inputs. + +The signal. Users with valid inputs cannot proceed. + +The cure. Audit validation; allow international, plus-aliased, non-Latin inputs. + +--- + +## The unmaintained configurator + +The pattern. Product changed; configurator did not. + +The signal. Configurator references deprecated options; pricing wrong. + +The cure. Quarterly maintenance; product changes trigger configurator updates. + +--- + +## The aggressive-pricing-anchoring configurator + +The pattern. Strikethrough prices that were never charged; "$X for a limited time" perpetually. + +The signal. Sophisticated audiences notice; trust collapses. + +The cure. Honest anchoring; real discounts only. + +--- + +## The orphan-configuration configurator + +The pattern. Configurations save; user returns; configuration valid but pricing changed silently. + +The signal. Users surprised at price difference. + +The cure. Honest about price changes on resume. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +**Audit questions per configurator.** + +- Is default sensible (anti-pattern check: blank-canvas)? +- Are constraints calibrated (anti-pattern check: over-constrained, under-constrained, unclear)? +- Is pricing visible and consistent (anti-pattern check: hidden-pricing, price-drift)? +- Does state preserve on error (anti-pattern check: lose-state-on-error)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Does cart preserve configuration (anti-pattern check: lost-on-cart)? +- Is validation calibrated (anti-pattern check: validation-strict)? +- Is configurator current (anti-pattern check: unmaintained)? +- Are saved configurations honest about price changes (anti-pattern check: orphan-configuration)? + +**The retire decision.** Configurators failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-decision-criteria.md b/skills/product-configurator-design/references/configurator-decision-criteria.md new file mode 100644 index 0000000..60185a6 --- /dev/null +++ b/skills/product-configurator-design/references/configurator-decision-criteria.md @@ -0,0 +1,129 @@ +# Configurator decision criteria + +When configurators earn the build vs when bundles serve. + +A configurator is meaningful work. Constraint logic, real-time pricing, validation, save-and-share, cart handoff, ongoing maintenance. The configurator earns this investment only when specific conditions are present. + +--- + +## When configurators earn the build + +Five conditions that, when present, make a configurator a strong investment. + +**The product has genuinely customizable parameters that affect outcome and cost.** Not just cosmetic options; real parameters that change what the user gets. + +**The audience values customization beyond what bundles offer.** Some audiences want choice; others prefer curated bundles. + +**The team can support the configuration logic.** Validation, pricing, fulfillment for variable configurations. + +**The combinatorial space is meaningful but constrained.** Not literally infinite; not so small that bundles would suffice. + +**The success metric is defined.** Configuration completion rate, configuration-to-purchase rate, average configuration price. + +When all five are present, a configurator is strong investment. When two or fewer are present, bundles often serve better. + +--- + +## When configurators do NOT earn the build + +Funnels where configurators add complexity without lift. + +**The product is essentially bundles.** Calling them configurations is marketing. + +**The audience prefers curated options.** Some audiences resent customization friction. + +**The combinatorial space is too large.** No audience can navigate. + +**Customization produces invalid combinations.** Team cannot prevent; users hit failures. + +**A simpler tool would serve.** Comparison, calculator, or selection tool. + +The honest assessment matters. Configurators are sometimes the wrong tool. + +--- + +## Configurators vs bundles + +When each fits. + +**Bundles strengths.** Simple; clear; no decision paralysis. Easy to maintain. + +**Bundles weaknesses.** Audiences that need customization underserved. + +**Configurators strengths.** Match real customer needs; capture revenue from edge cases. + +**Configurators weaknesses.** Build cost; complexity. + +**The combined approach.** Some products offer bundles AND a configurator for users who want custom. + +--- + +## The opportunity-cost frame + +Configurators are significant work. + +**Build cost.** Constraint logic, pricing engine, save-and-share, validation, cart integration. 60-200 engineering hours typical. + +**Maintenance cost.** Product changes trigger configurator updates. 4-12 hours per quarter. + +**Opportunity cost.** Better bundles, comparison tool, calculator. The configurator has to clear those alternatives. + +The decision frame. Configurators earn investment when they produce more revenue than bundle-only or alternative formats. + +--- + +## Decision worked example + +A B2B SaaS with seat-based + add-on pricing. + +**Conditions check.** + +- Genuinely customizable: yes (seats, add-ons, integrations). +- Audience values customization: yes; team size and add-ons vary. +- Team can support: yes. +- Combinatorial space: meaningful but constrained. +- Success metric: defined. + +**Decision.** Build the configurator. + +The decision was deliberate. + +--- + +## Decision worked example: when bundles serve + +A consumer SaaS with three plans. + +**Conditions check.** + +- Genuinely customizable: no; plans are bundles. +- Audience values customization: no; users pick plans. +- Combinatorial space: trivial. + +**Decision.** Bundles. No configurator needed. + +The decision was right-sized. + +--- + +## When to retire a configurator + +Configurators can become wrong over time. + +**Retire when:** + +- Conversion declined and refinements have not moved it. +- Most users default-and-purchase; customization unused. +- Product changed; configurator no longer matches. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions for configurators. The five against. Configurators vs bundles. Opportunity-cost frame. Decision worked examples. The retire decision. + +## Implementation choices that stay internal + +Specific configurator decisions for specific products. Capacity benchmarks. Tooling. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-to-cart-handoff.md b/skills/product-configurator-design/references/configurator-to-cart-handoff.md new file mode 100644 index 0000000..36bbf43 --- /dev/null +++ b/skills/product-configurator-design/references/configurator-to-cart-handoff.md @@ -0,0 +1,159 @@ +# Configurator-to-cart handoff + +Handoff that preserves configuration; cart visibility; edit-from-cart. + +When the user commits, the handoff to cart determines whether the commitment sticks. Done well, handoff preserves the configuration; done poorly, the cart shows generic SKUs and the user feels their custom build was lost. + +--- + +## The preserve-the-build principle + +The configuration becomes the cart item. The cart shows the configuration. Editing returns to the configurator with state preserved. + +**The win.** User finishes configuration; clicks add to cart; cart shows the custom configuration with breakdown and price; user can edit, returning to configurator with all choices preserved. + +**The fail.** User finishes; clicks add to cart; cart shows "Custom Product - $X" with no detail. User cannot tell if their build is reflected. + +The discipline. Handoff loop closed. + +--- + +## Cart presentation + +How the configuration appears in cart. + +**Configuration summary.** Key choices listed (not all; not none). + +**Price breakdown.** Subtotal matches configurator's price. + +**Edit link.** Clear path back to configurator with state preserved. + +**Visual.** If configurator shows visual configuration, cart shows it too (or summary image). + +--- + +## Edit-from-cart + +When user wants to change. + +**Pattern.** Cart includes "Edit configuration" link. + +**Behavior.** + +- Click; return to configurator. +- All choices loaded. +- Adjust; commit; cart updates. + +**The lose-state-on-edit failure.** User clicks edit; configurator restarts; previous choices lost. + +The cure. State preserved through the handoff loop. + +--- + +## Multi-item handoff + +When the user configures multiple items. + +**Pattern.** Each configuration becomes a separate cart item with its own summary. + +**Edit each independently.** User can edit one without affecting others. + +--- + +## B2B configurator-to-quote + +When the configurator generates a quote rather than direct cart. + +**Pattern.** Configuration generates a quote; quote can be shared, approved, then converted to order. + +**Strengths.** B2B workflows often require approval. + +**The discipline.** Quote includes everything the configuration includes; conversion to order preserves. + +--- + +## Handoff to checkout + +After cart, checkout. + +**The principle.** Configuration details flow through checkout. Confirmation email reflects the configuration. + +**The drop-config-at-checkout failure.** Configuration disappears at checkout; user cannot verify. + +The cure. Configuration visible throughout the funnel. + +--- + +## Configuration ID + +The technical bridge. + +**Pattern.** Each configuration gets an ID. Cart, checkout, fulfillment all reference the ID. + +**Strengths.** Stable reference. + +**Weaknesses.** Requires backend infrastructure. + +--- + +## Pricing consistency + +Prices match across configurator, cart, checkout. + +**The principle.** No price drift between stages. + +**The drift failure.** Configurator shows $X; cart shows $Y; user feels deceived. + +**Causes.** Caching, currency conversion, tax estimation, discount expiration. + +**The cure.** Single source of truth for pricing; all stages query. + +--- + +## Save-and-share-to-cart + +When users return from saved configurations. + +**Pattern.** Saved configuration link opens configurator with state; user can add to cart from there. + +**The discipline.** Save mechanism integrates with cart workflow. + +--- + +## Mobile cart handoff + +On mobile, the handoff transition matters. + +**Considerations.** + +- Cart visible without horizontal scroll. +- Edit returns work on mobile. +- Configuration summary readable. + +--- + +## Common handoff failures + +**Cart shows generic SKU.** User cannot verify configuration. + +**Edit restarts configurator.** Previous choices lost. + +**Pricing drifts between stages.** User confused. + +**Configuration disappears at checkout.** Cannot verify. + +**Multi-item handoff broken.** Configurations conflict in cart. + +**B2B quote misses details.** Quote does not match configuration. + +**Confirmation email lacks configuration.** User cannot verify post-purchase. + +--- + +## Methodology-level choices that stay in the public skill + +The preserve-the-build principle. Cart presentation. Edit-from-cart. Multi-item handoff. B2B configurator-to-quote. Handoff to checkout. Configuration ID. Pricing consistency. Save-and-share-to-cart. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific cart implementations for specific configurators. Specific configuration-ID systems. Specific backend integrations. These vary by team. diff --git a/skills/product-configurator-design/references/constraint-logic-patterns.md b/skills/product-configurator-design/references/constraint-logic-patterns.md new file mode 100644 index 0000000..809e52b --- /dev/null +++ b/skills/product-configurator-design/references/constraint-logic-patterns.md @@ -0,0 +1,173 @@ +# Constraint logic patterns + +Hard, soft, implication, capacity constraints. Communication patterns. + +Constraints prevent invalid configurations. Done well, they protect users from errors and surface why; done poorly, they feel arbitrary or fail to prevent invalid configurations. + +--- + +## The protect-and-explain principle + +Constraints should prevent invalid configurations and explain why when they engage. + +**The win.** User selects Option A. System recognizes A is incompatible with currently-selected Option B. Inline message: "Option A and Option B are incompatible. Choose A or B." User adjusts; understands. + +**The fail.** User builds configuration. Submits. Backend rejects. User confused; no path forward. + +The discipline. Constraints engage at choice-time; explain why; offer paths. + +--- + +## Pattern A: Hard constraints + +Combinations that cannot exist. + +**How it works.** + +- Two options incompatible; configurator prevents both selected. +- User selects A; B becomes unavailable (greyed; with explanation). +- Or vice versa. + +**Strengths.** Prevents invalid configurations. + +**Weaknesses.** Can frustrate users who do not understand the constraint. + +**When to use.** Genuinely incompatible options. + +--- + +## Pattern B: Soft constraints + +Combinations that are unusual but possible. + +**How it works.** + +- User selects unusual combination. +- System warns: "This combination is unusual. Most teams choose [alternative]." +- User can proceed. + +**Strengths.** Respects user agency; provides guidance. + +**Weaknesses.** Some users will ignore warning; downstream issues. + +**When to use.** Combinations that work but are uncommon. + +--- + +## Pattern C: Implication constraints + +When choosing one option requires another. + +**How it works.** + +- User selects A. +- System auto-selects required B (or surfaces it for selection). +- Explains: "Selecting A requires B because [reason]." + +**Strengths.** Prevents missing-dependency errors. + +**Weaknesses.** Implication chains can grow complex. + +**When to use.** When dependencies are clear and predictable. + +--- + +## Pattern D: Capacity constraints + +Configuration exceeds product or fulfillment capacity. + +**How it works.** + +- User configures heavily; reaches capacity ceiling. +- System caps; explains: "Max [X] supported per configuration." +- Offers contact for custom. + +**Strengths.** Prevents impossible configurations. + +**Weaknesses.** Can frustrate enterprise audiences; offer contact for custom. + +**When to use.** Hard product limits. + +--- + +## Pattern E: Combinatorial constraints + +When multiple choices interact in complex ways. + +**How it works.** + +- Configurator evaluates the full configuration after each change. +- Constraints engage based on combinations, not individual options. +- Surface conflicts as they emerge. + +**Strengths.** Handles complex products. + +**Weaknesses.** Maintenance complexity. + +**When to use.** Products with genuine combinatorial constraints. + +--- + +## Constraint communication + +How constraints surface. + +**Inline.** Message next to the constrained choice. + +**Modal.** Full-screen explanation for major constraints. + +**Toast.** Brief notification for minor. + +**The discipline.** Match intensity to constraint importance. + +--- + +## Constraint copy + +What the message says. + +**Strong copy.** "Option A and Option B are incompatible because [specific reason]. Choose A or B." + +**Weak copy.** "Invalid configuration." + +The discipline. Specific; explanatory; offers paths. + +--- + +## Constraint maintenance + +Constraints decay. + +**What decays.** + +- Constraints from old product variants. +- Constraints inherited from deprecated options. +- New options not yet constrained. + +**Maintenance cadence.** Quarterly review with product changes. + +--- + +## Common constraint failures + +**Over-constrained.** Too many constraints; user feels boxed in. + +**Under-constrained.** User builds invalid configuration; fails downstream. + +**Constraint without explanation.** User confused by arbitrary blocking. + +**Stale constraints.** Inherited from old product. + +**Constraint surface inappropriate.** Modal for minor; toast for major. + +**No path offered.** Constraint blocks; user has no alternative. + +--- + +## Methodology-level choices that stay in the public skill + +The protect-and-explain principle. Patterns A through E. Constraint communication. Constraint copy. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific constraints for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/default-configuration-design.md b/skills/product-configurator-design/references/default-configuration-design.md new file mode 100644 index 0000000..aee99bf --- /dev/null +++ b/skills/product-configurator-design/references/default-configuration-design.md @@ -0,0 +1,109 @@ +# Default-configuration design + +The starting point. Default selection and presentation. + +The configurator opens with a default configuration. Done well, the default makes the user feel guided rather than overwhelmed; done poorly, the user faces a blank canvas and abandons. + +--- + +## The default-heavy principle + +Configurators should open with a sensible default, not a blank canvas. + +**The win.** User opens the configurator; sees a complete configuration with price; can adjust from there. + +**The fail.** User opens the configurator; sees empty fields and 0 fields completed. Decision paralysis. + +The discipline. Default-heavy; user adjusts from default; never builds from zero. + +--- + +## Default selection + +Which configuration is the default. + +**Common-case default.** The configuration most audiences would choose. Reflects audience research. + +**Inferred default.** Based on referrer, query, or stated preference. + +**Audience-segment default.** Different defaults for different segments (small vs enterprise). + +**The most-popular default.** Use what most users actually pick. + +--- + +## Default presentation + +How the default appears. + +**Visible immediately.** User sees a complete configuration with price. + +**Adjust controls obvious.** User knows what is changeable. + +**Reset-to-default available.** Users who experiment can return to default. + +**Summary-and-detail.** Default shown as summary with expandable detail. + +--- + +## The blank-canvas trap + +When configurators open empty. + +**The pattern.** Empty fields; user must build from scratch. + +**The signal.** High first-step abandonment. + +**The cost.** Users abandon before reaching ah-ha moment of seeing a configuration. + +**The cure.** Default-heavy. Open with a complete configuration. + +--- + +## Default updating + +Defaults decay. + +**What decays.** + +- Most-popular configuration shifts. +- Audience composition changes. +- Product changes invalidate defaults. + +**Maintenance cadence.** Quarterly review. + +--- + +## Default-by-segment + +Different audiences may warrant different defaults. + +**Pattern.** Detect or ask about audience; default adapts. + +**Detection.** Referrer, query, stated input, or inferred from context. + +The discipline. Audience-fit defaults serve better than one-size-fits-all. + +--- + +## Common default failures + +**Blank canvas.** No default; user paralyzes. + +**Wrong default.** Most users adjust away; default does not match audience. + +**Stale default.** Reflects old product or pricing. + +**Default obscures customization.** User does not realize options exist. + +**Default biased toward expensive.** Default flatters revenue, not user fit. + +--- + +## Methodology-level choices that stay in the public skill + +The default-heavy principle. Default selection. Default presentation. The blank-canvas trap. Default updating. Default-by-segment. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific configurators. Specific detection logic. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/real-time-pricing-patterns.md b/skills/product-configurator-design/references/real-time-pricing-patterns.md new file mode 100644 index 0000000..b562309 --- /dev/null +++ b/skills/product-configurator-design/references/real-time-pricing-patterns.md @@ -0,0 +1,157 @@ +# Real-time pricing patterns + +Price updates with choices. Breakdown and impact display. + +Pricing that responds to choices. Done well, users see cost impact immediately; done poorly, price-shock at checkout drives abandonment. + +--- + +## The no-surprises principle + +Price visible throughout the configuration. No surprises at checkout. + +**The win.** Total price visible at top of configurator. Updates as user adjusts. Per-choice impact visible ("Adds $X"). Breakdown available. + +**The fail.** Price hidden until checkout. User configures heavily. Sees price; abandons. + +The discipline. Price visible; breakdown available; surprises eliminated. + +--- + +## Total price display + +How the total appears. + +**Prominent placement.** Top or top-right of configurator. + +**Real-time updates.** Updates immediately as user changes choices. + +**Currency and locale.** Match the user's locale. + +**Period.** Per-month, per-year, one-time. Match the product's pricing model. + +--- + +## Per-choice impact + +Showing what each option costs. + +**Inline impact.** "+$X/month" next to the option. + +**Strikethrough for upgrades.** Old price strikethrough; new price highlighted. + +**Free options labeled.** "Free" or "Included" explicit. + +The discipline. User can see the cost of each choice without computing. + +--- + +## Pricing breakdown + +How the total breaks down. + +**Expandable breakdown.** "How is this priced" toggle reveals detail. + +**Categorized breakdown.** Base + add-ons + fees. + +**Subscription vs one-time.** Recurring vs one-time costs distinguished. + +The discipline. Breakdown available on demand; not forced. + +--- + +## Annual vs monthly + +Subscription periods. + +**Toggle visible.** User can switch between annual and monthly. + +**Discount disclosed.** "Save X% with annual billing." + +**Both totals shown.** Annual total and monthly equivalent. + +--- + +## Hidden cost surfacing + +Costs that often hide. + +**Setup fees.** Disclosed at configuration; not at checkout. + +**Implementation costs.** If applicable, visible. + +**Per-user vs flat.** Mode disclosed. + +**Overage pricing.** What happens beyond capacity, disclosed. + +The hidden-cost trap. Costs surfaced only at checkout; user feels deceived. + +--- + +## Tax and shipping + +Where applicable. + +**Tax estimate.** Approximate tax visible if jurisdiction can be inferred. + +**Shipping estimate.** Approximate shipping visible if applicable. + +**Final calculation at checkout.** Estimate at configurator; final at checkout. + +The discipline. Estimates clearly labeled; final disclosed. + +--- + +## Price comparison anchoring + +Showing alternative configurations. + +**Comparison anchoring.** "If you upgrade to X, the price increases to Y." + +**Bundle anchoring.** "Equivalent bundle is Z." + +**Use carefully.** Anchoring can manipulate; honesty matters. + +--- + +## Pricing maintenance + +Pricing decays. + +**What decays.** + +- Pricing levels from old pricing models. +- Currency conversions stale. +- Discount terms expired. + +**Maintenance cadence.** When pricing changes, configurator pricing updates as part of the change. + +--- + +## Common pricing failures + +**Hidden pricing.** Total not visible until checkout. + +**Per-choice impact hidden.** User does not know what each choice costs. + +**Surprise fees.** Setup, implementation costs hidden until checkout. + +**Stale pricing.** Reflects old prices. + +**Tax surprise.** Tax not estimated; user surprised at checkout. + +**Currency wrong.** Local user sees wrong currency. + +**No annual-vs-monthly toggle.** User locked into one period. + +**False discount anchoring.** Strikethrough prices that were never charged. + +--- + +## Methodology-level choices that stay in the public skill + +The no-surprises principle. Total price display. Per-choice impact. Pricing breakdown. Annual vs monthly. Hidden cost surfacing. Tax and shipping. Price comparison anchoring. Pricing maintenance. Common failures. + +## Implementation choices that stay internal + +Specific pricing displays for specific configurators. Specific currency and tax logic. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/save-and-share-mechanics.md b/skills/product-configurator-design/references/save-and-share-mechanics.md new file mode 100644 index 0000000..5ca6010 --- /dev/null +++ b/skills/product-configurator-design/references/save-and-share-mechanics.md @@ -0,0 +1,218 @@ +# Save-and-share mechanics + +Email-link, account, anonymous, shareable URL, embed. + +Configurations users return to or send to others. Multi-decision purchases require deliberation; B2B configurations often need stakeholder review. Save-and-share supports these workflows. + +--- + +## The deliberation-friendly principle + +Configurators that serve real decision-making produce configurations users want to save and share. + +**The win.** User configures complex purchase. Saves via email-link. Shares with stakeholders. Returns days later. Configuration intact; price unchanged; ready to buy. + +**The fail.** User configures; cannot save; loses work between sessions; abandons. + +The discipline. Save mechanisms support multi-session and multi-stakeholder workflows. + +--- + +## Pattern A: Email-link save + +User enters email; link emailed. + +**How it works.** + +- "Save and resume later" CTA. +- User enters email. +- Link emailed; user clicks to return. + +**Strengths.** No account required; cross-device. + +**Weaknesses.** Email deliverability; link expiration. + +**When to use.** Default for non-authenticated configurators. + +--- + +## Pattern B: Account-based save + +Logged-in users save automatically. + +**How it works.** + +- User logs in. +- Configurations save to account. +- User returns; finds saved configurations. + +**Strengths.** Multi-configuration management. + +**Weaknesses.** Account creation friction. + +**When to use.** When configurator is part of a logged-in product. + +--- + +## Pattern C: Anonymous-session save + +Browser-based persistence. + +**How it works.** + +- Configuration saved to browser local storage. +- User returns same browser; configuration restored. + +**Strengths.** Lowest friction. + +**Weaknesses.** Lost on browser change; limited persistence. + +**When to use.** As supplement to other patterns. + +--- + +## Pattern D: Shareable URL + +Configuration encoded in URL. + +**How it works.** + +- Configurator encodes the configuration in URL parameters. +- User shares URL; recipient opens; sees same configuration. + +**Strengths.** Easy sharing across channels. + +**Weaknesses.** URL length; pricing may shift over time. + +**When to use.** Shareable configurations; B2B stakeholder review. + +--- + +## Pattern E: Embed code + +Configuration embeddable on other sites. + +**How it works.** + +- Configurator generates embed code. +- User pastes into other sites or proposals. + +**Strengths.** Used in B2B proposals. + +**Weaknesses.** Cross-site complexity. + +**When to use.** B2B sales contexts. + +--- + +## Pattern F: Hybrid + +Combining patterns. Common for production configurators. + +**Common combination.** Email-link save + shareable URL + anonymous-session backup. + +**Strengths.** Multiple paths. + +**Weaknesses.** Complexity. + +--- + +## Save trust communication + +Users hesitate to save partial sensitive configurations. + +**What to communicate.** + +- What is saved. +- How long it persists. +- Who can access it. +- How to delete. + +The discipline. Trust communication explicit; not buried in privacy policy. + +--- + +## Resume experience + +When user returns. + +**The principle.** Resume should be uninterrupted. + +**The pattern.** + +- User clicks recovery link or logs in. +- Lands at the configuration; rest preserved. +- Continues without re-doing. + +**Resume failures.** + +- Configuration partially preserved; values lost. +- Pricing changed; user surprised. +- Constraint logic shifted; configuration now invalid. + +The discipline. Resume preserves; communicate any changes (e.g., "Pricing has updated since you last visited"). + +--- + +## Pricing on resume + +When prices change between save and resume. + +**Honest pattern.** Show the saved configuration with original price; surface "Pricing has changed; updated price is X" with explanation. + +**Dishonest pattern.** Silently update price; user does not notice. + +The discipline. Honesty about price changes. + +--- + +## Sharing privacy + +Shared configurations may include sensitive info. + +**Considerations.** + +- What is in the URL/embed. +- Who can see it. +- How long links are valid. + +The discipline. Sharing respects user privacy; sensitive details may need account-based sharing rather than URL. + +--- + +## Save-and-share analytics + +Track usage. + +**Metrics.** + +- Save rate. +- Resume rate per saved configuration. +- Share rate. +- Configurations completed via save-and-share path. + +--- + +## Common save-and-share failures + +**No save mechanism.** Users lose work; abandon. + +**Save mechanism brittle.** Links expire; account access broken. + +**Resume loses state.** User lands at start; loses work. + +**Pricing surprise on resume.** Silent price update. + +**Sharing exposes sensitive info.** Embedded URLs share more than intended. + +**Save trust missing.** Users do not save because they distrust persistence. + +--- + +## Methodology-level choices that stay in the public skill + +The deliberation-friendly principle. Patterns A through F. Save trust communication. Resume experience. Pricing on resume. Sharing privacy. Analytics. Common failures. + +## Implementation choices that stay internal + +Specific save mechanisms for specific configurators. Specific tooling for URL encoding and embed generation. Privacy review processes. These vary by team. diff --git a/skills/product-configurator-design/references/validation-and-error-patterns.md b/skills/product-configurator-design/references/validation-and-error-patterns.md new file mode 100644 index 0000000..7375621 --- /dev/null +++ b/skills/product-configurator-design/references/validation-and-error-patterns.md @@ -0,0 +1,191 @@ +# Validation and error patterns + +Helpful validation. Inline, pre-emptive, final. + +Validation catches invalid input. Done well, validation is helpful and inline; done poorly, validation is punitive or arrives only at submission. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. + +**The win.** User selects an option that requires another. Inline validation surfaces immediately; explains; auto-corrects or guides. + +**The fail.** User configures complete configuration. Submits. Validation runs at backend. User sees error; loses momentum. + +The discipline. Validation timing matters; specific, helpful messages matter; preserve user inputs on error. + +--- + +## Pattern A: Inline validation + +Validation runs as the user makes choices. + +**How it works.** + +- User selects an option. +- System validates against the rest of the configuration. +- If invalid, message appears next to the choice. + +**Strengths.** Errors caught at point of input. + +**Weaknesses.** Real-time validation can lag; intrusive if too aggressive. + +**When to use.** Default for most configurators. + +--- + +## Pattern B: Pre-emptive validation + +Constraints prevent invalid choices from being selectable. + +**How it works.** + +- Options that would create conflicts are disabled with explanation. +- User cannot select the invalid option. + +**Strengths.** Errors prevented; user does not encounter them. + +**Weaknesses.** Some users want to see the option even if disabled. + +**When to use.** When the constraint is hard and explanation is clear. + +--- + +## Pattern C: Final validation + +Validation runs at submission. + +**How it works.** + +- User completes configuration. +- Submit; system runs full validation. +- Errors surfaced at this stage. + +**Strengths.** Catches errors that span multiple fields. + +**Weaknesses.** Late; user invested in completing. + +**When to use.** As supplement to inline validation; not primary. + +--- + +## Pattern D: Hybrid + +Combining patterns. + +**Common combination.** Pre-emptive for hard constraints; inline for soft validation; final as backup. + +**Strengths.** Multiple safety nets. + +**Weaknesses.** Complexity. + +**When to use.** Production configurators with multiple constraint types. + +--- + +## Validation message discipline + +What the message says. + +**Strong messages.** + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +**Examples.** + +- "Option A requires Option B; we have selected B for you." +- "Option C is incompatible with Option D. Choose one or contact us for custom." +- "Quantity exceeds 1000; for larger quantities contact our team." + +**Weak messages.** + +- "Invalid configuration." +- "Error." +- "Please correct the issues." + +The discipline. Specific, helpful, offers paths. + +--- + +## Validation strictness + +How aggressively to validate. + +**Too strict.** Rejects valid inputs at edge cases. Frustrates users. + +**Too loose.** Accepts invalid inputs that fail downstream. + +**The right strictness.** Validation matches actual product constraints. + +--- + +## Preserve inputs on error + +What happens when validation engages. + +**The principle.** Errors should not lose user inputs. + +**The pattern.** Error appears; rest of configuration preserved; user adjusts the specific issue. + +**The reset-on-error failure.** Form resets entirely on error. User loses all work; abandons. + +The cure. Errors are local; configuration state preserved. + +--- + +## Mobile validation + +Validation on mobile. + +**Mobile considerations.** + +- Inline messages must fit mobile screens. +- Auto-correct should work with touch. +- Error states must be visible without zoom. + +The mobile discipline. Test validation on actual devices. + +--- + +## Validation testing + +Test validation across cases. + +**Test cases.** + +- Valid configurations: pass through. +- Invalid configurations (each constraint type): caught with helpful message. +- Edge cases (boundary values, unusual combinations): handled. +- Mobile: works on touch. + +--- + +## Common validation failures + +**Late validation.** Errors caught only at submission. + +**Generic error messages.** No guidance. + +**Strict validation rejects valid inputs.** Edge cases lost. + +**Loose validation accepts invalid.** Fails downstream. + +**Reset-on-error.** User loses work. + +**Validation interrupts typing.** Real-time validation too eager. + +**Mobile-broken validation.** Errors invisible or off-screen. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D. Validation message discipline. Validation strictness. Preserve inputs on error. Mobile validation. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md new file mode 100644 index 0000000..124d85f --- /dev/null +++ b/skills/programmatic-seo/SKILL.md @@ -0,0 +1,279 @@ +--- +name: programmatic-seo +description: "How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. Data source identification, template design, schema patterns, quality control at scale, internal linking architecture, crawl budget management, AEO/GEO for programmatic pages, refresh discipline, and the make-or-break question of whether pSEO is the right answer for your program at all. Triggers on programmatic SEO, pSEO, scaled content, page generation, template SEO, location pages, comparison pages, directory site, listing site, scaled landing pages, programmatic content. Also triggers when a content set is not ranking, has been hit by an algorithm update, or when a team is considering pSEO as a growth lever." +category: content +catalog_summary: "Designing pSEO programs that work: data sources, template design, quality control at scale, internal linking, crawl budget, AEO/GEO patterns, refresh discipline, and when pSEO is and is not the right answer" +display_order: 6 +--- + +# Programmatic SEO + +A senior SEO strategist's playbook for designing and running programmatic SEO programs that produce durable traffic instead of penalty-bait. + +Programmatic SEO has a complicated reputation. Sites like Zillow, Airbnb, TripAdvisor, Indeed, and Yelp have built billion-dollar traffic engines on pSEO. Other sites have built pSEO programs that got hit by Google's helpful-content updates and lost 80% of their traffic in a week. The difference is rarely the technique; it is the underlying data quality and the quality control discipline at scale. + +This skill is the playbook for getting that distinction right. It assumes you have decided what keyword space to target (see `seo-keyword`) and how the broader content program is shaped (see `content-strategy`). It does not write individual editorial pieces (see `content-and-copy` for that) and does not architect editorial topic hubs (see `pillar-content-architecture` for that). What it does is teach the discipline of generating high-volume pages programmatically from structured data sources without producing thin content, duplicate content, or scale-without-substance pages that get penalized. + +When to use this skill: deciding whether pSEO is a fit for the program at all (the most important question), designing a new pSEO system, auditing an existing pSEO set that is not ranking or has been hit by an algorithm update, or building quality-control discipline for a pSEO program that grew faster than its quality processes. + +--- + +## What this skill is for + +This skill spans scaled-content programs from data source through quality control. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: editorial pillars, calendar, governance. Decides whether pSEO fits the program at all. +- `pillar-content-architecture` is hub-scope: one topic with 10 to 15 intentional editorial pieces. Editorial in nature. +- `content-brief-authoring` is per-piece scope: brief for one editorial artifact. +- `content-and-copy` is execution scope: writing individual editorial pieces. +- This skill is scaled scope: 100s to 100,000s of pages generated programmatically from structured data sources, each targeting a long-tail query. + +The clean reading order: `content-strategy` decides whether pSEO is a fit, `seo-keyword` surfaces the long-tail keyword space, this skill designs the pSEO system, `editorial-qa` (forthcoming) provides the QA discipline for sampled quality control across the set. `content-and-copy` and `content-brief-authoring` are not in the loop for pSEO at scale; those skills are for editorial pieces, not data-driven generated pages. + +The audience: SEO content strategists, content engineers, agencies running pSEO programs, in-house teams considering pSEO as a growth lever. The voice is senior SEO strategist to junior PM or marketer. Specific, opinionated, honest. The reputation problem is not pSEO; it is pSEO without underlying value. + +--- + +## When pSEO is the right answer + +The keystone question. pSEO works when all of the following are true. + +**1. Real underlying data.** A genuine structured data source with depth: 10+ fields per record, ideally 20+, with first-party data, expert-curated data, or licensed datasets. Not just scraped data or AI-generated facts dressed as structured records. + +**2. Long-tail query volume justifies the effort.** The queries the program would target have meaningful aggregate volume even if individual queries are small. Real estate "homes for sale in {neighborhood}" works at scale. "Blue widget reviews 2026" generated for every adjective times widget combination does not, because the queries are not actually searched. + +**3. User intent is queryable.** The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +**4. Update cadence aligns with query volatility.** Real estate listings update daily and the data refresh aligns. "Best [thing] for [year]" pages get stale annually and need a refresh discipline budgeted in. + +**5. Quality control is operationally feasible.** The team has the capacity to sample-audit the set, fix failures, and maintain quality as the set grows. Not aspirationally; budgeted in headcount. + +pSEO does NOT work when: + +- The underlying data is shallow (3 to 5 fields, mostly AI-generated, no first-party signal) +- The query volume is illusory (long-tail keywords nobody actually searches) +- User intent requires narrative or judgment that data cannot supply +- Quality control is not budgeted (write a bunch of pages, ignore them) +- The program is scaling AI-generated thin pages without unique data + +The honest framing. Most teams that ask "should we do pSEO?" should hear "probably not, unless the underlying data is unique or first-party expertise makes the pages actually useful." The reputation problem is not the technique; it is the technique applied without underlying value. + +Detail in [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md). + +--- + +## Data source identification + +The data source is the pSEO program. Common sources with different defensibility profiles. + +**First-party data.** Customer transactions, content database, user-generated content. Defensible because nobody else has it. Examples: Glassdoor's employee reviews, Yelp's user ratings, TripAdvisor's traveler reviews. + +**Licensed datasets.** Industry databases, regulatory data, government datasets, licensed third-party feeds. Defensible by license terms and integration depth. Examples: Zillow's MLS partnerships, real estate brokerage feeds, sports statistics licenses. + +**Aggregated public data.** Scraped, cleaned, enriched. Judgment call on legality (often gray area depending on robots.txt, terms of service, jurisdictional rules). Defensibility depends on the cleaning and enrichment work. Easy to copy if the cleaning is shallow. + +**Expert-curated content.** The dataset is built by hiring experts to populate it. Slow, high-quality, defensible. Examples: Wirecutter's product testing, expert-reviewed medical content, curated editorial databases. + +**Synthesized data.** Combining multiple sources into a unique view. "Neighborhoods times schools times prices" combining three datasets into a comparison view. Defensibility comes from the synthesis logic and the ongoing maintenance of multi-source pipelines. + +The "moat" question. Would a competitor be able to replicate the data source? If yes, the pSEO program has no defensibility; anyone can copy. If no, the data source becomes a moat that compounds. Zillow's MLS partnerships, Glassdoor's employee reviews, Crunchbase's funding data, are moats. "Scraped Wikipedia plus AI rewrite" is not. + +Detail in [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md). + +--- + +## Template design + +The template is the structure that data fills. Design principles. + +**Above-the-fold answer.** The user's specific question answered in the first 200 words of the rendered page, structured for both human reading and AI extraction. The answer is what gets cited; the rest is supporting depth. + +**Variable density.** The template accommodates records with sparse fields (some have 5 data points, others have 50) without looking broken. Sparse pages need fallback patterns; dense pages need progressive disclosure to avoid overwhelming. + +**Heading hierarchy that reflects data.** H2s and H3s map to data sections (overview, details, comparisons, related). The heading structure is not decorative; it tells crawlers and AI engines what the page covers. + +**Schema markup as part of template.** Structured data (JSON-LD, microdata, or RDFa depending on the stack) embedded in the template renders machine-readable signals at scale across the entire set. Without schema, the set is invisible to the structured-data extraction layer search and answer engines run. + +**Internal linking placeholders.** The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. 5 to 15 internal links per page is typical for a well-linked set. + +**Distinctive value per page.** Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. If the page is just a re-pivot of the parent's data, the page is filler. + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. If a randomly sampled page is thin, the entire set is thin. + +Detail in [`references/template-design-patterns.md`](references/template-design-patterns.md). + +--- + +## Schema design + +The data shape that drives the template. Design principles. + +**Field count signals depth.** 5 fields per record is thin. 15 to 20 is competent. 30+ is deep. The field count is not a vanity metric; it determines what the template can render at depth versus what falls back to filler. + +**Required vs optional fields.** Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. A page with 3 of 30 optional fields populated should not ship; a page with 25 of 30 should. + +**Computed fields.** Derived from source data. Average price per square foot computed from listings adds depth without requiring more source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +**Cross-record fields.** Fields that reference other records in the set enable internal linking and comparison. The "5 most similar neighborhoods" field on every neighborhood page powers the sibling-link section without manual curation. + +**Update frequency tags.** Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). Without tagging, refresh becomes "audit everything" instead of "refresh the volatile fields." + +The "schema-as-product" principle. The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. Versioned, reviewed, documented, breaking-change-aware. + +Detail in [`references/schema-design-patterns.md`](references/schema-design-patterns.md). + +--- + +## Quality control at scale + +Auditing all 100,000 pages individually is infeasible. The discipline. + +**Sampling strategy.** Random sample 50 to 200 pages per audit cycle, balanced across data shape (sparse, dense, recent, old, popular categories, niche categories). The sample is not "the latest 50 pages"; it is a stratified sample that exposes problems specific to particular data shapes. + +**Automated checks.** Heading structure, schema validity, internal link count, word count thresholds, duplicate-content checks, broken-link checks. Run on every page on a cadence; surface failures as a queue. + +**Manual review checklist.** For sampled pages, check the top-200-word answer quality, check whether the page would satisfy the user's query, check whether the page reads as distinctive versus templated. The manual review is the layer automated checks miss. + +**Failure thresholds.** If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. The threshold is not negotiable; without it, quality drift compounds invisibly until the algorithm update reveals it. + +**Cohort tracking.** Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. Cohort tracking is the pSEO equivalent of the experimentation team's drift detection. + +The team budget question. A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. If that is not budgeted, the program will decay. The set will look fine on launch and degrade over 6 to 12 months as data drifts, templates ship without QC, and the gap between the QC plan and the actual cadence widens. + +Detail in [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md). + +--- + +## Internal linking across the set + +pSEO sets need intentional internal linking architecture to compound. + +**Hub pages.** Parent-level pages (e.g., "homes for sale in Denver") that link to all child pages (specific neighborhoods). Hub pages are linked from main navigation; they are the entry point for the set's traffic. + +**Sibling linking.** Each page links to 5 to 15 related sibling pages: similar neighborhoods, similar price ranges, similar features. Sibling links are computed from cross-record fields in the schema; they are not manual curation at scale. + +**Reverse-direction linking.** Child pages link up to hub; sibling links go both directions. The graph is bidirectional; PageRank flows both ways. + +**Anchor text variation.** Avoid every page using the same anchor text. Vary by record characteristic (the record name, a descriptive phrase, the parent category). Uniform anchor text at scale signals manipulation to ranking systems. + +**Crawl-friendly architecture.** Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +The PageRank flow principle. Internal linking is what makes pSEO sets compound. A well-linked set distributes ranking signal across all pages; a poorly-linked set has hub pages ranking and child pages orphaned. The link architecture is half the program; the data is the other half. + +Detail in [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md). + +--- + +## Crawl budget management + +Search engines have crawl budgets. Large pSEO sets can exhaust them. + +**Sitemap segmentation.** Split sitemaps by category or recency so crawlers prioritize active pages. A single sitemap with 100,000 entries is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each, organized by category or last-update. + +**Noindex on thin pages.** Pages with insufficient data should noindex rather than ship as bait. The discipline: pages that fail the schema's required-field threshold do not get a public URL; they sit in the system as drafts until their data populates. + +**Canonical handling.** Comparison pages (X vs Y) often have inverse pages (Y vs X). Canonicalize to one. Comparison-pivot duplicates without canonicalization split ranking signal. + +**Crawl rate signals.** Monitor Google Search Console crawl stats. If crawl rate is plateauing while page count grows, the set is hitting budget limits. The fix is not "publish more pages"; it is "noindex thin pages and improve internal linking so crawlers prioritize better." + +**Pruning criteria.** Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. Pruning is hygiene, not failure. A 100,000-page set with 60% earning traffic is healthier than the same set with 40% earning traffic plus 60% dead weight crawlers waste budget on. + +Detail in [`references/crawl-budget-management.md`](references/crawl-budget-management.md). + +--- + +## AEO and GEO for programmatic pages + +Answer engines treat programmatic pages differently from editorial pages. + +**Direct-answer extraction.** AI engines extract the top-200-word answer; templates that lead with the answer get cited. The opening of the page is the citation candidate; everything after it is supporting depth. + +**Structured data signals.** JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. Programmatic pages with minimal schema lose to programmatic pages with deep schema even when the underlying data is similar. + +**Citation patterns.** AI engines tend to cite programmatic data pages for factual queries (prices, statistics, comparisons, factual details) and editorial pages for analytical queries (why, how, what should I think). Design templates to fit the factual-query lane; do not try to make programmatic pages compete for analytical queries that editorial content owns. + +**Quality crackdown sensitivity.** AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. The pSEO penalty risk has migrated to AI surfaces; the same quality-at-scale discipline applies, with less tolerance. + +The "two-engine optimization" framing applies. pSEO pages should serve both search engines and answer engines. Most pSEO programs were designed pre-AEO and need template updates for the new surface: stronger top-200-word answers, deeper schema markup, FAQPage schema where the page contains FAQ structure. + +Detail in [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md). + +--- + +## Refresh and maintenance at scale + +pSEO sets decay if not maintained. + +**Data refresh cadence.** Quarterly minimum for most datasets. Daily or weekly for time-sensitive data (real estate listings, prices, availability, current statistics). The refresh cadence is set when the program launches; retrofitting is expensive. + +**Template version migration.** When the template improves, all existing pages need migration. Cohort-by-cohort migration with monitoring beats big-bang migration. Each cohort gets the new template, sits for 30 days under monitoring, then the next cohort migrates. + +**Pruning lifecycle.** Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. The 24-month checkpoint is the standard cutoff; some categories warrant earlier or later pruning. + +**Set-level refresh.** Occasionally the entire set's template needs a refresh as user expectations evolve, AI engine signals shift, or category conventions change. Set-level refreshes are 6-month projects, not weekend cleanups. + +Detail in [`references/refresh-at-scale.md`](references/refresh-at-scale.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pseo-failures.md`](references/common-pseo-failures.md). + +- "We generated 50,000 pages and got penalized." Thin content, scaled too fast, no QC discipline. +- "We have 10,000 pages but only 200 rank." Internal linking architecture missing; child pages are orphans. +- "Crawl rate plateaued." Crawl budget exhausted; noindex thin pages and improve sitemap segmentation. +- "Pages look identical." Template lacks variable density; data is too sparse to differentiate. +- "We cannot update the templates without 10,000 manual fixes." Template versioning was not designed for scale. +- "Our quality control is whoever has time." No sampling discipline, no thresholds, no ownership. +- "AI engines do not cite our pages." Top-200-word answer was not designed; structured data is thin. +- "We are at 100,000 pages and engagement is dropping." The set has outgrown its data depth. +- "Competitors copied our pages." The data source was not a moat. +- "Refresh is overwhelming." Cadence was not designed for scale; templates are not migration-friendly. +- "Our pSEO drives traffic but no conversions." Query intent does not match buyer intent; reconsider whether pSEO was the right channel for the program goal. + +--- + +## The framework: 12 considerations for programmatic SEO + +When designing or auditing a programmatic SEO program, walk these 12 considerations. + +1. **Right answer for the program.** pSEO needs real underlying data, queryable intent, and quality-control budget. Default to no if any is missing. +2. **Data source as moat.** Replicable data is not defensible; first-party, licensed, expert-curated, or synthesized data is. +3. **Schema depth.** 15+ fields per record minimum; 30+ for competitive depth. +4. **Template variable density.** Accommodates sparse and dense records gracefully. +5. **Above-the-fold answer.** First 200 words answer the user's specific query. +6. **Schema markup at scale.** Structured data on every page; this is the AEO/GEO signal. +7. **Internal linking architecture.** Hub-and-spoke plus sibling linking, no orphans. +8. **Quality control sampling.** 50 to 200 pages per audit, balanced across data shape. +9. **Failure thresholds.** 5% sample failure halts generation until template or data fixes ship. +10. **Crawl budget discipline.** Sitemap segmentation, noindex on thin pages, canonicalization on duplicates. +11. **Refresh cadence.** Quarterly minimum data refresh; cohort-by-cohort template migration. +12. **Pruning lifecycle.** Pages that fail to earn traffic in 12 to 24 months get noindexed or removed. + +The output of the framework is a pSEO design document the team can reference at every stage: data source named, schema versioned, template specified, QC discipline budgeted, internal linking architecture mapped, refresh cadence set. + +--- + +## Reference files + +- [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md) - Five-criterion decision framework with worked examples of yes, no, and maybe. +- [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md) - First-party, licensed, public, expert-curated, synthesized; defensibility analysis. +- [`references/template-design-patterns.md`](references/template-design-patterns.md) - Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. +- [`references/schema-design-patterns.md`](references/schema-design-patterns.md) - Field count, computed fields, cross-record fields, update tags, schema-as-product. +- [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md) - Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. +- [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md) - Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. +- [`references/crawl-budget-management.md`](references/crawl-budget-management.md) - Sitemap segmentation, noindex patterns, canonicalization, crawl rate monitoring, pruning criteria. +- [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md) - Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. +- [`references/refresh-at-scale.md`](references/refresh-at-scale.md) - Data refresh cadence, template versioning, cohort migration, pruning lifecycle. +- [`references/common-pseo-failures.md`](references/common-pseo-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: quality at scale or not at all + +The only durable pSEO programs are the ones that hold quality at scale. The temptation to scale quantity at the cost of quality has produced the entire bad reputation pSEO carries. Sites that resist that temptation, that maintain real data depth, real quality control, real refresh discipline, keep producing meaningful traffic for years. Sites that do not get penalized within months of an algorithm update. + +The discipline is not optional and it is not free. Budget for it before generating the first page, or do not start at all. + +When in doubt about whether a pSEO program is ready, ask: is the data source actually unique, is the schema deep, does the template lead with the answer, is the internal linking architecture mapped, is QC budgeted in headcount, is the refresh cadence set? If yes to all of those, ship the design document and let the engineering work begin. If no to any of them, fix the gap before any pages generate. diff --git a/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md b/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md new file mode 100644 index 0000000..2300287 --- /dev/null +++ b/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md @@ -0,0 +1,106 @@ +# AEO and GEO for programmatic pages + +Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. + +Answer engines treat programmatic pages differently from editorial pages. The differences shape how pSEO templates should be designed for the AI search era. + +--- + +## Direct-answer extraction + +AI engines extract the top-200-word answer; templates that lead with the answer get cited. + +**The pattern.** The opening of the page is the citation candidate. AI engines pull from the first answer-shaped paragraph, FAQPage schema entries, and structured-data fields. Everything after the opening is supporting depth that justifies the citation but is rarely cited directly. + +**Template implication.** The first 200 rendered words must answer the user's specific query in a self-contained way. A page about "homes for sale in Denver under $500k" should answer that exact query in the opening: count of listings, average price, top neighborhoods, with structured data backing each claim. + +**Anti-pattern.** Welcome paragraphs, navigation hints, "below you will find" filler. These dilute the citation candidate and reduce the page's AI-engine pull. + +**Snippet-bait paragraphs at H2 level.** Beyond the top-200-word answer, each H2 should have a 40 to 60 word snippet-bait paragraph. AI engines often quote multiple snippet-bait paragraphs as multi-paragraph citations. + +--- + +## Structured data signals + +JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. + +**The "thin schema" penalty.** Programmatic pages with minimal schema (just the basic Article or Product type, with required fields only) lose to programmatic pages with deep schema (complete schema graph, optional fields populated, cross-entity references). The underlying data may be similar; the schema markup is what AI engines see. + +**Schema patterns that signal quality at scale.** + +- **Type-appropriate schema.** Product for product pages, LocalBusiness for location pages, Article for editorial pages, FAQPage for FAQ sections, BreadcrumbList for navigation context. +- **Cross-entity references.** Schema entries that reference other entities in the dataset (relatedProduct, parentOrganization, hasPart) signal a connected knowledge graph rather than isolated pages. +- **Aggregate schema.** Reviews, ratings, statistics presented as structured aggregateRating, aggregateOffer, aggregateProperty fields. +- **FAQPage schema on FAQ sections.** AI engines (Perplexity especially) cite FAQPage-marked content heavily; programmatic pages that include FAQ sections should mark them. + +**Schema validation.** Run schema validation on every page; failures produce silent invisibility in AI surfaces. The validation is automated and gates publish. + +--- + +## Citation patterns + +AI engines cite programmatic data pages and editorial pages for different query types. + +**Factual-query lane.** AI engines tend to cite programmatic data pages for factual queries: prices, statistics, comparisons, factual details, specifications, locations, ratings. The page renders the fact as structured data; the AI engine cites the structured data as the answer. + +**Analytical-query lane.** AI engines tend to cite editorial pages for analytical queries: why, how, what should I think, recommendations with reasoning, opinions, judgments. Programmatic pages cannot compete in this lane; the data does not supply the analysis the user wants. + +**Implication for pSEO design.** Design templates to fit the factual-query lane. Do not try to make programmatic pages compete for analytical queries that editorial content owns. The two lanes coexist; pSEO is one half of a two-lane content strategy. + +**The "hybrid page" pattern.** Some pSEO programs add an editorial layer to programmatic pages (per-page expert commentary, AI-summarized analysis with human review). Hybrid pages can compete in both lanes when the editorial layer is genuinely substantive. Without substantive editorial layer, hybrid pages read as factual pages with filler attached and lose in both lanes. + +--- + +## Quality crackdown sensitivity + +AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. + +**The migration of penalty risk.** Pre-AI search era, thin pSEO sets could rank for 12 to 24 months before quality crackdowns hit. AI engines apply quality signals more aggressively. Thin pSEO sets in 2026 lose AI citations within 3 to 6 months even when traditional search rankings are still holding. + +**Signals AI engines use beyond traditional search signals.** + +- **Distinctiveness.** Pages that read as templated boilerplate get deprioritized. Pages that surface page-specific data prominently get cited. +- **Source credibility.** Pages with named authors, expert credentials, and citation chains get cited preferentially. Anonymous pSEO pages with no attribution lose to attributed pages. +- **Citation traceability.** Pages that cite their underlying data sources (with links to the source) get treated as authoritative. Pages that present facts without sourcing get treated as unreliable. +- **Freshness.** Pages with recent update dates get cited preferentially for time-sensitive queries. Stale pages lose AI citations even when traditional search rankings hold. + +**The implication.** pSEO programs designed pre-AEO need template updates: stronger above-the-fold answers, deeper schema markup, FAQPage schema on FAQ sections, source citations on factual claims, named authorship where the program supports it. + +--- + +## Two-engine optimization + +pSEO pages should serve both search engines and answer engines. + +**Both engines reward depth.** Search engines reward comprehensive coverage; AI engines reward citation-ready depth. Same content, different extraction. + +**Both engines reward structure.** Search engines parse heading hierarchy for ranking; AI engines parse heading hierarchy for citation extraction. Same structure, different use. + +**Both engines reward freshness.** Search engines reward recent updates; AI engines re-index recently updated content more aggressively. Same updates, different cadence. + +**The two-engine implication.** Designing for AEO does not trade off against SEO. The template improvements that earn AI citations (top-200-word answers, FAQPage schema, named authorship, source citations) also earn search rankings. Teams that treat AEO and SEO as separate optimizations under-invest in both. + +--- + +## Set-level reputation signals + +Beyond individual page signals, AI engines apply set-level reputation. The set's overall quality affects each page's citation likelihood. + +**Domain-level reputation.** A domain with a substantive editorial content layer plus a high-quality pSEO set ranks both layers more strongly than a domain with only pSEO. The editorial layer establishes the domain's expertise; the pSEO layer benefits. + +**Set-level signal compounds.** A 10,000-page pSEO set with 90% high-quality pages and 10% thin gets the entire set treated as high-quality. The same set with 60% high-quality pages and 40% thin gets the entire set deprioritized. The bad pages drag the good ones down. + +**The implication.** Set-level QC discipline (covered in `quality-control-at-scale.md`) is also AEO discipline. Holding the quality threshold across the set protects the set's AI-citation reputation, not just its search ranking. + +--- + +## Measurement + +Hub-level AEO/GEO metrics worth tracking on the pSEO set: + +- Brand mention rate from AI search visibility tools (Profound, Frase visibility tracking, AirOps AEO data) +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude, Google AI Mode) on the set's target queries +- Top-cited pages within the set (which template patterns get cited most) +- AI crawler hit frequency from server logs (GPTBot, PerplexityBot, ClaudeBot) + +Track at the set level, not just per page. Aggregate trends surface patterns that per-page tracking misses. diff --git a/skills/programmatic-seo/references/common-pseo-failures.md b/skills/programmatic-seo/references/common-pseo-failures.md new file mode 100644 index 0000000..175bb9b --- /dev/null +++ b/skills/programmatic-seo/references/common-pseo-failures.md @@ -0,0 +1,161 @@ +# Common pSEO failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: pSEO programs that ship without one of the five readiness criteria (real data, queryable intent, sufficient volume, refresh cadence, QC budget) and assume the gap will close later. The gap rarely closes; the failure compounds. + +--- + +## "We generated 50,000 pages and got penalized" + +**Symptom.** Algorithm update lands; the set loses 60 to 90% of its traffic in days. + +**Diagnosis.** Thin content scaled too fast without QC discipline. The set was generating filler pages, sometimes from AI-summarized public data, sometimes from sparse first-party data with bolt-on AI text. The algorithm update detected the scale-without-substance pattern. + +**Fix.** Halt new generation. Run a triage audit: which pages have substantive data backing them, which are filler. Noindex the filler. The remaining pages may recover ranking once the set's quality signal improves; the filler ones will not. Sometimes the right call is removing the entire pSEO surface and rebuilding from a higher-quality data source. + +**Prevention.** The five-criterion check (`when-pseo-works-decision.md`) before launch. The QC discipline (`quality-control-at-scale.md`) before scaling. + +--- + +## "We have 10,000 pages but only 200 rank" + +**Symptom.** Pages exist in the set; few of them rank for their target queries. + +**Diagnosis.** Internal linking architecture missing or incomplete. Hub pages rank because they receive site-wide navigation links. Child pages do not rank because they have no in-page link votes; they are partial orphans reachable only via sitemap. + +**Fix.** Build the link graph. Add sibling-link slots to the template. Compute cross-record similarity to populate sibling links. Backfill the link graph across the existing set. Audit for orphans; surface them in the QC queue (`internal-linking-at-scale.md`). + +--- + +## "Crawl rate plateaued" + +**Symptom.** Page count grows; pages crawled per day stays flat or declines. + +**Diagnosis.** Crawl budget exhaustion. The set has more pages than the search engine's crawl budget supports. + +**Fix.** Noindex thin pages. Segment sitemaps. Improve internal linking so crawlers prioritize substantive pages. Reduce server response time. Prune the dead-page tail. Detail in `crawl-budget-management.md`. + +The wrong fix: publishing more pages to "catch up" on traffic targets. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## "Pages look identical" + +**Symptom.** Random sampling of pages from the set finds them indistinguishable in substance, only different in identifiers. + +**Diagnosis.** Template lacks variable density, or the data is too sparse to differentiate. The template renders the same boilerplate for every record because the records do not actually differ on the dimensions the template surfaces. + +**Fix.** Two paths. + +- If the template is the problem (the data has variation but the template hides it): redesign the template to surface distinctive fields prominently. Move the differentiating data above the fold; demote the boilerplate. +- If the data is the problem (the records genuinely lack distinctive fields): the schema is too thin. Either deepen the schema with more source data, or accept that the program does not justify pSEO and pivot to editorial content. + +--- + +## "We cannot update the templates without 10,000 manual fixes" + +**Symptom.** A template change requires manually editing every existing page. + +**Diagnosis.** Template versioning was not designed for scale. Pages were generated as static output rather than as renders from the schema; updating the template now requires updating each rendered page. + +**Fix.** Architectural rebuild. Pages need to be re-rendered from the schema each time the template changes. The schema is the source of truth; the rendered pages are the output. Without this discipline, every template change becomes a per-page migration project. + +**Prevention.** Design pages as renders from data, not as static artifacts. The specific stack choice (build-time generation that re-runs on template change, server rendering with template version in the cache key, hybrid approaches) varies by team; the methodology principle is the same. + +--- + +## "Our quality control is whoever has time" + +**Symptom.** No regular QC cadence. Sample audits happen sporadically when someone notices a problem. + +**Diagnosis.** No sampling discipline, no thresholds, no ownership. The QC was assumed to be everyone's job, which means it is nobody's job. + +**Fix.** Assign a QC owner. Set the sampling cadence (monthly minimum for active programs). Codify the failure threshold (5% sample failure halts new generation). Track cohort metrics. Detail in `quality-control-at-scale.md`. + +--- + +## "AI engines do not cite our pages" + +**Symptom.** Traditional search rankings are stable; brand mention rate from AI search visibility tools is flat or declining. + +**Diagnosis.** Multiple possible causes. + +- The top-200-word answer was not designed; pages start with welcome paragraphs instead of answers. +- Schema markup is thin; AI engines see the pages as low-authority. +- FAQPage schema is missing on FAQ sections. +- Source citations are missing on factual claims. +- The pages read as templated boilerplate rather than as distinctive answers. + +**Fix.** Audit the template against the AEO/GEO patterns (`aeo-geo-for-programmatic-pages.md`). Update the template; migrate cohorts; monitor citation count by cohort to confirm the fix earned gains. + +--- + +## "We are at 100,000 pages and engagement is dropping" + +**Symptom.** Traffic continues but bounce rate climbs, time-on-page falls, conversion rate decays. + +**Diagnosis.** The set has outgrown its data depth. Early pages were the highest-data-quality records; later pages were lower-quality data backfilled to grow the set. Users are landing on pages that do not satisfy their query. + +**Fix.** Reverse the growth and prune. The set should be smaller and higher-quality, not larger and lower-quality. Identify the data-quality threshold below which pages do not satisfy queries; noindex pages below the threshold; let the set's average quality recover. + +**Prevention.** The required-field threshold in the schema enforces a quality floor. Pages that fail the threshold should not have shipped in the first place. + +--- + +## "Competitors copied our pages" + +**Symptom.** A competitor launched a similar pSEO set; the brand's traffic share is shrinking. + +**Diagnosis.** The data source was not a moat. The pSEO pages were replicable. + +**Fix.** Two paths. + +- Deepen the data source. First-party data accumulation, expert curation investment, licensed-feed integration that competitors cannot match. The defensibility comes from the data, not from the pSEO build. +- Pivot. If the data cannot be deepened, the program does not have a long-term moat. Consolidate the strongest pages, prune the rest, redirect the team to higher-defensibility work. + +**Prevention.** The defensibility test (`data-source-identification-patterns.md`) before launch. If competitors could replicate the data source within 6 months at reasonable cost, do not launch the program. + +--- + +## "Refresh is overwhelming" + +**Symptom.** Quarterly refresh cycles are missed or partially completed; data drifts; pages get stale. + +**Diagnosis.** Refresh cadence was not designed for scale. The team thought "we will refresh quarterly" but the actual work to refresh 10,000 to 100,000 pages exceeds the team's quarterly capacity. + +**Fix.** Automate the volatile-field refresh through data pipelines (mostly hands-off after pipeline build). Reduce slow-changing-field refresh frequency to annual on most fields. Cohort-migrate the template refresh rather than big-bang. Detail in `refresh-at-scale.md`. + +If the work still exceeds capacity after these fixes, the set is too large for the team's resources. Prune to a sustainable size. + +--- + +## "Our pSEO drives traffic but no conversions" + +**Symptom.** Traffic from pSEO pages is high; signups, sales, or engagement on the funnel goal are flat or low. + +**Diagnosis.** Query intent does not match buyer intent. The pSEO pages are answering informational queries; the buyer the program needs to capture is searching with different intent. + +**Fix.** Audit the queries the pSEO traffic is coming from. If the queries are not in the buyer's funnel, the program is producing non-converting traffic regardless of how well the pages are optimized. The fix is not "add more CTAs to pSEO pages"; the fix is recognizing that pSEO was not the right channel for the program's conversion goal. + +**The reconsider-pSEO moment.** If the program's metric is conversions and the pSEO traffic does not convert, pSEO is the wrong tool. Editorial content with stronger buyer-intent alignment, paid acquisition with conversion tracking, or product-led growth surfaces may be the better fit. + +--- + +## "Our QC discipline drifted over time" + +**Symptom.** The program launched with strong QC. Months in, the cadence slipped, the threshold became aspirational rather than enforced, the cohort tracking went unread. + +**Diagnosis.** QC ownership rotated, accountability dispersed, the metric dashboard stopped being reviewed. The pattern is the same as the "set and forget" failure for editorial pillar maintenance. + +**Fix.** Assign a durable QC owner with quarterly accountability. Reinstate the cadence. Audit the set for the drift that accumulated; fix or noindex pages that ship below the threshold. + +**Prevention.** The QC owner is named in the program's planning doc and renewed annually. The dashboard that tracks cohort metrics has an actual owner who reviews it monthly. The threshold is treated as enforced, not aspirational. + +--- + +## The pattern across all failures + +Most pSEO failures are designed-in. They were predictable from the program's launch shape. The five-criterion check, the schema-as-product principle, the QC budget, the refresh cadence, the link architecture: each one shipped or did not at design time. The set's eventual success or decay was largely determined before the first page generated. + +The discipline is upstream. Hold the line at design time; the operational discipline at scale becomes manageable. Skip the design discipline; the program produces filler at scale and gets penalized. diff --git a/skills/programmatic-seo/references/crawl-budget-management.md b/skills/programmatic-seo/references/crawl-budget-management.md new file mode 100644 index 0000000..8d28d56 --- /dev/null +++ b/skills/programmatic-seo/references/crawl-budget-management.md @@ -0,0 +1,115 @@ +# Crawl budget management + +Sitemap segmentation, noindex on thin pages, canonicalization on duplicates, crawl rate monitoring, pruning criteria. + +Search engines have crawl budgets. Large pSEO sets can exhaust them. Crawl budget management is the discipline that keeps the set crawlable as it scales past 10,000+ pages. + +--- + +## Sitemap segmentation + +A 100,000-page sitemap is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each. + +**Segmentation by category.** One sitemap per top-level category. Crawlers prioritize sitemaps differently; segmentation helps the crawler prioritize active categories over dormant ones. + +**Segmentation by recency.** A "recent" sitemap surfaces pages generated in the last 30 days. Crawlers find new content faster; existing content remains crawlable through category sitemaps. + +**Segmentation by update frequency.** A "frequently-updated" sitemap surfaces pages whose volatile fields refresh weekly or daily. Crawlers re-crawl these pages on a tighter cadence. + +**Sitemap index.** A parent sitemap-of-sitemaps points to all segmented sitemaps. The index is what gets submitted to Search Console; the segments handle the actual page lists. + +**Sitemap size limits.** 50,000 URLs per sitemap is the hard limit. 10,000 to 25,000 per segmented sitemap is the typical practical size; smaller is fine for niche categories, larger is fine for high-volume categories. + +--- + +## Noindex on thin pages + +Pages with insufficient data should noindex rather than ship as bait. + +**The discipline.** Pages that fail the schema's required-field threshold do not get a public URL. They sit in the system as drafts until their data populates. + +**Why noindex matters.** Thin pages drag down the entire set's quality signal. Search engines and AI engines both apply set-level quality scoring; a set with 10,000 thin pages and 90,000 substantive pages scores worse than a set with just the 90,000 substantive pages, even though the absolute page count is lower. + +**Noindex implementation patterns.** + +- The thin pages render with a `noindex` meta tag in the head. +- The thin pages are excluded from the sitemap. +- The thin pages are not linked from any other page in the set. + +**The "we'll fix it later" trap.** Teams ship thin pages with `index, follow` and plan to backfill data later. The data backfill rarely happens; the thin pages accumulate; the set's quality signal degrades over time. + +--- + +## Canonical handling + +Comparison pages and other pivot patterns produce duplicate-content risks. + +**The X-vs-Y pattern.** A page comparing X to Y often has an inverse page comparing Y to X. The two pages cover the same content from different orderings. Canonicalize one to the other. + +**Canonical decision.** Pick the canonical based on search volume, alphabetical order, or category hierarchy. The choice itself matters less than picking one consistently. + +**Other pivot patterns.** + +- **Filter pivots.** "Homes in Denver under $500k" and "Homes under $500k in Denver" should canonicalize to one. +- **Sort pivots.** "Top hotels in Paris by rating" and "Top hotels in Paris by price" might be distinct enough to live separately, or might canonicalize depending on the user-intent overlap. +- **Date pivots.** "Best [thing] for 2025" and "Best [thing] for 2026" usually live separately because the content genuinely differs by year; canonicalization would lose the time-relevance signal. + +**The discipline.** Canonical decisions are designed at template time, not retroactively. The template either generates canonical-pair URLs (and chooses one as canonical from the start) or it does not generate the duplicate at all. + +--- + +## Crawl rate monitoring + +Search engines publish crawl statistics. Monitor them. + +**Google Search Console crawl stats.** Pages crawled per day, average response time, crawl request distribution by category. Monitor monthly; investigate drops or plateaus. + +**Crawl rate plateauing while page count grows.** The set is hitting crawl budget limits. The fix is not "publish more pages." The fix is: + +- Noindex thin pages to remove low-value crawl targets +- Improve internal linking so crawlers prioritize the substantive pages +- Segment sitemaps so the crawler can prioritize active categories +- Reduce server response time so crawlers can crawl more in the same budget + +**Crawl rate dropping unexpectedly.** Investigate. Common causes: server errors that the crawler is encountering, robots.txt changes that excluded important paths, sitemap submissions that broke, large-scale URL pattern changes without redirects. + +--- + +## Pruning criteria + +Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. + +**The 6-month checkpoint.** A page that has been in the set for 6+ months and has earned zero impressions in Search Console is dead weight. The fix is not "wait longer." + +**Pruning options.** + +- **Noindex.** The page stays accessible to direct visitors but is removed from the search index. Reversible if the page later starts earning impressions. +- **410 Gone.** The page is removed entirely; the URL returns 410. Permanent; appropriate for genuinely obsolete content. +- **301 Redirect.** The page redirects to a more-relevant alternative. Appropriate when the user's intent for the dead page can be served by an alternative page that still exists. + +**The 12-month and 24-month checkpoints.** Pages that have not earned traffic by month 12 should be reviewed for noindex or removal; pages that have not earned traffic by month 24 should be removed unless there is a specific strategic reason to keep them. + +**Why pruning matters.** Dead pages waste crawl budget. Crawlers visit them, find nothing useful, and the set's average quality signal degrades. Pruning concentrates the set's PageRank on the pages that earn traffic. + +--- + +## When the set is too large for the budget + +Symptoms: + +- Crawl rate is permanently below the page count's natural crawl demand +- New pages take weeks or months to get indexed +- Existing pages drop out of the index unexpectedly +- The site's overall ranking is degrading despite the set being substantively unchanged + +The diagnosis is usually crawl budget exhaustion. The fix is set reduction (prune to the substantive pages), set restructuring (split into multiple subdomains or sites if appropriate), or technical optimization (server response time, sitemap discipline). + +The temptation is to publish more pages to "catch up" with traffic targets. The temptation is wrong. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## Methodology vs implementation + +The principles above are methodology: which pages to noindex, when to canonicalize, how to segment sitemaps, how to read crawl stats. + +The specific implementation (the framework's noindex meta tag pattern, the sitemap generation library, the canonical link helpers, the deployment-time crawl-test integration) is stack-specific. Each team implements crawl budget management within their own stack's tooling; the methodology applies regardless of the implementation choice. diff --git a/skills/programmatic-seo/references/data-source-identification-patterns.md b/skills/programmatic-seo/references/data-source-identification-patterns.md new file mode 100644 index 0000000..e6fa193 --- /dev/null +++ b/skills/programmatic-seo/references/data-source-identification-patterns.md @@ -0,0 +1,104 @@ +# Data source identification patterns + +First-party, licensed, public, expert-curated, synthesized. Defensibility analysis for each pattern. + +The data source IS the pSEO program. A weak data source produces a weak set regardless of template quality, internal linking, or QC discipline. A strong data source produces durable traffic that compounds across years. + +--- + +## Pattern 1: first-party data + +Data the team owns because the business produced it. + +**Sources.** Customer transactions, content database, user-generated content, support ticket history, internal product analytics, sales call records, customer feedback databases. + +**Defensibility.** Maximum. Nobody else has the data. A competitor would have to build the same business and accumulate the same usage history to replicate. + +**Examples.** Glassdoor's employee reviews (built by getting employees to submit). Yelp's restaurant ratings (built by getting users to rate). TripAdvisor's traveler reviews (built by getting travelers to write). Reddit's discussion threads (built by getting users to post). + +**Watchouts.** Privacy and terms-of-service compliance. User-generated content used for pSEO needs explicit consent in the original collection terms; retrofitting consent is not legal in most jurisdictions. PII in pSEO pages is a separate liability. + +**The "moat compounds over time" effect.** First-party data sources get stronger as the business runs longer. A 10-year-old review database is more defensible than a 2-year-old one with the same volume because the time-series depth itself becomes valuable. + +--- + +## Pattern 2: licensed datasets + +Data acquired through commercial licensing. + +**Sources.** Industry databases (real estate MLS, automotive VIN databases, sports statistics feeds), regulatory data (SEC filings, government statistics), third-party content licenses (medical content, legal precedent). + +**Defensibility.** Medium to high. Defensibility depends on license exclusivity and integration depth. An exclusive license is a moat; a non-exclusive license that anyone can also buy is not. + +**Examples.** Zillow's MLS partnerships (licensed feeds with depth integration). Sportradar customers building stats sites. Bloomberg Terminal customers building financial content. Real estate brokerages with regional MLS access. + +**Watchouts.** License costs scale with usage; the unit economics need to work at scale. License terms typically restrict redistribution, which can complicate pSEO scaling (the data can power the pSEO pages but cannot be exported as a downloadable dataset). + +--- + +## Pattern 3: aggregated public data + +Data scraped, cleaned, enriched from public sources. + +**Sources.** Open government data, public web pages, academic research, public APIs. + +**Defensibility.** Low to medium. Anyone can scrape the same sources; the defensibility comes from the cleaning and enrichment work. If the cleaning is shallow, the defensibility is none. + +**Examples.** Sites built on government statistics (census data, BLS data). Sites built on academic research summaries. Sites built on public company filings (EDGAR data plus enrichment). + +**Watchouts.** Legality is jurisdictional and often gray. robots.txt compliance, terms-of-service review, copyright considerations, anti-circumvention rules in some jurisdictions. The legal review is mandatory, not optional, even when the data is "public." + +**The "scraped Wikipedia plus AI rewrite" anti-pattern.** The lowest-effort form of this category. The data is not really enriched (AI rewrite of public encyclopedia entries adds no defensible value). The pSEO sets built on this pattern are the ones that get penalized first when algorithm updates run. + +--- + +## Pattern 4: expert-curated content + +Data produced by hired experts who populate the dataset by hand. + +**Sources.** Expert-written reviews, expert-curated lists, professionally-tested products, professionally-evaluated services, professional translations. + +**Defensibility.** High. The defensibility is in the curation cost. A competitor would have to hire and pay the same experts for the same time to replicate. + +**Examples.** Wirecutter's product testing (experts test products in lab conditions). Consumer Reports' product reviews. Edmunds' car reviews. Specialty publications with paid expert contributors. + +**Watchouts.** Slow to build. The set scales at the speed of expert capacity, not at the speed of automated generation. Budget reflects the headcount, not the engineering effort. + +**The combination pattern.** Expert-curated content often combines with structured data (the expert reviews a car; the dataset captures the expert's score plus structured specifications) to produce pages with both narrative depth and queryable structure. + +--- + +## Pattern 5: synthesized data + +Data produced by combining multiple sources into a unique view. + +**Sources.** Multi-source pipelines that produce derived analyses unavailable from any single source. + +**Defensibility.** Medium to high. Defensibility comes from the synthesis logic and the ongoing pipeline maintenance. + +**Examples.** "Neighborhoods times schools times prices" combining three datasets into a comparison view. "Companies times salaries times employee reviews" combining three sources into a candidate-decision view. Aggregator pages that show "best X for Y use case" combining multiple product databases with use-case classification. + +**Watchouts.** The synthesis logic is the moat, not the underlying sources. Changes to source schemas break the pipelines. The pSEO program inherits the operational fragility of multi-source pipelines. + +--- + +## The defensibility test + +For each candidate data source, walk this question: would a competitor be able to replicate this source within 6 months at reasonable cost? + +- **Yes, easily.** No moat. Pursue editorial content instead, or invest in expert curation to build a moat. +- **Yes, with effort.** Partial moat. The first-mover advantage matters; ship before competitors. +- **No, requires major investment.** Real moat. pSEO compounds. +- **No, requires assets the competitor cannot acquire.** Strongest moat. The pSEO program becomes a long-term competitive advantage. + +--- + +## Combining patterns + +The strongest pSEO programs combine multiple patterns. + +- First-party data plus licensed data (Glassdoor: user reviews plus salary licenses) +- Licensed data plus expert curation (Wirecutter: licensed product databases plus expert testing) +- First-party data plus synthesized data (Yelp: user ratings synthesized with location data and external attributes) + +Single-pattern programs are simpler to ship but easier to replicate. Multi-pattern programs are harder to build and harder to copy. diff --git a/skills/programmatic-seo/references/internal-linking-at-scale.md b/skills/programmatic-seo/references/internal-linking-at-scale.md new file mode 100644 index 0000000..6c4d441 --- /dev/null +++ b/skills/programmatic-seo/references/internal-linking-at-scale.md @@ -0,0 +1,116 @@ +# Internal linking at scale + +Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. + +The internal-link graph is half the program; the data is the other half. A well-linked pSEO set distributes ranking signal across all pages and compounds. A poorly-linked set has hub pages ranking and child pages orphaned. + +--- + +## Hub-and-spoke architecture + +The standard pSEO link topology. + +**Hub pages.** Parent-level pages that aggregate the children. "Homes for sale in Denver" is a hub for the neighborhoods; "Software engineer salaries" is a hub for the company-specific salary pages; "Hotels in [city]" is a hub for individual hotel pages. + +**Hub-level discipline.** + +- Hub pages are linked from main site navigation, not just from sitemaps. Crawlers reach hubs first and traverse to children from there. +- Hub pages link to all children in the category. The hub's body or a paginated listing exposes the full set. +- Hub pages are not just link aggregators; they have their own content (category overview, comparison tables, top-of-category aggregates) that earns ranking on its own. + +**Spoke pages.** The individual records. Each spoke links up to the hub and laterally to siblings. + +--- + +## Sibling linking + +Each page links to 5 to 15 related sibling pages. + +**The pattern.** The sibling-link section of the template renders 5 to 15 related records computed from cross-record fields in the schema. Most-similar-by-attribute, similar-price-range, similar-features, geographic neighbors. + +**Why sibling linking matters.** Without it, the link graph is a star (hub to spokes only). PageRank concentrates at the hub; spokes get minimal flow. With sibling linking, the graph is dense; PageRank distributes across the set. + +**Bidirectional linking.** Sibling links go both directions. If A links to B as a sibling, B should link to A. Asymmetric sibling linking creates ranking dead ends. + +**Avoiding the "everyone links to everyone" trap.** Every page linking to every other page is a complete graph; anchor text relevance dilutes; the link graph reads as algorithmic rather than semantically meaningful. The 5 to 15 sibling-link cap keeps each page's outbound graph navigable and signal-dense. + +--- + +## Reverse-direction (bottom-up) linking + +Spoke pages link UP to hub. + +**The first-200-words pattern.** The spoke page's introduction includes a contextual link up to the hub: "This page covers [specific record]. For the broader [category] overview, see [hub page]." + +**The closing pattern.** The spoke page's closing includes a link back to the hub or to the next-most-relevant sibling, giving readers a navigation path back to broader content. + +**Why bottom-up matters.** Without it, the hub does not compound. The spokes inherit traffic from their long-tail queries; without bottom-up links, that traffic does not flow back to lift the hub. + +--- + +## Anchor text variation + +Avoid every page using the same anchor text. + +**The principle.** Anchor text is the signal that tells search engines what the linked-to page is about. Identical anchor text across thousands of links to the same page reads as manipulation; varied anchor text reads as natural authority. + +**Variation patterns for pSEO.** + +- **Record-name variation.** "View [neighborhood name]" / "[neighborhood name] homes for sale" / "Browse [neighborhood name] listings" / "[neighborhood name] guide" used across different siblings linking to the same record. +- **Descriptive variation.** Anchor text that describes the linked page's distinctive attribute. "Affordable [neighborhood]" / "Top-rated [neighborhood]" / "Family-friendly [neighborhood]" computed from the target record's attributes. +- **Context-driven variation.** The anchor text shifts based on what the linking page is about. A page about prices uses price-relevant anchor text; a page about schools uses school-relevant anchor text. + +**Anti-pattern.** Every sibling link uses "[Record name]" as the anchor. Easy to ship at scale, signals manipulation, dilutes the page's anchor profile. + +--- + +## Crawl-friendly architecture + +Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +**Sitemap segmentation.** A pSEO set with 50,000 child pages does not put all 50,000 in a single sitemap. Segment by category, by recency, by data freshness. Crawlers process segmented sitemaps more reliably. + +**Sitemap-only access is not enough.** A child page only reachable via sitemap, with no other page linking to it, is a partial orphan. Crawlers may visit it; the page will struggle to compound ranking signal because no in-page link votes for it. + +**The orphan check.** Pages with zero inbound internal links besides the sitemap are orphans. Audit quarterly; surface in QC. The fix: add the page to the hub's listing, add it to sibling sets it should belong to, expose it through breadcrumb navigation. + +--- + +## The PageRank flow principle + +Internal linking is what makes pSEO sets compound. + +**The pattern that compounds.** Hub linked from main nav (high PageRank concentration). Hub links to all children (PageRank distributes). Children link laterally to siblings (PageRank circulates within the set). Children link back up to hub (PageRank reinforces). + +**The pattern that does not compound.** Hub linked from main nav. Hub links to children. Children do not link to siblings, do not link back to hub. PageRank flows hub-to-child but does not circulate; child pages slowly accumulate independent ranking signal but never compound. + +**The auditable signal.** Average internal-links-in per page. The set's average should be 8 to 20 inbound internal links per page. Below 5, the set is under-linked and orphans dominate. Above 30, the set is link-dense and anchor signal dilutes. + +--- + +## Linking inventory + +Maintain an inventory of every internal link in the pSEO set. + +**Inventory format.** A queryable dataset (typically a database table or analytics schema) tracking source page, target page, anchor text, link slot (breadcrumb / hub / sibling / related-record / related-content), link direction, last-validated date. + +**Why inventory matters.** + +- Quarterly audits run queries against the inventory: orphan check, sibling symmetry check, anchor diversity check, broken-link check. +- Template changes that affect linking (slot adjustments, anchor pattern changes) can be analyzed against the inventory before shipping. +- Pruning decisions reference the inventory: "if we noindex these 200 pages, what siblings lose links and need their slots refilled?" + +**The "no inventory" failure.** Without inventory, audits become "crawl the site each time," which is slow and produces inconsistent results. The inventory turns audit into a query operation. + +--- + +## When linking architecture is broken + +Symptoms: + +- Hub pages rank, child pages do not (under-linked spokes; add sibling linking) +- Specific category cluster does not rank as well as siblings (the category's internal links are sparse; investigate) +- Crawl rate plateaus while page count grows (link graph cannot absorb new pages; sitemap and link slots need restructuring) +- Algorithm update hits child pages disproportionately (children read as orphans without hub-and-spoke reinforcement) + +The fix is rarely "more pages." The fix is usually "better link graph through the existing pages." Internal linking is the structural multiplier. diff --git a/skills/programmatic-seo/references/quality-control-at-scale.md b/skills/programmatic-seo/references/quality-control-at-scale.md new file mode 100644 index 0000000..c108409 --- /dev/null +++ b/skills/programmatic-seo/references/quality-control-at-scale.md @@ -0,0 +1,126 @@ +# Quality control at scale + +Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. The discipline that distinguishes durable pSEO from penalty-bait. + +Auditing all 100,000 pages individually is infeasible. Quality control at scale is sampling discipline plus automated checks plus failure thresholds plus cohort tracking. Without it, pSEO sets degrade silently until algorithm updates expose the rot. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle, balanced across data shape. + +**Stratified sampling.** Not "the latest 50 pages" or "the top-traffic 50 pages." A stratified sample exposes problems specific to particular data shapes. + +Stratification dimensions: + +- **Sparse vs dense data.** Sample some records with minimum-required fields; sample some with most-fields-populated. +- **Recent vs old.** Sample some pages generated in the last 30 days; sample some generated 12+ months ago. +- **Popular vs niche categories.** Sample some pages from high-traffic parent categories; sample some from low-traffic ones. +- **Different cohort versions.** If the template has shipped revisions, sample some pages from each cohort. + +**Sample size by set size.** + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +**Cycle frequency.** Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks + +Run on every page on a cadence; surface failures as a queue. + +**Heading-structure check.** Validates H1 exists once, H2s are in order, no orphan H3s, no H2-H3-H4 cascades that nobody scrolls. + +**Schema-validity check.** Validates JSON-LD against the page's intended schema type; flags missing required fields, type mismatches, malformed structured data. + +**Internal-link-count check.** Flags pages with fewer than 10 internal links (under-linked) or more than 50 (link-dense, anchor-signal-diluting). + +**Word-count threshold check.** Flags pages below the template's minimum (typically 300 to 500 words depending on category). Pages below the threshold either need data backfill or should sit as drafts. + +**Duplicate-content check.** Hash similarity across the set; flags pages with >80% content overlap with another page in the set. Common cause: comparison pages where X-vs-Y duplicates Y-vs-X without canonicalization. + +**Broken-link check.** Crawl outbound and internal links; flag 404s and 5xx responses. Ages quickly without the check; cluster pieces that linked to deleted records become orphan-link generators. + +**Schema-population-rate check.** For each optional schema field, the percentage of pages that populate it. Flag fields with population rates below 50%; these usually need either to be required, dropped, or backfilled. + +--- + +## Manual review checklist + +For sampled pages, the human review covers what automation misses. + +**Above-the-fold answer quality.** Read the first 200 words. Does it answer the user's likely query? Is the language specific to this record or templated boilerplate? + +**Distinctive vs templated.** Compare the page to two siblings. Could you tell them apart on substance, not just on the names? If they read identically, the template lacks variable density or the data is too sparse to differentiate. + +**Citation-readiness.** Would an AI engine cite this page for the user's query? Specifically: is there a self-contained answer paragraph, are statistics with sources present, is FAQPage or Article schema marked correctly? + +**User-intent satisfaction.** If a real user landed on this page from the target SERP, would they stay or bounce? Bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +**Off-brand or off-tone signals.** Does the page read consistently with the brand voice? Templated pSEO tends to drift toward generic neutral voice; the brand voice should still be present. + +--- + +## Failure thresholds + +If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. + +**The 5% threshold.** Empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +**What "halt" means.** New page generation stops. The template or data fix is shipped. The next sample audit confirms the fix improved the failure rate before generation resumes. + +**Why halt instead of "fix as you go."** Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +**The threshold is not negotiable.** "Just ship the next batch and we'll fix later" is the failure mode. The pattern produces pSEO sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. + +**Cohort cuts.** Pages from a given month, pages from a given template version, pages from a given data-source version. Track ranking, click-through rate, citation count (from AEO measurement), and engagement metrics by cohort. + +**Drift signals.** + +- **Cohort A pages rank top 10; cohort B pages rank position 30.** Template or data changed between cohorts; identify the change. +- **Cohort A pages get cited; cohort B pages do not.** Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- **Cohort A pages have stable engagement; cohort B pages have decaying engagement.** Cohort B may have a data freshness problem. + +**Why cohorts matter.** Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically; aggregate tracking misses it. + +--- + +## Team budget + +A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. A 100,000-page set requires 2 to 4 FTE. + +**Where the headcount goes.** + +- Sample audit cycles (monthly to quarterly) +- Automated check failure queue triage +- Manual review of sampled pages +- Template or data fixes when failures surface +- Cohort tracking analysis and investigation +- Refresh cycle execution (volatile-field refresh, template-version migration) + +**The "we'll get to QC later" failure.** Programs that ship without QC headcount budgeted typically degrade within 6 to 12 months. The set looks fine on launch day; the data drifts, the template ships untracked changes, the cohort gap widens, and by month 12 the algorithm update finds the rot. + +**The discipline.** Budget the QC headcount before generating the first page. If the budget cannot absorb 0.5+ FTE for ongoing QC, the program's scope is too large; reduce scope until QC fits. + +--- + +## When QC reveals the program is broken + +Sometimes the QC discipline reveals that the underlying program is wrong, not just that individual pages need fixes. Signals: + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole in that category; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. The sunk cost is real but smaller than the cost of continuing to generate filler. diff --git a/skills/programmatic-seo/references/refresh-at-scale.md b/skills/programmatic-seo/references/refresh-at-scale.md new file mode 100644 index 0000000..a402ea8 --- /dev/null +++ b/skills/programmatic-seo/references/refresh-at-scale.md @@ -0,0 +1,100 @@ +# Refresh at scale + +Data refresh cadence, template versioning, cohort migration, pruning lifecycle. + +pSEO sets decay if not maintained. Refresh discipline is built into the program at design time; retrofitting refresh on a 50,000-page set that was not designed for it costs more than building it from the start. + +--- + +## Data refresh cadence + +Match the refresh cadence to the data's volatility and the query's freshness reward. + +**Volatile fields.** Daily to weekly refresh. Real estate listings, current prices, current availability, recent reviews, current ratings. The data feed updates daily; the pages update daily; the search and AI surfaces see fresh data. + +**Slow-changing fields.** Quarterly refresh. Population statistics, business categories, attribute classifications, neighborhood demographics. The data updates seasonally or annually; the refresh cycle aligns. + +**Static fields.** No refresh required. Geographic coordinates, founding years, fixed attributes. Set at record creation; tracked in the schema's update-tag system. + +**Mixed-cadence pages.** Most pSEO pages are mixed: some volatile fields, some slow-changing, some static. The refresh pipeline updates each field on its own cadence; the page renders the latest data on each request (or rebuilds when fields change). + +**The "refresh cadence wasn't designed in" failure.** A program ships with annual refresh as the plan. Six months in, the volatile fields are stale (prices moved, listings expired). The fix is expensive: retrofit a daily pipeline for fields that should have had one from launch. + +--- + +## Template version migration + +When the template improves, all existing pages need migration. + +**Why templates ship revisions.** AEO patterns evolve, SERP intent shifts, schema requirements update, brand voice tightens. Templates from 18 months ago may need significant updates to compete in the current search and AI environment. + +**Cohort-by-cohort migration.** Migrate one cohort at a time, monitor, then migrate the next. The cohort might be a category, a generation period, a data-density tier. The cohort approach surfaces problems specific to particular page shapes before they spread across the entire set. + +**Big-bang migration.** Migrate all pages at once. Higher risk; if the new template has a regression, the entire set degrades simultaneously. Sometimes the right call when the migration is small or the team can roll back fast; usually the wrong call for large changes. + +**Migration monitoring.** Each cohort post-migration is monitored for 30 days minimum: ranking changes, citation count changes, click-through rate changes, engagement metric changes. Negative trends pause the migration and surface the regression before it propagates. + +**Rollback discipline.** The template migration ships with a rollback path. If a cohort's metrics degrade post-migration, the cohort rolls back to the previous template while the regression is investigated. Without rollback discipline, a bad migration produces permanent damage. + +--- + +## Cohort migration patterns + +Three common patterns. + +**Category-based cohort migration.** Migrate one parent category at a time. Real estate: migrate Denver pages first, monitor 30 days, then migrate Seattle. The advantage: category-level metrics are clean; investigation is scoped. + +**Generation-period cohort migration.** Migrate the oldest cohort first (pages generated in year 1), then the next, then the next. The advantage: oldest pages have the most accumulated decay; migrating them first improves the set's average quality fastest. + +**Data-density cohort migration.** Migrate the dense-data pages first (most fields populated), then the medium, then the sparse. The advantage: dense pages have the most upside from template improvements; sparse pages may need data backfill before template migration earns gains. + +The right pattern depends on the migration's intent. AEO-focused migrations often prefer dense-data first. Algorithm-update recovery migrations often prefer category-based. Maintenance migrations often prefer generation-period. + +--- + +## Pruning lifecycle + +Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. + +**The 24-month checkpoint.** Standard cutoff. A page that has been indexed for 24+ months and has earned zero impressions in Search Console is dead weight. Pruning options: noindex, 410, or 301 redirect to a more-relevant alternative. + +**Earlier pruning for some categories.** Time-sensitive pages (annual "best of [year]" pages, event-specific pages, deal-specific pages) prune earlier. A "best of 2024" page generated in 2024 should be archived or pruned by mid-2026; the freshness signal has decayed. + +**Later pruning for stable categories.** Some categories support evergreen pages that earn traffic for decades. Geographic pages (neighborhoods, cities), historical reference pages, foundational definitional pages. The 24-month checkpoint is too aggressive for these; review case-by-case. + +**Pruning is hygiene, not failure.** Pruning a page that did not earn traffic is not abandoning the program; it is removing dead weight that drags the set's quality signal down. The set is healthier with 40,000 traffic-earning pages than with the same 40,000 plus 60,000 dead pages. + +--- + +## Set-level refresh + +Occasionally the entire set's template needs a refresh. + +**Triggers for set-level refresh.** + +- AEO patterns shifted significantly (the entire set needs better above-the-fold answers, FAQPage schema, or source citations) +- The dataset's underlying source changed schema (the new data exposes fields the old template did not render) +- User expectations evolved (the category's accepted page shape shifted; the set's pages now read as dated) +- An algorithm update affected the set disproportionately (the set's design needs to adapt to the new ranking signals) + +**Set-level refresh is a 6-month project.** Plan accordingly. The work includes template redesign, cohort-by-cohort migration, post-migration monitoring, and pruning of pages that the new template cannot improve. Underestimating the duration is the most common mistake. + +**The "do not refresh and let the set decay" anti-pattern.** Some teams treat the initial pSEO build as ship-and-forget. The set ranks for 12 to 18 months, then declines as competitors with refreshed sets pass it. The decline accelerates when an algorithm update finds the set's accumulated drift. Refresh is part of the program's ongoing cost; teams that do not budget for it should not start the program. + +--- + +## Refresh budget + +The ongoing refresh cost in headcount. + +**Volatile-field refresh.** Mostly automated (data pipelines pull new data into the schema). 0.1 to 0.5 FTE for pipeline maintenance and exception handling. + +**Slow-changing-field refresh.** Quarterly cycles. 0.2 to 0.5 FTE during cycles; lower between cycles. + +**Template version migration.** Project-based when migrations ship. 1 to 3 FTE for the duration of the migration; varies by set size and migration scope. + +**Pruning lifecycle.** Quarterly review of dead pages. 0.1 to 0.3 FTE. + +**Total ongoing refresh budget.** A 10,000-page set: roughly 0.5 FTE steady state plus migration projects when they ship. A 100,000-page set: 1 to 2 FTE steady state plus larger migration projects. + +The refresh budget is in addition to the QC budget. Programs that under-budget either degrade; programs that budget both produce durable traffic for years. diff --git a/skills/programmatic-seo/references/schema-design-patterns.md b/skills/programmatic-seo/references/schema-design-patterns.md new file mode 100644 index 0000000..563400f --- /dev/null +++ b/skills/programmatic-seo/references/schema-design-patterns.md @@ -0,0 +1,114 @@ +# Schema design patterns + +Field count, computed fields, cross-record fields, update tags, schema-as-product. The data shape that drives the template. + +The schema design here is the methodology layer: what shape the data takes, what fields earn their keep, what derivations add depth. Specific framework type signatures, ORM bindings, and database column choices are stack-specific implementation that varies by team. + +--- + +## Field count signals depth + +5 fields per record is thin. 15 to 20 is competent. 30+ is deep. + +**Why field count matters.** Field count determines what the template can render at depth versus what falls back to filler. A record with 5 fields can produce a 200-word page; a record with 30 fields can produce a 1,500-word page that reads as substantive across multiple sections. + +**The "thin schema" failure mode.** Teams design with 5 to 10 fields, ship, find pages reading as thin, then try to bolt on additional fields after the fact. Bolt-on fields rarely populate consistently across the existing dataset; the result is a half-thin set with a thin tail and a thicker head. + +**The "too-many-fields" trap.** 50+ fields per record where most are sparsely populated. The schema looks deep on paper but most fields are empty for most records. The template either renders empty sections (looks broken) or hides them (back to thin pages). Better to design 25 fields with 90% population than 50 fields with 30% population. + +--- + +## Required vs optional fields + +Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. + +**Required field discipline.** Define a minimum field-count threshold below which a record does not get a public page. The threshold ships in the schema validation; pages that fail validation sit as drafts until their data populates. + +**Optional field handling.** Each optional field has a render rule: if populated, render this section; if empty, hide this section or substitute a computed default. The render rules are part of the template, not afterthoughts. + +**The discipline.** A page with 25 of 30 optional fields populated is fine. A page with 3 of 30 should not ship; it produces filler content that drags the entire set's quality signal down. + +--- + +## Computed fields + +Derived from source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +**Common computed-field patterns.** + +- **Aggregations.** "Average price per square foot" computed from listing data; "median rating" computed from review data. +- **Derived classifications.** "Price tier" computed from price percentiles; "freshness tier" computed from data age. +- **Comparisons.** "Price vs neighborhood average" computed from the record's price and the parent category's average; "rating vs category average." +- **Trends.** "Price trend over 12 months" computed from time-series source data; "review-volume trend" from review-date stamps. +- **Rankings.** "Top 10 percent by [field]" computed across the set; "ranked by [field] within [category]." + +**Why computed fields earn their keep.** Each computed field adds a section to the template without requiring more source-data collection. The pipeline does the work; the template renders the result. This is how 15-field source data produces 30-field rendered pages. + +--- + +## Cross-record fields + +Fields that reference OTHER records in the set. Enable internal linking and comparison without manual curation. + +**Common cross-record patterns.** + +- **Most similar records.** "5 most similar neighborhoods" computed by attribute distance. +- **Parent and child references.** "Parent category" and "list of child records" computed from the hierarchy. +- **Sibling-comparison aggregates.** "Average price across sibling neighborhoods" computed across the parent's children. +- **Recommended-related.** "Users who viewed X also viewed Y" computed from analytics data (when first-party analytics is available). + +**How they power linking.** The sibling-link slot in the template renders from the "most similar records" cross-record field. Without this field, sibling linking becomes manual curation at scale, which is infeasible. + +--- + +## Update frequency tags + +Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). + +**Tag categories.** + +- **Static.** Set at record creation; rarely changes (geographic coordinates, neighborhood name, founding year). +- **Slow-changing.** Updates quarterly to annually (population statistics, business categories, attribute classifications). +- **Volatile.** Updates daily to weekly (current price, current availability, current rating, recent reviews). +- **Real-time.** Updates within minutes (live availability, dynamic pricing). Only relevant when the underlying data feed supports it. + +**Why tagging matters.** Without tags, refresh becomes "audit everything every cycle," which does not scale. With tags, refresh becomes "refresh volatile fields daily, slow-changing fields quarterly, static fields never," which scales. + +--- + +## Schema-as-product principle + +The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. + +**Schema versioning.** Major schema changes (renaming required fields, restructuring nested objects, changing field types) bump a version. Minor changes (adding optional fields, adding computed fields) do not. All schema changes are reviewed; breaking changes require migration plans. + +**Schema documentation.** Every field has a description, a source (where the data comes from), an update tag, a population rate (what percentage of records have this field), and example values. Documentation lives alongside the schema; it is not a separate doc that drifts. + +**Schema review.** Before adding fields or changing field types, the schema change goes through review with stakeholders who depend on the schema (template authors, QC reviewers, analytics consumers). Schema changes affect downstream rendering; review catches breakage before it ships. + +**Schema testing.** Validation rules ship as automated tests. Required fields, type constraints, value-range constraints, cross-field consistency checks. The tests run on every record in the dataset on a cadence; failures surface in the QC queue. + +--- + +## When the schema is wrong + +The schema is wrong when: + +- Required-field threshold produces too few publishable pages (relax the threshold or fix the data pipeline) +- Required-field threshold produces too many shallow pages (raise the threshold; let thin records sit as drafts) +- Optional fields are sparsely populated, dragging the average page quality down (drop them and refocus on dense fields) +- Computed fields are not actually used by the template (cut them; reduce schema bloat) +- Cross-record fields produce poor sibling matches (revise the similarity algorithm; the sibling-link section is doing real work for users) +- Update tags are wrong (refresh cadence is missing or over-shooting; recalibrate) + +The schema is iterated, not designed once. The "schema-as-product" principle makes that iteration safe by enforcing review and migration discipline; without it, every schema change risks breaking the template. + +--- + +## Methodology-level choices that stay in the public skill + +Field-count thresholds, computed-field patterns, cross-record patterns, update-tag categories, the schema-as-product principle. + +## Implementation choices that stay internal + +The specific schema language (TypeScript type definitions, dbt YAML, Sanity schema config, Prisma schema, etc.). The specific ORM or query layer. The specific validation framework. The specific deployment pipeline for schema migrations. These vary by stack. diff --git a/skills/programmatic-seo/references/template-design-patterns.md b/skills/programmatic-seo/references/template-design-patterns.md new file mode 100644 index 0000000..e56000d --- /dev/null +++ b/skills/programmatic-seo/references/template-design-patterns.md @@ -0,0 +1,104 @@ +# Template design patterns + +Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. + +The template is the structure that data fills. Templates are designed at the methodology level here; specific framework implementations (rendering, slot composition, build-time generation versus on-demand rendering) are stack-specific and belong in internal team documentation. + +--- + +## Above-the-fold answer + +The first 200 words of the rendered page answer the user's specific query. + +**Why.** Search engines and AI engines both extract the top of the page disproportionately. Featured snippets pull from the first answer-shaped paragraph. AI engines extract the first 200 words as the canonical citation. The reader who lands on the page from a SERP decides within 5 seconds whether to stay; the answer needs to be visible. + +**The pattern.** Lead with the structured answer to the specific query: the price, the rating, the count, the comparison, the location, the recommendation. Follow with supporting details that justify or expand the answer. The opening is not a marketing introduction; it is the answer paragraph. + +**Anti-pattern.** "Welcome to our [page type] page. Below you will find information about [topic]." This intro reads as filler to crawlers and humans. Cut it; lead with the answer. + +--- + +## Variable density + +The template accommodates records with sparse fields and dense records gracefully. + +**Sparse-record handling.** Some records will have fewer fields populated. The template needs fallback patterns: hide sections that depend on missing fields, substitute computed defaults, surface "limited data available" rather than rendering empty headings. + +**Dense-record handling.** Some records will have many fields. The template needs progressive disclosure: collapse less-essential sections behind expandable headings, paginate long lists, prioritize the most-queried fields above the fold. + +**The shape principle.** Two pages from the same template can differ significantly in length and depth based on data density without either looking broken. A page with 20% of optional fields populated should still feel competent; a page with 95% should not feel overstuffed. + +--- + +## Heading hierarchy reflects data + +H2s and H3s map to data sections, not to template decoration. + +**The pattern.** The H2 set is the same across all pages in the template, but the content under each H2 reflects each page's specific data. "Overview," "Details," "Comparisons," "Related" might be the H2 set; what populates each varies per page. + +**Snippet-bait paragraphs at H2 level.** Each H2 has a 40 to 60 word answer paragraph immediately following it that summarizes that section's specific content. AI engines often quote these as multi-paragraph citations. + +**Anti-pattern.** Every page has a different H2 set because the template branches on data. The inconsistency confuses crawlers; the heading structure should be predictable across the set. + +--- + +## Schema markup as part of template + +Structured data renders machine-readable signals at scale. + +**The principle.** Pick the schema type that matches the page's content (Product, Article, LocalBusiness, FAQPage, BreadcrumbList, etc.). Embed the schema in the template; populate from the same data that renders the visible page. The schema is generated, not hand-written; the template ensures every page has it. + +**Validation discipline.** Run schema validation as an automated check on every generated page. Schema errors produce silent failures in search and AI surfaces; the validation catches them before publish. + +**Schema field coverage.** Populate every relevant schema field, not just the required ones. Optional schema fields (aggregateRating, additionalProperty, areaServed, etc.) signal depth at scale even when individual fields are not visibly rendered. + +--- + +## Internal linking placeholders + +The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. + +**Standard slot patterns.** + +- **Breadcrumb slot.** Path from home to current record. 3 to 4 levels typical. +- **Parent-category slot.** Link up to the hub page for the record's category. +- **Sibling slot.** 5 to 15 related sibling records. Computed from cross-record fields in the schema. +- **Related-record slot.** 3 to 5 records related across categories (different parent, similar attributes). +- **Related-content slot.** Editorial content related to the record (blog posts, guides, comparison editorials). + +**Total internal links per page.** 15 to 30 typical for a well-linked pSEO page. Below 10, the page is under-linked; above 50, the page reads as link-dense and dilutes anchor signal. + +--- + +## Distinctive value per page + +Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. + +**The test.** Generate three sample pages from the template using different records. Read all three. Can you tell them apart on substance, not just on the names? If the pages are interchangeable in everything but identifiers, the template is not generating distinct value. + +**The fix.** Surface the distinctive fields prominently. The fields that vary most across the set are the ones that justify the page's existence; those should be in the above-the-fold answer and in the H2 structure, not buried as "additional details." + +--- + +## Quality bar: the random-sample test + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. + +**The test sequence.** + +1. Pick 5 random records from the dataset. +2. Render them through the template. +3. Read each page as if you arrived from a search results page. +4. Score each page on three dimensions: does it answer the query, is the depth competitive with editorial content for the same query, would you trust this page as a source. + +If any of the 5 fails, the template needs work before scaling. The 5-page sample is the minimum viable QC; the cohort tracking discipline scales it across the program's lifetime. + +--- + +## Methodology-level design choices that stay in the public skill + +The principles above. Field-count heuristics, slot patterns, hierarchy choices, validation discipline, sample-test discipline. + +## Implementation choices that stay internal + +The framework rendering choice (build-time generation, server rendering, hybrid), the specific component composition pattern, the specific data-fetching layer, the deployment topology, the cache-invalidation strategy. These vary by stack and team and should not be prescribed at the methodology level. diff --git a/skills/programmatic-seo/references/when-pseo-works-decision.md b/skills/programmatic-seo/references/when-pseo-works-decision.md new file mode 100644 index 0000000..269fb79 --- /dev/null +++ b/skills/programmatic-seo/references/when-pseo-works-decision.md @@ -0,0 +1,107 @@ +# When pSEO works decision + +The five-criterion framework for deciding whether programmatic SEO is the right answer, with worked examples across business types. + +The default answer is no. Most teams asking "should we do pSEO?" should hear "probably not." pSEO works only when all five criteria are met; failing any one is a hard signal to pursue editorial content or paid acquisition instead. + +--- + +## The five criteria + +### 1. Real underlying data + +A genuine structured data source with depth. 10+ fields per record, ideally 20+. First-party data, licensed datasets, expert-curated content, or synthesized multi-source data. Not scraped Wikipedia plus AI rewrite. + +**The test.** Could a competent reader extract genuine value from a single page in the set without reading any other page? If yes, the data is real. If no, the page is filler dressed as pSEO. + +### 2. Long-tail query volume justifies the effort + +The queries the program targets have meaningful aggregate volume. Individual queries can be small (10 to 100 monthly searches each) as long as the aggregate across the set is large. + +**The test.** Pull the top 20 candidate queries from keyword research. Sum their volumes. If the aggregate is below 5,000 monthly searches, pSEO probably does not justify the build. If above 50,000, the volume case is strong. + +**The illusion to watch for.** Long-tail keywords that look reasonable in keyword tools but are not actually searched by humans. Permutation keywords (every adjective times every noun) often have keyword-tool volume because the tools generate the data; the queries themselves are dead. + +### 3. User intent is queryable + +The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +**Queryable intent examples.** "Homes for sale in [neighborhood]" answered by listing data. "Software engineer salary at [company]" answered by salary data. "Restaurants near [landmark]" answered by location and rating data. + +**Non-queryable intent examples.** "Should I buy a house in [neighborhood]" requires personal financial judgment. "Why is Y better than X" requires editorial argumentation. "How do I choose [thing]" requires guidance. + +If the intent requires narrative, choose editorial. If the intent requires data presented well, choose pSEO. + +### 4. Update cadence aligns with query volatility + +Real estate listings update daily; the data feed updates daily; pSEO refresh aligns with the volatility. "Best [thing] for [year]" pages get stale annually; the refresh cadence is annual. + +**The test.** Match the data's update frequency to the query's volatility. If the data is static (geographic features, founding dates) and the queries are stable, low maintenance. If the data shifts daily and the queries reward freshness, daily refresh. + +**The trap.** Underestimating refresh effort at design time. A team designs for "annual refresh" because that feels reasonable, ships 50,000 pages, and discovers the refresh requires 2 FTE for 6 weeks every year. The cadence was real; the resourcing was not. + +### 5. Quality control is operationally feasible + +Headcount is budgeted to sample-audit the set, fix failures, and maintain quality. Not aspirationally; in actual hours allocated. + +**The rule of thumb.** A 10,000-page set requires roughly 0.5 to 1.0 FTE of ongoing quality control. A 100,000-page set requires 2 to 4 FTE. If the budget cannot absorb the QC headcount, the program will degrade within 12 months of launch. + +--- + +## Worked examples + +### Example 1: real estate listings (yes) + +A regional brokerage considering pSEO for "homes for sale in [neighborhood]" pages. + +- Real underlying data: yes. MLS feeds with 30+ fields per listing. +- Long-tail volume: yes. Each neighborhood query has 50 to 500 monthly searches; aggregate across 200 neighborhoods is significant. +- Queryable intent: yes. Buyers want listings. +- Update cadence: data updates hourly; pSEO refresh aligns daily; manageable. +- QC feasible: yes; the brokerage already has data ops headcount. + +Decision: yes. This is the canonical pSEO use case. + +### Example 2: SaaS comparison pages (maybe) + +A B2B SaaS considering "X vs Y" pages for every competitor combination. + +- Real underlying data: judgment call. If the comparison data is licensed (G2 reviews, feature databases) or first-party (the team's actual evaluation), yes. If the data is "scraped competitor websites plus AI summary," no. +- Long-tail volume: yes for major competitors; thin for niche ones. +- Queryable intent: yes for "X vs Y," but readers often want narrative judgment ("which is better for my use case") that data alone cannot supply. +- Update cadence: feature databases drift; quarterly refresh required. +- QC feasible: depends on team size. + +Decision: maybe, leaning yes if the team commits to combining structured comparison data with brief editorial analysis per page. Pure-data comparison pages tend to underperform pages that include the analytical layer. + +### Example 3: AI-generated city guides (no) + +A travel content site considering "things to do in [city]" pSEO across 5,000 cities. + +- Real underlying data: no. The plan is "AI-generate the content from public sources." Anyone can replicate. +- Long-tail volume: yes for major cities; thin for small ones. +- Queryable intent: yes, but the queries reward editorial depth (curation, recommendations, taste). +- Update cadence: events change weekly; the AI-generated approach cannot match. +- QC feasible: no; "AI-generate 5,000 pages" is the plan because QC was not budgeted. + +Decision: no. This is the pattern that produces penalty-bait. Either invest in real expert-curated data or pursue editorial content for the highest-volume cities only. + +### Example 4: enterprise B2B pricing pages (no) + +An enterprise B2B SaaS considering "pricing for [industry] companies" pSEO across 50 industries. + +- Real underlying data: no. Pricing for enterprise SaaS is typically negotiated; there is no structured data feed to render. +- Long-tail volume: yes for some industries. +- Queryable intent: no. Buyers want a sales conversation, not a price table. +- Update cadence: not relevant. +- QC feasible: not relevant. + +Decision: no. The intent is not queryable. Editorial content explaining the buying process plus a sales-led conversion path is the right approach, not pSEO. + +--- + +## When two of five criteria fail, walk away + +If two or more criteria fail, walk away from the pSEO idea. The temptation is to start anyway and "improve as you go," but pSEO programs that launch with weak foundations rarely recover. The data depth, the QC budget, and the refresh cadence are designed in or they are missing forever. + +If exactly one criterion fails, see whether a smaller scope resolves the failure. "5,000 pages across all cities" failing on data depth might become "500 pages across major cities with expert-curated depth" that succeeds on all five criteria. diff --git a/skills/qa-testing/SKILL.md b/skills/qa-testing/SKILL.md new file mode 100644 index 0000000..22a57a5 --- /dev/null +++ b/skills/qa-testing/SKILL.md @@ -0,0 +1,294 @@ +--- +name: qa-testing +description: "Run QA testing on a page, feature, or full site at one of three depth tiers (smoke, standard, full). Use this skill whenever the user asks to test a page, audit a site, check for bugs, verify a deploy, run a QA sweep, or review accessibility, performance, or SEO basics. Triggers on test, QA, audit, verify, check, is it working, does it look right, broken, 404, image not loading, post-deploy check, regression test. Also triggers proactively after any significant code change or new page launch where verification matters." +category: qa +catalog_summary: "Pre-launch QA, regression testing, cross-browser checks" +display_order: 1 +--- + +# QA Testing + +Verify that a page, feature, or site is working before declaring it shipped. Stack-agnostic. Console-snippet driven for speed. + +This skill is faster than `accessibility-audit` (which goes deeper on WCAG) and `performance-optimization` (which goes deeper on Core Web Vitals). Use this skill for general QA. Use the specialists for deep audits. + +--- + +## When to use + +- After every deploy (smoke test) +- After launching a new page or feature (standard audit) +- Before a major release (full release matrix) +- Investigating a "something looks off" report +- Pre-launch verification of a site or section + +## When NOT to use + +- Deep accessibility compliance work (use `accessibility-audit`) +- Deep performance investigation (use `performance-optimization`) +- Code review or debugging (use `code-review-web`) +- Initial site setup or technical SEO baseline (use `seo-technical`) + +--- + +## Required inputs + +- The page URL or site under test +- The tier of QA needed (smoke, standard, or full) +- Browser dev tools access +- Any specific concerns to check beyond the standard tier + +--- + +## The framework: 3 tiers + +QA scales with the stakes. Pick the tier that matches the context. + +| Tier | When to run | Time | Coverage | +|---|---|---|---| +| Smoke | After every deploy | 2 minutes | Critical signals only | +| Standard | New page or feature | 10 minutes | On-page basics, accessibility, structure | +| Full | Major release, pre-launch | 30+ minutes | Comprehensive across all dimensions | + +### Tier 1: Smoke test + +The 2-minute "did the deploy break anything obvious?" check. Run after every deploy. + +Console snippet (paste in browser dev tools): + +```javascript +const smoke = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + h1Count: document.querySelectorAll('h1').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { try { return JSON.parse(s.innerText)['@type'] } catch(e) { return 'invalid' } }), + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete || i.naturalWidth === 0).length, +}; +console.log(JSON.stringify(smoke, null, 2)); +``` + +**Pass criteria:** +- Title exists and is 30 to 60 characters +- Canonical points at the production domain (never staging or preview URLs) +- Exactly one H1 +- Zero missing alts +- Zero broken images +- Schema includes the expected types for the page + +If any of these fail, do not proceed with deeper testing until the smoke issue is fixed. + +### Tier 2: Standard page audit + +The 10-minute new-page-or-feature audit. Covers the on-page basics plus accessibility and structure. + +Console snippet: + +```javascript +const audit = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + metaDesc: document.querySelector('meta[name="description"]')?.content, + metaDescLen: document.querySelector('meta[name="description"]')?.content?.length, + ogImage: document.querySelector('meta[property="og:image"]')?.content, + ogTitle: document.querySelector('meta[property="og:title"]')?.content, + twitterCard: document.querySelector('meta[name="twitter:card"]')?.content, + h1Count: document.querySelectorAll('h1').length, + h1Text: document.querySelector('h1')?.innerText, + h2Count: document.querySelectorAll('h2').length, + h2s: [...document.querySelectorAll('h2')].map(h => h.innerText.trim().slice(0, 60)), + totalImages: document.querySelectorAll('img').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete || i.naturalWidth === 0).length, + externalLinksWithoutNoopener: [...document.querySelectorAll('a[target="_blank"]')] + .filter(a => !a.rel?.includes('noopener')).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { + try { + const d = JSON.parse(s.innerText); + return d['@graph'] ? d['@graph'].map(x => x['@type']) : d['@type']; + } catch(e) { return 'invalid' } + }), + hasSkipLink: !!document.querySelector('a[href^="#"]:first-of-type'), + pageLanguage: document.documentElement.lang || 'NOT SET', + hasFavicon: !!document.querySelector('link[rel*="icon"]'), +}; +console.log(JSON.stringify(audit, null, 2)); +``` + +**Pass criteria** (in addition to smoke): +- Meta description: 120 to 160 characters +- og:image, og:title, twitter:card present +- H2s present and descriptive +- All external links with `target="_blank"` have `rel="noopener"` +- Page language declared (`lang` attribute on `<html>`) +- Favicon present + +### Tier 3: Full release matrix + +The 30-minute pre-launch check. Cover all dimensions. + +| Dimension | Pass criteria | +|---|---| +| Smoke and standard | All pass | +| Accessibility (basic) | Run browser audit tool (e.g., Lighthouse), score above 90 | +| Performance (basic) | Lighthouse Performance score above 80, LCP under 2.5s, CLS under 0.1 | +| Mobile responsiveness | Tested at 375px, 768px, 1024px, 1440px | +| Cross-browser | Tested in Chrome, Safari, Firefox (and Edge if relevant audience) | +| Forms | All forms submit successfully and validate correctly | +| Internal links | No broken internal links (sample 20 random) | +| External links | All return 200 (sample 10) | +| Sitemap | Returns 200, lists canonical URLs only | +| robots.txt | Allows production crawlers, blocks staging if applicable | +| Security headers | HSTS, X-Frame-Options, X-Content-Type-Options present | +| HTTPS | All resources load over HTTPS, no mixed content | +| 404 handling | 404 pages return HTTP 404 (not soft 200) | +| Schema validation | All schema validates in Rich Results Test | +| Analytics | Events fire as expected on key user actions | +| Cache behavior | Cache headers appropriate for page type | + +For headers, run: + +```javascript +fetch(window.location.origin, { method: 'HEAD' }) + .then(r => { + const headers = {}; + for (const [k, v] of r.headers.entries()) headers[k] = v; + console.log(JSON.stringify(headers, null, 2)); + }); +``` + +Look for: `strict-transport-security`, `x-frame-options`, `x-content-type-options`. + +--- + +## Specific QA snippets + +### Image audit + +```javascript +const imgs = [...document.querySelectorAll('img')].map(i => ({ + src: i.src.split('/').pop().split('?')[0].slice(0, 60), + alt: i.alt || 'MISSING', + width: i.naturalWidth, + height: i.naturalHeight, + loaded: i.complete && i.naturalWidth > 0, +})); +console.table(imgs); +console.log({ + total: imgs.length, + broken: imgs.filter(i => !i.loaded).length, + noAlt: imgs.filter(i => i.alt === 'MISSING').length, +}); +``` + +### Heading hierarchy check + +```javascript +const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')].map(h => ({ + level: parseInt(h.tagName[1]), + text: h.innerText.trim().slice(0, 80), +})); +console.table(headings); + +// Check for skipped levels +const levels = headings.map(h => h.level); +let skipped = false; +for (let i = 1; i < levels.length; i++) { + if (levels[i] > levels[i-1] + 1) { + console.warn(`Skipped from H${levels[i-1]} to H${levels[i]}: "${headings[i].text}"`); + skipped = true; + } +} +if (!skipped) console.log('No skipped heading levels'); +``` + +### Contrast spot-check + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + const r = ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2); + return r + ':1 ' + (parseFloat(r) >= 4.5 ? 'PASS body' : parseFloat(r) >= 3 ? 'PASS large only' : 'FAIL'); +} + +// Examples +contrast('#FFFFFF', '#4B5563'); // body color check +contrast('#FFFFFF', '#9CA3AF'); // verify gray choices +``` + +### Form audit (per form) + +```javascript +[...document.querySelectorAll('form')].forEach((form, i) => { + const fields = [...form.querySelectorAll('input, select, textarea')].map(field => ({ + type: field.type || field.tagName.toLowerCase(), + name: field.name, + hasLabel: !!form.querySelector(`label[for="${field.id}"]`) || !!field.closest('label'), + required: field.required, + })); + console.log(`Form ${i + 1}:`); + console.table(fields); +}); +``` + +### External link audit + +```javascript +const externalLinks = [...document.querySelectorAll('a[href^="http"]')] + .filter(a => !a.href.includes(window.location.host)); +const issues = externalLinks.filter(a => + a.target === '_blank' && (!a.rel?.includes('noopener') || !a.rel?.includes('noreferrer')) +); +if (issues.length) { + console.warn(`${issues.length} external links missing noopener/noreferrer:`); + issues.forEach(a => console.warn(a.href)); +} else { + console.log(`All ${externalLinks.length} external links properly attributed`); +} +``` + +--- + +## Workflow + +1. **Pick the tier.** Smoke for routine deploys. Standard for new work. Full for releases. +2. **Run the snippet.** Paste the appropriate console snippet, review output. +3. **Note failures.** Each failure either gets fixed before ship or filed as a known issue. +4. **For Standard tier**, add: visual review at 375px, 768px, 1440px. Test the primary user flow. +5. **For Full tier**, add: cross-browser testing, Lighthouse audit, schema validation, security headers, 404 handling. +6. **Document.** Use the template in [`references/qa-report-template.md`](references/qa-report-template.md) for full audits. + +--- + +## Failure patterns + +- **Skipping smoke tests on "small" deploys.** Half of broken-production incidents start with a deploy that "looked safe." +- **Running snippets but not reading the output.** The console snippet is a tool. The judgment is reading what it returns. +- **Visual-only QA.** Eyeballing a page misses missing alt text, broken schema, missing canonical. Always run the snippet. +- **Single-browser testing.** Mobile Safari and Chrome differ enough to surprise you. Test at least Chrome and Safari. +- **No mobile QA.** The 375px viewport is where most users live. Test there or get burned later. +- **Pass-fail with no remediation.** A failed QA must produce a fix or a known-issue ticket. Failed QA that ships unfixed is process theater. + +--- + +## Output format + +For smoke tests: console output is the report. + +For standard and full audits: a markdown report at `qa-report-[date].md`. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md). + +--- + +## Reference files + +- [`references/qa-report-template.md`](references/qa-report-template.md) - Markdown report template for standard and full audits. diff --git a/skills/qa-testing/references/qa-report-template.md b/skills/qa-testing/references/qa-report-template.md new file mode 100644 index 0000000..91b7bdd --- /dev/null +++ b/skills/qa-testing/references/qa-report-template.md @@ -0,0 +1,200 @@ +# QA Report: [Page or Site URL] + +**Date:** [YYYY-MM-DD] +**Tier:** [Smoke / Standard / Full] +**Tester:** [Name] +**Browser(s):** [List] +**Device(s):** [Desktop, mobile device, viewport width] + +--- + +## Summary + +**Overall:** [Pass / Pass with minor issues / Fail] + +[1 to 3 sentences. The headline finding. What works, what's broken, what to do.] + +**Critical issues found:** [N] +**Important issues found:** [N] +**Minor issues found:** [N] + +--- + +## Smoke check + +| Check | Pass | Notes | +|---|---|---| +| Title tag present and 30-60 chars | ☐ | | +| Canonical = production URL | ☐ | | +| Exactly one H1 | ☐ | | +| Zero missing image alts | ☐ | | +| Zero broken images | ☐ | | +| Schema present and valid | ☐ | | + +--- + +## Standard audit (if applicable) + +### Meta tags +| Field | Value | Pass | +|---|---|---| +| Title | | ☐ | +| Title length | | ☐ | +| Meta description | | ☐ | +| Meta description length | | ☐ | +| og:image | | ☐ | +| og:title | | ☐ | +| twitter:card | | ☐ | + +### Structure +| Check | Result | Pass | +|---|---|---| +| H1 text | | ☐ | +| H2 count | | ☐ | +| Skipped heading levels | | ☐ | +| Page language declared | | ☐ | +| Favicon present | | ☐ | + +### Images +| Check | Count | +|---|---| +| Total images | | +| Broken images | | +| Missing alt text | | + +### Links +| Check | Count | +|---|---| +| External links | | +| External missing `noopener` | | + +### Schema +[List schema types found and any validation issues] + +--- + +## Full release matrix (if applicable) + +### Accessibility +- [ ] Lighthouse Accessibility score above 90 (actual: __) +- [ ] No skipped heading levels +- [ ] All form fields have labels +- [ ] Skip link present +- [ ] Page operable by keyboard alone +- [ ] Focus indicators visible + +### Performance +- [ ] Lighthouse Performance score above 80 (actual: __) +- [ ] LCP under 2.5s (actual: __) +- [ ] CLS under 0.1 (actual: __) +- [ ] INP under 200ms (actual: __) + +### Mobile responsiveness +- [ ] 375px viewport: layout intact, no horizontal scroll +- [ ] 768px viewport: layout adapts cleanly +- [ ] 1024px viewport: desktop variant works +- [ ] 1440px viewport: max-width holds, no awkward stretch +- [ ] Tap targets minimum 44px + +### Cross-browser +- [ ] Chrome: tested +- [ ] Safari: tested +- [ ] Firefox: tested +- [ ] Edge: tested (if relevant audience) +- [ ] Mobile Safari: tested +- [ ] Mobile Chrome: tested + +### Forms +- [ ] All forms submit successfully +- [ ] Validation works as expected +- [ ] Error states display clearly +- [ ] Success states display clearly + +### Links +- [ ] No broken internal links (sample of 20 tested) +- [ ] No broken external links (sample of 10 tested) + +### Site infrastructure +- [ ] Sitemap returns 200 and lists canonical URLs +- [ ] robots.txt correct (allows production, blocks staging) +- [ ] HTTPS on all resources, no mixed content +- [ ] HSTS header present +- [ ] X-Frame-Options header present +- [ ] X-Content-Type-Options header present + +### 404 handling +- [ ] 404 pages return HTTP 404 (not 200) +- [ ] 404 page provides helpful navigation + +### Schema +- [ ] All schema validates in Rich Results Test +- [ ] Required properties filled +- [ ] No mixed signals (canonical vs sitemap vs internal links) + +### Analytics +- [ ] Page view fires correctly +- [ ] Key events fire on user actions +- [ ] No PII in event parameters + +### Cache behavior +- [ ] Cache headers appropriate for page type +- [ ] No stale content displayed +- [ ] Cache invalidation works after content updates + +--- + +## Critical issues + +[Things that block ship.] + +### 1. [Issue title] +- **Where:** [URL or component] +- **What:** [What's broken] +- **Impact:** [Who is affected] +- **Fix:** [Specific remediation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Things that should be fixed but might not block ship.] + +### 1. [Issue title] +- **Where:** +- **What:** +- **Impact:** +- **Fix:** + +--- + +## Minor issues + +[Polish items.] + +- [Issue] +- [Issue] +- [Issue] + +--- + +## Recommendations + +[Suggestions beyond fixing the identified issues.] + +- [Recommendation] +- [Recommendation] + +--- + +## Sign-off + +- [ ] All critical issues resolved +- [ ] Important issues resolved or have known-issue tickets +- [ ] Minor issues acknowledged + +**Approved for ship:** [Yes / No / Conditional] +**Approved by:** [Name] +**Date:** [YYYY-MM-DD] diff --git a/skills/quiz-and-assessment-design/SKILL.md b/skills/quiz-and-assessment-design/SKILL.md new file mode 100644 index 0000000..d364cea --- /dev/null +++ b/skills/quiz-and-assessment-design/SKILL.md @@ -0,0 +1,283 @@ +--- +name: quiz-and-assessment-design +description: "Designing quizzes, personality assessments, and recommendation tools that segment users into actionable categories rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping, lead capture integration. Honest about clickbait-quiz (engagement only), vanity-result (entertaining, not useful), and actionable-segmentation (genuine categorization that drives next-step recommendations) patterns. Triggers on quiz, assessment, personality test, recommendation tool, scorecard, diagnostic, fit evaluator, what-type-of-X-are-you, persona quiz. Also triggers when an audience needs a categorization-driven lead magnet, when a vanity quiz is producing engagement but no qualified leads, or when an assessment is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing quizzes and assessments that produce actionable segmentation. Distinguishes clickbait-quiz (engagement only) from vanity-result (entertaining, not useful) from actionable-segmentation (genuine categorization that drives next-step recommendations)" +display_order: 3 +--- + +# Quiz and Assessment Design + +A senior growth practitioner's playbook for designing quizzes and assessments that produce actionable segmentation rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping. The discipline of building a quiz the audience actually uses to make a decision. + +Most quizzes on the web are clickbait. "What kind of pizza are you?" energy applied to brand-building, with results that flatter the taker but drive no specific next step. The quiz captures emails because the format implies fun; the leads are unqualified because the result told them nothing they could act on. + +The quizzes that work as compounding assets do something different. They categorize the taker into a defined segment with a specific recommendation matched to that segment. The taker comes away knowing what to do next, not just what they are. The brand becomes the source of the recommendation the audience acted on. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the quiz-specific methodology (scoring algorithms, result categorization, recommendation matching) lives here. + +The voice is the senior growth practitioner who has watched quizzes earn long-term subscribers and watched them produce engagement metrics with no downstream impact. Practical, opinionated about the difference between fun-quiz and decision-quiz, willing to call out when a quiz is the wrong format for the goal. + +When to use this skill: scoping a quiz or assessment for the first time, auditing a quiz that produces engagement but no qualified leads, designing the result categories that drive specific recommendations, or deciding which inputs warrant the lead-capture step. + +--- + +## What this skill covers + +This skill spans quiz and assessment design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology. Quizzes are one specific lead-magnet type. +- `calculator-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- **`quiz-and-assessment-design` (this skill)** is quiz-specific methodology (question architecture, scoring algorithms, result categorization, recommendation matching). +- `discovery-research-synthesis` is customer-research synthesis (this skill is user-facing assessment, not internal research). +- `landing-page-copy` is the quiz landing page (downstream of quiz design). + +The audience: growth marketers, product marketers, content marketers, agencies running quiz-based growth tooling for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); calculator design (covered by `calculator-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the quiz (handed off via `pm-spec-writing`). + +--- + +## The quiz/assessment decision: when this format earns investment + +Before designing the quiz, decide whether a quiz is the right tool for the audience and the goal. + +**Quizzes earn investment when:** + +- The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. +- The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation; 30 questions stops being a quiz and becomes a survey. +- The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation does not justify the format; the segment-recommendation mapping is the value. +- The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage; audiences who do not (technical buyers, enterprise) often see quizzes as gimmicks. + +**Quizzes do NOT earn investment when:** + +- The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. +- The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. +- The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. +- The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional; the format choice has to fit the audience. + +The decision is not "should we have a quiz"; it is "is the quiz the right next investment for this specific audience and decision." + +Detail in [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md). + +--- + +## Clickbait-quiz vs vanity-result vs actionable-segmentation + +The keystone framing. + +**Clickbait-quiz.** "What kind of pizza are you?" energy. Generates engagement (shares, comments, brief virality), segments nothing useful. Fun but not strategic. Cost: the engagement metric looks fine; the leads have no qualification signal because the quiz did not reveal anything actionable about them. + +**Vanity-result.** Elaborate-feeling result that flatters the taker but does not drive any specific next step. "You are an INTJ visionary entrepreneur" with a description that reads like horoscope, no actionable follow-up. Cost: the taker enjoyed the result, did not act on it, did not return. The quiz produced a moment of attention, not a relationship. + +**Actionable-segmentation.** Result places the taker into a defined category with a specific recommendation matched to that category. The result tells them what to DO next, not just what they ARE. The category and the recommendation are the value; the taker comes away with a next step. + +The litmus test. After taking the quiz, can a stranger in the target audience name the next thing they should do? Can they describe the recommendation matched to their result? If yes, the quiz is actionable-segmentation. If they got a flattering description with no clear next step, the quiz is vanity-result. If they got entertainment with no segmentation, the quiz is clickbait. + +--- + +## Question architecture + +The questions are the mechanism that produces the segmentation. Bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +**Question count.** Most effective quizzes use 5-10 questions. Fewer than 5 rarely produces meaningful segmentation; more than 12 stops feeling like a quiz and starts feeling like an interrogation. + +**Question types.** + +- **Multiple-choice (single-select).** The most common. Each option maps to a segment or scoring weight. +- **Multiple-select.** Useful when multiple attributes apply. Care needed; multi-select complicates scoring. +- **Slider or scale.** "On a scale of 1-5, how often do you..." Useful for intensity questions; less useful for categorical segmentation. +- **Yes/no.** Useful for binary qualifying questions; rarely produces nuanced segmentation alone. +- **Free text.** Avoid in quizzes. Free text breaks the scoring flow and adds friction. + +**Question ordering.** Start with engaging, low-friction questions. Save more revealing or sensitive questions for later when commitment has built. Demographic or qualifying questions belong at the end, not the start. + +**Question phrasing.** + +- Plain language. Avoid jargon. +- Specific situations the audience recognizes. +- Avoid leading questions ("How much do you struggle with X" presumes struggle). +- Avoid double-barreled questions ("How much do you value speed AND simplicity" mixes two dimensions). + +**Question-segment mapping.** Each question should contribute to the segmentation in a defined way. Questions that do not affect the result are filler; remove them. + +Detail in [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md). + +--- + +## Scoring algorithms + +The math that turns answers into a segment. + +**Pattern A: Direct mapping.** Each answer corresponds directly to a segment. The dominant answer choice determines the result. Simple, transparent, easy to explain. + +**Pattern B: Weighted scoring.** Each answer adds points to one or more segments. The highest-scoring segment wins. Allows for nuance; one answer can contribute to multiple segments. + +**Pattern C: Multi-dimensional.** The quiz produces scores across multiple axes (e.g., introvert/extrovert AND analytical/intuitive). The result combines the scores into a 2D or 3D segment. Common in personality assessments. + +**Pattern D: Branching logic.** The next question depends on the previous answer. Allows for adaptive questioning; complicates scoring. + +**Choice criteria.** + +- Direct mapping when the segments are well-defined and the questions clearly distinguish them. +- Weighted scoring when nuance matters and most answers contribute to multiple segments. +- Multi-dimensional when the segmentation is genuinely multi-axis (personality, fit-evaluation). +- Branching when later questions make sense only in the context of earlier answers. + +**Scoring transparency.** Some quizzes show the score during or after the quiz; others present only the segment. The choice depends on whether the score is meaningful to the user. Personality assessments benefit from showing dimensions; recommendation quizzes often do not. + +Detail in [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md). + +--- + +## Result categorization + +How many segments, named how, distinguishable from each other. + +**Segment count.** Most quizzes work well with 4-8 result categories. Fewer than 4 makes the categorization feel coarse; more than 8 makes individual segments feel under-developed. + +**Segment naming.** + +- Memorable. The taker should be able to describe their segment to a friend. +- Specific. "The Strategic Planner" beats "Type 3." +- Honest. Names should not flatter universally; some segments are more flattering than others, which is honest segmentation. +- Brand-voice consistent. The names should sound like the brand the quiz represents. + +**Segment distinguishability.** Each segment should be meaningfully different. If two segments have similar descriptions and similar recommendations, the segmentation is fake. + +**Segment balance.** The quiz should not always route 80 percent of takers to one segment. Balanced segmentation (each segment receives a meaningful share of takers) signals that the questions actually distinguish. + +Detail in [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md). + +--- + +## Result-to-recommendation mapping + +The action attached to each category. This is where the quiz earns its conversion. + +**The principle.** Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +**Mapping examples.** + +- B2B SaaS quiz: "Which CRM tier fits your team" maps each segment to a recommended plan. +- Content quiz: "What kind of marketer are you" maps each segment to a different content series matched to that maturity level. +- Onboarding quiz: "What is your readiness for X" maps each segment to a different onboarding path or resource. + +**The recommendation has to be real.** The brand should actually offer the recommended next step; the recommendation should match the segment specifically; the recommendation should be valuable to the segment. + +**Mapping discipline.** + +- Each segment has a distinct recommendation. No two segments share the same next step. +- Each recommendation is actionable. The taker can act on it without additional research. +- Each recommendation is valuable to that specific segment. Generic recommendations for one segment do not earn the segmentation. +- The recommendation is delivered in context of the result. Not buried 3 emails later. + +**The vanity-result failure.** Result describes the segment without a recommendation. "You are a Strategic Planner" with a description but no next step. The taker enjoys the segment, does nothing. + +**The actionable-segmentation win.** Result describes the segment, then says: "Strategic Planners benefit most from [specific resource or product or path]. Here is the next step." The taker has a specific action. + +Detail in [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md). + +--- + +## Lead capture integration + +When and where to ask for the email, with what value-add. + +**The principle.** Capture the email in exchange for the personalized result delivery, not in exchange for seeing the result at all. + +**Pattern A: Email after questions, before result.** "Enter your email to see your personalized result." Common; works when the perceived value of the result is high. Risk: lead-trap pattern if the result was already calculated and is being held hostage. + +**Pattern B: Email after result, for personalized delivery.** "See your result here. Want a PDF with personalized recommendations matched to your segment? Enter your email." Honest; the result is free, the additional value justifies the email. + +**Pattern C: Email integrated with optional features.** "See your result. Save this scenario, get notified when new content for your segment is available, or download a personalized resource." Gradual opt-in; less aggressive. + +**The value-add at lead capture.** What the user gets for their email matters. A personalized PDF report, a follow-up email series matched to their segment, a curated resource list specific to their result. Generic delivery (just sending the same result by email) does not justify the gate. + +**Conversion vs lead quality.** Pattern A converts higher; Pattern B and C produce higher lead quality. Pattern choice depends on what the program optimizes for. + +Detail in [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md). + +--- + +## Quiz anti-patterns + +Patterns that look like quizzes but degrade trust. + +**The clickbait-quiz.** Engagement-driven framing with no actionable segmentation. "What kind of marketer are you" with 4 personality types and no recommendations. + +**The vanity-result quiz.** Flattering descriptions for every segment; no honest segmentation; no specific recommendations. + +**The forced-result quiz.** Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +**The interrogation-quiz.** 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +**The leading-question quiz.** Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +**The black-box quiz.** No explanation of how the result was determined. The taker gets a label with no insight into why. + +**The no-recommendation quiz.** Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +**The mismatched-recommendation quiz.** Recommendation does not match the segment. Audience that catches the mismatch loses trust. + +Detail in [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-quiz-failures.md`](references/common-quiz-failures.md). + +- "Quiz gets shared widely; lead quality is poor." Clickbait pattern; the audience taking and sharing is not the audience the brand serves. +- "Engagement is high; downstream conversion is near zero." Vanity-result pattern; takers enjoyed the segment but had no next step. +- "Most takers route to the same segment." Question architecture not distinguishing; algorithm needs review. +- "Drop-off mid-quiz is high." Too many questions; or questions feel uncomfortable; or the value of finishing is not clear. +- "Segments feel similar." Distinguishability problem; segments need more divergent descriptions and recommendations. +- "Recommendations feel generic." Mapping problem; each segment needs a specific recommendation, not a default. +- "We cannot tell which segment converts best downstream." Attribution missing; segments need tracking through the funnel. +- "Audience comments that the result was wrong." Either question or scoring problem; the segments do not match audience self-perception. + +--- + +## The framework: 12 considerations for quiz and assessment design + +When designing or auditing a quiz, walk these 12 considerations. + +1. **The quiz decision.** Is a quiz the right format for this audience and decision, or would a comparison table or assessment-as-content serve better? +2. **Actionable-segmentation, not clickbait or vanity.** The result places the taker into a category with a specific recommendation. +3. **Question architecture sound.** 5-12 questions; each contributes to segmentation; phrased plainly without leading. +4. **Scoring algorithm fits the segmentation.** Direct mapping, weighted scoring, multi-dimensional, or branching as appropriate. +5. **Result categories distinguishable and balanced.** 4-8 segments; each meaningfully different; each receives a meaningful share of takers. +6. **Segment naming memorable and brand-consistent.** Names the taker can describe to a friend. +7. **Recommendations specific to each segment.** No two segments share the same recommendation; each recommendation is valuable to that segment. +8. **Lead capture honest.** Email exchange for personalized delivery, not for seeing the result. +9. **Result delivery in context.** Recommendation appears with the result, not buried 3 emails later. +10. **Drop-off measured.** Question-by-question drop-off tracked; questions that lose audience flagged for review. +11. **Lead quality measured by segment.** Downstream conversion tracked per segment; some segments may be more valuable than others. +12. **Audit cadence.** Periodic review of segment balance, recommendation alignment, and conversion-by-segment. + +The output of the framework is a quiz that segments the audience meaningfully, produces specific recommendations, and converts the segments into action. + +--- + +## Reference files + +- [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md) - When a quiz is the right tool for the audience and goal, and when a comparison table or other format would serve. +- [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md) - Question count, types, ordering, phrasing, and segment mapping discipline. +- [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md) - Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. +- [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md) - Segment count, naming, distinguishability, balance. +- [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md) - The action attached to each category. Mapping discipline and worked examples. +- [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md) - When and where to ask for the email. Pattern choices and tradeoffs. +- [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md) - The patterns that look like quizzes but degrade trust. +- [`references/clickbait-vs-actionable-distinctions.md`](references/clickbait-vs-actionable-distinctions.md) - Detailed treatment of the keystone framing with worked examples and counter-examples. +- [`references/common-quiz-failures.md`](references/common-quiz-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: quizzes earn engagement when they earn the next step + +The quizzes that work as compounding assets are the ones the audience acts on. Not shares. Not engagement metrics. Action. The taker runs the quiz, gets a segment with a matched recommendation, and does the recommendation. + +That is the bar. Below the bar are clickbait-quizzes (engagement without action) and vanity-results (flattery without action). Above the bar are actionable-segmentation tools that produce specific next steps the taker actually takes. + +The discipline is in the design choices. The questions that genuinely distinguish segments. The scoring algorithm that maps answers to meaningful categories. The recommendations that match each segment specifically. The result-delivery that surfaces the recommendation in context, not 3 emails later. diff --git a/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md b/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md new file mode 100644 index 0000000..43f8d87 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md @@ -0,0 +1,192 @@ +# Clickbait vs actionable distinctions + +Detailed treatment of the keystone framing with worked examples and counter-examples. The single distinction that separates quizzes that compound credibility from quizzes that produce engagement without action. + +--- + +## The three-state framing + +Three states a quiz can land in. Only one of them produces compounding value. + +**State 1: Clickbait.** The quiz exists primarily to generate engagement. "What kind of pizza are you?" energy. The result is fun but means nothing. No segmentation that maps to a decision. No recommendation. Engagement metrics look healthy; downstream metrics are zero. + +**State 2: Vanity-result.** The quiz produces a result that feels meaningful but does not drive action. "You are an INTJ visionary entrepreneur." The taker reads the description, may share it, does not act on it. The result is descriptive without being prescriptive. + +**State 3: Actionable-segmentation.** The quiz produces a result that includes a specific recommendation matched to that segment. The taker can act immediately on the recommendation. The result is both descriptive (this is who you are) and prescriptive (this is what to do next). + +The states are not always obvious from the outside. A quiz can look polished and still be vanity-result; a quiz can look simple and still be actionable-segmentation. The distinction is in the design, not the surface. + +--- + +## What separates the states + +The three differences that separate actionable-segmentation from the others. + +**Difference 1: The result includes a recommendation.** + +- Clickbait: result is a label or description. "You are a 'Strategic Visionary'." +- Vanity: result is an elaborate description. "You are a 'Strategic Visionary': big-picture thinker, comfortable with ambiguity, drawn to long-term impact..." +- Actionable: result is a description plus a recommendation. "You are a 'Strategic Visionary'. The next step that fits this profile: [specific resource, product, or path]." + +**Difference 2: The recommendation is specific to the segment.** + +- Clickbait: no recommendation, so the question does not apply. +- Vanity: every segment may get a similar generic next step ("read our blog"); the recommendation is decorative. +- Actionable: each segment gets a distinct recommendation matched to that segment specifically. + +**Difference 3: The recommendation is actionable today.** + +- Clickbait: no recommendation. +- Vanity: recommendation is aspirational ("consider whether you might be ready for X someday"). +- Actionable: recommendation is concrete and immediate ("start your trial here," "book a 30-minute call here," "download the playbook here"). + +The pattern. Clickbait has no recommendation. Vanity has decorative recommendation. Actionable has specific, matched, concrete recommendation. + +--- + +## Worked example: the same topic in three states + +A quiz on "what kind of marketer are you" treated three ways. + +**Clickbait version.** + +- 5 questions about content preferences and personality. +- Result: "You are 'The Storyteller'." Description: "Storytellers love narrative and connect deeply with their audience." +- Action: share the result. + +The taker enjoys the result, may share it, learns nothing actionable. The quiz produces engagement; the brand earns no qualified leads. + +**Vanity-result version.** + +- 8 questions about marketing approach, content, audience interaction. +- Result: "You are 'The Storyteller': a marketer who values narrative, audience connection, and emotional resonance. Storytellers thrive in brands that prioritize voice and depth..." +- Action: 3 paragraphs of description; soft CTA at the bottom: "Want more? Subscribe to our newsletter." + +The taker reads the elaborate description; may subscribe to the newsletter; does not take a specific action that converts. The quiz produces a moment of attention; the brand earns subscribers but no qualified leads. + +**Actionable-segmentation version.** + +- 7 questions about marketing approach, content, audience interaction, current tools, current challenges. +- Result: "You are 'The Storyteller'. Storytellers benefit most from our 4-part 'Brand Voice Workshop' series. Here is the first lesson; the next 3 arrive over the following week. Or, if you prefer, start with our 'Brand Voice Audit Template' [direct download]." +- Action: clear next step with two options matched to the segment's likely preference (sequence or self-serve). + +The taker gets a matched recommendation. The taker who wants the sequence opts in; the taker who wants the template downloads. Either way, action is taken; the brand earns a qualified lead. + +The same topic, three quizzes, three different outcomes. The actionable version compounds value; the others do not. + +--- + +## How to evaluate which state a quiz is in + +Diagnostic questions to apply to any quiz. + +**Question 1: Does the result include a specific recommendation?** + +- No: the quiz is clickbait or vanity. +- Yes: continue. + +**Question 2: Does each segment have a distinct recommendation, or do all segments share the same recommendation?** + +- All same: the quiz is forced-result; segmentation is decorative. +- Distinct: continue. + +**Question 3: Is the recommendation actionable today?** + +- No (aspirational, vague, "consider"): the quiz is vanity. +- Yes (specific link, button, or action): the quiz is actionable-segmentation. + +**Question 4: Does the recommendation match the segment specifically (not a generic offer)?** + +- No: the quiz is vanity with decorative recommendations. +- Yes: the quiz is actionable-segmentation. + +When all four questions get the right answer, the quiz is actionable-segmentation. When any fails, the quiz is somewhere between clickbait and vanity. + +--- + +## The compounding-value mechanism + +Why actionable-segmentation compounds and the others do not. + +**Actionable-segmentation compounds.** + +- The taker acts on the recommendation; the brand becomes the source of the action. +- The taker sees results from the action; the brand earns credit. +- The taker returns or refers; the brand's reach grows. +- The brand's recommendations become trusted; future quizzes earn more conversion. + +**Clickbait does not compound.** + +- The taker engages; the engagement does not convert. +- The brand's quiz is one of many forgotten amusements. +- No relationship deepens; no credibility builds. + +**Vanity does not compound.** + +- The taker enjoys; the enjoyment does not convert. +- The brand's quiz is one of many flattering distractions. +- The newsletter subscription (if any) decays without engagement. + +The compounding effect is the difference between quizzes that earn ongoing investment and quizzes that get retired. + +--- + +## Why teams build clickbait and vanity quizzes + +The patterns are easy to ship. Understanding why teams default to them helps teams choose actionable-segmentation instead. + +**Reason 1: Engagement metrics are easier to measure.** Conversion rate to email, share counts, time on page are all available immediately. Downstream conversion takes weeks or months to measure. Teams optimize what they measure. + +**Reason 2: Designing recommendations is hard.** Each segment needs a matched recommendation; the brand has to have the recommendations to give. Designing the segment-recommendation mapping is more work than designing the quiz alone. + +**Reason 3: Templates default to clickbait.** Many quiz-platform templates are designed for engagement, not for segmentation-driven action. Using a template often produces clickbait by default. + +**Reason 4: The vanity-result feels safer.** Flattering descriptions feel safer than honest segmentation; teams worry about "telling someone they are not a fit." Honest segmentation is harder but produces more trust. + +**Reason 5: Short-term thinking.** Engagement is immediate; downstream conversion is delayed. Teams optimizing for the next quarter default to engagement. + +The cure. Track downstream conversion as the primary metric. Build the recommendation portfolio before designing the quiz. Avoid templates that default to engagement. Practice honest segmentation. + +--- + +## Counter-example: when engagement is the goal + +Some quizzes are intentionally engagement-driven, and that is fine. + +**The legitimate engagement-quiz.** A consumer brand running a viral quiz to drive social shares and brand awareness. The goal is reach, not lead-capture. The quiz is intentionally entertainment. + +**The pattern.** Light, fun, shareable. No email gate. Result is shareable. Brand association is the value. + +**Why this is fine.** The brand has chosen reach as the metric. The quiz delivers on that goal. The quiz is not pretending to be something it is not. + +**The discipline.** Be honest about the goal. If the goal is engagement, do not pretend the quiz is for lead-capture; do not include a half-hearted email gate that produces neither real engagement nor real leads. + +The clickbait pattern fails when teams pretend it is something else. When teams own the engagement goal and design for it explicitly, the quiz can serve that goal well. + +--- + +## Common patterns by industry + +How clickbait, vanity, and actionable-segmentation play differently across industries. + +**Consumer brands.** Consumer brands often run engagement-quizzes successfully when the brand-association goal is the value. Lead-capture quizzes are harder; consumer audiences resist email gates more. + +**B2B SaaS.** B2B SaaS audiences expect actionable-segmentation. Clickbait and vanity are read as unprofessional. Actionable quizzes that route to specific plans or resources work well. + +**Education and creators.** Mixed. Some audiences engage with personality-style quizzes; some want practical assessment. The audience the brand serves determines which works. + +**Enterprise.** Enterprise audiences usually skip quizzes entirely. When they engage, only actionable-segmentation works; clickbait or vanity is read as unserious. + +**Ecommerce.** Recommendation quizzes ("which of our products fits you") work well as actionable-segmentation when the product portfolio supports it. + +The discipline. Match the quiz pattern to the audience expectation. Audiences that expect actionable-segmentation will reject anything else; audiences that engage with personality quizzes will not be converted by overly-formal segmentation. + +--- + +## Methodology-level choices that stay in the public skill + +The three-state framing. The three differences that separate actionable-segmentation from clickbait and vanity. The diagnostic questions. The compounding-value mechanism. Why teams default to clickbait and vanity. The counter-example for legitimate engagement-quizzes. Industry patterns. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. Specific recommendation portfolios. Specific tracking for downstream conversion per pattern. The team's measurement framework for engagement vs action. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/common-quiz-failures.md b/skills/quiz-and-assessment-design/references/common-quiz-failures.md new file mode 100644 index 0000000..a350ba8 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/common-quiz-failures.md @@ -0,0 +1,187 @@ +# Common quiz failures + +8+ failure patterns with diagnoses and cures. The patterns that surface as "the quiz did not produce qualified leads" or "engagement is high but nothing converts" or "we cannot tell if the quiz worked." + +--- + +## "Quiz gets shared widely; lead quality is poor." + +**The diagnosis.** Clickbait pattern. The audience taking and sharing is not the audience the brand serves; the quiz attracts engagement from a broader audience than the brand's target. + +**The cure.** Tighten the quiz's audience-fit. Specific titles, specific topics, specific recommendations matched to the brand's actual buyers. Detail in `references/quiz-investment-criteria.md` (recommendation-portfolio precondition) and `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Engagement is high; downstream conversion is near zero." + +**The diagnosis.** Vanity-result pattern. Takers enjoyed the segment but had no next step. The quiz produced moments of attention without action. + +**The cure.** Add specific recommendations to each segment. Detail in `references/result-to-recommendation-mapping.md`. Each result page must include a clear next step. + +--- + +## "Most takers route to the same segment." + +**The diagnosis.** Question architecture not distinguishing. Either the questions do not actually capture differentiating signals, or the scoring algorithm biases toward one segment. + +**The cure.** Audit the question-segment mapping (`references/question-architecture-patterns.md`). Ensure each question contributes meaningfully to multiple segments. Audit the scoring weights for unintended bias. + +--- + +## "Drop-off mid-quiz is high." + +**The diagnosis.** Too many questions, or questions feel uncomfortable, or the value of finishing is not clear. + +**The cure.** Reduce question count if over 12. Audit questions for those that feel sensitive or repetitive. Add a progress indicator and a teaser of the result ("almost done; see your result next") to reduce late-stage drop-off. + +--- + +## "Segments feel similar." + +**The diagnosis.** Distinguishability problem. Either over-segmentation (more segments than the questions can support) or weak descriptions that do not differentiate. + +**The cure.** Reduce segment count to what the questions can distinguish (`references/result-categorization-patterns.md`). Strengthen the descriptions to make each segment meaningfully different. + +--- + +## "Recommendations feel generic." + +**The diagnosis.** Mapping problem. Each segment needs a specific recommendation, not a default. + +**The cure.** Audit the segment-to-recommendation mapping (`references/result-to-recommendation-mapping.md`). Verify each segment has a distinct, valuable, actionable recommendation. + +--- + +## "We cannot tell which segment converts best downstream." + +**The diagnosis.** Attribution missing. Segments need tracking through the funnel. + +**The cure.** Tag leads by segment at capture. Track downstream conversion per segment. The data informs which segments warrant continued investment and which segments may need different recommendations. + +--- + +## "Audience comments that the result was wrong." + +**The diagnosis.** Either question or scoring problem. The segments do not match audience self-perception. + +**The cure.** Persona testing. Have personas representing each segment take the quiz; verify each persona reaches the intended segment. Adjust questions or scoring weights to align. + +--- + +## "The quiz earns 5000 takers; the email list grows by 200." + +**The diagnosis.** Either the result is not perceived as valuable enough to opt in for additional value (Pattern B failure), or the email gate is for the result itself with no value-add (lead-trap risk). + +**The cure.** Design a substantive value-add for the email opt-in (PDF, sequence, resource). Make the value-add visible at the result. Detail in `references/lead-capture-integration-patterns.md`. + +--- + +## "We added a quiz; our other lead magnets stopped converting." + +**The diagnosis.** Cannibalization. The quiz absorbed the audience that previously converted via other magnets. + +**The cure.** This may not be a failure. If the quiz-sourced leads are higher quality than the previous magnets, the cannibalization is portfolio improvement. If not, the quiz may have replaced a working magnet with a worse one; audit and decide. + +--- + +## "Sales says quiz-sourced leads are low-fit." + +**The diagnosis.** Either the audience-fit at the quiz is wrong (the quiz attracts non-target audiences) or the recommendation-mapping routes audiences to wrong products. + +**The cure.** First, audit the audience-fit. If the quiz is attracting the wrong audience, tighten the targeting (title, topic, distribution channels). Second, audit the recommendation-mapping. If the audience-fit is right but the recommendation is wrong, fix the mapping. + +--- + +## "The quiz looks great; nobody completes it." + +**The diagnosis.** Either the topic does not engage the audience (audience-fit weak) or the question count is too high (drop-off too early). + +**The cure.** First, validate the topic with audience research. If the topic is right, audit the question count and question phrasing. + +--- + +## "Engagement was great at launch; conversion has dropped 40 percent over a year." + +**The diagnosis.** Decay. Recommendations have shifted; segments have evolved; references are stale. + +**The cure.** Audit and refresh. Update recommendations to match current portfolio; verify segments still describe the audience accurately; refresh any stale references in question phrasing or result descriptions. + +--- + +## "We made the quiz shorter; conversion went up but downstream conversion went down." + +**The diagnosis.** Question removal removed differentiating signals. The quiz now produces engagement faster but the segmentation is weaker. + +**The cure.** Restore the questions that contributed to segmentation. Speed-of-completion is a metric; segmentation quality is a separate metric. Optimize for the right one. + +--- + +## "The result page is fine; the email follow-up sequence converts terribly." + +**The diagnosis.** Sequence does not match the segment. Either the sequence is generic across segments, or the sequence does not deepen the matched recommendation. + +**The cure.** Design segment-specific sequences (or at least segment-specific opening emails). The sequence should extend the result's recommendation, not start over with generic content. + +--- + +## "We tried branching logic; the quiz felt confusing." + +**The diagnosis.** Branching added complexity without value. Different takers got different question sets; comparison across takers became hard. + +**The cure.** Revert to linear quiz unless branching is genuinely warranted. The simplicity often produces better outcomes. + +--- + +## "The quiz works on Chrome; it breaks on Safari mobile." + +**The diagnosis.** Browser/device-specific bugs. The quiz was tested on the team's primary platform; the audience's actual devices were not covered. + +**The cure.** Cross-browser, cross-device testing. The audience uses what they use; the quiz has to work there. + +--- + +## "The recommendation links to a product we discontinued." + +**The diagnosis.** Maintenance lapse. The quiz's recommendation drifted out of sync with the brand's actual offering. + +**The cure.** Set a maintenance trigger: when products are discontinued or pricing changes, the quiz updates are part of the change. Quarterly review at minimum. + +--- + +## "Audiences take the quiz multiple times to get different results." + +**The diagnosis.** This is fine, often. Audiences exploring the segmentation may take it multiple times to understand how the algorithm works. Track unique users vs total completions. + +**The action.** Make sure the algorithm is stable enough that repeated takes with consistent answers produce consistent results. Inconsistency at this level signals algorithm issues. + +--- + +## "The quiz produces good leads; the sales team does not follow up." + +**The diagnosis.** Sequence or routing missing. Quiz-sourced leads should be tagged, routed to sales, and prioritized appropriately. + +**The cure.** Design the post-conversion flow. Calculator-sourced leads should be tagged with their segment, routed to the appropriate sales rep, and the sales rep should know which segment the lead represents. + +--- + +## The pattern across failures + +Most quiz failures fall into one of three patterns. + +**Pattern 1: The quiz does not deliver actionable segmentation.** Clickbait, vanity-result, no-recommendation, mismatched-recommendation. The fix is to add or correct the recommendations. + +**Pattern 2: The quiz does not match the audience.** Audience-fit weak, topic-audience mismatch, format-audience mismatch (e.g., quizzes for enterprise audiences who reject the format). The fix is to align the quiz to the audience the brand serves. + +**Pattern 3: The quiz decays.** Recommendations point to retired products; segments no longer describe the audience; references are stale. The fix is maintenance discipline. + +The metric pattern: quiz failures often look fine on engagement metrics. The signal is in lead quality, downstream conversion, and audience self-recognition. Programs that track only engagement keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that engagement alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md b/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md new file mode 100644 index 0000000..d10544c --- /dev/null +++ b/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md @@ -0,0 +1,240 @@ +# Lead capture integration patterns + +When and where to ask for the email. Pattern choices and tradeoffs. The decision that affects both conversion and lead quality. + +The lead-capture integration is where the quiz earns its email. Done well, the audience opts in for personalized value; done poorly, the quiz becomes a lead-trap that the audience resents. + +--- + +## The capture-honest principle + +Capture the email in exchange for personalized result delivery, not in exchange for seeing the result at all. + +**The honest pattern.** The taker completes the quiz; the result is shown; an offer is made for additional value (PDF, follow-up sequence, saved scenario) that requires the email. + +**The dishonest pattern.** The taker completes the quiz; the result is calculated but hidden; the email is required to reveal it. This is the lead-trap pattern (described in `calculator-design`'s email-capture-decision-tree but applies equally to quizzes). + +--- + +## Pattern A: Email after questions, before result + +The taker completes the quiz; before the result is shown, an email gate appears. + +**How it works.** + +- The taker answers all questions. +- A form appears: "Enter your email to see your personalized result." +- The taker enters email; the result is shown. + +**Strengths.** + +- Highest conversion to email opt-in. +- Common pattern; audiences are familiar. + +**Weaknesses.** + +- Lead-trap pattern. The audience that recognizes the manipulation feels resentment. +- Lead quality is lower; some takers enter throwaway emails. +- Downstream conversion suffers because some leads are unqualified or actively annoyed. + +**When to use.** When the quiz is genuinely entertainment-driven and the audience expects the format (consumer brands sometimes work here). For B2B and considered purchases, this pattern often degrades trust. + +--- + +## Pattern B: Email after result, for personalized delivery + +The result is shown; an offer is made for personalized PDF or follow-up. + +**How it works.** + +- The taker answers all questions. +- The result is shown immediately, including segment description and matched recommendation. +- Below or alongside the result, an offer: "Want this as a PDF you can share?" or "Want a personalized 5-day sequence with deeper resources for your segment?" +- The taker who wants the additional value enters email. + +**Strengths.** + +- Honest. The audience gets what they came for. +- Lead quality is higher; takers who opt in are signaling real interest. +- Trust is preserved; audience that does not opt in still leaves with positive brand association. + +**Weaknesses.** + +- Lower conversion rate to email than Pattern A. +- Requires designing additional value (PDF, sequence) that justifies the email. + +**When to use.** Default pattern for B2B and considered purchases. The honest exchange compounds trust over time. + +--- + +## Pattern C: Email integrated with optional features + +The result is shown; multiple optional opt-ins are offered. + +**How it works.** + +- The taker answers all questions. +- The result is shown. +- Multiple opt-in options appear, each with distinct value: "Save this scenario for later," "Get notified when new content for your segment is available," "Download a personalized resource." +- The taker chooses which (if any) to opt into. + +**Strengths.** + +- Most flexibility for the audience. +- Allows different audience segments to engage at different levels. +- Lead quality is high because each opt-in is for specific value. + +**Weaknesses.** + +- More complex to design and implement. +- Multiple options can dilute conversion ("paradox of choice"). +- Requires the brand to actually deliver on each opt-in. + +**When to use.** When the quiz has multiple legitimate value-add follow-ups and the audience benefits from choice. + +--- + +## Pattern D: Progressive opt-in across the quiz + +Email is captured early but only used after the quiz completes. + +**How it works.** + +- The quiz starts with optional email entry ("get a personalized PDF report when you finish"). +- Takers can enter email upfront or skip. +- The quiz proceeds; the result is shown for everyone. +- Takers who entered email get the PDF; others see the result and an opt-in offer. + +**Strengths.** + +- Captures highly committed takers early. +- Does not gate the result. +- Provides a soft opt-in path for less-committed takers. + +**Weaknesses.** + +- Asking for email upfront can depress quiz starts. +- Two-path design (email-given vs not-given) adds complexity. + +**When to use.** When the audience benefits from setting expectations upfront and when the brand can deliver value differently to opted-in vs walk-up takers. + +--- + +## The value-add at lead capture + +What the user gets for their email matters as much as when the email is asked. + +**Strong value-adds.** + +- A personalized PDF report matched to the segment. +- A follow-up email series that deepens the segment-matched content. +- A curated resource list specific to the result. +- Notifications about new resources, products, or events relevant to the segment. + +**Weak value-adds.** + +- Just sending the same result by email (no value-add over what is on screen). +- A generic newsletter signup (not personalized to the result). +- A "join our community" offer with no clear value. + +**The discipline.** The value-add should be substantively better than what the audience saw on screen. If it is not, the email gate is not justified. + +--- + +## Conversion vs lead quality + +The patterns trade off these two metrics. + +**Conversion-optimized.** Pattern A captures the most emails but produces lower lead quality. Suitable when the goal is volume or when the audience is highly aligned (every taker is a target lead). + +**Quality-optimized.** Pattern B and C capture fewer emails but produce higher lead quality. Suitable when the goal is downstream conversion or when the audience is mixed (only some takers are target leads). + +**The choice.** Depends on what the program optimizes for. Brands optimizing for downstream revenue often choose Pattern B or C. Brands optimizing for list growth may default to Pattern A. + +**The trap.** Optimizing for conversion at the expense of lead quality is short-term thinking. The conversion metric looks fine; the downstream metrics suffer; the program quietly underperforms. + +--- + +## The "no email needed" alternative + +Some quizzes do not capture email at all. + +**When this works.** When the quiz's purpose is brand-building, SEO, or audience-engagement rather than lead-capture. The quiz's existence and shareability are the value; the email is incidental. + +**The pattern.** The taker takes the quiz; the result is shown; share buttons are prominent; no email gate. + +**Why it can work.** Some brands earn more from a widely-shared quiz than from a gated quiz that captures fewer emails. The brand association is the value. + +**When it fails.** When the program needs leads and the no-gate design produces nothing for the funnel. + +--- + +## Lead-capture form design + +The form itself matters. + +**Field count.** Email only is the strong default. Each additional field reduces conversion. + +**Field justification.** If additional fields are required (name for personalization, company for B2B sales context), justify them inline. "We use your name to personalize your follow-up" is honest; uncontextualized fields feel like sales-form padding. + +**Form placement.** Inline with the result is honest; popup that interrupts the result viewing is hostile. + +**CTA copy.** "Get my personalized PDF" beats "Submit." Specific value statement beats generic action. + +**Loading state.** After submission, show progress and confirm receipt. "Sending your PDF now... check your inbox in 2 minutes." + +--- + +## Post-capture experience + +What happens after the email is captured. + +**Immediate delivery.** The promised PDF, sequence, or resource arrives within minutes. Delays break trust. + +**Confirmation message.** On the result page or in the email, confirm what was sent and what to expect next. + +**Sequence integration.** If a follow-up sequence was offered, the first email arrives within 24 hours. The sequence delivers the promised cadence. + +**Opt-out clarity.** Easy unsubscribe from the start. Audiences that find unsubscribe friction lose trust permanently. + +--- + +## Capture-pattern testing + +Test pattern choice with real metrics. + +**Test design.** A/B test Pattern A vs Pattern B with the same quiz. Measure both conversion to email and downstream conversion (trial signup, demo request, purchase). + +**The metric that matters.** Downstream conversion per visitor, not conversion to email. A pattern that captures fewer emails but produces more downstream conversion is the better pattern. + +**Test duration.** Long enough to capture downstream signal (often 30-60 days minimum, depending on consideration cycle). + +--- + +## Common capture failures + +**Lead-trap pattern.** Result hidden behind email; downstream conversion drops; trust degrades. + +**Email gate without value.** Email required for the same content; gate is not justified; conversion drops. + +**Too many fields.** Form asks for name, company, role, phone in addition to email; conversion plummets. + +**Generic CTA copy.** "Submit" rather than "Get my personalized PDF"; conversion suffers. + +**Popup that interrupts.** Result loads; popup appears; user's flow breaks. + +**Slow delivery.** PDF arrives 30 minutes later; trust drops. + +**No confirmation.** User submits, sees no acknowledgment, wonders if it worked. + +**Hard unsubscribe.** Multi-step or hidden unsubscribe; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The capture-honest principle. Pattern A through D with strengths, weaknesses, and when-to-use guidance. The value-add at lead capture. The conversion-vs-quality tradeoff. The no-email-needed alternative. Lead-capture form design. Post-capture experience. Capture-pattern testing. Common failures. + +## Implementation choices that stay internal + +Specific capture pattern choices for specific quizzes. Specific PDF templates and sequence designs. Specific form copy and CTAs in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/question-architecture-patterns.md b/skills/quiz-and-assessment-design/references/question-architecture-patterns.md new file mode 100644 index 0000000..8fca5ba --- /dev/null +++ b/skills/quiz-and-assessment-design/references/question-architecture-patterns.md @@ -0,0 +1,212 @@ +# Question architecture patterns + +Question count, types, ordering, phrasing, and segment mapping discipline. The questions are the mechanism that produces the segmentation; bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +--- + +## Question count + +Most effective quizzes use 5-10 questions. + +**Fewer than 5 questions.** Rarely produces meaningful segmentation. The taker reaches the result quickly, but the result feels arbitrary because too few signals were captured. Useful only for very simple categorizations (binary or 3-segment outcomes). + +**5-7 questions.** The sweet spot for most quizzes. Enough to produce nuanced segmentation; few enough that the audience completes without fatigue. + +**8-12 questions.** Acceptable when the segmentation is genuinely multi-dimensional or when the audience has high commitment. Watch drop-off carefully; the last few questions are where audiences abandon. + +**13+ questions.** Stops feeling like a quiz; starts feeling like a survey. Drop-off rises sharply. If the segmentation truly needs this many questions, consider whether quiz is the right format. + +--- + +## Question types + +Choose the type that fits the variable being captured. + +**Multiple-choice (single-select).** The most common quiz question type. Each option maps to a segment or scoring weight. + +When to use: when the answer space is well-defined and mutually exclusive. +When to avoid: when the audience genuinely could choose multiple answers; forcing single-select frustrates the taker. + +**Multiple-select.** Useful when multiple attributes apply to the taker. + +When to use: when the answer space includes overlapping options ("which features matter most" with multiple selections). +When to avoid: when scoring complexity outweighs the value; multi-select complicates segmentation. + +**Slider or scale.** "On a scale of 1-5, how often do you..." Useful for intensity questions. + +When to use: when the variable is continuous (frequency, importance, satisfaction). +When to avoid: when the categorization is genuinely categorical; sliders force false continuity. + +**Yes/no.** Useful for binary qualifying questions. + +When to use: as part of a broader question set when one binary attribute matters (does the team use a CRM today, yes or no). +When to avoid: as the primary question type; quizzes built only on yes/no questions feel coarse. + +**Free text.** Avoid in quizzes. Free text breaks the scoring flow and adds friction. The few quizzes that genuinely need free text often work better as forms or assessments. + +--- + +## Question ordering + +The order matters as much as the questions themselves. + +**Open with engaging, low-friction questions.** "What kind of role best describes you?" or "What size is your team?" These warm up the taker and build commitment. + +**Mid-quiz: substantive segmentation questions.** The questions that most influence the segmentation belong in the middle. The taker has invested enough to commit; you have not yet exhausted their patience. + +**Late-quiz: more revealing or sensitive questions.** "How effective is your current process?" or "What is your biggest challenge?" These questions benefit from the trust built earlier. + +**End: qualifying questions, if needed.** Demographic data, company-size confirmation, or contact-channel preferences. These belong at the end, not the start. Asking demographic questions first signals "this is a sales form" and depresses completion. + +--- + +## Question phrasing + +Plain language. No jargon. No leading. + +**Plain language.** Avoid technical terms the audience may not know. If the quiz is for SaaS founders, "ARR" is fine; if it is for general business owners, "annual revenue" is clearer. + +**Specific situations.** Frame questions around situations the audience recognizes. "When you onboard a new customer, do you..." beats "What is your customer-onboarding maturity." + +**Avoid leading questions.** Phrasing that pushes toward a specific answer biases the result. + +- Leading: "How much do you struggle with X?" (presumes struggle) +- Honest: "How would you describe your experience with X?" + +**Avoid double-barreled questions.** Questions that mix two dimensions confuse scoring. + +- Double-barreled: "How much do you value speed AND simplicity?" +- Cleaned up: split into two questions if both dimensions matter. + +**Avoid "all of the above" or "none of the above" defaults.** These options are escape valves that produce uninterpretable answers. + +--- + +## Question-segment mapping + +Each question should contribute to the segmentation in a defined way. + +**The principle.** For each question, document which answer choices map to which segments and with what weight. + +**Example: "What size is your team?"** + +- 1-5 employees → segment "Solo or small" (+3 to that segment) +- 6-25 employees → segment "Growing team" (+3) +- 26-100 employees → segment "Mid-market" (+3) +- 101+ employees → segment "Enterprise" (+3) + +**Example: "What is your sales process maturity?"** + +- "Founder-led, no defined process" → "Solo or small" (+2), "Growing team" (+1) +- "Some defined steps, owner driven" → "Growing team" (+2), "Mid-market" (+1) +- "Defined sales playbook, multiple reps" → "Mid-market" (+2), "Enterprise" (+1) +- "Multi-stage enterprise sales process" → "Enterprise" (+3) + +The mapping is explicit. Each question contributes specific weight to specific segments. The mapping should be documented so future maintenance can verify it. + +**Filler questions.** Questions that do not affect the segmentation are filler. They add friction without adding value. Audit and remove. + +--- + +## Question count vs segmentation depth + +The relationship between question count and segmentation accuracy. + +**Few questions, broad segments.** A 5-question quiz produces 4-5 segments reliably; trying to produce 10 segments from 5 questions makes each segment poorly distinguished. + +**More questions, narrower segments.** An 8-question quiz can produce 6-8 segments with enough distinction. + +**The over-segmentation trap.** Too many segments produced from too few questions creates segments that are not really different. The audience that lands in different segments gets similar recommendations; the segmentation is fake. + +**The right ratio.** Roughly 1.5-2 questions per segment is a useful baseline. 5-7 segments from 8-12 questions; 4-5 segments from 5-7 questions. + +--- + +## Conditional questions and branching + +Whether to ask different questions based on earlier answers. + +**Branching when it helps.** Later questions make sense only in the context of earlier ones. "If you have a CRM today, which one?" is a useful follow-up to "Do you use a CRM today?" + +**Branching when it hurts.** When branching adds complexity without value, when the branching makes the quiz feel different for different takers in confusing ways, when the scoring becomes hard to reason about. + +**The simplicity preference.** Linear quizzes (everyone gets the same questions in the same order) are easier to maintain, easier to test, and easier for the audience to predict. Use branching only when the value justifies the complexity. + +--- + +## Drop-off considerations + +Where audiences abandon, and why. + +**The first question.** Some takers click into the quiz and leave at question 1. Often the question or the format made them realize this is not for them. This is fine; honest filtering. + +**Mid-quiz (questions 4-7).** Drop-off here usually signals fatigue or discomfort. Audit the questions; are they too long, too sensitive, too repetitive? + +**Late-quiz (final questions).** Drop-off here often signals that the user got bored or the value of finishing was not clear. A progress indicator and a teaser of the result ("almost done; see your result next") can reduce late-stage drop-off. + +**Question-by-question tracking.** Tracking drop-off per question is the diagnostic. Questions with disproportionate drop-off warrant review. + +--- + +## Mobile question design + +Most quiz takers are on mobile. The question UX has to work there. + +**Mobile-specific considerations.** + +- Touch-friendly answer options (minimum 44x44 pixel touch targets). +- Single question per screen on mobile (multi-question screens cramp). +- Progress indicator visible without scroll. +- Answer options large enough to tap accurately; spacing prevents accidental taps. +- Sliders sized for thumb interaction. + +**Mobile testing.** Test the quiz on actual devices. Real-device behavior often differs from browser dev-tools simulation. + +--- + +## Question-mapping audit + +Periodically audit the question-segment mapping. + +**The audit.** For each segment, verify that the questions actually produce that segment for takers who should get it. Run the quiz with personas representing each segment; confirm each persona reaches the right result. + +**The audit cadence.** When the recommendation portfolio changes, when the audience composition shifts, or at least quarterly. + +**Drift indicators.** + +- One segment now receives 70+ percent of takers. +- Another segment receives less than 5 percent. +- Specific personas reach the wrong segment when audited. +- Audience comments that the result was wrong. + +These signals warrant question or scoring revision. + +--- + +## Common question architecture failures + +**Too many questions.** 15+ questions feels like a survey; drop-off climbs. + +**Filler questions.** Questions that do not affect segmentation; audit and remove. + +**Leading questions.** Phrasing that biases the answer. + +**Double-barreled questions.** Two dimensions in one question; scoring becomes ambiguous. + +**Demographic questions first.** Signals "sales form"; depresses completion. + +**Vague answer options.** "Sometimes" vs "often" without anchors; the taker cannot calibrate. + +**Inconsistent question types.** Mixing 5-point sliders with yes/no without coherent rationale; the rhythm breaks. + +**Mobile-broken questions.** Sliders that do not work on touch; answer options that overflow. + +--- + +## Methodology-level choices that stay in the public skill + +Question count, types, ordering, phrasing. Question-segment mapping discipline. Question count vs segmentation depth. Conditional questions and branching. Drop-off considerations. Mobile question design. Question-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific question sets for specific quizzes. Specific scoring weights and segment mappings. Specific tooling for quiz engineering and analytics. The team's drop-off benchmarks and audit calendars. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md b/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md new file mode 100644 index 0000000..533a111 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md @@ -0,0 +1,223 @@ +# Quiz anti-patterns + +The patterns that look like quizzes but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The clickbait-quiz + +The pattern. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you?" with 4 personality types and no recommendations. + +The signal. Engagement metrics are high (shares, completions); downstream metrics are flat. The quiz is fun; it does not produce qualified leads or conversions. + +The cost. The build cost is wasted on entertainment that does not compound business value. The brand earns "fun but not useful" association. + +The cure. Add actionable segmentation. Each segment maps to a specific recommendation matched to that segment. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The vanity-result quiz + +The pattern. Flattering descriptions for every segment. No honest characterization. No specific recommendations. + +The signal. Takers enjoy the result; do not act on it; do not return. The quiz produces a moment of attention without a relationship. + +The cost. The audience associates the brand with horoscope-style content. The quiz does not differentiate the brand from competitors offering similar entertainment. + +The cure. Honest segmentation. Some segments are more flattering than others; honest descriptions produce respect; recommendations that match each segment specifically produce action. + +--- + +## The forced-result quiz + +The pattern. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The signal. Sales team or product team notices that quiz-sourced leads all look the same; the segmentation is not differentiating. + +The cost. The quiz misleads the audience. Takers who answered honestly believing they would get a matched recommendation get a generic one; trust degrades. + +The cure. Real segmentation that produces real different recommendations per segment. If the brand only has one recommendation, do not use a quiz format; use a clear landing page. + +--- + +## The interrogation-quiz + +The pattern. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The signal. High drop-off rate, especially at questions 8-15. Few takers reach the result. + +The cost. The build effort produces a quiz few people complete. The audience that drops off remembers the brand as the source of the long form they abandoned. + +The cure. Reduce question count. 5-12 questions is the working range. Audit questions for those that do not affect segmentation; remove them. + +--- + +## The leading-question quiz + +The pattern. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The signal. The result distribution is biased; takers report that the result felt predetermined; analytical audiences notice the leading. + +The cost. The audience that catches the leading loses trust. The result is artificially produced rather than reflecting the taker's actual situation. + +The cure. Plain phrasing without bias. "How would you describe your experience with X?" beats "How much do you struggle with X?" + +--- + +## The black-box quiz + +The pattern. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The signal. Audience comments asking how the result was calculated; some takers question whether the result is real or random. + +The cost. The quiz feels arbitrary. Even when the segmentation is real, the audience cannot verify; trust suffers. + +The cure. Some transparency about the methodology. "Your result reflects your answers to questions 2, 4, and 6" or a brief explanation of what the segments represent. + +--- + +## The no-recommendation quiz + +The pattern. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The signal. Strong engagement; near-zero downstream conversion; the quiz captures a moment without converting it. + +The cost. The brand has the audience's attention and does nothing with it. The quiz produces brand impression without business impact. + +The cure. Every result page must include a specific next step. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The mismatched-recommendation quiz + +The pattern. The recommendation does not match the segment. A taker classified as "enterprise" gets a "starter plan" recommendation, or vice versa. + +The signal. Sales team feedback that quiz-sourced leads do not match the recommended product. Audience feedback that the recommendation felt wrong. + +The cost. Trust damage. The taker who notices the mismatch feels misled; the brand earns "doesn't get me" reputation. + +The cure. Audit the segment-to-recommendation mapping. Verify each segment's recommendation actually fits. + +--- + +## The over-segmentation quiz + +The pattern. 12+ segments produced from 5 questions. Most segments end up similar; segmentation is fake. + +The signal. Segments that read the same; segments that get the same recommendation; segments that receive less than 3 percent of takers each. + +The cost. Design and copy effort wasted on segments that do not really exist. The audience that lands in similar segments cannot tell them apart. + +The cure. Reduce segment count to what the questions can actually distinguish. 4-7 segments from 5-7 questions; 6-8 segments from 8-10 questions. + +--- + +## The under-segmentation quiz + +The pattern. 2 segments that could have been a yes/no question. The quiz format is over-engineering. + +The signal. The audience completes the quiz quickly; the result feels obvious; the quiz adds friction without adding value. + +The cost. Build effort wasted on a quiz that did not need to be a quiz. The audience that recognizes the over-engineering questions the brand's judgment. + +The cure. Either expand the segmentation to justify the format or replace the quiz with a simpler tool (yes/no qualifier, comparison table). + +--- + +## The lead-trap quiz + +The pattern. The result is calculated but hidden behind an email gate. The taker enters 8 fields, hits Calculate, sees "enter your email to see your result." + +The signal. Email-form conversion is high; downstream conversion is low; audience that recognizes the pattern bounces immediately. + +The cost. Lead quality suffers. The brand earns "lead-trap" reputation. Detail in `references/lead-capture-integration-patterns.md`. + +The cure. Show the result freely; gate the additional value (PDF, follow-up sequence) instead. + +--- + +## The cookie-cutter quiz + +The pattern. The quiz looks and behaves like every other quiz from a template platform. Generic UI, generic question style, generic result format. + +The signal. The quiz does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The quiz becomes commodity. The brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Question phrasing in brand voice. Result presentation that feels distinct. + +--- + +## The mobile-broken quiz + +The pattern. Quiz works on desktop; breaks on mobile. Answer options that overflow; sliders impossible to grab; result hidden below the fold. + +The signal. High mobile bounce rate; mobile completion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Detail in `references/question-architecture-patterns.md` (mobile section). + +--- + +## The popup-interrupted quiz + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. + +The signal. Bounce rate spikes at the result moment; users complain about the interruption. + +The cost. The quiz's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. + +--- + +## The orphan-quiz + +The pattern. The quiz exists; no follow-up sequence; no integration with the broader funnel. Takers complete; nothing happens. + +The signal. Email captures sit on a list with no engagement; downstream conversion is near zero. + +The cost. The lead-capture work was for nothing. The brand has emails but no relationship. + +The cure. Design the post-quiz sequence as part of the quiz design (similar to the lead-magnet sequence discipline in `lead-magnet-design`). + +--- + +## The everyone-quiz + +The pattern. Quiz designed to appeal to "everyone." Generic segments; generic recommendations. + +The signal. Conversion may be high; lead quality is low; downstream conversion is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly. + +The cure. Narrow the audience the quiz serves. Specific quizzes for specific segments produce specific recommendations that convert. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active quiz, looking specifically for these anti-patterns. + +**Audit questions per quiz.** + +- Does each segment have a specific, distinct recommendation (anti-pattern check: forced-result, mismatched-recommendation)? +- Is segment distribution balanced across takers (anti-pattern check: over-segmentation, under-segmentation)? +- Is drop-off concentrated at specific questions (anti-pattern check: interrogation, leading questions)? +- Does the result page include a clear next step (anti-pattern check: no-recommendation, vanity-result)? +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Does the quiz feel branded or templated (anti-pattern check: cookie-cutter)? +- Does the quiz work on mobile (anti-pattern check: mobile-broken)? + +**The retire decision.** Anti-pattern quizzes often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-quiz plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md b/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md new file mode 100644 index 0000000..11cf765 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md @@ -0,0 +1,145 @@ +# Quiz investment criteria + +When a quiz is the right tool for the audience and the goal, and when a comparison table or other format would serve. The conditions that warrant the quiz format. + +A quiz is a meaningful build. Question architecture, scoring algorithm, result categorization, recommendation mapping, lead-capture integration. The quiz earns this investment only when specific conditions are present. + +--- + +## When a quiz earns the build + +Five conditions that, when present, make a quiz a strong investment. + +**The audience faces a decision that benefits from categorization.** "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. + +**The categorization can be derived from a small number of questions.** 5-12 questions can produce meaningful segmentation. If the categorization needs 30+ questions, the format is closer to a survey or assessment than a quiz; the audience drop-off makes the format wrong. + +**The brand has a portfolio of recommendations that match the segments.** A quiz that produces 5 segments and only one recommendation is decorative; the segment-recommendation mapping is the value. + +**The result format suits the audience.** Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage well. Audiences who do not (technical buyers, enterprise sales) often see quizzes as gimmicks. + +**The success metric is defined.** Lead volume from the quiz, lead quality by segment, downstream conversion per segment, the audience acting on the recommendation. Without the success metric defined, evaluation is impossible. + +When all five are present, the quiz is a strong investment. When two or fewer are present, a different format (comparison table, worked example, calculator) often serves better. + +--- + +## When a quiz does NOT earn the build + +Funnels where the quiz is the wrong tool. + +**The categorization is trivial.** "What plan is right for you" with two plans does not need a quiz; a comparison table works. Quizzes earn investment when the categorization is non-trivial. + +**The categorization is irrelevant to the next step.** A personality quiz with no product-recommendation tie-in entertains but does not convert. The categorization needs to map to action. + +**The brand has no varied recommendations.** A quiz with one outcome is bait; the segmentation is decorative. Without a portfolio of segment-matched recommendations, the quiz cannot deliver the actionable-segmentation value. + +**The audience disrespects quizzes in this context.** Enterprise buyers often see quizzes as unprofessional. Technical decision-makers often skip quizzes in favor of direct documentation. The format choice has to fit the audience the brand wants to serve. + +**The team cannot maintain the quiz.** Quizzes decay as recommendations change, segments evolve, and audience preferences shift. Without maintenance commitment, the quiz becomes stale. + +**The audience would convert without the quiz.** When the funnel is already producing the conversion the quiz would serve, the quiz adds friction without lift. + +The honest assessment matters more than the default. "Should we have a quiz" is not the question. "Is the quiz the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A quiz is a meaningful build. Account for the cost honestly. + +**The build cost.** Question design, scoring algorithm, result categorization, recommendation mapping, UI design, mobile responsiveness, integration. A meaningful quiz often takes 30-100 engineering hours plus design, copy, and content for the recommendations. + +**The maintenance cost.** Recommendations change; segments evolve; question phrasing decays. Quarterly review and updates run 3-8 hours per active quiz. + +**The recommendation portfolio cost.** Each segment needs a matched recommendation. Building or curating those recommendations is itself work. + +**The opportunity cost.** What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization. The quiz's success has to clear the bar of those alternatives. + +The decision frame. The quiz earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus recommendation portfolio. + +--- + +## The recommendation-portfolio precondition + +Without a portfolio of segment-matched recommendations, the quiz cannot deliver actionable segmentation. + +The check. For the segmentation the quiz will produce, does the brand have a distinct, valuable recommendation for each segment? + +If yes, the quiz can deliver actionable segmentation. The takers get matched to a recommendation that fits their result. + +If no (the brand has one product, one resource, one recommendation regardless of segment), the quiz becomes vanity. The segmentation is decorative; the recommendation was predetermined. + +**How to assess the recommendation portfolio.** + +- Does the brand have multiple products, services, or content paths that fit different audience segments? +- Can the brand articulate which recommendation fits which segment specifically? +- Are the recommendations valuable enough to that segment to justify the quiz? + +If yes to most of these, the recommendation portfolio supports the quiz. If no, the quiz is the wrong format until the portfolio exists. + +--- + +## The decision worked example + +A B2B SaaS company considering a "What CRM fits your team" quiz. + +**Conditions check.** + +- Decision benefits from categorization: yes. Prospects evaluate CRMs based on team size, use case, sales process maturity, integration needs. The categorization is non-trivial. +- Small number of questions sufficient: yes. 6-8 questions can capture team size, use case, sales process, integration needs. +- Recommendation portfolio: yes. The brand offers 3 plan tiers plus 2 industry-specific configurations. Each segment can map to a distinct recommendation. +- Audience-fit for quiz format: yes. B2B mid-market PMs and sales leads engage with quizzes when the recommendation is genuinely useful. +- Success metric: yes. Lead volume from the quiz, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo or trial within 60 days. + +**Decision.** Build the quiz. The conditions warrant it. + +**Result categorization.** 5 segments: "Solo founder just starting," "Growing team without CRM," "Mid-market with multiple sales reps," "Enterprise with complex sales cycles," "Integration-heavy team." + +**Recommendation per segment.** Each segment maps to a specific plan and onboarding path. The segment description explains why that recommendation fits. + +**Lead capture.** Email after result for personalized PDF showing the recommendation, alternative options considered, and case study from a similar customer. + +The decision was not "should we have a quiz" but "given these conditions, this is the quiz to build." + +--- + +## When to choose a different format + +The quiz is the wrong tool. What works. + +**Comparison table.** When the choice is between 2-4 well-defined options with clear distinguishing features, a comparison table often serves better. The audience compares directly without going through questions. + +**Worked-example resource.** When the audience benefits from seeing how others in their situation chose, a 2-page worked-example resource often serves better than a quiz. The audience identifies which example matches them. + +**Calculator.** When the decision benefits from a calculation rather than a categorization, a calculator serves better. Detail in `calculator-design`. + +**Direct documentation.** When the audience prefers self-directed research, a clear documentation page about which option fits which situation often serves better than a quiz. + +The pattern. Many "we need a quiz" intuitions are actually "we need a clear way to communicate which option fits which audience." Often the simpler format works as well or better, at lower build cost. + +--- + +## When to retire a quiz + +Quizzes decay. Retiring them is part of the discipline. + +**Retire when:** + +- Lead volume has dropped below baseline for two consecutive quarters. +- The recommendation portfolio has shifted enough that the quiz routes to outdated recommendations. +- One segment now receives 80 percent of takers, suggesting the question architecture no longer distinguishes. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. Stale quizzes route audience to outdated recommendations and damage trust. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a quiz. The opportunity-cost frame. The recommendation-portfolio precondition. The decision worked example. When to choose a different format. The retirement discipline. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. The team's capacity benchmarks for build, maintenance, and recommendation curation. Specific tooling for quiz engineering and integration. Specific recommendation portfolios per segment. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/result-categorization-patterns.md b/skills/quiz-and-assessment-design/references/result-categorization-patterns.md new file mode 100644 index 0000000..f9e74d7 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/result-categorization-patterns.md @@ -0,0 +1,233 @@ +# Result categorization patterns + +Segment count, naming, distinguishability, balance. The shape of the result categories that the quiz produces. + +The categorization is the quiz's segmentation product. Bad categorization produces results that feel arbitrary or that fail to help the audience act. Good categorization produces results the audience recognizes and uses. + +--- + +## Segment count + +Most quizzes work well with 4-8 result categories. + +**Fewer than 4 segments.** The categorization feels coarse. Two-segment quizzes (e.g., "is this for you, yes or no") rarely earn the quiz format; a comparison or qualifying form serves better. + +**4-6 segments.** The sweet spot for most quizzes. Enough segments to feel nuanced; few enough that each gets adequate development. + +**7-8 segments.** Acceptable when the segmentation is genuinely multi-dimensional. Each segment needs a distinct description, distinct recommendation, and clear distinguishability. + +**9+ segments.** Often a sign of over-segmentation. Many segments end up similar in description and recommendation; the segmentation becomes fake. + +--- + +## Segment naming + +Memorable. Specific. Honest. Brand-voice consistent. + +**Memorable.** The taker should be able to describe their segment to a friend. "The Strategic Planner" is memorable; "Type 3" is not. + +**Specific.** Names should distinguish the segment from others. + +- Specific: "The Hands-On Builder" (vs "Type B") +- Specific: "Solo founder just starting" (vs "Beginner") +- Specific: "Mid-market operator with multiple sales reps" (vs "Mid-tier user") + +**Honest.** Names should not flatter universally. Some segments are more flattering than others; honest segmentation reflects this. + +- Honest: "Just exploring" alongside "Already executing" alongside "Mature operator." Each describes a real position. +- Dishonest: every segment named with a flattering descriptor regardless of where the taker actually is. + +**Brand-voice consistent.** The names should sound like the brand the quiz represents. A serious brand uses serious names; a playful brand can use playful names. Consistency matters. + +--- + +## Segment distinguishability + +Each segment should be meaningfully different from the others. + +**The test.** Read the descriptions of two adjacent segments. Are they meaningfully different in: +- Who the segment describes? +- What the segment's situation is? +- What the segment's recommendation is? + +If yes, the segments are distinguished. If no (the descriptions are similar, the recommendations overlap), the segmentation is fake. + +**The fake-segmentation pattern.** A quiz produces 5 segments, but segments 2, 3, and 4 are described in similar terms with similar recommendations. The audience that lands in different segments gets indistinguishable results; the segmentation is decorative. + +**The cure.** Either reduce the segment count (if the segmentation does not support 5 segments, do not pretend it does) or strengthen the distinctions (rewrite descriptions and recommendations so each segment is distinct). + +--- + +## Segment balance + +Each segment should receive a meaningful share of takers. + +**Balanced segmentation.** Each segment receives roughly 10-30 percent of takers (depending on segment count). The audience is genuinely distributed across segments. + +**Imbalanced segmentation.** One segment receives 70+ percent of takers; another receives less than 5 percent. The segmentation is not working; the questions do not distinguish meaningfully. + +**Why balance matters.** + +- Imbalance signals the segmentation is broken. +- The unused segments waste design and copy effort. +- The dominant segment becomes a default that does not really categorize anyone. + +**The cure.** Audit the question architecture (`references/question-architecture-patterns.md`). Often the questions do not produce balanced segmentation because they bias toward one segment. Adjust questions or weights to produce more even distribution. + +**The exception.** Some quizzes intentionally produce imbalanced segmentation because the audience genuinely skews. A "what is your team size" quiz may produce 60 percent "small team" because the audience is mostly small teams. Honest imbalance reflecting real audience composition is fine; imbalance from broken questions is not. + +--- + +## Segment description + +What appears at the result, beyond the segment name. + +**The description should include:** + +- A 2-3 sentence summary of the segment (who they are, what their situation is). +- Specific characteristics the audience will recognize. +- The matched recommendation (what to do next). +- Optional: case study or worked example of someone in this segment. + +**Example segment description.** + +``` +Segment: "The Mid-Market Operator" + +You are running a sales team of 5-25 people across multiple +products or regions. You have a defined sales process but +inconsistent execution; some reps follow it, others freelance. +Your top priority is unifying the team's process without +slowing your fastest performers. + +Recommendation: Our Growth plan with the multi-region +playbook configuration. We have a 30-day onboarding path +for teams in your situation. + +[Link to PDF: see how 3 mid-market operators implemented +this and the results] +``` + +The description is specific. The recommendation is matched. The next step is clear. + +**Description antipatterns.** + +- Generic descriptions that could fit multiple segments. +- Flattering descriptions with no honest characterization. +- Descriptions that describe but do not recommend. +- Recommendations that are the same across segments. + +--- + +## Segment naming patterns + +Common patterns and their tradeoffs. + +**Pattern A: Role-based names.** "The Strategic Planner," "The Hands-On Builder." Useful when segments correspond to functional roles. + +**Pattern B: Maturity-based names.** "Just Starting," "Growing," "Mature." Useful when segments correspond to stages of development. + +**Pattern C: Style-based names.** "The Optimizer," "The Connector," "The Visionary." Common in personality assessments. Risk of feeling horoscope-like. + +**Pattern D: Situation-based names.** "Solo founder pre-launch," "Mid-market operator with multi-region team." Useful when segments correspond to specific situations the audience recognizes. + +**Pattern E: Outcome-based names.** "Cost-focused buyer," "Time-saver-focused buyer." Useful when segments correspond to what the buyer is optimizing for. + +The pattern choice depends on the quiz's purpose and the audience the brand serves. The discipline is that whatever pattern is chosen, names should be specific and honest. + +--- + +## Result-page composition + +What the result page contains beyond the segment description. + +**The standard structure.** + +- The segment name and key visual. +- The segment description (2-3 sentences). +- The matched recommendation. +- The clear next step (CTA: download PDF, talk to team, explore product). +- Optional: comparison to other segments (so the taker sees the full picture). +- Optional: share button (if the quiz is shareable). + +**The clear-next-step principle.** Every result page must include a specific next step. Without it, the quiz produces awareness without action. + +**The optional comparison.** Showing the other segments lets the taker see the full segmentation. Useful when the audience benefits from understanding where they sit; less useful when the segments would distract from the matched recommendation. + +--- + +## Result-page mobile design + +The result page must work on mobile. + +**Mobile considerations.** + +- Segment name and recommendation visible without scroll. +- Visual elements sized for mobile screens. +- CTA button large and prominent. +- Share buttons functional on mobile platforms. + +**Common mobile failures.** + +- Result hidden below the fold; user does not know it loaded. +- Recommendation buried after a long scroll. +- CTA button tiny or hard to tap. + +--- + +## Segment maintenance + +Segments decay along with the quiz. + +**What decays.** + +- Segment descriptions that no longer match the audience composition. +- Recommendations that point to retired products or content. +- Brand voice that has shifted. + +**Maintenance cadence.** Quarterly review of segment descriptions and recommendations. Update as the recommendation portfolio evolves. + +**The retire-segment decision.** A segment that receives less than 3 percent of takers consistently may not warrant maintenance. Either restructure the segmentation to merge underused segments or accept that the segmentation has segments that exist but are rarely produced. + +--- + +## The segmentation-recommendation alignment audit + +Periodically verify that each segment's recommendation still matches. + +**The audit.** For each segment: +- Does the recommendation still exist (not pointing to a retired product)? +- Does the recommendation still match the segment's situation? +- Does the recommendation deliver value to that specific segment? + +**The drift.** Recommendations decay. Products are retired, content is updated, the brand evolves. Audit cadence catches the drift. + +--- + +## Common categorization failures + +**Too few segments.** Categorization feels coarse; quiz earns no segmentation value. + +**Too many segments.** Over-segmentation; segments end up similar; categorization feels fake. + +**Generic segment names.** Names that could apply to multiple segments; not memorable. + +**Flattering-everyone descriptions.** No honest segmentation; all segments feel positive. + +**Indistinguishable segments.** Two segments that read the same; categorization is decorative. + +**Imbalanced distribution.** One segment dominates; segmentation is broken. + +**Result without recommendation.** Description but no next step; quiz produces awareness without action. + +**Recommendations all the same.** Different segments routed to the same product or path; segmentation is decorative. + +--- + +## Methodology-level choices that stay in the public skill + +Segment count guidance. Naming patterns and discipline (memorable, specific, honest, brand-voice consistent). Distinguishability test. Balance principle. Segment description structure. Naming patterns A through E. Result-page composition. Mobile design. Segment maintenance. Segmentation-recommendation alignment audit. Common failures. + +## Implementation choices that stay internal + +Specific segment names for specific quizzes. Specific descriptions in brand voice. Specific recommendations matched to segments. Specific result-page layouts. The team's audit calendars. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md b/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md new file mode 100644 index 0000000..e94131f --- /dev/null +++ b/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md @@ -0,0 +1,255 @@ +# Result-to-recommendation mapping + +The action attached to each category. Mapping discipline and worked examples. The recommendation is what the taker does next; without it, the quiz produces awareness without action. + +The mapping is where the quiz earns its conversion. A great segmentation produces nothing if each segment lacks a matched, actionable recommendation. + +--- + +## The mapping principle + +Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +**The principle's three requirements.** + +- The recommendation is real (the brand actually offers the recommended next step). +- The recommendation matches the segment specifically (no two segments share the same recommendation). +- The recommendation is valuable to that specific segment (not a generic offer applied to everyone). + +Quizzes that hit all three produce action. Quizzes that miss any of the three produce vanity-result patterns. + +--- + +## What a recommendation can be + +The next step the taker should take. Many forms. + +**Product or service.** "Solo founders benefit most from our Starter plan with the founder-led onboarding path." The recommendation is a specific tier or configuration matched to the segment. + +**Content or resource.** "Mid-market operators benefit most from our 30-day playbook for unifying multi-rep teams." The recommendation is a specific resource matched to the segment. + +**Conversation or consultation.** "Enterprise buyers benefit most from a 30-minute conversation with our team." The recommendation is a specific human touchpoint. + +**Path or sequence.** "Creators just starting benefit most from our 4-part onboarding sequence." The recommendation is a structured next experience. + +**Configuration or setup.** "Teams using Salesforce benefit most from our integration setup wizard." The recommendation is a specific technical configuration. + +The form depends on the brand's offerings and the segment's situation. The discipline is that the recommendation is specific, not generic. + +--- + +## The mapping discipline + +Each segment-to-recommendation mapping should pass these tests. + +**Test 1: Does the recommendation actually exist?** The brand currently offers it; it is not aspirational or in development. + +**Test 2: Does the recommendation match the segment specifically?** Other segments would not benefit from this recommendation as much; the matching is real. + +**Test 3: Does the recommendation deliver value to this segment?** The segment that gets this recommendation can act on it and benefit from it. + +**Test 4: Is the recommendation deliverable?** The brand can provide what is being recommended in the timeframe and form the taker expects. + +**Test 5: Does the recommendation include a clear action?** The taker knows what to do (click here, start here, talk to someone, download this). + +When all five pass, the mapping is honest. When any fails, the mapping is decorative or misleading. + +--- + +## Worked example: B2B SaaS pricing quiz + +A SaaS platform offering 4 plan tiers with industry-specific configurations. + +**Segments and recommendations.** + +**Segment 1: "Solo founder just starting"** +- Description: 1-person team, exploring options, pre-revenue or early revenue. +- Recommendation: Starter plan ($X / month) with the founder-led onboarding path. Free for first 30 days; no credit card required. +- Action: "Start your 30-day trial." Direct link to signup pre-filled with the recommended plan. + +**Segment 2: "Growing team without CRM"** +- Description: 2-15 people, no CRM today, sales process is informal but starting to need structure. +- Recommendation: Growth plan ($Y / month) with the team-onboarding path. 30-day setup support included. +- Action: "Talk to our team about your setup." Calendar booking link. + +**Segment 3: "Mid-market with multiple reps"** +- Description: 16-100 people, multiple sales reps, defined process but inconsistent execution. +- Recommendation: Business plan ($Z / month) with multi-rep configuration and 60-day implementation support. +- Action: "Get a custom demo." Form for demo request. + +**Segment 4: "Enterprise with complex sales cycles"** +- Description: 100+ people, multi-stage sales process, integration-heavy environment. +- Recommendation: Enterprise plan (custom pricing) with dedicated implementation manager. +- Action: "Talk to enterprise sales." Direct line to enterprise contact. + +**Segment 5: "Integration-heavy team"** +- Description: Any size, but the primary need is integrating with their existing tool stack. +- Recommendation: Any plan plus the integration setup wizard. Detailed integration documentation linked. +- Action: "Explore our integrations." Integration catalog page. + +Each segment maps to a distinct, specific recommendation. Each recommendation includes a clear action. + +--- + +## Worked example: content-marketing quiz + +A content-marketing brand offering multiple content paths. + +**Segments and recommendations.** + +**Segment 1: "Just starting in content"** +- Recommendation: 4-part email course covering content fundamentals. +- Action: "Get the 4-part course." Signup form. + +**Segment 2: "Producing content but inconsistent results"** +- Recommendation: Content audit template + worked-example case study. +- Action: "Download the audit template." Direct download. + +**Segment 3: "Scaling a content team"** +- Recommendation: Team-management playbook + interview with a content director. +- Action: "Read the playbook." Resource page with playbook and interview. + +**Segment 4: "Optimizing for distribution"** +- Recommendation: Distribution-strategy framework + 5 worked examples. +- Action: "Read the framework." Resource page. + +Each segment routes to a distinct content path matched to where the audience is. + +--- + +## Worked example: readiness-assessment quiz + +A consultancy offering readiness assessments before engagement. + +**Segments and recommendations.** + +**Segment 1: "Not yet ready"** +- Description: Foundation work needed before the consultancy's offering would help. +- Recommendation: Self-serve resources for foundation work. Honest acknowledgment that engagement is not warranted yet. +- Action: "Explore the foundation library." Free resources. + +**Segment 2: "Ready for assessment"** +- Description: Foundation in place; specific gaps need addressing. +- Recommendation: 60-minute assessment call to identify specific engagement scope. +- Action: "Book the assessment call." Calendar link. + +**Segment 3: "Ready for full engagement"** +- Description: Foundation in place; clear gaps; ready to engage. +- Recommendation: Direct engagement conversation. +- Action: "Talk to our partner." Direct contact. + +**Segment 4: "Ongoing support"** +- Description: Already engaged, looking for continued partnership. +- Recommendation: Continuity-engagement options. +- Action: "Discuss your next phase." Direct contact. + +The honest segmentation includes a "not yet ready" segment. This is honest and earns trust; not every taker should be sold to immediately. + +--- + +## The "not for you" segment + +Honest segmentation sometimes includes a segment that is not the brand's audience. + +**The pattern.** A segment for takers who are not a fit. The recommendation acknowledges the lack of fit and offers something useful (a referral, a different brand's resource, a self-serve path). + +**Why it works.** + +- The taker who would have churned anyway leaves with respect for the brand. +- The brand earns "honest" reputation that compounds across audience segments. +- The unfit taker may refer fit takers later. + +**The dishonest alternative.** Pretending every taker is a fit; routing everyone to a sales contact regardless of segment. Audiences that catch the dishonesty disengage. + +--- + +## Recommendation freshness + +Recommendations decay; the mapping needs maintenance. + +**What decays.** + +- Recommendations pointing to retired products. +- Recommendations referencing outdated pricing or features. +- Recommendations linking to broken pages or moved resources. +- Recommendations that no longer match the brand's strategic priorities. + +**Maintenance cadence.** Quarterly review of every active recommendation. Update or replace as the brand's portfolio evolves. + +**The drift indicator.** Sales-team feedback that quiz-sourced leads are landing on the wrong recommendation. The mapping has drifted; refresh. + +--- + +## Recommendation testing + +Test the recommendations as part of quiz launch and updates. + +**Click-through testing.** What percentage of takers in each segment click the recommendation's CTA? Low click-through suggests the recommendation does not feel matched. + +**Conversion testing.** What percentage of takers in each segment complete the recommended action (sign up, book a call, download the resource)? Low conversion suggests the recommendation does not deliver expected value. + +**Feedback testing.** Direct user feedback ("does this recommendation feel right for you?"). Useful for early validation; rarely scalable. + +--- + +## The recommendation-as-CTA discipline + +The recommendation is also the call to action. + +**The pattern.** The recommendation includes a specific button or link that takes the taker to the next step. + +**Specific CTAs.** + +- "Start your 30-day trial" (specific action, specific timeframe). +- "Book a 30-minute assessment call" (specific format, specific duration). +- "Download the audit template" (specific deliverable). + +**Generic CTAs to avoid.** + +- "Learn more" (about what?). +- "Get started" (started doing what?). +- "Click here" (no value statement). + +The recommendation deserves a specific CTA matched to the action. + +--- + +## Multi-recommendation results + +Some quizzes produce multiple recommendations per segment. + +**The pattern.** The result includes a primary recommendation and one or more secondary recommendations. + +**When this works.** When the segment genuinely benefits from multiple paths (e.g., "you can start with X, or if you have specific need Y, consider Z instead"). + +**When this fails.** When multiple recommendations dilute the call to action; the taker does not know which to choose. + +**The discipline.** Default to one primary recommendation. Add secondary recommendations only when the segment genuinely benefits from a choice. + +--- + +## Common mapping failures + +**Same recommendation across segments.** Different segments route to the same product or path; segmentation is decorative. + +**Generic recommendations.** "Talk to our team" for every segment without segment-specific framing. + +**Aspirational recommendations.** Recommendations for products or services not yet available; the taker tries the action and hits dead ends. + +**Mismatched recommendations.** Recommendation does not match the segment's situation; takers feel unheard. + +**Buried recommendations.** Recommendation appears 3 emails after the result rather than in the result itself. + +**No clear CTA.** Recommendation describes what to do without providing the link or button to do it. + +**No "not for you" segment.** Every taker routed toward sales; the audience that does not fit is treated as fitting; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle and three requirements. Forms a recommendation can take. The mapping discipline (5 tests). Worked examples across quiz types. The "not for you" segment. Recommendation freshness. Recommendation testing. Recommendation-as-CTA discipline. Multi-recommendation results. Common failures. + +## Implementation choices that stay internal + +Specific segment-to-recommendation mappings for specific quizzes. Specific recommendation copy and CTAs in brand voice. Specific tracking for click-through and conversion per recommendation. The team's quarterly mapping audit calendar. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md b/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md new file mode 100644 index 0000000..31c9328 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md @@ -0,0 +1,284 @@ +# Scoring algorithm patterns + +Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. The math that turns answers into a segment. + +The scoring algorithm is the bridge from question answers to result categorization. The right algorithm produces meaningful segments; the wrong algorithm produces results that do not match audience self-perception. + +--- + +## Pattern A: Direct mapping + +Each answer corresponds directly to a segment. The dominant answer choice determines the result. + +**How it works.** + +- Each question's answer choices map to specific segments. +- Each answer adds 1 point (or fixed weight) to its corresponding segment. +- The segment with the most points wins. + +**Example.** + +Question: "What size is your team?" +- 1-5 → "Solo" (+1) +- 6-25 → "Growing" (+1) +- 26-100 → "Mid-market" (+1) +- 100+ → "Enterprise" (+1) + +After all questions, the segment with the highest count wins. + +**Strengths.** + +- Simple, transparent, easy to explain. +- Easy to maintain (changes are obvious in their effect). +- The scoring logic can be displayed to the audience without confusion. + +**Weaknesses.** + +- Limited nuance; one answer cannot contribute to multiple segments meaningfully. +- Risk of ties when multiple segments score equally. + +**When to use.** When segments are well-defined and questions clearly distinguish them. The default starting point for many quizzes. + +--- + +## Pattern B: Weighted scoring + +Each answer adds points (with weights) to one or more segments. The highest-scoring segment wins. + +**How it works.** + +- Each question's answer choices add weighted points to one or more segments. +- An answer might add 3 points to segment A and 1 point to segment B. +- After all questions, the segment with the highest total score wins. + +**Example.** + +Question: "What is your sales process maturity?" +- "Founder-led, no defined process" → "Solo" (+3), "Growing" (+1) +- "Some defined steps" → "Growing" (+3), "Mid-market" (+1) +- "Defined sales playbook" → "Mid-market" (+3), "Enterprise" (+1) +- "Multi-stage enterprise process" → "Enterprise" (+4) + +This question is more central to segmentation, so its weights are higher. + +**Strengths.** + +- Allows nuance; one answer can contribute to multiple segments. +- Different questions can have different importance through their weights. +- Reduces tie likelihood by spreading weights. + +**Weaknesses.** + +- Less transparent (audience cannot easily reverse-engineer the result). +- More complex to maintain (changes to weights have non-obvious effects). +- Easy to bias accidentally if weights are not audited. + +**When to use.** When segmentation needs nuance, when some questions are more important than others, when the segmentation is multi-attribute. + +--- + +## Pattern C: Multi-dimensional + +The quiz produces scores across multiple axes. The result combines the scores into a 2D or 3D segment. + +**How it works.** + +- The quiz captures scores across 2-3 distinct dimensions (e.g., introvert/extrovert AND analytical/intuitive). +- The result is determined by the position on each dimension (introvert + analytical = one quadrant; extrovert + intuitive = another). +- Common in personality assessments, fit-evaluations, and any segmentation that is genuinely multi-axis. + +**Example.** + +A 2-dimensional quiz might score: +- Dimension 1: technical depth (low to high) +- Dimension 2: collaboration preference (solo to team) + +Result quadrants: +- High technical, solo → "Solo specialist" +- High technical, team → "Team specialist" +- Low technical, solo → "Solo generalist" +- Low technical, team → "Team generalist" + +**Strengths.** + +- Captures genuine multi-dimensional segmentation. +- Produces results that feel nuanced and accurate. +- Allows for richer recommendations matched to the dimensional combination. + +**Weaknesses.** + +- Significantly more complex than single-axis scoring. +- Larger result-set to design and maintain (4 quadrants from 2 dimensions; 8 from 3 dimensions). +- Harder for the audience to predict their result before taking. + +**When to use.** When segmentation is genuinely multi-axis (personality, fit-evaluation, learning style, decision-making style). + +--- + +## Pattern D: Branching logic + +The next question depends on the previous answer. Allows for adaptive questioning. + +**How it works.** + +- The quiz starts with a few common questions. +- Based on early answers, the quiz routes to different question sets. +- Different paths through the quiz produce different results. + +**Example.** + +Question 1: "Do you currently use a CRM?" +- Yes → branch A (questions about current CRM, satisfaction, gaps) +- No → branch B (questions about why not, what would change, current process) + +The two branches produce different question sets that map to different segments. + +**Strengths.** + +- Adaptive; questions feel relevant to the taker. +- Can produce highly specific segmentation. +- Reduces irrelevant questions for any one taker. + +**Weaknesses.** + +- Significantly more complex to build and test. +- Harder to compare segments because not all takers answered the same questions. +- Maintenance is harder; changes to one branch can affect overall scoring. + +**When to use.** When later questions make sense only in the context of earlier ones, when the audience genuinely needs different questions based on their initial situation. + +--- + +## Choice criteria + +Which pattern fits which quiz. + +**Use direct mapping when:** + +- Segments are well-defined and clearly distinguished. +- Each question maps cleanly to one segment. +- Transparency matters (audience benefits from being able to reason about their result). + +**Use weighted scoring when:** + +- Segmentation needs nuance. +- Some questions are more central to segmentation than others. +- Most answers contribute to multiple segments meaningfully. + +**Use multi-dimensional when:** + +- Segmentation is genuinely multi-axis. +- The audience expects a richly textured result (personality assessments, learning styles). +- Each dimension can be measured by a coherent subset of questions. + +**Use branching when:** + +- Later questions depend on earlier context. +- The audience genuinely splits into distinct groups that need different question sets. +- The maintenance complexity is justified by the segmentation value. + +The simplest pattern that produces the right segmentation is usually the best choice. Complexity has cost; only spend it where it produces value. + +--- + +## Tie-breaking + +What happens when two segments score equally. + +**Pattern A: First-tied-segment wins.** The segment that reached the top score first (in the order segments are evaluated) wins. Simple but can introduce bias if the order is not deliberate. + +**Pattern B: Tie-breaker question.** A specific question whose answer breaks the tie. Useful when ties are common. + +**Pattern C: Combined-segment result.** A result for the tie itself ("You are between segment A and segment B"). Useful when the tie is genuinely meaningful. + +**Pattern D: Re-prompt or randomize.** Ask one more clarifying question to break the tie. Adds friction but produces a definitive result. + +**The choice.** Depends on how often ties occur and how meaningful the distinction between tied segments is. If ties are rare and the segments are similar, Pattern A is fine. If ties are common and the segments differ significantly, Pattern B or C is warranted. + +--- + +## Edge-case handling + +What happens at the boundaries of the scoring. + +**The all-segments-zero edge case.** A taker answers in a way that gives zero points to every segment. Rare but possible. Default to the most common segment, or surface a "we could not categorize you" message that prompts re-engagement. + +**The very-high-single-segment edge case.** A taker scores extremely high on one segment, far above any other. Often signals strong segmentation; the result is reliable. + +**The all-segments-equal edge case.** A taker scores equally across all segments. Often signals the questions did not distinguish; the result is unreliable. May warrant a different question set or a different recommendation flow. + +**The contradictory-answers edge case.** A taker's answers contradict each other in ways the scoring did not anticipate. Often surfaces in audit; the question set may need clarification. + +--- + +## Scoring transparency to the user + +Whether to show the score during or after the quiz. + +**Show the score.** When the dimensions or score are themselves meaningful to the user (personality assessments often benefit from showing dimensional scores). + +**Hide the score.** When the score is implementation detail and the segment is the meaningful output (most recommendation quizzes hide the score). + +**Hybrid.** Show segment + a brief explanation of how it was determined. "Your result is X. The questions that most influenced this were Y and Z." + +The choice depends on whether the score helps the user understand or distract from the result. + +--- + +## Algorithm decay + +Scoring algorithms decay along with quizzes. + +**What decays.** + +- Question weights that no longer reflect the segmentation reality. +- Segments that have shifted in audience composition. +- Edge cases that have become more common. + +**Maintenance cadence.** Quarterly review of the scoring algorithm. Audit a sample of takers to confirm results match expectations. + +**Drift indicators.** + +- One segment receiving 70+ percent of takers. +- Audience comments that the result feels wrong. +- Sales-team feedback that quiz-sourced leads are misclassified. + +--- + +## Algorithm testing + +Test the scoring algorithm before launch and after changes. + +**Persona testing.** Create personas representing each intended segment. Take the quiz as each persona; verify each persona reaches the intended segment. + +**Edge-case testing.** Try answer combinations that should produce ties, contradictions, or boundary conditions. Verify the algorithm handles them gracefully. + +**Volume testing.** Run the quiz with synthetic data simulating expected audience composition. Verify segment distribution matches expectations. + +**Production monitoring.** Track segment distribution over time. Sudden shifts may indicate question or scoring issues. + +--- + +## Common scoring failures + +**Algorithm too simple for the segmentation.** Direct mapping when weighted scoring is needed; segments end up poorly distinguished. + +**Algorithm too complex for the segmentation.** Multi-dimensional when single-axis would have served; complexity without value. + +**Hidden bias in weights.** Weights that systematically favor one segment regardless of true audience composition. + +**Tie-breaking arbitrary.** Ties resolved in inconsistent or biased ways. + +**No production monitoring.** Algorithm drifts unnoticed; segment distribution becomes skewed. + +**Scoring not documented.** Future maintainers cannot reason about the algorithm; changes break in unexpected ways. + +--- + +## Methodology-level choices that stay in the public skill + +The four scoring patterns with how-it-works, strengths, weaknesses, and when-to-use guidance. Choice criteria. Tie-breaking patterns. Edge-case handling. Scoring transparency. Algorithm decay and maintenance. Algorithm testing. Common failures. + +## Implementation choices that stay internal + +Specific scoring algorithms for specific quizzes. Specific weights and segment mappings. Specific testing personas. Specific tooling for algorithm implementation and monitoring. These vary by team. diff --git a/skills/roadmap-planning/SKILL.md b/skills/roadmap-planning/SKILL.md new file mode 100644 index 0000000..ba9cc5e --- /dev/null +++ b/skills/roadmap-planning/SKILL.md @@ -0,0 +1,228 @@ +--- +name: roadmap-planning +description: "Build a multi-quarter roadmap from a backlog of ideas, requests, and ongoing initiatives. Use this skill when planning the next quarter, sequencing dependent work, balancing build vs improve vs maintain, or making the case for what NOT to do. Triggers on roadmap, quarterly planning, what should we build next, sequencing, prioritization, OKR planning, capacity planning, what's on the roadmap, plan the year, what to ship next quarter. Also triggers when stakeholders are pulling in different directions and the team needs a defensible plan." +category: product +catalog_summary: "Quarterly planning, prioritization, dependency mapping" +display_order: 2 +--- + +# Roadmap Planning + +Take a pile of ideas, requests, and ongoing work. Produce a defensible plan for what to ship, when, and why. The output is a roadmap document plus the prioritization work that made it credible. + +--- + +## When to use + +- Planning the next quarter or the next year +- Sequencing work where some items depend on others +- Balancing new builds, improvements, and maintenance +- Saying no (or "not yet") to specific requests with a defensible reason +- Aligning a team around a single shared plan +- Communicating the plan to stakeholders outside the team +- Replanning after a strategy shift, a missed quarter, or new constraints + +## When NOT to use + +- Specifying a single feature for development (use `pm-spec-writing`) +- Validating whether the idea is worth building (use `ux-research`) +- Designing the feature itself (use `design-standards`) +- Writing the launch plan for a single initiative (use `launch-runbook`) +- Reviewing what shipped vs what was promised (use `after-action-report`) + +--- + +## Required inputs + +- The team's strategy or top-level goals (1 to 5 OKRs, themes, or pillars) +- The backlog: every candidate item, with at least a one-sentence description +- The team's capacity (people × time) +- Known constraints (deadlines, dependencies, hiring, budget) +- The planning horizon (a quarter, two quarters, a year) + +If the strategy is missing, the roadmap will be a list of features, not a plan. Push back and get the strategy first. A roadmap without strategy is just a queue. + +--- + +## The framework: 5 layers + +Roadmaps fail at five different layers. A roadmap is only as good as its weakest one. + +### Layer 1: Themes (the WHY) + +Top-level groupings tied to strategy. Every theme answers: "If we do nothing else this period, this is the outcome we want." + +Good themes are: +- Outcome-shaped, not feature-shaped ("Reduce time-to-first-value" beats "Build onboarding") +- Limited (3 to 5 max) +- Defensible (you can explain why this and not something else) +- Measurable (each maps to one or two metrics) + +Bad themes look like a junk drawer: "Improvements," "Tech debt," "Misc." If it can't be defended in one sentence, it isn't a theme. + +### Layer 2: Initiatives (the WHAT) + +Multi-week or multi-month efforts that ladder up to a theme. Each initiative is bigger than a feature but smaller than a theme. Initiatives have: + +- A clear outcome (the metric or result it should produce) +- A rough size (S / M / L / XL) +- A confidence rating (how sure are we this is the right initiative?) +- A dependency map (what has to happen first) + +Initiatives are where stakeholders push hard. Resist the urge to commit to dates here. Commit to outcomes and rough sizes. + +### Layer 3: Sequencing (the WHEN) + +The order things happen. Sequencing is constrained by: + +- **Dependencies** (X must finish before Y can start) +- **Capacity** (the team can do N things at once) +- **Calendar reality** (Q4 has fewer working days, certain teams have hiring gaps) +- **Strategic windows** (some launches need to land before a season, conference, or competitive moment) + +Build the sequence after the prioritization. Putting things in time-order before deciding what matters produces a plan optimized for calendar fit, not impact. + +### Layer 4: Capacity reality (the HOW MUCH) + +Most roadmaps fail here. The plan looks good on paper but assumes 100% of every person's time on roadmap work. Real capacity is much lower. + +Default capacity assumptions: + +- Engineers: 60-70% of time on roadmap initiatives. The rest is meetings, reviews, on-call, support, interviews, debugging, ramp-up. +- Designers: 50-60%. Same reasons plus more cross-team support. +- PMs: 40-50%. The rest is planning, comms, stakeholder management, async writing. +- New hires: assume 50% of full capacity for the first quarter, 75% for the second, 100% from Q3 on. +- On-call rotations, leave, holidays: subtract before sizing. + +If the math says the plan needs 100% of the team, the plan is wrong. Cut. + +### Layer 5: Trade-off communication (the WHY NOT) + +Every roadmap has a "Not now" list as important as the "Doing" list. The "Not now" is what makes the plan defensible. + +Include: +- The top requests you considered and rejected +- The reason for each rejection (not the right time, not the right size, conflicts with theme, lower expected impact) +- The condition that would make it move into "Doing" (a metric, a date, a finished prerequisite) + +Stakeholders pushing for cut items can argue against the rejection criteria, not the omission. That's a productive argument. + +--- + +## Workflow + +### Step 1: Anchor the strategy + +Before touching the backlog, write down 3 to 5 themes. If the team's OKRs or strategy doc gives you these, copy them. If not, draft them and validate with the people who own strategy. + +If the strategy is missing or vague, stop. Producing a roadmap against an unclear strategy is worse than producing nothing. Surface the gap. + +### Step 2: Catalog the backlog + +Every candidate gets: +- Name (one phrase) +- Theme it ladders up to (or "no theme" - flag for later) +- Source (request, OKR, retro, customer feedback, leadership ask, technical need) +- Rough size (S / M / L / XL) +- Owner or proposed owner +- Status (idea, validated, scoped, ready) + +Items with "no theme" are warning flags. Either the theme list is incomplete, or the item should be cut. + +### Step 3: Prioritize within each theme + +Inside each theme, rank the initiatives. Use one prioritization framework consistently. Common ones: + +- **RICE** (Reach × Impact × Confidence ÷ Effort): good for feature-heavy roadmaps +- **MoSCoW** (Must / Should / Could / Won't): good for fixed-deadline projects +- **Kano** (Threshold / Performance / Excitement): good for product investment decisions +- **Cost of delay**: good when timing matters more than effort +- **Strategic alignment + impact**: good for executive-facing roadmaps + +The framework matters less than the consistency. Pick one. Use it the same way for every initiative. Document the math. + +See [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) for the full breakdown. + +### Step 4: Build the dependency map + +For every "Doing" initiative, list what must happen first: +- Other initiatives +- Hiring +- External dependencies (vendor delivery, partner readiness) +- Research or validation work +- Infrastructure or platform readiness + +Visualize as a graph or a Gantt-style sequence. Items with no dependencies can start immediately. Items with multiple unmet dependencies are warning flags. + +### Step 5: Lay out the sequence + +Now place initiatives in time. Use the dependency map. Use the capacity math. Match initiatives to people who can actually do them. + +Default cadence: month-by-month for one quarter, quarter-by-quarter beyond that. Weekly is too granular for most roadmaps. Half-year buckets are too vague to commit to. + +### Step 6: Validate with the team + +Before sharing externally, validate with the people doing the work: +- Are the size estimates realistic? +- Are the dependencies correctly mapped? +- Are the capacity assumptions accurate? +- Is anyone overcommitted? + +If the team says the plan is impossible, the plan is impossible. Adjust. Going to leadership with a plan the team disagrees with is how trust gets broken. + +### Step 7: Write the "Not now" list + +For every "Doing" item, name what got cut to make room. Document why. Document the trigger that would move it to "Doing" later. + +### Step 8: Communicate + +Different audiences need different views: + +- **Team:** detailed sequence, owners, dependencies, sizes +- **Cross-functional partners:** themes, initiatives, rough timing, what they need to provide +- **Leadership:** themes, expected outcomes, key initiatives, top trade-offs +- **Public or customer-facing:** themes, no specific dates, "what to expect" + +The same roadmap should produce all four. If it can't, the roadmap is incomplete. + +--- + +## Failure patterns + +**A list of features instead of a plan.** Themes are missing. The roadmap is a backlog with months attached. Fix: start over from strategy. + +**Date-driven thinking.** "What can we ship by end of Q2?" instead of "What is the most important thing to do in Q2?" Dates are constraints, not goals. + +**Capacity fantasy.** The plan adds up to 100% of every person's time. No room for support, interrupts, planning, or unknown unknowns. Roadmap dies in week three. + +**Stakeholder pressure overrides strategy.** A loud customer or executive request gets prioritized because they pushed hard, not because it ladders up. The "Not now" list saves you here. + +**Missing dependencies.** Initiative B depends on initiative A, but A is scheduled later. Or A depends on a hire that hasn't happened. The plan looks fine until execution starts. + +**Too far out.** Specific commitments six months out create promises the team can't keep. Use ranges or themes for far horizons, specifics for near horizons. + +**One framework for every level.** RICE for the whole roadmap including platform work, infra, and exploration. RICE is great for features, weak for foundational work. Use different lenses for different initiative types. + +**No "Not now."** Stakeholders rediscover their cut requests every two weeks because there's no record of why they were cut. Document once, point to it forever. + +--- + +## Output format + +The roadmap document includes: + +- **Strategy summary** (1 page or section): themes, why these themes, how they ladder to top-level goals +- **The plan** (the visual): a quarter-by-quarter or month-by-month view, color-coded by theme +- **Initiative briefs** (one per initiative): outcome, size, owner, dependencies, success metric +- **Capacity model**: who is doing what, with utilization math +- **Trade-offs and "Not now"**: top items considered and rejected, with reasons +- **Risks and assumptions**: what could derail the plan +- **Update cadence**: when the roadmap will be revisited (monthly is typical) + +The roadmap is a living document. Plan to revisit it monthly. Replan it formally each quarter. Do not treat it as a contract. + +--- + +## Reference files + +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Detailed breakdown of RICE, MoSCoW, Kano, Cost of Delay, and Strategic Alignment frameworks. When to use each, how to apply them, common mistakes. diff --git a/skills/roadmap-planning/references/prioritization-frameworks.md b/skills/roadmap-planning/references/prioritization-frameworks.md new file mode 100644 index 0000000..fead81c --- /dev/null +++ b/skills/roadmap-planning/references/prioritization-frameworks.md @@ -0,0 +1,192 @@ +# Prioritization Frameworks + +Five frameworks for prioritizing work. Each suits different problems. Pick one per planning cycle. Use it consistently. + +--- + +## RICE + +Best for: feature-heavy roadmaps where features are roughly comparable in shape. + +### The math + +``` +RICE Score = (Reach × Impact × Confidence) ÷ Effort +``` + +- **Reach:** how many people will this affect in a fixed period (e.g., users per quarter). Use real numbers, not relative scores. +- **Impact:** how much will it affect each person? Use a fixed scale: 3 (massive), 2 (high), 1 (medium), 0.5 (low), 0.25 (minimal). +- **Confidence:** how sure are you in the estimates? 100% (high), 80% (medium), 50% (low). Below 50%, you don't know enough to score. +- **Effort:** total person-months to deliver. Be honest. Include design, dev, QA, launch. + +Higher score = higher priority. + +### Where it shines + +Comparing many similarly-shaped feature ideas. Forces conversation about the inputs (Reach, Impact, Confidence) instead of a gut "I think this is more important." + +### Where it fails + +- Foundational work (infra, platform, refactors). Reach and Impact don't apply cleanly. +- Strategic bets where Confidence is low but the upside is huge. RICE punishes low-confidence work. +- "Cost of inaction" items (security, compliance). These often score badly but must ship. + +### Common mistakes + +- Inventing Reach numbers without a basis. If you don't have data, your Reach is a guess wrapped in math. +- Effort estimates that come from PMs, not engineers. Effort is always the engineer's call. +- Treating Impact as a continuous variable. The scale is fixed for a reason - so it's comparable. +- Re-scoring each cycle without checking what shipped last cycle and what its actual Reach × Impact turned out to be. + +--- + +## MoSCoW + +Best for: fixed-deadline projects where you have to decide what's in scope and what isn't. + +### The buckets + +- **Must have:** without these, the project fails. Non-negotiable for launch. +- **Should have:** important but not deal-breaking. Plan to include unless capacity tightens. +- **Could have:** nice to include if there's room. First to be cut. +- **Won't have (this time):** explicitly out of scope. Documented to prevent drift. + +### Where it shines + +Deadline-driven launches. New site builds. Migrations. Anything with a fixed go-live date. + +### Where it fails + +- Open-ended product work without a hard deadline. Everything tends to drift to "Must have." +- Long-running platforms. The buckets don't help sequence multi-quarter work. + +### Common mistakes + +- "Must have" creeping. By the end of planning, 80% of items are Must. Hard rule: "Must have" should be 30-50% of items, never more. +- No "Won't have." The "Won't have" list is the discipline. Without it, scope grows. +- Ambiguous lines between Must and Should. Define each explicitly. "If we ship without X, will the product work?" If yes, X is Should, not Must. + +--- + +## Kano + +Best for: product investment decisions about feature investment vs polish vs new bets. + +### The categories + +- **Threshold features:** users expect them. Their absence causes dissatisfaction. Their presence is barely noticed. (Examples: a working login. Email password reset.) +- **Performance features:** users notice them and value them linearly. More is better. (Examples: speed, search relevance, design quality.) +- **Excitement features:** users don't expect them. Their presence is delight. Their absence is unnoticed. (Examples: a clever zero state, an unexpected automation.) + +### How to use + +Audit the product. Categorize every feature. Decide where to invest: + +- Threshold features must be present and working. Underinvestment is a tax on everything else. +- Performance features should get sustained investment. They are how the product stays competitive. +- Excitement features are the differentiation budget. Spend selectively, expect them to age into Performance and eventually Threshold. + +### Where it shines + +Product strategy conversations. "Should we polish what we have or ship something new?" Kano answers it: are the Thresholds shipped? Then Performance. Then Excitement. + +### Where it fails + +- Doesn't help with sequencing among features in the same category. +- The categories shift over time. Today's Excitement is tomorrow's Threshold. + +### Common mistakes + +- Treating Excitement as the most valuable category. It's not. Threshold gaps will sink you faster than missing Excitement features. +- Confusing Excitement with novelty. Many "innovative" features are just Performance features in disguise. + +--- + +## Cost of Delay + +Best for: portfolios where timing matters more than effort, especially under capacity constraints. + +### The math + +``` +Cost of Delay per Week = Value Lost Per Week the Item Doesn't Ship +``` + +For each candidate, estimate: if we delay this by one week, what does it cost in revenue, retention, market position, or risk? + +Then divide by effort: + +``` +Cost of Delay Divided by Duration (CD3) = Cost of Delay per Week ÷ Duration in Weeks +``` + +The highest CD3 ships first. + +### Where it shines + +Sequencing inside a constrained team. Surfaces items where every week of delay matters (compliance deadlines, seasonal launches, competitive responses). + +### Where it fails + +- Estimating Cost of Delay is hard. Many items have qualitative cost ("brand damage," "team morale") that resists numerical estimates. +- Bias toward urgent over important. Recurring time-sensitive items (deadlines, customer escalations) keep beating strategic work. + +### Common mistakes + +- Treating all delays as having the same cost shape. Some items have flat cost (delay a week or a year, same outcome). Others have step changes (miss a deadline, lose 80% of the value). +- Ignoring the cost of NOT delaying (opportunity cost from working on this instead of something else). + +--- + +## Strategic Alignment + Impact + +Best for: executive-facing roadmaps and any planning where the question is "should we do this at all?" + +### The matrix + +A 2×2 grid: Strategic Alignment (low/high) on one axis, Impact (low/high) on the other. + +- **High alignment / High impact:** ship now. Resource heavily. +- **High alignment / Low impact:** ship if cheap. Question if expensive. +- **Low alignment / High impact:** dangerous. Either redefine strategy or cut. Items here drag the team away from the plan. +- **Low alignment / Low impact:** cut. Always. + +### Where it shines + +Cutting noise from the backlog. The bottom-right quadrant (Low/Low) is where most of the noise lives, and the matrix makes it obvious. + +Communicating with leadership. "This is high impact but not aligned" is a defensible reason to deprioritize. + +### Where it fails + +- Doesn't sequence within quadrants. Inside "High/High," you still need a tiebreaker. +- "Strategic alignment" is judgment, not math. Different people will plot the same item differently. + +### Common mistakes + +- Plotting everything as High/High to avoid the conversation. The matrix is only useful if there's a Low quadrant. +- Treating Strategic Alignment as fixed. Strategy changes. Re-plot every cycle. + +--- + +## Picking a framework + +| If your team is... | Use | +|---|---| +| Building features for a product, comparable in shape | RICE | +| Launching against a fixed deadline | MoSCoW | +| Deciding investment levels across product areas | Kano | +| Sequencing under capacity constraints with timing-sensitive items | Cost of Delay | +| Cutting noise and aligning with leadership | Strategic Alignment + Impact | + +You can use more than one in a single planning cycle, but apply each consistently within its scope. Don't switch frameworks halfway through to justify a pre-decided answer. + +--- + +## The meta-rule + +Every framework has known weaknesses. Every framework can be gamed by stakeholders who learn how the math works. + +The frameworks are conversation tools, not decision tools. Their value is forcing the team to articulate inputs (reach, impact, alignment, urgency) instead of arguing about outputs. + +A good roadmap can be defended without the framework. The framework is the work, not the result. diff --git a/skills/scheduler-and-booking-design/SKILL.md b/skills/scheduler-and-booking-design/SKILL.md new file mode 100644 index 0000000..1057df6 --- /dev/null +++ b/skills/scheduler-and-booking-design/SKILL.md @@ -0,0 +1,273 @@ +--- +name: scheduler-and-booking-design +description: "Designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic Calendly link. Availability logic, qualification gating, prep automation, follow-up sequencing. Honest about any-time-friction (no qualification, just a booking link), interrogation-gate (so much qualification it scares users off), and qualified-fast-path (just enough qualification to set up the call well) patterns. Triggers on scheduler design, meeting booking, demo scheduling, sales call scheduling, calendar tool, booking page, qualification flow. Also triggers when sales team complains about cold demos, when booking conversion is poor, or when scheduler is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing schedulers and booking flows. Distinguishes any-time-friction (no qualification, just a booking link) from interrogation-gate (so much qualification it scares users off) from qualified-fast-path (just enough qualification to set up the call well)" +display_order: 10 +--- + +# Scheduler and Booking Design + +A senior growth practitioner's playbook for designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic booking link. Availability logic, qualification gating, prep automation, follow-up sequencing. The discipline of building a scheduler that earns the booking by earning a better call. + +Most schedulers fail in one of two ways. Generic booking links produce cold demos where reps know nothing about the person they are about to talk to. Conversion stays at the rate of unqualified raw demos. Or qualification forms with 12 fields scare users off before they can book; drop-off at the form approaches 90 percent; only the leads who happen to survive the form actually convert. + +The schedulers that work do something different. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads route differently), prep automation that briefs the rep before the call. The booking is honest about who the audience is; the call is set up to succeed. + +The voice is the senior growth practitioner who has watched schedulers double demo conversion when redesigned and watched them collapse when more qualification was added. Practical, opinionated about which fields earn their place, willing to call out when the booking flow is the wrong tool. + +When to use this skill: scoping a scheduler for the first time, auditing a booking flow with poor conversion or poor downstream call quality, designing the qualification gate that produces context without producing friction, or deciding routing logic that matches leads to the right reps. + +--- + +## What this skill covers + +This skill spans meeting schedulers and booking experiences across acquisition and sales contexts. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access to anything). This skill is meeting-booking specifically; qualification fields exist but the goal is the call, not the data. +- `funnel-flow-architecture` is broader funnel architecture. This skill is the scheduler specifically. +- `lead-magnet-design` is different commitment level. Magnets earn an email; bookings earn time. +- **`scheduler-and-booking-design` (this skill)** is the qualification, availability, routing, prep automation, and follow-up sequencing for meetings. +- `pm-spec-writing` is the spec for engineers building the scheduler. + +The audience: growth marketers, product marketers, marketing operations leads, sales operations leads, agencies running booking optimization for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); broader funnel orchestration (covered by `funnel-flow-architecture`); the engineering implementation; specific Calendly/Cal.com/Chili Piper/SavvyCal platform configurations (those stay implementation-side). + +--- + +## The booking-flow decision: scheduler vs forms vs sales-pipeline tools + +Before designing the scheduler, decide whether a scheduler is the right tool. + +**Schedulers earn investment when:** + +- The conversion goal is a meeting (demo, sales call, consultation). Email-only conversions do not need a scheduler. +- The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. +- The team has enough sales or success capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. +- The team can support qualification logic and routing. Without these, a generic booking link is the result. + +**Schedulers do NOT earn investment when:** + +- The conversion goal is a download or signup. Use forms or magnet flows. +- The audience volume is too low for routing logic. A handful of bookings per month does not need infrastructure. +- The team's capacity is variable and routing cannot reflect that. Scheduling without capacity awareness produces no-shows on both sides. +- A simpler contact form would serve the same purpose. + +The decision is not "should we have a scheduler"; it is "is the scheduler the right next investment for this audience and goal." + +Detail in [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md). + +--- + +## Any-time-friction vs interrogation-gate vs qualified-fast-path + +The keystone framing. + +**Any-time-friction.** Generic booking link with no qualification, no context capture. Reps show up to calls cold; they spend the first 10 minutes asking the same qualification questions the form should have captured. Conversion stays at the rate of unqualified raw demos. Cost: sales capacity used inefficiently; high-fit leads get the same experience as low-fit leads; downstream conversion suffers. + +**Interrogation-gate.** Qualification form with 12 fields before the user can book. Drop-off at the form approaches 90 percent. The qualification works for the leads who survive but the system loses everyone else. Cost: high-fit leads who would have converted abandon at the form; conversion rate is poor even though the post-form leads are well-qualified. + +**Qualified-fast-path.** Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads see SDRs or are routed to async), prep automation that briefs the rep before the call. Cost: design effort upfront is significant; conversion plus downstream call quality both improve meaningfully. + +The litmus test. Does the rep arrive at the call already knowing the prospect's situation? Did the prospect feel respected by the booking experience? If yes to both, qualified-fast-path. If the rep starts cold, any-time-friction. If the prospect dropped at the form, interrogation-gate. + +--- + +## Qualification field design + +Which fields earn their place; which create friction. + +**The principle.** Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +**Strong qualification fields.** + +- **Company size or team size.** Routes to the right rep tier; enables enterprise vs SMB tracking. +- **Use case or primary goal.** Lets the rep prepare for the conversation that matches. +- **Current solution or stack.** Tells the rep where the prospect is starting. +- **Timeline or urgency.** Routes to active-pipeline vs nurture. +- **Role or job function.** Lets the rep tailor framing. + +**Weak qualification fields.** + +- **Phone number** (often unnecessary if email and meeting time are captured). +- **Generic comments box** (free-text; rarely informs prep). +- **Marketing data not used in the call** (industry codes, lead-source detail). +- **Demographic data unrelated to the call** (gender, age). + +**The five-field rule.** Most production schedulers work well with 3-5 qualification fields. More than 5 starts producing interrogation-gate dynamics. Less than 3 does not give the rep useful prep context. + +Detail in [`references/qualification-field-design.md`](references/qualification-field-design.md). + +--- + +## Availability logic + +Round-robin, weighted by fit, calendar integration. + +**Pattern A: Pure round-robin.** Bookings cycle through available reps in order. + +When to use. Simple distribution; small teams. + +Strengths. Even distribution; simple logic. + +Weaknesses. Does not match high-fit leads to senior reps; does not load-balance based on capacity. + +**Pattern B: Weighted round-robin.** Bookings cycle but weighted by rep performance, capacity, or specialty. + +When to use. Teams with rep specialization; teams where capacity differs. + +**Pattern C: Fit-based routing.** High-fit leads (large company, high urgency) route to senior reps; lower-fit leads route to SDRs or async resources. + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +**Pattern D: Hybrid.** Combines patterns. Fit-based routing for top tier; round-robin within tier. + +When to use. Most production teams. + +**The match-to-rep discipline.** The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +Detail in [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md). + +--- + +## Routing patterns + +Different reps for different lead types. + +**By company size.** SMB to SDRs, mid-market to AEs, enterprise to senior AEs. + +**By use case.** Different specialists for different product use cases. + +**By geography.** Different reps for different time zones or regions. + +**By language.** Native-language reps for non-English-primary leads. + +**By account ownership (B2B).** If the lead's company is already a customer or prospect of an AE, route to that AE. + +**The unrouted lead.** Some leads do not fit obvious routing. Default rule needed: round-robin or specific catchall. + +Detail in [`references/routing-patterns.md`](references/routing-patterns.md). + +--- + +## Prep automation + +Briefing the rep before the call. + +**The principle.** The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused. + +**Prep automation patterns.** + +- **CRM enrichment.** Qualification data populates the CRM record; rep sees it in their pre-call review. +- **Calendar invite enrichment.** Qualification data appears in the meeting invite description; rep sees it on their calendar. +- **Slack or email brief.** Pre-call brief sent to the rep with synthesized prospect info. +- **Account research.** Qualification data triggers automated research (company size verification, recent news). + +**Strong prep automation.** The rep arrives at the call already knowing: who the prospect is, what they are trying to accomplish, what they are using today, when they need a solution. + +**Weak prep automation.** The rep has the qualification data but it is buried in a CRM field nobody opens. The rep starts the call cold despite the data. + +Detail in [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md). + +--- + +## Confirmation and reminder sequences + +The communications around the booking. + +**Booking confirmation.** Sent immediately after booking. Confirms time; restates context; sets expectations. + +**Pre-meeting reminder.** Sent 24 hours and/or 1 hour before. Reduces no-shows. + +**Post-meeting follow-up.** Sent within hours of the call. Recap; next steps; resources. + +**Reschedule and no-show flows.** Different flows for different outcomes. + +**The reminder discipline.** Reminders are useful; over-reminding is friction. Two reminders (24-hour and 1-hour) is typical. + +Detail in [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md). + +--- + +## Reschedule and no-show handling + +What happens when meetings do not go to plan. + +**Reschedule patterns.** + +- Easy self-serve reschedule (no friction). +- Reschedule preserves qualification data. +- Reschedule notifies the rep proactively. + +**No-show patterns.** + +- Auto-detect (rep reports no-show; or system detects unattended meeting). +- Follow-up to the prospect (gentle; not punitive). +- Re-engagement sequence (one or two attempts to rebook). +- Eventual deactivation (do not pursue forever). + +**The respect-the-no principle.** Prospects who no-show twice often do not want the meeting. Multiple aggressive reschedule attempts feel like pressure. + +Detail in [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md). + +- "Booking conversion is high; demo conversion to sale is low." Qualification too thin; cold demos do not convert. +- "Booking conversion is low; demo conversion to sale is high." Interrogation-gate; qualification scares off would-be buyers. +- "Sales says many bookings come from wrong-fit leads." Routing logic not connecting qualification to rep tier. +- "No-show rate is over 30 percent." Reminder sequence broken; or commitment friction at booking too low. +- "Reps complain they get no context before calls." Prep automation broken; data captured but not delivered to rep. +- "Calendar integration breaks every few weeks." Brittle integration; or rep calendar permissions changing. +- "Mobile booking conversion is half of desktop." Mobile UX issue. +- "Booking link gets shared by reps; routing logic bypassed." Generic link in use alongside structured flow; bypass undermines routing. +- "Round-robin produces uneven workload." Reps with different capacity treated equally. + +--- + +## The framework: 12 considerations for scheduler and booking design + +When designing or auditing a scheduler, walk these 12 considerations. + +1. **The booking-flow decision.** Is a scheduler the right tool, or a form / sales-pipeline tool? +2. **Qualified-fast-path, not any-time-friction or interrogation-gate.** Just enough qualification to set up the call well. +3. **Qualification fields earn their place.** 3-5 fields; each routes or preps. +4. **Availability logic matches team structure.** Round-robin, weighted, fit-based, or hybrid. +5. **Routing connects qualification to rep tier.** High-fit leads to senior reps. +6. **Prep automation delivers data to reps.** CRM enrichment, calendar invite, Slack brief. +7. **Confirmation and reminders reduce no-shows.** 24-hour and 1-hour typical. +8. **Reschedule is friction-low.** Self-serve; preserves data. +9. **No-show flow honest.** Re-engagement attempts limited; respect non-response. +10. **Mobile parity.** Booking works on the devices the audience uses. +11. **Conversion to sale as success metric.** Not just booking rate; downstream call-to-sale conversion. +12. **Maintenance discipline.** Routing rules updated as team changes; quarterly audit. + +The output of the framework is a scheduler that earns the booking by earning a better call, with conversion that compounds because the calls themselves are better. + +--- + +## Reference files + +- [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md) - When schedulers earn the build vs when forms or sales-pipeline tools serve. +- [`references/qualification-field-design.md`](references/qualification-field-design.md) - Strong and weak qualification fields. The five-field rule. +- [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md) - Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. +- [`references/routing-patterns.md`](references/routing-patterns.md) - By size, use case, geography, language, account ownership. Unrouted-lead default. +- [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md) - CRM enrichment, calendar invite, Slack brief, account research. +- [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md) - Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. +- [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md) - Reschedule patterns, no-show patterns, respect-the-no principle. +- [`references/scheduler-anti-patterns.md`](references/scheduler-anti-patterns.md) - The patterns that look like schedulers but degrade conversion. +- [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: schedulers earn the booking when they earn the better call + +The schedulers that work as compounding assets are the ones that produce better calls. Not just more bookings. Calls where the rep arrives prepared; the prospect feels respected; the conversation moves faster because qualification was already done. Conversion compounds because the calls themselves convert better. + +That is the bar. Below the bar are any-time-friction (cold demos, conversion suffers) and interrogation-gate (90 percent abandon at the form). Above the bar are qualified-fast-path schedulers where qualification, availability, routing, prep automation, and follow-up sequencing combine into a system that earns the booking and the call. + +The discipline is in the design choices. The decision to use a scheduler at all. The qualification fields that earn their place. The availability logic that matches lead to rep. The routing that respects rep tier and capacity. The prep automation that delivers context to reps before the call. The reminder cadence that reduces no-shows without becoming spam. The reschedule and no-show handling that respects the prospect. diff --git a/skills/scheduler-and-booking-design/references/availability-logic-patterns.md b/skills/scheduler-and-booking-design/references/availability-logic-patterns.md new file mode 100644 index 0000000..a2c9192 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/availability-logic-patterns.md @@ -0,0 +1,272 @@ +# Availability logic patterns + +Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. + +How the scheduler decides which rep gets which booking. Done well, availability logic distributes load while matching high-fit leads to senior reps; done poorly, leads land on the wrong reps and conversion suffers. + +--- + +## The match-to-rep principle + +The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +**The win.** A high-fit enterprise lead (large company, urgent timeline) sees availability for senior AEs. Low-fit lead (small team, exploring) sees availability for SDRs. Each lead gets the right call. + +**The fail.** Same scheduler with pure round-robin. Enterprise lead lands on an SDR; SDR is unprepared; conversion drops. + +The discipline. Routing is not separate from qualification; the two are coupled. + +--- + +## Pattern A: Pure round-robin + +Bookings cycle through available reps in order. + +**How it works.** + +- Available reps in the queue. +- Each booking goes to the next rep. +- Cycle continues. + +**Strengths.** + +- Even distribution. +- Simple logic. +- Easy to explain to the team. + +**Weaknesses.** + +- Does not match high-fit leads to senior reps. +- Does not load-balance based on capacity. +- Does not account for rep specialization. + +**When to use.** Small teams; reps are interchangeable; volume is low. + +--- + +## Pattern B: Weighted round-robin + +Bookings cycle but weighted by rep performance, capacity, or specialty. + +**How it works.** + +- Each rep has a weight (performance score, capacity, etc.). +- Distribution skews toward higher-weighted reps. +- Still distributes; just unevenly. + +**Strengths.** + +- Higher-performing reps get more bookings. +- Capacity differences accommodated. + +**Weaknesses.** + +- Lower-performing reps get fewer learning opportunities. +- Weighting must be maintained. + +**When to use.** Teams with significant rep performance differences; teams where capacity differs. + +--- + +## Pattern C: Fit-based routing + +High-fit leads route to senior reps; lower-fit leads route to SDRs or async resources. + +**How it works.** + +- Qualification fields determine fit score. +- High-fit leads see availability for senior reps only. +- Lower-fit leads see availability for SDRs. + +**Strengths.** + +- Senior reps focus on high-value conversations. +- SDRs handle qualification and nurture. +- Resource allocation matches lead value. + +**Weaknesses.** + +- Requires clear fit signals from qualification. +- May produce uneven workload (senior reps light, SDRs heavy). + +**When to use.** Teams with multi-tier sales motion; clear fit signals captured. + +--- + +## Pattern D: Specialty-based routing + +Bookings route to reps with specific expertise. + +**How it works.** + +- Qualification captures use case or industry. +- Bookings route to the rep with matching specialty. + +**Strengths.** + +- Rep is genuinely prepared for the specific conversation. +- Higher conversion when specialty matches. + +**Weaknesses.** + +- Specialist reps can become bottlenecks. +- Requires per-rep specialty tagging. + +**When to use.** Products with multiple distinct use cases or verticals. + +--- + +## Pattern E: Account-ownership routing (B2B) + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +**How it works.** + +- Qualification or domain matching detects existing-account leads. +- Bookings route to the AE who owns the account. +- Override default routing. + +**Strengths.** + +- Account owner has context. +- Avoids confusion of multiple reps on the same account. + +**Weaknesses.** + +- Requires CRM integration to detect ownership. +- Account ownership must be current. + +**When to use.** B2B teams with account-ownership models. + +--- + +## Pattern F: Hybrid + +Combining patterns. Most production teams use hybrid. + +**Common combinations.** + +- Account-ownership routing first (existing accounts to AEs). +- Then fit-based routing (high-fit new leads to senior AEs). +- Then specialty-based routing within tier. +- Then round-robin within remaining pool. + +**Strengths.** + +- Handles common cases. +- Routes lead to best-matched rep. + +**Weaknesses.** + +- More complex to maintain. +- More edge cases to handle. + +**When to use.** Mature production teams with multi-tier sales motion. + +--- + +## Calendar integration + +How availability connects to actual calendars. + +**Direct calendar integration.** Scheduler reads rep calendars; shows actual availability. + +Strengths. No double-booking; reflects reality. + +Weaknesses. Requires calendar permissions; integration brittle. + +**Office hours definition.** Reps define availability windows; scheduler shows those. + +Strengths. Simpler integration; no calendar permissions needed. + +Weaknesses. Manual maintenance; reps may forget to update. + +**Hybrid.** Scheduler uses office hours plus calendar busy/free for fine-grain. + +Strengths. Resilient to integration issues. + +Weaknesses. More complex. + +--- + +## Buffer time + +Time between meetings. + +**Why it matters.** Back-to-back meetings produce rushed reps and late starts. Buffer protects rep effectiveness. + +**Common buffers.** 10-15 minutes between meetings. + +**The discipline.** Buffer should be in the calendar logic, not optional. + +--- + +## Capacity caps + +How many meetings per day per rep. + +**Why caps matter.** Reps booked solid produce poor calls; quality drops; conversion suffers. + +**Common caps.** 3-5 demos per day per rep typical for B2B SaaS. + +**The discipline.** Caps respect rep effectiveness, not just calendar availability. + +--- + +## Time zone handling + +The scheduler shows availability in the prospect's time zone. + +**The principle.** Display in prospect's time zone; reps see in their own. + +**Common patterns.** + +- Auto-detect from browser; show prospect that detection. +- Allow manual override. +- Display rep's time zone for clarity ("PT" badge). + +**Anti-pattern.** Showing all times in rep's time zone; prospect has to convert mentally. + +--- + +## Out-of-office and holiday handling + +Real life intervenes. + +**Patterns.** + +- Calendar integration handles vacation as busy time. +- Manual office-hours updates handle planned absences. +- Holiday calendars block company-wide closures. + +**The discipline.** Out-of-office should be respected automatically; otherwise no-shows happen. + +--- + +## Common availability failures + +**Pure round-robin for tiered teams.** High-fit leads land on junior reps. + +**No capacity caps.** Reps overbooked; quality drops. + +**No buffer.** Meetings run late; reps are stressed. + +**Time zone confusion.** Prospect sees rep's time zone; bookings happen at wrong times. + +**Stale rep weights.** Weighted round-robin uses last-quarter performance; recent changes ignored. + +**Specialty routing without specialty data.** Specialty-based routing requires per-rep tagging; missing tags route incorrectly. + +**Account-ownership not detected.** Existing-account lead bounces around between reps. + +**Calendar integration broken.** Double-bookings happen; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The match-to-rep principle. Patterns A through F (round-robin, weighted, fit-based, specialty, account-ownership, hybrid). Calendar integration. Buffer time. Capacity caps. Time zone handling. Out-of-office and holiday handling. Common failures. + +## Implementation choices that stay internal + +Specific routing logic for specific teams. Specific weights and caps. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/common-scheduler-failures.md b/skills/scheduler-and-booking-design/references/common-scheduler-failures.md new file mode 100644 index 0000000..be02c42 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/common-scheduler-failures.md @@ -0,0 +1,179 @@ +# Common scheduler failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Booking conversion is high; demo conversion to sale is low." + +**The diagnosis.** Qualification too thin; cold demos do not convert. + +**The cure.** Add 3-5 strategic qualification fields. Detail in `references/qualification-field-design.md`. + +--- + +## "Booking conversion is low; demo conversion to sale is high." + +**The diagnosis.** Interrogation-gate; qualification scares off would-be buyers. + +**The cure.** Cut qualification to 3-5 fields. Defer non-essential questions to in-call. + +--- + +## "Sales says many bookings come from wrong-fit leads." + +**The diagnosis.** Routing logic not connecting qualification to rep tier. + +**The cure.** Add fit-based routing. Detail in `references/routing-patterns.md`. + +--- + +## "No-show rate is over 30 percent." + +**The diagnosis.** Reminder sequence broken; or commitment friction at booking too low. + +**The cure.** Audit reminder cadence. Strengthen pre-meeting communications. Detail in `references/reminder-sequence-patterns.md`. + +--- + +## "Reps complain they get no context before calls." + +**The diagnosis.** Prep automation broken; data captured but not delivered. + +**The cure.** CRM enrichment, calendar invite enrichment, Slack brief. Detail in `references/prep-automation-patterns.md`. + +--- + +## "Calendar integration breaks every few weeks." + +**The diagnosis.** Brittle integration; or rep calendar permissions changing. + +**The cure.** Monitor integration; fix permissions; have a manual fallback for downtime. + +--- + +## "Mobile booking conversion is half of desktop." + +**The diagnosis.** Mobile UX issue. + +**The cure.** Mobile-first design and testing. + +--- + +## "Booking link gets shared by reps; routing logic bypassed." + +**The diagnosis.** Generic link in use alongside structured flow. + +**The cure.** Disable generic links. Train reps; provide rep-specific structured links if needed. + +--- + +## "Round-robin produces uneven workload." + +**The diagnosis.** Reps with different capacity treated equally. + +**The cure.** Weighted round-robin or capacity-aware routing. + +--- + +## "Time zone errors cause no-shows." + +**The diagnosis.** Time zone display unclear or auto-detection wrong. + +**The cure.** Display time zone clearly at booking and in invites. Auto-detect prospect time zone; allow override. + +--- + +## "Reps reschedule manually frequently." + +**The diagnosis.** Routing produces wrong-fit bookings; reps fix manually. + +**The cure.** Audit routing logic; fix the source of the wrong-fit bookings. + +--- + +## "Conversion was strong; quality dropped after sales team change." + +**The diagnosis.** New rep tier or specialization mix; routing not updated. + +**The cure.** Routing rules updated as team changes. Quarterly review. + +--- + +## "We added more qualification fields; conversion dropped." + +**The diagnosis.** Crossed the five-field threshold. + +**The cure.** Cut back. Five-field rule from `references/qualification-field-design.md`. + +--- + +## "Some segments convert; others do not." + +**The diagnosis.** Single scheduler treats all segments the same. + +**The cure.** Per-segment qualification or routing. Different segments may need different schedulers. + +--- + +## "Schedulers work for direct traffic; partner-sourced leads convert poorly." + +**The diagnosis.** Partner-sourced leads have different fit profile; routing or qualification not adapted. + +**The cure.** Source-based routing. Partner leads may need different rep tier or different prep. + +--- + +## "We tried different reminder cadences; no-shows did not move." + +**The diagnosis.** No-show may not be reminder-driven. Could be commitment friction at booking, time zone errors, or audience mismatch. + +**The cure.** Test other variables. Audit booking commitment level, time zone clarity, audience-fit. + +--- + +## "Sales says enterprise prospects skip the scheduler and email instead." + +**The diagnosis.** Enterprise audiences sometimes want personal contact rather than self-serve booking. + +**The cure.** Offer a "talk to sales" alternative for enterprise leads. Hybrid approach. + +--- + +## "Conversion dropped after we updated the booking flow." + +**The diagnosis.** Specific change introduced friction. + +**The cure.** Compare metrics pre- and post-change. Roll back if necessary; isolate the issue. + +--- + +## "Reschedule flow loses qualification data." + +**The diagnosis.** Reschedule treated as new booking; data not preserved. + +**The cure.** Reschedule preserves qualification. Detail in `references/reschedule-and-no-show-handling.md`. + +--- + +## The pattern across failures + +Most scheduler failures fall into one of three patterns. + +**Pattern 1: Qualification miscalibrated.** Any-time-friction, interrogation-gate, or wrong fields. The fix is calibrating qualification to the team's needs. + +**Pattern 2: Routing or prep miscalibrated.** Wrong-rep-tier, no-prep-automation, broken integrations. The fix is connecting qualification to rep workflow. + +**Pattern 3: Communication miscalibrated.** Aggressive reminders, brittle no-show flows, missing reschedule paths. The fix is gentle, useful communication. + +The metric pattern: scheduler failures often look fine on booking conversion alone. The signal is in demo-to-sale conversion, no-show rates, rep prep quality. Programs that track only booking rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (qualification, routing/prep, communication). The principle that booking rate alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/prep-automation-patterns.md b/skills/scheduler-and-booking-design/references/prep-automation-patterns.md new file mode 100644 index 0000000..fe9f876 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/prep-automation-patterns.md @@ -0,0 +1,247 @@ +# Prep automation patterns + +CRM enrichment, calendar invite, Slack brief, account research. + +The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused and the rep starts the call cold despite the data being captured. + +--- + +## The data-reaches-rep principle + +Prep automation closes the loop between qualification capture and rep readiness. + +**The win.** Prospect books; qualification data populates the CRM record, appears in the calendar invite, and triggers a brief Slack message to the rep with synthesized prep notes. The rep arrives at the call already knowing the prospect's situation. + +**The fail.** Qualification data captured; sits in a database; rep does not see it until they search for it. Most reps do not search; they start the call cold. + +The discipline. Capture qualification AND deliver it to the rep where they will see it. + +--- + +## Pattern A: CRM enrichment + +Qualification data populates the CRM record. + +**How it works.** + +- Booking submission writes to CRM (Salesforce, HubSpot, etc.). +- Fields populate the lead/contact record. +- Rep sees the data when they review the lead. + +**Strengths.** + +- Single source of truth. +- Fits existing rep workflow (reps already check CRM). + +**Weaknesses.** + +- Reps may not check CRM before every call. +- CRM custom fields require setup. + +**When to use.** Default; baseline for any prep automation. + +--- + +## Pattern B: Calendar invite enrichment + +Qualification data appears in the meeting invite description. + +**How it works.** + +- When the meeting is created, the invite description includes the qualification data. +- Rep sees it on their calendar; visible at-a-glance. + +**Strengths.** + +- Rep cannot miss it; calendar is the moment of action. +- Works regardless of CRM access. + +**Weaknesses.** + +- Calendar invite descriptions can be long; reps may not read fully. +- Updates after booking do not appear in the invite. + +**When to use.** Strong complement to CRM enrichment. + +--- + +## Pattern C: Slack or email brief + +Pre-call brief sent to the rep with synthesized prospect info. + +**How it works.** + +- Booking triggers a Slack message or email to the rep. +- Brief includes qualification data plus context (account history, company info, prior interactions). +- Often delivered hours or a day before the call. + +**Strengths.** + +- Active delivery; rep receives it without searching. +- Can include synthesized context (CRM history, news, prior touches). + +**Weaknesses.** + +- Slack noise can dilute brief; reps may scroll past. +- Email may sit unread. + +**When to use.** When the team's workflow includes Slack or email-driven prep. + +--- + +## Pattern D: Account research + +Qualification data triggers automated research. + +**How it works.** + +- Booking triggers automated lookup (company size verification via Clearbit/ZoomInfo, recent news search, social media check). +- Research results appended to CRM or prep brief. + +**Strengths.** + +- Rep gets richer context than qualification alone provides. +- Catches data prospects did not provide. + +**Weaknesses.** + +- Research tools cost. +- Can miss for small companies or international. + +**When to use.** Enterprise sales motion; high-value calls warrant research investment. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production teams use multiple. + +**Common combination.** + +- CRM enrichment as baseline. +- Calendar invite enrichment for at-a-glance visibility. +- Slack brief 24 hours before the call for richer prep. +- Account research for high-fit leads. + +The hybrid produces multiple touchpoints; rep sees prep data wherever they happen to look first. + +--- + +## What to include in prep automation + +The fields that matter to the rep. + +**Standard inclusions.** + +- Prospect name and role. +- Company name and size. +- Use case or primary goal. +- Current solution. +- Timeline or urgency. +- Source (paid, organic, referral). + +**Sometimes useful.** + +- Company industry and recent news. +- Prior interactions with the brand. +- LinkedIn profile link. +- Account history (existing customer, prior trial). + +**Avoid in prep.** + +- Free-text fields the prospect filled with noise. +- Marketing data not relevant to the call (UTM details, lead source granularity). +- Personal data not needed for the call. + +--- + +## Prep timing + +When the brief reaches the rep. + +**At-booking.** Brief delivered immediately after booking. Rep can prepare any time. + +**Day-before.** Brief delivered 24 hours before. Forces prep into the rep's workflow. + +**Hour-before.** Brief delivered 1 hour before. Last-minute prep; useful for back-to-back calls. + +**The combined approach.** Most teams use at-booking (CRM record) plus day-before (Slack) plus calendar visibility throughout. + +--- + +## Prep brief copy + +What the brief says. + +**Strong brief copy.** + +- "Sarah Lee, Director of Marketing at [Company], 200-500 employees, evaluating analytics tools to replace [current solution] within 60 days." + +What works. Specific; structured; gives rep enough to prepare. + +**Weak brief copy.** + +- "New booking from Sarah Lee." + +What fails. No context; rep starts cold despite the data being captured upstream. + +The discipline. Brief should be specific enough that the rep arrives ready. + +--- + +## Prep automation testing + +Verify the loop works. + +**Test cases.** + +- Booking happens; CRM record created; data populates. +- Booking happens; calendar invite shows the qualification data. +- Booking happens; Slack brief arrives at the right time. +- Edge case: prospect updates booking; prep updates accordingly. + +**Production monitoring.** If reps consistently arrive at calls cold, prep automation is broken somewhere. + +--- + +## Privacy and consent + +Prep automation involves handling user data. + +**The principle.** Data captured at booking flows to internal systems for prep. The prospect has implicitly consented to internal use through the booking. + +**Limits.** + +- Data should not flow to systems unrelated to the booking purpose. +- Account research should respect privacy norms. +- GDPR and other regulations apply. + +--- + +## Common prep automation failures + +**No automation.** Data captured; reps do not see it. + +**CRM enrichment without rep CRM use.** Data is in CRM; reps do not check CRM before calls. + +**Slack brief lost in noise.** Prep brief among 50 other Slack messages; rep misses. + +**Calendar invite truncated.** Invite description too long; reps see only opening. + +**Stale account research.** Research data from months ago. + +**Brief copy generic.** Brief contains data but not synthesized context. + +**Updates after booking not propagated.** Prospect updates info; prep stays old. + +**No testing.** Prep loop broken; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The data-reaches-rep principle. Patterns A through E (CRM, calendar, Slack, research, hybrid). What to include in prep. Prep timing. Prep brief copy discipline. Prep automation testing. Privacy and consent. Common failures. + +## Implementation choices that stay internal + +Specific prep configurations for specific teams. Specific Slack templates and CRM custom fields. Specific research tooling. The team's privacy review processes. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/qualification-field-design.md b/skills/scheduler-and-booking-design/references/qualification-field-design.md new file mode 100644 index 0000000..ea83e3c --- /dev/null +++ b/skills/scheduler-and-booking-design/references/qualification-field-design.md @@ -0,0 +1,221 @@ +# Qualification field design + +Strong and weak qualification fields. The five-field rule. + +The fields decide the booking flow's friction and the call's quality. Done well, qualification produces context for the call without scaring off prospects; done poorly, it produces interrogation-gate dynamics. + +--- + +## The earns-its-place principle + +Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +**The win.** Four fields: company size, role, primary use case, timeline. Each routes or preps. Conversion is high; rep prep is concrete. + +**The fail.** Twelve fields including industry code, employee count range, marketing source, lead-source detail, gender. Most do not affect routing or prep; conversion drops 70 percent. + +The discipline. Audit each field. Cut fields that do not earn placement. + +--- + +## Strong qualification fields + +Patterns that earn placement. + +**Company size or team size.** + +Why it works. Routes to the right rep tier (SMB vs mid-market vs enterprise); enables segment tracking; concrete signal of fit. + +Format. Dropdown with bands ("1-10," "11-50," "51-200," "201-1000," "1000+"). + +**Use case or primary goal.** + +Why it works. Lets the rep prepare for the conversation that matches. + +Format. Dropdown with 5-7 use cases; or short open text if use cases are not enumerable. + +**Current solution or stack.** + +Why it works. Tells the rep where the prospect is starting; informs migration vs greenfield framing. + +Format. Dropdown of common alternatives plus "other" with text field. + +**Timeline or urgency.** + +Why it works. Routes to active-pipeline vs nurture; signals urgency to the rep. + +Format. Dropdown ("Within 30 days," "1-3 months," "3-6 months," "Just exploring"). + +**Role or job function.** + +Why it works. Lets the rep tailor framing; routes to specialist reps if role-aligned. + +Format. Dropdown of common roles; "Other" field for unusual cases. + +--- + +## Weak qualification fields + +Patterns that fail. + +**Phone number.** + +Why it fails. Often unnecessary if email and meeting time are captured. Reps can request phone in the call. Phone field adds friction without value for the booking itself. + +When to include. If the call is by phone (not video), phone is necessary. + +**Generic comments box.** + +Why it fails. Free-text rarely informs prep. Most prospects skip; some over-share; few provide useful context. + +When to include. Sparingly; if structured fields cannot capture the necessary context. + +**Marketing data not used in the call.** + +Why it fails. Industry codes, lead-source detail, etc. add friction without affecting the call's quality. + +When to include. Capture later (post-meeting follow-up form, CRM enrichment) rather than at the booking. + +**Demographic data unrelated to the call.** + +Why it fails. Gender, age, etc. rarely inform a B2B sales conversation. + +When to include. Almost never. Only if regulatory or product-specific reasons require. + +--- + +## The five-field rule + +Most production schedulers work well with 3-5 qualification fields. + +**Why 3-5.** + +- 3 fields is the minimum for useful qualification. +- 5 fields is the threshold beyond which drop-off climbs. +- Production data across many SaaS products supports this range. + +**Exceptions.** + +- Some enterprise sales contexts warrant 5-7 fields because the audience expects qualification. +- Some highly specialized products warrant fewer fields (1-2) because conversion volume matters more. + +**The over-five trap.** Each additional field beyond 5 reduces conversion meaningfully. The marginal value of field 6 rarely justifies the conversion cost. + +--- + +## Field ordering + +Within the form, the order matters. + +**Open with low-friction.** Identity fields (name, email) first. Familiar; easy. + +**Build to value.** Use-case or goal fields next. The prospect engages with what the call will be about. + +**Save commitment for later.** Timeline or budget fields late. The prospect has invested; harder ask is acceptable. + +**End with optional.** Comments or "anything else?" at the end if included. The prospect can leave or skip. + +--- + +## Field formats + +How each field captures input. + +**Dropdowns.** Best for categorical fields. Constrains responses; easy to route on. + +**Text fields.** For free-form fields (name, email, sometimes use case). + +**Sliders.** Rarely useful in qualification. + +**Yes/No toggles.** For binary qualifying questions (e.g., "Do you currently use a CRM?"). + +**Conditional fields.** Some fields appear based on earlier answers. Use sparingly; complexity adds maintenance. + +--- + +## Field validation + +What to validate. + +**Email format.** Standard validation; respect plus-aliases and international domains. + +**Required vs optional.** Mark explicitly. + +**Length and character.** Don't reject international names or non-Latin characters. + +**The validation-strict failure.** Validation that rejects valid inputs (international phone formats, plus-sign emails) loses real prospects. + +--- + +## Inferred vs asked fields + +What to ask vs what to infer. + +**Ask sparingly.** Each field is friction. + +**Infer when possible.** + +- Lead source: from URL parameters or referrer. +- Company info: from email domain. +- Geography: from IP or browser. +- Timezone: from browser. + +**The discipline.** If the system can infer a value reliably, do not ask. + +--- + +## Field-level analytics + +Track per-field drop-off. + +**Per-field completion rate.** Where in the form do prospects abandon? + +**Diagnostic uses.** + +- Specific field with high abandonment: friction at that field. +- Field rarely completed even by survivors: often signals the field can be cut. +- Specific segment abandons specific fields: segment-specific friction. + +The data informs which fields earn their place over time. + +--- + +## Field maintenance + +Fields decay. + +**What decays.** + +- Dropdowns with options that no longer match audience. +- Fields the rep team stopped using for prep. +- Fields whose routing logic changed without update. + +**Maintenance cadence.** Quarterly review of each field. Are reps using the data? Is routing connecting field-to-tier? + +--- + +## Common field failures + +**Too many fields.** Drop-off at the form. + +**Fields not used.** Captured but reps do not prep with them. + +**Wrong field types.** Free text where dropdown would route better. + +**Validation too strict.** Loses valid prospects. + +**No analytics.** Cannot tell which fields are working. + +**Stale field options.** Dropdowns no longer match audience. + +**Fields asked that could be inferred.** Friction without need. + +--- + +## Methodology-level choices that stay in the public skill + +The earns-its-place principle. Strong qualification fields (5 patterns). Weak qualification fields (4 patterns). The five-field rule. Field ordering. Field formats. Field validation. Inferred vs asked. Field-level analytics. Field maintenance. Common failures. + +## Implementation choices that stay internal + +Specific fields for specific schedulers. Specific dropdown options. Specific tooling for inference. The team's audit calendar. These vary by team and product. diff --git a/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md b/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md new file mode 100644 index 0000000..05b3b4d --- /dev/null +++ b/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md @@ -0,0 +1,256 @@ +# Reminder sequence patterns + +Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. + +The communications around the booking. Done well, reminders reduce no-shows without becoming spam; done poorly, reminders are either insufficient (no-shows climb) or excessive (prospect resents). + +--- + +## The reduce-no-shows-without-spam principle + +Reminders matter; their volume should be calibrated. + +**The win.** Confirmation immediately after booking; one reminder 24 hours before; one reminder 1 hour before. Three communications total. No-show rate drops; prospects feel reminded but not nagged. + +**The fail.** Confirmation; 5-day reminder; 2-day reminder; 1-day reminder; 1-hour reminder; 15-minute reminder. Six communications. Prospects mute the channel; no-shows persist for users who muted. + +The discipline. Reminders earn their place; cumulative volume should be capped. + +--- + +## Pattern A: Booking confirmation + +Sent immediately after booking. + +**What it includes.** + +- Confirmed time and meeting type. +- Calendar invite attached. +- Brief restate of expectations (e.g., "Looking forward to learning about your X"). +- Reschedule and cancel links. + +**Strengths.** + +- Immediate; reduces buyer's remorse. +- Sets expectations. +- Provides reschedule path. + +**Weaknesses.** + +- One-touch communication. + +**When to use.** Always. + +--- + +## Pattern B: Pre-meeting reminder + +Sent 24 hours and/or 1 hour before. + +**24-hour reminder.** + +- Useful for users who book days in advance. +- Lets them prepare or reschedule with notice. + +**1-hour reminder.** + +- Useful for last-minute prep. +- Catches calendar drift. + +**Both useful or one only?** + +- Most production teams use both. +- For very short booking windows (same-day), 1-hour is enough. +- For longer-lead bookings, 24-hour matters. + +--- + +## Pattern C: Post-meeting follow-up + +Sent within hours of the call. + +**What it includes.** + +- Brief recap. +- Action items (rep's commitments). +- Resources mentioned in the call. +- Next-step CTA (next meeting, document, trial). + +**Strengths.** + +- Captures momentum from the call. +- Documents commitments. + +**Weaknesses.** + +- Requires rep to populate after the call (or rep-side tooling to auto-generate). + +**When to use.** Sales conversations where next steps matter. + +--- + +## Pattern D: Reschedule prompts + +When the prospect cannot make the meeting. + +**What it includes.** + +- Easy reschedule link. +- Brief check-in copy ("Need to reschedule? No problem."). + +**Strengths.** + +- Reduces no-shows; users reschedule rather than ghost. + +**Weaknesses.** + +- Some users use this to reschedule indefinitely. + +**When to use.** Always available; not aggressive. + +--- + +## Pattern E: No-show follow-up + +When the prospect does not attend. + +**What it includes.** + +- Acknowledgment of missed meeting. +- Reschedule link. +- Brief context-restatement. + +**Tone.** Gentle, not punitive. The prospect may have had a real reason. + +**The respect-the-no-show principle.** After 1-2 reschedule attempts, accept that the prospect is not engaging. + +--- + +## Reminder timing + +When each communication fires. + +**Common cadence.** + +- T+0: Confirmation immediately after booking. +- T-24h: Reminder 24 hours before. +- T-1h: Reminder 1 hour before. +- T+15m: Late-arrival check (sometimes). +- T+24h: Post-meeting follow-up. + +The discipline. Each communication earns its place. Drop the ones that do not. + +--- + +## Channel choice + +Which channels to use. + +**Email.** Default. Reliable; familiar. + +**SMS.** Higher attention; more friction. Use selectively for high-value bookings. + +**In-app notification.** If the booking is for a logged-in user, in-app reminders work. + +**Slack or Teams.** For B2B internal-team meetings. + +**The cumulative discipline.** Multiple channels for the same reminder is excessive. Pick one channel per reminder. + +--- + +## Reminder copy + +What the reminders say. + +**Strong reminder copy.** + +- "Looking forward to our call tomorrow at 2 PM PT. Here's what we'll cover: [agenda]." +- "Reminder: 1 hour until our call. Join here: [link]." +- "Thanks for the call today. Here's what we discussed: [recap]." + +What works. Specific; useful; brief. + +**Weak reminder copy.** + +- "Don't forget your meeting!" +- "Your meeting is in 1 hour." +- "Did you know..." + +What fails. Generic; no value-add; just a notification. + +--- + +## Reminder personalization + +How much to personalize. + +**Default personalization.** Name; meeting time; rep name. + +**Strong personalization.** Brief context tied to qualification ("Looking forward to discussing your [use case] situation"). + +**Over-personalization.** Long personalized paragraphs that read as marketing. + +The discipline. Personalize where it adds value; do not pad with personalization for its own sake. + +--- + +## Reminder analytics + +Track effectiveness. + +**Metrics.** + +- Open rate per reminder. +- Reschedule rate per reminder. +- No-show rate (cumulative across cadence). +- Cancellation rate. + +**Diagnostic uses.** + +- Low open rate: subject line weak or channel wrong. +- High reschedule rate after specific reminder: that reminder triggers reconsideration. +- High no-show despite reminders: friction at the meeting itself, not the reminder. + +--- + +## Reminder maintenance + +Reminders decay. + +**What decays.** + +- Templates with stale rep names or roles. +- Calendar links that broke after platform changes. +- Channel preferences that no longer fit audience. + +**Maintenance cadence.** Quarterly review of reminder templates and channels. + +--- + +## Common reminder failures + +**Too many reminders.** Cumulative volume is spam; users mute. + +**Too few reminders.** No-show rate climbs. + +**Generic copy.** No value; users dismiss. + +**Wrong channel.** SMS for an audience that prefers email. + +**Stale templates.** Rep names from former employees; broken calendar links. + +**No post-meeting follow-up.** Conversation momentum lost. + +**Aggressive no-show follow-up.** Multiple reminder attempts after a no-show; respect non-response. + +**Personalization padding.** Long personalized text that reads as marketing. + +--- + +## Methodology-level choices that stay in the public skill + +The reduce-no-shows-without-spam principle. Patterns A through E (confirmation, pre-meeting, post-meeting, reschedule, no-show). Reminder timing. Channel choice. Reminder copy discipline. Reminder personalization. Reminder analytics. Reminder maintenance. Common failures. + +## Implementation choices that stay internal + +Specific reminder cadences for specific teams. Specific copy in brand voice. Specific channel choices. The team's no-show baselines. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md b/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md new file mode 100644 index 0000000..081a420 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md @@ -0,0 +1,241 @@ +# Reschedule and no-show handling + +Reschedule patterns, no-show patterns, respect-the-no principle. + +What happens when meetings do not go to plan. Done well, reschedule and no-show handling protect the relationship and capture re-engagement; done poorly, they punish the prospect for ordinary life events. + +--- + +## The respect-the-no principle + +Prospects who reschedule or no-show often have real reasons. Handling should be gentle, not punitive. + +**The win.** Prospect no-shows; gentle follow-up offers easy reschedule. Prospect reschedules once; offered again at a new convenient time. After two no-shows, the system stops aggressive pursuit and routes to nurture. + +**The fail.** Prospect no-shows; system fires three reminder emails over two days; phone call follows; prospect feels harassed. + +The discipline. Acknowledge that life intervenes; offer a path back; do not pressure. + +--- + +## Reschedule patterns + +When prospects need to change the meeting. + +**Pattern A: Self-serve reschedule.** + +How it works. The booking confirmation includes a reschedule link. Prospect clicks; sees new availability; selects new slot. + +Strengths. No friction; respect for the prospect's time. + +Weaknesses. Some abuse possible (repeated reschedules). + +When to use. Default for most schedulers. + +**Pattern B: Reschedule preserves qualification data.** + +How it works. Reschedule keeps all the qualification info; rep does not lose context. + +Strengths. Reschedule does not cost prep work. + +Weaknesses. None significant. + +When to use. Always. + +**Pattern C: Reschedule notifies the rep.** + +How it works. When prospect reschedules, rep gets notified. Original calendar slot freed up. + +Strengths. Rep can use the freed slot. + +Weaknesses. None. + +When to use. Always. + +**Pattern D: Reschedule limits.** + +How it works. After N reschedules, the system flags the booking for review or routes to nurture. + +Strengths. Prevents abuse. + +Weaknesses. Risks alienating prospects with legitimate scheduling difficulty. + +When to use. Sparingly; usually 3+ reschedules before flagging. + +--- + +## No-show patterns + +When prospects do not attend. + +**Detection.** + +- Rep reports no-show after the meeting time. +- System detects unattended meeting (if integrated with video platform). +- Manual reports from CS or sales ops. + +**Pattern A: Single follow-up.** + +How it works. Within 4-24 hours of the no-show, send a single gentle email offering reschedule. + +Strengths. Catches genuine forgetfulness. + +Weaknesses. Single touch may not catch users on vacation. + +When to use. Default. + +**Pattern B: Two-touch follow-up.** + +How it works. First email immediate. Second email 3-5 days later if no response. + +Strengths. Catches prospects who were genuinely busy. + +Weaknesses. Risks feeling persistent. + +When to use. Higher-value bookings where multi-touch is justified. + +**Pattern C: Sales-led recovery.** + +How it works. For high-value no-shows, sales rep reaches out personally. + +Strengths. Most engaging; can recover the relationship. + +Weaknesses. Expensive; only viable for high-value accounts. + +When to use. Enterprise no-shows or accounts with strategic value. + +**Pattern D: Async route.** + +How it works. Send the no-show prospect resources or content rather than another booking attempt. Re-engagement deferred. + +Strengths. Respects the no-show as a signal. + +Weaknesses. May lose prospects who would have rebooked. + +When to use. After 1-2 unsuccessful reschedule attempts. + +--- + +## Reschedule cadence + +How often to retry. + +**Single reschedule attempt:** offer once; respect non-response. + +**Multiple attempts:** at most 2 attempts spaced 3-7 days apart. Stop after that. + +**No reschedule attempts:** for bookings flagged as low-fit; route to nurture. + +The discipline. Each reschedule attempt earns its place. Cumulative attempts become harassment. + +--- + +## When to abandon reschedule + +Some no-shows should be respected as final. + +**Signals to stop.** + +- Prospect explicitly asked to stop contact. +- Multiple no-shows from same prospect. +- No response to 2 reschedule attempts. +- Email bounced or unsubscribed. + +**The respect-the-pattern principle.** Multiple no-shows often signal the prospect's needs changed. Continuing pursuit damages the brand. + +--- + +## No-show flow design + +The full sequence. + +**T+0 (no-show happens).** + +- Rep marks no-show in CRM. +- Free the calendar slot. + +**T+4-24h (first follow-up).** + +- Email: "Sorry we missed you. Want to reschedule? [Link]." + +**T+3-5d (second follow-up if needed).** + +- Email: "We're still interested in connecting if your schedule changed. Here's the reschedule link." + +**T+10d (final attempt or async route).** + +- Send relevant content; surface re-engagement option without pressure. + +**T+30d+.** + +- Treat as nurture; pursue through other channels (email newsletter, content). + +The cadence respects multiple touchpoints without becoming aggressive. + +--- + +## No-show analytics + +Track patterns. + +**Per-segment no-show rate.** + +- Different sources, sizes, or use cases may no-show at different rates. + +**Per-rep no-show rate.** + +- Some reps may correlate with higher no-shows (timing, time zone, prep gaps). + +**Reschedule conversion rate.** + +- Of rescheduled bookings, what percentage attend. + +**Diagnostic uses.** + +- High overall no-show: reminder sequence weak or commitment friction at booking too low. +- Specific segment no-shows more: that segment may need different cadence. +- Specific rep no-shows more: their availability or prep may be off. + +--- + +## Time zone and travel mistakes + +Common reasons for no-shows that are not the prospect's fault. + +**Prevention.** + +- Display time zone clearly at booking. +- Calendar invites include time zone. +- Reminders include time zone. + +**The cure for time zone mistakes.** Quick reschedule; do not penalize. + +--- + +## Common reschedule and no-show failures + +**Aggressive recovery.** Multiple touches over short periods; harassment. + +**Reschedule limits too tight.** Genuine prospects flagged after 2 reschedules; lost. + +**Reschedule loses qualification data.** Rep loses context on reschedule. + +**No reschedule path.** Prospect cannot reschedule; ghosts instead. + +**No-show no follow-up.** Prospect's missed meeting is just lost; could have rebooked. + +**Punitive copy.** No-show follow-up shames the prospect. + +**Time zone confusion.** Prospect missed because of time zone error; system blames the prospect. + +**Stale reschedule links.** Link works at booking; broken later. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-no principle. Reschedule patterns A through D. No-show patterns A through D. Reschedule cadence. When to abandon. No-show flow design. No-show analytics. Time zone considerations. Common failures. + +## Implementation choices that stay internal + +Specific reschedule limits for specific teams. Specific follow-up cadences. Specific copy in brand voice. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/routing-patterns.md b/skills/scheduler-and-booking-design/references/routing-patterns.md new file mode 100644 index 0000000..fe64b71 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/routing-patterns.md @@ -0,0 +1,235 @@ +# Routing patterns + +By size, use case, geography, language, account ownership. Unrouted-lead default. + +The specific routing rules that translate qualification answers into rep assignments. Done well, routing matches lead to rep cleanly; done poorly, leads bounce around or land on wrong reps. + +--- + +## Routing-by-company-size + +The most common routing axis. + +**Pattern.** + +- 1-50 employees: SDR or self-serve. +- 51-500 employees: AE. +- 501-2000 employees: senior AE. +- 2000+ employees: enterprise AE. + +**Why it works.** Different sizes have different sales motions; rep tier should match. + +**Failure modes.** + +- Size bands set years ago; team scaled; bands no longer right. +- Size data missing or stale. +- Solo founders with backed companies appear "small" but warrant senior treatment. + +--- + +## Routing-by-use-case + +Different specialists for different product use cases. + +**Pattern.** + +- Use case A: rep with A specialty. +- Use case B: rep with B specialty. +- General use case: any AE. + +**Why it works.** Specialists arrive with deeper context; conversion higher. + +**Failure modes.** + +- Specialist becomes bottleneck. +- New use cases without assigned specialist. +- Use case overlap; multiple specialists could fit. + +--- + +## Routing-by-geography + +Different reps for different regions or time zones. + +**Pattern.** + +- Americas: US-based AEs. +- EMEA: European AEs. +- APAC: APAC AEs. + +**Why it works.** Time zone alignment; cultural fit; language fit. + +**Failure modes.** + +- Insufficient coverage in some regions. +- Cross-region accounts confuse routing. +- Geography data missing or wrong. + +--- + +## Routing-by-language + +Native-language reps for non-English-primary leads. + +**Pattern.** + +- English-primary: US/UK AEs. +- Spanish-primary: Spanish-speaking AEs. +- Etc. + +**Why it works.** Native-language conversation produces better calls. + +**Failure modes.** + +- Incomplete language coverage. +- Multi-language leads bounce. +- Language inferred wrong from email or location. + +--- + +## Routing-by-account-ownership + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +**Pattern.** + +- Detect domain match against CRM. +- If match, route to AE who owns the account. +- If no match, default routing. + +**Why it works.** Account owner has context; avoids confusion. + +**Failure modes.** + +- Domain detection misses subsidiaries or aliases. +- Account ownership stale (former AE). +- New lead from existing account but for unrelated use case. + +--- + +## Routing-by-source + +Different reps for different lead sources (paid, organic, partner, referral). + +**Pattern.** + +- Partner-sourced leads: partner-channel AE. +- Paid-sourced leads: marketing-aligned AEs. +- Organic-sourced: general AEs. + +**Why it works.** Different sources signal different commitment; specialists handle differently. + +**Failure modes.** + +- Source data missing or attribution wrong. +- Paid traffic includes high-fit leads who would have come organically. + +--- + +## Routing-by-tier + +Combining size, use case, and other signals into a tier score. + +**Pattern.** + +- Lead score 80-100: senior AE. +- Lead score 50-79: AE. +- Lead score 0-49: SDR or async. + +**Why it works.** Single score combines multiple signals. + +**Failure modes.** + +- Score model out of date. +- Score thresholds wrong for current capacity. +- Score data incomplete; defaults dominate. + +--- + +## The unrouted-lead default + +Some leads do not fit obvious routing. + +**Patterns for default.** + +- **Round-robin among all available reps.** Simple. +- **Catchall AE.** One rep gets all unrouted leads. +- **Async or self-serve.** Lead goes to a self-serve resource if no obvious rep. + +**The discipline.** Default rule should be explicit. Unrouted leads should not silently fail or bounce. + +--- + +## Routing transparency + +Prospect-side vs rep-side visibility. + +**Prospect-side.** Generally, prospects do not see routing logic. They see a calendar with available times. + +**Rep-side.** Reps should see why they were assigned (lead score, fit signals). Helps with prep. + +**Anti-pattern.** Routing happens silently; rep does not know what made this lead route to them. + +--- + +## Routing changes and team transitions + +When the team changes, routing must follow. + +**Common transitions.** + +- Rep leaves; their accounts and routing reassign. +- New rep hires; routing weights adjust. +- Tier restructure (rep promoted from SDR to AE). +- Specialty changes. + +**The maintenance discipline.** Routing rules update as team changes. Stale routing can route leads to absent reps. + +--- + +## Routing analytics + +Track routing effectiveness. + +**Metrics.** + +- Per-rep booking volume. +- Per-rep conversion (booking-to-sale). +- Per-route conversion (route x → sale rate). +- Routing override rate (manual reassignments). + +**Diagnostic uses.** + +- Per-rep volume uneven without reason: routing logic skewing. +- Per-route conversion uneven: routing matching wrong. +- High override rate: routing logic not capturing real fit. + +--- + +## Common routing failures + +**Routing data missing.** Qualification did not capture; routing defaults dominate. + +**Stale routing rules.** Team changed; rules did not. + +**Stale rep weights.** Performance scores from quarters ago. + +**Account-ownership detection wrong.** Subsidiary leads route to unfit AE. + +**Specialty routing without specialty data.** Specialty-based routing requires tagging; tags miss. + +**Default rule unclear.** Unrouted leads silently fail. + +**Routing override frequent.** Reps reassign manually; routing logic does not match reality. + +**Round-robin for tiered team.** High-fit leads land on junior reps. + +--- + +## Methodology-level choices that stay in the public skill + +Routing patterns by size, use case, geography, language, account ownership, source, tier. The unrouted-lead default. Routing transparency. Team transitions. Routing analytics. Common failures. + +## Implementation choices that stay internal + +Specific routing rules for specific teams. Specific size bands and tier thresholds. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md b/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md new file mode 100644 index 0000000..6b3c225 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md @@ -0,0 +1,209 @@ +# Scheduler anti-patterns + +The patterns that look like schedulers but degrade conversion. Anti-patterns are easy to ship; the cost shows up in booking conversion, downstream call quality, and brand reputation. + +--- + +## The any-time-friction scheduler + +The pattern. Generic booking link with no qualification. + +The signal. Reps show up cold; downstream demo-to-sale conversion poor. + +The cost. Sales capacity used inefficiently; call quality suffers. + +The cure. Add 3-5 qualification fields; route to right rep tier; deliver prep to reps. + +--- + +## The interrogation-gate scheduler + +The pattern. 12-field qualification form before booking. + +The signal. 90 percent drop-off at the form. + +The cost. Lose conversions from would-be buyers; only the most committed survive the form. + +The cure. Cut to 3-5 fields; defer additional questions to in-call or post-meeting. + +--- + +## The wrong-rep-tier scheduler + +The pattern. Round-robin routing for tiered team. + +The signal. Enterprise leads land on SDRs; SDRs unprepared; conversion drops. + +The cost. High-value leads get junior reps; senior reps underutilized. + +The cure. Fit-based routing tied to qualification. + +--- + +## The no-prep-automation scheduler + +The pattern. Qualification captured but not delivered to reps. + +The signal. Reps start calls cold despite qualification data existing. + +The cost. Qualification work wasted; cold-call dynamics return. + +The cure. CRM enrichment, calendar invite enrichment, Slack briefs. + +--- + +## The no-buffer scheduler + +The pattern. Back-to-back meetings without buffer time. + +The signal. Reps run late; calls feel rushed; quality drops. + +The cost. Reps stressed; calls poorer; conversion suffers. + +The cure. 10-15 minute buffer between meetings. + +--- + +## The no-capacity-cap scheduler + +The pattern. Reps booked solid all day every day. + +The signal. Quality drops; rep burnout. + +The cost. Calls that book are lower quality; reps eventually leave. + +The cure. Cap meetings per day per rep (3-5 typical). + +--- + +## The time-zone-confused scheduler + +The pattern. Times shown in rep's time zone; prospect has to convert mentally. + +The signal. Wrong-time bookings; no-shows from time zone errors. + +The cost. Prospects miss meetings; assume their fault. + +The cure. Auto-detect prospect time zone; display explicitly. + +--- + +## The aggressive-reminder scheduler + +The pattern. Multiple reminders per booking (5+ touchpoints). + +The signal. Prospects mute or unsubscribe; reminder effectiveness drops. + +The cost. Reminders trained to be ignored; no-shows persist. + +The cure. Two reminders typical (24-hour, 1-hour). Cap cumulative volume. + +--- + +## The aggressive-no-show-recovery scheduler + +The pattern. Multiple reschedule attempts over short period. + +The signal. Brand earns harassment reputation; recovery rate drops. + +The cure. One-to-two reschedule attempts max; respect non-response. + +--- + +## The aggressive-cancellation-prevention scheduler + +The pattern. Cancellation requires multi-step or contact with sales. + +The signal. Public complaints; trust damage. + +The cost. Reputation harm; sometimes regulatory issues. + +The cure. Self-serve cancellation; one click. + +--- + +## The unmaintained scheduler + +The pattern. Routing rules from years ago; team changed; rules did not. + +The signal. Leads route to absent reps; bookings sit unread. + +The cure. Quarterly maintenance. Team transitions trigger routing updates. + +--- + +## The mobile-broken scheduler + +The pattern. Booking flow works on desktop; breaks on mobile. + +The signal. Mobile conversion half of desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. + +--- + +## The double-booking scheduler + +The pattern. Calendar integration broken; multiple bookings for same time. + +The signal. Reps and prospects both arrive; one waits or leaves. + +The cost. Rep frustration; prospect confusion; brand damage. + +The cure. Calendar integration tested. Buffer time. Conflict detection. + +--- + +## The shared-link bypass scheduler + +The pattern. Reps share generic booking links alongside structured flow. + +The signal. Routing logic bypassed; cold demos return. + +The cost. Investment in qualification and routing partially undone. + +The cure. Disable generic links. Train reps to use structured links. + +--- + +## The integration-brittle scheduler + +The pattern. Calendar, CRM, or video integration breaks frequently. + +The signal. Reps complain about manual workarounds. + +The cost. Operational friction; data inconsistency. + +The cure. Stable integrations; monitoring; rollback plans. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of scheduler portfolio. + +**Audit questions.** + +- Is qualification calibrated (anti-pattern check: any-time-friction, interrogation-gate)? +- Does routing match team tier (anti-pattern check: wrong-rep-tier)? +- Does prep automation deliver (anti-pattern check: no-prep-automation)? +- Is calendar logic sound (anti-pattern check: no-buffer, no-capacity-cap, double-booking)? +- Are reminders calibrated (anti-pattern check: aggressive-reminder)? +- Is no-show recovery respectful (anti-pattern check: aggressive-no-show-recovery)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does the system work on mobile (anti-pattern check: mobile-broken)? +- Are integrations stable (anti-pattern check: integration-brittle)? + +**The retire decision.** Anti-pattern schedulers warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md b/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md new file mode 100644 index 0000000..62327fe --- /dev/null +++ b/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md @@ -0,0 +1,175 @@ +# Scheduler decision criteria + +When schedulers earn the build vs when forms or sales-pipeline tools serve. + +A scheduler is meaningful work. Qualification logic, availability rules, routing, prep automation, follow-up sequences, ongoing maintenance. The scheduler earns this investment only when specific conditions are present. + +--- + +## When schedulers earn the build + +Five conditions that, when present, make a scheduler a strong investment. + +**The conversion goal is a meeting.** Demo, sales call, consultation. Email-only or trial-signup conversions do not need a scheduler. + +**The audience is willing to commit time.** Schedulers ask for a calendar slot; not all audiences are ready for that. Top-of-funnel awareness audiences are usually not ready; consideration-stage audiences often are. + +**The team has enough capacity to handle scheduled meetings.** Without capacity, scheduled meetings produce wait times that erode conversion. Reps booked solid for two weeks lose conversions to faster competitors. + +**The team can support qualification logic and routing.** Without these, a generic booking link is the result. Generic booking links produce cold demos. + +**The success metric is defined.** Booking conversion, demo-to-sale conversion, no-show rate, call quality (often measured via rep self-reports). Without the success metric, evaluation is impossible. + +When all five are present, a scheduler is strong investment. When two or fewer are present, simpler tools (contact forms, sales pipeline outreach) often serve better. + +--- + +## When schedulers do NOT earn the build + +Funnels where the scheduler is the wrong tool. + +**The conversion goal is a download or signup.** Use forms (covered by `multi-step-form-design`) or magnet flows (covered by `lead-magnet-design`). + +**The audience volume is too low.** A handful of bookings per month does not need routing infrastructure; a contact form may serve better. + +**The team's capacity is variable and routing cannot reflect it.** Scheduling without capacity awareness produces booked-too-tight or booked-too-loose patterns; both fail. + +**A simpler contact form would serve.** Inbound leads where sales does outbound contact may not need a scheduler; the prospect just provides info; the rep reaches out. + +**The audience prefers async communication.** Some audiences (technical buyers, asynchronous teams) prefer email or document exchange to scheduled calls. + +The honest assessment matters. Schedulers are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Schedulers vs forms + +Both capture lead info; they differ in commitment. + +**Form strengths.** + +- Lower commitment from the prospect. +- Higher top-of-funnel volume. +- Suitable for any conversion type (download, demo request, contact). + +**Form weaknesses.** + +- No automatic time commitment. +- Requires sales follow-up to schedule. +- Wait time between form submission and meeting. + +**Scheduler strengths.** + +- Time committed at booking; no scheduling delay. +- Higher prospect commitment signal. +- Direct conversion to a calendar slot. + +**Scheduler weaknesses.** + +- Higher friction; not all prospects ready. +- Requires capacity to handle bookings. +- Routing complexity. + +**The choice.** When the conversion is a meeting and the audience is consideration-stage, scheduler. When the conversion is more open or the audience is awareness-stage, form. + +--- + +## Schedulers vs sales-pipeline tools + +For B2B sales, alternatives exist. + +**Sales pipeline strengths.** + +- Sales-led; rep makes contact on their schedule. +- Can prioritize based on fit before reaching out. + +**Sales pipeline weaknesses.** + +- Slower response. +- Higher acquisition cost per booking. + +**Scheduler advantages.** + +- Self-serve; faster response. +- Lower acquisition cost. + +**The combined approach.** Many production teams use both: scheduler for self-serve high-intent leads; sales pipeline for outbound and complex deals. + +--- + +## The opportunity-cost frame + +A scheduler is significant work. Account for it. + +**The build cost.** Qualification logic, availability rules, routing, prep automation, reminder sequences, integration with CRM and calendar, mobile responsiveness. A meaningful scheduler often takes 40-150 engineering hours plus operational setup. + +**The maintenance cost.** Routing rules update as team changes; integrations need maintenance. Quarterly review and updates run 4-8 hours. + +**The opportunity cost.** What else could the team have built? A simpler contact form, a better sales-led process, direct outreach. The scheduler has to clear the bar of those alternatives. + +The decision frame. Scheduler earns investment when it produces more meeting volume at acceptable quality than alternatives. + +--- + +## Decision worked example + +A B2B SaaS with 50 demo requests per week. + +**Conditions check.** + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes (mid-market audience). +- Team capacity: yes; 4 reps with capacity for 12-15 demos per week each. +- Qualification and routing supported: yes; reps differ by industry vertical. +- Success metric defined: booking conversion, demo-to-trial within 14 days. + +**Decision.** Build the scheduler. The conditions warrant it. + +**Architecture.** 4-field qualification (size, role, use case, timeline); fit-based routing (enterprise to senior AE, mid-market to AE, SMB to SDR); CRM enrichment and Slack brief for prep automation. + +**Maintenance commitment.** Quarterly review; team-change updates as part of onboarding. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A consumer-facing financial advisory company with 5 inbound consultations per week. + +**Conditions check.** + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes. +- Team capacity: yes (3 advisors). +- Qualification and routing supported: not really; advisors are interchangeable. +- Volume justifies scheduler infrastructure: low. + +**Decision.** Do not build a custom scheduler. Use a generic booking link with a brief 2-field qualification form. The volume does not justify routing infrastructure; the simplicity is fine. + +The decision was right-sized. + +--- + +## When to retire a scheduler + +Schedulers can become wrong over time. + +**Retire-or-redesign when:** + +- Conversion has dropped below baseline consistently and refinements have not moved it. +- Team structure changed; routing logic no longer fits. +- Volume changed; infrastructure no longer matches need. +- Integration with CRM or calendar has broken repeatedly. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant schedulers. The five conditions that argue against. Schedulers vs forms. Schedulers vs sales-pipeline tools. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific scheduler decisions for specific teams. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/security-baseline/SKILL.md b/skills/security-baseline/SKILL.md new file mode 100644 index 0000000..bd3f1ec --- /dev/null +++ b/skills/security-baseline/SKILL.md @@ -0,0 +1,296 @@ +--- +name: security-baseline +description: "Establish a security baseline for a website or web app. Use this skill when configuring HTTPS and TLS, setting security headers, planning secrets management, evaluating CSP policies, doing a basic security audit, or hardening a site before launch. Triggers on security headers, HTTPS, TLS, CSP, content security policy, HSTS, secrets management, vulnerability scan, security audit, harden, OWASP, security baseline. Also triggers when a security review is required for compliance or before going live." +category: operations +catalog_summary: "HTTPS, security headers, CSP, secrets management, vulnerability scans" +display_order: 7 +--- + +# Security Baseline + +Establish the security floor for any production website or web app. Stack-agnostic. Covers the things that should be in place before public launch and verified periodically after. + +--- + +## When to use + +- Pre-launch security review +- Setting up a new site or environment +- Periodic security audit (quarterly recommended) +- Onboarding a new vendor or third-party integration +- Responding to a security finding or report +- Hardening after an incident + +## When NOT to use + +- Active incident response (use `incident-response`) +- Code-level security review (use `code-review-web`) +- Email-specific authentication (SPF/DKIM/DMARC) (use `email-deliverability`) +- DNS-level security (CAA, DNSSEC) (use `domain-strategy`) +- Performance-related security (DDoS protection sizing) (use `performance-optimization`) + +--- + +## Required inputs + +- The site or app in scope (URLs, environments) +- The hosting platform and CDN +- Authentication method (if any) +- Third-party scripts and integrations +- Compliance context (PCI, SOC2, GDPR, etc., if applicable) +- Existing security tooling + +--- + +## The framework: 6 layers + +Security is layered. Each layer addresses a different attack surface. + +### Layer 1: Transport security + +How data moves from server to client. + +- HTTPS everywhere. No HTTP variants serving content. +- TLS 1.2 minimum, TLS 1.3 preferred. Disable TLS 1.0 and 1.1. +- HSTS (Strict-Transport-Security) header set, with `includeSubDomains` and `preload` for high-confidence sites. +- Strong cipher suites only. Modern browsers handle this if you pick a modern config from your provider. +- Certificates from a trusted CA, monitored for expiration. + +### Layer 2: Response headers + +What the browser is told about your site. + +| Header | Purpose | Default value | +|---|---|---| +| `Strict-Transport-Security` | Force HTTPS | `max-age=31536000; includeSubDomains` | +| `Content-Security-Policy` | Restrict resource loading | Site-specific | +| `X-Content-Type-Options` | Prevent MIME sniffing | `nosniff` | +| `X-Frame-Options` | Clickjacking protection | `DENY` or `SAMEORIGIN` | +| `Referrer-Policy` | Control referrer info | `strict-origin-when-cross-origin` | +| `Permissions-Policy` | Control browser features | Site-specific (camera, mic, etc.) | +| `Cross-Origin-Opener-Policy` | Process isolation | `same-origin` (where compatible) | +| `Cross-Origin-Embedder-Policy` | Cross-origin restrictions | `require-corp` (where applicable) | + +CSP deserves its own attention. See the framework section below. + +### Layer 3: Authentication and authorization + +How users prove who they are and what they can do. + +- Strong password requirements (length over complexity rules; allow long passphrases) +- Account lockout or rate limiting on login +- 2FA available, required for admin accounts +- Session tokens: short-lived, secure, HttpOnly cookies +- Logout invalidates tokens server-side, not just client-side +- Password reset flows that don't reveal account existence +- Authorization checked on every request (don't rely on UI hiding) + +### Layer 4: Input handling + +How untrusted input is processed. + +- Validate on the server (client validation is UX, not security) +- Parameterized queries for any database access (no string concatenation into SQL) +- Output encoding by context (HTML, JS, URL, CSS) +- File upload restrictions (type, size, location, scanning) +- Rate limiting on endpoints that could be abused +- CSRF tokens on state-changing requests + +### Layer 5: Secrets management + +Where credentials and keys live. + +- No secrets in code, config files in repos, or environment variables baked into images +- Secrets in a dedicated secrets manager +- Different secrets per environment (no shared dev/prod secrets) +- Rotation schedule documented and followed +- Audit log of secret access +- Limited blast radius (each service has its own credentials, scoped narrowly) + +### Layer 6: Operational security + +How the team operates. + +- Access controls reviewed quarterly (offboard immediately on departure) +- 2FA enforced on every admin account (hosting, DNS, registrar, code host, deploy tools) +- Audit logs enabled and reviewed +- Vulnerability scanning (dependencies, containers, infrastructure) +- Patch cadence defined +- Incident response runbook exists (see `incident-response`) +- Backups exist and are tested (see `backup-and-disaster-recovery`) +- Security contact published (security.txt at /.well-known/security.txt) + +--- + +## Content Security Policy + +CSP is the most powerful response header and the most often misconfigured. Worth its own treatment. + +### What CSP does + +CSP tells the browser which sources are allowed for various resource types: scripts, styles, images, frames, connections, etc. A strict CSP prevents most XSS attacks even when input handling has bugs. + +### Two flavors + +**Strict CSP (recommended):** uses `nonce-` or `hash-` based source allowlists. Inline scripts must be explicitly allowed via nonce. + +``` +Content-Security-Policy: script-src 'self' 'nonce-{random}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; +``` + +**Allowlist CSP (legacy):** lists allowed domains. Easier to set up, much weaker. + +``` +Content-Security-Policy: script-src 'self' https://trusted.com; ... +``` + +Strict CSP requires application changes (every inline script needs a nonce). The investment pays off. + +### Roll out CSP gradually + +1. Start with `Content-Security-Policy-Report-Only` to log violations without blocking. +2. Set up a violation report endpoint. +3. Watch for legitimate violations (third-party scripts, inline handlers). +4. Tune the policy. +5. Switch to enforcing mode once violations are mostly false positives. +6. Continue monitoring violation reports for new issues. + +### Common CSP mistakes + +- `unsafe-inline` in script-src. Defeats most of CSP's value. +- `unsafe-eval` in script-src. Often required by older libraries; refactor or replace. +- Wildcard sources (`*`). Defeats the policy. +- Allowing CDNs that host arbitrary user content. Attackers can upload scripts to the CDN. +- Not restricting `frame-ancestors`. Use this for clickjacking defense (more flexible than `X-Frame-Options`). + +--- + +## Workflow + +### Step 1: Run a baseline scan + +Use a free scanner: securityheaders.com, observatory.mozilla.org. Get a current grade. This is the floor. + +### Step 2: Inventory the surface + +- Domains and subdomains in scope +- Public endpoints (forms, APIs) +- Authentication entry points +- Admin interfaces +- Third-party integrations and their permissions + +### Step 3: Audit each layer + +Walk the 6 layers. For each, document: +- What's in place +- What's missing +- Risk level (high, medium, low) + +### Step 4: Prioritize + +High risk, easy fixes go first: +- HSTS not set +- Default headers missing +- Admin without 2FA +- Old TLS versions enabled + +Medium risk, medium fixes next: +- CSP rollout +- Input validation gaps +- Secret management improvements + +Low risk, nice-to-haves last: +- Permissions-Policy refinements +- Optional headers (Cross-Origin-* family) + +### Step 5: Implement and verify + +For each fix: +- Make the change +- Test in a non-production environment +- Verify with a scanner +- Roll out +- Re-verify in production + +### Step 6: Set up monitoring + +- Certificate expiration alerts +- CSP violation reporting +- Failed login monitoring +- Unusual admin activity alerts +- Dependency vulnerability alerts (Dependabot, Snyk, or equivalent) + +### Step 7: Document the baseline + +Write a security baseline document. It says what's expected on every site: +- Required headers +- Required configurations +- Required practices + +New sites get audited against this. Existing sites get re-audited periodically. + +### Step 8: Schedule review + +Quarterly is the floor. Add reviews after major changes or incidents. + +--- + +## Common compliance touchpoints + +Not legal advice. Surfaces where security baseline meets compliance requirements: + +- **PCI DSS** (if handling payment cards): much more involved than baseline. The baseline is a starting point, not sufficient. +- **SOC 2:** baseline aligns with most CC controls (CC6 series). Documented baseline plus evidence of execution is the audit ask. +- **GDPR / privacy regs:** baseline supports security obligations (Article 32). Privacy is broader than security. +- **HIPAA, HITRUST, FedRAMP:** baseline is necessary, far from sufficient. Get specialized help. + +When compliance applies, the baseline is necessary but not the full answer. + +--- + +## Failure patterns + +**HSTS without `includeSubDomains`.** Attacker tricks browser into HTTP on a subdomain you haven't HTTPS'd yet. + +**HSTS preload without commitment.** Once preloaded, removing it takes weeks. Don't preload until HTTPS is solid across all subdomains forever. + +**CSP with `unsafe-inline`.** Defeats most of CSP. Either go strict (nonce-based) or accept that CSP is providing limited protection. + +**Default headers missing.** `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` are easy and free. Set them. + +**Admin without 2FA.** The single most common high-impact vulnerability across small teams. Fix today. + +**Secrets in environment variables baked into images.** Anyone with image access has the secrets. Use a runtime secret manager. + +**No security.txt.** Researchers find issues; they need somewhere to report. Publish a security.txt at /.well-known/security.txt. + +**Old TLS versions enabled.** Disable TLS 1.0 and 1.1. Most providers offer this as a checkbox. + +**CDN allowing arbitrary inline scripts via misconfigured CSP.** The CDN proxies user content; attackers leverage that. Audit the CSP against actual loaded resources. + +**No incident response plan.** When (not if) something happens, no runbook = chaos. See `incident-response`. + +**Vulnerability scanning without remediation.** Reports pile up. The scan is theater unless someone fixes findings. + +**Penetration test ignored.** Pen test report sits on a shelf. Test results without remediation are worse than no test. + +--- + +## Output format + +A security baseline document includes: + +- **Inventory:** what's in scope +- **Layer-by-layer status:** what's in place, what's missing +- **Required headers:** with values, applied per environment +- **Required configurations:** TLS, secrets, auth +- **Required operational practices:** access reviews, patch cadence, audit logging +- **Findings:** prioritized list of gaps +- **Remediation plan:** owners, dates +- **Re-audit cadence:** when this is reviewed next + +--- + +## Reference files + +- [`references/headers-checklist.md`](references/headers-checklist.md): A copy-paste checklist of recommended security headers with example values, organized by tier of importance. diff --git a/skills/security-baseline/references/headers-checklist.md b/skills/security-baseline/references/headers-checklist.md new file mode 100644 index 0000000..3a847f9 --- /dev/null +++ b/skills/security-baseline/references/headers-checklist.md @@ -0,0 +1,311 @@ +# Security Headers Checklist + +Copy-paste reference for HTTP response headers that improve security. Organized by tier of importance. + +Test current headers with: securityheaders.com or observatory.mozilla.org. + +--- + +## Tier 1: Set on every site, no excuse + +These are simple to deploy, low risk of breaking things, and material security improvements. + +### Strict-Transport-Security (HSTS) + +Forces browsers to use HTTPS for all future requests to this domain. + +``` +Strict-Transport-Security: max-age=31536000; includeSubDomains +``` + +- `max-age`: lifetime in seconds (31536000 = 1 year, recommended for stable HTTPS deployments) +- `includeSubDomains`: applies to all subdomains. Only enable when every subdomain serves HTTPS reliably. +- `preload`: optional. Enables inclusion in browser preload lists. Once enabled, removal takes weeks. Only add when committed. + +**Common mistake:** Setting `includeSubDomains` before all subdomains are HTTPS-ready. Internal staging or admin subdomains break. + +--- + +### X-Content-Type-Options + +Prevents browsers from MIME-sniffing the content type, which can lead to confusion attacks. + +``` +X-Content-Type-Options: nosniff +``` + +No nuance. Set it everywhere. + +--- + +### X-Frame-Options + +Prevents your site from being framed by other sites (clickjacking defense). + +``` +X-Frame-Options: DENY +``` + +Use `SAMEORIGIN` instead if your own site uses iframes of itself. + +`X-Frame-Options` is largely superseded by CSP's `frame-ancestors`, but setting both is fine for backward compatibility with older browsers. + +--- + +### Referrer-Policy + +Controls how much information is sent in the Referer header on outbound links and resource loads. + +``` +Referrer-Policy: strict-origin-when-cross-origin +``` + +This sends full URL on same-origin requests, only the origin on cross-origin HTTPS-to-HTTPS, and nothing on HTTPS-to-HTTP downgrades. + +For privacy-sensitive sites: + +``` +Referrer-Policy: no-referrer +``` + +--- + +## Tier 2: Material security improvements, requires planning + +These add real protection but may require code changes or rollout planning. + +### Content-Security-Policy + +The most powerful header. Prevents most XSS attacks even when input handling has bugs. + +**Strict CSP (recommended for new sites):** + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' 'nonce-{random}' 'strict-dynamic'; + style-src 'self' 'nonce-{random}'; + img-src 'self' data: https:; + font-src 'self'; + connect-src 'self'; + frame-ancestors 'none'; + base-uri 'self'; + form-action 'self'; + object-src 'none'; + upgrade-insecure-requests; +``` + +**Notes:** +- `nonce-{random}` is replaced per request with a fresh random token, included on legitimate inline scripts. +- `'strict-dynamic'` allows scripts loaded by trusted scripts (recursive trust). Most modern apps need this. +- `frame-ancestors 'none'` is the modern equivalent of `X-Frame-Options: DENY` and is more flexible. +- `object-src 'none'` blocks Flash and similar (still useful even though Flash is dead). +- `base-uri 'self'` prevents base tag hijacking. + +**Allowlist CSP (if you can't do strict):** + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' https://trusted-cdn.com; + style-src 'self' 'unsafe-inline'; + img-src 'self' data: https:; + ... +``` + +This is weaker than strict CSP. Plan to migrate to strict. + +**Roll out via Report-Only first:** + +``` +Content-Security-Policy-Report-Only: ...; report-uri /csp-violation-report +``` + +Watch reports, tune, then switch to enforcing. + +--- + +### Permissions-Policy + +Controls which browser features (camera, microphone, geolocation, etc.) can be used. + +Conservative default: + +``` +Permissions-Policy: + accelerometer=(), + camera=(), + geolocation=(), + gyroscope=(), + magnetometer=(), + microphone=(), + payment=(), + usb=(), + interest-cohort=() +``` + +This denies all listed features by default. Allow specific ones if needed: + +``` +Permissions-Policy: camera=(self), geolocation=(self "https://maps.example.com") +``` + +`interest-cohort=()` opts the site out of FLoC and similar third-party tracking. + +--- + +## Tier 3: Newer, useful in specific contexts + +These provide additional isolation and protection. Some require more careful integration. + +### Cross-Origin-Opener-Policy (COOP) + +Isolates your site's window from cross-origin windows. Defends against cross-origin attacks like Spectre. + +``` +Cross-Origin-Opener-Policy: same-origin +``` + +May break some popup-based OAuth flows. Test carefully. + +--- + +### Cross-Origin-Embedder-Policy (COEP) + +Required for `SharedArrayBuffer` and high-resolution timers. Restricts what can be loaded. + +``` +Cross-Origin-Embedder-Policy: require-corp +``` + +Means every cross-origin resource you load must explicitly opt in via `Cross-Origin-Resource-Policy: cross-origin`. + +Often impractical for sites with many third-party resources. Use `credentialless` as a softer option: + +``` +Cross-Origin-Embedder-Policy: credentialless +``` + +--- + +### Cross-Origin-Resource-Policy (CORP) + +For your own resources (images, scripts, styles), declares who can include them. + +``` +Cross-Origin-Resource-Policy: same-origin +``` + +For resources you want others to be able to embed (a public CDN, a sharing widget): + +``` +Cross-Origin-Resource-Policy: cross-origin +``` + +--- + +### Reporting-Endpoints + +Modern way to specify where violation reports go (replaces the older `report-uri`). + +``` +Reporting-Endpoints: csp-endpoint="https://example.com/csp", default="https://example.com/reports" +Content-Security-Policy: ...; report-to csp-endpoint +``` + +--- + +## Headers to remove or set carefully + +### Server + +The `Server` header reveals what server software is running. + +``` +Server: nginx/1.18.0 +``` + +Reveals software and version. Helps attackers target known vulnerabilities. Set to a generic value or remove: + +``` +Server: web +``` + +(Or remove entirely if your stack allows.) + +--- + +### X-Powered-By + +Reveals the framework or language. + +``` +X-Powered-By: Express +X-Powered-By: PHP/8.0 +``` + +Same issue as `Server`. Remove. + +--- + +### X-AspNet-Version, X-AspNetMvc-Version + +Same. Remove. + +--- + +## What to skip + +These are deprecated, not useful, or actively harmful: + +- **`X-XSS-Protection`**: deprecated. Modern browsers ignore it. Use CSP instead. +- **`Public-Key-Pins`** (HPKP): removed from browsers. Don't bother. +- **`Expect-CT`**: deprecated. Certificate Transparency is enforced automatically. +- **`Feature-Policy`**: replaced by `Permissions-Policy`. Use the latter. + +--- + +## Quick reference table + +| Header | Tier | Default value | +|---|---|---| +| `Strict-Transport-Security` | 1 | `max-age=31536000; includeSubDomains` | +| `X-Content-Type-Options` | 1 | `nosniff` | +| `X-Frame-Options` | 1 | `DENY` (or `SAMEORIGIN`) | +| `Referrer-Policy` | 1 | `strict-origin-when-cross-origin` | +| `Content-Security-Policy` | 2 | Site-specific (see strict CSP example) | +| `Permissions-Policy` | 2 | Site-specific (deny by default) | +| `Cross-Origin-Opener-Policy` | 3 | `same-origin` | +| `Cross-Origin-Embedder-Policy` | 3 | `require-corp` or `credentialless` | +| `Cross-Origin-Resource-Policy` | 3 | `same-origin` (resources), `cross-origin` (public) | +| `Server` | Remove | Set generic or remove | +| `X-Powered-By` | Remove | Remove | + +--- + +## Verification + +After deploying, verify: + +```bash +curl -I https://example.com +``` + +Look for the headers in the response. + +Test grade: securityheaders.com gives a letter grade. Aim for A or A+. + +--- + +## Setting headers by stack + +Where you set these depends on the stack. Common locations: + +- **Reverse proxy (Nginx, Caddy, HAProxy):** in the proxy config +- **CDN (Cloudflare, Fastly, Akamai):** in the CDN's response header rules +- **Application (Express, Django, Rails, etc.):** middleware or filter +- **Hosting platform (Vercel, Netlify, Cloudflare Pages):** platform-specific config file (e.g., `vercel.json`, `_headers`) + +Setting at the edge (CDN or proxy) is preferred when possible: applies to every response without depending on application code. + +For dynamic values (like the CSP nonce), the header has to be set per-request from the application. diff --git a/skills/seo-aeo-geo/SKILL.md b/skills/seo-aeo-geo/SKILL.md new file mode 100644 index 0000000..c60a7b4 --- /dev/null +++ b/skills/seo-aeo-geo/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-aeo-geo +description: "Optimize content and site structure for AI-driven search experiences including AI overviews, large language model citations, generative answer engines, and AI assistants. Use this skill whenever the user wants to optimize for AI search, get cited by language models, appear in AI overviews, build llms.txt, structure content for AI extraction, or future-proof their SEO for the shift from blue links to AI answers. Triggers on AEO, GEO, AI search, AI SEO, AI overview, generative search, LLM optimization, llms.txt, AI citation, ChatGPT search, Perplexity, Gemini, Claude search, AI assistant optimization, answer engine. Also triggers when the user expresses concern about AI eating their organic traffic or wants to understand how to remain visible as search shifts." +category: seo-foundation +catalog_summary: "AI search optimization, llms.txt, extraction-friendly content" +display_order: 7 +--- + +# AEO and GEO + +Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO). Make content discoverable, extractable, and citable by AI search experiences. + +This skill encodes principles. AI search products evolve fast. The principles age slower than the products. + +--- + +## When to use + +- Optimizing content for AI overviews and generative answer engines +- Building or updating llms.txt +- Structuring content so AI assistants can extract and cite it correctly +- Future-proofing a site as search shifts from blue links to AI answers +- Auditing whether existing content is AI-friendly +- Adding signals that help AI assistants identify the site as a trustworthy source + +## When NOT to use + +- Traditional on-page or technical SEO (use `seo-onpage` or `seo-technical`) +- Keyword research (use `seo-keyword`) +- Off-page authority and link building (use `seo-offpage`) + +This skill stacks on top of those. Strong AEO/GEO requires strong fundamental SEO underneath. + +--- + +## Required inputs + +- The site or page to optimize +- The topic area or query types AI should cite the site for +- Access to inspect rendered HTML and structured data + +--- + +## The framework: 5 layers + +AI search visibility comes from five stacked layers. Each layer compounds. + +### 1. Extractable content structure + +AI systems extract facts and pull citations from content. Make extraction easy. + +- **Direct answers.** Open major sections with a definitive 1 to 3 sentence answer to the question that section addresses. AI extracts the first answer it sees. +- **Question-headers.** Use H2s and H3s phrased as questions when natural. Mirrors how people prompt AI. +- **Atomic facts.** When stating a fact, state it once, clearly, with the supporting context next to it. AI struggles when claims are spread across paragraphs. +- **Tables and lists.** AI parses these reliably. Use them for comparisons, specs, steps, and data. +- **Definitions early.** When introducing a concept, define it inline. Do not assume the reader (or AI) saw a definition three pages ago. +- **Numbered steps.** For procedural content, number every step. Avoid prose disguised as instructions. + +### 2. Citation worthiness + +AI cites sources it considers authoritative. Earn that consideration. + +- **Original data.** Surveys, studies, proprietary research, internal benchmarks. AI prefers primary sources over restatements. +- **Specific numbers.** "Roughly 40 percent" beats "many." Specific stats with sources beat round-number generalizations. +- **Named experts.** Author bios with credentials, links to professional profiles, schema-marked-up Person entities. +- **Date stamps.** Publication date AND last-updated date, both visible AND in schema. AI heavily weights recency for time-sensitive queries. +- **Methodology disclosure.** When stating a finding, briefly note how it was reached. AI rewards transparency. +- **Citations of other sources.** Linking to authoritative sources you used builds reciprocal credibility. + +### 3. Structured data depth + +Schema is how you speak machine-readable language. AI assistants parse it heavily. + +- **Schema.org types** appropriate to content (Article, FAQPage, HowTo, Recipe, Product, Organization, Person, LocalBusiness, etc.) +- **Required AND recommended properties** filled in (most sites only fill required, leaving signal on the table) +- **Person schema** for authors, with `sameAs` links to verifiable profiles +- **Organization schema** on the homepage with logo, contact, social links +- **FAQPage schema** for content with genuine question-answer pairs +- **HowTo schema** for procedural content +- **BreadcrumbList schema** site-wide +- Validates in Schema.org Validator AND Rich Results Test (some properties differ) + +### 4. AI-readable accessibility + +Beyond traditional SEO, AI tools need access patterns of their own. + +- **llms.txt at the site root.** A markdown file at `/llms.txt` describing the site's content, key URLs, and what topics the site covers. See [`references/llms-txt-guide.md`](references/llms-txt-guide.md). +- **llms-full.txt** (optional) - a complete content dump for AI training and context, if the site permits it. +- **robots.txt allowing AI crawlers.** Decide explicitly which AI crawlers to allow (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, etc.) or disallow. Do not block by default if visibility matters. +- **Clean HTML semantics.** Semantic tags (`article`, `section`, `nav`, `main`) help AI parse structure. +- **Avoid client-side-only rendering for critical content.** Many AI crawlers render less reliably than Googlebot. + +### 5. Real-world entity signals + +AI builds knowledge graphs and prefers entities with multiple consistent signals. + +- **Wikipedia entry** if the brand or person qualifies for notability (do not force this; it requires genuine notability) +- **Wikidata entry** for the entity, with consistent properties +- **Consistent NAP** (Name, Address, Phone) across all citations +- **Brand mentions across multiple authoritative sources.** AI cross-references entity claims across the open web. +- **Social profile schema** linking owned profiles via `sameAs` properties +- **Reviews and reputation signals.** Aggregate ratings on Google Business, Trustpilot, industry-specific review sites where applicable + +--- + +## Workflow + +1. **Audit current state.** Run the 5-layer framework against the existing site. Score each. +2. **Identify the priority queries.** What questions should AI cite this site for? List 10 to 20. +3. **Test current AI visibility.** Query each of the major AI products (those relevant to the audience) with the priority questions. Note which sources they cite. +4. **Identify gaps.** Is the site cited? On which queries? Why does it lose to the cited sources? +5. **Layer-by-layer plan.** + - Fix extractable structure on top 20 priority pages + - Add citation-worthy signals (original data, expert authorship, methodology) + - Deepen schema implementation + - Build/update llms.txt + - Strengthen entity signals +6. **Implement and re-test.** AI products update frequently. Re-test priority queries quarterly. + +--- + +## Failure patterns + +- **Treating AEO/GEO as separate from SEO.** Strong fundamental SEO is a prerequisite. AI cites pages, not magic. +- **Stuffing FAQ schema on pages that have no genuine FAQs.** Search engines and AI alike penalize manufactured FAQ blocks. +- **Hiding key content behind heavy JavaScript.** AI crawlers render less reliably. Server-render or pre-render critical content. +- **Optimizing for one AI product only.** Different products use different ranking and citation logic. Optimize for the principles, not for one product's quirks. +- **Ignoring entity strength.** Content alone, with no real-world entity signals, will not get cited reliably for branded or expertise-related queries. +- **Treating llms.txt as a magic bullet.** It helps, but it is one of many signals. +- **Static optimization.** AI products evolve faster than search algorithms historically did. Re-audit at least quarterly. + +--- + +## Output format + +Default output is a markdown plan at `aeo-geo-strategy.md`. Structure: + +1. Current AI visibility audit (which queries cite the site, which do not) +2. 5-layer scorecard +3. Priority queries (the 10 to 20 the site should be cited for) +4. Layer-by-layer remediation plan +5. Implementation roadmap +6. Re-test schedule (quarterly) + +--- + +## Reference files + +- [`references/llms-txt-guide.md`](references/llms-txt-guide.md) - How to write a useful llms.txt, with examples. +- [`references/extraction-friendly-patterns.md`](references/extraction-friendly-patterns.md) - Content patterns that AI extracts cleanly, with before/after examples. diff --git a/skills/seo-aeo-geo/references/extraction-friendly-patterns.md b/skills/seo-aeo-geo/references/extraction-friendly-patterns.md new file mode 100644 index 0000000..2906fb1 --- /dev/null +++ b/skills/seo-aeo-geo/references/extraction-friendly-patterns.md @@ -0,0 +1,266 @@ +# Extraction-Friendly Patterns + +Content patterns that AI search experiences extract cleanly, with before-and-after examples. The goal is not to write for AI exclusively. The goal is to write so a human reader gets the answer fast and an AI extractor gets it fast too. The two overlap more than people think. + +--- + +## The principle + +AI extractors and skim-readers want the same thing: the answer first, the supporting context second. Content that buries the answer behind preamble loses both audiences. + +Three structural moves do most of the work: + +1. **Lead with the answer.** First sentence of the section answers the section's question. +2. **Use semantic structure.** Headings name the question. Lists separate items. Tables compare options. Code blocks contain code. +3. **Be self-contained.** Each section should make sense without depending on the section above. + +Everything below is an application of these three moves. + +--- + +## Pattern 1: question-led headings + +Headings phrased as the question the user actually asks. + +### Bad + +> ## Onboarding optimization + +### Better + +> ## How long should employee onboarding take? + +The question form does three jobs at once: it matches likely search queries, it tells the reader what they will learn, and it tells the AI extractor what answer follows. + +--- + +## Pattern 2: answer-first paragraph + +The first sentence answers the question. Subsequent sentences provide context, caveats, and depth. + +### Bad + +> ## How long should employee onboarding take? +> +> Onboarding has many definitions across organizations. Some companies define onboarding as the first day, some as the first week, and others as the entire ramp-up period. There is no industry consensus, and the question depends on many factors. With that said, most modern companies aim for a structured program lasting somewhere between 30 and 90 days. + +### Better + +> ## How long should employee onboarding take? +> +> Most structured onboarding programs run 30 to 90 days, with 90 being the most common. The exact length depends on role complexity, company size, and how much time managers can dedicate. The first week typically covers logistics and culture; the first month adds shadowing and small projects; the second and third months ramp the new hire into full ownership. + +The "Better" version puts the extractable answer in the first sentence. The follow-up adds context without burying the lead. + +--- + +## Pattern 3: definitions in inverse pyramid + +Define the term in one sentence, then expand. + +### Bad + +> ## What is a service blueprint? +> +> A service blueprint is a versatile tool used by many designers and product teams. Originally developed in the 1980s by G. Lynn Shostack at Bankers Trust, it has since been adopted across industries from healthcare to retail. Service blueprints help teams visualize the relationships between people, processes, and physical evidence in a service experience. + +### Better + +> ## What is a service blueprint? +> +> A service blueprint is a diagram that maps every step of a service experience, both what the customer sees and what happens behind the scenes. It typically uses lanes for the customer journey, frontstage actions, backstage actions, and supporting systems. Originally developed by G. Lynn Shostack in the 1980s, it is now standard in service design, healthcare workflow design, and operations planning. + +The first sentence is a complete, extractable definition. AI assistants quoting your page will quote this sentence. Search snippets will lift it. + +--- + +## Pattern 4: numbered lists for sequenced steps + +Sequenced procedures go in numbered lists. Not in prose. + +### Bad + +> To deploy with the CLI, first you'll want to run npm install. Once that completes, run npm run build to generate the production bundle, then npm run deploy to push to your environment. After that, verify the deployment by checking the status endpoint. + +### Better + +> ## How to deploy with the CLI +> +> 1. Install dependencies: `npm install` +> 2. Build the production bundle: `npm run build` +> 3. Deploy to your environment: `npm run deploy` +> 4. Verify the deployment by checking the status endpoint. + +The numbered list extracts cleanly into "how-to" snippets, FAQ-style answers, and HowTo schema. The prose version forces the extractor (human or AI) to do the work of parsing the steps. + +--- + +## Pattern 5: bullet lists for parallel items + +Parallel items go in bullets. Especially "what is included" or "options" lists. + +### Bad + +> Our enterprise tier includes single sign-on, audit logs, advanced role-based access controls, dedicated support, and custom data retention policies. + +### Better + +> ## What is included in the enterprise tier +> +> - Single sign-on (SSO) +> - Audit logs +> - Advanced role-based access controls +> - Dedicated support +> - Custom data retention policies + +The bullet form is extractable. An AI assistant asked "what does the enterprise tier include" can quote this list verbatim. + +--- + +## Pattern 6: tables for comparisons + +When comparing 2+ options across 2+ criteria, use a table. AI extractors handle tables well; prose comparisons get garbled. + +### Bad + +> The free plan supports up to 3 projects and 5 team members, with email support only. The pro plan extends this to 25 projects and 25 team members, adds priority support, and includes the API. The enterprise plan removes all limits, adds SSO, audit logs, and a dedicated success manager. + +### Better + +> | Feature | Free | Pro | Enterprise | +> |---|---|---|---| +> | Projects | 3 | 25 | Unlimited | +> | Team members | 5 | 25 | Unlimited | +> | Support | Email | Priority | Dedicated CSM | +> | API access | - | ✓ | ✓ | +> | SSO | - | - | ✓ | +> | Audit logs | - | - | ✓ | + +--- + +## Pattern 7: explicit Q&A blocks + +For pages where the user is asking a direct question (FAQs, help docs, glossaries), use explicit Q&A formatting. + +### Pattern + +> **Q: [The question phrased as the user would ask it]** +> +> A: [Direct answer in 1-3 sentences. Optional supporting paragraph after.] + +This is what FAQ schema lifts directly. AI extractors recognize the pattern and treat it as a discrete answerable unit. + +--- + +## Pattern 8: self-contained sections + +Each section under an H2 should make sense if read in isolation. AI extractors often pull a single section as the answer to a query. If the section depends on context from earlier sections, the answer it surfaces will be incomplete or wrong. + +### Bad + +> ## Setup +> +> Use the same approach we discussed in the previous section, but with the production endpoint instead of staging. + +### Better + +> ## Setup for production +> +> Run the deploy command against the production endpoint: +> +> ```bash +> npm run deploy --target=production +> ``` +> +> The production endpoint requires the `PROD_API_KEY` environment variable. See "Environment variables" for setup. + +The "Better" version stands alone. A reader (or AI assistant) landing here from search gets a complete answer. + +--- + +## Pattern 9: explicit data and units + +State numbers, ranges, and units explicitly. Vague modifiers ("a lot," "fast," "some users") do not extract. + +### Bad + +> Our customers see a major improvement in conversion after switching. + +### Better + +> On average, our customers see a 23% lift in conversion within the first 30 days after switching, based on data from 412 customers measured between January and March 2025. + +The "Better" version has extractable specifics: the metric, the magnitude, the time window, the sample size, and the date range. Trustworthy AI assistants prefer extracting specifics. + +--- + +## Pattern 10: structured author and date metadata + +For any content that depends on currency or expertise, expose the metadata visibly and in schema. + +- **Author byline** with a real name and a credential or one-line bio. +- **Publish date** and **last updated date** in human-readable form. +- **Reviewer** if the content is reviewed by an SME. +- Article schema with `author`, `datePublished`, `dateModified`, and (where applicable) `reviewedBy`. + +AI search uses author and date signals as part of trustworthiness scoring. + +--- + +## Pattern 11: explicit topic boundaries + +Tell the reader (and the extractor) what the page is and is not about. + +### Pattern + +> ## What this guide covers +> +> This guide covers backup strategies for Postgres databases on managed services (AWS RDS, GCP Cloud SQL, Supabase). It does not cover self-hosted Postgres tuning, backup of file storage, or disaster recovery testing. +> +> If you are self-hosting Postgres, see [other guide]. If you are designing DR drills, see [other guide]. + +This pattern protects against AI summaries that conflate your scope with adjacent topics. + +--- + +## Pattern 12: predictable summary blocks + +Sections like "Summary," "Key takeaways," "TL;DR" at the top or bottom of an article extract well. Keep them tight: 3-7 bullets, one short sentence each. + +### Pattern + +> ## Key takeaways +> +> - Aim for 30-90 day onboarding, with 90 being the most common. +> - First week: logistics and culture. First month: shadowing and small projects. Months 2-3: full ramp. +> - The single highest-impact factor is manager time, not program design. +> - Track time-to-productivity, not arbitrary onboarding completion. + +A summary block doubles as the AI snippet, the social card excerpt, and the email digest line. + +--- + +## What to avoid + +These patterns hurt extraction: + +- **Walls of text without headings.** The reader and the extractor both lose place. +- **Inline references that depend on prior sections.** "As mentioned above" is invisible to a snippet. +- **Vague modifiers in place of numbers.** "Many users," "several studies," "a long time." +- **Jargon without definition.** AI assistants will define it incorrectly if you do not. +- **Marketing fluff in lead sentences.** "Discover the powerful possibilities of..." extracts as gibberish. +- **PDFs and images for content that should be text.** Tables and key data trapped in images cannot be extracted. +- **Iframe-embedded content.** AI assistants do not consistently follow iframes. + +--- + +## How to test + +After writing a page, simulate extraction: + +1. Read only the H1 and the first sentence under each H2. Does the page still make sense? +2. Read only the bullet lists, tables, and Q&A blocks. Do they answer the obvious questions? +3. Ask an LLM (in a fresh context) the questions your page answers. Does it pull useful, accurate snippets from your page? +4. Check Google's "People also ask" for your topic. Does your page answer those exact questions? + +If a test fails, the structure needs more semantic markup, not more words. diff --git a/skills/seo-aeo-geo/references/llms-txt-guide.md b/skills/seo-aeo-geo/references/llms-txt-guide.md new file mode 100644 index 0000000..5360369 --- /dev/null +++ b/skills/seo-aeo-geo/references/llms-txt-guide.md @@ -0,0 +1,227 @@ +# llms.txt Guide + +`llms.txt` is a markdown file at the root of a domain (e.g., `example.com/llms.txt`) that helps AI systems understand what the site is, what it covers, and which URLs are most valuable. + +It is the AI-era equivalent of `robots.txt` plus a sitemap, written in plain language for language models. + +This guide walks through how to write a useful one. + +--- + +## What llms.txt is for + +- Tell AI assistants what the site is and what it covers +- Point AI to the most valuable URLs for citation +- Provide structured context that helps AI summarize and cite the site accurately +- Reduce the chance of AI hallucinating about your brand or content + +What it is NOT: + +- A ranking signal (yet, possibly ever) +- A guarantee of citation +- A replacement for sitemap.xml or robots.txt +- A way to block AI crawlers (use robots.txt for that) + +--- + +## The format + +llms.txt is a markdown file with a specific structure: + +```markdown +# [Site or Brand Name] + +> [One-sentence description of what the site is and who it serves] + +[1 to 3 paragraphs of context. Who runs the site, what topics it covers, what makes it credible, what audience it serves. Plain language.] + +## [Section 1 - typically content categories or product lines] + +- [Title](URL): [One-line description] +- [Title](URL): [One-line description] + +## [Section 2] + +- [Title](URL): [One-line description] + +## Optional + +[Less critical resources.] +``` + +Section headers are flexible. Use whatever organization fits the site's content. + +--- + +## Example: a simple content site + +```markdown +# Example Knowledge Base + +> A free guide library on [topic area] for [audience]. + +We publish in-depth guides, comparisons, and how-tos on [topic area]. Content is written by [credentials of authors] and updated [frequency]. Our methodology is documented at /methodology. + +## Core guides + +- [The Complete Guide to X](https://example.com/complete-guide-x): A 5,000-word reference covering fundamentals through advanced topics. +- [How to Choose Y](https://example.com/how-to-choose-y): Decision framework with comparison tables and worked examples. +- [The Beginner's Guide to Z](https://example.com/beginner-z): A 30-minute primer for someone new to the topic. + +## Comparisons + +- [A vs B](https://example.com/a-vs-b): Head-to-head feature, pricing, and use case comparison. +- [Top 10 [Category]](https://example.com/top-10): Ranked list with selection criteria. + +## Tools + +- [Calculator](https://example.com/calculator): Free interactive tool for [purpose]. +- [Templates](https://example.com/templates): Downloadable templates with examples. + +## About + +- [About us](https://example.com/about) +- [Methodology](https://example.com/methodology) +- [Editorial standards](https://example.com/editorial-standards) +``` + +--- + +## Example: a SaaS product site + +```markdown +# ProductName + +> [Product category] for [target audience]. [Core value proposition in one phrase]. + +ProductName is built and operated by a team of [size and background]. We serve [audience description]. The product is used by [scale, e.g., "over 10,000 teams" or "from solo founders to Fortune 500 companies"]. + +## Product + +- [How it works](https://example.com/product): Overview of core functionality and architecture. +- [Pricing](https://example.com/pricing): Transparent pricing tiers and what each includes. +- [Integrations](https://example.com/integrations): Third-party tools we connect with. + +## Documentation + +- [Getting started](https://docs.example.com/getting-started): 15-minute setup guide. +- [API reference](https://docs.example.com/api): Complete API documentation. +- [Best practices](https://docs.example.com/best-practices): How successful customers use the product. + +## Resources + +- [Customer stories](https://example.com/customers): How specific customers achieved specific outcomes. +- [Blog](https://example.com/blog): Engineering posts, product updates, and industry analysis. +- [Changelog](https://example.com/changelog): Recent product changes. + +## Trust + +- [Security](https://example.com/security): SOC 2, encryption, compliance. +- [Privacy policy](https://example.com/privacy) +- [Terms of service](https://example.com/terms) +``` + +--- + +## What to include + +A good llms.txt is curated, not exhaustive. Include: + +- **Cornerstone content.** Your 10 to 30 best, most authoritative pieces. +- **Decision-support pages.** Comparisons, calculators, frameworks. +- **Authority signals.** Methodology, editorial standards, about pages. +- **Trust signals.** Security, privacy, compliance, certification pages. +- **Recency cues.** A changelog or "latest" link if you publish frequently. + +What to leave out: + +- Every URL on the site (use sitemap.xml for that) +- Marketing fluff with no informational substance +- Pages that exist primarily for SEO (low-quality programmatic content, doorway pages) +- Internal admin URLs + +--- + +## What to write in the description + +The opening description (under the title, prefixed by `>`) is what AI extracts when asked "what is [site]?" Make it count. + +**Bad description:** +> A leading provider of innovative solutions in the digital space. + +**Good description:** +> A free guide library on home renovation for first-time buyers, with calculators and template contracts. + +The good description names: what it is (guide library), what topic (home renovation), who it serves (first-time buyers), and what's unique (calculators and templates). + +--- + +## Length and depth + +- **Title and one-sentence description**: required +- **Context paragraphs**: 1 to 3 paragraphs, 100 to 400 words total +- **Sections**: 3 to 8 sections is typical +- **URLs per section**: 3 to 10 is the sweet spot +- **Total file length**: 500 to 2000 words for most sites + +A 50-word llms.txt is too thin to be useful. A 5000-word llms.txt buries the signal. + +--- + +## Updating + +- Update llms.txt when you launch a major new content category, product, or section +- Re-review at least quarterly +- Remove dead links (broken URLs in llms.txt actively damage credibility with AI) +- Keep the description fresh as the site evolves + +--- + +## llms-full.txt (the optional sibling) + +Some sites also publish `llms-full.txt`, which contains the full text content of the linked pages concatenated into one file. This is more aggressive: it offers AI systems the entire content for context. + +Reasons to publish it: + +- You want maximum AI context, including verbatim content +- Your content is freely licensed or you accept it being used for AI training +- Your content is short enough that the file is manageable (under 10MB, ideally under 5MB) + +Reasons NOT to publish it: + +- You sell or gate content (e.g., paid courses, premium reports) +- Your terms of service disallow AI training on your content +- File size would exceed reasonable limits + +If you do publish it, link to it from llms.txt: + +```markdown +## Full content + +- [Full content dump](https://example.com/llms-full.txt): The complete content of all linked pages. +``` + +--- + +## Common mistakes + +- **Auto-generating llms.txt from sitemap.xml.** Defeats the purpose. The point is editorial curation. +- **Treating it as a sitemap.** Sitemap is for crawlers. llms.txt is for AI context. +- **Stuffing it with thin content.** Every URL listed should be content you would proudly cite if a human asked. +- **Forgetting to update it.** A 2-year-old llms.txt makes you look abandoned. +- **Hosting it at a non-root path.** It belongs at `/llms.txt` (root of the domain), not `/docs/llms.txt`. +- **Returning HTML instead of plain text.** Serve as `text/markdown` or `text/plain`, not as a rendered HTML page. + +--- + +## Verification + +After publishing: + +- [ ] File is at `https://yourdomain.com/llms.txt` (root) +- [ ] File serves with content type `text/markdown` or `text/plain` +- [ ] All linked URLs return 200 +- [ ] All linked URLs use the canonical URL form (no redirects) +- [ ] File is referenced (or at least not blocked) in robots.txt +- [ ] File renders cleanly in a plain text viewer +- [ ] Description and section headings accurately describe the site diff --git a/skills/seo-audit-orchestration/SKILL.md b/skills/seo-audit-orchestration/SKILL.md new file mode 100644 index 0000000..92c3e96 --- /dev/null +++ b/skills/seo-audit-orchestration/SKILL.md @@ -0,0 +1,182 @@ +--- +name: seo-audit-orchestration +description: "Master orchestrator for a full SEO audit suite powered by the Ahrefs MCP. Use this skill when running a comprehensive SEO audit, scoping a quarterly health check, doing pre-acquisition SEO due diligence, or post-migration verification. Triggers on full SEO audit, comprehensive SEO review, SEO health check, audit my site, SEO due diligence, audit suite, comprehensive audit, end-to-end SEO. Also triggers when a stakeholder wants the complete picture rather than a single-dimension audit." +category: seo-audit-suite +catalog_summary: "Master orchestrator: sequences the suite, produces a rollup report" +display_order: 1 +--- + +# SEO Audit Orchestration + +Run a complete SEO audit by sequencing the sibling audit skills in a defined order. Stack-agnostic. Assumes the Ahrefs MCP is connected. Produces a single rollup report that synthesizes findings across backlinks, keywords, content, traffic, technical health, and rankings. + +--- + +## When to use + +- Running a full SEO audit (quarterly, biannual, annual) +- Pre-acquisition SEO due diligence +- Post-migration verification (after content move, replatform, or domain change) +- Onboarding a new client or new property +- Building a baseline before a major SEO investment +- Diagnosing chronic underperformance + +## When NOT to use + +- Single-dimension audits (use the specific child skill: `seo-onpage`, `seo-backlink-audit`, etc.) +- Investigating a specific traffic drop (use `seo-traffic-diagnosis`) +- Tactical questions like "which keywords should we target" (use `seo-keyword-gap-audit`) +- Routine monitoring (use `seo-rank-tracking`) + +--- + +## Required inputs + +- The site or properties in scope +- Target market and primary languages +- Competitor set (3-5 properties) +- Goal of the audit (baseline, due diligence, fix plan, growth roadmap) +- Time and reporting constraints +- Confirmation that the Ahrefs MCP is connected and the workspace has access to the target property + +--- + +## The framework: 6 phases of an end-to-end audit + +A complete audit moves through six phases in order. Skipping phases produces gaps. Reordering them produces rework. + +### Phase 1: Scope and baseline + +Define the audit before running it. + +- What is in scope (subdomains, paths, languages) +- What is out of scope +- Goal of the audit (baseline, fix plan, growth roadmap, due diligence) +- Stakeholders and their priorities +- Reporting format and length expectations + +Output: a 1-page audit charter. + +### Phase 2: Data gather + +Pull the raw data from Ahrefs and any companion sources. + +Required pulls: + +- Site Explorer: organic keywords, organic traffic, top pages, top countries, referring domains, backlinks, anchor text profile +- Site Audit: full crawl results +- Keywords Explorer: target keyword universe and competitor keyword overlap +- Content Explorer: top performing content in target topics +- Rank Tracker: current tracked positions if set up + +Companion pulls (not Ahrefs-native): + +- Search Console: query and page data, coverage issues +- Analytics: traffic, conversions, segment by source +- Server logs (if available): bot crawl behavior + +Document data freshness for every pull. Stale data yields wrong conclusions. + +### Phase 3: Run the sub-audits + +Run each child audit. Each produces its own findings doc. + +| Sub-audit | Skill | What it produces | +| --- | --- | --- | +| Site health | `seo-site-health-audit` | Prioritized technical fix backlog | +| Backlinks | `seo-backlink-audit` | Profile health, toxic list, reclamation list | +| Keywords | `seo-keyword-gap-audit` | Prioritized opportunity list | +| Content | `seo-content-gap-audit` | Create/update/merge roadmap | +| Page-level | `seo-onpage` | Per-page audit on top pages | +| AI search | `seo-aeo-geo` | AI search readiness gaps | + +The child skills do the analysis. This skill sequences them and integrates the outputs. + +### Phase 4: Synthesize + +Combine findings into themes. A list of 200 issues is not an audit. A list of 5-7 themes is. + +Themes typically emerge in categories like: + +- Technical foundation gaps that cap upside +- Content depth gaps in priority topics +- Backlink profile concentration risks +- Keyword opportunities the site is leaving on the table +- Cannibalization or thin coverage +- AI search readiness + +Each theme should answer: what is happening, why it matters, what is the size of prize, what is the fix. + +### Phase 5: Prioritize + +Rank the themes. Use a simple impact/effort matrix. + +- Quick wins: high impact, low effort. Do now. +- Strategic plays: high impact, high effort. Plan and resource. +- Maintenance: low impact, low effort. Backlog. +- Avoid: low impact, high effort. Drop. + +Tie each theme to a measurable target (organic clicks, ranked keywords in target band, conversions from organic). + +### Phase 6: Deliver + +Produce the rollup report. See [`references/audit-rollup-template.md`](references/audit-rollup-template.md). + +Structure: + +- Executive summary (1 page) +- Themes and recommendations (5-7 themes, 1 page each) +- Sub-audit findings (linked or appended) +- Roadmap (next 90 days) + +Walk stakeholders through it. Get commitment to the next 90 days of work. + +--- + +## Workflow + +1. **Charter the audit.** 1-page scope, goal, stakeholders, format. +2. **Confirm Ahrefs MCP access.** Verify the workspace has the target property and recent data. +3. **Pull all data.** Run the gather list in phase 2. Document freshness. +4. **Run each sub-audit.** Use the child skills. Each produces its own findings doc. +5. **Synthesize themes.** 5-7 themes max. Each ties to an impact and a fix. +6. **Prioritize.** Impact/effort matrix. Quick wins surface to the top. +7. **Draft the rollup.** Use the template. Executive summary first. +8. **Review with the team.** Pressure-test conclusions before stakeholder readout. +9. **Deliver.** Walk stakeholders through. Get commitment to next 90 days. +10. **Schedule the next one.** Audits decay. Rerun on a cadence. + +--- + +## Failure patterns + +- **Audit without a goal.** Produces a 60-page document nobody reads. Charter the audit first. +- **All findings, no themes.** A list of 200 issues is data, not an audit. Synthesize into themes. +- **Skipping the sub-audits.** Running one big audit instead of six focused ones produces shallow analysis everywhere. +- **No prioritization.** "Here are 47 things to fix" gets nothing fixed. Rank them. +- **Stale data.** Ahrefs index updates on a delay. Note freshness. Do not draw conclusions from week-old movement. +- **Tool worship.** Ahrefs is one source. Search Console, analytics, and logs add ground truth. Triangulate. +- **Audit-to-audit drift.** Running every audit differently makes trends impossible to spot. Standardize the structure. +- **No 90-day roadmap.** Without a plan after the audit, the audit is shelfware. +- **Solo audit.** Audits done alone miss context. Pull in the people who own the work. + +--- + +## Output format + +A rollup audit report with: + +1. **Executive summary** (1 page). +2. **Audit charter** (scope, goal, methodology). +3. **Themes and recommendations** (5-7 themes, each with what, why, size of prize, fix). +4. **Sub-audit appendix** (linked outputs from each child skill). +5. **90-day roadmap** (sequenced work with owners and targets). +6. **Methodology notes** (data sources, pull dates, caveats). + +Total length: 15-30 pages including appendices. Executive summary readable in 5 minutes. + +--- + +## Reference files + +- [`references/audit-rollup-template.md`](references/audit-rollup-template.md) - Template for the rollup report including executive summary, theme structure, and roadmap format. diff --git a/skills/seo-audit-orchestration/references/audit-rollup-template.md b/skills/seo-audit-orchestration/references/audit-rollup-template.md new file mode 100644 index 0000000..2343b76 --- /dev/null +++ b/skills/seo-audit-orchestration/references/audit-rollup-template.md @@ -0,0 +1,236 @@ +# Audit rollup template + +A template for the final SEO audit deliverable. Adapt sections to fit the audit goal and stakeholder appetite. + +--- + +## Document structure + +``` +1. Executive summary (1 page) +2. Audit charter (1 page) +3. Themes and recommendations (5-7 themes, 1 page each) +4. 90-day roadmap (1-2 pages) +5. Sub-audit appendix (linked or attached) +6. Methodology notes (1 page) +``` + +Total: 15-30 pages. Executive summary always readable in 5 minutes. + +--- + +## 1. Executive summary template + +``` +# [Property] SEO Audit + +**Audit date:** [date] +**Period covered:** [date range] +**Auditor:** [name or team] + +## Headline + +[One sentence. The state of SEO at this property.] + +## Top 3 themes + +1. **[Theme name].** [One sentence. Why it matters.] +2. **[Theme name].** [One sentence. Why it matters.] +3. **[Theme name].** [One sentence. Why it matters.] + +## Top 3 quick wins + +1. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. +2. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. +3. **[Action].** Estimated impact: [target metric movement]. Effort: [size]. + +## Recommended next 90 days + +[3-5 bullets describing the proposed plan.] + +## What is going well + +[2-4 bullets. Avoid an audit that reads as 100% negative.] +``` + +--- + +## 2. Audit charter template + +``` +## Scope + +- Properties in scope: [list] +- Languages: [list] +- Subdomains: [list] +- Out of scope: [list] + +## Goal + +[Baseline / fix plan / growth roadmap / due diligence] + +## Stakeholders + +| Name | Role | Priority | +| --- | --- | --- | +| [name] | [role] | [their main concern] | + +## Methodology + +- Data sources: [Ahrefs, Search Console, Analytics, logs] +- Pull dates: [dates] +- Sub-audits run: [list] + +## Limitations + +[Anything that limits confidence: data gaps, access restrictions, time constraints.] +``` + +--- + +## 3. Theme template + +Use one page per theme. 5-7 themes total. + +``` +## Theme [N]: [Name] + +**What is happening** + +[2-3 sentences describing the pattern.] + +**Why it matters** + +[2-3 sentences linking the pattern to a business outcome.] + +**Size of prize** + +[Quantified opportunity. E.g., "+12,000 monthly clicks" or "+$80k annual revenue at current conversion."] + +**Evidence** + +- [Data point with source] +- [Data point with source] +- [Data point with source] + +**Recommendation** + +[The proposed fix or action. 1 paragraph.] + +**Effort and timeline** + +[Effort: S/M/L. Timeline: weeks or sprints. Dependencies: list.] + +**Owners** + +[Who needs to do what.] +``` + +--- + +## 4. 90-day roadmap template + +Sequence the work. Tie to themes. Assign owners. + +``` +## Days 1-30 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Days 31-60 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Days 61-90 + +| Action | Theme | Owner | Effort | Target | +| --- | --- | --- | --- | --- | +| [Action] | [Theme #] | [Name] | [S/M/L] | [Metric target] | + +## Review cadence + +[Weekly, biweekly, monthly. Who attends. What is reviewed.] +``` + +--- + +## 5. Sub-audit appendix + +Link or attach the output from each child skill: + +- Site health audit: [link or attachment] +- Backlink audit: [link or attachment] +- Keyword gap audit: [link or attachment] +- Content gap audit: [link or attachment] +- Page-level audits (top pages): [link or attachment] +- AI search readiness: [link or attachment] + +Do not paste full sub-audits into the rollup. Reference them. Stakeholders who want detail can drill in. + +--- + +## 6. Methodology notes + +``` +## Data sources and freshness + +| Source | Pull date | Coverage | Notes | +| --- | --- | --- | --- | +| Ahrefs Site Explorer | [date] | [scope] | [caveats] | +| Ahrefs Site Audit | [date] | [scope] | [caveats] | +| Search Console | [date range] | [scope] | [caveats] | +| Analytics | [date range] | [scope] | [caveats] | + +## Caveats + +- Ahrefs metrics are estimates, not ground truth. +- Search Console data is sampled and capped. +- Analytics may have tagging gaps. +- Server log data was [available / unavailable] for this audit. + +## Repeatability + +To rerun this audit: + +- [Steps to reproduce data pulls] +- [Saved Ahrefs reports or filters] +- [Companion data pull instructions] +``` + +--- + +## Style guidance + +- Lead with the "so what." Stakeholders skim. +- Quantify wherever possible. Vague impact claims get ignored. +- Pair every problem with a proposed fix. Audits without recommendations are reports. +- Keep technical jargon out of the executive summary. +- Use tables and bullets. Avoid wall-of-text. + +--- + +## Common length targets by audit type + +| Audit type | Total length | Executive summary | Themes | +| --- | --- | --- | --- | +| Quarterly health check | 10-15 pages | 1 page | 3-4 themes | +| Full annual audit | 25-40 pages | 1-2 pages | 5-7 themes | +| Pre-acquisition due diligence | 30-50 pages | 2 pages | 6-10 themes | +| Post-migration verification | 10-20 pages | 1 page | 3-5 themes | + +--- + +## Pre-delivery checklist + +- [ ] Executive summary readable in 5 minutes +- [ ] Every theme tied to a quantified impact +- [ ] Every recommendation tied to an owner +- [ ] Quick wins called out separately +- [ ] 90-day roadmap is sequenced and resourced +- [ ] Methodology and caveats are documented +- [ ] Internal review completed before stakeholder readout +- [ ] Next audit date scheduled diff --git a/skills/seo-backlink-audit/SKILL.md b/skills/seo-backlink-audit/SKILL.md new file mode 100644 index 0000000..31e223d --- /dev/null +++ b/skills/seo-backlink-audit/SKILL.md @@ -0,0 +1,166 @@ +--- +name: seo-backlink-audit +description: "Audit a backlink profile using Ahrefs MCP data: profile health, anchor text distribution, toxic link identification, lost link reclamation, and gap analysis against competitors. Use this skill when reviewing backlink health, scoping a disavow project, recovering from a manual action, planning link building, or doing M&A due diligence on a property's link equity. Triggers on backlink audit, link profile, toxic links, disavow, anchor text analysis, lost links, link reclamation, referring domains, link gap. Also triggers when traffic decline correlates with link loss or when an unnatural link warning appears in Search Console." +category: seo-audit-suite +catalog_summary: "Profile health, anchor mix, toxic links, reclamation, gap analysis" +display_order: 2 +--- + +# SEO Backlink Audit + +Audit a backlink profile using data pulled from the Ahrefs MCP. Stack-agnostic. Produces a profile health assessment, a toxic link list (if needed), a reclamation list, and a gap analysis against competitors. + +--- + +## When to use + +- Periodic backlink health check (quarterly or biannual) +- Recovering from a Google manual action or unnatural link warning +- Scoping a disavow file +- Pre-acquisition due diligence on link equity +- Planning a link building campaign (need a baseline) +- Investigating ranking drops correlated with link loss +- Recovering lost links after a migration or replatform + +## When NOT to use + +- Building new links (use `seo-offpage`) +- General SEO audits (use `seo-audit-orchestration`) +- Keyword opportunity analysis (use `seo-keyword-gap-audit`) +- Technical issues unrelated to links (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Target property (root domain, subdomain, or URL prefix) +- Competitor set (3-5 properties with comparable strategies) +- Time window (typically last 12-24 months) +- Confirmation Ahrefs MCP is connected and has access to the property +- Search Console manual action status (if any) +- Recent SEO history (migrations, link campaigns, penalties) + +--- + +## The framework: 5 dimensions of a backlink profile + +A profile is healthy when all five dimensions are healthy. Issues in any one can cap rankings or invite penalties. + +### Dimension 1: Referring domain quality + +Volume of links matters less than the quality and relevance of the linking domains. + +Pull from Ahrefs: + +- Total referring domains (current and trended) +- Domain Rating distribution (DR bands) +- Topical relevance of linking domains +- Geographic distribution (where appropriate) +- Domain age and trust signals + +Healthy signal: a long tail of relevant, established domains. Concentration in any single source is a risk. + +### Dimension 2: Link velocity + +How fast links are gained or lost. + +Pull from Ahrefs: + +- New referring domains per month (trended 12-24 months) +- Lost referring domains per month +- Net change + +Healthy signal: steady positive growth. Sudden spikes suggest paid campaigns or negative SEO. Sudden drops correlate with redirect mistakes, content removal, or the linking sites going down. + +### Dimension 3: Anchor text distribution + +The mix of anchor types tells search engines what the property is about and whether the profile looks natural. + +Categories to map: + +- Branded (the brand name) +- Naked URL +- Generic ("click here", "this page") +- Exact-match keyword +- Partial-match keyword +- Image (alt text or none) + +Healthy signal: branded and naked URL anchors dominate. Exact-match keyword anchors are a small minority. Heavy exact-match concentration triggers spam filters. + +### Dimension 4: Link types + +Not all links are equal. + +Categories: + +- Dofollow versus nofollow +- Editorial versus directory or comment +- In-content versus footer or sidebar +- Sponsored or UGC tagged +- Redirect chains +- Lost links recoverable via outreach + +Healthy signal: editorial in-content dofollow links from relevant sites dominate. + +### Dimension 5: Competitive gap + +What links do peers have that you do not? + +Pull from Ahrefs: + +- Domains linking to 2+ competitors but not the target +- Domains linking to 1 competitor with high relevance to the target +- Top performing competitor pages by referring domain count + +Healthy signal: the gap is shrinking over time. A widening gap is a strategic risk. + +--- + +## Workflow + +1. **Charter the audit.** Goal, scope, time window, competitor set. +2. **Pull baseline data.** Referring domains, anchor text, link types, lost links, competitor overlap. +3. **Map the profile across 5 dimensions.** One section per dimension. +4. **Identify red flags.** Velocity spikes, anchor concentration, low-DR concentration, suspect TLDs, repeated footprints. +5. **Build the toxic list (if needed).** Use the criteria in [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md). +6. **Build the reclamation list.** Lost links worth recovering via outreach. +7. **Build the gap list.** Domains linking to peers, prioritized by relevance. +8. **Synthesize.** Profile health verdict, top 3 risks, top 3 opportunities. +9. **Recommend.** Disavow (rare), reclamation outreach, link building targets, monitoring cadence. +10. **Document and hand off.** Outputs feed `seo-offpage` and `seo-audit-orchestration`. + +--- + +## Failure patterns + +- **Disavow happy.** Most profiles do not need a disavow. Disavowing legitimate links damages rankings. Use it only after a manual action or clear algorithmic signals. +- **Counting links instead of evaluating them.** A profile with 10,000 referring domains can be weaker than one with 200 high-quality editorial links. +- **Ignoring lost links.** Recovering a lost link is faster and cheaper than building a new one. +- **No competitor benchmark.** Profile health is relative. A "low" backlink count for a tier-1 competitor is a "great" count for a niche site. +- **Anchor text panic.** A high exact-match percentage in absolute terms is fine for niche sites where the brand and keyword overlap. Investigate before disavowing. +- **One-time audit.** Profile health drifts. Audit on a cadence (quarterly minimum for active properties). +- **Treating Ahrefs as ground truth.** Ahrefs sees most links but not all. Triangulate with Search Console for completeness. +- **Over-indexing on Domain Rating.** DR is a relative metric, not a quality signal. A DR-30 niche site can be more valuable than a DR-80 generalist. + +--- + +## Output format + +A backlink audit document with: + +1. **Executive summary.** Profile health verdict and top risks. +2. **Profile snapshot.** Key metrics: referring domains, DR distribution, anchor mix, velocity. +3. **5-dimension analysis.** One section per dimension with findings. +4. **Toxic link list.** If needed. Disavow file ready format. +5. **Reclamation list.** Lost links worth recovering, with contact paths. +6. **Gap list.** Top 50 domains linking to competitors but not target. +7. **Recommendations.** Disavow (Y/N), reclamation outreach plan, link building targets. +8. **Methodology.** Data sources, pull dates, criteria used. + +Length: 8-15 pages depending on profile complexity. + +--- + +## Reference files + +- [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md) - Decision framework for classifying a link as toxic, including the disavow file format and threshold guidance. diff --git a/skills/seo-backlink-audit/references/toxic-link-criteria.md b/skills/seo-backlink-audit/references/toxic-link-criteria.md new file mode 100644 index 0000000..8e26d42 --- /dev/null +++ b/skills/seo-backlink-audit/references/toxic-link-criteria.md @@ -0,0 +1,182 @@ +# Toxic link criteria + +A decision framework for classifying a backlink as toxic and worth disavowing. Bias the framework toward keeping links unless the case is clear. Disavowing legitimate links damages rankings. + +--- + +## The disavow bar + +Disavow when one or more of the following is true: + +1. The site has been hit with an algorithmic devaluation that correlates with link-based signals. +2. The site has received a manual action citing unnatural links. +3. There is clear evidence of a negative SEO attack with low-quality links pointed at the property. +4. Pre-acquisition due diligence on a property reveals a known toxic profile. + +Outside these cases, the default is to leave links alone. Google has stated repeatedly that they ignore most low-quality links automatically. + +--- + +## Per-link signals (any one is concerning, multiple is decisive) + +### Site-level signals + +| Signal | Severity | +| --- | --- | +| Site is in a known link network | High | +| Site exists primarily to host links | High | +| Site has thin or auto-generated content | High | +| Site is on a suspect TLD pattern (mass registered) | Medium | +| Site has no organic traffic per Ahrefs estimates | Medium | +| Site is in an irrelevant language or geography | Medium | +| Site has been deindexed or penalized | High | +| Site is parked or for sale | High | +| Site has a footprint shared with many other suspect sites | High | + +### Page-level signals + +| Signal | Severity | +| --- | --- | +| Page is a low-effort link page or directory | Medium | +| Page has a high outbound link count with no editorial logic | Medium | +| Page is hidden from the site's main navigation | Medium | +| Page is in a foreign language with no relevance | Medium | +| Page has been hacked or is serving malware | High | + +### Link-level signals + +| Signal | Severity | +| --- | --- | +| Anchor text is exact-match commercial and unnatural in context | High | +| Link is in a footer with hundreds of others | Medium | +| Link is part of a sitewide footer link | Medium | +| Link is in a comment with promotional text | Low | +| Link is paid without disclosure | High | + +--- + +## Deciding by domain versus by URL + +Disavow at the domain level when: + +- The entire site is suspect. +- Multiple pages from the same site link to you. +- You expect the site to keep adding links. + +Disavow at the URL level when: + +- Only one specific page is suspect on an otherwise legitimate site. +- The site has editorial credibility but a single contributor placed the link. + +Default to domain-level disavow when in doubt. URL-level disavows are fragile: the site can move the content and the disavow no longer applies. + +--- + +## Outreach before disavow + +Disavow is a last resort. Before disavowing, attempt outreach for high-value but problematic links: + +1. Find a contact (whois, contact page, social). +2. Send a polite link removal request. +3. Wait 14 days. +4. Send a follow-up. +5. If no response after 30 days, disavow. + +Document outreach attempts. If a manual action review is needed later, Google requires evidence of cleanup effort beyond just a disavow file. + +--- + +## Disavow file format + +The disavow file is a plain text file submitted to Google Search Console. + +Format: + +``` +# Disavow file for [property] +# Last updated: [date] +# Submitted: [date or pending] + +# Section 1: Domain-level disavows + +domain:lowqualitysite-example.com +domain:linkfarm-example.net +domain:hackedsite-example.org + +# Section 2: URL-level disavows + +https://otherwiselegitimate-example.com/sponsored-post-page + +# Section 3: Notes for future me + +# - Disavowed lowqualitysite-example.com after manual action 2024-03 +# - Reviewed quarterly +``` + +Rules: + +- One entry per line +- `domain:` prefix for domain-level +- Full URL for URL-level +- Lines starting with `#` are comments and ignored +- File must be UTF-8 plain text +- Maximum 100,000 lines or 2 MB + +--- + +## Bulk classification heuristic + +When auditing thousands of referring domains, use this triage: + +### Round 1: filter obvious keepers + +Mark as KEEP without further review: + +- Domain Rating above a relevance-appropriate threshold and topical match +- Known media, government, education domains +- Linking from a page with organic traffic + +Skip these. They are not toxic. + +### Round 2: filter obvious toxics + +Mark as TOXIC for further review: + +- Domain Rating zero with no organic traffic +- TLDs in known spam patterns +- Domains matching known link network footprints +- Sites that link to thousands of unrelated properties + +### Round 3: review the middle + +The remaining domains need manual review. Apply the per-link signal table above. + +Expected breakdown for a healthy profile: 80%+ keep, 5-15% review, under 5% toxic. If toxic exceeds 20%, the profile has structural problems beyond a disavow. + +--- + +## After disavow + +- Submit the file in Search Console. +- Document submission date in your audit log. +- Wait 4-8 weeks before evaluating impact. +- Recrawl can take longer for larger sites. +- Do not submit revised disavows weekly. Submit, wait, evaluate. + +If a manual action was the trigger, file a reconsideration request with: + +- Summary of the cleanup effort +- Evidence of outreach attempts +- The submitted disavow file +- An honest acknowledgment of the cause + +--- + +## Common mistakes + +- **Disavowing low-traffic links indiscriminately.** Most have no negative effect. Disavowing them can lose minor positive equity. +- **Disavowing competitor links by accident.** Double-check the file before submission. +- **Forgetting that disavow is reversible.** Resubmit a file without the entry to remove a disavow. Test cautiously. +- **Treating disavow as a recurring task.** It is not. Audit and submit when needed. Otherwise leave it alone. +- **Disavowing without documenting why.** Six months later you will not remember which entries were intentional. +- **Using disavow as a substitute for outreach.** For high-value links, removal is better than disavow. diff --git a/skills/seo-competitor/SKILL.md b/skills/seo-competitor/SKILL.md new file mode 100644 index 0000000..39e585d --- /dev/null +++ b/skills/seo-competitor/SKILL.md @@ -0,0 +1,137 @@ +--- +name: seo-competitor +description: "Run a competitive SEO analysis comparing the user's site to chosen competitors across SERP overlap, content depth, backlink profiles, technical posture, and brand presence. Use this skill whenever the user wants to analyze competitors, find content gaps, identify backlink opportunities, understand why competitors outrank them, or benchmark against the rest of their category. Triggers on competitor analysis, competitive analysis, SERP analysis, content gap, backlink gap, why is X ranking, who is winning the SERP, beat my competitor, benchmark, market positioning. Also triggers when planning a content strategy and the question 'what are competitors doing' is implicit." +category: seo-foundation +catalog_summary: "SERP overlap, content gaps, backlink gaps, technical comparison" +display_order: 4 +--- + +# SEO Competitor Analysis + +Compare a site to its competitors and find the gaps worth closing. Stack-agnostic. Tool-friendly but tool-optional. + +--- + +## When to use + +- Identifying which competitors to study +- Finding content gaps (topics they cover, you do not) +- Finding backlink gaps (sites linking to them, not you) +- Understanding why a specific competitor outranks the user +- Benchmarking authority, technical posture, and content depth + +## When NOT to use + +- Single-page optimization (use `seo-onpage`) +- Initial keyword research with no competitors yet identified (use `seo-keyword` first to find them) +- Auditing one's own existing content (use `seo-content-audit`) + +--- + +## Required inputs + +- The user's site +- 3 to 5 named competitors (or the topic area, if competitors are not yet identified) +- Access to a keyword tool, a backlink tool, and any crawler + +If competitors are unknown, start by listing the top 10 ranking domains for the user's top 10 priority keywords. Pick the 3 to 5 that appear most often. + +Where competitor traffic estimation is the input you need (relative scale, channel mix, audience overlap), Similarweb MCP is the strongest source. Pair with Ahrefs (for backlink and keyword overlap) and Semrush (for SERP feature presence and SEO-PR overlap). Each platform gives a different cut of the same competitive landscape; using them together produces sharper signal than any one alone. + +--- + +## The framework: 5 angles + +Competitor analysis covers five angles. Run all five for a full picture, or pick two or three for a focused investigation. + +### 1. SERP overlap +Where do you and the competitor compete head-to-head? + +- For each priority keyword, who ranks in the top 10? +- For each top-10 ranking, what page type wins (article, product, comparison, video)? +- Are there SERP features (featured snippet, AI overview, video, image pack) one party holds and the other does not? +- Which queries do competitors rank for that the user does not? (the content gap) + +### 2. Content depth +What does their winning content look like? + +- Word count and structure of their top-ranking pages +- Information types they include (data tables, original research, video, calculators, downloadable assets) +- Update frequency on key pages (last modified date, change history) +- Internal linking patterns (do their winning pages link to commercial pages?) +- Topical breadth (how many related topics do they cover?) + +### 3. Backlink profile +Where does their authority come from? + +- Total referring domains +- Domain rating (or equivalent authority metric) +- Top 50 referring pages by traffic value +- Backlink types (editorial, directory, partner, paid, spam) +- Link velocity (gaining or losing referring domains over time) +- Pages on their site attracting the most links (these are their "linkable assets") + +### 4. Technical posture +How clean is their technical foundation? + +- Core Web Vitals (LCP, INP, CLS) +- Mobile usability +- Schema implementation (which types, on which page types) +- Site architecture and internal linking density +- Crawl efficiency (are they wasting crawl budget?) +- HTTPS, security headers +- llms.txt and AI search readiness + +### 5. Brand and entity strength +How well-known are they outside organic search? + +- Branded search volume (how many people search their name?) +- Entity recognition in knowledge graph (do they have a Wikipedia page, knowledge panel, structured data feeding entity status?) +- Mention frequency in their topic area (PR coverage, podcast appearances, citations) +- Social signals (followers, engagement, share rates) +- Reviews and reputation + +--- + +## Workflow + +1. **Confirm the competitors.** Either named, or derive from SERP overlap on top 10 priority keywords. +2. **Pick the angles.** Run all 5 for a full audit, or 2 to 3 for a focused dive. +3. **Pull the data.** Keyword tool exports, backlink tool exports, manual SERP inspection, technical crawl. +4. **Score each angle.** Where does the user lead? Where do they trail? +5. **Identify gaps.** Specific content gaps, specific backlink gaps, specific technical gaps. +6. **Prioritize.** Which gaps are highest leverage to close? (Big traffic potential, achievable effort, strategic fit.) +7. **Write the report.** Use the template in [`references/competitive-audit-template.md`](references/competitive-audit-template.md). + +--- + +## Failure patterns + +- **Picking the wrong competitors.** A site that outranks you on one keyword but operates a different business is not a competitor. Pick by SERP overlap and audience overlap, not by who you think you compete with. +- **Treating "more content" as the takeaway.** They are not winning because they have 500 articles. They are winning because of specific content + links + UX. Find the actual lever. +- **Copying their pages verbatim.** Diminishing returns. Beat them by being more useful, not by paraphrasing them. +- **Ignoring brand strength.** A weaker site with a stronger brand wins on branded queries you cannot touch with content alone. +- **Static analysis.** Re-run the analysis at least annually. Competitor strategies shift. + +--- + +## Output format + +Default output is a markdown report at `competitive-analysis.md` plus accompanying spreadsheets for the keyword and backlink data. + +Structure: +1. Executive summary (3 to 5 critical findings) +2. Competitor profiles (one per competitor, brief) +3. SERP overlap analysis +4. Content gap analysis +5. Backlink gap analysis +6. Technical comparison +7. Brand and entity comparison +8. Prioritized gap-closing roadmap + +--- + +## Reference files + +- [`references/competitive-audit-template.md`](references/competitive-audit-template.md) - Fillable competitive audit template. +- [`references/content-gap-method.md`](references/content-gap-method.md) - Detailed methodology for finding content gaps with example. diff --git a/skills/seo-competitor/references/competitive-audit-template.md b/skills/seo-competitor/references/competitive-audit-template.md new file mode 100644 index 0000000..556d013 --- /dev/null +++ b/skills/seo-competitor/references/competitive-audit-template.md @@ -0,0 +1,160 @@ +# Competitive SEO Analysis: [Your Site] vs Competitors + +**Date:** [YYYY-MM-DD] +**Site under audit:** [URL] +**Competitors analyzed:** [List] +**Analyst:** [Name] + +--- + +## Executive summary + +[3 to 5 critical findings. Lead with the most important. What is the single biggest gap to close, and what is the single biggest strength to defend?] + +**Top 3 priorities:** +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Competitor profiles + +### Competitor 1: [Name] +- **Domain rating:** [X] +- **Estimated organic traffic:** [X / month] +- **Total referring domains:** [X] +- **Top 3 ranking categories:** [What they win on] +- **Why they matter:** [1 to 2 sentences] +- **Their key advantage over us:** [1 sentence] + +### Competitor 2: [Name] +[Same structure] + +### Competitor 3: [Name] +[Same structure] + +--- + +## SERP overlap analysis + +**Keywords where we both rank top 10:** [N] +**Keywords where they rank, we don't:** [N] +**Keywords where we rank, they don't:** [N] +**Keywords where they hold a SERP feature we don't:** [N] + +### Head-to-head wins +[Top 10 keywords where we currently rank above them] + +| Keyword | Our rank | Their rank | Volume | +|---|---|---|---| +| | | | | + +### Head-to-head losses +[Top 10 keywords where they rank above us] + +| Keyword | Our rank | Their rank | Volume | Likely reason they win | +|---|---|---|---|---| +| | | | | | + +### Their territory (we don't rank) +[Top 20 keywords they rank for that we don't, ranked by traffic potential] + +| Keyword | Their rank | Volume | Difficulty | Strategic fit for us | +|---|---|---|---|---| +| | | | | | + +--- + +## Content gap analysis + +[Topics or page types they cover that we don't, organized by theme.] + +### Theme 1: [e.g., "How-to guides for beginners"] +- **Their coverage:** [X pages, including these top performers...] +- **Our coverage:** [None / weak / partial] +- **Estimated traffic value if closed:** [X visits/month] +- **Recommended action:** [Produce / partial coverage / skip] + +### Theme 2: [e.g., "Comparison content"] +[Same structure] + +--- + +## Backlink gap analysis + +**Their referring domains we don't have:** [N] +**Their unique referring domains (in our category):** [N] + +### Top 10 backlink opportunities +[Domains linking to multiple competitors but not us. These are the highest-probability outreach targets.] + +| Domain | Domain rating | Links to (competitors) | Why they link to them | +|---|---|---|---| +| | | | | + +### Their linkable assets +[Pages on competitor sites that attract the most backlinks. These are the asset types we could replicate.] + +| URL | Referring domains | Asset type | +|---|---|---| +| | | | + +--- + +## Technical comparison + +| Dimension | Us | Comp 1 | Comp 2 | Comp 3 | +|---|---|---|---|---| +| LCP (mobile) | | | | | +| INP (mobile) | | | | | +| CLS (mobile) | | | | | +| Mobile-friendly | | | | | +| HTTPS / HSTS | | | | | +| Schema types | | | | | +| Sitemap quality | | | | | +| llms.txt present | | | | | +| Internal links per page (avg) | | | | | + +**Key takeaways:** [Where are we ahead, where are we behind?] + +--- + +## Brand and entity comparison + +| Dimension | Us | Comp 1 | Comp 2 | Comp 3 | +|---|---|---|---|---| +| Branded search volume | | | | | +| Wikipedia entity | | | | | +| Knowledge panel | | | | | +| Editorial mentions / month | | | | | +| Social following | | | | | +| Reviews aggregate | | | | | + +--- + +## Prioritized gap-closing roadmap + +[Sequenced list of actions, with effort and expected impact.] + +### Quarter 1 +1. [Action] - [effort] - [expected impact] +2. [Action] - [effort] - [expected impact] + +### Quarter 2 +1. [Action] + +### Quarter 3+ +[Strategic plays that take longer to execute.] + +--- + +## What we should defend + +Areas where we currently lead and need to maintain: + +- [Strength] +- [Strength] +- [Strength] + +A defensive strategy is as important as a gap-closing one. diff --git a/skills/seo-competitor/references/content-gap-method.md b/skills/seo-competitor/references/content-gap-method.md new file mode 100644 index 0000000..f7f0083 --- /dev/null +++ b/skills/seo-competitor/references/content-gap-method.md @@ -0,0 +1,225 @@ +# Content Gap Method + +A detailed methodology for finding content gaps between your site and competitors. The output is a prioritized list of topics or queries the competition ranks for and you do not, ranked by opportunity. + +This is the methodology. For the orchestrated version that runs against the Ahrefs MCP, use `seo-content-gap-audit`. + +--- + +## What a content gap is (and is not) + +A content gap is a query or topic where: + +- One or more competitors rank in the top 10 +- You do not rank in the top 100 (or rank weakly) +- The query is plausibly something your audience cares about +- You could credibly produce content that addresses it + +A content gap is not: + +- Every keyword a competitor ranks for. Many of those will not match your audience. +- Branded queries for the competitor. You will never rank for "[CompetitorName] login" and should not try. +- Queries with unwinnable SERPs (dominated by Reddit, video, or marketplace listings) unless you have an unusual asset. + +--- + +## Step 1: define the competitor set + +Three categories of competitors. Include all three. + +### Direct competitors + +Same product, same audience. Found in your "industry," your sales process, your churn data. + +### Search competitors + +Whoever ranks for the queries you care about. Often surprising. Often includes industry publications, aggregators, and adjacent SaaS tools you do not consider competition commercially. + +To find search competitors: + +1. Pull your top 20 priority queries. +2. Note the top 10 ranking domains for each. +3. Aggregate. Domains that appear 5+ times are search competitors, even if they are not direct. + +### Aspirational competitors + +Brands that own the topic-area you want to own. Often larger or older. Useful for surfacing topics, less useful for direct comparison. + +Build a final set of 5-10 competitors. More than that gets noisy. + +--- + +## Step 2: pull keyword data + +For each competitor, pull the queries they rank for in the top 10 (or top 20 for completeness). + +Filter out: + +- Branded queries containing the competitor name +- Queries with monthly volume below your relevance threshold (commonly 50-100, lower for niche industries) +- Queries with no clear commercial or informational intent (typos, location-specific irrelevant queries, etc.) +- Queries with parent topic that does not apply to your business + +Tools: Ahrefs Site Explorer (Organic keywords), Semrush Organic Research, or DataForSEO equivalents. + +--- + +## Step 3: build the gap matrix + +Cross-reference all competitors against your site. + +| Query | Competitor 1 position | Competitor 2 position | Competitor 3 position | Your position | Monthly volume | Difficulty | +|---|---|---|---|---|---|---| +| query a | 3 | 7 | - | 45 | 1,200 | 32 | +| query b | 5 | 4 | 8 | not ranking | 800 | 28 | +| query c | 1 | - | 5 | 12 | 500 | 41 | + +Three categories emerge: + +- **Pure gaps:** competitors rank, you do not. Highest opportunity. Filter for queries where 2+ competitors rank. +- **Weak coverage:** you rank but poorly (positions 11-50). Often the fastest wins. +- **Saturated topics:** you and 1+ competitors all rank well. Defensive territory; opportunity to leapfrog. + +Focus the next steps on Pure gaps and Weak coverage. + +--- + +## Step 4: cluster by topic + +Raw query lists are unmanageable. Cluster by topic so you can plan content, not chase individual keywords. + +### Method + +Group queries that share intent and can be answered by the same piece of content. + +- "best crm for startups," "top crm small business," "crm software comparison" - one cluster, one comparison piece. +- "how to choose a crm," "crm buying guide" - same cluster. +- "what is a crm," "crm definition" - separate cluster (top-of-funnel, glossary or pillar lead-in). + +A cluster is one piece of content (or a closely-related set: pillar + spokes). + +### Output + +| Cluster | Sample queries | Total monthly volume | Avg difficulty | Recommended format | Lead competitor | +|---|---|---|---|---|---| +| | | | | | | +| | | | | | | + +--- + +## Step 5: assess each cluster + +For each cluster, answer: + +### Audience fit + +Does this cluster match your audience? If you sell to enterprise but the cluster is dominated by SMB intent ("free crm for solopreneurs"), score it low. + +### SERP analysis + +Open the SERP for the highest-volume query in the cluster. Note: + +- **Result types:** organic blue links, video, AI overview, featured snippet, local pack, shopping. Some SERPs leave little real estate for new entrants. +- **Result formats:** what kind of pages rank? Blog posts, comparison pages, product pages, free tools, video? +- **Domain mix:** dominated by big publishers (HubSpot, Forbes), niche players, Reddit, or peer companies? +- **SERP volatility:** has the top 10 been stable, or churning? + +### Effort estimate + +How long would it take to produce content competitive with what is ranking? Be honest. Some clusters need a 4,000-word definitive guide with original research. Others need a 1,200-word how-to. + +### Scoring + +Combine into a simple opportunity score per cluster. Example: + +``` +Opportunity = (Volume × Audience Fit × SERP Winnability) / Effort +``` + +Where: + +- **Volume:** total monthly volume across cluster +- **Audience Fit:** 1 (poor), 2 (decent), 3 (perfect match) +- **SERP Winnability:** 1 (saturated, big domains), 2 (mixed), 3 (gettable) +- **Effort:** hours of writing, research, asset creation + +This is not a precise formula. Use it to rank clusters, then sanity-check the top of the list against editorial judgment. + +--- + +## Step 6: produce the gap report + +A typical output deliverable: + +### Section 1: executive summary + +- Top 10 clusters ranked by opportunity score +- Estimated total monthly traffic potential if you captured the average competitor position +- Estimated effort (in hours or pieces of content) to address the top 10 + +### Section 2: cluster details + +For each top cluster: + +- Cluster name and theme +- Sample queries with volume and difficulty +- SERP analysis snapshot +- Lead competitor's content URL with a one-line note on what makes it strong +- Recommended content format and length +- Recommended hook or angle +- Estimated effort +- Why we should rank: the unique asset, perspective, or data we can bring + +### Section 3: clusters to skip + +Clusters that surfaced but should not be pursued, with the reason. (Audience mismatch, SERP unwinnable, etc.) Documenting skips prevents re-litigation. + +### Section 4: next steps + +- Hand-off to `content-strategy` for editorial planning +- Production sequencing (which cluster ships first) +- Measurement: how will you track whether the gap is closing + +--- + +## Worked example + +**Site:** B2B project management tool, 50-person company, target audience is engineering leads at series-B SaaS startups. + +**Competitors (5):** +1. Linear (direct, peer) +2. Jira (direct, incumbent) +3. Notion (adjacent, encroaching) +4. Asana (direct, larger) +5. Height (direct, peer) + +### Gap matrix excerpt + +| Cluster | Sample queries | Volume | Difficulty | Lead competitor | Audience fit | SERP winnable | Effort | Opportunity | +|---|---|---|---|---|---|---|---|---| +| "linear vs jira" | 5,400 | 38 | linear.app | High | Mixed | Med | High | +| "engineering project management" | 2,100 | 42 | linear.app | High | Big domains | Med | High | +| "agile sprint planning" | 14,000 | 55 | atlassian.com | Med | Saturated by Atlassian | High | Low | +| "github issue templates" | 3,200 | 28 | github.com | High | Owned by github.com | Med | Skip | + +### Recommendations + +- **Pursue:** "linear vs jira" cluster (5 related comparison queries, 7,200 combined monthly volume, mid-effort, audience-perfect). Format: comparison page anchored by an internal POV piece. +- **Pursue:** "engineering project management" cluster (broader topic, 4 related queries, requires a pillar piece + 3 spokes). Format: pillar guide + spokes. +- **Skip:** "agile sprint planning." Atlassian owns this with deep, mature content; effort to compete is too high vs opportunity. +- **Skip:** "github issue templates." github.com itself ranks #1; even strong content will not displace. + +### Next steps + +- Hand the two pursued clusters to content-strategy for editorial sequencing. +- Track positions weekly for the cluster's primary queries. +- Re-run the gap analysis quarterly to spot new gaps as competitors publish. + +--- + +## When to re-run + +- **Quarterly** as a routine. +- **After a major competitor launch** (new product page, big content push, redesign). +- **After a search algorithm update** (especially core updates that reshuffle SERPs). +- **When entering a new audience segment** (segment-specific competitors emerge). diff --git a/skills/seo-content-audit/SKILL.md b/skills/seo-content-audit/SKILL.md new file mode 100644 index 0000000..36ecee8 --- /dev/null +++ b/skills/seo-content-audit/SKILL.md @@ -0,0 +1,193 @@ +--- +name: seo-content-audit +description: "Audit existing content across a site to decide what to keep, update, merge, redirect, or delete. Use this skill whenever the user wants to audit existing content, fix content decay, resolve keyword cannibalization, prune underperforming pages, prioritize content updates, or apply a keep/update/merge/redirect/delete framework to a content library. Triggers on content audit, content decay, content refresh, cannibalization, keyword cannibalization, prune content, delete pages, redirect old pages, content inventory, what to keep, what to update, content scorecard, evergreen refresh. Also triggers when traffic is dropping site-wide and the cause might be content quality, even if 'audit' is not said explicitly." +category: seo-foundation +catalog_summary: "Keep/update/merge/redirect/delete decisions across a site" +display_order: 6 +--- + +# Content Audit + +Inventory existing content, score it, and decide for each piece: keep, update, merge, redirect, or delete. Stack-agnostic. Works on blogs, marketing sites, knowledge bases, and product content. + +--- + +## When to use + +- Inheriting a content library you did not create +- Diagnosing site-wide traffic decline +- Resolving cannibalization (two pages competing for the same query) +- Pre-migration cleanup +- Annual or semi-annual content health check +- Pruning before a redesign or replatform + +## When NOT to use + +- Optimizing a single page (use `seo-onpage`) +- Planning new content (use `seo-keyword`) +- Comparing your content to competitors (use `seo-competitor`) +- Site-level technical issues (use `seo-technical`) + +--- + +## Required inputs + +- The site URL and access to crawl it (or a complete URL list) +- Search console access (or a 12-month export) +- Analytics access (sessions, conversions, engagement) +- A backlink tool (to identify pages with referring domains worth preserving) + +--- + +## The framework: 5 actions + +For every content piece, the audit produces one of five decisions. + +### 1. Keep +The page performs well, has clear intent, and needs no changes. + +**Signals:** +- Top 10 ranking for its primary query +- Consistent traffic with no decay +- Healthy engagement (above-site-average time on page or interaction rate) +- Up-to-date information + +### 2. Update +The page has potential but is underperforming due to fixable issues. + +**Signals:** +- Page 2 ranking for high-value queries (rank 11 to 30) +- Traffic decay over the last 6 to 12 months +- Information gone stale +- Title or meta need rewriting for CTR +- Thin content that could expand to match competitor depth +- Missing schema or other technical hygiene + +### 3. Merge +Two or more pages target overlapping queries and should consolidate. + +**Signals:** +- Cannibalization (multiple pages ranking for the same query, none ranking well) +- Significant content overlap between pages +- Combined, they would outperform either alone +- Both have backlinks worth preserving + +### 4. Redirect +The page has no future but has assets (links, equity) worth preserving. + +**Signals:** +- No traffic, no rankings +- Holds backlinks (especially editorial ones) +- A relevant target page exists that would benefit from the equity +- Topic is still relevant but this specific page is not + +### 5. Delete (and let return 404 or 410) +The page has no future and no assets worth preserving. + +**Signals:** +- No traffic, no rankings, no backlinks +- Content is outdated and not worth updating +- Topic is no longer relevant +- Even thin or spam content from a previous era + +Note: In most cases, return 410 (gone) for intentionally deleted content. 410 is processed faster than 404 and signals the deletion was deliberate. + +--- + +## Scoring inputs + +Pull these for every URL before deciding: + +| Metric | Source | Threshold for "low" | +|---|---|---| +| Sessions (last 90 days) | Analytics | <10/month | +| Organic traffic (last 90 days) | Search console or analytics | <5/month | +| Average position for top query | Search console | >30 | +| Impressions (last 90 days) | Search console | <100/month | +| Click-through rate | Search console | <1% (when impressions exist) | +| Referring domains | Backlink tool | 0 | +| Engagement (avg time on page) | Analytics | <30 seconds | +| Last meaningful update | Manual / git | >24 months | +| Word count | Crawler | <300 (for articles) | +| Internal links in | Crawler | 0 | + +A page can survive low scores on a few metrics. A page that fails on most is a delete or redirect candidate. + +--- + +## Decision matrix + +A simplified decision tree: + +``` +Has traffic? ─── Yes ──── Recent decay? ─── Yes ── UPDATE + │ │ + │ └── No ─── KEEP + │ + └── No ──── Has backlinks? ─── Yes ── Has relevant target? ─── Yes ── REDIRECT + │ │ + │ └── No ─── UPDATE (rebuild) + │ + └── No ──── Cannibalizing another page? ─── Yes ── MERGE + │ + └── No ─── DELETE (410) +``` + +For overlapping pages, "merge" usually wins over "delete" because it preserves both link equity and any topical authority. + +--- + +## Workflow + +1. **Inventory.** Pull a complete URL list from the crawl, sitemap, and search console (some indexed pages may not be in the sitemap). +2. **Pull the metrics.** Sessions, organic, search console rank/CTR, backlinks, last-modified date, word count. +3. **Score each URL.** Use the framework. Mark a decision: Keep / Update / Merge / Redirect / Delete. +4. **Identify cannibalization clusters.** Group URLs targeting the same query. Decide which becomes the canonical, what to merge, what to redirect. +5. **Sequence the work.** Do redirects and deletes in batches. Plan updates by priority (highest-traffic-recovery potential first). +6. **Implement.** With change tracking. Re-crawl after each batch to confirm no broken redirect chains. +7. **Measure.** Track aggregate organic traffic 30, 60, 90 days post-audit. + +--- + +## Failure patterns + +- **Deleting pages with backlinks.** Always check referring domains before deleting. A redirect preserves equity at near-zero cost. +- **Updating pages that should be merged.** Two thin pages updated to medium pages still cannibalize. Merge first. +- **Merging without preserving the better URL.** Pick the merge target by which URL has stronger signals (older URL, more backlinks, better URL slug, currently better ranking), not which one has more content. +- **Mass-deleting low-traffic pages.** Some have value: fresh pages still ramping, niche pages serving a specific audience, evergreen pages with seasonal traffic. Do not bulk-delete by sessions alone. +- **Over-aggressive pruning of "old" content.** Date alone is not a delete signal. Topic relevance and intent quality are. +- **No post-audit measurement.** Without measurement, you cannot tell if the audit worked. + +--- + +## Output format + +Default output: a spreadsheet with one row per URL, plus a summary markdown report. + +**Spreadsheet columns:** +- URL +- Page type (article, product, category, etc.) +- Sessions (90d), organic clicks (90d), impressions (90d), avg position +- Referring domains +- Word count +- Last modified +- Decision (keep / update / merge / redirect / delete) +- Merge target / redirect target (if applicable) +- Priority (1-5) +- Notes + +**Summary report:** +1. Inventory totals (URLs by decision) +2. Cannibalization clusters identified +3. Top 20 update priorities +4. Redirect map (CSV) +5. Delete list +6. Implementation roadmap (sequenced by priority) +7. Measurement plan + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Spreadsheet column definitions and report template. +- [`references/cannibalization-resolution.md`](references/cannibalization-resolution.md) - Detailed methodology for resolving cannibalization clusters. diff --git a/skills/seo-content-audit/references/audit-template.md b/skills/seo-content-audit/references/audit-template.md new file mode 100644 index 0000000..246de40 --- /dev/null +++ b/skills/seo-content-audit/references/audit-template.md @@ -0,0 +1,223 @@ +# Content Audit Template + +Spreadsheet column definitions and report template for a site-wide content audit. The output is a per-URL decision (keep / update / merge / redirect / delete) plus a summary report for stakeholders. + +--- + +## What this audit produces + +- A spreadsheet (one row per URL) with all signals and the final decision +- A report that summarizes the decisions, the rationale, and the next-step backlog +- A roll-up of expected SEO impact and effort + +--- + +## Required spreadsheet columns + +Every row is one URL. Every column below is required. + +| Column | Type | Source | Description | +|---|---|---|---| +| **URL** | Text | Crawl | Full URL | +| **Title tag** | Text | Crawl | Current `<title>` | +| **H1** | Text | Crawl | Current H1 | +| **Word count** | Number | Crawl | Body text words | +| **Publish date** | Date | CMS / inferred | Original publish date | +| **Last updated** | Date | CMS | Most recent meaningful update | +| **Page type** | Pick list | Manual / patterned URL | Article / product / category / landing / utility / legal / etc. | +| **Topic cluster** | Pick list | Manual | Which topic cluster (from content strategy) | +| **Primary query target** | Text | Manual / GSC top query | The query the page should rank for | +| **Sessions (last 90d)** | Number | Analytics | Organic sessions | +| **Conversions (last 90d)** | Number | Analytics | Goal completions attributable to this URL | +| **Top ranking position** | Number | GSC / rank tracker | Best position achieved in last 90d | +| **Average position** | Number | GSC | Average position in last 90d | +| **Impressions (last 90d)** | Number | GSC | | +| **CTR (last 90d)** | Number | GSC | | +| **Backlinks (referring domains)** | Number | Backlink tool | | +| **Internal inlinks** | Number | Crawl | Number of internal pages linking to this URL | +| **Last meaningful traffic** | Date | Analytics | Most recent month with traffic above threshold | +| **Decision** | Pick list | Manual | Keep / Update / Merge / Redirect / Delete | +| **Reasoning** | Text | Manual | One sentence per decision | +| **Action notes** | Text | Manual | What needs to happen if Update or Merge | +| **Owner** | Person | Manual | Who executes | +| **Target completion** | Date | Manual | When the action ships | +| **Status** | Pick list | Manual | Backlog / In progress / Shipped / Verified | + +--- + +## Optional but recommended columns + +| Column | Description | +|---|---| +| **Cannibalization risk** | Other URLs ranking for the same primary query. See `cannibalization-resolution.md`. | +| **Schema present** | Yes / No / Type | +| **Has index tag** | Indexable / noindex | +| **Status code** | 200 / 301 / 404 etc. (catches accidental noindex or broken pages) | +| **Time on page** | From analytics; rough engagement signal | +| **Bounce rate or scroll depth** | From analytics | +| **Current canonical** | Self / other URL | +| **Image count** | Helps identify thin pages | +| **Outbound external links** | | +| **Topic authority signal** | Original research, expert author, structured comparison, etc. - subjective but useful | + +--- + +## The 5 decision types + +### Keep + +Page is performing or recently published. No action needed. Track for future audits. + +**Default for:** +- Top 20% of pages by sessions +- Pages within 3 months of publish (too early to judge) +- Cornerstone pages with strong rankings or backlinks + +### Update + +Page is on the right topic but has decayed (rankings down, content stale, broken links, missing schema). + +**Action:** add to the editorial backlog with a specific update brief. Common updates: refresh examples and dates, expand thin sections, add new H2s for related queries surfacing in GSC, improve title and meta, add schema, update screenshots and links. + +### Merge + +Two or more pages cover the same intent and split signals. Combine into one stronger page. + +**Action:** pick the canonical winner (usually the one with more backlinks and more search visibility), redirect the loser(s) to the winner, fold the loser's unique content into the winner. + +### Redirect + +Page no longer relevant but has equity (backlinks, traffic, internal links) worth preserving. + +**Action:** 301 redirect to the closest topical match. If no match exists, redirect to the parent category or topic hub. Avoid blanket redirects to homepage (Google often treats them as soft 404s). + +### Delete + +Page has no traffic, no rankings, no backlinks, no internal links pointing to it, and no strategic role. + +**Action:** return 410 Gone (preferred) or 404 if 410 is not supported. Update sitemap. Remove internal links pointing to the deleted page. + +### Decision tree + +``` +Page is performing well? +├── Yes → Keep +└── No → Page is on a relevant topic? + ├── Yes → Page is the only one on this topic? + │ ├── Yes → Update (refresh and expand) + │ └── No → Merge (consolidate into stronger version) + └── No → Page has equity (backlinks, internal links)? + ├── Yes → Redirect to closest topical match + └── No → Delete (410 Gone) +``` + +--- + +## Triage thresholds + +The audit looks at hundreds or thousands of URLs. Triage thresholds let you focus. + +### Performing (default Keep) + +- 100+ organic sessions in last 90 days, OR +- 1+ conversions in last 90 days, OR +- 10+ referring domains, OR +- Average position 1-10 for primary query + +### Decaying (default Update or Merge) + +- 5-100 sessions in last 90 days +- Average position 11-50 +- Last meaningful traffic 6-24 months ago + +### Dormant (default Redirect or Delete) + +- 0-5 sessions in last 90 days +- Average position 51+ +- Last meaningful traffic 24+ months ago + +These are starting points. Adjust to your site's volume. + +--- + +## Cannibalization check + +For each primary query target, group URLs targeting the same query. If 2+ URLs target the same query: + +- **One ranking, one not:** the non-ranking one is a Merge or Redirect candidate. +- **Both ranking but neither in top 5:** classic split-signal case. Merge into one definitive page. +- **One ranking strong, one ranking weak:** the weak one is a Merge candidate. + +For deeper diagnosis and resolution patterns, see `cannibalization-resolution.md`. + +--- + +## Report template + +The audit produces a stakeholder-readable report. + +### Section 1: executive summary + +- Total URLs audited +- Decisions: Keep / Update / Merge / Redirect / Delete (with counts and percentages) +- Estimated SEO impact: traffic preserved, traffic potential unlocked, traffic risk if action delayed +- Estimated effort: hours of writing, engineering URL work, design work + +### Section 2: decisions by topic cluster + +Per cluster: how many pages, decisions, top action items. + +### Section 3: top opportunities + +The 10-20 highest-leverage actions (typically Updates and Merges that protect strong rankings or unlock obvious wins). + +### Section 4: risks if no action + +What happens if the team does not act. Common: continued ranking decay, cannibalization that suppresses both URLs, technical risk (crawl budget), content sprawl that confuses readers. + +### Section 5: backlog and sequencing + +Prioritized backlog with owners and target dates. Sequence so that: + +- Redirects ship first (they are mechanical and preserve equity) +- Merges ship second (combine before refreshing) +- Updates ship third (work on what remains) +- Deletes happen last (after all redirects and merges that depend on those URLs are in) + +--- + +## Pre-audit checklist + +Before running the audit: + +- [ ] Analytics access granted (GA4 or equivalent) +- [ ] Search Console access granted +- [ ] Crawl tool ready (Screaming Frog, Sitebulb, or hosted equivalent) +- [ ] Backlink data source identified (Ahrefs, Semrush, GSC limited data) +- [ ] Topic clusters defined (from content strategy) +- [ ] Threshold values agreed (sessions, position, age) +- [ ] Decision authority confirmed (who can approve Delete and Merge actions) +- [ ] Implementation owner confirmed (who runs the post-decision work) + +--- + +## Post-audit verification + +After the actions ship: + +- [ ] Verify all redirects resolve correctly (no chains, no loops) +- [ ] Verify all 410/404 pages return correct status +- [ ] Update sitemap to remove deleted URLs and reflect canonical changes +- [ ] Resubmit sitemap in Search Console +- [ ] Monitor the merged URLs for ranking confirmation (typically 2-8 weeks) +- [ ] Re-run a slim audit at 90 days to confirm decay was halted + +--- + +## Sign-off + +Audit produced by: [Name, date] +Decisions approved by: [Name, role, date] +Implementation owner: [Name, date] + +Next audit scheduled: [Date - typically annual or after major content investment] diff --git a/skills/seo-content-audit/references/cannibalization-resolution.md b/skills/seo-content-audit/references/cannibalization-resolution.md new file mode 100644 index 0000000..e4ad239 --- /dev/null +++ b/skills/seo-content-audit/references/cannibalization-resolution.md @@ -0,0 +1,148 @@ +# Cannibalization Resolution + +When two or more pages on the same site compete for the same query, all of them lose. Search engines either pick the wrong one to rank, split the ranking signal across both, or rotate between them unpredictably. + +This reference walks through how to identify and resolve cannibalization. + +--- + +## How to identify cannibalization + +You have cannibalization when: + +- Two or more URLs from your site appear in the top 50 for the same query +- A query has multiple URLs ranking and rotating across the top 30 over time (search console shows this as inconsistent) +- A new page appears for a query and the previously-ranking page drops sharply +- Two URLs on the same site share the same primary intent and substantial content overlap + +**How to find it:** + +1. Export search console queries with multiple ranking URLs +2. Look for queries where the same site appears more than once in the data +3. Check rank stability: if a query bounces between URLs week to week, that is the signal +4. Internal: search your own site (`site:yourdomain.com "exact query"`) and see how many results appear + +--- + +## Resolution decision tree + +For each cannibalization cluster, you have four options. + +``` +Same intent? ─── Yes ──── Substantial content overlap? ─── Yes ── MERGE + │ + └── No ── Different angles, same intent? ─── DIFFERENTIATE + │ + └── No ──── Confirm intent classification, may not be cannibalization +``` + +### Option 1: Merge + +Combine the pages into one canonical page. Use this when: +- Both pages serve the same intent +- Content overlaps substantially +- Combined, the page would be stronger than either alone + +**Steps:** +1. Pick the merge target. Best signals win: highest-ranking URL, most backlinks, older URL, cleaner URL slug. +2. Pull the unique content from the loser pages, integrate into the winner. +3. 301 redirect the loser URLs to the winner. +4. Update internal links pointing at loser URLs to point at the winner. +5. Submit the winner URL for re-crawling. +6. Monitor rankings for 30 to 60 days. + +### Option 2: Differentiate + +Keep both pages, but reposition each to target distinct sub-intents. Use this when: +- The pages serve genuinely different queries that just look similar +- Both have meaningful traffic and rankings that are worth preserving +- The category supports nuanced sub-topics + +**Steps:** +1. Identify the distinct intent each page should target (e.g., "best running shoes" vs "best running shoes for beginners") +2. Rewrite titles, meta, H1, and intros to reinforce the distinct intent +3. Update internal links to use distinct anchor text +4. Cross-link the two pages so each acknowledges the other +5. Update any sitemap or hub page that lists them + +### Option 3: Redirect + +Pick a winner, kill the rest. Use this when: +- One page is clearly stronger +- The losers have no unique content worth preserving +- There is no benefit to maintaining multiple pages + +**Steps:** +1. Pick the winner using the same criteria as merge. +2. 301 redirect the losers to the winner. +3. Pull any unique content from the losers and integrate into the winner if useful. +4. Update internal links. + +### Option 4: Noindex the secondary page + +Keep both pages, but tell search engines to only consider one for ranking. Use this when: +- One page has a strong UX or business reason to exist (e.g., a product variant page) +- It does not need to rank, but does need to exist +- Merging would damage UX + +**Steps:** +1. Add `<meta name="robots" content="noindex, follow">` to the secondary page +2. Confirm the canonical of the secondary page points at itself (not the primary), since canonical and noindex serve different purposes +3. Verify in search console after a week that the noindex took effect +4. Maintain the user-facing functionality of the page + +--- + +## Picking the merge winner + +When you have to choose which URL becomes canonical, use this prioritized scoring: + +1. **Current ranking position.** If one URL is on page 1 and the other on page 3, keep page 1. +2. **Backlinks.** Highest count of referring domains usually wins. +3. **URL quality.** Cleaner slug, fewer parameters, shorter, descriptive. +4. **Internal links in.** More inbound internal links signals existing site structure. +5. **Page age.** Older URLs often have accumulated trust signals. +6. **Content quality.** If all else is tied, pick the one with better content (or the one easier to expand). + +Do not pick by recency of publication or "I just wrote it." Search engines reward signals that have accumulated over time. + +--- + +## Common cannibalization patterns + +### Pattern 1: Old article + new article on same topic + +Common in evergreen sites. Resolution: merge, with the older URL as canonical (preserves backlinks and age signals). + +### Pattern 2: Category page + product page targeting same query + +Resolution: differentiate. Category page targets the broad query ("running shoes"). Product pages target product-specific queries ("[brand] [model] running shoes"). + +### Pattern 3: Blog post + landing page + +Resolution: differentiate aggressively or merge. Blog post targets informational intent. Landing page targets commercial intent. If they keep cannibalizing, the keyword is fundamentally one-intent and one of them needs to retire. + +### Pattern 4: Multiple "best X" listicles for slight variants + +E.g., "best running shoes," "best running shoes for women," "best running shoes for marathons." Resolution: maintain a clear hub-and-spoke structure. The hub page targets the broad query. Spoke pages target specific variants. Cross-link. + +### Pattern 5: Geographic variants + +E.g., "best plumber" vs "best plumber in Denver." Resolution: differentiate by geo modifier in title, H1, content. Use schema (LocalBusiness) for the geo-specific pages. + +--- + +## Verification after resolution + +For 60 days post-resolution, monitor: + +- Rank for the canonical URL on the target query (should stabilize and improve) +- Rank for the merged/redirected URLs (should drop out, which is expected) +- Aggregate impressions and clicks for the cluster (should rise as ranking signals consolidate) +- Internal links pointing at deprecated URLs (should be zero after cleanup) + +If the canonical URL does not improve in rank within 60 days, recheck: + +- Did the redirects fire correctly? (Test 5 random old URLs) +- Are there still other pages on the site competing for the same query? +- Is the canonical URL strong enough on its own to rank? (Compare to top-ranking competitors) diff --git a/skills/seo-content-gap-audit/SKILL.md b/skills/seo-content-gap-audit/SKILL.md new file mode 100644 index 0000000..f7fcf21 --- /dev/null +++ b/skills/seo-content-gap-audit/SKILL.md @@ -0,0 +1,159 @@ +--- +name: seo-content-gap-audit +description: "Audit content gaps and decay using Ahrefs MCP data: missing topics, thin coverage, outdated content, and decaying pages. Use this skill when planning a content roadmap, refreshing a stale catalog, building topical authority, or identifying which existing pages need update versus replacement. Triggers on content gap, content audit, content refresh, content roadmap, decaying content, content decay, topical authority, what topics should we cover, where is competitor content stronger. Also triggers when organic traffic is flat despite consistent publishing." +category: seo-audit-suite +catalog_summary: "Missing topics, thin coverage, outdated content, decay diagnosis" +display_order: 4 +--- + +# SEO Content Gap Audit + +Find content gaps and decay using Ahrefs MCP data. Stack-agnostic. Produces a roadmap of create, update, merge, and prune actions across the existing content catalog and identified topic gaps. + +--- + +## When to use + +- Planning the next quarter or half of content investment +- Refreshing a stale or underperforming content catalog +- Building topical authority in a target space +- Identifying decaying pages before they tank traffic +- Audit prep before a major site redesign or migration +- Diagnosing why content investment is not driving organic growth + +## When NOT to use + +- Pure keyword research (use `seo-keyword`) +- Competitor keyword gap (use `seo-keyword-gap-audit`) +- Single-page optimization (use `seo-onpage`) +- Pure prune-and-redirect decisions (use `seo-content-audit`) +- New site planning with no existing content (use `content-strategy`) + +--- + +## Required inputs + +- Target property and content scope +- Competitor set (3-5 properties with comparable content depth) +- Target topics or pillars (if defined) +- Existing content inventory with URLs, primary topics, publish dates +- Performance data (organic clicks per page, ranked keywords per page) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: 4 categories of content opportunity + +Every content opportunity falls into one of four categories. Different categories need different actions. + +Content gap analysis is sharper with multiple data sources. Ahrefs surfaces keyword and topic gaps (the primary backend below). Similarweb surfaces traffic-driving page-level gaps (which of a competitor's pages earn meaningful traffic, not just rankings). Semrush surfaces SERP-feature gaps (where competitors win answer boxes, knowledge panels, People Also Ask placements). The three platforms often disagree on individual data points; that disagreement is itself a useful signal. + +### Category 1: Missing topics + +Topics with traffic potential where the property has no relevant page at all. Competitors often rank in the top 10. The fix: create new content. + +Pulled from: + +- Ahrefs Content Explorer (top performing content in target topics) +- Competitor top pages (Ahrefs Site Explorer) +- Keyword gap audit output (clustered into topics) + +### Category 2: Thin coverage + +Topics where the property has a page but it is too shallow, narrow, or single-keyword to compete with topical hubs. Competitor pages cover the topic across multiple subtopics. The fix: deepen the existing page or expand into a topic cluster. + +Pulled from: + +- Pages ranking on page 2-3 for target keywords +- Pages with low organic click share relative to ranked keyword volume +- Pages where competitors have longer or broader equivalents + +### Category 3: Outdated content + +Pages that ranked well historically but have lost ground due to staleness. Information is dated, examples are old, the SERP intent has shifted. The fix: refresh with current information and re-promote. + +Pulled from: + +- Pages with declining organic clicks over the last 6-12 months +- Pages with publish dates over 18 months old +- Pages with ranked keywords slipping in position + +### Category 4: Decaying content + +Pages that have lost traffic for reasons not obviously about staleness: SERP feature changes, competitor publishing, intent shifts, internal linking dilution. The fix: diagnose why, then refresh, merge, or redirect. + +Pulled from: + +- Pages with sharp recent traffic drops +- Pages where SERP composition has shifted (more video, more featured snippets, AI overviews) +- Pages that compete with newer pages on the same site (cannibalization) + +--- + +## Workflow + +1. **Charter the audit.** Scope (whole site or section), goal, time window for performance data. +2. **Pull the inventory.** Every URL, with publish date, primary topic, organic clicks, ranked keywords. +3. **Pull competitor coverage.** Top pages and content clusters from each competitor. +4. **Classify each existing page.** Healthy / thin / outdated / decaying / off-topic. +5. **Identify missing topics.** Cross-reference competitor top pages and keyword gap output. +6. **Score each opportunity.** See [`references/content-decision-matrix.md`](references/content-decision-matrix.md). +7. **Cluster.** Group related missing topics into pillar concepts. +8. **Decide actions.** Create / update / merge / redirect / prune for each opportunity. +9. **Sequence the roadmap.** Quarter by quarter, with effort estimates and traffic forecasts. +10. **Hand off.** Output feeds `content-strategy`, `content-and-copy`, and `seo-onpage`. + +--- + +## The action decision matrix + +For each piece of existing content or proposed new content, decide one action. + +| Signal | Action | +| --- | --- | +| Strong page, healthy traffic, current information | Keep. Defend with internal linking and refresh on schedule. | +| Page exists, ranking on page 2-3, content is thin vs SERP | Update. Deepen, restructure, broaden. | +| Page exists, traffic declining, content is dated | Refresh. Update facts, examples, year references, screenshots. | +| Page exists, low or zero traffic, low ranking, no improvement path | Prune or merge. Redirect to a stronger relative if one exists. | +| Multiple pages on overlapping topics | Merge into one canonical page. Redirect the others. | +| Topic missing entirely, competitor coverage strong | Create new page or pillar. | +| Topic missing, but competitors do not rank well either | Validate intent before investing. Could be an opportunity or could be a dead end. | +| Page is off-topic for the property | Redirect to most relevant page or remove from sitemap. | + +--- + +## Failure patterns + +- **All-create, no-update bias.** Teams default to creating new content. Updates and merges often outperform new pieces by a wide margin and at lower cost. +- **Treating publish date as currency.** A 5-year-old page can outrank a 1-month-old page if it is better. Stop deleting old content reflexively. +- **Cannibalization blind spots.** Two pages on overlapping topics dilute each other. Audit for it explicitly. +- **No effort estimates.** A roadmap without effort sizes cannot be sequenced realistically. +- **No traffic forecast.** A roadmap without forecasted impact loses funding fights. Forecast even with wide confidence bands. +- **Refreshing without re-promotion.** A refreshed page needs a re-crawl signal: update sitemap, internal links, distribution. +- **Ignoring intent shift.** Some keywords have shifted from informational to transactional or to AI-answer-dominated. Recognize when the SERP is no longer addressable by the existing format. +- **Confusing decay with seasonality.** A 30% click drop in summer for a back-to-school topic is not decay. Compare year-over-year, not month-over-month. +- **Auditing in isolation from the keyword gap.** The two audits feed each other. Run them adjacent. + +--- + +## Output format + +A content gap audit document with: + +1. **Executive summary.** Top 3 themes, content health verdict, recommended quarterly investment split. +2. **Content inventory snapshot.** Counts by health classification. +3. **Missing topics.** Prioritized list with cluster mapping and traffic forecast. +4. **Thin coverage.** Pages to deepen, with recommendation for each. +5. **Outdated content.** Pages to refresh, with refresh scope. +6. **Decaying content.** Pages to diagnose and act on, with hypothesis for each. +7. **Cannibalization findings.** Page pairs to merge. +8. **Action roadmap.** Quarter by quarter, with effort and forecast. +9. **Methodology.** Data sources, classification criteria, caveats. + +Length: 8-15 pages plus an attached inventory spreadsheet. + +--- + +## Reference files + +- [`references/content-decision-matrix.md`](references/content-decision-matrix.md) - Detailed decision tree for classifying pages and choosing the create/update/merge/prune action, with worked examples. diff --git a/skills/seo-content-gap-audit/references/content-decision-matrix.md b/skills/seo-content-gap-audit/references/content-decision-matrix.md new file mode 100644 index 0000000..65f3685 --- /dev/null +++ b/skills/seo-content-gap-audit/references/content-decision-matrix.md @@ -0,0 +1,177 @@ +# Content decision matrix + +A decision tree for classifying every page in a content audit and picking the right action. Use it after pulling the inventory and performance data. + +--- + +## The 6 actions + +Every page gets exactly one of these: + +1. **Keep.** Page is healthy. Defend it. +2. **Refresh.** Update facts, examples, screenshots, year references. +3. **Update.** Deeper rework. New sections, restructured argument, expanded scope. +4. **Merge.** Combine with another page. Redirect the loser. +5. **Redirect.** Page has no path forward. Redirect to closest relative. +6. **Prune.** Remove from sitemap, return 410 or noindex. + +--- + +## The decision tree + +Follow the tree top to bottom. The first match wins. + +### Step 1: Is the page on-topic for the property? + +If no: redirect to the most relevant page. If no relative exists, prune. + +### Step 2: Is the page duplicative of another page on the same site? + +If yes: merge. Pick the stronger of the two as the canonical, redirect the other. See "Merge selection criteria" below. + +### Step 3: Has traffic declined sharply over the last 6-12 months? + +Define "sharp": a drop of 40% or more, sustained for 3+ months, not explainable by seasonality. + +If yes: investigate. Likely actions are refresh, update, or redirect depending on root cause. See "Decay diagnosis" below. + +### Step 4: Is the page over 18 months old with stale specifics? + +Stale specifics include: outdated year references, old screenshots, dated examples, products no longer available, statistics from old reports. + +If yes: refresh. Keep the structure. Replace the stale parts. + +### Step 5: Is the page ranking on page 2-3 for relevant terms? + +Page 2-3 means positions 11-30 for keywords with meaningful volume. + +If yes: update. The page has potential. It needs more depth, better structure, or broader scope to break into top 10. + +### Step 6: Is the page getting steady traffic but the content is shallow vs the SERP? + +Shallow means: shorter than the top 3 SERP results, missing subtopics they cover, or single-keyword focused while they cover a topic cluster. + +If yes: update. The page is winning despite being thin. Make it stronger before competitors push it down. + +### Step 7: Is the page getting low traffic with no growth trend? + +Low traffic: under 50 organic clicks per month for an established page (over 12 months old). + +If yes and no clear path to improvement: prune or redirect. Do not waste effort trying to rescue every page. + +### Step 8: Default + +If none of the above, the page is healthy. Keep. Schedule a routine refresh on a 12-18 month cadence. + +--- + +## Merge selection criteria + +When two pages cover overlapping topics, decide which becomes canonical. + +Pick the page with: + +1. Stronger backlink profile (Ahrefs Site Explorer) +2. More ranked keywords with meaningful volume +3. Better URL (cleaner, more descriptive, shorter) +4. Higher current position for the head term + +If the pages have different strengths, often the right move is to keep the better URL and migrate the better content into it. + +Always: + +- 301 redirect the loser to the winner +- Update internal links to point at the canonical +- Notify Search Console (resubmit sitemap) +- Wait 4-8 weeks before evaluating impact + +--- + +## Decay diagnosis + +Sharp traffic decline can have multiple root causes. Diagnose before deciding action. + +### Possible causes and their signatures + +| Cause | Signature | Action | +| --- | --- | --- | +| SERP feature steal (featured snippet, PAA, AI overview) | Position stable, click-through rate fell | Refresh + restructure for snippet capture, or accept the new normal | +| Competitor published better content | Position fell, SERP composition includes new domain | Update to match or exceed competitor depth | +| Intent shifted (informational to transactional, etc.) | SERP composition is now a different content type (e.g., now product pages dominate) | Re-evaluate format, or pivot URL purpose | +| Internal cannibalization | A newer page on same site now ranks for the same term | Merge or differentiate | +| Site-wide ranking decline | Multiple pages lost position simultaneously | Likely site-wide issue, see `seo-traffic-diagnosis` | +| Content went stale | Year references and stats are outdated | Refresh | +| Algorithm update | Decline correlates with a known update date | Audit content quality and E-E-A-T | +| Lost backlinks | Referring domain count fell | See `seo-backlink-audit` for reclamation | +| Migration aftermath | Decline started immediately after a migration | Audit redirect chains and structural changes | + +Always confirm the cause before acting. Wrong diagnosis equals wrong fix. + +--- + +## Worked examples + +### Example 1: keep + +Page: pillar guide on a core topic, 2 years old, top 3 ranking, steady traffic, 800+ clicks/month, content is current. + +Decision: keep. Schedule routine refresh in 6 months. + +### Example 2: refresh + +Page: how-to guide, 3 years old, position 6-8, traffic flat for 12 months, screenshots show old UI, references "in 2023". + +Decision: refresh. Update screenshots, year references, and any tool versions. Re-promote internally. + +### Example 3: update + +Page: 1,200 word article on a category topic, position 14 for the head term, low CTR, top 3 results are 3,000+ word topic hubs covering 8-10 subtopics. + +Decision: update. Expand to cover the missing subtopics. Restructure for skim. Add internal links from related pages. + +### Example 4: merge + +Pages: two articles on closely overlapping topics, both ranking somewhere between positions 8-15 for related terms, splitting traffic. + +Decision: merge. Pick the page with stronger backlinks as canonical. Migrate the unique content from the other. 301 redirect the loser. Update internal links. + +### Example 5: redirect + +Page: outdated tutorial for a tool no longer in use, no organic traffic, no ranked keywords, off-topic for current site direction. + +Decision: redirect to closest relevant page. If none, prune (410 or noindex). + +### Example 6: prune + +Page: thin tag archive with under 5 items, no organic traffic, no internal links, indexed only because of CMS defaults. + +Decision: prune. Noindex via meta tag or remove from sitemap. Add to robots disallow if appropriate. + +--- + +## Effort and traffic forecast cheat sheet + +For sequencing the roadmap, use these rough estimates: + +| Action | Typical effort per page | Traffic impact timeline | +| --- | --- | --- | +| Keep | 0 (or routine refresh in 6-12 months) | None | +| Refresh | 2-4 hours | 30-60 days to see ranking impact | +| Update | 6-16 hours | 60-120 days | +| Merge | 4-8 hours per pair | 60-120 days | +| Redirect | 30 min | Immediate (no ranking impact) | +| Prune | 30 min | Immediate (positive if it removes thin content drag) | +| Create new | 12-30 hours | 90-180 days for new pages to gain traction | + +Updates and merges typically deliver more traffic per hour invested than new content. Most teams underweight them. + +--- + +## Common mistakes + +- **Pruning aggressively without verifying low value.** Some low-traffic pages have backlinks, internal link equity, or seasonal traffic. Audit these before pruning. +- **Refreshing pages that need updates.** A surface refresh on a thin page does not move rankings. Match the action to the root cause. +- **Updating pages that need merges.** Two competing pages on the same topic will keep splitting traffic. Merge first, then optimize. +- **Skipping internal link audit.** Updates and refreshes underperform without renewed internal links pointing to them. +- **Optimizing pages with intent mismatch.** If the SERP is now product pages and the page is an article, no amount of editing fixes that. Either pivot the page type or redirect. +- **Forgetting to notify Search Console.** Resubmit sitemap after major content moves to accelerate recrawl. diff --git a/skills/seo-keyword-gap-audit/SKILL.md b/skills/seo-keyword-gap-audit/SKILL.md new file mode 100644 index 0000000..ac38d93 --- /dev/null +++ b/skills/seo-keyword-gap-audit/SKILL.md @@ -0,0 +1,161 @@ +--- +name: seo-keyword-gap-audit +description: "Find keywords competitors rank for that the target property does not, and prioritize them by opportunity. Uses Ahrefs MCP for keyword and competitor data. Use this skill when planning content investment, identifying quick wins, building a content calendar against a competitor set, or scoping a market entry. Triggers on keyword gap, content gap, competitor keywords, opportunity keywords, what should we target, where are competitors winning, keyword opportunity. Also triggers when planning content for a new market or after losing organic share to a specific competitor." +category: seo-audit-suite +catalog_summary: "Competitor keyword gaps with opportunity scoring and clustering" +display_order: 3 +--- + +# SEO Keyword Gap Audit + +Find keyword opportunities by comparing the target property's organic footprint against a competitor set, using Ahrefs MCP data. Stack-agnostic. Produces a prioritized list of keywords to target with new or improved content. + +--- + +## When to use + +- Planning content investment for the next quarter +- Identifying quick-win keywords for fast organic gains +- Scoping market entry into a new vertical +- Refreshing a stale content strategy +- Diagnosing why a competitor is gaining organic share +- Pre-acquisition due diligence on growth ceiling + +## When NOT to use + +- Pure keyword discovery without a competitor frame (use `seo-keyword`) +- Single-page optimization (use `seo-onpage`) +- Content audit on existing pages (use `seo-content-audit`) +- Topic and pillar planning (use `content-strategy`) + +--- + +## Required inputs + +- Target property +- Competitor set (3-5 properties with overlapping intent and audience) +- Target market and language +- Business priorities (which segments matter most) +- Existing content inventory (URLs and primary topics) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: the gap matrix + +A keyword can fall into one of four cells based on whether the target ranks and whether competitors rank. + +| | Target ranks | Target does not rank | +| --- | --- | --- | +| **Competitors rank** | Shared territory (defend and grow) | Pure gap (the opportunity) | +| **Competitors do not rank** | Unique territory (asset to protect) | Untouched (validate before investing) | + +The audit focuses primarily on the "pure gap" cell. The other cells get secondary treatment. + +### Pure gap (top focus) + +Keywords where one or more competitors rank in the top 10 and the target does not rank at all or ranks past page 3. These are the primary opportunities. + +### Shared territory + +Keywords where both target and competitors rank. Useful for defending position and finding pages to push from page 2 to page 1. + +### Unique territory + +Keywords where the target ranks and no competitor does. These are differentiators. Audit to confirm they are actually valuable (not just irrelevant terms). + +### Untouched + +Keywords no one in the set ranks for. Could be opportunity or could be irrelevant. Validate intent before investing. + +--- + +## Opportunity scoring + +Not every gap keyword is worth pursuing. Score each candidate. + +### Scoring dimensions + +| Dimension | What it measures | Weight | +| --- | --- | --- | +| Search volume | Estimated monthly searches in target market | 20% | +| Business relevance | How close to a money topic for the target | 30% | +| Difficulty | How hard to rank (Ahrefs KD or proxy) | 15% | +| Intent match | Whether target can satisfy the dominant intent | 20% | +| Position potential | Realistic top 3 reach within 6 months | 15% | + +Weights adjust based on goal. For quick wins, weight position potential and difficulty higher. For strategic territory, weight business relevance and volume higher. + +### Opportunity score formula + +``` +score = (volume_normalized * 0.2) + + (relevance_score * 0.3) + + (difficulty_inverted * 0.15) + + (intent_match * 0.2) + + (position_potential * 0.15) +``` + +Where each input is normalized to 0-100. The result is a 0-100 score. + +### Banding for action + +| Score | Action | +| --- | --- | +| 80-100 | Top priority. Plan content this quarter. | +| 60-79 | Strong priority. Plan within 6 months. | +| 40-59 | Watch list. Revisit if competitive landscape shifts. | +| Below 40 | Park or drop. | + +--- + +## Workflow + +1. **Define the competitor set.** 3-5 properties. Confirm they share intent and audience. +2. **Pull keyword data.** For each property: organic keywords, top pages, traffic estimates. +3. **Build the gap matrix.** Label each keyword with which property ranks where. +4. **Filter to the pure gap cell.** Strip out the other cells for now. +5. **Validate intent.** For each keyword, confirm the SERP intent matches what the target can produce. +6. **Score by opportunity.** Use the formula. See [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md). +7. **Cluster.** Group related keywords into topics. One topic, one piece of content. +8. **Map to existing content.** Some gap keywords are addressable by updating an existing page rather than creating new. +9. **Sequence.** Build the prioritized list with action (create / update / merge / new pillar). +10. **Hand off.** Output feeds `content-strategy` and `seo-onpage`. + +--- + +## Failure patterns + +- **Wrong competitor set.** Choosing competitors by brand recognition rather than SERP overlap produces gap lists that are not actually competitive. Pick competitors that fight you in the SERPs. +- **Volume worship.** High-volume gap keywords are often unrealistic. A 50-volume keyword you can rank for beats a 5,000-volume keyword you cannot. +- **Ignoring intent.** A gap keyword where the SERP is dominated by tools or marketplaces is not addressable by an article. Match content type to intent. +- **Skipping clustering.** Targeting individual keywords instead of topics produces thin content that loses to topical hubs. +- **Over-relying on Ahrefs KD.** Difficulty scores are heuristics. Look at the actual SERP. If it is dominated by Forbes and Wikipedia, KD is misleadingly low. +- **No business filter.** A high-volume gap with zero buyer intent is a vanity opportunity. Filter for relevance. +- **One-shot audits.** Gap closes and reopens as competitors publish. Rerun on a cadence. +- **Forgetting unique territory.** Defending what you uniquely rank for can be more valuable than chasing gaps. Audit both directions. +- **Single-language audits in multi-market sites.** Run separate gap audits per market. Patterns differ. + +--- + +## Output format + +A keyword gap audit document with: + +1. **Executive summary.** Top 3 themes and top 10 priority keywords. +2. **Competitor set.** Who, why selected, SERP overlap evidence. +3. **The gap matrix.** Counts and patterns across the four cells. +4. **Pure gap analysis.** The opportunity list, scored and banded. +5. **Topic clusters.** Groups of related keywords mapped to content concepts. +6. **Action map.** Create / update / merge decisions per cluster. +7. **Quick wins.** Top 5-10 highest-confidence opportunities. +8. **Strategic plays.** High-impact, longer-horizon investments. +9. **Methodology.** Data sources, scoring weights, caveats. + +Length: 6-15 pages plus an attached opportunity spreadsheet. + +--- + +## Reference files + +- [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md) - Scoring rubric with normalization rules, formula, and worked examples. diff --git a/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md b/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md new file mode 100644 index 0000000..3b9af2a --- /dev/null +++ b/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md @@ -0,0 +1,233 @@ +# Opportunity scoring rubric + +A scoring framework for ranking keyword gap opportunities. The score combines five normalized inputs into a single 0-100 ranking. Use it to convert a long gap list into a prioritized roadmap. + +--- + +## The 5 inputs + +### 1. Search volume (weight: 20%) + +Monthly search volume in the target market. + +Normalize on a log scale because volume is heavily skewed: + +| Volume range | Normalized score (0-100) | +| --- | --- | +| 0-100 | 20 | +| 100-500 | 40 | +| 500-2,000 | 60 | +| 2,000-10,000 | 80 | +| 10,000+ | 100 | + +Use Ahrefs Keywords Explorer for the volume figure. Confirm the country setting matches the target market. + +### 2. Business relevance (weight: 30%) + +How close is this keyword to a revenue or conversion topic? + +Score on intent stage: + +| Stage | Normalized score | Examples | +| --- | --- | --- | +| Direct purchase intent | 100 | "buy [product] online", "[product] price" | +| Comparison and evaluation | 80 | "best [product] for [use case]", "[product A] vs [product B]" | +| Problem-aware research | 60 | "how to [solve problem]", "what is [problem]" | +| Top-of-funnel education | 40 | "[broad topic] guide", "[topic] meaning" | +| Tangentially related | 20 | Adjacent topic with weak conversion path | +| Off-topic | 0 | Drop | + +Adjust based on business model. SaaS values evaluation-stage highly. Ecommerce values direct purchase highly. Media values volume across all stages. + +### 3. Difficulty (weight: 15%) + +How hard is it to rank in the top 10? Use Ahrefs Keyword Difficulty as the starting input, but verify against the actual SERP. + +Invert the score. Lower difficulty equals higher opportunity: + +| KD score | Inverted normalized score | +| --- | --- | +| 0-10 | 100 | +| 11-30 | 80 | +| 31-50 | 60 | +| 51-70 | 40 | +| 71-100 | 20 | + +Override KD if the SERP visibly contradicts it. A KD-15 SERP dominated by Forbes, Reddit, and Wikipedia is harder than a KD-40 SERP of niche bloggers. + +### 4. Intent match (weight: 20%) + +Can the target produce content that matches the dominant SERP intent? + +Look at the top 10 results and classify what they are: + +| SERP type | Match score for an article | Match score for a tool | Match score for a product page | +| --- | --- | --- | --- | +| Articles dominate | 100 | 20 | 0 | +| Tools or calculators dominate | 20 | 100 | 0 | +| Product pages dominate | 0 | 0 | 100 | +| Marketplaces dominate | 20 | 40 | 60 | +| Video dominates | 40 | 60 | 0 | +| Mixed (no dominant type) | 60 | 60 | 60 | + +If the target cannot produce the matching content type, drop the keyword regardless of other scores. + +### 5. Position potential (weight: 15%) + +Realistic top 3 reach within 6 months given current site authority. + +Estimate based on: + +- Current ranking position (if any) +- Domain Rating relative to the SERP +- Content depth required +- Topical authority in this space + +| Current position | DR vs SERP avg | Position potential score | +| --- | --- | --- | +| Top 3 already | Any | Skip (defend, do not gap-target) | +| Position 4-10 | At or above | 100 | +| Position 11-20 | At or above | 80 | +| Position 11-20 | Below | 60 | +| Position 21+ | At or above | 50 | +| Not ranking | Above SERP avg | 60 | +| Not ranking | At SERP avg | 40 | +| Not ranking | Below SERP avg | 20 | + +--- + +## The formula + +``` +score = (volume_normalized * 0.20) + + (relevance_score * 0.30) + + (difficulty_inverted * 0.15) + + (intent_match * 0.20) + + (position_potential * 0.15) +``` + +Score ranges 0-100. Apply the action banding: + +| Score | Action | Typical timeline | +| --- | --- | --- | +| 80-100 | Top priority. Plan content this quarter. | 0-90 days | +| 60-79 | Strong priority. Plan within 6 months. | 90-180 days | +| 40-59 | Watch list. Revisit on landscape shift. | Quarterly review | +| Below 40 | Park or drop. | Annual review | + +--- + +## Worked example 1: high-priority gap + +Keyword: "[mid-funnel evaluation phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 1,800/month | 60 | +| Relevance | Comparison stage | 80 | +| Difficulty | KD 25, SERP confirms accessible | 80 | +| Intent | Articles dominate, target produces articles | 100 | +| Position | Currently position 14, DR above SERP avg | 80 | + +``` +score = (60 * 0.20) + (80 * 0.30) + (80 * 0.15) + (100 * 0.20) + (80 * 0.15) + = 12 + 24 + 12 + 20 + 12 + = 80 +``` + +Band: top priority. Plan this quarter. + +--- + +## Worked example 2: borderline opportunity + +Keyword: "[broader top-of-funnel phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 9,500/month | 80 | +| Relevance | Top-of-funnel education | 40 | +| Difficulty | KD 55 with Forbes in top 3 | 30 (override) | +| Intent | Mixed SERP, target produces articles | 60 | +| Position | Not ranking, DR below SERP avg | 20 | + +``` +score = (80 * 0.20) + (40 * 0.30) + (30 * 0.15) + (60 * 0.20) + (20 * 0.15) + = 16 + 12 + 4.5 + 12 + 3 + = 47.5 +``` + +Band: watch list. Revisit if domain authority grows or if priority shifts. + +--- + +## Worked example 3: drop + +Keyword: "[high-volume but off-topic phrase]" + +| Input | Raw | Normalized | +| --- | --- | --- | +| Volume | 22,000/month | 100 | +| Relevance | Tangentially related | 20 | +| Difficulty | KD 65 | 30 | +| Intent | Marketplaces dominate, target produces articles | 20 | +| Position | Not ranking, DR well below SERP avg | 20 | + +``` +score = (100 * 0.20) + (20 * 0.30) + (30 * 0.15) + (20 * 0.20) + (20 * 0.15) + = 20 + 6 + 4.5 + 4 + 3 + = 37.5 +``` + +Band: drop. High volume is not enough. + +--- + +## Adjusting weights for goal + +Default weights work for general opportunity audits. For specific goals: + +### Quick wins focus + +- Volume: 15% +- Relevance: 25% +- Difficulty: 25% +- Intent: 20% +- Position: 15% + +### Strategic territory focus + +- Volume: 25% +- Relevance: 35% +- Difficulty: 10% +- Intent: 20% +- Position: 10% + +### Defensive (protect rankings) + +Reuse the formula but apply to "shared territory" cell. Position potential weights higher. + +--- + +## Clustering after scoring + +After scoring individual keywords, cluster them. Targeting clusters beats targeting one-off keywords. + +Cluster rules: + +- Same dominant intent +- Overlapping SERP results (top 5 results match for 60%+ of the cluster) +- Naturally addressable by one piece of content + +Apply the highest score in the cluster as the cluster's score for prioritization. + +--- + +## Common mistakes when scoring + +- **Trusting volume estimates blindly.** Ahrefs estimates have wide confidence intervals at low volumes. A "50/month" keyword may be 5 or 200. +- **Treating KD as ground truth.** Always look at the SERP. KD is a heuristic, not a verdict. +- **Scoring before intent matching.** A keyword with mismatched intent scores high on paper but cannot rank for the target. Filter intent first. +- **One-time scoring.** Re-score quarterly. SERPs evolve. Competitor moves change difficulty. +- **No business filter.** A high score on a topic with zero conversion path is not an opportunity. Add a sanity check on relevance. +- **Optimizing for the formula, not the goal.** The score informs the call. The goal makes the call. diff --git a/skills/seo-keyword/SKILL.md b/skills/seo-keyword/SKILL.md new file mode 100644 index 0000000..f635e1f --- /dev/null +++ b/skills/seo-keyword/SKILL.md @@ -0,0 +1,163 @@ +--- +name: seo-keyword +description: "Run keyword research, classify by search intent, cluster into topical groups, and prioritize for content production. Use this skill whenever the user asks to do keyword research, find target keywords, identify ranking opportunities, classify search intent, build a topical map, or plan a content strategy around what people search for. Triggers on keyword research, keyword strategy, search intent, keyword clustering, topic clusters, keyword difficulty, search volume, ranking opportunity, content gap, what should I write about, target keyword, primary keyword, secondary keyword, long-tail. Also triggers when planning a content calendar or new site without keywords yet defined." +category: seo-foundation +catalog_summary: "Discovery, intent classification, clustering, prioritization" +display_order: 3 +--- + +# Keyword Research + +Find the queries worth ranking for, classify them by intent, cluster them into topics, and prioritize what to produce. Stack-agnostic. Tool-agnostic (works with any keyword tool). + +--- + +## When to use + +- Starting a new site or content section +- Planning a content calendar +- Looking for ranking opportunities on an existing site +- Understanding search intent before writing +- Building topic clusters for internal linking +- Identifying content gaps vs competitors + +## When NOT to use + +- Optimizing a single page where the target query is already known (use `seo-onpage`) +- Comparing your site to a competitor across many dimensions (use `seo-competitor`) +- Auditing existing content for performance (use `seo-content-audit`) + +--- + +## Required inputs + +- The site or topic area +- The target audience and what they need +- A keyword tool (Ahrefs, Semrush, Moz, Google Keyword Planner, or similar) OR access to search console for an existing site +- Optional: 3 to 5 known competitors to seed the research + +If no tool is available, the skill still works using SERP inspection and search console data alone, but the volume estimates will be rough. + +--- + +## The framework: 4 stages + +### Stage 1: Discover + +Cast a wide net. Sources: + +- **Seed terms** from the brief or the user's vocabulary +- **Competitor keywords** (any keyword tool will export these) +- **Search console queries** for an existing site (find the page-1 and page-2 queries) +- **Related searches and "People also ask"** in actual SERPs +- **Customer language** (support tickets, sales calls, reviews) +- **Forum and community language** (Reddit, niche forums, Stack Overflow) + +Goal: 200 to 500 candidate keywords for a typical content sprint. More if planning a year of content. + +### Stage 2: Classify by intent + +Every keyword maps to one of four intents. Get this right or the rest is noise. + +| Intent | Signal | Page type that wins | +|---|---|---| +| **Informational** | "how to," "what is," "why," "best way to" | Article, guide, tutorial | +| **Navigational** | brand or product name + modifier | Brand homepage, product page | +| **Commercial** | "best," "review," "vs," "comparison," "alternatives" | Listicle, comparison, review | +| **Transactional** | "buy," "price," "deal," "near me," "for sale" | Product page, category page | + +A keyword tool's volume tells you the demand. The SERP tells you the intent. When in doubt, look at what's actually ranking. If page 1 is articles, the query is informational. If page 1 is product pages, it's transactional. + +**Hybrid intents exist.** "Best running shoes" is commercial-investigational. "Best running shoes under $100" is the same intent narrowed by a budget filter. Treat hybrids as their dominant intent and note the modifier. + +### Stage 3: Cluster + +Group keywords that should target the same page (or topic cluster). + +Two clustering approaches: + +**Approach A: SERP overlap.** If two keywords share at least 3 of the top 10 results, they target the same page. This is mechanical and reliable. + +**Approach B: Topical relevance.** Group keywords by the underlying topic, not just word overlap. "How to start a podcast" and "podcast equipment for beginners" are the same topic, different facets. + +Use both. A typical cluster has: +- 1 primary keyword (highest volume, broadest intent) +- 5 to 15 secondary keywords (variations and long-tails) +- 1 page that targets them all + +### Stage 4: Prioritize + +For each cluster, score on three dimensions: + +**Opportunity** (1 to 5): +- Volume (raw search demand) +- Click potential (some queries answer themselves in the SERP, lowering CTR) +- Conversion potential (does this query attract buyers or browsers?) + +**Difficulty** (1 to 5): +- Domain authority of top results +- Backlink count of top results +- Content depth and freshness of top results +- Whether the SERP has features (featured snippets, AI overview, video carousel) that compete with organic + +**Strategic fit** (1 to 5): +- Does it serve our audience? +- Does it support our positioning? +- Does it link to commercial pages naturally? + +**Priority score = Opportunity + Strategic fit - Difficulty.** + +Rank the clusters. Top 20 percent get produced first. + +--- + +## Workflow + +1. **Define the scope.** What site, what topic area, what audience. +2. **Run discovery.** Pull seeds, competitor exports, search console data, SERP inspections. Aim for 200 to 500 candidates. +3. **Deduplicate and clean.** Remove obvious junk, brand misspellings, irrelevant terms. +4. **Classify by intent.** Mark each keyword. +5. **Cluster.** Group into topical clusters. Aim for 20 to 50 clusters. +6. **Score each cluster** on opportunity, difficulty, and strategic fit. +7. **Prioritize.** Rank by composite score. Identify the top 10 to 20 clusters to produce first. +8. **Output.** Use the template in [`references/keyword-research-template.md`](references/keyword-research-template.md). + +--- + +## Failure patterns + +- **Chasing volume without intent.** A 10,000-volume informational keyword does not drive purchases. Match query to commercial outcome. +- **Targeting impossibly competitive keywords.** New sites cannot rank for "credit cards." Find the underserved long-tail variant. +- **Ignoring search console.** Existing sites already rank for queries they did not target. These are the easiest wins. +- **Treating clusters as one-keyword-per-page.** A page can target 10 to 30 related keywords. One-keyword-per-page leads to thin, cannibalized content. +- **Ignoring SERP features.** A query with a featured snippet, AI overview, and a video carousel above the organic results may not be worth pursuing. +- **Static keyword research.** Search demand shifts. Refresh the research at least annually for evergreen sites, quarterly for fast-moving topics. + +--- + +## Output format + +Default output: a spreadsheet (CSV or sheet) with one row per keyword and one row per cluster, plus a markdown summary with the top 10 to 20 clusters detailed. + +Recommended columns for the keyword sheet: + +| Column | Source | +|---|---| +| Keyword | Discovery | +| Volume | Tool | +| Difficulty | Tool | +| Intent | Manual classification | +| SERP features | Manual or tool | +| Cluster | Stage 3 | +| Cluster role (primary/secondary) | Stage 3 | +| Opportunity score | Stage 4 | +| Strategic fit | Stage 4 | +| Priority | Composite | +| Notes | Free text | + +--- + +## Reference files + +- [`references/keyword-research-template.md`](references/keyword-research-template.md) - Spreadsheet column definitions and a markdown summary template. +- [`references/intent-classification-guide.md`](references/intent-classification-guide.md) - Detailed examples of each of the four intent categories. diff --git a/skills/seo-keyword/references/intent-classification-guide.md b/skills/seo-keyword/references/intent-classification-guide.md new file mode 100644 index 0000000..0b145f2 --- /dev/null +++ b/skills/seo-keyword/references/intent-classification-guide.md @@ -0,0 +1,246 @@ +# Intent Classification Guide + +Detailed examples of each of the four search intent categories. Use this to tag every keyword in research with its intent before deciding what content (if any) to build. + +Intent classification is the most important and most-skipped step in keyword research. Tools surface volume and difficulty. They do not tell you whether the searcher wants to learn, compare, navigate, or buy. Without intent, you produce content that ranks for words but converts nothing. + +--- + +## The four intents + +| Intent | The searcher wants to | Right content | Right CTA | +|---|---|---|---| +| **Informational** | Learn something | Article, guide, video | Subscribe, related content | +| **Navigational** | Reach a specific destination | Branded page, login, location | Direct link | +| **Commercial investigation** | Compare options before buying | Comparison, review, list, buyer's guide | Demo, trial, deeper guide | +| **Transactional** | Take an action (buy, sign up, download) | Product page, pricing, signup, checkout | Buy / sign up / download | + +The same root word can fall into multiple intents depending on modifier. "Crm" alone is ambiguous. "What is a crm" is informational. "Salesforce login" is navigational. "Best crm for startups" is commercial investigation. "Buy salesforce" is transactional. + +--- + +## Informational intent + +The searcher wants to understand, learn, or solve a problem. + +### Signals + +- Question words: what, why, how, when, where, who +- "Guide," "tutorial," "examples," "definition," "explained" +- Topic-only queries with no commercial modifier ("dmarc records," "css grid") +- "How to" + a task + +### Examples + +| Query | Intent depth | Notes | +|---|---|---| +| "what is a service blueprint" | Top-of-funnel learning | Definition piece | +| "how to write a creative brief" | How-to | Step-by-step guide | +| "service blueprint examples" | Mid-funnel learning | Examples gallery | +| "service blueprint vs customer journey map" | Comparison-flavored learning | Overlaps with commercial; treat as info if no products in result | +| "why is css grid useful" | Conceptual | Explainer with code examples | +| "history of bauhaus design" | Background | Editorial / long-form | +| "node js error eaddrinuse" | Troubleshooting | Specific fix article | + +### What to publish + +Long-form articles, guides, glossary entries, video tutorials, original research. Content that earns subscribers, social shares, and backlinks. Not where conversion happens; where awareness builds. + +### CTA approach + +Soft. "Subscribe to the newsletter," "read the related guide," "join the community." A pricing CTA at the end of an informational piece reads as a bait-and-switch. + +### Failure mode + +Producing informational content with hard sales CTAs because someone metric'd it as "low conversion." Informational content's job is awareness and authority. Measure it on assists, brand recall, and downstream conversions, not last-click. + +--- + +## Navigational intent + +The searcher knows what they want and is using search to get there. + +### Signals + +- Brand names ("HubSpot," "Notion") +- Brand + modifier ("HubSpot login," "Notion pricing," "Salesforce careers") +- Product names ("MacBook Pro M4," "Tesla Model Y") +- Domain-style queries ("github.com," "facebook") + +### Examples + +| Query | What the searcher wants | +|---|---| +| "linear" | Linear's homepage | +| "linear login" | Linear's login page | +| "salesforce careers" | Salesforce's careers page | +| "amazon prime" | Amazon Prime's page | +| "github status" | GitHub's status page | + +### What to publish + +For your own brand: own the navigational queries. The homepage, login page, status page, careers page, contact page, pricing page should rank #1 for branded variants. + +For other brands' navigational queries: do not pursue. You will not rank, you should not try, and even if you did, the user does not want you. + +The exception: comparison queries ("Linear alternatives," "vs Linear") are not navigational; they are commercial investigation. See below. + +### CTA approach + +Whatever the destination expects. Login page → login form. Pricing page → buy or trial. Careers page → application. + +### Failure mode + +Treating "alternatives to" queries as navigational. They are not. They are commercial investigation, and a comparison page is the right format. + +--- + +## Commercial investigation intent + +The searcher is in the buying process but not ready to buy. They are comparing, reading reviews, building a shortlist. + +### Signals + +- "Best [category]" ("best crm for small business") +- "Top [category]" ("top hosting providers") +- "[Category] comparison" ("crm comparison") +- "[Brand] vs [brand]" ("notion vs obsidian") +- "[Brand] alternatives" ("alternatives to mailchimp") +- "[Brand] review" ("notion review") +- "[Category] for [audience]" ("crm for startups") +- "Cheap / affordable / free [category]" +- "Buyer's guide for [category]" + +### Examples + +| Query | What the searcher wants | +|---|---| +| "best email marketing tool" | A ranked list of options | +| "mailchimp vs convertkit" | A direct comparison | +| "alternatives to mailchimp" | A shortlist of competitors with pros and cons | +| "convertkit review" | Honest assessment from a third party (or the brand's own page if positioning) | +| "crm for solo consultants" | Curated shortlist for a niche | +| "free project management software" | Filtered list with feature notes | + +### What to publish + +- **For your category (high traffic, broad):** "best of" lists, ranked comparisons, buyer's guides. Honest about tradeoffs. Include yourself if relevant; do not lie about ranking. +- **For your brand vs others:** comparison pages on your own domain ("[YourBrand] vs [Competitor]"). These are the highest-converting content type after pricing pages. +- **For your category by use case:** segment-specific landing pages ("CRM for solo consultants," "CRM for series-A startups"). Use case + CTA. + +### CTA approach + +Stronger than informational, lighter than transactional. "Try [product] free," "see how it compares," "book a demo," "download the buyer's guide." Multiple CTAs are OK because the visitor's progress is uncertain. + +### Failure mode + +Writing a "best of" list that is transparently a sales pitch for your product. Readers and Google can both spot this. Honest comparison pages, even when they include you, perform far better than disguised brochures. + +--- + +## Transactional intent + +The searcher wants to act now. Buy, sign up, download, contact, get a quote. + +### Signals + +- "Buy," "purchase," "order" +- "Sign up," "create account" +- "Download" +- "Get a quote," "request a demo," "contact sales" +- Brand + transactional modifier ("buy [product]," "[product] coupon," "[product] discount") +- "[Product] near me" (local-transactional) +- "[Product] free trial" + +### Examples + +| Query | What the searcher wants | +|---|---| +| "buy iphone 16 pro" | Purchase, fast | +| "salesforce free trial" | Trial signup | +| "download notion mac" | Direct download | +| "request a demo hubspot" | Demo form | +| "plumber near me" | A plumber to call | +| "amazon prime sign up" | Amazon Prime signup flow | + +### What to publish + +Product pages, pricing pages, signup pages, checkout flows, contact pages. Make the transactional path frictionless. Strong CTAs above the fold. Trust signals near the action. + +### CTA approach + +The CTA is the page. One primary action, sized and placed so the user cannot miss it. Secondary actions allowed if they protect the primary (e.g., "talk to sales" alongside "start free trial" for enterprise vs SMB). + +### Failure mode + +Burying the transactional action behind marketing copy. The user came to act. Get out of the way. + +--- + +## Mixed and ambiguous intent + +Many queries do not fit cleanly. Use the SERP to disambiguate. + +### Method + +Open the query in incognito. Look at the top 10 results. + +- All articles? Informational. +- All branded landing pages? Navigational or transactional. +- Mix of comparison pages, "best of" lists, and product pages? Commercial investigation. +- Mix of articles and product pages? Mixed - the safer bet is to produce both kinds of content. + +### Example: "crm software" + +Could be informational ("what is CRM software"), commercial investigation ("which CRM should I pick"), or transactional ("crm software to buy now"). The SERP shows: a definition (HubSpot's), a "best of" list (multiple), several product pages, and a Wikipedia entry. Mixed intent leaning commercial investigation. + +The right play: produce a comparison page that opens with a one-paragraph definition. Catches both intents. + +--- + +## Intent shifts across the funnel + +The same audience moves through intents. + +| Stage | Example query | Intent | Right content | +|---|---|---|---| +| Aware of problem | "team is missing deadlines" | Informational | Article on missed-deadline diagnosis | +| Aware of category | "project management software" | Informational + commercial | Pillar guide | +| Comparing options | "linear vs jira" | Commercial investigation | Comparison page | +| Ready to commit | "linear pricing" | Transactional | Pricing page | +| Already a customer | "linear keyboard shortcuts" | Informational | Help docs | + +Build coverage across the funnel for your category. A site that only addresses transactional intent has nothing to rank for at the top of funnel and loses the audience to category-defining publishers. + +--- + +## Tagging in research + +When pulling keyword research, tag every row. + +| Query | Volume | Difficulty | Intent | Notes | +|---|---|---|---|---| +| "service blueprint" | 8,100 | 32 | Informational | Definition + examples piece | +| "service blueprint vs customer journey" | 1,200 | 28 | Commercial investigation | Comparison piece | +| "service blueprint template" | 2,400 | 25 | Informational + transactional | Template page with download CTA | +| "service blueprint software" | 880 | 41 | Commercial investigation | Buyer's guide | + +The intent tag drives the format and the CTA. Without it, content drifts into whatever the writer felt like producing. + +--- + +## Decision rule + +Once intent is tagged: + +- **Informational:** publish if the topic supports authority-building and the SERP is winnable. Skip if the SERP is dominated by big publishers and you have no asset. +- **Navigational (your brand):** make sure you own it. If not, fix. +- **Navigational (someone else's brand):** skip. +- **Commercial investigation:** publish if you compete in the category. These convert. +- **Transactional:** make sure your product / pricing / signup pages rank for the obvious branded transactional queries. Optimize them aggressively. + +--- + +## When intent surprises you + +Sometimes a query you assumed was one intent reveals as another. Trust the SERP over your assumption. The SERP reflects what Google has learned about searcher behavior at scale, which is more reliable than your guess. diff --git a/skills/seo-keyword/references/keyword-research-template.md b/skills/seo-keyword/references/keyword-research-template.md new file mode 100644 index 0000000..b701650 --- /dev/null +++ b/skills/seo-keyword/references/keyword-research-template.md @@ -0,0 +1,115 @@ +# Keyword Research: [Site or Topic Area] + +**Date:** [YYYY-MM-DD] +**Scope:** [What this research covers] +**Audience:** [Who we are writing for] +**Tools used:** [Which keyword tools were used] + +--- + +## Summary + +**Total keywords analyzed:** [N] +**Clusters identified:** [N] +**Priority clusters (top 20%):** [N] + +[2 to 3 sentence overview. The headline themes, the surprising finds, the strategic priorities.] + +--- + +## Top priority clusters + +The following clusters scored highest on opportunity, strategic fit, and reasonable difficulty. Produce these first. + +### Cluster 1: [Cluster name] +- **Primary keyword:** [keyword] (volume: X, difficulty: Y) +- **Intent:** [Informational / Commercial / Transactional / Navigational] +- **Recommended page type:** [Article / guide / comparison / product page / category] +- **Secondary keywords:** [list 5 to 15] +- **Suggested URL:** [/proposed-slug] +- **Estimated effort:** [Hours or days] +- **Why this cluster:** [1 to 2 sentences on strategic fit] + +### Cluster 2: [Cluster name] +- **Primary keyword:** +- **Intent:** +- **Recommended page type:** +- **Secondary keywords:** +- **Suggested URL:** +- **Estimated effort:** +- **Why this cluster:** + +[Continue for top 10 to 20 clusters.] + +--- + +## Full keyword sheet + +[Link to or attach the spreadsheet.] + +Columns: +1. Keyword +2. Volume +3. Difficulty +4. Intent (I/N/C/T) +5. SERP features (featured snippet, AI overview, PAA, video, image, local pack) +6. Cluster +7. Cluster role (primary / secondary / long-tail) +8. Opportunity score (1-5) +9. Strategic fit (1-5) +10. Priority (composite) +11. Notes + +--- + +## Topic map + +A visual or hierarchical view of how the clusters relate. This becomes the basis for internal linking and information architecture. + +``` +[Top-level topic] + ├── [Cluster A] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + ├── [Cluster B] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + └── [Cluster C] + └── ... +``` + +--- + +## Quick wins + +Existing pages that already rank on page 2 or low page 1 for high-value keywords. Optimizing these is faster than producing new content. + +| URL | Current rank | Target query | Volume | Recommended action | +|---|---|---|---|---| +| | | | | | +| | | | | | + +(Pull from search console: queries with average position 5 to 20 and impressions over 100/month.) + +--- + +## Deferred clusters + +Clusters that did not make the priority cut and why. + +| Cluster | Reason | +|---|---| +| [Cluster name] | Too competitive for current authority | +| [Cluster name] | Low commercial value | +| [Cluster name] | Audience mismatch | +| [Cluster name] | Better suited for paid acquisition | + +--- + +## Refresh schedule + +This research should be revisited: +- **Quarterly** for fast-moving topics (tech, news, trends, finance) +- **Annually** for evergreen topics +- **After any major SERP feature change** (e.g., AI overviews appearing on key queries) +- **After authority increases** that unlock harder keywords (e.g., domain rating going up by 10+ points) diff --git a/skills/seo-offpage/SKILL.md b/skills/seo-offpage/SKILL.md new file mode 100644 index 0000000..fc103e6 --- /dev/null +++ b/skills/seo-offpage/SKILL.md @@ -0,0 +1,168 @@ +--- +name: seo-offpage +description: "Plan and execute off-page SEO including link building, digital PR, brand mentions, citation building, and external authority signals. Use this skill whenever the user wants to build backlinks, plan a digital PR campaign, list local citations, run guest post outreach, develop linkable assets, recover lost links, or audit a backlink profile for risk. Triggers on link building, backlinks, digital PR, brand mentions, citation building, guest post, outreach, linkable asset, broken link building, HARO, podcast outreach, off-page SEO, anchor text, link velocity, toxic backlinks, disavow. Also triggers when the user is trying to grow domain authority or earn coverage." +category: seo-foundation +catalog_summary: "Link building, digital PR, citations, linkable assets" +display_order: 5 +--- + +# Off-Page SEO + +Build the external signals that earn rankings: backlinks, brand mentions, citations, and trusted sources pointing back to the site. Stack-agnostic. + +--- + +## When to use + +- Planning a link-building strategy +- Running digital PR or earned-media campaigns +- Building citations for a local business +- Developing linkable assets (research, tools, calculators) +- Recovering lost backlinks after a migration or audit +- Auditing a backlink profile for spam or toxicity +- Pitching guest posts, podcast appearances, or expert quotes + +## When NOT to use + +- On-site optimization (use `seo-onpage` or `seo-technical`) +- Keyword research and content planning (use `seo-keyword`) +- Competitor backlink research alone (start with `seo-competitor`, then return here for outreach planning) +- Paid link buying (this skill does not endorse or facilitate that) + +--- + +## Required inputs + +- The site or brand getting the links +- The audience and category +- A backlink tool (Ahrefs, Semrush, Moz, Majestic, or similar) for prospecting and monitoring +- A target outcome (rank for X, build authority in Y, recover from Z) + +--- + +## The framework: 4 strategies + +Off-page work splits into four strategy types. Most programs blend them. Pick the mix that fits your phase. + +### 1. Earned media +Links and mentions you earn through coverage, journalism, or contribution. + +- Digital PR (data-driven studies, original research, surveys) +- Expert quotes (HARO, journalist platforms, expert request services) +- Podcast appearances (relevant shows in your category) +- Speaking engagements and conference content +- Newsworthy product launches or company milestones + +**Strength:** Highest authority, hardest to replicate. +**Cost:** Time-intensive, often requires PR or content budget. +**Volume:** Low to medium per quarter. + +### 2. Owned assets +Linkable assets on your own site that attract links passively over time. + +- Original research and reports +- Free tools, calculators, and generators +- Comprehensive guides (the kind that become "the X resource for Y") +- Visualizations and interactive content +- Templates and frameworks +- Industry data trackers (regularly updated benchmarks) + +**Strength:** Compounds over time. Each link points at an evergreen asset. +**Cost:** Upfront content investment. +**Volume:** Slow to start, accelerates as the asset earns mentions. + +### 3. Partnerships and relationships +Links earned through real business relationships. + +- Customer case studies (where they link back) +- Partner programs and integrations +- Co-marketing campaigns +- Industry association memberships +- Speaker and expert contributor relationships +- Affiliate and referral programs + +**Strength:** Trustworthy, contextually relevant. +**Cost:** Time to develop relationships. +**Volume:** Medium and consistent. + +### 4. Citations and listings +Local and category-specific listings that establish entity legitimacy. + +- Google Business Profile (for local businesses) +- Bing Places, Apple Maps Connect +- Industry directories (review-quality only, skip spam directories) +- Niche association directories +- Wikipedia entry (where the brand qualifies for notability) +- Wikidata entry +- Trade publications and category indexes + +**Strength:** Foundational for local and entity SEO. +**Cost:** Low to medium, mostly setup time. +**Volume:** One-time foundation, occasional refresh. + +--- + +## Workflow + +1. **Audit the current profile.** + - Total referring domains + - Domain rating trend + - Top referring pages by traffic value + - Anchor text distribution (over-optimized exact-match anchors are a risk) + - Toxic links (spam directories, link farms, irrelevant categories) + - Lost links (referring domains that disappeared) + +2. **Define the goal.** "Rank top 3 for X by Q4" requires a different tactic mix than "build category authority." + +3. **Pick the strategy mix.** Allocate effort across the 4 strategies. A new site typically goes 70/20/10/0 (assets/citations/partnerships/earned) for the first year. An established site can lean more toward earned media. + +4. **Build the prospecting list.** + - For earned media: relevant journalists, podcast hosts, publication beats + - For owned assets: identify what assets to build based on what gets linked in your category + - For partnerships: list 50 to 100 potential partner sites + - For citations: standard list per category, plus niche directories + +5. **Outreach.** Personalized, value-first. Generic templated pitches damage the brand more than they help. + +6. **Track and measure.** + - Referring domains gained per month + - Domain rating trend + - Anchor text mix (avoid over-optimization) + - Pages on the site attracting links + - Lost link recovery rate + +7. **Audit and disavow.** Quarterly review for toxic links. Disavow only when there is real evidence of harm (manual penalty notice, sudden drop after spam attack). Most sites should not need to disavow. + +--- + +## Failure patterns + +- **Volume over quality.** 100 directory submissions help less than 5 editorial links from category-relevant sites. +- **Buying links.** Risk of manual penalties is real. Cost-adjusted, the ROI rarely works out. +- **Over-optimized anchor text.** If 40 percent of your inbound anchors are "best running shoes," it looks engineered. Aim for natural distribution: brand, naked URL, generic, partial-match, exact-match (in roughly that order of frequency). +- **Generic outreach templates.** "Dear [first name], I love your blog about [topic]" gets archived in seconds. Personalize or do not send. +- **Ignoring lost links.** A 5 percent monthly loss in referring domains compounds. Build a recovery workflow. +- **Treating disavow as a routine cleanup tool.** Disavow is for confirmed spam attacks or penalty recovery, not preemptive hygiene. +- **Working off-page before the site is worth linking to.** A poorly-designed, thin-content site will not convert outreach. Fix on-site first. + +--- + +## Output format + +Default output is a markdown plan at `offpage-strategy.md` plus tracking spreadsheets for prospects and outreach. + +Structure: +1. Current backlink profile summary +2. Goal and target metrics +3. Strategy mix (allocation across the 4 types) +4. Q1, Q2, Q3, Q4 tactical plan +5. Prospecting lists (in spreadsheets) +6. Outreach templates (personalized, never generic) +7. Tracking and measurement plan + +--- + +## Reference files + +- [`references/outreach-templates.md`](references/outreach-templates.md) - Templates for guest posting, expert quotes, broken-link outreach, podcast pitches. +- [`references/linkable-assets-guide.md`](references/linkable-assets-guide.md) - Categories of linkable assets with examples and effort estimates. diff --git a/skills/seo-offpage/references/linkable-assets-guide.md b/skills/seo-offpage/references/linkable-assets-guide.md new file mode 100644 index 0000000..ed9c7d7 --- /dev/null +++ b/skills/seo-offpage/references/linkable-assets-guide.md @@ -0,0 +1,353 @@ +# Linkable Assets Guide + +Categories of linkable assets, with examples and effort estimates. A linkable asset is content (or a tool, or a dataset) that other sites have a reason to link to. Without a linkable asset, link building is begging. With one, it is offering value. + +--- + +## What makes an asset linkable + +A linkable asset has at least one of these properties: + +- **It is the only place to find this thing.** Original data, original tool, original framework. +- **It is the best place to find this thing.** Most comprehensive, most current, most carefully built. +- **It saves the linker time.** A reusable resource the linker would otherwise have to build or explain. +- **It carries authority.** Survey from a recognized brand, published research, expert-authored. +- **It is current.** Updated more recently than alternatives, with the year visible. + +Pages that fail all five are not linkable. They might be useful, but they are not assets that earn links. + +--- + +## Category 1: original research + +Surveys, studies, or data analyses you ran and nobody else has. + +### Examples + +- Annual industry survey (e.g., "State of [category] 2026") +- Benchmark report from your own product data ("the average [metric] across 1,000 companies using us") +- Trend analysis from public data sources you cleaned and synthesized +- Salary or compensation report for your industry +- Pricing transparency report ("what [category] really costs") + +### Effort + +- **Low end:** 40-80 hours (existing data, in-house analysis, single-author write-up) +- **High end:** 200-400 hours (custom survey, n=1,000+, design and PR investment) + +### Link earning rate + +Highest of any category, when done well. A defensible original research asset can earn 100+ referring domains over its life. + +### When to invest + +If you have unique access to data (your product's data, your customer base, your industry network) and you can update annually, this is the highest-leverage asset category. + +### When to skip + +If the data is shallow, the sample is small, or the analysis is obviously self-serving, the asset will be ignored or worse, criticized publicly. + +--- + +## Category 2: free tools + +Calculators, validators, generators, viewers - small interactive utilities that solve a specific problem. + +### Examples + +- Calculators (mortgage, ROI, paycheck, conversion rate) +- Validators (HTML, schema markup, robots.txt, regex) +- Generators (favicon, color palette, password, lorem ipsum, og image) +- Converters (currency, units, file format) +- Viewers (JSON, EXIF, certificate) + +### Effort + +- **Low end:** 20-40 hours (single-purpose calculator, basic UI) +- **High end:** 200+ hours (rich tool with saved state, account integration, PWA, accessibility-perfect) + +### Link earning rate + +High and durable. Tools earn links steadily for years if they remain useful and current. + +### When to invest + +When the problem is recurring, you can build something cleaner than what exists, and the tool naturally surfaces your product as the next step (e.g., a "how much will this site weigh" tool from a perf optimization vendor). + +### When to skip + +When the space is saturated with free tools that already work well. A new "color picker" is unlikely to displace the entrenched ones. + +--- + +## Category 3: definitive guides + +Long-form, exhaustive coverage of a topic that becomes the reference everyone links to. + +### Examples + +- "The complete guide to DMARC" +- "The HTTP status code reference" +- "Web performance metrics explained" +- "The 2026 GDPR compliance checklist" +- "All the CSS units, with examples" + +### Effort + +- **Low end:** 40-80 hours +- **High end:** 200+ hours, plus annual maintenance + +### Link earning rate + +High when the topic has natural inbound demand and the asset is genuinely the best version. Lower when 5+ competitor guides already exist. + +### When to invest + +When you can credibly produce something better than the current best (more comprehensive, more current, better organized, better examples, better visuals). When the topic supports your business strategically. + +### When to skip + +When the topic is dominated by an evergreen entrenched guide (Wikipedia-level reference, MDN, NN/g) that you cannot displace. + +--- + +## Category 4: visual / interactive assets + +Infographics, interactive explainers, micro-sites built around a single concept. + +### Examples + +- Interactive timelines +- Animated explainers ("how does HTTPS work") +- Map-based visualizations +- Comparison interactive ("the size of every JavaScript framework") +- Single-purpose explainer micro-sites (e.g., "supply chain visualizer") + +### Effort + +- **Low end:** 40-80 hours (static infographic, simple interactive) +- **High end:** 400+ hours (complex interactive, custom illustration, browser-based simulation) + +### Link earning rate + +High when the visual is genuinely useful and shareable. Often peaks early and decays unless the topic has lasting interest. + +### When to invest + +When visual treatment unlocks something prose cannot show. When the topic has strong visual storytelling potential. When you have design capacity to do it well. + +### When to skip + +When the same value can be delivered as a normal article. Visual treatment is not a substitute for substance; it is a multiplier on substance that already exists. + +--- + +## Category 5: templates and frameworks + +Reusable structures the audience can copy, adapt, and use. + +### Examples + +- Project plan templates +- Notion / Airtable templates with download +- Email outreach templates +- Pitch deck templates +- Resume / CV templates +- Code starter templates (CodeSandbox, Stackblitz, GitHub repos) +- Frameworks ("the SPADE framework for decisions") + +### Effort + +- **Low end:** 8-20 hours per template +- **High end:** 40-80 hours for a polished template suite + +### Link earning rate + +Moderate. Templates earn references in roundups and resource lists. Less likely to earn high-authority editorial links. + +### When to invest + +When the template solves a frequent problem in your audience's work and naturally connects to your product. + +### When to skip + +When the template space is crowded with free, polished alternatives. + +--- + +## Category 6: glossaries and reference indexes + +Comprehensive, well-organized indexes of terms, codes, status messages, error codes, etc. + +### Examples + +- "All HTTP status codes with examples" +- "Glossary of marketing terms" +- "Every accessibility WCAG criterion explained" +- "The full list of CSS pseudo-classes" + +### Effort + +- **Low end:** 40-80 hours +- **High end:** 200+ hours, plus continuous updates + +### Link earning rate + +Moderate to high. Reference assets earn links steadily as authors writing on related topics need a place to link the term. + +### When to invest + +When you have the patience to be exhaustive and the topic supports it. + +### When to skip + +When canonical references already exist and dominate (MDN, W3C, official docs). + +--- + +## Category 7: industry rankings and lists + +Annual or continuous lists ranking companies, products, or trends in a category. + +### Examples + +- "The 100 fastest-growing [category] companies" +- "The 50 best [job role] to follow" +- "[Industry] state-of-the-art software comparison" + +### Effort + +- **Low end:** 60-100 hours +- **High end:** 200+ hours with PR + +### Link earning rate + +Moderate to high. Ranked companies link to the list as a credibility signal. Higher rankings earn more links. + +### When to invest + +When you have the credibility to be the ranker (your audience trusts your judgment in the category). + +### When to skip + +When you would be ranking yourself or competitors with no objectivity. + +--- + +## Category 8: events and community assets + +Conferences, summits, awards, communities you sponsor or run. + +### Examples + +- Industry conference recap and highlight reels +- Annual awards +- Slack / Discord community +- Recurring meetup +- Podcast + +### Effort + +- **High.** Events and communities require continuous investment, not one-time. + +### Link earning rate + +Moderate. Earns links from participants, partners, press coverage. + +### When to invest + +When the audience-building flywheel is part of your strategy and you can sustain investment for 2+ years. + +### When to skip + +When the team cannot commit to sustained investment. + +--- + +## Category 9: opinionated takes and POVs + +Strong, well-argued positions on industry questions. Not lists, not data; arguments. + +### Examples + +- "Why we stopped using [framework]" +- "The case against [common practice]" +- "[Industry standard] is wrong, and here is why" +- Manifestos + +### Effort + +- **Low.** A great POV piece can be 1,500-3,000 words and 10-30 hours. + +### Link earning rate + +Highly variable. A POV that hits a nerve in the industry can earn 50+ links in a week. Most POVs earn nothing. + +### When to invest + +When the author has standing to take the position credibly (track record, role, prior writing). When the POV is genuinely held and well-defended. + +### When to skip + +When the POV is contrarian for the sake of being contrarian. Bad-faith hot takes earn ire and short-term traffic, not durable links. + +--- + +## How to pick + +Score candidates against four dimensions: + +| Dimension | Weight | Score 1-5 | +|---|---|---| +| Strategic fit | 30% | Does it serve a topic cluster you want to own? | +| Defensibility | 25% | Can you build something competitors will not easily match? | +| Effort | 25% | What does it cost to ship and maintain? (Lower effort = higher score) | +| Audience pull | 20% | Will the right people link to it? | + +Build the highest-scoring candidate first. Ship one asset all the way through promotion before starting the next. Two well-promoted assets beat ten orphaned ones. + +--- + +## Promotion plan (a separate but linked task) + +A linkable asset that nobody knows about earns no links. The promotion plan must exist before the build starts. + +Typical promotion plan elements: + +- 5-10 pre-launch outreach contacts (industry voices, friendly press, peer companies who would benefit) +- Coordinated social, email, and content launch +- Explicit "ask" templates for outreach (no link begging; offer the asset as relevant, let the linker decide) +- Follow-up content that references the asset for the next 3-6 months +- Ongoing maintenance plan (annual update for research, evergreen updates for tools) + +Without a promotion plan, even great assets sit unlinked. + +--- + +## Common failure modes + +- **Asset is too thin.** Calling a 600-word article a "definitive guide" earns no respect. +- **Asset is dated.** "2022 industry report" still on the site in 2026. Looks abandoned. +- **No promotion plan.** Built, shipped, never told anyone. +- **Self-serving disguised as research.** Survey questions written to produce a result that flatters your product. +- **Tool that breaks.** Calculator with stale data, validator that misses common cases. Returns negative trust. +- **Asset that offers no follow-up.** Visitor arrives, uses it, leaves. No reason to subscribe, register, or convert. + +--- + +## Rough effort vs durable links matrix + +| Category | Effort | Typical referring domains over asset's life | +|---|---|---| +| Free tool (single-purpose) | 30 hours | 40-200 | +| Free tool (rich) | 200 hours | 100-1,000 | +| Original research (annual) | 100 hours | 50-500 per edition | +| Definitive guide | 80 hours | 30-300 | +| Visual / interactive | 80 hours | 30-200 | +| Templates suite | 40 hours | 10-100 | +| Glossary / reference index | 80 hours | 50-300 | +| Industry ranking (annual) | 100 hours | 50-300 per edition | +| Community / event | 1,000+ hours | 100-1,000 | +| POV piece | 20 hours | 0-200 (high variance) | + +These are rough ranges from typical SaaS and content-led businesses. Industry, audience size, and promotion quality all shift them substantially. diff --git a/skills/seo-offpage/references/outreach-templates.md b/skills/seo-offpage/references/outreach-templates.md new file mode 100644 index 0000000..4db4f4b --- /dev/null +++ b/skills/seo-offpage/references/outreach-templates.md @@ -0,0 +1,213 @@ +# Outreach Templates + +Templates for the most common off-page outreach scenarios. Personalize every send. The templates are scaffolding, not ready-to-fire copy. + +A few rules across all templates: + +- Subject lines under 60 characters +- First line never says "I love your blog" or any variant +- One specific reference to their actual work (not a generic compliment) +- One clear ask +- One reason it benefits them, not you +- Sign with a real name and link to a real profile +- Plain text, no formatting, no images, no tracking pixels + +--- + +## Guest post pitch + +**Subject:** [Topic] for [their site name]? + +Hi [first name], + +I just read your piece on [specific article, published Date] and noticed [specific observation about an angle they did not cover, or a question their piece raised but did not answer]. + +I write about [your topic area] and I think the gap there could become a strong follow-up. Working title: "[Specific working title]." It would cover: + +- [Specific point 1] +- [Specific point 2] +- [Specific point 3] + +I can have a draft to you in two weeks. Recent samples of my writing: +- [URL 1] +- [URL 2] + +If this is not a fit, no worries. Let me know either way. + +Thanks, +[Name] +[Title and where you write] + +--- + +## Expert quote / source pitch + +**Subject:** Expert source on [topic] for your [piece type] + +Hi [first name], + +I saw your request for sources on [topic] via [HARO / Twitter / their site]. + +Quick credentials: [one sentence on why you're qualified - title, years, specific work]. Happy to provide a quote, full interview, or background on: + +- [Specific angle 1] +- [Specific angle 2] +- [Specific angle 3] + +Available for a quick reply via email today, or a call this week. + +[Name] +[Title] +[Profile / portfolio link] + +--- + +## Broken link outreach + +**Subject:** Broken link on your [page topic] page + +Hi [first name], + +I was reading your [page name] page (great resource) and noticed the link to [specific old URL] is broken - the destination returns a 404. + +I run [your site] and we have a piece on the same topic that might be a relevant replacement: [your URL]. It covers [specific overlap with what the broken link was for]. + +No pressure either way. Just wanted to flag the broken link. + +[Name] + +--- + +## Podcast pitch + +**Subject:** [Specific topic angle] for [show name]? + +Hi [first name], + +I have been listening to [show name] for [time period]. The recent episode with [guest name] on [topic] resonated because [specific reason]. + +I would love to come on and talk about [specific topic angle]. Why this is a fit for your audience: + +- [Specific angle 1] +- [Specific angle 2] +- [What I bring that other guests have not covered] + +Past appearances: +- [Show name] - [topic] - [link] +- [Show name] - [topic] - [link] + +If the topic resonates, I can send a one-page brief with sample questions. + +[Name] +[Title] +[Headshot / bio link] + +--- + +## Resource page link request + +**Subject:** Resource for your [page topic] roundup + +Hi [first name], + +Your [page name] page is one of the better roundups I have seen on [topic]. I noticed it includes [example resource they list]. + +I run [site] and recently published [your URL], which covers [specific angle]. A few reasons it might earn a spot in the list: + +- [Differentiator 1: e.g., original data, more detail, recently updated] +- [Differentiator 2] + +If it is a fit, I would be grateful for the inclusion. If not, completely understood. + +[Name] + +--- + +## Linkable asset announcement + +**Subject:** New [asset type] on [topic] + +Hi [first name], + +We just published [asset type, e.g., "an interactive calculator", "a 50-source benchmark study", "a free template"] on [topic]: [URL]. + +The reason I am sending it your way: [specific reason this person or publication would care - their audience overlap, a stated interest, a recent piece they wrote]. + +Three things that make it different from existing resources: +1. [Specific differentiator] +2. [Specific differentiator] +3. [Specific differentiator] + +If it is useful for your readers, I would love a mention. Either way, I would value your read of it. + +[Name] + +--- + +## Citation / mention reclamation + +When your brand is mentioned online but not linked to. + +**Subject:** Quick note on the [piece] you published + +Hi [first name], + +Thanks for mentioning [your brand] in your [piece title, with link]. Genuinely appreciated. + +Quick request: would you be open to linking the mention back to [your URL]? Helps your readers find us, and helps us track the reach of the piece. + +No worries if it is not your editorial standard to add links retroactively. + +Thanks, +[Name] + +--- + +## Partnership pitch (low-key) + +**Subject:** [Brand] x [their brand]? + +Hi [first name], + +I run [your brand]. We share an audience with [their brand] - both serving [audience description]. + +A few low-effort ways we could collaborate: + +1. [Specific idea: e.g., cross-promote in newsletters, swap quotes for content, co-host a webinar] +2. [Specific idea] +3. [Specific idea] + +If any resonate, I would love a 20-minute call to figure out the simplest version we could ship in 30 days. + +[Name] +[Title] +[Site] + +--- + +## Universal don'ts + +- Do not start with "Hope you are doing well." +- Do not call yourself a "fellow [profession]" unless you actually know them. +- Do not say "I'll keep this brief" and then write 600 words. +- Do not attach files in cold outreach. +- Do not follow up more than twice. Three+ follow-ups damage reputation. +- Do not use subject lines like "Quick question" or "Re: [topic]" if it is not actually a reply. +- Do not include phrases like "value-add," "synergy," or "leverage." +- Do not pitch yourself as the expert in their field. They are. + +--- + +## Personalization checklist + +Before sending any outreach: + +- [ ] Used their first name correctly (spelled right) +- [ ] Referenced specific recent work of theirs (not from 5 years ago) +- [ ] Stated the ask clearly in the first 3 lines +- [ ] Gave them a reason to say yes that benefits them +- [ ] Plain text, no HTML, no images, no tracking pixel +- [ ] Subject line under 60 characters and not deceptive +- [ ] Signature includes real credentials and a way to verify the sender + +If any are missing, do not send. diff --git a/skills/seo-onpage/SKILL.md b/skills/seo-onpage/SKILL.md new file mode 100644 index 0000000..ae226fe --- /dev/null +++ b/skills/seo-onpage/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-onpage +description: "Run a comprehensive on-page SEO audit or optimization pass covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, URL hygiene, and on-page schema. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review header structure, check internal linking, improve a single URL's search performance, or write SEO-friendly copy. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization, optimize this page, SEO this page. Also triggers for any single-page review where ranking, click-through, or relevance signal quality is the goal, even if the user does not say 'SEO' explicitly." +category: seo-foundation +catalog_summary: "Single-page audits and optimization across 8 dimensions" +display_order: 1 +--- + +# On-Page SEO + +Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site. + +--- + +## When to use + +- Auditing or optimizing a single page (homepage, product page, article, landing page) +- Writing or reviewing title tags and meta descriptions +- Fixing header structure or content hierarchy +- Reviewing internal links from or to a page +- Improving a page's CTR from search results + +## When NOT to use + +- Site-wide crawl, indexing, or speed issues (use `seo-technical`) +- Keyword research or intent mapping (use `seo-keyword`) +- Competitor SERP analysis (use `seo-competitor`) +- Auditing many pages at once for prune/merge decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- The page URL or the draft content if pre-launch +- The primary target query (one phrase the page should rank for) +- The page's role in the site (commercial, informational, navigational) + +If the target query is unknown, run `seo-keyword` first or ask the user to name one. + +--- + +## The framework: 8 dimensions + +A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix. + +### 1. Title tag +- One unique title per URL across the site +- Roughly 50 to 60 characters (longer gets truncated in SERPs) +- Primary query near the front +- Brand at the end if it earns inclusion +- Distinct from the H1 (often very similar, but should not be identical word-for-word) + +### 2. Meta description +- One unique description per URL +- Roughly 150 to 160 characters +- Restates the value proposition, not the title +- Includes a soft CTA where natural +- Treats the description as ad copy that earns the click + +### 3. Header structure +- Exactly one H1 per page +- H1 contains or paraphrases the primary query +- H2 sections cover the major sub-topics +- H3+ used only when an H2 has genuine sub-points +- No skipped levels (no H2 followed by H4) +- Headers describe sections accurately enough that a reader could navigate by them alone + +### 4. Body content +- Opens with the primary user intent answered in the first paragraph +- Covers the topic comprehensively (define your competition's depth, then match or exceed it) +- Includes related entities and supporting concepts naturally +- Avoids keyword stuffing (write for the reader, not the bot) +- Reading level matches the audience (run a readability check) +- Paragraphs short enough to scan on mobile (3 to 5 lines) + +### 5. Internal links +- At least 2 to 3 outbound internal links to closely related pages +- At least 2 to 3 inbound internal links from related pages +- Anchor text is descriptive, not "click here" or "learn more" +- Links to canonical URLs, not redirects +- No broken internal links + +### 6. Images and media +- Every meaningful image has descriptive alt text (skip alt for purely decorative images) +- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg") +- Modern format used where supported (WebP, AVIF) +- Lazy loading on below-the-fold images +- Width and height attributes set to prevent layout shift + +### 7. URL slug +- Lowercase, hyphen-separated +- Includes the primary query naturally (no stuffing) +- Short (under 60 characters where possible) +- No dates unless the page is genuinely time-bound +- No session IDs, tracking parameters, or random hashes +- Matches the site's URL pattern conventions + +### 8. On-page schema +- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.) +- Required properties filled (review Schema.org docs for the type) +- Validates in Google's Rich Results Test or equivalent +- Matches what is visible on the page (do not lie to crawlers) +- Author and publisher schema linked correctly for content pages + +--- + +## Workflow + +1. **Confirm the target query.** If unclear, ask. Do not optimize without one. +2. **Render the page.** View it as a user would. Read the content top to bottom. +3. **View the rendered HTML.** Inspect the actual served markup, not just the visual page. Check `<title>`, `<meta>`, headers, and schema in the source. +4. **Run the 8-dimension framework.** Score each, note specific fixes. +5. **Prioritize.** Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish). +6. **Write the report.** Use the template in [`references/audit-template.md`](references/audit-template.md). +7. **Offer to draft fixes.** If the user wants, draft the new title, meta, headers, or copy directly. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Make it more SEO."** Vague. Ask for the target query and what's broken first. +- **"Add the keyword 5 times in the body."** Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead. +- **Optimizing a page that is not crawlable or indexable.** Check `seo-technical` first. No on-page work helps a noindexed page. +- **Optimizing a page with no clear user intent.** A page that does not serve a real query will not rank no matter how well-tagged it is. +- **Targeting the same query as another page on the site.** This is cannibalization. Use `seo-content-audit` to decide which page should rank. + +--- + +## Output format + +Default output is a markdown audit at `seo-audit-[page-slug].md` in the project root. Structure: + +1. Page summary (URL, target query, role) +2. Score across 8 dimensions +3. Critical fixes +4. Important fixes +5. Nice-to-have polish +6. Drafted replacements (if requested) + +Keep audits under 1500 words. If a page needs more detail, link to deeper appendices. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable audit template, copy and use. +- [`references/onpage-checklist.md`](references/onpage-checklist.md) - Quick-reference checklist for the 8 dimensions. +- [`references/title-and-meta-patterns.md`](references/title-and-meta-patterns.md) - Patterns for writing strong titles and meta descriptions. diff --git a/skills/seo-onpage/references/audit-template.md b/skills/seo-onpage/references/audit-template.md new file mode 100644 index 0000000..ab15d58 --- /dev/null +++ b/skills/seo-onpage/references/audit-template.md @@ -0,0 +1,112 @@ +# On-Page SEO Audit: [Page URL] + +**Target query:** [The primary phrase this page should rank for] +**Page role:** [Commercial / Informational / Navigational] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] + +--- + +## Summary + +[2 to 3 sentence overview. What's working, what's broken, what to fix first.] + +**Overall score:** [Pass / Needs work / Fail] + +| Dimension | Score | One-line note | +|---|---|---| +| Title tag | | | +| Meta description | | | +| Header structure | | | +| Body content | | | +| Internal links | | | +| Images and media | | | +| URL slug | | | +| On-page schema | | | + +--- + +## Critical fixes + +[Things that are broken, missing, or actively hurting the page.] + +### 1. [Fix name] +- **Current:** [What it is now] +- **Problem:** [Why it's broken] +- **Fix:** [Specific replacement] + +### 2. [Fix name] +- **Current:** +- **Problem:** +- **Fix:** + +--- + +## Important fixes + +[Things that are suboptimal but not broken.] + +### 1. [Fix name] +- **Current:** +- **Problem:** +- **Fix:** + +--- + +## Nice-to-have polish + +[Things that would lift the page from good to great.] + +- [Item] +- [Item] + +--- + +## Drafted replacements + +### Title tag +> **Current:** [exact current title] +> **Proposed:** [exact proposed title, with character count] + +### Meta description +> **Current:** [exact current meta] +> **Proposed:** [exact proposed meta, with character count] + +### H1 +> **Current:** [exact current H1] +> **Proposed:** [exact proposed H1] + +### Header outline +``` +H1: [proposed H1] + H2: [proposed section title] + H3: [if needed] + H2: [proposed section title] + H2: [proposed section title] +``` + +### URL (only if changing) +> **Current:** [current URL] +> **Proposed:** [proposed URL] +> **Redirect required:** Yes / No + +--- + +## Implementation notes + +[Any stack-specific considerations, deploy gotchas, or order-of-operations notes.] + +- [Note] +- [Note] + +--- + +## Verify after deploy + +- [ ] Rendered title in SERP preview tool matches proposed +- [ ] Rendered meta description matches proposed +- [ ] H1 visible and matches proposed +- [ ] Schema validates in Rich Results Test +- [ ] Internal links resolve, no broken anchors +- [ ] Images load with correct alt text +- [ ] If URL changed: 301 redirect in place, old URL no longer in sitemap diff --git a/skills/seo-onpage/references/onpage-checklist.md b/skills/seo-onpage/references/onpage-checklist.md new file mode 100644 index 0000000..283cf3e --- /dev/null +++ b/skills/seo-onpage/references/onpage-checklist.md @@ -0,0 +1,90 @@ +# On-Page SEO Checklist + +A condensed checklist for the 8 dimensions. Use as a pre-publish gate or a quick audit pass. + +--- + +## Title tag + +- [ ] Unique across the site +- [ ] 50 to 60 characters +- [ ] Primary query near the front +- [ ] Brand at end (only if it earns inclusion) +- [ ] Not identical to H1 +- [ ] Reads as a compelling search snippet, not a list of keywords + +## Meta description + +- [ ] Unique across the site +- [ ] 150 to 160 characters +- [ ] Restates value, does not repeat title verbatim +- [ ] Includes a soft CTA where natural +- [ ] No keyword stuffing +- [ ] Treats it as ad copy + +## Header structure + +- [ ] Exactly one H1 +- [ ] H1 contains or paraphrases primary query +- [ ] H2s cover the major sub-topics +- [ ] No skipped levels (H2 to H4 with no H3) +- [ ] Headers describe the section accurately +- [ ] A reader could navigate by headers alone + +## Body content + +- [ ] First paragraph answers the primary user intent directly +- [ ] Topical depth matches or exceeds top-ranking competitors +- [ ] Related entities and concepts appear naturally +- [ ] No keyword stuffing +- [ ] Reading level matches the audience +- [ ] Paragraphs are mobile-scannable (3 to 5 lines) +- [ ] Includes original perspective or proprietary data where possible + +## Internal links + +- [ ] At least 2 to 3 outbound internal links to related pages +- [ ] At least 2 to 3 inbound internal links from related pages +- [ ] Anchor text is descriptive +- [ ] Links to canonical URLs (no redirects) +- [ ] No broken internal links + +## Images and media + +- [ ] Every meaningful image has descriptive alt text +- [ ] Decorative images use empty alt (`alt=""`) +- [ ] File names are descriptive +- [ ] Modern format used (WebP or AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] Width and height attributes set +- [ ] Captions where they aid comprehension + +## URL slug + +- [ ] Lowercase, hyphen-separated +- [ ] Includes primary query naturally +- [ ] Under 60 characters where possible +- [ ] No dates unless time-bound +- [ ] No tracking parameters +- [ ] Matches site URL conventions + +## On-page schema + +- [ ] Appropriate Schema.org type +- [ ] Required properties filled +- [ ] Validates in Rich Results Test +- [ ] Matches what is visible on the page +- [ ] Author and publisher schema linked for content pages +- [ ] BreadcrumbList schema for nested pages + +--- + +## Quick wins (fastest to implement, biggest typical impact) + +1. Rewrite title tag for CTR +2. Rewrite meta description for CTR +3. Fix any missing or duplicate H1 +4. Add 2 to 3 internal links from existing related pages +5. Add alt text to images that lack it + +If a page is underperforming and you only have 30 minutes, run those five. diff --git a/skills/seo-onpage/references/title-and-meta-patterns.md b/skills/seo-onpage/references/title-and-meta-patterns.md new file mode 100644 index 0000000..71d1dd1 --- /dev/null +++ b/skills/seo-onpage/references/title-and-meta-patterns.md @@ -0,0 +1,306 @@ +# Title and Meta Patterns + +Patterns for writing strong title tags and meta descriptions. The title tag and meta description are the two most-edited and most-impactful elements in on-page SEO. They are also the two most often left as defaults. + +--- + +## Title tag patterns + +### The job of the title tag + +- Tell Google what the page is about (ranking signal) +- Tell the human what the page is about (CTR signal) +- Distinguish from other pages on the same site (uniqueness signal) +- Earn the click against 9 other titles in the SERP + +A title that does all four wins on rankings AND clicks. A title that does only the first ranks but earns no clicks. A title that does only the last earns clicks but ranks badly. + +### Length + +- 50-60 characters is the safe range for most desktop and mobile SERPs. +- Longer titles get truncated (Google appends "..."). +- Truncation is not catastrophic if the most important words are in the first 50 characters. + +### Character priority + +The most important word (typically the primary query target) goes near the front. Secondary words and brand go at the end. + +``` +[Primary query target] | [Modifier or value prop] | [Brand] +``` + +Examples: + +| Bad | Better | +|---|---| +| "Welcome to Acme - your trusted partner in widgets since 1995" | "Widgets for industrial use - Acme" | +| "Acme Inc. - Best widgets - Buy online" | "Industrial widgets - free shipping - Acme" | +| "About us" | "About Acme - 25 years building industrial widgets" | + +### Patterns by page type + +#### Homepage + +``` +[Brand]: [One-line value prop] +``` + +Examples: +- "Notion: the all-in-one workspace for your notes and tasks" +- "Linear: built for modern software teams" +- "Acme Hardware: industrial widgets for builders" + +#### Category page + +``` +[Category name] - [Modifier or differentiator] | [Brand] +``` + +Examples: +- "Industrial widgets - in stock, free shipping | Acme" +- "Project management software for engineers | Linear" +- "Recipes by region - 1,000+ tested recipes | RecipeCo" + +#### Product / detail page + +``` +[Product name] - [Key benefit or spec] | [Brand] +``` + +Examples: +- "10mm steel widget - 50 lb capacity | Acme" +- "Linear Free - up to 10 users, unlimited issues | Linear" +- "Mediterranean lentil soup recipe | RecipeCo" + +#### Article / blog post + +``` +[Headline that promises value] - [Brand] +``` + +Examples: +- "How to choose an industrial widget supplier - Acme" +- "Linear vs Jira: 5 differences that actually matter - Linear" +- "Why your meta descriptions are getting rewritten - Search Engine Journal" + +The blog title is usually the H1 + brand. If the H1 is long, shorten for the title. + +#### Comparison / vs page + +``` +[Brand A] vs [Brand B]: [Differentiating angle] | [Your brand] +``` + +Examples: +- "Linear vs Jira: speed, opinions, and team size | Linear" +- "MongoDB vs PostgreSQL: when to pick which | Engineering Blog" + +#### Pricing page + +``` +[Brand] pricing - [What is included] | [Brand] +``` + +Examples: +- "Linear pricing - free forever for small teams | Linear" +- "Pricing - simple, transparent, no surprises | Acme" + +#### Geographic / location page + +``` +[Service] in [City], [State] | [Brand] +``` + +Examples: +- "Plumbing services in Austin, TX | Smith Plumbing" +- "Coworking in Brooklyn - day passes and memberships | WorkSpace" + +--- + +## Title rules and anti-patterns + +### Do + +- Put the primary query near the front +- Include brand at the end +- Use a separator that the SERP renders cleanly (`|`, `-`, `:`) +- Be specific (numbers, modifiers, segments earn attention) +- Match the H1 in spirit, not word-for-word + +### Do not + +- Repeat the primary query multiple times ("Widgets, industrial widgets, buy widgets - Widgets.com") +- Start with the brand on every page (homepage is the exception) +- Use ALL CAPS for emphasis +- Use clickbait phrasing that mismatches the page content +- Pad with filler words ("Welcome to," "Find the best," "Looking for") +- Append "Home" / "Default" / "Untitled" +- Leave it as the CMS default + +--- + +## Meta description patterns + +### The job of the meta description + +- Earn the click in the SERP +- Set expectations for what the page delivers +- Reinforce the primary query (Google bolds matched terms) + +The meta description is **not** a ranking signal directly. It is a CTR signal, which feeds back into ranking via behavioral signals. + +### Length + +- 140-160 characters. Longer gets truncated on most devices. +- Mobile truncates earlier than desktop. Front-load the value. + +### Structure + +Three moves in 1-3 sentences: + +1. **Promise the value.** What does the reader get if they click? +2. **Justify it.** Why is this credible? (Numbers, recency, specificity, authority.) +3. **Cue the action.** What should they expect to do or learn? + +Not every meta description does all three. The strongest do. + +### Examples + +| Bad | Better | +|---|---| +| "Welcome to our blog where we write about widgets." | "How to pick the right industrial widget for your project. 10 specs that matter, with a comparison chart." | +| "Acme Inc. is a leading provider of widgets and other products." | "Industrial widgets in 50+ sizes. Free shipping over $100. Same-day dispatch from Austin, TX." | +| "Click here to learn more about our pricing." | "Linear pricing: free forever for teams up to 10. Pro is $8/user/month. No setup fee. See plans and limits." | + +--- + +## Meta description patterns by page type + +### Homepage + +``` +[What the brand does, one sentence]. [The audience or use case]. [The differentiator or social proof]. +``` + +Example: "Modern issue tracking for software teams. Built for speed. Used by 5,000+ teams from startups to enterprise." + +### Category page + +``` +[What the category contains]. [The selection or differentiator]. [Trust or shipping signal]. +``` + +Example: "Industrial widgets in 50+ sizes from 10mm to 200mm. Free shipping over $100. In stock and ready to ship from Austin." + +### Product / detail page + +``` +[Product, with key spec]. [Use case]. [Trust signal or guarantee]. +``` + +Example: "10mm steel widget rated to 50 lb. Built for industrial assembly lines. 5-year warranty, free returns." + +### Article / blog post + +``` +[The promise of the article in one sentence]. [The substance or evidence]. [Optional: who it is for]. +``` + +Example: "How to choose between Linear and Jira: 5 specific differences in workflow, speed, and pricing. With screenshots and benchmarks. For engineering managers comparing the two." + +### Pricing page + +``` +[The headline pricing]. [What is included]. [Anti-friction language]. +``` + +Example: "Linear is free forever for teams up to 10. Pro plan starts at $8/user/month. No setup fee, cancel anytime." + +--- + +## Meta description rules + +### Do + +- Front-load the value +- Use the primary query naturally (Google bolds it) +- Include numbers, specifics, and proof points +- Match the page's actual content +- Write for humans (it is a sales line, not a ranking line) + +### Do not + +- Pad with marketing-speak ("revolutionary," "industry-leading") +- Repeat the title verbatim +- End mid-sentence +- Stuff keywords (Google will rewrite the description if it looks unnatural) +- Leave the CMS default +- Use the same description on multiple pages + +--- + +## When Google rewrites your meta description + +Google rewrites meta descriptions when it thinks its rewrite will earn more clicks. Common triggers: + +- The description does not match the query +- The description is too short, too generic, or stuffed +- The page content has clearly different value from the description +- The page is matched against a long-tail query the description does not address + +To avoid rewrites: + +- Match the description to the page's actual content +- Make sure the primary query appears naturally in the description +- Keep the description specific and current + +If Google rewrites your description and the rewrite is wrong (low CTR, misleading), tighten the description and consider adding `name="description"` plus alternative phrasings via `<meta property="og:description">` for parity. + +--- + +## CTR optimization tips (beyond pattern) + +- **Numbers earn attention.** "5 ways," "100+ examples," "in 10 minutes." +- **Year in title for evergreen-but-current content.** "(2026)" earns clicks in fast-moving categories. Update annually. +- **Brackets and parens are click-bait when overused, useful when accurate.** "[Free Template]," "(2026 update)." +- **Question titles work for some intents.** "How do I [task]?" earns clicks for how-to. +- **Comparison titles are click magnets.** "X vs Y: [angle]." +- **Promise-and-deliver framing.** Title promises a specific value; the page delivers it. + +--- + +## Title and description audit shortcut + +For any page, ask: + +1. Does the title contain the primary query in the first 30 characters? +2. Is the title under 60 characters? +3. Is the title unique on the site? +4. Does the meta description promise value, justify it, and read as a human-written sentence? +5. Is the meta description under 160 characters? +6. Has Google rewritten the description? (Check Search Console performance report.) + +If 4 of 6 are "no," the title or description is the highest-leverage fix on the page. + +--- + +## A/B testing titles and descriptions + +For high-traffic pages, A/B test alternates. Tools that support this: native CMS tools, edge workers, dedicated SEO testing platforms. + +Test one variable at a time (title length, vs comparison hook vs question form, etc.). Run for 2-4 weeks per variant. Measure CTR and downstream conversion, not just rank position. + +--- + +## Snippet appearance is not just title and description + +What the SERP shows can include: + +- The title and description (this guide) +- Sitelinks (Google-auto, can be encouraged via clean IA) +- Rich results from schema (recipe, FAQ, product, review) +- Breadcrumbs (improves CTR, requires breadcrumb schema) +- Author and date (article schema) +- Featured snippets (a separate optimization layer) + +Title and description are the foundation. Schema and sitelinks are leverage on top. diff --git a/skills/seo-rank-tracking/SKILL.md b/skills/seo-rank-tracking/SKILL.md new file mode 100644 index 0000000..c1cb198 --- /dev/null +++ b/skills/seo-rank-tracking/SKILL.md @@ -0,0 +1,250 @@ +--- +name: seo-rank-tracking +description: "Set up and run rank tracking using Ahrefs MCP: pick the right keywords to track, segment them by purpose, set baselines, and define alert thresholds. Use this skill when starting a new tracking project, baselining for a campaign, choosing what to monitor, or building a rank reporting cadence. Triggers on rank tracking, keyword tracking, monitor rankings, track positions, what should we track, ranking dashboard, baseline rankings, alert thresholds. Also triggers when a stakeholder wants weekly or monthly ranking visibility." +category: seo-audit-suite +catalog_summary: "Setup, baseline, segmentation, alerting, dashboarding" +display_order: 7 +--- + +# SEO Rank Tracking + +Set up and run an ongoing rank tracking program using Ahrefs MCP data. Stack-agnostic. Produces a tracked keyword set, segmentation, baseline, alert thresholds, and a review cadence. + +--- + +## When to use + +- Starting rank tracking for a new property or section +- Baselining before a campaign, content launch, or major site change +- Deciding what keywords are worth tracking +- Setting up a ranking dashboard for stakeholders +- Establishing alert thresholds for ranking drops +- Reviewing whether the current tracked set is still meaningful + +## When NOT to use + +- Keyword discovery (use `seo-keyword`) +- Competitor keyword analysis (use `seo-keyword-gap-audit`) +- Diagnosing a ranking change that already happened (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) + +--- + +## Required inputs + +- Target property +- Target market and language +- Business priorities (which segments matter) +- Existing ranked keywords (Ahrefs Site Explorer) +- Stakeholder reporting cadence (weekly, monthly, quarterly) +- Confirmation Ahrefs MCP and Rank Tracker access + +--- + +## The framework: tracking taxonomy + +A good tracked keyword set has structure. Random keyword lists produce noisy dashboards. Segmented keyword sets produce signal. + +Group every tracked keyword into one of four buckets. + +### Bucket 1: Brand keywords + +Queries containing the brand name (and major variants and misspellings). + +Why track: + +- Detect brand visibility issues +- Catch competitors bidding on the brand +- Spot reputation problems early + +Volume in this bucket: typically 10-30 keywords for most brands. + +Healthy signal: position 1 for all variants. Anything else is investigate-worthy. + +### Bucket 2: Money keywords + +Queries that drive (or should drive) revenue: high-intent transactional and evaluation-stage queries directly tied to the business model. + +Why track: + +- These are the keywords that pay the bills +- Movement here directly affects revenue +- Stakeholders care most about these + +Volume in this bucket: 30-100 keywords for most properties. More for ecommerce. + +Healthy signal: top 3-5 positions. Watch for position drift in either direction. + +### Bucket 3: Opportunity keywords + +Queries the property is currently ranking on page 2-3 (positions 11-30) with potential to break into top 10. + +Why track: + +- These are the active growth bets +- Movement reflects whether content investment is working +- Quick wins typically come from this bucket + +Volume in this bucket: 50-200 keywords typically. + +Healthy signal: trending toward page 1 over a 90-day window. + +### Bucket 4: Competitor benchmark keywords + +A representative sample of head and torso queries shared with the competitor set, used to track relative position over time. + +Why track: + +- Measure share of voice +- Spot competitor gains in real time +- Provide industry context for movement + +Volume in this bucket: 50-150 keywords. + +Healthy signal: relative position improving or holding within a defined competitive band. + +--- + +## Selection criteria + +### Brand bucket + +- Brand name (exact) +- Brand name + product or service +- Brand name common misspellings +- Brand name + "review", "vs", "alternative" +- Brand-owned product names if relevant + +### Money bucket + +- Top 20 ranked keywords by traffic value (Ahrefs Site Explorer) +- Top transactional queries from Search Console with non-trivial impressions +- Conversion-driving queries identified in analytics +- Strategic head terms from `seo-keyword-gap-audit` output + +Quality over volume. 50 well-chosen money keywords beats 500 noisy ones. + +### Opportunity bucket + +- All keywords currently ranking positions 11-30 with monthly volume above a relevance-appropriate threshold +- Queries with rising impression volume in Search Console +- Output from the keyword gap audit's quick wins list + +Refresh this bucket quarterly. Opportunity is a moving target. + +### Competitor benchmark bucket + +- Keywords where 3+ competitors rank in top 20 +- Mix of head, torso, and informational queries +- Sized to represent the broader category + +This bucket is for relative comparison, not absolute targeting. + +--- + +## Segmentation beyond buckets + +Tag every tracked keyword on additional dimensions for filtering: + +| Tag | Purpose | +| --- | --- | +| Topic or pillar | Group by editorial theme | +| Funnel stage | TOFU, MOFU, BOFU | +| Content type expected | Article, product page, calculator, etc. | +| Page mapped | Which URL is targeting this query | +| Country and language | For multi-market sites | +| Device | Desktop, mobile | +| SERP feature presence | Featured snippet, AI overview, video, etc. | + +Tagging up front pays off when filtering reports later. + +--- + +## Baselines + +Capture the starting state on day one. + +For each keyword, record: + +- Current position +- Current SERP composition (top 10 domains, dominant content type, SERP features present) +- Current click-through rate at that position (from Search Console if available) +- Date of baseline + +Baselines are the reference for measuring future movement. Without one, every dashboard is just current state. + +--- + +## Alert thresholds + +Not every position change deserves attention. Set thresholds that filter noise. + +### Default thresholds + +| Bucket | Alert if | +| --- | --- | +| Brand | Position drops below 1 for any tracked variant | +| Money | Position drops by 5+ places, or out of top 10 | +| Opportunity | Position rises into top 10 (positive alert), or drops past 30 | +| Competitor benchmark | Aggregate share-of-voice changes by 10%+ | + +Adjust thresholds based on volatility of the niche. High-competition spaces need looser thresholds to reduce false alarms. + +### Alert routing + +- Brand alerts: notify SEO lead and brand manager immediately +- Money alerts: notify SEO lead within a daily digest +- Opportunity alerts: weekly summary +- Competitor alerts: monthly summary + +--- + +## Workflow + +1. **Define scope.** Target property, market, language, stakeholders. +2. **Pull starting data.** Existing ranked keywords, Search Console queries, competitor overlap. +3. **Build the tracked set.** 4 buckets, 200-500 total keywords for most properties. +4. **Segment with tags.** Topic, funnel stage, page mapped, etc. +5. **Configure tracking.** Set up Ahrefs Rank Tracker projects with tags and locations. +6. **Capture baseline.** Day-one positions and SERP composition. +7. **Define alert thresholds.** By bucket. Wire to notification system. +8. **Build the dashboard.** See [`references/dashboard-template.md`](references/dashboard-template.md). +9. **Set the cadence.** Weekly review of money + brand. Monthly review of all. Quarterly rebuild of opportunity bucket. +10. **Iterate.** Drop dead keywords. Add new ones. Recalibrate thresholds based on noise. + +--- + +## Failure patterns + +- **Tracking too many keywords.** A 5,000-keyword tracker is unreadable. Pick fewer, watch closer. +- **Tracking too few.** A 30-keyword tracker misses the picture. Most properties need 200-500. +- **No segmentation.** Untagged tracked keywords produce dashboards that cannot be filtered. +- **No baseline.** Without day-one snapshots, "did the campaign work" becomes unanswerable. +- **Alert fatigue.** Loose thresholds produce too many alerts. Stakeholders stop reading. Tighten. +- **Set and forget.** Tracked keyword sets need quarterly review. Opportunity moves. Money keywords shift. +- **Conflating position with traffic.** A position-1 keyword with no clicks is worse than a position-5 keyword with steady traffic. Layer in CTR and clicks data. +- **Single-device tracking on a mobile-dominant business.** Track the device that matches the audience. +- **Tracking aggregate position only.** Aggregate position averages can hide important movement in specific buckets. Always show by bucket. +- **Reporting absolute position without context.** "We are position 4" means nothing. "Up from position 11 over 60 days" means something. + +--- + +## Output format + +A rank tracking setup document with: + +1. **Tracking charter.** Property, scope, stakeholders, cadence. +2. **Tracked keyword set.** All keywords with bucket and tag assignments. +3. **Baseline snapshot.** Position, SERP composition, CTR per keyword. +4. **Alert configuration.** Thresholds by bucket, routing. +5. **Dashboard layout.** What charts, what filters, what is visible. +6. **Review cadence.** Weekly, monthly, quarterly responsibilities. +7. **Methodology notes.** Country and device settings, refresh frequency, data caveats. + +Plus a recurring rank report at the chosen cadence (typically weekly or monthly). + +--- + +## Reference files + +- [`references/dashboard-template.md`](references/dashboard-template.md) - Template for the rank tracking dashboard layout, including the recurring report structure for weekly and monthly cadences. diff --git a/skills/seo-rank-tracking/references/dashboard-template.md b/skills/seo-rank-tracking/references/dashboard-template.md new file mode 100644 index 0000000..f3ec228 --- /dev/null +++ b/skills/seo-rank-tracking/references/dashboard-template.md @@ -0,0 +1,273 @@ +# Rank tracking dashboard template + +A template for the rank tracking dashboard and the recurring weekly and monthly rank reports. + +--- + +## Dashboard layout principle + +The dashboard should answer three questions in order: + +1. **Are we okay?** (brand and money buckets) +2. **Are we growing?** (opportunity bucket) +3. **How do we compare?** (competitor benchmark bucket) + +Anything that does not serve those three questions is clutter. + +--- + +## Section 1: Brand health (top of dashboard) + +Single panel. Status indicator. Should be glanceable. + +Display: + +- Position 1 status across all brand variants (count: e.g., "27 of 30 variants at position 1") +- Any brand variant not at position 1, listed below the status + +Alert color coding: + +- Green: all brand variants at position 1 +- Yellow: 1-3 variants below position 1 +- Red: 4+ variants below position 1, or any branded query showing competitor in top 3 + +--- + +## Section 2: Money keyword health + +The keystone section. Show: + +### Headline metric + +- Average position across all money keywords (current vs 30 days ago vs 90 days ago) +- Count of money keywords in top 3, top 10, top 20, beyond + +### Movement table + +Top 10 movers (positive and negative) over the chosen window: + +| Keyword | Bucket | Current position | Change | Page mapped | +| --- | --- | --- | --- | --- | +| [keyword] | Money | 4 | +6 | /products/[slug] | + +### Distribution chart + +Stacked bar showing how many money keywords are at each position band: + +- Top 3 +- Positions 4-10 +- Positions 11-20 +- Positions 21-50 +- Beyond 50 or unranked + +Track this distribution over time. Improving SEO shifts the distribution upward. + +--- + +## Section 3: Opportunity progress + +The growth section. + +### Headline metric + +- Count of opportunity keywords that broke into top 10 over the chosen window +- Count that fell out of opportunity range (past 30 or to top 10) +- Net opportunity bucket size (with quarterly refresh) + +### Top breakthroughs + +Keywords that crossed from positions 11-30 into top 10: + +| Keyword | Previous position | Current position | Page mapped | Likely cause | +| --- | --- | --- | --- | --- | +| [keyword] | 14 | 7 | /guides/[slug] | Refresh shipped 30 days ago | + +### Top regressions + +Keywords moving the wrong way: + +| Keyword | Previous position | Current position | Page mapped | Likely cause | +| --- | --- | --- | --- | --- | + +--- + +## Section 4: Competitor benchmark + +### Share of voice + +Aggregate position-weighted share of voice across the benchmark keyword set: + +| Property | SOV (current) | SOV (90 days ago) | Change | +| --- | --- | --- | --- | +| [Target] | 18% | 14% | +4 | +| [Competitor A] | 22% | 23% | -1 | +| [Competitor B] | 15% | 16% | -1 | +| [Competitor C] | 12% | 10% | +2 | + +### Head-to-head + +For top 20 strategic head terms, show position for target and each competitor side by side. + +--- + +## Section 5: SERP feature awareness + +Dashboard should call attention to SERP composition changes. + +Track: + +- Featured snippets owned by target (count, change) +- AI overviews appearing on target's tracked queries (count, change) +- Featured snippets owned by competitors on tracked queries +- New SERP feature types appearing (video carousels, image packs, etc.) + +A position-1 ranking that loses its featured snippet can lose 30%+ clicks while position stays the same. + +--- + +## Section 6: Filters + +The dashboard must be filterable by: + +- Bucket (brand, money, opportunity, benchmark) +- Topic or pillar tag +- Funnel stage tag +- Country and language +- Device +- Page mapped (URL) + +Filters let stakeholders drill from "the dashboard" to "my section". + +--- + +## Weekly report template + +The weekly report is for the SEO team and immediate stakeholders. + +``` +# Weekly rank report: [property] +**Week of:** [date range] +**Prepared:** [date] + +## Brand health + +[Green/Yellow/Red indicator] +[1-2 sentences. Anything not at position 1.] + +## Money keyword movement + +- Average position: [N] (vs [N] last week, [N] 90 days ago) +- Top 3 count: [N] (vs [N] last week) +- Top 10 count: [N] (vs [N] last week) + +### Notable gainers + +| Keyword | Previous | Current | Change | +| --- | --- | --- | --- | + +### Notable decliners + +| Keyword | Previous | Current | Change | +| --- | --- | --- | --- | + +## Opportunity progress + +- Breakthroughs to top 10: [N] +- Regressions out of opportunity range: [N] + +## Alerts triggered this week + +| Date | Keyword | Bucket | Alert | Action taken | +| --- | --- | --- | --- | --- | + +## Hypothesis or call-out + +[1-2 sentences on the most interesting movement and what it suggests.] +``` + +Length: 1 page. Readable in 3 minutes. + +--- + +## Monthly report template + +The monthly report is for broader stakeholders. Add narrative. + +``` +# Monthly rank report: [property] +**Month:** [month] +**Prepared:** [date] + +## Headline + +[1 paragraph. State of organic visibility.] + +## Brand and money keywords + +- Brand health: [status, with any concerns] +- Money keyword distribution: [chart description, key shifts] +- Notable wins: [bullet list] +- Notable concerns: [bullet list] + +## Opportunity progress + +- Breakthroughs to top 10 this month: [N] +- Quarterly target progress: [N of target N] +- Top opportunities watched + +## Competitive landscape + +- Share of voice: [target % vs competitor set] +- Notable competitor movement +- New SERP features observed + +## Themes for the month + +[3-5 themes from the data. Each is 1 paragraph.] + +## Recommendations for next month + +[Specific actions with owners and expected outcomes.] + +## Methodology + +- Tracking set: [N] keywords across [N] buckets +- Country: [list] +- Device: [list] +- Last refresh: [date] +- Data caveats: [list] +``` + +Length: 4-8 pages. + +--- + +## Quarterly rebuild + +Every 90 days, audit the tracked set itself. + +### Rebuild checklist + +- [ ] Brand bucket: any new product names, brand variants, or PR-driven query patterns? +- [ ] Money bucket: any keywords no longer aligned with current product or content focus? +- [ ] Money bucket: any new high-value queries identified by analytics or Search Console? +- [ ] Opportunity bucket: rebuild from current page 2-3 rankings; remove keywords that broke into top 10 (move to money) or fell past 30 (drop) +- [ ] Benchmark bucket: still representative of competitive landscape? +- [ ] Tags: any new pillars or topics that need tagging? +- [ ] Alert thresholds: too noisy? too quiet? recalibrate +- [ ] Reporting cadence: still useful at this frequency? + +Document the rebuild in a short changelog so historical comparisons remain interpretable. + +--- + +## Common dashboard pitfalls + +- **Single big number.** "Average position" alone hides bucket-level signal. +- **No trend lines.** Current state without trend is half the picture. +- **No segmentation visible.** A dashboard that cannot be filtered cannot answer follow-up questions. +- **Showing every keyword.** Stakeholders cannot read 500 rows. Show distributions and movers. +- **Hiding SERP features.** Feature changes cause invisible click drops. Always show them. +- **Showing only target, not competitors.** Movement is meaningless without context. +- **Static data.** A rank dashboard updated monthly is too slow for fast-moving niches. Match refresh to volatility. +- **No annotations.** Mark deploy dates, content launches, and known algorithm updates on charts so movement has context. diff --git a/skills/seo-site-health-audit/SKILL.md b/skills/seo-site-health-audit/SKILL.md new file mode 100644 index 0000000..a47c414 --- /dev/null +++ b/skills/seo-site-health-audit/SKILL.md @@ -0,0 +1,184 @@ +--- +name: seo-site-health-audit +description: "Triage technical SEO findings from Ahrefs Site Audit (and similar crawlers) by SEO impact, not just severity. Use this skill when reviewing crawl results, prioritizing technical fixes, scoping a technical SEO sprint, or after running any site-wide crawl. Triggers on site audit results, technical fix list, crawl errors, technical SEO triage, prioritize technical issues, what should we fix first, broken links, redirect chains. Also triggers when a long list of crawler issues is creating decision paralysis." +category: seo-audit-suite +catalog_summary: "Triage Ahrefs Site Audit findings by SEO impact, not severity" +display_order: 6 +--- + +# SEO Site Health Audit + +Triage technical SEO findings from Ahrefs Site Audit (or any equivalent crawler) by impact on rankings and traffic, not by raw issue count or severity label. Stack-agnostic. Produces a prioritized backlog of fixes mapped to business impact. + +--- + +## When to use + +- After running an Ahrefs Site Audit or other site-wide crawl +- Reviewing a long list of technical issues and needing to prioritize +- Scoping a technical SEO sprint +- Pre-launch or post-migration technical verification +- Quarterly technical health check +- When developer time is limited and you must pick the highest-leverage fixes + +## When NOT to use + +- Running the crawl itself (use the crawler tool directly) +- Diagnosing specific traffic drops (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) +- Pure technical strategy or schema design (use `seo-technical`) + +--- + +## Required inputs + +- Crawl results from Ahrefs Site Audit (or equivalent) +- Search Console coverage and Core Web Vitals data +- Property's organic traffic profile (which pages drive traffic) +- Stakeholder time and developer capacity available +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: triage by SEO impact, not severity + +Crawlers label issues "critical", "warning", "notice". These labels are useful but not sufficient. Two issues both labeled "critical" can have wildly different actual impact on the property. + +Triage on three axes. + +### Axis 1: Page-level traffic impact + +Does the issue affect a page that drives meaningful organic traffic, or one that does not? + +A "critical" issue on a tag archive with zero traffic is lower priority than a "warning" on a top-10-traffic landing page. + +Tier the affected URLs: + +- **Tier 1:** Top 10% of pages by organic traffic +- **Tier 2:** Pages that rank but do not yet drive significant traffic (page 2-3 results) +- **Tier 3:** Pages that exist but do not rank meaningfully + +A fix on Tier 1 is worth 10x a fix on Tier 3 in most cases. + +### Axis 2: Mechanism of impact + +Does the issue actually move rankings or traffic? Some "critical" issues are aesthetic or theoretical. + +Categories of real impact: + +| Mechanism | Examples | +| --- | --- | +| Indexability | Accidental noindex, robots.txt blocks, canonical errors, X-Robots-Tag | +| Crawlability | Crawl traps, infinite redirects, 5xx errors, slow server response | +| Renderability | JS errors blocking critical content, blocked resources | +| Core Web Vitals | LCP, INP, CLS in the poor band | +| Structured data | Errors on rich-result-eligible pages (not warnings) | +| Internal link integrity | 404s on internally linked URLs, broken canonicals | +| Hreflang | Errors on multilingual deployments | + +Categories of low or theoretical impact: + +| Type | Why it is lower priority | +| --- | --- | +| Title tag length warnings | Not a ranking factor in itself | +| Meta description length | Not a ranking factor | +| H1 absence on low-traffic pages | Marginal impact | +| Alt text missing on decorative images | Accessibility issue, low SEO impact | +| Schema warnings (not errors) | Often best-practice nudges, not ranking issues | + +Fix the high-mechanism categories first. + +### Axis 3: Effort + +Some issues are 5-minute fixes. Some are multi-sprint projects. + +- **S (small):** Configuration change, single template edit, sitemap regeneration +- **M (medium):** Theme or component change, redirect map work, template-level fixes +- **L (large):** Architecture change, re-platform, framework migration, schema overhaul + +--- + +## The triage matrix + +Combine the three axes into a priority score. + +| Tier | Mechanism | Effort | Priority | +| --- | --- | --- | --- | +| Tier 1 | High mechanism | S | P0 (do this week) | +| Tier 1 | High mechanism | M | P1 (do this sprint) | +| Tier 1 | High mechanism | L | P2 (plan as project) | +| Tier 1 | Low mechanism | S | P3 (batch when convenient) | +| Tier 1 | Low mechanism | M-L | Park unless evidence emerges | +| Tier 2 | High mechanism | S | P1 | +| Tier 2 | High mechanism | M-L | P2 | +| Tier 3 | High mechanism | S | P3 | +| Tier 3 | Anything else | Anything | Park | + +P0-P1 work earns the team's attention. P2 goes on the roadmap. P3 batches into routine maintenance. Park is honest about deprioritization. + +--- + +## Workflow + +1. **Pull the crawl results.** Ahrefs Site Audit + Search Console + Core Web Vitals. +2. **Tier the URLs.** Use organic traffic data. Tag every affected URL as Tier 1, 2, or 3. +3. **Categorize each issue by mechanism.** High or low impact mechanism. +4. **Estimate effort per fix type.** Group similar fixes into one effort estimate. +5. **Apply the triage matrix.** Assign P0-P3 or Park. +6. **Cluster the fixes.** Group fixes that share an effort: one template change can resolve hundreds of issues. +7. **Build the backlog.** P0 first, P1 next, etc. Add fix descriptions, owners, expected impact. +8. **Add measurement.** What metric will confirm the fix worked? Define before shipping. +9. **Hand off.** Output feeds the development backlog and `seo-audit-orchestration`. +10. **Re-crawl after fixes.** Confirm resolution. Update the backlog. + +--- + +## High-leverage clusters worth looking for + +These patterns commonly produce outsized impact when fixed: + +- **Wholesale redirect chain cleanup.** One sitemap update plus internal link updates can resolve thousands of "redirect chain" issues at once. +- **Accidental noindex on a template.** A single line of code change can re-index hundreds or thousands of pages. +- **Sitemap freshness pipeline.** A broken sitemap regeneration job affects every issue that depends on Search Console seeing the right URLs. +- **Canonical inconsistencies on faceted navigation.** A template-level canonical fix can resolve duplicate content issues across an entire ecommerce category tree. +- **Robots.txt restored.** A reverted production robots.txt can recover a sitewide drop in days. +- **Hreflang block fix.** One template change resolves hreflang issues across the whole multilingual site. +- **Image optimization at the asset pipeline.** Fixing the build process resolves thousands of individual asset issues. + +When you spot one of these, prioritize even if individual issues look small. The cluster impact is large. + +--- + +## Failure patterns + +- **Severity worship.** Treating every "critical" label as truly critical. Many are not. Triage by mechanism and traffic impact. +- **Counting issues.** Reporting "we fixed 1,200 issues" without showing traffic or ranking impact wastes engineering credibility. +- **Skipping the tiering.** Fixing 100 Tier-3 issues before 5 Tier-1 issues is busy work. +- **Single-issue fixes.** Most issues come in clusters. Fixing one redirect chain when 800 share the same root cause is the wrong unit of work. +- **No re-crawl.** "Fixed" without verification leaves doubt. Always re-crawl after major fixes. +- **Ignoring Search Console.** Ahrefs sees what its crawler finds. Search Console reflects what Google actually sees and indexes. Use both. +- **Treating Core Web Vitals like a checklist.** CWV is field data, not lab data. Optimize for real-user experience, not synthetic scores. +- **Fixing low-mechanism issues for show.** A clean technical report with no traffic gain helps no one. +- **Not measuring.** Define the metric that proves the fix worked before fixing. + +--- + +## Output format + +A site health triage document with: + +1. **Summary.** Total issues, top 3 fix clusters, expected impact. +2. **URL tiering.** How URLs were classified and counts per tier. +3. **Issue categorization.** Counts by mechanism category, by tier, by priority band. +4. **Prioritized backlog.** P0-P3 ordered. Each item has: issue, affected URLs, fix description, effort, expected impact, owner. +5. **Fix clusters.** Groups of issues that share a fix. Highest leverage at the top. +6. **Measurement plan.** Per fix or cluster, what proves it worked. +7. **Methodology.** Crawler used, date, scope, caveats. + +Length: 5-12 pages plus a backlog spreadsheet. + +--- + +## Reference files + +- [`references/issue-impact-table.md`](references/issue-impact-table.md) - Mapping table of common crawler issues to mechanism impact and typical fix effort, plus the triage matrix in detailed form. diff --git a/skills/seo-site-health-audit/references/issue-impact-table.md b/skills/seo-site-health-audit/references/issue-impact-table.md new file mode 100644 index 0000000..672e1b0 --- /dev/null +++ b/skills/seo-site-health-audit/references/issue-impact-table.md @@ -0,0 +1,190 @@ +# Issue impact table + +A reference table mapping common crawler-reported issues to their actual SEO impact mechanism and typical fix effort. Use it to triage Ahrefs Site Audit (or any equivalent) findings without treating every "critical" label as equally important. + +--- + +## How to use + +For each issue type from the crawler: + +1. Look up the mechanism and effort here. +2. Combine with URL tier (Tier 1 = top 10% by traffic) using the triage matrix. +3. Assign priority band P0-P3 or Park. + +Mechanism tiers: + +- **HIGH:** Direct effect on indexing, rankings, or Core Web Vitals. +- **MEDIUM:** Indirect effect via crawl, equity flow, or user signals. +- **LOW:** Best practice nudge or cosmetic. Real impact is usually marginal. + +--- + +## Indexability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Page returns noindex on indexed URL | HIGH | S | Template fix usually resolves at scale | +| Robots.txt blocks important URLs | HIGH | S | One file edit | +| X-Robots-Tag header set to noindex | HIGH | S-M | Often a CDN or hosting config | +| Canonical points to non-canonical URL | HIGH | M | Often template-level | +| Canonical points to redirect | HIGH | S | Update canonical to final URL | +| Self-canonical missing on important page | MEDIUM | S | Add to template | +| URL not in sitemap but indexed | MEDIUM | S | Regenerate sitemap | +| URL in sitemap but noindexed | HIGH | S | Decide indexability, fix one or the other | + +--- + +## Crawlability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| 5xx errors on URLs | HIGH | M-L | Investigate hosting and app errors | +| 4xx errors on internally linked URLs | HIGH | M | Fix links or add redirects | +| Redirect chain (3+ hops) | MEDIUM | M | Update final destination in links | +| Redirect loop | HIGH | S | Fix immediately | +| Slow time to first byte | MEDIUM | M-L | Hosting, caching, or app changes | +| Crawl trap (infinite parameter combinations) | HIGH | M | Robots disallow patterns or canonical | +| Orphan page (indexed but no internal links) | MEDIUM | S-M | Add internal links or noindex | +| Excessive redirects in sitemap | MEDIUM | S | Update sitemap to final URLs | +| 301 used where 302 intended (or vice versa) | LOW-MEDIUM | S | Audit and fix per case | + +--- + +## Renderability issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Critical content rendered only via JS (with crawler issues) | HIGH | L | Server render, prerender, or hybrid | +| Blocked CSS or JS resources | MEDIUM | S | Allow in robots.txt | +| Excessive client-side dependencies for above-fold content | MEDIUM | M-L | Code splitting and SSR | +| Render mismatch (HTML differs from rendered DOM in important ways) | HIGH | M-L | Investigate framework rendering | + +--- + +## Core Web Vitals (field data) + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| LCP > 4 seconds (poor band) on Tier 1 pages | HIGH | M-L | Image optimization, caching, render path | +| LCP 2.5-4 seconds (needs improvement) | MEDIUM | M | Lower priority but still worth fixing | +| INP > 500ms (poor band) | HIGH | M-L | JS optimization, hydration deferral | +| CLS > 0.25 (poor band) | HIGH | S-M | Reserve space for images, ads, embeds | +| CLS 0.1-0.25 | LOW-MEDIUM | S | Often quick wins | + +CWV thresholds are based on the 75th percentile of real-user data per URL group. + +--- + +## Structured data issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Schema error blocking rich result eligibility | HIGH | S-M | Fix the offending field | +| Schema warning (recommended field missing) | LOW | S | Optional improvement | +| Wrong schema type for content | MEDIUM | S | Replace with correct type | +| Schema markup but content does not match | HIGH | M | Either fix schema or fix content (Google penalizes mismatch) | +| Duplicate schema across multiple types | LOW-MEDIUM | S | Clean up duplicates | + +Pages eligible for rich results (FAQ, How-to, Recipe, Product, etc.) deserve high priority. Schema on pages without rich result eligibility is lower priority. + +--- + +## Internal link integrity + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Internal link to 404 | MEDIUM | S | Update or remove link | +| Internal link to redirect | LOW | S | Update to final URL when batching | +| Internal link with empty anchor | LOW | S | Add descriptive anchor | +| Page receiving zero internal links (orphan) | MEDIUM | S-M | Add links or reassess if page should exist | +| Important page with very few internal links | MEDIUM | S | Identify and add link points | +| Footer or sitewide internal link to broken URL | MEDIUM | S | High visibility, fix quickly | + +--- + +## Hreflang (multilingual sites) + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing return tag (hreflang reciprocity) | HIGH | M | Template fix often resolves at scale | +| Hreflang points to redirected URL | MEDIUM | S | Update to final URL | +| Hreflang points to noindexed URL | HIGH | S | Decide indexability or remove hreflang | +| Hreflang language code malformed | HIGH | S | Use ISO 639-1 + ISO 3166-1 alpha-2 | +| Mixing x-default and specific tags incorrectly | MEDIUM | S | Audit pattern across site | + +Multilingual sites with broken hreflang often see the wrong locale rank in the wrong market. Real ranking impact. + +--- + +## On-page elements + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing title tag | MEDIUM | S | Add via template | +| Duplicate title tag across many pages | MEDIUM | S-M | Template fix or unique-by-default | +| Missing meta description | LOW | S | Affects CTR, not ranking | +| Duplicate meta descriptions | LOW | S | Affects CTR, not ranking | +| Missing H1 on Tier 1 page | MEDIUM | S | Add to template | +| Missing H1 on Tier 3 page | LOW | S | Park unless trivial to fix | +| Multiple H1s | LOW | S | Modern HTML allows; rarely a real issue | +| Title or H1 that does not match content topic | MEDIUM | S | Audit content and update | + +--- + +## Image issues + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Missing alt text on content images | LOW (SEO), HIGH (accessibility) | S | Important for accessibility regardless | +| Missing alt text on decorative images | LOW | S | Use empty alt="" | +| Image weight (large file size) on Tier 1 page | HIGH | M | Asset pipeline fix at scale | +| Image format not modern (no WebP/AVIF) | MEDIUM | M | Pipeline change | +| Image lazy loading missing | MEDIUM | S | Add `loading="lazy"` to off-screen images | +| Hero image lazy loaded | MEDIUM | S | Should be `loading="eager"` for LCP | + +--- + +## Security and trust + +| Issue | Mechanism | Typical effort | Notes | +| --- | --- | --- | --- | +| Mixed content (HTTPS page loading HTTP resources) | MEDIUM | S | Update resource URLs | +| Expired or misconfigured SSL | HIGH | S | Fix immediately | +| HSTS missing | LOW | S | Best practice | +| Internal links use HTTP, page is HTTPS | LOW | S | Update links to relative or HTTPS | + +--- + +## Cluster opportunities + +When you see multiple issues from the same root cause, treat as one fix: + +| Cluster signal | Single fix | +| --- | --- | +| Hundreds of "redirect chain" warnings | Update internal links and sitemap to final URLs | +| Sitewide "missing canonical" | Add canonical to base template | +| Mass "noindex on indexable URL" | Audit template-level meta tag | +| Many "page not in sitemap" | Regenerate sitemap from canonical URL list | +| Many slow LCP pages with same image pattern | Optimize image pipeline once | +| Many hreflang errors with same pattern | Template-level hreflang fix | +| Many H1 issues on archive pages | Theme or template change | + +Always look for clusters before fixing one-off. Cluster fixes are 10-100x more efficient. + +--- + +## Park or skip + +These rarely deserve dedicated work even when flagged: + +- Title tag length warnings (within reason; only fix if truncation visibly hurts CTR on a Tier 1 page) +- Meta description length warnings (same logic) +- "URL contains uppercase" if redirects already handle it +- "URL contains underscore" if URLs are stable and ranking +- Trailing slash inconsistency if redirects handle it +- Schema warnings (not errors) on pages with no rich result eligibility +- HTML validation issues that do not affect rendering or indexing +- Old browser-specific issues (IE-era) + +Park them. Document why. Move on. diff --git a/skills/seo-technical/SKILL.md b/skills/seo-technical/SKILL.md new file mode 100644 index 0000000..ef9c358 --- /dev/null +++ b/skills/seo-technical/SKILL.md @@ -0,0 +1,154 @@ +--- +name: seo-technical +description: "Run a comprehensive technical SEO audit covering crawlability, indexability, rendering, site architecture, structured data, page experience, security, and internationalization. Use this skill whenever the user asks about technical SEO, crawl issues, indexing problems, sitemaps, robots.txt, canonical tags, schema markup, page speed, Core Web Vitals, hreflang, redirects, or site-wide search performance. Triggers on technical SEO, site audit, crawlability, indexability, sitemap, robots.txt, canonical, redirect chain, schema, JSON-LD, Core Web Vitals, page speed, hreflang, mobile usability, HTTPS, security headers, render-blocking, JavaScript SEO. Also triggers when a site has indexing problems, traffic drops, or migration concerns, even if 'technical SEO' is not said explicitly." +category: seo-foundation +catalog_summary: "Crawlability, indexability, rendering, schema, page experience" +display_order: 2 +--- + +# Technical SEO + +Audit and fix the layer beneath the content: how search engines crawl, render, index, and trust a site. Stack-agnostic. + +--- + +## When to use + +- Site-wide audit before or after a migration +- Investigating indexing or ranking drops +- Setting up SEO foundations on a new site +- Auditing Core Web Vitals or page experience signals +- Fixing crawl waste, redirect chains, or canonical issues +- Setting up multilingual or multi-regional sites + +## When NOT to use + +- Single-page on-page optimization (use `seo-onpage`) +- Keyword strategy or content planning (use `seo-keyword`) +- Competitor backlink or SERP analysis (use `seo-competitor`) +- Pure performance optimization without SEO context (use `performance-optimization`) + +--- + +## Required inputs + +- The site URL or staging URL +- Access to (at minimum) view the rendered HTML, robots.txt, and sitemap +- Ideally: search console access, server logs, and a crawler + +If the site is large (10K+ URLs), confirm whether the audit is a full crawl or a sample. + +--- + +## The framework: 6 layers + +Technical SEO has six layers, stacked. A failure in a lower layer breaks everything above it. + +### 1. Crawlability +Can search engines access the URLs? + +- robots.txt does not block important paths +- No accidental `noindex` on indexable pages +- No accidental `disallow` patterns blocking CSS or JS (rendering breaks) +- Sitemap is present, returns 200, and lists canonical URLs only +- Sitemap is referenced in robots.txt +- No infinite spaces (faceted nav generating endless URLs) +- Crawl budget is not wasted on low-value URLs + +### 2. Indexability +Of crawlable URLs, which should be indexed? + +- One canonical URL per piece of content (no duplicates) +- Canonical tags self-reference on canonical pages +- `noindex` on staging, search results, filter pages, thank-you pages, internal admin +- No mixed signals (canonical pointing one way, sitemap another, internal links a third) +- Pagination handled correctly (rel=next/prev is deprecated, but consistent canonicals matter) +- Parameter handling deliberate (UTM, session IDs, sort orders) + +### 3. Rendering +Does the rendered HTML match what crawlers see? + +- Critical content visible without JavaScript (or properly server-rendered) +- For SPAs: confirm Googlebot sees the rendered content (test with the URL Inspection tool) +- No cloaking (showing different content to bots vs users) +- Lazy-loaded content has proper loading attributes +- Hydration errors do not strip content from the rendered DOM + +### 4. Site architecture +Is the site structured for both users and crawlers? + +- Clear URL hierarchy that mirrors site structure +- Important pages reachable in 3 clicks or fewer from the homepage +- Internal linking distributes authority logically +- Breadcrumb navigation present and marked up with schema +- No orphan pages (pages with no internal links) +- No redirect chains (one redirect max) +- No 4xx errors on internally-linked URLs + +### 5. Structured data and signals +Does the site speak crawler language? + +- Schema.org markup on appropriate page types +- JSON-LD format (preferred over microdata) +- Validates in the Rich Results Test +- Organization or LocalBusiness schema on the homepage or about page +- BreadcrumbList schema on nested pages +- Author and publisher schema linked correctly on content pages +- llms.txt present at the root (for AI crawlers, see `seo-aeo-geo`) + +### 6. Page experience and security +Does the site meet the page experience baseline? + +- HTTPS on all pages, no mixed content +- HSTS header set +- Core Web Vitals pass (LCP, INP, CLS within thresholds) +- Mobile-friendly (responsive, no horizontal scroll, tap targets sized correctly) +- No intrusive interstitials on mobile +- Stable URL structure (no random URL changes between deploys) +- 404 pages return 404, not 200 with "page not found" content (soft 404) + +--- + +## Workflow + +1. **Define scope.** Whole site, a subfolder, a migration check, or a specific issue. +2. **Confirm access.** What can you actually see (HTML, robots, sitemap, search console, server logs, staging)? +3. **Crawl.** Use a crawler to enumerate URLs and statuses. Sample if the site is huge. +4. **Run the 6-layer framework.** Score each, note specific issues with example URLs. +5. **Cross-reference.** Search console for what's actually indexed. Compare to sitemap and crawl output. +6. **Prioritize.** Critical (blocks indexing or causes traffic loss), Important (suboptimal), Nice-to-have (polish). +7. **Write the report.** Use the template in [`references/audit-template.md`](references/audit-template.md). + +--- + +## Failure patterns + +- **Optimizing rankings on a page that is `noindex`.** Always check indexability before content work. +- **Adding sitemaps without fixing canonical issues.** A sitemap of duplicate URLs is worse than no sitemap. +- **Blocking crawlers from CSS or JS.** Breaks Google's rendering. Common in over-aggressive robots.txt files. +- **Over-relying on canonical tags.** Canonicals are hints, not directives. Use redirects when content actually moved. +- **Migrating without a redirect map.** Single biggest cause of post-migration traffic loss. +- **Treating Core Web Vitals as the only ranking signal.** Page experience matters but does not override relevance. + +--- + +## Output format + +Default output is a markdown audit at `seo-technical-audit.md`. Structure: + +1. Scope and methodology +2. Executive summary (3 to 5 critical findings) +3. 6-layer score +4. Critical issues (with example URLs) +5. Important issues +6. Nice-to-have polish +7. Implementation roadmap (sequenced) + +For migrations, include a redirect map as a CSV alongside the report. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable technical SEO audit template. +- [`references/migration-checklist.md`](references/migration-checklist.md) - Pre and post-migration checklist (covers the highest-risk scenario). diff --git a/skills/seo-technical/references/audit-template.md b/skills/seo-technical/references/audit-template.md new file mode 100644 index 0000000..a424d3f --- /dev/null +++ b/skills/seo-technical/references/audit-template.md @@ -0,0 +1,321 @@ +# Technical SEO Audit Template + +Fillable template for a technical SEO audit. The audit covers crawlability, indexability, rendering, schema, page experience, and site architecture. + +The output is a stakeholder-readable report plus a prioritized backlog. For migration scenarios specifically, also use `migration-checklist.md`. + +--- + +## Audit metadata + +**Site:** [Domain] +**Pages audited:** [Sample size and selection method] +**Audit date:** [YYYY-MM-DD] +**Auditor:** [Name] +**Tools used:** [Crawler, GSC, log analyzer, Lighthouse, schema validator, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall technical state. +2. The single biggest blocker. +3. The estimated traffic at risk if technical issues persist. +4. The recommended next move. +5. Estimated effort for the top fix. + +> [Summary] + +--- + +## 1. Crawlability + +Can search engines crawl the site? + +### Robots.txt + +- [ ] File exists at `/robots.txt` +- [ ] File is syntactically valid (test in GSC) +- [ ] Critical sections of the site are not accidentally disallowed +- [ ] Specific user agents are not blocked (`Googlebot`, `Bingbot`) +- [ ] Sitemap location is declared (`Sitemap: https://example.com/sitemap.xml`) + +### XML sitemap(s) + +- [ ] Sitemap exists and is reachable +- [ ] Sitemap is referenced in robots.txt +- [ ] Sitemap is submitted in Search Console +- [ ] Sitemap contains only canonical, indexable URLs +- [ ] Sitemap is updated automatically when content changes +- [ ] Sitemap is split if over 50,000 URLs or 50MB +- [ ] `lastmod` reflects the actual last meaningful update (not the build date) + +### Internal linking + +- [ ] No important pages are orphaned (zero internal inlinks) +- [ ] Crawl-discoverable from the homepage within 4 clicks +- [ ] No internal links go to redirected URLs +- [ ] No internal links go to broken URLs (404) +- [ ] Anchor text is descriptive (avoid "click here," "read more") +- [ ] No `nofollow` or `noindex` on important internal pages + +### Crawl budget + +- [ ] Log analysis confirms Googlebot reaches the important sections regularly +- [ ] No crawl traps (calendar pages, infinite faceted nav, session ID parameters) +- [ ] Faceted nav uses `noindex,follow` or controlled parameter handling +- [ ] No duplicate URLs from URL parameter variations (UTMs, tracking, sort orders) +- [ ] Pagination handled with `rel="next"` and `rel="prev"` or paginated URL structure (no infinite scroll for important content) + +--- + +## 2. Indexability + +Can search engines index the site? + +### Index status + +- [ ] GSC "Indexed" count matches expected (production URL count) +- [ ] GSC "Not indexed" reasons are reviewed and addressed +- [ ] "Discovered - currently not indexed" pages are not high-value (or are addressed) +- [ ] "Crawled - currently not indexed" pages are not high-value (or are addressed) + +### Index directives + +- [ ] No `<meta name="robots" content="noindex">` on important pages +- [ ] No `X-Robots-Tag: noindex` HTTP header on important pages +- [ ] Staging or dev environments are noindexed (and not bypassable) +- [ ] Login pages, internal search results, and tag archives are noindex (or otherwise low-priority) + +### Canonicalization + +- [ ] Every page has a `rel="canonical"` tag +- [ ] Self-canonical URLs match the actual URL (no http/https mismatch, no trailing slash mismatch) +- [ ] Cross-canonical references point to indexable, live URLs +- [ ] Pagination uses self-canonicals (not pointing to page 1) +- [ ] No conflicting signals (canonical to URL A, redirect to URL B) + +### Status codes + +- [ ] 200 for live pages +- [ ] 301 for permanently moved pages +- [ ] 302 used only for genuinely temporary redirects +- [ ] 404 for genuinely missing pages (with helpful 404 page) +- [ ] 410 for intentionally removed pages +- [ ] 5xx errors investigated and resolved + +### Redirect chains + +- [ ] No redirect chains over 1 hop (A → B is fine; A → B → C → D is not) +- [ ] No redirect loops +- [ ] HTTPS redirect from HTTP is single-hop +- [ ] Trailing-slash redirect is single-hop + +--- + +## 3. Rendering + +Can search engines render JavaScript-dependent content? + +### Rendering strategy + +- [ ] Critical content is in the initial HTML response (server-rendered or static) +- [ ] If JS-rendered, "fetch as Google" via URL Inspection in GSC shows full content +- [ ] No reliance on user interaction to load primary content (no "click to load article") + +### Specific rendering risks + +- [ ] No JS-rendered title tags or meta descriptions (these often fail to be picked up) +- [ ] No JS-injected canonical tags +- [ ] Lazy-loaded images use native `loading="lazy"` or proper IntersectionObserver implementation +- [ ] Lazy-loaded content above the fold is not lazy-loaded +- [ ] CSS is not blocking critical content rendering + +### JavaScript SEO sanity check + +- [ ] Disable JS in DevTools and reload key pages. Critical content should still appear. +- [ ] Use the URL Inspection tool in GSC and view the rendered HTML. Compare to user-rendered version. + +--- + +## 4. Schema and structured data + +- [ ] Pages have appropriate schema (Article, Product, Organization, BreadcrumbList, FAQ, HowTo, Recipe, etc.) +- [ ] Schema validates in Google's Rich Results Test +- [ ] Schema validates in Schema.org validator +- [ ] No schema violations in GSC enhancement reports +- [ ] BreadcrumbList schema implemented (often-overlooked CTR boost) +- [ ] Organization schema on the homepage +- [ ] WebSite schema with SearchAction (enables sitelinks search box) +- [ ] No schema for content not visible on the page + +--- + +## 5. Page experience + +### Core Web Vitals + +Field data preferred (CrUX, RUM). Lab data is a fallback diagnostic. + +| Metric | Target | Mobile p75 | Desktop p75 | Status | +|---|---|---|---|---| +| LCP | < 2.5s | | | | +| INP | < 200ms | | | | +| CLS | < 0.1 | | | | + +For detailed performance audit, see `performance-optimization` skill. + +### HTTPS + +- [ ] Entire site served over HTTPS +- [ ] No mixed content warnings +- [ ] HSTS header set +- [ ] Certificate valid and not approaching expiry + +### Mobile + +- [ ] Responsive (single URL, single HTML, CSS adapts) +- [ ] Mobile usability passes in GSC +- [ ] No tap targets too close together +- [ ] Viewport meta tag set + +### Safe browsing + +- [ ] No security warnings in GSC +- [ ] No malware or phishing flags + +--- + +## 6. International SEO + +If the site is multilingual or multi-region: + +- [ ] `hreflang` tags present and correct on every locale alternate +- [ ] `hreflang` includes self-reference +- [ ] `x-default` set for language picker fallback +- [ ] Language and region codes follow ISO standards +- [ ] No hreflang errors in GSC International Targeting report +- [ ] URL structure follows a consistent pattern (subdir / subdomain / ccTLD) + +--- + +## 7. Site architecture and URLs + +### URL hygiene + +- [ ] URLs are lowercase +- [ ] URLs use hyphens, not underscores or spaces +- [ ] URLs are short and descriptive +- [ ] No session IDs or tracking parameters in canonical URLs +- [ ] URL structure reflects content hierarchy (category → subcategory → page) + +### Trailing slash + +- [ ] Consistent trailing slash policy (with or without) +- [ ] One version redirects to the other (no duplicates) + +### Subdomains vs subdirectories + +- [ ] Strategic decision documented (subdir typically pools authority better; subdomain better for separate sites) +- [ ] `www` and non-`www` consolidated via 301 + +--- + +## 8. Search Console hygiene + +- [ ] Both `https://www` and `https://` (and `http://` versions) verified as separate properties +- [ ] Domain property verified (the recommended approach) +- [ ] Sitemap submitted and showing "Success" +- [ ] No critical issues in Coverage report +- [ ] No manual actions or security issues +- [ ] Crawl stats reviewed (sudden drops or spikes investigated) + +--- + +## 9. Log file analysis (advanced) + +For larger sites, server logs reveal what crawlers actually do, vs what the site allows. + +- [ ] Top crawled pages match top-priority pages +- [ ] Googlebot does not waste crawl on noindex / parameter / faceted URLs +- [ ] No orphaned pages getting crawler traffic +- [ ] No 5xx errors served to Googlebot + +--- + +## Findings summary + +| Severity | Issue | Pages affected | Recommended fix | Effort | +|---|---|---|---|---| +| P0 (blocking) | | | | | +| P1 (high) | | | | | +| P2 (medium) | | | | | +| P3 (low) | | | | | + +### Severity definitions + +- **P0:** Critical content cannot be crawled or indexed; major technical errors causing exclusion from search. +- **P1:** Significant indexability or rendering issues affecting traffic; broken canonicals; large redirect chains. +- **P2:** Suboptimal but not blocking; missing schema, suboptimal sitemap, partial CWV failures. +- **P3:** Polish; minor inefficiencies, documentation gaps. + +--- + +## Recommendations + +### Now (this week) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Next (this sprint or month) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | +| 2 | | | | | + +### Later (this quarter) + +| # | Recommendation | Owner | Estimated impact | Effort | +|---|---|---|---|---| +| 1 | | | | | + +--- + +## Monitoring after fixes ship + +- [ ] GSC Coverage report rechecked weekly until stable +- [ ] Position tracking for top queries to confirm no regression +- [ ] Log analysis re-run 2-4 weeks after fixes ship +- [ ] CWV field data tracked for affected page templates +- [ ] Set alerts for: 5xx errors, sudden index drops, certificate expiry + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- **Crawl tool config:** [tool, depth, render mode, user agent] +- **Sample selection:** [How URLs were selected for deep review] +- **Field data window:** [Date range] +- **Caveats:** [What this audit did not cover] + +--- + +## Sign-off + +Audit conducted by: [Name, date] +Reviewed with: [Stakeholders] +Implementation owner: [Name] +Re-audit scheduled: [Date] diff --git a/skills/seo-technical/references/migration-checklist.md b/skills/seo-technical/references/migration-checklist.md new file mode 100644 index 0000000..c812907 --- /dev/null +++ b/skills/seo-technical/references/migration-checklist.md @@ -0,0 +1,118 @@ +# Migration Checklist + +A site migration (domain change, platform change, URL restructure, HTTPS move) is the single highest-risk SEO event. Follow this checklist to avoid the typical 30 to 70 percent traffic loss most migrations cause. + +--- + +## Pre-migration (T minus 30 days) + +### Document the current state +- [ ] Crawl the entire current site, save URL list +- [ ] Export top 1000 organic landing pages from search console (last 12 months) +- [ ] Export top 1000 organic queries from search console +- [ ] Note current rankings for the top 50 commercial queries +- [ ] Save current XML sitemap +- [ ] Save current robots.txt +- [ ] Document current schema implementation +- [ ] Screenshot current SERP appearance for top 10 queries + +### Plan the new structure +- [ ] Map every old URL to its new URL (redirect map) +- [ ] Confirm every important URL has a destination (no orphan redirects) +- [ ] Decide on canonical URL structure (trailing slash, www vs non-www, http to https) +- [ ] Plan handling of parameter URLs (UTM, sort, filter) +- [ ] Plan handling of pagination +- [ ] Plan internal linking structure (avoid relying on redirects) + +### Build and stage +- [ ] Set staging environment to `noindex` +- [ ] Block staging from search engines via robots.txt and HTTP auth +- [ ] Build redirect logic for the redirect map +- [ ] Implement the new sitemap +- [ ] Implement schema on all page types +- [ ] Verify Core Web Vitals on staging +- [ ] Test mobile usability on staging +- [ ] Test HTTPS configuration (HSTS, no mixed content) + +--- + +## Migration day + +### Just before cutover +- [ ] Final crawl of the production site (baseline for comparison) +- [ ] Final export of indexed URL list from search console +- [ ] Confirm DNS TTLs lowered if changing hosts (24 to 48 hours prior) +- [ ] Backup the current site fully +- [ ] Communicate the migration window to stakeholders + +### During cutover +- [ ] Deploy the new site +- [ ] Confirm 301 redirects firing for old URLs (test 20 random samples) +- [ ] Remove `noindex` from new site +- [ ] Update robots.txt on new site (allow crawling) +- [ ] Submit new sitemap in search console +- [ ] Submit change of address (if domain changed) +- [ ] Update canonical references on the new site + +### Within 24 hours of cutover +- [ ] Crawl the new site, compare to baseline +- [ ] Spot-check 50 redirected URLs end-to-end +- [ ] Verify search console shows the new sitemap as processed +- [ ] Check for unexpected 4xx or 5xx errors in server logs +- [ ] Submit top 20 priority URLs for re-indexing + +--- + +## Post-migration (T plus 1 to 30 days) + +### Week 1 +- [ ] Daily check on indexed page count in search console +- [ ] Daily check on crawl errors +- [ ] Daily check on average position for top 50 queries +- [ ] Verify no traffic anomalies in analytics +- [ ] Fix any redirect loops or chains identified in logs + +### Week 2 to 4 +- [ ] Verify all old URLs redirecting to new URLs (full crawl) +- [ ] Verify no redirect chains (max one hop) +- [ ] Verify schema validates on key page types +- [ ] Check Core Web Vitals trend (any regressions vs pre-migration) +- [ ] Update external backlinks where feasible (highest-value links first) +- [ ] Check social media platforms display new URLs correctly + +### Month 2 +- [ ] Compare organic traffic to pre-migration baseline +- [ ] Compare keyword rankings to pre-migration baseline +- [ ] Note any pages that lost rankings, investigate +- [ ] Begin pruning redirect rules for URLs that no longer receive traffic (after 90 days minimum) + +--- + +## Common migration failures (and how to prevent each) + +| Failure | Prevention | +|---|---| +| Old URLs returning 404 | Comprehensive redirect map, tested before cutover | +| Redirect chains (2+ hops) | Direct redirect old → new, never old → middle → new | +| Lost rankings on key pages | Same content, same intent, same internal linking on new pages | +| Crawl waste from old parameters | Clean URL structure, parameter handling rules | +| Mixed HTTPS and HTTP content | Audit all asset URLs, force HTTPS via HSTS | +| Search console disconnect | Verify both old and new properties, submit change of address | +| Sitemap mismatch | New sitemap lists new canonical URLs only, no legacy URLs | +| Hreflang breaks (international sites) | Map hreflang to new URLs, preserve language pair relationships | + +--- + +## Recovery if traffic drops + +If organic traffic drops more than 20 percent within 14 days: + +1. Verify all critical URLs return 200 or 301 (no 404 or 500) +2. Verify search console is processing the new sitemap +3. Spot-check top 50 lost-traffic URLs for content parity (does the new page actually answer the same query?) +4. Check robots.txt and meta robots for accidental noindex +5. Check for hreflang errors if international +6. Submit affected URLs for re-indexing manually +7. Audit internal linking - are key pages still well-linked? + +Most migration drops recover within 60 to 90 days IF the redirect map is complete and the content is preserved. If not recovering by day 90, the issue is structural and needs deeper investigation. diff --git a/skills/seo-traffic-diagnosis/SKILL.md b/skills/seo-traffic-diagnosis/SKILL.md new file mode 100644 index 0000000..cd5c87b --- /dev/null +++ b/skills/seo-traffic-diagnosis/SKILL.md @@ -0,0 +1,180 @@ +--- +name: seo-traffic-diagnosis +description: "Diagnose organic traffic changes (drops, stalls, or unexpected wins) using Ahrefs MCP plus Search Console data. Use this skill when traffic suddenly dropped, has been flat despite investment, after an algorithm update, after a migration or deploy, or when a competitor seems to be taking share. Triggers on traffic dropped, traffic decline, traffic stalled, organic decline, lost rankings, why is traffic down, algorithm update, post-migration traffic loss, traffic diagnosis. Also triggers when stakeholders are panicking about analytics." +category: seo-audit-suite +catalog_summary: "Diagnose drops, stalls, or wins via 5-layer root cause analysis" +display_order: 5 +--- + +# SEO Traffic Diagnosis + +Diagnose why organic traffic moved (down, flat, or unexpectedly up) using Ahrefs MCP combined with Search Console and analytics data. Stack-agnostic. Produces a root-cause diagnosis and an action plan. + +--- + +## When to use + +- Organic traffic dropped sharply +- Organic traffic has been flat for months despite content investment +- After a known Google algorithm update +- After a migration, replatform, or domain change +- After a deploy that touched routing, redirects, or rendering +- When a competitor is visibly taking organic share +- When a single page dropped from a ranked position +- When stakeholders need an explanation, fast + +## When NOT to use + +- Routine performance reporting (use `analytics-strategy`) +- Pre-emptive content planning (use `seo-content-gap-audit`) +- Backlink-only investigations (use `seo-backlink-audit`) +- Technical issue triage outside of traffic concerns (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Description of the symptom (what changed, when, magnitude) +- Date the change started (best estimate) +- Recent SEO history: deploys, migrations, content changes, link campaigns +- Access to Ahrefs MCP, Search Console, and analytics +- Confirmation the change is real (not a tracking artifact) + +--- + +## The framework: 5 layers of diagnosis + +A traffic change has one or more root causes. Move through the layers in order. Stop when you have enough evidence. + +### Layer 1: Confirm the change is real + +Before diagnosing, rule out: + +- Tracking gaps (analytics outages, tag manager issues) +- Bot traffic changes +- Reporting comparison errors (different date ranges, wrong segment) +- Seasonality (compare year-over-year, not just month-over-month) +- Holiday or weekday effects + +Cross-check Search Console clicks against analytics organic sessions. Significant divergence often points to a tracking issue, not a real traffic change. + +### Layer 2: Localize the change + +Where is the change happening? + +Segment by: + +- Country and language +- Device (mobile, desktop, tablet) +- Page or section (homepage, blog, product, category) +- Query type (branded vs non-branded) +- Landing page + +A change in one segment requires different diagnosis than a change everywhere. + +| Pattern | Likely cause | +| --- | --- | +| One country dropped | Local algorithm update, hreflang issue, geo redirect issue | +| Mobile dropped, desktop flat | Mobile usability or page speed regression | +| One section dropped | Topical algorithm update or section-specific quality issue | +| Branded queries dropped | Brand-level issue: site outage, reputation, manual action | +| Non-branded dropped | Algorithmic ranking issue | +| Single page dropped | Page-level issue: content, technical, or competitive | +| Sitewide dropped | Sitewide issue: penalty, technical, migration, or algorithm | + +### Layer 3: Page-level analysis + +For affected pages, audit: + +- Position changes per ranked keyword (Ahrefs Rank Tracker history) +- SERP composition changes (more ads, AI overviews, featured snippets, video) +- Click-through rate changes +- Index status (Search Console coverage) +- Crawl errors and accessibility +- Recent content changes +- Internal link changes +- Backlink changes (lost links, redirect chains) + +A page can lose traffic without losing rank if SERP composition changed. + +### Layer 4: Technical analysis + +Did anything break technically? + +Check: + +- Robots.txt changes +- Canonical tag changes +- Meta robots changes (accidental noindex) +- Redirect chains and loops +- Render issues (especially for JS-heavy frameworks) +- Site speed regressions +- Hreflang errors +- Sitemap freshness +- HTTP status codes (4xx, 5xx spikes) +- Server log evidence of crawl behavior changes + +Recent deploys are the prime suspect. Compare deploy dates to traffic change dates. + +### Layer 5: External analysis + +If layers 1-4 do not explain the change, look outward. + +- Algorithm update calendar (cross-reference timing) +- Competitor moves (new content, new SERP features they captured) +- Industry trend (declining search demand for the topic) +- Manual action (Search Console security and manual actions) +- Negative SEO (sudden link velocity changes) + +External-factor diagnosis benefits from competitive context: did your traffic drop while competitors held steady (suggests an algorithm-specific issue), or did the entire vertical lose ground (suggests a user-behavior shift)? Similarweb shows competitor traffic trends; Ahrefs shows competitor SERP movement; pairing both surfaces whether the issue is yours alone or the category's. + +--- + +## Workflow + +1. **Confirm the symptom.** Get exact dates, magnitude, segment if known. +2. **Validate the data.** Layer 1 checks. Rule out tracking and seasonality. +3. **Localize.** Layer 2. Segment until the pattern is clear. +4. **Page-level dive.** Layer 3 on the most affected pages. +5. **Technical check.** Layer 4. Recent deploys, robots, canonicals, redirects. +6. **External check.** Layer 5. Algorithm updates, competitors, industry. +7. **Build the hypothesis.** State the cause as a single sentence. +8. **Validate the hypothesis.** Find the evidence that confirms or refutes it. See [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md). +9. **Action plan.** Specific fixes mapped to specific evidence. +10. **Communicate.** Write up the diagnosis. Stakeholders want clarity, not exhaustive analysis. + +--- + +## Failure patterns + +- **Jumping to algorithm update.** "It must be the algorithm" is the lazy answer. Eliminate technical and page-level causes first. +- **Solving the wrong problem.** A drop diagnosed as "content quality" when the real cause was an accidental noindex on a deploy. Validate the hypothesis before fixing. +- **No baseline for "normal."** Without a baseline, every fluctuation looks alarming. Establish what normal noise looks like before reacting. +- **Treating one page as the site.** Site-wide and page-level diagnoses are different. Confirm scope first. +- **Ignoring branded vs non-branded.** A drop in branded queries means a brand-level problem. A drop in non-branded means an SEO problem. Different teams own them. +- **Comparing wrong date ranges.** Comparing 28 days to the previous 28 days during a holiday distorts the picture. Use year-over-year for seasonal businesses. +- **Stopping at correlation.** A deploy and a drop on the same day is a strong correlation, not proof. Find the mechanism. +- **Single-source diagnosis.** Ahrefs sees position. Search Console sees clicks and queries. Analytics sees behavior. Logs see crawl. Use them together. +- **Premature reassurance.** Telling stakeholders "it is just an algorithm update, will recover" without evidence sets up a worse conversation later. + +--- + +## Output format + +A diagnosis document with: + +1. **Summary.** What changed, when, magnitude, root cause in one paragraph. +2. **The symptom.** Charts and segment breakdowns. +3. **Layer-by-layer findings.** What each layer ruled in or out. +4. **Root cause hypothesis.** Single statement with evidence. +5. **Action plan.** Ordered fixes with owners and timelines. +6. **Recovery forecast.** Realistic expectations on timeline and ceiling. +7. **Monitoring plan.** What to watch for confirmation of recovery. + +Length: 4-10 pages. Stakeholders read this fast. + +--- + +## Reference files + +- [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md) - Layer-by-layer diagnostic checklist with the specific data to pull at each layer and how to interpret each signal. diff --git a/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md b/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md new file mode 100644 index 0000000..2895ed3 --- /dev/null +++ b/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md @@ -0,0 +1,209 @@ +# Diagnosis checklist + +A layer-by-layer checklist for diagnosing organic traffic changes. Use it after the symptom is confirmed real and you need to narrow root cause. + +--- + +## Layer 1: Confirm the change is real + +### Pulls + +- Search Console clicks and impressions (last 90 days, day-by-day) +- Analytics organic sessions (matching window) +- Year-over-year same-period comparison +- Bot or crawler traffic if filterable + +### Checks + +- [ ] Date range comparison is apples to apples +- [ ] No tracking outage in analytics during the window +- [ ] No tag manager deploys during the window +- [ ] Search Console clicks and analytics organic sessions move together (within 10-20%) +- [ ] Year-over-year shows the same pattern (rules out seasonality) +- [ ] No major holiday or industry event explains the change + +If clicks and sessions diverge significantly: the issue may be tracking, not traffic. +If year-over-year shows the same pattern: the change is seasonal, not anomalous. + +--- + +## Layer 2: Localize the change + +### Pulls + +- Search Console: clicks segmented by country, device, query type, page +- Analytics: organic sessions segmented by landing page, country, device + +### Checks for each segment + +- [ ] One country dropped, others stable: local algorithm or geo issue +- [ ] One device dropped, others stable: device-specific issue +- [ ] One section dropped, others stable: section-specific quality or technical issue +- [ ] Branded queries dropped: brand-level issue +- [ ] Non-branded dropped: SEO ranking issue +- [ ] Single page dropped: page-level issue +- [ ] Everything dropped: sitewide issue + +### Decision + +Pick the dominant pattern. Carry the most affected segment into Layer 3. + +--- + +## Layer 3: Page-level analysis + +For each affected page or page cluster: + +### Pulls + +- Ahrefs: ranked keywords with current and historical positions +- Ahrefs: SERP overview for top 5-10 ranked keywords (current and from before the drop) +- Search Console: queries, impressions, clicks, position, CTR for each affected page +- Analytics: landing page sessions, conversion rate, bounce rate +- Index status in Search Console +- Recent edits to the page (CMS history) +- Internal links pointing to the page (Ahrefs Site Explorer) +- Backlinks to the page (Ahrefs) + +### Checks + +- [ ] Did position drop, or did position stay flat with CTR drop? +- [ ] Did the SERP composition change (new AI overviews, featured snippet steal, more ads, more video)? +- [ ] Are click-through rates lower than benchmarks for the position? +- [ ] Has the page been recently edited (intentionally or accidentally)? +- [ ] Has the page lost backlinks? +- [ ] Have internal links to the page decreased? +- [ ] Is the page indexed? + +### Interpretation + +| Pattern | Cause | +| --- | --- | +| Position fell, SERP same | Quality, freshness, or competitor improved | +| Position stable, CTR fell | SERP feature change (snippet, AI overview, ads) | +| Position fell, SERP added new strong domain | Competitor took share | +| Position fell after a CMS edit | Recent edit broke something | +| Page deindexed | Technical issue (robots, canonical, noindex) | +| Backlinks fell | Link-based ranking signal decline | +| Internal links fell | Internal link equity dilution | + +--- + +## Layer 4: Technical analysis + +### Pulls + +- Robots.txt (current and historical via web archive if needed) +- Canonical tag check on affected pages +- Meta robots tag check on affected pages +- Redirect map for any URL changes +- HTTP status codes for affected URLs +- Sitemap freshness +- Hreflang implementation (multilingual sites) +- Server logs (Googlebot crawl behavior) +- Recent deploy log +- Recent infrastructure changes (CDN, DNS, hosting) + +### Checks + +- [ ] Robots.txt has not blocked anything new +- [ ] No accidental `noindex` on affected pages +- [ ] No accidental canonical to a different URL +- [ ] Redirects resolve in 1 hop with 301 status +- [ ] No 4xx or 5xx spikes for affected URLs +- [ ] Sitemap includes affected URLs and is current +- [ ] Hreflang is reciprocal and points to live URLs (multilingual) +- [ ] Googlebot is crawling at normal rates +- [ ] No deploy date matches the traffic drop date + +### Common technical regressions + +| Symptom | Likely cause | +| --- | --- | +| Sudden full-site drop after a deploy | Robots.txt blocked everything, accidental sitewide noindex, or routing broke | +| Pages return 404 or 410 | URL structure changed, redirects missing | +| Pages return 5xx | Server or hosting issue, possible CDN misconfiguration | +| Render mismatch | JS rendering broke for crawlers (especially with framework upgrades) | +| Hreflang broken | Cross-country traffic falls but other markets shift | +| Mass canonical change | Pages canonicalized to wrong URLs after redesign | + +--- + +## Layer 5: External analysis + +### Pulls + +- Algorithm update calendar (cross-reference traffic change date) +- Ahrefs SERP overview for affected keywords (looking for new ranking domains) +- Ahrefs competitor traffic estimates (their gain may be your loss) +- Search Console security and manual actions +- Backlink velocity changes (sudden gains or losses) +- News or industry trend search interest + +### Checks + +- [ ] No manual action notice in Search Console +- [ ] Drop date does not align with a known algorithm update +- [ ] No competitor has visibly taken share on affected keywords +- [ ] Industry-wide search demand for the topic has not shifted +- [ ] No spike in suspicious backlinks (negative SEO signal) +- [ ] No negative news or PR event affecting the brand + +### If layers 1-4 are clean + +- Drop on a known update date is likely algorithmic. Audit content quality and E-E-A-T signals. Recovery often takes the next update cycle. +- Drop with new dominant SERP domain is likely a competitive shift. Audit their content and update yours. +- Drop with industry-wide demand decline is not your fault. Manage stakeholder expectations. + +--- + +## Hypothesis statement template + +After working through the layers, state the hypothesis as a single sentence: + +``` +[Property] lost [magnitude] organic traffic starting [date] +because [root cause], +evidenced by [specific data points], +and recovery requires [specific actions] +with an expected timeline of [duration]. +``` + +Examples: + +> Site organic clicks dropped 35% starting March 12 because a deploy on March 11 added an accidental `noindex` meta tag sitewide, evidenced by Search Console coverage going from 2,400 indexed pages to 180 in 14 days, and recovery requires removing the noindex tag and resubmitting the sitemap with an expected timeline of 4-8 weeks. + +> Blog section organic clicks dropped 22% starting August 8 because Google rolled out a core update on that date that emphasizes E-E-A-T signals our author bylines lacked, evidenced by position drops on informational queries while transactional queries held, and recovery requires adding author E-E-A-T signals and improving content depth with an expected timeline of 1-2 update cycles (3-6 months). + +--- + +## When the diagnosis is unclear + +Sometimes the data points in multiple directions. In that case: + +1. State the top 2 hypotheses with evidence for each. +2. Recommend the lowest-risk action that helps in either case. +3. Identify the data that would distinguish the hypotheses. +4. Propose a monitoring plan to gather that data. + +Avoid forcing a clean conclusion when the evidence does not support one. Stakeholders prefer honest uncertainty to confident-but-wrong. + +--- + +## Communication template + +When delivering the diagnosis to stakeholders: + +``` +**What happened:** [1 sentence] + +**Why it happened:** [1 sentence] + +**What we are doing:** [3-5 specific actions] + +**When to expect recovery:** [timeline with confidence level] + +**What to watch for:** [leading indicators of recovery or further decline] +``` + +Stakeholders rarely want the layer-by-layer detail. They want clarity, accountability, and timeline. Keep the full diagnosis as an appendix. diff --git a/skills/skill-creation-walkthrough/SKILL.md b/skills/skill-creation-walkthrough/SKILL.md new file mode 100644 index 0000000..7683255 --- /dev/null +++ b/skills/skill-creation-walkthrough/SKILL.md @@ -0,0 +1,261 @@ +--- +name: skill-creation-walkthrough +description: Step-by-step guide for creating your own Claude Skills, from deciding whether a skill is the right tool to writing the SKILL.md file, structuring reference material, and making it trigger reliably. Use when you want to package a workflow, framework, or repeated task into a reusable Skill, when an existing skill is not triggering or not loading the right context, when you are auditing a skill that is underperforming, or when you want to publish a skill for others. Also triggers when someone asks "how do I make a skill" or "what makes a good skill". Useful for individuals, teams, and anyone publishing skills publicly. +category: process-and-team +catalog_summary: "The meta-skill: how to write your own custom skills" +display_order: 5 +--- + +A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate. + +## When to use + +- You catch yourself writing the same prompt or instructions repeatedly. +- You want to package a workflow or framework for reuse. +- An existing skill of yours is not triggering when it should. +- You are publishing skills for others to use. +- You want to teach Claude a domain-specific way of working. +- You are reviewing a skill someone wrote and need a quality bar. + +## When NOT to use + +- For one-off prompts (just write the prompt). +- For information that should live in system context, not progressive disclosure. +- For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills). +- For replacing tool calls (skills are instructions, not tools). + +## Required inputs + +- The task or workflow you want to encode. +- The audience: who will trigger this skill, in what kind of conversation. +- Existing artifacts: prompts you have used, docs you have written, examples of good output. + +## The framework: how skills work + +A Skill is a folder with a `SKILL.md` file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed. + +The key property: **progressive disclosure**. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context. + +What this means for you: + +- The **description** is everything for triggering. Get it right or the skill never loads. +- The **SKILL.md body** is for the workflow itself. +- The **references** are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material. + +## Workflow + +### Phase 1: Decide if a skill is the right shape + +Not everything should be a skill. Run this test: + +| Sign it should be a skill | Sign it should not be | +| --- | --- | +| You repeat the same workflow 5+ times. | You used it once. | +| The output benefits from a consistent structure. | Each output is bespoke. | +| The task has a clear trigger (a question shape, a file type, a domain). | The task is part of every conversation already. | +| The instructions exceed 200 words. | A one-line system instruction would do. | +| Templates or reference material would help. | Pure prose is enough. | +| Other people might benefit from the same workflow. | Only relevant to your single project. | + +If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction. + +### Phase 2: Define the trigger + +Before writing anything, ask: when should this skill load? + +Be concrete. Write down the exact phrases or situations that should trigger it. Examples: + +- "When the user asks for a creative brief, kickoff doc, or project brief." +- "When the user uploads a CSV and wants tabular analysis." +- "When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related." +- "When the user mentions they want to pick a vendor or compare tools." + +The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably. + +### Phase 3: Write the description + +This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill. + +Good descriptions have 4 parts: + +1. **What it does** (one sentence, action-oriented). +2. **When to use it** (the trigger phrases or situations). +3. **Edge cases** with "Also triggers when..." (catches less obvious situations). +4. **Useful for...** (audience or use cases, helps disambiguation). + +Bad description: + +> "Helps with SEO." + +Why it fails: vague, no trigger phrases, will not fire when the user actually needs it. + +Good description: + +> "Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits." + +Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity. + +### Phase 4: Structure the SKILL.md body + +A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills: + +``` +--- +name: [your-skill-name] +description: [your description] +--- + +[One-sentence purpose statement] + +## When to use +[Bulleted list of trigger situations] + +## When NOT to use +[Bulleted list, ideally redirecting to sibling skills] + +## Required inputs +[What Claude needs from the user to run this skill] + +## The framework +[The durable IP: the model, the steps, the dimensions, the layers] + +## Workflow +[Numbered steps Claude follows] + +## Failure patterns +[Common mistakes to avoid or push back on] + +## Output format +[What the deliverable looks like] + +## Reference files +[List of files in the references/ folder with descriptions] +``` + +Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed. + +### Phase 5: Add references for what does not belong in SKILL.md + +References are the second tier of progressive disclosure. They load when Claude reads them, not by default. + +Use references for: + +- Long checklists (a 100-item audit checklist). +- Templates with worked examples. +- Detailed playbooks for specific scenarios. +- Reference material like spec links, glossaries, decision tables. +- Anything over 100 lines that not every invocation needs. + +Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides. + +Naming patterns that work: + +- `references/[noun]-template.md` for templates. +- `references/[noun]-checklist.md` for checklists. +- `references/[noun]-playbook.md` for end-to-end runbooks. +- `references/example-[scenario].md` for worked examples. + +Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each. + +### Phase 6: Test and iterate + +Skills do not work the first time. Plan to iterate. + +Testing checklist: + +- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong. +- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire? +- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad. +- [ ] Output test: run the skill on a real task. Is the output what you expected? +- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim. + +After testing, common fixes: + +- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..." +- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience. +- Output is generic → add a clearer framework or workflow with more specifics. +- Reference is overwhelming → split into multiple references, keep each focused. + +## Deep dive: description anatomy + +The description is hard to get right. Here is the formula in detail. + +### Sentence 1: What it does + +Lead with the verb. Be specific. + +- Good: "Audit on-page SEO." +- Bad: "Help with SEO things." + +### Sentence 2: When to use it + +State the primary triggers. Use phrases users would actually say. + +- Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'." +- Bad: "Use for SEO improvements." + +### Sentence 3: "Also triggers when..." + +Catch the secondary triggers and edge cases. + +- Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup." +- Bad: (omitted) + +### Sentence 4: Useful for... + +Explain audience or scope to help with disambiguation. + +- Good: "Useful for both individual page reviews and small-batch audits." +- Bad: (omitted) + +If your skill description is one sentence, it is probably not specific enough. + +## Deep dive: worked example + +Imagine you keep writing technical post-mortem documents and want to skill-ify it. + +**Step 1: Decide it's a skill.** You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill. + +**Step 2: Trigger.** "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong." + +**Step 3: Description.** + +> "Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews." + +**Step 4: SKILL.md body.** Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up). + +**Step 5: References.** A `post-mortem-template.md` with the document structure and a `facilitator-checklist.md` for running the post-mortem meeting. + +**Step 6: Test.** Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro). + +You iterate until the triggers fire correctly, then ship. + +## Failure patterns + +- **Description too narrow.** The skill never fires because your description requires exact phrases the user does not say. +- **Description too broad.** The skill fires constantly, including for unrelated tasks. +- **No trigger phrases.** The description describes what the skill does but not when to load it. Triggering is unreliable. +- **SKILL.md too long.** A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references. +- **References that duplicate SKILL.md.** If a reference repeats what the body says, prune one. +- **No "When NOT to use".** Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly. +- **No examples.** A framework without a worked example is hard to apply. Include at least one in the reference material. +- **Optimizing for one example.** A skill written around your single use case fails at adjacent ones. Generalize. +- **No iteration.** Shipping a skill once and never revisiting it. Skills decay. Audit yearly. +- **Branding or product-specific assumptions in a public skill.** Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md) for the full discipline and the user-outcome reasons it matters. + +## Output format + +When using this skill to create another skill, deliver: + +1. **Trigger analysis**: a short list of phrases and situations that should fire the skill. +2. **Description draft**: the 2-4 sentence description for the YAML frontmatter. +3. **SKILL.md body**: the full body of the skill, following the standard structure. +4. **Reference plan**: a list of reference files to create with one-line descriptions. +5. **First reference file**: at least one reference written end to end as a starting point. +6. **Test plan**: 3-5 test prompts that should trigger the skill, plus 2-3 that should not. + +## Reference files + +- [`references/skill-template.md`](references/skill-template.md): A blank SKILL.md template with annotated section guidance, ready to copy and fill in. +- [`references/description-cookbook.md`](references/description-cookbook.md): A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs). +- [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md): What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure. diff --git a/skills/skill-creation-walkthrough/references/description-cookbook.md b/skills/skill-creation-walkthrough/references/description-cookbook.md new file mode 100644 index 0000000..ff3ba60 --- /dev/null +++ b/skills/skill-creation-walkthrough/references/description-cookbook.md @@ -0,0 +1,214 @@ +# Description cookbook + +The skill description is the single most important sentence (or paragraph) in your skill. It is what Claude sees in the system prompt to decide whether to load the rest of the skill. If the description is wrong, the skill never fires when it should, or fires when it should not. + +This cookbook gives you description patterns for common skill types, each with a worked example. + +## The 4-part formula + +A reliable description has 4 parts: + +1. **Action**: what the skill does (verb-led, specific). +2. **Primary triggers**: when to use it (the obvious cases). +3. **Edge cases**: secondary triggers introduced with "Also triggers when...". +4. **Audience or scope**: who this serves, introduced with "Useful for...". + +Not every skill needs all four parts. Most benefit from at least three. + +## Pattern 1: The audit skill + +For skills that evaluate something against a rubric. + +### Template + +``` +[Verb] [the thing] for [purpose]. Use when the user asks for [a concrete request], wants to [common task], or asks "[likely user phrasing]". Also triggers when the user mentions [related concepts] or shares [input that implies the audit]. Useful for [scope: one-off vs ongoing, individual vs batch]. +``` + +### Worked example + +``` +Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks "why is this page not ranking". Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits. +``` + +Why this works: + +- "Audit" is a clear verb. +- The "on a single URL or a small set of pages" sets scope, which prevents this from competing with bulk audit skills. +- Three primary triggers in different phrasings. +- "Also triggers when..." catches secondary signals. +- "Useful for..." narrows the use case. + +## Pattern 2: The template or generator skill + +For skills that produce a structured artifact. + +### Template + +``` +Generate [the artifact] following [methodology or structure]. Use when the user asks to write [artifact name], needs [related deliverable], or describes [the work this artifact captures]. Also triggers when the user has [precondition] and is preparing to [downstream action]. Useful for [audience or use case]. +``` + +### Worked example + +``` +Generate a creative brief that aligns stakeholders before a project starts. Use when the user asks to write a brief, kickoff doc, or project brief, or describes a project that has a goal but no shared context document. Also triggers when the user is starting design or development work without an agreed scope. Useful for individual project briefs and recurring brief templates. +``` + +Why this works: + +- "Generate" is the verb. +- "That aligns stakeholders before a project starts" tells Claude the context. +- Multiple ways the user might phrase the request. +- The "also triggers" catches the upstream signal (no shared context yet). + +## Pattern 3: The framework or methodology skill + +For skills that teach or apply a way of thinking. + +### Template + +``` +Apply [framework name or shape] to [the problem]. Use when the user is [the situation], asks "[likely question]", or needs to think through [the kind of decision]. Also triggers when [secondary condition]. Useful for [scope]. +``` + +### Worked example + +``` +Apply the Diataxis framework to documentation problems: separate tutorials, how-to guides, references, and explanations. Use when the user is reorganizing docs, asks "where should I put this", or has docs that try to do too much at once. Also triggers when the user is starting a fresh docs site and needs a content structure. Useful for both internal and external documentation. +``` + +Why this works: + +- Names the framework explicitly. +- Concrete trigger phrases. +- "Has docs that try to do too much at once" is a specific symptom that maps to this framework. + +## Pattern 4: The walkthrough or playbook skill + +For skills that take the user through a multi-step process. + +### Template + +``` +Walk through [the process] step by step. Use when the user is [the situation], asks how to [the goal], or needs a structured approach to [complex task]. Also triggers when [edge case]. Useful for [first-time vs repeat use, individuals vs teams]. +``` + +### Worked example + +``` +Walk through a domain migration step by step, including DNS, redirects, content mapping, and post-launch validation. Use when the user is moving content between platforms, changing domains, or restructuring URLs at scale. Also triggers when the user mentions hreflang updates, sitemap regeneration, or 301 redirect maps. Useful for both small migrations (a few hundred URLs) and large ones (tens of thousands). +``` + +Why this works: + +- "Step by step" sets expectation. +- Names the components ("DNS, redirects, content mapping, and post-launch validation") so users with one of these in mind still trigger correctly. +- Scale guidance in "useful for" helps with disambiguation. + +## Pattern 5: The decision or evaluation skill + +For skills that help the user pick between options. + +### Template + +``` +Compare [option type] and recommend [outcome]. Use when the user is choosing between [options], asks "[option A] vs [option B]", or needs to decide [the question]. Also triggers when [renewal/replacement/scaling situation]. Useful for [scope]. +``` + +### Worked example + +``` +Compare vendors and recommend a pick for a specific job. Use when the user is choosing between SaaS tools, asks "X vs Y", or needs to evaluate options before signing a contract. Also triggers when an existing vendor is up for renewal or being replaced. Useful for both small SaaS decisions and large infrastructure choices. +``` + +Why this works: + +- "Compare and recommend" frames the action. +- Multiple trigger phrasings. +- "Also triggers when..." catches the renewal/replacement situation that often forces a decision. + +## Pattern 6: The diagnostic or troubleshooting skill + +For skills that help find what is wrong. + +### Template + +``` +Diagnose [the problem class] and propose fixes. Use when the user reports [symptom], asks "why is [thing] [bad state]", or shares [evidence of the problem]. Also triggers when [related signal]. Useful for [scope of diagnosis]. +``` + +### Worked example + +``` +Diagnose slow page performance and propose specific fixes. Use when the user reports slow load times, asks "why is my site slow", or shares a Core Web Vitals report. Also triggers when the user mentions Lighthouse scores, LCP, INP, or CLS issues. Useful for both individual page diagnosis and site-wide performance reviews. +``` + +Why this works: + +- "Diagnose and propose fixes" is the action. +- Catches the user's likely phrasing ("why is my site slow"). +- Catches technical phrasings (Core Web Vitals report, Lighthouse, specific metric names). + +## Pattern 7: The strategy or planning skill + +For skills that produce a plan or strategy. + +### Template + +``` +Design [the plan or strategy] for [outcome]. Use when the user is [the situation], asks for a [plan / strategy / roadmap], or needs to align [stakeholders or work] around [the goal]. Also triggers when [precondition or constraint]. Useful for [scope]. +``` + +### Worked example + +``` +Design a content strategy that supports a specific business goal. Use when the user is starting a content program, asks for an editorial plan, or needs to align content production with marketing or SEO objectives. Also triggers when the user mentions topical authority, content calendar, or pillar pages. Useful for both new programs and reboots of stalled ones. +``` + +Why this works: + +- "Design a content strategy that supports a specific business goal" sets the action and the constraint. +- Catches both fresh starts and reboots in "useful for". + +## Anti-patterns: descriptions that fail + +### "Helps with X" + +Too vague. No triggers. Will fire constantly or never. + +### "When the user wants help with technical SEO and on-page SEO and off-page SEO" + +Too broad. Should be split into multiple skills or narrowed. + +### "Use when the user mentions XYZ" + +Too narrow. Real users will not always use the exact phrase. + +### "Comprehensive guide to [topic]" + +Marketing copy, not a trigger. Does not tell Claude when to load. + +### "[no description, just a name]" + +The skill never loads except by accident. + +## How to test a description + +Before publishing: + +1. Write down 5 prompts that should trigger the skill. +2. Write down 3 prompts that should not. +3. In a fresh conversation with the skill installed, try each prompt. +4. Check whether the skill loaded. +5. Adjust the description until trigger and non-trigger prompts behave correctly. + +If a should-trigger prompt does not fire, broaden the description: add the phrasing the user used, add an "also triggers" clause. + +If a should-not-trigger prompt fires, narrow the description: add scope boundaries, name the sibling skill the user actually wants, or add a "Do not trigger when..." clause if needed (most skill descriptions do not need this, but it is available). + +## Final tip: match the user's vocabulary + +Users do not say "perform an SEO audit". They say "can you check my page" or "is my site optimized". Your description should anticipate the user's vocabulary, not yours. + +If your description is full of expert jargon and the user is a beginner, the skill will not fire. Use the words your audience actually says. Use jargon as a backup, not the lead. diff --git a/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md b/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md new file mode 100644 index 0000000..55c6f4f --- /dev/null +++ b/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md @@ -0,0 +1,96 @@ +# Methodology vs implementation + +What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. + +A public skill is methodology, not implementation. Skills teach the framework, the decision criteria, the taxonomies, the anti-patterns. They do not teach the specific page architecture, type definitions, image generation script structure, or stack-specific patterns that any one team uses to ship polished delivery. + +This is not gatekeeping. It is user-aligned. Methodology produces work that is distinctive to each team's stack and judgment. Cookie-cutter implementation produces homogenized output that looks identical across users. Stack-agnosticism makes the catalog actually portable. Implementation specificity makes it useless to teams on different stacks. + +--- + +## What belongs in a public skill (methodology layer) + +- Conceptual frameworks (architectures, registers, taxonomies, classifications) +- Decision criteria (when to choose X versus Y, with the tradeoffs surfaced) +- Anti-patterns and common failure modes +- The shape of artifacts the skill produces, described in generic terms (a markdown brief with these sections; a JSON object with these fields; a design spec with these decisions documented), not as type signatures bound to a specific framework +- Voice and style guidance for the work +- Workflow descriptions at the methodology level (the sequence of decisions and handoffs, not the platform commands) +- General principles applicable across stacks +- Worked examples with fictional or anonymized actors that demonstrate the framework concretely without prescribing a specific tooling stack + +The 12-consideration framework pattern (or 5-pillar, 4-axis, etc.) lives here. Frameworks are durable; they survive stack migrations and team transitions because they teach judgment, not code. + +--- + +## What does not belong in a public skill (implementation layer) + +- Specific Next.js, React, Vue, Svelte, or other framework-specific page architectures +- TypeScript or other type definitions optimized for a specific application's data shapes +- Component patterns with stack-specific code (JSX, template syntax, framework directives) +- Image generation script structures matching a specific implementation +- Application-context CSS-rendered mockup component code +- Theme integration patterns tied to specific design tokens (brand-color names, spacing scales, font tokens that exist only in one team's design system) +- Tailwind class strings or other utility-CSS specifics that prescribe one stack's idioms +- Schema markup component shapes that match one team's component library +- Vercel, Netlify, or specific deployment patterns + +If a section of a skill cannot be applied by a reader on a different stack, it does not belong in the public skill. It belongs in an internal playbook, a productized client deliverable, or a stack-specific reference implementation maintained separately. + +--- + +## Why the line matters + +Three principles, each user-outcome framed. + +### 1. Methodology produces distinctive work + +A skill that teaches "five logo architectures" leaves the user to choose, design, and execute the architecture that fits their brand. A skill that teaches "render this Next.js component with these Tailwind classes" produces work that looks identical across every user who runs the skill. Cookie-cutter implementation homogenizes; methodology requires the user to engage with why, which produces work distinctive to each team's context. + +The user outcome that matters: did the skill help the user produce work that is theirs, or did it produce work that signals "I ran a skill"? + +### 2. Stack-agnosticism is real value + +A skill that mandates a specific Next.js component is useless to teams on Astro, vanilla HTML, Figma-only workflows, WordPress, Shopify, or anywhere off the prescribed stack. Methodology applies across all of them. + +The catalog gets used by people writing in plain markdown, working in Notion, building on a static site generator, running in WordPress, or shipping in something that did not exist when the skill was written. Methodology survives all of those. Stack-coupled implementation does not. + +### 3. The catalog compounds because skills are durable + +Skills last across stack changes, framework migrations, and team transitions because they teach judgment, not code. A skill that hardcodes the framework du jour decays as the framework changes. A skill that teaches the framework-agnostic principle the framework was implementing keeps working when teams migrate to the next framework. + +Implementation-leaking skills decay as their implementations become outdated. Methodology-pure skills compound across years. + +--- + +## The audit pattern + +The catalog is audited periodically for methodology versus implementation drift. The first formal audit (May 2026) reviewed 18 flagship skills against the criteria in this reference and found zero implementation-leakage findings; the discipline had been held by instinct from the catalog's earliest skills onward. Future audits will land as the catalog grows past current size. + +Findings shape the discipline. Recently shipped skills tend to carry the discipline more cleanly than the earliest ones, which reflects the maturation any catalog goes through. The principle is not "perfection from day one"; it is "audit, learn, codify, hold the line going forward." + +--- + +## How to apply this when authoring new skills + +A short checklist for skill authors: + +1. **Before writing, identify the methodology versus implementation boundary explicitly.** What part of this skill teaches a framework that applies across stacks? What part teaches your specific stack's implementation? The framework part goes in the public skill; the implementation part stays internal. +2. **When tempted to include specific code, ask: is this teaching the framework, or is this teaching my stack?** If it teaches the framework using your stack as one illustration, keep it; if it teaches your stack using the framework as scaffolding, move it. +3. **When referring to tooling, prefer general categories** ("a feature flag platform," "a data warehouse," "a CMS with structured content models") over specific products. Name specific products when the category needs concretization, and name multiple alternatives so readers see the category rather than locking into one vendor. +4. **Cross-references to specific tools or services should be sparse.** Each cross-reference should earn its inclusion through methodology relevance, not marketing value. If a cross-reference exists primarily to drive traffic, it is not earning its keep in a methodology skill. +5. **Run the audit checklist before merge.** Any specific code? Any type signatures matching your application? Any framework-specific patterns? If yes, move to internal playbook. + +--- + +## What stays internal + +Implementation specifics live somewhere; they just do not live in the public skill. Common locations: + +- Internal playbooks in private repositories +- Internal documentation in team wikis or knowledge bases +- Productized client deliverables produced by combining methodology plus playbook plus judgment +- Stack-specific reference implementations maintained as separate properties +- Onboarding materials for team members joining the implementation work + +The principle: anyone reading the public skill should be able to produce quality methodology-driven work on their own stack. Teams that want polished productized delivery in a specific stack do that work themselves, build their own internal playbooks, or engage practitioners who specialize in that delivery. The public skill is the upstream input; the implementation is the downstream work, owned by whoever is doing it. diff --git a/skills/skill-creation-walkthrough/references/skill-template.md b/skills/skill-creation-walkthrough/references/skill-template.md new file mode 100644 index 0000000..eb5f92f --- /dev/null +++ b/skills/skill-creation-walkthrough/references/skill-template.md @@ -0,0 +1,153 @@ +# Skill template + +A blank SKILL.md template with annotated guidance. Copy this, fill it in, and you have a skill that fits the pattern. + +## How to use this template + +1. Copy the YAML and structure below into a new file at `your-skill-name/SKILL.md`. +2. Replace the placeholder text in `[brackets]`. +3. Delete sections you do not need (most skills do not need every section). +4. Read the annotations to understand what each section is doing. +5. Test the skill on a real task. Iterate. + +## The template + +``` +--- +name: [your-skill-name] +description: [2-4 sentences. What the skill does. When to use it. "Also triggers when..." for edge cases. "Useful for..." for audience clarity.] +--- + +[One-sentence purpose statement. What this skill exists to do.] + +## When to use + +- [Trigger situation 1] +- [Trigger situation 2] +- [Trigger situation 3] +- [Trigger situation 4] + +## When NOT to use + +- [Situation that looks similar but should use a different skill] +- [Situation that is out of scope for this skill] +- [Sibling skill cross-reference: "For X, use the [other-skill] skill."] + +## Required inputs + +- [Information Claude needs from the user before it can do good work] +- [Or context Claude needs to gather] +- [Or files, links, or examples needed] + +## The framework + +[The durable IP. The model, dimensions, layers, principles that make this skill different from a freeform response. This is where the skill earns its keep.] + +[Format options: numbered list of layers, table of dimensions, hierarchy of concepts. Pick what fits the content.] + +## Workflow + +1. [First step Claude takes] +2. [Second step] +3. [Third step] +4. [...] +5. [Final step or output] + +## Failure patterns + +- **[Common mistake]**: [Why it happens, how to avoid]. +- **[Common mistake]**: [Why it happens, how to avoid]. +- **[Common mistake]**: [Why it happens, how to avoid]. + +## Output format + +Deliverables from this skill: + +1. **[Artifact 1]**: [What it is]. +2. **[Artifact 2]**: [What it is]. +3. **[Artifact 3]**: [What it is]. + +[Optional: notes on format, length, or delivery mechanism.] + +## Reference files + +- `references/[name].md`: [One-line description of what is in this reference]. +- `references/[name].md`: [One-line description]. +``` + +## Annotations: what each section is for + +### YAML frontmatter + +The `name` should match the folder name and use lowercase hyphens. The `description` is the most important field in the entire skill. It is what Claude sees in the system prompt to decide whether to load the skill body. Be specific about triggers. + +### Purpose statement (one sentence) + +This is the elevator pitch. A reader should know what the skill does after this one sentence. If you cannot summarize it in a sentence, the skill may be doing too much. + +### When to use + +Be concrete. List the actual situations where the skill should fire. These map to the trigger phrases in the description but in more detail. + +### When NOT to use + +Just as important as "when to use". This is where you redirect to sibling skills and prevent overlap. Without this section, related skills compete and Claude makes ambiguous choices. + +### Required inputs + +What does Claude need before it can do good work with this skill? Sometimes this is information ("the URL to audit"). Sometimes it is context ("the user's audience"). Listing it explicitly helps Claude ask the right question if it is missing. + +### The framework + +This is the durable IP. The thing that makes your skill better than a generic LLM response on the topic. A model, a set of dimensions, a hierarchy, a checklist of layers. + +If you cannot articulate the framework, the skill may be more about output structure than methodology. That is fine. Skip this section. + +### Workflow + +The numbered steps Claude follows when running the skill. Should be repeatable across different invocations. If the steps differ wildly per use case, you may need multiple skills or a more abstract framework. + +### Failure patterns + +What goes wrong in practice. This section is what makes a skill feel earned. It signals "we have done this many times and these are the mistakes". Specific failure patterns are more useful than abstract ones. + +### Output format + +What the deliverable looks like. Not "good output" - actually structured and named. This is what Claude produces at the end. + +### Reference files + +The list of `references/` files with brief descriptions. Each reference should be standalone and useful even if read out of order. + +## Sizing guidance + +| Component | Target | Hard limit | +| --- | --- | --- | +| Description | 2-4 sentences | 1 paragraph | +| SKILL.md total | Under 250 lines | 500 lines | +| Single reference file | Under 400 lines | 800 lines | +| Number of references | 1-3 | 5 | + +If you are over the targets, split or trim. Skills get heavier and more brittle as they grow. + +## Naming conventions + +- Skill folder: `lowercase-hyphenated` +- SKILL.md: always exactly `SKILL.md` (case-sensitive) +- References: `references/[name].md` +- Templates: `[noun]-template.md` +- Checklists: `[noun]-checklist.md` +- Playbooks: `[noun]-playbook.md` +- Examples: `example-[scenario].md` + +## Common adaptations + +Not every skill needs the standard structure. Examples of valid adaptations: + +- **Pure how-to skill**: skip the "framework" section, lead with workflow. +- **Pure template skill**: skip framework and workflow, focus on the structure of the output. +- **Audit skill**: heavy on the framework (the dimensions to score), lighter on workflow. +- **Walkthrough skill**: numbered phases as the spine, no separate framework section. +- **Decision skill**: heavy on options and tradeoffs, lighter on workflow. + +The structure exists to make sure you cover the right ground. If a section does not earn its place, drop it. But know what you are dropping and why. diff --git a/skills/stakeholder-communication/SKILL.md b/skills/stakeholder-communication/SKILL.md new file mode 100644 index 0000000..f5a1950 --- /dev/null +++ b/skills/stakeholder-communication/SKILL.md @@ -0,0 +1,360 @@ +--- +name: stakeholder-communication +description: "Communicate effectively with stakeholders across functions and seniority levels. Use this skill when writing status updates, preparing executive reviews, sharing technical decisions with non-technical audiences, managing up, communicating bad news, or designing the communication cadence for a project. Triggers on stakeholder update, status report, executive summary, exec review, manage up, communicate bad news, project comms, status meeting, weekly update. Also triggers when a project is going off track and the team needs to communicate it." +category: process-and-team +catalog_summary: "Status updates, exec readouts, project communications" +display_order: 1 +--- + +# Stakeholder Communication + +Get the right information to the right people at the right time, in a form they can act on. Stack-agnostic. Applies to any team operating with cross-functional stakeholders. + +--- + +## When to use + +- Writing weekly or monthly status updates +- Preparing for an executive review or board update +- Sharing a technical decision with a non-technical audience +- Communicating a delay, miss, or quality problem +- Asking for help, resources, or decisions +- Managing up to a manager or sponsor +- Designing the communication cadence for a project +- Drafting an internal announcement + +## When NOT to use + +- Customer-facing communication (use marketing/support skills) +- Public comms or press (different framework, different stakes) +- Incident communication during an active incident (use `incident-response`) +- Internal documentation that isn't time-sensitive (use `documentation-strategy`) +- Specific delivery formats (slide deck design, email tone) - this skill is about content and structure + +--- + +## Required inputs + +- The audience (who specifically, what's their context, what do they care about) +- The purpose (inform, decide, escalate, ask, celebrate) +- The substance (what's actually happening) +- The medium (email, doc, meeting, slide, chat) +- Time constraints (when do they need this) + +--- + +## The framework: 5 questions + +Before any stakeholder communication, answer: + +### Question 1: Who is the audience? + +Specifically. "Leadership" is too vague. The CFO and the VP of Engineering have different concerns. + +For each named audience: +- What do they care about? (revenue, risk, quality, velocity, costs, customers) +- What do they already know? (background you can skip) +- What's their level of detail tolerance? (executives want headlines; ICs want details) +- What action do you want from them? (acknowledgment, decision, help, no action) + +### Question 2: What's the headline? + +If they read only one sentence, what should they take away? + +The headline goes first. Always. The narrative supports it; the data confirms it. + +This is the biggest gap in most stakeholder communication: people start with context and build to a conclusion. Stakeholders want the conclusion first. + +### Question 3: What's the so-what? + +Stakeholders ask "and?" implicitly. Answer it explicitly. + +- "We hit 80% of the milestone." → so what? +- "We hit 80% of the milestone, which puts the launch one week behind plan." → that's the so-what. + +The so-what makes the information actionable. + +### Question 4: What do you want? + +Communications generally have one of these requests: + +- **Inform:** no action needed. Just keeping them in the loop. +- **Decide:** a decision is needed; here are the options and recommendation. +- **Escalate:** something is stuck; we need help. +- **Ask:** a specific request (resource, introduction, review). +- **Celebrate:** a win to share; no action needed but morale matters. + +State which. Don't bury the request. + +### Question 5: What format? + +- **Async written** (doc, email): rich content, decision trail, easy to reference +- **Sync written** (chat, ticket comment): quick exchange, conversational +- **Sync spoken** (meeting, call): nuance, debate, alignment +- **Mixed** (doc + meeting): the doc is read in advance; meeting is decision + +For most updates: async written. Save sync time for actual discussion. + +--- + +## The structure: the inverted pyramid + +Stakeholder communication reads like a news article, not an essay. + +``` +Headline (one sentence) + +The "so what" and the request (one paragraph) + +Status / progress (the body) + +Risks and asks (what we need) + +Detail / appendix (what curious readers want) +``` + +Cut from the bottom. If your update gets shortened, the top survives. + +--- + +## Update templates + +### Weekly project update + +``` +**Project:** [Name] +**Status:** [On track / At risk / Off track] +**Headline:** [One-sentence summary] + +**This week:** +- [Specific accomplishment] +- [Specific accomplishment] +- [Specific accomplishment] + +**Next week:** +- [Specific plan] +- [Specific plan] + +**Risks / blockers:** +- [Risk + what we're doing about it / what we need] + +**Metrics:** +- [Metric: value vs target] +- [Metric: value vs target] +``` + +The status indicator (on track / at risk / off track) is essential. Stakeholders scan for it. + +### Executive review + +``` +**Headline:** [The summary, one sentence] + +**Key points:** +1. [Point with one supporting sentence] +2. [Point with one supporting sentence] +3. [Point with one supporting sentence] + +**Decisions needed:** +- [Decision A: options and recommendation] +- [Decision B: options and recommendation] + +**Asks:** +- [Specific request] + +**Detail:** [Linked doc or appendix] +``` + +Executives skim. They click into detail when interested. + +### Bad news + +The hardest update to write well. + +``` +**Headline:** [The bad news, plainly stated] + +**What happened:** +[Specific facts, no euphemisms] + +**Impact:** +[Who's affected, how much, by when] + +**What we're doing:** +[Specific actions and owners] + +**What we need:** +[Specific asks, if any] + +**Timeline:** +[When the next update will land] +``` + +Don't soften the headline. Soft headlines on bad news erode trust faster than the news itself. + +### Decision request + +``` +**Decision:** [What needs to be decided] + +**Context:** [The minimum needed to understand] + +**Options:** +1. [Option A: description, pros, cons] +2. [Option B: description, pros, cons] +3. [Option C: description, pros, cons] + +**Recommendation:** [Option X, because...] + +**Need by:** [Date] +**Decision rights:** [Who decides] +``` + +Recommendation matters. Not making one is putting the work back on the decider. + +--- + +## Tone and register + +### Across audiences + +| Audience | Tone | Detail | Length | +|---|---|---|---| +| Direct manager | Candid, briefer | Mid | Medium | +| Skip-level / VP | Polished, sharper | Low | Short | +| Cross-functional peer | Collaborative, specific | Mid-high | Medium | +| Executive / board | Headlines, confident | Low (with detail available) | Short | +| Team / IC stakeholders | Detailed, direct | High | Long | + +### What to avoid + +- **Hedging when confident.** "I think maybe we might be able to..." Just say what you mean. +- **Confidence when uncertain.** "Definitely launching Friday" when there's risk. Calibrate. +- **Jargon for non-technical audiences.** Replace with plain language. +- **Burying the lede.** Headline first. +- **Implicit asks.** State explicitly what you want. +- **Status updates that are 90% activity, 10% outcome.** Focus on outcomes; activity is supporting evidence. + +--- + +## Workflow + +### Step 1: Define the audience and purpose + +Before writing, answer Q1-Q5 above. Often this clarifies the message before any drafting. + +### Step 2: Draft the headline + +One sentence. The takeaway. If you can't write the headline, you don't know yet what you're communicating. + +### Step 3: Write inverted pyramid + +Headline, so-what, body, asks, detail. + +### Step 4: Cut + +A first draft is usually 30-50% too long. + +- Cut activities that don't have outcomes +- Cut adjectives (great, awesome, excellent, exciting) +- Cut filler (just, really, very, actually) +- Cut hedging (kind of, sort of, somewhat) when confident +- Cut sentences that don't add information + +### Step 5: Verify the request + +Reread. Is the ask clear? Is it specific? Is the deadline named? + +### Step 6: Check the audience + +Imagine the recipient reading. Will they understand the headline? Have you skipped context they need? Have you given context they don't need? + +### Step 7: Send and follow up + +After sending: +- Did the right people see it? Acknowledge the right channel. +- Did they understand? Watch for confused replies; address them. +- Did they act? Follow up on stale asks. + +--- + +## Cadence design + +Different audiences need different cadences. + +### High-frequency (weekly or more) + +- Direct team, manager, sponsor +- Active project stakeholders +- People making day-to-day decisions + +### Medium-frequency (biweekly to monthly) + +- Skip-level +- Cross-functional partners +- Adjacent teams +- Strategic stakeholders + +### Low-frequency (quarterly) + +- Executive review +- Board update +- Wider organization +- External stakeholders (where relevant) + +The right cadence is what's needed, not what fills the calendar. Update people when there's something new; don't manufacture updates. + +--- + +## Failure patterns + +**Long preamble before the point.** Three paragraphs of context, then the one sentence that mattered. Lead with the point. + +**Status: yellow.** Same status three weeks in a row. Yellow with no change is red. Be honest about progress. + +**Update without a clear ask.** "We're working on it." OK, what do you want? If nothing, say "no action needed." + +**Sandwiching bad news in good news.** "We've done X and Y, and unfortunately Z is delayed, but we've also done W." The bad news gets lost. Lead with it if it's the headline. + +**Walls of text.** Too long, unread. Cut to the structure. + +**Activity vs outcome.** "Met with team. Reviewed plan. Updated tickets." So what? "Cut scope to hit launch date" is an outcome. + +**Different update for every audience.** Maintaining 5 versions doubles work. Have one core update; tailor the framing. + +**Status update that's actually a request.** Buries an ask in a wall of status. Pull the ask out. Make it visible. + +**Optimistic projections.** "We'll be back on track next week." Then we're not. Then again. Trust erodes. Be honest about the path. + +**No follow-up on asks.** Asked for a decision; didn't get one; moved on. Now the project is stuck. Follow up. + +**Communicating bad news only when forced to.** Stakeholders find out from someone else, or from a missed deadline. Lose trust. Communicate proactively. + +**Performative comms for the audience of one.** Every update reads like a sales pitch to the boss. Stakeholders see through it. Be direct. + +**No comms when no news.** Silence is worse than "no change this week." Set expectations on cadence and stick to it. + +--- + +## Output format + +A communication plan for a project includes: + +- **Stakeholder map:** named people, their interests, their decision rights +- **Cadence:** what updates go to whom, how often +- **Templates:** standardized formats for repeated updates +- **Escalation paths:** who to involve when something's at risk +- **Decision log:** running record of decisions made, by whom, why + +For individual communications: + +- **Headline:** the takeaway +- **Body:** the supporting structure +- **Ask:** the request, explicitly +- **Distribution:** who gets it, in what form + +--- + +## Reference files + +- [`references/update-templates.md`](references/update-templates.md): Ready-to-use templates for the most common stakeholder communications, with annotated examples. diff --git a/skills/stakeholder-communication/references/update-templates.md b/skills/stakeholder-communication/references/update-templates.md new file mode 100644 index 0000000..70d88d4 --- /dev/null +++ b/skills/stakeholder-communication/references/update-templates.md @@ -0,0 +1,452 @@ +# Update Templates + +Ready-to-use templates for the most common stakeholder communications. Annotated with what each section is doing. + +Adapt to your house style. The structure matters more than the exact wording. + +--- + +## Template 1: Weekly project status + +For internal teams, manager, sponsor. Sent same day each week. + +``` +Subject: [Project] weekly update: [date] + +**Status: On track** + +We're on plan to ship [milestone] by [date]. + +This week: +- Shipped [specific outcome] +- Started [specific work], [N]% complete +- Decision: chose [option] for [problem] + +Next week: +- Complete [specific work] +- Begin [specific work] +- Review: [decision needed by sponsor] + +Risks: +- [Risk]: [what we're doing about it] + +Asks: +- [Specific ask, if any] + +Detail: [link to project doc] +``` + +**Annotations:** +- Status indicator (On track / At risk / Off track) is the first thing readers scan +- "This week" is outcomes, not activities +- "Next week" is specific commitments, not vague intentions +- Risks have plans attached +- Asks are explicit and called out + +--- + +## Template 2: At-risk update + +When the project is no longer comfortably on track. + +``` +Subject: [Project] update: at risk for [milestone] + +**Status: At risk** + +The [milestone] target of [date] is at risk because [specific reason]. + +What's happening: +- [Fact 1] +- [Fact 2] +- [Fact 3] + +Impact: +- If we miss by a week: [specific impact] +- If we miss by a month: [specific impact] + +What we're doing: +- [Action 1] (owner: [name], by: [date]) +- [Action 2] (owner: [name], by: [date]) + +What we need from you: +- [Specific decision or help] + +Next update: [date] +``` + +**Annotations:** +- Doesn't pretend to be on track +- Names the specific cause +- Quantifies the impact +- Has a plan with owners and dates +- Has a clear ask +- Sets expectations for next update + +--- + +## Template 3: Off-track / missed milestone + +When the milestone has been missed or will be. + +``` +Subject: [Project] off track: [milestone] will miss [date] + +**Status: Off track** + +We will miss the [date] milestone for [specific reason]. Revised target: [new date]. + +What happened: +[2-3 sentences of what specifically caused the miss. Direct, no euphemisms.] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we're doing: +- [Action 1] +- [Action 2] + +Lessons we're applying: +- [Lesson learned] + +What we need: +- [Specific ask, if any] + +Next milestone: [date for the next checkpoint] +``` + +**Annotations:** +- States the miss in the headline +- Names cause without scapegoating +- Quantifies impact +- Has a plan +- Includes lessons (shows learning, builds trust) +- Sets the next checkpoint + +--- + +## Template 4: Decision request + +When you need a decision from a stakeholder. + +``` +Subject: Decision needed: [decision] by [date] + +**The decision:** [What needs to be decided] + +**Context (60 seconds):** +[The minimum needed for someone to understand. Include only what's relevant.] + +**Options:** + +Option A: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option B: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option C: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +**Recommendation:** Option [X], because [reason]. + +**Need by:** [Date] + +**Detail:** [Link to fuller analysis] +``` + +**Annotations:** +- The decision is named at the top +- Context is bounded (60 seconds) +- Options are parallel in structure +- Recommendation is explicit +- Deadline is named + +--- + +## Template 5: Executive review + +For exec audiences: monthly, quarterly, or per major milestone. + +``` +Subject: [Initiative] exec review: [date] + +**Headline:** [One-sentence summary of the state of things] + +**Key points:** + +1. [Point 1 with one supporting sentence] +2. [Point 2 with one supporting sentence] +3. [Point 3 with one supporting sentence] + +**Metrics:** + +| Metric | Target | Actual | Trend | +|---|---|---|---| +| [Metric 1] | [Target] | [Actual] | ↑/↓/→ | +| [Metric 2] | [Target] | [Actual] | ↑/↓/→ | +| [Metric 3] | [Target] | [Actual] | ↑/↓/→ | + +**Decisions needed:** +- [Decision 1: brief context, options summary, recommendation] +- [Decision 2: brief context, options summary, recommendation] + +**Risks:** +- [Top risk and mitigation] + +**Asks:** +- [Specific ask] + +**Detail:** [Link to fuller documentation] +``` + +**Annotations:** +- Executives skim. Headline carries the load. +- 3 key points (not 7) +- Metrics in table form, with trend +- Decisions called out, with recommendations +- Detail is linked, not inlined +- One page max for the email body + +--- + +## Template 6: Launch announcement (internal) + +For announcing something shipped. + +``` +Subject: Launched: [Thing] + +We've launched [Thing]. + +What it is: +[1-2 sentences of plain description. What it does, who it's for.] + +Why it matters: +[1-2 sentences of impact. What problem it solves, what changes.] + +How to learn more: +- [Link to docs / demo / page] +- [Contact for questions] + +Thanks to: +[The team that did the work, by name] +``` + +**Annotations:** +- Short and clear +- Includes the why (not just the what) +- Acknowledges the team + +--- + +## Template 7: Asking for help + +When you need expertise, time, or introduction from a colleague. + +``` +Subject: [Specific ask]: [N] minutes + +Hi [Name], + +I'm working on [brief context, one sentence]. I'd value your help with [specific ask]. + +What I need: +- [Specific item 1] +- [Specific item 2] + +What I've already tried: +- [Approach 1, outcome] +- [Approach 2, outcome] + +Time I'm asking for: [N minutes / specific session / specific deliverable] +Need by: [Date or "no rush"] + +If you're not the right person, who would you suggest? + +Thanks, +[Name] +``` + +**Annotations:** +- Subject is specific +- Specific ask, not vague +- Shows you've tried (respect for their time) +- States time required +- Provides an out (suggest someone else) + +--- + +## Template 8: Update for skip-level / VP + +For your manager's manager. Shorter, sharper than direct-manager update. + +``` +Subject: [Initiative]: quick update + +[Initiative] is [on track / at risk] for [milestone]. + +Highlights: +- [Outcome 1] +- [Outcome 2] +- [Decision: what was decided] + +What's coming: +- [Next big milestone] + +Risks I'm watching: +- [Top risk] + +I'll come to you for: [specific upcoming need] + +Detail: [link] +``` + +**Annotations:** +- Half the length of a manager update +- Emphasizes outcomes, not activities +- "I'll come to you for" sets expectations on when you'll need them +- Detail is linked, not inlined + +--- + +## Template 9: Quarterly business review (QBR) + +Cross-functional, leadership audience. Substantive. + +``` +Subject: [Function/team] QBR: Q[N] + +**Quarter at a glance:** + +[3-sentence narrative summarizing the quarter] + +**Goals vs results:** + +| Goal | Target | Result | Status | +|---|---|---|---| +| [Goal 1] | [Target] | [Result] | ✅ / 🟡 / ❌ | +| [Goal 2] | [Target] | [Result] | ✅ / 🟡 / ❌ | +| [Goal 3] | [Target] | [Result] | ✅ / 🟡 / ❌ | + +**Wins this quarter:** +- [Specific win 1] +- [Specific win 2] +- [Specific win 3] + +**What didn't go as planned:** +- [Specific miss 1: what happened, what we learned] +- [Specific miss 2: what happened, what we learned] + +**Next quarter:** +- [Top priority 1] +- [Top priority 2] +- [Top priority 3] + +**Risks and asks:** +- [Risk and what we're doing] +- [Ask if any] + +**Headcount / budget changes:** +[If relevant, brief] +``` + +**Annotations:** +- Narrative summary up front +- Goals table with clear pass/fail +- Wins AND misses (honest) +- Forward-looking section +- Asks are explicit + +--- + +## Template 10: Bad news, broader audience + +For when something significant has gone wrong and a wider audience needs to know. + +``` +Subject: [Plain description of what happened] + +[1 sentence: what happened, in plain language] + +What happened: +[2-4 sentences of specific facts. No euphemisms.] + +Who's affected: +- [Specific group 1] +- [Specific group 2] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we've done so far: +- [Action 1] +- [Action 2] + +What's next: +- [Action and timeline] +- [Action and timeline] + +If you have questions: +[Contact and channel] + +[Sign-off from named accountable person, with their role] +``` + +**Annotations:** +- Plain subject. No spin. +- Facts before reassurance +- Impact stated, not hedged +- Forward path is clear +- Named accountable person at the bottom +- Channel for questions + +--- + +## What to avoid in any template + +**Vague status indicators.** "Things are going well" is not status. On track / at risk / off track is. + +**Activity dumps.** "We met. We reviewed. We updated." Stakeholders care about what changed, not what you did. + +**Hedge words on certainty.** "We should probably maybe be on track." If you know, say it. If you don't, say what you don't know. + +**Buried asks.** Asks at the bottom in a paragraph go unread. Pull them out. Bold them. Make them findable. + +**Different units in different sections.** "5 days" in one place, "by next Tuesday" in another. Pick a convention and stick with it. + +**Acronyms not understood by the audience.** Especially across functions. Spell out on first use. + +**No links.** Detail in the email forces everyone to read the same wall of text. Link the detail. Let people choose. + +**Missing accountable owner.** Who owns each next step? If the answer is "the team," nothing happens. Name people. + +**Inconsistent cadence.** Update Monday, then nothing for three weeks, then a wall on a Friday. Set cadence. Hold it. + +--- + +## Customizing for your context + +The templates above are starting points. Customize for: +- Your organization's tone (formal vs casual) +- Your stakeholders' preferences (some want bullets, some want narrative) +- Your medium (email vs doc vs slide) +- Your project's complexity (more or less detail in the body) + +Whatever you customize, keep: +- Headline first +- Status indicator visible +- Asks explicit +- Owners and dates named +- Consistent structure across updates (so readers can scan reliably) diff --git a/skills/team-onboarding-playbook/SKILL.md b/skills/team-onboarding-playbook/SKILL.md new file mode 100644 index 0000000..180e5c4 --- /dev/null +++ b/skills/team-onboarding-playbook/SKILL.md @@ -0,0 +1,189 @@ +--- +name: team-onboarding-playbook +description: Design a structured onboarding experience that gets new team members productive in 30, 60, and 90 days. Use when a new hire is joining, when contractors or agency partners need to ramp up, when an existing team is restructuring and members are switching focus, or when current onboarding feels chaotic and slow. Also triggers when one person owns all the tribal knowledge and you need to capture it, when you keep losing people in their first 90 days, or when a new project has many fresh members joining at once. Useful for engineering, design, product, marketing, and operations roles. +category: process-and-team +catalog_summary: "30-60-90 onboarding plans for new hires and contractors" +display_order: 4 +--- + +A repeatable framework for building an onboarding playbook that ramps new team members predictably without burning out the people training them. + +## When to use + +- A new hire is joining and you do not have a written onboarding plan. +- An existing onboarding process is informal and inconsistent. +- A team is growing fast and onboarding is the bottleneck. +- A contractor or agency partner needs to ramp up quickly. +- A team member is leaving and their knowledge needs capturing. +- Onboarding currently takes too long and you want to reduce it. + +## When NOT to use + +- For ongoing performance management (different problem). +- For training on a specific technology (use targeted docs and tutorials). +- For documentation strategy in general (use `documentation-strategy`). +- For role definition or hiring (different upstream problem). + +## Required inputs + +- The role: what the person will do, what success looks like at 90 days. +- Existing artifacts: docs, runbooks, codebases, design files. +- The team: who will mentor, who will pair, who answers what kind of question. +- Tools and access: what accounts and systems the new person needs. +- Time budget: how much time team members can invest in onboarding. + +## The framework + +A good onboarding plan operates on 4 layers. Build all four. + +### Layer 1: Belonging (Day 1 to Week 1) + +The first week is mostly about belonging, not productivity. Get this right and everything else accelerates. + +- Welcome message before they start. +- Workspace and accounts ready before day 1. No "we will get to that". +- A buddy or onboarding partner assigned (someone other than the manager). +- Day 1 schedule that is not 8 hours of meetings, but is also not zero meetings. +- Introductions to the people they will work with regularly. +- A first-week rhythm: daily check-in with manager or buddy. + +### Layer 2: Context (Week 1 to Week 4) + +The next phase is context. The new person needs to understand the system before they can change it. + +- The product or business: what we do, who we serve, why we exist. +- The team: who owns what, how decisions get made. +- The technical or operational landscape: the architecture diagram, the main tools, the key files. +- The recent past: major decisions, recent launches, current priorities. +- Active projects: what is in flight and how it fits. + +A reading list is part of this. Keep it short. Annotated. Curated. + +### Layer 3: Contribution (Week 2 to Week 6) + +By week 2 or 3, the new person should be making real contributions. Not because they are fully ramped, but because contribution is how ramping happens. + +- A first task that is small, scoped, and shippable in week 2. +- Pairing or shadowing on a real piece of work in week 3. +- Independent ownership of a small project by week 4 or 5. +- Code review, design critique, or equivalent peer feedback from the start. + +The first task matters. Pick something that touches the main systems but cannot break anything important. Something that ships gives confidence and visibility. + +### Layer 4: Mastery (Month 2 to Month 3) + +By the end of 90 days, the new person should be a full member of the team. + +- Owning a project end to end. +- On-call or on-rotation if the team has one. +- Contributing to roadmap discussions, not just executing them. +- Mentoring or supporting the next new hire. + +90 days is a checkpoint, not a finish line. Document what worked and what was missing for the next person. + +## The 30/60/90 plan + +Every onboarding plan should have explicit milestones at 30, 60, and 90 days. + +### 30 days + +- Workspace, tools, and access fully set up. +- Has met every team member. +- Understands the product, the team, and the recent context. +- Has shipped or contributed to at least one real piece of work. +- Has a clear picture of their first major project or area. + +### 60 days + +- Owns a project or area independently. +- Knows where to find answers without asking every time. +- Has formed working relationships beyond the immediate team. +- Has made at least one meaningful improvement to a process, doc, or codebase. + +### 90 days + +- Fully productive in the role. +- Participating in roadmap and planning discussions. +- Capable of training the next new hire on parts of the system. +- Comfortable raising concerns and pushing back. + +If someone is significantly behind these markers at the 30/60/90 checkpoints, address it directly. Either the plan is wrong, the support is wrong, or the role fit is wrong. Hoping it resolves itself does not work. + +## The role-specific overlay + +The framework above applies to every role. The specifics differ. + +### Engineering + +- Day 1: dev environment running, first commit (a docs fix or trivial change). +- Week 1: read the architecture doc, read the main service code paths. +- Week 2: ship a small bug fix or refactor. +- Week 4: own a feature or component. +- Month 2: on-call shadow, then on-call. + +### Design + +- Day 1: design tools set up, design system access, brand guidelines reviewed. +- Week 1: studio crit and design review participation. +- Week 2: own a small surface (a setting page, an empty state). +- Week 4: lead a design review for a feature in flight. +- Month 2: own a feature design end to end. + +### Product + +- Day 1: read the strategy doc, the roadmap, and the latest 3 PRDs. +- Week 1: shadow customer calls, attend support sync, join standup of all relevant teams. +- Week 2: write a discovery doc or competitive analysis. +- Week 4: own a feature spec. +- Month 2: own a roadmap area. + +### Marketing or content + +- Day 1: brand voice doc, recent campaigns, top performing content. +- Week 1: customer research artifacts and persona docs. +- Week 2: ship a small piece of content (a social post, a blog edit). +- Week 4: own a content piece end to end. +- Month 2: own a campaign or channel. + +Adapt to your role and stack. The shape stays the same. + +## Workflow + +1. Start the playbook before the new person arrives. Do not write it on day 1. +2. Pre-stage accounts, hardware, and access. This is the most common day-1 failure point. +3. Assign a buddy. Tell the buddy what is expected of them. +4. Send the welcome message and the day-1 schedule before they start. +5. Run the first week with a focus on belonging and context, not output. +6. Check in daily for the first week, weekly for the first month. +7. Run formal 30/60/90 check-ins with explicit milestones. +8. After 90 days, do a retrospective: what worked, what was missing. +9. Update the playbook based on the retrospective. Onboarding is a living doc. + +## Failure patterns + +- **No plan.** Day 1 with no schedule, no laptop, no accounts. Sets a tone. +- **Drinking from a firehose.** 8 hours of meetings on day 1. People remember nothing. +- **No real work for too long.** Three weeks of "reading docs" is demoralizing. Ship something small early. +- **All buddy, no manager.** Buddies are great but cannot evaluate or advocate. Manager is still on the hook. +- **Tribal knowledge as gating.** "Just ask Sara if you have questions" works until Sara is on vacation. Document the answers Sara keeps giving. +- **No 30/60/90 milestones.** Onboarding "ends" when someone seems busy. That is not a milestone. +- **Generic plan for every role.** Engineering and marketing have different first-week needs. Use the role overlay. +- **No retrospective.** The same gaps catch every new hire because nobody updated the playbook. +- **Buddy with no time.** Assigning a buddy who is also drowning is a recipe for poor onboarding and burnout. Protect their time. +- **Skipping the customer or product context.** Engineers who do not know who the customer is build the wrong things. Marketers who do not know how the product works write thin copy. + +## Output format + +Deliverables: + +1. **Pre-day-1 checklist**: accounts, hardware, access, buddy assignment, welcome message. +2. **Day-1 schedule**: meeting list, intros, first deliverable. +3. **First-week reading list**: 5-10 curated, annotated docs. +4. **30/60/90 milestones**: the explicit checkpoints for this role. +5. **Buddy guide**: what is expected of the onboarding partner. +6. **Manager check-in cadence**: scheduled 1:1s and milestone reviews. +7. **Retrospective template**: to fill out at 90 days for next-time improvement. + +## Reference files + +- [`references/onboarding-checklist.md`](references/onboarding-checklist.md): A day-by-day, week-by-week checklist for the first 30 days, with role-specific variants and a 30/60/90 review template. diff --git a/skills/team-onboarding-playbook/references/onboarding-checklist.md b/skills/team-onboarding-playbook/references/onboarding-checklist.md new file mode 100644 index 0000000..c82acb7 --- /dev/null +++ b/skills/team-onboarding-playbook/references/onboarding-checklist.md @@ -0,0 +1,214 @@ +# Onboarding checklist + +A day-by-day, week-by-week checklist for the first 30 days. Adapt the role-specific items to fit your team. + +## Before day 1 (1 week ahead) + +Manager prep: + +- [ ] Confirm start date and any logistics (remote, hybrid, in-office). +- [ ] Assign onboarding buddy. Brief them on expectations. +- [ ] Order hardware. Confirm delivery before start date. +- [ ] Create accounts: email, chat, source control, design tools, project management, calendar, password manager. +- [ ] Add to relevant team channels and meeting invites. +- [ ] Block manager calendar for daily check-ins in week 1. +- [ ] Send welcome email to new hire 3-5 days before start. Include: day-1 logistics, what to expect, where to be, what to bring. +- [ ] Notify the team via channel: who is starting, when, what role. +- [ ] Prep first task. Something small, scoped, shippable in week 1 or 2. + +## Day 1 + +Morning: + +- [ ] Welcome from manager (30 min, not 90 min). +- [ ] Tour of tools, accounts, and where things live. +- [ ] Lunch with buddy or team (whatever is normal for your team). + +Afternoon: + +- [ ] Read the welcome doc or onboarding hub. +- [ ] Set up local environment. Buddy or buddy-channel available for help. +- [ ] First commit, design upload, doc edit, or equivalent. Trivial. Just to validate the workflow. + +End of day: + +- [ ] 15-minute check-in with manager. How did it go. + +## Week 1 + +Goals: belonging and basic context. Not productivity. + +- [ ] Daily 15-minute check-in with manager. +- [ ] 1:1 with buddy at least twice. +- [ ] Read the curated reading list (5-10 docs, no more). +- [ ] Meet with 5-7 people they will work with. 30 minutes each. Casual. +- [ ] Attend team standup and one team meeting (without obligation to contribute). +- [ ] Submit at least one trivial fix or improvement (typo, doc clarification, small refactor). +- [ ] Set up time tracking, expense, or admin systems if your org uses them. +- [ ] Confirm hardware, software, and access are all working. + +End of week 1: + +- [ ] Manager check-in: what is unclear, what felt wrong, what is missing. + +## Week 2 + +Goals: contributing to real work, even in a small way. + +- [ ] Pair with a teammate on a real task. Half day to a full day. +- [ ] Take ownership of the first small task. Should be shippable in 3-5 days. +- [ ] Attend customer call, support sync, or equivalent customer touchpoint. +- [ ] Read the recent decision log or major PRDs from the last 3 months. +- [ ] First contribution to standups: what they are working on. + +End of week 2: + +- [ ] Manager check-in: how is the first task going. What is blocking. What feels overwhelming. + +## Week 3 + +Goals: independent ownership starts. + +- [ ] Ship the first small task. +- [ ] Take on a slightly larger task. 1-2 weeks of work. +- [ ] Participate in code review, design critique, or equivalent. +- [ ] Meet with 3-5 cross-functional partners (PM ↔ Eng, Design ↔ PM, etc.). +- [ ] Begin to recognize patterns: "this is the third time someone asked X, where is that documented?" + +End of week 3: + +- [ ] Buddy check-in: how is the experience. What is the new hire stuck on that they will not raise to the manager. + +## Week 4 / 30-day mark + +Goals: validate the ramp is on track. + +- [ ] Complete the first medium-sized project or be visibly in flight. +- [ ] Have a working mental model of the product, team, and stack. +- [ ] Have at least one improvement filed (a doc fix, process suggestion, automation). +- [ ] Manager 30-day review (see template below). + +## 30-day review + +Manager runs this with the new hire, in 1:1, around day 30. + +``` +30-day review for [name] + +What is going well: +- [Two or three things] + +What is unclear or hard: +- [Two or three things] + +What I have shipped or contributed to: +- [List] + +What I want to be doing more of: +- [List] + +What I want help with: +- [List] + +Manager observations: +- [What you have noticed] + +Action items: +- [Specific things to address before 60-day mark] +``` + +The output of the 30-day review is honest signal. If the new hire is behind, the manager addresses the cause, not the symptom. If they are ahead, accelerate. + +## 60-day milestones + +By day 60: + +- [ ] Owning a project or area independently. +- [ ] Asking targeted questions, not "how does anything work" questions. +- [ ] Has working relationships outside the immediate team. +- [ ] Has been on customer or user calls if applicable. +- [ ] Has flagged at least one process improvement. +- [ ] 60-day review complete. + +## 90-day milestones + +By day 90: + +- [ ] Fully productive in the role at expected level. +- [ ] Participating in planning and roadmap discussions. +- [ ] On call or on rotation if the team has one. +- [ ] Capable of teaching parts of the system to a peer. +- [ ] Has identified gaps in onboarding from their perspective. +- [ ] 90-day review and onboarding retrospective complete. + +## 90-day onboarding retrospective + +Run this with the new hire at the end of 90 days. Capture the answers. Update the playbook. + +``` +What was great about your onboarding: +- [List] + +What was confusing or hard: +- [List] + +What was missing: +- [List] + +What you would have liked on day 1: +- [List] + +What you would change for the next person: +- [List] + +What you wish you had known earlier: +- [List] +``` + +The output of this retro feeds the next version of the playbook. Without this loop, every new hire faces the same gaps. + +## Role-specific first tasks + +Examples of good first tasks (shippable in week 1-2): + +### Engineering + +- Fix a small bug from the bug tracker (not customer-blocking, but real). +- Add a missing test or improve a flaky one. +- Update a deprecated API call in one place. +- Improve a developer doc that has been out of date. + +### Design + +- Audit a small part of the product against the design system. +- Design an empty state, error state, or settings sub-page. +- Update an outdated illustration or asset. +- Document a component that is in production but not in the design system. + +### Product + +- Write a competitive analysis on one feature area. +- Document a customer pain point heard in support. +- Update a stale PRD with current state. +- Write a one-pager on a roadmap item that needs sharper framing. + +### Marketing / Content + +- Edit and update a stale blog post. +- Audit recent campaign performance and write a 1-page summary. +- Repurpose an existing piece of content into a new format. +- Write a short customer quote roundup or testimonial summary. + +The pattern: real, scoped, ships in days, low risk, builds context. + +## What "fully ramped" looks like + +A new hire is fully ramped when: + +- They no longer ask "how does this work" but "why was it built this way". +- They contribute to direction, not just execution. +- They identify gaps and fill them without being asked. +- They mentor or assist the next new hire. +- They push back on things that do not make sense. + +This usually lands somewhere between 90 and 180 days, depending on the role and the system's complexity. Track it. If 180 days passes and the person is still not at this bar, dig into why. diff --git a/skills/upgrade-flow-design/SKILL.md b/skills/upgrade-flow-design/SKILL.md new file mode 100644 index 0000000..da26f0f --- /dev/null +++ b/skills/upgrade-flow-design/SKILL.md @@ -0,0 +1,309 @@ +--- +name: upgrade-flow-design +description: "Designing free-to-paid conversion flows for SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. Honest about paywall-everywhere (gates everything aggressively), free-forever-trap (no upgrade path surfaces), and value-triggered-upgrade (paywall surfaces at moments of demonstrated value) patterns. Triggers on upgrade flow, paywall, free-to-paid, freemium conversion, trial conversion, plan upgrade, subscription upgrade, win-back flow, churn prevention. Also triggers when free-to-paid conversion is low, when paywalls are blocking the wrong moments, or when upgrade flows are being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing free-to-paid conversion flows. Distinguishes paywall-everywhere (gates everything aggressively) from free-forever-trap (no upgrade path surfaces) from value-triggered-upgrade (paywall surfaces at moments of demonstrated value)" +display_order: 9 +--- + +# Upgrade Flow Design + +A senior product marketing director's playbook for designing free-to-paid conversion flows in SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. The discipline of asking for the upgrade at the moment the user has a reason to say yes. + +Most upgrade flows fail in one of two ways. They block meaningful product use behind paywalls so aggressively that users churn before reaching the moment that would justify paying. Or they offer a generous free tier with no upgrade path that ever surfaces; users get everything they need; conversion stays at single-digit percentages indefinitely. + +The upgrade flows that work do something different. They surface paywalls at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next; the user is positioned to say yes because the value is fresh. + +The voice is the senior product marketing director who has watched conversion rates double when paywalls were re-timed and watched them collapse when more aggressive paywalls were added. Practical, opinionated about the moments that earn the upgrade ask, willing to call out when the product's free tier is too generous to convert. + +When to use this skill: scoping a free-to-paid conversion flow for the first time, auditing paywalls that block conversion or never surface, designing the trigger moments that earn upgrade asks, or deciding plan structure that supports upgrades over time. + +--- + +## What this skill covers + +This skill spans free-to-paid conversion flows in SaaS products. The growth-tooling distinctions: + +- `lead-magnet-design` is top-of-funnel email capture. This skill is free-to-paid conversion in-product. +- `funnel-flow-architecture` is the cross-tool funnel architecture. This skill is the upgrade flow specifically. +- **`upgrade-flow-design` (this skill)** is trigger-moment design, paywall presentation, plan structure, win-back, churn prevention. +- `landing-page-copy` is pricing-page copy; lives downstream of this skill's plan-structure decisions. +- `pm-spec-writing` is the spec for engineers building the upgrade flow. + +The audience: product marketers, growth marketers, in-house product teams, agencies running SaaS conversion work for clients. + +Out of scope: cross-funnel architecture (covered by `funnel-flow-architecture`); pricing-page copy (covered by `landing-page-copy`); the engineering implementation; specific Stripe/Chargebee/Recurly/Paddle billing-platform configurations (those stay implementation-side). + +--- + +## The free-tier decision: freemium vs free-trial vs no-free + +Before designing the upgrade flow, decide the free-tier structure. + +**Freemium (free-forever tier).** + +- Users use the product indefinitely without paying. +- Paid tier offers more value (capacity, features, support). +- Conversion typically 2-5 percent; volume compensates. + +When it works: products with strong network effects, or where free users provide product value (data, content, virality). + +**Free-trial (time-limited).** + +- Users get full or near-full product for a defined period. +- After trial, must pay to continue. +- Conversion typically 10-25 percent of trial signups. + +When it works: products where the value is clear quickly; audiences willing to commit time before paying. + +**Reverse trial.** + +- Users start on paid plan; auto-downgrade to free after period. +- Less common; mixes signals; can produce surprise churn. + +**No-free (paid-only).** + +- No free tier; users pay to start. +- Conversion is from prospects rather than free users. +- Conversion rates depend on sales motion, not in-product upgrade flows. + +When it works: enterprise products, high-touch sales, products where free would dilute brand or capacity. + +The decision is upstream of upgrade flow design. Different free-tier structures warrant different upgrade flows. + +Detail in [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md). + +--- + +## Paywall-everywhere vs free-forever-trap vs value-triggered-upgrade + +The keystone framing. + +**Paywall-everywhere.** Paywall blocks meaningful product use. Free tier exists but is too constrained to demonstrate value. Users churn before reaching the moment that would justify paying. Cost: users who would have paid after seeing value never reach that moment; conversion suffers despite aggressive paywalling. + +**Free-forever-trap.** Generous free tier with no upgrade path that ever surfaces. Users get everything they need; never see why they would pay. Conversion rate stays at single-digit percentages indefinitely. Cost: the team has built a product users like for free; revenue does not follow because the upgrade ask never lands. + +**Value-triggered-upgrade.** Paywall surfaces at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next. Cost: design effort upfront is significant; conversion typically meaningfully higher than either alternative. + +The litmus test. After a user encounters the upgrade flow, can they articulate why they should pay? "Because I just hit my limit on this feature I have used 200 times" is value-triggered. "Because the product told me to pay before letting me use it" is paywall-everywhere. "I have not seen an upgrade ask" is free-forever-trap. + +--- + +## Trigger-moment design: where paywalls earn their interruption + +The single most consequential decision in upgrade flow design. + +**The principle.** Paywalls surface at moments where the user has demonstrated they are getting the product's value. The interruption is justified because the user has a reason to say yes. + +**Strong trigger moments.** + +- **Usage threshold reached.** User has used a feature N times; further use requires paid plan. Honest because they are clearly getting value. +- **Capacity limit hit.** User has reached free-tier capacity; upgrade unlocks more. Predictable; expected. +- **Advanced feature attempted.** User clicked into a feature that requires paid plan. Interest is fresh. +- **Workflow completed successfully.** User has seen value through a completed action; upgrade ask connects that value to recurring access. +- **Team-collaboration moment.** User wants to invite teammates; team capabilities require paid plan. +- **Time-trial ending.** Trial-based products surface upgrade as trial nears end. + +**Weak trigger moments.** + +- **First-login.** User has not yet seen value; upgrade ask is premature. +- **Random in-product placement.** Paywall on the dashboard with no specific trigger; users dismiss. +- **Every-page banner.** Persistent upgrade banner across all surfaces; users develop blindness. + +**The discipline.** Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +Detail in [`references/trigger-moment-design.md`](references/trigger-moment-design.md). + +--- + +## Paywall presentation: modal vs banner vs inline + +How the paywall surfaces. + +**Pattern A: Modal paywall.** Full-screen overlay blocks the action; user must upgrade or dismiss. + +When to use. Capacity limits, feature gates the user has hit. The interruption is warranted by the trigger. + +**Pattern B: Banner paywall.** Persistent banner at top of page suggesting upgrade. + +When to use. Soft prompts; awareness without interruption. Risk of becoming visual noise. + +**Pattern C: Inline paywall.** Upgrade ask embedded in the surface where the trigger occurred. + +When to use. Contextual prompts that integrate with the workflow. + +**Pattern D: Toast or notification.** Brief paywall surfaced as a notification. + +When to use. Soft prompts; low-priority upgrade asks. + +**Choice criteria.** + +- The trigger's strength determines the presentation's intensity. +- Strong triggers (capacity hit, feature gate) warrant modal. +- Soft triggers (general awareness) warrant inline or toast. + +**Copy and value-prop discipline.** + +- The paywall copy should connect to what the user just did. +- "You have used [feature] 50 times. Upgrade to remove the limit and unlock [related capabilities]." matches the trigger. +- "Upgrade for more features" is generic and weak. + +Detail in [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md). + +--- + +## Upsell vs downsell logic + +When the user does not accept the primary upgrade. + +**Upsell.** User is on basic plan; ask them to upgrade to higher tier. + +**Cross-sell.** User is paying; offer add-ons or related products. + +**Downsell.** User declined the higher tier; offer a smaller commitment (smaller plan, monthly vs annual, basic vs full feature set). + +**The downsell discipline.** Some users will not upgrade to the proposed tier but will upgrade to something. Downsell captures revenue otherwise lost. + +**Examples.** + +- User declined Pro upgrade; offer Starter plan as a path to begin paying. +- User declined annual plan; offer monthly with explicit cost difference disclosed. +- User declined full team plan; offer single-seat upgrade. + +**Anti-pattern.** Aggressive downsell that makes the user feel manipulated. Honest framing: "If Pro is more than you need, here is something that fits." + +Detail in [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md). + +--- + +## Win-back flow design + +Lapsed users, downgrades, partial-churn. + +**Win-back triggers.** + +- User has not logged in for 30/60/90 days. +- User downgraded plan. +- User canceled but did not delete account. +- User churned and signed up again later. + +**Win-back patterns.** + +- **Email-based.** Outreach with renewed value-prop, sometimes with discount or trial extension. +- **In-product upon return.** When the lapsed user returns, surface re-engagement help and (if appropriate) an upgrade-back ask. +- **Personal outreach.** For high-value lapsed users, sales or customer success conversation. + +**Discount discipline.** + +- Discounts to win back can create reverse-incentive (user churns to get discount). +- Discount sparingly; emphasize new value first. + +Detail in [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md). + +--- + +## Churn prevention upstream of upgrade + +The best upgrade flow is the one the user does not need because they did not churn. + +**Upstream churn signals.** + +- Declining engagement; sessions per week dropping. +- Last login distant. +- Support ticket pattern (frustration signals). +- Plan downgrade interest signals. + +**Prevention patterns.** + +- **Engagement re-orientation.** Surface help when engagement drops. +- **Outreach.** Customer success contact for high-value accounts at risk. +- **Friction reduction.** Audit the reasons users disengage; fix the friction. + +**The prevention-vs-recovery economics.** Preventing churn is much cheaper than winning back churned users. Invest upstream. + +Detail in [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md). + +--- + +## Plan structure: tier count, feature gating, pricing-page design + +The plans that the upgrade flow leads to. + +**Tier count.** + +- 2-tier (Free + Paid): simple; clear upgrade path; works for many products. +- 3-tier (Starter + Pro + Enterprise): broader audience; harder to design. +- 4+ tier: rarely better; complexity confuses users. + +**Feature gating.** + +- **Capacity-based.** Free tier limited by use volume; paid unlocks more. +- **Feature-based.** Free tier missing specific features; paid unlocks them. +- **Hybrid.** Both capacity and features differ. + +**Discipline.** Each tier should have a clear "this is for [X audience] because of [Y]." Tiers without clear audience-fit produce weak conversions. + +**Pricing-page design.** The pricing page is downstream of plan structure but lives close to upgrade flow. Detail in `landing-page-copy` for pricing-page copy specifically. + +Detail in [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md). + +- "Conversion rate is low; users churn before reaching upgrade." Paywall-everywhere; gates blocking value demonstration. +- "Conversion rate is single-digit; free users use the product for years." Free-forever-trap; no upgrade path surfaces. +- "Paywall fires; users dismiss; conversion does not lift." Trigger moments wrong; paywall not connected to demonstrated value. +- "Users hit paywall and churn." Wrong moment; paywall blocks before value is fresh. +- "Upgrade rate looks fine; downgrade rate is high." Plan structure wrong; users upgrade then realize they did not need the higher tier. +- "Win-back attempts have low conversion." Re-engagement timing wrong, or value-prop unchanged from what failed initially. +- "Annual plans not converting; monthly plans dominate." Annual value-prop weak; or commitment friction too high. +- "Sales says many leads come from churned users coming back." Win-back working but the previous churn was avoidable; audit upstream. +- "Conversion did not change after we redesigned the paywall." Paywall design was not the problem; trigger or plan structure may be. + +--- + +## The framework: 12 considerations for upgrade flow design + +When designing or auditing an upgrade flow, walk these 12 considerations. + +1. **The free-tier decision.** Freemium, free-trial, reverse trial, or no-free. +2. **Value-triggered-upgrade, not paywall-everywhere or free-forever-trap.** Paywalls at moments of demonstrated value. +3. **Trigger-moment design sound.** Paywalls connect to specific user-demonstrated value. +4. **Paywall presentation matches trigger intensity.** Strong triggers warrant modal; soft triggers inline. +5. **Copy connects to the trigger.** Specific value-prop tied to what the user just did. +6. **Upsell, cross-sell, downsell logic.** When primary upgrade is declined, secondary paths exist. +7. **Win-back flows designed.** Lapsed users have a clear re-engagement path. +8. **Churn prevention upstream.** Upstream signals trigger prevention; downstream upgrade flow is one of multiple defenses. +9. **Plan structure clear.** Tier count appropriate; each tier has clear audience-fit. +10. **Pricing-page coordinates with upgrade flow.** Plan structure decisions reflected on the pricing page. +11. **Conversion as success metric.** Not just paywall display; downstream conversion to paid. +12. **Maintenance discipline.** Plans, paywalls, win-back flows updated alongside product and pricing changes. + +The output of the framework is an upgrade flow that earns the user's "yes" by asking at the moment the user has a reason to say yes, with plan structure that fits the audience the product serves. + +--- + +## Reference files + +- [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md) - Freemium, free-trial, reverse trial, no-free. Choice criteria. +- [`references/trigger-moment-design.md`](references/trigger-moment-design.md) - Where paywalls earn their interruption. Strong vs weak trigger moments. +- [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md) - Modal, banner, inline, toast. Copy and value-prop discipline. +- [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md) - When primary upgrade is declined, secondary paths. +- [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md) - Lapsed users, downgrades, partial-churn re-engagement. +- [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md) - Preventing churn before the upgrade flow is needed. +- [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md) - Tier count, feature gating, audience-fit per tier. +- [`references/upgrade-flow-anti-patterns.md`](references/upgrade-flow-anti-patterns.md) - The patterns that look like upgrade flows but degrade trust. +- [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: upgrade flows earn revenue when they earn the user's yes + +The upgrade flows that compound revenue are the ones that ask at the moment the user has a reason to say yes. Not because the paywall blocked them. Not because the upgrade prompt happened to appear. Because the user just did something that demonstrated value, and the upgrade ask connected that value to continued or expanded access. + +That is the bar. Below the bar are paywall-everywhere (gates before value, conversion suffers) and free-forever-trap (no upgrade path, conversion never starts). Above the bar are value-triggered-upgrade flows where trigger-moment design, paywall presentation, plan structure, win-back, and churn prevention work together to convert the right users at the right moments. + +The discipline is in the design choices. The free-tier decision (freemium, trial, paid-only) sets the funnel shape. Trigger-moment design decides when paywalls earn their interruption. Paywall presentation decides how the ask lands. Plan structure decides what the user is upgrading to. Win-back and churn prevention catch the cases that escaped the primary upgrade flow. diff --git a/skills/upgrade-flow-design/references/churn-prevention-upstream.md b/skills/upgrade-flow-design/references/churn-prevention-upstream.md new file mode 100644 index 0000000..d20876e --- /dev/null +++ b/skills/upgrade-flow-design/references/churn-prevention-upstream.md @@ -0,0 +1,250 @@ +# Churn prevention upstream + +Preventing churn before the upgrade flow is needed. + +The best upgrade flow is the one the user does not need because they did not churn. Investing upstream of churn produces more revenue than recovering churned users. + +--- + +## The prevention-vs-recovery economics + +Preventing churn is much cheaper than winning back churned users. + +**The math.** Cost of preventing one churn (engagement program, support intervention, friction reduction): X. Cost of winning back one churned user (outreach, discount, re-acquisition): often 3-10X. + +**The implication.** Programs that detect churn risk early and intervene save more revenue than win-back programs that activate only after churn. + +The discipline. Build upstream signals; intervene before churn happens. + +--- + +## Upstream churn signals + +What predicts churn. + +**Engagement decline.** + +- Sessions per week dropping over 4-week period. +- Time-in-product per session declining. +- Feature usage breadth narrowing. + +**Engagement gap.** + +- Last login distant. +- Specific feature stopped being used. +- Days since last meaningful action. + +**Support pattern.** + +- Support tickets indicating frustration. +- Multiple unresolved issues. +- Tone shift in support conversations. + +**Plan-related signals.** + +- Asked about cancellation. +- Researched competitors (sometimes detectable through partner data). +- Downgrade interest. + +**Team-level signals (B2B).** + +- Champion left the company. +- Team reduced seats internally. +- Decision-maker became unresponsive. + +The signals combine. Single signals are noisy; combinations predict more reliably. + +--- + +## Detection systems + +How to know which users are at risk. + +**Engagement scoring.** Composite score based on usage signals; threshold for at-risk classification. + +**Health scores.** Often used by customer success teams; combines product engagement, support pattern, contract data. + +**Predictive models.** Statistical or ML models that predict churn probability per user. + +**Manual flags.** Account managers flag accounts they sense are at risk. + +The discipline. Detection should be operationalized; signals should fire alerts to teams who can act. + +--- + +## Intervention patterns + +What to do when at-risk users surface. + +**Pattern A: Engagement re-orientation.** + +How it works. In-product help surfaces when engagement drops. Re-orients the user to value. + +When to use. Soft signals; users who may have forgotten what the product does for them. + +**Pattern B: Outreach.** + +How it works. Customer success or sales reaches out to at-risk accounts. + +When to use. High-value accounts; B2B contexts where personal touch matters. + +**Pattern C: Friction reduction.** + +How it works. Audit reasons users disengage; fix the friction. Often product changes rather than outreach. + +When to use. When patterns of disengagement reveal product issues. + +**Pattern D: Educational re-engagement.** + +How it works. Send the user content (case study, advanced feature explanation) that re-anchors value. + +When to use. Soft re-engagement; cheap to scale. + +**Pattern E: Plan adjustment.** + +How it works. If usage shows the user is over-paying, suggest a downgrade. Counterintuitive but builds trust. + +When to use. When the user is genuinely on the wrong plan; saves the relationship. + +--- + +## The engagement-re-orientation pattern + +In-product help that surfaces when engagement drops. + +**Implementation.** + +- Trigger fires when engagement signal drops below threshold. +- In-product surface shows: "It looks like you have not used [specific feature] in a while. Here is how others use it." +- Optional brief tour or case study. + +**Strengths.** + +- Cheap. +- Scalable. +- Often catches users who simply forgot. + +**Weaknesses.** + +- May feel intrusive. +- Cannot address all reasons for disengagement. + +--- + +## The customer success outreach pattern + +Personal contact for high-value accounts. + +**Implementation.** + +- Health score crosses at-risk threshold. +- Account manager or CS lead reaches out. +- Conversation: what is happening, what would help, can we address. + +**Strengths.** + +- Highest engagement potential. +- Surfaces real reasons. +- Builds relationship. + +**Weaknesses.** + +- Expensive. +- Only viable for accounts above revenue threshold. + +--- + +## The friction-reduction pattern + +Fixing the underlying reason rather than just intervening per user. + +**Implementation.** + +- Audit common reasons for disengagement. +- Identify product changes that would address. +- Ship the changes. + +**Strengths.** + +- Compounds across all users. +- Often the highest-impact intervention. + +**Weaknesses.** + +- Slower; requires product team prioritization. +- Some friction reasons cannot be product-fixed (audience-fit issues). + +--- + +## The educational-re-engagement pattern + +Send content that re-anchors value. + +**Implementation.** + +- Email or in-product content showing case studies, advanced features, or use cases. +- Targeted to the user's profile. + +**Strengths.** + +- Cheap and scalable. +- Educates without demanding immediate action. + +**Weaknesses.** + +- Lower engagement than personal outreach. +- May feel like marketing. + +--- + +## When intervention has limits + +Not all churn can be prevented. + +**Genuinely unfit users.** Some users signed up but are not the right audience. Their churn is appropriate. + +**Genuinely changed needs.** User changed jobs; product no longer relevant. Cannot be retained. + +**Genuinely better alternatives.** Competitor genuinely better fit. Recovery may not be appropriate. + +**The honest assessment.** Recognizing unpreventable churn is part of the discipline. Intervention should focus on preventable churn. + +--- + +## Churn prevention vs upgrade flow + +Different problems; complementary disciplines. + +**Churn prevention.** Keeps users engaged; avoids churn. + +**Upgrade flow.** Converts engaged users to paid (or higher paid). + +**The interaction.** Strong churn prevention produces engaged users; engaged users are the audience for upgrade flow. Programs running both produce more revenue than either alone. + +--- + +## Common prevention failures + +**No detection.** Churn happens; nobody flagged it; recovery is the only option. + +**Detection without intervention.** Signals fire but nobody acts. + +**Intervention timing wrong.** Action too late; user already disengaged emotionally. + +**Generic intervention.** Same outreach to all at-risk users; no segmentation. + +**Discount-led intervention.** Lead with discount instead of value; trains discount-seeking behavior. + +**Prevention misses fixable friction.** Patterns of disengagement reveal product issues; team focuses on per-user intervention instead. + +**No measurement.** Cannot tell if prevention reduces churn rate. + +--- + +## Methodology-level choices that stay in the public skill + +The prevention-vs-recovery economics. Upstream churn signals (5 categories). Detection systems. Intervention patterns A through E. When intervention has limits. Churn prevention vs upgrade flow interaction. Common failures. + +## Implementation choices that stay internal + +Specific signals and thresholds for specific products. Specific health-score formulas. Specific intervention copy and protocols. The team's CS staffing model. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/common-upgrade-failures.md b/skills/upgrade-flow-design/references/common-upgrade-failures.md new file mode 100644 index 0000000..bdc5116 --- /dev/null +++ b/skills/upgrade-flow-design/references/common-upgrade-failures.md @@ -0,0 +1,179 @@ +# Common upgrade failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Conversion rate is low; users churn before reaching upgrade." + +**The diagnosis.** Paywall-everywhere; gates blocking value demonstration. + +**The cure.** Loosen free tier. Surface paywalls at moments of demonstrated value. Detail in `references/trigger-moment-design.md`. + +--- + +## "Conversion rate is single-digit; free users use the product for years." + +**The diagnosis.** Free-forever-trap; no upgrade path surfaces. + +**The cure.** Add value-triggered paywalls. Connect upgrade asks to demonstrated value. + +--- + +## "Paywall fires; users dismiss; conversion does not lift." + +**The diagnosis.** Trigger moments wrong; paywall not connected to demonstrated value. + +**The cure.** Audit trigger logic. Each paywall should answer "what value did the user just demonstrate?" + +--- + +## "Users hit paywall and churn." + +**The diagnosis.** Wrong moment; paywall blocks before value is fresh. + +**The cure.** Move paywalls to moments of demonstrated value, not pre-value moments. + +--- + +## "Upgrade rate looks fine; downgrade rate is high." + +**The diagnosis.** Plan structure wrong; users upgrade then realize they did not need the higher tier. + +**The cure.** Clarify tier audiences. Each plan should have specific audience-fit. Detail in `references/plan-structure-patterns.md`. + +--- + +## "Win-back attempts have low conversion." + +**The diagnosis.** Re-engagement timing wrong, or value-prop unchanged from what failed initially. + +**The cure.** Lead with value-prop change. Avoid discount-only win-back. Detail in `references/win-back-flow-patterns.md`. + +--- + +## "Annual plans not converting; monthly plans dominate." + +**The diagnosis.** Annual value-prop weak; or commitment friction too high. + +**The cure.** Strengthen annual value (better discount, additional features). Reduce commitment friction (easier mid-year cancellation, prorated refunds). + +--- + +## "Sales says many leads come from churned users coming back." + +**The diagnosis.** Win-back working but the previous churn was avoidable; audit upstream. + +**The cure.** Invest in churn prevention upstream. Detail in `references/churn-prevention-upstream.md`. + +--- + +## "Conversion did not change after we redesigned the paywall." + +**The diagnosis.** Paywall design was not the problem; trigger or plan structure may be. + +**The cure.** Test variables that matter. Trigger moment, plan structure, value-prop copy. Paywall presentation alone often does not move the needle. + +--- + +## "Upgrade flow works for new users; existing users do not upgrade." + +**The diagnosis.** Triggers designed for new-user behavior; existing users do not hit them. + +**The cure.** Segment trigger logic. Existing users may need different triggers (feature-launch upgrades, capacity-growth upgrades). + +--- + +## "Conversion increased but new customer churn climbed." + +**The diagnosis.** Paywall too aggressive; converting users who do not see value. + +**The cure.** Audit conversion-to-retention correlation. Aggressive conversion may produce buyer's remorse. + +--- + +## "Users complain about hidden charges after upgrade." + +**The diagnosis.** Pricing not transparent; users surprised by total cost. + +**The cure.** Surface all costs upfront. Annual price, monthly price, taxes if applicable. Hidden costs damage trust. + +--- + +## "Cancellation rate spikes 3 months after upgrade." + +**The diagnosis.** Upgrade was made but value did not materialize; users gave it 3 months and left. + +**The cure.** Post-upgrade welcome and onboarding. Surface paid features; help users access value of paid plan. + +--- + +## "Different audience segments convert at different rates; we cannot tell why." + +**The diagnosis.** Per-segment data not tracked. + +**The cure.** Per-segment conversion analytics. Different segments may need different upgrade flows. + +--- + +## "Win-back outreach has unsubscribe rate climbing." + +**The diagnosis.** Outreach too frequent or generic. + +**The cure.** Segment outreach. Respect non-response. Reduce frequency. + +--- + +## "We A/B tested annual vs monthly default; result was wash." + +**The diagnosis.** Default may not have been the issue; price-anchoring or commitment friction may be. + +**The cure.** Test different variables. Price level, discount magnitude, presentation order. + +--- + +## "Sales-led upgrades convert at higher rate than self-serve." + +**The diagnosis.** Self-serve flow misses something that sales touches address. + +**The cure.** Audit what sales does that the flow does not. Often: clarifies value, addresses objections, customizes recommendation. + +--- + +## "We added more upsell prompts; existing customer churn went up." + +**The diagnosis.** Prompt fatigue. Existing customers feel squeezed. + +**The cure.** Frequency limits on upsell. Less is often more. + +--- + +## "Conversion drops at the credit-card-entry step." + +**The diagnosis.** Form friction or trust signals missing. + +**The cure.** Optimize the credit-card form. Add trust signals (security badges, refund policy). Reduce required fields. + +--- + +## The pattern across failures + +Most upgrade flow failures fall into one of three patterns. + +**Pattern 1: Paywalls at wrong moments.** Paywall-everywhere, premature, unconnected, free-forever-trap. The fix is to align paywalls with demonstrated value. + +**Pattern 2: Plan structure misaligned.** Plan-paralysis, plan-mismatch, post-upgrade-empty. The fix is clearer tier audiences and post-upgrade experience. + +**Pattern 3: Trust damage.** Bait-and-switch, hidden-price, aggressive-downsell, hard-to-cancel. The fix is transparency and respect for the user. + +The metric pattern: upgrade flow failures often look fine on conversion alone. The signal is in retention post-upgrade, churn rate, win-back conversion. Programs that track only conversion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (paywall timing, plan structure, trust). The principle that conversion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/upgrade-flow-design/references/free-tier-decision-criteria.md b/skills/upgrade-flow-design/references/free-tier-decision-criteria.md new file mode 100644 index 0000000..6111ee4 --- /dev/null +++ b/skills/upgrade-flow-design/references/free-tier-decision-criteria.md @@ -0,0 +1,253 @@ +# Free-tier decision criteria + +Freemium, free-trial, reverse trial, no-free. Choice criteria. + +The free-tier decision is upstream of upgrade flow design. The structure determines what the upgrade flow looks like, which trigger moments matter, and what conversion rates are achievable. + +--- + +## The free-tier decision matters + +Different free-tier structures warrant different upgrade flows. + +**The win.** A SaaS product chooses freemium because users provide product value (data, virality, network). Upgrade flow surfaces capacity-based paywalls. Conversion is 3 percent but volume produces meaningful revenue. + +**The fail.** Same product chooses free-trial without realizing user value matters more than time-bound trial. Trial ends; users churn rather than convert; the product loses the network effect users were providing for free. + +The decision is strategic; downstream design choices follow from it. + +--- + +## Pattern A: Freemium (free-forever tier) + +Users use the product indefinitely without paying. + +**How it works.** + +- Free tier offers core value with constraints (capacity limits, feature limits). +- Paid tier removes constraints or unlocks more. +- Users may stay free forever; conversion happens when they hit constraints they value enough to pay around. + +**Conversion baseline.** 2-5 percent typical for B2B SaaS; varies widely. + +**Strengths.** + +- Volume. +- Network effects from free users. +- Users provide product value (data, content, virality). +- Lower acquisition cost. + +**Weaknesses.** + +- Most users do not convert. +- Free-tier capacity costs. +- Plan-design pressure to gate the right things. + +**When to use.** Products with strong network effects, or where free users genuinely contribute to product value. + +--- + +## Pattern B: Free-trial (time-limited) + +Users get full or near-full product for a defined period. + +**How it works.** + +- Trial period (7-30 days typical). +- After trial, must pay to continue. +- Often credit-card-required at start (with auto-charge) or credit-card-not-required (with explicit conversion at end). + +**Conversion baseline.** 10-25 percent of trial signups; higher with credit-card-required. + +**Strengths.** + +- Strong commitment from users who start. +- Clear conversion deadline. +- Revenue arrives quickly post-trial. + +**Weaknesses.** + +- Friction at signup if credit card required. +- Users churn if trial ends before they reach value. +- Trial extension dynamics can become a negotiation. + +**When to use.** Products where value is clear within the trial period; audiences willing to commit time before paying. + +--- + +## Pattern C: Reverse trial + +Users start on paid plan; auto-downgrade to free after period. + +**How it works.** + +- Signup grants paid features for a defined period. +- After period, auto-downgrades to free tier. +- Users who want continued paid features upgrade. + +**Conversion baseline.** Moderate; mixes signals. + +**Strengths.** + +- Users see paid features; familiarity may drive conversion. +- Easier to start than credit-card-required trial. + +**Weaknesses.** + +- Surprise when downgrade hits. +- Some users dislike the loss-aversion framing. +- Less common; users may not know what to expect. + +**When to use.** When the team has tested both freemium and free-trial and reverse-trial outperforms; specific product-audience fits. + +--- + +## Pattern D: No-free (paid-only) + +No free tier; users pay to start. + +**How it works.** + +- Sales conversation or demo; user signs contract or starts subscription. +- No self-serve free path. + +**Strengths.** + +- Higher revenue per signup. +- Clearer signal of intent. +- No free-tier capacity costs. + +**Weaknesses.** + +- Lower top-of-funnel volume. +- Higher acquisition cost. +- Sales-motion dependent. + +**When to use.** Enterprise products, high-touch sales, products where free would dilute brand or capacity. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production products mix. + +**Common combinations.** + +- Freemium with free-trial of paid tier (free forever; trial of higher tier for free users). +- Free-trial with credit-card-not-required for self-serve, plus paid-only for enterprise. +- Reverse-trial for new users, freemium for users who downgrade at end of reverse-trial. + +**The hybrid challenge.** More complexity; more paths to maintain. Justify complexity with conversion data. + +--- + +## Choice criteria + +How to decide. + +**Use freemium when:** + +- Network effects matter; free users contribute value. +- Audience expects free; paid-only would limit reach. +- Conversion rate at scale produces meaningful revenue. + +**Use free-trial when:** + +- Value is clear within a trial period. +- Audience willing to commit time before paying. +- Conversion economics favor higher rate over higher volume. + +**Use reverse-trial when:** + +- Both freemium and free-trial have been tested and reverse-trial outperforms. +- Audience signal-strength is high (paid features get used). + +**Use no-free when:** + +- Audience is enterprise or high-touch. +- Product capacity costs prohibit freemium. +- Sales motion is the dominant funnel. + +**Use hybrid when:** + +- Different audience segments warrant different free structures. +- Data justifies the complexity. + +--- + +## Free-tier capacity design + +For freemium, the capacity decision. + +**The principle.** Free tier offers enough capacity to demonstrate value; not enough to replace paid tier. + +**Capacity dimensions.** + +- **Use volume.** Number of items, queries, exports per month. +- **Capacity.** Storage, seats, integrations. +- **Feature set.** Specific features paid only. +- **Support level.** Self-serve only on free; live support on paid. +- **Branding.** Free tier shows brand; paid removes. + +**Design discipline.** Free tier should let users hit the ah-ha moment; paid tier should be necessary for sustained or scaled use. Too generous: users do not convert. Too constrained: users do not reach ah-ha. + +--- + +## Trial period length + +For free-trial, how long. + +**Common periods.** + +- **7 days.** Aggressive; works when ah-ha moment is clear and quick. +- **14 days.** Common B2B; balances time-to-value with urgency. +- **30 days.** Generous; works for products with longer evaluation cycles. +- **60+ days.** Rare; usually reflects enterprise sales cycles. + +**Decision factors.** + +- Time-to-value of the product. +- Audience evaluation cycle. +- Conversion rate by trial length (test if uncertain). + +--- + +## Free-tier maintenance + +Free-tier structures decay. + +**What decays.** + +- Capacity limits set years ago no longer match current product capability. +- Features moved between tiers without comprehensive update. +- Audience composition shifted; old free-tier no longer fits. + +**Maintenance cadence.** Quarterly review of free-tier structure alongside pricing review. + +**The decay-driven redesign.** When refinements have not moved conversion, the free-tier structure may need redesign. + +--- + +## Common free-tier failures + +**Free-tier too generous.** Users get everything they need; conversion never starts. + +**Free-tier too constrained.** Users do not reach value; churn before conversion. + +**Trial too short.** Users do not reach ah-ha moment; trial ends with low conversion. + +**Trial too long.** Conversion incentive weak; users defer decision. + +**Wrong free-tier structure for audience.** Freemium chosen for enterprise audience that wanted no-free; adoption suffers. + +**No maintenance.** Free-tier static; conversion declines as product evolves. + +--- + +## Methodology-level choices that stay in the public skill + +The free-tier decision matters principle. Patterns A through E. Choice criteria. Free-tier capacity design. Trial period length. Maintenance considerations. Common failures. + +## Implementation choices that stay internal + +Specific free-tier structures for specific products. Specific capacity limits. Specific trial lengths. The team's pricing review calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/paywall-presentation-patterns.md b/skills/upgrade-flow-design/references/paywall-presentation-patterns.md new file mode 100644 index 0000000..a08b9ea --- /dev/null +++ b/skills/upgrade-flow-design/references/paywall-presentation-patterns.md @@ -0,0 +1,293 @@ +# Paywall presentation patterns + +Modal, banner, inline, toast. Copy and value-prop discipline. + +How the paywall surfaces. Done well, the presentation matches the trigger's intensity; done poorly, presentation fights the trigger and conversion suffers. + +--- + +## The presentation-matches-trigger principle + +Strong triggers warrant prominent presentation; soft triggers warrant subtle presentation. + +**The win.** A user hits a capacity limit; a modal surfaces explaining the limit and offering upgrade. The modal is justified because the trigger is hard (the user cannot continue without resolving). The user accepts the interruption. + +**The fail.** Same user, soft trigger (general awareness moment). A modal surfaces the same way. The interruption is not justified by the trigger; user resents. + +The discipline. Match presentation intensity to trigger strength. + +--- + +## Pattern A: Modal paywall + +Full-screen overlay blocks the action. + +**How it works.** + +- Modal overlay appears. +- User must engage (upgrade) or dismiss to continue. +- Often blocks the action that triggered it. + +**Strengths.** + +- Highest visibility. +- Clear demand for attention. +- Works for hard triggers (capacity hit, feature gate). + +**Weaknesses.** + +- Most disruptive. +- Easily abused; produces annoyance. + +**When to use.** Hard triggers where the user cannot proceed without resolution. + +--- + +## Pattern B: Banner paywall + +Persistent banner at top of page. + +**How it works.** + +- Banner remains visible across pages. +- Often dismissable for the session. +- Soft prompt; does not block action. + +**Strengths.** + +- Persistent awareness without blocking. +- Reaches users who have not hit hard triggers. + +**Weaknesses.** + +- Visual noise; users develop blindness. +- Cumulative exposure can feel like spam. + +**When to use.** Awareness campaigns. Use sparingly; persistent banners abused become noise. + +--- + +## Pattern C: Inline paywall + +Upgrade ask embedded in the surface where the trigger occurred. + +**How it works.** + +- Paywall content appears within the workflow. +- User reads in context; can act or scroll past. +- No overlay; no modal. + +**Strengths.** + +- Contextual; integrated with the workflow. +- Non-disruptive. +- Respectful of user momentum. + +**Weaknesses.** + +- Easier to miss. +- May not produce conversion if too easy to ignore. + +**When to use.** Soft triggers; awareness without interruption. + +--- + +## Pattern D: Toast or notification + +Brief paywall surfaced as a notification. + +**How it works.** + +- Small notification appears (often corner of screen). +- Auto-dismisses after time or on click. +- Brief content. + +**Strengths.** + +- Lightest weight. +- Easy to dismiss. + +**Weaknesses.** + +- Easy to miss entirely. +- Limited content. + +**When to use.** Soft prompts; low-priority awareness. + +--- + +## Pattern E: Hybrid + +Combining patterns. + +**Common combinations.** + +- Modal for hard triggers + inline for soft triggers. +- Banner for awareness + modal at hard trigger moments. +- Inline for in-feature prompts + modal at capacity limits. + +**The hybrid discipline.** Each presentation has a clear role; users do not see overlapping or competing paywalls. + +--- + +## Choice criteria + +Which presentation fits which trigger. + +**Use modal when:** + +- Trigger is hard (cannot proceed without resolution). +- Capacity limit reached. +- Feature gate hit. + +**Use inline when:** + +- Trigger is contextual but soft. +- User can continue without resolving. +- Workflow integration is the priority. + +**Use banner when:** + +- Awareness campaign across pages. +- Soft prompt for users who have not hit hard triggers. + +**Use toast when:** + +- Low-priority awareness. +- Brief acknowledgment. + +The simplest pattern that matches the trigger is usually right. Most upgrade flows benefit from inline + occasional modal. + +--- + +## Copy and value-prop discipline + +What the paywall says. + +**The principle.** Paywall copy should connect to what the user just did and what they get next. + +**Strong copy patterns.** + +- "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [advanced capabilities]." +- "You have hit your free tier's [capacity]. Upgrade to expand to [paid capacity]." +- "Inviting teammates requires our [team plan]. Upgrade to invite up to [number] teammates." + +What works: specific connection to user action; specific value of upgrade. + +**Weak copy patterns.** + +- "Upgrade for more features." (Generic; no connection.) +- "Get the full experience." (Vague; no specifics.) +- "Don't miss out." (FOMO without value.) + +What fails: no connection to user behavior; no specific value-prop. + +--- + +## Plan presentation in paywalls + +Showing the upgrade options. + +**Single-plan paywall.** One upgrade option presented. Simple; clear. + +When to use. When the upgrade is unambiguous (capacity hit; one obvious path). + +**Multi-plan paywall.** Two or three upgrade options presented (e.g., Pro vs Enterprise). + +When to use. When multiple plans could fit; let the user choose. + +**Presentation discipline.** + +- Highlight the recommended plan. +- Make pricing clear. +- Make value differences clear. + +**Anti-pattern.** Showing 5 plans in a paywall. Decision paralysis; user does not choose. + +--- + +## Pricing presentation + +How prices appear. + +**Per-month vs per-year.** Default to the user's likely commitment level; offer the alternative. + +**Price anchoring.** Show what the upgrade saves vs equivalent value (use carefully; can feel manipulative). + +**Currency and locale.** Match the user's locale. + +**Discounts.** Surface honest discounts (annual discount, promotion). Avoid fake urgency. + +--- + +## Action design + +The buttons and CTAs. + +**Primary CTA.** "Upgrade to Pro" with specific plan name. Bold; visible. + +**Secondary CTA.** "Maybe later" or "See plans." Allows decline without forcing. + +**No third option.** Two paths (upgrade or decline) preferred. Three or more paths confuse. + +**The decline-respect principle.** "Maybe later" should respect the decline. The same paywall should not re-fire immediately. + +--- + +## Paywall as opportunity to communicate value + +Even when the user declines, the paywall is a touchpoint. + +**The principle.** Paywall copy explains what paid offers in concrete terms. Even users who decline understand more about the paid plan than they did before. + +**Why this matters.** Future trigger moments find users with more context. The decline today may convert next month because the value is now understood. + +--- + +## Paywall analytics + +Track the paywall's performance. + +**Metrics.** + +- Display rate (how often does it surface?). +- Click rate (how many engage with upgrade button?). +- Conversion rate (of clicks, how many complete upgrade?). +- Decline rate (how many dismiss?). +- Re-show rate per declined paywall. + +**Diagnostic uses.** + +- High display, low click: copy or value-prop weak. +- High click, low conversion: friction in upgrade flow downstream. +- High decline rate: trigger may be wrong, or copy unclear. + +--- + +## Common presentation failures + +**Wrong presentation for trigger.** Modal on soft trigger; inline on hard trigger. + +**Generic copy.** Paywall does not connect to user behavior. + +**Plan paralysis.** Too many options in the paywall. + +**Hidden price.** User has to dig to find the cost. + +**Decline ignored.** Same paywall re-fires immediately after dismiss. + +**Cumulative exposure.** User sees too many paywalls per session. + +**Mobile-broken paywall.** Modal on mobile blocks all interaction. + +**Loading delay.** Paywall takes time to appear; user has moved on. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation-matches-trigger principle. Patterns A through E. Choice criteria. Copy and value-prop discipline. Plan presentation. Pricing presentation. Action design. Paywall as value communication. Paywall analytics. Common failures. + +## Implementation choices that stay internal + +Specific paywall designs for specific products. Specific copy in brand voice. Specific tooling. The team's analytics dashboards. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/plan-structure-patterns.md b/skills/upgrade-flow-design/references/plan-structure-patterns.md new file mode 100644 index 0000000..da29b03 --- /dev/null +++ b/skills/upgrade-flow-design/references/plan-structure-patterns.md @@ -0,0 +1,240 @@ +# Plan structure patterns + +Tier count, feature gating, audience-fit per tier. + +The plans the upgrade flow leads to. Done well, plan structure makes upgrade decisions clear; done poorly, plan structure produces decision paralysis or upgrade-then-downgrade churn. + +--- + +## The clear-tier-fit principle + +Each tier should have a clear "this is for [audience] because of [reason]." Tiers without clear audience-fit produce weak conversions. + +**The win.** A SaaS analytics product has 3 tiers. Starter ("solo analysts and small teams"), Growth ("10-50 person analytics teams"), Enterprise ("complex analytics needs at scale"). Each tier maps to a specific audience; users self-select by recognizing themselves. + +**The fail.** Same product has 3 tiers labeled Bronze, Silver, Gold with feature checkmarks. Audiences cannot tell which is for them; many pick the wrong tier; downgrade rates climb. + +The discipline. Each tier has clear audience-fit articulated. + +--- + +## Tier count + +How many tiers. + +**2-tier (Free + Paid).** + +How it works. Free for some users, paid for everyone else. + +Strengths. Simple; clear upgrade path. + +Weaknesses. Cannot capture enterprise-tier revenue; cannot serve segmented audiences differently. + +When to use. Single-audience products; products with limited feature differentiation. + +**3-tier (Starter + Pro + Enterprise).** + +How it works. Three plans serving three audiences. + +Strengths. Captures entry-level, mid-market, and enterprise. Industry-standard. + +Weaknesses. Requires clear audience differentiation; can create decision paralysis if audiences are not clear. + +When to use. Most B2B SaaS products. Default for products with diverse audiences. + +**4+ tier.** + +How it works. Four or more plans. + +Strengths. Highly granular; serves many audiences. + +Weaknesses. Decision paralysis; users cannot tell which tier fits. + +When to use. Rarely. Most products do better with 3 tiers and add-ons rather than 4+ tiers. + +The simplest tier count that fits the audience is usually best. + +--- + +## Feature gating patterns + +How features differ between tiers. + +**Pattern A: Capacity-based gating.** + +How it works. All tiers have most features; tiers differ in volume (seats, queries, storage). + +Strengths. Clear upgrade trigger when capacity hit. Easy to understand. + +Weaknesses. Encourages users to optimize against limits. + +When to use. Products where capacity is the key cost driver. + +**Pattern B: Feature-based gating.** + +How it works. Lower tiers missing specific features; higher tiers unlock them. + +Strengths. Clear value differentiation between tiers. + +Weaknesses. Feature gating can feel arbitrary; users may want one paid feature but not the rest. + +When to use. Products with clearly tiered feature sets (basic vs advanced vs enterprise). + +**Pattern C: Hybrid gating.** + +How it works. Both capacity and features differ between tiers. + +Strengths. Most flexibility; serves diverse audiences. + +Weaknesses. More complex to communicate; feature comparison tables get long. + +When to use. Default for production B2B SaaS; most products benefit from hybrid. + +**Pattern D: Service-based gating.** + +How it works. Tiers differ in service level (support, onboarding, SLA). + +Strengths. Aligns with enterprise expectations. + +Weaknesses. Service costs scale with tier. + +When to use. Often for top tier (Enterprise); rarely the only differentiation. + +--- + +## Plan naming + +What to call the plans. + +**Audience-named plans.** "For solo creators," "For growing teams," "For enterprise." + +Strengths. Self-selecting; users know which fits. + +Weaknesses. Audience names age; "for startups" can feel limiting. + +**Tier-named plans.** "Starter," "Pro," "Enterprise" or "Basic," "Pro," "Premium." + +Strengths. Industry-standard; users recognize. + +Weaknesses. Generic; does not differentiate from competitors. + +**Outcome-named plans.** "Build," "Grow," "Scale." + +Strengths. Aspirational; aligns with user goals. + +Weaknesses. Vague; users may not know which outcome describes them. + +The discipline. Names should be specific enough that users self-select correctly. + +--- + +## Pricing structure + +How prices map to tiers. + +**Per-seat.** Cost scales with team size. + +When to use. Team collaboration products. + +**Per-feature.** Cost scales with feature set. + +When to use. Modular products. + +**Per-usage.** Cost scales with use volume. + +When to use. Capacity-driven products. + +**Flat per-tier.** Each tier has fixed price regardless of usage. + +When to use. Predictable-budget audiences (often enterprise). + +**Hybrid pricing.** Combinations of the above. + +When to use. Most production products use hybrid (per-seat with usage caps; flat tier with feature differences). + +--- + +## Annual vs monthly + +Commitment options. + +**Monthly.** Lower commitment; higher friction at cancellation; users can leave easily. + +**Annual.** Higher commitment; usually discounted; reduces churn but requires upfront payment. + +**Both offered.** Most products offer both; annual discount incentivizes commitment. + +**Discipline.** Discount on annual should reflect real value to the company (lower churn, predictable revenue) rather than arbitrary marketing percent-off. + +--- + +## Plan transition design + +How users move between plans. + +**Free to paid.** First commitment. Smooth experience matters most. + +**Tier upgrade (within paid).** From Pro to Enterprise. Often involves billing transition. + +**Downgrade (within paid).** From Enterprise to Pro. Should be friction-low to maintain trust; aggressive downgrade prevention damages trust. + +**Cancellation to free.** Some products auto-downgrade on cancellation; others fully cancel. Each has tradeoffs. + +The transitions should be smooth. Friction at transition damages trust. + +--- + +## Pricing-page coordination + +Plan structure decisions reflect on the pricing page. + +**The principle.** Plan structure decisions made for the upgrade flow appear on the pricing page. Users should see consistent information. + +**The integration.** Pricing-page copy (covered by `landing-page-copy`) implements the plan structure decisions made here. The two skills coordinate. + +--- + +## Plan maintenance + +Plans decay. + +**What decays.** + +- Capacity limits set years ago no longer match product capability. +- Features moved between tiers over time without comprehensive update. +- Pricing levels no longer match market. +- Tier audiences shifted. + +**Maintenance cadence.** Annual review at minimum; major product or market changes trigger more frequent. + +**The decay-driven redesign.** When plan structure no longer reflects reality, redesign rather than patch. + +--- + +## Common plan structure failures + +**Too many tiers.** Decision paralysis; users pick wrong tier. + +**Tiers without clear audience-fit.** Generic names without differentiation. + +**Misaligned pricing.** Prices that do not reflect value differences between tiers. + +**Feature gating arbitrary.** Features gated based on what is easy rather than what audiences need. + +**No annual discount.** Users default to monthly; cumulative revenue lower. + +**Aggressive downgrade prevention.** Users want to downgrade; friction damages trust. + +**Plans not updated.** Pricing or tiers from years ago no longer fit current product or market. + +**Pricing-page mismatched.** Plans on the page differ from plans in the upgrade flow. + +--- + +## Methodology-level choices that stay in the public skill + +The clear-tier-fit principle. Tier count guidance. Feature gating patterns A through D. Plan naming patterns. Pricing structure patterns. Annual vs monthly. Plan transition design. Pricing-page coordination. Plan maintenance. Common failures. + +## Implementation choices that stay internal + +Specific plans for specific products. Specific feature gating decisions. Specific pricing levels. Specific naming conventions. The team's pricing review calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/trigger-moment-design.md b/skills/upgrade-flow-design/references/trigger-moment-design.md new file mode 100644 index 0000000..7b4af5d --- /dev/null +++ b/skills/upgrade-flow-design/references/trigger-moment-design.md @@ -0,0 +1,217 @@ +# Trigger-moment design + +Where paywalls earn their interruption. Strong vs weak trigger moments. + +The single most consequential decision in upgrade flow design. Paywalls surface at moments where the user has demonstrated they are getting value. Get this wrong and conversion suffers regardless of paywall design quality. + +--- + +## The earned-interruption principle + +Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +**The win.** User has used a feature 50 times. Hits the 50th-use limit. Paywall surfaces: "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [related advanced capabilities]." The trigger is fresh; the value is demonstrated; the user is positioned to say yes. + +**The fail.** Same user. Paywall surfaces on first login: "Upgrade for more features." User has not yet demonstrated value; the upgrade ask is premature; user dismisses. + +The discipline. Paywalls earn their interruption by connecting to recent demonstrated value. + +--- + +## Strong trigger moments + +Patterns that recur across products. + +**Usage threshold reached.** + +How it works. User has used a feature N times in a period. Further use requires paid plan. + +Why it works. The user clearly values the feature. The threshold is predictable; the paywall is honest about the constraint. + +**Capacity limit hit.** + +How it works. User reached free-tier capacity (storage, seats, queries). Upgrade unlocks more. + +Why it works. User encountered an unambiguous block. The block is part of the free-tier promise; the upgrade is the resolution. + +**Advanced feature attempted.** + +How it works. User clicked into a feature that requires paid plan. + +Why it works. Interest is fresh; the user wanted this specific feature. Upgrade ask connects to the specific interest. + +**Workflow completed successfully.** + +How it works. User completed an action that produced visible value (saved view, exported result, completed flow). Upgrade ask connects continuing or expanding that value to paid plan. + +Why it works. Value is fresh; user just experienced what the product does. Upgrade frames continuation. + +**Team-collaboration moment.** + +How it works. User wants to invite teammates; team capabilities require paid plan. + +Why it works. The collaboration intent is concrete; team capabilities are a clear value extension. + +**Time-trial ending.** + +How it works. Trial-based products surface upgrade as trial nears end. + +Why it works. Predictable; user expected it; the conversion conversation is timely. + +**Multi-session usage.** + +How it works. User has returned multiple times; engagement signal strong; soft upgrade prompt. + +Why it works. The user has demonstrated commitment through return; soft prompt fits. + +--- + +## Weak trigger moments + +Patterns that fail. + +**First-login paywall.** + +The pattern. Upgrade ask on first login. + +Why it fails. User has not yet seen value; the ask is premature. + +**Random in-product placement.** + +The pattern. Persistent paywall on the dashboard with no specific trigger. + +Why it fails. Not connected to user behavior; users develop blindness. + +**Every-page banner.** + +The pattern. Persistent upgrade banner across all surfaces. + +Why it fails. Visual noise; users learn to ignore. + +**Paywall on the action the user expected free.** + +The pattern. User believed a feature was free (because of marketing or onboarding); paywall surfaces when they try to use it. + +Why it fails. Trust damage. The user feels deceived. + +**Paywall on irrelevant moments.** + +The pattern. Paywall surfaces during user actions unrelated to the paid feature. + +Why it fails. Confusing; user does not connect the ask to anything. + +**Paywall right after an error.** + +The pattern. User just had a bad experience; immediately gets an upgrade ask. + +Why it fails. Tone-deaf; trust degrades. + +--- + +## Trigger moment design discipline + +Designing each trigger. + +**Step 1: Identify the demonstrated value.** What did the user just do that demonstrates value? + +**Step 2: Identify the connection to paid.** How does the paid plan extend or continue that value? + +**Step 3: Time the ask.** When in the user's flow does the ask land cleanly without breaking momentum? + +**Step 4: Match presentation to importance.** Strong triggers warrant modal; soft triggers inline. + +**Step 5: Plan the response paths.** What if user accepts? Declines? Asks for info? Each path designed. + +The output is a trigger moment that the user perceives as fair. + +--- + +## Trigger frequency + +How often paywalls fire. + +**Per-trigger.** A specific trigger should not fire repeatedly. Once it has fired and been declined, give space before re-asking. + +**Cumulative session frequency.** Total paywall exposures per session capped (often 1-2). Beyond that, additional triggers defer. + +**Per-week.** For users who use the product frequently, weekly cap prevents fatigue. + +**The over-trigger trap.** Each individual trigger looks reasonable; cumulative exposure is annoying. + +--- + +## Personalized trigger logic + +Different users may warrant different triggers. + +**Power-user vs new-user.** Power users may have different trigger thresholds; new users may need more time. + +**Plan tier.** Free users see free-to-paid triggers; paid users see paid-to-higher-paid triggers. + +**Engagement frequency.** Daily active vs returning monthly may warrant different timing. + +**The discipline.** Personalize where data justifies; do not over-segment. + +--- + +## Trigger testing + +Test triggers before launching. + +**Test cases.** + +- New user encounters trigger: appropriate timing? +- Returning user encounters trigger: re-fire respect? +- Power user encounters trigger: relevant? +- User who declined trigger encounters again: respectful? + +**Production monitoring.** + +- Per-trigger fire rate. +- Per-trigger conversion rate. +- Decline rate per trigger. +- Cumulative session exposure. + +The data informs which triggers earn their place and which should be retired. + +--- + +## Trigger maintenance + +Triggers decay. + +**What decays.** + +- Thresholds set years ago no longer match current usage patterns. +- Features the trigger references have changed or been deprecated. +- Audience composition shifted; old triggers no longer fit. + +**Maintenance cadence.** Quarterly review. Triggers that fire too often, too rarely, or with low conversion warrant attention. + +--- + +## Common trigger-moment failures + +**Premature triggers.** Asking before value is demonstrated. + +**Unconnected triggers.** Paywall not tied to the user's recent action. + +**Over-frequent triggers.** Cumulative exposure becomes noise. + +**Stale triggers.** Threshold values set long ago no longer match usage. + +**Mistimed triggers.** Right concept, wrong moment in the user's flow. + +**Triggers right after errors.** Tone-deaf placement after frustration. + +**Triggers that violate free-tier promise.** Asking the user to pay for something they were told was free. + +--- + +## Methodology-level choices that stay in the public skill + +The earned-interruption principle. Strong trigger moments (7 patterns). Weak trigger moments (6 patterns). Trigger moment design discipline. Trigger frequency. Personalized trigger logic. Trigger testing. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific triggers for specific products. Specific thresholds. Specific tooling. The team's audit calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md b/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md new file mode 100644 index 0000000..3c9cb48 --- /dev/null +++ b/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md @@ -0,0 +1,212 @@ +# Upgrade flow anti-patterns + +The patterns that look like upgrade flows but degrade trust. Easy to ship; the cost shows up in conversion, retention, and brand reputation. + +--- + +## The paywall-everywhere flow + +The pattern. Paywall blocks meaningful product use; free tier too constrained. + +The signal. Users churn before reaching value; conversion stays low despite aggressive paywalling. + +The cost. Users who would have paid after seeing value never reach it. + +The cure. Loosen the free tier; surface paywalls at moments of demonstrated value. + +--- + +## The free-forever-trap flow + +The pattern. Generous free tier; no upgrade path surfaces. + +The signal. Conversion stays at single-digit indefinitely. + +The cost. Product is loved free; revenue does not follow. + +The cure. Add value-triggered paywalls. Connect upgrade to demonstrated value. + +--- + +## The premature-paywall flow + +The pattern. Paywall on first login or before value is demonstrated. + +The signal. High dismiss rate; conversion does not lift. + +The cost. Users associate the brand with hard-sell early; some leave entirely. + +The cure. Move paywalls to moments of demonstrated value. + +--- + +## The unconnected-paywall flow + +The pattern. Paywall not connected to user behavior; appears at random or on every page. + +The signal. Visual noise; users develop blindness. + +The cost. Cumulative exposure becomes spam; trust degrades. + +The cure. Tie each paywall to specific user-demonstrated value. + +--- + +## The plan-paralysis flow + +The pattern. 5+ tiers presented in upgrade flow; users cannot decide. + +The signal. Click rate on plans is even across tiers; conversion does not match interest. + +The cost. Decision paralysis prevents conversion. + +The cure. Reduce tier count to 3. Recommend a default plan based on user signals. + +--- + +## The hidden-price flow + +The pattern. Prices buried; users have to dig to find them. + +The signal. Users abandon at the price-discovery step. + +The cost. Friction at the moment of decision; users leave. + +The cure. Surface prices clearly. Hidden pricing damages trust. + +--- + +## The decline-ignored flow + +The pattern. User dismisses paywall; same paywall fires immediately. + +The signal. Users disable tours globally; complain about persistent paywalls. + +The cost. Trust degrades; users may churn from the friction itself. + +The cure. Respect declines. Wait substantial time before re-asking. + +--- + +## The aggressive-downsell flow + +The pattern. User declines primary; multiple decline-and-counter rounds; user feels pressured. + +The signal. Users associate the brand with manipulation. + +The cost. Even users who eventually convert leave with negative impressions. + +The cure. One downsell at most. Respect the second decline. + +--- + +## The bait-and-switch flow + +The pattern. User believed feature was free (because of marketing); paywall surfaces when they try to use it. + +The signal. Users complain about deception; trust collapses. + +The cost. Long-term brand damage. + +The cure. Marketing and product align on what is free. No surprise paywalls on advertised-as-free features. + +--- + +## The discount-led-win-back flow + +The pattern. Win-back discount-only; no value-prop change. + +The signal. Re-engaged users churn again; users learn to lapse for discounts. + +The cost. Reverse incentive; lapse rate rises strategically. + +The cure. Lead with value-prop change; discount sparingly. + +--- + +## The aggressive-cancellation-prevention flow + +The pattern. User wants to cancel; flow makes cancellation hard (multi-step, hidden, support-only). + +The signal. Users complain publicly; brand earns "hard to cancel" reputation. + +The cost. Long-term trust damage; sometimes regulatory issue. + +The cure. Cancellation should be as easy as signup. Friction at exit damages reputation. + +--- + +## The plan-mismatch flow + +The pattern. Tier audiences not clearly differentiated; users pick wrong plan. + +The signal. Upgrade rate looks fine; downgrade rate climbs as users realize they picked wrong. + +The cost. Churn through dissatisfaction. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit visible. + +--- + +## The post-upgrade-empty flow + +The pattern. User upgrades; nothing changes immediately. New features unlocked but not surfaced. + +The signal. Upgraded users do not engage with paid features they paid for. + +The cost. Buyer's remorse; downgrade rate climbs. + +The cure. Post-upgrade welcome; surface what changed; help users access new features immediately. + +--- + +## The aggressive-upsell flow + +The pattern. Customers paying already; upsell asks fire constantly. + +The signal. Customer fatigue; cross-sell rate drops over time. + +The cost. Existing customer relationship damaged. + +The cure. Frequency limits on upsell. Cross-sell at moments of relevance, not constantly. + +--- + +## The win-back-spam flow + +The pattern. Lapsed users get win-back outreach repeatedly without segmentation. + +The signal. Unsubscribe rate climbs; brand earns spammy reputation. + +The cost. Loses users who might have returned with better outreach. + +The cure. Segment win-back; respect non-response; abandon after reasonable attempts. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of upgrade flows. + +**Audit questions per flow.** + +- Are paywalls connected to demonstrated value (anti-pattern check: paywall-everywhere, premature, unconnected)? +- Is decline respected (anti-pattern check: decline-ignored, aggressive-downsell)? +- Is plan structure clear (anti-pattern check: plan-paralysis, plan-mismatch)? +- Is pricing visible (anti-pattern check: hidden-price)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does post-upgrade experience deliver (anti-pattern check: post-upgrade-empty)? +- Is win-back honest (anti-pattern check: discount-led, win-back-spam)? +- Is marketing-product alignment maintained (anti-pattern check: bait-and-switch)? + +**The retire decision.** Anti-pattern flows often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md b/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md new file mode 100644 index 0000000..f5497ed --- /dev/null +++ b/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md @@ -0,0 +1,214 @@ +# Upsell vs downsell logic + +When the user does not accept the primary upgrade. Secondary paths. + +Not every user accepts the proposed upgrade. The discipline is to capture revenue from users who would pay something but not the proposed amount, while respecting users who genuinely do not want to upgrade. + +--- + +## The secondary-path principle + +When the primary upgrade is declined, secondary options may capture revenue otherwise lost. + +**The win.** User is offered Pro plan ($X/month). Declines. System offers Starter plan ($X/3/month). User accepts Starter. Some revenue beats no revenue. + +**The fail.** User declines Pro; sees no other path; remains free; revenue is zero. + +The discipline. Design secondary paths thoughtfully; do not aggressive-downsell into manipulation. + +--- + +## Pattern A: Upsell + +User on basic plan; ask them to upgrade to higher tier. + +**How it works.** + +- Trigger fires when user demonstrates value of higher-tier features. +- Upgrade flow surfaces with the higher plan. + +**Strengths.** + +- Higher revenue per converted user. +- Aligned with demonstrated value. + +**Weaknesses.** + +- User may not need the higher tier; conversion can be poor. + +**When to use.** When the user has hit limits or used features that the higher tier addresses. + +--- + +## Pattern B: Cross-sell + +User is paying; offer add-ons or related products. + +**How it works.** + +- Trigger fires when user shows interest in adjacent capabilities. +- Cross-sell surfaces complementary product or add-on. + +**Strengths.** + +- Expands revenue from existing customer. +- Often easier than acquiring new customers. + +**Weaknesses.** + +- Risks fatigue if cross-sells are too frequent. +- Users may feel they are being squeezed. + +**When to use.** When add-ons or related products genuinely fit the customer's profile. + +--- + +## Pattern C: Downsell + +User declined the higher tier; offer a smaller commitment. + +**How it works.** + +- User dismisses upgrade. +- Secondary paywall offers a lower-tier plan, monthly instead of annual, or smaller seat count. + +**Strengths.** + +- Captures revenue from users not ready for the primary plan. +- Establishes paying relationship that may upgrade later. + +**Weaknesses.** + +- Aggressive downsell feels manipulative. +- Users may downgrade to the lowest option even when they would have paid more. + +**When to use.** When the primary plan is decline-prone; downsell catches users who would pay something. + +--- + +## Pattern D: Annual-vs-monthly downsell + +User declined annual; offer monthly. + +**How it works.** + +- Annual plan offered first (with discount). +- Decline; monthly offered as backup. + +**Strengths.** + +- Some users avoid annual commitment but accept monthly. +- Captures revenue from commitment-averse users. + +**Weaknesses.** + +- Cumulative revenue lower. +- Can train users to expect monthly when annual was the goal. + +**When to use.** When annual is the desired commitment but conversion suffers from upfront cost. + +--- + +## Pattern E: Seat-count downsell + +User declined full team plan; offer single-seat upgrade. + +**How it works.** + +- Team plan offered first. +- Decline; single-seat upgrade offered. + +**When to use.** When the user's situation suggests they would value paid features for themselves but cannot commit team-wide yet. + +--- + +## Downsell discipline + +When downsell crosses into manipulation. + +**Honest framing.** "If Pro is more than you need, here is something that fits your team size." + +**Manipulative framing.** Aggressive flow that pressures the user. Multiple decline-and-counter rounds. Hidden costs. Switching plan terms after acceptance. + +**The discipline.** Downsell respects the decline; offers an alternative; does not pressure. + +--- + +## When NOT to downsell + +Some declines should be respected. + +**The user explicitly does not want any plan.** Continued upgrade asks become harassment. + +**The user has signaled disengagement.** Aggressive downsell on a disengaged user accelerates churn. + +**The user is on a free tier that fits.** Forcing an upgrade where the user is happy on free degrades trust. + +**The user is in a bad moment.** After an error, support ticket, or negative experience, downsell is tone-deaf. + +--- + +## Sequencing upsell, cross-sell, downsell + +In a typical flow. + +**Step 1: Primary upgrade ask** (matched to trigger). +**Step 2 (if declined): Downsell** (smaller commitment alternative). +**Step 3 (if declined): Soft acknowledgment** ("No problem; here is the link to plans whenever you are ready."). +**Step 4 (later): Cross-sell** (when the user has continued use signals). + +The flow respects each decline before re-engaging at a later moment. + +--- + +## Frequency limits across upsell/downsell + +How often these surface. + +**Within session.** Once primary + once downsell + soft acknowledgment. No more. + +**Across sessions.** Wait days or weeks before re-ask. The user's circumstances may have changed. + +**Per quarter.** Major upgrade pushes per quarter at most. + +--- + +## Conversion economics of upsell vs downsell + +Different patterns have different revenue dynamics. + +**Upsell.** Higher revenue per converted user. Lower conversion rate. + +**Cross-sell.** Adds revenue per existing customer. Conversion depends on fit. + +**Downsell.** Lower revenue per converted user. Higher conversion rate. Captures users who would otherwise stay free. + +**The math question.** Total revenue = (upsell rate × upsell revenue) + (downsell rate × downsell revenue) + (free-to-paid rate × paid revenue). Optimize the sum. + +--- + +## Common upsell/downsell failures + +**Aggressive downsell rounds.** Multiple decline-and-counter loops; user feels manipulated. + +**Downsell that breaks the upsell.** Users learn to decline upsell to get downsell discount. + +**No downsell.** Users decline primary; revenue is zero. + +**Cross-sell fatigue.** Customers see too many cross-sells; resent. + +**Wrong sequencing.** Cross-sell before user has paid first plan. + +**No frequency limits.** Cumulative upgrade asks become spam. + +**Tone-deaf timing.** Downsell after a customer support escalation. + +--- + +## Methodology-level choices that stay in the public skill + +The secondary-path principle. Patterns A through E (upsell, cross-sell, downsell, annual-vs-monthly, seat-count). Downsell discipline. When NOT to downsell. Sequencing logic. Frequency limits. Conversion economics. Common failures. + +## Implementation choices that stay internal + +Specific upsell, cross-sell, downsell flows for specific products. Specific copy. Specific tooling. The team's revenue economics modeling. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/win-back-flow-patterns.md b/skills/upgrade-flow-design/references/win-back-flow-patterns.md new file mode 100644 index 0000000..80eb6ab --- /dev/null +++ b/skills/upgrade-flow-design/references/win-back-flow-patterns.md @@ -0,0 +1,240 @@ +# Win-back flow patterns + +Lapsed users, downgrades, partial-churn re-engagement. + +When users disengage, downgrade, or churn, win-back flows attempt to bring them back. Done well, win-back captures revenue from users who left due to specific (often fixable) reasons; done poorly, win-back becomes spam that confirms the user's decision to leave. + +--- + +## The respect-the-decline principle + +Users who left often left for reasons. Win-back should be honest about the reasons and offer something genuinely changed, not just a discount. + +**The win.** A user lapsed 60 days ago. Win-back email surfaces with: "Since you last logged in, we shipped [specific feature you mentioned wanting]. Want to try it?" The user returns; the value-prop is fresh. + +**The fail.** Same user. Win-back email surfaces with: "We miss you! Come back for 20 percent off." The user dismisses; the discount feels like manipulation; the previous problems remain. + +The discipline. Win-back is most effective when something has changed (new feature, fixed problem) the user would value. + +--- + +## Win-back triggers + +When to fire. + +**User has not logged in for 30 days.** Soft trigger; light re-engagement. + +**User has not logged in for 60-90 days.** Moderate trigger; more substantive re-engagement. + +**User has not logged in for 6+ months.** Aggressive trigger; usually the last attempt before treating as fully churned. + +**User downgraded plan.** Trigger surfaces post-downgrade; win-back attempts to retain the higher tier. + +**User canceled but did not delete account.** Soft trigger; re-engage before full churn. + +**User churned and signed up again.** Different trigger; usually treat as new signup with prior context. + +The triggers vary by product and audience. + +--- + +## Pattern A: Email-based win-back + +Outreach with renewed value-prop. + +**How it works.** + +- Email sent to lapsed user. +- Content focuses on what has changed since they left. +- May include discount or trial extension. + +**Email design discipline.** + +- Subject line concrete; not generic "we miss you." +- Body specific to what has changed. +- One clear CTA back to product. +- Easy unsubscribe; respect users who do not want re-engagement. + +**Strengths.** + +- Cheap; can scale. +- Reaches users outside the product. + +**Weaknesses.** + +- Easy to feel like spam. +- Email deliverability for lapsed users is harder. + +**When to use.** Default for lapsed-user re-engagement. + +--- + +## Pattern B: In-product upon return + +When a lapsed user returns, surface re-engagement help. + +**How it works.** + +- User logs in after long absence. +- In-product surfaces re-orientation and (if appropriate) upgrade-back ask. + +**Design.** + +- Welcome-back banner with what has changed. +- Brief tour of new features added during absence. +- Soft upgrade-back if user downgraded. + +**Strengths.** + +- The user has already returned; engagement is fresh. +- Can be specific to the user's prior usage. + +**Weaknesses.** + +- Misses users who do not return on their own. + +**When to use.** When email or other re-engagement has produced a return. + +--- + +## Pattern C: Personal outreach + +For high-value lapsed users, sales or customer success conversation. + +**How it works.** + +- Customer success or sales reach out directly. +- Often via email or call. +- Conversation about what changed for the user; what would bring them back. + +**Strengths.** + +- Highest engagement potential. +- Surfaces real reasons; can address them. + +**Weaknesses.** + +- Expensive; only viable for high-value accounts. +- Risk of harassment if not done well. + +**When to use.** Enterprise lapsed accounts, high-revenue lapsed customers, accounts with strategic value. + +--- + +## Pattern D: Offer-based win-back + +Discount or trial extension as primary motivator. + +**How it works.** + +- Offer (e.g., 30 percent off, 3 months free, extended trial) presented to lapsed user. +- Limited time; explicit terms. + +**Strengths.** + +- Can move users who left for cost reasons. +- Easy to implement. + +**Weaknesses.** + +- Can train users to lapse intentionally to get discounts. +- Discount alone does not address why they left. + +**When to use.** Sparingly. Combine with value-prop changes; do not lead with discount alone. + +The discount-as-only-strategy failure. Discounts to win back can create reverse incentives. If users learn that lapsing gets them discounts, lapse rate climbs strategically. + +--- + +## Win-back sequence design + +A multi-touch win-back rather than single email. + +**Typical sequence.** + +- Day 30: light re-engagement (what's new). +- Day 60: more substantive (specific feature; case study). +- Day 90: explicit win-back offer (if appropriate). +- Day 120: final outreach; respect non-response. +- Beyond Day 120: treat as fully churned. + +The sequence respects the user's silence; multiple touches at different intensities. + +--- + +## When to abandon win-back + +Some users genuinely do not want to come back. Respect that. + +**Signals to stop.** + +- User unsubscribed from emails. +- User explicitly stated they do not want contact. +- Multiple win-back attempts produced no response. +- User left for reasons unfixable by the product (changed jobs, changed needs). + +**The respect-the-no principle.** Continuing win-back after clear no signals is harassment. + +--- + +## Discount discipline in win-back + +When discounts make sense. + +**Use discount when:** + +- The user explicitly stated cost was a factor. +- The product's price has not changed but the user's situation has. +- A time-limited promotion is genuinely available. + +**Avoid discount when:** + +- The user left for non-cost reasons (poor experience, missing features). +- The discount would train lapse-for-discount behavior. +- The discount cannibalizes existing customer revenue. + +--- + +## Win-back analytics + +Track effectiveness. + +**Metrics.** + +- Re-engagement rate (lapsed users who returned after win-back outreach). +- Conversion rate (returned users who paid or upgraded back). +- Retention of returned users (do they stay or lapse again?). + +**Diagnostic uses.** + +- Low re-engagement: outreach not relevant or not delivered. +- High re-engagement, low conversion: returns happen but value-prop weak. +- Returns lapse again quickly: underlying issue not fixed. + +--- + +## Common win-back failures + +**Generic outreach.** "We miss you" with no specifics; user dismisses. + +**Discount-only strategy.** Discount without value-prop change; trains lapse-for-discount. + +**Frequency overload.** Too many win-back attempts; harassment. + +**No segmentation.** Same outreach to all lapsed users regardless of why they left. + +**Ignoring unsubscribes.** Outreach continues despite explicit no. + +**No measurement.** Cannot tell if win-back works. + +**Returns-lapse-again.** Win-back succeeds short-term; underlying issue persists; user lapses again. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-decline principle. Win-back triggers. Patterns A through D (email, in-product, personal, offer-based). Win-back sequence design. When to abandon. Discount discipline. Win-back analytics. Common failures. + +## Implementation choices that stay internal + +Specific win-back sequences for specific products. Specific outreach copy in brand voice. Specific discount levels. The team's segment-specific approaches. These vary by team and product. diff --git a/skills/usability-testing/SKILL.md b/skills/usability-testing/SKILL.md new file mode 100644 index 0000000..26f0a9e --- /dev/null +++ b/skills/usability-testing/SKILL.md @@ -0,0 +1,238 @@ +--- +name: usability-testing +description: "Plan and run usability tests on existing or prototype designs including test design, task scripts, moderation, observation, and findings synthesis. Use this skill whenever the user wants to test usability, run a moderated test, run an unmoderated test, validate a design, find usability issues, or improve task completion. Triggers on usability test, usability testing, moderated test, unmoderated test, task script, think aloud, prototype testing, user testing, design validation, task completion. Also triggers when the user has built something and wants to know if real users can use it before shipping." +category: research +catalog_summary: "Test design, moderation, findings reports" +display_order: 2 +--- + +# Usability Testing + +Plan and run tests that find usability problems before users hit them in production. Stack-agnostic. Tool-agnostic. + +This skill is for testing existing designs or prototypes. For broader discovery research, use `ux-research`. For conversion testing in production, use `cro-optimization`. + +--- + +## When to use + +- Before launching a new flow or major redesign +- After a redesign to verify it doesn't introduce new problems +- When analytics show drop-off but you don't know why +- When customer support tickets pattern around specific UI areas +- Pre-launch user validation +- Comparing two design directions + +## When NOT to use + +- Discovery / generative research (use `ux-research`) +- Live conversion optimization (use `cro-optimization`) +- Mapping the broader experience (use `journey-mapping`) +- Pure quantitative measurement (use `analytics-strategy`) + +--- + +## Required inputs + +- The design or prototype to test (functional or near-functional) +- Specific tasks users would do +- The audience (who should be tested) +- Testing infrastructure (moderated tool, unmoderated tool, in-person setup) + +--- + +## The framework: 5 phases + +### 1. Define what to test + +Don't test the whole product. Test specific tasks. + +**Task selection criteria:** + +- The task represents a real user goal (not "click around and explore") +- The task has a clear start and end +- The task is achievable in 2 to 10 minutes +- The task is one of: most common, most strategic, most problematic + +**Examples of testable tasks:** + +> "You want to find a contractor near you who can install a fence. Show me how you'd do that on this site." + +> "You're a first-time visitor. You want to understand if this product fits your needs. Walk me through how you'd evaluate it." + +> "Your team needs a new tool to manage projects. Use this site to figure out which plan is right for a 12-person team." + +**Task framing rules:** + +- State the user goal, not the system action ("find a place to stay" not "click the search button") +- Provide context (why are you doing this?) +- Don't reveal the path +- Don't use product terminology in the task framing + +### 2. Choose moderated or unmoderated + +**Moderated** (live, with researcher): + +- Researcher observes and probes in real time +- Best for early-stage prototypes, complex tasks, novel concepts +- Higher cost, smaller sample (5 to 8 participants typical) +- Catches surprises and probe deeper + +**Unmoderated** (recorded, asynchronous): + +- Participant completes alone, often via tool (UserTesting, Maze, Lookback) +- Best for stable designs, simple tasks, larger sample +- Lower cost, larger sample (15 to 30 participants typical) +- Catches patterns at scale, less depth per session + +For most teams: moderated for early/critical decisions, unmoderated for ongoing validation. + +### 3. Recruit + +Target audience - not just convenience. + +**Recruit criteria:** + +- Match real users (target audience, not just "anyone") +- Mix of experience levels with the product (new and existing if applicable) +- Mix of relevant device types (mobile, desktop, tablet if relevant) +- Exclude friends, family, employees + +**Sample size:** + +- Moderated: 5 to 8 participants (Nielsen's "5 users find 85% of usability issues" for the most common segment) +- Unmoderated: 15 to 30 participants (more participants compensate for less probing) +- Multi-segment testing: 5 to 8 per segment + +### 4. Run the test + +**Pre-task setup:** + +- Confirm recording works +- Brief participant (purpose, anonymity, recording, "no wrong answers") +- Get verbal consent +- Have participant share screen if remote + +**Moderated session structure:** + +1. **Warm-up** (2 to 3 min). Easy questions to put participant at ease. +2. **Pre-test questions** (3 to 5 min). Background context, current behavior with similar products. +3. **Task 1** (5 to 10 min). Describe task. Have participant attempt while thinking aloud. +4. **Post-task questions** (1 to 2 min). What was easy/hard? Anything confusing? +5. **Repeat for tasks 2, 3, 4** (typically 3 to 5 tasks per 60-minute session). +6. **Overall debrief** (5 to 10 min). General reactions, comparisons to alternatives, anything else. +7. **Close** (2 min). + +**Moderation principles:** + +- Encourage think-aloud ("What's going through your mind?") +- Don't help unless they're truly stuck (and even then, only after a long pause) +- Don't lead ("Are you looking for the menu?" - bad) +- Note where they hesitate, scroll, or backtrack +- Note their language vs the product's language +- Note emotional reactions + +**Anti-patterns:** + +- Talking too much (researcher should talk maybe 20% of the time) +- Defending the design when participants struggle +- Helping prematurely +- Asking participants to predict their future behavior +- Treating participant suggestions as features ("Users want X" - test demand for X separately) + +### 5. Synthesize and report + +Patterns across participants are signal. Single-participant complaints are weaker (but worth investigating). + +**Synthesis steps:** + +1. **Issue inventory.** Every issue observed, with which participant, which task, severity. +2. **Cluster.** Issues that are the same root problem. +3. **Severity.** + - **Critical:** Blocks task completion. Most users hit this. + - **Major:** Significantly slows task. Many users hit this. + - **Minor:** Friction. Some users hit this. Workaround exists. + - **Cosmetic:** Polish. Doesn't affect task. +4. **Recommendations.** For each issue, propose specific fixes. +5. **Prioritize.** By severity and effort. + +**Report structure:** + +```markdown +# Usability Test: [Design / flow] + +## Summary +[2 to 3 paragraphs covering: what was tested, headline findings, top 3 priorities] + +## Method +[Moderated/unmoderated, sample size, audience, dates, tasks] + +## Critical findings +[Each with description, frequency, supporting evidence (quotes/clips), recommendation] + +## Major findings +[Same structure] + +## Minor findings +[Brief] + +## Cosmetic findings +[Briefest] + +## What worked well +[Calibration: capture successes too] + +## Recommendations +[Prioritized list with effort estimates] + +## Next steps +[Test re-run schedule, design iteration plan] +``` + +--- + +## Workflow + +1. **Define the goals.** What decisions hinge on this? What tasks matter most? +2. **Design tasks.** 3 to 5 specific, realistic, goal-framed tasks. +3. **Choose moderated vs unmoderated.** Match to stage and depth needed. +4. **Recruit.** Specific to audience. +5. **Pilot.** 1 to 2 sessions before main batch. Refine tasks if needed. +6. **Run.** Follow the protocol. Stay disciplined. +7. **Synthesize during, not just after.** Patterns emerge by session 4 or 5. +8. **Report.** Multiple formats - written report + highlight clips. +9. **Track fixes.** Every critical issue should have an owner and date. +10. **Re-test after fixes.** Verify the fix worked, didn't introduce new issues. + +--- + +## Failure patterns + +- **Testing the whole product instead of specific tasks.** Vague results. +- **Tasks that reveal the path.** ("Click the menu and find...") +- **Friends and family as participants.** Biased, not representative. +- **Researcher leading the participant.** Findings reflect the researcher. +- **Defending the design when participants struggle.** Misses real issues. +- **Helping too quickly.** Participant doesn't experience the friction. +- **Treating participant suggestions as features.** Users solve their problem; product team designs the solution. +- **One participant = data point.** A single strong opinion isn't a finding. +- **Skipping severity scoring.** All findings treated equally; team can't prioritize. +- **Reports no one reads.** Highlight clips and live walkthroughs work better than 80-page decks. +- **Testing once, never re-testing.** Fixes that introduce new problems go undetected. + +--- + +## Output format + +Default outputs: + +1. **Test plan** (before testing) - `usability-test-plan-[topic].md` +2. **Task script** (per session) - `usability-tasks-[topic].md` +3. **Findings report** (after synthesis) - `usability-findings-[topic].md` +4. **Highlight clips** (separately produced) + +--- + +## Reference files + +- [`references/task-script-patterns.md`](references/task-script-patterns.md) - Task framing patterns by common product type, with good and bad examples. diff --git a/skills/usability-testing/references/task-script-patterns.md b/skills/usability-testing/references/task-script-patterns.md new file mode 100644 index 0000000..bcc0cd7 --- /dev/null +++ b/skills/usability-testing/references/task-script-patterns.md @@ -0,0 +1,315 @@ +# Task Script Patterns + +Patterns for writing usability test tasks that produce real findings rather than scripted compliance. Includes good and bad examples by common product type. + +--- + +## Universal task framing rules + +### Rule 1: State the user goal, not the system action + +| Bad (system action) | Good (user goal) | +|---|---| +| "Click the search button at the top." | "Find a place to stay in Lisbon for a weekend." | +| "Open the settings menu and change your password." | "You think someone else might know your password. Update it." | +| "Add this product to your cart." | "You want to buy this jacket. Walk me through purchasing it." | + +The system-action version reveals the path. Findings tell you whether the participant could follow instructions, not whether they could use the product. + +### Rule 2: Provide motivating context + +| Bare task | Better with context | +|---|---| +| "Find a hotel in Paris." | "You're planning a 3-day trip to Paris next month for your anniversary. Find a hotel that fits." | +| "Sign up for an account." | "You decided this looks promising and want to try it. Get started." | + +Context shapes how participants approach the task. Without it, they make their own assumptions, often differently from each other. + +### Rule 3: Avoid product terminology + +| Bad (uses our terms) | Good (uses user's terms) | +|---|---| +| "Create a workspace." | "Set this up so your team can collaborate." | +| "Find an experience." | "Find an activity to do this Saturday." | + +If the participant doesn't already know the product's terminology, using it in the task gives them the answer. + +### Rule 4: Don't reveal the path + +| Bad (path revealed) | Good (open) | +|---|---| +| "Use the filters to narrow the results to under $100." | "Find something within your budget of $100." | +| "Click on the FAQ section to find the return policy." | "Find out if you can return this if it doesn't fit." | + +If the path is in the task, you're not testing whether the participant can find the path. + +### Rule 5: Make it specific + +| Bad (vague) | Good (specific) | +|---|---| +| "Try out the product." | "Find out if this product would work for tracking your team's meetings." | +| "Look around." | "Walk me through how you'd evaluate whether this is right for you." | + +Vague tasks produce vague findings. Specific tasks produce actionable findings. + +--- + +## Common pre-test framing + +Use a script for the opening so it's consistent across sessions. + +### Standard opener + +> "Thanks again for joining. As I mentioned, we're testing a [website / app / prototype]. The point is to learn from your experience, not to test you. There are no right or wrong ways to do anything. If you get confused or stuck, that's information for us, not a problem with you. +> +> A few things to know: +> 1. I'll ask you to do some tasks. As you go, please think out loud. Tell me what you're looking at, what you're thinking, what you expect to happen, what's confusing. +> 2. I won't be able to help much during the tasks. The whole point is to see how you'd use this without help. After each task, we'll talk about what was easy and what wasn't. +> 3. We're recording this session for our own notes. The recording stays internal. Sound good? +> +> Any questions before we start?" + +### Pre-task framing + +> "OK, here's the first task. Take your time, think out loud, and there's no rush. +> +> [Read the task aloud, slowly. Send it in chat if remote so they can refer back.] +> +> Go ahead and start whenever you're ready." + +### Mid-task probes (use sparingly) + +When participant is silent for a while: +> "What are you thinking?" + +When participant pauses on something: +> "What's going through your mind right now?" + +When participant takes an unexpected action: +> "What did you expect to happen there?" + +### When participant gets truly stuck + +Wait at least 30 seconds before intervening. Real frustration is signal. + +> "Take a moment. What would you typically do at a point like this?" + +Or: + +> "Is there anything you'd want to do that you're not seeing a way to do?" + +If they're still stuck after another 30 seconds, you can offer a hint: "What might happen if you scrolled?" But this is a last resort. The struggle is the data. + +### Post-task probes + +> "On a scale of 1 to 5, how easy or hard was that?" + +> "What was hardest?" + +> "What was easiest?" + +> "If you could change one thing about how that worked, what would it be?" + +### Closing + +> "Thanks for working through these tasks. Two last questions: +> +> Overall, what's your impression? +> +> If you imagine using this regularly, what would make it work for you? What might keep you from using it? +> +> Anything else you want to mention before we wrap?" + +--- + +## Task patterns by product type + +### Ecommerce + +#### Browse and discovery + +> "You're looking for a gift for a friend who loves cooking. They've been getting into making bread. You have a budget of about $75. Find something that might work." + +[Tests: navigation, search, filtering, product browsing] + +#### Specific product purchase + +> "You've decided to buy [specific product]. Walk me through purchasing it. Stop just before you'd actually enter your payment info." + +[Tests: cart flow, checkout flow, friction points] + +#### Comparison + +> "You're trying to decide between two of these products. Use the site to figure out which one is better for your needs." + +[Tests: comparison features, product pages, decision support] + +#### Returns + +> "You bought something from this store last month. It doesn't fit. Find out how to return it." + +[Tests: help center, account flows, post-purchase support] + +--- + +### SaaS / B2B + +#### Self-service evaluation + +> "You're a [role] at a 30-person company. Your team needs better [tool category]. Use this site to figure out if this is the right fit, and if so, what plan to pick." + +[Tests: positioning, value prop, pricing, evaluation flow] + +#### Onboarding (post-signup) + +> "You just signed up for an account. Walk me through what you'd do next. Try to get to the point where the product would be useful for you." + +[Tests: onboarding, time-to-value, activation friction] + +#### First key task + +> "You're new to this product. Try to [specific key action: create your first project, set up an integration, invite a teammate]. Think out loud as you go." + +[Tests: feature discovery, task completion] + +#### Existing-user task + +> "You're an experienced user of this product. You need to [specific advanced task]. Show me how you'd do that." + +[Tests: depth of features, expert workflows] + +--- + +### Marketplaces + +#### Buyer side: discovery + +> "You need someone to [service]. Find a few options that look good to you." + +[Tests: search, filters, listing pages] + +#### Buyer side: deciding + +> "You've narrowed it down to a few options. Pick the one you'd actually book and walk me through what you'd do next." + +[Tests: details pages, social proof, booking flow] + +#### Seller side: setup + +> "You [run a business / offer a service]. You're considering listing it here. Use this site to figure out how to get started." + +[Tests: onboarding, value prop for the supply side] + +#### Seller side: ongoing + +> "You're an existing seller. You want to [check on inquiries / update your availability / respond to a review]. Show me how you'd do that." + +[Tests: account management, dashboard] + +--- + +### Content / publisher + +#### Reading flow + +> "Read [specific article / topic that interests you]. As you go, tell me what's working or not working about the experience." + +[Tests: readability, page experience, ads, related content] + +#### Discovery + +> "Spend a few minutes exploring this site. Find articles that interest you. Tell me how you decide what to click." + +[Tests: navigation, recommendations, browse paths] + +#### Subscribe + +> "You've decided you want to read more from this publication. Sign up for whatever you think makes sense." + +[Tests: paywall flow, subscription page, account setup] + +--- + +### Mobile app + +#### Initial impression + +> "You just downloaded this app. Open it and start using it. Tell me what you do, what you expect." + +[Tests: app onboarding, initial value] + +#### Specific feature + +> "You want to [specific feature use]. Show me how you'd do that." + +[Tests: feature discovery, mobile-specific patterns] + +#### Push / notification flow + +> "Your phone just buzzed with a notification from this app. Show me what you'd do." + +[Tests: notification design, deep links, post-notification flow] + +--- + +## Task script common pitfalls + +### Pitfall 1: Multiple tasks in one + +> "Sign up, create a project, and invite a teammate." + +This is three tasks. Run as three separate tasks so you can score and analyze each. + +### Pitfall 2: Tasks that aren't realistic + +> "Imagine you're an enterprise CFO evaluating procurement tools." + +If the participant is not a CFO, they're roleplaying. Findings tell you about roleplay, not real CFO behavior. Recruit real CFOs or pick a different task. + +### Pitfall 3: Tasks the participant has already done + +> "Sign up for an account." +> +> Participant: "I already have one." + +Either log them out for the test, or change the task to first-time-user-feeling tasks. + +### Pitfall 4: Tasks tied to specific data the participant doesn't have + +> "Update your billing address." +> +> Participant: "I don't have an account on this site." + +Provide a test account with realistic data, or pick tasks that work for first-time users. + +### Pitfall 5: Asking about future behavior as a task + +> "Tell me what you'd pay for this." + +Hypothetical questions are weak signal. Test actual behavior (do they get to the pricing page? where do they hesitate?) and ask post-task what they'd be willing to pay if useful. + +--- + +## Severity scoring rubric + +Use after testing to score each issue. + +| Severity | Definition | Example | +|---|---|---| +| Critical | Most users cannot complete the task. Hard blocker. | "5 of 6 participants gave up trying to find pricing." | +| Major | Most users complete the task, but with significant struggle. | "4 of 6 participants needed multiple tries to find the search." | +| Minor | Some users hit friction. Most complete the task fine. | "2 of 6 participants paused on the form, but all completed." | +| Cosmetic | Polish issue. No effect on task completion. | "Multiple participants noted a typo." | + +Critical and Major issues block ship. Minor issues prioritize on cost/benefit. Cosmetic gets fixed in normal iteration. + +--- + +## Reporting tips + +- Lead with the **most surprising** finding, not the easiest fix +- Include **at least one quote per major finding** (specifics persuade) +- Include **video clips for critical findings** (no document beats seeing it) +- For each finding, include both **the issue** and **the recommended fix** +- Sort by **severity**, not by section of the product +- Make it **scannable**. Stakeholders skim. diff --git a/skills/user-feedback-aggregation/SKILL.md b/skills/user-feedback-aggregation/SKILL.md new file mode 100644 index 0000000..0336049 --- /dev/null +++ b/skills/user-feedback-aggregation/SKILL.md @@ -0,0 +1,302 @@ +--- +name: user-feedback-aggregation +description: "Collecting and synthesizing user feedback across channels (support tickets, NPS, in-app feedback, sales calls, social mentions, customer councils) into a continuous signal that informs product decisions. The triage discipline that distinguishes loudest-voice (whoever complains most wins) from averaged-noise (every signal weighted equally) from triaged-synthesis (signal weighted by source quality, frequency, and decision relevance). Triggers on user feedback, customer feedback aggregation, NPS, support ticket analysis, customer councils, feedback synthesis, voice of customer, feedback triage, in-app feedback. Also triggers when feedback channels overflow with volume that does not produce decisions, when the loudest-voice problem is steering roadmap, or when continuous feedback streams need synthesis discipline." +category: research +catalog_summary: "Collecting and synthesizing user feedback across channels into continuous decision signal. Triage discipline that distinguishes loudest-voice (whoever complains most) from averaged-noise (every signal weighted equally) from triaged-synthesis (weighted by source quality and decision relevance)" +display_order: 5 +--- + +# User Feedback Aggregation + +A senior product leader's playbook for collecting and synthesizing user feedback across channels into continuous decision signal. Support tickets, NPS surveys, in-app feedback, sales calls, social mentions, customer councils, all aggregated into a triaged synthesis the team can actually act on. + +Most product programs accumulate feedback they do not use. Channels overflow with submissions; CSAT and NPS scores get reported in monthly updates; customer council meetings produce notes that nobody references. The loudest voices steer roadmap because they are easiest to hear; quieter signal that matters more goes unaddressed. + +This skill is the triage discipline that turns continuous feedback streams into continuous decision signal. Each channel surfaces different signal at different reliability. Each signal type warrants different weight in different decisions. The team that aggregates feedback well makes better decisions; the team that drowns in feedback makes the same decisions they would have made without the feedback. + +Different from `discovery-research-synthesis`, which covers one-off research projects (a defined batch of artifacts, a defined synthesis output). This skill covers the always-on streams: feedback that arrives every day, every week, every month, and that the team must continuously triage and synthesize. + +The voice is the senior product leader who has watched feedback aggregation work and watched it fail. Concrete, opinionated about which channels matter for which decisions, willing to call out where loudest-voice or averaged-noise patterns produce bad outcomes. + +When to use this skill: building a feedback aggregation system, auditing a feedback program that is producing volume without decisions, deciding which feedback channels matter for the program, or designing the synthesis cadence for ongoing feedback streams. + +--- + +## What this skill is for + +This skill spans continuous user-feedback aggregation. The PM-skill distinction: + +- `discovery-research-synthesis` is one-off discovery research. Defined batch, defined output. +- **`user-feedback-aggregation` (this skill)** is ongoing feedback streams. Always-on channels needing continuous synthesis. +- `beta-program-management` covers feedback specific to beta participants. This skill spans all users continuously. +- `ux-research` is structured research projects. This skill is unsolicited feedback. +- `pm-spec-writing` is downstream: specs use feedback aggregation as input. +- `roadmap-planning` is downstream: roadmap uses feedback patterns as input. + +The audience: senior PMs, product directors, customer success and support managers running feedback programs, in-house teams aggregating feedback across many channels. + +What is not in scope: structured discovery research (covered by `discovery-research-synthesis`); beta-specific feedback (covered by `beta-program-management`); commissioned research projects (covered by `ux-research`). + +--- + +## Loudest-voice vs averaged-noise vs triaged-synthesis + +The keystone framing. + +**Loudest-voice.** Whoever complains the most gets their feature. Vocal minorities steer roadmap. Silent majority's needs go unaddressed. The squeaky-wheel anti-pattern. Cost: the program optimizes for the loudest customer, not for the broader customer base; quieter customers leave for products that addressed their needs. + +**Averaged-noise.** Every signal weighted equally. 1 enterprise customer's feedback = 1 trial user's feedback = 1 angry social mention. Volume aggregates without weighting; noise drowns signal. Cost: the team cannot tell which feedback matters; decisions get made on aggregate sentiment that does not reflect the customers who matter most for the strategy. + +**Triaged-synthesis.** Signal weighted by source quality, frequency, and decision relevance. Different feedback types have different weights for different decisions. The team that does this well makes decisions grounded in the signal that matters; the team that does it badly defaults to loudest-voice or averaged-noise. + +The litmus test. Pick a recent product decision. Can the team explain why specific feedback signals weighted into the decision the way they did? If yes, the aggregation is triaged. If the answer is "we heard a lot about this from customers," without specificity about which customers in which contexts, the aggregation is loudest-voice or averaged-noise. + +--- + +## Feedback channels and what each surfaces + +Six common channels. Each surfaces different signal at different reliability. + +**Support tickets.** What users hit when things break or confuse them. High volume, high signal-on-friction, biased toward users willing to contact support. + +**NPS surveys.** Aggregate sentiment toward the product or specific features. Periodic, quantitative-with-comments, bias toward respondents who feel strongly (positive or negative). + +**In-app feedback.** Friction at the moment users encounter it. Contextualized to specific product moments; volume varies; quality varies. + +**Sales calls.** Pre-purchase prospect perspective. Objections, competitive mentions, gaps between marketing and what sales leads with. Bias toward prospects, not existing customers. + +**Social mentions.** Public commentary about the product. Real-time but biased toward customers willing to post publicly; often skews negative or hyper-positive. + +**Customer councils.** Curated panels of customers in structured forums. High-quality feedback from selected customers; bias depends on selection. + +Each channel has strengths and weaknesses. Strong feedback aggregation triangulates across channels rather than relying on one. + +Detail in [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md). + +--- + +## Channel-source weighting + +The discipline that distinguishes triaged-synthesis from averaged-noise. + +**The principle.** Different sources warrant different weights in different decisions. + +**Worked example.** A decision about whether to prioritize an enterprise admin feature. + +- Sales call data showing enterprise prospects asking for the feature: high weight (the decision is about enterprise; the source matches). +- Support ticket data from enterprise customers: high weight (existing enterprise customers' friction is directly relevant). +- NPS data from small-team customers: low weight (the feature is not for them; their satisfaction is not load-bearing for the decision). +- Social mentions: variable weight (signal depends on who is mentioning; enterprise practitioners on LinkedIn carry more weight than anonymous trial users on social). + +**The discipline.** For each decision, identify which sources matter most. Weight accordingly. Volume from low-weight sources should not override signal from high-weight sources. + +**The averaged-noise failure.** Decisions made on aggregate volume regardless of source. The enterprise admin feature gets deprioritized because more total feedback came from small-team customers who do not need it; enterprise customers churn because their needs went unaddressed. + +Detail in [`references/channel-source-weighting.md`](references/channel-source-weighting.md). + +--- + +## Categorization and tagging discipline at scale + +How feedback gets organized when it arrives at high volume. + +**The taxonomy.** + +- Feature area or product surface (where in the product the feedback applies). +- Issue type (bug, friction, feature request, positive signal, edge case). +- User segment (who is providing the feedback). +- Severity or urgency (how blocking is it for the user). +- Source channel (where the feedback came from). + +**The discipline.** + +- Tags emerge from feedback patterns, not from a pre-built taxonomy. +- Tags get refined over time as patterns clarify. +- Multiple tags per feedback item; do not force single-category. +- Periodic taxonomy review surfaces categories that need to merge or split. + +**The volume challenge.** A program receiving 500-2000 feedback items per week needs aggregation tooling that supports tagging at scale. Manual tagging at scale burns out the team; AI-assisted tagging with human review on patterns is often the practical middle path. + +Detail in [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md). + +--- + +## Frequency vs intensity + +Two dimensions of feedback signal. + +**Frequency.** How often the same feedback recurs. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +**Intensity.** How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive, or describe satisfaction as transformative. +- Low-intensity feedback: minor friction or mild satisfaction. + +**The matrix.** + +- High-frequency, high-intensity: top priority. Many users hit this; it matters to them. +- High-frequency, low-intensity: papercuts. Address in batches; individual items are minor but cumulatively erode experience. +- Low-frequency, high-intensity: the affected users are deeply impacted but few. Often segment-specific. +- Low-frequency, low-intensity: noise. Capture; do not action individually. + +**The discipline.** Triage assigns each piece of feedback a frequency-intensity assessment. The combination informs prioritization weight. + +Detail in [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md). + +--- + +## From feedback to product decision + +The synthesis loop that turns aggregated feedback into roadmap input. + +**The loop.** + +- Feedback arrives across channels. +- Triage categorizes and weights. +- Periodic synthesis (weekly, monthly, quarterly) surfaces patterns. +- Patterns inform roadmap discussions, spec drafts, prioritization debates. +- Decisions reference specific feedback patterns as input. + +**The cadences.** + +- Daily: critical feedback (security, data loss, broken core flows) handled immediately. +- Weekly: team review of recent patterns. Adjusts current-quarter execution. +- Monthly: synthesis review. Surfaces trending patterns; informs next-quarter roadmap. +- Quarterly: strategic synthesis. Patterns over the quarter inform strategic planning. + +**The discipline.** Feedback aggregation has cadence. Without cadence, feedback accumulates without producing decisions. + +Detail in [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md). + +--- + +## Closing the loop with users + +When feedback shapes product, telling users matters. + +**The practice.** + +- When feedback drives a change, communicate to the users who provided that feedback. +- "We heard from many of you that X was painful; we shipped Y this week to address it. Thanks for the feedback that informed this work." +- Communication can be public (release notes, blog posts) or targeted (email to users who opened tickets on the issue). + +**Why it matters.** + +- Users who see their feedback acted on engage more in the future. +- The closed loop signals that the team is listening, which strengthens the relationship. +- Users without feedback follow-through stop providing feedback over time. + +**The risk of over-promising.** Promising changes that do not ship erodes trust faster than not promising. Communicate what shipped, not what might ship. + +Detail in [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md). + +--- + +## Detecting drift in feedback patterns over time + +What changes in feedback signal over time can reveal. + +**Drift patterns.** + +- Increasing feedback volume in a category: either the issue is worsening, the user base is growing, or awareness of the channel is increasing. Investigate the cause. +- New patterns emerging: previously-rare feedback becomes more common. Often signals product or market change. +- Patterns disappearing: feedback that used to be common stops. The issue may be resolved, or users may have given up reporting it. +- Sentiment shifts: NPS or CSAT trending differently than before. Often signals broader experience changes. + +**The investigation discipline.** Drift signals warrant investigation. Why did the volume increase? Why did this pattern emerge? The root cause often informs product decisions more than the surface signal. + +Detail in [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md). + +--- + +## Feedback aggregation tooling considerations + +Tooling choices without endorsing specific products. + +**Tooling categories.** + +- Customer feedback platforms (aggregate across multiple sources, support tagging, surface patterns). +- Support ticket systems with analytics layers. +- NPS or survey platforms with response aggregation. +- Customer relationship management systems with feedback fields. +- Custom dashboards combining feedback signal with usage analytics. + +**The criteria for tooling selection.** + +- Does it support multi-channel aggregation, or is it single-channel? +- Does it support tagging at scale? +- Does it surface patterns, or is it just storage? +- Does it integrate with the team's other systems (roadmap, ticketing, communication)? +- Does it scale with program volume? + +**The build-vs-buy tension.** Many programs end up with a mix: dedicated tooling for some channels, custom dashboards for cross-channel synthesis. Pure single-tool solutions often miss the multi-channel pattern detection. + +Detail in [`references/tooling-considerations.md`](references/tooling-considerations.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md). + +- "Loudest customers steer the roadmap." Loudest-voice pattern; vocal minorities dominate; silent majority underaddressed. +- "We have lots of feedback but no decisions." Aggregation without synthesis; no triage cadence. +- "Our channels overflow; we cannot keep up." Aggregation without weighting or tooling that scales. +- "Different teams cite different feedback for the same decision." Channel-source weighting absent; teams reach for whatever feedback supports their position. +- "Customer council meetings produce notes nobody references." Council without synthesis loop; the meeting is the deliverable. +- "NPS is reported monthly but does not inform decisions." NPS as compliance metric, not as decision input. +- "Feedback we shipped against did not move sentiment." Wrong feedback prioritized; the loud feedback was not the most consequential. +- "Users gave feedback once and never returned." Closed-loop missing; users feel ignored. +- "We tagged everything but cannot find patterns." Taxonomy too granular or too noisy; periodic taxonomy review missing. +- "Drift in feedback caught us by surprise." Drift detection missing; the team did not investigate trending patterns until they became problems. +- "Sales call data and support ticket data tell different stories." Cross-channel synthesis missing; each channel's signal stays in its own silo. + +--- + +## The framework: 12 considerations for feedback aggregation + +When designing or auditing a feedback aggregation system, walk these 12 considerations. + +1. **Triaged-synthesis, not loudest-voice or averaged-noise.** Signal weighted by source, frequency, decision relevance. +2. **Channel taxonomy known.** Support, NPS, in-app, sales, social, councils. What each surfaces. +3. **Channel-source weighting per decision.** Different decisions weight channels differently. +4. **Categorization and tagging at scale.** Taxonomy that emerges from data; tooling that supports volume. +5. **Frequency-intensity matrix.** Each feedback item assessed on both dimensions. +6. **Synthesis cadence.** Daily critical, weekly patterns, monthly review, quarterly strategic. +7. **Cross-channel triangulation.** Patterns that appear across channels are stronger. +8. **Closing the loop with users.** When feedback drives change, communicate. +9. **Drift detection.** Patterns over time reveal changes. +10. **Tooling that scales.** Multi-channel aggregation, pattern surfacing, integration. +11. **Specific feedback informs specific decisions.** Decisions traceable to specific signals. +12. **Honest assessment of source bias.** Each channel's bias acknowledged in synthesis. + +The output of the framework is feedback aggregation that produces decision-grade signal continuously, scales with program volume, and treats users well enough that they keep providing feedback over time. + +--- + +## Reference files + +- [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md) - Six common channels with strengths, weaknesses, biases, and synthesis implications. +- [`references/channel-source-weighting.md`](references/channel-source-weighting.md) - Decision-relative weighting. Worked examples of how channels weight differently for different decisions. +- [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md) - Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. +- [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md) - The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. +- [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md) - The synthesis loop. Cadences. The discipline of decisions traceable to feedback. +- [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md) - When and how to communicate feedback-driven changes. The over-promising risk. +- [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md) - Drift patterns. Investigation discipline. Drift as early signal of change. +- [`references/tooling-considerations.md`](references/tooling-considerations.md) - Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. +- [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: feedback as continuous signal, not periodic survey + +The teams that make good product decisions over time are the ones that aggregate feedback continuously and synthesize it into decision input. Not as compliance with a feedback-collection mandate; not as monthly NPS reporting; not as ad-hoc reactions to whoever complains loudest. As a continuous discipline that surfaces what users are actually experiencing, weighted appropriately, synthesized for the decisions the team is actually making. + +Feedback aggregation done well is invisible: the team makes better decisions, but the feedback work itself does not feel heroic. Feedback aggregation done badly is loud: channels overflow, NPS gets reported, customer councils produce decks, and decisions still get made on gut feel because the feedback work did not produce decision input. + +The discipline is in the triage. Each channel weighted by what it reveals. Each piece of feedback assessed on frequency and intensity. Patterns surfaced through synthesis. Decisions traceable to specific feedback. The closed loop with users that keeps feedback flowing. + +When in doubt about whether a feedback program is working, ask: can the team trace recent decisions to specific feedback patterns, are channels weighted differently for different decisions, is the synthesis cadence producing input the team uses, are users seeing their feedback acted on? If yes to all of those, the program is real. If no to any, the gap is where the feedback work is failing to convert into decisions. diff --git a/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md b/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md new file mode 100644 index 0000000..5faac7a --- /dev/null +++ b/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md @@ -0,0 +1,213 @@ +# Categorization and tagging at scale + +Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. + +How feedback gets organized when it arrives at high volume. The discipline that prevents the "we tagged everything but cannot find patterns" failure. + +--- + +## The taxonomy dimensions + +Each feedback item gets tagged across multiple dimensions. + +**Feature area or product surface.** Where in the product the feedback applies. Examples: onboarding, dashboard, billing, integrations, mobile app. + +**Issue type.** Bug, friction, feature request, positive signal, edge case. + +**User segment.** Who is providing the feedback. Examples: free tier, pro tier, enterprise, trial, churned. + +**Severity or urgency.** How blocking is the issue. Examples: critical (blocks core flow), high (significant friction), medium (workaround exists), low (minor). + +**Source channel.** Where the feedback came from. Examples: support ticket, NPS comment, in-app widget, sales call, social mention, customer council. + +**Date or time period.** When the feedback was submitted. Useful for drift detection. + +Most programs use 3-6 of these dimensions. More dimensions produce richer queries; more dimensions also increase tagging burden. + +--- + +## Tags emerge from data, not from a pre-built taxonomy + +The same principle as discovery research synthesis (see `discovery-research-synthesis`). + +**The pattern.** Tags emerge from feedback patterns. Initial tagging captures what users actually said; the taxonomy builds up from the data. + +**The anti-pattern.** Pre-built taxonomies that force feedback into categories. Patterns the taxonomy did not anticipate get missed; categories that do not match the data get used anyway. + +**Why emergent tagging matters.** + +- Users describe issues in their own language; pre-built categories often miss the actual issues. +- New product features generate new categories; emergent tagging adapts. +- Issues evolve over time; emergent tagging captures the evolution. + +**The transition.** Programs starting feedback aggregation often need a starting taxonomy to begin with. The starting taxonomy is provisional; it gets refined as feedback accumulates and patterns clarify. + +--- + +## Multiple tags per feedback item + +Most feedback items deserve multiple tags. + +**The pattern.** A single feedback item often touches multiple feature areas, issue types, or context dimensions. + +**Worked example.** Support ticket: "I'm an enterprise admin trying to set up SSO for the team and the configuration step keeps timing out." + +Tags: + +- Feature area: SSO configuration, admin settings. +- Issue type: bug (timeout) + friction (configuration is hard). +- User segment: enterprise. +- Severity: high (blocks core enterprise setup). +- Source channel: support ticket. + +Multiple tags capture the feedback's full context. Single-tag forcing loses information. + +--- + +## Tagging at volume + +Programs receiving 500-2000+ feedback items per week need tooling support. + +**Tooling approaches.** + +- **Manual tagging.** Each item tagged by a human. Highest quality; lowest scale. Works for low-volume programs (under 100 items per week). +- **AI-assisted tagging.** AI suggests tags; humans review and adjust. Scales better; quality depends on the AI's training and the team's review discipline. +- **Automated tagging.** AI tags without human review. Scales highest; quality is lowest because no one validates. +- **Hybrid.** Manual tagging for high-priority items (enterprise feedback, critical issues), AI-assisted for the bulk. + +**The recommended pattern for most programs.** AI-assisted tagging with human review on patterns. The AI handles bulk classification; humans review aggregate patterns and validate that the categorization is producing useful signal. + +**The volume calibration.** + +- Under 100 items/week: manual tagging is feasible and preferred. +- 100-500 items/week: AI-assisted with sample review. +- 500+ items/week: AI-assisted with pattern review; manual handling reserved for high-priority items. + +--- + +## Tag quality vs tag granularity + +Two competing pressures. + +**Granularity helps.** More specific tags surface more specific patterns. "Onboarding configuration step 3 friction" is more useful than "onboarding friction." + +**Granularity also harms.** More specific tags fragment data. If 10 different tags split what should be one pattern, the pattern is invisible. + +**The middle path.** + +- Start with moderate granularity. +- Refine over time. Tags that consistently co-occur may need to merge; tags that combine distinct patterns may need to split. +- Periodic taxonomy review (see below) catches granularity issues. + +--- + +## Periodic taxonomy review + +Quarterly or bi-annual review of the taxonomy. + +**The questions.** + +- Are there tags that consistently co-occur and could merge? +- Are there tags that contain multiple distinct patterns and should split? +- Are there new patterns that need new tags? +- Are there tags that no longer apply (deprecated features, resolved issues)? +- Is the taxonomy too granular (fragmenting patterns) or too coarse (hiding patterns)? + +**The output.** A revised taxonomy. Old tags may get retired; new tags may get added; some tags may get renamed. + +**The discipline.** Without periodic review, taxonomies decay. Old tags accumulate; new patterns get tagged into wrong categories; the taxonomy stops surfacing useful patterns. + +**The frequency.** Quarterly works for most programs. Annual works for stable programs with low product change rate. Bi-annual works as a middle path. + +--- + +## Tag conflicts and resolution + +Sometimes feedback could be tagged in multiple ways. + +**Resolution approaches.** + +- **Multi-tagging.** When in doubt, apply multiple tags. Captures the ambiguity rather than forcing a choice. +- **Convention.** Document conventions for ambiguous cases. "Friction with the dashboard's filter functionality" gets tagged "dashboard" + "filtering" + "friction" rather than choosing. +- **Reviewer judgment.** Train reviewers (human or AI) on conventions. Ambiguous cases get reviewed for consistency. + +**The cost of inconsistent tagging.** Patterns become invisible because the same kind of feedback gets tagged differently. The "we tagged everything but cannot find patterns" failure often traces to inconsistent tagging. + +--- + +## Tag distribution as signal + +The distribution of tags across feedback can be informative beyond individual tags. + +**Examples.** + +- Spike in volume on a specific tag: trending issue or feature area in flux. +- Decline in volume on a tag: issue resolved or users gave up reporting. +- Co-occurrence patterns: tags that consistently appear together suggest related issues. +- Segment-specific tag distributions: enterprise vs free-tier feedback patterns differ. + +**The dashboard view.** Most feedback aggregation tooling supports tag-distribution dashboards. The dashboards surface patterns the team would not see in individual feedback items. + +--- + +## Tagging discipline at the channel level + +Different channels need different tagging conventions. + +**Support tickets.** Often pre-tagged by the support system (issue type, product area). Augment with feedback-specific tags. + +**NPS comments.** Lighter tagging. Often just sentiment + topic area. Open-ended comments are mined for patterns; not every comment needs comprehensive tagging. + +**In-app feedback.** Auto-tagged by context (which page, which feature). Augment with issue-type and severity. + +**Sales calls.** Often summarized rather than tagged at the moment level. Summaries get tagged. + +**Social mentions.** Auto-classified by sentiment and topic; manual review for high-impact mentions. + +**Customer council notes.** Manually tagged after each council session. Higher tagging investment because volume is low and signal is high. + +--- + +## Cross-channel tag consistency + +Tags should mean the same thing across channels. + +**The risk.** "Onboarding friction" in support tickets means something slightly different than "onboarding friction" in NPS comments because the channels surface different aspects. + +**The mitigation.** + +- Document tag definitions explicitly. "Onboarding friction" includes X, Y, Z signals. +- Periodic cross-channel calibration. Review tagged samples from each channel to ensure consistency. +- Channel-specific sub-tags where appropriate. "Onboarding-friction-support" vs "Onboarding-friction-nps" if the distinction matters. + +**The honest framing.** Cross-channel tag consistency is hard. Strong programs work toward it; perfect consistency is rare. + +--- + +## Common tagging failures + +**Pre-built taxonomy forced.** Patterns the taxonomy did not anticipate get missed. + +**Single-tag forcing.** Multi-dimensional feedback gets reduced to one tag; information lost. + +**Inconsistent tagging.** The same kind of feedback gets tagged differently across reviewers or time periods. + +**Tag bloat.** Too granular; patterns fragment across many tags. + +**Tag coarseness.** Too broad; distinct patterns hide within the same tag. + +**No taxonomy review.** Tags decay over time without periodic review. + +**Volume overwhelms tagging.** High-volume programs without tooling support; tagging falls behind; old feedback never gets tagged. + +**Tag-without-purpose.** Tagging happens because it is supposed to; nobody uses the tags for synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The taxonomy dimensions. Emergent tagging. Multi-tag discipline. Tagging at volume (manual, AI-assisted, automated, hybrid). Tag quality vs granularity tradeoffs. Periodic taxonomy review. Tag conflict resolution. Tag distribution as signal. Channel-specific tagging. Cross-channel consistency. Common failures. + +## Implementation choices that stay internal + +Specific tagging tools and AI models. Specific tag definition documents. Specific reviewer training. Specific dashboard configurations. The team's own conventions for tagging within the principles. These vary by team. diff --git a/skills/user-feedback-aggregation/references/channel-source-weighting.md b/skills/user-feedback-aggregation/references/channel-source-weighting.md new file mode 100644 index 0000000..aac3763 --- /dev/null +++ b/skills/user-feedback-aggregation/references/channel-source-weighting.md @@ -0,0 +1,216 @@ +# Channel-source weighting + +Decision-relative weighting. Worked examples of how channels weight differently for different decisions. + +The discipline that distinguishes triaged-synthesis from averaged-noise. Different sources warrant different weights for different decisions; treating all sources as equal produces decisions made on aggregate volume rather than on signal that matters. + +--- + +## The weighting principle + +Each piece of feedback has a source. The source's weight in a decision depends on how relevant the source is to that decision. + +**Worked principle.** A piece of feedback from an enterprise customer has different weight than a piece of feedback from a trial user when the decision is about enterprise pricing. The enterprise customer's feedback is high-weight; the trial user's feedback is low-weight (they are not the audience for the decision). + +The same piece of feedback from a trial user has different weight when the decision is about trial conversion. Now the trial user is the audience; their feedback is high-weight. + +The weighting is decision-relative, not source-absolute. + +--- + +## Worked examples of channel weighting + +### Decision: Should we prioritize the enterprise admin role overhaul this quarter? + +**Audience for the decision.** Existing enterprise customers and enterprise prospects. + +**Channel weights for this decision.** + +- Sales call data with enterprise prospects: high weight. They directly inform the decision. +- Support ticket data from enterprise customers: high weight. Existing enterprise friction is directly relevant. +- Customer council data from enterprise members: high weight. Curated enterprise perspective. +- NPS data from enterprise customers: moderate weight. Aggregate signal but not specific to admin features. +- NPS data from small-team customers: low weight. Different segment; admin features not relevant. +- Social mentions: variable weight. Enterprise practitioners' posts higher than anonymous trial accounts. +- In-app feedback from small-team users: low weight. Different segment. + +The decision weighs enterprise sources heavily. Volume from non-enterprise sources should not displace enterprise signal. + +### Decision: Should we redesign the onboarding flow for new free-tier signups? + +**Audience for the decision.** Free-tier new signups. + +**Channel weights for this decision.** + +- Support tickets from free-tier users in their first week: high weight. Direct friction signal. +- In-app feedback from free-tier users during onboarding: high weight. Moment-of friction. +- NPS data from free-tier users: moderate weight. Aggregate sentiment. +- Sales call data: low weight. Sales calls are usually with prospects, not free signups; pre-decision conversation differs from post-signup experience. +- Customer council data: low weight. Councils usually have established customers, not new signups. +- Support tickets from long-tenured customers: low weight. Their onboarding friction was a year ago; current onboarding may differ. + +The decision weighs new-signup sources heavily. Long-tenured customer feedback is informative for other decisions but not this one. + +### Decision: Should we launch a new pricing tier? + +**Audience for the decision.** Both prospects and existing customers (existing customers may move tiers; prospects' tier choice affects acquisition). + +**Channel weights for this decision.** + +- Sales call data on pricing conversations: high weight. Prospects' pricing perception is critical. +- Support tickets about pricing or upgrade requests: high weight. Existing customer pricing pain points. +- Customer council discussion on pricing: high weight. Strategic discussion with curated customers. +- NPS data with pricing comments: moderate weight. Some signal but not decision-specific. +- Social mentions about pricing: moderate weight. Public perception affects acquisition. +- In-app feedback unrelated to pricing: low weight. Off-topic for this decision. + +Multiple high-weight channels because the decision spans audiences. + +### Decision: Should we invest in social mention monitoring as a primary channel? + +**Audience for the decision.** Strategic question about feedback aggregation infrastructure. + +**Channel weights for this decision.** + +- Past examples of social signal driving decisions: high weight. Direct evidence. +- Past examples where social signal misled (vocal minority, anonymous accounts): high weight as counter-evidence. +- Other companies' published patterns on social signal: moderate weight. Indicative but not specific. +- Internal team intuition about social signal: low weight unless backed by data. + +The decision weighs evidence of past signal-driven decisions heavily. + +--- + +## The averaged-noise failure + +When sources are weighted equally regardless of decision relevance. + +**The pattern.** + +- The team aggregates all feedback equally. +- Volume from any source counts the same. +- The most-feedback issue gets prioritized regardless of source. + +**Why it fails.** + +- Decisions get made on aggregate volume rather than on signal that matters for that decision. +- Decisions that should be enterprise-driven get displaced by volume from segments that do not matter for that decision. +- The team optimizes for the squeaky-wheel signal because it is loudest in the aggregate. + +**Worked failure.** The team is deciding whether to prioritize enterprise admin features. NPS and in-app feedback show low priority for this area (because most respondents are small-team users who do not need enterprise admin). Sales calls and enterprise support tickets clearly indicate the priority. The team aggregates volume, sees more total feedback against enterprise admin priority, and deprioritizes. Enterprise customers churn. + +**The cure.** Weight by decision relevance. Enterprise channels weight high for enterprise decisions; small-team feedback should not displace enterprise signal on enterprise decisions. + +--- + +## The loudest-voice failure + +When the most vocal source dominates regardless of representativeness. + +**The pattern.** + +- A small number of customers complain frequently and loudly. +- Their feedback dominates synthesis because they generate the most volume. +- Their preferences shape the roadmap. + +**Why it fails.** + +- Vocal minorities do not represent the broader user base. +- Silent majority's needs go unaddressed. +- The roadmap optimizes for the customers most likely to complain rather than the customers most strategic for the business. + +**The cure.** Weight by source quality and representativeness, not by volume. A complaint repeated 50 times by one user is not 50x the signal of one complaint by 50 distinct users. + +--- + +## How to set weights + +In practice, weighting is qualitative. Quantitative scoring schemes often produce false precision. + +**The discipline.** + +- For each decision, identify the audience (who the decision serves). +- Identify which channels surface signal from that audience. +- Identify which channels do not (and why their feedback is less relevant for this decision). +- In synthesis, give high-weight channel signal more attention than low-weight channel signal. + +**Quantitative weighting risks.** + +- Scoring systems (this channel = 3x weight; that channel = 1x) often produce false precision. +- Decisions made on weighted scores rather than on judgment can miss qualitative nuances. +- The discipline is qualitative judgment informed by source-relevance, not arithmetic. + +**The honest framing.** Weighting is a judgment call. The synthesis names the weighting choices explicitly: "We weighted enterprise channel signal heavily here because the decision is about enterprise priorities." Readers can disagree with the weighting; disagreement is productive. + +--- + +## Source bias acknowledgment + +Each source has biases that affect its signal. + +**Sources skew toward.** + +- Support: users willing to contact support; tend toward problem-reporting. +- NPS: users with strong opinions; middle-ground underrepresented. +- In-app feedback: users who interact with widgets; specific segments may dominate. +- Sales calls: prospects, not existing customers; pre-purchase context. +- Social: users who post publicly; enthusiasts and angry voices. +- Councils: curated members; specific selection criteria. + +**The synthesis discipline.** When weighting, acknowledge the bias. "Support tickets show high friction in this area" should be paired with "noting the support-channel bias toward users who contact support." The acknowledgment makes synthesis more honest and readers more informed. + +--- + +## Multi-channel triangulation as weighting + +When patterns appear across multiple channels, weighting becomes easier. + +**Strong cross-channel signal.** Same pattern in support, NPS, in-app, and sales. The cross-channel pattern survives any single channel's bias. + +**Single-channel signal.** Pattern in only one channel. Weighting depends on channel reliability for the decision; treat with more caution. + +**Conflicting cross-channel signal.** Different channels disagree. Investigate the source of the conflict; the disagreement often reveals segment differences or context-specific patterns. + +The discipline. Cross-channel triangulation is a form of weighting: patterns that survive multiple channels' biases are more reliable signal. + +--- + +## Weighting in tooling + +Some feedback aggregation tools support explicit weighting (priority scores, segment-specific dashboards). + +**Tooling support.** + +- Tagging by source channel and segment. +- Filtering and grouping by tag combinations. +- Dashboards that show signal per segment or channel. + +**The tooling principle.** Tooling supports weighting; the weighting judgment still belongs to humans. Tools that automate weighting away from human judgment risk false precision. + +**The build-vs-buy tension.** Many programs end up with custom dashboards or filtering that supports their specific weighting. Generic tooling rarely supports the program's specific decision-relative weighting needs out of the box. + +--- + +## Common weighting failures + +**No weighting.** All sources treated equally. Averaged-noise pattern. + +**Static weighting.** Same weights regardless of decision. Misses that different decisions need different weights. + +**Quantitative false precision.** Scoring systems that produce decisions without judgment. + +**Volume as proxy for weight.** Loudest-voice pattern; whoever generates most feedback wins. + +**Bias acknowledgment skipped.** Synthesis claims stronger signal than the channel's bias warrants. + +**Single-channel reliance.** Decisions made on one channel's signal without triangulation. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relative weighting principle. Worked weighting examples for different decisions. The averaged-noise and loudest-voice failures. How to set weights. Source bias acknowledgment. Multi-channel triangulation. Weighting in tooling. Common failures. + +## Implementation choices that stay internal + +Specific weighting conventions for specific decision types. Specific tooling that supports weighting. Specific dashboard configurations. The team's own conventions for naming weighting choices in synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md b/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md new file mode 100644 index 0000000..c2c0ec3 --- /dev/null +++ b/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md @@ -0,0 +1,263 @@ +# Channel types and what each surfaces + +Six common feedback channels with strengths, weaknesses, biases, and synthesis implications. Each channel surfaces different signal at different reliability; strong aggregation triangulates across channels. + +--- + +## Channel 1: Support tickets + +What users hit when things break or confuse them. + +**What support surfaces.** + +- Functional friction (where the product breaks down for users). +- Documentation gaps (questions users ask repeatedly). +- Feature requests that arrive in the form of complaints. +- Edge case failures. +- Confusion about intended behavior vs actual behavior. + +**Strengths.** + +- High volume; signal accumulates from many users. +- Grounded in specific user contexts (the user was trying to do something specific). +- Captures friction users actually encountered, not friction they speculated about. + +**Weaknesses.** + +- Bias toward users willing to contact support. Users who silently leave the product do not appear here. +- Bias toward fixable issues. Users who struggle but figure it out (or give up) without contacting support are invisible. +- Sentiment skew: users contact support when frustrated; positive experience is underrepresented. + +**Synthesis implications.** + +- Support volume on a feature area is a strong signal of friction; absence of volume is weak signal of satisfaction. +- Pattern-detection across tickets reveals systemic issues better than individual tickets. +- Combine with usage analytics: a feature with high support volume and low usage suggests broken value; high support volume and high usage suggests meaningful friction in something users still want. + +--- + +## Channel 2: NPS surveys + +Aggregate sentiment toward the product or specific features. + +**What NPS surfaces.** + +- Aggregate sentiment trend lines. +- Distribution between promoters, passives, and detractors. +- Open-ended comments (often the most useful part). +- Sentiment differences across segments. + +**Strengths.** + +- Quantitative signal that aggregates across many users. +- Trends over time reveal whether sentiment is improving or degrading. +- Open-ended comments provide qualitative depth. +- Industry-standard metric makes benchmarking possible. + +**Weaknesses.** + +- Response bias. Users with strong opinions (positive or negative) respond at higher rates than users in the middle. +- Cultural and segment biases in scoring (some segments score lower on average than others for cultural reasons). +- The 0-10 scale loses granularity; many decisions need more than promoter/passive/detractor categorization. +- Surveys on specific features can have small sample sizes that produce noisy signal. + +**Synthesis implications.** + +- NPS as a single number is less useful than NPS distribution and trend. +- Open-ended comments are often the highest-value section; mine them for patterns. +- Segment-specific NPS is more actionable than aggregate NPS. +- Single-quarter NPS shifts can be noise; multi-quarter trends are more reliable signal. + +--- + +## Channel 3: In-app feedback + +Friction at the moment users encounter it. + +**What in-app feedback surfaces.** + +- Contextual friction (the user was at a specific moment in the product when they submitted). +- Ratings or sentiment scoped to specific features or flows. +- Quick observations users would not bother to file as a ticket. + +**Strengths.** + +- Captures the moment. Friction is fresh; context is automatic (the system knows where the user was). +- Lower friction submission than support tickets; surfaces issues users would not formally report. +- Volume varies; some products see high in-app feedback, others minimal. + +**Weaknesses.** + +- Bias toward users who interact with the feedback widget. Some segments use it heavily; others rarely. +- Quality varies. Quick submissions are often shallow. +- Volume can overwhelm if the widget triggers too aggressively. + +**Synthesis implications.** + +- In-app feedback is best for detecting moment-specific friction. +- Pair with usage analytics: where users submit feedback in the product is informative. +- Filter by submission length and pattern; one-word submissions ("frustrating!") are weak signal compared to specific submissions ("I expected the export to include the filters I had applied; it did not"). + +--- + +## Channel 4: Sales calls + +Pre-purchase prospect perspective. + +**What sales calls surface.** + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Prospect vocabulary for describing their situation (often different from internal product language). + +**Strengths.** + +- Prospect view of the product before they have invested in it. Reveals what attracts and what blocks adoption. +- Competitive intelligence in the form of comparisons prospects make. +- Hire criteria signal (why prospects would choose the product). + +**Weaknesses.** + +- Bias toward prospects, not existing customers. Existing-customer experience differs. +- Sales-team interpretation can color how calls are tagged. +- Stage selection matters: early-stage discovery calls reveal different things than late-stage closing calls. + +**Synthesis implications.** + +- Sales call data informs positioning, pricing, and adoption-hire-criteria decisions. +- Combine with existing-customer feedback to understand the full lifecycle. +- Lost-deal analysis (specifically, calls with prospects who did not buy) is a separate research mode that surfaces what the product would need to win. + +--- + +## Channel 5: Social mentions + +Public commentary about the product. + +**What social mentions surface.** + +- Public sentiment in real time. +- Comparison to competitors (often more honest than survey responses). +- Use cases and use contexts the team did not anticipate. +- Reputation signals (how the product is perceived in the broader market). + +**Strengths.** + +- Real-time signal. +- Public visibility means the team can respond to issues that affect brand reputation. +- Captures users who post publicly but would not file feedback through formal channels. + +**Weaknesses.** + +- Bias toward users willing to post publicly. Often skews toward enthusiasts (positive) or angry (negative); middle-ground users are quiet. +- Volume can overwhelm; signal-to-noise ratio is low. +- Anonymous accounts complicate weighting (who is this person? are they a real customer?). +- Platform algorithms shape what is visible; the visible signal is not the full signal. + +**Synthesis implications.** + +- Social signal is one input, rarely a primary driver. Triangulate with other channels. +- Track reputational themes (what the product is known for in the broader market). +- Respond to specific issues that affect brand reputation; do not use social as the primary feedback prioritization channel. + +--- + +## Channel 6: Customer councils + +Curated panels of customers in structured forums. + +**What customer councils surface.** + +- Curated customer perspective on strategic questions. +- Deep discussion that reveals motivations and priorities. +- Cross-customer patterns (council members compare notes; the team sees what they share). +- Long-term relationship signal (council members commit time and engagement). + +**Strengths.** + +- High-quality feedback from selected customers. +- Structured forum makes discussion deeper than ad-hoc feedback. +- Council members often become advocates and references. + +**Weaknesses.** + +- Bias depends on selection. A council selected for size, role, or vocal customers will skew accordingly. +- Council members are often outliers (engaged, willing to commit time); their perspective may not represent broader users. +- Small sample size (usually 5-30 members); patterns from one council are weak signal. +- Cost: councils require curation, scheduling, and ongoing relationship management. + +**Synthesis implications.** + +- Council feedback is valuable but limited; do not treat as representative of the full user base. +- Use councils for strategic discussions, not for tactical prioritization. +- Council patterns can be a leading indicator of broader user patterns; validate with other channels. + +--- + +## Channels not covered here + +Some feedback channels are out of scope for this skill but worth naming. + +**Beta participants.** Covered by `beta-program-management`. Beta feedback is bounded to the beta period; this skill covers ongoing streams. + +**Discovery research interviews.** Covered by `discovery-research-synthesis`. One-off research projects, not always-on streams. + +**App store reviews.** A specific channel for consumer products. Similar dynamics to social mentions: public, biased toward strong opinions, real-time but volume-heavy. + +**Customer success quarterly business reviews.** Often produce structured customer feedback; can be treated as a council-like channel for top customers. + +**Internal employee feedback.** Sometimes valuable (employees are users of internal tools, or use the product alongside customers); always biased toward internal context. + +--- + +## Cross-channel triangulation + +Patterns that appear across channels are stronger than patterns from a single channel. + +**Worked example.** A feature area showing: + +- Support tickets: increasing volume in this area. +- NPS comments: this area mentioned negatively in detractor comments. +- In-app feedback: friction submissions in this area. +- Sales calls: prospects asking about this area as a comparison point against competitors. + +The cross-channel pattern is stronger than any single-channel signal. The feature area is a load-bearing issue across multiple lenses. + +**Worked counter-example.** A loud single-channel signal: + +- Social mentions: vocal complaints about a feature. +- Support tickets: minimal volume on the same feature. +- NPS: feature not flagged in detractor comments. +- Sales calls: feature not raised by prospects. + +The cross-channel pattern shows the social signal is loud but not load-bearing. Loud-on-one-channel-only is often vocal-minority signal. + +--- + +## Channel reliability calibration + +Different channels have different reliability for different kinds of decisions. + +**Functional friction decisions.** Support tickets and in-app feedback are most reliable. NPS is moderate. Social and sales are less reliable. + +**Adoption hire-criteria decisions.** Sales calls are most reliable. Support tickets and in-app feedback are less reliable (existing-customer bias). + +**Positioning decisions.** Sales calls and social mentions are most reliable (prospect/public perception). NPS and councils are moderate. + +**Strategic prioritization.** Customer councils and NPS trends are useful inputs. Support tickets indicate friction but not strategic priority. + +**Reputation decisions.** Social mentions are direct signal. Support and NPS are indirect. + +The discipline. For each decision, identify which channels are most reliable. Weight accordingly. + +--- + +## Methodology-level choices that stay in the public skill + +The six channel types with strengths, weaknesses, biases, and synthesis implications. Channels not covered. Cross-channel triangulation. Channel reliability calibration for different decision types. + +## Implementation choices that stay internal + +Specific tooling per channel. Specific tagging schemas. Specific integration patterns across channels. The team's own conventions for channel coverage. These vary by team and tooling. diff --git a/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md b/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md new file mode 100644 index 0000000..5c70fb4 --- /dev/null +++ b/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md @@ -0,0 +1,246 @@ +# Closing the loop with users + +When and how to communicate feedback-driven changes. The over-promising risk. + +Closing the loop is the practice of telling users when their feedback drove a product change. Done well, it strengthens the feedback relationship; users see their input matter. Done badly, it over-promises or appears performative; trust erodes. + +--- + +## Why closing the loop matters + +Users who provide feedback are doing the team a favor. The cost is their time and attention. The return on their investment is, in part, seeing their input acted on. + +**What happens when the loop is open.** + +- Users provide feedback. +- The team uses it (or does not). +- Users do not know what happened. +- Engagement decays. Why provide feedback if it does not seem to matter? + +**What happens when the loop is closed.** + +- Users provide feedback. +- The team uses it (or explains why not). +- Users see their input matter. +- Engagement strengthens. Future feedback flows. + +--- + +## What gets communicated + +Three categories of communication. + +**Changes shipped.** "We shipped X this week. Many of you reported Y was painful; X addresses that." + +- Specific, actionable, ties to specific feedback. +- Best when the team can quantify the change ("Step 3 deferral; activation rate increased from 32% to 41% in the first month"). + +**Changes coming.** "We are working on X for Q3. Several of you have asked about this; here is the timeline." + +- Specific timeline. +- Honest about uncertainty if applicable. +- Risk: over-promising. Communicating coming changes that do not ship erodes trust. + +**Decisions to defer or decline.** "We have heard feedback about X; we are choosing not to prioritize it because Y. Here is the reasoning." + +- Honest about the deferral. +- Explains the reasoning. +- Treats users as capable of understanding tradeoffs. + +The third category is rarely done; it is the most credibility-building. Teams that explain why something was not prioritized earn more trust than teams that promise everything. + +--- + +## Communication channels + +How to close the loop. + +**Public channels.** + +- **Release notes.** Standard post-launch communication. Includes feedback context where relevant. +- **Blog posts or changelog.** Longer-form for major changes. Names the feedback patterns that drove the work. +- **Public roadmap.** Shows what is coming; signals that user feedback informs prioritization. + +**Targeted channels.** + +- **Email to users who reported the issue.** "You reported X; we shipped Y to address it." Personalized; high impact for specific users. +- **In-app notification at the moment of relevance.** When the user encounters the changed flow, an in-product banner: "We changed this based on feedback like yours; here is what is different." +- **Customer success outreach.** For high-value or high-engagement users, direct outreach is appropriate. + +**Community channels.** + +- **Beta or community forums.** Where applicable, communicate to the engaged community. +- **Social media.** For high-visibility changes; risk of public attention if poorly communicated. + +The channel should match the audience and the change. High-impact public changes warrant public communication; targeted changes warrant targeted communication. + +--- + +## Frequency and timing + +When to close the loop. + +**Immediately after shipping.** Most effective. The change is fresh; users remember providing feedback. + +**Periodic recap (monthly or quarterly).** "Here are the changes we shipped this quarter, and the feedback patterns that motivated them." + +- Useful for changes that did not warrant individual announcement. +- Builds an aggregate sense that feedback is shaping the product. + +**Before shipping (preview).** "We are about to ship X; here is what to expect." + +- Heads-up for users who will encounter the change. +- Risk: pre-launch announcements that get delayed; users wonder when the change is coming. + +The frequency calibration. Avoid silence (users feel ignored). Avoid over-communication (users tune out). Calibrate to the change cadence and audience attention. + +--- + +## The over-promising risk + +Communicating future changes that do not ship erodes trust. + +**The pattern.** + +- The team announces "we are working on X" with a timeline. +- The work gets deprioritized, delayed, or canceled. +- Users who counted on the change feel deceived or ignored. + +**Why it happens.** + +- Marketing or stakeholder pressure to share roadmap information. +- The team's own optimism about timelines. +- Failure to communicate when plans change. + +**The cure.** + +- Communicate shipped changes with confidence. +- Communicate coming changes with appropriate hedging ("we are exploring this," "we are planning this for next quarter"). +- Communicate plan changes when they happen, not silently. + +**The honest framing.** Promising "X will ship in Q3" is high-risk; promising "X is on our radar; we are evaluating priority" is honest. The first looks more confident; the second is more credible over time. + +--- + +## Communication for declined or deferred feedback + +When the team decides not to prioritize requested changes. + +**The pattern.** + +- User provides feedback requesting a change. +- The team evaluates and decides not to prioritize. +- The team communicates the decision. + +**Strong communication.** + +- "Several of you have asked about [feature]. We have evaluated and are choosing not to prioritize it this year because [reason]. Here are alternatives or workarounds that may help in the meantime." +- "We hear the feedback about [issue]. We are choosing not to address this for now because [tradeoff]. We are open to reconsidering if the pattern strengthens." + +**Why it builds trust.** + +- Acknowledges the feedback was heard. +- Explains the reasoning. +- Treats the user as capable of understanding tradeoffs. + +**The risk of avoiding.** + +- Silence. The user wonders if the feedback was heard. +- "Maybe in the future." Vague commitments that do not commit. +- "We will consider it." Performative. + +The decline communication is rare in practice but disproportionately valuable. + +--- + +## Communication for high-volume feedback + +When many users have provided similar feedback. + +**The pattern.** + +- A specific change addresses widely-reported feedback. +- The team has many users to potentially notify. + +**Approaches.** + +- **Public announcement** referencing the feedback pattern. "Many of you reported X; we shipped Y." +- **Targeted email to users who reported the issue** (using support ticket history, NPS comments, etc.). +- **In-product notification** at the moment of relevance. + +**The capacity calibration.** Targeted communication is high-effort; public communication scales. Most programs combine: public announcement for visibility, targeted communication for highest-impact users. + +--- + +## Personal vs aggregate + +Sometimes the closing-the-loop communication is to a specific user; sometimes it is aggregate. + +**Personal.** + +- "John, you reported X two months ago. We shipped Y this week to address it. Thanks for the feedback that informed this work." +- Direct email or in-app message. +- High impact for the specific user; low cost; very high relationship value. + +**Aggregate.** + +- "Many of you have asked about X; we shipped Y this week." +- Public announcement; reaches many users. +- Lower per-user impact but scales. + +The discipline. Personal communication for high-impact users (long-tenured customers, design partners, council members). Aggregate for broader changes. + +--- + +## When closing the loop fails + +Common failures. + +**Silence.** The most common failure. Users provide feedback; the team uses it (or does not); users never know what happened. Engagement decays. + +**Generic acknowledgment.** "Thanks for the feedback! We will look into it." Standard auto-reply that everyone gets. Feels performative; closes the loop technically but not meaningfully. + +**Over-promising.** "We will ship this in Q3." The team misses the date or cancels; users feel deceived. + +**Late communication.** Changes shipped months ago; communication never happens; users stopped using the product. + +**Vague communication.** "We have heard your feedback and are working on improvements." No specifics; users cannot tell what was actually changed. + +**No deferral communication.** Changes the team decided not to prioritize go uncommunicated. Users keep wondering or assume the feedback was ignored. + +**Communication only on shipping.** Successes communicated; failures and deferrals never. Trust erodes when users notice the asymmetry. + +--- + +## Closing the loop and feedback volume + +Programs that close the loop well often see feedback volume increase over time. Users who saw their input matter contribute more. + +**The virtuous cycle.** + +- Feedback closes the loop. +- Users see their input matter. +- Engagement strengthens. +- Feedback volume and quality increase. +- The team has more signal to act on. + +**The vicious cycle.** + +- Feedback aggregation happens in silos. +- Closing the loop does not happen. +- Users feel ignored. +- Engagement decays. +- Feedback volume and quality decrease. +- The team has less signal. + +The discipline. Closing the loop is an investment in the future of the feedback program. + +--- + +## Methodology-level choices that stay in the public skill + +Why closing the loop matters. What gets communicated. Communication channels. Frequency and timing. The over-promising risk. Communication for declined or deferred feedback. Communication for high-volume feedback. Personal vs aggregate. Common failures. The virtuous and vicious cycle. + +## Implementation choices that stay internal + +Specific email templates for closing-the-loop communication. Specific automation that triggers communication. Specific in-product notification systems. The team's own conventions for personal vs aggregate. These vary by team. diff --git a/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md b/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md new file mode 100644 index 0000000..c16ce67 --- /dev/null +++ b/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md @@ -0,0 +1,193 @@ +# Common feedback aggregation failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most feedback aggregation failures share a single root, which is treating feedback aggregation as collection rather than as decision input. + +--- + +## Failure 1: Loudest customers steer the roadmap + +**Symptom.** A small number of vocal customers dominate roadmap discussions. Quieter customers' needs go unaddressed. The product evolves to serve the loudest, not the broadest. + +**Diagnosis.** Loudest-voice pattern. Volume from vocal users mistaken for broad signal. + +**Cure.** Apply channel-source weighting. Distinguish between distinct-user signal and per-user volume. Triangulate across channels to validate that loud signal represents broad pattern. + +**Prevention.** Synthesis names the source distribution explicitly. "This pattern came from 50 distinct users across 3 channels" is different from "this pattern came from 5 users with 200 tickets." + +--- + +## Failure 2: We have lots of feedback but no decisions + +**Symptom.** Feedback channels overflow. Tagging happens. Dashboards exist. Decisions get made on intuition rather than on the feedback signal. + +**Diagnosis.** Aggregation without synthesis. The triage cadence is missing or broken; feedback is collected without being turned into decision input. + +**Cure.** Establish the synthesis cadence (weekly, monthly, quarterly). Each cadence produces output the team uses for decisions. + +**Prevention.** Synthesis ownership explicit. Whoever owns synthesis is accountable for the loop's continuity. + +--- + +## Failure 3: Our channels overflow; we cannot keep up + +**Symptom.** Feedback volume exceeds the team's capacity to triage, tag, and synthesize. Old feedback never gets reviewed; new feedback piles up. + +**Diagnosis.** Capacity mismatch. Either tooling does not scale, or the team is under-staffed for the volume, or both. + +**Cure.** Scale tooling: AI-assisted tagging, aggregated channels, automated pattern surfacing. Or reduce capture: not every channel needs to be aggregated. + +**Prevention.** Match tooling and capacity to expected volume. Plan for growth; the volume that is comfortable today often is not in 6 months. + +--- + +## Failure 4: Different teams cite different feedback for the same decision + +**Symptom.** Engineering team cites one feedback pattern; product team cites another; sales team cites a third. The teams reach for whatever feedback supports their position. + +**Diagnosis.** Channel-source weighting absent. Each team uses the channel that is most accessible to them, regardless of decision relevance. + +**Cure.** Establish weighting per decision. The synthesis surfaces what the relevant channels say, weighted appropriately. Teams use the synthesis rather than going to channels independently. + +**Prevention.** Centralize synthesis ownership. The synthesis owner produces the canonical view; teams reference it rather than producing parallel interpretations. + +--- + +## Failure 5: Customer council meetings produce notes nobody references + +**Symptom.** Customer council convenes regularly. Notes are taken. Decks summarize. The notes get filed; no roadmap discussions reference them. + +**Diagnosis.** Council without synthesis loop. The meeting is the deliverable; the analytical follow-through is missing. + +**Cure.** Apply the synthesis loop to council inputs. Each council meeting produces specific actionable input that feeds product decisions. + +**Prevention.** Treat council inputs as part of the broader feedback aggregation, not as a separate stream that produces ceremonial outputs. + +--- + +## Failure 6: NPS is reported monthly but does not inform decisions + +**Symptom.** NPS scores get reported in monthly business reviews. The number is part of compliance reporting. It does not inform product decisions. + +**Diagnosis.** NPS as compliance metric. The number gets tracked; the underlying signal does not. + +**Cure.** Mine NPS comments for patterns. Segment NPS by user segment. Use NPS trends as drift signal. The number itself is less informative than the underlying signal. + +**Prevention.** NPS reporting includes the qualitative signal alongside the quantitative score. Decisions reference what NPS comments revealed, not just the score. + +--- + +## Failure 7: Feedback we shipped against did not move sentiment + +**Symptom.** Major feature shipped to address feedback. Post-launch sentiment did not improve. The team is confused. + +**Diagnosis.** Wrong feedback prioritized. The loud feedback was not the most consequential; the patterns the team addressed were not the patterns that drove sentiment. + +**Cure.** Re-examine the synthesis that motivated the work. Was the pattern strong across channels, or was it loud in one channel? Was the segment broad or narrow? Was the change the right response to the pattern? + +**Prevention.** Strong synthesis grounds prioritization in cross-channel patterns and frequency-intensity assessment. Single-channel signals get treated cautiously. + +--- + +## Failure 8: Users gave feedback once and never returned + +**Symptom.** Users submit feedback through channels. They never engage again. Repeat feedback rates are low. + +**Diagnosis.** Closed-loop missing. Users feel ignored after providing feedback. + +**Cure.** Establish closing-the-loop communication. Tell users when their feedback drove change. Personal communication for high-impact users; aggregate for broader changes. + +**Prevention.** Closing the loop is part of the feedback workflow, not an afterthought. Decisions to ship include closing-the-loop communication as a step. + +--- + +## Failure 9: We tagged everything but cannot find patterns + +**Symptom.** Tagging happens systematically. The team applies tags to most feedback items. But synthesis cannot identify clear patterns. + +**Diagnosis.** Taxonomy too granular, too coarse, or noisy. Periodic taxonomy review missing. + +**Cure.** Run a taxonomy review. Merge tags that fragment patterns; split tags that hide distinct issues; deprecate tags that no longer apply. + +**Prevention.** Quarterly or bi-annual taxonomy review. The taxonomy evolves with the program. + +--- + +## Failure 10: Drift in feedback caught us by surprise + +**Symptom.** A feedback category grew significantly over weeks or months. The team discovered the change only when it became a problem. + +**Diagnosis.** Drift detection missing. The team did not investigate trending patterns until they became urgent. + +**Cure.** Establish drift detection: trend dashboards, threshold alerts, periodic trend review. + +**Prevention.** Weekly quick scans for sharp drift. Monthly systematic review of category trends. Tooling that surfaces changes automatically. + +--- + +## Failure 11: Sales call data and support ticket data tell different stories + +**Symptom.** Sales suggests one priority; support suggests another. Both teams have data; the data conflicts. + +**Diagnosis.** Cross-channel synthesis missing. Each channel's signal stays in its own silo. + +**Cure.** Run cross-channel synthesis. Compare what sales calls reveal (prospect view) to what support tickets reveal (existing customer view). Often the conflict surfaces meaningful differences (different segments, different lifecycle stages); sometimes it surfaces inconsistency that warrants investigation. + +**Prevention.** Synthesis includes cross-channel triangulation. Conflicts get surfaced and resolved or acknowledged. + +--- + +## Failure 12: Feedback aggregation as compliance + +**Symptom.** Feedback collection happens because customers expect it or because leadership mandates it. The collection is performative; the synthesis is minimal. + +**Diagnosis.** Feedback aggregation treated as ceremony rather than as decision input. + +**Cure.** Tie feedback aggregation to specific decisions. The synthesis informs roadmap; decisions reference patterns. If the team cannot trace decisions to feedback, the program is compliance, not aggregation. + +**Prevention.** Feedback program goals are explicit and tied to decisions. The program's success is measured by whether decisions reference its synthesis, not by whether feedback was collected. + +--- + +## Failure 13: Synthesis that does not surface patterns + +**Symptom.** Monthly or quarterly synthesis happens. The output is descriptive but does not surface patterns or inform decisions. + +**Diagnosis.** Synthesis writing is documentation rather than analytical work. The patterns are not extracted; the implications are not drawn. + +**Cure.** Apply discovery-research-synthesis discipline to feedback synthesis. Patterns named with conviction; implications drawn; decisions informed. + +**Prevention.** Synthesis ownership includes analytical responsibility, not just documentation responsibility. + +--- + +## Failure 14: Tooling-led process + +**Symptom.** The team's process follows what the tooling supports. Capabilities the tooling does not support do not happen. + +**Diagnosis.** Tooling drives the process rather than the process driving tooling selection. + +**Cure.** Step back. Define what the team needs the feedback aggregation to produce. Evaluate tooling against those needs. + +**Prevention.** Tooling decisions are downstream of process design. The team designs the process, then selects or builds tooling that supports it. + +--- + +## The cross-cutting pattern + +Most feedback aggregation failures share a single root: treating feedback aggregation as collection rather than as decision input. + +Collection focuses on capturing feedback: channels integrated, items tagged, dashboards built, scores reported. Output: a record that feedback was collected. + +Decision input focuses on what the feedback informs: which decisions, what signal will inform them, what synthesis surfaces patterns the team needs. Output: decisions traceable to feedback patterns. + +The fix for almost any feedback aggregation failure starts with the same question: what specifically is this feedback program supposed to inform, and is the synthesis loop producing that input? When the answer is clear, the program becomes load-bearing. When the answer is "we should be aggregating feedback," the program becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting collection-vs-decision-input pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md b/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md new file mode 100644 index 0000000..cff4b6c --- /dev/null +++ b/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md @@ -0,0 +1,236 @@ +# Detecting drift in feedback + +Drift patterns. Investigation discipline. Drift as early signal of change. + +Feedback signal changes over time. Volume in a category increases or decreases; new patterns emerge; old patterns disappear; sentiment shifts. The team that detects drift early often catches issues before they compound; the team that does not detect drift often discovers problems after they are large. + +--- + +## The drift patterns + +Common ways feedback signal changes over time. + +### Increasing volume in a category + +**Signal.** Feedback volume in a specific area is rising over weeks or months. + +**Possible causes.** + +- The issue is worsening. +- The user base is growing (more total volume across all categories). +- Awareness of the channel is increasing (more users finding the feedback channel). +- Recent product changes introduced or amplified an issue. + +**The investigation.** Look at the cause: + +- Is the percentage of total feedback in this category increasing? (If yes, this category is growing relative to others; the issue is real, not just user-base growth.) +- Did recent product changes affect this area? (Often the cause when volume increases sharply.) +- Are users describing similar issues in different ways? (Could be one underlying issue surfacing through multiple feedback styles.) + +### Decreasing volume in a category + +**Signal.** Feedback volume in a specific area is declining over weeks or months. + +**Possible causes.** + +- The issue was resolved. +- Users gave up reporting (resignation rather than satisfaction). +- The user base shifted (fewer users in the affected segment). +- Channel access changed (users stopped using the feedback channel for this category). + +**The investigation.** Decreasing volume can be good or bad: + +- If a fix shipped and volume dropped: fix worked. +- If no fix shipped but volume dropped: investigate. Are users churning? Are they working around the issue silently? + +### New patterns emerging + +**Signal.** Feedback that was rare or non-existent starts appearing more frequently. + +**Possible causes.** + +- Recent product changes introduced new patterns. +- Market conditions changed (new competitors, new user expectations). +- User base expansion brought new use cases. +- Existing users developed new workflows. + +**The investigation.** Investigate the cause; new patterns often inform roadmap decisions. + +### Patterns disappearing + +**Signal.** Feedback patterns that used to be common stop appearing. + +**Possible causes.** + +- Product changes addressed the issue. +- Users migrated away from the affected workflows. +- The user base shifted. + +**The investigation.** Validate that the disappearance reflects resolution, not silent abandonment. + +### Sentiment shifts + +**Signal.** Aggregate sentiment (NPS, CSAT, in-app rating) trends differently than before. + +**Possible causes.** + +- Specific changes affected sentiment. +- External factors (market conditions, competitor actions, news cycles). +- User base composition changed. +- Cumulative experience changes that the team did not flag individually. + +**The investigation.** Sentiment shifts warrant root-cause analysis; both improvements and degradations are informative. + +--- + +## The drift detection cadence + +When the team checks for drift. + +**Weekly:** quick scans for sharp drift in critical categories. Sharp increases in support volume on specific issues, sudden NPS drops, viral social mentions. + +**Monthly:** systematic review of category-level trends. Compare the past month to prior months. Identify categories with significant increases or decreases. + +**Quarterly:** strategic drift review. Long-term trends, sentiment shifts, emerging patterns. Pairs with quarterly strategic synthesis. + +**Annually:** taxonomy and aggregate drift. Are tag categories still appropriate? Has the user base composition changed? Long-term sentiment trends. + +--- + +## Tooling for drift detection + +What infrastructure helps catch drift. + +**Trend dashboards.** Time-series views of feedback volume per category. Visual surfacing of changes. + +**Threshold alerts.** Automated alerts when a category's volume changes significantly (e.g., 50%+ increase week-over-week). + +**Sentiment tracking.** NPS or CSAT trends over time, segmented by user segment and product area. + +**Cross-channel views.** Aggregate trends across channels surface patterns that single-channel views miss. + +**Period comparisons.** Compare current period to prior periods (this month vs last month, this quarter vs same quarter last year). + +The tooling supports detection; humans interpret. + +--- + +## Investigation discipline + +When drift is detected, what to investigate. + +**The questions.** + +- What changed in the product or in the user base that could explain the drift? +- Is the drift persistent or a temporary spike? +- Is the drift segment-specific or universal? +- Is the drift correlated with other signals (churn, engagement, support volume)? +- What is the underlying cause vs the surface signal? + +**The investigation methodology.** + +- Pull a sample of feedback from the drifting category. +- Compare it to feedback in the same category from before the drift started. +- Identify what changed: language, contexts, severity, user segments. +- Map to product changes or external events that could explain. +- Form a hypothesis; test it through additional investigation. + +--- + +## Drift as early signal + +Drift often signals issues before they become large. + +**The leading-indicator pattern.** + +- A category's volume starts increasing. +- The team investigates and identifies the cause. +- The cause is addressed before it affects more users. + +Without drift detection, the same issue might compound for months before the team notices. + +**Worked example.** + +- Support tickets in the "configuration step 3" category increase 30% in two weeks. +- Investigation reveals: a recent change to the configuration form introduced a confusing default. +- The change is reverted or fixed within a week. +- Without drift detection, the issue might have continued for months, affecting many more users. + +--- + +## Drift in segments + +Drift can be segment-specific. + +**The pattern.** Aggregate metrics look stable; segment-specific metrics show drift. + +**Worked example.** Aggregate NPS is stable. Enterprise NPS is dropping; small-team NPS is improving. The aggregate hides the segment-specific drift. + +**The investigation.** Segment-level views surface patterns the aggregate hides. Enterprise drift may indicate a specific issue with enterprise features or experience that aggregate metrics miss. + +The discipline. Drift detection should include segment views, not just aggregate views. + +--- + +## Drift in cross-channel patterns + +Sometimes drift appears across channels even when individual channels look stable. + +**The pattern.** Each channel shows mild changes; the cross-channel aggregate shows a stronger pattern. + +**Worked example.** Support tickets in onboarding category up 15%. NPS comments mentioning onboarding up 10%. In-app feedback in onboarding up 20%. No single channel signals an emergency; the cross-channel aggregate suggests a real issue. + +**The investigation.** Cross-channel drift detection requires unified views or manual cross-channel review. + +--- + +## False-positive drift + +Not every change is real drift. + +**Common false positives.** + +- Seasonal patterns: support volume drops over holidays; NPS dips during certain campaigns. +- One-off events: a viral social mention spikes social signal but does not represent persistent change. +- Product launches: short-term volume spikes around new features, then normalize. +- Channel changes: a new feedback channel launches; volume in that channel grows from zero, not because the underlying issue grew. + +**The investigation discipline.** Before declaring drift, validate that the change is persistent and not explained by known factors. + +--- + +## Drift acknowledgment in synthesis + +Drift signals get surfaced in monthly and quarterly synthesis. + +**The pattern.** Synthesis documents include a drift section: what is changing, what may explain it, what action (if any) is recommended. + +**The honest framing.** Some drift gets acknowledged but not actioned (low-priority categories, edge cases). Some drift drives investigation. Some drift drives roadmap decisions. The synthesis names the disposition for each drift signal. + +--- + +## Common drift detection failures + +**No detection.** Aggregate volume is the only metric tracked; trends invisible. + +**Aggregate only.** Segment-specific drift hidden by aggregate stability. + +**Single-channel only.** Cross-channel patterns missed. + +**Late detection.** Drift caught after it has compounded for months. + +**False positives treated as real drift.** Seasonal patterns or one-off events trigger investigation that wastes time. + +**Real drift treated as false positive.** The team dismisses signals as noise; underlying issues compound. + +**Investigation without follow-through.** Drift detected; team investigates; finds cause; does not act. The detection was performative. + +--- + +## Methodology-level choices that stay in the public skill + +The drift patterns (increasing/decreasing volume, new/disappearing patterns, sentiment shifts). The drift detection cadence. Tooling for drift detection. Investigation discipline. Drift as early signal. Drift in segments. Drift in cross-channel patterns. False-positive drift. Drift acknowledgment in synthesis. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for drift detection. Specific threshold settings for alerts. Specific seasonality models. Specific segment-view configurations. The team's own conventions for drift acknowledgment in synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/frequency-vs-intensity.md b/skills/user-feedback-aggregation/references/frequency-vs-intensity.md new file mode 100644 index 0000000..3f96062 --- /dev/null +++ b/skills/user-feedback-aggregation/references/frequency-vs-intensity.md @@ -0,0 +1,231 @@ +# Frequency vs intensity + +The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. + +Feedback signal varies along two dimensions: how often the same feedback recurs (frequency) and how strongly users feel about it (intensity). The combination produces a matrix that informs prioritization. + +--- + +## The two dimensions + +**Frequency.** How often the same feedback recurs across users. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +**Intensity.** How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive ("I cannot use the product because of this"), or describe satisfaction as transformative ("This feature changed how my team works"). +- Low-intensity feedback: minor friction ("Slightly annoying") or mild satisfaction ("It's fine"). + +The two dimensions are independent. High frequency does not imply high intensity; high intensity does not imply high frequency. + +--- + +## The four-quadrant matrix + +### Quadrant 1: High frequency, high intensity + +**Top priority.** Many users hit this; it matters to them. + +**Examples.** + +- A bug that affects core flow for many users. +- A friction point users describe as "I almost canceled because of this." +- A feature gap that users repeatedly cite as a competitive disadvantage. + +**The disposition.** Address quickly. The combination of broad impact and high stakes warrants priority investment. + +### Quadrant 2: High frequency, low intensity + +**Papercuts.** Many users hit this but it is minor. + +**Examples.** + +- A confusing button label that users figure out within seconds. +- A slight delay in a flow that users tolerate. +- A small visual inconsistency. + +**The disposition.** Address in batches. Individual papercuts are minor; cumulatively they erode experience. Periodic "papercut sprints" address many at once. + +**The risk of ignoring papercuts.** Papercuts compound. Users who tolerate one papercut leave when they accumulate. The cumulative experience is worse than the sum of individual papercuts. + +### Quadrant 3: Low frequency, high intensity + +**Affected users deeply impacted but few.** Often segment-specific. + +**Examples.** + +- A bug that affects users in a specific configuration that 5% of customers use, but for those users it is blocking. +- A feature gap that prevents enterprise customers from passing compliance review. +- An accessibility issue that excludes a specific user group entirely. + +**The disposition.** Depends on segment importance and reversibility. + +- If the affected segment is strategically important: high priority. +- If the affected segment is marginal: lower priority but documented. +- If the issue is a complete blocker for the affected users (cannot use the product at all): often warrants urgency regardless of segment size. + +### Quadrant 4: Low frequency, low intensity + +**Noise.** Capture; do not action individually. + +**Examples.** + +- One-off observations from users with unusual contexts. +- Minor preferences that one user mentions. +- Edge cases nobody else encounters. + +**The disposition.** Note in the system. Do not invest action on individual items. Aggregate sometimes reveals patterns; the noise can become signal if patterns emerge. + +--- + +## Frequency assessment + +How to assess frequency. + +**Quantitative signals.** + +- Number of distinct users reporting the same issue across channels. +- Volume of feedback items in the relevant tag or category. +- Trend over time: is the frequency increasing or stable? + +**Cautions.** + +- Volume can reflect channel bias rather than actual frequency. A loud single user generating 50 tickets is not high-frequency feedback (50x). +- Channel coverage matters. If a feedback channel only reaches a subset of users, frequency in that channel does not reflect frequency across all users. + +**The cross-channel triangulation.** Issues that show up across multiple channels are higher-frequency than issues that appear in one channel only. + +--- + +## Intensity assessment + +How to assess intensity. + +**Verbal signals.** + +- Strong language: "I cannot use this," "This is unacceptable," "I love this," "This changed my workflow." +- Specific impact descriptions: "I lost 3 hours," "This made my quarterly review possible," "I missed a deadline." +- Workaround intensity: heavy workarounds suggest high-intensity friction; light workarounds suggest low-intensity. + +**Behavioral signals.** + +- Churn correlation: users with feedback in a category churn at higher rates. +- Engagement correlation: users with positive feedback in a category engage more. +- Escalation patterns: users escalating to higher support tiers or to executive contacts signal high intensity. + +**Cautions.** + +- Some users naturally use stronger language than others. +- Cultural differences affect verbal intensity. +- Triangulate verbal and behavioral signals. + +--- + +## The matrix in practice + +Worked example: a feedback aggregation review for a product team's quarterly planning. + +**Top-of-list items (high frequency, high intensity).** + +- Onboarding configuration step 3 abandonment (broad signal across support, NPS comments, in-app feedback; users describe it as "I almost gave up"). +- Mobile app stability issues (frequent mobile crashes; users describe them as blocking). +- Enterprise admin role limitations (consistent across enterprise sales calls and support tickets; described as compliance blockers). + +**Papercut batch (high frequency, low intensity).** + +- Inconsistent button labeling across the product. +- Slow page transitions in the dashboard. +- Filter resets when navigating between views. +- Date format inconsistencies. + +**Strategic-decision items (low frequency, high intensity).** + +- Specific accessibility issues affecting screen reader users. +- Compliance gaps for healthcare-segment customers (small segment but blocking for them). +- Bug affecting users in specific timezone configurations (5% of users, but blocking). + +**Noise-watch (low frequency, low intensity).** + +- Various individual feature requests with no aggregate pattern. +- Cosmetic preferences mentioned by single users. + +The team's quarterly planning weights the four quadrants differently: + +- Top-of-list: included in the next quarter's roadmap. +- Papercut batch: scheduled for a dedicated sprint. +- Strategic decisions: discussed at strategy review for prioritization. +- Noise-watch: captured but not actioned. + +--- + +## When the matrix is misapplied + +Common matrix misuses. + +**Volume as proxy for frequency.** Loudest-voice users generate volume that does not reflect distinct-user frequency. + +**Intensity assessed only verbally.** Some users complain loudly about minor issues; some users underreport severe ones. Triangulate verbal and behavioral signals. + +**Quadrant 4 dismissed too quickly.** Some apparent noise is early-signal of patterns that will grow. Periodic review of low-frequency items catches emerging patterns. + +**Quadrant 3 generalized to quadrant 1.** Strategic-segment issues weighted as if they affected all users. Or marginal-segment issues weighted as if they were strategic. + +**Frequency-only or intensity-only prioritization.** Looking at one dimension misses the matrix. + +--- + +## Frequency over time + +Frequency dimensions can shift over time. + +**Increasing frequency.** Issue is worsening, user base is growing, or reporting awareness is increasing. Investigate the cause. + +**Decreasing frequency.** Issue is resolving, users are giving up reporting, or the user base shifted. The decreasing frequency may not mean problem solved. + +**Stable frequency.** Issue is recurring at consistent rate. May indicate steady-state or chronic issue. + +The drift detection (see `detecting-drift-in-feedback.md`) covers temporal changes in feedback signal. + +--- + +## Intensity at scale + +Intensity assessments at high feedback volume. + +**The challenge.** Reading every piece of feedback to assess intensity is impractical at high volume. + +**The approach.** + +- Sample-based intensity assessment. Read a sample; characterize the intensity distribution. +- Behavioral signal as proxy. Churn rates, escalation patterns, support-tier escalations. +- AI-assisted intensity classification. AI flags high-intensity feedback for human review. + +**The discipline.** Even at high volume, the team should be able to identify high-intensity feedback and weight it appropriately. + +--- + +## Common frequency-intensity failures + +**Loudest-voice as high-frequency.** A few loud users generate volume; the team mistakes volume for frequency. + +**Intensity ignored.** Volume drives prioritization; intensity is not assessed; quadrant 1 and quadrant 2 get treated similarly. + +**Frequency ignored.** A single emotional submission gets prioritized as if it were broad-pattern signal. + +**Papercuts ignored as "low priority."** Cumulative papercut impact erodes experience; treating each papercut as too minor to address misses the cumulative effect. + +**Strategic-segment issues underweighted.** Quadrant 3 treated as quadrant 4 because the affected segment is small. + +**Noise treated as signal.** Quadrant 4 items that are genuinely one-off get actioned as if they were broad patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The two dimensions (frequency and intensity). The four-quadrant matrix with worked dispositions. Frequency assessment. Intensity assessment. The matrix in practice. When the matrix is misapplied. Frequency over time. Intensity at scale. Common failures. + +## Implementation choices that stay internal + +Specific tooling for frequency tracking. Specific intensity classification (manual or AI-assisted). Specific dashboard views by quadrant. The team's own conventions for matrix application in prioritization. These vary by team. diff --git a/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md b/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md new file mode 100644 index 0000000..3f911df --- /dev/null +++ b/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md @@ -0,0 +1,225 @@ +# From feedback to product decision + +The synthesis loop. Cadences. The discipline of decisions traceable to feedback. + +Feedback aggregation produces value when it informs decisions. Without the synthesis loop that turns aggregated feedback into decision input, the program produces volume without action. + +--- + +## The synthesis loop + +The cycle that turns continuous feedback into continuous decisions. + +**The stages.** + +1. Feedback arrives across channels. +2. Triage categorizes and weights. +3. Periodic synthesis surfaces patterns. +4. Patterns inform roadmap discussions, spec drafts, prioritization debates. +5. Decisions reference specific feedback patterns as input. +6. Decisions ship; the loop continues with new feedback informed by the changes. + +**The discipline.** The loop is continuous. Feedback aggregation is not a one-time research project; it is a steady-state discipline. + +--- + +## The cadences + +Feedback synthesis benefits from multiple cadences operating in parallel. + +**Daily: critical issues.** + +- Critical feedback (security incidents, data loss, broken core flows) handled immediately. +- The triage system surfaces critical items for immediate attention. +- Response within hours to a day. + +**Weekly: pattern review.** + +- Team review of recent feedback patterns. +- Categorization, tagging, and pattern identification. +- Adjusts current-quarter execution where patterns suggest changes. +- 1-2 hours per week typical. + +**Monthly: synthesis review.** + +- Surfaces trending patterns over the past month. +- Identifies what to escalate to roadmap discussions. +- Compares current month patterns to prior months (drift detection). +- 2-4 hours per month. + +**Quarterly: strategic synthesis.** + +- Patterns over the quarter inform strategic planning and next-quarter roadmap. +- Customer council inputs and other longer-cadence channels integrated. +- Pairs with the team's broader strategic planning. +- A multi-day effort within the quarter's planning cycle. + +The cadences compose. Critical issues do not wait for weekly review; weekly review captures patterns that monthly review aggregates; monthly synthesis informs quarterly strategic decisions. + +--- + +## The synthesis output + +What each cadence produces. + +**Daily/critical:** specific incidents handled, no formal output beyond the response. + +**Weekly:** internal team notes on emerging patterns. May include a short summary email or dashboard update. + +**Monthly:** a synthesis document covering the month's patterns. Surfaces what is emerging, what is stable, what has resolved. Roadmap discussions reference this document. + +**Quarterly:** a strategic synthesis document. Trends over the quarter, recommendations for next quarter, strategic implications. Senior product leadership reviews this. + +The output gets richer at longer cadences. Daily and weekly are tactical; monthly and quarterly are strategic. + +--- + +## Decisions traceable to feedback + +The discipline that distinguishes triaged-synthesis from feedback ceremony. + +**The pattern.** Each major product decision can be traced to specific feedback patterns. The team can articulate: "We decided to prioritize X because feedback showed Y pattern across Z channels." + +**The anti-pattern.** Decisions get made on intuition or politics. Feedback aggregation happens in parallel but does not inform the decisions. The team uses general impressions ("we hear a lot about this from customers") rather than specific patterns. + +**The discipline.** + +- Roadmap items reference the feedback patterns that motivated them. +- Prioritization debates reference specific signal weight. +- Spec drafts include feedback context for the design decisions. +- Stakeholder communication explains decisions in terms of feedback patterns. + +**The audit.** For recent decisions, can the team trace each to specific feedback signals? If yes, the program is informing decisions. If the answer is "we generally know what customers want," the program is feedback theater. + +--- + +## Roadmap input from feedback + +How feedback aggregation informs roadmap planning. + +**The roadmap inputs.** + +- High-frequency-high-intensity patterns (quadrant 1 from the frequency-intensity matrix). +- Strategic-segment patterns (quadrant 3 from segments that matter for strategy). +- Cross-channel patterns that have validated across multiple sources. +- Drift signals that suggest emerging issues. + +**The roadmap-output mapping.** Roadmap candidates get characterized by which feedback patterns they address. + +- Candidate: "Onboarding redesign." Feedback motivation: configuration step 3 abandonment pattern across support, NPS, in-app feedback. +- Candidate: "Enterprise admin overhaul." Feedback motivation: enterprise sales-call objections + enterprise customer support patterns. + +The mapping makes the roadmap defensible: each item has a feedback-grounded reason. + +**The "no feedback signal, no priority" discipline.** Candidates that lack feedback grounding may still be valuable but should be defensible on other grounds (technical foundation, strategic bet). Candidates without any defensible grounding should be deprioritized. + +Pair with `roadmap-planning` for the broader prioritization discipline. + +--- + +## Spec input from feedback + +How feedback aggregation informs spec writing. + +**The pattern.** Specs reference feedback context for design decisions. + +**Worked example.** A spec for an onboarding redesign: + +- Background: feedback shows 40% of new signups abandon at configuration step 3. Cross-channel pattern (support tickets, in-app feedback, NPS comments). +- User stories: grounded in the specific feedback patterns. "As a new signup, I want to defer credit-card configuration until after I have seen the value, so I do not need my card on hand at signup." +- Design decisions: tied to the feedback. "Step 3 deferral chosen because feedback specifically cites credit-card-not-on-hand as the abandonment cause; alternative approaches that do not address this would not move the metric." + +The spec is grounded in feedback rather than in intuition. + +Pair with `pm-spec-writing` for the broader spec discipline. + +--- + +## Stakeholder communication from feedback + +How feedback aggregation informs stakeholder discussions. + +**The pattern.** Decisions presented to stakeholders are explained in terms of feedback patterns. + +**Strong stakeholder communication.** + +- "We are prioritizing the onboarding redesign because feedback across support, NPS, and in-app surveys consistently shows 40%+ abandonment at configuration step 3, with users citing credit-card friction as the cause." +- "We are deferring the dashboard expansion because feedback signal is mixed: enterprise customers want it; small-team customers do not need it; the strategic priority for this quarter is small-team activation." + +**Weak stakeholder communication.** + +- "We have heard a lot of feedback about onboarding." +- "Customers want this feature." + +The strong version is defensible; readers can engage substantively. The weak version is hand-waving. + +--- + +## Closing the synthesis loop + +After decisions ship, feedback responds. + +**The post-decision feedback.** + +- Did the change reduce the feedback patterns that motivated it? +- Did new patterns emerge as a result? +- Did the change introduce new friction in adjacent areas? + +**The discipline.** Track post-decision feedback to validate that the decision worked. Decisions that ship without post-decision feedback tracking lose the loop's learning value. + +--- + +## Cadence drift + +When the synthesis cadence breaks down. + +**Common drift patterns.** + +- Critical issues handled but no weekly pattern review. Tactical signal lost. +- Weekly review happens but does not aggregate to monthly synthesis. Patterns over time invisible. +- Monthly synthesis happens but does not inform quarterly planning. Strategic input missing. +- Quarterly strategic synthesis happens but the team does not act on it. Synthesis ceremony. + +**The signal.** When decisions stop being traceable to feedback, the cadence has drifted. The fix is restoring the cadence rather than blaming the team. + +--- + +## Synthesis ownership + +Who owns the synthesis loop. + +**Common ownership patterns.** + +- A dedicated feedback program owner (often a senior PM, product ops, or customer-success-product liaison). +- The product team's PM rotates through synthesis duties. +- A customer feedback team that synthesizes and feeds product teams. + +**The discipline.** Whoever owns synthesis is accountable for the loop's continuity. Without explicit ownership, synthesis falls to whoever has time, which often means it does not happen. + +--- + +## Common decision-loop failures + +**Synthesis without decisions.** Patterns surfaced; team does not use them. Documentation theater. + +**Decisions without synthesis grounding.** Team makes decisions on intuition; feedback aggregation happens in parallel but does not inform. + +**Cadence breakdown.** Daily critical handled; weekly and monthly synthesis fall behind. Loop loses continuity. + +**No post-decision tracking.** Decisions ship; feedback response not tracked; learning lost. + +**Synthesis ownership missing.** No clear owner; synthesis falls between roles. + +**Synthesis output not actionable.** Documents produced but framed in ways that do not inform decisions. Dense, generic, or unfocused. + +**Stakeholder communication still hand-waving.** Synthesis happens internally but stakeholder communication does not reference the patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The synthesis loop. The cadences (daily, weekly, monthly, quarterly). The synthesis output per cadence. Decisions traceable to feedback. Roadmap input. Spec input. Stakeholder communication. Closing the loop after decisions ship. Cadence drift. Synthesis ownership. Common failures. + +## Implementation choices that stay internal + +Specific tooling for synthesis production. Specific document templates per cadence. Specific reviewer workflows. Specific dashboard configurations. The team's own conventions for owning synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/tooling-considerations.md b/skills/user-feedback-aggregation/references/tooling-considerations.md new file mode 100644 index 0000000..5669fc4 --- /dev/null +++ b/skills/user-feedback-aggregation/references/tooling-considerations.md @@ -0,0 +1,247 @@ +# Tooling considerations + +Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. + +Feedback aggregation tooling shapes what the program can do. The right tooling supports multi-channel aggregation, tagging at scale, pattern surfacing, and integration with adjacent systems. The wrong tooling produces silos, manual labor, and synthesis bottlenecks. + +This skill is platform-agnostic; specific products are not endorsed. The categories below describe what kinds of tooling exist; the team's actual product choices depend on stack, budget, and program shape. + +--- + +## Tooling categories + +Several categories of tooling support feedback aggregation. + +### Customer feedback platforms + +**What they do.** Aggregate feedback from multiple sources. Support tagging and categorization. Surface patterns through dashboards and analytics. + +**Strengths.** + +- Multi-channel support (often integrate with support, NPS, in-app, and other sources). +- Built-in tagging and pattern detection. +- Often include AI-assisted categorization. + +**Weaknesses.** + +- Pre-built taxonomies may not fit team-specific needs. +- Vendor-locked: switching costs grow over time. +- Coverage varies by vendor; some channels may not integrate. + +### Support ticket systems with analytics + +**What they do.** Track support tickets with tagging, routing, and reporting. Often the primary support channel. + +**Strengths.** + +- Native to support workflows. +- Strong tagging and routing for support-specific work. +- Analytics on support-team metrics. + +**Weaknesses.** + +- Often single-channel (support only). +- Cross-channel synthesis requires additional tooling or custom integration. + +### NPS or survey platforms + +**What they do.** Distribute surveys, collect responses, track sentiment trends. + +**Strengths.** + +- Specialized for survey distribution and response collection. +- Built-in NPS or CSAT methodology. +- Trend tracking over time. + +**Weaknesses.** + +- Single-modality (surveys only). +- Limited integration with other feedback sources. + +### Customer relationship management (CRM) systems + +**What they do.** Manage customer relationships, contact history, deal pipelines, customer feedback fields. + +**Strengths.** + +- Rich customer context (segment, deal stage, account history). +- Integration with sales workflows. + +**Weaknesses.** + +- Feedback aggregation is often a side feature, not a core function. +- Cross-channel feedback synthesis requires additional configuration. + +### Custom dashboards combining feedback signal with usage analytics + +**What they do.** Custom-built views combining feedback data with product analytics. + +**Strengths.** + +- Tailored to the team's specific needs. +- Cross-channel synthesis built-in to the design. +- Combines feedback patterns with behavioral signals. + +**Weaknesses.** + +- Build cost and ongoing maintenance. +- Skill requirements: data engineering or analytics expertise. + +--- + +## The criteria for tooling selection + +What to evaluate when choosing tooling. + +**Multi-channel aggregation.** Does it integrate with the channels the team uses? Or does it cover one channel only? + +**Tagging at scale.** Does it support the tagging volume the program needs? Manual tagging at low volume; AI-assisted at high volume. + +**Pattern surfacing.** Does it surface patterns, or is it just storage? Some tools store feedback without making it analyzable. + +**Integration with other systems.** Does it connect to roadmap tools, ticketing systems, communication channels? Isolated tools produce silos. + +**Scaling.** Does it scale with program volume? Tools that work at 100 items/week may break at 1000 items/week. + +**Cost.** License or build cost vs the value produced. Expensive tooling that fits is sometimes worth it; cheaper tooling that does not fit is often more expensive in practice. + +**Team skill match.** Does the team have skills to use the tool effectively? Sophisticated tools that the team cannot operate produce value that does not get realized. + +--- + +## The build-vs-buy tension + +Most programs end up with a mix. + +**The reasons to buy.** + +- Faster setup. Off-the-shelf tools work immediately. +- Specialized expertise. Vendors have built tooling for many programs. +- Standard features that the team would not build themselves. + +**The reasons to build.** + +- Cross-channel synthesis often requires custom work that off-the-shelf tools do not support. +- Team-specific tagging schemas and dashboards. +- Integration with the team's specific stack. + +**The hybrid pattern.** + +- Off-the-shelf tools for primary channels (support ticketing, NPS surveys). +- Custom dashboards for cross-channel synthesis. +- Custom integration to bring data together. + +The hybrid is more common than pure build-or-pure-buy in practice. + +--- + +## Volume considerations + +Different volume tiers warrant different tooling approaches. + +**Low volume (under 100 items/week).** + +- Manual tagging is feasible. +- Off-the-shelf tools usually sufficient. +- Custom build often overkill. + +**Mid volume (100-1000 items/week).** + +- AI-assisted tagging often worth the investment. +- Multi-channel aggregation tools earn their keep. +- Custom dashboards often add value. + +**High volume (1000+ items/week).** + +- Heavy AI-assisted or automated tagging. +- Custom infrastructure for cross-channel synthesis. +- Team capacity becomes the bottleneck; tooling must reduce manual work substantially. + +**Very high volume (10,000+ items/week).** + +- Often requires custom data engineering. +- Sampling and aggregation strategies replace per-item review. +- Tooling investment is substantial. + +--- + +## Integration considerations + +Feedback aggregation rarely lives alone. + +**Common integrations.** + +- **Roadmap tools.** Feedback patterns feed roadmap candidates. Tools that integrate (or are linked through workflows) reduce manual transfer. +- **Spec writing.** Feedback context for spec drafts. +- **Communication channels.** Slack or email for surfacing patterns to the team. +- **Customer success systems.** Closing the loop with users; account-level feedback views. +- **Product analytics.** Cross-reference feedback with usage patterns. + +**The integration discipline.** Tooling that integrates produces value compound across the systems. Isolated tooling produces silos that the team must manually bridge. + +--- + +## AI-assisted feedback work + +AI plays an increasing role in feedback aggregation. + +**Common AI uses.** + +- Automatic categorization and tagging. +- Sentiment classification. +- Pattern surfacing across feedback items. +- Summary generation for synthesis documents. +- Anomaly detection for drift identification. + +**The discipline.** + +- AI suggestions get human review at pattern-level. +- Critical decisions remain human-driven; AI accelerates the work. +- AI's biases (overfitting to training data, surface-level patterns) get checked through human pattern review. + +**The honest framing.** AI does not replace human synthesis; it supports it. Programs that automate synthesis entirely produce volume without judgment; programs that integrate AI with human review produce signal at scale. + +See `ai-content-collaboration` for the broader workflow discipline that applies to AI-assisted feedback work. + +--- + +## Privacy and data considerations + +Feedback often contains user information. + +**Considerations.** + +- User consent for feedback use beyond the immediate channel. +- Anonymization where appropriate (especially for sensitive feedback). +- Data retention policies. +- Compliance with regulations (GDPR, CCPA, industry-specific). + +**The discipline.** Tooling choices include data handling considerations. Vendors with poor data practices can create compliance issues regardless of tool capability. + +--- + +## Common tooling failures + +**Single-channel reliance.** Tooling supports only one channel; cross-channel synthesis impossible without additional work. + +**Overly generic tools.** Pre-built taxonomies and dashboards do not match team needs. + +**Custom build that consumes capacity.** Building feedback infrastructure absorbs PM and engineering capacity that should produce product. + +**Volume mismatch.** Tools that fit current volume break when the program scales. + +**Integration neglected.** Feedback tooling isolated from roadmap, spec, customer success systems. + +**AI without review.** Automated categorization without human pattern review produces patterns the team cannot trust. + +**Tooling-led process.** The tool drives the process rather than the process driving tool selection. The team adopts a tool's workflow rather than designing for their needs. + +--- + +## Methodology-level choices that stay in the public skill + +The tooling categories. The criteria for selection. The build-vs-buy tension. Volume considerations. Integration considerations. AI-assisted feedback work. Privacy and data considerations. Common failures. + +## Implementation choices that stay internal + +Specific tooling vendor selections. Specific integration configurations. Specific dashboard designs. Specific data pipelines. The team's own conventions for tool evaluation. These vary by team, stack, and program shape. diff --git a/skills/ux-research/SKILL.md b/skills/ux-research/SKILL.md new file mode 100644 index 0000000..2de3cb2 --- /dev/null +++ b/skills/ux-research/SKILL.md @@ -0,0 +1,252 @@ +--- +name: ux-research +description: "Plan and execute user research including research planning, recruiting, interview design, qualitative synthesis, and translating findings into product decisions. Use this skill whenever the user wants to plan user research, design interviews, recruit participants, conduct discovery, run formative research, or synthesize qualitative findings. Triggers on user research, UX research, user interviews, discovery research, generative research, formative research, qualitative research, user insights, research synthesis, recruitment, interview guide, jobs to be done. Also triggers when product decisions are being made without user input and the user wants to fix that." +category: research +catalog_summary: "Research planning, user interviews, qualitative synthesis" +display_order: 1 +--- + +# UX Research + +Plan and execute user research that produces decisions, not just decks. Stack-agnostic. Tool-agnostic. + +This skill is for generative and discovery research. For testing existing designs, use `usability-testing`. For mapping the full customer experience, use `journey-mapping`. + +--- + +## When to use + +- Starting a new product or major feature without sufficient user understanding +- Diagnosing why something isn't working without clear data signals +- Generating new opportunity hypotheses +- Validating a strategic direction before significant investment +- Building empathy across a team that's drifted from users +- Translating "we should talk to users" intent into a real plan + +## When NOT to use + +- Testing a specific design or prototype (use `usability-testing`) +- Mapping the full journey of an existing experience (use `journey-mapping`) +- Quantitative measurement (use `analytics-strategy`) +- Conversion testing (use `cro-optimization`) + +--- + +## Required inputs + +- The research question(s) - what you need to answer +- Stakeholder buy-in (who needs the findings, what decisions hinge on them) +- Access to users (current customers, prospects, lapsed users, target segments) +- Timeline and budget +- Any prior research to build on + +--- + +## The framework: 6 phases + +### 1. Frame the question + +Bad questions produce bad research. Spend disproportionate time on framing. + +**Good research questions:** +- Specific (not "How do users feel about our product?") +- Open-ended (not "Do users like feature X?") +- Decision-relevant (the answer changes what gets built) +- Researchable (can be answered through user contact, not just analysis) + +**Examples:** + +| Weak question | Better question | +|---|---| +| "Do users like our onboarding?" | "Where in onboarding do new users feel uncertain about whether to continue?" | +| "What features should we build?" | "What unmet needs do current users have when [specific job]?" | +| "Why is conversion low?" | "What's the user mental model when they reach the pricing page, and where does it diverge from our intent?" | + +### 2. Choose the method + +The method follows the question. + +**Generative methods (what's true?):** + +- **In-depth interviews.** 60 minutes, 5 to 15 participants. Best for understanding context, motivation, mental models. +- **Contextual inquiry.** Observe users in their environment doing their work. Best for workflow understanding. +- **Diary studies.** Participants log their experience over days/weeks. Best for behaviors that don't manifest in a single session. +- **Field research.** Spend time where users live/work. Best for cultural and contextual understanding. +- **Surveys (qualitative-heavy).** When you need broad signal with open-ended responses. + +**Validation methods (is this hypothesis right?):** + +- **Concept testing.** Show a description, mockup, or prototype. Get reactions. +- **Card sorts.** Validate information architecture. +- **Tree tests.** Validate findability without visual design influence. + +(For testing usability of working designs, see `usability-testing`.) + +### 3. Recruit + +The recruit makes or breaks the research. + +**Recruit criteria:** + +- Match the audience the research targets (not "anyone willing") +- Mix of behaviors (active users, lapsed users, never-users) +- Mix of demographics where relevant +- Excludes friends, family, employees (biased) +- Excludes professional research participants if possible (different population) + +**Recruit channels:** + +- In-product recruiting (intercept current users) +- Email outreach to user segments +- Recruiting platforms (UserInterviews, Respondent, etc.) +- Customer support team referrals +- Field intercept for in-person + +**Incentive:** Pay participants. Standard rates: $50 to $150 for 60 minutes, more for executives or specialized professions. + +**Recruit volume:** Plan for 20 to 30 percent no-show. Recruit 7 to schedule 5. + +### 4. Conduct + +The interview or session itself. + +**Pre-interview:** + +- Send confirmation 24 hours and 1 hour before +- Test recording setup (audio quality is non-negotiable) +- Prepare interview guide (see template) +- Have a notetaker if possible (frees the interviewer to focus) + +**During the interview:** + +- Record video and audio (with consent) +- Open with rapport-building, not the research questions +- Use open-ended questions ("Tell me about the last time...") +- Use silence (let participants fill it; don't rush to the next question) +- Ask "why" but not too many times in a row (becomes interrogation) +- Ask for specifics and examples ("Can you walk me through what you did?") +- Probe contradictions gently ("Earlier you said X, now you're saying Y; help me understand") +- Watch for moments of emotion (often signal something important) +- Don't sell or convince - this is listening, not pitching + +**Anti-patterns:** + +- Leading questions ("Don't you find this confusing?") +- Hypothetical questions ("Would you use a feature that...?") - poor predictor of behavior +- Multiple questions at once +- Interrupting +- Filling silence +- Interviewing your hypothesis (only asking questions that confirm what you already think) + +### 5. Synthesize + +Notes don't become insights automatically. + +**The synthesis process:** + +1. **Capture observations.** From recordings, notes, transcripts. Each observation is a single data point: a quote, a behavior, an emotion, a moment. +2. **Affinity mapping.** Cluster observations into themes. Physical sticky notes or digital equivalents. +3. **Find patterns.** Themes that appear across multiple participants are signal. One-off observations are interesting but weaker. +4. **Identify insights.** An insight is more than a theme. It's a non-obvious finding that explains a why or implies a so what. +5. **Test the insight against the data.** If the insight only fits some interviews, it's a hypothesis, not an insight. +6. **Distinguish signal from noise.** A belief that 1 of 8 participants holds may be noise. A belief 6 of 8 hold is signal. + +**Heuristics for strong insights:** + +- They surprise the team (insights you already knew aren't insights) +- They explain a "why" the team has been guessing about +- They imply specific actions (so what?) +- They hold up across multiple data points +- They can be stated in one or two sentences + +### 6. Communicate + +Findings die in slide decks. Plan distribution. + +**Outputs that work:** + +- **Top-line insights document.** 5 to 10 insights, clearly stated, with supporting quotes. +- **Highlight reels.** Edited 5 to 10 minute video of key participant moments. More persuasive than any document. +- **In-room workshops.** Walk stakeholders through the synthesis themselves. They internalize when they participate. +- **Per-stakeholder briefs.** Different audiences need different framings. CEO wants strategic implications. Designers want pain points. Engineers want use cases. + +**Outputs that fail:** + +- 80-slide decks that get skimmed +- Reports that no one reads past the executive summary +- Verbose narrative summaries +- Insights that sit in a doc no one re-opens + +--- + +## Workflow + +1. **Frame the research question.** With stakeholders. Multiple iterations. +2. **Pick the method.** Match to the question. +3. **Plan logistics.** Timeline, budget, recruit, tools, team. +4. **Recruit.** Start early. Slow recruits delay everything. +5. **Pilot.** Run 1 to 2 sessions before the main batch. Refine the guide. +6. **Conduct.** Stay disciplined to the guide while staying open to surprises. +7. **Synthesize.** Don't wait until all sessions are done; start mid-way. +8. **Communicate.** Multiple formats. Multiple audiences. +9. **Track impact.** Did decisions change because of the research? If not, the research failed regardless of quality. + +--- + +## Failure patterns + +- **Research without a decision.** Findings have no home. Effort wasted. +- **Vague research questions.** Bad questions produce uninterpretable answers. +- **Recruiting "anyone willing."** Sample doesn't match audience. +- **Over-recruiting professional participants.** Pattern-matched answers, not real users. +- **Leading questions in the guide.** Findings reflect the researcher, not the user. +- **Skipping synthesis.** Notes alone aren't insights. +- **Insights that confirm the team's existing beliefs.** Suspect those especially. +- **Findings that never ship.** Research findings that don't change product decisions are decoration. +- **Single research project for years of decisions.** Research has a shelf life. Refresh. +- **Research as one-time project.** Continuous discovery beats episodic research. + +--- + +## Output format + +Default outputs: + +1. **Research plan** (before research starts) - `research-plan-[topic].md` +2. **Interview guide** - `interview-guide-[topic].md` +3. **Findings doc** (after synthesis) - `research-findings-[topic].md` +4. **Highlight reel** (video, separately produced) + +Findings document structure: + +```markdown +# [Topic] research findings + +## Question we set out to answer +[Specific question] + +## Method +[Approach, sample size, dates] + +## Top insights +1. [Insight, stated in one sentence] + - Supporting evidence: [Quotes, behaviors] + - Implication: [What this means for product/strategy] +2. [Insight 2] + ... + +## Themes (less prominent than top insights, still worth noting) +[List] + +## Outliers worth investigating +[Single-participant observations that may be signal in disguise] + +## Recommended next steps +[Specific actions] +``` + +--- + +## Reference files + +- [`references/interview-guide-template.md`](references/interview-guide-template.md) - Structured interview guide template with example openings, probes, and closes. diff --git a/skills/ux-research/references/interview-guide-template.md b/skills/ux-research/references/interview-guide-template.md new file mode 100644 index 0000000..88fcb00 --- /dev/null +++ b/skills/ux-research/references/interview-guide-template.md @@ -0,0 +1,241 @@ +# Interview Guide Template + +A structured template for in-depth research interviews. Customize the sections to your topic. Length: typically 60 to 75 minutes. + +--- + +## Pre-interview prep + +**Participant info:** +- Name: +- Role / context: +- How they were recruited: +- Anything noteworthy from screener: + +**Research question being answered:** [The specific question this interview is helping answer] + +**Top 3 things I'm trying to learn:** +1. +2. +3. + +**Hypotheses I'm holding loosely:** +- [What I think I'll find. Naming this helps me notice when I confirm vs disconfirm it.] + +**Recording setup:** +- [ ] Audio recorder tested +- [ ] Video recorder (if applicable) tested +- [ ] Notetaker confirmed (or not present) +- [ ] Consent form sent + +--- + +## Section 1: Welcome and rapport (5 to 10 minutes) + +**Goal:** Put the participant at ease. Start collecting context. + +### Opening + +> "Thanks so much for joining today. As I mentioned, we're [purpose: studying how people do X / learning about Y / etc.]. There are no right or wrong answers; I'm here to learn from your experience. +> +> Before we start, do you have any questions? +> +> A few practical notes: I'll be recording so I can focus on listening rather than note-taking. The recording stays internal and is used only for our research. I'll never quote you by name without permission. You can ask me to stop the recording any time. Sound good? +> +> Great. Let's start with something easy." + +### Easy opener + +> "Tell me a little about yourself. What's your role, what does a typical [day / week / project] look like?" + +[Listen for context: industry, role, scale, constraints. Take notes on anything you want to come back to.] + +--- + +## Section 2: Context (10 to 15 minutes) + +**Goal:** Understand the world the participant lives in. Establish the context that shapes their decisions and behavior. + +### Probes (pick 3 to 5 that fit your topic) + +> "Walk me through how you handle [task] today, from start to finish." + +> "What's the last time you [specific behavior or event]? Tell me about that." + +> "Who else is involved when you [activity]? What's their role?" + +> "What tools do you use? Why those specifically?" + +> "What's typical, and what's unusual about how you approach this?" + +> "Where does your [organization / team] stand on [topic]? Any constraints I should understand?" + +### Listening notes + +- Look for **specific examples**, not generalities. "I've never been frustrated by X" is less reliable than "Tell me about the last time X frustrated you." +- Watch for **emotional tone**: where do they perk up, get quiet, or shift body language? +- Note any **language they use** that's different from how the team frames things. + +--- + +## Section 3: The core question (20 to 30 minutes) + +**Goal:** Address the heart of the research. + +### Sample probes for common research goals + +#### If exploring problems / unmet needs + +> "Tell me about the last time you had to [specific situation related to research]." + +> "What was hardest about that?" + +> "What did you try? What worked, what didn't?" + +> "If you had a magic wand and could change one thing about how this works, what would it be?" + +> "When you think about [topic], what frustrates you most?" + +#### If exploring mental models + +> "How would you explain [concept] to someone who's never heard of it?" + +> "When you hear [term we use], what comes to mind?" + +> "Can you draw or sketch how you think about [process]?" + +> "What's the goal when you [action]? What does success look like?" + +#### If exploring evaluation behavior + +> "Walk me through the last time you decided to [action]. How did you decide?" + +> "What were you comparing? How did you compare them?" + +> "What information would have helped you decide?" + +> "What made you confident in your decision? What made you nervous?" + +#### If exploring product or feature use + +> "Tell me about a time you used [product / feature]. Why? What happened?" + +> "When does [product] work well for you? When does it fall short?" + +> "What's the first thing you do when you open [product]?" + +> "What would have to be true for you to [action: recommend, expand use, switch]?" + +### Probe library (use as needed) + +> "Tell me more about that." + +> "What was that like for you?" + +> "Why does that matter to you?" + +> "Give me an example." + +> "Help me understand what you mean by [term]." + +> "Earlier you said X, now you're saying Y. Help me understand." + +> "What were you thinking at that moment?" + +> "What did you do next?" + +### Things to avoid + +- Leading questions ("Don't you think it would be better if...?") +- Hypothetical questions about future behavior ("Would you pay for...?") +- Multi-part questions +- Filling silence too quickly +- Defending the product +- Selling the product +- Asking "why" more than 2 to 3 times in a row (becomes interrogation) + +--- + +## Section 4: Reactions to specific stimuli (optional, 10 to 15 minutes) + +**Goal:** Get specific reactions to a concept, prototype, message, or design. Skip if research is purely generative. + +> "I'd love to show you something we're thinking about. There are no wrong reactions - whatever comes up for you is helpful. Take a look [share screen / show prototype / read description]." + +[Wait. Don't fill the silence.] + +> "What's your initial reaction?" + +> "What questions does this raise?" + +> "If you saw this in [context], what would you do next?" + +> "What's confusing or unclear?" + +> "Is there anything that doesn't fit your situation?" + +[Be especially alert to confused expressions, silences, and "I'm not sure what this is for." These are signal.] + +--- + +## Section 5: Wrap-up (5 to 10 minutes) + +**Goal:** Capture anything missed. Leave the participant feeling good about the experience. + +### Catch-all questions + +> "Is there anything I should have asked but didn't?" + +> "Is there anything you'd want me to know about this topic that didn't come up?" + +> "If you could give one piece of advice to the team building this, what would it be?" + +### Closing + +> "This was incredibly helpful. Thank you for the time and the candor. The [incentive] should arrive [timeline]. If you think of anything else after we hang up, my email is [email]; happy to hear from you. +> +> Last question: would it be okay if I reached out for follow-up research? I won't bombard you, but if something specific comes up and your perspective would be helpful, I'd love to be able to ask." + +--- + +## Post-interview (within 1 hour) + +While memory is fresh: + +- [ ] Write down 3 to 5 most surprising or vivid moments +- [ ] Note any quotes worth coming back to +- [ ] Note any new questions raised by this interview that should change subsequent ones +- [ ] Add to the running synthesis (don't wait to start synthesis until all interviews are done) + +--- + +## Common interview pitfalls and recoveries + +| Pitfall | Recovery | +|---|---| +| Participant gives short, surface answers | "Tell me more about that." Or wait silently. Often produces depth. | +| Participant goes far off-topic | "That's interesting. Let me bring us back to [topic]." | +| You realize the question was leading | "Let me ask that differently. What's been your experience with [topic], in your own words?" | +| Participant asks what you're working on | "I want to hear your unbiased thoughts first. Happy to share more at the end." | +| Participant tries to give you the "right" answer | "Honestly, the more frank you can be, including frustrations or criticisms, the more valuable for us." | +| You realize you're 20 minutes over | Wrap promptly. Ask the most important remaining question. End on time. | +| Participant has emotional reaction | Pause. Acknowledge. "That sounds like it was really frustrating. Take your time." Don't rush past. | + +--- + +## Customization notes + +This template is a scaffold. Adapt: + +- The sections to fit the topic +- The number and type of probes +- The amount of time per section +- Whether to include stimuli (Section 4) + +What stays constant: + +- Open with rapport, not the research question +- Use specific recent examples, not abstract opinions +- Use silence +- Don't lead +- Wrap on time, with grace diff --git a/skills/vendor-evaluation/SKILL.md b/skills/vendor-evaluation/SKILL.md new file mode 100644 index 0000000..03b9d4c --- /dev/null +++ b/skills/vendor-evaluation/SKILL.md @@ -0,0 +1,280 @@ +--- +name: vendor-evaluation +description: "Evaluate, select, and contract with vendors and SaaS tools. Use this skill when comparing alternatives, running an RFP, scoring vendors against criteria, negotiating contracts, planning a switch, or assessing a vendor's risk. Triggers on vendor evaluation, RFP, vendor selection, build vs buy, SaaS evaluation, vendor scorecard, vendor comparison, contract negotiation, vendor switch, procurement. Also triggers when a renewal is coming up or when a tool isn't meeting expectations." +category: process-and-team +catalog_summary: "Tool and vendor selection using a structured rubric" +display_order: 3 +--- + +# Vendor Evaluation + +Pick the right tool or service, negotiate fair terms, and avoid the lock-in traps. Stack-agnostic. Applies to SaaS, infrastructure providers, agencies, and any external dependency. + +--- + +## When to use + +- Selecting a tool or vendor for a new need +- Evaluating alternatives to a current vendor +- Build vs buy analysis +- Renewal coming up: should we stay or switch? +- Running a formal RFP or RFI +- Comparing finalists in a vendor selection +- Negotiating a contract +- Assessing vendor risk (financial, security, dependency) + +## When NOT to use + +- General cost reduction (use `cost-optimization`) +- Specific contract legal terms (those go to legal) +- Performance issues with an existing vendor (try fixing before switching) +- Hiring an agency for a one-off project (lighter framework needed) + +--- + +## Required inputs + +- The need (what problem are you solving, what would success look like) +- Constraints (budget, timeline, integration requirements) +- Stakeholders (users, IT, security, finance, legal) +- Existing context (what's already used, what's been tried) +- Compliance requirements + +--- + +## The framework: 5 phases + +A structured vendor evaluation. Skip phases at your peril. + +### Phase 1: Define the need + +Before looking at vendors, define what you actually need. + +- What problem are you solving? +- What's the user / use case? +- What does "success" look like in 6 months? In 2 years? +- What's the budget (range, not just ceiling)? +- What's the timeline? +- Are there must-have integrations or constraints? + +The temptation: skip this and start demoing. Vendors are happy to show off; you end up choosing what looks shiny rather than what fits. + +### Phase 2: Build vs buy + +Before evaluating vendors, decide whether you should build instead. + +**Build when:** +- It's core to the business (differentiating) +- The need is so specific no vendor matches +- The economics work at your scale +- You have the team to maintain it +- Vendor lock-in would be unacceptable + +**Buy when:** +- It's table stakes (not differentiating) +- The need is well-served by existing products +- The economics favor it +- The team should focus elsewhere +- The vendor's specialization beats your generalism + +Most teams over-build. The rule of thumb: buy unless there's a strong reason to build. Then question even that strong reason. + +### Phase 3: Generate the shortlist + +Cast a wider net than feels comfortable, then narrow. + +Sources: +- Internal team's existing knowledge +- Industry analyst reports (Gartner, Forrester, etc.) +- Peer recommendations (other companies similar to yours) +- Reviews (G2, Capterra; with caveats about review quality) +- Adjacent vendors you already use (often have the feature you need) +- Open-source alternatives + +Cast wide first. Aim for 5-8 candidates. Then narrow to 2-4 finalists for deep evaluation. + +### Phase 4: Score the finalists + +Use a scorecard. Without one, you'll be swayed by demo theatrics or who has the friendliest sales rep. + +Scorecard dimensions (weight by your situation): + +**Functional fit (40%):** Does it do what you need? Edge cases handled? UX quality. Workflow fit. + +**Technical fit (15%):** Integration with your stack. API quality and completeness. Data export and portability. Performance at your scale. Self-hosted, hybrid, or SaaS-only. + +**Operational fit (10%):** Onboarding effort. Training and adoption. Documentation quality. Support quality (test by submitting a ticket). SLAs. + +**Security and compliance (10%):** SOC 2, ISO 27001, HIPAA, etc., as applicable. Data residency. Encryption at rest and in transit. Access controls and audit logs. Penetration test results (ask). Subprocessors. + +**Vendor health (10%):** Years in business. Funding and runway (or revenue if private). Customer base size and similar customers. Public references. Roadmap visibility. + +**Cost (10%):** License or subscription cost. Implementation and onboarding cost. Training cost. Integration cost. Opportunity cost (in-house resource time). Switching cost (in case of failure). + +**Lock-in risk (5%):** Data export quality. Standard formats vs proprietary. Migration paths to alternatives. Open standards alignment. Contract escape clauses. + +Score each finalist 1-5 on each dimension. Multiply by weight. Sum. + +The score isn't gospel. It surfaces the tradeoffs. + +### Phase 5: Negotiate + +Most enterprise contracts are negotiable. Most aren't negotiated. + +**What's negotiable:** +- Price (multi-year, volume, prepayment, end-of-quarter timing) +- Terms (payment schedule, renewal terms) +- Success commitments (training, onboarding, support) +- SLAs (uptime, response time, credits) +- Termination clauses (auto-renewal, notice period, data export) +- Liability caps and indemnity (legal will care about these) +- Subprocessors and data handling (security/legal cares) + +**Common negotiation moves:** +- Multi-year discount (3-year for a 15-30% discount is common) +- Volume tiers (commit to higher usage for a per-unit discount) +- Annual prepayment for a discount +- Free or discounted onboarding +- Pilot pricing (trial period at reduced rate) +- "Most favored customer" clauses (if your size warrants) + +**What to avoid:** +- Multi-year lock with no escape clause for material breach +- Auto-renewal with short notice window (under 60 days; want longer) +- "All right, no further negotiation" stance from the start +- Signing without legal review + +--- + +## Workflow + +### Step 1: Define the need + +Write a one-page brief: what we need, why, success criteria, constraints, stakeholders. + +### Step 2: Build vs buy + +Honestly answer the build/buy question. Document the rationale. + +### Step 3: Generate shortlist + +Wider net first, narrowed via desk research: +- Read summaries +- Skim reviews +- Look at customer logos +- Skim docs +- Skim API specs + +Eliminate obvious misfits. Land on 2-4 finalists. + +### Step 4: Run demos and trials + +For each finalist: +- Demo with the use case (don't take their default demo; bring yours) +- Trial period if possible +- Reference calls with similar customers +- Pilot with real data if feasible + +Don't be charmed by the polished demo. Try it with your real workflow. + +### Step 5: Run security and compliance review + +Critical for any vendor handling sensitive data: +- Request SOC 2 / ISO 27001 reports +- Review their security questionnaire (most have one ready) +- Verify data handling matches your requirements +- Identify subprocessors + +This can take weeks for enterprise vendors. Start early. + +### Step 6: Score + +Apply the scorecard. Do this collaboratively with stakeholders. + +The scoring conversation matters more than the final number. It surfaces disagreement (one person scored UX 5, another scored 2: why?). + +### Step 7: Negotiate + +With the apparent winner: +- Open negotiation by asking for terms (not just price) +- Be willing to walk +- Run negotiations with #2 in parallel where appropriate (gives you leverage) + +### Step 8: Plan the rollout + +Contract signing is the start, not the end. Plan: +- Onboarding owner +- Training plan +- Migration plan if replacing an incumbent +- Success criteria at 30, 90, 180 days +- Renewal calendar + +### Step 9: Document + +Record: +- The decision and the rationale +- Alternatives considered +- Scorecard results +- Negotiated terms +- Renewal date and notice deadlines +- Owner of the relationship + +This is gold for the next renewal or the next similar evaluation. + +--- + +## Failure patterns + +**Skipping the needs definition.** Demoing first. Buying what's shiny. Realizing 6 months in that the actual need wasn't met. + +**Single-source decisions.** Talking to one vendor; deciding. No comparison. Probably overpaying or under-fitting. + +**Charisma-driven decisions.** Buying based on the sales rep's likability. The product is what you'll use for years; the rep won't be there. + +**Reference calls that the vendor curated.** Of course their references love them. Find references the vendor didn't suggest. + +**Glossing over security.** Security review skipped because of timeline pressure. Then a breach. Slow down or accept the risk explicitly. + +**Demos that don't match the use case.** Their default demo, not yours. Always do a use-case demo. + +**Trial that doesn't simulate real usage.** A trial with synthetic data tells you the product works in synthetic conditions. Use real (or close to real) data. + +**Negotiating only on price.** Terms, SLAs, and exit clauses matter more for long-term satisfaction than 5% price. + +**Auto-renewal without notice tracking.** Renewal happens; rate goes up 15%. No one was watching. Track renewals; review with notice. + +**Lock-in without exit plan.** Tightly integrating into a vendor's proprietary surface. When you want to leave, you can't. Plan exit at the start. + +**Multi-year contract for an unproven vendor.** Save the multi-year for vendors you trust. New vendor: shorter term, evaluate after. + +**No internal champion.** Tool selected; no one drives adoption. Tool sits unused. Identify the champion before signing. + +**Negotiating after a verbal commitment.** "Yes, we want to buy" means they have less reason to negotiate. Keep options open until terms are settled. + +**Ignoring red flags in security review.** Vendor's security responses are evasive or incomplete. Treat as a no. + +**Comparing apples to oranges.** Vendors price differently (per user, per usage, flat). Build a comparable cost model at your scale. + +--- + +## Output format + +A vendor evaluation document includes: + +- **Need brief:** problem, success criteria, constraints +- **Build vs buy decision:** with rationale +- **Shortlist:** 2-4 finalists with brief description +- **Scorecard:** filled out per finalist +- **Demo and trial notes:** what was learned +- **Security and compliance summary:** findings per finalist +- **Reference call notes:** what customers said +- **Recommendation:** which vendor, with rationale +- **Negotiated terms:** what was agreed +- **Rollout plan:** onboarding, training, migration +- **Renewal calendar:** with notice deadline + +--- + +## Reference files + +- [`references/evaluation-rubric.md`](references/evaluation-rubric.md) - Scoring template with weighted dimensions, 1-5 scale criteria for each dimension, and a worked vendor-comparison example. diff --git a/skills/vendor-evaluation/references/evaluation-rubric.md b/skills/vendor-evaluation/references/evaluation-rubric.md new file mode 100644 index 0000000..6689c2f --- /dev/null +++ b/skills/vendor-evaluation/references/evaluation-rubric.md @@ -0,0 +1,178 @@ +# Evaluation rubric + +A scoring template for vendor evaluations. Adapt the dimensions, weights, and scale to fit the decision. + +## The rubric structure + +Score each candidate on each dimension using a 1-5 scale. Multiply by the dimension's weight. Sum for a total. + +Numbers do not make the decision. They make differences visible. Use the totals to challenge your gut, not replace it. + +## Dimensions and what to score + +### Functional fit (typical weight: 25%) + +How well does the product do the specific job? + +| Score | Meaning | +| --- | --- | +| 5 | Does the job exactly. Built for this use case. | +| 4 | Does the job with minor configuration. | +| 3 | Does the job with workarounds or extensions. | +| 2 | Partial fit. Significant gaps. | +| 1 | Wrong tool for the job. | + +Evaluation method: trial the product on real (or representative) data. + +### Total cost (typical weight: 20%) + +Three-year total cost of ownership, including hidden fees and scaling. + +| Score | Meaning | +| --- | --- | +| 5 | Cost is well below alternatives. Pricing is predictable. No hidden fees. | +| 4 | Cost is competitive. Pricing scales gracefully. | +| 3 | Cost is fair. Some scaling concerns. | +| 2 | Cost is high or scaling is punitive. | +| 1 | Cost is prohibitive or pricing is opaque. | + +Evaluation method: project cost at 1x, 5x, and 10x current usage. Read the pricing page line by line. Ask sales for a custom quote at projected scale. + +### Reliability (typical weight: 15%) + +How often does it work? + +| Score | Meaning | +| --- | --- | +| 5 | Strong SLA, public status page, low historical incidents. | +| 4 | Reasonable SLA, transparent status, infrequent incidents. | +| 3 | Standard SLA, some visibility, occasional issues. | +| 2 | Weak SLA, limited visibility, frequent issues. | +| 1 | No SLA, no status page, customer reports of unreliability. | + +Evaluation method: read the SLA, browse status page history for 90 days, search for outage reports. + +### Integrations and ecosystem (typical weight: 15%) + +How well does it fit your stack and what is the exit story? + +| Score | Meaning | +| --- | --- | +| 5 | Native integrations to your stack, comprehensive API, easy data export. | +| 4 | Most integrations exist or are easy to build. Clean export path. | +| 3 | Some integrations, partial API, exportable with effort. | +| 2 | Limited integrations, weak API, hard to export. | +| 1 | Closed ecosystem, no API, vendor lock-in. | + +Evaluation method: list the integrations you need. Check each. Test the export. + +### Operational fit (typical weight: 10%) + +How easy is it to run? + +| Score | Meaning | +| --- | --- | +| 5 | Self-service, well-documented, low ongoing burden. | +| 4 | Mostly self-service. Support responds when needed. | +| 3 | Requires some hand-holding from vendor. | +| 2 | Requires significant ops effort or vendor intervention. | +| 1 | Black box that needs constant management. | + +Evaluation method: read the docs, send a test support question, ask "who would own this internally" and gauge the answer. + +### Vendor durability (typical weight: 10%) + +Will they be around in 3 years? + +| Score | Meaning | +| --- | --- | +| 5 | Profitable, established, deep customer base, growing. | +| 4 | Well-funded, growing, healthy customer base. | +| 3 | Stable but uncertain. Some risk signals. | +| 2 | Layoffs, leadership turnover, customer churn signals. | +| 1 | Likely to be acquired, shut down, or pivot. | + +Evaluation method: company news search, LinkedIn for headcount trends, customer review sites for sentiment. + +### Support quality (typical weight: 5%) + +What happens when something goes wrong? + +| Score | Meaning | +| --- | --- | +| 5 | Fast, technical, available 24/7 if needed. | +| 4 | Reliable, knowledgeable, business-hours coverage. | +| 3 | Adequate. Sometimes slow. | +| 2 | Slow, scripted, escalation needed for real issues. | +| 1 | Unreachable or unhelpful. | + +Evaluation method: send a real technical question during the trial. Time the response. Read the answer. + +## Worked example: picking an email service provider + +Job statement: "Send 200K transactional emails per month, 50K marketing emails per month, with deliverability above 98%, webhook delivery confirmation, and integration with our CRM." + +### Weighted scores + +| Dimension | Weight | Vendor A | Vendor B | Vendor C | +| --- | --- | --- | --- | --- | +| Functional fit | 25% | 5 (1.25) | 4 (1.00) | 5 (1.25) | +| Total cost | 20% | 3 (0.60) | 4 (0.80) | 2 (0.40) | +| Reliability | 15% | 5 (0.75) | 4 (0.60) | 5 (0.75) | +| Integrations | 15% | 4 (0.60) | 3 (0.45) | 5 (0.75) | +| Operational fit | 10% | 4 (0.40) | 5 (0.50) | 3 (0.30) | +| Vendor durability | 10% | 5 (0.50) | 3 (0.30) | 5 (0.50) | +| Support quality | 5% | 4 (0.20) | 4 (0.20) | 5 (0.25) | +| **Total** | **100%** | **4.30** | **3.85** | **4.20** | + +### What the numbers say + +Vendor A and Vendor C are close. The difference comes down to cost (B and A both better than C) vs integrations (C better than A and B). + +### What the numbers do not say + +The numbers do not capture: + +- A's pricing has a cliff at 500K monthly emails. We project crossing that within 18 months. +- C has best-in-class deliverability for our specific industry. +- B is rumored to be in acquisition talks. + +The numbers narrow the field to A and C. The qualitative read picks one. In this hypothetical: Vendor C wins on the strength of deliverability and ecosystem fit, despite being more expensive, because deliverability is the actual job and cost is recoverable. + +### What the decision memo looks like + +``` +Vendor: C +Reasoning: +- Best functional fit on deliverability and webhook reliability. +- Strongest ecosystem and exit story. +- Higher cost is justified by ROI from deliverability lift. +- A was a strong second; we will revisit if C disappoints in + year 1. + +Decision date: [date] +Reviewer: [person] +Next review: [date + 12 months] +Contract terms: +- 1-year commit, with option to extend +- Termination notice: 60 days +- Data export confirmed working in trial +``` + +## Adapting the rubric + +Different decisions weight dimensions differently. Some examples: + +- **Hosting decision**: reliability and operational fit weighted higher. +- **CMS decision**: functional fit and integrations weighted higher. +- **Analytics decision**: vendor durability and integrations weighted higher (you keep data here for years). +- **Payment processor decision**: reliability, support quality, and vendor durability weighted higher. + +Adjust weights before scoring. If you adjust after, you are rationalizing. + +## How to use the rubric without lying to yourself + +- Score independently first if multiple stakeholders are evaluating. Compare scores. Discuss the differences. +- Sleep on the scores before deciding. +- If the math points to a vendor your gut hates, find out why. Either the rubric is missing a dimension or your gut is wrong. Both happen. +- Document the score, the weights, and the qualitative notes. Store with the contract. diff --git a/skills/vertical-site-conventions/SKILL.md b/skills/vertical-site-conventions/SKILL.md new file mode 100644 index 0000000..b9f6e22 --- /dev/null +++ b/skills/vertical-site-conventions/SKILL.md @@ -0,0 +1,213 @@ +--- +name: vertical-site-conventions +description: "Compose pages and sites that read as their vertical: ecommerce-catalog storefronts that look like storefronts, hospitality-food sites that look like restaurants, b2b-manufacturer sites that look industrial. Use this skill whenever the user wants to build a site that looks like the vertical it serves, fix a build that reads as generic or off-vertical, build to an experience bar produced by competitor-experience-audit, or compose pages with the merchandising, density, and layout conventions a credible site in the category is expected to carry. Triggers on vertical conventions, storefront layout, ecommerce layout, retail conventions, merchandising layout, category page composition, site composition, build to the experience bar, make it look like the vertical, off-vertical, looks generic, build conventions for a vertical, site grammar. Also triggers when a build that is technically clean reads wrong for its category, and the cause is composition, not visual taste." +category: design +catalog_summary: "Vertical page and site composition built to the experience bar" +display_order: 4 +--- + +# Vertical Site Conventions + +Compose pages and whole sites to the layout, density, and merchandising conventions that make a build read as a credible member of its vertical. Stack-agnostic. Works on any framework that can express server-rendered pages and component composition. + +This skill owns vertical-level composition: which modules go where, how dense the page is, how much of the catalog or offering is surfaced, and which paths the navigation serves. It routes the day-to-day visual decisions to `design-standards`, the aesthetic register to `creative-direction`, the site-structure modeling to `information-architecture`, and the component implementation to `frontend-component-build`. It does not duplicate any of them; it composes their outputs into a vertical-correct site. + +It is the build-side counterpart to `competitor-experience-audit`. The audit measures the field on seven dimensions; this skill builds to those same seven, dimension by dimension. The two are deliberately structured as two sides of one standard so an experience bar produced by the audit maps one-to-one onto what this skill builds. + +--- + +## When to use + +- Building a new site in a vertical you have not built in before +- Fixing a build that reads as generic or off-vertical even though it is technically clean (the SEO, accessibility, and component implementation are correct, but the page does not read like its category) +- Building to an experience bar produced by `competitor-experience-audit` (the audit-fed path is the intended use) +- Adding the merchandising, density, and navigation conventions a site in this category is expected to carry +- Building a showcase or demo where the build must read as its vertical, not as a generic SaaS landing page + +## When NOT to use + +- Day-to-day visual decisions on a known build (use `design-standards`) +- Defining the brand register or aesthetic from scratch (use `creative-direction`, `brand-archetype-system`, `brand-discovery`) +- Building one component well (use `frontend-component-build`) +- Modeling site structure and navigation hierarchy from scratch (use `information-architecture`) +- Building a formal design system or token system (use `design-system`) +- Auditing the competitive field for what conventions exist (use `competitor-experience-audit`; this skill consumes that audit's output, it does not produce it) + +--- + +## Required inputs + +- The site shape the build is for, from the controlled list: `ecommerce-catalog`, `inventory-listing`, `directory-marketplace`, `local-service-booking`, `subscription-app`, `hospitality-food`, `institution-mission`, `b2b-manufacturer`, `ecommerce-standout`, `hospitality-experience`. +- An experience bar from `competitor-experience-audit` (the cross-site patterns and gaps for the vertical). If absent, the skill falls back to the per-shape default conventions in the references; the audit-fed path is stronger and is the intended use. +- The brand register and aesthetic decisions (from `creative-direction` or already settled). This skill does not redefine them. +- The framework or technical context the build will use (the skill is stack-agnostic but the consumer needs to know). + +If the site shape is unclear, ask. Building to the wrong shape's conventions produces a build that reads off-vertical, which is the exact failure this skill exists to prevent. + +--- + +## The framework: build to the seven dimensions + +The framework mirrors the seven dimensions `competitor-experience-audit` measures. Each is expressed here as build guidance (what to do) rather than audit questions (what to observe). Run them in order; the synthesis in dimension 7 is the composition checklist that catches what the earlier six missed. + +### 1. Build the primary task as the dominant, earliest element + +The visitor arrives with a primary job. The leaders in the vertical lead with that job; off-vertical builds bury it behind marketing copy or competing CTAs. + +- Identify the vertical's primary task from the experience bar or the per-shape reference. (Ecommerce-catalog: a fitment, search, or category-entry interaction. Hospitality-food: a menu or reservation entry. Inventory-listing: a search-and-filter. Local-service-booking: a "book now" or service-picker.) +- Give that task the largest, earliest interactive treatment in the hero. +- Demote competing CTAs. The hero gets one primary action; secondary actions live below the fold or in the chrome. +- Reach the core task without scrolling on the device class the vertical's visitors use. +- For commercial pages, sticky a compact version of the primary task to the chrome so it stays reachable on scroll. + +If the primary task cannot be the hero (a constraint from a stakeholder, a regulated vertical), surface the closest equivalent and document the compromise. Do not silently push the primary task below the fold. + +### 2. Build to the vertical's layout register and density + +Most off-vertical builds default to a generic SaaS-airy landing page. Retail and catalog verticals are denser; editorial verticals are calmer; hospitality is image-led. Build to the field's density, not to a default. + +- Identify the register from the experience bar or the per-shape reference (storefront-dense, editorial-calm, marketing-airy, image-led). +- Match the field's content-per-viewport: a catalog vertical surfaces more modules above the fold than a SaaS landing page. +- Choose the module count above the fold deliberately. State the count in the build notes. +- Route the actual color, type, and aesthetic choice to `creative-direction` and `design-standards`. This skill owns the density and module-count decision, not the visual register itself. + +Composition decision lives here. Visual register lives there. Do not redefine either; route to the right skill. + +### 3. Build the merchandising and category surface the vertical uses + +How much of the catalog or offering is surfaced at once, and in what shape, is a per-vertical decision the build must own. + +- Surface the catalog the way the vertical does: how many category, collection, or entry-point modules appear before scroll. +- Signal depth the way the vertical signals it: mega-menu hover, grid of category cards, faceted-search side rail, breadcrumb-driven hierarchy. Pick one and commit; do not stack three. +- Choose flat (one tier visible) or hierarchical (parent plus child categories shown together) per the vertical's convention. +- Use icon / image / text / hybrid category presentation per the vertical. + +Cross-reference `information-architecture` for the structural modeling of the nav tree. This skill owns the compositional surface; that skill owns the structural model. + +### 4. Build both the know-what-I-want and the browse path the vertical expects + +Verticals differ on which path is primary. A catalog vertical needs both search and category browse, with search often primary. A hospitality-food site rarely needs search but always needs a menu and a reservation entry. Build to the paths the field actually offers, in the prominence the field gives them. + +- List the paths the experience bar names (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience). +- Score each path as primary, secondary, or absent per the vertical. +- Build the primary paths into the hero or primary nav. Build the secondary paths into the chrome or below the fold. Drop the paths the field does not use. +- Search input prominence is a per-vertical decision: header-primary, secondary in a side rail, or absent. Match the field. + +Route the structural nav modeling to `information-architecture`; route the search UX patterns to that skill or to the project's existing search component. This skill owns which paths exist and how prominent each is. + +### 5. Build the brand posture consistently across the page + +The brand register is set by `creative-direction` and `brand-archetype-system`. This skill does not redefine it. But composition decides whether the posture holds across the page or only in the hero. + +- Carry the brand register from the hero into the nav, the cards, the empty states, the trust signals, and the footer. A premium-utilitarian register that disappears below the hero is a composition failure, not a brand failure. +- Apply the voice consistently in headings, microcopy, CTAs, and empty states. Do not let the empty states default to generic copy. +- Hold the imagery posture across the page: a vertical that uses studio product photography in the hero does not switch to abstract illustration in the trust section. + +Route the actual register choice and the voice attributes to `creative-direction` and `brand-voice`. Own the consistency requirement here. + +### 6. Build the trust and conversion signals the vertical requires + +Each vertical has a different set of trust signals it is expected to carry. A build that ships without them reads as not-yet-credible. Build them in. + +- Identify the required signals from the experience bar or the per-shape reference. (Ecommerce-catalog: reviews, guarantees, pricing transparency, stock signals, fitment confirmation, shipping promises. Hospitality-food: hours, location, reservation availability, menu price range. B2b-manufacturer: certifications, customer logos, spec sheets. Local-service-booking: licensing, insurance, service-area, response time.) +- Surface them where the field surfaces them. Reviews near the buying action; service-area in the hero; certifications in the chrome. +- Honor the functional-vs-demo line for showcase builds: real where touchable (real reviews if they exist, real cart state), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment). + +### 7. Run the synthesis as a composition checklist + +The seventh dimension is the synthesis: the specific conventions a credible build in this vertical must have, named explicitly. Run this as a pre-ship checklist before declaring the composition done. + +- Pull the conventions from the experience bar's dimension 7, or from the per-shape reference's recurring-conventions section. +- For each, confirm the build does it. Mark each item present, absent, or routed elsewhere (with a link to the routing decision). +- If three or more conventions are absent, the build is off-vertical. Go back to the earlier dimensions; this is not a polish-pass fix. +- If one or two are absent, name the reason: deliberate positioning (the wedge the build is exploiting from the audit's gaps section), constraint (stakeholder, technical), or oversight (fix before ship). + +The synthesis is what catches builds that pass dimensions 1 through 6 individually but compose into something off-vertical anyway. Run it. + +--- + +## How the skill consumes an experience bar + +When `competitor-experience-audit` has run for the vertical, its output is the input to this skill. The audit's seven dimensions map directly onto this skill's seven, in order. Concretely: + +- The audit's `Primary-task prominence` pattern names what to build in this skill's dimension 1. +- The audit's `Layout register and density` pattern names the density target for dimension 2. +- The audit's `Merchandising and category surface` pattern names the surface shape for dimension 3. +- The audit's `Primary navigation and search paths` pattern names the path inventory for dimension 4. +- The audit's `Brand register and conviction` pattern names the register `creative-direction` should be working from, which this skill carries across the page in dimension 5. +- The audit's `Trust and conversion signals` pattern names the required signals for dimension 6. +- The audit's `Recurring vertical conventions` are the checklist for dimension 7. +- The audit's `Gaps` section names the positioning opportunity the build can exploit as its wedge. + +If no audit has been run, fall back to the per-shape reference files in `references/`. The default conventions there are derived from observable cross-site patterns and are honest, but a vertical-specific audit is stronger and is the intended path. + +--- + +## Stays in its lane (load-bearing) + +This skill owns one thing: vertical-level page and site composition. It routes everything else, and that routing discipline is what keeps it useful and what keeps the catalog clean. + +- Visual tokens, color, type, contrast, spacing scale: route to `design-standards`. +- Aesthetic register, archetype, voice attributes: route to `creative-direction` and `brand-archetype-system`. +- Site structure, nav hierarchy, URL design: route to `information-architecture`. +- Component API, states, accessibility implementation: route to `frontend-component-build`. +- Formal design system, token library, component documentation: route to `design-system`. +- The audit that produces the experience bar: route to `competitor-experience-audit`. +- On-page SEO and accessibility audits: route to `seo-onpage` and `accessibility-audit`. + +If a build decision sits inside one of those skills, do not restate the standard here. Link to the skill and let it own its territory. + +--- + +## Workflow + +1. **Confirm the site shape and the experience bar.** Site shape from the controlled list. Experience bar from `competitor-experience-audit` if run; the per-shape reference otherwise. +2. **Run dimensions 1 through 6 in order.** For each, name the build decision and which other skill it routes to (for the parts that route elsewhere). +3. **Run dimension 7 as a checklist.** Confirm every recurring convention from the vertical is present, absent for a stated reason, or routed elsewhere. +4. **Write the composition notes.** Use the template in [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md). The notes are what `frontend-component-build` and `design-standards` read as the spec to implement against. +5. **Hand off to the implementation skills.** This skill's output is composition decisions, not finished components. The build is done when those decisions have been implemented through `frontend-component-build`, `design-standards`, and the project's component library. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- **"Make it look modern."** Vague. Ask which vertical, which experience bar, which conventions. "Modern" without a vertical produces the generic SaaS-airy build this skill exists to prevent. +- **Building to a generic / SaaS-airy default when the vertical wants a denser storefront.** Retail and catalog verticals surface more per viewport than a marketing page. If the build looks calm and roomy, check the density against the field. +- **Burying the primary task.** A hero stuffed with marketing copy and three competing CTAs is the most common off-vertical failure. Dimension 1 is not optional. +- **Redefining aesthetic vocabulary instead of routing to `creative-direction`.** This skill does not coin new register names or invent new voice attributes. If the question is what posture the brand takes, that is `creative-direction`'s call. +- **Treating the experience bar as optional when it is available.** If `competitor-experience-audit` has run for the vertical, the bar is the spec. Building to the per-shape default while ignoring the audit's bar is half a build. +- **Producing a template instead of building to the field's actual conventions.** Per-shape references are starting points, not finished templates. They name the patterns the field shares; the build still has to land them in this brand and this brief. +- **Skipping dimension 7.** A build that passes dimensions 1 through 6 individually can still compose off-vertical. The synthesis check is the one that catches it. +- **Calling implementation detail "composition".** Button radius, font size, color contrast are `design-standards` decisions. Module count, primary-task prominence, category-surface depth are this skill's decisions. Do not bleed across the line. + +--- + +## Output format + +Default output is a markdown set of composition notes at `composition-[site-shape]-[brand-slug].md` in the project root. Structure: + +1. The site shape and the experience bar consulted (or "no audit available; per-shape reference used") +2. Dimension-by-dimension build decisions (1 through 6) +3. The synthesis checklist (dimension 7), each convention marked present / absent / routed +4. The wedge (which gap from the audit's gaps section this build is exploiting, if any) +5. The hand-off list: what `frontend-component-build`, `design-standards`, and `creative-direction` need from these notes to implement + +Keep notes under 1500 words. The notes are a spec for the implementation skills; if they need more detail, that is a sign one of those skills should own the deeper specification. + +--- + +## Reference files + +- [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md) - The per-dimension build checklist applied as a pre-ship review. Mirror of the audit's dimension checklist on the build side. +- [`references/shape-ecommerce-catalog.md`](references/shape-ecommerce-catalog.md) - Default conventions for the ecommerce-catalog shape (first test case; auto-parts and similar dense storefronts). +- [`references/shape-inventory-listing.md`](references/shape-inventory-listing.md) - Stub; fill when the first inventory-listing demo is built. +- [`references/shape-directory-marketplace.md`](references/shape-directory-marketplace.md) - Stub. +- [`references/shape-local-service-booking.md`](references/shape-local-service-booking.md) - Stub. +- [`references/shape-subscription-app.md`](references/shape-subscription-app.md) - Stub. +- [`references/shape-hospitality-food.md`](references/shape-hospitality-food.md) - Stub. +- [`references/shape-institution-mission.md`](references/shape-institution-mission.md) - Stub. +- [`references/shape-b2b-manufacturer.md`](references/shape-b2b-manufacturer.md) - Stub. +- [`references/shape-ecommerce-standout.md`](references/shape-ecommerce-standout.md) - Stub. +- [`references/shape-hospitality-experience.md`](references/shape-hospitality-experience.md) - Stub. diff --git a/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md b/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md new file mode 100644 index 0000000..5b9abf4 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md @@ -0,0 +1,120 @@ +# Shape: b2b-manufacturer + +Industrial manufacturers, robotics, machine tools, components, OEMs, industrial integrators. The reader arrives as a buying engineer, a procurement specialist, an operations leader, or an industrial integrator, wanting specs, applied examples with named metrics, certifications, and a short path to an engineer-not-a-sales-rep. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (robotics, machine tools, semiconductor equipment, industrial sensors), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** see the products with specs visible, see the applied examples with named metrics, and request a demo or working session with an application engineer. The B2B-manufacturer conversion is a sales conversation, not a transactional add-to-cart; the page is a credibility document and a routing tool. + +**Build conventions:** +- The demo / contact action is in the chrome on every page AND in the hero AND at the end of each product detail page. Three placements, one form. +- The form is short. Six fields at most (name, company, work email, role, product of interest, problem statement). Long forms signal funnel-thinking; the field's leaders treat the first call as a working session, not a qualification step. +- Specs are surfaced in HTML, not in a PDF gated behind a marketing form. PDF datasheets exist for downloading after the page has done its job, not as the only path to the spec. +- The site does not invent dollar figures for products that are quote-based. Quote-based products carry "request a quote" or "talk to engineering," not "$ X." + +## 2. Layout register and density + +**Register:** technical-considered. Denser than a SaaS marketing page; less dense than an ecommerce catalog. Photography is industrial: factory floor, product close-up on a clean concrete surface, single subject. Cinematic, restrained, not Instagram. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: a single-subject hero photograph of a product (or a representative product), a declarative one-line manifesto or capability statement, the demo CTA, AND a product-or-application strip. A B2B-manufacturer hero that leads with a marketing slogan and no product visible reads as a brochure, not equipment. +- The hero photograph is industrial, not lifestyle. Equipment on the factory floor or in studio; no humans in lab coats unless they are doing real work. +- Whitespace is engineered, not generous. The page is a working document. Editorial-airy layouts read as off-vertical; catalog-dense layouts read as wrong too. A considered mid-density grid is the convention. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be cinematic-premium (anode-ev style: drivetrain-as-design), technical-considered (edge-devtools style: spec-as-page), institutional-professional (counsel-law style: certification-led), or rugged-utilitarian (forge-fitness style: equipment-as-tool); not flowery or expressive. + +## 3. Product surface + +**Conventions:** +- A product listing page carries each product line with a name, a tagline (one declarative sentence), three to six headline specs, a product image, and a link to the detail page. +- A product detail page carries: full spec table (payload, reach, repeatability, latency, IP rating, safety standards, integration interfaces), the blurb, **a primary product image plus at least one secondary image** (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot), the certifications applicable to this product, the applications that use it, a demo CTA wired to this product, integration-interface section (OPC UA, EtherNet/IP, REST API, etc.). +- Specs are an HTML table, not an image of a table from a PDF. Crawlers and screen readers read it; copy-paste works. +- Product imagery is real, single-subject, industrial-product photography. Premium register matching the brand (factory-floor or studio backdrop, controlled lighting, the machine as the subject). Spec tables alone read as a brochure-with-numbers; a buyer needs to see the machine. Specs remain the spine of the page; imagery supports the specs, it does not replace them. +- Certifications are carried at the **product level** on the detail page, not buried on About. A buyer screening for "must be ISO 10218 certified" should see the certification on the product page in under three seconds. +- Quote-based pricing is named openly. "Quote-based"; "Talk to engineering"; "Configurations vary by integration." A blank price field signals "this is hidden from me" rather than "this is configured to your line." +- Product imagery is honest-demo where the build is a showcase: unbranded equipment, no fabricated competitor logos, no real-world manufacturer brand marks, no baked-in pricing or spec text in the image (specs live in HTML). Industrial-product image generation is prone to hallucinating brand badges and control-panel writing; the image-pipeline gate's brand-name and fabricated-logo checks are load-bearing here. + +## 4. Applications surface (the case studies) + +**Conventions:** +- An **applications page** with named industries and named metrics. Battery cell assembly, warehouse throughput, precision machining, automotive sub-assembly. Each application named with the cycle time, the throughput change, the payback period, the first-pass yield, the operator-hours saved. +- Genericized marketing prose ("a global leader in X partnered with us") is the field's miss; the convention is to name the metric even if the customer is anonymized. "Throughput up 38%. Scrap rate down 22%. Cycle time per module under nine seconds." Pattern-level facts are credible; vague success language is not. +- Each application links to or references the products it uses, so a reader who arrived via Products can cross-walk to Applications and back. +- For showcase or demo builds, the functional-vs-demo line: pattern-level facts are acceptable but should be labeled as such in the workup; the build should not imply a real anonymized customer when one does not exist. + +## 5. Company, certifications, and engineering posture + +**Conventions:** +- A Company page with founding year, headquarters, certifications, plain-language about the engineering posture. Not a brand story. +- Certifications baseline at the company level (ISO 9001, ISO 10218, UL, AS9100, IEC 61508, etc.) and at the product level on each detail page. Buyers screen for these; making them findable is a credibility move. +- Made-in-X is named openly if relevant (made in Pittsburgh, designed in Munich, assembled in Taiwan). Country of design and country of manufacture are different and both are surfaceable. +- Founding team, depth of bench, customer count, plant size are facts a buyer's committee asks for; the page should answer them without forcing a sales conversation first. +- The engineering posture (what the company believes about how to build equipment) is a real thing to name. "The factory is the test bench" or "every product runs on our own line before it ships" is the kind of plain claim that does the work brand-essay generic copy fails to do. + +## 6. JSON-LD and structured data + +**Conventions:** +- Organization schema at the layout level: name, description, url, logo, founding date, address. +- Product schema on each product detail page: name, description, category, brand, manufacturer, sku, identifier. +- Where pricing is quote-based, omit the price field rather than fake one. Structured-data validators flag missing price; the buyer reads quote-based as honest. +- BreadcrumbList on every page beneath the home. + +## 7. Demo / contact flow + +**Conventions:** +- The demo form is on-site, six fields, no third-party gating. Form mounts the same component everywhere. +- The form does not require a phone number to submit; phone is optional. +- The "what happens next" copy is honest. "An application engineer reaches out within one business day to schedule a working session" is the field's leader posture. "A representative will be in touch shortly" is the field's miss. +- Phone-as-fallback: a visible phone number for buyers who would rather call. +- For procurement-led conversations, a separate "Request a quote" path that asks for the line spec (units per year, integration constraints, certifications required) is conventional; for a single-build demo, the demo form covers both. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- Specs visible, in HTML, on every product page. +- Applications named with named metrics. +- Certifications surfaced at the product level. +- Plain company facts (founding, headquarters, plant size, deployment geography). +- Engineering-posture statement that names what the company believes. +- Optional but conventional: a named-publication pull-quote or analyst quote ("X named Volta to the top tier"). Logo walls are the field's miss; one named pull-quote is the convention. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction, real spec tables), honestly demo where it needs a backend (clearly labeled demo request modal, no fake CRM entry, no fake customer logos). + +## 9. Recurring vertical conventions (the synthesis) + +A credible B2B-manufacturer site, against the field of leaders, carries eleven conventions: + +1. A single-subject industrial hero photograph above the fold at a 1280x800 desktop viewport, with a declarative one-line manifesto and the demo CTA. +2. **(Density-bearing)** Specs surfaced as an HTML table per product, not gated behind a PDF. +3. A product listing page with each product line, its tagline, three to six headline specs, and a product image visible per line. +4. A product detail page with full spec table, certifications at the product level, applied applications, and a demo CTA wired to the product. +5. **(Density-bearing)** An applications page with named industries and named metrics (cycle time, throughput change, payback period, first-pass yield); no genericized "global leader in X" prose. +6. A Company page with founding year, headquarters, certifications, and an engineering-posture statement that names what the company believes. +7. JSON-LD Organization at the layout level; Product schema on each product detail page (with the primary and secondary image URLs populated under image). +8. **(Density-bearing)** A demo / contact form that is on-site, six fields, no third-party gating; the demo flow lives within the site's visual contract. +9. Honest "what happens next" copy on the demo path; phone-as-fallback visible. +10. Where pricing is quote-based, no fake dollar figures; the page names the quote-based posture openly. +11. **(Density-bearing, new)** Real product imagery on the product surface. Each product detail page carries a primary product image plus at least one secondary (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot). Product listing cards lead with a product image above the spec table, not specs alone. Premium / industrial / single-subject register, honest-demo where the build is a showcase (no fabricated brand marks or pricing baked into the imagery). Spec tables remain the spine of the page; imagery supports the specs, it does not replace them. + +**Threshold and density-bearing items.** A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 5, 8, and 11 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a brochure, a lead-gen funnel, or a half-built equipment site instead of a credibility document. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of the density-bearing four will make the build read off-vertical regardless of how many other conventions it hits. Treat the density-bearing items as non-skippable. + +**Why convention 11 needed to be added separately.** The first b2b-manufacturer build (Volta Robotics) carried conventions 1 through 10 cleanly: spec tables in HTML, named-metric applications, six-field on-site demo form, certifications at the product level, JSON-LD Product schema. It passed the checklist and still read thin against a premium-industrial buyer's eye: one hero image, then spec-only product cards on the lineup and spec-only detail pages. A premium capital-equipment buyer expects to see the machine, multiple angles, in-context on a line. The model flagged it, the human confirmed it. A spec-led build can be checklist-correct and still register as a brochure-with-numbers rather than equipment. Convention 11 closes that gap: the product surface carries real product imagery as a chrome-level convention, not a polish extra; the spec table is the spine and the imagery is the evidence the spine describes a real machine. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Specs are the page.** Most competitors gate specs behind a marketing form for a PDF download. A build that surfaces the full spec table in HTML on every product page owns the "we are not afraid of comparison" position. +- **Named metrics on the applications page.** Most competitors write applications in genericized marketing prose. A build that names cycle time, throughput change, and payback period (even with the customer anonymized) owns the "we ship outcomes, not narratives" position. +- **Engineer-facing demo flow.** Most competitors route demo requests through marketing-gated long forms with MQL scoring. A build that runs a six-field on-site form and connects to an application engineer (not a sales rep) owns the "first call is a working session" position. +- **Certifications at the product level.** Most competitors mention certifications on About. A build that carries the applicable certifications on each product detail page owns the "we screen the way your committee does" position. +- **Engineering-posture statement.** Most competitors write a brand story. A build that names a plain engineering belief ("the factory is the test bench"; "every product runs on our own line before it ships") owns the "we mean what we say" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-conventions-checklist.md b/skills/vertical-site-conventions/references/shape-conventions-checklist.md new file mode 100644 index 0000000..17b57ae --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-conventions-checklist.md @@ -0,0 +1,97 @@ +# Vertical Site Conventions Checklist + +Run this checklist as the composition pre-ship review. It mirrors the seven dimensions `competitor-experience-audit` measures, on the build side. Mark each item present, absent for a stated reason, or routed elsewhere (with a link). + +Three or more absences across the seven dimensions means the build is off-vertical and needs composition work, not a polish pass. + +--- + +## 1. Primary-task prominence + +- [ ] The vertical's primary task is named (from the experience bar or per-shape reference). +- [ ] The primary task is the largest, earliest interactive element in the hero. +- [ ] No competing CTA is louder than the primary task in the hero. +- [ ] The primary task is reachable without scroll on the device class the vertical's visitors use. +- [ ] A compact version of the primary task is sticky to the chrome on scroll (for commercial pages). +- [ ] If the primary task is not the hero, the compromise is documented and the closest equivalent is surfaced. + +## 2. Layout register and density + +- [ ] The vertical's register is named (storefront-dense, editorial-calm, marketing-airy, image-led). +- [ ] The module count above the fold is decided deliberately, not by default, and matches the field's content-per-viewport. +- [ ] The visual register (color, type, aesthetic) is routed to `creative-direction` and `design-standards`, not redefined here. +- [ ] The page does not default to a generic SaaS-airy layout when the field uses a denser register. + +## 3. Merchandising and category surface + +- [ ] The number of category, collection, or entry-point modules above the fold matches the field. +- [ ] The depth signaling pattern is chosen and committed to (mega-menu, grid, faceted side rail, breadcrumb hierarchy). Not stacked. +- [ ] Flat or hierarchical category presentation matches the vertical. +- [ ] Category presentation style (icon, image, text, hybrid) matches the field. +- [ ] The nav tree structural modeling is routed to `information-architecture`, not redefined here. + +## 4. Navigation and search paths + +- [ ] The paths the field offers are inventoried (by category, brand, attribute, vehicle, location, occasion, audience). +- [ ] Each path is scored primary, secondary, or absent against the vertical. +- [ ] Primary paths land in the hero or primary nav; secondary paths land in chrome or below the fold. +- [ ] Search input prominence matches the vertical (header-primary, secondary side-rail, or absent). +- [ ] Paths the field does not use are not surfaced (do not invent paths the vertical does not carry). + +## 5. Brand register and conviction + +- [ ] The brand register is set by `creative-direction` and `brand-archetype-system`, not by this skill. +- [ ] The register carries from the hero into the nav, cards, empty states, trust signals, and footer. +- [ ] Voice is applied consistently in headings, microcopy, CTAs, and empty states. Empty states do not fall back to generic copy. +- [ ] Imagery posture is consistent across the page (no switch from studio photography to abstract illustration mid-page without a reason). + +## 6. Trust and conversion signals + +- [ ] The vertical's required signals are inventoried from the experience bar or per-shape reference. +- [ ] Each required signal is built into the page where the field places it (reviews near the buying action, service-area in the hero, certifications in the chrome, etc.). +- [ ] For showcase or demo builds, the functional-vs-demo line is honored: real where touchable, honestly demo where it needs a backend (clearly labeled demo modals, no fake payment, no real account creation). + +## 7. The synthesis: recurring vertical conventions + +Pull the conventions from the experience bar's dimension 7 (or the per-shape reference's "recurring conventions" section). For each: + +- [ ] Convention 1: __________________ , [present / absent (reason) / routed to ____] +- [ ] Convention 2: +- [ ] Convention 3: +- [ ] Convention 4: +- [ ] Convention 5: +- [ ] Convention 6: +- [ ] Convention 7: +- [ ] Convention 8: +- [ ] Convention 9: +- [ ] Convention 10: +- [ ] (Add rows as needed for the vertical's full convention list.) + +**Density-bearing items.** Some conventions are density-bearing: their absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. For the ecommerce-catalog shape, conventions 2 (category surface band above the fold at 1280x800), 9 (a promotional or deal surface near the top), and 10 (an inventory or catalog-depth signal a first-time visitor sees) are the density-bearing trio. Each shape's per-shape reference names its own density-bearing items. + +Mark the density-bearing items explicitly in the list above. Missing any one density-bearing item is sufficient to fail the synthesis on its own, regardless of how many other conventions hit. This rule comes from a real build hitting 6 of 8 conventions in an earlier (pre-density-bearing) form of this reference and still reading off-vertical because the density-bearing items it missed were the load-bearing ones. + +**Threshold:** a build hitting 8 of 10 (or the equivalent ratio for shapes with a different convention count) is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more conventions, OR any density-bearing item, is off-vertical and needs composition work, not a polish pass. Go back to dimensions 1 through 6. + +--- + +## The wedge + +If the experience bar named a recurring gap across the field, the build can exploit it as positioning. State which gap is being exploited and how the build addresses it. + +- **Gap exploited:** [from the audit's gaps section] +- **How the build addresses it:** +- **What that buys the build:** + +If the build is not exploiting a gap, that is fine; the build hits the experience bar and competes on execution. Say so explicitly. + +--- + +## Hand-off list + +- [ ] `frontend-component-build`: the components the build needs and the states each must support. +- [ ] `design-standards`: the tokens, contrast, and spacing the composition assumes. +- [ ] `creative-direction`: the register and voice the composition carries. +- [ ] `information-architecture`: the nav tree and URL structure the composition expects. + +The hand-off list is what makes this skill's output a real spec for the implementation skills, not a wish list. Each item should be specific enough that the implementation skill can read it and start. diff --git a/skills/vertical-site-conventions/references/shape-directory-marketplace.md b/skills/vertical-site-conventions/references/shape-directory-marketplace.md new file mode 100644 index 0000000..50a1acd --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-directory-marketplace.md @@ -0,0 +1,19 @@ +# Shape: directory-marketplace + +Service-provider directories, home services marketplaces, freelance / contractor matching. The reader arrives wanting to find a provider for a need they can name. + +## Status + +Stub. Fill when the first directory-marketplace demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** describe the need (service, location, urgency) and surface ranked providers. Often a wizard pattern (service picker, then ZIP, then refine). +- **Layout register:** trust-led and service-led. Photos of providers, ratings, and quoted response time carry the page. +- **Merchandising:** the provider list is the merchandising. Hero often carries a service-picker plus a band of top categories. +- **Paths:** by service category primary; by location primary; by provider (named) secondary. +- **Brand register:** marketplace-neutral or strongly opinionated (premium-curated vs widest-net). Cross-reference `creative-direction`. +- **Trust signals:** verified, licensed, insured, response time, ratings with review count, dispute resolution promise. +- **Synthesis (provisional):** service picker as the first interaction, location capture early, provider ratings with substantive review counts, response-time signal, clarity on what is curated vs open. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md b/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md new file mode 100644 index 0000000..fae3e57 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md @@ -0,0 +1,119 @@ +# Shape: ecommerce-catalog + +Dense catalog storefronts. Auto-parts, hardware, industrial supply, mass-merchant retail. The reader arrives with a part to find or a category to browse. The build leads with the path that gets them to the part. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (auto-parts, hardware, tooling), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** the path to a part. For verticals where compatibility matters (auto-parts, electronics), this is a fitment / compatibility selector. For undifferentiated catalogs (hardware, office supply), this is a search input. For mass merchants, this is category-entry-grid. + +**Build conventions:** +- The primary task is the largest, earliest interactive element. Not a sidebar widget; not a modal triggered by a marketing CTA. +- Competing CTAs (newsletter, account, brand pitch) live below the fold or in the chrome. +- The primary task is sticky to the chrome on scroll. A visitor mid-page who realizes the fitment is wrong can change it without scrolling back to the hero. +- For fitment-led verticals: setting the vehicle / compatibility once carries to every subsequent page. The selection is the global context, surfaced visibly. + +## 2. Layout register and density + +**Register:** storefront-dense. Not editorial; not marketing-airy. The page is a working surface, not a brand brochure. + +**Build conventions:** +- More than four modules above the fold on desktop is normal for this shape. Two-module heros are off-vertical. +- **Above the fold at a 1280x800 desktop viewport** (not "the first or second viewport"; the assertion is hard) the page carries: the primary task, the category surface band, AND at least one merchandising or trust signal. A category band that requires any scroll to reach reads as airy and off-vertical for this shape; a real build verifies this against a rendered capture, not in prose. +- Whitespace is functional, not generous. The leaders in this shape are dense; an airy build reads as not-a-real-store. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be utilitarian, premium-utilitarian, or technical; not flowery or expressive. + +## 3. Merchandising and category surface + +**Conventions:** +- A category surface band sits **above the fold at a 1280x800 desktop viewport.** Eight to twelve category entry points is typical for a wide catalog; four to six for a focused one. ("First or second viewport" is too loose; a real build hit that and still read airy because the band slipped below the fold.) +- Depth signaling is one of: mega-menu hover (broad catalogs), grid of category cards on the home (narrow catalogs), faceted-search side rail on category pages. Pick one; do not stack. +- Category cards carry an icon, an image, or a tight text-only treatment. Hybrid icon-plus-text reads as catalog; image-only reads as marketing. +- Hierarchical surface (parent plus child categories) is conventional for broad catalogs. Flat surface fits focused catalogs. +- A **promotional or deal surface** lives near the top: a deal-of-the-week strip, a promo band, a featured-offer row. The field carries it to signal "this is an active store with offers." Its absence reads as brochure-like rather than storefront-like. The promo can be a single strip with one or two offers; it does not have to be a full module. +- An **inventory or catalog-depth signal** appears somewhere a first-time visitor will see it: a part count, "12,000+ parts in stock," a category-count figure, or a near-equivalent that establishes the catalog has real depth. The field carries it as a credibility move; its absence reads as a thin or demo catalog. The figure can be approximate, can be in the hero, the trust band, or the chrome. +- Featured / promoted collections appear below the category surface, not above; categories carry the navigation load. (The promotional surface above is distinct from featured collections; one is a deal band, the other is a curation grid.) + +## 4. Navigation and search paths + +**Paths the shape carries:** +- By category: primary. Always present. +- By search: primary. Always present, in the header. +- By brand or manufacturer: secondary to primary for broad catalogs (often a band in the chrome or a top-level page). +- By attribute (price, size, color, condition): primary on category pages via the faceted side rail. +- By vehicle / compatibility / fitment: primary for compatibility-led verticals; absent for undifferentiated catalogs. +- Newsletter, account, cart: chrome-level secondary affordances. + +**Build conventions:** +- Search input is in the header, not in a side panel. Visible width meaningful (not collapsed to an icon). +- Faceted filtering on the listing page is conventional; flat lists are off-vertical for broad catalogs. +- Sort options (price asc, price desc, name, relevance) are visible on the listing. +- Search and category browse coexist; one is not gated behind the other. + +## 5. Brand register and conviction + +**Typical postures:** utilitarian, premium-utilitarian, technical, value-led. Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; do not invent new register names here. + +**Build conventions (consistency, not register choice):** +- The register carries into the empty states, the cart, the demo modals, and the trust signals. A premium-utilitarian register that dissolves into generic copy below the fold is a composition failure. +- Voice consistency in headings, microcopy, CTAs, and empty states. +- Product imagery posture is consistent: studio product photography across listing and detail; lifestyle imagery in the hero or category headers, if used at all. + +## 6. Trust and conversion signals + +**Signals this shape carries:** +- Reviews / ratings: average plus count on listing cards and at the top of the detail page. If reviews are absent, surface an alternative (warranty, return policy, brand reputation). +- Pricing transparency: price visible on the listing card; total cost (price plus shipping plus tax) surfaced before checkout, not after. +- Stock signals: in stock, low stock, lead time, backorder. Surfaced on the listing and detail. +- Fitment / compatibility confirmation: required for fitment-led verticals. The confirmation badge ("confirmed to fit your {vehicle}") on the detail page is conventional. +- Shipping promises: free over $X, same-day, two-day. Surfaced in the chrome or hero. +- Return policy: linked from the cart and the detail page. The exact text is in `terms` or `returns`. +- Brand or store badges: certifications, "X years in business", authorized-dealer, where relevant. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real cart state, real fitment filtering), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment, no real account creation). + +## 7. Recurring vertical conventions (the synthesis) + +A credible ecommerce-catalog storefront, against the field of leaders, carries eleven conventions: + +1. A primary task that owns the hero (fitment, search, or category-grid; not a brand pitch). +2. **(Density-bearing)** A category surface band **above the fold at a 1280x800 desktop viewport**, not buried in a menu and not requiring scroll to reach. +3. Working faceted filtering on category pages. +4. A persistent global context indicator if the vertical is fitment-led (the confirmed vehicle, the selected compatibility, the active filter set). +5. Visible price on every listing card, with no "click to reveal". +6. Reviews or an explicit substitute (warranty, return policy) near the buying action. +7. A working cart with real client-side state across pages. +8. A clearly labeled checkout flow (real in production; honestly demo in showcase builds). +9. **(Density-bearing)** A promotional or deal surface near the top: a deal-of-the-week strip, a promo band, or a featured-offer row. +10. **(Density-bearing)** An inventory or catalog-depth signal a first-time visitor will see (a part count, an SKU total, a category count, or a near-equivalent). +11. **(Density-bearing, new)** Section count and merchandising volume at the field's level, not at a token-row level. A credible storefront carries roughly thirteen-plus distinct merchandising surfaces top-to-bottom on the home (desktop and mobile each, mobile typically taller), three SKU rails carrying twelve-plus product cards in total, a multi-card deals grid of four-to-eight distinct deal cards (not a single thin promo strip), a category grid of eight-plus photographic tiles, a four-to-six-cell services and trust band, twenty-five-plus distinct images on the home, and a five-to-seven-column footer. A build that hits conventions 2, 9, and 10 with one four-card rail and a five-tile category band passes the presence-check and still reads thin against the field; the bar is volume, not presence. + +**Threshold and density-bearing items.** A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 9, 10, and 11 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. A build can miss a nice-to-have (a strong substitute for reviews, for example) and still read as the vertical; missing any of the density-bearing four is the failure mode the auto-parts builds exposed across multiple iterations. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +**Why convention 11 needed to be added separately.** Before this entry, a build could carry the category band, the promo strip, and the inventory signal (conventions 2, 9, 10) and still read thin, because the prior conventions named *which* sections, never *how many* or *how full*. A category band with five tiles passed convention 2; a promo strip with one offer passed convention 9; a part-count badge passed convention 10. The build read storefront-correct on the checklist and read SaaS-airy in a rendered comparison against the field. Convention 11 closes that gap: the bar is the field's actual volume, observed top-to-bottom on a rendered home page, not a presence-check that any single token instance satisfies. + +--- + +## Capture-path note (audit infrastructure) + +The named field leaders in heavily-defended verticals (auto-parts is one) sit behind CDN/WAF bot-mitigation layers that block Fork A rendered capture even with realistic User-Agent strings. In a render-and-match attempt against the four leading parts retailers, all four were intercepted (Cloudflare, Akamai 403, DataDome interstitial, network-idle timeout) and Fork A returned zero homepage content. A synthesis pass on zero captured content silently falls back to training-knowledge abstraction, which is the exact failure mode this shape was added to defend against. + +**The lesson, recorded as audit-infrastructure guidance for this shape:** in bot-walled verticals, the realistic capture path is screenshot ingestion (a human takes desktop and mobile screenshots of each leader and drops them at a known path; the audit reads the PNGs with vision and produces the section-and-density target from observed evidence). Render-and-match through Fork A alone is not a reliable capture path for this shape. The audit script's selection of capture path should treat Fork A as the default and fall back to screenshot ingestion when zero or trivial content is returned; absent that fallback, the audit silently degrades to abstraction and the build it informs reads thin. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Fitment-first as the entire navigation pattern.** Most catalogs treat fitment as a sidebar widget. A build that makes fitment the primary, persistent, single-source-of-truth navigation owns the "wrong-fit return is impossible" position. +- **Pricing transparency to the dollar.** Most catalogs hide total cost until checkout. A build that surfaces shipping plus tax on the listing card owns the "no surprises" position. +- **Honest stock and lead-time signals.** Most catalogs use "low stock" theatrically. A build that names actual lead time owns the "we tell you when it ships, not what we want you to feel" position. +- **Real reviews vs review theater.** Most catalogs surface 4.7-star aggregates that no one trusts. A build that surfaces verified-buyer reviews with the bad ones visible owns the trust position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-ecommerce-standout.md b/skills/vertical-site-conventions/references/shape-ecommerce-standout.md new file mode 100644 index 0000000..d1d528d --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-ecommerce-standout.md @@ -0,0 +1,19 @@ +# Shape: ecommerce-standout + +Single-product or narrow-line ecommerce where the brand and the object carry the page. Premium boots, designer goods, single-product subscriptions, expressive consumer brands. The reader arrives because of the brand, not because of a category need. + +## Status + +Stub. Fill when the first ecommerce-standout demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** see the product (image-led), see the story (brand-led), buy. Hero often carries large product photography or a brand statement. +- **Layout register:** expressive or premium-considered. The opposite of a dense catalog; air and image carry the load. +- **Merchandising:** one product line, surfaced as a few SKUs or one product with options. The product story is the merchandising; spec lists are short. +- **Paths:** by SKU or by product secondary (the catalog is small); by story / about primary; press or recognition often surfaced; size / fit guides important. +- **Brand register:** expressive-maximalist or premium-considered. Cross-reference `creative-direction`; this shape is where strong register choices land. +- **Trust signals:** materials, where-made, founder story, press, reviews focused on quality and longevity, return policy generous and visible. +- **Synthesis (provisional):** large product photography in the hero, brand story or founding line surfaced early, size / fit / materials guide reachable, press logos if they exist, reviews emphasizing quality and longevity (not quantity), generous and clearly stated return policy. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-hospitality-experience.md b/skills/vertical-site-conventions/references/shape-hospitality-experience.md new file mode 100644 index 0000000..bdf348c --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-hospitality-experience.md @@ -0,0 +1,19 @@ +# Shape: hospitality-experience + +Tours, balloon rides, escape rooms, adventure outfitters, immersive experiences. The reader arrives wanting to understand what the experience is, see real photos, and book. + +## Status + +Stub. Fill when the first hospitality-experience demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** book a date and time. The hero CTA is "book" or "check availability"; secondary is "what to expect" for first-timers. +- **Layout register:** image-led, atmosphere-heavy. The hero is the experience itself, in photography or video. +- **Merchandising:** experiences as packages with dates, durations, and prices. What-to-expect content carries the trust load. +- **Paths:** by experience or package primary; by date / availability primary; private events or group secondary. +- **Brand register:** expressive, premium-considered, or warm-considered. Often regionally-anchored (place-led brand). +- **Trust signals:** what-to-expect, what-to-bring, age and accessibility constraints, cancellation policy, weather policy (for outdoor experiences), safety briefing, real customer photos, recent reviews on a trusted platform. +- **Synthesis (provisional):** book or check-availability in the hero, what-to-expect content surfaced before the booking choice, constraints (age, accessibility, weather) clearly stated, cancellation and weather policies visible, recent real photography and reviews, no stock imagery that does not match the actual experience. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-hospitality-food.md b/skills/vertical-site-conventions/references/shape-hospitality-food.md new file mode 100644 index 0000000..d1b76d1 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-hospitality-food.md @@ -0,0 +1,115 @@ +# Shape: hospitality-food + +Restaurants, cafés, bakeries, food halls, ghost kitchens with a storefront. The reader arrives wanting to know if they want to eat there: what the food is, what it costs, when the place is open, whether they can get a table. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (fine dining, neighborhood restaurant, café, bakery), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** see the menu. The reservation action is the secondary primary task. For walk-in-only restaurants and cafés, the menu and the hours-and-address pair are the primary tasks; for reservation-led restaurants, the menu and the reservation flow share the lead. + +**Build conventions:** +- The menu is reachable in one click from the home page. A site that buries the menu behind a PDF link, behind a modal, or below the fold without a clear cue is off-vertical. The menu is the page, not a download. +- The reservation action is the largest CTA in the chrome (after the menu link). For walk-in-only shops, the equivalent is "where we are" and "when we open." +- The reservation flow is on-site, not punted to a third-party widget iframe. A widget that breaks the site's visual contract dissolves the room's identity at the moment the visitor is closest to deciding. +- The site's primary task is the same component everywhere. One reservation modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +**Register:** image-led, atmospheric. Less dense than a catalog; more density than a marketing page; more atmosphere than a service-booking page. The page should feel like the room. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: an edge-to-edge dish or room photograph, the restaurant name and one-line identity, AND the reservation CTA. A hospitality-food hero without a real photograph reads as a marketing template. +- The hero photograph is a single subject (one dish, one corner of the room, one moment of service), not a collage. Tiled grids of every dish lose focus; stock food imagery loses identity; single-subject photography on a confident background is the convention. +- Whitespace is generous and atmospheric. The dish gets to breathe. Catalog-dense layouts are off-vertical for this shape unless the vertical is a fast-casual chain. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be editorial-restrained (fine dining), warm-neighborhood (everyday), industrial-bright (fast-casual), or playful-soft (bakery, café); not corporate-flat. + +## 3. The menu + +**Conventions:** +- A **menu page**, not a PDF, with each item carrying a name, a description, and a price visible per item. Hiding prices is off-vertical; it tells the visitor the shop is luxury-pretense rather than confidence. +- Items are grouped by course (starters, mains, sides, desserts, drinks). For tasting menus, the courses are the structure. For diner-style menus, the categories are functional. +- Item descriptions are written, not enumerated. Two or three short sentences per item. Adjective stacks ("savory, hearty, comforting") read as marketing; ingredient-and-method copy ("twenty-four-hour bone broth, brisket, eye round") reads as the kitchen. +- Signature dishes carry a small visible mark (badge, label) so the visitor knows what to order. Hiding the signature inside the list misses the assist. +- Allergen notes are surfaced (peanut, shellfish, gluten) where the kitchen's handling requires it. Generic "ask your server" copy is acceptable but less confident than naming the handling. + +## 4. Chef, provenance, and story + +**Conventions:** +- A short chef-perspective or chef-partner passage is conventional, on the home page or the about page. Two short paragraphs at most; first-person, ingredient-literate, no marketing register. +- Provenance content (where the ingredients come from, who farms what, who supplies the seafood) carries the hospitality wedge for restaurants whose positioning leans on it. For places where it does not, this is absent. +- Staff bios beyond the chef are absent in fine dining and present in neighborhood restaurants and cafés (named baristas, pastry chefs, line cooks). Match the register of the shop. +- The story is not a brand history; it is a kitchen perspective. Brands tell origin stories; restaurants tell what they care about. + +## 5. Reservations flow + +**Conventions:** +- The form asks: name, party size, date, time, email, allergies and notes. Nothing more at this stage; not an account, not a password, not marketing consent. +- Confirmation is honest. Real production: email confirmation within the hour, sometimes within minutes. Demo build: clearly labeled demo-only, no fake confirmation copy. +- Cancellation, late, and allergy policies are visible on the reservation page, not hidden in terms or buried in confirmation email. +- Walk-in policy is named openly if relevant ("walk-ins welcome at the bar", "no walk-ins"). +- Phone-as-fallback: a visible phone number for visitors who would rather call. Restaurant customers vary; the field's best builds carry both. + +## 6. Address, hours, and visit info + +**Conventions:** +- Address visible in the chrome on every page. Hours visible at minimum in the footer; the home page should carry "open tonight" or the day's hours above the fold. +- Hours that vary (brunch on Sundays, late on weekends, closed Mondays) are listed line-by-line, not summarized. +- Transit and parking notes belong on a Visit page; they are a trust signal for visitors planning to travel to the restaurant. +- Accessibility notes (step-free entrance, accessible restroom, dress code, noise level) are conventional on the Visit page and rare in the field; their presence reads as care. +- A live map embed is optional; a static "find us" image plus a deep link to the visitor's preferred map app works as well and avoids the embed's accessibility and performance overhead. + +## 7. Press, reviews, and aggregate trust + +**Conventions:** +- One named-publication pull-quote is the conventional press treatment, not a logo wall. A short, specific quote that names what the restaurant is good at carries more credibility than five logos. +- Aggregate ratings (Google, Yelp, Resy) are present in the chrome or near the reservation action, not in a logo grid. Numbers plus counts; not stars alone. +- Awards (Michelin, James Beard, regional press) are listed plain text in the chrome or on About, not in a badge wall. +- For demo or showcase builds, the functional-vs-demo line: a placeholder press quote is acceptable but should be labeled as such in the workup, not implied to be a real publication. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- The dish photograph itself, edge-to-edge, dramatic light, single subject. +- The chef's-perspective passage that does the work of branding. +- Plain-language menu descriptions with prices. +- Open cancellation, late, and allergy policies on the reservation page. +- Visible address and hours. +- Aggregate ratings near the reservation action. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo reservation modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible hospitality-food site, against the field of leaders, carries ten conventions: + +1. An edge-to-edge hero photograph of a single dish, room, or moment, above the fold at a 1280x800 desktop viewport. +2. **(Density-bearing)** A menu page, not a PDF, with name, description, and price visible per item, reachable in one click from the home. +3. Item descriptions in ingredient-and-method voice, not adjective stacks; signature dishes marked. +4. A reservation action that is on-site, not a third-party widget iframe, available from the chrome on every page. +5. **(Density-bearing)** A short chef-perspective or chef-partner passage, first-person, two short paragraphs at most. The story of the kitchen, not a brand history. +6. Address and hours visible above the fold; full hours line-by-line on the home or visit page. +7. JSON-LD Restaurant with hasMenu, servesCuisine, acceptsReservations, openingHoursSpecification, and aggregateRating. +8. Cancellation, late, and allergy policies stated openly on the reservation page. +9. **(Density-bearing)** One named-publication press pull-quote OR a visible aggregate rating (count plus number), placed near the reservation CTA. Not a logo wall. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +**Threshold and density-bearing items.** A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **1, 5, and 9 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a template instead of the room. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of conventions 1, 5, or 9 will make the build read as a marketing page about food rather than a restaurant. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **The menu is the page.** Most competitors hide the menu behind a PDF or a modal. A build that surfaces the menu in plain HTML with ingredient-literate descriptions owns the "we know what we cook" position. +- **On-site reservations.** Most competitors punt to a third-party reservation widget. A build that keeps the reservation flow visually within the site's identity owns the "the room is the experience" position. +- **Single-subject photography.** Most competitors either tile every dish or use stock food imagery. A build that leads with edge-to-edge single-subject photography on a confident background owns the "this is the dish" position. +- **Chef's-perspective voice.** Most competitors write in marketing register (adjective stacks, brand voice). A build that writes the menu in the chef's voice (ingredient, method, restraint) owns the "we are not selling you, we are cooking for you" position. +- **Provenance literacy.** Most competitors gesture vaguely at "local, seasonal." A build that names the farmer, the supplier, the cut, owns the "we know where the food came from" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-institution-mission.md b/skills/vertical-site-conventions/references/shape-institution-mission.md new file mode 100644 index 0000000..b5c9e03 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-institution-mission.md @@ -0,0 +1,19 @@ +# Shape: institution-mission + +Nonprofits, museums, foundations, public-interest organizations. The reader arrives wanting to understand what the institution does and decide whether to give, attend, volunteer, or read further. + +## Status + +Stub. Fill when the first institution-mission demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** depends on the moment. Donate during a campaign; visit / attend for an institution with a physical presence; sign up or read for a research or advocacy group. The hero CTA matches the institution's primary ask. +- **Layout register:** editorial-considered. More text than a catalog, less than a long-form publication. Trust load is heavy; expressive maximalism is rare in this shape. +- **Merchandising:** the cause or mission is the merchandising. Programs, impact, and recent work carry the page. +- **Paths:** by program primary; by impact / outcomes primary for established institutions; news / press / blog secondary; financials / 990 secondary but conventional for nonprofits. +- **Brand register:** institutional, considered, mission-led. Premium-considered for arts and culture; restrained-authoritative for advocacy. +- **Trust signals:** mission statement, board / leadership, financial transparency (for nonprofits, the 990 or audit), accreditations, named donors or partners, recent impact numbers with sources. +- **Synthesis (provisional):** mission statement above the fold, a clear primary ask (donate, attend, sign up), program or impact surface, leadership and governance reachable from the chrome, financial transparency linked (for nonprofits), no over-emotive imagery that reads as manipulative. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-inventory-listing.md b/skills/vertical-site-conventions/references/shape-inventory-listing.md new file mode 100644 index 0000000..ca1fa7f --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-inventory-listing.md @@ -0,0 +1,19 @@ +# Shape: inventory-listing + +Used-car lots, real estate, equipment rental, marketplace listings. The reader arrives wanting to filter a finite inventory down to the right item. + +## Status + +Stub. Fill when the first inventory-listing demo is built, or when a `competitor-experience-audit` for an inventory-listing vertical has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** filtered search with high-fidelity facets (price range, location, condition, year, make, model, beds, square feet). Search and faceted filtering are co-primary. +- **Layout register:** dense, but more grid-led than catalog-led. Each listing carries multiple attributes that need room to read. +- **Merchandising:** the listing is the merchandising. Hero carries a search-and-filter entry plus a few featured items. +- **Paths:** search-and-filter primary; saved-search and favorites secondary (account-gated); browse-by-attribute primary on category pages. +- **Brand register:** transactional, trust-led. Premium-led for high-ticket inventory (real estate, luxury cars). +- **Trust signals:** verified seller, listing freshness, photos count, condition reports, response time. +- **Synthesis (provisional):** persistent filter chip row, listing freshness indicators, photo count signal, save-this-listing affordance, contact-the-seller path. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-local-service-booking.md b/skills/vertical-site-conventions/references/shape-local-service-booking.md new file mode 100644 index 0000000..2628de6 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-local-service-booking.md @@ -0,0 +1,125 @@ +# Shape: local-service-booking + +Barber shops, salons, gyms, BJJ schools, dental practices, repair shops, dog groomers. The reader arrives wanting to book a time, see prices, or confirm the place exists. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (barbershops, dentists, repair shops), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +**Primary task:** book an appointment. For unbookable services (drop-in only), the primary task is to call or to confirm hours. The booking action is the largest CTA on the page; everything else competes for second place. + +**Build conventions:** +- The book-now action is in the chrome (persistent on every page) AND in the hero, not one or the other. +- A first-time visitor who arrived to book should reach a booking surface in one click from the home page. A flow that requires "services then pick then book" is one click too many. +- For services where the picked practitioner matters (barber, stylist, trainer, dentist), the booking action surfaces the practitioner choice before the time choice. For services where practitioner does not matter (oil change, dog wash), it does not. +- The booking action is the same component everywhere on the site so a visitor cannot get lost. One booking modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +**Register:** image-led-warm. Less dense than a catalog; more dense than a marketing page. The page should feel like a room the visitor wants to be in. + +**Build conventions:** +- **Above the fold at a 1280x800 desktop viewport**, the page carries: the booking CTA, an interior photograph of the space, AND a trust signal (years, license, review average, or named practitioners). A booking page without a photograph of the room reads as a third-party scheduler iframe, not a shop. +- A hero image of the space (or a close-up of the craft) is conventional and load-bearing. Stock or generic imagery reads as "any salon"; the shop's specific room reads as the shop. +- Whitespace is generous but purposeful. Editorial-airy is off-vertical; the visitor needs to see the menu and book without scrolling far. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be warm-classic, considered-premium, institutional-professional (medical, legal), or rugged-craft; not corporate-flat or marketing-flashy. + +## 3. Service menu and pricing + +**Conventions:** +- A **service menu with duration and price visible per item** lives above the fold at a 1280x800 desktop viewport, OR is one click from the home page and clearly signposted. Hiding prices behind a phone call is off-vertical for the field's modern bar; it tells the visitor the shop is friction-tolerant. +- Service descriptions are plain language, not marketing. Two sentences max per service. +- Service categories (haircut, shave, beard, package) are grouped, not flat-listed, for shops with more than five services. +- Packages (cut-and-shave, cut-and-color) are surfaced as their own line items with their own price, not as "add $X to the base service". +- For services where duration varies (skin fade vs classic cut), the longer duration is named honestly; the shop blocks the chair for the time the cut takes. + +## 4. Trust block and identity + +**Signals this shape carries above the fold:** +- Years in business ("Est. 2014", "11 years on Walnut Street"). +- License or certification, where the vertical has one (master barber license, dental board, state cosmetology, ASE certification for repair shops). +- Review average plus count (not just the stars; the count is the credibility). +- Address visible, not buried in a footer-only treatment. +- Hours visible, not buried in a footer-only treatment. A visitor planning a drop-in needs to know if the shop is open right now. +- For practitioner-driven shops: the practitioners' names and faces. Anonymous "our team" copy reads as franchise; named, photographed practitioners read as shop. + +**Build conventions:** +- The trust block is **aggregated**, not scattered. Years in one footer line, reviews on a separate widget, hours on a separate page is the field's miss; pulling them into a single above-the-fold block is the field's lever. +- JSON-LD `LocalBusiness` (or the more specific subtype: `HairSalon`, `BarberShop`, `Dentist`, `AutoRepair`) carries address, hours, telephone, and aggregateRating in structured form. Most competitors ship none. + +## 5. Practitioner roster + +**Conventions for practitioner-driven shops (barber, stylist, trainer, dentist):** +- A **roster with faces** above the booking CTA is the conversion lever the field leaves on the table. Most competitors gate the practitioner choice inside the booking flow; surfacing it before the booking choice removes a decision point. +- Each practitioner card carries: name, face, years of experience, specialties (one to three short tags). +- Bio length is one or two sentences, plain language. Long bios read as profile pages, not a roster. +- For non-practitioner-driven shops (drop-in repair, walk-in clinic), this section is absent or replaced by a "what makes this shop different" block. + +## 6. Booking flow specifics + +**Conventions:** +- The booking surface is a modal or a single-page form, not a multi-step wizard. Local-service appointments are not enterprise sales. +- The form asks: name, service, practitioner (if applicable), preferred date, preferred time window, notes. It does not ask for an account, a password, or marketing consent at this stage. +- Confirmation is honest. Real production: SMS or email within the hour. Demo build: clearly labeled demo-only, no fake confirmation copy ("you're booked!" with no booking). +- Cancellation policy, late policy, and payment policy are visible on the booking page, not hidden in terms. +- Phone-as-fallback: a visible phone number for visitors who would rather call. Local-service customers vary in digital comfort; the field's best builds carry both. + +## 7. Navigation paths + +**Paths the shape carries:** +- Services (menu, prices, durations): primary. +- Book: primary, persistent. +- Visit (address, hours, directions, parking, accessibility): primary. +- About / story / team: secondary. +- Newsletter, account, cart: absent or chrome-level afterthought. Local-service shops are not subscription products. + +**Build conventions:** +- Hours and address are in the chrome (footer at minimum) on every page. +- Accessibility info (step-free entrance, adjustable chairs, accessible restroom, quieter hours) sits on the Visit page; competitors rarely carry it and it is a real differentiator. + +## 8. Trust and conversion signals + +**Signals this shape carries:** +- Reviews / ratings: average plus count, surfaced above the fold. A four-and-up rating without a count reads as theater. +- Years in business: visible in the chrome or hero. Local shops earn trust over time and the field rewards saying so. +- License or certification number: visible, on the Visit or About page if not in the chrome. +- Plain-language service descriptions: no upcharge surprises. +- Cancellation and late policies stated openly. Generous grace windows read as confident; harsh ones read as defensive. +- Quieter hours / accessibility / language spoken: trust signals the field rarely carries; presence reads as care. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo booking modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible local-service-booking site, against the field of leaders, carries ten conventions: + +1. A book-now action that owns the hero and persists in the chrome on every page. +2. **(Density-bearing)** An interior or craft photograph of the **specific** shop above the fold at a 1280x800 desktop viewport, not stock or generic. +3. A service menu with duration and price visible per item, one click from the home page at most. +4. **(Density-bearing)** A trust block aggregated above the fold: years in business, license or certification, review average plus count. Not scattered across footer and about page. +5. For practitioner-driven shops: a roster with faces and specialties above the booking CTA. +6. Address and hours in the chrome (footer at minimum) on every page. +7. JSON-LD LocalBusiness (or vertical-specific subtype) with address, hours, telephone, and aggregateRating. +8. A booking flow that is a single-page form or modal, not a multi-step wizard; asks for name, service, time, and nothing more at this stage. +9. **(Density-bearing)** A cancellation, late, and payment policy stated openly on the booking page, not hidden in terms. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +**Threshold and density-bearing items.** A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions **2, 4, and 9 are the density-bearing ones**, the items whose absence makes a checklist-passing build still read as a third-party scheduler iframe or a franchise template instead of a specific shop with a specific room. A build can miss a nice-to-have (the practitioner roster for a drop-in shop, for example) and still read as the vertical; missing any of conventions 2, 4, or 9 makes the build read as anyone's shop. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- **Booking-first composition.** Most competitors bury the booking action below the fold or behind a third-party scheduler iframe that breaks the visual contract. A build that makes the booking action the largest element on every page, with the shop's identity intact, owns the "we want you to book" position. +- **Roster-before-booking.** Most competitors gate the practitioner choice inside the booking flow. A build that surfaces a small, photographed roster above the booking CTA owns the "you pick the chair, then the time" position. +- **Honest service menu.** Most competitors hide prices behind a phone call or list services without durations. A build that posts duration and price for every service owns the "no surprises" position. +- **Specific-room photography.** Most competitors use stock or generic salon imagery. A build that leads with the shop's actual room owns the "this is the place" position. +- **Aggregated trust above the fold.** Most competitors scatter the trust signals (years, license, reviews) across the chrome and about page. A build that pulls them into a single above-the-fold block owns the "we are real, we are local, we are licensed" position before the visitor scrolls. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-subscription-app.md b/skills/vertical-site-conventions/references/shape-subscription-app.md new file mode 100644 index 0000000..2e3919a --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-subscription-app.md @@ -0,0 +1,19 @@ +# Shape: subscription-app + +Weather apps, productivity tools, news readers, fitness trackers, language learning. The reader arrives wanting to understand the app and decide whether to install or subscribe. + +## Status + +Stub. Fill when the first subscription-app demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- **Primary task:** install (App Store / Play Store buttons) or start trial. The download or trial CTA is the hero. +- **Layout register:** marketing-led with strong product imagery (device frames, screen captures). Editorial-airy is common. +- **Merchandising:** features as a vertical scroll of capability sections; not a catalog grid. +- **Paths:** by feature primary (scroll); pricing secondary (navigable but not first); blog / support tertiary. +- **Brand register:** wide range. Consumer apps lean expressive or playful; productivity leans considered or technical. +- **Trust signals:** App Store rating, install count, press logos, customer testimonials, screenshots that read as the actual product. +- **Synthesis (provisional):** install CTAs (real store buttons) in the hero and chrome, feature-by-feature scroll with real product imagery, pricing surfaced clearly with the free / paid line drawn, App Store rating and review count surfaced, no fake screenshots. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/tools/check_workflow_drift.py b/tools/check_workflow_drift.py new file mode 100644 index 0000000..3d1d366 --- /dev/null +++ b/tools/check_workflow_drift.py @@ -0,0 +1,84 @@ +#!/usr/bin/env python3 +"""Drift check: every skill slug a workflow binds must exist in SKILLS.lock. + +The authoring contract binds skills by SLUG on each phase's `Skills:` line +(the Run block then invokes those same slugs in prose). This check reads those +lines, extracts the bound slugs, and asserts each is a real skill in +SKILLS.lock. It is the operate-time twin of the catalog's authoring-time +verification: a workflow that names a skill the catalog does not have would +silently fail to run, so the reference is caught here instead. + +Two bare words appear on `Skills:` lines as authoring markers rather than +slugs: `none` (a phase that is deliberately a human judgment stop) and +`routing` (a phase that routes to other workflows). They are listed explicitly +so a genuine typo is still caught rather than waved through. + +Usage: + python tools/check_workflow_drift.py # exit 1 on any unknown slug +""" +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +WORKFLOWS_DIR = ROOT / "workflows" +LOCK_PATH = ROOT / "SKILLS.lock" + +SKILLS_LINE = re.compile(r"^Skills:\s*(.*)$", re.MULTILINE) +SLUG_SHAPE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$") + +# Bare words used on Skills: lines as authoring markers, not skill slugs. +NON_SKILL_MARKERS = {"none", "routing"} + + +def bound_slugs(text: str): + """Yield the skill slugs a workflow file binds on its Skills: lines.""" + for m in SKILLS_LINE.finditer(text): + value = m.group(1) + # The slug list ends at the first parenthetical note or semicolon. + for cut in ("(", ";"): + idx = value.find(cut) + if idx != -1: + value = value[:idx] + for token in value.split(","): + token = token.strip() + if not token or " " in token: + continue + yield token + + +def main() -> int: + if not LOCK_PATH.exists(): + print("SKILLS.lock is missing; cannot run the drift check.") + return 1 + known = set(json.loads(LOCK_PATH.read_text(encoding="utf-8")).keys()) + + checked = set() + unknown = [] + for path in sorted(WORKFLOWS_DIR.glob("*.md")): + text = path.read_text(encoding="utf-8") + for token in bound_slugs(text): + if token in NON_SKILL_MARKERS: + continue + if not SLUG_SHAPE.match(token): + unknown.append((path.name, token, "not slug-shaped")) + continue + checked.add(token) + if token not in known: + unknown.append((path.name, token, "not in SKILLS.lock")) + + print(f"Checked {len(checked)} distinct slugs against SKILLS.lock:") + for slug in sorted(checked): + print(f" {slug}") + if unknown: + print("\nDRIFT:") + for name, token, why in unknown: + print(f" {name}: '{token}' {why}") + return 1 + print("\nNo drift: every bound slug exists in SKILLS.lock.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/gen_skills_lock.py b/tools/gen_skills_lock.py new file mode 100644 index 0000000..543198e --- /dev/null +++ b/tools/gen_skills_lock.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Generate or verify SKILLS.lock, a checksum manifest of every skill file. + +Usage: + python tools/gen_skills_lock.py # write SKILLS.lock + python tools/gen_skills_lock.py --check # verify, exit 1 on drift +""" +import hashlib +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +SKILLS_DIR = ROOT / "skills" +LOCK_PATH = ROOT / "SKILLS.lock" + + +def sha256(path: Path) -> str: + h = hashlib.sha256() + h.update(path.read_bytes()) + return h.hexdigest() + + +def build_manifest() -> dict: + manifest = {} + for skill_dir in sorted(p for p in SKILLS_DIR.iterdir() if p.is_dir()): + files = {} + for f in sorted(skill_dir.rglob("*")): + if f.is_file(): + rel = f.relative_to(skill_dir).as_posix() + files[rel] = sha256(f) + manifest[skill_dir.name] = files + return manifest + + +def main() -> int: + manifest = build_manifest() + serialized = json.dumps(manifest, indent=2, sort_keys=True) + "\n" + if "--check" in sys.argv: + if not LOCK_PATH.exists(): + print("SKILLS.lock is missing. Run tools/gen_skills_lock.py.") + return 1 + if LOCK_PATH.read_text() != serialized: + print("SKILLS.lock is out of date. Regenerate and commit it.") + return 1 + print("SKILLS.lock is current.") + return 0 + LOCK_PATH.write_text(serialized) + print(f"Wrote SKILLS.lock with {len(manifest)} skills.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/gen_workflows_lock.py b/tools/gen_workflows_lock.py new file mode 100644 index 0000000..122cb20 --- /dev/null +++ b/tools/gen_workflows_lock.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Generate or verify WORKFLOWS.lock, the canonical manifest of workflow files. + +A workflow file is any Markdown file in workflows/ whose opening fenced block +declares both a slug and a status. The tier docs (README.md, CONNECTORS.md, +AGREEMENT-LOG.md) have no such block and are skipped. WORKFLOWS.lock is the +count source for the tier; no count is hand-typed anywhere. + +Usage: + python tools/gen_workflows_lock.py # write WORKFLOWS.lock + python tools/gen_workflows_lock.py --check # verify, exit 1 on drift +""" +import hashlib +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +WORKFLOWS_DIR = ROOT / "workflows" +LOCK_PATH = ROOT / "WORKFLOWS.lock" + +FENCE = re.compile(r"```(.*?)```", re.DOTALL) +SLUG = re.compile(r"^slug:\s*(\S+)\s*$", re.MULTILINE) +STATUS = re.compile(r"^status:\s*(\S+)\s*$", re.MULTILINE) + + +def sha256(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def parse_workflow(path: Path): + """Return (slug, status) if the file is a workflow, else None.""" + text = path.read_text(encoding="utf-8") + fence = FENCE.search(text) + if not fence: + return None + block = fence.group(1) + slug = SLUG.search(block) + status = STATUS.search(block) + if not slug or not status: + return None + return slug.group(1), status.group(1) + + +def build_manifest() -> dict: + manifest = {} + for path in sorted(WORKFLOWS_DIR.glob("*.md")): + parsed = parse_workflow(path) + if parsed is None: + continue + slug, status = parsed + if slug != path.stem: + raise SystemExit( + f"{path.name}: declared slug '{slug}' does not match filename stem " + f"'{path.stem}'. Fix one so the manifest key is unambiguous." + ) + manifest[slug] = { + "file": path.name, + "sha256": sha256(path.read_bytes()), + "status": status, + } + return manifest + + +def main() -> int: + manifest = build_manifest() + serialized = json.dumps(manifest, indent=2, sort_keys=True) + "\n" + # Compare and write as bytes with LF newlines so the lock is byte-stable + # across platforms; text mode on Windows would emit CRLF and break --check + # on a Linux runner. + payload = serialized.encode("utf-8") + if "--check" in sys.argv: + if not LOCK_PATH.exists(): + print("WORKFLOWS.lock is missing. Run tools/gen_workflows_lock.py.") + return 1 + if LOCK_PATH.read_bytes() != payload: + print("WORKFLOWS.lock is out of date. Regenerate and commit it.") + return 1 + print(f"WORKFLOWS.lock is current ({len(manifest)} workflows).") + return 0 + LOCK_PATH.write_bytes(payload) + print(f"Wrote WORKFLOWS.lock with {len(manifest)} workflows.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/scan_skills.py b/tools/scan_skills.py new file mode 100644 index 0000000..c3f3d3d --- /dev/null +++ b/tools/scan_skills.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +"""Heuristic safety scan for skill files. Flags known-risky patterns. + +Usage: + python tools/scan_skills.py [path ...] # scans given files, or all skills + +Prints findings. Exit code is always 0; this is advisory, not a gate. +Promote to a blocking check only after baselining against the full catalog. +""" +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +SKILLS_DIR = ROOT / "skills" +SCRIPT_SUFFIXES = {".py", ".js", ".ts", ".mjs", ".cjs", ".sh", ".bash"} + +SCRIPT_RULES = [ + ("HIGH", "shell or subprocess execution", + re.compile(r"\b(subprocess|os\.system|child_process|spawn|popen)\b|" + r"\b(bash|sh)\s+-c\b")), + ("HIGH", "dynamic code execution", re.compile(r"\b(eval|exec)\s*\(")), + ("HIGH", "environment or secret access", + re.compile(r"os\.environ|process\.env|getenv|id_rsa|" + r"\.aws/credentials|ANTHROPIC_API_KEY")), + ("HIGH", "network egress", + re.compile(r"\b(curl|wget)\b|requests\.|urllib|httpx|fetch\(|axios|" + r"socket\.")), +] +MARKDOWN_RULES = [ + ("MEDIUM", "instruction override / injection phrasing", + re.compile(r"ignore (the |all )?(previous|prior|above)|" + r"disregard (the |your )?(instructions|system)|exfiltrat", + re.IGNORECASE)), + ("MEDIUM", "references agent memory or config files", + re.compile(r"\b(MEMORY\.md|SOUL\.md|CLAUDE\.md)\b|~/\.claude|" + r"\.claude/settings", re.IGNORECASE)), + ("LOW", "instructs running shell on activation", + re.compile(r"run (this )?(command|script|shell)|execute the following", + re.IGNORECASE)), +] + + +def targets(args): + if args: + return [Path(a) for a in args if Path(a).is_file()] + return [p for p in SKILLS_DIR.rglob("*") if p.is_file()] + + +def scan_file(path): + findings = [] + try: + text = path.read_text(errors="ignore") + except OSError: + return findings + rules = SCRIPT_RULES if path.suffix in SCRIPT_SUFFIXES else MARKDOWN_RULES + for severity, label, pattern in rules: + for m in pattern.finditer(text): + line = text[: m.start()].count("\n") + 1 + findings.append((severity, label, str(path), line)) + return findings + + +def main(): + all_findings = [] + for path in targets(sys.argv[1:]): + all_findings.extend(scan_file(path)) + if not all_findings: + print("No findings.") + return 0 + for severity, label, path, line in sorted(all_findings): + print(f"[{severity}] {path}:{line} {label}") + print(f"\n{len(all_findings)} finding(s). Advisory only. Review in context.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/workflows/AGREEMENT-LOG.md b/workflows/AGREEMENT-LOG.md new file mode 100644 index 0000000..6c97420 --- /dev/null +++ b/workflows/AGREEMENT-LOG.md @@ -0,0 +1,82 @@ +# Agreement log: the schema spec + +The agreement log records what an engine proposed, what its guardrail said, what a human decided, and whether the two agreed. It is the substrate the autonomy doctrine reads: agreement rates per lane earn a gate class its auto-pass, and post-merge regressions revoke it. Autonomy Review reads this log; Incident Response and Lane Demotion reads its `post_merge_outcome`; nothing else mutates it. + +This file is the public schema, generalized from the krine agreement-rate table (migration 0007). The schema is what you get. The instance, its write path, the designation allowlist, and every promotion decision are operated, not published. A reader who implements this schema gets their own log; they do not get ours. + +The agreement log has no connector class, by design. It is operated substrate, not a connectable capability (see CONNECTORS.md). Workflow files that touch it split their done-when conditions into a public gate and an operated-log note, so a stranger running the workflow never depends on infrastructure that is not published. + +## Reference schema (migration 0007, quoted with types) + +The canonical source is the krine agreement-rate migration. Its columns and types, quoted as the reference: + +```sql +create type human_verdict_kind as enum ('merge', 'reject', 'revise'); +create type agreement_kind as enum ('true_pass', 'false_pass', 'true_fail', 'false_fail'); + +create table agreements ( + id uuid primary key default gen_random_uuid(), + project_id uuid references projects(id) on delete cascade, + decision_id text not null, + pr_id text, + lane text not null, + risk_tier text not null, + agent_id text not null, + guardrail_verdict text not null, -- pass or fail + guardrail_confidence numeric, -- graded score; null for deterministic checks + guardrail_checks jsonb, -- which checks fired and their results, plus the proposal pointer + human_verdict human_verdict_kind, -- merge | reject | revise; filled after human review + human_reason text, -- the rationale; filled after human review + proposal_to_merge_diff jsonb, -- the proposal-to-merge diff or a pointer; filled after merge + human_review_latency numeric, -- seconds from PR open to human verdict + agreement agreement_kind, -- authored after human review + post_merge_outcome text, -- null at merge, filled later by continuous verification + created_at timestamptz not null default now() +); +``` + +## The public spec + +The public schema carries the fields a reader implementing this tier needs. It converges with the reference above rather than restating it from memory. + +Retained from 0007 as-is: + +| Field | Type | Meaning | +|---|---|---| +| agreement | enum: true_pass, false_pass, true_fail, false_fail | the four-way agreement value, authored (see below), never derived from the verdict pair | +| lane | text, not null | the autonomy lane, e.g. content_roadmap. Per-lane agreement rates are the unit the promotion thresholds apply to; without lane, false-pass-among-passes cannot be computed per lane | +| risk_tier | text | the risk classification; per-tier thresholds govern promotion, and Tier 3 is permanently excluded | +| guardrail_confidence | numeric, nullable | the graded score; null for purely deterministic checks. The confidence-cutoff promotion for graded lanes is impossible without it | +| guardrail_checks | jsonb | which checks fired and their results, and the pointer to the proposal | +| human_verdict | enum: merge, reject, revise (+ waive, added below) | what happened to the work; a separate axis from agreement, and neither maps from the other | +| human_reason | text | the rationale, filled after human review; required on revise and waive in this tier | +| proposal_to_merge_diff | jsonb | the proposal-to-merge diff or a pointer to it; the primary correction signal, and the cold-start recovery reads merged-versus-rejected diffs | +| post_merge_outcome | text | null at merge, filled later by continuous verification; the second ground truth that demotion and the hardened rung read | + +Added for this tier: + +| Field | Type | Meaning | +|---|---|---| +| property | text, designation-guarded | the showcase property the row belongs to; the publish path enforces the allowlist against it | +| workflow_slug | text | which workflow produced the proposal | +| phase | text | which phase of that workflow | +| artifact_ref | text | pointer to the held artifact the row is about | +| waive | value on human_verdict | a fourth human verdict alongside merge, reject, revise | + +## Agreement is authored, never derived + +Agreement is AUTHORED by the human who saw the diff, never derived from the verdict pair. A guardrail pass that a human overrides to revise is a false_pass, and no naive rule produces that mapping; the human writes it. The verdict axis (what happened to the work) and the agreement axis (whether the guardrail was right) are independent, and neither is computed from the other. + +Waive rows carry an authored agreement value plus a required `human_reason`, are excluded from false-pass and false-fail rate computations, and report as their own line in Autonomy Review. Waives stay visible without contaminating the promotion thresholds: a gate waived because it was too strict, and a risk waived because it was knowingly accepted, are both recorded and both kept out of the rates that earn a lane its autonomy. + +## The designation guard + +The publish path refuses any public row whose `property` is not on the maintained showcase allowlist. The guard sits at the write boundary, not only in authoring convention: a row for a non-designated property can never become public output, and its property name can never appear in published material. The allowlist is data, maintained in one place, not a per-row judgment. + +## Open versus operated + +The schema is public. The instance, the write path, the allowlist, and every promotion decision are operated. A reader who implements this schema gets their own log; they do not get ours. Forking the repo yields the gates and this spec, and a reader's own log if they build one; it does not yield RampStack's rows. + +## Storage + +One append-only table in an operational Postgres store. Autonomy Review reads it, Incident Response and Lane Demotion reads `post_merge_outcome`, and nothing else mutates it. Do not add a second table until there is a second writer. diff --git a/workflows/CONNECTORS.md b/workflows/CONNECTORS.md new file mode 100644 index 0000000..b035b50 --- /dev/null +++ b/workflows/CONNECTORS.md @@ -0,0 +1,23 @@ +# Connector capability classes + +Workflows in this tier declare the data access they need as capability CLASSES, never vendors. Your MCP server or integration binds the class; the workflow stays valid when your stack changes. + +Rules, in force across every workflow: +- Read-only is the default. The only write mode is write-held: the action creates a draft or a held change that a human promotes. Publishing, merging, and platform actions are never agent actions under template status. +- Every warehouse capability carries mandatory query bounds: a date range pushed down as a partition filter on every call. A call without bounds is rejected, not silently run. +- Credentials live in environment, never in workflow files, tool output, or error messages. + +| Class | Access | What it serves | Binding today | +|---|---|---|---| +| warehouse.query | read | the metric warehouse all tracks read | managed warehouse MCP servers exist for the major warehouses; a thin domain layer encoding your query-correctness rules remains yours to build | +| search-performance.read | read | search console class data | the bulk export lands this in the warehouse natively; direct-API access is a thin layer to build | +| analytics.read | read | product/web analytics events | an official analytics MCP exists for the common stack; native warehouse export is the reference path | +| cms.draft | write-held | content pipeline drafts | your CMS's draft state via its API; no universal server, a small adapter | +| repo.change | write-held | code and config changes as held draft PRs | native to the code host | +| crawl.read | read | live-page fetches for verification gates | plain HTTPS; no server needed | +| experiment.read | read | experiment results and assignments | per-vendor adapter | +| revenue.read | read | commerce/affiliate revenue events, reconciled against the warehouse | per-platform adapter | + +Deliberate absences: there is no index-submit class and no analytics-config-write class. Submitting sitemaps, requesting indexing, and changing analytics settings are state-changing human actions. + +The agreement log has NO connector class, deliberately. It is operated substrate, not a connectable capability: the schema is public (AGREEMENT-LOG.md), the instance and its write path are not. Workflow files that touch it carry a public-gate versus operated-log split in their done-when conditions. diff --git a/workflows/GETTING-STARTED.md b/workflows/GETTING-STARTED.md new file mode 100644 index 0000000..f712dae --- /dev/null +++ b/workflows/GETTING-STARTED.md @@ -0,0 +1,12 @@ +# Running a workflow + +Each workflow in this directory is a runnable procedure, not an essay. The shape is identical across all of them: + +1. Install the catalog once: /plugin marketplace add rampstackco/claude-skills +2. Open the workflow file. Check "when to use / when not to use" first; half the value of the tier is the routing between workflows. +3. Work the prerequisites checklist. If it names a data export, enable it before anything else; the exports named here do not backfill. +4. Run the phases in order. Each phase names the skills it invokes, the input it consumes, a Run block you copy and adapt, the output artifact it produces, and a binary done-when. Phases marked as declared gaps carry their procedure inline; the capability-class line tells you what to substitute if you are off-catalog. +5. Respect the lanes. Divergent phases end at a human decision. Gate phases report and never fix. Nothing in any workflow publishes, merges, or changes platform state on its own. +6. Record what happened. The minimum record is the per-phase artifacts and the human's merge note. The full schema, if you want to implement the operated version, is AGREEMENT-LOG.md. + +Statuses are honest and defined in the README: everything starts as a template, and a workflow is validated only when it has been executed as written on a real property with a linked run record. You can watch that happen in this repo's history. diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 0000000..505f48d --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,67 @@ +# Forward-deployed workflows + +Operating workflows for forward-deployed roles running the engines inside a real company's pipeline and data stack. The skills catalog covers building a site once; this tier covers operating a deployed content and growth pipeline continuously. Same authoring contract, extended with role, status, connectors, and autonomy. + +New here? Start with GETTING-STARTED.md. + +Install the catalog these workflows invoke: + +``` +/plugin marketplace add rampstackco/claude-skills +``` + +## Tracks + +Three tracks run the pipeline, and a cross-track pair spans them: + +- Forward-deployed engineer (FDE): stands the pipeline up and keeps its data and deploys honest. +- Forward-deployed marketer (FDM): runs the content and experimentation loop through prove gates. +- Forward-deployed analyst (FDA): owns the numbers, the attribution, and the diagnosis loops. +- Cross-track: Incident Response and Lane Demotion, and Autonomy Review. These operate over every track, one on the event of a regression and one on a periodic cadence. + +## The status ladder + +The ladder is this tier's spine. A workflow's status says what has actually happened to it, not how good the document reads. + +- template: designed, not executed as written. +- validated: executed as written, by the engines, on a showcase-designated property, with a PUBLIC linked run record; manual runs the workflow merely describes do not count. +- hardened: validated plus failure modes documented from real incidents; explicitly the home of demotion and post_merge_outcome regression data, so hardened is earned by surviving events, not by prose. + +Every shipped file below enters at template. Content Pipeline with Prove Gates is the first to flip: Run 1 executed it end to end on a designated property, so its status is validated with the run record linked, the evidence landing before the claim. + +## The merge doctrine + +Checks report and fail, engines propose and stop, a human merges; autonomy is earned per lane under the published doctrine, never asserted. + +## The set + +WORKFLOWS.lock is the canonical manifest and the source for any count. The table is the list. Shipped files link, and with this wave every file is shipped, so no row remains defined and publishing. + +| Workflow | Track | Status | +|---|---|---| +| [Post-Deploy Live Verification](post-deploy-live-verification.md) | FDE | template | +| [Data Surface Integrity](data-surface-integrity.md) | FDE | template | +| [Migration with Verification](migration-with-verification.md) | FDE | template | +| [CI Prove-Gate Wiring](ci-prove-gate-wiring.md) | FDE | template | +| [Warehouse Data Plane Standup](warehouse-data-plane-standup.md) | FDE | template | +| [Content Pipeline with Prove Gates](content-pipeline-prove-gates.md) | FDM | validated | +| [Corpus Integrity and Correction](corpus-integrity-and-correction.md) | FDM | template | +| [Link Graph and Metadata Parity Audit](link-graph-and-metadata-parity-audit.md) | FDM | template | +| [Regulated-Content Compliance Gate](regulated-content-compliance-gate.md) | FDM | template | +| [Experiment Loop with Pre-Registered Gates](experiment-loop-with-pre-registered-gates.md) | FDM | template | +| [Traffic-Drop Triage](traffic-drop-triage.md) | FDA | template | +| [Conversion-by-Source Diagnosis](conversion-by-source-diagnosis.md) | FDA | template | +| [Revenue Tracking Integrity](revenue-tracking-integrity.md) | FDA | template | +| [Incident Response and Lane Demotion](incident-response-and-lane-demotion.md) | cross | template | +| [Autonomy Review](autonomy-review.md) | cross | template | + +## Roadmap: named, not launched + +- AI-Surface Visibility Baseline (FDM): fails connector readiness honestly; ships when citation-measurement has real runs. +- Attribution and Outcome Reporting (FDA): fails honest usability at template status; ships when the agreement log has real cross-property rows and post_merge_outcome data. +- Forward-deployed product manager track (FDPM): named to hold the track; not launched, and carried with the same visible not-launched treatment so it cannot read as an empty shipped track. + +## The docs in this tier + +- CONNECTORS.md: the capability classes every workflow declares, the deliberate absences, and the operated-substrate boundary. +- AGREEMENT-LOG.md: the public schema for the agreement log the operated deployment writes, generalized from the canonical agreement-rate table. diff --git a/workflows/autonomy-review.md b/workflows/autonomy-review.md new file mode 100644 index 0000000..3c0ab68 --- /dev/null +++ b/workflows/autonomy-review.md @@ -0,0 +1,156 @@ +# Autonomy Review + +``` +name: Autonomy Review +slug: autonomy-review +tier: forward-deployed (operations) +role: cross +status: template +score: 43 (demand 3, pain 4, differentiation 5, usability 4, connectors 4) +intent: the periodic ceremony over the agreement log: per-lane agreement rates, + which gate classes have earned auto-pass under the tier's thresholds, and + which divergences mean a rubric constant needs tuning +when to use: on a cadence or at a row threshold, once the agreement log holds enough + rows per lane to evaluate +when not to use: executing a revocation when a promoted lane regresses (Incident Response + and Lane Demotion); defining the schema (AGREEMENT-LOG.md is the spec, + this file is its consumer) +gap note: the agreement-log math is RampStack's and has no catalog skill by design; + every analytic phase is inline procedure with no nearest-miss anchor. It + is written to run against any log that implements AGREEMENT-LOG.md. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter # only if an outcome join is needed + - capability: repo.change + access: write-held # only Phase 5's rubric-tuning follow-ups +``` + +The agreement log has no connector class, deliberately. It is operated substrate, not a connectable capability (see CONNECTORS.md): the schema is public (AGREEMENT-LOG.md), the instance and its write path are not. This ceremony reads the operated log and proposes; it never gains a write path to the log, and the promotion it licenses is an operated decision, not a published capability. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- An agreement log implementing the AGREEMENT-LOG.md schema, with enough rows per lane to evaluate; the minimum sample below is a real gate, not a formality. +- The tier's per-lane thresholds and, for graded lanes, the `guardrail_confidence` cutoff, recorded and version-controlled. +- The published merge-authority doctrine (the three layers: access mode, gate auto-pass, merge authority), so a promotion proposal is measured against a written rule. + +## Phases + +### Phase 1: Assemble the window · lane: convergent (Tholo) + +Skills: none; the agreement-log math is a DECLARED GAP with no catalog anchor, procedure inline +Capability class: autonomy.window-assembly (declared catalog gap; no nearest-miss, the log math is RampStack's) +Input: the agreement log for the review window (a log implementing AGREEMENT-LOG.md) +Run: + + Read the agreement log for the window and group rows by lane. Per lane, + compute the four-way agreement rates over true_pass, false_pass, true_fail, + and false_fail, and the row count. Pull the waived rows (human_verdict = + waive) out first: they carry an authored agreement value plus a required + human_reason, are excluded from false-pass and false-fail rate computations, + and report as their own line. Agreement is the authored value on each row, + never derived from the verdict pair; read it, do not recompute it. Present the + per-lane window with the waived line kept separate from the rates, and + evaluate no promotion yet. + +Output artifact: the per-lane window (four-way agreement rates, row counts, the waived line reported separately) +Done when (public gate): every lane in the window has its four-way rates and row count, and waived rows are reported on their own line outside the rates +Operated-layer note: the window is read from the operated log instance; the schema and the four-way agreement values are public (AGREEMENT-LOG.md), and a reader runs this against their own log while RampStack's rows stay operated +Fails look like: folding waived rows into the rates. A waive is a recorded human override, not a guardrail miss, and counting it as a false_pass or false_fail poisons the exact number promotion depends on. + +### Phase 2: Threshold evaluation per lane · lane: gate (Basano) + +Skills: none; the promotion math is a DECLARED GAP with no catalog anchor, procedure inline +Capability class: autonomy.threshold-eval (declared catalog gap; no nearest-miss) +Input: the per-lane window; the tier's per-lane thresholds and the `guardrail_confidence` cutoff +Run: + + For each lane, evaluate three conditions against the written rule and report a + pass or fail on each, changing nothing. One: the false-pass-among-passes rate + is at or below the lane's tier threshold. Two: the lane's row count meets the + minimum sample, because a lane under sample is not evaluable and "insufficient + sample" is a verdict, not a delay. Three, for graded lanes only: the lane's + guardrail_confidence clears the confidence cutoff. A lane earns eligibility + for auto-pass only when every applicable condition holds. Report the per-lane + evaluation with the numbers; this gate reports and decides nothing. + +Output artifact: the per-lane eligibility evaluation (each condition, pass or fail, with the numbers) +Done when: every evaluable lane has a verdict on the threshold, the minimum sample, and (for graded lanes) the confidence cutoff, and under-sample lanes are marked not-evaluable +Fails look like: a ceremony on insufficient sample. A lane declared eligible on five rows has measured noise, and the promotion it licenses regresses on the first real week. + +### Phase 3: The ceiling · lane: gate (Basano) + +Skills: none; the ceiling is doctrine, procedure inline +Capability class: autonomy.ceiling-check (declared catalog gap; no nearest-miss) +Input: the per-lane eligibility evaluation +Run: + + Apply the ceiling before any proposal is written. Tier-3 judgment and boundary + gates (honesty and disclosure lines, the open-versus-operated boundary, + positioning, naming, and the meta-decision of when any lane graduates) are + PERMANENTLY ineligible: they never earn auto-pass and never earn merge + authority, at any status, on any sample. The ceremony that licenses a + graduation is itself a Tier-3 act, so it can never license its own class. + Strike every Tier-3 lane from the eligible set regardless of its rates, and + record that the strike is structural, not a close call. Report the eligible + set after the ceiling. + +Output artifact: the eligible set with every Tier-3 lane struck, and each strike recorded as permanent +Done when: no Tier-3 lane remains in the eligible set, and the graduation meta-decision is marked as itself Tier 3 and ineligible +Fails look like: a lane graduating the ceremony's own class. The moment the review licenses the authority that licenses reviews, the ceiling is gone and the ladder is a pricing page with extra steps. + +### Phase 4: Promotion, demotion, and tuning proposals · lane: divergent (human) + +Skills: none; the decision is deliberately human +Input: the eligible set after the ceiling; the divergences the window surfaced +Run: a person decides. For each eligible lane, the human decides whether to + promote it (grant gate auto-pass, or merge authority, per the doctrine's + layers) with the evidence attached; whether a lane's divergences mean a rubric + constant needs tuning rather than a promotion; and whether any lane should be + demoted. Promotion is licensed here and nowhere else, and it stays revocable. + The decision and its evidence are recorded. +Output artifact: the recorded decisions (promote, tune, demote, or hold) per lane, with evidence +Done when: every eligible lane has a recorded human decision with its evidence, or is explicitly held for more sample +Operated-layer note: in an operated deployment each decision is a Tier-3 act recorded against the lane in the agreement log; the licensing, the log instance, and the promotion are operated, and a reader running this against their own log makes their own decisions (AGREEMENT-LOG.md, open versus operated) +Fails look like: the ceremony drifting into a rubber stamp. If every review promotes and none tunes or demotes, the ceremony has stopped reviewing, and its own agreement rate, its proposals against what the evidence supported, is the number that catches it. + +### Phase 5: Rubric-tuning follow-ups · lane: convergent (Tholo) + +Skills: none; rubric constants are config, the change is procedure inline +Capability class: rubric.tune (write-held) +Input: the tuning decisions from Phase 4 +Run: + + For each tuning decision, prepare the rubric-constant change as a held change + (repo.change): the constant, its old and new value, and the divergence + evidence that motivated it. Nothing auto-applies; a human merges the tuning + the way any other held change is merged. Record the follow-up against the lane + so the next window can tell whether the tuning moved the agreement rate. + +Output artifact: held rubric-tuning changes, each tied to its lane and its motivating divergence +Done when: every Phase 4 tuning decision is a held change with its evidence, and nothing has auto-applied +Fails look like: tuning a constant to make a lane pass. A threshold moved to promote a lane it was blocking is the promotion wearing a disguise, and the divergence evidence is what keeps the tuning honest. + +## Failure modes + +- Ceremonies on insufficient sample: a lane declared eligible on too few rows (Phase 2's failure); insufficient sample is a verdict, not a delay. +- Counting waives in the rates: a recorded human override contaminating the false-pass or false-fail computation (Phase 1's failure). +- The ceremony as rubber stamp: a review that only ever promotes, its own agreement rate reviewable (Phase 4's failure). +- Promotion without the demotion counterpart wired: granting autonomy with no revocation path is the asymmetry the doctrine forbids; Incident Response and Lane Demotion must exist and be armed before any lane graduates. +- Licensing the ceiling's own class: a Tier-3 graduation (Phase 3's failure). +- Tuning to pass: moving a constant to promote a lane it was blocking (Phase 5's failure). + +## Worked example + +Pending. Populates when this ceremony is first run against the agreement log at a row threshold rather than a date; a small number of real rows exist today and the cadence adds more. Status flips to validated when that run record links here. + +## Boundaries + +- Incident Response and Lane Demotion executes the revocation this ceremony's promotions promise: it demotes a lane when a promoted lane's post_merge_outcome regresses, and no lane should graduate here until that counterpart is armed. +- AGREEMENT-LOG.md is the schema this ceremony consumes; that file is the spec and this workflow is its reader, and every column, verdict, and rule this file uses is defined there. diff --git a/workflows/ci-prove-gate-wiring.md b/workflows/ci-prove-gate-wiring.md new file mode 100644 index 0000000..7f9491f --- /dev/null +++ b/workflows/ci-prove-gate-wiring.md @@ -0,0 +1,162 @@ +# CI Prove-Gate Wiring + +``` +name: CI Prove-Gate Wiring +slug: ci-prove-gate-wiring +tier: forward-deployed (operations) +role: fde +status: template +score: 45 (demand 4, pain 4, differentiation 4, usability 4, connectors 5) +intent: install prove skills as required status checks so a failing verdict + blocks a merge the way a failing test does +when to use: a repo where prove checks exist but run advisory, and a merge can pass + without them +when not to use: pre-publish content-claim checking (that is Content Pipeline with Prove + Gates, Phase 3); verifying production after a merge (Post-Deploy Live + Verification); one-off local linting +gap note: the CI-inventory and gate-implementation cores are DECLARED CATALOG + GAPS; those phases are inline procedure with qa-testing and seo-technical + as the nearest anchors. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: repo.change + access: write-held # the wiring and every gate fix land as held PRs + - capability: crawl.read + access: read # only if a gate fetches built output to check it +``` + +Everything this workflow changes lands held: the gate wiring and any fix a gate surfaces are proposed as PRs a human merges. Making the checks required and enabling branch protection are platform actions a person performs (Phase 5). + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A repo with CI you can add status checks to, and the permission to make a check required. +- The prove checks you intend to gate on, already runnable against the repo by hand. +- A build command that produces the artifact production serves; a dev-flag build is a different artifact. +- Branch protection you can configure, or the access to request it. + +## Phases + +### Phase 1: Inventory the pipeline and the gate candidates · lane: convergent (Tholo) + +Skills: qa-testing (nearest anchor; the CI-inventory core is a DECLARED GAP, procedure inline) +Capability class: ci.inventory (declared catalog gap; nearest-miss qa-testing) +Input: the repo, its CI configuration, and the list of prove checks that could become gates +Run: + + Invoke qa-testing's checklist discipline against the current pipeline. + Enumerate: what CI runs today and on which events, which checks are advisory + versus blocking, and which prove checks are run by hand but not wired. For + each candidate gate record what it needs to run (a build artifact, a route + list, a data source) and whether it reads source or built output. Produce the + inventory; propose nothing yet. + +Output artifact: the gate-candidate inventory (each candidate, its inputs, source-versus-built, current advisory or blocking state) +Done when: every candidate has its inputs and current state recorded, including the checks that already block +Fails look like: inventorying the CI config and missing the by-hand checks. The gate a team runs manually and trusts is the one worth wiring, and it never appears in the YAML. + +### Phase 2: Define the gate set and the report contract · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the gate-candidate inventory +Run: + + Propose the gate set: which candidates become required checks, and for each, + the report contract every gate emits, one line per finding: file, check, + expected, found. The contract is report-only by construction, so a gate states + a pass or fail verdict with evidence and changes nothing. Rank candidates by + blocking value against false-positive cost. Present the proposed set and the + contract, and stop for the human. + +Output artifact: the proposed gate set and the per-finding report contract +Done when: a human has approved the gate set and the report contract, or returned them with changes +Operated-layer note: in an operated deployment the proposed set and the human's approval or edits land as an agreement-log row; the divergence between proposed and approved is the calibration signal (see AGREEMENT-LOG.md) +Fails look like: a gate contract that lets a check fix and pass. The moment a gate rewrites the thing it judges, its green means nothing, because it is grading its own homework. + +### Phase 3: Implement the checks against built output · lane: convergent (Tholo) + +Skills: qa-testing, seo-technical (nearest anchors; the gate-implementation core is a DECLARED GAP, procedure inline) +Capability class: ci.gate-implement (declared catalog gap; nearest-miss qa-testing, seo-technical) +Input: the approved gate set; the production-equivalent build command +Run: + + Invoke qa-testing and seo-technical as the check frameworks, and implement + each approved gate to run against the BUILT output with production-equivalent + flags, not the dev server and not source. Each gate emits the Phase 2 report + contract and exits non-zero on any fail. Wire them to run on the pull-request + event against the branch build. Land the wiring as a held PR; merge nothing. + +Output artifact: the gate implementations and their CI wiring, as a held PR that emits the report contract +Done when: each gate runs on the pull-request event against the built output and emits the report contract, in a held PR +Fails look like: asserting against a dev-flag build. A gate that passes on the dev server while the real build serves something else has verified a machine no user visits. + +### Phase 4: Deliberate-failure demonstration · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; procedure inline) +Capability class: ci.gate-prove (declared catalog gap; nearest-miss qa-testing) +Input: the wired gates from Phase 3 +Run: + + Invoke qa-testing's adversarial discipline. For each gate, seed a known-bad + input it must catch (a missing title, a broken internal link, a failing prove + check), run the pipeline, and capture the red: the gate failing and blocking, + with its report contract naming the seeded fault. Then revert the seed and + capture the green. Retain both as the gate's evidence. Report only; the seed + is reverted, never merged. + +Output artifact: per-gate failure evidence (the seeded fault, the captured red with its report, the reverted green) +Done when: every gate has a captured red on its seeded fault and a captured green after revert +Fails look like: shipping a gate no one has seen fail. A gate that has only ever passed is indistinguishable from a gate that checks nothing, and the difference surfaces the day it should have caught something. + +### Phase 5: Install as required checks and branch protection · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the proven gates and their evidence +Run: a person sets the gates as REQUIRED status checks and enables branch + protection so a failing verdict blocks a merge the way a failing test does. + These are platform state changes (repository settings and protection rules), + and they stay human. The person records which gates were made required and on + which branches. +Output artifact: the required-check and branch-protection configuration, recorded against the gate set +Done when: the named gates are required on the protected branches and a failing gate blocks the merge, confirmed by the human +Fails look like: gates that run but are not required. An advisory gate is a suggestion, and a pipeline under deadline merges past suggestions. + +### Phase 6: Drift watch · lane: convergent (Tholo) + +Skills: qa-testing, seo-technical (nearest anchors; procedure inline) +Capability class: ci.gate-drift (declared catalog gap; nearest-miss qa-testing, seo-technical) +Input: the installed gates; the canon each gate encodes (the prove checks, the report contract, the route list) +Run: + + Invoke qa-testing and seo-technical to re-verify each gate when its canon + moves: a gate that encodes a check's rules is re-proven (a Phase 4 rerun) when + that check updates, and a gate reading a route list is re-checked when routes + change. Flag any gate whose canon moved without a re-proof as stale. Land + re-proofs and updates as held changes. + +Output artifact: a drift record per gate (the canon version proven against, the last re-proof) and held updates for any stale gate +Done when: every gate names the canon version it was last proven against, and no gate is enforcing against moved canon unproven +Fails look like: a gate frozen against last quarter's rules. It still passes and still blocks, and it is now enforcing a standard the team no longer holds. + +## Failure modes + +- Gate theater: gates that never fail. The Phase 4 deliberate-failure demonstration is the antidote; a gate with no captured red is not installed. +- Hooks tripping on pre-existing debt: a gate that fails on unrelated legacy files in every PR gets bypassed, and a bypassed gate is a pipeline defect. Scope gates to the staged or changed set. +- Gates that fix instead of report: any gate that mutates what it judges. Report-only is the contract; a self-fixing gate grades its own work. +- Dev-flag assertion: gating against a non-production build, so the gate verifies an artifact production never serves. +- Advisory installation: wiring gates but never making them required (Phase 5's failure); a gate that does not block is documentation. +- Stale canon: gates enforcing rules that have since moved (Phase 6's failure). + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is installing this tier's prove gates as required status checks on an outdoor-sports content property, with the seeded-failure evidence retained per gate. Status flips to validated when that run record links here. + +## Boundaries + +- Post-Deploy Live Verification begins where these gates end: CI runs against the build, that workflow runs against the world, and a green pipeline is not a verified deploy. +- Content Pipeline with Prove Gates owns the content pre-publish gate (its Phase 3); this workflow is the wiring that makes any such gate a required, report-only, non-bypassable check. +- Warehouse Data Plane Standup stands up the bounded data access a data-reading gate would query; a gate needing warehouse access consumes that contract. diff --git a/workflows/content-pipeline-prove-gates.md b/workflows/content-pipeline-prove-gates.md new file mode 100644 index 0000000..534b6bc --- /dev/null +++ b/workflows/content-pipeline-prove-gates.md @@ -0,0 +1,171 @@ +# Content Pipeline with Prove Gates + +``` +name: Content Pipeline with Prove Gates +slug: content-pipeline-prove-gates +tier: forward-deployed (operations) +role: fdm +status: validated +run record: run-records/content-pipeline-prove-gates-run-1.md +score: 49 (demand 5, pain 4, differentiation 5, usability 4, connectors 4) +intent: run a content function as a delivery pipeline where every piece ships + through verification gates and a human merge +when to use: a content property with real traffic stakes, where volume is + agent-produced and trust cannot be +when not to use: one-off content tasks (use the build-time Content Production module); + site builds (use the Website Launch Pipeline); paid-media content + (off-catalog) +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: cms.draft # for CMS-published properties + access: write-held + - capability: repo.change # for git-published properties + access: write-held + - capability: crawl.read + access: read +``` + +One of cms.draft or repo.change is required, matching how the property publishes. Write-held means every draft lands held; nothing in this workflow publishes on its own. The agreement log referenced below is operated substrate with no connector class; see the operated-layer notes. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A demand source the ranking can read: a search-performance export, keyword data, or query logs. If using warehouse exports, enable them before anything else; they do not backfill. +- A publishable target with a draft-and-hold mechanism (CMS drafts or PRs). +- A claims-and-style standard file (STANDARDS.md or equivalent): voice rules, phrase rules, sourcing requirements. +- A route list or sitemap the link checks can resolve against. + +## Phases + +### Phase 1: Rank the backlog from demand · lane: divergent (Krine) + +Skills: seo-keyword, seo-keyword-gap-audit, content-strategy +Capability class: demand.rank (substitute equivalents if off-catalog) +Input: the demand source (search-performance data, keyword exports) plus whatever outcome history exists; the current content inventory +Run: + + Invoke seo-keyword and seo-keyword-gap-audit against the demand data, and + content-strategy against the property's positioning. Rank the candidate + topics with named, auditable criteria (demand volume tiers, intent fit to + the property's priority pages, difficulty). Emit the top items as a ranked + queue with the evidence attached to each: the demand numbers, the intent + read, and why it outranks its neighbors. Do not pick the winner; present + the ranking and stop. + +Output artifact: a ranked brief queue with per-item evidence (the stop package) +Done when: a human selects the go item from the ranking +Operated-layer note: in an operated deployment, the ranking and the human's selection land as an agreement-log row (ranked-choice payload); the divergence between engine order and human pick is the calibration signal +Fails look like: ranking by raw volume alone. Volume without intent fit sends the pipeline chasing traffic the property cannot convert or hold; the criteria exist to be argued with, which requires them to be named + +### Phase 2: Produce the held draft · lane: convergent (Tholo) + +Skills: content-brief-authoring, brand-voice, long-form-content-frameworks, seo-onpage +Capability class: content.draft (write-held) +Input: the selected brief from Phase 1; STANDARDS.md +Run: + + Invoke content-brief-authoring to expand the selected item into a full + brief, then draft against it using long-form-content-frameworks for + structure, brand-voice for voice, and seo-onpage for title, headers, meta, + and internal links. Every factual claim carries its source or derivation + inline. Land the result as a held draft (CMS draft or draft PR). Do not + publish, schedule, or merge. + +Output artifact: a held draft with sources inline, plus the brief it was written against +Done when: the draft exists in held state and nothing has published +Fails look like: the draft publishing directly because the target's draft mechanism was skipped. Write-held is the seam; a pipeline that can publish in this phase is a different and more dangerous machine + +### Phase 3: Pre-publish gate · lane: gate (Basano) + +Skills: editorial-qa, seo-onpage, seo-technical +Capability class: content.pre-publish-gate (substitute equivalents if off-catalog) +Input: the held draft from Phase 2 plus STANDARDS.md +Run: + + Invoke editorial-qa, seo-onpage, and seo-technical against the attached + draft. Using those skills' frameworks, check: every factual claim has a + source or derivation; style and phrase rules in STANDARDS.md pass; title, + meta description, and structured data are present and consistent; every + internal link resolves against the site's route list. Output a pass/fail + verdict per check with evidence. Do not fix anything; report only. + +Output artifact: a prove report (verdict per check, evidence attached), attached to the held draft +Done when (public gate): every check passes, or a failure is waived in writing with a recorded rationale attached to the held draft +Operated-layer note: in an operated deployment, the verdict and any waiver land as an agreement-log row; this is operated substrate, not part of the public package +Fails look like: the gate passing on a claim citing a source that does not contain the number (source-shape checking, not source-presence checking) + +### Phase 4: Human review and merge · lane: divergent (human, structural) + +Skills: none; this phase is the point +Input: the held draft and its prove report +Run: a person reviews the draft the way they would review a contractor's work, reads the prove report, and merges or publishes, or sends it back with notes +Output artifact: the published piece, or a revision note back to Phase 2 +Done when: a human has merged, published, or rejected; the pipeline never advances this phase on its own +Operated-layer note: the human verdict (merge, reject, revise, waive) and, on revise, what changed between proposal and merge, land in the agreement log; the proposal-to-merge diff is the pipeline's primary correction signal +Fails look like: rubber-stamping. If every draft merges untouched for weeks, either the pipeline has earned trust (the operated agreement record would show it) or the review has stopped happening; at template status, assume the second + +### Phase 5: Post-publish live audit · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; the live-verification core is a DECLARED GAP, procedure inline) +Capability class: deploy.live-verify (declared catalog gap; nearest-miss qa-testing) +Input: the production URL of the published piece; the approved draft from Phase 4 +Run: + + Fetch the live production URL (not a preview, not a staging domain, not a + cached copy). Verify: the rendered content matches what was approved at + merge; the canonical URL is self-referencing; title, meta description, + social-share metadata, and structured data are present on the live render + and match the approved values; every internal link on the live page + resolves. If the property fronts a CDN or uses incremental rendering, + confirm the render is current by checking a value known to have changed at + publish. Report verdict per check with the live evidence. + +Output artifact: a live-audit report tied to the production URL +Done when: every check passes against the live render, or the discrepancy is filed as a defect with the live evidence attached +Fails look like: verifying the preview. Merged is not live; a published piece can serve a stale render or the wrong metadata while the preview looks perfect, and only the production URL is ground truth + +### Phase 6: Outcomes and the refresh trigger · lane: convergent (Tholo) + +Skills: seo-rank-tracking, seo-content-audit, content-refresh-system +Capability class: outcomes.read + content.decay-detect +Input: search-performance and warehouse data for the published corpus, on a cadence (weekly or monthly) +Run: + + Invoke seo-rank-tracking against the published pieces' target queries and + seo-content-audit plus content-refresh-system against the corpus on the + set cadence. Flag pieces whose demand, position, or freshness has decayed + past the refresh thresholds. Emit decay flags as candidate items INTO the + Phase 1 ranking, carrying their evidence, where they compete with new + topics on the same criteria. + +Output artifact: outcome records per piece; decay flags entering the Phase 1 queue +Done when: outcomes are queryable for the next ranking cycle and decay candidates are in the queue +Fails look like: refresh running as its own separate pipeline. Decay is a demand source, not a second loop; the moment refreshes bypass the ranking, the pipeline has two front doors and the criteria govern only one of them + +## Failure modes + +- Gate theater: prove reports that always pass. A gate that never fails is either gating nothing or the drafts are being pre-sanitized to it; check by seeding a known-bad claim quarterly and confirming the gate catches it. +- Source-shape blindness: claims citing real sources that do not contain the claimed number (Phase 3's inline failure, the most common one in practice). +- Preview verification: Phase 5 run against anything but the production URL. +- Volume chasing: Phase 1 criteria quietly reduced to demand volume. +- Silent refresh edits: Phase 6 refreshes that change published claims without a visible note; corrections are visible or they are not corrections (see Corpus Integrity and Correction for the correction-note pattern). +- Write-held erosion: any phase acquiring publish or merge authority. At template status the human merge is absolute; graduation exists only under the operated autonomy doctrine, per lane, revocably, and never for judgment-tier gates. + +## Worked example + +Run 1 executed this workflow as written on bowhuntamerica.com: a demand-ranked how-to entered at Phase 1 and exited Phase 5 with a passing live audit, six pre-publish gates with no waiver, and a zero-diff human merge. The full run record, including the vantage finding Phase 5 surfaced and resolved, is linked from the front matter. + +## Boundaries + +- The build-time Content Production module owns one-off content tasks; this workflow owns the continuous loop. Each points here. +- Corpus Integrity and Correction owns claim-truth across the published corpus and the correction-note pattern; Phase 6 hands decayed or wrong claims to it rather than editing silently. +- Post-Deploy Live Verification owns the general deploy-verification procedure; Phase 5 is its content-shaped instance and shares its declared gap. diff --git a/workflows/conversion-by-source-diagnosis.md b/workflows/conversion-by-source-diagnosis.md new file mode 100644 index 0000000..377473f --- /dev/null +++ b/workflows/conversion-by-source-diagnosis.md @@ -0,0 +1,160 @@ +# Conversion-by-Source Diagnosis + +``` +name: Conversion-by-Source Diagnosis +slug: conversion-by-source-diagnosis +tier: forward-deployed (operations) +role: fda +status: template +score: 49 (demand 5, pain 5, differentiation 3, usability 4, connectors 5) +intent: find the conversion divergences worth money in the analytics export, + verify they are behavior rather than measurement, and emit a ranked + hypothesis list a human picks from +when to use: traffic is stable but the outcome number is not, or nobody has looked + at conversion by segment in a quarter +when not to use: traffic itself dropped (Traffic-Drop Triage); running the tests this + workflow proposes (Experiment Loop with Pre-Registered Gates); + verifying the tracking pipeline end to end (Revenue Tracking + Integrity) +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: analytics.read + access: read + - capability: search-performance.read + access: read # intent context for landing pages + - capability: crawl.read + access: read # measurement checks on live pages +``` + +Fully read-only. This workflow diagnoses and ranks; it changes nothing. Its output routes to the Experiment Loop or to held fixes owned elsewhere. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- Conversion events landing in the warehouse or analytics store with source attribution (the native analytics export into the warehouse is the reference setup; enable exports before anything else, they do not backfill). +- A defined conversion event set and, where it exists, a value per event; if value is unknown, the ranking uses volume and says so. +- Enough history for a stable baseline per segment (thin segments produce loud noise; the workflow flags them rather than ranking them). + +## Phases + +### Phase 1: Frame the funnel and the baseline · lane: convergent (Tholo) + +Skills: analytics-strategy, product-analytics-setup +Capability class: conversion.frame (substitute equivalents if off-catalog) +Input: the conversion event definitions; the analytics export in the warehouse +Run: + + Invoke analytics-strategy to state, in writing: which events count as + conversions here, what a source is (source/medium granularity), which + segments matter (landing page template, device, country, intent class), + and the baseline window. Invoke product-analytics-setup to confirm the + events named actually exist in the export with the fields the analysis + needs. Produce the frame document. No analysis yet. + +Output artifact: the frame (events, segments, baseline window, known value per event or the stated absence) +Done when: the frame names every dimension the sweep will cut by, and each named event is confirmed present in the data +Fails look like: framing after looking. A frame written once the divergences are visible quietly becomes a justification for them; the frame comes first so the sweep cannot be steered + +### Phase 2: The divergence sweep · lane: convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; the divergence-detection core is a DECLARED GAP, procedure inline) +Capability class: conversion.divergence-detect (declared catalog gap) +Input: the frame; bounded warehouse queries per the frame's window +Run: + + Compute conversion rate by source x landing template x device against + the baseline, with volume attached to every cell. Surface the divergences + worth money, in three shapes: segments converting well below their peers + at meaningful volume (the fix candidates), sources whose conversion + quality shifted against their own history (the quality drifts), and pages + that earn traffic but not outcomes, cross-read with search-performance + intent data (the rank-without-reward set). Flag thin cells as + not-rankable instead of ranking their noise. Attach the numbers to every + finding. + +Output artifact: the divergence table (finding, segment, magnitude, volume, baseline) +Done when: every finding carries its numbers and thin cells are marked not-rankable +Fails look like: averaging across segments, the same failure that breaks traffic triage. A flat blended conversion rate can hide one template at half its peers; the cuts in the frame exist so the blend cannot + +### Phase 3: Measurement gate · lane: gate (Basano) + +Skills: product-analytics-setup (anchor; procedure inline) +Capability class: measurement.verify (declared catalog gap) +Input: the divergence table; the live pages of affected segments (crawl.read) +Run: + + Before any divergence is treated as behavior, test it as measurement. + Per finding, check: consent-flow differences by source or geography + (a consent-heavy source under-reports conversions, not visitors); + attribution parameters surviving the landing path (redirects and + canonicalization strip params); cross-domain or app boundaries in the + converting path; event firing verified on the live affected templates; + and whether the divergence's start date aligns with a tracking or + consent deploy rather than a demand or content change. Verdict per + finding: BEHAVIOR, MEASUREMENT, or MIXED, with evidence. Report only. + +Output artifact: the divergence table, annotated with measurement verdicts +Done when: every finding carries a verdict; MEASUREMENT findings route to a tracking fix, not an optimization +Fails look like: optimizing a consent artifact. A quarter spent lifting a segment whose conversions were merely unmeasured is the expensive version of this failure, and it is common + +### Phase 4: Hypothesis ranking · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the BEHAVIOR and MIXED findings +Run: + + For each finding, state the hypothesis as mechanism, not aspiration: + what specifically about the page, offer, or match to intent would + explain the gap, and what change would test it. Rank by expected value + where value is known (volume x conversion delta x value per event) and + by volume-weighted delta where it is not, saying which basis each rank + uses. Present the ranked list with evidence. Recommend the top + candidates for testing; decide nothing. Stop for the human. + +Output artifact: the ranked hypothesis list (mechanism, evidence, expected-value basis) +Done when: a human selects which hypotheses proceed +Operated-layer note: in an operated deployment the ranking and the human's selection land as an agreement-log row; hypothesis hit-rate over time, fed back from experiment verdicts, is what calibrates this lane +Fails look like: aspiration hypotheses ("improve the CTA") with no mechanism. A hypothesis that does not say why the gap exists cannot be falsified by a test, and the experiment it produces measures nothing + +### Phase 5: Route the winners · lane: convergent (Tholo) + +Skills: routing; the work lives in the owning workflows +Input: the human-selected hypotheses +Run: + + Testable hypotheses route to the Experiment Loop with Pre-Registered + Gates, carrying their mechanism, expected effect size, and the segment + definition (the loop's pre-registration consumes exactly these). + Findings that are defects rather than hypotheses (a broken form, a + measurement fix) route as held changes to their owners. Record the + routing so experiment verdicts flow back against the original finding. + +Output artifact: routed work items, each tied to its finding and hypothesis +Done when: every selected hypothesis is in the experiment queue or routed as a held fix, with the return path recorded +Fails look like: the diagnosis running its own tests. The moment this workflow ships a variant, pre-registration is retrofitted to a change already believed in, and the experiment gate is theater + +## Failure modes + +- Segment blending (Phase 2's inline failure). +- Measurement artifacts optimized as behavior (Phase 3's inline failure, the expensive one). +- Expected-value theater: invented per-event values lending false precision to the ranking; the basis is stated or the rank is volume-weighted, never silently guessed. +- Thin-cell confidence: ranking noise from segments too small to trust; not-rankable is a verdict, not an apology. +- Mechanism-free hypotheses (Phase 4's inline failure). +- Self-testing (Phase 5's inline failure). + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property with conversion events; the intended first substrate is a designated property whose outbound pick-click events serve as the conversion set. Status flips to validated when that run record links here. + +## Boundaries + +- Experiment Loop with Pre-Registered Gates owns everything from pre-registration through verdict; this workflow supplies its intake and consumes its verdicts as calibration. +- Revenue Tracking Integrity owns the money path end to end on a schedule; Phase 3 here is a per-finding spot check, not that audit. +- Traffic-Drop Triage owns falling traffic; this workflow assumes traffic is roughly stable and the outcome is the question. diff --git a/workflows/corpus-integrity-and-correction.md b/workflows/corpus-integrity-and-correction.md new file mode 100644 index 0000000..1b58f26 --- /dev/null +++ b/workflows/corpus-integrity-and-correction.md @@ -0,0 +1,166 @@ +# Corpus Integrity and Correction + +``` +name: Corpus Integrity and Correction +slug: corpus-integrity-and-correction +tier: forward-deployed (operations) +role: fdm +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: keep a published corpus true over time: detect stale and wrong claims, + enforce derived counters, and correct visibly instead of silently +when to use: any property whose published pages carry claims, numbers, or dated + facts that age; any property where the same fact appears on more + than one page +when not to use: pre-publish checking of a new draft (Content Pipeline, Phase 3); + refreshing a decayed piece for demand reasons (Content Pipeline, + Phase 6); live data feeds like rates or prices (Data Surface + Integrity owns machine-rendered series; this workflow owns + authored claims) +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read # traffic-weights the triage + - capability: cms.draft # or repo.change, matching how the property publishes + access: write-held +``` + +Read-only until Phase 4; corrections land held, a human merges. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A crawlable corpus (the live site) and, for git-published properties, the content source tree. +- The property's canonical data sources for checkable claims (the statistics pages, standards bodies, or datasets its content cites). +- A decision, made once and recorded, of what counts as a visible correction on this property (the correction-note format and where it renders). + +## Phases + +### Phase 1: Claim inventory · lane: convergent (Tholo) + +Skills: seo-content-audit, editorial-qa +Capability class: corpus.claim-extract (substitute equivalents if off-catalog) +Input: the live corpus (crawl.read), plus the content source tree where one exists +Run: + + Invoke seo-content-audit across the corpus and editorial-qa's claim + framework per page. Extract every checkable claim: numbers, dates, + prices, counts, superlatives, cited facts, and every claim that names a + source. Classify each: DERIVED (rendered from a data source), RELAYED + (typed from a source at authoring time), or DATED (true as of a stated + date). Include claims living in titles, meta descriptions, and structured + data; body copy is the smallest part of the register. Emit the claim + register: claim, page(s), class, source if stated, last-verified date + if known. + +Output artifact: the claim register +Done when: the register covers the corpus including metadata surfaces, and every claim carries a class +Fails look like: inventorying body copy only. Claims rot fastest in the surfaces nobody rereads: meta descriptions, schema fields, comparison tables, and footer boilerplate + +### Phase 2: Truth check · lane: gate (Basano) + +Skills: editorial-qa, seo-content-audit (nearest anchors; the derived-counter and stale-claim detection cores are DECLARED GAPS, procedure inline) +Capability class: corpus.truth-check (declared catalog gap; nearest-miss editorial-qa) +Input: the claim register; the property's canonical sources +Run: + + For every RELAYED and DATED claim: check the source still exists, still + says what the page says, and whether the value has changed or the series + has been discontinued. For every count or total that a canonical source + could supply (a catalog size, an item count, an integration count): flag + any hand-typed literal as a defect regardless of whether it is currently + correct, because a correct literal is one release away from a wrong one. + For every fact appearing on more than one page: check the surfaces agree, + and flag any fact with two values or two sources as a defect even when + one of them is right. Output the discrepancy report with severity: + WRONG-NOW, STALE-BUT-WAS-RIGHT, HAND-TYPED-DERIVABLE, TWO-SURFACE-SPLIT, + UNVERIFIABLE (source gone). Verdict per claim, evidence attached. Do not + fix anything; report only. + +Output artifact: the discrepancy report +Done when: every register entry has a verdict, including the clean ones +Fails look like: source-presence checking. A claim citing a live source that no longer contains the claimed value passes a lazy check and fails a reader; the check is against the source's current content, not its existence + +### Phase 3: Triage and the correction plan · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the discrepancy report; search-performance data for the affected pages +Run: + + Rank the defects by reader harm: traffic-weight the affected pages + (search-performance.read), weight claims readers act on (money, safety, + how-to steps) above color, and mark each defect's correction class: + SILENT-SAFE (typos, formatting, broken links) or VISIBLE-CORRECTION + (any claim a reader may have relied on). Present the ranked plan and + stop for the human. + +Output artifact: a ranked correction plan with per-item correction class +Done when: a human approves the plan, including the correction classes +Operated-layer note: in an operated deployment the ranking and the human's approval or reordering land as an agreement-log row +Fails look like: severity by ease of fix. The cheap fixes migrate to the top because they close fast; the ranking's job is to hold reader harm above operator convenience + +### Phase 4: Corrections as held changes · lane: convergent (Tholo) + +Skills: editorial-qa, brand-voice +Capability class: content.correct (write-held) +Input: the approved plan; the property's correction-note format +Run: + + For each VISIBLE-CORRECTION item: fix the claim at its SOURCE (if the + value should derive, wire the derivation rather than retyping the number; + if the fact appears on several pages, fix the one source of truth and the + copies with it), and add the correction note in the property's format, + stating what was wrong, what it now says, and when it was corrected. + Original publish dates stay untouched. Removed claims are noted as + removed, not vanished. SILENT-SAFE items fix without notes. Everything + lands held: CMS drafts or a draft change, never a direct publish. + +Output artifact: held corrections, each tied to its plan item; correction notes in place +Done when: every approved item has a held change and nothing has published +Fails look like: silent edits to relied-upon claims. A correction a reader cannot see is indistinguishable from hoping nobody noticed, and on the day someone diffs the archive, it reads exactly that way + +### Phase 5: Verify live and install the guard · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; live verification shares the deploy.live-verify DECLARED GAP) +Input: the production URLs of corrected pages, post-merge +Run: + + After the human merges: fetch each corrected page's production URL and + verify the correction renders, the note renders where the format says it + should, and the corrected value matches the source. Then install the + guard: the Phase 1-2 pass recurs on a set cadence (quarterly fits most + corpora), and the property's authoring rule is recorded: every new + published number is derived or explicitly inventoried at publish time, + which is what keeps the next pass small. + +Output artifact: live verification per correction; the standing cadence and authoring rule, recorded +Done when: every merged correction is verified on its production URL and the cadence is scheduled +Fails look like: counting the fix as done at merge. Merged is not live; a correction that renders on the preview and not on production has corrected nothing + +## Failure modes + +- Silent edits (Phase 4's inline failure, and the workflow's reason to exist). +- Fixing copies instead of sources: retyping the right number on four pages plants the next two-surface split. +- Source-presence checking (Phase 2's inline failure). +- Severity by ease (Phase 3's inline failure). +- Metadata blindness: claims in meta descriptions, schema, and OG fields skipping the register. +- One-shot integrity: running this once and never installing the cadence; a corpus is only as honest as its most recent pass. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property. The pattern generalizes a real count-and-copy reconciliation on rampstack.co (hand-typed counts replaced with derived values, a listed-count mismatch corrected, a paragraph-length meta rebuilt from a derived count); the visible correction-note pattern additionally generalizes production incidents on an unnamed property. Status flips to validated when a run record links here. + +## Boundaries + +- Content Pipeline Phase 6 hands decayed or wrong claims here rather than editing silently; Phase 3 of the pipeline prevents new debt, this workflow retires existing debt. +- Data Surface Integrity owns machine-rendered data series (rates, prices, live stats) and their freshness guards; this workflow owns authored claims about the world. +- Regulated-Content Compliance Gate owns disclosure and claim rules at publish time in regulated verticals; corrections to regulated content route through both. diff --git a/workflows/data-surface-integrity.md b/workflows/data-surface-integrity.md new file mode 100644 index 0000000..80563f8 --- /dev/null +++ b/workflows/data-surface-integrity.md @@ -0,0 +1,162 @@ +# Data Surface Integrity + +``` +name: Data Surface Integrity +slug: data-surface-integrity +tier: forward-deployed (operations) +role: fde +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: keep machine-rendered data series honest: per-series freshness guards, + two-surface consistency from one source, honest degradation, and + discontinued-series retirement +when to use: any property that renders live or periodic data series (rates, prices, + counts, stats) a reader is expected to trust +when not to use: authored claims about the world (Corpus Integrity and Correction); + whether a surface is current at all after a deploy (Post-Deploy Live + Verification) +validation note: gated on a designated data surface existing or the allowlist expanding; + neither designated property renders external data series today +gap note: the freshness-guard and consistency cores are DECLARED CATALOG GAPS with + monitoring-and-alerting and seo-technical as the nearest anchors; those + phases are inline procedure. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only Phase 5's retirement changes +``` + +Read-only until Phase 5; retirement changes land held, a human merges. Nothing in the audit acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The property's machine-rendered data series and the source each renders from (the warehouse tables or feeds behind them). +- The live surfaces that render each series (crawl.read), including metadata and any narration that cites the series. +- The per-series cadence each source actually updates on. +- A place to record the discontinued-series registry and the correction-note format (the same format Corpus Integrity and Correction uses). + +## Phases + +### Phase 1: Series inventory · lane: convergent (Tholo) + +Skills: monitoring-and-alerting (nearest anchor; the series-inventory core is a DECLARED GAP, procedure inline) +Capability class: data.series-inventory (declared catalog gap; nearest-miss monitoring-and-alerting) +Input: the property's data sources; the live surfaces (crawl.read) +Run: + + Invoke monitoring-and-alerting's series discipline. Inventory every + machine-rendered series ONE series at a time: its source, the cadence that + source actually updates on, and every surface that consumes it (tiles, tables, + metadata, and any narration that cites it). Key the inventory by series, never + by dataset, because a dataset holds many series on different cadences. Produce + the per-series inventory; guard nothing yet. + +Output artifact: the per-series inventory (each series: source, real cadence, every consuming surface) +Done when: every machine-rendered series is inventoried by series with its source, cadence, and consuming surfaces, including metadata and narration +Fails look like: inventorying by dataset. A dataset marked fresh can carry one series that froze months ago, and a dataset-level view never sees the frozen series inside it. + +### Phase 2: Guard audit · lane: gate (Basano) + +Skills: monitoring-and-alerting (nearest anchor; the freshness-guard core is a DECLARED GAP, procedure inline) +Capability class: data.freshness-guard (declared catalog gap; nearest-miss monitoring-and-alerting) +Input: the per-series inventory +Run: + + Invoke monitoring-and-alerting's threshold discipline as a gate. Per series, + check three guards and change nothing. Freshness: a per-series staleness + threshold exists and fires when the series exceeds its own cadence, never a + dataset-wide threshold. Discontinued registry: a series that stopped updating + is registered as discontinued, not silently served stale. Honest degradation: + when a series is stale or degraded, the surface renders honestly, showing the + as-of date and suppressing the trend arrows and deltas a frozen value cannot + support. Report a verdict per series per guard with the rendered evidence. + +Output artifact: the guard report (per series: freshness threshold, discontinued registration, honest degradation, each with a verdict) +Done when: every series has a verdict on its per-series freshness threshold, its discontinued status, and its degradation rendering +Fails look like: a trend arrow on a degraded series. An up arrow drawn from a value that stopped updating tells the reader the number is rising when it is only frozen, which is worse than showing nothing. + +### Phase 3: Two-surface consistency · lane: gate (Basano) + +Skills: seo-technical, qa-testing (nearest anchors; the consistency build-test core is a DECLARED GAP, procedure inline) +Capability class: data.two-surface-consistency (declared catalog gap; nearest-miss seo-technical, qa-testing) +Input: the per-series inventory (series rendered on more than one surface) +Run: + + Invoke seo-technical and qa-testing. For any value that appears on two or more + surfaces, prove it renders from ONE source module, and back that proof with a + build test that fails if the two surfaces ever derive the value independently. + Check the caches too: two surfaces reading one module in code can still + diverge when their cache lifetimes differ, so the test covers served output, + not only source. Report consistency per shared value with the build-test + evidence. + +Output artifact: the consistency report (each shared value: single-source proof, the build test, the cache-lifetime check) +Done when: every value on two or more surfaces is proven single-source with a build test, or the divergence is flagged with evidence +Fails look like: one source in code, two lifetimes in cache. Two surfaces importing the same module look consistent in review and serve different numbers in production because one cache outlived the other. + +### Phase 4: Cadence-copy alignment · lane: gate (Basano) + +Skills: editorial-qa, monitoring-and-alerting (nearest anchors; the cadence-claim core is a DECLARED GAP, procedure inline) +Capability class: data.cadence-alignment (declared catalog gap; nearest-miss editorial-qa, monitoring-and-alerting) +Input: the per-series inventory; the surface copy that claims an update frequency +Run: + + Invoke editorial-qa to find the copy and monitoring-and-alerting to check the + mechanism. Wherever a surface states its own update frequency ("updated + daily", "live rates", "refreshed weekly"), verify the series behind it + actually updates on that cadence. A page promising daily data over a series + that updates monthly is a false claim the reader cannot see is false. Report + each cadence claim against its series' real cadence with a verdict. Report + only. + +Output artifact: the cadence-alignment report (each stated frequency, the series' real cadence, a verdict) +Done when: every surface claim about its own update frequency has a verdict against the series' real cadence +Fails look like: trusting the copy. "Updated daily" is a claim like any other, and a series that refreshes monthly behind it is a dated claim that rots the moment the copy ships. + +### Phase 5: Retirement protocol · lane: convergent (Tholo) + +Skills: editorial-qa, brand-voice +Capability class: data.series-retirement (write-held) +Input: the discontinued series from Phase 2; the property's correction-note format +Run: + + Invoke editorial-qa and brand-voice for the retirement, the same correction + discipline Corpus Integrity and Correction uses. For each discontinued series: + remove it from current renders (the tile, the table, the metadata), and add a + visible correction note anywhere the corpus narrates the series, stating that + it is discontinued and as of when. The narration is retired with the tile, not + left behind to describe a number that no longer renders. Everything lands + held; a human merges. + +Output artifact: held retirement changes per discontinued series (removed from renders, correction note on any narration) +Done when: every discontinued series is removed from current renders and its narration carries a visible correction note, all as held changes +Fails look like: retiring the tile but not the narration. The number disappears from the dashboard while a paragraph elsewhere still explains what it means and where it is heading, describing a series that no longer exists. + +## Failure modes + +- Dataset-level guards (Phase 1 and Phase 2's failure): a frozen series hiding inside a fresh dataset. +- Trend arrows on degraded series (Phase 2's failure): an arrow drawn from a value that stopped moving. +- One source in code, two lifetimes in cache (Phase 3's failure): two surfaces diverging past a shared module because their caches expire differently. +- Retiring the tile but not the narration (Phase 5's failure): the render gone, the prose still describing it. +- Cadence copy outrunning the mechanism (Phase 4's failure): a stated update frequency the series never meets. +- Guards written once and never re-run: a series added after the audit renders unguarded, so the guard set is only as complete as its last inventory. + +## Worked example + +Pending. Populates when this workflow is executed as written on a designated property that renders live data series; neither designated property renders external data series today, so it is gated on such a surface existing or the allowlist expanding. The freshness and degradation patterns generalize production incidents on an unnamed property (a series serving a frozen value behind a live trend arrow); that origin informs the guards but is not validation evidence. + +## Boundaries + +- Corpus Integrity and Correction owns authored claims about the world; this workflow owns machine-rendered data series, and Phase 5's retirement uses that workflow's correction-note pattern for any narration of a discontinued series. +- Post-Deploy Live Verification owns whether a surface is current at all after a deploy; this workflow owns whether the series it renders stay fresh, consistent, and honestly degraded between deploys. +- Warehouse Data Plane Standup stands up the bounded warehouse access and the sensing layer this workflow's guards read through. diff --git a/workflows/experiment-loop-with-pre-registered-gates.md b/workflows/experiment-loop-with-pre-registered-gates.md new file mode 100644 index 0000000..946da7a --- /dev/null +++ b/workflows/experiment-loop-with-pre-registered-gates.md @@ -0,0 +1,171 @@ +# Experiment Loop with Pre-Registered Gates + +``` +name: Experiment Loop with Pre-Registered Gates +slug: experiment-loop-with-pre-registered-gates +tier: forward-deployed (operations) +role: fdm +status: template +score: 43 (demand 4, pain 4, differentiation 3, usability 4, connectors 5) +intent: Basano on the test design: the stopping rule, MDE, and sample-size math + pre-registered before any variant ships, the SEO safety of variants gated, + and the verdict computed only against the pre-registered rule +when to use: a mechanism hypothesis worth a controlled test on a property with enough + traffic to power it +when not to use: finding the hypothesis in the first place (Conversion-by-Source Diagnosis); + a defect fix rather than a test (the ordinary held-fix flow) +validation note: gated on adequate traffic on a designated property; it holds at template + until a designated property has the traffic and a mechanism to test +``` + +## Connectors + +``` +connectors: + - capability: experiment.read + access: read + - capability: analytics.read + access: read + - capability: crawl.read + access: read # variant SEO-safety checks on the built variant + - capability: repo.change + access: write-held # the variant and its config land as held changes +``` + +The variant and its config land held; a human allocates traffic and launches. Traffic allocation is never an agent action. The verdict is computed against the pre-registered rule and nothing else. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A hypothesis from Conversion-by-Source Diagnosis (mechanism, expected effect, segment), or an equivalent stated the same way. +- Enough traffic in the target segment to power a test; if the segment cannot reach the sample the math requires, the honest outcome is not to run. +- The experiment platform (experiment.read) and the analytics that will measure the primary metric. +- A person who allocates traffic and launches; the workflow never does. + +## Phases + +### Phase 1: Intake · lane: convergent (Tholo) + +Skills: analytics-strategy +Capability class: experiment.intake (substitute equivalents if off-catalog) +Input: the hypothesis from Conversion-by-Source Diagnosis (mechanism, expected effect, segment) +Run: + + Invoke analytics-strategy to frame the incoming hypothesis as a testable spec: + the mechanism it claims (what about the page or offer would move the metric, + and why), the expected effect size, the primary metric it would move, and the + exact segment. A hypothesis that arrives as an aspiration rather than a + mechanism goes back to Conversion-by-Source Diagnosis; this workflow tests + mechanisms, not hopes. Produce the framed spec. + +Output artifact: the framed experiment spec (mechanism, expected effect size, primary metric, segment) +Done when: the hypothesis is framed as a mechanism with an expected effect size, a primary metric, and a segment, or returned to Conversion-by-Source Diagnosis as too vague to test +Fails look like: testing an aspiration. "Improve the CTA" names no mechanism and predicts no effect, so whatever the test does, nothing is learned; the spec has to say why the gap exists before a test can falsify it. + +### Phase 2: Pre-registration · lane: gate (Basano) + +Skills: experiment-design, experimentation-analytics +Capability class: experiment.pre-registration (substitute equivalents if off-catalog) +Input: the framed experiment spec; the segment's available traffic +Run: + + Invoke experiment-design and experimentation-analytics to pre-register the + test BEFORE anything ships: the stopping rule, the minimum detectable effect, + the sample-size math the MDE and the segment's traffic imply, the primary + metric, and the window. Write them down and freeze them. If the segment cannot + reach the required sample in a reasonable window, the pre-registration verdict + is "insufficient n, do not run", which is a respectable and final outcome, not + a delay. Report the pre-registration, or the not-run verdict, with the math. + +Output artifact: the frozen pre-registration (stopping rule, MDE, sample size, primary metric, window), or the "insufficient n, do not run" verdict with its math +Done when: the test is pre-registered with all five fields frozen, or it is declared underpowered and not run, with the sample-size math shown either way +Fails look like: shipping first and pre-registering after. A stopping rule and a metric written once the variant is believed in are fitted to the hope, and the test becomes a search for a number that agrees with it. + +### Phase 3: Variant SEO-safety gate · lane: gate (Basano) + +Skills: seo-technical +Capability class: experiment.seo-safety (substitute equivalents if off-catalog) +Input: the built variant (crawl.read); the pre-registration +Run: + + Invoke seo-technical against the built variant. Check that the variant is safe + to serve to search: no cloaking risk (the variant does not show crawlers and + users materially different content in a way search treats as deceptive), + canonical consistency across the variant and the control, and no layout-shift + or core-vitals regression the variant introduces. Report a verdict per check + with the evidence. Report only. + +Output artifact: the SEO-safety report (cloaking, canonical consistency, layout-shift, each with a verdict) +Done when: the variant carries a verdict on cloaking risk, canonical consistency, and layout-shift, all clear or the risk flagged +Fails look like: an experiment that wins by getting deindexed. A variant that trims the content search ranked for can lift the on-page metric while the page quietly falls out of the results, and the test would call that a win. + +### Phase 4: Launch as a held config change · lane: divergent (human) + +Skills: none; the launch and the traffic allocation are deliberately human +Input: the pre-registration and the passing SEO-safety report +Run: the variant and its experiment config land as a HELD change (repo.change). + A person allocates traffic and launches the test; traffic allocation is never + an agent action, because it is a live change to what real users see. The human + launches against the frozen pre-registration, allocating exactly the design + the math called for, and records the launch. +Output artifact: the launched experiment, recorded against its pre-registration, with the variant and config as held changes a human merged +Done when: the experiment is launched by a human at the pre-registered allocation, with the config held and merged by a person +Fails look like: an agent turning traffic on. Allocating traffic is a production act on real users, and it stays with a person the same way merging and deploying do. + +### Phase 5: The verdict · lane: gate (Basano) + +Skills: experimentation-analytics +Capability class: experiment.verdict (substitute equivalents if off-catalog) +Input: the running experiment's results; the frozen pre-registration +Run: + + Invoke experimentation-analytics to compute the verdict ONLY against the + pre-registered rule, at the pre-registered point. The stopping rule decides + when the test ends; interim looks are not stopping decisions, and a result + that looks significant early is not a verdict until the pre-registered point. + The primary metric is the one pre-registered, not whichever moved. Report the + verdict (win, loss, or inconclusive) against the pre-registered rule, with the + numbers. Report only. + +Output artifact: the verdict against the pre-registered rule (win, loss, or inconclusive) with the numbers at the pre-registered point +Done when: the verdict is computed at the pre-registered point against the pre-registered primary metric and stopping rule, with the numbers attached +Fails look like: peeking, then stopping on a good look. Checking the test daily and stopping the day it crosses significance turns noise into a false win, because the more often you look, the more often chance alone crosses the line. + +### Phase 6: Closeout · lane: convergent (Tholo) + +Skills: experimentation-analytics +Capability class: experiment.closeout (substitute equivalents if off-catalog) +Input: the verdict; the original hypothesis and its Conversion-by-Source finding +Run: + + Invoke experimentation-analytics to close the loop. Route the verdict and the + hypothesis outcome back to Conversion-by-Source Diagnosis as calibration: a + hypothesis that won, lost, or came back inconclusive updates that workflow's + hit-rate, which is what makes its next ranking better. If a winning variant is + to consolidate into the live page, it re-enters the SEO-safety check on the + consolidated version before it ships through the ordinary held-fix flow; the + experiment never publishes itself. Record the closeout. + +Output artifact: the routed verdict and hypothesis outcome to Conversion-by-Source Diagnosis, and the consolidation path (with its SEO-safety re-check) recorded where a variant won +Done when (public gate): the verdict and hypothesis outcome are recorded and routed to Conversion-by-Source Diagnosis, and any winning variant is queued for the ordinary held-fix flow with an SEO-safety re-check, not published from here +Operated-layer note: in an operated deployment the pre-registration, the verdict, and their agreement land as an agreement-log row; the verdict-versus-pre-registration agreement is what calibrates this lane (AGREEMENT-LOG.md) +Fails look like: shipping the winner without re-checking the consolidated version. A variant proven safe in isolation can regress SEO once it is merged into the real page with the rest of the layout, and the win does not carry a waiver for that. + +## Failure modes + +- Peeking (Phase 5's failure): interim looks becoming stopping decisions, which manufactures false wins. +- Post-hoc metric switching: reporting whichever metric moved instead of the pre-registered primary. +- Retrofitted pre-registration (Phase 2's failure): registering the rule after the variant is believed in. +- Shipping the winner without the SEO-safety re-check on the consolidated version (Phase 6's failure). +- Underpowered tests run anyway: ignoring the "insufficient n, do not run" verdict and running a test that cannot detect the effect; not-rankable is a verdict here too. +- An agent allocating traffic (Phase 4's failure): a production act on real users that stays human. + +## Worked example + +Pending. Populates when this workflow is executed as written on a designated property with adequate traffic to power a test; it holds at template until a designated property has both the traffic and a mechanism hypothesis to run. Status flips to validated when a run record links here. + +## Boundaries + +- Conversion-by-Source Diagnosis supplies this workflow's intake (its ranked hypotheses) and consumes its verdicts as calibration; the two form the diagnose-then-test loop, and neither runs the other's step. +- Revenue Tracking Integrity underwrites the measurement this workflow trusts: a verdict computed over a money path that does not survive redirects or consent is a verdict over noise. +- Content Pipeline with Prove Gates owns the publish path; a winning variant consolidates through the ordinary held-fix flow with an SEO-safety re-check, and the experiment never self-selects into publishing. diff --git a/workflows/incident-response-and-lane-demotion.md b/workflows/incident-response-and-lane-demotion.md new file mode 100644 index 0000000..23c9e59 --- /dev/null +++ b/workflows/incident-response-and-lane-demotion.md @@ -0,0 +1,176 @@ +# Incident Response and Lane Demotion + +``` +name: Incident Response and Lane Demotion +slug: incident-response-and-lane-demotion +tier: forward-deployed (operations) +role: cross +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: the event-driven counterpart to Autonomy Review: when a promoted lane's + post_merge_outcome regresses, demote the lane to human-gated first, then + roll back, then audit the false-pass row +when to use: a promoted lane shows a post-merge regression, a known suspect rather + than a mystery +when not to use: a traffic drop with no known cause (Traffic-Drop Triage); an ordinary + defect on a lane that was never promoted (the normal held-fix flow) +gap note: the attribution and false-pass-audit cores are DECLARED CATALOG GAPS with + incident-response as the nearest anchor; those phases are inline procedure. + It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: repo.change + access: write-held # the rollback and any fix land as held changes +``` + +The rollback and the fix land held; a human merges them through the now human-gated lane. The demotion itself and the agreement-log rows are operated actions on the operated instance; this workflow never promotes or re-promotes a lane. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A running autonomy program with at least one promoted lane and the agreement log behind it (AGREEMENT-LOG.md); with no promoted lane, Phase 2 routes elsewhere and this workflow does not apply. +- The `post_merge_outcome` signal source: the monitoring and verification outputs that populate it. +- The lane's `post_merge_outcome` budget, the regression threshold that makes a demotion mandatory. +- The rollback mechanism for the lane's changes. + +## Phases + +### Phase 1: Detection intake · lane: convergent (Tholo) + +Skills: incident-response, launch-runbook +Capability class: incident.intake (substitute equivalents if off-catalog) +Input: the `post_merge_outcome` signals for the window; the monitoring and verification outputs +Run: + + Invoke incident-response and launch-runbook to classify the intake. Enumerate + what counts as a lane-attributable regression: the post_merge_outcome signal + classes (a verification failure that recurs on a promoted lane's deploys, a + monitored metric crossing its regression budget) as distinct from ordinary + noise. For each signal, record the lane it points at, the merges in the + window, and the post_merge_outcome evidence. Produce the intake; attribute + nothing to a promoted lane yet. + +Output artifact: the intake record (each signal, its candidate lane, the window's merges, the post_merge_outcome evidence) +Done when: every regression signal in the window is recorded with its candidate lane and its post_merge_outcome evidence +Fails look like: treating every wobble as an incident. A metric breathing inside its normal band is not a regression, and an intake that flags noise trains the team to demote on nothing. + +### Phase 2: Attribution · lane: gate (Basano) + +Skills: incident-response (nearest anchor; the lane-attribution core is a DECLARED GAP, procedure inline) +Capability class: incident.attribution (declared catalog gap; nearest-miss incident-response) +Input: the intake record +Run: + + Invoke incident-response's attribution discipline as a gate. For each signal, + answer one question with evidence: is this regression attributable to a + PROMOTED lane's merge? Read the agreement log for the lane's recent merges and + their proposal_to_merge_diff, and line the regression up against a specific + promoted-lane merge. If the lane was never promoted (gate auto-pass and merge + authority never granted), this workflow does not apply: route a mystery drop + to Traffic-Drop Triage and an ordinary defect to the normal held-fix flow, and + say which. Report attribution per signal: a promoted-lane regression with the + merge named, or routed elsewhere with the destination named. + +Output artifact: the attribution verdict per signal (promoted-lane regression with the merge identified, or routed elsewhere) +Done when: every signal is either attributed to a specific promoted-lane merge with evidence, or routed to Traffic-Drop Triage or the normal defect flow with the destination named +Operated-layer note: the attribution reads the operated agreement log's rows and proposal_to_merge_diff for the lane; the schema is public (AGREEMENT-LOG.md), the instance and its rows are operated +Fails look like: blaming the gate before the evidence lands. Attributing a regression to a promoted lane without lining it up against a specific merge demotes a lane for a coincidence while the real cause keeps running. + +### Phase 3: Demote first · lane: divergent (human) + +Skills: none; the demotion is a deliberate human act +Input: the attribution verdict for a confirmed promoted-lane regression +Run: before any fix is written, a person returns the lane to human-gated. The + lane stops auto-passing and stops holding merge authority at once, so it + cannot merge again while it is being debugged. This is the ordinary first + move, not a punishment: a promoted lane that regressed has lost the evidence + that earned it, and it gets that evidence back the ordinary way, by re-earning + it. Record the demotion and its reason. +Output artifact: the lane returned to human-gated, with the demotion and its reason recorded +Done when: the lane is human-gated and cannot auto-pass or auto-merge, confirmed before any fix is written +Operated-layer note: in an operated deployment the demotion is recorded as an agreement-log action against the lane, with the regression as its reason; the demotion of the operated lane is an operated act (AGREEMENT-LOG.md) +Fails look like: fixing before demoting. While the fix is being written the lane is still promoted and still merging, so the machine that produced the regression keeps producing, and the incident grows a second head. + +### Phase 4: Roll back and fix as held changes · lane: convergent (Tholo) + +Skills: incident-response (nearest anchor; procedure inline) +Capability class: incident.rollback (write-held) +Input: the demoted lane; the attributed merge +Run: + + Invoke incident-response's rollback discipline. Roll back the attributed merge, + or land the corrective fix, as a HELD change (repo.change) a human merges + through the now human-gated lane. Verify the change against the + post_merge_outcome signal that detected the regression: it closes only when + that signal clears. Nothing here re-promotes the lane; the change merges + through the human gate the way every change on this lane now does. + +Output artifact: the held rollback or fix, tied to the attributed merge, with the post_merge_outcome signal it must clear +Done when: the rollback or fix is a held change and the regression signal has cleared against it, with the lane still human-gated +Fails look like: closing the incident on the merge instead of on the signal. The change meant to fix the regression is verified by re-running the post_merge_outcome check that caught it, not by the fact that a PR merged. + +### Phase 5: The false-pass audit · lane: gate (Basano) + +Skills: incident-response (nearest anchor; the false-pass-audit core is a DECLARED GAP, procedure inline) +Capability class: incident.false-pass-audit (declared catalog gap; nearest-miss incident-response) +Input: the agreement log row for the regressed merge; the gate that passed it +Run: + + Invoke incident-response's post-incident discipline as a gate. Find the + agreement-log row where the guardrail passed the merge that regressed: it is a + false_pass, and the audit asks what the gate misses STRUCTURALLY, not who + erred. Name the class of fault the gate could not see, and turn it into a + specific gate improvement (a new check, a tightened threshold) so the same + miss cannot re-promote a lane later. Report the audit with the false_pass row + and the proposed gate improvement. + +Output artifact: the false-pass audit (the false_pass row, the structural gap named, the proposed gate improvement) +Done when (public gate): the structural gap is named and a specific gate improvement is proposed as a held change +Operated-layer note: the audited row is the operated log's false_pass for the regressed merge; the schema and the four-way agreement values are public (AGREEMENT-LOG.md), the row is operated +Fails look like: demotion without the audit. A lane demoted and fixed but never audited leaves the gate that missed the fault unchanged, and the same miss re-promotes the same class of regression next quarter. + +### Phase 6: Re-promotion path · lane: convergent (Tholo) + +Skills: none; the re-promotion rule is doctrine, procedure inline +Capability class: incident.re-promotion (procedure inline) +Input: the demoted lane; the gate improvement from Phase 5 +Run: + + State the re-promotion path and record it; do not walk it here. Re-promotion + is never automatic. The lane re-earns gate auto-pass and merge authority the + ordinary way, under Autonomy Review's thresholds, over a RESET window that + starts after the fix and the gate improvement land, so the rows that regressed + do not count toward the lane's recovery. Record the reset window's start and + the conditions the lane must meet, and hand the lane to Autonomy Review. + +Output artifact: the recorded reset window (its start, the thresholds the lane must re-earn) handed to Autonomy Review +Done when: the reset window is recorded with its start and re-earning conditions, and the lane is handed to Autonomy Review rather than re-promoted here +Fails look like: quietly re-promoting the lane once the fix lands. A lane restored to autonomy without re-earning it under a reset window has learned nothing, and the demotion was theater. + +## Failure modes + +- Fixing before demoting (Phase 3's failure): the lane keeps merging while you debug it. +- Blaming the gate on noise: attributing a regression to a promoted lane before lining it up against a specific merge (Phase 2's failure); attribution rigor comes before demotion. +- Demotion without the false-pass audit (Phase 5's failure): the same miss re-promotes later. +- Automatic or quiet re-promotion (Phase 6's failure): the lane restored without re-earning under a reset window. +- Treating demotion as shameful: demotion is the system working, the ordinary first move, and a tone that makes it an emergency makes teams avoid promoting at all. +- Closing on the merge, not the signal (Phase 4's failure): the fix verified by a merged PR rather than a cleared post_merge_outcome. + +## Worked example + +Pending. Populates when a promoted lane first regresses and this workflow demotes it; no lane is promoted today, so this stays template until the autonomy program has a lane to demote. Status flips to validated when that run record links here. + +## Boundaries + +- Traffic-Drop Triage owns the mystery drop with no known suspect; this workflow owns the regression with a known suspect, a promoted lane's own merge, and Phase 2 routes to that workflow when no promoted lane is attributable. +- Autonomy Review owns promotion; this workflow owns the revocation that promotion promised, and the two are a pair: no lane graduates there until this is armed here. +- AGREEMENT-LOG.md is the schema whose post_merge_outcome this workflow reads and whose false_pass row it audits; that file defines the columns and the four-way agreement values this workflow uses. diff --git a/workflows/link-graph-and-metadata-parity-audit.md b/workflows/link-graph-and-metadata-parity-audit.md new file mode 100644 index 0000000..0f4e33a --- /dev/null +++ b/workflows/link-graph-and-metadata-parity-audit.md @@ -0,0 +1,131 @@ +# Link Graph and Metadata Parity Audit + +``` +name: Link Graph and Metadata Parity Audit +slug: link-graph-and-metadata-parity-audit +tier: forward-deployed (operations) +role: fdm +status: template +score: 45 (demand 5, pain 3, differentiation 3, usability 5, connectors 5) +intent: audit a site's link graph and per-route share metadata: find orphans and + dead ends, and hold every route to unique, self-referencing metadata +when to use: a site large enough that routes get orphaned or inherit the homepage's + metadata by default; a periodic structural pass +when not to use: per-deploy verification of the routes a change touched (Post-Deploy Live + Verification); whether a claim is true (Corpus Integrity and Correction) +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only in Phase 4, and only as held changes +``` + +Read-only until Phase 4; fixes land held, a human merges. Nothing in the audit acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The production site, crawlable, and the route registry or sitemap to reconcile the crawl against. +- The templates behind the routes, for fixes that belong at the template rather than the page. +- The list of money or conversion surfaces the graph is expected to feed. + +## Phases + +### Phase 1: Build the link graph · lane: convergent (Tholo) + +Skills: seo-technical, seo-site-health-audit +Capability class: linkgraph.build (substitute equivalents if off-catalog) +Input: the live site (crawl.read) and the route registry or sitemap +Run: + + Invoke seo-technical and seo-site-health-audit against a crawl of the live + site, reconciled with the route registry or sitemap. Build the directed link + graph: every route a node, every internal link an edge, with each route's + templates and its share metadata (title, description, canonical, OG, Twitter) + attached. Reconcile crawl against registry so that routes which exist but are + unlinked, and links that point at routes which do not exist, are both visible. + Produce the graph; judge nothing yet. + +Output artifact: the link graph (routes, edges, per-route metadata) reconciled against the route registry +Done when: every registry route is a node and every internal link is an edge, with crawl-versus-registry discrepancies marked +Fails look like: crawling the preview. A staging crawl maps a link graph no user traverses, and the orphan on production is the page staging linked fine. + +### Phase 2: Orphan and dead-end detection · lane: gate (Basano) + +Skills: seo-site-health-audit +Capability class: linkgraph.orphan-detect (substitute equivalents if off-catalog) +Input: the link graph +Run: + + Invoke seo-site-health-audit against the graph and flag two classes, fixing + nothing. Orphans: routes with zero inbound internal links, reachable only by + direct URL. Dead ends toward outcomes: routes with zero outbound links to the + money or conversion surfaces they should feed. Weight each by the route's + value (traffic or commercial intent) so the ranking holds business harm above + raw count. Report each with its graph evidence: the node, its inbound and + outbound degree, and the path that is missing. + +Output artifact: the orphan-and-dead-end report (each flagged route, its degrees, the missing path, its weight) +Done when: every route with zero inbound, or zero outbound to an outcome surface, is flagged with evidence, including the clean high-value routes confirmed reachable +Fails look like: counting orphans without weighting them. A thousand orphaned tag pages and one orphaned money page are not the same finding, and an unweighted list buries the one that pays. + +### Phase 3: Metadata parity per route · lane: gate (Basano) + +Skills: seo-onpage, seo-technical +Capability class: metadata.parity (substitute equivalents if off-catalog) +Input: the link graph's per-route metadata +Run: + + Invoke seo-onpage and seo-technical against every route's metadata. Check: + title and description are unique per route, not the homepage's defaults; OG + and Twitter tags are per-route, not the site-wide fallback; the canonical is + self-referencing; and no title template is doubling its suffix (the + "Page | Site | Site" class). Verdict per route per check, with the rendered + metadata as evidence. Report only. + +Output artifact: the metadata-parity report (verdict per route per check, rendered metadata attached) +Done when: every route carries a verdict for uniqueness, per-route OG and Twitter, self-canonical, and suffix dedup +Fails look like: checking presence, not uniqueness. Every page carrying the homepage's OG image passes a presence check and fails a reader who sees the same card for forty different links. + +### Phase 4: Triage and held fixes · lane: divergent (Krine) then convergent (Tholo) + +Skills: seo-onpage, seo-technical +Capability class: metadata.correct (write-held) +Input: the orphan-and-dead-end report and the metadata-parity report +Run: + + Invoke seo-onpage and seo-technical to rank the findings by value-weighted + harm and present the plan for a human to approve (the divergent stop). On + approval, use those skills to fix at the TEMPLATE, not the page: a doubled + suffix or a fallback-OG defect is one + template change that clears every route it governs, and a per-page patch + plants the next drift. Orphans are fixed by adding the missing inbound links + at their source. Everything lands held: a draft change, never a direct push. + +Output artifact: a ranked plan, then held fixes at the template level, each tied to its finding +Done when (public gate): a human has approved the plan, and every approved fix is a held change with nothing published +Operated-layer note: in an operated deployment the ranking and the human's approval or reordering land as an agreement-log row (see AGREEMENT-LOG.md) +Fails look like: fixing template symptoms per page. Retyping the right title on forty routes leaves the template that mis-set them in place, and the forty-first route ships wrong next week. + +## Failure modes + +- Presence-not-uniqueness checking (Phase 3's failure): every page sharing the homepage OG passes a presence check. +- Crawling the preview (Phase 1's failure): a link graph no user traverses. +- Per-page template fixes (Phase 4's failure): treating a template defect one route at a time. +- Unweighted orphan lists: a money page and a tag page counted the same. +- Registry-crawl blindness: trusting one source, so a route that exists but is unlinked, or a link to a route that does not exist, never surfaces. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; a full-graph pass on rampstack.co is schedulable as written in the near term. Status flips to validated when that run record links here. + +## Boundaries + +- Corpus Integrity and Correction owns whether a claim is true; this workflow owns whether the structure around it (links, canonicals, share metadata) is sound. +- Post-Deploy Live Verification owns the per-deploy check of the routes a change touched; this is the periodic full-graph pass across every route. +- Content Pipeline with Prove Gates checks a single draft's metadata and links at publish (its Phase 3); this audits the whole graph after the fact. diff --git a/workflows/migration-with-verification.md b/workflows/migration-with-verification.md new file mode 100644 index 0000000..ca91b0c --- /dev/null +++ b/workflows/migration-with-verification.md @@ -0,0 +1,175 @@ +# Migration with Verification + +``` +name: Migration with Verification +slug: migration-with-verification +tier: forward-deployed (operations) +role: fde +status: template +score: 47 (demand 4, pain 5, differentiation 4, usability 4, connectors 4) +intent: migrate a property with the redirect map gated for completeness, old and + new parity proven, cutover staged behind a human, and recovery watched + against baselines pre-registered before the flip +when to use: moving a property to a new domain, platform, or URL structure, where old + URLs carry traffic and rankings worth keeping +when not to use: verifying a single deploy on an unchanged property (Post-Deploy Live + Verification); a traffic drop with no known cause (Traffic-Drop Triage) +validation note: gated on a real migration of a designated property; none is planned, so + it holds at template until such a migration occurs +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read # both the old and the new property + - capability: search-performance.read + access: read # the pre-cutover baselines + - capability: repo.change + access: write-held # the redirect map and any fix land as held changes +``` + +Read-only until the held redirect map and fixes. The cutover itself, the DNS and platform actions, is a human phase; nothing here flips a property. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- Crawl access to both the old property and the new one. +- The complete list of old URLs, from the old sitemap, the crawl, and the search-performance export together, because any one alone misses pages. +- Search-performance history for the old property, to pre-register baselines before cutover. +- The cutover runbook's platform access (DNS, hosting), held by the human who performs it. + +## Phases + +### Phase 1: Inventory and pre-register the baselines · lane: convergent (Tholo) + +Skills: content-migration, seo-technical +Capability class: migration.baseline (substitute equivalents if off-catalog) +Input: the old property (crawl.read), its search-performance history, the new property's planned structure +Run: + + Invoke content-migration to inventory the old property and seo-technical to + read its structure. Build the complete old-URL list as the union of the + sitemap, the crawl, and the search-performance export, because any single + source misses pages. Then PRE-REGISTER the baselines before cutover: the + traffic and ranking levels per key segment, and the recovery metric (which + segment, back to what level, measured over what window) written down now, + while the old property is still live. Produce the inventory and the + pre-registered baseline record. + +Output artifact: the complete old-URL inventory and the pre-registered baseline record (traffic, rankings, the recovery metric), dated before cutover +Done when: every old URL is inventoried from the three sources unioned, and the baselines and recovery metric are recorded before any cutover step +Fails look like: baselines chosen after cutover. A recovery metric written once traffic has moved is fitted to whatever happened and will always find recovery; the baseline means something only if it predates the flip. + +### Phase 2: Redirect-map completeness gate · lane: gate (Basano) + +Skills: content-migration +Capability class: migration.redirect-completeness (substitute equivalents if off-catalog) +Input: the complete old-URL inventory; the new property's URL structure +Run: + + Invoke content-migration against the old-URL inventory. For EVERY old URL, not + a sample, assign one of three dispositions: a 301 to a specific new URL, + gone-with-intent (a 410 or an intentional removal with the reason recorded), + or explicitly dropped with a written rationale. The gate is completeness: an + old URL with no disposition is a fail, and the map is not done until the + uncovered count is zero. Report the map with its coverage and every + disposition's evidence. This gate reports and fixes nothing. + +Output artifact: the redirect map (every old URL, its disposition, the rationale for drops) with a zero-uncovered coverage report +Done when: every old URL in the inventory carries a disposition, the uncovered count is zero, and each drop has a recorded rationale +Fails look like: a sampled map. A redirect map spot-checked instead of completed passes review and drops the long tail, and the long tail is where the accumulated ranking equity quietly lived. + +### Phase 3: Parity audit, old versus new · lane: gate (Basano) + +Skills: seo-technical, seo-onpage +Capability class: migration.parity-audit (substitute equivalents if off-catalog) +Input: the old and new properties (crawl.read); the redirect map +Run: + + Invoke seo-technical and seo-onpage against matched old and new URLs. For each + mapped pair, check parity: title and meta, the canonical target, structured + data, the presence of the content the old page ranked for, and the + internal-link graph around it. Flag any new page that lost metadata, changed a + canonical away from itself, dropped structured data, or is missing content its + old counterpart carried. Report parity per pair with the evidence. Report only. + +Output artifact: the parity report (each mapped pair, per-check verdict, the evidence) +Done when: every mapped pair has a parity verdict across metadata, canonical, structured data, content presence, and internal links +Fails look like: parity by URL existence. A new URL that returns 200 can still have lost the title, the schema, and half the body the old one ranked for, and a check that stops at "the page exists" certifies a page that will not hold the ranking. + +### Phase 4: Staged cutover · lane: divergent (human) + +Skills: launch-runbook +Capability class: migration.cutover (write-held runbook; the actions are human) +Input: the passing redirect map and parity report +Run: + + Invoke launch-runbook to author the staged cutover runbook: the ordered DNS + and platform steps, each stage with a checkpoint that must pass before the + next. Then a person performs the cutover per the runbook; DNS and platform + changes are production state changes and stay human. The human records which + stage was executed when, and holds at any checkpoint that fails rather than + proceeding. + +Output artifact: the staged cutover runbook, and the human's record of each stage executed with its checkpoint result +Done when: the cutover stages are executed per the runbook with each checkpoint recorded, or the cutover is held at a failed checkpoint +Fails look like: a big-bang cutover with no checkpoints. Flipping everything at once removes the one thing staging buys, the chance to catch a broken stage before the next one lands on top of it. + +### Phase 5: Post-cutover verification · lane: gate (Basano) + +Skills: none; the engine is the Post-Deploy Live Verification workflow, executed as written +Capability class: deploy.live-verify (delegated to Post-Deploy Live Verification) +Input: the new property; the redirect map +Run: + + Run Post-Deploy Live Verification as written against the new property's touched + and blast-radius routes. Do not restate its procedure here: it owns the + discriminator value, the build-identity read, and the two-fetch production + discipline, and this phase inherits all of it. Then add the migration-specific + check: verify the redirect map fires on the live property, the highest-traffic + and the gone-with-intent URLs first, each old URL landing on its mapped target + with the right status code. Report the live-verification verdict and the + redirect verdicts together. + +Output artifact: the Post-Deploy Live Verification closure for the new property plus the live redirect verdicts from the map +Done when: Post-Deploy Live Verification closes VERIFIED on the new property and the mapped redirects fire live with the right status codes, or the discrepancies are filed with their evidence +Fails look like: declaring the migration done at the DNS flip. DNS resolving is not the property migrated; the redirects, the parity, and the live render are, and only production fetches prove them. + +### Phase 6: Monitoring window against the pre-registered baselines · lane: gate (Basano) + +Skills: seo-rank-tracking, seo-traffic-diagnosis +Capability class: migration.monitor (substitute equivalents if off-catalog) +Input: the pre-registered baseline record; the new property's search-performance and ranking data on a cadence +Run: + + Invoke seo-rank-tracking and seo-traffic-diagnosis against the new property on + a fixed cadence through the monitoring window. Measure the affected segments + against the baselines pre-registered in Phase 1, and report the trajectory. + Declare the migration recovered only when the pre-registered recovery metric + holds across its pre-registered window, not on the first good week. If the + trajectory contradicts the baseline, the migration has a regression and it + routes out of this workflow. + +Output artifact: monitoring reports on cadence, and a closure record when the pre-registered recovery condition holds +Done when: the pre-registered recovery condition holds across its window and the closure is recorded, or the window breaks baseline and the regression is routed to Traffic-Drop Triage +Fails look like: closing on the first good week. Migration traffic is noisy in the weeks after cutover, and a recovery declared on one datapoint reopens a month later as a mystery with the trail already cold. + +## Failure modes + +- The redirect map sampled instead of complete (Phase 2's failure): the long tail dropped, and with it the accumulated equity. +- Baselines chosen after cutover (Phase 1's failure): a recovery metric fitted to what happened always finds recovery. +- Declaring success at the DNS flip (Phase 5's failure): cutover is not migration; the redirects, the parity, and the live render are. +- The old property's cache serving past cutover: after the flip, some request paths keep serving the old property's cached render for a while, so a page can look migrated on one fetch and stale on another. Verification covers cookie-less vantages and does not stop at the first clean fetch; a clean read from one path is a sample, not the verdict. This is the split-serving class at its worst possible moment, when two properties are briefly both answering. +- Parity by URL existence (Phase 3's failure): a 200 that lost the title, the schema, and half the body. +- A big-bang cutover (Phase 4's failure): no checkpoint to catch a broken stage before the next lands on it. + +## Worked example + +Pending. Populates when this workflow is executed as written on a real migration of a designated property; none is planned, so it holds at template until such a migration occurs. The split-serving pattern in the failure modes generalizes production incidents on an unnamed property, where a render persisted on one request path after a change while another path served current data; that lesson informs Phase 5's vantage discipline but is not validation evidence. Status flips to validated when a run record links here. + +## Boundaries + +- Post-Deploy Live Verification is Phase 5's engine: this workflow runs it as written against the new property and adds the redirect checks, rather than restating its procedure. +- Traffic-Drop Triage takes over when the monitoring window breaks baseline: a post-cutover regression that contradicts the pre-registered recovery metric is a diagnosable drop, and that workflow owns the diagnosis. diff --git a/workflows/post-deploy-live-verification.md b/workflows/post-deploy-live-verification.md new file mode 100644 index 0000000..2d8ed29 --- /dev/null +++ b/workflows/post-deploy-live-verification.md @@ -0,0 +1,160 @@ +# Post-Deploy Live Verification + +``` +name: Post-Deploy Live Verification +slug: post-deploy-live-verification +tier: forward-deployed (operations) +role: fde +status: template +score: 53 (demand 5, pain 5, differentiation 4, usability 5, connectors 5) +intent: merged-is-not-live as a procedure: prove that what production serves + is what was approved, on every route that matters, before the change + is called done +when to use: after every merge that changes anything a user or crawler sees; as + the standing final step of any pipeline that ships +when not to use: pre-merge checking (that is CI Prove-Gate Wiring's territory); + content-claim truth (Corpus Integrity and Correction); a live + regression from an already-promoted lane (Incident Response and + Lane Demotion, which this workflow's failures feed) +gap note: this workflow's core is the tier's largest DECLARED CATALOG GAP; + most phases are inline procedure with qa-testing and seo-technical + as the nearest anchors. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only for fixes the verification surfaces +``` + +Verification is read-only. Fixes it surfaces land held; deploy-platform actions (promoting, purging, redeploying) are human actions on the platform, outside these connectors by design. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The production domain, and the list of routes the change touched plus the routes that share templates or data with them. +- A way to read which build produced a served page (a deployment id, build hash, or asset fingerprint in the rendered HTML; every modern host embeds one). +- The approved state: the merged content, metadata, and values the pages are supposed to show. + +## Phases + +### Phase 1: Capture the expected state · lane: convergent (Tholo) + +Skills: qa-testing (nearest anchor; procedure inline) +Capability class: deploy.expected-state (declared catalog gap) +Input: the merged change; the route list +Run: + + From the merged change, record what production should now show, per + route: the content values that changed, titles and meta descriptions, + canonical URLs, structured data, and at least one DISCRIMINATOR VALUE + per route: something this deploy changed that the previous build could + not be showing (new copy, a new derived count, a version string). Add + the blast-radius routes: pages sharing the template, layout, nav, or + data source with the changed ones, because deploys regress neighbors. + Record the newest deployment or build identifier the platform reports. + +Output artifact: the expected-state sheet (route, expected values, discriminator value, expected build id) +Done when: every touched and blast-radius route has expected values and a discriminator +Fails look like: verifying only the changed route. The route you edited is the one you will look at anyway; the regression ships on the sibling route nobody listed + +### Phase 2: Production fetch and identity check · lane: gate (Basano) + +Skills: qa-testing, seo-technical (anchors; procedure inline) +Capability class: deploy.live-verify (declared catalog gap) +Input: the expected-state sheet +Run: + + Fetch each route's PRODUCTION URL: not a preview, not a staging domain, + not localhost, and not a browser with a warm cache. For each route, + record: the discriminator value present or absent; the build identifier + the served page embeds; title, meta description, canonical, social-share + metadata, and structured data against expected; and status codes on the + route and its internal links. Fetch twice with a short gap; a CDN can + serve different edges different builds, and one fetch is a sample, not + a verdict. Report per route: VERIFIED (discriminator present, build id + current, values match), STALE (old build id or missing discriminator), + or WRONG (current build, unexpected values). + +Output artifact: the live report (verdict, evidence, build id per route, both fetches) +Done when: every route on the sheet has a verdict from production fetches +Fails look like: trusting the deploy dashboard. The platform saying the deployment succeeded is a claim about the build, not about what a given route serves; tool-reported success is not verified state, and only the rendered production URL is ground truth + +### Phase 3: Discriminate the failure class · lane: convergent (Tholo) + +Skills: none; this is the decision table (procedure inline; the discriminator pattern generalizes production incidents on an unnamed property) +Capability class: deploy.failure-discriminate (declared catalog gap) +Input: the live report, when any route is STALE or WRONG +Run: + + Apply the decision table. ALL routes stale on the same old build id: + the deploy never promoted; the fix is platform-side promotion, not code. + SOME routes current and SOME stale: route-level cache or incremental + render staleness; the stale HTML was generated under the old build and + is being served past the new deploy; the fix is a targeted purge or + revalidation of those routes, and if a purged route goes stale again, + its background regeneration is failing and the platform's function logs + for that route are the next read. Routes CURRENT but WRONG: the defect + merged; the fix is code, as a held change. State which class the + evidence supports and what evidence would distinguish it further if + ambiguous. + +Output artifact: the failure-class finding with its evidence +Done when: every non-verified route has a named failure class or a named ambiguity with the next check specified +Fails look like: purge-and-hope. Purging a cache without knowing whether the deploy promoted treats two different diseases with one drug; when it happens to work, nothing was learned, and when it does not, the next hour is spent purging harder + +### Phase 4: Route the fix · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the failure-class finding +Run: promotion, purge, revalidation, and redeploy are performed by a person + on the platform (these are production state changes, and they stay + human). Code defects land as held changes (repo.change) for normal + review. The human records what action was taken and against which + failure class. +Output artifact: the action taken, recorded against the finding +Done when: the action for every non-verified route is taken or explicitly deferred +Operated-layer note: in an operated deployment the finding and the action land as an agreement-log row; a promoted lane whose deploys repeatedly land STALE is exactly the post_merge_outcome signal Incident Response and Lane Demotion consumes +Fails look like: the verification performing the platform action itself. The read side of this workflow can be trusted precisely because it cannot touch what it measures + +### Phase 5: Re-verify and close · lane: gate (Basano) + +Skills: qa-testing (anchor; procedure inline) +Capability class: deploy.live-verify (declared catalog gap) +Input: the expected-state sheet; the actions taken +Run: + + Re-run Phase 2 on every route that was not VERIFIED, same discipline: + production URL, discriminator, build id, two fetches. The change closes + only when every route on the sheet reads VERIFIED. Record the closure + with the final build id per route. If this workflow runs as a pipeline's + standing final step (it should), the closure record is the pipeline's + definition of done. + +Output artifact: the closure record (all routes VERIFIED, final build ids, timestamps) +Done when: all routes VERIFIED on production, and the closure record exists +Fails look like: closing at merge, or closing on the first good fetch after a purge. Done is a property of what production serves, held across both fetches, on every route on the sheet + +## Failure modes + +- Preview verification: any fetch that is not the production URL proves nothing about production. +- Single-fetch verdicts: CDN edges disagree; two fetches minimum, and disagreement between them is itself a finding. +- Dashboard trust: deploy success and served state are different facts (Phase 2's inline failure). +- Sibling blindness: verifying only the edited route (Phase 1's inline failure). +- Purge-and-hope (Phase 3's inline failure). +- Missing discriminator: without a value only the new build can show, a stale page that happens to look right passes; the discriminator is what makes VERIFIED falsifiable. +- Merge-time closure: the change is done when production says so, not when the repo does. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property. The verification core generalizes real post-merge passes on rampstack.co (rendered-state checks, cross-link verification, build-identity reads across two merges in one day); the failure-class decision table additionally generalizes production incidents on an unnamed property, including a route serving a twelve-day-old render while its sibling served current data. Status flips to validated when a run record links here. + +## Boundaries + +- CI Prove-Gate Wiring owns pre-merge gates; this workflow begins where CI ends, because CI runs against the build and this runs against the world. +- Incident Response and Lane Demotion consumes this workflow's repeated failures on promoted lanes; a STALE that recurs is an incident, not a verification note. +- Content Pipeline Phase 5 and Corpus Integrity Phase 5 are this workflow's content-shaped instances; they share the declared gap and the doctrine. diff --git a/workflows/regulated-content-compliance-gate.md b/workflows/regulated-content-compliance-gate.md new file mode 100644 index 0000000..4bb7981 --- /dev/null +++ b/workflows/regulated-content-compliance-gate.md @@ -0,0 +1,128 @@ +# Regulated-Content Compliance Gate + +``` +name: Regulated-Content Compliance Gate +slug: regulated-content-compliance-gate +tier: forward-deployed (operations) +role: fdm +status: template +score: 45 (demand 3, pain 5, differentiation 4, usability 4, connectors 5) +intent: a YMYL pre-publish gate that runs inside the content pipeline for regulated + properties: required disclosures present and placed, every regulated claim + sourced to a citable authority, and prohibited-claim patterns absent +when to use: a regulated or YMYL property (finance, health, legal, and the like) where a + published claim carries real-world consequence +when not to use: an unregulated property (Content Pipeline Phase 3's ordinary gate is + enough); correcting already-published regulated content (Corpus Integrity + and Correction, under both workflows' rules) +gap note: the placement-verification core is a DECLARED CATALOG GAP with seo-technical + as the nearest anchor; that phase is inline procedure. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read # placement verification on the built page +``` + +This gate is read-only: it reads the content pipeline's held drafts and the built page, and reports. A failing gate blocks the merge; it never edits the draft. Waivers are human decisions by the register owner. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The property's regulatory context: the disclosure requirements, the list of citable authorities, and the prohibited-claim patterns for its vertical. +- A register owner: the human accountable for the compliance register and its waivers. +- The content pipeline's held drafts as input; this gate runs inside Content Pipeline Phase 3 for regulated properties. +- A production-equivalent build, because placement is verified on the rendered page. + +## Phases + +### Phase 1: The compliance register · lane: divergent (human) + +Skills: none; the register is written to the property's regulatory requirements and owned by a human +Capability class: compliance.register (human-owned) +Input: the property's regulatory context; the register owner +Run: the register owner writes the compliance register once and approves it: + the disclosure requirements and where each must be placed, the list of + citable authorities a regulated claim may be sourced to, the prohibited-claim + patterns, and the placement rules. The register is the standard every draft + is gated against, so it is authored and human-approved before the gate runs, + not derived per draft. It is versioned, and it carries a review cadence + against its own regulatory sources. +Output artifact: the approved compliance register (disclosures and placements, the authority list, prohibited patterns, the review cadence) +Done when: the register owner has approved the register and its review cadence, and it is versioned +Fails look like: a register derived per draft. A standard invented fresh for each piece is not a standard, and it drifts to whatever the current draft happens to satisfy. + +### Phase 2: The compliance gate · lane: gate (Basano) + +Skills: evidence-based-reviews, editorial-qa +Capability class: compliance.gate (substitute equivalents if off-catalog) +Input: a held draft from Content Pipeline Phase 3; the approved register +Run: + + Invoke evidence-based-reviews and editorial-qa against the held draft, gated + on the register. Check three things and change nothing. Disclosures: every + required disclosure is present. Claims: every regulated claim is sourced to a + specific authority ON THE REGISTER'S LIST, which is authority-list checking, + not source-presence checking; a claim citing some source that is not a listed + authority fails, even though a source is present. Prohibited patterns: none of + the register's prohibited-claim patterns appear. Report a verdict per check + with the evidence. Report only; this gate blocks a merge, it does not edit the + draft. + +Output artifact: the compliance verdict per check (disclosures, authority-sourced claims, prohibited patterns), evidence attached +Done when: the draft carries a verdict on disclosures present, every regulated claim authority-sourced, and prohibited patterns absent +Fails look like: source-presence instead of authority-list checking. A claim with a citation attached passes a lazy check and fails the register when the citation is a blog rather than a listed authority; the presence of a source is not the same as sourcing to an authority. + +### Phase 3: Placement verification on the built page · lane: gate (Basano) + +Skills: seo-technical (nearest anchor; the placement-verification core is a DECLARED GAP, procedure inline) +Capability class: compliance.placement-verify (declared catalog gap; nearest-miss seo-technical) +Input: the built page (crawl.read); the register's placement rules +Run: + + Invoke seo-technical against the BUILT page, not the source. For each required + disclosure, verify it renders where the register's placement rule requires: a + disclosure that exists in the source but renders below the fold, inside a + collapsed element, or on a path the reader does not take, fails placement even + though it is present. Report placement per disclosure against its rule, with + the rendered evidence. Report only. + +Output artifact: the placement report (each disclosure, its required placement, its rendered placement, a verdict) +Done when: every required disclosure has a placement verdict against the register's rule, checked on the built render +Fails look like: verifying placement in the source. A disclosure in the markup that a collapsed accordion hides at render is present to a grep and absent to a reader, and the reader is who the rule protects. + +### Phase 4: Waiver protocol · lane: divergent (human) + +Skills: none; a waiver is the register owner's decision +Input: a compliance failure the team proposes to waive +Run: only the register owner may waive a compliance failure, and a waiver is + never routine. The owner records what was waived, the specific rule, and the + rationale, and the waiver is scoped to the one draft, not the standard. + Repeated waivers of the same rule are a signal that the register is wrong or + the process is, and they surface for review rather than accumulating silently. +Output artifact: the recorded waiver (the rule, the draft, the register owner's rationale), or the confirmation that no waiver was granted +Done when (public gate): every compliance failure is either fixed and re-gated, or waived in writing by the register owner with a recorded rationale +Operated-layer note: in an operated deployment a waiver lands as an agreement-log row with human_verdict = waive and a required human_reason, excluded from the false-pass and false-fail rate computations and reported on its own line (AGREEMENT-LOG.md) +Fails look like: routine waivers. A waiver any reviewer can grant, or one that passes without the register owner and a rationale, turns the gate into a formality the pipeline learns to wave through. + +## Failure modes + +- Source-presence instead of authority-list checking (Phase 2's failure): a citation present but not to a listed authority. +- Disclosure present but mis-placed (Phase 3's failure): rendered below the fold or inside a collapsed element. +- The register going stale against changed rules: a regulatory requirement moves and the register does not; the Phase 1 review cadence on the register itself is the guard. +- Treating this gate as Content Pipeline Phase 3: it is additive, an extra gate for regulated properties, never a replacement for that phase's ordinary pre-publish gate. +- Routine waivers (Phase 4's failure): waivers granted without the register owner, or so often they stop meaning anything. +- Gating the draft but not the built page: passing on source presence and never checking the render is how a compliant draft ships as a non-compliant page. + +## Worked example + +Pending. Populates when this workflow is executed as written on regulated content reaching a designated property; no designated property carries regulated content today, so it holds at template until such content exists on one. Status flips to validated when a run record links here. + +## Boundaries + +- This gate runs INSIDE Content Pipeline with Prove Gates, Phase 3, for regulated properties: it is additive to that phase's ordinary gate, never a substitute, and a regulated draft passes both. +- Corpus Integrity and Correction owns corrections to already-published regulated content; a correction to a regulated claim runs under both this workflow's authority-list rule and that workflow's visible-correction pattern. diff --git a/workflows/revenue-tracking-integrity.md b/workflows/revenue-tracking-integrity.md new file mode 100644 index 0000000..9ae34bf --- /dev/null +++ b/workflows/revenue-tracking-integrity.md @@ -0,0 +1,163 @@ +# Revenue Tracking Integrity + +``` +name: Revenue Tracking Integrity +slug: revenue-tracking-integrity +tier: forward-deployed (operations) +role: fda +status: template +score: 47 (demand 4, pain 5, differentiation 5, usability 3, connectors 4) +intent: a scheduled prove pass over the money path: params surviving redirects, + consent not zeroing attribution, platform and warehouse reconciled, and + monetized links live +when to use: any property that earns through tracked links or events, on a schedule +when not to use: diagnosing a conversion divergence on stable traffic (Conversion-by-Source + Diagnosis); a falling-traffic mystery (Traffic-Drop Triage) +gap note: the money-path map, the consent matrix, and the reconciliation cores are + DECLARED CATALOG GAPS; those phases are inline procedure with + product-analytics-setup as the nearest anchor. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: analytics.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: revenue.read + access: read +``` + +Fully read-only until Phase 5, and Phase 5 only ever produces held changes and a schedule. Platform and merchant changes stay human; nothing in the audit acts on the money path. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The list of monetized link and event classes the property runs (affiliate links, checkout events, lead events). +- Read access to the platform that reports revenue or clicks, and to the analytics and warehouse stores the events land in. +- Enough accrued revenue or click data for a reconciliation window to be meaningful. +- The attribution parameter set: which parameters must survive the redirect chain. + +## Phases + +### Phase 1: Map the money path · lane: convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; the money-path-mapping core is a DECLARED GAP, procedure inline) +Capability class: revenue.path-map (declared catalog gap; nearest-miss product-analytics-setup) +Input: the site (crawl.read), the platform records (revenue.read), and the event definitions +Run: + + Invoke product-analytics-setup's instrumentation discipline. Enumerate every + monetized link and event CLASS, not instance: each affiliate or outbound money + link type, its full redirect chain, the attribution parameters it must carry, + the event it fires, and the platform record that event should become. Map each + class end to end, from the on-page link to the reconciled revenue row. Produce + the money-path map; test nothing yet. + +Output artifact: the money-path map (each class: link, redirect chain, required params, event, platform record) +Done when: every monetized class is mapped from on-page link to platform record, with its required attribution parameters named +Fails look like: mapping link instances instead of classes. Ten thousand affiliate links share a handful of classes, and a map keyed to instances misses the class-wide break while drowning in duplicates. + +### Phase 2: Liveness and parameter survival · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.liveness-check (declared catalog gap; nearest-miss product-analytics-setup) +Input: the money-path map +Run: + + Invoke product-analytics-setup's verification discipline as a gate. Per link + class, fetch a live instance (crawl.read), follow the full redirect chain to + its destination, and assert two things: the link resolves to a live endpoint + (no dead redirect, no parking page, no 404 at the merchant), and the required + attribution parameters arrive intact at the end of the chain, not stripped by + a redirect hop or a canonicalization. Test every class, including the ones + that look fine. Report liveness and parameter survival per class with the + chain as evidence. Report only. + +Output artifact: a liveness-and-survival report per class (resolves live, params arrived, the chain) +Done when: every link class has a liveness verdict and a parameter-survival verdict with its redirect chain recorded +Fails look like: testing one link and trusting the class. One affiliate link resolving does not prove the class resolves, and the broken subset earns nothing while the test stays green. + +### Phase 3: Consent-state matrix · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; the consent-matrix core is a DECLARED GAP, procedure inline) +Capability class: measurement.consent-matrix (declared catalog gap; nearest-miss product-analytics-setup) +Input: the money-path map; the property's consent states +Run: + + Invoke product-analytics-setup's measurement discipline. Build the matrix: + each money event against each consent state the property can be in (granted, + denied, not-yet-decided, and any regional variant). For each cell, confirm + whether the event fires and whether attribution survives. The failure this + catches: a consent state that silently zeroes attribution, so revenue is + earned but recorded as unattributed or not at all. Report the matrix with the + fired-and-attributed verdict per cell. Report only. + +Output artifact: the consent matrix (event by consent state, fired and attributed verdict per cell) +Done when: every money event has a verdict under every consent state the property supports +Fails look like: testing only the granted state. Consent-denied and undecided states are where attribution quietly zeroes, and a matrix that skips them certifies a path that loses money in the states most users are actually in. + +### Phase 4: Reconciliation · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.reconcile (declared catalog gap; nearest-miss product-analytics-setup) +Input: the platform-reported events and revenue (revenue.read); the warehouse-landed events (warehouse.query, bounded) +Run: + + Invoke product-analytics-setup's reconciliation discipline as a gate. For a + bounded window, pull platform-reported events and revenue and the + warehouse-landed equivalents, and reconcile them within a stated tolerance, + per source, not only in total. Flag any per-source row that drifts past + tolerance even when the totals happen to match, because offsetting errors hide + in the total. Every warehouse query carries its date range as a partition + filter. Report the reconciliation per source with the variance. Report only. + +Output artifact: the reconciliation report (platform versus warehouse per source, variance, tolerance verdict) +Done when: every source is reconciled within tolerance for the window, or the per-source variance is flagged with evidence +Fails look like: reconciling totals while per-source rows drift. A matching grand total made of two offsetting errors reads as healthy and is two broken sources wearing a coincidence. + +### Phase 5: Findings triage, held fixes, and the standing cadence · lane: divergent (Krine) then convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.correct (write-held) +Input: the liveness, consent, and reconciliation reports +Run: + + Invoke product-analytics-setup to rank the findings by revenue at risk and + present the plan for a human to approve (the divergent stop). On approval, + land fixes held: a dead link class routed to its owner, a consent-zeroing path + routed to a measurement fix, a reconciliation drift routed to the + instrumentation. Then set the standing cadence: this pass recurs on a schedule + (monthly fits most money paths), so a dead class is caught by the pass, not by + a quarter of missing revenue. Nothing here publishes; platform and merchant + changes stay human. + +Output artifact: a ranked plan, held fixes tied to findings, and the recorded recurring cadence +Done when (public gate): a human has approved the plan, every approved fix is held, and the recurring cadence is scheduled +Operated-layer note: in an operated deployment the ranking and the human's approval land as an agreement-log row (see AGREEMENT-LOG.md) +Fails look like: running this once. A money path is only as sound as its last pass, and the dead link that appears the week after a one-time audit earns nothing until someone notices the gap in the revenue. + +## Failure modes + +- Instance-not-class testing (Phase 2's failure): one link checked, the class assumed. +- Granted-only consent testing (Phase 3's failure): the states where attribution zeroes go unchecked. +- Total-level reconciliation (Phase 4's failure): per-source drift hidden by a matching total. +- One-shot auditing (Phase 5's failure): a dead monetized link discovered by its revenue's absence months later. +- Unbounded reconciliation queries: a warehouse pull with no partition filter, a cost incident on the money path. +- Parameter survival assumed from presence: a parameter present on the link but stripped mid-chain, so the click lands unattributed. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is a prove pass over the affiliate money path on an outdoor-sports content property once its first affiliate data accrues. Status flips to validated when that run record links here. + +## Boundaries + +- Conversion-by-Source Diagnosis assumes this path passes: its Phase 3 is a per-finding spot-check of measurement, and this is the scheduled end-to-end audit of the money path. +- Experiment Loop with Pre-Registered Gates (design v2, publishing later) reads verdicts only as trustworthy as this path; a revenue experiment on a broken money path measures noise. +- Warehouse Data Plane Standup wires the bounded warehouse access this workflow's reconciliation reads through. diff --git a/workflows/run-records/content-pipeline-prove-gates-run-1.md b/workflows/run-records/content-pipeline-prove-gates-run-1.md new file mode 100644 index 0000000..c51d708 --- /dev/null +++ b/workflows/run-records/content-pipeline-prove-gates-run-1.md @@ -0,0 +1,73 @@ +# Content Pipeline with Prove Gates: run record 1, draw length + +This is the validation run record for the "Content Pipeline with Prove Gates" workflow, executed as written on this property (an outdoor-sports content site). One piece moves through the pipeline: the draw-length how-to. Phases 1 to 5 run as written; Phase 6 accrues on cadence and is out of scope for this record. Each phase below is one artifact. + +## Phase 1: Rank the backlog from demand (already complete, cited here) + +- Go item: "how to measure draw length", the first how-to piece. +- Ranking evidence: demand overturned a rangefinder-first assumption. Draw length at roughly 1,200 monthly US searches outranked the how-to candidates it competed with (arrow spine about 1,000; sights about 450; rangefinder how-tos about 10). Write order follows demand; the rangefinder spokes ride as support for the priority money guide rather than leading. +- Difficulty and intent: the property relaunched ranking for nothing, so attainable difficulty (low across this map) was weighted over raw volume; the full ranking method, per-cluster demand numbers, and their capture citations are in docs/research/keyword-content-map.md. The SERP shows calculator intent and no strong article competitor, so the piece supports the existing draw-length calculator tool and the beginner-bow money guide. +- Recorded sequencing decision: draw length first. It is the fit number the beginner path leans on and the piece that feeds the arrows and bows guides, so it earns the front of the queue. +- NeuronWriter brief: briefs/how-to-measure-draw-length-2026-07-08.md (keyword "how to measure draw length", roughly 684-word target, twelve advisory terms, the reader questions, and the competitor set). Coverage against those terms is advisory and never a merge gate. +- The ranking was not re-run for this record; this phase cites the completed selection and stops. + +## Phase 2: Produce the held draft (write-held) + +- Held draft: PR #33 (draft), branch feat/content-draw-length. Nothing published, scheduled, or merged. +- Piece: content/articles/how-to-measure-draw-length.mdx. HowTo schema variant; four real-step H2s that read into the HowTo JSON-LD as steps; the AMO-standard definition and the arrow-length relation as H3 explainers; every factual claim carries its source or derivation inline; internal links to the draw-length calculator, the beginner compound bow guide, and the hunting arrows guide. Body length 680 words, inside the brief's 650 to 800 target. +- Written against: briefs/how-to-measure-draw-length-2026-07-08.md. + +## Phase 3: Pre-publish gate (report only, nothing fixed inside the gate) + +Prove report, verdict per check. The validator is the content-contract check that runs at build time plus the type and lint passes; the rendered audit is the built page inspected on a local production build. + +| Check | Verdict | Evidence | +|---|---|---| +| Content contract (frontmatter, schema, no picks) | PASS | build compiled; required article fields present (title, standfirst, excerpt, author, date); schema is "howto"; no picks apparatus on an article | +| Types and lint | PASS | tsc noEmit clean; eslint reports no errors | +| Every factual claim has a source or derivation inline | PASS | the wingspan-over-2.5 formula is named as the archery wingspan method; the nock-to-grip-pivot plus 1.75 inch definition is attributed to the AMO and ATA standard; the typical 26 to 31 inch range and the 28 to 29 inch adult-male average are stated as derivations from that method and from where stock bows center their adjustment; the half-inch confirmation tolerance matches the calculator's own stated basis. No unsourced statistic appears. | +| Style and phrase rules (STANDARDS: CLAUDE.md and docs/brand/voice.md) | PASS | zero em or en dashes; zero banned phrases; no "not just" construction (grep of the file) | +| Title, meta description, structured data present and consistent | PASS | rendered title is the piece title suffixed with the site name; the meta description is the standfirst; the HowTo JSON-LD is present with four HowToSteps matching the four H2 steps in order, alongside a BreadcrumbList filed under the Articles hub; the canonical is self-referencing | +| Every internal link resolves against the route list | PASS | /tools/draw-length-calculator, /guides/best-compound-bow-for-beginners, /guides/best-hunting-arrows, and /how-we-test each return 200 on the built site, as does the article's own route | + +Gate verdict: all checks pass, no waiver required. Nothing was fixed inside the gate; the draft was authored to the standard in Phase 2. + +## Phase 4: Human review and merge + +- Reviewer: Andy Dunn, the mergedBy on PR #33 +- Verdict: merge (human-verdict vocabulary: merge / reject / revise / waive) +- What changed (proposal to merge): Merged untouched. No revisions between the proposed held draft and the merge; no proposal-to-merge diff. The article content committed once (6389a70); the only later commits on the branch were run-record docs (692cb7e, 110c73e), not content edits. +- Merged at: 2026-07-10T01:41:15Z (UTC), squash-merge, merge commit f4395716 onto main + +## Phase 5: Post-publish live audit (post-merge, on the human's go) + +Run the live audit against the production URL https://bowhuntamerica.com/articles/how-to-measure-draw-length after merge and deploy. Verify per check against the live render, not a preview, staging domain, or cached copy: the rendered content matches what was approved at merge; the canonical is self-referencing; title, meta description, social-share metadata, and the HowTo structured data are present on the live render and match the approved values; every internal link on the live page resolves; and the render is current, confirmed against a value known to have changed at publish. Record the verdict per check and the deployment id. + +- Deployment id: current prerender of the article route; render ETag 52f1e233b9f8c2d1b3c977959aa29d8e, OpenGraph image asset fingerprint e531b1656856773d (content-derived, host-agnostic). +- Live-audit verdict per check: + +| Check | Verdict | Evidence | +|---|---|---| +| Rendered content matches what was approved at merge | PASS | the wingspan method, the AMO and ATA definition, the half-inch confirmation tolerance, the typical 26 to 31 inch range and the 28 to 29 inch adult-male average, and the nock-to-grip references all render on the live page, matching the Phase 2 draft | +| Canonical is self-referencing | PASS | the rendered canonical points to the article's own URL, https://bowhuntamerica.com/articles/how-to-measure-draw-length | +| Title, meta description, social-share metadata, and structured data present and consistent | PASS | rendered title is the piece title suffixed with the site name; the meta description is the standfirst; OpenGraph title, description, and image and the Twitter summary_large_image card, title, and description are present; the HowTo JSON-LD carries four HowToSteps matching the four H2 steps, alongside a BreadcrumbList; the values match the approved article | +| Every internal link on the live page resolves | PASS | all fourteen internal links on the live render return 200, including /tools/draw-length-calculator, /guides/best-compound-bow-for-beginners, /guides/best-hunting-arrows, /how-we-test, and the article's own route | +| Render is current (a value known to have changed at publish) | PASS | the article route serves the full new content that did not exist pre-publish; the page carries the current build's index, follow directive rather than the pre-launch noindex; the render is a current prerender (the ETag and OpenGraph asset fingerprint above) | + +Auto-appearance checks: + +| Check | Verdict | Evidence | +|---|---|---| +| The articles hub lists the piece | PASS | /articles renders the draw-length article's link and title | +| The homepage latest row carries it | PASS | the homepage links /articles/how-to-measure-draw-length in its latest row | +| The start-here draw-length link resolves | PASS | the homepage start-here strip's draw-length entry links /tools/draw-length-calculator, which returns 200 | + +A finding surfaced during this phase, recorded plainly. The audit's external fetch vantage returned a stale pre-launch render of the homepage, an indexing-directive mismatch included, while the article routes served the current build. The failure-class discrimination ran on that signal: production was confirmed healthy from direct vantages, the browser source and a cookie-less fetch from a clean path, both of which return the current build with index, follow, the Articles and Tools nav, and the draw-length piece in the latest row. The stale copies were attributed to an intermediary fetch cache on an external fetch path rather than to a production regression, so the audit exercised the vantage-and-staleness branch of its decision table on a real signal and closed with the production-healthy conclusion and its evidence. + +## Phase 6: Outcomes and the refresh trigger (not part of this record) + +Outcomes accrue on a cadence and decay flags re-enter the Phase 1 ranking. Out of scope for this run record. + +--- + +Run status: Phases 1 to 5 are complete. The pre-publish gate passed with no waiver, the draft merged unchanged with no proposal-to-merge diff, and the post-publish live audit passes against the production URL with every check green and the three auto-appearance checks confirmed. This is the completed validation record for the Content Pipeline with Prove Gates workflow: the run record that links from the workflow file to flip its status from template to validated. Phase 6 accrues on cadence and is out of scope for this record. diff --git a/workflows/traffic-drop-triage.md b/workflows/traffic-drop-triage.md new file mode 100644 index 0000000..2ce7bfb --- /dev/null +++ b/workflows/traffic-drop-triage.md @@ -0,0 +1,193 @@ +# Traffic-Drop Triage + +``` +name: Traffic-Drop Triage +slug: traffic-drop-triage +tier: forward-deployed (operations) +role: fda +status: template +score: 51 (demand 5, pain 5, differentiation 4, usability 4, connectors 4) +intent: diagnose an organic traffic drop with a disciplined decision tree, + evidence per branch, before anyone acts on it +when to use: organic traffic is down and the team is about to do something about it +when not to use: routine performance review (use Conversion-by-Source Diagnosis); + a known deploy broke something (use Incident Response and Lane + Demotion); paid traffic changes (off-catalog) +validation note: gated on a showcase-designated property experiencing a diagnosable + drop; the pattern generalizes a real production diagnosis on an + unnamed property +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: analytics.read + access: read + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only if Phase 4 routes to a technical fix +``` + +This workflow is read-only until Phase 4, and Phase 4 only ever produces held changes. Nothing in the triage acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- At least one demand-side data source (search-performance export) AND one behavior-side source (analytics events), because the single most valuable discriminator in the tree is whether they disagree. +- Enough history to compute a baseline: the same period last year if seasonality is plausible, or at minimum several stable weeks pre-drop. +- The deploy log or release history for the drop window. + +## Phases + +### Phase 1: Pin the drop · lane: convergent (Tholo) + +Skills: seo-traffic-diagnosis +Capability class: traffic.baseline (substitute equivalents if off-catalog) +Input: search-performance and analytics data spanning the drop and the baseline window +Run: + + Invoke seo-traffic-diagnosis against the traffic data. Establish, with + numbers: when the drop started (day precision), its magnitude vs the + pre-drop baseline, and its shape across segments: which page templates, + which query classes, which devices, which countries, which traffic + sources. Do not explain the drop yet. Produce the drop profile only. + +Output artifact: a drop profile (start date, magnitude, segment breakdown) +Done when: the profile states when, how much, and where, each with a number +Fails look like: averaging over segments. A sitewide average of minus 30 percent can be one template at minus 90 and everything else flat, and those are different diagnoses; the segment breakdown is the whole point of this phase + +### Phase 2: Run the branches · lane: gate (Basano) + +Five branches, every one checked, none acted on. Each produces evidence for or against; skipping a branch because another already looks guilty is the failure this phase exists to prevent. + +**Branch A, tracking breakage.** +Skills: product-analytics-setup (nearest anchor; the breakage-detection core is a DECLARED GAP, procedure inline) +Run: + + Cross-check the two data sources for the drop window: if search-performance + impressions and clicks are steady while analytics sessions dropped, the + traffic did not fall, the measurement did. Check: the analytics tag present + and firing on affected templates (crawl.read the live pages), consent-flow + changes in the window, filter or property configuration changes, and + whether the drop starts at a deploy boundary rather than a demand boundary. + +**Branch B, technical regression.** +Skills: seo-site-health-audit, seo-technical +Run: + + Invoke seo-site-health-audit and seo-technical against the affected + segments. Check: robots directives and noindex on affected templates, + canonical correctness, status codes and redirect chains, sitemap presence, + render-blocking or hydration failures on the live pages, and whether any + of these changed at a deploy inside the drop window. + +**Branch C, algorithm-update timing.** +Skills: seo-traffic-diagnosis +Run: + + Compare the drop start date against the published update timeline. Check + the drop's shape against the update class: sitewide vs template-scoped vs + query-class-scoped losses point at different update types. Timing + correlation alone is not a diagnosis; require shape agreement too. + +**Branch D, seasonality and demand shift.** +Skills: seo-keyword +Capability class: demand.trend +Run: + + Query the warehouse for the same period in prior years (bounded date + ranges). Invoke seo-keyword against the affected query classes: did the + demand itself fall? A drop that tracks the category's demand curve is not + a site problem, and treating it as one wastes a quarter. + +**Branch E, SERP displacement.** +Skills: seo-rank-tracking, seo-competitor +Run: + + Invoke seo-rank-tracking on the affected queries: are positions held or + lost? Positions held with clicks down points at SERP-feature displacement + (check the affected queries' current result layout). Positions lost points + at a competitor or a relevance change; invoke seo-competitor to identify + who took them and with what. + +Output artifact: a branch evidence table: five branches, evidence for, evidence against, per-branch confidence +Done when: all five branches have evidence recorded, including the branches that came back clean +Fails look like: stopping at the first guilty-looking branch. Real drops are frequently compound (an update lands the same week a consent banner breaks measurement), and a one-branch diagnosis on a compound drop fixes half the problem while the other half compounds + +### Phase 3: Diagnosis · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the drop profile and the branch evidence table +Run: + + Rank the candidate causes by evidence strength, stating per-branch + confidence and explicitly noting compound possibilities. Present the + ranked diagnosis with the evidence attached. Recommend nothing yet. + Stop for the human. + +Output artifact: a ranked diagnosis with per-cause confidence and the compound read +Done when: a human has confirmed the diagnosis or sent specific branches back for deeper evidence +Operated-layer note: in an operated deployment, the engine's ranked diagnosis and the human's confirmation or override land as an agreement-log row; diagnosis agreement over time is what earns this lane trust +Fails look like: the diagnosis arriving pre-merged with the treatment. The moment the diagnosis says "and therefore we should," the human is reviewing a plan, not a finding, and anchoring does the rest + +### Phase 4: Route the response · lane: convergent (Tholo) + +Skills: routing per diagnosis; the responses live in their owning workflows +Input: the confirmed diagnosis +Run: + + Route each confirmed cause to its owner: technical regression -> a held + change (repo.change) with the specific fix; tracking breakage -> a held + fix to the measurement path, plus an annotation on the drop window so + the record shows measurement loss, not traffic loss; update-class losses + -> the content-quality program (Corpus Integrity and Correction, Content + Pipeline refresh triggers), never a quick technical counterattack; + demand decline -> a strategy note, not a fix; SERP displacement -> + targeted format or coverage work through the Content Pipeline. Every + response lands held; nothing merges from inside the triage. + +Output artifact: held changes and routed work items, each tied to its diagnosed cause +Done when: every confirmed cause has a routed response or an explicit decision to accept it +Fails look like: fixing inside the triage. The triage's authority is diagnostic; the moment it merges its own fixes, the diagnosis and the treatment share an author and the verification story collapses + +### Phase 5: Recovery watch · lane: gate (Basano) + +Skills: seo-rank-tracking, seo-traffic-diagnosis +Input: the pre-registered recovery metric (set it now, before watching: which segment, back to what level, measured how) +Run: + + On a fixed cadence, measure the affected segments against the + pre-registered recovery metric and the pre-drop baseline. Report + trajectory per diagnosed cause. Declare recovery only when the + pre-registered condition holds across the pre-registered window, not + on the first good week. + +Output artifact: recovery reports on cadence; a closure record when the pre-registered condition holds +Done when: recovery is declared against the pre-registered condition, or the diagnosis is reopened because the trajectory contradicts it +Fails look like: victory on one good week. Traffic is noisy; a recovery declared on a single datapoint reopens as a mystery a month later, now with the trail cold + +## Failure modes + +- First-plausible-branch tunnel vision (Phase 2's inline failure; the discipline is that clean branches get recorded too). +- Measurement loss recorded as traffic loss: the record must say which it was, or every future baseline is quietly wrong. +- Timing-only update attribution: correlation with an update date without shape agreement is a coin flip wearing a citation. +- Treatment anchoring: diagnosis and recommendation delivered as one artifact (Phase 3's inline failure). +- Unpre-registered recovery: the metric chosen after watching begins always finds recovery. +- Compound drops resolved as single causes: fix half, and the remaining half now looks like the fix failed. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property experiencing a diagnosable drop. The decision tree generalizes a real production diagnosis (a mass deindexation timed to a core update, root-caused to content quality rather than technical failure, on an unnamed property); that incident informs the branches but is not validation evidence. + +## Boundaries + +- Incident Response and Lane Demotion owns drops caused by the pipeline's own promoted changes (a post-merge regression is an incident with a known suspect, not a mystery). +- Conversion-by-Source Diagnosis owns conversion problems on stable traffic; this workflow owns the traffic itself. +- Corpus Integrity and Correction and the Content Pipeline own the content-quality responses this workflow routes to; the triage never edits content. diff --git a/workflows/warehouse-data-plane-standup.md b/workflows/warehouse-data-plane-standup.md new file mode 100644 index 0000000..c4d7e6c --- /dev/null +++ b/workflows/warehouse-data-plane-standup.md @@ -0,0 +1,176 @@ +# Warehouse Data Plane Standup + +``` +name: Warehouse Data Plane Standup +slug: warehouse-data-plane-standup +tier: forward-deployed (operations) +role: fde +status: template +score: 43 (demand 4, pain 4, differentiation 3, usability 4, connectors 5) +intent: stand up the data plane the tier reads from: exports first, two stores, + read-only bounded access, cost governance, and an always-on sensing layer +when to use: day zero of a forward-deployed engagement, before any workflow that + reads metrics +when not to use: a stack whose warehouse, exports, and governance already exist (start + with the workflow that needs the data); a one-off query (this is the + standing plane, not a query) +validation note: the occasion is the search-console bulk-export and warehouse enablement + session on a showcase-designated property, already on the critical path +gap note: the two-store standup, the access-wiring, and the verification cores are + DECLARED CATALOG GAPS; those phases are inline procedure with + data-warehouse-experimentation as the nearest anchor. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: analytics.read + access: read +``` + +This workflow stands up read-only access and wires no write path. Enabling the exports and provisioning the stores are platform actions a person performs; the engines never gain a write tool on this plane. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A warehouse you can create datasets in, with a billing project. +- Admin access to the search-console and analytics properties whose exports you will enable. +- An operational store separate from the warehouse, or the ability to provision one. +- The access controls to grant a scoped, read-only service identity. + +## Phases + +### Phase 1: Enable the exports · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the list of properties in scope; the search-console and analytics accounts +Run: a person enables the search-console bulk export and the analytics + warehouse export (the native daily-table exports) on every property in + scope, and records the enablement date per property. This is the one + time-sensitive action in the standup: the exports do not backfill, so the + history starts the day the export is enabled and the clock only runs + forward. Turn them on before any other step. +Output artifact: the exports enabled per property, with the enablement date recorded +Done when: every in-scope property has both exports enabled with a recorded start date, confirmed in the source consoles +Fails look like: doing this last. Every day the exports are off is a day of history that will never exist, and no later step can recover it. + +### Phase 2: Separate the two stores · lane: convergent (Tholo) + +Skills: data-warehouse-experimentation (nearest anchor; the two-store standup core is a DECLARED GAP, procedure inline) +Capability class: warehouse.standup (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the enabled exports; the provisioned warehouse and operational store +Run: + + Invoke data-warehouse-experimentation's warehouse-shape discipline. Stand up + two stores with one boundary rule: the metric warehouse holds metric history + (the export tables and their derivations), the operational store holds run + records, decisions, and the agreement log. Pick the warehouse region once and + match it across both exports, because it cannot be changed later without a + migration. Nothing that answers "what did the engines and humans decide" goes + in the warehouse; nothing that answers "what happened to the numbers" goes in + the operational store. Record the boundary as written policy. + +Output artifact: the two stores stood up, the region fixed, and the store-boundary policy recorded +Done when: both stores exist, the region matches across exports, and the boundary policy names which data lives where +Fails look like: one store doing both jobs. A single store for metrics and decisions couples query cost to operational writes and loses the separation the whole plane depends on. + +### Phase 3: Wire read-only access with mandatory bounds · lane: convergent (Tholo) + +Skills: data-warehouse-experimentation (nearest anchor; the access-wiring core is a DECLARED GAP, procedure inline) +Capability class: warehouse.mcp-wire (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the metric warehouse; the identity and access controls +Run: + + Invoke data-warehouse-experimentation's access discipline. Wire the engines' + read path through a read-only interface (a managed warehouse MCP server plus a + thin domain layer) under a scoped service identity with dataset-scoped read + and deny-by-default elsewhere. Encode the query-correctness rules the raw + tools lack: the mandatory date range pushed down as a partition filter on + every call, and any source-specific offset (search-console positions are + zero-based, so average position is computed with the offset). A call without a + date range is rejected, not run. No write tool is present on this path. + +Output artifact: the read-only access layer, the scoped identity, and the bounds-and-offset rules encoded in the domain layer +Done when: every warehouse call goes through the bounded read path, an unbounded call is rejected, and the identity carries no write scope +Fails look like: bounds enforced by convention instead of code. A partition filter that is supposed to be there is absent on the one query written under deadline, and that is the query that scans the full history. + +### Phase 4: Cost and quota governance · lane: gate (Basano) + +Skills: data-warehouse-experimentation (nearest anchor; procedure inline) +Capability class: warehouse.cost-governance (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the wired access layer; the warehouse's billing and quota controls +Run: + + Invoke data-warehouse-experimentation's cost discipline as a gate. Issue an + unbounded query and confirm it is rejected; issue a bounded query and confirm + it scans only the requested partitions. Set a budget alert and a quota ceiling + on the billing project. Report the enforcement result and the alert + configuration per source. Change nothing about the access layer here; report + what holds and what does not. + +Output artifact: a governance report (bounds-rejection confirmed, partition scan confirmed, budget alert and quota set) +Done when: an unbounded query is confirmed rejected, a bounded query is confirmed to scan only its partitions, and a budget alert exists +Fails look like: an unbounded scan reaching the warehouse. It is a cost incident waiting for a cron job, and it bills for the whole history every time it runs. + +### Phase 5: Stand up the sensing layer · lane: convergent (Tholo) + +Skills: monitoring-and-alerting, analytics-strategy +Capability class: sensing.standup (substitute equivalents if off-catalog) +Input: the metric warehouse with at least one series accruing +Run: + + Invoke monitoring-and-alerting to define the sensing layer and analytics-strategy + to decide what is worth sensing. Per series, set a freshness threshold and a + movement threshold sized to that series' own cadence, a cadence check that + fires when an expected update is late, and an anomaly flag on a schedule. Each + threshold is derived from the series' own history, never copied from another + series. Emit the sensing definitions and the schedule; the layer flags and + never acts. + +Output artifact: the sensing definitions per series (freshness, movement, cadence, anomaly) and the schedule +Done when: every live series has thresholds derived from its own history and a scheduled check, and the layer only flags +Fails look like: thresholds copied between series of different cadences. A daily series' movement band applied to a weekly one alarms on every normal week and trains the team to ignore it. + +### Phase 6: Verification pass · lane: gate (Basano) + +Skills: data-warehouse-experimentation (nearest anchor; procedure inline) +Capability class: warehouse.verify (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the wired plane; one known query per source +Run: + + Invoke data-warehouse-experimentation's verification discipline as a gate. + Round-trip one bounded query per source through the read path: a + search-console query, an analytics query, and a warehouse derivation, each + with a date range, each returning the expected shape against a value known by + hand. Confirm the position offset is applied where it should be. Report pass + or fail per source with the returned evidence. Report only. + +Output artifact: a verification report (one bounded round-trip per source, expected-versus-returned, offset confirmed) +Done when: each source returns the expected shape through the bounded path, or the discrepancy is filed with its evidence +Fails look like: verifying the warehouse holds data without verifying the read path returns it correctly. The tables can be perfect while the domain layer drops the offset, and every downstream number inherits the error. + +## Failure modes + +- Exports enabled last: history that never exists (Phase 1's failure, the load-bearing one). +- One store, both jobs: metric history and operational decisions in a single store, coupling cost to writes and losing the boundary. +- Unbounded scans: a warehouse call with no partition filter (Phase 4's failure), a cost incident waiting for a cron job. +- Copied sensing thresholds: bands moved between series of different cadences (Phase 5's failure), which alarms on normal variation. +- Region drift: exports landing in mismatched regions, which forces a migration to join them. +- Read path unverified: trusting the tables without proving the domain layer returns them with the offsets applied. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is the search-console bulk-export and warehouse enablement session on an outdoor-sports content property, already on the critical path. Status flips to validated when that run record links here. + +## Boundaries + +- Data Surface Integrity (design v2, publishing later) consumes the series this workflow stands up; this owns the plane, that owns the freshness and consistency of what renders from it. +- Conversion-by-Source Diagnosis and Revenue Tracking Integrity read through the bounded access this workflow wires; each states its own warehouse bounds and inherits them here. +- Content Pipeline with Prove Gates ranks from the demand data this plane serves; the export enablement here is the prerequisite its demand source assumes.

`, `	` correctly with `scope` attributes +- Form inputs have `` associated via `for`/`id` or `aria-labelledby` + +1.3.2 Meaningful sequence (A) +- Reading order makes sense without CSS +- Audit check: disable CSS, read the page top to bottom + +1.3.3 Sensory characteristics (A) +- Instructions don't rely solely on shape, size, color, or position +- Audit check: avoid "click the green button" or "the button on the right" + +1.3.4 Orientation (AA) +- Content does not restrict view to a single orientation (portrait or landscape) + +1.3.5 Identify input purpose (AA) +- Form fields collecting user information use `autocomplete` attributes correctly + +### 1.4 Distinguishable + +1.4.1 Use of color (A) +- Color is not the only way information is conveyed +- Audit check: check error states, status indicators, chart elements + +1.4.2 Audio control (A) +- Audio that plays automatically for more than 3 seconds has pause/stop control + +1.4.3 Contrast minimum (AA) +- Normal text contrast ratio at least 4.5:1 +- Large text (18pt regular or 14pt bold) at least 3:1 +- Audit check: contrast checker on every text/background pair + +1.4.4 Resize text (AA) +- Text can be resized to 200% without loss of content or functionality +- Audit check: zoom to 200% in the browser, verify usability + +1.4.5 Images of text (AA) +- Use real text, not images of text, except for logos or where customization is essential + +1.4.10 Reflow (AA) +- Content can be presented without horizontal scrolling at 320px viewport +- Audit check: resize to 320px, verify no horizontal scroll + +1.4.11 Non-text contrast (AA) +- UI components and graphical objects at least 3:1 contrast ratio against adjacent colors +- Audit check: borders, icons, form field outlines, focus rings + +1.4.12 Text spacing (AA) +- No loss of content or functionality when text spacing is increased to specific minimums +- Audit check: apply line-height: 1.5, letter-spacing: 0.12em, word-spacing: 0.16em, paragraph-spacing: 2x font size + +1.4.13 Content on hover or focus (AA) +- Hover/focus tooltips can be dismissed, hovered, and persist until dismissed + +--- + +## Principle 2: Operable + +### 2.1 Keyboard accessible + +2.1.1 Keyboard (A) +- All functionality available from keyboard +- Audit check: navigate the entire site without a mouse + +2.1.2 No keyboard trap (A) +- Focus can always be moved away from any component using keyboard alone +- Audit check: open every modal, dropdown, widget; verify Tab can leave + +2.1.4 Character key shortcuts (A) +- If single-character keyboard shortcuts exist, they can be turned off, remapped, or only active on focus + +### 2.2 Enough time + +2.2.1 Timing adjustable (A) +- Time limits can be turned off, adjusted, or extended (with exceptions for real-time and essential) + +2.2.2 Pause, stop, hide (A) +- Auto-updating content can be paused or stopped (with exceptions for essential) + +### 2.3 Seizures and physical reactions + +2.3.1 Three flashes or below threshold (A) +- Nothing flashes more than 3 times per second + +### 2.4 Navigable + +2.4.1 Bypass blocks (A) +- Skip link present at the top of the page +- Or, use proper landmarks (` `, ` `, ` `, ` `) + +2.4.2 Page titled (A) +- Each page has a unique, descriptive `` + +2.4.3 Focus order (A) +- Focus order matches visual and logical reading order + +2.4.4 Link purpose in context (A) +- Link purpose is clear from the link text alone, or from text + immediate surrounding context +- Avoid "click here," "read more," "learn more" without context + +2.4.5 Multiple ways (AA) +- Multiple ways to find content (sitemap, search, navigation menu) + +2.4.6 Headings and labels (AA) +- Headings and labels are descriptive + +2.4.7 Focus visible (AA) +- Keyboard focus indicator is visible +- Audit check: Tab through the page; can you always see where focus is? + +### 2.5 Input modalities + +2.5.1 Pointer gestures (A) +- Multipoint or path-based gestures have single-point alternative + +2.5.2 Pointer cancellation (A) +- Down-event does not trigger action; action triggers on up-event or has way to abort + +2.5.3 Label in name (A) +- Accessible name (for screen readers) contains the visible label text + +2.5.4 Motion actuation (A) +- Motion-triggered functionality has UI alternative and can be disabled + +--- + +## Principle 3: Understandable + +### 3.1 Readable + +3.1.1 Language of page (A) +- Page language declared in HTML: `<html lang="en">` + +3.1.2 Language of parts (AA) +- Inline foreign-language passages marked: `<span lang="fr">...</span>` + +### 3.2 Predictable + +3.2.1 On focus (A) +- Receiving focus does not change context (no auto-submit, no unexpected navigation) + +3.2.2 On input (A) +- Changing a setting does not automatically change context unless user is warned + +3.2.3 Consistent navigation (AA) +- Navigation appears in the same relative order across pages + +3.2.4 Consistent identification (AA) +- Components with the same function are identified consistently + +### 3.3 Input assistance + +3.3.1 Error identification (A) +- Errors are identified and described in text (not just color or icon) + +3.3.2 Labels or instructions (A) +- Labels or instructions provided for inputs requiring user input + +3.3.3 Error suggestion (AA) +- When errors occur and suggestions are known, suggestions are provided + +3.3.4 Error prevention (legal, financial, data) (AA) +- For pages causing legal commitments or financial transactions: submissions are reversible, checked for errors, OR confirmed before final submission + +--- + +## Principle 4: Robust + +### 4.1 Compatible + +4.1.1 Parsing (A) [removed in 2.2 but still in 2.1] +- Markup is well-formed (no duplicate IDs, properly nested elements) + +4.1.2 Name, role, value (A) +- For all UI components, name and role can be programmatically determined; states, properties, and values can be set +- Use semantic HTML, ARIA where needed + +4.1.3 Status messages (AA) +- Status messages can be programmatically determined through role or properties so they can be announced by assistive technology +- Use `role="status"`, `role="alert"`, or `aria-live` + +--- + +## Audit check summary + +For each criterion, the audit needs to: + +1. Identify the requirement (what does WCAG ask for?) +2. Test against the site (does the site meet it?) +3. Document failures (which pages, which elements, what's wrong) +4. Specify the fix (what specific change resolves it) +5. Assign severity (P0 critical, P1 important, P2 minor, P3 polish) +6. Estimate effort (small, medium, large) + +A complete audit covers all 30+ AA criteria. Most sites fail 5 to 15 of them on first audit. Don't try to fix all at once. Sequence by severity and impact. + +--- + +## What WCAG does NOT cover + +WCAG is a floor, not a ceiling. Some accessibility considerations are outside its scope: + +- Cognitive accessibility nuances (reading level, attention, memory) - some basics in 3.1, but limited +- Audience-specific needs (the cognitive support a user with dyslexia needs vs. a user with autism) +- Mental models (whether the navigation makes sense to your specific audience) + +For these, supplement WCAG with usability testing including users with disabilities, and with specific design patterns aimed at cognitive accessibility. diff --git a/dist/pi/.agents/skills/ads-creative-development/SKILL.md b/dist/pi/.agents/skills/ads-creative-development/SKILL.md new file mode 100644 index 0000000..7fb0a7b --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/SKILL.md @@ -0,0 +1,231 @@ +--- +name: ads-creative-development +description: "How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting." +category: marketing +catalog_summary: "Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter" +display_order: 2 +--- + +# Ads Creative Development + +A senior creative strategist's playbook for producing ad creative that performs. + +Performance creative is a different discipline from brand creative. Brand work optimizes for memorability, emotional resonance, and distinctive identity. Performance creative optimizes for stopping the scroll, communicating value in three seconds, and producing a click. Both matter. Mixing them up costs money. Brand creative running as performance ads bleeds budget; performance creative running as brand ads erodes equity. + +This skill is the discipline that produces performance creative without diluting brand. It assumes you know your audience and offer (see `paid-media-strategy`). It assumes you have brand-voice guidance (see `brand-voice`). The hard part is the systematic production of variations that test cleanly and ship without manual approval bottlenecks, and that is what is here. + +When to use this skill: producing ad creative for paid campaigns, planning a creative testing cycle, diagnosing creative fatigue, or auditing why creative is not converting. + +--- + +## What this skill is for + +This skill spans creative production, hook patterns, testing methodology, and fatigue diagnosis. It does not cover paid media strategy (use `paid-media-strategy`), result interpretation (use `ads-performance-analytics` once it ships), or brand voice authoring (use `brand-voice`). Pair this skill with the relevant integrations microsite for platform-specific MCP details and example prompts. + +The audience is an ad creative producer, a growth marketer responsible for creative testing, or an agency producing creative at scale. The voice is tactical. There is no "consider every option." Performance creative has shape, and a senior practitioner can map a brief to a production-ready variation matrix in an afternoon. + +--- + +## Performance vs brand creative + +The two disciplines optimize for different metrics. Brand creative optimizes for memorability, distinctiveness, and emotional resonance over months. Performance creative optimizes for scroll-stop in 1 second, value comprehension by 5 seconds, and click by 15. + +The shared layer. Both should reflect brand voice. Both should look like they came from the same brand. The difference is structure, pacing, and where the creative effort concentrates. + +The failure mode. Most agency creative tries to do both and does neither well. The brand video that runs as a 60-second performance ad has a strong narrative arc and zero CTR. The performance ad that ignores brand voice converts but trains the audience to not recognize the brand. The fix is not to compromise; it is to produce both, in their respective formats, with shared voice and divergent structure. + +A worked example. A premium coffee brand running a 60-second YouTube awareness ad gets to build the world: cinematography, the founder's hands, slow-pour rituals, music that sets a mood. That same brand running a 15-second Meta Reels performance ad gets 1 second to stop the scroll (a visual pattern interrupt: the steam rising from a cup, fast cut, brand logo dropping in), 4 seconds to clarify the offer (the new flavor, the price, the deal), 8 seconds for social proof (three customer-style testimonials, fast cuts), and 2 seconds for CTA (shop now, end card with logo). Same voice. Different structure. Different pacing. Different creative effort distribution. + +--- + +## Hook patterns: the first 3 seconds + +The biggest lever in performance creative. If the hook fails, no amount of body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. The hook is the whole game until the body justifies why the user kept watching. + +Twelve hook patterns work consistently. Detail in [`references/hook-pattern-library.md`](references/hook-pattern-library.md). + +1. Problem-agitate-solve. Open with the problem the audience feels. Agitate by naming the consequence. Solve with the offer. Works when the audience recognizes the pain. +2. Direct callout to audience. "If you are a B2B founder running paid ads..." Triggers self-identification. Works when the audience is narrow and self-aware. +3. Contrarian claim. "Stop using lookalike audiences." Hooks attention by violating expectation. Works when the audience has heard the conventional wisdom too often. +4. Result-led. "How we cut CAC 40% in 30 days." Specific number, specific timeframe. Works when the result is real and documented. +5. Curiosity gap. "The mistake 80% of marketers make..." Promises a payoff after the gap. Works when the gap is real; clickbait without payoff trains the audience to scroll past. +6. Social proof at top. "Used by 10,000+ teams." Validation before pitch. Works when the proof is impressive enough to do the heavy lifting. +7. Visual pattern interrupt. A surprising visual that does not match the platform's usual feed flow. Works on TikTok and Reels where the pattern is fast and the interrupt is louder. +8. Question that hits intent. "Tired of paying $400 for project management software?" The question pre-qualifies the audience. Works when the question matches a real search query the audience has typed. +9. Number-led. "3 changes that doubled our ROAS." Lists trigger the brain's pattern-completion instinct. Works for educational content; less so for product ads. +10. Personal story open. "Last year I was burning $50K a month on Meta ads with no return..." First-person specificity is hard to skip. Works when the story is real and the conclusion is action-relevant. +11. Comparison. "X vs Y: which actually works." Pits two options against each other. Works when the audience is in evaluation mode. +12. Behind-the-scenes / process. "How we onboard a new client in 7 days..." Demystifies the work. Works when the process is the differentiator. + +For each pattern, the anti-pattern is the same: a hook that does not actually hook. Generic openings ("In today's world...", brand-logo cards, slow zooms over title cards) train the audience to scroll past. The first second is for the hook. The brand can wait. + +--- + +## Format selection + +Different formats fit different combinations of audience, platform, and offer. + +- Static image. Best for simple value props, retargeting, and quick test cycles. Lowest production cost. Limited room for narrative. +- Carousel. Best for multi-feature products, educational content, and B2B SaaS. Each card carries one idea; users swipe through at their own pace. Strong for considered purchases. +- Video (in-feed). Best for demonstration, story, and broad audiences. Higher production cost. Performance correlates strongly with hook quality. +- UGC-style video. Best for trust building, social proof, and lower production cost. Looks like an ordinary user filmed it. Especially strong on TikTok and Reels. +- Stories or Reels (vertical 9:16). Best for TikTok, Instagram, and Snap. Native to the platform's primary surface. Skipping anything not vertical here is leaving performance on the table. +- Spark Ads (boosted organic). Best for TikTok. Promotes an existing organic post as an ad. Retains organic engagement signals; consistently outperforms pure paid creative on TikTok. + +The decision rule. Match format to platform native style and to audience consumption pattern. Detail in [`references/format-decision-matrix.md`](references/format-decision-matrix.md). + +--- + +## Video pacing + +Video performance correlates more with pacing than with production value. A well-paced phone-shot video outperforms a poorly-paced agency-produced spot. Specific guidance for the 15-second performance video. + +\| Time window \| Job \| +\|---\|---\| +\| 0 to 1s \| Hook. Visual pattern interrupt plus audio hook. \| +\| 1 to 3s \| Clarify what this is. Brand and offer registered. \| +\| 3 to 7s \| Value proposition. The problem-solution moment. \| +\| 7 to 12s \| Social proof or demonstration. Show, do not just tell. \| +\| 12 to 15s \| CTA. End card with logo and call to action. \| + +Anything past 15 seconds in a performance video is awareness territory. Performance creative should resolve by 15s. + +Platform variations. TikTok performs at 15 to 30 seconds; the platform tolerates longer because the audience is in a longer dwell mode. Meta In-Feed performs at 15s. YouTube Shorts at 15 to 60s. Long-form YouTube at 30s+ for awareness, with the value prop still front-loaded. + +--- + +## Variation systems + +The systematic way to produce 20 to 50 ad variations from one core concept without manual creative authoring per variation. + +The decomposition. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. + +- 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. +- Most are not worth shipping. The matrix narrows to 20 to 40 variations the team will actually run. +- Asset library structure: organize by concept, not by date. `concepts/launch-2026/hooks/`, `concepts/launch-2026/bodies/`, etc. + +Naming convention. Use a structured naming system so the analyst can join performance data back to creative components. Example: `launch2026_meta-reel_hookA_bodyB_ctaC_v1`. The analyst pulls the report, joins on the naming components, and identifies which hook is winning across body and CTA combinations. + +Worked example in [`references/creative-variation-templates.md`](references/creative-variation-templates.md). A half-day production session produces 40 variations from one core concept by using the matrix. Without the matrix, the same 40 variations require five days of authoring overhead. + +--- + +## Sequential testing methodology + +The waterfall. Most teams test everything at once and lose the signal. Sequential testing isolates the variable that matters at each step. + +1. Test hooks first. 5 to 10 hook variants, same body, same CTA, same format. The hook is the biggest lever; isolate it first. +2. Winners advance to body testing. Top 2 to 3 hooks each get 5 to 10 body variants. Now you are testing what the audience watches after the hook lands. +3. Winners advance to CTA testing. Top hook plus body combinations each get 3 to 5 CTAs. Smaller search space at this stage; the differences are usually marginal. +4. Winners advance to format testing. Top combinations each render in 2 to 3 formats (vertical video, carousel, static). Catches format-specific drop-offs. +5. Top combos go into evergreen rotation. Two to four winners run on rotation. Refresh on the cadence below. + +The common mistake. Testing all variables at once. Variance compounds; the team cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential is slower but produces real learnings the team can apply to the next campaign. + +Detail in [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md). + +--- + +## Creative fatigue detection + +Fatigue is real. The same audience seeing the same creative six times a week tunes it out, or worse, develops negative associations. Five signals indicate fatigue. + +1. Frequency above 4 to 5 per user per week. Set explicit caps. Defaults are usually too high. +2. CTR declining 30%+ week over week. The creative is no longer fresh to the audience. +3. CPM increasing without audience saturation explanation. The platform is having to bid harder to deliver impressions because engagement signals are weakening. +4. Negative comments increasing. A direct user signal that the audience is irritated. +5. Hide ratio increasing. Meta exposes this as "negative feedback rate." TikTok exposes "not interested" rate. + +Refresh cadence. Weekly for high-spend campaigns ($50K+/month). Biweekly for medium spend. Monthly for low spend. The economics: producing a fresh variant is cheaper than running tired creative for one extra week. + +The decision tree. If a top performer's metrics are still strong but frequency is climbing, ship variants of the same concept (same hook structure, different copy and visuals). If the metrics are dropping, retire the concept and ship a new one. Detail in [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md). + +--- + +## Brand-voice alignment without conversion dilution + +The tension. Brand voice can feel off-brand when squeezed into 15-second ads. The fix is hierarchy, not compromise. + +Voice attributes that survive compression. Tone (playful, serious, expert, irreverent). Cadence (short sentences vs long-form). Vocabulary (industry-specific or accessible). Visual treatment (color, type, motion language). These survive in 15s because they live in the texture of every frame. + +Voice attributes that do not survive compression. Deep narrative arcs. Complex metaphors. Layered humor that requires setup. Long-form storytelling. These need 30s+ of runtime to land. Forcing them into 15s produces diluted versions that read as off-brand. + +The hierarchy. Brand voice in every frame; performance discipline in the structure. The brand voice shows up in tone, cadence, vocabulary, and visual treatment. The performance discipline shows up in pacing, hook strength, and CTA placement. + +A worked example. A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs three creatives. The 60-second YouTube awareness piece has the founder talking to camera, plain language, contrarian framing of the category. The 15-second Meta performance ad has fast cuts, plain language captions on screen, contrarian hook ("Stop overpaying for project management software"), specific value prop, CTA. The static carousel has 6 cards, plain language, contrarian opening card, value prop progression, CTA on the last card. Same voice. Different structure. None feels off-brand to a customer who has seen all three. + +Detail in [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md). + +--- + +## Platform-specific creative norms + +Each platform has native norms. Violating them tanks performance. The fix is producing platform-native, not repurposing. + +Meta (Facebook plus Instagram). In-feed visual hierarchy. Captions on by default (most users watch sound-off). Native-feeling production beats studio production for direct response. Vertical 9:16 for Reels and Stories; 1:1 or 4:5 for in-feed. CTAs above the fold or in first 2 lines of caption. + +TikTok. Vertical 9:16 only. Native-creator aesthetic; phone-shot is the default. Fast cuts every 1 to 2 seconds. Captions for accessibility. Music-driven; trending sounds compound reach but expire fast. Spark Ads (boost an existing organic post) consistently outperform pure paid because they retain organic engagement signal. + +LinkedIn. Professional tone. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. B2B vocabulary is fine; consumer-style copy reads as off-platform. Thought leadership angle works; product pitches feel salesy. + +Google Search. Text-only headlines plus descriptions. Character limits are real constraints (30-character headlines, 90-character descriptions). RSA (Responsive Search Ads) optimization rewards 15+ headline variations and 4+ descriptions; the platform mixes them. + +Google Display and YouTube. Depends on placement. YouTube allows longer narrative (15s to 6m); Display is fast banner-style. Skippable YouTube ads need to earn the next second of attention; non-skippable annoys. + +Detail in [`references/platform-creative-norms.md`](references/platform-creative-norms.md). + +--- + +## Common failures + +Eight patterns recur across creative production work. The short version. + +- "We made a beautiful brand video and ran it as performance." Wrong format and length for the channel. Brand video belongs in awareness; performance ads need the 15-second structure. +- "All our ads use the same hook." Saturation. Ship five to ten hook variants per concept and rotate. +- "Our ads stopped working after 3 days." Fatigue plus narrow audience. Either ship more variants or expand the audience; usually both. +- "We A/B tested 50 ad variations." Too many simultaneous variables. Run sequential tests instead. +- "Creative passes brand approval but underperforms." Brand discipline at the cost of performance discipline. The hierarchy is wrong; voice in every frame, performance in the structure. +- "TikTok ad uses Meta-style production." Platform norm violation. TikTok rejects polished ad creative; phone-shot native wins. +- "Our hooks all start with the brand logo." Kills the first-3-second hook. Brand logo belongs at second 1 to 3 (after the hook lands), not at second 0. +- "We never refresh creative because the old set still works ok." Incremental loss compounds. CTR decay is gradual; the team that does not refresh discovers a 40% performance gap when they finally check. + +--- + +## The framework: 10 considerations for sustainable creative production + +When designing or auditing ad creative, walk these 10 considerations. + +1. Performance vs brand. Name what this creative is optimizing for; do not mix. +2. Hook strength. First 3 seconds. Scroll-stopping. Specific. +3. Format-platform fit. Native to the channel. +4. Pacing. Value prop hits within 5 seconds; CTA by 15s. +5. Variation system. Matrix-based, not ad-hoc. +6. Sequential testing. Hooks, then bodies, then CTAs, then formats. +7. Fatigue monitoring. Frequency, CTR decay, CPM trend, negative feedback. +8. Brand-voice alignment. Voice that survives compression; performance in the structure. +9. Platform creative norms. Vertical for short-video platforms, captions on, native production. +10. Refresh cadence. Weekly to monthly by spend tier. + +The output of the framework is a production plan. A list of variations to ship in the next testing cycle, the testing waterfall to run, the fatigue thresholds that trigger refresh, and the platform-specific norms the variations respect. Three answers from the framework: ship as planned, revise the plan, or stop because a precondition is missing. + +--- + +## Reference files + +- [`references/hook-pattern-library.md`](references/hook-pattern-library.md) - Twelve hook patterns with worked examples and anti-patterns for each. +- [`references/format-decision-matrix.md`](references/format-decision-matrix.md) - Audience-objective context to recommended format with reasoning and common alternatives. +- [`references/creative-variation-templates.md`](references/creative-variation-templates.md) - Matrix-based production system, naming conventions, asset library structure, half-day worked example. +- [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md) - Sequential testing waterfall with per-stage variant counts, durations, and winner-advancement criteria. +- [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md) - Five fatigue signals with thresholds and refresh decision tree. +- [`references/platform-creative-norms.md`](references/platform-creative-norms.md) - Per-platform aspect ratios, lengths, audio expectations, caption norms, and native-aesthetic anti-patterns. +- [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md) - Voice attributes that survive 15-second compression vs those that do not, with a four-format worked example. + +--- + +## Closing: the hook is the whole game + +In performance creative, the hook is the whole game. If the hook fails, no body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. + +Spend the disproportionate creative effort on the first 3 seconds. The rest is delivery. The team that puts 60% of its creative effort into the hook and 40% into everything else outperforms the team that distributes effort evenly. The team that puts 90% of its effort into hooks and 10% into delivery beats both, as long as it ships enough variations for the testing waterfall to find which hooks actually work. + +When in doubt, ship the variant. A weak variant ships; a perfect variant never does. The sequential testing waterfall finds the winners; the variation system makes shipping cheap. The asymmetric cost of inaction is real; the asymmetric cost of shipping a marginal variant is small. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md b/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md new file mode 100644 index 0000000..2be0aa0 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/brand-voice-performance-balance.md @@ -0,0 +1,101 @@ +# Brand voice plus performance balance + +How to keep brand voice intact at 15-second performance scale without diluting conversion. + +The tension. Brand voice often feels off-brand when squeezed into a 15-second ad. The instinct is to compromise: water down the voice for the format, or sacrifice the format for the voice. Both are wrong. The fix is hierarchy. + +--- + +## Voice attributes that survive compression + +Four attributes carry the brand voice in 15 seconds without consuming runtime. + +Tone. Playful, serious, expert, irreverent, warm, blunt. Tone lives in the texture of every frame; it does not need narrative space to land. A blunt brand can write blunt captions in 15 seconds. A warm brand can shoot warm faces. + +Cadence. Short sentences vs long-form. Short and punchy fits the 15-second frame; long sentences need 30+ seconds to land. The brand whose voice is short and punchy is naturally well-fit for performance creative. + +Vocabulary. Industry-specific or accessible. Plain or formal. The brand voice that uses certain words and not others can preserve that vocabulary in any format. + +Visual treatment. Color, type, motion language, photographic style. Visual identity survives in 1 second; it survives in 15. + +--- + +## Voice attributes that do not survive compression + +Three attributes need runtime to land. Forcing them into 15-second performance creates diluted versions that read as off-brand. + +Deep narrative arcs. Hero's journey, character development, story-with-resolution. These need 30 to 60 seconds minimum. A 15-second compression of a narrative is the trailer, not the story. + +Complex metaphors. A brand whose voice relies on extended metaphors needs runtime to set up the metaphor and pay it off. 15 seconds of metaphor is the setup with no payoff; the audience leaves confused. + +Layered humor that requires setup. Jokes that depend on a long setup work in long-form. In 15 seconds the joke is too rushed to land. Punchline-style humor works; setup-dependent humor does not. + +The implication. A brand whose voice is built on narrative depth or complex metaphor will struggle with performance creative. The fix is not to compromise the voice; the fix is to use the appropriate format for the voice. Long-form awareness ads carry the narrative; performance creative carries the tone, cadence, vocabulary, and visual treatment without trying to land the full narrative in 15 seconds. + +--- + +## The hierarchy + +Brand voice in every frame. Performance discipline in the structure. + +Voice in every frame. The tone, cadence, vocabulary, and visual treatment of every clip, caption, and CTA reflects the brand. The audience watching three different ad variations should recognize the same brand across all of them. + +Performance in the structure. The pacing, hook strength, value-prop placement, and CTA placement follow performance norms. Hook in 1 to 3 seconds. Value prop by 5 seconds. Social proof or demo by 7 to 12. CTA by 15. The structure is platform-driven, not voice-driven. + +The two layers do not compete. Voice operates at the texture level; structure operates at the timing level. A blunt brand can be blunt in 1 second (texture) and structured in performance pacing (timing). + +--- + +## Worked example: same voice, four formats + +A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs four creatives. + +### 60-second YouTube awareness piece + +The founder talks to camera. Plain language. Contrarian framing of the category. The opening question hooks; the middle 40 seconds tell the story of why the brand exists; the closing 10 seconds invite the audience to learn more. + +Voice carries because there is runtime. Structure is narrative-led. + +### 15-second Meta Reels performance ad + +Fast cuts. Plain language captions on screen. Contrarian hook in second 1 ("Stop overpaying for project management software"). Specific value prop in seconds 4 to 7 ("$10 per user per month, all features"). Social proof in seconds 8 to 12 ("Used by 10,000+ teams"). CTA in seconds 13 to 15 ("Start your free trial"). + +Voice carries through tone (direct, plain) and visual treatment (consistent typography). Structure is performance-led. + +### 15-second TikTok Spark Ad + +Phone-shot. Creator-style. Plain language captions. Contrarian opening line spoken to camera ("Most project management tools cost too much"). Demonstration in seconds 4 to 9 (creator showing the product on their laptop). CTA in seconds 12 to 15. + +Voice carries through tone and the conversational cadence. Production aesthetic is platform-native (phone-shot, not studio). + +### Static carousel (6 cards) + +Card 1: Contrarian opening ("Most PM tools cost too much"). Card 2: The number ($10/user). Card 3: The features. Card 4: The customer logos. Card 5: The story (one customer who switched). Card 6: CTA. + +Voice carries through plain-language copy and consistent visual treatment. Structure is card-by-card progression, not narrative. + +The check. A customer who has seen all four pieces should recognize them as the same brand. The voice is consistent. The structure is format-appropriate. None of the four feels off-brand. + +--- + +## When voice and performance genuinely conflict + +Two situations where the conflict is real, not solvable. + +The brand voice is built on narrative depth. Some brands (especially heritage brands, premium brands, brands with founders who write long-form) have voices that genuinely require runtime. Performance creative for these brands often works better as static or carousel (where the depth lives in the copy) than as 15-second video (where the runtime is too short for the voice). + +The performance objective requires a tone the brand does not use. Direct response often pushes toward urgency, scarcity, and aggressive CTAs. A brand whose voice is calm and considered will read as off-brand if the performance ad uses high-urgency CTAs. The fix is to push back on the performance team's CTA defaults; calm-and-considered brands can have calm-and-considered CTAs that still convert when the offer is right. + +The default. Resolve the conflict by adjusting the format choice (use static or carousel for narrative-deep brands; use longer awareness pieces alongside performance) or by adjusting the CTA register (calm CTAs for calm brands). Do not compromise the voice; the voice is the long-term asset. Do not compromise the performance; the performance is the short-term revenue. Find the format and register that keeps both intact. + +--- + +## Common mistakes + +Watering down the voice for the format. A brand whose voice is sharp produces a soft 15-second ad to "fit the format." The audience does not recognize the brand; the ad converts marginally; the brand erodes. + +Sacrificing the format for the voice. A brand whose voice is narrative-deep produces a 60-second performance ad with no hook. The audience scrolls past in 1 second; the voice never lands. + +Treating voice and structure as the same axis. Voice is texture; structure is timing. They do not compete unless the voice depends on structure (narrative-led brands), in which case the format choice is the lever, not the voice itself. + +No brand-voice review on performance creative. The performance team produces ads that convert but read as off-brand. A 5-minute brand-voice review on every variation catches the off-brand drift before it ships. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md b/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md new file mode 100644 index 0000000..01f6754 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/creative-variation-templates.md @@ -0,0 +1,123 @@ +# Creative variation templates + +The matrix-based production system. How to produce 20 to 50 ad variations from one core concept in a half-day session. + +The principle. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. The matrix lets you ship dozens of variations from minimal authoring overhead, which is what the sequential testing waterfall requires. + +--- + +## The decomposition + +A single creative is composed of independent components. + +\| Component \| Example \| Authoring cost \| +\|---\|---\|---\| +\| Concept \| Theme or message ("the project management tax") \| High (the strategy work) \| +\| Hook \| First 3 seconds, scroll-stop \| Medium (per variant) \| +\| Body \| The middle 5 to 10 seconds \| Medium \| +\| CTA \| The closing call to action \| Low \| +\| Format \| Vertical video, carousel, static, etc. \| Medium (rendering) \| + +The math. 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. Most are not worth shipping; the matrix typically narrows to 20 to 40 the team will actually run. The point is that authoring 5 hooks plus 4 bodies plus 3 CTAs equals 12 components total, which compose into 60 hook-body-CTA combinations. + +--- + +## Variation matrix template + +A simple spreadsheet that drives the production session. + +\| Concept \| Hook ID \| Body ID \| CTA ID \| Format \| Variant ID \| Status \| +\|---\|---\|---\|---\|---\|---\|---\| +\| launch2026 \| hook_a \| body_a \| cta_a \| meta-reel \| v001 \| drafted \| +\| launch2026 \| hook_b \| body_a \| cta_a \| meta-reel \| v002 \| drafted \| +\| launch2026 \| hook_c \| body_a \| cta_a \| meta-reel \| v003 \| drafted \| +\| launch2026 \| hook_a \| body_b \| cta_a \| meta-reel \| v004 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_b \| meta-reel \| v005 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_a \| tiktok-vertical \| v006 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_a \| static-1x1 \| v007 \| drafted \| + +The status column tracks the production pipeline: drafted, rendered, approved, shipped, paused, retired. + +--- + +## Naming conventions + +Every variation has a structured name so the analyst can join performance data back to creative components. + +``` +{concept}_{platform-format}_{hook}_{body}_{cta}_v{n} +``` + +Examples: + +``` +launch2026_meta-reel_hookA_bodyB_ctaC_v1 +launch2026_tiktok-vertical_hookE_bodyA_ctaA_v3 +launch2026_static-1x1_hookA_bodyA_ctaB_v2 +``` + +The analyst pulls the report, splits the names on the underscore, joins to a master variant table, and reports performance by component. "Hook E is winning across body and CTA combinations on TikTok" becomes a query, not a manual review. + +--- + +## Asset library structure + +Organize files by concept, not by date. + +``` +concepts/ + launch2026/ + hooks/ + hookA-direct-callout.txt + hookB-contrarian-claim.txt + hookC-result-led.txt + hookD-curiosity-gap.txt + hookE-personal-story.txt + bodies/ + bodyA-feature-list.txt + bodyB-customer-story.txt + bodyC-comparison.txt + bodyD-process-walkthrough.txt + ctas/ + ctaA-shop-now.txt + ctaB-start-trial.txt + ctaC-book-demo.txt + visuals/ + hero-product-shot.png + ugc-customer-1.mp4 + founder-camera.mp4 + rendered/ + meta-reel/ + tiktok-vertical/ + static-1x1/ +``` + +Date-based organization rots fast. Concept-based organization composes; the team that runs three concepts a quarter has three folders, each with a clean inventory of components. Six months in, the library is searchable. + +--- + +## Half-day production session worked example + +The goal. Produce 40 variations of one core concept in 4 hours. The team: one creative strategist, one editor, one copywriter. + +Hour 1: matrix planning. Strategist drafts 5 hooks, 4 bodies, 3 CTAs against the concept brief. Copywriter refines language. Output: 12 component scripts. + +Hour 2: visual asset prep. Editor pulls the visual library (hero product shot, two UGC videos, two founder-to-camera takes). Copywriter writes captions per platform. Output: visual atoms ready to compose. + +Hour 3: rendering. Editor renders the matrix using a video editor's template feature (or a tool like Pencil, Vidico Forge, or in-house automation). The hook component swaps in; the body component swaps in; the CTA component swaps in; the format renders per platform. Output: 30 rendered variations. + +Hour 4: review and final renders. Team reviews the 30 outputs, kills the 5 to 10 that fail the smell test, renders the final 10 that need higher-quality cuts. Output: 20 to 25 production-ready variations. + +The math. 12 component scripts plus a half day of editor time produces 20 to 25 variations. Without the matrix, the same 20 to 25 variations require 5 days of independent authoring per variation. + +--- + +## When the matrix breaks down + +Two situations where the matrix is the wrong shape. + +Concept-driven brand work. Awareness creative often does not decompose cleanly. The 60-second YouTube spot is one creative, not a matrix. The hook, body, and CTA are integrated into the narrative. For brand work, drop the matrix and produce one strong piece. + +Highly format-specific creative. A behind-the-scenes TikTok is not a hook plus body plus CTA; it is a single creator's continuous take. Forcing the matrix produces stilted ads that read as agency-produced. For format-native creative, accept that one format produces one creative; do not try to render the same content into static. + +The rule. Use the matrix for performance creative where direct response is the goal. Drop the matrix for awareness, brand, or format-native creative where the integrity of the piece matters more than ship volume. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md b/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md new file mode 100644 index 0000000..c4b52d5 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/fatigue-detection-checklist.md @@ -0,0 +1,110 @@ +# Fatigue detection checklist + +Five signals that creative is fatiguing, with thresholds and a refresh decision tree. + +The principle. Creative fatigue is a real economic cost. The tired ad still spends; it just does not convert. The team that monitors fatigue catches the decay early; the team that does not discovers a 30 to 50% performance gap when they finally check. + +--- + +## The five signals + +### 1. Frequency above 4 to 5 per user per week + +Threshold. Above 4 per user per week for performance ads. Above 5 for awareness ads. + +Why it matters. The same audience sees the same creative too many times. CTR drops, irritation rises, brand association erodes. + +Where to check. Meta Ads Manager: frequency report at the ad-set level. Google Ads: frequency at the campaign level. TikTok: less granular, but available at the ad group level. + +Action. If frequency is climbing past 4, ship variants of the same concept (different copy and visuals, same hook structure). If multiple concepts are all climbing, the audience is too narrow; expand. + +### 2. CTR declining 30%+ week over week + +Threshold. A 30% drop week over week is the alarm. A 10 to 15% drop is normal noise; 30% is a signal. + +Why it matters. The audience is no longer interested in the creative. Continuing to run it spends without producing the click. + +Where to check. Each platform's reporting at the ad level over a 4-week window. Look at the trendline, not just the latest week. + +Action. Refresh the creative within 7 days. If multiple ads in the same audience are dropping simultaneously, the audience is fatigued; rotate audiences as well as creative. + +### 3. CPM increasing without audience saturation explanation + +Threshold. A 25%+ increase over 14 days, with audience size and competition both stable. + +Why it matters. The platform's algorithm is having to bid harder to deliver impressions because engagement signals are weakening. The audience is still there but the platform sees the creative as less relevant. + +Where to check. Each platform's CPM trend. Cross-reference with audience overlap reports and competitor activity (Meta Ads Library, SimilarWeb, etc.). + +Action. Refresh creative. The CPM will recover within 7 to 14 days of fresh creative landing. + +### 4. Negative comments increasing + +Threshold. Comments containing "spam," "stop showing me this," "annoying," or platform-specific negative reactions exceeding 1% of impressions. + +Why it matters. Direct user signal of irritation. The audience is mad; the brand is paying for that anger. + +Where to check. Meta Ads Manager: comments section per ad. TikTok: comments per ad. Less visible on LinkedIn. + +Action. Pull the creative within 24 hours. Negative comments compound; the audience that complains often is the audience that complains to friends. + +### 5. Hide ratio (negative feedback) increasing + +Threshold. Meta exposes "negative feedback rate"; trigger refresh when it exceeds 1.5% of impressions or rises 50% week over week. + +Why it matters. Hide is a stronger signal than scroll-past. The audience is actively rejecting the ad. Platform algorithms penalize creatives with high hide ratios by reducing reach. + +Where to check. Meta Ads Manager: customize columns to expose negative feedback. Other platforms: less direct equivalents (TikTok "not interested" rate is similar). + +Action. Pull the creative immediately. The cost is real: the platform will deliver less of all your ads to that audience as it learns to weight negative signals. + +--- + +## Refresh cadence by spend tier + +\| Monthly spend \| Refresh cadence \| Variants per refresh \| +\|---\|---\|---\| +\| Under $5K \| Monthly \| 2 to 3 \| +\| $5K to $25K \| Biweekly \| 3 to 5 \| +\| $25K to $100K \| Weekly \| 5 to 10 \| +\| Above $100K \| Twice weekly \| 10+ \| + +The economics. Producing a fresh variant costs less than running tired creative for one extra week. At $100K per month, even one day of underperformance is meaningful. Higher spend justifies higher refresh investment. + +--- + +## Refresh decision tree + +When fatigue signals trigger, three options. Pick based on the diagnosis. + +Option 1: variant of working concept. The hook structure is still working but the specific creative is fatigued. Ship 3 to 5 variants of the same concept (different copy, different visuals, same hook structure). + +When. CTR drop with frequency above threshold, but the concept itself was strong (top performer in the testing waterfall). + +Cost. Half-day production session if the matrix is in place. Variants ship within 48 hours. + +Option 2: replace concept entirely. The concept is exhausted. Ship a fresh concept (different hook structure, different angle, different value prop emphasis). + +When. Multiple variants of the same concept are dropping simultaneously, or the concept has been in market for 6 to 12 weeks at high frequency. + +Cost. Full production cycle. Variants ship within 1 to 2 weeks. + +Option 3: full creative rotation. Multiple concepts are tired across the account. The audience is over-saturated. + +When. CPM rising across multiple campaigns, hide ratio climbing across the account, multiple concepts dropping in parallel. + +Cost. Quarterly creative refresh. Plan ahead; do not let the rotation be reactive. + +--- + +## Common mistakes + +Watching only CTR. CTR is a fatigue signal but not the only one. CPM and frequency lead CTR; the team watching only CTR is reactive when leading signals would have caught it 1 to 2 weeks earlier. + +Refreshing too late. Once CTR has dropped 50%, the audience has already developed negative associations. The next creative inherits that fatigue context. Refresh on leading signals (CPM, frequency). + +Refreshing without analysis. Producing fresh creative without understanding what worked about the previous creative. The team ships variants that miss what made the original successful and reverts to baseline performance. + +Ignoring the platform algorithm's cooldown. A new creative variant goes through a learning phase (3 to 7 days). Performance during the learning phase is not representative; do not kill a new variant in week 1. + +Treating all fatigue the same. Audience fatigue is different from creative fatigue. If multiple creatives are all fatigued, the audience is the problem. Rotate audiences, not just creative. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md b/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md new file mode 100644 index 0000000..12b3bf6 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/format-decision-matrix.md @@ -0,0 +1,48 @@ +# Format decision matrix + +Audience-objective context to recommended format. Read top to bottom; pick the row that matches your situation. + +--- + +## The matrix + +\| Context \| Primary format \| Secondary format \| Reasoning and what to avoid \| +\|---\|---\|---\|---\| +\| B2C direct response, fast-scroll platforms (Meta, TikTok) \| Vertical video 9:16, 15s \| Static image (retargeting) \| Native to the feed, scroll-stop in 1s. Avoid horizontal video; it gets letterboxed and ignored. \| +\| B2B SaaS demo or feature explainer \| Carousel \| Vertical video with captions \| Carousel lets users self-pace; B2B audiences are in research mode. Avoid horizontal video for B2B feed placements. \| +\| DTC visual product \| UGC-style vertical video \| In-feed product carousel \| UGC retains organic feel and beats studio production for direct response. Avoid heavily produced product shots; reads as "ad" and gets skipped. \| +\| Trust-led offer (financial, healthcare) \| Static with social proof + carousel \| UGC video with named customers \| Trust requires repeat exposure to credible signals. Avoid moving cuts and music; reads as a pitch. \| +\| Founder-led B2B SaaS \| Founder-to-camera video, 15 to 30s \| Static quote card \| First-person specificity is high-trust. Avoid voiceover with stock footage; reads as agency-produced. \| +\| Education-led content marketing \| Long-form video (60s to 3m) \| Carousel \| Long-form rewards educational content. Use for awareness or top-funnel; not direct response. \| +\| App install \| Vertical video with screen recording \| Static screenshot grid \| Screen recording shows the product in 5 seconds, faster than narration. Avoid feature lists; show the product. \| +\| Local services \| Static image + lead form \| UGC-style customer quote \| Lead capture is the goal; minimize friction. Avoid long video; the audience is conversion-ready. \| +\| Enterprise B2B (>$50K ACV) \| LinkedIn Sponsored Content with carousel or static \| Long-form video for awareness \| Professional tone, slower pacing. Avoid TikTok-style fast cuts; reads as off-platform. \| +\| Retargeting (warm audience) \| Static image with offer \| Short carousel with social proof \| Audience already knows the brand; lead with the offer or social proof, not the brand intro. Avoid full hooks; the audience does not need them. \| +\| Black Friday or peak moment \| Static with discount + countdown \| Vertical video with offer + urgency \| Speed matters in peak; the audience is decision-ready. Avoid long-form storytelling. \| +\| Pre-launch awareness \| Long-form vertical video, 30 to 60s \| Carousel for waitlist \| The audience is curious, not converting. Reward attention with substance. Avoid short performance hooks; they undersell. \| + +--- + +## Decision rules + +Three rules apply across the matrix. + +Match the platform's native style. A 1:1 video on TikTok performs worse than the same video as 9:16 vertical. A horizontal video on LinkedIn performs better than the same vertical, because LinkedIn audiences watch on desktop more than TikTok audiences do. Rules differ; produce per platform. + +Match the audience's consumption mode. Scroll mode (TikTok, Reels) needs hook in 1 second. Research mode (LinkedIn, B2B blogs) tolerates longer pacing. Decision mode (retargeting, peak moments) wants the offer up front and skips the hook. + +Match the offer's complexity to the format's information density. Simple offers (a discount, a free trial) work in static. Complex offers (a multi-feature product, a service with a process) need carousel or video. Forcing a complex offer into static fails because the audience cannot understand what is being offered in 1 second. + +--- + +## Common mistakes + +One format across all platforms. A 16:9 video produced for YouTube does not work on TikTok or Reels. The team that ships one format and adapts crops produces underperforming creative on every platform except the one the format was designed for. + +Format chosen by what is easy to produce. Static is fastest to make; teams default to it even when video would convert 3x better. The cost of one good vertical video is recouped in one strong campaign; the production overhead is real but worth it for high-spend campaigns. + +Format chosen without testing. Most teams pick a format and stick with it. The matrix gives a starting point; the testing waterfall (see `testing-cadence-playbook.md`) gives the real answer for the specific brand and audience. + +Carousel without progression. A carousel is a multi-card story. Each card should advance the narrative or value prop. Six cards of the same image with different text waste the format. + +Vertical video without captions. Most users watch sound-off. A vertical video without captions communicates only its visual; the value prop disappears. Captions are not optional on Meta and TikTok. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md b/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md new file mode 100644 index 0000000..cf7d559 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/hook-pattern-library.md @@ -0,0 +1,157 @@ +# Hook pattern library + +Twelve hook patterns that work consistently in performance creative. For each: what makes it work, when it fits, the anti-pattern, and one or two worked examples. + +A hook is the first 1 to 3 seconds of an ad. If the hook fails, the rest of the creative does not get watched. The hook carries 60% of the performance weight; the body and CTA carry 40%. Spend the creative effort accordingly. + +--- + +## 1. Problem-agitate-solve + +What makes it work. Names the audience's pain in their own language, then makes the consequence vivid, then offers the way out. The structure mirrors how the audience already thinks. + +When it fits. When the audience recognizes the pain and feels it as a real cost. Less effective when the pain is abstract. + +Anti-pattern. Skipping the agitate step. The audience hears the problem named and shrugs because the consequence is not vivid. + +Example. "Spending 4 hours a week on status updates? That is 200 hours a year. (Pause.) StatusBot writes them for you in 5 minutes." + +--- + +## 2. Direct callout to audience + +What makes it work. Triggers self-identification in the first second. The viewer thinks "that is me" and watches. + +When it fits. When the audience is narrow, self-aware, and proud of the identity. Founders, doctors, parents, runners, B2B SaaS PMs. + +Anti-pattern. Calling out an audience that is too broad. "If you are a person on the internet..." triggers nothing. + +Example. "If you are a B2B founder running paid ads with no in-house marketer, this is for you." + +--- + +## 3. Contrarian claim + +What makes it work. Violates expectation. The viewer's brain pauses on the contradiction. + +When it fits. When the audience has heard the conventional wisdom too many times and is exhausted by it. + +Anti-pattern. Contrarian for its own sake. The claim has to be defensible by the body of the ad; otherwise the audience disengages by second 5. + +Example. "Stop using lookalike audiences. Here is the audience strategy that actually scales." + +--- + +## 4. Result-led + +What makes it work. Specific number plus specific timeframe. The brain treats specificity as a credibility signal. + +When it fits. When the result is real and documented. Faked numbers train the audience to scroll past the entire account. + +Anti-pattern. Vague results. "We helped a client grow" produces no curiosity; "we cut their CAC 40% in 30 days" does. + +Example. "How we cut CAC 40% in 30 days for a Series B SaaS with no creative budget." + +--- + +## 5. Curiosity gap + +What makes it work. Promises a payoff after the gap. The viewer stays to find out. + +When it fits. When the gap is real and the payoff is on-topic. Clickbait without payoff trains the audience to scroll past. + +Anti-pattern. Gap without payoff. "The mistake 80% of marketers make..." with no actual mistake named in the body of the ad. Audience feels deceived. + +Example. "The mistake 80% of marketers make on Meta Ads is the one that costs them 30% of their budget every month." + +--- + +## 6. Social proof at top + +What makes it work. Validation before pitch. The audience trusts the offer because someone they trust trusts it. + +When it fits. When the proof is impressive enough to do the heavy lifting. Specific names beat generic numbers when the audience knows the names. + +Anti-pattern. Generic proof. "Trusted by thousands" is filler. "Used by Notion, Brex, and Figma" is signal. + +Example. "Used by 10,000+ teams including Notion, Brex, and Whatnot. Now available for solo founders too." + +--- + +## 7. Visual pattern interrupt + +What makes it work. A surprising visual that does not match the platform's usual feed flow. The eye snaps to it. + +When it fits. TikTok, Reels, Stories. Platforms with fast scroll and high pattern density. Less effective on slower platforms (LinkedIn). + +Anti-pattern. Overproduced visual interrupt that reads as ad. The interrupt has to feel native to the platform; a Hollywood-style pattern interrupt on TikTok reads as "ad" and gets skipped. + +Example. A creator-style cold open: a person on screen, looking confused at their phone, then turning the camera around to show the screen. Two-second hook before the first word. + +--- + +## 8. Question that hits intent + +What makes it work. The question pre-qualifies the audience. The audience that does not match disengages immediately, which is fine. + +When it fits. When the question matches a real search query the audience has typed. "Tired of paying $400 for project management software" works because that is what the audience googles. + +Anti-pattern. Generic questions. "Want to grow your business?" filters nothing. + +Example. "Tired of paying $400 a month for project management software you barely use?" + +--- + +## 9. Number-led + +What makes it work. Lists trigger the brain's pattern-completion instinct. The viewer wants to know all three (or five, or seven) reasons. + +When it fits. Educational content, list-style ads. Less effective for product ads where the offer should be specific. + +Anti-pattern. Too many items. "10 reasons" is too many for a 15-second ad; 3 to 5 is the sweet spot. + +Example. "3 changes that doubled our ROAS in Q4. Number 2 surprised our agency." + +--- + +## 10. Personal story open + +What makes it work. First-person specificity. The brain treats personal stories as data, not pitch. + +When it fits. When the story is real and the conclusion is action-relevant. Founder-led ads especially. + +Anti-pattern. Manufactured stories that read as fictional. The audience can usually tell. + +Example. "Last year I was burning $50K a month on Meta ads with no return. Here is what I changed in 30 days." + +--- + +## 11. Comparison + +What makes it work. Pits two options against each other. The audience in evaluation mode wants the comparison. + +When it fits. When the audience is actively comparing. "X vs Y" search queries are the tell. + +Anti-pattern. Unfair comparisons. The audience smells the spin and discounts the brand. + +Example. "Notion vs Linear: which actually works for engineering teams under 50." + +--- + +## 12. Behind-the-scenes / process + +What makes it work. Demystifies the work. The audience that wonders how something is done watches to find out. + +When it fits. When the process is the differentiator. Agencies, services businesses, niche craft. + +Anti-pattern. Process content that is actually a sales pitch in disguise. Audience disengages. + +Example. "How we onboard a new client in 7 days, end to end, with one PM and no kickoff meeting." + +--- + +## The pattern across all twelve + +Every working hook does the same thing: it makes the next second non-optional. The viewer cannot skip without losing something. Specificity, surprise, identification, curiosity, proof. Different mechanisms; same effect. + +The non-working hooks all do the same thing too: they let the viewer skip with no cost. Generic openings. Brand logo cards. Slow zooms over title text. "In today's world..." The first second is for the hook. The brand can wait. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md b/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md new file mode 100644 index 0000000..cfa0389 --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/platform-creative-norms.md @@ -0,0 +1,111 @@ +# Platform creative norms + +Per-platform creative requirements and unwritten conventions. Each platform has native norms; violating them tanks performance. + +--- + +## Meta (Facebook plus Instagram) + +Aspect ratios. 9:16 for Reels and Stories. 4:5 for in-feed (preferred over 1:1; uses more vertical real estate). 1:1 acceptable. Avoid 16:9 horizontal in feed. + +Length. 15 seconds is the sweet spot for performance. 6-second bumpers work for awareness. Long-form (60s+) only for storytelling formats; performance ads should resolve by 15s. + +Audio. Sound-off is the default. Captions are mandatory. Music is helpful when matched to the platform's audio context (low-fi background, not stock library bombast). + +Captions. On-screen captions for spoken audio. Bold, high-contrast, animated to track delivery. Avoid tiny captions; they are unreadable at scroll speed. + +Native aesthetic. Phone-shot or polished both work. UGC-style outperforms studio for direct response; studio outperforms for awareness. The brand voice and the offer drive which fits. + +Anti-patterns. Horizontal video in feed (gets letterboxed). No captions on spoken audio. Brand logo at second 0 (kills the hook). Slow zoom over title cards. Stock music bombast. Overproduced agency-style cuts that signal "ad" before the value lands. + +What feels native. Real people on camera. Direct address. Specific value props. Social proof named with brand names. Pacing that respects the user's scroll velocity (cuts every 1 to 2 seconds in the first 5 seconds). + +--- + +## TikTok + +Aspect ratios. 9:16 vertical only. Anything else is rejected by the algorithm. + +Length. 15 to 30 seconds for performance. The platform tolerates and rewards longer dwell than Meta. + +Audio. Sound-on is default. Trending sounds compound reach but expire fast. Original audio works. Captions for accessibility, not just for sound-off viewers. + +Native aesthetic. Phone-shot, creator-style. Studio production reads as "ad" and gets skipped. Pencil-and-paper aesthetic, jump cuts, unfiltered backgrounds, daylight. + +Spark Ads. Boost an existing organic post. Retains organic engagement signal. Outperforms pure paid creative; if the brand has organic content performing, this is the format. The Pipeboard and Synter MCPs cover Spark Ad creation; the integrations microsite covers the tactical setup. + +Anti-patterns. Polished agency video. Brand logo at second 0. Voiceover with stock footage. Slow-paced narrative. Music that signals "ad" (cinematic stock library). Anything that does not look like a creator filmed it. + +What feels native. Direct-to-camera creator. Fast cuts (1 to 2 seconds). On-screen captions following the speaker. Trending sounds when they fit. Backgrounds that look like a kitchen or bedroom, not a studio. + +--- + +## LinkedIn + +Aspect ratios. 1:1 or 16:9 for feed. 9:16 vertical works for Stories but Stories has limited reach on LinkedIn relative to other platforms. + +Length. 15 to 60 seconds. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. 30 seconds is a strong default. + +Audio. Sound-off default but sound-on more common than Meta. Captions still recommended. Music optional; many high-performing LinkedIn ads use no music. + +Voice. Professional. B2B vocabulary fine; consumer-style copy reads as off-platform. Thought leadership framing works; product pitches feel salesy. + +Native aesthetic. Founder-to-camera, expert-to-camera, slide-deck style, screen-recording demos. Studio production fine for LinkedIn; the audience is more tolerant of polished production than TikTok. + +Anti-patterns. TikTok-style fast cuts. Bombastic music. Casual or irreverent tone for serious B2B categories. UGC-style production for high-trust offers (financial services, healthcare). Generic "let us help your business grow" copy. + +What feels native. Specific industry vocabulary. Named customers and case studies. Slower pacing. Captions over slides. Founder-led specificity beats agency-style polish. + +--- + +## Google Search + +Format. Text-only headlines plus descriptions plus extensions. + +Character limits. Headlines 30 characters; 15 headline variants for RSA. Descriptions 90 characters; 4 description variants. Path 1 and Path 2 in the display URL: 15 characters each. + +RSA optimization. Provide 15+ headline variants and 4 description variants. The platform mixes them. More variants give the platform more material to optimize against. + +Voice. Direct. Specific. Action-led. The search query is high-intent; the ad's job is to confirm the user is in the right place. + +Anti-patterns. Keyword stuffing in headlines. Generic "we do X" headlines. Same value prop in every headline (the platform cannot test variation). Caps lock entire headlines (rejected). Unsubstantiated superlatives. + +What works. Specific value props per headline ("Free 14-day trial", "Used by 10,000+ teams", "Deploy in 5 minutes"). Question headlines that match search intent. Geographic specificity for local. Price points where they are the differentiator. + +--- + +## Google Display and YouTube + +### Display + +Format. Static or short animated banners across the Google Display Network. + +Anti-patterns. Unhelpful targeting (broad display drives garbage clicks). Vague creative (the audience is not in search mode; they need the value prop fast). + +What works. Retargeting with specific offers. Contextual placements (publisher list filtering). Cart-abandonment creative. + +### YouTube + +Format. Skippable video ads (TrueView), non-skippable, bumper (6s), in-feed video. + +Length. Skippable: 15s to 6m. Non-skippable: 15s. Bumper: 6s. + +Audio. Sound-on default. Captions still recommended for accessibility. + +Native aesthetic. YouTube allows longer narrative; the audience is in dwell mode. Both phone-shot and studio production work depending on context. + +Anti-patterns. Saving the value prop for the unskippable end. Skippable ads need to earn the next second; the value prop has to land in 5 seconds even on skippable. + +What works. First 5 seconds earn the rest. Specific value props. Demonstrations. Skippable with strong hooks routinely outperform non-skippable because the audience self-selects into watching. + +--- + +## Cross-platform principles + +Three rules apply across the matrix. + +Native production beats repurposing. A 16:9 video produced for one platform and cropped for others performs worse than three platform-native pieces. Produce per platform; do not adapt. + +Pacing matches the platform's scroll velocity. TikTok scroll is fast; cuts every 1 to 2 seconds. LinkedIn scroll is slow; longer takes work. Meta is in between. + +Captions everywhere. Sound-off is the default on most platforms most of the time. Spoken audio without captions is wasted audio. diff --git a/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md b/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md new file mode 100644 index 0000000..664b7ac --- /dev/null +++ b/dist/pi/.agents/skills/ads-creative-development/references/testing-cadence-playbook.md @@ -0,0 +1,121 @@ +# Testing cadence playbook + +The sequential testing waterfall. How to find the winning creative without testing 50 things at once. + +The principle. Variance compounds. Testing all variables at once means you cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential testing isolates the variable that matters at each step. + +--- + +## The waterfall + +Five stages. Each stage isolates one variable and advances the winners. + +### Stage 1: Hook test + +Goal. Find which hooks stop the scroll. + +Setup. 5 to 10 hook variants, same body, same CTA, same format. Each variant gets equal budget initially. + +Duration. 7 to 14 days, or until each variant has 50+ conversions or 1M+ impressions, whichever comes first. + +Winner criteria. Top 2 to 3 hooks by CTR (the metric that isolates hook performance) plus conversion rate above the floor. Eliminate hooks with high CTR but low conversion (the click is generated by the hook but the ad does not deliver). + +Output. 2 to 3 winning hooks advance to Stage 2. + +### Stage 2: Body test + +Goal. Find which body copy or middle-section visuals convert best given the winning hooks. + +Setup. Winning hooks times 5 to 10 body variants. Same CTA, same format. If two hooks advanced, that is 2 hooks times 5 bodies equals 10 ad sets. + +Duration. 7 to 14 days, or until each combination has 50+ conversions. + +Winner criteria. Top 2 to 3 hook plus body combinations by conversion rate. CTR is no longer the primary metric; the body is what holds attention after the hook. + +Output. 2 to 3 hook plus body combinations advance to Stage 3. + +### Stage 3: CTA test + +Goal. Find which CTA produces the strongest action given the winning hook plus body. + +Setup. Winning hook plus body combinations times 3 to 5 CTAs. Same format. Differences at this stage are usually marginal; do not over-engineer. + +Duration. 5 to 10 days, or until each combination has 30+ conversions. + +Winner criteria. Top hook plus body plus CTA combinations by conversion rate plus AOV (if value matters). + +Output. 2 to 4 winning combinations advance to Stage 4. + +### Stage 4: Format test + +Goal. Find which format works best for the winning combinations. + +Setup. Winning combinations rendered in 2 to 3 formats (vertical video, carousel, static). + +Duration. 7 to 14 days. + +Winner criteria. Top combinations by conversion rate within each format. Different formats may have different winners; that is fine. Run the winning format per surface. + +Output. 2 to 4 production-ready creatives ready for evergreen rotation. + +### Stage 5: Evergreen rotation + +Goal. Run winners at scale; refresh on cadence. + +Setup. 2 to 4 winners running in rotation. Frequency capping per audience. + +Duration. Ongoing. Refresh creative on the cadence in `fatigue-detection-checklist.md`. + +--- + +## Statistical thresholds + +Two ways to call winners. Pick one and standardize across the team. + +Statistical significance. Run until the winner has 95% confidence (or whatever threshold the team agrees on). Some platforms expose a "significance" indicator; others do not. + +Pre-commit duration plus minimum volume. Decide before launching: "we will run for 14 days, each variant gets at least 50 conversions, top performer wins." This is the simpler, more honest approach for most performance work. The platform's algorithm will not run a clean test under your nose anyway, so trying for high-confidence statistical significance is often overkill. + +The trap. Calling winners on small samples. A variant with 5 conversions and 10% lift over the other looks impressive but is within margin of platform noise. Wait for volume before declaring. + +--- + +## Common mistakes + +Testing too many variables at once. The most common mistake. Six hooks times five bodies times three CTAs times two formats equals 180 ad sets. The platform cannot optimize against that many variants; the team cannot interpret the results. Sequential is slower but produces real learnings. + +Killing variants too early. A variant in the learning phase has not yet converged. The platform's first 3 days of delivery are not representative. Wait at least 7 days before killing. + +Calling winners on CTR alone. A hook can drive high CTR with no conversion follow-through. The hook is doing its job (stopping the scroll) but the body is failing. Use conversion rate as the primary winner criterion; CTR is a hook-quality signal, not a creative-quality signal. + +No exclusion of recent converters from the test audience. Recent converters click ads at higher rates because they are warm; mixing them into the test audience produces false-positive results. Exclude. + +Ignoring fatigue during the test. A variant that wins the test in week 1 because it is new can underperform in week 4 once frequency builds. Test results are read against frequency; high-frequency winners are unreliable. + +--- + +## Per-stage budget guidance + +Rough percentages for the testing budget within a campaign's total spend. + +\| Stage \| Share of testing budget \| +\|---\|---\| +\| Hook test \| 40% \| +\| Body test \| 25% \| +\| CTA test \| 10% \| +\| Format test \| 15% \| +\| Buffer (re-tests, lift checks) \| 10% \| + +The hook test gets the biggest share because it filters the most variants. CTA and format tests are smaller because the differences are usually marginal. + +--- + +## When to break the waterfall + +Two situations. + +Time pressure. A peak moment (Black Friday, product launch) does not allow 6 weeks of sequential testing. Compress: run a hook test concurrently with format test using your best-guess body and CTA. Accept lower confidence in exchange for speed. + +Discovery of an outlier. A hook variant that is winning by 5x at the end of week 1 should not wait for the full 14-day stage. Promote early, but track the long-tail performance to confirm. + +The default is the waterfall. The exceptions are real but rare; do not let "we are on a tight timeline" become the default reason to skip the discipline. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md b/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md new file mode 100644 index 0000000..2bcadc2 --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/SKILL.md @@ -0,0 +1,275 @@ +--- +name: ads-performance-analytics +description: "How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue." +category: marketing +catalog_summary: "Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget" +display_order: 3 +--- + +# Ads Performance Analytics + +A data-team-mentor's playbook for interpreting paid media dashboards without fooling yourself. + +The dashboard is the moment of truth for paid media decisions. The numbers on it determine whether you scale, hold, or kill. They also expose every platform's self-attribution bias, every modeled-conversion shortcut, every cross-platform double-count. Most "scale this campaign" decisions trace back to misreading the dashboard. + +This skill is the discipline that prevents misreading. It assumes the campaign was strategically sound (see `paid-media-strategy`). It assumes the creative was tested properly (see `ads-creative-development`). The hard part is knowing what each number actually means, what it does not, and how to reconcile platform-reported metrics with the truth in your warehouse. + +When to use this skill: any time you are about to scale, kill, or rebudget a campaign based on platform metrics; reconciling platform reports with revenue data; evaluating an agency's reporting; or building a paid media dashboard that will not lie to you. + +--- + +## What this skill is for + +This skill spans paid media result interpretation. It does not cover paid media strategy (use `paid-media-strategy`), creative production (use `ads-creative-development`), or platform-specific tooling (covered in the integrations microsites). Pair this skill with the relevant integrations microsite for platform-specific MCP commands and example prompts. + +The audience is a marketer, growth analyst, agency analyst, or founder evaluating paid media reports. The voice is patient and clinical. There is no "trust the platform's number" or "ignore the platform entirely." Both are wrong. The discipline is knowing which numbers from which platform mean what, and what to reconcile against to make the actual decision. + +--- + +## The result panel: what every paid media platform should expose + +A trustworthy result panel exposes nine things. Anything missing is a signal to treat reported numbers with extra skepticism. + +1. Spend, impressions, clicks. Table-stakes metrics. Should match across platforms within rounding. +2. Conversions with definition and window visible. Not just a count; the definition of what counts as a conversion and the attribution window applied. Without this, the count is unreadable. +3. Attribution breakdown. Last-click vs view-through vs modeled. The mix of how the conversions were credited. +4. Frequency. Impressions per unique user. The fatigue early-warning system. +5. Audience saturation. Where the platform exposes it. A flat audience-saturation curve means there is room to scale; a steep curve means efficiency is dropping. +6. Time series. Daily breakdown to spot novelty effects, fatigue, day-of-week patterns, and exogenous variance. +7. Cost metrics in clear currency. CPC, CPM, CPA, ROAS with the math defined and the currency labeled. Do not assume USD. +8. Conversion path data. Touchpoints before conversion, where available. Tells you whether a campaign is a closer or an opener. +9. Filters, segments, and exports. Without these, the panel is a brochure, not a tool. + +Platforms hide what makes their reporting look weakest. Google PMax hides keyword-level and placement-level data. Meta hides the modeled-conversion share. LinkedIn hides cross-device click paths. Treat hidden metrics as the place to dig. + +--- + +## Platform-reported vs reality + +Every platform's dashboard is optimized to make the platform look effective. This is not a moral failing; it is a structural incentive. Platforms with rosier reporting attract more spend. + +Conversion windows. Meta defaults to 7-day click plus 1-day view. Google defaults to 30-day click plus 1-day view. Different windows, same activity, different reported numbers. If you compare Google's 30-day-click count against Meta's 7-day-click count, you are comparing different definitions and pretending they are the same. + +View-through attribution. Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Treat view-through as a signal of awareness contribution, not as a direct response measurement. The user might have converted from organic search anyway. + +Modeled conversions. When iOS users opt out of tracking, Meta and others statistically model what the conversion would have been. Modeled numbers are educated guesses, not measurements. They are useful for direction; they are not reliable for precision. + +Self-attribution bias. Every platform's pixel fires on conversion and the platform claims credit. If you ran Meta, Google, and TikTok in the same week, all three platforms report your conversions as theirs. Sum-of-platforms is always greater than 100% of actual conversions. + +The discipline. Never report platform-reported numbers as fact in board decks. Always reconcile against the single source of truth (warehouse, GA4, or unified analytics platform). Detail in [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md). + +--- + +## Attribution models in practice + +Six models and one anti-model. None is right. They are all approximations. The discipline is picking one, committing, and reading the others as sanity checks. + +Last-click. Simple, reproducible, undercredits awareness. The conversion is fully credited to the last click before the conversion event. Easy to compute; easy to compare across channels; bad for understanding upper-funnel contribution. + +First-click. Opposite bias. Fully credits the first touchpoint, undercredits closing channels. Useful as a sanity check against last-click; rarely the right primary view. + +Linear. Equal credit across all touchpoints. Gives every channel something. Defensible; not informative. Most useful for board reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. + +Time-decay. More credit to recent touchpoints. Reflects the intuition that recent ads are more influential. Hard to argue against; hard to verify. + +U-shaped (position-based). Heavy on first and last (40% each), light on middle (20% distributed). Honors both opener and closer roles. The default in many MTA tools. + +Data-driven attribution (DDA, Google). Machine-learning model that distributes credit based on observed conversion paths. Opaque; hard to audit. The closest to "right" for digital channels but a black box. + +Marketing mix modeling (MMM). Regression-based, top-down. Uses spend and revenue time series across channels to estimate channel contributions. Requires 2+ years of data. The strongest defense against platform self-attribution because it does not rely on platform-reported conversions at all. + +The anti-model: trusting platform-reported attribution. Each platform's "DDA" or "attributed conversions" is the platform's self-attribution. Sum across platforms exceeds reality. Use platform attribution for in-flight optimization within the platform; use a unified attribution model for cross-channel decisions. + +Practical guidance. + +- Early-stage. Use last-click plus a single guardrail metric (warehouse-attributed CAC). Sophisticated attribution requires data volume you do not have. +- Mid-stage. Data-driven attribution from Google plus GA4, with explicit awareness vs closing channel labeling. +- Mature. MMM as the canonical incremental reference. MTA for in-flight optimization. Last-click for channel-level decisions where ambiguity is acceptable. + +Detail and a decision matrix in [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md). + +--- + +## Multi-platform reconciliation + +The trap. Google says you spent $50K with 800 conversions. Meta says $30K with 600. LinkedIn says $20K with 200. Total reported equals 1,600 conversions. Your warehouse says 950. Where did 650 go? + +The answer. Nowhere. They never existed. Each platform claimed conversions other platforms also claimed. + +The reconciliation pattern. + +- Trust the warehouse for total conversions and total revenue. +- Trust platforms for relative ranking within platform (which campaign won, which audience won). +- Never trust platform sums. +- Compute blended CAC as (total ad spend across platforms) divided by (total new customers from warehouse). Not from platform reports. + +The board-deck pattern. Report warehouse-attributed conversion counts, never platform-summed. Report blended CAC, not channel-by-channel CAC unless explicitly noted as platform-self-attributed. Detail and templates in [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md). + +--- + +## ROAS vs LTV: the time horizon trap + +ROAS is short-term. Revenue from purchases attributed to a campaign in a fixed window, often 7 to 30 days. LTV is long-term. Total customer lifetime revenue. + +Decisions made on ROAS can be wrong if LTV varies by channel. A worked example. + +Meta drives 2.5x ROAS at $40 CAC with $80 LTV. The 7-day-click revenue covers 1.5x payback over the customer lifetime. + +Google drives 1.8x ROAS at $60 CAC with $200 LTV. The 7-day-click revenue covers 3.3x payback over the customer lifetime. + +Google looks worse on ROAS, better on LTV-adjusted return. Allocating budget to Meta because the ROAS is higher is the wrong move. + +The fix. Cohort-based LTV by acquisition channel, updated quarterly. Compare channels on payback period or LTV-CAC ratio, not raw ROAS. The 2x ROAS heuristic is a dangerous shortcut. Same ROAS at different LTVs equals different actual returns. + +The trap that compounds. Performance teams optimize for short-term ROAS because the metric refreshes weekly. Brand and high-LTV channels get cut because their short-term ROAS is lower. Six months later, the brand pipeline has eroded and short-term ROAS itself drops because the cheap channels are saturated. The metric that drove the decision was the wrong horizon. + +--- + +## Cohort analysis vs daily metrics + +Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. + +Three cohort cuts that matter for paid media. + +By acquisition month. Are users acquired in March retaining better than users acquired in January? A declining LTV over rolling acquisition cohorts means recent acquisition is lower quality; the daily metrics will show this two to three months later when the retention starts hurting. + +By acquisition channel. Are users from Meta retaining better than users from Google? Channel-level cohort divergence is the data behind the LTV-vs-ROAS argument. Meta might drive volume at lower LTV; Google might drive lower volume at higher LTV. The cohort tells the story the daily ROAS hides. + +By acquisition campaign. Campaign-level cohort signals. Useful for diagnosing why a campaign that "works" in week 1 produces no recurring revenue. + +The signal to act on. Declining cohort LTV over two consecutive months is the alarm. Pause the channel or campaign before the daily metrics force you to. Detail in [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md). + +--- + +## Statistical noise in performance metrics + +Most "the campaign improved 15% week over week" stories are noise. Real performance changes are 30% or more in metrics that vary 10 to 20% naturally. Below that threshold, you are looking at variance and calling it signal. + +Sources of noise in paid media metrics. + +- Day-of-week effects. B2C tends to weekend dips. B2B tends to weekend gains. A "Monday morning is better" hypothesis often dissolves when day-of-week is normalized. +- Holiday and seasonal effects. Q4 dwarfs most "optimization" effects. A campaign launched in Q4 looks great because of seasonality, not strategy. +- Weather, news, competitor activity. Real exogenous variance. Last week's news cycle can shift CPMs across an entire vertical. +- Pixel fire and reporting delay. Conversions reported on a 7-day click window arrive incrementally. Reading the panel on Monday for last week's performance undercounts. + +The fix. Pre-commit to test duration before drawing conclusions. Use the experimentation discipline from `experimentation-analytics` for any directional change you want to claim is real. The signal-to-noise problem in paid media metrics is the same as the signal-to-noise problem in product experiments; the framework transfers. + +This is where `experimentation-analytics` bridges in. The statistical patterns are the same; the application is different. Read both for the full picture. + +--- + +## Incrementality testing + +The honest test. If we had not run this ad, would we still have gotten the conversion? The number above zero is the incremental contribution. + +Most paid media is 30 to 70% incremental, not 100%. Some is zero. Branded search bidding is often 5 to 20% incremental (most converters would have found you organically). Retargeting is often 20 to 40% incremental (many of those users were going to convert anyway). Prospecting is often 50 to 90% incremental. + +Four methods. + +Geo holdout. Hold one region out from the campaign. Measure the difference in conversions between the holdout region and the matched test region. The cleanest causal test for paid media at scale. + +Ghost bidding (Google). Google's own incrementality tool. Bids on a holdout share of impressions but does not actually serve the ad. Reports incremental conversions. Honest signal; some teams find the math opaque. + +Conversion lift studies (Meta). Splits audiences into test and control. Test sees the ad; control does not. Reports incremental lift. The cleanest within-Meta test. + +PSA tests. Serve some users a public service announcement instead of your ad. Compare conversion rates. Useful for legacy brands with deep budget. + +Incremental rate ranges by channel type are in [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md). The discipline is to run incrementality tests at least quarterly on the highest-spend channels. Without them, you are optimizing against platform-reported attribution that systematically overcounts. + +--- + +## Geo experiments and holdouts + +For paid media specifically, geo-based testing is the most reliable causal method. + +Geo holdout. Turn off paid media in one region. Measure baseline organic conversions. The difference between expected and actual conversions in the holdout region is the incremental paid contribution. + +Geo lift. Scale spend in one region by 2x. See if conversions scale linearly. A linear scale means the channel has headroom. A sublinear scale means saturation; further spend is diminishing returns. + +Switchback. Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. Useful when geo splitting is not feasible. + +Pre-and-post analysis. Launch in a region; measure 30 days before vs 30 days after. Weak design because external factors confound the comparison. Use only when no other test is available. + +The right setup. Matched markets (similar demographics, similar baseline conversion rates). Statistical power calculation upfront (how big a difference can the test actually detect). Pre-committed analysis window (so you do not stop early when the data looks good or wait too long when it looks bad). + +The trap. Calling a geo test successful because of timing-correlated revenue lift. A campaign launched in October will see "lift" because Q4 is starting; without a control region, the lift is not attributable to the campaign. + +--- + +## Platform self-attribution bias + +A specific failure mode worth its own section. + +The mechanism. Platform's pixel fires on conversion. Platform claims credit. The user might have converted from any channel; the platform that loaded the pixel last gets the credit on the platform's own dashboard. + +Why platforms reward this design. More credit on the platform dashboard equals better-looking ROAS equals more advertiser spend. Platforms have no incentive to underreport their own contribution. + +Detection patterns. When platform-reported conversions exceed warehouse-attributed conversions for the same channel by more than 30%, you have heavy double-counting. When sum-of-platform-reports exceeds total conversions in the warehouse, you have cross-platform double-counting. + +The fix. Warehouse as canonical for board reporting. Platform reporting as in-flight signal only. Incrementality tests at least quarterly to keep the channel-attribution honest. + +A worked example. A retargeting campaign in Meta showed 3.5x ROAS for six months. The team scaled spend from $20K to $80K per month. A geo holdout test revealed that 65% of the "conversions" would have happened anyway from organic. Real ROAS adjusted for incrementality was 1.2x, not 3.5x. The campaign got cut and warehouse-attributed CAC dropped 18% in the next quarter. + +--- + +## Common interpretation failures + +Twelve patterns recur in paid media reporting work. Detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "ROAS dropped 20% week over week, kill the campaign." Could be noise. Pre-commit a test window before acting on weekly variance. +- "Meta says 500 conversions, my warehouse says 200, who is right?" Both are wrong; warehouse is closer to truth, Meta self-attributes. Reconcile, do not pick a winner. +- "We turned off Google PMax and conversions did not drop." PMax was harvesting branded search you would have gotten free. Audit branded queries inside PMax. +- "The new campaign hit 5x ROAS in week 1." Likely retargeting hot leads. Check the audience composition before declaring victory. +- "We A/B tested and one creative wins by 12%." Within margin of platform noise. Not significant. +- "Our LTV calculation says this channel is profitable." Check cohort age. Recent cohorts may not have hit LTV yet; the calculation is a projection, not a measurement. +- "The platform says high frequency is fine because conversions are still happening." Fatigue masked by free organic conversions. The campaign is taking credit for conversions that would have happened anyway. +- "Last-click attribution shows Meta at 60% credit." Last-click bias. First-click view of the same data shows different. Pick a model and stick. +- "We scaled spend 5x and conversions only doubled." Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher. +- "Brand campaigns underperform on direct ROAS." They do not have to. Brand impact shows up in other channels' efficiency. Measure brand against brand-search lift, not direct ROAS. +- "ROAS held steady but profit dropped." The mix shifted toward lower-margin products. Channel-level ROAS hides product-mix effects. +- "Agency reported a 4x ROAS month." Whose number? Platform-reported, warehouse-attributed, or model-adjusted? The unit of measurement matters more than the magnitude. + +--- + +## The framework: 12 considerations for trustworthy paid media interpretation + +When reading a paid media dashboard about to inform a decision, walk these 12 considerations. Skipping any of them is how teams ship the wrong call. + +1. Result panel completeness. What is the platform showing vs hiding. +2. Platform-reported vs reality. View-through, modeled conversions, conversion windows. +3. Attribution model. Pick one and read the others as sanity checks. +4. Multi-platform reconciliation. Sum-of-platforms is always inflated. +5. ROAS vs LTV horizon. Short-term metric, long-term impact. +6. Cohort vs daily. Cohort tells the quality story; daily tells the volume story. +7. Statistical noise. Weekly variance, day-of-week, seasonal, exogenous. +8. Incrementality. What would have happened without the spend. +9. Geo and holdout testing. The honest causal test. +10. Self-attribution bias. Platforms claim credit they do not deserve. +11. Decision rule. Pre-committed scale up, hold, or pull back. +12. Single source of truth. Warehouse over platform reporting for board metrics. + +The output of the framework is one of three answers. Scale (the campaign is incremental and unit economics work). Hold (data is ambiguous; gather more before deciding). Kill (the campaign is not incremental enough to justify the spend). + +--- + +## Reference files + +- [`references/metric-definitions-glossary.md`](references/metric-definitions-glossary.md) - CTR, CPC, CPM, CPA, ROAS, LTV, AOV, frequency, reach, impressions, conversion window, view-through, modeled conversion, blended CAC, MER. +- [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md) - Last-click, first-click, linear, time-decay, U-shaped, DDA, MMM. Decision matrix by business stage. +- [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md) - Google PMax black box, Meta iOS impact and Conversions API, LinkedIn 30-day click defaults, TikTok video-completion attribution, programmatic viewability gates. +- [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md) - Geo holdout, ghost bidding, conversion lift, PSA tests, switchback designs. Setup, duration, analysis pattern, expected incremental rates. +- [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md) - Warehouse as canonical, platform as in-flight signal, blended CAC formula, board-deck patterns, reconciliation cadence. +- [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md) - By acquisition month, channel, and campaign. Retention curves, when to act on cohort signals. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it incremental zero + +Most paid media spend is not 100% incremental. Some channels are 70% incremental. Some are 30%. Some are zero, paying for conversions you would have gotten anyway. + +The discipline of accepting that channels can be incremental zero, and pulling spend accordingly, is the single highest-impact skill in paid media analytics. Most accounts have at least one campaign that looks profitable in the platform but is incremental zero in the warehouse. Branded paid search at $4 CPC when the same users find you at position one organically. Retargeting at $0.30 CPC for users who already added items to cart. PMax cannibalizing free brand traffic. + +The discipline of finding those campaigns and killing them is the work. The platform will not tell you. The platform's incentive is the opposite. The warehouse, paired with quarterly incrementality tests, is the only honest source. + +When in doubt about whether a campaign is incremental, run a geo holdout. The two-week test is cheaper than a quarter of unincremental spend. The team that does not run incrementality tests is optimizing against numbers that are systematically wrong, and the size of the error is exactly the size of the budget waste. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md b/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md new file mode 100644 index 0000000..55d3e3f --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/attribution-model-comparison.md @@ -0,0 +1,128 @@ +# Attribution model comparison + +For each major attribution model: definition, fit, bias direction, and a worked example showing how the same activity gets different attribution. + +The principle. No model is right. They are all approximations. The discipline is to pick one as the primary view, read the others as sanity checks, and report against the warehouse rather than against any single platform's view. + +--- + +## The models + +### Last-click + +Definition. Full credit to the last clickable touchpoint before conversion. + +When it fits. Early-stage measurement where simplicity matters more than precision. Final-stage decisions where the closer matters more than the opener. + +When it does not fit. Awareness-channel evaluation. Brands with multi-touch sales cycles. Anything upper-funnel. + +Bias direction. Undercredits awareness channels (display, video, top-of-funnel social). Overcredits closing channels (branded search, retargeting). + +### First-click + +Definition. Full credit to the first touchpoint in the conversion path. + +When it fits. Awareness-channel evaluation. Comparing top-of-funnel sources. + +When it does not fit. Closing-channel evaluation. Performance optimization at the bid level. + +Bias direction. Mirror image of last-click. Undercredits closing; overcredits opening. + +### Linear + +Definition. Equal credit across every touchpoint in the conversion path. + +When it fits. Board-deck reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. Defensible-by-default. + +When it does not fit. Decisions where the marginal contribution of each channel matters. Linear treats first-click and last-click the same; reality usually does not. + +Bias direction. Diffuses credit. Channels that touched the path always get something; channels that drove the conversion do not get more. + +### Time-decay + +Definition. More credit to recent touchpoints. Older touchpoints get progressively less. + +When it fits. When the intuition is that recent ads are more influential. Reasonable for short-cycle B2C. + +When it does not fit. Long sales cycles where the first touchpoint may have been months before the close. Decay underweights the opener. + +Bias direction. Skews toward the closer. Slightly less aggressive than last-click. + +### U-shaped (position-based) + +Definition. 40% credit to first touch. 40% credit to last touch. 20% distributed across middle touches. + +When it fits. When you want to honor both opener and closer roles without flattening to linear. Reasonable default for most B2C. + +When it does not fit. Single-touch paths (awards 80% to a single touchpoint, which is over-attributing). Long paths where the middle touchpoints matter as much as the ends. + +Bias direction. Balances the last-click and first-click views into one number. + +### Data-driven attribution (DDA, Google) + +Definition. Machine-learning model that distributes credit based on observed conversion paths. Compares paths that did and did not convert; assigns credit to touchpoints that correlate with conversion. + +When it fits. Mature accounts with sufficient conversion volume (Google requires 600+ conversions per month for DDA). Cross-channel optimization. + +When it does not fit. Sub-scale accounts. Accounts that need explainability for regulators or boards. The black-box nature is hard to audit. + +Bias direction. Best in class for digital channels where the data is clean. Still suffers from platform self-attribution bias because Google's DDA only sees Google touchpoints. + +### Marketing mix modeling (MMM) + +Definition. Regression-based, top-down. Models the relationship between spend across channels and revenue over time. Typically requires 2 to 3 years of data. + +When it fits. Mature accounts with cross-channel spend at scale. Brands where offline channels (TV, OOH, podcast) contribute. Anywhere platform self-attribution bias is a real concern. + +When it does not fit. Early-stage accounts without enough historical data. Fast-changing channel mixes where the historical data does not represent current reality. + +Bias direction. The strongest defense against platform self-attribution because MMM does not rely on platform-reported conversions. Limitations are statistical: confidence intervals are wide; granularity is low (channel-level, not campaign-level). + +--- + +## The same path under each model + +A worked example. A B2C SaaS user converts after this path: + +1. Sees a YouTube awareness ad (impression, not click). +2. Clicks a Meta retargeting ad three days later. +3. Searches for the brand on Google. Clicks a paid branded search ad. +4. Returns directly the next day. Converts. + +Attribution by model. + +\| Model \| YouTube \| Meta \| Branded Search \| Direct \| +\|---\|---\|---\|---\|---\| +\| Last-click \| 0% \| 0% \| 0% (depending on direct vs paid) \| 100% \| +\| First-click \| 0% (impressions excluded) \| 100% \| 0% \| 0% \| +\| Linear \| 0% \| 33% \| 33% \| 33% \| +\| Time-decay \| 0% \| 15% \| 35% \| 50% \| +\| U-shaped \| 0% \| 40% \| 20% \| 40% \| +\| Google DDA \| (only sees Google touchpoints) \| (only sees Meta touchpoints if Conversions API integration) \| varies \| varies \| +\| MMM \| partial credit (spend in YouTube correlates with conversions) \| partial credit \| partial credit \| (organic, not modeled) \| + +The takeaway. Same path. Five different attribution stories. None is right. Each tells you something different. + +--- + +## Decision matrix by business stage + +\| Stage \| Primary model \| Secondary check \| Why \| +\|---\|---\|---\|---\| +\| Pre-PMF \| Last-click + warehouse-attributed CAC \| None; insufficient volume for sophisticated models \| Sophisticated attribution needs volume you do not have \| +\| Series A or early growth \| Last-click + GA4 data-driven \| First-click as sanity check on awareness \| Volume insufficient for MMM; DDA requires more conversions than most early-stage accounts have \| +\| Mid-stage (10K+ conversions per month) \| Google DDA + GA4 path data \| Last-click for channel decisions; first-click for awareness \| DDA gets reliable here; cross-validate with simple models \| +\| Mature (100K+ conversions per month, 2+ years data) \| MMM as canonical \| Last-click for in-flight; DDA for cross-channel \| MMM is the strongest defense against self-attribution at scale \| +\| Multi-channel including offline \| MMM mandatory \| DDA for digital \| MMM is the only model that captures offline contribution \| + +The progression. As volume grows and channel mix expands, the model that fits changes. Locking in last-click forever is fine if the business stays simple; the moment offline or upper-funnel channels matter, the model has to advance. + +--- + +## How to communicate which model produced which number + +Three rules for honest reporting. + +1. Always label the model. "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions on last-click attribution with a 7-day-click window" is honest. +2. Report the same number under at least two models when stakes are high. Board decks should show the conservative view (last-click) and the generous view (linear or DDA). The range tells stakeholders what they are not learning. +3. Reconcile against the warehouse before reporting in dollars. Dollar figures attached to platform-reported conversions inherit all the platform's attribution biases. Warehouse-attributed dollars are the only dollars that have been independently verified. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md b/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md new file mode 100644 index 0000000..dbd3fdb --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/cohort-analysis-templates.md @@ -0,0 +1,113 @@ +# Cohort analysis templates + +Three cohort cuts that matter for paid media. By acquisition month, by channel, by campaign. Plus retention curves and when to act. + +The principle. Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. The difference is the leading indicator that a channel or campaign is degrading; daily metrics catch the same problem two to three months later when it shows up in revenue. + +--- + +## Template 1: Cohort by acquisition month + +The standard rolling 12-month view of LTV growth. + +Setup. For each acquisition month over the last 12 months, compute the cumulative revenue per customer at month 1, month 3, month 6, and month 12 (where data is available). + +Output. + +\| Acquisition month \| M1 revenue/customer \| M3 revenue/customer \| M6 revenue/customer \| M12 revenue/customer \| +\|---\|---\|---\|---\|---\| +\| 2025-05 \| $42 \| $86 \| $128 \| $185 \| +\| 2025-06 \| $44 \| $89 \| $135 \| $192 \| +\| 2025-07 \| $40 \| $82 \| $122 \| $178 \| +\| 2025-08 \| $43 \| $85 \| $130 \| (incomplete) \| +\| 2025-09 \| $38 \| $78 \| (incomplete) \| (incomplete) \| +\| 2025-10 \| $35 \| $72 \| (incomplete) \| (incomplete) \| +\| 2025-11 \| $33 \| $68 \| (incomplete) \| (incomplete) \| +\| 2025-12 \| $34 \| (incomplete) \| (incomplete) \| (incomplete) \| + +The signal. The M3 revenue per customer dropped from $86 to $68 over six months. Recent acquisitions are lower-quality customers. The daily metrics will show this as ROAS deterioration in two to three months when the recent cohorts hit their declining LTV plateau. + +Action. Investigate which channels or campaigns shifted in the last six months. The drop usually correlates with a specific channel scaling into lower-quality audiences. + +--- + +## Template 2: Cohort by acquisition channel + +The channel-level LTV story that ROAS hides. + +Setup. For each channel, compute LTV at fixed time windows (30, 60, 90, 180, 365 days post-acquisition). Track the trend over multiple acquisition cohorts. + +Output (cohort: 2025-Q3 acquisitions, measured at 90 days post-acquisition). + +\| Channel \| New customers \| CAC \| 90-day revenue/customer \| 90-day LTV/CAC \| Verdict \| +\|---\|---\|---\|---\|---\|---\| +\| Google brand search \| 420 \| $45 \| $128 \| 2.8x \| Strong \| +\| Google generic search \| 280 \| $95 \| $112 \| 1.2x \| Marginal \| +\| Meta prospecting \| 540 \| $72 \| $84 \| 1.2x \| Marginal \| +\| Meta retargeting \| 320 \| $48 \| $156 \| 3.3x \| Strong \| +\| LinkedIn Sponsored \| 95 \| $320 \| $580 \| 1.8x \| Long payback; B2B-typical \| +\| TikTok In-Feed \| 180 \| $58 \| $61 \| 1.1x \| Marginal \| +\| Direct (organic) \| 1,200 \| n/a \| $145 \| n/a \| Reference baseline \| + +The signal. Meta retargeting and Google brand search are the strong performers on LTV-CAC. Meta prospecting and TikTok In-Feed are marginal; the customer quality is lower than the platform-reported ROAS suggests. + +Action. The marginal channels need either CAC reduction or audience-quality improvement. Pulling back on the marginal channels and reallocating to the strong ones improves blended LTV-CAC. + +--- + +## Template 3: Cohort by acquisition campaign + +Campaign-level cohort signals. Use sparingly; sample sizes get small fast. + +Setup. For each campaign with sufficient acquisition volume (typically 100+ customers per cohort), compute LTV at 30 and 60 days. Compare against the channel average. + +Output. + +\| Campaign \| New customers \| CAC \| 60-day revenue/customer \| vs channel average \| +\|---\|---\|---\|---\|---\| +\| Meta-Lookalike-1pct \| 320 \| $58 \| $112 \| +30% \| +\| Meta-Lookalike-5pct \| 180 \| $48 \| $74 \| -15% \| +\| Meta-Interest-SaaS \| 90 \| $72 \| $86 \| -5% \| +\| Meta-Retargeting-30day \| 240 \| $42 \| $148 \| +60% \| + +The signal. The 5% lookalike is finding lower-quality customers than the 1% lookalike, even at lower CAC. The ROAS view favors the 5% lookalike (lower CAC, decent revenue); the cohort view shows the customer quality dropped. + +Action. Pull back the 5% lookalike. Concentrate spend on the 1% lookalike and the retargeting segments. Watch for next-cohort confirmation before a permanent reallocation. + +--- + +## Retention curves + +A retention curve plots customer activity over time. Three patterns to recognize. + +Plateau curve. Activity drops in the first 30 days, then stabilizes at a level it sustains long-term. The plateau height is the long-run user value. Healthy SaaS, subscription consumer, marketplace. + +Smile curve. Activity drops, plateaus, then trends upward (resurrection effect). Less common; characteristic of products with seasonal or lifecycle re-engagement. + +Decay curve. Activity drops continuously without stabilizing. The product is not retaining; the unit economics will not work no matter what CAC the channel produces. Common in low-engagement consumer apps. + +The curve to watch by acquisition channel. A channel whose retention curve plateaus higher than another is delivering higher-LTV customers, regardless of the CAC ratio. This is the data behind LTV-CAC channel comparisons. + +--- + +## When to act on cohort signals + +Three triggers. + +1. Two consecutive months of LTV decline at the same time horizon. A single month is noise; two is signal. Investigate which channels shifted. +2. Channel-level LTV-CAC ratio falls below 2x for two consecutive cohorts. Pause or reallocate the channel. The 2x threshold accounts for gross margin, payback period, and the variance in LTV measurement. +3. A campaign-level cohort underperforms the channel average by 20%+ for two consecutive cohorts. The campaign is bringing in lower-quality audiences than the rest of the channel. Pause or reallocate. + +The discipline. Watch cohort signals on a monthly cadence. Most teams over-index on weekly platform metrics and under-index on cohort signals; the cohort-watchers see the problems first. + +--- + +## Common cohort mistakes + +Reading recent cohorts as final. A 30-day cohort's "LTV" is actually 30-day revenue, not LTV. Naming matters. If the team treats 30-day revenue as LTV in spreadsheets, they will undercount channels with longer payback periods. + +Comparing cohorts at different ages. A January cohort measured at 12 months vs a November cohort measured at 2 months is comparing different things. Always compare at matched ages. + +Ignoring seasonal cohorts. Q4 cohorts often have higher first-purchase value but lower retention because Q4 acquisition includes one-time gifters. Account for the seasonal pattern; do not over-index on Q4 cohort numbers. + +Not segmenting by channel. Aggregate LTV trends hide channel-level shifts. The channel-segmented cohort is where the action signal lives. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md b/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..5b6e91d --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/common-interpretation-failures.md @@ -0,0 +1,155 @@ +# Common interpretation failures + +Twelve failure patterns that recur in paid media reporting work. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. ROAS dropped 20% week-over-week, kill the campaign + +Symptom. Weekly ROAS chart shows a drop. Team wants to pause the campaign. + +Root cause. Could be noise. Day-of-week, holiday timing, conversion-window lag, exogenous variance. A 20% drop in a metric that varies 10 to 15% naturally is below the signal threshold. + +Fix. Pre-commit a test window before acting on weekly variance. For most campaigns, two consecutive weeks of decline below the threshold is the signal. Single-week swings are usually noise. + +Prevention. Establish baseline variance for each campaign before declaring "improvement" or "decline." Without the baseline, every weekly chart looks alarming. + +--- + +## 2. Meta says 500 conversions, my warehouse says 200, who is right + +Symptom. Platform-reported numbers do not match warehouse numbers. The team picks the more flattering one. + +Root cause. Both are wrong; warehouse is closer to truth. Meta self-attributes (claims credit for conversions other channels also touched). View-through and modeled conversions inflate Meta's count. + +Fix. Reconcile, do not pick a winner. Report the warehouse number as canonical for board metrics. Use Meta's number only for in-flight optimization within Meta. + +Prevention. Make the reconciliation cadence explicit. Weekly check, monthly deep dive, quarterly attribution review. The team that runs the reconciliation never has to "pick a winner." + +--- + +## 3. Turned off Google PMax, conversions did not drop + +Symptom. Paused PMax. Total account conversions held steady. + +Root cause. PMax was harvesting branded search conversions you would have gotten free from organic. The platform was claiming credit for traffic that was not incremental. + +Fix. Audit branded queries inside PMax. Add account-level negative keywords for branded queries. Restart PMax with branded excluded; the incremental contribution from non-branded inventory is the real value. + +Prevention. At PMax setup, exclude branded queries from the start. Audit PMax's spend distribution monthly to catch the cannibalization pattern early. + +--- + +## 4. New campaign hit 5x ROAS in week 1 + +Symptom. A fresh campaign's first-week ROAS is 5x. Team wants to scale immediately. + +Root cause. Likely retargeting hot leads or running on a small audience of warm prospects who would have converted anyway. The first week is unrepresentative. + +Fix. Check the audience composition. If retargeting or warm-list, the 5x is not the steady-state. Wait two to four weeks before scaling. + +Prevention. Define the success metric and the test window before launch. Do not let a strong first week change the plan; pre-commit to the four-week measurement. + +--- + +## 5. A/B tested and one creative wins by 12% + +Symptom. Two creatives tested. One wins by 12%. Team wants to ship the winner. + +Root cause. 12% is within margin of platform noise for a typical creative test. Variants compete with each other inside the platform's optimization; the platform's own decisions confound the test. + +Fix. Re-run the test with more volume, or accept that the difference is within noise and pick based on production cost or refresh ease. + +Prevention. Set the minimum detectable effect (MDE) before testing. A 12% threshold requires a specific volume; if you cannot reach it, the test cannot detect that effect cleanly. + +--- + +## 6. LTV calculation says this channel is profitable + +Symptom. A team's LTV-CAC analysis shows a channel as profitable. Spend is increased. + +Root cause. The "LTV" in the calculation may be a 60-day cumulative revenue projected forward, not actual lifetime value. Recent cohorts have not aged enough to confirm the LTV. + +Fix. Confirm the cohort age. If projecting forward, document the assumption and stress-test (what happens if actual LTV is 80% of projected). + +Prevention. Always pair LTV calculations with cohort age. A 30-day cohort has 30-day revenue, not LTV. Naming clearly prevents the substitution error. + +--- + +## 7. High frequency is fine because conversions are still happening + +Symptom. Frequency at 6 to 8 per week. Conversions on the platform are stable. Team concludes fatigue is not an issue. + +Root cause. Fatigue masked by conversions that would have happened anyway from organic, retargeting overlap, or recurring customers. The platform is taking credit for traffic the high frequency did not actually drive. + +Fix. Run an incrementality test on the high-frequency campaign. The likely finding is that incremental rate dropped substantially even as raw conversions held. + +Prevention. Watch frequency as a leading indicator. Above 4 to 5 per week is the alarm regardless of conversion levels. Refresh creative. + +--- + +## 8. Last-click attribution shows Meta at 60% credit + +Symptom. Last-click view of paid media shows Meta dominant. Team allocates budget accordingly. + +Root cause. Last-click bias. Meta may also be the closer because users who searched for the brand on Google clicked through, then later saw a Meta retargeting ad and converted. Last-click credits Meta; the conversion would have happened anyway. + +Fix. Read the same data under first-click and a multi-touch model. The picture changes. Allocate based on a balanced view, not the last-click view alone. + +Prevention. Always compare attribution under at least two models for budget decisions. The single-model view is reliable for in-flight only. + +--- + +## 9. Scaled spend 5x, conversions only doubled + +Symptom. Budget went from $20K to $100K per month. Conversions went from 800 to 1,600. + +Root cause. Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher than the average CAC the team was reporting. + +Fix. Calculate the marginal CAC, not just average CAC. The marginal CAC at the higher spend tier tells you whether more spend will produce more conversions or just spend more for the same conversions. + +Prevention. Project the saturation curve before scaling. If a 1.5x spend increase produced a 1.2x conversion increase, expect the next 1.5x to produce 1.0x or less. + +--- + +## 10. Brand campaigns underperform on direct ROAS + +Symptom. A brand campaign reports 0.8x ROAS. Team wants to cut it. + +Root cause. Brand campaigns affect downstream channel efficiency, not direct conversion. The direct ROAS is the wrong measurement for brand impact. + +Fix. Measure brand against brand-search lift, organic traffic growth, or direct-traffic growth. The brand campaign's effect shows up in cheaper performance acquisition over the next 60 to 90 days. + +Prevention. At brand campaign setup, define the success metric explicitly (brand search lift target, organic traffic target, awareness lift). Do not let direct ROAS become the unintended grading metric. + +--- + +## 11. ROAS held steady but profit dropped + +Symptom. Channel-level ROAS at 3x, stable. Profit on the same channel dropped 20% over the quarter. + +Root cause. The mix shifted toward lower-margin products. ROAS is a revenue metric; it does not see margin. The channel attracted bargain hunters at lower margin, holding ROAS but cutting profit. + +Fix. Track contribution-margin ROAS, not gross-revenue ROAS. The contribution-margin view catches the mix shift the gross view hides. + +Prevention. Build margin-aware reporting from the start. Most teams default to gross revenue; the move to contribution margin pays for itself within a quarter. + +--- + +## 12. Agency reported a 4x ROAS month + +Symptom. External agency claims a 4x ROAS for the month. Team accepts the number. + +Root cause. Whose number? Platform-reported, warehouse-attributed, or model-adjusted? Agencies often report the most generous number (their incentive). Without specifying the attribution methodology, the 4x ROAS is unreadable. + +Fix. Demand the attribution methodology in every agency report. Reconcile against the warehouse before presenting to leadership. + +Prevention. Build attribution-methodology specification into the agency contract. Reports must include the model, the window, and the source of conversion data. The contract that does not specify produces reports that cannot be evaluated. + +--- + +## The pattern across all twelve + +Most paid media interpretation failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale ROAS at the cost of LTV. Pause an underperformer at the cost of total volume. Trust platform-reported attribution at the cost of incremental truth. + +The fix at the meta level. Decide on the success metric (warehouse-attributed CAC, LTV-CAC ratio, contribution-margin ROAS) and the guardrails (volume, frequency, customer-cohort quality, brand metrics) before reading any dashboard. Pull back the moment a guardrail breaks, even if the success metric still looks fine. The dashboard is a tool, not the truth; the warehouse plus quarterly incrementality testing is closer to truth. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md b/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md new file mode 100644 index 0000000..1066402 --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md @@ -0,0 +1,114 @@ +# Dashboard reconciliation patterns + +The single-source-of-truth pattern for paid media reporting. Warehouse as canonical; platforms as in-flight signals. + +The principle. Sum-of-platform-reports is always greater than reality because every platform claims credit for conversions other platforms also touched. Reporting platform-summed numbers as fact in board decks is the most expensive error in paid media analytics. + +--- + +## The three-layer reporting model + +Layer 1: platform metrics. Use for in-flight optimization only. Ad-set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +Layer 2: warehouse multi-touch attribution. Use for cross-platform comparison and channel-level decisions. Each conversion gets attributed across all platforms that touched the path. Pick one model (last-click, first-click, linear, U-shaped, DDA) and standardize across the team. + +Layer 3: marketing-mix modeling (MMM) at scale. Use for budget allocation across channels. MMM treats spend as input and revenue as output; it does not rely on platform-reported attribution at all. The strongest defense against platform self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## Blended CAC + +The board-deck number. Resistant to attribution debates because it does not require choosing an attribution model. + +Formula. + +``` +Blended CAC = (total ad spend across platforms) / (total new customers from warehouse) +``` + +Worked example. + +In Q4, the team spent $200K total: $80K on Google Ads, $70K on Meta, $30K on LinkedIn, $20K on TikTok. The warehouse shows 1,250 new customers in Q4 from all sources (paid, organic, direct, referral). + +But the team needs to attribute the new customers to paid specifically. Two ways to do this: + +1. Approximate. Assume the proportion of paid-attributed customers in the warehouse roughly equals the proportion that paid contributed to traffic. If 60% of traffic in Q4 was paid-attributed, then 60% of 1,250 equals 750 paid-acquired customers. Blended paid CAC: $200K / 750 = $267. +2. Precise. Use the warehouse's multi-touch attribution to credit paid channels with a fraction of each conversion. Sum the paid-attributed share across all conversions; that becomes the denominator. + +The precise version is better when available. The approximate version works when the warehouse data is incomplete. Both produce a number that does not double-count across platforms. + +--- + +## The board-deck pattern + +Three rules for reporting paid media numbers to leadership. + +1. Lead with blended CAC, not channel CAC. Channel CAC depends on attribution model; blended CAC does not. Stakeholders not in the weeds on attribution find blended CAC easier to compare across quarters. +2. Show the range. Report the conservative view (last-click) and the generous view (linear or DDA) for any high-stakes channel decision. The range tells stakeholders what they are not learning. +3. Always label the source. "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions per Meta's 7-day-click attribution; warehouse-attributed: 540" is honest. + +A worked example board slide. + +``` +Q4 paid media performance + +Total spend: $200K (vs $185K Q3, +8%) +New customers from paid (warehouse-attributed): 750 (vs 680 Q3, +10%) +Blended paid CAC: $267 (vs $272 Q3, -2%) + +Channel CAC (warehouse-attributed, last-click): + Google: $240 (40% of new customers) + Meta: $290 (35% of new customers) + LinkedIn: $480 (15% of new customers) + TikTok: $180 (10% of new customers) + +Platform-reported CAC (for in-flight context, not board decision): + Google: $190 (Google reports 26% more attributed conversions than warehouse) + Meta: $210 (Meta reports 38% more) + LinkedIn: $475 (roughly aligned) + TikTok: $135 (TikTok reports 33% more) + +Quarterly incrementality test result (geo holdout, October): + Brand search: 12% incremental (95% CI: 6-18%). Reduced spend 30%; CAC dropped. + Meta retargeting: 31% incremental (95% CI: 22-40%). Maintained spend; CAC view adjusted. +``` + +The slide tells the truth: the warehouse number is the canonical CAC, the platform numbers are inflated, the incrementality test confirms which channels are real. + +--- + +## Reconciliation cadence + +Weekly. Pull platform-reported numbers and warehouse numbers. Confirm the sum-of-platforms vs warehouse ratio is in the expected range. A sudden divergence means a tracking break, an attribution-model change, or a platform reporting bug. Investigate. + +Monthly. Deeper reconciliation. Compare channel-level attribution across last-click, first-click, and the team's chosen model. Identify channels whose ranking changes by model. + +Quarterly. Run an incrementality test on the highest-spend channel. Update the channel-level CAC adjustment factor based on the test result. + +--- + +## Common reconciliation mistakes + +Reporting platform-summed conversions to the board. The most common error. The board sees "1,600 conversions across paid channels" when the warehouse says 950. The team gets caught when someone divides revenue by 1,600 and gets a CAC that does not match the P&L. + +Comparing platforms on platform-reported CAC. Each platform's CAC is computed against a different attribution window and a different set of self-attribution biases. Compare on warehouse-attributed CAC instead. + +Treating "lift" as incrementality without a controlled test. A campaign that ran during a period of overall conversion growth gets credit for "lift" that was actually seasonality or organic momentum. Lift requires a control group; otherwise it is correlation reported as causation. + +Updating attribution models mid-quarter. Switching from last-click to DDA mid-quarter makes the quarter's data uninterpretable. Pick a model for the quarter; switch only at quarter boundaries with a documented changelog. + +Reporting blended CAC without naming the time window. "$267 blended CAC" depends on whether you measured over 30, 60, or 90 days. Pin the window. + +--- + +## When the platforms agree more than usual + +A useful diagnostic. If platform-reported sums match warehouse total within 10%, something has changed. Possibilities: + +- The team set up Conversions API on Meta or server-side tagging on Google, which improved tracking precision. +- The mix shifted toward branded search, where attribution overlap is lower. +- One platform's conversion volume dropped significantly (saturation, fatigue, or campaign issue). + +Investigate any sudden alignment. The platforms diverging is the normal state; alignment usually has a cause worth understanding. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md b/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md new file mode 100644 index 0000000..a52ea6c --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/incrementality-testing-playbook.md @@ -0,0 +1,139 @@ +# Incrementality testing playbook + +The honest test in paid media analytics. If we had not run this ad, would we still have gotten the conversion? The answer above zero is the incremental contribution. + +The principle. Most paid media is not 100% incremental. Branded search bidding is often 5 to 20% incremental. Retargeting is often 20 to 40% incremental. Prospecting is often 50 to 90% incremental. The number that matters for spend decisions is the incremental rate, not the platform-reported attribution rate. + +--- + +## Method 1: Geo holdout + +The cleanest causal test for paid media at scale. + +Setup. Pick two regions with similar baseline conversion rates and demographic profiles (matched markets). Run the campaign in one region (test); turn it off in the other (holdout). + +Duration. Two to four weeks minimum. Statistical power calculation upfront determines the right length given the spend scale and expected lift. + +Analysis. Compare conversions in test vs holdout, normalized by population. The difference is the incremental contribution. + +Expected incremental rate ranges. + +\| Channel \| Typical incremental rate \| +\|---\|---\| +\| Branded search \| 5 to 20% \| +\| Retargeting \| 20 to 40% \| +\| Lookalike audiences \| 40 to 70% \| +\| Cold prospecting \| 50 to 90% \| +\| Awareness video \| 30 to 60% \| + +Common pitfalls. + +- Picking holdout regions with confounding factors (different competitive presence, weather event, retail launch). Confounded results are worse than no test. +- Stopping the test early when the data looks good. Pre-commit the duration and stick to it. +- Holding out for too long. A 6-week holdout in a small region is expensive in lost conversions; 2 to 4 weeks is usually enough at scale. + +--- + +## Method 2: Ghost bidding (Google) + +Google's own incrementality tool. The platform bids on a holdout share of impressions but does not actually serve the ad. The reported delta between served and ghost is incremental. + +Setup. Configure within Google Ads. Choose the campaigns and the holdout share (typically 5 to 20%). + +Duration. Two to four weeks. + +Analysis. Google reports incremental conversions directly. Cross-validate against your own warehouse measurement. + +Pitfalls. + +- The math is opaque to many teams. The output is a single incremental number; the underlying methodology is Google's. Trust but verify with a manual geo test on the same campaign. +- Only available within Google Ads, not cross-channel. + +--- + +## Method 3: Conversion lift studies (Meta) + +Meta's incrementality tool. Splits audiences into test (sees the ad) and control (does not). Measures lift. + +Setup. Configure within Meta Ads Manager. Specify the campaign and the test-control split. + +Duration. Three to four weeks. Meta requires a minimum spend per study. + +Analysis. Meta reports incremental lift. The reporting includes statistical significance bands. + +Pitfalls. + +- The minimum spend requirement makes it expensive for small accounts. +- Only available within Meta, not cross-channel. +- Meta's interpretation tilts toward generous (their incentive). Cross-validate with geo holdout when possible. + +--- + +## Method 4: PSA tests + +Serve some users a public service announcement instead of your ad. Compare conversion rates. + +Setup. Run two parallel campaigns: one with your ad, one with a PSA (typically a charity or public-interest message). Match audiences. + +Duration. Three to six weeks. + +Analysis. Compare conversion rate of the PSA-exposed audience against the ad-exposed audience. The difference is incremental. + +Pitfalls. + +- Ethically and brand-wise, choose PSAs that align with brand values. +- Setup overhead is high. Reserved for legacy brands with deep budgets and serious incrementality questions. + +--- + +## Method 5: Switchback designs + +Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. + +Setup. Run for at least 8 weeks. Alternate weekly: on, off, on, off. Or alternate by audience segment. + +Duration. Eight to twelve weeks. Shorter switchbacks have low statistical power. + +Analysis. Difference in conversions between on-weeks and off-weeks, normalized for week-of-year and external variance. + +Pitfalls. + +- Confounded by exogenous factors (news, competitor activity, seasonality). Best for steady-state campaigns where the external context is stable. +- Audience contamination: users who saw the ad in week 1 may convert in week 2 even when the campaign is off. The contamination dilutes the measured incremental rate. + +--- + +## Choosing the right method + +\| Constraint \| Recommended method \| +\|---\|---\| +\| Single platform, want quick answer \| Platform-native (ghost bidding for Google, conversion lift for Meta) \| +\| Cross-platform incremental test \| Geo holdout \| +\| Small account, limited budget \| Geo holdout in two small matched markets \| +\| Long campaign cycle, steady-state \| Switchback \| +\| Brand or awareness channel \| PSA test or geo holdout \| +\| Regulated industry, ethics concern \| Geo holdout (no PSA) \| + +The default. Geo holdout. It is the most honest causal test, works cross-channel, and produces results that are interpretable without trusting the platform's methodology. + +--- + +## How to run a geo holdout step by step + +1. Pick matched markets. Use designated market areas (DMAs) or postal-code-level regions with similar baseline conversion rates and demographic profiles. Aim for at least three test and three holdout regions for statistical power. +2. Calculate statistical power. Given the expected lift and the regional conversion volume, can the test detect the effect? If the regions are too small, the test is underpowered and inconclusive results are likely. +3. Pre-commit the analysis window. Define the start date and end date before the test begins. Do not adjust based on early results. +4. Run the test. Campaign on in test regions; off in holdout. No mid-test changes. +5. Wait for the full window. Analyzing early produces noise. +6. Compute the delta. Conversions in test minus conversions in holdout, normalized by population. The delta divided by spend is the incremental CPA. Compare against the platform-reported CPA; the gap is the over-attribution. +7. Report incremental contribution. Do not report platform-reported CAC alongside warehouse CAC and incremental CAC without labeling. The unit of measurement matters as much as the number. + +--- + +## Cadence + +For accounts spending $25K+ per month, run incrementality tests at least quarterly on the highest-spend channels. The cost of the test is small relative to the cost of running un-incremental spend at scale. + +For accounts under $25K per month, annual or semi-annual tests are typically enough. The test cost vs the spend savings does not pencil out as often. + +The discipline. Schedule the tests. Do not wait for a "we should test this" moment; the moment never comes voluntarily. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md b/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md new file mode 100644 index 0000000..ee569ff --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/metric-definitions-glossary.md @@ -0,0 +1,83 @@ +# Metric definitions glossary + +The paid media metrics that show up on every dashboard, with explicit definitions, formulas, and the common pitfalls in usage. + +The point of an explicit glossary. Two teams using the same metric name often compute different numbers. "Conversion rate" might mean clicks-to-conversion or impressions-to-conversion or unique-users-to-conversion. The team that does not pin definitions ends up arguing about numbers that are not the same number. + +--- + +## Volume metrics + +Impressions. Count of times an ad was displayed. Includes the same user seeing the ad multiple times. + +Reach. Count of unique users who saw the ad. Always less than or equal to impressions. + +Frequency. Impressions divided by reach. The average number of times a unique user saw the ad. Above 4 to 5 per week is the fatigue alarm. + +Clicks. Count of clicks on the ad. Some platforms count "outbound clicks" (which leave the platform) separately from "all clicks" (which include in-platform interactions like saves and shares). Use outbound for direct response. + +--- + +## Cost metrics + +CPC (cost per click). Spend divided by clicks. Formula: `spend / clicks`. The cost of one click; not the cost of one conversion. Conflating them is the most common reporting error. + +CPM (cost per thousand impressions). Spend divided by (impressions / 1000). Formula: `spend / (impressions / 1000)`. The cost of reach. Useful for comparing platforms on awareness efficiency. + +CPA (cost per acquisition). Spend divided by conversions. Formula: `spend / conversions`. The variant where "conversion" is defined matters; the same campaign reports different CPAs depending on whether the conversion is a click, a lead form submission, a purchase, or a paid customer. + +ROAS (return on ad spend). Revenue from ad-attributed conversions divided by spend. Formula: `attributed revenue / spend`. NOT profit-divided-by-spend. ROAS is a revenue metric, not a profit metric. A 3x ROAS at 30% margin is a 0.9x return on cost; the ROAS reading on its own is misleading. + +MER (marketing efficiency ratio). Total revenue divided by total marketing spend, across all channels. Formula: `total revenue / total marketing spend`. The most honest top-line number; resistant to per-channel attribution debates. + +Blended CAC. Total ad spend divided by total new customers from warehouse. Formula: `total ad spend / new customers from warehouse`. The board-deck number. Channel-level CAC depends on attribution; blended CAC does not. + +--- + +## Conversion metrics + +Conversion. The event the campaign optimizes for. Definition varies. Always document: which event, what window, which attribution model. Without these three, "conversions = 800" is unreadable. + +Conversion rate. Conversions divided by something. The denominator changes the meaning. Click-through conversion rate (`conversions / clicks`) is different from impression conversion rate (`conversions / impressions`) which is different from unique-user conversion rate (`conversions / reach`). Pin the denominator at every report. + +Conversion window. The maximum time between the ad event (click or view) and the conversion for which the platform takes credit. Meta default: 7-day click plus 1-day view. Google default: 30-day click plus 1-day view. Different windows mean different reported counts from the same activity. + +View-through conversion. A conversion attributed to an ad the user saw but did not click. Counted by Meta and Google. Often half the platform-reported conversions are view-through. Treat as a soft signal of awareness contribution, not as direct response measurement. + +Modeled conversion. A statistically estimated conversion when actual tracking is blocked (most commonly iOS users on Meta after ATT). The platform models what the conversion would have been based on aggregated data. Modeled is an estimate, not a measurement; precision is low. + +--- + +## Customer-value metrics + +LTV (lifetime value). Total revenue from a customer over their relationship with the brand. Many definitions; the right one for paid media analytics is gross revenue or contribution margin, not unit count. Pair with CAC for the LTV:CAC ratio. + +LTV:CAC ratio. LTV divided by CAC. Formula: `LTV / CAC`. The unit-economics test. 3:1 is the venture-capital benchmark; the right number for any specific business depends on payback period and gross margin. + +Payback period. Months until cumulative revenue from a customer equals the CAC to acquire them. The cash-flow companion to LTV:CAC. Investors care about payback; operators care about both. + +AOV (average order value). Revenue divided by order count. Formula: `revenue / orders`. Useful for e-commerce; less for subscription. The number that turns "increased conversion rate" into "increased revenue." + +--- + +## Engagement metrics (less direct) + +CTR (click-through rate). Clicks divided by impressions. Formula: `clicks / impressions`. Useful for hook quality. Less useful for conversion quality; high CTR with low conversion rate means the hook is too aggressive for the offer. + +Hide ratio (negative feedback). Count of users who explicitly hid or marked the ad as not-interested, divided by impressions. Above 1.5% is the alarm; the platform algorithm will throttle delivery to that audience. + +Engagement rate. Likes plus comments plus shares plus saves divided by impressions. Useful for organic-style content; less directly tied to performance for paid. + +--- + +## Common pitfalls + +Treating ROAS as profit. ROAS is revenue-divided-by-spend. Profit-divided-by-spend is "return on ad investment" or "ROI." Confusing the two leads to greenlit campaigns that lose money on every conversion. + +Ignoring conversion window in cross-platform comparisons. Meta's 7-day-click count is not comparable to Google's 30-day-click count without normalization. + +Treating frequency as a vanity number. Frequency above 4 to 5 per week is a fatigue signal. Many teams celebrate high frequency as proof of "audience saturation"; it is the inverse. + +Using CPA when conversion definitions differ across campaigns. A search campaign with a "lead-form-submission" conversion has a CPA in different units from a display campaign with a "purchase" conversion. Compare campaign-level CPA only when the conversion event matches. + +Confusing modeled conversions with measured conversions. Modeled is an estimate; measured is a count. Treating the two as interchangeable produces false confidence in the size of the effect. diff --git a/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md b/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md new file mode 100644 index 0000000..363477b --- /dev/null +++ b/dist/pi/.agents/skills/ads-performance-analytics/references/platform-reporting-quirks.md @@ -0,0 +1,108 @@ +# Platform reporting quirks + +Per-platform reporting behaviors that affect how to read the numbers. The platforms do not agree on what counts as a conversion or how to credit it; reading their dashboards as truth is the most expensive error in paid media analytics. + +--- + +## Google Ads + +Default attribution model. Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on machine learning. Single-touch attribution (last-click) is available but no longer the default. + +Conversion windows. Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA4 reports by default; this produces the typical 1.3 to 1.5x conversion overcount versus GA4 for the "Google Ads" channel. + +Modeled conversions. Google models conversions for users with consent restrictions or cross-device gaps. Modeled volume can be material in iOS-heavy traffic. Modeled is an estimate; do not treat with the precision you would treat directly observed conversions. + +Performance Max black box. PMax does not expose keyword-level, placement-level, or audience-level performance directly. The platform manages allocation across Search, Shopping, Display, YouTube, Discover, and Gmail. Levers you have: budget, asset groups (creative quality), audience signals (Customer Match seeds), and exclusions (account-level negatives). + +Branded search cannibalization in PMax. PMax includes Search by default. It will harvest branded queries you would have ranked for organically. Add account-level negative keywords for branded queries to prevent paid cannibalization. + +Lost Impression Share metrics. Search exposes "Lost IS (rank)" and "Lost IS (budget)" to indicate why your ad did not show. Lost IS rising is the leading indicator that competition increased or budget became constrained. + +Search-term reports. The list of actual queries that triggered your ad, vs your keyword targeting. Underused. Audit monthly to find irrelevant queries (negative keyword candidates) and high-performing queries you might want to add as exact-match keywords. + +--- + +## Meta (Facebook and Instagram) + +Default attribution. 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +iOS 14.5+ impact. App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated) and Conversions API (CAPI, server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +Conversions API necessity. CAPI sends server-side events directly from your backend to Meta, bypassing the browser-pixel restrictions. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. Without CAPI, the platform's optimization signal degrades significantly on iOS-heavy audiences. + +View-through attribution overcount. View-through counts impressions even when the user did not click. Often half the reported conversions on Meta are view-through. Useful as awareness signal; misleading for performance optimization. + +Modeled conversions in iOS reports. Meta reports modeled conversions inline with directly observed ones unless you filter explicitly. Use the breakdown view to disaggregate by attribution type (1-day click, 7-day click, 1-day view, modeled). + +Frequency reporting at the ad set level. Meta exposes frequency in the Ads Manager. Use it as the primary fatigue signal; CTR decay is downstream of frequency rising. + +Negative feedback rate. Meta exposes "negative feedback rate" as a customizable column. Above 1.5% is the alarm; the algorithm penalizes high-feedback creatives by reducing reach. + +--- + +## LinkedIn + +Default attribution. 30-day click and 7-day view-through. + +Why the longer windows. B2B buying cycles are longer than B2C. The 30-day-click window matches the typical B2B consideration cycle. Comparing LinkedIn's reported numbers against Meta's 7-day-click numbers without normalizing is comparing different definitions. + +Cross-device gaps. LinkedIn reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair LinkedIn paid reports with self-reported attribution surveys when the offer is high-consideration B2B. + +Lead Gen Forms reporting. Form submissions count as conversions regardless of downstream lead qualification. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. Many leads are accidental or low-quality. + +Demographic insights. LinkedIn's demographic reporting (industry, job seniority, company size, function) is unique to the platform. Use it for audience refinement; the data is not available cleanly on other platforms. + +Cost insights. LinkedIn's CPM tends to be 3 to 10x higher than B2C platforms because of the audience precision premium. The justification is B2B LTV; lower-LTV offers cannot make LinkedIn math work. + +--- + +## TikTok + +Default attribution. 7-day click and 1-day view-through, similar to Meta. + +Video-completion-based attribution. TikTok counts conversions even when the user did not click but watched the full video. This is unique among the platforms covered here. The signal is real for awareness; it inflates direct-response numbers. + +iOS impact, less mature modeling. TikTok faces similar ATT-driven tracking gaps as Meta. The modeling is less mature, which means iOS-heavy audiences see more under-reporting on TikTok than on Meta. + +Spark Ads attribution overlap. Spark Ads boost organic posts. Engagement on the boosted version shows up in both organic and paid surfaces. Be careful not to double-count when reconciling against organic engagement reports. + +Spark Ads vs paid creative differential. Spark Ads consistently outperform pure paid creative on TikTok because they retain organic engagement signals. A team comparing CPMs of Spark vs paid will see Spark consistently lower; the difference is real, not a reporting artifact. + +Trend-based volatility. TikTok performance is more sensitive to trending sounds and formats than other platforms. Reporting comparisons across long time periods are less reliable because the platform itself shifted. + +--- + +## Programmatic and Display + +Viewability gates. Programmatic display sells impressions, but only "viewable" impressions count toward billed performance. The Media Rating Council (MRC) standard is 50% of pixels in view for 1 second (display) or 2 seconds (video). Below this threshold, the impression should not be billed. + +Fraud filters. Programmatic exposes fraud-detection metrics. Without fraud filtering, 10 to 30% of programmatic impressions are bot or fraudulent traffic. Use vendors like DoubleVerify or IAS for filtering. + +Attribution decay. Programmatic display's incremental rate is usually 5 to 20%. Most clicks come from users who would have converted from other channels anyway. Treat programmatic as awareness; do not optimize for direct response unless the incrementality test confirms it. + +--- + +## Cross-platform interference + +A specific quirk worth a dedicated callout. + +The mechanism. Two platforms claim the same conversion. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). The same revenue event shows up twice in the platform totals. + +The detection. Sum-of-platforms exceeds total conversions in the warehouse. If platform-reported sum is 1.5 to 3x the warehouse total, you have heavy cross-platform double-counting. + +The defense. Warehouse as canonical for board reporting. Platform reports for in-flight tuning of the platform's own levers. MMM at scale to estimate true cross-channel contribution. + +--- + +## Reporting differences in numbers + +A typical mid-stage account has the following attribution gap pattern across platforms. + +- Google Ads reports: 1.3 to 1.5x what GA4 reports for the "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA4 reports for the "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA4 for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA4 reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/dist/pi/.agents/skills/after-action-report/SKILL.md b/dist/pi/.agents/skills/after-action-report/SKILL.md new file mode 100644 index 0000000..d1690cc --- /dev/null +++ b/dist/pi/.agents/skills/after-action-report/SKILL.md @@ -0,0 +1,282 @@ +--- +name: after-action-report +description: "Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings." +category: operations +catalog_summary: "Post-mortems, retros, learnings documentation" +display_order: 3 +--- + +# After-Action Report + +Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document. + +This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`. + +--- + +## When to use + +- After any incident (any severity) +- After every major launch +- At the end of a project (sprint retro, quarterly retro, project closeout) +- When a recurring issue has happened enough times to demand investigation +- When a decision didn't work out and the team wants to learn + +## When NOT to use + +- During an active incident (use `incident-response`) +- For pre-launch planning (use `launch-runbook`) +- For one-off bug fixes that don't merit broad analysis + +--- + +## Required inputs + +- The event being analyzed (incident, launch, project) +- A timeline reconstructed from logs, chat, tickets +- Participant accounts of what they observed and did +- Outcomes and impact (what actually happened to users, the business) + +--- + +## The framework: blameless analysis + +The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones. + +### What blameless means + +- Focus on systems, not individuals +- Assume everyone made reasonable decisions given what they knew at the time +- The question is "why was this decision reasonable to make?" not "who screwed up?" +- Fixing the system means the next person in that situation succeeds where this person didn't + +### What blameless does not mean + +- No accountability (action items still have owners) +- No hard truths (sometimes the system is broken in obvious ways) +- No standards (some patterns of failure are individual, not systemic) +- No discomfort (real reflection is uncomfortable) + +--- + +## The framework: 6 sections + +A complete AAR covers six sections. + +### 1. Summary + +A 2 to 3 paragraph overview. Captures: + +- What happened +- Impact (users, business, time) +- Root cause (in plain language) +- Top action items + +This is what executives read. Anyone who reads only this section should leave with the most important information. + +### 2. Timeline + +A reconstructed timeline of events. + +For incidents: +- T-0: Detection +- T+X: Acknowledgment +- T+Y: Severity assessed, IC assigned +- T+Z: Investigation began +- ... mitigation, communication, resolution events +- T+N: Resolution declared + +For launches: +- Pre-launch decisions and milestones +- Launch day events +- Post-launch monitoring observations + +For projects: +- Major milestones, decisions, pivots +- Both planned and emergent + +The timeline is the source of truth. Disagreements about what happened get resolved here. + +### 3. Root cause analysis + +What caused this, in plain language. + +Use one or both of: + +Five whys. Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology. + +Example: +- Why did the site go down? Database connection pool exhausted. +- Why was the pool exhausted? Background job opened too many connections. +- Why did the background job open too many connections? Connection cleanup code didn't run on errors. +- Why didn't cleanup run on errors? Original code review didn't cover error paths. +- Why didn't the review cover error paths? No checklist for error handling in our review process. + +The fifth why often reveals the system fix. In this case: improve the review process. + +Causal chain. Multiple contributing factors that combined. + +- Factor 1: Background job opened too many connections (technical) +- Factor 2: Connection limit was set too low for actual traffic (configuration) +- Factor 3: No alert on connection pool saturation (monitoring) +- Factor 4: Recent traffic doubled without infra capacity review (process) + +No single fix addresses the incident. Multiple gaps need attention. + +### 4. Contributing factors + +Factors that didn't cause the event but made it worse, or removed safety nets that would have caught it. + +- Monitoring gaps +- Documentation gaps +- Process gaps +- Tooling gaps +- Knowledge gaps + +A "would have been caught earlier if..." factor. + +### 5. What went well + +Real lessons require capturing successes, not just failures. + +- What detection worked? +- What response worked? +- What decisions were good? +- What tools or processes performed as expected? + +This is not consolation. It's calibration. Things that worked here should be reinforced and replicated. + +### 6. Action items + +Specific, owned, dated. + +\| Action \| Owner \| Due \| Type \| +\|---\|---\|---\|---\| +\| Add alert on connection pool saturation \| [name] \| [date] \| Monitoring \| +\| Add error handling checklist to PR template \| [name] \| [date] \| Process \| +\| Audit other background jobs for similar issue \| [name] \| [date] \| Code \| + +Action item criteria: + +- Specific. "Improve monitoring" is not actionable. "Add alert on connection pool saturation, threshold 80%, page on-call" is. +- Owned. A name. Not "the team." +- Dated. A real date. Not "soon." +- Sized. Roughly hours, days, or weeks of effort. +- Closeable. Definition of done is clear. + +Action items that don't close in their committed timeframe should re-surface in the next AAR. Patterns of unclosed actions point to deeper organizational issues. + +--- + +## Workflow + +### 1. Schedule the AAR + +Within 1 to 2 weeks of the event. Long enough that emotions cooled and facts gathered. Short enough that memories are fresh. + +For incidents: pre-decided in the response procedure. +For launches: schedule on the runbook. +For projects: schedule at project closeout. + +### 2. Gather inputs + +Before the meeting: + +- Reconstructed timeline (often the scribe's notes if there was one) +- Logs, chat transcripts, tickets, incident updates +- Individual accounts from each participant (written, before the meeting) +- Impact data (users affected, duration, revenue impact, etc.) + +### 3. Run the meeting + +Typical agenda (60 to 90 minutes): + +- Read the summary as drafted (5 min) +- Walk the timeline together. Add corrections. Resolve disagreements. (20 to 30 min) +- Discuss root cause. Use five whys or causal chain. (15 to 20 min) +- Discuss contributing factors. (10 min) +- Discuss what went well. (10 min) +- Identify action items. Owners and dates. (10 min) + +A facilitator runs the meeting. Often the IC for an incident, or a project lead for a project. The facilitator is not the scribe. + +### 4. Write the document + +Within a few days of the meeting. The full AAR includes all 6 sections. + +### 5. Distribute + +Internal: post in a known location. Make searchable. Reference in onboarding. + +For high-severity incidents: external summary may be appropriate (status page, customer email, public blog). + +### 6. Track action items + +Every action item should be tracked to closure. The next AAR re-surfaces unclosed ones. + +--- + +## Failure patterns + +- Skipping the AAR for "small" incidents. Patterns get missed. +- Naming and shaming. Real lessons get hidden when people fear blame. +- Generic action items. "Improve testing" instead of specific testing change. +- Action items that never close. Filed, forgotten. Same incident recurs. +- Theater retrospectives. Going through the motions without genuine reflection. +- Skipping "what went well." Misses calibration on what's working. +- Blame externalized. "Our vendor failed." OK, what's our system for vendor risk? +- Single-person AAR. One person writes the whole thing. Misses other perspectives. +- AAR only for failures. Successful launches deserve AARs too. Lessons from success are valuable. +- Long delays. Memories fade. Conversations cool. Get it done within 2 weeks. + +--- + +## Output format + +A markdown document at `aar-[date]-[event-name].md`. + +Structure: + +```markdown +# AAR: [Event name] + +Date of event: [YYYY-MM-DD] +AAR date: [YYYY-MM-DD] +Severity / scope: [SEV-1 / Major launch / Project closeout] +Facilitator: [Name] +Participants: [Names] + +## Summary +[2 to 3 paragraphs] + +## Impact +- Users affected: [number, segment] +- Duration: [time] +- Revenue / business impact: [if applicable] + +## Timeline +[Timestamped events] + +## Root cause analysis +[Five whys or causal chain] + +## Contributing factors +[List] + +## What went well +[List] + +## Action items +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +## Lessons +[Reflections that don't fit elsewhere. Often the most quotable section.] +``` + +--- + +## Reference files + +- [`references/aar-template.md`](references/aar-template.md) - Fillable AAR template covering incidents, launches, and projects. diff --git a/dist/pi/.agents/skills/after-action-report/references/aar-template.md b/dist/pi/.agents/skills/after-action-report/references/aar-template.md new file mode 100644 index 0000000..0d37d24 --- /dev/null +++ b/dist/pi/.agents/skills/after-action-report/references/aar-template.md @@ -0,0 +1,296 @@ +# AAR Template + +Fillable after-action report template. Three variations: incident AAR, launch AAR, project closeout AAR. The structure is similar; the inputs and emphasis differ. + +--- + +## Universal sections (used in all three variations) + +### Header + +```markdown +# AAR: [Event name] + +Type: [Incident / Launch / Project] +Date of event: [YYYY-MM-DD or range] +AAR date: [YYYY-MM-DD] +Severity / scope: [SEV-1 / Major launch / Project closeout] +Facilitator: [Name] +Participants: [Names] +Distribution: [Internal only / Internal + customers / Public] +``` + +--- + +## Variation 1: Incident AAR + +### Summary + +> [2 to 3 paragraphs. What happened, what was the impact, what was the root cause, what are the top action items. Should stand alone for executives who read only this section.] + +### Impact + +- Users affected: [Number and segment. "All US users" or "Approximately 12% of paid customers in EU."] +- Duration: [Detection to resolution] +- Severity: [SEV-1 / 2 / 3 / 4] +- Revenue impact: [If quantifiable] +- Customer-facing communication: [What was said, when] +- Regulatory implications: [If any] + +### Timeline + +\| Time \| Event \| Notes \| +\|---\|---\|---\| +\| T-X \| [Pre-incident state, recent deploy, etc.] \| \| +\| T-0 \| [Detection event] \| \| +\| T+5min \| [Acknowledgment] \| \| +\| T+10min \| [Severity assessed, IC assigned] \| \| +\| T+Xmin \| [Investigation milestone] \| \| +\| T+Ymin \| [Mitigation applied] \| \| +\| T+Zmin \| [Verification] \| \| +\| T+Nmin \| [Resolution declared] \| \| +\| T+Hours \| [Customer comms, post-incident] \| \| + +Timeline source: [Logs, chat, monitoring, IC notes] + +### Detection + +- How was it detected? [Alert / customer report / internal observation] +- Time to detection: [From event start to detection] +- Was detection adequate? [Should we have detected this faster? How?] + +### Response + +- Time to acknowledgment: [Detection to acknowledgment] +- Time to mitigation: [Detection to mitigation] +- Time to resolution: [Detection to resolution] +- Were the right people involved? [Yes / No, why] +- Did the response procedure work? [Yes / No, what gaps] + +### Root cause analysis + +Surface symptom: [What users experienced] + +Five whys: + +1. Why did [symptom] happen? [Answer] +2. Why did [Answer 1] happen? [Answer] +3. Why did [Answer 2] happen? [Answer] +4. Why did [Answer 3] happen? [Answer] +5. Why did [Answer 4] happen? [Answer - often the system fix] + +Or, causal chain (multiple contributing factors): + +- Factor 1 (technical): [Description] +- Factor 2 (configuration): [Description] +- Factor 3 (process): [Description] +- Factor 4 (monitoring): [Description] + +### Contributing factors + +What didn't cause this but made it worse, or removed safety nets: + +- [Factor] +- [Factor] +- [Factor] + +### What went well + +- [Detection mechanism that worked] +- [Decision that was correct] +- [Tool that performed as designed] +- [Communication that was effective] + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| [Name] \| [Date] \| Monitoring \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Code \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Process \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Documentation \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Training \| Open \| + +### Lessons + +[Reflections beyond the action items. Often the most-quoted section in the long term.] + +--- + +## Variation 2: Launch AAR + +### Summary + +> [2 to 3 paragraphs. What launched, did it go well, what surprised us, what should we do differently next time.] + +### Outcomes + +- What launched: [Specific scope] +- Launch window: [Planned vs actual] +- Maintenance time: [If applicable] +- Issues during launch: [Count and severity] +- Rollback?: [Yes / No] +- Post-launch incidents: [In the first 7 days] +- Business outcomes: [If measurable, e.g., conversion impact] + +### Timeline + +\| Time \| Event \| Notes \| +\|---\|---\|---\| +\| Pre-launch \| [Major decisions, milestones] \| \| +\| Launch start \| \| \| +\| Cutover steps \| [Each step with timing] \| \| +\| Verification \| \| \| +\| Public announcement \| \| \| +\| First 24 hours \| [Notable observations] \| \| +\| First week \| [Notable observations] \| \| + +### What went according to plan + +- [Step that worked exactly as runbook described] +- [Communication that was clear] +- [Decision that proved correct] + +### What deviated from plan + +- [Deviation, why, what we did] +- [Deviation, why, what we did] + +### What surprised us + +- [Unexpected observation] +- [Unexpected user behavior] +- [Unexpected technical behavior] + +### What we'd do differently + +- [Change to runbook for next launch] +- [Change to pre-launch QA] +- [Change to communication plan] + +### What we'd repeat + +- [Practice that worked, want to keep] + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| \| \| \| \| + +### Lessons + +[Reflections.] + +--- + +## Variation 3: Project closeout AAR + +### Summary + +> [2 to 3 paragraphs. What we set out to do, what we delivered, what we learned, what comes next.] + +### Goals vs outcomes + +\| Goal \| Outcome \| Notes \| +\|---\|---\|---\| +\| [Original goal 1] \| [Met / Partially met / Not met] \| [Notes] \| +\| [Original goal 2] \| [Met / Partially met / Not met] \| [Notes] \| +\| [Original goal 3] \| [Met / Partially met / Not met] \| [Notes] \| + +### Timeline + +\| Phase \| Planned \| Actual \| Variance \| +\|---\|---\|---\|---\| +\| Discovery \| \| \| \| +\| Design \| \| \| \| +\| Build \| \| \| \| +\| QA \| \| \| \| +\| Launch \| \| \| \| + +### What went well + +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] + +### What didn't go well + +- [Pain point with system-level explanation] +- [Pain point with system-level explanation] + +### What surprised us + +- [Surprising input from users / market / internal] +- [Surprising scale / complexity / opportunity] + +### What we'd do differently + +For people working on similar projects in the future: + +- [Specific change] +- [Specific change] +- [Specific change] + +### Decisions in retrospect + +\| Decision \| Was it right? \| Why or why not \| +\|---\|---\|---\| +\| [Major decision 1] \| \| \| +\| [Major decision 2] \| \| \| +\| [Major decision 3] \| \| \| + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| \| \| \| \| + +### Lessons + +[Reflections.] + +### Recommendations for next phase + +[If the project continues. Otherwise, recommendations for what builds on this work.] + +--- + +## Universal facilitator guide + +### Before the meeting (pre-work) + +- Send the timeline draft to all participants +- Ask each participant to write their personal account of what they observed and did (1 to 2 paragraphs each) +- Compile contributing data: logs, metrics, ticket counts, customer feedback +- Send participants the agenda 24 hours in advance + +### During the meeting + +- Set the tone in the first 60 seconds: "This is blameless. Focus on systems, not individuals." +- Walk the timeline. Add corrections from participants. +- For root cause: ask "why" until the answers stop being substantive. Note when it shifts from technical to process. +- For action items: insist on specificity, owner, date. +- Don't let the meeting become a debugging session. Investigation happened before; this is for analysis. +- Capture the document live where possible. Edits in real time prevent recall errors. + +### After the meeting + +- Polish the document within 48 hours +- Distribute to broader audience +- File action items into a tracking system +- Schedule follow-up to verify action items closed (typically 30 days out) + +--- + +## Common AAR anti-patterns + +\| Anti-pattern \| What it looks like \| Better \| +\|---\|---\|---\| +\| Naming and shaming \| "Sarah deployed the bug" \| "Our review process didn't catch the issue. Why? What checklist or test would have?" \| +\| Generic actions \| "Improve testing" \| "Add a test for X scenario to the existing test suite by [date]" \| +\| No follow-through \| Action items filed, never tracked \| Action item review at next AAR; pattern of unclosed items surfaces \| +\| Skipping success \| Only failures discussed \| Equal time to what went well \| +\| Sole authorship \| One person writes the AAR \| Group discussion + sole author for polish \| +\| Long delay \| AAR happens 2 months later \| AAR within 2 weeks of event \| +\| Skipping minor incidents \| "Not worth the time" \| Patterns hide in the minors \| diff --git a/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md b/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md new file mode 100644 index 0000000..d04119e --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/SKILL.md @@ -0,0 +1,281 @@ +--- +name: ai-content-collaboration +description: "How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy." +category: content +catalog_summary: "How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production" +display_order: 8 +--- + +# AI Content Collaboration + +A senior editorial leader's playbook for how humans and AI compose in content workflows. Pragmatic, tool-agnostic, honest about both what AI in the loop enables and what it threatens. + +Most content programs in 2026 use AI somewhere in the workflow. Pretending otherwise is dishonest; treating AI as a magic content factory is the failure mode this skill exists to prevent. The discipline is in between: knowing where AI legitimately accelerates, where humans must own, what hybrid patterns produce work that earns reader trust, and what crosses the line into AI slop or intellectual dishonesty. + +This skill is the WORKFLOW layer that composes with every other content skill. Briefs can be AI-assisted; hub architectures can be AI-assisted; programmatic SEO is almost always AI-involved; editorial QA now includes AI-content audit by necessity. The collaboration discipline applies to all production stages, not to a single artifact type. + +The voice is pragmatic and tool-agnostic deliberately. The methodology applies whether the AI in your loop is one of the major commercial models, an open-source model, or whatever ships next quarter. What stays constant is the workflow shape, the participation boundaries, the voice ownership question, and the ethical frame. What changes is which specific tool you reach for, which is implementation work that varies by team and budget. + +When to use this skill: building or refining an AI-content workflow, calibrating a team on consistent AI usage, addressing the "we use AI but our work feels generic" problem, designing disclosure policies, or working through the ethics of AI-assisted content production for a regulated or trust-sensitive context. + +--- + +## What this skill is for + +This skill spans the workflow layer of AI-assisted content production. It composes with all six other content-suite skills as the cross-cutting discipline. + +- `content-strategy` is program scope: what to produce. Strategy decisions can be AI-assisted; the program-level judgment stays human. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. Hub architecture can be AI-suggested; the architectural commitment stays human. +- `content-brief-authoring` is per-piece scope: briefs each piece. Briefs can be AI-drafted from research; the contract decisions stay human. +- `content-and-copy` is execution scope: writes each piece. Drafts can be AI-produced; voice and editorial judgment stay human. +- `programmatic-seo` is scaled scope: generates pages from data. AI generation is the dominant production model; sampling QA is the human gate. +- `editorial-qa` is gate scope: verifies before publish. AI-content audit is now a load-bearing gate; the audit's judgment stays human. +- This skill is workflow scope: how the human and AI layers compose across all six stages above. + +The audience: editorial leaders, content directors, content ops managers, agencies running AI-assisted production, in-house teams calibrating AI usage across writers. The voice is senior editorial leader to junior editor or content marketer. Pragmatic, honest, tool-agnostic. + +What is not in scope: specific prompts (those are implementation; teams develop their own), specific tool endorsements (the methodology applies regardless of which tool is in the loop), specific integration code (varies by stack and team). Tool categories appear when they earn methodology relevance; specific tools appear only as illustrations of categories, never as recommendations. + +--- + +## Humans own, AI accelerates + +The keystone framing. + +The pathology to avoid is treating AI as either a magic content factory (cheap, fast, scaled, output quality optional) OR as a forbidden intruder (purity gospel that does not survive contact with deadlines). Both readings produce bad work. + +The discipline that produces durable work: humans own the content; AI accelerates the work. Specifically: + +Humans own. Editorial judgment, voice, distinctive POV, fact accuracy, ethical decisions, what to publish versus what to kill, brand voice, narrative arc, tone calibration, reader empathy, claim verification. + +AI accelerates. Research synthesis, draft generation against a brief, copy edit suggestions, alternative phrasings, summary, transcription, quality-control automation at scale. + +The line. AI does work that the human directs and verifies. AI does NOT make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +The litmus test. If your AI-assisted piece publishes without a human being able to defend every claim, every position, and every word, you have crossed the line. The piece is AI's work, dressed in your byline. Readers eventually notice. + +--- + +## Where AI legitimately participates + +A non-exhaustive list of stages where AI in the loop is fine and often improves the work. + +- Research synthesis. AI condenses long-form sources into briefs the writer reads. Saves hours; the writer still reads and verifies. +- Outline generation against a brief. AI proposes an H2 / H3 structure from a brief; the editor approves or restructures. +- First-draft generation. AI produces a draft against an explicit brief; the human edits substantially. +- Alternative phrasings. AI offers 3 versions of a sentence; the human picks one or rewrites. +- Copy edit suggestions. AI catches typos, awkward phrasings, repetition. +- Summary and abstraction. AI condenses long pieces into TL;DRs. +- Transcription. AI transcribes interview audio; the human verifies. +- Translation drafts. AI produces a translation draft; a native speaker reviews and corrects. +- Quality-control automation at scale. AI flags pages in a programmatic SEO set that need human review. +- Idea generation. AI proposes 30 angles; the human picks 3. + +In each case, AI accelerates work the human still owns. The acceleration is real; the ownership stays unchanged. + +Detail in [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md). + +--- + +## Where humans must own + +The boundary list. + +- Editorial judgment. What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. +- Voice. Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution. +- Fact verification. Every claim, every statistic, every quote, every named person. AI hallucinates; humans verify. +- Ethical decisions. What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. +- Reader empathy. What the reader actually needs from this piece, not what the algorithm scores well. +- Quote attribution. Real people who actually said the thing, with consent where relevant. +- Tone calibration on hard topics. Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. +- Narrative arc. How the piece unfolds, where the reader's attention goes. AI produces shapes; humans choose them. +- Final approval. The human who signs off is accountable for what shipped. + +The "human in the loop" framing is necessary but insufficient. A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. Ownership requires the human to have made the actual decisions the piece embodies. + +--- + +## Hybrid workflow patterns + +Five patterns that work, with tradeoffs. + +1. AI-first draft, human-edit-heavy. AI produces a 90% draft; the human spends 60% of the time editing. Output: efficient for high-volume editorial; risks generic voice if editing is light. + +2. Human-first outline + research, AI-draft, human-rewrite. Human builds the outline and gathers research; AI drafts within that scaffold; human rewrites in voice. Output: preserves voice better; slower than AI-first. + +3. AI-as-research-assistant, human-writes. AI condenses sources into a brief; human writes the entire piece from the brief. Output: highest voice fidelity; slowest. + +4. Human-writes, AI-as-editor. Human drafts; AI suggests edits, alternative phrasings, copy edits; human accepts or rejects. Output: writer voice preserved; AI catches details. + +5. AI-generates-at-scale, human-samples. For programmatic SEO. AI generates thousands of pages; human samples 50 to 200 with editorial-qa discipline. Output: scaled production; depends entirely on template quality and sampling discipline. + +The pattern that fits depends on volume, voice sensitivity, team skill, and time budget. No pattern is "the right one"; pattern selection is a real decision that should match the production context. + +Detail in [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md). + +--- + +## Voice ownership preservation + +Voice is the dominant casualty of careless AI workflows. The patterns that preserve voice. + +- Voice guidelines as prompt input. Every AI generation includes the brand voice guidelines as context. Generic AI defaults regress without this. +- Sample text as voice anchor. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. +- Mid-draft voice check. At the halfway mark of a long piece, have a human or a separate AI pass read for voice drift. Long AI generations regress halfway through almost always. +- Final pass in human voice. The human edits the closing sections in their own voice; this is where the piece's emotional register often lands. +- Reject the bland. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The honest framing. Voice is the hardest thing to preserve in AI-assisted work and the easiest thing to lose. Programs that do not actively preserve voice end up with content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +Detail in [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md). + +--- + +## The AI slop problem + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. Cross-reference `editorial-qa`'s ai-content-audit-patterns reference for the detection patterns; this section addresses prevention. + +Patterns that produce slop. + +- AI does too much of the work (no real human direction or rewriting) +- Generic prompts (no brand voice context, no audience specificity, no anti-pattern guidance) +- No editorial judgment in the loop (AI generates, human glances, ship) +- Volume prioritized over quality (10x more pages can mean 10x more slop, not 10x more value) +- No iteration (first draft ships; no rewrite for voice) + +Patterns that prevent slop. + +- Strong briefs (per `content-brief-authoring`) +- Voice guidelines as prompt context +- Heavy human editing pass +- Iteration: AI draft, then human rewrite, then AI suggestions, then human final +- Editorial judgment at every gate + +The reader-detection problem. Readers can often sense AI-flavored content even when they cannot articulate why. Generic openings, predictable structures, "perfect" grammar that is emotionally flat. Slop loses reader trust over time even when individual pieces are not penalized. + +Detail in [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) and cross-reference editorial-qa's audit patterns. + +--- + +## Disclosure and transparency + +When should AI usage be disclosed to readers? + +The tiered framework. + +- Always disclose. Journalism, news reporting, attributed expert opinion, content where AI tools are the subject. +- Default disclosure (consider context). Thought leadership where the byline is doing trust work, regulated industries, content that influences purchase decisions. +- Generally not necessary. Marketing copy, descriptive product content, programmatic data pages, copy edit assistance only. +- Clearly fine without disclosure. AI as research assistant only; AI for transcription; AI for spelling and grammar suggestions. + +The principle. Disclose when the reader's understanding of the content's origin would change their trust in it. A bylined opinion piece purportedly by a named expert that is substantially AI-drafted is a trust violation; a product description on an ecommerce site that was AI-drafted is not. + +Disclosure language patterns (when used). + +- "AI tools assisted in research and drafting; the author edited and verified all claims." +- "This piece was generated programmatically from [data source]; reviewed by [team] before publish." +- Avoid hedging language like "may have used AI" or "could have been AI-assisted"; be specific or omit. + +Industry-specific norms vary. Major journalism organizations have published explicit AI usage standards. Content marketing has weaker norms but is moving toward disclosure for high-trust pieces. + +Detail in [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md). + +--- + +## Team training and calibration + +Inconsistent AI usage across a team produces inconsistent output. The discipline. + +- Documented AI policy. Which uses are approved, which require explicit permission, which are prohibited. +- Calibration sessions. Editors review AI-assisted pieces from multiple writers, surface differences, agree on standards. +- Voice library updates. As voice evolves, the prompts and sample text fed to AI evolve with it. +- Quality benchmarks. What does "AI-assisted but on-voice" look like for your brand? Document it with examples. +- Tool standardization or intentional pluralism. Team uses one tool consistently OR documents which tools fit which tasks. +- Forbidden patterns list. This team does not use AI for X (whatever X is for your context). +- Onboarding. New writers learn the AI policy and calibration in their first 2 weeks. + +The pathology. AI usage emerges informally, every writer develops their own patterns, output drifts, editors cannot pinpoint why pieces feel off. The discipline is making AI usage explicit, calibrated, and documented. + +Detail in [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md). + +--- + +## Ethics: training data, attribution, intellectual honesty + +AI tools were trained on copyrighted material. That is the simple ethical reality of every major LLM in 2026. The catalog's position on this question is not "AI use is unethical" (that would render the catalog itself hypocritical) but "intellectual honesty about AI involvement is non-negotiable." + +The principles. + +- Do not pass AI work as fully human-written. Bylined content where the byline implies human craft requires substantial human craft. +- Do not claim AI did not help when it did. False denials are worse than disclosure. +- Do not generate content that closely mirrors copyrighted source material. AI tools can produce near-replicas of training data when prompted carelessly; humans verify originality. +- Attribute when borrowing. Ideas, frameworks, statistics that came from specific sources get cited. +- Do not fabricate quotes or expertise. Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. +- Be honest about AI capabilities and limits. Do not oversell AI as more capable than it is. + +The intellectual-honesty frame supersedes any specific policy debate. Teams that treat AI usage with intellectual honesty produce content readers can trust over time. Teams that hide, deny, or rationalize lose trust eventually. + +Detail in [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md). + +- "We used AI and the content feels generic." Voice not preserved; not enough human rewriting. +- "Hallucinated facts made it to publish." Fact-verification gate skipped or rushed. +- "Different writers produce wildly different AI-assisted output." No team calibration. +- "Our AI-assisted SEO content got penalized." Slop volume plus thin templates plus no QA discipline. +- "We cannot tell what was AI versus human." No AI usage tracking; teams should document at the workflow level. +- "Readers complained about AI-flavored content." Slop reaching audience; intensify human craft pass. +- "We disclosed AI usage and lost credibility." Depends on context; disclosure is sometimes a trust gain, sometimes a loss; calibrate to audience norms. +- "Our AI tools changed and our content shifted." Over-coupled to one tool's specific behavior; methodology should be tool-agnostic. +- "We are producing 10x more content but the same audience growth." Volume was not the constraint that was binding; quality was. +- "The team is using AI inconsistently." Calibration sessions overdue. +- "An expert byline turned out to be substantially AI-drafted." Ethics breach; correct, disclose, recalibrate. + +--- + +## The framework: 12 considerations for AI content collaboration + +When designing or auditing an AI-assisted content workflow, walk these 12 considerations. + +1. Humans own; AI accelerates. Make this explicit in your workflow, not implicit. +2. Participation boundaries. Document where AI legitimately helps, where humans must own. +3. Hybrid pattern selection. Match the pattern to volume, voice sensitivity, time budget. +4. Voice guidelines as prompt input. Every AI generation includes brand voice context. +5. Voice drift sampling. Long pieces drift mid-way; sample throughout. +6. Fact verification gate. Every claim, every quote, every stat verified before publish. +7. AI slop prevention. Heavy human editing, strong briefs, iteration. +8. Disclosure tiering. Disclose when origin would change reader trust; calibrate to audience. +9. Team calibration. Documented policy, calibration sessions, voice library. +10. Tool-agnostic methodology. Workflow shape stays constant as tools change. +11. Ethical floor. Intellectual honesty, no fabrication, no hidden AI in trust-sensitive work. +12. Final accountability. The human who signs off is accountable; AI does not sign off. + +The output of the framework is a workflow document the team can reference: AI participation rules named, hybrid pattern selected, voice preservation patterns specified, disclosure tier set, calibration cadence committed, ethical floor articulated, accountable signer named for each piece. + +--- + +## Reference files + +- [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md) - Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. +- [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md) - Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. +- [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md) - Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. +- [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) - What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. +- [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md) - Tiered disclosure framework, language patterns, industry norms. +- [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md) - Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. +- [`references/quality-calibration-with-ai-in-loop.md`](references/quality-calibration-with-ai-in-loop.md) - How editorial standards shift when AI is in the workflow. Same standards, different failure modes. +- [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md) - Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. +- [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: collaboration, not replacement + +AI in content workflows is neither magic nor menace. It is a category of tooling that, like every tooling category before it, rewards disciplined use and punishes careless use. The teams producing memorable AI-assisted content are the ones holding the line on human ownership, voice, fact accuracy, and intellectual honesty. The teams producing AI slop are the ones treating AI as a content factory. + +The discipline is not anti-AI; it is pro-craft. Craft was always what made content worth reading; AI does not change that, it just raises the cost of skipping it. + +When in doubt about whether an AI-assisted workflow is ready, ask: is human ownership specified, are participation boundaries documented, is voice preservation built into the prompt and review patterns, is fact verification a halt-condition, is disclosure tiered to audience trust, is the team calibrated, and is the ethical floor explicit? If yes to all of those, the workflow is ready. If no to any, the gap is where the program will produce slop and lose reader trust. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md new file mode 100644 index 0000000..0d6b20a --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-participation-boundaries.md @@ -0,0 +1,131 @@ +# AI participation boundaries + +Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. + +The boundary list below is the operational expression of the keystone framing: humans own the content, AI accelerates the work. The list is not exhaustive; the principle is: AI does work the human directs and verifies, AI does not make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +--- + +## Where AI legitimately participates + +### Research synthesis + +AI condenses long-form sources (papers, interviews, prior reports, internal docs) into a research brief. The writer reads the brief, follows up on the citations the brief surfaced, and verifies anything that will become a load-bearing claim in the piece. + +The acceleration: hours of reading become minutes of reviewing. The retained ownership: the writer judges what is worth using, where the source is questionable, what additional research is needed. + +### Outline generation against a brief + +AI proposes an H2 / H3 structure based on the content brief and SERP analysis. The editor approves the outline, restructures it, or rejects it. + +The acceleration: the writer starts from a structure that fits the brief instead of from a blank page. The retained ownership: the editor decides whether the structure fits the audience and the publication. + +### First-draft generation + +AI produces a draft against an explicit brief. The human edits substantially. + +The acceleration: a 1,500-word draft in minutes that the human revises rather than composing from scratch. The retained ownership: the human chooses what to keep, what to rewrite, what to cut, what to add. A draft that ships unchanged is not collaboration; it is rubber-stamping. + +### Alternative phrasings + +AI offers 3 versions of a sentence, paragraph, or headline. The human picks one or rewrites. + +The acceleration: faster surfacing of options the writer might not have considered. The retained ownership: the writer chooses the option that fits the voice and the context. + +### Copy edit suggestions + +AI catches typos, awkward phrasings, repetition, weak connections between paragraphs. + +The acceleration: faster than a manual copy edit pass. The retained ownership: the editor decides which suggestions to accept; some of what AI flags as awkward is actually deliberate stylistic choice. + +### Summary and abstraction + +AI condenses long pieces into TL;DR summaries, executive summaries, or social media captions. + +The acceleration: faster TL;DR generation; useful for content systems that produce summaries at scale. The retained ownership: the human verifies the summary captures what matters and does not flatten the piece's distinctive points. + +### Transcription + +AI transcribes interview audio. The human verifies the transcription against the audio for accuracy, especially on names, technical terms, and quoted positions. + +The acceleration: hours of transcription become minutes of verification. The retained ownership: the human is responsible for what gets attributed; transcription errors that misquote sources are the human's accountability to catch. + +### Translation drafts + +AI produces a translation draft. A native speaker reviews and corrects. + +The acceleration: a translation starting point in seconds. The retained ownership: the native speaker is the source of truth on idiomatic correctness, cultural context, and brand-voice translation. + +### Quality-control automation at scale + +AI flags pages in a programmatic SEO set that need human review (per `editorial-qa`'s sampling discipline). + +The acceleration: automated check on every page; manual review focused on the flagged subset. The retained ownership: the editor decides what counts as a fail; the AI flags candidates, the human judges. + +### Idea generation + +AI proposes 30 angles on a topic; the human picks 3. + +The acceleration: faster brainstorm. The retained ownership: the human chooses which angles fit the brand and the audience. + +--- + +## Where humans must own + +### Editorial judgment + +What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. The judgment requires audience knowledge, brand context, and quality standards the AI does not have. + +### Voice + +Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution that the AI can mimic if shown samples but cannot originate. + +### Fact verification + +Every claim, every statistic, every quote, every named person. AI hallucinates plausible-but-fake claims; humans verify against authoritative sources. Fact verification is a halt-condition gate; pieces with unverified claims do not ship. + +### Ethical decisions + +What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. Ethics requires context, audience awareness, and accountability that the AI does not carry. + +### Reader empathy + +What the reader actually needs from this piece, not what the algorithm scores well. The reader's situation, knowledge, and emotional context shape the piece's job; the AI cannot model the specific reader the way a writer who has spent time with the audience can. + +### Quote attribution + +Real people who actually said the thing, with consent where relevant. AI hallucinates quotes; humans verify against the source. + +### Tone calibration on hard topics + +Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. A piece on bereavement should not read as if a chatbot wrote it. + +### Narrative arc + +How the piece unfolds, where the reader's attention goes, what the climax is, what the resolution is. AI produces shapes; humans choose them. + +### Final approval + +The human who signs off is accountable for what shipped. Accountability cannot be delegated to AI; the byline and the editorial chain stop at humans. + +--- + +## "Human in the loop" is not ownership + +The phrase "human in the loop" appears in many AI workflows. It is necessary but insufficient. + +A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. The piece's substance, voice, and judgment are still AI-produced; the human's role is signature only. + +Ownership requires the human to have made the actual decisions the piece embodies. Specifically: the human chose the angle, the human verified the facts, the human enforced the voice, the human made the editorial judgment calls that distinguish this piece from the AI's default output. + +The test. Could the human defend every claim, every position, and every word in the piece? If yes, the human owns it. If no, the human is rubber-stamping. + +--- + +## Methodology-level choices that stay in the public skill + +The list of where AI legitimately participates, the list of where humans must own, the "human-in-the-loop versus ownership" distinction, the verification-and-defense litmus test. + +## Implementation choices that stay internal + +The specific AI tools the team uses for each participation category (research synthesis tool, drafting tool, copy edit tool, transcription tool, translation tool, QC automation tool). The specific prompts the team has developed for each task category. The specific tracking system that records which AI participated in which piece. The specific review workflows that gate publish. These vary by team and stack. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md new file mode 100644 index 0000000..4e3df19 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md @@ -0,0 +1,134 @@ +# AI slop detection and avoidance + +What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. The detection patterns live in `editorial-qa/references/ai-content-audit-patterns.md`. This reference addresses prevention: what production patterns produce slop, what production patterns prevent it. + +--- + +## Patterns that produce slop + +### AI does too much of the work + +The pattern. The AI generates the entire piece; the human glances at it and ships. The piece reads as model-default because no human substantively rewrote it. + +The signal. Pieces ship in less time than they would take a human to write from scratch. Speed is not the problem; the problem is that the speed comes from skipped craft. + +### Generic prompts + +The pattern. The prompt is "write a 1,500-word blog post about X." No brand voice, no audience specificity, no anti-pattern guidance. The AI generates the most common kind of post about X, which is by definition generic. + +The signal. Prompts can fit in one sentence. Prompts that produce on-voice output are typically multi-paragraph, with voice guidelines, sample text, audience description, and anti-pattern lists. + +### No editorial judgment in the loop + +The pattern. The workflow is "AI generates, human reviews quickly, ship." The reviewer is not making editorial decisions; they are spell-checking. Whether the piece is good enough to publish, whether it answers the user's actual question, whether it reflects brand POV are not asked. + +The signal. The team cannot articulate the editorial judgments made on a piece because those judgments did not happen. Pieces ship with no halt-decisions, no rewrites, no "this piece does not work, kill it" calls. + +### Volume prioritized over quality + +The pattern. The team commits to publishing 50 pieces a month with the same headcount that previously produced 10. AI is the multiplier. Quality drops because the production line cannot sustain craft at the new volume. + +The signal. Publish targets defined in pieces-per-week or pages-per-month. Quality-controlled publish targets are defined differently: traffic earned, citations earned, leads converted, audience grown. Volume targets without quality targets produce slop volume. + +### No iteration + +The pattern. First draft (AI-generated) ships. No revision pass. No second draft. No "let us read this aloud and rewrite the bland sections." + +The signal. The workflow document does not include a rewrite step. Production is generation-then-publish, not generation-then-iteration-then-publish. + +--- + +## Patterns that prevent slop + +### Strong briefs + +Per `content-brief-authoring`. A brief that fills all 12 fields gives the AI enough context to produce a draft that respects audience, voice, structure, entity coverage, and success criteria. Vague briefs produce slop output regardless of how the AI is prompted. + +The discipline. Brief-adherence is the first QA gate per `editorial-qa`. AI drafts that fail brief-adherence get returned, not rubber-stamped. + +### Voice guidelines as prompt context + +Per `voice-ownership-preservation.md`. Every AI generation includes the brand voice guidelines and sample anchor text as prompt input. Without active voice prompting, AI defaults dominate. + +### Heavy human editing pass + +The discipline. The human spends substantial time editing AI drafts: rewriting flat sentences, replacing abstractions with specifics, restoring brand voice in mid-piece sections, replacing generic openings and closings with specific ones. + +The time investment. 50 to 60% of the piece's production time goes to human editing in Pattern 1 (AI-first draft, human-edit-heavy). Lower than that and the editing is light; the piece ships with AI defaults preserved. + +### Iteration + +The discipline. The workflow includes multiple revision passes: AI draft, then human rewrite, then AI suggestions for the rewrite, then human final pass. Each pass catches a different layer. + +- AI draft: structure, completeness, basic prose. +- Human rewrite: voice, specificity, claim verification, distinctive POV. +- AI suggestions: copy edit catches, alternative phrasings, repetition flagging. +- Human final: closing voice, emotional register, final polish. + +The pattern produces work that reads as human-crafted with AI assistance. Skip any pass and the piece moves toward AI default. + +### Editorial judgment at every gate + +The discipline. Each QA gate is a judgment moment, not a rubber stamp. Brief-adherence asks "did this piece execute the brief?" Voice consistency asks "does this sound like our brand?" Fact accuracy asks "is every claim verified?" Each question requires a human's actual judgment. + +The signal of editorial judgment in action. Halts happen. Pieces get sent back for revision. Some pieces get killed because they cannot be made to work. Programs that publish 100% of what they draft are not exercising editorial judgment; they are producing whatever the workflow ships. + +--- + +## The reader-detection problem + +Readers can often sense AI-flavored content even when they cannot articulate why. The signals. + +- Generic openings that could be the opening of any article on the topic +- Predictable structure (intro, three points, conclusion) +- Bullet-list overuse where prose would serve +- "Perfect" grammar that reads as emotionally flat +- Specific-but-fake details (named decimals, named sources that turn out to be fake) +- Hedge stacking that avoids commitment + +Slop loses reader trust over time even when individual pieces are not penalized by algorithm updates. Readers stop returning. Email open rates drop. Citation quality declines. The traffic numbers may hold for a year before the trust loss compounds visibly. + +The implication. Slop is not a search-engine problem; it is a reader-trust problem. Programs that optimize away from slop because of algorithm fear are missing the bigger reason: readers stop trusting the brand. + +--- + +## The slop avoidance audit + +For each AI-assisted piece, ask the following before publish. + +1. Could this piece have been published by any competitor using the same tools? If yes, the voice is not preserved. +2. Are the claims in this piece specific enough to verify? If no, the piece is hedging. +3. Does the piece take a position the reader will remember? If no, the piece is forgettable. +4. Did the human substantially rewrite, or is the AI draft mostly intact? If mostly intact, the piece is at slop risk. +5. Does the closing read as the writer's own voice? If no, the final pass was skipped. +6. Did the brief adhere to the 12-field discipline? If no, the failure is upstream. + +A piece that fails 3+ of these is slop-shaped. Halt and revise. + +--- + +## The "we are producing 10x more content but the same audience growth" pattern + +A common signal that slop has set in. The volume increased; the audience metric did not. The team often interprets this as "we need even more content"; the diagnosis is usually the opposite. + +The actual diagnosis. Volume was not the constraint. Quality was. The 10x content production has produced 10x slop, which earns less per piece and sometimes hurts the brand's overall trust signal. + +The fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## Cross-reference + +The detection patterns (AI tells, hallucination patterns, voice drift) live in `editorial-qa/references/ai-content-audit-patterns.md`. The avoidance patterns (production discipline) live here. The two skills compose: editorial-qa catches what reaches the gate; this skill prevents production patterns that produce slop in the first place. + +--- + +## Methodology-level choices that stay in the public skill + +The patterns that produce slop, the patterns that prevent slop, the reader-detection observation, the 6-question slop avoidance audit, the volume-vs-quality counter-intuition, the cross-reference to editorial-qa. + +## Implementation choices that stay internal + +The specific iteration loop the team runs (AI draft to human rewrite to AI suggestions to human final, or variations). The specific time-tracking that captures the editing-time-to-generation-time ratio. The specific prompt patterns that include voice guidelines and sample text. The specific reader-feedback channels that surface slop perception. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md b/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md new file mode 100644 index 0000000..cfabbca --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/common-collaboration-failures.md @@ -0,0 +1,165 @@ +# Common collaboration failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: the team treated AI as either a magic content factory (producing slop at scale) or as a pure-replacement-or-nothing question (producing inconsistent output as writers privately negotiated their own AI usage). The discipline is in between: humans own, AI accelerates, the workflow is documented, the team is calibrated. + +--- + +## "We used AI and the content feels generic" + +Symptom. Pieces ship technically clean but feel indistinguishable from competitors using the same tools. Audience growth flat despite consistent publishing. + +Diagnosis. Voice not preserved. Editing was light; AI defaults reached publish. The pattern that produces this: AI-first drafts with a quick review pass that catches typos but does not rewrite for voice. + +Fix. Apply the voice ownership preservation patterns (`voice-ownership-preservation.md`): voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland audit. Increase editing intensity to 50-60% of production time. + +--- + +## "Hallucinated facts made it to publish" + +Symptom. A statistic, quote, citation, or product claim in a published piece turns out to be invented. + +Diagnosis. Fact-verification gate skipped or rushed. The team trusted AI output that read as authoritative. + +Fix. Fact-accuracy as halt-condition gate per `editorial-qa/references/fact-accuracy-and-citation-discipline.md`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +--- + +## "Different writers produce wildly different AI-assisted output" + +Symptom. Two writers given the same brief and the same AI tools produce pieces that read as if they came from two different programs. + +Diagnosis. No team calibration. Each writer developed their own AI patterns; the program drifted as different patterns produced different output shapes. + +Fix. Documented AI policy, calibration sessions, voice library, quality benchmarks per `team-training-and-calibration.md`. Onboarding for new writers includes calibration. + +--- + +## "Our AI-assisted SEO content got penalized" + +Symptom. A programmatic SEO set or a high-volume editorial program loses 60-90% of traffic in an algorithm update. + +Diagnosis. Slop volume plus thin templates plus no QA discipline. The set was generating filler pages with limited human direction; the algorithm update detected the scale-without-substance pattern. + +Fix. Halt new generation. Apply QA at scale per `editorial-qa/references/qa-at-scale-patterns.md`. Sampling discipline with 5% failure threshold. Noindex pages that fail the data-depth threshold. Possibly remove the entire pSEO surface and rebuild from a stronger data source. + +--- + +## "We can't tell what was AI vs human" + +Symptom. Asked to characterize AI usage on a specific piece, the team cannot answer. Workflow logs, CMS metadata, and writer recall all yield uncertain answers. + +Diagnosis. No AI usage tracking. The workflow does not capture which AI participated in which stage. + +Fix. Add AI involvement tracking to the production workflow. The metadata captures: which workflow pattern was used, which AI tools were involved, which stages, which prompts (or prompt template versions), which human made which decisions. The tracking is the input to retrospective audits and to disclosure decisions. + +--- + +## "Readers complained about AI-flavored content" + +Symptom. Direct audience feedback (comments, support tickets, social mentions) flags content as feeling AI-generated. + +Diagnosis. Slop reaching the audience. Reader detection is real even when the team's QA does not catch it. + +Fix. Intensify the human craft pass. Audit recent pieces against the slop avoidance audit (`ai-slop-detection-and-avoidance.md`). If multiple pieces fail the audit, the production patterns need to shift: heavier human editing, more rejection-of-bland, possibly pattern shift from AI-first to AI-as-editor for higher-trust content. + +--- + +## "We disclosed AI usage and lost credibility" + +Symptom. Team added AI disclosure to a piece; audience response shifted negative. + +Diagnosis. Could be either: + +- The disclosure was for content where audience norms expect human authorship (Tier 1 or Tier 2 content per the disclosure framework); disclosure was correct but audience trust calibration is moving slowly +- The disclosure language was hedging or defensive, signaling lower commitment than direct authorship would have +- The disclosure was for content where it was unnecessary (Tier 4); the disclosure created an issue where there was none + +Fix. Calibrate disclosure to audience norms per `disclosure-and-transparency-patterns.md`. Specific language matters; defensive language reads worse than no disclosure. Consider audience-research feedback to inform per-content-type disclosure tiering. + +--- + +## "Our AI tools changed and our content shifted" + +Symptom. Team updates the AI tool or model version. Output behavior changes. Content quality shifts before the team recalibrates. + +Diagnosis. Over-coupled to one tool's specific behavior. The methodology should be tool-agnostic; the team's prompts and patterns should produce similar output across tools. + +Fix. Methodology-first calibration. The voice library, prompt templates, and quality benchmarks should be portable across tools. After tool changes, run a calibration session against the new tool to verify the methodology still produces on-voice output. If the methodology no longer works, that is a signal the methodology was over-coupled to tool-specific behavior. + +--- + +## "We're producing 10x more content but the same audience growth" + +Symptom. Team committed to a 10x content target enabled by AI. Volume hit the target. Audience growth flat or declining. + +Diagnosis. Volume was not the constraint that was binding. Quality was. The 10x volume produced 10x slop, which earns less per piece. + +Fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## "The team is using AI inconsistently" + +Symptom. Team members use different AI tools in different patterns for the same kind of work. Output varies by who picked up the assignment. + +Diagnosis. Calibration sessions overdue. Either the policy is informal (no documented standards) or the documented policy has not been reinforced through calibration. + +Fix. Quarterly calibration sessions. Tool standardization (or intentional pluralism with documented selection criteria). Onboarding refresh. The cadence is calendar-anchored. + +--- + +## "An expert byline turned out to be substantially AI-drafted" + +Symptom. A piece bylined by a named expert is publicly identified as substantially AI-drafted (sometimes by AI-detection tools, sometimes by readers familiar with the expert's actual voice). + +Diagnosis. Ethics breach. The byline implied human authorship; AI authorship was substantive; the gap between claim and reality reached the audience. + +Fix. Two parts. + +- Immediate. Correct the published piece (issue an editor's note clarifying the workflow, possibly retract and republish with appropriate disclosure). Apologize where appropriate. Recalibrate. +- Process. Restore the ethical floor: bylined expert content requires substantial human authorship. Recalibrate the team. Update the AI policy to document the floor explicitly. + +The fix is not "stop using AI." The fix is using AI consistently with the byline's implied authorship. + +--- + +## "Our AI policy is 18 months stale and references tools we no longer use" + +Symptom. Team consults the AI policy doc; the doc references tools the team migrated away from a year ago. The doc is treated as not authoritative because it is obviously dated. + +Diagnosis. Policy review cadence has slipped. The doc has not been updated as tools, capabilities, and team practices have evolved. + +Fix. Quarterly policy review. Each quarter the policy gets reviewed against current practice; updates ship; the team is briefed on the changes. The policy is a living document; staleness signals process failure. + +--- + +## "The team feels guilty about AI use but uses it anyway" + +Symptom. Team members use AI substantively but do not document, do not discuss in calibration sessions, do not include in retrospectives. AI usage is treated as something to hide. + +Diagnosis. The team has not articulated its AI ethics. Without articulation, individual writers privately negotiate their own ethics; the team accumulates ethical debt. + +Fix. Run an ethics conversation explicitly. Articulate the team's position on the six ethical floors per `ethics-and-intellectual-honesty.md`. Document where AI is used substantively. Make the workflow visible. Guilt is usually a signal of unresolved ethical questions; the resolution is articulation, not avoidance. + +--- + +## The pattern across all failures + +Most AI-collaboration failures reduce to two patterns. + +1. The team treated AI as a magic content factory. Outcome: slop, hallucinations, voice loss, audience trust decline. +2. The team failed to articulate its AI workflow explicitly. Outcome: drift, inconsistency, ethics debt, calibration failures. + +The fix in both cases is the same: explicit articulation of where AI participates, where humans own, what the discipline looks like in practice, and what the team's ethical floors are. The articulation is the work; once the work is done, individual failures become per-piece corrections rather than program-level breakdowns. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the cross-references to other reference files, the underlying-pattern observation about magic-factory thinking and unarticulated workflows. + +## Implementation choices that stay internal + +The specific tracking system the team uses for AI usage. The specific calibration session cadence. The specific ethics-policy doc and its review process. The specific tool selections and their rationale. These vary per team and brand. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md b/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md new file mode 100644 index 0000000..454370a --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md @@ -0,0 +1,170 @@ +# Disclosure and transparency patterns + +Tiered disclosure framework, language patterns, industry norms. + +When should AI usage be disclosed to readers? The answer is not "always" or "never"; it is "calibrate to context." The framework below tiers disclosure decisions by trust sensitivity. + +--- + +## The tiered framework + +Four tiers, ordered by disclosure obligation. + +### Tier 1: Always disclose + +AI usage is disclosed regardless of how light the involvement was. + +Categories. + +- Journalism and news reporting (any AI involvement, any extent) +- Bylined expert opinion (where the byline implies human authorship of the argument) +- Content where AI tools are themselves the subject (transparency about methodology is part of the topic) +- Regulated industries with explicit AI disclosure requirements (financial advice, medical content, legal content in some jurisdictions) + +Reasoning. In these categories, the reader's understanding of the content's origin is load-bearing for trust. A news story partially AI-drafted reads differently from a story fully reported and written by a journalist; readers have a right to that information. + +### Tier 2: Default disclosure (consider context) + +Disclosure is the default; opting out requires a specific reason. + +Categories. + +- Thought leadership pieces where the byline carries trust value +- Content that influences purchase decisions (reviews, comparisons, recommendations) +- Content for trust-sensitive audiences (academia, enterprise procurement, professional services) +- Long-form pieces where the audience has reasonable expectation of human craft + +Reasoning. Readers in these contexts often assume human authorship; AI involvement that is undisclosed becomes a trust violation if discovered. Disclosure is cheap; the trust hit from undisclosed-then-discovered AI involvement is expensive. + +### Tier 3: Generally not necessary + +Disclosure is allowed but not required by audience expectations. + +Categories. + +- Marketing copy (web pages, ad copy, email marketing copy) +- Descriptive product content (product descriptions, spec listings) +- Programmatic data pages (where the page is obviously data-generated) +- Internal team content (memos, internal reports) +- Copy edit assistance only (the human wrote the piece; AI suggested edits) + +Reasoning. In these categories, audience expectations do not assume specific authorship. Readers recognize the genre as functional content; AI involvement does not violate trust the way it would in a thought leadership piece. + +### Tier 4: Clearly fine without disclosure + +Disclosure is unnecessary and would feel weird if present. + +Categories. + +- AI as research assistant (the AI condensed sources; the human wrote) +- AI for transcription only (the human is the writer; the AI was a typist) +- AI for spelling and grammar suggestions (copy edit role only) +- AI as brainstorming partner where the human took the ideas and wrote independently + +Reasoning. The AI's role was so light that disclosure would imply more involvement than there was. Readers would interpret a disclosure as misleading. + +--- + +## Language patterns + +When disclosure is used, the language matters. + +### Patterns that work + +> "AI tools assisted in research and drafting; the author edited and verified all claims." + +> "This piece was generated programmatically from [data source]; reviewed by [team] before publish." + +> "The author drafted this piece; AI tools were used for copy edit suggestions." + +> "Research synthesis assisted by AI; all sources verified by the author." + +The patterns share three features: they specify what AI did, they specify what humans did, they identify the accountability party. + +### Patterns to avoid + +- Hedge language. "May have used AI" or "could have been AI-assisted" reads as covering legal bases without committing to honesty. Be specific or omit. +- Disclosure that minimizes. "AI was minimally involved" is hedging; either AI was substantively involved (disclose substantively) or it was not (no disclosure needed for Tier 4 use). +- Disclosure that overstates. "Fully written by AI" when humans rewrote 50% is dishonest in the other direction. The disclosure should match the actual AI involvement. + +### Where to place disclosure + +- Footer or byline area. Standard placement; readers find disclosure where they expect it. +- Inline at relevant points. When AI involvement varies across a piece, inline notes are clearer than a single footer note. +- Methodology section. Long pieces with substantial AI involvement benefit from a "How this piece was produced" section that explains the workflow. + +--- + +## Industry norms + +Disclosure norms vary by industry. The principle of intellectual honesty is constant; the specific expectations differ. + +Journalism. Major journalism organizations have published explicit AI usage standards. The norm is moving toward disclosure of AI involvement in any reported piece. Journalism trust depends on transparency; AI-related opacity is a fast trust violation in the audience. + +Content marketing. Norms are weaker but moving toward disclosure for high-trust pieces. Branded thought leadership is increasingly expected to disclose AI involvement; routine marketing copy is not. + +Academic and research content. AI involvement in research papers is a contested area; conferences and journals have varying policies. The conservative default is full disclosure, including which AI tools were used and at what stages. + +Regulated industries. Financial, medical, and legal content increasingly carries explicit AI disclosure requirements. The defaults here are tighter than in unregulated marketing content; consult the specific regulatory environment. + +Ecommerce and product content. Disclosure is generally not expected on product descriptions or spec listings. AI generation is genre-typical; readers do not interpret presence or absence of disclosure as meaningful. + +--- + +## When disclosure helps and when it hurts + +The honest framing. Disclosure is sometimes a trust gain, sometimes a trust loss; the calibration depends on audience norms. + +Disclosure as trust gain. + +- Audience expects human authorship; disclosure preempts trust loss from later discovery +- Brand positions itself on transparency +- Industry is moving toward disclosure as the new norm +- The piece's value is in research and verification, which AI assisted but did not replace + +Disclosure as trust loss. + +- Audience interprets AI involvement as quality reduction (sometimes a misreading, sometimes accurate) +- Disclosure language reads as defensive or hedging +- Audience expects routine content (where AI is genre-typical) + +The decision is not "always disclose" or "never disclose" but "calibrate." The calibration is best done by someone who knows the audience and the brand's positioning, not by a generic policy. + +--- + +## Disclosure policy at the program level + +The program-level discipline. Document the disclosure policy by content type. Editors and writers know which content types require disclosure; the disclosure language is templated; the policy is reviewed quarterly. + +Template policy structure. + +- Content type: [thought leadership]. Disclosure: [required]. Language template: [template]. +- Content type: [knowledge base article]. Disclosure: [optional]. Language template: [template if used]. +- Content type: [programmatic data page]. Disclosure: [not required]. +- Content type: [marketing landing page]. Disclosure: [not required]. + +The policy gets updated as norms evolve. AI disclosure norms in 2026 are looser than they will be in 2028; policy review keeps the program aligned with audience expectations. + +--- + +## When the disclosure decision is hard + +Edge cases. + +Long-running expert byline. A column under a named expert's byline, where some pieces are pure expert authorship and others are substantively AI-assisted. Disclosure on the AI-assisted pieces is the right call; the byline's trust value depends on it. + +Pillar content with mixed authorship. A pillar piece where the lede is human-written, the body is AI-drafted-then-rewritten, the closing is human-written. Disclosure language can specify the mix: "Research and core argument by the author; AI assisted in initial drafting of body sections; all claims verified." + +Internal-only content that becomes external. An internal report that gets externalized requires retroactive disclosure if the internal version was AI-assisted. Sometimes the externalization should include rewriting to bring the disclosure inline. + +The principle. When the disclosure decision is hard, default to disclosure. Trust is recoverable from over-disclosure; trust is not always recoverable from under-disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The four-tier framework, the disclosure language patterns, the industry norms summary, the trust-gain-vs-trust-loss calibration, the program-level policy structure, the edge-case handling. + +## Implementation choices that stay internal + +The specific disclosure language the team has developed for each content type. The specific tracking that records AI involvement per piece (workflow log, CMS metadata, byline annotation). The specific review cadence for the disclosure policy. The specific audience-research feedback that informs disclosure norms for the brand's specific audience. These vary by team, brand, and industry. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md b/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md new file mode 100644 index 0000000..d435d59 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md @@ -0,0 +1,154 @@ +# Ethics and intellectual honesty + +Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. + +This is the most ethically loaded reference in the catalog. The voice is honest, pragmatic, non-preachy. The catalog itself is produced with AI assistance; pretending otherwise would render any anti-AI position hypocritical. The position is not "AI use is unethical" but "intellectual honesty about AI involvement is non-negotiable." + +--- + +## Training data realities + +Every major LLM in 2026 was trained on copyrighted material. That is the simple ethical reality. + +The legal status of training-data copyright is contested in multiple jurisdictions and is being litigated. The position the catalog takes is not "AI training is ethical" or "AI training is unethical"; the position is "the question is unresolved, the tools exist, teams use them, the way to use them ethically is the question this skill addresses." + +What this skill does not relitigate. The training-data copyright question. The compute-intensity environmental question. The labor-displacement question. These are real ethical questions; this skill is not the place to resolve them. Teams reading this skill make their own choices about whether to use AI tools at all; the skill addresses how to use them with intellectual honesty when teams have made the use-AI choice. + +--- + +## Don't pass AI work as fully human-written + +The first ethical floor. + +Bylined content where the byline implies human craft requires substantial human craft. A column under a named expert's byline that is substantially AI-drafted is a trust violation regardless of whether disclosure was technically present somewhere on the page. The byline's value depends on the audience's understanding that the named human authored the piece; AI authorship that the byline obscures is dishonest. + +What "substantial human craft" requires. + +- The argument is the human's +- The voice is recognizable as the human's +- The judgments about what to include, what to cut, what to emphasize are the human's +- The fact verification is the human's +- The final approval is the human's + +What it does not require. Every word being typed by the human (research-assistant patterns are fine). Every sentence being unrewritten (copy edit assistance is fine). The human spending a specific time-on-task (the time matters less than the substance). + +--- + +## Don't claim AI didn't help when it did + +The second ethical floor. + +False denials are worse than disclosure. A team that uses AI substantially and then claims the work is fully human is staking trust on a falsifiable claim. Discovery of the AI involvement (which becomes more reliable each year as detection tools improve) compounds the trust violation: the audience now distrusts both the work and the team's honesty about the work. + +The honest pattern. If AI was used in any way that would matter to the audience, the team is honest about it. The disclosure tiering framework (per `disclosure-and-transparency-patterns.md`) addresses when disclosure is required; the no-false-denial floor is broader: even when disclosure is not required, false denial is not allowed. + +In practice. Most teams do not face direct denial questions; the issue comes up in interview contexts ("how do you produce your content?"), retrospectives, or conversations with clients and partners. The honest answer in those contexts is the truthful one, even when no public disclosure was attached to specific pieces. + +--- + +## Don't generate content that closely mirrors copyrighted source material + +The third ethical floor. + +AI tools can produce near-replicas of training data when prompted carelessly. The team's responsibility is to verify that AI-generated content is original work and not a paraphrase of a specific copyrighted source. + +The check. For each substantive section of AI-generated content, search for the unique phrasing in quoted form. If results come back to a specific copyrighted source that the AI was likely trained on, the section is too close to source material. Revise. + +The pattern. AI tools tend to mirror training data more closely on niche topics than on common topics. Common topics have many sources to blend; niche topics have fewer. Specialized content (academic topics, technical documentation, industry-specific niches) needs more careful mirroring checks. + +--- + +## Attribute when borrowing + +The fourth ethical floor. + +Ideas, frameworks, statistics, and specific phrasings that came from identifiable sources get cited. The principle is not changed by whether AI surfaced the source or whether the human did; attribution belongs to the source, not to the discovery method. + +The pattern. + +- Statistics with sources: cite the source. +- Frameworks attributed to specific thinkers: cite the thinker. +- Specific arguments traceable to a specific publication: cite the publication. +- Common knowledge: no citation needed, but verify it actually is common knowledge and not specialized knowledge that the AI surfaced from a specific source. + +The honesty test. If the team would feel uncomfortable having the source's author read the piece and recognize their work uncited, citation is required. + +--- + +## Don't fabricate quotes or expertise + +The fifth ethical floor. + +Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. The team is accountable for what gets attributed; the AI is not the accountable party. + +The pattern. AI generates plausible-but-fake quotes in 2026; that is a known limitation. The fact-accuracy gate per `editorial-qa` catches them before publish. The ethical position is broader than the QA position: even if a fabricated quote were never caught, generating it under attribution to a real person is dishonest. + +The same applies to expertise claims. AI-drafted "expert content" attributed to a named expert who did not draft it is fabricated expertise. The expert's name carries trust value; the trust depends on the expert having actually drafted the piece. + +--- + +## Be honest about AI capabilities and limits + +The sixth ethical floor. + +Do not oversell AI as more capable than it is. Do not undersell it as less capable than it is. Both produce decision-making errors in the team and in the audience. + +The pattern. AI in 2026 is genuinely useful for research synthesis, drafting against briefs, copy edit suggestions, transcription, summary, and quality-control automation at scale. AI in 2026 is genuinely limited at editorial judgment, fact verification (it is what gets fact-checked, not what does fact-checking), voice origination, ethical decisions, and reader empathy. + +Teams that get this right calibrate AI use to the limits. Teams that oversell AI ship work that exceeds AI's actual capabilities and produces hallucinations or voice failures. Teams that undersell AI miss productivity gains the technology offers. + +--- + +## The intellectual honesty frame + +The frame that supersedes specific policy debate. + +The question is not "is AI use ethical?" The question is "can the team be intellectually honest about AI use?" If yes, the team's ethics hold. If no, the team is rationalizing. + +What intellectual honesty looks like. + +- The team can articulate its AI-usage policy without defensiveness +- The team can name the specific patterns it does and does not use +- The team can defend each pattern on the merits, not just by precedent +- The team can engage with critiques of its policy without dismissing them +- The team updates its policy when reality changes (new tools, new evidence, new audience norms, new regulatory requirements) + +What intellectual dishonesty looks like. + +- Defensiveness when AI involvement is questioned +- Refusal to articulate the policy +- Dismissing critiques without engaging +- Hiding AI involvement that would be material to audiences +- Claiming AI does what it does not, or hiding that AI does what it does + +The honest team can withstand external scrutiny because its position holds up. The dishonest team eventually faces external scrutiny that surfaces the gap between claimed and actual practice. + +--- + +## When the ethical question is hard + +Edge cases. + +Ghostwritten content historically allowed. Industries where ghostwriting has always been the norm (executive thought leadership, celebrity book authorship, political speechwriting). AI assistance in ghostwriting workflows raises questions: is the ghost an AI? does the byline still mean what it meant? + +The conservative position. The byline implies human authorship; if the ghost is an AI rather than a human writer, that distinction is material to the audience and disclosure is appropriate. The aggressive position. Ghostwriting has always been a fiction the audience tolerates; AI ghostwriting is the same fiction with different tools. + +The catalog's position. Default to the conservative reading. The byline's trust value depends on audience understanding of authorship; AI ghostwriting under a named expert byline is more honest with disclosure than without. + +Educational content with structured explanations. Topics where the explanation has a canonical shape (math, basic programming, established science). AI-drafted explanations of canonical topics may closely mirror training data because the canonical shape is what the training data contains. + +The conservative position. Cite the canonical sources where they exist; rephrase substantively where citation is impractical. + +Programmatic SEO at scale. Hundreds of thousands of pages where individual disclosure is impractical and audience expectations differ from editorial content. + +The position. Programmatic content is genre-typically machine-generated; specific disclosure per page is unnecessary; transparency about the program's overall production model is appropriate at the brand level. + +--- + +## Methodology-level choices that stay in the public skill + +The training-data realities framing, the six ethical floors, the intellectual honesty frame, the edge-case handling, the conservative-vs-aggressive position taking on contested cases. + +## Implementation choices that stay internal + +The specific ethics policy the team has documented. The specific review process when an ethics question surfaces. The specific escalation pathway for ethics decisions. The specific tracking that records ethics-related decisions for retrospective review. These vary per team and brand. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md b/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md new file mode 100644 index 0000000..1f91b00 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md @@ -0,0 +1,121 @@ +# Hybrid workflow patterns + +Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. + +No pattern is "the right one." Pattern selection is a real decision that should match volume, voice sensitivity, team skill, and time budget. The wrong pattern produces predictable failures: AI-first drafts on voice-sensitive pieces produce slop; human-writes patterns on programmatic-scale work produce throughput failures. + +--- + +## Pattern 1: AI-first draft, human-edit-heavy + +The shape. AI produces a 90% draft against a brief. The human spends 60% of the production time editing: rewriting flat sentences, restructuring sections that miss the brief, adding voice and specificity, verifying facts. + +Best for. High-volume editorial where the brief is well-authored and the voice is moderately tolerant of AI defaults. SaaS blog posts, knowledge-base articles, secondary editorial pieces. + +Risks. Generic voice if editing is light. The pattern fails quietly; pieces ship with AI defaults preserved because the editor was rushed. + +Time profile. 30% AI generation, 60% human editing, 10% fact verification. Faster than human-writes for the same word count but slower than naive AI-only generation because editing time scales with the piece's length. + +When this fits. The team has clear brand voice and disciplined editors. The volume requirement is real (multiple pieces per day). The audience is tolerant of AI-assisted-but-edited content (most B2B, most consumer marketing). + +--- + +## Pattern 2: Human-first outline + research, AI-draft, human-rewrite + +The shape. Human builds the outline (or extends the brief's outline). Human gathers and verifies the research. AI drafts within that scaffold. Human rewrites in voice. + +Best for. Voice-sensitive editorial where the brand voice is distinctive enough that AI drafts need substantive rewriting anyway. The pattern formalizes the rewrite as the discipline rather than treating it as cleanup. + +Risks. Slower than AI-first drafts. If the rewrite is light, output is similar to Pattern 1. The discipline is in the rewrite intensity. + +Time profile. 20% human research and outline, 20% AI drafting, 50% human rewriting, 10% fact verification. + +When this fits. Brand voice is distinctive (provocative, opinionated, or emotionally specific). The audience would notice generic drafts. Time budget allows substantive rewrites. + +--- + +## Pattern 3: AI-as-research-assistant, human-writes + +The shape. AI condenses sources into research briefs. Human writes the entire piece from the brief in their own voice. + +Best for. Highest-trust editorial: thought leadership, contributed expert pieces, journalism, regulated content. Pieces where the byline is doing trust work and any AI involvement in drafting would compromise the byline's value. + +Risks. Slowest pattern. AI's role is small enough that the team may question whether AI is helping at all; the answer is usually yes (research time savings are real) but the gain is in time-to-research, not time-to-publish. + +Time profile. 40% human reading and outlining, 60% human writing, 10% fact verification (with AI sometimes assisting in flagging fact-check candidates). + +When this fits. The byline is named and trusted (a CEO, an expert, a journalist). The publication's positioning depends on human craft. Disclosure norms in the audience expect human authorship. + +--- + +## Pattern 4: Human-writes, AI-as-editor + +The shape. Human drafts the piece. AI suggests copy edits, alternative phrasings, structural improvements. Human accepts or rejects each suggestion. + +Best for. Senior writers whose voice is established and whose drafts are mostly clean. The AI's role is the second-pair-of-eyes that catches what fatigue or close reading missed. + +Risks. AI suggestions can pull voice toward AI defaults if the writer accepts too many. The discipline is rejecting the suggestions that would homogenize voice even when they read as "cleaner." + +Time profile. 80% human writing, 15% AI suggestion review, 5% fact verification. + +When this fits. The writer is experienced, the brand voice is well-developed, the piece is high-stakes. Pattern is over-kill for routine editorial; right-sized for thought leadership and named-byline pieces. + +--- + +## Pattern 5: AI-generates-at-scale, human-samples + +The shape. For programmatic SEO. AI generates thousands of pages from structured data and templates. Human samples 50 to 200 pages per cycle with editorial-qa sampling discipline. Failures above the 5% threshold halt new generation until template or data fixes ship. + +Best for. Programmatic SEO programs (per `programmatic-seo`). Volume scales the AI does not penalize the program because the underlying data is real and the template is strong; humans sample rather than fully review. + +Risks. Without sampling discipline, the program produces slop at scale. Without threshold gating, slop compounds invisibly until algorithm updates expose it. Pattern requires the editorial-qa scaling pattern to work; without QA scaling, the pattern is just AI-content-factory thinking with extra steps. + +Time profile. 5% template and data setup (one-time, deep), 0.5% per-page generation (mostly automated), 10% sampling QA (per cycle), 5% threshold response. + +When this fits. Data depth is real, query intent is queryable, QC headcount is budgeted. All five criteria from `programmatic-seo`'s when-pseo-works-decision must be met. + +--- + +## Selection criteria + +How to pick the pattern. + +Voice sensitivity. Distinctive voice → Pattern 2, 3, or 4. Generic-tolerant voice → Pattern 1 or 5. + +Volume. Single-piece-at-a-time editorial → Pattern 2, 3, or 4. High-volume editorial → Pattern 1. Programmatic scale → Pattern 5. + +Trust requirement. Named-byline trust work → Pattern 3 or 4. Standard branded content → Pattern 1, 2, or 5. + +Time budget. Tight (hours not days) → Pattern 1. Generous (days available) → Pattern 2, 3, or 4. One-time-deep then automated → Pattern 5. + +Team skill. Junior writers → Pattern 1 or 2 (more AI scaffolding). Senior writers → Pattern 3 or 4 (less AI, more craft). + +--- + +## Combining patterns within one program + +Most content programs run multiple patterns simultaneously. Common combinations. + +- Editorial pillar + cluster: Pattern 3 (AI as research assistant) for the pillar piece; Pattern 1 (AI-first draft, human-edit-heavy) for the cluster pieces. The pillar carries the trust; the cluster scales. +- Editorial + programmatic: Pattern 2 or 4 for editorial; Pattern 5 for programmatic. Same brand, different production model per content type. +- Marketing copy + thought leadership: Pattern 1 for marketing; Pattern 3 for thought leadership. Different trust requirements; different patterns. + +The discipline. Document which pattern the team uses for which content type. Without explicit documentation, the patterns drift; one writer uses Pattern 1 on a piece that should have been Pattern 3, and the trust value of the byline is compromised. + +--- + +## Anti-pattern: pattern drift mid-piece + +Sometimes a piece starts in Pattern 4 (human-writes, AI-as-editor) and drifts into Pattern 1 (AI-first, human-edits) when the writer falls behind on deadline. The piece publishes with AI default voice in sections the writer was supposed to draft. + +The fix. Recognize the drift as a process failure, not a writing failure. The writer was over-committed; the fix is workload management, not blame. Future pieces of this type either get more time (preserving Pattern 4) or get reassigned to Pattern 1 with the editing intensity that Pattern 1 requires. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns, the tradeoffs per pattern, the selection criteria framework, the multi-pattern combinations within a program, the pattern-drift anti-pattern. + +## Implementation choices that stay internal + +The specific AI tools used in each pattern (drafting model, editing model, research model). The specific prompts each pattern uses for the AI handoff. The specific time-tracking that captures pattern adherence per piece. The specific deadline-management workflow that prevents pattern drift mid-piece. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md b/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md new file mode 100644 index 0000000..e16cab8 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md @@ -0,0 +1,143 @@ +# Quality calibration with AI in the loop + +How editorial standards shift when AI is in the workflow. Same standards apply; the failure modes shift. + +The editorial standards from `editorial-qa` apply identically to AI-assisted work: brief adherence, voice consistency, fact accuracy, structure and clarity, AEO/SEO compliance, internal linking and schema validation. What shifts is the failure-mode profile. Programs that ship AI-assisted content with the same QA discipline as human-written content but without recognizing the new failure modes produce slop while believing they are calibrated. + +This reference connects the QA discipline to the AI workflow discipline. It surfaces the shifts. + +--- + +## Same standards, different failure modes + +For each editorial standard, the failure mode that dominates in AI-assisted production differs from the failure mode that dominated in human-only production. + +### Brief adherence + +Human-only failure. Writer skips a brief field because they think they know better, or misreads the brief. + +AI-assisted failure. AI ignores brief fields that were not in the prompt context. The brief is in one document; the AI prompt is in another. Brief fields that did not get pasted into the prompt do not get executed. + +The fix. Prompt templates that explicitly include all 12 brief fields. Brief-adherence QA gate runs against the brief, not against the prompt. + +### Voice consistency + +Human-only failure. Writer fatigue causes voice drift in section 4 of long pieces. Editorial style drift over months as writers absorb each other's tics. + +AI-assisted failure. AI default voice reasserts mid-piece. Long AI generations regress toward generic by section 4 reliably. The drift is faster than human drift and more consistent across pieces. + +The fix. Mid-piece voice sampling per `voice-ownership-preservation.md`. Voice anchor text in every prompt. Final pass in human voice on every long piece. + +### Fact accuracy + +Human-only failure. Lazy fact-checking. The writer "remembers reading" something but does not verify. Citations to publications without specific dates or page references. + +AI-assisted failure. AI hallucinations. Plausible-but-fake statistics with named sources that do not exist. Quotes attributed to real people who did not say them. Citations to URLs that 404. + +The fix. Fact-accuracy as halt-condition gate per `editorial-qa`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +### Structure and clarity + +Human-only failure. Buried lede, vague opening, history dump in section 1. Mismatched section lengths. + +AI-assisted failure. Generic opening that could open any article on the topic. Repetitive paragraph structure (every paragraph 2 to 3 sentences). Bullet-list overuse where prose would serve. Forced bilateral framing throughout. Wrap-up filler endings. + +The fix. AI-content audit per `editorial-qa/references/ai-content-audit-patterns.md`. Read-aloud audit catches what line-review misses. + +### AEO and SEO compliance + +Human-only failure. Writer forgets to include the target keyword in title and headings. Schema markup absent or invalid. + +AI-assisted failure. AI over-optimizes the surface (keyword in every heading, schema markup over-claimed) but under-optimizes the substance (the answer paragraph is generic, the entity coverage is thin, the POV is absent). + +The fix. AEO/SEO checks that go beyond surface compliance into substance: is the top-200-word answer self-contained, is the entity coverage what the brief specified, is the POV distinctive. + +### Internal linking and schema validation + +Human-only failure. Writer skips internal-link discipline because it feels mechanical. Anchor text uses "click here" or generic phrases. + +AI-assisted failure. AI-generated links to URLs that do not exist (hallucinated link targets). Anchor text repeats the same exact-match keyword across multiple links because the AI defaults to that pattern. + +The fix. Link-target liveness check on every published piece. Anchor text variation as a explicit QA item. + +--- + +## The "QA standards must be tighter" claim is wrong + +A common misreading. Teams shipping AI-assisted work decide their QA needs to be tighter, more checks, more thresholds. The misreading produces checkbox theater. + +The accurate reading. QA needs to be calibrated to the new failure modes, not tightened indiscriminately. The standards stay the same; the patterns to look for shift. + +The discipline. When a team starts AI-assisted production, the QA process gets reviewed against the new failure-mode profile. Some checks become more important (fact accuracy, voice consistency, AI-content audit). Some checks become less important (the writer's preferred typo patterns, since the AI does not have the same typo patterns). The QA shape adjusts. + +--- + +## Calibration sessions specific to AI-assisted work + +The calibration session methodology from `team-training-and-calibration.md` adapts for AI-assisted work specifically. + +The AI-specific calibration session. + +1. Three editors independently review the same 3 to 5 AI-assisted pieces. +2. Each editor's assessment includes the AI-content audit dimensions: AI tells, hallucination patterns, voice drift, slop signals. +3. The team reads all assessments together. +4. Differences in interpretation surface; reconcile. +5. Output: addendum to the AI policy doc capturing the calibration consensus on AI-specific QA dimensions. + +The cadence. Quarterly minimum. More frequent during program build or after AI tool changes that affect output behavior. + +--- + +## When the team is calibrated but the output still feels off + +Symptoms. + +- QA gates pass, individual pieces look fine, the program's overall feel is generic +- Readers complain about AI-flavored content despite QA passing +- Audience growth flat despite shipped quality being technically high + +Diagnosis. The QA discipline catches per-piece failures. It does not catch program-level patterns: every piece passing voice review individually but the cumulative output reading as homogenized. + +The fix. Add a program-level review to the calibration cadence. Read 10 published pieces in sequence. Do they sound like one publication with a distinctive voice, or do they sound like 10 separate AI-assisted pieces from different generic publications? The latter signals voice has been preserved at the per-piece level but lost at the program level. + +The intervention. Tighter voice library, more aggressive reject-the-bland discipline, possibly a return to a heavier human-writes pattern for trust-anchor pieces (pillars, thought leadership, named-author content) while keeping AI-assisted patterns for cluster work. + +--- + +## The "ship vs hold" calibration + +In AI-assisted production, the ship-vs-hold decision shifts. More pieces marginally pass QA; the question becomes whether marginal-pass pieces should ship. + +Human-only mode. Marginal pieces usually have specific fixes. The editor flags them; the writer fixes them; the piece ships. + +AI-assisted mode. Marginal pieces often have systemic AI-tells throughout that fixing one-by-one will not address. The editor's choice is between substantial rewrite (back to Pattern 2 or 3) or kill. + +The discipline. Some AI-assisted pieces are kill candidates, not revise candidates. The team should have explicit kill criteria: pieces that fail AI-content audit on 4+ dimensions, pieces where voice was lost beyond paragraph-level recovery, pieces where the underlying brief was thin enough that the AI draft has nothing to anchor to. + +Killing pieces is part of the discipline. Programs that publish 100% of what they draft are not exercising editorial judgment. + +--- + +## The calibration-with-AI checklist + +For each AI-assisted piece, beyond the standard QA gates. + +1. AI-content audit run per `editorial-qa/references/ai-content-audit-patterns.md`? +2. Voice anchor text was used in the prompt? +3. Mid-piece voice sample taken on long pieces? +4. Final pass in human voice for the closing? +5. Fact-accuracy gate ran with AI-hallucination patterns specifically in mind? +6. Disclosure decision made per the disclosure tier framework? +7. The piece passes the "could a competitor have shipped this with the same tools" test? + +If 2+ items fail, the piece is at slop risk. Halt and revise. + +--- + +## Methodology-level choices that stay in the public skill + +The same-standards-different-failure-modes mapping, the "QA standards must be tighter" misreading correction, the AI-specific calibration session adaptation, the program-level review pattern, the kill-criteria discipline, the calibration-with-AI checklist. + +## Implementation choices that stay internal + +The specific QA tooling that surfaces AI-specific failure patterns. The specific automation that flags potential AI tells before manual review. The specific calibration session cadence and team composition. The specific kill-criteria thresholds the team has settled on. These vary by team scale and content sensitivity. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md b/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md new file mode 100644 index 0000000..da21f15 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/team-training-and-calibration.md @@ -0,0 +1,149 @@ +# Team training and calibration + +Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. + +Inconsistent AI usage across a team produces inconsistent output. The discipline below makes AI usage explicit, calibrated, and documented at the team level so the program ships consistent work regardless of which writer is assigned which piece. + +--- + +## Documented AI policy + +The starting point. Every team running AI-assisted content has a policy document, even if currently informal. + +What the policy specifies. + +- Approved uses. AI in research synthesis, AI in copy edit suggestions, AI in transcription, AI in alternative phrasings. The team uses these without per-piece approval. +- Conditional uses. AI in first-draft generation, AI in outline generation, AI in long-form drafting. Approved per content type (e.g., approved for cluster pieces, requires editor approval for pillar pieces). +- Prohibited uses. AI as the sole author of bylined expert content, AI for fact verification (the AI is what gets fact-checked, not what does fact-checking), AI for ethical decisions, AI for final approval. +- Tool standards. Either "the team uses [specific tool] for [specific task]" or "the team selects from this list of tools per task type." Documented either way. +- Disclosure requirements. By content type, per the disclosure framework. +- Voice library reference. Where the team's voice anchor texts and prompt templates live. + +The discipline. The policy is a document, not an oral tradition. Writers, editors, and contributors know where to find it; it is referenced in onboarding; it is updated quarterly. + +--- + +## Calibration sessions + +The discipline. Quarterly editor sessions where editors review the same AI-assisted pieces and surface differences in their judgment. + +Session structure. + +1. Three editors independently review the same 3 to 5 recently-published pieces. +2. Each editor writes a one-paragraph assessment per piece: voice, brief adherence, AI tells, fact accuracy, overall quality. +3. The team reads all assessments together. +4. Differences in interpretation surface; the team reconciles to a shared standard. +5. The session output is an addendum to the policy doc capturing the calibration consensus. + +Why this matters. Without calibration, individual editors apply individual taste. Some editors flag AI-tells aggressively; others ship the same piece without flagging. The inconsistency confuses writers and produces drift in published quality. + +Cadence. Quarterly minimum. More frequent during onboarding waves or after policy updates. + +--- + +## Voice library + +The team's collection of canonical brand-voice samples used as anchor text in AI prompts. + +What goes in the library. + +- 2 to 3 paragraphs of canonical brand voice per content type (blog, whitepaper, help doc, marketing copy, thought leadership) +- 2 to 3 paragraphs per writer voice (where the brand has multiple distinct contributor voices) +- 5 to 10 examples of AI-generated content that the team rewrote successfully (showing the before-and-after as a calibration aid) +- The vocabulary list: preferred terms, forbidden terms, term-specific usage rules + +Update cadence. Monthly during program build; quarterly once stable. + +Why this matters. The voice library is the operational expression of brand voice. Without a library, every AI prompt reinvents the voice context; the team produces inconsistent output. With a library, the prompt is templated and the voice context stays consistent. + +--- + +## Quality benchmarks + +The team's documented examples of "AI-assisted but on-voice" pieces. + +What the benchmarks show. + +- 5 to 10 published pieces where AI assistance was substantial but the output reads as on-voice +- For each benchmark: the pattern used (which workflow pattern), the editing intensity, the time profile, the quality outcome +- The benchmarks are calibration aids: writers and editors look at them when calibrating their own AI-assisted work + +Why this matters. "On-voice AI-assisted content" is an abstraction. Concrete examples make it tangible. New writers calibrate to the benchmarks; experienced writers reference them when their work feels off. + +Anti-pattern. Benchmarks that are aspirational rather than achieved. The benchmark library should be real published work, not "what we wish we shipped." Aspirational benchmarks set unrealistic expectations. + +--- + +## Tool standardization vs intentional pluralism + +Two valid models for AI tool selection at the team level. + +### Standardization + +The team uses one tool consistently for each task type. Drafting on tool A, editing on tool B, transcription on tool C. New writers learn the standard tools; the prompt templates and voice library are tool-specific. + +When this fits. Smaller teams. Predictable content types. Time-budget for tool learning is limited. Consistency matters more than per-task optimization. + +### Intentional pluralism + +The team documents which tools fit which tasks; writers select per-task. Tool A for tasks of type X, tool B for tasks of type Y, contributors choose between them as appropriate. + +When this fits. Larger teams. Diverse content types. Writers have time to learn multiple tools. Per-task optimization matters more than absolute consistency. + +The discipline either way. The choice is documented; tool selection is not arbitrary or per-writer. + +--- + +## Forbidden patterns list + +The patterns the team explicitly does not use AI for, even when AI could technically do them. + +Common forbidden patterns. + +- AI fabricating quotes (always; this is fabrication) +- AI generating content that names specific real people (consent and verification issues) +- AI as the sole author of bylined opinion (ethics) +- AI for content involving regulated topics where the team lacks AI-policy guidance (medical advice, legal advice, financial advice) +- AI for content the team would be ashamed to publish under their byline (slop test) + +Why this matters. The forbidden list is shorter than the approved list but more important. The forbidden list is what keeps the program out of ethics violations and trust failures. + +--- + +## Onboarding + +New writers learn the AI policy and calibration in their first 2 weeks. + +Onboarding components. + +- Policy read. The new writer reads the AI policy doc. +- Voice library walkthrough. The new writer reviews the voice samples and prompt templates. +- Calibration session participation. The new writer participates in the next calibration session as observer. +- Shadow assignment. The new writer's first piece is reviewed jointly with an experienced editor; the editor narrates the calibration in real-time. +- Quality benchmark walkthrough. The new writer reviews the quality benchmarks and identifies what makes each "on-voice." + +Why this matters. New writers without onboarding develop their own AI patterns. The program drifts as new writers join. Onboarding makes the team's discipline transferable. + +--- + +## When team calibration breaks + +Symptoms. + +- Different writers produce wildly different AI-assisted output (calibration overdue) +- Editors disagree on whether a piece is "AI-flavored" (calibration session needed) +- The AI policy doc is 6 months stale and references tools the team no longer uses (policy update overdue) +- New writers are using AI in ways that experienced writers do not (onboarding gap) +- Voice library has not been updated since the program launched (library refresh overdue) + +The fix. Quarterly calibration sessions, quarterly policy review, quarterly voice library updates, structured onboarding for every new writer. The cadences are calendar-anchored; skipping them is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +The documented-policy structure, the calibration session methodology, the voice library practice, the quality-benchmark library, the standardization-vs-pluralism choice, the forbidden-patterns discipline, the onboarding components, the calibration-breakdown signals. + +## Implementation choices that stay internal + +The specific format of the policy doc (Notion page, Markdown file, internal wiki). The specific tooling that hosts the voice library (database, Notion, Git repo of sample text). The specific calibration session cadence and team composition. The specific onboarding tracking system. The specific tool selections the team has standardized on. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md b/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md new file mode 100644 index 0000000..cbeb488 --- /dev/null +++ b/dist/pi/.agents/skills/ai-content-collaboration/references/voice-ownership-preservation.md @@ -0,0 +1,133 @@ +# Voice ownership preservation + +Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. + +Voice is the dominant casualty of careless AI workflows. The patterns below are what programs do to keep voice through AI-assisted production. Programs that skip these patterns produce content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +--- + +## Voice guidelines as prompt input + +The principle. Every AI generation includes the brand voice guidelines as part of the prompt context. Without explicit voice context, AI defaults to a generic register that flattens distinctive brands into industry-standard prose. + +What goes into the prompt. + +- Voice attributes (3 to 5 attributes; e.g., "direct, confident, slightly skeptical") +- Sentence rhythm preference (short and punchy, measured and layered, conversational with asides) +- Stance pattern (opinionated, diplomatic, coach-style, peer-style) +- Register (formal, casual, register that matches the surface) +- Vocabulary preferences (preferred terms, forbidden terms list) +- Anti-patterns (specific phrases or structures to avoid) + +The discipline. The voice guidelines are an input to every AI run, not a one-time setup. Teams that paste the voice guidelines into a saved prompt template ensure consistency; teams that re-type them per session produce drift. + +Why this works. Generic AI defaults are stronger than the AI's training-era voice memory. Without active voice prompting, the AI regresses to the most common patterns in its training data, which are the most common patterns in published content, which are by definition not distinctive. + +--- + +## Sample text as voice anchor + +The principle. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. + +What to use as anchor. + +- The brand's strongest published piece in the relevant register +- A canonical opening from the brand's editorial doc +- A published piece from a writer whose voice the brand wants to maintain consistency with + +The discipline. Anchor text is updated as the brand voice evolves. Stale anchors produce stale-feeling content; the program treats anchors as living documents. + +Why this works. Description prompts ("write in a direct, skeptical voice") are abstract. AI mimics them generically. Sample text is concrete; AI mimics specific patterns: word choices, sentence shapes, transitional phrases, opening patterns. The mimicry is not perfect but it is closer to the brand voice than the abstract description. + +The combination. The strongest voice prompt combines voice guidelines (description) with sample text (concrete examples). Either alone produces drift; together they hold the line. + +--- + +## Mid-draft voice check + +The principle. Long pieces drift. At the halfway mark of a 3,000-word piece, AI generations regress toward generic. The check catches the drift before publish. + +The check. + +1. Sample paragraphs from the start (first 300 words), middle (1,200 to 1,800 words), and end (last 300 words). +2. Compare each sample to the brand voice doc. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. Send back for revision. + +Detection patterns. + +- Vocabulary regresses (words from the do-not-use list reappear; brand-specific terms drop out) +- Sentence rhythm uniforms (every paragraph 2 to 3 sentences, similar lengths) +- Stance softens (specific positions become "there are good arguments on all sides") +- Register drifts toward "professional neutral" regardless of the surface's intended register + +Cross-reference. This check is also covered in `editorial-qa/references/voice-consistency-patterns.md`. The two skills are aligned; the QA gate enforces what this skill prescribes. + +--- + +## Final pass in human voice + +The principle. The human edits the closing sections in their own voice. The closing is where the piece's emotional register often lands; AI defaults there reduce the piece to flat informational tone. + +Why the closing matters. + +- The reader's last impression +- The conversion or memory moment for the piece +- The signature moment where the brand voice is most recognizable + +The discipline. Even in Pattern 1 (AI-first draft, human-edit-heavy), the closing 100 to 300 words should be substantially or fully human-written. The opening can be AI-drafted with heavy editing; the closing benefits from being composed in the writer's own register. + +Anti-pattern. AI-drafted closing paragraphs that announce the piece is ending ("In summary," "By following these steps," "Now you have a comprehensive understanding"). These are AI tells; the human pass should replace them with specific endings: a question, an action, an observation, a direct call to action with concrete language. + +--- + +## Reject the bland + +The principle. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The audit. Read the piece. For each sentence, ask: is this distinctively from this brand, or could it have come from any competitor? The interchangeable sentences are the bland ones. + +The fix. + +- Replace abstractions with specifics. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research, do the research; if not, cut the claim. +- Replace hedges with stances. "It depends on your situation" becomes "for teams under 50 employees, [specific recommendation]; for teams over 200, [different specific recommendation]." +- Replace generic openings with brand-specific openings. Throat-clearing intros become specific entry-points tied to the piece's argument. + +The discipline. Bland sentences are not just "less interesting" sentences; they are voice-killers. A piece with 20% bland sentences reads as 80% diluted; the brand voice is present but watered down past distinction. + +--- + +## The voice library + +A program-level practice. The team maintains a library of canonical brand-voice samples that get used as anchor text in AI prompts. The library evolves as the brand voice evolves. + +Library structure. + +- Voice samples by register (formal whitepaper, casual blog post, conversational email, professional help doc) +- Voice samples by content type (pillar editorial, cluster piece, thought leadership, listicle) +- Voice samples by writer (where the brand has multiple distinct contributor voices) + +Update cadence. Quarterly. As new pieces ship that exemplify the voice, they go into the library. As old pieces feel stale, they come out. + +Why this matters. Teams without a voice library re-paste the same 3 paragraphs as anchor text for years. The voice ages; the AI mimicry ages with it; the content starts feeling dated. Library updates keep the anchor fresh. + +--- + +## When voice cannot be preserved + +Sometimes the voice is genuinely incompatible with AI assistance at the volume the program requires. Signals. + +- Brand voice is so distinctive that AI drafts always need 80% rewriting (Pattern 2 might fit; if even Pattern 2 fails, Pattern 3 or 4 are the only options) +- Audience is so trust-sensitive that any AI involvement compromises the byline (Pattern 3 only) +- Volume target requires AI involvement that voice cannot tolerate + +The honest answer in these cases. Reduce volume to match what voice tolerates, or accept voice trade-off as a strategic choice. The trade-off must be deliberate; "we did not realize voice was suffering" is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +Voice guidelines as prompt input, sample text as voice anchor, the mid-draft sampling discipline, the final-pass-in-human-voice discipline, the reject-the-bland audit, the voice library practice, the "when voice cannot be preserved" honest framing. + +## Implementation choices that stay internal + +The specific format of the brand voice doc (Notion page, Markdown file, internal wiki). The specific AI tool prompt templates that include voice guidelines and sample text. The specific voice library storage and access pattern. The specific calibration session cadence and team composition. These vary by brand and team. diff --git a/dist/pi/.agents/skills/analytics-strategy/SKILL.md b/dist/pi/.agents/skills/analytics-strategy/SKILL.md new file mode 100644 index 0000000..c67502c --- /dev/null +++ b/dist/pi/.agents/skills/analytics-strategy/SKILL.md @@ -0,0 +1,230 @@ +--- +name: analytics-strategy +description: "Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track." +category: growth +catalog_summary: "Measurement frameworks, dashboard design, event taxonomy" +display_order: 1 +--- + +# Analytics Strategy + +Design measurement frameworks that produce decisions, not just dashboards. Stack-agnostic. Tool-agnostic. + +This skill is for measurement planning. For conversion optimization, use `cro-optimization`. For SEO measurement specifically, use `seo-onpage` and adjacent SEO skills. + +--- + +## When to use + +- Setting up analytics on a new product or site +- Auditing existing analytics setup +- Designing dashboards for a team or business +- Defining KPIs and a north star metric +- Building event taxonomies for product analytics +- Designing attribution models for marketing +- Translating business questions into measurement plans + +## When NOT to use + +- Conversion testing or optimization (use `cro-optimization`) +- SEO performance measurement (use SEO skills) +- Pure data infrastructure decisions (different domain) + +--- + +## Required inputs + +- The business or product context (what does success look like) +- The audience for the analytics (who needs to make what decisions) +- The current measurement state (existing tools, tracking, gaps) +- The questions the team needs to answer + +--- + +## The framework: 4 layers + +A complete measurement strategy covers all four. Each layer feeds the next. + +### 1. North star and KPI hierarchy + +The single metric that captures the most important outcome, plus the supporting metrics. + +North star metric: + +- One metric. Singular. +- Captures customer-perceived value. +- Leads to revenue, but isn't revenue itself (revenue is too far downstream). +- Examples: weekly active users, completed jobs, revenue-generating sessions, hours of value delivered. + +Underneath the north star, the KPI hierarchy: + +``` +North star metric +├── Acquisition KPI (how new users enter) +├── Activation KPI (when new users get value) +├── Engagement KPI (how often users return) +├── Retention KPI (how many stick over time) +└── Monetization KPI (how value translates to revenue) +``` + +This is the "AARRR" or "pirate metrics" framework. It works because it covers the full lifecycle. + +### 2. Event taxonomy + +The vocabulary the product uses to describe what users do. + +Event design principles: + +- Verb + noun. `signed_up`, `created_project`, `completed_checkout`. Past tense, snake_case. +- One event per discrete action. Not "interacted_with_modal" - too vague. Specifically `opened_modal_X`, `closed_modal_X`, `confirmed_in_modal_X`. +- Properties capture context. Each event has properties (key-value pairs) for context. `signed_up` has properties like `signup_method`, `referrer`, `plan`. +- Standardize property names. `user_id` everywhere, not `userId` here and `id` there. +- Document everything. A tracking plan that lives nowhere is a tracking plan no one follows. + +Event coverage: + +- All key user actions tracked +- All conversion points tracked +- All errors tracked +- All page views tracked (with consistent properties) +- All button clicks that matter (not all button clicks - that's noise) + +Anti-patterns: + +- 500+ events with no documentation +- Inconsistent naming (`buttonClicked`, `Button Clicked`, `clicked_button`) +- Property keys that vary across events +- Events fired client-side that should be server-side (and vice versa) +- PII in event properties (privacy issue and tooling issue) + +### 3. Dashboards and reports + +The interface between data and decisions. + +Dashboard design principles: + +- One audience per dashboard. Executive dashboard != product team dashboard. Different metrics, different cadence. +- One question per chart. A chart should answer one question, not three. +- Annotations matter. Note launches, experiments, holidays, outages. A spike means nothing without context. +- Context comparisons. "10,000 signups this month" - compared to what? Last month, last year, target? +- Lead with the action. What does this dashboard help someone decide? + +Common dashboard types: + +\| Dashboard \| Audience \| Metrics \| Cadence \| +\|---\|---\|---\|---\| +\| Executive \| Leadership \| North star, top 3 KPIs, big-picture trends \| Weekly review \| +\| Product \| Product team \| Funnel metrics, feature adoption, retention \| Daily / weekly \| +\| Marketing \| Marketing team \| Acquisition by channel, CAC, attribution \| Daily / weekly \| +\| Operations \| Ops / on-call \| Performance, errors, capacity \| Real-time \| +\| Custom (per team) \| Specific team \| Their specific KPIs \| Their cadence \| + +### 4. Attribution and segmentation + +How to connect cause and effect. + +Attribution models: + +- First-touch. Credit the first interaction. Useful for awareness understanding. +- Last-touch. Credit the final interaction before conversion. Default in many tools, often misleading. +- Linear. Spread credit equally across touches. Avoids over-crediting any single channel. +- Time-decay. Recent touches get more credit. Reasonable middle ground. +- Position-based. First and last get more credit, middle touches less. +- Data-driven (algorithmic). Tools like Google Analytics 4 use ML. Black box but increasingly the default. + +For most businesses: pick one primary attribution model, use multiple secondary models for validation. + +Segmentation principles: + +- Segment by what causes different behavior, not by what's easy to track +- Useful segments: source/channel, plan tier, geography, device, cohort (signup date) +- Less useful: demographic guesses without behavioral validation + +--- + +## The tracking plan document + +Output of the analytics strategy. A living document. + +Structure: + +1. Goals and KPIs. Business objectives, north star, KPI hierarchy. +2. Event catalog. Every event, with properties, when fired, why tracked. +3. User properties. Persistent attributes (plan, signup_date, role). +4. Page taxonomy. Page categories, page properties. +5. Naming conventions. Snake_case, verb_noun, etc. +6. Implementation notes. Client-side vs server-side, SDK details, sampling. +7. Privacy and compliance. PII rules, consent handling, data retention. +8. Governance. Who can add events, review process, change log. + +--- + +## Workflow + +1. Define the questions. What does the team need to answer? Working backward from questions to metrics works better than starting from metrics. +2. Define the north star. One metric. Tested against the criteria above. +3. Build the KPI hierarchy. Acquisition, activation, engagement, retention, monetization. +4. Audit existing tracking. What's there? What's broken? What's missing? +5. Design the event taxonomy. Cover the user journey. Document everything. +6. Implement with care. Test each event. Verify properties. Catch issues in staging. +7. Build dashboards. One per audience. Lead with action. +8. Establish review cadence. Weekly business review, monthly KPI review, quarterly strategy review. +9. Govern. Who adds events, who reviews, how changes propagate. + +--- + +## Failure patterns + +- Tracking everything. Noise overwhelms signal. +- Tracking nothing strategic. Page views and that's it. Cannot answer real questions. +- No documentation. Tracking plan lives in someone's head. +- Inconsistent naming. Same concept, three names. Reports become detective work. +- Events fired but never reviewed. Tracking debt accumulates. +- Dashboards no one looks at. Built for vanity, not decisions. +- Single attribution model treated as truth. All models lie. Some lie usefully. +- PII in events. Compliance and tooling problems. +- Client-side only. Critical business events should be server-side too. Ad blockers, network issues, edge cases lose client-side events. +- No connection to business outcomes. Metrics exist in a silo, never connected to revenue, retention, or strategic decisions. + +--- + +## Output format + +Default output: a markdown tracking plan at `analytics-tracking-plan.md` plus a dashboard inventory. + +Tracking plan structure: + +```markdown +# Tracking Plan + +## North star metric +[Definition, calculation, target] + +## KPI hierarchy +[Each KPI with definition, calculation, owner] + +## Event catalog +\| Event \| When fired \| Properties \| Owner \| Status \| +\|---\|---\|---\|---\|---\| +\| user_signed_up \| After successful signup form submit \| source, plan, referrer \| Marketing \| Live \| +\| project_created \| When user clicks Create Project \| project_type, template_used \| Product \| Live \| +\| ... \| \| \| \| \| + +## User properties +[List with definitions] + +## Naming conventions +[Rules] + +## Privacy and compliance +[Rules] + +## Governance +[Process] +``` + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Starter event catalog with patterns for common product types. diff --git a/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md b/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md new file mode 100644 index 0000000..69e22bb --- /dev/null +++ b/dist/pi/.agents/skills/analytics-strategy/references/event-taxonomy-template.md @@ -0,0 +1,407 @@ +# Event Taxonomy Template + +Starter event catalogs for common product types. Adapt to specific products. The patterns generalize. + +--- + +## Universal events (most products need these) + +### Lifecycle events + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `user_signed_up` \| New account created \| signup_method, source, referrer, plan \| +\| `user_logged_in` \| Successful login \| login_method \| +\| `user_logged_out` \| Session ended \| session_duration \| +\| `user_deleted_account` \| Account deletion \| reason (if collected) \| + +### Product/feature engagement + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `feature_used` \| Specific feature interaction \| feature_name, feature_version \| +\| `setting_changed` \| User changes a setting \| setting_name, old_value, new_value \| +\| `notification_clicked` \| User clicks a notification \| notification_type, notification_id \| + +### Errors + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `error_occurred` \| Anywhere an error is shown to user \| error_type, error_message, page, action_attempted \| +\| `form_validation_failed` \| Form submit blocked by validation \| form_name, fields_with_errors \| + +### Communication + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `email_received` \| Email delivered (server-side, via ESP webhook) \| email_type, campaign_id \| +\| `email_opened` \| Email opened (via tracking pixel) \| email_type, campaign_id \| +\| `email_clicked` \| Link in email clicked \| email_type, campaign_id, link_text \| +\| `email_unsubscribed` \| User unsubscribes \| email_type \| + +--- + +## SaaS / B2B product events + +``` +Acquisition +├── user_signed_up +├── trial_started +└── trial_extended + +Activation (the "aha" moment) +├── workspace_created +├── teammate_invited +├── first_project_created +├── first_integration_connected +└── first_value_action (product-specific - the moment user gets value) + +Engagement +├── session_started +├── project_opened +├── workflow_completed +└── feature_X_used (one per key feature) + +Conversion +├── plan_upgraded +├── seats_added +├── invoice_paid +└── annual_plan_purchased + +Retention +├── returned_after_inactivity +├── reactivated_from_email +└── usage_milestone_hit (e.g., crossed 100 actions) + +Risk signals +├── support_ticket_opened +├── billing_failure_occurred +├── trial_expiring_soon (calculated, server-side) +└── churn_risk_threshold_hit (calculated) +``` + +### Properties to capture across all events + +``` +user_id Persistent across sessions +session_id New per session +account_id For multi-user accounts +plan Current plan tier +days_since_signup +device_type +browser +os +geo_country +geo_region +referrer +utm_source / utm_medium / utm_campaign / utm_term / utm_content +``` + +--- + +## Ecommerce events + +``` +Discovery +├── page_viewed +├── search_performed +├── search_results_viewed +├── filter_applied +└── product_listing_viewed + +Consideration +├── product_viewed +├── product_image_zoomed +├── size_selected +├── color_selected +├── reviews_read +└── product_shared + +Cart +├── product_added_to_cart +├── product_removed_from_cart +├── cart_viewed +├── cart_quantity_changed +└── cart_abandoned (calculated, server-side) + +Checkout +├── checkout_started +├── shipping_info_entered +├── billing_info_entered +├── promo_code_applied +├── promo_code_failed +├── checkout_step_viewed (with step_name) +└── purchase_completed + +Post-purchase +├── order_shipped +├── order_delivered +├── product_returned +├── review_submitted +└── reorder_initiated +``` + +### Ecommerce-specific properties + +``` +For purchase_completed: + order_id + total_value + currency + shipping_method + payment_method + discount_applied + items: [ + { product_id, product_name, category, brand, variant, quantity, unit_price } + ] + +For product_viewed: + product_id + product_name + category + brand + price + in_stock + position (when viewed in a list) +``` + +--- + +## Content site / publisher events + +``` +Reading +├── page_viewed +├── article_started (when article body enters viewport) +├── article_25_percent_scrolled +├── article_50_percent_scrolled +├── article_75_percent_scrolled +├── article_100_percent_scrolled (read to end) +└── article_time_spent (calculated on page exit) + +Engagement +├── newsletter_signup_shown +├── newsletter_signup_completed +├── comment_posted +├── article_shared +├── article_bookmarked +└── related_article_clicked + +Subscription (if metered/paywalled) +├── paywall_hit +├── paywall_dismissed +├── subscribe_started +├── subscribe_completed +├── article_unlocked (free, registered, paid) +``` + +### Content-specific properties + +``` +For article events: + article_id + article_title + category + author + published_date + word_count + paywall_status (free, registered_only, paid_only) + is_premium +``` + +--- + +## Marketplace events + +Marketplaces have two-sided tracking: buyers and sellers/providers. + +``` +Buyer side +├── search_performed +├── listing_viewed +├── inquiry_sent +├── booking_started +├── booking_completed +├── review_left +└── repeat_booking_made + +Seller/provider side +├── listing_created +├── listing_published +├── listing_edited +├── inquiry_received +├── inquiry_responded +├── booking_received +├── booking_completed +├── payout_received +└── review_received +``` + +### Marketplace-specific properties + +``` +For listing_viewed: + listing_id + category + price + location + seller_id + position_in_search + +For booking_completed: + booking_id + listing_id + seller_id + buyer_id + total_value + fee_amount +``` + +--- + +## Mobile app events + +``` +App lifecycle +├── app_installed (server-side or attribution platform) +├── app_first_opened +├── app_opened (every launch) +├── app_backgrounded +├── app_foregrounded +└── app_uninstalled (often inferred, hard to track directly) + +Engagement +├── push_notification_received +├── push_notification_opened +├── deep_link_opened +└── share_extension_used + +Permissions +├── permission_requested (push, location, camera, etc.) +├── permission_granted +└── permission_denied +``` + +### Mobile-specific properties + +``` +app_version +app_build +device_model +os_version +network_type (wifi, cellular) +push_token +notification_permission_status +``` + +--- + +## Forms and surveys + +``` +Form lifecycle +├── form_viewed +├── form_started (first field interaction) +├── form_field_focused +├── form_field_completed +├── form_field_validation_failed +├── form_submitted +└── form_abandoned (left page without submit) +``` + +### Properties + +``` +form_name +form_id +fields_total +fields_completed +fields_with_errors +time_spent_seconds +``` + +--- + +## Naming convention rules + +### Verb_noun, past tense, snake_case + +✓ `user_signed_up` +✓ `product_added_to_cart` +✓ `article_50_percent_scrolled` +✗ `signupCompleted` +✗ `addProduct` +✗ `Article 50% Scrolled` + +### Properties: camelCase or snake_case (pick one and stay) + +snake_case is more common in SQL contexts (data warehouses). +camelCase is more common in JavaScript/TypeScript contexts. +The choice matters less than consistency. + +✓ `user_id`, `signup_method`, `email_type` (consistent snake_case) +✓ `userId`, `signupMethod`, `emailType` (consistent camelCase) +✗ `userId`, `signup_method`, `EmailType` (mixed) + +### Property values: standardize where possible + +Don't allow free-text where an enum should exist. + +✓ `signup_method: "email" \| "google" \| "github" \| "sso"` +✗ `signup_method: "email", "Email", "EMAIL", "via email", "with email address"` + +### Reserved properties + +Most analytics tools have built-in properties. Don't override them. + +Common reserved names: +- `id`, `userId` (or system equivalent) +- `event`, `event_name` +- `timestamp`, `time` +- `session_id` +- `anonymous_id` +- `properties`, `traits` + +--- + +## What NOT to track + +- PII in event properties. Email, phone, full name, address. Privacy issue and tooling issue. +- Every click. Track meaningful clicks. Hover events. Mouse movements. Generic interactions are noise. +- Server-side state churn. Background jobs, cron runs, internal events. These belong in monitoring, not product analytics. +- Anything you cannot define in one sentence. If you can't describe what the event represents, you won't be able to use it. + +--- + +## Privacy and consent + +Common compliance patterns: + +- Consent before tracking. Cookie banner, opt-in flow. +- Honor Do Not Track. Browsers signal preferences. +- Right to deletion. User can request all their data deleted (GDPR, CCPA). +- Right to export. User can request their data in machine-readable format. +- No cross-site tracking without consent. Some jurisdictions require explicit opt-in. +- Data residency. EU user data may need to stay in EU. + +Standard compliance approaches: + +- Server-side tagging when available (more reliable, more controllable) +- Consent management platform (CMP) for cookie consent +- Clear privacy policy that lists what you collect +- A pseudonymous user ID separate from PII + +Compliance specifics vary by jurisdiction. Consult counsel for high-stakes decisions. + +--- + +## Governance and review + +Patterns that work: + +- New events require an RFC or short proposal +- Event catalog reviewed quarterly +- Deprecated events flagged and removed after a grace period +- Tracking plan version-controlled (in Git) +- Implementation tested in staging before production +- Monitoring on event volume (sudden drops = tracking break) diff --git a/dist/pi/.agents/skills/art-direction/SKILL.md b/dist/pi/.agents/skills/art-direction/SKILL.md new file mode 100644 index 0000000..65e9452 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/SKILL.md @@ -0,0 +1,198 @@ +--- +name: art-direction +description: "Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables." +category: design +catalog_summary: "Photography, illustration, and visual direction for campaigns" +display_order: 3 +--- + +# Art Direction + +Direct creative work that extends the brand into specific deliverables. Photography, illustration, video, motion, campaigns, environmental design. + +This skill assumes brand identity is approved (`brand-identity` complete). Art direction is about applying and extending it, not defining it. + +--- + +## When to use + +- Briefing photographers, illustrators, videographers +- Developing campaign creative concepts +- Directing in-house creative teams +- Writing creative direction documents for vendors +- Evaluating creative deliverables for brand fit +- Adapting brand visual identity to a new format or context + +## When NOT to use + +- Setting project-wide aesthetic direction across multiple downstream skills (use `creative-direction` instead). This skill briefs specific creative deliverables; `creative-direction` produces the structured aesthetic brief that this skill consumes. +- Defining brand visual identity from scratch (use `brand-identity`) +- Day-to-day component design (use `design-standards`) +- Writing copy for creative work (use `content-and-copy` or `landing-page-copy`) +- Building a design system (use `design-system`) + +--- + +## Required inputs + +- The deliverable (photo shoot, illustration set, video, campaign) +- The brand identity (visual system, voice, imagery direction) +- The audience for this specific work +- The goal (brand awareness, conversion, education, emotional connection) +- Budget and timeline +- Distribution context (where it will be seen) + +--- + +## The framework: 5 layers + +A creative brief covers five layers. Each must be clear before the brief leaves your hands. + +### 1. The story + +What this creative work is fundamentally about. + +- The premise. The core idea in one sentence. +- The emotional through-line. What the audience feels. +- The role of the brand. How the brand shows up in the story. +- The takeaway. What the audience walks away with. + +A weak premise produces work that's pretty but says nothing. Spend time here. + +### 2. The look + +The visual treatment. + +For photography: +- Subject and composition (close-up, environmental, candid, posed) +- Lighting (natural, studio, dramatic, soft) +- Color palette (true color, treated, monochrome) +- Locations (specific or general direction) +- Wardrobe and props +- Mood references (3 to 5 reference images) + +For illustration: +- Style (flat, dimensional, hand-drawn, geometric, abstract) +- Color use (full palette, restricted, brand-only) +- Line treatment +- Composition style +- Detail level +- Reference artists or works (with explicit "we want like X but NOT like Y") + +For video / motion: +- Pacing (slow, medium, fast cuts) +- Camera movement (static, handheld, sweeping) +- Color grading +- Transitions and effects +- Audio direction (music, voiceover, ambient) +- Reference work (3 to 5 examples) + +### 3. The execution + +Production-level direction. + +Specifications: +- Deliverable formats and sizes (web hero, social square, print full-page) +- Required shots or frames +- Optional shots if budget allows +- Wardrobe and prop list (for live action) +- Color and asset specs (RGB, CMYK, hex codes for matching) + +Constraints: +- Things to avoid (specific cliches, forbidden treatments, regulatory) +- Brand-system requirements (logo placement, color use, type rules) + +### 4. The variants + +How this creative scales across distribution. + +Most creative needs to live in multiple places. Plan the variants up front. + +Common variant set for a campaign: +- Hero web image (16:9 or wider) +- Mobile web hero (4:5 or 1:1) +- Social square (1:1) +- Social vertical (9:16) +- Email banner (3:1 typical) +- Display ad sizes (300x250, 728x90, etc.) +- Print sizes if applicable + +For each variant, note: how the composition adapts, what gets cropped or repositioned, what assets are required. + +### 5. The standards + +The quality bar. + +Technical: +- Resolution and format requirements +- Color profile +- File naming conventions +- Delivery format (raw + edited, layered files, exported variants) + +Creative: +- What "approved" looks like (specific examples of acceptable work) +- What "not approved" looks like (specific examples to avoid) +- Number of revision rounds budgeted + +--- + +## Workflow + +### For briefing external creative + +1. Confirm the inputs. Brand identity locked. Audience and goal clear. Budget and timeline known. +2. Develop the concept. Premise, emotional through-line, takeaway. +3. Build the look. Mood references. Specific direction on style elements. +4. Write the spec. Production-level direction. Variants. Constraints. +5. Brief the vendor. In writing. Walk through it live. Allow questions. +6. Review milestones. Treatment review, halfway review, final review. Don't skip the early reviews; corrections compound. +7. Approve and document. What was produced, what's licensed for what use. + +### For directing in-house creative + +1. Same brief, lighter format. In-house direction can be more iterative. Still document the brief. +2. Co-create. In-house teams know the brand. Use their judgment. Don't over-direct. +3. Establish review rhythm. Daily check-ins for fast work, weekly for longer projects. + +### For evaluating existing creative + +1. Score against the brief. Did the work hit the brief? Where did it deviate? +2. Score against the brand. Does this look like the brand? Could this be confused with a competitor? +3. Score against the goal. Will this drive the intended outcome? +4. Identify fixes. What can be improved? What's a deal-breaker vs. acceptable? + +--- + +## Failure patterns + +- "Modern, clean, minimal" briefs. Means nothing. Force specificity. Use specific reference brands, named artists, or visual examples. +- No "what to avoid" direction. Vendors interpret broadly. Tell them what's out of bounds explicitly. +- Reference imagery that's actually competitor work. You'll get something that looks like the competitor. Never use direct competitors as references. +- Skipping early reviews. Every revision late in the process is 5x more expensive than catching issues at treatment stage. +- Too many cooks. 6 stakeholders all giving creative feedback produces incoherent work. Concentrate creative authority. +- Ignoring distribution. Creative that doesn't work in the actual contexts where it will live is failed creative. +- No variant planning. Discovering at delivery that you need a square crop and the photographer composed for 16:9 only. +- Approving creative that's "fine." Fine is the enemy of distinctive. If it doesn't move you, it won't move the audience. + +--- + +## Output format + +Default output is a creative brief at `creative-brief-[project].md`. + +Structure: +1. The story (premise, through-line, role of brand, takeaway) +2. The look (visual treatment with references) +3. The execution (specs, variants, constraints) +4. The standards (quality bar, examples of acceptable and unacceptable) +5. The logistics (timeline, milestones, budget, deliverables) + +Plus a separate moodboard or visual reference doc with images. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Generic art direction brief template covering any production type (photo, illustration, video, animation, mixed). +- [`references/photo-shoot-brief.md`](references/photo-shoot-brief.md) - Detailed brief template for photography commissions. +- [`references/illustration-brief.md`](references/illustration-brief.md) - Brief template for illustration commissions. diff --git a/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md b/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md new file mode 100644 index 0000000..feb2406 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/creative-brief-template.md @@ -0,0 +1,249 @@ +# Art Direction Brief Template + +A fillable brief for art direction projects. Fill every section before production begins. A short brief beats a generic brief; a generic brief produces generic work. + +--- + +## Project: [Name] + +Project type: [Photography / Illustration / Video / Animation / Mixed] +Channel(s): [Where this will live] +Date briefed: [YYYY-MM-DD] +Production date: [YYYY-MM-DD] +Director: [Name] +Producer: [Name] +Budget: [Range] + +--- + +## 1. Project context + +Why this project exists: +[1 to 2 paragraphs. The business reason this work needs to be made.] + +What it must accomplish: +[The specific outcome. Awareness, conversion, brand association, internal use, etc.] + +How it will be measured: +[Concrete success indicator. Engagement, completion rate, brand lift, internal feedback.] + +--- + +## 2. Concept + +The big idea (one sentence): +[The angle, insight, or opinion the creative work expresses.] + +Why this concept now: +[2 to 3 sentences. Why this idea fits the moment, the brand, and the audience.] + +What this concept rejects: +[The opposite or adjacent ideas this concept is not.] + +--- + +## 3. Audience + +Primary audience: +[Specific persona. "Mid-career operator at a B2B SaaS company evaluating tools for their team," not "B2B buyers."] + +What they currently feel about the category: +[1 to 2 sentences.] + +What we want them to feel after seeing this: +[1 to 2 sentences.] + +--- + +## 4. Subjects + +People: +- Cast: [Demographics, archetypes, specific casting direction] +- Wardrobe: [Direction] +- Expression: [What we want them showing] +- Diversity: [Explicit casting expectations] + +Products: +- What appears: [List] +- Staging: [How they're shown] +- Hierarchy: [Hero product vs supporting] + +Settings: +- Locations: [Specific or category] +- Environment: [Indoor/outdoor, real/built, public/private] +- Time of day: [If relevant] + +Objects/props: +- Required: [Specific items] +- Forbidden: [Things never to include] + +--- + +## 5. Composition + +Formats and channels: +\| Channel \| Aspect ratio \| Resolution \| Specific requirements \| +\|---\|---\|---\|---\| +\| [e.g., Instagram feed] \| 1:1 \| [px] \| [Crop-safe area for text overlay] \| +\| [e.g., Instagram stories] \| 9:16 \| [px] \| [Top/bottom safe areas] \| +\| [e.g., Web hero] \| 16:9 \| [px] \| [Subject must allow text overlay on left] \| +\| [e.g., Print] \| [Specific] \| [DPI] \| \| + +Shot list: +[Specific shots required. Include reference frame for each.] + +1. [Shot description]: [Reference image] +2. [Shot description]: [Reference image] +3. [Shot description]: [Reference image] + +Framing direction: +- Crop tendency: [Tight / medium / wide] +- Subject placement: [Centered / off-center / dynamic] +- Eye line: [To camera / away / unspecified] +- Depth: [Foreground emphasis / background environment / flat] +- Negative space: [Generous / minimal / variable] + +--- + +## 6. Lighting + +Direction: +[2 to 4 sentences describing the lighting approach.] + +Specific qualities: +- Source: [Natural / available / controlled] +- Direction: [Front / side / back / overhead] +- Quality: [Hard / soft] +- Color temperature: [Warm / neutral / cool] +- Time of day if natural: [Specific] + +Lighting references: +[3 to 5 reference images with annotations.] + +--- + +## 7. Color and treatment + +Color palette: +[Brand palette + any campaign-specific extensions] + +Treatment direction: +- Saturation: [True / muted / desaturated / heightened] +- Contrast: [Low / balanced / high] +- Color grade: [Specific look or signature] +- Film references: [Specific films, photographers, or art if relevant] + +Treatment references: +[3 to 5 reference images with annotations.] + +--- + +## 8. Tone + +Adjectives (3 to 5): +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] + +Pacing (moving image): +[If applicable: brisk / deliberate / breathless / languid] + +Sound direction (moving image): +[If applicable: score, sound design, voice, silence] + +--- + +## 9. Reference moodboard + +[Link to moodboard with 10 to 15 curated images.] + +Each reference labeled with what we are taking from it (composition, lighting, treatment, casting, etc.). Avoid using a single reference for everything; pull specific elements from different sources. + +--- + +## 10. What to avoid + +Visual cliches in our category to reject: +- [Specific cliche with example] +- [Specific cliche with example] +- [Specific cliche with example] + +Treatments not aligned with our direction: +- [Specific treatment] +- [Specific treatment] + +Casting we will not use: +- [Specific casting type and why] + +--- + +## 11. Deliverables + +Final deliverables required: + +\| Asset \| Format \| Count \| Specifications \| +\|---\|---\|---\|---\| +\| [e.g., Hero image] \| JPG, PNG \| 5 \| 16:9, 4K \| +\| [e.g., Story crops] \| MP4 \| 10 \| 9:16, 1080p, 15s max \| +\| [e.g., Behind-the-scenes] \| MP4 \| 1 \| 16:9, 60s \| + +Editing/retouching specifications: +[Color grading approach, retouching rules, watermarking, captions] + +File naming convention: +[`project-asset-version-channel.format`] + +Delivery method: +[How files arrive. Drive, DAM, direct upload.] + +--- + +## 12. Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Pre-production complete \| \| \| +\| Production day(s) \| \| \| +\| Selects review \| \| \| +\| Edit v1 / first cut \| \| \| +\| Final delivery \| \| \| + +--- + +## 13. Approvals + +Approval path: +1. [Person / role] - [What they approve] +2. [Person / role] - [What they approve] +3. [Final approver] + +Maximum review rounds: [Typically 2 to 3] +Hard stop: [Date after which changes are out of scope] + +--- + +## 14. Talent + +Photographer / Illustrator / Director: [Name and rate] +Why we picked them: [1 to 2 sentences linking their portfolio to this brief] +Crew: [Producer, stylist, lighting, etc.] +Talent (on-camera): [Casting decisions] + +--- + +## 15. Open questions + +[Anything unresolved at brief-writing time. Resolve before production day.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: +- [Name] [Date] +- [Name] [Date] + +Production day(s) confirmed: [Date] diff --git a/dist/pi/.agents/skills/art-direction/references/illustration-brief.md b/dist/pi/.agents/skills/art-direction/references/illustration-brief.md new file mode 100644 index 0000000..46bba36 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/illustration-brief.md @@ -0,0 +1,238 @@ +# Illustration Brief + +A complete brief for commissioning illustration work. Use as a starting template, fill out fully before sending to the illustrator. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a redo (and most illustrators charge for redos). + +--- + +## Project overview + +Project name: [Working title] +Date of brief: [YYYY-MM-DD] +Delivery deadline: [Final files due] +Illustrator / studio: [If selected] +Producer / point of contact: [Name and contact] +Budget: [Total or per-illustration rate] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is each illustration fundamentally about?] + +### Audience +[Who will see these illustrations. Their context, their state of mind.] + +### Goal +[What do these illustrations accomplish? Editorial illustration, brand storytelling, product visualization, instruction, decoration?] + +### Brand role +[How does the brand show up? Subtle (illustrations stand on their own), prominent (brand mark visible in scene), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Playful," "considered," "warm," "sharp," "optimistic."] + +--- + +## The look + +### Style references + +[5 to 10 reference illustrations. Source: illustrator portfolios (Behance, It's Nice That, Cargo), editorial illustration archives, ad campaigns. AVOID: direct competitor imagery, AI-generated images, copyrighted character work used out of context.] + +For each reference, note WHAT to take from it: +- "From this illustration: the loose hand-drawn line quality" +- "From this illustration: the limited color palette" +- "From this illustration: the flat geometric construction" + +NOT just dumping references with no commentary. The illustrator needs to know which qualities matter. + +### What to AVOID + +- [Specific style cliche to avoid, e.g., "Corporate Memphis / Alegria figures"] +- [Specific style cliche to avoid, e.g., "isometric tech-startup spot illustrations"] +- [Visual treatment that's been overused in the category] + +### Style and technique + +- Medium: [Vector / raster / mixed / hand-drawn scanned / 3D] +- Line quality: [Geometric and clean / loose and gestural / no line / variable] +- Fill style: [Flat / textured / gradients / cross-hatching / watercolor] +- Detail level: [Highly detailed / minimal / mid] +- Perspective: [Flat / isometric / one-point / loose / mixed] +- Figure style (if illustrating people): [Realistic / stylized / abstract / no figures] + +### Color + +- [Specific palette with hex codes if matching brand] +- [Number of colors: limited (2-3), moderate (4-6), full] +- [Treatment: brand-matched / shifted / monochrome / sepia / saturated / muted] + +### Composition + +- [Single subject focus / scene with multiple elements / pattern / decorative] +- [Negative space treatment] +- [Orientation defaults: square, landscape, portrait, mixed] + +--- + +## Illustration list + +A specific list of illustrations needed. Each entry is a deliverable. + +### Required illustrations (must-have) + +1. [Illustration name] + - Subject: [What's depicted] + - Concept: [What it should communicate or evoke] + - Use case: [Where it will appear, e.g., "blog post hero, 1200x675"] + - Variants: [Aspect ratios or color modes needed] + +2. [Illustration name] + - Subject: + - Concept: + - Use case: + - Variants: + +[Continue for all required illustrations] + +### Optional illustrations (if time and budget allow) + +1. [Illustration name] +2. [Illustration name] + +### Variants per illustration + +Most illustrations need to work in multiple contexts: + +- Light mode and dark mode: does the illustration need a dark-background variant? +- Aspect ratios: which crops are needed (16:9, 1:1, 9:16, banner)? +- Resolution variants: retina vs standard, social vs hero +- Cropped vs full: is a cropped detail of the same illustration also needed? +- Animation: is a static illustration plus a looping animated version needed? + +When briefing, note which variants each illustration must support. + +--- + +## Technical specs + +### Source files + +- Format: [AI / SVG / PSD / PNG layered / Procreate / Figma] +- Layered structure required: [Yes - so the brand can adjust colors, swap elements, or animate later. No - flat delivery only.] +- Editability: [Editable text and shapes preferred / OK to outline] + +### Export formats + +- Web: [SVG for vector, WebP / PNG for raster] +- Print: [If applicable: CMYK, 300 DPI, with bleed] +- Resolution: [Specific minimums per use case] +- Color profile: [sRGB for web, CMYK for print] + +### Delivery + +- Format: [Cloud delivery, file sharing, hard drive] +- Naming convention: [e.g., "ProjectName_IllustrationN_VariantX.svg"] +- Asset management: [Where the files live after delivery] + +### Licensing + +- Usage: [Where the illustrations can be used; web, print, paid media, all media, in perpetuity] +- Term: [Duration of license; usually 1 year, 2 years, or perpetual] +- Geography: [Worldwide, US-only, etc.] +- Exclusivity: [Exclusive to brand, or illustrator can include in portfolio? Most illustrators want portfolio rights even on exclusive work.] +- Modification rights: [Can the brand modify the illustration in-house, or does any change require returning to the illustrator?] +- NFT / generative AI training: [Explicitly state whether the illustrator can use the work to train AI, and whether the brand can.] + +--- + +## Process and milestones + +### Stages and approvals + +A typical illustration commission moves through these stages. Define what each milestone delivers and who approves. + +\| Stage \| What is delivered \| Who approves \| +\|---\|---\|---\| +\| Brief approved \| This document, signed \| Brand lead \| +\| Sketches / thumbnails \| 2-3 rough directions per illustration \| Brand lead + creative director \| +\| Refined sketch \| Single chosen direction, more detail \| Brand lead + creative director \| +\| Color and style test \| One illustration finalized as reference \| Brand lead + creative director \| +\| Final illustrations \| All deliverables, in all variants \| Brand lead \| +\| Files handed over \| Source + exports, organized \| Brand lead \| + +### Revision rounds + +- Sketch round 1: [What is in scope. Typically composition and concept. Major changes are easier here.] +- Sketch round 2: [Refinement only. Style and composition are locked.] +- Final art rounds: [Typically 1 round of small adjustments. Beyond this, usually billed separately.] +- Beyond included rounds: [Cost or process for additional rounds.] + +### Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Brief approved \| \| \| +\| Sketches delivered \| \| \| +\| Sketch sign-off \| \| \| +\| First finished illustration \| \| \| +\| Style sign-off \| \| \| +\| Remaining illustrations delivered \| \| \| +\| Final files handed over \| \| \| + +--- + +## Budget breakdown + +\| Item \| Cost \| Notes \| +\|---\|---\|---\| +\| Illustrator fee (base) \| \| \| +\| Per-illustration rate \| \| \| +\| Style test / first finish \| \| \| +\| Revisions beyond included rounds \| \| \| +\| Rush fees (if applicable) \| \| \| +\| License fees (if separate from base) \| \| \| +\| Source file delivery (if separate) \| \| \| +\| Total \| \| \| + +--- + +## Approval process + +### Who approves at each stage + +- Brief: [Name] +- Sketches: [Names] +- Style test: [Names] +- Final illustrations: [Name] +- Final delivery: [Name] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Illustrator credit: [Required / optional / no credit. Typical: credit required where editorial use, optional where commercial.] +- Promotion: [Illustrator can / cannot promote on their own portfolio. Typical: yes after the work is publicly launched.] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md b/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md new file mode 100644 index 0000000..c3efba1 --- /dev/null +++ b/dist/pi/.agents/skills/art-direction/references/photo-shoot-brief.md @@ -0,0 +1,255 @@ +# Photo Shoot Brief + +A complete brief for commissioning a photo shoot. Use as a starting template, fill out fully before sending to the photographer. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a reshoot. + +--- + +## Project overview + +Project name: [Working title] +Date of brief: [YYYY-MM-DD] +Shoot date(s): [Target dates] +Location(s): [Specific or "TBD - photographer recommends"] +Photographer / studio: [If selected] +Producer / point of contact: [Name and contact] +Budget: [Total or range] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is this shoot fundamentally about?] + +### Audience +[Who will see these images. Be specific. Their context, their state of mind.] + +### Goal +[What do these images accomplish? Brand awareness? Conversion? Emotional connection? Editorial illustration?] + +### Brand role +[How does the brand show up? Subtle (it's about the people), prominent (the product is the hero), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Confident," "intimate," "celebratory," "considered," "energetic."] + +--- + +## The look + +### Visual references + +[5 to 10 reference images. Source: photographers' portfolios, ad campaigns, editorial work. AVOID: direct competitor imagery.] + +For each reference, note WHAT to take from it: +- "From this image: the soft natural light" +- "From this image: the close composition on hands" +- "From this image: the muted color palette" + +NOT just dumping references with no commentary. + +### What to AVOID + +- [Specific visual cliche to avoid, e.g., "Stock-photo-style smiling at camera"] +- [Specific visual cliche to avoid] +- [Visual treatment that's been overused in the category] + +### Lighting + +- [Natural / studio / mixed] +- [Soft and diffused / dramatic and directional / high-contrast / low-contrast] +- [Time of day if natural] + +### Color + +- [True color / treated / monochrome / desaturated] +- [Specific color palette or mood, with hex codes if matching brand] + +### Composition + +- [Tight crops vs. wide environments] +- [Symmetrical vs. asymmetrical] +- [Subject placement preferences] +- [Portrait vs. landscape orientation defaults] + +### Wardrobe and styling + +- [Casual / formal / specific style direction] +- [Color preferences for wardrobe] +- [Things to avoid (logos other than ours, distracting patterns, etc.)] + +### Subjects / talent + +- [Demographics and casting direction] +- [Specific talent if cast, or open call criteria] +- [Diversity considerations] +- [Number of subjects per shot] + +### Props and set + +- [Required props] +- [Set direction (clean, lived-in, organized, chaotic, etc.)] +- [Branded elements (yes / no / minimal)] + +--- + +## Shot list + +A specific list of shots needed. Each entry is a shot the photographer must deliver. + +### Required shots (must-have) + +1. [Shot name] + - Description: [What's in the frame] + - Composition: [Tight, wide, environmental] + - Use case: [Where this image will be used, e.g., "homepage hero, 16:9"] + - Quantity: [How many variations] + +2. [Shot name] + - Description: + - Composition: + - Use case: + - Quantity: + +[Continue for all required shots] + +### Optional shots (if time and budget allow) + +1. [Shot name] +2. [Shot name] + +### Variants per shot + +Most shots need to work in multiple aspect ratios. Specify: + +- 16:9 (wide): for web hero, video thumbnails +- 4:5 (vertical): for social, mobile hero +- 1:1 (square): for Instagram, app icons, avatars +- 9:16 (vertical extreme): for Stories, vertical video + +When briefing, note which aspect ratios each shot must support. Photographer composes accordingly (loose enough to crop multiple ways, OR shoots specifically for each crop). + +--- + +## Technical specs + +### Resolution and format + +- Minimum resolution: [e.g., 6000x4000] +- File format: [RAW + edited high-res JPG / TIFF] +- Color profile: [sRGB / Adobe RGB] +- Color space: [Web vs. print] + +### Editing + +- Editing scope: [Color correction only / full retouch / specific retouch needs] +- Editing reference: [Examples of approved final-look] + +### Delivery + +- Format: [Cloud delivery, file sharing, hard drive] +- Naming convention: [e.g., "ProjectName_ShotN_VariantX.jpg"] +- Asset management: [Where the files live after delivery] + +### Licensing + +- Usage: [Where the images can be used; web, print, paid media, all media, in perpetuity] +- Term: [Duration of license; usually 1 year, 2 years, or perpetual] +- Geography: [Worldwide, US-only, etc.] +- Exclusivity: [Exclusive to brand, or photographer can include in portfolio?] + +--- + +## Logistics + +### Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Brief approved \| \| \| +\| Treatment / mood board sign-off \| \| \| +\| Casting / location finalized \| \| \| +\| Shoot day(s) \| \| \| +\| Selects delivered \| \| \| +\| Final edits delivered \| \| \| + +### Budget breakdown + +\| Item \| Cost \| Notes \| +\|---\|---\|---\| +\| Photographer fee \| \| \| +\| Talent \| \| \| +\| Wardrobe / styling \| \| \| +\| Hair / makeup \| \| \| +\| Location fee \| \| \| +\| Set / props \| \| \| +\| Equipment \| \| \| +\| Editing / retouching \| \| \| +\| Production / coordination \| \| \| +\| Contingency (10%) \| \| \| +\| Total \| \| \| + +### Crew + +- Photographer: [Name] +- Photo assistant: [Name] +- Producer: [Name] +- Stylist: [Name] +- Hair / makeup: [Name] +- Talent: [Names] +- Brand reps on set: [Names] + +### Logistics day-of + +- Call time: [Time] +- Wrap time (target): [Time] +- Catering / craft services: [Plan] +- Wet weather plan: [If outdoor] +- Day-of contact list: [Names and numbers] + +--- + +## Approval process + +### Who approves at each stage + +- Brief: [Name] +- Treatment / mood board: [Names] +- Day-of selects: [Names on set or remote review] +- Edited final selects: [Name] +- Final delivery: [Name] + +### Revision rounds + +- Edits round 1: [What's in scope] +- Edits round 2: [What's in scope] +- Beyond round 2: [Cost or process for additional rounds] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Photographer credit: [Required / optional / no credit] +- Promotion: [Photographer can / cannot promote on their own portfolio] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md b/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md new file mode 100644 index 0000000..3a5c787 --- /dev/null +++ b/dist/pi/.agents/skills/backup-and-disaster-recovery/SKILL.md @@ -0,0 +1,268 @@ +--- +name: backup-and-disaster-recovery +description: "Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability." +category: operations +catalog_summary: "RPO/RTO targets, backup strategy, restoration drills" +display_order: 6 +--- + +# Backup and Disaster Recovery + +Plan for the worst case: the database is gone, the host is down for a week, the deploy was poisoned, ransomware encrypted everything. The skill is in advance preparation, not reaction. + +--- + +## When to use + +- Setting up backups for a new system +- Reviewing and validating backup architecture +- Defining RPO (recovery point objective) and RTO (recovery time objective) +- Running a disaster recovery drill +- Diagnosing gaps after an incident +- Planning for ransomware, data corruption, or insider threats +- Migrating to a new platform (DR planning belongs in the migration plan) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Routine deploy rollbacks (use `launch-runbook`) +- Code or content versioning (covered by Git, CMS revision history) +- Routine database snapshots (use this skill to set them up; routine review goes in monitoring) + +--- + +## Required inputs + +- The systems in scope (databases, file storage, code, configs, secrets) +- The hosting platforms and providers +- Existing backup tooling and what it covers +- Tolerance for data loss (in time) +- Tolerance for downtime (in time) +- Compliance requirements (some regulations mandate specific backup standards) + +--- + +## The framework: 4 questions + +Every disaster recovery plan answers four questions explicitly. + +### Question 1: What needs to be recoverable? + +List every system that holds state. Categorize by criticality. + +Tier 1: must recover. Without it, the business stops. (Customer database, transaction log, primary content store.) + +Tier 2: should recover. Loss is painful but not fatal. (Analytics, logs, secondary services.) + +Tier 3: nice to recover. Easy to rebuild. (Caches, derived data, temporary state.) + +The tier drives RPO, RTO, backup frequency, and storage spend. + +### Question 2: How much data loss is acceptable? (RPO) + +RPO is the maximum age of data that's acceptable to lose, measured in time. + +- RPO = 1 hour: hourly backups or continuous replication needed +- RPO = 1 day: daily backups acceptable +- RPO = 1 week: weekly backups acceptable + +For most production data, RPO of 1 hour or less is the target. For critical financial systems, near-zero RPO (continuous replication). + +For derived or rebuildable data, RPO of 1 day or longer is fine. + +### Question 3: How much downtime is acceptable? (RTO) + +RTO is the maximum time to restore service after a disaster. + +\| RTO target \| Implies \| +\|---\|---\| +\| < 5 minutes \| Hot standby with automatic failover \| +\| < 1 hour \| Warm standby with manual failover or fast restore from recent snapshot \| +\| < 24 hours \| Cold backup with documented restore process \| +\| Days to weeks \| Best-effort, accept extended downtime \| + +RTO drives architecture spend. Aggressive RTOs (< 1 hour) are expensive. Loose RTOs (days) are cheap. + +### Question 4: What's the disaster? + +Plan for specific scenarios. Each has different implications. + +Hardware failure. Disk dies. Standard backups solve this. Most modern hosts handle automatically. + +Provider outage. Region or vendor goes down. Cross-region or cross-provider redundancy needed for low RTO. + +Data corruption. Bad migration, bug, accidental delete. Point-in-time restore needed. The latest backup might be corrupted; you need history. + +Ransomware or compromise. Attacker encrypts or deletes. Backups must be immutable or air-gapped, otherwise the attacker takes them too. + +Account compromise. Attacker has admin credentials, deletes everything. Same defense as ransomware: immutable backups, separate access control. + +Vendor lock-out. Account suspended, billing dispute, vendor disappears. Backups outside the vendor needed. + +Insider threat. Disgruntled employee deletes or exfiltrates. Audit logs, separation of duties, immutable backups. + +A backup strategy that handles only hardware failure isn't a strategy. It's the easiest case. + +--- + +## Workflow + +### Step 1: Inventory state + +Every system that holds state goes on a list: + +\| System \| Data type \| Tier \| Current backup \| Tested? \| +\|---\|---\|---\|---\|---\| + +If you can't list it, you can't protect it. Often the inventory itself reveals gaps (the "we forgot about that database" moment). + +### Step 2: Set RPO and RTO per tier + +For each tier, agree on RPO and RTO. Get sign-off from the people who'd be impacted by a disaster. + +Push back on aspirational targets that aren't backed by infrastructure spend. RTO of 5 minutes for a system without a hot standby is not real. + +### Step 3: Verify or design backup architecture + +For each system, ensure: + +- Frequency matches RPO. +- Retention covers point-in-time recovery (typically 30+ days for production data). +- Storage location is separate from the source. Same disk, same account, same region: not enough. +- Immutability or write-once storage for at least some backup copies. Defends against ransomware. +- Encryption at rest. Standard for compliance. +- Tested restore procedure. Untested backups are not backups. + +The "3-2-1 rule" is a useful starting point: 3 copies of data, 2 different storage types, 1 offsite (or off-account, off-platform). + +### Step 4: Document the restore runbook + +For each system, write the runbook: + +1. How to detect the disaster (cross-reference monitoring) +2. How to decide to restore (decision criteria, who authorizes) +3. The exact restore steps (commands, screenshots, sequence) +4. How to verify the restore worked +5. How to switch traffic back +6. Communication template (status page, customer notice) + +The runbook is for the worst night of someone's career. Write it for tired, panicked you. + +### Step 5: Run a drill + +The first restore should never be during a real disaster. + +Drills can be: + +- Tabletop: walk through the runbook on paper. Useful for finding gaps in the plan. +- Partial: restore to a non-production environment. Verify the data, validate the steps. +- Full: simulate the disaster. Production failover or full restore. Maximum confidence, maximum risk. + +For most teams: quarterly tabletop, annual partial drill, full drill before major launches or after major architecture changes. + +### Step 6: Document drill results + +After each drill, document: +- What was tested +- What worked +- What broke +- What the actual RPO and RTO were (vs. targets) +- Action items + +If the actual RTO was 6 hours when the target was 1 hour, the target is fiction. Either fix the gap or revise the target. + +### Step 7: Schedule the next drill + +Calendar it. Assign an owner. Backups that aren't drilled drift toward useless. + +--- + +## Special topics + +### Database point-in-time recovery + +Many managed databases offer point-in-time recovery (PITR) within a retention window (often 7-35 days). This typically achieves RPO of seconds to minutes. + +For longer retention, schedule periodic exports to immutable storage. + +PITR alone isn't enough. If the database service itself is compromised, PITR is gone too. Always have at least one backup outside the source service. + +### File storage backups + +Object stores (S3, GCS, Azure Blob) usually offer: + +- Versioning (recover overwritten objects) +- Replication (cross-region) +- Object lock or immutability (defense against deletion) + +Set all three for production-critical buckets. Don't rely on the storage provider's default retention. + +### Code and config backups + +Code lives in Git. The Git host (GitHub, GitLab, etc.) is your backup, but a single host is a single point of failure. + +For high-criticality code: +- Mirror to a second host or your own server +- Periodic offline exports + +Configs and secrets need separate handling: +- Infrastructure-as-code: in Git, mirrored +- Runtime configs: backed up alongside the system +- Secrets: in a secret manager with its own backup story + +### Backups of backups + +The backup system itself can fail. Backup metadata, backup credentials, encryption keys: all must be backed up. + +If your backup is encrypted with a key you've lost, the backup is useless. + +### Compliance backups + +Some regulations require specific retention (e.g., 7 years for financial data). Comply with the highest applicable standard. + +Don't conflate compliance retention with operational backup. Compliance often allows much slower restore (just need to be able to produce the data eventually). + +--- + +## Failure patterns + +Untested backups. The single most common failure. Backups appear to work; restore fails. Test. + +Backups in the same account or region as the source. Account compromise or region outage takes both. + +No immutability. Ransomware encrypts the backups too. Use object lock or air-gapped storage. + +RTO and RPO that aren't measured. Target says "1 hour" but no one has verified the actual RTO. Assume the actual is longer than the target until proven otherwise. + +Restore runbook only in someone's head. Person leaves or is unavailable; runbook is gone. Document. + +Backups but no DR plan. "We have backups" isn't a plan. The plan is the runbook plus the architecture plus the drilling. + +Optimism bias. "It won't happen to us." It happens. Plan as if it will. + +Backups too old or too new. Want point-in-time history (in case corruption isn't immediately discovered). Daily snapshots with 30+ day retention. Or continuous replication with separate periodic snapshots for history. + +Skipping drills "because we're busy." Then you'll be busier during the disaster. + +No communication plan. Restoring data is half the job. Telling customers, stakeholders, and internal teams what's happening is the other half. + +--- + +## Output format + +A DR plan document includes: + +- Inventory: every stateful system +- Tiering: criticality per system +- Targets: RPO and RTO per tier +- Architecture: backup tooling, frequency, storage, immutability +- Runbooks: restore procedures per system +- Drill schedule: what gets tested when +- Drill log: results of past drills +- Communication templates: what to say during a real DR event + +--- + +## Reference files + +- [`references/restore-runbook-template.md`](references/restore-runbook-template.md): Fillable template for a restore runbook, covering detection, authorization, steps, verification, and rollback. diff --git a/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md b/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md new file mode 100644 index 0000000..6adf708 --- /dev/null +++ b/dist/pi/.agents/skills/backup-and-disaster-recovery/references/restore-runbook-template.md @@ -0,0 +1,231 @@ +# Restore Runbook Template + +Fill out one of these per system that needs to be restorable. The runbook is read by a tired, panicked person at 3am. Optimize for that reader. + +--- + +## System: [System name] + +Owner team: [Team name] +On-call escalation: [Who, how to reach] +Last drill: [YYYY-MM-DD] +Last verified working: [YYYY-MM-DD] + +--- + +## Tier and targets + +\| \| Target \| Last measured \| +\|---\|---\|---\| +\| Tier \| [1 / 2 / 3] \| \| +\| RPO \| [Time] \| [Time] \| +\| RTO \| [Time] \| [Time] \| + +If the last measured RTO is longer than the target, the target needs revision or the architecture needs investment. + +--- + +## What this system does + +[2-3 sentences describing what the system is and why it matters. The reader may not be familiar with this system in a panic.] + +--- + +## What "lost" looks like + +The triggers for using this runbook: + +- [ ] [Specific symptom, e.g., "Database returns errors on all queries"] +- [ ] [Specific symptom, e.g., "Data has been deleted or appears corrupted"] +- [ ] [Specific symptom, e.g., "Provider region is down per their status page"] +- [ ] [Specific symptom, e.g., "Account access is locked or suspended"] + +If none of these match, this might not be the right runbook. Pause and check `incident-response`. + +--- + +## Decision: should we restore? + +Restoring is destructive. Don't do it without authorization. + +Authorize restoration if: +- [Condition 1] +- [Condition 2] +- [Condition 3] + +Do NOT restore if: +- The system is recoverable through less destructive means (failover, replica promotion, partial fix) +- The data loss is recoverable through other channels (event replay, cache rebuild) +- We're not yet sure of the cause (restoring on top of an unknown cause can make things worse) + +Authorization required from: [Role] +Backup authorization from: [Role] + +Document the authorization in the incident channel before proceeding. + +--- + +## Pre-restore checklist + +- [ ] Authorization received and documented +- [ ] Communication sent: status page updated, internal notice posted +- [ ] Recent backup identified and validated +- [ ] Backup integrity verified (checksum, sample query, etc.) +- [ ] Target environment prepared (downtime accepted, traffic redirected) +- [ ] Rollback plan understood +- [ ] Timer started (track actual RTO) + +--- + +## Restore procedure + +### Step 1: Identify the backup to restore from + +[Specific instructions: which backup system, how to find the right one, how to verify it's the right one.] + +``` +[Example commands] +``` + +### Step 2: Prepare the target + +[Specific instructions: which environment, how to ensure no traffic, how to clear or prepare destination.] + +``` +[Example commands] +``` + +### Step 3: Run the restore + +[Specific instructions: the actual restore command(s), expected duration, what success looks like.] + +``` +[Example commands] +``` + +Expected duration: [Time] + +### Step 4: Verify + +[Specific instructions: how to know the restore worked. Sample queries, row counts, data spot-checks.] + +``` +[Example commands and queries] +``` + +Expected results: [What to look for] + +### Step 5: Re-enable traffic + +[Specific instructions: how to direct traffic back to the restored system.] + +``` +[Example commands] +``` + +### Step 6: Monitor + +For [time period] after the restore: + +- [ ] Watch error rates (link to dashboard) +- [ ] Watch latency (link to dashboard) +- [ ] Spot-check user-visible behavior +- [ ] Confirm no further data anomalies + +--- + +## Rollback + +If the restore makes things worse: + +[Specific instructions for reverting. This is rarely possible for data restores, but for failover-style restores, rollback is just the failover in reverse.] + +--- + +## Post-restore + +### Communication + +- [ ] Status page updated (resolved) +- [ ] Internal notice updated (system restored) +- [ ] Customer comms (if appropriate, who and what) +- [ ] Stakeholder summary + +### Documentation + +- [ ] Actual RTO recorded +- [ ] Actual RPO measured (latest data point preserved vs latest data point lost) +- [ ] Notes on any deviations from the runbook +- [ ] Items to fix in the runbook + +### After-action + +Schedule the after-action report within 5 business days. See `after-action-report` skill for the framework. + +--- + +## Backup details + +### Backup architecture + +\| \| Detail \| +\|---\|---\| +\| Backup tool \| [Tool name] \| +\| Frequency \| [Cadence] \| +\| Retention \| [Period] \| +\| Storage location \| [Where, including account/region] \| +\| Immutable? \| [Yes / No, details] \| +\| Encryption \| [Method, key location] \| + +### How backups are tested + +- [ ] [Test method 1] +- [ ] [Test method 2] +- [ ] [Test method 3] + +Last test: [YYYY-MM-DD] +Test cadence: [How often] + +--- + +## Dependencies + +This system depends on: +- [Dependency 1, what it provides] +- [Dependency 2, what it provides] + +If a dependency is also down, the restore may need to wait or proceed with workarounds. Document the workarounds: + +- [Dependency unavailable scenario 1]: [Workaround] +- [Dependency unavailable scenario 2]: [Workaround] + +--- + +## Drill log + +\| Date \| Type (tabletop / partial / full) \| Outcome \| Issues found \| Fixes \| +\|---\|---\|---\|---\|---\| +\| YYYY-MM-DD \| [Type] \| [Pass / Partial / Fail] \| [Issues] \| [Fixes applied] \| + +--- + +## Maintenance + +This runbook needs review: +- After every restore (real or drill) +- When the system architecture changes +- When backup tooling changes +- At least quarterly + +Last review: [YYYY-MM-DD] by [Name] +Next review: [YYYY-MM-DD] + +--- + +## Common gotchas + +[List of things that have surprised people during past restores or drills. Specific to this system.] + +- [Gotcha 1] +- [Gotcha 2] +- [Gotcha 3] diff --git a/dist/pi/.agents/skills/beta-program-management/SKILL.md b/dist/pi/.agents/skills/beta-program-management/SKILL.md new file mode 100644 index 0000000..30362a4 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/SKILL.md @@ -0,0 +1,312 @@ +--- +name: beta-program-management +description: "Running closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time." +category: product +catalog_summary: "Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops)" +display_order: 13 +--- + +# Beta Program Management + +A senior product leader's playbook for running betas that produce real signal. Closed and open betas, alpha programs, design partner programs, early access. Participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). + +Most betas underperform. Teams ship a beta because they think they should run a beta; participants are recruited loosely or open-flooded; feedback is collected ad-hoc through whatever channels exist; the decision to graduate to GA happens on calendar rather than on signal. The beta produced activity but not learning; the team launches with the same uncertainty they had before the beta. + +This skill is the discipline that turns betas into decision input. Calibrated cohorts who match the post-launch user profile. Structured feedback that captures what the team needs to know. Mid-beta triage that uses what is being learned. Graduation criteria that distinguish "ready" from "we are tired of running the beta." The discipline is not bureaucratic; it is the difference between a beta that informs the GA launch and a beta that produces noise. + +The voice is the senior product leader who has run betas with real signal and watched plenty of betas produce nothing. Concrete, opinionated about what produces signal, willing to call out where beta programs slide into ceremony. + +When to use this skill: planning a beta for an upcoming launch, auditing why prior betas have not produced actionable signal, designing the beta participant experience, or deciding whether a feature is ready to graduate from beta to GA. + +--- + +## What this skill is for + +This skill spans beta program design and execution. The PM and engineering distinction: + +- `feature-flagging` is rollout mechanics; the technical layer for controlling who gets which features. +- `beta-program-management` (this skill) is participant management and feedback discipline; the human layer. +- `feature-launch-playbook` is the full launch (post-GA); this skill is what happens BEFORE GA. +- `experiment-design` is rigorous A/B testing; betas are softer, qualitative-leaning, smaller-N. +- `user-feedback-aggregation` is ongoing feedback streams; beta feedback is bounded to the beta period. +- `discovery-research-synthesis` is one-off discovery research; betas are validation-stage rather than discovery-stage. + +The audience: senior PMs, product directors, engineering leads coordinating with product, customer success and support running beta cohorts, anyone planning a closed or open beta. + +What is not in scope: the broader feature launch (covered by `feature-launch-playbook`); the technical rollout mechanics (covered by `feature-flagging`); the rigorous experimentation methodology (covered by `experiment-design`); the discovery-stage research that informs whether to build the feature in the first place. + +--- + +## Soft-launch vs kitchen-sink vs structured-beta + +The keystone framing. + +Soft-launch. "We will just turn it on for some users." No structured participant selection, no defined feedback collection, no graduation criteria. The beta runs because the team wanted to ship the feature without the full launch ceremony. Output: the feature is in production for some users; the team has no organized way to learn from their experience; signal accumulates through whatever channels happen to surface it; mid-beta course-correction does not happen because there is no structure to surface what should be corrected. + +Kitchen-sink. Everyone gets in. The beta opens to whoever signs up. 5,000 beta users; 50 useful pieces of feedback; 4,950 silent users who provide no signal. Volume drowns signal. The team cannot tell which users matched the target post-launch profile. Feedback channels overflow; useful patterns get lost in noise; mid-beta triage cannot keep up. Output: a sense of "we ran a big beta" without the actionable feedback that smaller calibrated cohorts produce. + +Structured-beta. Calibrated cohort selected by participant criteria. Intentional feedback loops the cohort knows to use. Clear graduation criteria that distinguish "ready for GA" from "tired of the beta." Mid-beta triage that uses what is being learned. Output: the beta produces decision-grade signal; the GA launch ships with confidence; problems that would have surfaced in production get caught and addressed in beta. + +The litmus test. After the beta concludes, ask: what specifically did we learn from this beta that changed the GA launch? If the team can name 3-7 specific lessons, the beta was structured. If the team can only generally say "the beta went well," the beta was soft-launch or kitchen-sink. + +--- + +## Beta type decisions + +Several axes of beta-type choice. The right combination depends on the launch context. + +Closed vs open. + +- Closed: invite-only. Participants are selected by criteria. Cohort is bounded. +- Open: anyone can join. Cohort is self-selecting. +- Closed produces calibrated signal; open produces volume signal that may not match the target user profile. + +Alpha vs beta vs RC. + +- Alpha: very early, internal or trusted-partner only, expectation of bugs. +- Beta: more polished, broader cohort, expectation of feedback rather than crash discovery. +- RC (release candidate): essentially launch-ready, last validation, expectation of production-grade quality. + +Internal vs external. + +- Internal: only employees use the feature. +- External: real customers use the feature. +- Internal betas catch only what employees would experience; external betas catch the full user-context complexity. + +Time-bounded vs open-ended. + +- Time-bounded: 4-week beta, 8-week beta, with a defined end. +- Open-ended: beta runs until the team decides to graduate. +- Time-bounded forces the graduation decision; open-ended risks beta-purgatory. + +The combination decision. A typical structured beta might be closed + beta + external + 6-week time-bounded. A design partner program might be closed + alpha + external + open-ended. An open early access might be open + beta + external + time-bounded. The combination should match the kind of signal the team needs. + +Detail in [`references/beta-type-decisions.md`](references/beta-type-decisions.md). + +--- + +## Participant selection criteria + +The discipline that makes calibrated cohorts possible. + +The criteria that work. + +- Match the post-launch user profile. If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. The beta participant profile should resemble the target GA audience. +- Variety across relevant dimensions. Not all participants identical. If the feature has segment-specific behavior, the cohort spans segments. If usage volume varies, the cohort includes high-volume and low-volume users. +- Feedback willingness. Participants who agree to provide feedback through the structured channels. Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Existing relationship strength. Customers with strong existing relationships are more likely to engage substantively. Customers in churn-risk are less likely to engage; their feedback may also be less representative. + +The criteria that fail. + +- Self-selection only. Open beta sign-ups skew toward enthusiasts and tinkerers; their feedback may not represent the broader target user. +- Highest-paying customers only. Skews toward enterprise patterns that may not generalize; misses smaller-team use cases. +- Internal employees only. Misses the customer-context complexity; signals "we tested" without "real users tested." + +The cohort size question. Calibrated cohorts are usually 20-200 participants for closed external betas. Smaller (5-20) for design partner programs. Larger (200-2,000) for open early access. Beyond 2,000 the program is a soft-launch with beta branding. + +Detail in [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md). + +--- + +## Beta cohort sizing + +How big is enough; when does signal saturate. + +Saturation patterns. + +- Critical feedback (bugs, crashes, broken flows) saturates quickly. 20-30 participants surface most critical issues in the first 2 weeks. +- Behavioral feedback (how users actually use the feature) saturates more slowly. 50-100 participants needed to see usage patterns clearly. +- Edge case feedback saturates slowly. 100+ participants needed; some edge cases never surface in beta. + +Sizing decisions. + +- For betas focused on bug discovery: 20-50 participants for 2-4 weeks. Beyond this, returns diminish. +- For betas focused on behavioral signal: 50-200 participants for 4-8 weeks. +- For betas focused on validating product-market fit assumptions: 100-500 participants over 8-12 weeks. +- For betas focused on at-scale infrastructure validation: 500-2,000 participants over 4-8 weeks. + +The "beta size matches signal need" principle. Cohort size follows from what the team needs to learn. Larger is not always better; calibrated is. + +Detail in [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md). + +--- + +## Onboarding beta participants + +How participants enter the beta and what they know going in. + +The setup. + +- Welcome communication that sets expectations: what the beta is, what feedback is expected, how long it runs, what happens at graduation. +- NDAs where relevant (for unannounced features, design partner programs). +- Feedback channel access: where participants give feedback, what format, what cadence. +- Support escalation path: who participants contact when things break. +- Compensation or incentive disclosure: free access to the feature post-GA, gift cards, swag, named recognition, etc. + +The expectations contract. + +- What the team commits to participants: communication cadence, response to feedback, transparent about graduation criteria. +- What participants commit to the team: feedback through the structured channels, not sharing externally during NDA, willingness to engage in interviews if requested. + +Common onboarding failures. + +- Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. +- No NDA where appropriate. Beta features get screenshotted on social before the team is ready. +- Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. +- No incentive clarity. Participants feel underrecognized; engagement decays. + +Detail in [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md). + +--- + +## Feedback collection patterns + +Structured channels that produce signal rather than noise. + +Channels that work. + +- Structured surveys. 5-15 question surveys at defined points (week 1, week 4, end of beta). Specific questions tied to the team's learning goals. +- Async feedback forms. Participants submit specific feedback through a defined form. Fields prompt for use case, severity, expected vs actual behavior. +- Structured interviews. 30-60 minute interviews with a subset of participants (5-15 per beta). Focused on usage patterns, decision moments, and qualitative depth. +- In-product feedback widgets. Contextualized to the moment. The feedback is timestamped to the user's actual experience. +- Support tickets routed to beta-aware support. Beta participants get faster, more contextualized support; the support interactions surface usage friction. + +Channels that fail. + +- Slack channels for venting. Beta participants vent in real time; signal mixes with noise; nobody synthesizes. +- "Reply to this email with feedback." Returns long unstructured emails; synthesis is hard; useful patterns get lost. +- "Tell us what you think in the survey at the end." End-of-beta surveys catch only what participants remember; in-the-moment friction is forgotten. + +Channel mix discipline. Most structured betas use 3-5 channels. Each channel surfaces different kinds of signal. The team synthesizes across channels. + +Detail in [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md). + +--- + +## Mid-beta triage and iteration + +How the team responds to feedback during the beta. + +The principle. Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. + +The triage cadence. + +- Weekly: review feedback across all channels. Categorize: critical bug, friction issue, feature request, positive signal, edge case. +- Bi-weekly: surface patterns. What recurring feedback are we seeing? What signal is converging? +- As-needed: critical issues get same-day response. Bugs that prevent core flows are not allowed to sit. + +The iteration discipline. + +- Critical bugs fixed during the beta. Beta participants experience the fixes; the post-fix experience informs the GA decision. +- Friction issues prioritized for fixes during the beta where feasible; documented for the GA decision where not. +- Feature requests captured for post-GA roadmap; not added during the beta unless they are graduation-blocking. +- Positive signal validated; surfaces what works, informs marketing copy and onboarding for GA. + +The communication discipline. Participants are kept informed: "We received your feedback on X; we are addressing it in next week's beta update." Silence makes participants feel ignored; over-communication signals overhead. Calibrate. + +Detail in [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md). + +--- + +## Beta-to-GA decision criteria + +Graduation gates that distinguish "ready" from "tired of running the beta." + +The criteria. + +- Critical bugs cleared. No known crashes, data loss, or core-flow failures. +- Friction issues addressed or accepted. Friction the team will not address by GA is documented and accepted as known limitation. +- Behavioral validation. Beta participants are using the feature in the patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). +- Performance under load. The feature performs adequately at the scale GA will produce. (For infrastructure betas, this is the central criterion.) +- Documentation and support readiness. Help docs reflect actual usage; support team is trained on common issues; escalation paths work. +- Positive signal sufficient. Feedback is net-positive enough to launch with confidence. Not all participants delighted, but a substantial majority finding value. + +The "we are tired of running the beta" anti-pattern. Beta has run long enough that the team wants to graduate regardless of signal. The graduation decision happens on calendar rather than on criteria. Resist this; either the criteria are met (graduate) or they are not (extend or reset). + +The "perpetual beta" anti-pattern. Beta runs indefinitely because no firm graduation criteria were set. The team avoids the GA commitment by keeping the feature in beta. Force the graduation decision; if the feature is not ready for GA, identify what would make it ready or reconsider whether to ship at all. + +Detail in [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md). + +--- + +## Beta wind-down and participant communication + +How the beta ends. + +The graduation announcement. Participants are told the feature is graduating. Specific date. What changes for them: continued access (typically yes), pricing changes (often beta participants get free access for some period), feature stability commitments (the GA version is what they will use going forward). + +The transition. + +- For most participants: nothing changes operationally. The feature stays available; the "beta" label drops. +- Pricing transitions communicated explicitly if applicable. +- Beta-only features that did not make GA are flagged. Participants who relied on those features are given alternatives or transition timelines. + +The thank-you. Beta participants invested time providing feedback. Recognition matters: named in changelog (with consent), gift cards or swag, advance access to future betas. The recognition strengthens future-beta recruitment. + +The postmortem. Internal review of what the beta produced. What was learned, what changed in the GA launch, what would be done differently in future betas. This feeds the team's beta program practice. + +Detail in [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-beta-failures.md`](references/common-beta-failures.md). + +- "Our beta produced no signal." Soft-launch pattern; no structured selection or feedback collection. +- "Our beta has 5,000 users and we cannot synthesize feedback." Kitchen-sink; cohort too large for the structured signal the team needs. +- "Our beta participants never gave feedback." Onboarding contract was unclear or feedback channels were friction-laden. +- "We graduated to GA on schedule but launched with critical bugs." Graduation criteria not enforced; calendar-driven graduation. +- "Our beta has been running for 8 months with no graduation." Perpetual beta; no firm graduation criteria; graduation decision avoided. +- "Beta participants vented on Twitter before the launch." NDA missing or unclear; trust violation early erodes participant willingness. +- "The beta surfaced patterns we did not act on." Mid-beta triage missing; feedback collected but not used during the beta. +- "The GA launch surprised us." Beta was not actually validating the GA experience; cohort or feedback structure was wrong. +- "Beta participants felt ignored after providing feedback." Communication discipline missing; participants commit time and want to know it mattered. +- "We ran a closed beta that was effectively employees only." Internal-only beta; missed customer-context complexity. + +--- + +## The framework: 12 considerations for beta program management + +When designing or auditing a beta program, walk these 12 considerations. + +1. Structured-beta, not soft-launch or kitchen-sink. Calibrated cohort, intentional feedback, clear graduation. +2. Beta type matches signal need. Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. +3. Participants match the post-launch profile. Match the user the GA serves. +4. Cohort size calibrated to signal need. Smaller for bugs; larger for behavioral signal. +5. Onboarding contract clear. Expectations on both sides documented. +6. Feedback channels structured. 3-5 channels; signal not noise. +7. Mid-beta triage active. Feedback acted on during the beta. +8. Communication keeps participants engaged. Updates on what was heard and what is changing. +9. Graduation criteria explicit. Critical bugs cleared, friction addressed, behavioral validation, performance under load, support readiness, positive signal. +10. Wind-down treats participants well. Transition clarity, recognition, thank-you. +11. Postmortem feeds practice. Each beta improves the next. +12. Honest decisions on graduation. Either criteria met (graduate) or not (extend or reconsider). No tired-of-the-beta graduation. + +The output of the framework is a beta program that produces decision-grade signal, supports the GA launch, and treats participants well enough to recruit them for future betas. + +--- + +## Reference files + +- [`references/beta-type-decisions.md`](references/beta-type-decisions.md) - Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. +- [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md) - Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. +- [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md) - Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. +- [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md) - Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. +- [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md) - Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. +- [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md) - Triage cadence. Iteration discipline (what to fix during, what to defer). Communication with participants. +- [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md) - The six graduation criteria. The "tired of the beta" anti-pattern. Perpetual beta anti-pattern. +- [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md) - Graduation announcement, transition, recognition, postmortem. Treating participants well. +- [`references/common-beta-failures.md`](references/common-beta-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: betas earn their keep with structure + +A structured beta is one of the most useful product activities available. The cohort experiences the feature; the team learns from their experience; the GA launch ships with reduced uncertainty. The discipline pays back many times its cost. + +A soft-launch or kitchen-sink beta is one of the least useful. The team spends weeks running an activity that produces ambient activity without converting to learning. The GA launches with the same uncertainty the beta was supposed to address. + +The teams that earn returns on betas are the ones that take the structure seriously: cohorts calibrated to the GA profile, feedback channels designed for signal, mid-beta triage that uses what is being learned, graduation criteria that distinguish ready from tired, wind-down communication that treats participants well enough to recruit them again. + +When in doubt about whether a beta is ready, ask: are participants matched to the GA user, are feedback channels structured, is the team responding to feedback during the beta, are graduation criteria explicit and being applied honestly, will participants want to join the next beta? If yes to all of those, the beta is real. If no to any, the gap is where the beta will fail to convert participation into learning. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md b/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md new file mode 100644 index 0000000..a691d40 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-onboarding-templates.md @@ -0,0 +1,230 @@ +# Beta onboarding templates + +Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. + +Onboarding sets the tone for the beta. Done well, participants enter with clear expectations and stay engaged through the program. Done badly, participants drop off, fail to provide feedback, or violate confidentiality unintentionally. + +--- + +## The welcome communication + +The first message participants receive after accepting the invitation. + +What it covers. + +- Welcome and thank-you for joining. +- What the beta is: the feature, the goals, what is being validated. +- Beta duration: start date, end date, what graduation looks like. +- What is expected of participants: feedback channels, cadence, format. +- What participants get: access to the feature, support, recognition or compensation, post-GA terms. +- NDA reminder where applicable. +- How to access the feature: links, accounts, configuration steps. +- Who to contact: support escalation path, beta program manager. +- First feedback prompt: what the team would like to hear about in the first week. + +What it does not cover. + +- A complete product manual. The participant should be able to use the feature; in-product guidance handles the detail. +- Internal team structure or politics. Participants do not need to know who reports to whom. +- Future roadmap. The beta is about this feature; future plans are separate communication. + +Length. 400-800 words for substantive features. Shorter for simpler features. The welcome should be readable in 3-5 minutes. + +Tone. Warm but professional. Beta participants are doing the team a favor; the welcome reflects that. Avoid corporate-stiff or overly casual. + +--- + +## The expectations contract + +Both sides commit to specific behaviors. + +What the team commits to. + +- Communication cadence: regular updates (weekly or bi-weekly). +- Response to feedback: critical issues addressed quickly; friction issues prioritized; feature requests captured. +- Transparency: participants are told what is being changed based on feedback and what is being deferred. +- Graduation criteria: explicit criteria, applied honestly. +- Post-GA continuity: participants know what their access looks like after graduation (typically continued access; sometimes special pricing). + +What participants commit to. + +- Feedback through the structured channels (specific channels named). +- Confidentiality where NDA applies (no public posts, screenshots, or sharing of beta features outside the participant's organization). +- Reasonable engagement: not required to use the feature daily, but expected to use it enough to provide informed feedback. +- Willingness to engage in interviews if requested (with the right to decline specific interviews). + +The signed-or-implicit agreement. + +- For substantial NDAs, participants sign an explicit agreement. +- For lighter beta agreements, the welcome communication may be the implicit acceptance (participation implies agreement to terms). +- The team should know which approach applies and apply it consistently. + +--- + +## NDA considerations + +When NDAs are appropriate. + +NDA appropriate. + +- Unannounced features (the beta is essentially confidential). +- Features that affect competitive positioning (the team does not want competitors to see the feature early). +- Design partner programs with deep collaboration on feature shaping. +- Enterprise features that touch sensitive customer data or workflows. + +NDA not appropriate or unnecessary. + +- Open public betas. +- Features that have already been announced. +- Features where the team welcomes public discussion (e.g., developer-tool launches that benefit from community feedback). + +NDA enforcement reality. + +- NDAs in open beta are essentially unenforceable. Pretending an open beta has NDA protection is theater. +- Closed-beta NDAs are enforceable but require trust; the team should not invite participants who are likely to violate confidentiality. +- For sensitive betas, the cohort selection itself is the primary control; NDAs are the legal backstop. + +What an NDA covers. + +- Confidentiality of the beta feature, its functionality, and the team's plans. +- Restrictions on screenshots, public posts, recordings. +- Term: typically until the feature is publicly announced or for a defined period. +- Exceptions: feedback to the team is allowed; discussion within the participant's organization is usually allowed. + +--- + +## Feedback channel access + +What participants need to know about how to give feedback. + +Channel inventory. + +- Structured surveys: when they will arrive, how long they take, how to access. +- Async feedback forms: link, instructions, what fields to fill. +- Interview signups: how to volunteer for interviews, what compensation if any. +- In-product feedback widget: how to use, what context it captures. +- Support routing: how beta participants flag issues to the support team. +- Slack or community: if a beta-only channel exists, how to join and what tone is expected. + +Channel discipline. + +- Each channel serves a different purpose. The welcome communication explains which channel is for which feedback type. +- Avoid duplicating channels (multiple Slack-like channels for the same feedback) or confusing channel mappings. + +--- + +## Support paths + +How participants escalate issues. + +The escalation map. + +- Bug reports: filed through the structured form or support ticketing system tagged "beta." +- Critical issues (crashes, data loss): escalation contact named explicitly; not buried in standard support queues. +- Feature questions and how-to: routed to in-product help or beta program manager. +- Account issues: standard support paths or beta-aware support reps. + +Support team awareness. + +- Support team should know the beta is running and how to handle beta-tagged tickets. +- Beta-tagged tickets often deserve faster response than standard tickets (the participant is doing the team a favor; long support waits damage the relationship). +- Common beta issues should be documented for the support team in advance. + +--- + +## Incentive disclosure + +What participants get for joining. + +Common incentives. + +- Free access to the feature post-GA for some period. +- Discounted pricing on the feature post-GA. +- Beta-only feature flags or capabilities preserved post-GA. +- Recognition (named in changelog, on website, in launch communications) with consent. +- Gift cards, swag, or other compensation. +- Direct access to product team during the beta (some participants value this most). + +Disclosure discipline. + +- The welcome communication names the incentives explicitly. No surprise reveals at the end. +- Different participants may have different incentive packages (design partners often get more); each participant knows their package. +- The incentives match the commitment level. Light betas have light incentives; design partner programs have substantive ones. + +The "no incentive" pattern. + +- Some betas offer no formal incentive beyond access to the feature. +- This works for high-engagement audiences (developers, enthusiasts) where access itself is the incentive. +- It does not work for audiences where the time investment is significant; participants need a reason to engage substantively. + +--- + +## First-week onboarding + +What happens after the welcome message. + +The first week's actions. + +- Day 1: welcome arrives; participants get access; first-day checklist (set up, access feature, complete profile if applicable). +- Day 2-3: first feedback prompt arrives. Could be an in-product widget triggered after first usage, or an email asking specifically about the first impression. +- End of week 1: brief check-in. Are participants able to access? Have they used the feature? Any friction with onboarding itself? + +Onboarding-specific friction. + +- Beta participants who cannot access the feature in the first 24-48 hours often disengage. Access friction is the most consequential onboarding failure. +- Documentation that does not match the actual experience (because the docs were written for a slightly different feature version) frustrates early. +- Missing context about what the feature is for. Participants who do not know what the feature is meant to accomplish use it tentatively or not at all. + +--- + +## Onboarding for different beta types + +Different beta types warrant different onboarding intensity. + +Lightweight onboarding (open beta, RC validation). + +- Email welcome with key information. +- Self-service access. +- In-product guidance handles most setup. + +Standard onboarding (closed beta, structured cohort). + +- More substantial welcome email. +- Optional onboarding call for participants who request it. +- Beta program manager available via direct channel. + +Deep onboarding (design partner program, complex feature). + +- Onboarding call with each participant or company. +- Custom configuration support. +- Direct channel to product team for ongoing collaboration. + +The onboarding intensity matches the beta type. Heavyweight onboarding for an open beta with 5,000 participants is impossible; lightweight onboarding for a 5-partner design program under-invests in the relationships. + +--- + +## Common onboarding failures + +Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. + +Missing NDA where appropriate. Beta features get screenshotted on social before the team is ready. + +Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. + +No incentive clarity. Participants feel underrecognized; engagement decays. + +Welcome communication too long or too short. Too long: participants do not read; too short: participants miss critical context. + +Access friction in first 24-48 hours. Participants cannot get into the feature; many disengage permanently. + +Onboarding intensity mismatched to beta type. Heavy onboarding for an open beta wastes effort; light onboarding for a design partner program under-invests. + +--- + +## Methodology-level choices that stay in the public skill + +The welcome communication structure. The expectations contract for both sides. NDA considerations. Feedback channel access. Support paths. Incentive disclosure. First-week onboarding. Onboarding by beta type. Common failures. + +## Implementation choices that stay internal + +Specific welcome email templates. Specific NDA boilerplate. Specific support routing automation. Specific incentive packages and approval workflows. The team's own conventions for onboarding intensity. These vary by team and beta type. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md b/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md new file mode 100644 index 0000000..e835ce5 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md @@ -0,0 +1,239 @@ +# Beta-to-GA graduation criteria + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. + +Graduation is the decision that distinguishes a structured beta from beta theater. Honest graduation criteria, applied honestly, separate "ready for GA" from "we are tired of running the beta." Defining the criteria explicitly upfront prevents calendar-driven graduation decisions later. + +--- + +## The six graduation criteria + +The criteria that should be met before graduating from beta to GA. + +### 1. Critical bugs cleared + +The criterion. No known crashes, data loss, or core-flow failures. + +The validation. Bug tracker shows no open critical issues. The beta cohort has not reported new critical issues in the past 1-2 weeks. + +The exception. Some critical issues may be acceptable if they affect a tiny segment that the GA can either exclude or address with documentation. Decisions to graduate with known issues should be explicit. + +### 2. Friction issues addressed or accepted + +The criterion. Friction issues are either fixed before GA or documented as known limitations the team is choosing not to address pre-GA. + +The validation. Each friction issue from the beta has a disposition: fixed, fix-in-progress (with timeline), accepted-for-now (with rationale), accepted-permanently (with rationale). + +The honest disposition. "Accepted for now" is honest if the team plans to address post-GA. "Accepted permanently" is honest if the team has decided the friction is not worth the engineering cost. Hidden friction that the team hopes nobody will notice is not honest. + +### 3. Behavioral validation + +The criterion. Beta participants are using the feature in patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). + +The validation. Usage data from the beta cohort shows the feature being used in the ways the design assumed. Significant deviations are investigated; either the design is adjusted, or the GA experience is modified to support the actual usage pattern. + +The unexpected-pattern handling. + +- Pattern A: most beta participants are using the feature in a different way than the design assumed. The design is wrong; iterate before GA. +- Pattern B: a subset of participants is using the feature in an unexpected way that suggests an additional use case. Capture for post-GA expansion; do not delay GA. +- Pattern C: participants are not using the feature much at all. The feature may not be solving a real problem; reconsider whether to ship. + +### 4. Performance under load + +The criterion. The feature performs adequately at the scale GA will produce. + +The validation. Performance testing under projected GA load. Beta cohort performance was acceptable; the GA scale projection has been tested. + +The infrastructure-validation focus. For features where scale is the primary concern (data-processing features, real-time features, multi-tenant features), this criterion is the central one. RC betas often exist primarily to validate this. + +### 5. Documentation and support readiness + +The criterion. Help docs reflect actual usage; support team is trained on common issues; escalation paths work. + +The validation. + +- Help docs match the feature as it will ship at GA. +- Support team has been briefed and has handled at least the simulated beta-tier ticket volume. +- Common issues are documented for the support team's reference. +- Escalation paths from support to engineering are tested. + +The skip risk. Teams often graduate before docs and support are ready. The GA launch then catches the support team off-guard; tickets pile up; users have a worse experience than they would have with proper readiness. + +### 6. Positive signal sufficient + +The criterion. Beta feedback is net-positive enough to launch with confidence. + +The validation. + +- Survey signal shows positive sentiment among beta participants. +- Behavioral signal shows continued usage (participants are not just trying the feature once). +- Participants would recommend the feature to others. + +The "sufficient" calibration. Not all participants need to be delighted. A substantial majority finding value, with the dissenting voices understood (segment misfit, expectations mismatch, unfixable friction), is sufficient. A divided cohort with no clear majority signal is not. + +--- + +## The "tired of the beta" anti-pattern + +Graduation that happens because the team wants to be done with the beta. + +The pattern. + +- Beta has run for the planned duration. +- Some criteria are met; some are not. +- The team graduates anyway because "we have to ship at some point" or "the beta cannot run forever." + +Why it fails. + +- Unmet criteria mean the GA launches with known issues that are not yet addressed or acknowledged. +- Support, marketing, and customer success encounter problems the beta would have caught if extended. +- Trust degrades: customers experience friction the beta participants reported but the team did not fix. + +The cure. + +- Either extend the beta until criteria are met. +- Or graduate with explicit acknowledgment of the unmet criteria (known issues, deferred work). +- Or reset the beta if significant changes are needed. + +The discipline: the graduation decision is criteria-driven, not calendar-driven. Calendar pressure can inform whether to ship a smaller scope, but it should not produce graduation despite unmet criteria. + +--- + +## The perpetual beta anti-pattern + +Graduation that does not happen because the beta drifts indefinitely. + +The pattern. + +- Beta runs without firm graduation criteria. +- Issues keep surfacing; the team keeps fixing; the beta extends. +- 6 months later, the beta is still running. The "perpetual beta" branding becomes a strategic stance ("everything is always evolving"). +- The GA commitment is avoided. + +Why it fails. + +- Beta participants experience indefinite uncertainty about the feature's status. +- The team avoids the discipline of GA readiness; the feature stays in a less-mature state than it could be. +- Marketing, support, and customer success cannot operate around a beta-forever feature. +- Stakeholder trust degrades: the team is not shipping. + +The cure. + +- Force the graduation decision. Either the criteria are met (graduate) or they are not (decide what would make them met, set a timeline, commit). +- "Perpetual beta" as a strategic stance is rare and usually a rationalization. +- Some features genuinely need extended-beta status for valid reasons (regulatory complexity, unusual scale validation); these should be exceptions documented explicitly, not the default. + +--- + +## Honest graduation patterns + +When graduation criteria are mostly but not fully met. + +Graduation with known issues. + +- Some criteria fully met; one or two have known gaps. +- Graduate with explicit acknowledgment: "We are shipping with X known limitation; documented; will address in [timeline]." +- Communicate the known issues to support, marketing, customer success. +- Customers who hit the known issue are not surprised; they were warned. + +Graduation with extended monitoring. + +- Behavioral signal not fully validated due to cohort limitations. +- Graduate with monitoring infrastructure that surfaces issues at GA scale. +- Plan for fast iteration if monitoring catches issues post-GA. + +Graduation with phased rollout. + +- All criteria met for a subset of users; less certain for broader users. +- Graduate to the validated subset first; expand the rollout in phases. + +These patterns preserve graduation discipline while accommodating real-world constraints. + +--- + +## When NOT to graduate + +Conditions that warrant extending or resetting the beta. + +Not to graduate. + +- Critical bugs are unaddressed. +- Major friction issues affect mainline usage. +- Behavioral signal contradicts the design assumptions. +- Performance under projected load is inadequate. +- Documentation and support are not ready. +- Beta sentiment is divided without clear positive signal. + +The honest extension. + +- Acknowledge the gap explicitly. +- Define what would close the gap. +- Set a new timeline. +- Communicate to participants and stakeholders. + +The reset. + +- If the gap requires significant feature changes, end the current beta and start a new one with the changed feature. +- Do not blend "old beta" and "new feature" data. + +--- + +## Graduation decision-making + +Who decides graduation and how. + +The decision-maker. Typically the product manager who owns the feature, with input from engineering lead, design lead, and beta program manager. + +The decision process. + +- Beta program manager prepares a graduation review document: status against each criterion, known issues, recommendation. +- Decision meeting (60-90 minutes): review the document, discuss any open questions, make the decision. +- Decision recorded explicitly: graduate, extend, or reset. + +Stakeholder visibility. The decision is communicated to stakeholders (executives, marketing, sales, customer success) before participants are notified. + +Graduation timing. Once the decision is made, graduation typically takes 1-2 weeks to execute (final code, marketing prep, support readiness, participant communication). + +--- + +## Graduation criteria for different beta types + +The criteria adapt to the beta type. + +Closed beta with calibrated cohort. All six criteria apply. The cohort is small enough to validate behavioral signal directly. + +Open beta with large volume. Behavioral signal validates at scale. Critical bugs and performance criteria are more central. Documentation and support readiness scale with the open-beta visibility. + +RC validation. Performance under load is the central criterion. Other criteria should already have been met in prior alpha or beta stages. + +Design partner program. The criteria apply but graduation often happens incrementally (specific design partners moving to GA terms while the program continues with new partners). Less of a single graduation moment. + +Internal beta. Customer-context criteria (behavioral validation, support readiness for external) may need to be validated at GA rather than during beta. Honest disclosure: the beta did not fully validate the customer experience. + +--- + +## Common graduation failures + +Calendar-driven graduation. Graduate when the planned duration ends regardless of criteria. + +Criteria not defined upfront. Graduation decision happens without explicit criteria; subjective decision. + +Hidden known issues. Graduate with known issues that are not surfaced; customers and support discover them later. + +Perpetual beta. Indefinite extension; graduation decision avoided. + +Premature graduation. Graduate before behavioral signal has emerged or critical bugs are fully cleared. + +No stakeholder notification. Graduation happens; support, marketing, customer success encounter the GA launch unprepared. + +No participant communication about graduation. Beta participants are not told about graduation timing or what changes for them. + +--- + +## Methodology-level choices that stay in the public skill + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. Honest graduation patterns. When not to graduate. Graduation decision-making. Graduation criteria for different beta types. Common failures. + +## Implementation choices that stay internal + +Specific graduation review document templates. Specific decision-meeting formats. Specific stakeholder notification workflows. The team's own conventions for graduation timing. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md b/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md new file mode 100644 index 0000000..0995f48 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-type-decisions.md @@ -0,0 +1,228 @@ +# Beta type decisions + +Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. + +Beta type is the upstream decision that constrains everything downstream: who participates, what feedback channels make sense, what graduation looks like. Getting the type wrong makes the rest of the program harder. + +--- + +## Closed vs open + +The cohort-control axis. + +Closed beta. Invite-only. Participants are selected by the team based on criteria. Cohort is bounded. + +Strengths. + +- Calibrated cohort: the team knows who is in the beta and can match participants to the GA user profile. +- Quality of feedback: invited participants typically engage more substantively than self-selected open-beta users. +- NDA enforceability: closed cohorts can sign NDAs; open cohorts usually cannot. +- Synthesis tractability: bounded cohort means feedback volume is manageable. + +Weaknesses. + +- Recruiting overhead: identifying and inviting participants is real work. +- Limited diversity: the cohort reflects the team's recruiting choices; gaps in selection produce gaps in feedback. +- Slower feedback volume: smaller cohorts produce less total feedback. + +Open beta. Anyone can join. Cohort is self-selecting. + +Strengths. + +- Volume: large numbers of participants quickly. +- No recruiting overhead: participants opt in. +- Marketing value: open betas can build pre-launch audience awareness. + +Weaknesses. + +- Self-selection bias: early adopters and enthusiasts skew the cohort; their feedback may not represent the broader target user. +- Signal-to-noise ratio: most participants do not provide actionable feedback; the team must mine signal from volume. +- NDA difficulty: open cohorts cannot reasonably enforce NDAs; the feature is essentially public. + +--- + +## Alpha vs beta vs RC + +The polish axis. + +Alpha. + +- Very early. Significant bugs expected. +- Internal users or trusted partners only. +- Goal: surface fundamental issues before broader exposure. +- Feedback orientation: bug discovery, fundamental flow validation. + +Beta. + +- More polished. Major bugs caught; remaining issues are friction or edge cases. +- Broader cohort. External customers in calibrated cohorts. +- Goal: validate the feature works for real users in real contexts. +- Feedback orientation: usage patterns, friction, behavioral signal, edge cases. + +RC (release candidate). + +- Essentially launch-ready. Production-grade quality expected. +- Cohort can be large (open beta or extended beta). +- Goal: last validation before GA, performance at scale, infrastructure readiness. +- Feedback orientation: scale issues, infrastructure issues, last-mile polish. + +The progression. Many features pass through all three (alpha → beta → RC) before GA. Some skip alpha (sufficient internal testing) or skip RC (the beta is the last validation). The decision depends on feature complexity and risk tolerance. + +--- + +## Internal vs external + +The audience axis. + +Internal beta. Only employees use the feature. + +Strengths. + +- Fast feedback: employees are easy to recruit and follow up with. +- High engagement: employees usually feel some ownership of company products. +- NDA simplicity: confidentiality is implicit. + +Weaknesses. + +- Missing customer context: employees experience features differently than customers (familiarity, infrastructure context, motivations). +- Bias toward team-known patterns: employees use products in ways the team designed for; customers often use products differently. +- Limited signal: internal-only cannot validate customer-context complexity. + +External beta. Real customers use the feature. + +Strengths. + +- Real customer experience: feedback reflects how customers actually use the product. +- Behavioral signal: usage patterns from real customers inform GA decisions. +- Trust building: customers who beta-test become advocates. + +Weaknesses. + +- Requires customer relationship: cannot just turn the feature on for employees. +- Recruiting overhead: identifying willing customers and managing the cohort. +- Risk: bugs reaching customers can damage trust if not handled well. + +The combination. Most strong betas pass through both: internal alpha, then external beta. Some skip internal (when internal use cases differ enough from customer use cases that internal validation is misleading). + +--- + +## Time-bounded vs open-ended + +The duration axis. + +Time-bounded beta. A defined end date. Common durations: 4 weeks, 6 weeks, 8 weeks, 12 weeks. + +Strengths. + +- Forces the graduation decision. The end date arrives; the team must decide ready or not. +- Clarity for participants: they know how long they are committing. +- Resource bounding: the team's beta-running effort is bounded. + +Weaknesses. + +- Calendar pressure can force premature graduation: "we are at the end date so we are graduating" regardless of signal. +- Some signals need longer to surface: behavioral patterns may not be visible in 4 weeks. + +Open-ended beta. No defined end. The beta runs until the team decides to graduate. + +Strengths. + +- Signal-driven graduation: the team graduates when the criteria are met, regardless of calendar. +- Allows long-running validation: behavioral signal can develop over months. +- Suits design partner programs: ongoing relationships rather than time-bounded cohorts. + +Weaknesses. + +- Beta-purgatory risk: beta runs indefinitely because nobody forces the graduation decision. +- Participant fatigue: open-ended commitments without clear duration drain engagement. +- Resource drain: the team's beta-running effort is open-ended. + +The default. Most betas should be time-bounded. Open-ended is appropriate for design partner programs and specific extended-validation scenarios. + +--- + +## The combination decision + +How to choose across the four axes. + +Worked combinations. + +Standard structured beta: closed + beta + external + time-bounded (6-8 weeks). + +- Use when: shipping a meaningful feature that needs validation before GA. Most common combination. + +Alpha: closed + alpha + internal + open-ended (typically 2-6 weeks of internal testing before external alpha). + +- Use when: very early feature; need to surface fundamental issues before exposing customers. + +Design partner program: closed + alpha or beta + external + open-ended. + +- Use when: building a feature with deep customer involvement; small set of partner customers (3-10) collaborating closely on shaping the feature. + +Open early access: open + beta or RC + external + time-bounded (4-12 weeks). + +- Use when: pre-GA marketing matters; the feature is sufficiently polished that early access can build audience; team can handle the volume. + +RC validation: open or closed + RC + external + time-bounded (2-4 weeks). + +- Use when: the feature is essentially launch-ready; need last validation at scale or in the production environment. + +Internal-only RC: closed + RC + internal + time-bounded. + +- Use when: the feature is for internal users (e.g., admin tools used by support team), or when external testing is impractical for the type of feature. + +--- + +## When the combination decision goes wrong + +Common mismatches. + +Open + alpha. Open cohorts on an alpha-stage feature exposes customers to bugs the team has not caught. Damages trust. Cure: alpha should be closed; open up at beta stage when the feature is more polished. + +Closed + RC. Closed RCs miss the at-scale validation that RCs are meant to provide. The cohort is too small to surface scale issues. Cure: RCs are usually open or large-closed. + +External + alpha + open-ended. External customers commit to an alpha that has no end date and many bugs. Engagement decays. Cure: alpha should be internal or trusted-partner only; external alpha should be time-bounded and limited. + +Open + beta + open-ended. Volume cohort with no end date. The beta runs forever; participants lose interest; the team cannot synthesize. Cure: time-bound the beta; force graduation decision. + +--- + +## Beta type for specific contexts + +Common contexts and the typical type combinations. + +B2B SaaS feature launch. Closed + beta + external + time-bounded. 20-200 participants from existing customer base, 6-8 weeks. + +Consumer product launch. Open + beta + external + time-bounded (or open + RC). 1,000-10,000+ participants, 4-8 weeks. Marketing value is part of the rationale. + +Enterprise platform major release. Closed + alpha + design-partner + open-ended initially, then closed + beta + extended cohort + time-bounded for validation. + +Developer-tool launch. Open + beta + external + time-bounded, with public roadmap and community feedback channels. + +Internal tool launch. Closed + alpha or beta + internal + time-bounded. The cohort is the internal users who will use the tool post-GA. + +Compliance-impacting feature. Closed + extended beta + external + carefully selected design partners. The validation needs to surface compliance edge cases before GA. + +--- + +## Common beta-type failures + +Defaulting to soft-launch. Skipping beta-type decisions and just turning the feature on for some users. Decide the type explicitly. + +Defaulting to open beta for everything. Open volume substituted for calibrated cohorts. Open is right for some contexts; not for all. + +Mismatching alpha/beta/RC to feature polish. Calling something "beta" when it is alpha (too many bugs); calling something "RC" when it is beta (not yet production-grade). + +Internal-only when external context matters. Validates an internal experience that does not match what customers will encounter. + +Open-ended without graduation criteria. Beta drifts into perpetual beta because no firm end was set. + +--- + +## Methodology-level choices that stay in the public skill + +The four axes (closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended). Strengths and weaknesses per axis. Worked combinations. Common mismatches. Beta type for specific contexts. Common failures. + +## Implementation choices that stay internal + +Specific platform feature-flagging configurations. Specific recruitment platforms and processes. Specific NDA templates. Specific time-bounding workflows. The team's own conventions for beta-type decisions in different contexts. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md b/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md new file mode 100644 index 0000000..8f77cc2 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/beta-wind-down-communication.md @@ -0,0 +1,231 @@ +# Beta wind-down communication + +Graduation announcement, transition, recognition, postmortem. Treating participants well. + +The beta's wind-down is its closing impression. Done well, participants leave the beta engaged and willing to participate in future betas. Done badly, participants feel discarded after providing significant feedback. + +--- + +## The graduation announcement + +Communication to participants when the beta graduates. + +Timing. 1-2 weeks before graduation, with confirmation at graduation. + +Content. + +- The feature is graduating to GA. Specific date. +- What changes for participants. +- What does not change. +- Recognition or thank-you for participation. +- Information about post-GA support, pricing, or special terms. +- Any beta-specific features or terms that will not carry to GA. + +Tone. Warm, appreciative. Participants invested time; the announcement reflects that. + +Length. 300-600 words. Long enough to cover the necessary information; short enough to be readable. + +--- + +## What changes for participants at graduation + +Continued access. Most beta participants retain access to the feature post-GA. The beta was their preview; GA continues their use. + +Pricing transitions. If the feature has paid tiers, participants need to know: + +- Does beta access include free use of the feature post-GA for some period? +- Does the feature require an upgraded plan for full access? +- Are there special pricing terms for beta participants (early-bird discount, lifetime grandfathering, etc.)? + +Feature stability. Communicate what level of stability participants should expect post-GA. Beta features sometimes have rough edges; GA implies stability commitments. + +Support transition. Beta-aware support routing typically ends at GA. Participants now use standard support channels. + +Beta-only features. Some features in the beta may not make GA (deprecated, simplified, removed). Participants who relied on those features need clear communication about alternatives. + +--- + +## Recognition + +Beta participants invested time providing feedback. Recognition matters. + +Forms of recognition. + +- Named in changelog or launch communications (with consent). +- Gift cards or compensation for substantial time investment. +- Swag for closed-beta participants. +- Advance access to future betas. +- Direct thank-you from product team, often via personal email. +- Public acknowledgment in marketing or community materials. + +Calibration. + +- Light betas: direct thank-you, possibly modest swag. +- Standard betas: thank-you, swag, post-GA continued access on favorable terms. +- Design partner programs: substantial recognition, sometimes including case studies, named partnerships, financial compensation. + +The discipline. Recognition matches the participant's investment. Light recognition for a heavy commitment feels dismissive; heavy recognition for a light commitment is unnecessary. + +--- + +## The post-beta survey + +A final feedback collection at graduation. + +Purpose. Capture overall reflections on the beta experience and the feature. + +Content. + +- Overall feature satisfaction. +- Likelihood to continue using post-GA. +- Likelihood to recommend. +- What worked well in the beta program (process feedback, not feature feedback). +- What could be improved in future betas. +- Optional open-ended reflections. + +Length. 5-10 questions, 5-10 minutes to complete. + +Why it matters. The post-beta survey closes the loop with participants and informs the team's beta-program practice. The process feedback is particularly valuable: future betas improve based on past feedback. + +--- + +## The beta postmortem + +Internal review of what the beta produced. + +Timing. Within 1-2 weeks of graduation. + +Participants. Beta program manager, product manager, engineering lead, design lead, customer success lead, support lead. + +Content. + +- What was learned from the beta? (Patterns, behavioral validation, friction discovery.) +- What changed in the GA launch as a result? +- What worked well in the beta program (process)? +- What did not work? What would the team do differently next time? +- What patterns recur across multiple betas? Are there lessons for the broader practice? + +Output. A short postmortem document. Surfaces lessons. Informs future betas. + +Why it matters. Beta programs improve through accumulated learning. Without postmortems, the team repeats the same mistakes; with postmortems, the practice gets sharper over time. + +--- + +## Recruiting for future betas + +The wind-down is a recruiting moment for future betas. + +The pattern. Participants who had a good beta experience are likely to participate in future ones. The wind-down communication can include an invitation: would they like to be considered for future betas? + +The benefits. + +- Builds a roster of engaged beta participants for future programs. +- Reduces recruiting overhead for future betas. +- Strengthens the participant relationship. + +The discipline. Do not over-commit; future betas should not be promised in ways that are not honored. The invitation is to be considered, not a guarantee. + +--- + +## Handling beta-only features that do not make GA + +Sometimes beta features include capabilities that are removed or simplified at GA. + +Why it happens. + +- The feature scope was reduced based on beta findings. +- Some capabilities did not perform well enough to ship at GA. +- The team learned the capability was not load-bearing. + +The communication. + +- Surface the change explicitly. Do not silently remove. +- Explain the reasoning where appropriate. +- Provide alternatives or workarounds for participants who relied on the removed capability. +- Acknowledge the impact on participants. + +The participant impact. Some participants may push back; their usage assumed the capability would persist. The team must decide whether to extend support, offer migration help, or accept the participant churn. + +--- + +## Special cases: extended beta + +Some betas extend beyond their planned duration. + +Communication for extension. + +- Tell participants when the extension is decided, not when the original end date passes. +- Explain why the extension is needed. +- Give a specific new end date. +- Acknowledge the participant impact (they committed to the original timeline). +- Provide an option to opt out if the extension is significant. + +Avoid. + +- Silent extensions where the planned end passes without acknowledgment. +- Multiple extensions that erode the timeline credibility. +- Extensions framed as "no big deal" when they affect participants' ongoing time investment. + +--- + +## Special cases: beta cancellation + +Sometimes the team decides not to graduate the feature to GA. + +Why it happens. + +- The beta revealed the feature does not work as intended. +- Strategic shift redirected resources. +- The feature would compete poorly at GA scale. + +The communication. + +- Be honest about the cancellation. +- Acknowledge the participants' time investment. +- Explain (at appropriate level of detail) why the cancellation. +- Discuss what happens to participants' beta data, configurations, etc. +- Recognize the participation despite the cancellation. + +The participant impact. Cancellation can frustrate participants who invested time. Honest communication and good recognition mitigate the impact. + +--- + +## Long-term participant relationships + +Beta participants represent ongoing relationships, not transactional interactions. + +The relationship investment. + +- Participants who had a good beta experience may become advocates, references, case study subjects. +- Future product strategy benefits from continued conversation with beta alumni. +- Customer success can use beta participation as relationship signal. + +The maintenance. Periodic check-ins with notable beta participants strengthen relationships even outside formal beta programs. Light-touch communication (annual newsletter, occasional product updates, personalized outreach for major launches) maintains the connection. + +--- + +## Common wind-down failures + +Silent graduation. Beta participants discover graduation through the public launch announcement rather than through advance communication. + +Vague transition information. Participants do not know what changes for them; uncertainty produces churn. + +Insufficient recognition. Heavy participation rewarded with thin thank-you; participants feel dismissed. + +Missing post-beta survey. Process feedback is lost; future betas do not improve. + +No postmortem. Internal lessons are lost; the team repeats mistakes. + +Surprise feature removals. Beta-only features removed without warning; participants discover at GA that capabilities they relied on are gone. + +No invitation to future betas. The relationship ends at graduation; future betas restart recruitment from scratch. + +--- + +## Methodology-level choices that stay in the public skill + +The graduation announcement structure. What changes for participants. Recognition forms and calibration. The post-beta survey. The beta postmortem. Recruiting for future betas. Handling beta-only feature removals. Extended betas. Beta cancellations. Long-term relationships. Common failures. + +## Implementation choices that stay internal + +Specific graduation announcement templates. Specific recognition packages and approval. Specific postmortem templates. Specific CRM tracking of beta alumni. The team's own conventions for relationship maintenance. These vary by team. diff --git a/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md b/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md new file mode 100644 index 0000000..1457a9e --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/cohort-sizing-patterns.md @@ -0,0 +1,207 @@ +# Cohort sizing patterns + +Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. + +Cohort size is a calibration decision, not a maximize-volume decision. Each beta has a specific signal need; the right cohort size is the smallest that produces that signal reliably. + +--- + +## Saturation patterns by feedback type + +Different kinds of feedback saturate at different cohort sizes. + +Critical bugs (crashes, data loss, broken core flows). + +- Saturate fast: most surface in the first 1-2 weeks with 20-30 participants. +- Beyond ~50 participants, additional volume produces few new critical bugs. +- The cohort size for bug discovery: 20-50 participants is usually sufficient. + +Friction issues (workflow interruptions, confusing flows, slow performance in specific cases). + +- Saturate moderately: most surface in 2-4 weeks with 50-100 participants. +- Volume helps surface friction in less-common usage patterns. +- The cohort size for friction discovery: 50-200 participants typical. + +Behavioral patterns (how users actually use the feature, what flows they follow, what features they ignore). + +- Saturate slowly: 4-8 weeks with 100-500 participants needed for clear patterns. +- Patterns require usage volume; small cohorts may not generate enough usage to see patterns. +- The cohort size for behavioral signal: 100-500+ participants typical. + +Edge cases (unusual configurations, rare usage contexts, specific environment combinations). + +- Saturate very slowly: 500+ participants needed; some edge cases never surface in beta and are discovered post-GA. +- Volume is the only way to surface low-frequency edge cases. +- The cohort size for edge case discovery: 500-5,000+ participants; even at this scale, rare cases may slip through. + +Performance under load (scale-related issues, infrastructure constraints, concurrent-use issues). + +- Saturate when cohort exceeds the load threshold the issue requires. +- 1,000-10,000+ participants for at-scale validation. +- Often the central goal of RC betas. + +--- + +## Sizing decisions for different beta goals + +The cohort size matches what the team needs to learn. + +Goal: Catch critical bugs before GA. + +- Cohort size: 20-50 participants. +- Duration: 2-4 weeks. +- Closed cohort, calibrated to GA user profile. +- Most critical bugs surface fast; beyond this, returns diminish. + +Goal: Validate behavioral assumptions about how users will use the feature. + +- Cohort size: 100-300 participants. +- Duration: 4-8 weeks. +- Closed cohort with variety across usage patterns. +- Behavioral patterns need usage volume to emerge clearly. + +Goal: Validate product-market fit assumptions for a major new feature. + +- Cohort size: 200-500 participants. +- Duration: 8-12 weeks. +- Closed cohort spanning segments. +- Long enough duration to see retention and continued usage, not just initial engagement. + +Goal: Validate at-scale infrastructure for a launch. + +- Cohort size: 1,000-5,000+ participants. +- Duration: 4-8 weeks. +- Often open beta or large closed RC. +- Volume is the point; calibration is less important than scale. + +Goal: Build a design partner program for ongoing collaboration. + +- Cohort size: 3-10 partners. +- Duration: open-ended (months to years). +- Highly calibrated cohort with strong relationships. +- Depth over breadth; the program is qualitative collaboration, not at-scale validation. + +Goal: Generate pre-launch marketing and audience. + +- Cohort size: 1,000-10,000+ participants. +- Duration: 4-12 weeks. +- Open beta with marketing-driven recruitment. +- The cohort serves both validation and pre-launch buzz. + +--- + +## The size-matches-signal principle + +The cohort should be the smallest size that produces the signal the team needs. + +Why "smaller is better when calibrated." + +- Smaller cohorts produce more synthesizable feedback. The team can read every transcript, review every survey response, follow up with every participant who reports an issue. +- Smaller cohorts make participant relationships stronger. Each participant feels seen; engagement is higher. +- Larger cohorts produce volume that can drown signal. The team cannot synthesize 5,000 pieces of feedback as well as 50. + +When larger is necessary. + +- The team needs at-scale validation (load, concurrent users, edge cases). +- The team needs marketing reach. +- The team needs behavioral signal that requires substantial usage volume. + +The discipline. Default to the smallest cohort that produces the needed signal. Justify any larger size against specific signal needs. + +--- + +## Cohort size and feedback channel design + +Larger cohorts require different feedback channel design than smaller ones. + +For cohorts of 5-50. + +- Direct channels work: email, dedicated Slack, structured interviews. +- The team can engage with each participant individually. +- Synthesis can include reviewing all feedback. + +For cohorts of 50-500. + +- Mixed channels: structured surveys + sample interviews + in-product feedback widgets. +- Sampling required for synthesis: review all surveys, sample interviews and tickets. + +For cohorts of 500-5,000. + +- Aggregated channels: in-product feedback widgets, support ticket aggregation, automated surveys. +- Heavy sampling: review aggregate patterns, sample individual feedback. + +For cohorts of 5,000+. + +- Volume aggregation: NPS-style scoring, automated categorization, statistical analysis of usage patterns. +- Individual feedback rarely reviewed; patterns are the signal. + +The implication. Beta planning includes feedback channel design appropriate to cohort size. Mismatches (small cohort with aggregated channels, or large cohort with direct channels) produce friction. + +--- + +## Adjusting cohort size mid-beta + +Sometimes the team realizes mid-beta that the cohort is wrong-sized. + +Cohort too small. + +- Symptom: feedback volume is insufficient to see patterns. +- Cure: open recruitment for additional participants, applying the same selection criteria. +- Caution: late additions have less time in the beta; their feedback covers less of the beta period. + +Cohort too large. + +- Symptom: feedback volume overwhelms synthesis capacity; the team is reactive rather than analytical. +- Cure: usually do not reduce; instead, scale up synthesis capacity (more reviewers, more aggregation tooling). Reducing cohort feels like a betrayal to participants. +- Prevention: better sizing decision upstream. + +Cohort skewed. + +- Symptom: feedback patterns reflect skew (one segment over-represented). +- Cure: targeted recruitment to balance the cohort, or explicit acknowledgment of skew in synthesis. +- The cohort cannot always be re-balanced quickly; sometimes the synthesis adjusts for the skew rather than the cohort. + +--- + +## Cohort and beta duration + +Cohort size and duration interact. + +Short beta (2-4 weeks). Smaller cohort works because feedback saturates faster on critical issues. 20-100 participants typical. + +Medium beta (4-8 weeks). Mid-size cohort matches the duration. 50-300 participants typical. + +Long beta (8+ weeks). Larger cohort works because behavioral signal needs duration. 100-1,000+ participants. + +The mismatch failures. + +- Long beta with small cohort: insufficient volume; the duration produces no proportional signal. +- Short beta with very large cohort: insufficient time; the volume produces no proportional learning. + +The matching. Beta duration and cohort size both follow from signal need; they should be consistent. + +--- + +## Common cohort sizing failures + +Defaulting to "more is better." Large cohorts where small calibrated ones would produce stronger signal. + +Sizing without reference to signal need. Cohort size set arbitrarily; team cannot defend why this size. + +Cohort size mismatched to duration. Small cohort in a long beta produces sparse signal; large cohort in a short beta produces noise. + +Cohort size mismatched to feedback channel design. Direct channels with too many participants overwhelm; aggregated channels with too few participants under-utilize. + +Mid-beta cohort changes without synthesis adjustment. Cohort grows or shrinks; the synthesis approach does not adapt. + +Confusing volume with signal. Larger cohort numbers reported as success; the team did not actually learn proportionally more. + +--- + +## Methodology-level choices that stay in the public skill + +The saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. Cohort size and feedback channel design alignment. Adjusting cohort size mid-beta. Cohort and beta duration interaction. Common failures. + +## Implementation choices that stay internal + +Specific recruitment automation tooling. Specific aggregation tooling for large cohorts. Specific synthesis processes for different cohort sizes. The team's own conventions for sizing within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md b/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md new file mode 100644 index 0000000..204a1c2 --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/common-beta-failures.md @@ -0,0 +1,205 @@ +# Common beta failures + +Ten-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most beta failures share a single root, which is treating beta as ceremony rather than as decision input. + +--- + +## Failure 1: Our beta produced no signal + +Symptom. The beta ran. The team has nothing actionable to show for it. The GA launch will happen with the same uncertainty the beta was supposed to address. + +Diagnosis. Soft-launch pattern. No structured selection, no defined feedback collection, no graduation criteria. + +Cure. Restructure the beta. Define the cohort, channels, criteria, and triage cadence. If the current beta cannot be saved, plan a more structured beta for the next feature. + +Prevention. Plan beta structure at the start, not after the beta has been running. + +--- + +## Failure 2: Our beta has 5,000 users and we cannot synthesize + +Symptom. Open beta or large cohort. Volume is high. The team is reactive rather than analytical. Synthesis cannot keep up. + +Diagnosis. Kitchen-sink. Cohort too large for the structured signal the team needs. + +Cure. Two paths. Scale up synthesis capacity (more reviewers, aggregation tooling). Or reduce the active cohort by focusing structured channels on a calibrated subset (e.g., select 200 active participants for interviews; let the rest contribute through aggregated channels). + +Prevention. Size cohort to match synthesis capacity. Larger cohorts require aggregated feedback infrastructure. + +--- + +## Failure 3: Our beta participants never gave feedback + +Symptom. Few survey responses. Few in-product widget submissions. Few interview signups. The cohort is silent. + +Diagnosis. Onboarding contract was unclear or feedback channels were friction-laden. Participants did not know what was expected or could not easily give feedback. + +Cure. Re-engage. Send specific, prompted requests for feedback. Make the channels easier (in-product prompts, simpler forms). Communicate what is being heard from those who do respond. + +Prevention. Onboarding makes feedback expectations explicit. Channels are designed for low friction. + +--- + +## Failure 4: We graduated to GA on schedule but launched with critical bugs + +Symptom. The GA launches. Critical issues that the beta cohort would have surfaced (or did surface but were not addressed) appear post-GA. + +Diagnosis. Graduation criteria were not enforced. The decision was calendar-driven; the team graduated before the criteria were met. + +Cure. Damage control: address the bugs quickly, communicate transparently, reset support expectations. + +Prevention. Graduation criteria are enforced honestly. The decision is criteria-driven, not calendar-driven. If criteria are not met, extend the beta or graduate with explicit acknowledgment of unmet criteria. + +--- + +## Failure 5: Our beta has been running for 8 months with no graduation + +Symptom. Beta has run far longer than planned. No firm graduation date. The team has avoided the GA decision. + +Diagnosis. Perpetual beta. No firm graduation criteria; the team avoided commitment. + +Cure. Force the graduation decision. Define criteria explicitly. Decide: graduate now, graduate by a specific date, or reset the beta. + +Prevention. Time-bound the beta from the start. Define graduation criteria upfront. Force the decision when the criteria are met or when the time is up. + +--- + +## Failure 6: Beta participants vented on Twitter before the launch + +Symptom. Beta participants posted screenshots, mentioned the feature publicly, or discussed the beta outside the cohort. + +Diagnosis. NDA missing or unclear. Trust violation early erodes participant willingness; broader visibility may damage launch plans. + +Cure. Damage control depending on impact. Reach out to participants individually. Adjust the launch plan if the leaked information affects positioning. + +Prevention. NDAs in place where appropriate. Confidentiality expectations explicit in onboarding. Cohort selection includes trust assessment. + +--- + +## Failure 7: The beta surfaced patterns we did not act on + +Symptom. The beta produced clear feedback about specific issues. The GA launches without addressing them. Customers hit the same issues post-GA. + +Diagnosis. Mid-beta triage missing. Feedback was collected but not used during the beta. + +Cure. For the GA: address the issues quickly post-launch; communicate transparently. For future betas: implement the triage cadence and iteration discipline. + +Prevention. Weekly triage cadence. Categorization of feedback. Iteration on critical and high-impact items during the beta. + +--- + +## Failure 8: The GA launch surprised us + +Symptom. Issues emerge at GA that the team did not anticipate from the beta. The beta did not actually validate the GA experience. + +Diagnosis. Cohort or feedback structure was wrong. The cohort did not match the GA user; the channels did not surface the kinds of issues the GA exposed. + +Cure. Address the surprises post-GA. Investigate the gap between beta and GA experience. Apply lessons to future betas. + +Prevention. Cohort calibrated to GA user. Channels designed to surface the kinds of signal the GA decision needs. Validation of the cohort-GA match before the beta starts. + +--- + +## Failure 9: Beta participants felt ignored after providing feedback + +Symptom. Participants gave feedback. The team did not communicate what was heard or addressed. Participants disengaged. + +Diagnosis. Communication discipline missing. Participants commit time and want to know it mattered. + +Cure. Re-engage with appreciation and specific acknowledgment. For future participants, tighten the communication discipline. + +Prevention. Weekly or bi-weekly updates to participants. Updates reference specific feedback. Participants who give substantive feedback receive direct acknowledgment. + +--- + +## Failure 10: We ran a closed beta that was effectively employees only + +Symptom. The "external beta" included primarily employees, employees' family members, or very-friendly customers. Not actual representative customers. + +Diagnosis. Internal-only beta with external branding. Missed the customer-context complexity. + +Cure. Run a true external beta before GA, even if shorter. Apply lessons to future cohort selection. + +Prevention. Cohort selection includes "are these actually external customers using the product in real conditions?" Internal-leaning cohorts get flagged in cohort review. + +--- + +## Failure 11: Cohort and channels mismatched + +Symptom. Small cohort with aggregated channels (no signal extracted from the small volume). Or large cohort with direct channels (overwhelmed synthesis). + +Diagnosis. Cohort size and channel design did not align. + +Cure. Adjust mid-beta if possible: scale synthesis for large cohorts, deepen direct channels for small ones. + +Prevention. Cohort size and channel design decided together. Mismatches caught at planning. + +--- + +## Failure 12: Feedback collected but not synthesized + +Symptom. Surveys completed; widgets submitted; interviews recorded. The beta ends; the team has not synthesized the feedback into patterns or recommendations. + +Diagnosis. Synthesis was treated as optional or postponed. Without synthesis, the feedback never produced decisions. + +Cure. Allocate synthesis time post-beta. Apply discovery-research-synthesis discipline (see that skill). Produce the synthesis even if delayed. + +Prevention. Plan synthesis as part of the beta timeline. Allocate explicit time and ownership. + +--- + +## Failure 13: Wind-down treated participants poorly + +Symptom. Participants graduated to GA without clear transition information. Recognition was thin or missing. Future-beta recruitment is harder because alumni are unenthused. + +Diagnosis. Wind-down communication missed key elements. Recognition was insufficient for the time invested. + +Cure. Reach out individually to participants who feel underrecognized. Adjust future wind-down templates. + +Prevention. Wind-down communication template covers all elements (transition, recognition, post-survey, future beta invitation). + +--- + +## Failure 14: No postmortem + +Symptom. Beta ends; team moves on. Lessons from this beta do not inform future ones. Patterns recur across multiple betas because nobody surfaced them. + +Diagnosis. Postmortem was skipped. The beta program does not improve. + +Cure. Run a delayed postmortem if feasible. Establish postmortem as a non-negotiable step. + +Prevention. Postmortem on the timeline. Owner identified. Lessons documented and applied. + +--- + +## Failure 15: Beta scope crept + +Symptom. Mid-beta, additional capabilities were added based on participant requests. The beta validated a different feature than the original. + +Diagnosis. Scope creep during the beta. Feature requests were absorbed into the live beta. + +Cure. Reset the beta if the changes are significant. Capture for post-GA roadmap rather than addressing during the beta. + +Prevention. Triage discipline rejects scope-expanding feature requests during the beta. Capture for post-GA; do not add. + +--- + +## The cross-cutting pattern + +Most beta failures share a single root: treating beta as ceremony rather than as decision input. + +Ceremony focuses on running a beta because betas are expected: invite participants, collect feedback, ship the GA. The beta is a stage gate, not a learning loop. + +Decision input focuses on what the beta needs to inform: which decisions, what signal will inform them, what cohort and channels will produce that signal. The beta is structured around the decision it serves. + +The fix for almost any beta failure starts with the same question: what specifically did the team need to learn from this beta, and how is the beta structured to produce that learning? When the answers are clear, the beta becomes load-bearing. When the answers are vague, the beta becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-decision pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md b/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md new file mode 100644 index 0000000..49e1bbf --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/feedback-collection-patterns.md @@ -0,0 +1,295 @@ +# Feedback collection patterns + +Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. + +The feedback collection design is what determines whether the beta produces signal or noise. Structured channels capture usable data; ad-hoc venting channels produce volume that does not synthesize. + +--- + +## Structured surveys + +Surveys at defined points in the beta. + +The structure. + +- 5-15 questions per survey. +- Mix of structured questions (Likert scale, multiple choice) and 1-2 open-ended questions. +- Tied to specific learning goals: each question has a reason for being there. +- Sent at defined points: end of week 1, mid-beta, end of beta. + +Strong survey questions. + +- "On a scale of 1-7, how likely are you to use this feature daily?" (closed-ended; quantitative signal) +- "What's the most useful thing you've done with this feature so far?" (open-ended; surfaces use cases) +- "What was confusing or frustrating in your first week?" (open-ended; surfaces friction) +- "Compared to how you did this task before, is this feature better, worse, or about the same?" (specific comparison) + +Weak survey questions. + +- "Do you like the feature?" (binary; not actionable) +- "What features would you like next?" (out of beta scope; produces wishlist) +- "How can we improve?" (too open-ended; produces unfocused responses) + +Why structured surveys work. + +- Quantitative signal aggregates. Mid-beta NPS or satisfaction trend lines surface signal. +- Open-ended questions tied to specific topics produce focused qualitative data. +- Participants understand what is being asked; response rates are higher than for vague open-ended surveys. + +--- + +## Async feedback forms + +Forms participants fill when they encounter specific issues. + +The structure. + +- Always-available link or in-product entry point. +- Form fields prompt for specific information: use case, severity, expected vs actual behavior, screenshots if applicable. +- Auto-routes to the team's tracking system (issue tracker, feedback aggregation tool). + +Strong form fields. + +- "What were you trying to do?" (use case context) +- "What did you expect to happen?" (mental model) +- "What actually happened?" (observed behavior) +- "How blocking is this?" (severity) +- "Steps to reproduce" (when applicable) + +Why async forms work. + +- Captures issues at the moment they happen. +- Structured fields produce consistent data across submissions. +- Synthesis is easier when each submission has the same information shape. + +--- + +## Structured interviews + +30-60 minute interviews with a subset of participants. + +The structure. + +- 5-15 interviews per beta, depending on cohort size. +- Mid-beta or near end of beta. +- Discussion guide tied to the team's learning goals. +- Recorded with permission; transcribed for synthesis. + +Strong interview prompts. + +- "Walk me through the last time you used this feature. What were you trying to do?" +- "What was the most useful thing about it? What was the most frustrating?" +- "How did you decide to use this instead of [alternative]?" +- "Looking back, what do you wish was different?" + +Why structured interviews work. + +- Depth that surveys cannot capture. +- Specific moments and decisions surface in conversation that participants would not write into surveys. +- The qualitative data complements the quantitative survey data. + +Cross-reference `discovery-research-synthesis` for the broader interview discipline. Beta interviews are validation-stage; the interviewing methodology is similar. + +--- + +## In-product feedback widgets + +Feedback collection contextualized to the moment. + +The structure. + +- Trigger: button or prompt within the beta feature. +- Captures: what the user was doing (page or context), brief feedback text, optional rating. +- Routes to the team's tracking system. + +Strong in-product widget design. + +- Triggered after specific moments (completing the feature's primary action, abandoning a flow). +- Brief: 1-3 fields max. +- Optional severity or sentiment rating. +- Captures the page or context automatically. + +Why in-product widgets work. + +- Capture friction at the moment, not weeks later. +- Context is preserved automatically. +- Low friction encourages submissions. + +--- + +## Beta-aware support tickets + +Support tickets routed to a beta-aware support team. + +The structure. + +- Beta participants flagged in the support system. +- Tickets from beta participants get special handling: tagged "beta," routed to support reps trained on the feature, given priority response. +- Common beta issues documented for the support team in advance. + +Strong beta-support practices. + +- Faster response than standard tickets (the participant is doing the team a favor). +- Support reps escalate beta issues to product team where the issue affects beta program decisions. +- Patterns across tickets surface to the beta program manager. + +Why beta-aware support works. + +- Surfaces issues participants encounter "in the wild," not just the issues they choose to flag through formal channels. +- Captures the support burden of the feature, which informs GA support readiness. + +--- + +## Channels that fail + +Common feedback channels that produce noise rather than signal. + +Beta-only Slack channels for venting. + +- Participants vent in real time. +- Mixes critical signal with casual chat. +- Nobody synthesizes. +- High-engagement participants drown out quieter ones. +- Cure: structured channels instead, or use Slack for community building rather than feedback collection. + +"Reply to this email with feedback." + +- Returns long unstructured emails. +- Synthesis is hard; useful patterns get lost. +- Cure: structured forms or surveys. + +End-of-beta survey only. + +- Catches only what participants remember at the end. +- In-the-moment friction is forgotten. +- Cure: surveys at multiple points; in-product widgets for moment-of capture. + +"Tell us anything." + +- Unfocused open-ended prompts produce unfocused responses. +- Participants do not know what is wanted; many do not respond. +- Cure: specific prompts tied to what the team needs to learn. + +--- + +## Channel mix discipline + +Most structured betas use 3-5 channels. Each surfaces different signal. + +Typical channel mix. + +- 1 structured survey at end of week 1 (quantitative + first-impression qualitative). +- 1 structured survey at mid-beta (quantitative trend + behavior signal). +- Always-available async feedback form (specific issues as they arise). +- 5-10 structured interviews near end of beta (qualitative depth). +- In-product feedback widget (in-the-moment friction). +- Beta-aware support routing (issues participants choose to escalate). + +The synthesis. The team synthesizes across channels. Patterns that appear in multiple channels are stronger; signals from a single channel are weaker. + +Channel mix calibration. + +- Smaller cohorts (5-50): more interviews, less aggregation. +- Larger cohorts (100-500): more surveys and aggregation, fewer interviews. +- Largest cohorts (500+): heavy aggregation, sampling for interviews. + +--- + +## Feedback synthesis cadence + +How feedback gets reviewed during the beta. + +Weekly synthesis. + +- 1-2 hours weekly during the beta. +- Review feedback across all channels for the week. +- Categorize: critical bug, friction, feature request, positive signal, edge case. +- Surface patterns: what recurring feedback are we seeing? + +Bi-weekly pattern review. + +- 1-2 hours bi-weekly. +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening? +- Decide: what to fix during the beta vs what to defer to post-GA roadmap. + +End-of-beta synthesis. + +- Substantial work: 1-2 weeks of synthesis depending on cohort size. +- Apply discovery-research-synthesis discipline (see that skill). +- Output: beta synthesis document with patterns, implications, and graduation recommendation. + +--- + +## Feedback signal quality + +Not all feedback is equally valuable. + +High-signal feedback. + +- Specific moments of friction with reproducible context. +- Patterns across multiple participants. +- Behavioral data showing what users actually do (vs what they say). +- Comparison to alternatives (what users tried before, why they switched). + +Lower-signal feedback. + +- One-off complaints with no pattern. +- Hypothetical preferences ("it would be nice if..."). +- Wishlist features unrelated to the beta scope. +- Venting without specific context. + +The discipline. Synthesis weights higher-signal feedback. Lower-signal feedback gets noted but does not drive decisions. + +--- + +## Feedback volume management + +Managing the flow of feedback as the beta runs. + +Volume signals. + +- Critical issues surface fast: most appear in the first 2 weeks. +- Friction issues surface continuously through the beta. +- Behavioral signal accumulates; visible by mid-beta. + +Volume management. + +- The team's synthesis capacity bounds usable volume. Beyond that capacity, additional feedback produces less actionable signal. +- For larger cohorts, aggregate channels (surveys, in-product widgets) scale better than direct channels (Slack, email). + +Burnout risk. + +- Beta program managers reading 100+ feedback items per week burn out. +- Triage is the discipline: not all feedback gets equal attention. +- Critical and pattern feedback gets full attention; one-off venting gets noted briefly. + +--- + +## Common feedback collection failures + +Single-channel reliance. Only one feedback channel; misses signal that other channels would have caught. + +Channels not tied to learning goals. Feedback collected without clear purpose; synthesis cannot tell what to do with it. + +Noisy channels (Slack venting). High volume, low signal-to-noise ratio. + +End-of-beta only. Misses in-the-moment friction; relies on participant memory. + +Vague prompts. Open-ended questions without focus; produces unfocused responses. + +No mid-beta synthesis. Feedback collected but not reviewed until end; opportunities to address issues during the beta missed. + +Feedback channels that conflict. Multiple Slack channels for the same purpose; participants confused about where to post. + +No closing the loop. Participants give feedback; team never tells them what was heard or changed; engagement decays. + +--- + +## Methodology-level choices that stay in the public skill + +Channels that work (structured surveys, async forms, interviews, in-product widgets, beta-aware support). Channels that fail. Channel mix discipline. Feedback synthesis cadence. Signal quality discipline. Volume management. Common failures. + +## Implementation choices that stay internal + +Specific survey tools and templates. Specific feedback form integrations. Specific in-product widget implementations. Specific support ticketing systems. The team's own conventions for channel selection. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md b/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md new file mode 100644 index 0000000..aa2614c --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/mid-beta-triage-and-iteration.md @@ -0,0 +1,216 @@ +# Mid-beta triage and iteration + +Triage cadence. Iteration discipline (what to fix during the beta, what to defer). Communication with participants. + +Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. Mid-beta triage turns a static validation into an iterative one. + +--- + +## The triage cadence + +How the team reviews feedback during the beta. + +Weekly triage (1-2 hours). + +- Review feedback across all channels for the week. +- Categorize each piece: critical bug, friction issue, feature request, positive signal, edge case. +- Tag for action: fix this week, fix later in the beta, defer to post-GA, no action needed (one-off). +- Identify any critical issues warranting immediate response. + +Bi-weekly pattern review (1-2 hours). + +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening, which are not surfacing in volume? +- Surface decisions: what to address in the remaining beta period. + +As-needed escalation. + +- Critical issues (data loss, security, broken core flows) get same-day response regardless of cadence. +- The triage cadence does not delay critical-issue response. + +--- + +## Categorization + +Each piece of feedback gets categorized. + +Categories. + +- Critical bug. Crashes, data loss, broken core flows, security issues. Must be fixed before GA. +- Friction issue. Workflows that are confusing, slow, or sub-optimal but functional. Fix during beta where feasible; document otherwise. +- Feature request. Capability the participant wants that is outside beta scope. Capture for post-GA roadmap; do not add during beta. +- Positive signal. What is working well; what users find valuable. Surfaces what to preserve in GA and what to highlight in marketing. +- Edge case. Unusual configurations or contexts. Note for post-GA monitoring; address only if affecting many participants. +- One-off. Single observation without pattern. Note briefly; do not action. + +Why categorization matters. + +- Different categories have different action paths. Treating all feedback the same overwhelms triage. +- The categorization is the basis for the iteration decisions. + +--- + +## What to fix during the beta + +The team should fix some things during the beta and defer others. + +Fix during the beta. + +- Critical bugs that prevent participants from using the feature. The beta cannot validate the feature if participants cannot use it. +- Friction issues that are clearly addressable and significantly affect participant experience. Fixing them produces stronger end-of-beta signal. +- Issues that, if unfixed, will surface again post-GA at higher cost. +- Issues that participants are about to escalate publicly (if NDA-relevant) or that damage trust if left. + +Defer to post-GA. + +- Feature requests outside beta scope. +- Friction issues that affect a small subset of users in ways the team can document. +- Polish work that does not block the GA decision. +- Edge cases that do not affect mainline usage. + +The "what changes the GA decision" test. If fixing this issue affects whether the team can ship to GA, fix it. If it does not affect the GA decision, capture it for post-GA roadmap. + +--- + +## The iteration discipline + +Mid-beta iteration adds value but has constraints. + +The discipline. + +- Iterate on the feature, not the beta scope. Adding features to the beta mid-way confuses participants and dilutes signal. +- Fix critical and high-impact friction; capture rather than fix lower-impact issues. +- Communicate iteration to participants: when they see a fix or change, they know it came from their feedback. + +The "do not redesign mid-beta" rule. + +- Significant feature changes mid-beta produce two betas: the pre-change beta and the post-change beta. Neither is fully validated. +- If significant changes are needed, end the current beta, redesign, and start a new beta. Do not blend them. + +The "no creep" discipline. + +- Mid-beta is not the time to add capabilities outside the beta's original scope. +- Feature requests get captured for post-GA, not added to the beta. +- The beta's signal depends on consistency; scope creep undermines the validation. + +--- + +## Communication with participants + +Mid-beta communication keeps participants engaged. + +The cadence. + +- Weekly or bi-weekly updates to participants. +- Format: short email or in-product notification. +- Content: what was heard, what is being addressed, what is being deferred, what to expect next week. + +Strong update content. + +- "We heard your feedback about the configuration friction in step 3. We pushed a fix this week; please let us know if it is improved." +- "Several of you reported the dashboard load time is slow at scale. We are investigating; we expect a fix in the next 1-2 weeks." +- "We are seeing strong positive signal on the new export functionality. We will expand the format options in the next iteration." +- "Several of you requested integrations beyond the beta scope. We have captured these for post-GA roadmap." + +Why communication matters. + +- Participants who see their feedback acted on engage more substantively. +- Participants who feel ignored decay. +- Communication signals to participants that the team is listening. + +Common communication failures. + +- Silence between welcome and end of beta. Participants feel ignored. +- Generic updates that do not reference specific feedback. Feels performative. +- Over-communication. Daily updates are too much; participants tune out. +- Updates that promise more than the team will deliver. Erodes trust when promises are not kept. + +--- + +## The mid-beta health check + +A specific mid-beta milestone. + +The milestone. Roughly the midpoint of the beta. The team takes stock of where the beta is. + +The questions. + +- Is the feedback volume what was expected? If not, what is causing the difference? +- Are critical issues surfacing or has the team caught them all in the first part of the beta? +- Are behavioral patterns emerging? What do they suggest for the GA experience? +- Are participants engaged? Are some segments dropping off? +- Is the trajectory toward graduation criteria? Where are gaps? + +The output. + +- Adjustments to the beta operations: more triage, more communication, additional cohort recruitment if needed. +- Surfaced concerns about graduation: are the criteria reachable in the remaining beta time? +- Surfaced wins: what is going well that the team can build on for GA. + +--- + +## Mid-beta participant churn + +Some participants will drop off during the beta. + +Why participants churn. + +- The feature did not match their use case (they expected something different). +- They lost interest or got busy. +- They hit critical friction early and gave up. +- They felt ignored after providing feedback. + +The response. + +- Investigate churn. A subset of churn is normal; high churn is signal. +- For participants who churned because of friction: address the friction; possibly re-engage them. +- For participants who churned because of misfit: the cohort may have been miscalibrated; learn for future betas. +- For participants who felt ignored: tighten the communication discipline; thank them for prior feedback even if they have stopped engaging. + +Replacement recruitment. + +- For betas that need a specific cohort size for signal, replace churned participants if possible. +- Late-recruited replacements have less time in the beta; their feedback covers less of the beta period. +- Sometimes accepting churn and a smaller-than-planned cohort is the right call. + +--- + +## Triage anti-patterns + +Common ways triage decays. + +Triage skipping. No formal triage cadence; feedback accumulates without categorization or action. + +Triage as logging. Feedback gets categorized but never actioned. The categorization is documentation theater. + +Triage by loudest voice. Loudest participants get attention; quieter ones with similar feedback do not. Skews the synthesis. + +Triage by easiness. Easy fixes get prioritized regardless of impact. Important harder fixes get deferred indefinitely. + +Triage without communication. Internal triage happens but participants are not told. They feel ignored. + +Triage that absorbs feature requests. Participants request features outside scope; the team adds them mid-beta; scope creeps; signal dilutes. + +--- + +## Common iteration failures + +No iteration during the beta. Feedback is collected; the team waits for end of beta; opportunities to address issues during the beta are missed. + +Excessive iteration. Significant feature changes mid-beta. The beta becomes two different betas; neither validates the GA experience cleanly. + +Iteration without communication. The team fixes issues; participants do not know; engagement decays. + +Iteration on participant requests outside scope. Scope creep; the beta validates a different feature than the original. + +No closing the loop. Iterations happen; participants are not told their feedback drove the change; the connection between feedback and improvement is invisible. + +--- + +## Methodology-level choices that stay in the public skill + +The triage cadence. The categorization scheme. What to fix during the beta vs defer. The iteration discipline. The "do not redesign mid-beta" rule. Communication with participants. The mid-beta health check. Mid-beta churn handling. Common failures. + +## Implementation choices that stay internal + +Specific triage tools and trackers. Specific communication templates. Specific health-check formats. The team's own conventions for what counts as critical vs friction. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md b/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md new file mode 100644 index 0000000..b95bbcf --- /dev/null +++ b/dist/pi/.agents/skills/beta-program-management/references/participant-selection-criteria.md @@ -0,0 +1,212 @@ +# Participant selection criteria + +Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. + +Participant selection determines what the beta can produce. Calibrated cohorts produce decision-grade signal; misaligned cohorts produce noise that does not represent the GA user. Selection is upstream of every other beta decision. + +--- + +## Criteria that produce calibrated cohorts + +Match the post-launch user profile. If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. + +- Worked example: a feature for product managers at growth-stage SaaS companies. Beta participants should be PMs at growth-stage SaaS companies. Not designers, engineers, or PMs at very-early or very-late stage companies. +- The matching dimensions depend on the feature: role, company size, industry, usage volume, tenure, technical sophistication. + +Variety across relevant dimensions. Not all participants identical. + +- If the feature has segment-specific behavior, the cohort spans segments. +- If usage volume varies, the cohort includes high-volume and low-volume users. +- If geography matters (compliance, latency, language), the cohort spans relevant geographies. +- The variety should match the GA user diversity. + +Feedback willingness. Participants who agree to provide feedback through structured channels. + +- Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Recruiting should make the feedback expectation explicit. Participants who agree are more likely to engage; participants who decline are honest about their availability. + +Existing relationship strength. Customers with strong existing relationships are more likely to engage substantively. + +- Champion users, design partners, customers with active customer success relationships engage more. +- Customers in churn-risk are less likely to engage; their feedback may also be less representative (the relationship is already strained). + +Real usage of the broader product. Beta participants who use the broader product actively can give grounded feedback. Participants who signed up only for the beta and do not use the product otherwise often give surface-level feedback. + +--- + +## Criteria that produce miscalibrated cohorts + +Self-selection only. Open beta sign-ups skew toward enthusiasts and tinkerers. + +- Skews toward users who try every new feature; their feedback may not represent the broader target user. +- Misses users who would adopt at GA but who do not seek out beta sign-ups. + +Highest-paying customers only. Skews toward enterprise patterns. + +- Misses smaller-team and individual use cases. +- Enterprise feedback may emphasize features that smaller customers do not need. + +Internal employees only. Misses customer-context complexity. + +- Employees experience features differently than customers (familiarity, infrastructure, motivations). +- Internal-only validation produces "we tested" without "real customers tested." + +Whoever happens to be available. No selection criteria; the cohort is whoever the team can recruit quickly. + +- The cohort may not match the GA user; signal does not transfer to the GA decision. + +Champion users only. All beta participants are existing strong advocates. + +- Enthusiastic feedback may overstate readiness; missing the friction non-champion users would hit. + +--- + +## Variety calibration + +How to ensure the cohort spans the relevant dimensions. + +The dimension audit. + +- For the feature being beta'd, identify the dimensions that affect user experience. +- Common dimensions: role, company size, industry vertical, usage volume, geographic region, technical sophistication, tenure with the product. +- Decide which dimensions matter most for this feature. + +Cohort composition. + +- For each high-priority dimension, ensure the cohort includes representation across the values. +- If role matters: cohort includes participants in each relevant role. +- If usage volume matters: cohort includes high-volume, mid-volume, low-volume users. +- If industry varies meaningfully: cohort spans industries. + +Worked example. A feature for product managers using analytics tools. + +- Role dimension: cohort is all PMs (no other roles). +- Usage dimension: high-volume PMs (active daily users) + mid-volume PMs (weekly users). Skip low-volume because they likely will not use the feature meaningfully. +- Company size dimension: 10-50 employee, 50-200 employee, 200-500 employee. Skip enterprise (different feature priorities). +- Tenure dimension: PMs who have used the product 3+ months (so they have established workflows the new feature will integrate into). Skip new users. + +The cohort composition is intentional; each participant fits multiple criteria. + +--- + +## The cohort size question + +How many participants are enough. + +The calibration is signal-need-driven. + +- Bug discovery saturates fast: 20-30 participants surface most critical issues in 2-4 weeks. +- Behavioral signal saturates slower: 50-100 participants needed to see usage patterns clearly. +- Edge case discovery: 100-500+ participants needed; some edge cases never surface in beta. + +Common cohort sizes by beta type. + +- Design partner program: 3-10 participants. +- Closed alpha: 10-30 participants. +- Closed beta: 50-200 participants. +- Open beta: 500-5,000+ participants. +- RC validation: 1,000-10,000+ participants. + +The "more is better" anti-pattern. Teams default to large cohorts thinking volume produces signal. In practice, larger-than-needed cohorts produce volume without proportional signal increase, while making feedback synthesis harder. + +The "smaller produces calibrated" principle. A 50-person calibrated cohort often produces stronger signal than a 5,000-person uncalibrated one. Pick the smallest cohort that produces the signal needed. + +--- + +## The recruitment process + +How participants get selected. + +Sources. + +- Existing customer base: customer success identifies candidates matching the criteria. +- Sales pipeline: late-stage prospects who could become customers and provide feedback. +- Past beta participants: customers who participated in prior betas and proved engaged. +- Public sign-up forms (for open betas): with screening criteria applied to actual selection. +- Partner referrals: customers who recommend other customers fitting the profile. + +The screening. + +- Define the criteria explicitly (role, dimension values, feedback willingness). +- Apply the screening to candidates: who fits the criteria? +- For closed betas, decide which subset of fitting candidates to invite (cohort sizing). +- For open betas with screening, the sign-up form captures qualifying information; the team selects from sign-ups. + +The invitation. + +- Personalized invitations engage better than mass invitations. +- The invitation explains: what the beta is, what is expected, what participants get, how long it runs. +- Acceptance is opt-in; participants who decline are honest. + +The capacity. + +- Recruiting takes real time. A 50-participant closed beta may take 2-4 weeks of recruiting work depending on customer base and selection criteria. +- Plan recruiting time as part of the beta timeline. + +--- + +## The diversity-vs-control tradeoff + +Calibrated cohorts can over-control diversity in ways that miss valuable signal. + +The tradeoff. + +- Tightly-defined selection criteria produce a cohort that is uniform along the criteria. Reduces variety; may miss signal from users who differ. +- Loosely-defined criteria produce more diverse cohorts but make the cohort less calibrated to the GA user. + +The middle path. + +- Define the must-have criteria (role, key segment markers). +- Allow variety in the optional dimensions (industry, geography, tenure). +- The cohort is calibrated on what matters and varied on what does not. + +--- + +## When recruitment fails + +What to do when selection criteria cannot be met. + +Insufficient candidates fitting criteria. + +- Reconsider whether the criteria are too narrow. +- Extend recruiting time if feasible. +- Accept a smaller cohort that fully fits the criteria, rather than a larger cohort that includes mismatches. + +Candidates fitting criteria decline to participate. + +- Investigate why. Is the beta commitment too heavy? The compensation insufficient? The timing wrong? +- Adjust the offer; re-invite. +- If still insufficient, consider whether the beta plan is realistic given customer engagement willingness. + +Cohort skew despite intentional selection. + +- Some dimensions skew despite efforts (e.g., one industry over-represented because that industry is more receptive). +- Acknowledge the skew explicitly in synthesis. Patterns from the over-represented dimension may not generalize. + +--- + +## Common selection failures + +No criteria. Whoever happens to be available joins. Cohort does not represent GA user. + +Self-selection only. Open sign-ups skew the cohort. + +Only champions. Cohort over-represents enthusiasts; misses friction non-champions hit. + +Internal employees only. Misses customer-context complexity. + +Single-dimension calibration. Cohort uniform on one dimension (role) but mismatched on others (usage, segment). + +Recruiting too late. Beta starts before the cohort is calibrated; recruitment continues mid-beta; signal is muddled. + +Enterprise-only. Cohort over-represents large customers; misses smaller use cases. + +--- + +## Methodology-level choices that stay in the public skill + +The criteria for calibrated cohorts. The criteria for miscalibrated cohorts. Variety calibration with worked example. The cohort size question. The recruitment process. The diversity-vs-control tradeoff. When recruitment fails. Common selection failures. + +## Implementation choices that stay internal + +Specific recruiting tools and CRM integration. Specific screening surveys. Specific outreach templates. Specific tracking of cohort composition. The team's own conventions for selection criteria within different beta types. These vary by team and customer base. diff --git a/dist/pi/.agents/skills/brand-archetype-system/SKILL.md b/dist/pi/.agents/skills/brand-archetype-system/SKILL.md new file mode 100644 index 0000000..feb6c98 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/SKILL.md @@ -0,0 +1,143 @@ +--- +name: brand-archetype-system +description: "Apply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles." +category: brand +catalog_summary: "12 archetype defaults across 18 verticals: color, type, voice, imagery starters" +display_order: 5 +--- + +# Brand Archetype System + +Pre-composed aesthetic archetype defaults that jumpstart brand design work. Each archetype bundles color tendencies, type pairings, layout patterns, voice samples, and imagery direction for a recognizable aesthetic family. Stack-agnostic. Tool-agnostic. + +This is a starting-point library, not a methodology library. The agent applies archetype defaults to a specific brief; the archetypes themselves provide anchor points, not endpoints. + +--- + +## When to use + +- The user wants a starting point rather than designing from first principles +- The user references a brand or aesthetic family they want to design near +- Need to converge faster from many directions to one +- The user wants vertical-typical defaults (for example fintech consumer, B2B developer tools) +- The user wants to test what a brief would look like in a different archetype + +## When NOT to use + +- The user wants pure methodology guidance (use `brand-identity`) +- The user is in early ideation needing positioning territories (use `brand-ideation`) +- Defining voice for an existing brand (use `brand-voice`) +- Documenting a finished brand (use `brand-style-guide`) + +--- + +## How this composes with other skills + +This skill works upstream of `brand-identity` (provides starting defaults that brand-identity refines into a finished system) and parallel to `creative-direction` (archetypes can be located by position on the 4 creative-direction axes). + +Typical flow when this skill is invoked: +1. User provides a brief or references a target archetype +2. Agent picks the most relevant core archetype, or composes from 2 adjacent archetypes +3. Agent adapts the archetype's defaults to the brief (color tokens shift, type swaps to vertical-appropriate fonts, voice samples rewrite for the brand) +4. Agent flags adaptation choices made + +Direct verbatim copying of an archetype's default palette into a new brand is a failure mode. Archetypes constrain the design space; the brief specifies the point within that space. + +--- + +## The framework: 12 core archetypes plus 18 vertical applications + +Two layers of content in `references/`: + +### Core archetypes (12 files) + +Located in `references/core-archetypes/`. Each is an aesthetic family with: +- Aesthetic summary +- Position on the 4 `creative-direction` axes +- Color palette starter (4 to 6 hex values with token names and rationale) +- Type pairing starter (Google Fonts pairing with size scale) +- Layout and composition patterns +- Voice samples (5 to 10 representative lines) +- Component pattern descriptions (heroes, buttons, cards, tables) +- Imagery direction +- When to pick and when to avoid +- Adaptation guidance +- Exemplar brands with attribution language + +### Vertical applications (18 files) + +Located in `references/by-vertical/`. Each maps named brands to core archetypes in that vertical with: +- Vertical summary +- Common archetypes +- Brand-to-archetype mapping (5 to 10 brands per vertical) +- Vertical-specific adaptation notes +- Common archetype evolution patterns as brands mature + +### Two overview files + +- `00-archetype-system-overview.md`: how the system works, the taxonomy +- `01-how-to-apply-an-archetype.md`: the adaptation discipline, the failure modes + +--- + +## The 12 core archetypes + +\| # \| Archetype \| Single-line summary \| +\|---\|---\|---\| +\| 01 \| Editorial Restrained \| Low-saturation, type-led, generous whitespace, considered \| +\| 02 \| Technical Precise \| Monospace and grid prominent, data-dense, system-feeling \| +\| 03 \| Warm Conversational \| Human imagery, mid-saturation, friendly type, approachable \| +\| 04 \| Bold Confident \| High-contrast, large display type, saturated, direct \| +\| 05 \| Playful Energetic \| Bright colors, illustration-led, dynamic, character-driven \| +\| 06 \| Luxe Considered \| Serif-led, generous spacing, restrained palette, premium \| +\| 07 \| Clinical Trustworthy \| Cool palette, sans-serif, clean medical or financial register \| +\| 08 \| Rugged Utilitarian \| Earth tones, workwear influence, no-nonsense type \| +\| 09 \| Retro Nostalgic \| Period-specific palette and type, intentional vintage reference \| +\| 10 \| Minimal Essentialist \| Black, white, single accent, sans-serif only, sparse \| +\| 11 \| Vibrant Saturated \| High-saturation across full palette, color as character \| +\| 12 \| Documentary Honest \| Photography-led, real people, low-touched imagery \| + +## The 18 vertical applications + +- B2B SaaS: Developer Tools, Business Productivity, Marketing and Sales, Data and Analytics +- Fintech: Consumer, Enterprise +- DTC: Fashion, Beauty, Home and Lifestyle, Food and Beverage +- Consumer Health and Wellness +- Hospitality and Travel +- Media and Publishing +- EdTech +- Gaming and Entertainment +- Marketplace +- Crypto and Web3 +- Real Estate and Proptech + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands. "Editorial Restrained" not "Stripe-like." Brands are referenced as exemplars in description text using attribution language: "exemplified by [brands]", "common among [brands]", "characteristic of [brands]". + +This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## The four creative-direction axes (reference) + +Each archetype positions on the 4 axes defined in the `creative-direction` skill. Brief summary for cross-reference: + +- Tone register: Professional, Conversational, Playful +- Aesthetic register: Restrained, Considered, Expressive, Maximal +- Audience relationship: Authority, Peer, Companion, Performer +- Sensory ambition: Functional, Considered, Immersive, Theatrical + +Each core archetype file specifies its position on each axis. + +--- + +## Reference files + +- [`references/00-archetype-system-overview.md`](references/00-archetype-system-overview.md) - How the two-layer system fits together, entry patterns, when archetypes compose, and the recurring failure modes. +- [`references/01-how-to-apply-an-archetype.md`](references/01-how-to-apply-an-archetype.md) - The 5-step adaptation process: locate the design space, map the brief to adjustable dimensions, adapt color, adapt type, write voice samples. Includes the cross-archetype coherence check. + +The 12 core archetype files live in the `core-archetypes/` subdirectory under references, numbered 01 (Editorial Restrained) through 12 (Documentary Honest). The 18 vertical application files live in the `by-vertical/` subdirectory under references, numbered 01 (B2B SaaS Developer Tools) through 18 (Real Estate and Proptech). Load the relevant core archetype file plus the relevant vertical file together for any brief that names both an aesthetic family and an industry. + diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md b/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md new file mode 100644 index 0000000..b47a529 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/00-archetype-system-overview.md @@ -0,0 +1,40 @@ +# Archetype system overview + +This document explains the taxonomy and how the layers fit together. Read this first when working with the archetype system for the first time. + +## The two layers + +Core archetypes (12 files) are the aesthetic families themselves. They span verticals; an archetype like Editorial Restrained appears in B2B SaaS, in media publishing, in DTC fashion. The core archetype files describe the family in pure form: what makes it recognizable, the color tendencies, the type pairings, the voice character. + +Vertical applications (18 files) describe how the archetypes manifest in specific industries with named brands. They are discovery surfaces: a user working on a fintech brand should be able to find their vertical, see which archetypes are common, see specific brand-to-archetype mappings, and decide which core archetype to start from. + +## How the agent should use the system + +Two entry patterns: + +Entry by archetype (user references an aesthetic family): "I want something Editorial Restrained for my analytics product." Agent loads the Editorial Restrained core archetype file, plus the B2B SaaS Data and Analytics vertical file for context. Composes defaults adapted to the brief. + +Entry by vertical (user references their industry): "I'm designing a consumer fintech app, what archetypes work here?" Agent loads the Fintech Consumer vertical file first, sees the brand-to-archetype mappings, picks the most relevant core archetype, then loads that for full defaults. + +## What this system is and is not + +It is: a library of pre-composed defaults that accelerate brand work by providing known-good starting points with documented rationale. + +It is not: a substitute for design judgment. The defaults are anchor points; the brief specifies where to land within the archetype's design space. + +It is not: a comprehensive theory of brand aesthetics. The 12 archetypes capture the most recognizable contemporary Western brand aesthetics. They are not exhaustive. Regional, cultural, and historical archetypes are deferred to future expansions of the catalog. + +## When archetypes compose + +Two archetypes can blend. Linear is Editorial Restrained with Technical Precise undertones. Stripe is Technical Precise with Editorial Restrained surfaces. Glossier is Vibrant Saturated with Minimal Essentialist composition. + +When the brief calls for blending, the agent picks two core archetypes and notes which contributes which dimension (for example "Editorial Restrained for type and whitespace, Technical Precise for color and density"). + +## The failure modes + +1. Verbatim copying: pulling the exact starter palette into a new brand without adaptation. Produces generic output. +2. Archetype mismatch with audience: picking an archetype because the user likes its exemplars rather than because it fits the audience. +3. Cross-archetype tokens: pulling a color from one archetype and type from another without considering coherence. Often produces incoherent output. +4. Stale exemplars: assuming a brand still exemplifies an archetype after a redesign. The archetype is durable; the brand is not. + +Each core archetype file's "Adaptation guidance" section addresses these. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md b/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md new file mode 100644 index 0000000..02c6607 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md @@ -0,0 +1,69 @@ +# How to apply an archetype + +This document is the operating manual. Once an archetype is picked, follow this process to adapt it to the specific brief. + +## The 5-step adaptation process + +### Step 1: Locate the archetype's design space + +Read the core archetype file. Understand: +- Position on the 4 creative-direction axes +- The non-negotiable structural choices (for example "single accent" for Editorial Restrained, "monospace prominent" for Technical Precise) +- The adjustable dimensions (specific hue of the accent, specific serif, specific density) + +The structural choices are what make the archetype recognizable. The adjustable dimensions are where the brief lands. + +### Step 2: Map the brief to adjustable dimensions + +For each adjustable dimension, ask: what does the brief specify or imply? + +- Audience character: Younger audience usually wants warmer accent; older wants cooler. Technical audience tolerates more density; consumer audience needs more whitespace. +- Category context: Crowded categories need stronger contrast; quiet categories can be more restrained. +- Emotional direction: Trust-needing brands lean cooler; warmth-needing brands lean warmer. +- Competitive position: If the closest competitor is in the same archetype, shift one adjustable dimension hard to differentiate. + +### Step 3: Adapt the color palette + +The starter palette is a relationship between values, not absolute hex codes. Preserve the relationship; shift the values. + +Example with Editorial Restrained: +- Default: ink #0F1B2D (navy), accent #5B8B85 (muted teal) +- Adaptation for a finance brief: ink #1A1F2E (deeper navy), accent #4A5D6E (slate blue), reads more institutional +- Adaptation for a consumer wellness brief: ink #2A2520 (warm dark brown), accent #7A9B7C (sage green), reads more grounded and warm + +Preserve: low saturation, single accent, paper-not-white background, ink-not-black text. Shift: specific hues to match emotional direction. + +### Step 4: Adapt the type pairing + +The starter pairing is a relationship between display and body, not specific fonts. Preserve the relationship; shift the fonts. + +Example with Editorial Restrained: +- Default: IBM Plex Serif (display) plus Inter (body) +- Adaptation for luxe-leaning brief: Tiempos Display (display) plus Inter (body) preserves the pairing, shifts the serif character +- Adaptation for technical-leaning brief: IBM Plex Serif (display) plus IBM Plex Sans (body) keeps within one family, reads more system-like + +Preserve: serif display plus sans body, modular scale, single weight per role. Shift: specific font choices to match register. + +### Step 5: Write voice samples for the specific brand + +The voice samples in the core archetype show character; they are not copy to lift directly. Write 5 to 10 new voice samples for the specific brand using the archetype's cadence and register. + +## The cross-archetype check + +Before finalizing, verify the output reads as coherent within the archetype: + +- Color: matches the archetype's saturation and contrast character? +- Type: matches the archetype's display and body relationship? +- Voice: matches the archetype's cadence and register? +- Layout: matches the archetype's density and whitespace tendency? + +If two of the four diverge from the archetype, either pick a different archetype or accept that the brand is a blend (and document which archetype contributes which dimension). + +## When to abandon an archetype mid-flow + +The archetype is wrong if: +- Three or more dimensions resist adaptation to the brief +- The audience signals reject the archetype's defaults (for example picking Editorial Restrained for a children's app) +- Direct competitors all live in the same archetype and your brief needs differentiation + +When abandoning, return to the vertical file for that industry and pick a different starting archetype. Do not try to retrofit an archetype that does not fit. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md new file mode 100644 index 0000000..1241203 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md @@ -0,0 +1,44 @@ +# B2B SaaS: Developer Tools + +## Vertical summary + +Brands serving developers building software. Audience values: technical precision, documentation depth, time-to-first-API-call. Brands compete on developer experience, primitive quality, observability, and composition. The category is mature with established archetypes. + +## Common archetypes in this vertical + +The dominant archetype is Technical Precise (Stripe docs, Sentry, Datadog). Editorial Restrained is the rising adjacent archetype (Linear, Vercel, Resend). Bold Confident appears at the consumer-edge (Loom, formerly Heroku). Other archetypes are rare in this space; warmth and play do not read as credibility to developers building production systems. + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Stripe \| Technical Precise with Editorial undertones \| Best-in-category documentation aesthetic; navy and violet accents; serif display creeping into marketing \| +\| Linear \| Editorial Restrained \| Single-accent restraint; brutal type hierarchy; muted palette \| +\| Vercel \| Editorial Restrained leaning Technical Precise \| Black and white; Geist font system; minimal accents \| +\| Sentry \| Technical Precise \| Dark mode dominant; purple accent; data-dense \| +\| Datadog \| Technical Precise \| Cool palette; UI-led marketing; dense \| +\| Resend \| Editorial Restrained \| New entrant; serif display; warm paper background \| +\| Cloudflare \| Bold Confident \| Orange brand color; energetic; consumer-tilted \| +\| GitHub \| Editorial Restrained adjacent \| Octocat character softens the precision \| +\| Supabase \| Bold Confident leaning Technical Precise \| Green primary; recently more restrained \| +\| Cursor \| Technical Precise \| Dark-mode-first; tool-focused; understated \| + +## Vertical-specific adaptation notes + +- Documentation surfaces are first-class: developer brands need documentation as part of the brand surface, not an afterthought. The type system must scale to long-form technical reading. +- Code samples are brand assets: how code renders (syntax highlighting palette, line numbers, copy buttons) is brand expression. +- Dark mode is required, not optional. Most developers spend their day in dark interfaces. +- Performance signals as brand signals: page load time, animation frame rate, perceived speed are part of how developers judge developer brands. +- Density tolerance: developers tolerate (and often prefer) higher information density than other B2B audiences. + +## Common archetype evolution + +Developer brands frequently start Technical Precise and add Editorial Restrained as they mature. Stripe's evolution from pure technical to editorial-influenced marketing is the canonical example. Conversely, brands that start Bold Confident (Cloudflare, Supabase) sometimes retreat toward restraint as they target enterprise. + +The early-stage developer brand archetype shift is almost always: drop the consumer-tinted color, add a serif, lean into restraint. The mature-stage shift is sometimes: re-introduce a careful illustration system to soften pure restraint (GitHub's Octocat-era is the canonical case). + +## Vertical anti-patterns + +- Playful Energetic in developer tools: reads as unserious. Developers building production systems do not want a mascot taking up screen real estate in their dashboard. +- Luxe Considered in developer tools: reads as out-of-touch. Developer tools differentiate on substance, not premium feel. +- Vibrant Saturated in developer tools: rare and risky; works only when the brand is consumer-tilted (Cloudflare manages it with discipline). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md new file mode 100644 index 0000000..76f81c5 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md @@ -0,0 +1,43 @@ +# B2B SaaS: Business Productivity + +## Vertical summary + +Brands serving teams getting work done across documents, projects, communications, and design. Audience is prosumer-tilted: knowledge workers who self-serve, evaluate based on demos and free trials, and bring tools into their organizations from the bottom up. Brands compete on approachability, integration depth, and brand likeability alongside functional differentiation. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Slack, Mailchimp, Figma in marketing) and Bold Confident (Notion, Linear in launches). Playful Energetic appears at the edges (Asana classic era). Editorial Restrained is rising (Coda, Notion's recent surfaces). The category rewards personality more than developer tools but less than consumer apps. + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Notion \| Bold Confident leaning Warm Conversational \| Black on white plus illustration character; emoji-rich; oversized type \| +\| Figma \| Warm Conversational \| Multi-hue creative palette; illustration-led; community-driven \| +\| Loom \| Bold Confident \| Recent rebrand bold-purple-and-black; high contrast \| +\| Slack \| Warm Conversational \| Multi-hue saturated brand colors; hands-and-objects illustration era \| +\| Airtable \| Warm Conversational \| Multi-color brand; spreadsheet-meets-database approachable \| +\| Coda \| Editorial Restrained \| Type-led; restrained palette; document-first feeling \| +\| Asana \| Playful Energetic moving to Warm Conversational \| Mascot-era to recent considered warmth \| +\| ClickUp \| Vibrant Saturated \| Multi-hue palette; expressive; consumer-tilted \| +\| Monday.com \| Vibrant Saturated \| Saturated multi-hue; bold UI; high energy \| +\| Dropbox \| Vibrant Saturated leaning Editorial Restrained \| 2017 rebrand era is the canonical example of the shift \| + +## Vertical-specific adaptation notes + +- Illustration budget matters: brands without illustration capacity should pick Editorial Restrained or Bold Confident rather than Warm Conversational or Playful Energetic. Bad illustration kills the warm archetypes immediately. +- Onboarding surface as brand surface: in productivity, onboarding flows are heavily branded and high-impact. The archetype must extend cleanly into product chrome. +- Self-serve discovery: pricing pages, signup flows, and product tours carry brand weight. Restraint in these surfaces signals trust; warmth signals approachability. +- Bottom-up adoption pattern: brands are evaluated by individual users before procurement. The archetype should not require enterprise sign-off to feel right. + +## Common archetype evolution + +Productivity brands often start Warm Conversational with heavy illustration and pull back toward Editorial Restrained or Bold Confident as they scale into enterprise. Slack's evolution shows this: early Slack was warm-illustration-heavy; current Slack reads more restrained while retaining color personality. Notion's evolution is similar. + +The mature-stage shift is frequently: keep the personality in voice and color, remove decorative illustration from primary surfaces, lean into typographic hierarchy. + +## Vertical anti-patterns + +- Pure Technical Precise in productivity: reads as developer tool rather than productivity tool. Audience expects warmth. +- Luxe Considered in productivity: reads as enterprise theatre. Self-serve audiences read restraint as remote. +- Rugged Utilitarian: completely incompatible with the audience. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md new file mode 100644 index 0000000..ae51ddf --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md @@ -0,0 +1,43 @@ +# B2B SaaS: Marketing and Sales + +## Vertical summary + +Brands serving marketers, sales teams, growth professionals, and revenue operations. Audience is mixed prosumer and enterprise: bottom-up adoption among individual marketers, top-down evaluation by RevOps and procurement. Brands compete on platform breadth, integration ecosystems, attribution claims, and trust signals to budget-holders. + +## Common archetypes in this vertical + +The dominant archetypes split by audience tier. Warm Conversational dominates SMB and prosumer (Mailchimp, Intercom, ConvertKit). Bold Confident appears at the growth-energy edge (Drift, Mutiny). Clinical Trustworthy dominates enterprise (Salesforce, Marketo). Editorial Restrained is the rising adjacent archetype (Webflow's marketing surfaces). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Mailchimp \| Warm Conversational \| Multi-hue brand; mascot-era illustration; SMB-focused \| +\| Webflow \| Editorial Restrained \| Serif-led marketing; typographic hierarchy; designer audience \| +\| HubSpot \| Warm Conversational \| Orange and white; rounded illustration; inbound voice \| +\| Intercom \| Warm Conversational \| Friendly conversational brand; chat-first UX \| +\| Drift \| Bold Confident \| Bold colors; conversational-AI positioning \| +\| Marketo \| Clinical Trustworthy \| Cool palette; enterprise-trust signals; B2B authority \| +\| Salesforce \| Clinical Trustworthy at enterprise edge \| Cloud iconography; trust-blue; enterprise authority \| +\| ConvertKit (Kit) \| Warm Conversational \| Creator-focused warmth; muted palette \| +\| Mutiny \| Bold Confident \| Saturated personalization-as-brand \| +\| Apollo \| Editorial Restrained leaning Bold Confident \| Recent restrained typography redesign \| + +## Vertical-specific adaptation notes + +- Enterprise versus prosumer split is wide: prosumer leans warm and friendly; enterprise leans clinical and authoritative. The brand should pick a lane and commit; trying to do both produces neither. +- Trust signals matter: customer logo strips, peer-reviewed comparison tables, security certifications carry brand weight in this vertical. +- Demo and trial flows: a high portion of brand perception forms during the demo or free trial. The archetype must extend cleanly into in-product surfaces. +- AI-positioning surge: many brands in this category have recent AI-features positioning that affects archetype choice; AI features tend to pull brands toward Technical Precise or Bold Confident. + +## Common archetype evolution + +Marketing and sales brands frequently start Warm Conversational at SMB and evolve toward Clinical Trustworthy or Editorial Restrained as they target upmarket. Mailchimp's evolution from playful-illustration to more restrained type-led marketing reflects this. HubSpot's evolution from friendly orange to a more institutional brand presence is another example. + +The mature-stage shift is frequently: drop heavy illustration, narrow the palette, lean into customer evidence rather than personality. + +## Vertical anti-patterns + +- Playful Energetic in enterprise marketing tools: reads as unserious to budget-holders. +- Luxe Considered in mass-market marketing tools: reads as out-of-touch with the SMB user base. +- Pure Technical Precise: works for some categories (analytics, attribution) but feels wrong for relationship-building tools (CRM, email). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md new file mode 100644 index 0000000..a1cff84 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md @@ -0,0 +1,43 @@ +# B2B SaaS: Data and Analytics + +## Vertical summary + +Brands serving data teams, analysts, product managers, and engineers working with data infrastructure, business intelligence, and product analytics. Audience values: query power, schema clarity, time-to-first-insight, and trust in numbers. The category overlaps with developer tools at the infrastructure end and with marketing analytics at the application end. + +## Common archetypes in this vertical + +The dominant archetypes are Technical Precise (Mixpanel, Amplitude, Snowflake) and Editorial Restrained (dbt, Hex, Threshold the fictional reference build). The category rewards precision; Clinical Trustworthy appears at the enterprise BI edge (Tableau historically); Bold Confident appears at the new-entrant edge (Hex at launch). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Mixpanel \| Technical Precise \| Cool palette; product analytics rigor; chart-as-hero \| +\| Amplitude \| Technical Precise \| Blue and white; data-density tolerant; PLG positioning \| +\| Looker \| Technical Precise \| Enterprise BI restraint; Google acquired \| +\| Snowflake \| Editorial Restrained adjacent \| Restrained type; cloud-native confidence \| +\| Tableau \| Clinical Trustworthy historically, Editorial Restrained recently \| Recent rebrand pulled toward typographic restraint \| +\| dbt \| Editorial Restrained \| Type-led; community-driven; restraint as differentiator \| +\| Hex \| Bold Confident \| Saturated brand; modern data workspace positioning \| +\| Census \| Editorial Restrained \| Recent shift toward type-led restraint \| +\| Hightouch \| Bold Confident \| Strong brand colors; reverse ETL positioning \| +\| Threshold (fictional reference) \| Editorial Restrained \| Catalog reference build; PLG onboarding analytics \| + +## Vertical-specific adaptation notes + +- Chart and table rendering as brand: how a chart looks, how table cells align, how numbers format are core brand expression. The archetype must extend cleanly into data visualization conventions. +- Documentation depth: data tools live and die on documentation. Long-form technical reading is core to the brand surface, not auxiliary. +- Trust through precision: vague claims undermine the archetype. Specific numbers, specific schemas, specific examples carry the brand. +- SQL and code as content: query examples, schema definitions, and code samples are first-class brand assets. + +## Common archetype evolution + +Data brands frequently start Technical Precise and add Editorial Restrained as they mature into prosumer territory. Snowflake's evolution from pure technical to restrained editorial is the canonical case. Conversely, brands that start Bold Confident (Hex, Hightouch) often pull back toward restraint as they target enterprise. + +The early-stage shift is usually: keep the technical precision in product surfaces, add editorial restraint to marketing. + +## Vertical anti-patterns + +- Playful Energetic in data tools: reads as untrustworthy with numbers. Audiences expecting analytical rigor reject playful brand expression. +- Luxe Considered in data tools: reads as marketing rather than substance. +- Rugged Utilitarian: completely incompatible with the audience and the category. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md new file mode 100644 index 0000000..1050614 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md @@ -0,0 +1,43 @@ +# Fintech: Consumer + +## Vertical summary + +Brands serving individual consumers across banking, investing, payments, lending, and budgeting. Audience splits sharply by age and risk tolerance: younger audiences tolerate (and prefer) energy and playfulness; older audiences require clinical trust signals. Brands compete on trust, fee transparency, and emotional positioning around money. + +## Common archetypes in this vertical + +The dominant archetypes are Bold Confident (Cash App, Robinhood for younger audiences) and Clinical Trustworthy (Chime, SoFi, Wealthfront for trust-needing positions). Warm Conversational appears at the savings-and-budgeting edge (Acorns). Playful Energetic appears at the consumer-payments edge (Venmo historically). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Cash App \| Bold Confident \| Black plus saturated green; oversized type; consumer-payments register \| +\| Robinhood \| Bold Confident \| Saturated green plus black; recently more institutional \| +\| Chime \| Clinical Trustworthy \| Trust-blue palette; calm voice; banking-not-bank positioning \| +\| SoFi \| Clinical Trustworthy \| Multi-product trust signals; restrained palette \| +\| Venmo \| Playful Energetic historically \| Multi-color personality; payments-as-social positioning \| +\| Wealthfront \| Editorial Restrained \| Type-led; institutional confidence; long-term-investing register \| +\| Acorns \| Warm Conversational \| Warm palette; round-up framing; approachable savings \| +\| Mint \| Clinical Trustworthy historically \| Cool palette; budgeting-trust positioning \| +\| Current \| Bold Confident \| Saturated brand; younger-audience positioning \| +\| Step \| Playful Energetic leaning Bold Confident \| Teen-banking; character-driven \| + +## Vertical-specific adaptation notes + +- Trust versus energy is the central design tension: every consumer fintech brand sits somewhere on this spectrum. Picking the archetype is picking the position. +- Regulatory and compliance copy affects voice. The brand's voice must accommodate disclosures, terms, and risk language without breaking the archetype. +- Money is emotional: the archetype carries emotional positioning about money (excitement, security, freedom, control). The visual must match the emotional position. +- Mobile-first: most consumer fintech brand exposure is on phone screens. The archetype must extend cleanly to small screens with reduced ornamentation. + +## Common archetype evolution + +Consumer fintech brands frequently shift archetype as they target older audiences. Robinhood's evolution from pure bold-energy to more institutional restraint as it added retirement and IRA products is the canonical case. Cash App's evolution into financial-products-beyond-payments shows similar restraint additions. + +The mature-stage shift is usually: keep the brand color, add restraint to type, dial back the swagger in voice, add trust signals. + +## Vertical anti-patterns + +- Luxe Considered in mass-market fintech: reads as out-of-touch. +- Documentary Honest in payments and investing: photography of real people does not communicate the right thing in this category; the value is the product, not the experience. +- Rugged Utilitarian: completely incompatible. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md new file mode 100644 index 0000000..eb6935b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md @@ -0,0 +1,43 @@ +# Fintech: Enterprise + +## Vertical summary + +Brands serving businesses with payments, treasury, banking, spend management, and financial infrastructure. Audience splits between developer-touching (payment infrastructure) and finance-touching (corporate cards, spend management, treasury). Brands compete on integration depth, control surfaces, and operational trust. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Editorial Restrained with Technical Precise undertones dominates developer-touching fintech (Stripe, Modern Treasury). Bold Confident dominates finance-touching B2B (Ramp, Brex, recent Mercury). Technical Precise dominates pure infrastructure (Plaid). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Stripe \| Editorial Restrained with Technical Precise undertones \| Best-in-category fintech brand; serif marketing, technical product \| +\| Plaid \| Technical Precise \| Developer-first; cool palette; integration-as-product \| +\| Mercury \| Bold Confident, recently shifting to Editorial Restrained \| Recent rebrand pulled back toward restraint \| +\| Brex \| Bold Confident \| Bold colors; corporate-card energy; recent restraint additions \| +\| Ramp \| Bold Confident \| Saturated palette; spend-management-with-energy positioning \| +\| Modern Treasury \| Editorial Restrained \| Type-led; payments-infrastructure restraint \| +\| Adyen \| Editorial Restrained leaning Clinical Trustworthy \| Enterprise-payments authority \| +\| Square (now Block) \| Bold Confident historically \| Black plus accent; SMB-payments register \| +\| Bill.com \| Clinical Trustworthy \| Cool palette; finance-team-tool positioning \| +\| Carta \| Editorial Restrained \| Recent rebrand pulled toward editorial type-led \| + +## Vertical-specific adaptation notes + +- Developer-touching versus finance-touching split: payment infrastructure (Stripe, Plaid) is evaluated by developers; spend management (Ramp, Brex) is evaluated by finance. The archetype must match the evaluator. +- Compliance and trust copy is heavier than in consumer fintech: SOC 2, PCI-DSS, certifications must appear above the fold and be visually weighty. +- Documentation depth: developer-facing fintech needs documentation as primary surface; finance-facing needs reporting and dashboards as primary surface. +- Multi-product expansion: many enterprise fintech brands expand from a single product (payments, cards, banking) into a platform. The archetype must extend to multiple product lines coherently. + +## Common archetype evolution + +Enterprise fintech brands frequently start Bold Confident as challengers and shift toward Editorial Restrained as they target larger customers. Mercury's recent rebrand from bold-pastel to restrained-serif is the canonical example. Carta's recent restraint shift follows the same pattern. + +The mature-stage shift is usually: dial back the saturated color, lean into typographic restraint, add institutional confidence to voice. + +## Vertical anti-patterns + +- Playful Energetic in enterprise fintech: reads as financially unserious. Finance buyers reject playful brand expression even in modern challenger brands. +- Vibrant Saturated: tolerated only when the brand is a category challenger; mature enterprise positions require restraint. +- Documentary Honest: incompatible with the category; product surfaces and dashboards carry the brand, not real photography. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md new file mode 100644 index 0000000..b98fed8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md @@ -0,0 +1,43 @@ +# DTC: Fashion + +## Vertical summary + +Brands selling apparel directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability or ethical positioning where relevant. The category is dominated by photography quality; brand archetypes ride on photo direction more than on type or color. Price point splits the vertical: above 80 dollars per piece favors Luxe Considered, mass-market favors Minimal Essentialist or Warm Conversational. + +## Common archetypes in this vertical + +The dominant archetypes are Luxe Considered (Aritzia, Reformation, COS at the premium end) and Minimal Essentialist (Everlane, Allbirds at launch, Cuyana). Bold Confident appears at streetwear and challenger brands (Stüssy digital, Kith). Documentary Honest appears in heritage and outdoor-adjacent fashion (Patagonia, Filson). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Aritzia \| Luxe Considered \| Editorial photography; serif type; mid-premium positioning \| +\| Reformation \| Luxe Considered with sustainability voice \| Cream and earthy palette; sustainability framing \| +\| Everlane \| Minimal Essentialist \| Black plus white; transparency narrative \| +\| Allbirds (launch era) \| Minimal Essentialist \| Warm white plus single accent; sustainable-essentials \| +\| Cuyana \| Luxe Considered \| Cream and warm-neutral; fewer-better-things positioning \| +\| Stüssy \| Bold Confident at streetwear edge \| High-contrast; oversized lockup; streetwear authority \| +\| COS \| Minimal Essentialist \| Black on white; architectural typography; H and M premium tier \| +\| Filson \| Documentary Honest with Rugged Utilitarian \| Heritage workwear; earned authenticity \| +\| Outdoor Voices (historical) \| Vibrant Saturated leaning Warm Conversational \| Multi-hue palette; recreation-not-sport positioning \| +\| Universal Standard \| Editorial Restrained \| Size-inclusive premium; serif-led type-first \| + +## Vertical-specific adaptation notes + +- Photography quality is the gating factor: every archetype in this vertical depends on excellent product and lifestyle photography. Brands without photography budget should pick Minimal Essentialist (which can survive on product-on-white) over the other archetypes. +- Model casting is brand expression: who appears in the photography signals the audience the brand is speaking to. Casting decisions are archetype-relevant. +- Sustainability framing is increasingly default in this vertical: the archetype may need to accommodate sustainability narrative without leaning preachy. +- Seasonal updates affect archetype continuity: brands must be able to refresh imagery seasonally without breaking the brand system. + +## Common archetype evolution + +Fashion brands frequently start Minimal Essentialist at launch (low-cost archetype with high signal) and migrate toward Luxe Considered as they raise prices and add product lines. Allbirds' evolution shows this: launch era was pure Minimal Essentialist; recent surfaces lean warmer and more storied (Warm Conversational with Documentary Honest notes). + +Conversely, brands that start Luxe Considered sometimes pull back toward Minimal Essentialist when they target younger or more digitally-native audiences. + +## Vertical anti-patterns + +- Technical Precise in fashion: completely incompatible. +- Playful Energetic in mass-market fashion: reads as costume; works only at children's-or-novelty edge. +- Bold Confident in heritage fashion: undermines the heritage positioning. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md new file mode 100644 index 0000000..e007077 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md @@ -0,0 +1,43 @@ +# DTC: Beauty + +## Vertical summary + +Brands selling skincare, cosmetics, hair care, and personal care directly to consumers. Audience values: ingredient evidence (in clinical positions), aesthetic alignment (in aspirational positions), and category authority (in challenger positions). The vertical splits sharply across three lanes that map cleanly onto archetypes. + +## Common archetypes in this vertical + +Three clear lanes: Vibrant Saturated for personality-driven challenger brands (Glossier, Drunk Elephant); Luxe Considered for premium and aspirational (Aesop, Augustinus Bader); Minimal Essentialist for clinical-and-rational positioning (The Ordinary). Documentary Honest appears at the editorial-skincare edge (Topicals). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Glossier \| Vibrant Saturated with restraint \| Pink-and-white world; soft typography; community-as-brand \| +\| Drunk Elephant \| Vibrant Saturated \| Multi-hue saturated palette; clinical ingredient framing \| +\| Aesop \| Luxe Considered \| Apothecary aesthetic; restrained palette; editorial confidence \| +\| The Ordinary \| Minimal Essentialist \| Black on white; ingredient-as-name; clinical transparency \| +\| Fenty Beauty \| Bold Confident \| Saturated brand; inclusivity-as-positioning \| +\| Topicals \| Vibrant Saturated with editorial photography \| Saturated palette plus documentary photo direction \| +\| Sunday Riley \| Luxe Considered \| Premium clinical; warm palette; ingredient narrative \| +\| Augustinus Bader \| Luxe Considered \| Pure luxury skincare; serif-led; minimal product range \| +\| Tatcha \| Luxe Considered \| Japanese-influenced premium; cream palette; heritage narrative \| +\| Bubble \| Vibrant Saturated leaning Playful Energetic \| Gen-Z skincare; bright multi-hue; accessible price point \| + +## Vertical-specific adaptation notes + +- Three-lane decision is the central archetype choice: Vibrant Saturated (personality), Luxe Considered (premium), Minimal Essentialist (clinical). Commit to one lane; trying to do two reads as confused. +- Ingredient communication: how ingredients are presented carries archetype weight. Clinical lane presents ingredients as data; premium lane treats ingredients as story; personality lane treats ingredients as character. +- Packaging design is integrated with the digital brand: the bottle, jar, or tube on the page is brand expression. Packaging design must match the archetype. +- Photography conventions: clinical lane uses product-on-white; premium lane uses editorial styled photography; personality lane uses saturated lifestyle and product-on-color. + +## Common archetype evolution + +Beauty brands frequently stay within their original archetype but refine over time. Glossier has stayed Vibrant Saturated with increasing restraint as the brand has matured. The Ordinary has stayed Minimal Essentialist with subtle additions for new product lines. Aesop has stayed Luxe Considered with consistent discipline since launch. + +Brands that try to switch archetypes (for example a clinical brand adding personality) usually undermine their original positioning. + +## Vertical anti-patterns + +- Technical Precise in beauty: incompatible; reads as cold and clinical without the trust signals to justify it. +- Rugged Utilitarian: completely incompatible. +- Mixed clinical-and-personality: a brand that tries to be both The Ordinary and Glossier ends up neither. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md new file mode 100644 index 0000000..5d47154 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md @@ -0,0 +1,43 @@ +# DTC: Home and Lifestyle + +## Vertical summary + +Brands selling bedding, furniture, kitchenware, home accessories, and lifestyle goods directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability framing where relevant. The vertical rides on lifestyle photography quality more than any other element; the archetype is downstream of how the brand photographs interiors and objects in use. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Brooklinen, Article, Floyd in marketing) and Luxe Considered (Parachute, West Elm, Pottery Barn premium tier). Minimal Essentialist appears at the design-purist edge (Floyd in product surfaces, Hem). Bold Confident appears at the challenger-mattress edge (Tuft and Needle historically, Casper historically). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Brooklinen \| Warm Conversational \| Friendly bedding brand; mid-saturation palette; clear value framing \| +\| Parachute \| Luxe Considered \| Cream and warm-neutral; aspirational bedding \| +\| Article \| Warm Conversational \| Mid-century furniture; muted palette; design-led \| +\| Floyd \| Minimal Essentialist \| Minimal modular furniture; clean type; restrained palette \| +\| West Elm \| Luxe Considered \| Premium home; serif type; lifestyle photography \| +\| Tuft and Needle (historical) \| Bold Confident historical, Warm Conversational now \| Direct-to-consumer mattress positioning \| +\| Casper (historical) \| Bold Confident historical \| Original sleep-better-everything campaign register \| +\| Hem \| Minimal Essentialist \| Scandinavian-influenced minimal; modular furniture \| +\| Quince \| Minimal Essentialist leaning Luxe Considered \| Premium-quality at accessible pricing; restraint as positioning \| +\| Snowe \| Luxe Considered \| Cream palette; minimal kitchenware aesthetic \| + +## Vertical-specific adaptation notes + +- Lifestyle photography is the foundation: the archetype rides on environmental photography quality. Bad room photography kills any archetype in this vertical. +- Product-in-context dominates: the bedding on a real bed, the chair in a real room. Product-on-white works only for technical specifications, not for hero photography. +- Material and craftsmanship narrative: how the brand discusses what the product is made of carries archetype weight. Luxe Considered uses material story heavily; Warm Conversational uses it lightly. +- Sustainability framing: increasingly default in this vertical; the archetype must accommodate it without leaning preachy. + +## Common archetype evolution + +Home brands frequently start Warm Conversational at launch and pull toward Luxe Considered as they raise prices and add product lines. Parachute's evolution shows this: launch era was more Warm Conversational; current Parachute is firmly Luxe Considered. Brooklinen has stayed Warm Conversational by intentionally holding its accessibility positioning. + +The mature-stage shift is usually: dial back the brand color, lean into typography and photography, drop overt accessibility framing. + +## Vertical anti-patterns + +- Technical Precise in home goods: completely incompatible. +- Vibrant Saturated in home goods: works only at the kids and novelty edge; reads as cheap on premium furniture and bedding. +- Rugged Utilitarian: works only when the brand is genuinely heritage-craftsman (cast iron, woodworking); slips into costume on mainstream home goods. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md new file mode 100644 index 0000000..1677ab1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md @@ -0,0 +1,43 @@ +# DTC: Food and Beverage + +## Vertical summary + +Brands selling beverages, snacks, supplements, and packaged food directly to consumers. Audience values: ingredient transparency, taste promise, and category disruption framing. The vertical is dominated by challenger brands using nostalgic-or-bold positioning to break into commoditized categories (soda, water, snacks, protein, energy drinks). + +## Common archetypes in this vertical + +The dominant archetype right now is Retro Nostalgic (Olipop, Liquid Death, Poppi), differentiating by era pick more than by archetype switch. Bold Confident appears at the energy and functional drink edge (AG1, Athletic Brewing). Minimal Essentialist appears at the clean-label edge (RXBar). Vibrant Saturated appears at the wellness-with-personality edge (Recess). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Olipop \| Retro Nostalgic (70s lean) \| Wellness-soda category creator; 70s wellness palette and type \| +\| Liquid Death \| Retro Nostalgic (80s metal lean) \| Water with metal-band branding; saturated metal aesthetic \| +\| Poppi \| Retro Nostalgic (90s lean) \| Pastel 90s palette; gut-health soda \| +\| AG1 (Athletic Greens) \| Bold Confident \| Black plus saturated green; premium green-powder positioning \| +\| RXBar \| Minimal Essentialist \| Black on white; no-bullshit label as brand identity \| +\| Athletic Brewing \| Bold Confident with retro undertones \| Non-alcoholic beer; heritage type plus modern energy \| +\| Recess \| Retro Nostalgic (70s wellness lean) \| Pastel palette; CBD and adaptogens with chill positioning \| +\| Magic Spoon \| Retro Nostalgic (90s cereal lean) \| Adult cereal with 90s saturated palette \| +\| Olly \| Retro Nostalgic with Playful Energetic notes \| Mass-market vitamins with playful 70s wellness register \| +\| Bare Performance Nutrition \| Bold Confident \| Black plus saturated accent; performance-supplement register \| + +## Vertical-specific adaptation notes + +- Era pick is the differentiation strategy: the F and B challenger category is dominated by Retro Nostalgic right now. Brands differentiate primarily by which era they reference, not by which archetype they pick. +- Packaging design is integrated with digital: the can, bottle, or box on the website is the brand. Packaging design must lead the digital brand expression. +- Ingredient transparency is default: nutrition facts, ingredient lists, and provenance stories must accommodate the archetype. +- Subscription mechanics: many F and B brands are subscription-driven; the archetype must extend cleanly into subscription management and unsubscribe surfaces. + +## Common archetype evolution + +F and B challenger brands frequently start strong in Retro Nostalgic and stay there. The brand identity is the era choice. Brands that try to evolve away from their original era reference usually lose differentiation. + +Mature brands sometimes dial back the era reference as they enter mass distribution: Olipop's recent surfaces are subtler about the 70s reference than its original launch. + +## Vertical anti-patterns + +- Editorial Restrained in F and B: works only at premium spirits and craft chocolate; reads as wrong-category for mass beverage and snack. +- Technical Precise: completely incompatible. +- Generic minimalism: F and B is so saturated with retro-and-bold brands that Minimal Essentialist works only when the brand has a sharp specific reason to be minimal (RXBar's no-bullshit label is the canonical case). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md new file mode 100644 index 0000000..3a97ae8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md @@ -0,0 +1,43 @@ +# Consumer Health and Wellness + +## Vertical summary + +Brands serving consumers across telehealth, mental wellness, fitness, supplements, and self-care. Audience values: trust signals, clinical credibility, and emotional positioning around health. The vertical splits between mental health (which leans warmer and softer) and physical health (which leans clinical and trust-led). + +## Common archetypes in this vertical + +The dominant archetypes split by mental versus physical: Clinical Trustworthy for telehealth and physical-meds (Hims, Ro, Cerebral, Care/of); Warm Conversational and Playful Energetic for mental wellness (Calm, Headspace); Vibrant Saturated at the gen-Z mental health edge (Bumble Health). Editorial Restrained appears at the longevity-clinic edge (Function Health). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Hims \| Clinical Trustworthy with peach warmth \| Mens-health telehealth; warm tone breaks pharmaceutical cold \| +\| Hers \| Clinical Trustworthy with warm accent \| Womens-health telehealth; same brand system, womens lens \| +\| Ro \| Clinical Trustworthy \| Trust-blue palette; multi-condition telehealth \| +\| Care/of \| Clinical Trustworthy with Warm Conversational \| Personalized supplements; warm trust register \| +\| Cerebral \| Clinical Trustworthy \| Mental-health telehealth; restraint signals seriousness \| +\| Calm \| Vibrant Saturated with restraint \| Sleep-and-meditation; gradient-rich; soft palette \| +\| Headspace \| Playful Energetic \| Orange brand; character-illustration-driven; meditation-with-personality \| +\| Talkspace \| Clinical Trustworthy \| Therapy access; cool palette; trust signals \| +\| Function Health \| Editorial Restrained \| Longevity testing; type-led restraint; institutional confidence \| +\| Whoop \| Technical Precise \| Performance health; data-density; athlete positioning \| + +## Vertical-specific adaptation notes + +- Mental versus physical health split: mental health brands lean warmer (Calm, Headspace, Talkspace); physical health brands lean clinical (Hims, Ro). The audience signals differ; the archetype must match. +- Regulatory copy affects voice. FDA disclaimers, medical disclaimers, prescription-required notices must accommodate the archetype. +- Trust through specificity: vague claims undermine the archetype. Specific dosages, specific evidence, specific licensed-clinician credentials carry the brand. +- Subscription-and-cancellation flows: the archetype must extend into ongoing subscription management; brands often lose trust here when the archetype breaks. + +## Common archetype evolution + +Health and wellness brands frequently stay in their original archetype but refine. Hims has stayed Clinical Trustworthy with growing warmth as it expanded categories. Calm has stayed in its restrained-vibrant lane as it expanded from meditation to sleep to broader wellness. + +Mental wellness brands that try to add physical-health products (or vice versa) often struggle to extend the archetype; the brand may need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- Bold Confident in clinical wellness: reads as overpromising. Health categories punish overpromise heavily. +- Rugged Utilitarian: works only in performance-athletic wellness; reads wrong in mainstream health. +- Vibrant Saturated in physical health: works only at younger-audience edges (Bumble Health for college students); reads wrong in mainstream telehealth. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md new file mode 100644 index 0000000..8b0b68a --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md @@ -0,0 +1,43 @@ +# Hospitality and Travel + +## Vertical summary + +Brands across hotels, short-term rentals, travel platforms, and travel-adjacent services. Audience values: trust signals (especially for booking platforms), aesthetic alignment (for hotels and properties), and experiential promise. The vertical is photography-dominated; the archetype rides on photo direction. + +## Common archetypes in this vertical + +The dominant archetypes are Documentary Honest (Airbnb in marketing, Selina, Hostelworld) and Luxe Considered (Aman, Four Seasons, premium hotel collections). Editorial Restrained appears at the hotel-tech edge (Sonder). Minimal Essentialist appears at travel-product brands (Away). Bold Confident at the disruptor edge (Hopper). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Airbnb \| Documentary Honest \| Real-photography of real homes; experiential framing \| +\| Aman \| Luxe Considered (extreme) \| Pure luxury hospitality; serif-led; understated authority \| +\| Four Seasons \| Luxe Considered \| Premium hotel chain; institutional luxury aesthetic \| +\| Selina \| Documentary Honest \| Lifestyle hotels; real-photography; community framing \| +\| Sonder \| Editorial Restrained \| Boutique short-stay; type-led; quiet confidence \| +\| Away \| Minimal Essentialist \| Travel luggage; minimal product photography; restrained type \| +\| Marriott Bonvoy \| Luxe Considered \| Loyalty program brand; aspirational typography \| +\| Hopper \| Bold Confident \| Saturated brand; price-prediction positioning \| +\| Hostelworld \| Playful Energetic \| Backpacker positioning; multi-color; younger-audience \| +\| Tripadvisor \| Warm Conversational \| Trust-through-reviews; friendly approachable register \| + +## Vertical-specific adaptation notes + +- Photography defines the vertical: the archetype is downstream of photo direction. Brands without exceptional photography cannot execute Documentary Honest or Luxe Considered. +- Booking flow versus discovery flow: the brand must extend across both surfaces. Booking flow leans toward trust signals (Clinical Trustworthy notes); discovery flow leans toward aspiration (the chosen archetype). +- Trust signals matter: reviews, ratings, cancellation policies must appear with archetype-appropriate weight. Luxe Considered makes trust signals understated; Documentary Honest puts them alongside imagery. +- Multi-property versus single-property: hotel chains (Marriott, Hilton) face different brand challenges than single-property luxury (Aman individual properties). The archetype must scale. + +## Common archetype evolution + +Hospitality brands frequently stay in their original archetype. Airbnb has stayed Documentary Honest through multiple rebrand iterations. Aman has stayed Luxe Considered since launch. Travel-product brands (Away) have stayed Minimal Essentialist. + +Brands that try to switch archetypes (for example a budget brand trying to feel premium without raising prices) usually fail to land. + +## Vertical anti-patterns + +- Technical Precise in hospitality: completely incompatible. +- Rugged Utilitarian in mainstream hospitality: works only at adventure-travel edges (REI Adventures); reads wrong in city hotels. +- Vibrant Saturated in luxury hospitality: undermines the premium positioning immediately. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md new file mode 100644 index 0000000..588967b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md @@ -0,0 +1,43 @@ +# Media and Publishing + +## Vertical summary + +Brands across digital publications, newsletters, books, podcasts, and editorial platforms. Audience values: editorial voice, intellectual rigor, and reading experience quality. The vertical is dominated by typography; the archetype rides on type system more than on color or photography. + +## Common archetypes in this vertical + +The dominant archetypes are Editorial Restrained (Substack, The Browser, Bloomberg, NYT Cooking) and Luxe Considered (Stripe Press, premium book design). Minimal Essentialist appears at the classic-publishing edge (Medium in its restrained era). Documentary Honest appears at journalism-as-brand (NYT visual journalism). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Substack \| Editorial Restrained \| Serif-led; cream paper; type-as-product \| +\| Stripe Press \| Luxe Considered \| Premium book design; typography excellence; collector-grade \| +\| The Browser \| Editorial Restrained \| Restrained newsletter; type-led; institutional reading register \| +\| NYT Cooking \| Editorial Restrained \| Recipe-focused; serif typography; brand-trust-through-restraint \| +\| Bloomberg \| Editorial Restrained \| Financial publishing; high-density information; institutional confidence \| +\| The Information \| Editorial Restrained \| Tech business journalism; type-led; subscriber-business model \| +\| Medium (classic) \| Minimal Essentialist \| Original era was pure restrained sans; recent evolution warmer \| +\| The New York Times \| Editorial Restrained \| Canonical example; serif-led; institutional journalism \| +\| Defector \| Editorial Restrained with personality \| Worker-owned sports; restrained with editorial voice \| +\| Lithub \| Editorial Restrained \| Literary publishing; serif throughout; reading-first \| + +## Vertical-specific adaptation notes + +- Type system carries the brand: in media and publishing, the typography is the brand. Most archetype decisions are font-pair decisions. +- Reading experience as primary surface: the article page must lead the brand expression. Marketing surfaces follow the article-reading experience. +- Long-form versus short-form: long-form journalism brands lean Editorial Restrained or Documentary Honest; newsletter and short-form brands have more archetype range. +- Subscription mechanics: paywall surfaces, subscription management, and unsubscribe flows must extend the archetype. Brands often lose archetype coherence at these surfaces. + +## Common archetype evolution + +Media brands frequently stay in their original archetype. Substack has stayed Editorial Restrained since launch. The New York Times has stayed Editorial Restrained for over a century. Bloomberg has stayed Editorial Restrained through multiple redesigns. + +Brands that try to add personality to a restrained archetype (Medium's attempts to feel warmer over time) often produce confusion. The discipline is the brand. + +## Vertical anti-patterns + +- Bold Confident in journalism: undermines credibility; reads as opinion-blog rather than reporting. +- Vibrant Saturated in publishing: works only at children's-publishing and novelty edges. +- Technical Precise in media: works only at niche publications (tech-focused) and reads wrong elsewhere. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md new file mode 100644 index 0000000..7b3d29b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/14-edtech.md @@ -0,0 +1,43 @@ +# EdTech + +## Vertical summary + +Brands across K-12 learning, higher education, professional development, and consumer learning apps. Audience splits sharply by age and learning context: children's apps lean playful; professional development leans clinical; consumer learning leans warm; technical education leans precise. The vertical rewards personality on the consumer side and authority on the institutional side. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Playful Energetic for K-12 and habit-forming consumer learning (Duolingo, Khan Academy Kids). Warm Conversational for adult consumer learning (Khan Academy, Brilliant). Clinical Trustworthy for professional development (Coursera, edX). Luxe Considered for premium adult education (MasterClass). Technical Precise for technical education (Codecademy, Frontend Masters). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Duolingo \| Playful Energetic (canonical) \| Owl mascot; saturated green; character-driven habit formation \| +\| Khan Academy \| Warm Conversational \| Friendly approachable; muted palette; non-profit mission framing \| +\| Brilliant \| Bold Confident leaning Warm Conversational \| Math-and-science learning; saturated palette; problem-solving register \| +\| MasterClass \| Luxe Considered \| Premium adult education; editorial photography; celebrity-instructor positioning \| +\| Codecademy \| Technical Precise \| Developer education; dark mode; code-first \| +\| Coursera \| Clinical Trustworthy \| Higher-ed-credentialed; cool palette; institutional partnerships \| +\| edX \| Clinical Trustworthy \| University-courses-online; restrained academic register \| +\| Udemy \| Warm Conversational \| Mass-market courses; multi-hue palette; accessible pricing \| +\| Outschool \| Playful Energetic with Warm Conversational \| K-12 small-group learning; warm illustration; family register \| +\| Frontend Masters \| Technical Precise \| Developer-focused; dark mode; instructor-as-authority \| + +## Vertical-specific adaptation notes + +- Audience age determines archetype: K-12 leans playful; teens lean bold; adults lean warm or clinical; technical learners lean precise. Pick the audience first. +- Habit formation versus information transfer: habit-formation products (language apps, daily-skill apps) lean playful. Information-transfer products (course platforms, lectures) lean restrained or clinical. +- Credential signaling: institutional partnerships, certifications, accreditation must appear with archetype-appropriate weight. Clinical Trustworthy makes them prominent; Playful Energetic makes them secondary. +- Progress mechanics: streaks, badges, leveling are core to many edtech products. The archetype must extend into gamification surfaces. + +## Common archetype evolution + +Edtech brands frequently start in their target audience archetype and stay. Duolingo has stayed Playful Energetic since launch (with increasing character development). Coursera has stayed Clinical Trustworthy. MasterClass has stayed Luxe Considered. + +Brands that try to switch (a K-12 brand attempting to add adult learning) usually need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- Playful Energetic for adult professional development: reads as unserious; adult learners reject playful brand expression for credential-building. +- Clinical Trustworthy for K-12: reads as cold and unfriendly to children and parents. +- Rugged Utilitarian: works only at outdoor-education edge (NOLS, Outward Bound); reads wrong elsewhere. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md new file mode 100644 index 0000000..86dba90 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md @@ -0,0 +1,43 @@ +# Gaming and Entertainment + +## Vertical summary + +Brands across gaming platforms, streaming services, game studios, and entertainment apps. Audience values: cultural alignment with the gaming or entertainment subculture, content discovery, and community signals. The vertical splits between platform brands (chrome that hosts content) and content brands (the games or shows themselves). Platforms tend toward restraint to let content carry; content brands lean toward expression. + +## Common archetypes in this vertical + +The dominant archetypes are Bold Confident (Epic Games, Riot, Discord) and Vibrant Saturated (Discord with character, Twitch). Editorial Restrained appears at the platform-chrome edge (Steam at category level). Retro Nostalgic appears at indie-gaming and arcade-revival brands. Minimal Essentialist appears at platform-distributor edges (Itch.io). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Discord \| Vibrant Saturated with character \| Multi-hue brand palette; community-focused; playful chrome \| +\| Steam \| Editorial Restrained at category level \| Platform chrome restrained to let games lead; dark mode dominant \| +\| Twitch \| Vibrant Saturated \| Saturated purple; live-streaming positioning \| +\| Epic Games \| Bold Confident \| Strong brand colors; platform energy \| +\| Riot Games \| Bold Confident \| Saturated brand; competitive-gaming positioning \| +\| Itch.io \| Minimal Essentialist \| Indie game platform; minimal chrome; lets games carry \| +\| Spotify (entertainment) \| Vibrant Saturated \| Saturated green; mood-based personalization \| +\| Netflix \| Bold Confident \| Black plus red; content-as-hero; minimal platform chrome \| +\| HBO Max (Max) \| Editorial Restrained leaning Luxe Considered \| Premium streaming positioning; restrained type \| +\| Roblox \| Playful Energetic \| Multi-color brand; family-friendly positioning \| + +## Vertical-specific adaptation notes + +- Platform versus content distinction: platform brands (the place where games or shows live) lean toward restraint to avoid competing with content. Content brands (individual games, shows, studios) lean toward expression. +- Dark mode dominance: most gaming and entertainment surfaces lean dark-mode-first to support content viewing. +- Subculture signaling: gaming brands often signal subculture alignment (esports, indie, MMO, casual mobile). The archetype must extend to subculture-appropriate visual cues. +- Live and real-time experiences: many brands in this vertical have real-time surfaces (live streams, multiplayer lobbies) that affect archetype expression. + +## Common archetype evolution + +Gaming brands frequently choose archetypes orthogonal to their content. Discord is Vibrant Saturated despite hosting communities of every register. Steam is Editorial Restrained despite hosting saturated games. The platform chrome makes a brand decision separate from the content's character. + +Mature platforms sometimes pull back ornamentation to let content lead (Netflix's evolution toward minimalist chrome shows this). + +## Vertical anti-patterns + +- Clinical Trustworthy in gaming: incompatible; gaming audiences reject clinical framing. +- Rugged Utilitarian: works only at simulation-and-mil-sim edges; reads wrong on mainstream gaming. +- Luxe Considered in mass gaming: works only at premium subscription tiers (Max, Apple TV Plus); reads wrong on free-to-play and casual. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md new file mode 100644 index 0000000..2148be5 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/16-marketplace.md @@ -0,0 +1,43 @@ +# Marketplace + +## Vertical summary + +Brands operating two-sided platforms connecting buyers and sellers across categories: handmade goods, secondhand, niche-expert, livestream commerce, B2B wholesale. Audience values: trust signals, seller quality verification, and category authority. Marketplace brands face a unique brand challenge: the platform brand interacts with hundreds or thousands of seller brands, and the platform must hold an identity that does not compete with seller identities. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Etsy, Faire in marketing) and Bold Confident (StockX, Whatnot). Editorial Restrained appears at the niche-expert edge (Reverb). Vibrant Saturated appears at the gen-Z commerce edge (Depop). Documentary Honest at the artisan-commerce edge (Etsy's seller stories). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Etsy \| Warm Conversational with craft emphasis \| Handmade marketplace; warm palette; seller-story framing \| +\| Reverb \| Editorial Restrained with niche-expert voice \| Musical instruments; type-led; expertise-as-trust \| +\| Faire \| Editorial Restrained \| Wholesale marketplace; restrained type; B2B confidence \| +\| StockX \| Bold Confident \| Sneakers and streetwear; saturated brand; market-data positioning \| +\| Whatnot \| Bold Confident \| Livestream commerce; saturated palette; energy register \| +\| Depop \| Vibrant Saturated \| Gen-Z fashion resale; bright multi-hue palette \| +\| Vinted \| Warm Conversational \| European resale; cream palette; friendly approach \| +\| eBay \| Bold Confident \| Established marketplace; high-energy multi-color brand \| +\| Mercari \| Warm Conversational \| Resale marketplace; soft palette; approachable \| +\| Substack (creator marketplace) \| Editorial Restrained \| Newsletter marketplace; serif type; creator-economy framing \| + +## Vertical-specific adaptation notes + +- Platform brand versus seller brands: the marketplace brand must hold an identity that does not compete with seller brands. Restraint often wins; let sellers carry visual energy. +- Trust signals matter heavily: ratings, reviews, return policies, seller verification carry brand weight. The archetype must give trust signals appropriate space. +- Multi-category challenge: marketplaces frequently span many product categories. The brand must work for fashion, electronics, home goods, and handmade simultaneously. +- Buyer-side versus seller-side surfaces: marketplace brands often have parallel surfaces for buyers (consumer-facing) and sellers (creator-or-merchant facing). The archetype must extend coherently to both. + +## Common archetype evolution + +Marketplace brands frequently start in their original archetype and stay. Etsy has stayed Warm Conversational since its early days (with refinements). StockX has stayed Bold Confident since launch. + +Brands that try to switch archetypes (Etsy's brief attempts at more polished marketing in the late 2010s) usually pull back to their original positioning. + +## Vertical anti-patterns + +- Luxe Considered in mass-market marketplaces: works only at curated-luxury marketplaces (1stDibs, Sotheby's); reads out-of-place elsewhere. +- Technical Precise: works only at B2B infrastructure marketplaces (Faire's developer-tools edge); reads wrong on consumer. +- Clinical Trustworthy: incompatible; reads as cold and corporate where marketplaces need community feeling. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md new file mode 100644 index 0000000..6a1e674 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md @@ -0,0 +1,43 @@ +# Crypto and Web3 + +## Vertical summary + +Brands across crypto exchanges, wallets, NFT platforms, DeFi protocols, and Web3 infrastructure. Audience splits between consumer (Coinbase-tier accessibility) and infrastructure (developer-and-builder-tier precision). The vertical has unusual archetype range because crypto culture spans speculative-energy to cypherpunk-minimal to artist-luxe. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Bold Confident for consumer crypto (Coinbase, OpenSea, Rainbow). Technical Precise for protocol and infrastructure (Anchor, Alchemy). Editorial Restrained at the writing-and-publishing edge (Mirror). Luxe Considered at the NFT-art edge (Foundation, Async Art). Vibrant Saturated at the consumer-wallet edge (Rainbow). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Coinbase \| Bold Confident with blue \| Trust-blue palette; mainstream-consumer positioning \| +\| OpenSea \| Bold Confident \| Saturated palette; NFT marketplace energy \| +\| Mirror \| Editorial Restrained \| Decentralized publishing; serif-led; restrained confidence \| +\| Foundation \| Luxe Considered \| NFT art marketplace; cream palette; curated-gallery feeling \| +\| Rainbow \| Vibrant Saturated \| Multi-hue wallet brand; gradient-rich; consumer-friendly \| +\| Phantom \| Bold Confident with purple \| Solana wallet; saturated brand; consumer-tilted \| +\| Uniswap \| Bold Confident with Vibrant Saturated \| DeFi protocol; pink-and-saturated brand; consumer-DeFi \| +\| Alchemy \| Technical Precise \| Web3 infrastructure; developer-facing; cool palette \| +\| Polygon \| Bold Confident \| Layer-2 infrastructure; saturated purple; institutional positioning \| +\| Async Art \| Luxe Considered \| Programmable art; restrained gallery aesthetic \| + +## Vertical-specific adaptation notes + +- Consumer versus infrastructure split: consumer brands (Coinbase, Rainbow, Phantom) lean energetic and friendly. Infrastructure brands (Alchemy, Anchor) lean toward Technical Precise. The archetype must match the audience. +- Trust signals matter: regulatory framing, audit reports, security signals must accommodate the archetype. Bold Confident makes them inline; Technical Precise gives them dedicated surfaces. +- Cultural alignment: crypto culture has subcultures (cypherpunk, DeFi-degen, NFT-collector, builder). Brands must signal which subculture they speak to. +- Compliance copy: increasing regulatory pressure (especially post-2024) affects brand voice; the archetype must accommodate disclaimers without breaking. + +## Common archetype evolution + +Crypto brands frequently shift archetype as the regulatory environment matures and as they target broader audiences. Coinbase has moved from more energetic to more institutional over its lifetime. Many crypto brands started Vibrant Saturated (matching crypto culture energy of 2021-2022) and pulled back toward Bold Confident or Editorial Restrained. + +The mature-stage shift is typically: dial back the saturation, add trust signals, lean into typographic restraint without losing the consumer accessibility. + +## Vertical anti-patterns + +- Warm Conversational in crypto: works only at extremely consumer-tilted onboarding products; reads wrong on most surfaces. +- Rugged Utilitarian: incompatible. +- Clinical Trustworthy in pure DeFi: reads as trying to be a bank; works only at the regulated-stablecoin edge. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md new file mode 100644 index 0000000..d04cc2f --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md @@ -0,0 +1,44 @@ +# Real Estate and Proptech + +## Vertical summary + +Brands across residential real estate platforms, premium real estate, proptech tools, and home-buying products. Audience splits sharply by price point: premium residential real estate leans Luxe Considered universally; mass-market platforms split between Warm Conversational, Bold Confident, and Clinical Trustworthy. The vertical rewards trust signals across every archetype because real estate transactions are high-value, high-friction, and infrequent. + +## Common archetypes in this vertical + +The dominant archetypes are Luxe Considered at the premium tier (Compass, Sotheby's International Realty, Pacaso). Bold Confident at the disruptor tier (Opendoor, Sundae). Warm Conversational at the consumer-information tier (Zillow). Clinical Trustworthy at the technology-platform tier (Redfin). Editorial Restrained at the proptech-software edge (some commercial real estate platforms). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Compass \| Luxe Considered \| Premium residential; serif typography; agent-network positioning \| +\| Zillow \| Warm Conversational at consumer edge \| Friendly approachable; muted palette; consumer-information register \| +\| Redfin \| Clinical Trustworthy \| Cool palette; technology-platform positioning; agent-as-employee model \| +\| Opendoor \| Bold Confident \| Saturated brand; instant-offer disruption framing \| +\| Sundae \| Bold Confident \| Saturated brand; off-market-property positioning \| +\| Pacaso \| Luxe Considered \| Co-ownership of vacation homes; premium photography; lifestyle framing \| +\| Sotheby's International Realty \| Luxe Considered (extreme) \| Pure premium real estate; serif throughout; institutional luxury \| +\| Cadre \| Editorial Restrained \| Commercial real estate investment platform; restrained type \| +\| Knock \| Bold Confident \| Home-trade-in services; saturated brand \| +\| Vacasa \| Warm Conversational with Documentary Honest \| Vacation rental management; real-photography of properties \| + +## Vertical-specific adaptation notes + +- Premium versus mass-market split is sharp: premium real estate is universally Luxe Considered; mass-market splits into three or four archetypes based on positioning. +- Photography is critical: real estate brands depend on excellent property photography. The archetype rides on photo direction. +- Trust signals across every archetype: license info, agent credentials, customer reviews, third-party certifications must appear with appropriate weight. Premium archetypes make these understated; consumer archetypes make them prominent. +- Local versus national: many real estate brands operate hyper-locally (individual agents and small brokerages). The archetype must extend to local agent-branded surfaces. + +## Common archetype evolution + +Real estate brands frequently stay in their original archetype. Compass has stayed Luxe Considered since launch. Zillow has stayed Warm Conversational. Redfin has stayed Clinical Trustworthy. + +Brands that try to switch archetypes (a mass-market brand attempting to feel premium) usually struggle to convince either audience. Real estate is unusually punishing of inauthentic positioning. + +## Vertical anti-patterns + +- Vibrant Saturated in real estate: incompatible; reads as untrustworthy with high-value transactions. +- Playful Energetic: incompatible. +- Rugged Utilitarian: works only at vacation-property and recreational-land edges; reads wrong on mainstream residential. +- Technical Precise: works only at commercial real estate analytics platforms (CoStar tier); reads wrong on consumer. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md new file mode 100644 index 0000000..0af4a7c --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md @@ -0,0 +1,119 @@ +# Editorial Restrained + +## Aesthetic summary + +Low-saturation, type-led, generous whitespace. Considered rather than performed. The brand earns attention through restraint instead of demanding it through volume. Reads as institutional confidence without stiffness. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (warm but precise, comfortable with first person) +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0F1B2D \| Primary text, body, anchors \| +\| ink-muted \| #1F2D44 \| Secondary text \| +\| paper \| #FAF9F6 \| Warm off-white background \| +\| paper-soft \| #F3F1EC \| Card surfaces, subtle elevation \| +\| accent \| #5B8B85 \| Single accent for links and key actions \| +\| accent-muted \| #3F6E55 \| Hover states, secondary accent applications \| +\| highlight \| #C9A227 \| Numeric callouts, display sizes only \| +\| highlight-body \| #8E6E1A \| Same hue at body-text contrast (WCAG AA) \| +\| line \| #EDEFF2 \| Borders, separators \| + +Rationale: +- Ink at #0F1B2D not pure black. Pure black on warm paper feels harsh; navy ink reads as ink-on-paper. +- Paper at #FAF9F6 not pure white. Warm tint signals editorial register versus UI register. +- Accent restricted to one hue. Two-color systems read as institutional; multi-color reads as consumer. +- Highlight restricted to display sizes; the body-contrast variant (#8E6E1A) covers WCAG AA at smaller scales without losing the warm-gold character. + +## Type pairing starter + +- Display: IBM Plex Serif (Google Fonts, free). 700 for hero, 600 for sections. +- Body: Inter (Google Fonts, free). 400 for prose, 500 for UI labels. +- Numerics: JetBrains Mono (Google Fonts, free). 400 to 500 for KPIs and code. + +Size scale (modular, 1.2 ratio anchored at 16px): +- Hero: 56 to 72px serif +- H2: 32 to 40px serif +- H3: 22 to 26px serif +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Mono: 14 to 16px monospace + +Pairing rationale: serif display plus sans body is the classic editorial pairing (NYT, magazines). IBM Plex specifically has open apertures and modest contrast that reads as institutional but modern. JetBrains Mono for numbers communicates precision without being overtly technical. + +## Layout and composition + +- Generous whitespace. Sections separated by 96 to 128px vertical rhythm minimum. +- Single-column hero, content left-aligned, max-width around 720px for prose. +- Asymmetric grids on landing pages: 2-column with deliberate imbalance (40/60 or 60/40) more often than centered or 50/50. +- Density: low. The page should breathe. +- Cards: subtle elevation via 1px line border at line color, no drop shadows. + +## Imagery direction + +- Photography: editorial, low-touched, real environments, natural light. +- Illustration: rare. If used, line-only, single color, technical drawing register. +- Product UI: shown in stylized chrome with branded surfaces; rarely the actual app screenshot. +- Decorative imagery: avoided. Everything earns its place. + +## Voice samples + +- "Built around the question, not against the event stream." +- "Real components, real brand foundations, real working forms." +- "The measurement surface PLG teams actually need." +- "Onboarding metrics live in the cracks between general-purpose tools." +- "Focused, not just smaller." +- "Sample funnel, real benchmarks, your cohort." +- "Pre-built activation funnels. Time-to-first-value benchmarking." + +Cadence: complete sentences. Comma-separated qualifiers more often than dashed asides. Direct claims with built-in qualification. No exclamation marks. Numerals over written numbers. + +## Component pattern descriptions + +Hero: Eyebrow (uppercase, accent color, letterspaced 0.16em), then serif headline 56 to 72px, then sans subhead 18px paragraph, then 2 buttons (primary solid ink, secondary outline), optional KPI strip below. + +Buttons: Primary is solid ink, white text. Secondary is white surface, ink border 1px, ink text. No gradients. No drop shadows. Hover state shifts opacity to 0.9 or fills the secondary surface. + +Cards: Paper-soft background, 1px line border, 24 to 32px internal padding. Numerals top-left in mono. Title in serif. Body in sans. + +Tables: Paper-soft header row, line color separators between rows, monospace numerics aligned right. + +## When to pick this + +- B2B brand for a measured, considered audience (PMs, engineers, founders, finance) +- Category is loud and your differentiation is calm +- Product earns attention through depth rather than novelty +- Audience reads documentation and trusts restraint + +## When to avoid + +- Consumer brand for an audience that wants energy and warmth +- Product that needs to feel inviting at first touch +- Category where competitors are already restrained (you will disappear) +- Brand that needs to communicate playfulness or character + +## Adaptation guidance + +When applying this archetype to a specific brief: + +1. Keep the structure (whitespace, single-accent, restrained type pairing). Adapt specific values. +2. Color: shift accent hue to match emotional direction. Muted teal feels rational; muted plum feels considered; muted moss feels grounded; muted slate feels institutional. +3. Type: IBM Plex Serif is a starting point. Substitutes that fit: GT Sectra, Tiempos, Fraunces, Source Serif. +4. Density: dial up or down based on audience. Developers tolerate more density; founders prefer more whitespace. +5. Highlight color: optional. Brands without a numeric story do not need it. + +Direct copying of all defaults verbatim produces generic Editorial Restrained output. The brief should produce a meaningful variant. + +## Exemplar brands + +Editorial Restrained is exemplified by Linear, Vercel, Stripe Press, Resend, and the fictional Threshold reference build in this catalog. Earlier examples include Pentagram's institutional work and the early Medium publication system. + +These brands share: serif display, sans body, single accent, generous whitespace, editorial photography or stylized product UI, peer-relationship voice. + +The archetype overlaps with Technical Precise (Stripe docs, Sentry); blended brands typically use Editorial Restrained for marketing surfaces and Technical Precise for documentation surfaces. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md new file mode 100644 index 0000000..8180aea --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md @@ -0,0 +1,122 @@ +# Technical Precise + +## Aesthetic summary + +Monospace prominent in display and numerics. Grid visible in compositions. Data density tolerated and embraced. Dark mode often dominant. Cool palette with high precision feel. The brand communicates that it understands the technical substance of what it is selling, and that its audience does too. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (precise, low-affect, treats the reader as informed) +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Functional + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0A0E1A \| Light-mode primary text \| +\| ink-muted \| #1F2937 \| Light-mode secondary text \| +\| paper \| #FFFFFF \| Light-mode background \| +\| paper-soft \| #F6F8FA \| Light-mode card surface \| +\| surface-dark \| #0F1117 \| Dark-mode primary background \| +\| surface-dark-elevated \| #161922 \| Dark-mode card surface \| +\| text-dark \| #E6E9F2 \| Dark-mode primary text \| +\| text-dark-muted \| #9DA4B4 \| Dark-mode secondary text \| +\| accent \| #7C5CFF \| Saturated single accent (violet shown) \| +\| accent-muted \| #5B3FD6 \| Active state \| +\| signal-success \| #16A34A \| Positive numeric signal \| +\| signal-warn \| #F59E0B \| Caution signal \| +\| signal-error \| #DC2626 \| Error signal \| +\| line \| #2A2F3C \| Dark-mode line, panel separators \| + +Rationale: +- Dark mode is first-class; the palette is built dark-mode primary with light-mode adaptations. +- Single saturated accent (violet, electric blue, lime, or cyan) lets the rest of the palette stay neutral. +- Signal colors are functional, not decorative; reserved for status communication in dashboards and logs. +- Lines visible (#2A2F3C in dark, #E5E7EB in light) to reinforce the grid character. + +## Type pairing starter + +- Display: Geist Sans (Vercel, free) or Inter Display. 600 to 700 weight. +- Body: Geist Sans or Inter. 400 to 500. +- Monospace: Geist Mono or JetBrains Mono. Prominent in display, numerics, code samples, KPIs, badges, and labels. + +Size scale (modular, 1.25 ratio anchored at 15px for higher density): +- Hero: 48 to 64px sans +- Hero-mono: 36 to 48px mono (for technical brands using mono in display) +- H2: 28 to 36px sans +- Body: 15 to 16px sans +- Small: 13px sans +- Code: 14 to 15px mono + +Pairing rationale: Geist (and its mono variant) was designed specifically for technical product interfaces. Inter plus JetBrains Mono is the equivalent if Geist is not available. The mono should appear regularly enough that the reader registers the brand uses it deliberately. + +## Layout and composition + +- Higher density than Editorial Restrained. The reader expects information. +- Grids are visible: hairline borders on cards and tables, monospace coordinates in nav, table-of-contents sidebars. +- Code samples are treated as primary content, not supplementary. +- Hero often pairs a clean headline with a live-looking product surface (dashboard, terminal, code editor). +- Dark mode is the design target; light mode is the adaptation. + +## Imagery direction + +- Photography: rare. When used, abstract or product-context, not people. +- Illustration: technical diagrams, network graphs, architecture maps. Single accent color over neutral background. +- Product UI: shown as real screenshots or near-real chrome. The product surface itself is the brand asset. +- Decorative imagery: minimal. The information density is the visual. + +## Voice samples + +- "Latency p99: 47ms across 12 regions." +- "Idempotent by default. Versioned endpoints. Zero-downtime migrations." +- "Built for the request volume you actually have at 3am." +- "Error budgets, not vibes." +- "Your stack already speaks this protocol." +- "Run it locally. Deploy it globally. Same primitives." +- "Observability that does not require its own observability." + +Cadence: short. Often fragments. Numerals over words. Technical specificity over abstraction. Comfortable with industry vocabulary. + +## Component pattern descriptions + +Hero: Often split layout: left side is headline plus sub plus 2 CTAs, right side is a live product surface (terminal, dashboard, code editor). Or full-bleed dark with an oversized mono headline. + +Buttons: Primary is solid accent on dark, or solid ink on light. Secondary is bordered. Often a small mono prefix on labels ("$ deploy" pattern). + +Cards: Hairline border, dark-elevated background, monospace metadata in the header row, sans body. Often with a small status dot (signal color) in the corner. + +Tables: Dense. Hairline rows. Mono numerics, right-aligned. Hover state with a faint accent tint. Sortable columns marked. + +Code blocks: First-class. Syntax highlighting palette is part of the brand. Copy button. Language label. + +## When to pick this + +- Developer audience +- Observability, platform, infrastructure, or DX product +- Audience values data density and precise specification +- Brand needs to communicate "we built this, we run it, we understand it" + +## When to avoid + +- Consumer audience that wants warmth +- Product that is not technically substantive (the archetype will read as costume) +- Brand needs to communicate approachability over rigor +- Photography or human imagery is central to the brand story + +## Adaptation guidance + +1. Accent hue: violet for product-first brands, electric blue for infrastructure, lime or cyan for AI-adjacent, soft green for sustainability-leaning. +2. Mono density: dial up for developer brands (mono in hero, mono in nav, mono in labels) and dial down for prosumer brands wanting only the precision signal. +3. Dark mode: required. Skip this archetype if the brand cannot ship a dark mode. +4. Photography: if the brand needs human imagery, blend with Editorial Restrained or Warm Conversational instead of forcing it into Technical Precise. +5. Voice density: stay specific. Vague claims in this archetype read as worse than vague claims elsewhere, because the visual is promising specificity. + +## Exemplar brands + +Technical Precise is exemplified by Stripe (especially the documentation and developer surfaces), Sentry, Datadog, Vercel, Cursor, and Linear in its most technical surfaces. Adjacent older examples include the early Heroku CLI and the original GitHub UI before its consumer-tilted redesigns. + +These brands share: dark-mode-first, monospace prominent, code as first-class content, saturated single accent, dense tables and grids, low-affect voice. + +The archetype frequently blends with Editorial Restrained at the marketing surface level (Stripe's marketing pages, Vercel's announcements) while keeping the technical surface pure Technical Precise. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md new file mode 100644 index 0000000..82530ab --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md @@ -0,0 +1,114 @@ +# Warm Conversational + +## Aesthetic summary + +Human imagery, mid-saturation palette with warm undertones, approachable type, second-person voice. The brand reads as a colleague who genuinely wants to help rather than a vendor selling. Friendly without performance; honest without coldness. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational +- Aesthetic register: Considered +- Audience relationship: Companion +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1F2937 \| Primary text \| +\| ink-muted \| #4B5563 \| Secondary text \| +\| paper \| #FFFBF5 \| Cream background \| +\| paper-soft \| #FAF3E7 \| Card surface \| +\| accent \| #D97757 \| Warm terracotta primary accent \| +\| accent-soft \| #F3B690 \| Tint of accent for backgrounds \| +\| accent-deep \| #A75440 \| Active state \| +\| support-green \| #5A8A6E \| Sage green secondary \| +\| support-blue \| #5E8FA8 \| Dusty blue secondary \| +\| line \| #E8DFCF \| Borders, separators on cream \| + +Rationale: +- Cream background (not white) is the foundation; it signals warmth before any other element fires. +- Mid-saturation accent (terracotta shown) is warm and human; cooler accents (sage, dusty blue) appear as secondary tones rather than primaries. +- The palette is calibrated mid-saturation throughout; no value is below 35% or above 70% saturation. This is what produces the "considered warmth" reading instead of either pastel or vivid. +- Lines use a warm gray rather than neutral gray to keep coherence with the paper. + +## Type pairing starter + +- Display: Hubot Sans or Söhne or GT America. 600 to 700. +- Body: Same family for body, 400 to 500. Single-family systems read warmer than serif plus sans pairings. +- Optional accent type: a friendly humanist serif (Tiempos Text, Source Serif) for editorial moments inside otherwise sans content. + +Size scale (modular, 1.2 ratio anchored at 17px for comfortable reading): +- Hero: 48 to 64px sans +- H2: 30 to 38px sans +- H3: 22 to 26px sans +- Body: 17 to 19px sans (slightly larger than B2B default) +- Small: 14 to 15px sans + +Pairing rationale: single-family sans systems read warm and consistent. Humanist or geometric-humanist sans (Hubot, Söhne, GT America) have rounder shapes than neo-grotesques like Helvetica, which is what produces the "friendly" reading without sliding into childlike. Body sizes run slightly larger than other archetypes because the reader is expected to actually read. + +## Layout and composition + +- Comfortable density. Not as breathing as Editorial Restrained, not as dense as Technical Precise. +- Sections frequently use full-bleed photography or illustration as scene-setters. +- Hero often pairs a human photo (real customer, real team member) with a friendly headline. +- Generous interior padding inside cards and forms; the page feels welcoming rather than businesslike. +- Curved corners (8 to 16px) on cards and buttons; sharp corners read colder. + +## Imagery direction + +- Photography: real people, varied skin tones and body types, candid rather than posed, natural light, real environments (homes, coffee shops, offices that look lived-in). +- Illustration: custom illustration systems are common (Mailchimp's monkey era, Slack's hands-and-objects era). When used, illustration should have a consistent vocabulary rather than stock-feeling variety. +- Product UI: shown in real photo-context (laptop on a real desk) more often than stylized chrome. +- Stock photography pitfall: this archetype dies on bad stock photo selection. Curate hard or commission custom. + +## Voice samples + +- "Sign up takes about a minute. We will not ask for a credit card." +- "Here is what we tried, what worked, and what did not." +- "You probably do not need a meeting for this. But if you do, we can hop on one." +- "Made for teams who would rather get the work done than configure the tool that does the work." +- "Yes, we send fewer emails than other tools. On purpose." +- "We charge what we charge because that is what it costs to run the thing well." + +Cadence: complete sentences. Comfortable with first and second person. Contractions and hedging are fine; performed informality ("hey friend!") is not. Reads honest, not chummy. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 or 2 CTAs, often paired with a human photo or warm illustration. Background frequently cream (not white). Headline weight is mid-bold (600), not display-heavy. + +Buttons: Primary is solid accent, white text, 10 to 16px corner radius. Secondary is bordered or text-only. Hover states use a slight color deepening rather than opacity shift. + +Cards: Soft cream surfaces, 12 to 16px radius, generous padding (32 to 40px), shadow at low intensity (0 4px 12px rgba(0,0,0,0.04)). + +Forms: Generous field height (48 to 56px). Labels above inputs (not floating). Help text below fields. Pre-fill where possible. + +## When to pick this + +- Prosumer SaaS, team productivity, marketing tools at the consumer-leaning edge +- Brand needs to communicate "we get you" more than "we are best in class" +- Audience values approachability over rigor +- Brand wants to differentiate in a category of cold competitors + +## When to avoid + +- Audience that reads warmth as unserious (most developer infrastructure, most enterprise) +- Brand with limited photography or illustration budget (the archetype dies on bad imagery) +- Brand needs to communicate authority or expertise as the primary signal +- Category is already crowded with warm brands (you will disappear) + +## Adaptation guidance + +1. Accent hue: terracotta and warm orange feel grounded; sage green and dusty blue feel calm; coral and peach feel optimistic. Pick one primary based on emotional direction. +2. Single-family vs paired type: single-family sans is the default. If the brand needs editorial moments, add a humanist serif as the accent type, not as the body. +3. Illustration vs photography: pick one as primary. Brands trying to do both usually do neither well. +4. Voice: write honest first, friendly second. Performed friendliness without honest substance reads cheap. +5. Density: avoid over-roominess. The archetype tips into "marketing fluff" when the page is too breathing and the content is too thin. + +## Exemplar brands + +Warm Conversational is exemplified by Mailchimp (especially the illustration-driven era), Webflow, Slack, Notion in its marketing surfaces, Loom, Intercom, and Figma. Adjacent examples include Khan Academy and Mailchimp's earlier mascot work. + +These brands share: cream or warm-white surfaces, single-family sans, mid-saturation warm accent, human or custom-illustration imagery, second-person voice, comfortable density. + +The archetype frequently overlaps with Playful Energetic when the illustration system carries character; the difference is that Warm Conversational keeps the illustration in service of communication, while Playful Energetic lets the illustration become the dominant visual. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md new file mode 100644 index 0000000..f1710a6 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md @@ -0,0 +1,115 @@ +# Bold Confident + +## Aesthetic summary + +High-contrast color (often black plus one saturated accent). Oversized display type used as design element. Direct copy. Strong horizontal grids. The brand walks into the room and says what it is selling without flinching. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (direct, comfortable with first person) +- Aesthetic register: Expressive +- Audience relationship: Performer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0A0A0A \| Near-black primary \| +\| paper \| #FFFFFF \| White surface \| +\| paper-soft \| #F2F2F2 \| Tinted surface \| +\| accent \| #FF4D2E \| Saturated single accent (vibrant orange shown) \| +\| accent-deep \| #C13A20 \| Active state \| +\| support \| #18181B \| Off-black for layered surfaces \| +\| line \| #1F1F1F \| Heavy line color (matches the bold register) \| + +Alternative accent picks that fit this archetype (one only): +- Hot pink: #EC2877 +- Lime: #C7F11D +- Electric blue: #2563EB +- Saturated yellow: #FFD400 (use with extreme contrast) + +Rationale: +- Two-tone is the move: high-contrast black-and-white plus one saturated accent. Three or more colors dilute the boldness. +- Pure black (or near-black) and pure white reinforce the contrast register. Off-blacks or warm whites pull the archetype toward Editorial Restrained. +- The accent is loud enough that it has to be deployed sparingly. Used as background for one section, not as button color everywhere. + +## Type pairing starter + +- Display: Druk Wide, Söhne Breit, GT Sectra Display, Helvetica Now Display, or PP Editorial New (when leaning expressive editorial). Heavy weight (800 to 900) on display. +- Body: Söhne, Inter, or Helvetica Now. Mid-weight (500). + +Size scale (extreme contrast between hero and body): +- Hero: 80 to 140px display (the headline is the hero) +- H2: 48 to 72px display +- H3: 28 to 36px +- Body: 17 to 19px +- Small: 14 to 15px + +Pairing rationale: the archetype is built around extreme type contrast. Hero type runs huge (often 100px or more on desktop); body type is normal. The size ratio itself is the visual signature. Heavy display weights are non-negotiable; light or regular weights produce a different archetype entirely. + +## Layout and composition + +- Horizontal grids dominate. Heroes often full-bleed with the headline as the design element. +- Asymmetric layouts with intentional imbalance: text aligned hard-left, oversized headlines that extend past container edges. +- High contrast section transitions: black section, then white section, then accent section. The page reads as panels. +- Sharp corners more often than rounded. +- Minimal decorative imagery; the type IS the visual. + +## Imagery direction + +- Photography: high-contrast, often desaturated or single-color-tinted, real but stylized. +- Illustration: bold flat illustration when used, single accent color, no gradients. +- Product UI: shown in oversized chrome that mirrors the brand's contrast register. +- Decorative: type-as-image; the headline often becomes the visual. + +## Voice samples + +- "We do not negotiate with hidden fees." +- "Built for the people doing the actual work." +- "This is the version that works. The free trial is the version that works." +- "No setup call. No demo. Just sign up." +- "We charge once. You own the thing." +- "Our competitor's pricing page has a button to talk to sales. Ours has a price." + +Cadence: short sentences. Declarative. Contrasts and oppositions ("not X, just Y"). Comfortable with confrontation. Avoids hedging. + +## Component pattern descriptions + +Hero: Oversized headline as the dominant element (80 to 140px). Sub headline below at standard size. 1 to 2 buttons. Often a single bold visual or a horizontal divider in the accent color. + +Buttons: Primary is solid ink or accent on white. Often oversized (56 to 72px height) to match the bold register. Square or low-radius corners (0 to 4px). + +Cards: Sharp corners, heavy border (2 to 3px) or strong shadow, large internal padding. Often the card itself uses contrast (black card with white text, or accent card with black text). + +Tables: Heavy header (black background, white text). Large row height. Bold numerics. + +## When to pick this + +- Launch moments or rebrand moments where the brand needs to reset attention +- Category is full of timid competitors and your brief needs differentiation through volume +- Product confidence is high and the value prop is sharp +- Brand is comfortable being polarizing + +## When to avoid + +- Brand needs to communicate care, gentleness, or expertise-through-restraint +- Audience reads boldness as bro-culture or as insecurity +- Product value is technical and needs space to explain itself +- Brand will be embarrassed by the visual in 18 months (this archetype dates faster than restrained ones) + +## Adaptation guidance + +1. Accent pick: hot pink leans consumer, lime leans tech-edgy, electric blue leans fintech, orange leans general-purpose bold, yellow only with extreme contrast discipline. +2. Display size: do not pull this back to "reasonable." If the hero is 56px, you have made an Editorial Restrained brand instead. Commit to 100px+ or pick a different archetype. +3. Voice: easy to slip into bro-culture. Pull back the swagger by writing honest, not performed. The visual is bold; the voice is direct, not bombastic. +4. Image strategy: pick type-as-visual or one strong photo. Mixed imagery dilutes the impact. +5. Use the contrast: panel-by-panel section transitions are core. A single-color page is not Bold Confident. + +## Exemplar brands + +Bold Confident is exemplified by Loom (current era), Cash App, Robinhood, Mercury (in its recent rebrand), Notion (in product launches), Linear (in major launches), Cloudflare (consumer edge), and Brex. Adjacent older examples include the original Squarespace launch era and the original Mailchimp redesign. + +These brands share: high-contrast palette, oversized display type as visual element, direct voice, panel-based section transitions, one strong accent. + +The archetype often pairs with Technical Precise on developer-tilted brands (the marketing page is Bold Confident; the product surface is Technical Precise). It also overlaps with Vibrant Saturated when the accent is the brand color rather than a supporting note. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md new file mode 100644 index 0000000..3accaa3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md @@ -0,0 +1,114 @@ +# Playful Energetic + +## Aesthetic summary + +Bright multi-color palette. Illustration-led, frequently character-driven. Dynamic, sometimes literally animated. Chunky display type or rounded sans. The brand has a personality, often a recurring character or mascot, and that personality is the primary asset. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Companion +- Sensory ambition: Immersive + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1B1B2A \| Soft-black text \| +\| paper \| #FFFDF7 \| Cream surface \| +\| paper-soft \| #FFF4D6 \| Pastel surface tint \| +\| accent-primary \| #58CC02 \| High-saturation primary (Duolingo green shown) \| +\| accent-secondary \| #FF4B4B \| Bright contrast accent \| +\| accent-tertiary \| #FFC800 \| Sunny yellow \| +\| accent-quaternary \| #1CB0F6 \| Bright sky blue \| +\| accent-quinary \| #CE82FF \| Bright purple \| + +Rationale: +- Multi-hue palette is the signature. Single-accent palettes do not produce Playful Energetic. +- High saturation (often above 80%) across the full palette. Pastel-only is a different archetype (Vibrant Saturated pulled toward soft). +- The palette is calibrated so any two colors can sit next to each other without clashing. This is harder than it looks and requires hue and value discipline. +- Soft black for text (not pure black) keeps the warmth of the palette intact. + +## Type pairing starter + +- Display: Recoleta, Sofia Pro Black, Pangaia, or a chunky humanist serif. Heavy weight, rounded shapes. +- Body: Nunito, Inter, or a rounded humanist sans. 500 to 600. +- Character lettering: Many brands in this archetype use custom wordmark lettering for the brand name itself (Duolingo, Mailchimp, Headspace). The custom mark sits outside the type system. + +Size scale (energetic, with playful proportions): +- Hero: 56 to 80px display (heavy weight) +- H2: 32 to 44px display +- H3: 22 to 28px +- Body: 17 to 19px sans (rounded) +- Small: 14 to 15px + +Pairing rationale: rounded shapes communicate friendliness. Heavy weights communicate playfulness over preciousness. The pairing is "chunky and round" rather than "tall and narrow." + +## Layout and composition + +- Generous use of decorative elements (mascot illustrations, sparkles, shapes, patterns). +- Asymmetric layouts; intentional cheerful imbalance. +- Diagonal motion lines, jaunty rotations on key elements (cards rotated 2 to 4 degrees), bouncy interactions on hover. +- Heavy use of card-based sections with playful borders (heavy, often colored borders rather than hairlines). +- Rounded corners are aggressive (16 to 24px); sharp corners feel wrong in this archetype. + +## Imagery direction + +- Illustration: custom illustration system is the brand's primary visual asset. Often character-driven (mascot has a personality and shows up across surfaces). +- Animation: motion design is core. The mascot moves; cards bounce on hover; loading states have personality. +- Photography: rare. When used, candid and bright, never sterile. +- Stock imagery: forbidden. The archetype requires custom illustration capacity. + +## Voice samples + +- "Hi! It is time for your daily lesson." +- "You did the thing. We are very proud." +- "Skip a day, and the streak ends. We are watching." +- "Two minutes today is better than zero minutes today." +- "Surprise! You earned a badge." +- "Your friend just passed you. Are you going to let that stand?" + +Cadence: short, punchy. First and second person. Comfortable with exclamation marks (but not abuse). Frequent direct address. Humor as a primary tool. Occasional knowing winks at the reader. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 CTA, paired with a large illustration or animated mascot. The illustration is roughly equal weight to the headline rather than supplementary. + +Buttons: Heavily rounded (12 to 20px radius). Often with a 2 to 4px solid bottom border in a darker shade (the "neumorphic toy button" pattern). Bouncy hover animations. + +Cards: 16 to 24px radius, soft drop shadows, often slightly rotated. Sometimes with character illustrations integrated into the card itself. + +Forms: Inputs are oversized, friendly, with playful focus states. Validation errors are gentle ("Hmm, that does not look right" rather than "Invalid input"). + +Loading states: have personality. The mascot waves, bounces, makes a face. Default spinners are missed opportunities in this archetype. + +## When to pick this + +- Consumer apps targeting habit formation, learning, or wellness +- B2B brands intentionally breaking category convention with humor +- Audience appreciates personality over precision +- Brand has illustration budget and willingness to build a character system + +## When to avoid + +- Brand has no illustration budget (this archetype dies on poor illustration) +- Audience reads playfulness as unserious (most enterprise, most developer tools) +- Brand is selling to risk-averse buyers (finance, health, B2B procurement) +- Brand is in a category where competitors are already playful (you will not differentiate) + +## Adaptation guidance + +1. Character commitment: decide early whether the brand has a mascot. Mascot brands need ongoing illustration. Mascot-less playful brands rely on pattern and color systems. +2. Palette discipline: defining 4 to 6 saturated hues that compose together is the hardest part. Spend real time here; the rest of the archetype is downstream. +3. Motion: the archetype needs motion to feel right in product. Static-only execution reads as toy-without-charm. +4. Voice: write to one specific reader, not "users." The archetype falls apart when the voice tries to be funny without commitment. +5. Restraint: even Playful Energetic needs editorial moments. Pages that are 100% playful all the way through exhaust the reader. + +## Exemplar brands + +Playful Energetic is exemplified by Duolingo (the canonical example, with a full character system), Mailchimp in its monkey-mascot era, Headspace, Asana classic era, Liquid Death (visual side), Ben and Jerry's, and MoonPay. Adjacent examples include the Trello mascot era and the original Slackbot personality. + +These brands share: multi-hue saturated palette, custom illustration as primary asset, second-person voice with personality, heavy use of motion, rounded everything. + +The archetype overlaps with Warm Conversational when the illustration is friendly but not character-driven; the difference is that Playful Energetic lets the personality become the brand, while Warm Conversational keeps the human relationship in the foreground. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md new file mode 100644 index 0000000..d97188b --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md @@ -0,0 +1,112 @@ +# Luxe Considered + +## Aesthetic summary + +Serif-led across display and body. Extreme whitespace. Restrained monochromatic palette plus one premium accent. Photography is editorial-grade. Voice is sparse and confident. The brand communicates premium not by saying premium but by behaving premium: in pacing, in spacing, in what it omits. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (formal but not stiff) +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Theatrical + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1A1614 \| Warm near-black \| +\| ink-soft \| #3A332E \| Secondary text \| +\| paper \| #F5F1EA \| Cream off-white background \| +\| paper-warm \| #EDE6D9 \| Warmer cream surface \| +\| accent \| #5C2A26 \| Deep oxblood (alternative: forest #2D4A38, charcoal navy #1F2A40, champagne #C3A87C) \| +\| accent-soft \| #8B4843 \| Active states \| +\| line \| #D9D0BC \| Warm beige border \| + +Rationale: +- Cream and warm-neutral palette is the foundation. Pure white feels cheap in this archetype; cool grays feel corporate. Warmth is the premium signal. +- Single deep accent (oxblood, forest, navy, champagne, deep emerald). Saturation is restrained; the depth of value carries the premium feel. +- No bright colors. Even subtle saturation reads as cheap in this archetype. +- Line color matches paper-warm; lines should be visible but not strong. + +## Type pairing starter + +- Display: Tiempos Headline, GT Super, Reckless, Reforma, or Saol Display. Light to regular weight (300 to 400). +- Body: Tiempos Text, GT Super Text, or Source Serif. Light weight (300 to 400) at comfortable reading size. +- Optional sans: Söhne or GT America at low weight (300) for UI labels and metadata only. + +Size scale (editorial proportions, smaller hero than Bold Confident, larger body than Technical Precise): +- Hero: 48 to 64px serif (light weight) +- H2: 32 to 42px serif +- H3: 22 to 26px serif +- Body: 18 to 20px serif (light weight, comfortable line height) +- Small: 14 to 15px sans + +Pairing rationale: editorial serifs throughout produce the "magazine" feeling. Light weights communicate confidence without aggression. The pairing is rare in B2B (which mostly uses serif display plus sans body) and that rarity is part of the premium signal. + +## Layout and composition + +- Extreme whitespace. Sections separated by 144 to 200px vertical rhythm. +- Often centered or left-aligned with massive horizontal margins on desktop (max content width can run 580 to 720px even on wide screens). +- Asymmetric compositions where the imbalance is intentional and editorial (a 70/30 split with text against a single dominant photograph). +- Minimal UI chrome. Buttons are often text-only with underlines, or thin-bordered, or absent entirely (the call to action is a single line of body copy with a link). +- Page transitions are slow and deliberate. Animations cross-fade rather than slide. + +## Imagery direction + +- Photography: editorial-grade, professionally lit, deliberately styled. Natural light is fine but composition is intentional. Real product, real environment, but elevated. +- Photography is large. Hero images are full-bleed or near-it. The image carries the page. +- Illustration: rare. When used, line-only, sometimes hand-drawn or engraved-feeling. +- Decorative imagery: none. The composition is the visual. +- This archetype requires real photography or excellent stock curation. Bad photo direction kills it instantly. + +## Voice samples + +- "Made from cashmere. From goats that live in places we visit." +- "One garment, one decision." +- "We do not chase trends. We do not need to." +- "Built in 1923. Refined since." +- "If it is not in this collection, it is because it was not ready." +- "The thing we changed was the thread." + +Cadence: short, often fragments. First-person plural ("we") more often than first-person singular. Comfortable with silence. Avoids superlatives ("the best," "the most"); the visual communicates premium without verbal claim. Numbers used sparingly, with deliberate weight when they appear. + +## Component pattern descriptions + +Hero: Single full-bleed photograph or a small serif headline against generous whitespace. No subhead. No CTAs in the visible hero region; the page expects the reader to scroll. + +Buttons: Often text-only with a serif underline, or thin-bordered with serif label. Solid buttons exist but are rare and reserved for primary purchase moments. Padding is generous (16 to 20px vertical). + +Cards: Often no card chrome at all; product is shown on a tinted surface with serif type alongside. When cards exist, they are bordered (1px line color) rather than shadowed, with sharp or low-radius corners (0 to 4px). + +Navigation: Minimal. Often horizontally centered with wide letter spacing. Logo small. The brand does not announce itself loudly. + +## When to pick this + +- Luxury or premium-priced products (above 50 dollars consumer, premium-tier B2B) +- Hospitality, fashion, beauty at price points where the visual must signal value +- Audience explicitly buys premium and is reassured by understated execution +- Brand has the production budget for premium photography + +## When to avoid + +- Brand is competing on price or accessibility +- Audience reads restraint as unfriendly +- Brand has no photography budget (the archetype dies immediately) +- Product is not actually premium (the visual will read as costume) + +## Adaptation guidance + +1. Accent depth: oxblood reads heritage, forest reads sustainability, deep navy reads institutional, champagne reads contemporary luxury. Pick based on brand position. +2. Photography commitment: this is a photography archetype before it is a type archetype. Lock photography direction first. +3. Type weight discipline: light weights (300 to 400) only. Bold serif display pulls the archetype toward Bold Confident. +4. CTA restraint: resist adding obvious buy buttons in hero positions. The archetype expects the reader to discover, not be sold to. +5. Sans usage: keep sans confined to UI labels and metadata. Sans body copy breaks the archetype. + +## Exemplar brands + +Luxe Considered is exemplified by Aesop, Aritzia, Reformation, La Marzocco, Loro Piana, Aman, Bottega Veneta digital, and Stripe Press (in the book design surface). Adjacent examples include the Apple mid-2010s premium product pages, Squarespace's recent rebrands, and the original Goop. + +These brands share: cream and neutral palette, serif-throughout type system, generous whitespace, editorial photography, sparse voice, premium pricing. + +The archetype overlaps with Editorial Restrained (which is the B2B-tilted cousin) and Minimal Essentialist (which strips out the serif entirely). The key difference: Luxe Considered uses the serif and warmth to signal premium; Minimal Essentialist uses absence of ornament to signal premium; Editorial Restrained uses considered ornament to signal trust. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md new file mode 100644 index 0000000..c3bac14 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md @@ -0,0 +1,115 @@ +# Clinical Trustworthy + +## Aesthetic summary + +Cool palette (blue, teal, soft greens) with optional warm accent for humanity. Sans-serif throughout. Clean compositions. Medical or financial register. Photography of products and clinical environments, occasionally real hands and real people in calm contexts. The brand communicates "trust us with something important" without sliding into cold or pharmaceutical. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (calm, knowledgeable, low-affect) +- Aesthetic register: Considered +- Audience relationship: Authority +- Sensory ambition: Functional + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0F2540 \| Deep navy primary \| +\| ink-soft \| #344C68 \| Secondary text \| +\| paper \| #FFFFFF \| White surface \| +\| paper-soft \| #F4F8FB \| Cool tinted surface \| +\| accent-primary \| #2D7FB8 \| Trust blue \| +\| accent-secondary \| #4CA8A0 \| Soft teal \| +\| warm-tone \| #F4B69B \| Optional peach warm accent for humanity \| +\| signal-success \| #2F8F5F \| Calm success green \| +\| line \| #DAE3EC \| Cool gray border \| + +Rationale: +- Cool palette communicates calm authority. Blues and teals are the trust signals; warm tones are optional humanizers, not primary brand colors. +- Trust blue (#2D7FB8) is calibrated to read confident without sliding into corporate cold. Bluer (toward #1976D2) reads more pharmaceutical; teal-shifted reads more wellness. +- The optional warm accent (peach, soft coral) is the single move that distinguishes contemporary Clinical Trustworthy from sterile pharma aesthetic. Without it, the brand reads dated. +- White surfaces. Off-whites and creams pull the archetype toward warmth and away from clinical. + +## Type pairing starter + +- Display: Avenir Next, Circular, Söhne, or GT America. 500 to 700 weight. +- Body: Same family, 400 to 500. Or paired with a soft humanist body (Inter, Source Sans). +- Optional accent serif: A clean serif (Source Serif, Tiempos Text) used sparingly for editorial moments or testimonials. + +Size scale (calm, generous, accessible): +- Hero: 48 to 60px sans +- H2: 30 to 38px sans +- H3: 22 to 24px sans +- Body: 17 to 19px sans (accessible default; this archetype frequently serves older audiences) +- Small: 14 to 15px + +Pairing rationale: geometric sans-serif communicates clinical without medical-sterile. Circular and Avenir specifically have open shapes that read calm rather than clinical. Body sizes run slightly larger because the audience may include older readers and the brand should not require strain. + +## Layout and composition + +- Comfortable density; not as dense as Technical Precise, not as breathing as Luxe Considered. +- Generous internal padding inside cards and forms. Trust is communicated partly through "we are not hurrying you." +- Hero often pairs a clean headline with a calm photograph (a real hand holding a product, a calm clinical environment, a portrait of a doctor or pharmacist). +- Comfortable line lengths (60 to 80 characters per line) and generous line height (1.6 to 1.8). +- Soft drop shadows on cards (gentle elevation, not floating). Rounded corners at moderate radius (8 to 12px). + +## Imagery direction + +- Photography: real hands, real products in real environments. Calm lighting (often natural). Real people who look like the audience. +- Product packaging: shown clearly, frequently against soft tinted backgrounds. +- Illustration: rare; when used, technical diagrams of how something works (a calm anatomical illustration, a process flow with annotations). +- Avoid: aggressive close-ups of medical procedures, stock photos of clinicians in lab coats with crossed arms, hands-only-on-keyboard generic stock. + +## Voice samples + +- "Reviewed by licensed clinicians." +- "Effective ingredients at evidence-backed doses." +- "Same medication. Less hassle." +- "Your doctor will see this report. So will you." +- "We do not bill you for what we do not provide." +- "If it is not safe for you, we will tell you." + +Cadence: complete sentences. Comfortable with first and second person. Calm, qualified, specific. Numbers used carefully (specific doses, specific time-to-response). Avoids superlatives. Compliance-aware writing without being legal-coded. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 to 2 CTAs, paired with a calm photograph. Trust signals (clinician endorsements, FDA mentions, peer-reviewed citations) appear above the fold but understated. + +Buttons: Primary is solid trust-blue or solid ink-navy, white text, 8 to 12px corner radius. Secondary is bordered. Hover states use a slight darkening rather than opacity shift. + +Cards: White or paper-soft surface, 8 to 12px radius, gentle shadow (0 2px 8px rgba(15,37,64,0.06)). Generous internal padding (32 to 40px). Trust signals (clinician credentials, certification marks) frequently appear in cards. + +Forms: Generous field height (48 to 56px). Labels above inputs. Help text below explaining why each piece of information is needed (trust signal: we explain why we ask). + +Trust strip: Common pattern. Logo strip of certifications, regulatory bodies, peer-reviewed citations, or major employers using the product. + +## When to pick this + +- Telehealth, digital health platforms +- Fintech, especially at the trust-needing edge (banking, insurance, investments for older audiences) +- Insurance, retirement, anything where the conversion driver is "trust us with this" +- Health-finance intersection (HSA, healthcare benefits, prescription savings) + +## When to avoid + +- Audience is young and reads clinical as boring or institutional +- Brand needs to communicate energy or excitement +- Category is already dominated by clinical-trustworthy brands (you will disappear) +- Product is not actually substantive enough to support the trust register (the visual will read as costume) + +## Adaptation guidance + +1. Cool to warm balance: pure clinical cool reads pharmaceutical. The optional warm accent (peach, soft coral, butter yellow) is what distinguishes contemporary from dated. +2. Photography: real hands and real environments are the move. Stock photos of "doctor with arms crossed" date the brand immediately. +3. Voice density: write specific. Vague claims in a clinical archetype read as worse than vague claims in a playful one, because the visual is promising specificity. +4. Trust signals: dedicate space to credentials, certifications, citations. Hide them and the archetype is half-built. +5. Density: keep it comfortable. Both too dense and too breathing read as untrustworthy in this archetype. + +## Exemplar brands + +Clinical Trustworthy is exemplified by Hims, Ro, Care/of, Cerebral, Mercury (in finance-trust context), and Stripe (in payment-trust context). Older or adjacent examples include early One Medical, the original Headspace landing surfaces before they leaned playful, and the original Robinhood when it was selling trust over excitement. + +These brands share: cool palette with optional warm humanizer, geometric or humanist sans throughout, real-hand photography, calm voice with specific evidence, generous form fields with help text. + +The archetype frequently splits brands by surface: Clinical Trustworthy for the marketing and conversion surface, with Warm Conversational notes in customer support and post-purchase. The hand-off matters: trust converts, warmth retains. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md new file mode 100644 index 0000000..6690a5f --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md @@ -0,0 +1,115 @@ +# Rugged Utilitarian + +## Aesthetic summary + +Earth tones (clay, olive, charcoal, raw paper). Workwear-influenced type (slab serifs, condensed sans, stencil). Photography of real conditions: outdoor, working, lived-in. Voice is direct and unadorned. The brand reads as built for use rather than for show, and the visual restraint communicates that the product earns its place through function. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (plain, direct, working-class register without affectation) +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #2C2A26 \| Charcoal primary \| +\| paper \| #F0EAD8 \| Raw paper background \| +\| paper-soft \| #E2DAC2 \| Tinted surface \| +\| accent-clay \| #B8543B \| Clay red primary \| +\| accent-olive \| #5C6B3D \| Olive green secondary \| +\| accent-sand \| #C29A60 \| Warm sand tertiary \| +\| accent-charcoal \| #2C2A26 \| Heavy charcoal (alternative primary) \| +\| line \| #A89B7F \| Warm tan border \| + +Rationale: +- Earth tones throughout. The palette is derived from natural pigments: oxide reds, military olives, sun-bleached tans, deep charcoals. +- Saturation is low to medium; nothing in the palette exceeds 60% saturation. Higher saturation pulls toward Bold Confident or Vibrant Saturated. +- The palette reads as outdoor and used. Pure white feels wrong; cool grays feel wrong. Warmth and weight are signature. +- Primary color is often the clay red or charcoal; olive functions as a secondary. The reverse also works. + +## Type pairing starter + +- Display: Druk Condensed, Bebas Neue, Roboto Slab, or a workwear-influenced slab (United Sans Slab, Sentinel). Heavy weight, condensed proportions. +- Body: Inter, Söhne, or a clean humanist sans. 400 to 500. +- Optional accent type: stencil or workshop-influenced display for product callouts and signage moments. + +Size scale (utilitarian, less extreme than Bold Confident): +- Hero: 56 to 80px display +- H2: 32 to 44px display +- H3: 22 to 26px sans +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Numeric mono: 14 to 16px (for spec sheets) + +Pairing rationale: condensed display type feels like signage on industrial equipment, on workwear labels, on shipping crates. Slab serifs feel like surveyor stamps and field guides. Clean humanist sans body keeps the page legible without dressing it up. + +## Layout and composition + +- Functional density. Information shown without softening. +- Heavy use of horizontal rules and labeled sections (the page reads like a spec sheet or field manual). +- Photography is large and full-bleed; the image carries the page. +- Cards are bordered (1 to 2px) rather than shadowed. Corners are sharp or low-radius (0 to 4px). +- Type often allCAPS for labels and section headers (reinforcing the signage register). + +## Imagery direction + +- Photography: real conditions. Real users in real environments. Dirt, sweat, weather, work. Not staged. Natural light dominant; flash photography rare. +- Photography subjects: products in use rather than products on white. The brand wants to show what the product looks like after a season of work, not what it looks like in a studio. +- Illustration: technical diagrams, exploded views, blueprints. Functional rather than decorative. +- Forbidden: pristine product-on-white shots (those belong to Minimal Essentialist or Luxe Considered), happy-family-lifestyle shots (those belong to Warm Conversational). + +## Voice samples + +- "Built to outlast you." +- "If it breaks, send it back. We will fix it." +- "Designed in Bozeman. Tested where it gets cold." +- "We made it heavier on purpose." +- "Spend it on the gear. Save it on the brand." +- "Lifetime guarantee. Read that again." + +Cadence: short. Direct. First-person plural ("we") when the brand speaks. Comfortable with imperative voice. No marketing jargon, no superlatives, no exclamation marks. Honest specifications over emotional appeals. + +## Component pattern descriptions + +Hero: Photograph (full-bleed, real-conditions) with overlaid type, or split layout with text left and photograph right. Headline in display, often condensed or slab. Buttons are direct. + +Buttons: Primary is solid charcoal or clay, white or cream text, sharp or low-radius corners (0 to 4px). Heavy and substantial; never floaty. Often labeled in all caps or with stencil-style lettering. + +Cards: Bordered (1 to 2px line), low-radius, generous internal padding. Often with a labeled header strip (uppercase, condensed) that reads like a product tag. + +Tables: Specification-sheet feel. Labeled rows. Mono numerics. Heavy horizontal rules between sections. + +Product detail: Honest. Materials listed. Construction methods explained. The reader is expected to care about how it is made. + +## When to pick this + +- Outdoor, gear, work-tool products +- Brands where durability and utility are the genuine value proposition +- Audience values function over fashion +- Brand has authentic claim to ruggedness (the brand actually serves people doing the work) + +## When to avoid + +- Brand is not actually utilitarian (the archetype reads as costume when applied to delicate products) +- Audience reads ruggedness as bro-culture or as anti-intellectual +- Brand needs to communicate softness, care, or gentleness +- Brand has no claim to outdoor or work-tool authenticity + +## Adaptation guidance + +1. Authenticity test: if the brand cannot show real photography of real use, this archetype is wrong. Switch to Documentary Honest if real photography is feasible at a different intensity. +2. Palette pick: clay-and-olive feels heritage outdoor (REI, Filson register). Charcoal-and-sand feels industrial workwear (Carhartt, Dickies register). Pick based on category position. +3. Type weight: heavy is non-negotiable. Light or regular weights pull the archetype toward Editorial Restrained. +4. Voice: avoid performed toughness ("BUILT FOR THE GRIND"). Real Rugged Utilitarian voice is matter-of-fact, not bombastic. +5. Specification depth: dedicate page real estate to materials, construction, warranty, repair policy. These are the trust signals. + +## Exemplar brands + +Rugged Utilitarian is exemplified by Patagonia, Carhartt, Yeti, Filson, Snow Peak, Best Made Co (historical), Topo Designs, REI in its product detail surfaces, Stanley (recently), and Hemlock Goods. Adjacent examples include Tom Bihn and Goruck. + +These brands share: earth-tone palette, condensed display or slab serif, real-conditions photography, plainspoken voice, specification depth, lifetime guarantee or repair offering. + +The archetype overlaps with Documentary Honest when photography is the dominant visual; the difference is that Rugged Utilitarian has explicit utility framing (this is for working) while Documentary Honest is about authentic representation more broadly (this is what real life looks like). diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md new file mode 100644 index 0000000..72a07e7 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md @@ -0,0 +1,136 @@ +# Retro Nostalgic + +## Aesthetic summary + +Period-specific palette and type. Intentional vintage reference to a specific era (70s, 80s, 90s, or earlier). Often uses textured or grainy compositions. Voice references the era in cadence or vocabulary. The brand asks the audience to associate it with a felt period rather than with a category, and that association does most of the differentiation work. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Companion +- Sensory ambition: Theatrical + +## Color palette starter + +Three era-keyed palette options. Pick ONE era; do not blend. + +70s palette (warm, earthy, optimistic): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #2A1810 \| Deep brown primary \| +\| paper \| #F4EAD0 \| Cream ground \| +\| accent-orange \| #D2602B \| Burnt orange \| +\| accent-avocado \| #6A7A3A \| Avocado green \| +\| accent-mustard \| #D4A02E \| Harvest gold \| +\| accent-rust \| #8E3F1E \| Deep rust \| + +80s palette (neon, geometric, bold): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0D0D2A \| Deep navy primary \| +\| paper \| #FAF5EF \| Cream surface \| +\| accent-pink \| #FF2D87 \| Hot pink \| +\| accent-cyan \| #18C2D9 \| Electric cyan \| +\| accent-yellow \| #FFD30F \| Saturated yellow \| +\| accent-purple \| #6A2EB8 \| Bold purple \| + +90s palette (muted, grunge-edged, prosumer): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1F1A14 \| Warm dark brown \| +\| paper \| #E8DEC8 \| Aged cream \| +\| accent-rust \| #9C4B2E \| Muted rust \| +\| accent-teal \| #3E7575 \| Faded teal \| +\| accent-yellow \| #C49A35 \| Aged mustard \| +\| accent-purple \| #654273 \| Muted purple \| + +Rationale: +- Each era has a recognizable palette signature. Mixed-era palettes read confused; the audience cannot place the reference. +- The 70s palette is warm and earth-toned, optimistic but not bright. The 80s palette is neon and geometric. The 90s palette is muted, with deliberate aged warmth. +- Pick the era based on the audience's nostalgia moment: 70s for late-30s and older, 80s for late-30s to mid-40s, 90s for late-20s to mid-30s, early 00s for current 20-somethings. + +## Type pairing starter + +Era-keyed type pairings. Pick ONE era. + +- 70s: Cooper Black or VAG Rounded or ITC Bauhaus (display); Cooper or Avenir (body). +- 80s: Eurostile, Avant Garde, or Compacta (display); a clean geometric sans (Avenir, Futura) for body. +- 90s: Trade Gothic, a worn grunge serif (Bureau Grot, Knockout), or a digital-feeling sans (Eurostile) for display; classic sans for body. + +Size scale (varies by era, but generally expressive): +- Hero: 56 to 96px display +- H2: 36 to 48px display +- Body: 16 to 18px sans + +Pairing rationale: type is the era signature. Cooper Black is 70s consumer; Eurostile is 80s tech-future; Trade Gothic worn is 90s grunge. The reader recognizes the era through the type before recognizing it through the color. + +## Layout and composition + +- Era-specific composition styles. 70s leans toward soft asymmetric blocks and groovy curves. 80s leans toward hard geometric grids, oversized type, and Memphis-influenced shapes. 90s leans toward grunge collage, intentional rough edges, and zine-influenced layouts. +- Textures matter: grain, scan lines, paper-aged effects, halftone. Pure digital flat surfaces fight the archetype. +- Iconography is period-keyed: hand-drawn for 70s, geometric for 80s, photocopied-feeling for 90s. + +## Imagery direction + +- Era-keyed photography: warm-tinted and grainy for 70s, neon-lit and high-contrast for 80s, muted and slightly desaturated for 90s. +- Often pairs modern product photography with period-accurate styling (the product is contemporary, but the styling and framing reference the era). +- Pattern: era-accurate decorative elements (sunbursts, stripes, Memphis shapes, halftone dots) are common. + +## Voice samples + +(80s example for an energy drink brand) +- "Soda for people who remember what soda was." +- "From the era when caffeine had personality." +- "Yes, it tastes like that on purpose." +- "Made with cane sugar. Like before." + +(70s example for a wellness brand) +- "Roots, herbs, and a generally chill outlook." +- "Wellness from when wellness was just called feeling good." +- "Brewed the long way. Drunk the slow way." + +Cadence: era-keyed. 70s reads warm and unhurried. 80s reads punchy and confident. 90s reads ironic and self-aware. The voice should evoke the era without quoting it directly. + +## Component pattern descriptions + +Hero: Often centered with oversized era-keyed display type, paired with era-accurate decorative elements (sunburst, Memphis shapes, halftone, scan lines). Background frequently textured. + +Buttons: Era-keyed. 70s buttons are rounded and warm. 80s buttons are geometric and high-contrast. 90s buttons are flat with rough edges or grunge texture. + +Cards: Often with era-specific borders (chunky 70s borders, neon 80s outlines, distressed 90s edges). Background textures common. + +Patterns: Era-keyed pattern systems are common (gingham, paisley, geometric, Memphis, halftone). Used as section backgrounds, packaging, and brand accents. + +## When to pick this + +- F&B challenger brands in commoditized categories (soda, water, snacks) +- Lifestyle brands with a clear era-of-inspiration +- Brands wanting to differentiate in categories crowded with contemporary minimalist competitors +- Brand has clear position on which era and why + +## When to avoid + +- Brand has no genuine connection to the era (the archetype reads as costume) +- Brand needs to communicate forward-looking innovation +- Audience reads the chosen era as embarrassing or dated rather than nostalgic +- Brand cannot commit to the era at production cost (this archetype requires real photography styling and packaging design) + +## Adaptation guidance + +1. Era commitment: pick one era and commit. 70s plus 80s blend reads as confused; the audience cannot place the reference. +2. Texture investment: this archetype requires real textures (grain, halftone, paper aging). Flat digital versions read as contemporary-with-retro-fonts rather than genuinely retro. +3. Voice: avoid direct era quotation ("groovy," "rad," "totally tubular"). The voice should feel like the era, not parody it. +4. Modern functionality: the archetype is visual reference, not functional regression. The website should still work well in 2026; the visual reference is decorative. +5. Photography: era-styled photography is expensive. If budget is limited, lean harder into pattern and type as era carriers. + +## Exemplar brands + +Retro Nostalgic is exemplified by Olipop (70s wellness lean), Liquid Death (80s metal lean), Poppi (90s lean), Recess (70s wellness), Athletic Brewing (early 1900s heritage lean), Magic Spoon (90s cereal lean), and Olly (70s wellness lean). Adjacent examples include Brooklyn Brewery (heritage industrial), Hoxton Hotels (period-specific by property), and Howler Brothers. + +These brands share: era-keyed palette and type, period-specific decorative elements, texture-rich compositions, era-aware voice, packaging design that reads as the period. + +The archetype frequently anchors F&B challenger brands; the era pick is the differentiation strategy within a crowded category. Olipop and Poppi are both in the gut-health soda space; they differentiate primarily through 70s versus 90s era reference. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md new file mode 100644 index 0000000..7bcd522 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md @@ -0,0 +1,111 @@ +# Minimal Essentialist + +## Aesthetic summary + +Black, white, single accent maximum. Sans-serif only. Extreme whitespace. Type-led but at smaller scales than Luxe Considered. Compositions almost sparse to the point of empty. Voice is short and declarative. The brand earns attention by removing rather than adding, and the absence of ornament itself becomes the brand signal. + +## Position on the 4 creative-direction axes + +- Tone register: Professional +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #000000 \| True black primary \| +\| paper \| #FFFFFF \| Pure white \| +\| paper-soft \| #F7F7F7 \| Tinted gray surface (only when needed) \| +\| muted \| #888888 \| Mid-gray for secondary text \| +\| line \| #E5E5E5 \| Hairline separator \| +\| accent \| #FF3B30 \| Optional single accent (red shown; reserve for one use case) \| + +Rationale: +- Pure black and pure white. Off-black or off-white pulls the archetype toward Luxe Considered or Editorial Restrained. +- Single accent if any. Many Minimal Essentialist brands use no accent at all. When used, the accent appears once per page (a single CTA, a single error state, a single quote). +- Gray is the secondary palette. Mid-gray for secondary text, hairline gray for borders. +- No gradients. No tints beyond the gray scale. No color washes. + +## Type pairing starter + +- Display and body: One sans-serif family across all surfaces. Helvetica Now, Söhne, GT America, Inter, or Suisse Int'l. Multiple weights (300 to 700) carry the hierarchy. +- Optional secondary: Sometimes the same family in a tightly-set condensed cut for labels or navigation. + +Size scale (modest contrast, hierarchy through weight more than size): +- Hero: 40 to 56px sans (smaller than Bold Confident; the hero does not need to shout) +- H2: 28 to 36px sans +- H3: 20 to 24px sans +- Body: 16 to 17px sans +- Small: 13 to 14px sans + +Pairing rationale: one family across the system reinforces the discipline. Hierarchy is communicated through weight, size, and color rather than through type pairing. Neo-grotesque sans (Helvetica, Söhne, Suisse) feel pure; geometric sans (Avenir, Circular) feel slightly warmer; humanist sans (GT America, Inter) feel slightly friendlier. Pick based on the temperature you want. + +## Layout and composition + +- Extreme whitespace, but at smaller scale than Luxe Considered. The page reads as efficient rather than ceremonial. +- Often a strict grid: 12-column desktop with deliberate column spans. Asymmetry less frequent than in Editorial Restrained. +- Type-led: type sits in space rather than being framed by photography or color blocks. +- Cards are rare. Content sits directly on the page surface with hairline separators rather than card containers. +- Sharp corners (0 to 2px). Curves feel wrong in this archetype. + +## Imagery direction + +- Photography: product on white. Studio-lit. Considered. No styling beyond the product itself. +- People photography: rare. When used, portraits against neutral backgrounds, minimal styling. +- Illustration: extremely rare. Diagrams in line-only black-on-white if at all. +- Decorative imagery: none. The whitespace is the decoration. + +## Voice samples + +- "One mattress. One price." +- "We make the product. We tell you how it works. You decide." +- "The product is described accurately on the product page." +- "Returns within 100 days. No questions." +- "There is no enterprise tier." +- "The cheapest plan is the only plan." + +Cadence: very short. Declarative. First-person plural ("we") common. Numbers when relevant; otherwise sparse. The voice is honest to the point of dryness. No salesmanship, no superlatives, no hedging. + +## Component pattern descriptions + +Hero: Headline plus subhead plus single CTA. Often centered or hard left-aligned. Sometimes paired with a single product photograph against white; often with no imagery at all. + +Buttons: Solid black, white text, or solid white with black border. Sharp corners or 2 to 4px radius. Single CTA per section. + +Cards: Rare. When present: hairline border (1px line gray), no shadow, sharp corners, minimal internal styling. + +Tables: Hairline rows. Sans body throughout (no mono). Left-aligned text, right-aligned numerics. + +Navigation: Minimal. Logo (often wordmark only), a small number of nav items, a single CTA. No mega-menus, no drawer animations, no decorative chrome. + +## When to pick this + +- Brand wants to communicate timelessness or rigor +- Product is design-focused and the audience appreciates restraint as a value signal +- Brand is competing in a category where every competitor is ornamented; restraint is the differentiator +- Brand can defend the discipline (saying no to internal requests to add color, illustration, ornament) + +## When to avoid + +- Brand has rich content that benefits from visual organization (the archetype's lack of cards and color makes dense content hard to scan) +- Audience reads minimalism as cold or unwelcoming +- Brand needs to communicate warmth, personality, or specific human values +- Brand will eventually be tempted to add ornament (better to start in a more flexible archetype) + +## Adaptation guidance + +1. Discipline is the brand: this archetype requires institutional commitment to saying no. Adding decoration over time degrades the archetype faster than other archetypes. +2. Type family pick: Helvetica reads neutral and Swiss; Söhne reads contemporary and sharp; Suisse reads precise and minimal; Inter reads accessible and modern. Pick based on temperature, not novelty. +3. Color discipline: black plus white plus one accent maximum. Brands that "just add one more color" frequently undermine the archetype. +4. Photography: product-on-white only. Lifestyle photography pulls toward Warm Conversational or Luxe Considered. +5. Voice: write honest, not poetic. Minimal Essentialist voice that tries to be evocative reads as Luxe Considered; minimal voice that is too plain reads as Editorial Restrained. + +## Exemplar brands + +Minimal Essentialist is exemplified by Apple at its most restrained (mid-2010s product pages), Allbirds at launch, Muji, Casper at launch, Everlane, Squarespace (in its minimal era), The Ordinary, and Aritzia in product detail pages. Adjacent examples include Dieter Rams' principles applied to digital and the early Medium publication system. + +These brands share: black-white-plus-accent, single sans family, extreme whitespace, product-on-white photography, terse declarative voice, no decorative ornament. + +The archetype differs from Editorial Restrained primarily in the absence of serif type and the absence of warm paper backgrounds. Editorial Restrained allows serif display and warm cream; Minimal Essentialist eliminates both. Brands frequently start Minimal Essentialist at launch and migrate toward Warm Conversational or Editorial Restrained as the audience matures and the brand needs more content depth. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md new file mode 100644 index 0000000..0484151 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md @@ -0,0 +1,112 @@ +# Vibrant Saturated + +## Aesthetic summary + +High saturation across the full palette. Color used as primary brand expression. Type often plays second to color. Compositions are color-blocked. Voice is energetic and personality-driven. The brand makes color the primary asset, and the audience remembers the brand by hue before they remember the wordmark. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Performer +- Sensory ambition: Immersive + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #181818 \| Soft-black text \| +\| paper \| #FFFFFF \| White surface \| +\| accent-primary \| #FE2D81 \| Saturated brand pink \| +\| accent-secondary \| #2BC8F4 \| Bright cyan \| +\| accent-tertiary \| #FFD426 \| Saturated yellow \| +\| accent-quaternary \| #8B3DFF \| Vivid purple \| +\| accent-quinary \| #21D17C \| Bright green \| +\| signal \| varies \| Color-blocking accents derived from the palette \| + +Rationale: +- Multi-hue saturated palette is the signature. Single-accent palettes do not produce Vibrant Saturated. +- Saturation generally above 70% across the palette. The discipline is that all colors are at similar saturation; this is what produces palette coherence despite hue variety. +- Pure white surfaces. Cream and warm-white pull the archetype toward Warm Conversational. +- The palette is calibrated so any two colors can sit next to each other. This requires hue and value discipline; brands that wing it produce chaos rather than coherent vibrancy. + +## Type pairing starter + +- Display: A clean geometric or neo-grotesque sans (Söhne, GT America, Helvetica Now, or a brand-custom face). 600 to 800 weight. +- Body: Same family, 400 to 500. +- Optional serif: A clean serif (Source Serif, Tiempos Text) for editorial moments. Used sparingly. + +Size scale (color carries the page; type is competent rather than expressive): +- Hero: 48 to 64px sans +- H2: 32 to 40px sans +- Body: 16 to 18px sans +- Small: 14 to 15px + +Pairing rationale: the type is intentionally calmer than the color. Going expressive on both type and color produces visual chaos; one element carries the personality while the other carries the functional load. In Vibrant Saturated, color carries personality and type carries function. + +## Layout and composition + +- Color-blocked compositions are signature. Sections alternate full-bleed background colors; the page reads as panels. +- Heavy use of color as section organizer. The brand may use 6 different colors across a single page, each demarcating a different content type. +- Type sits in color fields rather than on white. White-on-saturated and dark-on-light alternate. +- Rounded corners are common but not aggressive (8 to 16px). +- Motion design uses color transitions (sections fade between hues on scroll, hover states shift hue). + +## Imagery direction + +- Photography: high-saturation, often product-on-color-block, sometimes graphic-treated. +- Illustration: brand-custom illustration systems often appear, with the brand's color palette as the discipline. +- Pattern: bold pattern systems common, using the brand palette. +- Product UI: shown against brand-color backgrounds rather than neutral surfaces. The product takes on the brand's color identity. + +## Voice samples + +- "Music for whatever you're feeling. All of it. Right now." +- "The good news: this works. The better news: you do not have to figure it out." +- "Yes, we are different. That is the point." +- "Press play. We will handle the rest." +- "Built for people who pick a color and commit." + +Cadence: energetic. First and second person. Comfortable with personality. Direct address. Numbers used playfully ("100 percent honest, 0 percent boring"). The voice is the spoken version of the visual energy. + +## Component pattern descriptions + +Hero: Often a single dominant brand color as background, with white type and a contrasting accent CTA. Sometimes split between two brand colors. The hero is the color, not the photograph. + +Buttons: Solid brand color, contrast text. 8 to 16px radius. Buttons may use one of several brand colors depending on context (the CTA color signals the section's purpose). + +Cards: Often colored rather than white. Each card may use a different brand color, with the color carrying meaning (category, type, status). 12 to 16px radius. + +Sections: Strong color demarcation. Section A is pink-on-white; Section B is cyan-on-white; Section C is yellow-on-dark. The reader navigates by color. + +Patterns and shapes: Common as section dividers and decorative accents. Always within the brand palette. + +## When to pick this + +- Consumer apps with strong category brands +- B2B brands targeting prosumer or creator audiences +- Brands where memorability through color is the strategy +- Brand has color system design discipline (this archetype is harder than it looks) + +## When to avoid + +- B2B brand targeting risk-averse buyers +- Brand cannot commit to color system discipline (winging it produces chaos) +- Brand needs to communicate seriousness or rigor as primary signals +- Category is already crowded with vibrant brands + +## Adaptation guidance + +1. Palette discipline first: defining 4 to 6 saturated hues that compose together is the hardest part of this archetype. Spend real time here; the rest is downstream. +2. Saturation calibration: keep all colors at similar saturation. Mixed high-saturation and low-saturation produces incoherence. +3. Type restraint: the type should not also be expressive. Clean type plus expressive color is the formula; expressive type plus expressive color is chaos. +4. Color carries meaning: in the strongest applications of this archetype, color is functional (different colors signal different content types). Use this rather than decorative color. +5. Accessibility: contrast ratios must work despite saturated palette. Test every color combination against WCAG AA at minimum. + +## Exemplar brands + +Vibrant Saturated is exemplified by Glossier (with restraint), Spotify, Notion (in its color-era brand expressions), Headspace (overlaps with Playful Energetic), Wise, Klarna, Bumble, and Patreon. Adjacent examples include the Slack rebrand era and the early Stripe consumer-facing surfaces. + +These brands share: multi-hue saturated palette, clean sans type, color-blocked compositions, color as section organizer, expressive but not chaotic compositions. + +The archetype overlaps with Playful Energetic when illustration becomes the dominant element; the difference is that Vibrant Saturated is color-first while Playful Energetic is character-first. Spotify is Vibrant Saturated; Duolingo is Playful Energetic. Both are colorful; the dominance pattern is what distinguishes them. diff --git a/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md new file mode 100644 index 0000000..183c053 --- /dev/null +++ b/dist/pi/.agents/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md @@ -0,0 +1,111 @@ +# Documentary Honest + +## Aesthetic summary + +Photography-first. Real people in real conditions. Low touch on imagery. Type recedes to let imagery lead. Compositions are large and image-dominant. Voice is direct and journalistic. The brand uses honest representation as its primary asset, and the visual restraint signals that the product or experience is the real thing rather than the constructed thing. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1B1B1B \| Near-black text \| +\| paper \| #FAFAF8 \| Off-white surface \| +\| paper-soft \| #F0EFEB \| Subtle tinted surface \| +\| accent \| varies by imagery \| Pulled from dominant photography tones \| +\| muted \| #5C5C5A \| Mid-gray for metadata \| +\| line \| #E2E0DA \| Soft line color \| + +Rationale: +- The palette derives from photography rather than being imposed on photography. Each brand expression of this archetype has a distinct accent because the accent comes from the imagery world. +- Off-white surfaces with subtle warmth; the photography sits on the page rather than being framed by aggressive surfaces. +- Mid-gray secondary text reads as caption-feeling rather than UI-feeling. +- Saturation throughout the palette is low; photographs may be saturated, but the surrounding UI is muted to let imagery be the contrast. + +## Type pairing starter + +- Display: A clean serif (Tiempos Headline, Source Serif, GT Sectra) or a humanist sans (GT America, Söhne, Inter Display). 500 to 700. +- Body: Same family or matched body weight, 400 to 500. +- Caption type: A subtle italic or smaller weight for image captions and metadata, often in muted gray. + +Size scale (modest, deferential to imagery): +- Hero: 36 to 48px (smaller than most archetypes; the photograph carries hero weight, not type) +- H2: 26 to 32px +- Body: 17 to 19px (comfortable reading) +- Caption: 14 to 15px italic or in muted gray + +Pairing rationale: type sits in service of imagery. Restrained scale and weight let the photograph dominate. Italic captions read journalistic, evoking magazine and newspaper conventions. Either serif or sans works; the pairing should be calm. + +## Layout and composition + +- Photography is large and frequently full-bleed. The image occupies more page real estate than the type. +- Compositions reference editorial design: photograph with caption, photograph with pull quote, photograph plus body text. +- Asymmetric layouts where the image leads and text follows. Often 60/40 splits with photography dominant. +- Generous internal padding around text blocks. The text breathes within the layout. +- Hover states are subtle. The page reads as a document rather than as an interface. + +## Imagery direction + +- Real people, real environments, real conditions. Candid more often than posed. +- Natural light dominant. Studio lighting rare and intentional when used. +- Documentary photography conventions: telephoto compression for environmental portraits, wide-angle for context shots, intentional grain accepted. +- The archetype assumes investment in photography. Stock imagery undermines the archetype immediately. +- Photo direction matters more than photo quantity. A few exceptional images carry the archetype better than many adequate ones. + +## Voice samples + +- "She has been on the trail for six days. Today is the first day she has had warm feet." +- "We met him in the workshop where he learned the trade. He has worked there for 31 years." +- "Three thousand miles. Six time zones. One bag." +- "Built in Vermont. Tested in places where bad gear ends careers." +- "This is what we did. These are the people we did it with. These are the results." + +Cadence: journalistic. Third-person more often than first. Comfortable with specificity (real dates, real durations, real names where appropriate). The voice reads as reporting rather than selling. + +## Component pattern descriptions + +Hero: Large photograph (full-bleed or near-it) with overlaid restrained type, or photograph above type-only headline section. The photograph IS the hero. + +Buttons: Restrained. Often text-only with underlines, or thin-bordered with calm labels. The buttons recede; the photography leads. + +Cards: Often a card is a photograph plus caption plus body excerpt. The card structure mirrors editorial conventions (photo, caption, headline, dek). + +Quotes: Pulled quotes are a recurring pattern, set in restrained type with attribution beneath. + +Sequences: This archetype frequently uses image sequences (3 to 6 photographs telling a small story) where most archetypes use a single hero image. + +## When to pick this + +- Travel, hospitality, lifestyle brands where the experience IS the value proposition +- Journalism-adjacent brands (publications, archives, documentary work) +- Brands where real stories are the differentiation +- Brand has access to genuine documentary photography (either custom or excellently curated) + +## When to avoid + +- Brand has no real photography access or budget +- Product is functional rather than experiential +- Audience expects highly designed marketing rather than journalistic restraint +- Category is built on aspiration rather than reality (Documentary Honest fights aspirational positioning by definition) + +## Adaptation guidance + +1. Photography commitment: this is a photography archetype before it is anything else. If photography is going to be stock or poorly art-directed, switch archetypes. +2. Voice register: write journalistic, not marketing. Documentary Honest voice that slides into "we are passionate about" undermines the archetype. +3. Restraint discipline: resist adding decorative elements, color accents, or pattern. The photography is the visual; everything else should recede. +4. Caption discipline: captions are first-class content. They carry the story alongside the image. Treat them with the same care as headlines. +5. Authenticity test: the brand should be able to defend each photograph with a real story. Generic stock-feeling images destroy the archetype. + +## Exemplar brands + +Documentary Honest is exemplified by Airbnb (in its early marketing surfaces), Patagonia (overlaps with Rugged Utilitarian), Outside Magazine, The New York Times' visual journalism work, REI in its editorial content, Selina, and Yeti (in its long-form brand content). Adjacent examples include Field Mag, Topo Designs in long-form marketing, and Filson's historical archives. + +These brands share: real photography as primary visual, restrained type system, journalistic voice, image-plus-caption editorial conventions, low-saturation palette derived from imagery. + +The archetype overlaps with Rugged Utilitarian (both rely on real photography) and Editorial Restrained (both rely on restrained type). The difference: Rugged Utilitarian has utility framing (this is for working); Editorial Restrained is institutional confidence applied to B2B; Documentary Honest is honest representation applied to experience and story. diff --git a/dist/pi/.agents/skills/brand-discovery/SKILL.md b/dist/pi/.agents/skills/brand-discovery/SKILL.md new file mode 100644 index 0000000..3829f09 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/SKILL.md @@ -0,0 +1,197 @@ +--- +name: brand-discovery +description: "Run upstream brand discovery covering audience research, competitive landscape, category dynamics, problem space, and positioning territory exploration. Use this skill at the very start of a brand or website project when the user needs to understand who they're for, who they compete with, what the audience actually needs, and where the brand could plausibly stand. Triggers on brand discovery, audience research, market research, competitive scan, category research, customer research, who is this for, who are we, positioning research, intake, kickoff. Also triggers when a creative brief is requested but the upstream inputs (audience, competitors, problem space) are not yet clear." +category: strategy-and-discovery +catalog_summary: "Audience research, competitive scan, positioning territory exploration" +display_order: 1 +--- + +# Brand Discovery + +Upstream of every brief, identity, and content plan. Discovery answers four questions: who the brand is for, what they need, who else is competing for that need, and where the brand could plausibly stand that competitors do not. + +--- + +## When to use + +- The very first phase of a new brand or website project +- Understanding an audience before any creative work begins +- Mapping competitors and category dynamics +- Surfacing the problem space the brand will operate in +- Generating positioning territories before brief or ideation +- When a creative brief was requested but the inputs are missing + +## When NOT to use + +- The audience and category are already well-understood (jump to `creative-brief` or `brand-ideation`) +- Validating a specific design or feature with users (use `usability-testing`) +- Mapping the customer journey of an existing audience (use `journey-mapping`) +- Generating brand names or visual directions (use `brand-ideation`) + +--- + +## Required inputs + +- The product, service, or organization being branded +- Whatever is already known about the audience and category (often very little) +- Access to existing materials (sales calls, support tickets, reviews, analytics) +- Any constraints (parent brand, regulatory, geographic) +- A timeline (a 1-week discovery looks different than a 6-week one) + +--- + +## The framework: 4 dimensions + +Discovery covers four dimensions. Each has its own sources, methods, and outputs. + +### 1. Audience + +Who specifically does this serve? + +Layers to surface: + +- Demographic: Age range, geography, language, life stage, income (only if relevant; do not over-collect demographics) +- Psychographic: Values, motivations, beliefs, fears +- Behavioral: What they currently do to address the problem, what tools they use, where they spend time online and offline +- Jobs-to-be-done: The functional, emotional, and social jobs they hire a brand to perform + +Sources: + +- Existing customer interviews (5 to 8 ideal) +- Sales call recordings or transcripts +- Support ticket themes +- Review and forum analysis (Reddit, Trustpilot, App Store, niche communities) +- First-party analytics (search console queries, on-site search, top pages) +- Social listening (what they post about the category) + +Output: 1 to 3 named audience segments, each with a one-page profile. + +### 2. Competitors + +Who else competes for the same audience and need? + +Three layers of competitor: + +- Direct: Solves the same problem the same way (e.g., another SaaS in the category) +- Indirect: Solves the same problem a different way (e.g., a spreadsheet replacing a SaaS tool) +- Status quo: Doing nothing, doing it manually, or living with the problem + +The third is most often forgotten and most often the actual competitor. + +Per competitor, document: + +- Who they target (audience overlap with you) +- How they position (what they claim to be) +- What they actually deliver (often different from positioning) +- Pricing model and structure +- Strengths and weaknesses from the audience's perspective +- Recent moves (launches, pivots, hires, departures) + +Sources: + +- Their own website and marketing +- Reviews of their product or service +- Their content and SEO presence (use `seo-competitor` for the search angle) +- Social proof and customer voices + +Competitive scan benefits from quantitative grounding: not just "who are the competitors" but "how much traffic do they earn, where does it come from, who is the audience overlap." Similarweb is the standard for this kind of competitive landscape analysis; pair with Ahrefs for the SEO-specific overlap. + +Output: Competitor matrix (3 to 8 competitors deep), plus a one-line "what makes them dangerous" for each. + +### 3. Category and problem space + +What is the broader context this brand operates in? + +Map: + +- The problem. What is the actual user problem? Not the surface symptom, the underlying job to be done. +- The category. How is the category structured? Is it new, mature, fragmenting, consolidating? +- The conventions. What does every brand in the category do the same way? (These are the conventions you can break.) +- The shifts. What is changing in the category? Technology, regulation, audience behavior, distribution. +- The moats. What protects incumbents? Brand, distribution, network effects, switching costs? +- The vocabulary. What language does the category use? What is jargon, what is meaningful, what is empty? + +Sources: + +- Industry reports and analyst coverage +- Trade publications and conferences +- Adjacent category observations +- Customer language vs. category language (the gap is informative) + +Output: A category map and a list of conventions to consider breaking (or keeping deliberately). + +### 4. Positioning territory + +Given the audience, competitors, and category, where could this brand plausibly stand? + +This is not yet "the positioning." Discovery surfaces possible territories. `brand-ideation` narrows them and commits. + +Generate territories from: + +- Underserved audience segments (audiences others ignore) +- Underserved jobs (jobs the category does not do well) +- Category convention violations (what would happen if you broke the rules everyone follows) +- Honest brand truths (what is genuinely true about this brand that competitors cannot also claim) +- Category shifts (where the puck is going) + +Per territory, document: + +- The statement (one sentence) +- Why it could work (proof point) +- Who would resonate (the audience for this territory) +- Who is competing in this territory (often, no one good) +- Risk (what makes it fragile) + +Output: 3 to 5 distinct territories. Not yet committed. Inputs to `brand-ideation`. + +--- + +## Workflow + +1. Define the discovery scope. 1 week for a startup pre-launch. 4 to 6 weeks for a major rebrand. Set expectations. +2. Audit existing inputs. Sales calls, support tickets, reviews, analytics, internal docs. Often more is known than people think. +3. Audience research. 5 to 8 interviews if possible. Plus secondary research from review and forum analysis. +4. Competitor mapping. 3 to 8 competitors deep, including indirect and status-quo competitors. +5. Category mapping. Conventions, shifts, vocabulary, moats. +6. Territory generation. 3 to 5 plausible positioning territories. +7. Write the discovery report. Use the template in [`references/discovery-report-template.md`](references/discovery-report-template.md). +8. Hand off to next phase. Discovery feeds into `creative-brief`, `brand-ideation`, or `content-strategy` depending on where the project goes next. + +--- + +## Failure patterns + +- Skipping discovery to "save time." Every shortcut here costs 10x downstream when the brand fails to land. +- Audience research that confirms what you already believe. If your audience research validates every assumption, you did not actually research. Look for surprises. +- Demographic-heavy audience profiles. "Women aged 25 to 45" is not insight. Behavior, beliefs, and jobs-to-be-done are. +- Listing every competitor as if equal. Most competitors do not matter. Pick the 3 that are genuinely dangerous. +- Forgetting status-quo as competition. The biggest competitor is usually "doing nothing" or "doing it manually." +- Outputting territories without rejection criteria. A territory without a "what this rejects" is not a territory. +- Treating discovery as a one-time event. Categories shift. Audiences evolve. Re-run discovery at least every 3 years. + +--- + +## Output format + +Default output is a discovery report at `discovery-report.md` plus appendices. + +Structure: +1. Executive summary (5 to 10 bullets) +2. Audience (1 to 3 named segments with profiles) +3. Competitors (matrix and per-competitor analysis) +4. Category and problem space +5. Positioning territories (3 to 5 candidates) +6. Implications and recommendations +7. Open questions that require further research + +Appendices: +- Interview notes (sanitized) +- Competitor research data +- Source list + +--- + +## Reference files + +- [`references/discovery-report-template.md`](references/discovery-report-template.md) - Full discovery report template. +- [`references/interview-guide.md`](references/interview-guide.md) - Audience interview guide with question prompts. diff --git a/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md b/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md new file mode 100644 index 0000000..68844e7 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/references/discovery-report-template.md @@ -0,0 +1,177 @@ +# Brand Discovery Report Template + +A fillable template for the discovery deliverable. The discovery report is what every later phase of brand work references. If a section is thin, later phases will be too. + +Fill every section. If a section is "N/A", say why explicitly. + +--- + +## Project metadata + +Brand / project: [Name] +Phase: [Initial discovery / refresh / repositioning] +Date: [YYYY-MM-DD] +Lead: [Name] +Stakeholders interviewed: [Names and roles] +Customers interviewed: [Number, segments] + +--- + +## Executive summary + +Three to five sentences. The single most important thing the discovery surfaced, the strongest opportunity, and the biggest risk. + +> [Summary] + +--- + +## Audience + +### Primary audience + +Who they are: [Demographic and behavioral picture. Not a persona archetype. Real, specific, current.] + +What they want: [The job they hire the category to do. Surface and underlying.] + +What they fear or doubt: [Objections, hesitations, alternative options being considered.] + +Where they are: [Channels, communities, sources of trust.] + +Quotes (verbatim from interviews): + +> "[Verbatim quote that reveals motivation or pain]" - [Segment] +> "[Verbatim quote]" - [Segment] +> "[Verbatim quote]" - [Segment] + +### Secondary audience(s) + +[Only include if they materially shape the work. Otherwise note "none material" and move on.] + +--- + +## Category and competition + +### The category as the audience sees it + +What the audience calls this category. What they group us with. (Often different from how the company sees it.) + +### Direct competitors + +\| Competitor \| Position they hold \| Strength \| Weakness \| Opportunity for us \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| +\| \| \| \| \| \| + +### Indirect / adjacent + +[Substitutes the audience considers, even if not in the same product category.] + +### Reference brands (aspirational) + +[Brands the audience admires that we want to be associated with - same audience, different category.] + +--- + +## Positioning territory + +### What we found + +The discovery process should produce 2 to 4 candidate positioning territories. Each is a defensible space the brand could own. + +#### Territory 1: [Name] + +- Core idea: [One sentence] +- Why it could work: [Audience need it serves, gap in competition, asset we have] +- Why it could fail: [Risk, what would have to be true] +- What it would look like: [How marketing, product, copy would feel under this territory] +- Evidence from research: [Specific findings that support this] + +#### Territory 2: [Name] + +[Same structure] + +#### Territory 3: [Name] + +[Same structure] + +### Recommendation + +The discovery report is allowed to recommend one. Make the case. Or explicitly punt: "Run a positioning workshop with these four candidates." + +--- + +## Brand truths + +What the discovery surfaced about who this brand actually is, not what marketing has been saying. + +### What is true + +- [Fact about the company, founders, product, or community that is real and ownable] +- [Fact] +- [Fact] + +### What is aspirational (and that is OK) + +- [Thing we want to be that we are not yet, but are credibly working toward] +- [Thing] + +### What is not true (and stop saying) + +- [Claim the company makes that did not survive scrutiny] +- [Claim] + +--- + +## Strategic implications + +What the discovery means for the work ahead. + +### For brand identity + +- [Implication, e.g., "The visual direction should signal quietness, not loudness; the audience is exhausted by category noise."] + +### For brand voice + +- [Implication, e.g., "Voice should be confident without being clever; the audience equates cleverness with sales pressure."] + +### For product + +- [Implication if discovery surfaced product-level gaps or strengths] + +### For marketing + +- [Implication for channel strategy, content focus, message hierarchy] + +--- + +## Open questions + +Things discovery raised that it did not answer. These belong in the next phase. + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Methodology and sources + +- Stakeholder interviews: [Number, role mix, format] +- Customer interviews: [Number, segment mix, format] +- Customer surveys: [Sample size, response rate] +- Competitive scan: [Number of brands, depth of review] +- Search and social listening: [Sources, time window] +- Internal docs reviewed: [Strategy decks, prior research] +- Caveats: [What this discovery did not cover, sample limitations] + +--- + +## Sign-off + +Discovery accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand ideation / positioning workshop / direct to identity / etc.] diff --git a/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md b/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md new file mode 100644 index 0000000..340ee32 --- /dev/null +++ b/dist/pi/.agents/skills/brand-discovery/references/interview-guide.md @@ -0,0 +1,193 @@ +# Audience Interview Guide + +A guide for conducting 30 to 45 minute interviews with current customers, prospects, or audience members during brand discovery. + +The goal of interviews is not to validate assumptions. It is to find surprises. Plan to be wrong about most of what you think you know. + +--- + +## Before the interview + +### Who to interview + +For a typical brand discovery, talk to 5 to 8 people across these segments: + +- Active customers who have been using the product for 3+ months (deep understanding) +- Recent customers who joined in the last 30 days (still remember the buying journey) +- Lapsed customers who churned (the most informative; understand why people leave) +- Prospects who didn't buy (understand objections) +- Power users in adjacent categories (understand alternatives and substitutes) + +If the project is for a new brand with no customers yet, interview members of the target audience using competitive products or substitutes. + +### Recruiting + +Recruit through: +- Customer email list with a thank-you incentive +- Sales team referrals +- LinkedIn outreach to titles matching the audience profile +- Existing user research panels +- Niche communities (Reddit, niche Slack groups, professional forums) + +Compensate participants. $50 to $100 in cash or product credit is reasonable for 30 minutes. + +### Logistics + +- 30 to 45 minutes is the right length. Longer fatigues both sides. +- Record (with consent). Take notes too in case the recording fails. +- Use a video tool that creates transcripts automatically. +- Send a calendar invite with a clear agenda. +- Confirm the day before. + +--- + +## Question framework + +Structure interviews in three sections: their world, the problem, and how they currently solve it. + +### Opening (3 to 5 minutes) + +Get them talking. Build rapport. Establish that there are no wrong answers. + +- "Tell me a bit about yourself and what you do." +- "Walk me through a typical day. What does work look like?" +- "How long have you been doing this kind of work?" + +These warm-up questions also surface context you'll need later. + +### Section 1: Their world (10 minutes) + +Understand the context the brand fits into. + +- "When you think about [the problem area or category], what comes to mind?" +- "What's the part of your work or life this connects to?" +- "How important is [the problem area] in the bigger picture of what you do?" +- "Who else is involved in [the problem area]? Coworkers? Family? Clients?" +- "What's the goal you're trying to hit in this area?" + +Listen for: priorities, stakeholders, vocabulary, time pressure. + +### Section 2: The problem (10 to 15 minutes) + +Surface the actual problem, not the surface symptom. + +- "Tell me about the last time you ran into [the problem]. Walk me through what happened." +- "What was frustrating about that?" +- "What did you try to do about it?" +- "What did you wish had happened instead?" +- "What's the cost of this problem? Time? Money? Stress? Relationships?" +- "Have you ever just decided to live with it instead of solving it? Why?" + +Listen for: emotional weight, the real cost, the workarounds people invent, the resignation. + +The key follow-up: "Tell me more about that." Use it relentlessly. Most insight is one or two layers below the first answer. + +### Section 3: How they solve it now (10 to 15 minutes) + +Understand the current toolkit and the alternatives considered. + +- "What do you currently use to address [the problem]?" +- "How did you start using [their current solution]? What were you using before?" +- "What did you consider but not pick? Why not?" +- "What do you wish [your current solution] did better?" +- "If you could wave a magic wand and have [the problem] solved perfectly, what would that look like?" +- "Imagine a tool came along that promised to solve [the problem]. What would it have to be true for you to switch?" + +Listen for: the switching cost, the unmet needs, the specific moments where current solutions fail. + +### Closing (3 to 5 minutes) + +- "Is there anything I should have asked but didn't?" +- "Is there anyone else you think I should talk to about this?" +- "Would you be open to a follow-up if questions come up later?" + +--- + +## Common interview pitfalls + +### Leading questions + +Bad: "Do you find it frustrating when [your assumption]?" + +Better: "Tell me about your last experience with [the activity]." + +The first question telegraphs the answer you want. The second lets them tell you what was actually frustrating, including things you didn't predict. + +### Asking for solutions + +Bad: "What features would you want in [the product]?" + +Better: "What's frustrating about how this works today?" + +Users are not product designers. They are the world's leading experts on their own frustrations. Mine the frustrations; you'll design the solutions. + +### Validating instead of investigating + +Bad: "Would you use [feature description]?" + +Better: "When was the last time you needed something like that? What did you do?" + +Hypothetical answers are useless. Past behavior is informative. + +### Closed questions + +Bad: "Was that frustrating?" + +Better: "How did you feel about that?" + +Yes/no questions kill the conversation. Open questions keep it going. + +### Talking too much + +If you're talking more than 20 percent of the time, you're talking too much. Your job is to listen, follow up, and get out of the way. + +--- + +## Synthesis + +After all interviews, synthesize across them. + +### Step 1: Tag the transcripts + +Read every transcript. Tag passages by theme: +- Pain points +- Workarounds +- Aspirations +- Vocabulary they use +- Emotional moments +- Surprising statements + +### Step 2: Identify recurring patterns + +A theme that appears in 3+ interviews is signal. A theme in 1 interview is interesting but anecdotal. + +### Step 3: Look for surprises + +The most valuable findings are things you didn't expect. List them explicitly. These often become the basis for distinctive positioning. + +### Step 4: Identify quotes + +The right quote captures more than a paragraph of synthesis. Pull 5 to 10 quotes that capture the core insights. + +### Step 5: Write the audience section of the discovery report + +For each segment: +- Who they are (with the specificity you've earned) +- What they're trying to do +- What's getting in the way +- How they currently solve it +- What they wish were different +- Anchor quote (one strong verbatim quote) + +--- + +## What to avoid + +- Treating the interview as a sales pitch +- Asking about your specific product or feature ideas (validation theater) +- Skipping interviews because "we already know our customer" (you don't) +- Interviewing only happy customers (lapsed customers are more informative) +- Doing 1 or 2 interviews and declaring "we did research" +- Skipping synthesis and going straight to "here's what we learned" without rigor + +5 interviews is the minimum to find patterns. 8 is comfortable. 12+ has diminishing returns for most projects. diff --git a/dist/pi/.agents/skills/brand-ideation/SKILL.md b/dist/pi/.agents/skills/brand-ideation/SKILL.md new file mode 100644 index 0000000..55ed7b3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/SKILL.md @@ -0,0 +1,175 @@ +--- +name: brand-ideation +description: "Generate, evaluate, and narrow brand concepts during early ideation including positioning territories, naming candidates, mood directions, and narrative angles. Use this skill whenever the user is in the early phase of brand creation, exploring brand directions, brainstorming names, building moodboards, generating positioning options, or trying to choose between multiple brand directions. Triggers on brand ideation, brand concept, naming, brand name, name candidates, positioning, brand positioning, mood board, brand directions, exploring brands, early brand work, brand exploration, brand brainstorm, brand options. Also triggers when the user has multiple half-formed brand ideas and needs help converging on one, even if they do not say 'ideation' explicitly." +category: brand +catalog_summary: "Naming, positioning territories, mood directions, narrative angles" +display_order: 1 +--- + +# Brand Ideation + +Generate and converge on brand directions before committing to identity work. This is upstream of `brand-identity` (the visual system) and `brand-style-guide` (the documentation). It is the divergent-then-convergent thinking phase where ideas are cheap and direction matters more than polish. + +--- + +## When to use + +- Generating naming options for a new brand or product +- Exploring positioning territories before committing +- Building moodboards and visual direction options +- Drafting narrative or origin-story angles +- Helping the user converge from many half-ideas to one direction +- Stress-testing an existing brand idea before investing in identity work + +## When NOT to use + +- The brand direction is already locked, the user wants logo and identity work (use `brand-identity`) +- Documenting an existing brand system (use `brand-style-guide`) +- Defining voice for an existing brand (use `brand-voice`) +- Initial discovery and audience research (use `brand-discovery`) + +--- + +## Required inputs + +- The category or product type +- The audience (at least roughly) +- The reason this brand exists (the problem it solves or the gap it fills) +- Constraints (existing brand assumptions, parent brand, regulatory limits) +- Number of directions desired (typically 3 to 5) + +If the audience is unclear, run `brand-discovery` first. + +--- + +## The framework: 4 stages + +Brand ideation moves through four stages. Each stage diverges (generate options) then converges (pick a direction). + +### Stage 1: Positioning territories + +A positioning territory is the strategic space the brand occupies. It is not a tagline. It is the answer to "what does this brand stand for that competitors do not?" + +Generate 3 to 5 territories using these angles: + +- Functional benefit. "The fastest way to X." (Risk: easy to copy.) +- Emotional benefit. "The brand that makes you feel Y." (Risk: vague if not earned.) +- Identity. "For people who are Z." (Risk: alienates non-Z customers.) +- Antagonist. "The opposite of [incumbent]." (Risk: defines you by them.) +- Originator. "The first or only one to do W." (Risk: must be defensible.) +- Worldview. "We believe V." (Risk: must be lived, not just stated.) + +For each territory, write: +- Statement (one sentence) +- Why this is true (the proof point) +- What this rejects (the territory we are NOT going to) +- Risk (what makes this fragile) + +### Stage 2: Naming directions + +Names cluster by approach. Generate names across multiple approaches, not just one. + +\| Approach \| Description \| Examples \| +\|---\|---\|---\| +\| Descriptive \| Says what it is \| "General Electric," "American Airlines" \| +\| Evocative \| Suggests a feeling or quality \| "Patagonia," "Oasis," "Stripe" \| +\| Founder \| Person's name \| "Disney," "Ford," "Tesla" \| +\| Acronym \| Letters from longer phrase \| "IBM," "BMW," "AWS" \| +\| Coined \| Made-up word \| "Kodak," "Häagen-Dazs," "Asana" \| +\| Metaphor \| Borrowed concept \| "Apple," "Amazon," "Twitch" \| +\| Compound \| Two words combined \| "Facebook," "PayPal," "Spotify" \| +\| Suggestive \| Hints at function without describing \| "Tide," "Sprint," "Slack" \| + +Generate 8 to 15 candidates per direction. Apply naming filters before short-listing: + +- Pronounceable in target languages +- Spellable without confusion +- Available as a domain (.com or relevant TLD), social handles, and trademark +- Distinctive in the category (search the name + category, see what comes up) +- Stretchable (does the name still work if the company expands?) +- Free of negative associations (run it past native speakers of any major target market) + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high. + +### Stage 3: Mood and visual direction + +Generate visual directions BEFORE designing anything. Each direction should be distinct enough that a designer would produce visibly different work for each. + +For each mood direction (typically 2 to 4): + +- Mood adjectives (3 to 5 words) +- Color territory (warm/cool, saturated/muted, light/dark - not specific hex yet) +- Type territory (serif/sans, modern/classical, geometric/humanist) +- Imagery direction (photography style, illustration style, iconography) +- Reference brands or sites (3 to 5 that exemplify the direction) +- What this rejects (the visual territory we are NOT going to) + +A mood direction is "Editorial sophistication: Warm cream paper backgrounds, classical serifs, archival photography. Think: The New York Times Magazine meets a literary journal." + +A bad mood direction is "Modern and clean." + +### Stage 4: Narrative and origin + +Every brand has a story. The narrative answers: how do we tell people why this exists? + +Common narrative shapes: + +- Founder story. A real person solved a real problem they had. +- Mission story. A bigger purpose drives every decision. +- Discovery story. We found something the world did not know. +- Heritage story. This has always been done a certain way; we honor or refresh it. +- Frustration story. The category was broken; we built the alternative. +- Vision story. Here is the future we are pulling toward. + +For each candidate narrative: + +- One-sentence summary +- The opening line (how the story starts when told for the first time) +- The proof points (what makes it true and not marketing puff) +- The hero (who the audience identifies with - the founder, the customer, the world) + +--- + +## Workflow + +1. Confirm the inputs. Category, audience, reason for being, constraints. +2. Stage 1: Generate 3 to 5 positioning territories. Use the 6 angles above. Name what each rejects. +3. Pick 1 to 2 territories. Move forward with the strongest. +4. Stage 2: Generate 30 to 50 naming candidates across at least 4 approaches. Filter to 8 to 12 that pass the six-criteria check. +5. Stage 3: Generate 2 to 4 mood directions. Each must be distinguishable enough to brief a designer. +6. Stage 4: Generate 2 to 3 narrative shapes. Pick the one that fits the founders, the audience, and the proof points. +7. Converge. Present the user with: 1 positioning, 8 to 12 naming finalists, 2 to 4 mood directions, 2 to 3 narrative shapes. Help them pick. +8. Output. Use the template in [`references/ideation-output-template.md`](references/ideation-output-template.md). + +--- + +## Failure patterns + +- Generating one option and calling it "the answer." The point of ideation is divergence. Without options, there is no real choice. +- Skipping the rejection step. A territory that does not name what it rejects is not a territory. Same for moods. +- Naming before positioning. Names without positioning end up arbitrary. Position first. +- Falling in love with one name too early. Run the full filter on every candidate. The clever name that fails the trademark check is not a candidate. +- "Modern, clean, minimal" mood direction. Means nothing. Always require specific reference brands. +- Skipping pronunciation tests. Especially for international brands. A name that confuses non-English speakers loses search volume forever. +- Mistaking ideation for execution. The output of this stage is direction, not finished assets. Resist the urge to design logos here. + +--- + +## Output format + +Default output is a markdown brief at `brand-ideation.md` in the project root. Includes: + +1. The chosen positioning territory (with what it rejects) +2. Naming finalists (8 to 12) with notes on each +3. Mood directions (2 to 4) with reference URLs +4. Narrative shape (chosen) with opening line and proof points +5. Open questions and decisions still needed before identity work begins + +Optional: a separate `naming-explorations.md` with the full list of 30 to 50 candidates (the "kill file") in case the chosen finalists fail later checks. + +--- + +## Reference files + +- [`references/ideation-output-template.md`](references/ideation-output-template.md) - Fillable template for the ideation deliverable. +- [`references/naming-evaluation-rubric.md`](references/naming-evaluation-rubric.md) - The 6-criteria filter applied with examples. diff --git a/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md b/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md new file mode 100644 index 0000000..e3d208c --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/references/ideation-output-template.md @@ -0,0 +1,181 @@ +# Brand Ideation Output Template + +A fillable template for the ideation deliverable. Captures the candidate names, positioning territories, mood directions, and narrative angles produced during ideation. + +The deliverable is not a single answer. It is a structured set of options the team can evaluate, narrow, and combine. + +--- + +## Project metadata + +Brand / project: [Name] +Ideation lead: [Name] +Date: [YYYY-MM-DD] +Inputs used: [Discovery report, brief, prior decks - link them] + +--- + +## Recap: what we are ideating against + +Two to four sentences. Pull from the discovery report. Anyone reading this deliverable cold should know: + +- Who the audience is +- What position the brand is trying to take +- What the constraints are (legal, geographic, category) + +> [Recap] + +--- + +## Naming candidates + +Generate widely first. Filter later. Aim for 30-50 candidates per round before applying the rubric. + +### Round 1: divergent + +\| # \| Name \| Type \| Source / inspiration \| +\|---\|---\|---\|---\| +\| 1 \| \| Coined / descriptive / metaphorical / founder / acronym / compound / portmanteau \| \| +\| 2 \| \| \| \| +\| 3 \| \| \| \| +\| ... \| \| \| \| + +### Round 2: filtered shortlist + +After applying the 6-criteria rubric (`naming-evaluation-rubric.md`), the names that survive. + +\| # \| Name \| Why it survived \| Open concerns \| +\|---\|---\|---\|---\| +\| 1 \| \| \| \| +\| 2 \| \| \| \| +\| 3 \| \| \| \| +\| 4 \| \| \| \| +\| 5 \| \| \| \| +\| 6 \| \| \| \| + +### Round 3: top 3 with full case + +For each finalist, write a one-page case. + +#### Finalist 1: [Name] + +- Pronunciation: [How it is said] +- Type: [Coined, metaphor, etc.] +- Meaning: [What it evokes, intentionally or by association] +- Why it works: [Per the 6 criteria] +- Risks: [Domain availability, trademark, cultural concerns, audience misreading] +- Domain status: [.com / alternative TLDs / acquisition cost estimate] +- Trademark status: [Cleared by counsel / preliminary search clean / requires deeper search] +- Visual potential: [How it could render as a wordmark, monogram, icon] + +#### Finalist 2: [Name] + +[Same structure] + +#### Finalist 3: [Name] + +[Same structure] + +--- + +## Positioning territories + +The territories from discovery, sharpened into ideation directions. Each territory should produce a distinct creative direction. + +### Territory 1: [Name] + +- One-sentence position: [The territory in a sentence] +- Voice direction: [How it sounds] +- Visual direction: [How it looks] +- Headline examples: [3-5 sample headlines that could only come from this territory] +- What it rules out: [Names, treatments, or messages this territory disqualifies] + +### Territory 2: [Name] + +[Same structure] + +### Territory 3: [Name] + +[Same structure] + +### Territory 4: [Name] + +[Same structure] + +--- + +## Mood directions + +Three to five mood directions, each with reference imagery, color cues, and a one-line description. These are not final design - they are starting points for art direction. + +### Mood 1: [Name, e.g., "Quiet confidence"] + +- Description: [One line] +- References: [3-5 visual references with credit and one-line note on what to take from each] +- Color cues: [General feel, not exact palette] +- Typography cues: [General feel] +- Photography or illustration direction: [General feel] +- Adjacent brands as reference: [Not to copy, to triangulate] + +### Mood 2: [Name] + +[Same structure] + +### Mood 3: [Name] + +[Same structure] + +--- + +## Narrative angles + +Three to five candidate brand stories or origin narratives. Each is a different way of telling who this brand is and why it exists. + +### Angle 1: [Name, e.g., "Founder's journey"] + +- Premise: [The narrative angle in two sentences] +- First page hero: [What the homepage hero would say under this angle] +- About page opening: [The first paragraph of the about page] +- Why it works: [What it earns the brand] +- Why it might fail: [Risk] + +### Angle 2: [Name] + +[Same structure] + +### Angle 3: [Name] + +[Same structure] + +--- + +## Synthesis: provisional recommendation + +Even though ideation produces options, the team should leave with a provisional combination to test next. + +> Provisional combination: Name [X], territory [Y], mood [Z], narrative [W]. +> +> Why this combination: [Two sentences.] +> +> What we test next: [Concept board, name validation with audience, treatment exploration, etc.] + +--- + +## Open questions + +- [ ] [Trademark search needed for finalist names] +- [ ] [Domain acquisition feasibility] +- [ ] [Audience reaction test for top 2 names] +- [ ] [Stakeholder alignment session for territory selection] +- [ ] [Other] + +--- + +## Sign-off + +Ideation accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand identity / further name validation / board-level review / etc.] diff --git a/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md b/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md new file mode 100644 index 0000000..d34bbfa --- /dev/null +++ b/dist/pi/.agents/skills/brand-ideation/references/naming-evaluation-rubric.md @@ -0,0 +1,151 @@ +# Naming Evaluation Rubric + +A name has to clear six bars. This document walks through each, with examples of names that pass and fail. + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high because a name lives forever. + +--- + +## 1. Pronounceable + +A name people cannot say will not get said. + +Pass: +- "Stripe" - one syllable, unambiguous +- "Notion" - two syllables, common word, clear stress +- "Loom" - one syllable, common phoneme + +Fail: +- "Xobni" (the X is silent? before the b? unclear) +- Names with non-English diacritics for an English-speaking market that get stripped to ambiguity +- "Yext" - is it "yext" with a hard Y or "ekst"? People disagree + +Test: Read the name aloud to 5 people who have not seen it written. If 3 of 5 pronounce it differently, fail. + +--- + +## 2. Spellable + +A name people cannot spell will not get found. + +Pass: +- "Asana" - phonetic, spelled exactly as it sounds +- "Patagonia" - long but predictable +- "Slack" - one syllable, common word + +Fail: +- "Häagen-Dazs" - even the inventors made it hard to spell on purpose +- Names with silent letters that are not standard English +- Names with "ee" / "ea" / "ie" ambiguity +- Names with double letters in unexpected places + +Test: Read the name aloud to 5 people. Ask them to spell it. If 2 of 5 misspell it, fail. + +--- + +## 3. Available + +A name you cannot legally use is not a candidate. + +Check, in this order: + +1. Trademark search in the relevant jurisdictions. Class matters - you can have the same name as another brand if you operate in different categories, but check. +2. Domain availability. The .com (or category-relevant TLD) for the exact name. Adjacent TLDs (.io, .co, .app) are weaker; .com is still default for most categories. +3. Social handles. Check the major platforms. Inconsistent handles fragment the brand. +4. Existing brands in the category. Even if trademark is technically clear, a confusable competitor name is a problem. +5. Negative associations. Search the name in quotes. See what shows up. + +Pass: +- A name with .com available, no conflicting trademark, clean handles across major platforms + +Fail: +- A name where the .com is parked at $50,000 and no budget exists +- A name that conflicts with a registered trademark in the same class +- A name that someone notable already uses on social platforms + +--- + +## 4. Distinctive + +A name that gets confused with competitors loses every benefit of being a name. + +Pass: +- "Stripe" in payments - distinct from PayPal, Square, Adyen +- "Notion" in productivity tools - distinct from Asana, Monday, Trello +- "Loom" in async video - distinct from Zoom, Vimeo, YouTube + +Fail: +- A name one letter different from a major competitor +- A name that rhymes with a major competitor +- A name from the same conceptual family (e.g., another fruit name in a market dominated by Apple) +- A name with words common in the category (e.g., "Pay" in fintech, "Code" in dev tools, "AI" in AI products) that gets lost in search + +Test: Search the name + category. If your name is buried under unrelated content or competitor confusion, fail. + +--- + +## 5. Stretchable + +A name that locks you into one product or category will hurt as you grow. + +Pass: +- "Amazon" - was a bookstore. Now sells everything. +- "Apple" - was a computer company. Now does phones, music, services. +- "Stripe" - "stripe of code" implied developer tools. Now does broader fintech. + +Fail: +- "TomatoTracker" - locked to tomatoes +- "PDFMonkey" - locked to PDFs +- Names that explicitly describe a single product feature, when the company plans to be more than that single feature + +Note: Locked-in names can be the right choice IF the company is committed to staying narrowly focused. "PDFMonkey" works if you genuinely just want to be the best PDF tool. The failure is when you outgrow the name and have to rebrand at scale. + +Test: Imagine the company in 5 years, expanded into adjacent categories. Does the name still fit? If not, plan for it. + +--- + +## 6. Free of negative associations + +A name that means something embarrassing in another language, or that already carries cultural baggage, will hit a ceiling. + +Check: + +- Translations. Run the name through a few major target market languages. Native speakers should review (translation tools miss nuance). +- Slang. Especially Gen Z and online slang shifts fast. A name that was clean five years ago may not be clean today. +- Acronyms. Some names form embarrassing acronyms when written in caps or in initialisms. +- Visual confusions. When written in certain fonts, do letters create unfortunate combinations? (Famous example: "kidsexchange" spelled as one word.) +- Existing pop culture. Is the name a character in a recent TV show, a banned topic, or a meme? + +Pass: +- Cleared in target markets, no recent cultural collisions, no embarrassing acronyms + +Fail: +- Names that translate to insults or anatomical terms in target markets +- Names that match recent meme content (the meme will fade but the association sticks) +- Names with unfortunate acronyms (e.g., "Strategic Health Initiative Team") + +Test: Native speakers in each target market review. Plus a 5-minute search of the name in pop culture context. + +--- + +## Scoring + +For each candidate name, score 1 to 5 on each of the six criteria, where 5 is "passes cleanly" and 1 is "definite fail." + +A name is short-listable if it scores 4 or 5 on every criterion. A 3 anywhere is a yellow flag (proceed with eyes open). A 2 or 1 anywhere is disqualifying. + +--- + +## Pragmatic notes + +- Domains: .com is still default for most US/global brands. Category-specific TLDs (.app, .ai, .io) work in some categories but require more brand investment to teach the audience. +- Trademark: Get a real attorney to clear the trademark before launch. The cost of a TM search is dramatically less than a rebrand. +- Generic names (descriptive of the category) cannot be trademarked and will struggle with distinctiveness. +- Made-up names are easier to clear and trademark but require more marketing investment to load with meaning. +- Founder names carry heritage but can complicate equity and exits. + +--- + +## When to walk away + +If the top 3 candidates all fail at least 2 criteria, the naming exploration was not deep enough. Generate another 30 to 50 candidates before settling. The cost of a bad name is paid every day for the life of the brand. diff --git a/dist/pi/.agents/skills/brand-identity/SKILL.md b/dist/pi/.agents/skills/brand-identity/SKILL.md new file mode 100644 index 0000000..f3a8ef8 --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/SKILL.md @@ -0,0 +1,203 @@ +--- +name: brand-identity +description: "Design or evaluate a brand visual identity system covering logo, color, typography, imagery direction, iconography, and motion principles. Use this skill whenever the user wants to design a logo, build a visual identity, define brand colors, choose brand typography, develop iconography, plan brand imagery, or evaluate an existing identity for cohesion. Triggers on logo design, brand identity, visual identity, brand mark, wordmark, monogram, color palette, brand colors, brand typography, type system, iconography, brand imagery, motion design, brand system, identity system. Also triggers when the user has a brand direction approved and now needs the visual artifacts that express it." +category: brand +catalog_summary: "Logo system, color, typography, imagery, iconography, motion" +display_order: 2 +--- + +# Brand Identity + +Design or evaluate the visual artifacts that express a brand: logo system, color, typography, imagery, iconography, and motion. Stack-agnostic. Tool-agnostic. + +This skill assumes a brand direction is already approved (positioning, mood, name). If not, run `brand-ideation` first. + +--- + +## When to use + +- Designing a logo system +- Defining a brand color palette +- Choosing brand typography +- Developing iconography or illustration style +- Defining imagery direction (photography, illustration) +- Establishing motion principles +- Auditing an existing identity for cohesion or gaps + +## When NOT to use + +- Brand direction is not yet defined (use `brand-ideation`) +- Documenting a finished system (use `brand-style-guide`) +- Defining voice and tone (use `brand-voice`) +- Building UI components from an existing brand (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- The brand name and approved positioning +- The mood direction (from ideation, or supplied as references) +- Audience and category context +- Application contexts (web, print, packaging, motion - whatever applies) +- Constraints (parent brand requirements, regulatory marks, accessibility minimums) + +--- + +## The framework: 5 elements + +A complete identity has five elements. Each element should reinforce the others. Inconsistency between them is the most common identity failure. + +### 1. Logo system + +Most brands need not one logo but a system of marks for different contexts. + +Components of a logo system: + +- Primary mark. The main logo. Used wherever there is room. +- Wordmark. Just the typography, no symbol. Used in tight horizontal contexts. +- Symbol or glyph. Just the symbol, no type. Used in app icons, favicons, social avatars. +- Lockup variations. Horizontal, stacked, square - whichever apply. +- Monogram. The initial(s) styled as a mark. Optional but useful for small contexts. + +Design principles: + +- Legible at 16 pixels. Test the logo at favicon size. If it falls apart, redesign. +- Reproducible in single-color. If the logo only works in full color, it cannot be screen-printed, embroidered, or rendered in browser favicons. +- Distinctive silhouette. Squint at it. Can you still tell what it is? If it looks like every other logo in the category at silhouette, redesign. +- Construction grid. Every curve and angle is intentional. Document the construction. + +Common failure: +- Designing only the primary mark and discovering at launch that the wordmark, glyph, and small-size variants do not exist. + +### 2. Color system + +A color system is more than a palette. It is the rules for how color carries meaning. + +Components: + +- Primary color. The signature color most associated with the brand. +- Secondary colors. 1 to 3 supporting colors that extend the palette. +- Neutrals. The grays and tints that make up most of the surface area. +- Semantic colors. Success, warning, error, info - if the brand operates in product UI. +- Accent colors. Used sparingly for highlight and emphasis. + +Per color, document: +- Hex, RGB, HSL, CMYK (if print is in scope), and Pantone (if brand-critical print exists) +- WCAG AA contrast against the other colors in the system +- Allowed and disallowed pairings (some brand colors look terrible together) +- Usage notes (when to use, when not to use) + +Design principles: + +- Test for accessibility. WCAG AA requires 4.5:1 contrast for normal text, 3:1 for large text. If the brand color cannot pass either against white, you have a problem. +- Test for color blindness. Around 8 percent of men have some form of color blindness. Critical UI signals should not rely on color alone. +- Define neutrals carefully. Neutrals are 80 percent of the surface area in most brand applications. They carry more weight than the brand color. +- Limit the palette. A 30-color palette is unmanageable. 5 to 8 carefully chosen colors beats a sprawling system. + +### 3. Typography + +Type is the second-most-recognizable element of a brand after the logo. + +Components of a type system: + +- Display typeface. For headlines and brand moments. +- Body typeface. For long-form reading. Often the same as display, sometimes different. +- Monospace typeface (if applicable for technical brands). +- Type scale. The set of sizes used across applications. Typically 5 to 8 steps. +- Type weights and styles. Which weights and italics are part of the system. + +Design principles: + +- Pairing. If using two typefaces, they must work together at body and display sizes. Common pattern: serif display + sans body, or geometric sans display + humanist sans body. +- Web licensing. Confirm web licensing covers expected pageviews. Some popular typefaces have prohibitive web licenses. +- Variable fonts are increasingly the right call for performance and flexibility. +- Fallback stack. Specify system fallbacks for when the brand font fails to load. The fallback should be visually similar. +- Open-source alternatives. Document open-source equivalents for situations where licensing is impractical (third-party tools, embedded contexts). + +### 4. Imagery and illustration + +Imagery direction is often underspecified, leading to brand drift over time. + +Photography direction: + +- Subject matter. What does the brand show? +- Composition style. Tight crops, wide environments, candid, posed? +- Lighting. Bright and natural, dramatic and directional, soft and diffused? +- Color treatment. True color, warm shifted, desaturated, high-contrast? +- What to reject. Stock photo aesthetics, specific cliches in the category. + +Illustration direction: + +- Style. Flat, dimensional, hand-drawn, geometric, abstract, representational? +- Color use. Full palette, restricted palette, brand colors only? +- Line treatment. Bold and outlined, soft and shaded, no outlines? +- Subject matter. What gets illustrated and what does not? + +Iconography: + +- Style. Filled or outline. Rounded or sharp. Single weight or variable. +- Grid. Pixel-perfect grid (often 24x24 or 16x16 base). +- Stroke weight. Consistent across the icon set. +- Set. Which icons exist, and how new icons get added consistently. + +### 5. Motion + +If the brand lives in any digital product, marketing video, or animated touchpoint, motion is part of the identity. + +Motion principles to define: + +- Easing curves. Default easings used across animations. Linear, ease-in-out, custom. +- Duration scale. Fast (100ms), medium (200-300ms), slow (500ms+) and when each applies. +- Choreography. How elements enter, exit, and respond to interaction. +- Brand moments. Signature animations (logo build, page transitions, loaders). + +Design principles: + +- Restraint. Most motion in product UI should be quick and subtle. Reserve dramatic motion for brand moments. +- Reduced motion. Always provide a `prefers-reduced-motion` alternative for users with vestibular sensitivities. +- Performance. Animations must be 60fps on the target devices. Profile before shipping. + +--- + +## Workflow + +1. Confirm brand direction. Positioning, mood, audience. If unclear, return to `brand-ideation`. +2. Audit applications. List every place the brand will appear (web, print, packaging, app, social, signage, video). The application contexts drive what the system needs to handle. +3. Element-by-element design. Start with logo and color, since these constrain typography. Then type. Then imagery, iconography, motion. +4. Stress-test. Apply the system to 3 to 5 mock applications (homepage, social post, business card, product UI, signage). Where does it break? Iterate. +5. Document. Each element with rules, examples, and dos/don'ts. This becomes the input to `brand-style-guide`. +6. Get sign-off before broad rollout. Identity changes after rollout are 10x the cost of changes during design. + +--- + +## Failure patterns + +- Designing logos in isolation from application. A logo that looks great on a hi-res mockup but illegible at favicon size is a design failure. +- Picking a brand color without contrast testing. A brand color that fails WCAG AA against white means UI built on the brand will be inaccessible by default. +- Specifying typography without checking web licensing. Discovering at deploy that the foundry charges per-pageview for the chosen typeface is a budget-buster. +- Skipping imagery direction. Without it, the brand becomes whatever stock photos the next person picks. +- Treating motion as decoration. Inconsistent motion erodes brand cohesion as fast as inconsistent color. +- Designing only primary states. What does the brand look like in error? In dark mode? In a localization where the wordmark needs to flip direction? These are not edge cases; they are the brand. + +--- + +## Output format + +Default output is a structured set of files: + +- `identity/logo/` - All logo variants (SVG primary, plus PNG/JPG exports at common sizes) +- `identity/colors.md` - Color system with hex codes, contrast ratios, usage rules +- `identity/typography.md` - Type system with scale, weights, fallbacks +- `identity/imagery.md` - Imagery direction with reference examples +- `identity/iconography/` - Icon set or icon style spec +- `identity/motion.md` - Motion principles +- `identity/applications/` - 3 to 5 application mockups stress-testing the system + +These feed directly into `brand-style-guide`. + +--- + +## Reference files + +- [`references/identity-system-spec.md`](references/identity-system-spec.md) - Detailed spec template for documenting each element. +- [`references/contrast-and-accessibility.md`](references/contrast-and-accessibility.md) - Accessibility checks for color and type, with the math. diff --git a/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md b/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md new file mode 100644 index 0000000..d0f964e --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/references/contrast-and-accessibility.md @@ -0,0 +1,188 @@ +# Contrast and Accessibility for Brand Identity + +A brand color choice that fails accessibility is a design defect. Every product, page, button, and label using that color inherits the failure. + +This reference walks through the math, the standards, and the practical implications. + +--- + +## The standards + +WCAG 2.1 AA is the minimum bar for most professional brand work. + +\| Element \| Required contrast ratio \| +\|---\|---\| +\| Normal body text \| 4.5:1 \| +\| Large text (18pt regular or 14pt bold) \| 3:1 \| +\| UI components and graphical elements \| 3:1 \| + +WCAG 2.1 AAA is stricter. Required for some accessibility-focused products, optional but admirable for most. + +\| Element \| Required contrast ratio \| +\|---\|---\| +\| Normal body text \| 7:1 \| +\| Large text \| 4.5:1 \| + +--- + +## The math + +Contrast ratio is calculated as: + +``` +(L1 + 0.05) / (L2 + 0.05) +``` + +Where L1 is the relative luminance of the lighter color and L2 of the darker. Relative luminance comes from a weighted formula on RGB values that accounts for human perception (green contributes more than blue). + +Quick contrast checker (run in browser console): + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + return ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2) + ':1'; +} + +// Example +contrast('#FFFFFF', '#4B5563'); // returns '6.40:1' +``` + +--- + +## Common brand color failures + +These are color choices that look great in a logo but fail WCAG when used for text or UI: + +\| Pairing \| Ratio \| Status \| +\|---\|---\|---\| +\| Light gray (#9CA3AF) on white \| 2.85:1 \| Fails AA \| +\| Bright yellow on white \| 1.07:1 \| Fails AAA, AA, and basic legibility \| +\| Bright orange (#FF9900) on white \| 2.14:1 \| Fails AA \| +\| Sky blue (#3B82F6) on white \| 4.57:1 \| Passes AA for normal text \| +\| Most "vibrant" brand reds on white \| 3-4.5:1 \| Borderline; check exact values \| +\| White text on bright orange \| 2.14:1 \| Fails AA \| + +When in doubt, darken the brand color for text contexts. Keep the original hue for non-text brand expressions (logos, large graphics, decorative elements). + +--- + +## The "darker variant" strategy + +For brand colors that fail AA contrast, define a darker variant for use in text and UI. + +``` +Brand orange (signature): #FF9900 (used in logos, illustrations, large graphics) +Brand orange (text/UI): #B86600 (passes AA against white) +``` + +Both are "the brand color." The signature version is what people associate with the brand. The text variant is what enables accessible UI without abandoning the identity. + +This is standard practice. Most major brands have both versions, even if only the signature version is publicized. + +--- + +## Color blindness considerations + +Around 8 percent of men and 0.5 percent of women have some form of color vision deficiency. The most common is red-green (deuteranopia and protanopia). + +Tests to run: + +- Red-green confusion. Greens and reds at similar luminance look the same to deuteranopes. If your success/error indicators rely on red-green distinction, add an icon or text label. +- Tritan simulation. Less common but worth checking. Blues and yellows. +- Greyscale conversion. Convert your palette to grayscale. If two brand colors look identical in greyscale, they will be hard to distinguish for people with severe color blindness. + +Tools: Stark plugin (Figma), Coblis (online simulator), Chrome DevTools rendering tab. + +Practical rule: Critical UI signals must communicate through more than just color. Use icons, labels, position, or shape as redundant signals. + +--- + +## Typography contrast + +Type contrast is not just about color. It includes: + +- Color contrast (per the standards above) +- Weight contrast (light text on a busy background fails even at high color contrast) +- Size contrast (very small text needs higher color contrast) + +Practical rules: + +- Body text: minimum 14px on web, ideally 16px. Below 14px is uncomfortable for most readers regardless of contrast. +- Body text on photographs or busy backgrounds: add a scrim, increase the type weight, or move the text. +- Light-weight fonts (Thin, Extra Light) for body text: avoid. They fail visual contrast even at passing color contrast. + +--- + +## Dark mode considerations + +Most brand colors that work on white do not work on dark backgrounds. + +Common failure: +- Brand color = dark navy. On white: 12:1 contrast (excellent). On near-black: 1.4:1 (terrible). + +Solutions: + +- Define light-mode AND dark-mode variants of every functional color in the system. +- Brand colors typically need to be lightened or desaturated in dark mode. +- Test the entire palette against both light and dark surfaces. + +``` +Brand navy: + Light mode (on white): #0F2A4A (12:1 contrast) + Dark mode (on #111): #6B9FE8 (5.2:1 contrast against #111) +``` + +Both are "the brand color." Both express the identity. They just live in different lighting conditions. + +--- + +## Icons and graphical elements + +WCAG requires 3:1 for UI components and graphical elements. This includes: + +- Icons used to convey meaning +- Form field borders +- Focus indicators +- Chart elements that distinguish data series +- Toggle and switch states + +Common failure: +- Light gray icon (#D1D5DB) on white background: 1.4:1. Invisible to users with low vision. +- Form field borders at #E5E7EB: 1.3:1. Borderline visible. + +Fix: +- Icons that convey meaning: minimum #6B7280 on white (3.9:1). +- Form field borders: minimum #9CA3AF on white (3.0:1) for default state. Stronger for focus. + +--- + +## Practical checklist for brand color decisions + +Before locking a brand color: + +- [ ] Tested against white at WCAG AA for body text (4.5:1) +- [ ] Tested against white at WCAG AA for large text (3:1) +- [ ] Tested against the brand's dark surface color (for dark mode) +- [ ] Tested for color blindness (deuteranopia simulation) +- [ ] A "darker variant" defined for text contexts if signature color fails AA +- [ ] White text on the brand color tested for 4.5:1 (for buttons and CTAs) +- [ ] All semantic colors (success, warning, error) pass AA on white and dark +- [ ] Neutrals scale tested across the full range + +If any check fails, document the failure and provide an alternative variant for the failing context. Do not just hope it will be fine in practice. It will not be fine. + +--- + +## Resources + +- WebAIM Contrast Checker (free, browser-based) +- Stark plugin for Figma +- Chrome DevTools accessibility panel +- Coblis color blindness simulator +- WCAG 2.1 specification at w3.org diff --git a/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md b/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md new file mode 100644 index 0000000..4b08849 --- /dev/null +++ b/dist/pi/.agents/skills/brand-identity/references/identity-system-spec.md @@ -0,0 +1,212 @@ +# Identity System Spec + +A spec template for documenting each element of the brand identity system. This is the working document during identity build, before the polished style guide. It locks decisions and exposes gaps. + +Fill every section. The point of the spec is to surface what is undecided. + +--- + +## System metadata + +Brand: [Name] +Version: [v1.0, v1.1, etc.] +Date: [YYYY-MM-DD] +Owner: [Name] +Status: [Draft / In review / Approved] + +--- + +## 1. Logo system + +### Primary logo + +- Form: [Wordmark / lettermark / combination mark / pictorial / abstract] +- Construction notes: [Geometry, custom letterforms, optical adjustments] +- Source files: [SVG, AI, layered] +- Color versions: [Full color, single color, reversed (white on dark)] +- Minimum size: [Pixels for digital, inches/mm for print] +- Clear space: [Minimum margin around logo, defined as multiple of a logo element, e.g., "1x cap height"] + +### Logo variants + +\| Variant \| When to use \| Source file \| +\|---\|---\|---\| +\| Horizontal \| Default \| \| +\| Stacked \| Constrained widths, social avatars \| \| +\| Mark only \| Favicons, app icons, watermarks \| \| +\| Wordmark only \| Inline text contexts \| \| + +### Misuse rules + +What never to do with the logo. Ten short rules at most. + +- Do not stretch +- Do not rotate +- Do not recolor outside the approved palette +- Do not place on busy photography without a scrim +- (etc.) + +### Application examples + +Where the logo lives. Document the canonical placements. + +- Web header: [Position, size, color treatment] +- Email signature: [Position, size] +- Favicon: [Variant used, sizes generated] +- App icon: [Variant, background, padding] +- Print: [Letterhead, business card] +- Social: [Avatar variant, banner specs] + +--- + +## 2. Color + +### Primary palette + +\| Token name \| Hex \| RGB \| HSL \| Usage \| +\|---\|---\|---\|---\|---\| +\| `color-brand-primary` \| \| \| \| Primary brand color, dominant in identity \| +\| `color-brand-secondary` \| \| \| \| Secondary brand color \| +\| `color-brand-tertiary` \| \| \| \| Optional accent \| + +### Neutrals + +\| Token name \| Hex \| Usage \| +\|---\|---\|---\| +\| `color-neutral-0` \| #FFFFFF \| Background, max contrast \| +\| `color-neutral-50` \| \| \| +\| `color-neutral-100` \| \| \| +\| `color-neutral-200` \| \| \| +\| ... \| \| \| +\| `color-neutral-900` \| \| \| +\| `color-neutral-1000` \| #000000 \| \| + +### Semantic tokens + +\| Token name \| Resolves to \| Usage \| +\|---\|---\|---\| +\| `color-text-primary` \| \| Body text \| +\| `color-text-secondary` \| \| Captions, less important text \| +\| `color-text-disabled` \| \| Disabled state \| +\| `color-text-inverse` \| \| Text on dark backgrounds \| +\| `color-bg-primary` \| \| Default background \| +\| `color-bg-elevated` \| \| Cards, modals \| +\| `color-border-default` \| \| Card borders, dividers \| +\| `color-success` \| \| \| +\| `color-warning` \| \| \| +\| `color-error` \| \| \| +\| `color-info` \| \| \| + +### Color rules + +- Never invent a new color. If a use case is not covered, propose a new token. +- Brand color contrast against approved backgrounds must meet WCAG AA for text. See `contrast-and-accessibility.md`. +- Dark mode tokens defined separately or via theme switch logic. + +--- + +## 3. Typography + +### Type families + +\| Role \| Family \| Weights used \| License \| +\|---\|---\|---\|---\| +\| Display \| \| \| \| +\| Body \| \| \| \| +\| Mono (code, data) \| \| \| \| + +### Type scale + +\| Token \| Size \| Line height \| Weight \| Use case \| +\|---\|---\|---\|---\|---\| +\| `text-display-1` \| \| \| \| Hero headline \| +\| `text-display-2` \| \| \| \| Section headline \| +\| `text-h1` \| \| \| \| Page title \| +\| `text-h2` \| \| \| \| Section title \| +\| `text-h3` \| \| \| \| Sub-section \| +\| `text-body-lg` \| \| \| \| Lead paragraph \| +\| `text-body` \| \| \| \| Default body \| +\| `text-body-sm` \| \| \| \| Caption, supporting text \| +\| `text-label` \| \| \| \| UI labels \| +\| `text-overline` \| \| \| \| Eyebrow text \| + +### Typography rules + +- Display weights only at display sizes. Do not use display weights for body. +- Body line height target 1.5 to 1.65 for readability. +- Line length target 50 to 75 characters per line. +- Avoid mixing more than two type families on a single page. + +--- + +## 4. Iconography + +- Style: [Outline / filled / mixed / two-tone] +- Stroke weight: [Specific px or em value] +- Corner radius: [Specific px] +- Grid: [24x24 default, with optional 16, 32, 48 sizes] +- Source: [Custom set / Lucide / Heroicons / Phosphor / Material] +- Naming convention: [`icon-[noun]-[modifier]`] +- License: [If using a third-party set] + +### Icon rules + +- Icons paired with labels by default. Icon-only buttons require an accessible label. +- Decorative icons get `aria-hidden="true"`. +- Functional icons inherit text color via `currentColor`. + +--- + +## 5. Imagery + +### Photography + +- Style: [Editorial / lifestyle / product / documentary / abstract] +- Color treatment: [Natural / treated / desaturated / signature filter] +- Composition: [Tight / wide / asymmetrical / symmetrical / negative space] +- Subject direction: [Demographics, environments, energy] + +### Illustration + +- Style: [If applicable - flat / textured / line / mixed] +- Color usage: [Limited palette / full palette] +- Pattern library: [Where it lives] + +### Stock and AI policy + +- Stock photography: [Allowed / banned / case-by-case with approval] +- AI-generated imagery: [Allowed / banned / case-by-case] +- Sources approved: [Specific platforms or studios] + +--- + +## 6. Motion + +- Default duration: [ms - typically 200-300] +- Default easing: [Standard easing curve, e.g., `cubic-bezier(0.4, 0, 0.2, 1)`] +- Token naming: [`motion-duration-fast`, `motion-easing-standard`] +- Reduced motion: [What animates becomes static when `prefers-reduced-motion: reduce`] + +--- + +## 7. Voice (cross-reference) + +Voice has its own deliverable. See the brand voice document. The identity spec only notes voice attributes that interact with visual identity (e.g., if voice is "quiet," typography should not be loud). + +--- + +## Open questions + +- [ ] [Token naming convention finalized?] +- [ ] [Dark mode strategy defined?] +- [ ] [Brand color WCAG contrast verified across approved backgrounds?] +- [ ] [Icon set licensed for production?] +- [ ] [Photography source defined?] + +--- + +## Sign-off + +- Design lead: [Name, date] +- Creative director: [Name, date] +- Engineering lead (for token implementability): [Name, date] diff --git a/dist/pi/.agents/skills/brand-style-guide/SKILL.md b/dist/pi/.agents/skills/brand-style-guide/SKILL.md new file mode 100644 index 0000000..a852bf3 --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/SKILL.md @@ -0,0 +1,202 @@ +--- +name: brand-style-guide +description: "Build or audit a comprehensive brand style guide that documents the full brand system including story, logo system, color, typography, imagery, voice, applications, and dos/don'ts. Use this skill whenever the user wants to create brand guidelines, document an existing brand, build a brand book, audit an existing style guide for completeness, or produce the artifact that other teams will reference for years. Triggers on style guide, brand guidelines, brand book, brand standards, brand manual, style sheet, brand documentation, brand reference. Also triggers when the brand identity is finished and needs to be documented for handoff to designers, developers, vendors, or future team members." +category: brand +catalog_summary: "The canonical reference document for the full brand system" +display_order: 3 +--- + +# Brand Style Guide + +Document the brand system so other people can use it without ambiguity. This is the artifact that lives longest. Designers, developers, agencies, and vendors will reference it for years. Build it like a reference manual, not a presentation. + +This skill assumes the brand identity is designed (run `brand-identity` first if not). The output of this skill is the canonical reference document. + +--- + +## When to use + +- Creating brand guidelines for a finished identity +- Documenting an existing brand that has no formal guide +- Auditing an existing style guide for gaps or inconsistencies +- Building a brand book to hand to vendors, partners, or new team members +- Updating a guide after a major brand evolution + +## When NOT to use + +- The brand identity is not yet designed (use `brand-identity`) +- Brand voice work specifically (use `brand-voice` for the voice doc, then integrate) +- Building UI components (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- Finished brand identity (logo, colors, typography, imagery direction, motion principles) +- Brand voice and tone documentation (or sufficient inputs to write a voice section) +- Application examples that show the brand in real contexts +- Decisions on what is mandatory vs flexible vs forbidden + +--- + +## The framework: 8 sections + +A complete style guide has eight sections. Most guides skip 2 or 3 of them and create downstream confusion. Build all 8 from the start. + +### 1. Story +The narrative behind the brand. Why it exists, what it stands for, what it rejects. + +- Origin / founding story +- Mission and vision +- Values (3 to 5, with what each means in practice) +- Positioning statement +- Audience (with the level of specificity from the brief) +- What we are not (the things we explicitly reject) + +### 2. Logo system +Every variant of every mark, with rules. + +- Primary logo (with construction grid showing relationships) +- Wordmark +- Symbol / glyph +- Lockup variations (horizontal, stacked, etc.) +- Monogram (if part of system) +- Clear space rules (minimum spacing around logo) +- Minimum sizes (smallest acceptable size for print and digital) +- Acceptable color treatments (full color, single color, knock-out, reverse) +- Forbidden treatments (stretching, rotating, recoloring, drop shadows, gradients - whatever is forbidden) +- File formats and where to find them + +### 3. Color +The full color system with rules. + +- Primary palette (signature colors) +- Secondary palette +- Neutrals scale +- Semantic colors (success, warning, error, info) +- Light mode and dark mode variants +- Per color: hex, RGB, HSL, CMYK, Pantone (if print-relevant) +- Contrast ratios documented +- Allowed pairings +- Forbidden pairings +- Usage hierarchy (primary first, secondary supporting, neutrals dominant) + +### 4. Typography +The full type system. + +- Display typeface (with sample sizes) +- Body typeface (with sample sizes) +- Monospace (if applicable) +- Type scale (specific sizes used) +- Weight and style usage (which weights for which contexts) +- Line height ratios +- Letter spacing standards +- Web fallback stacks +- Open-source alternatives for licensing-restricted contexts +- Forbidden treatments (all caps overuse, fake italics, etc.) + +### 5. Imagery and illustration +What pictures look like in this brand. + +- Photography direction with example library +- Illustration style with example library +- Iconography system with the full icon set (or rules for adding to it) +- Forbidden imagery (stock photo cliches, specific things never to show) +- Photo treatment rules (color treatment, crops, composition) + +### 6. Voice and tone +How the brand sounds. (Pulled from `brand-voice` work if done separately.) + +- Voice attributes (3 to 5 adjectives with "we are X, not Y" framing) +- Tone shifts by context (onboarding, error, marketing, support, legal) +- Vocabulary preferences (words we use, words we avoid) +- Grammar and style rules +- Examples (good and bad copy side by side) + +### 7. Applications +The brand applied to real contexts. + +- Web (homepage, product pages, blog template) +- Email (template, signature, transactional) +- Social (post templates, profile imagery, story formats) +- Print (business cards, letterhead, print ads) +- Packaging (if applicable) +- Signage (if applicable) +- Internal documents (slides, reports, proposals) +- Each with examples showing what good looks like + +### 8. Dos and don'ts +The boundaries, illustrated. + +- Logo dos and don'ts (visual examples of correct and incorrect use) +- Color dos and don'ts (combinations to use, combinations to avoid) +- Type dos and don'ts (treatments to use, treatments to avoid) +- Composition dos and don'ts (layout patterns that work, ones that do not) +- Voice dos and don'ts (phrases that fit, phrases that do not) + +The dos and don'ts section is what people actually reference in practice. Make it the easiest section to scan. + +--- + +## Workflow + +1. Inventory the inputs. What identity work is finished? What voice work is finished? What is missing? +2. Confirm the format. Is this a PDF, a web page, a Notion doc, a printed book, or all of the above? Different formats have different production requirements. +3. Section by section, draft. Use the template in [`references/style-guide-template.md`](references/style-guide-template.md). +4. Stress-test with real examples. For every rule, find a real application example. Rules without examples get ignored. +5. Get review from the people who will use it. Designers, developers, marketers. They will surface gaps. +6. Version control. Style guides evolve. Date the doc. Note what changed in each version. +7. Publish in the format the team will actually open. A 200-page PDF that lives on a shared drive is dead weight. A web page or Figma file with a clear URL gets used. + +--- + +## Failure patterns + +- Skipping the "what we are not" sections. Without rejection rules, anything becomes acceptable. +- Document with no examples. Rules without visual examples are abstract and ignored. +- Document with only examples. Examples without rules cannot be applied to new situations. +- Static PDF that no one opens. Ship the guide in the format the team uses daily (web page, Figma, Notion, etc.). +- No version history. When the brand evolves, no one knows which rules changed or when. +- Aspirational rules. Rules the brand does not actually follow get treated as suggestions. Document what is actually true, not what is wished. +- Treating "dos and don'ts" as filler. This section is what people use most. Invest in it. + +--- + +## Output format + +Default output is a multi-section markdown document or a structured set of files, plus a presentation-ready version (web page, PDF, or Figma) for sharing with stakeholders. + +Recommended structure: + +``` +brand/ + style-guide.md (the canonical document) + story.md (or as a section) + logo/ + construction.md + files/ (SVG, PNG, etc.) + colors.md + typography.md + imagery/ + photography.md + illustration.md + icons/ + icons.md + files/ + voice.md + applications/ + web.md + email.md + social.md + print.md + dos-and-donts.md +``` + +For consumer-facing presentation, build a web page version that imports from these source files. The source files are canonical. The presentation is a view of them. + +--- + +## Reference files + +- [`references/style-guide-template.md`](references/style-guide-template.md) - Fillable section-by-section template. +- [`references/maintenance-playbook.md`](references/maintenance-playbook.md) - How to keep the guide current after launch. diff --git a/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md b/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md new file mode 100644 index 0000000..33e208d --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/references/maintenance-playbook.md @@ -0,0 +1,251 @@ +# Brand Style Guide Maintenance Playbook + +A style guide that does not get maintained becomes a museum piece within a year. This playbook covers who owns it, when it gets updated, and how change requests get handled. + +--- + +## Why guides decay + +The common failure modes: + +- No owner. The guide was a project deliverable. The team disbanded. No one maintains it. +- Drift. Real work in market diverges from the guide. The guide stops reflecting reality. +- Frozen in time. The guide was right at launch. Markets, products, and audiences moved. +- Locked away. The guide lives in a tool nobody opens. Teams reinvent rather than reference. +- Too rigid. The guide bans variation that real work demands. Teams ignore it rather than challenge it. + +The maintenance playbook addresses each of these. + +--- + +## Ownership + +### The owner + +Every brand guide has one owner. Not a committee. The owner: + +- Is named in the guide itself +- Has explicit authority to approve changes +- Has time allocated (typically 5-10% of one role) for guide upkeep +- Reports to a stakeholder who cares about brand consistency + +If the role is vacant, the guide is at risk regardless of how good the content is. + +### The guidance council (optional) + +For larger organizations, a small council reviews proposed changes before the owner approves. Typically: + +- Brand lead (chair) +- Design lead +- Marketing lead +- Engineering lead (if guide includes design tokens / dev assets) +- One product representative + +The council meets quarterly to review the change queue. + +--- + +## Change types and authority + +Not every change needs the same review. Define tiers. + +### Tier 1: clarifications (owner approves directly) + +- Typo fixes +- Adding examples to existing rules +- Improving wording without changing meaning +- Adding missing assets that are already approved (new logo file format, etc.) + +Process: owner ships within a week. + +### Tier 2: extensions (owner consults, then approves) + +- New use cases for existing elements +- New approved color combinations +- New typographic patterns within the existing scale +- New illustration or photography patterns within existing direction + +Process: owner posts to a working channel for 5-day comment period, addresses feedback, ships. + +### Tier 3: changes (council reviews, owner ships) + +- Modifying or expanding the color palette +- Modifying the type scale +- Adding or removing approved photographic styles +- Updating logo construction or variants +- Voice tone adjustments + +Process: RFC document, council review at quarterly meeting (or async if time-sensitive), then owner ships. + +### Tier 4: shifts (executive approval required) + +- Logo redesign +- Brand voice repositioning +- Color palette overhaul +- Naming or positioning changes + +Process: full brand project. Treat as a separate engagement, not a maintenance ticket. + +--- + +## Update cadence + +Even without inbound change requests, schedule reviews. + +\| Cadence \| What happens \| +\|---\|---\| +\| Monthly \| Owner sweeps the change queue, ships Tier 1 fixes, queues Tier 2 for the comment period. \| +\| Quarterly \| Council reviews Tier 3 RFCs, takes a sample-based audit (see below), updates roadmap. \| +\| Annually \| Full audit (see audit playbook), refresh of examples, prune of stale content, version bump. \| +\| As-needed \| Tier 4 shifts driven by business strategy. \| + +--- + +## Change request process + +Anyone in the organization can propose a change. The process: + +1. Submit via the request channel (template below). +2. Triage by owner within 5 business days. Assigns tier. +3. Comment / review depending on tier. +4. Decide. Approve, decline (with reason), or revise. +5. Ship. Update the guide, update related assets, communicate. +6. Communicate. Announce in the brand channel. Note in the changelog. + +### Request template + +``` +What is the change? +[One paragraph] + +Why is it needed? +[Real use case that surfaced this] + +What is affected? +[Pages, assets, components] + +Proposed solution +[Specific change to the guide] + +Alternatives considered +[Other ways to solve this] + +Requester +[Name, team] +``` + +--- + +## Audit cadence + +### Monthly: surface scan + +Owner scans 5-10 randomly selected production touchpoints (web pages, ads, emails, social posts) and notes any guide violations or undocumented patterns. 30 minutes max. + +The output is a row in a tracking sheet, not a deliverable. Used to surface drift trends. + +### Quarterly: sample audit + +Owner (or council) audits 20-30 production touchpoints across channels. Categorize each: + +- Compliant +- Minor deviation (acceptable, document if recurring) +- Major deviation (followup required) +- Undocumented pattern (consider adding to guide) + +Output: a one-page summary with action items. + +### Annual: full audit + +Use the audit template (typically a separate audit deliverable, not part of the guide itself). Full review across: + +- Logo usage +- Color +- Typography +- Imagery +- Voice and copy +- Motion and interaction +- Adoption (which teams use the guide vs work around it) + +Output: a backlog for the next year. + +--- + +## Versioning + +Use semantic versioning for the guide. + +- Major (1.0 → 2.0): brand shift. Logo redesign, voice repositioning, palette overhaul. +- Minor (1.1 → 1.2): new sections, expanded color or type, new approved patterns. +- Patch (1.1.1 → 1.1.2): clarifications, typo fixes, new examples. + +Each version has a changelog entry: what changed, who approved, when, and migration notes if any. + +### Backward compatibility window + +When a Tier 3 or Tier 4 change ships, set a deprecation window: + +- Tier 3: 90 days. Old patterns acceptable in production, new patterns required for new work. +- Tier 4: 6-12 months depending on production cycle (print catalogs, manufactured goods, regulatory deliverables may need longer). + +Document deprecated patterns with a clear "Replaced by [new pattern], deprecated as of [date], removal date [date]" note. + +--- + +## Communication + +When the guide changes, people need to know. + +### Channels + +- Brand channel: standing channel for all updates, requests, questions. +- Changelog page in the guide: running list of versioned changes. +- Quarterly digest email: roundup of the past quarter's changes, plus the audit summary. +- Annual review post: the year's biggest changes, the audit findings, the next year's priorities. + +### When to push, when to publish + +- Push (announce, require attention) for Tier 3 and Tier 4 changes. +- Publish (update the guide and the changelog, no broadcast) for Tier 1 and Tier 2. + +--- + +## Adoption health metrics + +The guide is healthy when teams use it. Track: + +\| Metric \| Healthy \| Warning \| Failing \| +\|---\|---\|---\|---\| +\| Average page views per month \| Steady or growing \| Declining \| Near-zero \| +\| Change requests per quarter \| 5-15 \| <3 \| 0 (or 50+) \| +\| Audit compliance score (Tier 3+) \| >90% \| 75-90% \| <75% \| +\| Percent of new launches that referenced the guide pre-launch \| >80% \| 50-80% \| <50% \| +\| Time to ship a clarification \| <1 week \| 1-4 weeks \| >4 weeks \| + +If multiple metrics are failing simultaneously, the guide needs a refresh, not just maintenance. + +--- + +## When to retire and rewrite + +Sometimes maintenance is not enough. Signs the guide needs a rewrite: + +- The brand has shifted enough that >30% of the guide no longer applies +- The audience or category has shifted enough that the brand position is dated +- A new owner cannot make sense of the structure +- The guide reads as if it was written for a different company +- Compliance has fallen below 60% across multiple audits + +Rewriting is not a maintenance task. It is a separate brand project. The maintenance playbook ends when the rewrite begins. + +--- + +## Sign-off + +Maintenance plan accepted by: + +- Brand owner: [Name, date] +- Council members: [Names, date] +- Executive sponsor: [Name, date] + +Next quarterly review: [Date] diff --git a/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md b/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md new file mode 100644 index 0000000..a55b540 --- /dev/null +++ b/dist/pi/.agents/skills/brand-style-guide/references/style-guide-template.md @@ -0,0 +1,407 @@ +# [Brand Name] Style Guide + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Maintained by: [Team or person] +Format: This document is canonical. Other formats (PDF, web page, Figma) are views of this document. + +--- + +## How to use this guide + +[1 to 2 paragraphs explaining what the guide is for, who it serves, and where to go with questions.] + +Quick links: +- [Logo files](#logo-files) +- [Color values](#color-values) +- [Typography](#typography) +- [Voice cheat sheet](#voice) +- [Dos and don'ts](#dos-and-donts) + +--- + +## 1. Story + +### Origin +[1 to 3 paragraphs. Why this brand exists. The problem it solves. The moment it began.] + +### Mission +[One sentence. What we are trying to do in the world.] + +### Vision +[One sentence. The future we are pulling toward.] + +### Values + +We hold [N] values. + +[Value 1] +[What it means in practice. 2 to 3 sentences. Include a behavioral example.] + +[Value 2] +[Same structure.] + +[Value 3] +[Same structure.] + +### Positioning + +[The positioning statement. One paragraph. What we offer, to whom, and what makes us different.] + +### Audience + +Primary: [Who, with specificity] + +Secondary: [Who, briefly] + +Anti-personas: [Who we are not for] + +### What we are not + +- [Thing we explicitly reject] +- [Thing we explicitly reject] +- [Thing we explicitly reject] + +--- + +## 2. Logo system + +### Primary logo + +[Image of primary logo] + +[Description: what it is, what it represents, when to use it.] + +### Wordmark + +[Image of wordmark] + +[Description and usage.] + +### Symbol / glyph + +[Image of glyph] + +[Description and usage.] + +### Lockup variations + +[Images of horizontal, stacked, square variants.] + +### Construction + +[Image showing construction grid, proportions, key relationships.] + +### Clear space + +[Image showing minimum clear space around the logo.] + +The logo requires minimum clear space equal to [X] on all sides. + +### Minimum sizes + +\| Format \| Minimum size \| +\|---\|---\| +\| Digital primary \| [Xpx] wide \| +\| Print primary \| [Xmm] wide \| +\| Favicon \| [Xpx] \| +\| Mobile \| [Xpx] \| + +### Color treatments + +Allowed: +- Full color on white +- Full color on light backgrounds (with [contrast rule]) +- Single color on light backgrounds +- White (knockout) on dark backgrounds +- Single color black + +Forbidden: +- [Specific forbidden treatment with example image] +- [Specific forbidden treatment with example image] + +### Logo files + +\| File \| Use case \| Path \| +\|---\|---\|---\| +\| logo-primary.svg \| Web primary \| /brand/logo/primary.svg \| +\| logo-wordmark.svg \| Tight horizontal \| /brand/logo/wordmark.svg \| +\| logo-symbol.svg \| App icon, favicon \| /brand/logo/symbol.svg \| +\| logo-monogram.svg \| Tiny contexts \| /brand/logo/monogram.svg \| +\| [more files] \| \| \| + +--- + +## 3. Color + +### Primary palette + +\| Name \| Hex \| RGB \| Use \| +\|---\|---\|---\|---\| +\| [Name] \| #XXXXXX \| (R,G,B) \| [Use case] \| +\| [Name] \| #XXXXXX \| (R,G,B) \| [Use case] \| + +### Secondary palette + +[Same table structure] + +### Neutrals + +[Same table structure] + +### Semantic colors + +\| Name \| Hex \| Use \| +\|---\|---\|---\| +\| Success \| #XXXXXX \| Positive states, confirmations \| +\| Warning \| #XXXXXX \| Caution, attention needed \| +\| Error \| #XXXXXX \| Errors, destructive actions \| +\| Info \| #XXXXXX \| Neutral information \| + +### Dark mode variants + +\| Color \| Light mode \| Dark mode \| +\|---\|---\|---\| +\| Brand primary \| #XXXXXX \| #XXXXXX \| +\| Body text \| #XXXXXX \| #XXXXXX \| +\| Surface \| #FFFFFF \| #XXXXXX \| + +### Contrast ratios + +[For each meaningful pairing, document the ratio and pass/fail.] + +\| Pairing \| Ratio \| WCAG \| +\|---\|---\|---\| +\| Brand primary on white \| X.X:1 \| Pass AA / Pass AAA \| +\| Body text on white \| X.X:1 \| Pass AA \| + +### Allowed pairings + +[List or visual showing which colors work together.] + +### Forbidden pairings + +[List or visual showing combinations not to use.] + +--- + +## 4. Typography + +### Display typeface + +[Typeface name] + +[Sample at large size] + +Used for: [Headlines, hero copy, brand moments] + +Weights used: [list] + +### Body typeface + +[Typeface name] + +[Sample at body size] + +Used for: [Long-form reading, paragraphs] + +Weights used: [list] + +### Monospace (if applicable) + +[Typeface name] + +Used for: [Code, technical data] + +### Type scale + +\| Step \| Size \| Weight \| Line height \| Letter spacing \| Use \| +\|---\|---\|---\|---\|---\|---\| +\| Display 1 \| 64 \| 700 \| 1.0 \| -0.02em \| Hero headlines \| +\| Display 2 \| 48 \| 700 \| 1.05 \| -0.01em \| Section headers \| +\| H1 \| 36 \| 700 \| 1.1 \| 0 \| Page titles \| +\| H2 \| 28 \| 600 \| 1.2 \| 0 \| Section titles \| +\| H3 \| 22 \| 600 \| 1.3 \| 0 \| Sub-sections \| +\| Body Large \| 18 \| 400 \| 1.5 \| 0 \| Lead paragraphs \| +\| Body \| 16 \| 400 \| 1.6 \| 0 \| Default body \| +\| Small \| 14 \| 400 \| 1.5 \| 0 \| Captions, metadata \| +\| Caption \| 12 \| 400 \| 1.4 \| 0.01em \| Footnotes, labels \| + +### Web fallback stack + +``` +font-family: '[Brand display]', '[OS fallback 1]', '[OS fallback 2]', sans-serif; +``` + +### Open-source alternatives + +For contexts where the licensed brand fonts are impractical (third-party tools, embeds), use: + +- Display alternative: [Open-source typeface name] +- Body alternative: [Open-source typeface name] + +### Forbidden treatments + +- [No fake italics] +- [No fake bold] +- [No all-caps body text] +- [Other forbidden treatments] + +--- + +## 5. Imagery and illustration + +### Photography + +Subject matter: [What we photograph] + +Style: [Composition, lighting, color treatment] + +What we reject: [Stock photo aesthetics, specific cliches] + +Examples: +[Include 4 to 6 example images] + +### Illustration + +Style: [Description] + +Color use: [Rules] + +Examples: +[Include 4 to 6 example illustrations] + +### Iconography + +Style: [Filled / outline / mixed] + +Grid: [Base grid size] + +Stroke weight: [Specification] + +Set: +[Include the icon set or rules for adding new icons] + +--- + +## 6. Voice and tone + +### Voice attributes + +We sound: [adjective], [adjective], [adjective], [adjective], [adjective]. + +We do not sound: [opposite], [opposite], [opposite], [opposite], [opposite]. + +\| We are \| We are NOT \| +\|---\|---\| +\| [Adjective] \| [What it could tip into] \| +\| [Adjective] \| [What it could tip into] \| +\| [Adjective] \| [What it could tip into] \| + +### Tone shifts + +\| Context \| Tone \| +\|---\|---\| +\| Onboarding \| [Description] \| +\| Error states \| [Description] \| +\| Success states \| [Description] \| +\| Marketing \| [Description] \| +\| Support \| [Description] \| +\| Legal \| [Description] \| + +### Vocabulary preferences + +Use: [Words and phrases that fit] + +Avoid: [Words and phrases that do not fit] + +### Sample copy + +Bad (off-voice): +> [Example] + +Good (on-voice): +> [Example] + +--- + +## 7. Applications + +### Web + +[Show 2 to 3 example layouts: homepage, product page, blog template] + +### Email + +[Show template, signature, transactional examples] + +### Social + +[Show post templates, profile imagery, story formats] + +### Print (if applicable) + +[Show business cards, letterhead, print examples] + +### Packaging (if applicable) + +[Show packaging examples] + +### Internal documents + +[Show slide template, report template, proposal template] + +--- + +## 8. Dos and don'ts + +### Logo + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example with caption] \| [Visual example with caption] \| +\| \| \| + +### Color + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Type + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Composition + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Voice + +\| Do \| Don't \| +\|---\|---\| +\| "[Example phrase]" \| "[Example phrase]" \| +\| \| \| + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial publication \| + +--- + +## Contact + +Questions or requests for clarification: [contact info] + +To suggest changes: [process] diff --git a/dist/pi/.agents/skills/brand-voice/SKILL.md b/dist/pi/.agents/skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b5c55f1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/SKILL.md @@ -0,0 +1,193 @@ +--- +name: brand-voice +description: "Develop or document a complete brand voice and tone system covering voice attributes, tone shifts by context, vocabulary preferences, grammar rules, and copy examples. Use this skill whenever the user wants to define how a brand sounds, write a voice and tone document, audit existing copy for voice consistency, train a team or AI assistant on brand voice, or refine the personality of brand writing. Triggers on brand voice, voice and tone, tone of voice, writing voice, brand personality, copy voice, voice document, voice guidelines, how should we write, voice training, voice audit. Also triggers when the user has copy that 'feels off' and the underlying issue is voice, even if not stated explicitly." +category: brand +catalog_summary: "Voice attributes, tone shifts, vocabulary, paired-example library" +display_order: 4 +--- + +# Brand Voice + +Define how a brand sounds in writing. Document it in a way that anyone (writer, designer, founder, AI assistant) can apply it consistently. + +This skill produces a standalone voice document that can either live in the brand style guide or feed into it. + +--- + +## When to use + +- Defining brand voice for the first time +- Auditing existing copy for voice consistency +- Training a team, freelancer, or AI assistant on the brand voice +- Refining a voice that exists but is inconsistent across applications +- Adapting voice when a brand evolves (new audience, new positioning) + +## When NOT to use + +- Writing specific copy (use `content-and-copy`) +- Brand visual identity work (use `brand-identity`) +- Documenting a complete brand system (use `brand-style-guide`, which incorporates voice) +- Initial brand exploration (use `brand-ideation`) + +--- + +## Required inputs + +- The brand and its positioning +- The audience and what they need to hear +- 5 to 10 examples of existing brand writing (if any) +- 3 to 5 reference brands whose voice resonates with where this brand should go +- Any voice attributes already specified in the brief + +--- + +## The framework: 4 layers + +Voice has four layers, stacked. Each layer constrains the one below it. + +### Layer 1: Voice attributes + +The constants. The personality traits that define how the brand sounds across every context. + +Pick 3 to 5 attributes. Pair each with what it is NOT (the failure mode if overdone). + +Common attribute pairings (NOT a menu - generate your own): + +- Confident, not arrogant +- Direct, not blunt +- Warm, not saccharine +- Witty, not sarcastic +- Smart, not academic +- Honest, not harsh +- Playful, not silly +- Practical, not boring +- Bold, not loud +- Curious, not unfocused + +The "not" half is what saves writers from overshooting. "Confident" alone produces swagger. "Confident, not arrogant" tells writers where the line is. + +### Layer 2: Tone shifts + +Voice is constant. Tone adapts to context. + +Map the major contexts the brand writes in. For each, document how voice expresses differently. + +Common contexts: + +\| Context \| Tone shift \| +\|---\|---\| +\| Onboarding \| Warmer, more enthusiastic, slightly slower pace \| +\| Hero / marketing \| Confident, signature voice fully on \| +\| Product copy / UX \| Direct, helpful, brief \| +\| Error messages \| Calm, matter-of-fact, no apology theater \| +\| Success states \| Brief celebration, redirect to next action \| +\| Empty states \| Helpful, slightly playful, suggest action \| +\| 404 / not found \| Self-aware, light, points the way home \| +\| Account deletion / cancellation \| Quiet, respectful, no jokes \| +\| Pricing \| Direct, transparent, confidence-inspiring \| +\| Legal / TOS \| Plain language version sits next to the legal version \| +\| Support / help center \| Patient, thorough, no condescension \| +\| Crisis communication \| Calm, factual, accountable \| +\| Product announcements \| Excited but not breathless \| +\| Email subject lines \| Specific, never click-bait \| + +Voice stays consistent across all of these. Tone is what shifts. + +### Layer 3: Vocabulary and grammar + +The granular dial settings. + +Vocabulary preferences: + +- Words and phrases the brand uses +- Words and phrases the brand avoids +- Words the brand has redefined (if any) - e.g., a SaaS product calling its features "huddles" instead of "meetings" +- Industry jargon: keep it (signals expertise) or strip it (signals approachability) +- Sentence-opening preferences (some brands lean on imperatives, some on questions, some on statements) + +Grammar and style: + +- Contractions (use them = casual, avoid them = formal) +- Sentence length default (short = punchy, medium = considered, long = literary) +- Punctuation marks favored or avoided (em dash is famously polarizing) +- Pronouns ("we" / "you" / "I") +- Capitalization style (title case, sentence case, all-lowercase deliberate) +- Number formatting (spell out under ten, or always digits) +- Oxford comma (use or skip) +- Active vs passive voice (most brands prefer active) + +### Layer 4: Examples and patterns + +Voice is taught through examples, not rules. Build a library. + +For each major content type, show: + +- Bad example (off-voice) +- Good example (on-voice) +- Brief note on what changed + +Common content types to cover: + +- Headline +- Subheadline +- Hero CTA +- Feature description +- Testimonial intro +- Email subject line +- Email opening +- Push notification +- Error message +- Success message +- About page paragraph +- Social post +- Sales page paragraph + +Aim for 15 to 25 paired examples. This is the most-used part of the voice doc in practice. + +--- + +## Workflow + +1. Audit existing copy if it exists. Identify what is on-brand, what is off, what patterns recur. +2. Layer 1: Voice attributes. Generate 5 to 8 candidates with "we are X, not Y" framing. Pick 3 to 5. +3. Layer 2: Tone shifts. List 8 to 15 contexts the brand writes in. Note the tone shift for each. +4. Layer 3: Vocabulary and grammar. Define preferences. Skip default rules unless they actually distinguish the brand. +5. Layer 4: Examples. Build the paired-example library. 15 to 25 minimum. +6. Stress-test. Pick a fresh writing brief and apply the voice doc. Does it produce on-voice copy? If not, the doc is incomplete. +7. Document. Use the template in [`references/voice-document-template.md`](references/voice-document-template.md). +8. Distribute. Voice docs only work if they get used. Make the doc easy to reference inline (link to it from CMS templates, brief templates, AI assistant prompts). + +--- + +## Failure patterns + +- Generic attributes ("friendly, professional, approachable"). Every brand says this. Means nothing. Pick attributes that genuinely distinguish. +- No "we are NOT" pairings. Without the rejection, attributes drift toward extremes. +- Voice doc with no examples. Rules without examples cannot be applied. +- Examples that are obviously bad and obviously good. Real voice work shows nuanced shifts, not cartoonish before/after. +- Skipping tone shifts. Treating voice as one-size-fits-all leads to a brand that sounds wrong in error states or legal contexts. +- Documenting aspirational voice. If the brand does not actually sound this way today and has no plan to shift, the doc is fiction. +- Voice without distribution. A perfect doc that no one references is worth nothing. + +--- + +## Output format + +Default output is a markdown document at `voice.md` in the brand folder. Sections: + +1. Voice attributes (with we-are-not pairings) +2. Tone shifts by context +3. Vocabulary preferences +4. Grammar and style rules +5. Paired examples library (the most-used section) +6. Anti-patterns (specific phrases or constructions to avoid) +7. References (the brands and writers we are inspired by) + +This doc can stand alone or feed into `brand-style-guide`. + +--- + +## Reference files + +- [`references/voice-document-template.md`](references/voice-document-template.md) - Fillable template. +- [`references/voice-frameworks.md`](references/voice-frameworks.md) - Detailed walkthrough of the Nielsen Norman 4 dimensions, Jung archetypes, and the "we are X not Y" approach. diff --git a/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md b/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md new file mode 100644 index 0000000..b0362e1 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/references/voice-document-template.md @@ -0,0 +1,324 @@ +# [Brand Name] Voice and Tone + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Maintained by: [Team or person] + +--- + +## How to use this doc + +[1 to 2 paragraphs. Who this is for, when to reference it, where to ask questions.] + +For most writers, the section that gets used most is the paired examples library at the end. When unsure how to write something, find the closest example and pattern-match. + +--- + +## Voice attributes + +We sound: + +- [Adjective 1], not [opposite] +- [Adjective 2], not [opposite] +- [Adjective 3], not [opposite] +- [Adjective 4], not [opposite] +- [Adjective 5], not [opposite] + +### What each attribute means + +[Adjective 1] +[2 to 3 sentences. What this looks like in practice. Include one specific example phrase.] +Failure mode: when [Adjective 1] tips into [opposite], we sound [bad outcome]. + +[Adjective 2] +[Same structure.] + +[Adjective 3] +[Same structure.] + +[Adjective 4] +[Same structure.] + +[Adjective 5] +[Same structure.] + +--- + +## Tone shifts by context + +Voice stays constant. Tone adjusts based on what the user is doing and feeling. + +\| Context \| Tone \| +\|---\|---\| +\| Hero / marketing \| [How tone shifts] \| +\| Onboarding \| [How tone shifts] \| +\| Product copy / UX labels \| [How tone shifts] \| +\| Empty states \| [How tone shifts] \| +\| Error messages \| [How tone shifts] \| +\| Success states \| [How tone shifts] \| +\| 404 / not found \| [How tone shifts] \| +\| Account deletion / cancellation \| [How tone shifts] \| +\| Pricing \| [How tone shifts] \| +\| Legal / TOS \| [How tone shifts] \| +\| Support / help center \| [How tone shifts] \| +\| Crisis communication \| [How tone shifts] \| +\| Email subject lines \| [How tone shifts] \| +\| Social posts \| [How tone shifts] \| + +--- + +## Vocabulary preferences + +### Words and phrases we use + +[Bulleted list of vocabulary that fits the brand. Be specific.] + +- [Word or phrase] +- [Word or phrase] +- [Word or phrase] + +### Words and phrases we avoid + +[Bulleted list of vocabulary that does not fit. Often these are category cliches or fluff words.] + +- [Word or phrase] - [optional note on why] +- [Word or phrase] +- [Word or phrase] + +### Redefined words (if any) + +If the brand uses standard words in non-standard ways, document here. + +\| Standard term \| We say \| Why \| +\|---\|---\|---\| +\| [Standard] \| [Our term] \| [Reasoning] \| + +### Industry jargon + +We [keep / strip] industry jargon. [1 to 2 sentences explaining the call.] + +--- + +## Grammar and style + +\| Decision \| Our standard \| +\|---\|---\| +\| Contractions \| [Use / avoid] \| +\| Default sentence length \| [Short / medium / long] \| +\| Em dashes \| [Use / avoid] \| +\| Oxford comma \| [Yes / no] \| +\| Pronouns \| [we / you / I patterns] \| +\| Capitalization (headlines) \| [Title / sentence / lowercase] \| +\| Numbers under 10 \| [Spell out / digits] \| +\| Active vs passive \| [Active default] \| +\| Hashtags (in social) \| [In body / in comment / not used] \| +\| Exclamation points \| [Frequency rule] \| +\| Emoji \| [Use / avoid / context-specific] \| + +--- + +## Paired examples library + +The most-used part of this doc. When in doubt, find the closest example and pattern-match. + +### Headlines + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +[Brief note on what changed and why.] + +--- + +### Subheadlines + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Hero CTA + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Feature description + +Off-voice: +> [Bad example, 2 to 3 sentences] + +On-voice: +> [Good example, 2 to 3 sentences] + +--- + +### Testimonial intro + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Email subject line + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Email opening + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Push notification + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Error message + +Off-voice: +> "An error has occurred. Please try again later." + +On-voice: +> [Good example specific to this brand] + +--- + +### Success message + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Empty state + +Off-voice: +> "No items found." + +On-voice: +> [Good example specific to this brand] + +--- + +### About page paragraph + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Social post + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Sales page paragraph + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### 404 page + +Off-voice: +> "404. Page not found." + +On-voice: +> [Good example specific to this brand] + +--- + +### Cancellation flow copy + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +## Anti-patterns + +Specific phrases or constructions that NEVER appear in our writing: + +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] + +--- + +## References + +Brands and writers whose voice we admire and learn from: + +- [Brand or writer] - [What we learn from them] +- [Brand or writer] - [What we learn from them] +- [Brand or writer] - [What we learn from them] + +We are not copying these voices. We are calibrating against them. + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial publication \| + +--- + +## How to evolve this doc + +[1 paragraph on how the team proposes voice updates, who reviews, who approves.] + +Voice should be reviewed: +- Annually as a minimum +- After any major audience shift +- After any major positioning change +- When it consistently fails the "stress test" (writing produced from this doc no longer feels right) diff --git a/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md b/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md new file mode 100644 index 0000000..8d57718 --- /dev/null +++ b/dist/pi/.agents/skills/brand-voice/references/voice-frameworks.md @@ -0,0 +1,188 @@ +# Voice Frameworks + +Three established frameworks for thinking about brand voice. Each emphasizes a different layer. Mix and match. None is "right." Each is a tool. + +--- + +## Framework 1: The "We are X, not Y" approach + +The most pragmatic framework. Start here if you have not done voice work before. + +### How it works + +Pick 3 to 5 voice attributes. For each, name what the attribute is NOT. The pairing is the framework. + +``` +We are confident, not arrogant. +We are direct, not blunt. +We are warm, not saccharine. +We are smart, not academic. +``` + +### Why the "not Y" matters + +Single-word attributes are aspirational. They float. Without a counterweight, writers (and AI assistants) overshoot. + +- "Confident" alone = swagger, bravado, dismissiveness +- "Direct" alone = curtness, coldness, rudeness +- "Warm" alone = mushy, performative, over-friendly +- "Smart" alone = jargon-heavy, exclusionary + +Each "not Y" tells the writer where the line is. It is the guardrail. + +### Picking attributes + +Avoid generic words every brand claims. "Friendly," "professional," "approachable," "trustworthy," "innovative" are filler. They do not distinguish. + +Better attributes are specific enough to make some other brand a bad fit. If you can imagine your competitor saying the same word, the word is too generic. + +A good list: +- Distinctive (no other brand in your category would put it the same way) +- Honest (you actually sound this way, or are committed to) +- Useful (writers can apply it to a real piece of copy) +- Limited (3 to 5 attributes; 8+ becomes unworkable) + +### Stress test + +Take a recent piece of copy. Score it 1 to 5 against each attribute. If it scores below 3 on any, the copy is off-voice. If it scores 5 across the board, the attributes might be too generous. + +Apply the test to a competitor's copy. If their copy scores high on your attributes, the attributes are not distinctive enough. + +--- + +## Framework 2: The Nielsen Norman 4 dimensions + +Nielsen Norman Group introduced a model that treats voice as four sliders rather than a list of adjectives. + +### The 4 sliders + +1. Funny vs serious +Where on the spectrum from playful to earnest does the brand sit? + +- Far funny: jokes are signature, even in support content +- Mid: occasional wit, mostly straightforward +- Far serious: humor is rare and only when context invites it + +2. Formal vs casual +How structured and decorous is the writing? + +- Far formal: full sentences, correct grammar, no contractions, professional register +- Mid: standard professional, occasional contractions +- Far casual: contractions, fragments, conversational rhythms, slang where appropriate + +3. Respectful vs irreverent +Does the brand treat its audience and category with deference, or does it poke fun? + +- Far respectful: customers are addressed with care, category is treated with seriousness +- Mid: respectful default, willing to be playful at edges +- Far irreverent: category cliches get punctured, the brand is willing to mock conventions (its own and competitors') + +4. Matter-of-fact vs enthusiastic +What is the energy level? + +- Far matter-of-fact: calm, even, measured +- Mid: warm but not effusive +- Far enthusiastic: animated, expressive, energetic + +### How to use + +Plot the brand on each of the four. The position is the brand's voice signature. + +Example: +- Funny vs serious: 30 (mostly serious, occasional dryness) +- Formal vs casual: 70 (mostly casual, contractions standard) +- Respectful vs irreverent: 40 (respectful default, willing to be playful) +- Matter-of-fact vs enthusiastic: 50 (warm but measured) + +This produces a recognizable signature distinct from competitors plotted on the same axes. + +### Why this framework + +It forces choices. Adjective lists let you claim "warm AND professional AND witty AND smart." The dimensions force you to commit to a position, which is what voice actually is. + +### When to use it + +Best as a complement to the "We are X, not Y" approach. Use the dimensions to plot the brand. Use the attributes to give writers actionable language. + +--- + +## Framework 3: Brand archetypes (the Jung-derived model) + +A model from depth psychology, applied to brands by Margaret Mark and Carol Pearson. Twelve archetypes, each with a recognizable voice pattern. + +### The 12 archetypes + +\| Archetype \| Voice signature \| Example brands (illustrative, not endorsements) \| +\|---\|---\|---\| +\| Innocent \| Pure, optimistic, simple \| Wholesome consumer brands, family-oriented \| +\| Sage \| Wise, considered, knowledgeable \| Educational publishers, research institutions \| +\| Explorer \| Adventurous, free, restless \| Outdoor brands, travel platforms \| +\| Outlaw \| Rebellious, defiant, anti-establishment \| Disruptors, challenger brands \| +\| Magician \| Visionary, transformative, mystical \| Tech that "changes everything" \| +\| Hero \| Brave, decisive, achievement-oriented \| Athletic brands, ambitious tools \| +\| Lover \| Sensual, intimate, devoted \| Premium consumer goods, luxury \| +\| Jester \| Playful, irreverent, lighthearted \| Entertainment, fast food, fun-first \| +\| Everyman \| Down-to-earth, relatable, fair \| Mass market, "for everyone" \| +\| Caregiver \| Compassionate, generous, protective \| Healthcare, family services \| +\| Ruler \| Authoritative, sophisticated, in-control \| Premium brands, enterprise \| +\| Creator \| Imaginative, expressive, original \| Creative tools, artistic brands \| + +### How to use + +Pick a primary archetype. Optionally a secondary. The combination is the voice signature. + +A brand might be primary Sage with secondary Caregiver. That voice is wise + protective. It would write differently than a Sage + Outlaw (wise + defiant). + +### Strengths + +- Forces a clear voice character rather than a list of adjectives +- The archetypes are recognizable, which helps writers visualize the voice +- Distinguishes brands that might otherwise sound similar + +### Weaknesses + +- Some archetypes are dated or culturally specific +- "Pick one" is harder than it sounds; brands often span 2 or 3 +- Easy to pick aspirational archetypes the brand does not actually live + +### When to use it + +When the brand has a distinctive personality you want to crystallize. Less useful for utilitarian or category-defining brands. + +--- + +## Combining frameworks + +The three frameworks are not mutually exclusive. They emphasize different layers. + +A useful combination: + +1. Archetype for the high-level character +2. NN/g dimensions for the calibration +3. "We are X, not Y" attributes for the daily writing guardrails + +Example for a fictional brand: + +- Archetype: Sage (primary) + Everyman (secondary) +- Dimensions: 30 funny / 60 casual / 50 respectful / 40 enthusiastic +- Attributes: + - Knowledgeable, not academic + - Plain-spoken, not basic + - Honest, not harsh + - Patient, not condescending + +Each layer adds resolution. The archetype gives character. The dimensions give calibration. The attributes give writers the daily tool. + +--- + +## Choosing a framework + +If you have done voice work before and know what you want, the "We are X, not Y" approach alone is enough. + +If the brand voice is undefined and you need to start from zero, begin with archetypes (high-level character), move to dimensions (calibration), then derive attributes (daily guardrails). + +If voice work has been done but is too vague, the dimensions framework is the best clarifier. + +If voice has been documented but writers do not know how to apply it, the attributes framework is the missing piece. + +The frameworks are tools. The output of voice work is consistent writing across the brand. If the writing is consistent, the framework worked. If it is not, no framework is the right one yet. diff --git a/dist/pi/.agents/skills/calculator-design/SKILL.md b/dist/pi/.agents/skills/calculator-design/SKILL.md new file mode 100644 index 0000000..a9be8c1 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/SKILL.md @@ -0,0 +1,296 @@ +--- +name: calculator-design +description: "Designing interactive calculators (ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments) that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. Honest about vanity-calculator (no real value), lead-trap (hides the answer behind email), and transparent-decision-tool (gives the result and earns the email through tiered value) patterns. Triggers on calculator, ROI calculator, pricing estimator, savings calculator, custom calculator, interactive tool, decision tool, financial calculator. Also triggers when an audience needs a calculation-driven lead magnet, when a vanity calculator is producing leads but no qualified ones, or when a calculator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive calculators that deliver decision-support value while qualifying leads. Distinguishes vanity-calculator (no real value) from lead-trap (hides answer behind email) from transparent-decision-tool (gives genuine value, captures leads honestly)" +display_order: 2 +--- + +# Calculator Design + +A senior growth practitioner's playbook for designing interactive calculators that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments. The discipline of building a tool the audience actually trusts. + +Most calculators on the web are bait. Random multipliers behind official-looking math; an "Industry Average" number that does not cite a source; the result hidden behind a contact-sales form. The calculator captures emails because the format implies calculation; the leads are unqualified because the calculator did not actually help anyone decide anything. + +The calculators that work as compounding assets do something different. They give the audience a result they can defend to a stakeholder. They show the methodology so the result is interrogatable. They capture leads through value (a PDF report, a save-and-compare account, a custom analysis) rather than through manipulation. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the calculator-specific methodology (calculation transparency, tiered value, methodology disclosure) lives here. + +The voice is the senior growth practitioner who has watched calculators earn long-term credibility and watched them burn it within weeks of launch. Practical, opinionated about transparency, willing to say when a calculator is the wrong investment for the goal. + +When to use this skill: scoping a calculator for the first time, auditing a calculator that converts but does not qualify, designing the methodology disclosure that earns audience trust, or deciding which features warrant the email gate. + +--- + +## What this skill covers + +This skill spans calculator design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology (when to invest in any magnet, format selection, audience-fit, follow-up sequence). Calculators are one specific lead-magnet type. +- `calculator-design` (this skill) is calculator-specific methodology (calculation transparency, tiered value, methodology disclosure, input design). +- `quiz-and-assessment-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `landing-page-copy` is the calculator landing page (downstream of calculator design). +- `pm-spec-writing` is writing the spec for engineers building the calculator. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: growth marketers, product marketers, marketing teams building lead-magnet calculators, agencies running growth-tooling work for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the calculator (handed off via `pm-spec-writing`). + +--- + +## The calculator decision: when calculators earn investment + +Before designing the calculator, decide whether a calculator is the right tool for the audience and the goal. + +Calculators earn investment when: + +- The audience faces a specific calculation as part of a decision. ROI on a software purchase, savings from a refinance, monthly cost of an expense, sizing for a service tier. Without a real calculation in the audience's actual workflow, the calculator becomes a vanity tool. +- The calculation is non-trivial. Multiplying two numbers does not need a calculator; calibrating across 5-10 inputs with branching logic does. +- The brand has methodology authority. The calculator's output has to be defensible. Brands without methodology authority (or unwilling to disclose methodology) often produce calculators audiences do not trust. +- The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation); the sequence has to use that signal. + +Calculators do NOT earn investment when: + +- The audience does not actually run this calculation. A calculator solving a problem the audience does not have produces low usage. +- The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" does not earn its build. +- The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend, the calculator becomes a vanity tool by necessity. +- A simpler magnet would serve the same audience and goal. Templates and checklists are cheaper to build and maintain than calculators; choose the calculator only when the calculation is the value. + +The decision is not "should we have a calculator"; it is "is the calculator the right next investment for this specific audience and goal." + +Detail in [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md). + +--- + +## Vanity-calculator vs lead-trap vs transparent-decision-tool + +The keystone framing. + +Vanity-calculator. Inputs and outputs that do not actually help anyone decide anything. "Calculate your marketing ROI" with random multipliers; "estimate your savings" with no defensible methodology. Looks impressive in a screenshot; helps nothing in a real decision. Cost: leads downloaded the result, found it useless, and remember the brand as the source of the useless tool. + +Lead-trap. Genuine calculation logic but the result is hidden behind an email gate. The user inputs 8 fields, hits "Calculate," and sees "enter your email to see your result." Manipulative; reader resents the friction; conversion drops below baseline because the audience can tell when the gate is bait rather than value-add. + +Transparent-decision-tool. Genuine calculation that gives the result immediately. Email gate for advanced features (PDF report, custom analysis, save-and-compare across scenarios) where the additional value justifies the ask. The reader gets the answer they came for; the brand gets the email through demonstrated generosity. + +The litmus test. After running the calculator, can a stranger in the target audience defend the result to a stakeholder? Can they cite the methodology behind the number? If yes, the calculator is a transparent-decision-tool. If they got a number with no defensible source, the calculator is vanity. If they could not see the result without giving an email, the calculator is a lead-trap. + +--- + +## Input design + +The calculator's inputs are the audience's first interaction. Bad input design loses the user before the calculation runs. + +The principle. Each input should be necessary for the calculation, easy for the user to provide, and respectful of the user's time. + +Necessary. If an input does not affect the output meaningfully, do not ask for it. Calculators that ask 18 inputs but only use 5 in the actual math signal that the form is collecting data for sales rather than for the calculation. The audience can tell. + +Easy to provide. Use defaults from honest assumptions. "Average company size" preset to a reasonable industry baseline. "Typical conversion rate" preset to a defensible number. Defaults reduce the cognitive load and let the user adjust where their context differs. + +Respectful of time. Group related inputs visually. Show only the fields the user is currently working through (progressive disclosure where it helps). Indicate progress so the user knows how many steps remain. + +Input types. + +- Numeric (revenue, customer count, monthly cost). The most common. Often warrants tooltip explaining what the number represents. +- Slider (percentage estimates, conversion rates). Good for ranges where exact values are not knowable. +- Dropdown (industry, company size, region). Good for predefined categories. +- Toggle (feature on/off, scenario A vs B). Good for binary choices. +- Free text (only when the value is genuinely user-specific and cannot be calculated). Use sparingly; free text is friction. + +Detail in [`references/input-design-patterns.md`](references/input-design-patterns.md). + +--- + +## Calculation logic transparency + +The defensibility of the result is the calculator's credibility currency. + +The principle. The audience should be able to inspect the methodology. Either the calculation is shown openly, or a methodology link explains it, or the team is willing to share the spec on request. + +Methodology disclosure options. + +- Inline formulas. "Your savings = (current cost x 12) - (our cost x 12) + implementation savings of $X." Explicit and verifiable. +- Methodology page. A link from the calculator to a page explaining the assumptions, sources, and formulas. The audience can read if they care; defaults are good for those who do not. +- Source citations. When inputs come from external benchmarks ("Industry Average: 14 percent"), cite the source. Uncited benchmarks erode trust. +- Assumption list. A list of the calculator's assumptions, plain-language. "We assume you are comparing month-over-month after a 3-month implementation period." + +The vanity-calculator failure. Assumptions hidden, sources missing, formulas opaque. The audience uses the tool, gets a number, and cannot defend it. The brand is invisible in their next conversation about the decision because the calculator did not earn the credibility. + +The transparent-tool win. Assumptions visible, sources cited, formulas inspectable. The audience uses the tool, gets a number, and can defend it. The brand is in the conversation because the audience cites the calculator as their source. + +Detail in [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md). + +--- + +## Result presentation + +The result is the calculator's product. Bad result presentation wastes the calculation work. + +The principle. The result should be specific, contextualized, and actionable. + +Specific. A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." + +Contextualized. Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." The context makes the number interpretable. + +Actionable. What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step is the calculator's bridge from result to action. + +Result-presentation patterns. + +- Headline number. The single most important output, large and prominent. +- Breakdown. Sub-results that explain how the headline number was calculated. +- Visualization. Bar chart, comparison table, or simple graphic that helps the user see the relationship. +- Scenario comparison. "Your current state vs the optimized state." Useful when the calculator is illustrating a delta. + +Avoid. + +- Burying the result. The result should be visible immediately, not after a scroll. +- Result followed by 5 paragraphs of marketing. The result is what the user came for; marketing belongs after, not before. +- Result that requires re-entering all inputs to view. Persist inputs and results within the session. + +Detail in [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md). + +--- + +## Email-capture decision + +What to gate, what to give freely. + +The principle. Give the audience the result they came for. Gate the additional value (PDF report, custom analysis, save-and-compare, saved scenarios across visits). + +What to give freely. + +- The headline result. +- The breakdown of how the result was calculated. +- A visualization of the result. +- The methodology disclosure. + +What to gate (with email or account creation). + +- A formatted PDF report the user can share or save. +- A saved scenario the user can revisit and compare against alternatives. +- A custom analysis (a deeper version of the calculation, often delivered later). +- Email-based notifications when assumptions change or new benchmarks emerge. + +The lead-trap failure. The headline result is gated. The user inputs 8 fields, hits Calculate, sees "enter your email to see your result." Conversion drops because the audience perceives the manipulation. The lead-trap pattern is short-term thinking. + +The transparent-tool win. The result is free; the additional value is gated. Conversion is honest; lead quality is high because the lead opted in for the additional value, which signals real interest. + +Detail in [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md). + +--- + +## Tiered-value structures + +The architecture that lets calculators capture leads honestly. + +The principle. The calculator delivers tiered value: free immediate result + gated advanced features. + +Tier 1 (free, no gate): the headline result, the breakdown, the methodology, basic visualization. + +Tier 2 (email-gated): a formatted PDF, a saved scenario, an emailed copy of the result. + +Tier 3 (account or sign-up gated): save-and-compare across multiple scenarios over time, advanced analysis, integration with the brand's product or service. + +The tier-design discipline. + +- Each tier should add real value over the previous. If Tier 2 is just "the same result in a PDF," the tier does not justify the email ask. +- The gate at each tier should be matched to the value. Email for Tier 2; account creation only for Tier 3. +- The tier transitions should feel natural. The user gets the free result, sees the additional value visibly, and chooses whether to opt in for it. + +Worked example. + +A B2B SaaS pricing calculator. + +- Tier 1 (free): the user enters team size and use case, sees the recommended plan and the estimated monthly cost. Methodology link explains tier breakpoints. +- Tier 2 (email-gated): a PDF showing the recommended plan, the calculation, and a comparison to alternative plans the user might consider. +- Tier 3 (account-gated): a saved scenario the user can revisit; ability to compare against historical pricing if the calculator is used periodically; option to receive notifications if pricing or recommended plans change. + +Each tier earns its gate. + +Detail in [`references/tiered-value-structures.md`](references/tiered-value-structures.md). + +--- + +## Calculator anti-patterns + +Patterns that look like calculators but degrade trust. + +The lead-trap. Result hidden behind email. Detail in keystone framing. + +The vanity output. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? + +The hidden-methodology calculator. No way to see the math; no methodology page; no assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The interrogation form disguised as calculator. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The misleading-baseline calculator. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. The audience that knows the industry sees the gap. + +The misaligned-units calculator. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The static-assumption calculator. Assumptions hardcoded in 2022 that have not been updated. The calculator's outputs are stale. + +The mobile-broken calculator. Calculator works fine on desktop, breaks on mobile. The mobile audience either bounces or gets a worse experience that misrepresents the brand. + +Detail in [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-calculator-failures.md`](references/common-calculator-failures.md). + +- "Conversion rate is high; downstream conversion is near zero." Lead-trap or vanity-output pattern; the audience captured did not get value, did not engage with the follow-up, did not convert. +- "Audience visits the calculator, runs it once, never returns." Calculator does not produce a save-worthy or share-worthy result; no reason to come back. +- "Sales team says the calculator-sourced leads are unqualified." Calculator's audience-fit weak; the calculation does not match the buyer's actual decision. +- "We get questions about how the calculator works; we have no answer." Methodology not documented; the team cannot defend the calculator's outputs. +- "We updated the product; the calculator outputs are now wrong." No update cadence; the calculator drifted out of sync with the actual offering. +- "The calculator works; nobody uses it." Calculator hidden in the site; no distribution; the audience does not know it exists. +- "Our calculator looks like our competitor's." Generic calculator-template patterns produce generic calculators; the brand differentiation absent. +- "The form has 12 fields and 4 percent conversion." Interrogation-form pattern; the calculator is collecting data, not delivering value. +- "Audience trusts our brand; the calculator outputs feel arbitrary." Methodology disclosure missing; the brand's credibility does not transfer to the tool because the tool does not show its work. + +--- + +## The framework: 12 considerations for calculator design + +When designing or auditing a calculator, walk these 12 considerations. + +1. The calculator decision. Is a calculator the right investment, or would a simpler magnet serve? +2. Transparent-decision-tool, not vanity or lead-trap. Result is free; methodology is visible; gate is on additional value, not on the result. +3. Inputs are necessary, easy, respectful of time. Each input affects the math; defaults reduce friction; progressive disclosure where it helps. +4. Calculation methodology disclosed. Inline formulas, methodology page, source citations, or assumption list. +5. Result is specific, contextualized, actionable. Number with units; baseline for interpretation; clear next step. +6. Tiered value structure. Free immediate result; gated advanced features; each tier earns its gate. +7. Email-capture decision honest. Gate on real value-add (PDF, save-and-compare, custom analysis), not on the result the user came for. +8. Source attribution clear. Industry averages, benchmarks, and assumptions all cited or explained. +9. Mobile experience tested. Calculator works on the device the audience uses. +10. Update cadence defined. When inputs, benchmarks, or product details change, the calculator gets updated. +11. Distribution planned. The calculator's audience knows it exists. Landing page, navigation, content references all include the calculator. +12. Lead quality measured. Downstream conversion from calculator-sourced leads is the real metric, not surface conversion. + +The output of the framework is a calculator that delivers real decision-support value, earns the email through demonstrated generosity, and produces leads the team can convert downstream. + +--- + +## Reference files + +- [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md) - When a calculator is the right tool for the audience and goal, and when a simpler magnet would serve. +- [`references/input-design-patterns.md`](references/input-design-patterns.md) - Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. +- [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md) - Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. +- [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md) - Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. +- [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md) - What to give freely, what to gate. The lead-trap failure and the transparent-tool win. +- [`references/tiered-value-structures.md`](references/tiered-value-structures.md) - Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. +- [`references/methodology-disclosure-templates.md`](references/methodology-disclosure-templates.md) - Templates for assumption lists, methodology pages, source citations, formula explanations. +- [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md) - The patterns that look like calculators but degrade trust. +- [`references/common-calculator-failures.md`](references/common-calculator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: calculators earn the email when they would have been worth paying for + +The calculators that work as compounding assets are the ones the audience trusts. Not impressive screenshots. Not high conversion rates. Trust. The audience runs the calculator, gets a result they can defend, and remembers the brand as the source of the result they used in their actual decision. + +That is the bar. Below the bar are vanity-calculators (no real result) and lead-traps (result hidden until you pay with an email). Above the bar are transparent-decision-tools that give the audience the answer freely and capture leads through additional value the audience opts in for. + +The discipline is in the design choices. The methodology disclosure that earns credibility. The input design that respects the audience's time. The tiered value structure that makes the email-capture honest. The result presentation that makes the calculator's output usable in the audience's real conversation. The update cadence that keeps the calculator in sync with the offering it represents. + +When in doubt, ask: would the audience pay for this calculator if it were not free, and can they defend the result to a stakeholder after they use it? If yes to both, the calculator earns the email. If no to either, redesign or do not ship. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md b/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md new file mode 100644 index 0000000..8afc216 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculation-logic-transparency.md @@ -0,0 +1,200 @@ +# Calculation logic transparency + +Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. The defensibility of the result is the calculator's credibility currency. + +A calculator's output is only as trustworthy as the audience's ability to inspect how it was computed. Calculators that hide methodology produce numbers; calculators that disclose methodology produce defensible numbers. The difference shows up in whether the audience cites the calculator in stakeholder conversations. + +--- + +## The transparency principle + +The audience should be able to inspect the methodology if they care. + +Three levels of transparency, in increasing depth. + +Level 1: Inline. The methodology appears in the calculator itself, near the result. "Your annual savings: $14,200 = (current cost x 12) - (estimated new cost x 12) + first-year implementation savings of $X." + +Level 2: Methodology page. A linked page explaining the formulas, assumptions, and sources in detail. The result page links to it; users who want depth find it. + +Level 3: Spec on request. The team is willing to share the underlying spec, customer-data sources, or formula derivations on request. Useful for analytical or enterprise audiences who want full inspection. + +A calculator should at minimum support Level 1 or Level 2. Level 3 is optional and signals analytical credibility. + +--- + +## Inline formulas + +Show the math near the result. + +The pattern. Below or alongside the headline result, show the formula that produced it. + +Example: ROI calculator inline formula. + +``` +Annual savings: $14,200 + +Calculation: + Current annual cost: $36,000 ($3,000 / month x 12) + Estimated new annual cost: $24,000 ($2,000 / month x 12) + Annual savings: $36,000 - $24,000 = $12,000 + + First-year implementation savings: $2,200 + Total: $14,200 +``` + +The win. The audience can verify the math. They can adjust their inputs and predict how the result will change. They can defend the result to a stakeholder by citing the formula. + +When to use inline formulas. When the calculation is straightforward enough to display in a few lines. Most ROI, savings, and pricing calculators fit this pattern. + +When inline formulas hurt. When the calculation is so complex (multi-stage, with branching) that the formula display overwhelms the result. In those cases, link to a methodology page instead. + +--- + +## Methodology page + +A linked page explaining the calculation in depth. + +The pattern. The result page includes a "How this is calculated" or "Methodology" link. The link opens a page with formulas, assumptions, and sources. + +What a methodology page should include. + +- The central formulas in plain text (not just images). +- Each variable defined. +- Each assumption listed plainly. "We assume a 3-month implementation period." "We assume the user is comparing month-over-month." +- Sources for any external benchmarks. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025]." +- Worked example. A specific scenario with input values and the resulting calculation. +- Caveats. "This calculator does not account for [X]; for that, see [other resource]." + +The methodology page test. A skeptical reader of the methodology page should come away thinking "this is reasonable" or "I disagree with assumption Y, here is why." Either response is a sign the methodology is real and the audience can engage with it. + +Methodology pages and SEO. Methodology pages can themselves rank for search terms ("how is X calculated"), bringing additional traffic to the calculator. The page is not just transparency; it is also a content asset. + +--- + +## Source citations + +When the calculator uses external benchmarks or data, cite the source. + +The pattern. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025, page 23]." + +Why source citations matter. They signal that the benchmark is real, not invented. They let the skeptical user verify. They protect the brand if the benchmark is later disputed. + +Citation discipline. + +- Cite the most authoritative source available (industry report, academic paper, published study). +- Date the source. Benchmarks decay; an undated source could be from any year. +- Link to the source where possible. Inaccessible sources (paywalled reports cited from memory) are weaker than linked sources. +- If the source is internal customer data, say so. "Source: [Brand]'s customer cohort, n=200, 2024-2025." Internal sources are valid; honesty about their origin matters. + +The uncited-benchmark failure. "Industry Average: 14 percent" with no source. The audience that knows the industry sees the gap; the audience that does not know rolls the dice on whether to trust. Either way, credibility leaks. + +--- + +## Assumption lists + +A plain-language list of what the calculator assumes. + +The pattern. Either inline (near the result) or on the methodology page, list the assumptions in plain English. + +Example assumption list for a SaaS pricing calculator. + +- "We assume your team will use the platform daily." +- "We assume implementation takes 4-6 weeks." +- "We assume the productivity gains compound through year 1 and stabilize in year 2." +- "We assume your current solution costs include licenses, hosting, and 1 FTE for maintenance." +- "We do not account for [specific factors] in this estimate." + +Why assumption lists matter. They make the calculator's worldview visible. The audience can see whether the assumptions match their situation. If the assumptions diverge, the audience knows to discount the result accordingly. + +Honest assumptions vs flattering assumptions. Honest assumptions reflect the typical case; flattering assumptions reflect the case that produces the most attractive output. Audiences that catch flattering assumptions stop trusting the calculator. + +The assumption-decay problem. Assumptions need updating as the world changes. A calculator with assumptions from 2022 may have outdated benchmarks; review quarterly. + +--- + +## The methodology-authority spectrum + +Calculators sit on a spectrum from "fully transparent" to "fully opaque." Each position has tradeoffs. + +Fully transparent. All formulas, all assumptions, all sources visible. The audience can fully reconstruct the calculation. Trust is maximum; competitive risk (others copying the methodology) is highest. + +Largely transparent. Major formulas visible; minor weighting or proprietary elements glossed. The audience trusts the result; the brand keeps some IP. Common middle ground. + +Methodology-page transparent. The result is shown without inline formulas; the methodology page has the depth. The audience that cares finds the depth; the audience that does not, does not have to. + +Opaque. No methodology shown. The audience either trusts the brand or not; there is no inspection path. High competitive protection; low audience trust. + +The right position depends on the audience and the goal. Analytical audiences (engineers, finance teams, technical buyers) need transparency to trust. Less-analytical audiences may accept opacity if the brand has earned trust through other means. Most calculators benefit from at least Level 2 (methodology page) transparency. + +--- + +## When the calculation cannot be fully disclosed + +Some calculations include proprietary IP. Honest framing matters. + +The honest framing. "The output combines public benchmark data with proprietary insights from our customer cohort. Public elements are detailed in the methodology page; the proprietary weighting reflects our own data and is not detailed here." + +The dishonest framing. Hiding the proprietary nature; presenting opaque outputs as if they came from public methodology. + +The audience's reaction. Honest framing about proprietary IP is usually accepted. The audience understands that some IP is protected; they appreciate the honesty about what is shown and what is not. Dishonest framing breaks trust when the audience tries to interrogate and finds nothing. + +The discipline. Disclose what can be disclosed. Honestly label what cannot. The combination earns more trust than full opacity or false transparency. + +--- + +## Methodology display patterns + +How to integrate methodology into the calculator's UI. + +Pattern A: Always-visible inline formulas. The result and the formula appear together. Best for short calculations where the formula is digestible. + +Pattern B: Expandable methodology details. The result appears prominently; "How this was calculated" is an expandable section below. The user opens it if they want depth. + +Pattern C: Methodology link to a separate page. The result is shown; the methodology page is linked. Good for complex calculations that need full discussion. + +Pattern D: Hover-revealed assumption tooltips. Each variable in the result has a tooltip explaining how it was derived. Useful when the calculation has many components. + +Pattern E: Methodology in PDF report. The free result shows the headline; the gated PDF contains the full methodology. This pattern works when the PDF is genuinely the value-add and the headline result is enough for free users. + +The choice depends on calculator complexity, audience analytical depth, and the brand's transparency posture. + +--- + +## Common transparency failures + +No methodology shown. Result is a number; user has no way to verify or defend it. + +Hidden assumptions. Inputs and outputs visible; assumptions baked into the math without disclosure. + +Uncited benchmarks. "Industry Average: 14 percent" with no source. + +Stale assumptions. Methodology written in 2022, never reviewed. + +Flattering defaults. Defaults set to produce favorable outputs; the audience that catches the bias stops trusting. + +Methodology page that hides more than it reveals. Marketing copy disguised as methodology; no actual formulas or sources. + +Inconsistent precision. Result shown as "$14,237" when the inputs justify only "$14,000 (estimated)." False precision erodes trust. + +No version history on methodology. Methodology page changed over time without record; users who relied on previous outputs cannot tell what changed. + +--- + +## The credibility compounding effect + +Transparent calculators compound credibility. + +The mechanism. The audience uses the calculator, gets a defensible result, cites it in their decision-making conversation. The brand is in the conversation. The audience returns to the calculator for related decisions. The brand's authority on the topic deepens. + +The opposite. Opaque calculators do not compound. The audience uses the calculator, gets a number they cannot defend, leaves it out of their stakeholder conversation. The brand is invisible. The audience does not return. + +The metric. Track whether the calculator is being cited. Mentions in customer conversations, references in industry discussions, backlinks from other content all signal compounding credibility. + +--- + +## Methodology-level choices that stay in the public skill + +The transparency principle and the three levels. Inline formulas, methodology pages, source citations, assumption lists. The methodology-authority spectrum. Honest framing for proprietary calculations. Methodology display patterns. Common transparency failures. The credibility compounding effect. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source citations and benchmark relationships. Specific tooling for methodology display. Specific brand-voice methodology copy. The team's update calendars and version control for methodology. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md b/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md new file mode 100644 index 0000000..430a9c9 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculator-anti-patterns.md @@ -0,0 +1,211 @@ +# Calculator anti-patterns + +The patterns that look like calculators but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The lead-trap + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +The signal. Conversion-rate metric on the email form looks fine; downstream conversion is near zero; the audience that recognizes the pattern bounces immediately. + +The cost. The leads captured are unqualified or actively annoyed. The brand earns "lead-trap" reputation; trust erodes across all future interactions. + +The cure. Restructure so the result is free and the additional value (PDF, save-and-compare, custom analysis) is gated. Detail in `references/email-capture-decision-tree.md`. + +--- + +## The vanity output + +The pattern. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? Compared to what? + +The signal. Audiences run the calculator out of curiosity; do not return; do not cite the result anywhere; do not engage with the follow-up sequence. + +The cost. The calculator's build cost was wasted. The audience does not associate the brand with useful analysis. + +The cure. Anchor the result to a decision the audience actually makes. The output should be a number with units, contextualized against a baseline, with a clear next step. + +--- + +## The hidden-methodology calculator + +The pattern. No way to see the math. No methodology page. No assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The signal. Sales-team friction; prospects who used the calculator cannot bring its outputs into stakeholder conversations. + +The cost. The calculator does not compound credibility. Each user runs it once and does not return; the brand stays invisible in the audience's actual decision conversations. + +The cure. Disclose methodology. Detail in `references/calculation-logic-transparency.md`. + +--- + +## The interrogation form disguised as calculator + +The pattern. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The signal. Conversion rate on the form is poor. The audience self-selects out at the form length. + +The cost. The calculator's reach drops dramatically. The leads that do convert are over-disclosed and may resent the friction; the audience the calculator could have served does not get to use it. + +The cure. Audit the input set. Remove fields that do not affect the calculation. Capture additional data later in the relationship, not at the form. + +--- + +## The misleading-baseline calculator + +The pattern. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. + +The signal. Audiences with industry knowledge notice the gap. Those audiences do not return; they may post about the bias publicly. + +The cost. Trust damage that can be hard to recover. Brand earns "spin" reputation. + +The cure. Source the baselines honestly. Use defensible benchmarks; if the brand's data is favorable, disclose that the data comes from the brand's own customer cohort and acknowledge the bias. + +--- + +## The misaligned-units calculator + +The pattern. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The signal. Audiences cannot interpret the result; cannot use it in their decision; do not return. + +The cost. The calculator's outputs are uninterpretable; the calculator does not produce decision-grade signal. + +The cure. Numbers with units. Percentages with bases. Multipliers with reference values. Contextualization that makes the result interpretable. + +--- + +## The static-assumption calculator + +The pattern. Assumptions hardcoded in 2022 that have not been updated. Industry benchmarks from 2 years ago. Tooling references to products that have been deprecated. + +The signal. Audiences with current knowledge see the staleness; trust drops; some users may report the inaccuracy. + +The cost. The calculator's outputs are unreliable. The brand looks careless or out of touch. + +The cure. Quarterly maintenance review. Update assumptions, refresh benchmarks, prune stale references. + +--- + +## The mobile-broken calculator + +The pattern. Calculator works fine on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; result hidden below the fold. + +The signal. High mobile bounce rate; mobile conversion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic; this failure is significant. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. Detail in `references/input-design-patterns.md` (mobile section). + +--- + +## The over-precise calculator + +The pattern. Result shown as "$14,237.42" when the inputs justify only "$14,000 (estimated)." False precision suggests the calculator knows more than it does. + +The signal. Analytical audiences see the false precision and discount the result. The calculator earns "fake math" reputation among the audience that matters most. + +The cost. Trust erosion specifically among the audience the calculator was designed to serve. + +The cure. Round to honest precision. Use "estimated" or "approximately" framing. Disclose the precision the inputs support. + +--- + +## The marketing-disguised-as-methodology calculator + +The pattern. The methodology page exists but contains marketing copy ("our proprietary algorithm draws on industry-leading data") rather than actual formulas, sources, or assumptions. + +The signal. Audiences who click through to verify find no real verification; trust drops. + +The cost. The calculator's credibility is performative rather than real; the audience that interrogates discovers the gap. + +The cure. Real methodology. Formulas, assumptions, sources. Brand voice can frame the methodology page; brand voice cannot replace the methodology itself. + +--- + +## The orphan-result calculator + +The pattern. The result loads; no next step is offered. The user gets the number and leaves. + +The signal. Conversion to next step (PDF, save, contact, demo) is near zero because no next step is offered. + +The cost. The calculator captures attention without converting it. The brand has the audience's moment of intent and does nothing with it. + +The cure. Offer a clear next step at the result. PDF, save scenario, talk to team, related resource. Detail in `references/result-presentation-patterns.md` (result-to-action transitions). + +--- + +## The popup-interrupted calculator + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. The user's flow breaks. + +The signal. Bounce rate spikes at the popup moment; users complain about the interruption. + +The cost. The calculator's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. Detail in `references/result-presentation-patterns.md`. + +--- + +## The cookie-cutter calculator + +The pattern. The calculator looks and behaves like every other calculator from a template platform. Generic UI, generic assumption set, generic output styling. + +The signal. The calculator does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The calculator becomes commodity; the brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## The pessimistic-default calculator + +The pattern. Defaults set to make the brand's outputs look favorable through pessimistic baselines. "Current cost" defaults to the high end; "savings" defaults to the optimistic end. + +The signal. Audiences who notice (often analytical audiences) discount the result. The audience the calculator was built for stops trusting it. + +The cost. Same as misleading-baseline. Trust damage; brand earns "spin" reputation. + +The cure. Honest defaults sourced from data; let the user adjust to their actual context. + +--- + +## The form-without-calculator + +The pattern. A "calculator" that is actually a form. No real calculation; the result is generic ("based on your inputs, our team will reach out") or static ("your estimated savings: 30 percent"). + +The signal. Audiences expecting a real calculation get a sales form; bounce rate spikes; the audience perceives bait-and-switch. + +The cost. The calculator's framing was a lie; trust collapses. + +The cure. Either build a real calculator with real math, or do not call the form a calculator. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active calculator, looking specifically for these anti-patterns. + +Audit questions per calculator. + +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Is the methodology disclosed in a way the audience can verify (anti-pattern check: hidden-methodology)? +- Are the inputs all necessary for the calculation (anti-pattern check: interrogation-form)? +- Are the baselines and benchmarks sourced and current (anti-pattern check: misleading-baseline, static-assumption)? +- Does the calculator work on mobile (anti-pattern check: mobile-broken)? +- Is the result actionable, with a clear next step (anti-pattern check: orphan-result)? +- Does the calculator differentiate from other calculators on similar topics (anti-pattern check: cookie-cutter)? + +The retire decision. Anti-pattern calculators often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-tool plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md b/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md new file mode 100644 index 0000000..b0673aa --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/calculator-investment-criteria.md @@ -0,0 +1,144 @@ +# Calculator investment criteria + +When a calculator is the right tool for the audience and the goal, and when a simpler magnet would serve. The conditions that warrant the calculator's build cost. + +A calculator is one of the highest-build-cost magnet formats. Engineering, design, methodology research, and ongoing maintenance all add up. The calculator earns this investment only when specific conditions are present. + +--- + +## When a calculator earns the build + +Five conditions that, when present, make a calculator a strong investment. + +The audience faces a specific calculation as part of a real decision. ROI on a software purchase, savings from a refinance, monthly cost projection, sizing for a service tier, time-to-payback estimate. The calculation has to be one the audience actually runs in their workflow. Without a real calculation, the calculator becomes vanity. + +The calculation is non-trivial. Multiplying two numbers does not need a calculator; the audience can do that in their head. Calibrating across 5-10 inputs with branching logic, applying industry benchmarks, or running a multi-scenario comparison earns the format. + +The brand has methodology authority. The output has to be defensible. Brands with research, customer data, or industry expertise that informs the calculation can disclose methodology credibly. Brands without that authority often produce calculators audiences cannot trust. + +The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation: company size, current configuration, projected savings). The sequence has to use that signal. A generic sequence wastes the input data. + +The success metric is defined. What does "the calculator works" look like? Lead volume, lead quality, downstream conversion, the audience citing the calculator in stakeholder conversations. Without the success metric defined, evaluation is impossible. + +When all five are present, the calculator is a strong investment. When two or fewer are present, a simpler magnet (template, checklist, or worked example) often serves better. + +--- + +## When a calculator does NOT earn the build + +Funnels where the calculator is the wrong tool. + +The audience does not actually run this calculation. The team imagines the audience would benefit from the calculation; the audience does not actually face this decision. Usage is low; the build cost was wasted. + +The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" is not a calculator; it is a multiplication. The audience can do this without a tool. + +The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend ("we estimate 60 percent improvement based on internal data we cannot share"), the calculator becomes a vanity tool by necessity. The audience that would benefit from a defensible calculator gets a brand-flattering one instead. + +A simpler magnet would serve the same audience and goal. A pricing PDF that shows worked examples and methodology might serve the same audience as a pricing calculator at one-tenth the build cost. Choose the simpler magnet when it would serve. + +The audience is too small to justify the build. A calculator for a niche of 200 prospects is hard to justify against the build cost. Direct outreach or a simpler resource may be more efficient. + +The team cannot maintain the calculator. Calculators decay as benchmarks change, product details evolve, and tooling updates. Without maintenance commitment, the calculator becomes a stale liability. + +The honest assessment matters more than the default. "Should we have a calculator" is not the question. "Is the calculator the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A calculator's cost is significant. Account for it honestly. + +The build cost. Methodology research, formula design, input UX, result UX, calculation engine, methodology disclosure, mobile responsiveness, edge-case handling. A meaningful calculator often takes 60-200 engineering hours plus design and copy. + +The maintenance cost. Benchmarks change; product details change; assumptions shift. Quarterly review and updates run 4-12 hours per active calculator. + +The sequence cost. The follow-up sequence using the input data is itself a build. 10-30 hours upfront. + +The opportunity cost. What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The calculator's success has to clear the bar of those alternatives. + +The decision frame. The calculator earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The methodology-authority precondition + +Without methodology authority, the calculator cannot be defensible. + +The audience's question. After running the calculator: "Where does this number come from?" + +If the team can answer with sources (industry benchmarks, customer data, public research, defensible assumptions), the calculator has methodology authority. The audience can trust the result and use it in their decision. + +If the team cannot answer ("our model just produces this number"), the calculator does not have methodology authority. The audience either does not trust the result or trusts it without understanding it (which is worse for the audience and ultimately for the brand). + +How to assess methodology authority. + +- Does the team have direct customer data on the calculation's central variables? +- Does the team have access to defensible industry benchmarks? +- Is the team willing to publish the methodology, or does the methodology have to stay proprietary? +- Can the team defend the methodology to a sophisticated stakeholder? + +If the answer to most of these is yes, the calculator has methodology authority. If the answer is no, the calculator is being built on assumptions that will not survive interrogation. + +--- + +## The decision worked example + +A SaaS analytics platform considering a "ROI of moving from spreadsheets" calculator. + +Conditions check. + +- Specific calculation: yes. Prospects evaluating the platform run an internal estimate of switching value. +- Non-trivial: yes. The calculation involves time-saved-per-week, hourly cost of analyst time, error-rate reduction, decision-speed lift, and implementation cost. +- Methodology authority: yes. The team has customer data on time saved, error reduction, and decision speed across 200+ deployed customers. +- Sequence has purpose: yes. Calculator inputs reveal company size, analytics maturity, and current tooling. Sequence can match the lead's profile. +- Success metric defined: yes. Lead volume from the calculator, lead quality (audience-fit at SaaS companies above 50 employees), downstream conversion to demo within 90 days. + +Decision. Build the calculator. The conditions warrant it. + +Tier design. Tier 1 (free): the headline annual savings number, the breakdown across time-saved, error-reduction, and decision-speed components, methodology disclosure linked. Tier 2 (email-gated): a PDF the prospect can share with their stakeholders showing the calculation in defensible form. Tier 3 (account-gated, optional): saved scenarios across multiple analyst counts and use-case configurations. + +Maintenance commitment. Quarterly review of the customer-data benchmarks. Update assumptions when the customer base shifts. + +The decision was not "should we have a calculator" but "given these conditions, this is the calculator to build." + +--- + +## When to choose a simpler magnet instead + +The calculator is the wrong tool. What works. + +Pricing one-pager template. When the calculation is "what would my pricing look like," a worked-example one-pager often serves better than a calculator. The prospect adapts the example; the team avoids building. + +ROI worked-example PDF. When the calculation is "what would I save," a PDF showing 3-5 worked-example customer scenarios often serves better. The prospect identifies which scenario matches them; the team gets a downloadable resource without engineering overhead. + +Sizing checklist. When the calculation is "what tier do I need," a checklist of features and team-size signals can guide the prospect to the right tier without a calculator. + +Comparison table. When the calculation is "is this better than the alternative," a static comparison table often serves better than a dynamic calculator. + +The pattern. Many "we need a calculator" intuitions are actually "we need a clear way to communicate this calculation to prospects." Often the simpler format works as well or better, at one-tenth the build cost. + +--- + +## When to retire a calculator + +Calculators decay. Retiring them is part of the discipline. + +Retire when: + +- Lead volume has dropped below baseline for two consecutive quarters. +- The product or pricing has changed enough that the calculator's calculations no longer reflect the offering. +- The benchmarks the calculator relies on are stale and the team cannot update them. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. A portfolio of stale calculators costs maintenance attention without producing results. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a calculator. The opportunity-cost frame. The methodology-authority precondition. The decision worked example. When to choose a simpler magnet. The retirement discipline. + +## Implementation choices that stay internal + +Specific calculator topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence. Specific tooling for calculator engineering, hosting, and integration. Specific methodology sources and update calendars. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md b/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md new file mode 100644 index 0000000..badb9cc --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/common-calculator-failures.md @@ -0,0 +1,179 @@ +# Common calculator failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the calculator did not work" or "the leads are unqualified" or "we cannot tell what the calculator is producing." + +--- + +## "Conversion rate is high; downstream conversion is near zero." + +The diagnosis. Lead-trap or vanity-output pattern. The audience captured did not get value; did not engage with the follow-up; did not convert downstream. + +The cure. Audit for lead-trap (`references/email-capture-decision-tree.md`). Audit for vanity-output (`references/result-presentation-patterns.md`). The result has to be specific, contextualized, and actionable; the email gate has to be on additional value, not on the result itself. + +--- + +## "Audience visits the calculator, runs it once, never returns." + +The diagnosis. The calculator does not produce a save-worthy or share-worthy result. No reason to come back. + +The cure. Add tier-2 value (PDF, saved scenario) that gives the user something to bring back to. Audit the result presentation (`references/result-presentation-patterns.md`); a result the user cannot share with stakeholders rarely produces return visits. + +--- + +## "Sales team says the calculator-sourced leads are unqualified." + +The diagnosis. Calculator's audience-fit is weak. The calculation does not match the buyer's actual decision; the audience captured is curious-but-not-buying. + +The cure. Audit the calculator's audience-fit. Does the calculation map to a real decision the buyer faces? If not, the calculator may be capturing wrong-segment leads. Detail also in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "We get questions about how the calculator works; we have no answer." + +The diagnosis. Methodology not documented. The team cannot defend the calculator's outputs. + +The cure. Document the methodology (`references/calculation-logic-transparency.md`, `references/methodology-disclosure-templates.md`). The methodology page should answer the audience's interrogation questions before they ask. + +--- + +## "We updated the product; the calculator outputs are now wrong." + +The diagnosis. No update cadence. The calculator drifted out of sync with the actual offering. + +The cure. Maintenance discipline. Quarterly review of every active calculator. Update inputs, recommendations, and pricing as the offering evolves. + +--- + +## "The calculator works; nobody uses it." + +The diagnosis. Calculator hidden in the site; no distribution; the audience does not know it exists. + +The cure. Distribution. Link to the calculator from related landing pages, blog posts, and navigation. Promote it in newsletter and social channels. Cite it in sales conversations. The calculator's existence is not enough; the audience has to know about it. + +--- + +## "Our calculator looks like our competitor's." + +The diagnosis. Generic calculator-template patterns produce generic calculators. Brand differentiation is absent. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## "The form has 12 fields and 4 percent conversion." + +The diagnosis. Interrogation-form pattern. The calculator is collecting data, not delivering value. + +The cure. Audit the input set (`references/input-design-patterns.md`). Each input should affect the calculation. Remove fields that do not. + +--- + +## "Audience trusts our brand; the calculator outputs feel arbitrary." + +The diagnosis. Methodology disclosure missing. The brand's credibility does not transfer to the tool because the tool does not show its work. + +The cure. Disclose methodology (`references/calculation-logic-transparency.md`). The brand-trust is one part of credibility; the tool's transparency is a separate part. Both have to be present. + +--- + +## "Our pricing changed; the calculator was not updated for 6 months." + +The diagnosis. Maintenance lapse. The calculator's outputs were misleading for half a year. + +The cure. Set a maintenance trigger: when pricing or product details change, the calculator update is part of the change. Otherwise, set a calendar review at minimum quarterly. + +--- + +## "The calculator was great at launch; conversion has dropped 40 percent over a year." + +The diagnosis. Decay. Stale benchmarks; outdated references; methodology that no longer reflects the brand's offering. + +The cure. Audit and refresh. If the calculator is still relevant, update it. If it is not, retire it. + +--- + +## "The free result is just 'estimated savings: significant.'" + +The diagnosis. Vanity output. The free tier is a teaser rather than a substantive result. + +The cure. The free tier has to be substantive. "Estimated annual savings: $14,200" with breakdown and methodology beats "significant savings" with email gate. + +--- + +## "Audiences complete the inputs but do not opt for the PDF." + +The diagnosis. The PDF does not justify the email exchange. Either the PDF is the same content as the free result (no value-add) or the audience does not perceive the PDF as worth the email. + +The cure. Make the PDF genuinely better. Add comparison tables, case studies, or additional analysis. Frame the PDF as "what you can share with your CFO" so the audience sees the use case. + +--- + +## "We get traffic; we get email signups; the sales team never hears about the leads." + +The diagnosis. Sequence missing or poorly designed. The leads sit on the list without being routed to sales. + +The cure. Design the post-conversion flow. Calculator-sourced leads should be tagged, routed, and sequenced. Sales should know which leads came from the calculator and what the leads' inputs revealed. + +--- + +## "We added a calculator; our other lead magnets stopped converting." + +The diagnosis. Cannibalization. The calculator absorbed the audience that previously converted via other magnets. + +The cure. This may not be a failure. If the calculator-sourced leads are higher quality than the previous magnets, the cannibalization is a portfolio improvement. If the calculator absorbed leads but produced no incremental value, the calculator may have replaced a working magnet with a worse one. + +--- + +## "The calculator works on Chrome desktop; it breaks on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The calculator was tested on the team's primary platform; the audience's actual devices were not covered. + +The cure. Cross-browser, cross-device testing. The audience uses what they use; the calculator has to work there. + +--- + +## "The calculator estimates 60 percent savings; our actual customers see 35 percent." + +The diagnosis. The calculator's assumptions are flattering rather than accurate. The customers who used the calculator's projections are now disappointed. + +The cure. Recalibrate. Use actual customer cohort data to set the assumptions. The honest result may be less impressive on the marketing screen but earns more trust over time. + +--- + +## "We want to A/B test the calculator's email gate placement." + +The diagnosis. This is fine, but the test should be designed carefully. Moving the email gate is a gating-decision change that affects both conversion and lead quality. + +The cure. Test gate placement with both conversion-rate and downstream-conversion metrics. A change that lifts conversion but tanks downstream is a regression, not an improvement. + +--- + +## "The calculator's methodology page got 200 visits and 50 unsubscribes." + +The diagnosis. Likely the audience interrogated the methodology and found it wanting. Either the methodology has a real flaw, or the methodology page is unclear. + +The cure. Audit the methodology page. Either fix the methodology (if there is a real flaw) or clarify the page (if the issue is presentation). + +--- + +## The pattern across failures + +Most calculator failures fall into one of three patterns. + +Pattern 1: The calculator does not deliver real value. Vanity output, hidden methodology, lead-trap. The fix is to deliver real, defensible, accessible results. + +Pattern 2: The calculator does not match the audience or decision. Audience-fit weak, calculation-decision mismatch, interrogation-form. The fix is to align the calculator to the audience the brand serves and the decision the audience faces. + +Pattern 3: The calculator decays. Stale assumptions, outdated benchmarks, broken integration. The fix is maintenance discipline. + +The metric pattern: calculator failures often look fine on conversion rate. The signal is in lead quality, downstream conversion, and audience interrogation behavior. Programs that track only conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md b/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md new file mode 100644 index 0000000..f1fb4fc --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/email-capture-decision-tree.md @@ -0,0 +1,205 @@ +# Email-capture decision tree + +What to give freely, what to gate. The lead-trap failure and the transparent-tool win. + +The single most consequential decision in calculator design is what gets shown freely and what requires an email. Get this wrong and the calculator is either a lead-trap (gating the result the user came for) or a missed opportunity (giving away everything with no capture mechanism). + +--- + +## The honest principle + +Give the audience the result they came for. Gate the additional value. + +The audience showed up to run a calculation. They want the answer. Gating the answer is bait-and-switch: the calculator promised a result, the user provided inputs, and the result is held hostage until they trade an email. + +The transparent alternative: give the result freely. The audience gets what they came for. The brand offers additional value (a PDF report, a saved scenario, a custom analysis) that the audience can opt in for. The email exchange is then for additional value, not for the result the calculator promised. + +--- + +## What to give freely + +Tier 1, no gate. + +The headline result. The number the user came for. "Your annual savings: $14,200" or "Recommended plan: Growth." + +The breakdown. The components that explain how the headline number was calculated. Necessary for the audience to defend the result. + +A basic visualization. A chart or comparison that helps the user see the relationship. + +The methodology disclosure. Either inline formulas or a methodology link. Necessary for the audience to trust the result. + +Source citations. Where the calculator's benchmarks come from. + +The assumption list. What the calculator assumes about the user's situation. + +This set is what the audience needs to use the calculator's output in their decision. Holding any of it hostage is the lead-trap pattern. + +--- + +## What to gate (with email) + +Tier 2, email-required. + +A formatted PDF report. The result, breakdown, methodology, and assumptions in a shareable format. The user can send this to their stakeholders. The PDF has to be genuinely better than a screenshot of the result; otherwise the gate is not justified. + +A saved scenario the user can revisit. Persistence across visits. The user adjusts inputs over time, returns to compare, sees how the result has changed. Email-required to identify the user. + +A custom or deeper analysis. A second-pass calculation that uses the user's inputs as a starting point and adds more depth (more variables, more scenarios, more methodology). Often delivered later (by email) rather than immediately. + +Email-based notifications. When the calculator's benchmarks change or new versions launch, the user can be notified. + +The discipline. Each gated tier has to add real value over the free tier. If the PDF is just "the same result in a PDF," the gate is not earning the email. + +--- + +## What to gate (with account or sign-up) + +Tier 3, account-required. + +Save-and-compare across multiple scenarios. The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +Integration with the brand's product or service. The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +Historical comparison. When the calculator is used periodically (monthly cost projection, quarterly review), the user's historical inputs and results are tracked. + +Collaboration features. Multiple users on the same account can model scenarios together. + +These features warrant the higher friction of account creation. Email alone is insufficient; the user needs persistent identity for these to work. + +--- + +## The lead-trap failure + +The pattern that destroys conversion. + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +Why it fails. + +- The audience perceives the manipulation. The calculator promised a result; the result is hidden. +- Conversion drops. Many users abandon at the gate; some enter throwaway emails. +- The leads that do convert are unqualified or actively annoyed; downstream conversion is poor. +- The brand earns "lead-trap" reputation; future users who recognize the pattern bounce immediately. + +Why teams build lead-traps. Short-term thinking. The team optimizes for capture rate without measuring downstream conversion. The lead-trap looks like it works because the form-fill rate is high; the lead-trap fails because the leads do not convert. + +The cure. Restructure the calculator so the result is free and the additional value is gated. Conversion to the email gate may drop in absolute terms, but the leads that do opt in are higher-quality. + +--- + +## The transparent-tool win + +The pattern that compounds credibility. + +The pattern. The user enters inputs, sees the result immediately, and is offered a "Get this as a PDF" or "Save this scenario" option that requires email. + +Why it works. + +- The audience trusts the brand. The calculator delivered on its promise. +- The email opt-in is for additional value, not for the result. Users who opt in are signaling real interest in the topic. +- Lead quality is higher because the lead opted in for value-add, which signals genuine interest. +- The brand earns "honest" reputation; word-of-mouth and referral grow. + +The metrics that matter. + +- Free-tier completion rate (how many users finish the calculation and see the result). +- Email-tier conversion rate (of those who see the result, how many opt in for the additional value). +- Downstream conversion (of those who opted in, how many engage with the follow-up sequence and convert to the next step). + +The transparent-tool optimizes for downstream conversion, which is the metric that matters for the program. + +--- + +## The decision tree + +Walk through this for each gating decision. + +Question 1: Is this the result the user came for? + +- If yes: do not gate. Holding the user-promised result hostage is lead-trap. +- If no: continue. + +Question 2: Is this additional value the user might want? + +- If yes: gating is potentially appropriate. +- If no: do not gate; the user does not want it badly enough for the email exchange to be worthwhile. + +Question 3: Is the additional value substantial enough to justify the email? + +- If yes: gate it. The user gets real value; the brand gets the email; the exchange is honest. +- If no: do not gate; the gate is not earning its friction. + +Question 4: Could the additional value be delivered better as a follow-up after the email? + +- If yes: gate it as a follow-up offer in the post-result flow, not as a barrier to the result. +- If no: gate it as a clear "get this additional value" offer near the result. + +This decision tree separates honest gating from manipulative gating. + +--- + +## Worked examples + +Example 1: SaaS pricing calculator. + +- Free: recommended plan, monthly cost estimate, breakdown by component, methodology link. +- Email-gated: a PDF showing the recommendation, alternative plans considered, and a printable comparison table. +- Account-gated: ability to save the scenario and adjust over time as the team's needs change. + +The free tier delivers what the prospect came for. The email gate delivers a shareable artifact for the prospect's internal stakeholders. The account gate enables ongoing use. + +Example 2: ROI calculator for a B2B service. + +- Free: estimated annual savings, breakdown across cost reduction and productivity gains, methodology disclosure. +- Email-gated: PDF analysis with industry-comparison context and worked-example case study. +- Account-gated: not offered. The calculator is single-use; account creation is unnecessary friction. + +The free tier serves the audience. The email gate serves the prospect's internal stakeholders by providing a shareable analysis. + +Example 3: Mortgage calculator. + +- Free: estimated monthly payment, breakdown across principal, interest, taxes, insurance, methodology link. +- Email-gated: a personalized rate quote (which requires the bank to underwrite based on user inputs). +- Not offered: account creation. The calculator is a one-shot tool; account creation does not match the use case. + +The email gate is justified by genuine value-add (personalized rate quote requires underwriting). The free tier delivers the calculator's promise. + +--- + +## When the email gate is the wrong tool + +Sometimes no gating is the right answer. + +Calculators built primarily for SEO or brand authority. A widely-shared, well-ranked calculator can be a strong brand asset even without lead capture. The audience that uses it associates the brand with the topic; the SEO ranking compounds traffic. + +Calculators where lead-capture friction destroys the value proposition. A simple, quick-use calculator may be best as a no-gate tool. The audience uses it, gets value, returns; the brand becomes the source of the tool. + +Calculators in regulated industries. Some sectors have specific privacy or regulatory constraints on email capture. The calculator may need to operate without standard lead-capture flows. + +The decision depends on the program's goals. Not every calculator needs to be a lead magnet. Some calculators serve other purposes (SEO, brand, audience-building) better without gates. + +--- + +## Common gating failures + +Result hidden behind email. The lead-trap. Conversion drops; downstream metrics drop further. + +Gate without value. Email required to access something that should have been free; no real additional value behind the gate. + +Gate that lies about what is gated. "Get the full analysis" suggests the free version was incomplete; the user expects more depth, gets the same content reformatted, feels deceived. + +Multiple gates in sequence. Email for one tier, account for another, phone number for a third. Each step adds friction; cumulative drop-off destroys the audience. + +Gate copy that is manipulative. "Don't lose your result, give us your email" is hostile. "Want this as a PDF? Enter your email" is honest. + +Gate placement that interrupts the result viewing. The result loads; the user starts reading; a popup appears asking for email. The user's flow breaks; trust drops. + +--- + +## Methodology-level choices that stay in the public skill + +The honest principle. What to give freely. What to gate at email and at account level. The lead-trap failure pattern. The transparent-tool win pattern. The decision tree. Worked examples. When the email gate is the wrong tool. Common gating failures. + +## Implementation choices that stay internal + +Specific gating decisions for the team's calculators. Specific PDF templates and follow-up flows. Specific account-creation flows and integration patterns. Specific gate copy in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md b/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md new file mode 100644 index 0000000..4f8cf5d --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/input-design-patterns.md @@ -0,0 +1,218 @@ +# Input design patterns + +Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. + +The calculator's inputs are the audience's first interaction with the tool. Bad input design loses users before the calculation runs. Good input design respects the user's time and produces inputs that genuinely affect the math. + +--- + +## The necessity principle + +Each input should be necessary for the calculation. Inputs that do not affect the output meaningfully should not be asked for. + +The test. For each input, ask: does removing this input change the result by a meaningful amount? If no, the input is not necessary; remove it. + +The interrogation-form failure. Calculators that ask 18 inputs but only use 5 in the math are signaling that the form is collecting sales-qualification data. The audience can tell. Conversion drops; trust drops. + +The honest input set. Most calculators need 4-10 inputs. Tools asking 15+ inputs almost always have non-essential fields that should move to a separate (later, optional) interaction. + +The exception: meaningful customization. When inputs do affect the result and the audience values the customization, more inputs are warranted. A pricing calculator that customizes to industry, team size, use case, and feature needs may need 8-12 inputs because each input affects the output. + +The discipline. Audit the input set against the actual math. Remove fields that do not affect the result. + +--- + +## Default discipline + +Defaults reduce cognitive load. Bad defaults bias the result. + +Honest defaults. Set defaults to honest, sourced values. "Average company size: 50" if 50 is the median across the audience. "Typical conversion rate: 14 percent" if 14 percent is a defensible benchmark. + +Sourced defaults. When defaults come from external benchmarks, source them. A footnote or tooltip explaining the default's origin earns trust. + +Adjustable defaults. The user should be able to override the default with their actual value. Defaults that look hardcoded reduce trust; defaults the user can edit signal that the calculator respects the user's situation. + +Bias-flattering defaults. Defaults set to flatter the brand's outputs (high savings, low costs) destroy credibility when the user notices. The audience that catches the bias remembers it. + +Default decay. Defaults need updating as benchmarks shift. A default set in 2022 that has not been touched is stale; the audience that knows the current benchmark sees the gap. + +--- + +## Input types + +Choose the right input control for each variable. + +Numeric input. Free-form number entry. Use for variables that are user-specific and where exact values matter (revenue, customer count, monthly cost). Often warrants a tooltip explaining what the number represents. + +Slider. Visual range control. Use for percentage estimates and ranges where exact values are not knowable (conversion rate, growth rate, retention). Sliders communicate the range and reduce cognitive load on choosing a precise number. + +Dropdown. Select from predefined categories. Use for variables that are categorical (industry, region, company size band). Dropdowns prevent invalid inputs and group similar audiences. + +Toggle. Binary on/off. Use for feature inclusion/exclusion or scenario switching (with implementation / without implementation). + +Stepper. Increment/decrement controls. Use for small whole-number variables (number of users, number of locations) where the range is bounded. + +Free text. Open-ended text input. Use sparingly. Free text adds friction and rarely affects calculation; if the calculator needs free text to function, the calculation may be the wrong format. + +The choice depends on the variable's nature. The wrong control type adds friction; the right control type makes the input feel natural. + +--- + +## Progressive disclosure + +Show only the inputs the user is currently working through. + +The pattern. The calculator presents 2-4 inputs at a time. The user completes those, the next set appears. Each step builds on the previous. + +When progressive disclosure helps. When the calculator has 8+ inputs, when input groups are conceptually distinct (company info, then current state, then desired state), or when later inputs depend on earlier choices. + +When progressive disclosure hurts. When the calculator has 4-6 inputs that the user could complete in 30 seconds, hiding any of them adds friction. Single-page calculators are fine for short input sets. + +Progress indicators. When the calculator is multi-step, show progress ("Step 2 of 4") so the user knows the time commitment. + +Back navigation. The user should be able to go back and adjust earlier inputs without losing later ones. + +--- + +## Input grouping and visual flow + +Group related inputs visually. The user processes related inputs as a unit. + +Logical groups. + +- Company info (name, size, industry). +- Current state (current cost, current process, current tools). +- Desired state (target outcome, target timeline). +- Configuration choices (tier, options, add-ons). + +Visual cues. + +- Section headers for each group. +- Spacing between groups. +- Consistent input styles within a group. + +Avoid. + +- Mixing unrelated inputs in one section. +- Inconsistent label patterns across the form. +- Required-vs-optional ambiguity (mark required inputs explicitly). + +--- + +## Tooltips and explanations + +Inputs that are not self-explanatory need explanation. Inputs that are self-explanatory do not need it. + +When tooltips help. When the input requires context the user may not have ("Customer Acquisition Cost: the marketing and sales spend per new customer"), when the input has a specific definition that varies by interpretation, or when the default needs sourcing ("Industry average from [source]"). + +When tooltips hurt. When the input is obvious (no tooltip needed for "Number of users"), when the tooltip is marketing rather than explanation, or when the tooltip overwhelms the form visually. + +Tooltip placement. Inline (right next to the field label) or hover-triggered. Hover-triggered keeps the form clean for users who do not need explanation. + +Tooltip discipline. Each tooltip should answer one question. Multiple paragraphs in a tooltip signal that the input itself needs redesign. + +--- + +## Validation and error handling + +Inputs need validation. Errors need helpful messages. + +Inline validation. Validate as the user types or after they leave the field. Catch errors at the point of input, not at submission. + +Helpful error messages. "Number must be greater than 0" beats "Invalid input." "Try a value between 1 and 1000" beats "Out of range." + +Avoid friction. Validation that rejects too aggressively (rejecting all special characters when only a few cause problems) frustrates users. Error messages that scold ("You must enter...") signal a hostile form. + +Required vs optional. Mark required inputs explicitly. Optional inputs should be obvious (and rare; if it is not used, why ask). + +--- + +## Mobile input design + +Many calculator users are on mobile. The input experience has to work there. + +Mobile-specific considerations. + +- Touch-friendly input sizes (minimum 44x44 pixel touch targets). +- Numeric keyboards for numeric inputs (use input type="number" or appropriate inputmode). +- Sliders sized for thumb interaction. +- Dropdowns that work with native mobile selection. +- Sufficient spacing between inputs to prevent accidental taps. + +Mobile testing. Test the calculator on actual mobile devices, not just browser dev tools. Real-device behavior often differs. + +Mobile-broken calculator failure. Calculator works on desktop, breaks on mobile. The mobile audience either bounces or has a worse experience. This failure is common; mobile testing prevents it. + +--- + +## Input examples and worked patterns + +Pattern: company info input set. + +- Company size (dropdown: 1-10, 11-50, 51-200, 201-500, 501-2000, 2000+) +- Industry (dropdown of 8-12 categories) +- Current annual revenue (numeric, optional, with tooltip explaining how it affects calculation) + +3 inputs, 30 seconds to complete, all affect the calculation. + +Pattern: current state input set. + +- Current monthly cost (numeric, with tooltip) +- Current team size on the relevant function (numeric) +- Current process (dropdown: manual, partially automated, fully automated) + +3 inputs, sets the baseline for the calculation. + +Pattern: desired state input set. + +- Target outcome (dropdown: cost reduction, time savings, revenue lift, all of the above) +- Target timeline (slider: 3 months to 24 months) + +2 inputs, sets the goal for the calculation. + +Total: 8 inputs across 3 logical groups. Each input affects the math. Defaults reduce friction. Progressive disclosure presents groups one at a time. + +--- + +## Input decay + +Inputs need maintenance. + +What decays. + +- Defaults based on benchmarks that have shifted. +- Tooltips referencing tools or terms that have changed. +- Dropdown options that are no longer accurate (industry categories, product tiers). +- Sources cited in tooltips that no longer exist or have moved. + +Maintenance cadence. Quarterly review of every active calculator's inputs. Update defaults, refresh tooltips, prune stale options. + +The decay-trust connection. Stale defaults erode trust. The audience notices when "Industry Average: 14 percent (2022)" appears in a 2026 tool. + +--- + +## Common input failures + +Too many inputs. 15+ inputs signal interrogation rather than calculation. Audit for non-essential fields. + +Bias-flattering defaults. Defaults that produce favorable outputs for the brand. Audiences notice; trust drops. + +Hardcoded defaults that cannot be changed. The audience cannot adjust to their actual situation. The calculator feels generic. + +Wrong input type for the variable. Free text where dropdown would be better; dropdown where slider would be better. Adds friction. + +Missing tooltips on non-obvious inputs. The audience does not know what the input means; they guess; the result is meaningless. + +Mobile-broken inputs. Sliders impossible to grab on mobile; dropdowns that overflow; numeric keyboards not triggered. + +Stale defaults. Benchmarks from years ago; tooltips referencing deprecated tools; dropdown options that no longer match reality. + +--- + +## Methodology-level choices that stay in the public skill + +The necessity principle. Default discipline. Input type guidance. Progressive disclosure. Input grouping and visual flow. Tooltip discipline. Validation and error handling. Mobile input design. Input decay and maintenance. + +## Implementation choices that stay internal + +Specific input sets for specific calculators. Specific default values from the team's data sources. Specific tooltip copy in brand voice. Specific input components and styling. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md b/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md new file mode 100644 index 0000000..170bf18 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/methodology-disclosure-templates.md @@ -0,0 +1,321 @@ +# Methodology disclosure templates + +Templates for assumption lists, methodology pages, source citations, formula explanations. Patterns for disclosing calculation logic in ways the audience can use to defend the result. + +A methodology disclosure is not a marketing document. It is a technical document that lets the audience interrogate the calculator. The templates here cover the patterns that hold up to interrogation. + +--- + +## Methodology page template + +A standalone page that explains the calculator's calculations in detail. + +Structure. + +``` +# How the [calculator name] is calculated + +## What this calculator does +[2-3 sentences describing the calculation in plain language] + +## The formulas +[Plain-text formulas with each variable defined] + +## Assumptions +[Plain-language list of what the calculator assumes] + +## Sources +[Citations for any external benchmarks or data] + +## Worked example +[A specific scenario with input values and resulting calculation] + +## Caveats +[What the calculator does not account for; when to seek additional analysis] + +## Updates +[Date of last methodology review; how often the calculator is updated] +``` + +--- + +## Assumption list template + +A plain-language list of assumptions, formatted for scan-ability. + +Structure. + +``` +## What this calculator assumes + +- [Assumption 1: stated plainly] +- [Assumption 2: stated plainly] +- [Assumption 3: stated plainly] + +## What this calculator does NOT account for + +- [Excluded factor 1] +- [Excluded factor 2] + +If your situation differs significantly from these assumptions, the result is an estimate; consider [additional resource] for more precise analysis. +``` + +Example assumption list for a SaaS pricing calculator. + +``` +## What this calculator assumes + +- Your team will use the platform daily across business hours. +- Implementation takes 4-6 weeks for teams in the 50-200 employee range. +- The recommended plan is based on typical usage patterns from our customer base. +- Productivity gains compound through year 1 and stabilize in year 2. + +## What this calculator does NOT account for + +- Custom integrations or enterprise SSO requirements. +- Volume discounts available for annual contracts above $50K. +- Migration cost from your current platform. + +If your situation involves enterprise SSO, custom integrations, or migration costs, talk to our team for a tailored estimate. +``` + +--- + +## Source citation template + +How to cite external benchmarks or data. + +Inline citation pattern. + +``` +Industry Average: 14 percent (Source: [Industry Benchmark Report 2025], page 23) +``` + +Footnote pattern. + +``` +Industry Average: 14 percent [^1] + +[^1]: Industry Benchmark Report 2025. Available at [URL]. Accessed [Date]. +``` + +Multi-source pattern. + +``` +The conversion-rate benchmark we use combines: +- Industry Benchmark Report 2025 (Source A) +- Our customer cohort data (n=200, 2024-2025) +- Public conversion-rate studies from [Source C] + +The composite benchmark is 14 percent. +``` + +Internal-source pattern. + +``` +Source: [Brand]'s customer cohort data, n=200, 2024-2025. The cohort represents customers in the 50-500 employee range across SaaS, e-commerce, and B2B services. +``` + +--- + +## Formula explanation template + +How to display formulas in ways the audience can verify. + +Plain-text formula pattern. + +``` +Annual savings = (current annual cost) - (estimated new annual cost) + first-year implementation savings + +Where: + current annual cost = current monthly cost x 12 + estimated new annual cost = recommended plan price x 12 + first-year implementation savings = $500 if migrating from a manual process, otherwise $0 +``` + +Step-by-step calculation pattern. + +``` +1. Calculate current annual cost: $3,000 / month x 12 = $36,000 +2. Calculate estimated new annual cost: $2,000 / month x 12 = $24,000 +3. Calculate cost reduction: $36,000 - $24,000 = $12,000 +4. Add first-year implementation savings: $12,000 + $2,200 = $14,200 + +Annual savings: $14,200 +``` + +Conditional logic pattern. + +``` +The recommended plan is determined by: + +If team size is 1-10: Starter plan ($X / month) +If team size is 11-50: Growth plan ($Y / month) +If team size is 51-200: Business plan ($Z / month) +If team size is 201+: Enterprise (contact for pricing) + +Plan recommendations may shift based on use case (e.g., teams with heavy data needs may benefit from a higher tier even at a lower seat count). +``` + +--- + +## Worked-example template + +A concrete scenario the audience can read end-to-end. + +Structure. + +``` +## Worked example: [scenario description] + +Inputs: +- [Input 1]: [value] +- [Input 2]: [value] +- [Input 3]: [value] + +Calculation: +[Step-by-step formula application] + +Result: +[Final output with units] + +Interpretation: +[1-2 sentences explaining what the result means and how the audience would use it] +``` + +Example for a SaaS pricing calculator. + +``` +## Worked example: 75-person B2B SaaS team + +Inputs: +- Team size: 75 +- Use case: Customer support +- Current solution: Manual spreadsheets + +Calculation: +- Recommended plan: Business ($45 / user / month) +- Monthly cost: 75 users x $45 = $3,375 +- Annual cost: $3,375 x 12 = $40,500 +- Estimated time savings: 8 hours / week / agent x 75 agents x $40 / hour x 50 weeks = $1.2M +- Net annual value: $1.2M - $40,500 = $1.16M + +Result: +- Recommended plan: Business +- Monthly investment: $3,375 +- Estimated annual time-savings value: $1.2M +- Net annual value: $1.16M + +Interpretation: +A 75-person customer-support team migrating from manual spreadsheets to the Business plan would invest $40,500 annually and save approximately $1.16M in time-equivalent value. The largest contributor is hours saved per agent per week. +``` + +--- + +## Caveats template + +What the calculator does not do, stated honestly. + +Structure. + +``` +## What this calculator does not account for + +- [Excluded factor 1]: why it is excluded and what to do if it matters +- [Excluded factor 2]: why it is excluded and what to do if it matters + +For situations involving [specific complex case], the calculator's estimate may not apply; consider [additional resource or contact] for more precise analysis. +``` + +Why caveats matter. Caveats signal the calculator's honesty. The audience that knows the caveats can use the result with appropriate confidence; the audience that does not know the caveats may apply the result to a situation it does not fit. + +Common caveats to include. + +- The calculator does not account for taxes, regulations, or jurisdiction-specific factors. +- The calculator does not account for one-time setup or migration costs. +- The calculator's benchmarks reflect the typical case; outliers may differ significantly. +- The calculator's projections are estimates, not guarantees. + +--- + +## Update-history template + +How to track methodology changes over time. + +Structure. + +``` +## Updates + +This calculator's methodology was last reviewed on [date]. + +Recent updates: +- [Date]: Updated industry-benchmark source from [old] to [new]. +- [Date]: Adjusted productivity-gains assumption based on cohort data through [year]. +- [Date]: Added consideration for [new factor]. + +Major version history: +- v1.0 ([date]): Initial release. +- v1.1 ([date]): Added [feature]. +- v2.0 ([date]): Refactored methodology to include [new dimension]. +``` + +Why update history matters. Audiences who relied on previous outputs can see what changed. The transparency about updates signals that the calculator is maintained, not abandoned. + +--- + +## Methodology integration patterns + +How to integrate the methodology disclosure into the calculator UI. + +Pattern A: Inline disclosure. The methodology appears alongside the result. Best for short calculations where the formula is digestible. + +Pattern B: Expandable section. "How this is calculated" expandable below the result. The user opens it if they want depth. + +Pattern C: Linked methodology page. A "How this is calculated" link to a separate page. Best for complex calculations. + +Pattern D: Hover-revealed detail. Each result component has a tooltip explaining how it was derived. Useful for multi-component results. + +Pattern E: Methodology-in-PDF. The free result shows the headline; the gated PDF contains full methodology. Works when the PDF is genuine value-add. + +--- + +## Audience-specific methodology depth + +Calibrate methodology depth to the audience's analytical sophistication. + +Highly analytical audiences (engineers, finance, data scientists). Detailed formulas, source citations, version history. The audience expects depth and rewards transparency. + +Moderately analytical audiences (PMs, marketers, operations). Plain-language formulas, key assumptions, summary citations. The audience wants to verify but does not need every variable. + +Less analytical audiences (executives, generalists). Plain-language summary of the methodology, key assumptions, "talk to us if you want depth" option. The audience trusts based on the summary; depth is available if needed. + +The discipline. Match the methodology depth to the audience that uses the calculator. Too thin loses analytical audiences; too dense loses generalist audiences. + +--- + +## Common methodology disclosure failures + +No methodology shown. Result without explanation; audience cannot verify or defend. + +Methodology hidden behind email. Lead-trap pattern applied to methodology; audience that wants to verify must opt in first. + +Methodology in marketing language. "Our proprietary algorithm draws on industry-leading data" is not methodology; it is brand copy. + +Methodology that hides the assumptions. Formulas shown; assumptions not stated; audience cannot tell what the calculator assumes about their situation. + +Methodology that hides the sources. Industry averages cited without attribution. + +Methodology that does not match the calculation. Stated methodology and actual implementation drift apart over time. + +Methodology with no update history. Calculator changes silently; audience that relied on previous outputs cannot see what changed. + +--- + +## Methodology-level choices that stay in the public skill + +The methodology page template. The assumption list template. The source citation patterns. Formula explanation patterns. Worked-example template. Caveats template. Update-history template. Methodology integration patterns. Audience-specific methodology depth. Common disclosure failures. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source-citation conventions and benchmark relationships. Specific formula-display tooling and styling. Specific worked-example libraries. The team's methodology update calendars and version control. These vary by team. diff --git a/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md b/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md new file mode 100644 index 0000000..5cd614b --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/result-presentation-patterns.md @@ -0,0 +1,247 @@ +# Result presentation patterns + +Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. The result is the calculator's product; bad presentation wastes the calculation work. + +A calculator that runs the right math and presents the result poorly fails as completely as a calculator that runs the wrong math. Result presentation is half the user experience. Get it wrong and the audience does not know what to do with the number they computed. + +--- + +## The presentation principle + +The result should be specific, contextualized, and actionable. + +Specific. A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." Precision matters; the audience uses the result in their actual decision. + +Contextualized. Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." Without the baseline, the number is just a number; with the baseline, it becomes meaningful. + +Actionable. What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step bridges from result to action. + +A result that hits all three is one the audience can use in their actual decision. A result that misses any of the three leaves the audience with an unanswered "so what." + +--- + +## The headline number + +The single most important output, large and prominent. + +The pattern. One number, one label, large type, central placement. The audience sees the headline number first. + +Example headline outputs. + +- "Estimated annual savings: $14,200" +- "Recommended plan: Growth (37 users, 3 admins)" +- "Time to payback: 8 months" +- "Estimated monthly cost: $2,400" + +The discipline. + +- One headline number, not five. Multiple competing headlines fragment the user's attention. +- Number with units. "$14,200" beats "14200." "8 months" beats "8." +- Honest framing. "Estimated" or "Projected" is honest; "Guaranteed" is overstatement. +- Visual hierarchy. The headline is the largest text on the result screen. + +Headline number antipatterns. + +- "Up to $50,000" (range with no specific value). +- "Significant savings" (no number). +- "X% improvement" (no base). +- Multiple competing numbers (user does not know which to focus on). + +--- + +## The breakdown + +Sub-results that explain how the headline number was calculated. + +The pattern. Below the headline, show the components that make up the result. + +Example breakdown for an ROI calculator. + +``` +Annual savings: $14,200 + + Cost reduction: $9,200 + Current cost: $36,000 + New cost: $26,800 + + Productivity gains: $4,000 + Hours saved per week: 8 + Hourly cost: $50 + Weeks per year: 50 + + Implementation savings: $1,000 (first year only) +``` + +Why the breakdown matters. + +- It makes the headline number defensible. The user can cite the components. +- It helps the user understand how their inputs influenced the result. Adjusting inputs becomes meaningful. +- It surfaces the assumptions implicitly. The user sees what the calculator weighted. + +Breakdown display options. + +- Stacked text (as above). +- Expandable section (compact by default; user opens for detail). +- Visual breakdown (stacked bar chart, pie chart for components). + +--- + +## Visualization + +Charts and graphics that help the user see the relationship. + +When visualization helps. + +- Comparing the result against a baseline ("current vs new"). +- Showing components contributing to a total ("savings breakdown"). +- Showing change over time ("month-by-month savings projection"). +- Showing thresholds ("you fall in the 'mid-market' band based on your inputs"). + +When visualization hurts. + +- When the data does not warrant a chart (a single number does not need a pie chart). +- When the chart obscures rather than clarifies (3D pie charts, gratuitous animation). +- When the chart cannot be interpreted on mobile. + +Visualization patterns. + +- Bar comparison. Current state vs new state. Easy to read; instant relative comparison. +- Stacked bar (component breakdown). Total height = headline; segments = components. +- Line chart (time series). Monthly cost projection over 12-24 months. +- Threshold indicator. Position the user's result on a scale ("you are at the 73rd percentile"). + +Visualization quality discipline. + +- Charts should be readable at the size displayed. +- Labels should be present and legible. +- Color should reinforce, not decorate (different colors for different components, not random palette). +- Mobile rendering should preserve readability; charts that work on desktop and break on mobile fail half the audience. + +--- + +## Scenario comparison + +Useful when the calculator is illustrating a delta between two states. + +The pattern. Show the user's current state and the projected state side-by-side, with the delta highlighted. + +Example: SaaS migration calculator. + +``` + Current New Change +Annual cost $36,000 $24,000 -$12,000 +Hours/week 12 hrs/wk 4 hrs/wk -8 hrs/wk +Errors/month 14 3 -11 +``` + +Why scenario comparison works. + +- The delta is the value proposition; showing both states makes the delta concrete. +- The user can see what they are giving up (if anything) alongside what they are gaining. +- The comparison format is familiar from spreadsheets and decision tools. + +When scenario comparison applies. Calculators that compare a current state to a proposed state (migrations, refinances, configurations). Less applicable to calculators that produce a single recommendation without an explicit baseline. + +--- + +## Result-presentation antipatterns + +Patterns that waste the calculation. + +Buried result. The result requires scrolling past 5 paragraphs of marketing. The user came for the result; serve it first. + +Vague output. "Significant" or "Up to" framing without specific values. The audience cannot use vague results in real decisions. + +Result followed by 5 paragraphs of marketing. The result is what the user came for; the brand pitch belongs after, not before. + +Result that requires re-entering inputs to view. Persist inputs and results within the session. Forcing re-entry is a friction the user did not consent to. + +False precision. "$14,237.42" when the inputs justify only "$14,000 (estimated)." Precision the math does not support erodes trust. + +Multiple competing headlines. Five "important" numbers; the user does not know what to focus on. + +Disconnected result and breakdown. The headline number does not obviously add up from the breakdown components. The user does the mental math, finds the gap, loses trust. + +Result without a next step. The user gets the number, then what? Without a next step, the calculator does not bridge to action. + +--- + +## Mobile result presentation + +The result should work on mobile. + +Mobile-specific considerations. + +- Headline number readable without zoom. +- Breakdown components stack vertically rather than spread horizontally. +- Visualizations sized for mobile screens; complex multi-axis charts often do not translate. +- Scroll position lands on the result, not the inputs. + +Common mobile failures. + +- Headline number tiny on mobile because it was sized for desktop. +- Breakdown table requires horizontal scroll. +- Charts illegible at mobile size. +- Result hidden below the fold; user does not know it loaded. + +--- + +## Result-to-action transitions + +The result should lead naturally to a next step. + +Patterns. + +- CTA below the result. "Get a PDF of this analysis" or "Save this scenario" or "Talk to our team about implementing this." +- Multiple CTAs ranked. Primary action prominent; secondary action visible but smaller; tertiary action available but not pushy. +- Email-capture in context. When the gated tier (PDF, save) is offered, the form appears in context with the result, not in a popup that breaks flow. + +The discipline. + +- The next step should match the audience's likely intent. After a savings calculator, "talk to sales" may be premature; "get a PDF I can share" may match. +- Multiple CTAs should not compete; rank them by likely user intent. +- The next step should be honest. Promising "instant analysis from a specialist" and delivering "we will email you in 5 days" breaks trust. + +--- + +## Result update behavior + +When the user adjusts inputs, the result updates. + +Real-time updates. As the user changes a slider, the result recalculates. Useful for exploration; the audience sees the relationship between inputs and result. + +On-submit updates. The user adjusts inputs, hits Calculate, sees the new result. Useful for calculators with many inputs where real-time updates would be distracting. + +Hybrid. Real-time for sliders and toggles; on-submit for full input changes. Common middle ground. + +The choice. Depends on calculator complexity and the value of input exploration. Calculators that benefit from "what if" exploration favor real-time; calculators that produce a definitive recommendation favor on-submit. + +--- + +## Result-context for share-ability + +When users share the result with stakeholders, the result has to be self-contained. + +The principle. The shared result (PDF, email, screenshot, link) should be interpretable by someone who did not run the calculator. + +What share-able results need. + +- The headline number and what it represents. +- The breakdown so the recipient can verify the math. +- The methodology so the recipient can interrogate the assumptions. +- The inputs so the recipient knows what scenario was modeled. +- Brand attribution so the recipient knows the source. + +The non-shareable result. "Your savings: $14,200" with no inputs, no methodology, no breakdown. The recipient cannot use this; they ignore it or come back to ask follow-up questions that should not have been necessary. + +The shareable result extends the calculator's reach. The audience that shares is bringing the brand into a conversation; make the result strong enough to carry that weight. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation principle (specific, contextualized, actionable). Headline number discipline. Breakdown patterns. Visualization patterns and discipline. Scenario comparison. Result-presentation antipatterns. Mobile result presentation. Result-to-action transitions. Result update behavior. Share-ability discipline. + +## Implementation choices that stay internal + +Specific result-page layouts for specific calculators. Specific visualization libraries and styling. Specific PDF templates for share-able results. Specific brand-voice copy for next-step CTAs. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md b/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md new file mode 100644 index 0000000..ce17cf8 --- /dev/null +++ b/dist/pi/.agents/skills/calculator-design/references/tiered-value-structures.md @@ -0,0 +1,236 @@ +# Tiered value structures + +Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. + +The architecture that lets calculators capture leads honestly. The user gets immediate value (free tier) and is offered progressively richer value at each tier with proportional friction. Each tier earns its gate. + +--- + +## The tier-design principle + +Each tier should add real value over the previous. Tiers that gate the same content at higher friction destroy trust. + +Tier 1 (no gate). Immediate, complete result. The audience gets what they came for. The free tier is not a teaser; it is the substantive output of the calculator. + +Tier 2 (email-gated). Additional value the user might want for sharing, persistence, or depth. Email is the appropriate friction level for this value. + +Tier 3 (account-gated). Persistent, multi-session, collaborative, or product-integrated value. Account creation is the appropriate friction level for this value. + +Each tier's friction matches its value-add. Tiers that ask for more friction than they justify destroy conversion. + +--- + +## Tier 1: free immediate result + +What lives at Tier 1. + +The calculator's primary output. The headline result the user came for. Annual savings, recommended plan, monthly cost, time to payback. + +The breakdown. Components that show how the headline was calculated. + +Basic visualization. A chart or comparison that helps the user see the relationship. + +Methodology disclosure. Either inline formulas or a methodology link. + +Assumption list. What the calculator assumes about the user's situation. + +Source citations. Where the calculator's benchmarks come from. + +The Tier 1 set is complete. A user who never opts into Tier 2 still got the calculator's full value. The brand still earns trust; the audience still associates the brand with the topic. + +What Tier 1 should NOT include. + +- A teaser version of the result that withholds the actual answer. +- A "preview" of the analysis that requires email to see in full. +- Marketing copy that displaces the result itself. + +--- + +## Tier 2: email-gated additional value + +What lives at Tier 2. + +A formatted PDF report. The Tier 1 content packaged in a shareable format. The PDF has to be genuinely better than a screenshot, or the gate is not justified. + +A saved scenario. The user's inputs and result persist; they can return to the calculator and see their previous calculation. + +A custom analysis. A deeper second-pass calculation, often delivered by email after submission. + +Notification opt-in. Updates when benchmarks change, when new calculator versions launch, or when the brand publishes related content. + +Tier 2 design discipline. + +- Each Tier 2 offering must clearly justify the email exchange. "Get a PDF that you can share with your CFO" is justifiable; "Get the same content in a PDF" is not. +- The email-capture form should appear in context with the offer, not as an interruption to the Tier 1 viewing. +- The follow-up email should deliver the promised value immediately, not delay it. + +--- + +## Tier 3: account-gated persistent value + +What lives at Tier 3. + +Save-and-compare across multiple scenarios. The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +Historical tracking. When the calculator is used periodically (monthly projection, quarterly review), the user's historical inputs and results are tracked over time. + +Collaboration features. Multiple users on the same account can model scenarios together. + +Product integration. The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +Tier 3 design discipline. + +- Account creation is significant friction. Tier 3 features must justify it. +- Tier 3 is often unnecessary. Many calculators serve their purpose with Tier 1 and Tier 2 alone; do not add Tier 3 unless the use case warrants it. +- Account-creation friction can be reduced (social login, magic link) but not eliminated. + +--- + +## Worked example: SaaS pricing calculator + +A B2B SaaS platform considering a tiered pricing calculator. + +Tier 1 (free). + +- The user enters team size, role distribution, and use case. +- Sees the recommended plan and the estimated monthly cost. +- Sees a breakdown showing per-seat cost, included features, and any add-ons. +- Sees a comparison against the next-tier-up plan with a brief explanation of when it would be worth it. +- Sees a methodology link explaining how recommendations are made. + +Tier 2 (email-gated). + +- A PDF showing the recommended plan, the breakdown, the next-tier comparison, and 2-3 customer case studies of similar teams using similar plans. +- The PDF is shareable and contains enough context for an internal stakeholder to evaluate. + +Tier 3 (account-gated). + +- The user can save the scenario and adjust inputs over time as the team grows. +- The user can model alternative scenarios (different team size, different use case) and compare side-by-side. +- The user can receive an email when their team size threshold suggests a tier change. + +Each tier earns its gate. The user can stop at Tier 1 and still get value. Tier 2 is offered as a way to share with stakeholders. Tier 3 is offered for users who want ongoing tracking. + +--- + +## Worked example: ROI calculator for a B2B service + +A B2B service company considering an ROI calculator. + +Tier 1 (free). + +- The user enters current cost, team size, and process maturity. +- Sees estimated annual savings. +- Sees a breakdown across cost reduction, productivity gains, and implementation savings. +- Sees the methodology disclosed inline. + +Tier 2 (email-gated). + +- A PDF showing the calculation in defensible form, with industry-context comparison and a worked-example case study from a similar customer. + +Tier 3. Not offered. The calculator is single-use; account creation would be unnecessary friction. + +The two-tier structure fits the use case. Adding Tier 3 would add friction without value. + +--- + +## Worked example: financial calculator (mortgage, refinance, savings) + +A financial services company considering a savings calculator. + +Tier 1 (free). + +- The user enters current loan details, target rate, and timeline. +- Sees estimated monthly savings, total savings over the loan term, and break-even point on closing costs. +- Sees the breakdown and methodology. + +Tier 2 (email-gated). + +- A PDF analysis with comparison across multiple lender scenarios. +- A personalized rate quote (which requires underwriting based on user inputs). + +Tier 3. Optional. An account that tracks the user's loan over time and notifies them when refinance opportunities emerge as rates change. + +The Tier 2 includes genuine value-add (personalized quote requires underwriting). The Tier 3 is optional for users who want ongoing monitoring. + +--- + +## Tier-design failures + +Patterns that look like tiered value but degrade trust. + +Teaser-tier-as-Tier-1. The free tier shows a partial result; the email tier shows the full result. This is lead-trap dressed as tiered value. + +Same-content-different-format. Tier 1 is the result on screen; Tier 2 is the same result in a PDF. The PDF is not value-add; the gate is not justified. + +Inverted tiers. Tier 1 is thin; Tier 2 is what should have been Tier 1; Tier 3 is what should have been Tier 2. The audience that gets Tier 1 sees nothing useful; conversion drops. + +Tier-3 friction without Tier-3 value. Account creation required for features that could have been email-only or free. Friction without value-add destroys the gate. + +Surprise upsells. The user opts into Tier 2; the email follow-up reveals additional gates the user did not anticipate. Trust drops. + +--- + +## The flat-tier alternative + +Some calculators do not need tiers. + +When flat is right. + +- Simple calculators where the result is the only output worth offering. +- Calculators built for SEO or brand authority where lead capture is secondary. +- Calculators where account creation does not match the use case. + +The flat structure. Tier 1 (free, complete result). Optional email opt-in for newsletter or related content (no gate, no friction). + +This structure works when the calculator's primary value is the calculation itself and the lead-capture motion is secondary or absent. + +--- + +## Tier transitions + +How the user moves from tier to tier. + +Tier 1 to Tier 2. The user sees the free result. Below or alongside, an offer: "Want this as a PDF you can share?" or "Save this scenario for later." Email-capture in context. + +Tier 2 to Tier 3. After the user has engaged with Tier 2 (downloaded the PDF, returned to the saved scenario), an offer: "Want to track this over time? Create an account." The friction increase is justified by the additional value. + +The discipline. Tier transitions should feel natural, not pushy. The user gets value at each tier; the next tier is offered, not demanded. + +--- + +## Tier maintenance + +Tiers decay along with the calculator. + +Tier 1 maintenance. Update defaults, refresh sources, update methodology as benchmarks shift. + +Tier 2 maintenance. Update PDF templates as the brand evolves; refresh case studies; update comparison data. + +Tier 3 maintenance. Maintain the account-side functionality; ensure persistence works; update integrations. + +The retire-tier decision. Tier 3 features that are not used can be retired. Tier 2 PDFs that no one downloads can be simplified. Periodic audit of tier usage informs maintenance. + +--- + +## Common tier failures + +Tier 1 is a teaser. Lead-trap pattern. + +Tier 2 does not justify the email. Same content, repackaged. + +Tier 3 is offered but unused. Friction without payoff; sometimes the right answer is to retire Tier 3. + +Tier transitions are pushy. Aggressive popups at each transition; the user feels pressured. + +Tier maintenance lapses. Stale PDFs, broken account features, outdated comparison data. + +--- + +## Methodology-level choices that stay in the public skill + +The tier-design principle. What lives at each tier. Tier-design discipline at each level. Worked examples across calculator types. The flat-tier alternative. Tier transitions. Tier maintenance. Common failures. + +## Implementation choices that stay internal + +Specific tier structures for specific calculators. Specific PDF templates and account-creation flows. Specific tooling for tier transitions. The team's tier-usage measurement and audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md b/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md new file mode 100644 index 0000000..0cdffe9 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/SKILL.md @@ -0,0 +1,266 @@ +--- +name: chatbot-flow-design +description: "Designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. Honest about scripted-bot (rigid trees, fail edge cases), hallucinating-bot (LLM without structure, makes things up), and structured-guided-conversation (LLM-powered with intent architecture and fallback discipline) patterns. Distinguishes chatbot DESIGN (this skill) from chatbot IMPLEMENTATION (engineering and platform work). Triggers on chatbot, conversational AI, AI agent, chat widget, intent design, conversational flow, bot escalation, LLM grounding. Also triggers when a chatbot is hallucinating, when a scripted bot is failing edge cases, or when a chatbot is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing conversational flows for chatbots and AI agents on websites. Distinguishes scripted-bot (rigid trees, fail edge cases) from hallucinating-bot (LLM without structure, makes things up) from structured-guided-conversation (LLM-powered with intent architecture and fallback discipline)" +display_order: 5 +--- + +# Chatbot Flow Design + +A senior growth practitioner's playbook for designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. The discipline of building a bot that knows what it knows and routes appropriately when it does not. + +Most chatbots on the web fail in one of two ways. Scripted bots break the moment a user phrases something the script did not anticipate; the user gets pushed through a decision tree that does not fit their situation. LLM-powered bots without structure hallucinate; they confidently answer questions about pricing, policy, or capabilities and frequently make up answers, creating support burden and trust damage. + +The chatbots that work do something different. They have an intent architecture that defines what the bot can and cannot handle. They ground their responses in a knowledge base so they do not invent facts. They have explicit fallback paths for unclear or out-of-scope intents. They escalate to humans cleanly when the bot's job is done. The audience trusts the bot because the bot is honest about its scope. + +The voice is the senior growth practitioner who has watched chatbots become trusted brand surfaces and watched them become liability risks. Practical, opinionated about the architecture that distinguishes the two outcomes, willing to call out when a chatbot is the wrong investment or when an existing chatbot needs to be redesigned rather than tuned. + +When to use this skill: scoping a chatbot for the first time, auditing a chatbot that hallucinates or fails edge cases, designing the intent architecture and fallback patterns, or deciding when to escalate to humans. + +--- + +## What this skill covers + +This skill spans chatbot design as conversational flow architecture, not chatbot implementation. The growth-tooling distinctions: + +- `ai-content-collaboration` covers AI in content workflows. This skill covers AI in customer-facing conversations. +- `integration-orchestrator` covers cross-team coordination for chatbot deployment. This skill is the conversational design itself. +- `pm-spec-writing` covers the spec for engineers building the bot. This skill is about WHAT the conversation should be; pm-spec-writing is about communicating it. +- `discovery-research-synthesis` covers customer research that informs intent architecture. Input to this skill, not part of it. +- `chatbot-flow-design` (this skill) is intent architecture, knowledge-base grounding, fallback patterns, and escalation discipline. + +The audience: growth marketers and product marketers shipping chatbot growth tooling, in-house teams designing conversational flows for marketing or support contexts, agencies running chatbot work for clients. + +Out of scope: AI in content workflows (covered by `ai-content-collaboration`); the engineering implementation of chatbots (handed off via `pm-spec-writing`); platform-specific bot configurations (those stay implementation-side); voice agents and IVR flows (different methodology though related principles apply). + +--- + +## The chatbot decision: when chatbots earn deployment + +Before designing the chatbot, decide whether a chatbot is the right tool. + +Chatbots earn deployment when: + +- The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. +- The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. +- The bot can ground its answers in real knowledge (documentation, product specs, pricing pages). Without grounding, the bot's answers are at best generic and at worst fabricated. +- The team can maintain the bot. Chatbots decay; intents drift; knowledge bases need updating. Without maintenance commitment, the bot becomes stale liability. + +Chatbots do NOT earn deployment when: + +- The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. +- The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates or stays so generic it adds no value. +- The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. +- The audience is small enough that direct human conversation is more efficient. +- The team cannot maintain the bot. Stale bots produce wrong answers. + +The decision is not "should we have a chatbot"; it is "is the chatbot the right tool for this specific audience and conversation." + +Detail in [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md). + +--- + +## Scripted-bot vs hallucinating-bot vs structured-guided-conversation + +The keystone framing. + +Scripted-bot. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. The chatbot equivalent of an automated phone tree. Cost: the user's actual question goes unanswered; the bot pushes the user through paths that do not fit; the audience leaves with a worse experience than no bot. + +Hallucinating-bot. LLM-powered with no structure. Will confidently answer questions about pricing, policy, capabilities, and frequently make up answers. Liability risk; trust-eroding; support burden when wrong answers reach customers. Cost: the bot's confident wrong answers damage the brand more than no bot would; the team learns about the hallucinations through customer complaints. + +Structured-guided-conversation. LLM-powered with intent architecture, knowledge-base grounding, defined fallback paths, and explicit escalation to humans. The bot knows what it knows, knows what it does not, and routes appropriately. Cost: the design effort upfront is significant; the maintenance is real; the audience trusts the bot because the bot is honest about its scope. + +The litmus test. Ask the bot a question outside its intended scope. Does it confidently make up an answer (hallucinating), refuse rigidly (scripted), or honestly route the user to a human or alternative resource (structured-guided)? The third response is the goal. + +--- + +## Intent architecture + +Defining what the bot can and cannot handle. + +The principle. The bot has a defined set of intents it can handle. Each intent maps to a conversation pattern (questions to ask, knowledge to ground in, response to provide). Anything outside the intent set falls to fallback. + +Intent design patterns. + +- Named intents. "Pricing question," "feature comparison," "integration question," "support escalation," "demo request." Each intent is explicit. +- Intent hierarchy. Top-level categories with sub-intents. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question." +- Intent boundaries. Each intent has clear scope. Out-of-scope topics route to fallback. + +Intent coverage. The bot's intents should cover 70-90 percent of expected conversations. The remaining percentage falls to fallback. Trying to cover 100 percent often produces bloated intent sets that the bot cannot handle reliably. + +Intent maintenance. Intents drift as products evolve, audiences shift, and conversations change. Periodic review surfaces which intents are useful and which need refining. + +Detail in [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md). + +--- + +## Knowledge-base grounding + +The bot's responses must come from real knowledge, not made-up confidence. + +The principle. The bot's response generation should reference a structured knowledge base (documentation, product specs, pricing pages, support articles). The bot does not invent answers; it retrieves and presents. + +Grounding patterns. + +- Retrieval-augmented generation (RAG). The bot searches a knowledge base for relevant content before generating a response. The response is grounded in retrieved content. +- Source-of-truth design. The knowledge base is the canonical source. When the bot answers, the underlying source is identified. +- Citation discipline. The bot can cite the source ("based on our pricing page, ..."). Audiences benefit from knowing where the answer came from. +- Knowledge-base maintenance. The knowledge base is maintained as the product evolves; the bot's answers stay current. + +The hallucinating-bot failure. No grounding. The LLM generates confident-sounding answers from nothing. The team discovers wrong answers through customer complaints. + +The structured-guided win. Grounded answers. The bot's responses match the source-of-truth. Customer-facing accuracy is maintained. + +Detail in [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md). + +--- + +## Branching and conditional logic + +How the bot adapts the conversation based on user input. + +The principle. The bot's conversation can branch based on user inputs (intent recognized, prior answers, user attributes). Branching makes the conversation feel adaptive. + +Branching patterns. + +- Intent-driven branching. Different intents lead to different conversation flows. +- Context-driven branching. "Are you asking about plan A or plan B?" routes to plan-specific information. +- User-attribute branching. Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB. +- Multi-turn branching. The conversation deepens over turns; later turns build on earlier context. + +Branching discipline. Each branch should add value. Decorative branching (asking for confirmation when none is needed) adds friction. + +Branching limits. Bots that branch too deeply lose users. 3-5 turns is often the practical limit before the user wants resolution. + +Detail in [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md). + +--- + +## Fallback patterns + +What happens when intent is unclear or out-of-scope. + +The principle. Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." + +Fallback patterns. + +- Clarifying question. "Can you tell me more about what you are looking for?" Asks the user to refine; sometimes recovers. +- Suggested intents. "I can help with X, Y, or Z. Were you asking about one of those?" Surfaces what the bot can do. +- Resource handoff. "I cannot answer that, but here is our [documentation page] that covers it." +- Human escalation. "Let me connect you with a human who can help." + +Fallback discipline. Multiple fallback layers. First, try clarification. If unclear after one round, suggest alternatives or escalate. Do not loop the user through 5 clarification attempts. + +The fallback-as-honesty principle. A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers they were given confidently. + +Detail in [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md). + +--- + +## Escalation to human + +When, how, with what context handoff. + +The principle. Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. + +Escalation triggers. + +- User-initiated. "Talk to a human." The bot escalates immediately. +- Out-of-scope intent. The bot recognizes the user's intent is outside its scope; escalates with the intent context. +- Repeated fallback. After 2-3 unclear exchanges, the bot escalates rather than loop. +- Sentiment-driven. The user's sentiment indicates frustration; the bot escalates rather than persist. +- High-stakes topic. Sensitive topics (cancellations, complaints, security) escalate by default. + +Escalation context handoff. When escalating, the bot passes the conversation history and recognized intent to the human. The human does not start from scratch; they pick up where the bot left off. + +The escalation-quality test. Does the human pick up the context smoothly, or do they have to ask the user to repeat everything? The latter signals broken handoff. + +Detail in [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md). + +--- + +## Conversation analytics + +Measuring what the bot is and is not doing well. + +The principle. Track the bot's performance per intent, per fallback, per escalation. The data informs maintenance and design improvements. + +Conversation metrics. + +- Intent recognition rate. What percentage of conversations are correctly classified into intents? +- Resolution rate per intent. What percentage of conversations starting with intent X resolve successfully (user gets the answer they needed)? +- Fallback rate. What percentage of conversations hit fallback? High fallback rates signal intent gaps. +- Escalation rate per intent. What percentage of conversations within each intent escalate? High escalation may signal the intent should not be bot-handled. +- User satisfaction. Post-conversation surveys when feasible. Useful but limited; many users do not respond. + +Diagnostic uses. + +- High fallback rate: intents missing or unclear; expand or refine intent set. +- Low resolution rate per intent: knowledge base inadequate; improve grounding. +- High escalation rate per intent: the intent may not be appropriate for bot handling. +- High repeat-fallback within conversations: clarifying questions not landing; redesign clarification. + +Detail in [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md). + +- "Bot makes up answers about pricing." Hallucinating-bot pattern; no grounding to pricing source-of-truth. +- "Users say the bot is rigid and unhelpful." Scripted-bot pattern; intents do not cover real questions. +- "Sales is angry that the bot is qualifying leads wrong." Intent recognition or routing logic broken; audit qualification flow. +- "Support tickets increase after chatbot launch." Bot is producing wrong answers that send users to support; audit grounding and resolution. +- "Users abandon mid-conversation." Bot loops or fallback patterns are inadequate. +- "We cannot tell what the bot is actually doing." Analytics missing; instrument before further changes. +- "Bot was great at launch; quality has degraded." Maintenance lapse; knowledge base or intent set out of date. +- "Bot escalates to humans for everything." Escalation logic too permissive; bot should handle more. +- "Bot tries to handle everything itself." Escalation logic too restrictive; bot should escalate more. +- "Users complain the bot does not know what they asked five minutes ago." Conversation context not preserved across turns. + +--- + +## The framework: 12 considerations for chatbot flow design + +When designing or auditing a chatbot, walk these 12 considerations. + +1. The chatbot decision. Is a chatbot the right tool for this audience and conversation, or would a different channel serve? +2. Structured-guided-conversation, not scripted or hallucinating. Intent architecture; knowledge-base grounding; fallback discipline. +3. Intent architecture sound. Named intents with clear scope; coverage targets 70-90 percent of expected conversations. +4. Knowledge-base grounded. Responses retrieved from source-of-truth; the bot does not invent answers. +5. Branching adds value. Each branch serves a real need; depth limited to 3-5 turns. +6. Fallback patterns multi-layered. Clarification, suggested intents, resource handoff, human escalation. +7. Escalation triggers defined. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. +8. Escalation context handoff clean. Humans pick up where the bot left off. +9. Analytics instrumented. Per-intent recognition, resolution, fallback, escalation rates. +10. Maintenance cadence defined. Knowledge base refreshed; intent set audited; bot quality verified. +11. Brand voice consistent. The bot sounds like the brand it represents. +12. Audience-fit honest. The bot serves the audience it can actually help; out-of-fit audiences get escalated quickly. + +The output of the framework is a chatbot that knows what it knows, grounds its answers in real knowledge, escalates appropriately, and earns trust by being honest about its scope. + +--- + +## Reference files + +- [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md) - When chatbots earn deployment and when they do not. The conditions that warrant the build. +- [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md) - Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. +- [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md) - Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. +- [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md) - How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. +- [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md) - What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. +- [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md) - When, how, with what context. Escalation triggers and handoff quality. +- [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md) - Per-intent metrics. Diagnostic uses. The data that informs maintenance. +- [`references/chatbot-anti-patterns.md`](references/chatbot-anti-patterns.md) - The patterns that look like chatbots but degrade trust. +- [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: chatbots earn deployment when they know what they don't know + +The chatbots that work as compounding assets are the ones the audience trusts. Not because they answer every question. Not because they are infinitely capable. Because they are honest about their scope, ground their answers in real knowledge, and escalate to humans when the bot's job is done. + +That is the bar. Below the bar are scripted-bots (rigid trees that fail edge cases) and hallucinating-bots (LLMs without structure that make things up). Above the bar are structured-guided-conversations where the bot's intent architecture, knowledge-base grounding, fallback discipline, and escalation patterns combine into a tool the audience can rely on. + +The discipline is in the design choices. The intents that define what the bot can do. The knowledge-base grounding that prevents hallucination. The fallback patterns that handle the unknown gracefully. The escalation logic that knows when to step aside. The analytics that surface what is working and what is not. The maintenance discipline that keeps the bot in sync with the brand it represents. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md b/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md new file mode 100644 index 0000000..7ca9f24 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/branching-and-conditional-logic.md @@ -0,0 +1,269 @@ +# Branching and conditional logic + +How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. + +The bot's conversation can branch based on user inputs. Branching makes the conversation feel adaptive; over-branching makes it feel labyrinthine. + +--- + +## The adaptive principle + +The bot adapts the conversation to the user's situation. Branching is the mechanism. + +The win. A user asks about pricing; the bot recognizes the user is on the enterprise track (from earlier inputs or context); the response includes enterprise-specific information rather than starter-tier information. + +The fail (no branching). Every user gets the same response regardless of context. The pricing question gets a generic answer that helps no one specifically. + +The fail (over-branching). The conversation branches at every turn; the user feels stuck in a labyrinth; resolution recedes. + +The discipline. Branch when branching adds value. Avoid branching when it adds friction. + +--- + +## Pattern A: Intent-driven branching + +Different intents lead to different conversation flows. + +How it works. + +- The bot recognizes the user's intent. +- The conversation flow for that intent kicks in. +- Each intent has its own scripted or templated response pattern. + +Example. + +User: "How much does the Pro plan cost?" +Bot recognizes "pricing question" intent. +Bot routes to pricing-conversation flow: +- Retrieves pricing. +- Presents Pro plan pricing. +- Offers follow-up: "Would you like to compare with other tiers, or talk to sales for a custom quote?" + +Strengths. + +- Each intent gets a dedicated, optimized flow. +- Easy to maintain (changes to one intent do not affect others). + +Weaknesses. + +- Requires intent recognition to work reliably. +- Cross-intent topics may not fit any single flow. + +When to use. Default for most chatbots. Intent-driven branching is the foundation. + +--- + +## Pattern B: Context-driven branching + +Branching within an intent based on context. + +How it works. + +- Within an intent's flow, the bot asks clarifying questions or branches based on context. +- "Are you asking about plan A or plan B?" routes the rest of the conversation to plan-specific information. + +Example. + +User: "How does the API work?" +Bot recognizes "integration question" intent. +Within the integration flow, the bot asks: "Are you looking at REST or GraphQL?" +User: "REST." +Bot routes to REST-specific information. + +Strengths. + +- Within-intent precision. +- The user feels heard; the response addresses their specific situation. + +Weaknesses. + +- Each clarifying question adds a turn; can frustrate users who want quick answers. + +The discipline. Use context-driven branching only when the context genuinely affects the response. Decorative clarifications add friction. + +--- + +## Pattern C: User-attribute branching + +Branching based on user attributes (logged-in status, role, segment). + +How it works. + +- The bot accesses user attributes (often from a CRM or session data). +- Responses adapt to those attributes. +- "Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB." + +Example. + +User: "Tell me about your pricing." +Bot detects the user is from a domain associated with an enterprise account. +Bot routes to enterprise-specific pricing conversation: "For teams of 200+, we offer a custom Enterprise plan. Here are the typical components..." + +Strengths. + +- Highly personalized. +- The right information for the right audience. + +Weaknesses. + +- Requires attribute infrastructure (CRM integration, session data). +- Privacy considerations (the bot is using data the user may not have explicitly shared). +- Risk of getting attributes wrong (a freelancer with a corporate domain treated as enterprise). + +When to use. When the attribute infrastructure exists and the personalization genuinely improves the experience. + +--- + +## Pattern D: Multi-turn branching + +The conversation deepens over turns. Later turns build on earlier context. + +How it works. + +- The bot maintains conversation state across turns. +- Each turn's response considers what was said in previous turns. +- The conversation can pivot, deepen, or refocus based on the cumulative context. + +Example. + +Turn 1. +User: "I am evaluating CRMs." +Bot: "What size is your team?" +User: "We have 25 sales reps." + +Turn 2. +Bot: "For a team of 25, our Growth plan often fits. Are you looking at any specific features?" +User: "We need integration with HubSpot." + +Turn 3. +Bot: "Our HubSpot integration supports two-way sync, lead routing, and custom fields. Would you like to see a demo focused on this integration?" + +The conversation deepens. Each turn builds on the previous. + +Strengths. + +- Conversation feels natural. +- Bot can handle complex inquiries that require multiple inputs. + +Weaknesses. + +- Conversation state management is complex. +- Long conversations risk losing context. +- Users may want resolution faster than multi-turn allows. + +The discipline. Limit multi-turn conversations to 3-5 turns before either resolving, escalating, or offering a summary handoff. Beyond that, users abandon. + +--- + +## Branching depth limits + +Bots that branch too deeply lose users. + +The 3-5 turn principle. Most users want resolution within 3-5 turns. Beyond that, the bot's value declines. + +When 3-5 turns is enough. Most marketing-site Q&A, simple support, qualification. + +When more turns are needed. Complex troubleshooting, detailed product configuration. In these cases, the bot should consider escalating to a human or offering a richer interface (form, video walkthrough). + +Branching as turn-cost. Each branch adds a turn. Branches that do not resolve within the turn budget should be reconsidered. + +--- + +## Branching design patterns + +How to structure branches. + +Linear branching. A then B then C. Simple; fits intent-driven patterns. + +Tree branching. A leads to B or C; each leads to further options. Common; fits context-driven and user-attribute patterns. + +Loop-back branching. Conversation can return to earlier turns. Useful when users want to compare options. + +Open-ended branching. Conversation can take multiple paths from any point. Most flexible; hardest to maintain. + +The choice depends on conversation complexity. Most chatbots benefit from tree branching with limited depth. + +--- + +## Branching and brand voice + +The bot's voice should stay consistent across branches. + +The principle. Branching changes the conversation's content; the brand voice stays consistent. + +Voice failures across branches. + +- One intent's flow is formal; another is casual. Inconsistent. +- Bot voice shifts based on user attributes in ways that feel performative. +- Branches that adopt different personas confuse the user. + +The discipline. Voice consistent; content adaptive. + +--- + +## Conversation state management + +What the bot remembers across turns. + +Within-conversation state. + +- Recognized intent and sub-intent. +- Captured user inputs (company size, role, specific interests). +- Conversation history. +- Pending follow-up actions. + +Across-conversation state. When the user returns later (in the same session or a new session), what does the bot remember? + +- Logged-in users: bot may remember previous conversations. +- Anonymous users: bot typically starts fresh; some implementations use cookies for limited memory. +- Privacy considerations: cross-session memory should be transparent and opt-in where appropriate. + +The discipline. State management should serve the user. State that improves the experience is good; state that surprises or feels invasive is bad. + +--- + +## Branching testing + +Test the bot across branching paths. + +The challenge. A bot with multiple branching points has many paths through any given conversation. Testing all paths is infeasible; testing critical paths is the discipline. + +Critical paths. + +- The most common conversation patterns (most-frequent intents). +- Each major branch point (one path that takes each branch). +- Edge cases (unusual user inputs that could break branching). + +Testing methods. + +- Manual testing of critical paths. +- Automated testing where feasible. +- Sampling production conversations to verify branching behavior. + +--- + +## Common branching failures + +Decorative branching. Clarifying questions that do not change the response; user feels stuck. + +Branching without resolution. Conversation branches but never resolves; user gives up. + +Branching depth too deep. 8+ turns without resolution; user abandons. + +Inconsistent voice across branches. Different intents speak differently. + +State loss across turns. Bot forgets earlier context; conversation feels disjointed. + +Privacy-violating attribute branching. Bot uses attributes the user did not consent to share. + +Untested edge-case branches. Specific paths break in production. + +--- + +## Methodology-level choices that stay in the public skill + +The adaptive principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Branching depth limits. Branching design patterns. Branching and brand voice. Conversation state management. Branching testing. Common failures. + +## Implementation choices that stay internal + +Specific branching designs for specific bots. Specific state management implementations. Specific tooling for branching and testing. The team's testing protocols. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md new file mode 100644 index 0000000..52d7dda --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-anti-patterns.md @@ -0,0 +1,224 @@ +# Chatbot anti-patterns + +The patterns that look like chatbots but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The scripted-bot + +The pattern. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. + +The signal. Users complain the bot is rigid; bot fails any conversation that does not match the predefined paths. + +The cost. The user's actual question goes unanswered. The bot pushes the user through paths that do not fit. Audience leaves with a worse experience than no bot. + +The cure. Move from rigid trees to LLM-powered intent recognition with grounded responses. Detail in `references/intent-architecture-patterns.md` and `references/knowledge-base-grounding-patterns.md`. + +--- + +## The hallucinating-bot + +The pattern. LLM-powered with no structure. Confidently answers questions about pricing, policy, capabilities, and frequently makes up answers. + +The signal. Customer complaints about wrong information from the bot; sales or support hearing audiences cite incorrect bot answers. + +The cost. Liability risk. Trust damage. Support burden when wrong answers reach customers. + +The cure. Add intent architecture and knowledge-base grounding. The bot retrieves from sources-of-truth rather than generating from training data. + +--- + +## The bot-that-tries-to-handle-everything + +The pattern. Bot scope is "anything the user asks." No defined intents; no fallback discipline. + +The signal. High hallucination rate; high resolution-rate variability across topics; users get inconsistent experiences. + +The cost. The bot is unreliable. Some conversations work; many do not. Users cannot predict what they will get. + +The cure. Define explicit intent scope. Honest fallback for everything outside scope. Detail in `references/intent-architecture-patterns.md`. + +--- + +## The bot-that-handles-nothing + +The pattern. Bot's intent set is so narrow that most conversations fall to fallback or escalation. + +The signal. High fallback rate; high escalation rate; bot adds little value over a contact form. + +The cost. The build cost was significant; the value delivered is small. + +The cure. Expand the intent set to cover the conversations the audience actually has. Detail in `references/intent-architecture-patterns.md` (intent coverage section). + +--- + +## The bot-that-loops + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. Detail in `references/fallback-pattern-design.md` (fallback loop section). + +--- + +## The bot-that-refuses-rigidly + +The pattern. Bot says "I cannot help with that" without offering paths forward. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer alternatives. Resource handoff or human escalation. The bot's "I cannot help" should be followed by "but here is what might." + +--- + +## The bot-with-no-escalation + +The pattern. Bot tries to handle everything itself; rarely escalates; users get stuck with bot for conversations needing humans. + +The signal. Specific intents have high abandonment; users complaining they could not reach a human; sensitive topics handled poorly by the bot. + +The cost. The user's frustration compounds. The brand earns "you cannot reach a human" reputation. + +The cure. Define escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## The bot-that-escalates-everything + +The pattern. Bot escalates almost every conversation; the bot is not really doing its job. + +The signal. Escalation rate near 100 percent; bot adds friction without value. + +The cost. The bot is decorative. The team built a chatbot when they needed staffing. + +The cure. Either expand the bot's intent handling capability or reconsider whether the chatbot is the right tool. Sometimes the answer is to invest in human chat instead. + +--- + +## The bot-with-broken-handoff + +The pattern. Bot escalates; human picks up; the human starts from scratch because the context was not passed. + +The signal. Users complain about repeating themselves; humans report not knowing what the bot was discussing. + +The cost. The escalation experience is broken. Users feel the bot was wasted effort. + +The cure. Test the handoff. Ensure the human sees the conversation history and recognized intent. Detail in `references/escalation-to-human-patterns.md` (context handoff section). + +--- + +## The bot-with-stale-knowledge + +The pattern. Knowledge base not updated; bot answers reflect outdated reality. + +The signal. Bot answers contradict current product; users notice; sales hears about wrong information. + +The cost. Trust damage. Each wrong answer is a moment the brand lost credibility. + +The cure. Knowledge-base maintenance discipline. Quarterly review at minimum. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## The bot-with-no-citation + +The pattern. Bot generates answers without citing sources. Users cannot verify. + +The signal. Hallucination goes undetected because there is no verification path; users with deeper questions abandon because they cannot follow up. + +The cost. Trust does not compound. Each answer is taken on faith; some are wrong. + +The cure. Citation discipline. Bot cites sources; users can verify. Detail in `references/knowledge-base-grounding-patterns.md` (citation discipline section). + +--- + +## The bot-with-inconsistent-voice + +The pattern. Different intents speak in different voices. Bot voice does not match brand voice elsewhere. + +The signal. Users report the bot feels disjointed; brand voice is fragmented. + +The cost. Brand consistency suffers. The bot is a brand surface that is undermining the brand. + +The cure. Brand voice document including bot examples. Test conversations across intents. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The bot-with-no-analytics + +The pattern. Bot launched without per-intent tracking. Quality is invisible. + +The signal. Cannot diagnose issues; cannot track decay; remediation is guesswork. + +The cost. Quality decays unnoticed. Maintenance happens only when customers complain (too late). + +The cure. Instrument before launch. Per-intent recognition, resolution, fallback, escalation rates. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## The bot-that-pretends-to-be-human + +The pattern. Bot does not disclose it is a bot; users think they are talking to a human. + +The signal. Users feel deceived when they realize; complaints about hidden automation; trust collapse. + +The cost. Trust damage that can be hard to recover. Brand earns "deceptive" descriptors. + +The cure. Disclose that the user is talking to a bot. Modern AI chatbots can be disclosed openly without losing engagement; users often appreciate the honesty. + +--- + +## The bot-with-mobile-broken-UI + +The pattern. Bot works on desktop; UI breaks on mobile. Conversation cramped; input field hidden; responses overflow. + +The signal. Mobile conversation completion is significantly lower than desktop. + +The cost. Mobile audience underserved. Mobile is often the majority of traffic. + +The cure. Mobile-first chatbot UI design. Test on actual devices. + +--- + +## The bot-without-availability-disclosure + +The pattern. Bot escalates to humans without communicating that humans may not be available. + +The signal. Users wait indefinitely for a human; abandonment after escalation; frustration. + +The cost. Escalation creates expectation that is not met. Worse than no escalation. + +The cure. Communicate availability honestly. "Our team is available [hours]." Or offer async alternatives. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active bot, looking specifically for these anti-patterns. + +Audit questions per bot. + +- Does the bot have explicit intents (anti-pattern check: bot-that-tries-to-handle-everything, hallucinating-bot)? +- Are responses grounded in source-of-truth (anti-pattern check: hallucinating-bot, bot-with-no-citation)? +- Does fallback have multiple layers including escalation (anti-pattern check: bot-with-no-escalation, bot-that-loops)? +- Does escalation pass context (anti-pattern check: bot-with-broken-handoff)? +- Is the knowledge base maintained (anti-pattern check: bot-with-stale-knowledge)? +- Is brand voice consistent across intents (anti-pattern check: bot-with-inconsistent-voice)? +- Are analytics in place (anti-pattern check: bot-with-no-analytics)? +- Does the bot disclose its nature and human availability (anti-pattern check: bot-that-pretends-to-be-human, bot-without-availability-disclosure)? + +The retire decision. Anti-pattern bots often warrant retirement or significant redesign. Patching anti-patterns rarely produces a good bot. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md new file mode 100644 index 0000000..501d77a --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/chatbot-decision-criteria.md @@ -0,0 +1,163 @@ +# Chatbot decision criteria + +When chatbots earn deployment and when they do not. The conditions that warrant the build, and the funnels where a chatbot adds friction without lift. + +A chatbot is a meaningful build. Intent architecture, knowledge-base grounding, fallback patterns, escalation logic, ongoing maintenance. The chatbot earns this investment only when specific conditions are present. + +--- + +## When chatbots earn deployment + +Five conditions that, when present, make a chatbot a strong investment. + +The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. Without recurring question patterns, the bot has nothing to handle reliably. + +The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. Off-hours visitors get something instead of nothing. + +The bot can ground its answers in real knowledge. Documentation, product specs, pricing pages, support articles. Without grounding, the bot's answers are at best generic and at worst fabricated. + +The team can maintain the bot. Intents drift; knowledge bases need updating; conversation patterns shift. Without maintenance commitment, the bot becomes stale liability. + +The success metric is defined. Resolution rate, fallback rate, escalation rate, user satisfaction, downstream conversion. Without the success metric defined, evaluation is impossible. + +When all five are present, the chatbot is a strong investment. When two or fewer are present, a different channel (human chat, structured FAQ, contact form) often serves better. + +--- + +## When chatbots do NOT earn deployment + +Funnels where the chatbot is the wrong tool. + +The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. A chatbot in these contexts may be perceived as an obstacle to the human conversation the audience wants. + +The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates (confident wrong answers) or stays so generic it adds no value (vague responses to specific questions). + +The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. The bot might be cheaper to operate but more expensive in lost conversions. + +The audience is small enough that direct human conversation is more efficient. Niche audiences with low conversation volume often work better with human-first channels; the chatbot's overhead is not justified. + +The team cannot maintain the bot. Stale bots produce wrong answers. Without quarterly maintenance commitment, the bot becomes a liability over time. + +The conversation pattern is too varied to model. Some audiences ask wildly different questions; the intent architecture cannot meaningfully cover the conversation space; the bot mostly fallbacks anyway. + +The honest assessment matters more than the default. "Should we have a chatbot" is not the question. "Is the chatbot the right tool for this audience and conversation pattern" is. + +--- + +## The opportunity-cost frame + +A chatbot is significant work. Account for the cost honestly. + +The build cost. Intent architecture, knowledge-base preparation, RAG pipeline, fallback design, escalation logic, conversation UI, brand-voice tuning, mobile responsiveness, analytics instrumentation. A meaningful chatbot often takes 80-300 engineering hours plus design and content for the knowledge base. + +The maintenance cost. Knowledge base updates, intent refinement, hallucination detection, conversation analytics review. Quarterly maintenance often runs 8-20 hours per active bot. + +The escalation infrastructure cost. Human handoff requires staffing or routing infrastructure. The bot does not eliminate the need for humans; it changes when humans are involved. + +The opportunity cost. What else could the team have built? A better support documentation site, a self-serve help center, a different growth-tooling investment. The chatbot's success has to clear the bar of those alternatives. + +The decision frame. The chatbot earns investment when it produces more value than the alternatives, accounting for build plus maintenance plus escalation infrastructure. + +--- + +## The grounding precondition + +Without knowledge-base grounding, the chatbot is the wrong tool. + +The check. Does the team have or can the team build a knowledge base that covers the conversation patterns the bot will handle? + +If yes, the chatbot can be grounded. The bot's responses retrieve from the knowledge base; hallucination risk is contained. + +If no (the team's knowledge is in people's heads, not documented), the chatbot will hallucinate or stay generic. The bot is the wrong tool until the knowledge base exists. + +Building the knowledge base. Sometimes the right move is to build the knowledge base first (which itself is valuable as documentation) before deploying the bot. The knowledge base serves users directly even before the bot accesses it. + +--- + +## The decision worked example + +A B2B SaaS company considering a chatbot for the marketing site. + +Conditions check. + +- Recurring questions: yes. Visitors ask about pricing, integrations, security, and demo requests recurringly. +- Off-hours coverage gap: yes. The team handles US business hours; international visitors get nothing in their evening hours. +- Knowledge-base grounding possible: yes. Pricing, integrations, security details all documented; FAQ exists; product specs are detailed. +- Maintenance commitment: yes. Marketing operations has capacity for quarterly bot review. +- Success metric defined: yes. Resolution rate per intent, escalation rate, downstream conversion to demo within 14 days. + +Decision. Build the chatbot. The conditions warrant it. + +Intent architecture. 7 named intents: pricing, integrations, security, demo request, support escalation, integration troubleshooting, account access. + +Knowledge-base grounding. RAG pipeline pulling from docs, pricing page, security page, integration catalog. + +Fallback strategy. Clarification on first unclear; suggested intents on second unclear; escalation to human on third or sentiment-driven. + +Escalation handoff. Bot passes conversation history and recognized intent to the human; the human picks up where the bot left off. + +The decision was not "should we have a chatbot" but "given these conditions, this is the chatbot to build." + +--- + +## The decision worked example: when to choose differently + +The same company considering a chatbot for sales conversations. + +Conditions check. + +- Recurring questions: partially. Sales conversations vary widely; while some patterns recur, the conversation often needs nuance. +- Off-hours coverage: not relevant; sales conversations work async via demo bookings already. +- Knowledge-base grounding possible: yes for product info; less so for personalized recommendations. +- Maintenance commitment: yes. +- Success metric: hard to define. Sales conversion is the goal; the bot's contribution is hard to attribute. + +Decision. Do not build a sales-focused chatbot. The audience expects human sales conversation; the bot would add friction. Use the bot for marketing-site Q&A and demo qualification; route demo requests to human sales. + +The decision was "is this chatbot right for this conversation" and the answer was "for some conversations yes, for others no." The bot's scope was constrained accordingly. + +--- + +## The audience-fit precondition + +The chatbot's audience must be willing to interact with chatbots. + +Audiences that engage with chatbots well. + +- Self-service-oriented users who want quick answers without human contact. +- Off-hours visitors who would otherwise get nothing. +- Users with specific factual questions (pricing, hours, policies). + +Audiences that resist chatbots. + +- Users who explicitly want to talk to a human (often signaled in the conversation opening). +- Sales-focused enterprise buyers expecting white-glove human attention. +- Users in distress (frustration, urgency) who need empathy not automation. + +The discipline. The chatbot should serve the audiences who engage well and escalate the audiences who do not. Trying to serve everyone with the bot fails both groups. + +--- + +## When to retire a chatbot + +Chatbots can be wrong even after being right initially. + +Retire when: + +- Resolution rate has dropped below an acceptable threshold consistently. +- Escalation rate climbs as intents fail to keep pace with audience evolution. +- The knowledge base maintenance burden exceeds the bot's value. +- A redesigned support model (better docs, expanded human team, different tooling) makes the bot unnecessary. +- The team can no longer commit to maintenance. + +The retiring discipline is part of the program. Stale bots produce wrong answers; honest retirement protects the brand. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant chatbot deployment. The conditions that argue against. The opportunity-cost frame. The grounding precondition. The audience-fit precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific chatbot scope decisions for specific audiences. The team's capacity benchmarks. Specific tooling for chatbot platforms, RAG pipelines, and analytics. Specific success-metric baselines. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md b/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md new file mode 100644 index 0000000..35d1c67 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/common-chatbot-failures.md @@ -0,0 +1,187 @@ +# Common chatbot failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the bot is hallucinating" or "users complain the bot is unhelpful" or "we cannot tell what the bot is doing." + +--- + +## "Bot makes up answers about pricing." + +The diagnosis. Hallucinating-bot pattern. No grounding to pricing source-of-truth. + +The cure. Add knowledge-base grounding for pricing. The bot retrieves from the pricing page or pricing knowledge base; answers reflect the source. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## "Users say the bot is rigid and unhelpful." + +The diagnosis. Scripted-bot pattern. Intents do not cover real questions; bot fails when users phrase things unexpectedly. + +The cure. Move from rigid trees to LLM-powered intent recognition. Define more flexible intents. Add fallback that handles unexpected phrasings. Detail in `references/intent-architecture-patterns.md`. + +--- + +## "Sales is angry that the bot is qualifying leads wrong." + +The diagnosis. Intent recognition or routing logic broken. The bot is recognizing leads as one type when they should be another. + +The cure. Audit the qualification flow. Verify intent recognition with realistic test cases. Tighten routing logic. Add human review for edge cases. + +--- + +## "Support tickets increase after chatbot launch." + +The diagnosis. Bot is producing wrong answers that send users to support after the fact. Worse than no bot. + +The cure. Audit grounding and resolution. Identify the intents producing bad answers. Either improve grounding or escalate those intents to humans. Detail in `references/knowledge-base-grounding-patterns.md` and `references/escalation-to-human-patterns.md`. + +--- + +## "Users abandon mid-conversation." + +The diagnosis. Bot loops or fallback patterns are inadequate. Users get stuck without resolution path. + +The cure. Review fallback patterns. Limit clarification rounds. Add multi-layered fallback ending in human escalation. Detail in `references/fallback-pattern-design.md`. + +--- + +## "We cannot tell what the bot is actually doing." + +The diagnosis. Analytics missing. Without instrumentation, quality is invisible. + +The cure. Instrument per-intent recognition, resolution, fallback, and escalation rates before any further changes. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot was great at launch; quality has degraded." + +The diagnosis. Maintenance lapse. Knowledge base or intent set out of date. + +The cure. Quarterly maintenance review. Update knowledge base; refine intents; verify grounding. Set the maintenance trigger so updates happen alongside product changes. + +--- + +## "Bot escalates to humans for everything." + +The diagnosis. Escalation logic too permissive, or the bot's intent handling is so weak that everything ends up at humans. + +The cure. Audit which intents escalate most. If the bot can handle them with better grounding, fix that. If the bot truly cannot handle them, reconsider whether they should be in scope. + +--- + +## "Bot tries to handle everything itself." + +The diagnosis. Escalation logic too restrictive. Bot stays with conversations it should not. + +The cure. Add escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Users complain the bot does not know what they asked five minutes ago." + +The diagnosis. Conversation context not preserved across turns. Bot treats each message as standalone. + +The cure. Implement conversation state management. Bot remembers earlier turns within the same conversation; later responses build on that context. Detail in `references/branching-and-conditional-logic.md` (conversation state management section). + +--- + +## "Bot gives different answers to the same question." + +The diagnosis. Either grounding is inconsistent (different retrievals for similar queries), or the LLM generation has variability that produces different answers. + +The cure. Review grounding pipeline. Verify retrieval consistency. Tune generation parameters for consistency. Audit specific cases. + +--- + +## "We tried the bot in our pricing page; conversion went down." + +The diagnosis. Bot may be adding friction to a flow that worked. Some pages benefit from chatbots; some do not. + +The cure. A/B test bot presence vs absence on the affected pages. The data informs whether the bot is the right tool there. + +--- + +## "Bot ignores the user when sentiment is negative." + +The diagnosis. No sentiment-driven escalation. Bot continues handling conversations where the user is frustrated. + +The cure. Add sentiment-driven escalation. Recognize frustration signals; escalate to human. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Sales team finds qualification bot data unreliable." + +The diagnosis. Bot's qualification logic does not match sales-team criteria, or recognition is misclassifying leads. + +The cure. Align bot qualification with sales criteria. Audit recognition with sales feedback. Update intents and routing. + +--- + +## "We added a chatbot; our overall site conversion dropped." + +The diagnosis. Bot may be displacing higher-converting paths (direct CTAs, contact forms). Bot is the wrong tool for this audience or page. + +The cure. A/B test bot presence vs absence at the funnel level. If the bot reduces conversion, reconsider its placement or scope. + +--- + +## "Bot answers correctly but conversation never closes." + +The diagnosis. No clear conversation-end pattern. Bot keeps offering more help; user does not know when to stop. + +The cure. Add explicit conversation closing. "Anything else I can help with?" "If not, [next step option]." Detail in fallback patterns. + +--- + +## "We migrated platforms; the bot quality dropped." + +The diagnosis. Platform migration may have broken intent recognition, knowledge base integration, or escalation routing. + +The cure. Test the migrated bot end-to-end before declaring it ready. Critical paths first. Roll back if quality dropped significantly. + +--- + +## "Mobile conversations end with no resolution." + +The diagnosis. Mobile UI may be breaking; or the bot's responses may be too long for mobile screens. + +The cure. Mobile UI testing. Audit response lengths. Mobile-specific UI adjustments. + +--- + +## "We cannot tell which intents need work." + +The diagnosis. Analytics aggregated rather than per-intent. The intent-level signal is hidden. + +The cure. Per-intent analytics. Recognition rate, resolution rate, escalation rate, hallucination rate per intent. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot's voice does not sound like our brand." + +The diagnosis. Bot is using generic LLM voice; brand voice was not specifically tuned. + +The cure. Brand voice document including bot examples. Tune bot prompts and response patterns to match. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The pattern across failures + +Most chatbot failures fall into one of three patterns. + +Pattern 1: The bot does not have proper architecture. Hallucinating, scripted, no grounding, no fallback discipline. The fix is structural. + +Pattern 2: The bot does not match the audience or context. Bot in wrong context, wrong voice, wrong scope for audience. The fix is matching the bot to where it serves. + +Pattern 3: The bot decays. Knowledge base stale, intent set frozen, no maintenance. The fix is maintenance discipline. + +The metric pattern: chatbot failures often look fine on conversation count alone. The signal is in resolution rate per intent, hallucination rate, escalation quality, downstream conversion. Programs that track only conversation counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (architecture, audience-context match, decay). The principle that conversation count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md new file mode 100644 index 0000000..5775305 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/conversation-analytics-patterns.md @@ -0,0 +1,272 @@ +# Conversation analytics patterns + +Per-intent metrics. Diagnostic uses. The data that informs maintenance. + +Conversation analytics is the bot's diagnostic system. Without analytics, maintenance is guesswork; intent gaps go unnoticed; hallucination patterns persist; the bot's quality decays without anyone seeing the decay. + +--- + +## The instrumentation principle + +Track the bot's performance per intent, per fallback, per escalation. The data informs every maintenance decision. + +The minimum tracking. + +- Conversation start (a user opens the bot). +- Intent recognition (which intent the bot classified). +- Conversation outcome (resolved, fallback, escalation, abandoned). +- Per-turn data (each user message, each bot response). + +The derived metrics. + +- Intent recognition rate. +- Resolution rate per intent. +- Fallback rate. +- Escalation rate per intent. +- Abandonment rate. + +Without instrumentation, none of this data exists. Set up tracking before launch. + +--- + +## Intent recognition rate + +What percentage of conversations are correctly classified. + +The metric. Of conversations where the user expressed intent, what percentage did the bot recognize correctly? + +Measurement methods. + +- Sample auditing. Periodically sample conversations and verify intent classification manually. +- User feedback signals. Conversations where users complain or escalate often correlate with misrecognized intent. +- Conversation outcome correlation. Conversations resolved successfully often had correct intent recognition. + +Diagnostic uses. + +- Low recognition rate: intent set may not cover real conversations; recognition logic may be brittle. +- Specific intents misrecognized: those intents may be poorly defined or overlap with others. + +Target ranges. 80-90 percent recognition is achievable for well-designed chatbots. Below 70 percent suggests significant intent or recognition issues. + +--- + +## Resolution rate per intent + +What percentage of conversations starting with intent X resolve successfully. + +Resolution definition. The user got the answer they needed and the conversation ended successfully (no escalation, no abandonment, no follow-up indicating frustration). + +Measurement methods. + +- Conversation completion plus user signal. User explicitly says "thanks" or rates the conversation positively. +- No follow-up issues. User does not return with the same question or escalate later. +- Direct survey. Post-conversation survey asking if the user got what they needed. + +Diagnostic uses. + +- Low resolution per intent: the bot's grounding or response pattern for that intent is weak. +- Some intents have higher resolution than others: variation may signal intent design quality differences. + +Target ranges. 70-85 percent resolution per intent is reasonable. Lower for complex intents; higher for simple intents. + +--- + +## Fallback rate + +What percentage of conversations hit fallback at any point. + +The metric. Conversations where the bot's intent recognition failed or the bot's response did not address the user's need, requiring fallback. + +Diagnostic uses. + +- High fallback rate (above 25-30 percent): intent set may be missing common conversations. +- Specific fallback layers triggered disproportionately: that layer needs review. +- Fallback rate trending up: audience evolving away from current intent set. + +Per-layer breakdown. Track which fallback layers (clarification, suggested intents, resource handoff, human escalation) trigger most. Each tells a different story. + +--- + +## Escalation rate per intent + +What percentage of conversations within each intent escalate to humans. + +The metric. Of conversations classified as intent X, what percentage ended with human escalation? + +Diagnostic uses. + +- High escalation rate per intent: the intent may not be appropriate for bot handling; consider removing from bot scope. +- Low escalation rate per intent: bot may be over-handling; some conversations may benefit from earlier escalation. +- Specific intents with rising escalation: maintenance lapse or audience evolution. + +The 100-percent-escalation intent. An intent where the bot always escalates is not a bot intent; it should be a "tell me about [topic]; we will get back to you" intent or removed entirely. + +--- + +## Abandonment rate + +What percentage of conversations end without resolution or escalation (the user just leaves). + +The metric. Conversations where the user stops responding without indicating resolution. + +Diagnostic uses. + +- High abandonment: bot is failing to satisfy users; review fallback patterns and conversation flows. +- Abandonment concentrated at specific turn or intent: that point in the flow is breaking. +- Mid-conversation abandonment vs first-turn abandonment: different diagnostic implications. + +--- + +## User satisfaction + +When measurable, satisfaction is the highest-value metric. + +Measurement methods. + +- Post-conversation rating. "How was that conversation?" with 1-5 stars or thumbs up/down. +- Post-conversation survey. Brief survey after the conversation ends. +- Sentiment analysis. Programmatic analysis of conversation sentiment. + +Diagnostic uses. + +- Low satisfaction: bot is failing the user even when conversations technically complete. +- Satisfaction-resolution mismatch: bot resolves but users are unhappy; quality of resolution is poor. + +Limitations. + +- Many users do not respond to satisfaction surveys. +- Satisfaction can be biased (frustrated users more likely to respond than satisfied ones). +- Sentiment analysis can miss nuance. + +The metric is valuable but not the only signal. + +--- + +## Conversation length distribution + +How many turns the average conversation takes. + +The metric. Distribution of conversation turn count. + +Diagnostic uses. + +- Long average length: bot may be over-clarifying; conversations should resolve faster. +- Bimodal distribution (very short or very long): some conversations resolve quickly; others get stuck. +- Increasing trend: bot quality may be declining; users having to work harder. + +Target ranges. 2-5 turns for typical resolution. Longer for complex intents; shorter for simple ones. + +--- + +## Response time + +How quickly the bot responds. + +The metric. Time between user message and bot response. + +Diagnostic uses. + +- Slow response: user perceives the bot as sluggish; abandonment may climb. +- Variable response time: inconsistent experience; users unsure what to expect. + +Target ranges. Under 2 seconds for most responses. Longer responses (when retrieving or generating) should show typing indicators. + +--- + +## Hallucination tracking + +Specifically tracking when the bot generates wrong answers. + +Detection methods. + +- Sample auditing of bot responses against source-of-truth. +- User reports ("the bot said X; that is not right"). +- Citation verification (programmatic check that cited sources contain the cited content). + +Diagnostic uses. + +- Specific intents with hallucination rate: those intents need grounding review. +- Specific topics within intents: knowledge base may have gaps. +- Hallucination trend: if rate is rising, model or grounding may be drifting. + +The honesty discipline. Track hallucination explicitly. Teams that hide hallucination from themselves ship worse bots. + +--- + +## Conversation funnel + +Track conversations as a funnel from start to resolution. + +The funnel. + +- Conversation started. +- Intent recognized. +- First response delivered. +- User continued. +- Resolution achieved (or escalation, or abandonment). + +Diagnostic uses. Drop-off at each stage points to specific issues. + +- Drop-off after intent recognition: bot's first response is not engaging or is wrong. +- Drop-off mid-conversation: branching or follow-ups are not landing. +- Drop-off near resolution: closing or call-to-action is weak. + +--- + +## Per-segment analytics + +Different audience segments may experience the bot differently. + +Segments. + +- New visitors vs returning. +- Logged-in vs anonymous. +- Mobile vs desktop. +- Source of arrival (paid, organic, referral). + +Diagnostic uses. + +- Segments with worse outcomes signal segment-specific issues. +- Sometimes the right answer is segment-specific bot behavior. + +--- + +## Analytics review cadence + +How often to look at the data. + +Weekly review. For high-volume bots or recently launched bots. Catches regressions and informs rapid iteration. + +Monthly review. For stable bots. Tracks trends and surfaces gradual decay. + +Quarterly review. For all active bots as part of the broader bot audit. + +Triggered review. When intent set changes, when knowledge base updates, when team escalation patterns shift. Ad-hoc reviews catch specific issues. + +--- + +## Common analytics failures + +No instrumentation. Bot launched without per-intent tracking; quality is invisible. + +Vanity metrics. Tracking conversation count without tracking outcome quality. + +Aggregate-only tracking. Conversation rate tracked but not per-intent; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; intent renames or schema changes broke the tracking. + +Confounded data. Multiple changes deployed simultaneously; cannot attribute changes to any one update. + +No segment-level data. Aggregate hides segment-specific issues. + +No hallucination tracking. Bot wrongness goes unnoticed until customers complain. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation principle. Intent recognition rate. Resolution rate per intent. Fallback rate. Escalation rate per intent. Abandonment rate. User satisfaction. Conversation length distribution. Response time. Hallucination tracking. Conversation funnel. Per-segment analytics. Analytics review cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific bots. Specific tooling for analytics implementation. Specific target ranges for the team's audience. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md new file mode 100644 index 0000000..429ba8d --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/escalation-to-human-patterns.md @@ -0,0 +1,209 @@ +# Escalation to human patterns + +When, how, with what context. Escalation triggers and handoff quality. + +Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. Escalation done well preserves the conversation's momentum; escalation done poorly resets the user. + +--- + +## The escalation principle + +Escalation is part of the bot's job. A bot that knows when to step aside earns more trust than a bot that tries to handle everything. + +The win. The bot recognizes its scope is exceeded; escalates with the conversation context; the human picks up where the bot left off. + +The fail (no escalation). The bot tries to handle everything; produces wrong answers; the user has to start over with a human eventually. + +The fail (broken escalation). The bot escalates but the human starts from scratch; the user has to repeat everything. + +The discipline. Escalation triggers defined; context handoff clean. + +--- + +## Escalation triggers + +When the bot escalates. + +User-initiated. "Talk to a human." "I need to speak with someone." "Get me a person." + +The bot escalates immediately. Do not try to handle the request first; the user has been explicit. + +Out-of-scope intent. The bot recognizes the user's intent is outside its scope. + +The bot escalates with the intent context. "Looks like you have a [intent type] question; let me connect you with the team." + +Repeated fallback. After 2-3 unclear exchanges, the bot escalates rather than loop. + +The bot acknowledges: "I am having trouble understanding your question; let me get a human who can help." + +Sentiment-driven. The user's sentiment indicates frustration. + +The bot recognizes frustration signals (negative phrasing, repeated complaints, exclamation patterns) and escalates. + +High-stakes topic. Sensitive topics escalate by default. + +Account security, cancellations, complaints, signs of distress. The bot does not try to handle these; immediate escalation. + +Complexity-driven. The user's question requires deep customization or analysis the bot cannot provide. + +The bot acknowledges: "This needs a more detailed look; let me connect you with our team." + +--- + +## The context handoff + +When escalating, the bot passes context to the human. + +What to pass. + +- The conversation history (full transcript). +- The recognized intent (what the bot thought the user wanted). +- The user's situation (any captured attributes: company, role, source). +- The reason for escalation (user-initiated, out-of-scope, sentiment, etc.). +- Any pending follow-up actions. + +The handoff format. + +- Visible to the human in their tool of choice (CRM, support ticket system, chat panel). +- Structured so the human can scan it quickly. +- Accurate (the recognized intent matches what the user actually said). + +The handoff failure. The human picks up the conversation but does not see the context; they ask the user to repeat everything; the user feels the escalation was for nothing. + +The discipline. Test the handoff. The human should pick up the context smoothly. The user should feel the escalation moved them forward, not backward. + +--- + +## Escalation user experience + +What the user sees during escalation. + +The pattern. + +- Bot acknowledges the escalation: "Let me connect you with someone who can help." +- Bot provides expectation: "Someone from our team will be with you in [timeframe]." +- If the wait will be long, bot offers alternatives: "If you do not want to wait, you can [book a call / email us / submit a ticket]." +- Conversation transitions to human cleanly when the human joins. + +The escalation-as-transition principle. The user should feel the conversation continued, not started over. The transition from bot to human is part of the experience. + +--- + +## Escalation and human availability + +What happens when no human is available. + +During business hours. The bot escalates; a human picks up within the expected response time. + +Off-hours. The bot acknowledges: "Our team is available [hours]. I can take your information and have someone respond when they are back." + +During high-volume. The bot acknowledges the wait: "We are seeing high volume right now; expected wait is about [time]." + +The honest framing. The bot communicates availability honestly. Pretending humans are available when they are not creates frustrated users. + +Asynchronous escalation. When the user is willing, async escalation (email, ticket) is often better than waiting in chat. The bot can offer this option proactively. + +--- + +## Escalation routing + +Which human gets the conversation. + +Routing patterns. + +- Single team. All escalations go to one team (often support). Simple but may not match all conversation types. +- Intent-based routing. Different intents route to different teams (sales escalations to sales; support to support). +- Tier-based routing. Different user tiers route to different teams (enterprise to enterprise account managers; SMB to general support). +- Context-based routing. Routing combines intent, tier, and other attributes. + +Routing failures. + +- Wrong team gets the escalation; they have to re-route; user waits longer. +- Routing logic stale; teams have changed but the bot has not. +- Round-robin without consideration of expertise; users get inconsistent quality. + +Routing maintenance. Quarterly review of routing logic alongside team structure changes. + +--- + +## Escalation measurement + +Track escalation rate and quality. + +Metrics. + +- Escalation rate. What percentage of conversations escalate? +- Escalation rate per intent. Some intents may escalate more often than others. +- Time-to-human-pickup. How quickly does the human respond after escalation? +- Resolution after escalation. What percentage of escalated conversations resolve? +- User satisfaction post-escalation. When measurable. + +Diagnostic uses. + +- High escalation rate per intent: that intent may not be appropriate for bot handling. +- Long time-to-human: staffing or routing issues. +- Low resolution after escalation: handoff quality may be poor or the team may not have the resources. + +The data informs both bot maintenance and human team capacity planning. + +--- + +## Bot-to-human transition design + +The moment the human joins the conversation. + +Pattern A: Visible transition. The user sees a message: "Hi, I am [name] from the team. I see you were asking about [topic]; how can I help?" + +The transition is explicit; the user knows they are now with a human. + +Pattern B: Continuous transition. The conversation continues without explicit handoff; the bot's voice fades; the human's voice picks up. + +Less common; can confuse users about who they are talking to. + +Pattern C: Bot stays available. The bot remains in the conversation alongside the human; can be called on for specific information retrieval while the human leads. + +Useful for complex conversations; rare in simple chatbot deployments. + +Pattern A is the default. Explicit transitions reduce confusion. + +--- + +## Escalation back to bot + +Sometimes the conversation can return to the bot after a human handoff. + +When this works. The human resolves the immediate issue; the user has a follow-up question that is bot-handlable; the bot can pick back up. + +When this fails. The user expected human attention; returning to the bot feels like demotion. + +The discipline. Bot-after-human transitions need user consent. "Is there anything else? I can connect you with our chatbot for quick questions, or keep you with me." Let the user choose. + +--- + +## Common escalation failures + +No escalation logic. Bot tries to handle everything; produces wrong answers; users escalate to support after the fact (worse than escalating upfront). + +Escalation without context handoff. Human starts from scratch; user repeats everything. + +Escalation to unavailable humans. Bot creates expectation that is not met; user waits indefinitely or abandons. + +Wrong-team routing. Escalation goes to a team that cannot help; rerouting adds friction. + +Sensitive topics not escalated. Bot tries to handle account security, cancellations, complaints; makes things worse. + +Escalation triggers too restrictive. Bot rarely escalates; users get stuck. + +Escalation triggers too permissive. Bot escalates everything; the bot is not really doing its job. + +No escalation user experience. Transition to human is jarring; user is confused about whether they are still with the bot. + +--- + +## Methodology-level choices that stay in the public skill + +The escalation principle. Escalation triggers (6 patterns). Context handoff discipline. Escalation user experience. Escalation and human availability. Escalation routing. Escalation measurement. Bot-to-human transition design (3 patterns). Escalation back to bot. Common failures. + +## Implementation choices that stay internal + +Specific escalation routing for specific teams. Specific handoff formats and integration with CRM or support tools. Specific brand-voice transition copy. The team's staffing and SLA decisions. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md b/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md new file mode 100644 index 0000000..32163d1 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/fallback-pattern-design.md @@ -0,0 +1,257 @@ +# Fallback pattern design + +What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. + +Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." Done well, fallback earns trust through honesty; done poorly, fallback frustrates users into abandonment. + +--- + +## The honesty principle + +A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers given confidently. + +The win. A user asks about a topic outside the bot's scope. The bot says "I cannot help with that, but [here is the right resource or human contact]." The user gets routed to value; the brand earns trust. + +The fail (faked confidence). The bot generates an answer from training data because it has no scope discipline. The answer is wrong; the user finds out later; the brand earns "lying bot" reputation. + +The fail (rigid refusal). The bot says "I cannot help with that" and offers no alternative. The user has nowhere to go. + +The discipline. Honest about limits; helpful about alternatives. + +--- + +## Multi-layered fallback + +Multiple fallback patterns, sequenced. + +Layer 1: Clarifying question. "Can you tell me more about what you are looking for?" + +When to use: when the user's intent is unclear and clarification might resolve. + +When it fails: when the user has already been clear; clarification feels patronizing. + +The discipline: ask clarification once, not repeatedly. + +Layer 2: Suggested intents. "I can help with X, Y, or Z. Were you asking about one of those?" + +When to use: when clarification did not work, or when the user asked something the bot can almost handle. + +When it fails: when the suggestions do not match what the user wanted. + +The discipline: suggest the bot's actual capabilities, not generic options. + +Layer 3: Resource handoff. "I cannot answer that, but here is our [documentation page] that covers it." + +When to use: when the bot cannot help but a self-serve resource exists. + +When it fails: when the resource is not actually relevant. + +The discipline: route to genuinely relevant resources; do not deflect to generic help. + +Layer 4: Human escalation. "Let me connect you with a human who can help." + +When to use: when self-serve will not work or the user has expressed frustration. + +When it fails: when no human is available; the escalation creates an expectation that does not get met. + +The discipline: escalate to humans only when humans are available; otherwise communicate the wait. + +--- + +## Layer sequencing + +The order matters. + +Standard sequence. + +1. Recognize intent. If recognized, handle. +2. If not recognized, try clarification (Layer 1). +3. If clarification fails, suggest intents (Layer 2). +4. If suggestions fail, offer resources (Layer 3). +5. If resources do not match, escalate (Layer 4). + +Sequence variations. + +- High-stakes topics may skip to Layer 4 immediately. +- User-initiated escalation ("talk to a human") goes to Layer 4 immediately. +- Frustrated sentiment may trigger Layer 4 sooner. + +--- + +## Anti-pattern: fallback loop + +Multiple clarification attempts that go nowhere. + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again; loop. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. The bot's job is to resolve or hand off, not to keep asking the same question. + +--- + +## Anti-pattern: rigid refusal + +Bot says "I cannot help" and offers no path forward. + +The pattern. User asks something out of scope; bot says "I cannot help with that"; conversation ends. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer an alternative. Resource handoff or human escalation. The bot's "I cannot help" should be followed immediately by "but here is what might." + +--- + +## Fallback copy discipline + +What the fallback messages say. + +Helpful fallback copy. + +- "I am not sure I caught that. Are you asking about [option 1] or [option 2]?" +- "I can answer questions about pricing, integrations, or features. Was your question about one of those?" +- "I cannot answer that specifically. Our team can help; would you like me to connect you?" + +Unhelpful fallback copy. + +- "I do not understand." +- "Please rephrase." +- "Sorry, I cannot help with that." + +The voice discipline. Fallback copy should sound like the brand. Apologetic but not groveling; honest but not curt; helpful but not desperate. + +--- + +## Fallback for sensitive topics + +Some topics warrant immediate escalation regardless of bot capability. + +Sensitive triggers. + +- Account security ("my account was hacked," "I think I was charged wrong"). +- Cancellation ("I want to cancel my subscription"). +- Complaints ("I want to speak to a manager"). +- Crises (any indication of user distress). + +The pattern. The bot recognizes the sensitive topic and escalates immediately rather than attempting to handle. + +Why this matters. Sensitive topics need human empathy. A bot trying to handle them often makes things worse. Immediate escalation protects the user and the brand. + +--- + +## Fallback during human unavailability + +What happens when the user wants a human but no human is available. + +The honest options. + +- "Our team is available [hours]. Can I take a message they can respond to when they are back?" +- "We are not available right now. You can [submit a ticket / book a call / email us]." +- "I can help with [list of topics]; for [out-of-scope topic], please reach out to [channel] directly." + +The dishonest option. + +- Pretending a human is available when they are not. The user waits, gets frustrated, abandons. + +The discipline. Communicate availability honestly. Set the expectation upfront if humans cannot respond immediately. + +--- + +## Fallback measurement + +Track fallback rate as a key metric. + +The metric. What percentage of conversations hit fallback at any point? + +Diagnostic uses. + +- High fallback rate (above 25-30 percent): intents are missing or recognition is poor. +- Specific fallback layers triggered disproportionately: that layer needs design review. +- Fallback escalation rate (what percentage of fallbacks lead to human escalation): high rates may signal the bot is doing less than it should; low rates may signal users abandoning rather than escalating. + +The fallback-as-signal principle. Fallback is not failure; it is the bot honestly recognizing limits. The signal is in the fallback patterns and what they reveal about intent gaps. + +--- + +## Fallback maintenance + +Fallback decays. + +What decays. + +- Suggested intents that no longer reflect the bot's actual capabilities. +- Resource links that have moved or broken. +- Escalation routing that no longer matches the team structure. + +Maintenance cadence. Quarterly review of fallback messages, suggested intents, resource links, and escalation routing. + +The drift indicator. User feedback about unhelpful fallback responses; broken links in the fallback flow; escalations going to wrong teams. + +--- + +## Fallback and brand voice + +Fallback responses are an opportunity for brand voice. + +The principle. Fallback is when the bot is most likely to lose the user. Brand voice in fallback can recover the moment. + +Voice in fallback. + +- Acknowledge the limitation honestly. +- Maintain warmth (do not become cold or robotic when failing to help). +- Offer the path forward with the same voice as the rest of the conversation. + +The voice failure. Fallback messages that sound generic; bot loses voice exactly when voice matters most. + +--- + +## Fallback testing + +Test the fallback flow as carefully as the success flow. + +Test cases. + +- User asks something clearly out of scope. +- User asks something on the edge of scope. +- User asks something within scope but phrased unusually. +- User explicitly asks for a human. +- User shows frustration in their messages. +- User asks during off-hours. + +The testing discipline. Each fallback layer should be tested with realistic triggers. + +--- + +## Common fallback failures + +No fallback patterns. Bot has no rehearsed responses for unknown intents; generates whatever the LLM produces. + +Single-layer fallback. Only "I do not understand" without alternatives. + +Fallback loops. Bot keeps asking clarification; user gets stuck. + +Rigid refusal. Bot says "I cannot help" without offering paths. + +Generic fallback copy. Fallback messages do not match brand voice. + +Stale resource links. Resource handoff points to broken URLs. + +Wrong escalation routing. Bot escalates to teams that are not appropriate. + +Hidden human availability. Bot does not communicate when humans are or are not available. + +Sensitive topics not escalated. Bot tries to handle topics that need human empathy. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Multi-layered fallback (4 layers with when to use). Layer sequencing. Anti-patterns (fallback loop, rigid refusal). Fallback copy discipline. Fallback for sensitive topics. Fallback during human unavailability. Fallback measurement. Fallback maintenance. Fallback and brand voice. Fallback testing. Common failures. + +## Implementation choices that stay internal + +Specific fallback messages for specific bots. Specific suggested intents and resource links. Specific escalation routing logic. The team's brand-voice fallback templates. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md new file mode 100644 index 0000000..2733529 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/intent-architecture-patterns.md @@ -0,0 +1,238 @@ +# Intent architecture patterns + +Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. + +The intent architecture is the bot's scope definition. Bad architecture produces bots that try to handle everything (and hallucinate) or bots that handle so little they fail audience expectations. Good architecture defines explicit scope and routes the rest to fallback. + +--- + +## The named-intent principle + +The bot has a defined set of intents it can handle. Each intent has a name, a scope, and a conversation pattern. + +The win. A user asks "what does the Pro plan include?" The bot recognizes this as the "pricing question" intent. The conversation pattern for that intent retrieves from the pricing knowledge base, generates a response, and offers follow-up. + +The fail (no named intents). The bot tries to handle every question with the same generic flow. Some questions get good answers; some get hallucinated answers; the bot cannot reason about its own scope. + +The discipline. Define the intents explicitly. The bot's behavior at each intent is intentional; behavior outside the intents is fallback. + +--- + +## Common intent patterns + +Patterns that recur across marketing-site and support chatbots. + +Pricing question. "How much does the Pro plan cost?" "What is included in the Enterprise tier?" "Do you offer discounts for nonprofits?" + +Conversation pattern: retrieve from pricing knowledge base, present the relevant tier or comparison, offer follow-up (talk to sales, see comparison, view full pricing page). + +Feature comparison. "What is the difference between A and B?" "Does feature X include Y?" + +Conversation pattern: retrieve from feature documentation, present comparison or specific feature details, offer follow-up. + +Integration question. "Do you integrate with Salesforce?" "How does the API work?" + +Conversation pattern: retrieve from integration catalog or API docs, present specific integration or API details, offer follow-up. + +Support escalation. "I need help with my account." "Something is broken." + +Conversation pattern: capture the issue context, escalate to human support with the captured context. + +Demo request. "Can I see a demo?" "I want to talk to sales." + +Conversation pattern: qualify the request (capture company size, use case, timeline), route to sales with the qualified context. + +Account access. "I forgot my password." "How do I access my account?" + +Conversation pattern: route to account-recovery flow or self-serve help. + +General question. "Tell me more about [topic]." "What can you help with?" + +Conversation pattern: present overview of bot capabilities; ask what specifically the user wants. + +--- + +## Intent hierarchy + +Top-level categories with sub-intents. + +The pattern. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question," "annual vs monthly." + +Strengths. + +- Hierarchy mirrors how audiences think. +- Each sub-intent can have specific knowledge-base grounding and conversation pattern. +- Easier to maintain than flat intent set. + +Weaknesses. + +- More complex to build. +- Risk of over-decomposition (sub-intents that nobody triggers). + +When to use. When the bot's scope is broad enough that a flat intent set becomes unwieldy. Most production chatbots benefit from hierarchy. + +--- + +## Intent boundaries + +Each intent has clear scope. Out-of-scope topics route to fallback. + +The principle. The intent definition specifies what the intent covers and what it does not. + +Example: "Pricing question" intent. + +In scope: tier prices, plan inclusions, discount inquiries, billing-cycle questions. + +Out of scope: sales-specific negotiations (escalate to sales), custom pricing requests (escalate to sales), historical pricing (out-of-scope, fallback). + +The boundary discipline. Without clear boundaries, the bot tries to handle topics it should not. Boundaries are part of the intent definition. + +--- + +## Intent coverage + +The bot's intents should cover 70-90 percent of expected conversations. + +The principle. Trying to cover 100 percent often produces bloated intent sets the bot cannot handle reliably. Aiming for 70-90 percent leaves room for honest fallback on the remaining edge cases. + +Coverage measurement. + +- After launch, sample conversations and classify them by intent. +- The percentage classified into named intents is coverage. +- The percentage falling to fallback is the gap. + +Coverage targets by use case. + +- Marketing-site Q&A: 80-90 percent coverage achievable. +- Support: 60-80 percent coverage typical; support questions are more varied. +- Sales qualification: 70-85 percent coverage; depending on audience. + +The over-coverage trap. Pursuing 100 percent coverage often means adding intents that fire rarely. The maintenance overhead is significant; the value is low. Honest fallback for rare cases is often better than rarely-triggered intents. + +--- + +## Intent design discipline + +Designing each intent. + +Step 1: Name the intent. Specific name that reflects the conversation pattern. + +Step 2: Scope the intent. What topics in, what topics out. + +Step 3: Identify the knowledge base. What knowledge sources the intent grounds in. + +Step 4: Design the conversation pattern. Opening response, possible follow-ups, success state, escalation conditions. + +Step 5: Define the success criterion. What does success look like for this intent? User got the answer? User clicked through to a relevant page? User completed a follow-up action? + +Step 6: Define escalation triggers. When does this intent escalate to a human? + +The discipline. Each intent is designed deliberately. Generic conversation patterns produce generic results. + +--- + +## Intent recognition + +How the bot determines which intent the user is in. + +LLM-based intent recognition. The LLM classifies the user's message into one of the named intents. Common in modern chatbots. + +Rule-based intent recognition. Keywords or patterns trigger intent assignment. Older approach; brittle but predictable. + +Hybrid. LLM as primary; rules for high-confidence overrides. Common middle ground. + +The recognition challenge. Users phrase the same intent in many ways. "How much?" "What does it cost?" "Is there a free tier?" all map to "pricing question." The intent recognition has to handle the variety. + +Recognition failure modes. + +- Misclassification (intent A treated as intent B). +- Over-classification (too many intents recognized; conversation gets confusing). +- Under-classification (intents go unrecognized; conversations fall to fallback). + +The discipline. Test intent recognition with realistic user messages. Tune until the classification matches user intent reliably. + +--- + +## Intent maintenance + +Intents drift. Audiences shift; products evolve; conversation patterns change. + +Maintenance signals. + +- Specific intents see declining resolution rates. +- New conversation patterns emerge that no intent covers. +- Sub-intents become more or less common over time. + +Maintenance cadence. Quarterly review of intent performance. Add new intents when new patterns emerge consistently; retire intents that fire rarely. + +The intent-maintenance audit. + +- For each intent: trigger rate, resolution rate, escalation rate. +- Identify intents that are over-triggering (capture too much) or under-triggering (rarely fire). +- Identify gaps (conversations that should have an intent but do not). + +--- + +## Intent and brand voice + +Each intent's conversation pattern should sound like the brand. + +The principle. The bot's voice in each intent matches the brand voice. Consistent across intents; consistent with the brand's other surfaces. + +Brand-voice failures. + +- Different intents speaking in different voices. +- Bot voice that does not match the brand's other surfaces. +- Generic LLM voice (no brand personality). + +The cure. Voice guidance specific to the bot. Brand voice document that includes bot-specific examples. Test conversations to verify voice consistency. + +--- + +## Intent-architecture worked example + +A B2B SaaS chatbot for a project management tool. + +Top-level intents. + +1. Pricing question (sub-intents: tier comparison, discount inquiry, billing question, annual vs monthly) +2. Feature inquiry (sub-intents: specific feature, comparison to competitor, roadmap question) +3. Integration question (sub-intents: specific integration, API question, custom integration) +4. Demo request (sub-intents: standard demo, enterprise demo, technical deep-dive) +5. Support escalation (sub-intents: bug report, account issue, billing problem, general help) +6. Account access (sub-intents: password reset, account login, organization-level access) +7. General overview (sub-intent: introductory tour) + +Coverage estimate. 80-85 percent of expected conversations. + +Fallback for the remaining 15-20 percent. Multi-layered fallback (clarification, suggested intents, resource handoff, human escalation). + +The architecture is explicit. Each intent has scope, knowledge-base grounding, conversation pattern, and escalation triggers. + +--- + +## Common intent failures + +Too few intents. Bot tries to handle everything with generic flow; hallucinates or stays generic. + +Too many intents. Intents that rarely fire; maintenance overhead with no value. + +Overlapping intents. Two intents claiming the same conversations; recognition becomes ambiguous. + +Unclear intent boundaries. Bot handles topics out of scope; quality drops. + +Intent recognition unreliable. Misclassification rate high; users get wrong responses. + +No intent maintenance. Intent set frozen at launch; audiences evolve away from it. + +Brand voice inconsistent. Each intent speaks differently; bot feels disjointed. + +--- + +## Methodology-level choices that stay in the public skill + +The named-intent principle. Common intent patterns. Intent hierarchy. Intent boundaries. Intent coverage. Intent design discipline. Intent recognition approaches. Intent maintenance. Intent and brand voice. Worked example. Common failures. + +## Implementation choices that stay internal + +Specific intent sets for specific bots. Specific conversation patterns and copy. Specific recognition implementations. Specific knowledge-base mappings per intent. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md b/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md new file mode 100644 index 0000000..4ba9fb1 --- /dev/null +++ b/dist/pi/.agents/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md @@ -0,0 +1,263 @@ +# Knowledge-base grounding patterns + +Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. The bot's responses must come from real knowledge, not made-up confidence. + +Without grounding, the bot hallucinates. With grounding, the bot retrieves and presents. The difference is the gap between hallucinating-bot and structured-guided-conversation. + +--- + +## The grounding principle + +The bot's response generation should reference a structured knowledge base. The bot does not invent answers; it retrieves and presents. + +The win. A user asks "what is included in the Pro plan?" The bot retrieves the current pricing page, extracts the Pro plan inclusions, and presents them. The answer matches the source-of-truth. + +The fail (hallucinating). A user asks the same question. The bot has no grounding; the LLM generates a response from training data or pattern-matching. The response sounds confident but may be wrong (outdated, fabricated, partially correct). + +The discipline. Every response that could be wrong if invented must be grounded. + +--- + +## Pattern A: Retrieval-augmented generation (RAG) + +The bot searches a knowledge base for relevant content before generating a response. + +How it works. + +- The user's message is converted to a query. +- The query searches the knowledge base (often via vector embedding similarity). +- Relevant content chunks are retrieved. +- The LLM generates a response grounded in the retrieved content. + +Strengths. + +- Responses reflect current knowledge base content. +- Bot answers questions about specific topics it has been trained on. +- Easier to update than retraining a model; updating the knowledge base updates the bot. + +Weaknesses. + +- Retrieval quality depends on knowledge-base structure and embedding quality. +- Bot may still hallucinate if retrieval returns nothing or if generation strays from retrieved content. +- Latency increases (retrieval + generation). + +When to use. Default pattern for grounded chatbots. Most production bots use some form of RAG. + +--- + +## Pattern B: Source-of-truth design + +Defining the knowledge base as the canonical source. + +The principle. The knowledge base is the canonical source for the bot's responses. When the source-of-truth changes, the bot's answers change. + +Source-of-truth examples. + +- Pricing page = source for pricing answers. +- Documentation = source for feature and integration answers. +- Support knowledge base = source for support answers. +- Security and compliance docs = source for security answers. + +Source-of-truth discipline. + +- Each topic has a single source-of-truth. +- The bot retrieves from that source. +- When the source updates, the bot's answers update automatically (depending on the RAG pipeline). + +The fragmented-source failure. Multiple sources for the same topic produce inconsistent answers. The bot might cite one source; the user might rely on another. Confusion. + +The cure. Single source-of-truth per topic. If multiple documents cover the same topic, designate one as canonical and reference the others. + +--- + +## Pattern C: Citation discipline + +The bot can cite the source of its answer. + +The principle. Audiences benefit from knowing where the answer came from. Citation builds trust and lets the user verify. + +Citation patterns. + +- Inline citation. "Based on our pricing page, the Pro plan is $X per user per month." +- Source link. "You can see the full plan comparison [here]." +- Source attribution at end. "Source: [document name or link]" + +Why citation matters. + +- Trust-building. Users can verify the answer. +- Hallucination protection. If the bot cannot cite, the answer may be fabricated. +- User self-service. Users with deeper questions can follow the link. + +Citation failures. + +- Bot generates an answer without citation; the user cannot verify. +- Bot cites a source that does not actually contain the answer (citation hallucination). +- Bot cites a moved or deleted source; the link breaks. + +The discipline. Citations must point to real sources that contain the cited content. + +--- + +## Pattern D: Boundary disclosure + +The bot tells the user when it is operating outside its grounding. + +The principle. When the bot's response is not grounded (the question is outside the knowledge base), the bot says so explicitly. + +Disclosure patterns. + +- "I do not have information on that specific topic; would you like me to connect you with our team?" +- "Our pricing details are on the [pricing page]; the specific scenario you are asking about may need a custom quote from sales." +- "I can answer questions about our integrations; for product roadmap, you may want to contact our team." + +The disclosure-as-honesty principle. A bot that admits limitations earns more trust than a bot that fakes confidence on out-of-scope questions. + +--- + +## Knowledge-base structure + +How the knowledge base is organized affects retrieval quality. + +Chunking. Knowledge base content is broken into chunks for retrieval. Chunk size affects retrieval precision and context. + +- Too small chunks. Retrieval returns isolated facts without context. The bot may miss surrounding nuance. +- Too large chunks. Retrieval returns too much; relevant content is buried; generation may stray. +- Right chunks. Topically coherent units (a pricing tier description, a feature explanation, a support article section). + +Metadata. Each chunk has metadata (source document, section, last-updated date, topic tags). Metadata supports filtering and citation. + +Embeddings. Chunks are embedded for similarity search. Embedding quality affects retrieval relevance. + +Index updates. When the source-of-truth changes, the index must update. Stale index produces stale answers. + +--- + +## Knowledge-base scope + +What goes into the knowledge base. + +In scope. + +- Pricing and plan details. +- Feature and capability documentation. +- Integration catalog and API documentation. +- Support FAQs. +- Security and compliance information. +- Company overview, team, contact information. + +Out of scope. + +- Confidential information (internal-only docs, sensitive data). +- Information that changes too rapidly to keep current (real-time inventory, live availability). +- Information that requires personalization the bot cannot do (account-specific data). + +Boundary discipline. Sensitive or personalization-required topics should not be in the bot's knowledge base. The bot should escalate or route to authenticated channels for those. + +--- + +## Knowledge-base maintenance + +The knowledge base decays. Maintenance is part of the bot's lifecycle. + +What decays. + +- Pricing changes that did not propagate to the knowledge base. +- Features added or removed without docs being updated. +- Integration partners changing names or capabilities. +- Support articles that became outdated. + +Maintenance cadence. + +- Monthly review of high-traffic content (pricing, features). +- Quarterly review of broader knowledge base. +- Triggered review when the product or pricing changes (the change includes a knowledge-base update task). + +Maintenance ownership. Someone owns the knowledge base. Without owner, it decays. + +Decay indicators. + +- Bot answers that contradict current product reality. +- User complaints about wrong information from the bot. +- Sales or support hearing audiences cite outdated bot information. + +--- + +## Hallucination detection + +Even with grounding, bots can hallucinate. Detection is part of the discipline. + +Detection methods. + +- Sample auditing. Periodically sample bot conversations and verify the responses against source-of-truth. +- User feedback signals. "This response was not helpful" feedback often correlates with hallucination. +- Citation verification. Programmatic checks that cited sources actually contain the cited content. +- Anomaly detection. Conversations where the bot's response diverges significantly from retrieved content. + +Remediation. + +- Hallucinated content reported promptly. +- Knowledge base or grounding logic updated to prevent recurrence. +- Specific intent or topic may need re-design. + +The honesty discipline. Acknowledge hallucination when it happens. The team that hides hallucination from itself ships worse bots over time. + +--- + +## Knowledge-base and brand voice + +The knowledge base content informs the bot's voice. + +The principle. Source documents written in brand voice produce bot responses in brand voice. Source documents written generically produce generic bot responses. + +The discipline. When preparing source documents for the knowledge base, write in the brand voice. The bot will reflect what it retrieves. + +Brand-voice editing. Some teams edit retrieved content for the bot's response. This adds brand voice but risks drifting from the source-of-truth. Trade-off worth considering. + +--- + +## Multi-source grounding + +When the bot needs to combine information from multiple sources. + +The pattern. The bot retrieves from multiple sources and synthesizes a response. + +Strengths. + +- Bot can answer questions that span topics. +- Richer responses possible. + +Weaknesses. + +- Synthesis can introduce hallucination. +- Citation becomes more complex (multiple sources). +- Quality control harder. + +The discipline. Use multi-source grounding sparingly. When used, ensure the synthesis is grounded in retrieved content, not generated from training data. + +--- + +## Common grounding failures + +No grounding. Bot generates from training data; hallucinations are routine. + +Stale grounding. Knowledge base not updated; bot answers reflect outdated reality. + +Fragmented grounding. Multiple sources for same topic; bot answers are inconsistent. + +Citation hallucination. Bot cites sources that do not contain the cited content. + +Generic content in knowledge base. Source documents are not in brand voice; bot responses are generic. + +Out-of-scope grounding. Bot retrieves from sources that should not be in scope (confidential, personalized). + +Boundary blur. Bot answers questions outside its grounding without disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The grounding principle. Patterns A through D (RAG, source-of-truth, citation, boundary disclosure). Knowledge-base structure. Knowledge-base scope. Knowledge-base maintenance. Hallucination detection. Knowledge-base and brand voice. Multi-source grounding. Common grounding failures. + +## Implementation choices that stay internal + +Specific knowledge bases for specific bots. Specific RAG pipelines and embedding choices. Specific chunking and indexing approaches. Specific tooling for hallucination detection. The team's maintenance calendars. These vary by team. diff --git a/dist/pi/.agents/skills/code-review-web/SKILL.md b/dist/pi/.agents/skills/code-review-web/SKILL.md new file mode 100644 index 0000000..0edae47 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/SKILL.md @@ -0,0 +1,213 @@ +--- +name: code-review-web +description: "Review web application code for bugs, security issues, performance problems, and stack-specific anti-patterns. Use this skill whenever the user wants to review code, debug a production issue, investigate a build failure, audit security, or check a PR before merging. Triggers on code review, review my code, debug, build error, broken, not working, why is X failing, check this code, security check, PR review, audit code, refactor. Also triggers when investigating 4xx or 5xx errors, deploy failures, environment variable issues, and CMS integration problems." +category: development +catalog_summary: "PR review, build error diagnosis, security and quality checks" +display_order: 1 +--- + +# Code Review for Web + +Review and debug web application code with a focus on the patterns that actually break production. Stack-agnostic principles in SKILL.md. Stack-specific patterns in references. + +--- + +## When to use + +- Reviewing a pull request before merging +- Debugging a production issue +- Investigating a build failure +- Auditing security or performance of existing code +- Investigating environment variable or configuration issues +- Triaging a "the site is broken" report + +## When NOT to use + +- Writing a new feature spec (use `pm-spec-writing`) +- Pre-launch QA against the running site (use `qa-testing`) +- Performance deep-dive on Core Web Vitals (use `performance-optimization`) +- Deep accessibility compliance review (use `accessibility-audit`) + +--- + +## Required inputs + +- The code, PR, error message, or symptom under review +- Access to logs (build logs, function logs, server logs) if debugging +- The stack (framework, hosting, database) - even at high level + +If just a symptom is provided ("the site is broken"), the workflow's first step is gathering enough context to investigate. + +--- + +## The framework: 5 review dimensions + +Every code review covers five dimensions. Pick the depth based on the situation. + +### 1. Correctness + +Does the code do what it claims to do? + +- Logic matches the intent stated in the spec or PR description +- Edge cases handled (empty states, error states, network failures) +- Off-by-one errors, null/undefined handling, async race conditions +- Tests exist for the change, or there's a reason they don't +- The change does not break existing functionality (regression risk) + +### 2. Security + +Does the code expose anything sensitive or open an attack surface? + +- Secrets handling. No secrets, API keys, or service-role credentials in client-side code or version control +- Auth checks. Every mutation endpoint validates the caller before acting +- Input validation. User input sanitized before use in queries, file paths, or HTML +- External requests. Outbound URLs validated; no SSRF on user-controlled inputs +- CSRF protection. State-changing requests require a token or same-origin policy +- Rate limiting. Public-facing mutation endpoints have rate limits +- HTTPS-only. No HTTP in production code paths +- Cookies. Session cookies have `Secure`, `HttpOnly`, `SameSite` attributes set +- Environment variables. Server-only secrets are not prefixed with anything that exposes them to the client bundle + +### 3. Performance + +Will this code scale and stay fast? + +- Database queries. No N+1 patterns. Joins or batch fetches preferred over loops with queries. +- Pagination. Large result sets paginated, never loaded entirely. +- Caching. Appropriate cache strategy for the data freshness needs. +- Bundle size. Client-side dependencies justified. Tree-shaking working. +- Image handling. Modern formats, lazy loading, explicit dimensions. +- Background work. Slow operations moved off the request path. +- Cold start sensitivity. Cold paths optimized if frequently triggered. + +### 4. Reliability + +What happens when this fails? + +- Error handling. Caught and handled, not swallowed. Errors logged with context. +- Retries. Network calls have retry logic for transient failures. +- Timeouts. External calls have explicit timeouts (no infinite waits). +- Graceful degradation. Failure of non-critical paths does not crash the page. +- Idempotency. Mutations that might be retried are safe to retry. +- Logging. Enough context in logs to diagnose without reproducing. + +### 5. Maintainability + +Will the next person (or future you) understand this in six months? + +- Naming. Functions and variables named for what they do, not how. +- Comments. Explain why, not what. The code says what. +- Complexity. Functions do one thing. If a function takes 200 lines, it's doing too much. +- Duplication. Same logic in multiple places gets extracted. +- Dependencies. New dependencies justified. Each one is a maintenance burden. +- Magic values. No literal `60000` in code. Use named constants. + +--- + +## Common bug patterns (stack-agnostic) + +Patterns that recur across stacks and are worth checking on every review. + +### Build and deploy + +- Build-time data fetches that timeout. Routes that query a database during static generation can fail at scale. Mark them as runtime-rendered if the data must be fresh. +- Environment variables not propagating. A var that works locally but breaks in production usually means it was not added to the production environment. +- Mismatched env between preview and production. Deploys that work in preview but break on the production domain often have stack-specific URLs hardcoded. + +### URL and domain issues + +- Canonical pointing at staging or preview URL. Caused by client-exposed environment variables that pick up the wrong domain. Canonical domain should come from a server-only environment variable. +- API URL pointing at the main domain that loops back. After a DNS cutover, the main domain may now serve a different application. APIs should live on dedicated subdomains. +- HTTPS upgrade issues. Mixed content (HTTP resources loaded into HTTPS pages) breaks browsers' security model. + +### Cache invalidation + +- Stale content after deploy. Either the cache was not invalidated, or the invalidation requires a manual trigger that did not run. +- CDN serving old asset under same filename. Always use a new filename or cache-bust query string when replacing assets. +- Cache headers too aggressive. Long max-age on resources that change frequently leads to users seeing stale content for hours or days. + +### Database and data + +- N+1 queries. Loop with a query inside the loop. Replace with batch fetch or join. +- Missing limits on table scans. Forgetting `LIMIT` on queries that hit large tables. +- Connection pool exhaustion. Too many concurrent connections, often from build-time fetches in parallel routes. +- Schema migration without backfill. Adding a NOT NULL column without populating it for existing rows. + +### Image handling + +- Image not loading after upload. CDN cached the previous filename. Use new filenames for replacements. +- Layout shift from images. Missing width/height attributes. Always specify both. +- Slow LCP from large images. Hero images not optimized for size or format. + +### External integrations + +- Bot mitigation blocking server-to-server calls. CDN or firewall is challenging legitimate automated traffic. Whitelist server IPs or disable challenges for API endpoints. +- API rate limit triggered in production. Worked locally where traffic was tiny. Add backoff and rate limiting awareness. + +### Security + +- Unprotected revalidation or admin endpoints. Always require a secret token. +- PII in URLs. Visible in server logs, browser history, referrer headers. +- Secrets exposed in client bundle. Anything that gets sent to the browser is public. + +--- + +## Workflow + +1. Gather context. What stack? What's broken or under review? Logs available? +2. Pick the depth. Quick scan for a small PR. Full review for a major change. Deep dive for a production incident. +3. Run through the 5 dimensions. Note issues by severity (blocker, important, minor). +4. Check stack-specific patterns. Reference the appropriate stack guide. +5. For incidents: identify the smallest hypothesis-driven fix. Reproduce locally if possible. +6. Write the review. Use the template in [`references/review-template.md`](references/review-template.md) for formal reviews. + +--- + +## Failure patterns + +- "Looks good to me" on a 500-line PR. If the review takes 5 minutes on a large PR, the review didn't happen. +- Reviewing without running the code. Some bugs only surface at runtime. Pull the branch and run it. +- Over-indexing on style. Bikeshedding on formatting while missing logic bugs. +- Skipping security review on "internal" features. Internal becomes external faster than expected. +- Treating warnings as decoration. Build warnings often become production errors after a dependency update. +- Debugging without reading the full error message. First line of the stack trace is often not the actual cause. Read all of it. + +--- + +## Debugging workflow + +When a production issue is reported: + +1. Read the full error message. Including the stack trace. +2. Check hosting build and function logs. The exact failing line is usually here. +3. Identify the last working version. `git log --oneline` and check recent commits. +4. Reproduce locally. Confirms it's a code issue and not an environment issue. +5. Check environment variables. Especially after deploys or DNS changes. +6. Check cache state. Force a cache invalidation before concluding it's a code bug. +7. Make the minimal fix. Big refactors during incidents create more incidents. +8. Verify in production. Check the actual fix worked, not just that the deploy succeeded. +9. Document. What was the root cause? What would have prevented it? File the learnings. + +--- + +## Output format + +For PR reviews: comments inline on the PR, plus a summary if needed. + +For formal code reviews: a markdown document at `code-review-[date].md` with: +1. Scope (what was reviewed) +2. Summary (overall assessment) +3. Critical issues (blockers) +4. Important issues +5. Minor issues +6. Suggestions for follow-up + +For incidents: a postmortem document. See `after-action-report` for that format. + +--- + +## Reference files + +- [`references/review-template.md`](references/review-template.md) - Markdown template for formal code reviews. +- [`references/nextjs-patterns.md`](references/nextjs-patterns.md) - Stack-specific patterns for Next.js (App Router, ISR, Server Components, common bugs). +- [`references/wordpress-headless-patterns.md`](references/wordpress-headless-patterns.md) - Stack-specific patterns for headless WordPress integrations. diff --git a/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md b/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md new file mode 100644 index 0000000..0989e7c --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/nextjs-patterns.md @@ -0,0 +1,360 @@ +# Next.js Patterns + +Stack-specific patterns and anti-patterns for Next.js projects. Covers App Router and Pages Router. Stack-agnostic principles live in [SKILL.md](../SKILL.md). + +--- + +## App Router specific + +### Server vs client components + +Default to server components. Reach for `"use client"` only when interactivity, browser APIs, or React state hooks are required. + +```typescript +// Server component (default) - runs on server, no hydration cost +// app/page.tsx +export default async function Page() { + const data = await fetchData(); + return <Article data={data} />; +} + +// Client component - hydrates in browser +// app/components/InteractiveButton.tsx +"use client"; +export default function InteractiveButton() { + const [count, setCount] = useState(0); + return <button onClick={() => setCount(c => c + 1)}>{count}</button>; +} +``` + +Anti-pattern: Marking parent components as `"use client"` when only a leaf component needs it. This pulls everything below into the client bundle. + +### ISR and revalidation + +Pick the right rendering strategy per route: + +```typescript +// Static (default) - rendered at build, served from CDN +export default async function Page() { ... } + +// ISR (revalidate periodically) - rendered at build, regenerated on schedule +export const revalidate = 3600; // 1 hour + +// Dynamic (rendered on every request) - never cached +export const dynamic = "force-dynamic"; + +// Common combination: dynamic with cache hint for downstream +export const dynamic = "force-dynamic"; +export const revalidate = 3600; +``` + +### Build timeout failures + +Common error: +``` +Failed to build /route after 3 attempts because it took more than 60 seconds +``` + +Cause: A static route that queries a database or external API at build time, and the call exceeds the build timeout. + +Fix: Add `dynamic = "force-dynamic"` to defer rendering to request time: + +```typescript +export const dynamic = "force-dynamic"; +export const revalidate = 3600; + +export async function GET() { + try { + const data = await dbQuery(); + return generateResponse(data); + } catch (e) { + console.error("Route error:", e); + return new Response("", { status: 200 }); // empty but valid + } +} +``` + +### TypeScript errors in scripts directory + +If you have a `scripts/` folder with one-off scripts, exclude it from the build: + +```json +// tsconfig.json +{ + "exclude": ["node_modules", "scripts"] +} +``` + +### Canonical URL configuration + +The canonical domain must come from a server-only environment variable. Never expose with `NEXT_PUBLIC_` prefix. + +```typescript +// next.config.ts +const config = { + env: { + SITE_URL: process.env.SITE_URL ?? "https://yourdomain.com", + }, +}; +export default config; +``` + +```typescript +// Where the canonical is set +const url = process.env.SITE_URL; // server-only, never exposed to browser +``` + +Anti-pattern: Using `NEXT_PUBLIC_SITE_URL`. Vercel preview deploys will pick up the preview URL and pollute production canonicals. + +--- + +## Pages Router specific + +### getStaticProps timeouts + +Same fundamental issue as App Router build timeouts. Solution is `getServerSideProps` for routes that need fresh data: + +```typescript +// pages/dynamic-page.tsx +export async function getServerSideProps(context) { + const data = await dbQuery(); + return { props: { data } }; +} +``` + +Or ISR: + +```typescript +export async function getStaticProps() { + const data = await dbQuery(); + return { + props: { data }, + revalidate: 3600, + }; +} +``` + +--- + +## Common patterns across both routers + +### API routes / route handlers + +Authentication on mutations: + +```typescript +// app/api/protected/route.ts (App Router) +export async function POST(req: Request) { + const secret = req.headers.get("authorization"); + if (secret !== `Bearer ${process.env.API_SECRET}`) { + return new Response("Unauthorized", { status: 401 }); + } + // ... handle the request +} +``` + +Revalidation endpoint protection: + +```typescript +// app/api/revalidate/route.ts +import { revalidatePath } from "next/cache"; + +export async function POST(req: Request) { + const url = new URL(req.url); + const secret = url.searchParams.get("secret"); + + if (secret !== process.env.REVALIDATE_SECRET) { + return Response.json({ error: "Unauthorized" }, { status: 401 }); + } + + const path = url.searchParams.get("path") ?? "/"; + revalidatePath(path); + + return Response.json({ revalidated: true, path }); +} +``` + +### Image optimization + +Use the framework's built-in image component for proper optimization: + +```typescript +import Image from "next/image"; + +<Image + src="/photo.jpg" + alt="Descriptive alt text" + width={800} + height={600} + loading="lazy" // explicit even though lazy is default for below-fold +/> +``` + +For external image domains, configure `next.config.ts`: + +```typescript +const config = { + images: { + remotePatterns: [ + { protocol: "https", hostname: "cms.yourdomain.com" }, + ], + }, +}; +``` + +### Environment variables + +Three categories. Be explicit about which is which. + +``` +Server-only secrets (never prefix with NEXT_PUBLIC_): + DATABASE_URL + API_SECRET + STRIPE_SECRET_KEY + REVALIDATE_SECRET + SITE_URL (use server-only even for canonical, despite being a "public" value) + +Client-safe variables (NEXT_PUBLIC_ prefix exposes to browser): + NEXT_PUBLIC_GA_ID + NEXT_PUBLIC_DEFAULT_LANGUAGE + NEXT_PUBLIC_FEATURE_FLAGS + +Build-time only: + ANALYZE_BUNDLE + NODE_ENV (set automatically) +``` + +Red flags during review: +- Any secret with `NEXT_PUBLIC_` prefix +- Canonical or site URL set to a preview/staging URL in production +- Service role keys exposed to the browser + +--- + +## Common bugs and fixes + +### Page renders partially after deploy + +Symptom: Hero loads but content below is missing or stale. + +Cause: Stale ISR cache from before the deploy. + +Fix: Force revalidation: + +```bash +curl -X POST "https://yourdomain.com/api/revalidate?path=/&secret=$REVALIDATE_SECRET" +``` + +If the issue persists, check server logs for rendering errors during regeneration. + +### CMS API redirects to main domain after DNS cutover + +Symptom: API calls to the CMS return 302 redirects or 403 errors. + +Cause: API URL points at the main domain, which now serves the Next.js app instead of the CMS. + +Fix: Use a dedicated CMS subdomain: + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json # correct +WP_API_URL=https://yourdomain.com/wp-json # loops back to Next.js +``` + +### Images return 502 after domain change + +Cause: Image optimizer fetching from a domain that no longer hosts the source images. + +Fix: Update `images.remotePatterns` in `next.config.ts` to match the new image origin. Rewrite media URLs in data fetches to point at the correct origin. + +### Client component re-renders excessively + +Cause: Inline object or function as prop. New reference on every render triggers re-render in the child. + +Fix: Memoize: + +```typescript +// Before (creates new object each render) +<Child config={{ foo: "bar" }} /> + +// After +const config = useMemo(() => ({ foo: "bar" }), []); +<Child config={config} /> +``` + +--- + +## Performance patterns + +### Avoid request waterfalls + +```typescript +// Bad: sequential fetches +const user = await getUser(); +const posts = await getPostsByUser(user.id); +const comments = await getCommentsForPosts(posts.map(p => p.id)); + +// Good: parallel where possible +const user = await getUser(); +const [posts, settings] = await Promise.all([ + getPostsByUser(user.id), + getSettingsForUser(user.id), +]); +``` + +### Database query patterns + +```typescript +// Bad: N+1 +for (const post of posts) { + const author = await db.user.findUnique({ where: { id: post.authorId } }); +} + +// Good: batch fetch with relation +const posts = await db.post.findMany({ + include: { author: true }, +}); + +// Always limit large scans +const data = await db.post.findMany({ + where: { ... }, + take: 100, +}); +``` + +### Streaming with Suspense + +For App Router, stream slow content to improve perceived performance: + +```typescript +// app/page.tsx +import { Suspense } from "react"; +import FastContent from "./FastContent"; +import SlowContent from "./SlowContent"; + +export default function Page() { + return ( + <> + <FastContent /> + <Suspense fallback={<Loading />}> + <SlowContent /> + </Suspense> + </> + ); +} +``` + +--- + +## Code review checklist for Next.js + +- [ ] Server components default; `"use client"` only where needed +- [ ] ISR routes have appropriate `revalidate` value +- [ ] Database-querying routes have `force-dynamic` if they can timeout at build +- [ ] Canonical/site URL uses server-only env var +- [ ] No secrets in `NEXT_PUBLIC_` variables +- [ ] API routes have auth checks on mutations +- [ ] Revalidation endpoint protected with secret +- [ ] Images use the `Image` component, with explicit width/height +- [ ] External image domains in `images.remotePatterns` +- [ ] Scripts directory excluded from tsconfig if causing type errors +- [ ] Suspense boundaries for slow content where streaming helps diff --git a/dist/pi/.agents/skills/code-review-web/references/review-template.md b/dist/pi/.agents/skills/code-review-web/references/review-template.md new file mode 100644 index 0000000..35bcea4 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/review-template.md @@ -0,0 +1,141 @@ +# Code Review: [PR Title or Scope] + +Reviewer: [Name] +Date: [YYYY-MM-DD] +PR or commit: [Link or hash] +Author: [Name] +Scope: [Files reviewed, lines changed] + +--- + +## Summary + +[2 to 3 sentences. Overall assessment. Recommend merge, request changes, or block.] + +Recommendation: [Approve / Approve with comments / Request changes / Block] + +Critical issues: [N] +Important issues: [N] +Minor issues: [N] +Suggestions: [N] + +--- + +## Critical issues (blockers) + +[Issues that must be fixed before merge.] + +### 1. [Issue title] +- File: [path/to/file.ext] +- Line: [Line number or range] +- Issue: [What's wrong] +- Why critical: [Impact if shipped] +- Suggested fix: [Specific recommendation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Issues that should be addressed but might not block merge.] + +### 1. [Issue title] +- File: +- Line: +- Issue: +- Suggested fix: + +--- + +## Minor issues + +[Polish items, style consistency, naming.] + +- [file:line] [Description and suggestion] +- [file:line] [Description and suggestion] +- [file:line] [Description and suggestion] + +--- + +## Suggestions for follow-up + +[Things worth doing in a follow-up PR, not in this one.] + +- [Suggestion] +- [Suggestion] + +--- + +## Dimension scorecard + +\| Dimension \| Pass \| Issues \| +\|---\|---\|---\| +\| Correctness \| ☐ \| [Notes] \| +\| Security \| ☐ \| [Notes] \| +\| Performance \| ☐ \| [Notes] \| +\| Reliability \| ☐ \| [Notes] \| +\| Maintainability \| ☐ \| [Notes] \| + +--- + +## Specific checks + +### Correctness +- [ ] Logic matches PR description +- [ ] Edge cases handled (empty, null, error) +- [ ] No off-by-one or async race conditions +- [ ] Tests exist or are not needed (with reason) +- [ ] No regressions in existing functionality + +### Security +- [ ] No secrets in client-side code +- [ ] Auth checks on mutations +- [ ] Input validated before use +- [ ] No new SSRF surface +- [ ] Cookies have appropriate attributes +- [ ] Server-only env vars not exposed to client + +### Performance +- [ ] No N+1 queries +- [ ] Pagination on large result sets +- [ ] Cache strategy appropriate +- [ ] Bundle size impact reasonable +- [ ] Images handled correctly + +### Reliability +- [ ] Errors caught and handled +- [ ] Network calls have timeouts +- [ ] Graceful degradation for non-critical paths +- [ ] Mutations idempotent if retried +- [ ] Sufficient logging for diagnosis + +### Maintainability +- [ ] Naming clear +- [ ] Functions focused (one thing well) +- [ ] No unjustified duplication +- [ ] No magic values (use constants) +- [ ] Comments explain why, not what + +--- + +## Stack-specific checks (if applicable) + +[Reference the stack-specific guide for the project. Note any stack-specific patterns or anti-patterns worth flagging.] + +--- + +## Notes for the author + +[Encouraging or contextual notes. What was done well. What's a learning opportunity.] + +--- + +## Sign-off + +Approval status: [Approved / Approved with comments / Changes requested / Blocked] +Date: [YYYY-MM-DD] + +If changes were requested, link to the follow-up PR or commit when resolved: +- [Link or hash] diff --git a/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md b/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md new file mode 100644 index 0000000..cddd929 --- /dev/null +++ b/dist/pi/.agents/skills/code-review-web/references/wordpress-headless-patterns.md @@ -0,0 +1,265 @@ +# WordPress Headless Patterns + +Stack-specific patterns for WordPress as a headless CMS, integrated with a separate frontend (Next.js, Astro, Eleventy, custom, etc.). + +The principles in [SKILL.md](../SKILL.md) apply universally. This file covers the WordPress-specific patterns that recur in headless setups. + +--- + +## Architecture + +A headless WordPress setup typically looks like: + +``` +cms.yourdomain.com → WordPress backend (admin, REST API, media) +yourdomain.com → Frontend (renders content fetched from CMS API) +``` + +WordPress serves the data and admin. The frontend serves the user-facing site. The two are decoupled. + +This separation matters for several patterns below. + +--- + +## Always use a CMS subdomain + +Pattern: All API calls go to a dedicated subdomain. + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json +``` + +Anti-pattern: API calls to the main domain. + +``` +WP_API_URL=https://yourdomain.com/wp-json # this will break after DNS cutover +``` + +Why: When the main domain points to the frontend (post-DNS cutover), API calls to the main domain hit the frontend instead of WordPress. The frontend has no `/wp-json` route, so calls fail. + +The CMS subdomain remains a stable, dedicated endpoint regardless of where the main domain points. + +--- + +## Site URL configuration in WordPress + +After moving to a subdomain, WordPress needs to know its real URL. Otherwise the admin redirects to the main domain. + +In `wp-config.php`: + +```php +define("WP_HOME", "https://cms.yourdomain.com"); +define("WP_SITEURL", "https://cms.yourdomain.com"); +``` + +Symptom if missing: Logging into `cms.yourdomain.com/wp-admin` redirects to `yourdomain.com/wp-admin`, which hits the frontend (no admin), returning a 403 or 404. + +--- + +## Media URL handling + +WordPress generates media URLs based on the configured site URL. When fetched through the API, they will reference the CMS subdomain. The frontend needs to handle these correctly. + +### Pattern 1: Reference media at the CMS subdomain (simplest) + +The frontend renders images directly from the CMS subdomain: + +```html +<img src="https://cms.yourdomain.com/wp-content/uploads/photo.jpg" alt="..." /> +``` + +Pros: Simple. No URL rewriting. +Cons: Browser makes requests to a different origin. Need to allow that origin in image optimizer config. + +### Pattern 2: Rewrite media URLs to the frontend domain + +Strip the CMS prefix and serve media via the frontend's image optimizer: + +```typescript +// Convert CMS media URL to a pattern the frontend image optimizer accepts +function rewriteMediaUrl(url: string): string { + return url.replace("https://cms.yourdomain.com", ""); +} +``` + +Configure the frontend image optimizer to allow the CMS subdomain as a remote source. + +### Anti-pattern: Hardcoded media URLs in content + +If editors paste full URLs into the content (`<img src="https://cms.yourdomain.com/...">`), changing the CMS subdomain later breaks every reference. Use relative paths or template-rendered URLs instead. + +--- + +## Permalinks and post URLs + +WordPress posts have a `link` field in the API response that returns the WordPress-rendered URL (e.g., `https://cms.yourdomain.com/post-slug/`). This is wrong for the public-facing site. + +Anti-pattern: Using the `link` field directly. + +```typescript +// Wrong - shows the CMS URL +<a href={post.link}>{post.title}</a> +``` + +Pattern: Construct the public URL from the slug. + +```typescript +// Right - build the URL the frontend serves +<a href={`/blog/${post.slug}`}>{post.title}</a> +``` + +--- + +## Caching and revalidation + +The frontend caches API responses. When content changes in WordPress, the cache must be invalidated. + +### Pattern 1: Time-based revalidation + +Cache responses for a fixed period. Simple but content can be stale up to that period. + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { revalidate: 3600 }, // 1 hour +}); +``` + +### Pattern 2: On-demand revalidation via webhook + +WordPress fires a webhook on save. The webhook calls a frontend endpoint that invalidates the cache. + +WordPress side (mu-plugin or theme function): + +```php +add_action('save_post', function ($post_id) { + $post = get_post($post_id); + if ($post->post_status !== 'publish') return; + + wp_remote_post('https://yourdomain.com/api/revalidate', [ + 'body' => json_encode([ + 'secret' => REVALIDATE_SECRET, + 'path' => '/blog/' . $post->post_name, + ]), + 'headers' => ['Content-Type' => 'application/json'], + ]); +}); +``` + +Frontend side: an endpoint that invalidates the cache for the given path. + +### Pattern 3: Tag-based invalidation + +Tag fetches with semantic identifiers, then invalidate by tag when relevant content changes. + +```typescript +const posts = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { tags: ["posts"] }, +}); + +// Later, invalidate +revalidateTag("posts"); +``` + +--- + +## Authentication for the API + +For private content or write operations, the API requires authentication. + +### Application passwords (built into WordPress) + +WordPress supports application passwords for API authentication. Generate one in the admin under user profile. + +```typescript +const auth = btoa(`${username}:${appPassword}`); + +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + headers: { + Authorization: `Basic ${auth}`, + }, +}); +``` + +Anti-pattern: Hardcoding credentials in client-side code. Application passwords go in server-only environment variables. + +### JWT (via plugin) + +JWT plugins offer a more standard auth flow but add a plugin dependency. + +--- + +## Common bugs and fixes + +### "API returns 403 from server-side fetch" + +Cause 1: A bot mitigation service (Cloudflare's "Attack Challenge Mode" or similar) is challenging the server-to-server request. + +Fix: Disable bot mitigation challenges for the CMS API path, or whitelist the frontend's server IPs. + +Cause 2: The API requires authentication and the request is unauthenticated. + +Fix: Add an `Authorization` header with application password or JWT. + +### "Posts list is paginated and we're only getting 10" + +Cause: WordPress default per-page is 10. + +Fix: Use `per_page` parameter and handle pagination: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?per_page=100`); +const total = parseInt(res.headers.get('x-wp-total') ?? '0'); +const totalPages = parseInt(res.headers.get('x-wp-totalpages') ?? '0'); +``` + +For very large content sets, paginate explicitly rather than fetching all at once. + +### "Custom fields are missing from the API response" + +Cause: Advanced Custom Fields (ACF) or custom post meta is not exposed by default. + +Fix: Use the ACF to REST API plugin, or register custom fields with `register_rest_field`: + +```php +add_action('rest_api_init', function () { + register_rest_field('post', 'custom_field_name', [ + 'get_callback' => function ($post) { + return get_post_meta($post['id'], 'custom_field_name', true); + }, + ]); +}); +``` + +### "Featured image is missing from the API response" + +Cause: The API returns the image ID, not the full media object. + +Fix: Use `_embed=true` to inline media: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?_embed=true`); +// Now post._embedded["wp:featuredmedia"][0] has the full image data +``` + +### "Slug-only URLs return wrong content after rename" + +Cause: WordPress slug changes don't redirect the old slug. Frontend caches lock to the old slug. + +Fix: +1. WordPress: install a redirection plugin or maintain a redirects table +2. Frontend: handle 404s on slug routes by falling back to a search-by-title + +--- + +## Code review checklist for headless WordPress + +- [ ] All API calls use the CMS subdomain (no main domain references) +- [ ] WP_HOME and WP_SITEURL set in wp-config.php +- [ ] Media URLs handled correctly (either CMS-direct or rewritten) +- [ ] Post URLs constructed from slug, not the WordPress `link` field +- [ ] Cache invalidation strategy in place (time-based, webhook, or tag) +- [ ] Authentication credentials in server-only env vars +- [ ] API responses include needed embedded data (`_embed=true` where relevant) +- [ ] Pagination handled for large post lists +- [ ] Error handling for API failures (CMS down should not crash the frontend) +- [ ] Custom fields exposed via REST API where needed diff --git a/dist/pi/.agents/skills/comparison-tool-design/SKILL.md b/dist/pi/.agents/skills/comparison-tool-design/SKILL.md new file mode 100644 index 0000000..051888d --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/SKILL.md @@ -0,0 +1,261 @@ +--- +name: comparison-tool-design +description: "Designing side-by-side comparison tools (plan-compare, product-compare, alternative-compare) that help users decide rather than just listing features. Axis selection, default-comparison logic, recommendation discipline. Honest about feature-list-dump (every feature in a row, no decision support), hidden-recommendation (biased comparison pretending to be neutral), and honest-comparison-with-guidance (genuine comparison plus opinionated recommendation) patterns. Triggers on comparison tool, plan compare, product compare, alternative compare, vs page, decision support tool. Also triggers when conversion through comparison stages is poor, when users are abandoning at the comparison step, or when a comparison tool is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing comparison tools that help users decide. Distinguishes feature-list-dump (every feature in a row, no decision support) from hidden-recommendation (biased comparison pretending to be neutral) from honest-comparison-with-guidance (genuine comparison plus opinionated recommendation)" +display_order: 11 +--- + +# Comparison Tool Design + +A senior product marketing director's playbook for designing side-by-side comparison tools that help users decide rather than just listing features. Plan-compare, product-compare, alternative-compare. Axis selection, default-comparison logic, recommendation discipline. The discipline of building a comparison tool that earns the user's trust. + +Most comparison tools fail in one of two ways. They dump every feature into a giant grid (4 options × 40 features = 160 cells) and ask the user to weigh everything against everything. The user leaves without choosing. Or they pretend to be neutral comparisons but are actually sales pitches with biased defaults and weighted framing; the user catches the bias and trust collapses. + +The comparison tools that work do something different. Genuine like-for-like comparison plus an explicit opinionated recommendation. "For X audience, choose Y." The recommendation is visible, defended, and not the only path; users can override. The tool helps the user decide rather than asking them to decide alone. + +The voice is the senior product marketing director who has watched comparison tools double conversion when redesigned with honest recommendations and watched them collapse when feature grids grew without decision support. Practical, opinionated about which axes matter, willing to call out when the comparison is decoration. + +When to use this skill: scoping a comparison tool for the first time, auditing a feature-grid comparison that produces no conversion lift, designing recommendation logic that is honest about the recommendation, or deciding which axes earn placement in a comparison tool. + +--- + +## What this skill covers + +This skill spans side-by-side comparison tools. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number. This skill is comparing known options. +- `quiz-and-assessment-design` is quizzes that give a category. This skill is comparing options the user already knows about. +- `comparison-tool-design` (this skill) is axis selection, default-comparison logic, recommendation engine, filter-and-toggle UX. +- `landing-page-copy` is pricing-page copy; one specific application of comparison tools is the pricing page. +- `content-strategy` is upstream; what topics warrant comparison content. + +The audience: product marketers, growth marketers, content marketers running vs-pages and decision-support tooling, agencies running comparison work for clients. + +Out of scope: calculator design (covered by `calculator-design`); quiz design (covered by `quiz-and-assessment-design`); the engineering implementation; specific Webflow/Framer/CMS configurations (those stay implementation-side). + +--- + +## The comparison-tool decision: when comparison tools earn investment + +Before designing the tool, decide whether a comparison tool is the right answer. + +Comparison tools earn investment when: + +- The audience is at a decision moment between known options (vs unknown options where a quiz or recommendation tool fits better). +- The options have meaningful differences that warrant side-by-side analysis. +- The brand can articulate honest distinctions between options without becoming sales pitch. +- The audience benefits from decision support, not just feature listing. + +Comparison tools do NOT earn investment when: + +- Options are too similar to compare meaningfully. +- The brand cannot make honest distinctions without creating sales-pitch dynamics. +- A simple comparison table or written content would serve. +- The audience does not actually face this decision (manufactured comparisons). + +The decision is not "should we have a comparison tool"; it is "is the comparison tool the right tool for this decision." + +Detail in [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md). + +--- + +## Feature-list-dump vs hidden-recommendation vs honest-comparison-with-guidance + +The keystone framing. + +Feature-list-dump. Every option's every feature in a giant grid. No decision support. The user is asked to weigh 40 cells against each other; most leave without choosing. Cost: design effort wasted on a grid that does not produce decisions; the audience perceives the grid as overwhelming. + +Hidden-recommendation. "Comparison" tool that is actually a sales pitch. Defaults favor one option; framing weights the answer; the recommendation is invisible but baked in. Trust erodes when users notice the bias. Cost: short-term conversion may look fine; long-term brand damage from "manipulative" reputation. + +Honest-comparison-with-guidance. Genuine like-for-like comparison plus an explicit opinionated recommendation ("For X audience, choose Y"). The recommendation is visible, defended, and not the only path; users can override. Cost: design effort upfront is significant; conversion typically improves because users feel respected and helped. + +The litmus test. Does the tool tell the user what to choose for their specific situation, with reasoning? If yes, honest-comparison-with-guidance. If it dumps features without guidance, feature-list-dump. If it says "the right answer is obviously [our preferred option]" without acknowledgment, hidden-recommendation. + +--- + +## Axis selection: which dimensions matter, which are noise + +The single most consequential decision in comparison tool design. + +The principle. Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision, not every feature available. + +Strong axes. + +- Decision-relevant capabilities. Features that materially affect the audience's outcome. +- Cost dimensions. Price, total cost of ownership, hidden costs. +- Constraint dimensions. Capacity, scale, integration support. +- Service dimensions. Support quality, onboarding, SLA. +- Risk dimensions. Vendor stability, security, compliance. + +Weak axes. + +- Marketing checkboxes. Features that exist on every option; checkmarks across the row. +- Nice-to-haves. Features the audience does not actually weigh. +- Vendor-specific terminology. Features named differently by each vendor; comparison becomes label confusion. +- Decoration features. Features added to the grid because the brand has them and competitors do not. + +The 8-12 axis rule. Most production comparison tools work well with 8-12 axes. Beyond that, decision paralysis sets in. + +Detail in [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md). + +--- + +## Default-comparison logic + +Which options compare by default, and why. + +The principle. Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; biased defaults shape conclusions. + +Default options. + +- Audience-fit defaults. The options the audience most commonly considers. +- Stage-fit defaults. The options that match the audience's stage of decision. +- Inferred defaults. Based on referral source, query, or prior interaction. + +Default axes. + +- The axes most relevant to the typical audience. +- Audience can expand to additional axes if interested. + +Bias-flattering defaults. + +- Defaults set so brand always wins on visible axes. +- Defaults that hide axes where competitors win. +- Defaults that frame in brand's terminology. + +The discipline. Defaults serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +Detail in [`references/default-comparison-logic.md`](references/default-comparison-logic.md). + +--- + +## Recommendation engine design + +When to recommend, how to defend the recommendation. + +The principle. Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible. + +Recommendation patterns. + +- Single recommendation. "For [audience], choose [option] because [reasons]." Clear; opinionated. +- Multi-segment recommendation. "If you are [A], choose X. If you are [B], choose Y." Honest about audience-fit. +- Conditional recommendation. "If [factor] matters most, X. If [other factor] matters most, Y." Helps the user decide based on priorities. + +Recommendation defense. + +- The reasoning shown. +- The audience for the recommendation explicit. +- The override path visible. + +Anti-pattern: hidden recommendation. Tool that defaults to one option's victory through axis selection and framing, without explicit recommendation. Users feel manipulated when they catch the pattern. + +Detail in [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) and [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md). + +--- + +## Filter and toggle UX + +What users can adjust, what should stay fixed. + +Filterable elements. + +- Which options to compare (user adds or removes options). +- Which axes to show (user filters to relevant dimensions). +- Audience or use case (user signals their context; tool adapts). + +Fixed elements. + +- Methodology disclosure (always visible). +- Recommendation reasoning (always findable). +- Source citations (always linkable). + +The filter-fatigue trap. Too many filters; user paralyzed. + +The under-filtered trap. Tool too rigid; user cannot match their context. + +The discipline. Filters that materially help; not filters for the sake of customization. + +Detail in [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md). + +--- + +## Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Pattern 1: Too many cells. 40 features × 5 options = 200 cells; cognitive overload. + +Pattern 2: All-checkmarks rows. Every option has the feature; the row produces no signal. + +Pattern 3: Inconsistent axis terminology. Each vendor names features differently; user confused. + +Pattern 4: Hidden costs. Pricing visible; fees, overage, integrations not surfaced. + +Pattern 5: Apples-to-oranges options. Comparing genuinely different things; no axis applies cleanly. + +Pattern 6: No recommendation. Tool lists; user must decide; user does not. + +The cumulative effect. The tool produces no decision; users default to the brand they already heard of. + +Detail in [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-comparison-failures.md`](references/common-comparison-failures.md). + +- "Tool gets traffic; conversion is unchanged." Likely feature-list-dump; no decision support. +- "Sales says competitor leads cite our tool as biased." Hidden-recommendation pattern; trust damage. +- "Mobile users do not engage with the tool." Comparison grids do not work well on mobile; design for it. +- "Power users criticize axis selection." Audience knows these features; tool may have used easy axes rather than decision-relevant. +- "Tool was great at launch; conversion declined over time." Features changed; comparison stale. +- "Audience says 'this is helpful' but does not convert." Recommendation absent or weak; users get information without decision support. +- "Comparison shows every option as 'good' for something." Dilution; no clear recommendation. +- "Adding more features to the comparison reduced conversion." Crossed the cell-count threshold; cognitive overload. + +--- + +## The framework: 12 considerations for comparison tool design + +When designing or auditing a comparison tool, walk these 12 considerations. + +1. The comparison-tool decision. Is a tool the right answer, or does written content serve? +2. Honest-comparison-with-guidance, not feature-list-dump or hidden-recommendation. Genuine compare plus opinionated rec. +3. Axis selection. 8-12 decision-relevant axes; cut decoration features. +4. Default-comparison logic. Honest defaults; not bias-flattering. +5. Recommendation engine designed. Visible; defended; not the only path. +6. Filter and toggle UX. Filters that help; not filters for customization theater. +7. Methodology disclosed. Source data, axis weighting, audience definition. +8. Mobile parity. Tool works on the devices the audience uses. +9. Maintenance discipline. Comparison stays current as options change. +10. Honest about competitor strengths. When competitors win on an axis, say so. +11. Audience-fit measured. Per-segment conversion through the tool. +12. Conversion as success metric. Not just engagement; downstream choice and retention. + +The output of the framework is a comparison tool that earns the user's trust by helping them decide, with recommendation that is honest and defensible. + +--- + +## Reference files + +- [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md) - When comparison tools earn the build vs when written content serves. +- [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md) - Strong axes, weak axes, the 8-12 rule. +- [`references/default-comparison-logic.md`](references/default-comparison-logic.md) - Honest defaults vs bias-flattering defaults. +- [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) - When to recommend, how to defend, override path. +- [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md) - Filterable vs fixed elements; filter-fatigue trap. +- [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md) - Why most comparisons fail to produce decisions. +- [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md) - The discipline that distinguishes hidden from honest recommendations. +- [`references/comparison-anti-patterns.md`](references/comparison-anti-patterns.md) - The patterns that look like comparisons but degrade trust. +- [`references/common-comparison-failures.md`](references/common-comparison-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: comparison tools earn the choice when they earn the user's trust + +The comparison tools that work as compounding assets are the ones the audience trusts to help them decide. Not because the tool flatters the brand. Not because the tool dumps features. Because the tool genuinely helps the user pick the option that fits their situation, and is honest about which option that is. + +That is the bar. Below the bar are feature-list-dump (no decision support; user leaves without choosing) and hidden-recommendation (biased pretending to be neutral; trust collapses when caught). Above the bar are honest-comparison-with-guidance tools where axis selection, default logic, recommendation engine, and filter UX work together to produce decisions the audience trusts. + +The discipline is in the design choices. The decision to build a comparison at all. The axes that earn placement. The defaults that serve the audience. The recommendation that is visible and defended. The filters that help the user match their context. The methodology that is disclosed. The maintenance that keeps the comparison current. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md new file mode 100644 index 0000000..299644d --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/axis-selection-patterns.md @@ -0,0 +1,185 @@ +# Axis selection patterns + +Strong axes, weak axes, the 8-12 rule. + +Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision. Done well, axes produce decisions; done poorly, they produce overwhelm. + +--- + +## The decision-relevance principle + +Each axis should affect the audience's decision. Axes that do not are decoration. + +The win. A comparison tool with 10 axes covering capability, pricing, integration, support quality. Each axis materially affects whether the audience would choose. + +The fail. Same tool with 35 axes including marketing-checkbox features. User overwhelmed; many cells provide no signal. + +The discipline. Axes earn placement through decision relevance. + +--- + +## Strong axes + +Patterns that earn placement. + +Decision-relevant capabilities. The 5-7 capabilities the audience explicitly evaluates. + +Cost dimensions. Price, total cost of ownership, hidden costs. + +Constraint dimensions. Capacity, scale ceilings, integrations, geography. + +Service dimensions. Support quality, onboarding, SLA. + +Risk dimensions. Vendor stability, security, compliance. + +Time dimensions. Time to value, implementation timeline. + +The selection discipline. Each axis answers "will this matter to the audience?" If no, cut. + +--- + +## Weak axes + +Patterns that fail. + +Marketing checkboxes. Features on every option; checkmarks across the row. No signal. + +Nice-to-haves. Features the audience does not weigh. + +Vendor-specific terminology. Features named differently by each vendor; label confusion. + +Decoration features. Added because brand has them. + +Generic checkmarks. "Customer support: yes/yes/yes." Not differentiating. + +--- + +## The 8-12 axis rule + +Most production comparison tools work well with 8-12 axes. + +Why 8-12. + +- Below 8: comparison thin. +- Above 12: cognitive overload. + +Exceptions. + +- Highly technical audiences may absorb 15-20. +- Consumer audiences may tolerate 6-8. + +The over-12 trap. Each axis beyond 12 reduces engagement. + +--- + +## Axis ordering + +Within the comparison, order matters. + +Strong order. Most decision-relevant first. + +Weak order. Random; alphabetical; feature-category without importance weighting. + +The first-axis discipline. First axis should be one of the most important; users may skim past later axes. + +--- + +## Axis grouping + +When axes group naturally. + +Grouping patterns. Capability axes together; cost together; service together; risk together. + +Strengths. Easier to scan. + +Weaknesses. Group dividers add visual complexity. + +When to use. When axis count justifies (10+ axes). + +--- + +## Axis content per cell + +What each cell shows. + +Beyond checkmarks. "Yes/no" rarely produces decisions. Numbers, descriptions, comparisons add depth. + +Examples. + +- Cost: "$X/month" not just "Yes" to "has pricing." +- Capacity: "Up to 1000 users" not just "Yes" to "scales." +- Support: "24/7 chat plus phone" not just "Yes" to "support." + +The cell content discipline. Depth where decisions need it. + +--- + +## Axis defaults + +Which axes show by default; which behind toggle. + +Default-shown axes. The 8-12 most decision-relevant. + +Toggle-shown axes. Less critical; audience can expand. + +The hide-bias trap. Hiding axes where brand loses; detection eventual. + +The honest-default principle. Defaults reflect audience importance; not brand strength. + +--- + +## Axis updates + +Axes decay. + +What decays. + +- Axes that lost relevance. +- Axes that gained relevance. +- Axis content stale. + +Maintenance cadence. Quarterly review. + +--- + +## Axis testing + +Validate axes with the audience. + +Methods. + +- User research: which axes do they consider? +- A/B test: different axis sets. +- Sales-call mining: which axes do prospects ask about? + +The validation discipline. Axes are hypotheses; validate. + +--- + +## Common axis failures + +Too many axes. Cognitive overload. + +Too few axes. Comparison thin. + +Wrong axes. Audience does not weigh them. + +Marketing-checkbox axes. No signal. + +Vendor-specific terminology. Label confusion. + +Hidden axes where brand loses. Bias detected. + +Stale axis content. Pricing or features outdated. + +Axis ordering ignores importance. First axes are not most critical. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relevance principle. Strong axes (6 patterns). Weak axes (5 patterns). The 8-12 rule. Axis ordering. Axis grouping. Cell content. Axis defaults. Updates. Testing. Common failures. + +## Implementation choices that stay internal + +Specific axes for specific tools. Specific cell content. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md b/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md new file mode 100644 index 0000000..6dafdbb --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/common-comparison-failures.md @@ -0,0 +1,179 @@ +# Common comparison failures + +8+ failure patterns with diagnoses and cures. + +--- + +## "Tool gets traffic; conversion is unchanged." + +The diagnosis. Likely feature-list-dump; no decision support. + +The cure. Add recommendation. Cut decoration axes. Detail in `references/recommendation-engine-design.md`. + +--- + +## "Sales says competitor leads cite our tool as biased." + +The diagnosis. Hidden-recommendation pattern; trust damage. + +The cure. Honest recommendation discipline (`references/honest-recommendation-discipline.md`). Acknowledge competitor strengths. + +--- + +## "Mobile users do not engage with the tool." + +The diagnosis. Comparison grids do not work well on mobile. + +The cure. Mobile-first design. Stacked layout. Reduced axis count for mobile. + +--- + +## "Power users criticize axis selection." + +The diagnosis. Audience knows these features; tool may have used easy axes rather than decision-relevant. + +The cure. Audit axes against real audience decisions. Replace marketing-checkbox axes with decision-relevant ones. + +--- + +## "Tool was great at launch; conversion declined over time." + +The diagnosis. Features changed; comparison stale. + +The cure. Quarterly maintenance. + +--- + +## "Audience says 'this is helpful' but does not convert." + +The diagnosis. Recommendation absent or weak. + +The cure. Add recommendation with reasoning and clear next-step CTA. + +--- + +## "Comparison shows every option as 'good' for something." + +The diagnosis. Dilution; no clear recommendation. + +The cure. Take a stand. Recommendation should be opinionated; tradeoffs acknowledged. + +--- + +## "Adding more features to the comparison reduced conversion." + +The diagnosis. Crossed the cell-count threshold; cognitive overload. + +The cure. Cut back. 8-12 axes is the working range. + +--- + +## "Sales says many leads come through the tool but bounce on demo." + +The diagnosis. Tool's framing oversells; reality on demo does not match. + +The cure. Honest tool produces honest leads. Audit framing for sales-pitch dynamics. + +--- + +## "Audience-segment recommendations feel stereotyped." + +The diagnosis. Segment definitions based on assumptions rather than research. + +The cure. Validate audience segments with research. Refine recommendations based on real needs. + +--- + +## "Specific competitor is missing; users ask why." + +The diagnosis. Competitor omitted from comparison. + +The cure. Include relevant competitors. If intentionally excluded, disclose why ("we focus on X category; competitor Y is in different category"). + +--- + +## "Tool methodology questioned by analyst or journalist." + +The diagnosis. Methodology hidden or weakly defended. + +The cure. Detailed methodology disclosure. Be ready to defend specific axis choices and weights. + +--- + +## "Tool conversion is fine; sales conversion does not match." + +The diagnosis. Tool optimizes for tool-conversion; downstream not aligned. + +The cure. Track downstream metrics. Optimize for downstream conversion, not just tool engagement. + +--- + +## "Filter use is low; users see default comparison only." + +The diagnosis. Filters added but not promoted; users do not realize they exist. + +The cure. Promote filters; or accept that defaults serve and reduce filter complexity. + +--- + +## "Filters produce empty result combinations." + +The diagnosis. Filter logic does not constrain combinations to those producing comparable options. + +The cure. Smart filter logic. When filters would produce empty result, surface alternatives. + +--- + +## "Recommendation fires for one option always." + +The diagnosis. Hidden-recommendation; bias-flattering logic. + +The cure. Test the recommendation engine across audience scenarios. Ensure competitors win when fit warrants. + +--- + +## "Audience tells us the comparison feels accurate but the recommendation feels off." + +The diagnosis. Comparison data accurate; recommendation engine logic does not match audience priorities. + +The cure. Validate recommendation logic. Audience research on what they weigh vs what the tool weights. + +--- + +## "We A/B tested adding axes; conversion went down." + +The diagnosis. Crossed the cell-count threshold. + +The cure. Maintain axis discipline. More is not always better. + +--- + +## "Tool produces good conversion for new visitors; returning visitors do not engage." + +The diagnosis. Tool optimized for first-time-decision audience; returning visitors have other needs. + +The cure. Different surfaces for different stages. Returning visitors may want simpler reference rather than full tool. + +--- + +## The pattern across failures + +Most comparison tool failures fall into one of three patterns. + +Pattern 1: No decision support. Feature-list-dump, no-recommendation, dilution. The fix is clear, defensible recommendation. + +Pattern 2: Bias damages trust. Hidden-recommendation, contradiction, omitted competitors, stereotypes. The fix is honest recommendation discipline. + +Pattern 3: Friction. Over-filtered, mobile-broken, fatigue patterns. The fix is reducing cognitive load and matching audience use. + +The metric pattern: comparison failures often look fine on engagement alone. The signal is in conversion, downstream metrics, audience trust. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (no-decision-support, bias, friction). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md new file mode 100644 index 0000000..35ec8f0 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-anti-patterns.md @@ -0,0 +1,218 @@ +# Comparison anti-patterns + +The patterns that look like comparisons but degrade trust. Easy to ship; cost shows up in conversion, brand reputation, and audience trust. + +--- + +## The feature-list-dump comparison + +The pattern. Every feature × every option. No decision support. + +The signal. Users skim; do not choose; tool produces no conversion lift. + +The cure. Cut to 8-12 decision-relevant axes. Add recommendation. + +--- + +## The hidden-recommendation comparison + +The pattern. Defaults bias toward brand without disclosure. + +The signal. Sophisticated audiences notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest defaults; explicit recommendation; acknowledge competitor strengths. + +--- + +## The all-checkmarks comparison + +The pattern. Every option has every feature; checkmarks across the rows. + +The signal. Rows produce no signal; users skim. + +The cure. Cut generic-checkmark rows. Replace with specifics that differentiate. + +--- + +## The terminology-confused comparison + +The pattern. Each vendor's terminology used in their column; user cannot tell if features match. + +The signal. Users confused; comparison breaks semantically. + +The cure. Normalize terminology. Vendor names in subtext; functional descriptions in main label. + +--- + +## The hidden-cost comparison + +The pattern. Headline pricing visible; overage, fees, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cure. Total cost of ownership surfaced. + +--- + +## The apples-to-oranges comparison + +The pattern. Options compared that are genuinely different things. + +The signal. Comparison feels strained; axes do not apply cleanly. + +The cure. Compare options the audience actually considers together. Separate tools for separate categories if needed. + +--- + +## The no-recommendation comparison + +The pattern. Tool lists; user decides alone. + +The signal. High abandonment; conversion lift absent. + +The cure. Add recommendation with reasoning. + +--- + +## The contradicts-itself comparison + +The pattern. Comparison shows competitor winning on most axes; tool recommends brand anyway. + +The signal. Users notice the contradiction; trust collapses. + +The cure. Recommendation aligns with comparison; or recommendation defends the contradiction explicitly. + +--- + +## The stale comparison + +The pattern. Information from 6+ months ago. + +The signal. Users notice; trust drops. + +The cure. Quarterly maintenance. + +--- + +## The over-filtered comparison + +The pattern. 12+ filters; user paralysis at filter step. + +The signal. High drop-off before the comparison loads. + +The cure. Reduce filter count; default-heavy. + +--- + +## The under-filtered comparison + +The pattern. Tool too rigid; one fixed view. + +The signal. Specific segments convert poorly. + +The cure. Add filters where audiences split. + +--- + +## The mobile-broken comparison + +The pattern. Grid designed for desktop; mobile cramped or scroll-required. + +The signal. Mobile conversion much lower. + +The cure. Mobile-first design. + +--- + +## The methodology-hidden comparison + +The pattern. Tool shown without explaining how comparison was built. + +The signal. Sophisticated users question the tool. + +The cure. Methodology disclosure. + +--- + +## The audience-stereotype comparison + +The pattern. Audience-segment recommendations rely on stereotypes ("enterprise = big and slow"). + +The signal. Users in those segments feel mis-served. + +The cure. Audience-segment recommendations based on real needs, not assumptions. + +--- + +## The over-recommend comparison + +The pattern. Tool recommends in cases where genuine differentiator does not exist. + +The signal. Users notice the recommendation feels arbitrary. + +The cure. "We cannot rank these for you" is sometimes the honest answer. + +--- + +## The competitor-omission comparison + +The pattern. Important competitor missing from the comparison. + +The signal. Users ask "where is X?" or feel comparison is incomplete. + +The cure. Include relevant competitors. If a competitor is omitted intentionally, disclose why. + +--- + +## The bias-flattering-axis-selection comparison + +The pattern. Axes chosen where brand wins; axes hidden where brand loses. + +The signal. Sophisticated audiences notice axis selection. + +The cure. Honest axis selection. Detail in `references/axis-selection-patterns.md`. + +--- + +## The marketing-checkbox comparison + +The pattern. Every option's marketing checkboxes laid out as comparison. + +The signal. Comparison reads like marketing brochures rather than analysis. + +The cure. Replace marketing checkboxes with specific functional capabilities. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +Audit questions per tool. + +- Is the tool feature-list-dump (anti-pattern check)? +- Does the recommendation acknowledge competitor strengths (anti-pattern check: hidden-recommendation)? +- Are rows differentiating (anti-pattern check: all-checkmarks)? +- Is terminology normalized (anti-pattern check: terminology-confused)? +- Are total costs surfaced (anti-pattern check: hidden-cost)? +- Are options apples-to-apples (anti-pattern check: apples-to-oranges)? +- Is recommendation present (anti-pattern check: no-recommendation)? +- Does recommendation align with comparison (anti-pattern check: contradicts-itself)? +- Is information current (anti-pattern check: stale)? +- Are filters calibrated (anti-pattern check: over-filtered, under-filtered)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Is methodology disclosed (anti-pattern check: methodology-hidden)? + +The retire decision. Tools failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md new file mode 100644 index 0000000..10e5a0f --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-fatigue-patterns.md @@ -0,0 +1,190 @@ +# Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Most comparison tools accumulate cognitive load until users abandon without choosing. Comparison-fatigue patterns are the failure modes that make this happen. + +--- + +## Pattern 1: Too many cells + +The pattern. 40 features × 5 options = 200 cells. + +The signal. Users skim; pick the brand they already heard of; tool produces no decision. + +The cost. Comparison work is invisible because users cannot process the volume. + +The cure. Reduce cells. 8-12 axes × 3-5 options = 24-60 cells. The comparison density is comprehensible. + +--- + +## Pattern 2: All-checkmarks rows + +The pattern. Every option has the feature; the row produces checkmarks across. + +The signal. Users skim past; row provides no signal. + +The cost. Row earns space without earning attention. + +The cure. Cut the row, or replace generic checkmarks with specifics that differentiate. + +--- + +## Pattern 3: Inconsistent axis terminology + +The pattern. Each vendor names features differently; comparison becomes label confusion. + +The signal. User confusion; cannot tell if "Pro Workspace" and "Premium Studio" are the same thing. + +The cost. Comparison breaks at semantic level; users cannot weigh. + +The cure. Normalize terminology. Use functional descriptions; vendor labels in subtext. + +--- + +## Pattern 4: Hidden costs + +The pattern. Pricing visible; fees, overage, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cost. Trust damage when discovered. + +The cure. Surface total cost of ownership. Acknowledge fees, overage, expected add-ons. + +--- + +## Pattern 5: Apples-to-oranges options + +The pattern. Comparing genuinely different things; no axis applies cleanly. + +The signal. Comparison feels strained; users cannot tell why these options are being compared. + +The cost. Tool exists but produces no useful decision support. + +The cure. Compare options the audience would actually consider together. If options are too different, separate tools may serve better. + +--- + +## Pattern 6: No recommendation + +The pattern. Tool lists; user must decide; user does not. + +The signal. High abandonment; conversion rate low. + +The cost. The tool's information work does not produce decisions. + +The cure. Add explicit recommendation with reasoning. Detail in `references/recommendation-engine-design.md`. + +--- + +## Pattern 7: Stale information + +The pattern. Comparison content from 6+ months ago; competitors have updated; brand has updated. + +The signal. Users notice the staleness; trust drops. + +The cost. Tool produces decisions based on outdated information. + +The cure. Quarterly maintenance. Triggered updates when major competitor or brand changes happen. + +--- + +## Pattern 8: Bias-flattering framing + +The pattern. Comparison content frames in brand's favor (showing brand's most expensive plan vs competitors' cheap; using brand's terminology for axes). + +The signal. Sophisticated users notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest framing. Acknowledge competitor strengths. Use neutral terminology where possible. + +--- + +## Pattern 9: Decision paralysis at filter step + +The pattern. Tool requires extensive filter setup before showing comparison; users abandon at filter step. + +The signal. High drop-off before the comparison loads. + +The cost. Comparison work is invisible; users never see it. + +The cure. Default-heavy. Show comparison immediately; filters available but optional. + +--- + +## Pattern 10: Mobile illegibility + +The pattern. Comparison grid designed for desktop; on mobile, cells cramped or scroll-required. + +The signal. Mobile conversion much lower than desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design. Stacked layout for mobile; reduced axis count. + +--- + +## Pattern 11: No methodology disclosure + +The pattern. Comparison shown without explaining how it was assembled. Users do not know if it is honest. + +The signal. Users question the comparison; sales hears about doubts. + +The cost. Trust degrades; comparison's authority unclear. + +The cure. Disclose methodology. Where data came from; how axes were chosen; when last updated. + +--- + +## Pattern 12: Recommendation contradicts comparison + +The pattern. Comparison shows option B winning on most axes; tool recommends option A. + +The signal. Users notice the contradiction; trust collapses. + +The cost. Tool internally inconsistent; users cannot rely on it. + +The cure. Recommendation aligns with comparison. If recommendation favors A despite axis losses, defend explicitly ("Option A wins despite [losses] because [audience-specific reasoning]"). + +--- + +## The cumulative effect + +Most comparison tools fail at multiple of these patterns simultaneously. The cumulative effect: tool produces no decisions; users default to the brand they already heard of; comparison work is wasted. + +The cure. Audit each pattern. Each pattern fixed reduces cumulative friction. + +--- + +## How to audit comparison fatigue + +Quarterly review. + +Audit questions per tool. + +- Cell count: is it under 100? +- Are any rows all-checkmarks? +- Is terminology normalized across options? +- Are total costs surfaced? +- Are options apples-to-apples? +- Is recommendation present and visible? +- Is information current? +- Is framing honest? +- Is filter step lightweight? +- Does mobile work? +- Is methodology disclosed? +- Does recommendation match comparison? + +The retire decision. Tools failing multiple patterns warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 fatigue patterns. Signal-pattern-cost framing. Cures. The cumulative effect. Audit questions. + +## Implementation choices that stay internal + +Specific fatigue patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md new file mode 100644 index 0000000..527087f --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md @@ -0,0 +1,132 @@ +# Comparison-tool decision criteria + +When comparison tools earn the build vs when written content serves. + +A comparison tool is meaningful work. Axis selection, default logic, recommendation engine, filter UX, ongoing maintenance. The tool earns this investment only when specific conditions are present. + +--- + +## When comparison tools earn the build + +Five conditions that, when present, make a comparison tool a strong investment. + +The audience is at a decision moment between known options. They know the options exist; they need help choosing. Audiences who do not yet know the options need different tools (quizzes, recommendations). + +The options have meaningful differences. Comparing two options that differ only in branding produces nothing useful. + +The brand can articulate honest distinctions. Without becoming sales pitch. + +The audience benefits from decision support. Some audiences want a tool that helps them decide rather than weigh tradeoffs themselves. + +The success metric is defined. Conversion through the tool, downstream conversion, choice quality. + +When all five are present, a comparison tool is strong investment. When two or fewer are present, written content often serves better. + +--- + +## When comparison tools do NOT earn the build + +Funnels where comparison tools add cost without lift. + +Options too similar. Comparing genuinely interchangeable options produces no decision support. + +Options apples-to-oranges. Comparison axes do not apply across both. + +Brand cannot make honest distinctions. Tool will become hidden-recommendation; trust suffers. + +A simple table or article would serve. Static comparison content is cheaper. + +The audience does not face this decision. Manufactured comparisons feel forced. + +--- + +## Comparison tools vs written vs-pages + +Both compare options; differ in interactivity. + +Written vs-pages strengths. Cheap; SEO-friendly; easy to update. + +Written vs-pages weaknesses. Static; no recommendation logic. + +Comparison tool strengths. Adaptive; surfaces recommendations dynamically; lets users explore. + +Comparison tool weaknesses. Build cost; maintenance burden. + +The combined approach. Many production teams use both: vs-pages for SEO; tools for decision support. + +--- + +## The opportunity-cost frame + +Comparison tools are significant work. + +Build cost. Axis curation, recommendation logic, filter UX, methodology disclosure, mobile responsiveness. 30-100 engineering hours plus design and content. + +Maintenance cost. Quarterly updates run 4-8 hours. + +Opportunity cost. What else could the team have built? Better vs-pages, calculator, quiz. The tool has to clear those alternatives. + +The decision frame. Comparison tools earn investment when they produce more decision lift than alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering a comparison tool against 3 named competitors. + +Conditions check. + +- Decision moment: yes. +- Meaningful differences: yes; pricing, features, integration vary. +- Brand can articulate honest distinctions: yes. +- Audience benefits: yes. +- Success metric defined: yes. + +Decision. Build the comparison tool. + +Architecture. 10 axes; 4 options; honest recommendation per audience segment. + +The decision was deliberate. + +--- + +## Decision worked example: when written serves + +A consumer-facing financial product considering a comparison tool against generic bank accounts. + +Conditions check. + +- Decision moment: yes. +- Meaningful differences: somewhat; many banks similar. +- Brand articulate distinctions: yes for specific competitors. +- Audience benefits: somewhat. +- Success metric: signup; harder to attribute. + +Decision. Written vs-pages plus a brief comparison table. Full tool not warranted. + +The decision was right-sized. + +--- + +## When to retire a comparison tool + +Tools can become wrong over time. + +Retire when: + +- Conversion declined consistently. +- Options changed enough that comparison is misleading. +- Competitors deprecated. +- A redesigned vs-page produces equivalent results. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant comparison tools. The five conditions that argue against. Comparison tools vs written vs-pages. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tool decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md b/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md new file mode 100644 index 0000000..07c542a --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/default-comparison-logic.md @@ -0,0 +1,169 @@ +# Default-comparison logic + +Honest defaults vs bias-flattering defaults. + +Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; bias-flattering defaults shape conclusions in ways that erode trust when caught. + +--- + +## The honest-default principle + +Defaults should serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +The win. Default comparison shows the brand alongside 2-3 commonly-considered competitors. Default axes are the 8-12 most decision-relevant. Default audience profile (if pre-selected) reflects the visitor's likely segment. + +The fail. Default comparison shows the brand alongside the 2 weakest competitors. Default axes are the ones where the brand wins. Audience defaults assume the brand's ideal customer. + +The discipline. Defaults make the comparison fair as a starting point; users can adjust. + +--- + +## Default options + +Which options compare by default. + +Audience-fit defaults. The options the audience most commonly considers. + +How to determine. Sales-call mining (which competitors do prospects mention?), referral analysis, user research. + +Stage-fit defaults. The options that match the audience's stage. + +How. Awareness audiences may compare against generic categories; decision audiences against specific products. + +Inferred defaults. Based on referral source or query. + +How. Visitor from "X vs Y" search query gets X and Y as defaults; visitor from generic landing gets default comparison set. + +--- + +## Default axes + +Which axes show by default. + +The most-critical-axes default. Top 8-12 axes by decision relevance. + +Audience-relevant axes. Default to axes most relevant to the inferred or stated audience. + +The hide-where-we-lose anti-pattern. Defaulting to axes where the brand wins; hiding where it loses. Detection by analytical audiences eventual; trust damage permanent. + +The cure. Defaults reflect audience importance, not brand strength. Honest about competitor strengths. + +--- + +## Default audience or use case + +When the tool asks (or infers) the audience. + +Pattern A: Pre-selected. Tool selects an audience based on referrer or query. + +Strengths. Lower friction; tool seems intelligent. + +Weaknesses. Inference can be wrong. + +Pattern B: Asked upfront. Tool asks "what is your role?" or "what is your team size?" + +Strengths. Accurate; user controls. + +Weaknesses. Adds friction; some audiences skip. + +Pattern C: No audience selection. Tool shows comparison; user can filter. + +Strengths. Lowest friction; works for all audiences. + +Weaknesses. Generic; no per-audience recommendation. + +The choice depends on the tool's complexity and the audience's diversity. + +--- + +## Default recommendation + +What the tool recommends by default. + +Pattern A: Single default recommendation. "For most teams, [option] is the best choice." + +Strengths. Clear; opinionated. + +Weaknesses. May not fit all visitors. + +Pattern B: Audience-conditional default. Recommendation changes based on audience selection. + +Strengths. Fits different audiences. + +Weaknesses. More complex. + +Pattern C: No default recommendation. Tool requires user to specify before recommending. + +Strengths. User commits; recommendation is matched. + +Weaknesses. Higher friction. + +The discipline. Whatever default, the recommendation is honest about who it is for. + +--- + +## Bias-flattering defaults: the failure + +Patterns that destroy trust. + +Defaults set for brand victory. Comparison tool defaults to axes where the brand wins, hides where it loses. + +Defaults that frame in brand's terminology. Other options compared in vocabulary that favors the brand's positioning. + +Defaults that misrepresent competitor pricing. Showing competitor's most expensive plan vs brand's mid-tier. + +Defaults that show outdated competitor info. Listing features competitors have updated. + +The audience reaction. Sophisticated audiences notice; trust collapses; brand earns "manipulative" reputation. + +--- + +## Honest defaults with disclosure + +When the brand legitimately stands out, honest framing matters. + +The pattern. "Default view shows the comparison most relevant to teams of [size]. Your situation may differ; use filters to adjust." + +Disclosure where defaults are brand-favorable. "We are highlighting [axis] because we think it matters most for [audience]. Let us know if you weigh things differently." + +The honest framing earns trust where bias-flattering loses it. + +--- + +## Default maintenance + +Defaults decay. + +What decays. + +- Default options no longer match audience consideration. +- Default axes no longer the most relevant. +- Default audiences shifted. + +Maintenance cadence. Quarterly review. Update as competitive landscape and audience composition shift. + +--- + +## Common default failures + +Hide-where-we-lose. Bias detected; trust collapses. + +Stale defaults. Competitor info outdated. + +Wrong default audience. Inference produces unfit comparison for visitor. + +No default at all. Tool requires extensive setup before showing comparison. + +Default obscures methodology. Defaults look like neutral; methodology is biased. + +Default ignores recent competitor changes. Defaults from 6 months ago. + +--- + +## Methodology-level choices that stay in the public skill + +The honest-default principle. Default options. Default axes. Default audience or use case. Default recommendation. The bias-flattering failure pattern. Honest defaults with disclosure. Default maintenance. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific comparison tools. Specific audience inference logic. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md b/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md new file mode 100644 index 0000000..2d5addb --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/filter-and-toggle-patterns.md @@ -0,0 +1,225 @@ +# Filter and toggle patterns + +What users can adjust, what should stay fixed. The filter-fatigue trap. + +Filters and toggles let users adapt the comparison to their context. Done well, filters help users match the tool to their situation; done poorly, filters become customization theater that adds complexity without value. + +--- + +## The help-don't-customize principle + +Filters earn placement when they help users match the comparison to their context. Filters for the sake of customization options add complexity without lift. + +The win. Tool offers 3 filters: audience size, use case, must-have integrations. Each filter materially adapts the recommendation. Users find their context quickly. + +The fail. Tool offers 15 filters across multiple dimensions. Decision paralysis at the filter step; users abandon before reaching the comparison. + +The discipline. Filters that help; not filters for theater. + +--- + +## Filterable elements + +What users can adjust. + +Options to compare. User adds or removes options. + +Axes to show. User filters to relevant dimensions. + +Audience or use case. User signals their context; tool adapts. + +Pricing model preference. User selects monthly vs annual; per-seat vs flat. + +Region or geography. User selects where they operate; tool adapts to applicable options. + +--- + +## Fixed elements + +What should not be filterable. + +Methodology disclosure. Always visible. + +Recommendation reasoning. Always findable. + +Source citations. Always linkable. + +Honest framing. Tool is honest about its biases regardless of filter state. + +--- + +## Filter UI patterns + +How filters appear. + +Pattern A: Top-of-page filters. + +How it works. Filter row at top; user adjusts; comparison below updates. + +Strengths. Visible; familiar. + +Weaknesses. Takes screen space; mobile-challenging. + +Pattern B: Sidebar filters. + +How it works. Filter panel on the side; comparison main area. + +Strengths. Persistent; works on desktop. + +Weaknesses. Mobile-broken; takes space. + +Pattern C: Inline filters. + +How it works. Filters appear within the comparison (per-axis filtering, per-option toggling). + +Strengths. Contextual. + +Weaknesses. Visual complexity. + +Pattern D: Wizard-style. + +How it works. Tool asks 2-3 filter questions; then shows comparison. + +Strengths. Less overwhelming. + +Weaknesses. Adds friction upfront. + +The choice depends on filter complexity and audience preferences. + +--- + +## Filter count + +How many filters earn placement. + +3-5 filters. Sweet spot. Each filter helps; cumulative friction manageable. + +6-8 filters. Acceptable for complex tools; require strong UX. + +10+ filters. Almost always too many. Decision paralysis at filter step. + +1-2 filters. Often too few; tool feels rigid. + +--- + +## Filter defaults + +What filters are pre-set. + +Honest defaults. Reflect typical audience. + +Audience-detected defaults. Inferred from referral or context. + +No defaults (user must select). Adds friction but ensures intentionality. + +The default discipline. Defaults reflect audience importance; not brand strength. + +--- + +## Filter combinations + +When filters interact. + +Independent filters. Each filter changes one dimension; combinations multiply. + +Conditional filters. Some filters appear only after others are set. + +Smart filters. Tool suggests filters based on earlier selections. + +The discipline. Combinations should produce meaningful comparisons; not empty cells. + +--- + +## The filter-fatigue trap + +Too many filters; user paralyzed. + +The pattern. Tool offers 12 filters. User feels they need to set them all to get meaningful comparison. User leaves before completing. + +The signal. Drop-off at the filter step; users do not reach the comparison. + +The cost. Comparison tool's main value (the comparison) is invisible. + +The cure. Reduce filter count. Default-heavy. Optional filters behind a "more options" toggle. + +--- + +## The under-filtered trap + +Tool too rigid; user cannot match context. + +The pattern. Tool shows one fixed comparison; no way to adapt. + +The signal. Users complain the tool does not fit them; specific segments convert poorly. + +The cost. Tool serves only the audience the default fits. + +The cure. Add filters where audience genuinely splits. + +--- + +## Filter mobile design + +Filters on mobile have specific considerations. + +Mobile-specific patterns. + +- Filters in a collapsible drawer rather than always-visible panel. +- Reduced filter count on mobile (defer non-critical filters). +- Touch-friendly toggles. + +Mobile-broken patterns. + +- Sidebar filters cramping the comparison. +- Top-of-page filters that scroll off and require scrolling back. +- Filter modals that take over the screen. + +The mobile discipline. Filters work on mobile or do not exist there. + +--- + +## Filter analytics + +Track filter use. + +Metrics. + +- Per-filter use rate. +- Filter abandonment (started filtering; left without completing). +- Filter combinations that produce no results. + +Diagnostic uses. + +- Filter rarely used: it may not earn placement. +- Filter abandonment high: too many filters or bad defaults. +- No-result combinations: filter logic may have gaps. + +--- + +## Common filter failures + +Too many filters. Filter fatigue. + +Too few filters. Tool too rigid. + +Filters with no value. Filters that do not change anything meaningful. + +Filters that produce empty results. Combinations show no options. + +Mobile-broken filters. Filters work on desktop, fail mobile. + +Filter UX inconsistent. Mix of patterns; users confused. + +Default filters bias-flattering. Defaults make brand look better than reality. + +No filter analytics. Cannot tell which filters earn their place. + +--- + +## Methodology-level choices that stay in the public skill + +The help-don't-customize principle. Filterable vs fixed elements. Filter UI patterns A through D. Filter count. Filter defaults. Filter combinations. The filter-fatigue and under-filtered traps. Filter mobile design. Filter analytics. Common failures. + +## Implementation choices that stay internal + +Specific filters for specific tools. Specific filter UI implementations. Specific defaults. The team's mobile testing benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md b/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md new file mode 100644 index 0000000..37df188 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/honest-recommendation-discipline.md @@ -0,0 +1,201 @@ +# Honest recommendation discipline + +The discipline that distinguishes hidden from honest recommendations. + +Recommendations are powerful. Honest ones earn trust; hidden ones erode it. The discipline is to know which kind your tool produces. + +--- + +## The litmus test + +A sophisticated user from the target audience tests the tool by selecting a clearly wrong-fit scenario for the brand. Does the tool recommend a competitor when fit warrants? + +The win. Tool recommends competitor X for the wrong-fit scenario, with reasoning. The sophisticated user trusts the tool because it is willing to recommend against the brand. + +The fail. Tool always recommends the brand regardless of scenario. The sophisticated user catches the pattern; trust collapses. + +The discipline. The tool's willingness to recommend competitors when warranted is the trust marker. + +--- + +## What honest recommendation looks like + +Five marks of honesty. + +Mark 1: Brand does not always win. When competitors fit better, tool says so. + +Mark 2: Reasoning is specific and verifiable. "Option B has X capability that Option A lacks" rather than "B is better." + +Mark 3: Audience-fit is articulated. "For [audience] with [needs], choose X. For different audience, choose Y." + +Mark 4: Tradeoffs acknowledged. "Option X wins on capability A but loses on capability B." + +Mark 5: Methodology disclosed. Users can see how the recommendation was generated. + +When all five are present, the recommendation is honest. When any are absent, hidden-recommendation dynamics creep in. + +--- + +## What hidden recommendation looks like + +Five marks of hidden bias. + +Mark 1: Brand always wins regardless of scenario. + +Mark 2: Reasoning is generic ("best in class") without specifics. + +Mark 3: Audience-fit not articulated; one recommendation for all. + +Mark 4: Tradeoffs not acknowledged; brand presented as superior on all axes. + +Mark 5: Methodology hidden or vague. + +When these patterns combine, the tool is hidden-recommendation regardless of whether the team intended bias. + +--- + +## The acknowledge-competitor-strengths principle + +Honest recommendation tools acknowledge where competitors are stronger. + +The pattern. "Competitor X has the strongest [capability]. We win on [different capability]. For audiences prioritizing [first], X. For audiences prioritizing [second], us." + +Why it works. Acknowledging strengths signals honesty. Audiences trust the recommendation more because the tool is willing to lose on specific axes. + +The reluctant-acknowledgment failure. Acknowledging competitor strengths only when forced; minimizing them where possible. Detection by sophisticated audiences eventual. + +--- + +## The recommendation-defense quality + +How well the tool defends its recommendation. + +Strong defense. + +- Specific to audience. +- Tied to specific axes where the recommended option wins. +- Includes tradeoffs. +- Cites data or sources. + +Example. + +"For mid-market teams (50-200 users): Option B. Reasons: B's pricing scales better at 200+ users, B's [specific feature] is unmatched, B's support response time is fastest. Tradeoff: B's onboarding is longer than Option A's. For under-50-user teams, Option A may serve better." + +Weak defense. + +- "B is the best choice." +- "Most teams choose B." +- Generic claims. + +The defense earns trust through specificity and acknowledged tradeoffs. + +--- + +## Audience-segment recommendations + +Different audiences may warrant different recommendations. + +Patterns. + +- "Solo and small teams: choose A." +- "Mid-market: choose B." +- "Enterprise: choose C." + +Why this works. Audiences self-identify; tool serves each. + +The single-recommendation-fits-all failure. One recommendation for diverse audiences misses fit. + +The discipline. When audiences differ, recommendations differ. + +--- + +## When the recommendation should be no-recommendation + +Sometimes "we cannot tell which is best for you" is the honest answer. + +Patterns. + +- "Both options fit teams in your situation; differentiator is [factor] you should weigh personally." +- "If [criterion] matters most to you, X. If [criterion] matters most, Y. We cannot rank for you." + +Why this works. Honest about the limits of recommendation; respects user agency. + +The over-recommend failure. Recommending in cases where genuine differentiator does not exist; trust suffers when users notice. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +Disclosure patterns. + +- "We weight [axes] heavily because [reasons]." +- "If you weigh different axes, your recommendation may differ." +- "Our methodology is described here." + +The audience that questions. Some users will dig. Methodology should hold up. + +--- + +## The recommendation-audit pattern + +Periodically test the tool's honesty. + +Audit method. + +- Test scenarios where competitors should win. +- Test scenarios where brand should win. +- Test edge cases. + +Audit findings. + +- Tool always recommends brand: hidden-recommendation; redesign. +- Tool sometimes recommends competitors: honest; verify the recommendations make sense. +- Tool refuses to recommend: may be appropriate for genuine ties; should not be default. + +The audit catches drift. Honest tools at launch can become hidden-recommendation through small changes over time. + +--- + +## Honest recommendation maintenance + +Honest recommendations decay. + +What decays. + +- Reasoning based on outdated capabilities. +- Audience-segment definitions that no longer fit. +- Methodology that no longer matches the tool's logic. + +Maintenance cadence. Quarterly review. Verify reasoning still holds; verify methodology matches implementation. + +--- + +## Common honest-recommendation failures + +Brand always wins. Hidden-recommendation; trust risk. + +No defense. Recommendations without reasoning. + +Generic recommendations. "Best for most teams" without specificity. + +Single recommendation for diverse audiences. Missed fit. + +Tradeoffs hidden. Brand presented as superior on all axes. + +Methodology vague. Users cannot inspect. + +No competitor-strength acknowledgment. Trust suffers. + +Stale recommendation. Reasoning based on outdated info. + +--- + +## Methodology-level choices that stay in the public skill + +The litmus test. Five marks of honest recommendation. Five marks of hidden recommendation. The acknowledge-competitor-strengths principle. Recommendation defense quality. Audience-segment recommendations. When no-recommendation is honest. Recommendation transparency. The audit pattern. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific recommendation logic for specific tools. Specific audience-segment mappings. Specific methodology copy. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md b/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md new file mode 100644 index 0000000..28b7c77 --- /dev/null +++ b/dist/pi/.agents/skills/comparison-tool-design/references/recommendation-engine-design.md @@ -0,0 +1,172 @@ +# Recommendation engine design + +When to recommend, how to defend, override path. + +Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible, visible, and not the only path. + +--- + +## The visible-defended-overridable principle + +Recommendations are most useful when: + +- Visible. Users can see what the tool recommends. +- Defended. Reasoning is explicit. +- Overridable. Users who weigh things differently can choose otherwise. + +The win. Tool recommends "Option B for mid-market teams prioritizing scale." Recommendation prominent; reasoning shown; user can switch audience or pick differently. + +The fail. Tool dumps features; user must decide alone. + +The discipline. Recommend with reasoning; respect override. + +--- + +## Recommendation patterns + +Common patterns. + +Pattern A: Single recommendation. "For [audience], choose [option] because [reasons]." Clear; opinionated. + +Pattern B: Multi-segment recommendation. "If [A], choose X. If [B], choose Y." + +Pattern C: Conditional recommendation. "If [factor] matters most, X. If [other], Y." + +Pattern D: Recommendation with caveat. "We think X fits most teams in your situation, with these caveats." + +Pattern E: No recommendation. Rarely the right choice. + +--- + +## Defending the recommendation + +The reasoning shown. + +Strong defense. Specific reasons tied to recommended option's strengths; audience-fit articulated; tradeoffs acknowledged. + +Example. "For mid-market teams: Option B. B's pricing scales better at 200+ users (X% vs Y%), B's integration with [tool] is faster, B's support response is shortest in this tier. Tradeoff: B's interface is less polished than Option A; A wins for teams under 50." + +Weak defense. "B is our recommendation"; "B is best for most teams"; generic claims. + +The defense earns trust through specificity. + +--- + +## The override path + +How users can choose otherwise. + +Visible alternative paths. + +- Toggle to switch recommended audience. +- Filter to weight axes differently. +- Direct selection of different option. + +Friction balance. + +- Override findable in 1-2 clicks. +- Override does not require restart. +- Override preserves user context. + +The discipline. Override is honest; users who disagree are not punished. + +--- + +## Recommendation framing + +How recommendations are worded. + +Strong framing. Specific to audience; tied to reasoning; acknowledges tradeoffs; inviting override. + +Weak framing. "Obviously X is best"; "most experts agree X"; "X is the only choice for serious teams." + +What works. Specificity, humility, agency for the user. + +--- + +## Audience-fit recommendations + +Different audiences may warrant different recommendations. + +The pattern. Tool detects or asks about audience; recommendation adapts. + +Detection methods. + +- Referrer or query. +- Stated input. +- Inferred from context. + +The discipline. Audience signals inform recommendation; do not stereotype. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +Methodology disclosure. + +- "We weight [axes] heavily because [reasons]." +- "If you weigh [factor] differently, your recommendation may differ." + +The audience that questions. Some users will dig; methodology should hold up. + +--- + +## The recommendation-bias risk + +Recommendations are powerful; biased ones damage trust. + +Common biases. + +- Recommending brand in all cases. +- Recommendations always benefit recommender. +- Hidden weighting toward brand strengths. + +The trust-collapse. When users catch bias, they stop trusting entirely. + +The cure. Acknowledge competitor strengths. Recommend competitors when fit warrants. Honest about who is recommending whom. + +--- + +## Recommendation testing + +Validate. + +Methods. + +- User research: do recommendations match what audiences would have chosen with full information? +- Cohort analysis: do recommendation-followers retain better? +- Sales feedback: do recommended-option leads convert at higher rates? + +The discipline. Recommendation is hypothesis until validated. + +--- + +## Common recommendation failures + +No recommendation. Tool lists; users decide alone. + +Hidden recommendation. Tool defaults bias toward one option without disclosure. + +Generic recommendation. "Best for most teams" without specificity. + +Single recommendation for diverse audiences. Missed fit. + +Recommendation without defense. Authoritative without reasoning. + +No override path. Users who disagree have no clear alternative. + +Recommendation always favors brand. Trust collapses. + +Stale recommendation. Reasoning based on outdated capabilities. + +--- + +## Methodology-level choices that stay in the public skill + +The visible-defended-overridable principle. Patterns A through E. Defending the recommendation. The override path. Framing. Audience-fit recommendations. Transparency. The bias risk. Testing. Common failures. + +## Implementation choices that stay internal + +Specific recommendation engines for specific tools. Specific audience-segment mappings. Specific reasoning copy. The team's validation processes. These vary by team. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md b/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md new file mode 100644 index 0000000..0eee8fd --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/SKILL.md @@ -0,0 +1,191 @@ +--- +name: competitor-experience-audit +description: "Audit the brand, UX, and site design of the leading sites in a vertical as a set of observable cross-site patterns, producing the experience bar a new build must meet or beat. Use this skill whenever the user wants to assess the competitive design field, capture vertical conventions, identify the design and UX bar of a category, or set the experience standard before a build. Triggers on competitor experience audit, UX audit, site design audit, brand audit, design conventions, what makes these sites good, vertical conventions, storefront patterns, merchandising patterns, layout density, primary task, design bar, category conventions, retail vs marketing register, what does the field do. Also triggers when an audit of the competitive field has captured technical signals (SEO, accessibility) but never named the brand, UX, or design conventions, and the build downstream will read as off-vertical without that bar." +category: research +catalog_summary: "Cross-site experience patterns and gaps across a vertical" +display_order: 6 +--- + +# Competitor Experience Audit + +Capture the brand, UX, and site design that the leading sites in a vertical observably share, and where they fall short. The output is the experience bar a new build must meet or beat, grounded in cross-site patterns rather than aesthetic opinion. + +Stack-agnostic. Works on any SiteShape (ecommerce-catalog, inventory-listing, hospitality-food, b2b-manufacturer, and so on). Auto-parts catalogs are the first test case, not the only target. + +This skill is the brand / UX / design counterpart to a technical audit like `seo-onpage` or `accessibility-audit`. Technical findings are objective (a missing canonical is missing). Design is more subjective, so this skill is deliberately written to make the subjective assessable: every dimension is judged by observable questions about what the leading sites actually do, reported as patterns and gaps, and marked `not_assessable` whenever the evidence does not support a judgment. + +--- + +## When to use + +- Setting the experience bar for a new build in a vertical you have not built in before +- Capturing the design and UX conventions a credible site in the category is expected to carry +- Auditing the competitive field for a critic or strategy review where SEO and accessibility have been covered but design and experience have not +- Naming the positioning opportunity that recurs across the leaders (the gap even the leaders share) +- Pairing with a technical audit (SEO, accessibility) so the competitor review captures both axes + +## When NOT to use + +- Rating a single page or one brand's design taste in isolation (use `design-standards` or `brand-style-guide` for production design decisions on a known build) +- Backlink, keyword, or SERP-overlap competitive analysis (use `seo-competitor`) +- Generating a creative direction from scratch for a new brand (use `creative-direction` and `brand-discovery`) +- User research with real participants on your own product (use `ux-research`, `usability-testing`) +- Auditing a single page's on-page SEO or accessibility against the audit suite (use `seo-onpage`, `accessibility-audit`) + +--- + +## Required inputs + +- The vertical and a list of the leading sites in it (3 to 6 sites; more than 6 stops surfacing new patterns) +- Access to the rendered sites (a real browser view, not just static HTML; see "Static vs rendered" below) +- The site shape the audit feeds, if known (ecommerce-catalog, inventory-listing, etc.); this scopes which dimensions to weight +- Any explicit constraint on the build downstream (the brand voice, the audience, the conversion the build will own) + +If the list of leading sites is unknown, ask. Picking the wrong field produces an experience bar against the wrong vertical. + +### Static vs rendered + +Some dimensions can be partially assessed from static HTML (primary navigation, the catalog/category surface count, the presence of search). Most cannot. Layout density, brand register, motion, trust-signal prominence, and the rendered hierarchy of the first viewport all need the rendered page to judge honestly. If you only have static HTML for a site, mark every rendered-only dimension `not_assessable` for that site rather than guessing. + +--- + +## The framework: 7 experience dimensions + +Each dimension is judged by observable questions across the leading sites in the field, then reported as a cross-site pattern plus the gap (where the leaders converge, and where even they fall short). + +Score each dimension as `Pattern present` (the field converges on a recognizable convention), `Mixed` (the field splits across two or three approaches), or `Gap` (no convention emerges, or every leader misses it). Mark `not_assessable` when the evidence cannot support a judgment. + +Never write `Good design` or `Bad design` or any aesthetic verdict. The dimensions are about what the field observably does, not whether you like it. + +### 1. Primary-task prominence + +Does the site lead with the visitor's primary job, or bury it? + +- What is the largest, earliest interactive element on the first viewport? (For auto-parts: typically a fitment selector. For hospitality-food: a menu or reservation entry.) +- How many clicks or scrolls to the core task? +- Does the site protect the primary task from competing CTAs in the hero? + +Observable signal: count the elements that compete for first attention, identify which one the layout actually privileges, name what the field converges on as the primary task. + +### 2. Layout register and density + +Is the layout retail-dense, editorial, or marketing-airy? Cross-reference `creative-direction` aesthetic positions (editorial restrained, polished standard, controlled maximalist, expressive maximalist) for vocabulary; do not redefine that here. + +- How many distinct modules appear above the fold? +- What is the content-per-viewport ratio (dense storefront, calm editorial, generous marketing)? +- Does the page read as a storefront, a catalog, a landing page, or a brochure? + +Observable signal: count modules above the fold across the field; describe the register the leaders share, not whether you find it attractive. + +### 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape? + +- How many category, collection, or entry-point modules appear before scroll? +- How is depth signaled (mega-menu, grid, side rail, faceted search)? +- Is the surface flat (one tier visible) or hierarchical (parent plus child categories shown together)? + +Observable signal: count the category entry points and describe the navigation depth pattern the field uses. + +### 4. Primary navigation and search paths + +Do the sites serve both the know-what-I-want path and the browse path? + +- Is search prominent and primary, secondary, or absent? +- What paths are offered (by category, by brand, by attribute, by vehicle, by location, by occasion)? +- Where does the primary nav sit (top, side, sticky, mega-menu)? + +Observable signal: list the paths the field offers, score whether each path is primary, secondary, or missing. + +### 5. Brand register and conviction + +What brand posture do the leading sites take, and is it consistent across the page? + +- Color, type, imagery: utilitarian, premium, friendly, institutional, technical, expressive? +- Voice in headings and microcopy: direct, persuasive, technical, warm, plain? +- Trust signals: institutional (long-standing, association badges), social (reviews, community), or operational (in-stock, warranty, fitment confirmation)? + +Cross-reference the `creative-direction` and `brand-archetype-system` skills for the vocabulary. Report the register the field converges on. Do not rate the taste; describe what posture the leaders take. + +### 6. Trust and conversion signals + +What recurring trust and conversion conventions does the field use? + +- Reviews, guarantees, social proof, badges +- Pricing transparency (price visible, no surprises, total cost surfaced) +- Stock and availability signals +- Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it) +- Return, shipping, or service-level promises + +Observable signal: which signals appear across the field, where they appear, and which the leaders share. + +### 7. Recurring vertical conventions (the synthesis) + +The patterns that recur across the leaders and define what a credible site in this vertical is expected to have. This is the synthesis of dimensions 1 through 6 into a short list of "if your build does not do this, it will read as off-vertical." + +Observable signal: which conventions recur on 3 of N or more of the leading sites; which are absent across the field (the gap that a positioning opportunity exploits). + +--- + +## The honesty guardrail (load-bearing) + +This is not negotiable. The credibility of an experience audit erodes the moment it slides into taste: + +- Report what the leading sites observably do and where they observably fall short, as cross-site patterns. Do not render personal aesthetic judgments ("this is ugly", "good design", "the typography is clean"). Aesthetic verdicts belong in `art-direction` or `design-standards`, not here. +- When the evidence does not support a judgment, say so plainly and mark the dimension `not_assessable` for that site or that pattern. Common cases: layout and density cannot be judged from un-rendered static HTML; motion and animation cannot be judged from a screenshot; brand voice cannot be judged from a single page. +- Do not name a convention from one site. A pattern is a recurrence across the field (3 of N or more); one site doing something distinctive is a single-site observation, not a convention. +- The output is a grounded experience bar: the conventions and gaps of the field, usable as a standard a build must meet. It is not an opinion piece. + +If the user asks "is this design good", redirect to observable patterns ("the leading sites in the field share X, Y, Z; this build does X and W but not Y or Z; that is the gap"). If the user asks for an aesthetic call, point them at `design-standards` or `art-direction`. + +--- + +## Workflow + +1. Confirm the vertical and the leading sites. Ask if either is unclear; an audit against the wrong field is worse than no audit. +2. Render and view each site as a user would. Open in a real browser, on the device class the field's visitors use (desktop and mobile for ecommerce; mobile-first for hospitality-food; etc.). Do not work from static HTML alone for any dimension marked rendered-only. +3. Assess each dimension across the field. Use [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) to score each site on each dimension. Mark `not_assessable` wherever the evidence is thin. +4. Synthesize cross-site patterns. For each dimension, name the recurring convention (or the split, or the gap). Distinguish patterns the field converges on from single-site moves. +5. Name the gap (the positioning opportunity). Where do even the leaders fall short? That is where a new build's positioning can exploit the field. +6. Write the bar. Use the template in [`references/audit-template.md`](references/audit-template.md). Default output is a markdown experience bar, generalized to pattern-level if it will feed a public showcase workup (no named competitors in the public version). +7. Hand the bar to the build skills. The output is the standard `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill (`landing-page-copy`, `frontend-component-build`) read as the experience bar to meet. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Rate the design of these sites." Vague. Redirect to observable patterns: what the leading sites in the field do across the seven dimensions, not whether you like it. +- Judging un-rendered pages for layout, density, or motion. Mark `not_assessable` and get the rendered view. Static HTML supports only partial assessment; do not guess at design quality you cannot see. +- Naming a convention from one site. A pattern is a recurrence across the field. One site doing something distinctive is a single-site observation; flag it that way, not as a convention. +- Substituting personal taste for field patterns. "I think the colors are good" is not an audit finding. "The field converges on a navy-and-rust register; this site uses it" is. +- Aesthetic verdicts dressed as observations. Watch for "clean", "modern", "professional", "premium-feeling" with no observable signal underneath. If you cannot point at a specific observable thing, you are giving taste, not a pattern. +- Skipping the gap. An audit that names only what the leaders do well is half the value. The recurring weakness across the field is where a positioning opportunity lives; name it. +- Generalizing too soon. A 2-site sample is not the field. If you can only render 2 of 5 leaders, mark the audit `partial` and call out what is assessed vs what is not. + +--- + +## Output format + +Default output is a markdown experience bar at `experience-audit-[vertical-slug].md` in the project root. Structure: + +1. Vertical and the field surveyed (sites assessed, what could not be rendered) +2. Score per dimension across the field +3. Cross-site patterns (the conventions the leaders converge on) +4. Gaps (where the field falls short, the positioning opportunity) +5. The experience bar (the synthesis: what a credible build in this vertical must do) +6. `Not_assessable` items (what could not be judged and why) + +Keep the bar under 1500 words. If a dimension needs deeper treatment, link to a deeper appendix rather than expanding inline. + +### Scrub for showcase use + +If the audit will feed a public showcase workup, scrub for named competitors before publishing. The named version stays operated-side; the public workup carries the patterns and the gaps in generalized form. This mirrors how Basano's competitor review already handles named sites in its model-backed audit. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable experience-audit template, copy and use. Generalized and named variants both present. +- [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) - The observable questions per dimension, in scoring order. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md b/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md new file mode 100644 index 0000000..d244e9a --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/references/audit-template.md @@ -0,0 +1,136 @@ +# Competitor Experience Audit: [Vertical] + +Site shape: [ecommerce-catalog / inventory-listing / directory-marketplace / local-service-booking / subscription-app / hospitality-food / institution-mission / b2b-manufacturer / ecommerce-standout / hospitality-experience] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Field assessed: [N sites] +Rendered: [N of N] Static-only: [N of N] + +--- + +## Field surveyed + +\| Site \| Rendered \| Notes \| +\|---\|---\|---\| +\| [Site 1] \| [yes/no] \| [any access caveat] \| +\| [Site 2] \| [yes/no] \| \| +\| [Site 3] \| [yes/no] \| \| +\| [Site 4] \| [yes/no] \| \| +\| [Site 5] \| [yes/no] \| \| + +If publishing the audit publicly, prepare a generalized version that drops the named column; the named version stays operated-side. + +--- + +## Summary + +[Two to three sentences. The cross-site picture: what the field converges on, where it falls short, what the positioning opportunity is. Generalized; no aesthetic verdicts.] + +\| Dimension \| Score \| One-line pattern \| +\|---\|---\|---\| +\| Primary-task prominence \| [Pattern present / Mixed / Gap / Not assessable] \| \| +\| Layout register and density \| \| \| +\| Merchandising and category surface \| \| \| +\| Primary navigation and search paths \| \| \| +\| Brand register and conviction \| \| \| +\| Trust and conversion signals \| \| \| +\| Recurring vertical conventions \| \| \| + +--- + +## Cross-site patterns + +### 1. Primary-task prominence + +[What the field converges on as the primary task; what element carries it; how protected the task is from competing CTAs. Observable signal: what is the largest, earliest interactive element, and what is the click count to the core task.] + +Pattern: [The field's convention] +Outliers: [Any leader that breaks the pattern, and what they do instead] + +### 2. Layout register and density + +[The register the field shares (retail-dense, editorial, marketing-airy, hybrid). Cross-reference `creative-direction` aesthetic positions for vocabulary.] + +Pattern: [The field's register] +Outliers: [Any leader that uses a different register] + +### 3. Merchandising and category surface + +[How much of the offering is surfaced before scroll; the navigation depth pattern; mega-menu vs grid vs side rail.] + +Pattern: +Outliers: + +### 4. Primary navigation and search paths + +[Which paths the field offers (search-first, by-category, by-brand, by-attribute, by-vehicle, by-location). Score each path as primary / secondary / absent.] + +Pattern: +Outliers: + +### 5. Brand register and conviction + +[The brand posture the leaders converge on. Cross-reference `creative-direction` and `brand-archetype-system`.] + +Pattern: +Outliers: + +### 6. Trust and conversion signals + +[Which signals appear across the field (reviews, guarantees, pricing transparency, stock, fitment confirmation, return policy). Where they appear.] + +Pattern: +Outliers: + +### 7. Recurring vertical conventions + +[The synthesis. The conventions a credible site in this vertical is expected to have, named explicitly. A build that ignores these will read as off-vertical.] + +Conventions: +- [Convention 1] +- [Convention 2] +- [Convention 3] +- ... + +--- + +## Gaps (the positioning opportunity) + +[Where even the leaders fall short. The recurring weakness across the field. This is the wedge a new build's positioning can exploit. Observable, not speculative.] + +- [Gap 1]: [The weakness the field shares; how it shows up across N of the N leaders; what a build that fixes it would look like.] +- [Gap 2]: +- [Gap 3]: + +--- + +## The experience bar (the build standard) + +A credible build in this vertical, against this field, must: + +- [Bar item 1 - usually maps to a recurring convention from dimension 7] +- [Bar item 2] +- [Bar item 3] +- ... + +Optional positioning move: + +- [The build's wedge - exploit one or more of the gaps above] + +Hand this bar to `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill so they read as the standard to meet, not as suggestions. + +--- + +## Not assessable + +[Dimensions or sites that could not be judged honestly. Common reasons: site not renderable, motion not capturable, brand voice not derivable from a single page, depth of the category surface only visible after authentication.] + +- [Dimension or site]: [Why it cannot be judged from the evidence available. What evidence would be needed to assess it.] +- [Dimension or site]: +- ... + +--- + +## Generalized version (for showcase / public use) + +If this audit will feed a public showcase workup or a published critique, copy the sections above into a generalized form that drops the named-competitor column and the Outliers callouts. Patterns and gaps are publishable; named-and-rated competitor breakdowns are not. The named version stays operated-side. diff --git a/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md b/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md new file mode 100644 index 0000000..8313356 --- /dev/null +++ b/dist/pi/.agents/skills/competitor-experience-audit/references/experience-dimensions-checklist.md @@ -0,0 +1,134 @@ +# Experience Dimensions Checklist + +Score each leading site on each dimension using the observable questions below. Mark `not_assessable` whenever the evidence does not support a judgment; do not guess. The audit's value rests on honest observation. + +The rule for every dimension: name what is observably true across the field, not whether you like it. If you cannot point at a specific observable thing, you are giving taste, not a pattern. + +--- + +## 1. Primary-task prominence + +The visitor arrives with a primary job. The leading sites either lead with that job or bury it. + +- [ ] What is the largest, earliest interactive element on the first viewport? +- [ ] Does that element correspond to the visitor's primary task in the vertical? (Auto-parts: a fitment selector. Hospitality-food: a menu or reservation entry. Inventory-listing: a search or filter. Local-service-booking: a "book now" or service picker.) +- [ ] How many clicks or scrolls from arrival to completing the core task? +- [ ] How many competing CTAs share the hero with the primary task? +- [ ] Is the primary task reachable from a sticky element on scroll? + +Rendered required: partial. The primary task can usually be identified from a static fetch (it is in the markup), but its visual dominance and protection from competitors requires the rendered view. + +--- + +## 2. Layout register and density + +Storefront, editorial, marketing-airy, hybrid. Cross-reference `creative-direction` aesthetic positions (editorial-restrained, polished-standard, controlled-maximalist, expressive-maximalist) for vocabulary. + +- [ ] How many distinct modules appear above the fold on a standard desktop viewport? +- [ ] How many on a mobile viewport? +- [ ] What is the content-per-viewport ratio: dense (a catalog or storefront), calm (an editorial), generous (a landing page or brochure)? +- [ ] Where does the page read as a storefront vs a marketing page? +- [ ] Does the whitespace ratio match a retail or a publication register? + +Rendered required: yes. Static HTML cannot tell you what users see in the first viewport. + +--- + +## 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape. + +- [ ] How many category, collection, or entry-point modules appear before scroll? +- [ ] How is depth signaled (mega-menu hover, fly-out, side rail, faceted search, breadcrumb expansion)? +- [ ] Is the surface flat (one tier visible) or hierarchical (parent plus child)? +- [ ] Are the categories shown as text, icon, image, or hybrid? +- [ ] Is a search-first path offered alongside the category-first path? + +Rendered required: partial. Counts and structure show up in static markup; visual emphasis and reveal patterns need rendering. + +--- + +## 4. Primary navigation and search paths + +The know-what-I-want path and the browse path. Both, or only one. + +- [ ] Is a search input prominent (in the header, large input), secondary (small, in a side panel), or absent? +- [ ] Which paths does the primary nav offer (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience)? +- [ ] Score each available path: primary / secondary / absent. +- [ ] Where does the primary nav sit (top bar, side drawer, mega-menu, sticky)? +- [ ] On mobile, does the primary nav collapse into a hamburger or stay flat? + +Rendered required: partial. Path inventory is in the static markup; visual prominence and primary-vs-secondary judgment needs the rendered view. + +--- + +## 5. Brand register and conviction + +The posture the leading sites take and whether they hold it across the page. + +- [ ] Color palette: muted / saturated; warm / cool; monochrome / multi-hue. +- [ ] Typography: humanist / geometric / serif-led / display-led; one face or paired. +- [ ] Imagery: photographic (studio, lifestyle, editorial); illustrated; abstract; none. +- [ ] Voice in headings: direct, persuasive, technical, warm, plain, institutional. +- [ ] Voice in microcopy and CTAs: matches the heading voice or breaks from it. +- [ ] Brand posture: utilitarian / premium / friendly / institutional / technical / expressive. + +Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; use those terms rather than inventing new ones. + +Rendered required: yes. Brand register is a visual judgment; static HTML alone cannot support it. + +--- + +## 6. Trust and conversion signals + +The recurring conventions a credible commercial page in this vertical carries. + +- [ ] Reviews / ratings present (where, how prominent, count or average shown). +- [ ] Guarantees (return policy, money-back, warranty) surfaced or hidden. +- [ ] Pricing transparency: price visible without interaction; total cost surfaced before checkout; "starting at" or full? +- [ ] Stock or availability signals (in stock, low stock, lead time). +- [ ] Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it). +- [ ] Shipping or service-level promises (ETA, free over $X, same-day). +- [ ] Institutional trust signals (years in business, association badges, certifications). +- [ ] Social proof (logos of customers, press mentions, testimonials). + +Rendered required: partial. Many trust signals are visible in markup; placement and emphasis are rendered judgments. + +--- + +## 7. Recurring vertical conventions (synthesis) + +The patterns that recur across the field define what a credible site in this vertical is expected to have. This is not a new measurement; it is the synthesis of dimensions 1 through 6. + +- [ ] Which conventions appear on 3 of N or more of the leaders? +- [ ] Which appear on fewer than 3 (single-site moves, not conventions)? +- [ ] Which are absent across the field (the gap a positioning opportunity exploits)? + +The output of this dimension is a short list: "If your build does not do X, Y, Z, it will read as off-vertical." That list is what goes into the experience bar. + +--- + +## Scoring rubric + +For each dimension, score the field (not a single site): + +- Pattern present. 3 of N or more leaders converge on a recognizable convention. Name it. +- Mixed. The field splits across two or three distinct approaches. Name each, and note which the new build should adopt. +- Gap. No convention emerges, or every leader misses the dimension. Often this is the positioning opportunity. +- Not assessable. The evidence does not support a judgment. Name what evidence would be needed. + +For each site (operated-side only; the public version drops named scores): + +- Mark each dimension `pattern-aligned`, `outlier`, or `not assessable`. + +--- + +## What this checklist will not do + +- Rate a single site's design taste. Use `design-standards` for production design review. +- Tell you which vertical your build belongs in. The vertical and field are inputs to this skill, not outputs. +- Replace user research. Use `ux-research` and `usability-testing` for real-user assessment. +- Generate creative direction from scratch. Use `creative-direction` and `brand-discovery` for that. +- Produce a SERP or backlink competitive analysis. Use `seo-competitor`. + +This checklist names patterns and gaps so a downstream build has a real bar to meet. Everything else is out of scope. diff --git a/dist/pi/.agents/skills/content-and-copy/SKILL.md b/dist/pi/.agents/skills/content-and-copy/SKILL.md new file mode 100644 index 0000000..e8a1f80 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: content-and-copy +description: "Write or edit website copy, blog content, and editorial pieces with attention to voice, structure, and goal. Use this skill whenever the user wants to write an article, draft website copy, edit existing content for clarity or voice, write a blog post, or produce general editorial content. Triggers on write a blog post, draft an article, write copy for, edit this, rewrite this, write content, write a guide, draft a how-to, write web copy. Also triggers when content has been outlined and now needs to be written, or when existing content needs voice or clarity edits." +category: content +catalog_summary: "Website copy, blog content, content production frameworks" +display_order: 3 +--- + +# Content and Copy + +Write or edit content that serves a specific reader and goal. Stack-agnostic. This skill is for general content production. Specialized skills exist for landing pages (`landing-page-copy`) and email (`email-sequences`). + +--- + +## When to use + +- Writing a blog post or article +- Drafting website copy (homepage sections, about, services) +- Editing existing content for voice or clarity +- Writing how-to guides, listicles, or explainers +- Producing knowledge base or help center articles +- Adapting brand voice to a specific piece + +## When NOT to use + +- Landing pages with conversion goals (use `landing-page-copy`) +- Email campaigns or sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- SEO keyword research (use `seo-keyword`) +- Content strategy and planning (use `content-strategy`) + +--- + +## Required inputs + +- The piece to be written or edited +- The target reader (specific audience segment) +- The goal of the piece (inform, convert, rank, retain, entertain) +- The brand voice (or willingness to define it) +- Length target and any structural constraints + +If brand voice is undefined, run `brand-voice` first or use a working voice and document it as you go. + +--- + +## The framework: 5 dimensions + +Strong content is strong on all five. Weakness on any one drags the rest down. + +### 1. Hook + +The opening earns the read. Most readers decide whether to continue within 3 to 5 seconds. + +Strong hooks do one of: + +- Promise specific value. "By the end, you'll know exactly which X to pick for your situation." +- Surface a tension. "Most advice on X is wrong. Here's why." +- Open a loop. A question or scenario the rest of the piece resolves. +- State a contrarian point. Provided you can defend it. +- Show, don't summarize. A specific moment or scenario the reader recognizes. + +Weak hooks: + +- Throat-clearing ("In today's fast-paced world...") +- Dictionary-definition openers ("X is a type of Y that...") +- Stating the obvious ("Many people struggle with X.") +- Vague promises ("This article will explore X.") + +### 2. Structure + +The reader follows the flow without effort. + +Common structures: + +- Problem → Solution → Proof. Most non-fiction. +- List + reasoning. Listicles with substance, not filler. +- How-to (numbered steps). Procedural content. +- Compare → Contrast → Recommend. Comparison and review content. +- Story → Lesson. Narrative non-fiction. +- Question → Answer → Implication. Explainers and analysis. + +Pick a structure. Stick to it. Most weak content fails because the writer drifted between structures. + +### 3. Voice + +The piece sounds like the brand. + +- Voice attributes consistent throughout (per `brand-voice` definition) +- Tone shifts appropriately for context (a serious topic gets a serious tone, even from a playful brand) +- Vocabulary preferences honored +- Grammar and style standards followed (contractions, em dashes, sentence length) +- Reads aloud like the brand would actually talk + +Test: Read a paragraph aloud. Does it sound like the brand? If it sounds like AI, generic marketing, or someone else's voice, edit until it doesn't. + +### 4. Substance + +The piece earns its length. Every paragraph adds something. + +Substance comes from: + +- Specifics. "Roughly 40 percent" beats "many." Names, numbers, examples, data. +- Original perspective. Your take, not a summary of everyone else's. +- Actionable detail. What the reader does with this information. +- Honest tradeoffs. What's NOT true, what doesn't work, what's overhyped. +- Real examples. Specific scenarios, real customers, real failures. + +Lack of substance shows up as: + +- Padding ("It's important to note that...") +- Restating the same point in three different paragraphs +- Generalities that anyone in the category could write +- Word counts hit by stretching, not depth + +### 5. Closing + +The piece ends with intention. + +Strong closings: + +- Resolve the loop opened in the hook. +- Issue a specific next action. What does the reader do now? +- Land a memorable line. Something quotable. +- Return to the opening. Echo or invert the first line. + +Weak closings: + +- Summary that restates the article +- "Hope this helps!" or equivalent +- A wall of CTAs from unrelated programs +- Trailing off with no clear ending + +--- + +## Workflow + +### For new pieces + +1. Confirm the brief. Reader, goal, length, voice. If the brief is vague, do not write yet. +2. Outline. Structure first. Headlines and section purposes only. Skip prose until the structure is sound. +3. Open with the hook. Write the opening before anything else. If the hook isn't working, the rest won't either. +4. Draft for substance. First draft is about getting the substance down. Voice comes in editing. +5. Edit for voice. Read aloud. Tighten sentences. Cut padding. Apply brand voice. +6. Edit for clarity. Each paragraph: does it earn its place? Each sentence: is the meaning unambiguous? +7. Pre-publish checks. Headers in order, no skipped levels, internal links present, image alt text written, SEO basics applied (title, meta, slug). + +### For editing existing content + +1. Read the whole piece first. Do not edit on first read. Understand it before changing it. +2. Identify what's working. Note the strong sections so you don't damage them. +3. Identify what's broken. Voice mismatches, weak structure, vague claims, padding. +4. Edit by priority. Structure first (move sections, cut sections). Then substance (strengthen claims). Then voice. Then sentence-level polish. +5. Read aloud. Catch awkward phrasing the eye misses. + +--- + +## Failure patterns + +- Writing without a brief. Without reader, goal, and voice defined, the piece drifts. +- Burying the lead. The most important thing is in paragraph 8 because the writer "got there." +- Padding to hit word count. Length should serve the reader, not the production schedule. +- Generic voice. Sounds like every other article in the category. Brand voice neutralized. +- Weak transitions. Sections feel disconnected. Reader has to do the work the writer should have done. +- No closing. The piece runs out instead of ending. +- Edit by adding. Fixing weak content by piling on more words. Strong editing usually cuts. +- Ignoring the headers. Headers carry navigation weight. Bad headers fail readers who scan. + +--- + +## Output format + +Default output is a markdown document at `[content-slug].md` ready to import into the CMS. + +Structure: +```markdown +# [H1: matches the title or tightly paraphrases] + +[Hook paragraph. Earns the read in 3 to 5 seconds.] + +[Body content with H2 sections, H3 subsections where useful.] + +## [H2 section heading - descriptive, not clever] + +[Section content.] + +### [H3 if needed] + +[Subsection content.] + +## [H2 section heading] + +[Section content.] + +## [Closing section] + +[Closing that resolves and points to next action.] +``` + +Front-matter for SEO and CMS: +```yaml +--- +title: [SEO title, 50 to 60 chars] +description: [Meta description, 120 to 160 chars] +slug: [url-slug] +author: [author] +date: [YYYY-MM-DD] +last_updated: [YYYY-MM-DD] +tags: [tag1, tag2] +category: [category] +--- +``` + +--- + +## Reference files + +- [`references/content-brief-template.md`](references/content-brief-template.md) - The brief that should exist before any content is written. +- [`references/content-edit-checklist.md`](references/content-edit-checklist.md) - Pre-publish editing checklist. diff --git a/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md b/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md new file mode 100644 index 0000000..d1bc428 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/references/content-brief-template.md @@ -0,0 +1,242 @@ +# Content Brief Template + +Every piece of content needs a brief before writing. Without one, the piece will drift, miss the audience, or fail the goal. + +A brief takes 15 minutes to write. Saves hours of rewrites later. + +--- + +## Template + +```markdown +# Brief: [Working title] + +## Reader + +Who specifically is this for? Be precise. + +- Primary audience segment: [from content strategy] +- What they currently know: [their starting point] +- What they want to know: [the question they're bringing] +- What they need to do after: [the action this enables] + +## Goal + +What does this piece accomplish? + +- Primary goal: [Inform / Convert / Rank / Retain / Entertain] +- Specific outcome: [What measurable thing should happen] +- Success metric: [How we know it worked] + +## Pillar / Strategy fit + +- Content pillar this serves: [from content strategy] +- Cornerstone or supporting: [Cornerstone / Supporting] +- Internal links to / from: [related pieces] + +## Angle + +What's the take? Why does this piece exist when others on the topic already do? + +- The angle: [One sentence] +- Why ours is different: [Specific differentiator] +- The contrarian or surprising element: [If any] + +## Format + +- Type: [Article / Guide / Listicle / Comparison / Case study / How-to / Tutorial / Explainer] +- Length: [Word count or range] +- Reading level: [Beginner / Intermediate / Advanced] +- Required elements: [Images, tables, video, downloads, code blocks] + +## Structure + +Section-by-section outline. Headlines + 1 sentence on what each section does. + +### [H1: Working title] + +[Hook approach: how the piece will earn the read in 3 to 5 seconds] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Closing section] +[How the piece resolves and what action it points to] + +## Voice + +- Apply: [Brand voice attributes] +- Tone for this piece: [How tone adjusts for the topic] +- Specific cues: [Anything to lean into or avoid for this topic] + +## Sources and citations + +- Required sources: [Specific data, studies, or experts to cite] +- Internal data: [Anything we have that competitors don't] +- Quotes from: [SMEs, customers, founders to include] + +## SEO + +- Primary keyword: [from keyword research] +- Secondary keywords: [supporting terms] +- Search intent: [Informational / Commercial / Transactional / Navigational] +- Target SERP feature (if any): [Featured snippet / People also ask / etc.] +- Title tag (50-60 chars): [Draft] +- Meta description (120-160 chars): [Draft] +- URL slug: [Draft] + +## Distribution + +Where and how this piece gets seen after publishing. + +- Newsletter inclusion: [Yes/No] +- Social posts: [Number of variations and channels] +- Outreach: [Specific people or sites to ping] +- Internal links to add from: [Existing pieces that should link to this] + +## Constraints and notes + +- Deadline: [Date] +- Word count: [Target] +- Required approvals: [Who needs to sign off] +- Things to avoid: [Anything off-limits for this piece] + +## Out of scope + +What this piece is explicitly NOT about. Prevents scope creep during writing. + +- [Topic not in this piece] +- [Topic not in this piece] +``` + +--- + +## Filled example + +```markdown +# Brief: How to choose between SQL and NoSQL for a startup + +## Reader + +- Primary audience segment: Technical founders or first engineers at early-stage startups (under 20 employees) +- What they currently know: Basics of databases, used both SQL and NoSQL casually +- What they want to know: Which to pick for their specific situation, what they'll regret in 18 months +- What they need to do after: Make the database choice and feel confident enough to commit + +## Goal + +- Primary goal: Inform (with rank as a secondary) +- Specific outcome: Reader makes the decision and references this piece when others ask +- Success metric: Top 3 ranking on "SQL vs NoSQL for startups" within 6 months; 5+ minute average read time + +## Pillar / Strategy fit + +- Content pillar: Startup engineering decisions +- Cornerstone or supporting: Cornerstone for the pillar +- Internal links: from "Founder's guide to technical debt" and to "When to migrate your database" + +## Angle + +- The angle: Most articles compare SQL and NoSQL on technical features. We compare on regret-likelihood at 18 months in production. +- Why ours is different: Built around real failure modes, not theoretical capabilities +- Surprising element: Most startups regret choosing NoSQL for the wrong reasons, not the right ones + +## Format + +- Type: Long-form decision guide +- Length: 2,500 to 3,500 words +- Reading level: Intermediate +- Required elements: Decision flowchart, 2-3 case examples, comparison table + +## Structure + +### H1: How to choose between SQL and NoSQL for a startup + +Hook: Open with a specific founder's regret moment from a real conversation. + +### H2: The wrong question (and the right one) +Most teams ask "which is faster" or "which scales." Reframe to "what will I regret in 18 months." + +### H2: When SQL is the right call +Specific scenarios with examples. + +### H2: When NoSQL is the right call +Narrower scenarios than most articles claim. + +### H2: The hybrid that works +Real-world pattern: SQL primary, targeted NoSQL for specific use cases. + +### H2: A decision flowchart +The actionable diagram. The piece's main asset. + +### H2: What to do if you've already chosen wrong +Migration realism, with specific signals it's time to switch. + +### H2: Closing +Return to the opening founder. Where they ended up. The decision framework as the takeaway. + +## Voice + +- Apply: Direct, experienced, not-academic +- Tone: Slightly weary about industry overcomplication +- Specific cues: First-person plural ("we"), war-story examples preferred over textbook explanations + +## Sources + +- Internal: Conversations with [N] startup CTOs +- External: [List of specific studies, posts, papers] +- Quotes: [Names if any] + +## SEO + +- Primary keyword: SQL vs NoSQL startup +- Secondary: SQL vs NoSQL for small teams, when to use NoSQL, NoSQL mistakes startups +- Search intent: Informational with commercial undertone +- Target SERP feature: Featured snippet for "when to use NoSQL" +- Title tag: SQL vs NoSQL for Startups: How to Avoid 18-Month Regret +- Meta: A practical guide to picking a database when you're 5 engineers, deciding fast, and don't want to migrate twice. Includes a decision flowchart. +- URL slug: sql-vs-nosql-startup + +## Distribution + +- Newsletter: Feature in next issue +- Social: 3 LinkedIn variations, 1 X thread +- Outreach: Email to 5 startup engineering newsletter writers +- Internal links: Add from /resources/cto-decisions and /technical-debt-guide + +## Constraints + +- Deadline: [Date] +- Word count: 3,000 target +- Approvals: Editorial lead and one technical SME +- Avoid: Vendor-specific recommendations (we're not selling a product) + +## Out of scope + +- Specific NoSQL database comparisons (CouchDB vs MongoDB) - separate piece +- Schema design tutorials - separate piece +- ORM choice - separate piece +``` + +--- + +## When to skip the brief + +The brief is required for: +- Cornerstone content +- Anything over 1500 words +- Anything with a conversion goal +- Anything written by someone other than the editorial lead + +The brief can be lighter for: +- Short newsletter blurbs +- Social posts +- Pieces written by the editorial lead with the strategy fully internalized + +But "lighter" is not "absent." Even a 100-word note covering reader / goal / angle saves time. diff --git a/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md b/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md new file mode 100644 index 0000000..4e1f906 --- /dev/null +++ b/dist/pi/.agents/skills/content-and-copy/references/content-edit-checklist.md @@ -0,0 +1,147 @@ +# Content Edit Checklist + +A pre-publish checklist for editing content. Run it line by line before any piece of content goes live. + +The checklist catches the regular mistakes. Editing for substance is a separate pass. + +--- + +## Pass 1: substance + +Before sweating commas, confirm the piece does its job. + +- [ ] The brief is satisfied. Re-read the content brief. Does this piece deliver against every objective? +- [ ] The audience is the right one. Who is the reader? Are they assumed correctly? +- [ ] The single takeaway is clear. If a reader skims and remembers one thing, what is it? Is it what we wanted? +- [ ] The first 50 words earn the next 50. Cut throat-clearing intros. Get to the point. +- [ ] Every paragraph earns its place. If a paragraph could be removed without loss, remove it. +- [ ] The structure serves the reader. Headers form a meaningful outline. Skim test passes. +- [ ] There is one CTA per piece, and it is unmissable. Or zero, if the piece is purely informational. +- [ ] No claim is unsupported. Every fact, statistic, or assertion has a source or is hedged. +- [ ] Examples are concrete. Specific numbers, named scenarios, real artifacts beat vague "many users" generalizations. + +--- + +## Pass 2: voice and tone + +- [ ] Voice matches the brand voice document. Read aloud. If a stranger could not place this as our brand, voice is too generic. +- [ ] Tone matches the context. Promotional vs editorial vs technical vs support. Different content, different tone shifts. +- [ ] Pronouns are consistent. "You" / "we" / "our" stay stable across the piece. +- [ ] No internal voice leaked into customer-facing copy. Jargon, project names, internal team names removed. +- [ ] No first-person commentary in instructional content. ("I think you should..." → "Do this because...") + +--- + +## Pass 3: structure and scannability + +- [ ] Headings are descriptive, not clever. "How to add a payment method" beats "Money matters." +- [ ] Heading hierarchy is correct. One H1, then H2s for top-level sections, H3s under H2s. No skipping levels. +- [ ] Paragraphs are tight. Default 2-4 sentences per paragraph for web. One-sentence paragraphs are allowed for emphasis. +- [ ] Lists are used where they fit. Bullets for parallel items, numbered for sequenced steps. +- [ ] Bold and italic used sparingly. Bold for the term being defined, italic for emphasis. Not both. Not often. +- [ ] Code blocks for code. Inline code for short references. +- [ ] Tables for tabular data. Not for layout. + +--- + +## Pass 4: clarity at the sentence level + +- [ ] Active voice by default. Passive voice for specific reasons (focus on object, unknown actor, polite distancing). +- [ ] Concrete nouns and verbs. "We process" beats "processing is performed by us." +- [ ] Average sentence length under 20 words. Vary the rhythm with shorter sentences for emphasis. +- [ ] No nominalizations. "Decide" beats "make a decision." "Implement" beats "carry out the implementation of." +- [ ] No throat-clearing phrases. Cut "It is important to note that," "In order to," "At the end of the day." +- [ ] No filler intensifiers. Cut "very," "really," "quite," "actually," "basically." Each weakens the word it modifies. +- [ ] No hedge words where you mean something specific. "May," "might," "could" are honest when uncertain, weak when specific. + +--- + +## Pass 5: jargon and accessibility + +- [ ] Jargon defined on first use. Or replaced if the audience would not know it. +- [ ] Acronyms spelled out on first use. Then acronym is fine. +- [ ] No insider language. Project codenames, internal team references, deprecated product names. +- [ ] Idioms checked for global audiences. "Hit it out of the park" reads strange to non-US English readers. +- [ ] Reading level appropriate. Use a tool (Hemingway, Readable) to spot-check. For most audiences, target Grade 8-10. +- [ ] No ableist or exclusionary language. "Crazy" → "wild," "blacklist" → "blocklist," gendered defaults checked. + +--- + +## Pass 6: SEO basics + +If the piece is for organic search: + +- [ ] Primary query target identified. One phrase per piece. +- [ ] Title tag drafted. Distinct from H1, 50-60 characters, primary query near front. +- [ ] Meta description drafted. 140-160 characters, value-led, includes primary query naturally. +- [ ] H1 is unique on the site and includes the primary query. +- [ ] Internal links added. 2-5 contextual links to related content on the site. +- [ ] External links added. Link out where it adds value or substantiates a claim. +- [ ] Images have descriptive alt text. Decorative images get `alt=""`. +- [ ] URL slug is short, lowercase, hyphenated, includes primary query. +- [ ] Schema considered. Article, FAQ, HowTo, etc. - whichever fits the format. + +--- + +## Pass 7: facts and claims + +- [ ] Numbers verified. Especially statistics, dates, prices, version numbers. +- [ ] Names spelled correctly. People, products, companies, places. +- [ ] Quotes verified verbatim. Speaker name, attribution, context correct. +- [ ] Dates checked. "Last updated" reflects the actual edit date. +- [ ] Links work and go where they say. No 404s, no redirect chains, no link rot to dead resources. +- [ ] Screenshots are current. Older screenshots show outdated UI; refresh or remove. +- [ ] Claims about competitors are fair and current. Or removed. + +--- + +## Pass 8: legal and compliance + +- [ ] Trademarked terms used correctly. Capitalization, ™ or ® where required by license. +- [ ] Disclaimers present where needed. Affiliate disclosures, regulated industry disclaimers, advisory caveats. +- [ ] Customer permissions secured for testimonials. Case studies, quotes, photos. +- [ ] No confidential or pre-announcement information. Product roadmaps, unannounced pricing, internal team names. +- [ ] Image rights clear. Licensed stock, original photography, or in-house illustration. + +--- + +## Pass 9: cross-channel consistency + +If the piece appears in more than one place: + +- [ ] Web vs email vs social variants align in message. Tone may shift; substance does not contradict. +- [ ] Excerpts and meta descriptions match the piece. No bait-and-switch. +- [ ] CTAs point to current destinations. Landing page is live, has matching messaging, is not stale. + +--- + +## Pass 10: final mechanical sweep + +- [ ] Spellcheck. Twice. Once with autocorrect off so it does not silently fix names. +- [ ] Grammar check. Tool-assisted, then human-verified. +- [ ] Punctuation consistent. Oxford comma, smart quotes, dashes - per the style guide. +- [ ] No double spaces. Find-and-replace. +- [ ] No trailing whitespace at line ends. +- [ ] No placeholder text left in. "Lorem ipsum," "TBD," "[INSERT QUOTE]," "TKTK." +- [ ] No commented-out drafts in the source. Especially in CMS HTML view. + +--- + +## Sign-off + +\| Pass \| Editor \| Date \| +\|---\|---\|---\| +\| Substance \| \| \| +\| Voice and tone \| \| \| +\| Structure \| \| \| +\| Sentence-level \| \| \| +\| Jargon and accessibility \| \| \| +\| SEO \| \| \| +\| Facts and claims \| \| \| +\| Legal and compliance \| \| \| +\| Cross-channel \| \| \| +\| Mechanical \| \| \| + +Final approval: [Name, date] + +Ready to publish: [ ] diff --git a/dist/pi/.agents/skills/content-brief-authoring/SKILL.md b/dist/pi/.agents/skills/content-brief-authoring/SKILL.md new file mode 100644 index 0000000..85733df --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/SKILL.md @@ -0,0 +1,252 @@ +--- +name: content-brief-authoring +description: "How to author a content brief that actually guides a writer (human or AI) to produce a piece that ranks, converts, or both. Per-piece editorial brief: target keyword and cluster, search intent, audience and JTBD, heading structure, entity coverage for AEO/GEO, internal linking strategy, success criteria. The middle path between thin briefs (a keyword and a deadline) and thick briefs (a 4-page document nobody reads). Triggers on content brief, brief the writer, brief the article, brief authoring, content brief template, brief audit, per-piece brief, editorial brief, target keyword brief, search intent brief. Also triggers when briefing a human writer or an AI agent on a single content piece." +category: content +catalog_summary: "Per-piece editorial brief: target keyword, intent, audience, outline, entity coverage, internal linking, success criteria, and the discipline that distinguishes useful briefs from bloat" +display_order: 2 +--- + +# Content Brief Authoring + +A senior content strategist's playbook for authoring per-piece content briefs that actually guide writers to produce content worth publishing. + +Most content briefs are some flavor of broken. The thin version is a keyword, a word count, and a deadline; the writer fills in everything else from scratch and the output is generic. The thick version is a 4-page document nobody reads, that the writer skims for the headline and the outline and ignores the rest. Either way, the brief failed at its job: making the writer's work easier and the output more predictable. + +This skill is the middle path. It defines the 12 fields that earn their keep in a content brief, the fields that bloat without helping, and the discipline of writing briefs that route a writer (human or AI) toward a content piece that ranks for its target keyword, gets cited by AI engines, converts the right reader, or whatever the success criteria say. It assumes you have decided what to write (see `content-strategy` for program-level decisions) and now you are briefing each piece. The piece itself gets written separately (see `content-and-copy`). + +When to use this skill: briefing a writer (human or AI) on an individual content piece, auditing existing briefs that are not producing good content, building a brief template for a content program, or running a brief-generation pipeline through Frase, AirOps, or another tool. + +--- + +## What this skill is for + +This skill spans the per-piece editorial brief discipline. It composes with three sister skills, and the distinction between them is what keeps each one sharp. + +- `creative-brief` is a project brief. It bridges discovery to execution at the project level: a new website, app, brand, or campaign. Audience, goals, scope, success at project scope. +- `content-strategy` is a program-level editorial strategy. Pillars, calendar, topic clusters, governance. What to produce across a quarter or a year. +- `content-and-copy` is the writing itself. Voice, structure, edit pass, tone calibration. Execution scope for general editorial. +- This skill is the per-piece brief between `content-strategy` (program decided) and `content-and-copy` (piece gets written). It briefs a single content artifact: keyword, intent, audience, outline, entities, success criteria. + +The clean reading order: `content-strategy` decides what to produce; this skill briefs each piece; `content-and-copy` writes it. If the team is briefing a redesign or a new brand build, that is `creative-brief`, not this skill. + +The audience: content strategists, SEO content marketers, editorial leads, content ops managers, agencies running content programs at scale, and any PM or marketer briefing a writer (human or AI). The voice is senior content strategist to junior content marketer. Specific, opinionated, honest about what makes a brief useful versus useless. + +--- + +## Thin vs thick vs effective briefs + +The keystone distinction. Three concrete shapes. + +Thin brief. Keyword, word count target, deadline. Maybe a one-line summary of the angle. The writer fills in everything else from scratch. Output is generic, drifts off-topic, does not rank, and does not convert. The cost is the rewrite cycle: editor spends two hours rewriting because the writer chose the wrong intent, the wrong audience, or the wrong outline. + +Thick brief. A 4-page document with executive summary, brand-guidelines refresher, comprehensive competitive analysis, voice guidelines, plus the actual brief somewhere in the middle. The writer skims for the outline, ignores the rest. Output is not materially better than from a thin brief because the writer never read most of the document. The cost is the authoring time: the strategist spends three hours producing pages of context the writer will never absorb. + +Effective brief. One to two pages. Every field earns its keep. Writer reads all of it because there is no fluff. Output is predictable enough that the editor does not have to rewrite the lede. The cost is the discipline of cutting fields that do not change writer behavior. + +The discipline. Every field in the brief has a job. If you can remove the field without degrading the output, remove it. The brief is the contract between editorial leader and writer; vague contracts produce vague output, overstuffed contracts produce output that reflects only the parts the writer read. + +Most briefs that are not working are thin, not thick. The instinct to add more usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +--- + +## The 12 fields of an effective brief + +A useful brief has 12 fields. Skip any of them and the writer fills the gap from priors; the gap is where output drifts. + +1. Target keyword + supporting cluster. Primary keyword plus 3 to 5 supporting keywords from the same cluster. The cluster is what tells the writer the topic has range; the primary is what the piece optimizes for. +2. Search intent classification. Informational, navigational, commercial, or transactional. Plus the dominant SERP format check (article, listicle, comparison, video, tool). The intent decides what kind of piece this is; the format decides the shape. +3. Target audience. Specific role and sophistication level. Not "anyone interested in X." A senior data engineer at a 500-person SaaS company is a target; "data people" is not. +4. Job to be done. The problem the reader is trying to solve when they land on the piece. One sentence. Specific. +5. Word count / depth target. Calibrated to the SERP, not to a content quota. If the top 10 are all 1,200 words, briefing 3,000 wastes effort; if the top 10 are all 4,000 words, briefing 1,500 produces a piece that cannot rank. +6. Heading structure outline. H2s and H3s explicit, ordered logically. The outline is where the writer reads the brief most carefully; spend time here. +7. Required entities, statistics, citations. For AEO and GEO, the named tools, methods, experts, and statistics the piece must cover. The entity gap is the agent's prioritization signal. +8. Internal linking strategy. 3 to 5 pages this piece should link out to with anchor text; 1 to 3 existing pages that should link back to this piece after publish. +9. External proof points. Required citations, sources, expert quotes. Not optional. +10. Anti-patterns. What not to do. Off-topic tangents the writer might wander into, off-brand voice, AI clichés the brief explicitly forbids by listing them in a do-not-use list (the standard set of overused corporate-speak adjectives, throat-clearing openers, and verbs that signal AI generation). +11. Success criteria. What good looks like. Rank for the target keyword in 90 days. Get cited by ChatGPT for the cluster within 60 days. Drive 50 trial signups in the first 30 days. Measurable, time-bound, tied to the program goal. +12. Author voice and tone reference. Link to the brand-voice guide. If the piece needs a tone shift from the default voice, note it here in one sentence. + +The fields that do not earn their keep, and should be omitted from briefs unless the writer is brand new to the program: + +- Long executive summary (the brief itself is the executive summary) +- Brand-guidelines refresher (link to it; do not repeat) +- Comprehensive competitive landscape (link to research; do not dump) +- Brief history of the publication, company, or brand (irrelevant to this piece) + +Detail and templates per content type in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## Search intent classification + +The four standard intents: + +- Informational. The reader wants to learn. SERP usually shows articles, guides, explainers. +- Navigational. The reader wants a specific brand or page. SERP usually shows the brand site at #1; ranking against navigational intent is mostly impossible unless you are the brand. +- Commercial. The reader is researching a purchase. SERP usually shows comparisons, reviews, "best X" listicles. +- Transactional. The reader is ready to buy. SERP usually shows product pages, pricing pages, signup flows. + +The dominant SERP format check. After classifying intent, scan the SERP top 10 and tag the dominant format: article, listicle, comparison, video, tool, hybrid. The dominant format tells you the shape of the piece, which is more decisive than the intent label. + +The override pattern. When the intent feels informational but the SERP shows mostly listicles, write the listicle. When the intent feels commercial but the SERP shows mostly long-form articles, write the article. The SERP is the source of truth, not your priors. Rankings come from matching the SERP's accepted shape; deviating costs ranking. + +The AEO/GEO consideration. AI engines tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. Mismatched format is a citation risk in addition to a ranking risk. + +Detail in [`references/search-intent-classification.md`](references/search-intent-classification.md). + +--- + +## Heading structure design + +Heading hierarchy patterns the brief should specify: + +- H2 sections that match common follow-up questions for the keyword. The reader's mental model is a series of questions; the H2s answer them in order. +- H3s under H2s only when they add navigational value. No orphan H3s. No H2-H3-H4 cascades that nobody scrolls through. +- Featured snippet bait pattern: a 40 to 60 word answer paragraph immediately following an H2 question. Google often pulls this paragraph as the snippet; AI engines often quote it as the citation. +- H2 ordering that matches the reader's mental model, not the writer's enthusiasm. Put the obvious answer first; the writer's clever angle goes in H2 #4, not H2 #1. + +Anti-patterns the brief should explicitly forbid: + +- H2s that all start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. +- Buried lede: H2 #4 has the actual answer. The reader bounced at H2 #2. +- Section length wildly uneven: H2 #1 is 1,500 words, H2 #2 is 80 words. The 80-word section reads as a placeholder. + +Detail in [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md). + +--- + +## Entity coverage for AEO and GEO + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that mentions the entities the SERP top-ranking pages mention, includes specific statistics with sources, contains citation-formatted proof points, and demonstrates topical depth via entity coverage. + +The entity discovery pattern, run before briefing the piece: + +1. Pull SERP top 10 for the target keyword. +2. Identify entities mentioned across multiple pages: named tools, named methods, named experts, named data sources, named statistics. +3. Identify entities mentioned by 1 to 2 pages but not in your existing content. This is the entity gap. +4. Add the gap entities to the brief as required coverage. + +The brief lists the entities the writer must mention, with light context on why each matters. The writer is not expected to research each entity from scratch; the brief includes a one-line note ("CUPED is the variance-reduction technique used by data-warehouse-experimentation teams; mention in the methodology section") so the writer can integrate without breaking flow. + +Tools that automate this: Frase has entity-gap analysis built in; AirOps composes the same analysis through its workflow builder; Surfer SEO ships entity coverage scoring. The skill is tool-agnostic; the workflow is what matters. + +Detail in [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md). + +--- + +## Internal linking strategy + +The brief should specify two link directions: + +- Outbound from this piece. 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer should not be deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. +- Inbound to this piece, post-publish. 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +The orphan-content failure mode: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. Prevented by upstream-link planning in the brief. + +The self-cannibalization check: if this piece would compete with an existing piece for the same keyword cluster, the brief flags it explicitly. The options are consolidate (merge into the existing piece), differentiate (the brief sharpens the angle so the two do not compete), or kill one. Flagging late, after the piece is written, costs more than flagging in the brief. + +Detail in [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md). + +--- + +## Brief templates by content type + +Different content types call for different brief shapes. The 12 fields are constant; the weight of each field shifts. + +- Pillar piece. Comprehensive coverage of a topic, 3,000 words plus, anchors a topic cluster. Brief emphasizes structure, comprehensiveness, internal links to and from supporting pieces. +- Supporting / cluster piece. Narrower topic, 1,000 to 2,000 words, links up to the pillar. Brief emphasizes specificity, single-question scope. +- Comparison piece (X vs Y). Commercial intent, structured comparison, decision framework. Brief emphasizes objectivity (or honest positioning if the brand is one of X or Y), table structure, "when X wins" / "when Y wins" framing. +- Listicle. Informational or commercial intent, scannable, ranked or unranked. Brief emphasizes selection criteria, ordering rationale, depth-per-item. +- How-to guide. Informational, step-by-step, screenshots. Brief emphasizes step granularity, prerequisites, troubleshooting section. +- Thought leadership / opinion. Commercial or branding, distinctive POV, signal of expertise. Brief emphasizes thesis, supporting arguments, anticipated counter-arguments. + +Each template gets a worked example in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## The brief-to-writer handoff + +Whether the writer is human or AI, the handoff has the same shape. + +- Brief delivered with all 12 fields populated. +- Writer asks clarifying questions before drafting (or the AI agent surfaces ambiguities in the brief as the first response). +- Writer or agent acknowledges the success criteria explicitly. +- First draft references the brief: "this draft hits 4 of the 5 required entities; the 5th is missing because the SERP coverage was thin and I could not find a reliable source." +- Editor reviews against the brief, not against personal taste. "The brief said X; the draft did Y" is the review framing. + +For AI handoff specifically, the brief becomes a structured prompt or a tool input. Frase, AirOps, and similar tools structure briefs as YAML or JSON for machine consumption; the same 12 fields apply. The structured format is the only difference; the contract is the same. + +Detail in [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md). + +--- + +## Brief governance + +Versioning. Every brief has a version. Significant changes (target keyword change, audience shift, scope expansion) bump the version; cosmetic edits do not. The writer always works from the current version, not a stale draft pasted into Slack three weeks ago. + +Approval. The brief approver is the editorial owner of the content program. Single approver, not a committee. The approver is also the editor on the back end, so the same person is responsible for both the contract and the review. Splitting these roles is how briefs and reviews drift apart. + +Archival. After publish, the brief is archived alongside the content piece (Notion database row, dbt model, content management system metadata, whatever the team's source of truth is). Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, a content audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +Detail in [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses and fixes in [`references/common-brief-failures.md`](references/common-brief-failures.md). + +- "The brief was too thin." Fill all 12 fields or accept generic output. +- "The brief was too thick." Every field needs a job; remove the rest. +- "The writer ignored the brief." Anchor success criteria to the brief; review against the brief. +- "The brief had the wrong target keyword." SERP-validate before briefing. +- "The piece does not match the SERP intent." SERP intent override applies; do not write an article when the SERP wants a listicle. +- "The piece has no internal links." Internal linking belongs in the brief, not as an afterthought. +- "The piece is generic; could have been written about anything." Entity coverage and POV missing from brief. +- "The brief is comprehensive but the piece does not rank." Brief was right; SERP was harder than expected; iterate based on real performance, not by adding fields to the brief. +- "We never went back to evaluate." Success criteria measured 30 / 60 / 90 days post-publish. +- "Different writers produce wildly different output from the same brief." Brief was actually too vague; tighten anti-patterns and voice notes. + +--- + +## The framework: 12 considerations for brief authoring + +When authoring or auditing a content brief, walk these 12 considerations. + +1. Target keyword + cluster. Primary plus 3 to 5 supporting. +2. Search intent + dominant SERP format. Match the SERP, not your priors. +3. Target audience + JTBD. Specific role and problem, not "anyone interested in X." +4. Word count calibrated to SERP. Not to a content quota. +5. Heading structure. Explicit H2s and H3s, ordered to match reader mental model. +6. Entity coverage. Entities the SERP top 10 mention; gap entities added explicitly. +7. Internal linking. 3 to 5 outbound links specified; 1 to 3 inbound updates queued. +8. External proof points. Citations and sources required. +9. Anti-patterns. What not to do, including AI clichés and off-brand voice. +10. Success criteria. Measurable, time-bound, tied to original program goals. +11. Brief versioning + approval. Single approver; version bumps for material changes. +12. Brief stays under 2 pages. Every field earns its keep; remove fields that do not. + +The output of the framework is a brief document the writer can absorb in 5 minutes and execute against in the next 5 hours. + +--- + +## Reference files + +- [`references/brief-templates.md`](references/brief-templates.md) - Pillar, supporting, comparison, listicle, how-to, and thought-leadership brief templates with field-weight notes per type. +- [`references/search-intent-classification.md`](references/search-intent-classification.md) - Four-intent framework, SERP format check, override patterns. +- [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md) - H2 and H3 patterns, featured snippet bait, anti-patterns. +- [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md) - Entity discovery from SERP, gap analysis, AEO/GEO citation drivers. +- [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md) - Outbound and inbound linking patterns, orphan prevention, self-cannibalization check. +- [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md) - Human-writer handoff, AI-agent handoff, success-criteria anchoring. +- [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md) - Versioning, approval, archival, audit trail. +- [`references/common-brief-failures.md`](references/common-brief-failures.md) - Ten-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: the brief is the contract + +A content brief is the contract between editorial leader and writer. If the contract is vague, the output is vague. If the contract is overstuffed, the output reflects only the parts the writer read. The discipline is writing contracts the writer can absorb in 5 minutes and execute against in the next 5 hours; that is the entire job. + +Most briefs that are not working are thin, not thick. The instinct to add more pages usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +When in doubt about whether a brief is ready, ask: are all 12 fields populated, do they each earn their keep, is the SERP intent matched, are the entities listed, are the internal links specified, is the success criteria measurable, and is the document under 2 pages? If yes to all of those, ship the brief and let the writer work. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md b/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md new file mode 100644 index 0000000..725b669 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/brief-governance-patterns.md @@ -0,0 +1,104 @@ +# Brief governance patterns + +Versioning, single-approver, archival alongside the published piece, audit trail. + +--- + +## Versioning + +Every brief has a version. Significant changes bump the version; cosmetic edits do not. + +Version-bump triggers: +- Target keyword change (the piece is now optimizing for a different keyword) +- Audience shift (the JTBD has changed) +- Scope expansion or contraction (word count target moves by 50%+; new H2s added or removed) +- Success criteria change (the metric the piece is being measured against shifts) + +No version bump for: +- Typo fixes +- Anchor text adjustments on internal links +- Adding a sentence of clarification to an existing field +- Reformatting + +The writer always works from the current version. If a writer is mid-draft when the brief bumps from v2 to v3, the strategist tells the writer immediately and decides whether to restart, integrate the changes, or freeze the v2 draft. + +The brief has a version field at the top: `brief_version: 3`. The version is the contract identifier. + +--- + +## Single approver + +The brief approver is the editorial owner of the content program. Single approver, not a committee. + +Why single approver: +- A committee bog dilutes the brief. Each member adds a field; nobody removes fields. The brief grows from 1 page to 4 pages and stops being readable. +- A committee splits accountability. When the published piece misses, no single person owns the brief that produced it. +- A single approver enforces taste. The program has a consistent editorial voice because one person is gatekeeping. + +The approver is also the editor. The same person who approves the brief reviews the draft. This prevents the gap between "what the brief asked for" and "what the editor wants"; the same person owns both sides. + +Splitting these roles is how briefs and reviews drift apart. The strategist who briefed the piece sees the gap; an external editor reads the draft and changes the lede because of personal taste, not because of the brief. + +The exception: for high-stakes pieces (pillar content, thought leadership with named author, comparison pieces involving competitors), a second reader is useful. The second reader provides input but does not approve. The single approver still decides. + +--- + +## Archival + +After publish, the brief is archived alongside the content piece. + +Common archival patterns: +- Notion database row. Brief and published-piece URL on the same row. Custom fields for brief version, approver, publish date, success-criteria results. +- dbt model with content metadata. For warehouse-native content tracking; brief stored as JSON in the model's seed data. +- CMS metadata fields. Contentful, Sanity, and similar CMSs allow custom metadata fields; the brief lives in a "brief" field on the content entry. +- Git repo. For docs sites and developer-facing content programs; brief in a sibling markdown file to the published piece. + +Why archival matters. Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, an audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +The audit question is "did we ship what we briefed, and did the briefed piece achieve its success criteria?" Both halves need source-of-truth records: the brief for what was asked, the published piece for what was delivered, the metrics for what the piece achieved. + +--- + +## Audit trail + +A content program that runs at scale needs an audit trail. The audit trail answers four questions per piece: + +1. What did we brief? The archived brief, with version history. +2. What did we publish? The published URL, with publish date and last-update date. +3. How did the piece perform against the success criteria? Rank position at 30 / 60 / 90 days; AI citation count if measured (Profound, Frase, AirOps); conversion data from the analytics stack. +4. What did we learn? A short post-publish note: what worked, what did not, what to brief differently next time. + +The audit trail compounds. After 50 pieces, the program can see patterns: pillar pieces with comprehensive outlines outperform pieces with thin outlines; comparison pieces with explicit "when X wins" / "when Y wins" framing outperform pieces with implicit positioning; entity-coverage scores above 80 correlate with citation count. + +The audit trail is what turns content production from a per-piece activity into a learning system. Without the trail, every piece is a one-off; with the trail, the program improves quarter over quarter. + +--- + +## The "post-mortem on a failed piece" pattern + +When a piece misses its success criteria, the post-mortem walks the brief. + +1. Read the brief. Was it complete? Were the 12 fields populated? +2. Read the published piece. Did it follow the brief? +3. Identify the gap. Was the brief wrong (target keyword too competitive, intent misclassified)? Was the execution off (writer drifted from outline, entities missed)? Was the SERP harder than expected (well-executed brief, well-written piece, still no rank)? +4. Update the brief template if the failure is systemic (next time, run a deeper SERP check before briefing). +5. Update the writer-handoff if the failure is communication (next time, the brief is read aloud at handoff). +6. Accept the failure if the failure is variance (some pieces miss; the program does not chase every miss). + +The post-mortem is short, half a page. It feeds the audit trail and informs the next brief. It does not turn into a multi-page analysis that nobody reads. + +--- + +## Brief field: governance metadata + +The brief carries governance metadata at the top: + +> Brief metadata +> - Brief version: 3 +> - Approver: editorial-lead@team.com +> - Approval date: 2026-04-22 +> - Writer assigned: J. Smith (or AI agent: Frase v4) +> - Target publish date: 2026-05-15 +> - Archive location: Notion content-pipeline database, row #847 + +The metadata is six lines, not a paragraph. It identifies the contract; the rest of the brief is the contract terms. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md b/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md new file mode 100644 index 0000000..5f9c94a --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/brief-templates.md @@ -0,0 +1,87 @@ +# Brief templates by content type + +Six templates. The 12 fields are constant; the weight of each field shifts based on the content type. Each template names the fields that lean heavier and the fields that lean lighter for that type. + +--- + +## Pillar piece + +Comprehensive coverage of a topic, 3,000+ words, anchors a topic cluster. The piece other content links up to. + +Heavier fields: heading structure (the outline is the spine), entity coverage (a pillar that misses entities loses credibility), internal linking (links to and from the supporting cluster pieces), word count (calibrated to top SERPs, often long). + +Lighter fields: anti-patterns (the writer assigned to a pillar usually knows the topic), tone reference (default brand voice; tone shifts are rare for pillars). + +Brief shape: 2 pages. The H2 outline takes ~40% of the brief because pillar structure is decisive. Entity list is long (15 to 25 entities). Internal-link section names every cluster piece that should link in or out. + +Worked example. Target keyword: "experimentation analytics dashboards." Cluster: experimentation methodology. Intent: commercial-investigation. SERP format: long-form articles plus comparison tables. Word count target: 2,800 to 3,400. Outline: H2 #1 "what an experimentation dashboard does," H2 #2 "platform-native vs warehouse-native," H2 #3 "the metrics that earn their keep," H2 #4 "build vs buy," H2 #5 "common dashboards that ship trusted results." Entities: lift, p-value, MDE, CUPED, sequential testing, Statsig, PostHog, Optimizely, dbt, Mixpanel, Snowflake. Internal links: 5 supporting pieces queued. + +--- + +## Supporting / cluster piece + +Narrower topic, 1,000 to 2,000 words, links up to the pillar. One question, one answer. + +Heavier fields: target keyword (specific long-tail), search intent (cluster pieces have to match SERP precisely), JTBD (one specific reader problem), internal linking (must link up to pillar with anchor text matching the pillar's target). + +Lighter fields: entity coverage (smaller scope, fewer entities required), thought-leadership POV (cluster pieces serve the cluster, not the writer's opinion). + +Brief shape: 1 page. JTBD in one sentence. H2 outline is 3 to 5 sections. Entity list is short (5 to 10). The "links up to pillar" specification is mandatory; an orphan cluster piece is a wasted slot. + +Worked example. Target keyword: "CUPED variance reduction." Pillar: experimentation analytics dashboards. Intent: informational. JTBD: data analyst wants to apply CUPED in a dbt model and needs the formula plus the gotchas. Outline: H2 "what CUPED does," H2 "the formula," H2 "implementing in dbt," H2 "common pitfalls." Internal link up to pillar with anchor "experimentation analytics dashboards." + +--- + +## Comparison piece (X vs Y) + +Commercial intent, structured comparison, decision framework. The reader wants help choosing. + +Heavier fields: anti-patterns (snark and trash-talk are the failure mode), heading structure (table-style comparison plus "when X wins" / "when Y wins" sections), success criteria (commercial intent piece; the metric is signups or sales-qualified leads, not traffic alone). + +Lighter fields: word count flex (top-ranking comparison pieces vary widely; SERP-calibrate). + +Brief shape: 1 to 2 pages. The comparison criteria are listed in the brief, not invented by the writer. If the brand is one of X or Y, the brief specifies honest positioning: what the brand wins on, what the competitor wins on. The brief explicitly forbids "X is the worst, Y is the best" framing. + +Worked example. Target keyword: "Statsig vs PostHog." Intent: commercial. SERP format: comparison tables plus prose. Comparison criteria: pricing model, MAU thresholds, MCP support, custom-metric depth, frontend visual editor, mobile SDK. "When Statsig wins": teams with strong custom-metric needs, teams that already pay for Snowflake. "When PostHog wins": product analytics-led teams, teams that want session replay alongside experimentation. Anti-pattern explicitly listed: do not write "PostHog is the clear winner" or "Statsig is overpriced." Honest comparison or do not write the piece. + +--- + +## Listicle + +Informational or commercial intent, scannable, ranked or unranked list. "10 best X" or "7 ways to Y." + +Heavier fields: selection criteria (why are these 10 the chosen ones; the writer needs to defend the list), ordering rationale (why is item #1 first; explicit ranking criteria), depth-per-item (how many words per item; even depth is the discipline). + +Lighter fields: narrative arc (listicles have minimal narrative; the list itself is the structure). + +Brief shape: 1 page. The selection criteria are listed in the brief. The order is suggested in the brief, with note that the writer can reorder if the research warrants. Depth-per-item is specified (e.g., 150 words each for 10 items, plus 200-word intro and 150-word conclusion = ~1,850 words). + +Worked example. Target keyword: "best feature flag tools 2026." Intent: commercial. Selection criteria: official MCP support, free tier exists, hosting model. The 10 items pre-listed in the brief: LaunchDarkly, Statsig, PostHog, GrowthBook, Optimizely, VWO FME, Split.io, Kameleoon, Flagsmith, Unleash. Depth: 150 words per tool covering pricing, MCP status, when this tool wins. + +--- + +## How-to guide + +Informational intent, step-by-step, screenshots, prerequisites, troubleshooting. The reader wants to do something specific. + +Heavier fields: step granularity (each step is one action, not three), prerequisites (what the reader needs before starting), troubleshooting section (common failure modes the reader will hit). + +Lighter fields: thought-leadership POV (how-to guides serve the task, not the writer's perspective on it). + +Brief shape: 1 to 2 pages. The brief lists the steps in outline form so the writer can spot missing prerequisites or merged steps before drafting. The screenshot list is queued (which screens, in what state). Troubleshooting bullets are listed; the writer expands each into a paragraph. + +Worked example. Target keyword: "how to set up a Statsig experiment." Prerequisites: Statsig account, SDK installed, exposure events instrumented. Steps: H2 "create the experiment in the console," H2 "define the assignment unit," H2 "configure the metrics," H2 "set the duration and MDE," H2 "launch and monitor." Troubleshooting: SRM check failure, exposure events not firing, metric definition mismatch. + +--- + +## Thought leadership / opinion + +Commercial or branding intent, distinctive POV, signal of expertise. The piece exists to differentiate the brand voice in the category. + +Heavier fields: thesis (one sentence; the whole piece defends it), anticipated counter-arguments (what would a smart skeptic say; the piece must address them), tone reference (often a sharper voice than default; the brief specifies the shift). + +Lighter fields: SERP entity coverage (thought leadership often deliberately diverges from SERP consensus; entity coverage is a softer requirement). + +Brief shape: 1 page. The thesis is one sentence at the top. The supporting arguments are listed (3 to 5). The anticipated counter-arguments are listed with notes on how the piece responds to each. The brief explicitly names the writer or contributor; thought leadership has authorship, not anonymous editorial. + +Worked example. Thesis: "warehouse-native experimentation is the right default for any team running 50+ experiments per quarter." Supporting arguments: cost crossover at scale, custom metric flexibility, audit trail, data-team integration. Counter-arguments to address: setup cost, time-to-first-experiment, missing UI tooling. Tone shift: sharper, more declarative than default brand voice. Author: named senior data leader. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md b/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md new file mode 100644 index 0000000..b9c2cf9 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/common-brief-failures.md @@ -0,0 +1,123 @@ +# Common brief failures + +Ten-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "The brief was too thin" + +Symptom. Brief contains target keyword, word count, deadline, maybe a one-line angle. Writer fills in everything else from priors. Output is generic, drifts off-topic, does not rank. + +Diagnosis. The strategist treated the brief as a task assignment instead of a contract. The 12 fields were not populated; the writer's defaults filled the gaps; the defaults were not aligned with the program's intent. + +Fix. Populate all 12 fields. If a field cannot be populated (the success criteria is genuinely unknown, the SERP is too volatile to call), name the gap explicitly and flag it as "writer's call, defend the choice in the first draft." + +--- + +## "The brief was too thick" + +Symptom. Brief is 4 pages with executive summary, brand-voice refresher, comprehensive competitive landscape, plus the actual brief. Writer skims for the outline. Output is not better than from a thin brief. + +Diagnosis. Strategist optimized for brief authorship instead of brief consumption. Each field added felt important; nobody asked "would the writer behave differently if this field were missing?" + +Fix. Cut fields that do not change writer behavior. Brand-voice refresher: link, do not repeat. Competitive landscape: link to research, do not summarize. Executive summary: the brief is the executive summary. Target: 1 to 2 pages. + +--- + +## "The writer ignored the brief" + +Symptom. The published piece misses the SERP intent, drops required entities, ignores internal-link guidance. Editor's review surfaces the gap. + +Diagnosis. No success-criteria acknowledgment at handoff. The writer read the brief once at the start, drafted from memory plus priors, never re-read. + +Fix. Require acknowledgment at handoff (see `writer-handoff-protocols.md`). The acknowledgment restates the success criteria in the writer's voice. Saying it is what keeps it load-bearing. + +--- + +## "The brief had the wrong target keyword" + +Symptom. The piece publishes; the target keyword turns out to have search volume of 50/month, or to be navigational (a brand wins position 1 forever), or to have a SERP the team cannot win. The piece does not rank. + +Diagnosis. SERP not validated before briefing. The strategist assumed the keyword was good without pulling the SERP and the volume. + +Fix. SERP-validate before briefing. Pull the keyword volume (Ahrefs, Semrush, GSC). Pull the SERP top 10. If the SERP looks unwinnable for the brand at current authority, pick a different keyword. + +--- + +## "The piece does not match the SERP intent" + +Symptom. SERP shows mostly listicles; the briefed piece is a long-form article. Or SERP shows long-form articles; the briefed piece is a listicle. Either way, the piece does not rank. + +Diagnosis. SERP intent override was not applied. The strategist's priors about what the keyword "should" look like overrode what the SERP actually shows. + +Fix. Apply the SERP override pattern (see `search-intent-classification.md`). The format choice line in the brief must match the dominant SERP format. + +--- + +## "The piece has no internal links" + +Symptom. Piece publishes with zero internal links to other pages on the site. Or with one or two links that the writer added arbitrarily. + +Diagnosis. Internal linking was treated as an afterthought. The brief did not specify outbound links; the writer added some at the end without strategic intent. + +Fix. Specify 3 to 5 outbound links in the brief, with anchor text and target page. Queue 1 to 3 inbound updates as post-publish tasks (see `internal-linking-strategy.md`). + +--- + +## "The piece is generic; could have been written about anything" + +Symptom. Reading the piece, you cannot tell what brand it came from, what makes it different from the SERP top 10, or why this piece exists. The piece reads as AI-generated even when a human wrote it. + +Diagnosis. Entity coverage and POV were missing from the brief. The writer hit the target keyword but did not differentiate; the piece blends into SERP consensus. + +Fix. Specify gap entities (entities mentioned by 1 to 2 SERP pages but not by the rest). Specify a POV for the piece: what the brand argues that the rest of SERP does not. Generic content has no POV; effective content makes a specific claim. + +--- + +## "The brief is comprehensive but the piece does not rank" + +Symptom. Brief had all 12 fields. Writer followed the brief. Piece is well-written, hits the entities, follows the outline. Three months post-publish: position 47. + +Diagnosis. The SERP was harder than expected. The brief was right; the keyword was over-competitive at the brand's current authority. This is variance, not failure. + +Fix. Do not iterate by adding fields to the brief. Iterate by SERP-validating more carefully next time, by accepting that some keywords are out of reach until the brand earns more authority, or by pivoting to a less-competitive long-tail variant. + +--- + +## "We never went back to evaluate" + +Symptom. Pieces publish; nobody checks performance at 30 / 60 / 90 days. The program runs without feedback. + +Diagnosis. Success criteria were defined in the brief but no measurement task was queued at publish time. + +Fix. Make 30 / 60 / 90 day check-ins part of the publish checklist. The check-in is a 5-minute task: read the rank, the citation count, the conversion data; update the audit trail (see `brief-governance-patterns.md`). Not optional. + +--- + +## "Different writers produce wildly different output from the same brief" + +Symptom. Two writers given the same brief produce pieces that read like they came from two different programs. The brief was supposedly identical; the output is not. + +Diagnosis. The brief was actually too vague. Different writers filled gaps with their own priors; the gaps were where the divergence lives. + +Fix. Tighten the anti-patterns and the voice notes. The brief explicitly forbids common writer drifts (off-topic tangents, off-brand tone, AI clichés). The voice reference is specific (not "use brand voice" but "use the voice of section 3 of the voice guide; default tone, no sharper"). + +--- + +## "The piece succeeded but we cannot tell why" + +Symptom. A piece outperforms expectations: top-3 rank, high citation count, conversion above target. The team cannot explain what made it work. + +Diagnosis. The brief and the published piece have multiple distinguishing features (specific outline, gap entities, sharp POV); without controlled comparison, the team cannot isolate the cause. + +Fix. Document hypotheses about why the piece worked in the post-publish note. Test the hypotheses by briefing the next 3 pieces with the same pattern. If the pattern replicates, it is the cause; if not, the success was variance. The audit trail compounds (see `brief-governance-patterns.md`); patterns emerge over 20+ pieces. + +--- + +## "We approved the brief but the writer wrote a different piece" + +Symptom. The brief was for a comparison piece; the writer delivered a thought-leadership piece. The brief was for 1,800 words; the writer delivered 3,400 words. The brief was for a senior data engineer audience; the writer wrote for a non-technical CMO. + +Diagnosis. The handoff acknowledgment was skipped. The writer read the brief, drafted from a different mental model, and did not surface the divergence early. + +Fix. Require acknowledgment that restates the brief's parameters: word count, audience, format. If the writer's acknowledgment misstates anything, the strategist catches it before drafting starts. After 1,500 words of writing, restarting is expensive; before drafting, restating is cheap. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md b/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md new file mode 100644 index 0000000..54ada43 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/entity-coverage-checklist.md @@ -0,0 +1,91 @@ +# Entity coverage checklist + +Entity discovery from SERP, gap analysis, AEO and GEO citation drivers. + +--- + +## Why entity coverage matters + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that: + +- Mentions the entities the SERP top-ranking pages mention +- Includes specific statistics with sources +- Contains citation-formatted proof points +- Demonstrates topical depth via entity coverage + +Entities are the named things the topic depends on: tools, methods, experts, datasets, statistics, brands, frameworks, standards, organizations. A piece on "experimentation analytics" that does not mention CUPED, sequential testing, p-values, or named platforms (Statsig, PostHog, Optimizely) reads as thin both to humans and to ranking systems. + +Traditional SEO has known about entity coverage for years (Google's Hummingbird and BERT updates emphasized it). AEO and GEO double the stakes: AI engines explicitly use entity coverage as a citation signal because they can extract the entity graph from the page and assess topical depth at retrieval time. + +--- + +## The entity discovery workflow + +Run before authoring the brief; do not delegate to the writer. + +Step 1. Pull the SERP top 10 for the target keyword. + +Step 2. For each top-10 page, extract the named entities. Tools that automate this: Frase (built-in entity gap analysis), AirOps (workflow builder runs the same analysis), Surfer SEO (entity coverage scoring), or manual extraction with a structured prompt. + +Step 3. Tag each entity by frequency: +- Mentioned by 7+ of 10 pages: required coverage. The brief lists these. +- Mentioned by 3 to 6 pages: standard coverage. The brief lists these with shorter notes. +- Mentioned by 1 to 2 pages: gap entities. The brief includes these as differentiation opportunities. +- Mentioned by 0 pages but relevant: brand-owned entities the team knows matter even if SERP misses them. + +Step 4. For each required and standard entity, write a one-line note in the brief explaining why it matters and where to mention it. Example: + +> CUPED. Variance-reduction technique mentioned by 9 of 10 SERP pages. Mention in the methodology H2 with the formula. Required. + +Step 5. Add the gap entities (1 to 2 page mentions) as differentiation opportunities. The writer can choose to include them; they add depth without crowding the required entities. + +--- + +## AEO and GEO citation drivers + +Beyond entity coverage, AI engines weight several other signals when deciding what to cite. + +Specific statistics with sources. "Statsig charges per MAU starting at 100K MAU" cites better than "Statsig is expensive at scale." Numbers with sources are higher-citation; vague qualifiers are lower-citation. + +Named experts or quotes. "As Ronny Kohavi noted in his book Trustworthy Online Controlled Experiments, the most common SRM diagnosis is..." cites better than "experts agree that SRM diagnoses are common." Named attribution earns citation; anonymous attribution does not. + +Direct definitions. "CUPED stands for Controlled-experiment Using Pre-Existing Data" cites better than a passage that uses CUPED without defining it. AI engines extract definitions and use them as the canonical answer when users ask "what is CUPED." + +Comparison tables. Tables with explicit columns and rows cite better than prose comparisons. AI engines extract structured data preferentially. + +Specific tool names with version numbers. "dbt Cloud (v1.7+)" cites better than "dbt." Specificity is the citation signal. + +--- + +## Brief field: how to populate entity coverage + +The brief lists the required entities, the standard entities, and the gap entities, with one-line notes per entity. + +> Required entities (mention all) +> +> - CUPED: variance-reduction technique (9/10 SERP pages). Mention in methodology H2 with formula. +> - Sequential testing: confidence-adjustment for peeking (8/10). Mention in pitfalls H2. +> - MDE (minimum detectable effect): power-calculation input (10/10). Mention in setup H2. +> - Statsig, PostHog, Optimizely: named platforms (10/10 mention at least one). Brief should mention all three with one-sentence positioning. +> +> Standard entities (mention if relevant) +> +> - A/A test: sanity check (5/10). Mention in pitfalls H2. +> - Bonferroni correction: multiple-testing adjustment (4/10). Mention in pitfalls H2. +> +> Gap entities (differentiation opportunity) +> +> - CUPAC: successor to CUPED (1/10). Mention in methodology H2 as the next-generation technique. Differentiates the piece from SERP consensus. +> - Bayesian inference: alternative to frequentist hypothesis testing (1/10; mentioned occasionally in advanced experimentation content). Mention in advanced section if word budget allows. + +The "Bayesian inference" entity is the example: it is a specific technical concept that some advanced experimentation content covers, where most SERP top-10 pieces stop at frequentist hypothesis testing. Adding the gap entity differentiates the piece without crowding the required-coverage list. + +--- + +## The entity-coverage failure mode + +The most common failure: the writer mentions all the required entities once each, in passing, without weight. The piece passes the entity-coverage check on a string-match basis but does not actually demonstrate topical depth. + +The fix in the brief: specify weight per entity. "Mention CUPED in passing in H2 #2; develop CUPED with formula and example in H2 #4." The brief is not just a list of entities to include; it is a placement plan. + +The writer's draft references the brief's entity placement plan. The editor reviews against placement, not just against presence. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md b/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md new file mode 100644 index 0000000..e89841b --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/heading-structure-patterns.md @@ -0,0 +1,102 @@ +# Heading structure patterns + +H2 patterns, H3 sub-section patterns, featured-snippet bait, and the anti-patterns the brief should explicitly forbid. + +--- + +## H2 patterns that work + +Question-style H2s. "What is CUPED?" "How does CUPED reduce variance?" "When should I use CUPED?" These match how readers think and how Google's "People Also Ask" box surfaces queries. They are also the easiest format for AI engines to extract as citation candidates. + +Declarative H2s. "CUPED reduces variance by adjusting for pre-experiment covariates." "The formula uses a regression coefficient computed before assignment." Declarative H2s work for pieces that have a strong thesis or that summarize before they explain. + +Comparison H2s. "Platform-native: faster, narrower, opinionated." "Warehouse-native: slower, broader, custom-metric capable." Symmetrical H2s pair to set up a comparison; the reader sees the structure on the table of contents alone. + +Imperative H2s. "Configure the assignment unit." "Define the metrics." "Set the duration and MDE." Common for how-to guides; each H2 is one action. + +The discipline: pick one pattern and use it consistently within a piece. Mixing question + declarative + imperative reads as inconsistent and signals AI generation when the mixing is random. + +--- + +## H3 patterns under H2s + +H3s should add navigational value, not just structure for its own sake. + +When to add H3s: +- The H2 covers a topic with 3 to 5 sub-topics that the reader might want to jump to +- The H2 section is long enough (700+ words) that scanning needs sub-anchors +- The piece has a table of contents that benefits from sub-entries + +When not to add H3s: +- The H2 is short (under 400 words) +- The H3s would be a cosmetic enumeration that does not add navigation +- The piece is short overall (under 1,200 words); H3s are usually unnecessary + +No orphan H3s. Every H2 either has zero H3s or 2+ H3s. A single H3 under an H2 reads as a typo or an aborted edit. + +No H2-H3-H4 cascades. If a section needs H4s, the structure is wrong. Either the H2 is too broad and should split into two H2s, or the H4 is decoration that should be a paragraph. + +--- + +## The featured snippet bait pattern + +Place a 40 to 60 word answer paragraph immediately following the H2 question. Google often pulls this paragraph as the featured snippet; AI engines often quote it as the citation. + +Example. + +> ## What is CUPED? +> +> CUPED (Controlled-experiment Using Pre-Existing Data) is a variance-reduction technique that adjusts experimental measurements using pre-treatment covariates. The covariate's regression coefficient against the outcome is computed before assignment, then used to subtract baseline variance from the experiment's measurement, increasing statistical power without changing the experiment's design. + +The paragraph is self-contained: read alone, it answers the H2 question completely. The rest of the section expands on the answer with examples, formulas, edge cases. + +The discipline: the snippet paragraph is the most important paragraph in the section. Write it first; expand the section around it. + +--- + +## H2 ordering + +H2s should match the reader's mental model, not the writer's enthusiasm. + +The standard order for informational pieces: +1. What is it (definition, plain language) +2. Why does it matter (why the reader cares) +3. How does it work (mechanism, technical depth) +4. When to use it (decision criteria) +5. Common pitfalls (what goes wrong) +6. Wrap-up or call-to-action + +The buried-lede anti-pattern. H2 #4 has the actual answer the reader came for. The reader bounced at H2 #2. + +The fix. Put the obvious answer first. The writer's clever angle goes in H2 #4 or H2 #5, not H2 #1. + +--- + +## Anti-patterns the brief should forbid explicitly + +Repetitive H2 structure. All H2s start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. Vary the patterns within a piece, but keep one dominant pattern. + +Buried lede. The actual answer is in H2 #4. The brief specifies which H2 carries the keystone answer; usually H2 #1 or H2 #2. + +Section length unevenness. H2 #1 is 1,500 words; H2 #2 is 80 words. The 80-word section reads as a placeholder. Briefs should specify approximate word counts per H2 to enforce balance. + +H3-only enumeration. A section that is just an H2 plus a list of H3s with one paragraph each. Either the H2 should hold all the content, or the H3s deserve more depth. The half-and-half shape is a sign of incomplete thinking. + +Misnumbered H2s in numbered series. "5 ways to Y" with 6 H2s, or with 4. The mismatch reads as careless. + +--- + +## Brief field: how to populate the heading structure + +The brief lists the H2s in order with one-line notes. H3s only when they earn their keep. + +> Heading structure outline +> +> - H2 #1: "What is X?" (snippet paragraph mandatory; ~250 words section) +> - H2 #2: "Why X matters" (~300 words; one specific reader scenario) +> - H2 #3: "How X works" (~600 words; H3s: "the formula," "the assumption," "the implementation"; show the math) +> - H2 #4: "When to use X" (~400 words; decision-criteria list) +> - H2 #5: "Common pitfalls" (~400 words; 3 to 5 specific pitfalls with diagnoses) +> - H2 #6: "Wrap-up" (~150 words; call-to-action to related cluster piece) + +The writer follows the outline; deviations are flagged in the first draft for editor review. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md b/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md new file mode 100644 index 0000000..85918ae --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/internal-linking-strategy.md @@ -0,0 +1,97 @@ +# Internal linking strategy + +Outbound and inbound linking patterns, orphan-content prevention, self-cannibalization check. + +--- + +## Two link directions to specify + +Every brief specifies links in two directions. + +Outbound from this piece. 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer is not deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. + +Inbound to this piece, post-publish. 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +--- + +## Outbound link selection + +The cluster pieces. The brief lists the supporting cluster pieces this piece should link to, with anchor text that matches each target's primary keyword. + +Example for a pillar piece on "experimentation analytics dashboards": + +> Outbound links (writer integrates) +> +> 1. Link to "CUPED variance reduction" (cluster piece) using anchor "CUPED" or "variance reduction with CUPED" in the methodology H2. +> 2. Link to "warehouse-native experimentation" (sister pillar) using anchor "warehouse-native experimentation" in the platform-vs-warehouse comparison H2. +> 3. Link to "feature flag tools comparison" (commercial-intent piece) using anchor "feature flag tools" in the deployment H2. +> 4. Link to "data warehouse setup" (foundation piece) using anchor "data warehouse" in the prerequisites H2. + +The discipline: anchor text matches the target's primary keyword. Generic anchors ("click here," "this article") do not pass ranking signals; keyword anchors do. + +--- + +## Inbound link queue + +The brief queues 1 to 3 existing pages that should add a link to the new piece after it publishes. The strategist updates these as part of the publish checklist. + +Example continuing the same pillar: + +> Inbound link updates (post-publish task) +> +> 1. Update "feature flagging" pillar to link to the new piece in the "measuring feature impact" section using anchor "experimentation analytics dashboards." +> 2. Update "PostHog vs Statsig" comparison to link to the new piece in the analytics-comparison H2. +> 3. Update homepage "Resources" section to add the new piece to the "Pillars" list. + +The inbound queue prevents the orphan-content failure mode. + +--- + +## The orphan-content failure mode + +Symptom: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. + +Cause: internal linking was an afterthought, handled by the writer or by SEO at publish time without strategic intent. The writer linked out to 3 pages because the brief said to; nobody linked back in because nobody owned that task. + +Fix: the brief queues the inbound updates explicitly. The publish checklist includes the inbound updates as a tracked task. Without a tracked task, the inbound updates do not happen; without inbound links, the piece is an orphan. + +The "5-link rule" diagnostic. Every published piece should have at least 5 internal links pointing to it within 30 days of publish. If a piece has fewer than 5 inbound links at the 30-day check, audit the inbound queue and add the missing links. + +--- + +## The self-cannibalization check + +Before briefing a new piece, check whether it would compete with an existing piece for the same keyword cluster. + +The check. Search the site for the target keyword. If an existing piece is in the top 5 of internal search results, flag it. + +Three options when self-cannibalization is detected: + +1. Consolidate. Merge the planned piece into the existing piece. Update the existing piece with the new angle, the new entities, the new examples. Keep one URL ranking; do not split ranking authority across two URLs. +2. Differentiate. Sharpen the angle of the new piece so it does not compete. The existing piece covers "what is feature flagging"; the new piece covers "feature flag rollout strategies for enterprise teams." Different intent, different audience, different SERP target. +3. Kill one. Determine which piece serves the cluster better. Redirect the loser to the winner. This is rare and usually signals the program does not have clear pillar structure. + +The discipline: flag self-cannibalization in the brief, not after the piece is written. Late detection is the expensive failure mode; the writer has already invested hours that now have to be either rewritten or thrown away. + +--- + +## Brief field: how to populate internal linking + +> Internal linking +> +> Outbound (3 specified, 2 optional) +> - Required: link to "CUPED variance reduction" with anchor "CUPED" in methodology H2 +> - Required: link to "warehouse-native experimentation" with anchor "warehouse-native" in comparison H2 +> - Required: link to "feature flag tools 2026" with anchor "feature flag tools" in deployment H2 +> - Optional: link to "data warehouse setup" with anchor "data warehouse" in prerequisites H2 (writer's call based on flow) +> - Optional: link to "experiment-design skill" with anchor "experiment design" in introduction (writer's call) +> +> Inbound (post-publish, queued) +> - Update "feature flagging" pillar (insert link in section 4) +> - Update "PostHog vs Statsig" comparison (insert link in analytics-comparison H2) +> +> Self-cannibalization check +> - Existing pieces on adjacent keywords: "experiment dashboards introduction" (different angle, no conflict) +> - No conflict; proceed with brief + +The brief is explicit about what is required, what is optional (writer chooses), and what is queued for post-publish. Three layers of discipline. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md b/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md new file mode 100644 index 0000000..eeaf7ce --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/search-intent-classification.md @@ -0,0 +1,68 @@ +# Search intent classification + +Four-intent framework, dominant SERP format check, override patterns when intent and format mismatch. + +--- + +## The four standard intents + +Informational. The reader wants to learn. Queries: "what is CUPED," "how does feature flagging work," "experimentation analytics explained." SERP usually shows articles, guides, explainers, sometimes videos. Conversion is downstream (the reader signs up for the newsletter or returns to the site weeks later); ranking is the immediate goal. + +Navigational. The reader wants a specific brand, product, or page. Queries: "Statsig pricing," "LaunchDarkly login," "PostHog docs." SERP usually shows the brand site at #1 and a sitelinks block. Ranking against navigational intent is mostly impossible unless you are the brand. The exception: the reader-bypass pattern where adjacent brands rank for "competitor X login" by writing comparison content; play this carefully because it can read as bait. + +Commercial. The reader is researching a purchase. Queries: "best feature flag tools," "Statsig vs LaunchDarkly," "Optimizely review." SERP usually shows comparisons, reviews, "best X" listicles, sometimes detailed guides. The reader is in active evaluation; this is the highest-conversion intent for B2B SaaS content. + +Transactional. The reader is ready to buy. Queries: "Statsig signup," "buy LaunchDarkly," "PostHog free trial." SERP usually shows product pages, pricing pages, signup flows. Editorial content does not rank here; brand-owned commercial pages do. + +--- + +## The dominant SERP format check + +After classifying intent, scan the SERP top 10 and tag the dominant format. + +- Article. Long-form prose, single-author voice. Common for informational intent. +- Listicle. "10 best X," "7 ways to Y." Common for commercial-investigation intent. +- Comparison. Side-by-side X vs Y, table-heavy, decision frameworks. Common for high-funnel commercial intent. +- Video. YouTube embeds dominate the top of SERP. Common for how-to and tutorial queries. +- Tool. Calculator, generator, interactive tool. Common for "X calculator" or "X generator" queries. +- Hybrid. SERP shows a mix; usually tells you the keyword is contested or the intent is split. + +The dominant format tells you the shape of the piece, which is more decisive than the intent label. An informational keyword whose SERP is mostly listicles wants a listicle, not a long-form article. + +--- + +## The override pattern + +When intent and format mismatch, the format wins. + +Case 1. The intent feels informational ("how to design an A/B test") but the SERP shows mostly listicles ("7 steps to designing an A/B test"). Write the listicle. The SERP is the source of truth, not your priors about what the intent "should" look like. + +Case 2. The intent feels commercial ("best feature flag tools") but the SERP shows mostly long-form articles that mention many tools without ranking them. Write the long-form article. Listicle format would feel out of place against the SERP. + +Case 3. The SERP is genuinely split: half listicles, half long-form articles. Either format can rank. Pick based on the brand's voice and the piece's role in the cluster. + +The reason. Rankings come from matching the SERP's accepted shape; deviating costs ranking. Google's ranking algorithm is partly trained on what users click and stay on, which is selected from existing top-ranking content. Existing top-ranking content sets the shape; new content has to match the shape to compete. + +--- + +## The AEO and GEO consideration + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. + +A piece that mismatches the SERP format faces two problems: it is harder to rank in traditional search, and it is less likely to be cited by AI engines. The mismatch is a double cost. + +The exception: thought leadership that deliberately diverges. A piece arguing "the listicle format is misleading for this category; here is why" can rank by drawing traffic on the controversy and earning citations on the contrarian thesis. This is rare and risky; do not default to it. + +--- + +## Brief field: how to populate intent + format + +The brief field reads like this: + +> Search intent + SERP format +> Intent: commercial-investigation +> Dominant SERP format: long-form article + comparison table hybrid (top 5 are articles with embedded comparison tables; positions 6 to 10 are pure listicles) +> Format choice for this piece: long-form article with one comparison table at the midpoint +> SERP intent override: none (format choice matches dominant) + +The "format choice" line is decisive. The writer reads this line first and shapes the piece around it. diff --git a/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md b/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md new file mode 100644 index 0000000..ca3be09 --- /dev/null +++ b/dist/pi/.agents/skills/content-brief-authoring/references/writer-handoff-protocols.md @@ -0,0 +1,101 @@ +# Writer handoff protocols + +Human-writer handoff, AI-agent handoff, success-criteria anchoring. + +--- + +## The handoff has the same shape regardless of writer + +Whether the writer is a human freelancer, a staff editor, an internal SME, or an AI agent (Claude, ChatGPT, a Frase brief-runner, an AirOps workflow), the brief-to-writer handoff has the same five-step shape. + +1. Brief delivered with all 12 fields populated. +2. Writer asks clarifying questions before drafting (or the agent surfaces ambiguities as the first response). +3. Writer or agent acknowledges the success criteria explicitly. +4. First draft references the brief: which fields the draft addresses, which fields it could not address, why. +5. Editor reviews against the brief, not against personal taste. + +The shape is the same; the medium differs. Human writers acknowledge in Slack or email; AI agents acknowledge in the first message of the agent thread. Both cases: the acknowledgment is required, not optional. + +--- + +## Human-writer handoff + +Step 1: brief delivery. The brief is delivered as a single document (Notion page, Google Doc, dbt-style markdown file in the repo). The writer can read it in 5 minutes; if reading takes longer, the brief is too thick and should be cut. + +Step 2: clarifying questions. Before drafting, the writer asks clarifying questions. Common ones: + +- Is the target audience right? Is the JTBD specific enough to write to? +- Is the SERP intent classification right? Do I write a listicle or an article? +- Are these entities really required, or are some optional? +- Is the success criteria measurable from my side, or is it a downstream-only metric? + +The strategist answers questions in the same document; clarifications are versioned with the brief, not pasted into Slack and lost. + +Step 3: acknowledgment. The writer acknowledges in writing: "I have read the brief. I am writing to the success criteria of [X]. I will hit all required entities. I am clear on the SERP format choice." Acknowledgment is a 3-line message, not a treatise. + +Step 4: first draft with reference. The first draft is delivered with a reference note: "Hit 4 of 5 required entities; the 5th (CUPAC) was not in the SERP coverage I could find sources for, so I substituted the standard CUPED treatment per the brief's gap-entity guidance." The reference note tells the editor what to focus on in review. + +Step 5: editor review against brief. The editor reads the brief first, the draft second. The review framing is "the brief said X; the draft did Y; gap is Z." Personal taste comes after brief review, not before. + +--- + +## AI-agent handoff + +The shape is the same; the medium is structured. + +Step 1: brief delivery as structured input. The brief becomes a YAML or JSON object the agent ingests. Frase, AirOps, and similar tools structure briefs in their own schema; the same 12 fields appear regardless. Example minimal YAML structure: + +```yaml +target_keyword: experimentation analytics dashboards +supporting_cluster: + - CUPED variance reduction + - sequential testing + - feature flag rollout +search_intent: commercial-investigation +serp_format: long-form-article-with-comparison-table +target_audience: senior data engineer at 500-person SaaS +jtbd: choose between platform-native and warehouse-native experimentation +word_count_target: 2800 +heading_outline: + - { level: 2, text: "What an experimentation dashboard does" } + - { level: 2, text: "Platform-native vs warehouse-native" } + - { level: 2, text: "Metrics that earn their keep" } + - { level: 2, text: "Build vs buy" } + - { level: 2, text: "Common dashboards that ship trusted results" } +required_entities: + - { name: "CUPED", note: "mention with formula in methodology H2" } + - { name: "Statsig, PostHog, Optimizely", note: "mention all three" } +internal_links: + outbound: + - { target: /skills/cuped, anchor: "CUPED" } + - { target: /skills/warehouse-native, anchor: "warehouse-native experimentation" } + inbound_queued: + - { source: /pillars/feature-flagging, anchor: "experimentation analytics dashboards" } +anti_patterns: + - "do not use the team's do-not-use word list (see brand voice guide)" + - "do not write a listicle; SERP wants long-form" +success_criteria: + - "rank top 10 for target keyword in 90 days" + - "cited by ChatGPT for 'experimentation dashboard' queries within 60 days" +voice_reference: /brand/voice-guide +brief_version: 2 +brief_approver: editorial-lead@team.com +``` + +Step 2: ambiguity surfacing. The agent's first response surfaces ambiguities. "The brief lists CUPED as required, but the SERP top 10 only mention CUPED in 6 of 10 results; should I emphasize it or treat it as standard coverage?" The strategist answers; the brief gets versioned with the answer. + +Step 3: acknowledgment. The agent acknowledges in structured output: "Reading brief version 2. Target: 2,800 words. Format: long-form with comparison table. Will hit 4 required entities; need clarification on CUPED weight." Single message, machine-readable. + +Step 4: first draft with reference. The agent's draft is delivered with a structured note: which fields the draft addressed, which entities are present and where, what success criteria the draft is targeting. + +Step 5: editor review. The editor reviews the agent's draft using the same brief-first framing. Tools like Frase highlight which entities are present in the draft; the editor scans the highlights to confirm coverage. + +--- + +## Success-criteria anchoring + +The most-skipped handoff step is success-criteria acknowledgment. The writer or agent reads the brief, drafts the piece, delivers it; the success criteria sit in the brief unread. + +The fix: every handoff acknowledgment includes the success criteria verbatim. "I am writing to the success criteria: rank top 10 for 'experimentation analytics dashboards' in 90 days; get cited by ChatGPT for the topic within 60 days; drive 50 trial signups in the first 30 days." + +The acknowledgment is the contract restated in the writer's voice. Saying it out loud is what keeps it load-bearing during drafting. diff --git a/dist/pi/.agents/skills/content-distribution/SKILL.md b/dist/pi/.agents/skills/content-distribution/SKILL.md new file mode 100644 index 0000000..eeb09a6 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/SKILL.md @@ -0,0 +1,307 @@ +--- +name: content-distribution +description: "Content distribution as a discipline. Owned channels (newsletter, blog, social), earned channels (PR, syndication, mentions), paid channels (boosted posts, syndication networks), and the channel-fit decisions that distinguish strategic distribution from spam-everywhere. Audience-channel matching, content-channel matching, distribution cadence. Triggers on content distribution, channel strategy for content, owned earned paid channels, content amplification, content promotion, audience-channel matching, content-channel matching, distribution cadence, syndication strategy, organic distribution. Also triggers when content is publishing but reach is low, when the team is distributing on every channel without strategy, or when the content program needs a distribution discipline rather than just publication." +category: content +catalog_summary: "Content distribution discipline: owned, earned, and paid channels matched to audience and content type. Channel-fit decisions, distribution cadence, the strategic alternative to spam-everywhere or hope-and-pray" +display_order: 12 +--- + +# Content Distribution + +A senior editorial leader's playbook for content distribution as a discipline. Owned, earned, and paid channels matched to audience and content type, with the channel-fit decisions that distinguish strategic distribution from spam-everywhere or hope-and-pray. + +Content distribution is half the work and gets a fraction of the attention. Most programs spend 90% of capacity on production and 10% on distribution; the resulting ratio of effort-to-reach is consistently poor. The teams producing content that reaches audiences are the ones who treat distribution as a real discipline: channels chosen for fit, cadence calibrated to audience attention, owned-earned-paid balance set by program strategy, and effectiveness measured per channel. + +This skill is the channel discipline. Different from `content-repurposing` (which turns one piece into many formats), this skill is about getting content TO audiences via the right channels. The two skills compose: repurpose first, then distribute the right format on the right channel. + +The voice is the senior editorial leader who has watched programs underperform because distribution was treated as posting-after-publishing rather than as the equal half of the work. + +When to use this skill: building a distribution discipline for a content program, auditing why content publishes consistently but reach is low, calibrating owned-earned-paid balance, designing channel-fit decisions for a multi-format program. + +--- + +## What this skill is for + +This skill spans channel selection, audience-channel matching, content-channel matching, and distribution cadence. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes pieces. +- `editorial-qa` verifies before publish. +- `content-repurposing` turns one piece into many formats (transformation). +- `content-distribution` (this skill) gets content TO audiences via channels (channel work). + +The distinction from `content-repurposing` is load-bearing. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. Distribution is channel work: getting content to audiences via the right channels. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content programs that need reach, agencies running distribution for clients. + +What is not in scope: paid acquisition for purposes other than content amplification (covered by `paid-media-strategy`), the specific email channel discipline (covered by `email-sequences`), the AI-search optimization layer that sits across distribution channels (covered partially by `seo-aeo-geo`). + +--- + +## Hope-and-pray vs spam-everywhere vs channel-fit + +The keystone framing. + +Hope-and-pray. Publish and assume readers will find it. The piece goes live; the team links it on the blog homepage; maybe shares it once on social; assumes search and word of mouth will carry it. Output: most pieces reach a fraction of their potential audience because no deliberate distribution work was done. The program produces good content that nobody encounters. + +Spam-everywhere. Blast every piece on every channel regardless of fit. Every piece on LinkedIn, Twitter/X, Facebook, Threads, Mastodon, Bluesky, plus 5 emails to the full list, plus paid promotion on every platform. Audience tunes out; channels deprioritize the program; trust degrades. AI tooling has made spam-everywhere cheap and increasingly common, which makes the audience reaction sharper. + +Channel-fit. Distribute through channels matched to audience and content type. Specific channels chosen for specific pieces. Cadence calibrated to each channel's audience attention rhythm. Owned-earned-paid balance set by program strategy. Output: each distribution choice produces engagement from audiences who actually want the content; the program's distribution capacity is concentrated where it produces value. + +The litmus test. Ask of any distribution decision: which audience is this piece for, where does that audience consume content, does the piece's format fit that channel's conventions, and at what cadence does the channel reward presence? If the answers are specific, the distribution is channel-fit. If the answers are "everyone, everywhere, every channel, all the time," the distribution is spam-everywhere. + +--- + +## Channel taxonomy + +Three categories with sub-types within each. + +Owned channels. Channels the program owns and controls. + +- Newsletter and email. Direct relationship with subscribers. High control over reach (every subscriber receives the email); lower scale than social. +- Blog and content site. Owned property where pieces live. Search and direct traffic; the canonical version of pieces. +- Social channels owned by the program. LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account. Owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. +- Communities and forums owned by the program. Slack communities, Discord servers, dedicated discussion forums. Direct relationship with members. + +Earned channels. Channels where content reaches audiences via third-party amplification, not paid placement. + +- PR and press coverage. Journalists, podcasters, newsletter operators who cover the program's content because it is newsworthy or insightful. +- Syndication. Other publications republishing or excerpting the program's content (with appropriate attribution and canonical signaling). +- Mentions and citations. Other content marketing programs, industry analysts, AI search engines citing the program's content. +- Word of mouth and shares. Audiences sharing pieces with their networks; the program's content becoming part of conversations. + +Paid channels. Channels where paid spending amplifies content. + +- Boosted social posts. Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. +- Promoted newsletter sends. Sponsored placements in third-party newsletters. +- Syndication networks. Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. +- Search advertising for content. Paying for clicks on content pieces (less common; usually content is the organic side and paid is the conversion side). +- Sponsored podcast or content placements. Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Detail in [`references/channel-taxonomy.md`](references/channel-taxonomy.md). + +--- + +## Audience-channel matching + +Where the target audience actually consumes content. The distribution decision starts here. + +The audit. + +- Identify the audience for the program (or for the specific piece). +- Map where that audience spends time in their professional or consumer life. +- Identify the channels in that audience map where the audience is genuinely engaged (not just present). +- Match content distribution to those channels. + +Common audience-channel maps. + +- B2B technical audiences. LinkedIn high engagement; X moderate engagement (specific communities); industry newsletters; specific industry forums; podcasts in their domain. +- B2B executive audiences. LinkedIn high engagement; specific executive newsletters and podcasts; conferences and analyst-influence channels. +- Consumer mass audiences. Instagram, TikTok, YouTube, Facebook depending on demographic; broad email if subscribed. +- Niche specialist audiences. Specific subreddits, Discord servers, specialized newsletters, niche podcasts. Often higher engagement on smaller channels than on broad social. +- Developer audiences. GitHub, Hacker News, specific subreddits, dev-focused podcasts and newsletters, Twitter/X for parts of the community. + +The mismatch failure. Distributing on channels where the audience is present but not engaged produces low reach and low engagement. A B2B technical program publishing TikToks may technically reach audiences on TikTok but engage few of them; the audience is on TikTok for entertainment, not for technical learning. + +Detail in [`references/audience-channel-matching.md`](references/audience-channel-matching.md). + +--- + +## Content-channel matching + +Which formats fit which channels. Beyond audience match, the format must fit the channel's conventions. + +Format-channel fit examples. + +- Long-form analytical text fits blog, newsletter, LinkedIn long posts, X threads (for the right communities). Does not fit TikTok, Instagram Reels, or short-form video platforms. +- Short-form video fits TikTok, Reels, Shorts, increasingly LinkedIn video. Does not fit newsletter (where text leads) or owned blog (where written long-form leads). +- Statistic-driven content fits social with quote-graphics, AI search snippets, podcast mentions. Does not fit (as primary format) newsletter where context develops the stat. +- Conversational expert content fits podcasts, video interviews, possibly long social threads. Does not fit short-form video or single-post-format social. + +The mismatch failure. Distributing a format on a channel where the format does not fit produces low engagement. A 5,000-word whitepaper on TikTok (even repurposed) may not fit the format expectations of TikTok audiences regardless of audience overlap. + +The compose-with-repurposing pattern. When the audience is on a channel but the format does not fit, the right answer is often to repurpose into a format that does fit (see `content-repurposing`), then distribute. The composition is "repurpose for fit, distribute on channel." + +Detail in [`references/content-channel-matching.md`](references/content-channel-matching.md). + +--- + +## Distribution cadence + +How often, what mix, sustaining vs campaign rhythm. + +Cadence axes. + +- Frequency per channel. How often the program posts to each channel. +- Mix. What proportion of distribution is owned vs earned vs paid; what proportion is original vs derivative. +- Rhythm. Sustaining baseline cadence vs campaign spikes around flagship launches. + +Common cadence patterns. + +- B2B program with content-led demand generation. Newsletter weekly. Blog 2-4 posts per week. LinkedIn 3-5 posts per week. X 5-10 posts per week. Quarterly campaign spikes for flagship launches. +- Consumer brand with broad-audience reach goals. Daily Instagram content. Weekly newsletter. TikTok 2-4 posts per week. Owned blog 1-2 posts per week. Continuous paid amplification. +- Niche specialist program with concentrated audience. Newsletter weekly or bi-weekly. Owned blog 1-2 posts per month. Social on specific platforms 2-3 posts per week. Earned channels prioritized over paid. + +Sustaining vs campaign. + +- Sustaining cadence. The baseline rhythm. Audiences expect this cadence; deviation (long pauses or sudden spikes) affects engagement. +- Campaign rhythm. Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +The cadence audit. Programs that publish in fits and starts (3 posts in one week, then nothing for 3 weeks) underperform programs with steady cadence. Audience attention rewards predictability. + +Detail in [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md). + +--- + +## Owned-channel discipline + +Owned channels are the program's most reliable distribution. The discipline keeps them effective. + +Newsletter. Direct subscriber relationship; near-100% delivery to inboxes (modulo spam filtering). Cadence consistency matters: weekly is the most common cadence for B2B; bi-weekly works for higher-investment formats. Each send earns the next; sloppy sends lose subscribers. + +Blog. Canonical home for long-form content. SEO compounds over time; internal linking earns authority. The blog is where pieces persist; social and email send audiences to the blog. + +Social channels owned by the program. LinkedIn, X, Instagram, etc. Reach is platform-controlled (not the program's), but the program controls what publishes and when. Algorithmic favor varies; content that the platform's algorithm rewards gets reach beyond the follower base. + +Podcast. Owned distribution is the show feed; subscribers receive new episodes. Episodes also live on the blog with show notes; the show notes are an SEO asset. + +Communities. Slack, Discord, forums where the program facilitates discussion. The community is the audience the program is most directly engaged with; distribution to the community is the most reliable engagement signal. + +The owned-channel anti-pattern: starvation. Programs that under-invest in owned channels become dependent on third-party distribution. When platforms change algorithms, when paid costs rise, when earned channels go quiet, the program's reach collapses. Owned-channel investment is the durable foundation. + +Detail in [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md). + +--- + +## Earned-channel work + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real. + +PR and press. Pitching journalists, podcasters, newsletter operators on the program's content. Effective when the content is genuinely newsworthy or insightful; ineffective when pitches feel like blast emails. + +Syndication. Negotiating with other publications to republish or excerpt the program's content with appropriate attribution and canonical signaling. The syndication earns reach; the canonical link preserves SEO value. + +Mentions and citations. Earning mentions in other programs' content. Often happens when the program's pieces are genuinely useful as references; pieces that are generic or surface-level rarely get cited. + +AI search citation. Earning citations from AI search engines. Increasingly important as AI search grows; pieces designed for citation (see `content-repurposing`'s AEO extraction patterns) get cited at higher rates. + +Word of mouth and shares. Audiences sharing pieces with their networks. The hardest to earn deliberately; pieces that are genuinely valuable get shared. + +The earned-channel investment. Earned channels require relationship-building, pitch quality, and content quality. Programs that try to "do PR" with mass-blast pitches earn nothing; programs that invest in genuine relationships earn ongoing channel access. + +Detail in [`references/earned-channel-work.md`](references/earned-channel-work.md). + +--- + +## Paid promotion of organic content + +When boosting organic content earns its keep. + +The pattern. A piece publishes organically; some pieces show strong engagement signals; the program boosts those pieces with paid spend to extend reach. The paid spend is on content that the audience has already validated. + +When boosting fits. + +- The piece has demonstrated organic engagement (high CTR, high time-on-page, organic shares). +- The audience addressable through paid amplification overlaps with the program's target audience. +- The piece's value is clear enough that paid amplification produces engagement, not just impressions. + +When boosting fails. + +- Boosting low-engagement pieces because the calendar said so. Paid spend on content the audience does not engage with produces wasted budget. +- Boosting pieces that drive volume but not value. Pieces that produce clicks but not engagement may be drawing the wrong audience; paid amplification compounds the wrong-audience problem. +- Treating paid content amplification as a substitute for organic distribution. Paid amplifies what organic validated; paid alone produces transactional reach without the audience relationship organic builds. + +The mix. Most strong programs allocate 0-20% of distribution capacity to paid content amplification. Programs heavily dependent on paid promotion are usually programs that have not yet built owned and earned distribution. + +Detail in [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md). + +--- + +## Distribution measurement + +Which channels actually drive value. The discipline that prevents distribution-theater. + +Per-channel metrics. + +- Reach. How many people the channel surfaces the content to. +- Engagement. Click-through, time-on-page, scroll depth, completion rate (varies by format). +- Conversion. Newsletter signups, content downloads, qualified-lead actions, sales-cycle progression. +- Attribution. Which channels drove the audience members who eventually converted. + +Channel-level analysis. + +- Which channels produce the highest engagement-per-distribution-effort? Some channels look impressive (high reach) but produce low engagement. +- Which channels produce the highest conversion? Reach without conversion is vanity; conversion is value. +- Which channels' performance is changing over time? Algorithm shifts, audience migrations, and competitive landscape changes affect channel effectiveness. + +Cross-channel attribution. The same audience member encounters the program on multiple channels before converting. Single-touch attribution misrepresents which channels matter; multi-touch attribution is more accurate but harder to implement. + +The measurement-honest program. Cuts channels that consistently underperform. Increases investment in channels that consistently produce. Adjusts cadence based on engagement patterns, not on arbitrary publishing schedules. + +Detail in [`references/distribution-measurement.md`](references/distribution-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-distribution-failures.md`](references/common-distribution-failures.md). + +- "We publish but reach is low." Hope-and-pray pattern; no deliberate distribution work happening. +- "We post on every channel and engagement is flat." Spam-everywhere pattern; distribution capacity diluted across channels where the audience is not engaged. +- "Newsletter open rates are dropping." Cadence may be wrong, or list quality declining, or content not earning the open. Investigate. +- "Our LinkedIn engagement keeps falling." Possible algorithm shift; possible content-channel mismatch; possible cadence issue. +- "Our PR pitches are getting ignored." Mass-blast pitching; relationships not built; pitches not specific to recipient. +- "We invest heavily in paid but engagement is low." Paid amplifying low-organic-engagement content; paid as substitute for owned development. +- "We do not know which channels are working." Measurement absent; program operating on channel-presence rather than channel-effectiveness. +- "Content publishes but audiences do not see it." Distribution treated as posting; cadence wrong; channels mismatched to audience. +- "We launched campaign distribution but it landed quietly." Campaign rhythm not earned by sustaining cadence; audiences not primed to attention-spike. +- "Our owned audience is small." Long-term investment in owned channels skipped; program dependent on third-party distribution. +- "Earned channels are not producing." Treating earned as automatic; relationships not built; pitches not earning. +- "Paid distribution costs are rising." Auction dynamics on paid platforms; programs heavily dependent on paid see costs rise without offsetting owned/earned investment. + +--- + +## The framework: 12 considerations for content distribution + +When designing or auditing a distribution program, walk these 12 considerations. + +1. Channel-fit, not hope-and-pray or spam-everywhere. Specific channels for specific audiences and formats. +2. Channel taxonomy understood. Owned, earned, paid; sub-types within each; which channels the program actually uses. +3. Audience-channel matching. Where the target audience actually engages, not just where they are present. +4. Content-channel matching. Format fits the channel's conventions and audience expectations. +5. Distribution cadence calibrated. Per-channel frequency, owned-earned-paid mix, sustaining-vs-campaign rhythm. +6. Owned-channel discipline. Newsletter, blog, social channels owned by the program, possibly podcast and community. Long-term investment. +7. Earned-channel work. PR, syndication, mentions, AI-search citation. Relationship investment. +8. Paid promotion of organic content. Boost pieces that have organic engagement; do not substitute paid for owned. +9. Cross-channel attribution. How audiences encounter the program across channels before converting. +10. Per-channel measurement. Reach, engagement, conversion. Channels that underperform get cut. +11. Sustaining-vs-campaign rhythm. Baseline cadence plus campaign spikes for flagship launches. +12. Distribution capacity allocation. Real budget; not done in the cracks. + +The output of the framework is a distribution program where each channel choice is deliberate, each cadence decision matches audience attention, each measurement informs the next decision, and the program's reach grows because the work is concentrated where it produces value. + +--- + +## Reference files + +- [`references/channel-taxonomy.md`](references/channel-taxonomy.md) - Owned, earned, paid with sub-types. Newsletter, blog, social, communities, PR, syndication, mentions, boosted social, syndication networks, sponsored placements. +- [`references/audience-channel-matching.md`](references/audience-channel-matching.md) - Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction. +- [`references/content-channel-matching.md`](references/content-channel-matching.md) - Format-channel fit. The compose-with-repurposing pattern. The format-mismatch failure mode. +- [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md) - Frequency, mix, rhythm. Sustaining vs campaign. Common cadence patterns by program type. +- [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md) - Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. +- [`references/earned-channel-work.md`](references/earned-channel-work.md) - PR, syndication, mentions, AI-search citation, word of mouth. Relationship investment. +- [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md) - Boosting organic content. When paid amplification fits and when it fails. The paid-as-substitute anti-pattern. +- [`references/distribution-measurement.md`](references/distribution-measurement.md) - Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. +- [`references/common-distribution-failures.md`](references/common-distribution-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: distribution is half the work + +Most content programs are production-heavy and distribution-light. The teams producing flagship pieces typically spend 90% of capacity producing and 10% distributing; the resulting reach matches the inverse ratio. Pieces that took 60 hours to produce reach a fraction of their potential audience because the 6 hours allocated to distribution were not enough to do the channel work. + +The discipline is not "distribute more"; it is "distribute deliberately." Channel-fit decisions concentrate distribution work where it produces value. Owned-channel investment builds durable foundations. Earned-channel relationships accumulate over years. Paid promotion amplifies what organic validated. Measurement informs what to keep and what to cut. + +When in doubt about whether a distribution program is ready, ask: are channels chosen for fit, is audience-channel matching deliberate, do formats fit channels, is cadence calibrated, is owned-channel investment in place, are earned-channel relationships being built, is paid amplification on organically-validated pieces, is measurement informing the next decisions? If yes to all of those, the program is real. If no to any, the gap is where reach will fall short of what the production work earned. diff --git a/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md b/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md new file mode 100644 index 0000000..c1d5753 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/audience-channel-matching.md @@ -0,0 +1,172 @@ +# Audience-channel matching + +Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction that prevents distributing on channels where the audience is technically present but not actually paying attention. + +The first and most consequential distribution decision is which channels to invest in. Most programs over-invest in channels with high audience presence but low audience engagement, and under-invest in smaller channels where the audience is genuinely paying attention. The audit shifts capacity to where engagement happens. + +--- + +## The presence-vs-engagement distinction + +A channel where the audience is present is not necessarily a channel where the audience is engaging. + +Presence. Members of the target audience have accounts on the platform. They could see the program's content if they encountered it. + +Engagement. Members of the target audience are actively using the platform for the kind of content the program produces. They click; they comment; they share; they convert. + +The mismatch failure mode. A B2B technical program publishing TikTok content. The audience may have TikTok accounts (presence), but the audience is on TikTok for entertainment, not for B2B technical learning (low engagement for the program's content). The presence creates a false signal that the channel might work; the engagement reality is that distribution capacity goes to a low-return channel. + +The audit question. Not "is the audience on this channel?" but "is the audience consuming this kind of content on this channel?" + +--- + +## Common audience-channel maps + +Mappings that show up repeatedly across program types. Programs should still validate against their own audience research; the maps below are starting points. + +### B2B technical audiences + +Engineers, technical decision-makers, developer-influencers, technical product managers. + +High engagement. LinkedIn (especially long-form posts and articles); X/Twitter (specific technical communities); industry-specific newsletters; specialized podcasts; specific subreddits and Discord servers; GitHub for code-adjacent content; technical conferences and analyst-influenced channels. + +Moderate engagement. YouTube for tutorial and conference-talk content; Hacker News for specific topics; vendor-platform community sites (AWS, Azure, GCP forums; specific tool communities). + +Low engagement. TikTok, Instagram, Facebook for the program's primary content. Some technical professionals consume these for entertainment but rarely for technical content. + +### B2B executive audiences + +C-suite, VPs, senior strategy leaders. + +High engagement. LinkedIn (long-form posts, articles, sometimes video); specific executive newsletters and podcasts; analyst-influence channels (Gartner, Forrester); event-driven media (high-quality conferences, executive roundtables). + +Moderate engagement. Industry-specific publications; some podcasts; X/Twitter for specific topics with executive commentary. + +Low engagement. Most consumer-focused social platforms. Executives often have low time for content consumption; the channels where they engage are concentrated. + +### Consumer mass audiences + +Broad consumer demographics for B2C brands. + +High engagement. Instagram, TikTok, YouTube, Facebook (varies by demographic age and interest). Email newsletter for engaged subscribers. Pinterest for visual-product categories. Specific subreddits for interest-driven topics. + +Moderate engagement. X/Twitter (declining for many consumer demographics). LinkedIn (low for most consumer use cases). + +Low engagement. Most B2B-oriented channels. + +### Niche specialist audiences + +Concentrated audiences within specific domains (cybersecurity professionals, fertility-tracking enthusiasts, specific hobby communities). + +High engagement. Specific subreddits, Discord servers, specialized newsletters and podcasts. Often higher engagement on smaller channels than on broad platforms. + +Moderate engagement. Domain-specific Twitter/X communities; some LinkedIn; YouTube for educational content. + +Low engagement. Broad social platforms where the audience is small fraction of total platform population. + +### Developer audiences + +Software developers across stacks and seniority levels. + +High engagement. GitHub (code-adjacent content); Hacker News (specific topics); specific subreddits; Twitter/X for parts of the dev community; dev-focused podcasts and newsletters; YouTube for tutorial content. + +Moderate engagement. LinkedIn for senior developers; Stack Overflow for Q&A-driven content (different distribution model than programs typically use); Discord servers for specific tools. + +Low engagement. TikTok, Instagram, Facebook, Pinterest for primary content. + +### Founder and startup audiences + +Founders, startup operators, early-stage investors. + +High engagement. Twitter/X (the founder community has historically been engaged here); LinkedIn for some segments; specific newsletters (Lenny's, Substack-based founder newsletters); specific podcasts; YC-adjacent forums. + +Moderate engagement. YouTube for some long-form content; specific subreddits. + +Low engagement. Most mass-consumer platforms. + +--- + +## The audience-channel audit + +A short framework for matching audience to channels. + +1. Define the target audience specifically. Not "marketers" but "B2B SaaS marketing leaders at companies with 50-500 employees, primarily in North America and Western Europe." Specificity unlocks the matching. +2. Map where this audience spends time professionally. Where do they get news, learn new ideas, hear from peers, encounter products? +3. Map where this audience spends time consuming the kind of content the program produces. Different from professional time generally; specific to the content type. +4. Identify channels where the audience engages. Not just where they have accounts. Engagement signals: comments, shares, conversion behaviors. +5. Score channels by engagement potential. High, moderate, low. The high-engagement channels get primary distribution capacity. + +--- + +## Audience-research methods for the audit + +How to actually identify where audiences engage. + +Customer interviews. Ask existing customers where they consume content related to the program's topic. The answers are the audience's revealed-preference distribution map. + +Audience surveys. Quantitative confirmation of channel-engagement patterns. Surveys can over-represent platforms respondents feel they should use; the customer interviews ground-truth the survey data. + +Existing program data. Where does the program's existing audience come from? Referral data, UTM analysis, conversion attribution. Channels that produce existing audience are channels where the audience is engaging with the program. + +Competitive analysis. Where do competing programs distribute? Where do they appear to earn engagement (visible signals: comments, shares, mentions)? Competitive distribution patterns inform but should not dictate the program's choices. + +Industry research. Some industry research firms publish channel-engagement data by audience segment. Useful as starting points; should be triangulated with the program's own data. + +--- + +## The audience-channel mismatch failure mode + +The pattern when audience-channel matching is skipped. + +The symptom. The program publishes consistently on multiple channels. Engagement is flat or declining. Distribution capacity is spread thin. The team cannot identify which channels are working because none of them are working clearly. + +The diagnosis. Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +The cure. Run the audience-channel audit. Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. The total distribution capacity stays the same; the allocation shifts. + +Recovery time. Cutting underperforming channels and concentrating capacity on engaging channels typically produces visible engagement improvements within 4-8 weeks. + +--- + +## When audience-channel maps shift + +Audiences move across channels over time. Maps that fit a program 3 years ago may not fit now. + +Common shifts. + +- Twitter/X engagement has declined for many B2B audiences as the platform has changed; LinkedIn has absorbed some of the shifted attention. +- TikTok has expanded into demographics it did not initially serve. +- Newsletter consumption has grown across most audience types as inbox-based content consumption has become more accepted. +- AI-search citation has emerged as a distribution channel that did not exist meaningfully before 2024. + +The audit cadence. Run the audience-channel audit at least annually. Maps that have not been refreshed for 18+ months are likely outdated. + +--- + +## The audience-channel-content-type triangle + +Audience-channel matching is one of three matching decisions; content-channel matching is another (see `content-channel-matching.md`); the third is content-audience matching (the source piece is for the right audience in the first place). + +The triangle. + +- Audience matches channel. +- Content matches channel. +- Content matches audience. + +The failure modes. + +- Audience-channel mismatch: distribution where the audience is not engaged. +- Content-channel mismatch: format does not fit the channel's conventions. +- Content-audience mismatch: the piece is not actually for the channel's audience even if both fit individually. + +The triangle is what produces channel-fit distribution. All three matchings need to hold for distribution to produce engagement. + +--- + +## Methodology-level choices that stay in the public skill + +The presence-vs-engagement distinction, the common audience-channel maps, the audience-channel audit, audience-research methods, the mismatch failure mode, the map-shift recognition, the audience-channel-content-type triangle. + +## Implementation choices that stay internal + +Specific audience-research surveys and interview templates. Specific UTM tracking and attribution conventions. Specific competitive analysis tooling. Specific channel-engagement scoring rubrics. The team's own audience-segment definitions. These vary by team, audience, and tooling. diff --git a/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md b/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md new file mode 100644 index 0000000..c826a25 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/channel-taxonomy.md @@ -0,0 +1,215 @@ +# Channel taxonomy + +Owned, earned, paid with sub-types. The full taxonomy that grounds channel-fit decisions. + +Programs that distribute well think in terms of the taxonomy. Programs that distribute poorly think in terms of "social media" or "content marketing" without distinguishing the categories. The distinction matters because owned, earned, and paid channels have different cost structures, different reach characteristics, and different roles in a program's distribution mix. + +--- + +## Owned channels + +Channels the program owns and controls. + +### Newsletter and email + +The most direct owned distribution. + +Characteristics. Direct relationship with subscribers. The program controls what sends, when, and to whom. Near-100% delivery to inboxes (modulo spam filtering and engagement-based deliverability adjustments). + +Strengths. No platform algorithm between the program and the audience. Engagement is cleanly measured. Audience commitment signal is strong (people who subscribe and stay subscribed are valuable signal). + +Weaknesses. Slow to grow vs broad-reach social channels. Each subscriber is real work to acquire and retain. + +The newsletter discipline. Cadence consistency, content quality matching subscriber expectations, single-CTA-per-send, deliverability hygiene. See `email-sequences` for the email-specific discipline. + +### Blog and content site + +The program's content home. + +Characteristics. Owned property where pieces live as canonical versions. Search traffic compounds over years. Internal linking earns authority. Direct traffic from audiences who know the property. + +Strengths. Compounding asset. Content that earns search position keeps producing traffic indefinitely. Full design and presentation control. + +Weaknesses. Slow to start producing meaningful traffic. SEO investment is multi-year. Without distribution to the blog, pieces sit unread. + +The blog discipline. Architecture and technical SEO foundations (see `seo-technical`); pillar and cluster organization (see `pillar-content-architecture`); refresh discipline (see `content-refresh-system`); on-page optimization (see `seo-onpage`). + +### Social channels owned by the program + +LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account, etc. + +Characteristics. The program runs the account; the platform controls reach via algorithms. Reach varies by platform algorithm changes, audience size, content engagement signals. + +Strengths. Larger potential audience than newsletter. Algorithmic favor can produce reach beyond follower base when content earns engagement signals. + +Weaknesses. Platform-controlled reach. Algorithm shifts can dramatically reduce reach without warning. Audiences are renting the platform; the program does not own the relationship the way newsletter signals ownership. + +The owned-social discipline. Per-platform conventions; cadence calibrated to platform attention rhythm; content adapted for platform; engagement-signal optimization; account-health hygiene. + +### Podcast + +Owned audio distribution. + +Characteristics. The show feed is owned; subscribers receive new episodes through their podcast app. Episodes also live on the blog with show notes; cross-platform distribution (Spotify, Apple Podcasts, YouTube) extends reach. + +Strengths. Intimate audience relationship. High engagement when audience is loyal. Long-form context for substantive content. Show notes are SEO assets. + +Weaknesses. Production cost is real (audio quality, editing, hosting). Discoverability depends on platform algorithms and word-of-mouth. + +The podcast discipline. See podcast-specific format conventions; show notes as derivative format; consistent episode cadence; cross-platform distribution for reach. + +### Communities + +Slack communities, Discord servers, dedicated discussion forums. + +Characteristics. Direct relationship with members. The program facilitates discussion; members engage with each other and with program content. + +Strengths. Highest-engagement audience the program has. Community feedback informs content and product. Members become advocates. + +Weaknesses. Community management is meaningful work. Communities require continuous facilitation; abandoned communities decay and signal decline. + +The community discipline. Active moderation; sustained value-delivery to members; integration with the broader content program (members get access; program content is shared in community). + +--- + +## Earned channels + +Channels where content reaches audiences via third-party amplification, not paid placement. + +### PR and press coverage + +Journalists, podcasters, newsletter operators who cover the program's content. + +Characteristics. Third parties cover the program's content because it is newsworthy, insightful, or fits their editorial agenda. The program does not pay for coverage; the value exchange is editorial fit. + +Strengths. External authority signal. Reach into audiences the program does not have direct relationships with. Often higher trust signal than program's own distribution. + +Weaknesses. Hard to predict; relationship-dependent; pitches that miss editorial fit produce nothing. + +The PR discipline. Genuine relationship-building with relevant journalists. Pitches specific to recipient and to actual newsworthy content. Quality over quantity; mass-blast pitches earn no coverage and damage future relationship potential. + +### Syndication + +Other publications republishing or excerpting the program's content. + +Characteristics. Programs negotiate with other publications to republish or excerpt their content. Canonical link signaling preserves SEO value. Attribution is mandatory. + +Strengths. Reach into the syndication partner's audience. Some pieces reach more readers via syndication than via owned distribution. + +Weaknesses. Negotiation overhead. Risk of authority dilution if canonical signaling is wrong. Partners may discontinue syndication; the program cannot rely on syndication as primary distribution. + +The syndication discipline. Canonical link tags; clear attribution; partner relationship management; selective syndication (not every piece warrants syndication). + +### Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +Characteristics. External programs reference the program's content as a source. The program's authority signal compounds with each citation. + +Strengths. Compounding authority. Long-term backlink and citation profile that informs SEO and AI-search positioning. + +Weaknesses. Largely outside the program's direct control. The program can produce citation-worthy content (specific data, framework introductions, primary research) but cannot force citation. + +The citation-earning discipline. Produce content with citation hooks: original data, named frameworks, primary research, contrarian-but-defensible positions. Pieces that are generic rarely get cited; pieces that are specifically valuable do. + +### Word of mouth and shares + +Audiences sharing pieces with their networks. + +Characteristics. The program's content becomes part of conversations beyond the program's distribution. Most valuable when sharing happens in private channels (DMs, Slack channels, internal corporate emails) where the program cannot directly track. + +Strengths. Highest-trust distribution. A piece shared by a colleague carries more weight than the same piece in a feed. + +Weaknesses. Hard to measure; hard to engineer deliberately. Pieces that earn word-of-mouth are pieces that are genuinely valuable to the audience. + +The word-of-mouth discipline. Produce content that audiences want to share. Specific, useful, citation-worthy. Avoid generic content that nobody bothers to share even if they read it. + +--- + +## Paid channels + +Channels where paid spending amplifies content. + +### Boosted social posts + +Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. + +Characteristics. The program pays the platform to show the post to additional audiences (often defined by audience targeting parameters). The post still appears as an owned post; the paid spend extends its reach. + +Strengths. Quick to deploy; extends reach of pieces that have demonstrated organic engagement; measurable. + +Weaknesses. Costs accumulate; auction dynamics drive prices up over time; pieces that performed organically may not maintain engagement at scaled paid reach. + +The boost discipline. Boost pieces with strong organic engagement signals; do not boost pieces that did not earn engagement organically; treat boost spend as amplification of validation, not as substitute for organic. + +### Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +Characteristics. The program pays a third-party newsletter to feature its content. The newsletter audience sees the program's content alongside the newsletter's editorial content. + +Strengths. Reach into newsletter audiences with strong attention rhythms. Often higher engagement than broad social paid amplification. + +Weaknesses. Requires negotiation; sponsorship feels different from editorial; price-per-send varies. + +The sponsored-newsletter discipline. Match the newsletter's audience and tone; sponsored content that fits the newsletter feels like value; sponsored content that clashes feels like an ad. + +### Syndication networks + +Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. + +Characteristics. Programs pay per click; content appears on third-party sites in "you may also like" or "recommended for you" placements. + +Strengths. Volume reach at variable cost; geographic and audience targeting. + +Weaknesses. Quality of audience varies; engagement often low; reputation challenges (some networks have brand-safety concerns). + +The syndication-network discipline. Test cautiously; measure beyond clicks (engagement, time-on-page); some networks fit some programs and not others. + +### Search advertising for content + +Paying for clicks on content pieces. + +Characteristics. Less common; usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +Strengths. High-intent audiences; quick reach for high-value content. + +Weaknesses. Cost-per-click on competitive queries; content that converts via paid clicks usually has clear conversion signals. + +The content-search-ads discipline. Reserve for content with clear conversion or lead-capture goals; measure paid traffic against owned-traffic comparison; high-value content only. + +### Sponsored podcast or content placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Characteristics. The program pays to be featured in a third-party podcast or newsletter, often via host-read endorsement. + +Strengths. Host-read endorsements carry strong trust signal. Audiences of niche podcasts and newsletters are highly engaged. + +Weaknesses. Cost varies; production quality matters; mismatched host-program fit damages both. + +The sponsored-placement discipline. Match host audience to program audience; provide hosts with substantive talking points; measure on engagement signals beyond impressions. + +--- + +## Channel mix evolution over program maturity + +Programs at different stages have different channel mixes. + +Early-stage programs. Heavy owned-channel investment (newsletter, blog). Limited earned (relationships not yet built). Limited paid (budget often constrained). The early program is building the foundation. + +Mid-stage programs. Owned channels producing reliable distribution. Earned channels developing (PR relationships, syndication, mentions accumulating). Paid amplification of best organic pieces. + +Mature programs. Owned channels are reliable foundations. Earned channels are significant traffic and authority sources. Paid amplification is strategic, not load-bearing. + +The maturity audit. Programs heavily dependent on paid distribution often have under-invested in owned and earned. The dependency is visible: when paid budgets cut, reach collapses; when paid costs rise (as they do over time on auction-based platforms), program effectiveness degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The owned/earned/paid taxonomy with sub-types, the characteristics and disciplines per sub-type, the channel mix evolution by program maturity, the maturity audit. + +## Implementation choices that stay internal + +Specific platform tooling per channel. Specific community management software. Specific PR-relationship CRMs. Specific paid-platform configurations and bidding strategies. Specific syndication-network vendor selections. The team's own conventions for channel-mix targets at different program stages. These vary by team, budget, and program shape. diff --git a/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md b/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md new file mode 100644 index 0000000..92119ff --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/common-distribution-failures.md @@ -0,0 +1,193 @@ +# Common distribution failures + +Twelve-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most distribution failures share a single root, which is treating distribution as posting-after-publishing rather than as the equal half of the work. + +--- + +## Failure 1: Hope-and-pray (publish and wait) + +Symptom. The program publishes consistently. Reach is low. The team is unclear why; the content seems strong. + +Diagnosis. No deliberate distribution work. Publishing is treated as the end of the work; audiences are expected to find the content via search, social, and word of mouth without proactive distribution. + +Cure. Apply the channel-fit discipline. Identify which channels the audience engages on; distribute deliberately on those channels with appropriate format adaptation. Treat distribution as half the work. + +Capacity recovery. Programs that shift from hope-and-pray to deliberate distribution typically see 2-5x reach improvements within 8-12 weeks. + +--- + +## Failure 2: Spam-everywhere + +Symptom. The program posts on every channel: LinkedIn, X, Facebook, Threads, Bluesky, Instagram, TikTok, plus 5 emails per week, plus paid promotion on every platform. Engagement is flat across all channels. + +Diagnosis. Distribution capacity diluted across channels where the audience is not engaged. Each channel gets cursory attention; none gets enough to produce real engagement. + +Cure. Apply the audience-channel matching discipline. Cut channels where the audience is present but not engaged. Concentrate capacity on channels that produce engagement. + +Recovery time. Cutting underperforming channels and concentrating capacity typically produces visible engagement improvements within 4-8 weeks. + +--- + +## Failure 3: Newsletter open rates declining + +Symptom. The newsletter open rate has declined from 35% to 22% over 6 months. Subscribers are not opening sends. + +Diagnosis. Multiple possible causes. Cadence may be wrong (too aggressive or too sparse). List quality may be declining (lapsed subscribers depressing engagement signal). Subject lines may not be earning the open. Content may not be matching subscriber expectations. + +Cure. Diagnose first. Pull cohort data: are recent subscribers opening at higher rates than long-term subscribers (suggests content fit decline)? Are sends with specific subject-line patterns performing better (suggests subject line issue)? Is open rate consistent across send-times (rules out timing)? + +Apply the relevant fix: list pruning for lapsed subscribers; subject-line improvement; cadence adjustment; content recalibration. + +--- + +## Failure 4: LinkedIn engagement falling + +Symptom. LinkedIn engagement on the program's posts has declined. Comments, shares, and reach signals all lower than 6 months ago. + +Diagnosis. Multiple possible causes. Algorithm shift; content-channel mismatch; cadence issue; account-health degradation. LinkedIn algorithm changes have affected many programs over the past several years. + +Cure. Audit content quality (does it match what worked previously?). Audit cadence (within platform-rewarded range?). Check account-health signals (engagement on others' content, not just own posts; profile completeness; consistent branding). If algorithm shifts are the cause, content patterns may need recalibration to fit current algorithmic preferences. + +--- + +## Failure 5: PR pitches ignored + +Symptom. The program pitches journalists for coverage. Most pitches get ignored. Coverage is rare. + +Diagnosis. Mass-blast pitching, or relationships not built before pitching, or pitches not specific to recipient. + +Cure. Apply the relationship-first PR principle (see `earned-channel-work.md`). Build relationships with relevant journalists over months before pitching. Pitch specific to recipient with reference to their recent work. Reduce pitch volume; increase pitch quality. + +Timeline. PR relationships build over 1-3 years. Programs in mass-blast mode cannot fix this in a quarter; the cure is multi-year. + +--- + +## Failure 6: Heavy paid investment, low engagement + +Symptom. The program spends significantly on paid amplification. Engagement metrics are low. Cost-per-engagement keeps rising. + +Diagnosis. Paid amplification is amplifying low-organic-engagement content. Or paid is substituting for owned-channel investment. Or both. + +Cure. Apply the boost-organic pattern. Only boost pieces that have demonstrated organic engagement. Reduce paid spend on pieces without organic validation. Reallocate capacity toward owned-channel investment for long-term durability. + +--- + +## Failure 7: No measurement + +Symptom. The team operates on intuition about which channels are working. Different team members have different intuitions. Decisions about cadence, channel mix, and capacity are not informed by data. + +Diagnosis. No measurement infrastructure or no measurement-to-decision discipline. + +Cure. Establish per-channel metrics; channel-level analysis; cross-channel attribution. Quarterly measurement reviews that produce specific decision changes. See `distribution-measurement.md` for the discipline. + +--- + +## Failure 8: Posting without distribution + +Symptom. Content publishes. The piece appears on the blog and is shared once on social. The team considers distribution complete. + +Diagnosis. Distribution is treated as the act of posting. The work of getting content TO audiences is not happening. + +Cure. Plan distribution at production time. Each piece has a distribution plan: which channels, what cadence, what cross-channel co-promotion. Distribution is part of the production work, not an afterthought. + +--- + +## Failure 9: Campaign launches landing quietly + +Symptom. The team prepared a flagship launch with significant cross-format coordination. Launch day arrives. Engagement is muted. + +Diagnosis. Sustaining cadence was insufficient before the launch. Audiences were not warm; the campaign moment did not feel like a campaign moment because no audience habit primed it. + +Cure. Build sustaining cadence first. Campaign rhythm is earned by sustaining cadence. Programs that try to spike attention without sustaining baseline produce limited campaign engagement. + +--- + +## Failure 10: Owned audience small after years + +Symptom. After 2-3 years of program operation, the newsletter has 800 subscribers; the blog gets 5,000 monthly visits; the community is small. + +Diagnosis. Long-term investment in owned channels was skipped. Program reach (if there is reach) is rented from third parties. + +Cure. Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +--- + +## Failure 11: Earned channels not producing + +Symptom. The program has occasional coverage from third parties but no reliable earned-channel reach. Mentions are rare; syndication is informal; AI-search citation rates are low. + +Diagnosis. Earned channels are being treated as automatic. Relationship investment, pitching discipline, and citation-hook content design are not in place. + +Cure. Apply the earned-channel investment discipline. Specific capacity to relationship-building, pitching, syndication, citation tracking. Investment compounds over years. + +--- + +## Failure 12: Paid distribution costs rising + +Symptom. Paid amplification was producing acceptable cost-per-engagement 12-18 months ago. Costs have risen 50-100% since then. Engagement is similar; costs are higher. + +Diagnosis. Auction dynamics on paid platforms. Programs heavily dependent on paid see costs rise without offsetting owned/earned investment that would reduce paid dependence. + +Cure. Build owned and earned channels to reduce paid dependence. Within paid, focus on the highest-ROI placements; cut lower-performing paid spend. Recognize that paid costs typically rise over time on auction-based platforms; budget assumptions should account for this. + +--- + +## Failure 13: Channels mismatched to audience + +Symptom. The program is present on multiple channels. Engagement is low across most of them. The team is confused because the channels seemed obvious choices. + +Diagnosis. Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +Cure. Run the audience-channel audit (see `audience-channel-matching.md`). Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. + +--- + +## Failure 14: Cadence too aggressive + +Symptom. Email subscribers are unsubscribing at higher rates. Social engagement is declining despite increased posting volume. The team is producing more content per week than ever; reception is worse. + +Diagnosis. Cadence has exceeded audience attention norms. The team is over-publishing. + +Cure. Reduce cadence to channel norms. Test reduced frequency for 6-8 weeks; observe whether engagement improves and unsubscribes slow. Most programs benefit from disciplined cadence rather than maximal cadence. + +--- + +## Failure 15: Cadence inconsistent + +Symptom. The program publishes 3 times in a week, then nothing for 3 weeks, then 5 times in 4 days. Audiences cannot develop habit. + +Diagnosis. No cadence discipline. Production happens when capacity allows; distribution follows production rather than following audience-attention rhythm. + +Cure. Establish cadence targets per channel. Build content calendars that smooth publication across the period. Capacity that produces content unevenly should distribute the publication evenly even if production was uneven (held pieces release on schedule). + +--- + +## Failure 16: No campaign rhythm + +Symptom. The program runs sustained cadence consistently. Flagship launches happen. The launches receive routine treatment; no campaign coordination produces outsized attention. + +Diagnosis. Campaign rhythm has not been built. The program has sustained cadence but no concentrated moments. + +Cure. Plan 4-12 campaign moments per year. Each campaign concentrates cross-format distribution for 4-6 weeks. The campaigns are earned by the sustaining cadence; together they produce the rhythm strong programs use. + +--- + +## The cross-cutting pattern + +Most distribution failures share a single root: treating distribution as posting-after-publishing rather than as the equal half of the work. + +Posting-after-publishing thinking treats publication as the end of the work. The piece goes live; minimal distribution work follows; reach is whatever happens organically. Output: most pieces reach a fraction of their potential audience. + +Distribution-as-half-the-work thinking treats distribution as a discipline equal to production. Channel choices are deliberate; cadence is calibrated; owned-earned-paid mix is strategic; measurement informs decisions. Output: pieces reach engaged audiences because the distribution work earned the reach. + +The fix for almost any distribution failure is the same: treat distribution as a real discipline, not as posting. Allocate capacity proportionate to its importance. The capacity required is significant; the value extracted is also significant. + +--- + +## Methodology-level choices that stay in the public skill + +The sixteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the distribution-as-half-the-work framing. + +## Implementation choices that stay internal + +Specific tooling for distribution tracking. Specific reporting templates for distribution outcomes. Specific reviewer training on per-channel conventions. Specific automation that flags distribution gaps. The team's own conventions for failure-pattern detection in their distribution program. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md b/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md new file mode 100644 index 0000000..6fcbf13 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/content-channel-matching.md @@ -0,0 +1,181 @@ +# Content-channel matching + +Format-channel fit decisions. The compose-with-repurposing pattern. The format-mismatch failure mode that produces low engagement even when audience and channel match. + +Audience-channel matching answers "where is the audience?" Content-channel matching answers "does this format fit this channel?" Both must hold for distribution to produce engagement. + +--- + +## Format-channel fit examples + +How specific formats land on specific channels. + +### Long-form analytical text + +Strong fit. Newsletter (long-form-tolerant subscribers expect depth). Owned blog (long-form is the blog's native register). LinkedIn long posts (the platform rewards substantive long content). X threads (when the community fits and the thread is well-paced). + +Weak fit. Instagram (the format does not support text-driven content as primary). TikTok (audiences come for short-form video, not long text). Most podcast platforms (audio is the format; long-form text is not what audiences came for). + +### Short-form video + +Strong fit. TikTok, Reels, YouTube Shorts (the platforms' native formats). Increasingly LinkedIn video (the platform has invested in video). Twitter/X video for some communities. + +Weak fit. Newsletter (where text leads and video is a supplement). Owned blog (where written long-form leads). Most podcast platforms (audio-only consumption). + +### Statistic-driven content + +Strong fit. Social with quote-graphic visual treatment (LinkedIn, X, Instagram with the right design). AI search snippets (search engines weight statistics with named sources). Podcast mentions (host-read statistic + source citation works well). + +Weak fit. As primary format on owned blog (where context develops the stat; the stat alone is thin). Newsletter as the entire content (the stat without development underdelivers). + +### Conversational expert content + +Strong fit. Podcasts (the format is conversational by design). Video interviews (long-form video supports the conversational depth). Long social threads on platforms where substantive content is rewarded. + +Weak fit. Short-form video (the conversational depth does not fit 60-second windows). Newsletter (where edited prose fits better than conversational transcript). + +### Reference content (definitions, glossaries, FAQs) + +Strong fit. Owned blog and FAQ pages (canonical home). AI search snippets (citation-ready). Documentation sites (where reference is the format). + +Weak fit. Most social channels (reference content does not earn engagement on attention-driven feeds). Podcasts (reference content does not work in audio). + +### Visual narrative content (case studies with custom visuals, illustrated guides) + +Strong fit. Instagram (visual-first). Pinterest (visual reference). Owned blog with strong design treatment. + +Weak fit. Podcast (audio cannot carry visual content). Newsletter (most newsletters do not support rich visual treatment). + +--- + +## The compose-with-repurposing pattern + +When the audience is on a channel but the source format does not fit, the right answer is often to repurpose into a format that does fit. + +The pattern. + +- Source piece: 5,000-word whitepaper. +- Audience: present and engaged on TikTok (consumer-oriented program; younger demographic). +- Direct distribution: 5,000-word whitepaper does not fit TikTok. +- Compose-with-repurposing: produce 60-second video derivatives from the whitepaper's key claims, framed for TikTok conventions. Distribute the derivatives on TikTok; keep the whitepaper as the source for audiences who want depth. + +The discipline. Distribution is downstream of repurposing. A program with strong audience-channel matching but weak content-channel matching solves it through repurposing, not through distributing inappropriate formats. + +See `content-repurposing` for the cross-format adaptation discipline. The two skills compose: repurpose first to fit the channel; then distribute on the channel. + +--- + +## The format-mismatch failure mode + +The pattern when content-channel matching is skipped. + +The symptom. The program is present on the right channels (audience-channel matching held). Engagement is still low. The team is confused because the channels seem right but the content is not landing. + +The diagnosis. The format does not fit the channel even though the audience is there. The audience is on the channel for a different kind of content; the program's content does not match the channel's content expectations. + +The cure. Identify the format-channel mismatches. For channels with strong audience-channel match but weak content-channel match, repurpose to fit. For channels where neither matching holds, cut the channel. + +Recovery time. Format-mismatch fixes through repurposing typically produce visible engagement improvements within 4-12 weeks as the new format derivatives accumulate. + +--- + +## Format conventions per channel + +Beyond the strong/weak fit, each channel has specific conventions that distinguish good fit from forced fit. + +### LinkedIn long-form posts + +- 800-2,500 character body. +- First 1-3 lines must hook (truncation point). +- Short paragraphs, white space, occasional emphasis. +- Specific argument or position; vague observations underperform. +- Engagement-earning closes (questions, polarizing claims, specific examples). + +### X/Twitter threads + +- 5-15 posts typical for substantive threads. +- First post must hook; the thread is read sequentially. +- Each post is a complete thought, not a 280-character split of a longer thought. +- Conclusion specific. + +### Newsletter (substantive content) + +- 200-800 words for typical sends; 1,500-3,000 for engaged-audience long-form newsletters. +- Subject line and preheader bear most engagement load. +- Plain prose paragraphs render reliably. +- Single clear CTA per send. + +### Podcast + +- Spoken-language sentence structure. +- Conversational pacing with examples and asides. +- Show notes with links and structured summary. +- Consistent episode length; audiences develop expectations. + +### Owned blog + +- Format depends on the source-piece type; long-form articles, listicles, definitive guides, case studies, etc. +- SEO conventions: target keyword in title and headings, internal linking, schema markup. +- Visual rhythm appropriate to length. + +### TikTok / Reels / Shorts + +- 60-90 seconds typical. +- Hook in first 1-2 seconds. +- Captions essential. +- Single specific point. +- Visual variation, motion, or text-on-screen design. + +### Instagram (feed posts) + +- Visual-first; images carry the post's immediate impact. +- Caption supplements; not all viewers expand caption. +- Conventions vary by subgenre (educational carousels, product photography, lifestyle imagery). + +### YouTube (long-form) + +- 8-30 minutes typical for substantive content. +- Pacing for spoken delivery. +- Visual variation. +- Audio quality matters more than video quality. +- Thumbnail and title bear most click-through load. + +### AI-search snippets + +- 40-80 words for FAQ-style; 100-200 words for paragraph-style. +- Standalone meaning. +- Named-source citations. +- Specific framings. +- Schema markup where applicable. + +--- + +## Format adaptation per channel within a single source + +A worked example: a research report that distributes across multiple channels. + +Source. 8,000-word research report on B2B paid media benchmarks. + +Distribution by channel with content adaptation. + +- Owned blog. Full report as the canonical version. Schema-marked. Internal-linked from related pieces. Sections support deep linking. +- Newsletter (substantive subscribers). A 1,200-word digest sending the report's key findings, with a clear CTA to read the full report. +- LinkedIn long posts. 4-6 long-form posts, each developing one finding from the report. Each post includes the report's most relevant statistic with named-source attribution. +- X threads. 2-3 threads from the report, each focused on a specific finding. Threads link to the report. +- Podcast. One episode interviewing a practitioner who has applied the report's findings, with the report as the show's spine. +- TikTok / Reels. Statistic-driven 60-second videos, one per key statistic. Custom graphic treatment for each. +- AI-search snippets. 15-20 FAQ extractions from the report. Schema-marked FAQ page on the owned property. +- Promoted newsletter. Sponsored placement in 1-2 industry newsletters whose audience overlaps with the report's target. +- Boosted social. Boost the LinkedIn posts that earn the highest organic engagement. + +The example shows the compose-with-repurposing pattern in practice. The source is one piece; the distribution adapts per channel. The cross-format set composes with the channel choices to produce engagement appropriate to each channel's conventions. + +--- + +## Methodology-level choices that stay in the public skill + +The format-channel fit examples, the compose-with-repurposing pattern, the format-mismatch failure mode, the format conventions per channel, the worked example of multi-channel distribution from one source. + +## Implementation choices that stay internal + +Specific platform tooling for format-specific publishing. Specific design templates per channel-format combination. Specific automation for cross-channel scheduling. The team's own conventions for format-fit decisions when ambiguous. These vary by team, tooling, and brand voice. diff --git a/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md b/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md new file mode 100644 index 0000000..cc20c8b --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/distribution-cadence-patterns.md @@ -0,0 +1,183 @@ +# Distribution cadence patterns + +Frequency, mix, rhythm. Sustaining vs campaign rhythm. Common cadence patterns by program type. The audit that catches cadence mismatches. + +Cadence is the rhythm of a program's distribution: how often each channel publishes, what mix of owned-earned-paid, and how steady-state baseline relates to campaign spikes. The wrong cadence produces predictable engagement decline: too aggressive exhausts audiences; too sparse loses connection; mismatched to channel attention rhythm produces underperformance at any frequency. + +--- + +## Cadence axes + +Three axes that together define a program's distribution cadence. + +Frequency per channel. How often the program publishes to each channel. Newsletter weekly vs bi-weekly. LinkedIn 3 posts per week vs 1 per week. X 5-10 posts per week vs occasional. The frequency per channel is calibrated to the channel's audience attention rhythm. + +Mix. What proportion of distribution is owned vs earned vs paid. What proportion of pieces are original vs derivative. The mix reflects program strategy: owned-heavy programs invest in long-term audience-building; paid-heavy programs prioritize immediate reach. + +Rhythm. Sustaining baseline cadence vs campaign spikes. Most programs have a steady-state rhythm punctuated by occasional campaign moments around flagship launches. The rhythm shape determines how audiences experience the program. + +--- + +## Common cadence patterns by program type + +Cadences that show up repeatedly across program shapes. + +### B2B program with content-led demand generation + +Newsletter. Weekly. Substantive sends; subscribers expect depth. + +Blog. 2-4 posts per week. Mix of new pieces, refresh updates, and cross-format derivatives. + +LinkedIn. 3-5 posts per week. Mix of long-form posts, link drops to blog content, occasional video. + +X/Twitter. 5-10 posts per week. Higher cadence than LinkedIn; mix of original observations, links, and replies. + +Podcast. Bi-weekly or weekly episodes. + +Earned channels. Pitches and PR work continuous; coverage when earned. + +Paid amplification. Boost of best-performing organic pieces; occasional sponsored newsletter sends. + +Campaign rhythm. Quarterly spikes around flagship launches: cross-format wave for 4-6 weeks per launch. + +### Consumer brand with broad-audience reach goals + +Newsletter. Weekly or 2x weekly depending on subscriber engagement. + +Blog or content site. 1-2 posts per week. + +Instagram. Daily content (often a mix of feed posts, stories, and reels). + +TikTok. 2-4 posts per week. + +YouTube. Weekly long-form video plus shorts. + +Earned channels. PR for major moments; influencer relationships continuous. + +Paid amplification. Continuous; brands often run paid amplification on most major content as part of standard practice. + +Campaign rhythm. Heavier campaign spikes around product launches, seasonal moments, and brand events. + +### Niche specialist program with concentrated audience + +Newsletter. Weekly or bi-weekly. Substantive sends; the audience is concentrated and engaged. + +Blog. 1-2 posts per month. Quality-focused; depth over volume. + +Specific platforms (one or two). 2-3 posts per week on the platforms where the niche audience engages. + +Podcast (if applicable). Bi-weekly or monthly episodes. + +Earned channels. High prioritization; relationships with niche publications and influencers compound. + +Paid amplification. Selective; most niche programs benefit more from earned-channel investment than from paid amplification. + +Campaign rhythm. Less pronounced than broader programs; sustaining cadence is the dominant rhythm. + +### Founder-led brand with personal-brand element + +Newsletter. Weekly; founder-voice register; personal insight alongside program content. + +LinkedIn. Daily posts (or near-daily). Founder voice; personal observations alongside program content. + +X/Twitter. Daily posts with conversation engagement. + +Podcast. Often the founder hosts; weekly episodes. + +Earned channels. Founder builds relationships personally; PR coverage often person-driven. + +Paid amplification. Selective; the program builds on organic reach earned by founder authority. + +Campaign rhythm. Less formal campaigns; the program reads more as continuous founder voice than as discrete campaign moments. + +--- + +## Sustaining vs campaign rhythm + +The relationship between baseline cadence and campaign spikes. + +Sustaining cadence. The baseline rhythm. Audiences expect this cadence; deviations affect engagement. Sustaining cadence builds audience habit (subscribers who expect a Tuesday send keep paying attention; subscribers who get inconsistent sends start ignoring even the good ones). + +Campaign rhythm. Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +The relationship. Campaign rhythm is earned by sustaining cadence. Programs without sustaining cadence cannot run effective campaigns; the audiences are not warm. Campaigns that spike out of nowhere produce limited engagement because no audience habit primes the moment. + +The balance. Strong programs run mostly sustaining cadence with occasional campaign spikes. The campaign spikes are 4-6 weeks total, 4-12 times per year. Programs running continuous "campaign" rhythm exhaust audiences; programs running only sustaining without campaigns miss the moments where flagship work could earn outsized attention. + +--- + +## Per-channel cadence tuning + +Each channel rewards different cadences. Cadence tuning matches channel-specific norms. + +Newsletter. Weekly is the most common B2B cadence. Bi-weekly works for higher-investment formats. Daily works for highly-engaged subscriber bases. The cadence should be predictable: subscribers should know roughly when to expect sends. + +LinkedIn. Algorithmic favor rewards 1-2 posts per day for individual accounts; company pages typically post less frequently (2-5 posts per week). Lower cadences (1-2 per week) work but limit reach. + +X/Twitter. The platform rewards higher cadence than other platforms. 5-15 posts per day is normal for engaged accounts; less can work but limits reach. + +Instagram. 1 post per day is common for engaged consumer accounts; 3-5 per week works for B2B and niche programs. Stories and reels often have higher cadence than feed posts. + +TikTok. Algorithmic recommendation rewards higher cadence; 1+ posts per day typical for accounts trying to grow. + +YouTube. Weekly long-form video is the upper-frequency norm; many channels publish less frequently. Shorts can publish more often (multiple per week). + +Podcast. Weekly is the most common cadence; bi-weekly works for higher-investment shows; daily works for high-volume formats (news-style podcasts). + +Owned blog. SEO programs benefit from regular publishing (2-4 posts per week typical for active programs); less frequent publishing limits the program's compounding traffic potential. + +--- + +## The cadence audit + +A short framework for auditing a program's cadence. + +1. Pull current cadence per channel over the last 90 days. What is the program actually doing? Often differs from the program's stated cadence target. +2. Compare to channel-specific norms. Are channel cadences within the engagement-rewarding range, or are they too sparse or too aggressive? +3. Identify cadence inconsistencies. Are there gaps where the program goes silent for weeks, then spikes? Inconsistency damages audience habit even when total volume is similar. +4. Match cadence to capacity. Is the program able to sustain the current cadences, or is it running unsustainably? +5. Identify the campaign rhythm. When were the last 3 flagship launches? Did sustaining cadence support them? Did campaigns earn outsized attention? + +The audit produces a calibration plan: which cadences to maintain, which to adjust, where the program is over-investing or under-investing. + +--- + +## Cadence anti-patterns + +Inconsistent cadence. 3 posts in one week, then nothing for 3 weeks. Audiences cannot develop habit; the program disappears between bursts. + +Volume-driven cadence. "We need to post X times per week" without reference to channel norms or audience attention. Volume without engagement is presence; presence without engagement is wasted capacity. + +Identical cadence across channels. Treating LinkedIn, X, TikTok, and newsletter all on the same cadence ignores channel-specific norms. Each channel has a different attention rhythm. + +No campaign rhythm. Pure sustaining cadence with no spikes. Flagship launches receive routine treatment; the moments where the program could earn outsized attention pass without the campaign coordination they warrant. + +Continuous campaign rhythm. Pure campaign rhythm with no sustaining baseline. Audiences never develop habit; every "launch" feels like another launch in a continuous stream of launches. + +Cadence beyond capacity. The team commits to LinkedIn daily, X 10x per day, newsletter twice weekly. Capacity cannot sustain; cadence drifts; audiences notice the drift. + +--- + +## When to adjust cadence + +Signals that cadence needs change. + +Engagement declining steadily on a channel. May indicate cadence too aggressive (audience fatigue) or too sparse (audience disengagement) or content-fit issues (different problem). Investigate. + +Subscriber unsubscribes spiking on newsletter. Cadence too aggressive, or content quality declining, or both. Cure depends on diagnosis. + +Algorithm changes on a platform. Some platform algorithm shifts reward different cadences. Adjust based on observed engagement signals. + +Capacity changes. Team grows or shrinks; cadence should match sustainable capacity. Programs with shrinking teams that maintain prior cadence often produce drift in quality. + +Audience-research findings. New data about audience attention rhythms. Adjust cadence to fit revealed audience patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The cadence axes, common cadence patterns by program type, sustaining-vs-campaign rhythm, per-channel cadence tuning, the cadence audit, the cadence anti-patterns, the signals for cadence adjustment. + +## Implementation choices that stay internal + +Specific scheduling tools the team uses. Specific cadence-tracking dashboards. Specific cadence-by-channel calendars. The team's own conventions for cadence-vs-quality tradeoffs when capacity is constrained. These vary by team, tooling, and program shape. diff --git a/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md b/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md new file mode 100644 index 0000000..c1d73f9 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/distribution-measurement.md @@ -0,0 +1,203 @@ +# Distribution measurement + +Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. The discipline that prevents distribution-theater and turns distribution into a learning system. + +Distribution without measurement runs on assumption. Channels stay in the mix because they have always been in the mix; cadence stays at current levels because nobody has asked whether it is right; paid spend continues because budget exists. Measurement is the discipline that surfaces what is actually working and what is not. + +--- + +## Per-channel metrics + +Metrics organized by what they reveal about a channel's effectiveness. + +Reach metrics. + +- Impressions: how many times the content was shown. +- Unique reach: how many unique people saw the content. +- Audience growth: how the channel's owned audience size is changing. + +Engagement metrics. + +- Click-through rate (CTR): clicks divided by impressions. +- Time-on-page: how long visitors stay on the linked content. +- Scroll depth: how far down the content visitors scroll. +- Completion rate: for video and audio, what percentage finishes. +- Comment, share, and reaction signals on social. +- Reply rate on email. + +Conversion metrics. + +- Newsletter signups attributed to the channel. +- Content downloads attributed to the channel. +- Qualified-lead actions (form submissions, demo requests, free-trial starts). +- Sales-cycle progression for B2B programs. +- Attributed revenue for revenue-tracked programs. + +Channel-health metrics. + +- Audience retention rate (subscribers staying vs unsubscribing). +- Engagement-rate trend over time (rising, stable, falling). +- Algorithm-favor signals (for platform-controlled channels). +- Deliverability rate (for email). + +--- + +## Channel-level analysis + +Aggregating metrics into channel effectiveness assessments. + +Engagement-per-distribution-effort. + +- Some channels look impressive (high reach numbers) but produce low engagement. +- Some channels produce moderate reach but very high engagement. +- The channels that compound value are usually the engagement-heavy ones, not the reach-heavy ones. + +Conversion-per-channel. + +- Reach without conversion is vanity. Conversion is value. +- Channels driving conversion at favorable cost (whether owned-channel investment cost or paid-channel spend) earn their place in the mix. +- Channels driving impressive reach but no conversion may be building brand awareness (which is real value) or producing nothing of value (which is wasted capacity). + +Trend over time. + +- Channels' performance changes. Algorithm shifts, audience migrations, competitive landscape changes affect channel effectiveness. +- A channel that was effective 18 months ago may be underperforming now. +- A channel that was marginal 18 months ago may be the program's strongest now. +- Quarterly review of channel-level trends catches these shifts. + +The relative-effectiveness audit. + +Rank channels by engagement-per-effort and by conversion-per-effort. Channels at the top of both rankings are the program's strongest; channels at the bottom of both are candidates for cutting or restructuring. + +--- + +## Cross-channel attribution + +The audience member encounters the program on multiple channels before converting. Attribution should reflect this reality. + +Single-touch attribution failures. + +- Last-touch attribution. Credits the last channel before conversion. Misrepresents which channels actually drove the audience relationship; usually overweights the conversion channel (often newsletter or direct site visit) and underweights the discovery channels. +- First-touch attribution. Credits the first channel of contact. Misrepresents the role of nurturing channels; usually overweights discovery channels and underweights nurturing channels. + +Multi-touch attribution patterns. + +- Linear attribution. Equal weight to all touchpoints. Simple; usually a step up from single-touch. +- Time-decay attribution. More weight to touchpoints closer to conversion. Reflects the commonsense intuition that recent touches matter more than distant ones. +- Position-based attribution. Significant weight to first and last touch; remaining weight distributed across middle touches. Reflects the importance of discovery and conversion moments. +- Data-driven attribution. Algorithmic weighting based on observed conversion patterns. Most accurate; requires sufficient data and tooling. + +The attribution honesty discipline. + +- Attribution models are simplifications. None is "correct"; all are useful approximations. +- Programs should pick an attribution model and stay consistent. Switching attribution models produces apparent performance changes that are not real. +- Cross-reference attribution data with other signals (subscriber surveys, sales conversation reports). Triangulation is more honest than relying on attribution data alone. + +--- + +## The measurement-honest program + +Discipline that turns measurement into a decision-making input rather than into reporting theater. + +Cuts channels that consistently underperform. + +- A channel underperforming for 2-3 quarters is a real signal, not noise. +- Cutting underperforming channels reallocates capacity to channels that produce. +- The decision is hard because cutting feels like admitting failure; programs that cut decisively outperform programs that maintain everything indefinitely. + +Increases investment in channels that consistently produce. + +- Strong channels deserve disproportionate investment. +- Programs often spread investment evenly across channels regardless of performance; the measurement-honest discipline allocates investment to where return is highest. + +Adjusts cadence based on engagement patterns. + +- Cadence that is too aggressive shows up in declining engagement and rising unsubscribes. +- Cadence that is too sparse shows up in audience-habit decay. +- Engagement patterns inform cadence adjustments. + +Calibrates paid spend based on organic validation. + +- Boost what organic validates. +- Reduce or eliminate paid spend on content that does not earn organic engagement. +- Paid spend should be a function of organic signal, not a function of available budget. + +--- + +## The measurement-theater anti-pattern + +When measurement is performed without informing decisions. + +The pattern. The team produces quarterly reports with channel-level metrics. Reports are presented to leadership. Decisions are not changed based on the reports. Underperforming channels stay in the mix; over-performing channels do not get additional investment. The program continues as it would have continued without the measurement. + +Why it happens. + +- Measurement is treated as performance theater rather than as decision input. +- Leadership signals that all channels should continue (political pressure, sunk cost, brand reasons). +- The team has measurement capacity but lacks decision-authority over distribution. + +The cure. Tie measurement to specific decisions. Each quarter, the measurement review produces a list of changes: cuts, additions, cadence adjustments, capacity reallocations. Reviews without decisions are theater. + +--- + +## Common measurement failures + +No measurement. Distribution runs on assumption. Channels stay in the mix because they always have. Cadence and capacity allocation persist regardless of effectiveness. + +Measurement without action. Measurement is performed; decisions are not changed. The program runs as if no measurement happened. + +Vanity metrics. Reach and impressions reported as primary success metrics. Engagement and conversion underreported. The program looks like it is working when it may not be. + +Single-touch attribution dominance. All attribution analysis runs on last-touch or first-touch. The realities of multi-touch journeys are missed. + +No trend analysis. Channel performance reported in quarterly snapshots; trends across quarters are not surfaced. Channel decay is detected late. + +Cross-program comparison failures. The program compares itself to industry benchmarks without context. Benchmark numbers from other industries or audience segments may not apply; comparison produces false signals. + +--- + +## Measurement infrastructure + +The tooling and processes that support measurement. + +Analytics platform. Web analytics that tracks per-channel traffic, engagement, and conversion. Standard requirement for any program with a content site. + +Email analytics. Open rates, click-through rates, unsubscribe rates, deliverability rates. Standard for any program with a newsletter. + +Social analytics. Per-platform analytics from each social platform; supplemented by social-listening tools where the program tracks mentions and shares beyond direct posts. + +Attribution tooling. From simple UTM tracking and Google Analytics multi-touch reports to sophisticated attribution platforms (depending on program scale and complexity). + +Channel-specific dashboards. Programs often build per-channel dashboards that surface the metrics most relevant to that channel's optimization. + +Cross-channel rollup. A program-level dashboard that aggregates channel-level data into a coherent view of distribution effectiveness. + +The infrastructure cost is real; the alternative (running distribution without measurement) is more expensive over time because capacity gets allocated to wrong places. + +--- + +## Measurement cadence + +When to measure what. + +Continuous. Some metrics update daily or weekly: website traffic, social engagement, email opens. The team monitors these continuously. + +Weekly. Per-channel summaries of recent performance. Catches sharp decay or sharp improvements early. + +Monthly. Channel-level rollup. Detects trends developing across multiple weeks. + +Quarterly. Strategic measurement review. Decisions about channel cuts, additions, cadence adjustments, capacity reallocations. + +Annual. Program-level measurement review. Strategic shifts in channel mix, attribution-model adjustments, capacity reallocations across the program. + +The cadence should match the decision cadence. Programs with monthly capacity-allocation decisions need monthly measurement; programs with quarterly decisions need quarterly measurement. + +--- + +## Methodology-level choices that stay in the public skill + +The per-channel metric categories, channel-level analysis approaches, cross-channel attribution patterns, the measurement-honest discipline, the measurement-theater anti-pattern, common measurement failures, infrastructure requirements, measurement cadence. + +## Implementation choices that stay internal + +Specific analytics platforms (the team's chosen GA configuration, alternative platforms, attribution tools). Specific dashboard designs and reporting templates. Specific UTM tagging conventions. Specific attribution-model parameters tuned for the program. The team's own conventions for benchmark comparisons. These vary by team, tooling, and program scale. diff --git a/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md b/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md new file mode 100644 index 0000000..690d86b --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/earned-channel-work.md @@ -0,0 +1,172 @@ +# Earned-channel work + +PR, syndication, mentions, AI-search citation, word of mouth. The relationship investment that compounds over years. The pitching discipline that earns coverage rather than burning relationships. + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real: relationships built over years, pitches that demonstrate the program's value, content that earns citation. Programs treating earned channels as automatic produce nothing; programs investing in the relationships earn ongoing channel access. + +--- + +## PR and press + +Journalists, podcasters, newsletter operators who cover the program's content. + +The relationship-first principle. Coverage follows relationships. Cold pitches from unknown senders get ignored at high rates; warm pitches from known senders get read. Programs that build relationships before they need coverage are the programs that earn coverage when they have flagship work to share. + +Building relationships. + +- Read the journalists, podcasters, and operators in the program's space. Know what they cover, what their angles are, what they have written or aired recently. +- Engage substantively before pitching. Comment thoughtfully on their work; share their pieces with attribution; respond if they ask for input. +- Build the relationship to a level of mutual recognition before the first pitch. + +Pitching when the relationship exists. + +- Pitch specific to the recipient. Reference their recent work; explain why the program's content fits their angle. +- Lead with the angle, not with the company. Recipients care about the story, not about the program's brand. +- Provide everything the recipient needs: the source piece, key statistics, possible quotes, a clear point of contact. +- Make it easy to say yes; make it easy to say no. + +The mass-blast pitching anti-pattern. + +- Identical pitches sent to dozens of recipients. Recipients detect mass-blast quickly; relationships are damaged not built. +- Pitches focused on the program rather than on the story. Recipients filter these as ads. +- Follow-up pressure. Excessive follow-ups damage future relationship potential. + +The PR investment timeline. Real PR relationships build over 1-3 years. Programs without prior PR investment cannot generate coverage on a deadline; programs with sustained investment have relationships that produce ongoing coverage. + +--- + +## Syndication + +Other publications republishing or excerpting the program's content with appropriate attribution. + +The syndication exchange. The program provides quality content; the partner provides reach into their audience. Both parties win when the exchange is fair. + +Negotiation patterns. + +- Republishing with canonical link. The partner runs the full piece; canonical link tag points to the program's version for SEO. Reach extends; SEO authority preserves. +- Excerpt with link. The partner runs an excerpt with a link to the full piece on the program's site. Less full reach but stronger funnel back to the program. +- Republishing without canonical. Less common; risks SEO duplication issues; should be avoided unless specifically negotiated with the partner about which version is canonical. + +Common syndication failures. + +- Canonical link mishandling. The piece appears on the partner's site as the canonical version; the program's version drops in rankings. +- Partner relationships not maintained. Syndication partners that stop running the program's content; the channel goes silent. +- Indiscriminate syndication. Every piece syndicated regardless of fit; partner audiences see content that does not match their interests; partner removes the program from rotation. + +The selective-syndication discipline. Not every piece warrants syndication. Match piece-to-partner: which pieces fit which partners; which partners' audiences will engage with which pieces. Selective syndication produces stronger partner relationships than blanket syndication. + +--- + +## Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +Citation as compounding authority. Each citation increases the program's authority signal. Citations from authoritative sources weight more than citations from less authoritative ones. Citation accumulation over years is one of the most durable signals of program quality. + +Earning citations. + +- Produce content with citation hooks. Original data; named frameworks; primary research; contrarian-but-defensible positions. +- Build identifiable phrasings or term coinages. If the program names a concept, others citing the concept cite the program. +- Make content discoverable when others are researching the topic. SEO and AI-search visibility matter for citation discoverability. + +The generic-content-no-citation problem. Pieces that do not have specific citation hooks rarely get cited even if they are well-written. The hook is what other writers reach for. + +AI-search citation specifically. AI engines cite content that matches their retrieval criteria. See `content-repurposing`'s AEO extraction patterns for the discipline of producing AI-citation-friendly content. Programs that design for AI citation earn more citations than programs that publish without that consideration. + +--- + +## Word of mouth and shares + +Audiences sharing pieces with their networks. + +The hardest channel to engineer. Word of mouth follows from genuine usefulness. Pieces that audiences want to share are pieces that are genuinely valuable; pieces that are generic do not get shared even if they are read. + +Patterns that earn shares. + +- Specific, useful content. Audiences share pieces that help them or that they think will help others. +- Citation-worthy content. Audiences share pieces they want to point to as references. +- Provocative-but-defensible content. Audiences share pieces that take a position they want to amplify. +- Memorable framings. Audiences share pieces that introduce concepts or framings they find useful. + +Patterns that do not earn shares. + +- Generic content. Pieces that say what every other piece on the topic says do not earn the share. +- Surface-level coverage. Pieces that scratch the surface without substantive depth do not feel worth sharing. +- Defensive content. Pieces that hedge every position do not earn the share because they do not say anything specific. + +The measurement challenge. Word-of-mouth sharing often happens in private channels (DMs, internal Slack, work emails) where the program cannot directly measure. Indirect signals: referral traffic from unknown sources, audience members reporting "a colleague sent me this," conversion-without-tracked-attribution. + +--- + +## Earned-channel investment + +The capacity allocation question. + +Programs without earned-channel investment. Treat earned channels as automatic. Coverage that happens, happens; coverage that does not happen, does not. Output: limited earned reach; the program is dependent on owned and paid distribution. + +Programs with strategic earned-channel investment. Allocate specific capacity to relationship-building, pitching, syndication negotiation, citation tracking. Output: earned channels become reliable distribution over years. + +The investment shape. + +- PR work. A specific person owns relationships and pitching. Investment level varies by program: from 5% of one person's time at smaller programs to dedicated PR roles at larger programs. +- Syndication negotiation. Periodic outreach to potential partners; relationship maintenance; canonical-link verification. +- Citation tracking. Monitoring where the program is being cited; engaging with those citations (thanking citers; building relationships with frequent citers). +- AI-search citation. Tracking AI engine citation rates; iterating on AEO extraction patterns based on what gets cited. + +The investment payoff timeline. Earned-channel investment compounds over 2-5 years. Year 1 produces limited returns; years 3-5 produce significant returns if the investment was sustained. + +--- + +## Common earned-channel failures + +Mass-blast pitching. Pitches sent to dozens of recipients identical or near-identical. Recipients detect; relationships damaged; future coverage potential reduced. + +No relationship investment. The program tries to "do PR" only when it has flagship work to share. Without prior relationship investment, pitches go cold even when the content is genuinely strong. + +Syndication mishandled. Canonical-link issues; partner relationships not maintained; SEO authority drained to partner sites. + +No citation hooks. Pieces produced without elements that earn citation. Mentions and AI-search citation rates stay low because nothing in the content prompts citation. + +Earned channel as automatic. Treating earned channels as if they happen on their own. Without investment, they do not. + +Limited PR scope. Pitching only the same 3-5 trade publications repeatedly. The relationship gets over-extended; coverage drops; broader earned-channel work is not happening. + +--- + +## Earned-channel measurement + +Earned channels are harder to measure than owned or paid, but measurement is still possible. + +PR coverage. + +- Volume: how many pieces of coverage per quarter. +- Quality: which publications, which authors, what reach those publications have. +- Sentiment: positive coverage, neutral, critical. +- Attribution: traffic and conversions sourced from coverage moments. + +Syndication. + +- Reach via partner: traffic and engagement on partner-published versions. +- Funnel back: traffic from partner content to program's own site. +- Authority preservation: SEO position holding given canonical link signaling. + +Mentions and citations. + +- Citation count over time. Tools that track mentions across the web help here. +- Citing-source quality. Citations from high-authority sources weight more. +- AI-search citation rates. Tools that track AI engine citations are emerging; the measurement infrastructure is improving. + +Word of mouth. + +- Indirect signals: referral traffic from unknown sources, audience reports, sustained organic growth without proportional paid amplification. +- Survey data: when audience members are asked how they discovered the program, word-of-mouth signals appear. + +--- + +## Methodology-level choices that stay in the public skill + +The relationship-first PR principle, the syndication exchange and selective-syndication discipline, the citation-earning patterns, the word-of-mouth observations, the earned-channel investment shape and timeline, the common failures, the measurement approaches. + +## Implementation choices that stay internal + +Specific PR-relationship CRM tooling. Specific pitching templates and tracking. Specific syndication negotiation conventions. Specific citation tracking software. Specific AI-search citation tracking infrastructure. The team's own conventions for relationship-investment cadence. These vary by team, budget, and program scope. diff --git a/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md b/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md new file mode 100644 index 0000000..3b3adbb --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/owned-channel-discipline.md @@ -0,0 +1,156 @@ +# Owned-channel discipline + +Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. The patterns that turn owned channels from posting infrastructure into durable distribution foundations. + +Owned channels are the most reliable distribution a program has. The newsletter delivers to every subscriber's inbox; the blog persists indefinitely; the owned social accounts run on the program's terms (within platform constraints). Programs that under-invest in owned channels become dependent on third-party distribution; when platforms change, when paid costs rise, when earned channels go quiet, the dependent program's reach collapses. + +--- + +## Newsletter discipline + +The most direct owned distribution. + +The discipline shape. + +- Cadence consistency. Subscribers develop expectations. Weekly send on Tuesdays gets opened more reliably than weekly send that drifts to Thursday or Wednesday or Friday. +- Content quality matching subscriber expectations. What subscribers signed up for; the program delivers it. Drift in quality (or in topic) produces unsubscribes. +- Single CTA per send. Multi-CTA emails dilute. Subscribers process one action; competing actions reduce all of them. +- Deliverability hygiene. Spam-trigger words, unbalanced text-to-image ratios, technical configuration (SPF, DKIM, DMARC) all affect deliverability. Programs that ignore deliverability watch open rates decline. +- List health. Engaged subscribers vs lapsed subscribers; pruning lapsed segments improves overall deliverability and engagement metrics. + +Common newsletter failures. + +- Cadence drift. The "weekly" newsletter that becomes bi-weekly, then monthly, then sporadic. Subscribers stop expecting; engagement decays. +- Subject lines that announce instead of earning the open. "Newsletter for week of November 14" performs worse than specific subject lines tied to the email's content. +- Multi-topic emails that try to cover everything the program produced this week. Single-topic focus produces stronger engagement. +- No segmentation. The same email goes to every subscriber regardless of interest patterns. Programs with multiple distinct content streams benefit from segmented sends. + +See `email-sequences` for the email-specific discipline including subject-line patterns, sequence design, and lifecycle campaigns. + +--- + +## Blog discipline + +The owned content home. + +The discipline shape. + +- Architecture and technical SEO foundations. Crawlability, indexability, page speed, schema markup. Without these, the blog cannot earn search traffic regardless of content quality. +- Pillar and cluster organization. Topical hubs that compound authority over years. See `pillar-content-architecture`. +- Refresh discipline. Library does not decay into staleness. See `content-refresh-system`. +- Internal linking. Strong internal-link graph that distributes authority and earns rankings. +- On-page optimization. Per-page SEO discipline. See `seo-onpage`. + +Common blog failures. + +- Publishing without distribution to the blog. The blog is the destination; if no traffic flows to it from owned and earned distribution, only the slowly-compounding search traffic builds. +- Architectural neglect. The blog's information architecture rots; URL structures change without redirects; old content drags down newer pages' authority. +- Refresh starvation. The library accumulates stale pieces; new pieces have to compete with the team's own decaying content for rankings. +- No design investment. The blog reads as a content dump rather than as a property; visitors do not return. + +The blog as compounding asset. A well-disciplined blog produces traffic for years. Programs that invest in blog foundations early earn compounding returns; programs that under-invest never earn the compounding effect. + +--- + +## Owned social discipline + +LinkedIn company page, X account, YouTube channel, Instagram account, etc. + +The discipline shape. + +- Per-platform conventions. Each platform rewards different content shapes. LinkedIn rewards substantive long-form posts; X rewards conversation; YouTube rewards specific topic and audio quality; Instagram rewards visuals. +- Cadence calibrated to platform attention rhythm. Daily on platforms that reward daily; weekly on platforms that work weekly. Mismatch reduces reach regardless of content quality. +- Engagement-signal optimization. Algorithmic recommendation rewards content that earns engagement signals (comments, shares, time-watched, click-through). Content designed for these signals reaches more. +- Account-health hygiene. Posting consistency; authentic engagement (not spam-replies); profile completeness; consistent branding. + +Common owned-social failures. + +- Cross-posting identical content across platforms. Each platform has different conventions; identical posts perform poorly on all platforms. +- Generic posting templates. Audiences detect template-driven posting; engagement decays. +- No engagement with the audience. Posting without responding to comments or engaging with industry conversations reduces algorithmic favor over time. +- Reliance on a single platform. Platform algorithms shift; programs dependent on one platform's reach are exposed to algorithm risk. + +Owned vs platform-controlled. Owned-social channels are owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. The distinction matters for risk: programs treating owned-social as fully owned underestimate platform-algorithm risk. + +--- + +## Podcast discipline + +Owned audio distribution. + +The discipline shape. + +- Audio quality. Listeners tolerate uneven video far more than uneven audio. Audio investment returns more than video investment up to a point. +- Consistent episode cadence. Weekly is most common; bi-weekly works for higher-investment shows. Drift undermines listener habit. +- Show notes as derivative format. Show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as their own derivative format with quality discipline. +- Cross-platform distribution. Apple Podcasts, Spotify, YouTube, Google Podcasts. Each is a discoverability surface. +- Format consistency within the show. Listeners develop expectations; format changes can lose listeners. + +Common podcast failures. + +- Production quality drift. The first 10 episodes are well-produced; episodes 30+ show production decay. +- No cross-platform distribution. The show lives on one platform; potential listeners on other platforms cannot find it. +- Show notes treated as afterthought. Thin show notes reduce SEO value and listener navigation. +- Cadence inconsistency. Drift between episodes undermines listener habit. + +The podcast as relationship channel. Engaged listeners feel connected to the host(s); the audience relationship is intimate. Podcasts produce trust signal that other channels often cannot match. + +--- + +## Community discipline + +Slack communities, Discord servers, dedicated discussion forums. + +The discipline shape. + +- Active moderation. Communities require continuous facilitation. Spam, off-topic content, and unaddressed conflict damage community health. +- Sustained value-delivery. Members come and stay because the community delivers value. Value can be peer connection, expert access, content access, or product feedback. +- Integration with the broader content program. Members get early access; program content is shared in the community; community feedback informs program decisions. +- Member-driven content. Strong communities have member-to-member interaction beyond program-to-member broadcasting. + +Common community failures. + +- Abandonment. Communities launched with fanfare and then under-staffed. Members leave; the community decays into a ghost town signaling the program's decline. +- Broadcast-only. The program posts to the community as if it were another social channel; no facilitation of member interaction. +- Membership-quality drift. Open communities accumulate members who do not contribute; the signal-to-noise ratio degrades. +- No moderation policy. Conflict, spam, or off-brand content erodes the community's character. + +Community as audience-relationship multiplier. The community is often the program's most engaged audience segment. Investment in the community returns at multiple points: feedback, advocacy, product input, content participation. + +--- + +## The starvation anti-pattern + +Programs that under-invest in owned channels become dependent on third-party distribution. + +The pattern. The program invests heavily in paid acquisition or in social platforms it does not own. Reach grows on those channels. The program does not build newsletter, blog, or community in proportion. When platforms change algorithms or paid costs rise, reach collapses; the program has no owned channels to fall back on. + +The visibility. Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscribes, account creations, community memberships). The reach is rented, not owned. + +The cure. Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +Prevention. Programs in early stages should over-invest in owned channels relative to the reach those channels initially produce. The investment compounds over years; the alternative is decade-long dependency on third-party distribution. + +--- + +## The owned-channel investment timeline + +Owned channels reward long investment. + +Year 1. Newsletter and blog established; cadence consistent; subscriber count and traffic both small. The investment feels like it is producing little; the cadence is the foundation. + +Year 2-3. Newsletter list grows; blog accumulates SEO traffic; community starts to form (if part of the strategy). The investment starts to compound; engagement signals improve. + +Year 4+. Owned channels are reliable distribution. Newsletter sends produce predictable engagement; blog earns substantial organic traffic; community is a meaningful audience asset. The early investment compounds. + +The patience cost. Owned-channel investment is multi-year; the visible returns lag the investment. Programs that abandon owned-channel investment in years 1-2 because returns feel small often regret it in years 3-5 when peers who sustained the investment are reaping the compounding effect. + +--- + +## Methodology-level choices that stay in the public skill + +The owned-channel disciplines (newsletter, blog, social, podcast, community), the common failures per channel type, the starvation anti-pattern, the investment timeline. + +## Implementation choices that stay internal + +Specific newsletter platforms and templates. Specific blog CMS and design systems. Specific social-publishing tools. Specific podcast hosting and editing tools. Specific community-management software (Slack, Discord, custom forums). The team's own conventions for cadence and quality thresholds. These vary by team, budget, and program scope. diff --git a/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md b/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md new file mode 100644 index 0000000..43dbd94 --- /dev/null +++ b/dist/pi/.agents/skills/content-distribution/references/paid-promotion-patterns.md @@ -0,0 +1,181 @@ +# Paid promotion patterns + +When boosting organic content earns its keep. The paid-as-substitute anti-pattern. The disciplines that distinguish strategic paid amplification from spending budget on content that did not validate organically. + +Paid promotion of organic content is an amplification layer. The pattern works when paid spend extends the reach of content that organic engagement has already validated; the pattern fails when paid spend substitutes for organic validation or for owned-channel investment. + +--- + +## The boost-organic pattern + +The most common and effective form of paid content amplification. + +The shape. A piece publishes organically. Some pieces show strong engagement signals: high CTR, high time-on-page, organic shares, comment engagement. The program boosts those validated pieces with paid spend to extend reach. + +Why it works. The content has audience validation. Audiences engage with the boosted content because it is genuinely engaging. The paid spend amplifies what already worked rather than gambling on what might work. + +Implementation patterns. + +- Engagement-threshold boosting. Pieces that exceed defined engagement thresholds in the first 24-48 hours get boosted. The thresholds (CTR, share rate, comment volume) vary by program. +- Editorial-judgment boosting. Editorial reviews recent organic pieces and selects which ones merit boost spend based on broader strategic fit, not just engagement metrics. +- Hybrid. Engagement-threshold boost for tactical amplification; editorial-judgment boost for strategic amplification of pieces that align with program goals beyond engagement metrics. + +Capacity allocation. Most strong programs allocate 5-20% of distribution capacity to paid amplification of organic content. Higher allocations often signal under-investment in owned channels. + +--- + +## Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +The shape. The program pays a third-party newsletter to feature its content. The newsletter's audience sees the program's content alongside the newsletter's editorial content. + +Why it works. Newsletter audiences have strong attention rhythms; sponsored content placed in a newsletter the audience reads gets meaningful attention. + +Implementation patterns. + +- Single-send sponsorship. The program pays for one prominent placement in a single send. Strongest engagement; highest cost per send. +- Multi-send package. The program pays for placements across multiple sends. Weaker per-send engagement; lower cost per send. +- Co-marketing. The program partners with the newsletter on a co-produced piece; both parties benefit. Often the most effective format when it fits both audiences. + +Selection criteria. + +- Audience overlap with target audience. +- Newsletter editorial fit (content tone matches the program's voice). +- Engagement metrics (open rates, click-through rates, sponsor performance history). +- Cost relative to alternative paid options. + +Common newsletter-sponsorship failures. + +- Mismatched audience. The newsletter has reach but does not match the program's target audience. +- Mismatched tone. Sponsored content clashes with the newsletter's voice; readers tune out. +- Generic sponsored content. Sponsored placements that read as ads underperform sponsorships that read as editorial fit. + +--- + +## Syndication networks (Outbrain, Taboola, native networks) + +Paid placement on third-party sites via "you may also like" or "recommended for you" units. + +The shape. Programs pay per click; content appears on third-party sites in recommendation units. + +Implementation patterns. + +- Bid management. Per-piece bidding; cost-per-click optimization. +- Geographic and audience targeting. Some networks support targeting; others are broader. +- Brand-safety controls. Choose where the content appears; some networks have brand-safety concerns about co-placement. + +Effectiveness. Variable. Some programs see meaningful traffic with reasonable cost-per-engagement; others see high traffic numbers but low engagement once visitors land on the program's content. The audience quality varies significantly across networks. + +Common syndication-network failures. + +- Click optimization without engagement measurement. The program optimizes for cost-per-click; clicks arrive; engagement is low; the audience is the wrong audience. +- Brand-safety incidents. Content appears in unwanted contexts; brand association damaged. +- Treating syndication networks as primary distribution. The networks supplement; they do not substitute for owned and earned channels. + +The cautious-test discipline. Test syndication networks at small budget; measure beyond clicks (engagement, time-on-page, conversion); expand only if the audience quality matches expectations. + +--- + +## Search advertising for content + +Paying for clicks on content pieces via search ads. + +The shape. Less common than other paid content amplification. Usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +When it fits. + +- High-value content with clear conversion or lead-capture goals. +- Pieces targeting queries where organic ranking is hard to achieve. +- Time-sensitive content where waiting for organic ranking is not an option. + +When it fails. + +- Routine blog posts boosted via search ads. Cost-per-click usually exceeds the value of the click. +- Content that does not have clear conversion paths. Paid traffic without conversion produces sunk cost. +- Competitive queries where ad costs are high. Programs may be unable to justify cost-per-click in highly contested categories. + +The selective-discipline. Reserve search ads for content with clear conversion goals; measure paid traffic against owned-traffic comparison; high-value content only. + +--- + +## Sponsored podcast placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts. + +The shape. Programs pay to be featured in third-party podcasts. Often via host-read endorsement; sometimes via produced ads. + +Why host-read works. The podcast host's voice carries trust signal; audiences hearing the host endorse content engage at higher rates than they engage with produced ads. Host-read endorsements are often the highest-engagement paid content amplification available. + +Selection criteria. + +- Host audience alignment with the program's target. +- Host content alignment with the program's voice. +- Per-episode reach and download numbers (with verification; some self-reported numbers are inflated). +- Cost relative to expected engagement. + +Common podcast-sponsorship failures. + +- Mismatched host. The host's audience does not match the program's audience. +- Mismatched content. The host reads the program's pitch awkwardly because the content does not fit the host's editorial voice. +- Production quality issues. Poorly produced sponsored segments damage the host's show; future sponsorship opportunities reduce. + +The host-collaboration discipline. Provide the host with substantive talking points, not scripted ad copy. Hosts read better when they have material they can adapt to their voice. The collaboration produces stronger sponsorships than rigid scripts. + +--- + +## The paid-as-substitute anti-pattern + +When paid promotion substitutes for organic validation or for owned-channel investment. + +The pattern. The program does not invest in newsletter, blog, community, or earned channels. Paid amplification produces visible reach; the program looks like it is working. Underlying owned-channel growth is minimal; the program is rented reach without owned-audience growth. + +Why it fails over time. + +- Paid costs rise. Auction dynamics on paid platforms drive prices up; the program's cost-per-engagement increases. +- Algorithm shifts. Paid platforms change targeting; previously-effective audiences become harder to reach or more expensive. +- Audience saturation. Audiences encountering the program's paid content develop ad-blindness; engagement decays. +- No compounding effect. Each paid impression is paid for separately; nothing compounds the way newsletter or blog growth compounds. + +The visibility. Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscriptions, account creations, community memberships). The reach is rented, not owned. + +The cure. Reallocate capacity. Reduce paid spend; increase newsletter, blog, and community investment. Recovery is multi-year; programs in paid-substitute state cannot rebuild quickly. + +--- + +## Paid amplification of low-organic-engagement content + +Boosting pieces that did not earn engagement organically. + +The pattern. A piece publishes organically. Engagement is low. The team boosts the piece anyway, reasoning that more reach will produce more engagement. + +Why it fails. Audiences who did not engage organically rarely engage when shown the same content via paid amplification. The piece's value proposition is not landing; paid amplification compounds the problem. + +The cure. Boost organically-validated content; do not substitute paid for organic validation. Pieces that did not engage organically should be evaluated for whether they should be refreshed (see `content-refresh-system`) or whether they were the wrong piece for the audience. + +Exception cases. Some content may be specifically targeted at audiences who do not see the organic version (different geographic markets, different audience segments). In those cases, paid amplification to specific audiences may be appropriate even without organic validation in the original audience. The rule is "validate within the addressable audience"; not necessarily "validate organically before any paid spend." + +--- + +## Capacity allocation for paid promotion + +Most programs benefit from a clear capacity allocation. + +Capacity guidelines. + +- 0-5% of distribution capacity to paid. Programs with strong owned and earned channels; paid is selective amplification of best organic pieces. +- 5-20% of distribution capacity to paid. Programs balancing organic-first with strategic paid amplification. +- 20-50% of distribution capacity to paid. Programs with explicit paid-amplification strategy; usually B2C brands or programs with strong conversion-funnel logic. +- 50%+ of distribution capacity to paid. Often signals under-investment in owned and earned; should be reviewed against the paid-as-substitute anti-pattern. + +The allocation review. Quarterly, review actual spend allocation. Programs drifting toward paid-heavy allocation should consider whether the drift reflects strategy or under-investment in alternatives. + +--- + +## Methodology-level choices that stay in the public skill + +The boost-organic pattern, sponsored newsletter discipline, syndication network cautious-test discipline, search advertising selective discipline, sponsored podcast host-collaboration discipline, paid-as-substitute anti-pattern, paid amplification of low-organic-engagement failure, capacity allocation guidelines. + +## Implementation choices that stay internal + +Specific paid platform configurations and bidding strategies. Specific engagement-threshold values for boost decisions. Specific newsletter sponsorship vendor selections. Specific syndication network testing protocols. Specific podcast sponsorship measurement infrastructure. The team's own conventions for paid-vs-organic capacity tradeoffs. These vary by team, budget, and platform mix. diff --git a/dist/pi/.agents/skills/content-migration/SKILL.md b/dist/pi/.agents/skills/content-migration/SKILL.md new file mode 100644 index 0000000..6f19225 --- /dev/null +++ b/dist/pi/.agents/skills/content-migration/SKILL.md @@ -0,0 +1,259 @@ +--- +name: content-migration +description: "Move content between platforms, domains, or URL structures while preserving SEO equity, user bookmarks, and integrations. Use this skill when planning a CMS migration, replatforming, consolidating sites, changing URL structures, or merging content from multiple sources. Triggers on content migration, replatform, CMS migration, domain migration, URL restructure, redirect map, site merge, content consolidation, migration plan, post-migration drop. Also triggers when planning a launch that involves moving existing content." +category: cross-cutting +catalog_summary: "Platform migrations with SEO equity preservation" +display_order: 2 +--- + +# Content Migration + +Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic. + +--- + +## When to use + +- Migrating from one CMS to another (e.g., WordPress to a headless setup) +- Consolidating multiple sites into one +- Splitting one site into multiple +- Changing URL structures +- Domain migration (one brand to another, mergers, rebrands) +- Migrating from a custom build to a platform (or vice versa) +- Content audit-driven cleanup as part of a larger move + +## When NOT to use + +- A net-new site with no existing content (no migration needed) +- Single-page edits or content updates within an existing site (use `content-and-copy`) +- Performance or technical SEO improvements without URL changes (use `seo-technical`) +- Routine content audits (use `seo-content-audit`) + +--- + +## Required inputs + +- The source: current platform, current URL structure, current content inventory +- The destination: target platform, target URL structure, target capabilities +- The reason for migration (drives priority of what to preserve) +- Constraints (timeline, budget, downtime tolerance) +- Stakeholders (SEO, content, dev, comms, support) + +--- + +## The framework: 6 phases + +Every content migration follows the same arc. Skipping a phase is how migrations go badly. + +### Phase 1: Inventory + +You can't migrate what you don't know. Build a complete map of what exists. + +For each piece of content: +- URL +- Title +- Content type (article, landing page, product, doc, etc.) +- Status (live, draft, archived, scheduled) +- Last modified +- Author or owner +- Traffic (last 12 months) +- Backlinks (top external referrers) +- Internal links pointing to it +- Embedded assets (images, video, downloads) + +Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool. + +The inventory is a spreadsheet. It's the source of truth for the rest of the migration. + +### Phase 2: Audit and decide + +For each piece of content, decide: + +- Keep: migrate as-is +- Update: migrate with edits (refresh, expand, fix) +- Merge: combine with another piece, redirect both old URLs to the new +- Redirect: don't migrate; redirect to a related page +- Delete: don't migrate, no redirect (use sparingly; only for clearly low-value pages) + +This is `seo-content-audit` work. The migration is the time to do it; not the time to skip it. + +For each "Update" or "Merge," document the specific changes. + +### Phase 3: Map URLs + +The URL map is the most important migration artifact. + +\| Old URL \| New URL \| Status code \| Reason \| +\|---\|---\|---\|---\| +\| /old/path \| /new/path \| 301 \| Direct equivalent \| +\| /old/page-1, /old/page-2 \| /new/merged \| 301 \| Merged content \| +\| /old/deprecated \| /related/replacement \| 301 \| Closest replacement \| +\| /old/junk \| (none) \| 410 \| Intentionally gone \| + +Rules: +- 301 (permanent redirect) for content that has a new home +- 410 (gone) for intentionally deleted content +- Avoid 404 (not found) where 410 is more accurate +- Never redirect everything to the homepage; specific is always better +- Map every URL with traffic or backlinks; lower-priority URLs can be patterned + +For domain migrations, use a 1:1 path mapping by default (`old.com/page` → `new.com/page`) with specific overrides where structure changes. + +### Phase 4: Build and stage + +Build the destination. Don't skip a staging environment. + +- Set up the new platform with the new content +- Implement the URL map (most platforms support a redirect file or rule) +- Verify a representative sample of redirects work +- Test critical user flows (signup, purchase, contact) +- Validate analytics, monitoring, and integrations +- Test from search engine perspective: robots.txt, sitemap, canonicals + +If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip. + +### Phase 5: Cut over + +The actual switch. Plan it like a launch (and use `launch-runbook` alongside this skill). + +Pre-cutover: +- Comms to stakeholders (date, expected impact) +- Comms to users if downtime expected +- Support team prepped for likely questions +- Lower DNS TTL the day before (1-3 days for safety) +- Backup of source platform (in case rollback is needed) + +Cutover: +- Redirect rules go live +- DNS changes go live +- New sitemap submitted to search engines +- Old sitemap removed or updated +- Internal links audited and updated to point to new URLs (where possible) +- Status page or banner if user-visible disruption + +Immediately post-cutover: +- Smoke test top 50 pages from the inventory +- Verify redirects are 301 (not 302) +- Verify search console for errors +- Watch real-time traffic for unexpected drops +- Watch error logs for missing assets, broken integrations + +### Phase 6: Monitor and recover + +The migration isn't done at cutover. The next 30-90 days reveal problems. + +Watch: +- Traffic: expect a temporary drop (10-30% is common); should recover in 4-8 weeks. A persistent drop beyond that is a problem. +- Indexing: new URLs should be crawled and indexed. Check coverage in search console. +- Rankings: track top keywords. A position drop is normal; a position cliff is a sign of a redirect or canonical problem. +- Backlinks: check that linked-from-elsewhere pages still resolve to the right destination. +- 404s: any URL getting 404s that should have been redirected? Add to the map. +- User reports: support tickets, social media. Are users finding their old links? + +Common 30-day fixes: +- Add missed redirects from 404 patterns +- Update internal links you missed +- Re-submit sitemap if indexing stalls +- Investigate and fix any crawl errors + +--- + +## Workflow + +### Step 1: Set the scope + +What's in scope? What's out? Write it down. Migrations expand if not bounded. + +### Step 2: Build the inventory + +Pull every URL, traffic, backlinks, internal links. The spreadsheet is the artifact. + +### Step 3: Decide per piece + +Keep, update, merge, redirect, delete. Document decisions. + +### Step 4: Map URLs + +The complete redirect map. Reviewed by SEO and content stakeholders. + +### Step 5: Build the destination + +In a staging environment. Real content (or representative content). Real redirects. + +### Step 6: Test + +- Sample of redirects (top 20 by traffic, top 20 by backlinks, edge cases) +- Critical flows (signup, checkout, contact) +- Analytics and monitoring +- Search-engine perspective (robots.txt, sitemap, canonicals) + +### Step 7: Cut over + +Following the cutover checklist. Have rollback ready. + +### Step 8: Monitor + +Daily for the first week. Weekly for the first month. Monthly through 90 days. + +### Step 9: Document the result + +What worked. What didn't. Lessons. (See `after-action-report`.) + +--- + +## Failure patterns + +No URL inventory. Migration team thinks they have everything. They don't. Old PDFs, archived posts, marketing landing pages with backlinks. Build the inventory. + +302 redirects instead of 301. 302 is temporary. SEO equity doesn't reliably pass. Use 301 unless you have a specific reason. + +Redirecting everything to the homepage. "We'll let users find their way." They won't. They'll bounce. Map specifically. + +Long redirect chains. /a → /b → /c → /d. Each hop loses a little equity and adds latency. Collapse to /a → /d. + +Forgetting non-HTML URLs. PDFs, images, downloads. They have URLs too. They have backlinks too. Include in the map. + +Forgetting query strings. `/page?id=123` is a different URL than `/page`. Patterns or specific maps for query string variants. + +Ignoring trailing slashes. `/page` and `/page/` are different to most servers. Pick one canonical form. Redirect the other. + +No staging. The first time the migration runs is in production. Things break. Stage and test. + +Stage that's too different from production. Different DNS, different CDN, different platform. Tests pass on staging, fail on production. Stage as close to prod as feasible. + +Leaving the source live. Two sites serving the same content. Duplicate content, split equity, user confusion. Take down the source after confirming the destination is solid. + +Leaving the source domain unrenewed. Domain expires, redirects break, traffic dies. Renew the source domain for a long time, even if you're not using it. + +Big-bang migration with no rollback plan. Something goes wrong. Now what? Plan rollback before cutover. + +Cutover during a busy period. End of quarter, holiday season, big campaign. Bad timing. Pick a quiet period. + +No comms. Users find their bookmarks broken with no warning. Some won't come back. Communicate. + +Migration as a one-time event. It's not done at cutover. Monitor for 30-90 days. Fix what surfaces. + +Treating migration as just a dev project. SEO, content, support, comms all need to be involved. Cross-functional from day one. + +--- + +## Output format + +A migration plan document includes: + +- Scope: what's in, what's out +- Inventory: the URL spreadsheet +- Audit decisions: keep, update, merge, redirect, delete +- URL map: old to new, with status codes +- Architecture: new platform setup, redirect implementation +- Cutover plan: the runbook for switch day +- Rollback plan: if it goes wrong +- Monitoring plan: what's watched, for how long +- Comms plan: internal and external +- Owners and timeline: who does what when + +--- + +## Reference files + +- [`references/migration-runbook.md`](references/migration-runbook.md): Step-by-step runbook for cutover day, including pre-flight checks, the actual switch, immediate verification, and the first 24 hours of monitoring. diff --git a/dist/pi/.agents/skills/content-migration/references/migration-runbook.md b/dist/pi/.agents/skills/content-migration/references/migration-runbook.md new file mode 100644 index 0000000..c63c24e --- /dev/null +++ b/dist/pi/.agents/skills/content-migration/references/migration-runbook.md @@ -0,0 +1,351 @@ +# Migration Cutover Runbook + +A step-by-step runbook for the day of a content migration cutover. Pair this with `launch-runbook` for general launch protocol. + +The runbook is read by tense people watching the clock. Optimize for clarity. + +--- + +## Roles + +Assign these before the day: + +\| Role \| Responsibility \| Person \| +\|---\|---\|---\| +\| Migration lead \| Calls the cutover, makes go/no-go decisions \| \| +\| Tech lead \| Executes DNS and redirect changes \| \| +\| QA lead \| Runs verification scripts and manual checks \| \| +\| SEO lead \| Monitors search and indexing \| \| +\| Comms lead \| Sends notifications, updates status page \| \| +\| Support lead \| Watches tickets, escalates user reports \| \| +\| Backup decision maker \| Authorizes rollback if needed \| \| + +--- + +## T-7 days: prep + +- [ ] Inventory verified complete +- [ ] URL map signed off by SEO and content +- [ ] Destination tested in staging +- [ ] Sample of 50 redirects verified +- [ ] Rollback plan documented and rehearsed +- [ ] Cutover date and window communicated to all stakeholders +- [ ] Support team briefed on common questions +- [ ] DNS TTL lowered to 300 seconds (5 minutes) +- [ ] Monitoring dashboards built and tested +- [ ] Search console verified for both old and new domains (if domain change) + +--- + +## T-1 day + +- [ ] Final inventory pull (any new content added since the freeze?) +- [ ] Final URL map review +- [ ] Backup of source platform (full, restorable) +- [ ] Test rollback procedure in staging +- [ ] Confirm everyone on the team is available during the window +- [ ] Status page draft prepared +- [ ] Internal comms draft prepared +- [ ] Customer comms draft prepared (if applicable) + +--- + +## T-2 hours + +- [ ] All stakeholders in the cutover channel (chat or call) +- [ ] Status: source platform writeable lock (no new content during cutover) +- [ ] Final smoke test on staging +- [ ] Final confirmation: GO or NO-GO + +NO-GO triggers: +- Critical bug found in destination +- Key person unavailable +- Source data integrity issue +- External factors (e.g., source platform outage) + +If NO-GO, reschedule. Don't push through. + +--- + +## T-0: cutover + +Time-box each step. If a step takes 2x its expected duration, pause and assess. + +### Step 1: Final source backup + +Time: 5-15 minutes depending on volume. + +``` +[Specific backup commands or steps] +``` + +Verify backup integrity. Continue only on success. + +### Step 2: Deploy destination to production + +If the destination has been on staging only: + +``` +[Deploy commands] +``` + +Verify the destination is responding correctly on its production address (which may not yet have DNS pointed at it). + +### Step 3: Deploy redirect rules + +The redirect rules go on whatever the source platform uses to redirect (htaccess, edge worker, CDN rule, server config). + +``` +[Deploy redirect rules] +``` + +Test 5 redirects manually: + +```bash +curl -I https://oldhost.com/path1 +curl -I https://oldhost.com/path2 +# Expected: 301 to https://newhost.com/path1 +``` + +### Step 4: DNS cutover (if domain change) + +Update DNS to point the new domain to the destination. + +``` +[DNS update steps] +``` + +Verify resolution from multiple regions: + +```bash +dig +short newhost.com @8.8.8.8 +dig +short newhost.com @1.1.1.1 +``` + +DNS propagation usually completes within minutes (with the TTL lowered earlier). Some resolvers may lag. + +### Step 5: Submit new sitemap + +``` +[Submit to search engines] +``` + +For Google: search console → sitemaps → submit. +For Bing: webmaster tools → sitemaps → submit. + +### Step 6: Update internal references + +If the source has links to itself (or hardcoded references), update the source to point at the new URLs (helps tools that haven't picked up the redirects yet). + +If the source is being decommissioned entirely, this step is moot. + +### Step 7: Update integrations + +External integrations that reference URLs: +- Email templates with absolute URLs +- Social profiles with bio links +- Partner sites with deep links +- Marketing automation +- Analytics goals (URL-based goals may break) +- Saved CRM links + +Update each. Document in the comms plan. + +--- + +## T+15 minutes: smoke test + +- [ ] Top 50 URLs from inventory each return correct status +- [ ] Redirects return 301 (not 302) +- [ ] Critical user flows work (signup, contact form, checkout if applicable) +- [ ] Search engines can crawl (robots.txt, sitemap) +- [ ] Analytics is firing on new pages +- [ ] Monitoring is showing the new endpoints + +If any check fails: triage. Fix forward if simple; rollback if complex. + +--- + +## T+1 hour: stakeholder check-in + +- [ ] Status page updated +- [ ] Internal comms sent +- [ ] Customer comms sent (if applicable) +- [ ] Support has not seen unusual ticket volume +- [ ] Real-time analytics shows expected traffic patterns + +--- + +## T+24 hours + +- [ ] Search console shows crawls of new URLs +- [ ] Search console "Indexing" tab not showing major issues +- [ ] No spike in 404s or 5xx errors in logs +- [ ] Backlink-bearing pages confirmed to redirect correctly +- [ ] Monitoring dashboards normal +- [ ] No major customer reports + +--- + +## Rollback decision criteria + +Rollback if: +- Critical functionality broken on the destination +- Significant data corruption discovered +- Security issue introduced by the migration +- Search indexing catastrophically failing (rare; usually fixable forward) + +Do NOT rollback for: +- Normal traffic dip (expected, recovers) +- Individual broken redirects (fix forward) +- Minor visual issues (fix forward) +- Slow pages (fix forward) + +Rollback procedure: + +### Step R1: Reverse DNS (if domain change) + +``` +[Revert DNS] +``` + +### Step R2: Disable redirect rules + +Take redirects offline so source URLs serve source content again. + +``` +[Disable redirects] +``` + +### Step R3: Unlock source platform + +Remove the writeable lock on the source. + +### Step R4: Restore from backup if needed + +If data corruption: restore. See `backup-and-disaster-recovery`. + +### Step R5: Comms + +- [ ] Status page updated (rolled back) +- [ ] Internal comms (rolled back, next steps) +- [ ] Customer comms if applicable (apology, next steps) + +### Step R6: Schedule retrospective + +Within 5 business days. See `after-action-report`. + +--- + +## First-week monitoring + +Daily checks: + +\| Metric \| Target \| Action if off \| +\|---\|---\|---\| +\| Top-10 page traffic \| Within 80% of baseline \| Investigate redirects, check indexing \| +\| Conversion rate \| Within 90% of baseline \| Investigate UX changes, check analytics implementation \| +\| 404 rate \| Below 1% of requests \| Add missing redirects \| +\| Crawl errors \| Decreasing \| Check robots.txt, sitemap, canonicals \| +\| Indexing rate \| Increasing toward old volume \| Submit URLs manually if stalled \| +\| Search rankings (top 20 keywords) \| No cliff drops \| Investigate canonicals, redirects, content parity \| + +--- + +## First-month monitoring + +Weekly checks: + +\| Metric \| Target \| +\|---\|---\| +\| Total organic traffic \| Recovering toward baseline (typically 4-8 weeks) \| +\| Indexed pages \| At or above pre-migration count \| +\| Backlink-pointed-to pages \| All resolving correctly \| +\| 410 vs 404 ratio \| Pages that should be gone return 410, not 404 \| + +--- + +## After 90 days + +- [ ] Full performance review vs pre-migration baselines +- [ ] Document what worked, what didn't (after-action report) +- [ ] Decommission source platform if not already done +- [ ] Renew source domain (long-term, even if not in use, to preserve redirects) +- [ ] Archive the migration documentation for future reference + +--- + +## Common surprises + +Backlinks pointing to URLs not in inventory. Old marketing pages, archived posts, removed-but-still-linked content. Add to the map after cutover. + +Trailing slash inconsistencies. Server treats `/page` and `/page/` differently. One redirects, the other 404s. Fix with a normalizing redirect. + +Search engines slow to update. Old URLs still appear in search for weeks. Normal. Don't redirect to homepage to "speed it up." + +Analytics goals broken. URL-based goals don't match new URLs. Update the goals; backfill if possible. + +Hardcoded absolute URLs in email templates. Old links in transactional emails. Update templates. + +Schema.org or canonical tags pointing wrong. Crawlers follow canonical even after redirects. Verify canonical tags on the destination point to the destination. + +Sitemap caching. Some platforms cache sitemaps aggressively. Force a refresh. + +robots.txt forgot the new sitemap. Add the new sitemap to robots.txt. + +--- + +## Post-cutover comms template + +### Internal (to team) + +Subject: Migration cutover complete + +``` +The migration to [new platform/URL/etc.] is complete as of [time]. + +Status: +- [N] redirects in place +- All critical flows verified +- Monitoring shows expected traffic patterns + +We'll watch closely over the next 24 hours and the first week. Report any issues in [channel]. + +Next steps: +- [Specific monitoring action] +- [Specific follow-up] + +Thanks to everyone who made this happen. +``` + +### External (to users, if applicable) + +Subject: We've moved [or rebranded, or restructured] + +``` +Hi [name], + +[Brief reason for the change.] + +What this means for you: +- [Specific user-facing change 1] +- [Specific user-facing change 2] + +Old links should redirect automatically. If you find a broken link, please let us know at [contact]. + +Thanks for your patience as we make this transition. +``` + +--- + +## Document the result + +Within a week of cutover, write up: + +- What was migrated +- What worked +- What broke and how it was fixed +- What we'd do differently +- Lessons for the next migration + +This becomes input to `after-action-report` and to future migration playbooks. diff --git a/dist/pi/.agents/skills/content-refresh-system/SKILL.md b/dist/pi/.agents/skills/content-refresh-system/SKILL.md new file mode 100644 index 0000000..a7f8fa1 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/SKILL.md @@ -0,0 +1,255 @@ +--- +name: content-refresh-system +description: "Systematic content refresh discipline. Quarterly audits, refresh prioritization (which pieces, when, how deep), refresh-vs-merge-vs-delete decisions, the lifecycle that distinguishes intentional refresh from set-and-forget decay. Builds on the refresh sections of pillar-content-architecture and editorial-qa with a program-level discipline. Triggers on content refresh, content decay, content audit, refresh prioritization, content lifecycle, refresh strategy, traffic decay, ranking drop, content freshness, evergreen content, content maintenance. Also triggers when traffic is eroding silently across an aging content library, when teams cannot decide which pieces to refresh, or when refresh work is happening but the impact is unclear." +category: content +catalog_summary: "Systematic content refresh: quarterly audits, refresh prioritization, refresh-vs-merge-vs-delete decisions, the lifecycle discipline that distinguishes intentional programs from set-and-forget decay" +display_order: 10 +--- + +# Content Refresh System + +A senior editorial leader's playbook for systematic content refresh. The discipline that distinguishes intentional refresh programs from set-and-forget decay, and the prioritization framework that prevents both over-refresh (refresh-everything-on-calendar) and under-refresh (refresh-nothing-until-traffic-collapses). + +Content decays. Search behavior shifts; SERP intent reshapes; facts go stale; competitors publish stronger pieces; the brand's own positioning evolves past what older pieces represent. Programs that ignore this reality watch traffic erode silently across the library. Programs that overreact (rewriting everything on calendar) burn editorial capacity that should be producing new flagship work. The discipline is in the middle: refresh what matters when signals say so, and document the decisions so the program is auditable. + +This skill is the program-level refresh discipline across the whole content library. It builds on `pillar-content-architecture`'s hub-level refresh consideration (refresh as ONE consideration in hub design) and `editorial-qa`'s pre-publish quality gate (this skill is post-publish lifecycle, not pre-publish QA). Together those skills cover content quality at the moments quality decisions get made; this skill covers the moments between, when content is in the field and decaying or holding. + +The voice is the senior editorial leader who has watched refresh programs fail in both directions and who has shipped the systems that produced durable refresh discipline. + +When to use this skill: building a refresh program from scratch, auditing why refresh work is happening but traffic is not responding, designing the prioritization that keeps refresh tractable across a 200-piece or 2,000-piece library, or fixing a refresh program that is eating editorial capacity without clear results. + +--- + +## What this skill covers + +This skill spans the post-publish lifecycle of content. The content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is HUB scope; refresh appears as ONE consideration in hub design. +- `content-brief-authoring` is per-piece scope at production time. +- `content-and-copy` is execution scope at production time. +- `editorial-qa` is gate scope: pre-publish verification. +- `content-refresh-system` (this skill) is lifecycle scope: program-level refresh discipline across the whole content library, after pieces are in the field. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content libraries of 50-5,000+ pieces, agencies maintaining client content programs across years. + +What is not in scope: writing the refreshed pieces themselves (that is `content-and-copy`), the brief that drives the refresh (that is `content-brief-authoring`), the pre-publish gate on the refreshed piece (that is `editorial-qa`). This skill is the prioritization and lifecycle discipline; the actual content work plugs into the existing skills. + +--- + +## Refresh-everything vs refresh-nothing vs triaged-refresh + +The keystone framing. Two failure modes plus the discipline. + +Refresh-everything. Full rewrites on calendar. Every piece gets a refresh on a 12-month or 18-month rotation regardless of signals. Output: editorial capacity consumed by maintenance work that often was not needed, while strong pieces are touched into worse versions and weak pieces consume the same effort as flagship pieces. Cost: opportunity cost on new flagship production; maintenance fatigue in the editorial team; some pieces that were performing well get diluted by unnecessary edits. + +Refresh-nothing. Set-and-forget. Pieces ship and never get touched again. Output: traffic decays silently across the library as facts go stale, competitors publish stronger pieces, and SERP intent shifts away from the piece's framing. The library's compounding value erodes invisibly until an algorithm update or a competitor's flagship piece exposes the rot. Cost: cumulative traffic loss that nobody attributes to refresh failure because the loss is gradual; trust loss when readers find stale facts in pieces they expected to be current. + +Triaged-refresh. Refresh what matters when signals say so. Audit cadence catches decay early; prioritization concentrates effort on high-value-decaying pieces; weak pieces get refresh-vs-merge-vs-delete dispositions instead of automatic refresh; the program is auditable because every refresh decision was a deliberate response to specific signals. Output: editorial capacity preserved for new production; the library's compounding value protected; refresh work is seen, understood, and measured. + +The litmus test. Ask of any refresh decision: what signal triggered this refresh, what depth of refresh did the signal warrant, what outcome do we expect, and how will we measure whether the refresh worked? If the answer is "it was scheduled" or "we always refresh after 12 months," the program is on calendar rather than on signal. + +--- + +## Refresh signals + +Five categories of signal that trigger refresh consideration. Pieces that show no signals do not need refresh; pieces that show multiple signals are higher priority. + +Traffic decay. Organic traffic to the piece is trending down over a 90+ day window beyond the seasonal baseline. The decay can be slow (5-10% over a year) or sharp (40%+ in a month after an algorithm update). Slow decay typically indicates content drift; sharp decay typically indicates external change. + +Ranking drops. The piece is losing position on its target keywords. Drops from page 1 to page 2-3 are particularly consequential; drops within page 1 (position 3 to position 7) are less so but still tracked. Persistent ranking drops over 30+ days indicate a real shift, not search-result volatility. + +Factual staleness. The piece contains statistics, references, examples, or claims that are dated. A 2018 stat in a 2026 piece on a fast-moving topic is staleness; a piece that references defunct products or platforms is staleness; a piece that uses pre-shift framings ("AI is starting to influence search" in 2026) is staleness. + +SERP intent shift. The dominant SERP format for the target keyword has changed. The piece was written when articles ranked for the keyword; now the SERP wants product comparisons, video, or AI-overview-style answers. The piece may still rank but increasingly for the wrong reason. + +Content drift. The piece's positioning no longer matches the brand's current positioning. Voice has evolved; the brand's POV on the topic has sharpened or shifted; the piece reads as the brand-of-three-years-ago. Internal signal more than external; readers may not notice but the team will. + +The audit. Every piece in the library can be characterized by which signals it shows. Pieces with zero signals are stable; pieces with one or two signals warrant attention; pieces with three or more signals are typically in active decay. + +Detail in [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md). + +--- + +## The audit cadence + +How often to look. Two cadences with different tradeoffs. + +Quarterly audit. A formal review of the content library every 90 days. The team pulls traffic, ranking, and recency data; reviews each piece against the signals; assigns dispositions (refresh, merge, delete, or leave alone). Output: a refresh queue with priorities and a backlog of merge/delete decisions. + +- Strength: predictable, auditable, fits naturally into editorial calendar planning. +- Weakness: 90-day delay in detecting sharp decay; piece that lost 40% traffic in week 2 of a quarter is in decay for 75 days before the audit catches it. + +Continuous monitoring. Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. Pieces that lose more than X% traffic in Y days trigger a review. + +- Strength: catches sharp decay early; allows fast response to algorithm updates. +- Weakness: requires monitoring infrastructure; can produce alert fatigue if thresholds are too tight; misses slow decay that does not cross thresholds. + +The hybrid pattern. Most strong refresh programs run both. Quarterly audits catch slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. The two cadences cover different failure modes. + +Detail in [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md). + +--- + +## Refresh prioritization + +Prioritization is the discipline. Most libraries have more pieces showing signals than the team has capacity to refresh. Prioritization concentrates effort on the pieces where refresh produces the most value. + +The 2x2 matrix: piece value (high vs low) crossed with traffic state (decaying vs stable). + +High-value, decaying. Top priority. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. Refresh these first; the traffic loss compounds and the lost equity is hard to recover. + +High-value, stable. Monitor; do not refresh proactively. Pieces that are performing should not be touched without clear signal; refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. + +Low-value, decaying. Audit for merge or delete. Pieces with low traffic that are decaying further are usually candidates for merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling). Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. + +Low-value, stable. Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. Detail in [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md). + +--- + +## Refresh depth options + +Not every refresh is the same kind of work. Four depth levels. + +Light edit. Update statistics, replace dead links, fix factual errors, swap dated examples. Keeps the piece's structure and argument intact. Time investment: 30-90 minutes per piece. Use when the piece is structurally sound and only the surface details have aged. + +Substantial revision. Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that emerged after the piece was written. Time investment: 2-4 hours per piece. Use when the piece's structure is sound but specific sections have become weak. + +Full rewrite. Keep the URL and topic; rewrite the piece end-to-end. Time investment: similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. Use when the piece's structure no longer fits the current SERP intent or the brand's positioning has shifted enough that the piece needs to be re-conceived. + +Structural redesign. Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Time investment: a multi-piece project. Use when refresh is part of a larger structural change in the content library (a hub being rebuilt, a category being consolidated). + +The depth-decision discipline. Match depth to signal strength. Sharp decay or major SERP intent shift may warrant full rewrite; slow decay with stale stats may warrant only a light edit. Treating every refresh as a full rewrite is refresh-everything energy in a different shape. + +Detail in [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md). + +--- + +## Refresh vs merge vs delete decisions + +Not every piece in decay should be refreshed. Three dispositions. + +Refresh. The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +Merge. Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +Delete. The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. Delete and redirect to the closest sibling or, if no sibling exists, to the relevant hub or category page. + +The decision criteria. Refresh when the piece has demand and a path back. Merge when authority is being split. Delete when there is no path forward and the piece is not worth maintaining. + +The under-recognized failure mode: refreshing pieces that should have been merged or deleted. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. + +Detail in [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md). + +--- + +## Refresh execution patterns + +Who does the work, how it ships. + +Ownership. A single owner per refresh, not a committee. The owner is accountable for the outcome and runs the work through to ship. Refreshes that pass through multiple hands without an accountable owner often get partially done and then stall. + +Editorial integration. Refreshes typically run through the same editorial workflow as new pieces (brief, draft, edit, QA gate, publish), scaled to the depth chosen. A light edit may skip the brief and go straight to edit; a full rewrite goes through every step. + +Capacity allocation. Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff: a team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. The split varies by program maturity (older libraries often need 30-40% refresh allocation; newer libraries may need 5-10%). + +Refresh batching. Some teams batch refresh work into dedicated weeks or sprints; others integrate one refresh per week into the steady-state production cadence. Batching produces focus but interrupts new production; integration sustains new production but slows refresh velocity. Either works; the failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence. + +Detail in [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md). + +--- + +## Re-promotion after refresh + +Refreshed pieces need to signal to search engines and audiences that they have been updated. + +To search engines. Update the modified date in schema markup. Update the published-or-modified-date in the visible metadata. Submit the URL for re-crawl through Search Console. Some teams update the URL minimally (e.g., adding a year to the slug for evergreen pieces), but URL changes carry redirect risk and should be reserved for substantial-revision or full-rewrite refreshes. + +To audiences. Re-share the refreshed piece on the channels where the original landed: newsletter, social, syndication partners. Treat the refresh as a publication event, not as silent maintenance. The re-promotion is part of the refresh's value proposition: the piece earns new attention as well as preserved search position. + +Internal linking refresh. Pieces that link to the refreshed piece may benefit from anchor-text updates if the refreshed piece's positioning shifted. Sister pieces that should now link to the refreshed piece can be updated to do so. + +The refresh that nobody tells anyone about. A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement. + +Detail in [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md). + +--- + +## Refresh tracking and effectiveness measurement + +The discipline that prevents refresh-theater: tracking which refreshes worked, which did not, and what the patterns reveal. + +Per-refresh tracking. Each refresh is logged with: the signals that triggered it, the depth chosen, the date shipped, the predicted outcome, the actual outcome at 30 days and 90 days post-refresh. The log is the refresh program's evidence base. + +Effectiveness metrics. The primary metrics depend on the refresh's purpose. Traffic-decay refreshes track post-refresh traffic recovery; ranking-drop refreshes track post-refresh ranking position; content-drift refreshes track post-refresh engagement metrics (time on page, return visits) more than search metrics. + +Pattern detection. The log reveals patterns over time. Some signal types produce reliable recovery; others rarely produce recovery and indicate a deeper problem (the topic itself is dying; the brand's positioning on the topic is wrong; competitors are too strong to displace). The patterns inform program-level decisions. + +The refresh-that-did-not-work review. Refreshes that did not produce the expected recovery should get a structured review. Was the depth wrong? Was the merge or delete decision the right disposition that we did not take? Did the underlying problem turn out to be something refresh cannot fix? + +Detail in [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-refresh-failures.md`](references/common-refresh-failures.md). + +- "We refresh every piece annually and traffic is still declining." Refresh-everything pattern; the calendar-based work is not catching the actual decay signals. +- "We have not touched the library in 18 months and traffic has eroded 30%." Refresh-nothing pattern; the decay went uncaught. +- "We refresh pieces but the traffic does not come back." Wrong disposition; the pieces were merge or delete candidates, not refresh candidates. +- "Our refresh queue is 200 pieces deep and growing." No prioritization; everything that shows any signal goes in the queue regardless of value. +- "We refreshed a flagship piece and traffic dropped." Refresh damaged a piece that was performing; the refresh was triggered by calendar rather than signal. +- "The team is exhausted from refresh work." Capacity allocation is wrong; either refresh ratio is too high, or new production is suffering, or the depth choices are over-investing. +- "We do not know if our refreshes are working." No tracking; refresh work happens but its effectiveness is invisible. +- "Some pieces always get refreshed; others never do." The signal triage is informal and inconsistent; some pieces are getting attention because they are visible, not because they are most decayed. +- "We refreshed a piece and forgot to re-promote it." Refresh-without-re-promotion; the piece's modified date updated but no audience or channel re-engagement happened. +- "Our quarterly audit catches things 75 days late." Quarterly cadence alone is missing sharp decay; add continuous monitoring for traffic-loss thresholds. +- "We refresh sister pieces but the hub orchestration is unchanged." Pieces refreshed in isolation when the hub-level architecture also needed updating; coordinate with `pillar-content-architecture` discipline. + +--- + +## The framework: 12 considerations for content refresh + +When designing or auditing a refresh program, walk these 12 considerations. + +1. Triaged-refresh, not refresh-everything or refresh-nothing. Refresh on signal, not on calendar. +2. Signal categories named. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. +3. Audit cadence committed. Quarterly audit plus continuous monitoring; both running. +4. Prioritization matrix applied. High-value-decaying first; low-value-decaying audited for merge or delete. +5. Depth matched to signal. Light edit, substantial revision, full rewrite, structural redesign. +6. Disposition decided per piece. Refresh, merge, or delete; not all decay warrants refresh. +7. Single ownership per refresh. Accountable owner runs the work to ship. +8. Capacity allocation explicit. Refresh ratio of editorial capacity is a real number, planned. +9. Re-promotion built into the workflow. Schema, visible date, search-engine resubmit, audience re-share. +10. Per-refresh tracking. Signals, depth, outcomes logged for pattern detection. +11. Effectiveness measurement. Recovery tracked at 30 and 90 days; patterns inform program decisions. +12. The-refresh-that-did-not-work review. Failed refreshes get structured review; lessons compound. + +The output of the framework is a refresh program that is auditable, capacity-respecting, and producing visible value for the library's compounding equity. + +--- + +## Reference files + +- [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md) - Five signal categories with detection patterns. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. The audit pattern that surfaces signals across the library. +- [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md) - Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, alert-threshold design. +- [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md) - 2x2 matrix with quadrant strategies. High-value-decaying as top priority; low-value-decaying audited for merge or delete; the discipline of NOT refreshing the high-value-stable quadrant. +- [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md) - Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, depth-creep anti-pattern. +- [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md) - Disposition criteria. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged. +- [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md) - Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. +- [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md) - Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. +- [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md) - Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. +- [`references/common-refresh-failures.md`](references/common-refresh-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: refresh is content's immune system + +A content library is a long-running system. The pieces in it interact with search algorithms that change, audiences that shift, brands that evolve, and competitors that publish. Set-and-forget treats the library as a static asset and watches it decay. Refresh-everything treats it as a maintenance project and burns capacity that should be producing new flagship work. + +The discipline is the immune system: signals are detected early, prioritization concentrates effort where the value is highest, depth matches signal strength, dispositions include merge and delete (not just refresh), and the work is tracked so the program learns. Programs that run this discipline preserve the library's compounding value. Programs that do not watch the library erode and discover the loss only when an algorithm update or a competitor's flagship piece exposes how far the rot has spread. + +When in doubt about whether a refresh program is ready, ask: does the program detect signals, prioritize on value, match depth to signal, decide between refresh and merge and delete, allocate capacity explicitly, re-promote the refreshed pieces, and track effectiveness? If yes to all of those, the program is real. If no to any, the gap is where decay will compound. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md b/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md new file mode 100644 index 0000000..4667597 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/audit-cadence-patterns.md @@ -0,0 +1,162 @@ +# Audit cadence patterns + +Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, and alert-threshold design. + +The audit cadence determines how quickly decay signals turn into refresh decisions. Programs that audit annually catch decay 9-12 months late; programs that monitor continuously without an audit layer catch sharp decay early but miss the slow-drift and content-drift signals that need human review. The hybrid pattern is the standard for mature programs. + +--- + +## The quarterly audit + +A formal review of the content library every 90 days. + +The mechanics. + +- The team blocks 1-3 days per quarter for the audit. +- Pull data: traffic per URL over the last 90 and 180 days, rankings on target keywords, last-modified dates, target-keyword SERP samples. +- Run each piece through the five-signal checklist (see `refresh-signals-checklist.md`). +- Assign each piece a disposition: refresh (with depth), merge, delete, monitor, no action. +- Output a refresh queue prioritized by the prioritization matrix. + +Strengths. + +- Predictable. The team knows when audit work happens and can plan around it. +- Auditable. Each quarter's decisions are documented; patterns over multiple quarters become visible. +- Comprehensive. The signal types that need human judgment (content drift, SERP intent shift) get reviewed; continuous monitoring cannot detect these without human eyes. +- Capacity-aware. Audit work happens at known times; new production schedules can flex around it. + +Weaknesses. + +- 90-day delay in detecting sharp decay. A piece that lost 40% traffic in week 2 of the quarter is in decay for 75 days before the audit catches it. +- Heavy lift. Auditing 200-2,000 pieces in 1-3 days requires structured tooling; teams without tooling burn out. +- Focus on the audit moment can crowd out continuous attention. "We will catch it next quarter" becomes the answer to issues that warrant immediate response. + +--- + +## Continuous monitoring + +Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. + +The mechanics. + +- Define thresholds for sharp decay: e.g., traffic drop of 25%+ in 14 days, ranking drop of 5+ positions in 14 days. +- Automated monitoring runs daily or weekly, comparing current data to baseline. +- Alerts route to the editorial owner of the affected piece (or to a refresh queue triage owner if pieces do not have individual owners). +- Triage decides whether the alert warrants immediate refresh, addition to the next quarterly audit's queue, or dismissal as noise. + +Strengths. + +- Catches sharp decay early. Algorithm-update fallout, technical regressions, and dramatic SERP intent shifts get attention within days, not 75-90 days. +- Allows fast response. A piece that lost 50% traffic on a specific date can be investigated while the cause is fresh. +- Reduces audit-day exhaustion. Sharp signals are handled in real time; the quarterly audit focuses on the slower signals. + +Weaknesses. + +- Requires monitoring infrastructure. Teams need rank tracking, traffic monitoring, and alerting that can route to specific URL owners. +- Alert fatigue if thresholds are too tight. Daily alerts on minor fluctuations train the team to ignore the alerts; thresholds need calibration. +- Misses slow decay. Pieces declining 5-8% per quarter never cross thresholds; they accumulate decay invisibly. The quarterly audit is what catches these. +- Misses non-traffic signals. Continuous monitoring on traffic and rankings cannot detect content drift or factual staleness. + +--- + +## The hybrid pattern + +Most strong refresh programs run both. The quarterly audit catches slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. + +Integration shape. + +- Continuous monitoring runs daily or weekly with a small set of well-calibrated thresholds. +- Quarterly audit runs the full signal checklist on the whole library. +- Pieces that triggered continuous-monitoring alerts during the quarter get fast-track disposition; the quarterly audit reviews the rest. +- The continuous-monitoring log feeds into the quarterly audit so the team can see whether thresholds are calibrated correctly (too many false alerts, too few real ones). + +Capacity split. A typical hybrid pattern might allocate 5-10% of editorial capacity to continuous-monitoring response (a few hours per week) and a concentrated 1-3 days per quarter to the audit. The split scales with library size and decay rates. + +--- + +## Alert-threshold design + +Calibrating continuous-monitoring thresholds is its own discipline. + +Threshold goals. + +- High precision: when the threshold is crossed, the alert is usually a real signal, not noise. +- Reasonable recall: catches the sharp-decay events that matter; does not need to catch every minor fluctuation (the audit catches those). +- Sustainable cadence: alerts arrive at a frequency the team can triage without fatigue. + +Threshold patterns that work. + +- Traffic: 25%+ drop in 14 days, sustained over 21 days. The sustainment requirement filters volatility. +- Ranking: 5+ position drop on a tracked keyword, sustained over 14 days. Single-day drops are noise; sustained drops are signal. +- Indexing: any unexpected change in indexed status (200 to non-200 status, sudden noindex tag, sudden disappearance from index). These are usually technical regressions and warrant immediate attention. +- Schema validation: schema breaking or warnings appearing on a piece that previously validated cleanly. Often indicates a CMS update or template change. + +Threshold patterns that fail. + +- 10% traffic drop alerts produce far too many false positives; teams stop reading the alerts. +- Single-day rank drop alerts produce noise; SERP volatility within a few positions is normal. +- Aggregate-traffic alerts on whole categories rather than per-URL alerts hide which specific pieces are decaying. + +Threshold tuning. Run alerts in shadow mode for 4-6 weeks before committing. Track whether alerts correspond to real signals on review. Adjust thresholds based on the precision-recall observed. + +--- + +## When to audit more frequently + +Some programs warrant more than quarterly audits. + +Programs in active rebuild. Content libraries undergoing structural redesign or hub reorganization benefit from monthly audits during the rebuild phase. The signal volume is higher and the decisions need faster cycle time. + +Post-algorithm-update period. In the 30-90 days after a major algorithm update, signal volume spikes. Some teams run a special audit at the 30-day post-update mark in addition to the regular quarterly cadence. + +Programs with rapid topic evolution. Topics that move quickly (AI tools, evolving regulatory environments, tactical playbooks in fast-moving fields) may benefit from monthly factual-staleness checks even when traffic and ranking signals are stable. + +--- + +## When to audit less frequently + +Some programs can run on lighter cadence. + +Small libraries (under 50 pieces) with stable performance. Bi-annual audits may be sufficient if continuous monitoring is in place and the library has shown stable decay rates over multiple cycles. + +Libraries dominated by evergreen pieces. When the topical mix is heavily evergreen (foundational concepts that move slowly), quarterly audits may produce limited signal volume. Combine with continuous monitoring; reduce audit frequency. + +The discipline. Cadence should match decay rate, not be fixed by convention. Programs that decay quickly need faster cadence; programs that decay slowly can run longer audit cycles. + +--- + +## Audit anti-patterns + +Annual audit as the only cadence. Catches decay 9-12 months late; the library is in significant erosion before the audit runs. + +Continuous monitoring without quarterly audit. Catches sharp decay; misses slow decay, content drift, and SERP intent shifts that need human review. + +Audit happening but no follow-through. The team runs the audit, produces a queue, then loses momentum on actually executing the refreshes. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +Audit without prioritization. The output is a list of every piece showing any signal, with no value-weighted prioritization. The team does the cheapest refreshes first regardless of value, leaving high-value-decaying pieces in the backlog. + +Audit without depth assignment. Pieces are tagged "refresh" without specifying depth. Refresh execution defaults to whatever depth the team has time for, which is often light edit even when substantial revision is needed. + +--- + +## Audit governance + +Who runs the audit, who approves dispositions, how the queue routes to execution. + +Single audit owner. A specific person runs the audit each quarter, accountable for signal quality and disposition recommendations. + +Disposition review. Refresh, merge, and delete dispositions are reviewed by a content lead or director. Delete dispositions in particular need approval because they are irreversible (pieces deleted and not redirected can lose authority that did not need to be lost). + +Queue routing. The refresh queue routes to specific editorial owners based on capacity, expertise, and the depth of work required. Light edits route to anyone with capacity; full rewrites route to the writer or editor best matched to the topic. + +Audit log. Each quarter's audit, dispositions, and outcomes are logged. The log feeds the next quarter's review (which dispositions actually shipped, which produced recovery, which patterns are emerging). + +--- + +## Methodology-level choices that stay in the public skill + +The quarterly audit mechanics, continuous monitoring mechanics, hybrid pattern, alert-threshold design principles, audit-cadence variations, audit governance shape, and the anti-patterns. + +## Implementation choices that stay internal + +Specific monitoring tools the team uses (rank trackers, analytics platforms, alerting systems). Specific threshold values calibrated to the team's data. Specific dashboards and reporting templates. Specific ticketing or queue systems for refresh routing. Specific automation scripts that pull data into audit-ready formats. The team's own audit-day rituals and tooling. These vary by team, tooling, and library size. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md b/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md new file mode 100644 index 0000000..df86203 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/common-refresh-failures.md @@ -0,0 +1,169 @@ +# Common refresh failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear across programs of different sizes, library ages, and editorial team compositions; the underlying causes are rarely about people and almost always about discipline, prioritization, or measurement gaps. + +--- + +## Failure 1: Refresh-everything-on-calendar + +Symptom. Every piece gets refreshed on a 12-month or 18-month rotation regardless of signals. Editorial capacity is consumed by maintenance work that often was not needed. + +Diagnosis. The program treats refresh as a calendar event rather than as a signal-driven decision. Pieces that were performing get touched into worse versions; pieces that were decaying are scheduled for refresh whenever their rotation comes up rather than when the decay signals warrant. + +Cure. Replace calendar-driven refresh with the prioritization matrix and the signal-driven audit cadence. Refresh on signals; leave stable pieces alone. + +Capacity recovery. Programs that abandon refresh-everything typically recover 30-50% of their refresh capacity for higher-value work or for new production. + +--- + +## Failure 2: Set-and-forget + +Symptom. The team has not touched the library in 18+ months. Traffic has eroded across the library; the team is uncertain how much loss is from refresh failure vs other causes. + +Diagnosis. The program lacks both audit cadence and continuous monitoring. Decay accumulates silently because no system is detecting it. + +Cure. Establish the hybrid audit pattern: quarterly audit plus continuous monitoring. The first audit will surface a large queue (typical when starting from set-and-forget); the queue should be triaged by the prioritization matrix and worked through over multiple quarters rather than tackled all at once. + +--- + +## Failure 3: Refresh that should have been merge or delete + +Symptom. The team spends hours refreshing pieces that even at their best will not produce meaningful recovery. The same pieces appear in queue across multiple audits. + +Diagnosis. The disposition decision was wrong. Refresh was the default disposition because it felt less destructive than merge or delete; the actual right disposition was merge into a stronger sibling or delete with redirect. + +Cure. Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. Train the audit owner on the disposition decision flow (see `refresh-vs-merge-vs-delete.md`). + +--- + +## Failure 4: Unprioritized refresh queue + +Symptom. The refresh queue is 200 pieces deep and growing. The team works through the queue in order of arrival or in order of "easiest first" rather than by value. + +Diagnosis. No prioritization matrix is being applied. Every piece showing any signal goes in the queue regardless of value. + +Cure. Apply the 2x2 matrix (value × traffic state). Queue entries get tagged by quadrant. Work focuses on high-value-decaying first; low-value-decaying gets disposition decisions (often merge or delete) rather than refresh; stable quadrants get monitor or no action. + +--- + +## Failure 5: Refresh-on-stable-piece regression + +Symptom. A flagship piece was performing well. The team refreshed it because it was the next piece in the rotation. After the refresh, traffic dropped 30% and rankings dropped 5 positions. + +Diagnosis. Refresh-everything-on-calendar damaged a stable piece. The refresh introduced changes that shifted the SERP signals or the piece's structural fit; the new version performs worse than the original. + +Cure. Stop refreshing high-value-stable pieces by default. Pieces in this quadrant get monitor disposition unless content drift is severe enough to warrant the regression risk. When refreshing a stable piece is genuinely warranted, plan for fast revert if regression occurs. + +Recovery. Some refresh regressions can be partially reversed by going back to a closer-to-original version of the piece. Some cannot. The lesson informs future stable-piece refresh decisions. + +--- + +## Failure 6: Capacity overcommitment + +Symptom. The team is exhausted from refresh work. New-piece production is suffering. The team complains of refresh fatigue. + +Diagnosis. Capacity allocation to refresh is too high (or new-production commitments are too high; the result is the same). The team is being asked to do more total work than capacity allows. + +Cure. Right-size the allocation. Reduce refresh queue intake by tightening prioritization (only highest-value items enter the queue); or reduce new-production commitments; or temporarily increase capacity. The status quo is unsustainable. + +Sustainability check. Capacity is real. Programs that pretend capacity is infinite produce burnout, quality drift, and team turnover. The capacity audit (see `refresh-execution-patterns.md`) is what catches this before burnout. + +--- + +## Failure 7: Effectiveness invisible + +Symptom. "We do not know if our refreshes are working." Refresh work happens but its effectiveness is not tracked or reviewed. + +Diagnosis. No per-refresh tracking is in place. The program runs without learning data. + +Cure. Establish the minimum log (see `effectiveness-measurement.md`). Backfill the log for recent refreshes if possible. Establish 30-day and 90-day measurement windows. Run quarterly pattern-detection reviews. + +Adoption. Logging adds overhead. Programs that resist logging often discover later that the program's effectiveness has been declining for quarters and they cannot tell why because the data was not captured. The overhead of logging is small compared to the cost of running the program blind. + +--- + +## Failure 8: Inconsistent refresh attention + +Symptom. Some pieces always get refreshed; others never do. The pattern correlates with which writers prefer which topics, not with which pieces need refresh most. + +Diagnosis. The signal triage is informal and inconsistent. Pieces are getting attention because they are visible to certain people, not because they are most decayed. + +Cure. Formalize the audit so signal detection is data-driven rather than memory-driven. The matrix and the audit log force visibility on the whole library, not just on the pieces individual team members happen to think of. + +--- + +## Failure 9: Refresh-without-re-promotion + +Symptom. Refreshes ship. Modified dates update. The team waits for traffic recovery. Recovery is marginal at best. The team concludes refresh does not work. + +Diagnosis. Re-promotion was skipped. Search engines saw the modified date but audiences did not engage; the recovery curve that re-promotion typically produces did not happen. + +Cure. Build re-promotion into the workflow as a non-skippable step. Match re-promotion intensity to refresh depth (see `re-promotion-after-refresh.md`). The refresh is not "done" when published; the refresh is "done" when re-promotion has executed. + +--- + +## Failure 10: Audit without follow-through + +Symptom. The team runs the quarterly audit; produces a queue; the queue largely sits unworked; the next quarter's audit shows the same pieces in queue. + +Diagnosis. No owner-of-owners is keeping the queue moving. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +Cure. Assign an owner-of-owners role for the refresh program as a whole. Their job is queue movement, escalation of stalled refreshes, and program-level reporting. Without this role, even good audits do not produce execution. + +--- + +## Failure 11: Quarterly cadence too slow for sharp decay + +Symptom. The quarterly audit catches a piece in significant decay. The traffic loss has been accumulating for 75 days before the audit caught it. The recovery is harder because the decay has compounded. + +Diagnosis. Quarterly cadence alone is missing sharp decay. The lag between decay and detection is too long. + +Cure. Add continuous monitoring for traffic-decay and ranking-drop thresholds. Sharp decay alerts route to fast-track triage; the quarterly audit focuses on slower signals that continuous monitoring cannot detect (content drift, factual staleness, SERP intent shift). + +--- + +## Failure 12: Refresh in isolation when hub orchestration changed + +Symptom. Pieces are refreshed individually but the hub-level architecture also needed updating. The refreshes ship; the hub-level decay continues because the architecture problem was unaddressed. + +Diagnosis. Piece-level refresh is being done without coordination with hub-level architecture. Some refresh queues need to escalate to structural-redesign disposition rather than be addressed at piece level. + +Cure. Coordinate with `pillar-content-architecture` discipline. When piece-level refresh is bumping against architecture-level issues, escalate to a structural-redesign project. Some refresh attempts cannot succeed without the hub-level work. + +--- + +## Failure 13: Stalled refreshes accumulating + +Symptom. The refresh queue contains zombie items: pieces assigned months ago that have not shipped and are not progressing. Everyone knows they are stalled; nobody is removing them. + +Diagnosis. No stalled-refresh recovery process. Refreshes that get stuck stay stuck because there is no review mechanism to escalate or reassign. + +Cure. Build stalled-refresh review into each quarterly audit. Refreshes that have been in queue more than two cycles get reviewed: reassign owners, re-scope depth, or remove from queue if the disposition was wrong. The review prevents zombie accumulation. + +--- + +## Failure 14: Light-edit-as-default + +Symptom. Most refreshes are light edits regardless of signal strength. The light edits do not move the needle on pieces that needed substantial revision; the team concludes "refresh does not work" when the actual issue is depth mismatch. + +Diagnosis. Depth assignment is defaulting to light edit because light edits are the easiest to schedule. Substantial revision and full rewrite are being skipped because they are harder to fit into capacity. + +Cure. Match depth to signal strength explicitly. Depth-light when signals support light edit; depth-deeper when signals warrant. Capacity allocation should account for depth distribution; if the team consistently has capacity only for light edits, the allocation needs adjustment, not the depth assignment. + +--- + +## The cross-cutting pattern + +Most refresh failures share a single root: shortcuts in discipline. Calendar-refresh shortcuts the signal analysis. No-measurement shortcuts the learning. Refresh-as-default shortcuts the disposition decision. Light-edit-as-default shortcuts the depth decision. No-re-promotion shortcuts the audience-engagement work. Each shortcut feels like it is saving capacity; each shortcut is actually shifting capacity to lower-value work. + +The fix for almost any refresh failure is the same: surface the discipline that was being shortcutted, and pay the cost of running the discipline. The capacity recovered from eliminating low-value refreshes typically more than pays for the discipline overhead. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the discipline-as-cure observation. + +## Implementation choices that stay internal + +Specific tooling for stalled-refresh detection. Specific reporting templates for owner-of-owners updates. Specific reviewer training on disposition decisions. Specific automation that catches refresh-without-re-promotion. The team's own conventions for capacity recalibration when overcommitment is detected. These vary by team, tooling, and program structure. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md b/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md new file mode 100644 index 0000000..7e6d0d3 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/effectiveness-measurement.md @@ -0,0 +1,150 @@ +# Effectiveness measurement + +Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. The discipline that prevents refresh-theater and turns the refresh program into a learning system. + +Refresh effectiveness measurement is the difference between a program that learns and a program that runs. Programs without measurement run the same patterns indefinitely, including the patterns that do not work; programs with measurement see which refreshes produce recovery, which do not, and what the patterns reveal about depth, signal interpretation, and disposition decisions. + +--- + +## Per-refresh tracking + +Each refresh is logged with the data needed to evaluate it. + +The minimum log. + +- URL. The refreshed piece. +- Date shipped. When the refresh published. +- Signals that triggered the refresh. Which of the five signal categories were active; signal severity. +- Disposition. Refresh, merge, delete (with target URLs for merge). +- Depth. Light edit, substantial revision, full rewrite, structural redesign. +- Owner. Who shipped the refresh. +- Capacity spent. Hours of editorial time invested. +- Predicted outcome. What the team expected the refresh to produce (recovery within X% in Y days, or qualitative expectation). +- Actual outcome at 30 days. Traffic, ranking, engagement metrics post-refresh vs pre-refresh. +- Actual outcome at 90 days. Same metrics extended to 90 days. +- Notes. Qualitative observations on what happened, surprising patterns, questions raised. + +Why the minimum log. Each field is load-bearing for pattern detection. Without signals, you cannot tell whether decay-driven refreshes recover differently from drift-driven refreshes. Without depth, you cannot tell whether full rewrites outperform substantial revisions. Without capacity, you cannot evaluate ROI. + +The log as program memory. Across years, the log becomes the program's accumulated learning. A team that has logged 200 refreshes can answer questions like "what is the typical recovery curve for substantial-revision refreshes on traffic-decayed pieces?" with data; a team without the log answers the same question with anecdote. + +--- + +## 30-day recovery measurement + +The first measurement window post-refresh. + +What the 30-day window shows. + +- Schema and indexing recognition. Search engines have crawled the updated piece and registered the modified date. +- Initial ranking response. Some ranking shifts happen within days as the search engine re-evaluates; others take longer. +- Audience engagement spike. Re-promotion produces traffic from newsletter, social, and syndication. The 30-day window captures the immediate engagement. +- Quick wins or regressions. If the refresh broke something (regressions in indexing, schema, or ranking), the 30-day window catches it. + +What the 30-day window does not show. + +- Sustained recovery. Initial spikes from re-promotion fade; the 30-day window cannot distinguish sustained recovery from re-promotion afterglow. +- Algorithm-update response. If an algorithm update happens after the refresh, the 30-day measurement may be confounded. +- Long-tail keyword recovery. Some long-tail rankings move slowly; the 30-day window may show only head-term response. + +The 30-day pattern. Most refreshes that will produce sustained recovery show some signal at 30 days: ranking improvement, traffic uptick, engagement spike. Refreshes that show no signal at 30 days are not necessarily failures, but they warrant attention; the 90-day measurement will resolve the question. + +--- + +## 90-day recovery measurement + +The longer-window measurement that confirms or refutes the 30-day signal. + +What the 90-day window shows. + +- Sustained recovery. Initial spikes have faded; what remains is the refresh's durable contribution. +- Algorithm-update integration. Most algorithm updates have been digested; the 90-day data reflects the new state. +- Long-tail keyword response. Slower-moving rankings have settled. +- Engagement-based metrics. Time on page, return visits, scroll depth post-refresh vs pre-refresh. + +The 90-day pattern. + +- Strong recovery. Traffic and rankings are above pre-refresh baseline by 20%+. The refresh worked. +- Modest recovery. Traffic and rankings are 5-20% above pre-refresh baseline. The refresh helped but did not produce dramatic improvement. +- No recovery. Traffic and rankings are within 5% of pre-refresh baseline. The refresh was not effective. +- Regression. Traffic or rankings are below pre-refresh baseline. The refresh damaged the piece. + +The 90-day measurement is the primary effectiveness measurement. The 30-day is the early-warning; the 90-day is the verdict. + +--- + +## Pattern detection across refreshes + +Individual refresh measurements are noisy. Patterns across refreshes are signal. + +Patterns the log reveals. + +- Depth-effectiveness. Are full rewrites producing better recovery than substantial revisions on similar signals? If yes, the team should consider deeper depth on similar future cases. +- Signal-effectiveness. Are traffic-decay refreshes recovering more reliably than content-drift refreshes? If yes, the program may benefit from prioritizing traffic-decay queue and being more selective about content-drift refresh. +- Disposition-effectiveness. Are pieces in the high-value-decaying quadrant recovering when refreshed, or are they continuing to decay? If continuing decay, the disposition may be wrong (merge or delete may have been better) or the underlying cause is structural (the topic is dying; competitors too strong). +- Owner-effectiveness. Are some owners producing better recovery than others on similar refreshes? Possibly skill differential, possibly capacity issues, possibly random variation that needs more data. +- Topic-effectiveness. Are refreshes on some topics recovering reliably while others do not? Some topics may be in structural decline; the program may need to reduce investment in those topics rather than increase refresh effort. + +Pattern detection cadence. Quarterly review of accumulated refresh data. Year-over-year reviews on multi-year programs. The patterns inform program-level decisions about allocation, prioritization, and disposition defaults. + +--- + +## The refresh-that-did-not-work review + +Refreshes that did not produce recovery are the program's most valuable learning data. + +The review questions. + +- Was the depth wrong? Did the refresh need more depth than was applied? Light edit when substantial revision was needed produces no recovery on substantial-decay signals. +- Was the disposition wrong? Should the piece have been merged or deleted instead of refreshed? Refreshing a piece that should have been merged produces ongoing decay because the underlying authority-splitting was not addressed. +- Was the signal interpretation wrong? Did the team read decay as content-drift when it was actually competitor-displacement? Refresh on the wrong cause does not produce recovery. +- Is the topic in structural decline? Some topics decline structurally; refresh cannot recover what the topic itself has lost. The right disposition may be to reduce investment in the topic and reallocate capacity. +- Did re-promotion happen? Refresh-without-re-promotion underperforms; some "did not work" cases are actually "did not get re-promoted." + +The review output. Each non-recovery refresh produces either: a re-disposition (try merge or delete), a depth re-attempt (next quarter try the deeper depth), or an acknowledgment that the topic is in decline and the program should reduce investment. + +The review's program impact. Without the review, non-recovery refreshes accumulate as silent program failures. With the review, the patterns surface and the program adjusts. + +--- + +## Effectiveness metrics by refresh purpose + +Different refresh purposes warrant different primary metrics. + +Traffic-decay refreshes. Primary metric: post-refresh traffic recovery vs pre-refresh baseline at 90 days. Secondary: ranking position recovery on target keywords. + +Ranking-drop refreshes. Primary metric: ranking position recovery on target keywords at 90 days. Secondary: traffic recovery (rankings without traffic recovery suggest CTR issues that ranking alone does not capture). + +Factual-staleness refreshes. Primary metric: less straightforward; the refresh's purpose is correctness, not recovery. Track that the staleness was caught before reader-detected errors compound. Secondary: any traffic recovery is bonus. + +SERP-intent-shift refreshes. Primary metric: ranking on target keywords (rankings reflect format-fit). Secondary: engagement metrics (the refresh changed format; does the new format engage better?). + +Content-drift refreshes. Primary metric: engagement metrics (time on page, return visits, conversions). Secondary: voice consistency review (qualitative; the refresh purpose was alignment with current brand positioning). + +The metric should match the purpose. Programs that measure every refresh by traffic recovery miss the value of refreshes whose purpose was correctness or alignment rather than recovery. + +--- + +## Common measurement failures + +No measurement at all. Refreshes ship; outcomes are not tracked; the program runs without learning. Each refresh is a fresh prediction with no accumulated evidence. + +Measurement at the wrong window. Measuring at 7 days captures only re-promotion afterglow; measuring at 6 months conflates many other variables. 30 and 90 days are the workable windows. + +Single-metric measurement. Measuring only traffic ignores ranking, engagement, and conversion metrics. Different refresh purposes warrant different metrics. + +Measurement without context. Comparing post-refresh metrics to pre-refresh metrics without accounting for seasonality, algorithm updates, or competitor activity produces noisy attribution. + +No pattern detection. Per-refresh measurement happens but never gets aggregated into pattern review; the program does not learn across refreshes. + +No non-recovery review. Successful refreshes get celebrated; failed refreshes get forgotten. The asymmetry hides the program's most valuable learning. + +--- + +## Methodology-level choices that stay in the public skill + +The minimum per-refresh log fields, the 30-day and 90-day measurement windows, the pattern-detection cadence, the refresh-that-did-not-work review, the metric-by-purpose mapping, the common measurement failures. + +## Implementation choices that stay internal + +Specific analytics dashboards that pull refresh metrics. Specific log structure in the team's project-management or content system. Specific seasonality models the team uses to baseline. Specific competitor-activity tracking that contextualizes attribution. Specific reviewer workflow for non-recovery refreshes. The team's own pattern-detection rituals. These vary by team, tooling, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md b/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md new file mode 100644 index 0000000..1f20605 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/re-promotion-after-refresh.md @@ -0,0 +1,159 @@ +# Re-promotion after refresh + +Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. The patterns that signal a refresh to search engines and audiences. + +A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement that re-promotion produces. Programs that ship refreshes silently leave value on the table. + +--- + +## Signal to search engines + +What the search engine needs to see to recognize the refresh. + +Modified-date in schema markup. Schema.org Article (and related types) include a `dateModified` field. Update this when the refresh ships. Many CMS platforms update this automatically on save; verify the automation is working. Schemas with stale modified dates signal that the refresh is technical rather than substantive. + +Visible modified-date on the page. The page should display "Updated [date]" or similar visible signal. Some templates show "Published [date]" without an updated date; these should be updated to surface the refresh date. + +Sitemap update. The XML sitemap's `lastmod` field for the URL should reflect the refresh date. Most sitemap generators handle this automatically; verify after the refresh ships. + +Search Console URL inspection and resubmission. For high-priority refreshes, use Search Console's URL inspection tool and request indexing. This signals the refresh to the index without waiting for the next crawl. Use sparingly; bulk resubmission of every refresh can throttle. + +Internal-link-graph signals. When sister pieces add or update links to the refreshed piece, the additional internal-link signals reinforce that the URL is current and load-bearing. Refresh that updates internal linking from sister pieces sends stronger signals than refresh that does not. + +--- + +## Substantive vs cosmetic modifications + +Search engines distinguish between substantive content changes and cosmetic touch-ups. + +Substantive changes. Body content edits, section additions or removals, lede or closing rewrites, factual updates, restructuring. The refresh has changed what the piece says. + +Cosmetic changes. Date stamp updates without content changes. CSS or template changes. Whitespace edits. These do not constitute refresh; updating the modified date without substantive change is signaling a refresh that did not happen. + +Why the distinction matters. Search engines that detect the modified-date signal as cosmetic rather than substantive can devalue the signal. Programs that bump modified dates without substantive change to chase the refresh signal are running a tactic that has been increasingly detected and discounted. The honest signal is a real refresh; the tactic of date-bumping without change is short-lived value at best. + +The audit. Refreshes should produce diff'able content changes. If the refresh ships without diff'able changes, it is not a refresh. + +--- + +## Signal to audiences + +The other half of re-promotion: re-engaging the audiences who saw the original. + +Newsletter re-share. For pieces that originally went to the newsletter, a refreshed piece deserves a re-share. The framing is "we updated this with [specific updates]," not "here is a piece you may have seen before." Specificity earns re-engagement; vague re-shares feel like filler. + +Social re-share. For pieces that originally landed on social channels, the refresh is a social moment. New angle, new pull-quote, new visual, framing the refresh as the news the piece now carries. + +Syndication partner update. For pieces syndicated to partner platforms, the refresh may warrant communication with syndication partners about the updated version. Some partners pull the latest content automatically; some do not. The refresh communication closes the loop. + +Email-list segmentation. For programs with sophisticated email-list segmentation, refreshed pieces can be sent to segments that did not see the original or that engaged with the original and may benefit from the updated version. + +Re-share cadence discipline. Not every refresh deserves the same re-share intensity. Light edits typically do not warrant social re-share; substantial revisions or full rewrites do. Calibrate re-share to depth. + +--- + +## Internal linking refresh + +Pieces that link to the refreshed piece may benefit from anchor-text updates. + +When anchor-text update fits. The refreshed piece's positioning shifted, and the anchor text on sister pieces should now describe the piece differently. A piece that linked to the refreshed piece as "our guide to programmatic SEO" may now want to link as "our guide to programmatic SEO durability" if the refreshed piece's framing is now durability-focused. + +When sister pieces should now link to the refreshed piece. Some refreshes add coverage of topics that sister pieces discuss. Pieces discussing those topics that did not previously link to the refreshed piece may now warrant new internal links. + +The internal-link-refresh pass. Some programs run a quick pass after each substantial refresh: search the library for pieces mentioning the refreshed piece's topic, audit whether the existing anchor text and link presence are correct, update where warranted. + +The over-linking failure. Refreshes that trigger 30 internal-link updates across the library can create maintenance overhead disproportionate to value. The internal-link refresh should be targeted, not exhaustive. + +--- + +## URL preservation vs URL change + +Most refreshes preserve the URL. Some warrant URL change. + +Preserve the URL when: + +- The refresh is light edit, substantial revision, or most full rewrites. +- The existing URL has authority worth preserving (rankings, backlinks, internal-link references). +- The URL slug fits the refreshed piece's framing reasonably well even if not perfectly. + +Change the URL when: + +- The refresh is a structural redesign and the URL slug no longer fits. +- The piece is being merged with a sibling and the consolidated piece needs a new URL. +- The original URL was a structural mistake (wrong category, awkward slug) that the refresh is correcting. + +The URL-change cost. Even with 301 redirects, URL changes incur authority transfer cost; some authority does not survive the redirect. URL changes should be earned by structural rationale, not chosen for cosmetic reasons. + +The URL-preservation discipline. Most refreshes should preserve URLs. The default disposition is preserve; URL change is the exception requiring rationale. + +--- + +## The refresh that nobody told anyone about + +The pattern when re-promotion is skipped. + +The symptom. A refresh ships. Modified date updates. Schema validates. The piece sits in the library with the refresh complete on paper. Traffic recovers marginally if at all. The team concludes refresh does not work. + +The actual cause. Re-promotion was skipped. The refresh signaled to the search engine but did not signal to audiences. New-piece-style audience engagement (newsletter, social, syndication) did not happen. The refresh produced search-engine recognition without the audience-engagement spike that often drives broader recovery. + +The cure. Build re-promotion into the refresh workflow as a non-skippable step. The refresh is not "done" when the piece is published; the refresh is "done" when the re-promotion has been executed. Define re-promotion intensity per depth (light edit may need only modified-date and schema; substantial revision needs newsletter and social re-share; full rewrite needs full re-promotion treatment). + +--- + +## Re-promotion checklist by depth + +A short framework matching re-promotion to refresh depth. + +Light edit re-promotion. + +- Modified date in schema and visible. +- Sitemap lastmod. +- No audience re-share required for routine light edits. +- Internal-link audit only if specific anchor text changes warranted. + +Substantial revision re-promotion. + +- Modified date and visible date. +- Sitemap lastmod. +- Newsletter re-share with framing on what was updated. +- Social re-share to channels that originally promoted the piece. +- Internal-link audit on sister pieces with relevant topics. + +Full rewrite re-promotion. + +- All of the above. +- Search Console URL inspection and resubmission. +- Syndication partner update where applicable. +- Email-list segment send to engaged segments. +- Visual asset refresh for social and newsletter (new pull-quote graphics, new hero image if applicable). + +Structural redesign re-promotion. + +- All of the above. +- Coordination with the broader hub or category being redesigned (see `pillar-content-architecture`). +- Cross-piece internal-link audit across the affected hub or category. +- Possible launch communication if the redesign represents a major program milestone. + +--- + +## Re-promotion failure modes + +Skipping re-promotion entirely. The refresh produces marginal recovery; the team concludes refresh does not work; the program loses momentum. + +Bulk-resubmitting every refresh URL to Search Console. Search Console's URL submission has implicit rate limits; bulk submission of low-value refreshes throttles the team's submission capacity for the cases that warrant it. + +Re-share without specificity. "We refreshed this piece; here it is" lacks the specific framing that earns re-engagement. Specific framing ("we added the 2026 data and a new section on X") earns clicks; vague re-shares get ignored. + +Anchor-text updates that proliferate. Internal-link refresh that touches every mention of the topic across the library is over-investment. Target specifically; touch sparingly. + +Modified-date bumping without content change. The signal that gets discounted by search engines and signals to careful auditors that the team is gaming the metric rather than producing substantive refresh. + +--- + +## Methodology-level choices that stay in the public skill + +The signal-to-search-engine patterns, the substantive-vs-cosmetic distinction, the audience re-promotion patterns, the internal-link refresh discipline, the URL-preservation default, the re-promotion checklist by depth, the re-promotion failure modes. + +## Implementation choices that stay internal + +Specific schema markup automation in the team's CMS. Specific newsletter and social-publishing tooling and templates. Specific Search Console workflow conventions. Specific internal-link-audit automation. Specific syndication-partner communication channels. The team's own depth-to-re-promotion-intensity mappings. These vary by team, stack, and channel mix. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md new file mode 100644 index 0000000..4e55045 --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-depth-decision.md @@ -0,0 +1,174 @@ +# Refresh depth decision + +Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, the depth-creep anti-pattern. + +Refresh depth is one of the most consequential decisions in the program. The wrong depth produces predictable failure: light edits on pieces that needed substantial revision produce no recovery; full rewrites on pieces that only needed factual updates burn capacity. The discipline is matching depth to signal strength. + +--- + +## Depth 1: Light edit + +The work. Update statistics. Replace dead links. Fix factual errors. Swap dated examples. Update product or platform references. Verify external links still resolve and still go where they should. + +Time investment. 30-90 minutes per piece for typical pieces. Longer for research-heavy pieces with many external citations. + +The piece's structure stays intact. Section weights, lede, closing, archetype, voice, claims-and-arguments are all preserved. The light edit is surface maintenance. + +Use when. + +- Factual staleness is the only or dominant signal. +- Traffic is stable or only slightly decayed. +- The piece's structural framing still fits current SERP intent and brand positioning. +- The piece is performing well enough that significant changes would risk performance. + +Common failures. + +- Light-editing when substantial revision is warranted. Surface fixes do not address the structural reasons for decay; the piece continues to decay after the light edit ships. +- Light edits that touch more than they should. A "light edit" that becomes 4 hours of work because the editor kept finding things has lost the depth discipline; either commit to substantial revision or stop at the originally scoped scope. + +--- + +## Depth 2: Substantial revision + +The work. Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that have emerged since the piece was written. Restructure 1-3 H2 sections without redesigning the piece's overall shape. + +Time investment. 2-4 hours per piece for typical pieces. Longer for pieces with extensive new sections to add. + +The piece's spine stays intact. The archetype, the central thesis, and most sections survive. Specific sections are rewritten or added. + +Use when. + +- Traffic has decayed moderately but not catastrophically. +- Specific sections of the piece have aged badly (often the introduction, closing, or a section on a topic that has shifted). +- New topics have emerged that the piece needs to cover to stay current. +- The piece's structural framing is mostly fine but needs targeted updates. + +Common failures. + +- Substantial revision drifting into full rewrite. The "substantial revision" that becomes 8 hours of work has crossed into full-rewrite territory; either commit to full rewrite or scope back to the original substantial-revision plan. +- Substantial revision that rewrites the introduction without rewriting the closing, leaving the piece structurally inconsistent (the introduction promises one shape; the closing delivers a different one). +- Rewriting sections without auditing whether the rewrites match each other in voice and density. + +--- + +## Depth 3: Full rewrite + +The work. Keep the URL and topic; rewrite the piece end-to-end. New lede, new structure (possibly new archetype), new closing. The new piece occupies the old piece's URL and connects to the existing internal-link graph. + +Time investment. Similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. 8-16 hours for typical long-form rewrites. + +The piece's spine changes. New archetype possible. New positioning possible. The connection to the URL and the existing topical authority is what is being preserved; everything else can change. + +Use when. + +- Traffic has decayed sharply or persistently. +- The piece's structural framing no longer fits current SERP intent. +- The brand's positioning has shifted enough that the piece needs to be re-conceived. +- Light edit and substantial revision have already been tried and did not produce recovery. + +Common failures. + +- Full rewrite that loses what worked. The original piece had specific strengths (a memorable lede, a particular section that drew links). The rewrite that does not preserve those strengths can perform worse than the original even if the rewrite is technically stronger. +- Full rewrite that breaks internal linking. Section IDs change, anchor links from sister pieces break, the internal-link graph that supported the piece's authority is disrupted. +- Full rewrite that ignores the URL constraint. The team rewrites as if writing a new piece, then realizes the URL is locked and the new framing does not fit the existing slug. Either accept the slug mismatch (suboptimal) or change the URL (incurring redirect cost). + +--- + +## Depth 4: Structural redesign + +The work. Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Often part of a larger structural change in the content library: a hub being rebuilt, a category being consolidated, a topic cluster being reorganized. + +Time investment. A multi-piece project. 1-3 weeks for a hub-level restructure involving multiple pieces. + +Multiple URLs and pieces are affected. The piece being refreshed is one node in a graph that is being reshaped. + +Use when. + +- Refresh of an individual piece is bumping against architecture-level issues that cannot be addressed at the piece level. +- A hub is being redesigned and pieces within the hub need to be reconceived as part of the redesign. +- Multiple pieces are competing for the same query and a consolidated piece would produce stronger authority than any of the individual pieces. + +Common failures. + +- Treating structural redesign as a refresh exercise rather than as a project. The work scope is project-scope; treating it as a refresh queue item leads to under-resourcing. +- Structural redesign without coordination with `pillar-content-architecture` discipline. The hub-level work and the piece-level work need to compose; doing them separately produces friction. +- Redirect plans that do not account for all the URLs being consolidated. Some authority is lost in transit because some redirects were missed. + +--- + +## Signal-to-depth matching + +A short framework for choosing depth from the signals. + +Light edit when: + +- Factual staleness is the dominant signal. +- Traffic stable or only slightly decayed (under 10%). +- Rankings stable or only slightly drifted. +- No SERP intent shift detected. +- No content drift detected. + +Substantial revision when: + +- Multiple signal types present (factual + content drift, or traffic decay + ranking drops). +- Traffic decayed moderately (10-25%). +- Rankings drifted but still on page 1. +- Specific sections have aged badly while others are sound. +- SERP intent has not shifted dramatically. + +Full rewrite when: + +- Traffic decayed sharply (25%+). +- Rankings dropped from page 1 to page 2 or beyond. +- SERP intent has shifted substantially (the dominant SERP format has changed). +- Brand positioning has shifted enough that the piece reads as the brand-of-multiple-years-ago. +- Light edit or substantial revision already attempted without recovery. + +Structural redesign when: + +- The piece's issues are architecture-level rather than piece-level. +- A hub or category is being reorganized. +- Multiple sibling pieces are competing for the same query and consolidation would produce stronger authority. + +--- + +## The depth-creep anti-pattern + +Refreshes that grow during execution from their planned depth into a deeper depth that was not budgeted. + +The pattern. A refresh planned as a light edit becomes substantial revision because the editor "kept finding things." The substantial revision becomes a full rewrite because once you are restructuring two sections you might as well restructure the rest. The piece ships 6 weeks after planned, having consumed 4x the planned capacity. + +Why it happens. Editors and writers are pattern-matchers; once they start working on a piece, they see all its problems and want to fix all of them. The discipline of staying at the planned depth is not natural to editorial work. + +The cure. Two options. + +1. Stop at scope. When the editor finds work beyond the planned depth, log it but do not do it. The next quarter's audit can decide whether the piece needs deeper work; this refresh ships at the planned depth. +2. Re-scope explicitly. When the editor discovers the planned depth is wrong, halt the refresh and re-scope formally. The capacity allocation gets adjusted; the timing gets adjusted; the team is aware the refresh became a bigger project. + +The failure mode is the third option: keep going at deeper depth without explicit re-scoping. That produces capacity overruns and missed timelines that affect other work. + +--- + +## Multi-depth refresh sequences + +Some pieces benefit from a sequence of refreshes at different depths over time. + +The pattern. + +- Light edit ships first to address factual staleness while broader investigation continues. +- Substantial revision follows in the next quarter once SERP intent shift has been analyzed and the right structural changes are clear. +- Full rewrite follows in 2-3 quarters if the substantial revision did not produce recovery. + +When this pattern fits. High-value-decaying pieces where the right disposition is unclear and the team wants to avoid premature commitment to a full rewrite. Light-edit-first preserves what works while buying time for analysis. + +When this pattern fails. Programs that always start with light edit on high-value-decaying pieces, regardless of signal strength, because light edit is the easiest depth to schedule. The light edit does not move the needle, and the next quarter's audit shows the same piece in the same queue. + +--- + +## Methodology-level choices that stay in the public skill + +The four depth levels with their work, time investment, and use cases. The signal-to-depth matching framework. The depth-creep anti-pattern with its cure. The multi-depth refresh sequence pattern. + +## Implementation choices that stay internal + +Specific time-tracking that captures actual depth per refresh. Specific scope-confirmation tooling that flags depth-creep. Specific writer or editor assignment patterns by depth (some writers are stronger at light edits; some at full rewrites). Specific brief templates per depth in the team's writing system. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md new file mode 100644 index 0000000..9cee5bb --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-execution-patterns.md @@ -0,0 +1,154 @@ +# Refresh execution patterns + +Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. The execution patterns that turn audit queues into shipped refreshes. + +The audit produces a queue. The execution patterns turn the queue into shipped work. Programs that produce strong audits but weak execution end up with documentation of what should have been refreshed rather than refreshed pieces. + +--- + +## Single owner per refresh + +Each refresh has one owner accountable for shipping it. + +The pattern. When a refresh is assigned, one person is named as the owner. The owner runs the work end-to-end: confirming the depth, doing or coordinating the actual editorial work, running the QA gate, shipping, re-promoting, logging the outcome. + +Why single ownership matters. Refreshes that pass through multiple hands without a clear owner often get partially done and then stall. One person believes another is finishing the work; the work sits between them; the audit's next pass shows the piece still in queue. The accountability gap is the failure mode. + +Owner selection. Typically the writer or editor best matched to the topic. For light edits, the owner can be anyone with capacity; for substantial revision and full rewrite, ownership matches expertise. For structural redesign, ownership often sits with a content lead because the work spans multiple pieces. + +Owner-of-owners. A single person owns the refresh program as a whole. Their job is keeping the queue moving, escalating stalled refreshes, ensuring effectiveness measurement is happening, and reporting on the program's health to leadership. Without this role, the program drifts even if individual refreshes have owners. + +--- + +## Editorial-workflow integration + +Refreshes typically run through the same editorial workflow as new pieces, scaled to the chosen depth. + +Light edit workflow. May skip the brief and go straight to edit. The editor pulls the piece, identifies the specific updates, makes them, runs a QA pass, and ships. 30-90 minutes of editorial time; minimal coordination. + +Substantial revision workflow. Brief, draft, edit, QA gate, publish. The brief covers the targeted sections being rewritten; the draft is partial-rewrite; the edit and QA gate match new-piece discipline. 2-4 hours of editorial time; coordination similar to a short blog post. + +Full rewrite workflow. Brief, draft, edit, QA gate, publish. Full new-piece workflow with the additional constraint of preserving the URL and existing internal-link integration. 8-16 hours of editorial time; coordination at long-form-piece scale. + +Structural redesign workflow. Project-scope coordination. Multiple briefs, multiple drafts, redirect plans, internal-link audits. Multi-week timeline; coordination at flagship-project scale. + +The integration discipline. Refreshes are not a separate workflow; they plug into the existing editorial workflow at the appropriate depth. Teams that build a parallel refresh workflow create coordination overhead and quality drift; teams that integrate refresh into the standard workflow benefit from the workflow's existing discipline. + +--- + +## Capacity allocation + +Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff. + +Allocation patterns. + +- Newer libraries (under 100 pieces, under 2 years old): 5-15% of capacity to refresh. Most pieces are still relatively current; signals are limited. +- Mid-stage libraries (100-500 pieces, 2-5 years old): 15-30% of capacity to refresh. Decay rates have built up; high-value-decaying queue is meaningful. +- Mature libraries (500+ pieces, 5+ years old): 25-40% of capacity to refresh. Cumulative decay is significant; without sustained refresh capacity, the library erodes. + +The capacity-vs-new-production tradeoff. + +A team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. Or 8 to refresh, 12 to new. The split affects program shape: heavy-refresh programs preserve existing equity; heavy-new-production programs build new topical authority. + +Right-sizing the allocation. + +- If refresh queues are growing quarter-over-quarter, allocation is too low. +- If new-production output is dropping or the team complains of refresh fatigue, allocation may be too high. +- If high-value-decaying pieces stay in queue across multiple audits, allocation is misallocated (volume of work, not allocation share, may be the issue, but allocation review is the first step). + +The capacity audit. Quarterly, review the actual refresh time spent vs the planned allocation. Programs that consistently exceed their allocation are signaling that the queue's growth rate exceeds the allocation; either grow allocation, narrow the prioritization, or accept slower queue cycle times. + +--- + +## Batching vs integration + +Two patterns for how refresh work fits into the cadence. + +Batching. Dedicated weeks or sprints for refresh work. The team blocks 1-2 weeks per quarter for concentrated refresh execution. + +- Strength. Focus. The team is in refresh mode; context-switching costs are low; throughput on refresh work is high. +- Weakness. Interrupts new production. New-piece workflows pause during refresh sprints; pieces in the new-production pipeline stall. +- Fits. Mid-stage libraries with manageable refresh queues; teams that prefer focused work blocks; programs with predictable seasonality where new production has natural pauses. + +Integration. One refresh per week (or similar steady cadence) integrated into the regular production cadence. + +- Strength. Sustains new production. New-piece work continues without pauses. +- Weakness. Slower refresh velocity per piece; context-switching costs are higher; refresh work can get deprioritized in favor of "more urgent" new-piece work. +- Fits. Mature libraries with continuous refresh queues; teams that prefer sustained pacing; programs where new production has tight commitments. + +Hybrid. A baseline integration cadence plus periodic batching for the high-priority queue. + +- Strength. Sustained refresh on lower-priority work; periodic concentration on high-value-decaying queues. +- Weakness. Coordination overhead; the team manages both modes. +- Fits. Mature programs with sophisticated capacity planning. + +The discipline. Pick a pattern. The failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence and a queue that never clears. + +--- + +## The refresh that needs to happen now + +Some refreshes cannot wait for the next allocation slot. + +Trigger conditions. + +- Sharp decay (40%+ traffic loss in 30 days) on a high-value piece. +- Algorithm-update fallout affecting a high-value piece. +- Factual error producing reputational risk. +- Broken page state (indexing failure, schema regression, redirect loop). + +The fast-track pattern. + +- Continuous monitoring detects the issue. +- The owner-of-owners decides whether the issue warrants fast-track. +- Fast-track refreshes get pulled out of the queue and shipped within days. +- The refresh skips some workflow steps if necessary (briefer brief, faster QA) but does not skip the QA gate; pieces that ship without QA produce regressions that compound. + +Fast-track capacity. Teams need a small reserve for fast-track work. The reserve is typically 5-10% of total capacity. Without reserve, fast-track work pushes other work out and produces cascade delays. + +--- + +## Stalled refresh recovery + +Refreshes that have been in queue for more than two audit cycles need intervention. + +Common causes. + +- Owner is over-committed; the refresh is not the highest priority on their plate. +- The refresh's depth was wrong (planned as light edit, actually needed substantial revision); the owner stalled rather than escalate. +- The refresh's disposition was wrong (planned as refresh, should have been merge); the owner is uncertain how to proceed. + +The recovery pattern. + +- Owner-of-owners reviews stalled refreshes at each audit. +- Reassign owners where capacity is the issue. +- Re-scope where depth was wrong; re-disposition where the disposition was wrong. +- For refreshes stalled because the analysis revealed a deeper issue, escalate to a content lead for decision. + +The stalled-refresh review prevents the queue from accumulating zombie items that everyone knows are not getting done but nobody is removing. + +--- + +## Common execution failures + +No single owner. Refreshes are assigned to "the team"; nobody is accountable; the refresh stalls. + +Workflow shortcuts. The refresh skips the QA gate or the brief. Quality drifts; regressions compound. + +Capacity overcommitment. The team plans 20% capacity for refresh; actual refresh work consumes 35%; new production suffers; team burns out. + +Refresh queue without owner-of-owners. The queue grows; nobody is reporting on its health; the program drifts toward set-and-forget within the formal-program shape. + +Fast-track without reserve. Urgent refreshes push planned work out; cascade delays affect downstream pieces. + +Stalled refreshes accumulating. The queue has zombie items in it; the queue's reported health does not match the queue's actual state. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner discipline, editorial-workflow integration shapes by depth, capacity allocation patterns by library stage, batching vs integration vs hybrid tradeoffs, the refresh-that-needs-to-happen-now pattern, the stalled-refresh recovery pattern. + +## Implementation choices that stay internal + +Specific project-management tooling for the refresh queue. Specific notification systems for refresh assignments. Specific time-tracking for capacity audits. Specific reserves and fast-track triage workflows. The team's own conventions for owner reassignment. These vary by team, tooling, and program shape. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md new file mode 100644 index 0000000..8b4649b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-prioritization-matrix.md @@ -0,0 +1,148 @@ +# Refresh prioritization matrix + +The 2x2 prioritization matrix with quadrant strategies. The discipline of NOT refreshing the high-value-stable quadrant. The under-recognized failure of treating low-value-decaying as automatic refresh candidates. + +Most libraries have more pieces showing signals than the team has capacity to refresh. Without prioritization, refresh work happens on the cheapest pieces or the most visible pieces, leaving high-value-decaying pieces in the backlog while editorial capacity goes to pieces that would not have produced recovery worth the effort. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. + +--- + +## The two axes + +Piece value. A composite of business value, traffic value, and strategic role. + +- Business value. Pieces that drive conversions, qualified leads, or specific business outcomes. Sometimes measurable directly (pieces that close a defined funnel step), sometimes attributed (pieces that influence subsequent conversions). +- Traffic value. Pieces that drive meaningful organic traffic, especially on commercial-intent keywords or topical-authority-building queries. +- Strategic role. Pieces that anchor a hub, that establish the brand's POV on a flagship topic, or that earn external citations and links. Strategic role can outweigh raw traffic; a 500-traffic flagship piece is high-value if it is the canonical statement of the brand's position. + +Pieces are classified as high-value (HV) or low-value (LV). The line between HV and LV is judgment-driven; teams typically settle the criteria by establishing tiers (top 10% by value, next 30%, bottom 60%, or similar). + +Traffic state. A composite of recent and trending traffic. + +- Stable. Traffic over the last 90 days is within 10-15% of the prior 90-day baseline, accounting for seasonality. +- Decaying. Traffic over the last 90 days is down meaningfully (15%+ beyond seasonal baseline), or trending consistently down over multiple quarters. + +Pieces are classified as stable or decaying. The classification is the easier of the two axes because traffic data is cleanly measurable. + +--- + +## Quadrant 1: High-value, decaying + +Top priority. + +The pieces. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. + +The strategy. Refresh first; the traffic loss compounds and the lost equity is hard to recover. These pieces are usually worth substantial-revision or full-rewrite refresh depth because the value at stake justifies the work. + +The disposition decision. Almost always refresh. Merge candidates in this quadrant exist (a high-value piece that is decaying because a sister piece is competing for the same query) but are uncommon. Delete is essentially never the right disposition for a high-value piece. + +Capacity allocation. This quadrant gets the largest share of refresh capacity. Many programs allocate 60-70% of total refresh capacity to high-value-decaying pieces. + +Expected outcomes. Recovery measured at 30 and 90 days. Strong refreshes on this quadrant typically produce 20-50% traffic recovery within 90 days; full rewrites can produce more. + +Common failures. + +- Treating this quadrant as "save for later" because the work is heavy. The traffic loss continues during the delay. +- Light-editing high-value-decaying pieces when substantial revision is warranted. The light edit does not move the needle and the team concludes refresh does not work. +- Not investigating the cause. A piece that is decaying because a competitor published a better resource needs different work than a piece decaying because of SERP intent shift. + +--- + +## Quadrant 2: High-value, stable + +Monitor; do not refresh proactively. + +The pieces. Pieces that are performing strongly and showing no decay signals. + +The strategy. Leave alone. Refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. Pieces that are working should not be touched without clear signal. + +The disposition decision. No action; monitor through continuous monitoring for emerging decay; review at quarterly audits for content drift signals. + +The discipline. This is the quadrant that calendar-refresh programs damage most. A piece ranking position 2 with stable traffic gets refreshed because it is the next piece in the rotation; the refresh introduces minor changes that shift the SERP signals; ranking drops to position 5; traffic drops 30%. The refresh that was meant as maintenance was actually destruction. + +When to revisit. Monitor for emerging signals. If traffic starts decaying or rankings drop, the piece moves to high-value-decaying. If content drift becomes pronounced (the piece is performing but the team sees positioning misalignment), substantial revision may be warranted but only if the team is willing to risk the performance. + +Common failures. + +- Refresh-on-calendar damaging stable pieces. +- Treating stable rankings as a refresh target because the team wants to "improve" the piece. Improvement on stable pieces is a high-risk operation. +- Touching the URL, schema, or core copy of a stable piece without strong rationale. + +--- + +## Quadrant 3: Low-value, decaying + +Audit for merge or delete. + +The pieces. Pieces with low traffic that are decaying further. Pieces that never had strong demand and are now losing what little they had. + +The strategy. The default disposition is NOT refresh. Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. The actual disposition is usually merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling or relevant hub). + +The disposition decision. + +- Merge when a sibling piece on a related topic is performing better and could absorb the failing piece's content. Merging consolidates authority and produces a stronger consolidated piece. The merged URLs redirect to the survivor. +- Delete when no merge candidate exists, the topic is not load-bearing for the program, and the piece's residual value (small as it is) does not justify maintenance. Delete and redirect to the closest sibling piece or hub. +- Refresh is occasionally warranted: when the piece has clear strategic role (anchors a small but important sub-topic) and the decay is recoverable. Rare in this quadrant. + +Capacity allocation. This quadrant gets the smallest share of refresh capacity but a meaningful share of disposition work (merges and deletes are real work, less than full rewrites but more than light edits). + +Common failures. + +- Refreshing pieces in this quadrant by default. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. +- Skipping the merge analysis. Pieces that should have been merged get refreshed in isolation, leaving the authority-splitting problem intact. +- Avoiding deletes because deleting feels destructive. Maintaining a library of low-value pieces forever costs ongoing audit attention and dilutes overall library quality. + +--- + +## Quadrant 4: Low-value, stable + +Leave alone. + +The pieces. Pieces with low traffic that are not actively decaying. They are at the floor. + +The strategy. Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The disposition decision. No action. Pieces that have been low-traffic-stable for multiple audits are candidates for batch consideration: do they collectively represent a topic that is no longer load-bearing for the program? If yes, a structural decision (delete the topic cluster, merge into a hub, archive) may be warranted at program level. If no, leave alone. + +When the strategy fails. If a low-value-stable piece starts decaying further (moves to low-value-decaying), the disposition is reconsidered. Usually merge or delete. + +Common failures. + +- Refresh-on-calendar touching this quadrant. Pure capacity waste. +- Treating low-traffic as a problem to be solved. Low traffic on a low-value piece is the right outcome; not every piece needs to drive significant traffic. Some pieces serve narrow but real strategic roles at low volume. + +--- + +## Capacity allocation by quadrant + +A typical refresh program's capacity might split as: + +- High-value, decaying: 60-70% of refresh capacity. The largest share, on the highest-value work. +- Low-value, decaying: 15-20% of capacity, mostly on merge and delete dispositions, occasional refresh on strategically important pieces. +- High-value, stable: 5-10% of capacity, on the rare cases where content drift warrants substantial revision despite stable performance. +- Low-value, stable: 0-5% of capacity. Mostly batch reviews to identify topic-level decisions. + +The allocation varies by library age and decay rates. Newer libraries with limited decay have less work in the decaying quadrants and may invest more in continuous-monitoring infrastructure. Older libraries with significant decay have more work to do across quadrants. + +--- + +## Common matrix failures + +The "every piece is high-value" trap. Teams that classify too many pieces as high-value lose the prioritization signal. A library where 60% of pieces are "high-value" is essentially unprioritized; the matrix fails to discriminate. + +The traffic-only value classification. Classifying value purely by traffic misses strategic-role pieces that have lower traffic but high importance. A flagship manifesto that earns 800 visits a month but drives external citations and brand recognition is high-value despite lower traffic. + +The "refresh = recovery" assumption. Some pieces in the high-value-decaying quadrant cannot be recovered through refresh. The topic is genuinely declining; competitors are too strong; SERP intent has shifted away from any format the brand can produce. The matrix prioritizes refresh; it does not promise refresh will work. The effectiveness measurement (see `effectiveness-measurement.md`) catches the cases where refresh is not producing recovery. + +Static classification. Value and traffic state both shift over time. A piece in low-value-stable that suddenly draws traffic from an emerging keyword moves to high-value-stable; a piece in high-value-decaying that fully recovers moves to high-value-stable. The matrix is not a one-time classification; it is the framework run at each audit. + +--- + +## Methodology-level choices that stay in the public skill + +The two axes (value, traffic state), the four quadrants with strategies, the capacity allocation guidance, the common matrix failures, the dynamic-classification discipline. + +## Implementation choices that stay internal + +Specific value-classification rubrics the team uses (revenue attribution models, strategic-role tagging, traffic-tier definitions). Specific scripts that classify pieces into quadrants from data pulls. Specific dashboards that visualize the matrix at audit time. The team's own conventions for high-value-stable refresh decisions when content drift is pronounced. These vary by team, business model, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md new file mode 100644 index 0000000..bddf11b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-signals-checklist.md @@ -0,0 +1,164 @@ +# Refresh signals checklist + +Five signal categories that trigger refresh consideration, with detection patterns and the audit shape that surfaces signals across the library. + +Pieces that show no signals do not need refresh. Pieces that show one or two signals warrant attention. Pieces that show three or more signals are typically in active decay and should be high in the prioritization queue. The signal taxonomy below is what distinguishes triaged refresh from calendar refresh. + +--- + +## Signal 1: Traffic decay + +Organic traffic to the piece is trending down over a 90+ day window beyond seasonal baseline. + +Detection patterns. + +- Pull traffic data per URL over rolling 90-day windows. +- Compare current 90 days to prior 90 days, accounting for known seasonality. +- A drop of more than 15-20% beyond seasonality on a piece that previously had stable traffic is a real signal. +- A drop of more than 40% in a 30-day window is a sharp signal warranting urgent review. + +What the signal usually means. + +- Slow decay (5-10% over a year): content drift. The piece is gradually losing relevance as the topic evolves or the brand's voice shifts. +- Moderate decay (15-30% in a quarter): ranking position drift, or SERP intent shifting, or competitor publication. +- Sharp decay (40%+ in a month): algorithm update, indexing issue, dramatic SERP intent shift, or technical regression on the URL. + +Diagnostic next steps. When traffic decay is detected, check ranking positions for the piece's target keywords (signal 2 may also be active), check for technical issues (indexability, page speed, broken redirects), and check the SERP for intent shift (signal 4). + +Anti-patterns in detection. + +- Comparing month-over-month rather than 90-day windows over-attributes seasonal noise to decay. +- Ignoring known seasonality (holiday traffic, B2B dropping in late December) produces false positives. +- Looking only at total traffic instead of organic specifically blurs the signal with referral or paid changes. + +--- + +## Signal 2: Ranking drops + +The piece is losing position on its target keywords. + +Detection patterns. + +- Track each piece's primary 3-10 target keywords with rank tracking. +- Drops from page 1 to page 2-3 are particularly consequential because click-through rates fall sharply at the page-1-to-page-2 boundary. +- Drops within page 1 (position 3 to position 7) reduce clicks but are less existential. +- Persistent drops over 30+ days are real shifts; week-over-week volatility within a few positions is normal. + +What the signal usually means. + +- A piece that was at position 3 and is now at position 8 has been displaced by stronger competing pieces. The displacement is informative; review what is now ranking and what those pieces have that this piece does not. +- A piece that was at position 5 and is now at position 35 has likely been algorithm-affected, indexing-affected, or technically regressed. Investigate before refresh; refreshing a piece with an indexing issue does not solve the indexing issue. +- Drops on long-tail keywords with simultaneous gains on broader head terms can indicate the piece's focus has broadened beneficially. Not always a refresh signal. + +Diagnostic next steps. Pull the SERP for each target keyword. Examine what is ranking. Identify whether the new rankings are stronger pieces (refresh signal: improve the piece) or different SERP intent (signal 4: SERP intent shift, possibly different format needed). + +Anti-patterns in detection. + +- Treating any rank movement as a refresh signal produces refresh-on-noise; require persistence over 30+ days. +- Tracking only branded keywords misses the meaningful organic ranking signal. +- Ignoring keyword cannibalization (multiple pieces competing for same keyword) treats split rankings as a refresh signal when the actual disposition is merge. + +--- + +## Signal 3: Factual staleness + +The piece contains statistics, references, examples, or claims that are dated. + +Detection patterns. + +- Annual review of statistics in the piece. Any stat older than 3 years on a fast-moving topic is a candidate for staleness flagging. +- Reference checks for defunct products, platforms, services, or companies named in the piece. +- Example checks for examples that have aged poorly (a 2019 case study of a company that has since gone bankrupt or changed direction). +- Framing checks for claims that no longer match current reality ("AI is starting to influence search" in 2026 is anachronistic). + +What the signal usually means. + +- Factual staleness alone is often a light-edit signal: update the stats, replace dead links, swap dated examples. The piece's structure may be sound. +- Factual staleness combined with traffic decay or ranking drops is a stronger signal that the piece's broader framing has aged, not just the surface details. +- Factual staleness on a flagship piece is more urgent than on a low-traffic piece because flagship pieces are read by more people who notice the staleness. + +Diagnostic next steps. List the specific stale facts, references, and examples. Estimate the light-edit time required to refresh them. If the structural framing is also stale, the depth required is substantial revision rather than light edit. + +Anti-patterns in detection. + +- Treating every old stat as stale when the stat may still be current (some stats genuinely have not changed in 3 years) produces unnecessary refresh. +- Ignoring framing-level staleness while updating individual stats produces pieces that are technically current in stats but feel old in voice. + +--- + +## Signal 4: SERP intent shift + +The dominant SERP format for the target keyword has changed. + +Detection patterns. + +- Pull the current SERP for each target keyword. What format is dominating? Articles? Listicles? Videos? Product comparisons? AI overviews? +- Compare to the piece's format. If the piece is an article and the SERP wants product comparisons, intent has shifted. +- Watch for new SERP features that did not exist when the piece was written: AI overviews, generative answers, knowledge panels, featured-snippet shifts. + +What the signal usually means. + +- The piece may still rank but increasingly for the wrong reasons. Click-through rates fall as the SERP signals the piece is not the dominant intent match. +- The piece may need format restructuring (full rewrite or substantial revision rather than light edit) to fit the new dominant intent. +- Sometimes the right disposition is to write a NEW piece in the new dominant format and either consolidate the old piece into it or keep the old piece for the residual intent it still serves. + +Diagnostic next steps. Read the top-ranking pieces for the target keyword. What format are they? What questions do they answer that the piece does not? Decide whether refresh in the new format will recover the position, or whether a new piece in the new format is the better disposition. + +Anti-patterns in detection. + +- Ignoring AI-overview presence on the SERP. AI overviews change click-through rates substantially and may indicate the piece needs restructuring for AI search citation. +- Assuming SERP intent is stable. Some keywords have stable intent for years; others shift quarterly. The audit should be active. + +--- + +## Signal 5: Content drift + +The piece's positioning no longer matches the brand's current positioning. + +Detection patterns. + +- The piece's voice reads as the brand-of-three-years-ago. Vocabulary, tone, level of conviction. +- The piece's POV on the topic has not kept up with how the brand now thinks. The brand has sharpened a position the piece treats with old hedging. +- The piece's framing fits the audience the brand had then, not the audience the brand has now. +- The piece's calls-to-action, internal linking, and product references reflect older brand offerings that have since changed. + +What the signal usually means. + +- Content drift is internal signal. Readers may not consciously notice, but the team will, and over time the library's voice incoherence weakens the brand. +- Content drift is often paired with the team's discomfort about which pieces in the library represent the brand best when sharing externally. +- Content drift is rarely the sole driver of a refresh decision (because traffic and rankings may be fine), but it determines depth: a content-drift refresh is usually substantial revision or full rewrite, not light edit. + +Diagnostic next steps. Identify which sections drift hardest from current positioning. If drift is concentrated in introduction, closing, and CTAs, substantial revision can address it. If drift is throughout, full rewrite is the cleaner disposition. + +Anti-patterns in detection. + +- Treating every voice evolution as drift triggers calendar refresh of pieces that are still serving readers. +- Ignoring drift because the piece is performing in search produces a library that performs but no longer represents the brand. + +--- + +## The library audit + +Running the signal taxonomy across the whole library. + +Audit shape. + +- Pull a per-URL data set: traffic over time, rankings, last-modified date, target keywords, business-value tag (high/medium/low). +- For each URL, run the five signal checks. Mark each signal as present or absent. +- Pieces with zero signals: stable; no action. +- Pieces with one or two signals: candidate queue; review individually for disposition. +- Pieces with three or more signals: active-decay queue; high priority for disposition decision. + +Output. A spreadsheet or database of pieces with their signals and the resulting disposition (refresh, merge, delete, monitor). The output feeds the prioritization matrix and the refresh queue. + +Cadence. Full audit quarterly. Continuous monitoring for traffic-decay and ranking-drop signals; manual signal checks (factual staleness, SERP intent shift, content drift) at quarterly cadence. + +--- + +## Methodology-level choices that stay in the public skill + +The five signal categories with detection patterns and what each signal means; the audit shape across the library; the cadence; the anti-patterns in detection. The signal-to-disposition mapping that informs prioritization. + +## Implementation choices that stay internal + +Specific data pulls from the team's analytics platform. Specific rank-tracking thresholds. Specific automation that runs continuous monitoring. Specific reviewer dashboards that surface signals. Specific seasonality models the team uses to baseline traffic. The team's own tags for business-value classification. These vary by team, tooling, and analytics setup. diff --git a/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md b/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md new file mode 100644 index 0000000..e1b242b --- /dev/null +++ b/dist/pi/.agents/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md @@ -0,0 +1,137 @@ +# Refresh vs merge vs delete + +The disposition decision. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged or deleted. + +Most refresh programs default to refresh as the disposition. The default is wrong. Some pieces should be merged into stronger siblings; some should be deleted and redirected. The disposition decision is upstream of the depth decision: a piece getting deleted does not need depth, and a piece being merged is doing a different kind of work than refresh. + +--- + +## Refresh + +The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +Criteria for refresh disposition. + +- The piece has demonstrated demand: it draws meaningful traffic now or did historically. +- The topic is one the brand wants to own; the piece's existence is strategically warranted. +- A path to recovery exists: refresh of the right depth has a reasonable chance of producing improvement. +- No sister piece is competing for the same query in a way that splits authority. +- The piece's URL has accumulated authority worth preserving. + +When refresh fits but might not. + +- Sometimes a refresh-eligible piece is also a merge candidate. A high-value-decaying piece that is decaying because a sister piece is stronger may produce more value through merge than through refresh of either piece alone. +- Sometimes refresh has been tried and did not produce recovery. The first failed refresh shifts disposition consideration toward merge or full-rewrite-with-new-positioning rather than another refresh attempt. + +Refresh failure modes. + +- Refreshing pieces that are not recoverable. The topic is dying; the brand cannot win against the competition; the SERP intent has shifted to a format the brand does not produce. Refresh in these cases is theater. +- Refreshing without resolving the underlying issue. If a piece is decaying because a sister piece is competing for the same query, refresh of the original piece does not solve the cannibalization. Both pieces continue to underperform. + +--- + +## Merge + +Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +Criteria for merge disposition. + +- Two or more pieces target the same primary query or a closely overlapping query cluster. +- Combined authority across the pieces is meaningful; merging would produce a piece with stronger authority than any individual piece has. +- The pieces' coverage overlaps enough that consolidation produces a coherent piece, not a Frankenstein of mismatched sections. +- The team can identify which URL the survivor occupies (typically the one with strongest existing authority) and which URLs redirect to the survivor. + +The merge decision in detail. + +- Identify the survivor URL. Usually the URL with strongest existing rankings, traffic, and backlinks. The survivor inherits the consolidated content; other URLs redirect to it. +- Plan the consolidated content. Outline the merged piece. Decide which sections come from which source piece. Plan the gaps where new content will fill what neither piece had. +- Author the consolidated piece. Write or rewrite as needed. The consolidated piece is usually stronger than any of the source pieces because it is built from the strongest components plus targeted new content. +- Implement redirects. 301 redirects from the merged URLs to the survivor. Redirects need to be implemented at publish time, not after; the merged URLs going to 404 or 410 produces traffic loss that did not need to happen. +- Update internal links. Pieces that linked to the merged URLs should be updated to link to the survivor. + +Merge failure modes. + +- Merging without redirects. The merged URLs go to 404; the consolidated authority does not transfer; traffic is lost. +- Merging pieces that did not actually compete. If two pieces target different intents, merging them produces a piece that does neither well. +- Frankenstein merges. The consolidated piece reads as multiple pieces stitched together rather than as a unified piece. Cure: rewrite the consolidated piece as a piece in its own right, using the source pieces as input rather than as components. + +--- + +## Delete + +The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. + +Criteria for delete disposition. + +- The piece draws minimal traffic and has minimal residual authority. +- The topic is not load-bearing for the program; the brand does not need to own it. +- No merge candidate exists; the piece's content does not consolidate cleanly into any stronger piece. +- Maintaining the piece costs ongoing audit attention without proportional return. + +The delete decision in detail. + +- Identify the redirect target. The deleted URL should redirect to the closest sibling piece, or to the relevant hub or category page, or to the homepage if no other target fits. Deleting without redirect (returning 404 or 410) is correct only when the piece's residual authority is genuinely zero, which is rare. +- Implement the redirect. 301 redirect to the chosen target. +- Update internal links. Pieces that linked to the deleted URL should be updated to link to the redirect target directly. The redirect chain still works but direct links are cleaner. +- Document the deletion. The audit log should capture the delete decision, the rationale, and the redirect target. Future audits can reference the log if a question arises about the URL. + +Delete failure modes. + +- Avoiding delete because deleting feels destructive. The library accumulates low-value pieces forever, costing ongoing audit attention and diluting overall library quality. +- Delete without redirect. The URL returns 404; whatever residual authority existed is lost; users who linked to the URL or bookmarked it find a dead link. +- Delete of pieces that should have been merged. The piece's content had value the team did not recognize; merging would have preserved it. Delete is appropriate when no merge candidate exists, not as the easy path to avoid the merge analysis. + +--- + +## The disposition decision flow + +A short framework for choosing. + +1. Does the piece have demonstrated demand? Traffic, rankings, conversions, or strategic role. If yes, continue. If no, the disposition is likely delete (or merge if there is a candidate). +2. Is there a sibling piece competing for the same query? If yes, evaluate merge. The merged piece has a strong chance of outperforming both original pieces. +3. Is the topic load-bearing for the brand? If no, refresh disposition is unlikely to be the right answer; consider merge into a stronger sibling or delete. +4. Has refresh been tried recently without recovery? If yes, the next disposition should be merge or full-rewrite-with-new-positioning, not another refresh attempt. +5. What is the cheapest disposition that addresses the actual problem? Refresh is often defaulted to because it feels less destructive; merge and delete are sometimes the cheaper paths to the actual outcome. + +--- + +## The under-recognized failure: refreshing what should have been merged or deleted + +The pattern that costs refresh programs the most capacity. + +How it shows up. The team spends 4 hours refreshing a low-value-decaying piece that even at its best will not draw meaningful traffic. The refresh ships. The piece ranks slightly better for two weeks, then drifts back down. Three months later the piece is in the same audit queue. + +Why it happens. + +- Refresh feels less destructive than merge or delete. +- The merge analysis takes time; refresh feels like the immediate action. +- Delete requires team agreement; refresh can be done by a single owner. +- The team has not internalized that some pieces should not be refreshed. + +The cure. Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. The audit is not "which pieces to refresh"; it is "what disposition each piece should get." Refresh becomes one option among several rather than the default. + +The capacity recovery. Programs that adopt the merge-and-delete-as-first-class-dispositions discipline typically recover 20-40% of refresh capacity for higher-value work. The pieces that were getting refreshed but should have been merged or deleted stop consuming capacity; the freed capacity goes to high-value-decaying pieces that produce real recovery. + +--- + +## Disposition decisions that need approval + +Some dispositions are higher-risk than others and warrant approval beyond the audit owner. + +Delete dispositions. Always need approval. Deletes are essentially irreversible without significant work to undelete; the redirect strategy is consequential; the team should be aligned on the decision. + +Merge dispositions involving high-value pieces. Need approval. Merging into a survivor URL means the non-survivor URLs lose their identity. If the non-survivor pieces had high-value characteristics, the merge needs review. + +Refresh dispositions on stable high-value pieces. Need approval. Touching a stable high-value piece is a high-risk operation; the audit owner should not unilaterally decide to refresh. + +Light edit and substantial revision on decaying pieces. Usually do not need approval beyond the audit owner. The risk-reward is straightforward. + +--- + +## Methodology-level choices that stay in the public skill + +The three dispositions and their criteria, the disposition decision flow, the under-recognized failure of refreshing what should have been merged or deleted, the merge and delete mechanics, the dispositions that need approval. + +## Implementation choices that stay internal + +Specific redirect implementation in the team's CMS or hosting layer. Specific internal-link update automation that catches links to merged or deleted URLs. Specific approval workflows for high-risk dispositions. Specific audit-log templates that capture disposition rationale. These vary by team, tooling, and CMS. diff --git a/dist/pi/.agents/skills/content-repurposing/SKILL.md b/dist/pi/.agents/skills/content-repurposing/SKILL.md new file mode 100644 index 0000000..be7ced8 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/SKILL.md @@ -0,0 +1,298 @@ +--- +name: content-repurposing +description: "Cross-format content adaptation. Turning one substantial piece into many derivative formats (blog series, email sequences, social posts, webinars, podcasts, video shorts) without losing the original's value or producing AI-slop variants. The discipline of adaptation per medium rather than mass-blast distribution. Triggers on content repurposing, content adaptation, cross-format content, content atomization, content multiplication, content distribution across formats, source-piece-to-derivative, video shorts from blog, email from whitepaper, podcast from article, blog series from research. Also triggers when a flagship piece is shipping but the team has not planned how to extend it across formats, when repurposing is happening but the derivatives feel mass-produced, or when AI-assisted repurposing is producing slop variants of strong source pieces." +category: content +catalog_summary: "Cross-format content adaptation: one piece becomes many (blog series, email, social, webinar, podcast, video) with per-format adaptation rather than mass-blast that ignores medium constraints" +display_order: 11 +--- + +# Content Repurposing + +A senior editorial leader's playbook for cross-format content adaptation. The discipline of turning one substantial piece into many derivative formats without losing the original's value or producing slop variants. + +Most content programs underspend on repurposing. A flagship piece costs 40-80 hours to produce; the program publishes it once, shares it on three channels, and moves on. The same piece could have produced a blog series, an email sequence, a webinar, a podcast episode, a dozen social posts, video shorts, and FAQ extractions for AI search visibility. The work to extend the source piece across formats is small relative to the value extracted; programs that skip repurposing leave most of the value unrealized. + +The failure mode in the other direction is mass-blast: the same content reposted across channels without adaptation. A blog post pasted into LinkedIn as a long-text post; the email newsletter is the blog's first three paragraphs with "read more" tacked on; the YouTube video is a slideshow of the article text read aloud. Mass-blast respects neither the medium nor the audience. AI-assisted repurposing has made mass-blast cheap; the result is a wave of derivative content that performs poorly across every channel because it was adapted to none of them. + +This skill is the discipline of adaptation per medium. Each format has constraints, conventions, and reader expectations the source piece does not have. Repurposing that respects those constraints produces work that earns engagement on the new format; repurposing that ignores them produces filler. + +When to use this skill: planning the extension of a flagship piece across formats, auditing a repurposing pipeline that is producing low-engagement derivatives, calibrating an AI-assisted repurposing workflow that is producing slop, or designing the cross-format adaptation conventions for a content program. + +--- + +## What this skill is for + +This skill spans cross-format adaptation work after a source piece has been produced. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes the original piece in any single format. +- `content-repurposing` (this skill) turns one piece INTO many formats. +- `content-distribution` gets content TO audiences via channels. +- `editorial-qa` verifies pre-publish, including derivatives. +- `ai-content-collaboration` is the workflow layer; AI participation rules apply within repurposing. + +The distinction from `content-distribution` is load-bearing. Distribution is channel work: getting content to audiences via the right channels. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running multi-format programs, agencies producing derivative content for clients, anyone planning to extend a flagship piece across formats. + +What is not in scope: the original piece's production (covered by `content-and-copy` and the long-form skills), the channels themselves (covered by `content-distribution`), the editorial QA on derivatives (covered by `editorial-qa`). + +--- + +## One-and-done vs mass-blast vs adapt-by-format + +The keystone framing. + +One-and-done. Publish once on the source format; never reuse. The piece took 60 hours to produce; it generates traffic for 90 days; it gets shared three times; it goes silent. The team treats publication as the end of the piece's life. Output: most of the source piece's value goes unrealized; the team is always producing new flagship work because old flagship work is not being extended. + +Mass-blast. Same content reposted across channels without adaptation. Blog post text pasted into LinkedIn as a long post. Email newsletter is the blog's first three paragraphs. The YouTube version is a slideshow of the text read by AI voice. Output: low engagement on every channel because nothing was adapted to any channel's conventions. Audiences perceive the cross-channel sameness as low-effort filler. AI-assisted repurposing has made this pattern cheap and common. + +Adapt-by-format. Per-medium adaptation that respects each format's constraints and conventions. The blog series breaks the source piece into chapters with new ledes and closings per chapter. The email sequence builds on the source's framework with sender-voice adjustments. Social posts use platform-native conventions. The webinar adds Q&A and live elements. Output: each derivative earns engagement on its medium because it was made for that medium; the source piece's value compounds across formats. + +The litmus test. Read each derivative as if you had not seen the source piece. Does it stand on its own? Does it use the medium's conventions? Would it earn engagement if it were the only thing the audience saw of this work? If yes to all three, the adaptation succeeded. If the derivative reads as "I should have read the original instead," the adaptation failed. + +--- + +## Source-piece selection + +Not every piece is worth repurposing. Selection is the first discipline. + +Strong source-piece characteristics. + +- The source has a clear central argument or framework that travels across formats. +- The source has standalone sections, examples, or sub-arguments that work as derivative pieces. +- The source's audience overlaps with the audiences on the target formats. +- The source's voice is distinctive enough that derivative voice can stay coherent. +- The source has accumulated demand: traffic, links, mentions, social shares. + +Weak source-piece characteristics. + +- The source is a tightly-integrated argument where every section depends on context. +- The source is a list-style piece where the items do not have standalone weight. +- The source's value depended on being read end-to-end (a narrative arc, a layered argument with payoff). +- The source's audience does not exist on most target formats. +- The source's voice is generic; derivative voice has nothing to anchor. + +The selection audit. Run candidate pieces through these questions before committing to repurposing. Pieces that fail the audit may still be valuable but as one-and-done; programs that try to repurpose unsuitable pieces produce derivatives that feel forced. + +Detail in [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md). + +--- + +## Format adaptation patterns + +Eight common source-to-derivative adaptations with worked examples. + +Long-form to blog series. A 6,000-word whitepaper becomes 4-6 standalone blog posts, each developing one of the whitepaper's sub-arguments with new ledes and closings. + +Blog post to email sequence. A 1,500-word blog post on a multi-step framework becomes a 5-email sequence, one email per step, with sender-voice adaptation and per-email engagement hooks. + +Whitepaper to webinar. Substantive whitepaper becomes a 30-45 minute webinar with the whitepaper's framework as the spine, plus live Q&A, plus interactive elements that print do not support. + +Long-form to social posts. Pull-quote-style posts, framework summaries, key-question posts, contrarian-claim posts. Each social post is one moment from the source, framed for the platform's conventions. + +Article to podcast episode. Article becomes the episode's spine; the host adds context, examples, and conversational elaboration; sometimes a guest interview drives the episode while the article is the show notes. + +Long-form to video shorts. 60-90 second video clips on individual claims, examples, or framework elements from the source. Each short is a standalone unit; series-of-shorts can extend the source over weeks of social posting. + +Research report to FAQ extractions. Specific Q&A extractions from the source piece, formatted for AI search citation and snippet capture. + +Multi-piece source to ebook. Several related pieces (blog posts, articles, even social threads) consolidated into an ebook, with new connective tissue, an introduction that frames the body, and a conclusion that synthesizes. + +Detail in [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md). + +--- + +## Per-format constraints + +Each medium demands and forbids specific things. Repurposing that ignores the constraints produces derivatives that fail the medium. + +Email. + +- Subject line and preheader bear most of the engagement load. +- Plain prose paragraphs work; complex formatting often breaks across email clients. +- Length tolerance varies by audience; 200-800 words common. +- Single clear CTA per email; multiple competing CTAs underperform. + +Social posts (text-driven platforms). + +- Hook in the first 1-2 lines; readers decide to expand or scroll. +- Platform-specific conventions (LinkedIn long-post structure differs from X/Twitter thread structure). +- Visual or quote-graphic options to break up text. +- One specific point per post; multi-point posts dilute. + +Video (long-form). + +- Pacing differs from print; spoken delivery requires different sentence structure. +- Visuals carry information print does not need; talking-head video alone for 30+ minutes underperforms. +- Audio quality matters more than video quality up to a point; bad audio kills retention. + +Video (short-form). + +- 60-90 second window for most platforms; 15-30 seconds for some. +- Captions essential; many viewers watch without sound. +- Hook in the first 1-2 seconds; algorithmic recommendation rewards retention from second 1. +- One specific point or moment per short. + +Podcast. + +- Spoken-language sentence structure; print-style sentences read aloud sound stilted. +- Conversational pacing rewards examples and asides; tightly-argued print sections feel stiff. +- Show notes do the print work the audio cannot; treat show notes as a derivative format too. + +Webinar. + +- Live element: Q&A, polls, interactive moments. Static webinar is a video; interactive webinar earns the format. +- Slide design matters; text-heavy slides fail. +- Length: 30-60 minutes typical; longer requires high engagement design. + +Detail in [`references/per-format-constraints.md`](references/per-format-constraints.md). + +--- + +## Voice consistency across formats + +The source piece's voice anchors the derivatives. The discipline is staying recognizable through the format shifts. + +What stays constant. + +- The brand's POV on the topic. +- Distinctive vocabulary, specific framings, recognizable phrasings. +- The level of conviction or hedging the brand uses. +- The audience-respect register (talking up to, down to, alongside the audience). + +What adapts per format. + +- Sentence length and structure (spoken voice differs from written). +- Density (visual formats can carry less per minute than text). +- Conversational vs declarative register (podcasts are conversational; whitepapers declarative). +- Direct-address frequency ("you" usage varies by format). + +The voice audit per derivative. Read or watch the derivative. Does it sound like the brand? Could a reader who knows the source piece tell the derivative is from the same source? If voice has drifted to AI-default or to the platform's default register, the adaptation lost the voice. + +The AI-repurposing voice problem. AI-assisted repurposing is particularly prone to voice drift. The source piece may have specific voice characteristics; AI generation of derivatives without strong voice prompts produces derivatives that sound more generic than the source. See `ai-content-collaboration` for the voice-preservation discipline that applies to repurposing workflows. + +Detail in [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md). + +--- + +## Sequencing and cadence + +When to release derivatives relative to the source, and at what pace. + +Sequencing patterns. + +- Source-first, derivatives following. Source publishes; derivatives roll out over the following 2-12 weeks. The source carries authority; derivatives extend reach. +- Derivatives-first, source as anchor. Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship. Less common; works for built-up audiences who follow the program. +- Simultaneous launch. Source and a wave of derivatives publish on the same day. Maximum splash; risks audience fatigue if every channel is firing the same day. + +Cadence within the rollout. + +- Concentrated. Most derivatives ship within 4-6 weeks of source. Maximum momentum from the source's authority; minimum time for individual derivatives to land. +- Distributed. Derivatives ship over 3-6 months. Each derivative has space to land; the program is extracting value over a longer window; risks losing connection to source if the gap grows too long. +- Indefinite. Derivatives keep being created from the source as long as the source remains relevant. Common for evergreen flagship pieces; rare otherwise. + +The pacing audit. Match cadence to the source's traffic curve. Pieces with sharp early traffic (trending topics) benefit from concentrated rollout; pieces with sustained evergreen traffic can support distributed rollout over many months. + +Detail in [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md). + +--- + +## Cross-promotion across derivatives + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. + +Linking patterns. + +- Derivative back to source. Each derivative includes a link or reference to the source piece for readers who want depth. The source's traffic compounds. +- Source forward to derivatives. The source piece is updated to include links to derivatives as they ship. The source becomes the hub for the cross-format extension. +- Derivatives across. Where appropriate, derivatives link to other derivatives in the cross-format set. The series feeling helps audiences engage with multiple pieces. + +Attribution within derivatives. When a derivative is clearly drawn from a source piece, acknowledge: "This is adapted from our recent piece on X." Attribution earns reader trust; uncredited derivatives can feel like the same work being recycled without acknowledgment. + +Co-promotion across channels. A blog post derivative can be re-shared on social where the original blog post was; a social post derivative can be promoted in the email newsletter. Cross-channel flow extends each derivative's reach. + +Detail in [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md). + +--- + +## Repurposing for AI search visibility + +A specific repurposing pattern worth its own treatment. + +FAQ extraction. Pull specific question-answer pairs from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries that can be cited by AI search engines. + +Snippet design. Identify standalone paragraphs in the source that answer specific queries cleanly. These paragraphs can be quoted, schema-marked, and presented in derivative pieces or in dedicated FAQ pages. + +Statistic extractions. AI engines weight statistics with named sources. Extract specific stats from the source (with citations to the underlying primary research) into format that AI can cite cleanly. + +Definition and entity extractions. Source pieces often define specific terms or describe specific entities authoritatively. Extract these as standalone definitions in glossaries, FAQ pages, or knowledge-base entries. + +The AI-search-derivative discipline. Treat AI-search optimization as a derivative format with its own conventions: specific question framings, named-source citations, standalone-paragraph design. Pieces that do this well earn AI citations; pieces that do not still get cited but at lower rates and with less control over framing. + +Detail in [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md). + +- "Our derivatives feel like AI slop." Mass-blast pattern; AI-assisted repurposing without per-format adaptation. Cure: add adaptation discipline, voice prompts, per-format review. +- "We repurposed but engagement is low." Format constraints ignored. Cure: audit each derivative against per-format conventions. +- "The blog post derivative outperforms the source." Either the source was the wrong format for the topic (the derivative format fits better), or the derivative cannibalizes the source. Investigate. +- "We never reuse pieces." One-and-done pattern; the program is leaving 70-90% of source-piece value unrealized. +- "Our LinkedIn posts are blog-post text dumps." Mass-blast on a platform with specific conventions. Cure: rewrite for platform-native structure. +- "The email newsletter is the blog's first paragraphs with 'read more' tacked on." Mass-blast email pattern. Cure: rewrite as a standalone email with engagement hooks. +- "Our podcast episodes are articles read aloud." Print-to-audio without spoken-language adaptation. Cure: rewrite for spoken delivery; add conversational pacing. +- "We extracted FAQ pages but they are not getting cited by AI search." Format may be wrong (snippets not standalone) or content may not be authoritative enough; audit against AI-search norms. +- "Our voice drifts across derivatives." AI-repurposing voice failure. Cure: stronger voice prompts; per-derivative voice audit. +- "We launched 12 derivatives in a week and audiences were exhausted." Concentrated cadence too aggressive. Cure: distributed cadence with engagement-driven sequencing. +- "Our derivatives compete with the source for the same query." Cannibalization. Cure: clear primary-keyword assignment per piece; consolidate or restructure. + +--- + +## The framework: 12 considerations for content repurposing + +When designing or auditing a repurposing program, walk these 12 considerations. + +1. Adapt-by-format, not mass-blast or one-and-done. Each derivative respects its medium. +2. Source-piece selection. Strong sources have travelable arguments and standalone sections. +3. Format adaptation patterns chosen. Match source-piece characteristics to derivative formats. +4. Per-format constraints respected. Each medium's conventions, length norms, and reader expectations. +5. Voice consistency across formats. Brand POV stays; sentence structure adapts. +6. Sequencing and cadence planned. Source-first vs simultaneous; concentrated vs distributed. +7. Cross-promotion across derivatives. Linking, attribution, co-promotion. +8. AI-search extraction. FAQ, snippet, statistic, entity extractions designed deliberately. +9. Cannibalization avoided. Derivatives complement the source; do not compete for the same query. +10. Engagement-per-format measured. Derivatives evaluated on each medium's metrics. +11. AI-assisted repurposing with voice discipline. Voice prompts, per-derivative review, slop prevention. +12. Capacity allocation explicit. Repurposing is real work; budgeted, not done in the cracks. + +The output of the framework is a repurposing program that turns each strong source piece into a coherent multi-format extension, with each derivative earning engagement on its medium. + +--- + +## Reference files + +- [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md) - Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. +- [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md) - Eight source-to-derivative adaptations with worked examples. Long-form to blog series, blog to email, whitepaper to webinar, etc. +- [`references/per-format-constraints.md`](references/per-format-constraints.md) - What each medium demands and forbids. Email, social, video, podcast, webinar, AI search. Length norms, conventions, hooks. +- [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md) - What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem. +- [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md) - Source-first vs simultaneous vs derivative-first. Concentrated vs distributed cadence. Pacing audits. +- [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md) - Linking patterns, attribution, co-promotion across channels. +- [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md) - FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. +- [`references/repurposing-pipeline-templates.md`](references/repurposing-pipeline-templates.md) - Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. +- [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: adaptation is craft, not duplication + +Repurposing is widely treated as a content multiplication problem to be solved with AI: feed the source into a tool, get derivatives out. The output of that approach is mass-blast, slop, and audiences that learn to ignore the program. The teams producing repurposing that earns engagement are the ones treating each derivative as a piece in its own right, adapted for its medium, written with the source's voice but the format's craft. + +Adaptation is craft, not duplication. The source piece is the starting material; the derivative is its own work. Programs that hold this discipline get value compounding across formats; programs that skip it produce a wall of derivative content that performs worse, not better, than publishing only the source. + +When in doubt about whether a repurposing program is ready, ask: does each derivative respect its medium's conventions, does voice stay consistent across the set, are derivatives cross-promoting and linking back to the source, is AI-search extraction part of the plan, is cannibalization being managed, is the cadence pacing earning engagement? If yes to all of those, the program is real. If no to any, the gap is where the derivatives will read as filler and audiences will tune out. diff --git a/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md new file mode 100644 index 0000000..3ec2330 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/aeo-extraction-patterns.md @@ -0,0 +1,205 @@ +# AEO extraction patterns + +FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. The repurposing pattern that turns long-form content into AI-search-ready derivatives. + +AI search engines (the citation-driven generative answer engines) cite content in specific shapes. Pieces that are designed for citation get cited at higher rates and with better framing control; pieces that are not designed for citation still get cited but at lower rates and with less control over how the citation appears. + +The AEO (answer engine optimization) extraction is its own derivative format with its own conventions. Treating it as a derivative is the discipline. + +--- + +## The AEO extraction frame + +AI engines retrieve and cite content paragraph-by-paragraph or snippet-by-snippet. They favor content that: + +- Has standalone meaning (the snippet works without surrounding context). +- Cites named sources within the snippet (specific authority). +- Uses specific phrasings (queryable framings). +- Has structural signals (FAQ schema, headings, lists where appropriate). + +Source pieces written without these properties may have the same content but in shapes the engines do not cite cleanly. AEO extraction restructures the content into citation-ready shape. + +--- + +## Pattern 1: FAQ extraction + +The most common AEO extraction pattern. + +The shape. Specific question-answer pairs derived from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries. + +Question framing. + +- Use phrasings users actually search. "What is X?" "How does X work?" "Why does X matter?" "When should I use X?" +- Avoid phrasings users do not search. "What are the considerations around X?" rarely matches search intent. +- Specific is better than generic. "How long should a B2B sales email be?" performs better than "What length should sales emails be?" + +Answer framing. + +- Standalone meaning. The answer works as a paragraph; no pronoun references that depend on outside context. +- Named source within the answer where applicable. "According to a 2025 Forrester study, B2B sales emails between 75 and 150 words have the highest reply rates" performs better than "Studies show shorter emails work better." +- Specific framings, not hedged. "The strongest length is 75-150 words" performs better than "Generally, shorter tends to be better." +- Length: 40-80 words typical. Longer answers get truncated or cited partially; shorter answers may not have enough substance to cite. + +Where the FAQ lives. + +- A dedicated FAQ section at the bottom of the source piece, schema-marked with FAQPage. +- A standalone FAQ page that aggregates multiple FAQs across topics, deeply linked to source pieces. +- Inline within the source piece as a callout box, surfacing the Q&A while the surrounding prose develops the topic. + +--- + +## Pattern 2: Snippet design + +Standalone paragraphs in the source piece designed to be citation-ready. + +The shape. A paragraph (100-200 words typical) that answers a specific query cleanly and can be cited as a unit. + +Snippet framing. + +- Opens with a specific claim or definition. Snippets that open with throat-clearing rarely get cited cleanly. +- Includes named source citations where the claims need authority. +- Uses specific framings. "B2B sales emails between 75 and 150 words have a 32% reply rate, compared to 18% for emails over 250 words" is citation-ready; "shorter emails tend to do better" is not. +- Stands alone. The paragraph's meaning does not depend on the prior or following paragraphs. + +Where snippets live. + +- Throughout the source piece as load-bearing paragraphs that incidentally meet snippet criteria. +- As deliberately-designed snippets in specific positions (often after each H2 question for AEO-optimized pieces; see `editorial-qa`'s SEO/AEO compliance for the answer-paragraph discipline). +- As standalone snippets in derivative pieces (FAQ pages, glossaries, knowledge-base entries). + +--- + +## Pattern 3: Statistic extractions + +AI engines weight statistics with named sources at high citation rates. + +The shape. Specific statistic with named source, framed for citation. + +Statistic framing. + +- The number is specific. "32% of B2B buyers" performs better than "around a third of buyers." +- The source is named. "According to the 2025 Salesforce State of Marketing report" performs better than "according to a recent study." +- The context is clear. "Among B2B SaaS buyers in the $50M-500M revenue band" rather than just "among buyers." +- The currency is specified. The stat's date matters for AI engines deciding which sources to cite as current. + +Where statistic extractions live. + +- Throughout the source piece where data supports claims. +- In dedicated "key statistics" callouts that schema-mark the stats. +- As standalone tweet-graphic-style social derivatives (the stat on its own with the source citation). +- In FAQ-style answers that frame "what does the data say about X?" + +The citation-laundering avoidance. Statistic extractions that cite secondary sources (other content marketing pieces) rather than primary sources reduce citation rates. AI engines increasingly detect citation laundering and discount it. + +--- + +## Pattern 4: Definition and entity extractions + +Source pieces often define specific terms or describe specific entities authoritatively. + +The shape. Standalone definitions or entity descriptions that can serve as canonical references. + +Definition framing. + +- "X is [definition], typically [characterization], distinguished from [related concept] by [distinction]." +- 50-150 words for substantive definitions. +- Specific authority signals: who developed the concept, when, in what context. + +Entity framing. + +- For products, companies, frameworks: who, what, when, why, where used. +- Specific dates, named people, named organizations. +- Source attribution where the entity claim depends on authority. + +Where definition and entity extractions live. + +- Glossary pages. Many programs underuse glossaries; they are AI-search valuable real estate. +- Knowledge-base entries. +- Schema-marked definitions within source pieces (Article schema with appropriate sub-types). +- Wikipedia and similar entity authorities where the entity is significant enough to warrant external listings (different from on-property AEO but related; AI engines weight cross-source consistency). + +--- + +## Pattern 5: Comparison extractions + +Source pieces that compare options, frameworks, or approaches produce comparison-extraction derivatives. + +The shape. Side-by-side or table comparisons with specific axes, citation-ready. + +Comparison framing. + +- Defined axes (price, feature set, fit, scale). +- Specific values per axis per option. +- Tradeoff summary that AI can quote. +- Recommendation framing where the source piece commits a position. + +Where comparison extractions live. + +- Tables within the source piece, schema-marked where appropriate. +- Standalone comparison pages. +- FAQ-style answers framing "How does X compare to Y?" +- Decision-guide derivatives that walk readers through the comparison. + +--- + +## Pattern 6: How-to extractions + +Source pieces with sequential instructions produce how-to extractions. + +The shape. Step-by-step instructions that AI can cite as a procedure. + +How-to framing. + +- Numbered steps in a clear sequence. +- Each step is a complete instruction (not "do this, then that" run together). +- Schema-marked with HowTo where the source is an instructional piece. + +Where how-to extractions live. + +- Within source pieces as schema-marked procedures. +- Standalone how-to pages on specific tasks. +- Tutorial derivatives in video format. + +--- + +## AEO extraction failures + +Generic FAQs. Questions that do not match user search phrasings get little citation. Cure: query research; phrase questions in user voice. + +Context-dependent answers. Answers that reference "this approach" or "the method described above" do not cite cleanly. Cure: each answer is rewritten to stand alone with full context. + +Hedged answers. "Generally, in some cases, depending on context, X might work" rarely gets cited. AI engines prefer specific framings. Cure: where the source piece is genuinely uncertain, scope the answer to the specific case where the answer is specific. + +Missing schema. FAQs and snippets without schema markup do not signal cleanly to engines. Cure: add appropriate schema (FAQPage, HowTo, Article) where formats fit. + +No source citations within answers. Statistics and specific claims without named sources within the answer paragraph get cited at lower rates. Cure: include source citations within the answer body, not just in surrounding context. + +Citation laundering. FAQs citing other content marketing pieces rather than primary sources. Cure: trace claims to primary sources; cite the primary. + +Over-extraction. Producing 50 FAQs from a 5,000-word source piece dilutes; not every question deserves a standalone FAQ. Cure: extract the 10-15 highest-value questions; let the rest live within the source's prose. + +--- + +## AEO extraction integration with the cross-format set + +AEO extractions integrate with other derivatives. + +FAQ pages link to the source. The FAQ page is a derivative; the source piece is the canonical version. Cross-promotion follows the standard pattern. + +Statistic extractions appear in social posts. Each stat with its source citation can become a social post (often with quote-graphic visual treatment). + +Definition extractions appear in glossaries that the source piece links to. The glossary entry serves as the canonical definition for the term across the program. + +Comparison extractions appear in decision-guide derivatives. The comparison from the source becomes the spine of a separate decision-guide piece. + +The integration discipline. AEO extraction is one derivative type among several; the cross-format set's coordination includes the AEO extractions, not as a separate workflow but as part of the rollout plan. + +--- + +## Methodology-level choices that stay in the public skill + +The six AEO extraction patterns, the question/answer/snippet framing principles, the schema markup integration, the AEO extraction failures, the integration with the broader cross-format set. + +## Implementation choices that stay internal + +Specific schema markup automation. Specific FAQ-page templates in the team's CMS. Specific glossary-page architecture. Specific statistic-extraction tooling. Specific monitoring of AI citation rates per piece. The team's own conventions for FAQ length within the bands. These vary by team, CMS, and AI-citation tracking infrastructure. diff --git a/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md b/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md new file mode 100644 index 0000000..63412eb --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/common-repurposing-failures.md @@ -0,0 +1,175 @@ +# Common repurposing failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most repurposing failures share a single root, which is treating repurposing as content multiplication rather than as cross-format craft. + +--- + +## Failure 1: Mass-blast (same content reposted across channels) + +Symptom. Blog post text pasted into LinkedIn as a long post. Email is the blog's first three paragraphs with "read more." YouTube version is a slideshow of the article text read aloud. + +Diagnosis. Repurposing without per-format adaptation. The team is treating "more channels" as the goal rather than treating each derivative as a piece adapted for its medium. + +Cure. Apply the per-format constraints discipline (see `per-format-constraints.md`). Each derivative gets rewritten for the target format. AI-assisted repurposing without strong format prompts produces this failure; the cure includes voice prompts and per-format instructions. + +--- + +## Failure 2: AI-slop derivatives + +Symptom. Derivatives feel like AI slop. Generic, derivative, signal-less. Voice has drifted from the source. + +Diagnosis. AI-assisted repurposing without voice discipline. AI generation regresses to model defaults; multiple derivatives generated without voice anchor compound the drift. + +Cure. Apply the voice-consistency-across-formats discipline (see `voice-consistency-across-formats.md`). Voice prompts including sample text from the source. Per-derivative voice review. Reject the bland; rewrite generic sentences in voice. See also `ai-content-collaboration` for the broader voice-preservation discipline. + +--- + +## Failure 3: One-and-done + +Symptom. Source pieces publish; never get repurposed. The team produces new flagship work continuously while older flagship work sits unused. + +Diagnosis. No repurposing discipline; the team treats publication as the end of the piece's life. Most of the source-piece value goes unrealized. + +Cure. Establish source-piece tiering (see `source-piece-selection-criteria.md`). Tier 1 and Tier 2 pieces get cross-format extension plans at production time. Capacity allocation for repurposing becomes a real budget line. + +--- + +## Failure 4: Repurposing the wrong pieces + +Symptom. Repurposing capacity goes to pieces that resist extension. The derivatives feel forced; engagement is low. + +Diagnosis. Source-piece selection is choosing pieces by availability rather than by suitability. Pieces with tightly-integrated arguments, list-style structure, or no demand signal are being repurposed when they should stay one-and-done. + +Cure. Apply the selection audit. Run candidates through the strong vs weak source-piece characteristics. Some pieces stay one-and-done; that is the right disposition for them. + +--- + +## Failure 5: Format constraints ignored + +Symptom. Derivatives feel awkward on their target formats. Engagement is low. Audiences scroll past or unsubscribe. + +Diagnosis. Each medium has constraints; the derivatives violate them. LinkedIn long posts as walls of text; emails as image-only layouts; podcasts as articles read aloud. + +Cure. Apply the per-format constraints discipline. Each format has demand-and-forbid lists. Derivatives must respect them, even at cost of departing from the source's surface. + +--- + +## Failure 6: Derivative outperforms source (cannibalization) + +Symptom. A blog-post derivative outperforms the source whitepaper for the source's target keyword. Authority is splitting between the two pieces. + +Diagnosis. Either the source was the wrong format for the topic (the derivative format fits SERP intent better), or the derivative is targeting the same keyword as the source and cannibalizing. + +Cure. Two options. If the source was the wrong format, consider whether the derivative should become the canonical piece (with the source decommissioned or repositioned). If the derivative is cannibalizing, reassign primary keywords: the source keeps the high-value head term; the derivative gets a long-tail variant. + +--- + +## Failure 7: Voice drift across the cross-format set + +Symptom. Each derivative is fine alone but the cross-format set reads as voice variants. Audiences who follow the program notice the inconsistency. + +Diagnosis. Multiple writers or AI generators produced derivatives without voice coordination. Voice drifted across producers. + +Cure. Single voice owner across the cross-format set. Voice library with examples. Calibration sessions where multiple writers reconcile voice expectations. AI tools include the same voice prompts across all derivative generations. + +--- + +## Failure 8: Cadence too aggressive + +Symptom. Cross-format set ships a wave of 12 derivatives in one week. Audiences disengage by day 3. Most derivatives produce minimal engagement. + +Diagnosis. Concentrated cadence too tight for the audience attention rhythm. The cross-format presence on a single week exhausts rather than reinforces. + +Cure. Apply the sequencing-and-cadence discipline. Match cadence to source's traffic curve and audience attention norms. Most cross-format sets benefit from concentrated-but-not-collapsed pacing (4-6 weeks rather than 1 week). + +--- + +## Failure 9: No cross-promotion + +Symptom. Derivatives ship in isolation. No links to source. No links between derivatives. No mention of the cross-format set on the channels where audiences could discover it. + +Diagnosis. Cross-promotion was treated as optional or as an afterthought. The compounding effects of cross-linking and co-promotion are missing. + +Cure. Apply the cross-promotion discipline (see `cross-promotion-patterns.md`). Every derivative includes a derivative-to-source link. The source piece is updated to reference derivatives. Co-promotion across channels is planned at rollout time. + +--- + +## Failure 10: AEO extraction skipped or generic + +Symptom. The cross-format set ships without FAQ extractions or with generic FAQ extractions. AI-search citation rates are low. + +Diagnosis. AEO extraction was not part of the plan, or the FAQ questions do not match user search phrasings, or the answers are context-dependent rather than standalone. + +Cure. Apply the AEO extraction patterns. Treat FAQ extraction, snippet design, and statistic extractions as derivative formats with their own conventions. Schema-mark where appropriate. + +--- + +## Failure 11: No source-piece updating after rollout + +Symptom. The source piece publishes; derivatives ship; the source piece is never updated to reference the derivatives. The source remains static. + +Diagnosis. The forward-promotion from source to derivatives was skipped. The source's role as cross-format hub is wasted. + +Cure. Plan source-piece updates as part of the rollout. As each derivative ships, the source's "related" or "see also" section gets updated. The source becomes a navigation hub for the cross-format set. + +--- + +## Failure 12: Capacity underestimation + +Symptom. The team planned 30 hours for a whitepaper repurposing pipeline; actual cost is 70 hours. New production suffers; team burns out. + +Diagnosis. Capacity estimates were based on optimistic assumptions or on prior pipelines that were not as substantial. + +Cure. Track actual capacity per pipeline (see `repurposing-pipeline-templates.md`). Calibrate estimates over time. Some pipelines genuinely cost more than the team has budget for; the right answer may be to reduce scope rather than to overrun. + +--- + +## Failure 13: No measurement + +Symptom. Cross-format sets ship; the team has a vague sense some perform better than others; the program does not learn. + +Diagnosis. No per-pipeline or per-derivative tracking. Outcomes are anecdotal rather than data-driven. + +Cure. Establish a minimum log per pipeline run: source piece, derivatives planned vs delivered, capacity spent, outcomes per derivative, lessons learned. Pattern-detect across pipelines to inform future ones. + +--- + +## Failure 14: Pipeline dogmatism + +Symptom. The team applies the same pipeline template to every source piece regardless of the source's characteristics or the audience overlap. Some derivatives consistently underperform; the team keeps producing them anyway. + +Diagnosis. Treating templates as fixed shapes rather than as starting points to customize. + +Cure. Customize pipelines per source piece. Audience characteristics, source characteristics, and capacity should adjust the cross-format set. Drop derivatives that consistently underperform for the program's audience mix. + +--- + +## Failure 15: AI repurposing as the strategy + +Symptom. "We use AI to repurpose, so we can scale." The output is a wave of low-engagement derivatives across many channels. The team is producing more derivative content than ever; engagement is flat or declining. + +Diagnosis. AI is being treated as a substitute for the craft of cross-format adaptation. Volume is being prioritized over quality. + +Cure. AI is a tool within the workflow, not the workflow itself. The discipline of adaptation per medium is still the work; AI accelerates parts of it. See `ai-content-collaboration` for the workflow discipline that prevents AI-assisted repurposing from drifting into mass-blast and slop. + +--- + +## The cross-cutting pattern + +Most repurposing failures share a single root: treating repurposing as content multiplication rather than as cross-format craft. + +Multiplication thinking treats each derivative as another item in a quota: more channels, more pieces, more reach. The output is mass-blast and slop because adaptation is skipped. + +Craft thinking treats each derivative as a piece in its own right, adapted for its medium, holding the source's voice while respecting the format's conventions. The output is a coherent cross-format set where each derivative earns engagement on its medium. + +The fix for almost any repurposing failure is the same: stop multiplying, start adapting. The capacity required for craft-driven repurposing is higher than multiplication-driven repurposing; the value extracted is also higher, often by an order of magnitude. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the multiplication-vs-craft framing. + +## Implementation choices that stay internal + +Specific tooling for derivative tracking. Specific reporting templates for cross-format outcomes. Specific reviewer training on per-format conventions. Specific automation that flags voice drift across derivatives. The team's own conventions for failure-pattern detection in their pipelines. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md new file mode 100644 index 0000000..e775ee6 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/cross-promotion-patterns.md @@ -0,0 +1,170 @@ +# Cross-promotion patterns + +Linking patterns, attribution, and co-promotion across channels. The mechanics that turn a cross-format set into a coordinated extension rather than scattered derivatives. + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. The cross-promotion discipline is small per-derivative but compounds significantly across the set. + +--- + +## Derivative back to source + +Each derivative includes a link or reference to the source piece for readers who want depth. + +The pattern. + +- Blog-post derivative includes "This is one of six pieces drawing from our recent whitepaper on X. Read the full whitepaper here." +- Email derivative ends with "Want the full framework? Read the original piece here." +- Social-post derivative includes a link to the source in profile, in comments, or as part of a multi-post thread. +- Podcast episode show notes link to the source article. +- Video description links to the source. + +Why it works. The source's traffic compounds. Audiences who engage with a derivative and want depth click through; the source piece earns continued traffic from the cross-format set. The source's authority benefits from the inbound links from derivative pieces. + +The discipline. Every derivative includes a derivative-to-source link as a non-negotiable element of the format adaptation. The link is not buried; it is positioned where readers who want more naturally find it. + +--- + +## Source forward to derivatives + +The source piece is updated to include links to derivatives as they ship. + +The pattern. + +- A "related" or "see also" section at the end of the source piece, updated as derivatives ship. +- Inline links from specific source sections to corresponding derivatives that develop those sections. +- A dedicated "this piece's extensions" callout linking to the cross-format set. + +Why it works. The source becomes the hub for the cross-format extension. Audiences who land on the source can navigate to derivatives that match their preferred format. The source's role as canonical anchor strengthens. + +The discipline. Update the source piece as the cross-format set rolls out. Stale source pieces that do not reference their derivatives miss the cross-promotion opportunity. + +--- + +## Derivatives across + +Where appropriate, derivatives link to other derivatives in the cross-format set. + +The pattern. + +- Blog post 3 in a series links to blog posts 1, 2, 4, 5, 6 either inline or in a "more in this series" footer. +- Email 5 in a sequence references email 4's framework or previews email 6. +- Podcast episode show notes link to a related video, blog series, or webinar. +- Webinar registration page links to the relevant blog series and the underlying source piece. + +Why it works. The series feeling helps audiences engage with multiple pieces. Internal linking compounds across the set. SEO benefits accrue when derivatives strengthen each other's authority. + +The discipline. Plan the cross-derivative link graph at production time. Each derivative's link plan is part of the production work, not an afterthought. + +--- + +## Attribution within derivatives + +When a derivative is clearly drawn from a source piece, acknowledge. + +The pattern. + +- "This is adapted from our recent piece on X." +- "Drawing from our research on [topic]." +- "Originally published as [source piece title]." +- For social posts: "From our recent whitepaper on X, [insight]." + +Why it works. Attribution earns reader trust. Uncredited derivatives can feel like the same work being recycled without acknowledgment; audiences notice and discount the program's perceived effort. + +The discipline. Attribution is honest about the derivative status. The format adaptation is the value-add; pretending the derivative is independent work overstates the production effort and reads as low-trust positioning. + +Anti-pattern: hiding derivatives. Some teams treat derivatives as if they were independent pieces, with no acknowledgment that they draw from a source. Audiences who follow the program detect the recycling and the cross-format coherence is lost. + +--- + +## Co-promotion across channels + +Derivatives can be promoted on channels other than the channel where they natively live. + +The pattern. + +- A blog post derivative gets re-shared on social where the original blog post might not have been re-shared without the derivative pretext. +- A social post derivative gets mentioned in the email newsletter as "our latest LinkedIn post on X." +- A podcast episode gets promoted on social, in the email, and on the blog. +- A video derivative gets embedded in a blog post or shared via email. + +Why it works. Each derivative's reach extends beyond its native channel. Audiences encountering a derivative through cross-channel promotion discover both the derivative and the channel where it lives. + +The discipline. Plan cross-channel promotion as part of the rollout. Each derivative has a primary channel (where it lives natively) and a secondary channel set (where it gets promoted from). The plan is explicit, not improvised. + +--- + +## Internal linking refresh on related pieces + +Pieces in the library that are related to the source's topic may benefit from updated internal linking when the source's cross-format set rolls out. + +The pattern. + +- Sister pieces that mention the source's topic get updated to link to the source piece (if they did not already) and possibly to the most relevant derivative. +- Pieces in the same hub or category get updated where the cross-format set makes new linking opportunities sensible. +- Anchor text on existing internal links may benefit from refresh if the source's positioning shifted. + +Why it works. The source's authority benefits from internal links across the library. Derivatives benefit from being part of the link graph rather than orphaned. + +The discipline. Run a brief internal-linking audit when the cross-format set rolls out. The audit catches obvious linking opportunities; over-investing in this pass is the failure mode (touching too many pieces, producing diminishing returns). + +--- + +## The cross-promotion graph + +Visualizing the cross-promotion structure as a graph helps catch gaps. + +Nodes. The source piece and each derivative. + +Edges. + +- Source-to-derivative links. +- Derivative-to-source links. +- Derivative-to-derivative links. +- Cross-channel co-promotion (each channel promoting each piece). + +Audit. Each derivative should connect to the source. Each derivative should connect to at least one other derivative where format-appropriate. Each derivative should be co-promoted on at least one secondary channel where audience overlap exists. + +Output of the audit. A planned link and promotion graph for the cross-format set, with the gaps identified before the rollout begins. + +--- + +## Common cross-promotion failures + +Derivatives shipping in isolation. Each derivative ships without links to source or to other derivatives. The cross-format set reads as scattered pieces; the compounding effect of cross-linking is lost. + +Source piece not updated. Source publishes; derivatives ship; the source piece is never updated to reference the derivatives. The hub function of the source is wasted. + +Attribution skipped. Derivatives ship without acknowledging the source. Audiences detect the recycling; trust degrades. + +Cross-channel co-promotion skipped. Each derivative stays on its native channel. Reach is limited to the audiences who happen to be on each channel. + +Internal-linking refresh skipped. Existing pieces in the library do not get linked to the new source piece. The library's internal-link graph stays static; the source piece's authority does not benefit. + +Over-investment in cross-promotion. Internal-link refresh that touches 50+ pieces in the library produces diminishing returns and maintenance overhead. Cure: target the highest-value linking opportunities; skip the marginal ones. + +--- + +## Cross-promotion in mature programs + +Programs with established cross-promotion discipline accumulate compounding effects over time. + +The pattern in mature programs. + +- Every flagship piece has an established cross-format extension plan. +- Every derivative has documented linking and promotion structure. +- The library's internal-link graph reflects accumulated cross-promotion across multiple cross-format sets over years. +- Audiences trust that pieces from the program connect; navigation between pieces feels intuitive. + +The compounding effect. Older flagship pieces continue to draw traffic because their cross-format sets extended their reach; their derivatives continue to draw traffic because their cross-promotion brought audiences in. The library's traffic profile reflects accumulated cross-format work, not just individual-piece performance. + +The maturity audit. Do new flagship pieces' cross-format sets connect to older flagship pieces' cross-format sets where topics overlap? Mature programs cross-promote across time; immature programs treat each cross-format set as isolated. + +--- + +## Methodology-level choices that stay in the public skill + +The cross-promotion link patterns, attribution discipline, co-promotion across channels, internal linking refresh, the cross-promotion graph, the common failures, the maturity-audit pattern. + +## Implementation choices that stay internal + +Specific link-graph tooling. Specific automation that surfaces missing cross-format links. Specific channel-promotion calendars. Specific internal-link audit tools. The team's own conventions for attribution language. These vary by team, CMS, and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md new file mode 100644 index 0000000..18b376f --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/format-adaptation-patterns.md @@ -0,0 +1,202 @@ +# Format adaptation patterns + +Eight source-to-derivative adaptations with worked examples. The patterns that distinguish thoughtful adaptation from mass-blast. + +Each pattern below is a recurring shape: a particular source-piece type adapting into a particular derivative format. The patterns are not the only adaptations; they are the most common, with the most predictable success and failure modes. + +--- + +## Pattern 1: Long-form to blog series + +Source. A 4,000-8,000 word whitepaper, definitive guide, or research report. + +Derivatives. 4-6 standalone blog posts. Each post takes one of the source's H2 sections (or one of its sub-arguments) and develops it as a piece in its own right. + +Adaptation work. + +- New lede per post. The source's lede establishes the whole piece's thesis; each derivative needs its own lede that establishes its standalone scope. +- New closing per post. Source closing addresses the whole piece's argument; derivative closings address the post's specific argument. +- Connective tissue. Each derivative briefly references the source piece ("This is one of six pieces drawing from our recent whitepaper on X") and links forward to other derivatives in the series and back to the source. +- SEO targeting per derivative. The source piece may target one primary keyword cluster; each derivative can target a more specific long-tail keyword. + +Example. A whitepaper "The complete framework for content distribution" with H2 sections on owned, earned, paid channels, audience-channel matching, content-channel matching, and distribution measurement. Derivatives: 6 blog posts, one per section, each developing the section into a standalone piece (typically 1,200-1,800 words each). + +Common failures. + +- Derivative posts that are paste-ins of source sections without rewriting. Reads as duplicate content; SEO penalty risk; voice flatness. +- Derivative posts that compete with the source for the same keyword (cannibalization). Cure: explicit primary-keyword assignment per piece, with derivatives on long-tail variants. +- Derivative posts that drop the source's voice. Cure: voice prompts and review per derivative. + +--- + +## Pattern 2: Blog post to email sequence + +Source. A 1,200-2,500 word blog post on a multi-step framework, methodology, or process. + +Derivatives. 3-7 emails delivered over 1-3 weeks. Each email develops one step or section of the source's framework with sender-voice adaptation. + +Adaptation work. + +- Sender voice. Email voice is more direct and conversational than blog voice. Sentences shorter; "you" usage higher; more direct address. +- Engagement hooks per email. Subject line and preheader carry most of the email's open-rate burden. Hooks need to be earned per email. +- One CTA per email. Email format rewards single clear CTAs; multi-CTA emails underperform. +- Sequential building. Each email assumes the prior emails have been read; the sequence builds; the final email synthesizes. + +Example. A blog post on "the 5-step framework for product launches" becomes a 6-email sequence: introduction email, one email per step, synthesis email. Each email is 200-500 words with a single CTA. + +Common failures. + +- Emails that are blog paragraphs with "read more" links. Mass-blast pattern. +- Emails that lose voice consistency. Cure: voice anchored to source's distinctive register; per-email review. +- Sequences that are too long. 12-email sequences from a 1,500-word source are over-extension; audiences disengage. Cure: match sequence length to source's actual content depth. + +--- + +## Pattern 3: Whitepaper to webinar + +Source. A substantive whitepaper or research report. + +Derivatives. A 30-45 minute webinar with the whitepaper's framework as the spine, plus live elements that print does not support: Q&A, polls, interactive moments, possibly guest appearances. + +Adaptation work. + +- Spine selection. The webinar typically takes the whitepaper's 3-5 most load-bearing sections as its spine. Lower-priority sections from the source become spoken asides or get cut. +- Spoken-language adaptation. Print-style sentences read aloud sound stilted. The webinar script (or speaker notes) is rewritten in spoken voice. +- Interactive design. Polls, Q&A, audience prompts. Webinar without interactivity is a video; webinar with interactivity earns the format. +- Slide design. Text-heavy slides fail; the visual layer carries the audience's attention while the speaker delivers the content. +- Recording and follow-up. Most webinars become video derivatives after the live session; the recording extends value indefinitely. + +Example. A 6,000-word research report on B2B paid media benchmarks becomes a 40-minute webinar: 25-minute walkthrough of the report's framework with the speaker's commentary, 10-minute Q&A, 5-minute conclusion with specific recommendations. The recording is later cut into derivative video clips. + +Common failures. + +- Webinars that read the whitepaper aloud. The whitepaper is published; the webinar adds nothing. +- No interactivity. Live audiences disengage when the format is one-way. +- Text-heavy slides that compete with the speaker. Cure: visuals carry the design; speaker carries the content. + +--- + +## Pattern 4: Long-form to social posts + +Source. A long-form piece (whitepaper, definitive guide, research report). + +Derivatives. 8-30 social posts across the platforms where the audience exists. Each post is one specific moment from the source: a pull quote, a framework summary, a key statistic, a contrarian claim. + +Adaptation work. + +- Platform-specific structure. LinkedIn long-post structure differs from X/Twitter thread structure differs from Threads structure. Adaptation is per platform. +- Hook in the first 1-2 lines. Social readers decide to expand or scroll within seconds; the hook earns expansion. +- Visual or quote-graphic options. Many social posts benefit from accompanying visuals (quote graphics, statistic graphics, framework diagrams). +- One specific point per post. Multi-point social posts dilute; one clear point earns engagement. +- Series cadence. Posts shipped over weeks rather than dumped in one day; audiences engage with each post if they are spaced. + +Example. A whitepaper on AI search optimization becomes 18 social posts: 6 framework-summary posts, 4 statistic posts (with custom graphics), 4 contrarian-claim posts, 4 question-prompt posts. Distributed over 6 weeks across LinkedIn and X. + +Common failures. + +- Posts that are quote graphics with no context. The graphic is decoration; the post needs text that earns engagement. +- Posts that read as blog-text paste-ins. Mass-blast on social. +- Cadence too aggressive. 18 posts in one week exhausts audiences; distributed cadence performs better. + +--- + +## Pattern 5: Article to podcast episode + +Source. A substantive article (1,500-3,500 words). + +Derivatives. A podcast episode with the article as spine, plus host commentary, examples, and possibly guest interviews. + +Adaptation work. + +- Spoken-language adaptation. Article sentences read aloud sound stiff. The episode script (or talking-points outline) is in spoken voice. +- Conversational pacing. Examples and asides that print would cut earn their place in audio because the conversation needs space to breathe. +- Show notes as derivative format. The show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as a derivative in their own right. +- Guest dynamics where applicable. Some podcast episodes pair the article's framework with guest perspective; the article is the show's structured input, the guest adds expert commentary. + +Example. An article on programmatic SEO durability becomes a podcast episode: 5-minute introduction by the host, 30-minute interview with a practitioner who has run programmatic operations, 10-minute synthesis by the host. Show notes link to the source article and to several mentioned references. + +Common failures. + +- Episodes that read the article aloud. The article is published; the episode adds nothing. +- Episodes without spoken-language adaptation. Stilted delivery; low completion rates. +- Show notes that are afterthoughts. Show notes that fail their own format reduce the episode's discoverability and value. + +--- + +## Pattern 6: Long-form to video shorts + +Source. A long-form piece with travelable elements (specific examples, framework moments, contrarian claims). + +Derivatives. 6-20 short-form video clips, 30-90 seconds each. Each short is one standalone moment. + +Adaptation work. + +- Hook in seconds 1-2. Algorithmic recommendation rewards retention from second 1; openings must earn continued viewing. +- Captions essential. Many viewers watch without sound; captions carry the message. +- Visual presence. Talking-head shorts work for some audiences; many short-form platforms reward visual variation, motion, or text-on-screen design. +- Single specific point per short. Short-form does not support multi-point delivery; one moment per clip. +- Platform-specific aspect ratios and conventions. TikTok shorts, Instagram Reels, YouTube Shorts each have specific norms. + +Example. A research report becomes 12 video shorts: 4 statistic shorts (text-on-screen with audio narration), 4 framework moment shorts (whiteboard-style explanation), 4 contrarian-claim shorts (talking head). Distributed across LinkedIn video, YouTube Shorts, Instagram Reels. + +Common failures. + +- Shorts without strong opening hooks. Algorithmic feed deprioritizes; reach is minimal. +- Shorts without captions. 50%+ of audience cannot consume the content. +- Shorts that try to cover too much in 60 seconds. Cure: one moment, one point, one short. + +--- + +## Pattern 7: Research report to FAQ extractions + +Source. A research report or definitive guide with specific Q&A-able material. + +Derivatives. Standalone FAQ entries (40-80 words each), formatted for AI search citation, possibly aggregated into FAQ pages or schema-marked snippets within the source piece. + +Adaptation work. + +- Question framing. AI search engines cite content that matches likely user-query phrasings. FAQ questions need to use the phrasings users actually search. +- Standalone answer paragraphs. Each FAQ answer must work as a standalone paragraph; AI engines cite paragraphs, not contextual passages. +- Source attribution within the answer. Statistics and specific claims need named sources within the answer paragraph; AI engines weight named-source claims at higher rates. +- Schema markup. FAQPage schema where the FAQ aggregates as a dedicated page; structured data signals the format to search engines. + +Example. A research report on content distribution effectiveness becomes 15 FAQ extractions: "What channels produce highest engagement for B2B content?" "How does audience size affect channel selection?" "What is the typical engagement rate decay across channel types?" Each Q&A is 40-80 words with named-source citations. + +Common failures. + +- Questions that do not match how users phrase queries. Cure: query research; phrase questions in user voice. +- Answers that depend on context outside the answer paragraph. AI engines may not cite cleanly; paragraphs need to stand alone. +- Missing schema markup. The FAQ format does not signal cleanly to search engines without schema. + +--- + +## Pattern 8: Multi-piece source to ebook + +Source. Several related pieces (blog posts, articles, social threads) that together cover a topic. + +Derivatives. An ebook with the multi-piece content as the bulk, plus new connective tissue: introduction, chapter framings, conclusions, and possibly new chapters that fill gaps the source pieces did not cover. + +Adaptation work. + +- Topic synthesis. The multi-piece source covers the topic in scattered ways; the ebook needs to organize the content into a coherent sequence. +- New connective tissue. Introductions, chapter prefaces, transitions, conclusion. Often 20-30% of the ebook is new content not present in the source pieces. +- Voice consolidation. Pieces written over months may have voice variation; the ebook needs to read as one unified work, which often means rewriting passages to match a target voice. +- Design and production. Ebook format expectations: chapter design, table of contents, possibly downloadable PDF. Higher production cost than other repurposing patterns. + +Example. Twelve blog posts on a topical theme, written over 18 months, are consolidated into a 22,000-word ebook. New material includes a 1,500-word introduction, chapter framings totaling 3,000 words, a 1,500-word conclusion, and a 2,500-word new chapter that fills a gap the original posts did not address. + +Common failures. + +- Ebook that reads as posts stitched together. Cure: rewrite for unity; the ebook is a piece in its own right. +- No new connective tissue. The ebook adds no value over reading the source pieces. +- Voice inconsistency. Voice drift across pieces becomes visible when consolidated; cure: unified voice editing pass. + +--- + +## Methodology-level choices that stay in the public skill + +The eight adaptation patterns with their work, examples, and common failures. The recurring lesson: adaptation is per-format craft, not source-text recycling. + +## Implementation choices that stay internal + +Specific platform automation tooling. Specific design templates per derivative format. Specific tooling for video clip extraction from longer videos. Specific show-notes templates. Specific schema markup patterns the team uses for FAQ extractions. The team's own conventions for connective-tissue length in ebook consolidation. These vary by team, stack, and platform mix. diff --git a/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md b/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md new file mode 100644 index 0000000..df75a32 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/per-format-constraints.md @@ -0,0 +1,192 @@ +# Per-format constraints + +What each medium demands and forbids. Length norms, conventions, hooks, and the underlying observation: derivatives that ignore the medium's constraints fail the medium even when the source content was strong. + +Each format below has specific reader expectations. Pieces that meet expectations earn engagement; pieces that violate expectations get scrolled past or ignored regardless of content quality. Repurposing capacity goes to waste when derivatives fail the format-specific tax. + +--- + +## Email + +Length norms. 200-800 words per email for most B2B and consumer audiences. Newsletter-style emails can run longer (1,500-3,000 words) for engaged audiences but shorter is generally safer. + +What email demands. + +- A subject line that earns the open. Most engagement happens or fails at the subject-line level. +- A preheader that supports the subject line. The preheader is the second-most-read element of the email and most templates underuse it. +- Plain prose paragraphs that render reliably. Many email clients break complex formatting; tables, columns, and rich layouts can fail. +- A single clear CTA. Multi-CTA emails dilute; readers process one action at a time. +- Mobile-first design. 60-70% of email opens are on mobile; readability on small screens is essential. + +What email forbids. + +- Image-only emails. Many clients block images by default; image-only emails arrive blank. +- Link-laden text dumps. More than 3-4 links in body text dilutes attention. +- Multi-CTA layouts that compete for the click. +- Subject lines that announce the topic without earning the open ("Newsletter for week of X"). + +Adaptation discipline. Email derivatives need new ledes (the source's lede does not transfer); spoken-direct voice (more "you" usage; shorter sentences than blog voice); a single CTA per email even when the source piece had multiple potential actions. + +--- + +## LinkedIn (long-form text post) + +Length norms. 800-2,500 characters typical; long-form posts up to ~3,000 characters. The character count matters because the platform truncates with "see more"; the truncation point is the hook. + +What LinkedIn demands. + +- A first line that earns the "see more" click. The first 1-3 lines determine whether readers expand the post. +- Clear structure: short paragraphs, white space, occasional emphasis. Walls of text get scrolled past. +- A specific point or argument. Narrative-style posts that take time to land work; vague observations do not. +- Engagement hooks: questions, polarizing claims, specific examples that invite comment. +- Original perspective. Repurposed content marked clearly as such; uncredited recycling reads as low effort. + +What LinkedIn forbids. + +- Walls of text without paragraph breaks. +- Generic motivational content; the platform has decreasing tolerance for this. +- Posts that read as ads with no substantive content. +- Heavy use of emoji decoration without purpose. + +Adaptation discipline. Source content needs to be restructured for LinkedIn rhythm: short opening hook, body with paragraph breaks every 2-3 sentences, specific examples or stakes, possibly a question at the close that invites comment. + +--- + +## X/Twitter (single post and threads) + +Length norms. Single post: 280 characters (or up to 4,000 for premium accounts; conventions vary). Thread: 5-15 posts typical for substantive threads. + +What X demands (single post). + +- Tight phrasing. Each character matters; specific framings that fit the format earn engagement. +- Stand-alone meaning. Tweets that depend on context outside the tweet often fail. +- Specific points or claims. Vague observations underperform. + +What X demands (threads). + +- A first post that earns the next click. Threads are read sequentially; the first post must hook. +- One coherent argument across the thread. Threads that wander get abandoned mid-way. +- Reasonable length. Threads longer than 15-20 posts often lose readers; very long threads may be better as a blog post linked from a shorter thread. + +What X forbids. + +- Threads that read as a blog post split into 280-character chunks. The platform's conversational rhythm is different. +- Hashtags-as-content. Heavy hashtag usage signals SEO chasing rather than communication. + +Adaptation discipline. Source content for threads needs to be re-paced: each post a complete thought, the thread building, the conclusion specific. + +--- + +## Long-form video (YouTube, in-depth content) + +Length norms. 8-30 minutes typical for substantive content. Some categories support longer (45-90 minutes for deep technical content); the algorithm rewards retention over duration. + +What long-form video demands. + +- Pacing for spoken delivery. Print-style sentences read aloud sound stilted; video scripts need spoken voice. +- Visual variation. Talking-head video alone for 30+ minutes underperforms; cuts, b-roll, on-screen text, illustrations carry attention. +- Audio quality. Bad audio kills retention faster than bad video; audio investment usually returns more than video investment. +- A specific topic. The video's title and thumbnail need to communicate scope; vague titles underperform in algorithmic recommendation. + +What long-form video forbids. + +- Slideshows of text read aloud. Mass-blast pattern in video form. +- No editing. Filler words, long pauses, and unedited rambling reduce retention. +- Talking head only with no visual variation across long durations. + +Adaptation discipline. Source content for video needs scripting in spoken voice (or talking-points for unscripted delivery), visual planning per segment, and an opening that earns the next 30 seconds of viewing. + +--- + +## Short-form video (TikTok, Reels, Shorts) + +Length norms. 60-90 seconds typical; 15-30 seconds for some platforms. Algorithmic recommendation typically rewards retention from second 1. + +What short-form demands. + +- Hook in seconds 1-2. Viewers scroll past the opening if it does not earn the next 5 seconds. +- Captions. Many viewers watch without sound; captions carry the message. +- A single specific point. Short-form does not support multi-point delivery. +- Visual presence. Motion, text-on-screen, or visual variation within the short. Static talking heads underperform. + +What short-form forbids. + +- Content that takes 10+ seconds to land. Viewers leave before the point. +- Long-form video clipped without re-pacing. The pacing assumed in the source piece does not match short-form expectations. +- Captions that lag the audio. Mistimed captions distract. + +Adaptation discipline. Source content for shorts needs extreme compression: one moment, one point, one short. Each short is a standalone unit. + +--- + +## Podcast + +Length norms. 20-90 minutes typical for substantive content. Daily-news-style podcasts can be shorter (8-15 minutes); deep-interview podcasts can run 90-180 minutes. + +What podcast demands. + +- Spoken-language sentence structure. Print-style sentences read aloud sound stiff. +- Conversational pacing. Examples, asides, and natural speech earn engagement; tightly-argued print sections feel cold. +- Audio quality. Listening is intimate; bad audio breaks the connection. Better audio than video matters here. +- Show notes that do the print work the audio cannot. Links, structured summary, citations, references. + +What podcast forbids. + +- Reading articles aloud without adaptation. +- Scripts that sound scripted (over-rehearsed delivery, no conversational rhythm). +- Episodes without show notes or with thin show notes. +- Inconsistent episode length within a series; audiences develop expectations. + +Adaptation discipline. Source content for podcasts becomes the show's spine; the host adds context, examples, and conversational elaboration. Show notes are a distinct derivative format with their own constraints. + +--- + +## Webinar + +Length norms. 30-60 minutes typical. Longer webinars (90+ minutes) require very high engagement design or strong specific draws (like premiere announcements). + +What webinars demand. + +- A live element. Q&A, polls, interactive moments. Static webinars are videos; interactive webinars earn the format. +- Slide design that supports rather than competes with delivery. Text-heavy slides distract; visual slides with the speaker carrying the content work. +- Pacing for live audience attention. Audience attention dips in the middle; engagement design needs to address the dip. +- Recording strategy. Most webinars become video assets after the live session; the recording extends value indefinitely. + +What webinars forbid. + +- Reading slides aloud. The audience can read; the speaker should add the value the slides cannot carry. +- No engagement design. Audiences disengage in pure one-way webinars. +- Webinars that try to cover too much in 30 minutes. Cure: narrow the topic to what 30 minutes can deliver. + +Adaptation discipline. Source content for webinars typically takes the source's 3-5 most load-bearing sections as the spine, plus interactive moments, plus Q&A. + +--- + +## AI-search snippet (for citation by AI engines) + +Length norms. 40-80 words per snippet for FAQ-style extractions; 100-200 words for paragraph-style extractions. + +What AI-search snippets demand. + +- Standalone meaning. The snippet works without the surrounding context; AI engines extract paragraphs, not full pieces. +- Named-source citations within the snippet. AI engines weight named-source claims; "according to a 2025 Forrester study" performs better than "studies show." +- Specific framings. Vague phrasings rarely get cited; specific phrasings do. +- Schema markup where applicable. FAQPage and similar schemas signal the format. + +What AI-search snippets forbid. + +- Floating claims without sources. +- Pronoun references that depend on outside context ("This is why..." with no clear referent within the snippet). +- Hedged language on claims that can be specific. + +Adaptation discipline. Source content for AI snippets needs to be extractable as standalone paragraphs with internal citations and specific framings. Often the source piece needs additions specifically designed for snippet citation. + +--- + +## Methodology-level choices that stay in the public skill + +The format constraints by medium, the length norms, the demand-and-forbid lists, the adaptation discipline per format. The underlying observation: medium constraints are non-negotiable. + +## Implementation choices that stay internal + +Specific platform automation. Specific design templates per format. Specific captioning workflows. Specific schema markup patterns. Specific A/B testing of format-specific elements (subject lines, hooks, opening lines). The team's own conventions on length within the bands. These vary by team and platform mix. diff --git a/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md b/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md new file mode 100644 index 0000000..9325d2f --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/repurposing-pipeline-templates.md @@ -0,0 +1,237 @@ +# Repurposing pipeline templates + +Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. The repeatable shapes that turn ad-hoc repurposing into a predictable program. + +Repurposing without templates produces ad-hoc workflows: each cross-format extension is invented from scratch, capacity estimates are unreliable, quality varies. Templates make repurposing a known production shape, with predictable capacity and predictable quality. + +The templates below are recurring shapes; teams adapt them to specific source pieces and program contexts. + +--- + +## Pipeline 1: Whitepaper + +Source. A 4,000-8,000 word whitepaper or definitive guide. + +Cross-format set (typical). + +- 4-6 blog posts (one per major section). +- 5-7 email sequence. +- 1 webinar. +- 12-18 social posts across LinkedIn, X, possibly Instagram or Threads. +- 6-12 video shorts. +- 10-15 FAQ extractions for AI search. +- Possibly 1 podcast episode. + +Production sequence. + +- Week 0: Source piece publishes. +- Week 1: First social posts ship; email teaser sends. FAQ extractions ship as part of the source piece (or as an immediately-following FAQ page). +- Weeks 2-6: Blog posts ship at 1-per-week cadence. Email sequence sends in parallel. More social posts ship from each blog post's release. +- Weeks 4-8: Webinar runs. Webinar recording becomes additional video derivatives. +- Weeks 6-10: Video shorts ship. Podcast episode (if applicable) records and releases. + +Capacity. Typical whitepaper pipeline costs 30-60 hours of editorial and production work across 8-10 weeks, on top of the source piece's production cost. + +Owner structure. Single owner-of-extensions for the whitepaper. Specific derivative owners by format (blog series owner, email sequence owner, social owner, video owner). The owner-of-extensions coordinates timing and ensures cross-promotion happens. + +--- + +## Pipeline 2: Blog post (substantive) + +Source. A 1,500-2,500 word substantive blog post on a multi-step framework or substantive topic. + +Cross-format set (typical). + +- 5-7 email sequence (if the source has a multi-step framework). +- 4-8 social posts. +- 2-4 video shorts. +- 3-5 FAQ extractions. +- Possibly 1 podcast episode segment (not full episode). + +Production sequence. + +- Week 0: Blog post publishes. +- Week 1: First social posts ship; email teaser if part of a sequence; FAQ extractions added to the post. +- Weeks 2-4: Email sequence sends. Additional social posts. Video shorts ship. +- Weeks 4-6: Long-tail social and AI-search-snippet refinement. + +Capacity. Typical substantive blog post pipeline costs 8-15 hours of additional work across 4-6 weeks. + +Owner structure. Often one owner runs the full extension for blog-post-tier sources because the work is small enough to coordinate in one head. + +--- + +## Pipeline 3: Research report + +Source. A 4,000-12,000 word research report with primary data. + +Cross-format set (typical). + +- 5-8 blog posts (one per major finding or section). +- 7-10 email sequence. +- 1-2 webinars (often a launch webinar plus a deeper-dive webinar). +- 20-30 social posts (research reports produce many statistic-driven social derivatives). +- 8-15 video shorts (statistic-focused). +- 15-25 FAQ extractions. +- 1-2 podcast episodes. +- Possibly an interactive data visualization or microsite. + +Production sequence. + +- Week -2 to Week 0: Pre-launch promotion teasers (research findings preview). +- Week 0: Source report publishes; launch webinar announces; first wave of statistic-focused social ships. +- Weeks 1-4: Heavy email sequence; blog posts ship; webinars run; social posts continue. +- Weeks 4-12: Video shorts roll out; podcast episodes record and release; FAQ extractions get refined as AI-search citations are tracked; second webinar runs for deeper-dive audience. +- Indefinitely: Statistics from the report continue to be cited in subsequent program pieces; the report becomes a reference asset. + +Capacity. Research report pipelines are the highest-investment repurposing efforts. Typical cost: 60-150 hours of additional work across 8-16 weeks, on top of the report's production cost. + +Owner structure. Owner-of-extensions plus dedicated derivative owners. Often a research report's cross-format extension is treated as a project with its own project manager rather than as a routine repurposing pipeline. + +--- + +## Pipeline 4: Multi-piece consolidation (ebook) + +Source. Multiple existing pieces (blog posts, articles, social threads) on a related topic. + +Cross-format set (typical). + +- 1 ebook (the primary consolidation). +- New introduction, chapter framings, conclusion within the ebook (often 20-30% new content). +- 4-7 promotional blog posts (potentially excerpting chapters or introducing the ebook). +- 5-8 email sequence promoting the ebook. +- 1 webinar based on the ebook's framework. +- 8-15 social posts promoting the ebook and its chapters. +- 3-6 video shorts. + +Production sequence. + +- Months 1-3: Source-piece selection and consolidation. Identify which existing pieces fit; outline the ebook; write new connective tissue; consolidate and edit for unified voice. +- Month 3-4: Production: design, layout, possibly PDF generation, gating setup if applicable. +- Month 4: Ebook launches. First promotional blog posts and emails ship. Webinar runs. +- Months 5-8: Promotional cadence continues. Video shorts and social posts roll out. + +Capacity. Multi-piece consolidation pipelines often cost 60-120 hours of consolidation and production work, plus the standard derivative production. Total: 80-180 hours across 4-8 months. + +Owner structure. A consolidation lead drives the editorial work; standard derivative owners run the promotional set. The consolidation lead often is a senior editor because the unified-voice editing is substantial. + +--- + +## Pipeline 5: Trending topic editorial + +Source. A 1,000-2,500 word editorial piece on a trending or news-driven topic. + +Cross-format set (typical, lighter than evergreen). + +- 4-7 social posts (concentrated in the first week to ride the trend). +- 1-2 video shorts. +- 1-2 FAQ extractions if the topic supports it. +- Often no email sequence (trending topics may not justify a multi-email investment). +- Often no webinar (production cycle is too long for trending topics). + +Production sequence. + +- Day 0: Source piece publishes. +- Days 1-7: Social posts ship rapidly to ride the trend. Video shorts ship if production cycle allows. +- Weeks 2-4: Long-tail social and AI-search-snippet refinement if the topic has staying power. +- After 4 weeks: Pipeline typically winds down as the trend fades. + +Capacity. Trending topic pipelines are deliberately light: 4-10 hours of additional work across 1-2 weeks. + +Owner structure. Often one owner runs the full extension because timeliness matters more than coordinated multi-format depth. + +--- + +## Pipeline 6: Case study + +Source. A 2,000-4,000 word case study with real specifics. + +Cross-format set (typical). + +- 3-5 blog posts pulling specific lessons or framework moments from the case. +- 3-5 email sequence (if the case study has clear teachable steps). +- 6-10 social posts (often statistic-driven from the case's outcomes). +- 1-3 video shorts (often featuring the case's customer if available, with their consent). +- 3-5 FAQ extractions. +- Possibly 1 webinar featuring the customer. + +Production sequence. + +- Week 0: Case study publishes. +- Week 1: First social posts ship; FAQ extractions added. +- Weeks 2-6: Blog posts and emails ship. Webinar runs (if part of the plan, often with customer participation). +- Weeks 4-10: Video shorts and additional social. + +Capacity. Typical case study pipeline costs 15-30 hours of additional work, plus customer coordination time for any derivatives featuring the customer. + +Owner structure. Customer-coordination owner plus standard derivative owners. The customer-coordination owner manages the relationship; derivative owners produce the work; the customer reviews customer-facing derivatives before they ship. + +--- + +## Pipeline customization + +Templates are starting points; programs adapt them. + +Customization based on audience. + +- B2B technical audiences: more LinkedIn, more whitepaper-driven; less TikTok and Instagram. +- Consumer audiences: more video and visual social; less long-form. +- Vertical-specific audiences: platform mix may differ (YouTube heavy in some industries; Twitter/X heavy in others). + +Customization based on capacity. + +- Smaller teams may execute Pipeline 1 with reduced scope (3 blog posts instead of 6, 6 social posts instead of 18). +- Larger teams may extend pipelines with additional derivatives the templates do not include (interactive tools, microsites, dedicated landing pages). + +Customization based on source characteristics. + +- Highly visual source pieces benefit from heavier video and visual-social investment. +- Voice-distinctive source pieces benefit from heavier email and podcast investment (where voice carries). +- Citation-rich source pieces benefit from heavier AEO-extraction investment. + +--- + +## Pipeline tracking + +Each pipeline run produces data that informs future pipelines. + +The minimum log per pipeline. + +- Source piece title, type, length, traffic at launch. +- Cross-format set planned vs delivered. +- Capacity spent (hours per derivative type). +- Outcomes per derivative (engagement, traffic, conversion, citation rates). +- Lessons learned (what worked, what failed, what to change next time). + +Pattern detection across pipelines. + +- Are some pipeline templates outperforming others on similar source types? +- Are some derivative types consistently outperforming others? +- Are capacity estimates accurate, or do certain pipelines consistently overrun? +- Are some channels consistently underperforming for the program's audience mix? + +The log informs program-level decisions: which pipelines to invest in more deeply, which to drop, which to redesign. + +--- + +## Common pipeline failures + +Pipeline-as-checklist. The team treats the pipeline as a checklist to complete rather than as a coordinated plan. Each derivative gets produced; nothing connects to the others; cross-promotion is missing. + +Capacity underestimation. Teams plan a Pipeline 1 expecting 30 hours; actual cost is 70 hours; new production suffers. Cure: track actual capacity per pipeline; calibrate estimates. + +Pipeline dogmatism. Treating the template as a fixed shape regardless of source-piece characteristics. Some source pieces fit the template; some need customization. Cure: customize pipelines per source. + +No tracking. Pipelines run; outcomes are not measured; the program does not learn. Cure: minimum log per pipeline. + +No owner-of-extensions. Pipelines run with derivative owners but no overall coordination. Cross-promotion gaps; cadence drift; no single accountable person. Cure: assign an owner-of-extensions per pipeline. + +--- + +## Methodology-level choices that stay in the public skill + +The six pipeline templates with cross-format set, sequencing, capacity, and ownership structures. The pipeline customization framework. The pipeline tracking log. The common pipeline failures. + +## Implementation choices that stay internal + +Specific project-management templates per pipeline. Specific calendar tooling for cross-format scheduling. Specific time-tracking that captures pipeline capacity. Specific reporting templates for pipeline outcomes. The team's own conventions for which pipelines apply to which source-piece tiers. These vary by team, tooling, and program scale. diff --git a/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md b/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md new file mode 100644 index 0000000..0678d1e --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/sequencing-and-cadence-patterns.md @@ -0,0 +1,198 @@ +# Sequencing and cadence patterns + +When to release derivatives relative to the source. Concentrated vs distributed cadence. Pacing audits. The patterns that match cadence to the source's traffic curve and audience attention. + +The release sequence and cadence determine how the cross-format set lands. The wrong sequencing can produce a wave of derivatives that exhausts audiences, or a trickle that loses connection to the source's authority. The right sequencing matches the source's traffic curve and the audiences' attention rhythm. + +--- + +## Sequencing patterns + +Three patterns for how derivatives sequence relative to the source. + +### Source-first, derivatives following + +The pattern. The source piece publishes; derivatives roll out over the following 2-12 weeks. The source carries the initial authority and traffic spike; derivatives extend reach and re-engage audiences over time. + +Strengths. + +- The source piece's launch is concentrated, earning the full attention of the program's audiences. The launch is a moment. +- Derivatives reference the source's authority. Each derivative can link back to the source as the canonical version; the source's ranking and authority compounds. +- Audiences who engaged with the source are primed for derivatives; the first derivative often performs well because the audience is warm. + +Weaknesses. + +- The source needs to support the launch with strong promotion. If the source publishes quietly, the launch moment is muted. +- Audiences who missed the source see derivatives without context; the derivatives need to stand alone. + +Fits. Most programs. The default sequencing pattern. + +### Simultaneous launch + +The pattern. Source and a wave of derivatives publish on the same day. Multiple channels fire at once. + +Strengths. + +- Maximum splash. The cross-format presence on a single day signals significance to audiences. +- Cross-channel reinforcement. Audiences encountering the program on multiple channels in one day register the significance more strongly than serial encounters. + +Weaknesses. + +- Risks audience fatigue. If every channel is firing the same day, audiences may tune out before they engage with any individual piece. +- Heavy production load on launch day. All derivatives must be ready simultaneously, which can compress quality. +- Less time for individual derivatives to land. Each derivative competes for attention with every other derivative on the same day. + +Fits. Major flagship launches where the moment itself is part of the value (annual research reports, ebook releases, manifesto-style pieces). Tier 1 source pieces. + +### Derivatives-first, source as anchor + +The pattern. Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship after the buildup. + +Strengths. + +- Builds anticipation. Audiences who engage with the early derivatives expect the source piece. +- The source piece publishes into a primed audience. + +Weaknesses. + +- Less common; works only for built-up audiences who follow the program closely. +- Risks giving away too much before the source. If the early derivatives expose the source's argument, the source publishes into an audience that feels they have already read it. +- Coordination overhead. The cross-format buildup needs to land at the right cadence to support the source's launch. + +Fits. Programs with engaged audiences and strong social presence. Less common than source-first; specific to programs that have earned anticipation. + +--- + +## Cadence within the rollout + +Three pacing patterns within the chosen sequencing. + +### Concentrated cadence + +The pattern. Most derivatives ship within 4-6 weeks of source. + +Strengths. + +- Maximum momentum from the source's authority. The source's traffic curve is highest in the first 2-4 weeks; derivatives launching during that window benefit from the source's freshness. +- The cross-format set feels coherent. Audiences see the program everywhere within a short window; the campaign feeling earns engagement. +- Easier to coordinate. Production and scheduling concentrate; the team is in launch mode for a defined period. + +Weaknesses. + +- Limited time for individual derivatives to land. A derivative in week 5 has less attention available than the source did in week 1. +- Audience fatigue risk. Audiences may disengage before week 4-6 if the cadence feels relentless. +- Less long-tail value. After week 6, the cross-format set largely stops producing new touchpoints. + +Fits. Tier 1 and Tier 2 source pieces. Programs running flagship launches where the campaign nature is part of the strategy. + +### Distributed cadence + +The pattern. Derivatives ship over 3-6 months. + +Strengths. + +- Each derivative has space to land. No internal competition for audience attention. +- Long-tail value. The program continues to produce touchpoints over a longer window. +- Sustainable. The team is not in launch mode for months; production fits steady-state cadence. + +Weaknesses. + +- Risk of losing connection to source. By month 3, the source piece may be background context rather than the active reference. +- Less momentum. The campaign feeling fades; each derivative is a standalone moment rather than part of a coherent push. +- Coordination overhead extended. Owners and producers need to maintain focus across months. + +Fits. Evergreen flagship pieces with sustained traffic curves. Programs with smaller production capacity that cannot sustain concentrated cadence. + +### Indefinite cadence + +The pattern. Derivatives keep being created from the source as long as the source remains relevant. + +Strengths. + +- Maximum long-term value extraction. +- Adapts to audience response. Derivatives that perform well inform what to produce next; the program learns from the cross-format set's reception. + +Weaknesses. + +- Most programs cannot sustain indefinite attention to a single source. Discipline tends to decay. +- Risk of voice drift. Derivatives produced 12 months apart may have voice variation that the original launch cadence avoided. +- Less coherent campaign feel. Audiences see scattered derivatives over a long window without a clear narrative. + +Fits. Truly evergreen sources whose value compounds for years. Rare; usually reserved for major flagship pieces (defining manifestos, definitive research reports). + +--- + +## Pacing audits + +Match cadence to the source's traffic curve and the audience's attention rhythm. + +The source's traffic curve. + +- Sharp early traffic, fast decay. Trending-topic pieces, news-driven analysis. Concentrated cadence; the audience is paying attention for a short window. +- Sustained high traffic for weeks. Flagship reports on hot topics. Concentrated to mid-distributed cadence; the audience attention extends but eventually fades. +- Slow build, sustained traffic for months. Evergreen flagship pieces, definitive guides. Distributed cadence; the audience encounter is continuous over time. +- Sustained low traffic with occasional spikes. Reference pieces that get rediscovered. Indefinite cadence works if the production capacity supports it. + +The audience's attention rhythm. + +- Email subscribers. Engagement varies; sequences spaced 5-7 days work for most B2B; daily for high-engagement consumer audiences. +- Social audiences. Platform-specific. LinkedIn rewards 1-2 posts per week from program accounts; X rewards higher frequency; Instagram somewhere in between. +- Podcast audiences. Episodic; weekly cadence common; bi-weekly works for higher-production-effort shows. +- YouTube audiences. 1-2 videos per week typical for active channels; long-form video can be less frequent. + +The pacing decision. Match the source's traffic curve and the audiences' attention rhythm. If they conflict, the source's curve usually wins; the cross-format set's coherence depends on the source's authority window. + +--- + +## Sequencing and cadence per derivative type + +Some derivatives have natural sequencing within the rollout. + +Derivatives that should ship early. + +- Email teaser or preview email. Sets up the source's launch with the email audience. +- Social posts that announce the source. Visibility on launch day. +- Short-form video that introduces the topic. Algorithmic recommendation responds best when the content is fresh. + +Derivatives that should ship 1-3 weeks in. + +- First blog post in a series. The source piece is still drawing traffic; the blog post benefits from internal linking and the audience's continued interest. +- Webinar based on the source. Allows time for audience registration and promotion. +- First batch of social pull-quote posts. The source's themes are familiar; the pull quotes resonate. + +Derivatives that should ship 1-3 months in. + +- Podcast episode. Production cycle is longer; podcast audience overlap with source audience may be partial. +- Subsequent blog posts in a series. Distributed cadence; each post earns its own attention. +- Email sequence (if not the immediate teaser). The sequence develops the source's framework over time. + +Derivatives with flexible timing. + +- FAQ extractions and AI-search snippets. These can ship at source-launch or any time after; AI search citation accumulates over months. +- Ebook consolidation. Often ships 6-12 months after source pieces accumulate; the consolidation work itself takes time. + +--- + +## Common sequencing and cadence failures + +All-at-once dumping. A wave of 12 derivatives in 5 days. Audiences disengage by day 3; most derivatives produce little engagement. Cure: distributed cadence with audience-attention spacing. + +Source quietly publishing while derivatives ship loudly. The derivatives carry the launch but the source piece itself launches without the attention it deserves. Cure: source-first launch with promotion focused on the source; derivatives follow. + +Source publishing months after promised derivatives. Derivatives that previewed a coming source piece ship; the source publishes 4 months later. Audiences have lost connection. Cure: tighten production schedule or flip the sequencing to source-first. + +Cadence too aggressive for the audience. Email subscribers receiving daily emails for 2 weeks unsubscribe. Cure: match cadence to audience attention norms; email audiences typically tolerate 1-2 sends per week from a program. + +Cadence too slow. Distributed cadence stretched too long; by month 4, audiences have forgotten the source. Cure: bring cadence closer to source's traffic curve; consider indefinite cadence only when the source genuinely supports it. + +No sequencing plan. Derivatives ship as they happen to be ready, with no coordination. Cross-format set feels random; audiences see scattered touchpoints with no coherent narrative. Cure: even rough sequencing planning at production time produces better outcomes than no plan. + +--- + +## Methodology-level choices that stay in the public skill + +The three sequencing patterns, the three cadence patterns, the pacing audit, the per-derivative-type sequencing, the common failures. + +## Implementation choices that stay internal + +Specific calendar tooling. Specific automation that schedules derivatives across channels. Specific coordination workflows between producers and channel owners. Specific A/B testing of cadence variants. The team's own conventions for fast-track vs queued derivatives. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md b/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md new file mode 100644 index 0000000..70e61ac --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/source-piece-selection-criteria.md @@ -0,0 +1,125 @@ +# Source-piece selection criteria + +Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. The discipline that prevents repurposing capacity from being spent on pieces that will not extend cleanly across formats. + +Not every piece is worth repurposing. Selection is the first decision, and getting it wrong produces derivative work that feels forced, fails to engage on the new formats, and consumes capacity that would have produced better return on stronger source pieces. + +--- + +## Strong source-piece characteristics + +A piece that extends cleanly across formats usually has several of the following. + +Clear central argument or framework. The piece has a thesis, a framework, or a structured set of positions that survives translation. The reader of any derivative can extract the argument; the reader of the source can recognize it. + +Standalone sections. The piece's H2 sections work as standalone units. A reader who only sees one section can still get value; the section does not depend on the cumulative context of preceding sections to make sense. Pieces with this property produce blog-series and social-post derivatives easily. + +Travelable examples and case studies. The piece contains specific examples, case studies, or worked illustrations that can stand alone. These travel into video shorts, social posts, and podcast episodes as natural anchors. + +Audience overlap with target formats. The source's audience exists on the platforms where derivatives will live. A B2B technical whitepaper extends well into LinkedIn long-form posts and into podcast episodes; less well into TikTok shorts. + +Distinctive voice. The piece has voice characteristics specific enough that derivative voice can stay coherent. Pieces in generic voice produce derivatives that sound like AI-default; pieces in distinctive voice anchor derivatives to recognizable register. + +Accumulated demand. The source has demonstrated reader interest: traffic, links, mentions, shares, citations. Pieces with traction support derivatives because the demand is real; pieces without traction produce derivatives that draw on no underlying interest. + +Multi-angle topic. The topic has multiple angles, sub-questions, or applications. Pieces on narrow single-angle topics produce few derivatives; pieces on broader topics with sub-questions produce more. + +--- + +## Weak source-piece characteristics + +Pieces that resist repurposing usually have several of the following. + +Tightly-integrated argument. The piece is a layered argument where every section depends on the cumulative context. Extract any section and it loses meaning. Whitepapers with this structure (high-rigor analytical pieces) often resist clean derivative extraction; the value is in reading end-to-end. + +List-style without standalone weight. The piece is a list of items where individual items are not substantial enough to support derivatives. "Top 10 marketing tips" with one-paragraph items per tip cannot produce strong derivatives because no single item justifies a derivative piece. + +Narrative-arc dependence. The piece's value comes from the unfolding narrative; reading any segment alone misses the arc. Some narrative case studies and feature-style longform have this property. Derivatives can summarize but cannot replace. + +Audience-format mismatch. The source's audience does not exist (or exists thinly) on most target formats. A regulatory-technical whitepaper for compliance officers extends poorly to TikTok; the audience is not there. + +Generic voice. The source piece reads in default-AI or generic-content-marketing voice. Derivatives generated from a generic source compound the genericness. Without a distinctive source voice, derivatives drift further from any recognizable register. + +No demand signal. The source piece has not earned traffic, links, or shares. Repurposing rarely creates demand that did not exist; pieces without demand should be evaluated for whether they should have been published in the first place. + +Highly time-bound. The source piece is about a specific event, news cycle, or moment that will not be relevant in the cadence's timeframe. Derivatives that ship 4-6 weeks after the source may already be out of date. + +--- + +## The selection audit + +A short framework for evaluating a candidate source piece. + +1. Read the piece's central argument or framework. Can you state it in one sentence? If not, the piece may not extend cleanly. If yes, the argument is the spine that derivatives will extend. +2. Identify standalone sections. Which H2 sections work alone? If most sections work alone, blog-series and social derivatives are natural. If only one section works alone, fewer derivative formats fit. +3. List travelable elements. Specific examples, case studies, statistics, or claims that could anchor derivatives. Pieces with 5-10 travelable elements support multi-format extension; pieces with 0-2 do not. +4. Check audience-format overlap. For each candidate derivative format, is the source's audience present on the format? If most candidate formats fail this check, the source may not be a multi-format candidate. +5. Audit voice distinctiveness. Read three paragraphs from different sections. Could a reader who knows the brand identify this as the brand's work? If yes, derivatives have voice anchor. If no, derivatives will drift. +6. Check demand signal. Has the source earned traffic, links, mentions, or shares? Pieces without demand signal do not transmit demand to derivatives. +7. Estimate extraction yield. Given the above, how many derivative pieces could the source plausibly support? Pieces yielding 1-2 derivatives may not be worth a formal repurposing plan; pieces yielding 6-12 are clear repurposing candidates. + +--- + +## Pieces that should stay one-and-done + +Some pieces are valuable but resist repurposing. Recognizing them prevents wasted effort. + +Tightly-argued analytical whitepapers. Pieces whose value is in the cumulative argument. Often valuable as flagship content but produce few clean derivatives. The right disposition: ship the source piece; create one or two derivative pieces (a summary blog post, an email teaser); accept that most of the value is in the source itself. + +Highly specific case studies. Pieces about a single specific situation that does not generalize cleanly. The case is valuable; abstraction loses the specifics that gave the case its weight. The right disposition: ship the case study; create derivative pieces only where the case has clear teachable moments that travel. + +Time-bound editorial. Pieces about a specific event, news cycle, or moment. The piece may be valuable in the moment but the moment passes. The right disposition: ship; minimal repurposing during the moment; archive after. + +Highly visual source pieces. Pieces whose value is primarily in custom visuals (data dashboards, illustrated guides, complex diagrams). Text derivatives often cannot carry the visual value. The right disposition: derivative video and visual-format extensions only; text derivatives often underperform. + +Niche-audience pieces. Pieces for a small specific audience that does not exist on most other formats. The right disposition: minimal repurposing; the audience is concentrated where the source already published. + +--- + +## Tier-based selection + +Programs with regular flagship production benefit from explicit tiering of source pieces by repurposing intensity. + +Tier 1: Major flagship (1-3 per year). The source piece is treated as the spine of a multi-month repurposing campaign. 8-15 derivative pieces planned. Cross-format extension covers blog series, email sequence, webinar, podcast, social waves, video shorts, AI-search extractions. Capacity allocation is significant; the source's value is being maximally extracted. + +Tier 2: Standard flagship (4-12 per year). Source piece supports 4-8 derivative pieces. Cross-format extension covers a subset of formats: blog series or email sequence (not both), social posts, FAQ extractions for AI search. Capacity allocation is moderate. + +Tier 3: Routine substantive piece (12-50 per year). Source piece supports 1-3 derivative pieces. Often a social-post wave, an email mention, an internal-link refresh on related pieces. Minimal additional capacity. + +Tier 4: One-and-done (the majority of pieces). Source piece publishes; appears in newsletter once; shares on social once; no derivative pieces planned. Capacity allocation only on the source. + +The tiering discipline. Most programs have too few Tier 1 and Tier 2 pieces and too many Tier 3 and Tier 4 pieces masquerading as flagship work. The audit shifts capacity allocation toward the few pieces that genuinely warrant multi-format extension. + +--- + +## When a piece grows into stronger source-piece status + +Some pieces start as Tier 4 and earn promotion based on performance. + +The signal. A piece that was published as routine starts drawing significant traffic, earning links, getting mentioned externally, or producing reader engagement disproportionate to its production tier. + +The response. Promote the piece into a higher tier. Plan derivatives. Some of the strongest source pieces in mature programs are pieces that performed unexpectedly well after publication; recognizing them quickly extracts the additional value. + +The audit. Quarterly review of pieces' performance. Pieces showing strong demand that have not been repurposed are candidates for retroactive extraction; pieces showing weak demand that were originally tiered as flagship may need their derivative plans reduced or canceled. + +--- + +## Common selection failures + +Repurposing every piece. Treating all pieces as repurposing candidates spreads capacity thin. Most programs benefit from concentrating capacity on 10-20% of pieces and accepting one-and-done for the rest. + +Repurposing the wrong pieces. Selecting source pieces because they are easy (recent, fresh in mind) rather than because they are strong source-piece candidates. The selection audit catches this. + +Ignoring weak-source-piece signals. Pushing through repurposing on pieces with tightly-integrated argument, list-style structure, or no demand signal produces derivatives that fail. + +Static tiering. Pieces tiered at production never get re-tiered based on performance. Strong sleeper pieces never get repurposed; weak flagship pieces consume planned derivative capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The strong vs weak source-piece characteristics, the selection audit, the one-and-done dispositions, the tiering framework, the dynamic-tiering discipline, the common selection failures. + +## Implementation choices that stay internal + +Specific scoring rubrics the team uses to score source pieces. Specific dashboards that surface high-performing pieces for retroactive promotion. Specific calendar templates that allocate repurposing capacity by tier. The team's own thresholds for when a routine piece warrants Tier 2 promotion. These vary by team and program shape. diff --git a/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md b/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md new file mode 100644 index 0000000..8435836 --- /dev/null +++ b/dist/pi/.agents/skills/content-repurposing/references/voice-consistency-across-formats.md @@ -0,0 +1,146 @@ +# Voice consistency across formats + +What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem and the discipline that prevents it. + +Voice is the most visible casualty of careless repurposing. The source piece may have specific voice characteristics; derivatives generated without strong voice discipline drift toward AI-default or platform-default register. Audiences detect the drift even when they cannot articulate it; the cross-format set reads as work from different brands rather than as a coherent program. + +--- + +## What stays constant + +The brand-voice elements that should survive every format adaptation. + +The brand's POV on the topic. If the source piece argues a specific position, the derivatives carry the same position. A derivative that hedges where the source committed, or that takes a different angle than the source, breaks the cross-format coherence. + +Distinctive vocabulary. Brand-specific terms, framings, and phrasings that signal "this is from this brand." If the source uses a particular word for a concept, derivatives use the same word. If the source has a recognizable phrase, derivatives carry the phrase. + +Level of conviction or hedging. Brands have characteristic stance positions. Some brands commit; some hedge thoughtfully; some are confrontational. The derivatives carry the brand's stance pattern even when format conventions might pull toward different stance defaults. + +Audience-respect register. Brands address audiences in specific ways: peer-to-peer, expert-to-novice, alongside-the-reader. The register stays consistent across formats; derivatives that suddenly talk down to the audience break voice coherence. + +Anti-patterns the brand avoids. If the brand does not use particular framings (motivational filler, generic-content-marketing voice, hype-driven language), derivatives also avoid them. Anti-pattern adherence is part of voice. + +--- + +## What adapts per format + +Voice elements that should adjust to the medium. + +Sentence length and structure. Spoken voice differs from written. Email voice differs from blog voice. Social-post voice differs from email voice. The brand's voice characteristics survive through these adaptations, but the surface-level sentence patterns change. + +- Print: medium sentences with occasional layered constructions. +- Email: shorter sentences, more direct address. +- Spoken (podcast, video): conversational rhythm with natural pauses and asides. +- Social: tight phrasing in first lines, paragraph breaks frequent. + +Density. Visual formats can carry less per minute than text formats. A short video cannot fit the density of a paragraph; the same point in video form has more breathing room. + +Conversational vs declarative register. Podcasts are conversational; whitepapers are declarative. The brand's POV stays the same in both; the framing register adapts. + +Direct-address frequency. "You" usage varies by format. Emails often use "you" frequently; whitepapers may use "the reader" or "marketers" more often. The shift is appropriate; pulling email voice into a whitepaper or vice versa would feel off. + +Visual element usage. Some formats use visuals heavily (social, video); others rely on text (email, long-form). Voice adapts to whether visuals are doing some of the work. + +--- + +## The voice audit per derivative + +A short framework for verifying voice consistency. + +1. Read or watch the derivative as if encountering it cold. Could a reader who knows the brand identify this as the brand's work? If yes, voice is working. +2. Compare to the source piece. Does the derivative carry the source's POV, vocabulary, and stance? Where it differs, is the difference appropriate format adaptation or unwanted drift? +3. Check against the brand's voice anti-patterns. Is the derivative slipping into framings the brand normally avoids? AI-default voice often slips in through derivatives. +4. Check sentence-level patterns. Sentence length, paragraph length, direct-address frequency, vocabulary. Are they format-appropriate but brand-recognizable? +5. Read aloud (for written derivatives) or read the script (for spoken derivatives). Does it sound like the brand's voice as the brand would speak it? + +The voice audit is one of the easiest to skip and one of the most consequential. Pieces that pass everything else but fail voice audit damage the cross-format coherence. + +--- + +## The AI-repurposing voice problem + +AI-assisted repurposing is particularly prone to voice drift. + +The pattern. The source piece has specific voice characteristics. AI generation of derivatives is asked to "summarize this for LinkedIn" or "turn this into emails." The AI produces derivatives that are technically related to the source but written in AI-default voice rather than the source's distinctive voice. + +Why it happens. AI generation regresses to model defaults unless the writer actively pulls it back. Without strong voice prompts, the derivatives sound like the AI's voice using the source's content. Multiple derivatives generated without voice anchor compound the drift; by the tenth derivative the cross-format set has lost the source's voice entirely. + +The cure. + +- Voice guidelines as prompt input. Every AI generation includes the brand voice guidelines as context. Generic prompts produce generic outputs. +- Sample text as voice anchor. Feed the AI 2-3 paragraphs of the source piece in their original voice. AI mimics what it sees more than what it is told. +- Per-derivative voice review. Each derivative gets a voice audit. Drift detected gets revision. The audit is non-negotiable. +- Rewrite the bland. Any sentence that could appear in any other piece on the topic gets rewritten in voice. Voice lives in the specific. + +See `ai-content-collaboration` for the broader voice-preservation discipline that applies across AI-assisted content workflows. The repurposing-specific application is that voice drift compounds across multiple derivatives in ways that single-piece AI generation does not. + +--- + +## When format conventions pull against brand voice + +Sometimes a format's conventions push toward voice that does not match the brand. + +LinkedIn motivational tone. LinkedIn rewards a particular kind of motivational and personal-narrative content. Brands with crisp analytical voice may resist the convention; the right answer is usually to maintain voice rather than to drift into LinkedIn-default motivational tone, even at cost of platform-specific engagement. + +TikTok's high-energy delivery. TikTok rewards high-energy short-form delivery. Brands with measured analytical voice may not fit naturally; the right answer may be to skip TikTok rather than to produce content that sounds wrong for the brand. + +Podcast-host conversational warmth. Some podcast styles reward warm conversational delivery; a brand with confrontational analytical voice may struggle to produce derivatives that fit. The right answer may be to format-fit (use a different format) or to produce derivatives that hold the brand's voice even at engagement cost. + +The discipline. Format-fit decisions are upstream of voice-adaptation decisions. If a format genuinely cannot accommodate the brand's voice, skipping the format is sometimes the right answer; voice integrity matters more than universal cross-format presence. + +--- + +## Voice prompts for AI-assisted repurposing + +When AI generates derivatives, the prompts should carry voice instructions. + +Components of a voice prompt. + +- 2-3 paragraphs of the source piece in original voice as anchor. +- A short voice description (3-5 specific characteristics). +- A short anti-pattern list (3-5 framings the brand avoids). +- Per-format adjustments (sentence length, register, direct-address frequency). + +A worked prompt example pattern. "The source piece below is in the brand's voice. Convert it into [target format]. The voice characteristics to preserve: [specific characteristics]. The anti-patterns to avoid: [specific anti-patterns]. The format adaptations: [format-specific]. Source piece: [text]." + +The discipline is including the voice instructions in every derivative generation, not assuming the AI will infer voice from the source alone. AI tools differ in how well they infer voice from samples; the safest discipline is explicit voice instruction. + +--- + +## Voice consistency across multiple writers or AI generators + +Programs with multiple writers or AI generators producing derivatives have a multi-source voice drift problem. + +The risk. Writer A produces three derivatives in slightly different voice from writer B's four derivatives, plus AI generates two more in default voice. The cross-format set has three voice variants, none of them quite the source's voice. + +The discipline. + +- Single voice owner. One person reviews all derivatives in the cross-format set for voice consistency. Catches drift across writers. +- Voice library. Documented brand voice with examples; all writers and AI generators reference the same library. +- Calibration sessions. Periodically, multiple writers (or writers plus the editorial lead) review derivatives together and reconcile voice expectations. + +Programs with sophisticated voice discipline can run multi-writer derivative production without losing voice; programs without discipline produce voice variants that audiences notice. + +--- + +## Common voice failures in repurposing + +AI-default drift. Derivatives sound like the AI's voice rather than the brand's voice. Cure: stronger voice prompts; per-derivative review. + +Platform-default drift. Derivatives sound like the platform's default register rather than the brand's voice. Cure: voice-over-platform-fit discipline; sometimes skip the platform. + +Cross-derivative drift. Each derivative is fine alone but the cross-format set reads as voice variants. Cure: single voice owner across the set. + +Source-voice loss. Derivatives carry the source's content but not the source's voice characteristics. Cure: voice anchor with sample text from the source. + +Voice-only-on-source. The source piece has voice; the derivatives default to generic. Cure: voice discipline applies to derivatives, not just to the source. + +--- + +## Methodology-level choices that stay in the public skill + +The constant-vs-adapting voice elements, the voice audit, the AI-repurposing voice problem and its cure, the format-vs-voice tension, the multi-writer voice discipline, the common voice failures. + +## Implementation choices that stay internal + +Specific voice-prompt templates per AI tool. Specific voice-library documentation in the team's writing system. Specific calibration session formats. Specific reviewer dashboards that surface cross-derivative voice variation. The team's own conventions for voice-vs-format tradeoffs. These vary by team, AI tooling, and brand voice maturity. diff --git a/dist/pi/.agents/skills/content-strategy/SKILL.md b/dist/pi/.agents/skills/content-strategy/SKILL.md new file mode 100644 index 0000000..dce5d9e --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/SKILL.md @@ -0,0 +1,211 @@ +--- +name: content-strategy +description: "Develop a content strategy covering editorial positioning, content pillars, formats, calendar, governance, and topical authority planning. Use this skill whenever the user wants to plan a content program, define content pillars, build an editorial calendar, structure topic clusters, set up content governance, or align content production with broader brand and SEO goals. Triggers on content strategy, content plan, editorial strategy, content pillars, content calendar, editorial calendar, topical authority, topic clusters, content governance, content roadmap, content production. Also triggers when the user is about to start producing content without a strategic plan." +category: strategy-and-discovery +catalog_summary: "Editorial strategy, content calendar, topical authority planning" +display_order: 5 +--- + +# Content Strategy + +Plan what content to produce, why, when, and how. Stack-agnostic. Works for blogs, knowledge bases, marketing sites, newsletters, and product content surfaces. + +This skill is the strategic layer. Tactical execution sits in `content-and-copy`, `landing-page-copy`, and `email-sequences`. SEO-driven content planning sits in `seo-keyword`. This skill stitches those together into a coherent program. + +--- + +## When to use + +- Planning a new content program or relaunching an existing one +- Defining editorial positioning and content pillars +- Building an editorial calendar +- Structuring topic clusters and content hubs +- Establishing content governance (review, approval, lifecycle) +- Aligning content with broader brand and revenue goals + +## When NOT to use + +- Writing specific content pieces (use `content-and-copy`) +- Writing landing pages or sales copy (use `landing-page-copy`) +- Writing email sequences (use `email-sequences`) +- Pure keyword research (use `seo-keyword`, then return here for strategic planning) +- Auditing existing content for keep/update/delete decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- Brand positioning and audience (from `brand-discovery` or `creative-brief`) +- Business goals the content needs to serve (traffic, leads, brand authority, retention) +- Existing content inventory (if any) +- Keyword research output (from `seo-keyword`) if SEO-driven +- Production capacity (writers, budget, cadence) + +If brand positioning is unclear, run `brand-discovery` first. If audience is undefined, do that work before strategy. + +--- + +## The framework: 5 layers + +A content strategy has five layers. Skip layers and the program drifts. + +### 1. Editorial positioning + +What this content program stands for. The "why we write" statement. + +Components: +- Mission. Why this content exists. One sentence. +- Audience. Who it serves. Specific. +- Promise. What readers get from us they cannot get elsewhere. +- Distinction. What makes this content different from the 50 other publications in the same space. + +Example structure: + +> We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +A strong editorial positioning forces choices. If you cannot complete the sentence, the positioning is too vague. + +### 2. Content pillars + +The 3 to 5 themes the program owns. Every piece of content belongs to a pillar. + +Per pillar, define: +- Theme. One sentence describing the topic territory. +- Why we own it. Audience need + brand authority + competitive opportunity. +- Sub-topics. 5 to 15 sub-topics that fit under the pillar. +- Cornerstone content. The 1 to 2 pieces that anchor the pillar (long-form, comprehensive, link-worthy). +- Supporting content. Articles, videos, tools, comparisons that reinforce and link to the cornerstone. + +Pillar selection criteria: +- Audience cares about it (research-backed, not assumed) +- Brand has credibility or can earn it +- Topical authority is achievable (you can plausibly become a top-3 source) +- Connects to revenue (directly or indirectly) +- Distinguishes you from competitors + +3 to 5 pillars is the sweet spot. Fewer than 3 risks brittleness. More than 5 dilutes focus. + +### 3. Content formats and types + +The shapes the content takes. + +Format dimensions: + +- Length. Short (under 500 words), medium (500 to 1500), long (1500 to 3000), epic (3000+) +- Depth. Surface (overview) vs. deep (comprehensive) +- Type. Article, guide, comparison, listicle, case study, interview, data study, tool, video, podcast, newsletter, social +- Originality. Aggregation (summarizing existing knowledge) vs. original research (new data or insight) +- Evergreen vs. timely. Lasting value vs. moment-driven + +Format selection criteria: + +- Match the audience's preferred consumption (do they read, watch, listen?) +- Match the topic (some topics demand depth; others demand brevity) +- Match production capacity +- Match distribution channels (LinkedIn favors short; YouTube favors video; SEO favors long evergreen) + +A content program typically has 3 to 5 formats it returns to consistently. More than that fragments production and brand recognition. + +### 4. Editorial calendar + +When content publishes. + +Cadence options: + +- High frequency (3+ pieces per week): builds momentum, requires significant production capacity +- Medium frequency (1 to 2 per week): sustainable for most teams, builds steady audience +- Low frequency (1 to 4 per month): each piece must be high-impact; longer production cycles +- Burst-then-pause (10 pieces in a month, then 3 months off): launches and campaigns + +Calendar structure: + +- Pillar rotation. If you have 4 pillars and publish weekly, each pillar gets one piece per month. +- Content type mix. Within a month, blend types (e.g., 2 articles + 1 case study + 1 video). +- Timely opportunities. Reserve flex slots for newsjacking, seasonal content, launches. +- Updates and refreshes. Plan time for updating existing high-performing content. + +Common failure: publishing whatever happens to get written. Without a calendar, the program drifts toward the topics easiest to write, not the ones the audience needs most. + +### 5. Governance and lifecycle + +How content gets made, reviewed, published, measured, and retired. + +Production workflow: + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +Per stage, define: + +- Who owns it +- What inputs they need +- What outputs they produce +- What the quality bar is +- How long it should take + +Roles: + +- Editorial lead. Owns positioning, calendar, quality bar. +- Writers. Produce drafts. May be in-house, freelance, or AI-assisted. +- Subject matter experts. Provide expertise, review for accuracy. +- Editors. Polish, ensure voice consistency, fact-check. +- SEO lead. Keyword optimization, internal linking, schema. +- Publishers. Ship the content (CMS, scheduling, distribution). + +Lifecycle decisions: + +- Update cadence. Top-performing evergreen content reviewed every 6 to 12 months. +- Retire criteria. Content that no longer serves the audience or hurts the site (use `seo-content-audit`). +- Republishing. Updated content republished as fresh, not buried as an update. + +--- + +## Workflow + +1. Confirm inputs. Brand positioning, audience, business goals, capacity. If any are missing, surface that first. +2. Draft editorial positioning. Mission, audience, promise, distinction. Stress-test the positioning by trying to complete the "We help X" sentence. +3. Define content pillars. 3 to 5. Each with a theme, justification, sub-topics, and planned cornerstone content. +4. Choose formats. 3 to 5 formats the program returns to consistently. +5. Build the calendar. Cadence, pillar rotation, format mix, flex slots. +6. Set up governance. Roles, workflow, quality bar, lifecycle rules. +7. Document. Use the template in [`references/content-strategy-template.md`](references/content-strategy-template.md). +8. Operationalize. Set up the editorial calendar in whatever tool the team uses (CMS, Notion, Airtable, etc.). + +--- + +## Failure patterns + +- Strategy without capacity. A 3-piece-per-week plan with one part-time writer fails. Match strategy to actual production capacity. +- Pillars chosen for SEO alone. Pillars must serve the audience and the brand, not just keyword opportunity. SEO is a downstream filter, not the strategy itself. +- Too many pillars. 7 pillars dilute the brand. The audience cannot remember what you stand for. +- Calendar without governance. Content gets produced but quality drifts. Without a quality bar, the program loses authority. +- No update plan. Top-performing content goes stale. Competitors with fresher versions overtake. +- Vanity metrics. Pageviews and follower counts without conversion tracking. Define what success looks like in business terms. +- Strategy that lives in a doc. A strategy document that doesn't translate to the editorial calendar and the production workflow is decoration. Operationalize or it doesn't exist. + +--- + +## Output format + +Default output is a strategy document at `content-strategy.md` plus an editorial calendar in whatever tool the team uses. + +Strategy document structure: +1. Editorial positioning +2. Content pillars (3 to 5, each detailed) +3. Formats +4. Calendar (cadence and structure, not the specific items) +5. Governance (roles, workflow, lifecycle) +6. Measurement plan (metrics, review cadence) +7. Production capacity and budget + +Editorial calendar (separate, ongoing): +- One row per planned content piece +- Columns for: title, pillar, format, target keyword (if SEO-driven), publish date, owner, status + +--- + +## Reference files + +- [`references/content-strategy-template.md`](references/content-strategy-template.md) - Strategy document template. +- [`references/editorial-calendar-template.md`](references/editorial-calendar-template.md) - Spreadsheet column definitions and calendar structure. diff --git a/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md b/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md new file mode 100644 index 0000000..2cee093 --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/references/content-strategy-template.md @@ -0,0 +1,259 @@ +# Content Strategy: [Brand or Site Name] + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Owner: [Editorial lead] +Review cadence: [Quarterly / Annually] + +--- + +## Editorial positioning + +### Mission + +[One sentence. Why this content program exists.] + +### Audience + +Primary: +[Specific audience segment with the depth of detail your discovery work earned.] + +Secondary: +[Additional segments, if any.] + +Anti-personas: +[Who this content is NOT for.] + +### Promise + +[What readers get from us that they cannot get elsewhere. One paragraph.] + +### Distinction + +We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +--- + +## Content pillars + +### Pillar 1: [Pillar name] + +- Theme: [One sentence] +- Why we own it: + - Audience need: [Specific need] + - Brand authority: [Why we're credible] + - Competitive opportunity: [Why this is winnable] +- Sub-topics (5 to 15): + - [Sub-topic] + - [Sub-topic] + - [Sub-topic] +- Cornerstone content (the 1 to 2 pieces that anchor this pillar): + - [Title or working title] + - [Title or working title] +- Supporting content (article types that link back to cornerstone): + - [Type and quantity, e.g., "5 deep-dive articles per quarter"] + +### Pillar 2: [Pillar name] +[Same structure] + +### Pillar 3: [Pillar name] +[Same structure] + +[Continue for all pillars; aim for 3 to 5] + +--- + +## Formats + +The program returns to these formats consistently. + +### Format 1: [Name, e.g., "In-depth guides"] +- Description: [What it is] +- Length: [Word count or duration range] +- Cadence: [How often we produce one] +- Use case: [When this format wins] + +### Format 2: [Name] +[Same structure] + +### Format 3: [Name] +[Same structure] + +[Continue for all formats; aim for 3 to 5] + +--- + +## Editorial calendar structure + +### Cadence + +Frequency: [N pieces per week/month] + +Reasoning: [Why this cadence; what it can sustainably support] + +### Pillar rotation + +[How pillars rotate through the calendar. Example: 4 pillars, weekly publishing, each pillar gets one piece per month.] + +### Format mix + +[Within a typical month, what's the format breakdown?] + +Example: +- 2 articles +- 1 case study or interview +- 1 longer guide or data study +- Plus: 1 newsletter (ongoing, separate cadence) + +### Flex slots + +[How much of the calendar is reserved for timely content, news jacking, or campaign launches?] + +Typical: 70% planned, 20% flex, 10% updates to existing content. + +### Updates and refreshes + +[Plan for refreshing top-performing content. Typically every 6 to 12 months for evergreen pillars.] + +--- + +## Governance + +### Roles + +\| Role \| Owner \| Responsibility \| +\|---\|---\|---\| +\| Editorial lead \| [Name] \| Strategy, calendar, quality bar \| +\| Writer (in-house or freelance) \| [Name(s) or agency] \| Drafts \| +\| Subject matter expert \| [Name(s)] \| Expertise, accuracy review \| +\| Editor \| [Name] \| Polish, voice consistency, fact-check \| +\| SEO lead \| [Name] \| Keyword optimization, internal linking, schema \| +\| Publisher \| [Name] \| CMS publication, scheduling, distribution \| + +### Production workflow + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +\| Stage \| Owner \| Inputs \| Outputs \| Quality bar \| Time estimate \| +\|---\|---\|---\|---\|---\|---\| +\| Idea \| \| \| \| \| \| +\| Brief \| \| \| \| \| \| +\| Outline \| \| \| \| \| \| +\| Draft \| \| \| \| \| \| +\| Edit \| \| \| \| \| \| +\| Review \| \| \| \| \| \| +\| Publish \| \| \| \| \| \| +\| Measure \| \| \| \| \| \| +\| Update or retire \| \| \| \| \| \| + +### Quality bar + +Every piece of published content meets these standards: +- [ ] Aligned with a defined content pillar +- [ ] Targets a specific audience need +- [ ] Voice and tone consistent with brand standards +- [ ] Factually accurate (sources cited where appropriate) +- [ ] SEO basics handled (title, meta, headers, internal links) +- [ ] Schema applied for the content type +- [ ] Edited by someone other than the writer +- [ ] Reviewed by the editorial lead + +### Lifecycle rules + +- Update trigger: A top-performing evergreen piece reviewed when [trigger, e.g., "stats are 12 months old" or "competitive landscape shifts"] +- Retire trigger: A piece is retired (deleted, redirected, or merged) when [trigger, e.g., "no traffic for 12 months and no backlinks"] +- See also: `seo-content-audit` for the keep/update/merge/redirect/delete framework + +--- + +## Measurement plan + +### Primary metrics + +\| Metric \| Target \| Reporting cadence \| +\|---\|---\|---\| +\| Organic traffic \| \| Monthly \| +\| Email subscribers \| \| Monthly \| +\| Conversions from content \| \| Monthly \| +\| [Custom metric] \| \| \| + +### Secondary metrics (signals) + +- Engaged sessions (sessions over 60 seconds) +- Scroll depth on long-form content +- Internal click-through from articles to commercial pages +- Backlinks earned per piece +- Time on page distribution +- Returning reader rate + +### Review cadence + +- Weekly: Calendar status check +- Monthly: Performance metrics review, calendar adjustments +- Quarterly: Strategy review, pillar performance, capacity check +- Annually: Full strategy refresh, audience research re-validation + +--- + +## Production capacity and budget + +### Capacity + +- Writers: [number, FTE or freelance, hours per week] +- Editors: [number, hours per week] +- Subject matter experts: [availability] +- Designers/illustrators (if needed): [availability] + +### Budget + +- Internal labor: [budget] +- Freelance writers: [per piece or per month] +- Subject matter expert honoraria (if external): [per piece] +- Imagery, illustration, video: [per piece or monthly] +- Tools and platforms: [monthly] + +### Output capacity at this budget + +[Realistic monthly output given the budget. Better to plan conservatively and exceed it than over-promise and under-deliver.] + +--- + +## Distribution + +Content does not earn its audience by being published. List the distribution channels and the standard process for promoting each piece. + +### Channels + +- Owned: site, email, social profiles +- Earned: PR, partnerships, expert mentions +- Paid (if budget): boosted social, sponsored newsletter slots + +### Per-piece distribution checklist + +When a new piece publishes: + +- [ ] Posted to social channels with [N] variations +- [ ] Included in next newsletter +- [ ] Sent to relevant internal stakeholders for sharing +- [ ] Outreach to [N] external mentions or backlink targets +- [ ] Submitted to relevant communities (forums, niche aggregators) +- [ ] Internal link added from [related cornerstone content] + +--- + +## Open questions + +[Things that still need to be decided before this strategy is fully operational.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial strategy \| diff --git a/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md b/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md new file mode 100644 index 0000000..15509c3 --- /dev/null +++ b/dist/pi/.agents/skills/content-strategy/references/editorial-calendar-template.md @@ -0,0 +1,214 @@ +# Editorial Calendar Template + +A spreadsheet column definition and calendar structure for content planning. Use as a setup spec for a new editorial calendar in any tool (Sheets, Airtable, Notion, Linear, Asana). + +The calendar is not the strategy. The calendar is the strategy made operational. If a strategy decision is missing, the calendar will reveal it. + +--- + +## Calendar structure + +### Single source of truth + +The editorial calendar is one document. Not five. If the team uses multiple tools (writing in Notion, scheduling in Buffer, etc.), one tool is the source of truth and the others mirror it. + +The source of truth answers, at a glance: + +- What is being published this week? +- What is in production right now? +- What is committed for the next quarter? +- What is the backlog? +- Who owns each piece? + +--- + +## Required columns + +Every row is one piece of content. Every column below is required. + +\| Column \| Type \| Description \| +\|---\|---\|---\| +\| ID \| Text or auto-number \| Unique identifier per piece. Used in cross-references. \| +\| Title (working) \| Text \| Working title. Final title can change at publish. \| +\| Type \| Pick list \| Article / guide / case study / video / podcast / email / social series / landing page / etc. \| +\| Topic cluster \| Pick list \| Which content cluster this piece belongs to (from the strategy doc). \| +\| Stage of funnel \| Pick list \| Awareness / Consideration / Decision / Retention / Advocacy. \| +\| Primary audience \| Pick list \| Maps to defined segments. \| +\| Primary keyword \| Text \| The query target if SEO-relevant. \| +\| Search intent \| Pick list \| Informational / commercial / navigational / transactional. (See `seo-keyword/references/intent-classification-guide.md`.) \| +\| Primary CTA \| Text \| What action should the reader take? \| +\| Channels \| Multi-select \| Web, email, organic social, paid, partnerships. \| +\| Owner (writer) \| Person \| Who drafts. \| +\| Editor \| Person \| Who reviews. \| +\| Reviewer (SME) \| Person \| Subject matter expert if needed. \| +\| Approver \| Person \| Who signs off before publish. \| +\| Status \| Pick list \| See status workflow below. \| +\| Brief due date \| Date \| When the brief should be ready. \| +\| Draft due date \| Date \| When the draft should be ready. \| +\| Edit due date \| Date \| When edits should be done. \| +\| Publish date (target) \| Date \| The intended publish date. \| +\| Publish date (actual) \| Date \| When it actually went live. \| +\| Brief link \| URL \| Link to the content brief document. \| +\| Draft link \| URL \| Link to the working draft. \| +\| Final link \| URL \| Live URL after publish. \| +\| Performance notes \| Text \| Updated 30 / 60 / 90 days post-publish. \| + +--- + +## Optional but recommended columns + +\| Column \| Description \| +\|---\|---\| +\| Estimated effort (hours) \| For capacity planning. \| +\| Tag(s) \| Cross-cutting tags beyond cluster (e.g., "originals research," "thought leadership," "evergreen"). \| +\| Related pieces \| IDs of companion pieces (series, follow-ups, redirects). \| +\| Distribution plan link \| Specific plan for how this piece is amplified post-publish. \| +\| Repurpose plan \| What this becomes downstream (newsletter, social cuts, video). \| +\| Source / inspiration \| Where the idea came from (data, customer ask, competitor gap, etc.). \| +\| Cost \| If freelance or paid placement. \| + +--- + +## Status workflow + +Every piece moves through these statuses, in this order. + +\| # \| Status \| Meaning \| Exit criteria \| +\|---\|---\|---\|---\| +\| 1 \| Idea \| Captured but not committed. \| Idea passes the prioritization screen. \| +\| 2 \| Backlog \| Committed for some future quarter. \| Scheduled for a specific quarter. \| +\| 3 \| Scheduled \| Targeted for a publish week. \| Brief assigned. \| +\| 4 \| In brief \| Brief being written. \| Brief approved. \| +\| 5 \| In draft \| Writer is drafting. \| Draft submitted to editor. \| +\| 6 \| In edit \| Editor reviewing. \| Edits accepted by writer. \| +\| 7 \| In review \| SME and approver reviewing. \| All approvals received. \| +\| 8 \| Ready to publish \| Final, scheduled in CMS. \| Publish date arrives. \| +\| 9 \| Published \| Live. \| (Terminal) \| +\| 10 \| Killed \| Decided not to ship. \| (Terminal, with reason recorded) \| + +### Why this matters + +If 30 pieces are sitting in "In draft" for 6 weeks, the bottleneck is writers. If 20 are in "In review," the bottleneck is approvers. The calendar exposes pipeline health, not just publish dates. + +--- + +## Calendar views + +The same data, sliced different ways. Each view answers a different question. + +### Calendar view (by week) + +Columns: weeks. Rows: channels (web, email, social). + +Used for: planning rhythm, spotting overlap and gaps. + +### Pipeline view (by status) + +Columns: status. Rows: pieces. + +Used for: identifying bottlenecks. + +### Owner view (by writer / editor) + +Columns: people. Rows: pieces. + +Used for: workload balancing. + +### Cluster view (by topic cluster) + +Columns: clusters. Rows: pieces in pipeline + already published. + +Used for: ensuring topical authority is being built coherently. + +### Funnel view (by funnel stage) + +Columns: stage. Rows: pieces. + +Used for: ensuring balance across funnel. + +### Performance view (post-publish) + +Columns: traffic, conversions, time on page, social shares. Rows: published pieces. + +Used for: retrospective and topic prioritization for next cycle. + +--- + +## Cadence rituals + +The calendar is reviewed on a rhythm. + +\| Ritual \| Cadence \| Attendees \| Purpose \| +\|---\|---\|---\|---\| +\| Daily standup \| Daily, 15 min \| Editorial team \| What is shipping today, blockers. \| +\| Weekly editorial planning \| Weekly \| Content lead + writers \| Confirm next 2 weeks, surface blockers, accept new ideas. \| +\| Monthly review \| Monthly \| Content team + marketing lead \| Look at last month's pipeline, performance, and adjust the next month. \| +\| Quarterly planning \| Quarterly \| Content team + cross-functional \| Plan the next quarter's content based on strategy and last quarter's data. \| +\| Annual review \| Annually \| All stakeholders \| Review the year's themes, performance, and rebuild the strategy. \| + +--- + +## Capacity planning + +Use the calendar to plan capacity, not just track output. + +### Throughput math + +- Available writer time per week: writers × hours allocated to writing +- Average effort per piece: hours from "Idea" to "Ready to publish" +- Throughput: available time ÷ effort + +If planned output exceeds throughput, the calendar will reveal it as drift (slipped dates, deferred backlog). + +### Buffer + +Real teams hit 70-80% of planned throughput. Plan to 70%. Treat the remaining 30% as buffer for inevitable surprises (priority shifts, sick days, longer-than-expected reviews). + +--- + +## Backlog management + +The backlog is not a wishlist. It is a curated set of committed-but-not-scheduled ideas. + +- Cap the backlog at 3-6 months of throughput. Beyond that, ideas go stale. +- Re-rank quarterly using the strategy doc's prioritization criteria. +- Kill backlog items that no longer match the strategy. Killing is a feature, not a failure. + +--- + +## Killed pieces + +When a piece is killed, record: + +- Date +- Reason (strategy shifted, owner left, evidence the piece would not perform, redundant with another piece) +- What happens to the brief or partial draft (archive, salvage for another piece, delete) + +Killed pieces inform future filtering. + +--- + +## Performance review + +For every published piece, update the calendar with performance at 30 / 60 / 90 days. Capture: + +- Sessions / pageviews +- Conversion events (CTAs clicked, signups, purchases) +- Time on page or read depth +- Social shares +- Backlinks earned +- Notes on what worked or did not + +Aggregate quarterly to inform the next quarter's plan. + +--- + +## Sign-off + +Calendar setup approved by: + +- Content lead: [Name, date] +- Marketing lead: [Name, date] +- Tooling owner: [Name, date] + +Calendar lives at: [URL] diff --git a/dist/pi/.agents/skills/cost-optimization/SKILL.md b/dist/pi/.agents/skills/cost-optimization/SKILL.md new file mode 100644 index 0000000..2f44efb --- /dev/null +++ b/dist/pi/.agents/skills/cost-optimization/SKILL.md @@ -0,0 +1,339 @@ +--- +name: cost-optimization +description: "Audit and reduce infrastructure and tooling costs without sacrificing reliability or velocity. Use this skill when reviewing monthly cloud or SaaS spend, finding unused resources, rightsizing infrastructure, negotiating vendor contracts, deciding what to consolidate, or planning for budget cuts. Triggers on cost optimization, cloud spend, SaaS spend, rightsizing, unused resources, FinOps, infrastructure audit, vendor consolidation, budget cut, cost review. Also triggers when finance flags rising costs or when a contract renewal is up." +category: cross-cutting +catalog_summary: "Infrastructure spend audits, rightsizing, contract negotiation" +display_order: 5 +--- + +# Cost Optimization + +Audit cloud, SaaS, and infrastructure spend. Cut what's not earning its keep. Rightsize what's oversized. Negotiate what's negotiable. Without breaking what works. + +--- + +## When to use + +- Quarterly or annual cost review +- Finance flags rising spend +- Vendor contract renewal coming up +- Budget cut required +- New leadership wants the numbers +- Migrating between providers (cost is part of the case) +- Audit before scaling significantly (catch waste before it scales) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Performance issues that happen to involve infrastructure (use `performance-optimization`) +- Vendor evaluation for a new purchase (use `vendor-evaluation`) +- Personnel or org costs (out of scope for this skill) + +--- + +## Required inputs + +- Current cost (monthly, ideally for the last 12 months) +- Cost broken down by service or vendor +- Inventory of cloud resources (instances, databases, storage, etc.) +- Inventory of SaaS subscriptions +- Owners per cost line (who decided to spend this, who uses it) +- Constraints (compliance, performance, contract terms) + +--- + +## The framework: 5 levers + +Every cost optimization opportunity falls into one of these levers. + +### Lever 1: Eliminate + +Stop paying for things that aren't used. + +- Idle resources (instances, databases, environments running but unused) +- Subscriptions where no one logs in +- Duplicate tools (multiple tools doing the same job) +- Old projects still incurring cost +- Test environments that should have been torn down +- Forgotten domains, backups, snapshots, logs + +This is usually the largest opportunity in the first audit. Often 10-30% of spend. + +### Lever 2: Rightsize + +Pay for what you actually use, not what you provisioned for the worst case three years ago. + +- Oversized instances (CPU and memory utilization low) +- Over-provisioned databases (storage and throughput far above usage) +- Over-purchased SaaS seats +- Premium plans where standard would suffice +- High-availability setups for non-critical systems + +Rightsizing requires real usage data, not theoretical needs. + +### Lever 3: Restructure + +Use cheaper structures for the same workload. + +- Reserved or committed-use pricing (1-3 year commitments at 30-70% discount) +- Spot or preemptible instances for fault-tolerant work +- Cold storage for data accessed rarely +- Tiered storage (hot/warm/cold) by access pattern +- CDN caching to reduce origin load +- Compression and deduplication +- Serverless for spiky workloads +- Reserved instances for steady workloads + +The right structure depends on the access pattern. Mismatch costs money. + +### Lever 4: Negotiate + +Pay less for the same thing. + +- Annual contracts at lower rates than monthly +- Volume discounts at higher tiers +- Multi-year commitments for predictable workloads +- Bundle deals (consolidating services with one vendor) +- Renewal negotiation (vendors expect you to ask) +- RFP / competitive bid (using alternatives as leverage) + +Most enterprise vendors negotiate. Most SaaS vendors don't, except at higher tiers. Consumer-tier services usually don't. + +### Lever 5: Reframe + +Change the question. + +- Build vs buy: maybe in-house is cheaper at scale +- Buy vs build: maybe outsourcing is cheaper at small scale +- Different architecture (e.g., monolith vs microservices) has different cost profiles +- Different audience (do all customers need the same tier?) +- Different stack (open source vs commercial) + +Reframe is the longest-lead lever. Worth thinking about even if not actionable now. + +--- + +## Workflow + +### Step 1: Pull the spend data + +Get monthly costs by service, vendor, and (where possible) team or project. + +For cloud (AWS, GCP, Azure): the billing console and cost-explorer tools. +For SaaS: each vendor's billing portal, plus an SaaS-management tool if available. +For everything else: bank statements and accounting export. + +12 months minimum. Trends matter as much as absolute numbers. + +### Step 2: Categorize + +Organize spend into categories: + +- Hosting / compute +- Storage +- Database +- Networking / CDN +- Monitoring / observability +- Email +- CMS / hosting platforms +- Analytics / marketing +- Productivity / collaboration +- Development tools +- Security / compliance +- Other + +The categories vary by business. The point is: similar costs grouped, easy to compare. + +### Step 3: Identify the biggest line items + +80/20 rule. Usually 20% of vendors account for 80% of spend. + +Focus the audit on the top 80%. The long tail can be cleaned up but rarely yields big savings per item. + +### Step 4: Apply the 5 levers + +For each major line item, walk the levers: + +\| Lever \| Question \| +\|---\|---\| +\| Eliminate \| Is it used? Could we stop using it? \| +\| Rightsize \| Are we paying for capacity we don't use? \| +\| Restructure \| Is there a cheaper pricing model or service tier? \| +\| Negotiate \| When was the last renewal? Did we negotiate? \| +\| Reframe \| Is this even the right approach? \| + +Document the opportunity, the effort, the risk, and the savings estimate. + +### Step 5: Prioritize + +Plot opportunities on a 2x2: +- Y axis: savings +- X axis: effort + +Quadrants: +- High savings, low effort: do first +- High savings, high effort: plan +- Low savings, low effort: do as time allows +- Low savings, high effort: skip + +Also consider risk: +- Eliminate something used by no one: low risk +- Rightsize a database: medium risk (test in staging first) +- Replace a critical dependency: high risk (plan carefully) + +### Step 6: Execute the easy wins + +For each easy-win opportunity: +- Document the change +- Get owner approval +- Make the change +- Monitor for unexpected impact +- Confirm cost reduction in next billing cycle + +Easy wins typically include: +- Canceling unused subscriptions +- Tearing down idle resources +- Switching off dev environments outside business hours +- Moving cold data to cheaper storage tiers + +### Step 7: Plan the larger work + +For higher-effort opportunities: +- Spec the change (use `pm-spec-writing` for the plan) +- Test in staging +- Roll out incrementally +- Validate cost impact + +Examples: +- Migrating to reserved instances +- Consolidating monitoring vendors +- Migrating from one CMS to another with cost benefit + +### Step 8: Set up ongoing visibility + +Optimization isn't one-time. Costs creep back up. + +- Monthly cost review (at least) +- Cost dashboard (current, trend, by category) +- Alerts on cost spikes (e.g., daily spend exceeds threshold) +- Tagging or labeling on cloud resources (cost by team or project) +- Quarterly deeper review + +### Step 9: Negotiate at renewal + +For vendor contracts up for renewal: +- Start the conversation 60-90 days before renewal +- Have alternatives identified (even if you don't switch) +- Ask for a multi-year discount +- Ask about volume tiers +- Ask if usage rightsizing is possible +- Be willing to walk (most vendors find a way to keep you) + +Pre-pandemic, many vendors auto-renewed at increases. Post-pandemic, many are hungry for retention. Ask. + +### Step 10: Document the policy + +Going forward: +- New vendor evaluation requires cost justification +- Resource provisioning has approval thresholds +- Tagging and labeling are required for cloud resources +- Quarterly review is calendared +- Cost attribution is clear + +Without policy, costs creep. + +--- + +## Common opportunities by category + +### Hosting and compute + +- Reserved or committed-use pricing for predictable workloads (30-70% off) +- Spot or preemptible for fault-tolerant batch +- Auto-scaling for variable loads +- Right instance family (compute-optimized, memory-optimized, etc.) +- Dev/staging instances stopped outside business hours + +### Storage + +- Lifecycle policies to move old data to cheaper tiers +- Delete old logs, backups, snapshots +- Compression for archival +- Object versioning costs (every version is a stored object) + +### Database + +- Right size based on actual CPU/memory usage +- Reserved capacity for predictable workloads +- Read replicas for read-heavy workloads (cheaper than scaling primary) +- Drop unused indexes (indexes cost storage and write performance) +- Old data archived or deleted + +### Networking and CDN + +- CDN reduces origin egress costs (often the biggest cost category) +- Compression on the wire +- Image and video optimization +- Region-aware routing + +### Monitoring and observability + +- Sample logs (don't ingest 100% of high-volume sources) +- Retention policies (do you need 90 days or 30?) +- Consolidate tools where possible +- Free or open-source tooling for non-critical needs + +### SaaS + +- Audit logins per seat (inactive users on $X/seat = $X waste) +- Renegotiate at renewal +- Move to annual billing for the discount +- Consolidate overlapping tools + +--- + +## Failure patterns + +Cost-cutting that breaks something. Aggressive rightsizing without testing causes outages. The cost of an outage is usually larger than the savings. + +Optimization that takes more time than it saves. A team spends a quarter saving $5K/year. Math doesn't work. Focus on opportunities where savings exceed effort. + +Renewal autopilot. Annual renewals go through without review. Calendar them. + +No tagging. Cloud spend grows; no one knows whose. Tag everything from day one. + +Free tier overruns. "It's on the free tier." Then it's not, and bills surprise. Set alerts on free-tier services. + +No environment differentiation. Production-grade staging "to match prod." Costs as much as prod. Often unnecessary. + +Untouched legacy. "The old project still runs." Why? Often: nothing actually uses it. Audit and shut down. + +Premium tiers for non-premium needs. Enterprise plan because someone wanted a feature that's been since added to lower tiers. Recheck. + +Vendor lock-in justifying cost. "We can't switch." That's not a reason to overpay; it's a strategic problem to plan around. + +Optimizing the small stuff while ignoring the big stuff. Saving $50/month on tools while $5K/month sits in oversized infrastructure. Top-down first. + +Penny-wise, pound-foolish. Cutting a useful tool to save $20/month, then losing hours to manual work. Tools that pay for themselves shouldn't be cut. + +No reinvestment. Every dollar saved goes to bottom line; nothing reinvested in upgrades or capacity. Saved costs and improved capability aren't either/or. + +--- + +## Output format + +A cost optimization document includes: + +- Current state: total spend, by category, trended +- Top line items: the biggest costs +- Opportunities: by lever (eliminate / rightsize / restructure / negotiate / reframe) +- Prioritized list: with savings, effort, risk +- Action plan: owners, dates +- Easy wins executed: what's already done, results +- Ongoing governance: dashboard, review cadence, tagging, approval thresholds + +--- + +## Reference files + +- [`references/cloud-audit-checklist.md`](references/cloud-audit-checklist.md): A practical walkthrough for auditing a cloud account (compute, storage, database, network, monitoring) for waste and rightsizing opportunities. diff --git a/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md b/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md new file mode 100644 index 0000000..1265c60 --- /dev/null +++ b/dist/pi/.agents/skills/cost-optimization/references/cloud-audit-checklist.md @@ -0,0 +1,292 @@ +# Cloud Audit Checklist + +A practical walkthrough for auditing a cloud account for waste and rightsizing opportunities. Stack-agnostic in principle; the categories apply across AWS, GCP, Azure, and others. + +Allow about a half-day for a first audit. Subsequent audits go faster. + +--- + +## Setup + +- [ ] Pull the last 12 months of billing data +- [ ] Pull current resource inventory (compute, storage, database, networking) +- [ ] Identify owners per service or project +- [ ] Note any compliance or contractual constraints + +--- + +## Compute + +### Identify idle and underused + +- [ ] Instances with CPU utilization below 10% over 30 days +- [ ] Instances stopped but still incurring some charges (storage, IPs, etc.) +- [ ] Instances running 24/7 that only need business hours +- [ ] Instances forgotten from old projects +- [ ] Instances spun up for a one-time task and never deleted + +For each: identify owner. Confirm it's not needed. Stop or delete. + +### Rightsize active instances + +- [ ] Instances with CPU peaks under 40% (probably oversized) +- [ ] Instances with memory underused +- [ ] Instances of older generation (newer generations often cheaper for same performance) +- [ ] Instances of wrong family (compute-optimized when memory-optimized would be cheaper) + +For each: test smaller size in staging. Roll out gradually. + +### Pricing structure + +- [ ] On-demand instances with stable load (candidates for reserved or savings plans) +- [ ] Workloads that could tolerate interruption (candidates for spot/preemptible) +- [ ] Long-running workloads with no commitment (candidate for committed-use discounts) + +Reserved/committed: 30-70% discount for 1-3 year commitment. +Spot/preemptible: 60-90% discount, can be terminated by provider. + +### Auto-scaling + +- [ ] Auto-scaling configured for variable workloads (vs always-on at peak size) +- [ ] Scaling policies actually scale down (some only scale up) +- [ ] Min size set appropriately (not over-provisioned) + +--- + +## Storage + +### Identify unused + +- [ ] Snapshots not used in 6+ months +- [ ] Disks unattached to any instance +- [ ] Buckets accessed never or rarely (per access logs) +- [ ] Old log archives no one queries +- [ ] Old backups beyond retention requirements + +For each: confirm it's not needed. Delete or archive. + +### Lifecycle policies + +- [ ] Hot data only for recent access +- [ ] Move data to warm tier after [N] days +- [ ] Move to cold/archive tier after [M] days +- [ ] Delete after [P] days (if compliant) + +Lifecycle policies are set-once, save-forever. High ROI for the time invested. + +### Storage class + +- [ ] Verify storage class matches access pattern + - Frequently accessed: standard + - Infrequent: IA / nearline + - Rarely: cold / archive + - Compliance-only: deep archive + +Mismatched storage class is a common waste category. + +### Versioning + +- [ ] Object versioning is on intentionally (not accidentally) +- [ ] Old versions cleaned up via lifecycle policy +- [ ] Soft-delete retention is finite (not indefinite) + +Versioned buckets can accumulate massive cost from old versions. + +--- + +## Database + +### Identify underused + +- [ ] Databases with low CPU/memory usage over 30 days +- [ ] Databases with low connection counts +- [ ] Databases that could be smaller instance class +- [ ] Read replicas no longer needed +- [ ] Databases for old projects + +### Rightsize storage + +- [ ] Storage allocated far above used +- [ ] Auto-scaling on for storage (avoid manual oversizing) +- [ ] Old logs and audit data cleaned up + +### Backup retention + +- [ ] Backup retention matches RPO (not aspirational, not excessive) +- [ ] Manual snapshots cleaned up (often outlive their purpose) + +### Pricing structure + +- [ ] Reserved capacity for steady workloads +- [ ] Spot/preemptible for non-critical analytics + +### Indexes + +- [ ] Unused indexes dropped (each index costs storage and write performance) +- [ ] Indexes match query patterns (use database tooling to identify) + +--- + +## Networking + +### Egress + +Egress (data leaving the cloud or moving across regions) is often the most surprising cost. + +- [ ] Egress to internet (largely user traffic; CDN can reduce) +- [ ] Egress between regions (often unintended; check architecture) +- [ ] Egress between availability zones (matters at scale) +- [ ] NAT gateway charges (per-GB; can be huge for high-traffic egress) + +Reduce egress with: +- CDN caching (origin egress drops dramatically) +- Compression +- Multi-region only when needed (single-region egress is often cheaper) +- VPC endpoints for cloud-internal traffic (avoid going out and back in) + +### Load balancers + +- [ ] Idle or unused load balancers +- [ ] Load balancer count appropriate (don't run 5 when 1 works) +- [ ] Load balancer type matches use (application LB vs network LB; pricing differs) + +### Public IPs + +- [ ] Idle elastic IPs (charged when not attached) +- [ ] Public IPs that should be private + +### CDN + +- [ ] CDN in front of high-traffic origin +- [ ] Cache hit rate measured (low cache hit = wasted CDN, untrained origin) +- [ ] Compression and image optimization on at the CDN + +--- + +## Monitoring and logs + +### Log volume + +- [ ] Logs ingested but never queried +- [ ] Verbose logging in production (debug level by accident) +- [ ] Logs from low-importance services at full volume + +Sample or filter where possible. High-volume logs can dominate observability bills. + +### Retention + +- [ ] Retention matches need (do you query 90-day-old logs?) +- [ ] Compliance retention separate from operational retention (compliance can use cheaper storage) +- [ ] Aggregated metrics retained longer than raw logs (cheaper, often sufficient) + +### Tooling + +- [ ] Multiple monitoring tools doing the same job +- [ ] Premium tier when standard would suffice +- [ ] Per-host pricing on tools where utilization is low + +--- + +## Specialty services + +### Search (Elasticsearch, Algolia, etc.) + +- [ ] Indexes for old data still queried? +- [ ] Replicas appropriate for traffic +- [ ] Tier matches need + +### Cache (Redis, Memcached) + +- [ ] Cache hit rate measured (low hit = expensive cache delivering little value) +- [ ] Cache size appropriate +- [ ] TTLs reasonable + +### Queue / streaming (Kafka, Kinesis, SQS) + +- [ ] Throughput matches actual load +- [ ] Retention matches need +- [ ] Idle streams or topics cleaned up + +### Email / SMS / push + +- [ ] Volume matches projection +- [ ] Per-message pricing tier appropriate +- [ ] Old or low-engagement contacts removed (don't pay to send to non-recipients) + +--- + +## Account-level + +### Multiple accounts + +- [ ] Account count matches need (separation of concerns is good; sprawl is wasteful) +- [ ] Consolidated billing enabled (volume discounts across accounts) +- [ ] Inactive accounts decommissioned + +### Tagging + +- [ ] Tags applied to all resources +- [ ] Tags consistent (team, project, environment, cost center) +- [ ] Untagged resources have owners identified + +### Budgets and alerts + +- [ ] Budget alerts configured (e.g., alert at 80% of monthly target) +- [ ] Anomaly detection enabled (alert on unusual cost spikes) +- [ ] Per-team or per-project budgets where possible + +--- + +## Findings document + +For each finding, capture: + +\| Field \| Example \| +\|---\|---\| +\| Description \| "Production database is 8xlarge; CPU peaks at 25%" \| +\| Category \| Compute / storage / database / network / etc. \| +\| Lever \| Eliminate / rightsize / restructure / negotiate / reframe \| +\| Estimated savings \| $/month \| +\| Effort \| Hours/days \| +\| Risk \| Low / medium / high \| +\| Owner \| Person or team \| +\| Action \| Specific next step \| + +--- + +## Prioritization + +After all findings: + +\| Priority \| Description \| +\|---\|---\| +\| P0 \| Easy, high savings, low risk: do this week \| +\| P1 \| Medium effort, high savings: plan this quarter \| +\| P2 \| Easy, low savings: do as time allows \| +\| P3 \| High effort, low savings: deprioritize \| + +Reserved instances and committed-use discounts often appear as P0/P1: high savings, structured effort. + +--- + +## Tracking + +After acting, track: +- Savings achieved (compare next billing cycle to baseline) +- Issues caused (any rollbacks needed?) +- Time spent +- Lessons for next audit + +Cost reductions sometimes appear gradually (e.g., reserved purchase smooths in). Track over 2-3 billing cycles. + +--- + +## Maintenance + +- [ ] Set monthly cost review (15-30 min, look at trends) +- [ ] Set quarterly deeper audit (this checklist, abbreviated) +- [ ] Set annual full audit (this checklist, full) +- [ ] Set renewal calendar (each major contract, with reminder 90 days out) +- [ ] Tag governance (new resources require tags, untagged flagged) + +Cost optimization is ongoing, not one-time. Without maintenance, savings reverse. diff --git a/dist/pi/.agents/skills/creative-brief-selector/SKILL.md b/dist/pi/.agents/skills/creative-brief-selector/SKILL.md new file mode 100644 index 0000000..64d4a99 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/SKILL.md @@ -0,0 +1,112 @@ +--- +name: creative-brief-selector +description: "Produce a creative brief grounded in live reference sites and deliberately distinct from existing demos, for any new brand build. Composes with brand-archetype-system and creative-direction. Use this skill at the start of any brand or microsite build when the result needs to land in a specific aesthetic position and not drift into a default house style. Triggers on creative brief, design brief, build brief, brand direction, where should this brand sit, what should this site look like, reference sites for, archetype for, distinct from our other brands, divergence from prior, not the same as. Also triggers when prior builds have come out as siblings and a systematic divergence approach is needed." +category: brand +catalog_summary: "Live-reference-grounded creative briefs with divergence check against prior builds" +display_order: 6 +--- + +# Creative Brief Selector + +A starting-point selector for brand and microsite builds. Given a business spec (name, vertical, shape, one-line vibe, optional list of shipped demos), produces a creative brief grounded in three things: + +1. An archetype position from `brand-archetype-system`, picked or composed to be deliberately distinct from the shipped demos. +2. A small set of live reference sites for that archetype-and-vertical combination, drawn from a curated bank plus optional per-build discovery. +3. A divergence check against the shipped demos that flags palette, voice, structural pattern, and section-shape overlap before the brief is handed off. + +The brief output is concrete tokens, not abstract families, including explicit section-shape choices (hero shape and footer shape) as first-class outputs alongside palette and voice. It is meant to be loaded by downstream build skills as the single creative artifact for the build. + +--- + +## When to use + +- Starting any new brand or microsite build that should land in a specific aesthetic position. +- The first build in a portfolio (no prior builds to diverge from yet, but the divergence schema can be seeded for the next one). +- The second through nth build in a portfolio, where the risk of sibling output is real. +- After a portfolio audit that surfaced sibling builds: this skill is the systemic fix for the pattern. +- When a build's creative direction is being chosen between two adjacent archetypes and the call needs a reference-grounded reason. + +## When NOT to use + +- The user wants pure aesthetic methodology guidance (use `creative-direction`). +- The user has a finished archetype and a finished brief and is asking for execution (skip to the downstream build skills). +- The user wants a logo or a finished identity (use `logo-design`, `brand-identity`). +- The user wants to define voice for an existing brand (use `brand-voice`). +- Defining brand strategy from zero positioning (use `brand-ideation` first, then return to this skill). + +--- + +## How this composes with other skills + +This skill works upstream of build-time skills and parallel to the aesthetic methodology layer: + +- `brand-archetype-system` (upstream input). The archetype catalog this skill picks from. The skill names the archetype in the rendered brief; it does not redefine the archetype's defaults. +- `creative-direction` (parallel input). The four-axis vocabulary the archetypes reference. If the consumer needs the full axis brief, run `creative-direction` first; this skill's brief consumes its outputs. +- `brand-identity` (downstream). Once the brief is approved, brand-identity turns it into a finished identity system. +- `landing-page-copy`, `content-and-copy`, `art-direction` (downstream). Every downstream skill that produces aesthetic output references this skill's brief. + +Direct verbatim copying of an archetype's default palette into a new brand is the failure mode this skill exists to prevent. The brief shifts the archetype's defaults toward the business spec's specifics. + +--- + +## The framework: five steps, three rules, one hybrid bank + +1. Locate the design space. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. +2. Run input-side divergence. Read the shipped-demos signatures. Discard candidates that would land sibling to anything shipped. Record what was rejected and why. +3. Pull references. From the curated reference bank under `references/reference-bank/`, load the file(s) matching the chosen archetype-and-vertical. Augment with one to two discovered live references if the bank is sparse. Add discovered references back to the bank in the build PR. +4. Adapt. Shift the chosen archetype's defaults (palette, type, voice, layout, imagery direction) toward the business spec. The brief lands as concrete tokens, not abstract families. +5. Render and verify. Render the brief using the template in [`references/02-brief-template.md`](references/02-brief-template.md). Run output-side divergence. Output the brief plus the references list plus the divergence-check result. + +Full step-by-step in [`references/01-process.md`](references/01-process.md). The divergence schema and its three overlap rules are in [`references/03-divergence-check.md`](references/03-divergence-check.md). + +--- + +## The hybrid references model + +A curated bank that grows with each build. Each file under `references/reference-bank/` covers one archetype-and-vertical combination and holds three to six live reference URLs, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations covering western-boot maker, heritage barbershop, and balloon-ride experience. + +When a build draws from a sparse combination, the build is expected to commit the live references it discovered back to the bank as part of its build PR. The bank gets denser with use. + +--- + +## The divergence schema + +Each shipped demo carries a signature with seven fields: + +- `slug` +- `archetype` (the canonical archetype name from `brand-archetype-system`) +- `dominant_hue_family` (the recognizable colour family, e.g. leather-bone-saddle, dawn-navy-coral, dark-linen-amber) +- `voice_register` (e.g. story-forward third-person, atmospheric second-person, fitment-first technical) +- `primary_structural_pattern` (e.g. shoppable-grid-product-forward, arc-timeline-hero, fitment-selector-then-rails) +- `hero_shape` (e.g. dual-column-image-and-text, wide-photograph-with-band-below, full-bleed-image-with-overlay; canonical vocabulary in `references/05-section-shapes-vocabulary.md`) +- `footer_shape` (e.g. single-line-strip, multi-column-sitemap, type-only-no-links; same vocabulary file) + +Overlap rules (full set in [`references/03-divergence-check.md`](references/03-divergence-check.md)): + +- Two demos share archetype AND share dominant_hue_family => SIBLING (block). +- Two demos share archetype AND share voice_register AND share primary_structural_pattern => SIBLING (block). +- Two demos share only dominant_hue_family across different archetypes => WARN. +- The candidate's hero_shape matches the hero_shape of two or more shipped demos => WARN. +- The candidate's hero_shape matches three or more shipped demos AND any share an archetype family => BLOCK. +- The candidate's footer_shape matches three or more shipped demos => WARN. + +A worked example file of seven signatures lives at [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) for illustration; the live signatures file for any consuming project lives in that project, not in this skill. + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands, following the convention of `brand-archetype-system`. Live reference sites are cited as exemplars using nominative attribution language: "exemplified by [URL]", "characteristic of", "in the register of". This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## Reference files + +- [`references/00-overview.md`](references/00-overview.md) - The case for the skill, the hybrid references model, the two-direction divergence, the trademark posture. +- [`references/01-process.md`](references/01-process.md) - The five-step process, each step concrete enough to execute. +- [`references/02-brief-template.md`](references/02-brief-template.md) - The fillable brief template with section-by-section guidance. +- [`references/03-divergence-check.md`](references/03-divergence-check.md) - The signature schema and the overlap rules. +- [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) - Worked example signatures file with seven demos. +- [`references/05-section-shapes-vocabulary.md`](references/05-section-shapes-vocabulary.md) - Canonical open vocabulary of hero and footer section shapes plus archetype affinities. + +The curated reference bank lives in a `reference-bank/` subdirectory under `references/`. The bank ships with a README plus three seed archetype-and-vertical files: `premium-dtc-maker-western-boots.md`, `heritage-local-service-barbershop.md`, and `hospitality-experience-balloon-ride.md`. The bank's purpose and extension procedure are documented in its README; the seed files each carry three to four positive live references and one to two negative references for the chosen position. Load the bank file matching the build's archetype-and-vertical at step 3 of the process. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md b/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md new file mode 100644 index 0000000..337ea91 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/00-overview.md @@ -0,0 +1,79 @@ +# Overview + +The case for the skill, the references model, and the trademark posture. + +--- + +## The problem this skill exists for + +Portfolios of brand work drift toward house style. The first demo establishes a default; the second demo borrows it; the third has the same skeleton with a different name. Without a deliberate intervention at brief time, every new build leans on the same palette, the same micro-label tracking, the same hero gradient, the same voice register. The output is competent and sibling. + +This pattern is observable in any portfolio that has shipped more than two builds. The symptoms show up at the imagery stage, when a stone-and-amber palette that worked for one shape suddenly reads as the brand's signature across three shapes that should not share a signature. The fix is upstream: pick the position before the build starts, and verify it stays distinct as the build renders. + +This skill is the deliberate creative direction at brief time. + +--- + +## The hybrid references model + +Two parts: + +### The curated bank + +Files under `reference-bank/`, one per archetype-and-vertical combination. Each file holds three to six live reference URLs that exemplify the position, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations and grows as new combinations are built against. + +The bank is the institutional memory of the portfolio. A new build for an archetype-and-vertical combination that has been done before loads the existing references and adapts. A new build for a sparse combination supplies new references during discovery and commits them back as part of its build PR. + +### Per-build discovery + +When the bank is sparse for a chosen combination, the build's first pass searches the live web for three to six exemplars. Curation rules are in [`reference-bank/README.md`](reference-bank/README.md). The discovered references serve the current build and seed the bank for future builds in the same combination. + +This is not a static reference list. The bank is supposed to drift over time as the portfolio grows; the discipline is that the bank reflects what was actually used in real builds. + +--- + +## The two-direction divergence check + +The skill runs divergence twice: once on input, once on output. + +### Input-side divergence + +Before any references are pulled, the skill loads the shipped-demos signatures file (a project artifact, not part of this skill; see [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md) for the illustrative format). Candidate archetypes are checked against the signatures. If a candidate would land sibling to a shipped demo, it is discarded and the rejection is recorded. + +The rejection record is itself useful output: it documents what the build was deliberately NOT. + +### Output-side divergence + +After the brief is rendered, the skill computes the brief's own signature (archetype, dominant hue family, voice register, primary structural pattern) and compares against the shipped signatures one more time. This catches adaptations that drifted back toward sibling territory during step 4 (the adapt step). + +The check produces one of three outcomes: `passed`, `warn-with-reasons`, or `block-with-reasons`. A `block` result means the brief cannot ship in its current form and needs adaptation before the next attempt. + +--- + +## Why two directions + +Input-side alone catches the obvious overlaps: picking an archetype that another demo already uses with the same palette family. Output-side catches the subtle drift: an archetype was picked clean of any sibling demo, but during adaptation the palette quietly converged on the recurring house family. + +The recurring stone-and-amber family is the worked example of this drift. The first build picked it intentionally; the second build adopted it because it was in the air; the third build adopted it because it felt like the brand. Without an output-side check, the brief itself becomes the carrier of the drift. + +--- + +## Trademark and attribution + +This skill follows the `brand-archetype-system` convention. Archetypes are named for aesthetic families ("Premium DTC Maker," "Heritage Local Service") not for brands. Live reference sites are cited as exemplars using nominative attribution language: + +- "exemplified by [URL]" +- "characteristic of [URLs]" +- "in the register of [URL]" + +This is descriptive and nominative fair use. A reference that pivots its identity does not invalidate the archetype it once exemplified, but it should be removed from the bank when the URL no longer shows what it was cited for. + +--- + +## What this skill is not + +- Not a logo designer. The brief includes a logo direction note ("type-led wordmark with a saddle-tan rule," "graphic mark in the dawn palette") but does not produce the mark itself. +- Not an identity system. The brief is the input to `brand-identity`, which produces the system. +- Not a finished design. The brief describes tokens; it does not lay them out into a finished page. +- Not a positioning exercise. The business spec is assumed to have positioning already. If positioning is open, run `brand-ideation` first. +- Not a taste machine. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. Taste is upstream of this skill. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md b/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md new file mode 100644 index 0000000..95c441e --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/01-process.md @@ -0,0 +1,143 @@ +# The five-step process + +Each step concrete enough to execute. Run in order. Do not skip the divergence steps. + +--- + +## Inputs + +The skill takes a business spec: + +- Name (the brand name to be used in the brief) +- Vertical (e.g. western-boot maker, neighborhood barbershop, balloon-ride operator) +- Shape (the site shape: ecommerce-catalog, ecommerce-standout, local-service-booking, hospitality-experience, hospitality-food, institution-mission, inventory-listing, subscription-app, b2b-manufacturer, directory-marketplace) +- One-line vibe (a sentence describing what the brand wants to feel like) +- Shipped-demos signatures file (optional; the project artifact listing prior builds' signatures) + +If the shipped-demos file is absent, the build is the first in the portfolio. Run the divergence steps anyway and seed the signatures file with the rendered brief's signature. + +--- + +## Step 1. Locate the design space + +Read the business spec. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. + +How to pick: + +- Read the vertical and shape against the 12 core archetypes. Most verticals have two or three plausible candidates; the shape narrows it. +- A western-boot maker maps plausibly to Luxe Considered (heritage premium), Rugged Utilitarian (workwear and craft), or Editorial Restrained (boutique editorial). The shape (ecommerce-standout, with a small editorial collection) narrows toward Luxe Considered with a Rugged Utilitarian secondary. +- A neighborhood barbershop maps plausibly to Warm Conversational (everyday-craft), Retro Nostalgic (period-specific), or Documentary Honest (real-people-real-work). The shape (local-service-booking, with a booking action) narrows toward Warm Conversational with a Retro Nostalgic secondary. +- A balloon-ride operator maps plausibly to Documentary Honest (landscape-and-light), Luxe Considered (aspirational-experience), or Warm Conversational (small-operator-warm). The shape (hospitality-experience, with a named arc and a booking flow) narrows toward Documentary Honest with a Luxe Considered secondary. + +Output of this step: + +- Primary candidate archetype (name) +- Optional secondary candidate archetype (name) with a note on which leads +- Two-sentence rationale tying each candidate to the vertical and shape + +--- + +## Step 2. Run input-side divergence + +Read the shipped-demos signatures file. Compare each candidate against every shipped demo using the rules in [`03-divergence-check.md`](03-divergence-check.md). + +Procedure: + +- For each candidate (primary, then secondary if present): + - For each shipped demo: + - If archetype matches AND dominant_hue_family matches => discard the candidate as SIBLING. + - If archetype matches AND voice_register matches AND primary_structural_pattern matches => discard the candidate as SIBLING. +- If all candidates are discarded, return to step 1 and pick fresh candidates from a different position on the four creative-direction axes. + +Output of this step: + +- The surviving candidate (the chosen archetype) +- A rejection log listing any discarded candidates with the reason (which shipped demo collided and on which fields) + +The rejection log is part of the brief output. It documents what the build was deliberately NOT. + +--- + +## Step 3. Pull references + +From `reference-bank/`, load the file matching the chosen archetype-and-vertical. Read the positive references and the negative references. + +If the bank has the combination: + +- Pull three to four positive references from the bank's list. Prefer the ones marked as canonical or most-recent. +- Read the negative references; they tell the build what register to avoid. + +If the bank is sparse for the combination: + +- Pull whatever positive references are available (one or two if that is all the bank has). +- Augment with one to two discovered live references that exemplify the position. Search the web for the vertical with the archetype's signal terms (e.g. for Luxe Considered DTC western boots: "premium western boot maker editorial photography prices visible"). +- Note the discovered references with the same format as the bank (URL plus one-line why). Add them back to the bank as part of the build PR. + +Output of this step: + +- A list of three to four live reference URLs, each with a one-line why +- A note on which references came from the bank versus which were discovered +- A list of negative references (registers to avoid) + +--- + +## Step 4. Adapt + +Take the chosen archetype's defaults from `brand-archetype-system` (palette, type, voice, layout, imagery direction). Shift them toward the business spec's specifics. + +Adaptations to document: + +- Palette. Pick 6 to 8 specific hex values that fit the brand. Name each with a token name (e.g. `Bone cream #f5ecd7`, `Saddle tan #a8753a`, `Pre-dawn navy #1a1f3a`). Each token gets a role (page background, primary text, primary CTA, accent, etc.). +- Type system. Pick the display family (often a serif from the archetype), the body family (often Inter or similar), and the micro-label treatment (tracking, casing, weight). Document the explicit differentiators from shipped demos (e.g. "tight uppercase tracking 0.04em on micro-labels, distinct from the loose 0.18em tracking the hospitality-experience build uses"). +- Voice. Pick the voice register (e.g. story-forward third-person; atmospheric second-person; fitment-first technical). Write five to ten voice samples in this voice using the brand name. +- Layout. Pick the structural pattern (e.g. shoppable-grid-product-forward; arc-timeline-hero; fitment-selector-then-rails). Describe the spine moves the homepage will run (four to six numbered moves). +- Section shapes. Pick a `hero_shape` and a `footer_shape` from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). The hero shape carries the most visual weight on the page; pick it deliberately based on archetype, audience, and the shapes already shipped in the portfolio. Document the rejected shapes in the brief with one-line reasons. Skipping this step means the engine inherits the most recently built hero shape regardless of brief specification, which is the drift signal this skill exists to catch. +- CTA grammar. Pick the verb register (e.g. "Shop the collection," "Book a dawn," "See the morning"). Verb-first, shape-appropriate. +- Imagery direction. Describe the shoot's register (e.g. "warm-bone studio seamless, three-quarter angle, soft overhead, products fill 70 percent of frame"). Specify aspect ratios per page slot. + +Each adaptation choice gets a sentence of why. The brief is a referenceable artifact; it should explain itself. + +Output of this step: + +- The full adaptation set, ready to render into the brief template. + +--- + +## Step 5. Render and verify + +Render the brief using the template in [`02-brief-template.md`](02-brief-template.md). + +After rendering, compute the brief's own signature and run output-side divergence: + +- `archetype`: the chosen archetype (from step 1) +- `dominant_hue_family`: derived from the palette tokens +- `voice_register`: from the voice section +- `primary_structural_pattern`: from the spine moves +- `hero_shape`: from the section-shapes choice in step 4 +- `footer_shape`: from the section-shapes choice in step 4 + +Compare this signature against every shipped demo using the full rule set in [`03-divergence-check.md`](03-divergence-check.md). The check now runs seven rules: the original three pairwise rules (archetype/hue, archetype/voice/pattern, recurring hue across archetypes) plus the three aggregate shape rules (hero shape collision warn at two matches, hero shape archetype-collision block at three matches with shared family, footer shape warn at three matches). + +Possible outcomes: + +- passed. No overlaps. The brief is ready to hand off. +- warn-with-reasons. The brief shares a single field (most commonly dominant_hue_family) with a shipped demo, but not enough to be sibling. Surface the warn with the matched fields so the consumer can make a deliberate call. +- block-with-reasons. The brief is sibling to a shipped demo. Return to step 4 and adapt further before re-rendering. Common fixes: swap the dominant accent colour, restructure one of the spine moves, shift the voice register. + +Output of this step: + +- The rendered brief +- The references list (from step 3) +- The divergence-check result with all matched fields if any +- A one-line summary suitable for the build PR's description + +--- + +## Failure modes + +- Skipping step 2. Picking the archetype that "feels right" without checking against shipped demos is how the portfolio drifts toward house style. +- Skipping step 5. Adapting in step 4 without re-checking on output is how the brief itself becomes the carrier of drift. +- Verbatim copying from the archetype's default palette. The archetypes provide anchor points, not endpoints. If the brief's palette is the archetype's palette unchanged, the brief is the archetype, not a build. +- Citing references without why-lines. A reference URL without a one-line why is decoration. The why is what makes the reference usable in step 4. +- Hand-waving the divergence check. The check is not a vibe call. It is a mechanical comparison against the schema. If it produces a block, the adaptation is incomplete. +- Treating the rejection log as overhead. The rejection log is part of the deliverable. It tells the next build what is already taken. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md b/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md new file mode 100644 index 0000000..96ac397 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/02-brief-template.md @@ -0,0 +1,190 @@ +# The brief template + +A fillable markdown skeleton. Fill every section. A section left blank is a section the build will fill with the house default, which is exactly the drift this skill exists to prevent. + +The template is modeled on the structure proven by real shipped builds. The worked example link at the bottom of this file shows the structure rendered against a real build. + +--- + +## Template + +```markdown +# Creative direction: <Brand Name> as <archetype position> + +A reusable brief for the <Brand Name> build. <One-sentence purpose: what shape is this, what position is this, why this brief>. + +Use this brief for: + +- <Specific use case 1> +- <Specific use case 2> + +Do NOT use this brief for: + +- <Adjacent shape that should NOT use this brief> +- <Adjacent position that should NOT use this brief> + +## The <N> spine moves + +1. <Move 1 name>. <One paragraph describing the move, specific to the shape>. +2. <Move 2 name>. <One paragraph>. +3. <Move 3 name>. <One paragraph>. +4. <Move 4 name>. <One paragraph>. +<continue 5, 6 if the shape calls for them> + +## Register + +- Positive reference frame: <one sentence describing what the brand IS, with named exemplars in nominative attribution> +- Negative reference frame: <one sentence describing what the brand is NOT, with named non-exemplars> + +## Live reference sites + +The references this brief draws from. Each is a real site exemplifying the chosen position. + +- [<URL 1>] - <one-line why; what specifically this site does that the brief inherits> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional> + +Negative references (do NOT pull from): + +- [<URL>] - <one-line why this register is the wrong one> + +## Section shapes (hero and footer; first-class brief outputs) + +Pick a `hero_shape` and a `footer_shape` from [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Document the choice with rationale; the choice is not optional and a brief without these fields does not pass the divergence check. + +### `hero_shape`: <chosen shape label, e.g. `wide-photograph-with-band-below`> + +<One paragraph: why this shape, what the chosen shape signals to the visitor that the alternatives do not, what shapes were rejected and why. Reference the section-shapes vocabulary by label.> + +Rejected shapes: + +- `<rejected shape 1>` - <one-line why this shape was wrong for this brief> +- `<rejected shape 2>` - <one-line why this shape was wrong for this brief> + +### `footer_shape`: <chosen shape label, e.g. `single-line-strip`> + +<One paragraph: why this footer shape, what it does for the page that alternatives do not.> + +Rejected shapes: + +- `<rejected shape>` - <one-line why> + +## Palette token shape (specific to this brand; do not reuse across brands) + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| <Token 1 name> \| `#hex` \| <Role> \| +\| <Token 2 name> \| `#hex` \| <Role> \| +\| <Token 3 name> \| `#hex` \| <Role> \| +\| <Token 4 name> \| `#hex` \| <Role> \| +\| <Token 5 name> \| `#hex` \| <Role> \| +\| <Token 6 name> \| `#hex` \| <Role> \| +\| <Token 7 name> \| `#hex` \| <Role, optional> \| +\| <Token 8 name> \| `#hex` \| <Role, optional> \| + +Do NOT re-use <named hue family from a shipped demo, e.g. "stone-50 + amber-300 (the hospitality-experience default from the X build)">. + +## Type system + +- Display. <Family choice with stack notation>, <weight>, <tracking>. +- Body. <Family choice>, <weight>. +- Brand wordmark. <Family, case, tracking>. Distinct from <named shipped demo's wordmark treatment, e.g. "the loose 0.22em tracking used on the hospitality build">. +- Micro-labels. <Family, case, tracking>. <One-line on the explicit differentiator from shipped demos>. +- Numerics. <Family, tabular-nums or proportional, treatment for prices>. + +## CTA grammar + +- Primary on home. "<Verb-first label>". <One-line on why this verb>. +- Secondary on home. "<Verb-first label>". <One-line on why this verb>. +- On product or detail page. "<Label>". Verb-shape-appropriate. +- On craft or about page. "<Label>". Should close back to the primary action. + +## Image-ready spine + +The structure must be image-ready before any imagery pass runs. Per page slot: + +\| Page \| Aspect \| Count \| Source \| +\|---\|---\|---\|---\| +\| <Page slot 1> \| <e.g. 5:6 portrait> \| 1 \| <e.g. the signature product> \| +\| <Page slot 2> \| <e.g. 4:5 portrait> \| <e.g. one per product> \| <e.g. each product, on its own card> \| +\| <Page slot 3> \| <e.g. 16:9 wide> \| 1 \| <e.g. one lifestyle scene supporting the craft band> \| +\| <continue for every page> \| \| \| \| + +Each slot uses a placeholder during Phase A and is filled by the imagery pass in Phase B. Placeholders carry the alt text the final image will carry, so the swap is structurally drop-in. + +## Voice samples + +Five to ten lines in the brand's voice, used downstream by content-and-copy and landing-page-copy. + +- <Sample 1> +- <Sample 2> +- <Sample 3> +- <Sample 4> +- <Sample 5> +- <Sample 6, optional> +- <Sample 7, optional> + +## Honesty contract (unchanging across the portfolio) + +- <Functional element, e.g. cart, booking form> is real client-side, <demo surface, e.g. checkout, payment> is a clearly labelled demo that processes nothing. +- Fictitious brand disclosure in the footer and in any JSON-LD `description` field. +- Demo-only labelling on any demo surface in the brand's primary accent colour. +- All prices and figures fictitious. No promotional cadence, no fabricated reviews, no fabricated press quotes. +- No real brand mark. The logo pass, if any, is a separate later run. + +## Acceptance checklist (Phase A criteria) + +A build matches this brief if: + +- [ ] <Move 1 acceptance criterion> +- [ ] <Move 2 acceptance criterion> +- [ ] <Move 3 acceptance criterion> +- [ ] <Move 4 acceptance criterion> +- [ ] Palette is documentable as <N> tokens, distinct from any shipped demo's tokens. +- [ ] Type micro-labels have a distinct treatment from <named shipped demo's treatment>. +- [ ] Per-page image slots are wired with descriptive alt text, ready for a Phase B drop-in. +- [ ] Honesty contract intact. + +## Divergence-check result + +- Archetype: <chosen archetype name from brand-archetype-system> +- Dominant hue family: <derived from palette, e.g. "leather-bone-saddle"> +- Voice register: <e.g. "story-forward third-person"> +- Primary structural pattern: <e.g. "shoppable-grid-product-forward"> +- Hero shape: <chosen label from 05-section-shapes-vocabulary.md> +- Footer shape: <chosen label from 05-section-shapes-vocabulary.md> + +Input-side divergence: <passed \| warn-with-reasons \| block-with-reasons>. <If anything was rejected at step 2, list it here: rejected <archetype> because it collided with <shipped demo slug> on <field>>. + +Output-side divergence: <passed \| warn-with-reasons \| block-with-reasons>. <If warn or block, list the matched fields and the colliding demo. Rules 4 and 6 surface as warns; Rule 5 surfaces as a block; Rules 1, 2, 3 surface per their definitions in 03-divergence-check.md.> + +--- +``` + +--- + +## Worked example + +The Pinto Mesa Boots store-spine brief at `rampstackco-app/progress/ecommerce-standout-store-spine-brief.md` is a faithful render of this template against a real shipped build (ecommerce-standout shape; Luxe Considered with Rugged Utilitarian influence). It demonstrates: + +- The five spine moves (product-forward hero, shoppable grid, honest wayfinding, craft as supporting band, premium trust signals). +- The leather-forward palette with explicit do-not-reuse against the prior hospitality build's stone-and-amber. +- The type differentiation (tight uppercase microlabel tracking, distinct from the prior hospitality build's loose tracking). +- The image-ready spine with per-page aspect / count / source. +- The acceptance checklist as Phase-A criteria. + +Use the worked example as a structural reference when rendering new briefs. + +--- + +## Common section failures + +- Skipping the "Do NOT use this brief for" section. The negative-use section is what keeps the brief from being mis-applied to an adjacent shape. +- Spine moves that are abstract. "Lead with the product" is not a spine move. "Lead with the signature product shown large at 5:6 with one primary CTA and price-forward entry" is. +- Palette without explicit do-not-reuse lines. The do-not-reuse line is what makes the divergence check checkable. +- Type system without the explicit differentiator from shipped demos. This is the single field most likely to drift if not pinned. +- CTA grammar in mood words. "Welcoming" is not CTA grammar. "Shop the collection" is. +- Image-ready spine without aspect ratios. Without the aspect ratios the imagery pass cannot generate to the right shape. +- Honesty contract treated as boilerplate. The contract is part of what makes the brand demo-honest; cut and paste it but verify each line still applies to the specific build. +- Acceptance checklist as motivational language. The checklist is the build's pass/fail criteria, not a vibe statement. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md b/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md new file mode 100644 index 0000000..8374b0f --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/03-divergence-check.md @@ -0,0 +1,229 @@ +# The divergence check + +The signature schema, the overlap rules, and the comparison procedure. + +--- + +## Signature schema + +Each shipped demo carries a signature with seven fields. The schema is small on purpose: any field that takes judgment to populate gets argued about; a small mechanical schema gets used. + +```yaml +- slug: <kebab-case slug, e.g. pinto-mesa-boots> + archetype: <canonical archetype name from brand-archetype-system, e.g. luxe-considered> + dominant_hue_family: <named hue family, e.g. leather-bone-saddle> + voice_register: <named register, e.g. story-forward-third-person> + primary_structural_pattern: <named pattern, e.g. shoppable-grid-product-forward> + hero_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. dual-column-image-and-text> + footer_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. single-line-strip> +``` + +The last two fields (`hero_shape` and `footer_shape`) are the latest schema additions. The canonical vocabulary for both lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +### slug + +The kebab-case slug for the shipped build. Used to identify the demo in rejection logs and warn or block reasons. + +### archetype + +The canonical archetype name from `brand-archetype-system`. Use the file slug from `references/core-archetypes/` (e.g. `luxe-considered`, `documentary-honest`, `warm-conversational`). If the demo composes two archetypes, record both as a hyphenated pair with the lead first (e.g. `luxe-considered-rugged-utilitarian`). + +### dominant_hue_family + +The recognizable colour family the demo reads as, in three to four words. Examples: + +- `leather-bone-saddle` (Pinto Mesa Boots v2) +- `dawn-navy-coral` (Drift & Dawn after the dawn retune) +- `dark-linen-amber` (Pho Heights) +- `warm-walnut-brass` (Iron & Rye) +- `forest-green-cream` (Clearflow Initiative) +- `slate-and-amber` (the original Drift & Dawn pre-retune, kept for historical reference) +- `stone-and-amber` (the recurring family the imagery passes surfaced as the drift signal) + +The naming convention: two to four colour terms separated by hyphens, lowercase. The terms should be specific enough that two demos with materially different palettes get different families even if they share an undertone. + +### voice_register + +The brand's voice in three to four words. Examples: + +- `story-forward-third-person` +- `atmospheric-second-person` +- `fitment-first-technical` +- `evidence-and-mission-first` +- `restrained-citation-bearing` +- `warm-everyday-craft` + +The naming convention: hyphenated phrase that names the register the voice samples in the brief operate in. + +### primary_structural_pattern + +The structural pattern the homepage runs, in three to five words. Examples: + +- `shoppable-grid-product-forward` +- `arc-timeline-hero-with-packages-strip` +- `fitment-selector-then-rails` +- `editorial-hero-then-courses-grid` +- `barber-roster-then-services-menu` +- `theory-of-change-hero-then-evidence-band` + +The naming convention: name the homepage's primary spine in a way another build can recognize from the rendered page. + +### hero_shape + +The shape of the hero section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `dual-column-image-and-text` +- `wide-photograph-with-band-below` +- `full-bleed-image-with-overlay` +- `type-led-prose` +- `centered-single-column` +- `asymmetric-large-image-small-text` +- `grid-of-elements` +- `data-table-or-spec-led` + +A build that needs a shape not in the vocabulary documents and proposes a new label per the extension procedure in `05-section-shapes-vocabulary.md`. + +### footer_shape + +The shape of the footer section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `single-line-strip` +- `multi-column-sitemap` +- `type-only-no-links` +- `editorial-colophon-with-masthead` +- `newsletter-band-with-credits` +- `dark-cta-then-credits` + +--- + +## Overlap rules + +The comparison is mechanical. The skill applies these rules in order; the first rule that fires determines the outcome for that pair. + +### Rule 1: Same archetype + same dominant_hue_family + +If two demos share `archetype` AND share `dominant_hue_family`, they are SIBLING (block). + +Two demos in the same archetype with the same hue family will read as the same brand at a glance. The block forces an adaptation in either archetype or palette before the brief can ship. + +### Rule 2: Same archetype + same voice_register + same primary_structural_pattern + +If two demos share `archetype` AND share `voice_register` AND share `primary_structural_pattern`, they are SIBLING (block). + +This catches the case where the palettes diverge but the underlying skeleton is identical. The build will look different on first glance and identical on the second. + +### Rule 3: Same dominant_hue_family across different archetypes + +If two demos share `dominant_hue_family` but their `archetype` differs, the outcome is WARN. + +A recurring hue family across different archetypes is the most common drift signal in a portfolio. The warn surfaces the recurrence so the consumer can choose to break the pattern or accept it as the portfolio's signature. + +### Rule 4: Hero shape collision (warn) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of two or more shipped demos, the outcome is WARN. + +The warn surfaces a deliberation note listing every shipped demo using the same shape. The brief author either justifies the repeat (and records that justification in the brief's section-shapes rationale) or picks a different shape from the vocabulary. Two demos sharing a hero shape is acceptable for a portfolio of nine to twelve demos; three or more is the point where the shape starts reading as the engine's house default. + +### Rule 5: Hero shape archetype-collision (block) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of three or more shipped demos AND any of those matching demos share an archetype family with the proposed brief, the outcome is BLOCK. + +This catches the case where the brief is heading toward the strongest sibling result possible: the same hero shape AND a related archetype. The block forces the brief to choose differently on at least one dimension (a different hero shape, or a different archetype lead, or a documented justification that escalates to the deliberation notes with explicit reasoning). + +Archetype-family overlap is computed by comparing the lead archetype tokens. Composed archetypes share a family if either of their tokens matches. For example, `editorial-restrained` and `editorial-restrained-documentary-honest` share the `editorial-restrained` family; `documentary-honest-luxe-considered` and `rugged-utilitarian-documentary-honest` share the `documentary-honest` family. + +### Rule 6: Footer shape collision (warn) + +If the candidate's proposed `footer_shape` matches the `footer_shape` of three or more shipped demos, the outcome is WARN. + +Footers tolerate more repetition than heroes since they carry less visual weight and are more functional than expressive. The threshold (three matching demos for a warn, not two) is correspondingly higher. There is no block-level rule for footer shapes at this scope; if a portfolio-wide footer shape emerges as the house default, it becomes part of the portfolio's signature rather than a per-build distinctness failure. + +### Rule 7: Anything else + +If no rule above fires, the outcome is PASSED. + +--- + +## Why shapes carry weight + +Heroes carry the most visual weight on a page and the most signal to the visitor. Hero-shape repetition across a portfolio compresses the perceived distance between builds even when palette, voice, and structural pattern diverge. The early showcase portfolio surfaced this drift signal: most builds shipped a `dual-column-image-and-text` or `full-bleed-image-with-overlay` hero regardless of brief specification, because the engine pattern-matched the most recently built shape. + +Footers carry less weight and are typically more functional than expressive. They tolerate more repetition before the repetition becomes a distinctness cost. + +Rules 4, 5, and 6 exist to make hero-shape and footer-shape choice an explicit selection at brief time rather than an implicit inheritance from the most recently built demo. + +--- + +## Comparison procedure + +``` +# Pairwise rules (run on every candidate-shipped pair): +for candidate in candidates: + for shipped in shipped_demos: + if rule_1(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'dominant_hue_family']) + continue + if rule_2(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'voice_register', 'primary_structural_pattern']) + continue + if rule_3(candidate, shipped): + record_warn(candidate, shipped, fields=['dominant_hue_family']) + continue + +# Aggregate rules (run once per candidate against the full set): +for candidate in candidates: + hero_matches = [s for s in shipped_demos if s.hero_shape == candidate.hero_shape] + if len(hero_matches) >= 3 and any(shares_archetype_family(candidate, s) for s in hero_matches): + record_block(candidate, hero_matches, fields=['hero_shape', 'archetype']) # rule 5 + elif len(hero_matches) >= 2: + record_warn(candidate, hero_matches, fields=['hero_shape']) # rule 4 + + footer_matches = [s for s in shipped_demos if s.footer_shape == candidate.footer_shape] + if len(footer_matches) >= 3: + record_warn(candidate, footer_matches, fields=['footer_shape']) # rule 6 +``` + +The check produces three lists: blocks, warns, and a passed flag (true iff blocks and warns are both empty). + +### Input-side outcome + +- If any block was recorded against the primary candidate, discard it. If the secondary candidate also blocks, return to step 1 and pick fresh candidates. +- Warns at input-side are surfaced in the rejection log but do not discard the candidate. + +### Output-side outcome + +After the brief is rendered, the brief's own signature is checked against every shipped demo using the same rules. The outcome is one of: + +- passed: no blocks, no warns. The brief is ready to hand off. +- warn-with-reasons: warns only. The brief shares a single field (most commonly `dominant_hue_family`) with a shipped demo. Surface the warn with the matched fields so the consumer can make a deliberate call. +- block-with-reasons: at least one block. The brief is sibling to a shipped demo. Return to step 4 of the process and adapt further before re-rendering. + +--- + +## What changes a block to a warn or a pass + +Concretely: + +- Shift the dominant_hue_family. Swap the dominant accent colour, change the page background's temperature, or change the accent colour family (saddle to oxblood to navy). Recompute the family. +- Shift the primary_structural_pattern. Change which move leads the page. A "product-forward" pattern becomes "story-forward" by reordering the spine moves. Recompute the pattern. +- Shift the voice_register. Change the voice from third-person to second-person, or from atmospheric to technical. Recompute the register. +- Compose a different archetype pair. If the chosen archetype is locked, change the secondary archetype to shift the brief's centre of mass. + +Each adaptation should be a deliberate choice, recorded in the brief's adaptation notes (step 4 of the process). + +--- + +## The signatures file + +The signatures file is a project artifact, not part of this skill. The consuming project maintains it (typically as `progress/shipped-demos-signatures.yml` or similar). The illustrative format is in [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md). + +Whenever a new build ships, append its signature to the file. The signatures grow with the portfolio; the divergence check stays current. + +--- + +## Failure modes + +- Filling fields with vibe words. "vibrant-modern" is not a hue family; "saddle-bone-walnut" is. The schema works because the field values are specific. Vague values produce vague checks. +- Re-using the same family across builds without recomputing. When a build's palette shifts during step 4, the dominant_hue_family must shift with it. A stale signature is worse than a missing signature. +- Treating warns as ignorable. A warn is the portfolio's drift early-warning. Three consecutive warns on the same hue family is the portfolio adopting a house signature, which is the failure mode this skill exists to prevent. +- Hand-waving the rules. The rules are mechanical. If a candidate blocks under rule 1, it blocks; the answer is to adapt, not to argue with the rule. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md b/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md new file mode 100644 index 0000000..b770582 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md @@ -0,0 +1,141 @@ +# Shipped-demos signatures: worked example + +An illustrative signatures file with seven worked entries. This file is example-only; the live signatures file for any consuming project lives in that project (typically at `progress/shipped-demos-signatures.yml`), not in this skill. + +The schema is defined in [`03-divergence-check.md`](03-divergence-check.md). Each entry has seven fields: `slug`, `archetype`, `dominant_hue_family`, `voice_register`, `primary_structural_pattern`, `hero_shape`, `footer_shape`. The last two (`hero_shape`, `footer_shape`) are the latest additions; their canonical vocabulary lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +The seven entries below are illustrative records of seven sibling-shape demos a portfolio might ship. They are written here as a worked example of what the file looks like in practice. The archetype values reference the canonical names from `brand-archetype-system`. + +--- + +## Example signatures + +```yaml +demos: + - slug: fitfirst-parts + archetype: technical-precise + dominant_hue_family: slate-and-amber + voice_register: fitment-first-technical + primary_structural_pattern: fitment-selector-then-rails + hero_shape: dual-column-image-and-text + footer_shape: multi-column-sitemap + + - slug: iron-and-rye-barbershop + archetype: warm-conversational-retro-nostalgic + dominant_hue_family: warm-walnut-brass + voice_register: warm-everyday-craft + primary_structural_pattern: barber-roster-then-services-menu + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: pho-heights + archetype: documentary-honest-luxe-considered + dominant_hue_family: dark-linen-amber + voice_register: chef-essay-first-person + primary_structural_pattern: editorial-hero-then-signatures-menu + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: volta-robotics + archetype: technical-precise + dominant_hue_family: graphite-and-signal-orange + voice_register: spec-forward-technical + primary_structural_pattern: product-strip-then-spec-table + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: clearflow-initiative + archetype: editorial-restrained + dominant_hue_family: forest-green-cream + voice_register: restrained-citation-bearing + primary_structural_pattern: theory-of-change-hero-then-evidence-band + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: pinto-mesa-boots + archetype: luxe-considered-rugged-utilitarian + dominant_hue_family: leather-bone-saddle + voice_register: story-forward-third-person + primary_structural_pattern: shoppable-grid-product-forward + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: drift-and-dawn + archetype: documentary-honest-luxe-considered + dominant_hue_family: dawn-navy-coral + voice_register: atmospheric-second-person + primary_structural_pattern: arc-timeline-hero-with-packages-strip + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip +``` + +--- + +## Why each field is what it is + +### fitfirst-parts (ecommerce-catalog) + +- archetype: `technical-precise`. The build leads with a YMM (year-make-model) fitment selector. Grids, monospace numerics, system-feeling. +- dominant_hue_family: `slate-and-amber`. Cool slate ground with warm amber accents on safety and action surfaces. +- voice_register: `fitment-first-technical`. The voice asks "does it fit your vehicle" before anything else. +- primary_structural_pattern: `fitment-selector-then-rails`. The home leads with the selector, then rails of parts filtered by the confirmed vehicle. + +### iron-and-rye-barbershop (local-service-booking) + +- archetype: `warm-conversational-retro-nostalgic`. Heritage barbershop register; walnut and brass; period-specific cues. +- dominant_hue_family: `warm-walnut-brass`. Walnut wood and brass hardware are the recognizable palette. +- voice_register: `warm-everyday-craft`. The voice is the shop talking about its work in plain terms. +- primary_structural_pattern: `barber-roster-then-services-menu`. Roster (initials) leads, services menu follows, atmosphere gallery threads the page. + +### pho-heights (hospitality-food) + +- archetype: `documentary-honest-luxe-considered`. Dark linen photography, real-food register, premium restraint. +- dominant_hue_family: `dark-linen-amber`. Dark linen background dominates; amber surfaces as the accent. +- voice_register: `chef-essay-first-person`. The chef-partner essay is the page's voice. +- primary_structural_pattern: `editorial-hero-then-signatures-menu`. Edge-to-edge hero, chef essay, signatures section with image-led cards. + +### volta-robotics (b2b-manufacturer) + +- archetype: `technical-precise`. Industrial spec-table register. Same archetype as fitfirst-parts but a different hue family and a different structural pattern (so rule 1 does not fire on this pair). +- dominant_hue_family: `graphite-and-signal-orange`. Industrial graphite with hazard-orange accents on action surfaces. +- voice_register: `spec-forward-technical`. Specs lead, narrative supports. +- primary_structural_pattern: `product-strip-then-spec-table`. Product strip up top, deep spec tables follow. + +### clearflow-initiative (institution-mission) + +- archetype: `editorial-restrained`. Counsel-restrained register; numbers before adjectives; citation-bearing voice. +- dominant_hue_family: `forest-green-cream`. Deep forest green sections with warm cream surfaces. +- voice_register: `restrained-citation-bearing`. Third-person about the org, low-register confidence, numbers leading. +- primary_structural_pattern: `theory-of-change-hero-then-evidence-band`. Theory of change in the hero, evidence band (lives reached, water systems built) follows. + +### pinto-mesa-boots (ecommerce-standout) + +- archetype: `luxe-considered-rugged-utilitarian`. Premium DTC maker register with workwear and craft secondary. +- dominant_hue_family: `leather-bone-saddle`. Bone cream ground with saddle tan and walnut accents; oxblood as the demo-only chip. +- voice_register: `story-forward-third-person`. The brand talks about itself in the third person, with material before adjectives. +- primary_structural_pattern: `shoppable-grid-product-forward`. Product-forward hero, six-boot shoppable grid on the home, by-last wayfinding. + +### drift-and-dawn (hospitality-experience) + +- archetype: `documentary-honest-luxe-considered`. Photography-led, atmospheric, aspirational. Same composed archetype as pho-heights but a different vertical and a different hue family (so rule 1 does not fire on this pair). +- dominant_hue_family: `dawn-navy-coral`. Pre-dawn navy with coral and pale-gold accents, deliberately distinct from the hospitality-experience stone-and-amber default the original build used. +- voice_register: `atmospheric-second-person`. The brand walks the visitor through the morning in second person. +- primary_structural_pattern: `arc-timeline-hero-with-packages-strip`. Hero with arc preview, packages strip with named prices, six-moment timeline on the experience page. + +--- + +## What this example exercises + +The seven entries are constructed to exercise the divergence rules: + +- Rule 1 not firing: `fitfirst-parts` and `volta-robotics` share `archetype: technical-precise` but differ on `dominant_hue_family` (`slate-and-amber` vs `graphite-and-signal-orange`). No block. +- Rule 1 not firing: `pho-heights` and `drift-and-dawn` share `archetype: documentary-honest-luxe-considered` but differ on `dominant_hue_family` (`dark-linen-amber` vs `dawn-navy-coral`). No block. The deliberate retune from the original `slate-and-amber` to `dawn-navy-coral` is what kept this pair from blocking. +- Rule 3 historical case: the original `drift-and-dawn` (pre-retune, hue family `slate-and-amber`) would have triggered rule 3 against `fitfirst-parts` (also `slate-and-amber`) across different archetypes. The retune resolved the recurring family. + +--- + +## How to use this example + +Copy the YAML block to a `progress/shipped-demos-signatures.yml` file in the consuming project. Edit the entries to match the actual shipped builds. Append new entries as builds ship. The divergence check in [`03-divergence-check.md`](03-divergence-check.md) reads from this file. + +This file is example-only. The skill does not parse this example file at runtime; it parses the consuming project's signatures file. The example exists to show what the file should look like. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md b/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md new file mode 100644 index 0000000..0195584 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md @@ -0,0 +1,151 @@ +# Section shapes vocabulary + +A canonical, open vocabulary of section shapes the brief picks from for the hero and footer sections (with optional later extension to trust-strip, CTA-close, and how-it-works sections). The vocabulary is a starting point, not a closed enum. Builds can document and propose a new shape if none of the listed labels fits. + +Section shapes are first-class brief outputs. The brief picks a shape per section explicitly and records the rationale next to palette and voice rationale. Two new fields per signature record (`hero_shape` and `footer_shape`) let the divergence check fire against shape collision across shipped demos. + +The divergence rules for shapes are in [`03-divergence-check.md`](03-divergence-check.md) (Rules 4, 5, 6). + +--- + +## Hero shapes (open list, starting set) + +### `dual-column-image-and-text` + +Image on one side of the hero, heading and lede and CTAs on the other. CSS grid with two columns (often around 1.1fr / 1fr). The engine's house default and the shape most prone to overuse in a portfolio that grows without explicit shape selection. + +- When it fits: brands where the photograph and the type carry roughly equal weight and the eye is meant to ricochet between them. Premium DTC product hero is the canonical fit; a single product on the image side and a price-and-CTA on the type side. +- References: [allbirds.com](https://allbirds.com), [tecovas.com](https://tecovas.com). +- Archetype affinities: Luxe Considered, Warm Conversational, Editorial Restrained (mild). + +### `wide-photograph-with-band-below` + +Single full-width hero photograph (aspect 16:9 or wider) spanning the content width, with structured content (search rail, CTA pair, lede, filter chips) stacked vertically below the photograph. The photograph carries the page; the band below carries the affordances. + +- When it fits: inventory marketplaces, regional specialists, sites where the photograph signals what the marketplace is for and the band carries the controls. Also fits magazine-style editorial registers where one strong image opens an article. +- References: [bringatrailer.com](https://bringatrailer.com), [icon4x4.com](https://icon4x4.com). +- Archetype affinities: Rugged Utilitarian, Documentary Honest, Editorial Restrained. + +### `full-bleed-image-with-overlay` + +Image fills the section (or near-fills, often at `object-cover` with `absolute inset-0`), with type overlaid via a gradient. Dramatic, cinema-poster register. Strongest visual signal of all hero shapes; correspondingly the easiest to over-saturate. + +- When it fits: hospitality experiences where the place is the product (balloon ride, restaurant, hotel), mission-driven nonprofits where the documentary photograph is the evidence, premium B2B where the product is photographed at scale. Atmospheric and cinematic. +- References: [bombasses.com](https://bombasses.com) (hospitality), [charitywater.org](https://charitywater.org) (institution-mission). +- Archetype affinities: Documentary Honest, Luxe Considered (composed with Documentary Honest), Editorial Restrained. + +### `type-led-prose` + +No image in the hero. The H1 and lede do the work; image (if any) appears below the hero as a supporting element. Editorial publication register. The whitespace and the type carry the page. + +- When it fits: editorial publications, ideas-led brands, B2B SaaS where the proposition is conceptual, premium consultancies, law and finance where understated credibility is the play. +- References: [nytimes.com](https://nytimes.com), [stripe.com](https://stripe.com) (mild type-led, with type leading and a subtle product render below). +- Archetype affinities: Editorial Restrained, Technical Precise (mild). + +### `centered-single-column` + +Narrow content column centered on the page, H1 and lede only, minimal. Often paired with atmospheric brand registers where the centered alignment signals "considered, not loud." + +- When it fits: portfolio brands, atmospheric or contemplative registers, single-product brands where the page is essentially a long-scroll story and the hero is just the opening line. +- References: [linear.app](https://linear.app), [framer.com](https://framer.com) (both run centered single-column heroes at times). +- Archetype affinities: Editorial Restrained, Luxe Considered. + +### `asymmetric-large-image-small-text` + +One element dominates the hero (usually an image at 70 to 80 percent of width), the other is caption-scale beside or below it. Distinct from `dual-column-image-and-text` by the imbalance: the dual-column is roughly balanced, the asymmetric leans heavily. + +- When it fits: magazine cover style, photography portfolios, single-product hero where the product carries everything and the type is a caption-scale credit line. +- References: [magnum.com](https://magnum.com), [aesop.com](https://aesop.com) (varies; some pages use asymmetric layouts). +- Archetype affinities: Luxe Considered, Documentary Honest, Editorial Restrained. + +### `grid-of-elements` + +The hero IS a grid: product tiles, listing cards, directory entries, no single anchor image. The inventory or directory itself is the hero. Distinct from `wide-photograph-with-band-below` by having no single dominant image; the grid carries the meaning. + +- When it fits: directory and marketplace shapes where the breadth of the catalog is the value, ecommerce catalog shapes where shoppability above the fold is the conversion lever. +- References: [airbnb.com](https://airbnb.com) (search results hero is the grid), [unsplash.com](https://unsplash.com). +- Archetype affinities: Technical Precise, Editorial Restrained (with restraint), Rugged Utilitarian (if the directory is the working catalog). + +### `data-table-or-spec-led` + +A data table or spec block is the hero element. The numbers and the comparison carry the page. Technical Precise register, B2B engineering context, comparison-led purchase decisions. + +- When it fits: B2B engineering procurement, hardware comparison sites, financial product comparison, anywhere the buyer is data-anchored before they care about photography. +- References: [parametric-portfolios.com](https://parametric-portfolios.com), [substack.com/pricing](https://substack.com/pricing) (pricing-table-as-hero variants). +- Archetype affinities: Technical Precise, Editorial Restrained. + +--- + +## Footer shapes (open list, starting set) + +### `single-line-strip` + +One row carrying the brand disclosure paragraph and the footer nav, no multi-column structure. Mobile and desktop render the same content reflowed. The default across most demos in the showcase portfolio. + +- When it fits: small-collection brands, single-purpose microsites, demo and showcase contexts, brands where the footer is meant to be functional chrome rather than navigation in its own right. +- References: most editorial brand sites with a small surface area. +- Archetype affinities: any; this is the chrome default. + +### `multi-column-sitemap` + +Three to six columns of links plus brand info. Common on larger commerce sites where the footer carries category navigation, popular searches, account shortcuts, customer service, about-the-company, and resources. + +- When it fits: ecommerce catalog with deep category trees, multi-tenant marketplaces with seller-side and buyer-side links, B2B sites with documentation libraries. +- References: [amazon.com](https://amazon.com), [shopify.com](https://shopify.com), most large retailers. +- Archetype affinities: Technical Precise, Rugged Utilitarian (if functional), any commerce-heavy archetype. + +### `type-only-no-links` + +Minimal editorial footer, copyright and disclosure only, no nav. The footer is essentially a colophon. + +- When it fits: ideas-led brands, single-page narratives, publications where the nav lives in the top chrome and the bottom is just the credit line. +- References: [pitchfork.com](https://pitchfork.com) (varies; minimal footer), portfolio sites. +- Archetype affinities: Editorial Restrained, Luxe Considered. + +### `editorial-colophon-with-masthead` + +Masthead-style footer naming the editorial team or contributors. Fits publication register where the footer credits the people behind the work. + +- When it fits: publications, magazine sites, editorial collectives, organizations where the people are the brand. +- References: [theatlantic.com](https://theatlantic.com), [theverge.com](https://theverge.com). +- Archetype affinities: Editorial Restrained, Documentary Honest. + +### `newsletter-band-with-credits` + +Newsletter signup as the dominant footer element, with credits below. The newsletter is the conversion goal; the footer is the conversion surface. + +- When it fits: content sites, newsletter-first publications, brands where the newsletter is the customer-relationship channel. +- References: [substack.com](https://substack.com), most content sites operating newsletter-led growth. +- Archetype affinities: Editorial Restrained, Warm Conversational. + +### `dark-cta-then-credits` + +Two-row footer with a dark CTA band on top and a credits strip below. The CTA band acts as the page-bottom conversion surface; the credits strip is the actual footer. + +- When it fits: conversion-led sites where the bottom of the page is the second-most-attended surface (after the hero), marketing sites, B2B with a sign-up funnel. +- References: [vercel.com](https://vercel.com), [linear.app](https://linear.app). +- Archetype affinities: Technical Precise, any conversion-led register. + +--- + +## Optional extensions (not formally checked at this dispatch's scope) + +The framework can grow to cover additional section shapes as the portfolio surfaces them. Currently documented loosely; not part of the divergence check fields. + +- Trust-strip shapes: four-signal block, two-paragraph narrative band, logo wall, citation row. +- CTA-close shapes: dark band with single CTA, gradient band with pair of CTAs, image-backed close, newsletter close. +- How-it-works shapes: three-card strip, numbered list with images, flow diagram, timeline. + +When a brief's shape choice for one of these sections proves load-bearing for the build's distinctness, a future framework dispatch can promote the section to a checked field. + +--- + +## How to extend the vocabulary + +A build that discovers a section shape not present in the vocabulary: + +1. Documents the shape in the brief with a name (kebab-case), a one-paragraph description, and one or two real-world references. +2. Adds the shape to this file under the appropriate section (hero or footer) with the same format the existing shapes use. +3. Commits the vocabulary addition in the build PR. + +The vocabulary grows with the portfolio. Stale shapes (no demo uses them, no live references remain) can be retired in subsequent dispatches. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md new file mode 100644 index 0000000..dbaf928 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/README.md @@ -0,0 +1,114 @@ +# Reference bank + +The bank holds curated live reference sites for archetype-and-vertical combinations the portfolio has built against. Each file covers one combination, with positive references (sites that exemplify the position) and negative references (sites in the same vertical but in the WRONG register). + +The bank is the institutional memory of the portfolio. A new build for a combination that has been done before loads the existing file and adapts. A new build for a sparse combination supplies discovered references and commits them back to the bank as part of its build PR. + +--- + +## File naming convention + +`<archetype>-<vertical-specific-tag>.md` + +Examples: + +- `premium-dtc-maker-western-boots.md` +- `heritage-local-service-barbershop.md` +- `hospitality-experience-balloon-ride.md` + +The archetype prefix is the canonical name from `brand-archetype-system` (composed archetypes are hyphenated with the lead first). The vertical-specific tag is the narrowest description of the vertical the file covers (not the broad shape; the specific category within it). + +--- + +## File structure + +Each file has the same structure: + +```markdown +# <Archetype>, <Vertical> + +- Archetype: <Canonical archetype name, with composition note if any>. +- Vertical: <Broad shape> (specifically <narrow category>). +- Position summary: <One-line position the references collectively exemplify>. + +## Positive references + +- [<URL 1>] - <one-line why; what specifically this site does that a build in this position should inherit> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional but encouraged> + +## Negative references + +- [<URL or named category>] - <one-line why this register is the wrong one for this position> + +## Extension note + +- <When was this file last updated and against which build> +``` + +--- + +## Adding references + +A build that uses this skill on a combination that has a file already: + +1. Loads three to four references from the existing file in step 3 of the process. +2. If the build discovered any new live references in addition (because the bank's references were stale or the build needed more breadth), append them to the positive references list in the same file with a one-line why. +3. Commit the file edit as part of the build PR. + +A build that uses this skill on a combination with no existing file: + +1. Creates a new file under `reference-bank/` named per the convention above. +2. Fills the file with three to six positive references discovered during the build's step 3. +3. Fills negative references with one to two categories or named sites that the build should not pull from. +4. Commits the file as part of the build PR. + +--- + +## Reference quality bar + +Each positive reference should be a real live site that: + +- Exemplifies the chosen position observably (palette, layout, voice, imagery, or all four). +- Is operating at a quality level the build can credibly aspire to. +- Has been live recently (within the past year if possible; older references are acceptable if they remain the canonical example). + +Each negative reference should be a real live site or a named category that: + +- Sits in the same vertical but in a different register. +- Helps the build understand what to NOT pull from. + +The one-line why for each reference is what makes the reference usable in step 4 of the process. A URL without a why is decoration; the why is what tells the next build what specifically to inherit or avoid. + +--- + +## When to retire a reference + +A reference should be removed from the bank when: + +- The URL stops showing what it was cited for (brand redesign, site shutdown, paywall changed the visible register). +- A more canonical example for the same position emerges. +- The build that originally cited the reference has been superseded and the new build uses different references. + +Retirement is a normal part of bank maintenance. The bank reflects what is currently usable, not what was once usable. + +--- + +## Seeded combinations + +Eleven combinations live in the bank: + +- [`premium-dtc-maker-western-boots.md`](premium-dtc-maker-western-boots.md) - Premium DTC maker register applied to a small-collection western-boot maker. +- [`heritage-local-service-barbershop.md`](heritage-local-service-barbershop.md) - Heritage local-service register applied to a neighborhood barbershop. +- [`hospitality-experience-balloon-ride.md`](hospitality-experience-balloon-ride.md) - Documentary-honest hospitality-experience register applied to a scenic-flight operator. +- [`editorial-restrained-documentary-honest-specialty-coffee-subscription.md`](editorial-restrained-documentary-honest-specialty-coffee-subscription.md) - Editorial-restrained subscription-app register applied to a single-origin specialty coffee subscription. +- [`rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md`](rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md) - Rugged-utilitarian inventory-listing register applied to a regional used-truck-and-SUV marketplace. +- [`editorial-restrained-literary-quarterly.md`](editorial-restrained-literary-quarterly.md) - Editorial-restrained editorial-publication register applied to a themed literary and ideas quarterly. +- [`luxe-considered-editorial-restrained-residential-architectural-brokerage.md`](luxe-considered-editorial-restrained-residential-architectural-brokerage.md) - Luxe-considered-editorial-restrained inventory-listing register applied to a residential brokerage of architecturally significant homes (the first same-shape divergence test against the rugged-utilitarian regional-used-vehicle-marketplace entry). +- [`bold-confident-editorial-restrained-aaa-game-studio.md`](bold-confident-editorial-restrained-aaa-game-studio.md) - Bold-confident-editorial-restrained corporate-portfolio register applied to a AAA-adjacent action game studio (the first portfolio entry in Bold Confident; the gentler entry into the bold register before a game-title demo). +- [`bold-confident-vibrant-saturated-single-ip-game-title.md`](bold-confident-vibrant-saturated-single-ip-game-title.md) - Bold-confident-vibrant-saturated single-IP marketing register applied to a post-launch AAA action game title (the first single-IP marketing entry; the title side of the game-studio pair, claiming the saturated leap the studio brief reserved). +- [`minimal-essentialist-documentary-honest-trades-directory.md`](minimal-essentialist-documentary-honest-trades-directory.md) - Minimal-essentialist-documentary-honest directory-marketplace register applied to a homeowner-facing local-trades directory (the first directory-marketplace shape and the first multi-provider entry; encodes the multi-provider conventions and the no-fabricated-reviews resolution). +- [`luxe-considered-curated-stays-directory.md`](luxe-considered-curated-stays-directory.md) - Pure-luxe-considered directory-marketplace register applied to an aspirational curated short-term-stays marketplace (the second directory-marketplace entry; the same-shape divergence partner to the trades directory, showing the shape across two opposite registers; reframes the multi-provider conventions for hosts and stays). + +Each seed file was built against a real shipped demo or shipped brief and reflects the references that build drew from. As the portfolio grows, the bank grows with it. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md new file mode 100644 index 0000000..3717ecd --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md @@ -0,0 +1,23 @@ +# Bold-confident-editorial-restrained, AAA-adjacent action game studio + +- Archetype: `bold-confident` with `editorial-restrained` as the composition secondary. The lead is the cinematic-confident register of AAA-adjacent action studios; the secondary is chrome restraint (the platform-versus-content distinction from the gaming and entertainment vertical file: a studio is the chrome around its games, so the chrome composes while the game key art carries the saturation). The composition is the explicit chrome-restraint dial: pure Bold Confident or composed-with-Vibrant-Saturated is reserved for single-game-title demos. +- Vertical: Corporate-portfolio (specifically AAA-adjacent action game studio: a content-creator studio that builds large-scale action games and presents itself as a serious craft-and-scale shop). +- Position summary: A studio whose chrome is composed and dark-mode-first, where each fictitious title's key art carries the saturation and energy. Cinematic full-bleed hero, titles portfolio strip, type-led studio band, careers band as the load-bearing conversion surface, dark CTA close. + +## Positive references + +- [bungie.net](https://bungie.net) - The canonical AAA-action studio chrome register: cinematic full-bleed key-art hero, dark-mode-first ground, restrained type chrome that lets the game art carry. Inherit the cinematic hero treatment, the dark ground, and the chrome restraint. +- [insomniac.com](https://insomniac.com) - Insomniac Games. The studio chrome at composed-cinematic; the titles portfolio surfaced with care. Inherit the titles-portfolio anatomy and the craft-proud-without-arrogance voice. +- [naughtydog.com](https://naughtydog.com) - Naughty Dog. The restrained-cinematic studio register; type-led studio band with the team presented at masthead density. Inherit the studio-band convention and the restrained-cinematic chrome. +- [remedygames.com](https://remedygames.com) - Remedy Entertainment. The composed-cinematic register at the studio level, with a smaller portfolio presented with editorial discipline. Inherit the title-detail-page-as-small-monograph anatomy. + +## Negative references + +- [steampowered.com](https://steampowered.com) - Steam. Platform chrome that hosts third-party content. Wrong vertical (platform, not studio); the platform chrome reads totally different from a studio's content-creator brand. +- [itch.io](https://itch.io) - Itch.io. Indie game platform; minimal chrome; wrong register and wrong vertical. +- Mobile and casual free-to-play studio sites (the bright-saturated multi-hue cartoon register of casual-mobile studio brands). Wrong register; a AAA-adjacent action studio is not casual-mobile. +- Streaming-service sites (netflix.com, hbomax.com). Adjacent Bold-Confident-leaning register but wrong vertical (streaming distribution vs studio creation). Netflix's content-as-hero treatment is a useful inheritance for the cinematic hero; the rest of Netflix's chrome is platform-distributor, not studio. + +## Extension note + +- Seeded from the Ironhold AAA-adjacent action studio brief (first portfolio entry in Bold Confident; first portfolio entry in the corporate-portfolio shape applied to a game studio). The brief is the gentler entry into Bold Confident in the showcase portfolio; the upcoming game-title demo is the leap into the saturated single-IP register. The studio composes with Editorial Restrained as the chrome-restraint dial so the title-demo can pull saturation further without colliding. The brief documents a Rule 4 WARN override on the full-bleed-image-with-overlay hero (the canonical AAA-studio cinematic treatment, four shipped matches but no archetype-family share so Rule 5 does not block; the override is justified by the new archetype carrying the shape into a completely different visual reading). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md new file mode 100644 index 0000000..a3e23c8 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md @@ -0,0 +1,24 @@ +# Bold-confident-vibrant-saturated, single-IP game-title marketing site + +- Archetype: `bold-confident` with `vibrant-saturated` as the composition secondary. The lead is the cinematic-confident register of AAA action titles; the secondary is the saturated leap (palette depth, type at title-card scale, key art as the load-bearing surface). This is the expressive content-brand end of the gaming and entertainment vertical, distinct from the studio-portfolio chrome that publishes the title. The pair to `bold-confident-editorial-restrained-aaa-game-studio`: the studio composes with Editorial Restrained chrome restraint, the single title composes with Vibrant Saturated to claim the saturation the studio reserved. +- Vertical: Single-IP marketing (specifically a post-launch AAA action game title: the marketing site where one shipped game lives, distinct from the studio portfolio that publishes it). The shape generalizes to any single published work (a single film, album, book, or show); the references here are the game-title instance. +- Position summary: A single published title's own brand, dark-mode-first, world-forward, where the world's own palette and the key art carry the saturation. Cinematic launch-poster hero, a trailer or curated key-art sequence, a world-immersion surface, a systems surface, a media gallery, and a follow-or-storefront conversion close. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (dark-mode-first, world-forward, saturated, cinematic) and pulls NO trade dress, layout, scroll behavior, font choice, or animation language from any specific real-game marketing site. Marketing-site mimicry is as off-limits as in-game resemblance. + +- [marathonthegame.com](https://marathonthegame.com) - The saturated single-IP marketing register at its most committed: a published title's own brand, dark-mode-first, with the title's palette and art carrying the saturation rather than the publisher's chrome. Inherit the world-forward saturated register; do NOT pull the flat-graphic identity or layout. +- [deathstranding.com](https://deathstranding.com) - Single-IP world-immersion marketing: the site immerses the visitor in one world (the setting, the lore) in the game's own voice rather than the studio's. Inherit the world-as-protagonist surface; do NOT pull the atmospheric scroll, type, or identity. +- [cyberpunk.net](https://cyberpunk.net) - Saturated single-IP launch register: type at title-card scale, palette depth carrying the world's own tones. Inherit the type-at-scale and palette-depth treatment; do NOT pull the neon-magenta identity. +- [eldenring.bandainamcoent.com](https://eldenring.bandainamcoent.com) - Single-IP lore-immersion marketing: a world page that treats the world as the protagonist with deep lore in the title's voice. Inherit the lore-immersion surface; do NOT pull the dark-fantasy identity. + +## Negative references + +- Studio and publisher portfolio sites ([bungie.net](https://bungie.net), [naughtydog.com](https://naughtydog.com), and the paired `bold-confident-editorial-restrained-aaa-game-studio` register) - The studio chrome composes and recedes to let many titles share a body of work. The single-IP title's register is the saturated content brand, distinct from the publisher's chrome; a single title is not a portfolio. +- Platform-chrome sites ([steampowered.com](https://steampowered.com), [store.epicgames.com](https://store.epicgames.com), [itch.io](https://itch.io)) - Platforms host third-party content and lean restrained to let the content carry. A single-IP marketing site is the content's own brand, not the platform that distributes it. +- Casual and mobile single-game marketing sites (the bright multi-hue cartoon register of casual-mobile single-game brands) - Wrong register; an AAA cinematic title is dark-mode-first and world-forward, not bright-cartoon. + +## Extension note + +- Seeded from the Mariner's Gauntlet single-IP marketing brief (first portfolio entry in the single-IP marketing shape; the title side of the Ironhold pair; the first portfolio entry composing with Vibrant Saturated). The title claims the saturated single-IP register that the paired studio brief (`bold-confident-editorial-restrained-aaa-game-studio`) deliberately reserved as forward-divergence headroom. The brief documents the framework's first Rule 5 BLOCK against a same-pair shipped demo: `full-bleed-image-with-overlay` is blocked (five shipped matches plus a shared Bold Confident family with the publisher Ironhold), so the title selects `centered-single-column` as a cinematic launch-poster hero, the intended divergence-within-the-pair. Footer is `newsletter-band-with-credits` (the follow-the-title conversion). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md new file mode 100644 index 0000000..6e98079 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md @@ -0,0 +1,22 @@ +# Editorial-restrained, documentary-honest, specialty coffee subscription + +- Archetype: `editorial-restrained` with `documentary-honest` as the composition secondary. The lead is editorial type-led restraint (low-saturation, generous whitespace, considered typography); the secondary is documentary farm and bean photography that grounds the single-origin claim. Premium but approachable; not luxury, not mass-market. +- Vertical: DTC food and beverage (specifically specialty coffee subscriptions; the references generalise to tea and other consumable single-origin subscriptions in adjacent registers). +- Position summary: A specialty single-origin coffee subscription in the editorial-restrained register. Subscriber-first commerce (cadence picker, pause and swap surfaced as features, not buried in account settings). Named farms, named processes, named roast dates. Documentary farm photography supports the type rather than leads. + +## Positive references + +- [drinktrade.com](https://drinktrade.com) - Subscriber-first commerce explicit: cadence picker on the home, match-quiz to find your roast, pause and swap surfaced as features rather than buried in account settings. Editorial-restrained type-led layout with documentary product photography. +- [counterculturecoffee.com](https://counterculturecoffee.com) - Specialty roaster with subscription surfaced; documentary photography of farms and farmers carries the page; editorial type. The canonical reference for "farm-direct specialty roaster with a subscription option." +- [onyxcoffeelab.com](https://onyxcoffeelab.com) - Editorial-restrained register at its most refined: type-led, considered photography, premium-but-approachable. Useful as the type-system reference (small-caps, restrained tracking, editorial serifs). +- [atlascoffeeclub.com](https://atlascoffeeclub.com) - Subscriber-first explicitly with a world-coffee-journey narrative. The closest match to the "one origin a month, named farm, named process" positioning. Useful for how to surface the rotation as the value prop. + +## Negative references + +- [starbucks.com](https://starbucks.com) - Mass-market grocery register; frappuccino lifestyle photography; promotional cadence dominates the homepage. The register a specialty roaster must not pull from. +- [folgers.com](https://folgers.com) - Commodity grocery brand; blue-can heritage but no specialty register. The bottom of the grocery shelf, conceptually. +- Generic lifestyle-influencer subscription boxes (BarkBox, FabFitFun, Allure Beauty Box and similar) - Lifestyle-spectacle subscription register where the unboxing is the product; the box itself is supposed to be a surprise. Wrong register entirely for a specialty-coffee subscription where the named farm and the roast date are the value, not the unboxing reveal. + +## Extension note + +- Seeded by the Northbound Coffee Co. brief (Phase 2 live pressure-test of the creative-brief-selector skill, rampstack/rampstackco-app PR #131). The brief was the first live invocation of the selector and discovered these references during step 3 because the bank had no seed for the specialty-coffee-subscription combination. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md new file mode 100644 index 0000000..a6c7c02 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md @@ -0,0 +1,25 @@ +# Editorial-restrained, literary quarterly + +- Archetype: `editorial-restrained` (pure, no composition secondary). The lead is the literary quarterly tradition: typography carries the page, the considered editorial register, the restrained accent, and the absence of marketing inflation. +- Vertical: Editorial publication (specifically themed literary and ideas quarterly with multi-author masthead, each issue organized around a single question or theme). +- Position summary: A themed literary quarterly where each issue is a single question, the table of contents reads as variations on the question across disciplines, the design is restrained-considered with one literary accent colour. Not politically situated, not generationally branded, not topical, not single-author. The audience is literary readers across disciplines. + +## Positive references + +- [aeon.co](https://aeon.co) - Multidisciplinary ideas register. Considered design, restrained palette (warm-grey ground with deep type and a single accent), essays at substantial length, multiple disciplines per surface. Inherit the ideas-led register, the considered-but-not-luxe typography, the absence of marketing inflation. +- [thepointmag.com](https://thepointmag.com) - Themed multi-author essay structure at length. The closest peer on the audience axis (broadly literary readers across disciplines). Inherit the multi-author themed-issue treatment and the essay-length expectation. +- [cabinetmagazine.org](https://cabinetmagazine.org) - The closest structural anchor in the field: each issue is organized around a single thematic question rendered with editorial restraint. Inherit the single-theme-per-issue structure and the question-as-masthead treatment. +- [canopycanopycanopy.com](https://canopycanopycanopy.com) - Triple Canopy. Themed digital-first sequenced issues with editorial restraint. Inherit the digital-first design discipline and the sequenced-issue numbering. + +## Negative references + +- [thedriftmag.com](https://thedriftmag.com) - Politically situated, generationally branded, identity-forward. A considered quarterly must avoid the political-statement register on conversion architecture, palette, and voice. +- [nplusonemag.com](https://nplusonemag.com) - Institutional NY cultural authority register. A considered quarterly should not borrow the geographic or generational positioning. +- [laphamsquarterly.org](https://laphamsquarterly.org) - Historical-source-driven format (passages from historical writing assembled around a theme). A different format entirely; canonical to that publication and not transferable. +- [believermag.com](https://believermag.com) - McSweeney's-adjacent geometric illustration identity. A type-led quarterly should not borrow the illustration-led visual treatment. +- [atavist.com](https://atavist.com) - Single-essay-per-issue reportage register. A multi-essay themed quarterly is a different shape. +- [themarginalian.org](https://themarginalian.org) - Single-author blog register. A multi-author themed quarterly is a different shape. + +## Extension note + +- Seeded from the Caesura editorial-publication brief (the first portfolio entry in the editorial-publication shape, using the extended creative-brief-selector framework with hero_shape and footer_shape as first-class outputs). The pure `editorial-restrained` archetype combined with the type-led-prose hero and editorial-colophon-with-masthead footer renders as the natural literary-publication fit; the framework's extended rules align with the register's tradition rather than fighting it. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md new file mode 100644 index 0000000..ec9fae5 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md @@ -0,0 +1,20 @@ +# Heritage local service, barbershop + +- Archetype: `warm-conversational` with `retro-nostalgic` as the composition secondary. The lead is warm-everyday-craft (real-room atmosphere, social proof from genuine reviews, real-team page); the secondary is period-specific cues (walnut wood, brass fittings, marble counters, restrained palette). +- Vertical: Hospitality and local service (specifically neighborhood barbershops). +- Position summary: A heritage neighborhood shop with craft-and-space-led atmosphere, real-people-real-work proof, social proof drawn from review aggregates rather than fabricated testimonials. Initials over fabricated portraits when fictitious-brand demos cannot ethically render faces. + +## Positive references + +- [therosemontbarbers.com](https://therosemontbarbers.com) - Cuts gallery, interior atmosphere, social-proof badge, real team page in the heritage register. +- [speakeasybarberlounge.com](https://speakeasybarberlounge.com) - Atmosphere-led, period-specific cues (lounge fittings, warm interior), interior photography carries the page. +- [franksdenver.com](https://franksdenver.com) - Heritage register at a higher-end price point; restrained palette, considered editorial layout. +- [alfanisbarbershop.com](https://alfanisbarbershop.com) - Small-operator heritage, atmosphere-forward, real-team page. + +## Negative references + +- The chain barbershop register (Great Clips, Supercuts, Sport Clips and the like) - High-volume operational chains in the same vertical but in a fundamentally different register: utility-led, promotion-driven, no atmosphere. A heritage maker pulling from this register loses the position. + +## Extension note + +- Seeded from the Iron and Rye Barbershop atmosphere imagery pass. The seed positive references were used as register cross-checks during the build's still-life and interior shots. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md new file mode 100644 index 0000000..3b4fced --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md @@ -0,0 +1,20 @@ +# Hospitality experience, balloon ride + +- Archetype: `documentary-honest` with `luxe-considered` as the composition secondary. The lead is photography-led documentary realism (real landscape, real light, the morning as it actually looks); the secondary is aspirational-experience polish (named arc, named prices, named safety signals). +- Vertical: Hospitality experience (specifically scenic flight or ride experiences, with the balloon ride as the worked example). +- Position summary: A photography-led experience operator with the morning arc surfaced explicitly, named packages with named prices above the fold, four trust signals (FAA certification, lead pilot hours, weather posture, cancellation) surfaced as the booking-confidence layer. No fabricated identifiable faces; environmental imagery only. + +## Positive references + +- [napavalleyaloft.com](https://napavalleyaloft.com) - Regional operator, atmosphere-forward, dawn-palette imagery. +- [aerogelichotairballooning.com](https://aerogelichotairballooning.com) - Atmosphere-led, ride arc surfaced, photography drives the page. +- [rainbowryders.com](https://rainbowryders.com) - Multi-region operator, photography-led, named packages with prices. +- [sundanceballoons.com](https://sundanceballoons.com) - Multi-region operator, considered-warm register, ride-arc framing. + +## Negative references + +- Generic adventure-tour aggregators (Viator, GetYourGuide, and similar) - Stock photography pile, undifferentiated palette, transactional layout. A photography-led operator pulling from this register loses the atmosphere that justifies the price. + +## Extension note + +- Seeded from the Drift and Dawn imagery pass and the audited-field competitor set used during that build's Stage 1. The dawn-palette retune was driven by the gap between the original stone-and-amber default and the actual dawn light these references carry. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md new file mode 100644 index 0000000..52aff00 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md @@ -0,0 +1,33 @@ +# Luxe-considered, curated short-term-stays directory-marketplace + +- Archetype: `luxe-considered` (pure; no composition secondary). The aspirational curated-stays register the hospitality vertical file names as Aman and Four Seasons: serif-led, understated authority, image-forward, the stay as a designed object. The escapist warmth is carried by a warm palette and a host-voice convention, not by a second archetype. Documentary Honest (the mass-market Airbnb register and a recurring portfolio secondary), Editorial Restrained (another build's exact luxe composition string), and Warm Conversational (the review-platform register) were each considered and rejected as secondaries; pure Luxe is the fit. +- Vertical: Directory-marketplace (specifically an aspirational curated short-term-rental marketplace of many independent hosts' standout stays). The second directory-marketplace entry in the bank; with the trades-directory entry it shows the shape across two opposite registers (functional-tool versus escapist-aspirational). +- Position summary: A small, curated marketplace a traveler dreams through, where the property photography carries the page and the stay is the product. Image-forward, escapist, design-forward; inventory grouped into curated collections; trust built on a stated verification claim rather than a fabricated-metric arms race. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (curated collections, image-forward discovery, the property-as-monograph, restrained booking affordances) and pulls NO palette, type, trade dress, photography style, or grid treatment from any specific real platform. + +- [plumguide.com](https://plumguide.com) - The curated-design short-term-stay register: a small vetted collection rather than the long tail, each stay presented with editorial care. Inherit the curated-collection posture and the property-as-monograph anatomy; do NOT pull the palette, type, or the specific listing-grid treatment. +- [boutique-homes.com](https://boutique-homes.com) - The design-led curated-stays register: architecturally distinctive properties grouped by design feeling. Inherit the design-forward collection grouping and the generous property gallery; do NOT pull the trade dress. +- [onefinestay.com](https://onefinestay.com) - The upper-curated hospitality register: a small set of standout homes with a hotel-grade presentation. Inherit the restrained-confident chrome and the aspirational photo direction; do NOT pull the palette or the brand identity. + +## Negative references + +- Functional-tool consumer directories (the trustworthy-direct-functional trades-directory neighbourhood; the same directory-marketplace shape in the opposite register). The functional tool a user controls is the deliberate opposite of the escapist marketplace a traveler dreams through; the shape and the multi-provider conventions are shared, the register is inverted. +- Single-operator hospitality-experience brands (one operator selling its own arc). The count axis differs: a curated-stays marketplace lists many independent hosts, not one operator's owned experience. +- Mass-market transactional rental platforms (the high-volume long-tail booking engines with urgency banners, opaque ranking, and dense result grids). Wrong register: a curated marketplace presents a small standout set as a publication, not the whole inventory as a funnel. + +## Multi-provider conventions (reframed for hosts and stays) + +The directory-marketplace shape's multi-provider conventions (first encoded by the trades-directory entry) carry forward, reframed from providers to hosts and stays: + +- Brand versus host voice. The marketplace brand's voice is the site voice throughout; each property carries a short host voice (a one-line note on why the place is worth the trip) only inside its card and detail, set with a typographic voice-shift. The brand never speaks as a host; hosts never speak as the brand. +- Discoverability is the spine, image-forward. The home is a search-and-browse surface where the property photography carries the page (the aspirational counterpart to the functional-categorical discovery of a trades directory). The hero is image-forward, not a functional tile grid. +- Listing density, organized as collections. Curated themed collections (coastal escapes, design landmarks, mountain retreats) rather than flat categories; roughly 4 to 6 collections with 4 to 8 properties each (24 to 40 properties). The collection is itself an editorial act. +- Comparison surface. Properties comparable within a collection on a small honest set (location, sleeps, stay-type, a demo-only rate band), with a within-collection compare view. +- Reviews-and-ratings honesty resolution. A demo-only Verified Host badge with its meaning stated plainly, plus an explicit "Demo: no reviews shown" placeholder slot and an aggregate-rating placeholder. The full trust UX is visible without fabricating a single review, rating, or superhost-style metric. Hosts are represented by their properties and a one-line voice, NOT by fabricated headshots; properties are set in fictitious locations; no real platform is named, even in negation. + +## Extension note + +- Seeded from the Lodestar curated-stays marketplace brief (the fifteenth and final showcase demo; the second directory-marketplace shape and the same-shape divergence partner to the trades-directory entry, running maximal-distance mode within the shape). Anchored to the hospitality and travel vertical file (`12-hospitality-travel.md`), which names pure Luxe Considered as the aspirational-hospitality register and Documentary Honest as the mass-market Airbnb register. The styled-aspirational property photography carries a real drift profile for the imagery pass: real-listing-platform aesthetic mimicry and fabricated-location-resemblance, both flagged for the build's NEGATIVE_GUARDRAILS, plus no real brand marks in any property image. The palette must read warm-aspirational (a design-hotel sandstone-clay-brass family) and must not reuse the trades-directory's cool functional family or any shipped warm-hospitality family. Last updated: 2026-05-29. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md new file mode 100644 index 0000000..aaf9c53 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md @@ -0,0 +1,23 @@ +# Luxe-considered-editorial-restrained, residential architectural brokerage + +- Archetype: `luxe-considered` with `editorial-restrained` as the composition secondary. The lead is the gallery-monograph register: premium, considered, type-and-photography-led, design-literate. The secondary is design-publication restraint: listings rendered as small monographs, the architect-and-year credit at byline weight, the brokerage represented as a practice rather than as a roster of agents. +- Vertical: Inventory-listing (specifically residential brokerage of architecturally significant homes: modernist, mid-century, architect-designed new builds, design-forward renovations). +- Position summary: A luxe residential brokerage that treats each architecturally significant home as a small monograph. The architect, the design year, the materials, the siting, and the light are first-class fields on every listing. The brokerage speaks as a design-literate practice rather than as a roster of individual agents. + +## Positive references + +- [themodernhouse.com](https://themodernhouse.com) - The canonical reference for the design-led residential brokerage register at editorial-restrained tier. Each listing reads as a small monograph; the architect is named in the listing card; the photography is disciplined. Inherit the listing-as-monograph anatomy and the considered-restraint voice. (Cited as a register anchor, not for trade dress copy; the negative-reference frame governs which brokerages a build must not pull trade dress from.) +- [phillips.com](https://phillips.com/design) - Phillips's design auction catalog register. The monograph treatment per lot (designer, year, materials, provenance) transfers cleanly to a residential listing. Inherit the per-lot monograph anatomy. +- [dezeen.com](https://dezeen.com) - The architectural press register. Listing-style architecture coverage with architect credits, year, materials, photography. Inherit the architecture-press literacy and the credit-line convention. +- [architecturaldigest.com](https://architecturaldigest.com) - The design-publication register with residential homes covered as design objects. Inherit the photography sensibility and the design-publication restraint. + +## Negative references + +- [zillow.com](https://zillow.com) - Mass-market portal; algorithmic listing presentation, estimated-value overlays, financing-first conversion. The register a luxe-considered brokerage must avoid on conversion architecture, palette, and voice. +- [realtor.com](https://realtor.com) - Same mass-market portal register; broker-listing-syndication shape, generic photography presentation. +- [redfin.com](https://redfin.com) - Mass-market portal with light brokerage layer; price-anxiety scoring, financing partnerships surfaced as primary CTAs. +- High-volume luxury brokerages whose primary surface is personality-led agent funnels. The architectural-monograph register is a practice, not a personal brand; the no-fabricated-agent-headshots line in the honesty contract is the structural rationale. + +## Extension note + +- Seeded from the Datum residential-brokerage brief (the first portfolio entry in luxe-residential-architectural-brokerage and the first same-shape divergence test in the portfolio; second inventory-listing build, the first being the rugged-utilitarian Treeline Motors marketplace). The brief documents the Section Shapes Rule 5 block on the two obvious luxe-architectural defaults (full-bleed-image-with-overlay and dual-column-image-and-text) and the resulting selection of asymmetric-large-image-small-text as the hero shape. Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md new file mode 100644 index 0000000..5083d66 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md @@ -0,0 +1,34 @@ +# Minimal-essentialist-documentary-honest, local-trades directory + +- Archetype: `minimal-essentialist` with `documentary-honest` as the composition secondary. The lead is the functional-tool register (clean, organized, content-forward, reduced chrome; the page is the directory and the chrome recedes to let the listings carry). The secondary is honest-transparency trust (a stated verification claim, honest placeholders where reviews would render, real-context provider photography). The marketplace platform-versus-provider principle is the structural rationale: the directory brand must not compete with the provider identities, so restraint wins. +- Vertical: Directory-marketplace (specifically a homeowner-facing local-trades directory of many independent providers across real trade categories: plumbing, electrical, HVAC, carpentry, painting, roofing). The first multi-provider entry in the bank. +- Position summary: A clean, trustworthy directory tool the homeowner controls, light-mode-first, where the categories and the providers are the page. Discoverability is the spine, comparison is core, and the trust is built on honest transparency rather than on warmth or on clinical authority. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (search-first discovery, category browse, provider listings, a comparison surface, a verification claim) and pulls NO palette, trade dress, logo language, or conversion-funnel pattern from any specific real directory. + +- [angi.com](https://angi.com) - The modern consolidated home-services directory register: category-and-location search, provider listings, the lead-handoff conversion. Inherit the search-first discovery spine and the category structure; do NOT pull the orange-and-green palette, the match-now funnel, or any trade dress. +- [thumbtack.com](https://thumbtack.com) - The matched-services register: structured by trade and location, provider profiles with comparable fields. Inherit the comparable-provider-profile anatomy; do NOT pull the blue palette or the get-matched interstitial funnel. +- [houzz.com](https://houzz.com) - The visual-services-directory register: real work photography carrying the provider listings. Inherit the documentary work-in-context photography direction (a trade in progress, a finished job), not glamour shots; do NOT pull the green-and-orange palette or the social-feed product framing. + +## Negative references + +- Warm-conversational single-provider service brands (a neighbourhood barbershop, a single local shop's site; the heritage-local-service register). Wrong register and wrong count: that is a single provider speaking warmly about itself, not a directory of many providers in a functional-trust tool. A trades directory must not read as one warm shop with extras. +- Magazine-editorial services-content sites (a home-improvement publication, a services-advice editorial). Wrong register: a directory is a functional tool, not a magazine pretending to be a directory; the editorial-publication register buries the listing density behind a narrative. +- Bold-cinematic or saturated AAA visual registers (a cinematic full-bleed experiential hero). Wrong register entirely: a directory reads functional, not experiential; an image-and-overlay cinema-poster hero is the opposite of the page-is-the-directory discovery spine. + +## Multi-provider conventions (new ground; inherited by future directory-marketplace briefs) + +The directory-marketplace shape is the first multi-provider register in the portfolio. These conventions are first-class and carry forward: + +- Brand versus provider voice. The directory brand's voice is the site voice throughout; each provider has its own short voice only inside its listing card (a one-line how-we-work statement). The directory speaks as the trustworthy tool; the providers speak as themselves inside their cards. (Single-provider builds never had to navigate this distinction.) +- Discoverability is the spine. The home page is a search-and-browse surface (category-and-location search, category tiles, provider cards), not a hero-and-essay narrative. A `grid-of-elements` hero fits naturally; a type-led or image-and-overlay hero does not. +- Listing density. A meaningful directory reads as real only at sufficient density: roughly 4 to 6 categories with 4 to 8 providers each (16 to 48 total). Fewer reads as a single-provider demo with extras; more risks bloat. +- Comparison surface. Providers within a category are comparable on a small honest set of dimensions (service area, specialties, years in business), not on an opaque ranking score. Comparison is core to the pattern. +- Reviews and ratings are the canonical fabrication risk, and the resolution is honest UX without fabricated content. A directory conventionally shows aggregate ratings, review counts, and written reviews; a demo cannot fabricate any of them. The resolution: an explicit "Demo: no reviews shown" placeholder slot where review content and an aggregate rating would render, plus a demo-only "Verified Pro" badge (the directory's own badge, meaning stated, not a real accreditation) where earned. The directory's full trust UX is visible without a single fabricated review, rating, license number, or certification. +- Real categories, fictitious providers. The trade categories are real; the providers within them are demo-fictitious, with names vetted against recognizable businesses (a proprietor-surname-plus-trade format), set in a fictitious city, with schematic service-area maps and no fabricated license numbers, certifications, or accreditation marks. + +## Extension note + +- Seeded from the Tradepost local-trades directory brief (the first directory-marketplace shape and the first multi-provider demo in the portfolio; the seventh selector-led build). The brand-archetype-system has no dedicated home-services, local-services, or trades vertical file; this build used `16-marketplace.md` (the two-sided-platform register) as the closest anchor, and the gap is flagged for a future skill-extension dispatch to add a dedicated local-services-and-trades vertical file. Tradepost runs maximal-distance mode; it is the same-shape divergence partner to a forthcoming vacation rental marketplace (the Browse-AI attended capstone), and the two diverge naturally because the verticals differ. The palette deliberately avoids the recognizable real-brand directory colours (Angi orange-and-green, Thumbtack blue, HomeAdvisor orange, Yelp red, Houzz green-and-orange, Yellow Pages yellow-and-black). Last updated: 2026-05-28. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md new file mode 100644 index 0000000..8a7d341 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md @@ -0,0 +1,22 @@ +# Premium DTC maker, western boots + +- Archetype: `luxe-considered` with `rugged-utilitarian` as the composition secondary. The lead is premium-considered (editorial layout, prices visible, restrained merchandising); the secondary is workwear-and-craft (heritage materials, hand-welt construction, made-to-last positioning). +- Vertical: DTC fashion (specifically western boots). +- Position summary: A premium small-collection western-boot maker, leather-forward, product-photographed, prices visible, no discount cadence, no SKU-strip-above-the-fold. Confident, not promotional. + +## Positive references + +- [tecovas.com](https://tecovas.com) - The elevated-DTC reference: product-forward hero, named prices visible, restrained merchandising. No discount banners above the fold. +- [lucchese.com](https://lucchese.com) - Heritage register; serif-led, craft narrative as a supporting band rather than the lead. +- [oldgringoboots.com](https://oldgringoboots.com) - Smaller-maker, leather-forward photography, restrained editorial set instead of catalog density. +- [ranchroadboots.com](https://ranchroadboots.com) - Small-operator boutique competing in the same position; useful for cross-checking how a peer maker handles wayfinding on a small collection. + +## Negative references + +- [durangoboots.com](https://durangoboots.com) - Catalog-dense big-box texture; discount cadence, SKU-strip-above-the-fold, sale-badge pile. Not the register a premium small maker should pull from. +- [justinboots.com](https://justinboots.com) - Same big-box texture in a different brand; promotional banners and grid density dominate. +- [bootbarn.com](https://bootbarn.com) - Multi-brand retailer rather than a maker; merchandising-led rather than craft-led. + +## Extension note + +- Seeded from the Pinto Mesa Boots store-spine brief (the worked example of the brief template). Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md new file mode 100644 index 0000000..b260e05 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md @@ -0,0 +1,24 @@ +# Rugged-utilitarian-documentary-honest, regional used-vehicle marketplace + +- Archetype: `rugged-utilitarian` with `documentary-honest` as the composition secondary. The lead is workwear-and-craft (Mountain West heritage utility register); the secondary is data-forward documentary (transparency-first listings, real photography, real source attribution). +- Vertical: Inventory-listing (specifically regional used-truck-and-SUV marketplace serving working-vehicle buyers, not full passenger-car market). +- Position summary: A regional working-vehicle specialist marketplace, transparency-first on every listing, documentary photography of vehicles in working context, plain-direct voice that speaks with familiarity of the terrain its audience drives. Specialist, not generalist; transparent, not promotional; regional, not national. + +## Positive references + +- [bringatrailer.com](https://bringatrailer.com) - The canonical listing-detail transparency reference: full ownership history, mileage timeline, photograph density (forty to one hundred photographs per lot is typical), a comments thread that adds provenance. Inherit the listing-detail anatomy and the source-attributed transparency posture. Diverge from the auction format; a fixed-price marketplace borrows the transparency without the closing-clock. +- [icon4x4.com](https://icon4x4.com) - Editorial documentary register applied to working vehicles. Inherit the photography direction (vehicles photographed in landscape and at work, not glamour shots on a studio seamless), the considered editorial type, and the absence of promotional banners. +- [filson.com](https://filson.com) - Mountain West heritage workwear register. Inherit the palette tendency (granite, evergreen, oxblood, aspen gold; cool ground with restrained accents), the documentary photography that supports the type rather than fighting it, and the plain-direct voice. +- [patagonia.com](https://patagonia.com) - The adjacent outdoor-utility register, useful as the second positive on voice (plain-direct, no marketing inflation, the audience treated as competent). + +## Negative references + +- [cargurus.com](https://cargurus.com) - Mass-market national passenger-car register; price-anxiety scoring as the hero, financing-first conversion architecture. The register a specialist regional marketplace must avoid on conversion architecture, palette, and voice. +- [cars.com](https://cars.com) - Same mass-market national register; promotional banner cadence, broad-inventory generalist posture. +- [carvana.com](https://carvana.com) - DTC mass-market with vending-machine theatrics, financing-first. The register to avoid on theatrics and on conversion-flow priority. +- [autotempest.com](https://autotempest.com) - Meta-aggregator with no editorial voice; utility-only search-across-the-others. A specialist marketplace must not read as utility-only. +- [edmunds.com](https://edmunds.com) - Research-led advisory; content-heavy editorial sitting adjacent to a marketplace. A specialist marketplace must not read as a magazine pretending to be a marketplace. + +## Extension note + +- Seeded from the Treeline Motors inventory-listing brief (the second batch-two build using the creative-brief-selector skill end to end). The Bring a Trailer reference is dual-positioned: positive on listing-detail transparency, negative on format (auction vs fixed-price marketplace). Last updated: 2026-05-27. diff --git a/dist/pi/.agents/skills/creative-brief/SKILL.md b/dist/pi/.agents/skills/creative-brief/SKILL.md new file mode 100644 index 0000000..8e18b1c --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/SKILL.md @@ -0,0 +1,158 @@ +--- +name: creative-brief +description: "Create or refine a creative brief that bridges discovery and execution. Use this skill whenever the user is starting a new project, kicking off a website, beginning a brand build or redesign, briefing a designer or developer or AI agent, or trying to align a team before building. Triggers on creative brief, design brief, brand brief, project kickoff, kicking off, briefing the team, project intake, design direction, brief the designer, brief the dev, where do we start, how do we start, write a brief, project overview, scope this project, align on direction. Also triggers when the user has a vague idea and needs to make it concrete enough to hand off, even if they do not say 'brief' explicitly." +category: strategy-and-discovery +catalog_summary: "Project briefs that align stakeholders before work starts" +display_order: 2 +--- + +# Creative Brief + +Bridges discovery and execution. Translates "we want a website" into a brief a designer, developer, or AI agent can actually run with. + +--- + +## When to use + +- Starting a new project (website, app, brand, campaign) +- Kicking off a redesign or rebrand +- Handing work to a designer, developer, or AI agent +- Aligning a team that has drifted off course +- Turning a vague idea into something buildable + +## When NOT to use + +- The user is asking a one-off design question (use `design-standards`) +- The user wants a PRD or dev ticket (use `pm-spec-writing`) +- The user is doing initial research and has not decided what they are building (use `brand-discovery` first) +- The user just wants you to write copy (use `content-and-copy`) +- The user already has scope and constraints settled and needs deeper aesthetic direction specifically (use `creative-direction` for the structured aesthetic axes) + +--- + +## Required inputs + +A brief needs answers to ten questions. Before writing, confirm you have answers (or can elicit them) for: + +1. What is the project? +2. Why does it exist? What problem does it solve? +3. Who is the audience? +4. What do you want them to do, feel, or know? +5. What is the personality? How does it sound? +6. What is the visual direction? How does it look? +7. What is in scope? What is out? +8. What are the constraints (time, budget, technical, brand)? +9. What does success look like? +10. Who approves? + +If you have fewer than five of these, run a quick intake first. See "Eliciting missing info" below. + +--- + +## The framework: brief structure + +Output a markdown brief with these ten sections. Keep each section tight. A good brief is two pages, not ten. + +### 1. Snapshot +One paragraph answering: what, who, why, when. The kind of thing you would say at a kickoff in thirty seconds. + +### 2. Audience +Primary audience first. Include who they are, what they are trying to do, what is blocking them today, and where you reach them. Add secondary audiences only if they materially change the work. + +### 3. Objectives +What success looks like. Pair every objective with a measurable signal. + +> Objective: drive trial signups. +> Signal: 3 percent conversion from homepage to signup within 30 days of launch. + +### 4. Key message +The one thing you want a visitor to walk away knowing. If they see only the homepage hero and bounce, what should they remember? One sentence. + +### 5. Voice and tone +Pick three to five adjectives. Pair each with what you are NOT (e.g. "confident, not arrogant"). See [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) for frameworks and worked examples. + +### 6. Visual direction +Mood, palette, type, and imagery direction. Three to five reference URLs are worth more than 500 words. Note what you like AND what you would reject. + +### 7. Scope and deliverables +A bulleted list of what is being made. Be specific. "Homepage" is not a deliverable. "Homepage with hero, three feature blocks, testimonial carousel, and contact CTA" is. + +### 8. Constraints +Time. Budget. Technical (existing stack, required integrations, hosting). Brand (logo, colors, fonts that must be used). Legal (compliance, accessibility level required). + +### 9. Inspiration and competitors +Three to five sites or brands you want to feel like, three to five you want to feel different from. Note WHY for each. + +### 10. Approval +Who signs off. What artifact triggers sign-off (a Figma file, a staging URL, a PDF). What happens if there is no sign-off by a deadline. + +--- + +## Eliciting missing info + +If the user comes with a partial answer (e.g., "I want a website for my coffee shop"), do not just write a generic brief. Ask. Use these prompts. + +For audience +- Who is the single most likely person to land on this site? Walk me through their day. +- If you could pick one type of customer to fill your inbox, who? +- Who do you NOT want to attract? + +For objectives +- Pretend it is six months after launch. What number tells you it worked? +- What is the one action you most want a visitor to take? + +For voice +- Pick three brands or people whose tone you would want to borrow. +- If your site were a person at a dinner party, what would they sound like? + +For visuals +- Show me three sites you love. What do you love about them? +- Show me one site you hate. Why? + +For scope +- If you only got one page, which one? +- What would you cut if the budget were halved? + +Do not ask all of these. Pick the ones that fill the actual gaps. + +--- + +## Workflow + +1. Read the conversation. Pull every fact already given. Do not ask questions you can answer from context. +2. Identify gaps. Which of the ten required inputs are missing or thin? +3. Run intake. Ask three to five targeted questions to fill the gaps. Group related questions to keep the conversation tight. +4. Draft the brief. Use [`references/creative-brief-template.md`](references/creative-brief-template.md) as the structure. Keep it under 1500 words. +5. Stress-test. Before delivering, check the brief against the failure patterns below. If any apply, revise before showing the user. +6. Deliver. Save as `creative-brief.md` in the project root. Offer to make it a Word doc or PDF if the user wants something to share with stakeholders. +7. Hand off for aesthetic depth (optional). For projects where sections 5 (voice and tone) and 6 (visual direction) need more rigor than this brief surfaces, run `creative-direction` next. It produces a structured aesthetic brief using four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) that content, copy, and art-direction skills consume directly. + +--- + +## Failure patterns + +When the user's input matches one of these patterns, push back before writing. + +- "We want to be the [giant brand] of [our niche]." Ask what specifically about that brand they want to borrow. Probably one or two things, not the whole thing. +- Audience as "men and women 18-65." This is not an audience. Ask for the single most valuable customer type and start there. +- "Increase awareness" with no metric. Awareness of what, by whom, measured how? Push for a number. +- "Modern, clean, minimalist." These words are meaningless. Ask for three specific URLs they think look right. +- Twenty pages of context, no clear ask. Ask: "If a designer reads only one paragraph, what should it be?" Then make that the snapshot. + +--- + +## Output format + +Default output is a markdown file at `creative-brief.md` in the project root. Structure follows the template exactly. + +If the project is large, split: keep the main brief under 1500 words and put detail in linked appendices (`audience-research.md`, `brand-guidelines.md`, etc.). Briefs that try to be everything end up read by no one. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Fillable template. Copy and use as the starting point. +- [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) - Voice frameworks, brand archetypes, and worked patterns. +- [`references/example-brief.md`](references/example-brief.md) - A worked example for a fictional B2B SaaS, showing what a "good" filled brief looks like. + +Read the template before drafting. Read the voice guide if the user has not already specified a voice. Read the example if you are unsure how filled-out a section should be. diff --git a/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md b/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md new file mode 100644 index 0000000..7d57fc3 --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/creative-brief-template.md @@ -0,0 +1,185 @@ +# Creative Brief: [Project Name] + +Date: [YYYY-MM-DD] +Author: [Who wrote this brief] +Stakeholders: [Who needs to sign off] +Status: Draft / In review / Approved + +--- + +## 1. Snapshot + +[One paragraph. What is this project, who is it for, why does it exist, and when does it need to be done? Aim for 3 to 5 sentences.] + +Quick facts +- Project type: [Website / app / brand / campaign / other] +- Launch target: [Date or quarter] +- Budget tier: [Range or "to be confirmed"] +- Stack constraints: [Required tech or "open"] + +--- + +## 2. Audience + +Primary audience + +Who: [One specific persona, not a demographic range] + +What they are trying to do: [The job they are hiring this product to do] + +What is blocking them today: [The friction they are experiencing now] + +Where you reach them: [Channels: search, social, referral, paid, etc.] + +Secondary audience (only if it changes the work) + +[Same structure, briefer.] + +Anti-personas + +- [Type of customer you do NOT want to attract, and why] + +--- + +## 3. Objectives + +\| Objective \| Measurable signal \| Timeframe \| +\|---\|---\|---\| +\| [What you want to achieve] \| [How you know it worked, with a number] \| [When you measure] \| +\| \| \| \| +\| \| \| \| + +--- + +## 4. Key message + +[One sentence. If a visitor saw only the hero and bounced, what should they remember?] + +--- + +## 5. Voice and tone + +We sound: [3 to 5 adjectives] + +We do not sound: [The mirror image of each adjective] + +\| We are \| We are NOT \| +\|---\|---\| +\| [Adjective] \| [What it could tip into if overdone] \| +\| \| \| +\| \| \| + +Examples of our voice in the wild + +- [Brand or writer 1, and what specifically about them] +- [Brand or writer 2, and what specifically about them] + +--- + +## 6. Visual direction + +Mood: [3 to 5 words] + +Palette direction: [Light/dark, warm/cool, saturated/muted, plus any required brand colors] + +Type direction: [Serif/sans, display vs body, formal vs casual] + +Imagery direction: [Photography style, illustration style, iconography] + +Reference sites we want to feel like + +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] + +Reference sites we want to feel different from + +- [URL]: [What we are rejecting] +- [URL]: [What we are rejecting] + +--- + +## 7. Scope and deliverables + +In scope + +- [Specific deliverable 1, with detail] +- [Specific deliverable 2, with detail] +- [Specific deliverable 3, with detail] + +Out of scope + +- [Things explicitly not being built in this project] + +--- + +## 8. Constraints + +Timeline + +- [Milestone 1]: [Date] +- [Milestone 2]: [Date] +- [Launch]: [Date] + +Budget + +- [Range or specific number, plus what it covers] + +Technical + +- Existing stack: [What is already in place] +- Required integrations: [Analytics, CRM, payment, etc.] +- Hosting: [If specified] + +Brand + +- Required: [Logo, colors, fonts, marks that must be used] +- Available: [Brand assets the team can pull from] + +Legal and compliance + +- Accessibility level: [WCAG AA / AA+ / AAA] +- Privacy: [GDPR / CCPA / other] +- Industry: [Any sector-specific requirements] + +--- + +## 9. Inspiration and competitors + +Inspiration (the feel we want) + +\| Site / brand \| What we love \| +\|---\|---\| +\| [URL] \| [Specific element] \| +\| [URL] \| [Specific element] \| +\| [URL] \| [Specific element] \| + +Competitors (in our category) + +\| Site / brand \| How we differ \| +\|---\|---\| +\| [URL] \| [Where we want to position differently] \| +\| [URL] \| [Where we want to position differently] \| + +--- + +## 10. Approval + +Sign-off owner: [Name, role] + +Sign-off artifact: [What needs to be approved: brief, comps, staging URL, etc.] + +Sign-off deadline: [Date] + +If no sign-off by deadline: [Default action: ship anyway, escalate, pause, etc.] + +--- + +## Appendix (optional) + +Link out to anything that would otherwise bloat the brief. + +- [Audience research] [link] +- [Competitive analysis] [link] +- [Brand guidelines] [link] +- [Technical requirements] [link] diff --git a/dist/pi/.agents/skills/creative-brief/references/example-brief.md b/dist/pi/.agents/skills/creative-brief/references/example-brief.md new file mode 100644 index 0000000..cef9a7f --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/example-brief.md @@ -0,0 +1,206 @@ +# Creative Brief: Plumb + +Date: 2026-04-15 +Author: Maria Chen, Founder +Stakeholders: Maria Chen (sign-off), Devon Park (engineering), Sasha Williams (design lead) +Status: Approved + +--- + +## 1. Snapshot + +Plumb is infrastructure observability built for small DevOps teams. We are launching a marketing site and product trial flow to support our public beta in Q3 2026. The site needs to convert technical buyers from a homepage visit to a trial signup, and clearly position us as the "right-sized" option against the heavy enterprise incumbents. Target launch: July 15, 2026. + +Quick facts +- Project type: Marketing website + trial signup flow +- Launch target: July 15, 2026 +- Budget tier: $25K design + dev, plus internal team time +- Stack constraints: Next.js + Vercel, with Supabase for the trial flow + +--- + +## 2. Audience + +Primary audience + +Who: A staff or principal engineer at a 20 to 200 person startup, currently the unofficial owner of the team's monitoring stack. They got handed Datadog two years ago, the bill is now embarrassing, and they want a defensible alternative they can sell internally. + +What they are trying to do: Cut the monitoring bill by at least 40 percent without taking on a tool that requires a dedicated SRE to operate. + +What is blocking them today: Datadog is too expensive and too sprawling. Grafana is technically free but burns engineering time on maintenance. Both feel built for someone three sizes bigger. + +Where you reach them: Hacker News, the changelog blog, lobste.rs, technical Twitter, dev-focused podcasts (Changelog, Software Engineering Daily), and search ("alternative to datadog", "self-hosted monitoring small team"). + +Secondary audience + +Engineering managers and CTOs at the same companies, who sign the invoice. They land later in the journey but need the pricing page and the ROI math to be airtight. + +Anti-personas + +- Enterprise procurement teams. We do not want to attract Fortune 500 inbound. The product is not built for that scale and we do not want to spend cycles on RFPs. +- Hobbyists who want a free forever tier. We have a generous trial but no free tier. Bargain hunters churn. + +--- + +## 3. Objectives + +\| Objective \| Measurable signal \| Timeframe \| +\|---\|---\|---\| +\| Drive trial signups from organic and content channels \| 200 trial signups per month within 90 days of launch \| By Oct 15, 2026 \| +\| Convert trials to paid \| 12 percent trial-to-paid conversion \| By end of Q4 2026 \| +\| Establish technical credibility \| 50+ inbound mentions on HN, lobste.rs, or dev Twitter referencing the site or docs \| By end of Q3 2026 \| +\| Reduce sales cycle for inbound \| Pricing page transparent enough that 80 percent of inbound deals close without a sales call \| Ongoing \| + +--- + +## 4. Key message + +Plumb is observability that fits a 50-person engineering team, priced for a 50-person engineering team. + +--- + +## 5. Voice and tone + +We sound: Direct, technical, confident, dry-witted, practical. + +We do not sound: Cute, hand-wavy, salesy, corporate, or condescending. + +\| We are \| We are NOT \| +\|---\|---\| +\| Direct \| Blunt or rude \| +\| Technical \| Inaccessible to a non-expert reader \| +\| Confident \| Boastful \| +\| Dry-witted \| Trying to be funny \| +\| Practical \| Boring \| + +Examples of our voice in the wild + +- Stripe docs, for the rhythm and the way they assume reader competence without showing off. +- Tailscale's blog, for the dry technical wit and willingness to admit tradeoffs. +- 37signals' product copy, for short sentences that earn their place. + +--- + +## 6. Visual direction + +Mood: Calm, confident, technical, slightly opinionated. A senior engineer's notebook, not a stadium. + +Palette direction: Predominantly light with strong dark-mode parity. Single accent color (deep teal). Charts and diagrams in muted, accessible color ramps. No gradients, no glow effects. + +Type direction: Geometric sans for display (Inter or similar), monospace for code and metrics (JetBrains Mono or similar). Generous line height. Comfortable for long-form reading. + +Imagery direction: Real screenshots of the product, annotated. Architecture diagrams drawn in a consistent simple style. No stock photos. No abstract 3D illustrations. No people in headsets pointing at laptops. + +Reference sites we want to feel like + +- linear.app: For the calm density and how every pixel feels intentional. +- planetscale.com: For technical credibility without enterprise stuffiness. +- fly.io: For the dry voice and the unapologetic technical depth on the homepage. + +Reference sites we want to feel different from + +- datadoghq.com: Too dense, too many product lines, screams "we will sell you everything." +- newrelic.com: Too corporate, too gradient-heavy, feels like 2018. + +--- + +## 7. Scope and deliverables + +In scope + +- Homepage with hero, three feature blocks, social proof, pricing teaser, footer CTA +- Pricing page with transparent tiers, calculator, and FAQ +- Product page with annotated screenshots and one short demo video +- About page (founder story, team, hiring CTA) +- Trial signup flow (3 steps: email + workspace name + first project setup) +- Docs index page that links into the existing docs site (separate property) +- Blog index and post template (engineering writing, changelog posts) +- 404 and other error pages + +Out of scope + +- Customer logos page (we do not have permissioned logos yet) +- Comparison pages (Datadog vs Plumb, etc.) - saved for Q4 once we have data +- Localization (English only at launch) +- Marketing automation integrations beyond a single newsletter capture + +--- + +## 8. Constraints + +Timeline + +- Brief approved: April 15, 2026 +- Wireframes: April 30 +- High-fi design: May 20 +- Dev complete: June 30 +- QA and content load: July 1 to July 12 +- Launch: July 15 + +Budget + +- $25K total: $15K design, $10K dev contractor for trial flow integration. Internal team handles content, brand assets, deploy. + +Technical + +- Next.js App Router on Vercel +- Trial flow writes to Supabase (existing project) +- Plausible for analytics (no Google Analytics) +- All pages must score 95+ on Lighthouse performance and accessibility +- Mobile baseline: 375px + +Brand + +- Logo: existing wordmark + glyph (provided) +- Colors: deep teal (#0F4C5C), slate gray scale, white. Single accent only. +- Type: Inter for display, JetBrains Mono for code + +Legal and compliance + +- Accessibility: WCAG 2.1 AA +- Privacy: GDPR compliant. EU users get a banner. Data residency in US-East. +- No customer testimonials with full names without written consent + +--- + +## 9. Inspiration and competitors + +Inspiration + +\| Site / brand \| What we love \| +\|---\|---\| +\| linear.app \| Density without clutter; type system; restraint \| +\| planetscale.com \| How they explain technical concepts in the hero \| +\| fly.io \| Voice, blog rhythm, code samples on the homepage \| +\| stripe.com/docs \| The annotated examples pattern (we want to borrow this for the product page) \| + +Competitors + +\| Site / brand \| How we differ \| +\|---\|---\| +\| datadoghq.com \| We are smaller, opinionated, and priced for teams under 200 \| +\| newrelic.com \| We avoid enterprise sprawl. Single product, clear pricing \| +\| grafana.com \| We are managed and easier to operate. We charge for the time savings \| + +--- + +## 10. Approval + +Sign-off owner: Maria Chen + +Sign-off artifacts: +- Wireframes: review by April 30, async approval in Figma +- High-fi design: review by May 20, in-person review meeting + 48-hour async window +- Pre-launch site (staging URL): review by July 10, all stakeholders sign off in writing + +Sign-off deadline: Each stage above has a 48-hour async window after the review meeting. After 48 hours of no objection, the stage is approved and we proceed. + +If no sign-off by deadline: Default to ship. Maria has final say on any post-launch revision. + +--- + +## Appendix + +- [Audience research notes](./audience-research.md) +- [Competitive teardown](./competitive-analysis.md) +- [Brand guidelines](./brand-guidelines.md) diff --git a/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md b/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md new file mode 100644 index 0000000..a8fb49d --- /dev/null +++ b/dist/pi/.agents/skills/creative-brief/references/voice-and-tone-guide.md @@ -0,0 +1,200 @@ +# Voice and Tone Guide + +Voice is who you are. Tone is how you sound right now. Voice stays constant. Tone shifts with context (a 404 page sounds different from an onboarding email, even if the voice is the same). + +This guide gives you frameworks for picking a voice and adapting tone, plus worked examples. + +--- + +## Framework 1: Four dimensions (Nielsen Norman) + +Pick a position on each axis. Together they describe the voice. + +\| Dimension \| One end \| Other end \| +\|---\|---\|---\| +\| Formality \| Formal \| Casual \| +\| Seriousness \| Serious \| Funny \| +\| Respectfulness \| Respectful \| Irreverent \| +\| Enthusiasm \| Matter-of-fact \| Enthusiastic \| + +A bank: formal, serious, respectful, matter-of-fact. +A craft soda brand: casual, funny, irreverent, enthusiastic. +A premium watch brand: formal, serious, respectful, matter-of-fact. +A coding bootcamp: casual, serious, respectful, enthusiastic. + +If you cannot pick a position on each axis, the voice is not defined yet. + +--- + +## Framework 2: Brand archetypes + +Twelve archetypes from Jung-derived brand theory. Pick one primary and one secondary. + +\| Archetype \| Promise \| Voice notes \| Example brands \| +\|---\|---\|---\|---\| +\| Innocent \| Safety, simplicity \| Warm, plain, reassuring \| Dove, Coca-Cola \| +\| Sage \| Truth, wisdom \| Authoritative, considered, measured \| Google, BBC, The Economist \| +\| Explorer \| Freedom, discovery \| Adventurous, restless, vivid \| Patagonia, Jeep, Subaru \| +\| Outlaw \| Disruption \| Rebellious, blunt, anti-establishment \| Harley-Davidson, Liquid Death \| +\| Magician \| Transformation \| Visionary, mysterious, evocative \| Apple, Tesla \| +\| Hero \| Mastery, courage \| Bold, confident, action-driving \| Nike, FedEx \| +\| Lover \| Intimacy, beauty \| Sensual, warm, indulgent \| Chanel, Godiva \| +\| Jester \| Joy, fun \| Playful, irreverent, witty \| Old Spice, Mailchimp, Slack \| +\| Everyman \| Belonging \| Friendly, plain, relatable \| IKEA, Target \| +\| Caregiver \| Service, compassion \| Nurturing, warm, supportive \| Johnson & Johnson, Volvo \| +\| Ruler \| Control, prestige \| Commanding, polished, exclusive \| Rolex, Mercedes \| +\| Creator \| Self-expression \| Imaginative, articulate, craft-focused \| Lego, Adobe \| + +Two archetypes give you range. A primary "Sage" with secondary "Hero" is authoritative AND action-driving. A primary "Caregiver" with secondary "Sage" is supportive AND wise. + +--- + +## Framework 3: We are X, not Y + +The fastest voice exercise. Pick three to five adjectives. For each, name what it could tip into if overdone. + +> Confident, not arrogant. +> Direct, not blunt. +> Warm, not saccharine. +> Witty, not sarcastic. +> Smart, not condescending. + +The "not" half is what saves you. "Confident" alone leads writers to swagger. "Confident, not arrogant" tells them where the line is. + +--- + +## Tone shifts by context + +Voice stays. Tone shifts. Map the high-frequency moments and decide how each one sounds. + +\| Moment \| Tone shift \| +\|---\|---\| +\| Onboarding \| Warmer, more enthusiastic \| +\| Error message \| Calmer, more matter-of-fact \| +\| Success state \| Brief celebration, quickly redirect to next action \| +\| Empty state \| Helpful, slightly playful, suggests action \| +\| 404 / not found \| Self-aware, light, points the way home \| +\| Account deletion \| Quiet, respectful, no jokes \| +\| Pricing page \| Direct, clear, confidence-inspiring \| +\| Legal copy \| Plain language version of the legal copy, sitting next to the legal copy \| + +--- + +## Practical patterns + +Voice shows up in concrete choices. These are the dials. + +Sentence length + +- Short sentences = punchy, confident. (Apple, Stripe, Liquid Death.) +- Medium sentences = considered, professional. (Most B2B SaaS.) +- Long sentences = literary, premium, slow. (The New Yorker, premium watch brands.) + +Vocabulary + +- Plain (most words 1-2 syllables) = approachable, mass-market. +- Domain-specific = signals expertise to insiders, alienates outsiders. +- Coined or invented = builds a worldview but high risk if not earned (Apple's "Retina", Slack's "huddle"). + +Pronouns + +- "We" = the company speaking. +- "You" = the customer being addressed. +- "I" = a person speaking, not a company. Strong on personal brands and creator products. Weird on enterprise. + +Contractions + +- Use them = casual. +- Avoid them = formal. + +Punctuation + +- Em dashes = literary, breath-taking pauses. +- Semicolons = considered, formal, slightly old-school. +- Periods only = punchy, confident. +- Exclamation points = exuberant; lose credibility past one or two. +- Em dashes are popular but polarizing. Many writers and brands ban them outright; some lean on them. Pick a side. + +Rhythm + +Read your copy out loud. If you stumble, the rhythm is off. Vary sentence length. A page of all-short sentences feels staccato. A page of all-long sentences feels lecture-y. + +--- + +## Worked example: B2B SaaS + +Voice + +> Direct, not blunt. +> Confident, not cocky. +> Practical, not boring. +> Smart, not academic. + +Archetype + +Primary: Sage. Secondary: Hero. + +Patterns + +- Sentence length: short to medium. Lead with the headline, deliver the proof, exit. +- Vocabulary: plain, with domain terms when precision earns its keep. +- Pronouns: "we" for the company, "you" for the reader. Avoid "users." +- Contractions: yes. +- Em dashes: no. + +Tone shifts + +- Onboarding: warmer. Lean into "you can do this." +- Error: matter-of-fact. State what happened, what to do, no apology theater. +- Pricing: direct. List the number, list what's included, stop. + +Sample + +Bad (vague, hedged, overwrought): +> Our innovative platform leverages cutting-edge technology to revolutionize how teams collaborate on data-driven workflows. + +Good (direct, plain, confident): +> Move data between tools without writing code. Connect your stack in minutes. Built for teams that have outgrown spreadsheets. + +--- + +## Worked example: D2C food brand + +Voice + +> Playful, not goofy. +> Honest, not blunt. +> Crave-worthy, not gluttonous. +> Curious, not academic. + +Archetype + +Primary: Jester. Secondary: Everyman. + +Patterns + +- Sentence length: short. Hit the joke, get out. +- Vocabulary: plain. Sensory words land. +- Pronouns: "we" and "you," very conversational. +- Contractions: always. +- Punctuation: light. Periods do the work. + +Sample + +Bad (corporate, distant): +> We are committed to providing high-quality artisanal granola made with the finest organic ingredients sourced from trusted partners. + +Good (playful, sensory, confident): +> Crunchy. Honey-roasted. Made with oats from one farm in Wisconsin. We tried adding more stuff. It got worse. So we stopped. + +--- + +## When voice is locked + +A voice is locked when you can: + +1. State it in one sentence ("We sound like a senior engineer explaining something to a junior, with patience.") +2. Cite three brands or writers it borrows from, and what specifically. +3. Show a piece of copy and a critic could say "that does/does not sound like us" without arguing. + +If you cannot do all three, keep working on the voice. diff --git a/dist/pi/.agents/skills/creative-direction/SKILL.md b/dist/pi/.agents/skills/creative-direction/SKILL.md new file mode 100644 index 0000000..0545b60 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/SKILL.md @@ -0,0 +1,153 @@ +--- +name: creative-direction +description: "Walk the user through four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) and produce a structured aesthetic brief that downstream content, copy, design, and art-direction skills consume as required input. The aesthetic depth layer, distinct from `creative-brief` (operational kickoff: scope, audience, deliverables, constraints). Use when a project needs aesthetic coherence across many small decisions and the user has only a vague feeling, or when multiple downstream aesthetic-producing skills need a shared brief. Triggers on creative direction, aesthetic direction, set the aesthetic, define the visual direction, what's the vibe, what's the tone, the four axes. Does NOT fire for a general kickoff brief (use `creative-brief`), tactical single-piece work, already-documented direction, purely functional output, or locked production-stage work." +category: strategy-and-discovery +catalog_summary: "Four-axis aesthetic brief (tone, aesthetic, audience, sensory ambition) for cross-skill coherence" +display_order: 3 +--- + +# Creative Direction + +Frameworks produce competent output. Coherent output requires a brief. + +This skill turns vague creative intent into a structured brief that downstream skills can reference. It does not generate taste. It captures direction, so the dozens of small decisions a project requires (word choice, image selection, white space, sequencing, what to leave out) all answer to the same question. + +--- + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## When to use + +- The start of a multi-touchpoint project (website, brand, campaign, product launch) where aesthetic coherence matters +- Before running multiple downstream skills that need to share a unified voice and look +- When inheriting a project that has competent execution but feels generic or incoherent +- Recalibrating an existing project that has drifted aesthetically over time +- When the user is a non-curator who knows what feeling they want but cannot articulate the decisions that produce it + +## When NOT to use + +- Use `creative-brief` instead when the user needs a general kickoff brief covering scope, audience, deliverables, and constraints. This skill goes deeper on aesthetic axes specifically, not on the operational layer. +- Use `art-direction` instead when briefing a specific creative deliverable (photo shoot, illustration set, video, campaign). This skill produces project-wide aesthetic direction; `art-direction` extends that direction into specific creative work. +- Tactical single-piece work (one tweet, one error message, one button label) +- Projects where the user has complete aesthetic direction documented already (skip to downstream skills) +- Purely functional output (data tables, form labels, system status text) +- Production-stage execution where direction is already locked +- When the goal is to develop taste; this skill codifies intent, it does not develop judgment + +--- + +## Required inputs + +- Project name and one-paragraph description +- Target audience (rough is fine; full audience profiles come from `brand-discovery`) +- Business goal (what changes if this project works) +- Optional but high-value: 2 to 4 reference URLs (sites, brands, or pieces) the user admires, with a sentence on what specifically resonates +- Optional: existing brand assets if the project is a refresh, not greenfield +- Constraints worth declaring (parent brand voice, regulatory tone requirements, accessibility floors) + +--- + +## The framework: 4 directional axes + +A creative brief sits at the intersection of four axes. Each axis is a spectrum, not a binary. The user picks a position on each, knowing that the choice excludes adjacent positions for this project. + +### 1. Tone Register + +How formal is the work? How much heat does the language carry? + +Positions: + +- Professional. Measured, precise, low-register. Trusts the reader to do work. Restraint is the signal. +- Conversational. Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking. +- Playful. Wit, surprise, willingness to break form for effect. Risks the reader missing the point if not earned. +- Provocative. Pointed, opinionated, willing to take a position other brands will not. Risks alienating people who do not share the position. + +How to choose: What does the audience already get too much of, and what too little? If the category is dry, conversational or playful is differentiation. If the category is loud, professional restraint is differentiation. + +### 2. Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +Positions: + +- Editorial Restrained. Generous white space, single definitive image instead of grids, considered typography, low color count. Signals confidence and patience. +- Polished Standard. Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions. Signals competence and professionalism. +- Controlled Maximalist. High visual density where every element is intentional. Loud but engineered. Signals craft and conviction. +- Expressive Maximalist. Visual abundance, willingness to be loud, willing to clash. Signals energy and ambition. Hardest to execute well. + +How to choose: What is the project saying about the brand's relationship to attention? Restrained earns attention by deserving it. Maximalist captures attention by not letting it leave. + +### 3. Audience Relationship + +How does the brand position itself relative to the reader? + +Positions: + +- Authority. We tell you what is true. Implicit hierarchy, expertise on display, reader is the learner. +- Peer. We are figuring this out together. Equal footing, shared vocabulary, reader is the co-thinker. +- Companion. We walk with you. Lower hierarchy than authority, more presence than peer, reader is the protagonist of their own work. +- Coach. We challenge you. The brand pushes the reader toward something they would not push themselves toward alone, reader is the trainee. + +How to choose: What does the audience need most? Audiences who feel lost want authority or coach. Audiences who feel patronized want peer or companion. The wrong choice patronizes or abandons the reader. + +### 4. Sensory Ambition + +How much is the work asking of the reader emotionally? + +Positions: + +- Functional. Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity. Most utility tools live here. +- Considered. Reader notices the craft. Aesthetic choices are visible without being the point. Most premium brands live here. +- Resonant. Reader feels something specific the brand architected. Aesthetics carry meaning. Hardest to produce. Most editorial and narrative brands aspire here. + +How to choose: What does the audience deserve from this experience? Functional respects time. Resonant respects feeling. The wrong choice either wastes attention or fails to deliver utility. + +--- + +## Workflow + +1. Gather inputs. Project name, description, audience, goal, references. +2. Walk through each axis as a question. One axis at a time. For each, present the positions, surface tradeoffs, and capture the user's selection plus reasoning. +3. Capture inspiration references. For each provided reference URL, ask what specifically resonates. The answer often clarifies which axis position fits better than abstract description does. +4. Surface tensions. Some combinations are difficult to execute well. Functional + Provocative is rare since provocation usually requires emotional engagement that pure functional work resists. Authority + Functional often slides into preachy without warming up at least slightly. Flag tensions and ask the user to confirm or reconsider. +5. Synthesize. Write a one-paragraph synthesis describing what this combination produces in practice. +6. Output the brief. Markdown format using the structure in [`references/brief-template.md`](references/brief-template.md). The brief becomes a project artifact (typically saved as `BRIEF.md` at the project root). +7. Hand off. Reference the brief in any downstream skill that produces aesthetic output. Required reading before `landing-page-copy`, `art-direction`, `content-and-copy`, `brand-style-guide`, or any other skill where coherence matters. + +--- + +## Failure patterns + +- Using this to develop taste. This skill codifies intent. It does not produce judgment. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. +- Skipping inspiration references. The references calibrate what the axis positions mean in practice. A user picking "Editorial Restrained" without examples often means something different than what an art director means by it. +- Treating positions as absolute. A project at "Conversational" still has moments of authority and play. Position is the gravitational center, not a fence. +- Brief drift mid-project. The most common failure. The brief gets written, then ignored. Discipline: every downstream skill checks the brief before producing output. If a skill wants to violate the brief, the violation is a decision the user makes consciously, not an accident. +- Picking incompatible combinations without flagging. Functional + Provocative is technically valid but very hard. The skill should surface that the combination is rare and ask the user to confirm. +- Producing a brief no one references. A brief that does not change downstream output is decoration. The test of a good brief is whether the output would be different if a different brief were used. + +--- + +## Output format + +Default output is a markdown brief, typically saved as `BRIEF.md` at the project root. + +Structure: + +1. Project header. Name, one-paragraph description, target audience, business goal. +2. The four axis selections. Each axis with the position selected and a one-sentence rationale. +3. Synthesis paragraph. What this combination produces in practice. Written in present tense, not aspirational ("This brief produces work that..." not "This brief will help us..."). +4. Inspiration references. The provided URLs with notes on what specifically each one demonstrates. +5. Rejection list. What this brief explicitly says no to. Often the most useful section. Examples: "No testimonial walls. No stock photography. No exclamation marks." +6. Open questions. Anything still unresolved that downstream skills will need to know. + +The brief is reference material for the project's life, not a one-time deliverable. Update it when the project's direction genuinely changes. Resist the urge to update it when execution is hard; usually that means execute harder, not loosen the brief. + +--- + +## Reference files + +- [`references/axes-explained.md`](references/axes-explained.md) - The four axes in depth, with positions, signals, and short brand examples per position to calibrate the user's eye. +- [`references/brief-template.md`](references/brief-template.md) - Blank template for the brief output. +- [`references/example-aesthetic-brief.md`](references/example-aesthetic-brief.md) - A fully completed brief from a representative project, showing how the abstract axes translate into concrete creative direction. diff --git a/dist/pi/.agents/skills/creative-direction/references/axes-explained.md b/dist/pi/.agents/skills/creative-direction/references/axes-explained.md new file mode 100644 index 0000000..b49c833 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/axes-explained.md @@ -0,0 +1,235 @@ +# The Four Axes Explained + +Each axis is a spectrum. Pick a position knowing it excludes adjacent positions for this project. Reference brands are illustrative, not prescriptive. + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## Axis 1: Tone Register + +How formal is the language? How much heat does it carry? + +### Professional + +Measured, precise, low-register. Trusts the reader to do the work of meaning. Restraint is the signal. + +What this signals: Seriousness, expertise, established status. The brand does not need to perform to be taken seriously. + +Reference examples: Stripe's documentation. The Economist. McKinsey's published thinking. Bloomberg's editorial style. + +When to pick this: The audience is making high-stakes decisions and needs to feel they are dealing with peers, not pitchpeople. Or, the category is loud and your differentiation is calm. + +Common failure: Sliding into stiffness. Professional is not robotic. It is restrained and warm, not cold. + +### Conversational + +Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking, not an institution speaking. + +What this signals: Approachability without sacrificing competence. A brand that respects the reader as a person, not a target. + +Reference examples: Linear's product copy. Vercel's marketing voice. Notion's onboarding. MailChimp's voice in their early years. + +When to pick this: Default for most modern B2B and prosumer brands. The audience appreciates human voice but still needs to trust the brand's competence. + +Common failure: Sliding into casual. Conversational is still considered. "Hey friend!" is not conversational, it is performed informality. + +### Playful + +Wit, surprise, willingness to break form for effect. Visible craft in the language itself. + +What this signals: Confidence, creative ambition, willingness to risk being misread. The brand is having fun and inviting the reader to as well. + +Reference examples: Slack's early voice. Old Spice campaigns. Bumble. Mailchimp at its peak. + +When to pick this: The audience expects beige and wants color. The category is mature and differentiation through craft is available. The brand has the cultural permission to be funny without it reading as forced. + +Common failure: Forcing humor that does not earn its place. Playful only works when it is actually funny. Otherwise it reads as desperate. + +### Provocative + +Pointed, opinionated, willing to take a position other brands will not. Says what others soften. + +What this signals: Conviction. The brand stands for something specific and is willing to lose the audience that disagrees in order to bond more deeply with the audience that agrees. + +Reference examples: Patagonia's political voice. Liquid Death's entire premise. Oatly's category-baiting copy. The early Apple "Think Different" era. + +When to pick this: Strong opinion exists and hiding it is more expensive than expressing it. The brand can defend the position over the long term, not just at launch. + +Common failure: Performing provocation without conviction. Audiences detect this in seconds. Either the position is real or the voice fails. + +--- + +## Axis 2: Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +### Editorial Restrained + +Generous white space, single definitive image instead of grids, considered typography, low color count, deliberate slowness. + +What this signals: Confidence and patience. The brand is willing to under-fill space because it trusts the reader to fill it with attention. + +Reference examples: Aesop's website. Apple's product pages in their classic era. Jacquemus. Phaidon's editorial work. Most luxury fashion houses. + +When to pick this: The audience is fatigued by visual noise. The brand is premium or aspirational. The product or work itself benefits from being viewed slowly. + +Common failure: Restraint that reads as absence. Restraint earns its place when every remaining element is exquisite. Strip too much and the page reads as unfinished. + +### Polished Standard + +Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions, conventional component patterns. + +What this signals: Competence, professionalism, current. The brand belongs in its category without standing out. + +Reference examples: Most modern B2B SaaS sites. Stripe's marketing pages. Linear. Notion's marketing. Vercel. + +When to pick this: The audience expects the category's visual conventions and the brand's differentiation is in the product, not the wrapper. Default for most B2B work. + +Common failure: Producing work indistinguishable from competitors. Polished Standard is safe. Safe is forgettable. + +### Controlled Maximalist + +High visual density where every element is intentional. Loud, but engineered. The page is full because each thing earns its place. + +What this signals: Craft and conviction. The brand has thought about every pixel and chose density on purpose. + +Reference examples: BUCK's portfolio site. Ueno's work. Pentagram's case study pages. Many top-tier creative agency sites. Some Nike campaign work. + +When to pick this: The audience expects boring and the brand wants to demonstrate creative ambition. Differentiation through visible craft is available. The team has the design capacity to execute it. + +Common failure: Density without intent. Controlled Maximalist requires every element to defend its existence. Lazy density reads as cluttered, not crafted. + +### Expressive Maximalist + +Visual abundance, willingness to be loud, willing to clash. Energy over restraint. + +What this signals: Energy, ambition, irreverence. The brand is having a moment and the work is the moment. + +Reference examples: Adult Swim. Cards Against Humanity. Some Heinz creative work. Liquid Death's loudest moments. Music festival branding. + +When to pick this: The audience is energetic and seeks brands that match. Cultural permission for loudness is high in the category. The brand can sustain the energy over time. + +Common failure: This is the hardest position to execute well. Expressive Maximalism that lacks craft reads as chaotic, not exciting. Most attempts fail. + +--- + +## Axis 3: Audience Relationship + +How does the brand position itself relative to the reader? + +### Authority + +We tell you what is true. Expertise on display. Hierarchy implicit and accepted. + +What this signals: Earned expertise. The reader came here to learn from someone who knows more than they do. + +Reference examples: Bloomberg. McKinsey's published frameworks. Bain's reports. The Economist. Some of Apple's product copy. + +When to pick this: The audience explicitly came for expertise. The brand has the credibility to back the position. The category rewards authoritative voice. + +Common failure: Authority without earned credibility reads as arrogance. The brand needs to actually know more than the reader. + +### Peer + +We are figuring this out together. Equal footing, shared vocabulary. + +What this signals: Mutual respect. The reader is treated as a co-thinker, not a learner. + +Reference examples: Linear. Most developer-focused brands. GitHub. Some of Notion's voice. Most modern B2B SaaS. + +When to pick this: The audience is sophisticated and reacts badly to being talked down to. The work is genuinely collaborative and acknowledging the reader's expertise serves the relationship. + +Common failure: False peering. If the brand actually does know more, hiding that to seem peer-like reads as condescending. + +### Companion + +We walk with you. Lower hierarchy than authority, more presence than peer. + +What this signals: Sustained accompaniment. The brand is here for the long arc, not just the transaction. + +Reference examples: Headspace. Calm. Stitch Fix. Some healthcare brands. Anthropic's voice in some moments. + +When to pick this: The audience is going through something difficult, ongoing, or uncertain. They need presence more than expertise. The relationship is about being with them, not directing them. + +Common failure: Companion without substance reads as performative warmth. The brand needs to actually do something useful to earn the relationship. + +### Coach + +We challenge you. The brand pushes the reader toward something they would not push themselves toward alone. + +What this signals: Productive friction. The brand assumes the reader wants growth and is willing to be pushed. + +Reference examples: Strava. Whoop. Crossfit's brand voice. Apple Fitness+. Some founder-focused programs. + +When to pick this: The audience explicitly wants to be challenged. The brand has the credibility to push without being dismissed. The product or service requires effort that the brand is asking of the reader. + +Common failure: Coaching without permission. The brand needs to be invited into that role. Pushing readers who did not ask to be pushed reads as preachy. + +--- + +## Axis 4: Sensory Ambition + +How much is the work asking of the reader emotionally? + +### Functional + +Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity, not feeling. + +What this signals: Respect for time. The brand assumes the reader has somewhere else to be. + +Reference examples: Wikipedia. Craigslist. Most documentation sites. Government services that work well. IRS forms when they are well-designed. + +When to pick this: The reader is in transactional mode. The work's value is utility, not feeling. Asking for emotional engagement would be presumptuous. + +Common failure: Confusing functional with bare. Functional work is still well-designed. It is just designed for clarity over resonance. + +### Considered + +Reader notices the craft. Aesthetic choices are visible without being the point. + +What this signals: Attention to detail without flexing it. The brand cares, and the reader can tell. + +Reference examples: Apple's product pages. Notion's marketing. Linear's interface. Aesop's product photography. Most premium SaaS. + +When to pick this: The audience appreciates craft when they encounter it but does not require an emotional payoff. The work needs to feel premium without demanding emotion. + +Common failure: Considered work that drifts toward decorative. If the craft is visible without earning its place, it reads as fussy. + +### Resonant + +Reader feels something specific the brand architected. Aesthetics carry meaning. The work is asking the reader to feel. + +What this signals: Ambition. The brand is trying to do more than communicate. It is trying to move. + +Reference examples: Hermes. Patagonia at their narrative best. Some Apple campaigns ("Think Different," "Shot on iPhone"). Aesop's editorial work. Most editorial publications. + +When to pick this: The audience came for feeling, not utility. The brand has the craft to deliver it. The work is significant enough to warrant the emotional ask. + +Common failure: This is the hardest position. Resonance that is forced reads as manipulation. Resonance that is mistargeted reads as melodrama. Resonance that is vague reads as pretentious. Most attempts fail. + +--- + +## Combinations to flag + +Some combinations are common, some are rare-but-doable, some are contradictory. + +Common combinations: + +- Conversational / Polished Standard / Peer / Considered = the modern B2B SaaS default +- Professional / Editorial Restrained / Authority / Considered = premium consultancy default +- Conversational / Polished Standard / Companion / Considered = wellness or healthcare default + +Rare but powerful: + +- Provocative / Editorial Restrained / Coach / Resonant = the "Patagonia at full conviction" register +- Conversational / Controlled Maximalist / Peer / Resonant = the "top creative agency" register +- Provocative / Controlled Maximalist / Coach / Resonant = the "high-stakes brand revival" register + +Difficult combinations to flag: + +- Functional + Provocative = rare. Provocation usually requires emotional engagement that pure functional work resists. +- Editorial Restrained + Expressive Maximalist = unreachable by selection. These are both positions on Axis 2 (Aesthetic Philosophy), so the user picks one or the other, not both. +- Authority + Functional = possible but flat. Often slides into "we are right and you should know that," which is hard to hold without warming up at least slightly. + +When the user picks a difficult combination, surface the difficulty. Ask them to confirm or reconsider. Sometimes the difficulty is the point. diff --git a/dist/pi/.agents/skills/creative-direction/references/brief-template.md b/dist/pi/.agents/skills/creative-direction/references/brief-template.md new file mode 100644 index 0000000..ffdd108 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/brief-template.md @@ -0,0 +1,74 @@ +# Brief Template + +Save this as `BRIEF.md` at the project root. Update when direction genuinely changes; otherwise hold the line. + +--- + +# [Project Name] Brief + +## Project + +Name: [Project name] + +Description: [One paragraph describing what the project is, what it produces, who it serves.] + +Target audience: [Rough description. A full audience profile from `brand-discovery` is a separate document.] + +Business goal: [What changes if this project works. The actual outcome that defines success.] + +--- + +## The four axes + +### Tone Register: [Position] + +[One sentence rationale for why this position fits this audience and goal.] + +### Aesthetic Philosophy: [Position] + +[One sentence rationale.] + +### Audience Relationship: [Position] + +[One sentence rationale.] + +### Sensory Ambition: [Position] + +[One sentence rationale.] + +--- + +## Synthesis + +[One to two paragraphs describing what this combination produces in practice. Written in present tense. "This brief produces work that..." not "This brief will help us...". Concrete enough that downstream skills can check their output against it.] + +--- + +## Inspiration references + +[For each reference URL or brand the user provided, document what specifically resonates and which axis it informs.] + +- [Reference 1] - [What this demonstrates and which axis it calibrates.] +- [Reference 2] - [What this demonstrates and which axis it calibrates.] +- [Reference 3] - [What this demonstrates and which axis it calibrates.] + +--- + +## Rejection list + +This brief explicitly says no to: + +- [Specific decision the brief rejects, e.g. "No testimonial walls."] +- [Another specific decision, e.g. "No stock photography of people."] +- [Another, e.g. "No exclamation marks in body copy."] + +The rejection list is often the most useful section. The choices a brief excludes are as important as the choices it commits to. + +--- + +## Open questions + +[Anything still unresolved that downstream skills will need to know. Better to surface uncertainty than to leave it implicit.] + +- [Question 1] +- [Question 2] diff --git a/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md b/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md new file mode 100644 index 0000000..6e52131 --- /dev/null +++ b/dist/pi/.agents/skills/creative-direction/references/example-aesthetic-brief.md @@ -0,0 +1,83 @@ +# Example Aesthetic Brief + +A representative completed brief, modeled on a realistic project. Showing how the abstract axes translate into concrete creative direction. + +> The brief below is a worked example for "Conversational + Editorial Restrained + Peer + Considered" applied to a developer-tool marketing site. Compare it against any rendered marketing site that hits these axis positions to see how the abstract axes translate into concrete decisions: copy register, typographic restraint, image treatment, page density, and rejection list. + +--- + +# Observatory Marketing Site Brief + +## Project + +Name: Observatory marketing site redesign + +Description: Rebuild the marketing site for an open-source observability tool aimed at senior infrastructure engineers. The current site reads like every other developer SaaS site (gradient hero, "trusted by" logo wall, three-column feature grid, code snippet, testimonials, signup CTA). The new site needs to feel like the team behind it actually understands the problem space, not like a marketing team built a site about a tool they have not used. + +Target audience: Senior platform engineers, infrastructure leads, and SRE managers at companies with 50 to 500 engineers. They evaluate observability tools for their team. They are skeptical of marketing claims and value technical depth. They will read documentation before they evaluate the product. + +Business goal: Increase qualified evaluation requests from engineering decision-makers, where "qualified" means the requester has authority to influence vendor selection and is in active evaluation. Volume of low-intent signups is not the goal. Quality and intent are. + +--- + +## The four axes + +### Tone Register: Conversational + +The audience is fatigued by both stiff vendor copy ("enterprise-grade reliability") and aggressive performance copy ("10x your observability"). Conversational treats the reader as a peer engineer who can read between the lines. + +### Aesthetic Philosophy: Editorial Restrained + +The category is visually loud. Dashboards, gradient heroes, neon accents, animated charts. The differentiation is opposite: low color count, generous white space, considered typography, single definitive image instead of dashboard screenshots above the fold. The site reads like documentation that decided to be a marketing site, not the other way around. + +### Audience Relationship: Peer + +These engineers do not need to be educated on observability. They need to be respected as practitioners. Authority voice would be condescending. Companion voice would be saccharine. Peer voice acknowledges that we and they are figuring out the same hard problems. + +### Sensory Ambition: Considered + +Functional would underdeliver; the audience expects a marketing site to be more than a feature list. Resonant is too much; this is not a brand campaign, it is a tool evaluation. Considered means the craft is visible (typography, restraint, the right photograph in the right place) without the site asking for an emotional response. + +--- + +## Synthesis + +This brief produces a marketing site that reads like a thoughtful engineering blog post the team happened to design well. Body copy is in first-person plural, contractions are fine, and technical terms appear without quotation marks (the audience uses them naturally, the site should too). Visual density is intentionally low, with a single hero image instead of a product screenshot grid, and pages that breathe rather than fill. There is no logo wall above the fold. There are no testimonials styled as ad copy. The product makes its case through clear documentation links, an honest comparison page, and a "how this differs from what you are already using" section that is willing to say what the tool is not for. + +The site refuses several conventions of the category. No animated dashboard hero. No "trusted by" logos as the second module. No three-column feature grid with checkmarks. No popup. No newsletter modal. The site assumes the reader will find the product if it is genuinely useful, and that the marketing's job is to be clear, not to be loud. + +--- + +## Inspiration references + +- Linear's marketing site (linear.app) - Demonstrates Conversational + Polished Standard + Peer well. The Observatory site borrows the calm density and the willingness to write in first person, but pushes further toward Editorial Restrained on the aesthetic axis. +- Vercel's marketing pages - Useful for how they handle technical depth without overwhelming. The product surfaces in code, not in dashboard mockups. +- Stripe's documentation - The reference for how documentation can be a marketing asset. Observatory's marketing site borrows the sense that good docs are a brand decision, not just a product decision. +- The Economist's editorial design - Aesthetic reference for restraint, considered typography, and the use of a single editorial photograph as a hero treatment instead of a dashboard screenshot. + +--- + +## Rejection list + +This brief explicitly says no to: + +- No "trusted by" logo wall, especially above the fold +- No gradient hero. Solid color or a single restrained photograph instead +- No three-column feature grid with checkmark icons +- No product dashboard mockup as the hero image +- No animated chart components scattered through the page +- No exit-intent modal, newsletter popup, or any popup of any kind +- No testimonials with headshots arranged in a grid +- No marketing-speak: "enterprise-grade," "blazing fast," "world-class," "industry-leading" +- No "AI-powered" framing. The product uses ML; that is not the lead +- No corporate stock photography of people in offices +- No vague "join the future" CTAs. Specific verbs only + +--- + +## Open questions + +- The comparison page is committed to but the comparators are not yet selected. Decision needed before `landing-page-copy` runs on that page. +- The hero image needs custom photography or commissioned illustration. Considered Restrained does not support stock. Budget question for the team. +- The pricing page is not yet scoped. Brief should be confirmed before that page is built; pricing pages have their own conventions. +- Author bylines are part of the documentation but not the marketing site yet. Worth deciding whether marketing pieces carry author attribution. diff --git a/dist/pi/.agents/skills/cro-optimization/SKILL.md b/dist/pi/.agents/skills/cro-optimization/SKILL.md new file mode 100644 index 0000000..d1ea82f --- /dev/null +++ b/dist/pi/.agents/skills/cro-optimization/SKILL.md @@ -0,0 +1,271 @@ +--- +name: cro-optimization +description: "Run conversion rate optimization through hypothesis-driven testing including audit, hypothesis generation, test design, statistical analysis, and rollout decisions. Use this skill whenever the user wants to optimize conversion, run A/B tests, audit a funnel, generate test hypotheses, design experiments, or analyze test results. Triggers on conversion optimization, CRO, A/B test, split test, multivariate test, hypothesis, conversion funnel, funnel audit, experiment design, statistical significance, lift, optimization. Also triggers when the user has a conversion problem and isn't sure where to start, or when test results are ambiguous and need interpretation." +category: growth +catalog_summary: "Hypothesis-driven testing, conversion optimization" +display_order: 2 +--- + +# CRO Optimization + +Run conversion rate optimization as a structured discipline: audit → hypothesize → test → decide. Stack-agnostic. Tool-agnostic. + +This skill is for running tests against existing pages and flows. For writing landing page copy from scratch, use `landing-page-copy`. For setting up the analytics that make CRO possible, use `analytics-strategy`. + +--- + +## When to use + +- Converting traffic at lower rate than expected +- Specific funnel step has high drop-off +- Pages with high traffic that could move the needle if optimized +- A/B testing infrastructure exists (or can be set up) +- Statistical significance and sample size questions + +## When NOT to use + +- Without sufficient traffic to test (under ~5,000 monthly conversions per variant) +- Pre-launch (no users to test on yet) +- Strategy or messaging-level questions that need qualitative research first +- Brand-defining choices (CRO can't optimize a fundamentally wrong brand) + +--- + +## Required inputs + +- The page or flow under optimization +- Current conversion rate and traffic volume +- Access to analytics (event tracking, funnel data) +- An A/B testing tool (or willingness to set one up) +- Time and budget for testing (typically 2 to 8 weeks per test) + +--- + +## The framework: 4 phases + +### 1. Audit + +Diagnose before treating. + +Quantitative audit: + +- Funnel data. Where are users dropping off? The biggest drop is the biggest opportunity. +- Segmentation. Does the funnel perform differently by source, device, geography, audience type? +- Performance data. Are slow pages dragging conversions? +- Search Console / on-site search. What are users looking for that they can't find? + +Qualitative audit: + +- Session replay. Watch 20+ sessions of users on the target flow. Note friction, confusion, hesitation. +- Heatmaps. Where do users click? Where do they scroll? Where do they not? +- User interviews / surveys. Why did users not convert? Survey people who started but abandoned. +- Form analytics. Which fields cause abandonment? Which cause errors? +- Customer support tickets. What conversion-related questions come in? + +Heuristic audit: + +- Apply CRO heuristics to the flow: + - Is the value proposition clear in 5 seconds? + - Is there a single primary CTA per page? + - Is the form length appropriate to the offer? + - Is the trust/social proof present? + - Are objections handled? + - Is the page accessible? (Accessibility issues hurt conversion silently.) + +The audit produces a list of suspected friction points. Each becomes a hypothesis candidate. + +### 2. Hypothesis + +A testable statement. + +Hypothesis structure: + +> Because [observation from audit], we believe that [change] will produce [predicted outcome] for [user segment], because [reason]. + +Example: + +> Because session replays show users abandoning at the shipping step (audit), we believe that adding visible shipping cost to the product page (change) will increase add-to-cart conversion by 5 percent (outcome) for desktop users (segment), because users are surprised by shipping cost and abandon (reason). + +Hypothesis quality criteria: + +- Specific change (not "improve the design") +- Measurable outcome (with a target) +- Grounded in evidence (audit, research, prior tests) +- Tied to a known mechanism (why would this work?) + +Hypothesis prioritization (ICE or PIE): + +- Impact: How much could this move the metric? +- Confidence: How likely is the hypothesis to be right? +- Ease: How easy to test? (Time, complexity, risk) + +Score each 1 to 10. Highest combined scores test first. + +### 3. Test design + +A test that produces an unambiguous answer. + +Sample size and duration: + +Use a sample size calculator (most A/B tools have one) before launching. Inputs: + +- Baseline conversion rate +- Minimum detectable effect (the smallest lift you'd care about) +- Statistical power (typically 80%) +- Significance level (typically 95%) + +This produces required sample size per variant. Run the test until that sample is reached, OR for a minimum duration that captures full business cycle (typically 2 weeks minimum, to cover weekends and weekly patterns). + +Common test setup mistakes: + +- Stopping the test the moment significance is hit (peeking) +- Running tests for too short to capture a full business cycle +- Running multiple overlapping tests on the same flow +- Testing during atypical periods (Black Friday, holidays, major campaigns) +- Excluding mobile when 50%+ of traffic is mobile (or vice versa) +- Testing on too small a slice of traffic (low statistical power) +- Not segmenting analysis (overall lift can hide negative impact on a segment) + +Test parameters to define before launch: + +- Primary metric (one) +- Guardrail metrics (do not go down) +- Sample size +- Duration (minimum and maximum) +- Decision criteria (when to ship, when to kill, when to extend) +- Segments to analyze in addition to overall + +### 4. Decide + +After the test concludes. + +Decision framework: + +\| Outcome \| Decision \| +\|---\|---\| +\| Variant clearly wins (>95% significance, exceeds minimum effect) \| Ship variant. Document. Continue testing. \| +\| Variant clearly loses \| Kill. Capture the lesson. Iterate hypothesis. \| +\| Inconclusive (neither significant) \| Larger test, different angle, or move on. Don't ship "tied" variants. \| +\| Small lift, lots of variance \| Probably not worth shipping. Even if "winner," may not replicate. \| +\| Wins overall, loses for important segment \| Investigate segment. Consider segment-specific solution. \| + +Anti-patterns: + +- "It looks like it's winning, ship it" before reaching significance +- Shipping a variant because the team wants to (HiPPO - highest paid person's opinion) +- Killing tests too early because they look bad +- Re-running tests until they "win" (false positive risk) +- Not capturing the learning when a test loses + +--- + +## Statistical foundations + +### Significance and confidence + +A 95% significance level means: if there were truly no difference between variants, there's only a 5% chance you'd see results this extreme by chance. + +That's not the same as "95% chance the variant wins." + +Most CRO tools report Bayesian probabilities ("95% chance of being best"). Read the methodology your tool uses. + +### Sample size + +Conversion testing needs more sample than people intuit. Quick reference: + +\| Baseline rate \| Minimum detectable effect \| Sample per variant \| +\|---\|---\|---\| +\| 2% \| 10% relative lift \| ~75,000 \| +\| 2% \| 20% relative lift \| ~19,000 \| +\| 5% \| 10% relative lift \| ~30,000 \| +\| 5% \| 20% relative lift \| ~7,500 \| +\| 10% \| 10% relative lift \| ~14,000 \| +\| 10% \| 20% relative lift \| ~3,500 \| + +(Approximate. Use a calculator.) + +If your monthly conversions per variant don't reach these numbers, A/B testing won't produce reliable results. Iterate via design and qualitative research instead. + +### Multiple testing + +The more variants and metrics tested simultaneously, the more false positives. Adjust significance thresholds for multiple comparisons (Bonferroni or similar). + +--- + +## Workflow + +1. Audit. Quantitative + qualitative + heuristic. +2. Generate hypotheses. From audit findings. Apply hypothesis structure. +3. Prioritize. ICE or PIE. Top 3 to 5 to test next. +4. Design the test. Sample size, duration, primary and guardrail metrics, decision criteria. +5. Implement. Build variants. QA carefully (broken variants invalidate tests). +6. Run. Don't peek. Don't stop early. +7. Analyze. Overall and by segment. Note interesting patterns regardless of significance. +8. Decide. Ship, kill, or extend. +9. Document. Hypothesis, design, results, decision, lesson. +10. Compound. Apply lessons to next round of hypotheses. + +--- + +## Failure patterns + +- Testing without audit. Random changes, random results. +- Vague hypotheses. "Make it better" is not a hypothesis. +- Peeking and early stopping. Bias toward false positives. +- Underpowered tests. Not enough sample for a real conclusion. +- HiPPO override. Highest paid person's opinion overrides the data. +- Testing during atypical periods. Holidays distort results. +- Single metric obsession. Conversion ups but average order value craters. Net loss. +- No guardrail metrics. Testing for one outcome, missing damage to others. +- Documentation gap. Wins captured, losses forgotten. Same hypothesis re-tested 3 times. +- Treating each test in isolation. Compounding learning across tests is where CRO programs really win. + +--- + +## Output format + +Default output: a markdown test plan at `cro-test-[hypothesis-slug].md` per test. After the test runs, append the results section. + +Structure: + +```markdown +# Test: [Hypothesis short name] + +## Hypothesis +Because [observation], we believe that [change] will produce [outcome] for [segment], because [reason]. + +## Audit evidence +[What evidence supports this hypothesis] + +## Test design +- Primary metric: +- Guardrail metrics: +- Sample size required: +- Duration: minimum X, maximum Y +- Variant traffic split: +- Segments to analyze: + +## Decision criteria +- Ship if: [conditions] +- Kill if: [conditions] +- Extend if: [conditions] + +## Results (filled after test) +- Sample reached: +- Duration actual: +- Primary metric: [variant vs control + significance] +- Guardrail metrics: [results] +- Segment analysis: [findings] + +## Decision +[Ship / Kill / Extend / Iterate] - [Why] + +## Lesson +[What this teaches us, regardless of outcome] +``` + +--- + +## Reference files + +- [`references/hypothesis-library.md`](references/hypothesis-library.md) - Common high-impact hypothesis patterns by funnel stage. diff --git a/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md b/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md new file mode 100644 index 0000000..89fbae6 --- /dev/null +++ b/dist/pi/.agents/skills/cro-optimization/references/hypothesis-library.md @@ -0,0 +1,313 @@ +# Hypothesis Library + +Common high-impact CRO hypothesis patterns by funnel stage. Use as starting points; adapt to the specific product and audience. Each pattern includes the typical evidence that supports it and the typical mechanism behind why it works. + +--- + +## Top of funnel: hero and value proposition + +### H1: Outcome-led headline beats feature-led + +Hypothesis: Replacing a feature-led headline ("Advanced workflow automation") with an outcome-led headline ("Ship 30% faster") will increase scroll-past-hero rate and CTA clicks. + +Evidence to look for: +- Session replays show users bouncing within 3 seconds +- Heatmaps show low engagement below the hero +- The current headline names a feature, not a benefit + +Mechanism: Users grant 3 to 5 seconds to decide whether to continue. Outcome language is processed faster than feature language. + +Test design: Hero-only swap. Control vs variant. Primary metric: scroll past hero + CTA click. + +--- + +### H2: Specific number beats vague claim + +Hypothesis: Replacing "Save time on month-end close" with "Close in 3 days, not 2 weeks" will increase signup rate. + +Mechanism: Specific numbers are more credible and more memorable than vague claims. + +--- + +### H3: Customer-facing ID over jargon + +Hypothesis: Replacing internal/industry jargon ("ETL pipeline orchestration") with customer language ("Move data between your tools without engineering") will improve hero engagement. + +Mechanism: Industry insiders use jargon. Most prospects are not industry insiders. + +--- + +### H4: Real customer photo beats stock + +Hypothesis: Replacing stock-photo hero imagery with photos of actual customers using the product will increase signup rate. + +Mechanism: Stock photos are pattern-recognized as marketing fluff. Real customer photos signal authenticity. + +--- + +## Mid-funnel: feature blocks and social proof + +### H5: Specific named customer logos beat unnamed + +Hypothesis: Replacing "Trusted by 1,000+ companies" with named logos will improve trust and conversion. + +Evidence: Heatmaps show users hovering near social proof but not converting. + +Mechanism: Named logos provide verifiable trust. Numbers without names are easily fabricated and users know it. + +--- + +### H6: Specific outcome quote beats generic praise + +Hypothesis: Replacing "We love this product!" with "Reduced our onboarding time by 40 percent in three months" will increase trust score and conversion. + +Mechanism: Specific outcomes are credible because they're quantifiable. Generic praise is dismissed as cherry-picked. + +--- + +### H7: Founder quote at scale stage + +Hypothesis: Adding a founder quote and photo on the homepage will increase early-stage trust signals. + +Evidence: Brand is unknown. No major customer logos to display yet. + +Mechanism: Personal accountability from a named person beats anonymous brand voice when trust signals are scarce. + +--- + +### H8: Comparison table for competitive categories + +Hypothesis: Adding a comparison table against named competitors will increase conversion for prospects in active evaluation. + +Mechanism: Users in evaluation mode are comparing anyway. Honest comparison reduces objection-handling work. + +Risks: Can backfire if comparison feels biased or if competitors are smaller than you (gives them oxygen). + +--- + +## Form and signup + +### H9: Fewer form fields wins + +Hypothesis: Reducing signup fields from 7 to 3 will increase signup conversion. + +Evidence: Form analytics show high abandonment, especially on optional fields. + +Mechanism: Each form field is friction. Optional fields without value to the user feel like data collection for company benefit. + +--- + +### H10: Progressive profiling beats upfront fields + +Hypothesis: Moving non-essential signup fields to a post-signup onboarding flow will increase initial signup conversion without hurting profile completion. + +Mechanism: Users commit incrementally. The hardest "yes" is the first one. + +--- + +### H11: Social signup options reduce friction + +Hypothesis: Adding "Sign up with Google" alongside email signup will increase signup rate. + +Risks: OAuth providers can also reduce signups for users uncomfortable with social login. Test, don't assume. + +--- + +### H12: Visible password requirements reduce errors + +Hypothesis: Showing password requirements (8 chars, etc.) above the field instead of as error messages will reduce form errors and abandonment. + +Mechanism: Errors after submission feel like punishment. Pre-emptive guidance feels like assistance. + +--- + +### H13: Trust signals near form + +Hypothesis: Adding "Free for 14 days. No credit card." adjacent to the CTA will increase form completion. + +Mechanism: Reduces perceived risk at the point of commitment. + +--- + +## Pricing page + +### H14: Annotated tiers beat unannotated + +Hypothesis: Adding "Best for" labels on each pricing tier ("Best for solo founders," "Best for teams of 10+") will increase plan selection clarity. + +Mechanism: Users self-select faster when given decision shortcuts. + +--- + +### H15: Annual emphasis beats monthly default + +Hypothesis: Defaulting the pricing toggle to annual (with savings highlighted) will increase annual plan adoption. + +Mechanism: Defaults stick. Loss-framed savings ("Save $X") are more compelling than gain-framed. + +--- + +### H16: Clear "what's included" reduces confusion + +Hypothesis: Adding a checkmark feature comparison below the pricing tiers will reduce sales-assist requests and improve self-service conversion. + +Mechanism: Many prospects abandon when they can't quickly verify a needed feature is in their tier. + +--- + +### H17: Social proof on pricing page + +Hypothesis: Adding tier-specific customer testimonials ("Why we picked Team plan") will increase plan upgrade rate. + +Mechanism: Tier-specific proof reduces fear of overpaying or under-buying. + +--- + +## Checkout / cart + +### H18: Free shipping threshold visible + +Hypothesis: Adding a "$X away from free shipping" message in the cart will increase average order value. + +Evidence: Cart abandonment correlated with sub-threshold orders. + +Mechanism: Goal gradient. Users near a goal accelerate toward it. + +--- + +### H19: Guest checkout option + +Hypothesis: Adding a guest checkout option will increase conversion of first-time buyers. + +Mechanism: Account creation is friction at the worst possible moment (when the user has just decided to buy). + +--- + +### H20: Multiple payment methods + +Hypothesis: Adding [PayPal / Apple Pay / Google Pay / etc.] at checkout will increase mobile conversion. + +Mechanism: Saved payment methods reduce friction. Mobile typing is painful. + +--- + +### H21: Visible total throughout checkout + +Hypothesis: Showing the running total persistently in the checkout flow will reduce abandonment. + +Evidence: Step-by-step abandonment shows users dropping after seeing fees. + +Mechanism: Surprise cost is the #1 cause of cart abandonment. + +--- + +### H22: Trust badges at checkout + +Hypothesis: Adding security badges (SSL, PCI, money-back guarantee) at the payment step will increase completion. + +Mechanism: Security concerns peak at payment entry. + +--- + +## Onboarding (post-signup) + +### H23: Single first action vs feature tour + +Hypothesis: Replacing a feature tour with a single guided first action will increase activation. + +Mechanism: Feature tours teach. First actions deliver value. Users who experience value retain better than users who learn features. + +--- + +### H24: Sample data on first login + +Hypothesis: Pre-loading the new user's account with sample data will increase first-week retention. + +Mechanism: Empty states are demotivating. Pre-populated data shows "what good looks like." + +--- + +### H25: Time-to-value reduction + +Hypothesis: Reducing the steps from signup to first valuable action from 12 to 4 will increase activation rate. + +Evidence: Funnel analysis shows huge drops in the middle of the onboarding flow. + +Mechanism: Each step is a chance to bounce. Fewer steps = more activations. + +--- + +## Email and notifications + +### H26: Subject line specificity + +Hypothesis: Replacing "Update from [Brand]" with a specific benefit-led subject ("Your invoice is ready" or "Save 20% this week") will increase open rate. + +Mechanism: Inbox is competitive. Specificity earns the open. + +--- + +### H27: Single CTA per email + +Hypothesis: Reducing email CTAs from 3 to 1 will increase click-through to primary action. + +Mechanism: Choice paralysis. Multiple CTAs dilute the primary action. + +--- + +### H28: Personalization beyond name + +Hypothesis: Personalizing email body content based on user behavior (last action, product viewed) will increase reactivation rate. + +Mechanism: Generic emails feel like spam. Behaviorally relevant emails feel like service. + +--- + +## Mobile-specific + +### H29: Tap target sizing + +Hypothesis: Increasing tap targets to meet 44x44 minimum will reduce mobile bounce rate. + +Evidence: Mobile heatmaps show mis-taps and rage clicks. + +Mechanism: Small targets fail more often than large ones. + +--- + +### H30: Sticky CTA on mobile + +Hypothesis: Adding a sticky bottom CTA on mobile pages will increase conversion. + +Mechanism: Long mobile pages bury CTAs. Sticky keeps the action available. + +Risks: Can cover content. Test for accessibility issues. + +--- + +### H31: Mobile-specific headlines + +Hypothesis: Shortening headlines for mobile viewports (vs desktop) will reduce bounce rate. + +Mechanism: Long headlines on mobile become walls of text. Short headlines preserve hierarchy. + +--- + +## Compounding tests + +The biggest CRO wins come from compounding learnings. After running 5 to 10 tests, you should know: + +- What kind of headlines win in your category +- How long your forms should be +- Which trust signals move your audience +- Which features matter to your buyer +- What price framing converts + +These insights compound across tests. Document each test's lesson, even when the test loses. + +A pattern to watch: +- Test #1: Outcome-led headline wins +- Test #5: Outcome-led email subject wins +- Test #10: Outcome-led ad copy wins + +You haven't just run 10 tests. You've discovered that "outcome-led messaging" is your audience's preference, broadly. That insight is worth more than any single test. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md b/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md new file mode 100644 index 0000000..f4a424f --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/SKILL.md @@ -0,0 +1,389 @@ +--- +name: data-warehouse-experimentation +description: "Running experiments out of the data warehouse instead of via dedicated experiment platforms. SQL-based assignment, exposure logging discipline, metric definitions in dbt models, statistical analysis in SQL or Python, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms like Statsig and Optimizely. Triggers on warehouse-native experimentation, run experiments in BigQuery, run experiments in Snowflake, dbt experiments, SQL t-test, CUPED variance reduction, exposure log, sample ratio mismatch, sequential testing, mSPRT, doubly robust estimation, build vs buy experimentation. Also triggers when the team is choosing between platform and warehouse, building warehouse-native experiment infrastructure, auditing one, or running an experiment with a custom metric the platform cannot handle." +category: product +catalog_summary: "Run experiments out of the warehouse: SQL assignment, exposure logs, dbt metric definitions, statistical analysis, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms" +display_order: 9 +--- + +# Data Warehouse Experimentation + +A senior data scientist's playbook for running experiments natively out of BigQuery, Snowflake, or any modern data warehouse, with metric definitions in dbt and statistical analysis in SQL or Python. + +Most companies that run experiments at scale use a dedicated platform. Statsig, Optimizely, LaunchDarkly with experimentation, PostHog, Amplitude Experiment. The platforms are good. They handle assignment, instrumentation, and analysis in one product, and the SQL-savvy data team does not have to reinvent the variance reduction wheel. + +There is a different operational model that mature data teams increasingly choose: warehouse-native experimentation. Assignment happens in code or via feature flags. Exposure events fire to the warehouse like any other event. Metrics are defined as dbt models. Statistical analysis runs as SQL or in a Python notebook against warehouse data. The "experiment platform" is just your existing data stack. + +This skill covers when warehouse-native is the right call, the architecture, and the specific techniques that make it work: assignment patterns, exposure logging discipline, metric definitions in dbt, t-tests and CUPED in SQL, sequential testing, and the pitfalls that take down homegrown setups. + +When to use this skill: deciding between platform vs warehouse-native, building a warehouse-native experiment infrastructure, auditing an existing one, or running a specific experiment when the platform of record cannot handle a custom metric or segmentation. + +--- + +## What this skill is for + +This skill spans the operational execution model for warehouse-native experimentation. It does not replace the methodology and interpretation skills; it composes with them. + +- `experiment-design` covers methodology: hypotheses, sample size, randomization unit, primary metric. Tool-agnostic. Read it first to design the experiment correctly regardless of where it runs. +- `experimentation-analytics` covers interpretation: confidence intervals, p-values, effect size, decision frameworks. Tool-agnostic. Read it when results land. +- `experimentation-platform-orchestrator` covers the platform-vs-warehouse decision in detail. Read it to decide whether to use a platform or this skill. +- `feature-flagging` covers assignment infrastructure when not running through a platform. Read it for the flag-management discipline that this skill assumes. +- This skill (`data-warehouse-experimentation`) covers the operational execution: SQL-based assignment, exposure logging, metric definitions in dbt, statistical analysis in SQL or Python, variance reduction, sequential testing. + +The distinction is between "what to do" (the methodology and interpretation skills) and "how to do it without a vendor platform" (this skill). Read this skill after you have decided warehouse-native is the right call. If you are still deciding, start with `experimentation-platform-orchestrator`. + +--- + +## When warehouse-native is the right call + +Six factors push the decision toward warehouse-native. + +1. Cost at volume. Platforms charge per MAU or per event. At 10K MAU the platform is cheap; at 1M MAU the bill becomes a real budget item. Warehouse-native runs on infrastructure you already pay for. +2. Custom metrics. If your primary metric is a complex business metric (revenue with refund-aware logic, cohort LTV, retention bracket, multi-event composites), platforms can struggle. Warehouse-native expresses any metric you can write in SQL. +3. Custom segmentation. Enterprise customers, account-tier crosscuts, complex behavioral segments. Platforms have segmentation features; the depth varies. dbt models compose without limit. +4. Trust requirements. Regulated industries (healthcare, finance, government) need full transparency into the math. Warehouse-native gives you every step of the calculation auditable in SQL. +5. Existing data team strength. If you have data engineers and data scientists, you have most of the infrastructure. Adding experimentation discipline on top costs less than adopting a new platform. +6. Iteration on metric definitions. Platforms ship metric updates on their own cadence. Warehouse-native iterates as fast as your dbt deployments. + +Five factors push toward platform. + +1. Frontend visual experiments. Optimizely's bread and butter. Variant code injected via a script tag, with WYSIWYG editing. +2. Sub-week iteration speed. Some platforms set up an experiment in 30 minutes; warehouse-native often takes a day or more for the first run of a new metric pattern. +3. Teams without strong data infrastructure. If you do not have a warehouse, dbt, and analysts, do not start with warehouse-native. The platform is the right call. +4. Mobile experimentation. SDK-based assignment with offline support is the platform's job, not the warehouse's. +5. Out-of-the-box sequential testing with strict guarantees. Statsig and Eppo ship mSPRT with calibrated alpha-spending. Building this in-house is real work. + +Detail and a decision tree in [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md). Many mature teams use both; warehouse-native for the hard cases, platform for fast iteration on standard experiments. + +--- + +## The architecture + +Four components, in order of data flow. + +1. Assignment. How users get bucketed into variants. Hash function, feature flag, or randomized assignment table. +2. Exposure logging. A discrete event fired the first time a user is exposed to the experiment, written to the warehouse like any other event. +3. Metric definitions. SQL queries (or dbt models) that compute the primary and secondary metrics from warehouse events. +4. Analysis. Statistical computation in SQL or Python that joins exposure to metrics and produces effect estimates with confidence intervals. + +The flow. User visits the product. Assignment determines the bucket (control or treatment). If the user is exposed to the variant (sees the treatment-specific behavior), an exposure event fires to the warehouse. The user takes actions, generating metric events to the same warehouse. At analysis time, exposure joins to metrics on the assignment unit (typically `user_id`); the analysis computes lift and produces a decision. + +The exposure-event pattern is critical. Without it you can compute only an "intent-to-treat" analysis (everyone assigned, regardless of whether they saw the variant). With it you compute the "exposed" analysis on the population that actually experienced the variant. The latter is usually what you want, especially when the variant only affects a subset of the assigned users (e.g., users who reached a specific page). + +--- + +## Assignment patterns + +Three approaches. + +Deterministic hash assignment. The default for warehouse-native. + +```sql +MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 +``` + +The salt (`'exp_button_color_v1'`) ensures different experiments produce uncorrelated assignments for the same user. Reproducible (same input always produces the same bucket), no service dependency, salt isolation across experiments. The assignment can be computed inline in any SQL query. + +Feature flag assignment. Rely on a feature flag service (LaunchDarkly, Statsig flags, Unleash, internal) to do bucketing; the warehouse just records the assignment that the flag service chose. + +```sql +-- Read assignment from the flag service's logs +SELECT user_id, variant_id, assigned_at +FROM flag_service.assignments +WHERE flag_key = 'exp_button_color_v1' +``` + +This works when the flag service is the source of truth for assignment and the warehouse mirrors the assignment table. Useful when assignment must respect flag-service rules (e.g., percentage rollouts, targeting rules) that are inconvenient to replicate in SQL. + +Randomized assignment table. Pre-randomize users into a table at experiment start. + +```sql +CREATE TABLE exp_button_color_v1_assignments AS +SELECT + user_id, + CASE WHEN RAND() < 0.5 THEN 'control' ELSE 'treatment' END AS variant_id +FROM dim_users +WHERE eligible = true; +``` + +Less common; useful when the eligibility set is fixed at experiment start and you want assignment to be deterministic and explicit (e.g., for compliance audit). The downside: new users joining mid-experiment are not in the table; either skip them or fall back to hash assignment. + +The deterministic hash approach is the default for warehouse-native because it requires no service dependency and produces stable, auditable assignments. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## The exposure log + +The single most important discipline in warehouse-native experimentation. + +Required exposure event schema: + +\| Field \| Type \| Notes \| +\|---\|---\|---\| +\| `experiment_id` \| string \| Unique identifier per experiment. \| +\| `variant_id` \| string \| The variant the user was bucketed into. \| +\| `user_id` \| string \| The assignment unit. \| +\| `exposed_at` \| timestamp \| ISO 8601 UTC. The moment exposure fired. \| +\| `context_` \| various \| Optional context properties: device, page, account_id. \| + +Fire exposure exactly when the user has seen the variant-specific behavior. Not at page load. Not at session start. Not at app open. + +The "delayed exposure" trap. If the variant only matters at button click and you fire exposure at page load, every page-load user enters the analysis whether or not they ever saw the variant. The control group includes users who never reached the button; the treatment group does too. The analysis dilutes the real effect. + +Worked example. The treatment shows a new pricing page; the control shows the old one. Fire exposure when the pricing page loads, not when the user lands on the homepage. Users who never reach the pricing page are not exposed to either variant; they should not be in the analysis. + +The "always-fire" trap. Some implementations fire exposure on every variant-specific interaction. The user clicks the button five times; exposure fires five times. The exposure log is now five times larger than it should be, and analysis tools that count distinct user_ids in exposure handle this correctly while tools that count rows do not. + +The discipline. Fire exactly one exposure event per user per experiment, at the moment of first variant-specific exposure. Use a deterministic flag in the client (or a server-side cache) to enforce single-fire. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## Metric definitions in dbt models + +Defining metrics as dbt models gives you four things. + +1. Version control on metric definitions.* Every change to a metric is a git commit. The history is queryable. +2. Testability. dbt tests on the metric output catch regressions. +3. Composability. The same `fct_orders` model feeds the board dashboard, the experiment analysis, and the executive report. Aligned definitions, no drift. +4. Single source of truth. When the experiment says X and the board says Y, the answer is in the dbt model, not in two unrelated SQL files. + +Pattern. + +```sql +-- models/experiments/exp_metrics_revenue.sql +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + MIN(occurred_at) AS first_purchase_at +FROM {{ ref('fct_orders') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' +GROUP BY user_id +``` + +The experiment analysis joins this to the exposure log on `user_id` and computes group means. + +The variance discipline. The same metric definition is used in board dashboards AND in experiment analysis. No "experiment-specific revenue calculation" that is slightly different. Otherwise you get the "the experiment said the revenue lifted but the board did not move" problem, which is almost always a metric-definition mismatch. + +The namespace pattern. Use `exp_metrics_` for experiment-shaped models that group by `user_id` and produce one row per user. Use `fct_` for the underlying fact tables that feed both metric models and dashboards. Detail in [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md). + +--- + +## Statistical analysis in SQL + +The basic two-sample Welch's t-test in SQL. + +```sql +WITH metric_by_variant AS ( + SELECT + e.variant_id, + COUNT() AS n, + AVG(m.net_revenue_cents) AS mean, + VAR_SAMP(m.net_revenue_cents) AS variance + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' + GROUP BY e.variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic +FROM + (SELECT FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment +``` + +Convert the t-statistic to a p-value or confidence interval using a SQL function (BigQuery: a UDF; Snowflake: native or a stored procedure) or compute in Python on the result of the SQL query. + +The SQL pattern is fine for simple t-tests on continuous metrics. For proportions tests, swap variance for `p * (1 - p)`. For non-parametric tests (Mann-Whitney), the SQL gets ugly fast; switch to Python. + +Anything more complex than a simple t-test (CUPED, bootstrap, doubly robust estimation, sequential testing) is easier in Python. Use SQL for the SUM-and-AVG aggregations; ship the result to Python for the statistical math. Detail in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Statistical analysis in Python + +The Python pattern, typically in a Jupyter or Hex notebook. + +```python +import pandas as pd +import numpy as np +from scipy import stats + +# Pull aggregated data from the warehouse +df = warehouse.query(""" + SELECT user_id, variant_id, net_revenue_cents + FROM exp_results + WHERE experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].net_revenue_cents +treatment = df[df.variant_id == 'treatment'].net_revenue_cents + +# Welch's t-test +t, p = stats.ttest_ind(treatment, control, equal_var=False) + +# Confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} cents (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"p-value: {p:.4f}") +``` + +Python gives you access to the full statistical ecosystem (`scipy`, `statsmodels`, `numpy`) for techniques SQL cannot easily express. + +The notebook pattern. One notebook per experiment, parameterized by `experiment_id`. Version-controlled in git or as Hex projects. Each notebook produces a written-up decision document at the end, archived in a queryable repository (Notion, GitHub markdown, or a dedicated experiment-results table in the warehouse). + +Detail and bootstrap templates in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Variance reduction: CUPED and beyond + +The most powerful variance reduction technique for warehouse-native experimentation: CUPED (Controlled-experiment Using Pre-Experiment Data). Originally from Microsoft. + +The intuition. If you can predict a user's metric behavior from pre-experiment data, you can subtract out that predicted variance, leaving a smaller residual to test on. + +```python +# Pre-experiment metric for each user (e.g., last 28 days revenue) +pre = pre_period_revenue(user_id) + +# Theta is the regression coefficient of the metric on the pre-period +theta = np.cov(metric, pre)[0, 1] / np.var(pre) + +# Adjusted metric +adjusted_metric = metric - theta * (pre - pre.mean()) +``` + +Run the t-test on the adjusted metric instead of the raw metric. The mean is preserved (CUPED does not change the point estimate) but the variance is smaller, so the confidence interval is narrower. + +CUPED typically reduces variance by 30 to 50 percent on engagement metrics. That is equivalent to running an experiment 1.5x to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +Other variance reduction techniques. + +- Stratification. Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. +- Regression adjustment. Fit an OLS regression with covariates; the residual analysis has lower variance. Generalizes CUPED to multiple covariates. +- Doubly robust estimation. Combines outcome modeling and propensity-score weighting. Useful in observational and quasi-experimental settings where randomization was imperfect. Outside the scope of typical A/B tests; pointer to academic references in the variance-reduction reference file. + +Detail with worked examples in [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md). + +--- + +## Pre-experiment power analysis + +Before running, compute required sample size. + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Solve for sample size given desired MDE +n_per_arm = tt_ind_solve_power( + effect_size=0.05, # Cohen's d + nobs1=None, + alpha=0.05, + power=0.8 +) + +# Or solve for MDE given sample size +mde = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8 +) +``` + +The "we need 10x more users than we thought" lesson. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10% lift; the actual effect is 1%, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. + +The fix. Use the historical distribution of past experiments' observed effects to set realistic MDE expectations. If the median observed effect across the last 30 experiments is 0.5%, plan for a 0.5% MDE on new experiments. The optimism asymmetry is real; correcting it requires looking at the actual distribution of effects, not the wished-for distribution. + +Detail in [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md). + +--- + +## Sequential testing patterns + +The "peeking" problem. Looking at experiment results before completion inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. + +Three approaches. + +- mSPRT (mixture Sequential Probability Ratio Test). Used by Optimizely and Statsig. Provides an always-valid p-value that survives peeking. Implementation in Python via `statsmodels` or custom code; not natively in SQL. +- Always-Valid Inference with confidence sequences. Howard et al. Confidence intervals that are valid at any sample size. Implementation requires careful Python; not for the data team that has not read the paper. +- Group sequential designs (O'Brien-Fleming boundaries). Pre-specified interim analysis points with calibrated alpha-spending. The classic frequentist approach. + +For warehouse-native, the practical recommendation is mSPRT in Python. Document the alpha-spending function used. Train one team member on the math; do not rely on a black-box implementation. + +The honest version. If you do not have someone on the team who understands sequential testing math, just do not peek. Pre-register sample size, run to completion, analyze once. Sequential testing is statistically correct only when implemented correctly; an incorrect implementation is worse than no peeking discipline at all. + +Detail in [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md). + +--- + +## Common pitfalls + +Eleven patterns recur in warehouse-native experimentation. Detail in [`references/common-pitfalls.md`](references/common-pitfalls.md). + +- "Our exposure log fires at page load." Should fire when the variant-specific behavior is shown, not at page load. The "delayed exposure" trap dilutes the effect. +- "We see lift in control, not treatment." Assignment-hash collision or salt reuse. Audit the salt; check that different experiments produce different bucket assignments for the same user. +- "P-value is 0.04, we are shipping." Probably underpowered plus multiple comparisons plus peeking. Compute the test at the planned sample size only; correct for multiple secondary metrics. +- "Experiment shows 30% lift." Almost certainly a bug. Effects that big rarely exist; first action is to audit the exposure log and metric definitions before celebrating. +- "Treatment users are different." Sample ratio mismatch (SRM). The assignment hash is broken or the exposure log is biased. Check the SRM before computing any metric. +- "We cannot reproduce yesterday's number." Non-deterministic queries (window functions without explicit ORDER BY, sampling without a seed) or floating-point issues in aggregations. Make queries deterministic; document the random seed if any. +- "Custom metric definition disagrees with the board metric." Bad. Align them by using the same dbt model. Otherwise nobody trusts either number. +- "We never finished the experiment." Pre-register stop criteria; honor them. Experiments that drift indefinitely waste team time and produce ambiguous decisions. +- "iOS users converted 3x in treatment." Segment effect or instrumentation bug. Check if iOS instrumentation differs from the rest. Beware over-claiming on small segments. +- "It worked on phase 1, broke on phase 2." Simpson's paradox from cohort mix shift. The aggregate trend reverses when the underlying segments are weighted differently across phases. +- "Statistical significance but tiny effect." Large sample inflated power. The p-value is below 0.05 but the effect is 0.3%. Consider practical significance: is 0.3% worth shipping? + +--- + +## The framework: 12 considerations for warehouse-native experimentation + +When designing or running a warehouse-native experiment, walk these 12 considerations. + +1. Platform vs warehouse decision. Cost, custom metrics, segmentation, trust, team strength. Read `experimentation-platform-orchestrator` if undecided. +2. Assignment unit. User, account, session, device. Pick once at experiment start and stick to it. +3. Assignment salt. Unique per experiment to prevent correlation with prior experiments. Document the salt convention. +4. Exposure logging discipline. Fire when the variant matters, not at page load. One exposure event per user per experiment. +5. SRM check. Sample ratio mismatch indicates assignment bugs. Check before computing any metric. +6. Metric definition reuse. Same dbt model for board and experiment. No experiment-specific calculations that drift from canonical metrics. +7. Pre-experiment power analysis. Realistic MDE based on the historical distribution of past observed effects. +8. Variance reduction. CUPED for engagement metrics. 30 to 50 percent variance reduction is worth the engineering for any team running 5+ experiments per quarter. +9. Statistical method. Welch's t-test as default. Bootstrap for skewed distributions. Doubly robust estimation for quasi-experiments. +10. Sequential testing. mSPRT or stop-at-N. Document alpha-spending. If you cannot implement correctly, do not peek. +11. Multiple comparisons. Bonferroni or Benjamini-Hochberg correction across secondary metrics. +12. Decision documentation. Write the result up. Archive in a queryable repository. The next experiment will benefit from the institutional memory. + +The output of the framework is an experiment record. Pre-registered sample size and stop criteria, the assignment salt, the exposure log specification, the dbt metric model, the analysis notebook, and a written-up decision. The record lives in version control or in a dedicated experiment-tracking system; the analysis is reproducible from the record. + +--- + +## Reference files + +- [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md) - When each operational model is the right call. Cost considerations at different scales. Hybrid patterns. Migration patterns. +- [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md) - Hash assignment SQL templates for BigQuery and Snowflake. Salt naming conventions. Exposure event schema. SRM check SQL. +- [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md) - dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. +- [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md) - SQL and Python templates for Welch's t-test, proportions test, Mann-Whitney, bootstrap. Notebook structure. +- [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md) - CUPED math and Python implementation with worked example. Stratification. Regression adjustment. Doubly robust estimation primer. +- [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md) - MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. +- [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md) - mSPRT, confidence sequences, group sequential designs. Honest framing on when to peek. +- [`references/common-pitfalls.md`](references/common-pitfalls.md) - Eleven failure patterns with diagnoses and fixes. + +--- + +## Closing: the build-vs-buy decision is real + +Warehouse-native experimentation is powerful but expensive in engineering time. A first-year experimentation team should almost always start with a platform; the platform handles 90 percent of cases and lets you focus on hypotheses, not infrastructure. The team that graduates to warehouse-native does so because their volume, custom metric needs, or trust requirements outgrew what platforms offer. + +If you are building warehouse-native because "platforms cost too much" without first running the math: you are underestimating the cost of your team's engineering time. The platform fee that looks expensive on a procurement form is often cheaper than three months of a data engineer's time spent reinventing CUPED. + +If you are building it because the platform cannot handle your specific needs: you are probably right and the investment will pay back. Platforms are general; your business is specific. The custom metric the platform cannot express is often the metric that matters most for your decisions. + +Honest middle ground: many mature teams use both. The platform for fast iteration on standard experiments where time-to-result matters more than custom depth. Warehouse-native for the hard cases where the platform's metric library or segmentation cannot reach. The hybrid is operationally complex; document the rule for which experiments go where, and revisit annually. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md new file mode 100644 index 0000000..a043446 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md @@ -0,0 +1,230 @@ +# Assignment and exposure patterns + +Hash assignment SQL templates. Salt naming conventions. Exposure event schema. The delayed-exposure trap. Sample ratio mismatch (SRM) check. + +--- + +## Hash assignment SQL templates + +### BigQuery + +```sql +-- 50/50 split for experiment exp_button_color_v1 +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Snowflake + +```sql +-- 50/50 split using SHA1 hash and modulo +SELECT + user_id, + CASE + WHEN MOD(ABS(HASH(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Postgres + +```sql +-- 50/50 split using md5 hash; convert hex to integer +SELECT + user_id, + CASE + WHEN ('x' \|\| SUBSTRING(MD5(user_id \|\| 'exp_button_color_v1'), 1, 8))::bit(32)::int % 100 < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Three-arm split + +```sql +-- 33/33/34 split (control / variant_a / variant_b) +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 33 + THEN 'control' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 66 + THEN 'variant_a' + ELSE 'variant_b' + END AS variant_id +FROM dim_users; +``` + +### Sub-sampling for opt-in experiments + +```sql +-- 10% of users in the experiment, 50/50 split among them +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_eligibility'))), 100) >= 10 + THEN 'not_in_experiment' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +Note the two different salts: one for eligibility, one for assignment. This ensures the eligibility decision is independent of the variant decision. + +--- + +## Salt naming conventions + +Three rules. + +1. Unique per experiment. Reuse the same salt across experiments and you correlate assignments. A user in control of experiment A is more likely to be in control of experiment B; the experiments interfere. +2. Stable across the experiment lifecycle. Do not change the salt mid-experiment. Changing the salt re-randomizes existing users; the analysis becomes uninterpretable. +3. Versioned. When semantics change, append `_v2`. The old experiment data remains queryable; the new salt produces independent assignments. + +Convention. + +``` +{prefix}_{descriptor}_{version} +``` + +Examples. + +- `exp_button_color_v1` +- `exp_pricing_test_v1` (eligibility salt) +- `exp_pricing_test_assign_v1` (assignment salt within eligible) +- `exp_recommendation_model_v2` (version 2 of an existing experiment) + +Document the salt convention. Add it to the experiment record. + +--- + +## Exposure event schema + +The required fields. + +\| Field \| Type \| Required \| Notes \| +\|---\|---\|---\|---\| +\| `experiment_id` \| string \| Required \| Unique identifier per experiment. \| +\| `variant_id` \| string \| Required \| The variant the user was bucketed into. \| +\| `user_id` \| string \| Required \| The assignment unit. \| +\| `exposed_at` \| timestamp \| Required \| ISO 8601 UTC. Server-stamped. \| +\| `assigned_at` \| timestamp \| Optional \| When the user was first assigned (may differ from exposed). \| +\| `device_type` \| string \| Optional \| mobile, web, desktop. \| +\| `app_version` \| string \| Optional \| For change-tracking when version-specific bugs surface. \| +\| `account_id` \| string \| Optional \| For B2B; the account context. \| +\| `session_id` \| string \| Optional \| For session-level path analysis. \| + +The minimum schema is the four required fields. Optional fields support segmentation and debugging. + +### Storage pattern + +Either as a dedicated `experiment_exposures` table or as an event in the main events table with `event_name = 'experiment_exposed'`. + +Dedicated table is cleaner for analysis. Main events table is simpler for instrumentation. Pick one and stick to it. + +--- + +## The delayed-exposure trap + +The single most common warehouse-native experimentation bug. + +The setup. The treatment shows a new pricing page; the control shows the old one. The team fires exposure at homepage load. + +The problem. Many users land on the homepage but never click through to the pricing page. They are counted as "exposed" to the experiment but never saw the variant. The control group includes users who never reached the pricing page; the treatment group does too. + +The result. The analysis dilutes the real effect. The treatment may have produced a 20 percent lift among users who actually saw the pricing page, but the analysis shows a 2 percent lift because 90 percent of "exposed" users never reached the variant. + +The fix. Fire exposure exactly when the user has seen the variant-specific behavior. + +```javascript +// Wrong: fires at every page load +function onHomepageLoad(user) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: getVariant(user), + user_id: user.id, + }); +} + +// Right: fires when the pricing page renders the variant-specific UI +function onPricingPageLoad(user) { + const variant = getVariant(user); + if (variant === 'treatment') { + renderNewPricingPage(); + } else { + renderOldPricingPage(); + } + // Fire once per user per experiment + if (!hasExposureFired(user, 'exp_pricing_v1')) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: variant, + user_id: user.id, + }); + markExposureFired(user, 'exp_pricing_v1'); + } +} +``` + +The discipline. Fire exposure when the variant-specific UI renders or the variant-specific code path executes. Use a single-fire flag (client-side cache or server-side state) to ensure exposure fires exactly once per user per experiment. + +--- + +## Sample ratio mismatch (SRM) check + +Before computing any metric, check that the assignment is balanced. + +```sql +-- For a 50/50 split, expect roughly equal counts in control and treatment +SELECT + variant_id, + COUNT() AS n, + COUNT() * 1.0 / SUM(COUNT()) OVER () AS share +FROM exposures +WHERE experiment_id = 'exp_button_color_v1' +GROUP BY variant_id; +``` + +Expected output. + +\| variant_id \| n \| share \| +\|------------\|--------\|-------\| +\| control \| 50,123 \| 0.501 \| +\| treatment \| 49,877 \| 0.499 \| + +If the share deviates from the expected 50 percent by more than 1 percentage point at large samples, you have an SRM. The chi-squared test detects this formally. + +```python +from scipy.stats import chi2_contingency + +observed = [50123, 49877] # control, treatment +expected_ratio = [0.5, 0.5] +chi2, p, dof, _ = chi2_contingency([observed, [sum(observed) r for r in expected_ratio]]) +print(f"SRM chi-squared p-value: {p:.4f}") +# p < 0.001 indicates SRM +``` + +If you have an SRM. Do not analyze the experiment. The assignment is broken (hash collision, biased exposure logging, instrumentation that fires for one variant but not the other). Fix the bug; restart the experiment. + +The honest pattern. Run an SRM check at the top of every experiment analysis notebook. If SRM is detected, abort with a clear error message; do not let the analysis proceed. + +--- + +## Common assignment and exposure mistakes + +- Salt reuse across experiments. A user in control of experiment A is correlated with control of experiment B. Use unique salts per experiment. +- Changing the salt mid-experiment. Re-randomizes existing users. The analysis becomes a mix of two different assignment functions. Pre-register the salt; freeze it at experiment start. +- Firing exposure on every event. Inflates the exposure log by 10 to 100x. Use single-fire enforcement. +- Server-side fire when only client renders the variant. Server-side fires for every API call; client-side fires only when the user reaches the variant-specific UI. Match exposure to where the variant matters. +- Eligibility check in the wrong place. Eligibility (e.g., paid users only) checked client-side after assignment produces biased exposure (only paid users in the log). Check eligibility before assignment, server-side. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md new file mode 100644 index 0000000..5e96609 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/common-pitfalls.md @@ -0,0 +1,143 @@ +# Common pitfalls + +Eleven failure patterns that recur in warehouse-native experimentation. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Exposure log fires at page load + +Symptom. The experiment shows a 1 percent lift; the team expected 10 percent. The lift is real but diluted because most exposed users never saw the variant. + +Root cause. Exposure fires at page load (or session start) regardless of whether the user reaches the variant-specific code path. The control group includes users who never saw the variant; the treatment group does too. + +Fix. Move exposure firing to the moment the variant-specific UI renders or the variant-specific code path executes. Re-run the experiment with corrected logging. + +Prevention. Document the exposure-firing rule in the experiment record. Code review the implementation. Check the exposure-to-metric ratio (if exposure count is much higher than expected metric count, exposure is firing too broadly). + +--- + +## 2. Lift in control, not treatment + +Symptom. The control group has a higher mean than the treatment group. The team is confused because the variant-specific changes should have increased the metric. + +Root cause. Assignment hash collision or salt reuse with a prior experiment. Users in control of the new experiment are correlated with users in treatment of an old experiment that also affected the metric. + +Fix. Audit the salt. Use a unique salt per experiment. Re-run with corrected assignment. + +Prevention. Salt naming convention with version suffix. Code review for new experiments. Run a chi-squared test of independence between the new experiment's assignment and recent prior experiments' assignments before launching. + +--- + +## 3. P-value is 0.04, we are shipping + +Symptom. The primary metric p-value is 0.04. The team declares victory and ships. Three months later the metric in production has not moved. + +Root cause. Some combination of underpowered experiment, multiple comparisons without correction, and peeking. Each of these inflates the false-positive rate; together they make a 0.04 p-value uninformative. + +Fix. Re-run with a pre-registered sample size, single primary metric, no peeking. If the lift is real, the second experiment will confirm it. If not, the first result was a false positive. + +Prevention. Pre-register the sample size, the primary metric, and the analysis method. Do not peek. Apply Bonferroni or BH correction across secondary metrics. Treat 0.04 with much more skepticism than 0.001. + +--- + +## 4. Experiment shows 30 percent lift + +Symptom. The treatment shows a 30 percent lift on the primary metric. The team is excited. + +Root cause. Almost certainly a bug. Effects that big rarely exist outside truly novel features. Common bugs: exposure log fires only for treatment users (control is missing); metric model has a join error that double-counts treatment events; assignment is non-random and treatment is over-represented in heavy users. + +Fix. Audit the exposure log balance, the assignment ratio, and the metric model. Compare metric values to the historical baseline; if the treatment metric is higher than the all-users historical metric, something is wrong. + +Prevention. Skepticism about large effects. Run an SRM check before any analysis. Compare exposed-treatment metric to the historical baseline as a sanity check. + +--- + +## 5. Treatment users are different (sample ratio mismatch) + +Symptom. The exposure log shows 52,000 control users and 48,000 treatment users for a planned 50/50 split. The chi-squared test rejects the null at p < 0.001. + +Root cause. Assignment is not balanced. Possible causes: hash function bug, biased exposure logging, instrumentation that fires for one variant but not the other, eligibility check that runs differently across variants. + +Fix. Do not analyze the experiment. Find and fix the assignment bug. Restart. + +Prevention. Run the SRM check at the top of every analysis notebook. Abort with a clear error message if SRM is detected. Code review the exposure logging for both variants. + +--- + +## 6. Cannot reproduce yesterday's number + +Symptom. Yesterday's analysis showed 5.2 percent lift; today's shows 4.8 percent. Same query, same data, same notebook. The team cannot tell which is "the" answer. + +Root cause. Non-deterministic queries. Window functions without explicit `ORDER BY` produce different results on different runs. Sampling without a seed produces different samples. Floating-point aggregations on large datasets produce slight numeric differences depending on the order of summation. + +Fix. Make queries deterministic. Add explicit `ORDER BY` to window functions. Set a seed for any sampling. For floating-point precision, sum integers (cents) instead of floats; convert to dollars only at display time. + +Prevention. Code review for non-determinism. Save the query plan or the result set; compare across runs to detect drift early. + +--- + +## 7. Custom metric definition disagrees with board metric + +Symptom. The experiment says revenue lifted 5 percent; the board's revenue dashboard shows revenue flat. The team cannot tell which is right. + +Root cause. Two different SQL queries computing "revenue" with subtly different rules. The experiment query may include or exclude refunds, internal users, test orders, or specific time windows in different ways than the board. + +Fix. Align via shared dbt models. The board's revenue dashboard and the experiment's revenue metric reference the same `fct_orders` model with the same filters. + +Prevention. Schema discipline. Every metric used in an experiment is also used somewhere in the board or weekly review. Drift between the two is a code smell that should be caught at code review. + +--- + +## 8. We never finished the experiment + +Symptom. The experiment has been running for 8 weeks. The team has looked at the dashboard three times. Each time the result was inconclusive. The team keeps running it hoping for a clear answer. + +Root cause. No pre-registered stop criteria. The experiment was launched without a clear "we will stop when X" rule. The team is implicitly peeking and refusing to call it. + +Fix. Set a stop date and honor it. Analyze once on the stop date; report the result (which may be inconclusive). Document the inconclusive result and the design improvements needed for the next attempt. + +Prevention. Pre-register the sample size, the stop date, and the decision rule. Honor them. + +--- + +## 9. iOS users converted 3x in treatment + +Symptom. The aggregate treatment lift is small (1 percent), but the iOS segment shows a 3x lift. The team wants to ship the variant for iOS specifically. + +Root cause. Three possibilities. (a) Real segment effect: iOS users genuinely prefer the variant. (b) Instrumentation bug: iOS metric tracking differs from the rest. (c) Multiple comparisons: among many segments, one shows a large effect by chance. + +Fix. Investigate. Compare iOS metric tracking to other platforms (is the same event firing the same way?). Check the iOS sample size (if small, the 3x is high variance). Re-run the experiment with iOS as the primary segment if the team genuinely wants iOS-specific results. + +Prevention. Pre-register segments of interest. Apply multiple-comparisons correction across segments. Treat unexpected segment effects as hypotheses to confirm in a follow-up experiment, not as ship signals. + +--- + +## 10. Worked on phase 1, broke on phase 2 + +Symptom. Phase 1 of a staged rollout showed a clear positive lift. Phase 2 (broader audience) shows a much smaller or negative lift. The team is confused. + +Root cause. Simpson's paradox from cohort mix shift. Phase 1's audience is enriched in a segment where the treatment works well; phase 2 includes more of a segment where the treatment works poorly. The aggregate result reverses. + +Fix. Decompose by segment. The phase 2 result is the truer estimate (broader audience), but the phase 1 result tells you which segments respond. Consider a segment-specific rollout if the segment-level economics support it. + +Prevention. Run the experiment on the full target audience from the start, not on a phase-1 sub-audience. If staged rollout is operationally required, plan for the cohort mix shift in the analysis. + +--- + +## 11. Statistical significance but tiny effect + +Symptom. The p-value is 0.001. The lift is 0.3 percent. The experiment is statistically significant but the team is unsure whether to ship. + +Root cause. Large sample inflated the test's power. The test detects effects much smaller than the team's practical significance threshold. + +Fix. Apply the practical-significance check. If the team's threshold is "ship at 1 percent or larger," 0.3 percent does not meet the bar regardless of the p-value. Document the result; do not ship. + +Prevention. Pre-register the practical-significance threshold (the MDE) at experiment design time. Treat statistical significance below the MDE as inconclusive, not as a ship signal. + +--- + +## The pattern across all eleven + +Most warehouse-native experimentation failures share one root cause: the team did not pre-register enough discipline before the experiment started. Pre-registered sample size prevents underpowered analysis. Pre-registered exposure rule prevents the delayed-exposure trap. Pre-registered primary metric prevents multiple-comparisons fishing. Pre-registered stop criteria prevent the experiment-runs-forever pattern. + +The fix at the meta level. Treat each experiment as a contract. Before launching, write down the assignment unit, the salt, the exposure rule, the primary metric, the secondary metrics with multiple-comparisons correction, the sample size, the stop criteria, the practical-significance threshold. The contract is reviewed at launch. Deviations from the contract during the experiment require explicit re-registration. The discipline is the only thing that scales as the team runs more experiments. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md new file mode 100644 index 0000000..7ecfb76 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md @@ -0,0 +1,229 @@ +# Metric definitions in dbt + +dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. Aligning with board metrics. + +The principle. Define experiment metrics as dbt models so they are version-controlled, testable, and aligned with board metrics. The same source of truth for both surfaces eliminates the "experiment said X but the board says Y" problem. + +--- + +## The namespace pattern + +Three layers in a typical dbt project. + +- `stg_`: staging models. Light cleanup of source data. One per source table. +- `fct_` and `dim_`: marts models. Business-logic transformations. Joined and enriched data ready for consumption. +- `exp_metrics_`: experiment-shaped models. One row per assignment unit (typically `user_id`) with the metrics needed for analysis. + +Example structure. + +``` +models/ + staging/ + stg_orders.sql + stg_users.sql + stg_events.sql + marts/ + fct_orders.sql + fct_sessions.sql + dim_users.sql + experiments/ + exp_metrics_revenue.sql + exp_metrics_engagement.sql + exp_metrics_retention.sql +``` + +The `fct_` models feed both the board dashboard and the experiment metrics. The `exp_metrics_` models pivot to one row per user with the metrics joined or aggregated. + +--- + +## Pattern 1: revenue metric + +```sql +-- models/experiments/exp_metrics_revenue.sql +{{ config(materialized='table') }} + +WITH order_data AS ( + SELECT + user_id, + occurred_at, + amount_cents, + refunded + FROM {{ ref('fct_orders') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +) +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + SUM(amount_cents) AS gross_revenue_cents, + COUNT() AS order_count, + MIN(occurred_at) AS first_order_at +FROM order_data +GROUP BY user_id; +``` + +Note the `var()` references for experiment start and end dates. The variables come from the dbt project's variables file or are passed at run time. + +The same `fct_orders` model feeds the board's revenue dashboard. Aligned definitions. + +--- + +## Pattern 2: engagement metric + +```sql +-- models/experiments/exp_metrics_engagement.sql +{{ config(materialized='table') }} + +WITH event_data AS ( + SELECT + user_id, + occurred_at, + event_name + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' + AND event_name IN ('content_created', 'content_edited', 'content_shared') +) +SELECT + user_id, + COUNT() AS engagement_event_count, + COUNT(DISTINCT DATE(occurred_at)) AS active_day_count, + SUM(CASE WHEN event_name = 'content_shared' THEN 1 ELSE 0 END) AS shares_count +FROM event_data +GROUP BY user_id; +``` + +The metric definition specifies exactly which events count as engagement. The board's "weekly active users" dashboard uses the same event filter via the same `fct_events` model. + +--- + +## Pattern 3: retention metric (bracket retention) + +```sql +-- models/experiments/exp_metrics_retention_w2.sql +{{ config(materialized='table') }} + +WITH user_first_activity AS ( + SELECT user_id, MIN(occurred_at) AS first_active_at + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + GROUP BY user_id +), +week2_activity AS ( + SELECT DISTINCT u.user_id + FROM user_first_activity u + JOIN {{ ref('fct_events') }} e ON e.user_id = u.user_id + WHERE e.occurred_at >= u.first_active_at + INTERVAL '7 days' + AND e.occurred_at < u.first_active_at + INTERVAL '14 days' +) +SELECT + u.user_id, + CASE WHEN w2.user_id IS NOT NULL THEN 1 ELSE 0 END AS retained_w2 +FROM user_first_activity u +LEFT JOIN week2_activity w2 USING (user_id); +``` + +Bracket retention (week 2 = days 7 to 13 from first activity) is more stable than N-day retention. The metric is binary: 1 if retained, 0 if not. + +--- + +## Pattern 4: ratio metric (delta method required) + +Some metrics are ratios (conversion rate, click-through rate). They require the delta method for correct variance estimation. + +```sql +-- models/experiments/exp_metrics_conversion.sql +{{ config(materialized='table') }} + +SELECT + user_id, + COUNT() AS impressions, + SUM(CASE WHEN converted THEN 1 ELSE 0 END) AS conversions +FROM {{ ref('fct_funnel_events') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +GROUP BY user_id; +``` + +The model produces numerator and denominator per user. The analysis layer (Python) computes the ratio and applies the delta method for variance. + +```python +# Per-user numerator and denominator +df = warehouse.query("SELECT FROM exp_metrics_conversion") + +# Group means +control = df[df.variant_id == 'control'] +treatment = df[df.variant_id == 'treatment'] + +# Conversion rate per group +control_rate = control.conversions.sum() / control.impressions.sum() +treatment_rate = treatment.conversions.sum() / treatment.impressions.sum() + +# Delta method variance (skipping the math here; see statistical-analysis-templates.md) +# ... +``` + +Do not compute the ratio per user and average it. That undercounts heavy users; the delta method is the correct treatment. + +--- + +## Versioning metric definitions + +Same versioning pattern as elsewhere. When the metric definition changes meaningfully, append `_v2`. + +``` +exp_metrics_revenue.sql <- v1, fires alongside v2 during transition +exp_metrics_revenue_v2.sql <- new semantics +``` + +The transition is the same: ship v2 alongside v1, migrate experiments to v2 over 90 days, deprecate v1. + +dbt's built-in versioning (the `models:` config with `versions:`) is also useful here; lets you serve both versions from the same model name with explicit version selection. + +--- + +## Aligning experiment metrics with board metrics + +The variance discipline. The same dbt model feeds both surfaces. + +If the board reports "monthly revenue" by summing `amount_cents` from `fct_orders` and excluding refunded orders, the experiment's revenue metric does the same. No special "experiment revenue" calculation that subtly differs. + +The mechanism. Both the board dashboard's SQL and the `exp_metrics_revenue` model reference the same `fct_orders` table with the same filters. dbt tests verify the table contains the expected rows. + +The check. When an experiment lands and the team reports "revenue lifted 5 percent in treatment," the team can pull the same numbers from the board and compare. If the board's revenue is flat or the experiment's lift is much larger than the board's revenue trend, the metric definitions disagree somewhere. Investigate. + +--- + +## Testing experiment metrics + +dbt tests on the metric models catch regressions. + +```yaml +# models/experiments/_experiments.yml +version: 2 + +models: + - name: exp_metrics_revenue + columns: + - name: user_id + tests: + - not_null + - unique + - name: net_revenue_cents + tests: + - not_null + - dbt_utils.expression_is_true: + expression: ">= 0" +``` + +The `unique` test on `user_id` confirms the model produces one row per user (no accidental duplicates from a bad join). The `>= 0` test confirms revenue is non-negative (refunds are subtracted, never additive). + +--- + +## Common metric-definition mistakes + +- Drift between board and experiment. "Experiment revenue" is computed differently from "board revenue." Align via shared dbt models. +- Wrong time window. The experiment runs for 14 days but the metric model includes 30 days of data. The control and treatment numbers are similar because the variant signal is diluted. +- One row per event instead of one row per user. Joining the metric to exposure on `user_id` produces a row explosion. Always aggregate to one row per user before joining. +- Forgetting to handle nulls. Users with no activity should appear with metric = 0, not be missing from the model. Use `LEFT JOIN` from exposure or include all eligible users in the metric model. +- Non-deterministic queries. Window functions without explicit `ORDER BY`, sampling without a random seed. The same query produces different numbers on different days. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md new file mode 100644 index 0000000..c7008f5 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/power-analysis-calculations.md @@ -0,0 +1,169 @@ +# Power analysis calculations + +Pre-experiment power analysis. MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. + +The principle. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10 percent lift; the actual effect is 1 percent, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. Power analysis prevents this by forcing a concrete decision about how big the lift needs to be before the experiment starts. + +--- + +## The four parameters + +Power analysis ties together four numbers. Fix any three; the fourth is determined. + +1. Effect size (or MDE, minimum detectable effect). The smallest lift the experiment can reliably detect. Expressed as a relative percentage, an absolute difference, or Cohen's d (effect size in standard deviations). +2. Sample size per arm. Number of users in each variant. +3. Alpha (significance level). Default 0.05. The false-positive rate. +4. Power. Default 0.8. One minus the false-negative rate. The probability of detecting a real effect. + +The standard practice. Fix alpha at 0.05, power at 0.8, decide on either the MDE (and solve for sample size) or the sample size (and solve for MDE). + +--- + +## Solving for sample size given MDE + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Continuous metric, two-sample t-test +# Cohen's d = (mean_treatment - mean_control) / pooled_std + +cohens_d = 0.05 # 5 percent of one standard deviation + +n_per_arm = tt_ind_solve_power( + effect_size=cohens_d, + nobs1=None, + alpha=0.05, + power=0.8, + ratio=1.0 # equal sample sizes per arm +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a Cohen's d of 0.05 (small effect), expect roughly 6,300 users per arm. For 0.1 (still small), roughly 1,600 per arm. For 0.2 (medium), roughly 400 per arm. + +### Solving for proportions + +```python +from statsmodels.stats.power import zt_ind_solve_power + +# Binary metric, proportions test +# baseline conversion rate = 5 percent; target lift = 5 percent relative +baseline_p = 0.05 +relative_lift = 0.05 +treatment_p = baseline_p * (1 + relative_lift) + +# Cohen's h for proportions +import numpy as np +def cohens_h(p1, p2): + return 2 * np.arcsin(np.sqrt(p1)) - 2 * np.arcsin(np.sqrt(p2)) + +h = cohens_h(treatment_p, baseline_p) + +n_per_arm = zt_ind_solve_power( + effect_size=h, + nobs1=None, + alpha=0.05, + power=0.8 +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a 5 percent relative lift on a 5 percent baseline conversion rate, expect roughly 60,000 users per arm. Small relative lifts on small baselines need very large samples. + +--- + +## Solving for MDE given sample size + +The reverse calculation. Given the available sample (e.g., 8,000 users per arm), what is the smallest effect the experiment can detect? + +```python +from statsmodels.stats.power import tt_ind_solve_power + +mde_cohens_d = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8, + ratio=1.0 +) +print(f"MDE in Cohen's d: {mde_cohens_d:.4f}") + +# Convert to relative MDE assuming the metric's standard deviation +metric_std = 50.0 # in cents, for example +metric_mean = 200.0 +mde_absolute = mde_cohens_d * metric_std +mde_relative = mde_absolute / metric_mean +print(f"MDE absolute: {mde_absolute:.2f}") +print(f"MDE relative: {mde_relative:.2%}") +``` + +If the available sample yields an MDE of 8 percent and the team expects only a 2 percent lift, the experiment is underpowered. Either secure more sample (run longer or expand the audience) or accept that the experiment will produce an inconclusive result. + +--- + +## Calibrating effect-size assumptions from historical experiments + +The most common power-analysis mistake is over-optimistic effect-size estimates. Three patterns help calibrate. + +### Pattern 1: pull the historical distribution + +For the last 30 (or however many) experiments, pull the observed lifts. Compute the median, 25th percentile, and 75th percentile. + +```python +df = warehouse.query(""" + SELECT experiment_id, observed_relative_lift + FROM experiment_results + WHERE shipped = true + ORDER BY ended_at DESC + LIMIT 30 +""") + +print(f"Median observed lift: {df.observed_relative_lift.median():.2%}") +print(f"P25: {df.observed_relative_lift.quantile(0.25):.2%}") +print(f"P75: {df.observed_relative_lift.quantile(0.75):.2%}") +``` + +The median observed lift is the realistic expectation for the next experiment. If past experiments show a median lift of 1 percent, planning for a 5 percent lift on the next experiment is optimistic. + +### Pattern 2: stratify by experiment type + +Pricing experiments often produce larger lifts than UI experiments. Onboarding experiments often produce larger lifts than feature-discovery experiments. Pull the distribution by experiment type to set type-specific expectations. + +### Pattern 3: ask the team about prior experiments they remember + +The "we usually see X" estimate from team members is anchored on memorable experiments (the wins, the disasters). Compare against the actual distribution; the memorable estimate is usually too high. + +The honest conversation. "Our last 30 experiments had a median observed lift of 0.5 percent. We are planning this experiment for a 5 percent MDE. Either the experiment is going to produce an inconclusive result, or we are expecting an unusually large effect. Which is it?" + +--- + +## When the math says "we cannot run this" + +Three escalation paths when the available sample is insufficient. + +1. Run longer. The default. If the experiment needs 60,000 users per arm and you have 10,000 per week, plan for a 6-week run. Document the duration before starting. +2. Expand the audience. If the experiment is targeting only paid users (10 percent of the user base), consider running on all users. The result is generalizable to a broader population, but the intervention may need to work for the broader population too. +3. Accept inconclusive. Some experiments cannot be powered with the available sample. Document the MDE; design the experiment to detect a larger effect or accept that it will be inconclusive. The discipline of saying "we cannot reliably answer this with our sample" is hard but honest. + +--- + +## The underpowered-experiment cost + +A team running 12 experiments per quarter, 4 of which are underpowered. The cost. + +- Underpowered experiments produce inconclusive results. The team learns nothing. +- Engineering and design effort spent on the experiment is wasted. +- Stakeholders treat inconclusive as "no effect"; later experiments that would have shown the same effect at a larger sample also produce inconclusive, reinforcing the false belief that no effect exists. +- The team's experimentation discipline degrades because the visible track record looks bad. + +Power analysis at the design stage prevents most of this. The cost is 30 minutes of work; the benefit is avoiding multi-week runs of experiments that cannot answer the question. + +--- + +## Common power-analysis mistakes + +- Optimistic effect-size assumption. Plan for a 10 percent lift; observe a 1 percent lift. The experiment is 100x underpowered. +- Forgetting variance from the historical metric. Power calculations use Cohen's d, which depends on the metric's standard deviation. A high-variance metric requires a larger sample for the same MDE than a low-variance metric. +- Computing power on aggregate when the assignment unit is something else. If the assignment unit is user but the metric is per-event, the per-event variance includes within-user correlation. Use the user-level variance for the calculation. +- Skipping the calculation for "small" experiments. "We will just see what happens" is the path to a quarter of inconclusive experiments. +- Confusing statistical significance with practical significance. A p-value below 0.05 with a 0.3 percent effect on a 100,000-user experiment is statistically significant but may not be worth shipping. Use the MDE as the practical-significance threshold; a 0.3 percent effect is below most teams' MDE. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md new file mode 100644 index 0000000..401eb49 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md @@ -0,0 +1,148 @@ +# Sequential testing patterns + +mSPRT, confidence sequences, group sequential designs. Plus an honest framing on when to peek. + +The principle. Looking at experiment results before completion (peeking) inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. The honest middle ground: if you do not understand the math, do not peek. + +--- + +## The peeking problem + +The standard t-test assumes a fixed sample size pre-registered before the experiment runs. When the team peeks early, the test is implicitly running multiple times; some of those peeks will hit p < 0.05 by chance even when no effect exists. + +A team that peeks daily on a 4-week experiment runs the test roughly 28 times. The implicit false-positive rate becomes much higher than the nominal 5 percent. Estimates suggest 30 percent or more in this case; the experiment is more likely to show a fake significant result than a real one. + +The four solutions. + +1. Do not peek. Pre-register the sample size; analyze once. +2. mSPRT. Always-valid p-values that survive peeking. +3. Confidence sequences. Always-valid confidence intervals via the Howard et al construction. +4. Group sequential designs. Pre-specified interim analyses with calibrated alpha-spending. + +Each solution requires implementation discipline. Incorrect implementation is worse than no peeking solution at all (the team thinks the math is correct and ships based on inflated false-positives). + +--- + +## mSPRT (mixture Sequential Probability Ratio Test) + +The most commonly deployed sequential testing method. Used by Optimizely, Statsig. + +The intuition. Compute a Bayes-factor-like statistic that updates as data arrives. The statistic crosses a fixed threshold when the evidence is strong enough to reject the null; it never crosses by chance under the null (with the correct calibration). + +### Python implementation sketch + +```python +import numpy as np + +def mSPRT(treatment, control, prior_var=1.0, alpha=0.05): + """ + Mixture SPRT for two-sample mean difference. + Returns the always-valid p-value at the current sample. + """ + n_t = len(treatment) + n_c = len(control) + diff = treatment.mean() - control.mean() + pooled_var = (treatment.var() / n_t + control.var() / n_c) + se = np.sqrt(pooled_var) + + # Test statistic + z = diff / se + + # Mixture prior with variance prior_var + # Always-valid p-value via the mixture-likelihood ratio + n_eff = (n_t * n_c) / (n_t + n_c) + weight = np.sqrt(prior_var / (prior_var + 1.0 / n_eff)) + log_lr = 0.5 * z*2 (1 - weight*2) - 0.5 np.log(1.0 / weight2) + p_always_valid = min(1.0, np.exp(-log_lr)) + + return p_always_valid +``` + +Note: the implementation above is a sketch for illustration. Production implementations should use a peer-reviewed library or expert review. Do not deploy this verbatim. + +The honest version. Use a maintained library (`sequential` in R, custom Python adapted from peer-reviewed papers like Johari et al 2017). Have a statistician on the team review the implementation. + +--- + +## Confidence sequences (Always-Valid Inference) + +The Howard et al construction. Confidence intervals that are valid at any sample size; the team can peek arbitrarily often without inflating the false-positive rate. + +The math is more involved than mSPRT. Useful when the team needs not just always-valid p-values but always-valid confidence intervals (effect size with uncertainty). + +References. + +- Howard, Ramdas, McAuliffe, Sekhon (2021), "Time-uniform, nonparametric, nonasymptotic confidence sequences." +- Code: `sequential` package in R, or custom Python. + +For most warehouse-native teams, mSPRT is enough. Confidence sequences are for teams with a statistician who has read the paper and validated the implementation. + +--- + +## Group sequential designs + +The classical frequentist approach. Pre-specified interim analysis points (e.g., at 25 percent, 50 percent, 75 percent of the planned sample) with calibrated alpha-spending boundaries. + +The most common boundary is O'Brien-Fleming. Conservative early (high effect size required to stop early); lenient late (lower effect size required to stop at the final analysis). + +```python +# Hypothetical O'Brien-Fleming boundaries for 4 interim analyses +# Z-values; if observed Z exceeds, reject the null and stop +boundaries = { + 0.25: 4.05, + 0.50: 2.86, + 0.75: 2.34, + 1.00: 2.02, +} +``` + +The discipline. + +1. Pre-register the interim analysis points and the boundary values. +2. At each interim point, compute the test statistic. +3. If the statistic exceeds the boundary, stop the experiment and reject the null. +4. If the statistic does not exceed any boundary by the final analysis, fail to reject (treat as inconclusive or as "no effect detected"). + +Group sequential designs require commitment up front. Adding interim analyses after the experiment starts is post-hoc peeking and inflates the false-positive rate. + +--- + +## When to peek and when not to + +Three scenarios. + +### Scenario 1: small team, no statistician, simple experiments + +Do not peek. Pre-register the sample size; analyze once at completion. The discipline is simpler than implementing sequential testing correctly, and the cost (running for the full pre-registered duration) is usually small. + +### Scenario 2: high-volume team running many experiments, has a statistician + +Implement mSPRT. The peeking is operationally useful (early stops free up the testing infrastructure for the next experiment) and the math is well-understood. Train the team on the implementation; review periodically. + +### Scenario 3: regulated industry, strong audit requirements + +Group sequential design. Pre-registered interim analyses with calibrated boundaries. The audit trail is clean: every interim analysis was specified before the experiment started; the boundaries are reproducible from the design document. + +--- + +## Common sequential testing mistakes + +- Implementing mSPRT without understanding the math. A wrong implementation produces inflated false-positives that the team trusts. Worse than no peeking. +- Adding interim analyses after the experiment starts. Group sequential designs require pre-registration. Post-hoc interim analyses are just peeking. +- Mixing methods. Compute mSPRT for some peeks and a standard t-test for others. The latter inflates false-positives; the former does not. Pick one method per experiment and stick to it. +- Using mSPRT but reporting the standard p-value. The mSPRT p-value is always-valid; the standard p-value is not. Reporting the standard p-value while peeking is the same as not using mSPRT at all. +- Stopping early on a tiny effect.** mSPRT may show "significant" before the team has enough evidence on practical significance. The effect is real but small; shipping it may not be worth the engineering complexity. + +--- + +## The honest recommendation + +For most warehouse-native experimentation teams, the right answer is "do not peek." + +- Pre-register the sample size based on power analysis. +- Run to the pre-registered sample. +- Analyze once at completion. + +The cost is some early stops the team would have liked. The benefit is no implementation risk in sequential testing math, no false-positives from mis-implemented peeking, and a clean audit trail. + +Move to sequential testing when the team has the statistical expertise to implement correctly and the operational pressure to peek (high-volume infrastructure where early stops materially affect the next experiment's timeline). diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md new file mode 100644 index 0000000..c1b1137 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md @@ -0,0 +1,241 @@ +# Statistical analysis templates + +SQL and Python templates for the most common warehouse-native analyses. t-test, proportions test, Mann-Whitney, bootstrap. Plus the recommended notebook structure. + +--- + +## Welch's t-test (continuous metrics) + +The default for continuous metrics where group variances may differ. + +### SQL + +```sql +WITH joined AS ( + SELECT e.variant_id, m.net_revenue_cents + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +), +metric_by_variant AS ( + SELECT + variant_id, + COUNT() AS n, + AVG(COALESCE(net_revenue_cents, 0)) AS mean, + VAR_SAMP(COALESCE(net_revenue_cents, 0)) AS variance + FROM joined + GROUP BY variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic, + -- Standard error of the mean difference + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS se, + control.n AS control_n, + treatment.n AS treatment_n +FROM + (SELECT FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment; +``` + +The query returns the t-statistic and standard error. Convert to p-value and confidence interval via a UDF or in Python. + +### Python + +```python +import pandas as pd +from scipy import stats +import numpy as np + +df = warehouse.query(""" + SELECT e.variant_id, COALESCE(m.net_revenue_cents, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +t_stat, p_value = stats.ttest_ind(treatment, control, equal_var=False) + +# 95 percent confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"t = {t_stat:.3f}, p = {p_value:.4f}") +``` + +--- + +## Proportions test (binary metrics) + +For binary outcomes (converted vs not, retained vs not). + +### Python + +```python +from statsmodels.stats.proportion import proportions_ztest, proportion_confint + +# Counts and totals per variant +control_conv = 1240 +control_n = 25000 +treatment_conv = 1390 +treatment_n = 25000 + +# Z-test +z_stat, p_value = proportions_ztest( + [control_conv, treatment_conv], + [control_n, treatment_n] +) + +# Confidence intervals on each proportion +control_ci = proportion_confint(control_conv, control_n, method='wilson') +treatment_ci = proportion_confint(treatment_conv, treatment_n, method='wilson') + +# Lift +control_rate = control_conv / control_n +treatment_rate = treatment_conv / treatment_n +relative_lift = (treatment_rate - control_rate) / control_rate + +print(f"Control: {control_rate:.4f}, CI: {control_ci}") +print(f"Treatment: {treatment_rate:.4f}, CI: {treatment_ci}") +print(f"Relative lift: {relative_lift:.2%}") +print(f"z = {z_stat:.3f}, p = {p_value:.4f}") +``` + +The Wilson score interval is more accurate than the normal approximation for small samples or extreme proportions. + +--- + +## Mann-Whitney U test (non-parametric) + +For metrics with skewed distributions (revenue, time-on-site) where the t-test's normal-distribution assumption is violated. + +```python +from scipy.stats import mannwhitneyu + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +u_stat, p_value = mannwhitneyu(treatment, control, alternative='two-sided') + +# Mann-Whitney tests stochastic dominance, not the mean. +# Report median lift alongside. +median_lift = treatment.median() - control.median() +print(f"Median lift: {median_lift:.2f}") +print(f"U = {u_stat:.0f}, p = {p_value:.4f}") +``` + +The Mann-Whitney U test is the standard non-parametric alternative. Use when the metric distribution is skewed and the t-test's assumption fails. + +--- + +## Bootstrap confidence interval + +For metrics where the analytic distribution is unclear or unusual (e.g., retention bracket, complex composite metrics). + +```python +import numpy as np + +def bootstrap_ci(treatment, control, n_iterations=10000, alpha=0.05): + diffs = [] + for _ in range(n_iterations): + t_sample = treatment.sample(n=len(treatment), replace=True) + c_sample = control.sample(n=len(control), replace=True) + diffs.append(t_sample.mean() - c_sample.mean()) + diffs = np.array(diffs) + return np.quantile(diffs, [alpha / 2, 1 - alpha / 2]) + +ci_low, ci_high = bootstrap_ci(treatment, control) +diff = treatment.mean() - control.mean() +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +``` + +10,000 bootstrap iterations is the standard. More iterations produce tighter intervals at the cost of compute time. + +--- + +## Notebook structure + +The recommended structure for an experiment analysis notebook. + +### Cell 1: parameters + +```python +EXPERIMENT_ID = 'exp_button_color_v1' +EXPERIMENT_START = '2026-04-01' +EXPERIMENT_END = '2026-04-15' +PRIMARY_METRIC = 'net_revenue_cents' +SECONDARY_METRICS = ['order_count', 'session_count'] +ALPHA = 0.05 +``` + +Parameters at the top. Parametrize the notebook so the same template runs for any experiment. + +### Cell 2: SRM check + +```python +df_exposures = warehouse.query(f""" + SELECT variant_id, COUNT() AS n + FROM exposures + WHERE experiment_id = '{EXPERIMENT_ID}' + GROUP BY variant_id +""") + +# Chi-squared test against expected ratio +from scipy.stats import chi2_contingency +observed = df_exposures.n.values +expected = [observed.sum() / len(observed)] len(observed) +chi2, p, _, _ = chi2_contingency([observed, expected]) +assert p > 0.01, f"SRM detected (p = {p:.4f}). Aborting analysis." +print(f"SRM check passed (p = {p:.4f})") +``` + +Abort the notebook if SRM is detected. Do not proceed to metric analysis with broken assignment. + +### Cell 3: pull data + +```python +df = warehouse.query(f""" + SELECT + e.variant_id, + e.user_id, + COALESCE(m.{PRIMARY_METRIC}, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = '{EXPERIMENT_ID}' +""") +``` + +### Cell 4: primary analysis + +t-test, proportions test, or bootstrap depending on the metric. + +### Cell 5: secondary metrics + +Loop over secondary metrics; apply Bonferroni correction for multiple comparisons. + +### Cell 6: written-up decision + +A markdown cell with the conclusion. Ship, kill, or inconclusive. Include the lift, the CI, the p-value, the SRM result, and any caveats. This cell is the deliverable. + +--- + +## Common analysis mistakes + +- No SRM check. Analyzing an experiment with broken assignment produces meaningless numbers. +- Equal-variance t-test on unequal-variance data. Use Welch's (`equal_var=False`) by default. +- t-test on heavily skewed metrics. Use bootstrap or Mann-Whitney instead. +- Per-user ratios for ratio metrics. Heavy users get under-weighted. Use the delta method. +- Multiple secondary metrics without correction. With 5 secondary metrics at alpha 0.05, expect a 25 percent chance of a false positive somewhere. Bonferroni or BH correction. +- Stop-on-significance peeking. Inflates the false-positive rate. Either pre-register the sample size or use a sequential testing method correctly. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md new file mode 100644 index 0000000..daa2693 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md @@ -0,0 +1,179 @@ +# Variance reduction techniques + +CUPED is the most powerful variance reduction technique for warehouse-native experimentation. Stratification, regression adjustment, and doubly robust estimation cover specific cases. + +The principle. Variance reduction makes confidence intervals narrower at the same sample size. A 30 to 50 percent variance reduction (typical with CUPED on engagement metrics) is equivalent to running the experiment 1.5 to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +--- + +## CUPED: the workhorse + +CUPED stands for Controlled-experiment Using Pre-Experiment Data. Originally from Microsoft (Deng et al, 2013). + +The intuition. If you can predict a user's metric behavior from pre-experiment data (their behavior before the experiment started), you can subtract that prediction from the metric, leaving a smaller residual to test on. The mean is preserved (CUPED does not change the point estimate of the lift), but the variance shrinks because predictable variance has been removed. + +### The math + +For each user, compute a pre-experiment covariate (e.g., revenue in the 28 days before the experiment started). Call this `pre_metric`. The CUPED-adjusted metric is: + +``` +adjusted_metric = metric - theta * (pre_metric - mean(pre_metric)) +``` + +where `theta` is the regression coefficient of `metric` on `pre_metric`: + +``` +theta = cov(metric, pre_metric) / var(pre_metric) +``` + +Run the t-test on `adjusted_metric` instead of `metric`. The mean difference between treatment and control is preserved; the variance is reduced. + +### Python implementation + +```python +import pandas as pd +import numpy as np + +# df has columns: user_id, variant_id, metric, pre_metric +df = warehouse.query(""" + SELECT + e.user_id, + e.variant_id, + COALESCE(m.net_revenue_cents, 0) AS metric, + COALESCE(p.pre_net_revenue_cents, 0) AS pre_metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + LEFT JOIN pre_experiment_revenue p USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +# Compute theta from the entire dataset (control and treatment combined) +theta = np.cov(df.metric, df.pre_metric)[0, 1] / np.var(df.pre_metric) + +# CUPED-adjusted metric +df['adjusted_metric'] = df.metric - theta * (df.pre_metric - df.pre_metric.mean()) + +# Run t-test on the adjusted metric +from scipy import stats +control_adj = df[df.variant_id == 'control'].adjusted_metric +treatment_adj = df[df.variant_id == 'treatment'].adjusted_metric +t_stat, p_value = stats.ttest_ind(treatment_adj, control_adj, equal_var=False) + +# Compare to unadjusted variance +unadjusted_var = df.metric.var() +adjusted_var = df.adjusted_metric.var() +variance_reduction = 1 - adjusted_var / unadjusted_var +print(f"Variance reduction: {variance_reduction:.1%}") +``` + +### When CUPED works well + +- Engagement metrics with strong autocorrelation. Pre-experiment activity strongly predicts in-experiment activity. +- Revenue metrics on consumer products with repeat customers. +- Retention metrics where past retention predicts future retention. + +### When CUPED works poorly + +- New users (no pre-experiment data). They drop out of the analysis or are imputed. +- Metrics with weak temporal autocorrelation. The pre-period does not predict the in-period. +- Metrics that are zero for most users (highly skewed binary outcomes). The t-test's normal-distribution assumption fails; CUPED on top inherits the failure. + +### Pre-experiment window length + +A 28-day pre-experiment window is the typical default. Longer windows (60 to 90 days) capture more of the user's behavior pattern and may reduce variance more, but also reduce eligibility (users who joined within the window have no pre-period). + +The discipline. Pre-register the pre-period length when designing the experiment. Do not change it after looking at results. + +--- + +## Stratification + +Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. + +```python +# Stratify by device +strata = df.device_type.unique() +stratum_estimates = [] +for s in strata: + sub = df[df.device_type == s] + diff = sub[sub.variant_id == 'treatment'].metric.mean() - sub[sub.variant_id == 'control'].metric.mean() + stratum_estimates.append({ + 'stratum': s, + 'n': len(sub), + 'diff': diff, + }) + +# Pool: weighted average by stratum size +total_n = sum(s['n'] for s in stratum_estimates) +pooled_diff = sum(s['diff'] * s['n'] / total_n for s in stratum_estimates) +``` + +The variance of the pooled estimate is lower than the unpooled t-test when the strata have different baseline metrics (the across-stratum variance is removed). + +The downside. Stratification by too many covariates produces small per-stratum samples, which inflates per-stratum variance. Use stratification on one or two strong predictors, not on every covariate available. + +--- + +## Regression adjustment (covariate adjustment via OLS) + +A generalization of CUPED to multiple covariates. + +```python +import statsmodels.api as sm + +# X: covariates (pre_metric, device_type encoded, region encoded) +X = pd.get_dummies(df[['pre_metric', 'device_type', 'region']], drop_first=True) +X['variant_treatment'] = (df.variant_id == 'treatment').astype(int) +X = sm.add_constant(X) +y = df.metric + +# OLS regression +model = sm.OLS(y, X).fit() +print(model.summary()) + +# The coefficient on 'variant_treatment' is the adjusted effect estimate. +# Its standard error is typically smaller than the unadjusted t-test SE. +``` + +Regression adjustment is more flexible than CUPED but requires more care: collinearity among covariates, model misspecification, and overfitting on small samples are all possible failure modes. + +For most warehouse-native experiments, CUPED with a single pre-period covariate is enough. Regression adjustment with multiple covariates is for edge cases. + +--- + +## Doubly robust estimation + +Useful in observational and quasi-experimental settings where randomization was imperfect (geo experiments, switchback designs, natural experiments). + +The intuition. Combine an outcome model (predict the metric from covariates) with a propensity-score model (predict the probability of treatment from covariates). The combined estimator is unbiased if either of the two models is correct (hence "doubly robust estimation"). + +For the standard A/B test where assignment is random, doubly robust estimation does not help. The benefit is in observational settings where the assignment mechanism may be confounded. + +The implementation requires `causalml`, `dowhy`, or a custom implementation. Outside the scope of the typical experiment notebook; pointer to the academic literature for full treatment. + +References. + +- Bang and Robins (2005), "Doubly Robust Estimation in Missing Data and Causal Inference Models." +- Funk et al. (2011), "Doubly Robust Estimation of Causal Effects." + +--- + +## When to invest in variance reduction + +Three signals. + +1. Running 5+ experiments per quarter. The amortized engineering investment in CUPED pays back across many experiments. +2. The team is power-constrained. Experiments routinely run too long or hit inconclusive results because of insufficient sample size. CUPED extends the effective sample size by 30 to 50 percent. +3. The team has data scientists who understand the math. CUPED is straightforward but easy to implement incorrectly (theta computed on the wrong subset, pre-period window misaligned, regression diagnostics ignored). Without someone on the team who can audit the implementation, the variance reduction may not be real. + +The order of investment. CUPED first; it is the highest ROI. Stratification second; useful for one or two strong predictors. Regression adjustment third; for edge cases where multiple covariates matter. Doubly robust estimation last; for genuine quasi-experiments. + +--- + +## Common variance reduction mistakes + +- Computing theta on treatment data only. Theta should be computed on the combined dataset (control plus treatment) for unbiased estimation. Computing on treatment alone re-introduces the bias CUPED is trying to remove. +- Pre-period contamination. The pre-period overlaps with the experiment period. Users in the experiment have already been exposed when their "pre-period" metric is measured. The pre-metric is not actually pre. +- CUPED on heavily skewed binary metrics. CUPED reduces variance but does not change the metric's distribution. A binary metric where 99 percent of users are 0 is still skewed after CUPED; the t-test is still misspecified. +- Stratification on a post-experiment covariate. The covariate must be measured before the experiment, otherwise the stratification creates selection bias. Use only pre-experiment covariates for stratification. +- Forgetting to validate that variance actually decreased. Run both adjusted and unadjusted analyses; verify the adjusted variance is smaller. If it is not, CUPED is not helping for this metric and pre-period. diff --git a/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md b/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md new file mode 100644 index 0000000..21e0222 --- /dev/null +++ b/dist/pi/.agents/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md @@ -0,0 +1,145 @@ +# Warehouse vs platform decision + +Side-by-side comparison. Cost considerations at scale. Hybrid patterns. Migration patterns. Decision tree. + +The principle. Both operational models are valid. The right choice depends on team strength, volume, custom-metric needs, and how much engineering time you are willing to invest in experimentation infrastructure. + +--- + +## Side-by-side comparison + +\| Dimension \| Platform (Statsig, Optimizely, etc.) \| Warehouse-native \| +\|---\|---\|---\| +\| Time to first experiment \| Hours to days \| Days to weeks \| +\| Custom metric depth \| Limited to platform's metric library \| Anything you can write in SQL \| +\| Custom segmentation \| Platform-specific filters \| dbt models compose without limit \| +\| Cost shape \| Per-MAU or per-event subscription \| Existing warehouse compute \| +\| Engineering investment \| Low \| Medium to high \| +\| Sequential testing \| Out of the box \| Build it yourself or skip \| +\| Frontend visual editing \| Optimizely, VWO ship this \| Not applicable \| +\| Mobile SDK assignment \| Out of the box \| Build it yourself \| +\| Trust and audit \| Platform's math is a black box \| Every step is auditable SQL \| +\| Iteration speed on metric definitions \| Platform release cadence \| dbt deploy cadence \| +\| Ecosystem integration \| Platform's connectors \| Warehouse already has the data \| + +--- + +## Cost considerations at scale + +Approximate costs as of 2025-2026. Verify with vendor pricing. + +### 10K MAU + +- Platform (mid-tier): $0 to $500 per month. Free tiers from PostHog, Statsig, Amplitude cover this. +- Warehouse-native: warehouse compute already paid for. Engineering time cost: 1 to 2 weeks of a data engineer's time to set up infrastructure. + +Recommendation. Platform. The engineering time on warehouse-native at this scale does not pay back. + +### 100K MAU + +- Platform (mid-tier): $1K to $10K per month. Statsig, PostHog paid tiers; Optimizely contract. +- Warehouse-native: same warehouse compute; engineering time amortized over more experiments. + +Recommendation. Either. Depends on team strength and custom-metric needs. Many teams stay on a platform; some graduate to warehouse-native. + +### 1M MAU + +- Platform: $10K to $80K per month, often more for enterprise contracts. Optimizely Enterprise can hit $200K+ per year. +- Warehouse-native: same warehouse compute. The engineering investment pays back at this scale. + +Recommendation. Warehouse-native is increasingly attractive. Many enterprise data teams run warehouse-native primary, with a platform for specific use cases (frontend visual experiments). + +### 10M+ MAU + +- Platform: enterprise contracts at $200K to $1M+ per year. +- Warehouse-native: dominant pattern at this scale. Custom infrastructure plus dbt plus Python notebooks. + +Recommendation. Warehouse-native, often with a thin platform for fast frontend iteration. + +--- + +## Hybrid patterns + +Three common hybrid patterns. + +### Pattern 1: platform for product, warehouse-native for analytics + +The platform handles assignment and exposure for product experiments. The warehouse handles analysis for the same experiments by reading the platform's exposure data. + +Why. The platform's analysis is fine for standard cases; warehouse-native analysis allows custom metrics and segmentation the platform cannot express. + +Operational shape. The platform's exposure events flow to the warehouse (typically via webhook or scheduled export). dbt models compute custom metrics; the analyst runs the t-test in Python against the joined data. + +### Pattern 2: warehouse-native for backend, platform for frontend + +Warehouse-native handles backend experiments where assignment is server-side (pricing, recommendations, ML model variants). The platform handles frontend visual experiments (button colors, copy, layout). + +Why. Frontend visual experiments benefit from the platform's WYSIWYG editor and script-tag injection. Backend experiments benefit from warehouse-native's metric flexibility. + +Operational shape. Two separate experiment registries. Each team picks the right tool for the experiment type. + +### Pattern 3: platform for fast iteration, warehouse-native for hard cases + +The platform handles experiments where time-to-result matters more than custom depth. Warehouse-native handles experiments where the platform cannot express the metric. + +Why. Most experiments are standard; the platform is faster. The 10 percent that are not standard need the warehouse. + +Operational shape. Default to platform; escalate to warehouse-native when the platform fails to support the experiment design. + +--- + +## Migration patterns + +### Platform to warehouse-native + +Triggered by cost (the platform bill became a budget item) or capability (the platform cannot handle a specific experiment design that matters). Typical effort: 6 to 12 engineer-weeks for the first warehouse-native experiment with full infrastructure; later experiments amortize the investment. + +Steps. Build the assignment hash function. Build the exposure logging discipline. Define the first metric in dbt. Run a parallel experiment on the platform and warehouse-native; verify results match within statistical noise. Migrate experiments one at a time; retire the platform when the last in-flight experiment completes. + +### Warehouse-native to platform + +Triggered by team contraction (the data engineer who built the infrastructure left) or by velocity needs (experiments are taking too long to set up). Typical effort: 2 to 4 engineer-weeks; the platform handles the heavy lifting. + +Steps. Pick the platform. Wire up assignment and exposure. Migrate the metric library to the platform's format. Run the first experiment on the platform; verify results align with what warehouse-native would have produced. + +The frequent reverse migration. Companies that move to warehouse-native and discover the engineering investment is too much. The migration back is usually faster than the migration out. + +--- + +## Decision tree + +``` +Is your team running 5+ experiments per quarter? +├── No → Platform. Warehouse-native does not pay back at low volume. +└── Yes → Continue. + │ + Do you have a data engineer and a data scientist? + ├── No → Platform. Warehouse-native requires both roles. + └── Yes → Continue. + │ + Are your experiments primarily frontend visual? + ├── Yes → Platform (Optimizely, VWO). Warehouse-native cannot match. + └── No → Continue. + │ + Do you need custom metrics the platform cannot express? + ├── Yes → Warehouse-native. The custom metric is the use case. + └── No → Continue. + │ + Is the platform bill exceeding 10x the cost of the engineering time? + ├── Yes → Warehouse-native. The math justifies it. + └── No → Platform. The simplicity is worth the cost. +``` + +The defaults. New teams: platform. Mature teams with strong data infrastructure and high volume: hybrid or warehouse-native primary. The decision is never permanent; revisit annually. + +--- + +## When the math is wrong + +Two situations where teams misjudge the build-vs-buy. + +Underestimating engineering cost. "We can build this in a week" rarely holds. The first experiment takes weeks; the second takes days; the long tail of pitfalls (CUPED, sequential testing, SRM checks, dashboard reconciliation) adds up to months of engineering investment. Budget realistically. + +Overestimating platform limitations. "The platform cannot handle our metric" is sometimes true and sometimes a workflow problem. Verify with the vendor; many platforms have advanced features (Cortex Analyst on Snowflake, custom SQL metrics on Statsig) that solve the apparent limitation. + +The honest test. Run a 30-day proof of concept on the platform with the actual experiment you say it cannot handle. If the platform truly fails, warehouse-native is justified. If the platform works (even if imperfectly), the cost-benefit shifts back toward the platform. diff --git a/dist/pi/.agents/skills/dependency-management/SKILL.md b/dist/pi/.agents/skills/dependency-management/SKILL.md new file mode 100644 index 0000000..4ea6220 --- /dev/null +++ b/dist/pi/.agents/skills/dependency-management/SKILL.md @@ -0,0 +1,326 @@ +--- +name: dependency-management +description: "Manage third-party libraries, runtimes, and SaaS dependencies. Use this skill when setting an update cadence, responding to security advisories, dealing with deprecated dependencies, evaluating new dependencies, auditing what's installed, or unblocking a dependency upgrade. Triggers on dependency, package update, security patch, lockfile, deprecated, breaking change, supply chain, dependency audit, npm audit, dependabot, renovate. Also triggers when a build breaks after an update or when an advisory is published for a used package." +category: cross-cutting +catalog_summary: "Package updates, security patches, lockfile hygiene" +display_order: 4 +--- + +# Dependency Management + +Decide what to depend on, keep dependencies current, respond to advisories, and reduce supply chain risk. Stack-agnostic principles; specifics vary by package manager. + +--- + +## When to use + +- Setting up dependency hygiene for a new or existing project +- Responding to a security advisory +- Major version upgrade of a key dependency +- Adding a new dependency (evaluation, decision) +- Removing a dependency (cleanup) +- Audit of what's installed and what's actually used +- Setting an update cadence and policy +- Diagnosing a broken build after an update + +## When NOT to use + +- General code review (use `code-review-web`) +- Vulnerability scanning of infrastructure (use `security-baseline`) +- Pinning vendor or service contracts (use `vendor-evaluation`) +- Performance impact of dependencies (use `performance-optimization`) + +--- + +## Required inputs + +- Package manager and lockfile in use (npm, yarn, pnpm, pip, gem, composer, etc.) +- Current dependency list (production and dev) +- Current advisories (run audit; check service like Snyk, Dependabot) +- Update history (when were major dependencies last updated) +- Risk profile (production criticality, change tolerance) + +--- + +## The framework: 4 categories of dependency + +Every dependency falls into one of these. The category drives the policy. + +### Category 1: Critical runtime + +Code that runs in production and would break the system if it failed. + +Examples: framework, database driver, payment SDK, authentication library. + +Policy: +- Update cadence: monthly minor, quarterly major (with planning) +- Security: patch within 24-72 hours of advisory, 24h for critical +- Pinning: exact version pins or narrow ranges +- Vetting: thoroughly evaluated before adoption + +### Category 2: Supporting runtime + +Code that runs in production but is replaceable or non-critical. + +Examples: utility libraries, formatting, non-core integrations. + +Policy: +- Update cadence: monthly together with critical +- Security: patch within a week of advisory +- Pinning: narrow ranges acceptable (e.g., `^1.2.3`) +- Vetting: moderate evaluation; alternatives considered + +### Category 3: Dev/build + +Code that runs only during development or build, not in production. + +Examples: bundlers, linters, test frameworks, type checkers. + +Policy: +- Update cadence: quarterly +- Security: patch within a week (still matters; supply chain attacks target build tools) +- Pinning: ranges acceptable +- Vetting: lighter; broken dev tools surface fast + +### Category 4: Optional/dev-only-personal + +Tools individual developers use that aren't part of shared dev environment. + +Not really managed at the project level. Mentioned for completeness. + +--- + +## The framework: 5 risk dimensions + +When evaluating a dependency, consider: + +### Dimension 1: Maintenance health + +- Last commit date (months ago is concerning) +- Open issue count and age +- Number of maintainers +- Sponsorship or commercial backing +- Roadmap visibility + +A dependency abandoned a year ago is a liability waiting to surface. + +### Dimension 2: Surface area + +- Size of the package +- Number of transitive dependencies +- Footprint in the bundle (for client-side) +- Privileges required (file system, network, etc.) + +A small dependency that pulls in 50 transitive packages has the surface area of all 50. + +### Dimension 3: Replaceability + +- How hard would it be to remove? +- Are there alternatives? +- Could the functionality be implemented in-house? +- Is the API standard or idiomatic? + +A dependency you can't replace is leverage you've granted to its maintainer. + +### Dimension 4: Trust + +- Reputation of the maintainer or organization +- Code quality (skim the source) +- License (GPL, MIT, BSD, proprietary, none) +- History of security issues +- Supply chain practices (signed releases, 2FA on publishes) + +### Dimension 5: Cost + +- Time to evaluate, integrate, maintain +- Risk of breaking changes +- Lockfile entropy +- Potential security exposure +- Bundle size impact (for client-side) + +Every dependency has a cost. Free packages aren't free. + +--- + +## Workflow + +### Step 1: Inventory + +Run a dependency listing: + +```bash +# npm/yarn/pnpm +npm ls --all --json + +# pip +pip list + +# gem +bundle list +``` + +For each top-level dependency, categorize (critical / supporting / dev). For transitives, you generally don't manage individually unless one becomes a problem. + +### Step 2: Audit + +Run the security audit: + +```bash +npm audit +yarn audit +pip-audit +bundle audit +``` + +For each finding: +- Severity (critical, high, medium, low) +- Package and version +- Fix available? +- Used directly or transitively? + +### Step 3: Categorize and prioritize + +\| Severity \| Direct dep \| Indirect dep \| +\|---\|---\|---\| +\| Critical \| Patch today \| Patch this week (if a fix exists; track if not) \| +\| High \| Patch this week \| Patch this month \| +\| Medium \| Patch this month \| Track; patch with next round \| +\| Low \| Track \| Track \| + +Critical and high in production code are emergencies. Low and medium are scheduled work. + +### Step 4: Test before merging fixes + +Even patch-level updates can break things. For critical dependencies: +- Run the full test suite +- Smoke-test in staging +- Watch the monitoring after rollout + +For supporting and dev: +- Run the test suite +- A failed test is OK to investigate; don't merge a known-broken update + +### Step 5: Plan major version upgrades + +Major versions break things. Plan rather than rush. + +For each major upgrade: +- Read the changelog and migration guide +- Estimate the migration effort +- Schedule the work (don't do it under deadline pressure) +- Branch and test thoroughly +- Plan a staged rollout if it's a critical dependency + +Don't sit on major versions indefinitely. The longer you wait, the more painful the upgrade. + +### Step 6: Set the policy + +Document: +- Update cadence (e.g., monthly review, quarterly upgrades) +- Security response SLA (e.g., critical within 24h) +- Approval for new dependencies (who signs off) +- Removal criteria (when do we drop a dependency) +- Pinning strategy (exact, narrow range, broad range) + +The policy is what survives team turnover. Without it, dependency management becomes chaotic ad hoc work. + +### Step 7: Automate + +- Renovate or Dependabot for automatic update PRs +- CI runs audit on every PR +- Block merges on critical advisories (with override path for false positives) +- Notify on advisories for installed packages +- Lockfile diff in PR review + +Automation reduces toil. Manual checking doesn't scale. + +### Step 8: Audit usage periodically + +Quarterly: +- Dependencies installed but not imported anywhere (run a tool like `depcheck`) +- Major versions behind (more than 1-2 majors behind = upgrade plan needed) +- Unmaintained packages (last commit over a year ago = consider replacing) +- License audit (anything that's changed terms?) + +Remove what's not used. Replace what's unmaintained. + +--- + +## New dependency evaluation + +Before adding a new dependency, answer: + +- [ ] What problem does this solve? +- [ ] Could we solve it without a dependency? (Often yes for small problems.) +- [ ] What alternatives exist? +- [ ] Is the package actively maintained? +- [ ] What's the install size and bundle impact? +- [ ] What are the transitive dependencies? (Worth a quick scan.) +- [ ] What's the license? +- [ ] What's the security history? +- [ ] How replaceable is it? + +Default: don't add. Add only when the value clearly exceeds the cost. The cost includes ongoing maintenance, not just installation. + +--- + +## Dependency removal + +When removing a dependency: + +- [ ] Identify all usages (search the codebase) +- [ ] Replace each usage (with native code, another dependency, or a no-op) +- [ ] Remove from package.json or equivalent +- [ ] Update lockfile (run install) +- [ ] Verify tests pass +- [ ] Verify build size went down (or stayed the same) +- [ ] Document the removal in the changelog + +Removed dependencies sometimes leave config files, CI hooks, or imports behind. Search broadly. + +--- + +## Failure patterns + +No update cadence. Dependencies drift. When you finally upgrade, it's painful. Set a cadence. + +Audit disabled in CI. "Too noisy." Tune the audit, don't disable it. Whitelist known false positives explicitly. + +Pinning everything to exact versions. Stops automatic patches. Misses security fixes. Use narrow ranges with a lockfile. + +Unpinned floating versions. `latest` in production. Builds aren't reproducible. Lockfile required. + +Adding dependencies without review. "I just needed a quick utility." Now there are 50 unused dependencies. Require review for new dependencies. + +Ignoring transitive dependencies. A direct dependency pulls in 50 indirect ones. Each is supply chain surface. Audit the tree, not just the top level. + +Patching with major version bumps. "Updating to fix a bug" but the update is a major version. Now you have unrelated breaking changes too. Be deliberate about the version of the fix. + +Vendor-bundled libraries. Some dependencies vendor copies of other dependencies. They're not visible to the audit. Periodically check. + +Build-time dependencies treated as zero-risk. Build tools have access to your code and credentials. Supply chain attacks target them. Treat with appropriate care. + +Fork without rebase plan. Forking a dependency to fix something. Then you own it. Plan how to rebase or merge upstream changes, or commit to maintaining the fork. + +No license audit. Project ships with a GPL dependency in a commercial product. Compliance issue. Audit licenses on add and quarterly. + +Update PRs piling up. Dependabot PRs go unmerged for months. Either tune to fewer PRs or commit time to merging them. + +--- + +## Output format + +A dependency policy document includes: + +- Inventory: current dependencies by category +- Audit status: open advisories, severity, plan +- Policies: cadence, SLA, pinning, approval +- Tooling: what's automated (Renovate, Dependabot, audit in CI) +- License audit: any concerns +- Quarterly review schedule: when this gets revisited + +--- + +## Reference files + +- [`references/upgrade-checklist.md`](references/upgrade-checklist.md): Step-by-step checklist for performing a major version upgrade of a critical dependency, from changelog reading to staged rollout. diff --git a/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md b/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md new file mode 100644 index 0000000..f9e6929 --- /dev/null +++ b/dist/pi/.agents/skills/dependency-management/references/upgrade-checklist.md @@ -0,0 +1,290 @@ +# Major Version Upgrade Checklist + +Step-by-step checklist for upgrading a critical dependency to a new major version. The work is in the prep, not the install. + +--- + +## Phase 1: Decide whether to upgrade + +- [ ] Read the changelog from current version to target version +- [ ] Read the migration guide (most major libraries publish one) +- [ ] Skim issues filed against the new version (early adopters surface problems) +- [ ] Note any other dependencies that may need to upgrade in tandem +- [ ] Estimate effort (hours, days, weeks?) +- [ ] Estimate risk (low/medium/high) +- [ ] Estimate value (security fix, new features, ecosystem support, etc.) + +Decision: GO, DEFER, or SKIP. + +GO triggers: +- Security fix only available in new major +- Current version losing support +- New version unblocks a needed feature +- Effort and risk are manageable + +DEFER triggers: +- New version released within last 30 days (let early adopters surface bugs) +- Conflicts with active development +- No urgent driver + +SKIP triggers: +- Maintenance discontinued; replace the dependency instead +- Migration effort exceeds the value +- A different replacement is the better path + +--- + +## Phase 2: Prepare + +### Branch + +- [ ] Create a feature branch named for the upgrade (e.g., `upgrade/library-v3`) +- [ ] Don't mix the upgrade with other work; isolate it + +### Read the changelog carefully + +- [ ] List every breaking change between current and target version +- [ ] Note deprecations that affect your code +- [ ] Note new patterns or APIs you'll use after the upgrade + +For each breaking change: +- Where does this affect our code? +- What's the migration path? +- Is there a codemod available? + +### Search for usages + +- [ ] Grep for every API surface used (function names, import paths) +- [ ] Identify call sites that need attention +- [ ] Identify tests that may break + +For complex libraries, this can be the longest step. Be thorough. + +### Check the ecosystem + +- [ ] Plugins or related packages that depend on the library: do they support the new version? +- [ ] TypeScript types: are they updated? +- [ ] Documentation and examples in the wild: have they caught up? + +--- + +## Phase 3: Upgrade + +### Install + +- [ ] Update the version in package.json (or equivalent) +- [ ] Update related packages (plugins, types, etc.) to compatible versions +- [ ] Run install, generate fresh lockfile +- [ ] Verify the install completes without errors + +```bash +# Example +npm install library@^3.0.0 +``` + +### Initial build + +- [ ] Run the build +- [ ] Note every error and warning +- [ ] Don't fix anything yet; just inventory + +### Inventory the breakage + +Categorize each error: +- Type errors: API signatures changed +- Import errors: module structure changed +- Runtime errors: behavior changed +- Test failures: assumed behavior changed +- Lint warnings: patterns deprecated + +This list is your work plan. + +--- + +## Phase 4: Migrate + +### Apply codemods first + +If the library publishes codemods: + +```bash +npx codemod-name path/to/code +``` + +Codemods handle the mechanical parts (renamed APIs, restructured imports). They're not perfect, but they reduce toil. + +- [ ] Run codemods +- [ ] Review the diff (codemods can over-apply or under-apply) +- [ ] Commit the codemod changes separately + +### Fix manual issues + +For each remaining issue: +- [ ] Identify the root cause (what changed in the new version?) +- [ ] Apply the fix per the migration guide +- [ ] Verify tests pass for that area +- [ ] Commit incrementally (small commits, easy to revert) + +### Update tests + +- [ ] Tests using deprecated patterns: update to new patterns +- [ ] Tests that fail because behavior is different: investigate. Is the new behavior correct? +- [ ] Add tests for any new behavior you depend on + +### Update documentation + +- [ ] README references to the old version +- [ ] Internal docs and runbooks +- [ ] Comments referencing the old behavior + +--- + +## Phase 5: Verify + +### Local + +- [ ] All tests pass (unit, integration, E2E) +- [ ] Build succeeds without warnings (or with only acceptable warnings) +- [ ] Lint passes +- [ ] Type check passes (if typed) +- [ ] No console warnings in dev mode that weren't there before + +### Visual + +For UI-affecting libraries: +- [ ] Visual regression tests (Chromatic, Percy, or similar) clean +- [ ] Manual smoke test of key user flows +- [ ] Check on multiple browsers/devices + +### Performance + +- [ ] Bundle size: comparable or better +- [ ] Build time: comparable +- [ ] Runtime performance: comparable on key paths + +If bundle size or performance regresses meaningfully, investigate before merging. + +### Compatibility + +- [ ] Browser compatibility (if relevant) maintained +- [ ] Node version compatibility (if relevant) maintained +- [ ] Other dependencies still work with the new version + +--- + +## Phase 6: Stage + +For critical dependencies, don't go straight to production. + +- [ ] Deploy to a staging environment +- [ ] Run automated tests against staging +- [ ] Smoke-test critical flows manually +- [ ] Watch monitoring for new errors +- [ ] Watch performance metrics for regressions +- [ ] Let it bake for at least 24 hours (longer for critical systems) + +--- + +## Phase 7: Roll out + +Strategy depends on the dependency and the risk: + +### Low risk: standard deploy + +- [ ] Merge the PR +- [ ] Deploy to production +- [ ] Watch monitoring for the next few hours +- [ ] Be ready to rollback + +### Medium risk: feature flag or canary + +- [ ] Behind a feature flag if applicable +- [ ] Deploy with traffic splitting (1% to new, 99% to old, if infrastructure supports) +- [ ] Gradually increase traffic +- [ ] Watch metrics at each step + +### High risk: parallel run + +- [ ] Run old and new side by side +- [ ] Compare outputs +- [ ] Switch over only when confident + +--- + +## Phase 8: Monitor + +For at least one week post-rollout: + +- [ ] Error rates (compare to pre-upgrade baseline) +- [ ] Performance metrics +- [ ] User-reported issues +- [ ] Any unexpected behavior + +If issues appear: +- [ ] Triage by severity +- [ ] Fix forward (most common) +- [ ] Or rollback (if severe) +- [ ] Document the issues for the next upgrade + +--- + +## Phase 9: Document + +After the upgrade is stable: + +- [ ] Note the upgrade in the changelog +- [ ] Document any non-obvious migrations for future reference +- [ ] Update internal docs that referenced the old version +- [ ] If the upgrade was painful, write a note for next time +- [ ] Thank anyone who helped (especially open-source maintainers if they helped) + +--- + +## Common gotchas + +Bundle size grows unexpectedly. New version pulls in additional code or dependencies. Check the bundle analysis. + +Tests that "passed but didn't actually run." Test infrastructure breaks silently in some upgrades. Verify tests are running, not just exiting clean. + +TypeScript types don't match runtime. Sometimes types are updated but runtime isn't (or vice versa). Test runtime behavior, not just types. + +Server-side rendering breaks. New version uses browser-only APIs. Check SSR if applicable. + +Tree-shaking changes. Bundle includes more or different code. Verify what's actually shipped. + +Peer dependency conflicts. Library A wants version X, library B wants version Y. Resolve carefully; sometimes requires upgrading multiple in tandem. + +Breaking changes in transitive dependencies. The upgrade pulls in a new major of a transitive. The transitive's breaking changes affect you indirectly. + +API changes that compile but behave differently. Same function name, different default behavior. Read the changelog. + +Migration guide assumes specific framework or stack. If you use the library in a non-standard way, the guide may not cover your case. Adapt. + +--- + +## When to abort + +It's OK to abort an upgrade. Better to abort than ship a broken version. + +Abort triggers: +- Migration effort blowing past estimate by 5x+ +- Discovering critical incompatibilities mid-migration +- Finding that the new version has bugs blocking your use case +- Realizing the dependency itself is the problem (consider replacement) + +After aborting: +- Keep the branch around for reference +- Document what you learned +- Schedule a retry when conditions are better, or pivot to replacement + +--- + +## Reference for next time + +After every major upgrade, capture: +- Total effort (hours) +- Surprises encountered +- Things that worked well +- Things to do differently + +This becomes input to estimating the next major upgrade. Major upgrades happen periodically; the team gets better at them with practice and notes. diff --git a/dist/pi/.agents/skills/design-standards/SKILL.md b/dist/pi/.agents/skills/design-standards/SKILL.md new file mode 100644 index 0000000..ee3d5dd --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/SKILL.md @@ -0,0 +1,213 @@ +--- +name: design-standards +description: "Apply production-grade design standards when building or reviewing pages, components, or UI. Use this skill whenever the user asks to build a page, design a component, lay out a section, review the UI, fix the layout, or check design quality. Triggers on build a page, create a component, design a section, hero, card, CTA, layout, review the UI, fix the design, design system, design tokens, spacing, typography scale, button standards, mobile design. Also triggers for any production design decision where contrast, accessibility, spacing, or visual hierarchy matters." +category: design +catalog_summary: "Production-grade page and component design standards" +display_order: 2 +--- + +# Design Standards + +Production design standards for any web project. Stack-agnostic. Tool-agnostic. Covers tokens, contrast, hierarchy, spacing, mobile rules, and the pre-ship checklist. + +This skill complements `brand-identity` (which defines the visual system) and `brand-style-guide` (which documents it). This skill is for the day-to-day work of applying those standards in real components and pages. + +--- + +## When to use + +- Building a new page, section, or component +- Reviewing UI for quality, accessibility, or consistency +- Setting up design tokens for a new project +- Fixing layout, contrast, or hierarchy issues +- Establishing a button or form standard +- Pre-ship design review + +## When NOT to use + +- Defining a brand identity from scratch (use `brand-identity`) +- Documenting a finished brand system (use `brand-style-guide`) +- Building a formal component library (use `design-system`) +- Frontend code architecture (use `frontend-component-build`) +- Accessibility-only audits with WCAG remediation (use `accessibility-audit`) + +--- + +## Required inputs + +- The page or component being built or reviewed +- The brand's design tokens (colors, type, spacing) - or willingness to define them +- The target devices and viewports + +If brand tokens are undefined, define a working set first using the template in [`references/design-tokens-template.md`](references/design-tokens-template.md). + +--- + +## The framework: 6 standards + +Six standards apply to every piece of UI. Hold the line on these and most design problems disappear. + +### 1. Design tokens + +Every project needs tokens defined before any UI gets built. Tokens are the source of truth. + +Color tokens (minimum): +- Primary brand color +- Primary hover (typically 15 to 25 percent darker) +- Background variants (surface, alt-section, hero/dark, footer) +- Text scale (heading, body, muted, on-dark) +- Semantic (success, warning, error, info) + +Spacing tokens: +- A consistent scale (e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96) +- Page max-width +- Section vertical padding (large, medium, small) +- Card padding +- Grid gaps + +Type tokens: +- Display, H1 through H4, body large, body, small, caption +- Each with size, weight, line height, letter spacing +- Font fallback stacks + +Radius tokens: +- Tight (cards, badges) +- Standard (buttons, inputs) +- Round (avatars, pill buttons) + +Document the tokens once. Reference them everywhere. Hardcoded values are technical debt. + +### 2. WCAG AA contrast (non-negotiable) + +Contrast is not a preference. It is a baseline. A design that fails AA is broken, regardless of how it looks to designers with full vision. + +\| Element \| Required ratio \| +\|---\|---\| +\| Normal body text \| 4.5:1 \| +\| Large text (18pt regular or 14pt bold) \| 3:1 \| +\| UI components and graphical elements \| 3:1 \| + +Common failures to avoid: +- Light gray body text on white that calculates to 2 to 4:1 +- Brand color used for body text without a darker variant +- Light borders on form fields that compute under 3:1 +- Bright orange or yellow on white at small sizes + +For the math, the contrast checker, and brand-color strategies, see `brand-identity/references/contrast-and-accessibility.md`. + +### 3. Visual hierarchy + +A well-designed page has a clear scan order. Hierarchy comes from: + +- Size. The largest element gets noticed first. +- Weight. Bold beats regular at the same size. +- Color. Saturated beats neutral. High-contrast beats low. +- Spacing. What sits alone gets emphasis. What gets crowded recedes. +- Position. Top-left and center get weight. Edges and corners recede. + +Apply hierarchy intentionally. Every visual element should be reachable through the hierarchy. If three things compete for primary attention, none of them wins. + +Common failures: +- Multiple elements styled as the "primary" CTA (creates ambiguity) +- Body text and headlines too close in size +- Hero image fighting the hero text for attention +- Icon, headline, and image at similar visual weight + +### 4. Spacing and rhythm + +Spacing is what separates a polished layout from a cluttered one. + +Rules: +- Use the spacing scale, not arbitrary values +- Related elements sit closer together than unrelated ones (proximity principle) +- Section breathing room: minimum 64px desktop, 48px mobile +- Card padding: minimum 24px desktop, 16px mobile +- Form field spacing: minimum 16px between fields +- Touch targets: minimum 44 by 44 pixels + +Common failures: +- Inconsistent spacing within similar contexts (one card has 24px padding, the next has 32px) +- Cramped sections that bleed into each other +- Touch targets under 44 pixels on mobile +- Headline butted directly against subheadline with no rhythm + +### 5. Mobile rules + +Most users are on mobile. Designing for desktop first guarantees mobile failures. + +Standards: +- Test on a 375 to 390 pixel viewport before declaring complete +- All interactive elements minimum 44 by 44 pixels +- Sticky bottom bars: page wrapper needs bottom padding equal to bar height +- No fixed pixel widths without max-width constraint +- Text never smaller than 14 pixels for body content +- Tap targets get 8 pixels of spacing minimum on all sides +- Modal and popover content scrolls; body locks +- Form inputs: at least 16px text size to prevent iOS auto-zoom + +Common failures: +- Designs that work in browser dev tools but break on real devices +- Sticky navigation eating 80px of viewport without compensation +- Horizontal scroll appearing because of one over-wide element +- Tap targets that are visually fine but impossibly close to other tap targets + +### 6. Component consistency + +The same thing should look the same everywhere. Variations should be intentional. + +Common consistency principles: +- Buttons: one primary style, one secondary style, one ghost style. Not five. +- Cards: one base card pattern with variants. Not bespoke cards per page. +- Icons: one stroke weight, one corner style across the icon set +- Avatars and brand marks: one shape rule (rounded-lg or fully round, pick one and stick to it) +- Form inputs: one set of input states (default, focus, error, disabled) used everywhere + +Common failures: +- Three different "primary buttons" used inconsistently across pages +- Some cards with rounded-2xl corners, others with rounded-xl +- Iconography style drifting between sections +- Brand avatar that switches between square and round depending on the page + +--- + +## Workflow + +1. Confirm tokens. If tokens are not yet defined, define a working set first. Document them. +2. Sketch hierarchy. Before writing markup, identify the primary action, secondary actions, and supporting content. Confirm the scan order makes sense. +3. Build mobile-first. Lay out for the smallest target viewport before scaling up. +4. Apply tokens. All values come from the token set. No hardcoded colors, sizes, or spacing. +5. Run contrast checks. Every text-on-background combination passes AA. Every UI element passes 3:1. +6. Test at viewport breakpoints. 375, 768, 1024, 1440 minimum. Confirm nothing breaks. +7. Run the pre-ship checklist in [`references/preship-checklist.md`](references/preship-checklist.md). + +--- + +## Failure patterns + +- Designing without tokens. Hardcoded colors and spacing. Hard to maintain. Inconsistent at scale. +- Skipping contrast checks. Especially on brand colors used for text. Most brand colors fail AA. +- Designing only for desktop. Mobile reveals every layout sin. Test mobile first or last, but always. +- Rounded-everything. Treating "modern" as "rounded all the things." Rounded corners are a tool, not a default. +- Visual hierarchy mush. Three things competing as primary. Reader does not know where to look. +- Touch target violations. Visually nice 32px buttons that fail finger ergonomics on real devices. +- Component drift. Each page rebuilds the card or button from scratch. Design system erodes. + +--- + +## Output format + +This skill produces design decisions and review notes more than artifacts. Outputs include: + +- Design tokens file (when starting a project): `design-tokens.md` or equivalent +- Component or page review: markdown notes scored against the 6 standards, with specific fixes +- Pre-ship checklist results: pass/fail across the checklist with notes + +When generating component code (HTML, CSS, framework-specific markup), the SKILL.md remains stack-agnostic. Stack-specific patterns live in reference files. + +--- + +## Reference files + +- [`references/design-tokens-template.md`](references/design-tokens-template.md) - Template for setting up tokens for any project. +- [`references/preship-checklist.md`](references/preship-checklist.md) - Final design review checklist before shipping. +- [`references/tailwind-patterns.md`](references/tailwind-patterns.md) - Optional. Tailwind-specific component patterns (hero, cards, buttons, data rows) for projects on that stack. diff --git a/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md b/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md new file mode 100644 index 0000000..7e96765 --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/design-tokens-template.md @@ -0,0 +1,248 @@ +# Design Tokens Template + +Tokens are the source of truth for color, spacing, typography, and other design decisions. Define them once at the start of the project. Reference them everywhere. + +This template is stack-agnostic. Adapt the syntax to your project: CSS custom properties, Tailwind config, design system JSON, Style Dictionary, Figma variables - the values stay the same. + +--- + +## Color tokens + +### Primary (brand) + +``` +brand/primary #XXXXXX /* signature brand color / +brand/primary-hover #XXXXXX / 15-25% darker, for hover states / +brand/primary-text #XXXXXX / darker variant if primary fails AA on white / +``` + +### Background + +``` +bg/surface #FFFFFF / default page background / +bg/surface-alt #F9FAFB / alternating section background / +bg/hero #1A1D23 / dark section for heroes, footers / +bg/footer #111827 / footer specifically / +``` + +### Text scale + +Document each with the contrast ratio against the background it sits on. + +``` +text/heading #111827 / heading on white = 16.9:1 / +text/body #374151 / body on white = 10.3:1 / +text/muted #4B5563 / muted on white = 7.6:1 PASS AA / +text/subtle #6B7280 / subtle on white = 5.1:1 PASS AA / +text/on-dark #FFFFFF / white on hero bg = 15.8:1 / +text/on-dark-muted #D1D5DB / on hero bg = 11.4:1 / +``` + +Avoid going lighter than the muted/subtle colors above on white. Lighter grays fail AA. + +### Semantic + +``` +semantic/success #059669 / on white = 4.5:1 PASS AA / +semantic/warning #D97706 / on white = 4.5:1 PASS AA / +semantic/error #DC2626 / on white = 4.7:1 PASS AA / +semantic/info #2563EB / on white = 5.6:1 PASS AA / +``` + +For each semantic color, also define a tinted background and a darker text variant for badges and alert blocks. + +### Border and divider + +``` +border/default #E5E7EB / default borders, subtle dividers / +border/strong #D1D5DB / form fields, interactive borders / +border/focus #2563EB / focus rings / +``` + +--- + +## Spacing tokens + +A consistent scale prevents arbitrary values. + +``` +space/0 0 +space/1 4px +space/2 8px +space/3 12px +space/4 16px +space/5 20px +space/6 24px +space/8 32px +space/10 40px +space/12 48px +space/16 64px +space/20 80px +space/24 96px +space/32 128px +``` + +### Layout-specific spacing + +``` +layout/page-max-width 1280px (or 1440px for spacious designs) +layout/page-padding-x 16px mobile / 24px tablet / 32px desktop +layout/section-py-large 80px desktop / 64px mobile +layout/section-py-medium 48px desktop / 32px mobile +layout/section-py-small 32px desktop / 24px mobile +layout/card-padding 24px to 32px +layout/grid-gap 24px to 32px +``` + +--- + +## Typography tokens + +### Font families + +``` +font/display "[Display typeface]", system-ui, sans-serif +font/body "[Body typeface]", system-ui, sans-serif +font/mono "[Mono typeface]", ui-monospace, monospace +``` + +### Type scale + +\| Token \| Size \| Weight \| Line height \| Letter spacing \| Use \| +\|---\|---\|---\|---\|---\|---\| +\| type/display-1 \| 64px \| 700 \| 1.0 \| -0.02em \| Hero headlines \| +\| type/display-2 \| 48px \| 700 \| 1.05 \| -0.01em \| Section heroes \| +\| type/h1 \| 36px \| 700 \| 1.1 \| 0 \| Page titles \| +\| type/h2 \| 28px \| 600 \| 1.2 \| 0 \| Section titles \| +\| type/h3 \| 22px \| 600 \| 1.3 \| 0 \| Sub-sections \| +\| type/h4 \| 18px \| 600 \| 1.4 \| 0 \| Component titles \| +\| type/body-large \| 18px \| 400 \| 1.5 \| 0 \| Lead paragraphs \| +\| type/body \| 16px \| 400 \| 1.6 \| 0 \| Default body \| +\| type/body-small \| 14px \| 400 \| 1.5 \| 0 \| Captions, metadata \| +\| type/caption \| 12px \| 400 \| 1.4 \| 0.01em \| Footnotes, labels \| +\| type/eyebrow \| 12px \| 600 \| 1.4 \| 0.08em \| Uppercase eyebrows \| + +### Mobile adjustments + +Mobile typography is typically 1 to 2 steps smaller for display sizes: + +``` +display-1: 64px desktop → 40px mobile +display-2: 48px desktop → 32px mobile +h1: 36px desktop → 28px mobile +``` + +Body sizes stay the same on mobile; never go below 14px. + +--- + +## Radius tokens + +``` +radius/none 0 +radius/sm 4px / small badges, tags / +radius/md 8px / default for inputs / +radius/lg 12px / buttons, alerts / +radius/xl 16px / cards (small) / +radius/2xl 20px / cards (default) / +radius/3xl 24px / cards (prominent), modals / +radius/full 9999px / pill buttons, fully rounded / +``` + +### Conventions for shapes + +``` +buttons (default): radius/full (pill) OR radius/lg (rounded rect) +buttons (form/utility): radius/md +inputs: radius/md or radius/lg +cards: radius/2xl +icon containers: radius/xl (NOT radius/full unless avatar) +avatars (people): radius/full +brand avatars/logos: radius/lg (matches favicon convention) +modals: radius/3xl (top corners on mobile sheets) +``` + +Pick the conventions, document them, and stick to them. Inconsistent radius is one of the most common visual drift patterns. + +--- + +## Shadow tokens + +``` +shadow/none none +shadow/sm 0 1px 2px rgba(0,0,0,0.05) +shadow/md 0 4px 6px rgba(0,0,0,0.08) +shadow/lg 0 10px 15px rgba(0,0,0,0.10) +shadow/xl 0 20px 25px rgba(0,0,0,0.10) +shadow/2xl 0 25px 50px rgba(0,0,0,0.15) +``` + +### Shadow conventions + +``` +default cards: shadow/sm +hover state cards: shadow/md +elevated content: shadow/lg +modals/dropdowns: shadow/xl +``` + +--- + +## Z-index tokens + +A documented z-index scale prevents the "9999 wars." + +``` +z/below -1 +z/base 0 +z/raised 10 / sticky elements, fixed nav / +z/dropdown 20 / popovers, dropdowns / +z/overlay 30 / page-level overlays, scrims / +z/modal 40 / modals, dialogs / +z/toast 50 / toasts, top-of-everything notifications / +``` + +--- + +## Motion tokens + +``` +motion/duration-fast 100ms / hover state, simple feedback / +motion/duration-base 200ms / most UI transitions / +motion/duration-slow 300ms / enter/exit animations / +motion/duration-slower 500ms+ / dramatic brand moments / + +motion/ease-default cubic-bezier(0.4, 0, 0.2, 1) +motion/ease-in cubic-bezier(0.4, 0, 1, 1) +motion/ease-out cubic-bezier(0, 0, 0.2, 1) +motion/ease-bounce cubic-bezier(0.68, -0.55, 0.27, 1.55) +``` + +Always provide `prefers-reduced-motion` alternatives that disable or shorten animations for users who request it. + +--- + +## Breakpoints + +``` +breakpoint/sm 640px +breakpoint/md 768px +breakpoint/lg 1024px +breakpoint/xl 1280px +breakpoint/2xl 1536px +``` + +Test the design at viewport widths matching each breakpoint, and at 375px (smaller phone), 390px (default iPhone), and 1440px (default laptop). + +--- + +## How to use this template + +1. Copy* the structure into your project. +2. Fill in values per the brand identity. +3. Verify contrast for every text/background combination using a contrast checker. +4. Document edge cases (e.g., the darker brand variant for text contexts). +5. Reference everywhere. No hardcoded values in components. +6. Update once. When tokens change, the whole product reflects the change. + +The token file is canonical. Anything in the codebase using a hardcoded value instead of a token is technical debt waiting to surface. diff --git a/dist/pi/.agents/skills/design-standards/references/preship-checklist.md b/dist/pi/.agents/skills/design-standards/references/preship-checklist.md new file mode 100644 index 0000000..14cd7fd --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/preship-checklist.md @@ -0,0 +1,180 @@ +# Pre-Ship Design Checklist + +Run before declaring any page or component complete. Most production design defects come from skipping these. + +--- + +## Tokens and consistency + +- [ ] All colors come from the token set (no hardcoded hex values) +- [ ] All spacing comes from the spacing scale (no arbitrary px values) +- [ ] All typography uses defined type tokens +- [ ] All radii use the defined radius tokens +- [ ] Shadows use defined shadow tokens +- [ ] No more than one variant per component type (e.g., one primary button style across the page) + +--- + +## Contrast (WCAG AA) + +- [ ] All body text passes 4.5:1 against its background +- [ ] All large text passes 3:1 +- [ ] All UI elements (icons, borders, focus rings) pass 3:1 +- [ ] Brand colors used for text use the darker text variant if the signature color fails +- [ ] No light gray text under #6B7280 on white backgrounds +- [ ] Dark mode (if implemented) tested against dark surfaces, not just light + +Use a contrast checker for every pairing. Visual judgment is unreliable. + +--- + +## Visual hierarchy + +- [ ] One clear primary action per page (one primary CTA) +- [ ] Secondary actions visually subordinate to primary +- [ ] Headline larger and heavier than body text by enough to be unambiguous +- [ ] Section breaks visible without effort (spacing or background change) +- [ ] Images do not visually compete with primary content + +--- + +## Typography + +- [ ] Exactly one H1 per page +- [ ] No skipped header levels (H2 followed by H4) +- [ ] Body text minimum 14px (16px preferred) +- [ ] Line length controlled (45 to 75 characters per line for body text) +- [ ] Line height appropriate (1.4 to 1.6 for body, 1.0 to 1.2 for display) +- [ ] No fake italics or fake bold (use real font weights) + +--- + +## Spacing and rhythm + +- [ ] Consistent padding inside same-type containers (all cards, all sections) +- [ ] Section breathing room: 64px+ desktop, 48px+ mobile +- [ ] Form fields spaced minimum 16px apart vertically +- [ ] Related elements visually grouped (proximity principle) +- [ ] No cramped sections that bleed into each other + +--- + +## Buttons and CTAs + +- [ ] Primary button uses brand primary color +- [ ] Hover state visible and distinct +- [ ] Focus state visible (focus ring or equivalent) +- [ ] Disabled state visible and accessible +- [ ] Touch target minimum 44 by 44 pixels +- [ ] Button text descriptive (not "click here" or "submit") + +--- + +## Forms + +- [ ] Every input has a visible label (placeholder is not a label) +- [ ] Required fields marked clearly +- [ ] Error states have text descriptions, not just color +- [ ] Help text positioned below or beside the field, not as placeholder +- [ ] Input height accommodates touch (minimum 44px) +- [ ] Form inputs use 16px+ text on iOS to prevent zoom + +--- + +## Images and media + +- [ ] All meaningful images have descriptive alt text +- [ ] Decorative images have empty alt (`alt=""`) +- [ ] Images have explicit width and height to prevent layout shift +- [ ] Modern formats used where supported (WebP, AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] No images stretched or pixelated due to wrong sizing + +--- + +## Interactive elements + +- [ ] All interactive elements have hover states (where pointer is supported) +- [ ] Focus rings visible (do not use `outline: none` without a replacement) +- [ ] Tap targets minimum 44 by 44 pixels +- [ ] Tap targets at least 8 pixels of spacing on all sides from other tap targets +- [ ] Cursor styles correct (`pointer` for clickable, `text` for inputs, etc.) + +--- + +## Mobile (375 to 390 pixel viewport) + +- [ ] Tested on real device or device-mode in browser +- [ ] No horizontal scroll +- [ ] No fixed-width elements breaking layout +- [ ] Sticky bottom bars do not overlap content (page wrapper has bottom padding) +- [ ] Sticky top bars do not eat critical content +- [ ] Mobile menu works on touch +- [ ] All text remains readable (no truncated headlines) +- [ ] Tap targets remain 44px minimum + +--- + +## Tablet (768 to 1024 pixel viewport) + +- [ ] Layout transitions cleanly between mobile and desktop breakpoints +- [ ] No awkward in-between sizing +- [ ] Multi-column layouts adapt sensibly + +--- + +## Desktop (1280+ pixel viewport) + +- [ ] Page max-width prevents content from stretching too wide +- [ ] Typography does not break (line lengths still controlled) +- [ ] Whitespace remains balanced + +--- + +## Performance signals (visual) + +- [ ] No visible layout shift after initial render +- [ ] Images load progressively (no blank-then-pop) +- [ ] No flash of unstyled text (FOUT) for primary fonts +- [ ] No render-blocking elements above the fold + +(For deep performance audits, use `performance-optimization`.) + +--- + +## Brand and consistency + +- [ ] Logo placed correctly (per brand-style-guide rules) +- [ ] Brand colors used per brand-style-guide rules +- [ ] Imagery direction matches brand-style-guide +- [ ] Voice (in any UI text) matches brand-voice +- [ ] No off-brand stock photography or generic illustrations + +--- + +## Accessibility (basic checks; for deeper audits use `accessibility-audit`) + +- [ ] Page operable by keyboard alone +- [ ] Logical tab order +- [ ] Form fields have associated labels (`for`/`id` or `aria-labelledby`) +- [ ] Buttons and links use semantic elements (not `<div onClick>`) +- [ ] Skip links present for long pages +- [ ] Page language declared (`<html lang="...">`) + +--- + +## Pre-launch sanity + +- [ ] No placeholder text remaining ("Lorem ipsum," "TODO," "[Replace this]") +- [ ] No broken images +- [ ] No broken links (test 5 random links) +- [ ] No console errors in browser dev tools +- [ ] No accessibility errors in browser audit tools + +--- + +## Sign-off + +When all boxes check, the design is ready to ship. If any box fails, document the failure, decide whether it is a launch blocker, and either fix or file a known-issue ticket before shipping. + +The checklist is the floor, not the ceiling. Great design exceeds it. diff --git a/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md b/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md new file mode 100644 index 0000000..7b8b004 --- /dev/null +++ b/dist/pi/.agents/skills/design-standards/references/tailwind-patterns.md @@ -0,0 +1,287 @@ +# Tailwind Component Patterns + +Optional reference. Tailwind-specific component patterns for projects on that stack. The principles in [`SKILL.md`](../SKILL.md) are stack-agnostic; this file translates them into Tailwind utilities. + +If you are not using Tailwind, skip this file. The patterns translate to any utility framework or CSS approach with minor changes. + +--- + +## Page wrapper + +The standard container pattern: + +```jsx +<main className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> + {/* page content /} +</main> +``` + +Token equivalents: +- `max-w-7xl` = page max width (1280px) +- `mx-auto` = horizontal centering +- `px-4 sm:px-6 lg:px-8` = responsive horizontal padding + +For wider designs, swap `max-w-7xl` for `max-w-[1440px]`. + +--- + +## Section spacing + +```jsx +{/ Large section (heroes, major content) /} +<section className="py-20 md:py-28"> + +{/ Medium section (most content) /} +<section className="py-12 md:py-16"> + +{/ Small section (compact content) /} +<section className="py-8 md:py-12"> +``` + +Always include the mobile-first variant. Mobile sections use shorter padding to preserve viewport efficiency. + +--- + +## Dark hero + +```jsx +<section className="bg-gray-900 py-20 md:py-28"> + <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center"> + {/ Breadcrumb - text-gray-300 minimum on dark for AA /} + <nav className="text-sm text-gray-300 mb-6" aria-label="Breadcrumb"> + <a href="/" className="hover:text-white transition-colors">Home</a> + <span className="mx-2" aria-hidden="true">/</span> + <span className="text-white">Current Page</span> + </nav> + + {/ Eyebrow /} + <p className="text-xs font-semibold uppercase tracking-wider text-blue-400 mb-3"> + Section Label + </p> + + {/ H1 - exactly one per page /} + <h1 className="text-4xl md:text-6xl font-extrabold tracking-tight text-white mb-4"> + Main <span className="text-blue-400">Headline</span> + </h1> + + {/ Supporting /} + <p className="text-lg text-gray-300 max-w-2xl mx-auto"> + Supporting description that gives context. + </p> + </div> +</section> +``` + +Contrast notes: +- White on `bg-gray-900` = 17.4:1 PASS +- `text-gray-300` on `bg-gray-900` = 11.2:1 PASS AA +- `text-gray-400` on `bg-gray-900` = 7.6:1 PASS AA (still readable) +- `text-gray-500` on `bg-gray-900` = 5.5:1 PASS AA borderline; prefer 300 or 400 for body on dark + +--- + +## Feature card grid + +```jsx +<div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6"> + <div className="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm hover:shadow-md transition-shadow"> + {/ Icon container - rounded-xl, NOT rounded-full unless avatar /} + <div className="w-10 h-10 rounded-xl bg-blue-50 text-blue-600 flex items-center justify-center mb-4"> + <Icon className="w-5 h-5" /> + </div> + <h3 className="font-semibold text-gray-900 mb-2">Card Title</h3> + <p className="text-sm text-gray-600">Card description that explains the feature.</p> + </div> + {/ repeat /} +</div> +``` + +Conventions: +- `rounded-2xl` for cards (consistent radius across all cards on the site) +- `rounded-xl` for icon containers (not `rounded-full` unless it's an avatar) +- `text-gray-600` is the muted-text floor on white (passes AA at 7.6:1) + +--- + +## Data row (key-value display) + +```jsx +<div className="flex justify-between items-center rounded-xl bg-gray-50 px-4 py-3 text-sm"> + <span className="text-gray-600 font-medium">Label</span> + <span className="font-semibold text-gray-900">Value</span> +</div> +``` + +Stack rows in a `space-y-2` container for vertically grouped data. + +--- + +## Inline CTA banner + +```jsx +<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 rounded-xl border border-blue-100 bg-blue-50 px-5 py-4"> + <div> + <p className="font-semibold text-gray-900">CTA Headline</p> + <p className="text-sm text-gray-600 mt-0.5">Supporting context</p> + </div> + <a + href="#" + className="shrink-0 bg-blue-600 hover:bg-blue-700 text-white text-sm font-semibold px-4 py-2.5 rounded-full transition-colors whitespace-nowrap" + > + Action Text + </a> +</div> +``` + +The `flex-col sm:flex-row` pattern stacks on mobile, sits side-by-side on tablet+. Standard across all banner-style CTAs. + +--- + +## Author byline + +```jsx +<div className="flex items-center gap-3"> + {/ Brand/author avatar - rounded-lg matches favicon shape /} + <div className="w-9 h-9 rounded-lg bg-blue-600 flex items-center justify-center text-white text-sm font-bold flex-shrink-0"> + {authorInitial} + </div> + <div className="min-w-0"> + <a + href={`/author/${slug}`} + className="text-sm font-medium text-gray-900 hover:text-blue-700 transition-colors block truncate" + > + {authorName} + </a> + <p className="text-xs text-gray-600 truncate">{authorRole}</p> + </div> +</div> +``` + +Convention: brand and author identifiers use `rounded-lg`, not `rounded-full`. Reserve `rounded-full` for actual person photographs (people-photo avatars). + +--- + +## Buttons + +```jsx +{/ Primary - pill shape, brand color /} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold transition-colors"> + Primary Action +</a> + +{/ Secondary - outline /} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full border border-blue-600 text-blue-600 hover:bg-blue-50 font-semibold transition-colors"> + Secondary Action +</a> + +{/ Ghost - text only /} +<a className="inline-flex items-center gap-2 px-4 py-2 text-blue-600 hover:text-blue-700 font-semibold transition-colors"> + Ghost Action +</a> + +{/ Disabled state /} +<button + disabled + className="px-6 py-3 rounded-full bg-gray-200 text-gray-500 font-semibold cursor-not-allowed" +> + Disabled +</button> +``` + +Pick pill (`rounded-full`) or rounded-rect (`rounded-lg`) for buttons. Use one consistently across the entire site. + +--- + +## Form inputs + +```jsx +{/ Input with label /} +<div className="space-y-1.5"> + <label htmlFor="email" className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + id="email" + type="email" + className="w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-base shadow-sm focus:border-blue-600 focus:ring-2 focus:ring-blue-600/20 focus:outline-none" + placeholder="you@example.com" + /> + <p className="text-xs text-gray-600">We'll never share your email.</p> +</div> + +{/ Error state /} +<div className="space-y-1.5"> + <label className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + type="email" + aria-invalid="true" + aria-describedby="email-error" + className="w-full rounded-lg border border-red-500 px-3.5 py-2.5 text-base shadow-sm focus:border-red-600 focus:ring-2 focus:ring-red-600/20 focus:outline-none" + /> + <p id="email-error" className="text-xs text-red-600"> + Please enter a valid email address. + </p> +</div> +``` + +Notes: +- Always use `text-base` (16px) on inputs to prevent iOS zoom on focus +- `py-2.5` gives ~44px height with text, hitting the touch target minimum +- Error states need text, not just color (color blindness consideration) + +--- + +## Mobile sticky bar + +```jsx +<> + {/ Page wrapper needs bottom padding to compensate for the bar /} + <main className="pb-20 md:pb-0"> + {/ page content /} + </main> + + {/ Sticky bar - mobile only /} + <div className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-200 px-4 py-3 md:hidden z-30"> + <a + href="#" + className="block w-full text-center px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold" + > + Mobile CTA + </a> + </div> +</> +``` + +The `pb-20 md:pb-0` on the wrapper is critical. Without it, the sticky bar covers the bottom of the page content. + +--- + +## Common Tailwind contrast values + +Quick reference for which gray text colors pass AA on white: + +\| Class \| Hex \| Contrast on white \| AA pass \| +\|---\|---\|---\|---\| +\| `text-gray-300` \| #D1D5DB \| 1.6:1 \| FAIL (decorative only) \| +\| `text-gray-400` \| #9CA3AF \| 2.85:1 \| FAIL \| +\| `text-gray-500` \| #6B7280 \| 4.6:1 \| PASS (borderline; prefer 600) \| +\| `text-gray-600` \| #4B5563 \| 7.6:1 \| PASS \| +\| `text-gray-700` \| #374151 \| 10.3:1 \| PASS \| +\| `text-gray-800` \| #1F2937 \| 14.6:1 \| PASS \| +\| `text-gray-900` \| #111827 \| 16.9:1 \| PASS \| + +Use `text-gray-600` as the floor for body text on white. Anything lighter requires verification against the specific background. + +For dark backgrounds: + +\| Class \| Hex \| Contrast on `bg-gray-900` \| AA pass \| +\|---\|---\|---\|---\| +\| `text-white` \| #FFFFFF \| 17.4:1 \| PASS \| +\| `text-gray-300` \| #D1D5DB \| 11.2:1 \| PASS \| +\| `text-gray-400` \| #9CA3AF \| 7.6:1 \| PASS \| +\| `text-gray-500` \| #6B7280 \| 5.5:1 \| PASS borderline \| +\| `text-gray-600` \| #4B5563 \| 3.8:1 \| FAIL for body \| + +Use `text-gray-300` as the floor for body text on `bg-gray-900`. Reserve lighter grays for headlines and primary content. diff --git a/dist/pi/.agents/skills/design-system/SKILL.md b/dist/pi/.agents/skills/design-system/SKILL.md new file mode 100644 index 0000000..9ae0401 --- /dev/null +++ b/dist/pi/.agents/skills/design-system/SKILL.md @@ -0,0 +1,202 @@ +--- +name: design-system +description: "Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer." +category: design +catalog_summary: "Component library, design tokens, design system documentation" +display_order: 1 +--- + +# Design System + +Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer. + +This skill is for building the system. For applying a system to specific pages or components, use `design-standards`. For brand visual identity, use `brand-identity`. + +--- + +## When to use + +- Building a design system from scratch +- Auditing an existing system for gaps or fragmentation +- Defining design tokens at the system level +- Structuring a component library +- Establishing contribution and governance models +- Migrating from ad-hoc components to a documented system + +## When NOT to use + +- Designing a single page or component (use `design-standards`) +- Brand identity work (use `brand-identity`) +- Component-level frontend implementation (use `frontend-component-build`) +- Pure design documentation for marketing (use `brand-style-guide`) + +--- + +## Required inputs + +- The brand identity (tokens, voice, imagery direction) +- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools) +- The team and its working tools (Figma, code framework, doc platform) +- Existing components, even if undocumented +- Constraints (accessibility requirements, performance targets, browser support) + +If brand identity is undefined, run `brand-identity` first. + +--- + +## The framework: 5 layers + +A complete design system has five layers, stacked. Each layer feeds the layer above. + +### 1. Foundations (tokens) + +The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints. + +Why this layer matters:* +- Tokens are the source of truth for everything above +- Token changes propagate everywhere automatically +- Without tokens, the system has no foundation + +Output: +- A documented token set (see `design-standards/references/design-tokens-template.md`) +- Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.) +- Token implementation in Figma (variables and styles) +- A primer doc explaining what tokens to use when + +Common patterns: +- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: `color-blue-600` (base) + `color-text-link` (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base. + +### 2. Elements (atoms) + +The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers. + +Per element, document: +- Visual variants (primary, secondary, ghost, etc.) +- Size variants (small, medium, large) +- States (default, hover, focus, active, disabled, error, loading) +- Anatomy (the parts that make up the element) +- Spacing and proportions +- Accessibility (keyboard support, screen reader behavior, ARIA) +- Code usage (props, examples) + +Output: +- Element library in Figma +- Element components in code +- Per-element documentation + +### 3. Components (molecules + organisms) + +Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers. + +Per component: +- Composition (which elements it uses) +- Variants and configurations +- Use cases (when to reach for this vs. an alternative) +- Layout behavior (responsive, contained, full-bleed) +- Anti-patterns (when NOT to use it) + +Output: +- Component library +- Per-component documentation with usage guidance + +### 4. Patterns (templates) + +Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections. + +Per pattern: +- The structure and components used +- The user journey it supports +- Layout grid and spacing +- Responsive behavior +- Variants (e.g., "with sidebar," "fullscreen," "modal") + +Output: +- Pattern library or page templates +- Documentation showing complete examples + +### 5. Documentation and governance + +How the system gets used, contributed to, and maintained. + +Documentation includes: +- Getting started guide for new team members +- How to use vs. how to extend +- Contribution model +- Versioning policy +- Migration paths when breaking changes happen +- Decision log for major system choices + +Governance includes: +- Who owns the system (a team or rotation) +- How new components get proposed and approved +- How conflicts get resolved +- How the system evolves vs. stays stable +- Cadence of review and updates + +--- + +## Workflow + +### For a new design system + +1. Inventory the existing UI. Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope. +2. Identify the duplicates. Same component built 5 different ways across the product. These are your high-value consolidation targets. +3. Define foundations. Token set, with both base and semantic layers. Document each. +4. Audit elements. From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set. +5. Build the element library. Figma + code. Document each element. +6. Identify priority components. The 10 to 15 components that appear most often. Build those first. +7. Document patterns. Page-level templates that show the system in use. +8. Establish governance. Owner, contribution model, review cadence. +9. Roll out. Migrate existing surfaces to the system progressively. + +### For an existing design system audit + +1. Inventory what exists. What's documented, what's in Figma, what's in code, what's actually used in production. +2. Map gaps. Where the system is incomplete. Where teams build outside the system because the system can't serve their need. +3. Map fragmentation. Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams). +4. Identify decay. Components that have drifted from the documented standard. +5. Prioritize fixes. Foundation gaps first. High-use component drift second. Rarely-used component cleanup last. +6. Plan rollout. Major changes need migration paths. + +--- + +## Failure patterns + +- Building the system before the brand is set. Tokens depend on brand. Set brand first. +- Atoms-up extreme. Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively. +- One-person system. A system without governance fails as soon as the original designer leaves. Establish ownership early. +- Stale documentation. A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs. +- Versioning everything. Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes. +- Adopting "atomic design" dogmatically. Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism. +- Building in a vacuum. A system designed without input from the teams using it gets ignored. Co-design with consumers. +- No deprecation path. Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly. +- Token explosion. Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have. + +--- + +## Output format + +A design system has multiple deliverables. Typically: + +- Documentation site (Notion, dedicated site, GitHub Pages, Storybook addon, etc.) +- Figma library (or equivalent design tool) +- Code library (npm package, monorepo workspace, copy-paste components) +- Decision log (system-level decisions and the reasoning) +- Roadmap and changelog + +For a design system audit, output is a markdown report at `design-system-audit.md`: + +1. Inventory of what exists (foundations, elements, components, patterns) +2. Gap analysis +3. Fragmentation analysis +4. Drift analysis +5. Prioritized remediation plan +6. Governance recommendations + +--- + +## Reference files + +- [`references/system-architecture.md`](references/system-architecture.md) - The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs. +- [`references/system-audit-template.md`](references/system-audit-template.md) - Template for auditing an existing design system. +- [`references/governance-playbook.md`](references/governance-playbook.md) - Contribution model, ownership, and decision process for an active system. diff --git a/dist/pi/.agents/skills/design-system/references/governance-playbook.md b/dist/pi/.agents/skills/design-system/references/governance-playbook.md new file mode 100644 index 0000000..8d72e3b --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/governance-playbook.md @@ -0,0 +1,303 @@ +# Design System Governance Playbook + +A design system without governance decays. This playbook covers the operating model: who owns it, how changes happen, and how the system stays alive. + +--- + +## Ownership models + +Three common models. Pick based on team size and maturity. + +### Model 1: Dedicated team + +A standing team owns the system full-time. 2 to 5 people typically: a lead designer, a lead engineer, and supporting roles. + +Strengths: +- Highest velocity for system improvements +- Clear ownership, fast decisions +- Can take on big system-level initiatives + +Weaknesses: +- Expensive +- Risk of disconnection from product teams +- Risk of building what the team finds interesting vs. what consumers need + +When to use: Organizations with 10+ designers and 50+ engineers, where system inconsistency is a real cost. + +### Model 2: Federated / contribution model + +System is maintained by multiple teams contributing changes. A small core team (or one lead) reviews contributions and maintains the foundation. + +Strengths: +- Distributed effort +- Component owners are the people closest to the use case +- Prevents the "system team builds for itself" problem + +Weaknesses: +- Coordination overhead +- Inconsistent velocity +- Requires strong contribution norms or quality drifts + +When to use: Mid-sized teams (5 to 15 designers, 20 to 100 engineers), where multiple teams need a shared system but no single team can dedicate full-time effort. + +### Model 3: Single owner / part-time + +One person owns the system as part of their broader role. Common in startups and small teams. + +Strengths: +- No coordination cost +- Decisions happen instantly +- Cheap + +Weaknesses: +- System decays when owner is busy +- Bus factor of one +- Hard to scale + +When to use: Early-stage teams. Plan to migrate to Model 1 or 2 as the team grows. + +--- + +## Contribution model + +How new components, variants, or changes get added to the system. + +### Stages + +1. Proposal. A team that needs a new component or variant proposes it. Proposal includes: the use case, examples in the wild, why existing components don't suffice. + +2. Triage. System owner(s) decide: + - Accept: add to the system. Assign owner. + - Adapt existing: existing component should grow to cover this use case. + - Defer: valid request but not prioritized now. + - Reject: doesn't fit the system. Solve in a one-off way. + +3. Design. Component is designed in the system's style. Includes all states, variants, and accessibility requirements. + +4. Review. System owner reviews against system standards. Iterate. + +5. Build. Component is built in code (and Figma if not built there first). + +6. Document. Usage doc, API doc, examples, anti-patterns. + +7. Release. Versioned release. Changelog entry. Announcement to consumers. + +### Proposal template + +```markdown +# Component Proposal: [Name] + +## Use case +[What we're building. The user problem this UI element solves.] + +## Examples in the wild +[3 to 5 places where teams have built ad-hoc versions of this. Screenshots.] + +## Why existing components don't fit +[Specific reasons existing components are insufficient.] + +## Proposed component +[Sketch or description of the proposed component, variants, states.] + +## Owner +[Who will design, build, and maintain this component.] + +## Timeline +[When this is needed. Hard deadlines vs. nice-to-have.] +``` + +--- + +## Decision-making + +### Type 1: Reversible decisions + +Most component-level decisions. Made by the component owner with light input from the system team. + +Examples: a new variant, a tweak to a state, an additional prop on an existing component. + +Process: lightweight. Propose in the team channel, get one or two reactions, ship. + +### Type 2: One-way doors + +Decisions that affect the foundation or ripple across many components. + +Examples: changing a base token, deprecating a component, changing the naming convention. + +Process: written proposal, formal review, broader stakeholder input, documented decision in the decision log. + +### Decision log + +Every Type 2 decision gets logged: + +```markdown +# DSDR-001: [Decision title] + +Date: YYYY-MM-DD +Status: [Proposed / Approved / Rejected / Implemented] +Author: [Name] + +## Context +[What situation led to this decision.] + +## Options considered +1. [Option] - pros, cons +2. [Option] - pros, cons +3. [Option] - pros, cons + +## Decision +[What was decided.] + +## Reasoning +[Why this option won.] + +## Consequences +[What changes as a result. What new constraints exist.] + +## Revisit when +[Trigger condition that would warrant reopening this decision.] +``` + +This log becomes the institutional memory. Future system owners can understand why things are the way they are. + +--- + +## Versioning + +### Semantic versioning + +For systems shipped as code packages, semver works well: + +- Major (1.0.0 → 2.0.0): breaking changes. API changes. Visual changes that consumers must adapt to. +- Minor (1.0.0 → 1.1.0): new components or variants. Backward-compatible. +- Patch (1.0.0 → 1.0.1): bug fixes. Backward-compatible. + +### Release cadence + +Three patterns: + +- Continuous: ship as ready. Best for teams that can absorb frequent updates. +- Periodic: weekly or biweekly batched releases. Best for systems with many consumers. +- Major releases: quarterly major versions, with weekly patches between. Best for systems with breaking changes that need migration time. + +### Communication + +For each release: +- Changelog entry (what changed, why) +- Migration guide for breaking changes +- Internal announcement (Slack, email, internal newsletter) +- Demo or office hours for major changes + +--- + +## Deprecation + +Components get retired. Manage retirement explicitly. + +### Deprecation stages + +1. Warning. Component is marked deprecated. Documentation gains a deprecation notice. Build emits a console warning. + +2. Migration period. Defined window (typically 1 to 2 quarters) for consumers to migrate. Migration guide published. + +3. Removal. Component removed. Code deleted. Documentation archived (not deleted, for historical reference). + +### Deprecation notice template + +```markdown +> ⚠️ Deprecated: [Component] is deprecated as of [version]. +> Replacement: [link to replacement component] +> Removal: scheduled for [version / date] +> Migration guide: [link] +``` + +--- + +## Quality bar + +Every component or change must meet the bar before merging. + +### Functional +- [ ] Works at the documented breakpoints +- [ ] All variants and states implemented +- [ ] Keyboard navigation works +- [ ] Screen reader announces correctly +- [ ] Focus indicators visible +- [ ] Touch targets at least 44px +- [ ] Color contrast passes AA + +### Documentation +- [ ] Usage doc (when to use, when not to) +- [ ] API doc (props, types, defaults) +- [ ] Examples (basic, advanced, edge cases) +- [ ] Anti-patterns (what to avoid) + +### Consistency +- [ ] Uses tokens (no hardcoded values) +- [ ] Follows naming conventions +- [ ] Visual style matches the system +- [ ] Behavior matches similar components + +### Test +- [ ] Unit tests for component logic +- [ ] Visual regression test +- [ ] Accessibility test + +--- + +## Metrics + +Track the health of the system. + +### Adoption + +- Percentage of product UI built from system components vs. one-offs +- Per-team adoption rate +- Component usage frequency + +### Velocity + +- Time from proposal to release +- Number of accepted contributions per month +- Open proposals in queue + +### Quality + +- Open bugs against system components +- Accessibility issues count +- Drift incidents (components used in unsupported ways) + +### Consumer satisfaction + +- Internal survey: how useful is the system? +- What's missing? What blocks adoption? + +Run satisfaction survey at least annually. Use results to guide system priorities. + +--- + +## Sustaining the system + +A design system is a living thing. Without maintenance, it dies. + +### Weekly +- Triage incoming proposals +- Review consumer questions and feedback +- Address bugs + +### Monthly +- Release notes for any changes +- Office hours for consumer teams +- Component audit (one or two components reviewed in depth) + +### Quarterly +- Roadmap review +- Foundation review (token health, naming consistency) +- Adoption metrics review + +### Annually +- Strategic review (is the system serving its purpose?) +- Consumer satisfaction survey +- Major version planning + +The system is never finished. It evolves with the product, the team, and the brand. diff --git a/dist/pi/.agents/skills/design-system/references/system-architecture.md b/dist/pi/.agents/skills/design-system/references/system-architecture.md new file mode 100644 index 0000000..113081c --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/system-architecture.md @@ -0,0 +1,275 @@ +# System Architecture + +How the four layers of a design system relate, and how to decide where new things belong. + +--- + +## The four layers, top to bottom + +``` +┌──────────────────────────────────────────────────────────────┐ +│ TEMPLATES (full screens, complete flows) │ +│ Optional layer. Use when the same screen pattern recurs. │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PATTERNS (composed components solving a UI problem) │ +│ Examples: form layouts, modal dialogs, navigation, tables │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PRIMITIVES (smallest reusable elements) │ +│ Examples: button, input, checkbox, badge, icon, link │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ TOKENS (atomic named values) │ +│ Examples: color-text-primary, space-md, radius-card │ +└──────────────────────────────────────────────────────────────┘ +``` + +Higher layers consume lower layers. A primitive uses tokens. A pattern composes primitives (and tokens). A template assembles patterns. + +A token never references a primitive. A primitive never references a pattern. The dependency direction is one-way. + +--- + +## When to add at each layer + +### Add a token when: +- A value appears in 3+ places +- The value has a clear semantic purpose +- Changing the value should propagate everywhere it appears + +Example: "Card border radius" - if 12 components use 12px corner radius, that's a token. + +Counter-example: A one-off radius for a single decorative element. Hard-code it. + +### Add a primitive when: +- The same combination of HTML/JSX/View elements recurs in 3+ places +- The element has an internal state machine (open/closed, default/hover/disabled) +- Centralized accessibility logic helps consumers + +Example: Button. Recurs everywhere. Has states. Accessibility (focus, keyboard, ARIA) is non-trivial. + +Counter-example: A specific marketing hero block that only appears on the homepage. Not a primitive. Build it inline. + +### Add a pattern when: +- Multiple teams keep building the same composition +- The composition involves non-obvious decisions (z-index, focus management, scroll behavior, animation) +- A central pattern reduces accessibility risk + +Example: Modal dialog. Hard to get right (focus trap, escape, scroll lock). Pattern centralizes the hard parts. + +Counter-example: A specific dashboard layout used only on the analytics page. Not a pattern. Build it inline as a screen. + +### Add a template when: +- A full screen recurs across products or sections +- New product features want a starting point that already follows system rules + +Example: Settings page layout (left nav, content area, save bar). If the team builds 5 settings sections, the template saves time. + +Counter-example: A unique landing page. Not a template. + +--- + +## Decision tree: where does this belong? + +``` +Is it a value? ────── Yes ────── Token + │ + └── No + +Is it a single element? ── Yes ── Primitive + │ + └── No + +Is it composed of primitives? ─ Yes ─ Pattern + │ + └── No + +Is it a full screen? ──────── Yes ── Template +``` + +--- + +## Token tiering + +Most systems benefit from at least two tiers. Three is the maximum without diminishing returns. + +### Tier 1: Primitives + +Raw values, no semantic meaning attached. + +``` +color-blue-50 = #EFF6FF +color-blue-100 = #DBEAFE +color-blue-500 = #3B82F6 +color-blue-900 = #1E3A8A + +space-1 = 4px +space-2 = 8px +space-4 = 16px +space-8 = 32px + +radius-sm = 4px +radius-md = 8px +radius-lg = 12px +``` + +### Tier 2: Semantic + +Purpose-named, mapped to primitives. + +``` +color-text-primary = color-gray-900 +color-text-secondary = color-gray-600 +color-text-link = color-blue-700 +color-bg-surface = color-white +color-bg-elevated = color-white +color-border-default = color-gray-200 + +space-stack-tight = space-2 +space-stack-default = space-4 +space-stack-loose = space-6 +``` + +### Tier 3 (optional): Component-specific + +Component-tied, mapped to semantic tokens. + +``` +button-padding-x = space-stack-default +button-padding-y = space-stack-tight +button-radius = radius-md +button-bg-primary = color-bg-action-primary +``` + +Rule of thumb: Stop at Tier 2 unless the system is large enough to justify Tier 3 maintenance. Tier 3 adds clarity but multiplies token count. + +--- + +## Naming conventions + +Pick one and stay. The most common patterns: + +### Pattern A: Hierarchical with hyphens +``` +color-text-primary +color-text-secondary +color-bg-surface +space-stack-md +``` + +### Pattern B: Object/dot notation (often in JSON or JS) +``` +color.text.primary +color.bg.surface +space.stack.md +``` + +### Pattern C: Flat with prefix +``` +text-color-primary +bg-color-surface +stack-space-md +``` + +Hierarchical-with-hyphens (Pattern A) is the most common for CSS variable contexts. Pick once, document, never deviate. + +--- + +## Naming for the semantic layer + +Names should describe purpose, not appearance. "Color is what it is, name is what it does." + +Good: +- `color-text-primary` (what role does it play?) +- `color-bg-action-destructive` (what action is this for?) +- `space-stack-section` (where does it apply?) + +Bad: +- `color-blue-medium` (semantic name should not encode the value; that's the primitive layer's job) +- `color-pretty-blue` (subjective, not purpose) +- `color-button-text` (OK at component layer; too specific for semantic layer) + +--- + +## Versioning + +Use semantic versioning: `major.minor.patch`. + +- Patch: Bug fixes, no API changes. Bump for any defect fix. +- Minor: Additive changes. New tokens, new components, non-breaking API additions. +- Major: Breaking changes. Removed tokens, renamed APIs, behavioral changes consumers must adapt to. + +For breaking changes, provide: + +1. Deprecation warning in the previous minor version +2. Migration guide +3. Codemod or scripted migration path where possible +4. A timeline for sunset (typically 1 to 2 quarters) + +--- + +## Anti-patterns + +### Color sprawl +- 200 named colors instead of a tight palette of 30 to 50. +- Symptom: every designer adds the color they need. +- Fix: enforce primitive layer review before new colors land. + +### Spacing chaos +- 17 different spacing values, half of them within 2px of each other. +- Symptom: each design uses unconstrained spacing. +- Fix: a defined scale. New spacing values require a real reason. + +### Naming inconsistency +- `colorPrimary`, `color-primary`, `primary-color`, `primaryColor` all in the same system. +- Symptom: tokens added by different people without convention. +- Fix: pick one convention, document, automate validation. + +### Tokens without consumers +- 200 tokens defined, 50 actually used. +- Symptom: aspirational tokens added "for the future." +- Fix: only add tokens with current or near-future consumers. + +### Components without docs +- 30 components in the library, 5 have docs. +- Symptom: docs treated as separate work, deprioritized. +- Fix: docs blocking the merge of new components. + +### Patterns over-built +- A "DataTable" pattern with 47 props supporting every imaginable variation. +- Symptom: Trying to anticipate every use. +- Fix: ship narrow first. Expand based on real demand. Hard to remove options once shipped; easy to add. + +--- + +## Dependency directions + +A healthy system has these dependency rules: + +- Tokens depend on nothing. +- Primitives depend on tokens. +- Patterns depend on primitives and tokens. +- Templates depend on patterns, primitives, and tokens. +- Application code depends on any layer. + +Violations to flag: + +- A token referencing another token at a different tier (sometimes OK, often a smell). +- A primitive referencing a pattern. Wrong direction. +- A pattern not using primitives, building from raw HTML. Bypasses the system. +- Application code defining its own colors instead of using tokens. Bypasses the system. + +--- + +## How to introduce a system to an existing codebase + +If the codebase has no system today: + +1. Audit. Inventory existing UI. Find duplicates and inconsistencies. +2. Tokens first. Establish the token foundation. Migrate hard-coded values gradually. +3. Primitives second. Replace ad-hoc components with system primitives. Highest-impact ones first (button, input, modal). +4. Patterns third. Once primitives are established, codify patterns. +5. Migrate over multiple quarters. Rip-and-replace fails. Coexistence with gradual migration succeeds. + +Plan for the system to take 2 to 4 quarters to fully replace ad-hoc UI in a medium-sized product. Plan for it to never be "done" - it evolves with the product. diff --git a/dist/pi/.agents/skills/design-system/references/system-audit-template.md b/dist/pi/.agents/skills/design-system/references/system-audit-template.md new file mode 100644 index 0000000..625f9f5 --- /dev/null +++ b/dist/pi/.agents/skills/design-system/references/system-audit-template.md @@ -0,0 +1,258 @@ +# Design System Audit Template + +A template for auditing an existing design system. Use this to take stock of what exists, what is missing, what is duplicated, and what is silently broken. + +The output is an honest report, not a grade. The goal is a backlog the team can act on. + +--- + +## When to use this template + +- Before a major redesign or rebrand (knowing the starting state shapes the plan). +- When the system feels heavy or inconsistent and no one can articulate why. +- When a new owner takes over and needs ground truth. +- Quarterly, as a regular health check. + +--- + +## Audit scope + +Decide upfront what is in and out of scope. A full audit covers all four layers (tokens, primitives, patterns, templates) plus governance and adoption. A focused audit covers one or two. + +\| Layer / area \| In scope \| Out of scope \| +\|---\|---\|---\| +\| Tokens \| \| \| +\| Primitives \| \| \| +\| Patterns \| \| \| +\| Templates \| \| \| +\| Documentation \| \| \| +\| Governance \| \| \| +\| Adoption \| \| \| + +--- + +## Layer 1: Tokens + +### Inventory + +List every token category in the system. For each, count, source of truth, and platforms supported. + +\| Category \| Count \| Source of truth \| Platforms supported \| +\|---\|---\|---\|---\| +\| Color \| \| \| \| +\| Typography (font, size, weight, line-height) \| \| \| \| +\| Spacing \| \| \| \| +\| Radius \| \| \| \| +\| Shadow \| \| \| \| +\| Motion (duration, easing) \| \| \| \| +\| Z-index \| \| \| \| +\| Breakpoints \| \| \| \| +\| Other \| \| \| \| + +### Findings + +- [ ] Are tokens named by role (`color-text-primary`) or by value (`gray-900`)? Role-based scales better. +- [ ] Is there a single source of truth (one file, one tool) or multiple sources that drift? +- [ ] Are tokens versioned? How are breaking token changes communicated? +- [ ] Are there duplicate tokens (`color-blue-primary` and `color-action`)? List them. +- [ ] Are there orphan tokens (defined but unused)? List them. +- [ ] Are dark mode / theme variants modeled at the token layer or elsewhere? + +### Token risks + +- Hardcoded values in code: grep the codebase for raw hex, raw px values, raw font sizes. Note where tokens were skipped. +- Token sprawl: more than 20 named colors, more than 8 spacing values, or more than 6 font sizes is usually a smell. +- Naming inconsistency: `color-text` vs `text-color` vs `textColor` across categories. + +--- + +## Layer 2: Primitives + +### Inventory + +List every primitive component the system ships. For each, status and consumer count. + +\| Primitive \| Status (Production / Beta / Deprecated) \| Consumers (rough count) \| Notes \| +\|---\|---\|---\|---\| +\| Button \| \| \| \| +\| Input \| \| \| \| +\| Checkbox \| \| \| \| +\| Radio \| \| \| \| +\| Select \| \| \| \| +\| Textarea \| \| \| \| +\| Badge \| \| \| \| +\| Avatar \| \| \| \| +\| Icon \| \| \| \| +\| Link \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Are primitives accessible (keyboard, screen reader, focus management)? List failures. +- [ ] Are all primitives token-driven, or do some hardcode values? +- [ ] Are there duplicate primitives that do almost the same thing (`Button` and `IconButton` and `LinkButton`)? Could they consolidate? +- [ ] Are primitives documented (props, states, variants, accessibility)? +- [ ] Are there one-off primitives in product code that should be promoted to the system? + +--- + +## Layer 3: Patterns + +Patterns are composed components solving a specific UI problem. + +### Inventory + +\| Pattern \| Status \| Used by (rough page or feature count) \| Notes \| +\|---\|---\|---\|---\| +\| Form layout \| \| \| \| +\| Modal dialog \| \| \| \| +\| Toast / notification \| \| \| \| +\| Navigation (top, side) \| \| \| \| +\| Empty state \| \| \| \| +\| Pagination \| \| \| \| +\| Data table \| \| \| \| +\| Card \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Are patterns built from primitives, or do they reach around the primitives layer? +- [ ] Do multiple patterns solve the same problem with different APIs? +- [ ] Are patterns flexible enough for real product needs, or are teams forking them? + +--- + +## Layer 4: Templates + +Templates are full screens or flows. Optional layer. + +### Inventory + +\| Template \| Status \| Used by \| Notes \| +\|---\|---\|---\|---\| +\| Marketing landing \| \| \| \| +\| App shell \| \| \| \| +\| Settings page \| \| \| \| +\| Onboarding flow \| \| \| \| +\| Empty product state \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Do templates exist at all? Many systems skip this layer. +- [ ] Are templates a starting scaffold or a rigid spec? +- [ ] Are template layouts responsive, or do teams reimplement responsive behavior each time? + +--- + +## Documentation + +### Inventory + +- Documentation site: [URL or "none"] +- Last meaningful update: [Date] +- Component coverage: [What % of shipped components are documented?] +- Code examples for every component: [Yes / partial / no] +- Accessibility notes for every interactive component: [Yes / partial / no] +- Migration / changelog: [Yes / no] + +### Findings + +- [ ] Is the documentation in sync with the shipped code, or has it drifted? +- [ ] Can a new engineer onboard from the docs alone, or do they need tribal knowledge? +- [ ] Is there a "do / do not" pattern with examples for each component? +- [ ] Are deprecated components clearly marked, with a migration path? + +--- + +## Governance + +- Ownership model: [Dedicated team / federated / single owner / unowned] +- Contribution process: [Documented / informal / nonexistent] +- Review cadence: [How often do owners look at incoming requests, bugs, drift?] +- Decision log: [Where are major design system decisions recorded? Or are they not?] +- Communication channel: [Slack channel / mailing list / standing meeting / none] + +### Findings + +- [ ] Who decides when a new component enters the system? +- [ ] Who decides when a component is deprecated? +- [ ] Who handles requests from product teams? What is the SLA? +- [ ] What happens when a product team needs something the system does not provide? + +--- + +## Adoption + +### Measurement + +\| Measure \| Today \| Target \| +\|---\|---\|---\| +\| % of UI built with system components \| \| \| +\| % of new features using system \| \| \| +\| Number of one-off components in product code \| \| \| +\| Number of token overrides in product code \| \| \| +\| Number of open issues against the system \| \| \| + +### Findings + +- [ ] Where is adoption strongest? Why? +- [ ] Where is adoption weakest? Why? (Often: missing components, too rigid, undocumented, or onboarding gap.) +- [ ] Are there teams actively forking or working around the system? + +--- + +## Risk register + +List the top 5 risks the audit surfaced. For each: severity (high / medium / low), affected area, and a one-line recommendation. + +\| # \| Risk \| Severity \| Affected area \| Recommendation \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| +\| 3 \| \| \| \| \| +\| 4 \| \| \| \| \| +\| 5 \| \| \| \| \| + +--- + +## Backlog + +Translate findings into a prioritized backlog. Keep items concrete and assignable. + +### Critical (block adoption or accessibility) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### High (consistent friction or duplication) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Medium (improvement, not blocking) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Low (polish) + +- [ ] [Item, owner, target date] + +--- + +## Audit summary + +Three sentences. What is the overall state, what is the single most important thing to fix, and what should the team start now. + +> [State summary] +> [Most important fix] +> [Start now] + +--- + +## Sign-off + +Audit conducted by: [Name(s), date] +Reviewed with: [Stakeholders] +Next audit scheduled: [Date] diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md b/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md new file mode 100644 index 0000000..be007e8 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/SKILL.md @@ -0,0 +1,265 @@ +--- +name: discovery-research-synthesis +description: "Turning research artifacts into actionable PM insight. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the decisions they are meant to inform. The discipline of moving from raw discovery data to clear product direction without losing signal in the synthesis or fabricating insight that was not actually there. Triggers on research synthesis, customer interview synthesis, user research analysis, discovery readout, research insights, sales call analysis, support ticket analysis, qualitative data analysis. Also triggers when a team has done research but cannot turn it into decisions, when synthesis is producing pretty decks but no roadmap movement, or when an upcoming PM decision needs to be grounded in research already conducted." +category: research +catalog_summary: "Synthesizing customer interviews, research notes, and support tickets into actionable PM decisions. Distinguishes data-dump (no synthesis) from insight-theater (overpolished narrative) from actionable synthesis (decision-grade clarity)" +display_order: 4 +--- + +# Discovery Research Synthesis + +A senior PM's playbook for turning research artifacts into decisions. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the product direction they are meant to inform. + +Most discovery research never produces decisions. The team conducts interviews; the transcripts pile up; a researcher hands product the raw artifacts (data-dump) or builds a polished readout deck (insight-theater); the deck gets a 30-minute review meeting and is never referenced again. Two months later the team is making the same product decisions that the research was supposed to inform, with the same gut-feel inputs the research was supposed to displace. + +The discipline is in the synthesis. Synthesis is where research earns its keep: where transcripts become tagged observations, observations cluster into patterns, patterns get named, named patterns surface product implications, and implications drive specific decisions. Without that sequence, research is performance art. + +This skill covers one-off discovery research projects: a 12-week customer development sprint, a sales-call review for an onboarding redesign, a support-ticket audit informing a roadmap quarter. Different from `user-feedback-aggregation`, which covers ongoing feedback streams; different from `jtbd-framing`, which is a specific framing technique often applied within synthesis but narrower in scope. + +The voice is the senior PM or staff product researcher who has run synthesis well and seen plenty of teams fail at it. Honest about where polish becomes performance and where pattern-naming slides into pattern-fabrication. + +When to use this skill: synthesizing a recent batch of customer interviews, auditing why prior research has not produced product decisions, designing the synthesis output for a multi-week discovery sprint, or establishing the synthesis discipline a team currently lacks. + +--- + +## What this skill is for + +This skill spans research-to-decision synthesis. The PM-skill distinction: + +- `discovery-research-synthesis` (this skill) is one-off research synthesis: turning a discrete batch of artifacts into a discrete set of decisions. +- `user-feedback-aggregation` is ongoing feedback streams: continuous synthesis across always-on channels (support, NPS, in-app, sales). +- `jtbd-framing` is a framing technique often applied during synthesis; this skill is broader. +- `pm-spec-writing` is downstream: specs use synthesized insights as input. +- `roadmap-planning` is downstream: roadmap uses synthesized priorities as input. +- `experiment-design` is the quantitative-validation discipline that often follows qualitative synthesis. + +The audience: senior PMs, product directors, in-house product teams, agencies running discovery work for clients, researchers handing off to product teams. + +What is not in scope: conducting the research itself (interview design, recruiting, moderation), the broader discovery strategy that decides which research to commission, or the long-running feedback channels that user-feedback-aggregation covers. + +--- + +## Data-dump vs insight-theater vs actionable-synthesis + +The keystone framing. Two failure modes plus the discipline. + +Data-dump. Research artifacts handed to the product team raw. "Here are 47 transcripts and a spreadsheet of tags; figure it out." No synthesis, no signal-finding, no implications drawn. The product team either does the synthesis itself (often badly, often months later) or skips it (the most common outcome). Output: a research investment that produced artifacts but not insight. + +Insight-theater. Overpolished synthesis dressed as insight. Pretty quote walls, designed personas, branded readout decks, no decision-driving conclusions. The research deck that gets a 30-minute review and never gets referenced. Synthesis that performed for the executive audience but did not inform the product audience. Cost: real research budget converted into a slide deck; the organization "did the research" without doing the research. + +Actionable-synthesis. Synthesis that drives decisions. Each pattern has a "so what" attached; each finding leads to a product implication; the document gets referenced in roadmap discussions, spec drafts, prioritization debates. The synthesis is short, opinionated, and load-bearing. Six months later, team members can quote the patterns that shaped what shipped and what got cut. + +The litmus test. Three months after a synthesis ships, can team members name the decisions the synthesis informed? If yes, the synthesis was actionable. If team members remember the deck but cannot name the decisions, it was insight-theater. If nobody remembers anything because the synthesis never happened, it was data-dump. + +--- + +## Discovery research types + +Five common research types, each with different artifacts and synthesis needs. + +Customer interviews. 30-90 minute structured or semi-structured conversations. Transcripts plus moderator notes plus recordings. Highest-quality qualitative data; most expensive to collect; most rewarding to synthesize when done well. Typical batch: 8-15 interviews per discovery cycle. + +Support ticket reviews. Auditing recent support tickets for patterns. Lower per-artifact richness than interviews; higher volume; surfaces the friction users actually hit (not just what they say in interviews). Typical batch: 100-500 tickets per audit. + +Sales call analysis. Recording or transcript review of recent sales calls. Surfaces objections, pricing-conversation patterns, competitive mentions, and the gap between marketing positioning and what sales actually leads with. Typical batch: 15-30 calls per audit. + +Survey data. Quantitative responses with optional qualitative comments. Best for validating qualitative patterns at scale; weak as primary discovery (surveys reveal what users say, not what they do). Typical batch: 100-2,000 responses. + +In-app feedback. Users submitting feedback through in-product channels. Volume is high; quality varies; signal lives in patterns across many low-effort submissions. Typical batch: ongoing; synthesized in periodic audits. + +Different research types compose. A discovery cycle often pairs interviews (depth) with support ticket review (volume) with survey data (validation at scale). The synthesis combines them. + +Detail in [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md). + +--- + +## The synthesis sequence + +Six stages from raw artifacts to decisions. Skipping stages is where synthesis fails. + +1. Transcribe and prepare. Convert artifacts into a synthesizable format. Interview recordings to transcripts; sales calls to summaries; support tickets to a tagged dataset. The prep work is unglamorous; teams that skip it never reach the later stages. + +2. Tag at the artifact level. Read each transcript or ticket and tag it with the topics, problems, and quotes that surface. First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. Tags are messy; that is fine. + +3. Cluster across artifacts. Group tags into themes. Multiple users mentioned the same friction; multiple tickets reference the same workflow; multiple interviews returned to the same struggling moment. The clusters surface the patterns. + +4. Name patterns. Each cluster becomes a named pattern. The naming is the work: a pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references. "Onboarding configuration friction" is a pattern name; "users had trouble" is not. + +5. Infer product implications. For each pattern, what does this imply for the product? Implications are the bridge from observation to decision. A pattern without an implication is a finding; a pattern with an implication is actionable input. + +6. Name the so-what. For each implication, the specific decision it informs. "Should we prioritize the onboarding redesign in Q2?" The so-what is what makes the synthesis decision-grade. + +The sequence is non-negotiable. Teams that skip tagging and jump to pattern naming hallucinate patterns; teams that skip implications produce findings without product direction; teams that skip so-what produce documentation, not synthesis. + +Detail in [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md). + +--- + +## Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. + +Tag at the artifact level first; do not pre-design the taxonomy. Tags emerge from the artifacts. Teams that arrive with a pre-built tag taxonomy ("we will tag for usability, performance, pricing, support") force artifacts into categories that may not fit the data, and miss patterns the taxonomy did not anticipate. + +Allow tag proliferation; collapse later. Early tagging may produce 80-150 tags across a batch. That is correct. The clustering stage collapses them. Premature consolidation ("we had 4 onboarding tags; let me merge them") loses distinctions that turn out to matter. + +Cluster on patterns, not on tag overlap. Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation: are these the same struggling moment, or do they share a tag because the tag was loose? + +Name the cluster after clustering, not before. The cluster name comes from the data, not from a hypothesis. Teams that arrive with named clusters and slot data into them produce confirmation; teams that name clusters from the data produce discovery. + +Tag dissent and contradictions explicitly. Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. Tag the dissent so the synthesis can address it. + +Detail in [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md). + +--- + +## Pattern naming + +The work that distinguishes synthesis from documentation. + +A pattern name is not a category label. "Onboarding" is a category. "Users abandon configuration before reaching the success state because the third configuration step requires data they do not have on hand" is a pattern. The pattern names the specific behavior the data reveals. + +The name should make the implication legible. A reader who sees only the pattern name should be able to guess the product implication. If the name is too abstract, the reader cannot reach the implication; if the name is too concrete, the synthesis becomes a list of micro-observations. + +Avoid category bloat. Synthesis with 30 named patterns is usually under-clustered: many of those patterns are variations on a smaller number of underlying patterns. Synthesis with 4 named patterns is often the right number; 6-8 is common; more than 12 is usually category bloat. + +Avoid naming the obvious. "Users want fast performance" is not a pattern; it is a truism. A pattern is a specific observation that the product team did not already know. If the pattern name reads as something everyone could have said before the research, the pattern is not a pattern. + +Name with conviction. Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly; they invite challenge and produce decisions. + +Detail in [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md). + +--- + +## From pattern to product implication + +The bridge from observation to decision. + +Pattern-to-implication is the writer's analytical work, not what the user said. Users do not state product implications; they describe their experience. The PM doing synthesis interprets the pattern and proposes the implication. The interpretation is where synthesis adds value beyond transcription. + +Each pattern can have multiple implications. A pattern about onboarding friction might imply a redesign of the configuration flow, or default-data pre-population, or staged onboarding. The synthesis surfaces the options; the prioritization decision picks one. + +Implications should be falsifiable. A vague implication ("we should improve onboarding") is not actionable. A specific implication ("staged onboarding that defers the third configuration step until after the user reaches the first success state") is. Specific implications can be debated, scoped, prioritized. + +Implications should acknowledge cost. Patterns suggest solutions; solutions cost product capacity. Synthesis that implies 30 product changes without acknowledging that delivering them all is impossible is not synthesis; it is a wishlist. + +Some patterns imply not-acting. Sometimes the pattern reveals friction the team should not address: it affects too few users, it represents segment misfit, addressing it would compromise other priorities. Naming the not-act implication is honest synthesis. + +Detail in [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md). + +--- + +## Writing for decisions, not deck performance + +Synthesis output should be optimized for decision use, not for presentation. + +Document, not deck. Deck format is poor for synthesis: slides cannot carry argument density; readers cannot reference slides later; decks decay into icons and bullet points. A short document (4-12 pages) carries more usable synthesis than a 60-slide deck. + +Lead with patterns and implications; relegate evidence to appendix. A reader scanning for decision input wants the patterns and implications first. Evidence (quotes, ticket excerpts, data tables) supports the patterns but does not lead. Decks that lead with quote walls have inverted the reader's needs. + +One section per pattern. Each pattern gets a short section: pattern name, evidence summary (2-3 sentences with link to full evidence in appendix), implication, so-what decision input. + +Be opinionated. Synthesis that hedges every pattern reads as a researcher avoiding accountability. Synthesis that commits positions invites challenge and produces decisions. The PM doing synthesis is making a recommendation; readers can disagree, but disagreement is the point. + +Include a decision-input section. What does this synthesis recommend the team do? Where should priorities shift? Which roadmap items does this validate, which does it challenge? The decision-input section is the synthesis's reason for existing. + +Detail in [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md). + +--- + +## The synthesis review and validation loop + +How the synthesis gets pressure-tested before it drives decisions. + +Internal review with the research participants where possible. Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? Misrecognition signals the synthesis fabricated patterns or projected interpretations the data did not support. + +Adjacent-team review. Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? Adjacent teams catch synthesis errors that the research team missed. + +Quantitative validation where possible. Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. The pattern says X; does the data confirm X happens at the frequency and severity the pattern implies? See `experiment-design` and `product-analytics-setup` for the quantitative methodology. + +The "challenge the synthesis" session. A specific session where adjacent teams try to find the patterns the synthesis missed, the implications the synthesis overstated, the decisions the synthesis is railroading. Productive disagreement strengthens the synthesis. + +Iterate before publishing. Synthesis goes through revision based on the review loop. Synthesis that ships in the first draft state usually carries unacknowledged blind spots. + +Detail in [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md). + +--- + +## When to halt and gather more data + +Synthesis sometimes reveals that the research did not collect enough. + +Pattern thinness. A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. Either name the pattern as tentative pending more data, or pause synthesis and gather more research. + +Segment under-representation. The research overrepresents one user segment and underrepresents another that matters for the decision. Patterns from the represented segment may not apply to the underrepresented one. + +Contradictory clusters. Two clusters point in opposite directions and the data does not resolve the contradiction. Often signals a sub-segment difference that the research did not investigate enough. + +Decision time pressure. Synthesis revealing data gaps but the decision has to ship before more research can happen. Honest path: name the data gap explicitly in the synthesis, make the recommendation with the gap acknowledged, plan the follow-up research that would validate or revise. + +The "we have enough" trap. Teams that have invested in research often want to declare the data sufficient even when the synthesis reveals gaps. The discipline is naming gaps even when uncomfortable. + +Detail in [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md). + +- "We did the research but never made decisions from it." Data-dump or insight-theater; synthesis sequence skipped or stopped at findings. +- "Our synthesis deck got a polite review and was never referenced again." Insight-theater; output was performative rather than load-bearing. +- "We have 30 named patterns and no clear priorities." Category bloat; under-clustering; cure: re-cluster to 4-8 underlying patterns. +- "Every pattern reads as something we already knew." The synthesis named truisms, not patterns. Re-examine the data for what was actually surprising. +- "The patterns contradict each other and we cannot reconcile them." Often segment misfit; consider whether the contradictions reveal sub-segments with different needs. +- "Research participants did not recognize themselves in our synthesis." Synthesis fabricated patterns or projected interpretations not in the data. Restart with closer evidence-tracking. +- "The synthesis is detailed but the team cannot tell what to do." Implications missing or vague; cure: each pattern gets a specific falsifiable implication. +- "We hedged every pattern and the synthesis reads as wishy-washy." Hedge stacking; the synthesis avoided commitment. Rewrite with conviction. +- "Our quote walls were impressive but the deck was 60 slides." Insight-theater; cure: 8-page document with quotes in appendix. +- "The synthesis recommended 20 product changes; we shipped one." Wishlist synthesis; did not acknowledge cost; cure: prioritize within the synthesis. +- "Adjacent teams disagreed with our patterns and we did not engage." Review loop skipped; cure: make adjacent-team review non-negotiable before shipping. + +--- + +## The framework: 12 considerations for discovery synthesis + +When designing or auditing a synthesis output, walk these 12 considerations. + +1. Actionable-synthesis, not data-dump or insight-theater. Synthesis that drives decisions. +2. Research types matched to questions. Interviews, support, sales calls, surveys, in-app combined deliberately. +3. The synthesis sequence: transcribe, tag, cluster, name, imply, so-what. No stage skipped. +4. Tags emerge from artifacts; taxonomy not pre-designed. +5. Tag proliferation allowed; clustering collapses. +6. Patterns named with conviction; not categories or truisms. +7. Each pattern produces a specific falsifiable product implication. +8. Each implication has a so-what tied to a real decision. +9. Output is a document, not a deck. Patterns lead; evidence in appendix. +10. Synthesis is opinionated. Hedges flagged; conviction shown. +11. Review loop before publish. Participants, adjacent teams, quantitative validation where available. +12. Data gaps named, not buried. Where research did not support a position, the synthesis says so. + +The output of the framework is a synthesis the team can act on: short, opinionated, evidence-grounded, decision-driving, accountable to challenge. + +--- + +## Reference files + +- [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md) - Five research types with synthesis implications. Composition patterns across types within a discovery cycle. +- [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md) - The six-stage sequence with worked example. Stage outputs, common skip-failures, time investment per stage. +- [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md) - Tag-at-artifact-level discipline, allow tag proliferation, cluster on patterns not overlap, name after clustering, tag dissent. +- [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md) - Pattern names that work and fail. Avoiding category bloat, naming-with-conviction, the implication-legibility test. +- [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md) - The bridge from pattern to implication. Falsifiability, multi-implication patterns, cost acknowledgment, the not-act implication. +- [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md) - Document over deck, patterns lead, evidence appendix, opinionated voice, decision-input section. +- [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md) - Participant review, adjacent-team review, quantitative validation, the challenge-the-synthesis session, iteration before publish. +- [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md) - Pattern thinness, segment under-representation, contradictory clusters, decision time pressure, the we-have-enough trap. +- [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: synthesis is where research earns its keep + +Discovery research is one of the most expensive activities a product team commissions. The expense is mostly hidden: customer time, researcher time, the opportunity cost of the discovery cycle itself, the management overhead of recruiting and scheduling. Most of that expense gets spent before synthesis even begins. + +The teams that earn returns on the research investment are the teams that take synthesis seriously: the sequence is run end-to-end, the patterns are named with conviction, the implications are falsifiable, the so-what ties to specific decisions, the output is a load-bearing document the team references for months. The teams that do not earn returns produce data-dumps or insight-theater; their research becomes documentation of work done rather than the input to work to come. + +When in doubt about whether a synthesis is ready, ask: are the patterns named with conviction, do they reach product implications, do the implications tie to specific decisions, has the synthesis been reviewed by participants and adjacent teams, are the data gaps named honestly? If yes to all of those, the synthesis is real. If no to any, the gap is where the research investment will fail to convert into decisions. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md new file mode 100644 index 0000000..a7b35c6 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md @@ -0,0 +1,193 @@ +# Common discovery synthesis failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most synthesis failures share a single root, which is treating synthesis as documentation work rather than as decision work. + +--- + +## Failure 1: We did the research but never made decisions from it + +Symptom. Discovery cycle completed; transcripts and notes filed; the team's roadmap discussions in the following months never reference the research. + +Diagnosis. Data-dump or insight-theater pattern. Synthesis sequence either skipped entirely (data-dump) or stopped at findings without reaching decisions (insight-theater). + +Cure. Run the synthesis sequence end-to-end on the existing artifacts. Even months after the original research, retroactive synthesis can produce decisions the original research was meant to inform. + +Prevention. Before commissioning the next research cycle, name the decisions the research is intended to inform. Build the synthesis sequence into the discovery plan, not as an afterthought. + +--- + +## Failure 2: Our synthesis deck got a polite review and was never referenced again + +Symptom. A polished readout deck. A 30-minute presentation. Positive feedback in the meeting. Six months later nobody references the synthesis in product decisions. + +Diagnosis. Insight-theater. Output was performative rather than load-bearing. Optimized for the presentation moment, not for reference use. + +Cure. Convert the deck content into a document with patterns leading, evidence in appendix, decision-input section. Recirculate as a reference document. + +Prevention. Future synthesis ships as documents, not decks. The presentation is a deck if needed; the synthesis is the document. + +--- + +## Failure 3: We have 30 named patterns and no clear priorities + +Symptom. The synthesis lists many patterns. The team agrees they are interesting but cannot prioritize. The synthesis fails to drive a roadmap shift. + +Diagnosis. Category bloat. Under-clustering produced inflation. Many of the 30 patterns are variations on a smaller number of underlying patterns. + +Cure. Re-cluster. Take the pattern list back to the clustering stage and look for the 4-8 underlying patterns the data actually supports. Synthesize from the consolidated list. + +Prevention. Cap pattern count at 4-8 for typical synthesis. When more than 8 patterns emerge, that is a signal to recluster, not to ship with bloat. + +--- + +## Failure 4: Every pattern reads as something we already knew + +Symptom. The synthesis names patterns that read as truisms. Team members who attended the readout could have produced the patterns without the research. + +Diagnosis. Pattern names captured truisms rather than the specific observations the research surfaced. The analytical work of pattern naming was skipped. + +Cure. Re-examine the data for what was actually surprising. Often the strongest patterns surface in the contradictions, the unexpected sub-segments, the workarounds users built. Pattern names should commit positions the team would not have committed before the research. + +Prevention. During pattern naming, apply the "what the team did not know" test. Patterns that read as common-knowledge are probably under-named. + +--- + +## Failure 5: The patterns contradict each other and we cannot reconcile them + +Symptom. Two patterns point in opposite directions. The synthesis is silent on the contradiction or hand-waves it. + +Diagnosis. Often segment misfit: different segments have different needs, and the synthesis did not surface the segment distinction. Sometimes context misfit: different use contexts produce different patterns. + +Cure. Re-examine the data for the segment or context dimension that explains the contradiction. The contradiction often becomes the most valuable finding once explained. + +Prevention. Tag dissent and contradictions explicitly during the tagging stage. Surface them through clustering. Address them in synthesis rather than burying them. + +--- + +## Failure 6: Research participants did not recognize themselves in our synthesis + +Symptom. When shown the synthesis, participants say "I did not say that" or "this does not match my experience." + +Diagnosis. Synthesis fabricated patterns or projected interpretations not in the data. The pattern naming reached for what the team wanted to find rather than what the participants actually said. + +Cure. Restart with closer evidence-tracking. Each pattern should be traceable to specific moments in specific artifacts. Patterns that cannot be traced are projections, not observations. + +Prevention. Build participant review into the synthesis process. Synthesis that participants do not recognize fails the validation; revise before publishing. + +--- + +## Failure 7: The synthesis is detailed but the team cannot tell what to do + +Symptom. Patterns are clear and well-supported. The team agrees on the patterns. The team cannot derive the product implications. + +Diagnosis. Implications missing or vague. The synthesis stopped at observations without bridging to product responses. + +Cure. Add implications to each pattern. Each implication should be specific, falsifiable, cost-acknowledged, and tied to a specific decision. + +Prevention. The synthesis sequence's implication stage is non-negotiable. Synthesis that ships without implications is incomplete. + +--- + +## Failure 8: We hedged every pattern and the synthesis reads as wishy-washy + +Symptom. "Users may sometimes occasionally seem to indicate." Every claim caveated. The synthesis avoids commitment. + +Diagnosis. Hedge stacking. The researcher did not commit to what the data showed. + +Cure. Rewrite with conviction. Name patterns as if the data supports them. If the data does not support the position, name a smaller position the data does support; do not hedge an oversized claim. + +Prevention. During pattern naming, apply the conviction test. Hedge stacking signals a pattern that should either be sharpened or dropped. + +--- + +## Failure 9: Our quote walls were impressive but the deck was 60 slides + +Symptom. Beautiful quote pulls; designed personas; 60 slides. Readers admired the deck. Few remember the patterns. + +Diagnosis. Insight-theater. Evidence dominated; analysis receded. Quote walls without analytical bridge. + +Cure. Restructure as a document. Patterns lead; evidence in appendix. Quote walls converted into evidence-summary paragraphs supporting each pattern. + +Prevention. The format choice is upstream. Default to documents; reserve decks for short executive summaries paired with substantive documents. + +--- + +## Failure 10: The synthesis recommended 20 product changes; we shipped one + +Symptom. Synthesis presents many implications. Team picks the easiest or most-vocal one to ship. The rest sit in the synthesis document unaddressed. + +Diagnosis. Wishlist synthesis. Implications did not acknowledge cost or prioritize within themselves. The synthesis offloaded prioritization to the team without giving them a starting point. + +Cure. Re-prioritize within the synthesis. Each implication gets a cost note. The synthesis recommends a sequence: which implications to address now, which to defer, which to drop. The team has a starting point for prioritization. + +Prevention. During implication writing, surface cost. The synthesis owner uses available context to estimate cost; pairs with engineering for harder estimates. Cost-blind synthesis is incomplete. + +--- + +## Failure 11: Adjacent teams disagreed with our patterns and we did not engage + +Symptom. Synthesis ships. Support team says "this does not match what we see in tickets." Sales team says "our prospects say something different." The synthesis fails to align with the teams closest to the customer. + +Diagnosis. Adjacent-team review skipped or compressed. The synthesis reached publication without surfacing perspectives the research team did not have. + +Cure. Pause publication. Run the adjacent-team review even after the fact. Revise based on inputs. + +Prevention. Build adjacent-team review into the synthesis workflow. Make it non-negotiable. The teams closest to the customer have ground-truth observations the research team needs. + +--- + +## Failure 12: Data gaps buried in the synthesis + +Symptom. Synthesis presents conclusions where the data did not support them. The recommendations sound confident; the data is thin in places the synthesis did not name. + +Diagnosis. The we-have-enough trap. Sunk-cost reasoning suppressed honest gap-naming. + +Cure. Audit each pattern for data sufficiency. Where gaps exist, name them explicitly. Where recommendations rest on under-supported patterns, downgrade or hedge them honestly. + +Prevention. The synthesis owner's job is to be honest about what the data can and cannot support. The team relies on the synthesis owner for this honesty. + +--- + +## Failure 13: Synthesis sequence stages skipped + +Symptom. Synthesis arrives at "patterns" without going through the tagging and clustering stages. Patterns feel imposed on the data rather than emerging from it. + +Diagnosis. Stages skipped. Researcher jumped to pattern-naming based on impressions from reading transcripts. + +Cure. Restart the sequence from tagging. Patterns from skipped sequences are usually projections; tagging-grounded patterns are observations. + +Prevention. The sequence is non-negotiable. Every synthesis runs through transcribe, tag, cluster, name, imply, so-what. + +--- + +## Failure 14: Synthesis owner became defensive in the review + +Symptom. Adjacent teams raise concerns; synthesis owner argues against each one; the review session produces no revisions; synthesis ships unchanged. + +Diagnosis. Defensive review posture. The owner treated review as defense of the synthesis rather than as input to it. + +Cure. Owner takes notes; does not defend in the moment; revises based on inputs over the following days. Reviewer concerns surface in the revision; the synthesis improves. + +Prevention. Establish the review session's purpose explicitly: input, not approval. The synthesis owner's job in the session is to listen. + +--- + +## The cross-cutting pattern + +Most synthesis failures share a single root: treating synthesis as documentation work rather than as decision work. + +Documentation work prioritizes capturing the research; producing a deliverable; performing for an audience. Output: artifacts that look like synthesis but do not drive decisions. + +Decision work prioritizes producing direction; committing positions; informing prioritization. Output: synthesis that team members reference for months, that drives roadmap shifts, that earns the research investment. + +The fix for almost any synthesis failure starts with the same question: what decision is this synthesis supposed to inform? When the answer is clear, the synthesis becomes load-bearing. When the answer is "we should document the research," the synthesis fails as decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting documentation-vs-decision pattern. + +## Implementation choices that stay internal + +Specific reviewer training on synthesis-failure detection. Specific automation that flags synthesis structures (e.g., document length checks, hedge-frequency analysis). Specific reviewer dashboards. The team's own conventions for catching synthesis failures pre-publish. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md new file mode 100644 index 0000000..1ed2d6b --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md @@ -0,0 +1,192 @@ +# From pattern to product implication + +The bridge from observation to decision. Implications are where synthesis adds value beyond transcription. + +A pattern without an implication is a finding. A finding describes the world; an implication proposes action. Synthesis stops at findings; actionable synthesis reaches implications. + +--- + +## Implications are the writer's analytical work, not what the user said + +The principle. Users describe their experience; PMs interpret what experience implies for the product. + +Why this matters. A common synthesis failure is presenting implications as if they came from users. "Users want X" treated as an implication. But users do not always know what would actually solve their problem; they describe symptoms, not solutions. + +Worked example. A pattern: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +- What users said: "I had to stop and find my credit card." +- What users want (per their own description): "Make signup not require credit card details." +- What the implication actually is (PM analytical work): defer the credit-card-requiring step to after first success state, OR remove the credit card requirement at signup, OR allow signup without credit card and request it before paid features. + +The implication options surface from analytical interpretation, not from user prescription. Users said the symptom; the PM proposes the system response. + +The discipline. Frame implications as the team's analytical position grounded in the pattern, not as user requests. "The pattern implies X" rather than "Users want X." + +--- + +## Each pattern can have multiple implications + +The principle. Synthesis surfaces options; the prioritization decision picks one. + +Worked example. A pattern: "Free users hit the upgrade prompt before experiencing paid value." + +Possible implications: + +- Delay the upgrade prompt until after the user has experienced the value-realization moment. +- Show the upgrade prompt earlier but reframe it as exploratory rather than transactional. +- Add a value-realization moment earlier in the free experience to align with the existing prompt timing. +- Remove the upgrade prompt entirely; let users discover paid features through usage. + +Each implication is a different product response. The synthesis presents the options; the team's prioritization debate picks one (or sequences several). + +Why multi-implication matters. Single-implication synthesis presents the synthesizer's preferred solution as if it were the only solution. Multi-implication synthesis surfaces options the team can debate. + +The presentation. Per pattern, surface 2-4 candidate implications. Acknowledge tradeoffs between them. Recommend if the data supports a recommendation; otherwise present the options for prioritization. + +--- + +## Implications should be falsifiable + +The principle. A vague implication cannot be acted on or debated. A specific implication can. + +Vague implications. + +- "We should improve onboarding." +- "Pricing should be reconsidered." +- "Mobile experience needs attention." + +These are too vague to drive decisions. The team agrees to "improve onboarding" without committing to any specific change. + +Falsifiable implications. + +- "Defer configuration step 3 to after first success state." +- "Add a value-realization moment within the first 90 seconds of signup." +- "Make the homepage hero copy lead with B2B use cases." + +These commit specific positions. The team can debate them, scope them, kill them, prioritize them. + +The test. For each implication, ask: could the team disagree with this and explain why? If the implication is vague enough that disagreement is impossible, the implication is too vague to be useful. + +--- + +## Implications should acknowledge cost + +The principle. Patterns suggest solutions; solutions cost product capacity. Synthesis that ignores cost produces wishlists. + +The pattern that fails. Synthesis recommends 30 product changes without acknowledging that delivering them all is impossible. The team takes one or two; the rest sit. The synthesis produced no actionable input because the team had no help prioritizing. + +The pattern that works. Each implication includes an estimated cost dimension and a recommendation about whether the cost is justified. + +- "Defer configuration step 3 (medium engineering cost; high expected impact on signup conversion)." +- "Pre-populate step 3 with sensible defaults (low engineering cost; medium expected impact)." +- "Remove credit card requirement entirely (high cost across systems; uncertain impact)." + +The cost annotations help the team prioritize without re-doing the synthesis work. + +The discipline. PMs doing synthesis usually have enough context to estimate cost roughly. If they do not, they can pair with engineering to estimate. Cost-blind synthesis is incomplete. + +--- + +## Some patterns imply not-acting + +The principle. Sometimes the pattern reveals friction the team should not address. + +When not-acting is honest. + +- The friction affects too few users to justify the engineering cost. +- The friction reveals segment misfit; the affected users are not the team's target. +- Addressing the friction would compromise other priorities or product positioning. +- The friction is real but the proposed solutions are worse than the problem. + +Worked example. A pattern: "Enterprise users want admin controls that small-team users do not need." + +Implications: + +- Build the admin controls (high cost, expands target market). +- Build the admin controls only for the enterprise tier (medium cost, segment-specific). +- Do not build (acknowledges enterprise as not the target segment). + +If the team is committed to small-team users as the target market, the not-act implication is honest; building enterprise admin controls would dilute focus. + +The naming discipline. When the synthesis recommends not-acting, name it explicitly. "The pattern is real but the recommended response is to not address it because [reason]." Buried not-act implications get overlooked; the team adds the unaddressed friction to the next quarter's roadmap because nobody surfaced the not-act case. + +--- + +## Implications that bridge to specific decisions + +The principle. The strongest implications point to a specific decision the team is making. + +Implication-to-decision mapping. + +- Implication: "Defer configuration step 3." + - Decision input: should the Q2 roadmap include the onboarding redesign? (Yes, with this approach.) +- Implication: "Add B2B-leading homepage hero." + - Decision input: should the homepage redesign be prioritized this quarter? (Yes, with positioning shift.) +- Implication: "Do not address enterprise admin controls." + - Decision input: should enterprise tier be in this year's roadmap? (No; small-team focus continues.) + +Why decision-mapping matters. Implications floating free of decisions produce a list the team must connect to its prioritization work themselves. Implications mapped to decisions produce direct input. + +--- + +## Implication strength and confidence + +The principle. Not all implications are equally well-supported. + +Strong implications. + +- Pattern is supported by multiple research types (interviews + tickets + survey). +- Implication has a clear analytical bridge from the pattern. +- Cost is reasonable relative to expected impact. +- Decision input is clear. + +Weaker implications. + +- Pattern is supported by limited evidence (3 interviews; thin volume). +- Implication is one of several plausible options without clear analytical bridge. +- Cost is uncertain. +- Decision input is hedged. + +The discipline. Synthesis labels implications by strength. Strong ones get presented as recommendations; weaker ones as options for further investigation. The team can prioritize confidently when it knows which implications carry weight. + +--- + +## Common pattern-to-implication failures + +Implications that restate the pattern. "The pattern shows X. The implication is X." No analytical bridge; no value added. + +Wishlist implications. Synthesis recommends 30 changes; the team cannot prioritize; one or two ship; the rest sit. + +Implications buried in narrative. The synthesis discusses the pattern at length; the implication is one sentence at the end. Readers miss it. + +No cost acknowledgment. Implications presented as if all are equal cost; team has to do the cost analysis itself. + +Skipping the not-act implication. Synthesis recommends action on every pattern; some patterns warrant not-acting; the synthesis fails to surface this honestly. + +Implications that prescribe specific designs. Implications should propose product responses, not detailed designs. Detailed designs are for spec writing; implications are the upstream input. + +--- + +## The implication-quality audit + +A short framework for auditing implications. + +1. Is each implication an analytical proposition, not a user request? +2. Are multiple candidate implications surfaced where appropriate? +3. Is each implication specific enough to be falsifiable? +4. Does each implication acknowledge cost? +5. Where the data supports not-acting, is that surfaced honestly? +6. Does each implication map to a specific decision? +7. Is implication strength labeled? + +Synthesis that passes this audit converts research into decisions. Synthesis that fails it produces findings that look like decisions but do not drive them. + +--- + +## Methodology-level choices that stay in the public skill + +The implication-as-analytical-work principle. Multi-implication patterns. Falsifiability. Cost acknowledgment. The not-act implication. Decision mapping. Implication strength. Common failures. The audit. + +## Implementation choices that stay internal + +Specific document templates that surface implications. Specific cost-estimation conventions. Specific cross-functional review patterns for cost validation. The team's own conventions for implication-strength labeling. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md new file mode 100644 index 0000000..26d6aac --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/pattern-naming-patterns.md @@ -0,0 +1,178 @@ +# Pattern naming patterns + +Pattern naming is the work that distinguishes synthesis from documentation. A pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references for months. + +The naming is not formatting. It is analytical work that surfaces what the data actually shows. Most synthesis underperforms because the pattern names did not do this work. + +--- + +## A pattern name is not a category label + +The principle. Categories describe topics; patterns describe specific observations the data reveals. + +Examples. + +- Category: "Onboarding." +- Pattern: "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." + +- Category: "Pricing." +- Pattern: "Free users hit the upgrade prompt before they have experienced the paid value, producing churn instead of conversion." + +- Category: "Mobile." +- Pattern: "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +Why categories fail as pattern names. Categories are containers. The synthesis with category-named patterns is a list of containers, not a list of observations. Readers cannot tell what the data showed; only what topic it concerned. + +The test. Does the pattern name commit a position about what the data reveals, or does it merely name a topic the data covered? Position-committing names are patterns; topic-naming labels are categories. + +--- + +## The name should make the implication legible + +The principle. A reader who sees only the pattern name should be able to guess the product implication. + +Examples that pass the test. + +- "Users abandon configuration step 3 because credit card details are not accessible during signup." + - Implication a reader can guess: defer configuration step 3 to after first success state, or remove credit card requirement at signup. +- "Sales prospects assume the product is for B2C because the homepage hero shows consumer use cases." + - Implication a reader can guess: revise homepage positioning to lead with B2B use cases. + +Examples that fail the test. + +- "Onboarding has issues." +- "Users have feedback about pricing." +- "There is mobile-related friction." + +Why implication-legibility matters. Synthesis exists to drive decisions. Pattern names that obscure implications force readers to do the analytical work themselves; many readers will not, and the synthesis fails to inform decisions. + +--- + +## Avoid category bloat + +The principle. Strong synthesis has 4-8 named patterns. Synthesis with 30 patterns is usually under-clustered: many of those are variations on a smaller number of underlying patterns. + +Diagnosis of bloat. + +- Look at the pattern list. Are some patterns sub-cases of others? If yes, the under-cluster is producing inflation. +- Are there patterns that always co-occur with other patterns? If yes, they may be the same pattern viewed from different angles. +- Are there patterns supported by 1-2 artifacts only? If yes, they may be noise being elevated to pattern status. + +The cure. Re-cluster. Take the 30-pattern list back to clustering and look for the 4-8 underlying patterns the data actually supports. + +Why bloat fails. Synthesis with 30 patterns produces no decision direction: the team cannot prioritize 30 things. Synthesis with 4-8 patterns surfaces what to focus on. + +--- + +## Avoid naming the obvious + +The principle. A pattern is a specific observation that the product team did not already know. Pattern names that read as truisms ("users want fast performance") are not patterns. + +The truism trap. + +- "Users want better performance." +- "Users find some aspects confusing." +- "Pricing is a consideration in the decision." +- "Mobile usage is increasing." + +These are descriptive of the universe; they do not describe what the research revealed. + +The cure. For each pattern name, ask: would this name have been just as accurate without the research? If yes, the pattern is a truism. The research must have surfaced something more specific; rewrite the name to capture it. + +The "what the team did not know" test. Strong pattern names commit a position the team would not have made before the research. Weak pattern names commit positions the team already held. + +--- + +## Name with conviction + +The principle. Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly. + +Hedging vs precision. + +- Hedged: "Some users may experience occasional difficulty in some configuration steps." +- Precise: "Users abandon configuration step 3 in 40% of signup attempts." + +The precise name is also commitment-bearing: it claims a specific behavior at a specific frequency. If the data does not support 40%, the name is wrong; the researcher should restate. The hedged name avoids being wrong by avoiding being specific. + +Why conviction matters. Synthesis that hedges every pattern reads as a researcher avoiding accountability. Readers cannot debate hedged patterns; they cannot prioritize them; they cannot act on them. Conviction-named patterns invite challenge, which strengthens synthesis. + +The discipline. Name as if the data fully supports the position. If it does not, name a smaller position the data does support. Do not pad an under-supported position with hedging. + +--- + +## Pattern naming structures that work + +Several structures recur across strong synthesis. + +The behavioral observation: "Users [do specific action] because [specific cause]." + +Example: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +This structure forces specificity in both behavior and cause. + +The contradiction: "Users [say X] but [do Y]." + +Example: "Users in interviews report wanting more configuration options, but in support tickets request defaults that match their actual usage." + +This structure surfaces the gap between stated preference and revealed preference. + +The segment difference: "[Segment A] [does X], while [Segment B] [does Y]." + +Example: "Free users hit the upgrade prompt before experiencing paid value, while paid users encounter it after the value-realization moment." + +This structure surfaces sub-segment patterns the research revealed. + +The mismatch: "[Team's framing] does not match [user's framing]." + +Example: "Marketing positions the product as B2C-friendly; sales prospects evaluating for B2B use assume the product is consumer-only based on the homepage." + +This structure surfaces positioning gaps. + +The frequency-specific: "[Specific behavior happens at frequency X across segment Y]." + +Example: "30% of new users hit the configuration friction within 5 minutes of signup; the friction correlates with day-7 churn." + +This structure pairs qualitative observation with quantitative validation. + +--- + +## The pattern-name editing pass + +Strong synthesis runs a final editing pass focused only on pattern names. + +For each pattern name, the editing questions. + +1. Is this a category or a pattern? +2. Can a reader guess the implication from the name alone? +3. Is this a truism or a specific observation? +4. Does the name commit a position with conviction? +5. Does the name match what the data actually shows (no overstatement)? +6. Could this be split into multiple patterns or merged with another? + +The editing investment. 1-2 hours of focused name-editing on a 4-8 pattern set. The investment pays off in synthesis usability. + +--- + +## Common pattern-naming failures + +Categories disguised as patterns. "Onboarding patterns" as a section heading; nothing in the section actually names a pattern. + +Patterns that hedge into nothing. "Users may sometimes experience difficulty"; the name commits no position. + +Truism patterns. "Users want fast performance"; the name describes the universe, not the data. + +Vague specificity. "Configuration step 3 is problematic"; specific enough to seem like a pattern, vague enough to not be one. + +Pattern bloat. 30 named patterns; the synthesis loses focus and produces no priorities. + +Patterns named without evidence ties. Synthesis where readers cannot trace each pattern to specific artifacts and quotes. Patterns become assertions rather than observations. + +--- + +## Methodology-level choices that stay in the public skill + +The category-vs-pattern distinction. The implication-legibility test. The avoid-bloat principle. The avoid-truism principle. The conviction principle. The pattern-name structures that work. The editing pass. Common naming failures. + +## Implementation choices that stay internal + +Specific document templates that surface pattern names prominently. Specific reviewer rubrics for editing pattern names. Specific A/B testing of pattern name variants for clarity. The team's own conventions for pattern count within the bands. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md new file mode 100644 index 0000000..341f05f --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md @@ -0,0 +1,221 @@ +# Research types and when each fits + +Five common discovery research types, what each surfaces, what synthesis they support, and how to compose them within a single discovery cycle. + +Research-type selection is upstream of synthesis. The wrong types collected for the question produce data that synthesis cannot rescue. The right types collected, even at modest scale, produce synthesis that drives decisions. + +--- + +## Customer interviews + +Format. 30-90 minute conversations, structured or semi-structured. Often one-on-one, sometimes in pairs or small groups for specific contexts. + +Artifacts. Recordings, transcripts, moderator notes, sometimes follow-up email exchanges. + +What this surfaces. + +- Why users do what they do (motivation, context, constraints). +- The struggling moments and workarounds users have built. +- The mental model behind user behavior. +- The trade-offs users are weighing that the team did not anticipate. +- The vocabulary users actually use (often different from internal product language). + +What this does not surface. + +- What users actually do in practice (interview self-report differs from behavioral data). +- Patterns that emerge only at scale (a single interview is one data point). +- Pricing willingness to pay (interview answers about price are notoriously unreliable). + +Synthesis implications. + +- Highest per-artifact richness; warrants careful per-transcript tagging. +- Best paired with other research types that quantify the qualitative patterns. +- Pattern thinness risk: 8-15 interviews surfaces patterns; 3-5 surfaces hypotheses that need more validation. + +Typical batch size. 8-15 interviews per discovery cycle. Larger batches saturate (most patterns emerge by interview 8-10 in a focused topic). + +--- + +## Support ticket reviews + +Format. Audit of recent support tickets, often spanning a defined time window or a defined product area. + +Artifacts. Tagged ticket dataset, agent-conversation transcripts, sometimes recorded support calls. + +What this surfaces. + +- The friction users actually hit (revealed by ticket volume). +- The vocabulary users use to describe broken experiences. +- The disconnect between intended user flow and actual user behavior. +- Repeated workflows that produce confusion or errors. +- Documentation and onboarding gaps. + +What this does not surface. + +- Why users got there (the ticket starts at the problem; the path before is not visible). +- The experience of users who did not contact support (silent struggling). +- Users who succeed without friction. + +Synthesis implications. + +- Lower per-artifact richness; higher volume; signal lives in patterns across many tickets. +- Best for surfacing concrete friction points; weak for understanding motivation. +- Often pairs with interviews (interviews explain why; tickets document where). + +Typical batch size. 100-500 tickets per audit, often filtered by topic or product area. + +--- + +## Sales call analysis + +Format. Recording or transcript review of recent sales calls. Often pairs with sales team feedback on patterns they hear repeatedly. + +Artifacts. Call recordings, sales notes, CRM-tagged objections, deal-stage data. + +What this surfaces. + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Use cases prospects describe (sometimes different from how marketing describes the product). +- Words prospects use to describe their situation (vocabulary signal). + +What this does not surface. + +- Existing-customer experience (sales calls are pre-purchase). +- Why prospects who did not buy did not buy (lost-deal analysis is a separate research mode). + +Synthesis implications. + +- Pairs well with positioning and pricing decisions. +- Useful for marketing-product alignment work. +- Sales teams often have synthesis hypotheses already; the research either confirms or challenges those. + +Typical batch size. 15-30 calls per audit. + +--- + +## Survey data + +Format. Quantitative responses to structured questions, often with optional qualitative comments. + +Artifacts. Response dataset, segmented by audience attributes. + +What this surfaces. + +- The frequency and severity of patterns identified through other research. +- Segment differences (do Pro users and Free users have different needs). +- Quantitative validation of qualitative hypotheses. +- Aggregate satisfaction or NPS-style sentiment. + +What this does not surface. + +- Why users responded the way they did (closed-ended responses do not explain). +- Patterns that the survey questions did not anticipate (surveys cannot find what they did not ask about). +- Behavior (surveys reveal what users say, not what they do). + +Synthesis implications. + +- Best as validation of qualitative patterns at scale, not as primary discovery. +- Survey design biases (leading questions, response order effects, satisficing) compromise data; treat with skepticism. +- Open-ended comments are often the highest-value section of a survey. + +Typical batch size. 100-2,000 responses, depending on segment specificity. + +--- + +## In-app feedback + +Format. Users submitting feedback through in-product channels (feedback widgets, NPS prompts, post-task surveys, error-state feedback forms). + +Artifacts. Submitted feedback corpus, often timestamped and contextualized by where in the product the feedback was triggered. + +What this surfaces. + +- Friction at the moment users encounter it (high context fidelity). +- Patterns across many low-effort submissions. +- Feature requests grounded in specific usage moments. +- Bugs and broken experiences not captured by support. + +What this does not surface. + +- Users who did not bother to submit feedback (silent majority). +- Why users hit the friction (the feedback names the problem; not always the cause). +- Patterns from users who do not actively use the feedback channels. + +Synthesis implications. + +- Volume varies widely; some products see high in-app feedback volume, others minimal. +- Often pairs with support tickets (similar surface area; different submission channels). +- Useful as ongoing signal; this skill is more about the periodic-audit case (`user-feedback-aggregation` covers continuous synthesis). + +Typical batch size. Ongoing; synthesized in periodic audits over defined windows. + +--- + +## Composition across types + +Strong discovery cycles combine research types deliberately. + +The pair-and-validate pattern. + +- Interviews (depth, ~12 conversations) provide qualitative patterns. +- Support tickets (volume, ~300 tickets) document where friction surfaces in practice. +- Survey (validation, ~500 responses) quantifies the patterns at scale. +- Synthesis weaves all three: interview patterns ground the why, tickets ground the where, survey grounds the how-many. + +The triangulate-the-decision pattern. + +- A specific decision (should we redesign onboarding) gets evidence from three sources. +- Interviews surface the experience of recent signups. +- Sales calls surface what prospects say onboarding will look like. +- Support tickets surface what new users actually hit. +- Synthesis converges three perspectives on the same decision. + +The single-type sufficiency pattern. + +- Some discovery questions only need one type. A pricing review might need only sales call analysis. A support-volume reduction effort might need only ticket analysis. +- Discipline: do not commission research types that will not contribute to the decision. + +The wrong-pairs to avoid. + +- Interviews + survey only, with no behavioral data: both are self-report; both can be wrong in the same direction. +- Survey only, no qualitative: the survey assumes the questions are right. +- Sales calls only, no customer voice: the prospect view is one segment; existing-customer voice may differ. + +--- + +## Research-type pitfalls per type + +Interview pitfalls. Recruiting bias (the easiest-to-recruit users are not always representative). Leading questions. Confirming the team's prior hypothesis rather than challenging it. Small-batch over-generalization. + +Support ticket pitfalls. Survivorship bias (only users who contacted support are visible; users who silently churned are not). Tag quality (poor tagging compounds in synthesis). Time-window choice (a window that misses recent product changes can mislead). + +Sales call pitfalls. Stage selection (early-stage discovery calls and late-stage closing calls reveal different things). Sales-team interpretation (sales reps' framings can color how calls are tagged). Anonymization vs detail (privacy needs can erase the specifics that matter). + +Survey pitfalls. Response bias (who responds is not representative of who is asked). Question wording. Ordering effects. Satisficing (respondents click through without engaging). Falsely-precise quantitative output from low-quality data. + +In-app feedback pitfalls. Channel bias (the kinds of users who submit in-app feedback differ from those who do not). Volume-driven prioritization (loudest categories get attention; quieter ones get missed). + +--- + +## When to commission what + +A short framework. + +1. Decision driving the research. What product decision is this research meant to inform? +2. Best research type for that decision. Discovery (interviews lead), validation (survey or quantitative leads), friction-mapping (support and in-app feedback lead), positioning (sales call analysis leads). +3. Composition. Which secondary types triangulate the primary? +4. Capacity. What can be collected within the time and budget the decision allows? +5. Existing data check. Has the team already collected research that would answer the question? Mining existing artifacts often produces value before commissioning new research. + +--- + +## Methodology-level choices that stay in the public skill + +The five research types and what each surfaces. The composition patterns. The wrong-pairs to avoid. The pitfalls per type. The when-to-commission framework. The principle that research-type selection is upstream of synthesis quality. + +## Implementation choices that stay internal + +Specific recruiting platforms and incentive structures. Specific transcription tooling. Specific support-ticket platforms and their tagging schemas. Specific survey tools and statistical-significance configurations. Specific in-app feedback widgets and integration patterns. The team's own conventions for sample sizes within the bands. These vary by team, budget, and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md new file mode 100644 index 0000000..4043285 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md @@ -0,0 +1,177 @@ +# Synthesis review and validation + +How synthesis gets pressure-tested before it drives decisions. Review and validation surface synthesis errors that the research team missed: fabricated patterns, projected interpretations, missing dissent, segment misreads. + +The discipline is making review non-negotiable. Synthesis that ships without review carries unacknowledged blind spots; review compresses those blind spots before the synthesis becomes the team's working document. + +--- + +## Internal review with research participants where possible + +The principle. Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? + +Why participant review matters. + +- Participants are the only authoritative source on whether the synthesis represents their experience. +- Misrecognition signals fabrication: the synthesis projected interpretations the data did not support, or named patterns that did not match what participants actually said. +- Recognition validates the synthesis: participants endorse the patterns as accurate representations. + +The mechanics. + +- Send the synthesis (or relevant excerpts) to 3-5 research participants for review. +- Ask: "Do these patterns reflect your experience? Anything missing? Anything the synthesis got wrong?" +- Build participant recognition into the research design from the start (with consent for follow-up review). + +The exception. Some research types (large-scale survey, anonymous in-app feedback) do not support participant review at the individual level. For those, validation depends on aggregate quantitative checks (the next section). + +The honest disclosure. When participant review surfaces misrecognition, the synthesis revises rather than dismissing the feedback. Synthesis that dismisses participant pushback is reverting to confirmation bias. + +--- + +## Adjacent-team review + +The principle. Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? + +Why adjacent-team review matters. + +- Adjacent teams have ground-truth observations the research did not access. Support sees the friction users hit every day; sales hears prospect objections; engineering knows which problems are technically tractable. +- Adjacent teams catch synthesis errors that the research team missed: patterns that contradict what support handles daily, implications that ignore engineering constraints. +- Adjacent teams' alignment with synthesis affects whether the synthesis drives decisions: if support disagrees with the support-related patterns, the synthesis loses authority. + +The mechanics. + +- Share the synthesis with relevant adjacent-team leads for review. +- Hold a structured review session where adjacent teams can challenge, validate, or extend the patterns. +- Capture adjacent-team observations as inputs to synthesis revision. + +Common adjacent-team feedback patterns. + +- Support: "Your synthesis names X as a pattern, but support tickets show Y is also load-bearing and not in the synthesis." +- Sales: "Prospects do say what your synthesis claims, but the patterns you missed are the pricing-conversation friction." +- Engineering: "The implication you propose has a constraint the synthesis did not account for." + +The synthesis revises in light of these inputs. + +--- + +## Quantitative validation where possible + +The principle. Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. + +The validation pattern. + +- Synthesis says: "Users abandon configuration step 3 because credit card details are not accessible at signup." +- Quantitative validation: pull analytics on configuration step 3 abandonment rate. Does the data confirm 40% abandonment that the pattern implies? Does abandonment correlate with the credit card requirement (versus other possible causes)? +- If the data confirms: the pattern is strongly supported. +- If the data does not confirm: the pattern needs revision; the qualitative signal may not generalize. + +Why validation matters. + +- Qualitative patterns can overstate frequency; small-sample interview signal does not always match large-sample reality. +- Quantitative validation grounds synthesis in scaled data without requiring the synthesis to be quantitative-only. +- Validation reveals which patterns are strong enough to act on and which need more investigation. + +See `experiment-design` for rigorous A/B testing as quantitative validation. See `product-analytics-setup` for the instrumentation that makes validation possible. + +The honest disclosure. When quantitative validation contradicts qualitative patterns, the synthesis adjusts. Patterns the analytics does not support get downgraded or removed. Synthesis that ignores quantitative pushback in favor of qualitative claims is unrigorous. + +--- + +## The "challenge the synthesis" session + +The principle. A specific session where adjacent teams try to find what the synthesis missed, overstated, or railroaded. + +The session structure. + +- Synthesis owner presents the patterns and implications (15-30 minutes). +- Adjacent-team participants challenge: "What patterns did the research miss? What implications overstate the data? What decisions is the synthesis trying to railroad?" +- Synthesis owner takes notes; does not defend; the session is for surfacing concerns, not for resolution in the moment. +- Synthesis owner revises based on the inputs over the following days; revised synthesis circulates back. + +Why this works. + +- Productive disagreement strengthens synthesis. The team that surfaces concerns is contributing to better synthesis, not undermining the research investment. +- The session creates space for honest pushback that quieter review formats sometimes suppress. +- The session signals that synthesis is open to challenge, which strengthens the team's trust in the synthesis once it ships. + +The anti-pattern. Synthesis owners who treat the session as defense of the synthesis rather than as input to the synthesis. The owner pushes back on every challenge; adjacent teams disengage; synthesis ships unrevised. + +The discipline. The synthesis owner's job in the session is to listen and capture, not to defend. Defense happens in the revision; pushback happens later, after considering the input. + +--- + +## Iterate before publishing + +The principle. Synthesis goes through revision based on the review loop. Synthesis that ships in first-draft state usually carries unacknowledged blind spots. + +The iteration cycle. + +- First draft from the synthesis owner. +- Participant review (where possible). +- Adjacent-team review (always). +- Challenge-the-synthesis session. +- Revision based on inputs. +- Final review by senior product leader for clarity and quality. +- Publication. + +Time investment. The review-and-iteration loop adds 1-2 weeks to the synthesis timeline. That investment is small relative to the cost of publishing synthesis with blind spots that produce wrong decisions. + +Common iteration outputs. + +- Patterns split (the original pattern was actually two patterns adjacent teams distinguished). +- Patterns merged (the original separation was not load-bearing). +- Patterns revised (the framing did not match the data on closer review). +- Implications expanded (additional implications surfaced during review). +- Implications narrowed (some implications overstepped what the data supports). +- Decision input refined (the original was too vague to drive decisions). + +--- + +## When the review loop reveals the synthesis cannot be saved + +The honest case. Sometimes review surfaces synthesis problems too deep to fix in revision: patterns built on insufficient data, projections the data did not support, framing that adjacent teams flatly contradict. + +The response. + +- Stop. Do not publish synthesis with known significant problems. +- Re-examine: was the underlying research adequate? Was the synthesis sequence run completely? Were the patterns named with conviction or projected? +- Restart from where the breakdown happened. Often returns to clustering or pattern-naming. +- Sometimes returns to gathering more research. The honest case is acknowledging that the discovery cycle did not produce sufficient input for reliable synthesis. + +The cost calibration. Restarting synthesis costs PM time. Publishing flawed synthesis costs the team's trust in research output, plus the wrong decisions the flawed synthesis drives. The latter is usually more expensive. + +--- + +## What review does not do + +Review does not validate every synthesis. Some synthesis fails review and should not ship; some passes with revision; some passes with minor adjustment. Review is the discipline that distinguishes the cases. + +Review does not eliminate disagreement. Adjacent teams may continue to disagree even after review. The synthesis owner makes the final call after considering inputs. Disagreement preserved in the published synthesis is fine and honest; pretended consensus is not. + +Review does not slow shipping artificially. A 1-2 week review loop on substantive synthesis is appropriate. Quick-turn synthesis (short audits, focused interview batches) can run a lighter review (asynchronous comments from 2-3 reviewers; adjacent-team check; ship). + +--- + +## Common review-and-validation failures + +Skipping participant review. Synthesis ships without participants ever seeing the patterns; participants would have caught misrecognitions; the synthesis carries projection. + +Skipping adjacent-team review. The team most likely to know the data is wrong did not see the synthesis before publication. + +Defensive review sessions. The synthesis owner argues against challenges instead of capturing them; the session produces defense rather than input. + +Quantitative validation skipped. The qualitative patterns went unchallenged by available analytics data; the synthesis overstates patterns the data does not support. + +Iteration compressed to one round. First draft + one review + ship. Most synthesis benefits from two rounds of revision: first round on substance, second round on presentation. + +Review feedback dismissed. Adjacent teams raise concerns; synthesis owner notes them but does not revise. Synthesis ships as if the feedback did not happen. + +--- + +## Methodology-level choices that stay in the public skill + +The participant review pattern. The adjacent-team review pattern. Quantitative validation. The challenge-the-synthesis session. Iteration discipline. The cannot-be-saved escalation. What review does and does not do. Common review failures. + +## Implementation choices that stay internal + +Specific reviewer pairings and roles. Specific session formats and facilitation. Specific revision tracking. Specific publication conventions. Specific quantitative validation pipelines. The team's own conventions for review-loop length. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md new file mode 100644 index 0000000..5a9b6f3 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md @@ -0,0 +1,229 @@ +# Synthesis sequence walkthrough + +The six-stage synthesis sequence with worked example. Stage outputs, common skip-failures, time investment per stage. + +The sequence is non-negotiable. Teams that skip stages produce findings that look like synthesis but are not: untagged transcripts, unclustered tags, unnamed patterns, patterns without implications, implications without decisions. Each stage builds on the previous; skipping any stage breaks the chain. + +--- + +## The six stages + +1. Transcribe and prepare. Convert artifacts into a synthesizable format. +2. Tag at the artifact level. First-pass descriptive tagging. +3. Cluster across artifacts. Group tags into themes. +4. Name patterns. Each cluster becomes a named pattern. +5. Infer product implications. What does each pattern imply. +6. Name the so-what. The decision input. + +--- + +## Stage 1: Transcribe and prepare + +The work. Convert artifacts into a format you can read, mark up, and search. + +Outputs. + +- Interview transcripts, time-stamped, speaker-labeled. +- Support ticket dataset, exported to a workable format with relevant fields (subject, body, resolution, tags, dates). +- Sales call summaries or transcripts. +- Survey data with open-ended responses extracted into a reviewable format. + +Time investment. Often underestimated. A 60-minute interview takes 60-90 minutes to transcribe (with AI tools) plus 30-60 minutes to clean. Eight interviews: 12-20 hours of prep before tagging starts. + +Common skip-failures. + +- Skipping transcription on the assumption that the recordings are sufficient. Reality: tagging from audio is impractical at any meaningful batch size. +- Cleaning to the point of distortion (removing the messy parts that contain signal). +- Skipping speaker labels (collapsed dialog loses critical context). + +The unglamorous-but-essential principle. Teams that skip prep work never reach the later stages because the artifacts are not workable. The investment in prep pays back across every later stage. + +--- + +## Stage 2: Tag at the artifact level + +The work. Read each transcript or ticket and tag it with topics, problems, quotes, and observations. + +Outputs. + +- Tagged artifacts (transcripts, tickets, etc.) with descriptive tags inline. +- A tag list (often 80-150 tags per batch by the end of this stage). +- Quote pulls (specific sentences worth referencing later). + +Approach. + +- First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. +- Allow tag proliferation. Do not force consolidation in this stage; that is for clustering. +- Tag dissent and contradictions explicitly. "User reports liking the onboarding" alongside other users reporting friction is signal; tag it. +- Mark quotes worth pulling. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. + +Time investment. Per artifact: 30-90 minutes for an interview transcript, 1-3 minutes per support ticket, 15-30 minutes per sales call. A typical batch (12 interviews + 200 tickets + 20 sales calls) might run 25-40 hours of focused tagging work. + +Common skip-failures. + +- Pre-designing the tag taxonomy and forcing artifacts into it. +- Tagging from memory after reading the transcript rather than during reading. +- Premature consolidation (collapsing tags during this stage instead of later). +- Skipping the contradictions (only tagging the dominant pattern). + +The artifact-level discipline. Each tag is grounded in a specific moment in a specific artifact. Tags floating free of evidence are a stage-2 failure that compounds in later stages. + +--- + +## Stage 3: Cluster across artifacts + +The work. Group tags into themes that surface the patterns the data reveals. + +Outputs. + +- A cluster list (often 6-15 clusters from the 80-150 tags). +- Per-cluster tag membership. +- Per-cluster artifact source list (which artifacts contributed to this cluster). + +Approach. + +- Cluster on the underlying observation, not on tag overlap. Two tags that co-occur may not be the same pattern. +- Iterate: first-pass clustering will reveal that some tags belong in multiple clusters; some clusters are too broad; some need to split. +- Use the artifact-source list to test cluster strength. A cluster with 8 supporting artifacts is stronger than one with 2. +- Track the dissent: which clusters have countervailing evidence the synthesis must address. + +Time investment. 4-8 hours of clustering work for a batch this size. Often done collaboratively with another reviewer to surface alternative groupings. + +Common skip-failures. + +- Clustering on assumed categories rather than emergent themes. +- Stopping at first-pass clustering without iterating. +- Ignoring artifact-source counts (clusters with thin support get weighted equally with strong ones). +- Forcing every tag into a cluster (some tags are noise; that is fine). + +--- + +## Stage 4: Name patterns + +The work. Each cluster becomes a named pattern that captures what the underlying observation actually is. + +Outputs. + +- A pattern list (typically 4-8 patterns from a strong synthesis). +- Per-pattern name, evidence summary, and source-artifact list. + +Approach. + +- Pattern name is specific enough that a reader can guess the implication. +- Pattern names commit a position: name what the data shows, not a category the data sits in. +- Avoid truisms: pattern names that read as something everyone could have said before the research are not patterns. +- Limit pattern count: 4-8 strong patterns serve synthesis better than 15 weak ones. + +Time investment. 2-4 hours of pattern-naming work. Often the highest-impact stage; investment in good pattern names pays off in implications and decisions. + +Common skip-failures. + +- Pattern names that are category labels (Onboarding, Pricing, Support). +- Pattern names that are truisms (Users want fast performance). +- Hedge-stacked pattern names (Users sometimes seem to occasionally maybe). +- Too many patterns (under-clustering manifests as pattern bloat). + +See `pattern-naming-patterns.md` for detail. + +--- + +## Stage 5: Infer product implications + +The work. For each pattern, name what this implies for the product. + +Outputs. + +- Per-pattern implication list (often 1-3 implications per pattern). +- Per-implication: specific, falsifiable, cost-acknowledged. + +Approach. + +- Each pattern can have multiple implications. Surface the options; do not pre-prioritize. +- Implications are the writer's analytical work, not what users said. Users describe experience; PMs interpret what experience implies. +- Make implications falsifiable. "We should improve onboarding" is not an implication; "Move the third configuration step to after first success state" is. +- Acknowledge cost. Implications that ignore implementation cost produce wishlists. +- Some patterns imply not-acting. Naming the not-act implication is honest synthesis. + +Time investment. 3-6 hours of implication work. + +Common skip-failures. + +- Vague implications that cannot be acted on or debated. +- Wishlist implications that do not acknowledge cost. +- Skipping the not-act implication when it would be honest. +- Implications that are restatements of the pattern (no analytical bridge). + +See `from-pattern-to-product-implication.md` for detail. + +--- + +## Stage 6: Name the so-what + +The work. For each implication, the specific decision it informs. + +Outputs. + +- Per-implication so-what statement tied to a real decision. +- An overall recommendation section: what should change as a result of this synthesis. + +Approach. + +- Map each implication to a decision the team is making (or should make). +- Be specific: "Should the Q2 roadmap include the onboarding redesign?" rather than "Onboarding should be considered." +- Surface the synthesis's overall recommendation: where to invest, where to deprioritize, where to gather more data before deciding. +- Acknowledge the decisions the synthesis cannot resolve: data gaps, contested patterns, decisions outside the synthesis's scope. + +Time investment. 2-4 hours of so-what work. + +Common skip-failures. + +- So-whats that are too abstract to drive decisions. +- Skipping the overall recommendation section (each pattern stands alone; the synthesis does not aggregate). +- Buried data gaps (the synthesis presents conclusions where the data did not support them). + +--- + +## Worked example + +A discovery cycle with 12 customer interviews + 250 support tickets + a sales call audit, focused on a possible onboarding redesign. + +Stage 1 (prep). 18 hours. Interview transcripts cleaned; ticket dataset extracted; sales call transcripts pulled. + +Stage 2 (tagging). 32 hours. 110 tags emerged across the artifacts. Quote pulls captured. + +Stage 3 (clustering). 6 hours. Clusters emerged: configuration-step friction, value-state delay, onboarding length, mobile-context onboarding, role-based mismatch, support-deflectable confusion. Six clusters with varying artifact support. + +Stage 4 (pattern naming). 3 hours. Six patterns named, including: + +- "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." +- "Free users reach the success state at half the rate of paid users because the configuration burden is the same but the value reveal is gated." +- "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +Stage 5 (implications). 4 hours. Per-pattern implications. Example for the configuration-step pattern: + +- Implication: defer configuration step 3 to after first success state, with a "complete your setup" prompt later. +- Cost: medium engineering investment; affects existing flows for users who completed step 3 historically. +- Alternative implication: pre-populate step 3 with sensible defaults from step 2 data where possible. +- Not-act implication: keep the current flow but improve docs (probably insufficient given the friction severity). + +Stage 6 (so-what). 3 hours. Decision input: yes, prioritize onboarding redesign in Q2; staged-onboarding approach; mobile parity is a sub-track within the redesign; configuration-step deferral is the headline change. + +Total synthesis time. 66 hours over the six stages. Roughly 1.5-2 weeks of focused synthesis work for one PM. + +--- + +## Time-investment patterns + +Synthesis sequences that go shorter than this are usually skipping stages. Sequences that go longer are usually over-investing in tagging or under-deciding in implications. The 60-80 hour range for a substantial discovery synthesis is typical. + +Programs that have not budgeted synthesis time often discover it after research ships and the synthesis stalls. The discipline is budgeting synthesis at the start of the discovery cycle, not as an afterthought. + +--- + +## Methodology-level choices that stay in the public skill + +The six-stage sequence with stage outputs and time investments. The worked example. The non-negotiability of the sequence. Common skip-failures per stage. + +## Implementation choices that stay internal + +Specific transcription tools. Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific document templates per output. Specific time-tracking conventions for synthesis budgeting. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md new file mode 100644 index 0000000..b09da20 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md @@ -0,0 +1,140 @@ +# Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. Tagging and clustering done badly produces bad patterns; tagging and clustering done well produces patterns that drive decisions. + +The discipline is in five principles that apply across both stages. + +--- + +## Principle 1: Tag at the artifact level first; do not pre-design the taxonomy + +The pattern. Tags emerge from the artifacts. The researcher reads each transcript and tags what is actually there. + +The anti-pattern. Researchers arrive at tagging with a pre-built taxonomy: "we will tag for usability, performance, pricing, support." Artifacts get forced into the categories. Patterns the taxonomy did not anticipate get missed. + +Why pre-built taxonomies fail. + +- The taxonomy reflects what the team already thinks; tagging confirms what the team already thinks; synthesis does not reveal anything new. +- Artifacts that do not fit the taxonomy categories get skipped or shoehorned in. +- Tags that emerge in the data but were not in the taxonomy do not get captured. + +The exception. Some categorical metadata is fine to apply consistently (user segment, source channel, recency). The semantic tagging that drives synthesis should still emerge from the data. + +The recovery. Mid-tagging, if the team realizes the pre-built taxonomy is constraining, it can be discarded and tagging restarted with descriptive tags emerging from artifacts. Better to restart than to publish synthesis grounded in a constraining taxonomy. + +--- + +## Principle 2: Allow tag proliferation; collapse later + +The pattern. First-pass tagging produces 80-150 tags across a batch. That is correct. Premature consolidation loses distinctions that turn out to matter. + +The anti-pattern. Researchers consolidating tags during the tagging stage. "We had four onboarding tags; let me merge them into one." The merge happens before the researcher has seen whether the four tags actually represent different patterns. + +Why proliferation matters. + +- Some distinctions only become visible after seeing many artifacts. Two tags that seem similar at artifact 3 may turn out to be different patterns by artifact 12. +- Granular tags can always be collapsed in the clustering stage; collapsed tags cannot be unmerged once the tagging is done. +- Proliferation supports the discovery posture; consolidation supports the confirmation posture. + +The volume calibration. A batch of 12 interviews + 250 tickets + 20 sales calls might end with 80-150 tags. Fewer than that often signals premature consolidation; more than that may signal undisciplined tagging. + +--- + +## Principle 3: Cluster on patterns, not on tag overlap + +The pattern. Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation, not on statistical co-occurrence. + +The anti-pattern. Tools that auto-cluster by co-occurrence. They produce statistical groupings that do not always match the patterns the researcher needs. + +Why pattern-clustering matters. + +- "Slow onboarding" and "configuration friction" might co-occur because both are common; that does not mean they are the same pattern. They might be the same (configuration is what makes onboarding feel slow) or different (there is friction in configuration AND there is a perception of length independent of configuration). +- The researcher's interpretation of the artifact-level tags is what surfaces the pattern; tools can suggest groupings but cannot determine them. + +The work. For each candidate cluster, ask: are the underlying observations the same, or do they share a tag because the tag was loose? If the latter, split the cluster. + +--- + +## Principle 4: Name the cluster after clustering, not before + +The pattern. The cluster name comes from the data after the clustering work is done. + +The anti-pattern. Researchers arriving with named clusters and slotting data into them. The clusters become hypothesis-confirmation rather than discovery. + +Why post-cluster naming matters. + +- Pre-named clusters bias the clustering: tags get assigned to clusters they fit linguistically rather than substantively. +- Post-cluster naming reveals patterns the team did not anticipate (the highest-value patterns). +- The naming itself is part of the synthesis work; rushing the naming compresses the analytical work into a label without thought. + +The discipline. First-pass clustering produces unnamed clusters. The researcher then names each cluster based on what the underlying observations actually show. Names emerge after the clustering, not before. + +--- + +## Principle 5: Tag dissent and contradictions explicitly + +The pattern. Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. + +The anti-pattern. Tagging only the dominant pattern; ignoring the contradictions; or tagging contradictions but not following them through to clustering and synthesis. + +Why dissent matters. + +- Contradictions reveal sub-segments. "Most users find configuration confusing; experienced users find it efficient" might mean the pattern is segment-specific, not universal. +- Contradictions reveal pattern strength. A pattern with no countervailing evidence is suspicious; a pattern with some dissent that the synthesis can explain is stronger. +- Synthesis that ignores dissent reads as researcher confirmation bias. + +The discipline. Each major pattern in synthesis has a "but consider" section: contradictions in the data, segment differences, edge cases. The synthesis is more honest with these sections; readers trust patterns that engage their counterevidence. + +--- + +## Tagging tactics that work + +A short list of tactics that improve tagging quality. + +Read the artifact end-to-end before tagging. Tagging while reading on first pass produces fragmentary tags. Reading first, then tagging on a second pass, produces tags grounded in the artifact's full context. + +Tag specific moments, not summaries. "User struggles" is a summary. "User abandons configuration step 3 because credit card details are not accessible during signup" is a specific moment. Specific moments support stronger pattern naming later. + +Pull quotes during tagging. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. Marking quote-worthy moments during tagging prevents re-reading later. + +Tag motivation alongside behavior. "User clicked X" is behavior; "User clicked X because they thought it would Y" is motivation. Motivation tags surface what users were trying to accomplish, which informs implications more than behavior alone. + +Tag emotional valence sparingly. "User was frustrated" is fine; tagging every artifact for emotional state produces noise. + +--- + +## Clustering tactics that work + +Iterate clustering at least twice. First-pass clustering is rough; second-pass clustering refines; third-pass clustering catches what the first two missed. + +Use artifact-source counts. A cluster supported by 8 artifacts is stronger than one supported by 2. The source count does not determine pattern importance, but it informs synthesis weighting. + +Test cluster boundaries. Take a tag from one cluster and ask: could this fit in another cluster instead? If yes, the cluster boundaries are unclear; refine. + +Surface the leftovers. Tags that do not fit any cluster are signal. They might be noise (one-off observations not generalizing). They might be edge-case patterns worth naming separately. They might point to a cluster the researcher missed. + +Cluster collaboratively where possible. A second reviewer surfaces alternative groupings the first reviewer did not see. Two reviewers usually produces better clustering than one. + +--- + +## Common tagging-and-clustering failures + +Tagging by memory, not by reading. Researchers reading transcripts and then tagging from recall. Loses specifics; produces general tags that cluster poorly. + +Tag exhaustion. Researchers running through too many artifacts in one session, tag quality decaying as fatigue sets in. Reduce session length; pace the tagging across days. + +Confirming the team's prior hypothesis. Researchers entering tagging with a hypothesis the research is meant to confirm. Tags get assigned to support the hypothesis; counterevidence gets minimized. + +Cluster collapsing to fit a target count. Researchers feeling they should have N clusters and forcing the data to that count. Either over-collapsing (losing distinctions) or under-collapsing (preserving noise as signal). + +Skipping the dissent. Tagging only the dominant pattern; clustering only the supporting tags. Synthesis publishes patterns without their counterevidence; reviewers later catch the gap. + +--- + +## Methodology-level choices that stay in the public skill + +The five principles (tag at artifact level, allow proliferation, cluster on patterns, name after clustering, tag dissent). The tagging tactics. The clustering tactics. The common failures. + +## Implementation choices that stay internal + +Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific session-length conventions for tagging. Specific reviewer pairings. The team's own conventions for tag-count thresholds. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md new file mode 100644 index 0000000..5ba1b81 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/when-to-gather-more-data.md @@ -0,0 +1,212 @@ +# When to gather more data + +Synthesis sometimes reveals that the research did not collect enough. The discipline is naming gaps explicitly and deciding whether to halt synthesis, ship with named gaps, or restart with more research. + +The discomfort of acknowledging gaps is the source of bad synthesis. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals it was not. The discipline is honesty about what the research can and cannot support. + +--- + +## Pattern thinness + +The signal. A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. + +Why it happens. + +- The discovery cycle had a defined batch size; some patterns emerged with limited support. +- The pattern is real but rare; the research did not encounter enough cases to characterize it. +- The pattern is segment-specific; the research overrepresented other segments. + +The honest options. + +- Name the pattern as tentative pending more data. Synthesis ships with this pattern flagged as preliminary; the team treats it as a hypothesis rather than a finding. +- Pause synthesis to gather more research. If the pattern is decision-load-bearing, the additional research investment may be worthwhile. +- Drop the pattern. If the pattern is not decision-relevant or the data is too thin to be useful, do not include it. Inflating thin patterns to fill space is a synthesis failure. + +The dishonest option to avoid. Naming the thin pattern as if it had full support. Readers cannot distinguish well-supported from thinly-supported patterns; decisions get made as if all patterns are equal weight; the team gets surprised when the thin-pattern decisions do not pan out. + +--- + +## Segment under-representation + +The signal. The research overrepresents one user segment and underrepresents another that matters for the decision. + +Why it happens. + +- Recruiting bias produces segment skew (the easiest-to-recruit users are usually a specific segment). +- The research was scoped before the team realized which segments mattered most for the decision. +- Available research artifacts (existing tickets, prior interviews) skew toward certain segments. + +The honest options. + +- Synthesize for the represented segment; flag explicitly that the patterns may not apply to underrepresented segments. +- Pause to recruit and conduct research with the underrepresented segment. +- Use existing data sources (analytics, support data) to validate patterns in the underrepresented segment indirectly. + +Worked example. A discovery cycle on B2B onboarding interviews 12 users, all from companies of 50-500 employees. The synthesis surfaces strong patterns for that segment. The product team is also considering enterprise (1000+ employees) and small business (1-50). The synthesis should: + +- Name patterns for the 50-500 segment with confidence. +- Acknowledge that enterprise and small business patterns are not represented. +- Recommend either separate research for the missing segments or scoping the decision to the segment the data covered. + +--- + +## Contradictory clusters + +The signal. Two clusters point in opposite directions and the data does not resolve the contradiction. + +Why it happens. + +- Sub-segment differences the research did not investigate explicitly. +- Different use contexts producing different needs (mobile vs desktop, new vs returning users). +- One cluster reflects what users say; the other reflects what users do; the contradiction is real and revealing. + +The honest options. + +- Investigate the contradiction. Often the contradiction itself becomes the most valuable finding: it surfaces a sub-segment or context distinction the team did not anticipate. +- Pause synthesis to gather targeted research that resolves the contradiction. +- Ship synthesis with the contradiction named and the recommendation to gather more data before committing decisions in this area. + +Worked example. Interviews with new users surface that they want simpler onboarding. Support tickets from new users in the same week surface frequent requests for more configuration options during onboarding. The contradiction may reveal: + +- New users say "simpler" but mean "fewer required steps before value"; configuration options are fine if not blocking. +- The interview sample skewed casual users; the support tickets came from power users. +- The contradiction needs more investigation before driving onboarding redesign. + +--- + +## Decision time pressure + +The signal. Synthesis revealing data gaps but the decision has to ship before more research can happen. + +Why it happens. + +- Roadmap commitments do not flex for data gaps. +- The decision is upstream of work that has already been committed. +- The cost of waiting exceeds the value of additional data. + +The honest path. + +- Name the data gap explicitly in the synthesis. Do not pretend the gap does not exist. +- Make the recommendation with the gap acknowledged. "Given current data, we recommend X. The gap that may revise this recommendation is Y." +- Plan the follow-up research that would validate or revise the recommendation. +- Build instrumentation that will validate the recommendation post-launch (so the team can detect if the recommendation was wrong). + +The path to avoid. Pretending the data is sufficient when it is not. Synthesis under time pressure that treats partial data as complete data produces decisions the team will not be able to recover from cleanly when the gap surfaces later. + +--- + +## The "we have enough" trap + +The pattern. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals gaps. + +Why it happens. + +- Sunk-cost reasoning: the team has spent the research budget; restarting feels like waste. +- Timeline pressure: the research was scheduled before synthesis; more research means schedule slip. +- Status concerns: declaring the research insufficient feels like admitting the discovery work was inadequate. + +Why it produces bad synthesis. + +- The data gaps still exist whether or not the team acknowledges them. Decisions made on incomplete data still suffer from the incompleteness. +- Synthesis that papers over gaps trains the team to treat synthesis as performative rather than load-bearing. +- The next discovery cycle will repeat the same scoping mistakes because the team did not name them honestly. + +The discipline. + +- Naming gaps is the synthesis owner's job. The team relies on the synthesis owner to be honest about what the research can and cannot support. +- The cost of naming gaps is short-term discomfort; the cost of pretending they do not exist is bad decisions. +- "We have enough" should be the conclusion of synthesis review, not the assumption. + +--- + +## When more research is the right call + +The criteria. + +- The decision is load-bearing for product direction. +- The gap is large enough that synthesis would be misleading without addressing it. +- The cost of additional research is bounded and feasible. +- The cost of deciding now and being wrong is high. + +Examples that warrant more research. + +- A pricing decision where current research underrepresents the segment that drives revenue. +- An onboarding redesign where the synthesis cannot distinguish what new users want from what they need. +- A positioning shift where existing-customer voice is in the data but prospect voice is missing. + +Examples that do not warrant more research. + +- Minor decisions where the gap's resolution would not change the recommendation materially. +- Decisions where the cost of waiting exceeds the value of additional data. +- Decisions that can be reversed easily based on post-launch data. + +--- + +## When to ship synthesis with named gaps + +The criteria. + +- Decision time pressure makes more research infeasible. +- The gap is named honestly so the team can weigh the recommendation accordingly. +- Post-launch instrumentation will detect if the recommendation was wrong. + +The discipline. + +- The named gap is in the synthesis prominently, not buried. +- The recommendation acknowledges what the gap might change. +- The follow-up research plan is specific and committed. + +Worked example. "Recommendation: prioritize the onboarding redesign in Q2. Caveat: our research underrepresents enterprise users; if enterprise represents a significant share of new signups, the redesign should include enterprise-specific paths we have not validated. Follow-up: enterprise-specific user research in Q1 to validate the redesign approach for that segment before Q2 ships." + +--- + +## When to drop the pattern entirely + +The criteria. + +- The supporting data is too thin to commit a position even tentatively. +- The pattern, if false, would mislead the team in directions hard to recover from. +- The pattern is not load-bearing for the synthesis's primary recommendations. + +The discipline. + +- Some thin patterns warrant dropping rather than flagging. Not every observation needs to make it into the synthesis. +- Dropping is honest synthesis; inflating is not. + +--- + +## Common gather-more-data failures + +Inflating thin patterns. Patterns supported by 2 artifacts presented as if supported by 12. Readers cannot distinguish strength. + +Hiding segment gaps. Synthesis presents recommendations as universal when they apply only to the segment researched. + +Pretending contradictions resolved. Synthesis writes around the contradiction rather than naming it; readers later discover it on their own. + +Decision-pressure denial. Synthesis treats time pressure as if it makes data complete. The decision is made; the wrong-decision cost is paid later. + +The "we have enough" trap. Sunk cost and status protect the synthesis from honest gap-naming. + +Endless research. The opposite failure: every gap triggers more research; synthesis never ships; the team paralyzes on data-gathering. + +--- + +## The data-sufficiency calibration + +A short framework. + +1. Is the gap load-bearing for the recommendations? If yes, address it. If no, name and proceed. +2. Is more research feasible within the decision timeline? If yes, gather. If no, ship with named gaps. +3. Can post-launch instrumentation catch wrong decisions? If yes, ship-with-instrumentation is reasonable. If no, more caution warranted. +4. What is the cost of being wrong vs cost of waiting? Compare; choose the lower-cost path. +5. Is the team's commitment to follow-up research credible? If named gaps will trigger real follow-up, ship-with-gaps works. If named gaps will be ignored, gather now. + +--- + +## Methodology-level choices that stay in the public skill + +The pattern thinness signal. Segment under-representation. Contradictory clusters. Decision time pressure. The we-have-enough trap. When more research is and is not the right call. When to ship with named gaps. When to drop patterns. Common gather-more-data failures. The data-sufficiency calibration. + +## Implementation choices that stay internal + +Specific recruiting pipelines for follow-up research. Specific instrumentation for post-launch validation. Specific synthesis-revision workflows when gaps are named. The team's own conventions for "thin pattern" thresholds. These vary by team. diff --git a/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md b/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md new file mode 100644 index 0000000..6291907 --- /dev/null +++ b/dist/pi/.agents/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md @@ -0,0 +1,207 @@ +# Writing for decisions, not decks + +Synthesis output should be optimized for decision use, not for presentation. The format choice (document vs deck), the structure (patterns lead, evidence appendix), the voice (opinionated), and the closing (decision input section) compose to produce synthesis the team actually references. + +--- + +## Document, not deck + +The principle. Deck format is poor for synthesis. + +Why decks fail. + +- Slides cannot carry argument density. A pattern, its evidence summary, its implications, and its decision input do not fit on one slide; spreading them across slides loses coherence. +- Readers cannot reference slides later. A pattern needs to be findable; decks decay into icons and bullet points that are hard to search and cite. +- Decks are presentation artifacts; synthesis needs to be a reference artifact that the team uses for months. +- The deck format encourages summarization that loses precision. + +Why documents work. + +- A 4-12 page document can carry the pattern, evidence, implications, and decision input in connected prose. +- Documents are searchable, linkable, and citable. +- Documents accommodate density without overwhelming; readers can scan headings and dive into sections. +- Documents read as load-bearing analytical work; decks read as presentation. + +The exception. A short executive summary deck (5-8 slides) can pair with a substantive document. The deck summarizes; the document carries the work. + +The discipline. If the synthesis is being optimized for a single 30-minute readout meeting, the format will fail when the team needs to reference the synthesis in week 6 of execution. Optimize for the reference use, not the presentation moment. + +--- + +## Lead with patterns and implications; relegate evidence to appendix + +The principle. Readers scanning for decision input want patterns and implications first. + +The reader's question. "What does this synthesis tell me to do?" Patterns and implications answer it. Evidence supports the answer but is not the answer. + +The structure that works. + +- Executive summary (1 page): the patterns, the recommendations, the decision input. +- Pattern sections (1-3 pages per pattern): pattern name, evidence summary in 2-3 sentences, implications, decision input. +- Recommendations section (1 page): overall synthesis recommendation; what should change. +- Appendix: detailed evidence, quote pulls, methodology notes, full transcripts or links to them. + +The structure that fails. + +- Decks that lead with quote walls. Readers admire the quotes; they do not extract decisions. +- Documents that bury the patterns under methodology and background. Readers stop reading before reaching the patterns. +- Synthesis that mixes evidence and analysis throughout. Readers cannot tell where observation ends and recommendation begins. + +The discipline. Each pattern section is short (2-4 paragraphs of synthesis text); evidence linked or summarized briefly; the appendix is where evidence depth lives. Readers who want depth follow the link; readers who want decisions stay in the body. + +--- + +## One section per pattern, parallel structure + +The principle. Synthesis with 4-8 patterns has 4-8 parallel sections, each with the same structure. + +Per-section structure. + +- Pattern name (the heading). +- Evidence summary (2-3 sentences naming the artifacts and the dominant signals). +- Implication (1-3 implications with cost notes). +- Decision input (specific decision the implication informs). + +Why parallel structure works. + +- Readers learn the structure from the first section and can scan subsequent ones. +- Comparison across patterns is easier when each is presented the same way. +- Editing for completeness is easier (each section either has the elements or it does not). + +The variation. Some patterns warrant longer treatment (richer evidence, more complex implications); some are shorter. Length variation is fine; structural variation is not. + +--- + +## Be opinionated + +The principle. Synthesis that hedges every pattern reads as a researcher avoiding accountability. + +Hedged synthesis. + +- "Users may sometimes occasionally seem to indicate possible difficulty." +- "It might be considered to potentially explore some adjustments." +- "There could be benefits to investigating opportunities." + +These commit nothing. Readers cannot debate or decide on hedged synthesis. + +Opinionated synthesis. + +- "Users abandon configuration step 3 in 40% of signup attempts because credit card details are not accessible at signup." +- "The Q2 roadmap should prioritize the onboarding redesign over the dashboard expansion." +- "The not-act recommendation is to defer enterprise admin controls until small-team segment growth stabilizes." + +These commit positions. Readers can disagree; disagreement produces decisions. + +The discipline. Write synthesis as a recommendation. The PM doing synthesis is making analytical claims; readers may push back, but pushback is the point. Hedging avoids pushback by avoiding claim. + +The exception for honest uncertainty. When the data genuinely does not support a position, name the uncertainty explicitly: "The evidence supports two possible interpretations; we recommend gathering more data before deciding." This is honest uncertainty, not hedging. Hedging is dressing up uncertainty as if it were synthesis. + +--- + +## Include a decision-input section + +The principle. What does this synthesis recommend the team do? + +The section's role. The decision-input section connects the synthesis to the team's prioritization work. Without it, the synthesis presents patterns and implications but does not aggregate them into recommendations. + +What the section addresses. + +- Where should priorities shift based on this synthesis? +- Which roadmap items does the synthesis validate? Which does it challenge? +- Which decisions can the team make now with this synthesis as input? +- Which decisions need more research before making? +- What is the synthesis's overall view of where the product should focus? + +The section's voice. Direct, specific, opinionated. The team can disagree, but the section should commit a recommendation. + +The discipline. Without this section, synthesis is a collection of patterns; with this section, synthesis is decision input. The section is what makes the synthesis load-bearing for the team's strategic work. + +--- + +## Length calibration + +The principle. Synthesis should be as short as possible without losing the load-bearing content. + +Typical lengths. + +- Discovery cycle synthesis from a meaningful research batch: 6-12 pages. +- Smaller-scale synthesis from a single research type (e.g., support audit alone): 3-6 pages. +- Quick-turn synthesis from a focused interview batch: 2-4 pages. + +Length anti-patterns. + +- Synthesis padded to 30+ pages. Readers stop reading; the load-bearing content gets lost. +- Synthesis compressed to 1 page. Density too high; specifics get lost. +- Synthesis stretched across multiple documents without clear primacy. Readers do not know which document is the synthesis. + +The discipline. Edit for length. Each pattern section should be tight; each implication should be specific; the recommendation should be concise. Readers will engage with a 6-page synthesis they can finish in 20 minutes; readers will skim a 30-page synthesis and miss the recommendations. + +--- + +## The reference-after-shipping test + +The principle. Synthesis that gets referenced months after publication has earned its keep. + +The test. Six months after a synthesis ships, can the team: + +- Name the patterns the synthesis surfaced? +- Cite the synthesis in roadmap discussions? +- Use the synthesis as input for related decisions that came up after publication? + +Failures the test reveals. + +- Synthesis nobody can name suggests insight-theater (presented but not absorbed). +- Synthesis nobody references suggests document-shelf-syndrome (filed away after readout). +- Synthesis the team contradicts in later decisions suggests the synthesis was not load-bearing in their actual prioritization work. + +Recovery. When prior synthesis fails the test, the next synthesis should adjust: shorter, more opinionated, more directly tied to specific decisions. Each round of synthesis should be more usable than the prior. + +--- + +## Visual elements in synthesis documents + +The discipline. Visuals should carry argumentative load the prose alone cannot. + +Visuals that work. + +- A pattern-to-implication-to-decision diagram showing how the synthesis connects to product work. +- A frequency chart for patterns supported by quantitative data. +- A segment comparison table where patterns differ across segments. +- An evidence map showing artifact-source distribution per pattern. + +Visuals that fail. + +- Stock images decorating section breaks. +- Quote walls without context. +- Word clouds (rarely informative). +- Persona illustrations (decorative; not synthesis output). + +The frequency. Visual elements every 2-3 pages of synthesis is typical. More than that risks decoration; fewer is fine if the prose carries the work. + +--- + +## Common synthesis-writing failures + +Format choice. Deck instead of document; the synthesis decays into bullets that lose precision. + +Buried recommendations. Patterns are clear; the recommendation is one sentence on page 11. Readers miss it. + +Hedge-stacking. Every claim caveated; readers cannot extract a position. + +No decision-input section. Synthesis presents patterns; team has to aggregate them into decisions on their own; usually does not. + +Length excess. 30 pages of synthesis where 8 would have served. Readers skim; load-bearing content gets lost. + +Length compression. 1 page of synthesis where 6 were needed. Density too high; specifics lost. + +Quote-wall presentation. Evidence dominates; analysis recedes; readers admire the quotes and miss the synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The document-not-deck principle. The patterns-lead-evidence-appendix structure. The parallel-section discipline. The opinionated voice. The decision-input section. Length calibration. The reference-after-shipping test. Visual element discipline. Common failures. + +## Implementation choices that stay internal + +Specific document templates and styles. Specific document hosting (Notion, Coda, Google Docs, Confluence). Specific link conventions for evidence. Specific reviewer workflows. Specific archive practices. The team's own conventions for synthesis length within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/documentation-strategy/SKILL.md b/dist/pi/.agents/skills/documentation-strategy/SKILL.md new file mode 100644 index 0000000..1b65361 --- /dev/null +++ b/dist/pi/.agents/skills/documentation-strategy/SKILL.md @@ -0,0 +1,428 @@ +--- +name: documentation-strategy +description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long." +category: process-and-team +catalog_summary: "Documentation systems, what to document, maintenance cadence" +display_order: 2 +--- + +# Documentation Strategy + +Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases. + +--- + +## When to use + +- Setting up documentation for a new team or product +- Auditing existing documentation +- Fixing stale or scattered docs +- Choosing a documentation tool or platform +- Defining what gets documented and what doesn't +- Establishing maintenance cadence +- Scoping technical writing work +- Designing onboarding documentation (use alongside `team-onboarding-playbook`) + +## When NOT to use + +- Writing the actual content of a single document (use `content-and-copy`) +- Customer-facing knowledge base copy (use `content-strategy`) +- Code comments and inline documentation (covered by `code-review-web`) +- One-off blog posts or articles (use `content-and-copy`) + +--- + +## Required inputs + +- The audience (internal, external, customer, dev, exec) +- Existing docs and their state (where, what shape, last updated) +- Team size and growth trajectory +- The kinds of work that produce documentation (engineering, product, ops, support) +- Tools currently in use + +--- + +## The framework: 4 categories of documentation + +Different categories of doc serve different purposes. Conflating them is how docs get bad. + +### Category 1: Reference + +What things are. Looked up when needed. + +Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries. + +Properties: +- Comprehensive +- Fact-checked, kept accurate +- Searchable +- Stable structure (links don't break) +- Version-aware where relevant + +### Category 2: How-to + +How to do specific tasks. Procedural. + +Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill." + +Properties: +- Step-by-step +- Tested by someone who didn't write it +- Includes the prerequisites +- Includes troubleshooting +- Versioned to the system it documents + +### Category 3: Explanation + +Why things are the way they are. Conceptual. + +Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents. + +Properties: +- Narrative +- Captures context (the why) +- Often historical (why we built it this way) +- Links to evidence + +### Category 4: Tutorial + +Learning-oriented. Walks someone from zero to capable. + +Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways. + +Properties: +- Sequenced from simple to complex +- Hands-on +- Doesn't assume prior knowledge in scope +- Has clear completion criteria + +(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.) + +--- + +## The framework: 5 tiers of doc + +Different docs serve different audiences with different stakes. + +### Tier 1: Customer-facing + +Public docs, customer KBs, API references. High visibility, slow change. + +Standards: +- Editorial review +- Version control +- Clear ownership +- High freshness bar +- Tied to release + +### Tier 2: Cross-team / shared + +Docs used across teams: shared APIs, common services, company-wide processes. + +Standards: +- Cross-team ownership clear +- Update obligations on changes +- Mid-to-high freshness bar + +### Tier 3: Team-internal + +Docs for the team that owns them: how the team works, runbooks, decisions. + +Standards: +- Team-owned, team-maintained +- Mid freshness bar +- Useful for the next person joining + +### Tier 4: Personal scratchpad + +Notes, drafts, work-in-progress. Not for others. + +Standards: +- Low maintenance +- Don't link from official docs +- Promote to higher tier when valuable + +### Tier 5: Auto-generated + +Docs derived from code: API references generated from comments, schemas, etc. + +Standards: +- Generation is automated, runs in CI +- Single source of truth (the code) +- Reviewed for usability, not freshness (that's automatic) + +The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable. + +--- + +## Workflow + +### Step 1: Audit current state + +- What docs exist? +- Where do they live? (often: scattered) +- Who owns each? +- How fresh are they? +- Are they actually used? (check page views or referrals if measurable) + +The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize. + +### Step 2: Categorize and tier + +For each doc: +- Category (reference / how-to / explanation / tutorial) +- Tier (customer / shared / team / scratchpad / generated) + +Some docs are mixed. Note the dominant category. + +### Step 3: Identify gaps + +What documentation does the team need that doesn't exist? + +Common gaps: +- "How does X actually work?" no answer +- Onboarding for the role no one's onboarded recently +- Runbook for a system that's never broken (yet) +- Decision rationale for "why are we doing it this way" + +Ask people what they wish were documented. They know. + +### Step 4: Identify dead weight + +Docs that are: +- Out of date and not getting updated +- Duplicated across places (one is canonical, others should redirect or be deleted) +- About things that no longer exist +- Drafts abandoned long ago + +Delete or archive. Stale docs are worse than missing docs (people might trust them). + +### Step 5: Pick the home(s) + +Where docs live affects whether they're maintained. + +Common locations: +- Code repo (markdown): for docs tightly coupled to code (READMEs, ADRs, runbooks for the service) +- Wiki / Notion / Confluence: for cross-team and team-internal +- Docs site (Docusaurus, Mintlify, custom): for customer-facing +- Tickets / decision logs: for ephemeral records + +Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?" + +### Step 6: Establish ownership + +Every doc has an owner. Without an owner, it goes stale. + +Owner can be: +- A team +- A role (the on-call rotation, the PM, the EM) +- A person, with a backup + +If an owner isn't obvious, the doc may not deserve to exist. + +### Step 7: Establish maintenance cadence + +Per tier: + +\| Tier \| Review cadence \| +\|---\|---\| +\| Customer-facing \| Per release, plus quarterly \| +\| Cross-team \| Quarterly \| +\| Team-internal \| Quarterly \| +\| Personal scratchpad \| None \| +\| Auto-generated \| On every change \| + +Maintenance includes: +- Verify accuracy +- Update for changed systems +- Archive what's no longer relevant +- Address user feedback + +### Step 8: Make doc updates part of work + +Documentation isn't a separate project. It's part of the work that produces it. + +- New feature: docs are part of the feature +- New process: doc is part of the rollout +- Decision made: ADR or decision-log entry filed +- Bug postmortem: runbook updated +- New hire: onboarding doc updated based on their experience + +The team that ships features without docs has less than they think they have. + +### Step 9: Make docs discoverable + +Even great docs are useless if no one finds them. + +- Search that actually works (most platforms; some better than others) +- Index pages for major topics +- Cross-links between related docs +- Search aliases for common alternative phrasings +- Pinning the most-used docs + +### Step 10: Measure + +What's measurable depends on the platform: +- Page views +- Search queries (and zero-result queries) +- "Was this helpful?" feedback +- Time on page +- Referral patterns + +For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear). + +--- + +## Specific patterns + +### README per project + +Every code repo has a README that answers: +- What is this? +- How do I run it? +- How do I contribute? +- Where do I find more info? + +Five sentences each, often. Length isn't the goal. The READ-it-ME promise is. + +### ADR (Architecture Decision Record) + +Per significant decision: + +``` +# ADR-NNN: [Title] + +Status: [Proposed / Accepted / Deprecated / Superseded] +Date: [Date] + +## Context +[What's the situation? What forces are at play?] + +## Decision +[What was decided?] + +## Consequences +[What happens because of this decision? Both good and bad.] +``` + +ADRs accumulate. They become the explanation layer for "why are we doing it this way." + +### Runbook + +Per system: +- What it is +- How to access it +- Common operations (with commands) +- Common failure modes +- Restore from backup procedure +- Escalation contacts + +See `incident-response` and `backup-and-disaster-recovery` for runbook standards. + +### Onboarding pathway + +Per role: +- Day 1 +- Week 1 +- Month 1 +- 90 days + +See `team-onboarding-playbook`. + +### Decision log + +Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony. + +### Glossary + +Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later). + +--- + +## Tooling + +The tool is less important than the discipline. That said: + +\| Tool category \| Examples \| Best for \| +\|---\|---\|---\| +\| Wiki \| Notion, Confluence, GitBook \| Cross-team, internal \| +\| Markdown in code \| GitHub, GitLab, Bitbucket \| READMEs, ADRs, technical \| +\| Docs sites \| Docusaurus, Mintlify, ReadMe \| Customer-facing, public docs \| +\| Internal sites \| MkDocs, custom \| Team-specific patterns \| + +Considerations: +- Search quality (a poor search makes everything worse) +- Editor quality (people won't write in painful editors) +- Version control (can you see history?) +- Permissions (right people can read and write) +- API and integration (for automation) +- Cost at your scale + +For small teams: a single wiki tool is plenty. For larger: tiered tools. + +--- + +## AI-related notes + +LLMs and AI assistants increasingly read documentation. Some considerations: + +- Clear, consistent structure helps both humans and AI +- A glossary of terms helps both +- File-level metadata (front matter) helps tools +- Public docs may be read by AI crawlers; consider an `llms.txt` if relevant +- AI-generated drafts are a starting point, not a final answer; humans review + +--- + +## Failure patterns + +Documentation as a "later" task. Always written later. Later means never. Make docs part of the work. + +One mega-doc for everything. Wiki page that's 8,000 words. No one reads it. Break by category and topic. + +Stale docs that nobody trusts. "Probably out of date" is the thought that kills documentation. Either keep current or archive. + +Docs everyone agrees should exist but no one writes. The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific. + +Wikis that are graveyards. Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set. + +Docs separated from code. API docs in a wiki, code in a repo. They drift. Co-locate. + +Docs without examples. Reference without examples is hard to use. Examples make it concrete. + +Examples that don't run. Code examples that worked once, drifted. Test examples in CI where possible. + +Long-form when reference would do. A 2,000-word doc explaining what a 30-row table would. Use the right form. + +Multiple sources of truth. Same info in three places, all slightly different. Pick canonical, redirect others. + +Doc tools no one uses. Adopted because of a feature; team doesn't actually use it. Pick tools the team will use. + +Doc style guide that's longer than the docs. Process beats product. Guide should be short. + +No way to mark docs as deprecated. Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status. + +No analytics. No idea what's being used or what's missing. Even basic page views inform priorities. + +Docs that read like specifications. Dense, formal, hard to scan. Write for the reader. + +--- + +## Output format + +A documentation strategy document includes: + +- Audit: what exists, where, in what state +- Tiering and categorization: the framework applied to existing docs +- Gap list: what should exist but doesn't +- Tool decisions: where each kind of doc lives +- Ownership map: who owns what +- Maintenance cadence: what's reviewed when +- Style guide (brief): consistency standards +- Roadmap: prioritized work to fill gaps and close out dead weight + +--- + +## Reference files + +- [`references/doc-types-guide.md`](references/doc-types-guide.md): Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each. diff --git a/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md b/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md new file mode 100644 index 0000000..badadbf --- /dev/null +++ b/dist/pi/.agents/skills/documentation-strategy/references/doc-types-guide.md @@ -0,0 +1,451 @@ +# Doc Types Guide + +The four categories of documentation, what each is for, and a template for each. Based on the Diátaxis framework (well-known in technical writing). + +The categories aren't interchangeable. Mixing them is the most common failure in documentation: a "tutorial" that's actually reference, a "how-to" that's secretly explanation, a "reference" that meanders into tutorial territory. + +--- + +## The four types + +\| Type \| Purpose \| Reader needs \| Style \| +\|---\|---\|---\|---\| +\| Reference \| Look up facts \| "What is the value of X?" \| Comprehensive, terse \| +\| How-to \| Solve a specific problem \| "How do I do Y?" \| Step-by-step, focused \| +\| Explanation \| Understand the why \| "Why does Z work this way?" \| Discursive, narrative \| +\| Tutorial \| Learn from zero \| "How do I get started?" \| Hands-on, sequenced \| + +A useful diagram of how they relate: + +``` + Practical (action) + \| + HOW-TO ───────────\|─────────── REFERENCE + \| + \| + Theoretical (understanding) + \| + TUTORIAL ───────────\|─────────── EXPLANATION + \| + Study (acquiring skill) Work (applying skill) +``` + +- Tutorial and how-to are practical (the reader is doing something) +- Reference and explanation are theoretical (the reader is understanding something) +- Tutorial and explanation are study-oriented (acquiring skill or understanding) +- How-to and reference are work-oriented (applying skill) + +--- + +## Reference + +### What it is + +The complete catalog of facts about something. Looked up when needed. + +### Examples + +- API reference (every endpoint, every parameter, every response) +- Configuration options (every flag, every default, every effect) +- Glossary (every term, definition) +- Error code catalog +- Component library docs + +### What makes it good + +- Comprehensive (covers everything) +- Accurate (verified against the actual system) +- Consistently structured (each entry follows the same pattern) +- Searchable (people find what they need quickly) +- Stable links (entries don't move or disappear without redirects) + +### What makes it bad + +- Editorializing ("This is the best way...") +- Tutorials interleaved (reader looking up a fact gets a wall of explanation) +- Inconsistent depth (some entries thorough, others sparse) +- Out of date (single most common reference failure) + +### Template + +``` +# [Function / Endpoint / Setting / Term] + +Type: [function / endpoint / configuration / etc.] +Since: [version introduced] +Status: [stable / beta / deprecated] + +## Description + +[1-2 sentences. What this is.] + +## [Parameters / Inputs / Properties] + +\| Name \| Type \| Default \| Description \| +\|---\|---\|---\|---\| +\| [name] \| [type] \| [default] \| [description] \| + +## [Returns / Output] + +[Description of return value or output.] + +## Examples + +[Minimum useful example.] + +## Notes + +- [Edge case] +- [Gotcha] +- [Related: link to related reference] +``` + +--- + +## How-to + +### What it is + +A guide to accomplishing a specific task. The reader has a problem; the how-to gives the solution. + +### Examples + +- "How to deploy to production" +- "How to reset a forgotten password" +- "How to add a new locale" +- "How to migrate data from system A to system B" + +### What makes it good + +- Goal-oriented (solves a specific problem) +- Sequential (steps in order) +- Tested (someone other than the author followed it) +- Includes prerequisites +- Includes troubleshooting for known issues +- Realistic (uses real values, not placeholders that confuse) + +### What makes it bad + +- Mixed with explanation (the reader wants to act, not understand the design) +- Too generic (steps don't apply cleanly to the actual situation) +- Out of date (commands no longer work) +- Missing prerequisites (reader gets stuck on step 2 because of an unstated dependency) +- Too many branches ("If X then..., else if Y then..."; usually means it should be split into multiple how-tos) + +### Template + +``` +# How to [Specific Task] + +## Goal + +[1 sentence: what the reader will accomplish.] + +## Before you start + +- [Prerequisite 1] +- [Prerequisite 2] +- [Prerequisite 3] + +## Steps + +### 1. [First step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 2. [Second step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 3. [Third step] + +[...] + +## Verify + +[How to confirm the task succeeded.] + +## Troubleshooting + +Problem: [Common issue] + +[Cause and resolution.] + +Problem: [Common issue] + +[Cause and resolution.] + +## See also + +- [Related how-to] +- [Related reference] +``` + +--- + +## Explanation + +### What it is + +The why. Discursive. Helps the reader understand the design, the rationale, the tradeoffs. + +### Examples + +- Architecture documents +- Design rationale +- Decision records (ADRs) +- "Why we don't support feature X" +- Strategy documents +- Conceptual overviews + +### What makes it good + +- Captures the why (not just the what) +- Honest about tradeoffs (every design choice has a cost) +- Includes alternatives considered +- Time-stamped (so readers know when this was true) +- Connects to other concepts + +### What makes it bad + +- Lecture-y (reader feels talked down to) +- Ahistorical (no context of why decisions were made) +- Marketing voice (everything is "great" and "exciting") +- Buried in how-to (reader is trying to do something; explanation slows them down) + +### Template (ADR specifically) + +``` +# ADR-NNN: [Title of decision] + +Status: [Proposed / Accepted / Deprecated / Superseded by ADR-MMM] +Date: [YYYY-MM-DD] +Deciders: [Who was involved] + +## Context + +[What's the situation? What's the problem? What forces are at play?] + +[Include enough context that a reader new to this can understand. Don't assume the present-day context will be obvious in the future.] + +## Decision + +[What was decided. State it clearly.] + +## Alternatives considered + +### Alternative A: [Name] + +[Description, why not chosen.] + +### Alternative B: [Name] + +[Description, why not chosen.] + +## Consequences + +### Positive + +- [What's better as a result] +- [What's better as a result] + +### Negative + +- [What's worse or constrained as a result] +- [What's worse or constrained as a result] + +### Neutral / mixed + +- [Tradeoffs that aren't clearly good or bad] + +## Notes + +[Anything else relevant. Links to discussion threads, prototypes, related decisions.] +``` + +### Template (general explanation doc) + +``` +# [Topic] + +## What this is + +[2-3 sentences orienting the reader.] + +## Background + +[The context. What was true before. Why this came up.] + +## How it works + +[The substance. Walk through the design, the model, the structure. Use diagrams.] + +## Why this approach + +[The rationale. What we considered. What we chose and why.] + +## Tradeoffs + +[Honest accounting of what's good and bad about this approach.] + +## See also + +[Related explanation, related decisions, related reference.] +``` + +--- + +## Tutorial + +### What it is + +Learning by doing. The reader starts with no knowledge of the topic and finishes capable of using it. + +### Examples + +- "Getting started with our SDK" +- "Your first deployment" +- Onboarding pathways for new team members +- "Building your first integration" + +### What makes it good + +- Sequenced from simple to complex +- Hands-on (the reader does things, not just reads) +- Concrete (real values, real commands, real outcomes) +- Has clear completion criteria +- Builds on a single thread (one project, one example) +- Acknowledges where the reader is (beginner) + +### What makes it bad + +- Reference dressed up as tutorial (no thread, no completion) +- Skips steps "for brevity" (reader gets stuck) +- Uses placeholders like `<your-value-here>` without making them concrete +- Assumes prior knowledge that wasn't stated as prerequisite +- Branches early ("if you want X, do this; if Y, do this") instead of staying focused + +### Template + +``` +# Getting started with [Thing] + +## What you'll build + +[1-2 sentences describing the end state. Maybe a screenshot or example output.] + +## Time required + +[Realistic estimate, e.g. "30-45 minutes"] + +## Before you start + +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] + +## Step 1: [First milestone] + +[Plain-English description of what we're doing in this step.] + +[Concrete instructions:] + +``` +[Specific command] +``` + +[What you should see:] + +``` +[Expected output] +``` + +If something different happens, see [Troubleshooting section]. + +## Step 2: [Second milestone] + +[Same pattern.] + +## Step 3: [Third milestone] + +[Same pattern.] + +[...] + +## What you've built + +[Recap. The reader should feel: I get it now.] + +## Where to go next + +- [Next tutorial] +- [Reference for what you just used] +- [How-to for related task] + +## Troubleshooting + +[Specific problem someone might hit] + +[Cause and resolution.] +``` + +--- + +## How to use this in practice + +### When writing new docs + +Identify which type before starting. Don't mix. + +If a doc has tutorial sections AND reference sections AND explanation sections, it's three docs. Split. + +### When auditing existing docs + +For each existing doc, ask: which type is this trying to be? + +If it's mixed, split. The split is usually: keep the dominant type in the original, link to the other types. + +### When linking between types + +The four types reinforce each other: +- Tutorials link to reference for the things they introduce +- How-tos link to reference for the commands they use +- Reference links to explanation for the why +- Explanation links to how-to for "to do this, see..." + +A connected web of all four serves the reader well. + +### When choosing the type for a need + +\| Reader is asking \| Type \| +\|---\|---\| +\| "What does X mean?" \| Reference \| +\| "What's the syntax for X?" \| Reference \| +\| "How do I do Y?" \| How-to \| +\| "How do I solve [specific problem]?" \| How-to \| +\| "Why does Z work this way?" \| Explanation \| +\| "What did we decide about W?" \| Explanation (ADR) \| +\| "I'm new; where do I start?" \| Tutorial \| + +If the answer is "all of the above," the reader actually needs multiple docs, not one mega-doc. + +--- + +## Anti-patterns to recognize + +- The "everything" doc: tries to be all four types. Reads like all four poorly. +- The "guide" doc: vague title, vague purpose. Often a how-to that lost focus. +- The "manual" doc: monolithic. Unmaintainable. Split. +- The "wiki page that became sacred: historical accumulation. Past usefulness. Audit and split or archive. diff --git a/dist/pi/.agents/skills/domain-strategy/SKILL.md b/dist/pi/.agents/skills/domain-strategy/SKILL.md new file mode 100644 index 0000000..568e44d --- /dev/null +++ b/dist/pi/.agents/skills/domain-strategy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: domain-strategy +description: "Plan, manage, and optimize a domain portfolio. Use this skill for DNS architecture decisions, redirect strategies, registrar choice, parking unused domains, multi-site setups, and domain consolidation or split planning. Triggers on DNS, domain, registrar, redirect, parking, subdomain, apex, www vs non-www, multi-site, portfolio, hreflang setup, domain migration. Also triggers when planning a new site that needs domain decisions made before launch." +category: operations +catalog_summary: "DNS architecture, redirects, registrars, multi-domain portfolios" +display_order: 4 +--- + +# Domain Strategy + +Decide how domains, subdomains, and DNS work across a portfolio. Stack-agnostic. Works for one site or one hundred. + +--- + +## When to use + +- Setting up DNS for a new site (apex vs www, primary vs aliases) +- Choosing or switching registrars +- Planning redirects across multiple domains (parked, retired, consolidated) +- Deciding subdomain vs subfolder vs separate domain for a new product line +- Consolidating multiple sites into one +- Splitting one site into multiple +- Setting up DNS for email, security records, third-party services + +## When NOT to use + +- Migrating content between platforms with URL changes (use `content-migration`) +- Email authentication setup specifically (use `email-deliverability`) +- Security headers or HTTPS config (use `security-baseline`) +- Internationalization domain choices (use `internationalization`) + +--- + +## Required inputs + +- Current domain inventory (every domain you own or operate) +- Status of each (live, parked, redirected, retired) +- Strategic role of each (primary brand, sub-brand, defensive registration, campaign) +- Current DNS provider and registrar for each +- Email and third-party service dependencies + +--- + +## The framework: 5 decisions + +Every domain decision falls into one of these buckets. Address them in order. + +### Decision 1: Apex vs www as canonical + +Pick one. Redirect the other to it. Pick before launch. Changing later is painful. + +- Apex (example.com): cleaner, more memorable, the modern default. +- www (www.example.com): historically standard, easier to add CDN-level CNAME records (apex CNAME is technically forbidden but most providers offer ALIAS or ANAME). + +Whichever you pick, the other must 301 to it. Both serving content is duplicate content and a soft signal of poor setup. + +### Decision 2: Subdomain vs subfolder vs separate domain + +For a new product, blog, or content section: + +\| Pattern \| Use when \| +\|---\|---\| +\| Subfolder (`example.com/blog`) \| Same brand, want SEO equity to flow, default choice \| +\| Subdomain (`blog.example.com`) \| Different stack or platform, organizationally separate but related \| +\| Separate domain (`exampleblog.com`) \| Different brand, different audience, intentional separation \| + +Default to subfolder. The case for subdomain or separate domain has to be made. + +### Decision 3: Registrar strategy + +The registrar is where the domain is registered. The DNS provider is where DNS records live. They can be the same or different. + +Decisions: +- Single registrar vs multiple: single is simpler. Multiple makes sense for redundancy at scale. +- Lock and 2FA: non-negotiable. Domain hijacking is real and costly. +- Auto-renew: on for everything you care about. Off only for intentional drops. +- WHOIS privacy: on by default. Free at most modern registrars. +- Transfer lock: on except during planned transfers. + +### Decision 4: DNS provider + +The DNS provider controls how domains resolve. Critical for performance, reliability, and security. + +Pick a provider that gives you: +- Fast global resolution (anycast network) +- DNSSEC support +- API access for automation +- Reasonable record limits +- Good audit logs + +Default DNS records every domain needs: +- A or AAAA records (or CNAME) for the apex and www +- MX records (even just nullified if no email) +- TXT for domain verification, SPF +- CAA records (locks down which certificate authorities can issue certs for the domain) + +### Decision 5: Parked domain strategy + +Domains you own but aren't actively using. Three valid strategies: + +1. Redirect to a primary site. Best for defensively registered domains close to your main brand. 301 every path to the primary's homepage or matching path. +2. Hold blank. A simple page or DNS NXDOMAIN. Acceptable for domains you may use later. +3. Park with a landing page. Generic "coming soon" page. Lowest value. Avoid registrar default parking pages (often serve ads against your brand). + +Anti-pattern: letting parked domains serve duplicate or near-duplicate content from your main site. This is an SEO liability. + +--- + +## Workflow + +### Step 1: Inventory + +Pull every domain you own from every registrar. Build a single sheet: + +\| Domain \| Registrar \| DNS provider \| Status \| Role \| Renewal date \| Notes \| +\|---\|---\|---\|---\|---\|---\|---\| + +If you can't account for every domain, the strategy can't be accurate. + +### Step 2: Classify by role + +Each domain gets one role: +- Primary (the main site for a brand) +- Alias (redirects to a primary) +- Defensive (registered to prevent others from getting it; usually parked) +- Campaign (short-term, specific use) +- Retired (no longer active; either drop at expiry or redirect permanently) + +The classification drives the configuration. + +### Step 3: Audit current configuration + +For each domain check: +- Is the canonical (apex vs www) consistent with the strategy? +- Are redirects 301 (permanent) where intended? +- Is HTTPS enforced on every variant? +- Are DNS records minimal and intentional? +- Is the registrar locked? +- Is auto-renew on? +- Is 2FA on the registrar account? + +Document gaps. Each gap is a ticket. + +### Step 4: Set the canonical pattern + +For new domains and any that need fixing: + +- Pick apex or www as canonical +- Configure 301 redirect for the non-canonical +- Force HTTPS for both +- Verify with curl: `curl -I http://example.com`, `curl -I http://www.example.com`, `curl -I https://www.example.com`. All should chain to a single 200 on the canonical. + +### Step 5: Document the redirect map + +Across the portfolio, document every redirect: + +\| Source \| Destination \| Type \| Reason \| Date set \| +\|---\|---\|---\|---\|---\| + +This is invaluable when something breaks or when planning consolidations. + +### Step 6: Set up monitoring + +Monitor: +- DNS resolution (alert on NXDOMAIN or wrong IP) +- HTTPS certificate expiration (alert at 30, 14, 7 days out) +- Redirect chains (alert if a 301 starts returning 200 or 404) +- Renewal dates (alert at 90, 30, 7 days out) + +This is the bridge between domain strategy and `monitoring-and-alerting`. + +### Step 7: Document and revisit + +Domain strategy is a quarterly review topic. Renewals, consolidations, and new launches change the picture. Without scheduled review, the portfolio drifts. + +--- + +## Failure patterns + +Both apex and www serve content. Duplicate content. Pick one, redirect the other. + +302 redirects where 301 was intended. 302 is temporary. 301 is permanent. SEO equity passes through 301, not (reliably) through 302. + +HTTPS not enforced. HTTP variant serving content alongside HTTPS. Force HTTPS at the edge or the load balancer. + +Registrar default parking pages. Parked domains serving registrar ads. Free for the registrar, bad for you. Replace with a redirect or your own page. + +Domains in multiple registrars by accident. Migrations that didn't fully complete. Consolidate. + +No CAA records. Anyone with a misconfigured ACME client can issue a cert for your domain. CAA limits which CAs can issue. Add it. + +Auto-renew off "to save money." Domain accidentally drops, gets snapped up, costs ten times more (or is unrecoverable). Auto-renew is cheap insurance. + +Subdomains used where subfolders would have been better. SEO equity gets fragmented across hostnames. The case for a subdomain has to be made; the default is subfolder. + +Parked domains with thin content "for SEO." Search engines don't reward this. They penalize doorway pages. Either redirect or leave blank. + +--- + +## Output format + +A domain strategy document includes: + +- Inventory: the spreadsheet of every domain +- Classification: the role of each +- Canonical decisions: apex vs www, locked +- Redirect map: every redirect in the portfolio +- DNS standards: the default record set +- Registrar standards: locked, 2FA, auto-renew +- Monitoring: what's watched, where alerts go +- Renewal calendar: the next 12 months +- Review cadence: when this gets revisited + +--- + +## Reference files + +- [`references/dns-record-reference.md`](references/dns-record-reference.md): Common DNS records explained, with the syntax for the most useful ones (A, AAAA, CNAME, MX, TXT, CAA, SRV, etc.) and when each is needed. diff --git a/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md b/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md new file mode 100644 index 0000000..62edfff --- /dev/null +++ b/dist/pi/.agents/skills/domain-strategy/references/dns-record-reference.md @@ -0,0 +1,252 @@ +# DNS Record Reference + +A quick reference to the DNS records every domain operator should understand. Stack-agnostic. The syntax is the same across DNS providers. + +--- + +## Address records + +### A record + +Maps a name to an IPv4 address. + +``` +example.com. 300 IN A 192.0.2.1 +www.example.com. 300 IN A 192.0.2.1 +``` + +Use for the apex and any subdomain that resolves to a specific IPv4. + +### AAAA record + +Maps a name to an IPv6 address. + +``` +example.com. 300 IN AAAA 2001:db8::1 +``` + +If your infrastructure supports IPv6, set AAAA records alongside A records. Many ISPs prefer IPv6. + +### CNAME record + +Maps a name to another name (which must resolve to A or AAAA). + +``` +www.example.com. 300 IN CNAME example.com. +shop.example.com. 300 IN CNAME shopify-store.myshopify.com. +``` + +CNAME cannot be used at the apex (e.g., `example.com.` cannot be a CNAME). Most providers offer ALIAS or ANAME records as a workaround for apex. + +CNAME at a name conflicts with any other record at the same name. You can't have both a CNAME and an MX at the same name, for example. + +--- + +## Mail records + +### MX record + +Specifies mail servers for the domain. Priority is the first number; lower wins. + +``` +example.com. 300 IN MX 10 mx1.mailprovider.com. +example.com. 300 IN MX 20 mx2.mailprovider.com. +``` + +Even if the domain doesn't send or receive email, set a "null MX" to prevent spoofing: + +``` +example.com. 300 IN MX 0 . +``` + +This is the "this domain doesn't accept mail" signal, defined in RFC 7505. + +### TXT record (for SPF, DKIM, DMARC) + +TXT records hold arbitrary text. The most common use is email authentication. + +SPF (Sender Policy Framework): declares which servers can send mail for the domain. + +``` +example.com. 300 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +``` + +Only one SPF record per domain. Multiple SPF records break SPF entirely. + +DKIM (DomainKeys Identified Mail): publishes the public key for signing outgoing email. + +``` +selector1._domainkey.example.com. 300 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +The selector is set by your mail provider. Different providers use different selectors. + +DMARC (Domain-based Message Authentication): tells receivers what to do with mail that fails SPF or DKIM. + +``` +_dmarc.example.com. 300 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +``` + +Start with `p=none` for monitoring, then move to `p=quarantine` and finally `p=reject` once aligned. See `email-deliverability` skill for the full progression. + +--- + +## Security records + +### CAA record + +Certificate Authority Authorization. Restricts which CAs can issue certificates for the domain. + +``` +example.com. 300 IN CAA 0 issue "letsencrypt.org" +example.com. 300 IN CAA 0 issuewild "letsencrypt.org" +example.com. 300 IN CAA 0 iodef "mailto:security@example.com" +``` + +Without CAA, any public CA can issue a cert for your domain. With CAA, only the listed CAs can. Add CAA for any domain you care about. + +The `iodef` directive specifies where to email reports of unauthorized issuance attempts. + +### TLSA record + +Used with DNSSEC for DANE (DNS-based Authentication of Named Entities). Pins the TLS certificate or public key in DNS. + +``` +_443._tcp.example.com. 300 IN TLSA 3 1 1 abc123def456... +``` + +Niche. Most operators won't need TLSA. Useful for high-security applications. + +### DNSKEY, DS, RRSIG (DNSSEC) + +DNSSEC signs DNS responses cryptographically, preventing spoofing. Setup is provider-specific. Most modern DNS providers offer one-click DNSSEC. Enable it if available. + +--- + +## Service discovery + +### SRV record + +Specifies the location of services (priority, weight, port, target). + +``` +_sip._tcp.example.com. 300 IN SRV 10 60 5060 sip-server.example.com. +``` + +Used for SIP, XMPP, and similar. Most websites don't need SRV records. + +### NS record + +Specifies authoritative name servers for the domain (or a delegated subdomain). + +``` +example.com. 300 IN NS ns1.dns-provider.com. +example.com. 300 IN NS ns2.dns-provider.com. +``` + +NS records are usually managed by the registrar (for the apex) or by you (for delegated subdomains). + +### SOA record + +Start of Authority. Contains administrative info about the zone. + +``` +example.com. 300 IN SOA ns1.dns-provider.com. admin.example.com. 2024010101 7200 3600 1209600 300 +``` + +Auto-managed by most DNS providers. The serial number (2024010101) increments on every zone change. + +--- + +## TTL guidance + +TTL is how long a record can be cached by resolvers, in seconds. + +\| Record type \| Recommended TTL \| Reason \| +\|---\|---\|---\| +\| A, AAAA on stable infrastructure \| 3600 (1 hour) to 86400 (1 day) \| Reduces lookup load \| +\| A, AAAA during a migration \| 300 (5 min) \| Fast cutover \| +\| CNAME \| 3600 to 86400 \| Stable mappings \| +\| MX \| 86400 (1 day) \| Mail rarely changes \| +\| TXT (SPF, DMARC) \| 3600 \| Quick to update if needed \| +\| CAA \| 86400 \| Rarely changes \| + +Lower TTL during migrations. Raise it back after. + +--- + +## Common record patterns + +### A new website, single domain + +``` +example.com. 3600 IN A 192.0.2.1 +example.com. 3600 IN AAAA 2001:db8::1 +www.example.com. 3600 IN CNAME example.com. +example.com. 3600 IN MX 10 mx.mailprovider.com. +example.com. 3600 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +_dmarc.example.com. 3600 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +example.com. 86400 IN CAA 0 issue "letsencrypt.org" +example.com. 86400 IN CAA 0 iodef "mailto:security@example.com" +``` + +### A domain that doesn't send mail + +Same as above but replace MX records with the null MX: + +``` +example.com. 86400 IN MX 0 . +``` + +And the SPF can be: + +``` +example.com. 3600 IN TXT "v=spf1 -all" +``` + +### A redirect-only domain + +For a parked or alias domain that only redirects to a primary: + +``` +parked-example.com. 3600 IN A 192.0.2.10 +parked-example.com. 86400 IN MX 0 . +parked-example.com. 3600 IN TXT "v=spf1 -all" +parked-example.com. 86400 IN CAA 0 issue "letsencrypt.org" +``` + +The A record points to whatever serves the redirect. The null MX and SPF prevent the domain from being used for email spoofing. + +--- + +## Common mistakes + +Multiple SPF records. Only one SPF record per domain is allowed. Two or more break SPF entirely. To "include" multiple senders, combine them in a single `v=spf1` record. + +CNAME at the apex. Forbidden by the DNS spec. Use ALIAS or ANAME (provider-specific) or just use an A record. + +TTL too low long-term. Sub-300 TTLs cause unnecessary DNS query load. Use low TTLs only during migrations. + +Forgotten CAA record after switching CAs. If you switch from Let's Encrypt to another CA but the CAA record only lists Let's Encrypt, the new CA can't issue. Update CAA before issuing. + +No null MX on non-mail domains. Domain becomes a target for spoofing. Cheap to add the null MX. + +Manual records that should be provider-managed. Many providers manage records for their services automatically (e.g., Vercel, Cloudflare). Manual records can drift and conflict. + +--- + +## Tooling + +For testing DNS: +- `dig` (command line, the standard) +- `nslookup` (older but widespread) +- Online tools: dnschecker.org, mxtoolbox.com, intodns.com (good for sanity-checking a fresh setup) + +For testing email auth specifically: +- mail-tester.com +- dmarcian.com +- mxtoolbox.com (deliverability tab) + +For monitoring DNS in production: +- Most monitoring services include DNS checks (uptime providers, observability platforms) +- See `monitoring-and-alerting` skill for setting these up. diff --git a/dist/pi/.agents/skills/editorial-qa/SKILL.md b/dist/pi/.agents/skills/editorial-qa/SKILL.md new file mode 100644 index 0000000..0f99207 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/SKILL.md @@ -0,0 +1,334 @@ +--- +name: editorial-qa +description: "Pre-publish QA framework for content. Brief adherence, voice consistency, fact accuracy, structure and clarity, AI-content audit, SEO and AEO compliance, internal linking and schema validation, QA at scale via sampling, the QA workflow, and the discipline that distinguishes catch-problems QA from checkbox QA. Triggers on editorial QA, content review, pre-publish review, content audit, content QA process, AI-content audit, hallucination check, content sampling, programmatic QA, voice consistency check, brief adherence check. Also triggers when a content team is shipping sloppy work, when AI-co-authored content is reaching publish unaudited, when a QA process burns reviewers out, or when a programmatic SEO set needs sampling discipline." +category: content +catalog_summary: "Pre-publish QA framework: brief adherence, voice consistency, fact accuracy, AI-content audit, AEO/SEO compliance, sampling at scale, and the workflow that distinguishes catch-problems QA from process theater" +display_order: 7 +--- + +# Editorial QA + +A senior editor's playbook for pre-publish content QA. The discipline that catches problems BEFORE content ships, not after. + +Most content QA is broken in one of two directions. The thin version is "did I read it once and is the spelling OK," which catches typos but misses brief drift, voice inconsistency, hallucinated facts, AI tells, and structural problems that reach readers as "this is fine but not memorable." The thick version is a 47-item checklist that nobody completes honestly because it is process theater: checkboxes nobody actually believes catch problems. + +This skill is the discipline of catch-problems QA. Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Checks the production volume cannot sustain get redesigned (sampling instead of full audit, automated instead of manual). The QA framework is what is left when you remove the theater. + +The skill covers three production shapes: single editorial pieces (one at a time, full QA), AI-generated drafts (with the AI-content audit that did not exist as prominently 2 years ago), and programmatic SEO sets at scale (sampling discipline, threshold gating). Each needs its own QA shape; the underlying methodology composes across all three. + +When to use this skill: building a content QA process from scratch, auditing an existing QA process that ships sloppy work or burns out the team, designing QA gates for an AI-assisted workflow, or building sampling discipline for programmatic SEO sets. + +--- + +## What this skill is for + +This skill spans pre-publish quality control. It plugs in at the END of every other content skill's output. The six-skill content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. +- `content-brief-authoring` is per-piece scope: briefs each piece. +- `content-and-copy` is execution scope: writes each piece. +- `programmatic-seo` is scaled scope: generates many pages from data. +- This skill is gate scope: verifies before publish. + +Every skill above produces a draft. This skill is what gets drafts to publishable. It is the gate where quality is actually enforced. + +The audience: editorial leads, content directors, in-house content QA, agencies with production lines, content ops managers, anyone running a writer (human or AI) and accountable for what ships. The voice is senior editor to junior editor or content marketer. Specific, opinionated, honest about where QA earns its keep versus where it becomes process theater. + +--- + +## Catch-problems QA vs checkbox QA + +The keystone distinction. Two failure modes plus the discipline. + +Thin QA (typo-checking dressed as quality control). "I read it once, it is fine." Catches obvious mistakes; misses brief drift, voice inconsistency, hallucinated facts, structural problems, AI tells. Output: shipped content that is "fine but not memorable." Cost: invisible until a brand misstep, a hallucinated statistic, or a competitor's content compounds and the thin set falls behind. + +Thick QA (47-item checklist nobody completes honestly). Every conceivable check listed; no triage. Reviewers either skim and check boxes (theater) or burn out under the cognitive load. Output: shipped content slightly more polished than thin QA produces, but the team's review velocity collapses. Cost: throughput drops; reviewers leave; the checklist atrophies into a few checks that actually run. + +Catch-problems QA (the discipline). Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Production volume drives sampling versus full-audit decisions. Reviewers are accountable for what they caught, not for box-completion. + +The litmus test. If the team can name the last 3 problems each QA check caught, the check earns its keep. If a check has not caught anything in 6 months, it is theater. Cut it; reallocate the attention to checks that catch real problems. + +--- + +## Brief adherence check + +Did the writer execute the brief? The check is straightforward when the brief is well-authored (see `content-brief-authoring`). + +The brief-adherence checks: + +- Target keyword and cluster. Present in title, first paragraph, headings. +- Search intent and SERP format. Piece matches the dominant SERP format (article when SERP wants article, listicle when SERP wants listicle). +- Target audience. Piece reads as written FOR the named audience, not for a generic reader. +- Heading structure. Piece follows the H2 / H3 outline in the brief, or has a documented reason for deviation. +- Required entities. Every entity flagged in the brief appears in the piece. +- Internal links. Outbound links specified in the brief are present with the right anchor text. +- Anti-patterns. Piece avoids the off-limits language and structures named in the brief. +- Success criteria acknowledged. Piece is shaped to MEASURE against the success criteria. + +The brief-adherence check is the cheapest, fastest, highest-value QA gate. It runs first in the QA sequence because catching a brief-adherence failure early saves the editor from spending time on voice and structure on a piece that will need to restart. + +If briefs are vague, this check is impossible. Fix briefs first; the QA process cannot enforce a contract that does not exist. + +Detail in [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md). + +--- + +## Voice consistency check + +Does the piece sound like the brand? + +- Vocabulary. Brand-specific terms used correctly; off-brand terms absent. +- Sentence rhythm. Matches brand voice (short and punchy versus measured and layered versus colloquial). +- Stance. The piece takes positions consistent with brand POV. +- Register. Formal or casual matches the surface (blog versus whitepaper versus help doc). +- Voice drift in long pieces. 3,000-word pieces often start in brand voice and drift to generic by section 4. Sample paragraphs from start, middle, end. + +For AI-co-authored pieces, voice drift is the dominant failure mode. AI assistants regress to a model-default voice unless the writer actively pulls them back. The QA check needs to read for the brand voice as much as for the words. + +Detail in [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md). + +--- + +## Fact accuracy and citation discipline + +Every claim in the piece needs to be true. The check: + +- Statistics. Every number sourced or removed if no source. +- Quotes. Every quote attributed to a real person who actually said it. +- Case studies. Every example refers to a real company or scenario, or labeled clearly as hypothetical. +- Dates and timelines. Verified, not approximate. +- Named experts. Real people who consented to attribution. +- Product claims. Matches actual product behavior, not future-tense roadmap or marketing aspiration. + +Hallucination is the dominant failure mode in AI-assisted writing. AI assistants generate plausible statistics, plausible quotes, plausible case studies, none of which are real. The fact-accuracy check is the gate that catches them. If you skip this gate on AI-generated content, you ship hallucinations. + +Citation discipline: + +- Inline citations link to authoritative sources (academic papers, industry reports, primary sources). +- Avoid citing other content marketing pages (citation laundering). +- Date the source; sources older than 3 years for fast-moving topics need refresh. + +Detail in [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md). + +--- + +## Structure and clarity check + +Does the piece work as a piece? + +- Lede. First 200 words answer the user's likely query (for SEO/AEO pieces) OR establish the thesis (for thought leadership). +- Sectioning. H2s map to user mental model, not writer enthusiasm. +- Section length. Even-ish across H2s. One massive section plus four 80-word sections signals broken structure. +- Reading flow. Paragraphs connect, sentences vary in length. +- Specificity vs abstraction. Claims are concrete, not vague. +- Endings. Piece concludes with something specific (action, question, idea), not throat-clearing filler. + +Detail in [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md). + +--- + +## AI-content audit + +The QA check that did not exist as prominently 2 years ago. AI-co-authored content has detectable patterns even when written by a competent human editor. + +AI tells (pattern recognition). + +- Excessive em-dashes (model-default punctuation) +- Predictable opening phrasings (throat-clearing openers that announce what the piece is about to do; the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener) +- Predictable concluding paragraphs (throat-clearing wrap-ups, "By following these steps") +- Bullet-list overuse where prose would serve +- "On the other hand" / "However" overuse +- Forced bilateral framing (always "two sides" even when one side is right) +- Sentence-end filler ("...and more.", "...among other things.", "...for example.") +- Repetitive sentence-rhythm (every paragraph 2-3 sentences, similar lengths) +- Generic openings (descriptive paragraphs that could open any article on the topic) +- Bridging fluff ("That said", "With that in mind", "Moving on") +- Hedge stacking ("typically", "generally", "often") on claims that should be specific + +Hallucination patterns (factual errors). + +- Statistics that look authoritative (specific decimal places, named source) but the source does not exist or does not say that +- Quotes attributed to real people who did not say it +- Case studies about companies that do not exist +- Citations to URLs that 404 or never existed +- "Studies show" claims with no actual study behind them +- Made-up product features + +Voice drift. + +- Piece starts in brand voice, drifts to generic by section 4 +- Vocabulary regresses to model defaults +- Stance becomes diplomatic ("there are good arguments on all sides") when brand stance was clear + +The audit shape. Read with these patterns top-of-mind. Flag any match. The bar is not "AI was used" (it almost always is now); the bar is "would a careful human editor have shipped this." If the patterns above are present, the piece needs another revision pass with the patterns called out. + +Detail in [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md). + +--- + +## SEO and AEO compliance check + +Does the piece serve search engines AND answer engines? + +SEO checks. + +- Target keyword in title, H1, first paragraph, slug +- Heading hierarchy clean (no orphan H3s, no H4 without H3) +- Image alt text descriptive +- Meta description compelling and keyword-aware +- Internal links specified in brief are present +- External links open in new tab (typically) and have rel attributes appropriate +- URL slug short and descriptive + +AEO checks. + +- 40 to 60 word answer paragraph immediately following each H2 question +- TL;DR section present (for pillar pieces) +- FAQ section with FAQPage schema (for pieces where Q and A format applies) +- Specific statistics with cited sources (AI engines weight statistics with sources) +- Named entities (experts, methods, tools) consistently mentioned (entity coverage signals) +- Distinctive POV that is attributable to the brand + +Detail in [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md). + +--- + +## Internal linking and schema validation + +Internal linking. + +- Outbound links specified in brief are present with correct anchor text +- Anchor text varies (avoid every link being "click here" or every link being the exact-match target keyword) +- Link targets are live (no 404s, no links to deprecated pages) +- Internal link count appropriate to length (3 to 7 for typical 1,500-word piece, 8 to 15 for pillars) +- Self-cannibalization check: piece does not compete with existing pieces for same target keyword + +Schema validation. + +- Article schema present on most pieces; HowTo schema on instructional pieces; FAQPage schema where Q and A applies +- Schema validates against schema.org definitions (no missing required fields, no malformed JSON-LD) +- Schema is consistent with on-page content (do not claim 5-star rating in schema if no rating on page) + +Detail in [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md). + +--- + +## QA at scale + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. Sampling discipline replaces it. + +Sampling strategy. + +- Random sample 50 to 200 pages per audit cycle +- Balance the sample across data shape (sparse versus dense records, recent versus old generation, popular versus niche categories) +- Fixed sample percentage as set grows; absolute count plateaus around 200 once the set is large + +Automated checks at scale. + +- Heading structure validation +- Schema markup validation +- Word count (flag pages below the floor, e.g. 600 words) +- Duplicate content check (compare each page against the rest of the set) +- Broken-link check +- Image-presence check (where templates expect images) + +Manual checks on sampled pages. + +- Brief-adherence equivalent (template-adherence check: does the page execute the template?) +- Top-200-word answer quality +- Whether the page would satisfy a human user's likely query +- Whether the page reads as distinctive versus templated +- Spot-check for AI hallucination if AI was in the loop + +Threshold gating. + +- If more than 5% of sampled pages fail the manual review, halt new generation +- Fix the template OR data quality issue before resuming +- Document the threshold breach in the QA log so patterns become visible + +Detail in [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md). + +--- + +## The QA workflow + +Ownership and sequencing. + +Single QA owner per piece, not a committee. The owner is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +Sequencing. Brief-adherence, then fact-accuracy, then structure, then AI-content audit, then voice, then SEO/AEO, then internal linking, then schema. Brief-adherence first because it is the cheapest gate; SEO/AEO checks last because they are easiest to fix and rarely halt-conditions. + +Halt vs flag vs auto-fix. + +- Brief-adherence and fact-accuracy can HALT (return to writer). +- Voice and structure FLAG with suggestions; editor judgment decides whether to halt or revise inline. +- SEO/AEO and schema typically auto-fix (slug, meta description, schema markup are mechanical edits the editor or a script can ship without writer involvement). + +Escalation. When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +Detail in [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-qa-failures.md`](references/common-qa-failures.md). + +- "Our QA process is a 47-item checklist nobody completes." Checkbox theater; cut to the checks that earned their keep. +- "We caught zero problems in QA last quarter." Either the process is broken or the writers are extraordinary; investigate. +- "Editor and writer disagree on voice." Voice guidelines are vague; document brand voice with concrete examples. +- "AI hallucinations made it to publish." Fact-accuracy gate skipped or rushed; reinstate as halt-condition. +- "Our pSEO set is shipping thin pages." Sampling discipline missing or thresholds not honored. +- "QA takes longer than the writing." Wrong sequencing; brief-adherence early catches problems before voice/structure investment. +- "Reviewers burn out." Checks that do not catch problems are taxing reviewer attention; cut them. +- "Voice drifts halfway through long pieces." Sample mid-piece paragraphs, not just open and close. +- "We never go back to evaluate." QA log archives feed pattern detection; quarterly review. +- "Different editors apply different standards." Calibration sessions where editors review the same piece independently and reconcile. +- "We ship and discover problems on social." QA was not catching the problem class that is reaching readers; add a check for that class. + +--- + +## The framework: 12 considerations for editorial QA + +When designing or auditing a QA process, walk these 12 considerations. + +1. Catch-problems vs checkbox. Every check earns its keep by catching a class of failure. +2. Brief-adherence first. Cheapest, fastest, highest-value gate. +3. Fact-accuracy as halt-condition. AI hallucinations do not ship to readers. +4. Voice consistency including mid-piece sampling. Long pieces drift; sample throughout. +5. AI-content audit. Pattern recognition for AI tells, hallucinations, voice drift. +6. Structure and clarity. Lede, sectioning, even-ish length, specific endings. +7. SEO and AEO compliance. Answer paragraphs, schema, entity coverage. +8. Internal linking and schema validation. Outbound links live, anchor text varies, schema validates. +9. Sampling at scale. Programmatic and high-volume sets need sampling, not full-audit. +10. Threshold gating. Failure rate above threshold halts generation; document breaches. +11. Single QA owner per piece. Accountability not diffused across committee. +12. Sequencing. Brief-adherence to fact-accuracy to structure to AI-audit to voice to SEO/AEO to linking to schema. + +The output of the framework is a QA process the team can run repeatably: each check named, each owner named, each halt-condition documented, each sampling rule specified for programmatic surfaces. + +--- + +## Reference files + +- [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md) - Every brief field as a QA check, with how to verify and what failure looks like. +- [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md) - Vocabulary, rhythm, stance, register, mid-piece sampling discipline for long pieces. +- [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md) - Verification methodology, hallucination detection, citation rules, source-age guidelines. +- [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md) - Lede patterns, sectioning principles, endings, structural anti-patterns. +- [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md) - 11 AI tells, 6 hallucination patterns, voice drift detection, worked example with revision. +- [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md) - SEO and AEO checks combined into one workflow. +- [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md) - Link discipline, anchor text variation, schema patterns and validation. +- [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md) - Sampling strategy, automated checks, manual review at scale, threshold gating. +- [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md) - Ownership, sequencing, halt versus flag versus auto-fix, escalation patterns. +- [`references/common-qa-failures.md`](references/common-qa-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: QA is where quality gets enforced + +Every other skill in the content suite produces drafts. QA is the discipline that turns drafts into publishable work. It is also where every previous decision (brief shape, voice guidelines, hub architecture, programmatic template) gets tested against actual output. Skipping QA is not "moving fast"; it is shipping the failure modes of every upstream decision unfiltered. + +The QA process is the immune system of the content program: invisible when it is working, catastrophic in its absence. + +When in doubt about whether a QA process is ready, ask: does each check name a class of failure it catches, has each check actually caught something in the last 6 months, is brief-adherence first in the sequence, is fact-accuracy a halt-condition, is the AI-content audit included, does sampling discipline apply to scaled surfaces? If yes to all of those, the process is real. If no to any, the gap is where readers will encounter the failure that QA did not catch. diff --git a/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md new file mode 100644 index 0000000..57337e9 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/ai-content-audit-patterns.md @@ -0,0 +1,119 @@ +# AI-content audit patterns + +The 11 AI tells, the 6 hallucination patterns, voice drift detection, a worked example. The QA check that did not exist as prominently 2 years ago and is now load-bearing for any program with AI in the loop. + +--- + +## The 11 AI tells + +Pattern recognition. Read with these top-of-mind; flag any match. + +1. Excessive em-dashes. Model-default punctuation. A piece with 8 em-dashes per 1,000 words is almost certainly AI-drafted. The fix: replace with periods, semicolons, or rephrase the sentence. + +2. Predictable opening phrasings. Throat-clearing openers that announce what the piece is about to do (the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener). These openings appear in AI output across topics; pattern-match against the team's curated do-not-use list and cut. + +3. Predictable concluding paragraphs. Throat-clearing wrap-ups. "By following these steps." "By implementing these strategies." "Now you have a comprehensive understanding of." All cut. + +4. Bullet-list overuse. AI defaults to bullets when prose would serve. Bullets fragment reading flow and signal AI drafting. Convert to prose where prose makes the connection between items clearer. + +5. "On the other hand" / "However" overuse. Forced bilateral framing pattern. Used 4+ times in 1,500 words is the AI tell. + +6. Forced bilateral framing. "While X has its advantages, Y also has merits." Always two sides given equal weight even when one side is right. The fix: pick a position; defend it; let the contrary view get one short acknowledgment. + +7. Sentence-end filler. "...and more." "...among other things." "...for example." All padding. Cut. + +8. Repetitive sentence-rhythm. Every paragraph 2 or 3 sentences of similar length. Read aloud: monotonous. The fix: deliberate variation in sentence length and paragraph shape. + +9. Generic openings. Descriptive paragraphs that could open any article on the topic. "Customer experience is more important than ever in today's competitive landscape." Cut; replace with a specific opening tied to the piece's thesis or the reader's specific query. + +10. Bridging fluff. "That said." "With that in mind." "Moving on." Throat-clearing transitions; cut. + +11. Hedge stacking. "Typically," "generally," "often" stacked on claims that should be specific. AI hedges to avoid being wrong; the result is content that says nothing definite. Replace hedges with specifics or cut the hedge. + +--- + +## The 6 hallucination patterns + +Factual errors that AI assistants generate and how to detect each. + +1. Specific decimal places, named source, source does not exist. "According to a 2024 Forrester report, 67.3% of B2B buyers..." The decimal place plus named source is the AI tell. Detection: search the source. If it does not exist or does not say that, cut the claim. + +2. Quotes attributed to real people the person did not say. "As Marc Benioff said in his 2024 keynote..." Plausible because Benioff gives keynotes. Detection: search for the quote in actual transcripts; verify against original source. If the quote does not match a real source, cut. + +3. Case studies about companies that do not exist. "Acme Innovations reduced their cycle time 40% using..." Detection: search the company name. If it does not appear in business directories, news coverage, or LinkedIn, the case study is fake. + +4. Citations to URLs that 404 or never existed. Detection: click every external link. 404s and dead links are signals; multiple dead links signal multiple unverified claims. + +5. "Studies show" claims with no actual study. "Studies show that 45% of marketers..." with no link, no journal, no year. Detection: ask for the study. If the writer cannot produce it, cut the claim. + +6. Made-up product features. "Product X now supports automatic Y" when the product does not. Detection: verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Voice drift detection + +The mid-piece drift pattern in AI-co-authored content. + +The pattern. Piece starts in brand voice (because the writer set up the opening prompt with brand voice cues). By section 4, the voice has drifted to model-default. The drift is gradual; the start and end pass voice review while the middle fails. + +Detection methodology. + +1. Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. +2. Compare each sample to the brand voice doc's vocabulary, rhythm, stance, register. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. + +The fix. Send back with the drifted sections highlighted. Specific note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes from the voice doc]." + +--- + +## Worked example: AI tells in a 4-paragraph excerpt + +Original AI-drafted excerpt (with AI tells in bold for the audit): + +> In today's fast-paced digital landscape, content marketing has become more important than ever. Whether you're a small business owner or a Fortune 500 executive, understanding the nuances of effective content strategy is crucial for success. +> +> There are many factors to consider when developing a content strategy. On one hand, you need to focus on creating high-quality content that resonates with your audience. On the other hand, you also need to ensure that your content is optimized for search engines, social media platforms, and more. +> +> It's important to note that successful content marketing requires a balance between creativity and analytics. Studies show that companies that prioritize data-driven decision-making see significant improvements in their content performance metrics. +> +> By following these steps, you'll be well on your way to creating a content strategy that drives results. Remember that consistency is key, and that great content takes time to produce. + +The audit tags 9 AI tells in 4 paragraphs (more than 2 per paragraph). + +Revised excerpt (AI tells removed, voice tightened, specifics added): + +> Content marketing produces results when the strategy answers two questions: who are we writing for, and what do they need to do after reading. The B2B SaaS team writing for senior data engineers asks different questions than the consumer brand writing for first-time buyers. Both work; conflating them does not. +> +> The trade-off most teams get wrong is craft against measurement. Pieces optimized for search rankings often read as templated; pieces optimized for craft often miss the structural patterns that earn rankings. The fix is not balance; it is sequencing. Brief the structural patterns first; write to craft within them. +> +> Companies that ship measurable content programs share three patterns: a brief discipline that survives writer changes, a voice doc specific enough to enforce, and a fact-check gate that does not compromise under deadline pressure. Companies that miss any of the three produce inconsistent output regardless of writer talent. +> +> The next step is auditing your current process against those three patterns. If the brief is vague, fix the brief. If the voice doc is aspirational, tighten it with concrete examples. If the fact-check gate is optional, make it a halt-condition. + +The revision removed AI tells, added specifics (the two audience examples, the three patterns), and replaced the closing throat-clearing with a concrete next-step. + +--- + +## The audit checklist + +For each AI-co-authored draft, walk this checklist. + +1. Read the first 200 words. Does the opening match any of the 11 AI tells? Flag. +2. Sample 2 paragraphs from the middle. Does either match AI tells? Does the voice match the brand voice doc? Flag. +3. Read the last 200 words. Does the closing match any of the 11 AI tells? Flag. +4. Search the piece for em-dashes; count. More than 5 in a 1,500-word piece is suspicious. +5. Search for forced bilateral framing patterns. Count. +6. Verify every statistic, quote, case study, citation, and product claim per the fact-accuracy methodology. +7. Sample 3 to 5 internal links; verify they go where the brief specified and the targets exist. + +If 3+ items flag, halt the piece and return for revision with the specific items called out. + +--- + +## Methodology-level choices that stay in the public skill + +The 11 AI tells, the 6 hallucination patterns, voice drift detection methodology, the worked example revision pattern, the 7-step audit checklist. + +## Implementation choices that stay internal + +The specific tooling for automated AI-tell detection (regex patterns, classifier models, prompt-based audits). The specific brand voice doc that drives voice-drift comparison. The specific archive of past AI-tell catches that informs ongoing pattern recognition. The specific revision workflow when AI tells are detected (writer's editing tool, AI assistant configured for revision-not-drafting, human-only revision). These vary by team and tooling preferences. diff --git a/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md b/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md new file mode 100644 index 0000000..3f711e9 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/brief-adherence-checklist.md @@ -0,0 +1,137 @@ +# Brief adherence checklist + +Every brief field as a QA check, with how to verify and what failure looks like. + +The brief-adherence check is the first QA gate in sequence. It is the cheapest gate to run and the highest-value gate to pass: catching a brief-adherence failure early saves the editor from spending review time on voice, structure, and fact-accuracy on a piece that will need to restart. + +This check assumes the brief was authored under the discipline of `content-brief-authoring`. If briefs are vague or thin, fix briefs first; the brief-adherence check enforces a contract that has to exist. + +--- + +## The checklist + +For each piece, walk these 8 fields. + +### 1. Target keyword and cluster + +Verify. Pull the brief's primary keyword and 3 to 5 supporting cluster keywords. Search the piece for each. + +Pass. Primary keyword appears in title, H1 (if separate), first paragraph, and at least one H2. Supporting keywords appear naturally across the piece without stuffing. + +Fail patterns. + +- Primary keyword missing from title or first paragraph +- Cluster keywords absent (piece read like a generic article on the topic) +- Keyword stuffing: same exact-match phrase repeated 8+ times in 1,500 words + +### 2. Search intent and SERP format + +Verify. Pull the brief's intent classification and dominant SERP format. Compare to the piece's shape. + +Pass. Piece shape matches the format the brief specified: long-form article when SERP wants long-form, listicle when SERP wants listicle, comparison when SERP wants comparison. + +Fail patterns. + +- Brief specified listicle; piece is long-form prose +- Brief specified commercial-investigation intent; piece reads as informational with no purchase decision support +- Brief flagged the SERP intent override; piece ignored the override + +### 3. Target audience + +Verify. Read the first 200 words and the closing 200 words with the brief's audience description in mind. + +Pass. Piece reads as written FOR the named audience: vocabulary, examples, and assumed knowledge match the audience's level. + +Fail patterns. + +- Brief specified senior data engineers; piece explains "what is a database" in the introduction +- Brief specified non-technical CMOs; piece uses unexplained jargon +- Piece reads as written for a generic reader rather than the named audience + +### 4. Heading structure + +Verify. Compare the piece's H2 / H3 outline to the brief's specified outline. + +Pass. Piece follows the brief's outline. Where the writer deviated, the brief's deviation note explains why or the writer's first-draft note flags the deviation for editor review. + +Fail patterns. + +- Brief specified 6 H2s; piece has 4 or 9 with no documented reason +- H2 order changed without explanation +- Sections from the outline missing entirely + +### 5. Required entities + +Verify. Pull the brief's required-entity list. Search the piece for each. + +Pass. Every required entity appears in the piece, ideally in the section the brief specified. Standard entities are covered. Gap entities (the differentiation opportunity) are present where the brief committed to them. + +Fail patterns. + +- Brief required mentioning CUPED in the methodology section; CUPED is not in the piece +- Required entities mentioned in passing once each; depth-of-coverage requirements not met +- Gap entities skipped because they were "optional" (they were not; the brief committed to them) + +### 6. Internal links + +Verify. Pull the brief's outbound internal-link list with anchor text. Check the piece for each link. + +Pass. Every required outbound link is present with the specified anchor text. Optional outbound links are either present or noted as skipped with reason. + +Fail patterns. + +- Brief specified 4 required outbound links; piece has 2 +- Anchor text differs from the specified anchor text without reason +- Links to deprecated pages (the writer copied old anchor links from a stale draft) + +### 7. Anti-patterns + +Verify. Pull the brief's anti-pattern list. Read the piece looking for each pattern. + +Pass. Piece avoids every named anti-pattern. The do-not-use word list, off-brand voice, off-topic tangents, AI clichés, and structural patterns the brief explicitly forbade are absent. + +Fail patterns. + +- Anti-pattern words from the do-not-use list present (e.g., the writer slipped into corporate-speak adjectives) +- Off-topic tangents the brief warned against (the writer wandered into adjacent facets the cluster covers separately) +- Voice drifted toward a register the brief excluded + +### 8. Success criteria acknowledged + +Verify. Read the piece with the brief's success criteria in mind. Does the piece's shape support the criteria? + +Pass. Piece is shaped to MEASURE against the success criteria: ranking-targeted pieces have keyword-aware structure, citation-targeted pieces have answer paragraphs and statistics, conversion-targeted pieces have CTAs and decision-support content. + +Fail patterns. + +- Brief said "rank top 10 for [keyword]"; piece misses the structural patterns that earn ranking (no answer paragraphs, no entity coverage, no internal-link plan) +- Brief said "drive 50 trial signups in 30 days"; piece has no clear CTA path to signup +- Success criteria treated as an afterthought rather than a design parameter + +--- + +## What halt-condition looks like + +Brief-adherence failures are halt-conditions: return the piece to the writer with the specific failures named. + +The return note is short. "This piece misses the brief in 3 places: [field 1], [field 2], [field 3]. The brief specified [X]; the piece does [Y]. Please revise and return for round 2." + +Editors who try to fix brief-adherence failures themselves end up rewriting the piece. Better to halt cleanly, return to the writer, and let the writer execute the contract that already existed in the brief. + +--- + +## When briefs are too vague to enforce + +Sometimes the brief itself is the problem. The brief specified "engineers" without naming the seniority level. The brief specified "informational intent" without checking the SERP. The brief specified entities without depth-of-coverage requirements. + +When the brief is too vague, brief-adherence cannot enforce anything. The fix is upstream: tighten brief authoring discipline (see `content-brief-authoring`). The brief is the contract; vague contracts produce vague output regardless of writer skill. + +--- + +## Methodology-level choices that stay in the public skill + +The 8-field checklist, the halt-condition discipline, the upstream-fix observation when briefs are vague. + +## Implementation choices that stay internal + +The specific format the team uses for return notes (Slack message template, Notion row, ticketing system field structure). The specific tooling that stores brief metadata for diff-checking against pieces. The specific automation (if any) that surfaces brief-adherence failures before manual review. These vary by team and stack. diff --git a/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md b/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md new file mode 100644 index 0000000..9f97eac --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/common-qa-failures.md @@ -0,0 +1,168 @@ +# Common QA failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: QA either drifted into theater (checks that do not catch problems but cost reviewer attention) or skipped the gates that catch the problems readers actually encounter. The fix is upstream: cut theater checks, reinstate gates that actually catch problems. + +--- + +## "Our QA process is a 47-item checklist nobody completes" + +Symptom. The checklist exists. Nobody completes it honestly. Reviewers either skim and check boxes or burn out under the cognitive load. + +Diagnosis. Checkbox theater. The checklist accumulated over time as new failures appeared and got added; nothing was ever removed. The list grew past what reviewer attention can sustain. + +Fix. Audit the checklist. For each item, ask: when did this last catch a problem? If the answer is "never" or "more than 6 months ago," cut it. The remaining items are the catch-problems checks; the cut items were theater. + +Prevention. Quarterly review of the checklist. Each new check earns its keep by catching at least one problem within 90 days; checks that do not catch problems get cut. + +--- + +## "We caught zero problems in QA last quarter" + +Symptom. No QA returns. No halt-conditions. No revision rounds. Pieces ship clean every time. + +Diagnosis. Either the writers are extraordinary or the process is broken. Almost always the latter. + +Fix. Audit recently-shipped pieces independently of the original QA. Find the problems QA missed: hallucinated statistics, voice drift in long pieces, broken links, schema validation failures. Document each. Reinstate the QA gate that should have caught the failure. + +The pattern. When QA catches nothing for a quarter, reviewers have stopped reading carefully. The fix is not "trust the writers"; it is reinstating the discipline that was nominally still running. + +--- + +## "Editor and writer disagree on voice" + +Symptom. Editor returns the piece with voice notes; writer pushes back; edits go back and forth without convergence. + +Diagnosis. Voice guidelines are vague. Both editor and writer are interpreting the brand voice doc differently because the doc does not specify enough. + +Fix. Update the voice doc with concrete examples of the disputed dimension. If the dispute was about sentence rhythm, add 5 paired examples (the rhythm we want, the rhythm we do not want). The voice doc gets sharper; future disputes resolve by reference to the examples. + +Prevention. Quarterly voice calibration sessions (see `voice-consistency-patterns.md`) where editors review the same piece independently and reconcile. + +--- + +## "AI hallucinations made it to publish" + +Symptom. A statistic, quote, citation, or product claim in a published piece turns out to be invented. Reader (or competitor) flags it. + +Diagnosis. The fact-accuracy gate was skipped or rushed. + +Fix. Two parts. + +- Immediate: correct the published piece, document the failure in the QA log. +- Process: reinstate fact-accuracy as a halt-condition. AI hallucinations do not progress past this gate. If the gate is too slow, automate the easy parts (named-entity extraction, statistic detection) so manual verification focuses on the hard parts. + +Prevention. Fact-accuracy gate runs second in the QA sequence (after brief-adherence). Detail in `fact-accuracy-and-citation-discipline.md`. + +--- + +## "Our pSEO set is shipping thin pages" + +Symptom. Programmatic pSEO set is producing pages with insufficient data; pages render at 200 to 400 words of templated boilerplate; algorithm risk compounds. + +Diagnosis. Sampling discipline missing or thresholds not honored. The set was generating pages without QC checking the quality at the data-shape level. + +Fix. Implement the sampling discipline (see `qa-at-scale-patterns.md`). Set the 5% failure threshold; halt new generation when breached. Audit the existing set; noindex or remove pages below the data depth threshold. + +Prevention. Sampling and threshold gating built into the program at design time, not retrofitted. + +--- + +## "QA takes longer than the writing" + +Symptom. The team's writers ship drafts in 4 hours; QA cycle takes 6 hours. The bottleneck is review. + +Diagnosis. Wrong sequencing. The team is running expensive checks (voice, structure) before cheap checks (brief-adherence, fact-accuracy). When a piece fails at gate 1, the time spent on gates 5 to 8 is wasted. + +Fix. Reorder the sequence. Brief-adherence first; fact-accuracy second; halt-conditions short-circuit the rest of the gates. Voice and SEO checks last because they are easiest to fix and rarely halt-conditions. + +Prevention. The sequencing discipline is documented in `qa-workflow-templates.md`; new editors get the sequence in their onboarding. + +--- + +## "Reviewers burn out" + +Symptom. Editors who used to review carefully now skim. The catch rate drops. Editors leave the team. + +Diagnosis. The QA load exceeds reviewer capacity. Often because checks that do not catch problems are taxing reviewer attention. + +Fix. Cut theater checks (the same fix as the 47-item checklist failure). Burn-out reduces with the cognitive load. + +Also. Verify that production volume matches reviewer capacity. If the team is shipping 30 pieces a week with 1 editor, the volume is wrong. Either reduce volume, add reviewers, or accept lower quality with eyes open. + +--- + +## "Voice drifts halfway through long pieces" + +Symptom. 3,000-word pillar pieces start in brand voice; by section 4 they read generic. + +Diagnosis. Voice review only sampled the start and end. Mid-piece drift went undetected. + +Fix. Mid-piece sampling discipline (see `voice-consistency-patterns.md`). Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. AI-co-authored pieces especially need this. + +Prevention. Voice review template explicitly requires mid-piece sampling. + +--- + +## "We never go back to evaluate" + +Symptom. QA process exists. QA log accumulates. Nobody reviews the log. + +Diagnosis. The log is an artifact, not a feedback mechanism. Patterns the log surfaces never reach the editorial process owner. + +Fix. Quarterly QA log review. The owner reads the log; pattern observations get translated into process changes (brief tweaks, writer feedback, workflow adjustments, automation additions). + +Prevention. The quarterly review is calendar-anchored. Skipping it is the failure mode. + +--- + +## "Different editors apply different standards" + +Symptom. A piece shipped under editor A would be returned under editor B (or vice versa). Writers receive inconsistent feedback. Quality varies by which editor caught the piece. + +Diagnosis. Voice and structural standards have drifted between editors. Without calibration, individual editors apply individual taste. + +Fix. Calibration sessions. Three editors review the same piece independently; the team reads the three assessments together and reconciles. The consensus updates the voice doc and the QA process; future reviews stay consistent. + +Prevention. Calibration sessions quarterly minimum. Onboarding new editors includes a calibration round before they review live pieces solo. + +--- + +## "We ship and discover problems on social" + +Symptom. Readers (or competitors, or critics on social) flag problems that QA did not catch. + +Diagnosis. QA was not catching the problem class that is reaching readers. The class might be hallucinations, voice drift, structural problems, factual errors, or off-brand tone. + +Fix. Identify the class of failure that reached readers. Add a QA check that catches that class. Document the addition in the QA log so the pattern becomes visible. + +Prevention. The QA process evolves with feedback from shipped pieces. New failure classes that reach readers feed new QA checks. + +--- + +## "AI tells slipped through" + +Symptom. Published piece reads as AI-generated despite a human editor reviewing it. Readers or AI-detection tools flag it. + +Diagnosis. The AI-content audit either was not run or ran without the pattern recognition the editor needed. + +Fix. Add the AI-content audit as a named gate in the QA sequence (see `ai-content-audit-patterns.md`). Train the editor on the 11 AI tells; provide the worked example as reference. The audit becomes a 5-minute discipline rather than an unstructured "does this read OK" check. + +Prevention. Every AI-co-authored piece runs through the audit. The audit is a named gate, not an implicit step. + +--- + +## The pattern across most failures + +Most QA failures are designed-in. The process either drifted into theater (cuts needed) or skipped gates that should have been there (gates needed). The discipline is upstream: design the QA process around catch-problems, not around process appearance, and the operational discipline at scale becomes manageable. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the prevention guidance, the upstream-discipline observation. + +## Implementation choices that stay internal + +The specific QA log format and tooling. The specific calibration session cadence and team composition. The specific automation that supports each gate (statistic detection, hallucination flagging, schema validation, link audit). The specific escalation pathways within the team's structure. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md b/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md new file mode 100644 index 0000000..17d8d83 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md @@ -0,0 +1,113 @@ +# Fact accuracy and citation discipline + +Verification methodology, hallucination detection, citation rules, source-age guidelines. + +Fact accuracy is a halt-condition QA gate. Hallucinations from AI-assisted writing reach readers if the gate is skipped or rushed. The discipline below is what makes the gate work at production speed without becoming the bottleneck. + +--- + +## What gets fact-checked + +Every claim that could be wrong. The categories. + +Statistics. Every number in the piece needs a source. "23% of feature flag rollouts include a kill switch" needs a source link to the survey, report, or dataset that produced the 23%. Without a source, the number is either removed or replaced with sourced equivalent. + +Quotes. Every quote attributed to a real person needs verification: the person said it, the quote is verbatim or correctly paraphrased, the attribution is accurate, the person consents to attribution. + +Case studies. Every example refers to a real company or scenario, OR is labeled clearly as hypothetical. "Acme Corp reduced churn by 40% using this method" needs verification that Acme exists, the method was used, the 40% is real. If the example is hypothetical, the piece labels it: "Imagine a SaaS company..." + +Dates and timelines. Verified, not approximate. "Google launched feature X in March 2025" needs verification of the exact month and year. + +Named experts. Real people who consented to being attributed. The piece should not attribute claims to "Ronny Kohavi" without verifying the attribution traces to actual published work or direct consent. + +Product claims. Match actual product behavior. The product does what the piece says it does, in the way the piece says it does, today, in production. Future-tense roadmap items get clearly labeled as roadmap; marketing aspirations get cut. + +--- + +## The verification methodology + +For each claim in the piece, the editor follows one of three paths. + +Path 1: in-line citation present. Click through the citation. Does the source exist? Does the source actually say the claimed thing? Is the source the original (not a citation-of-citation)? + +Path 2: claim has no citation but is a known fact. Editor verifies via authoritative source (academic paper, primary government data, official company announcement). Add the citation; do not let the piece ship with uncited claims. + +Path 3: claim has no citation and is not a known fact. Halt. Return to writer with the claim flagged. Either the writer adds verification, or the claim gets removed. + +The discipline. No claim ships without verification. "I'm pretty sure I read this somewhere" is not verification. + +--- + +## Hallucination detection + +AI-assisted writing produces plausible-but-fake claims at scale. The patterns to recognize. + +Pattern 1: specific decimal places, named source, source does not exist. "According to a 2024 Forrester report, 67.3% of B2B buyers prefer..." Sounds authoritative. The Forrester report does not exist, or exists but does not say that. The decimal place is the AI tell; AI assistants generate false precision to sound credible. + +Pattern 2: quotes attributed to real people the person did not say. "As Marc Benioff said in his keynote..." Plausible because Benioff gives keynotes. The specific quote is fabricated. Verify quotes against the actual recording, transcript, or primary source. + +Pattern 3: case studies about companies that do not exist. "Acme Innovations reduced their cycle time 40% using..." The company does not appear in any business directory; the case study is invented. Search the company name; if it does not surface in legitimate sources, the case study is fake. + +Pattern 4: citations to URLs that 404 or never existed. Click every external link. 404s and dead links are signals; a piece with multiple dead links has multiple unverified claims. + +Pattern 5: "Studies show" claims with no actual study. "Studies show that..." with no link, no journal, no year. Either the writer provides the study or the claim gets cut. + +Pattern 6: made-up product features. "[Product] now supports automatic X" when the product does not. Verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Citation discipline + +When citations are present, they need to be the right kind. + +Authoritative sources. + +- Academic papers (peer-reviewed journals) +- Industry reports from established research firms (Forrester, Gartner, McKinsey, IDC) when verified +- Primary government data (BLS, Census, SEC filings) +- Original company announcements (the company's own blog, press release, official documentation) +- First-party data the brand owns and has published + +Avoid citation laundering. + +Citing another content marketing page that itself cites a primary source is laundering. The chain of attribution gets murky; the claim's accuracy degrades through each hop. Cite the primary source directly. + +Date the source. + +Sources older than 3 years for fast-moving topics need refresh. "According to a 2018 Gartner report" is a yellow flag for content about a 2026 topic; the data might still be true but probably is not. Either find a more recent source or note the date and explain why the older source still applies. + +--- + +## When the writer disputes the fact-check + +Sometimes the editor flags a claim and the writer pushes back. "I read it in the original source; here's the link." Two outcomes. + +Outcome 1: writer's source verifies the claim. Add the citation; ship the piece. The QA process worked. + +Outcome 2: writer's source does not verify the claim. This is where the conversation gets uncomfortable. The writer thought they had a source; the source does not say what they thought. The fix is the same: cut the claim or find a verifying source. Do not ship the unverified claim because the writer is sure it is true. + +--- + +## Fact-check log + +Maintain a log of fact-check failures across pieces. Patterns surface over time. + +Log fields. Piece, claim, failure type (hallucination / wrong citation / outdated source / unverifiable), writer (if naming patterns), resolution (cut / re-sourced / verified). + +Patterns the log surfaces. + +- One writer repeatedly produces hallucinations: writer needs feedback or different work +- One topic area produces frequent hallucinations: that topic needs more verification time built in +- AI-co-authored pieces fail at higher rates than human-authored: AI workflow needs additional guardrails + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The verification methodology, the 6 hallucination patterns, the citation discipline rules, the fact-check log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing the fact-check log (spreadsheet, database, Notion). The specific automation (if any) for surfacing claims that need verification (named-entity extractors, statistic detectors). The specific verification workflow when the editor does not have the bandwidth to fact-check personally (assistant-powered verification, fact-checking service integration). These vary by team scale and tooling preferences. diff --git a/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md b/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md new file mode 100644 index 0000000..bce4dd4 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/internal-linking-and-schema-validation.md @@ -0,0 +1,125 @@ +# Internal linking and schema validation + +Link discipline, anchor text variation, schema patterns and validation. + +The internal-linking and schema layer is where SEO compounds. Each piece's link contribution and schema contribution feeds the program's overall ranking and citation signal. QA enforces the discipline so individual pieces do not drift from the program's link graph and schema standards. + +--- + +## Internal linking + +### Outbound links specified in brief + +- The brief named X outbound links. Verify each is present in the piece. +- Anchor text matches the brief's specification. "Click here" is dead anchor text; the brief should specify keyword-aware anchor text per link. +- Links go where the brief said. The link target is the page the brief specified, not a deprecated alternate or a different page that happens to share the topic. + +### Anchor text variation + +The "every link has the same anchor text" anti-pattern. + +Pattern. A piece links to the pillar 3 times. All 3 links use the exact-match keyword as anchor. This signals manipulation to ranking systems and dilutes the anchor's signal. + +Fix. Vary the anchor across the 3 links. One uses the exact-match keyword; one uses a descriptive natural-language phrase; one uses a brand-mention anchor or a context-driven phrase. + +The audit. For each piece, count the outbound links to the same target. If multiple links to the same target use identical anchor text, vary at least one. + +### Link-target liveness + +- Every internal link target exists. No 404s. The link goes to a live page on the site. +- No links to deprecated pages. If a target page was retired, the link should redirect (via 301) or the link itself should be replaced. +- External links work. Click them; verify they resolve and lead to the intended source. + +The external-link audit catches hallucinated citations (see `fact-accuracy-and-citation-discipline.md`) and link rot. + +### Internal link count + +- 3 to 7 internal links for a typical 1,500-word piece. Below 3 signals under-linked (orphan-shaped). Above 10 signals link-stuffing. +- 8 to 15 for a pillar piece. Pillars carry more outbound links to their cluster. +- The link count should be by design, not by accident. The brief specifies the link count; the writer should hit it; QA verifies. + +### Self-cannibalization check + +- The piece does not compete with an existing piece for the same target keyword. Search the site for the primary keyword. If an existing piece is in the top 5 internal results, flag the new piece. + +The flag triggers a decision: consolidate, differentiate, or kill one. Detail in `pillar-content-architecture/references/internal-linking-architecture.md` for the broader internal linking discipline. + +--- + +## Schema validation + +### Schema type matches content + +- Article schema for editorial pieces. Default for blog posts, long-form articles, thought leadership. +- HowTo schema for instructional pieces. Step-by-step guides with explicit steps that the schema can structure. +- Product schema for product pages. Programmatic pSEO pages rendering products usually use Product schema. +- LocalBusiness schema for location-based pages. Programmatic pSEO for geographic categories. +- FAQPage schema for genuine FAQ sections. As an embedded schema within the page, not as the page's primary schema (unless the page is FAQ-shaped throughout). +- BreadcrumbList schema for navigation context. Most pages benefit; pillar pages especially. + +### Schema validates + +- Schema validates against schema.org definitions. No missing required fields. No malformed JSON-LD. No invalid field types. +- Validation method. Run the schema through a validator (Google's Structured Data Testing Tool, schema.org's validator, or equivalent). Failures appear as errors with field-specific messages. + +### Schema is consistent with on-page content + +- Schema reflects what the page actually shows. Do not claim 5-star rating in schema if there is no rating on the page. Do not claim a HowTo with 7 steps if the page only walks through 4. Mismatch between schema and content can trigger manual penalties. + +### Optional schema fields earn their keep + +- Populated optional schema fields signal depth. Programmatic pages with comprehensive schema (`aggregateRating`, `additionalProperty`, `areaServed`, etc.) score higher with AI engines than pages with bare-minimum schema. +- The trade-off. Filling optional fields requires data. If the data does not exist, do not fabricate it; either populate genuinely or leave the field absent. + +--- + +## The link audit pattern + +For each piece in QA: + +1. Outbound links present. Match against brief. +2. Anchor text variation. Same-target links use varied anchor text. +3. Targets live. No 404s, no deprecated pages. +4. Link count in band. 3 to 7 for typical, 8 to 15 for pillar. +5. Self-cannibalization. No competition with existing pieces. +6. Inbound links queued for post-publish update. The brief queued 1 to 3 existing pages that should add links to this piece after publish; the QA log queues those updates. + +The 6-step audit takes 5 minutes per piece. Worth the time; under-linked or stuffed pieces fail to compound. + +--- + +## The schema audit pattern + +For each piece in QA: + +1. Schema type appropriate. Article, HowTo, Product, LocalBusiness, FAQPage, or BreadcrumbList per content shape. +2. Schema validates. Run through a validator; resolve errors before publish. +3. Schema matches content. No false claims (false ratings, false step counts). +4. Optional fields populated. Where data exists, fields populate; the page signals depth. +5. Multiple schema types when appropriate. Article + FAQPage + BreadcrumbList is common for pillar pieces with FAQ sections. + +The schema audit takes 3 to 5 minutes per piece (less with automation; more on first-pass for new content types). + +--- + +## Common failures + +Brief specified link, writer skipped it. Halt and return; brief-adherence catches this earlier in the QA sequence. + +Anchor text identical across links. Auto-fix in the editor pass; vary the anchor on at least 2 of every 3 same-target links. + +Schema fails validation. Auto-fix; the editor or a script ships the corrected schema. + +Schema claims rating that is not on the page. Halt and return; this is the manual-penalty risk. + +Internal link count below brief. Flag and return for the writer to add the missing links per the brief's specification. + +--- + +## Methodology-level choices that stay in the public skill + +The 6-step link audit, the 5-step schema audit, the anchor variation rule, the schema-content consistency rule, the optional-field discipline. + +## Implementation choices that stay internal + +The specific schema validation tooling (Google's tool, schema.org's tool, custom CI integration). The specific link checker (Screaming Frog, custom Puppeteer script, headless browser audit). The specific CMS integration that auto-populates schema from page metadata. The specific deployment pipeline that runs schema validation on every publish. These vary by stack and team. diff --git a/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md new file mode 100644 index 0000000..cd443d8 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/qa-at-scale-patterns.md @@ -0,0 +1,184 @@ +# QA at scale patterns + +Sampling strategy, automated checks, manual review at scale, threshold gating. + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. The discipline below is sampling plus automated checks plus threshold gating. It is the same shape as the QA section in `programmatic-seo` but applied to the editorial QA gate specifically. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle. The sample is stratified. + +Stratification dimensions. + +- Sparse vs dense data. Sample some records with minimum-required fields; sample some with most-fields-populated. Sparse pages fail differently from dense pages; the sample needs both. +- Recent vs old. Sample some pages generated in the last 30 days; sample some generated 12+ months ago. Recent pages catch template drift; old pages catch data drift. +- Popular vs niche categories. Sample some pages from high-traffic parent categories; sample some from low-traffic ones. The popular categories carry the program's traffic; the niche ones surface long-tail-specific failures. +- Different cohort versions. If the template has shipped revisions, sample some pages from each cohort. Cohort-specific failures only surface if the sample includes the cohort. + +Sample size by set size. + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +Cycle frequency. Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks at scale + +Run on every page on a cadence; surface failures as a queue. + +### Heading-structure validation + +- One H1 per page, in the right place +- H2 sequence reasonable (not orphan H3s, not H4 without H3) +- Heading text length within bounds (no 200-character H2s) + +### Schema markup validation + +- Schema type present and matches the page's content type +- Required fields populated +- JSON-LD parses without errors +- Schema does not claim things absent from the page + +### Word count + +- Pages below the floor (typically 600 words for editorial; varies for programmatic templates) get flagged +- Pages above an upper bound (typically 8,000+ words on programmatic templates) get flagged for review + +### Duplicate content + +- Hash-similarity comparison across the set +- Pages with >80% content overlap with another page in the set get flagged +- Common cause: comparison-pivot pages (X vs Y inverse) without canonicalization + +### Broken links + +- Crawl outbound and internal links +- 404s and 5xx responses get flagged +- Both internal links to deleted pages and external links to dead URLs surface + +### Image presence + +- Pages where the template expects images but the image slot is empty +- Programmatic pages with missing image fields render visibly broken + +--- + +## Manual checks on sampled pages + +For sampled pages, the human review covers what automation misses. + +### Brief or template adherence + +- For editorial pages: did the writer execute the brief? +- For programmatic pages: did the page execute the template? + +### Top-200-word answer quality + +- Read the first 200 words. Does the page answer the user's likely query? +- Is the answer self-contained (could be cited as the canonical answer to the query)? + +### Distinctive vs templated + +- Compare the sampled page to two siblings in the same template cohort. Could you tell them apart on substance, not just on identifiers? +- Templated pages that look identical signal weak data depth or weak template variable density. + +### User-intent satisfaction + +- If a real user landed on this page from the target SERP, would they stay or bounce? +- The bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +### AI hallucination spot-check + +- For pages that involved AI in drafting or generation, spot-check 3 to 5 statistics, citations, or factual claims per sampled page. +- Hallucination patterns surface in patterns; one bad page often signals a template-level or pipeline-level issue. + +### AI-tell pattern check + +- Sample a paragraph from the middle of the sampled page. +- Does it match the AI tells from `ai-content-audit-patterns.md`? +- Mid-page drift in programmatic pages signals the generation pipeline's output drifted; investigate. + +--- + +## Threshold gating + +If more than 5% of sampled pages fail the manual review, halt new generation. Fix the template OR data quality issue before resuming. + +The 5% threshold is empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +What "halt" means. + +- New page generation stops. +- The template or data fix is shipped. +- The next sample audit confirms the fix improved the failure rate before generation resumes. + +Why halt instead of "fix as you go." Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +The threshold is not negotiable. "Just ship the next batch and we will fix later" is the failure mode. The pattern produces sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another. That signals a template change or data quality drift; investigate. + +Cohort cuts. + +- Pages from a given month +- Pages from a given template version +- Pages from a given data-source version + +Drift signals. + +- Cohort A pages rank top 10; cohort B pages rank position 30. Template or data changed between cohorts; identify the change. +- Cohort A pages get cited; cohort B pages do not. Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- Cohort A pages have stable engagement; cohort B pages have decaying engagement. Cohort B may have a data freshness problem. + +Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically. + +--- + +## QA log + +Document each cycle's audit. The log compounds into pattern detection. + +Log fields. Cycle date, sample size, failure count, failure types, cohort distribution, threshold breach if any, halt action if triggered, fix shipped if applicable. + +The patterns the log surfaces over time. + +- Recurrent failure types (always the answer paragraph; always the schema; always the data freshness) +- Cohort-specific patterns (cohort B always fails harder than cohort A) +- Template versions that solved one problem and introduced another +- Data sources that drift faster than expected + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## When the sample reveals the program is broken + +Sometimes QC at scale reveals the underlying program is wrong, not just that individual pages need fixes. + +Signals. + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole there; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. + +--- + +## Methodology-level choices that stay in the public skill + +The stratified sampling strategy, the 5% threshold, the automated check categories, the manual review checklist, the cohort tracking discipline, the QA log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing and querying the QA log (database table, Notion, dbt model, BI tool). The specific automated check pipeline (CI integration, scheduled crawls, data warehouse queries). The specific sampling implementation (random ID selection script, weighted sampling logic). The specific dashboard or visualization for surfacing cohort patterns. These vary per team scale and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md b/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md new file mode 100644 index 0000000..ad175af --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/qa-workflow-templates.md @@ -0,0 +1,153 @@ +# QA workflow templates + +Ownership, sequencing, halt vs flag vs auto-fix, escalation patterns. + +The QA workflow is the operational shape of how QA actually runs. Templates below name the patterns; teams adapt the implementation to their own tooling. + +--- + +## Ownership: single QA owner per piece + +The principle. One person is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +Common ownership models. + +- Editor-owns-piece. The editor who reviews the piece is also accountable for what shipped. The same person sees the brief, reads the draft, runs QA checks, ships. +- Editor + dedicated QA. Editor reviews voice and structure; dedicated QA runs fact-checks, link audits, schema validation. The editor is still the single point of accountability for ship-decision. +- Rotating editor pool. Larger teams have multiple editors; each piece gets one named owner from the pool. The pool is calibrated quarterly so individual editors apply consistent standards. + +Anti-pattern. Committee review where 4 reviewers comment, nobody decides, the writer revises against contradictory feedback. The fix: name the decision-maker; treat other input as advisory. + +--- + +## The sequencing template + +Run QA gates in this order. Each gate is cheaper than the next; running them in order saves the editor's time on pieces that should restart. + +1. Brief-adherence. First. Cheapest to run. Catches the largest class of failures. +2. Fact-accuracy. Second. Halt-condition; AI hallucinations do not progress past this gate. +3. Structure and clarity. Third. Identifies pieces that need structural revision before voice and SEO checks make sense. +4. AI-content audit. Fourth. Catches AI tells, hallucinations not caught at gate 2, voice drift. +5. Voice consistency. Fifth. Mid-piece sampling for long pieces. +6. SEO and AEO compliance. Sixth. Most failures here are auto-fixable; rarely halt-conditions. +7. Internal linking and schema validation. Seventh. Mostly auto-fix or flag. +8. Final read. The last full read before publish. Catches anything the gate-by-gate review missed. + +The early gates (brief, fact, structure) save the most time; running them first means a piece that fails brief-adherence does not consume voice/SEO review time. + +--- + +## Halt vs flag vs auto-fix taxonomy + +Each QA gate has a default action when failures appear. + +Halt-conditions (return to writer). + +- Brief-adherence failures. The contract was not executed. +- Fact-accuracy failures (hallucinations, unverifiable claims). Cannot ship false claims. +- Structural failures that require rewriting (buried lede, mismatched intent, missing facets). Cannot fix in editor pass. +- Voice drift that requires rewriting sections. Cannot fix inline. + +Flag-and-revise (editor flags; writer or editor revises). + +- Voice consistency issues that are correctable inline. +- Structural issues that need paragraph-level revision (sentence variety, transition smoothing). +- AI tells that need targeted rewriting. +- Specificity gaps where the writer needs to add the missing concrete claim. + +Auto-fix (editor or script ships the correction without writer involvement). + +- Slug, meta description, image alt text. +- Schema markup formatting issues. +- Anchor text variation when same-target links share identical anchors. +- Heading structure mechanical fixes (closing orphan H3s). +- Typos and minor grammar. + +The discipline. Most pieces have a mix: some auto-fix items, some flag-and-revise items, sometimes a halt-condition. The editor processes them in the right order: handle auto-fixes inline, batch flag-and-revise items into one return note, halt early if a halt-condition appears. + +--- + +## Escalation patterns + +When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +### Brief-level patterns + +- Multiple writers fail brief-adherence on the same brief field. The brief is unclear about that field; tighten the brief template. +- Multiple briefs surface the same gap (always missing the audience specification, always missing the success criteria). The brief authoring process needs feedback. + +### Writer-level patterns + +- One writer repeatedly produces pieces that fail at the same gate. The writer needs targeted feedback or different work. +- One writer's pieces consistently need substantial revision. Either the briefs the writer receives need to be tighter, or the writer-fit is wrong for the work. + +### Process-level patterns + +- AI-content audit catches similar tells across pieces. The AI workflow needs additional guardrails. +- Fact-accuracy gates catch repeated hallucinations on the same topic. The verification step for that topic needs more time. +- Schema validation fails consistently on the same content type. The CMS template for that type needs updating. + +The escalation. Pattern goes to the editorial process owner with a short summary: "Across the last 12 pieces, 5 failed at [gate] for [reason]. Recommend [action]." The owner decides whether to update the brief template, retrain a writer, change the workflow, or document the pattern as known and accepted. + +--- + +## QA review templates + +Common formats for capturing QA findings. + +### Halt-condition return note + +Short. The note specifies what failed and what needs to change. + +> "This piece needs revision before round 2. Three failures: [field 1] missing the brief specification of [X], [field 2] contains an unverified statistic on line [N], [field 3] reads as model-default voice in section 4. Revise per the brief and the voice doc." + +### Flag-and-revise inline review + +Inline comments in the editing tool. Each comment is short and actionable. + +- "[Brief required] Add internal link to [X] with anchor '[Y]' here." +- "[Voice drift] This paragraph reads generic; pull back to brand voice." +- "[Specificity] 'Many companies' is vague; add the source or remove the claim." + +### Auto-fix log entry + +The editor logs what was auto-fixed for the writer's awareness without requiring writer action. + +> "Auto-fixed during review: meta description tightened, schema markup field [X] added, anchor text varied on 2 links to [target]. No writer action required." + +### Escalation note + +Short summary to the editorial process owner. + +> "Pattern: 5 of 12 recent pieces have failed AI-content audit on em-dash count. The writer using AI assistance is shipping mid-stage drafts without final em-dash cleanup. Recommend a final-pass revision guideline added to the AI-co-author workflow doc." + +--- + +## QA cycle time + +The discipline keeps QA cycle time tractable. + +Typical times for a 1,500-word piece. + +- Brief-adherence: 5 minutes +- Fact-accuracy: 10 to 30 minutes (depending on claim density) +- Structure and clarity: 10 minutes +- AI-content audit: 5 minutes +- Voice consistency: 5 minutes +- SEO and AEO compliance: 10 minutes +- Internal linking and schema: 5 minutes +- Final read: 5 minutes + +Total. 55 to 75 minutes for a healthy piece. Pieces that halt at gate 1 or gate 2 take less editor time because the early gates short-circuit the rest. + +The "QA takes longer than the writing" failure. Usually means the wrong sequencing (running expensive checks before cheap ones). Fix the sequence; the cycle time drops. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner principle, the gate sequencing, the halt/flag/auto-fix taxonomy, the escalation patterns, the review templates, the cycle-time targets. + +## Implementation choices that stay internal + +The specific editing tool the team uses (Google Docs, Notion, Markdown PRs, headless CMS draft mode). The specific commenting and review workflow within that tool. The specific tracking system for QA logs and escalations (Notion, Linear, Jira, custom database). The specific reporting cadence and format for editorial process owners. These vary per team and tooling. diff --git a/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md b/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md new file mode 100644 index 0000000..e3e31e6 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/seo-aeo-compliance-checklist.md @@ -0,0 +1,113 @@ +# SEO and AEO compliance checklist + +SEO and AEO checks combined into one workflow. The two-engine optimization principle holds: pieces that earn search rankings are largely the same pieces that earn AI citations. + +This checklist runs late in the QA sequence (after brief-adherence, fact-accuracy, structure, AI-content audit, voice). SEO and AEO failures are mostly auto-fixable; halting on them is rarely the right call. + +--- + +## SEO checks + +### Title and headings + +- Target keyword in title. The brief's primary keyword appears in the page title; the title is 50 to 65 characters; the title reads naturally rather than keyword-stuffed. +- H1 present and matches title intent. Some CMSs use the title as H1; some have separate H1. Either way, one H1 per page that establishes the topic. +- Heading hierarchy clean. No orphan H3s (every H3 sits under an H2). No H4 without H3. The hierarchy is tree-shaped, not arbitrary. +- H2 keyword variation. Supporting cluster keywords appear naturally across H2s without forcing. + +### Meta and URL + +- Meta description compelling and keyword-aware. 140 to 160 characters; includes the primary keyword without stuffing; reads as a benefit-statement that earns the click from SERP. +- URL slug short and descriptive. Hyphens, lowercase, keyword-aware, date-free, under 60 characters. Generic example: `/feature-flag-rollout/kill-switches/`. +- Canonical URL set. The piece has a canonical URL pointing to itself (or to the canonical version if this piece is a duplicate-by-design like an X vs Y comparison page). + +### On-page + +- Image alt text descriptive. Every image has alt text that describes the image's content, not "image of [thing]" or generic placeholders. +- External links open appropriately. Most external links open in a new tab; rel attributes (`noopener`, `noreferrer`, `sponsored`, `nofollow`) match the link's purpose. +- Internal link count appropriate. 3 to 7 internal links for a 1,500-word piece; 8 to 15 for a pillar piece. Below the floor signals under-linked; well above signals link-stuffing. + +--- + +## AEO checks + +The AEO surface complements the SEO surface. AI engines weight different patterns; the checks below catch what AI engines specifically reward. + +### Answer paragraphs at H2 level + +- 40 to 60 word answer paragraph immediately following each H2 question. AI engines extract these as citation candidates. The paragraph is self-contained: read alone, it answers the H2's specific question completely. +- Snippet-bait pattern repeats throughout. Not just the top of the piece. Every H2 gets one. + +### TL;DR section + +- Pillar pieces include a TL;DR section near the top. 150 to 250 words. Self-contained. The most-cited section by AI engines for pillar-shaped content. +- TL;DR placement. After the hero, before the table of contents. The reader sees TL;DR within the first scroll. + +### FAQ schema + +- FAQ section with FAQPage schema. Pieces that contain FAQ-shaped content (genuine reader questions with answers) mark the FAQ section with FAQPage structured data. Perplexity especially cites FAQPage content heavily. +- Genuine FAQs only. Do not mark fake FAQs (questions nobody actually asks) with FAQPage schema. Search engines and AI engines detect fabricated FAQs and deprioritize. + +### Statistics with sources + +- Specific statistics with cited sources. AI engines weight statistics with sources higher than vague qualifiers. "23% of B2B buyers cite [specific source]" beats "many B2B buyers." +- The numbers are real. Verify in the fact-accuracy gate; do not let hallucinated statistics ship just because they would help SEO/AEO. + +### Named entities + +- Entity coverage matches brief. The required entities from the brief are present; the standard entities are present where relevant; the gap entities are present where the brief committed to them. +- Entities mentioned with weight. Pass the brief's depth-of-coverage requirement: not just "CUPED is mentioned in passing" but "CUPED is developed in the methodology H2 with the formula and an example." + +### Distinctive POV + +- The piece takes a position. AI engines preferentially cite content with attributable claims. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. +- The POV is consistent with brand stance. Voice doc specified the brand stance; the piece's POV aligns. + +--- + +## Auto-fix vs flag vs halt + +Most SEO/AEO failures are auto-fixable: the editor or a script can fix slug, meta description, image alt text, schema markup without writer involvement. + +Some require flag-and-revise: heading structure, internal link count, answer paragraph patterns. The editor flags; the writer revises. + +Halt-conditions are rare for SEO/AEO. The typical case where halt makes sense: the piece is structurally wrong for the target SERP (brief specified listicle; piece is long-form prose). That is a brief-adherence failure that surfaced late; route back to the brief-adherence gate. + +--- + +## The combined SEO/AEO audit + +Run as one pass. The checks overlap (both reward heading structure, both reward depth, both reward freshness). Treating SEO and AEO as separate workflows doubles the audit time without doubling the catch rate. + +The discipline. One audit, one checklist, two-engine optimization mindset. The piece serves both surfaces or it serves neither well. + +--- + +## Pillar-specific extensions + +Pillar pieces have additional SEO/AEO requirements. + +- TL;DR section (covered above) +- Comprehensive entity coverage. Pillar pieces should mention 15 to 25 entities across the topic; cluster pieces have lower bars. +- Internal links to cluster pieces. Pillar links out to each cluster piece via contextual anchors, not via a footer dump. +- Schema includes BreadcrumbList. Tells crawlers and AI engines that this is the hub of a topical cluster. + +--- + +## Programmatic-page-specific extensions + +For programmatic SEO pages, SEO/AEO checks adapt. + +- Top-200-word answer. First 200 words answer the user's specific query directly. AI engines cite programmatic data pages for factual queries primarily. +- Schema population at scale. Every page has Article, Product, LocalBusiness, or other type-appropriate schema; schema fields populate from the same data that renders the visible page. +- Sampling discipline. Full-audit SEO/AEO checks are infeasible at scale; sample 50 to 200 pages per cycle (see `qa-at-scale-patterns.md`). + +--- + +## Methodology-level choices that stay in the public skill + +The combined SEO/AEO check sequence, the auto-fix/flag/halt taxonomy, the pillar-specific extensions, the programmatic-specific extensions. + +## Implementation choices that stay internal + +The specific tooling for automated SEO/AEO checks (Lighthouse audits, schema validators, headless-CMS-specific plugins). The specific schema-validation library or service. The specific staging environment where pre-publish checks run. The specific deployment pipeline that gates publish on SEO/AEO compliance. These vary by stack and team. diff --git a/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md b/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md new file mode 100644 index 0000000..aebad76 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/structure-and-clarity-review.md @@ -0,0 +1,128 @@ +# Structure and clarity review + +Lede patterns, sectioning principles, endings, structural anti-patterns. + +Structure determines whether the piece works as a piece. The discipline below is about making structure visible enough to QA repeatably without becoming process theater. + +--- + +## The lede + +The first 200 words. Two valid patterns depending on intent. + +For SEO/AEO pieces. The lede answers the user's likely query directly. The reader landed from a SERP looking for a specific answer; the lede provides it within the first 200 words. The rest of the piece develops the answer with depth. + +For thought leadership. The lede establishes the thesis. The reader is investing attention; the lede tells them the argument the piece will defend. The rest of the piece builds the case. + +Lede failure patterns. + +- Welcome-to-our-blog throat-clearing. The lede announces what the piece is about to do instead of doing it. +- Buried lede. The actual answer or thesis appears in section 4. The reader bounced at section 2. +- Vague opening. Generic descriptive paragraph that could open any article on the topic. +- History dump. "Since the dawn of [topic]..." Cuts the throat-clearing; ledes do not need a history. + +--- + +## Sectioning + +The check. H2s map to user mental model, not writer enthusiasm. + +User mental model. What questions does the reader bring? What questions follow naturally from the first answer? What does the reader want to know next? The H2 sequence answers these in order. + +Writer enthusiasm. What does the writer find interesting? Where does the writer want to dig deep? Writer enthusiasm produces sections that are well-written but mistargeted; the reader did not come for that section and skips it. + +The audit. Read the H2 list as a sequence of questions or topics. Does the sequence match what the reader's mind would ask in order? If H2 #4 has the answer the reader landed for, the structure has buried lede; promote H2 #4 to H2 #1. + +--- + +## Section length + +The check. Even-ish across H2s. + +Why even-ish matters. One massive section followed by four 80-word sections signals broken structure. The massive section is doing real work; the 80-word sections are placeholders or filler. + +The fix. + +- If the 80-word sections are placeholders: cut them or expand them to the section's natural depth. +- If the massive section is two facets bundled: split it into two H2s. +- If the structure is genuinely uneven (one section needs to be twice as long for substantive reasons): document the rationale; ship with the imbalance acknowledged rather than hidden. + +--- + +## Reading flow + +The check. Paragraphs connect; sentences vary in length. + +Paragraph flow. Each paragraph extends the previous one or pivots intentionally. Disconnected paragraphs read as bullet-points-pretending-to-be-prose. The fix: explicit connective tissue between paragraphs (the connection is implicit in the sequence, or the writer adds a one-sentence transition that does the work). + +Sentence variety. Reading aloud is the audit. Do all the sentences run the same length? That is a tell of AI-assisted writing or rushed drafting. Vary sentence length across the paragraph; mix short declarative sentences with longer ones that build through clauses. + +--- + +## Specificity vs abstraction + +The check. Claims are concrete, not vague. + +Concrete. Named tools, named methods, named statistics with sources, named experts, named scenarios. Concrete claims earn citations from AI engines and trust from readers. + +Abstract. "Many companies struggle with X." "Studies show Y." "Industry leaders agree Z." Vague claims read as content marketing filler; AI engines and readers both deprioritize. + +The fix. Replace each abstract claim with a specific one. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research the writer did not do, halt and request the research before shipping. + +--- + +## Endings + +The check. Piece concludes with something specific. + +Specific endings. + +- An action the reader can take now +- A specific question that frames the next step +- A concrete idea that lands as the takeaway +- A direct call to action with a specific destination + +Filler endings to cut. + +- Wrap-up paragraphs that summarize what the piece just said +- Wrap-up frames that announce the ending instead of arriving at it (the conclusion should land as a conclusion, not declare itself) +- Vague "join us as we explore" closings +- Marketing-tone CTAs that do not match the piece's voice + +The ending is the last thing the reader reads; it is the moment of conversion or memory. Filler endings waste the moment. + +--- + +## Structural anti-patterns + +The patterns that surface in QA, with the fix for each. + +Bullet-list overuse. When prose would serve, the writer used bullets. Bullets fragment the reading flow and signal AI-assisted drafting. Convert bullets to prose where prose makes the connection between items clearer. + +Subheading-fest. Every paragraph has its own H3 subheading. Reads as outline-converted-to-content rather than written content. Cut subheadings to the structural ones; let prose carry between subheadings. + +Repetitive paragraph structure. Every paragraph is 2 or 3 sentences of similar length. Vary the structure: some paragraphs are one long sentence; some are 4 short sentences; some are a sentence and a fragment. + +Forced bilateral framing. "On one hand X, on the other hand Y" pattern repeated throughout. AI-tell. Pick a position; defend it; let the contrary position get one sentence rather than equal weight when the position is genuinely strong. + +Throat-clearing transitions. "That said," "With that in mind," "Moving on," "Now let us look at..." All filler. Cut them; the section heading does the transition work. + +--- + +## The read-aloud audit + +The fastest structure check. Read the piece aloud (or silently with attention to rhythm). + +Signals. Where does the rhythm break? Where do you stumble? Where does the reading energy drop? Each break is a structural signal. Sometimes the fix is sentence-level; sometimes it is structural. + +The discipline. The read-aloud audit takes 10 minutes for a 1,500-word piece. It catches problems that line-by-line review misses. Build it into the QA workflow. + +--- + +## Methodology-level choices that stay in the public skill + +The lede patterns, the sectioning principles, the section-length discipline, the reading-flow audit, the specificity rule, the endings discipline, the structural anti-patterns, the read-aloud audit. + +## Implementation choices that stay internal + +The specific format the team uses for structural feedback (inline comments versus written summary versus structural diff). The specific tooling for documenting structural decisions on a piece (CMS metadata, brief addendum, separate review doc). The specific surface conventions per content type (the team's own blog vs help doc vs landing page structural patterns). These vary by team and stack. diff --git a/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md b/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md new file mode 100644 index 0000000..3a0ba06 --- /dev/null +++ b/dist/pi/.agents/skills/editorial-qa/references/voice-consistency-patterns.md @@ -0,0 +1,108 @@ +# Voice consistency patterns + +Vocabulary, rhythm, stance, register. Mid-piece sampling discipline for long pieces. The voice-drift failure mode in AI-co-authored content. + +Voice is the most subjective QA dimension and often the easiest one to skip. The discipline below makes voice-consistency checking concrete enough to run repeatably. + +--- + +## Vocabulary + +The check. Brand-specific vocabulary used correctly; off-brand vocabulary absent. + +Brand vocabulary. Each brand has a set of terms it uses (or refuses) consistently. Apple says "Mac," not "PC." Stripe says "developers," not "engineers." A B2B SaaS company might say "customers," not "users." A consumer brand might say "members," not "subscribers." + +The audit. Pull the brand voice doc's vocabulary section. Check the piece for each preferred term and each forbidden term. Failures: off-brand terms slipped in (the writer or AI assistant defaulted to industry-standard vocabulary instead of brand-specific). + +Forbidden terms list. Every brand has a list. Common patterns: corporate-speak adjectives, throat-clearing phrases, generic descriptors that flatten distinctive voice. The list is short (10 to 30 terms typically); reviewers should know it cold. + +--- + +## Sentence rhythm + +The check. Sentence rhythm matches brand voice. + +Three common rhythms. + +- Short and punchy. Short sentences. Frequent paragraph breaks. Dramatic emphasis through structural choices. +- Measured and layered. Longer sentences with subordinate clauses. Paragraphs build through accumulation. Conversational but considered. +- Colloquial. Conversational rhythm with mid-sentence asides, contractions, and direct reader address. Reads like a smart person talking. + +The audit. Read 3 paragraphs aloud. Does the rhythm match the brand's voice doc? Common drift: AI-assisted pieces regress to a uniform medium-length sentence rhythm regardless of the brand's specified rhythm. + +--- + +## Stance + +The check. The piece takes positions consistent with brand POV. + +Brand stance varies. Some brands are diplomatic and surface multiple sides without endorsing one. Others are opinionated and take clear positions. Others are coach-style and challenge the reader directly. + +The audit. Pick 3 to 5 places in the piece where the writer made a stance choice (a recommendation, a warning, an evaluation). Does each match the brand's stance pattern? + +Voice drift signal. AI-assisted pieces regress toward "diplomatic" stance even when the brand stance is opinionated. "There are good arguments on all sides" is the AI default; opinionated brands need to push the AI back toward conviction explicitly. + +--- + +## Register + +The check. Formal versus casual matches the surface. + +Surface determines register. A whitepaper takes one register; a blog post takes another; a help doc takes a third. The brand voice doc usually specifies registers per surface type. + +The audit. Identify the surface this piece will publish on (blog, knowledge base, whitepaper, marketing page, product help). Check the piece's register against the surface-appropriate register. + +Common drift. Blog pieces drift formal (they read like watered-down whitepapers). Whitepapers drift casual (they read like long blog posts). Help docs drift either direction. The brand voice doc establishes register expectations; the QA check enforces them. + +--- + +## Mid-piece sampling + +The discipline. Long pieces drift; sample throughout, not just at start and end. + +Why drift happens. Writers (human or AI) start in brand voice because that is what the brief, the opening prompt, and the recent context established. By section 4 of a 3,000-word piece, the writer's working memory has shifted to the topic at hand and the voice has drifted toward a generic baseline. AI-assisted pieces drift faster because the model's defaults reassert without continuous reinforcement. + +The sampling pattern. + +- Start sample. First 200 words. Voice should be strongest here. +- Middle samples. Two paragraphs from the middle 60% of the piece. Voice should hold. +- End sample. Last 200 words. Voice should match the start. + +If the start and end samples show brand voice and the middle samples show generic voice, the piece has voice drift. Send it back with the drifted sections highlighted. + +--- + +## The voice-drift signal in AI-co-authored content + +Voice drift is the dominant voice failure in 2025-2026 content. AI assistants produce drafts that pass the start-and-end check (because the writer set up the opening prompt with brand voice cues) but fail the mid-piece check (because the model defaults reasserted in the middle). + +The detection pattern. + +- Mid-piece paragraphs use vocabulary not in the brand voice doc +- Mid-piece sentence rhythm regresses to medium-length uniformity +- Mid-piece stance becomes diplomatic where brand stance was opinionated +- Mid-piece register drifts toward "professional neutral" regardless of the surface's intended register + +The fix. When mid-piece drift is detected, the revision pass needs to explicitly pull the voice back. The editor's note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes]." + +--- + +## Voice calibration sessions + +Different editors apply voice judgment differently. Quarterly calibration sessions reduce the drift between editors. + +The session. Three editors review the same piece independently. Each writes a one-paragraph voice assessment. The team reads the three assessments together; differences in interpretation surface; the team reconciles to a shared standard. + +The output. A short addendum to the brand voice doc capturing the calibration consensus on whatever was contested. Over time the addenda accumulate into a sharper, more specific voice doc. + +Why calibration matters. Without it, voice judgment varies by editor; writers receive inconsistent feedback; voice drift compounds across the program. The calibration session is preventative; once the team is calibrated, individual reviews stay consistent. + +--- + +## Methodology-level choices that stay in the public skill + +The 4-dimension voice check (vocabulary, rhythm, stance, register), the mid-piece sampling discipline, the AI voice-drift detection pattern, the calibration session methodology. + +## Implementation choices that stay internal + +The specific brand voice doc format (Notion page, Markdown file, internal wiki page). The specific vocabulary list and the specific forbidden-term list (these are brand-specific and live in the brand's own documentation). The specific calibration session cadence and team composition. The specific tooling for archiving voice assessments. These vary per brand and team. diff --git a/dist/pi/.agents/skills/email-deliverability/SKILL.md b/dist/pi/.agents/skills/email-deliverability/SKILL.md new file mode 100644 index 0000000..aca68b1 --- /dev/null +++ b/dist/pi/.agents/skills/email-deliverability/SKILL.md @@ -0,0 +1,283 @@ +--- +name: email-deliverability +description: "Make sure email actually reaches inboxes. Use this skill when setting up email authentication (SPF, DKIM, DMARC), diagnosing emails landing in spam, planning a domain reputation strategy, monitoring sender reputation, or hardening against email spoofing. Triggers on email deliverability, SPF, DKIM, DMARC, spam folder, sender reputation, mailbox provider, soft bounces, bounce rate, BIMI, MTA-STS, deliverability audit. Also triggers when a marketing or transactional email isn't reaching users." +category: operations +catalog_summary: "DMARC, SPF, DKIM, sender reputation, deliverability monitoring" +display_order: 8 +--- + +# Email Deliverability + +Get email into inboxes, not spam folders. Set up authentication. Monitor reputation. Diagnose problems before they hurt the business. + +--- + +## When to use + +- Setting up email for a new domain +- A meaningful percentage of email is going to spam +- Customers report they're not receiving emails +- Setting up DMARC, SPF, or DKIM +- Hardening against domain spoofing +- Migrating email service providers +- Sender reputation has dropped +- Pre-launch audit before sending volume increases + +## When NOT to use + +- Writing the email content itself (use `email-sequences`) +- Designing the email program strategy (use `email-sequences`) +- DNS records in general (use `domain-strategy`) +- Outbound spam coming FROM your account (different problem; investigate compromised credentials) + +--- + +## Required inputs + +- The sending domain(s) +- The email service provider (ESP, transactional service, mail server) +- Current DNS records (or access to them) +- Email volume (transactional vs marketing, daily volume) +- Current deliverability state (if known: bounce rate, spam complaints) + +--- + +## The framework: 3 pillars + +Email deliverability rests on three pillars. Weakness in any one limits the others. + +### Pillar 1: Authentication + +Mailbox providers verify email is actually from who it claims to be from. Three records. + +SPF (Sender Policy Framework) + +Lists which servers are authorized to send mail for the domain. Published as a TXT record at the apex. + +``` +v=spf1 include:_spf.mailprovider.com -all +``` + +- `include:` adds another sender's authorized list +- `-all` (hard fail): mail from unlisted senders fails authentication +- `~all` (soft fail): unlisted senders are suspicious but pass; useful during rollout +- `+all`: never use; allows anyone to send + +Only one SPF record per domain. Multiple SPF records break SPF entirely. Combine senders into a single record. + +SPF has a 10-DNS-lookup limit. Each `include:` may use multiple lookups. Hit the limit and SPF stops working. Watch this carefully. + +DKIM (DomainKeys Identified Mail) + +A cryptographic signature on each outgoing email. The mail server signs with a private key; the public key is published in DNS. + +``` +selector1._domainkey.example.com TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +Selectors differ by ESP. Some use `default._domainkey`, some use unique selectors per service. Most ESPs walk you through publishing the records. + +DKIM proves the message wasn't modified in transit and that the sender controls the domain. + +DMARC (Domain-based Message Authentication, Reporting, and Conformance) + +The policy layer. Tells receivers what to do when SPF or DKIM fails, and where to send reports. + +``` +_dmarc.example.com TXT "v=DMARC1; p=reject; rua=mailto:dmarc-aggregate@example.com; ruf=mailto:dmarc-forensic@example.com; pct=100; adkim=s; aspf=s" +``` + +Components: +- `p=`: policy. `none`, `quarantine`, or `reject`. +- `rua=`: aggregate reports (daily, summary). Always set this. +- `ruf=`: forensic reports (per-message). Optional, can be high volume. +- `pct=`: percentage of failing mail subject to the policy. Useful for gradual rollout. +- `adkim=`, `aspf=`: alignment mode. `s` (strict), `r` (relaxed). Strict means From: domain must match exactly. + +DMARC is the most important record. It's what makes spoofing your domain hard. + +### Pillar 2: Reputation + +Mailbox providers (Gmail, Outlook, Yahoo) score every sender. Reputation drives delivery. + +Reputation factors: +- Authentication pass rates (SPF, DKIM, DMARC) +- Engagement signals (opens, replies, marking as not-spam) +- Negative signals (spam complaints, deletions without opens, blocking) +- List hygiene (low bounce rates, no spam traps) +- Volume consistency (sudden spikes look like spam) +- Content patterns (link reputation, attachment patterns) +- IP and domain history + +Reputation is per (sending domain × mailbox provider). Gmail's view of you is independent of Outlook's. + +### Pillar 3: List quality and engagement + +Authentication and reputation rest on list quality. Bad list = bad reputation eventually. + +- Only send to people who explicitly opted in +- Confirmed (double) opt-in for marketing wherever feasible +- Honor unsubscribes immediately and reliably +- Remove hard bounces immediately +- Sunset disengaged contacts (no opens in 6 months: reduce frequency or remove) +- Avoid third-party lists, scraped emails, or "purchased opt-ins" + +The single biggest deliverability lever for most senders is list hygiene. + +--- + +## Workflow + +### Step 1: Audit current state + +Check the current DNS records: + +```bash +dig +short txt example.com +dig +short txt selector1._domainkey.example.com +dig +short txt _dmarc.example.com +``` + +Also check: +- Current bounce rate (target: under 2%) +- Current spam complaint rate (target: under 0.1%) +- Current open rate (varies by industry; falling trend is a warning) +- Current sending volume + +Tools: mxtoolbox.com, dmarcian.com, mail-tester.com (for individual messages). + +### Step 2: Fix authentication + +If any of SPF, DKIM, DMARC is missing or misconfigured, fix first. + +SPF fix order: +1. Identify all legitimate senders (transactional ESP, marketing ESP, support tools, etc.) +2. Get the `include:` value or IP for each +3. Combine into a single SPF record +4. Verify lookup count is under 10 +5. Use `-all` for hard fail (or `~all` if rolling out gradually) + +DKIM fix order: +1. Generate a new selector per sending service +2. Publish the public key in DNS +3. Configure the ESP to sign with the private key +4. Verify with a test send (check headers for `dkim=pass`) + +DMARC fix order: +1. Publish DMARC with `p=none` initially (monitoring mode) +2. Set up an aggregate report endpoint (use a DMARC analytics service or your own) +3. Watch reports for at least 2-4 weeks +4. Identify any legitimate senders failing alignment; fix them +5. Move to `p=quarantine` with `pct=10`, gradually increase +6. Move to `p=reject` once confidence is high + +The full progression typically takes 2-3 months. Rushing causes legitimate mail to bounce. + +### Step 3: Set up monitoring + +Ongoing visibility: + +- DMARC aggregate reports: parsed daily. Watch for new sources, alignment failures, volume changes. +- Bounce rate: per ESP dashboard. Target under 2% for transactional, under 5% for marketing. +- Spam complaint rate: target under 0.1%. +- Reputation tools: Google Postmaster Tools (free), Microsoft SNDS, Talos, Sender Score. +- Blacklist monitoring: most ESPs include this; otherwise mxtoolbox.com or hetrixtools.com. + +### Step 4: Address list hygiene + +- Remove hard bounces from your sending lists immediately (most ESPs do this; verify) +- Set up suppression lists (unsubscribes, manual blocks, deliverability sinkholes) +- Sunset disengaged contacts (re-engagement campaigns or just remove) +- Review opt-in flows: do people know what they're signing up for? + +### Step 5: Content and pattern audit + +If reputation is good and authentication passes, check content: + +- HTML-only emails (no plain-text alternative) raise flags +- Heavy image-to-text ratios raise flags +- Suspicious link patterns (bare IPs, URL shorteners, hijacked domains) +- Specific spam-trigger words in subject lines (less important than it used to be, still real) +- Lots of mismatched domains in URLs +- Generic from-name like "info@" rather than a real-sounding sender + +### Step 6: Plan for growth + +Email volume affects reputation. Sudden spikes look like spam. + +- Warm up new sending IPs gradually (start at 50/day, 2x daily) +- Warm up new domains gradually (similar pattern) +- Spread sends throughout the day +- Don't switch ESPs the week before a big launch + +### Step 7: Set up BIMI (optional but valuable) + +BIMI (Brand Indicators for Message Identification) shows your logo next to authenticated emails in supporting clients (Gmail, Apple Mail, Yahoo, others). + +Requires: +- DMARC at `p=quarantine` or `p=reject` (so this comes after the DMARC progression) +- A trademarked logo as an SVG (specific format requirements) +- A Verified Mark Certificate (VMC) from a CA, for Gmail and others +- A `_bimi` DNS record pointing to the SVG and VMC + +BIMI improves trust signals and engagement. Worth doing once DMARC enforcement is in place. + +### Step 8: Document and revisit + +Document the email architecture: +- Sending domains and subdomains +- Each ESP and what it sends +- DNS records for each +- Monitoring setup +- Escalation if deliverability degrades + +Revisit quarterly or when a new ESP is added. + +--- + +## Failure patterns + +Multiple SPF records. Two or more SPF records on the same domain breaks SPF. Combine into one. + +SPF DNS lookup limit exceeded. Too many `include:` directives or chained includes. Flatten or simplify. + +DMARC at `p=none` forever. Monitoring without enforcement. Spoofing remains easy. Move to enforcement. + +DMARC at `p=reject` too quickly. Legitimate mail bounces because alignment wasn't verified. Use the gradual rollout. + +Sending from a different domain than the From: address. Causes alignment failures. Fix the From: domain or ensure proper alignment. + +Using a shared ESP IP without ESP-specific configuration. Some ESPs don't sign with your DKIM by default; the signature is the ESP's, not yours. Configure custom DKIM. + +Sending from a domain that also sends marketing. A spam complaint on a marketing email hurts transactional deliverability. Use a subdomain for transactional (`transactional.example.com`) or marketing (`mail.example.com`). + +No bounce monitoring. Hard bounces accumulate, reputation tanks, deliverability cliff-falls. Monitor. + +Bought lists or scraped contacts. Spam traps in those lists destroy reputation. Don't. + +No double opt-in for marketing. Single opt-in lets bots and typos onto the list. Bots generate spam complaints, destroy reputation. + +Ignoring DMARC reports. Reports show problems early. Set up a parser. Look weekly. + +Treating "marked as not-spam" as the goal. The goal is to never land in spam in the first place. Once reputation is bad, recovery takes months. + +--- + +## Output format + +A deliverability audit document includes: + +- Domain inventory: every sending domain +- Authentication status: SPF, DKIM, DMARC per domain +- Sender inventory: every ESP or service that sends mail, what's configured +- Reputation status: per major mailbox provider where measurable +- List hygiene: bounce rate, complaint rate, opt-in process +- Findings: prioritized issues +- Roadmap: SPF/DKIM/DMARC fixes, BIMI plan, monitoring plan +- Monitoring setup: what's watched, where alerts go + +--- + +## Reference files + +- [`references/dmarc-rollout-playbook.md`](references/dmarc-rollout-playbook.md): Step-by-step for moving from no DMARC to `p=reject`, with timing, monitoring, and how to handle problems found along the way. diff --git a/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md b/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md new file mode 100644 index 0000000..bc3d319 --- /dev/null +++ b/dist/pi/.agents/skills/email-deliverability/references/dmarc-rollout-playbook.md @@ -0,0 +1,294 @@ +# DMARC Rollout Playbook + +A staged, low-risk path from no DMARC to full `p=reject` enforcement. Typical duration: 2-3 months. Rushing breaks things. + +--- + +## Why DMARC matters + +Without DMARC at enforcement, anyone can send email claiming to be from your domain. Phishing campaigns can spoof your brand to your customers, your investors, your own employees. + +DMARC at `p=reject` means mailbox providers will reject mail that fails authentication. The spoofing attacks fail. + +The goal of this playbook: get to `p=reject` without losing legitimate mail. + +--- + +## Prerequisites + +Before starting: + +- [ ] SPF is published, single record, under 10 lookups +- [ ] DKIM is published, every legitimate sender signs with your domain's key +- [ ] You have a DMARC report destination (a parsing service or your own endpoint) +- [ ] You have access to make DNS changes +- [ ] You know who is responsible for fixing email-related issues + +If any of these are missing, fix them first. DMARC enforcement on top of broken SPF or DKIM means losing legitimate mail. + +--- + +## Stage 1: Monitor (Week 1-2) + +### Goal +Discover every legitimate sender of mail from your domain. Many will be unexpected. + +### Action + +Publish DMARC at `p=none`: + +``` +v=DMARC1; p=none; rua=mailto:dmarc-aggregate@example.com; pct=100; adkim=r; aspf=r +``` + +Notes: +- `p=none`: no enforcement; mailbox providers report but take no action +- `rua=`: where aggregate reports go. Use a DMARC analytics service or your own endpoint +- `adkim=r`, `aspf=r`: relaxed alignment (less strict; eases initial rollout) + +### What to watch + +Aggregate reports start arriving from major mailbox providers within 24-48 hours. Reports are XML, daily, summarized. + +Look for: +- Every IP and sender sending mail "From: yourdomain" +- Pass/fail rates for SPF and DKIM +- Volume per sender +- Unexpected senders (often: a marketing tool, a customer support tool, a forgotten old service) + +### Common discoveries + +- Marketing ESP signing with their domain, not yours +- Internal tools sending email through unauthorized servers +- Help desk forwarding mail in a way that breaks alignment +- A SaaS notification service no one remembered +- Compromised accounts (rare but real) +- Spoofers trying to phish + +### Exit criteria + +- All legitimate senders identified +- All legitimate senders pass SPF or DKIM (ideally both) +- The volume of failing legitimate mail is well understood + +--- + +## Stage 2: Quarantine 10% (Week 3-4) + +### Goal +Begin enforcement on a small percentage. Watch for legitimate mail being affected. + +### Action + +Update DMARC to: + +``` +v=DMARC1; p=quarantine; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +Now 10% of failing mail goes to spam at supporting providers. 90% still passes through. + +### What to watch + +- Aggregate reports continuing to flow +- Customer reports of legitimate mail in spam +- Internal complaints (your own team is often the canary) + +### What to do if problems + +If a known-legitimate sender starts having mail quarantined: + +1. Identify the sender and the failure (SPF? DKIM? Alignment?) +2. Fix the sender (add to SPF, configure DKIM, fix alignment) +3. Verify the fix in subsequent reports +4. Continue + +If an unknown legitimate sender starts having mail quarantined: + +1. Investigate. Is this real legitimate use? (Internal tool? New SaaS?) +2. If yes, fix the authentication for it +3. If no, this is the spoofing DMARC is meant to stop + +### Exit criteria + +- Reports show no legitimate mail being quarantined +- Sustained for at least one week with no surprises + +--- + +## Stage 3: Quarantine 100% (Week 5-6) + +### Goal +Enforce quarantine for all failing mail. Build confidence before reject. + +### Action + +``` +v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 2 but expect higher volume of spam-foldered mail. Most should be illegitimate. + +### Exit criteria + +- No legitimate mail quarantined for at least one week +- Spoofing volume in reports is clearly visible (this is what DMARC is catching) + +--- + +## Stage 4: Reject 10% (Week 7-8) + +### Goal +Start rejecting failing mail. Fail-mode is harder than quarantine; legitimate mail that fails is bounced, not delivered to spam. + +### Action + +``` +v=DMARC1; p=reject; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +10% of failing mail is rejected. The other 90% goes to quarantine (the previous policy applies). + +### What to watch + +- Bounce rates from your sending tools (transactional and marketing) +- Customer reports of "I never got the email" +- Reports of legitimate mail being rejected + +If bounces spike, something legitimate is failing. Investigate immediately and consider rolling back. + +### Exit criteria + +- No spike in bounces or "didn't receive email" reports +- Sustained for at least one week + +--- + +## Stage 5: Reject 50% (Week 9-10) + +### Action + +``` +v=DMARC1; p=reject; pct=50; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 4. Legitimate failures will be more visible at higher percentage. + +### Exit criteria + +Same as Stage 4. No spike in legitimate mail rejection. + +--- + +## Stage 6: Reject 100% (Week 11+) + +### Goal +Full enforcement. Spoofing is now blocked. + +### Action + +``` +v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Continue monitoring reports. New senders, configuration drift, and changes in the email infrastructure can introduce new failures over time. + +### Maintenance + +- Review reports at least weekly +- Audit sender list quarterly +- Re-verify SPF and DKIM after any infrastructure change + +--- + +## Optional: Strict alignment + +After `p=reject` is stable, consider tightening alignment: + +``` +v=DMARC1; p=reject; pct=100; rua=...; adkim=s; aspf=s +``` + +Strict alignment requires the From: domain to match exactly (not just a parent domain). This catches subdomain spoofing too. + +Verify in monitoring mode (back to `p=none` with `adkim=s; aspf=s`) before enforcing. + +--- + +## Subdomain policy + +DMARC includes `sp=` for subdomain policy. Without it, subdomains inherit the main policy. + +For high-security applications: + +``` +v=DMARC1; p=reject; sp=reject; ... +``` + +This rejects spoofs on subdomains too. Important for parked or unused subdomains; an attacker can pick any subdomain by default. + +--- + +## Edge cases + +### Forwarders and mailing lists + +When mail is forwarded (e.g., user@oldcompany.com forwards to user@newcompany.com), SPF often fails (the forwarder is now the sender from SPF's view). + +DKIM survives forwarding if the message body isn't modified. Mailing lists that modify headers or add footers can break DKIM. + +Solutions: +- ARC (Authenticated Received Chain): restores authentication across forwards. Major providers support it. +- DKIM only (don't rely on SPF for DMARC alignment): if DKIM passes, DMARC passes regardless of SPF +- Mailing list software that's DMARC-aware + +### Bulk transactional providers + +Some providers (notification services, password reset emails) have hundreds of customers sharing IP space. Authentication usually requires custom domain setup; the default shared sending often fails alignment. + +Solution: configure the provider to use your domain for DKIM and From: address. Most providers offer "custom domain" or "sender authentication" features. + +### Email-on-acid testing services + +If you use email testing services that "send on your behalf" but don't authenticate, those will fail. Either configure them or accept the failure (they're not user-facing). + +--- + +## What can go wrong + +Legitimate mail starts bouncing. Roll back to the previous stage immediately. Investigate the failure. Fix. Try again. + +Spoofing complaints rise. Counterintuitively, after DMARC enforcement, you may see a temporary rise in complaints because spoofing that was previously delivered (silently spoofed your customers) now bounces (and the spoofer gets a bounce notification, then sometimes complains to the wrong place). This usually settles within a week. + +Volume of reports overwhelms. Reports are voluminous from large mailbox providers. Use a DMARC analytics service rather than parsing manually. + +Forensic reports (`ruf=`) flooding. Forensic reports include full message content of failures and can be high volume. Many use `rua=` (aggregate) only, especially after Stage 1. + +--- + +## Tools + +- Reporting/Analytics: Postmark, dmarcian, EasyDMARC, Valimail, Cloudflare Email Routing (free for some scenarios), or roll your own with a DMARC parser library. +- Testing: mxtoolbox.com, mail-tester.com, dmarcian.com. +- Lookups: `dig +short txt _dmarc.example.com`. + +--- + +## Timing summary + +\| Stage \| Policy \| Duration \| What you're doing \| +\|---\|---\|---\|---\| +\| 1 \| `p=none` \| 1-2 weeks \| Discovery \| +\| 2 \| `p=quarantine; pct=10` \| 1-2 weeks \| Initial enforcement \| +\| 3 \| `p=quarantine; pct=100` \| 1-2 weeks \| Full quarantine \| +\| 4 \| `p=reject; pct=10` \| 1-2 weeks \| Initial rejection \| +\| 5 \| `p=reject; pct=50` \| 1-2 weeks \| Half rejection \| +\| 6 \| `p=reject; pct=100` \| Ongoing \| Full enforcement \| + +Total: 6-12 weeks. Don't shortcut. The cost of moving slowly is low; the cost of breaking legitimate mail is high. diff --git a/dist/pi/.agents/skills/email-sequences/SKILL.md b/dist/pi/.agents/skills/email-sequences/SKILL.md new file mode 100644 index 0000000..e735886 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/SKILL.md @@ -0,0 +1,282 @@ +--- +name: email-sequences +description: "Design and write email campaigns and sequences including onboarding flows, lifecycle campaigns, transactional emails, newsletters, broadcast sends, and launch and announcement emails. Use this skill whenever the user wants to write email copy, plan an email sequence, design an onboarding drip, or set up lifecycle email campaigns. Triggers on email sequence, drip campaign, onboarding email, lifecycle email, welcome email, transactional email, newsletter, email broadcast, launch email, announcement email, nurture sequence, abandoned cart, re-engagement, win-back. Also triggers when planning email automation flows or writing email subject lines for campaigns." +category: content +catalog_summary: "Onboarding flows, lifecycle campaigns, transactional copy" +display_order: 5 +--- + +# Email Sequences + +Plan and write email campaigns. Sequences (multi-message flows triggered by events) and broadcasts (one-off sends). Stack-agnostic. Works with any email service provider. + +--- + +## When to use + +- Writing welcome and onboarding email sequences +- Planning lifecycle campaigns (activation, retention, win-back) +- Writing transactional emails (receipts, password resets, notifications) +- Newsletter design and writing +- Abandoned-cart or re-engagement flows +- Writing a one-off broadcast, launch announcement, or news email +- Drafting email subject lines and preview text for any send + +## When NOT to use + +- Landing pages and conversion pages (use `landing-page-copy`) +- Long-form articles (use `content-and-copy`) +- Brand voice work (use `brand-voice`) +- Analytics setup for email (use `analytics-strategy`) + +--- + +## Required inputs + +- The audience (segment or list) +- The trigger or context (signup, purchase, abandonment, time-based, manual) +- The goal of the email or sequence +- Brand voice +- Any technical constraints (provider, deliverability requirements) + +If the audience is undefined, define it before writing. Generic emails to "everyone" perform worse than targeted ones. + +--- + +## The framework: 6 sequence types + +Most email programs run a handful of standard sequence patterns. Each has its own goals, structure, and pitfalls. + +### 1. Welcome / onboarding + +Triggered by signup. Goal: get the user to first value. + +Typical structure (5 emails over 14 days): + +- Email 1 (immediate): Welcome. Confirm they're in. State what happens next. Single CTA: the next obvious action. +- Email 2 (day 1 or 2): First-value step. Help them get to a quick win or core action. +- Email 3 (day 4 or 5): Education. Show them something they probably haven't discovered yet. +- Email 4 (day 8): Social proof. Customer story or use case relevant to their segment. +- Email 5 (day 14): Outcome reminder. Where they could be in 30/60/90 days. Soft commercial cue. + +Common failure: Front-loading product features. Users don't care about features yet; they care about getting to value. + +### 2. Lifecycle / activation + +Time- or behavior-triggered. Goal: move users from signup to engaged user. + +Patterns: +- Sent when a user completes a milestone (first project, first invite, first export) +- Or sent when a user has NOT completed a milestone after N days +- Each email targets a specific next step + +Best practice: Trigger on behavior, not just time. A user who has done 3 onboarding steps doesn't need an email telling them to get started. + +### 3. Retention / engagement + +Ongoing. Goal: keep active users engaged. + +Patterns: +- Newsletter (weekly or monthly) +- Product updates +- Tips and tutorials +- Customer-only content (community, behind-the-scenes) + +Cadence rule: Frequency that earns the read, not frequency that fills the calendar. Weekly newsletter that is genuinely useful beats daily newsletter that gets archived. + +### 4. Re-engagement / win-back + +Triggered by inactivity. Goal: pull a lapsed user back. + +Typical structure (3 emails): + +- Email 1: "We miss you" framing or value reminder. What's new since they were last active. +- Email 2: Specific incentive (discount, feature unlock, content offer). +- Email 3: "Last call" or list-cleaning email. "We'll stop emailing you unless you click this." + +Best practice: Honor the unsubscribe. Aggressive win-back damages deliverability. A clean list of engaged subscribers beats a large list of inactive ones. + +### 5. Transactional + +Triggered by actions: receipts, password resets, notifications, order confirmations, shipping updates. + +Best practices: +- Confirm the action that triggered the email at the top +- Include all relevant detail without padding +- Use plain language ("Your order shipped" not "Your shipment notification") +- One primary CTA (track package, view receipt, view account) +- Subject line states the action ("Your receipt for order #12345") + +Highest open rates of any email type. Use sparingly for marketing nudges; over-marketing transactional emails damages trust. + +### 6. Broadcast + +One-off sends. Announcements, launches, news, time-sensitive campaigns. + +Best practices: +- Subject line earns the open +- Single clear message per send +- Specific audience targeting (do not blast the entire list for narrow announcements) +- Clear CTA in the first screen-height +- Mobile-optimized (most opens are mobile) + +--- + +## The 5 components of every email + +Regardless of sequence type, every email has the same components. + +### 1. Subject line + +The deciding factor for whether the email gets opened. + +Patterns: +- Specific ("Your week 1 progress: 3 of 5 steps done") +- Curiosity ("The mistake most teams make in week 2") +- Direct ("Your invoice #12345") +- Personal ("Quick question, [name]") +- Urgency ("Last day for the team plan discount") - use sparingly + +Avoid: +- ALL CAPS +- Excessive punctuation (!!!) +- Click-bait that doesn't deliver +- Generic ("Newsletter #23") + +Length: 30 to 50 characters. Mobile clients truncate longer. + +### 2. Preview text (preheader) + +The line that appears below or beside the subject in most email clients. + +Best practice: +- Treat as the subject's wingman +- Add what the subject line couldn't fit +- Avoid wasting it on "View this email in browser" +- 50 to 90 characters + +### 3. Opening + +The first line of the email body. The reader is deciding whether to keep reading. + +Strong openings: +- Reference the trigger ("You signed up yesterday for...") +- Get to the point ("Here's what changed this week...") +- Personal ("Saw your team just hit milestone X. Nice work.") + +Weak openings: +- "I hope this email finds you well." +- "Welcome to our amazing platform." +- Long throat-clearing before the actual content + +### 4. Body + +The substance. + +Length guide: +- Welcome and transactional: under 100 words +- Lifecycle and activation: 100 to 250 words +- Newsletter: 200 to 800 words depending on format +- Sales sequences: 250 to 500 words + +Structure: +- One core message per email (avoid "while we have you...") +- Short paragraphs (2 to 3 lines) +- Bullets or lists when content is enumerable +- Mobile-first formatting + +### 5. CTA + +The action the email is asking for. + +Best practices: +- One primary CTA per email (multiple CTAs split attention) +- Button or clearly-styled link, not buried in prose +- Action verb + specific outcome ("See your dashboard" not "Click here") +- Above the fold AND repeated at the end of longer emails +- Plain text link as a fallback for users who block buttons + +--- + +## Workflow + +### For a new sequence + +1. Define the trigger. What event starts this sequence? (Signup, purchase, abandonment, manual.) +2. Define the goal. What does success look like at the end of the sequence? +3. Map the journey. What does the recipient need to know, do, or feel between trigger and goal? +4. Outline emails. One purpose per email. Sequence them across appropriate timing. +5. Draft email 1. Subject, preview, opening, body, CTA. +6. Draft remaining emails. Each builds on the previous. +7. Test the sequence. Send to yourself. Read on mobile. Time the gaps. +8. Set up triggers. Configure in the email service provider. +9. Measure. Open rate, click rate, completion rate per email. Sequence completion rate. + +### For a single broadcast + +1. Define the audience. Specific segment, not the whole list. +2. Define the goal. One thing this email accomplishes. +3. Draft subject + preview. Generate 5 to 10 variations. +4. Draft body. Single message, clear CTA. +5. Test on mobile. Most opens are mobile. +6. Schedule. Day and time matched to audience behavior. +7. Measure. Open rate, click rate, downstream conversions. + +--- + +## Failure patterns + +- Sending to "everyone." Generic broadcasts to the full list have lower engagement than targeted segments. +- Too many CTAs in one email. Splits attention. Pick one. +- Subject line clickbait that doesn't deliver. Crashes the trust the email program is trying to build. +- Sequences that ignore behavior. Sending day-3 onboarding email to a user who already activated wastes the touch. +- Mobile-broken layouts. 60 to 70 percent of opens are on mobile. Test there first. +- Long pre-text. Burying the message under "I hope this email finds you well" wastes the read. +- Aggressive win-back. Emailing dormant users 5 times damages deliverability and brand trust. +- No measurement. Without tracking opens, clicks, and downstream conversion, you can't iterate. +- Ignoring deliverability. Sender reputation, authentication (SPF, DKIM, DMARC), list hygiene. Skip these and emails go to spam regardless of how good the content is. + +--- + +## Output format + +Default output is a markdown document per email or sequence: + +```markdown +# Sequence: [Name] + +Trigger: [What starts this sequence] +Goal: [Outcome at completion] +Audience: [Specific segment] +Length: [N emails over X days] + +## Email 1 - [Subject working title] + +Send: [Trigger / Day N] +Subject: [text] +Preview: [text] + +[Body] + +Primary CTA: [text] +CTA URL: [destination] + +--- + +## Email 2 - [Subject working title] + +[Same structure] + +--- + +[etc.] +``` + +For a single broadcast, just one email block. + +--- + +## Reference files + +- [`references/subject-line-patterns.md`](references/subject-line-patterns.md) - Subject line patterns with examples for each sequence type. +- [`references/sequence-templates.md`](references/sequence-templates.md) - Skeleton templates for the 6 sequence types. diff --git a/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md b/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md new file mode 100644 index 0000000..ac0ca87 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/references/sequence-templates.md @@ -0,0 +1,252 @@ +# Sequence Templates + +Starter outlines for the 5 standard sequence types. These are scaffolds. Adapt the cadence, voice, and content to the specific brand and audience. + +--- + +## Onboarding sequence (SaaS, 7 emails over 14 days) + +### Email 1 - Welcome +Send: Immediately on signup +Subject: Welcome to [Product]. Here's your first step. +Body skeleton: +- One-line welcome +- Restate the outcome they signed up for +- ONE clear next step +- Optional: founder note for early-stage products + +### Email 2 - First action tutorial +Send: T+1 day +Subject: [Specific first task] in 5 minutes +Body skeleton: +- Hook: Why this first task matters +- 3 to 5 numbered steps +- Visual or screenshot +- CTA back to the product + +### Email 3 - Build on first +Send: T+3 days +Subject: Now that [first task done], try [second task] +Body skeleton: +- Acknowledge progress (works even if user hasn't done first task; it primes them) +- Introduce next capability +- Show what it unlocks +- CTA + +### Email 4 - Use case spotlight +Send: T+5 days +Subject: How [persona] uses [Product] to [outcome] +Body skeleton: +- Specific persona description +- Their workflow with the product +- Specific result +- "Try this approach" CTA + +### Email 5 - Common questions +Send: T+7 days +Subject: Quick answers to questions new users ask +Body skeleton: +- 3 to 5 FAQs with brief answers +- Links to fuller help docs +- CTA: open help center or chat with support + +### Email 6 - Re-engagement check +Send: T+10 days (only if user is dormant) +Subject: Need a hand getting started? +Body skeleton: +- Acknowledge they may be busy +- Offer a 10-minute call or specific resource +- One simple action they can take in <2 minutes + +### Email 7 - Hand-off to ongoing comms +Send: T+14 days +Subject: You're set up. Here's what to expect from us. +Body skeleton: +- Confirm onboarding complete +- Set expectations for future emails (frequency, content type) +- Offer preferences center +- Light next-step CTA + +--- + +## Lifecycle (triggered, individual emails) + +### Anniversary (annual) +Subject: Hard to believe - it's been a year +Body: Celebrate the milestone, surface specific achievements ("You shipped X projects this year"), suggest next-level use case. + +### Plan upgrade nudge +Subject: You're hitting your [Plan] limits +Body: Specific data showing usage approaching limits, value of next tier, painless upgrade path. + +### Inactivity check (30 days dormant) +Subject: We haven't seen you for a bit +Body: Light touch, restate value, surface a recent improvement, easy way to come back. + +### Power user celebration (Y key actions) +Subject: You've crossed [Y] [actions]. Nice. +Body: Acknowledge the milestone, share advanced tips, invite to community or beta. + +### Feature announcement (when relevant feature ships) +Subject: New: [feature] +Body: What it does, why we built it, how to start using it. Brief. + +--- + +## Sales nurture (B2B, 9 emails over 28 days) + +### Email 1 - Deliver the asset +Send: Immediately on opt-in +Subject: Your [asset name] +Body: Direct download link, brief intro to what's inside. + +### Email 2 - Educational angle +Send: T+2 days +Subject: [Specific question the audience asks] +Body: Useful content piece tied to their problem. No pitch. + +### Email 3 - Educational angle (different facet) +Send: T+4 days +Subject: [Adjacent question] +Body: Different angle on the same problem space. + +### Email 4 - Customer story +Send: T+7 days +Subject: How [Customer] [achieved specific outcome] +Body: Specific company, specific outcome, specific approach. Their story, with brand as supporting role. + +### Email 5 - Objection handling +Send: T+10 days +Subject: "I'm not sure [common objection]" +Body: Address the most common reason this audience hesitates. Honest, non-defensive. + +### Email 6 - Demo invitation +Send: T+14 days +Subject: Want to see [Product] in action? +Body: 20-minute personalized demo offer. Specific outcome the demo will show. + +### Email 7 - Strong proof + soft pitch +Send: T+18 days +Subject: [Specific result] in [specific time] +Body: Strongest case study, direct invitation to start a trial or call. + +### Email 8 - Urgency +Send: T+21 days +Subject: [Deadline or limited offer] +Body: Clear offer with deadline. Real urgency only - manufactured urgency damages trust. + +### Email 9 - Goodbye +Send: T+28 days +Subject: Last note from us +Body: Acknowledge the silence. Offer one last resource or chance to opt back in. Then suppress or move to long-term nurture list. + +--- + +## Transactional templates + +### Order confirmation +Subject: Your order #[number] is confirmed +Body: +- Order summary (items, totals, shipping address) +- Estimated delivery +- Order tracking link +- Support contact + +Keep marketing minimal. People are looking for specific info. + +### Password reset +Subject: Reset your password +Body: +- Brief acknowledgment of the request +- Reset link (with expiration time stated) +- "Did not request this?" instruction +- Support contact + +No marketing in transactional. Keep it clean. + +### Email verification +Subject: Verify your email +Body: +- One-line ask +- Big verify button +- "If you did not sign up..." opt-out +- Expiration time + +### Abandoned cart +Subject: You left these in your cart +Body: +- Items left in cart with images +- Quick-resume link +- Optional: incentive (free shipping, small discount) +- Support contact + +Send 1 email at T+1 hour, optional second at T+24 hours, NO third email (annoyance penalty exceeds recovery). + +--- + +## Win-back (5 emails over 20 days) + +### Email 1 - We miss you +Subject: Hey, it's been a while +Body: Acknowledge the lapse, brief reminder of what's possible, soft re-engage CTA. + +### Email 2 - What's new +Subject: A few things have changed since you were last here +Body: Updates, new features, recent improvements. Specific. + +### Email 3 - Specific incentive +Subject: Come back: [specific offer] +Body: Concrete incentive (discount, bonus, free month). Deadline. + +### Email 4 - Last chance +Subject: Last call: [offer ends X] +Body: Final reminder of the offer. Clear deadline. + +### Email 5 - Sunset +Subject: We'll miss you +Body: Acknowledge they're not coming back, confirm we're stepping down sends, leave the door open. + +After this email: suppress from active sends. Optional: move to a quarterly "big news only" list. + +--- + +## Cadence rules across all sequence types + +- Default time of day: 8 to 10 AM in the recipient's timezone for non-time-sensitive sends. +- Avoid send fatigue: Cap at 2 emails per week from the same brand to the same person across all programs. +- Respect engagement: If a user has opened zero of the last 5 emails, throttle frequency or sunset. +- Honor unsubscribes immediately: Same-day, all programs, no exceptions. +- Test sending: Send tests to 5+ devices before any sequence goes live. + +--- + +## Subject line patterns that work + +- Specific question: "Why your churn rate isn't moving" +- Specific number: "47% of B2B buyers do this before purchasing" +- Personal/conversational: "Quick question about [topic]" +- Curiosity gap: "The mistake we see in 80% of pricing pages" +- Negative framing (sparingly): "Don't make this mistake on your next launch" +- Direct value: "Free template: 90-day onboarding checklist" + +Avoid: + +- Subject lines that look like spam (all caps, multiple exclamations) +- Misleading subject lines (mentions in subject that aren't in body) +- Tricks ("Re:" or "Fwd:" on cold sends) +- Subject lines longer than 50 characters where avoidable + +--- + +## Metrics to track per sequence + +\| Metric \| Target benchmark (rough) \| +\|---\|---\| +\| Open rate \| 20 to 35% (varies wildly by industry) \| +\| Click-through rate \| 2 to 5% \| +\| Conversion to goal \| Sequence-specific \| +\| Unsubscribe rate per email \| <0.5% \| +\| Spam complaint rate \| <0.1% \| +\| Reply rate (for cold/B2B) \| 1 to 3% \| + +Below benchmark: investigate the weakest emails in the sequence first. Above: capture what worked and apply to other sequences. diff --git a/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md b/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md new file mode 100644 index 0000000..2df7648 --- /dev/null +++ b/dist/pi/.agents/skills/email-sequences/references/subject-line-patterns.md @@ -0,0 +1,298 @@ +# Subject Line Patterns + +Subject lines are the deciding factor for opens. A great email with a weak subject gets archived unread. + +These patterns are tools, not formulas. Apply them, then make them sound like the brand. + +--- + +## Universal rules + +- Length: 30 to 50 characters. Mobile clients truncate longer. +- No ALL CAPS. Reads as shouting and triggers spam filters. +- No excessive punctuation. "!!!" reads as desperate. +- Match the body. A subject that doesn't deliver in the body kills trust. +- Sentence case is more readable than Title Case in inboxes. +- Skip the prefix conventions ("Newsletter #23"). Subscribers ignore them. + +--- + +## Pattern 1: Specific outcome + +Names what the reader gets. + +Examples: +- "The 5 questions to ask before hiring a designer" +- "Your team's productivity numbers for September" +- "How to cut your invoicing time in half" +- "What changed in your competitor's pricing this month" + +Strengths: Clear value. Easy to evaluate whether to open. + +When to use: Newsletters, content emails, value-driven sends. + +--- + +## Pattern 2: Curiosity gap + +Opens a loop the email body closes. + +Examples: +- "The mistake most teams make in week 2" +- "Why your best customers are leaving" +- "The one habit your top performers share" +- "What I wish I'd known before scaling to 50 people" + +Strengths: High open rates when the gap is genuine. + +Risks: Becomes click-bait if the body doesn't deliver. Erodes trust over time. + +When to use: Sparingly. The body must deliver real insight. + +--- + +## Pattern 3: Personal / direct + +Speaks as if to a friend. + +Examples: +- "Quick question, [name]" +- "Saw this and thought of you" +- "Got 5 minutes?" +- "Are you still using [tool]?" + +Strengths: Feels human. Cuts through marketing-speak. + +Risks: Used by every spam email. Authentic context required for it to work. + +When to use: 1:1 sends, personalized cold outreach, founder-to-customer emails. + +--- + +## Pattern 4: Direct / no-mystery + +States exactly what the email is about. + +Examples: +- "Your receipt for order #12345" +- "Password reset link" +- "Invoice for September" +- "Meeting confirmation: Tuesday 2pm" + +Strengths: High trust. High open rates for transactional content. + +When to use: Transactional emails. Always be direct. + +--- + +## Pattern 5: Question + +Poses the question the reader is asking. + +Examples: +- "Should you hire a generalist or specialist first?" +- "Is your pricing too cheap?" +- "What's the ROI of customer service?" +- "Are you measuring the wrong KPIs?" + +Strengths: Aligns with the reader's mental state. Strong for educational content. + +When to use: Newsletters and educational sequences. + +--- + +## Pattern 6: Number / list + +Promises a specific quantity of items. + +Examples: +- "3 things to do this week to retain customers" +- "7 signs your team is about to burn out" +- "The 4-step checklist for a clean handoff" + +Strengths: Sets clear expectations. Easy to scan. + +Risks: Overused. Can read as listicle filler. + +When to use: When the content genuinely is a list and the count matters. + +--- + +## Pattern 7: Time-bound / urgency + +Signals the email is time-sensitive. + +Examples: +- "Last day: free shipping on your order" +- "Webinar starts in 2 hours" +- "Pricing changes Thursday" + +Strengths: Drives immediate action. + +Risks: Overuse trains subscribers to ignore urgency cues. Reserve for genuine deadlines. + +When to use: Real time-sensitive sends only. Never fake urgency. + +--- + +## Pattern 8: News / update + +States what's new. + +Examples: +- "New: instant export to spreadsheets" +- "Just launched: team mode" +- "Update on the integration you asked for" + +Strengths: Useful for product update emails. + +When to use: Real product announcements that the recipient signed up to hear about. + +--- + +## Pattern 9: Personal anecdote / story + +Hints at a story. + +Examples: +- "I almost didn't ship this" +- "What happened when we tried [thing]" +- "The phone call that changed our hiring process" + +Strengths: Strong for narrative-driven brand newsletters. + +When to use: When the brand voice supports storytelling. + +--- + +## Pattern 10: Reference to recipient's behavior + +Acknowledges what they did. + +Examples: +- "Saw you tried [feature] - here's what's next" +- "Welcome back. Here's what you missed." +- "You completed week 1. Here's week 2." + +Strengths: Personalization that actually feels personal. + +When to use: Behavior-triggered emails. Lifecycle and onboarding sequences. + +--- + +## Subject lines by sequence type + +### Welcome / onboarding + +``` +Email 1: Welcome to [Brand], [name] +Email 2: The first thing to do in [Brand] +Email 3: How [audience] use [Brand] (3 examples) +Email 4: Did this happen for you? +Email 5: 30 days in: where you could be +``` + +### Lifecycle / activation + +``` +Trigger: completed milestone +"Nice work hitting [milestone]. Here's what's next." + +Trigger: stalled on a step +"Quick question about your setup" +``` + +### Re-engagement / win-back + +``` +Email 1: Hey [name], we miss you +Email 2: Here's [specific incentive] +Email 3: Last email - should we say goodbye? +``` + +### Newsletter + +``` +Curiosity: "The metric most teams ignore" +Specific: "September wrap: what we shipped, what we learned" +Question: "Should you raise your prices?" +Number: "3 reads from this week" +``` + +### Transactional + +``` +"Your order is on the way (#12345)" +"Receipt for your subscription" +"Your password was changed" +"Action required: confirm your email" +``` + +### Broadcast + +``` +Launch: "Just shipped: [feature]" +Event: "Live this Thursday: [topic]" +Update: "Our pricing changed today. Here's what it means for you." +``` + +--- + +## A/B test ideas + +Subject lines are the easiest thing to test. For any meaningful send, generate 2 to 4 variations along these axes: + +- Specific vs. curiosity: Does the audience prefer to know what they're getting, or to be intrigued? +- Personal vs. direct: Does first-person ("I just shipped this") work better than third-person ("Just launched")? +- Length: Short (under 30 chars) vs. medium (30 to 50 chars). +- Punctuation: Question vs. statement. +- Personalization: With name vs. without. + +Track open rates and click-through rates. Open alone is incomplete; some subject patterns get opened but discarded. + +--- + +## What to avoid + +### "Just checking in" +Empty. Adds no value. Reads as nag. + +### "Following up" +Same problem. The reader knows you're following up. Tell them why. + +### "Thoughts?" +A request without context. Comes across as lazy. + +### "Hi" +Just don't. Even from someone you know. + +### Excessive emojis +🎉🚀✨ does not signal value. Often signals spam to filters. + +### Re: when it's not actually a reply +Deceptive. Damages trust. + +### Personalization gone wrong +"{first_name} wanted to chat" with the variable un-rendered. Test send before broadcast. + +--- + +## Preview text (preheader) + +The line that appears next to or below the subject. Often more important than the subject for engagement. + +Best practice: +- Use it as the subject's continuation +- 50 to 90 characters +- Don't waste it on "View in browser" or boilerplate +- Add the detail the subject didn't fit + +Examples of subject + preview pairs: + +\| Subject \| Preview \| +\|---\|---\| +\| "Your week 1 progress" \| "3 of 5 steps complete. Here's what's next." \| +\| "The mistake most teams make" \| "(It's not the obvious one)" \| +\| "Just shipped: team mode" \| "Invite up to 50 teammates and assign roles." \| + +A weak preview wastes prime real estate. A strong preview can save a mediocre subject. diff --git a/dist/pi/.agents/skills/experiment-design/SKILL.md b/dist/pi/.agents/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..c858add --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/SKILL.md @@ -0,0 +1,255 @@ +--- +name: experiment-design +description: A discipline for designing experiments (A/B tests, multivariate, holdouts) so the results actually answer the question you asked. Hypothesis writing, sample size, duration, segment analysis, interpretation, decision-making, and the common failure modes that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Hypothesis to decision: sample size, duration, segment analysis, interpretation, and the failure modes that produce wrong shipping calls" +display_order: 4 +--- + +# Experiment Design + +A senior product manager's playbook for running experiments that produce trustworthy decisions. + +The default state of experimentation in most companies is sloppy. PMs run tests against vague hypotheses, look at results too early, ignore guardrails, stratify into noise, and ship features whose lift is mostly measurement error. The cost is real: ship the wrong thing, kill the right thing, learn the wrong lesson, repeat. + +This skill is the discipline that prevents most of those mistakes. It assumes you have a working experimentation platform (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon; the platform does not matter for the principles). It assumes you have product-design and engineering pipelines that can deliver real treatment changes. The hard part is the thinking, and that is what is here. + +When to use this skill: any time you are about to design or interpret an experiment. Read the relevant section before you start, not after the test is running. + +--- + +## What this skill covers + +The skill spans the full experiment lifecycle. Pre-experiment readiness (is this thing even worth testing). Hypothesis design (cause, effect, magnitude, mechanism). Sample size and minimum detectable effect (do you have enough traffic to learn anything). Duration (how long is long enough, when does the cycle bias the result). Running discipline (no peeking, guardrails, sequential testing). Interpretation (the three buckets and the inconclusive case). Decision-making (matching the result to a pre-committed rule). + +The skill does not cover feature flag operational mechanics; those live in the `feature-flagging` skill, which handles flag taxonomy, environment management, and stale-flag cleanup as a separate discipline. The skill does not cover statistical analysis depth; for delta methods, variance reduction techniques like CUPED, and Bayesian alternatives, see the `experimentation-analytics` skill. The skill does not cover platform-specific tooling; for MCP commands, auth models, and platform-specific configuration, consult the chosen platform's official documentation. This skill produces the experiment design; the platform implements it. + +For the orchestration layer above (which experiments to run, in what order, with what cadence), see the forthcoming `experimentation-platform-orchestrator` skill. That skill schedules; this skill designs. + +--- + +## The framework: 12 considerations for trustworthy experiment results + +A defensible experiment design sits at the intersection of twelve considerations. Each is covered in detail in its own section below. + +1. Hypothesis discipline. Cause, effect, magnitude, and mechanism. The hypothesis names what is being tested, what should move, by how much, and why. +2. Sample size and minimum detectable effect (MDE). Whether the test has enough traffic to detect the effect at the chosen power. Refuse to run underpowered tests. +3. Test duration. Longer of the sample-size-hit duration and a full weekly cycle. UI/UX changes need at least 14 days regardless. +4. What NOT to A/B test. UX bugs, legal-required changes, brand-philosophy questions, decisions already made, designs whose randomization cannot be clean. +5. Segment analysis. Pre-registered segments are evidence; post-hoc segments are noise mining. The multiple comparisons problem is real. +6. Interaction effects. Concurrent tests on the same surface can interfere. Mutex enforcement or coordination required. +7. Ratio metrics and variance estimation. Naive variance estimators on ratios understate uncertainty. Confirm the platform uses a ratio-aware estimator. +8. Network effects and two-sided markets. Treatment can leak into control via interference. Cluster randomization, switchback, or geographic isolation when needed. +9. Sequential testing and the peeking problem. Daily peeking inflates false positive rates. Use sequential testing methods when available; pre-commit otherwise. +10. Pre-commitment vs p-hacking. Write down the primary metric, MDE, duration, segments, and decision rule before launch. Apply mechanically when results come in. +11. Reading results and making the call. Three buckets: clear win, clear loss, inconclusive. The inconclusive bucket exists for a reason; resist the pull to ship anyway. +12. Common failures and fixes. A short rapid-fire pattern catalog, expanded in [`references/common-failures.md`](references/common-failures.md). + +The sections below cover each consideration in turn. Read the relevant section before running the experiment, not after. + +--- + +## Hypothesis discipline + +The most important section in the skill. Most experiment failures trace back to a vague hypothesis. + +A real hypothesis has four parts: cause, effect, magnitude, mechanism. Cause is the change you are making. Effect is the metric you expect to move. Magnitude is how much you expect it to move and from what baseline. Mechanism is why you expect this change to produce this effect. + +Bad hypothesis, common shape: "We think the new pricing page will increase conversions." What is wrong with it: no magnitude (how much), no mechanism (why), and the metric is "conversions" rather than a specific event with a clear definition. The team will run this test, look at the result, and argue about what counts as a win. Pre-commitment is impossible because nothing was committed. + +Good hypothesis, same domain: "Replacing the three-tier pricing comparison with a single recommended tier will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe." Cause is the tier replacement. Effect is signup-to-paid conversion, defined as the user reaches the paywall and completes payment within seven days. Magnitude is 8 percent relative lift, taking the rate from 12 to 13 percent absolute. Mechanism is decision friction reduction. Now the team has something to test, a number to hit, and a story to falsify. + +Primary metric vs guardrails. The primary metric is the thing you are trying to move. Guardrails are the things that must not break: revenue, retention, support ticket volume, page load time, error rates. Pick exactly one primary metric. Pick three to five guardrails. Multiple primary metrics destroy the discipline because they let you cherry-pick the favorable one when results come in. + +Falsifiability test. Before launching the experiment, write down what would make you NOT ship this. If the answer is "nothing, we are committed to the change regardless," the hypothesis is not real and the experiment is theater. Skip the test, save the engineering time, and just ship the change. + +Directional vs magnitude distinction. Knowing the change moves the needle is different from knowing it moves the needle enough to matter. A 0.3 percent absolute lift on signup conversion may be statistically significant with enough traffic and still not justify the engineering cost of maintaining the change. Magnitude matters as much as direction; the hypothesis names the magnitude that would justify shipping. + +For templates and worked examples across common metric types, see [`references/hypothesis-templates.md`](references/hypothesis-templates.md). + +--- + +## Sample size and minimum detectable effect + +Sample size grows with the inverse square of the effect you want to detect. Detecting a 1 percent lift requires roughly one hundred times the sample needed to detect a 10 percent lift. Most PMs underestimate this. + +The basic decision rule: if your minimum detectable effect (MDE) at current traffic and a reasonable test duration is greater than 5 percent absolute lift, you probably need a bigger MDE. Tiny changes that need huge samples to detect are usually not worth shipping anyway. The change is small either because the underlying mechanism is weak or because the implementation is timid. A weak mechanism is not worth a launch. A timid implementation should be made bolder before testing. + +The "we do not have enough traffic" trap. Real for very small products. Lazy for everyone else. If you have ten thousand users a week and you are trying to detect a half-percent absolute lift, you are not running an experiment, you are sampling noise. Pick changes whose expected effect is large enough to detect at your traffic level. If the change is genuinely small, ship it without a test (small upside, small downside, low cost) or do not ship it at all. + +Power. The test's ability to detect an effect that is actually present. The conventional floor is 80 percent. Below that, you are rolling dice; the test will frequently miss real effects. Higher power costs more sample. Most platforms default to 80; if you change it, document why. + +One-sided vs two-sided. Most PM tests are two-sided despite the temptation to claim otherwise. A one-sided test says "I only care about the positive direction; if the change makes things worse, I do not need to detect it." That is rarely true. If the new pricing page tanks conversion, you want to know. Default to two-sided. If you genuinely want one-sided, document the asymmetry before running. + +For pre-calculated sample size tables across common conversion rate baselines and MDEs, see [`references/sample-size-tables.md`](references/sample-size-tables.md). The tables are starting points, not substitutes for running the math against your specific traffic and metric. + +--- + +## Test duration + +Minimum duration is the longer of two constraints. Constraint one: the sample size hits the calculated requirement. Constraint two: the test runs at least one full weekly cycle. Testing only Monday through Wednesday misses weekend behavior, which on most consumer products differs meaningfully from weekday behavior. + +Novelty effects. New things attract attention. The first few days of a winning test often overstate the lift. Users notice the change, click it, and produce a temporary effect that fades as the novelty wears off. Run long enough to see if the lift survives the novelty period. Two weeks is the conventional minimum for any UI/UX experiment, even if the sample size hits faster. + +Primacy effects. The opposite problem. Existing users may resist the change in week one and adapt by week three. Common in UI rearrangement tests. Killing the test in week one because the result looks negative misses the point that primacy is bigger than the underlying effect at that timescale. + +Holdout periods. If the experiment changes a permanent feature (notification frequency, default settings, search ranking), keep a holdout group OFF the new behavior for at least a month after launch. The holdout measures long-term effect, not just the day-1 lift. Long-term effects are often different from short-term effects: a notification change that increases day-1 engagement may decrease month-three retention. + +Maximum duration. Usually four to six weeks. Beyond that, the world changes around the test. Seasonality shifts. Marketing campaigns launch. The product evolves. The comparison between treatment and control stops being clean because the underlying user population is no longer comparable across the test window. If the test needs to run longer than six weeks to hit power, the MDE is probably wrong; the change is too small to detect cleanly. + +--- + +## What NOT to A/B test + +This is a section many discussions of experimentation skip. Worth being direct about. + +UX bug fixes. If the current behavior is objectively broken (button does not work, copy says the wrong thing, accessibility fails), fix it. A/B testing it is theater. The right answer is not "let's see if our users prefer a working button"; the right answer is to ship the working button. + +Legal-required changes. GDPR consent flows, accessibility compliance, regulatory disclaimers. Ship them. The lift is irrelevant; the compliance is the point. A/B testing whether to comply with the law is not a serious question. + +Strategic or philosophical brand questions. "Should our voice be playful or serious?" is not an A/B test question; it is a brand strategy question that needs to be made by humans with context, weighed against brand equity, audience expectation, and long-term positioning. Picking the variant with the higher click-through rate does not answer it because click-through rate was not the brand decision. Use the experiment data as one input to the brand decision, not as the decision itself. + +Things you have already decided. If leadership has committed to a direction regardless of test result, do not run an experiment. A/B testing as theater (running tests where the outcome does not change the decision) corrodes trust in the experimentation discipline overall. Other PMs see the test, see the result ignored, and conclude that experiment results do not matter at this company. Then they stop pre-committing. Then the discipline collapses. + +Things where the test design is impossible. Cross-device experiences, network effects, internal tooling for a ten-person ops team, anything where the sample size is fundamentally too small or the randomization is fundamentally contaminated. Sometimes the right answer is qualitative research, longitudinal cohort analysis, or just shipping and watching. An experiment that cannot be designed cleanly will not produce a clean answer. + +--- + +## Segment analysis + +Pre-registered segments versus post-hoc segments. Declaring before the test runs that "we will look at the result for new users versus returning users" is fine. Discovering after the test that "users from California who signed up on Tuesdays via mobile" had a huge lift is almost always noise mining. + +The multiple comparisons problem. Every additional segment you analyze increases the probability of finding a "significant" result by chance. With twenty independent segments at p equals 0.05, you expect one false positive purely by chance. With fifty segments, two or three. Do not analyze fifty segments and report the one that hit significance. + +When stratification helps versus misleads. Stratification is useful when three things are true. The segment was pre-registered. There is a real prior reason to expect different behavior in this segment. There is enough sample within the segment to detect the effect at the chosen power. If any of the three is missing, stratification is noise mining. The default posture should be: report the overall result. Report pre-registered segments as additional context. Do not report unplanned segments. + +The "weighted average" reframe. If a treatment is positive for one segment and negative for another, the right question is "what is the weighted average effect across the population we will actually ship to" not "let's just ship to the segment where it works." Shipping to a segment usually requires UI complexity, audience targeting infrastructure, and ongoing maintenance that the segment-specific lift does not justify. The bias against segment-specific shipping is healthy. + +--- + +## Interaction effects + +The classic problem: you are running five concurrent A/B tests on the checkout flow. Each test individually shows a small lift. Together, the combinations may not multiply cleanly. They may not even sum cleanly. They may interfere in ways the individual tests cannot reveal. + +Pre-experiment hygiene. Before launching a new experiment, check what other experiments are running on the same surface. Ask the other PM owners. Coordinate on which tests are mutually exclusive and which can overlap. + +Mutex (mutually exclusive) experiment groups. Most platforms support exclusion rules so users in test A are not also in test B. Use them when interactions are likely. The cost is sample size; the benefit is interpretable results. For a small set of high-stakes tests, mutex is the right call. For dozens of lower-stakes tests, full mutex is impractical; coordinate and document overlap instead. + +The "we will analyze it later" fallacy. Post-hoc detangling of overlapping experiments is hard, expensive, and usually inconclusive. The factorial design that would isolate interaction effects requires sample sizes most products do not have. Coordinate up front rather than untangle afterwards. + +--- + +## Ratio metrics and the delta method + +The trap. Conversion rate is a ratio: conversions divided by users. Standard deviation calculations for raw counts do not apply directly to ratios. A naive variance estimate on a ratio metric tends to be too narrow, leading to overstated confidence and false-positive ship decisions. + +Why it matters. Many experimentation platforms quietly use the delta method (or bootstrap, or some other ratio-aware estimator) for ratio metrics. If yours does not, your confidence intervals are wrong. Wrong in the direction that matters: you ship things that look significant but are not. + +How to check. Ask your platform vendor: "What is your variance estimator for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (converted yes or no, with one row per user). If the answer is "delta method" or "bootstrap with re-sampling at the user level" or "linearization with Taylor expansion," that is correct. Other reasonable answers exist; the test is whether the platform team can articulate a ratio-aware estimator at all. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. RPU lift estimates that do not use a ratio-aware estimator tend to overstate confidence. A 5 percent reported lift with p equals 0.04 might actually be a 5 percent point estimate with no statistical significance once the variance is computed correctly. Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production. + +For deeper coverage of variance reduction (CUPED, stratified sampling, control variates), see the `experimentation-analytics` skill when it ships. + +--- + +## Network effects and two-sided markets + +The interference problem. In a two-sided marketplace (Uber, Airbnb, eBay, DoorDash, any platform with buyers and sellers), a treatment for buyers may affect sellers regardless of which group is in the test. A treatment that increases buyer demand changes seller behavior. The "control" buyers, who are competing for the same sellers, see different supply because of treatment buyers' actions. The test no longer measures the treatment effect cleanly; it measures treatment effect plus interference. + +Common pattern. Marketplace experiments where the control group is contaminated. The test reports a small effect because half the effect leaked into the control. The team underestimates the true effect, kills a winning idea, and learns the wrong lesson. + +Mitigations, none perfect. Cluster randomization assigns whole markets (cities, regions, market segments) to treatment or control rather than individual users. Eliminates within-cluster interference but reduces effective sample size by orders of magnitude. Switchback experiments alternate the entire population between treatment and control across time windows (week 1 treatment, week 2 control, week 3 treatment, etc.). Eliminates cross-user interference but requires careful temporal modeling. Geographic isolation runs the experiment in one city while keeping the rest of the network on the original behavior. Eliminates interference but is expensive and slow. + +When to call qualitative. If interference is severe and randomization cannot isolate it, the test will not tell you what you want to know. Switch to user research, longitudinal cohort analysis, or a phased rollout with careful instrumentation. The decision is "do we believe this works enough to invest in the rollout monitoring" rather than "did the lift hit significance." + +--- + +## Sequential testing and the peeking problem + +The peeking problem. If you check results every day and stop the test as soon as you see significance, your false positive rate is much higher than the nominal 5 percent. Standard statistical tests assume one analysis at the end of the test. Multiple analyses inflate alpha. + +The math. With one analysis, false positive rate is 5 percent (at alpha equals 0.05). With three analyses spread across the test, false positive rate climbs toward 14 percent. With daily peeking on a 28-day test, false positive rate can exceed 30 percent. You will see "significant" results that are not real, ship them, and watch them fail to replicate in production. + +Sequential testing methods. Most modern platforms (Statsig, Eppo, parts of PostHog, GrowthBook with mSPRT) support sequential testing that adjusts the math to allow daily peeking without inflating alpha. The methods include sequential probability ratio tests, group sequential designs, and always-valid p-values via mixture sequential probability ratio tests (mSPRT). Use them when the platform offers them. They cost some statistical power in exchange for valid mid-test inference. + +Pre-registered stopping rules. If the platform does not support sequential testing, declare the planned analysis date before the test runs. Save the pre-commitment. Do not look at results until that date. If you must look (some platforms make it hard not to), do not make decisions based on what you see. The decision happens at the pre-committed analysis date, not when the early peek looks favorable. + +The "ship early because results look great" trap. Results almost always look more dramatic on day 3 than they do at day 14. Regression to the mean kicks in. Novelty fades. The metric stabilizes. The tests that survive the full window and still look great are the ones worth shipping. The ones that "looked great early" and were shipped early are disproportionately the ones that disappointed in production. + +--- + +## Pre-commitment vs p-hacking + +The p-hacking inventory. Things people do, often unconsciously, when results do not come out the way they hoped: + +- Run additional segments until something hits significance +- Drop "outliers" until the headline result moves +- Switch the primary metric mid-flight +- Extend the test duration "just a bit longer" +- Reframe the hypothesis to match what the data showed +- Combine multiple inconclusive tests into a "directional pattern" that justifies shipping + +Each individually feels like a small judgment call. Cumulatively they destroy the discipline. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +The pre-commitment fix. Before the test runs, write down: the primary metric and how it is computed; the MDE you are powered to detect; the duration in calendar days; the segments you will analyze (if any); the decision rule that maps each possible result to a ship or kill. Save the pre-commitment somewhere with a timestamp. The PR description that ships the experiment configuration. A signed Slack message. A pinned ticket. Anywhere that makes it immutable. + +When the results come in, follow the pre-commitment. If the result was clean and you want to ship, file the launch. If the result was bad and you want to kill, kill. If the result was inconclusive, follow the inconclusive resolution path described below; do not invent new analyses. + +The "we learned so much" trap. If the test ran and produced an inconclusive result, the answer is "inconclusive." Not "we learned that the underlying mechanism is more nuanced than expected" or "we discovered a fascinating segment dynamic." Inconclusive is inconclusive. The lesson, if there is one, is for the next hypothesis, not retrofitted onto this one. + +--- + +## Reading results and making the call + +Three buckets. Clear win: ship. Clear loss: kill. Inconclusive: the hardest case. + +Inconclusive resolution paths, ranked from most acceptable to least: + +1. Ship anyway because the change is cheap and reversible (defensible only if guardrails are clean and you genuinely have no information that the change is harmful). The bar here is high; "the directional movement was favorable" is not enough. +2. Run a bigger version: more traffic, longer duration, larger MDE if the change can be made bolder. Use the inconclusive result as evidence that the original was underpowered or the effect is smaller than expected. +3. Kill the idea. The most common right answer; the hardest to do because PMs have invested in the hypothesis. +4. Iterate the hypothesis and re-test. Use the inconclusive result to refine the mechanism. The new test is a new test, not a continuation; pre-commit again. + +Bayesian thinking layer. If your prior was strong (this should obviously work, given everything we know about user behavior), an inconclusive result should still update your belief somewhat. The prior was wrong, or the effect is smaller than expected, or the implementation was too timid to capture it. If your prior was weak (we genuinely had no idea what would happen), an inconclusive result means inconclusive; the prior was already uncertain and the result did not narrow it. + +The hardest version. Positive primary metric, ambiguous guardrail. Revenue went up but support tickets ticked up. Conversion went up but session length went down. Use the pre-committed decision rule. If you did not pre-commit on the guardrail trade-off, default to "do not ship." The guardrails exist because you cared about them before you saw the result. Do not lower the bar after the fact. + +For a step-by-step results-reading checklist, see [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). + +--- + +## Common failures and fixes + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-failures.md`](references/common-failures.md). + +- "We did not have enough traffic" means the MDE was too small. Pick bigger changes worth detecting. +- "The lift disappeared after launch" means the test ran for 5 days and caught a novelty effect. Run longer next time; minimum two weeks for UI changes. +- "It worked for new users but not returning users" means the segment was post-hoc, probably noise. Ship to all or kill, do not ship to the segment. +- "The p-value crept up to 0.04 after 12 days of peeking" means the false-positive rate is much higher than nominal. Pre-commit and use sequential testing. +- "Revenue went up but retention went down" means a guardrail was violated. Do not ship. +- "We cannot replicate the result" means the original was probably noise or platform-bug. Investigate before re-running. +- "Conversion went up but only because of the bot traffic from the new ad campaign" means the result was confounded by an external event. Pause campaigns during sensitive tests, or stratify by acquisition source. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped" means you ignored your own discipline. The inconclusive bucket exists for a reason; do not let directional patterns substitute for evidence. + +--- + +## Reference files + +- [`references/hypothesis-templates.md`](references/hypothesis-templates.md). Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test, with worked examples across conversion, engagement, revenue, retention, and funnel-step metric types. +- [`references/sample-size-tables.md`](references/sample-size-tables.md). Pre-calculated sample size tables for the most common conversion-rate experiments, with how-to-use guidance and the common pitfalls in sample-size planning. +- [`references/common-failures.md`](references/common-failures.md). Fifteen anti-patterns that produce wrong shipping decisions, each with symptom, root cause, fix, and prevention. +- [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). Step-by-step checklist for reading results, the three-bucket decision matrix (win, loss, inconclusive), and the post-launch monitoring discipline. +- [`references/platform-comparison.md`](references/platform-comparison.md). Profiles of the major experimentation platforms (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon) with strengths, gotchas, and a decision matrix for choosing. +- [`references/pre-experiment-readiness-checklist.md`](references/pre-experiment-readiness-checklist.md). Ten-item go/no-go checklist run through before launch. +- [`references/post-experiment-decision-framework.md`](references/post-experiment-decision-framework.md). The moment-of-decision framework: confirm pre-commitment, apply rule mechanically, route to ship/kill/inconclusive paths, write the post-mortem within a week. + +--- + +## Closing: when in doubt + +Default conservative posture. When results are unclear, do not ship. The cost of a false negative (you did not ship a real win) is usually smaller than the cost of a false positive (you shipped something that does not actually work and now you have to maintain it forever). The maintenance cost compounds; the missed-opportunity cost does not, because you can always test again. + +The discipline of experiment design is the discipline of saying "I do not know" out loud when you do not know. Saying it is often the most consequential thing a PM does in a given week. The instinct is to pretend the result is more conclusive than it is, ship to look decisive, and absorb the failure quietly when the change does not work in production. The discipline is to say "the test was inconclusive, here is what I would change to get a real answer, here is the new test plan." Saying that is professional. Pretending otherwise is theater. + +For platform-specific patterns (which platform handles which experiment type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the operational layer below this skill (managing flags, retiring stale ones, coordinating environments), see the `feature-flagging` skill. For the analytical layer above this skill (variance reduction, Bayesian alternatives, sequential testing math), see the `experimentation-analytics` skill. diff --git a/dist/pi/.agents/skills/experiment-design/references/common-failures.md b/dist/pi/.agents/skills/experiment-design/references/common-failures.md new file mode 100644 index 0000000..ba75be0 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/common-failures.md @@ -0,0 +1,183 @@ +# Common failures and fixes + +Anti-patterns that produce confidently wrong shipping decisions, with the symptom you observe, the root cause, the fix that resolves it, and the prevention that stops it from recurring. + +--- + +## 1. The vague hypothesis + +Symptom. "We think the new pricing page will increase conversions." The team runs the test, the result is ambiguous, and a heated meeting follows about whether to ship. + +Root cause. The hypothesis lacks magnitude and mechanism. When the result comes in, there is no pre-committed bar to compare against, so the decision becomes political. + +Fix. Rewrite the hypothesis with the cause-effect-magnitude-mechanism format from [SKILL.md](../SKILL.md). Save it before launching. + +Prevention. Make hypothesis review part of the experiment kickoff. A peer reads the hypothesis and confirms all four parts are present before the test launches. + +--- + +## 2. The novelty effect ship + +Symptom. Test ran for 5 days, lift looked great, the team shipped, and the lift disappeared in production within two weeks. + +Root cause. Users notice new things and click them disproportionately during the novelty window. The early lift was novelty, not durable preference. + +Fix. Re-test the change with at least a two-week test window. Most novelty effects fade in 7-10 days. If the lift survives 14 days, it is likely durable. + +Prevention. Set minimum test duration of 14 days for any UI/UX change, regardless of how fast sample size hits. Document the rule and enforce it. + +--- + +## 3. The post-hoc segment win + +Symptom. Test was inconclusive overall, but "users from California who signed up via mobile on Tuesdays" had a huge lift. The team wants to ship to that segment. + +Root cause. Multiple comparisons. With enough segments analyzed, one will hit "significance" by chance. The California-mobile-Tuesday segment is almost certainly noise. + +Fix. Do not ship to the segment. Either ship to all (if guardrails hold), or kill, or re-test with the segment pre-registered as a hypothesis. + +Prevention. Pre-register the segments to be analyzed. Limit to three to five segments per test, each with a real prior reason to differ from the population. + +--- + +## 4. The peeking creep + +Symptom. P-value drifted around 0.06 for the first week, then crept to 0.04 on day 12, the team called it significant and shipped. + +Root cause. The platform did not use sequential testing. Daily peeking inflated the false positive rate. The "significance" on day 12 was a peeking artifact. + +Fix. Either use a platform with sequential testing, or pre-commit to a single end-of-test analysis. If you peeked and the test is over, treat the result as inconclusive and consider rerunning. + +Prevention. If your platform supports sequential testing (mSPRT, group sequential), enable it. If not, set up the test with calendar reminders for the analysis date, not before. + +--- + +## 5. The guardrail violation overlook + +Symptom. Primary metric (revenue) went up. Retention dropped. The team shipped because revenue was the headline metric. + +Root cause. Guardrails were defined but not treated as binding. When the primary metric looked favorable, the team rationalized the guardrail violation as acceptable. + +Fix. Do not ship. Investigate the retention drop. The change may be capturing short-term revenue at the cost of long-term value, which is a worse trade than no change at all. + +Prevention. Pre-commit on the guardrail trade-off. Write down explicitly: "We will not ship if retention drops by more than X." If you cannot specify the bar in advance, you do not understand the trade-off well enough to test it. + +--- + +## 6. The non-replicable result + +Symptom. Test reported a 5 percent lift. The team shipped. A month later the same change tested with a holdout group shows no effect. + +Root cause. Could be many things: original test was a false positive, platform bug, external event during the test window, contamination. Without investigation, you do not know which. + +Fix. Stop, investigate, find the cause. Possible findings: the metric was computed differently in the test versus production; the test exposure was lower than reported; an unrelated change confounded the result. Do not "just rerun and hope." + +Prevention. Schedule a post-launch holdout test for any change with a reported lift greater than 3 percent. Confirm the production behavior matches the test before declaring the win. + +--- + +## 7. The campaign confound + +Symptom. Test launched the same week as a major marketing campaign. Test reported a huge lift. The team shipped. The lift was the campaign's traffic mix, not the treatment. + +Root cause. The campaign brought a different user mix into the test population: higher-intent visitors, different geographies, different device types. Treatment and control both saw the campaign traffic, but the campaign-driven users may have responded differently to the variants than the baseline population would. + +Fix. Pause campaigns during sensitive tests, or stratify the analysis by acquisition source so campaign traffic is analyzed separately from baseline traffic. + +Prevention. Coordinate with the marketing team before launching tests. Maintain a calendar of upcoming campaigns and avoid launching experiments on the same surfaces during major pushes. + +--- + +## 8. The directional ship + +Symptom. Test was inconclusive. Primary metric trended up but did not hit significance. The team shipped because "the trend was directional." + +Root cause. Directional trend without significance is noise that happens to point in a flattering direction. Treating it as evidence is exactly the discipline failure that erodes experimentation rigor. + +Fix. Do not ship based on directional trends. Either run a bigger test (more traffic, longer duration), kill, or accept inconclusive as the answer. + +Prevention. Pre-commit to the decision rule. "Inconclusive" as a category requires acceptance, not creative reframing. + +--- + +## 9. The interaction effect blind spot + +Symptom. Five concurrent tests on the checkout flow. Each individually reported a small lift. Combined, total checkout conversion did not move. + +Root cause. Interactions between concurrent tests. The lifts did not multiply or even sum. Some may have canceled out, some may have interfered with each other. + +Fix. Roll back, run tests with mutex enforcement, or run them sequentially. Re-test the combination as a multivariate. + +Prevention. Maintain an experiment registry per surface. Before launching a new test, check which others are running on the same surface and coordinate. Use mutex when interactions are likely. + +--- + +## 10. The selection bias ship + +Symptom. ARPU went up. The team shipped. After launch, MAU dropped because the lowest-revenue users churned. + +Root cause. The treatment caused selection: lower-value users left, higher-value users stayed. ARPU went up arithmetically because the denominator shrank, not because anyone made more money. + +Fix. Pair ARPU primary metrics with retention or MAU guardrails. Investigate the source of the lift before shipping. + +Prevention. When the primary metric is a ratio, always pair with absolute count guardrails. ARPU plus revenue. Conversion rate plus conversion count. Engagement rate plus DAU. + +--- + +## 11. The internal traffic contamination + +Symptom. Test reported strong lift in the first week. Investigation showed half the test users were internal employees clicking around the new feature. + +Root cause. Internal traffic was not excluded from the test population. Employees behave differently from real users. + +Fix. Re-bucket the test excluding internal IPs and employee accounts. Re-analyze. + +Prevention. Maintain an internal-traffic exclusion list at the platform level. Apply it to all experiments by default. Audit the user counts on test launch to confirm internal traffic is excluded. + +--- + +## 12. The metric definition mismatch + +Symptom. Test reported a 5 percent lift in "conversion." Production analytics reported a 0.5 percent lift. The team blamed the platform. + +Root cause. The conversion event was defined differently in the test platform versus production analytics. Different conversion windows, different deduplication rules, different user-identity logic. + +Fix. Reconcile the metric definitions before re-running. Document the canonical definition and confirm both systems produce matching numbers on a known historical period. + +Prevention. Maintain a metric dictionary. Before adding a metric to an experimentation platform, document the canonical definition and validate against production analytics. Treat the metric definition as a versioned artifact. + +--- + +## 13. The ratio metric variance error + +Symptom. Test reported a "significant" lift in revenue per user with p equals 0.04. Production rollout produced no measurable change. + +Root cause. The platform used a naive variance estimator on a ratio metric. Confidence interval was too narrow; the "significance" was an artifact of bad math. + +Fix. Switch to a platform that uses a ratio-aware estimator (delta method, bootstrap). Re-run the test or confirm via holdout. + +Prevention. Audit your platform's variance estimator. Ask the vendor what they use for ratio metrics. If the answer is "standard t-test on proportions" for anything other than simple binary conversion, plan a workaround. + +--- + +## 14. The "we will fix it later" rollout + +Symptom. Test was inconclusive but engineering had already deployed the change. Rolling back was hard. The team shipped because the cost of rollback was higher than the expected cost of shipping. + +Root cause. The rollout was not gated on the experiment result. Engineering shipped to production before the test had concluded. + +Fix. Roll back if possible. If not, accept the change is shipped and instrument production carefully to confirm whether it actually works. + +Prevention. Gate rollouts behind experiment conclusions. Use feature flags so the change can be toggled off without a code revert. Coordinate engineering schedules with experiment timelines. + +--- + +## 15. The retroactive hypothesis + +Symptom. Test was set up to validate "the new homepage increases signups." Result showed signups flat but engagement up. The team rewrote the hypothesis as "the new homepage drives engagement" and shipped. + +Root cause. Hypothesis was changed after the result was visible. This is p-hacking even if no statistical math was changed. + +Fix. The original hypothesis was inconclusive on signups. Either kill, or run a new test with the engagement hypothesis pre-registered. + +Prevention. Pre-commit the primary metric and stick with it. If the data suggests a different metric is more interesting, treat that as the hypothesis for the next test, not a rewrite of the current one. diff --git a/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md b/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md new file mode 100644 index 0000000..18e3584 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/hypothesis-templates.md @@ -0,0 +1,95 @@ +# Hypothesis templates + +Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test from [SKILL.md](../SKILL.md). Each template names the right shape, shows two or three worked examples in different domains, and calls out the most common mistakes specific to that template type. + +The unifying format across all templates: replace [bracketed slots] with concrete project-specific values. If a slot reads as a vague phrase after replacement, the hypothesis is not specific enough. + +--- + +## Template 1: Conversion rate change + +Format. Replacing [current treatment] with [new treatment] will increase [conversion event] by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +Worked example, e-commerce. Replacing the multi-step shipping selector with an inline shipping summary on the cart page will increase cart-to-purchase conversion by 6 percent (currently 14.2 percent, target 15.1 percent) by reducing the cognitive load at the moment users are deciding whether to complete checkout. + +Worked example, SaaS. Replacing the three-tier pricing comparison with a single recommended tier on the pricing page will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe. + +Worked example, marketplace. Replacing the "browse all categories" landing page with a personalized recommendation grid will increase landing-to-listing-click conversion by 12 percent (currently 18 percent, target 20.2 percent) by surfacing relevant inventory before users have to specify intent. + +Common mistakes specific to this template. +- Naming the metric as "conversions" without specifying the conversion event. "Conversion" alone is ambiguous; cart-to-purchase, signup-to-paid, and landing-to-listing-click are different metrics with different baselines and different relevant timescales. +- Stating relative lift without absolute. "10 percent lift" sounds bigger than "1 percent absolute lift on a 10 percent baseline" but is the same thing; state both so the reader knows what is being claimed. +- Skipping the mechanism. "Will increase conversion by 8 percent" is a target, not a hypothesis. The why is what makes it falsifiable. + +--- + +## Template 2: Engagement metric change (DAU, sessions, time-on-task) + +Format. Adding [new feature or affordance] will increase [engagement metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, content product. Adding a "save for later" button to article cards will increase weekly active users by 5 percent (currently 1.2 million, target 1.26 million) by giving users a reason to return to articles they have started reading. + +Worked example, productivity tool. Adding inline comments on document blocks will increase sessions per week per active team by 15 percent (currently 4.2, target 4.8) by enabling asynchronous collaboration that previously required separate communication channels. + +Common mistakes specific to this template. +- Engagement metrics are not always good. A feature that increases sessions but decreases task completion is making the product worse, not better. Pair engagement primary metrics with task-completion guardrails. +- "Time on task" is ambiguous. More time can mean engagement or confusion. Specify whether longer or shorter is the desired direction and why. +- Treating engagement lift as a leading indicator without evidence that it is. Increased DAU does not always lead to increased revenue; sometimes it lags it, sometimes it has no relationship. + +--- + +## Template 3: Revenue metric change (ARPU, AOV, RPU) + +Format. Implementing [new pricing or merchandising change] will increase [revenue metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, subscription product. Adding an annual prepay option at 10 percent discount will increase average revenue per user by 4 percent (currently $87, target $90.50) by shifting price-sensitive users from monthly to annual billing, which has lower churn. + +Worked example, e-commerce. Adding a "frequently bought together" bundle on product detail pages will increase average order value by 8 percent (currently $42, target $45.40) by surfacing relevant add-on items at the moment of purchase decision. + +Common mistakes specific to this template. +- Revenue is a ratio metric (revenue divided by users or orders). Naive variance estimators understate the variance and overstate confidence. Confirm your platform uses the delta method or an equivalent ratio-aware estimator. +- ARPU lifts can come from selection effects: if the treatment moves the lowest-revenue users away (they churn), ARPU goes up without anyone making more money. Pair ARPU primary metrics with retention guardrails. +- Revenue lifts can be driven by a small number of high-value users. Confidence intervals are wide. Run longer than you think you need to. + +--- + +## Template 4: Retention metric change + +Format. Changing [interaction or feature] will increase [retention metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, mobile app. Changing the day-3 push notification copy from generic to personalized recommendations will increase day-7 retention by 3 percent (currently 38 percent, target 39.1 percent) by reminding users of specific value they can return to. + +Worked example, SaaS onboarding. Replacing the static onboarding checklist with a guided in-product tour will increase day-30 active retention by 5 percent (currently 22 percent, target 23.1 percent) by getting more users to the activation event during their first session. + +Common mistakes specific to this template. +- Retention takes time to measure. A test of day-30 retention requires at least 30 days of treatment exposure plus the test duration. Plan accordingly. +- Day-N retention is a moving definition. Day-7 active means different things in different products; specify the activity that defines "active" before running. +- Retention lifts often shrink over time. A treatment that improves day-7 retention may have no effect on day-90 retention. Decide which timescale matters for the business and measure that, not just the convenient short one. + +--- + +## Template 5: Funnel-step abandonment reduction + +Format. Modifying [specific funnel step] will reduce abandonment at that step by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +Worked example, signup funnel. Removing the phone number field from the signup form will reduce signup-form abandonment by 20 percent (currently 35 percent, target 28 percent) by removing a high-friction field that is not required for account creation. + +Worked example, checkout funnel. Adding guest checkout above the account creation prompt will reduce account-creation-step abandonment by 25 percent (currently 18 percent, target 13.5 percent) by giving purchase-intent users a path that does not require account creation. + +Common mistakes specific to this template. +- Reducing abandonment at one step often shifts abandonment to the next step. The right metric is downstream conversion, not just step-level abandonment. Pair step-level primary metrics with full-funnel guardrails. +- Signup abandonment can be measured noisily; users who abandon the form may return later. Define the conversion window (5 minutes, 24 hours, 7 days) before testing. +- Reducing friction is not always good. A signup form that is too short produces low-quality signups: trial users who never return, fake accounts, support load. Pair friction-reduction tests with downstream-quality guardrails. + +--- + +## Anti-templates: hypotheses that should be rejected + +Examples of hypotheses that fail the format and should be rewritten before launching: + +- "We think the new pricing page will increase conversions." Missing magnitude, mechanism, and a specific conversion event. Rewrite using Template 1. +- "Users will love the redesign." Missing everything. Not testable. Pick a metric. +- "The new flow is faster, so more people will complete it." Missing baseline, target, and a defined "complete" event. The mechanism (faster) is plausible but not specific. +- "We want to see if dark mode improves engagement." Vague metric (engagement), no magnitude, and dark mode is binary not a multivariate. Pick a specific engagement metric and pre-register the segments where dark mode users are likely to differ from light-mode users (mobile evening sessions, for example). + +If your draft hypothesis sounds like one of the anti-templates, rewrite it using one of the five templates above before running the test. diff --git a/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md b/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md new file mode 100644 index 0000000..f435e29 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/platform-comparison.md @@ -0,0 +1,133 @@ +# Platform comparison + +A practical guide to choosing an experimentation platform. Each platform has a distinct profile (statistical defaults, primary audience, integration model, pricing shape). Picking well saves quarters of friction; picking badly creates ongoing pain. + +This reference assumes the team is in the position of choosing or reconsidering. For platform-specific MCP commands, auth models, and example prompts, consult the chosen platform's official documentation. + +--- + +## Statsig + +Profile. Modern feature management plus experimentation platform. Built CUPED-first, holdouts as a first-class concept, warehouse-native with optional event ingestion. Fast-growing customer base including OpenAI, Notion, Brex, Whatnot. + +Strengths. CUPED variance reduction is the default, not an opt-in. Strong holdout analysis with built-in long-term measurement. Mature MCP exposing full CRUD across experiments, gates, dynamic configs, layers, and segments. Setup guides for ChatGPT, Cursor, Claude Code, Codex. + +Best for. Fast-growing companies that want one platform for both feature flags and experiments. Engineering-led teams comfortable with code-first configuration. Teams that need to run many concurrent experiments and care about variance reduction. + +Gotchas. Pricing scales with events, which can compound for high-traffic products. The breadth of the MCP can crowd context windows on smaller models; scoping helps. Best-in-class statistical defaults are nice but require the team to actually understand them. + +MCP setup. Statsig publishes setup guides for ChatGPT, Cursor, Claude Code, and Codex; consult the Statsig docs for the current MCP server URL and auth model. + +--- + +## PostHog + +Profile. Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics in one platform. Self-host or cloud. Customer base skews toward PLG products and developer tools. + +Strengths. Combines analytics and experimentation in one platform, eliminating the metric-definition mismatch between systems. Full event-level data in the warehouse. 200+ MCP tools across the entire product, the largest surface of any vendor in this list. + +Best for. Product-led growth products that benefit from full-funnel context across analytics, experiments, and session replays. Teams that want one platform for everything rather than a stack of specialized tools. + +Gotchas. The breadth of the MCP requires scoping with `?features=` query parameters; without scoping, the agent gets 200+ tools and tool selection accuracy degrades on smaller models. Self-host adds operational complexity. Some experiment features lag behind specialized platforms. + +MCP setup. PostHog's MCP scopes via `?features=` query parameters; without scoping, the agent gets 200+ tools and tool-selection accuracy degrades on smaller models. Consult the PostHog docs for current scoping syntax. + +--- + +## GrowthBook + +Profile. Open-source warehouse-native experimentation. Runs SQL on the team's existing data warehouse. Customer base skews data-mature: Dropbox, Khan Academy, Mistral. Claims the first open-source production MCP for experimentation. + +Strengths. Data stays in the team's warehouse; no event ingestion to a vendor. Strong cost control because the math runs on infrastructure the team already pays for. 100 percent open source under MIT, with self-host or cloud options. + +Best for. Data-mature teams that already own a warehouse (Snowflake, BigQuery, Redshift, ClickHouse, Postgres). Regulated industries where data residency matters. Teams that want full control over the statistical math. + +Gotchas. More setup overhead than hosted platforms. Requires SQL fluency for advanced analyses. Smaller community than the bigger commercial vendors. + +MCP setup. GrowthBook ships an open-source MCP for self-host or cloud; consult the GrowthBook docs for the current binary and auth model. + +--- + +## Optimizely + +Profile. Long-time enterprise leader in personalization and experimentation. Web Experimentation and Feature Experimentation as separate but linked products. Customer base skews enterprise marketing and e-commerce. + +Strengths. Deep targeting, audience management, multivariate testing. Visual editor accessible to non-technical users (marketers can build variants without engineering). Mature personalization and recommendation engine. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth. + +Best for. Marketing-led organizations where non-technical teams need to author variants. Enterprises with deep personalization needs. E-commerce sites with established A/B testing programs. + +Gotchas. Expensive at the enterprise tier. Visual editor produces JS that ships at runtime, which can affect page performance. Less ergonomic for engineering-led teams that prefer code-first configuration. + +MCP setup. Optimizely's hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth; consult Optimizely docs for the current server URL. + +--- + +## Amplitude + +Profile. Behavioral analytics platform with experiments and feature flags layered on top. Customer base skews product analytics teams that adopted Amplitude before adding experimentation. + +Strengths. Deep cohort analysis and behavioral segmentation. Native ChatGPT connector. Hosted MCP available to all customers including the free tier. Integrates tightly with the analytics layer that PMs already use. + +Best for. Teams that already use Amplitude for analytics and want to add experiments without introducing a new platform. Product analytics teams that need behavioral cohort segmentation as part of the experiment workflow. + +Gotchas. Experiments are a secondary feature, not the platform's center of gravity. Variance reduction options are more limited than dedicated experimentation platforms. Beta status of the MCP means the API surface may evolve. + +MCP setup. Amplitude's hosted MCP is available to all customers including the free tier and ships a native ChatGPT connector; consult the Amplitude docs for the current setup steps. + +--- + +## Eppo + +Profile. Warehouse-native experimentation platform with strong statistical defaults. Customer base skews data-team-led organizations: Twitch, DraftKings, Perplexity. Best-in-class statistical rigor. + +Strengths. Best-in-class statistical defaults: variance reduction, sequential testing, contextual bandits, lifecycle experimentation. Warehouse-native means data stays in the team's stack. Strong explainability features for tracing reported lifts back to underlying SQL. + +Best for. Data-team-led organizations where data scientists own the experimentation discipline. Companies with mature warehouses and strict statistical rigor requirements. Teams running contextual bandits or other advanced experiment designs. + +Gotchas. No first-party MCP server as of May 2026. Programmatic access is REST API only; teams that want agentic workflows today need to build a custom MCP adapter or wait. Pricing reflects the data-science-focused product positioning. + +MCP setup. No first-party MCP server as of mid-2026; teams that want agentic workflows today either build a custom MCP adapter on top of Eppo's REST API or wait for the official server. Consult Eppo's docs and roadmap for current status. + +--- + +## Kameleoon + +Profile. AI-driven personalization platform with a specialized MCP focused on the convert-and-promote workflow. The MCP pulls raw variation code from winning experiments and helps refactor it into production-ready React components. + +Strengths. Sharp, narrow MCP (seven specialized tools) focused on a specific job: take a winning marketing-site variation and ship it as permanent product code. Hosted MCP via OAuth. Avoids the broad-CRUD complexity that crowds context windows on other platforms. + +Best for. Teams that test on the marketing site and need to convert wins into permanent React components. Hybrid marketing-and-product setups where the experiment lives in JS/CSS and the win needs to ship as a product feature. + +Gotchas. The narrow MCP scope is intentional but limits broader CRUD work. For everyday flag management, teams use the Kameleoon dashboard or REST API rather than the MCP. + +MCP setup. Kameleoon's hosted MCP via OAuth ships a narrow seven-tool surface focused on the convert-and-promote workflow; consult Kameleoon's docs for the current server URL. + +--- + +## Decision matrix + +A short matrix for the first-pass platform decision. Tradeoffs are oversimplified; verify against the team's specific constraints. + +\| Situation \| Pick \| +\|---\|---\| +\| Pure SaaS, fast-growing, want one platform for flags + experiments \| Statsig or PostHog \| +\| Open-source preference, warehouse-native \| GrowthBook or Eppo \| +\| Enterprise, marketing-led, non-technical variant authoring \| Optimizely \| +\| Already using Amplitude for analytics, want experiments without new platform \| Amplitude \| +\| Convert marketing-site experiment wins into permanent product code \| Kameleoon \| +\| Data-team-led, statistical rigor is non-negotiable, can wait for MCP \| Eppo \| +\| Open-source AND warehouse-native AND need MCP today \| GrowthBook \| + +Beyond these defaults, the right choice depends on the team's existing stack, the experimentation maturity, and the budget. The "best" platform for one team is wrong for another; pick based on the team's actual constraints, not the platform's marketing. + +--- + +## Switching costs + +Once a team has adopted a platform, switching is expensive. Existing experiments need to be re-run on the new platform. The metric definitions need to be reconciled. The team needs to retrain on a new tool. Plan accordingly: + +- Easy switches. Visual A/B testing tools that ship JS at runtime (Optimizely Web, AB Tasty, VWO classic). Switching is mostly tag-replacement. +- Medium switches. Warehouse-native to warehouse-native (GrowthBook to Eppo, or vice versa). The data layer is shared; the configuration migrates. +- Hard switches. Anything to or from event-ingestion platforms (Statsig, Amplitude). The historical event data does not transfer cleanly; the team starts fresh on metric history. + +If the team is choosing now and might need to switch later, lean toward warehouse-native options. Data ownership is the most expensive thing to switch. diff --git a/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md b/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md new file mode 100644 index 0000000..6354a66 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/post-experiment-decision-framework.md @@ -0,0 +1,91 @@ +# Post-experiment decision framework + +The moment-of-decision framework for what to do when a test ends. Each step builds on the prior; do not skip ahead. The discipline at this stage is what separates teams that learn from experiments from teams that confirm their priors. + +--- + +## Step 1: Confirm pre-commitment was followed + +Before reading the results, pull up the pre-commitment document. Verify: +- The test ran for the pre-committed duration (not stopped early, not extended). +- The primary metric was the one pre-committed (not silently swapped). +- The segments analyzed were the ones pre-committed (not new ones discovered post-hoc). +- The guardrails are the ones pre-committed (not narrowed or widened after the fact). + +If any item failed the check, the result is compromised. Treat as inconclusive at minimum; consider re-running. + +--- + +## Step 2: Apply the pre-committed decision rule mechanically + +The pre-commitment mapped each possible result to a ship-or-kill decision. Find the bucket the result falls into. Apply the rule. + +Resist the temptation to add new analysis "just to be sure." If new analysis is required to make a decision, the pre-commitment was inadequate; the lesson is for next time, not a license to dig until the answer feels right. + +The mechanical-application discipline is the most important habit at this step. Teams that deliberate about whether to follow their own pre-commitment have already lost the discipline. Apply the rule. Document any second-guessing as feedback for the next pre-commitment. + +--- + +## Step 3a: If decision is "ship" + +1. File the launch ticket. Include: the test ID, the primary metric lift, confidence interval, guardrails status, segments status, and a link to the pre-commitment. +2. Schedule post-launch monitoring at +7 days, +30 days, +60 days. Calendar reminders, not "I'll check it later." +3. Confirm the launch removes the experiment infrastructure (the flag, the variant code paths) on the schedule the team has for stale-flag cleanup. See the `feature-flagging` skill for the cleanup discipline. +4. Post a brief launch summary to the team's experiment log. + +--- + +## Step 3b: If decision is "kill" + +1. Document the learning. What did the team predict? What happened? What is the most likely reason for the gap? +2. Propose a follow-up hypothesis if applicable. The hypothesis can be "we should not test this idea again" if the test was definitive in the negative direction. It can be "let's iterate the mechanism" if the test was inconclusive and the team has a clearer story now. +3. Archive the experiment infrastructure: remove the flag, clean up the variant code, remove instrumentation that was specific to this test. +4. Post the kill summary to the team's experiment log. Killed experiments are as valuable as winning experiments; they prevent the team from repeating the mistake. + +--- + +## Step 3c: If decision is "inconclusive" + +The inconclusive path is the hardest. The temptation is to ship anyway because the team has invested in the hypothesis. Resist it. + +Run through the resolution paths in order: + +1. Was the MDE realistic? If the test was underpowered (you needed a 5 percent lift to be detectable, and you got a 2 percent point estimate with a confidence interval crossing zero), the right answer may be to redesign the test with a bolder change and rerun. Do not extend the existing test; that produces a peeking artifact. Plan a new test, pre-commit, run. +2. Was the test contaminated? If a confounder (campaign, outage, instrumentation bug) is identifiable, fix and rerun. Do not handwave the confounder. +3. Is the change cheap and reversible? If the change is small, easy to maintain, and easy to roll back, shipping despite an inconclusive result is defensible. The bar is high; the change has to be genuinely cheap, and the guardrails have to be clean. If the change is expensive to maintain (additional UI complexity, additional code paths, additional analytics surface), ship is the wrong call. +4. Otherwise: kill, document, move on. The discipline of accepting inconclusive results as inconclusive is what makes experimentation a learning system. Treating every inconclusive result as a "we just need more data" justification destroys the discipline. + +--- + +## Step 4: Write the post-mortem within one week + +Regardless of the decision, write a short post-mortem within one week. The post-mortem covers: + +- The hypothesis (cause, effect, magnitude, mechanism) +- The pre-commitment (primary metric, MDE, duration, decision rule) +- The result (lift, CI, guardrails, segments) +- The decision (ship / kill / inconclusive) +- The action taken (launch, archive, redesign) +- The learning (what would the team do differently next time) + +Keep post-mortems short: half a page is plenty. Long post-mortems do not get written; short ones do. The compounding value of a written experiment log over years is enormous; the compounding value of a vague memory of past tests is zero. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. + +Schedule a review at: + +- Day 7. Production metric matches the experiment lift within reasonable tolerance. If it does not, investigate before declaring the launch successful. +- Day 14. Lift has not decayed (which would suggest novelty effect that the test underweighted) or amplified (which would suggest the change interacts with something the test could not capture). +- Day 30. Long-term metrics (retention, downstream conversion, support load) are not eroding. The change continues to deliver value, not just an initial bump. + +If the production behavior diverges materially from the test behavior at any review: + +1. Quantify the divergence. Is it within statistical noise, or is it a real effect? +2. Investigate the cause. Common ones: novelty wore off, segment distribution shifted, instrumentation bug, interaction with another concurrent change. +3. Decide: roll back, hot-fix, or accept and document. Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. + +The 30-day rule prevents the "we shipped, it worked, then it stopped working but nobody noticed" failure mode. Most teams skip post-launch monitoring; the ones that do it consistently learn faster. diff --git a/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md b/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md new file mode 100644 index 0000000..5a0e44a --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/pre-experiment-readiness-checklist.md @@ -0,0 +1,108 @@ +# Pre-experiment readiness checklist + +A go/no-go decision checklist to run through before launching any experiment. If any item is "no," delay the launch until it is "yes." Running an experiment without these in place produces results that cannot be defended, decisions that get second-guessed, and a long-term erosion of trust in the experimentation discipline. + +The checklist takes ten to fifteen minutes per experiment. The cost of skipping it is much higher. + +--- + +## 1. Hypothesis written in cause-effect-magnitude-mechanism format + +The hypothesis names: what change is being made (cause), what metric will move (effect), how much you expect it to move with what baseline and target (magnitude), and why you expect this change to produce this effect (mechanism). + +If the draft hypothesis is missing any of the four parts, rewrite using one of the templates from `hypothesis-templates.md` before launch. + +--- + +## 2. Primary metric defined with success threshold + +Exactly one primary metric. Specified with the same precision the platform's metric configuration requires (event name, deduplication window, user identity logic). Success threshold pre-committed: the lift you would consider sufficient to ship. + +If multiple metrics feel "primary," collapse to one and demote the others to guardrails. + +--- + +## 3. Guardrails defined (3 to 5) + +Three to five guardrail metrics that must not break: revenue, retention, support tickets, page load time, error rate, satisfaction scores. Each with a tolerance threshold pre-committed. + +Avoid: more than five guardrails (creates analysis paralysis), or zero guardrails (the test cannot detect collateral damage), or vague guardrails like "user happiness" (not measurable). + +--- + +## 4. Sample size calculated for chosen MDE + +The required sample size for the chosen minimum detectable effect, at standard alpha (0.05) and power (0.80), through your platform's calculator or via a stats library. Documented in the pre-commitment. + +If the math says "you need 200,000 users to detect this lift and you have 5,000 a week," accept a larger MDE or do not run the test. Do not run an underpowered test and hope for the best. + +--- + +## 5. Duration committed (longer of sample-size-hit and full weekly cycle) + +Calendar duration committed in advance. The longer of: time to hit the calculated sample size at expected daily traffic, or one full weekly cycle (typically 7 days). UI/UX changes get a 14-day minimum regardless. + +If the duration is "we will see how long it takes," that is not a duration. Pick a date. + +--- + +## 6. Segments pre-registered (if any) + +If you plan to analyze segment-level results, name the segments before launch. Three to five maximum, each with a real prior reason to expect different behavior in that segment. + +If you do not plan to analyze segments, write that down too. The pre-commitment to "no segment analysis" is itself a defense against post-hoc segment mining. + +--- + +## 7. Decision rule pre-committed (saved with timestamp) + +Map each possible result to a decision: +- Result above target threshold + guardrails clean: ship +- Result below MDE: kill +- Result inconclusive (point above zero, CI crosses zero): default to do not ship; document next-step options +- Guardrail violation: do not ship regardless of primary + +Save the decision rule somewhere immutable: the PR description, a pinned ticket, a signed Slack message, anywhere with a timestamp. + +--- + +## 8. No conflicting concurrent experiments on the same surface + +Check the experiment registry for what else is running on the same surface (checkout flow, signup form, pricing page). If there are interactions, set up mutex enforcement so users in this test are not also in the others. + +If you cannot enforce mutex (sample size constraints), document the overlap and accept the interpretability cost. Do not pretend there is no overlap. + +--- + +## 9. Instrumentation tested with a small canary + +Before launching to the full population, expose a small canary group (5 to 10 percent) and confirm: +- Treatment users actually see the treatment +- Events fire correctly for both groups +- The platform reports the right exposure counts +- Internal traffic is excluded +- The metric definitions match between the platform and production analytics + +Catching instrumentation bugs in canary saves a wasted full test run. + +--- + +## 10. Stakeholders aligned on what each outcome means + +The PM, the engineering lead, the design lead, and any other decision-maker have all agreed: if the test wins, we ship; if it loses, we kill; if it is inconclusive, we follow the inconclusive path documented in the decision rule. + +If a stakeholder is going to dispute the result regardless of what it shows, the experiment is theater. Resolve the strategic question first; run the experiment only if the result genuinely changes the decision. + +--- + +## Decision + +If all ten items are "yes," launch. + +If any item is "no": +- Items 1, 2, 3 (hypothesis, metric, guardrails): blocking. Fix before launch. +- Items 4, 5, 7 (math, duration, decision rule): blocking. Fix before launch. +- Items 6, 8, 9 (segments, mutex, canary): worth fixing but launch can proceed if the fix is impractical and the team accepts the risk. +- Item 10 (stakeholder alignment): blocking. An experiment that cannot change the decision is theater. + +The cost of delaying a launch by a day to fix a checklist item is small. The cost of running a test that produces an indefensible result is much higher. diff --git a/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md b/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md new file mode 100644 index 0000000..32d3006 --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/results-interpretation-checklist.md @@ -0,0 +1,112 @@ +# Results interpretation checklist + +A step-by-step checklist for reading experiment results and arriving at a defensible decision. Run through it in order. Do not skip steps because the result "looks obvious"; the obvious-looking results are often the ones that fail in production. + +--- + +## Step 1: Did the test run for the pre-committed duration? + +What to look for. The test ended on the date pre-committed at launch, with the planned analysis happening on that date. + +Red flags. The test was stopped early because results "looked great." The test was extended past the pre-commitment because results "had not stabilized." The test ran for an arbitrary duration not tied to the pre-commitment. + +When to escalate. If the duration was changed after launch without documented rationale, the result is compromised. Treat as inconclusive and consider re-running. + +--- + +## Step 2: Did all guardrails stay within tolerance? + +What to look for. Each pre-defined guardrail (revenue, retention, support tickets, page load time, error rate) within its acceptable range. Confidence intervals around guardrail metrics that exclude the threshold of concern. + +Red flags. A guardrail moved in the wrong direction even if the change was not "significant." Wide confidence intervals on guardrails (the test was underpowered for the guardrail). A guardrail you did not pre-define being raised post-hoc. + +When to escalate. A guardrail violation should be treated as binding. The fix is "do not ship," not "the primary metric was good enough to outweigh the guardrail." If the guardrail was poorly chosen, that is a lesson for next time, not a license to ignore it on this test. + +--- + +## Step 3: Did the primary metric move beyond the MDE? + +What to look for. The point estimate of the primary metric exceeds the pre-committed minimum detectable effect, and the confidence interval excludes zero (or excludes the no-effect threshold for one-sided tests). + +Red flags. Point estimate is above MDE but the confidence interval crosses zero. The "significance" comes from a peeking artifact (interim analysis that became the headline). The lift comes from a small number of outlier users. + +When to escalate. If the primary metric is significant but the lift is below MDE, the test was overpowered for the question; the result is technically real but practically too small to matter. Do not ship a 0.3 percent lift just because p equals 0.001. + +--- + +## Step 4: Was the confidence interval clean? + +What to look for. A confidence interval around the lift estimate that is well-bounded and not crossing zero. Symmetric (or appropriately skewed for the metric type). + +Red flags. Very wide CI (test was underpowered). Skewed CI hinting at distributional weirdness (a few outliers drove the result). CI computed without ratio-aware variance for ratio metrics. + +When to escalate. If the CI is wide enough that the practical lift could be anywhere from "not worth shipping" to "amazing," the test does not support a confident ship decision. Run longer or accept inconclusive. + +--- + +## Step 5: Are the results consistent across pre-registered segments? + +What to look for. The pre-registered segments show effects in the same direction as the overall result. Magnitude can vary; direction should not flip. + +Red flags. Some segments show effects opposite to the overall result. The overall lift comes from one segment and the rest are flat or negative. + +When to escalate. If one segment is driving the entire effect and others are negative, the right ship decision is "ship to the segment where it works" only if the targeting infrastructure exists and is worth the maintenance cost. More often the right answer is to redesign the change so it works for the whole population. + +Reminder: this step covers PRE-REGISTERED segments only. Post-hoc segments are noise mining; do not re-analyze the data through new segments looking for an interpretation. + +--- + +## Step 6: Did any external events potentially confound the results? + +What to look for. A timeline of events during the test window: marketing campaigns, product launches, outages, news cycles, holidays, seasonality shifts. + +Red flags. A campaign launched mid-test that brought a different user mix. A product release mid-test that changed user behavior. An outage during the test that affected one variant differently from the other. + +When to escalate. If a confounder is identified, isolate it. Stratify the analysis by acquisition source (excludes campaign-driven users), or by date (excludes the outage day), or rerun. Do not handwave the confounder; either fix it or accept that the result is tainted. + +--- + +## Step 7: Is the magnitude practically significant, not just statistically significant? + +What to look for. The lift is large enough to matter for the business. A 0.3 percent absolute lift on a 30 percent baseline is statistically significant with enough sample but may not justify the engineering cost of maintaining the change. + +Red flags. "Statistically significant" being used as the only justification. No conversation about whether the lift is large enough to be worth the implementation, maintenance, and complexity cost. + +When to escalate. If the magnitude is small, ask: "Is this worth the code surface area, the testing surface area, and the cognitive load on the team?" Often the answer is no. Do not ship marginal lifts unless the change is also cheap to maintain. + +--- + +## Step 8: Does the decision match the pre-committed rule? + +What to look for. The pre-commitment document mapped each possible result to a ship-or-kill decision. The result fits clearly into one of those buckets. + +Red flags. The result does not fit cleanly. The team is debating which bucket applies. Someone is proposing a new analytical knob to clarify the bucket. + +When to escalate. If the result is genuinely ambiguous, default to "do not ship" and document why. Inconclusive is a valid outcome; treating it as one is the discipline. + +--- + +## Decision matrix + +After running through the checklist, the result fits one of three buckets: + +\| Bucket \| Conditions \| Action \| +\|---\|---\|---\| +\| Clear win \| Primary moved past MDE, CI excludes zero, guardrails clean, segments consistent, no confounders \| Ship. File launch. Schedule post-launch monitoring at +30 and +60 days. \| +\| Clear loss \| Primary moved against expected direction with significance, OR guardrail violated \| Kill. Document the learning. Propose follow-up hypothesis if applicable. \| +\| Inconclusive \| Anything else \| Default to do not ship. Run a bigger version, kill, or iterate the hypothesis. \| + +The inconclusive bucket is the most common and the hardest. The discipline is to recognize it and resist the pull to ship anyway. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. Schedule a review at day 7, day 14, and day 30. + +What to check at each review: +- Day 7: Production metric matches the experiment lift within reasonable tolerance. +- Day 14: Lift has not decayed (novelty effect) or amplified (the change interacts with something the test could not capture). +- Day 30: Long-term metrics (retention, downstream conversion) are not eroding. + +If the production behavior diverges materially from the test behavior, the right call is to roll back and investigate, not to "wait and see." Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. diff --git a/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md b/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md new file mode 100644 index 0000000..5a74eea --- /dev/null +++ b/dist/pi/.agents/skills/experiment-design/references/sample-size-tables.md @@ -0,0 +1,88 @@ +# Sample size tables + +Pre-calculated sample size tables for the most common experimentation scenarios. These tables are starting points, not substitutes for running the math against your specific traffic and metric. The math depends on the variance of the metric, the desired power, the alpha threshold, and the test design (one-sided, two-sided, sequential). + +Use these tables to: +- Sanity-check a sample size estimate from your platform's calculator +- Decide whether the planned test is feasible given your traffic +- Choose an MDE that is realistic for your traffic level + +For exact figures, run the math through your platform's calculator (most experimentation platforms expose one) or use a stats library (`scipy.stats`, R's `pwr` package, or an online calculator). + +--- + +## How to use these tables + +Each table assumes: +- Two-sided test (the standard default for PM experiments) +- Alpha equals 0.05 (5 percent false positive rate) +- Power equals 0.80 (80 percent chance of detecting an effect that is really there) +- Equal group sizes (50/50 split) + +Total sample size is the sum across both groups. Per-group sample is half the total. + +If you change any of those assumptions, multiply by the indicated factor: +- Power 0.90 instead of 0.80: multiply sample size by ~1.34 +- Alpha 0.01 instead of 0.05: multiply sample size by ~1.49 +- One-sided test: multiply by ~0.79 + +Worked example for using Table 1: a product has a baseline conversion rate of 10 percent and wants to detect a 1 percent absolute lift (target 11 percent). Total sample size required is roughly 31,400 users. With 1,000 daily new users in the test population, the test needs about 31 days plus one full weekly cycle. If you can only run it for 14 days, the MDE you can detect at this traffic is closer to 1.5 percent absolute. Pick the change you can detect; do not run an underpowered test. + +--- + +## Table 1: Conversion rate experiments + +Total sample size required (across both groups) for a two-sided test, alpha 0.05, power 0.80. + +\| Baseline rate \| MDE 1% abs \| MDE 2% abs \| MDE 5% abs \| MDE 10% abs \| +\|---\|---\|---\|---\|---\| +\| 5% \| 14,800 \| 4,400 \| 1,000 \| 360 \| +\| 10% \| 31,400 \| 8,400 \| 1,700 \| 540 \| +\| 20% \| 51,800 \| 13,400 \| 2,500 \| 720 \| +\| 30% \| 65,600 \| 16,600 \| 3,000 \| 800 \| +\| 50% \| 78,400 \| 19,600 \| 3,200 \| 800 \| + +Reading the table. A product with 30 percent baseline conversion that wants to detect a 2 percent absolute lift (target 32 percent) needs ~16,600 users total, ~8,300 per group. Numbers are approximate and rounded. + +Choosing an MDE that matches traffic. If you have 5,000 weekly users in the test population: +- One week of traffic supports detection of ~5 percent absolute lift on a 30 percent baseline (3,000 users, MDE 5 percent matches) +- Two weeks supports ~3 percent absolute lift +- Four weeks supports ~2 percent absolute lift +- Six weeks supports ~1.5 percent absolute lift + +Beyond six weeks the test runs into seasonality and product-evolution problems described in [SKILL.md](../SKILL.md). If the change you want to test would only produce a 1 percent absolute lift and your traffic supports 5 percent MDE in a reasonable window, the test is not worth running. Pick a bigger change. + +--- + +## Table 2: Mean comparison experiments (continuous metrics) + +For continuous metrics like time-on-task, session length, page views per session, the math depends on the metric's standard deviation, which varies by product. The table below shows sample sizes assuming a coefficient of variation (standard deviation divided by mean) of 1.0, which is typical for engagement metrics. + +\| Baseline mean \| MDE 5% rel \| MDE 10% rel \| MDE 20% rel \| +\|---\|---\|---\|---\| +\| Any (CoV ~1.0) \| 12,600 \| 3,200 \| 800 \| +\| Any (CoV ~2.0) \| 50,400 \| 12,600 \| 3,200 \| + +For revenue metrics the CoV is often higher (2.0 to 3.0) because revenue is concentrated in a small fraction of users. Run your variance through the platform calculator before committing to a sample size; the table is illustrative, not authoritative. + +--- + +## Common pitfalls in sample size planning + +- Forgetting to count exposure, not allocation. If 1,000 users see the experiment per day but only 200 reach the surface where the variant is rendered, your effective sample is 200 per day. Use exposure counts, not bucketing counts. +- Treating session-level and user-level differently. Some metrics are evaluated per session (page views per session), others per user (day-7 retention). Sample size requirements differ. Specify which level the metric is evaluated at and use the matching count. +- Forgetting variance reduction. Methods like CUPED, stratified sampling, and control variates can reduce required sample size by 30 to 50 percent for the same power. If your platform supports them, use them. Sample size tables ignoring variance reduction overstate what you actually need. +- Underestimating the weekly cycle requirement. A test that hits sample size in three days still needs to run a full week to capture cycle effects. Sample size hit is necessary but not sufficient. +- Assuming traffic is stable. If a marketing campaign launches mid-test, the user mix changes and the test may no longer be a clean comparison. Coordinate with marketing before launching tests on user-acquisition-sensitive surfaces. + +--- + +## When the math says "you cannot detect this" + +Sometimes the table reads "you need 200,000 users to detect this lift and you have 5,000 a week." Three options: + +1. Accept a larger MDE. Pick a bigger change worth detecting. A 3 percent absolute lift may be detectable in two weeks; a 0.3 percent lift may take a year. Test the bigger change. +2. Find a more sensitive metric. Sometimes the metric is the constraint, not the change. Switching from "purchases" to "add-to-cart" gives you a higher-frequency event with more sample. The trade-off is that ATC is less directly tied to revenue; pair the more-sensitive primary with a revenue guardrail. +3. Skip the test. If the change is small but cheap and reversible, ship without testing. If it is small and expensive to maintain, do not ship. Running an underpowered test produces noise dressed up as evidence; that is worse than no test. + +The discipline is to refuse to run tests that cannot answer the question. An underpowered test is not "better than nothing"; it is worse than nothing because it produces a result that feels meaningful but is not. diff --git a/dist/pi/.agents/skills/experimentation-analytics/SKILL.md b/dist/pi/.agents/skills/experimentation-analytics/SKILL.md new file mode 100644 index 0000000..eb34627 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/SKILL.md @@ -0,0 +1,333 @@ +--- +name: experimentation-analytics +description: How to read experiment results without fooling yourself. Confidence intervals, p-values, multiple testing, sequential testing, CUPED, heterogeneous treatment effects, ratio metrics, network effects, dashboard reconciliation, and the interpretation failures that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Read result panels without fooling yourself: confidence intervals, p-values, multiple testing, sequential testing, CUPED, ratio metrics, network effects, dashboard reconciliation" +display_order: 6 +--- + +# Experimentation Analytics + +A data-team-mentor's playbook for interpreting experiment results without fooling yourself. + +The result panel is the moment-of-truth for an experiment. The numbers on it determine whether you ship, kill, or iterate. They also expose every shortcut taken in the design phase: an underpowered test produces wide confidence intervals; a peeked test produces a too-narrow p-value; a ratio metric without delta-method correction produces overconfident lift estimates. Most ship-the-wrong-thing decisions trace back to misreading the result panel. + +This skill is the discipline that prevents misreading. It assumes the experiment was designed well (see the `experiment-design` skill). It assumes the platform's results panel is technically correct (most modern platforms are; some older ones are not). It assumes you can read a number off a screen. The hard part is knowing what each number actually means and what it does not, and that is what is here. + +When to use this skill: any time you are reading an experiment result panel and about to make a ship, kill, or iterate decision. + +--- + +## What this skill is for + +This skill covers result interpretation, the statistical concepts that make the numbers trustworthy, and the dashboard reconciliation work that prevents executive-level confusion when the experiment number does not match the BI number. The audience is product managers and data analysts who read experiment results together and need a shared vocabulary that does not paper over the dangerous parts of statistics. + +Companion skills cover the adjacent territory. The `experiment-design` skill covers pre-experiment thinking: hypothesis, sample size, MDE, segments, what NOT to test. Read it before designing the test; read this skill when reading the result. The `feature-flagging` skill covers the operational mechanics of flag management, environment promotion, and stale-flag cleanup. Together the three skills span the experimentation lifecycle from intent through interpretation. For platform-specific MCP commands, consult the chosen platform's docs; Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, and Kameleoon all expose rich analytics surfaces that this skill informs how to read. + +--- + +## The result panel: what every modern platform should expose + +A result panel that omits any of the following is a black box. Treat results from black-box platforms with extra skepticism, and consider exporting raw assignment and event data into a notebook where you can compute the missing pieces yourself. + +What a competent platform exposes: + +- Variants and traffic allocation (e.g., 50/50, 33/33/33). Allocation drift across the test window indicates assignment bugs. +- Per-variant primary metric: point estimate, confidence interval (or credible interval for Bayesian), sample size at the variant level. +- Lift: variant minus control, expressed as both absolute change and relative percent. Both numbers matter; relative is intuitive, absolute is what shows up in revenue calculations. +- Statistical significance: p-value (frequentist) or probability of being best (Bayesian). The methodology should be labeled clearly so you know which interpretation rules apply. +- Variance reduction technique applied: CUPED, post-stratification, regression adjustment. If the platform applies these silently, ask which. +- Guardrail metric statuses: each guardrail labeled green, amber, or red against its tolerance. The tolerance was set at design time; the panel just enforces it. +- Per-segment results for pre-registered segments only. Post-hoc segment slicers are tempting and dangerous. +- Test status: running, ended, decision filed. +- A time series of the lift across the test window. This is where novelty effects, primacy effects, and assignment bugs become visible. + +If you are looking at a result panel that hides any of these, the first move is to surface them, not to ship. + +--- + +## Confidence intervals: the most important number + +The single most important number on the result panel is the confidence interval (CI) on the lift. More important than the point estimate. More important than the p-value. The CI tells you what you actually know. + +What a 95% CI of [+2%, +6%] means: under repeated sampling, the true effect would fall in this range 95% of the time. The true effect is most likely somewhere near the middle, but the extremes are entirely consistent with the data. + +What it does not mean: it does not literally mean "there is a 95% chance the true effect is between +2% and +6%." That is the Bayesian credible interval, which often gives similar numerical answers but is conceptually different. PMs can usually live with the loose intuition; analysts should know the precise version when defending a number to a skeptic. + +The width of the CI matters more than the center for most ship decisions. A wide CI means you do not know much yet. A narrow CI means you know with precision. The point estimate is your best guess; the width is your humility. + +Practical decision rules, in order of importance: + +1. If the CI includes zero AND a meaningful positive number (say [-1%, +5%]), you do not have enough data to ship. Period. The point estimate may look favorable, but the data is consistent with no effect and consistent with a meaningful win. You cannot tell which. +2. If the CI is all-positive (lower bound greater than zero, e.g., [+1%, +4%]), there is a real effect. Now evaluate magnitude: is the lower bound large enough to be worth the implementation cost? +3. If the CI is all-negative (upper bound less than zero, e.g., [-5%, -1%]), there is real harm. Kill the test. +4. If the CI straddles zero but is narrow (e.g., [-0.5%, +0.5%]), this is a real null result. The effect is small enough to call essentially zero. Useful information; do not ship the change for "lift" reasons (you found none) but do not panic about harm either. +5. If the CI straddles zero and is wide (e.g., [-5%, +8%]), the test is inconclusive. The data is consistent with a moderate win, no effect, or a moderate loss. Run longer, run bigger, or accept that the question cannot be answered at the available traffic. + +For a worked-example cheatsheet, see [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). + +--- + +## P-values: what they mean and what they do not + +The p-value is the probability of observing the lift you saw (or a larger one) IF the true effect were zero. A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. + +What the p-value does not mean, despite frequent abuse: + +- It does not mean "there is a 96% chance the treatment works." That sentence has no defensible interpretation; the p-value is computed under the assumption that the treatment does NOT work, so it cannot tell you the probability that it does. +- It does not mean "the effect is large." A tiny effect tested against a huge sample can produce a vanishingly small p-value. The p-value is about the strength of evidence against the null, not the size of the effect. +- It does not mean "the result will replicate." A p-value of 0.04 is associated with replication rates well below 50% in most published research; statistical significance is not reproducibility. + +The 0.05 cutoff is convention, not law. If you pre-committed to alpha equals 0.05, follow it; the discipline of pre-commitment is more valuable than the specific threshold. If you did not pre-commit, p equals 0.06 is not categorically different from p equals 0.04, and treating it as such is theater. + +Always read the CI alongside the p-value. The p-value tells you about the null hypothesis; the CI tells you about the magnitude. Both matter; neither is sufficient alone. A p-value of 0.001 with a CI of [+0.1%, +0.3%] is a real but practically tiny effect; a p-value of 0.08 with a CI of [-1%, +12%] is a noisy estimate that could be huge or zero. The former is technically significant and not worth shipping; the latter is technically not significant and you might still want to dig deeper. + +The peeking problem applies to p-values directly. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Modern platforms with sequential testing report "always-valid" or "anytime-valid" p-values that survive peeking; older platforms do not. Know which you are looking at. See [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md) for deeper coverage. + +--- + +## Multiple testing corrections + +The problem in one sentence: with twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty comparisons, two or three. With a hundred, five. + +Where multiple testing creeps in unintentionally: + +- Multiple variants: A vs B vs C vs D is three pairwise comparisons against control, not one. +- Multiple metrics: tracking primary plus six guardrails plus three secondary metrics is ten chances to find significance somewhere. +- Multiple segments: ten segments times three metrics is thirty chances. +- Multiple time windows: looking at week 1, week 2, week 3, and the full test is four chances per metric per segment. + +Two correction methods you should know: + +- Bonferroni correction. Divide alpha by the number of comparisons. Conservative; controls the family-wise error rate (the probability of even one false positive across the family of tests). Use when false positives are catastrophic. +- Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (the expected proportion of false positives among the things called significant). Better for exploratory analysis. + +Most modern platforms support these natively as a configuration option. Configure them, or know which the platform applies by default. Some platforms apply corrections silently to the displayed p-values; others report uncorrected numbers and expect you to do the math. + +The PM-friendly heuristic: pre-register your primary metric and primary segment. Treat everything else as exploratory. Findings in non-primary metrics or non-primary segments require larger effects, replication in a follow-up test, or both before they justify shipping. The discipline of designating primary up front protects you from the multiple-testing trap better than any correction formula. + +--- + +## Sequential testing math + +The peeking problem revisited from the analytics side. Classical t-tests, z-tests, and proportion tests assume one analysis at the end of a test. If you analyze the data five times during the test and stop the moment you see significance, your false positive rate is much higher than the nominal 5%. With daily peeking on a four-week test, false positive rate can climb above 30%. + +Sequential testing methods adjust the math to allow continuous monitoring without inflating false positives. The names you will encounter: + +- mSPRT (mixture sequential probability ratio test). Produces "always-valid" p-values: you can look any time, and the false positive rate stays at the nominal alpha. Common in modern platforms. +- Group sequential designs. Plan a fixed set of interim analyses (say, three) with adjusted significance thresholds at each. Less flexible than mSPRT but well-understood. +- Anytime-valid confidence intervals. The CI version of always-valid p-values. Wider than fixed-horizon CIs by design; the cost of peek-safety is some statistical efficiency. + +Modern platforms with sequential testing built in: Statsig (always-valid by default), Eppo (sequential CIs as a configuration), parts of PostHog (depending on the experiment type), GrowthBook (mSPRT supported). If your panel says "always-valid p-value" or "anytime-valid CI," that is sequential. If it says "p-value" with no qualifier, it is probably fixed-horizon and peeking inflates false positives. + +If your platform does not support sequential testing, the discipline is: pre-commit to a single analysis date at launch, do not peek, and if you must peek, do not make decisions based on the peek. Save the decision-making for the pre-committed date. This is hard. Sequential testing makes it easier. + +The trade-off: sequential tests have wider CIs and less aggressive p-values than fixed-horizon tests at the same sample size. The cost is real but usually worth it for PM contexts where the discipline of not peeking is impractical. + +--- + +## CUPED variance reduction + +CUPED (Controlled-experiment Using Pre-Experiment Data) uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. The result is the same point estimate with a much narrower confidence interval, often 30% to 50% narrower, which is equivalent to roughly doubling your effective sample size for free. + +When CUPED helps: + +- Metrics with high pre-experiment baseline variance: revenue per user, sessions per user, engagement minutes, content consumption. +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When CUPED does not help: + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline (a user either signs up or does not; there is nothing to subtract). +- Tests where pre-experiment behavior is essentially uncorrelated with the metric being moved. + +How to read CUPED-adjusted results: the point estimate is roughly the same as the unadjusted estimate; the CI is narrower. If a result switched from "significant with CUPED" to "not significant without CUPED," that is normal and the CUPED-adjusted version is the more powerful test. If a result went the other way (significant without CUPED, not significant with), the unadjusted result was probably noise that CUPED correctly removed. + +A common confusion: "CUPED made our lift smaller, so we should ship the unadjusted version." This is wrong. CUPED reduces variance, not point estimates. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. Trust the adjusted version. + +Platform support: Statsig, Eppo, GrowthBook, parts of PostHog, Amplitude (Experiment product). Optimizely has equivalent variance reduction. If your platform offers CUPED, turn it on for any metric where pre-experiment data exists. + +For deeper coverage of CUPED, the delta method, and other statistical methods, see [`references/statistical-method-reference.md`](references/statistical-method-reference.md). + +--- + +## Heterogeneous treatment effects (HTE) and segments + +A heterogeneous treatment effect is when the treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. This is common, often interesting, and easy to over-read. + +Why HTE is tempting: "let us just ship to new users." Why it is dangerous: post-hoc segment discovery is often noise; targeting infrastructure costs are real; UI complexity from per-segment behavior compounds over time. + +The right way to handle HTE: + +- Pre-register the segments you care about before launching. Two or three is plenty; ten is overfitting waiting to happen. +- If a pre-registered segment shows a meaningfully different effect, treat it as evidence worth following up. Not as a green light to ship to that segment alone. +- Before shipping segment-only behavior, ask: is the segment large enough to matter, is the effect large enough to justify the targeting work, and can we build the targeting cleanly in production? +- If the segment was discovered post-hoc by slicing the data many ways, treat the finding as a hypothesis for a follow-up test. Do not ship based on one observation. + +HTE versus simple averaging: when segments have meaningfully different effects, the average underrepresents both. A treatment that is +10% for half the population and -5% for the other half averages to +2.5%, which understates the win for half and ignores the loss for the other. The average is still the right number for "ship to everyone" decisions; per-segment numbers are the right inputs for "should we invest in segment-specific targeting" decisions. + +Practical heuristic: if pre-registered segments show meaningfully different effects, write a follow-up hypothesis. Run a follow-up test that confirms the segment behavior with appropriate power. Then decide on segment-specific shipping. The cost of the follow-up test is much smaller than the cost of shipping segment-targeted behavior that does not actually work. + +--- + +## Ratio metrics and the delta method + +Most "rate" metrics are ratios. Conversion rate equals conversions divided by users. Click-through rate equals clicks divided by impressions. Revenue per user equals revenue divided by users. Average order value equals revenue divided by orders. + +Why this matters for analytics: standard variance estimation for sums does not apply directly to ratios. Naive variance estimation on ratios produces incorrectly narrow confidence intervals and inflated false positive rates. You ship things that look significant but are not, because the math under the hood was wrong. + +Two correct approaches: + +- Delta method. A calculus-based correction (Taylor expansion linearization) that produces correct CIs and p-values for ratio metrics. Fast, well-understood, what most modern platforms use. +- Bootstrap. A simulation-based alternative: resample users with replacement many times, compute the ratio each time, and read off the empirical distribution. Distribution-free and intuitive; slower than delta method. + +How to verify your platform: ask "what variance estimator do you use for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (one row per user, converted yes or no). If the answer is "delta method," "linearization," or "bootstrap," correct. + +Most modern platforms (Statsig, Eppo, PostHog, Optimizely, GrowthBook) handle this correctly. Older or homegrown platforms often do not. The risk is silent: the panel shows confidence intervals that look reasonable but are too narrow, and you ship changes that do not produce the claimed effect. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. Suppose treatment shows a 5% lift with a CI that excludes zero under the wrong (naive) variance estimator. Under the correct delta-method estimator, the same point estimate has a CI that includes zero. The wrong math says "significant, ship." The correct math says "inconclusive, run longer or accept noise." Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production, then puzzling over why the launch did not move the dashboard. + +--- + +## Bayesian vs frequentist results panels + +Frequentist panels (most older platforms, parts of most modern ones) show p-values, confidence intervals, and "statistically significant" labels. Bayesian panels (Eppo by default, Statsig as an option, parts of PostHog) show probability of being best, credible intervals, and posterior distributions. + +For most PM contexts, both approaches produce similar ship-or-kill decisions when the experiment was designed correctly. The vocabulary differs; the underlying judgment is similar. + +Bayesian advantages: + +- Natural multi-variant comparison: "variant B has 87% probability of being best" reads more naturally than the equivalent Bonferroni-corrected p-value soup. +- Peek-safe by construction: posterior probabilities are valid at any time without sequential corrections. +- More intuitive for stakeholders unfamiliar with hypothesis testing. +- Allows informative priors when you have prior knowledge (rare in practice for shipping decisions). + +Frequentist advantages: + +- Better-understood: most analytics teams have stronger frequentist training. +- Clearer pre-registration semantics: "alpha equals 0.05, MDE equals 5%, decision rule X" is unambiguous. +- Longer track record in regulated contexts. + +Mixing them within a single experiment is fine. Most platforms (Eppo, Statsig) let you toggle. Pick one per experiment and stick with it; do not switch mid-flight to chase a more favorable interpretation. That is the Bayesian-frequentist version of p-hacking and corrodes the discipline. + +--- + +## Network effects and SUTVA violation + +SUTVA (Stable Unit Treatment Value Assumption) is the technical name for "one user's treatment does not affect another user's outcome." When SUTVA holds, standard A/B test math works. When it is violated, the math systematically understates or overstates the true effect. + +When SUTVA is violated: + +- Two-sided marketplaces. Changes to buyers shift seller behavior, which affects control buyers competing for the same supply. Treatment buyers' actions leak into the control group's experience. +- Social products. A treatment user's changed behavior affects the experience of users they interact with, regardless of which group those friends are in. +- Supply-constrained features. When supply is limited, treatment users compete with control users for the same scarce resource, and the test cannot cleanly separate treatment effect from substitution. +- Notification systems. A treatment that increases notification volume changes user behavior across the whole platform, not just in the treatment cell. + +The "interference dampens lift" pattern is the most common version. In marketplace experiments, if your treatment looks small, the true effect (in the absence of interference) may be 2x to 3x larger than what the standard A/B test reports. Killing a winning test because the leaked-into-control lift looked small is a common mistake. + +Detection methods: + +- Switchback experiments. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control, etc.). Eliminates cross-user interference within each window; requires careful temporal modeling. +- Cluster randomization. Assign whole units (cities, markets, friend groups) rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. +- Geographic experiments. Launch in some regions, hold others. Slow and expensive but interference-clean. + +When in doubt about whether interference is present, run a small cluster-randomized version as a check. If the cluster-randomized lift is much larger than the user-randomized lift, you have evidence of interference and should rerun the main test as cluster-randomized. + +--- + +## Dashboard metric vs experiment metric reconciliation + +The scenario: your business intelligence dashboard shows revenue grew 8% last week. Your experiment platform shows the treatment lifted revenue 2%. How can both be true? + +Likely answers, ranked by frequency: + +- Different denominators. The dashboard shows all users; the experiment shows just enrolled users. Most experiments enroll a subset; the lift only applies to that subset. +- Different time windows. The dashboard is rolling 7 days; the experiment is fixed start to end. The two windows can move independently. +- External effects. Marketing campaigns, seasonality, competitor activity, news cycles. The experiment correctly excludes these by random assignment; the dashboard reflects them. +- Selection effects. Who gets enrolled in the experiment matters. New users only? Logged-in users only? Users who passed a feature flag check? Each filter changes the population the lift applies to. +- Different metric definitions. "Revenue" might be gross in one place and net of refunds in another. "Conversions" might count differently across systems. + +Reconciliation discipline: never report experiment results as "the feature drove $X in revenue this week." Always report as "the feature lifted enrolled-user revenue Y% during the test period." The first phrasing implies a company-wide impact that the experiment cannot measure; the second phrasing is precise about what the experiment actually showed. + +The "blended attribution" trap is the most common reconciliation failure. PM takes the experiment lift (say +2% revenue per user) and multiplies by the total user base for a company-wide impact estimate ("$10M in incremental revenue"). This is wrong twice over. The lift only applies to enrolled users (typically 10% to 50% of the base). Even within the enrolled group, the lift was measured during the test conditions; long-term and at full scale, the effect can be different. The right phrasing is "during the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control." Then leadership can do the careful arithmetic of how that translates at full launch. + +For deeper reconciliation patterns and stakeholder-facing language, see [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). + +--- + +## Long-term effect estimation + +Most A/B tests run for two to four weeks. Many feature decisions need a thirty- to ninety-day understanding because behavior changes over longer windows: novelty fades, primacy fades, retention impacts emerge, network effects compound. + +Three patterns for long-term measurement: + +- Holdout groups. Keep a percentage of users (often 5% to 10%) on the control treatment for thirty or more days post-launch. Compare their long-term behavior to the launched-to users. The comparison measures the long-term effect cleanly because the holdout was randomized at the same time as the original test. +- Geo experiments. Launch the change in some markets and hold others. Measure long-term differences across market pairs. Slow, expensive, and the markets need to be comparable, but interference-clean and capable of measuring effects that user-randomization cannot. +- Difference-in-differences (diff-in-diff). Pre-launch versus post-launch measurement in a treated market versus a control market. Useful when you cannot randomize at all (regulatory rollouts, partner-specific changes). Weaker than randomized methods but defensible when randomization is impossible. + +Practical heuristic: any feature with novelty risk (new UI, new mechanic, new pricing, new notification cadence) deserves a thirty-day holdout. Set it up at launch, not later; setting it up later requires unwinding the launch and is rarely done in practice. The cost of the holdout is small (a small percentage of users on the old experience for a month); the value is the ability to detect long-term degradation before it compounds. + +--- + +## Common interpretation failures + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "P equals 0.04, ship it." No consideration of CI width, magnitude, or guardrails. Significance is a necessary condition, not a sufficient one. +- "We saw +5% on day 3, ending early." Peeking, novelty effect, or both. Day-3 lifts are routinely larger than day-14 lifts; ending early ships noise. +- "The new flow worked for power users (post-hoc segment)." Noise mining. The segment was found by slicing the data multiple ways; the apparent lift will not replicate. +- "Our experiment said +2%, but launch only delivered +0.5%." Often the experiment was correct: the lift applied to enrolled users in test conditions, and at full launch the effect is diluted by non-enrolled users, novelty fade, or interference effects the test could not capture. +- "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail violation that was reframed as "no signal." If retention is a guardrail, the guardrail is binding; "we did not see a clear signal" is not the same as "we have evidence of safety." +- "We CUPED-adjusted away a real treatment effect." CUPED reduces variance, not the point estimate. If the lift looked smaller after CUPED, the unadjusted lift was probably noise that CUPED correctly removed. Trust the adjusted version. +- "Two segments showed opposite effects; we shipped to the better segment." Likely overfitting unless both segments were pre-registered and the targeting infrastructure exists. Re-test before shipping. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped." Inconclusive is inconclusive. Directional patterns are not evidence; they are wishful reading of noise. + +--- + +## The framework: 14 considerations for trustworthy experiment interpretation + +Trustworthy interpretation sits at the intersection of fourteen considerations. Each is covered in detail in its own section above. + +1. Result panel completeness. The panel exposes variants, allocation, per-variant metrics, lifts, significance, variance reduction, guardrails, segments, time series, and status. Missing pieces are red flags. +2. Confidence interval reading. Width matters more than center. Five practical decision rules cover the cases where CI excludes zero, includes zero narrowly, and includes zero widely. +3. P-value semantics. The probability of seeing the lift if the null is true. Not the probability that the treatment works. Always read alongside the CI. +4. Multiple testing corrections. Bonferroni for family-wise control, BH for false discovery rate. Pre-register primary metrics and segments; treat the rest as exploratory. +5. Sequential testing math. Always-valid p-values and anytime-valid CIs survive peeking. Fixed-horizon p-values inflate false positives under daily monitoring. +6. CUPED variance reduction. Same point estimate, narrower CI. Use whenever pre-experiment data is available and informative. +7. Heterogeneous treatment effects. Pre-register segments. Treat post-hoc segment effects as hypotheses for follow-up tests, not as ship signals. +8. Ratio metrics. Use delta method or bootstrap. Naive proportion estimators understate variance and inflate false positives. +9. Bayesian vs frequentist. Pick one per experiment and stick with it. Both produce similar ship decisions when the experiment was designed correctly. +10. Network effects and SUTVA. Marketplace and social products often violate SUTVA. Cluster randomization, switchback, or geographic experiments when interference is suspected. +11. Dashboard reconciliation. Different denominators, time windows, external effects, and metric definitions explain most disagreements between BI dashboards and experiment panels. +12. Long-term effect estimation. Holdouts, geo experiments, and diff-in-diff for effects that emerge over thirty to ninety days. +13. Common interpretation failures. A pattern catalog of the most frequent ways smart teams ship wrong things. +14. The discipline of inconclusive. The hardest call is "we do not have enough signal to ship." It is often the right call. + +The sections above expand each consideration in turn. Read the relevant section before making the decision, not after. + +--- + +## Reference files + +- [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). How to read a CI, what to ignore, the five decision rules with worked examples for each. +- [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md). What it means, what people pretend it means, the 0.05 convention, the peeking problem, and the multiple-testing context. +- [`references/statistical-method-reference.md`](references/statistical-method-reference.md). CUPED, the delta method, sequential testing methods (mSPRT, group sequential, anytime-valid), HTE handling, multiple testing corrections, cluster randomization. The technical reference for analysts. +- [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). Why the BI number does not match the experiment number, the blended-attribution trap, and how to communicate the difference to non-statistical stakeholders. +- [`references/result-presentation-templates.md`](references/result-presentation-templates.md). Five templates for stakeholder communication: clear win, clear loss, inconclusive (the most common, hardest), mixed (positive primary with ambiguous guardrail), and long-term holdout report. +- [`references/analytics-platform-comparison.md`](references/analytics-platform-comparison.md). Profiles of seven major platforms (Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, Kameleoon) covering what each exposes, what each hides, and the gotchas in each. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). Fifteen-plus failure patterns: name, symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it inconclusive + +Most experiment results are not clear ship-or-kill. They are inconclusive: lift exists but the CI straddles zero; lift is real but does not justify the implementation cost; lift is significant but a guardrail is concerning; lift looks great in one segment but the segment is small or the targeting infrastructure does not exist. + +The hardest decision a PM makes in a given week is often "we do not have enough signal to ship." The temptation to lower the bar after seeing the result is enormous. The discipline of saying "inconclusive" is the discipline of caring about being right more than being decisive. + +The same discipline applies to analysts. The temptation to slice the data one more way until something looks significant, to apply one more variance reduction technique, to switch from frequentist to Bayesian mid-test, is constant. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +Inconclusive is a valid outcome. The lesson, if there is one, is for the next hypothesis: the effect is smaller than expected, the segment matters, the test was underpowered, the metric was the wrong one. Use the inconclusive result to design a better next test. Do not retrofit a story onto the current one. + +For pre-experiment design discipline, see the `experiment-design` skill. For the operational mechanics of feature flags that deliver the variants, see the `feature-flagging` skill. For platform-specific MCP commands and example prompts, consult the chosen platform's documentation. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md b/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md new file mode 100644 index 0000000..a8c3504 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/analytics-platform-comparison.md @@ -0,0 +1,147 @@ +# Analytics platform comparison + +Profiles of seven major experimentation platforms covering what each exposes, what each hides, and the gotchas in each. For MCP setup, auth, and example prompts, consult each platform's official documentation. + +The categorization below is for analytics surface area specifically. All seven platforms are competent at running experiments; the difference is what they expose on the result panel and how the math under the hood handles edge cases. + +--- + +## Statsig + +Statistical defaults. Among the most rigorous in the category. Always-valid p-values (sequential testing) by default. CUPED variance reduction available and easy to enable. Delta method for ratio metrics. Comprehensive HTE analysis with pre-registered and exploratory modes. + +What is exposed. Per-variant metrics with CIs, lift point estimate, always-valid p-value, sample size, variance reduction technique applied, guardrail status, segment results for pre-registered segments, time series of the lift across the test window. + +What can be hidden by default. Some advanced configuration is buried in the UI; defaults are sensible but worth confirming. The "topline metrics" view simplifies away the CI in some contexts. + +Gotchas. + +- Always-valid p-values are wider than fixed-horizon by design. Teams new to sequential testing sometimes interpret "less significant" as "weaker effect" rather than "peek-safe math." +- The auto-generated guardrail metrics catch some categories well (latency, error rate) and miss others (business-critical metrics specific to your product). Augment with custom guardrails. +- The "experiment hub" view groups results across multiple experiments and can mask single-experiment subtlety. + +Where it shines. Mid-stage to late-stage product teams running many concurrent experiments where peek-safety and variance reduction matter. The default rigor saves teams from common mistakes without requiring statistical expertise. + +--- + +## PostHog + +Statistical defaults. Solid for the open-source experimentation category. Frequentist by default; Bayesian available. Variance reduction via "stats engine" configuration. Sequential testing in some experiment types. + +What is exposed. Per-variant metrics, CIs, p-values, sample size, time series, segment results. + +What can be hidden. The newer "stats engine" updates change defaults across versions; what you see depends on the deployment version. Older deployments may use less-rigorous defaults. + +Gotchas. + +- Self-hosted vs cloud can differ in stats engine version. Confirm the version when interpreting numbers. +- The "winner" badge can appear on results that are technically significant but practically tiny. Always read the CI. +- Bayesian and frequentist views can coexist for the same experiment; use one consistently per experiment. + +Where it shines. Teams that want experimentation embedded in their analytics platform rather than separate. PostHog's strength is the integration of feature flags, experiments, session recording, and product analytics in one place. + +--- + +## Optimizely + +Statistical defaults. Enterprise-grade rigor. Stats Engine includes sequential testing, ratio-aware variance estimation, and configurable significance thresholds. Long track record in the category. + +What is exposed. Comprehensive per-variant statistics, configurable significance thresholds, sequential testing labels, sample size, segment analysis with pre-registration. + +What can be hidden. Configuration depth means defaults vary by account setup. Confirm with the platform admin which defaults are in play for your project. + +Gotchas. + +- The classic Optimizely product (Web Experimentation) and the newer products (Feature Experimentation, Personalization) have different stats engines. Know which product your team is on. +- Enterprise pricing can mean limited license seats; non-statistician PMs sometimes work from screenshots taken by analysts, which loses interactive panel context. +- The "lift" display can default to relative percent without the absolute number; both matter. + +Where it shines. Larger organizations with established experimentation practices, regulated contexts where the rigorous track record matters, and teams that need extensive personalization alongside experimentation. + +--- + +## GrowthBook + +Statistical defaults. Open-source-first, warehouse-native. Explicit choice between Bayesian and frequentist. Sequential testing via mSPRT. CUPED supported. + +What is exposed. Per-variant metrics with CIs, lift, significance, variance reduction, guardrails, segment results. + +What can be hidden. Because GrowthBook runs on top of your data warehouse, the metric definitions live in your SQL; verify them when reading results. A subtle metric query change can shift results without anyone noticing. + +Gotchas. + +- Warehouse latency affects how fresh the result panel is. A daily batch is common; treat panel data as up to one day stale. +- Custom metrics defined in SQL can drift from dashboard definitions of the same metric. Reconcile carefully. +- The "experiment health checks" surface assignment imbalance and other quality issues; pay attention when they fire. + +Where it shines. Engineering-led teams that want experimentation tied directly to the warehouse and version-controlled metric definitions. The open-source core means full transparency on the math. + +--- + +## Eppo + +Statistical defaults. Best-in-class statistical defaults among the platforms. Bayesian and frequentist supported, with Bayesian as the default for most use cases. Sequential CIs available. CUPED supported. Delta method for ratio metrics. Strong HTE analysis. + +What is exposed. Per-variant metrics with credible intervals (Bayesian) or CIs (frequentist), probability of being best, posterior distributions, lift, guardrails, segments. + +What can be hidden. The Bayesian default produces "probability variant B is best" rather than a p-value, which can confuse stakeholders trained on frequentist conventions. Switch to frequentist if your team's vocabulary is p-value-based; do not switch mid-experiment. + +Gotchas. + +- Bayesian probabilities and frequentist p-values answer different questions; do not translate one into the other naively. +- Eppo's "decision support" feature recommends actions based on the result; treat the recommendation as input, not as the decision. +- Warehouse-native like GrowthBook; same caveats about metric definition drift. + +Where it shines. Data-team-led organizations that want statistical rigor as a default. Eppo's design philosophy is "make it hard to do the wrong thing"; the defaults reflect that. + +--- + +## Amplitude (Experiment) + +Statistical defaults. Behavioral analytics first, experimentation second. Frequentist defaults; sequential testing available. Variance reduction supported. + +What is exposed. Per-variant metrics with CIs, p-values, sample size, segment analysis, guardrails. Tightly integrated with Amplitude's behavioral analytics surface. + +What can be hidden. Some statistical configuration options are less prominent than in Statsig or Eppo; defaults are reasonable but worth confirming. + +Gotchas. + +- Strength is the integration with behavioral analytics, not the rigor of the experimentation engine. For teams that prioritize statistical sophistication, the engine is competent but not the strongest. +- Amplitude's "insights" auto-generate from event data; the same flexibility that makes them useful makes it easy to slice into noise. +- Experiment results can be viewed alongside cohort and funnel analyses; this is powerful and risky (post-hoc cohort definitions are noise mining). + +Where it shines. Product teams already invested in Amplitude for behavioral analytics. The integration of experiment results with the broader product analytics is the differentiator. + +--- + +## Kameleoon + +Statistical defaults. Frequentist with Bayesian options. CUPED and sequential testing supported. Strong personalization and AI-driven optimization features. + +What is exposed. Per-variant metrics with CIs, p-values, lift, segments, guardrails. + +What can be hidden. The personalization and AI optimization features can take experiment results and apply them automatically; verify which of your "experiments" are actually fully randomized A/B tests vs personalization rollouts. + +Gotchas. + +- The boundary between experiment and personalization can blur. Personalization decisions made by an AI engine are not the same as ship decisions made from a randomized A/B test. +- Less common in the US than the European market; documentation and community resources are more limited than for Statsig, PostHog, or Optimizely. +- Some advanced statistical features require specific subscription tiers. + +Where it shines. Teams running heavy personalization alongside experimentation, particularly in the European market. The personalization features are differentiated; the experimentation engine is competent. + +--- + +## Quick comparison + +\| Platform \| Sequential testing \| CUPED \| Delta method \| Bayesian option \| Strongest for \| +\|---\|---\|---\|---\|---\|---\| +\| Statsig \| Default \| Yes \| Yes \| Yes \| Multi-team experimentation rigor \| +\| PostHog \| Some types \| Configurable \| Yes \| Yes \| Embedded analytics + experiments \| +\| Optimizely \| Yes \| Yes \| Yes \| No (frequentist Stats Engine) \| Enterprise + personalization \| +\| GrowthBook \| Yes (mSPRT) \| Yes \| Yes \| Yes \| Warehouse-native, open source \| +\| Eppo \| Yes \| Yes \| Yes \| Default \| Statistical rigor by default \| +\| Amplitude \| Yes \| Yes \| Yes \| Yes \| Behavioral analytics integration \| +\| Kameleoon \| Yes \| Yes \| Yes \| Yes \| Personalization-heavy contexts \| + +The platform choice is rarely the bottleneck on getting experimentation right. All seven are competent. The bottleneck is the design discipline (covered in the `experiment-design` skill), the interpretation discipline (covered in this skill), and the operational discipline of the flag layer (covered in the `feature-flagging` skill). Pick the platform that fits the team's existing stack and skill mix; spend the effort on the disciplines. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md b/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..86c27fb --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/common-interpretation-failures.md @@ -0,0 +1,203 @@ +# Common interpretation failures + +Fifteen-plus failure patterns that produce confidently wrong shipping decisions. Each pattern is described as: name, symptom (what it looks like in the panel or the discussion), root cause (why it happens), fix (what to do this time), prevention (how to avoid it next time). + +--- + +## Pattern 1: P-value worship + +Symptom. "P equals 0.04, ship it." No discussion of CI width, magnitude, or guardrails. + +Root cause. Treating statistical significance as a binary truth. The p-value answers one specific question (how surprising is this data under the null) and people use it to answer all questions. + +Fix. Always pair the p-value with the CI on the lift and the guardrail status. A significant p-value with a wide CI that includes practically tiny effects is not a ship signal. + +Prevention. Pre-commitment includes the MDE, not just the alpha. The decision rule should reference the lift magnitude relative to the MDE, not just the p-value. + +--- + +## Pattern 2: Early stop on a peek + +Symptom. Test ended on day 3 or day 5 because the result "looked great." Headline lift is 5% to 10%; later analysis shows the effect was much smaller. + +Root cause. Standard p-values inflate under peeking. Early-test lifts are systematically larger than late-test lifts due to regression to the mean and novelty effects. + +Fix. Re-run the test to the pre-committed end date. Treat the early result as suggestive only. If the platform supports always-valid p-values, those are peek-safe; otherwise, do not stop early. + +Prevention. Pre-commit the analysis date at launch. If the platform offers sequential testing, enable it. If not, do not look at intermediate results. + +--- + +## Pattern 3: Post-hoc segment mining + +Symptom. "The new flow worked for power users on Android in the EU on weekends." The segment was discovered by slicing the data many ways looking for an effect. + +Root cause. Multiple comparisons. With enough segments, some will show a "significant" effect purely by chance. The pattern is real for the test data; it does not replicate. + +Fix. Treat the post-hoc segment finding as a hypothesis for a follow-up test, not as a ship signal. Pre-register the segment in the new test and run it cleanly. + +Prevention. Pre-register segments at design time. Two or three is plenty; ten is overfitting waiting to happen. Treat any segment not in the pre-registration list as exploratory. + +--- + +## Pattern 4: Launch dilution misread + +Symptom. "Our experiment said +2%, but launch only delivered +0.5%. The experiment was wrong." + +Root cause. The experiment lift applied to enrolled users in test conditions. Launch dilution from non-enrolled users, novelty fade, and interference effects routinely produce smaller production effects than test effects. The experiment was usually correct; the production measurement is correctly capturing the diluted effect. + +Fix. Compare apples to apples: the launch effect on the same enrolled-user population, in the same conditions. If the launch effect on enrolled users matches the test, the experiment was right; the dashboard sees a smaller number because the dashboard includes everyone. + +Prevention. Communicate experiment results in enrolled-user terms, not extrapolated to the full base. The blended-attribution trap is the source of most "experiment wrong" complaints. + +--- + +## Pattern 5: Guardrail reframing + +Symptom. "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail movement that was reframed as "no signal" rather than treated as binding. + +Root cause. The guardrail was pre-committed but the team did not pre-commit a clear rule for "what counts as a guardrail violation." A wide CI on the guardrail leaves room for interpretation; the interpretation usually favors shipping. + +Fix. If retention is a guardrail, the guardrail binds. "We did not see a clear signal" is not the same as "we have evidence of safety." A wide guardrail CI means the test was underpowered for the guardrail; the right answer is more sample, not "ship anyway." + +Prevention. At pre-commitment, define guardrail rules as: "ship only if the CI on the guardrail clearly excludes a [X percent] degradation." Then apply the rule mechanically when results come in. + +--- + +## Pattern 6: CUPED misinterpretation + +Symptom. "We CUPED-adjusted away a real treatment effect. Let us report the unadjusted version." OR "The unadjusted lift is bigger; CUPED is hiding our win." + +Root cause. Misunderstanding what CUPED does. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior. + +Fix. Trust the CUPED-adjusted estimate. If the estimate is smaller and the CI is narrower, the CUPED estimate is closer to the true effect. + +Prevention. Educate the team on what CUPED does before enabling it. The first time the unadjusted and adjusted numbers diverge, walk through why. + +--- + +## Pattern 7: Opposite-segment shipping + +Symptom. "Two segments showed opposite effects; we shipped to the better segment." Often without re-testing or without infrastructure to support segment-specific behavior. + +Root cause. Post-hoc segment discovery (most common) or pre-registered segments where the targeting infrastructure does not exist. Either way, segment-only shipping is a significant commitment that requires more evidence than a single observation. + +Fix. Treat the segment finding as a hypothesis for a follow-up test. Confirm the effect with an appropriately powered re-test. Build the targeting infrastructure with eyes open about ongoing maintenance cost. + +Prevention. Pre-register segments. Build the targeting infrastructure separately, before any segment-specific shipping decision; do not let the decision force the infrastructure into existence under deadline pressure. + +--- + +## Pattern 8: Directional ship + +Symptom. "The result was technically inconclusive, but the trend was directional so we shipped." + +Root cause. Inconclusive is hard to communicate; directional language sounds more decisive. The team substitutes the appearance of evidence for actual evidence. + +Fix. Inconclusive is inconclusive. The directional pattern is wishful reading of noise. Do not ship; either run a bigger test or kill the hypothesis. + +Prevention. Pre-commit decision rules that map each possible result to a ship-or-kill decision. The inconclusive case should map to "do not ship" by default. Discussions of "directional" outcomes are a sign that pre-commitment was incomplete or is being ignored. + +--- + +## Pattern 9: Mid-test methodology switch + +Symptom. Test was running with frequentist analysis; results were ambiguous; team switched to Bayesian (or vice versa) and the new view "shows we should ship." + +Root cause. Different methodologies can produce different ship recommendations on the same data, particularly near the significance threshold. Switching mid-flight to find the more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +Fix. Stick with the methodology pre-committed at launch. If the result is ambiguous under the pre-committed method, that is the result. + +Prevention. Pre-commit the methodology along with the metric and the alpha. Document the choice in the experiment configuration so the change is visible if anyone tries. + +--- + +## Pattern 10: Ratio metric without delta method + +Symptom. Conversion rate or revenue per user with a CI that looks suspiciously narrow. The result panel shows significance that does not replicate at launch. + +Root cause. Naive variance estimation on ratio metrics produces incorrectly narrow CIs and inflated false positive rates. The platform did not use delta method, bootstrap, or another ratio-aware estimator. + +Fix. Re-analyze with a ratio-aware estimator. If the platform does not support one, export raw data and compute correctly in a notebook. + +Prevention. Verify your platform's variance estimator for ratio metrics during onboarding. If the answer is "standard t-test on proportions," consider migrating or implementing the correction yourself. + +--- + +## Pattern 11: Marketplace interference undercount + +Symptom. Marketplace experiment shows a small lift; team kills the test as not worth the effort. Later, a feature implemented for other reasons shows a much larger effect on the same metric. + +Root cause. SUTVA violation. In two-sided marketplaces, treatment users compete with control users for the same supply; the lift "leaks" into control. The standard A/B test undercounts the true effect, often by a factor of 2x to 3x. + +Fix. Re-run as cluster randomized (whole markets to treatment or control) or switchback. Compare the results to the user-randomized version to estimate the interference factor. + +Prevention. Identify SUTVA violation risk at design time. For marketplace, social, and supply-constrained features, default to cluster randomization or switchback unless interference is demonstrably negligible. + +--- + +## Pattern 12: Definition drift between systems + +Symptom. Experiment result shows +X% on conversion. Dashboard shows the launch having no effect on conversion. Investigation reveals the two systems define "conversion" differently. + +Root cause. Metric definitions live in different places (experiment platform, BI dashboard, data warehouse) and drift over time. Each definition individually makes sense; the comparison is meaningless. + +Fix. Reconcile the definitions before the next post-launch report. Pick one canonical definition and align both systems. + +Prevention. Centralize metric definitions (semantic layer, dbt model, shared SQL library). Audit all "the same metric" usages quarterly. + +--- + +## Pattern 13: Confounded test window + +Symptom. Test ran during a marketing campaign, a product launch, an outage, or a holiday. The result is reported without acknowledging the external event. + +Root cause. Random assignment usually handles external events (treatment and control are equally affected). But if the external event affects the metric definition (campaign brings different user mix), the populations stop being comparable. + +Fix. Stratify the analysis by the relevant covariate (acquisition source for campaigns, date for outages). If the stratified analysis differs meaningfully from the pooled analysis, report the stratified version and explain. + +Prevention. Maintain a calendar of marketing campaigns, product launches, and known external events. Avoid scheduling sensitive tests during these windows. If unavoidable, plan the stratification at design time. + +--- + +## Pattern 14: Long-tail metric overweighted by outliers + +Symptom. Revenue per user shows a large lift driven by a few high-value users. The lift is "significant" but unstable across re-samples. + +Root cause. Long-tailed distributions (revenue, session length, content engagement) have a few users contributing disproportionately. Random assignment of those users to treatment or control can drive large apparent effects that do not represent the underlying treatment effect. + +Fix. Winsorize the metric (cap extreme values at the 99th percentile, for example) and re-analyze. If the winsorized result is materially different from the raw result, the outliers were driving the effect. + +Prevention. Pre-commit to a winsorization threshold for long-tailed metrics. Apply the same threshold across treatment and control. Document the choice. + +--- + +## Pattern 15: Significance from sample size, not effect + +Symptom. "P equals 0.001, very significant." CI on the lift is [+0.1%, +0.3%]. Magnitude is tiny. + +Root cause. With enough sample, even tiny effects produce small p-values. Significance is not the same as magnitude. Shipping a 0.2% lift because "p was tiny" is a misuse of the framework. + +Fix. Read the CI alongside the p-value. If the practical lift is too small to matter, do not ship regardless of significance. + +Prevention. Pre-commit to an MDE (minimum detectable effect) as part of the design. If the observed lift is below the MDE, the test was overpowered and the result, while real, is not actionable. + +--- + +## Pattern 16: Overcorrection panic + +Symptom. Result shows a clean lift on the primary metric. Team adds five new metrics post-hoc and applies Bonferroni correction across all of them. Now the primary metric is "not significant." + +Root cause. Multiple testing corrections apply to pre-registered comparisons, not to post-hoc analyses meant to "stress-test" the result. Adding metrics after seeing the result and then correcting is statistically incoherent. + +Fix. Apply corrections only to the pre-registered comparison set. Post-hoc metrics are exploratory and should be reported as such, without claiming to update the primary inference. + +Prevention. Pre-register the metric set at design time. Treat any metric not on the list as exploratory. + +--- + +## The pattern behind the patterns + +Most of these failures share a common shape: the team had a hypothesis they wanted to confirm, the result was less clean than hoped, and the team applied an analytical knob (slice, switch methodology, drop outliers, reframe the guardrail, peek early) to make the result look cleaner. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. + +The defense against this pattern is pre-commitment. The defense against pre-commitment being weakened over time is documenting the pre-commitment somewhere immutable (PR description, signed Slack message, pinned ticket) and applying it mechanically when results come in. The pre-commitment is not the team's enemy; it is the team's protection from its own future motivated reasoning. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md b/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md new file mode 100644 index 0000000..1f3e1ec --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md @@ -0,0 +1,107 @@ +# Confidence interval cheatsheet + +The CI on the lift is the single most important number on the result panel. This cheatsheet covers what it means, what to ignore, and the five decision rules that map a CI to a ship, kill, or wait decision. + +--- + +## What the CI is + +A 95% confidence interval (CI) on a lift estimate is a range of values that, under repeated sampling of the experiment, would contain the true effect 95% of the time. The point estimate (the center) is your best single guess at the true effect. The width is your humility about how much you actually know. + +Three common CI shapes you will see on result panels: + +- Symmetric. Lift estimate +3% with CI [+1%, +5%]. The middle is the best guess; the bounds are equidistant. +- Skewed. Lift estimate +3% with CI [-0.5%, +8%]. Common with small samples or distributions with long tails. The point estimate is still the best guess; the asymmetry tells you the data is consistent with a wider range on the upside than the downside. +- Always-valid (sequential). Same shape as a normal CI but wider by design. Survives daily peeking. If your panel says "anytime-valid CI," that is what you are looking at. + +--- + +## What to read first + +Width before center. A narrow CI tells you a lot about the true effect; a wide CI tells you very little, regardless of where it is centered. A point estimate of +5% with CI [+4.5%, +5.5%] is a precise estimate of a real lift. A point estimate of +5% with CI [-3%, +13%] is essentially "we have no idea, somewhere between a meaningful loss and a huge win." + +The position of zero relative to the CI. If zero is well outside the CI on the positive side, you have a real positive effect. If zero is well outside on the negative side, you have a real harm. If zero is inside the CI, you cannot rule out "no effect." + +--- + +## What to ignore + +The point estimate alone. Without the CI, the point estimate is a single number with no honesty about how much it could move under different sampling. Reading "lift was +3%" without the CI is reading half the result. + +The p-value alone. P-values tell you about the strength of evidence against the null; CIs tell you about the magnitude of the effect. Both matter. A tiny lift with p equals 0.001 is technically significant and not worth shipping. A big lift with p equals 0.10 is technically inconclusive and worth a follow-up test. + +The "statistically significant" label as a binary. Most platforms color-code significance as a green check or a red X. The label is fine as a heuristic; the underlying CI is what you should defend the decision on. + +--- + +## The five decision rules + +### Rule 1: CI all-positive, lift above MDE. Ship. + +Example. MDE was 2%; CI is [+3%, +6%]. + +The lower bound of the CI exceeds the MDE you committed to detect. The data is inconsistent with no effect AND inconsistent with a trivial effect. Confidence is high, magnitude is meaningful. Ship. + +Confirm guardrails are clean before filing the launch. + +### Rule 2: CI all-positive, lift below MDE. Probably do not ship. + +Example. MDE was 5%; CI is [+0.5%, +1.2%]. + +The lift is real (CI excludes zero) but small (entire CI is below the MDE). The test was overpowered for the question, or the effect is smaller than expected. Real but tiny lifts are rarely worth shipping; the engineering, testing, and cognitive surface area exceeds the gain. + +The exception: changes that are essentially free to ship and maintain. A copy tweak with a +0.5% lift might be worth shipping; a feature requiring ongoing infrastructure with the same lift is not. + +### Rule 3: CI all-negative. Kill. + +Example. CI is [-4%, -1%]. + +The data is inconsistent with no effect and inconsistent with a positive effect. The change made things worse with high confidence. Kill the test. Document the lesson if the result is surprising; sometimes the lesson is "users wanted what we already had." + +### Rule 4: CI straddles zero, narrow. Real null result. + +Example. CI is [-0.5%, +0.8%]. + +Zero is inside the CI, but so is everything else within a small range. The data is consistent with no effect and inconsistent with any meaningful positive or negative effect. This is a real "we tested and it does not move the metric" result. Useful information; do not ship for "lift" reasons (you found none) but do not panic about harm either. + +The product question becomes: does the change have value beyond the metric we measured (brand consistency, code maintainability, accessibility)? If yes, ship for those reasons. If no, do not ship. + +### Rule 5: CI straddles zero, wide. Inconclusive. + +Example. CI is [-5%, +8%]. + +Zero is inside the CI and so is a wide range of meaningful effects in both directions. The data does not distinguish "moderate win" from "no effect" from "moderate loss." The test was underpowered for the question. + +Three follow-up paths: + +- Run longer or run bigger to narrow the CI. +- Make the treatment bolder so the expected effect is larger and detectable at the available traffic. +- Accept that the question cannot be answered cleanly and move on. + +The temptation is to ship anyway because "the point estimate was favorable." The point estimate is not evidence when the CI is this wide. Resist. + +--- + +## Pairing the CI with guardrails + +The CI on the primary metric is where the ship decision lives. The CI on each guardrail is where the safety check lives. Read both. + +A guardrail CI that excludes the threshold of concern is clean. For example, if retention is a guardrail and you require it to not drop more than 1%, a guardrail CI of [-0.3%, +0.4%] is clean. A CI of [-2%, +0.5%] is not clean even though it includes zero, because the lower bound exceeds the threshold. + +Wide guardrail CIs mean the test was underpowered for the guardrail. That is a real problem: you cannot claim safety on a metric you did not measure precisely. The fix is more sample, not "the point estimate looked fine." + +--- + +## Worked example: the "looks great" trap + +Setup. PM running a checkout redesign. Pre-committed primary: revenue per visitor. MDE: 3%. Guardrail: refund rate not increasing by more than 0.5%. + +Day 5. Result panel shows revenue per visitor +6%, p equals 0.03, CI [+0.5%, +11.5%]. Refund rate +0.3%, CI [-0.4%, +1.0%]. + +The temptation. Both metrics moved favorably; the headline is significant. PM proposes ending the test early. + +The CI read. Revenue CI [+0.5%, +11.5%] has a lower bound (+0.5%) below the MDE (+3%). The data is consistent with a real but tiny lift, not just the headline +6%. The guardrail CI [-0.4%, +1.0%] has an upper bound (+1.0%) that exceeds the threshold (+0.5%); the test cannot rule out a guardrail violation. + +The right call. Do not ship yet. Run to the pre-committed end date. Both CIs need to narrow before the ship case is defensible. The day-5 read is suggestive but not decisive; it is exactly the case the pre-commitment discipline was designed to handle. + +Common variant. PM ships anyway because "the trend is positive." Three weeks later the launch shows a refund rate increase that wipes out the revenue gain. The day-5 CI was warning of this exact possibility; the team did not read the width. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md b/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md new file mode 100644 index 0000000..072b959 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md @@ -0,0 +1,87 @@ +# Dashboard vs experiment reconciliation + +The scenario: the BI dashboard shows revenue grew 8% last week, the experiment platform shows the treatment lifted revenue 2%, and an executive asks how both can be true. This reference covers the common reasons numbers disagree, the blended-attribution trap, and how to communicate the difference. + +--- + +## Why numbers disagree (in order of frequency) + +Different denominators. The dashboard is computed across all users (or all sessions, or all transactions). The experiment is computed across enrolled users only. If 30% of users are enrolled in the experiment, the experiment lift applies to roughly 30% of the metric base; the dashboard sees the entire base. A 2% lift on the enrolled 30% looks like roughly 0.6% on the dashboard, even if everything is working perfectly. + +Different time windows. The dashboard shows rolling seven days; the experiment shows fixed start to end. Comparing a moving window to a fixed window is comparing two different summaries of overlapping but distinct data. + +External effects. Marketing campaigns, seasonality, news cycles, competitor moves, weather. The experiment correctly excludes these by random assignment (treatment and control see the same external effects, so they cancel in the lift estimate). The dashboard reflects them in full. The dashboard moving up has nothing to do with the experiment moving up. + +Selection effects in enrollment. Who is enrolled matters. New users only? Logged-in only? Users who passed a feature flag check? Each filter changes the population the experiment lift applies to, and changes how that population's behavior compares to the dashboard total. + +Different metric definitions. "Revenue" might be gross in the dashboard and net of refunds in the experiment. "Conversions" might count differently across systems (does a re-purchase count? a subscription renewal? a free trial activation?). Definitional drift between systems is common and almost always under-investigated. + +Pipeline lag. The dashboard is real-time or near-real-time. The experiment is computed on a daily batch with attribution windows that delay the metric by hours or days. Comparing a real-time number to a batched-and-attributed number is comparing two different versions of the truth. + +Different attribution models. First-touch vs last-touch vs multi-touch attribution can produce wildly different "revenue" numbers from the same underlying events. The dashboard and the experiment might use different models without anyone realizing. + +--- + +## The blended attribution trap + +The most common reconciliation failure: take the experiment lift and multiply by the total user base for company-wide impact. + +The wrong calculation. Experiment shows +2% revenue per user. Total active users: 5 million. "The feature drove $X million in incremental revenue." + +Why it is wrong, twice over. + +- The lift only applies to enrolled users, not the total base. If 30% of users are enrolled, the in-test impact is roughly 30% of what the multiplication suggests. +- Even within enrolled users, the lift was measured during the test conditions. Long-term and at full scale, the effect can be smaller (novelty fade, interference effects, market saturation) or sometimes larger (network effects that compound, learning effects). + +The right framing. "During the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control. Extrapolating to a full launch requires assumptions about how the effect translates at scale; the simple multiplication ignores those assumptions." + +The right framing is longer. Stakeholders sometimes push back on the precision. The precision is the point: the simple version is wrong, and shipping based on the simple version produces forecasts that do not materialize. + +--- + +## How to communicate to non-statistical stakeholders + +The temptation is to translate the experiment result into a single number that sounds like the dashboard. The translation is usually wrong because the two numbers are answering different questions. + +Better framings: + +- "The experiment is asking 'does this change move the metric for users who see it?' The dashboard is asking 'how is the metric trending overall?' Both can move independently and both can be true at the same time." +- "The experiment lift applies to enrolled users, in test conditions, during the test window. Translating to a launch forecast requires assumptions about scale, novelty, and interference." +- "If we ship to everyone, we expect the dashboard to move by roughly [X percent of the lift], plus or minus [a wide range], because of [specific assumptions]." + +Worse framings to avoid: + +- "The feature drove $X million in revenue this week." (Conflates the experiment lift with the dashboard movement.) +- "We hit our target." (When the target was set against the dashboard but the result is from the experiment.) +- "The lift was bigger in production than in the test." (Usually a sign of confounding, not vindication.) + +--- + +## When to dig into discrepancies vs accept them + +Dig in when: + +- The experiment shows a big effect and the dashboard shows nothing. The experiment is making a claim that the launch did not deliver. Either the experiment was wrong (selection effect, pipeline bug, confounder) or the launch is being measured wrong. +- The experiment shows nothing and the dashboard shows a big effect. The experiment is missing a real movement. Either the test was underpowered, the wrong population was enrolled, or the dashboard movement is from external factors. +- The directions disagree (experiment positive, dashboard negative). Almost always indicates a definitional drift or pipeline issue that needs investigation. + +Accept the discrepancy when: + +- The magnitudes are different but the directions agree. Usually a denominator or selection issue; document the explanation and move on. +- The dashboard is volatile and the experiment is stable. The dashboard reflects external noise the experiment correctly excludes. +- The dashboard is stable and the experiment showed a small effect. The launch effect is too small to detect in the dashboard's noise. + +--- + +## A reconciliation checklist for the moment of confusion + +When a stakeholder asks "why do these numbers not match?", run through this: + +1. Same metric definition? Confirm the experiment and dashboard are computing the metric the same way. Check the definitional doc for both. Ask the data team if there is no doc. +2. Same denominator? Confirm the experiment population and the dashboard population. Often they differ. +3. Same time window? Confirm the experiment window and the dashboard window are aligned (or explain why they are not). +4. Any external events? List campaigns, launches, outages, holidays during the test window. The dashboard reflects them; the experiment cancels them. +5. Any pipeline lag? Confirm both numbers are using the same attribution and the same data freshness. +6. Any selection effects? Who got enrolled and how? If enrollment was non-random (by feature flag check, by cohort), the experiment population is not representative of the dashboard population. + +If all six check out and the numbers still disagree by a meaningful amount, escalate to data engineering. There is probably a pipeline bug in one of the two systems. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md b/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md new file mode 100644 index 0000000..55e87f5 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/p-value-interpretation-guide.md @@ -0,0 +1,118 @@ +# P-value interpretation guide + +The p-value is the most-mentioned and most-misunderstood number on the result panel. This guide covers what it actually means, what people pretend it means, when the 0.05 cutoff binds and when it does not, and how to read p-values alongside the CI. + +--- + +## What the p-value is + +The p-value is the probability of observing the lift you saw (or one larger in magnitude), IF the true effect were zero. It is computed under the assumption that the treatment had no effect; the value tells you how surprised you should be by the observed data under that assumption. + +A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. A p-value of 0.001 means it would happen 0.1% of the time. Smaller p-values are stronger evidence against the null; larger p-values are weaker evidence. + +That is the whole technical definition. Everything else is interpretation, and most of it is wrong. + +--- + +## What the p-value is not + +These are the most common misinterpretations. Each one is wrong for a specific reason. + +"P equals 0.04 means 96% chance the treatment works." No. The p-value is computed under the assumption that the treatment does NOT work; it cannot tell you the probability that it does. The Bayesian probability of the alternative depends on the prior, which the p-value does not contain. + +"P equals 0.001 means the effect is huge." No. P-values are about the strength of evidence against the null, not the size of the effect. A tiny effect tested against a very large sample produces a tiny p-value. The CI tells you the size; the p-value tells you the certainty. + +"A significant result will replicate." Not necessarily. A p-value of 0.05 is associated with replication rates well below 50% in most published research. Statistical significance is one piece of evidence; reproducibility requires confirmation. + +"P greater than 0.05 means there is no effect." No. P-values cannot prove the null. A non-significant result means "we do not have enough evidence to reject no-effect," which is weaker than "no-effect is true." The CI tells you the practical conclusion: a wide CI straddling zero is "we do not know," while a narrow CI around zero is "the effect is small enough to call zero." + +"P equals 0.06 is much worse than p equals 0.04." No. The 0.05 cutoff is convention; the underlying evidence is roughly the same. Treating 0.06 as categorically different from 0.04 is theater unless you pre-committed to the cutoff. + +--- + +## The 0.05 convention + +Alpha equals 0.05 is the standard significance threshold by historical convention, not because the math says 0.05 is special. The convention is useful because it provides a shared reference point, and pre-committing to a threshold prevents post-hoc rationalization. + +Two valid uses of the threshold: + +- Pre-committed alpha. You declared at design time that you would ship if p was less than 0.05 and the CI excluded zero. Now apply the rule mechanically. If the result hit 0.04, follow the pre-commitment. +- Convention reference point. When communicating with stakeholders, "significant at the conventional 5% threshold" is a familiar phrasing. Use it as long as the underlying CI is also reported. + +Two invalid uses: + +- Post-hoc threshold games. Result is p equals 0.06; you decide that 0.10 is "good enough this time." This is p-hacking. +- Treating the threshold as a binary truth. Result is p equals 0.04; you ship without reading the CI. The threshold is necessary but not sufficient evidence to ship. + +--- + +## Always read the CI alongside the p-value + +The p-value tells you about the null hypothesis. The CI tells you about the magnitude. They answer different questions, and decisions need both answers. + +\| Scenario \| P-value \| CI on lift \| Decision \| +\|---\|---\|---\|---\| +\| Real, meaningful effect \| 0.001 \| [+3%, +6%] \| Ship if guardrails clean \| +\| Real but tiny effect \| 0.001 \| [+0.2%, +0.4%] \| Probably do not ship; magnitude too small \| +\| Suggestive but uncertain \| 0.08 \| [-0.5%, +12%] \| Inconclusive; run longer or kill \| +\| Inconclusive null \| 0.30 \| [-1%, +1%] \| Real null result; do not ship for lift reasons \| +\| Inconclusive wide \| 0.30 \| [-7%, +9%] \| Underpowered; not enough information \| + +Reading just the p-value loses the magnitude. Reading just the CI loses the certainty calibration. Both are routine on every result panel; both deserve attention. + +--- + +## The peeking problem + +Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. + +The math: at one analysis, alpha equals 5% means 5% false positive rate. At three analyses, it climbs toward 14%. At daily peeking on a four-week test, it can exceed 30%. The "significant" results you find by peeking are disproportionately false positives that will not replicate. + +Two fixes: + +- Sequential testing methods. Modern platforms (Statsig, Eppo, GrowthBook with mSPRT, parts of PostHog) report "always-valid" or "anytime-valid" p-values that survive peeking. The math is wider by design; the cost of peek-safety is some statistical efficiency. +- Pre-commitment. If your platform does not support sequential testing, declare the analysis date at launch and do not peek. If you must peek (some platforms make it hard not to), do not make decisions on intermediate peeks. + +If your panel says "p-value" without a qualifier, assume fixed-horizon. Treat early-peek results as suggestive only. + +--- + +## Multiple testing context + +A p-value of 0.05 means a 5% false positive rate per comparison. With twenty comparisons, you expect one false positive purely by chance. + +Where this matters: + +- Multiple variants (A vs B vs C vs D is three pairwise tests). +- Multiple metrics (primary plus six guardrails plus three secondary is ten chances). +- Multiple segments (ten segments times three metrics is thirty chances). + +Pre-register the primary metric and primary segment. Treat the rest as exploratory. A "significant" finding in a non-primary metric or non-primary segment requires either a larger effect, a follow-up test, or both before it justifies shipping. The discipline of pre-registration protects you from the multiple-testing trap better than any correction formula. + +When the platform applies a correction (Bonferroni, Benjamini-Hochberg) silently, the p-values you see have already been adjusted. Know which the platform applies by default; otherwise you may double-correct in your interpretation. + +--- + +## Bayesian alternatives + +Some platforms (Eppo by default, Statsig as a configuration option) report Bayesian probabilities rather than frequentist p-values. The vocabulary differs: + +- "Probability variant B is best": the Bayesian equivalent of multi-variant frequentist comparison. +- "Probability of beating control by at least X%": directly answers the magnitude question that frequentist p-values dance around. +- "Posterior credible interval": the Bayesian analogue of the confidence interval, with an interpretation closer to lay intuition ("there is a 95% chance the true effect is in this range"). + +For most PM contexts, both approaches produce similar ship decisions when the experiment was designed correctly. Pick one per experiment and stick with it. Switching mid-flight to chase a more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +--- + +## Communicating p-values to non-technical stakeholders + +Stakeholders often want a one-sentence summary. The temptation is "p equals 0.04, so we should ship." The temptation is wrong because it loses the magnitude. + +Better one-liners: + +- "We saw a 4% lift in revenue per visitor; the data rules out no-effect and is consistent with a 2% to 6% true lift." +- "The test was inconclusive: the lift could be anywhere from a small loss to a moderate win." +- "We measured a small but real effect: about 0.5% lift, which is statistically detectable but probably not worth shipping." + +Each names the magnitude, the uncertainty, and the decision implication. None reduces the question to a p-value threshold check. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md b/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md new file mode 100644 index 0000000..a89bd8e --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/result-presentation-templates.md @@ -0,0 +1,123 @@ +# Result presentation templates + +Five templates for stakeholder communication on experiment results. Each names the structure, the vocabulary, what to emphasize, and what to omit. Use the right template for the result you have, not the one that flatters the team. + +--- + +## Template 1: Clear win + +When to use. Primary metric moved past MDE, CI on lift excludes zero, all guardrails clean, pre-registered segments consistent. + +Structure. + +1. Headline. "We are shipping [feature]. The test showed a [X percent] lift in [primary metric] with [Y percent] confidence. Guardrails are clean." +2. The number. Point estimate of the lift, with the CI in parentheses. "Revenue per visitor lifted 4.2% (CI [+2.8%, +5.6%])." +3. Magnitude in business terms. "At our enrolled traffic, that is roughly [$Z] in incremental [period] revenue from this cohort. Full-launch impact depends on rollout assumptions." +4. Guardrails. One line per guardrail confirming it stayed within tolerance. +5. Decision and timing. "Filing the launch this week. Post-launch monitoring at days 7, 14, and 30." + +Vocabulary to use. "Real lift," "high confidence," "exceeds the threshold we committed to," "shipping." + +Vocabulary to avoid. Superlatives ("dramatic," "unprecedented," "transformative"). The number speaks; superlatives do not add to it. + +What to omit. Long discussion of why the test worked, deep statistical detail, exhaustive caveats. The headline result is clean; the writeup should be too. + +--- + +## Template 2: Clear loss + +When to use. Primary metric moved against expected direction with significance, OR a guardrail was violated. + +Structure. + +1. Headline. "We are not shipping [feature]. The test showed [a negative effect / a guardrail violation]." +2. The number. Point estimate and CI. Be precise about which metric showed the issue. +3. Likely cause, if known. Brief diagnosis: "Conversion dropped because users did not understand the new flow. Session recordings confirm confusion at step three." +4. What we learned. One or two sentences naming the lesson for the next hypothesis. +5. Decision and follow-up. "Killing the test. Filing the learning in the team retrospective. Considering [follow-up direction] as a next test." + +Vocabulary to use. "The test showed," "killing," "the change made things worse on [metric]," "we learned." + +Vocabulary to avoid. "Failed" applied to the team. "Setback." Defensive language. The test produced a clear answer; the team did its job. + +What to omit. Speculation about what would have happened with a different design. Excessive postmortem detail. The kill is the right decision; do not over-justify it. + +--- + +## Template 3: Inconclusive (the most common, hardest) + +When to use. Primary metric did not clearly move past MDE, CI is wide, OR guardrails are clean but signal is weak. The most frequent real outcome and the hardest to communicate without slipping into "we should ship anyway." + +Structure. + +1. Headline. "The test was inconclusive. We do not have enough signal to ship and we do not have enough signal to kill." +2. The number. Point estimate and the wide CI. Name the width: "Lift was +1.8%, but the CI is [-2.1%, +5.7%]; the data is consistent with a moderate win, no effect, or a moderate loss." +3. What we know vs what we do not. "We can rule out a large negative effect. We cannot distinguish a small positive effect from no effect. We cannot say whether shipping would help or hurt." +4. The three resolution paths. + + - Run bigger or longer: extend the test to narrow the CI. Cost: [time and traffic]. Benefit: a clearer answer. + - Make the treatment bolder: redesign with a larger expected effect, then re-test. Cost: design and engineering effort. Benefit: addresses the underlying mechanism rather than the measurement. + - Kill the idea: accept that the change does not produce a meaningfully detectable effect at our traffic. Cost: closing the hypothesis. Benefit: team time freed for higher-signal work. +5. Recommendation. Pick one path and explain why. +6. Decision. "Going with [path]. Re-evaluating in [timeframe]." + +Vocabulary to use. "Inconclusive," "the data does not distinguish," "we cannot confidently say," "the right call is to [chosen path]." + +Vocabulary to avoid. "Trending positive," "directional improvement," "looks promising." These are the phrases that get teams to ship inconclusive tests; they are wishful reading of noise. + +What to omit. Pleas to ship "since we are already here." Optimistic projections of what the lift "would be" with more sample. Alternative analyses that conveniently show significance. + +The hardest version of this template is the case where the team has invested in the hypothesis and the result is inconclusive. The temptation is to find a way to justify shipping. The discipline is to use the structure above and let the inconclusive result be inconclusive. + +--- + +## Template 4: Mixed result (positive primary, ambiguous guardrail) + +When to use. Primary metric moved past MDE with clean significance, but a guardrail metric showed concerning movement that did not clearly violate tolerance. + +Structure. + +1. Headline. "The primary metric moved as expected. A guardrail showed concerning movement; we are [shipping with monitoring / holding for further investigation]." +2. Primary metric result. Point estimate and CI. "Conversion lifted 5.1% (CI [+3.4%, +6.8%])." +3. Guardrail concern. Specific. "Refund rate point estimate moved +0.4%, with CI [-0.1%, +0.9%]. Pre-committed tolerance was no more than +0.5%. The CI does not clearly violate tolerance, but the upper bound is right at the threshold." +4. The interpretation question. "Pre-committed decision rule was 'do not ship if the guardrail CI excludes safe behavior.' The CI does not exclude safe behavior, but it does not exclude a violation either." +5. Recommendation with reasoning. Two valid paths: + + - Ship with extra monitoring: production behavior at +1, +2, +4 weeks specifically watching the guardrail. Roll back if it crosses tolerance in production. Acceptable when the primary lift is large and the guardrail risk is reversible. + - Hold and re-test: extend the test to narrow the guardrail CI. Acceptable when the primary lift is marginal or the guardrail is hard to monitor in production. +6. Decision. Pick the path. Document the guardrail-specific monitoring or the re-test plan. + +Vocabulary to use. "The guardrail CI does not clearly exclude tolerance," "shipping with intensified monitoring," "the pre-committed rule was." + +Vocabulary to avoid. "The guardrail did not move significantly" (when the CI does not exclude movement, do not pretend it did). "The primary lift outweighs the guardrail concern" (the guardrail was set as binding for a reason). + +What to omit. Reframing the guardrail as a "secondary metric" that does not need to bind. The guardrail was set during pre-commitment; it binds. + +--- + +## Template 5: Long-term holdout report (30 / 60 / 90 days post-launch) + +When to use. Reporting back on a feature that shipped with a holdout group, after the holdout period has elapsed. + +Structure. + +1. Headline. "[Feature] post-launch holdout report at [day count]. Long-term effect [confirms / diverges from / disconfirms] the test result." +2. Test result reminder. What the test showed at launch. "At launch, the test measured a +4% lift in [metric]." +3. Long-term result. What the holdout shows now. "At day 30, the launched cohort shows a +3.2% lift over the holdout (CI [+1.8%, +4.6%])." +4. Comparison. Direct: "The long-term effect is [in line with / smaller than / larger than] the test estimate. [If smaller: the difference is consistent with novelty fade / interference / dilution. If larger: the difference is consistent with network effects / learning effects.]" +5. Decision implications. "[Continue the launch as is / revisit the design / consider rollback]." +6. Holdout disposition. "[Releasing the holdout into the launched cohort / extending the holdout for another 30 days]." + +Vocabulary to use. "Long-term effect," "confirms / diverges from," "novelty fade," "we observe." + +Vocabulary to avoid. "Vindication" or "we were right." Long-term reports are about updating the prior, not declaring victory. + +What to omit. Excessive celebration of a confirmed lift. Excessive panic about a divergent lift. The report is information for the next decision; let the information drive it. + +--- + +## A note on the "we should report this differently" temptation + +When a result is inconclusive or mixed, there is always a way to slice the data, frame the writeup, or pick the chart that makes the result look more decisive. Resist. + +The cost of overstating an inconclusive result is shipping changes that do not work, eroding trust in the experimentation discipline, and accumulating production complexity for no gain. The cost of accurately reporting an inconclusive result is one round of disappointment from stakeholders who wanted a cleaner answer. The first cost compounds; the second does not. Use the right template for the actual result. diff --git a/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md b/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md new file mode 100644 index 0000000..bb11a4f --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-analytics/references/statistical-method-reference.md @@ -0,0 +1,150 @@ +# Statistical method reference + +The technical reference for analysts. Covers the methods named in the [SKILL.md](../SKILL.md) with enough depth to verify a platform's implementation, recognize when a method is needed, and explain the choice to a skeptical reviewer. + +--- + +## CUPED (Controlled-experiment Using Pre-Experiment Data) + +What it does. Uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. Same point estimate as the unadjusted analysis; narrower CI. + +The math, in one paragraph. For each user, take their in-experiment metric value Y and their pre-experiment metric value X. Compute the regression coefficient theta that relates X to Y in the control group. Replace Y with Y minus theta times (X minus X-bar) for every user. Run the analysis on the adjusted Y. The variance of the adjusted Y is lower than the variance of Y by a factor proportional to the squared correlation between X and Y, which directly narrows the CI. + +Variance reduction in practice. Typical reduction is 30% to 50% for engagement metrics, 20% to 40% for revenue metrics, near zero for one-time conversions. Effective sample size roughly doubles when variance halves. + +When to use. + +- Metrics with high pre-experiment baseline variance (revenue per user, sessions per user, engagement minutes). +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When NOT to use. + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline. +- Tests where pre-experiment behavior is uncorrelated with the metric being moved (a notification redesign rarely correlates with prior revenue, for example). + +How to verify your platform implements it correctly. Ask: "Do you compute theta on control only, or on the pooled population?" Pooled is technically wrong (induces bias). Control-only is correct. "What pre-experiment window do you use?" Common defaults are 14 to 28 days; the choice should be documented. + +Common confusion. "CUPED made our lift smaller, so we should report the unadjusted version." Wrong. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. + +--- + +## The delta method + +What it does. Provides correct variance estimation for ratio metrics. Naive variance estimation on ratios produces incorrectly narrow CIs and inflated false positive rates. + +Why ratios are special. Standard variance formulas assume sums of independent observations. Ratios are functions of two correlated sums (numerator and denominator). The variance of a ratio depends on the variance of the numerator, the variance of the denominator, AND the covariance between them. Naive estimators ignore the denominator variance and the covariance. + +The math, in one paragraph. For a ratio R equals N divided by D, the delta method approximates the variance of R using a first-order Taylor expansion around the means of N and D. The result expresses Var(R) as a function of Var(N), Var(D), Cov(N, D), and the means. The approximation is excellent when the sample size is moderate to large, which it is for almost any A/B test. + +When to use. + +- Conversion rate (conversions per user, when users can have multiple events). +- Click-through rate (clicks per impression). +- Revenue per user. +- Average order value. +- Any metric expressible as numerator divided by denominator where users can contribute multiple values. + +When the simple formula is fine. + +- Per-user binary conversion (one row per user, converted yes or no). The standard proportion variance formula is correct here. + +Bootstrap as an alternative. Resample users with replacement many times, compute the ratio each time, read off the empirical CI. Distribution-free; slower than delta method. Both produce similar CIs for typical A/B test sizes. + +How to verify your platform. Ask "what variance estimator do you use for ratio metrics?" Acceptable answers: delta method, linearization, bootstrap with user-level resampling. Unacceptable: standard t-test on proportions (wrong for non-binary ratios), bootstrap with row-level resampling (ignores within-user correlation). + +--- + +## Sequential testing methods + +The peeking problem. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Daily peeking on a four-week test can push false positive rate above 30%. + +Group sequential designs (GSD). Plan a fixed set of interim analyses (often three) with adjusted significance thresholds at each. The thresholds are computed so the overall false positive rate stays at the nominal alpha. Well-understood; less flexible than always-valid methods. + +Mixture sequential probability ratio test (mSPRT). Produces "always-valid" p-values: the false positive rate stays at nominal alpha regardless of how many times you analyze. Common in modern platforms. The math: define a likelihood ratio between the alternative and null hypotheses, integrated over a prior on the effect size. The test rejects when the ratio exceeds 1/alpha. + +Anytime-valid confidence intervals. The CI version of always-valid p-values. Produced by taking the inverse of the always-valid test family. Wider than fixed-horizon CIs; the cost of peek-safety is some statistical efficiency, typically 10% to 30% wider. + +Implementation across platforms. + +- Statsig: always-valid by default for sequential metrics. +- Eppo: sequential CIs available as a configuration. +- GrowthBook: mSPRT supported. +- PostHog: depends on the experiment type and configuration. +- Optimizely: supports sequential via Stats Engine. +- Amplitude (Experiment): supports sequential testing. + +How to read the panel. "Always-valid p-value" or "anytime-valid CI" labels indicate sequential. "P-value" with no qualifier is fixed-horizon; treat early peeks as suggestive only. + +--- + +## Heterogeneous treatment effects (HTE) + +What HTE is. The treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. + +Pre-registered vs post-hoc. Pre-registered HTE analysis is one of the segment definitions you committed to at design time, with sample size budgeted for the segment. Post-hoc HTE discovery is finding a segment whose effect is large by mining the data; this is noise mining and the apparent lift will not replicate. + +When to ship segment-only. Three conditions must all hold: + +- The segment was pre-registered. +- The effect within the segment is large enough to justify shipping. +- The targeting infrastructure exists (or is cheap to build) and the maintenance cost is acceptable. + +If any condition fails, do not ship segment-only. Either ship to everyone (taking the average effect) or do not ship. + +Methods for principled HTE detection. + +- Causal forests: machine learning method for estimating heterogeneous treatment effects across many features. +- Conditional average treatment effects (CATE) with regression: model the effect as a function of covariates. +- Pre-registered segment analysis: simpler, more defensible, and sufficient for most PM contexts. + +For most A/B tests, pre-registered segment analysis is the right level of sophistication. Causal forests are useful for marketplace and personalization research where the effect is genuinely expected to vary across many dimensions. + +--- + +## Multiple testing corrections + +The problem. With twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty, two or three. + +Bonferroni correction. Divide alpha by the number of comparisons. With 20 comparisons, use alpha equals 0.0025 per comparison. Conservative; controls the family-wise error rate (probability of any false positive across the family). + +Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (expected proportion of false positives among the things called significant). Better for exploratory analysis where some false positives are tolerable. + +When to use which. + +- Small number of pre-registered comparisons with high stakes: Bonferroni. +- Larger exploratory analysis where some false positives are acceptable: BH. +- Single pre-registered primary metric: no correction needed (one comparison). + +How platforms apply corrections. Some platforms apply corrections silently to displayed p-values; others report uncorrected numbers. Know which your platform does. The "5 of 12 metrics significant" headline means very different things depending on whether the p-values were corrected. + +--- + +## Cluster randomization + +When SUTVA is violated. SUTVA (Stable Unit Treatment Value Assumption) says one user's treatment does not affect another user's outcome. Violated in two-sided marketplaces, social products, supply-constrained features, and notification systems. + +Cluster randomization as a fix. Assign whole units (cities, markets, friend groups, sessions) to treatment or control rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. + +Trade-off. A cluster of 1000 users behaves more like one observation than 1000 independent observations. Effective sample size is roughly the number of clusters times the within-cluster correlation factor. Cluster randomization with 50 clusters has roughly the power of a user-randomized test with 200 to 500 users, even if the clusters contain millions of users total. + +Designing for cluster randomization. Choose the cluster boundary so that interference happens within clusters but not across them. Cities work for marketplace experiments. Friend groups work for social products. Sessions work for some notification studies. + +Switchback experiments as an alternative. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control). Eliminates cross-user interference within each window. Requires careful temporal modeling because the windows are not independent (carryover effects, day-of-week effects). + +Detection of SUTVA violation without redesign. Compare a small cluster-randomized version to the user-randomized version. If the cluster-randomized lift is much larger than the user-randomized lift, the user-randomized test is leaking treatment into control via interference. The user-randomized test is undercounting the effect. + +--- + +## Variance reduction beyond CUPED + +Stratified sampling. Pre-stratify users by a known covariate (geography, segment, signup cohort) and randomize within strata. Reduces variance from imbalanced randomization at the cost of slightly more complex analysis. + +Post-stratification. Run normal randomization, then adjust the analysis for known covariates after the fact. Similar variance reduction to CUPED for the right covariates. + +Regression adjustment. Include covariates as controls in the regression that estimates the treatment effect. Equivalent to post-stratification for one covariate; generalizes to multiple. + +Doubly robust estimation. Combines regression adjustment with inverse-probability weighting. Robust to misspecification of either the outcome model or the propensity model. Overkill for most A/B tests; useful for observational analysis and some quasi-experiments. + +For most PM contexts, CUPED plus pre-registered segment analysis covers the variance reduction needs. The methods above are the next step up when the standard tools are insufficient. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md new file mode 100644 index 0000000..ea765c9 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/SKILL.md @@ -0,0 +1,286 @@ +--- +name: experimentation-platform-orchestrator +description: "A platform decision framework for experimentation. When to use Statsig vs PostHog vs GrowthBook vs Optimizely vs Amplitude vs Eppo vs Kameleoon. How to migrate between them. How to coordinate when multi-platform is genuinely warranted. The decisions that compound for years and the ones you can defer. Triggers on which experimentation platform, choose Statsig vs PostHog, evaluate experimentation tools, switch experimentation platform, migrate from Optimizely, consolidate experimentation tools, multi-platform experimentation, experimentation platform decision, ab test platform selection, feature flag platform vs experiment platform, warehouse-native experiments, vendor lock-in experimentation. Also triggers when a team is asking about cost, governance, or migration cost across experimentation tools, or when an evaluation is starting." +category: product +catalog_summary: "Pick the right experimentation platform, migrate when wrong, coordinate when multi-platform: a decision framework for Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon" +display_order: 7 +--- + +# Experimentation Platform Orchestrator + +A senior product and engineering leader's playbook for making the experimentation platform decision and recovering from making it wrong. + +Picking an experimentation platform is one of those decisions that looks easy at the start and compounds for years afterward. The wrong choice costs you in lost experiments (because the team avoids the painful workflow), in cost (because the wrong pricing model penalizes your usage shape), in vendor lock-in (because migration is real engineering work, not a config change), and in cultural drift (because the platform's defaults shape what your team thinks experimentation is). + +This skill is the discipline that makes the decision well the first time and the migration plan when you didn't. + +When to use this skill: choosing a platform from scratch, evaluating whether to switch, deciding whether to consolidate from multi-platform to single, or planning a migration that has already been approved. + +--- + +## What this skill is for + +This skill spans platform selection, multi-platform decisions, migration planning, and governance setup. It does not cover experiment design (use `experiment-design`), result interpretation (use `experimentation-analytics`), or feature flag operations (use `feature-flagging`). Pair this skill with the relevant integrations microsite when you need platform-specific MCP details. + +The audience is a PM, engineering leader, or data lead who is making the decision or recovering from a previous one. The voice is decisive. There is no "it depends, evaluate them all yourself." The decision space has real shape, and a senior advisor can map your situation to a defensible answer in an afternoon. + +--- + +## The 7 considerations for the platform decision + +Every platform evaluation walks the same seven questions. Answer them honestly first, then read the per-platform profiles, then consult the decision matrix. The order matters: data architecture and statistical rigor are foundational; the rest are layered on top. + +1. Data architecture. Where does experiment data live? Three patterns. Vendor-native (Statsig, Optimizely) keeps the data in the vendor's storage. Product-suite (PostHog, Amplitude) combines analytics and experiments behind one event pipeline. Warehouse-native (GrowthBook, Eppo) runs SQL on your existing data warehouse. The pattern dictates security review depth, residency, statistical depth, and cost shape. + +2. Statistical rigor. Does the platform implement CUPED, sequential testing, the delta method for ratio metrics, and multiple testing corrections? Cheap to verify in a sales call: ask "what variance estimator do you use for ratio metrics?" and "do you support always-valid p-values?" Modern platforms (Statsig, Eppo, parts of PostHog) have these. Older or homegrown platforms often do not. + +3. MCP availability. All seven platforms covered here have a first-party or hosted MCP except Eppo (as of May 2026). MCP availability matters more for agentic workflows where AI agents create and read experiments end to end. It matters less for traditional human-driven experimentation. Worth weighting if your team is AI-forward. + +4. Feature flag integration. Do experiments and feature flags live in the same platform? Statsig, Optimizely, GrowthBook, and PostHog all unify them. Eppo is experiment-only. Kameleoon is creative-personalization-focused. If you also need feature flag operations as production infrastructure, check `feature-flagging` for the operational discipline; the platform choice has to support both surfaces or you accept a second tool. + +5. Analytics depth. Can you see funnels, retention, and cohorts in the same surface as experiment results? PostHog and Amplitude are strongest here (analytics-first products). Statsig has a strong analytics overlay. Optimizely and GrowthBook are experiment-first, with analytics as a supplementary feature. + +6. Governance and audit. Who can change targeting in production, who can ship experiments, who can read sensitive metrics? Enterprise tiers (Optimizely, LaunchDarkly Federal) handle this with maturity. Open-source platforms (GrowthBook, PostHog self-hosted) require self-built governance. For regulated industries (healthcare, finance, public sector), this question is the deciding factor. + +7. Cost shape. Vendor-native scales with events. Warehouse-native scales with seats and warehouse compute. Product-suite scales with combined event volume across all features. Match the pricing shape to your actual usage shape. A high-traffic startup pays vendor-native pricing differently from a lower-traffic enterprise; pick the shape that is friendly to your trajectory, not just your current month. + +--- + +## Statsig + +Modern experimentation and feature management combined in one platform. CUPED and sequential testing built in. Strong PM-led ergonomics. Used by OpenAI, Notion, Brex, Figma. + +Strengths. Fast time to first experiment. Combined experiments and feature flags eliminate the second-tool tax. Statistical rigor is current with the literature. The MCP exposes full CRUD across experiments, gates, dynamic configs, and metrics. + +Gotchas. Pricing scales with events, which can become expensive at high scale. The platform has strong opinions about how experiments should run; teams that want a custom statistical workflow will fight the defaults. Self-host is not a first-class option. + +Ideal customer. Fast-growing SaaS that wants one platform for flags and experiments, values out-of-the-box statistical depth, and is comfortable with vendor-native data architecture. + +--- + +## PostHog + +Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics. Free tier available. + +Strengths. Full-funnel context. Experiments live next to the analytics that contextualize them. The MCP exposes 200+ tools (use scoping like `?features=` to keep the agent context tight). Self-host option is mature. Open-source license keeps you outside the vendor lock-in trap. + +Gotchas. Combined event volume across all features can make pricing surprising at scale. The breadth of features can make onboarding feel busy. Statistical depth in experiments is good but a step behind dedicated experiment platforms (Statsig, Eppo) on advanced features like CUPED defaults. + +Ideal customer. Product-led-growth SaaS that wants analytics, experiments, and feature flags in one surface, values open-source flexibility, and is comfortable with the breadth. + +--- + +## GrowthBook + +Open-source warehouse-native experimentation. Data stays in your warehouse (Snowflake, BigQuery, Redshift, Postgres). Self-host or cloud. + +Strengths. Data sovereignty. Cost control at scale because the warehouse is already paid for. First open-source production MCP for experimentation per their announcement. Mature statistical defaults including Bayesian and frequentist toggles. Bring-your-own metrics from the warehouse means experiment metrics match analytics metrics by definition. + +Gotchas. Setup overhead is higher than vendor-native. You own the warehouse compute cost (this is usually a feature, not a bug, but it shows up in different finance line items). Smaller community than Statsig or PostHog. UI polish lags vendor platforms by half a step. + +Ideal customer. Data-mature teams that already run a warehouse, regulated industries that need data residency, and teams that prefer open-source for the exit option. + +--- + +## Optimizely + +Long-time enterprise leader. Web Experimentation plus Feature Experimentation. Strong personalization and visual editing for non-technical users. + +Strengths. Enterprise governance is mature. Visual editing lets marketers ship experiments without engineer help. Strong customer success organization. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai. + +Gotchas. Expensive. Pricing targets marketing budgets, not engineering budgets. The product has decades of accumulated features; navigating it takes time. Statistical defaults are conservative but the platform is not the place to look for the latest variance reduction techniques. + +Ideal customer. Marketing-led organizations, enterprises with mature experimentation programs, and teams where non-technical experiment creation is a hard requirement. + +--- + +## Amplitude + +Behavioral analytics platform with experiments and feature flags as additional features. Hosted MCP available to all customers including the free tier. + +Strengths. If your team already lives in Amplitude for analytics, adding experiments is the path of least resistance. Cohort and behavioral segmentation are excellent. Free tier (10M events/month) is generous. + +Gotchas. Experiments are a secondary feature, not the headline. Statistical depth is moderate. If experimentation is your team's primary discipline, Amplitude is rarely the right choice; if experimentation is a supporting capability and analytics is the headline, it works. + +Ideal customer. Analytics-first teams that need experiments as a supplementary capability, not the centerpiece. Pre-PMF teams that want a free tier with analytics and experiments together. + +--- + +## Eppo + +Warehouse-native, statistically rigorous, used by Twitch, DraftKings, Perplexity. Strong statistical defaults including Bayesian and frequentist toggles, sequential testing, and CUPED. + +Strengths. Statistical correctness is the headline. The team is heavy on data scientists and statisticians, and it shows in the defaults. Warehouse-native architecture matches the pattern data-mature teams already run. Reporting is clear and oriented to decisions. + +Gotchas. No first-party MCP as of May 2026. REST API only. If your workflow depends on AI agents reading and writing experiments, Eppo is currently a gap. Track for a future MCP release. Pricing is enterprise; no meaningful free tier. + +Ideal customer. Data-team-led organizations where statistical correctness is paramount, the warehouse is already the system of record, and AI agent workflows are a future concern rather than a current requirement. + +--- + +## Kameleoon + +Specialty platform focused on the winning-experiment-to-production-code workflow. AI-driven personalization. Hosted MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. + +Strengths. Converts marketing-site experiment wins into permanent React components, which is a real workflow that other platforms force teams to handle manually. AI-driven personalization for content sites. The MCP is purpose-built for the win-to-code path. + +Gotchas. Narrower than the others. Not a replacement for Statsig or Optimizely on product experiments. Often shows up alongside another platform rather than as the primary. + +Ideal customer. Teams running experiments on marketing or content sites that need the winning variant to become permanent code. Almost always layered with a primary product-experiment platform. + +--- + +## Decision matrix: which platform for which context + +The matrix lives in [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) with worked examples. The summary: + +- Pure SaaS, fast-growing, want one platform for flags and experiments. Choose Statsig. Choose PostHog if you also want analytics. +- Open-source preference, want data sovereignty, warehouse-native. Choose GrowthBook or Eppo. +- Enterprise, marketing-led, deep personalization. Choose Optimizely. +- Already deeply on Amplitude for analytics. Stay on Amplitude unless statistical depth becomes the bottleneck. +- Data-team-led, statistical correctness paramount, MCP not yet required. Choose Eppo. +- Need to convert marketing-site wins into production code. Add Kameleoon alongside your primary platform. +- Regulated industry (HIPAA, FedRAMP), self-hosting required. Choose GrowthBook self-hosted. PostHog self-hosted is also viable. +- Pre-PMF startup, low traffic, need a free tier. Use PostHog free tier or Statsig free tier; defer the real decision until traffic justifies the cost calculation. +- 100M+ events per month, cost control is the headline constraint. Choose GrowthBook or Eppo. Warehouse-native pricing scales better at this volume. +- AI-forward team, MCP-first workflow. Choose Statsig, PostHog, or Optimizely. Defer Eppo until its MCP ships. + +--- + +## Multi-platform: when warranted, when a mess + +Multi-platform is warranted when the surfaces are genuinely different and the platforms overlap zero. Marketing site personalization on Kameleoon plus product experiments on Statsig is a clean split: different surface, different audience, different metric set, no overlap. The cost of the second tool is justified because the workflows do not collide. + +Multi-platform is a mess when the surfaces overlap. Running both Statsig and Optimizely for product experiments creates duplicate cost, split data, and a "which one is the source of truth" problem that surfaces in the worst possible moment, which is when a leadership disagreement needs an answer. + +The 80/20 rule. Eighty percent of teams should pick one platform and consolidate. The 20% with genuine multi-surface needs (marketing site plus product app plus content site) can justify multi-platform with clear ownership boundaries. + +When multi-platform is genuine, three coordination patterns are non-negotiable. An ownership matrix names which platform owns which surface. Shared metric definitions ensure that "activation rate" computes the same way in both platforms (this is hard, and it is the reason most multi-platform setups quietly drift). Reconcilable dashboards let you see the same metric across both platforms with the same definitions. Detail in [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md). + +--- + +## Migration patterns + +Migration is the unglamorous engineering work that makes the platform decision recoverable. Five common paths. + +Statsig to PostHog. Typical when a company outgrows pure experimentation and wants analytics plus experiments combined. Effort: 3 to 5 engineer-weeks. Parallel-run for 4 to 8 weeks, validate experiments produce the same results on both, cut over once trust is established. + +Optimizely to Statsig. Typical under budget pressure or modernization. Effort: 4 to 8 engineer-weeks. Audit for feature parity first (Optimizely has personalization features Statsig does not). Migrate experiments before flags. Retire Optimizely only after all in-flight experiments complete on the old platform. + +PostHog to Eppo. Typical when statistical rigor becomes the binding constraint and the warehouse is already the system of record. Effort: 6 to 10 engineer-weeks. Often results in PostHog staying for analytics and Eppo running experiments. Plan for the dual-platform end state, not a clean replacement. + +GrowthBook to Eppo. Typical when commercial support and deeper statistical features become worth the price. Effort: 2 to 4 engineer-weeks because both are warehouse-native; the data already lives in your stack. + +Any to Statsig. Typical consolidation move from multi-platform mess. Effort scales with the number of platforms and in-flight experiments; a clean consolidation can run 6 to 12 engineer-weeks. + +The migration discipline is in [`references/migration-playbook.md`](references/migration-playbook.md). Three rules apply to every migration: do not parallel-run forever, do not big-bang switch, and do not retire the old platform before all in-flight experiments complete. + +--- + +## The cost reality + +Plain talk. Vendor-native (Statsig, Optimizely) bills on events, typically $0.10 to $0.50 per million events. Easy to predict at small scale, painful at very high scale. Warehouse-native (Eppo, GrowthBook paid) bills on seats and warehouse compute; $5K to $50K per year is the typical range for paid tiers, with warehouse compute showing up on a different finance line. Product-suite (PostHog, Amplitude) bills on combined event volume across all features; often the most cost-effective when used heavily and the most expensive when only experiments are needed. + +Free tiers. PostHog gives 1M events per month free. Statsig gives 1M events free. Amplitude gives 10M events per month free with basic features. GrowthBook is free open-source. Optimizely and Eppo do not have meaningful free tiers. + +The trap. Optimizing for sticker price ignores total cost. Total cost includes engineer time, statistical correctness (a wrong-result experiment can cost more than a year of platform fees), governance overhead, and migration risk. Sticker price matters for finance; total cost matters for product velocity. Detail and finance conversation patterns in [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md). + +--- + +## Governance and team fit + +Permission tiers, approval workflows, audit trails, and environment promotion are the four pillars of governance. Who creates experiments, who modifies targeting in production, who reads sensitive metrics, who approves a rollout. Enterprise tiers handle these out of the box. Open-source self-hosted requires you to build them, which is fine if you have the engineering capacity and a dealbreaker if you do not. + +Team fit shapes the decision more than most evaluations admit. PostHog and GrowthBook suit engineer-led and PLG teams. Optimizely suits marketing-led teams. Eppo and GrowthBook suit data-team-led teams. Statsig suits PM-led teams. The platform's defaults will pull your team's experimentation culture in the direction of its primary user; pick the alignment that matches who you actually want running experiments. + +Onboarding cost. How long until a new PM can ship their first experiment? Statsig and PostHog: hours to days. Optimizely: days to weeks. Eppo and GrowthBook: depends on whether the warehouse and metrics are already wired in (days if yes, weeks if no). Detail in [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md). + +--- + +## The MCP capability layer + +For AI-forward teams, the MCP capability layer is becoming the deciding factor. The current state as of May 2026: + +- All seven covered platforms have first-party or hosted MCPs, with the exception of Eppo. Eppo offers REST API only. +- Capability differs by an order of magnitude. PostHog exposes 200+ tools; Kameleoon exposes 7. More is not better; the right size depends on your workflow. +- For agentic workflows where AI agents run experiments end to end, prefer platforms with full CRUD via MCP: Statsig, PostHog, GrowthBook, Optimizely. +- For human-driven workflows where MCP supplements human action, any of the seven works (Eppo via the REST path). + +MCP availability is evolving fast. Check the current state of any platform before committing. Eppo is worth tracking for a future MCP release that would close its current gap. Side-by-side capability matrix in [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md). + +--- + +## When to defer the decision + +Sometimes the right answer is "not now." Four cases. + +Pre-PMF. Experimentation infrastructure is premature. Use a free tier (PostHog or Statsig) to remove blockers, defer the real decision until you have enough traffic to make any platform meaningful. + +Single-experiment validation. Do not pick a platform for one experiment. Use whatever is free and easy. The platform decision is for the team that runs experiments as a discipline, not the team running its first. + +No experimentation culture yet. Tooling does not fix culture. If your team is not running experiments, picking a fancy platform will not change that. Build the culture first; the platform decision becomes obvious once experiments are flowing. + +Pending acquisition or major pivot. Defer until the dust settles. The acquirer will likely have a preferred platform anyway. + +--- + +## Common mistakes + +Twelve patterns recur across platform decisions. The short version: + +- Picked the cheapest. Total cost dominates sticker price. +- Picked the most-featured. Features you do not use are technical debt. +- Tried multi-platform first. Almost always becomes a consolidation project later. +- Outgrew the platform but stayed for migration cost. The platform tax compounds; migration cost is fixed. +- Picked based on a demo. Demos optimize for the show; real usage reveals real tradeoffs. +- Did not check governance. Discovered after rollout that anyone can modify production targeting. +- Picked a platform that does not fit team type. PM-led team on a marketing-led platform is constant friction. +- Underestimated the warehouse setup. Warehouse-native platforms expect the warehouse to already be there. +- Skipped statistical depth review. Then a critical experiment surfaced a wrong-result decision. +- Ignored MCP trajectory. Picked a platform without MCP for an AI-forward team. +- Locked the brief on the demo, not the trial. Brief assumptions did not survive contact with real usage. +- Renewed without re-evaluating. The market changed; the brief did not. + +Detail in [`references/common-mistakes.md`](references/common-mistakes.md) with symptoms, root causes, fixes, and prevention. + +--- + +## The framework: 11 considerations for sustainable platform choice + +When choosing or evaluating an experimentation platform, walk these 11 considerations. Answer each one before reaching a recommendation. Skipping any of them is how teams end up in a migration project a year later. + +1. Data architecture. Vendor-native, product-suite, or warehouse-native. The pattern is downstream of every other decision. +2. Statistical rigor. CUPED, sequential testing, delta method for ratio metrics, multiple testing corrections. Verify at the sales-call level; do not assume. +3. MCP availability. Current capability and trajectory. Weight higher if your team is AI-forward. +4. Feature flag integration. Same platform or separate. Decide once and live with the implications. +5. Analytics depth. Funnels, retention, cohorts in the same surface. Decides whether you need a second tool for the analytics layer. +6. Governance. Permissions, audit, approval workflows, environment promotion. Non-negotiable for regulated industries. +7. Cost shape. Events vs seats vs warehouse compute. Match the shape to your usage trajectory. +8. Team fit. PM-led, engineer-led, data-led, marketing-led. The platform's defaults will pull your culture in the direction of its primary user. +9. Onboarding cost. Time to first experiment for a new team member. Faster is better; varies wildly across platforms. +10. Migration cost. What is the exit plan if you choose wrong. Higher migration cost means higher confidence required at decision time. +11. Multi-platform fit. Does this layer cleanly with platforms you already have, or does it create overlap. + +The output of this framework is one of three answers. A primary recommendation with reasoning. A short list of two if the situation is genuinely ambiguous. A "defer" if a precondition is not met (no traffic, no culture, pending pivot). + +--- + +## Reference files + +- [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) - Context-to-platform matrix with worked examples for the most common decision contexts. +- [`references/migration-playbook.md`](references/migration-playbook.md) - Step-by-step migration patterns for the five common migrations including effort estimates and validation approaches. +- [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md) - Side-by-side MCP capability matrix across the seven platforms. +- [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md) - Ownership boundaries, shared metric definitions, and reconciliation dashboards for genuine multi-platform setups. +- [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md) - Pricing shapes, real-world cost ranges at different traffic tiers, and finance conversation patterns. +- [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md) - Permission tiers, audit trail requirements, environment promotion rules, and team fit assessment. +- [`references/common-mistakes.md`](references/common-mistakes.md) - Twelve failure patterns with symptom, root cause, fix, and prevention for each. + +--- + +## Closing: when in doubt, pick boring + +When the analysis is genuinely ambiguous, pick the boring choice. Boring means mature, well-documented, large user base, and a recoverable migration if you turn out to be wrong. Statsig is boring for SaaS. PostHog is boring for product-led growth. Optimizely is boring for enterprise. GrowthBook is boring for warehouse-native. + +Boring is not the optimum, but it is almost never wrong. The optimum can come later, when the situation has clarified and the team has the experience to know what it actually needs. The cost of picking boring is a small efficiency tax. The cost of picking exotic and being wrong is a migration project that interrupts a year of product work. + +If the team disagrees on which boring choice is the right one, that is a data signal: the situation is not yet clear enough for any answer to be obviously correct. Run a 30-day trial on the top two, evaluate against the 11-consideration framework with real usage data, and pick. Do not skip the trial; demos lie about real usage in ways that only the trial reveals. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md new file mode 100644 index 0000000..bbf1200 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/common-mistakes.md @@ -0,0 +1,155 @@ +# Common mistakes + +Twelve failure patterns that recur in platform decisions. For each: name, symptom, root cause, fix, and prevention. + +--- + +## 1. Picked the cheapest + +Symptom. Six months in, the team is paying more in engineer time than they saved on the platform fee. Velocity is below the pre-decision projection. + +Root cause. Sticker-price optimization without a total-cost frame. Engineer time, statistical correctness, and migration risk were not priced in. + +Fix. Run a total-cost-of-ownership review. If TCO is materially worse, plan a migration to a better-fit platform. Counter-intuitively, paying more in platform fees can save more in engineer time. + +Prevention. Use the total cost frame at decision time. The cheapest sticker price is rarely the cheapest TCO. See `cost-and-pricing-models.md` for the framing. + +--- + +## 2. Picked the most-featured + +Symptom. The team uses 20% of the platform's features. The other 80% are noise that complicates onboarding and inflates the bill. + +Root cause. Demo-driven feature comparison. The platform's depth was impressive in the demo and translated into a "more features means more value" assumption. + +Fix. Audit feature usage. If 80% of the platform is unused, evaluate whether a simpler platform serves the team better. Migrating to a smaller-surface platform reduces operational complexity. + +Prevention. Build a "features needed" list before evaluating platforms. Use the list to filter out features you do not need; do not let demo-time enthusiasm expand it. + +--- + +## 3. Tried multi-platform first + +Symptom. Two platforms running, both partially used, neither fully embraced. Stakeholders cannot tell which one is the source of truth. + +Root cause. "Best of both worlds" thinking. The team picked two platforms hoping to combine their strengths, but the integration cost exceeded the combined benefit. + +Fix. Plan a consolidation. See `multi-platform-orchestration.md` for when consolidation is the right answer (almost always for teams in this state). + +Prevention. Default to single-platform unless the surfaces genuinely do not overlap. Multi-platform is a 20% case, not the default. + +--- + +## 4. Outgrew the platform but stayed for migration cost + +Symptom. The team is hitting limits the platform cannot serve (statistical depth, governance, scale). They know it. They have not migrated because the migration project feels expensive. + +Root cause. Migration cost is overweighted relative to the ongoing platform tax. The platform tax compounds; migration cost is fixed. + +Fix. Run the migration. Set a 90-day window. Use the migration playbook. + +Prevention. Do an annual platform fit review. If the platform is not the right fit, the answer is to migrate, not to defer. Deferral makes the migration harder, not easier. + +--- + +## 5. Picked based on a demo + +Symptom. Real usage reveals workflows that did not show up in the demo. Team velocity is below expectations. Frustration is mounting. + +Root cause. Demos optimize for the show. Real usage reveals real tradeoffs. The decision was made before the team had data on actual workflows. + +Fix. Run a 30-day trial on the next-best alternative. Compare real-usage friction. If the alternative is materially better, plan the migration. + +Prevention. Always run a real trial, never just a demo. The trial should ship at least one experiment end to end on each platform under evaluation. + +--- + +## 6. Did not check governance + +Symptom. Discovered after rollout that anyone with platform access can modify production targeting. A bad change shipped because no review was required. + +Root cause. Governance was not part of the evaluation. The team assumed defaults would be acceptable; they were not. + +Fix. Build the governance layer immediately. Permission tiers, approval workflows, audit trails, environment promotion. See `governance-and-team-setup.md`. + +Prevention. Make governance a non-negotiable evaluation criterion. For any platform under consideration, document the permission model, audit capabilities, and approval workflow before signing. + +--- + +## 7. Picked a platform that does not fit team type + +Symptom. Constant friction in experiment authoring. The team that should be shipping experiments is instead filing tickets. Experiment volume is below target. + +Root cause. Team-fit mismatch. A PM-led team on a marketing-led platform, or vice versa. The platform's defaults pull the workflow in a direction the team cannot follow. + +Fix. Either change the team's workflow to match the platform, or migrate to a platform that matches the team. The migration is usually the right answer because team workflow is hard to change quickly. + +Prevention. Assess team fit explicitly. See the team-fit framework in `governance-and-team-setup.md`. + +--- + +## 8. Underestimated the warehouse setup + +Symptom. Picked a warehouse-native platform. Three months in, still not running experiments because the warehouse layer is not ready. + +Root cause. Warehouse-native platforms expect the warehouse to already be the system of record with metrics defined and refresh cadences in place. The team did not have that foundation. + +Fix. Either complete the warehouse setup (real engineering project) or migrate to a vendor-native platform that does not require it. + +Prevention. Verify warehouse readiness before committing to warehouse-native. The platform decision should follow the warehouse decision, not lead it. + +--- + +## 9. Skipped statistical depth review + +Symptom. A critical experiment surfaced a wrong-result decision. The platform's defaults did not catch the issue (peeking, ratio metric, multiple testing, network effects). + +Root cause. Statistical depth was not part of the evaluation. The team assumed all platforms compute the same numbers correctly; they do not. + +Fix. Add the missing rigor. Either configure the current platform's advanced features (sequential testing, CUPED, delta method) or migrate to a platform with stronger defaults. Pair with the `experimentation-analytics` skill to interpret results going forward. + +Prevention. Verify statistical depth at evaluation time. Ask specifically about CUPED, sequential testing, delta method for ratio metrics, and multiple testing corrections. Do not accept "we have statistical features" without specifics. + +--- + +## 10. Ignored MCP trajectory + +Symptom. AI-forward team picked a platform without MCP. Six months later, the team is hitting the limit of agent-driven workflows and the platform is the bottleneck. + +Root cause. MCP trajectory was not weighted in the decision. The platform's strengths in other areas were assumed to make up for the gap. + +Fix. Either wait for the platform to ship an MCP (uncertain timeline) or migrate to a platform with mature MCP. Eppo specifically is worth tracking for a future MCP release. + +Prevention. For AI-forward teams, MCP availability is a primary criterion, not a tiebreaker. See `mcp-capability-comparison.md` for current state. + +--- + +## 11. Locked the brief on the demo, not the trial + +Symptom. Brief-time assumptions did not survive contact with real usage. The platform is technically capable but operationally uncomfortable in ways the demo did not reveal. + +Root cause. The decision was made on the strength of the demo, with the trial running as a formality afterward. Real-usage signals were not weighted. + +Fix. Do another trial of the next-best alternative. If the alternative removes the operational discomfort, migrate. + +Prevention. Run the trial first. Use trial outcomes to update the brief, not the other way around. Demos are useful for screening; trials are required for committing. + +--- + +## 12. Renewed without re-evaluating + +Symptom. Renewal cycle came up. The team renewed because the platform was working "well enough." Six months later, an alternative shipped a feature that would have changed the decision. + +Root cause. Renewal treated as a status-quo extension. The platform market changes faster than annual contracts, and a yearly renewal without re-evaluation drifts away from the optimal choice. + +Fix. Run the platform decision framework at every renewal. If the answer is the same platform, renew with confidence. If the answer is different, plan a migration. + +Prevention. Build the annual platform review into the team's calendar. Tie it to the renewal date so the review informs the renewal decision rather than competing with it. + +--- + +## The pattern across all twelve + +Most platform mistakes share one root cause: under-investment in the decision itself. A two-week evaluation that catches all twelve patterns is cheaper than a year on the wrong platform. + +The fix at the meta level. Treat the platform decision as a real engineering project. Allocate time. Run trials. Audit governance. Verify statistical depth. Check MCP trajectory. Document the decision and the reasoning. Review annually. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md new file mode 100644 index 0000000..146f835 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md @@ -0,0 +1,125 @@ +# Cost and pricing models + +Pricing shapes per platform, real-world cost ranges at different traffic tiers, the total cost frame, and finance conversation patterns. + +Pricing on experimentation platforms is rarely transparent on the public site for paid tiers. The numbers below are typical ranges from real customer conversations as of May 2026. Verify with each vendor before committing. + +--- + +## The three pricing shapes + +Vendor-native (event-based). Statsig, Optimizely. Billing scales with the number of events sent to the platform. Easy to predict at small scale: events per month times rate per million. Painful at very high scale because the rate per million does not always decrease quickly. + +Warehouse-native (seat plus warehouse compute). GrowthBook (paid), Eppo. Billing scales with the number of seats and the warehouse compute the platform consumes. Warehouse compute is your existing line item, so the marginal cost of more experiments is small once the platform is paid for. Less elastic on team size, more elastic on experiment volume. + +Product-suite (combined event volume). PostHog, Amplitude. Billing scales with combined event volume across all features (analytics, experiments, replays, error tracking, surveys). Often the most cost-effective when used heavily; can be the most expensive when only one feature is needed. + +--- + +## Free tiers + +Free tiers exist for the early-stage and pre-PMF cases. The numbers below are current as of May 2026. + +\| Platform \| Free tier shape \| +\|---\|---\| +\| PostHog \| 1M events per month free across all features \| +\| Statsig \| 1M events per month free; full feature access \| +\| Amplitude \| 10M events per month free with basic features (some advanced features paid) \| +\| GrowthBook \| Free open-source self-hosted; cloud has a free tier with 3 users and 5 active experiments \| +\| Optimizely \| No meaningful free tier \| +\| Eppo \| No meaningful free tier \| +\| Kameleoon \| No meaningful free tier; free trial only \| + +For pre-PMF and early-stage teams, the free-tier choice is between PostHog and Statsig. Both work. Pick the one whose product surface matches your needs (PostHog if you also want analytics; Statsig if you want experiments and flags primarily). The decision is reversible at low cost while you are still on the free tier. + +--- + +## Real-world cost ranges + +Approximate ranges for paid tiers. Bands are wide because pricing varies by contract size, sales discount, and feature mix. + +### Vendor-native (events per month) + +\| Volume \| Statsig (typical) \| Optimizely (typical) \| +\|---\|---\|---\| +\| 1M to 10M \| $0 (free) to $1K/month \| Custom contract; rarely under $30K/year \| +\| 10M to 100M \| $1K to $8K/month \| $30K to $100K/year \| +\| 100M to 1B \| $8K to $40K/month \| $100K to $400K/year \| +\| 1B+ \| $40K+/month with custom negotiation \| $400K+/year with custom negotiation \| + +Optimizely consistently sits at a higher absolute price point than Statsig for the same volume. The premium pays for the marketing-led ergonomics, the visual editor, and the personalization features. Whether the premium is justified is a per-team judgment. + +### Warehouse-native (seats and compute) + +\| Team size \| Eppo (typical) \| GrowthBook paid (typical) \| +\|---\|---\|---\| +\| 5 to 10 seats \| $20K to $40K/year \| $5K to $15K/year \| +\| 10 to 30 seats \| $40K to $120K/year \| $15K to $50K/year \| +\| 30+ seats \| Custom contract \| Custom contract \| + +Plus warehouse compute. For a Snowflake-based setup running 100 to 300 active experiments per year, expect $2K to $20K/year of additional warehouse compute attributable to experimentation queries. The exact number depends on metric complexity and refresh cadence. + +### Product-suite (combined events) + +\| Volume \| PostHog (typical) \| Amplitude (typical) \| +\|---\|---\|---\| +\| 1M to 10M \| $0 (free) to $500/month \| $0 (free) to $2K/month \| +\| 10M to 100M \| $500 to $5K/month \| $2K to $20K/month \| +\| 100M to 1B \| $5K to $30K/month \| $20K to $100K/month \| +\| 1B+ \| Custom negotiation \| Custom negotiation \| + +PostHog is consistently more cost-effective for combined product analytics plus experiments. Amplitude charges a premium for the depth of its behavioral analytics; if experiments are the primary use, PostHog is hard to justify against. + +--- + +## The total cost frame + +Sticker price is one input to the cost decision. Total cost is the right frame. + +Engineer time. Wiring, maintenance, dashboard upkeep, debugging integration issues. Ranges from 5% to 30% of an engineer's time depending on platform and team size. Vendor-native is usually lower; warehouse-native is usually higher (more setup); multi-platform is usually highest. + +Statistical correctness. A single wrong-result experiment can cost more than a year of platform fees. If a platform's defaults produce confidently-wrong recommendations, the cost is the experiment that shipped wrong, not the platform fee. Worth a real review at platform decision time. + +Governance overhead. Self-hosted open-source platforms require self-built governance (audit, permissions, approval workflows). For regulated industries, this is hours of compliance review per quarter. Enterprise tiers absorb this overhead in their pricing. + +Migration risk. What is the cost if you choose wrong and need to migrate? See `migration-playbook.md` for engineer-week ranges. Multiply by the probability you will need to migrate, and that is the migration risk component of total cost. + +Cultural drift. The platform's defaults shape what the team thinks experimentation is. PM-led platforms produce PM-led cultures. Marketing-led platforms produce marketing-led cultures. The drift is hard to price but real. + +--- + +## Finance conversation patterns + +Three patterns that work when justifying a platform decision to finance. + +### Pattern 1: cost per experiment + +Compute the all-in cost per experiment shipped: platform fees plus engineer time amortized across experiments per year. This converts platform cost into a unit that finance understands. A team running 50 experiments per year on a $40K platform fee is paying $800 per experiment in platform alone, plus engineer time. A team running 200 experiments on the same fee is paying $200 per experiment. + +The frame: more experiments per year reduces unit cost. Justify investment by showing a path to higher experiment throughput. + +### Pattern 2: avoided wrong-result experiments + +Estimate the cost of a wrong-result decision. For revenue experiments, this is often $50K to $500K (the value of the experiment shipped wrong). Multiply by the rate of wrong-result decisions before and after a platform change. + +The frame: a more rigorous platform avoids wrong-result decisions. A few avoided wrong-results per year easily justify the platform premium. + +### Pattern 3: total cost of ownership across alternatives + +Build a 3-year TCO model for the top two or three candidates. Include platform fees, engineer time, migration costs, and governance overhead. Show the comparison. + +The frame: the cheapest sticker price is rarely the cheapest TCO. The platform that minimizes engineer time often wins on TCO even if it costs more per month. + +Use whichever pattern matches finance's mental model. Pattern 1 works for ROI-focused finance leaders. Pattern 2 works for risk-focused leaders. Pattern 3 works for procurement-focused leaders. + +--- + +## Negotiation tips + +Three patterns work in vendor negotiations. + +1. Multi-year commits unlock 15 to 30% discounts. If the team is confident in the platform, lock in the discount. +2. Event volume tiers are negotiable. The published pricing is the starting position. Custom contracts at scale always run below it. +3. Bundle features for unit-cost reduction. Combining experiments and feature flags in one contract often costs less than the same features separately. + +Do not negotiate from desperation. If the team is in a "we have to migrate this quarter" position, the vendor knows and the discount evaporates. Negotiate from a position of optionality: keep the trial of the alternative platform live until the contract closes. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md new file mode 100644 index 0000000..f7db5ca --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md @@ -0,0 +1,133 @@ +# Governance and team setup + +Permission tiers, approval workflows, audit trail requirements, environment promotion, team fit assessment, and onboarding playbooks. + +Governance is the unglamorous discipline that prevents the worst outcomes. A team that ships fast without governance will eventually have an "anyone can modify production targeting" incident. This reference is the structure that prevents it. + +--- + +## The four governance pillars + +### Permission tiers + +A typical permission model has four tiers. + +1. Read. See experiments, flags, and results. Default for analysts, partners, and read-only stakeholders. +2. Author. Create and modify experiments and flags in non-production environments. Default for PMs and engineers shipping experiments. +3. Production. Modify production targeting. Reserved for senior engineers, leads, or designated experiment owners. +4. Admin. Manage users, billing, integrations. Reserved for engineering leadership and platform owners. + +Map roles to tiers. Document who has which tier. Review quarterly. Remove access proactively when someone changes roles. + +For platforms that do not natively support fine-grained permissions (some open-source self-hosted setups), build the permission model in the deployment process. For example, only certain CI/CD pipelines can push to production targeting. + +### Approval workflows + +Production-impacting changes go through review. The minimum approval workflow has three steps. + +1. The author proposes the change (new experiment, modified targeting, rollout to higher percentage). +2. A second person reviews. The reviewer is not the author. +3. The change is logged with actor, timestamp, before-and-after, and reason. + +Lighter approval is acceptable for low-risk experiments (5% rollout to internal users). Stricter approval applies to high-risk experiments (revenue, billing, security-adjacent). + +Some platforms (Optimizely Enterprise, Statsig Enterprise) build the approval workflow into the platform. Others require self-built workflows in your deployment process or change management tool. + +### Audit trails + +Every change logged. The log includes actor, timestamp, before state, after state, and reason. The log is immutable and queryable. + +Audit trails matter for two reasons. The first is compliance: regulated industries require them. The second is post-incident analysis: when a wrong-result decision ships, the audit trail tells you exactly when and why the experiment was modified. + +For platforms that do not natively log every change (smaller open-source setups), build the audit at the deployment-pipeline level. Every push to the experimentation platform's API runs through a logging proxy. + +### Environment promotion + +Experiments and flags promoted through environments: dev, staging, production. The promotion is not automatic. Each promotion is a deliberate decision. + +The minimum environment model is dev plus production. The fuller model is dev, staging, production. Larger organizations add a pre-production environment that mirrors production traffic for risk-free smoke testing. + +Promotion rules. Experiments are tested in dev first. The experiment definition (targeting, variants, metrics) is identical across environments. Only the user population differs. Promotion to production requires approval. + +--- + +## Team fit assessment + +The platform's defaults shape the team's experimentation culture. Pick the alignment that matches who you actually want running experiments. + +PM-led culture. PMs author and own experiments. Engineers wire metrics and SDK changes. The platform should have a low-overhead experiment authoring surface, clear analytics, and good metric documentation. + +Best fit: Statsig, PostHog. Both have PM-friendly authoring surfaces. + +Engineer-led culture. Engineers author and own experiments. PMs review and prioritize. The platform should have a code-first authoring surface and good SDK ergonomics. + +Best fit: PostHog, GrowthBook. Both have strong code-first paths. + +Data-team-led culture. Analysts and data scientists author experiments. The platform should have warehouse-native architecture, deep statistical defaults, and SQL-first metric definitions. + +Best fit: Eppo, GrowthBook. Both are warehouse-native. + +Marketing-led culture. Marketing teams author experiments without engineer involvement. The platform should have a visual editor and non-technical experiment authoring. + +Best fit: Optimizely, Kameleoon. Both have mature visual editors. + +The wrong fit is constant friction. A PM-led team on a marketing-led platform will struggle with the visual-editor-first authoring surface. A marketing-led team on an engineer-led platform will not be able to ship without filing engineering tickets. + +--- + +## Onboarding cost + +Time to first experiment for a new team member is a real metric. Track it after platform decisions. + +Statsig and PostHog. Hours to days. The authoring surfaces are PM-friendly; new team members can ship a low-risk experiment in a single afternoon with documentation. + +Optimizely. Days to weeks. The visual editor is approachable for non-engineers, but the platform's depth means navigation takes time. New marketing team members can ship faster than new engineering team members. + +Eppo and GrowthBook. Days if the warehouse and metrics are already wired in. Weeks if not. The setup overhead is in the warehouse layer, not the platform itself. + +Amplitude. Hours if the team is already using Amplitude for analytics. The experiments surface is a small extension of the analytics surface. New team members already familiar with Amplitude pick it up quickly. + +Kameleoon. Hours for the visual editor. Days for the win-to-code workflow. The specialty workflow has its own learning curve. + +--- + +## Onboarding playbook + +A repeatable onboarding playbook for a new PM or engineer joining an experimentation discipline. + +### Day 1: orientation + +- Read the platform documentation overview (1 hour). +- Walk through one completed experiment in the platform with the team owner (30 minutes). +- Review the team's metric definitions and ownership matrix (30 minutes). +- Get permissions provisioned at the Author tier (varies; aim for same day). + +### Day 2 to 5: shadow + +- Sit in on one experiment review meeting. +- Read the last 3 to 5 experiment writeups. +- Pair with a senior team member on a low-risk experiment. + +### Week 2: ship + +- Author and ship a low-risk internal experiment (5% rollout to internal users). +- Write up results. +- Get feedback from a senior team member. + +### Week 3 to 4: own + +- Take ownership of a backlogged experiment. +- Ship it end to end. +- Present results to stakeholders. + +After week 4, the new team member is fully onboarded. Track the time to first experiment as a metric. Investigate when it exceeds two weeks; that is a signal of either platform friction or onboarding-process drift. + +--- + +## Common governance failures + +Three patterns recur. + +1. Permission creep. Everyone gets Production tier "for convenience." Six months later, no one knows who can modify production targeting. The fix is quarterly access reviews and a strict default to Read or Author tier. +2. Approval theater. Changes go through an approval workflow but reviewers do not actually review. The fix is to require a substantive comment on every approval, not just a click. +3. Audit log drift. The audit log exists but no one reads it. The fix is to surface audit log highlights (high-risk changes, unusual targeting modifications) in a weekly digest. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md new file mode 100644 index 0000000..2c25bfc --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md @@ -0,0 +1,97 @@ +# MCP capability comparison + +Side-by-side capability matrix across the seven covered platforms. Current as of May 2026. MCP capability evolves quickly; verify before committing. + +The matrix is organized by capability category. Read it as "if my workflow needs X, which platforms support it." If your workflow needs every capability across the board, the answer is Statsig, PostHog, or Optimizely (the most mature MCPs). If your workflow needs a specific subset, smaller MCPs may be a better fit. + +--- + +## Capability matrix + +\| Capability \| Statsig \| PostHog \| GrowthBook \| Optimizely \| Amplitude \| Eppo \| Kameleoon \| +\|---\|---\|---\|---\|---\|---\|---\|---\| +\| Read feature flags \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Create or update feature flags \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Read experiments \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Create or update experiments \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Read experiment results \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Query analytics or events \| Yes \| Yes (200+ tools) \| Limited \| Limited \| Yes \| No (REST) \| No \| +\| Manage segments and audiences \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Governance actions (permissions, audit) \| Partial \| Partial \| No \| Yes \| Partial \| No \| No \| +\| Code generation (variant to component) \| No \| No \| No \| No \| No \| No \| Yes \| +\| Hosting model \| First-party (managed) \| First-party + self-host \| First-party + OSS self-host \| Hosted Remote \| Hosted \| n/a (REST) \| Hosted Remote \| +\| Auth method \| API key \| API key \| API key \| OAuth \| API key \| n/a \| OAuth \| +\| Approximate tool count \| ~30 \| 200+ \| ~25 \| ~20 \| ~15 \| n/a \| 7 \| +\| Recommended scoping \| Default \| `?features=` to scope \| Default \| Default \| Default \| n/a \| Default \| + +--- + +## Notes per platform + +### Statsig + +The MCP is mature and covers the full Statsig surface (gates, dynamic configs, experiments, holdouts, layers). The tool count is moderate, which keeps the agent context window tight without sacrificing capability. Authentication is API-key based; provision a service account for agent workflows so the audit trail is clean. + +Recommended for AI-forward teams that want full CRUD without context window concerns. + +### PostHog + +The MCP is the most expansive of any platform here. 200+ tools cover analytics, experiments, flags, surveys, replays, and more. The breadth comes with a cost: without scoping, the agent's context window fills with tool definitions before it can do useful work. + +Use the `?features=` scoping parameter to load only the surfaces you need. For an experimentation-focused workflow, scope to flags, experiments, and analytics; skip replays, surveys, and error tracking unless they are part of the workflow. + +Recommended for AI-forward teams that need broad coverage and are willing to invest in scoping discipline. + +### GrowthBook + +The MCP is the first open-source production MCP for experimentation. It covers the GrowthBook surface (experiments, flags, metrics, segments). Tool count is moderate. Self-host means you can run the MCP inside your network for data sovereignty. + +Recommended for OSS-preferring teams and regulated industries that need the MCP inside their VPC. + +### Optimizely + +The hosted Remote MCP works in browser-based ChatGPT and Claude.ai. Authentication is OAuth, which integrates cleanly with enterprise SSO. Tool count is moderate. Coverage is solid on Web Experimentation and Feature Experimentation; Personalization features are accessed via the same surface. + +Recommended for enterprise teams that need OAuth and SSO compatibility for compliance. + +### Amplitude + +The hosted MCP is available to all customers including the free tier. Tool count is smaller than Statsig or PostHog. Coverage is strongest on analytics queries (cohorts, funnels, retention) and adequate on experiments and flags. + +Recommended for teams that primarily need analytics queries and use experiments as a supplementary capability. + +### Eppo + +No first-party MCP as of May 2026. REST API is the integration path. Workflows that depend on agent-driven experiment creation need a custom adapter or a wait until Eppo ships an MCP. + +Track for a future MCP release. The platform has the underlying API; an MCP wrapper is a likely future development. + +### Kameleoon + +Hosted Remote MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. The tool surface is purpose-built for the win-to-code workflow. The smallest MCP in this matrix and the most opinionated. + +Recommended for teams running the marketing-site-to-product-code workflow. Layer with another MCP if your needs go beyond that scope. + +--- + +## Choosing by workflow + +Agent-driven full experiment lifecycle (create, run, monitor, conclude). Statsig, PostHog, GrowthBook, or Optimizely. All four support full CRUD via MCP. + +Agent-driven analytics queries plus light experiment work. PostHog (with scoping) or Amplitude. Both have strong analytics MCP coverage. + +Agent-driven win-to-code conversion. Kameleoon. The only platform with this workflow as a primary feature. + +Human-driven workflow where MCP is supplementary. Any of the seven. Eppo via REST works for the supplementary case. + +Compliance-sensitive workflow (SSO, audit, data residency). Optimizely (OAuth, hosted) or GrowthBook self-hosted (data residency, OSS auditable). + +--- + +## Things to check before committing + +1. Tool count and scoping. Verify the agent context window is comfortable with the platform's tool surface. PostHog without scoping fills the window fast. +2. Auth model. API key is faster to provision; OAuth is required for compliance-sensitive deployments. +3. CRUD coverage. Read-only MCPs limit your workflow. Verify create and update are supported for your target objects. +4. Hosting model. Hosted is faster to start; self-host is required for data sovereignty. +5. Trajectory. MCP capability evolves monthly. Check the platform's changelog before committing for a future-sensitive workflow. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md new file mode 100644 index 0000000..94c8ec8 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/migration-playbook.md @@ -0,0 +1,139 @@ +# Migration playbook + +Five common migration paths with effort estimates, the first 30 days plan, the 30-90 day cutover plan, and what NOT to do. + +The discipline applies to every migration. Three rules are non-negotiable: + +1. Do not parallel-run forever. Set a cutover date and hold to it. +2. Do not big-bang switch. The risk of a silent miscount is too high; you cannot tell whether the new platform is computing correctly without overlap. +3. Do not retire the old platform before all in-flight experiments complete. + +--- + +## Statsig to PostHog + +Trigger. Company has outgrown a pure experimentation platform and wants analytics, experiments, and feature flags in one surface. Often coincides with consolidating away from a separate analytics tool. + +Effort. 3 to 5 engineer-weeks. Add 2 to 4 weeks if you are also consolidating analytics. + +First 30 days plan. +- Week 1: Provision PostHog. Wire the SDK alongside Statsig. Verify event volume matches. +- Week 2: Recreate the top 5 metrics in PostHog. Compare totals against Statsig over a 7-day window. Investigate any variance over 1%. +- Week 3: Recreate 1 active experiment in PostHog as a parallel experiment. Run both for 7 to 14 days. Confirm results agree within statistical noise. +- Week 4: Decision review. Either commit to migration or roll back to Statsig only. Document the decision. + +30-90 day cutover plan. +- Migrate experiments one at a time. New experiments start in PostHog. Existing experiments complete in Statsig. +- Migrate feature flags by service. Highest-risk services move last. +- Build dashboards in PostHog before retiring Statsig dashboards. +- Final week: retire Statsig SDK from the codebase. Remove credentials. + +What NOT to do. +- Parallel-run the SDKs for more than 90 days. The dual cost compounds; the integration tax distracts. +- Migrate flags before experiments. Flags are operational; experiments are time-bound. Flag migration creates production risk that overshadows the migration value. +- Skip the metric reconciliation. Discovering a metric definition mismatch a month into the migration is the worst possible time. + +--- + +## Optimizely to Statsig + +Trigger. Budget pressure or modernization push. Often coincides with a CFO-led cost review. + +Effort. 4 to 8 engineer-weeks. Add weeks proportional to how heavily personalization features are used (Optimizely has personalization that Statsig does not match). + +First 30 days plan. +- Week 1: Feature parity audit. List every Optimizely feature in active use. Mark which ones Statsig covers, which it does not, and which need a workaround. +- Week 2: Migrate the simplest 3 experiments. Validate results match. +- Week 3: Address the personalization gap. If personalization is heavy, plan a hybrid (Statsig for product experiments, Optimizely retained for personalization, with a retirement date in 6 to 12 months). +- Week 4: Decision review. Commit to full migration or hybrid. + +30-90 day cutover plan. +- Migrate experiments first, flags second. Personalization last (or retain in Optimizely). +- Communicate clearly with non-engineering experiment authors. The visual editor change is the friction point. +- Train non-engineering authors on Statsig's experiment definition format. +- Final phase: cancel Optimizely contract on its renewal date. Do not cancel mid-term; the savings rarely justify the early-termination friction. + +What NOT to do. +- Underestimate the non-engineering author retraining. Marketing-led teams will resist the platform change harder than engineering-led teams. +- Force personalization into Statsig if the use case does not fit. A hybrid setup is cheaper than a forced consolidation that the team cannot use. +- Cancel the Optimizely contract before all in-flight experiments complete on the old platform. + +--- + +## PostHog to Eppo + +Trigger. Statistical rigor becomes the binding constraint. A data team has joined or grown, and a critical experiment surfaced a wrong-result decision that PostHog's defaults did not catch. + +Effort. 6 to 10 engineer-weeks. The migration is harder because PostHog includes session replay, error tracking, and analytics that Eppo does not replace. Plan for a dual-platform end state. + +First 30 days plan. +- Week 1: Define the scope. Eppo replaces experiments. PostHog stays for analytics, replay, and tracking. Document which surface owns what. +- Week 2: Wire Eppo SDK alongside PostHog. Configure metric definitions in the warehouse. +- Week 3: Run one parallel experiment. Compare statistical conclusions. Investigate any disagreement; this is where the rigor difference shows up. +- Week 4: Decision review. Commit to the dual-platform end state or rethink scope. + +30-90 day cutover plan. +- New experiments start in Eppo. Existing experiments complete in PostHog. +- Build the metric definition layer in the warehouse so both platforms can agree on what "activation" means. +- Set up reconciliation dashboards. The two platforms will disagree on edge metrics; surface those proactively rather than letting stakeholders find them. + +What NOT to do. +- Try to retire PostHog. The non-experiment features (replay, tracking, analytics) do not have a clean Eppo replacement. +- Skip the warehouse metric layer. Without it, the two platforms compute metrics differently and stakeholders lose trust in both. +- Use Eppo for the small experiments where statistical depth is overkill. The analyst overhead per experiment is higher in Eppo than in PostHog. + +--- + +## GrowthBook to Eppo + +Trigger. Team growth and a desire for commercial support, deeper Bayesian and sequential testing features, and decision-oriented reporting. + +Effort. 2 to 4 engineer-weeks. This is the easiest migration in the playbook because both platforms are warehouse-native; the data already lives in your stack. + +First 30 days plan. +- Week 1: Provision Eppo. Reuse the warehouse connection. +- Week 2: Recreate metric definitions. Most translate cleanly. +- Week 3: Run 1 to 2 parallel experiments to validate. +- Week 4: Cutover. New experiments in Eppo. In-flight in GrowthBook complete on GrowthBook. + +30-90 day cutover plan. +- Migrate active flag rollouts to Eppo if Eppo's flag features are sufficient. +- Retire GrowthBook 30 to 60 days after the last in-flight experiment completes. + +What NOT to do. +- Migrate flags if Eppo's flag features do not match. Run a separate flag platform if needed. +- Cancel GrowthBook before all dashboards are recreated. + +--- + +## Any to Statsig (consolidation) + +Trigger. Multi-platform mess. Common when a company has accumulated 2 to 3 platforms over time and wants to consolidate. + +Effort. 6 to 12 engineer-weeks, scaling with the number of platforms and in-flight experiments. + +First 30 days plan. +- Week 1: Inventory. List every experiment, flag, and dashboard across all platforms. Identify the canonical source of truth where they disagree. +- Week 2: Statsig provisioning. Configure metrics. Validate event volume matches. +- Week 3: Migrate the simplest 5 experiments. Validate results. +- Week 4: Migration plan with explicit retirement dates per old platform. + +30-90 day cutover plan. +- Per-platform retirement. Pick one of the old platforms to retire first (usually the smallest user base). +- Communicate retirement dates clearly. Stakeholders need 30 days of warning per platform. +- Build dashboards before retiring; never after. + +What NOT to do. +- Try to retire all old platforms at once. Sequential retirement is slower but lower risk. +- Skip the inventory step. Discovering a forgotten experiment in production after retirement is the failure mode. +- Underestimate the team training cost. Multi-platform teams have built workflow muscle memory across all of them; consolidation requires retraining. + +--- + +## Validation: how to know the migration succeeded + +Three signals that the migration is complete and successful. + +1. All in-flight experiments completed on the original platform. No experiment was stranded mid-test. +2. Metric values match within statistical noise on the new platform for at least 30 days post-cutover. Variance over 1 to 2% needs investigation. +3. The team is shipping experiments at the pre-migration rate or faster within 60 days of cutover. If velocity has not recovered, retraining or workflow changes are still needed. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md new file mode 100644 index 0000000..9553bc5 --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md @@ -0,0 +1,99 @@ +# Multi-platform orchestration + +When multi-platform is genuine, three coordination patterns are non-negotiable: an ownership matrix, shared metric definitions, and reconciliable dashboards. + +This reference is for the 20% of teams whose surfaces genuinely warrant more than one platform. The 80% should consolidate. If you are not sure which group you are in, the test is whether the platforms overlap. Zero overlap is a candidate for multi-platform; any overlap is a candidate for consolidation. + +--- + +## When multi-platform is warranted + +The pattern is: different surface, different audience, different metric set, no overlap. + +Marketing site plus product app. Kameleoon for personalization on the marketing site. Statsig for product experiments. The marketing site's metrics (conversion to signup, page-level engagement) do not collide with the product app's metrics (activation, retention, revenue). The two surfaces are run by different teams with different cadences. + +Content site plus product app. Optimizely or Kameleoon for content experiments. PostHog or Statsig for product. Same pattern: different surface, different audience. + +Pre-acquisition multi-tool reality. Two products from two acquired companies on different platforms. Multi-platform is the temporary reality; consolidation is the eventual answer. Plan a retirement date during the integration project. + +Specialized statistical needs. A core product on Statsig plus a specialized statistical workload (causal inference, network effects analysis) running on a separate tool. Rare but legitimate when the specialty platform has capabilities the primary platform lacks. + +--- + +## When multi-platform is a mess + +Three signals that the multi-platform setup has drifted into a consolidation candidate: + +1. The same experiment can be defined on more than one platform. Stakeholders ask "which one are we using?" and the answer is unclear. +2. Metrics differ between platforms. "Activation rate" computes one way in Statsig and another way in PostHog. Stakeholders see two numbers and trust neither. +3. Operational overhead exceeds the value of platform diversity. Engineers spend more time keeping platforms in sync than they save by using each platform's strengths. + +If two of three apply, plan a consolidation. + +--- + +## The ownership matrix + +The first artifact of a multi-platform setup is an explicit ownership matrix. It names which platform owns which surface, which metrics, and which experiments. Disagreements between platforms are resolved against the matrix. + +\| Surface \| Primary platform \| Secondary platform (if any) \| Owner \| +\|---\|---\|---\|---\| +\| Marketing site \| Kameleoon \| None \| Marketing team \| +\| Product app \| Statsig \| None \| Product team \| +\| Mobile app \| Statsig \| None \| Mobile team \| +\| Email \| None \| None \| n/a \| +\| Pricing page \| Kameleoon \| Statsig (revenue metrics) \| Marketing team primary, product team consulted \| + +Where two platforms touch the same surface (the pricing page row), name a primary and clarify what the secondary is responsible for. Ambiguity here is the source of every multi-platform drift. + +The ownership matrix lives in a single document, version-controlled, reviewed quarterly. Stakeholders refer to it instead of arguing. + +--- + +## Shared metric definitions + +The second artifact is a shared metric definitions document. The same metric should compute the same way across platforms. + +Example. "Activation rate" might be defined as: percentage of users who completed onboarding within 7 days of signup. The definition includes the event name, the time window, the denominator population, and any exclusions. Both platforms reference the same definition. + +In practice, sharing definitions across platforms is hard. Three approaches. + +Single source warehouse layer. Define metrics in your warehouse using a metrics layer (dbt, Cube, Metricflow). Both platforms query the warehouse. This is the strongest pattern. It works if both platforms support warehouse-native metrics (GrowthBook, Eppo) or have warehouse integration paths. + +Documented definitions with periodic reconciliation. Each platform has its own metric. The definitions document records what each is supposed to compute. A weekly or monthly reconciliation job compares the two and surfaces variance. This works for vendor-native platforms that do not share a warehouse. + +Tolerance for variance. Accept that the two platforms compute slightly differently and document the expected variance range. Over 1 to 2% triggers an investigation. Under 1% is treated as noise. This works when the platforms are used for different surfaces and the metrics are not directly compared across them. + +The wrong approach is no approach. Without one of these three patterns, the platforms drift, and a leadership disagreement surfaces in the worst possible moment. + +--- + +## Reconciliable dashboards + +The third artifact is dashboards that surface the same metrics from both platforms side by side. The point is not that the numbers always agree (they will not). The point is that disagreements are visible and explainable. + +A reconciliation dashboard has three columns per metric: the value from platform A, the value from platform B, and the variance with a threshold. Variance over the threshold triggers a notification. Owners investigate and either explain the variance or fix the underlying definition mismatch. + +Reconciliation runs daily for high-stakes metrics, weekly for everything else. Outputs go to a shared channel where the team sees them; do not let reconciliation reports live in a folder no one reads. + +--- + +## The "primary platform" rule + +In every multi-platform setup, one platform is canonical. If the platforms disagree, the canonical answer wins. Pick the canonical platform once, document it, and stop arguing. + +The canonical platform is usually the one that owns the surface where the metric originates. Revenue metrics: the warehouse is canonical. Product engagement: the product analytics platform is canonical. Marketing-site conversion: the marketing experiment platform is canonical. + +Without a canonical, every disagreement becomes a debate. With a canonical, disagreements become investigations into why the non-canonical platform diverged. + +--- + +## When to consolidate + +Three signals that consolidation is overdue: + +1. The reconciliation dashboard reports variance more often than not. The platforms drift faster than the team can reconcile. The cost of staying multi-platform exceeds the cost of consolidating. +2. A leadership disagreement surfaces a "which one is the source of truth" debate. Multi-platform is meant to support different surfaces, not different versions of the same answer. If the same answer has two values, consolidation is the fix. +3. The team is spending more than 10% of its experimentation operational time on platform coordination. That time should be on experiments, not platform plumbing. + +When consolidation is the right answer, see `migration-playbook.md` for the patterns. The consolidation move is almost always to whichever platform is closest to the canonical for the highest-stakes surface. diff --git a/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md new file mode 100644 index 0000000..1025a1f --- /dev/null +++ b/dist/pi/.agents/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md @@ -0,0 +1,61 @@ +# Platform decision matrix + +A context-to-platform map. The left column is the situation. The center column is the recommendation. The right column is the reasoning and the common alternative. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. The remaining rows are useful as cross-checks rather than primary picks. + +--- + +## The matrix + +\| Situation \| Primary recommendation \| Reasoning and common alternative \| +\|---\|---\|---\| +\| Pure SaaS, fast-growing, want one platform for flags and experiments \| Statsig \| Combined feature flags and experiments, modern statistical defaults, fast time to first experiment. Alternative: PostHog if you also want analytics. \| +\| Product-led growth, want analytics and experiments together \| PostHog \| Full-funnel context, free tier covers early growth, mature MCP for AI workflows. Alternative: Amplitude if analytics depth matters more than experiment depth. \| +\| Open-source preference, data sovereignty, warehouse-native \| GrowthBook \| Data stays in your warehouse, OSS license avoids vendor lock-in, mature statistical defaults. Alternative: PostHog self-hosted if you also need analytics. \| +\| Enterprise, marketing-led, deep personalization \| Optimizely \| Visual editing for non-engineers, mature governance, decades of features. Alternative: Adobe Target if you are already on the Adobe stack. \| +\| Already deep on Amplitude for analytics \| Amplitude \| Adding experiments is the path of least resistance. Alternative: layer Statsig or Eppo only if statistical depth becomes the binding constraint. \| +\| Data-team-led, statistical correctness paramount, MCP not yet required \| Eppo \| Strongest statistical defaults among warehouse-native platforms, decision-oriented reporting. Alternative: GrowthBook if open-source is non-negotiable. \| +\| Convert marketing-site wins into permanent code \| Kameleoon \| Purpose-built for the win-to-code path; the only platform with this workflow as a primary feature. Use alongside a primary product-experiment platform. \| +\| Regulated industry (HIPAA, FedRAMP, healthcare), self-hosting required \| GrowthBook self-hosted \| Full data residency, audit-friendly, OSS auditable. Alternative: PostHog self-hosted if you also need analytics. \| +\| Pre-PMF, low traffic, need free tier \| PostHog free or Statsig free \| Both free tiers cover the early phase. Defer the real platform decision until you have the traffic to make any platform meaningful. \| +\| 100M+ events per month, cost control is the binding constraint \| GrowthBook or Eppo \| Warehouse-native pricing scales better than vendor-native at this volume. Alternative: negotiate a custom contract with Statsig or PostHog; only worth it if vendor-native features justify the premium. \| +\| AI-forward team, MCP-first workflow important \| Statsig, PostHog, GrowthBook, or Optimizely \| All four have mature MCPs with full CRUD coverage. Avoid Eppo for now (REST only). \| +\| Mid-market SaaS, governance important, single tool preference \| Statsig \| Enterprise governance is mature, combined flags and experiments simplify the operational surface. Alternative: Optimizely if marketing-led, GrowthBook if open-source preferred. \| +\| Web-only personalization, content site, no product app \| Kameleoon or Optimizely \| Both are strong on visual editing and personalization. Kameleoon for the win-to-code workflow; Optimizely for enterprise governance. \| +\| Data warehouse already in place (Snowflake, BigQuery), small data team \| Eppo \| Statistical defaults are decision-grade, warehouse compute is already a line item, low operational burden. Alternative: GrowthBook if commercial support is not required. \| +\| Solo founder or pre-seed startup \| PostHog free or Statsig free \| Both work, both are free at this stage. Pick whichever you are more familiar with; the decision is reversible. \| + +--- + +## Worked examples + +### Example 1: Series B SaaS, 5M events/month, PM-led, considering Statsig vs PostHog + +The team has feature flags in LaunchDarkly already, has analytics in Amplitude, and is considering experiments. The PM-led culture wants experiments shipped weekly with low engineer overhead. + +Recommendation. Statsig. The PM-led culture matches Statsig's defaults. The 5M event volume is comfortably in the free tier or a small paid contract. Combined flags and experiments will likely cause a LaunchDarkly migration in 12 to 18 months, but that is a future decision, not a current one. PostHog is the alternative if the team also wants to consolidate analytics, but Amplitude is already paid for and migrating analytics is a bigger project than starting experiments. + +### Example 2: 50-person fintech, regulated industry, need data residency + +The team needs HIPAA-equivalent controls (financial regulations), data must stay in their VPC, and the engineering team is comfortable with a more hands-on platform. + +Recommendation. GrowthBook self-hosted. Data residency is a hard requirement and rules out all vendor-native options. The engineering team has the capacity to operate self-hosted. PostHog self-hosted is the alternative if analytics is also needed. + +### Example 3: Marketing-led brand, want non-engineer-shipped experiments + +The team is a marketing organization with a small engineering function. The marketing leads want to ship experiments without filing engineering tickets. + +Recommendation. Optimizely. Visual editing for non-engineers is a hard requirement. Statsig and PostHog can be used by non-engineers but require more comfort with structured experiment definitions. Kameleoon is the alternative if the win-to-code workflow is important. + +### Example 4: Data-team-led, 100M events/month, statistical depth required + +The data science team owns experimentation, runs the warehouse, and has been burned by misleading results from a less rigorous platform. + +Recommendation. Eppo. Statistical correctness is the headline. The 100M event volume makes warehouse-native pricing more attractive. The lack of MCP is acceptable because the team's workflow is data-scientist-driven, not agent-driven. GrowthBook is the alternative if open-source is required. + +### Example 5: Pre-PMF startup, 200K events/month + +The team has a product but no product-market fit. They want to start experimenting to find the wedge. + +Recommendation. PostHog free tier. Free covers the volume. Analytics plus experiments in one place lets the team learn. Defer the real platform decision until traffic is 10x higher and the platform tax becomes a real number. diff --git a/dist/pi/.agents/skills/feature-flagging/SKILL.md b/dist/pi/.agents/skills/feature-flagging/SKILL.md new file mode 100644 index 0000000..c0fa267 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/SKILL.md @@ -0,0 +1,281 @@ +--- +name: feature-flagging +description: Operational discipline for feature flags as production infrastructure. Flag types, naming, targeting rules, rollout strategy, lifecycle, governance, stale flag management, and the technical debt patterns that bite teams who weren't deliberate about it. +category: product +catalog_summary: "Flags as production infrastructure: types, naming, lifecycle, targeting, rollout, stale flag cleanup, governance" +display_order: 5 +--- + +# Feature Flagging + +A senior engineer's playbook for using feature flags well, not just frequently. + +Feature flags are infrastructure. Treated as such, they enable kill switches, gradual rollouts, A/B experiments, permission gates, and operational toggles without redeploys. Treated casually, they become the largest accumulating technical debt in your codebase: thousands of dead flags, conflicting evaluation logic, brittle targeting, and a permission surface no one fully understands. + +This skill is the discipline that prevents the second outcome. It assumes you have a feature flag platform (LaunchDarkly, Flagsmith, Split.io, VWO FME, GrowthBook, Statsig, PostHog, Optimizely; the platform does not matter for the principles). It assumes your engineering team can implement targeting rules and SDK integration. The hard part is the operational discipline, and that is what is here. + +When to use this skill: any time you are about to introduce a flag, modify a flag, audit existing flags, or design a flag-related governance policy. + +--- + +## What this skill is for + +The skill spans the operational lifecycle of a flag from creation through retirement. Flag types and the discipline of not mixing them. Naming conventions that survive code review. Lifecycle expectations baked in at creation, not bolted on later. Targeting rules that compose without fragility. Rollout strategies that match the risk profile of the launch. Stale flag management on a quarterly cadence. Governance and permissions that balance access with audit. Performance considerations so flags do not become a latency tax. Testing patterns that cover both branches. Rollback discipline. Observability across rollouts. + +The skill does not cover experiment design; for hypothesis writing, sample size, MDE, and the discipline of arriving at a defensible decision, see the `experiment-design` skill. It does not cover statistical analysis or variance reduction; those live in the `experimentation-analytics` skill. It does not cover platform-specific tooling; for MCP commands, auth, and platform-specific configuration, consult the chosen platform's documentation. This skill produces the operational shape; the platform implements it. + +--- + +## The five flag types + +Mixing flag types is the root cause of most flag mess. A flag is one of five things; commit at creation and do not let it drift. + +Release flag. Code is in production but disabled. The new feature ships dark, gets toggled on for a percentage, then ramps to 100. Lifetime: short, days to weeks. Lifecycle: clean removal after launch. Common name prefix: `release_`. + +Experiment flag. Users are randomly assigned to variants; conversion is measured. The flag controls which variant a user sees. Lifetime: medium, one to six weeks. Lifecycle: variant chosen, code paths consolidated, flag removed. Common name prefix: `exp_`. + +Operational flag. A kill switch or circuit breaker that lets ops disable a misbehaving feature without a redeploy. Lifetime: long-lived, often years. Lifecycle: usually never removed; remains as standby. Common name prefix: `ops_`. + +Permission flag. Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. Lifetime: long-lived. Lifecycle: managed alongside billing and access infrastructure. Common name prefix: `perm_`. + +Configuration flag. Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account. Lifetime: long-lived. Lifecycle: governed by sales and product agreements. Common name prefix: `cfg_`. + +Each type has different lifecycle, governance, and removal expectations. Mixing them in one flag (the flag is both a kill switch AND a permission gate AND now we are using it for an experiment) is the most common source of flag mess. When the flag's purpose changes, create a new flag and migrate. Do not overload an existing one. + +--- + +## Flag naming conventions + +A flag name encodes type, owner, and purpose. Without that encoding, a flag list at month nine is unreadable and the cleanup playbook from [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md) cannot tell what is safe to remove. + +The convention this skill recommends is `<type>_<owner>_<semantic_name>_<version_or_date>`: + +- `release_checkout_redesign_2026q2` +- `exp_billing_pricing_v2` +- `ops_search_circuit_breaker` +- `perm_enterprise_audit_log` +- `cfg_tenant_acme_custom_dashboard` + +Pick snake_case or kebab-case once, organization-wide, and stick with it. Mixing both in the same platform produces typo-driven bugs that bite at 3 AM. Vague names die a slow death: `new_feature`, `temp_toggle`, `test_flag`, `pricing_update_v3`. Within months, no one knows which `pricing_update` shipped and which is dead. + +For deeper coverage including the table of typed prefixes, owner conventions, and the migration plan for existing badly-named flags, see [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md). + +--- + +## The flag lifecycle + +Every flag has five life phases. Each phase has explicit entry and exit criteria. Skipping phases is how flag mess accumulates. + +Birth. Flag created with explicit metadata: owner, type, target removal date (for release and experiment flags), rollout plan, monitoring approach. The metadata is not optional; without it the flag has no end-of-life. + +Adolescence. The feature behind the flag is being built. Code paths exist for both the disabled (current production) branch and the enabled (new) branch. Both are tested. The flag remains off in production. + +Launch. Production rollout begins. Percentage starts low (1 or 5 percent), monitored at each step, ramps if metrics hold. Ramp gates documented in [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +Maturity. The flag is at 100 percent rollout. The new code path is the production path. Monitoring continues for at least 30 days to catch issues that did not show up during the ramp. + +Death. The flag is removed from code (PR that deletes the gating logic) and removed from the platform. The audit trail records the removal. + +The asymmetry: birth is fast (one PR creates the flag and gates the new code), death requires intentional cleanup. Most flag mess is unfinished death. Birth-and-death have to be planned together; the death plan is part of the birth metadata. + +For the per-phase checklist, see [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md). + +--- + +## Targeting rules and segmentation + +A targeting rule is the boolean expression that determines whether a user, account, or request gets the treatment branch. There are four useful target dimensions: + +- User attributes. `user.email_domain == "acme.com"`, `user.signup_date > "2026-01-01"`, `user.plan == "enterprise"`. +- Account attributes. `account.tier == "enterprise"`, `account.region == "EU"`, `account.feature_x_enabled == true`. +- Request attributes. `request.country == "US"`, `request.device_type == "mobile"`, `request.api_version >= 3`. +- Time-based. `time > "2026-06-01T00:00:00Z"`, `time < "2026-12-31T23:59:59Z"`. + +Compose with AND, OR, and NOT. Keep the expressions simple. If your rule needs three nested clauses, your taxonomy is wrong. Either define a segment (a named group of users with shared attributes) and target the segment, or split into multiple flags. + +The most common pitfall: targeting on attributes that change frequently. If the rule is `user.last_login_date > "2026-04-01"`, a user who logs in on May 1 sees the treatment, then their value changes the next day, and they see the control again. The user experience whiplashes. Volatile attributes belong in segments computed off snapshots, not in live targeting rules. + +For pattern catalog and anti-patterns, see [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md). + +--- + +## Rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile. + +Percentage rollout. The default for release flags. Start at 1 or 5 percent. Watch error rates, latency, and the primary success metric for at least one peak hour. If clean, ramp to 10. Watch. Ramp to 25, then 50, then 100. Total elapsed time depends on traffic, but a typical pattern is 1 percent for one day, then 10 percent for two days, then 50 for two days, then 100. Production rollouts that complete in under four hours are usually rolling too fast. + +Cohort rollout. Internal employees first, then beta customers, then free tier, then paid. Each cohort is a named segment; the flag advances through them in sequence. Use this for risky launches where the blast radius matters more than rollout speed. + +Geo-staged rollout. One region at a time. The default for compliance-sensitive features (data residency, regulatory disclosures, region-specific UX). Pair with the platform's region targeting capability so the rule does not have to be hand-written. + +Time-based rollout. Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment. Watch the timezone; midnight Eastern is not midnight UTC. Avoid time-based rollouts on holidays unless you have weekend on-call coverage. + +The "ramp and watch" rule: at each percentage step, monitor the system for at least one peak hour before advancing. The peak hour is when the rate of any new failure mode is highest; if the system holds at peak for an hour, the next step is safe. If you ramp during off-peak and immediately advance, you have not actually tested the change. + +For full strategy detail and a worked example for a checkout redesign, see [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +--- + +## Stale flag management + +Every live flag adds runtime cost: evaluation overhead, two code paths to maintain, mental overhead for engineers who read the code. One flag is fine. Two hundred dead flags is a productivity tax that compounds. + +Most platforms support stale flag reporting: flags that have not been evaluated in N days. Threshold defaults: 30 days for release flags and experiment flags, 90 days for operational and permission flags. A flag that has not been evaluated in 30 days is either retired in production (no users in the targeting rule) or completely dead in code (the gating call has been removed but the flag itself was never deleted). + +The cleanup playbook is mechanical: + +1. Generate the stale flag report from the platform. +2. For each flag: identify owner, last evaluation, type, recommended action. +3. Triage in a quarterly meeting: keep, remove, or investigate. +4. Open one PR per flag for code-side removal. One per PR is reviewable; bundling ten is not. +5. Delete from the platform after the PR merges. + +The reason cleanup does not happen by default: removing a flag is a code change PR with review, testing, and deploy overhead. PMs do not reward it (the feature already shipped). SREs eventually get fed up with the noise. The fix is to make removal part of the launch checklist, not a separate effort. When a flag is created, the removal date is in the metadata. The launch ticket has a follow-up sub-ticket scheduled 30 days out that says "remove flag X." If the launch goes well, the sub-ticket gets done. + +For the full quarterly cadence including ownership rotation for orphan flags, see [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md). + +--- + +## Governance and permissions + +Different roles need different access. Engineering can create flags broadly. Product can author targeting rules in dev and staging. Production targeting changes deserve a smaller set of approvers. + +Recommended permission tiers: + +- Viewer. Read-only across all environments. Includes most of engineering, product, support. +- Editor. Can create and modify flags in dev and staging. Includes the team that owns the flag. +- Approver. Can promote flag changes from staging to production. Smaller group; usually the team lead and the on-call engineer. +- Admin. Full control including deleting flags, modifying permissions, and accessing audit logs. Smallest group; platform team plus a backup. + +Production-impacting flag changes go through review like deploys, not chat. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review; the rule does not silently appear in production because someone clicked a button. + +Audit trail: every flag change logged with actor, timestamp, before/after rule, reason. Most platforms expose this; configure it to write to the central log aggregator alongside other infrastructure events. + +Environment promotion: rules tested in dev, promoted to staging, promoted to production. Authoring a production rule directly in production skips both staging tests and the review gate. Treat it as a deploy: dev → staging → production, with the same review and approval at each stage. + +Emergency override: who can flip the kill switch at 3 AM? Document, test in incident drills, and confirm the override path actually works. A kill switch nobody can find is not a kill switch. + +--- + +## Flag dependencies and conflicts + +Two failure modes that come from flags interacting: + +Dependency. Flag B's code path requires flag A to be on. Hard to model in most platforms; the SDK does not know about the inter-flag relationship. Avoid where possible; if you need to express it, document in the flag description and add a unit test that fails if A is off and B is on. + +Conflict. Two flags target the same surface, last-write-wins. The result depends on evaluation order, which depends on SDK implementation, which depends on platform internals. Detect via shared-key audit: any two flags whose targeting rules overlap on the same code path is a conflict candidate. The platform usually does not flag this; the team has to audit. + +Cross-team conflict is the dangerous version: team Alpha's release flag for the checkout redesign interacts with team Bravo's experiment on the pricing page. The interaction is invisible until production users see broken UI because both flags fired. The fix is up-front coordination via the experiment registry described in `experiment-design`. Discover before launch via planning, not via a 2 AM incident. + +For mutually exclusive experiment groups (where the platform enforces that a user is in either test A or test B but never both), see the experiment-design skill's coverage of mutex enforcement. + +--- + +## Performance considerations + +A flag evaluation is a function call (cheap) plus possibly a network call to the platform (expensive). The performance question is how much you spend in the latter. + +Cache aggressively. Most server-side SDKs cache flag values per request, per session, or per user; configure the cache so the network call happens once per relevant scope, not on every flag check. A request that evaluates fifty flags should hit the platform once at request start, not fifty times. + +Bulk evaluation: most platforms support evaluating all flags for a user or context in one call. Use it. The latency cost of "fifty individual flag checks" is fifty times the per-check overhead; the latency cost of "one bulk evaluation that returns all fifty" is one round trip plus a fast lookup per check. + +SDK selection: server-side SDKs are usually preferable to client-side for sensitive logic where latency, security, and freshness matter. Client-side SDKs are appropriate for UI-only behavior where the user can see the flag value in DevTools anyway. Mixing the two creates inconsistencies; if a user gets a different flag value on the server than the client, the UI breaks. + +Latency budget: evaluating fifty flags per request should add no more than 5 ms in the typical case. If it adds more, the SDK is misconfigured (no caching, no bulk evaluation, evaluating in a hot loop). Audit before scaling. + +--- + +## Testing flag-gated code + +Both branches need tests. The disabled branch is the existing production behavior; the enabled branch is the new code. Unit tests cover both with explicit flag overrides at test setup. + +Test the transition. What happens to a user mid-session when their flag value changes? In most well-behaved systems, the user finishes their current request with the value they had at request start, then sees the new value on the next request. Document the assumption explicitly. If your system mid-flips a user inside a session, that is usually a bug. + +Integration tests with flag overrides: most platforms support test-only flag overrides that do not affect production. Use them for end-to-end tests that exercise both branches. Without test overrides, integration tests have to share the production flag config, which means you cannot test new features that are still gated off in production. + +Common failure: shipping a "wins" experiment but only the test environment had the right targeting rules. The test environment let in 100 percent of test users via a permissive rule; production rules are stricter and let in only 20 percent. The lift you measured does not translate. Catch via staged rollout: the first 1 percent in production should match the test result before you ramp further. + +--- + +## Rollback discipline + +Flags are useful for instant rollback of the gated change. They are not a substitute for code rollback. If a bug ships in code that is not flag-gated (a fix to the existing path, an unrelated change in the same deploy), flipping the flag does nothing. Treat flag rollback as one tool among several, not as the only tool. + +If flipping the flag does work, document the rollback. If it does not work, the bug is in non-flag-gated code or in flag dependencies. Diagnose accordingly; do not assume the flag failed. + +Speed matters. How fast can you flip a flag in production? The target is under 60 seconds via UI or MCP, under 5 minutes via API plus auth. If your platform takes 15 minutes to propagate a flag change, that is a real incident-response constraint and the team should know. + +Practice. Include flag rollback in incident drills. The first time you flip a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. + +--- + +## Observability on flags + +Log flag evaluations alongside other request data. The flag value at evaluation time goes on the request log as a contextual field. When you investigate a slow request or an error, the log shows which flag values were active. + +Alert on flag evaluation rate changes. If a flag's evaluation rate suddenly drops, the rule is misconfigured (no users matching) or the SDK is broken. Either way, the team should know within minutes. + +Build dashboards for production rollouts. What percentage of users see treatment versus control, broken down by region, plan, device, etc. Without the dashboard, the rollout is a black box; with it, the team can answer "are we actually rolling out evenly across segments?" without writing a SQL query. + +Connect to error tracking. When errors spike during a rollout, the dashboard should show whether errors correlate with the flag value. Spike on treatment branch = roll back the flag. Spike on both branches = the issue is unrelated and the flag rollback will not help. + +--- + +## Common failures (rapid-fire) + +A short pattern catalog. Detail in `references/`. + +- "We launched but 90 percent of users still see the old version" means the rollout rule is wrong. Audit the rule against actual user attributes. +- "We disabled the flag but the bug is still happening" means the affected code path is not flag-gated, or there is a cached value, or a dependent flag is still on. +- "We have 400 dead flags and removing them is too risky" means cleanup never happened. Start the quarterly cadence now; one PR per flag. +- "Two flags target the same code path and we don't know which wins" means a conflict. Audit shared keys, decide one of them is canonical, retire the other. +- "Our flag evaluator is causing latency spikes" means bulk evaluation or caching is missing. Audit the SDK config. +- "We need to give finance access to feature toggles but they shouldn't change production rules" means permission tiering. Viewer for finance, editor for the owning team, approver for the team lead. + +--- + +## The framework: 14 considerations for sustainable feature flagging + +When designing or auditing feature flags, walk these 14 considerations: + +1. Type clarity. Release, experiment, operational, permission, or configuration. Pick one at creation; do not let it drift. +2. Naming. Typed prefix, owner prefix, semantic name. Avoid vague. +3. Lifecycle planning. Birth and death committed at creation. Removal date in metadata. +4. Targeting taxonomy. User, account, request, or time-based. Avoid volatile attributes. +5. Rule simplicity. AND, OR, NOT only. Three nested clauses means the taxonomy is wrong. +6. Rollout match. Strategy matches the risk profile. Percentage for low risk, cohort for medium, geo for compliance, time-based for coordinated launches. +7. Ramp discipline. One peak hour at each percentage step. No four-hour rollouts. +8. Stale flag cadence. Quarterly cleanup. One PR per removal. Make removal part of the launch checklist. +9. Permission tiering. Viewer / editor / approver / admin. Fewer admins than approvers, fewer approvers than editors. +10. Environment promotion. Dev to staging to production with review gates. Production rules are not authored in production. +11. Conflict audit. Two flags on the same surface = conflict. Detect via shared-key audit; coordinate cross-team via the experiment registry. +12. Performance budget. Bulk evaluation, caching, server-side SDKs for sensitive logic. 5 ms total budget for fifty flag checks. +13. Branch testing. Both code paths covered by tests. Transition behavior documented. +14. Observability. Every flag evaluation logged. Every rollout dashboarded. Errors correlated with flag value during incidents. + +--- + +## Reference files + +The following reference files extend this skill: + +- [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md): typed prefixes, owner prefixes, semantic naming patterns, and the migration plan for existing badly-named flags. +- [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md): birth-to-death checklist organized by lifecycle phase. +- [`references/flag-types-reference.md`](references/flag-types-reference.md): the five flag types in detail with worked examples and common pitfalls. +- [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md): quarterly cleanup process and the orphan-ownership pattern. +- [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md): common patterns and anti-patterns for targeting rules. +- [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md): percentage, cohort, geo, time-based, and combination strategies with a worked example. +- [`references/governance-and-permissions.md`](references/governance-and-permissions.md): permission tiers, environment promotion, approval workflows, and emergency override. + +--- + +## Closing: when to remove a flag + +The default disposition for any flag should be removal. Flags that earn permanent residence in the codebase (operational kill switches, permission flags tied to billing, configuration flags tied to contracts) are exceptions, not norms. Most release and experiment flags should be removed within 30 days of the launch decision. + +The cost of leaving them is real: every dead flag is two code paths to maintain, two test suites to keep green, and one more line of mental overhead for the engineer who reads the file next quarter. The cost compounds across hundreds of flags. + +The discipline of removing them is the discipline of caring about the codebase you will work in next quarter. It is the same discipline behind cleaning up after a deploy, removing dead imports, and writing a post-mortem within a week of the incident. None of it ships features today. All of it makes shipping features tomorrow easier. + +For platform-specific patterns (which platform handles which flag type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the experiment-design layer above this skill (hypothesis discipline, sample size, decision-making), see the `experiment-design` skill. For the analytical layer below this skill (variance reduction, sequential testing math, Bayesian alternatives), see the `experimentation-analytics` skill. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md b/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md new file mode 100644 index 0000000..619adb8 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-lifecycle-checklist.md @@ -0,0 +1,119 @@ +# Flag lifecycle checklist + +A phase-by-phase checklist for the operational discipline of a flag from creation through removal. Run through the phase the flag is currently in; do not skip ahead. + +--- + +## Phase 1: Birth (creation) + +Before merging the PR that introduces a new flag: + +- [ ] Type committed. Release, experiment, operational, permission, or configuration. Pick one. +- [ ] Name follows the convention from `flag-naming-conventions.md`. +- [ ] Owner assigned. The team or person responsible for the flag's lifecycle. +- [ ] Target removal date set in metadata (release flags: 30-60 days; experiment flags: end of test plus 14 days; operational/permission/configuration flags: "long-lived, review annually"). +- [ ] Rollout plan attached. Percentage, cohort, geo, or time-based; abort criteria defined. +- [ ] Monitoring approach attached. What metric is being watched? What alert fires if the rollout breaks something? +- [ ] Both code branches tested. The disabled branch (existing production) and the enabled branch (new code). +- [ ] Default value confirmed off in production. +- [ ] Removal sub-ticket created and scheduled (release/experiment flags only). + +If any item is no, do not merge. + +--- + +## Phase 2: Adolescence (pre-launch) + +The feature behind the flag is being built in dev and staging. The flag remains off in production. + +- [ ] Feature complete in code, both branches tested. +- [ ] QA sign-off on enabled branch. +- [ ] Staging rule mirrors planned production rule (does not have to match exactly; should be representative). +- [ ] Telemetry confirmed. Logs include flag value as a contextual field. Dashboards exist for the metrics the rollout will watch. +- [ ] Rollout plan reviewed by approver. + +--- + +## Phase 3: Launch (rollout) + +Production rollout begins. Each percentage step has its own gate. + +For each step (typical: 1% → 10% → 50% → 100%): + +- [ ] Apply rule change via platform UI, MCP, or API. +- [ ] Confirm rule applied. Flag evaluation rate matches expected percentage. +- [ ] Watch primary success metric, error rate, latency p95 for at least one peak hour. +- [ ] If clean, advance to next step. +- [ ] If degraded, hold or roll back. Document what was observed. + +At 100%: + +- [ ] Hold for 7 days at 100% before declaring launch complete. +- [ ] Confirm metrics stable across the full holding period. +- [ ] Schedule the 30-day review (calendar reminder for the owner). + +--- + +## Phase 4: Maturity (post-launch) + +Flag is at 100% rollout. Both code paths still exist. The new path is production. + +- [ ] 30-day review: any regressions detected? Any rollbacks needed? +- [ ] Confirm the removal sub-ticket created at birth still exists and is scheduled. +- [ ] Confirm no unexpected dependencies on the flag from other code paths. + +If the flag is operational, permission, or configuration, the lifecycle ends here. The flag is permanent. + +If the flag is release or experiment, proceed to Phase 5. + +--- + +## Phase 5: Death (removal) + +The flag has reached its target removal date or its purpose is complete. + +Code-side: + +- [ ] Open a single PR that removes the flag's gating logic. One flag per PR. +- [ ] Delete the disabled branch (the old code path). Keep only the enabled branch. +- [ ] Delete tests that targeted the disabled branch. +- [ ] Update any documentation that referenced the flag. +- [ ] Confirm CI passes; tests still cover the new (now permanent) code path. +- [ ] Merge the PR. + +Platform-side (after PR merges): + +- [ ] Confirm the flag has zero evaluations in the platform's dashboard for at least 24 hours. +- [ ] Archive or delete the flag from the platform. +- [ ] Audit log entry confirms deletion with actor, timestamp, reason. + +Documentation: + +- [ ] Close the original removal sub-ticket created at birth. +- [ ] Update any team-level flag inventory the team maintains. + +--- + +## Phase 6: Audit (quarterly) + +Even with the discipline above, some flags will slip through. The quarterly audit catches them. + +- [ ] Generate stale flag report from the platform (>30 days unevaluated for release/experiment, >90 days for operational). +- [ ] Triage in a meeting: keep, remove, or investigate per flag. +- [ ] Open removal PRs (one per flag) for the "remove" pile. +- [ ] Investigate the "investigate" pile; usually the answer is remove or rename. + +For the full audit pattern, see `stale-flag-cleanup-playbook.md`. + +--- + +## Common slips + +The phases above describe the disciplined path. Common slips: + +- Birth without removal date. Fix: require the removal date as part of the flag-creation form or PR template. +- Launch without monitoring. Fix: the rollout plan review at end of Phase 2 catches this. +- Maturity skipped (rolled to 100%, never reviewed). Fix: the 30-day review reminder is in the launch ticket. +- Death skipped (flag forgotten). Fix: the quarterly audit catches it. + +The slips compound. A skipped death today is one more flag to clean up at quarter end. A hundred skipped deaths over a year is the productivity tax described in `stale-flag-cleanup-playbook.md`. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md b/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md new file mode 100644 index 0000000..c5daa6d --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-naming-conventions.md @@ -0,0 +1,128 @@ +# Flag naming conventions + +A flag name encodes type, owner, and purpose. Encoding makes flag lists readable at month nine and lets the cleanup playbook tell what is safe to remove. This reference documents the conventions, shows worked examples, and provides the migration plan for existing badly-named flags. + +--- + +## The format + +`<type>_<owner>_<semantic_name>_<version_or_date>` + +Each segment is mandatory for new flags except the version/date suffix, which is recommended but optional for short-lived release flags. + +--- + +## Typed prefixes + +\| Prefix \| Type \| Lifetime \| Example \| +\|---\|---\|---\|---\| +\| `release_` \| Release flag \| Days to weeks \| `release_checkout_redesign_2026q2` \| +\| `exp_` \| Experiment flag \| 1-6 weeks \| `exp_billing_pricing_v2` \| +\| `ops_` \| Operational flag \| Long-lived \| `ops_search_circuit_breaker` \| +\| `perm_` \| Permission flag \| Long-lived \| `perm_enterprise_audit_log` \| +\| `cfg_` \| Configuration flag \| Long-lived \| `cfg_tenant_acme_custom_dashboard` \| + +Pick one prefix style organization-wide. Mixing `release_` with `release-` produces typo bugs that bite during 3 AM rollbacks. + +--- + +## Owner prefix + +The owner segment is the team or component that owns the code behind the flag. It does not have to be the team that created the flag. + +Examples: +- `checkout` for the checkout team +- `billing` for the billing team +- `search` for the search team +- `growth` for the growth team +- `infra` for platform/SRE work + +Organizations with many small teams may use a two-segment owner like `growth_signup` or `infra_db_failover`. Organizations with a single product team may use a component-level owner like `pricing`, `dashboard`, `api`. + +--- + +## Semantic name + +The semantic name describes what the flag controls. It should read naturally to someone who has not seen the flag before. + +Good semantic names: +- `redesign` (the team is redesigning a surface) +- `ml_recommendations` (the feature is ML-driven recommendations) +- `circuit_breaker` (the flag is a circuit breaker, an operational kill switch) +- `audit_log` (the feature behind the flag is an audit log) +- `single_step_billing` (a specific UX pattern the flag controls) + +Bad semantic names: +- `new_feature` (which feature?) +- `temp_toggle` (temporary for what?) +- `test_flag` (for testing what?) +- `pricing_update_v3` (which version was v3? was there a v2?) + +--- + +## Version or date suffix + +For experiment flags and release flags that may iterate, include a version or date suffix so old and new variants are distinguishable. + +- `release_checkout_redesign_2026q2`: quarter-stamped release +- `exp_pricing_test_v2`: second iteration of a pricing test +- `release_signup_form_v3_2026_05`: third iteration, May 2026 + +Operational, permission, and configuration flags usually do not need a version suffix; they are stable infrastructure. + +--- + +## Worked examples (good) + +``` +release_checkout_redesign_2026q2 +release_signup_passwordless_2026_06 +exp_billing_pricing_v2 +exp_homepage_hero_copy_test_v1 +ops_search_circuit_breaker +ops_db_failover_manual_override +perm_enterprise_audit_log +perm_eu_data_residency +cfg_tenant_acme_custom_dashboard +cfg_white_label_partner_xyz +``` + +Each name says: what type of flag, who owns it, what it controls, and (where applicable) which iteration. + +--- + +## Worked examples (bad) + +``` +new_pricing // bad: no type, no owner, no version +temp_homepage_test // bad: "temp" promises removal that never happens +billing_flag_2 // bad: vague semantic, what does flag_2 do? +killswitch // bad: which feature does this kill? +enterprise_features // bad: ambiguous, is this permission or configuration? +beta_users_only // bad: targeting concept in the flag name; rule should target, not name +``` + +--- + +## Migration plan for badly-named flags + +If the existing platform has hundreds of badly-named flags, do not rename them all at once. The pattern is to rename on touch: + +1. Establish the convention. Document it; share with the team. +2. New flags follow the convention. No exceptions. +3. Existing flags get renamed when touched: when the rule changes, when the rollout advances, when ownership transfers, when removal is scheduled. +4. Quarterly cleanup includes a "rename batch" of the 5-10 worst-named flags, especially ones that are confusing during the cleanup itself. +5. After 6-12 months, the platform stabilizes on the convention. + +Bulk renames can be scripted via the platform's API, but renaming forces a code change in every place the flag key is referenced. Bundle renames with refactors, not as standalone PRs. + +--- + +## Anti-pattern: targeting in the name + +Do not put targeting concepts in the flag name. The flag name describes what the flag controls; the targeting rule describes who sees it. + +Bad: `enterprise_users_audit_log` (the "enterprise_users" is targeting) +Better: `perm_audit_log` (the flag is a permission flag for the audit log; the rule targets enterprise users) + +If the targeting rule changes (audit log opens up to all paid customers), the flag does not need to be renamed. The rule does the work. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md b/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md new file mode 100644 index 0000000..3b13fdc --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-rollout-strategies.md @@ -0,0 +1,150 @@ +# Flag rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile of the change. The five patterns below cover most cases; combine them when needed. + +--- + +## Percentage rollout + +The default for release flags. The flag advances through fixed percentage steps with a monitoring gate at each step. + +Typical sequence: + +\| Step \| Percentage \| Hold time \| +\|---\|---\|---\| +\| 1 \| 1% \| At least one peak hour \| +\| 2 \| 10% \| At least 24 hours \| +\| 3 \| 50% \| At least 48 hours \| +\| 4 \| 100% \| Hold for 7 days before declaring complete \| + +Hold times are minimums. If the metric being watched takes longer than 24 hours to stabilize (retention, downstream conversion), extend the holds accordingly. + +Abort criteria at each step: +- Error rate exceeds baseline by 10 percent. +- Latency p95 exceeds baseline by 20 percent. +- Primary success metric trends materially negative. +- Any P1 alert fires that traces back to the flag. + +If any abort criterion fires, hold or roll back. Do not advance. + +--- + +## Cohort rollout + +For risky launches where the blast radius matters. Each cohort is a named segment; the flag advances through cohorts in sequence. + +Typical sequence: + +1. Internal employees only. Bugs surface from the team that can fix them quickly. +2. Beta customers (opt-in). Engaged users who tolerate roughness in exchange for early access. +3. Free-tier customers. Larger population; risk to revenue is bounded because they are unpaid. +4. Paid customers, smaller plans first. Tier-by-tier escalation. +5. Paid customers, enterprise. Last; highest revenue impact, lowest tolerance for issues. + +Each cohort hold is at least one full business cycle (5-7 days). Compress only with strong upstream confidence (the change has already shipped through internal and beta with zero issues). + +Abort criteria same as percentage rollout, plus: support ticket volume from the cohort exceeds baseline. + +--- + +## Geo-staged rollout + +Default for compliance-sensitive features (data residency, region-specific regulations, locale-specific UX). One region at a time. + +Typical sequence: + +1. Single test region (often the team's home region; US-East or EU-West for most products). +2. English-speaking regions (US, CA, UK, AU, NZ). +3. Western Europe (DE, FR, ES, IT, NL, etc.). +4. APAC (JP, SG, AU, etc.). +5. LATAM and remaining regions. + +Hold per region depends on the product. For compliance features, hold long enough to detect any regulatory complaint or support escalation; for UX features, one full business cycle suffices. + +Abort criteria same as cohort, plus: any region-specific regulatory escalation. Compliance issues are non-negotiable rollback triggers. + +--- + +## Time-based rollout + +Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment (a press release, a partner co-launch, a planned downtime window). + +Pattern: + +1. The flag has a `time > $LAUNCH_TIMESTAMP` condition. +2. Internal QA confirms the timestamp is correct in the platform UI. +3. The launch hour arrives; the flag flips automatically. +4. The team monitors the same metrics as a percentage rollout but at the full population from minute one. + +Watch the timezone. Coordinate the timestamp explicitly: midnight Eastern is not midnight UTC; "Friday at 9 AM" is ambiguous across timezones. Use UTC in the rule and let the platform UI display in the user's local time. + +Avoid time-based rollouts: +- On weekends, unless weekend on-call exists. +- On major holidays, unless the launch is the holiday itself (rare). +- Overlapping with other major launches or known marketing campaigns; the metrics get confounded. + +--- + +## Combination strategies + +The strategies above compose. Common combinations: + +Percentage within cohort. "Roll out to 50 percent of beta customers, then ramp to 100 percent of beta, then start the cohort rollout to free tier." Useful when the blast radius matters even within a single cohort. + +Geo within percentage. "Roll out to 1 percent of users in US-East only, then 10 percent of US-East, then expand to other regions." Useful when geo isolation is important for incident containment. + +Time-based gated by cohort. "At time T, the flag turns on, but only for the beta cohort. The rollout to other cohorts happens later." Useful when the public announcement matters but the broader rollout should still be cautious. + +--- + +## Worked example: checkout redesign launch + +A team is launching a redesigned checkout flow. The change is high-risk (revenue surface, complex code, third-party payment integrations). + +Rollout plan: + +\| Day \| Stage \| Rule \| Hold \| Watch \| +\|---\|---\|---\|---\|---\| +\| 1 \| Internal \| `user.email_domain == "yourcompany.com"` \| 24 hours \| Bug reports from team \| +\| 2-4 \| Internal extended \| Same \| 72 hours \| Conversion, error rate \| +\| 5 \| Beta \| `user.beta_opted_in == true` \| 24 hours \| Conversion, error rate, support \| +\| 6-8 \| Beta extended \| Same \| 72 hours \| Conversion, primary funnel metrics \| +\| 9 \| Production 1% \| `rollout 1% of all users` \| 24 hours (must include peak) \| Full alerting \| +\| 10 \| Production 10% \| `rollout 10%` \| 24 hours \| Full alerting \| +\| 11 \| Production 50% \| `rollout 50%` \| 48 hours \| Full alerting \| +\| 13 \| Production 100% \| `rollout 100%` \| 7 days \| Full alerting \| +\| 20 \| Launch declared complete \| Same rule \| n/a \| 30-day review scheduled \| +\| 50 \| 30-day review \| Same rule \| n/a \| Decide on flag removal \| +\| 60-80 \| Flag removal PR \| Code path consolidated \| n/a \| n/a \| + +Abort criteria at every stage: +- Checkout completion rate drops more than 1 percent absolute. +- Payment failure rate increases at all. +- Error rate (any 5xx) increases by more than 10 percent. +- Support ticket volume on checkout increases. + +Total time from launch to flag-removed: about 80 days. The work to remove the flag at day 60-80 is part of the launch plan, not an afterthought. + +--- + +## When to compress + +The cadences above are conservative defaults. Compress only with strong upstream confidence: + +- The change has already shipped behind a feature flag for an extended period (release-as-experiment-as-release). +- The blast radius is genuinely small (an internal admin tool, a low-traffic settings page). +- A previous similar launch went through the full cadence with zero issues, and the new launch is structurally analogous. + +Even with strong confidence, do not skip the production 1 percent stage. The first 1 percent in production is the only stage where production-specific issues (real user agents, real network conditions, real account distributions) surface. + +--- + +## When to extend + +Extend the cadence when: + +- The metric being watched is slow (retention measured at day-7 or day-30 cannot be observed at a 24-hour hold). +- The change involves a third party (payment processor, email provider, analytics vendor) whose behavior under load is unknown. +- The team is new to flag rollouts and benefits from the slower pace as a learning exercise. + +Extension is cheaper than incident response. Conservative defaults are correct defaults. diff --git a/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md b/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md new file mode 100644 index 0000000..f0a1325 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/flag-types-reference.md @@ -0,0 +1,83 @@ +# Flag types reference + +The five flag types in detail. Mixing them in one flag is the most common source of flag mess; commit at creation and do not let the type drift. + +--- + +## Release flag + +Definition. A flag that gates a new feature so the code can ship to production while disabled. The team toggles it on for a percentage, ramps to 100, then removes the flag. + +Lifetime. Days to weeks. Most release flags should be removed within 30 days of reaching 100 percent rollout. + +Lifecycle pattern. Birth (PR adds gated code), adolescence (testing in dev/staging), launch (gradual percentage ramp in production), maturity (100 percent, monitor for 30 days), death (removal PR consolidates code paths). + +Worked example. `release_checkout_redesign_2026q2` gates a new checkout flow. Created when the new flow PR merges. Toggled on for 1 percent of users on day 1; ramps to 10 percent on day 2, 50 percent on day 4, 100 percent on day 6. Removed on day 36 after the 30-day review confirms no regressions. + +Common pitfalls. Skipping the removal step (the most common). Conflating with an experiment flag (the team wants to A/B test the rollout instead of just ramping it; that is a different type). Leaving the flag at 50 percent forever because the team is "watching" it (either ramp to 100 or roll back; do not park). + +--- + +## Experiment flag + +Definition. A flag that randomly assigns users to variants for an A/B or multivariate test. The platform tracks conversion per variant; the team decides which variant wins, then ships the winner. + +Lifetime. One to six weeks. Tied to the duration of the test. + +Lifecycle pattern. Birth (PR adds the variants behind the flag), adolescence (canary in dev/staging), launch (test runs at the full target audience), maturity (test ends, decision made), death (winning variant code consolidated; flag removed). + +Worked example. `exp_billing_pricing_v2` tests two pricing page layouts. 50/50 split. Test runs for 21 days, hits the pre-committed sample size. Variant B wins. The PR removes the flag and the variant A code path; only variant B remains in production. + +Common pitfalls. Letting the experiment flag persist after the decision (the most common). Treating an inconclusive result as "let's keep the test running" instead of "kill or redesign." Mixing experiment with release: the team uses an experiment flag to gradually ramp a feature; if it is a ramp, it is a release flag. + +--- + +## Operational flag + +Definition. A kill switch or circuit breaker. Lets ops disable a misbehaving feature without a code redeploy. The flag is on by default in production; flipped off only during incidents. + +Lifetime. Long-lived. Often years. Removed only when the underlying feature is removed. + +Lifecycle pattern. Birth (PR adds the kill switch around a risk surface), maturity (the flag sits at "on" indefinitely), occasional use during incidents. + +Worked example. `ops_search_circuit_breaker` wraps the search service. If the search service starts returning errors at high rates during a 3 AM incident, on-call flips the flag off, and the search bar shows a graceful fallback message until the underlying issue is fixed. + +Common pitfalls. No incident drill (the first time the kill switch is used should not be at 3 AM). Wrapping logic that does not need a kill switch (every feature does not need one; pick the high-risk surfaces). Conflating with a release flag (the team uses the kill switch as a rollout control; if it is a ramp, the new code path needs its own release flag, and the kill switch wraps the larger feature). + +--- + +## Permission flag + +Definition. Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. The flag is the access control mechanism. + +Lifetime. Long-lived. Tied to the business model. + +Lifecycle pattern. Birth (PR adds the gate around a paid feature), maturity (the flag stays in production indefinitely), evolution (the rule changes as plans evolve, but the flag remains). + +Worked example. `perm_enterprise_audit_log` controls access to the audit log feature. Only accounts on the enterprise plan see it. When the plan structure changes (audit log opens up to the team plan too), the rule changes; the flag remains. + +Common pitfalls. Putting permission logic in code instead of in the flag (so the team has to deploy when plans change). Conflating with configuration: permission flags govern access by plan/role; configuration flags govern behavior per tenant contract. Permission flags use the same evaluation surface as release flags but the lifecycle is fundamentally different. + +--- + +## Configuration flag + +Definition. Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account, partner integrations. + +Lifetime. Long-lived. Tied to the contract or regulatory requirement. + +Lifecycle pattern. Birth (PR adds the configuration switch for a specific tenant or partner), maturity (the flag remains as long as the contract is active), evolution (the rule changes as new tenants come on or existing ones renegotiate). + +Worked example. `cfg_tenant_acme_custom_dashboard` enables a custom dashboard for Acme Corp because their contract specifies it. The flag's targeting rule is `account.tenant_id == "acme"`. The flag remains in production as long as Acme is a customer. + +Common pitfalls. Configuration sprawl: every tenant request becomes a new flag, the platform has hundreds, no one can audit. Mitigation: use segments and tenant-attribute targeting on a smaller set of feature flags rather than per-tenant flags. Conflating with permission: configuration governs custom behavior per tenant contract; permission governs access by plan tier. + +--- + +## Anti-pattern: type drift + +A flag created as a release flag gets repurposed as an experiment, then later as a permission gate. The name still says `release_`. The targeting rule is now multi-purpose. The lifecycle expectation is unclear. Removing the flag breaks something somewhere. + +The fix is to refuse type drift. When the purpose changes, create a new flag of the new type and migrate the rule. The original flag is removed once nothing depends on it. This is more work than just changing the rule on the existing flag, but it preserves the type-clarity discipline. + +The recovery for an existing type-drifted flag: rename to one of the five types, document the current actual purpose, and treat the flag as that type from now on. The original mixed history is grandfathered; the going-forward behavior is single-typed. diff --git a/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md b/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md new file mode 100644 index 0000000..a56582d --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/governance-and-permissions.md @@ -0,0 +1,115 @@ +# Governance and permissions + +Different roles need different access to the flag system. Engineering needs broad ability to create flags. Product needs to author targeting rules in dev and staging. Production targeting changes deserve a smaller approver pool. The pattern below balances access with audit. + +--- + +## Permission tiers + +Four tiers cover most cases. Not every organization needs all four. + +\| Tier \| Scope \| Typical members \| +\|---\|---\|---\| +\| Viewer \| Read-only across all environments \| Most of engineering, product, support, finance, executive \| +\| Editor \| Create and modify flags in dev and staging \| The team that owns the flag's surface \| +\| Approver \| Promote flag changes from staging to production \| Team lead, on-call engineer, designated approvers \| +\| Admin \| Delete flags, modify permissions, access audit logs \| Platform team plus a backup \| + +Smaller organizations may collapse Editor and Approver into a single "Engineer" tier. Larger organizations may add a fifth tier ("Owner") for cross-cutting governance. + +--- + +## Environment-based permissions + +Permissions vary by environment. The same person can have Editor in dev/staging and Viewer in production. The environment-based scope is the second axis after role. + +\| Environment \| Default access \| Notes \| +\|---\|---\|---\| +\| Dev \| Editor for engineering, Viewer for everyone else \| Sandbox; mistakes are cheap \| +\| Staging \| Editor for the owning team, Viewer for everyone else \| Pre-production; mistakes are detectable \| +\| Production \| Approver for the owning team, Viewer for everyone else \| Live; mistakes are expensive \| + +Production changes go through review like deploys. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review. The rule does not silently appear in production because someone clicked a button. + +--- + +## Approval workflow + +For production-impacting changes: + +1. Editor authors the change in staging. +2. Editor tests the change in staging (the rule applies, the metric moves as expected). +3. Editor opens a change request in the platform (most platforms have a built-in change-request workflow; if not, a Slack channel with a bot suffices). +4. The request includes: rule diff, rollout plan, abort criteria, link to relevant ticket/PR, link to staging test results. +5. An approver reviews. If clean, applies. If not, comments and the editor revises. +6. The change applies in production with the audit trail attached. + +For low-risk operational changes (a kill switch flip during an incident), the workflow can be compressed: the approver applies directly without a separate change request, and the audit trail captures the change with the incident reference. Document this exception explicitly so emergencies do not produce unexplained audit entries. + +--- + +## Audit trail + +Every flag change must be logged with: + +- Actor (who applied it, by user identity). +- Timestamp. +- Before-state and after-state (the rule diff). +- Reason (free-text or linked ticket). + +Most platforms do this automatically. Configure the audit log to also write to the central log aggregator (Datadog, Splunk, ELK, the team's choice). The platform's audit log is fine for routine inspection; the centralized log is where investigation happens during incidents. + +Audit retention: at least one year. Two years for organizations with regulatory obligations. + +--- + +## Emergency override + +An emergency override is the path that lets on-call flip a kill switch at 3 AM without going through the standard approval workflow. + +The pattern: + +1. A small group has Approver permission on the operational kill switches specifically. +2. The group includes the on-call rotation; on-call inherits Approver for the duration of their shift. +3. Emergency overrides apply with the standard audit trail; the reason field includes the incident reference. +4. After the incident, the override is reviewed in the post-mortem. + +Test the override in incident drills. The first time on-call flips a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. If the drill reveals the override path is broken (the on-call's account does not have the right permission, the platform's UI is confusing, the mobile app does not let you change rules), fix it immediately. + +--- + +## Service accounts + +Automation needs flag access too. CI/CD pipelines may flip flags as part of deploys; monitoring systems may flip kill switches based on alerts; orchestration agents may modify flags via MCP. + +Service accounts: + +- Each automation has its own service account with a clearly named identity (`ci_pipeline`, `monitoring_alert_bot`, `agent_orchestrator`). +- Service accounts have the minimum permission needed for their scope. The CI account that flips release flags after deploy does not need permission to delete flags. +- Service account credentials rotate on a schedule (90 days for production access). +- Audit log entries from service accounts are clearly marked so they can be filtered separately from human changes. + +Mixing human and service-account credentials in the same identity is the most common audit-trail mistake. The investigation question "who changed this flag at 2 AM" should not have the answer "an automation, but we are not sure which one because it was authenticated as a human admin." + +--- + +## The "production console freeze" anti-pattern + +Some organizations respond to a production flag incident by tightening access so much that every flag change requires a ticket, a meeting, and a 24-hour delay. The result is over-correction: routine flag changes get queued, the team starts authoring rules in code instead of in the platform, and the platform stops being load-bearing. + +The fix is not to freeze access. The fix is to: + +- Tighten the approval workflow (require change requests for production). +- Tighten the audit log (capture every change with reason). +- Tighten the emergency override (drill it). +- Loosen the day-to-day workflow so editors can do their jobs without paperwork. + +Bureaucracy substitutes for trust. Trust is built via the audit log and the approval workflow. Once the audit log is solid, day-to-day editing can stay fast. + +--- + +## Cross-team coordination + +When a flag's surface overlaps with another team's work, coordinate before the change. The experiment registry pattern from the `experiment-design` skill applies here too: maintain a shared list (in the platform, in a wiki, in a shared doc) of flags currently being modified or rolled out per surface. Before launching a flag rollout, check the registry for conflicts. + +Cross-team coordination does not have to be heavy. A 5-minute Slack check ("we're rolling out flag X on the checkout flow tomorrow at 1 PM, anyone working on adjacent flags?") is enough for most cases. The cost of skipping the check is the cross-team conflict scenario from the [SKILL.md](../SKILL.md), where two flags interact and produce broken UI. diff --git a/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md b/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md new file mode 100644 index 0000000..a4e2670 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/stale-flag-cleanup-playbook.md @@ -0,0 +1,116 @@ +# Stale flag cleanup playbook + +A quarterly cadence for keeping the flag inventory healthy. Without it, dead flags compound: every quarter adds 20-50 release/experiment flags that never got removed, and after two years the platform has hundreds of dead entries that nobody can confidently delete. + +The playbook is mechanical. Run it every quarter, the same way. Resist the urge to skip a quarter because the platform "looks fine." + +--- + +## What counts as stale + +\| Flag type \| Stale threshold \| +\|---\|---\| +\| Release \| 30 days without evaluation \| +\| Experiment \| 30 days without evaluation \| +\| Operational \| 90 days without evaluation \| +\| Permission \| Annual review; not "stale" by evaluation count \| +\| Configuration \| Annual review; tied to contract status \| + +Most platforms expose a "stale flag" report or a "last evaluated" timestamp per flag. If yours does not, the SDK can be configured to emit evaluation events to an analytics destination, and the analytics database becomes the source of truth. + +--- + +## Quarterly process + +### Step 1: Generate the report + +Pull the stale flag list from the platform. Filter by type-specific threshold above. Output: a list of flags with last-evaluation timestamp, owner, type, current rule. + +### Step 2: Owner triage + +For each flag in the list, route to the owner. The owner has three options per flag: + +- Remove. The flag is dead. Open a code-side removal PR. +- Keep. The flag is still load-bearing for a real reason (operational kill switch that has not fired in 90 days but should remain; permission flag for a feature whose rule is being audited annually). Document the reason; remove from this quarter's list. +- Investigate. The owner does not know why the flag exists or what it controls. Spawn a sub-task to investigate; the flag stays in next quarter's list. + +If a flag has no owner (the original owner left, ownership was never assigned, the flag predates the convention), rotate to the platform/SRE team for a forced decision in step 3. + +### Step 3: Triage meeting + +A 30-minute meeting per quarter. Attendees: representative from each team that owns flags, the platform/SRE team, the engineering lead. + +Walk the list. For each flag: + +- Confirm the owner's recommendation. +- For "investigate" flags, decide a deadline: investigation completes by next month or the flag is force-removed. +- For orphan flags (no owner, force-routed to platform), the platform team makes the call: remove if there is no evidence of active use, keep with documentation if there is. + +The meeting produces three artifacts: a remove list, a keep list with reasons, an investigate list with deadlines. + +### Step 4: Removal PRs + +One PR per flag. Bundle is tempting; resist it. One-flag-per-PR has three advantages: + +1. The reviewer can confirm the flag is genuinely dead by inspecting only the removed code paths. +2. If a flag was not actually dead (a code path uses it that the search missed), the rollback is a single revert. +3. The PR title and description reference the specific flag, which produces a clean audit trail. + +Each PR: + +- Removes the flag's evaluation calls from code. +- Consolidates the gated branches: usually keeps the "on" branch as permanent code and deletes the "off" branch. +- Removes any tests that targeted only the removed branch. +- Updates documentation that referenced the flag. + +### Step 5: Platform deletion + +After the removal PR merges and ships: + +- Wait 24 hours for the new code to fully roll out. +- Confirm the platform shows zero evaluations of the flag for the full 24-hour window. +- Archive or delete the flag from the platform. +- Audit log entry confirms deletion with actor, timestamp, reason ("quarterly cleanup, removal PR #NNNN"). + +### Step 6: Verification + +A week after platform deletion: + +- Spot-check the codebase for any remaining references to the flag's key (string-grep). Should be zero. +- Spot-check the platform for the flag's reappearance (sometimes platforms restore archived flags via API automation; rare but worth checking). + +--- + +## Orphan flags + +Orphan flags (no owner) are the hardest case. The original owner left the company, the team that owned the area dissolved, the flag predates the ownership convention. + +The pattern: + +1. Default ownership routes to the platform/SRE team. +2. The platform team asks: "Is this flag's targeting rule consistent with documented product behavior? Would removing it change observable behavior for any user?" +3. If no observable change, remove. If yes, escalate to the team most plausibly impacted. +4. If no team can be identified and no observable change is detectable, the flag is a candidate for removal in the next quarterly meeting; document the orphan status and remove on a 60-day delay so any silent dependency can be discovered. + +The 60-day delay is a hedge against unknown dependencies. In most cases, no one notices and the flag is safely removed. In the rare cases where a forgotten cron job or a downstream service was depending on the flag, the issue surfaces during the delay window. + +--- + +## Tooling + +Most platforms provide some automation: + +- LaunchDarkly: Code References finds usages in the codebase, flags candidates for removal. +- Statsig: Stale Gates report. +- GrowthBook: stale flag dashboard. +- Flagsmith: change request workflow integrates removal with governance. + +The automation reduces manual work but does not replace the triage meeting. The meeting is where humans make the keep/remove decision, which is the part automation cannot do. + +--- + +## Make removal part of the launch checklist + +The most important pattern is upstream: make flag removal part of the launch checklist, not a separate quarterly effort. When a release flag is created, the launch ticket has a sub-ticket scheduled 30 days out: "Remove flag X." When the launch goes well and the flag reaches 100 percent, the sub-ticket gets done as part of post-launch hygiene. + +Quarterly cleanup is the safety net for everything that slips past the upstream discipline. The discipline reduces the safety-net workload from "300 dead flags" to "5 dead flags," which is the difference between a 30-minute triage meeting and a multi-day project. diff --git a/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md b/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md new file mode 100644 index 0000000..edabbe0 --- /dev/null +++ b/dist/pi/.agents/skills/feature-flagging/references/targeting-rule-patterns.md @@ -0,0 +1,183 @@ +# Targeting rule patterns + +Common patterns and anti-patterns for flag targeting rules. The patterns work; the anti-patterns produce flag mess that takes quarters to unwind. + +--- + +## Pattern: percentage rollout + +Default: flag off (0 percent). Override: flag on for a percentage of the user population. + +``` +Default rule: off +Override: rollout 10% of all users +``` + +The platform handles the bucketing (usually a stable hash on user ID, so the same user gets the same value across requests). Use this for release flags during ramps. + +Variation: percentage within a segment. `Default off; rollout 50% of users where account.tier == "enterprise"`. Useful when the rollout should reach only a subset of the population. + +--- + +## Pattern: internal-only + +Restrict the flag to internal employees first. The flag is on for `@yourcompany.com` emails; everyone else sees the disabled state. + +``` +Default rule: off +Override: on if user.email_domain == "yourcompany.com" +``` + +Use this for the first stage of a sensitive release. Internal users find bugs without external exposure. + +--- + +## Pattern: opt-in beta + +Users who have opted into beta features see the flag on. Implementation requires an opt-in mechanism somewhere in the product (settings page, signup flow, support request). + +``` +Default rule: off +Override: on if user.beta_opted_in == true +``` + +Use this for risky features that need engaged-user feedback. The opt-in is the consent mechanism; the flag is the access mechanism. + +--- + +## Pattern: cohort-based + +Target a named segment defined elsewhere in the platform. The segment captures the cohort logic so the flag rule stays simple. + +``` +Default rule: off +Override: on if user IN segment "early_access_2026q2" +``` + +Use this when the cohort is shared across multiple flags (the same set of "early access" users sees several features). The segment is the single source of truth; flags reference it. + +--- + +## Pattern: geo-staged + +Target users by region. The country or region attribute usually comes from the request (IP-based geolocation) or the account profile. + +``` +Default rule: off +Override: on if request.country IN ("US", "CA") +``` + +Use this for compliance launches (data residency regulations, region-specific UX). Stage the rollout: US first, then EU, then APAC. + +--- + +## Pattern: time-based scheduled flip + +The flag turns on at a specific time. Useful for marketing-coordinated launches. + +``` +Default rule: off +Override: on if time > "2026-06-01T12:00:00Z" +``` + +Watch the timezone. Avoid scheduling on weekends or holidays unless on-call coverage exists for the rollout window. + +--- + +## Pattern: composition (cohort within percentage) + +A percentage of a cohort. Useful when the rollout should be slow even within an opt-in group. + +``` +Default rule: off +Override: on if user.beta_opted_in == true AND rollout 25% of those users +``` + +Order matters: the percentage applies to the cohort, not the full population. The platform's rule editor usually makes this clear. + +--- + +## Anti-pattern: volatile-attribute targeting + +Targeting on attributes that change frequently produces user-experience whiplash. + +Bad: +``` +Override: on if user.last_login_date > "2026-04-01" +``` + +A user's last_login_date changes every time they log in. They see the treatment one day, the control the next. The experience flickers; conversion data is noise. + +Fix: target on stable attributes. Or, snapshot the attribute at a fixed point (`user.first_login_date_was_after_2026_04_01`) and use the snapshot. + +--- + +## Anti-pattern: deeply nested AND/OR + +If your rule has three levels of nesting, the taxonomy is wrong. + +Bad: +``` +Override: on if ( + (user.country == "US" AND user.signup_date > "2026-01-01") + OR + (account.tier == "enterprise" AND NOT user.churned) + OR + (user.beta_opted_in == true AND request.device == "mobile") +) +``` + +The intent is unclear, the rule is fragile, and reviewing it during incidents is slow. + +Fix: define a segment that captures the intent (e.g., "eligible_for_new_dashboard") and use the segment in the flag rule. Or split into multiple flags (one for the US/recent-signup case, one for the enterprise case, one for the mobile-beta case) and let the calling code combine them. + +--- + +## Anti-pattern: production rules drift from staging + +The team tests the flag in staging with rule X. The rule that ships in production is rule Y, written directly in the production console without re-testing in staging. + +Result: the staging tests do not predict production behavior. The first 1 percent rollout in production reveals the gap, and the team scrambles to align. + +Fix: rules go through environment promotion. Author in staging, test in staging, promote to production via the platform's promotion workflow. If the platform does not have promotion, copy the rule from staging to production via a documented process and confirm the rule is identical in both before flipping production on. + +--- + +## Anti-pattern: targeting in the flag name + +Bad: `flag_name = "enterprise_audit_log"` with rule `account.tier == "enterprise"`. + +When the rule changes (audit log opens up to team-tier accounts), the flag name lies. + +Fix: name the flag for what it controls (`perm_audit_log`), let the rule do the targeting work. The rule can change without renaming the flag. + +--- + +## Anti-pattern: kill switch with a complex rule + +A kill switch (operational flag) should have a simple rule: `on for everyone` or `off for everyone`. If your kill switch's rule is `on for everyone except a specific cohort with these conditions`, you are using an operational flag as a permission gate. + +Fix: use a permission flag for the per-cohort access; use a separate operational flag (`ops_feature_x_killswitch`) for the universal kill. The operational flag wraps the entire feature; the permission flag wraps the access to the feature. + +--- + +## Pattern: explicit ramp gate + +Some platforms let you tag a flag's rule with explicit "stages." The flag advances through stages on a button press, with each stage having its own rule. + +``` +Stage 1: rollout 1% +Stage 2: rollout 10% (advance from stage 1 manually) +Stage 3: rollout 50% (advance from stage 2 manually) +Stage 4: rollout 100% (advance from stage 3 manually) +``` + +Use this when the platform supports it. The explicit stages make rollout history readable: you can see when each stage advanced, by whom, with what observed metrics. + +--- + +## Composition rule of thumb + +If a flag's rule reads naturally to a non-engineer ("on for enterprise customers in the US"), the rule is simple enough. If the rule requires a five-minute explanation, it is too complex; refactor into segments or split into multiple flags. + +The rule is read more times than it is written. Optimize for readability. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md b/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md new file mode 100644 index 0000000..119e651 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/SKILL.md @@ -0,0 +1,340 @@ +--- +name: feature-launch-playbook +description: "The operational playbook for launching a feature well. Positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring with pre-defined rollback triggers, post-launch measurement against spec hypotheses, and the discipline that distinguishes shipping from releasing from actually launching. Triggers on launch plan, feature launch, launch checklist, ship vs release, rollout strategy, gradual rollout, sales enablement, support readiness, launch announcement, post-launch measurement, launch failure, declared victory too early. Also triggers when planning a launch (any size, any segment), auditing an existing launch process, fixing the we shipped it but the metric did not move problem, or building a launch checklist for the team." +category: product +catalog_summary: "The operational discipline of launching a feature well: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement" +display_order: 10 +--- + +# Feature Launch Playbook + +A veteran PM-leader's playbook for launching features well, not just shipping them. + +Most teams conflate shipping, releasing, and launching. Shipping means engineering work is complete. Releasing means users can access it, even if it is behind a flag at 1 percent. Launching is the discipline of positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement that turns "feature exists" into "feature lands." + +A feature that ships without launching costs you the same engineering investment but captures a fraction of the value. Sales does not know how to sell it. Support does not know how to help with it. Customers do not notice it. The metric you said you would move does not move because nobody knows the feature is there. + +This skill is the operational playbook. It assumes you have already written the spec (`pm-spec-writing`), prioritized it onto the roadmap (`roadmap-planning`), instrumented it (`product-analytics-setup`), and possibly tested it (`experiment-design`). The launch is the next discipline: how to actually get the feature in front of the right users, with the right context, in a way that lets you measure whether it worked. + +When to use this skill: planning a launch (any size, any segment), auditing an existing launch process, fixing the "we shipped it but the metric did not move" problem, or building a launch checklist for the team. + +--- + +## What this skill is for + +This skill spans the operational launch discipline. It composes with the rest of the Product skill suite. + +- `pm-spec-writing` defines the launch hypotheses; this skill validates them. +- `roadmap-planning` provides the launch context (what came before, what comes next). +- `product-analytics-setup` is the instrumentation prerequisite; without it you cannot measure the launch. +- `experiment-design` and `data-warehouse-experimentation` provide the methodology for testing whether the launch worked. +- `feature-flagging` provides the rollout infrastructure this skill depends on. + +This skill does not cover pricing decisions, brand campaigns, or full GTM strategy. Those need a marketing team partner; this is the PM operational playbook for the engineering and product side. + +The audience is broad: every PM ships features, every PM has launched poorly at least once, every PM benefits from a checklist that stops the worst failure modes from recurring. The voice is veteran PM-leader to PM. Specific, opinionated, honest about what discipline matters at what stage. + +--- + +## Ship vs release vs launch + +The keystone distinction. Three definitions. + +Shipping means engineering completes the work. Code is on production. No users can access it yet, or only internal users via a flag. The PR is merged and deployed. + +Releasing means users can access it. Could be 1 percent rollout, could be 100 percent. The feature is "live" in some technical sense. The flag is on for at least one user. + +Launching means positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement are all in flight. The feature has been introduced to the people who would benefit from it, with the context they need to use it. + +The pathology. PMs report "we shipped feature X" when what happened is engineering completed the work. The feature might be released to 1 percent of users with no announcement, no documentation, no sales enablement, no measurement plan. From a value-capture perspective, that is an unlaunched feature. + +The discipline. Use precise vocabulary. "Engineering shipped on Tuesday. We are releasing to 25 percent on Thursday. We are launching publicly next month." The vocabulary forces honest accounting of what has and has not happened. + +Most "feature failed" diagnoses turn out to be "feature was unlaunched." This skill is structured around the launch dimension because that is where most teams under-invest. + +--- + +## Launch tiers + +Not every feature needs the full playbook. Match the work to the feature. + +Tier 1 (full launch). Net-new product, major feature reshaping the product narrative, pricing change, breaking change. Full playbook: positioning, all comms channels, sales enablement, customer success briefing, dedicated post-launch measurement, executive announcement. + +Tier 2 (focused launch). Meaningful improvement that materially affects user value or competitive positioning. Subset of the playbook: in-app comms, blog post or release note, support readiness, rollout strategy, post-launch measurement. + +Tier 3 (release note). Incremental improvement, bug fix made positive, polish. Minimal: changelog entry, release note, light monitoring. + +The trap on either side. + +- Treating every release as Tier 1 produces comms fatigue. Customers tune out the announcement firehose; your real Tier 1 launches lose signal in the noise. +- Treating every release as Tier 3 produces unlaunched features. The feature ships, the metric does not move, the team concludes "users do not want this" when the actual cause is "users were not told." + +Match the tier to the feature. This skill primarily covers Tier 1 and Tier 2. Tier 3 is mostly the changelog discipline; the launch playbook applies but compressed to the changelog entry plus light monitoring. + +Detail in [`references/launch-tier-decision.md`](references/launch-tier-decision.md). + +--- + +## Pre-launch: positioning + +Positioning answers: who is this for, what problem does it solve, why now, and what is the user-visible promise. + +The positioning canvas. One page, filled out before any comms drafting. + +- Target user. Segment, role, jobs-to-be-done. Specific enough that a sales rep could describe the customer profile in one sentence. +- Problem it solves. Specifically, in user words. Not "we improve productivity"; instead "the customer support manager who needs to triage 200 tickets a day cannot tell which are urgent without opening each one." +- Current alternative. What users do today without this. The status quo is the real competition. +- User-visible promise. One sentence. The promise the user will hear when they encounter the feature in the wild. +- Proof points. Three to five specific capabilities or outcomes. Concrete, not adjectives. +- Anti-positioning. What this is NOT, what it does not try to do. Prevents over-promising. + +The most common positioning failure is a vague target user. "It is for PMs" is not a target. "It is for B2B SaaS PMs at companies with 50 to 500 customers who need to coordinate roadmap discussions across engineering and customer success" is a target. The specificity is what lets sales, marketing, and support speak the same language about who this is for. + +Detail in [`references/positioning-canvas.md`](references/positioning-canvas.md). + +--- + +## Pre-launch: internal alignment + +Stakeholders who need to know before launch. + +- Engineering leadership. Capacity for follow-ups, support escalations, post-launch fixes. +- Sales leadership. Revenue forecast updates, deal coaching, pipeline impact. +- Customer success leadership. Proactive customer notifications, deal saves at risk, expansion conversations. +- Marketing leadership. Paid spend coordination, blog calendar, social timing. +- Support leadership. Training, FAQ, escalation paths. +- Executive sponsor. Visibility, public messaging, investor or board reporting. + +The discipline. A single internal launch brief, distributed two to four weeks before launch (Tier 1) or one week before (Tier 2). The brief contains a one-page summary, an FAQ, a decision log of choices already made, and the launch calendar. The brief should answer "what do I need to do differently because of this launch." + +The most common internal alignment failure: launching without sales knowing. Sales finds out from a customer asking about it. Trust erodes for the next launch. The fix is the launch brief plus a sales-specific briefing one to two weeks before customer-facing launch. + +Detail in [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md). + +--- + +## Pre-launch: customer comms plan + +Channels and decision factors. + +- In-app. Highest reach for active users; right for product-internal features. Tooltips, banners, modals. +- Email (transactional or campaign). High reach across active and inactive users; right for material changes that affect existing workflows. +- Blog post. SEO plus lead gen plus narrative; right for Tier 1 launches with external story. +- Release notes. Discoverable, archived, queryable; right for every Tier 2 and above. Often the canonical reference customers find later. +- Social (LinkedIn, X, Bluesky). Reach beyond existing customers; right when launch has external narrative or competitive angle. +- Webinar or customer call. Depth for enterprise customers; right for Tier 1 with material customer impact. +- Sales-led briefing. High-touch for top accounts; right when launch affects pricing, contracts, or strategic positioning. + +For each channel: who drafts, who approves, what is the timing, what is the call to action. + +The comms calendar pattern. A single document with all channels and dates, distributed in the internal launch brief. Prevents the "blog post went out before sales got the briefing" failure. Ordering typically goes: sales briefing first, support training second, customer success outreach to top accounts third, public comms fourth. + +Detail in [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md). + +--- + +## Pre-launch: sales enablement (B2B) + +For B2B products, sales enablement is not optional for Tier 1 and most Tier 2 launches. The deliverables. + +- One-page battlecard. Positioning, target customer, top objections, proof points. Sales can read it in two minutes and pitch the feature in five. +- Demo script and recorded demo. A repeatable demo the rep can run with a customer; the recorded version is the fallback for reps who join after the launch. +- Pricing change documentation if applicable. Sales reps cannot answer pricing questions accurately without explicit guidance. +- Deal coaching guide. Which deals does this unblock, which does it complicate. Specific named accounts where appropriate. +- Internal training session live or recorded, with Q&A archived. Sales reps need the chance to ask questions before they take the feature to a customer. + +The "shadow launch" failure. Feature ships, sales hears about it from product team Slack, no battlecard, sales reps either ignore it or misrepresent it to customers. Customers churn because the feature was promised in a way that did not match reality. + +For B2C and PLG products, this section is mostly skipped. The user is the buyer; there is no sales motion. Note this explicitly so PMs in those contexts do not feel they are missing the discipline. + +Detail in [`references/sales-enablement-template.md`](references/sales-enablement-template.md). + +--- + +## Pre-launch: support readiness + +Support is often the first to encounter the failure modes of a new feature. They need. + +- Training live or recorded, with Q&A. The same content as the sales training adapted to support workflows. +- FAQ document covering known questions, known limitations, and known bugs at launch. The FAQ updates daily during the first week as new questions surface. +- Escalation path for issues that need engineering or PM. Named owners and turnaround time commitments. +- Monitoring access or a way to ask for it. Support reps should be able to verify whether a customer's issue is feature-specific. + +The discipline. The support team's confusion is the test customer's confusion. If support does not understand the feature, neither will customers. Train support before customer-facing launch comms go out. + +Detail in [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md). + +--- + +## Launch day: rollout strategy + +Four common patterns matched to feature type. + +All-at-once (big bang). Zero to 100 percent in a single deploy. Right for marketing-coordinated launches where the announcement IS the rollout. Risky for anything where bugs would affect a meaningful customer base. Use sparingly. + +Gradual percentage rollout. 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days, monitored at each step. Right for most feature launches; the default unless there is a reason to deviate. + +Flag-gated cohort rollout. Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Right for features with cohort-specific risk profiles. + +Phased launch (multi-week). Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Right for Tier 1 launches with high uncertainty about user reception. + +The decision framework. Feature blast radius times confidence in correctness times external commitments. + +- High blast radius plus low confidence plus no external commitment: phased. +- Low blast radius plus high confidence plus external launch date: all-at-once. +- The middle (most launches): gradual percentage rollout. + +Detail in [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md). + +--- + +## Launch day: monitoring + +Pre-launch, define what you will monitor and what alerts you. Common dimensions. + +- Error rates. Overall plus feature-specific. +- Latency. Overall plus feature-specific. +- Feature usage rate. People who SHOULD use it actually do. +- Funnel completion. Users complete the new flow. +- Support ticket volume. Especially feature-specific tags. +- Customer satisfaction signals. NPS comments, feedback widget mentions. + +Define the rollback trigger explicitly before launch. Examples. + +- "Error rate above 1 percent sustained for 5 minutes triggers rollback." +- "Support tickets mentioning the feature exceed 50 in the first hour triggers escalation." +- "Funnel completion drops below 50 percent of pre-launch baseline for any cohort triggers paused rollout." + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate; the rule fires automatically and the team executes the rollback. + +Detail in [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md). + +--- + +## Launch day: comms execution + +The comms calendar from the customer comms section executes on launch day. Each channel has a clear owner, a clear time, and a clear sequence. + +- In-app banner activates when rollout reaches X percent. +- Email sends after a 4-hour stability check. +- Blog post publishes at the time announced internally. +- Sales briefing happens one day before public comms. +- Support training happens one week before launch. + +The "comms misfire" failure. Blog post auto-publishes at the scheduled time, but the rollout was paused two hours earlier due to an issue. Customers click through to a feature that is behind a flag for them. They lose trust; the launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +--- + +## Post-launch: measurement against spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses about what the feature would change. The launch measurement plan validates or invalidates each. + +Four measurement dimensions. + +1. Adoption. Did the right users actually use it? The reach question. Is the feature visible to the target segment, and are they trying it. +2. Engagement. Did users who tried it come back? The stickiness question. First use is necessary but not sufficient. +3. Outcome. Did the metric the spec said this would move actually move? The effect question. The hypothesis the spec made. +4. Side effects. Did any other metric move that was not supposed to? The safety question. Sometimes the feature works but breaks something else. + +Time horizons. Most launches need two to four weeks of post-launch data for engagement signals, four to eight weeks for outcome signals. Do not declare success or failure too early. + +The "no measurement plan" failure. Feature ships; the team moves on; six months later nobody knows if it worked. The feature becomes maintenance debt; the team cannot decide whether to invest in it further. + +Detail in [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md). + +--- + +## Post-launch: iteration and follow-ups + +Within the first four weeks post-launch, expect. + +- Bug discoveries that did not surface in QA or limited rollout. +- Usability issues that did not surface in user research. +- Adoption gaps in cohorts you did not expect to under-adopt. +- Feature requests for adjacent capabilities. + +The discipline. Document every issue, triage weekly, prioritize fixes against the original measurement plan. + +If adoption is below target, the question is. Is it a marketing problem (users do not know about the feature)? A usability problem (users try the feature and bounce)? A value problem (users try the feature and do not see value)? A wrong-segment problem (the target was not who we thought)? + +Each diagnosis maps to a different fix. + +- Marketing problem: more comms, repeat comms, sales reactivation. +- Usability problem: design or onboarding fix. +- Value problem: feature redesign or repositioning. +- Wrong-segment problem: re-target the comms to a different audience. + +The "we declared victory" failure. The launch metric hits target in week 1 (often due to the launch announcement spike); the team moves on; the metric falls back to baseline by week 4. The launch was reported as successful but the feature did not actually land. + +The fix. Declare success or failure based on a stable post-launch trend, not the launch-week spike. Most launches need at least a four-week stable trend before the success or failure call is reliable. + +--- + +## Common failure modes + +Twelve patterns recur across feature launches. Detail in [`references/common-launch-failures.md`](references/common-launch-failures.md). + +- "We shipped it but nothing happened." Unlaunched. No comms plan, no internal alignment, no measurement. +- "Sales is confused and selling it wrong." No enablement. Battlecard, demo, training were skipped or rushed. +- "Support is overwhelmed." No training, no FAQ. Support is encountering the feature for the first time when customers ask. +- "We rolled out and immediately rolled back." No rollout strategy, no health check. The big-bang deploy hit production and broke. +- "The blog post went out but the feature is broken." Comms misfire. The comms were not gated on rollout health. +- "Adoption was great in week 1, now it is flat." Declared victory on the launch spike. The metric reverted to baseline. +- "We do not know if it worked." No measurement plan tied to spec hypotheses. +- "Customers say we did not tell them." Comms did not reach the right segments. Email went to active users only; inactive users were not notified. +- "Enterprise customers found out from their account manager three days late." No high-touch tier in comms. Top accounts deserve sales-led briefing before public comms. +- "Our metric moved but it was actually because of a different launch that week." No isolation. Cannot attribute the metric movement to this launch versus other concurrent changes. +- "We launched the wrong feature." Positioning unclear. Customers expected something different from what shipped; the gap between expectation and reality reads as a failed launch even though the feature works. +- "It worked but nobody knew about it internally." No internal alignment. Sales did not capitalize on the feature in deals; customer success did not save accounts that were churning over the gap this feature now closes. + +--- + +## The framework: 12 considerations for a real launch + +When planning a launch, walk these 12 considerations. Skipping any of them produces one of the failure modes above. + +1. Tier the launch. Tier 1, Tier 2, or Tier 3. Match the effort to the feature. +2. Position it. Target user, problem, promise, proof points, anti-positioning. +3. Align internally. Single launch brief, distributed two to four weeks before launch. +4. Plan customer comms. Channel mix, calendar, owners, gates. +5. Enable sales. Battlecard, demo, training, deal coaching (B2B only). +6. Ready support. Training, FAQ, escalation paths, monitoring access. +7. Pick a rollout strategy. All-at-once, gradual, flag-gated, or phased. +8. Define monitoring. Metrics, alerts, rollback triggers. Pre-defined, not in-the-moment. +9. Sequence comms execution. Gated on health checks. Never auto-fire if the rollout is paused. +10. Tie measurement to spec hypotheses. Adoption, engagement, outcome, side effects. +11. Iterate post-launch. Weekly triage. Distinguish marketing, usability, value, and segment problems. +12. Declare success or failure on a stable trend. Not the launch-week spike. + +The output of the framework is a launch plan document. The positioning canvas, the internal launch brief, the comms calendar, the rollout strategy with health-check gates, the monitoring spec with rollback triggers, and the post-launch measurement plan tied to the spec hypotheses. The plan is reviewed two weeks before launch; gaps are filled before the launch date. + +--- + +## Reference files + +- [`references/launch-tier-decision.md`](references/launch-tier-decision.md) - Tier 1, 2, 3 decision framework with worked examples. +- [`references/positioning-canvas.md`](references/positioning-canvas.md) - One-page positioning template with B2B SaaS, B2C, and developer feature examples. +- [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md) - Stakeholders, brief structure, distribution timing by tier. +- [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md) - Channels, calendar, owners, gates. +- [`references/sales-enablement-template.md`](references/sales-enablement-template.md) - Battlecard, demo, deal coaching, training (B2B). Skip note for B2C and PLG. +- [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md) - Training, FAQ, escalation, monitoring access. +- [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md) - Four patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. +- [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md) - Metrics dimensions, alert thresholds, pre-defined rollback triggers. +- [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md) - Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. +- [`references/common-launch-failures.md`](references/common-launch-failures.md) - Twelve failure patterns with diagnoses and fixes. + +--- + +## Closing: most failed launches are unlaunched + +When a feature "fails," the most common diagnosis is not that the feature was wrong. It is that the launch was incomplete. Sales did not know. Customers were not told. Support could not help. The metric did not move because the launch did not reach the people who would have moved it. + +Before declaring a feature failed, audit the launch against this playbook. Half the time the feature was fine; the launch never happened. + +The discipline of separating shipping from releasing from launching is the single most useful PM vocabulary upgrade. Use it explicitly. Use it in stand-ups, in roadmap reviews, in launch retrospectives. The team that uses precise language about what has happened catches unlaunched features before declaring them failed and reallocates the engineering investment toward features that would actually capture value. + +When in doubt about whether a launch is ready, ask: is the launch brief written and distributed? Has sales seen the battlecard? Does support have the FAQ? Is the rollout strategy chosen and the rollback trigger defined? Are the comms gated on a health check? Is the measurement plan tied to the spec hypotheses? + +If any of those answers is no, the launch is not ready. Delaying the launch by a week to close the gaps is cheaper than launching incomplete and capturing a fraction of the value the feature could have delivered. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md b/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md new file mode 100644 index 0000000..987206f --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/common-launch-failures.md @@ -0,0 +1,181 @@ +# Common launch failures + +Twelve patterns that recur across feature launches. For each: name, symptom, root cause, fix, prevention. Cross-references to other reference files. + +--- + +## 1. We shipped it but nothing happened + +Symptom. The team reports "we shipped feature X." Three weeks later, nobody is using it. The metric the spec said this would move has not moved. Internal stakeholders ask if the feature is live; nobody is sure. + +Root cause. Unlaunched. Engineering completed the work; the team did not execute the launch. No comms plan, no internal alignment, no measurement plan tied to spec hypotheses. + +Fix. Treat it as a re-launch. Audit against the playbook: positioning, internal alignment, customer comms, sales enablement, support readiness, measurement plan. Distribute the launch brief. Sequence comms. Re-measure at the four-week checkpoint. + +Prevention. The launch brief is the artifact that prevents this. Without a brief, the launch defaults to engineering completion plus silence. With a brief, the launch has a calendar, owners, and measurement. + +See: `internal-alignment-checklist.md`, `customer-comms-playbook.md`, `post-launch-measurement-framework.md`. + +--- + +## 2. Sales is confused and selling it wrong + +Symptom. Customers ask sales questions sales cannot answer. Reps over-promise capabilities the feature does not have. Customers churn because the feature was sold wrong. + +Root cause. No sales enablement. Battlecard, demo, training were skipped or rushed. Reps are improvising in front of customers. + +Fix. Pause the launch (pause public comms; let in-app and release notes continue). Run the sales enablement playbook in compressed form: write the battlecard, record the demo, hold the training. Resume public comms after sales is enabled. + +Prevention. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. Battlecard plus 30-minute training plus recorded demo. The investment is small; skipping it is the largest avoidable launch cost. + +See: `sales-enablement-template.md`. + +--- + +## 3. Support is overwhelmed + +Symptom. Support ticket volume doubles or triples on launch day. Tickets pile up. Customer wait times balloon. Support reps escalate everything to the PM. + +Root cause. No training, no FAQ, or both. Support is encountering the feature for the first time when customers ask about it. They cannot answer questions; they escalate; the queue grows. + +Fix. Emergency FAQ. PM and support lead spend 4 hours documenting every question that has come in. FAQ updates push to support immediately. Re-train if needed (a short refresher). + +Prevention. Support training one week before launch. FAQ written before launch, not during. Estimate support volume realistically; staff for elevated volume. + +See: `support-readiness-checklist.md`. + +--- + +## 4. We rolled out and immediately rolled back + +Symptom. Big-bang deploy hit production. Within minutes, error rate was up. The team rolled back. Customers experienced a broken feature for 30 minutes; some saw error states. + +Root cause. Wrong rollout strategy. All-at-once was used when gradual was the right pattern. + +Fix. Audit the rollback. What was the bug; what would have caught it earlier in a gradual rollout. Pre-mortem the next launch. + +Prevention. Default to gradual percentage rollout for most launches. Use all-at-once only when the marketing-coordinated launch makes it unavoidable, AND the team has high confidence in correctness, AND the blast radius is low. + +See: `rollout-strategy-patterns.md`. + +--- + +## 5. The blog post went out but the feature is broken + +Symptom. Blog post auto-published at the announced time. Rollout had been paused two hours earlier due to an issue. Customers click through; 75 percent of them do not have the feature; they report "broken" feature that is actually a paused rollout. + +Root cause. Comms not gated on rollout health. Auto-fire schedule executed regardless of rollout state. + +Fix. Pull or update the blog post. Communicate transparently: "We hit an issue in our rollout; the feature is paused while we resolve. Your account will get access once we resume." + +Prevention. Make external comms manually triggered, gated on health check. Auto-fire is convenient but brittle. + +See: `customer-comms-playbook.md`. + +--- + +## 6. Adoption was great in week 1, now it is flat + +Symptom. The launch announcement drove a spike of users trying the feature. By week 4, adoption has dropped back to near-baseline. The team had declared victory in week 1. + +Root cause. Declared victory on the launch spike. The metric reverted because the launch announcement was the only driver of usage; users tried the feature once but did not come back. + +Fix. Re-evaluate as if the launch is unfinished. Diagnose: was it an awareness problem (users forgot the feature exists), a usability problem (users tried and bounced), a value problem (users tried and did not see value), a wrong-segment problem (the audience was wrong). Iterate based on the diagnosis. + +Prevention. Declare success or failure on the stable post-launch trend, not the launch-week spike. Minimum measurement window is four weeks. + +See: `post-launch-measurement-framework.md`. + +--- + +## 7. We do not know if it worked + +Symptom. Six months after launch, the team cannot answer "did feature X work?" Nobody measured. The feature is now maintenance debt. + +Root cause. No measurement plan tied to spec hypotheses. The launch did not commit to specific metrics with specific decision rules. + +Fix. Retroactive measurement. Pull the data; compare to a pre-launch baseline (if one exists); compute the lift. The retroactive measurement is less rigorous than a planned one but better than nothing. + +Prevention. Every launch has a measurement plan. The plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +See: `post-launch-measurement-framework.md`. + +--- + +## 8. Customers say we did not tell them + +Symptom. A customer reaches out asking why nobody told them about a feature that has been live for two months. The customer was on the email list; the email was sent; the customer missed it. + +Root cause. Comms did not reach the right segments. Email went to active users only; inactive users were not notified. Or the email subject line was generic and customers archived without reading. + +Fix. Re-send to the cohort that missed it. Use a different channel (in-app banner, account-manager outreach for top accounts). Improve the discoverability for new visitors (pricing page mention, feature-tour highlight). + +Prevention. Channel-mix analysis. For each launch, plan which channels will reach which cohorts. Inactive users need a different reach plan than active users. + +See: `customer-comms-playbook.md`. + +--- + +## 9. Enterprise customers found out from their account manager three days late + +Symptom. Enterprise customer hears about a launch from their account manager three days after public comms went out. The customer is annoyed; their AM is embarrassed; trust erodes. + +Root cause. No high-touch tier in comms. Public comms hit before account managers had been briefed. + +Fix. Apologize to the affected customer. Brief their AM immediately with the full context. Adjust process for the next launch. + +Prevention. Sales-led briefing for top accounts before public comms. Account managers should know about the feature one to three days before customers do, with talking points for the customer conversation. + +See: `customer-comms-playbook.md`, `sales-enablement-template.md`. + +--- + +## 10. Metric moved but it was actually because of a different launch that week + +Symptom. Outcome metric is up 8 percent in the four weeks post-launch. Team celebrates. Then someone notices a different launch happened the same week, and a price test concluded, and a marketing campaign ran. The 8 percent cannot be attributed to this specific feature launch. + +Root cause. No isolation. Multiple changes hit production in the same window; effects are confounded; the team cannot tell which change drove which metric. + +Fix. Run a follow-up isolated test. Roll back the feature for a cohort; measure the gap. If the gap is large, the feature was driving the metric. If the gap is small, other concurrent changes were the driver. + +Prevention. Stagger launches. Major launches should not coincide with each other; at minimum two weeks of separation for measurement isolation. For experiments, use the warehouse-native experimentation framework to isolate. + +See: `data-warehouse-experimentation` skill. + +--- + +## 11. We launched the wrong feature + +Symptom. The launch goes out. Customers respond with "this is great but it does not solve the problem we asked you to solve." The feature works; it just was not what customers expected. + +Root cause. Positioning unclear. The customer expected something different from what shipped because the spec, the comms, or both implied a different scope. + +Fix. Re-position. Re-write the comms to match what the feature actually does. Acknowledge the gap to customers who feel misled. Plan a follow-up that addresses the original ask. + +Prevention. The positioning canvas plus anti-positioning section forces explicit definition of what the feature is and is not. Review the canvas with sales and customer success before launch; their pushback often catches the positioning gap. + +See: `positioning-canvas.md`. + +--- + +## 12. It worked but nobody knew about it internally + +Symptom. The metric moved. Customer adoption was strong. The launch was a success. Six weeks later, sales is not pitching the feature, customer success is not using it as a save argument, and the executive team has forgotten about it. + +Root cause. No sustained internal awareness. The launch hit; the team moved to the next thing; internal momentum did not carry. + +Fix. Re-brief internal stakeholders at the four-week checkpoint. Share the metrics. Highlight customer use cases. Make the feature part of the next sales kickoff or company all-hands. + +Prevention. Internal launch is not a one-time event. After the four-week measurement, revisit. Share the win story. Update the sales playbook. The launch is not over until the feature is part of the team's vocabulary for at least a quarter. + +See: `internal-alignment-checklist.md`. + +--- + +## The pattern across all twelve + +Most launch failures share one root cause. The team treated the launch as a single event (the day the feature ships) rather than a multi-week discipline (the period when the feature lands). + +The shipping vs releasing vs launching distinction names this. Shipping is a moment; releasing is a moment; launching is a discipline that spans the four to eight weeks before and after. Teams that invest in the discipline catch most failure modes early; teams that treat the launch as a moment hit failure modes late or never. + +The fix at the meta level. Pre-launch checklist. Launch-day standup. Post-launch measurement at four-week and eight-week checkpoints. The discipline is the only thing that produces consistent launches across many features. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md b/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md new file mode 100644 index 0000000..739ade4 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/customer-comms-playbook.md @@ -0,0 +1,148 @@ +# Customer comms playbook + +Channels, decision factors, calendar template, comms misfire failure mode. + +The principle. Every channel has a different reach, latency, and cost. Pick the channels that match the feature's audience and tier; sequence them so the highest-touch channels fire first and the highest-reach channels fire last. + +--- + +## Channel-by-channel + +### In-app + +Reach. Active users only. Highest engagement among the people who already use the product. + +Latency. Real-time once the rollout reaches them. + +Right for. Product-internal features. Tooltips, banners, modals. Discoverability prompts. + +Decision factors. Are users active enough to encounter the in-app surface within the launch window? If your DAU is 10 percent of MAU, in-app reaches one in ten users in the first week. + +Anti-pattern. Modal interrupting the user mid-task. Use banners, tooltips, or empty-state prompts that the user notices but does not have to dismiss. + +### Email (transactional or campaign) + +Reach. All users who opted in. Higher than in-app for inactive users. + +Latency. Hours from send to read. Delays for users who batch-read email. + +Right for. Material changes that affect existing workflows. Pricing changes. Breaking changes that need user awareness. + +Decision factors. Is the change material enough to justify an email? If the user can discover the feature on their next visit, email may be unnecessary. If the change affects their billing or their workflow, email is the right channel. + +Anti-pattern. Sending email for every release. Customers unsubscribe; the channel decays. + +### Blog post + +Reach. External traffic plus existing customers who read the blog. Best for SEO, lead gen, narrative. + +Latency. Hours to days from publish to traffic peak. + +Right for. Tier 1 launches with external story. Competitive positioning announcements. Major narrative shifts. + +Decision factors. Is there a story worth telling beyond "we shipped a feature"? Blog posts about feature ships read as marketing churn; blog posts about category narrative shifts read as substantive. + +### Release notes + +Reach. Customers who actively check release notes. Discoverable later via search. + +Latency. Real-time on publish; the long-tail value comes from search-engine and customer-search traffic over the following months. + +Right for. Every Tier 2 and above. The canonical reference customers find later when they encounter the feature in the wild. + +Decision factors. Always. Release notes are the cheapest comms channel; the cost of writing one is small; the long-tail value is real. + +### Social (LinkedIn, X, Bluesky) + +Reach. Beyond existing customers. Mostly other PMs, engineers, prospects. + +Latency. Hours to days from post to engagement. + +Right for. Launches with external narrative or competitive angle. Founder-led marketing. + +Decision factors. Does the launch have a story that a non-customer would care about? If no, social is filler. If yes, social can drive net-new pipeline. + +### Webinar or customer call + +Reach. Limited to attendees, but high engagement per attendee. + +Latency. Days to weeks from announcement to event. + +Right for. Tier 1 launches with material customer impact. Enterprise customers who need depth. + +Decision factors. Does the feature need explanation that a blog post or email cannot deliver? If yes, webinar. If the feature is self-evident, skip. + +### Sales-led briefing + +Reach. Top accounts only. Highest-touch channel. + +Latency. Days from scheduling to delivery. + +Right for. Launches affecting pricing, contracts, or strategic positioning. Top accounts hear about the feature from their account executive before they hear from any other channel. + +Decision factors. Does the launch affect the top 10 to 20 accounts in a way that requires a personal conversation? If yes, sales-led briefing is non-negotiable. + +--- + +## The comms calendar + +A single document with all channels and dates. Distributed in the internal launch brief. + +\| Date \| Channel \| Owner \| Status \| Notes \| +\|---\|---\|---\|---\|---\| +\| T minus 14 days \| Sales briefing scheduled \| Sales lead \| Pending \| 30-min training \| +\| T minus 7 days \| Support training delivered \| Support lead \| Pending \| Live + recorded \| +\| T minus 3 days \| CS outreach to top 20 accounts \| CS lead \| Pending \| Email plus call \| +\| T minus 1 day \| Sales briefing delivered \| Sales lead \| Pending \| Q&A captured \| +\| T minus 1 day \| Support FAQ published internally \| Support lead \| Pending \| \| +\| T plus 0 (launch day, AM) \| In-app banner activates \| Eng \| Auto on rollout \| Gated on health \| +\| T plus 0 (launch day, AM) \| Release notes publish \| PM \| Manual on health \| \| +\| T plus 0 (launch day, PM) \| Email send to all customers \| Marketing \| Manual on health \| After 4-hr stability \| +\| T plus 1 day \| Blog post publishes \| Marketing \| Manual on health \| \| +\| T plus 1 day \| Social posts \| Marketing + founder \| Manual on health \| \| +\| T plus 7 days \| Webinar (Tier 1 only) \| PM + Marketing \| Scheduled \| \| +\| T plus 14 days \| First post-launch checkpoint \| PM \| Recurring \| Adoption review \| + +The calendar names every channel, every date, every owner. Gaps in the calendar signal channels that are not covered (intentionally or accidentally). + +--- + +## Sequencing principles + +Highest-touch first. Sales-led briefing for top accounts before public comms. The top customer hearing about a feature from their account manager before they hear from a blog post is a trust win; the inverse is a trust loss. + +Internal before external. Sales training before sales is asked customer questions. Support training before customers ask support questions. Internal launch brief before any customer-facing channel fires. + +Health-check gates on auto-fire channels. In-app banners, scheduled emails, scheduled blog posts should be gated on a rollout health check. Manual triggers preferred for any channel that would be embarrassing if the rollout is paused. + +Lower-reach to higher-reach. Release notes and in-app first; email second; blog and social last. The lower-reach channels catch initial issues; the higher-reach channels amplify after stability. + +--- + +## The comms misfire failure + +The most common comms execution failure. + +The setup. The blog post is scheduled to auto-publish at the announced launch time. The rollout starts at 9 AM. At 11 AM, an issue is detected and the rollout is paused at 25 percent. The blog post auto-publishes at noon as scheduled. + +The result. Customers click through to the new feature page. 75 percent of them do not see the feature (the rollout has not reached them). They report bugs that are actually rollout-paused state. The launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +The pattern. Auto-fire is convenient but brittle. Manual triggers are slightly more work but catch issues that auto-fire cannot. + +--- + +## Channel-mix rules of thumb by feature type + +\| Feature type \| Recommended channel mix \| +\|---\|---\| +\| New feature for active users (Tier 2) \| In-app + release notes \| +\| Major feature launch (Tier 1, B2B) \| All channels: in-app, email, blog, release notes, social, sales-led briefing for top accounts \| +\| Pricing change \| Email + blog + sales-led briefing + executive comms; in-app for affected users \| +\| Breaking change \| Email + in-app prominent banner + release notes + (B2B) sales-led briefing \| +\| Performance improvement \| Release notes + (Tier 2) in-app + (Tier 1) blog post \| +\| New integration \| Release notes + email + blog + co-marketing with the integration partner \| +\| Enterprise-only feature \| Sales-led briefing + customer success outreach + release notes; skip blog and social \| + +The pattern. The channel mix is not "all channels" by default. It is the subset of channels that match the audience and the tier. Skipping the wrong channel hurts; firing on the wrong channel also hurts. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md new file mode 100644 index 0000000..13637c1 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/internal-alignment-checklist.md @@ -0,0 +1,144 @@ +# Internal alignment checklist + +Stakeholders, brief structure, distribution timing. The launch brief is the single document that aligns everyone before customer comms go out. + +The principle. Internal alignment fails silently. The team does not know they are misaligned until a customer asks sales a question that sales cannot answer, or a customer escalates an issue support did not know existed. The launch brief catches misalignment before customers do. + +--- + +## Stakeholders by org type + +### Small startup (under 50 employees) + +- Engineering lead. Capacity for fixes, support escalation handling. +- Sales lead (if B2B). Pipeline impact, deal coaching. +- Customer success / support lead. Often the same person at this size. +- Marketing or content lead (if exists). Comms execution. +- Executive sponsor. Usually CEO at this size. + +The brief is shorter at this size; the meeting is faster; but the discipline still matters. The "small team did not need a launch brief" assumption is a frequent source of small-launch failures. + +### Mid-size (50 to 500 employees) + +- Engineering leadership. +- Sales leadership and at least one regional sales lead. +- Customer success leadership. +- Marketing leadership. +- Support leadership. +- Executive sponsor (VP-level for most launches; C-level for Tier 1). + +The brief is longer. The launch meeting includes a Q&A. Decision log captures the questions and answers; the log is part of the brief. + +### Enterprise (500+ employees) + +- Engineering leadership. +- Sales leadership across regions and segments. +- Customer success leadership. +- Marketing leadership including PMM (product marketing manager). +- Support leadership. +- Legal, security, and compliance (for features touching pricing, data, or regulated workflows). +- Executive sponsor (C-level for Tier 1). + +At this size, the launch brief is a formal document with sections owned by different functions. PMM often co-owns the brief with the PM. + +--- + +## The launch brief + +A single document distributed two to four weeks before Tier 1 launch, one week before Tier 2 launch. + +### Section 1: one-page summary + +Top of the brief. The PM writes it. The reader should be able to answer "what is launching, when, who is it for, why now" after one minute. + +### Section 2: positioning + +The positioning canvas (from the positioning-canvas reference) embedded directly. Target user, problem, current alternative, user-visible promise, proof points, anti-positioning. + +### Section 3: launch calendar + +Every channel and every date. In-app banner activation, email send, blog post publish, social post times, sales briefing, support training, customer success outreach windows. Owners named for each. + +### Section 4: what each function needs to do differently + +The most important section for the readers. Each function gets a paragraph. + +- Sales. Battlecard link. Demo recording link. Top objections and answers. Deals to revisit. Training session date. +- Customer success. Top accounts to brief. Talking points for the briefing. Escalation contact during launch week. +- Support. Training session date. FAQ link. Escalation path. Ticket tagging convention. +- Marketing. Channel list, dates, message variants by channel. +- Engineering. On-call coverage during launch. Rollback authority. Health-check dashboard link. + +If a function does not have a paragraph, the launch was not designed with that function in mind; revisit before distributing. + +### Section 5: FAQ + +The questions that have already come up internally, with answers. The FAQ updates daily during the first week of distribution as new questions surface. + +### Section 6: decision log + +Choices already made. Includes the rationale for non-obvious decisions. Future questions ("why did we pick that rollout strategy?") get answered by reading the log instead of re-litigating the decision. + +--- + +## Distribution timing + +\| Tier \| Timing \| Channel \| +\|---\|---\|---\| +\| Tier 1 \| 2 to 4 weeks before launch \| Email plus async meeting plus 1:1 follow-ups for sales and CS \| +\| Tier 2 \| 1 week before launch \| Email plus async meeting \| +\| Tier 3 \| Day of launch or as part of a weekly release digest \| Email or shared doc \| + +The pattern. Launch brief lands first. Sales briefing, support training, customer success outreach all happen after the brief lands and before the public comms fire. + +--- + +## The pre-launch meeting + +For Tier 1 launches, hold a 30-minute pre-launch meeting one week before launch. + +Agenda. + +1. PM walks through the positioning canvas and the calendar (10 minutes). +2. Each function lead confirms their readiness (10 minutes). +3. Open Q&A captured in the decision log (10 minutes). + +The meeting is not for re-litigating the launch. It is for confirming readiness and catching last-minute gaps. If functions are not ready, the launch is delayed. The PM has authority to delay; the executive sponsor confirms. + +--- + +## The launch-day standup + +For Tier 1 launches, hold a brief launch-day standup at the start of launch day. Five to ten minutes. + +Agenda. + +1. Confirm rollout health check is green. +2. Confirm comms are gated on the health check (the social post will not auto-fire if the rollout is paused). +3. Confirm support is staffed for the launch window. +4. Confirm escalation contacts are reachable. +5. Open the post-launch monitoring channel. + +The launch-day standup catches "the marketing person took the day off and the social post is set to auto-fire" the morning of launch instead of in the moment. + +--- + +## Common internal alignment failures + +- Launching without sales knowing. Sales finds out from a customer. Trust erodes for the next launch. Fix: launch brief plus sales-specific briefing one to two weeks before public comms. +- Sales briefing is the launch brief. Sales reads a 12-page document. Their actual takeaway is partial. Fix: separate one-pager for sales (the battlecard) plus the full brief for reference. +- Support is trained the day of launch. Support cannot internalize a new feature in one morning. Fix: train support one week before customer-facing launch. +- Customer success outreach happens after public comms. Top accounts hear about the feature from the email blast like everyone else. Fix: customer success briefs top accounts one to three days before public comms. +- Executive sponsor is surprised on launch day. The executive read the brief but did not internalize it; on launch day they see press coverage and ask the team questions that should have been answered in the brief. Fix: brief executives in person, not just via document. + +--- + +## When the brief reveals misalignment + +The brief is the artifact that surfaces misalignment. Common signals. + +- The positioning canvas does not match how sales describes the customer profile. Misalignment between PM and sales on who the customer is. +- The launch calendar does not give sales enough time. Misalignment on what enablement requires. +- The FAQ has questions nobody can answer. Misalignment on what the feature actually does. + +The pattern. Surface misalignment before launch; resolve before launch. The brief is the tool that forces the conversation. A team that drafts the brief carefully and finds it easy to write probably has no misalignment. A team that struggles to write the brief has misalignment that the brief is now revealing; resolve it before customer comms go out. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md b/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md new file mode 100644 index 0000000..dab6ffc --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/launch-tier-decision.md @@ -0,0 +1,137 @@ +# Launch tier decision + +Tier 1 / Tier 2 / Tier 3 decision framework. Worked examples. Anti-patterns on both sides. + +The principle. Match launch effort to feature scope. Treating every release as Tier 1 produces comms fatigue; treating every release as Tier 3 produces unlaunched features. + +--- + +## The tiers + +### Tier 1: full launch + +Scope. Net-new product, major feature reshaping the product narrative, pricing change, breaking change. + +Effort. Full playbook. Positioning, all comms channels, sales enablement (B2B), customer success briefing, dedicated post-launch measurement, executive announcement. Two to four weeks of pre-launch work; four to eight weeks of post-launch monitoring. + +Examples. + +- A new product surface (Slack adds Canvas; Figma adds FigJam; Notion adds Sites). +- A pricing model change (per-seat to consumption; introducing a new tier). +- A foundational replatforming with user-visible impact (a new UI architecture, a new permissions model). +- A flagship competitive feature (the thing the sales team has been asking for, the thing the analyst report compared you on). + +### Tier 2: focused launch + +Scope. Meaningful improvement that materially affects user value or competitive positioning. + +Effort. Subset of the playbook. In-app comms, blog post or detailed release note, support readiness, rollout strategy, post-launch measurement. One to two weeks of pre-launch work; two to four weeks of post-launch monitoring. + +Examples. + +- A new export format that customers have been requesting. +- A redesigned core flow (e.g., a new onboarding experience). +- An integration with a major third-party (Slack notifications, Salesforce sync). +- A meaningful performance improvement (page loads twice as fast on a flagship surface). + +### Tier 3: release note + +Scope. Incremental improvement, bug fix made positive, polish. + +Effort. Minimal. Changelog entry, release note, light monitoring. Hours of pre-launch work; passive monitoring post-launch. + +Examples. + +- A new keyboard shortcut. +- A small UI polish (better empty states, refined typography). +- A minor configuration option (toggle to disable a non-default behavior). +- A bug fix that improves reliability for a small cohort. + +--- + +## Decision framework + +When unsure between two tiers, ask three questions. + +1. Will sales need to talk about this? If yes, at least Tier 2. If sales is selling against this gap today, Tier 1. +2. Will customers be confused if we do not tell them? If yes, at least Tier 2. +3. Will the metric this is meant to move show up in board reporting? If yes, Tier 1. If yes but only at the team level, Tier 2. + +If all three answers are no, the feature is Tier 3. + +--- + +## Worked examples + +### Example 1: a new export-to-PDF capability + +A B2B SaaS product adds export-to-PDF to its reporting feature. + +- Will sales talk about this? Yes; this has been a top sales objection. +- Will customers be confused without comms? No; the feature is discoverable in the existing UI. +- Will the metric move at board level? Probably not directly; might unblock some deals. + +Tier 2. Sales enablement (battlecard plus a one-paragraph deal-coaching note). Blog post. Release note. In-app banner on the reporting page. Light monitoring. + +### Example 2: a new pricing tier with consumption-based billing + +A SaaS company adds a usage-based tier alongside its existing per-seat plans. + +- Will sales talk about this? Yes; pricing changes always involve sales. +- Will customers be confused without comms? Yes; existing customers will wonder if they should switch. +- Will the metric move at board level? Yes; revenue mix and ARR composition are board-level. + +Tier 1. Full positioning canvas. Internal launch brief 4 weeks ahead. Sales enablement including pricing change documentation. Email to existing customers explaining what is and is not changing for them. Blog post. Webinar for top accounts. Phased rollout starting with new customers, then existing customer opt-in. + +### Example 3: a keyboard shortcut for a power-user action + +A consumer app adds Cmd+K for quick navigation. + +- Will sales talk about this? No; consumer product, no sales motion. +- Will customers be confused without comms? No; the feature is purely additive and discoverable. +- Will the metric move at board level? No; small UX improvement. + +Tier 3. Changelog entry. Maybe a tweet from the product team. No further work. + +### Example 4: an enterprise SSO integration + +A B2B SaaS adds SAML SSO support. + +- Will sales talk about this? Yes; SSO is a hard requirement for many enterprise deals. +- Will customers be confused without comms? Existing self-service customers no; enterprise prospects yes. +- Will the metric move at board level? Indirectly; SSO unblocks enterprise deals worth real ARR. + +Tier 1 if SSO unlocks the enterprise segment for the first time, otherwise Tier 2. Sales enablement is the highest-impact piece (the deal-coaching note for previously SSO-blocked accounts). Customer success outreach to top enterprise prospects. Blog post focused on the security and IT audience. Quiet rollout for self-service customers (changelog only). + +--- + +## Anti-pattern: everything is Tier 1 + +Symptom. Every release gets a blog post, an email, a sales briefing. Customers tune out the announcement firehose. Real Tier 1 launches lose signal in the noise. Sales reps stop reading the briefings because they assume every one is minor. + +Fix. Be honest about which features are major. If you ship five "major" launches per quarter, three of them are Tier 2 or Tier 3 in disguise. The Tier 1 budget should be one to three per quarter for most companies. + +--- + +## Anti-pattern: everything is Tier 3 + +Symptom. Features ship without comms. Sales does not know what is new. Customers are surprised when they discover a feature six months after launch. Metrics do not move because users do not know the feature exists. + +Fix. Tier honestly. Most B2B SaaS releases are Tier 2; defaulting them to Tier 3 leaves value on the table. The minimum Tier 2 effort (release note plus in-app banner plus support FAQ) is small; the marginal value capture is large. + +--- + +## How tier affects the rest of the playbook + +\| Section \| Tier 1 \| Tier 2 \| Tier 3 \| +\|---\|---\|---\|---\| +\| Positioning canvas \| Required \| Required \| Skip \| +\| Internal launch brief \| 2 to 4 weeks ahead \| 1 week ahead \| Skip \| +\| Customer comms \| All channels \| In-app + blog + release note \| Release note \| +\| Sales enablement (B2B) \| Full battlecard + demo + training \| One-page note + Q&A \| Skip \| +\| Support readiness \| Full training \| Brief + FAQ \| FAQ if applicable \| +\| Rollout strategy \| Phased or gradual \| Gradual \| Either \| +\| Monitoring \| Full + rollback triggers \| Standard + alerts \| Passive \| +\| Post-launch measurement \| 4 to 8 weeks \| 2 to 4 weeks \| Light \| + +The pattern. Tier 1 is the full playbook. Tier 2 is the playbook compressed. Tier 3 is the changelog plus passive monitoring. Each section's depth scales with tier. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md new file mode 100644 index 0000000..6770c30 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md @@ -0,0 +1,185 @@ +# Monitoring readiness checklist + +Metrics dimensions, alert thresholds, pre-defined rollback triggers. The "no rollback trigger" failure mode. + +The principle. Monitoring catches launch issues before they compound into customer pain. The discipline is defining what to watch and what to do BEFORE launch, so the team executes rather than debates during the launch window. + +--- + +## What to monitor + +Six dimensions for most launches. + +### 1. Error rates + +- Overall error rate. The baseline. Has the deploy increased errors across the application. +- Feature-specific error rate. Errors in code paths the new feature touches. Often the first signal of a feature-specific bug. +- Per-cohort error rate. Errors broken down by user segment, plan, region. Catches cohort-specific bugs. + +### 2. Latency + +- Overall P50, P95, P99. Has the deploy slowed the application. +- Feature-specific latency. New code paths often have unoptimized queries; latency tracking catches them. +- Database query latency. New features often add new queries; database load can spike. + +### 3. Feature usage rate + +- Reach. Of users in the rollout cohort, how many actually trigger the feature within their first session post-rollout. +- Frequency. Of users who used the feature once, how many used it again. +- The expected vs actual gap. Pre-launch projections vs actual numbers. Large gaps in either direction need investigation. + +### 4. Funnel completion + +- End-to-end completion of the workflow the feature is part of. Did users complete the flow at the same rate as pre-launch. +- Step-by-step drop-off. Where in the flow are users abandoning. Compare pre-launch to post-launch step-by-step. +- Per-cohort completion. Cohort-specific drop-off can hide in aggregate metrics. + +### 5. Support ticket volume + +- Overall ticket volume. Has the team's support load increased. +- Feature-tagged tickets. Tickets where the customer mentions the feature. +- Ticket sentiment. Frustrated tickets vs informational tickets vs positive tickets. + +### 6. Customer satisfaction signals + +- NPS comments. Mentions of the feature in NPS responses. +- Feedback widget. In-product feedback explicitly about the feature. +- Social mentions. Twitter or LinkedIn posts about the launch. + +--- + +## Alert thresholds + +For each dimension, pre-defined thresholds that fire alerts. + +### Error rates + +- Yellow. Overall error rate up by more than 25 percent vs pre-launch baseline. Investigate without escalation. +- Orange. Overall error rate up by more than 50 percent vs baseline. Escalate to PM and engineering on-call. +- Red. Overall error rate above 1 percent absolute. Trigger rollback. + +### Latency + +- Yellow. P95 up by 25 percent vs baseline. Investigate. +- Orange. P95 up by 50 percent. Escalate. +- Red. P95 doubled or worse. Trigger rollback if sustained for 10 minutes. + +### Feature usage rate + +- Yellow. Below 50 percent of pre-launch projection. Investigate (probably comms or discovery problem). +- Orange. Below 25 percent of projection. Escalate; the launch may not be reaching users. +- Red. Near zero usage. Likely an instrumentation bug; the feature is not firing or the metric is not capturing. + +### Funnel completion + +- Yellow. Down by 10 percent from pre-launch baseline. Investigate. +- Orange. Down by 25 percent. Escalate; the feature may be breaking the flow. +- Red. Down by 50 percent for any cohort. Trigger rollback for that cohort or pause the rollout. + +### Support volume + +- Yellow. Feature-tagged tickets exceed 10 in the first hour. Investigate. +- Orange. Feature-tagged tickets exceed 50 in the first hour. Escalate. +- Red. Feature-tagged tickets exceed 100 in the first hour. Trigger rollback or pause; the feature has a real problem. + +The numbers above are illustrative. Calibrate to the team's actual support volume and the feature's expected reach. + +--- + +## Pre-defined rollback triggers + +A rollback trigger is a rule that fires automatically. The team executes the rollback without re-litigating whether to. + +### Examples + +For a feature touching the checkout flow. + +- Error rate above 1 percent sustained for 5 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline. +- Stripe API errors increase by 100 percent. + +For a new internal tool. + +- Error rate above 5 percent sustained for 5 minutes (higher tolerance because internal users provide more context). +- Adoption near zero after 24 hours (instrumentation bug or feature not deployed). + +For a pricing change. + +- Subscription cancellation rate increase by 50 percent in the first 48 hours. +- Customer service contact rate about pricing increase by 200 percent. +- Revenue forecast adjustment indicates a 10 percent quarterly miss. + +The pattern. Each rollback trigger names a specific metric, a specific threshold, and a specific time window. The team rehearses what to do when the trigger fires. + +### What rollback means + +Rollback can be one of several things. + +- Full rollback. Flag off, code reverted, user-visible state returns to pre-launch. +- Pause at current rollout percentage. Flag stays on for users who already have it; no new users get the feature. +- Cohort-specific rollback. Flag off for the cohort showing issues; flag on for cohorts that look healthy. +- Fix-forward. A small fix is deployed; rollout continues at the previous percentage. Risky; only use when the fix is high-confidence. + +The team should know which rollback path applies to which trigger before launch. + +--- + +## The on-call rotation + +For Tier 1 launches, the on-call rotation should include. + +- Primary engineering on-call. Standard rotation. Receives alerts, executes rollbacks. +- Secondary engineering on-call. Backup if primary is unreachable. +- PM contact. The PM who owns the launch is reachable during the launch window. +- Support escalation contact. The support lead responsible for routing customer issues to the right team. +- Marketing contact. For comms decisions if the rollout pauses. + +Reachability hours for Tier 1 launches: 24/7 for the first 48 hours, business hours plus on-call after that. + +--- + +## The "no rollback trigger" failure + +The pattern. + +- Launch goes sideways. Error rate is up; support volume is high; engineering is investigating. +- The team debates whether to roll back. The debate takes an hour. +- During the debate hour, more users encounter the issue. Support tickets pile up. The press notices. Trust erodes. +- The team eventually rolls back, but the recovery is now harder than it would have been one hour earlier. + +The fix. Pre-define the rollback triggers. Write them down. Get team agreement before launch. When a trigger fires, execute the rollback. Debate the appropriateness of the trigger after the rollback, not during the incident. + +The discipline. The cost of a wrong rollback (the team rolls back when the feature was actually fine) is small (a paused launch and a re-rollout). The cost of a delayed rollback (the team debates while the issue compounds) is large (customer impact, reputation, recovery cost). Bias toward fast rollback. + +--- + +## Post-rollback retrospective + +After any rollback, hold a retrospective within 48 hours. + +Agenda. + +1. What was the trigger that fired. +2. What was the actual problem. +3. Was the rollback the right call (almost always yes; even false positives that catch nothing teach the team about the system). +4. What is the path to re-launch (fix the bug, test it, validate the test, schedule a new rollout). +5. What did we learn that updates the next launch's monitoring. + +The retrospective is not a blame session. It is an investment in the next launch's monitoring quality. + +--- + +## Health check before each rollout step + +For gradual percentage rollouts, define a health check that gates each step. + +The health check passes when. + +- All Yellow thresholds clear for the prior percentage step's full duration. +- No Orange or Red alerts in the prior step. +- Support volume stable. +- Customer feedback (NPS, social) neutral or positive. + +The health check fails when any of the above conditions does not hold. The rollout pauses at the current step until the health check passes. + +The pattern. The rollout proceeds when the system is healthy; it does not proceed on a schedule. Schedule-driven rollouts that ignore health checks are how launches go sideways. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md b/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md new file mode 100644 index 0000000..4ab4b54 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/positioning-canvas.md @@ -0,0 +1,132 @@ +# Positioning canvas + +The one-page positioning template. Worked examples for B2B SaaS, B2C, and developer features. The vague-target-user failure mode. + +The principle. Positioning is the foundation of the launch. Without it, comms drift, sales improvise, and customers come away with a different understanding of the feature than the team intended. Filled out before any comms drafting; reviewed by sales, support, and an executive sponsor before launch. + +--- + +## The canvas + +One page. Six sections. Filled out by the PM with input from sales, customer success, and design. + +### 1. Target user + +Segment. What kind of company or individual. + +Role. What is their job title or function. + +Jobs-to-be-done. What is the user trying to accomplish in their work or life that this feature serves. + +Specificity test. Could a sales rep describe the customer profile in one sentence? Could marketing target ads at this segment? If no to either, the target user is too vague. + +### 2. Problem it solves + +The current pain. In the user's words. What is hard, slow, error-prone, or impossible today. + +The cost of the pain. Time, money, errors, missed opportunities. Quantified where possible. + +Specificity test. Is the problem stated in concrete terms or in abstract language? "Productivity is low" is abstract. "The customer support manager spends 3 hours per day triaging tickets that an automated system could route" is concrete. + +### 3. Current alternative + +What users do today without this. The status quo, the workaround, the competing product, the manual process, the spreadsheet. + +The status quo is the real competition. A feature that is better than nothing but worse than the user's existing workaround does not get adopted. + +### 4. User-visible promise + +One sentence. The promise the user will hear when they encounter the feature. + +Specificity test. Can sales repeat it without changing words? Can support repeat it without paraphrasing? If no, it is too long or too abstract. + +### 5. Proof points + +Three to five specific capabilities or outcomes. Concrete, not adjectives. + +Examples of bad proof points: "fast," "easy," "secure," "intelligent." These are claims, not proof. + +Examples of good proof points: "exports a 200-page report in under 5 seconds," "supports 14 languages including right-to-left," "SOC 2 Type II audited by Deloitte 2025." + +### 6. Anti-positioning + +What this is NOT. What it does not try to do. + +Anti-positioning prevents over-promising. If the feature does not handle enterprise scale, say so. If it does not work offline, say so. If it does not replace the customer's existing tool, say so. + +The anti-positioning protects the team from sales reps who hear about the feature and embellish. It protects support from customers who expected something the feature does not do. + +--- + +## Worked example 1: B2B SaaS feature + +A B2B project management tool ships a new automated routing feature. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Customer support managers at SaaS companies with 10 to 100 support reps. JTBD: triage incoming tickets and route them to the right team without reading every ticket. \| +\| Problem it solves \| Current manual triage takes 2 to 3 hours of a support manager's day. Tickets sit in the queue waiting for routing while customers grow impatient. The cost is 10+ hours per week of manager time plus 30 to 60 minute response delays on simple tickets. \| +\| Current alternative \| Manual triage by a senior support rep, or basic keyword routing rules in their existing helpdesk that produce 30 to 40% misroutes. \| +\| User-visible promise \| "Route incoming tickets to the right team in under 30 seconds with 95% accuracy." \| +\| Proof points \| (1) ML model trained on 90 days of historical ticket routing decisions. (2) Accuracy benchmarks: 95% routing accuracy at launch, retraining weekly. (3) Override and feedback flow lets support managers correct routes; corrections feed back into the model. (4) Audit log of every routing decision for compliance. (5) Configurable confidence threshold; below the threshold, the ticket falls back to manual routing. \| +\| Anti-positioning \| This is not a full ticket-resolution AI. It does not draft replies, identify duplicate tickets, or detect sentiment. It only routes. \| + +The anti-positioning protects the team from sales reps who would otherwise pitch this as "AI customer support." + +--- + +## Worked example 2: B2C feature + +A consumer note-taking app ships AI-generated summaries. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Students and knowledge workers who maintain long-form notes. Specifically users with 50+ notes longer than 500 words. JTBD: quickly recall the key points of a note without re-reading it. \| +\| Problem it solves \| Long notes get written then forgotten. The user cannot recall what is in them without scrolling and re-reading. Cost: hours per week of search-and-rediscover, plus the worse cost of acting on stale information. \| +\| Current alternative \| Manual TLDRs the user writes themselves (rare). Highlighted text within the note (common but unreliable). Re-reading the full note (default; expensive). \| +\| User-visible promise \| "See a summary of any note in two seconds." \| +\| Proof points \| (1) Summaries appear at the top of every note over 500 words. (2) Summary regenerates when the note is meaningfully edited. (3) Click any summary point to jump to its source paragraph in the note. (4) Generates in under 2 seconds for notes up to 5,000 words. \| +\| Anti-positioning \| This is not a research assistant; it does not pull in outside context or related notes. It summarizes the note in front of you, nothing more. \| + +--- + +## Worked example 3: developer feature + +A developer tools company ships a new CLI command. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Backend engineers using the platform's CLI for deploys. Specifically engineers who run more than 5 deploys per week. JTBD: deploy faster and roll back when something breaks. \| +\| Problem it solves \| Rollbacks today require digging through deploy history, finding the prior version, and running a deploy command with the version pinned. Takes 2 to 5 minutes; under incident pressure, the time matters. \| +\| Current alternative \| Manual deploy command with version pin. Some teams script this; most do it from memory under pressure. \| +\| User-visible promise \| "Roll back to the last known good deploy with one command." \| +\| Proof points \| (1) Single command: `acme deploy rollback`. (2) Defaults to the most recent successful deploy that is older than the current. (3) Confirmation prompt shows what will be rolled back; passes through to the existing deploy flow. (4) Logged as a rollback in deploy history (not as a fresh deploy) for clean audit trail. \| +\| Anti-positioning \| This does not auto-detect bad deploys. The engineer still decides when to roll back. \| + +--- + +## The vague-target-user failure mode + +The most common positioning failure. The PM writes "It is for PMs" or "It is for engineers" or "It is for marketers." + +Why it fails. Different PMs, engineers, and marketers have different jobs. A B2B PM at a 50-person startup has a different job from a B2C PM at a 5,000-person company. A backend engineer has a different job from a frontend engineer. The vague target prevents sales from filtering, prevents marketing from targeting ads, prevents support from anticipating questions. + +The fix. Specificity layers. + +- Industry or company type. (B2B SaaS at 50 to 500 customers.) +- Role and function. (Customer support manager, not just "support.") +- Jobs-to-be-done. (Triage incoming tickets, not "improve productivity.") + +Three layers of specificity move the target from useless to actionable. If you cannot fill in all three, the team has not yet decided who the feature is for. + +--- + +## Reviewing the canvas + +Before launch, review the positioning canvas with three audiences. + +1. Sales review. Can sales pitch this in 30 seconds? Does the language match how customers ask about the problem? +2. Support review. Can support answer the obvious questions (what does it cost, how do I turn it on, what are the limits) using only the canvas? +3. Executive review. Does the positioning fit the company narrative? Will it confuse customers who are mid-purchase on a different feature? + +If any of the three review groups push back, fix the canvas before launch comms drafting begins. Drafting comms on top of weak positioning produces comms that look fine in isolation but contradict each other across channels. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md b/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md new file mode 100644 index 0000000..3475f47 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/post-launch-measurement-framework.md @@ -0,0 +1,181 @@ +# Post-launch measurement framework + +Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. The "declared victory on launch spike" failure mode. + +The principle. The launch measurement plan answers "did this work." Without it, the team moves on without knowing. + +--- + +## Four measurement dimensions + +### 1. Adoption (the reach question) + +Did the right users actually use the feature. + +Metrics. + +- Reach: of users in the rollout cohort, what fraction has tried the feature. +- Time to first use: of users who tried the feature, how long after rollout. +- Distribution by cohort: are the right segments (per the positioning canvas) the ones using the feature. + +Signal interpretation. + +- High reach plus right cohorts: the launch reached the target audience. +- High reach plus wrong cohorts: the launch reached the wrong audience; positioning or comms missed the target. +- Low reach: comms problem or discovery problem. Investigate which channel users would have learned about the feature from. + +### 2. Engagement (the stickiness question) + +Did users who tried the feature come back. + +Metrics. + +- Retention: of users who tried the feature once, what fraction used it again within 7, 14, 30 days. +- Frequency: how many times per week did adopters use the feature. +- Depth: did adopters use the full feature or only the first step. + +Signal interpretation. + +- High first-time use plus high retention: the feature is delivering value. +- High first-time use plus low retention: the feature failed to deliver on the first-use experience. Usability or value-prop problem. +- Low first-time use plus high retention among the few who tried: the feature is valuable to a niche; reach the niche better, or accept that it serves a smaller audience. + +### 3. Outcome (the effect question) + +Did the metric the spec said this would move actually move. + +Metrics. + +- The primary metric from the spec. Usually a business metric (revenue, retention, support deflection, conversion rate). +- The lift relative to a pre-launch baseline. +- The statistical significance of the lift, if a controlled comparison is available. + +Signal interpretation. + +- Metric moved as predicted: the feature delivered the value the team committed to. +- Metric moved less than predicted: partial success; the feature works but did not have the size of impact the team expected. Investigate why (smaller cohort than expected, smaller per-user impact, or simply optimistic projection). +- Metric did not move: the launch did not deliver the promised value. Investigate before declaring failure (could be measurement timeline, isolation issues, or the feature genuinely failing). + +### 4. Side effects (the safety question) + +Did any other metric move that was not supposed to. + +Metrics. + +- Cohorts adjacent to the target: did the feature affect users it was not designed for. +- Adjacent metrics: did related metrics move (positively or negatively). +- Support volume on adjacent topics: did the feature confuse customers about other parts of the product. + +Signal interpretation. + +- No side effects: clean launch. +- Positive side effects: the feature delivered value beyond the target. Document for the next iteration. +- Negative side effects: the feature broke something else. Triage urgently; this is a launch quality issue regardless of whether the primary metric moved. + +--- + +## Time horizons + +Different signals stabilize at different times. + +\| Signal type \| Stable at \| +\|---\|---\| +\| Adoption (reach) \| 1 to 2 weeks post-launch \| +\| Engagement (retention) \| 4 weeks for week-2 retention; 8 weeks for week-4 retention \| +\| Outcome \| 4 to 8 weeks for most business metrics; longer for retention or LTV \| +\| Side effects \| 2 to 4 weeks \| + +The rule. Do not declare success or failure on the outcome metric before week 4. The launch-week spike is unrepresentative; the metric needs time to stabilize at its post-launch level. + +--- + +## Tying back to spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses. The launch measurement plan validates each. + +Example hypotheses from a hypothetical spec. + +- "We expect this feature to be used by 40 percent of paid users within 30 days of rollout." (Adoption hypothesis.) +- "Of users who try the feature, we expect 60 percent to use it again within 7 days." (Engagement hypothesis.) +- "We expect this feature to reduce support tickets in the X category by 25 percent." (Outcome hypothesis.) +- "We do not expect this feature to affect billing-related support volume." (Side-effect hypothesis.) + +The measurement plan validates each. + +\| Hypothesis \| Measurement \| Decision rule \| +\|---\|---\|---\| +\| 40% paid user adoption in 30 days \| Cohort: paid users in rollout. Metric: distinct user count using the feature divided by cohort size. \| Above 30% acceptable; below 20% requires intervention. \| +\| 60% week-1 retention \| Cohort: users who tried the feature in week 1. Metric: fraction of cohort using the feature again in week 2. \| Above 50% acceptable; below 40% indicates value or usability problem. \| +\| 25% reduction in X-category support tickets \| Pre-launch baseline 30 days; post-launch 30 days. Compare ticket volumes. \| Above 15% reduction acceptable; below 10% indicates the feature is not solving the right problem. \| +\| No effect on billing support \| Billing ticket volume pre vs post. \| Volume change above 20% requires investigation. \| + +The measurement plan is written before launch. The decision rules are pre-committed; the team does not move the goalposts after seeing the data. + +--- + +## The "declared victory on launch spike" failure + +The pattern. + +- Week 1: adoption is high. The team announced the feature; users tried it; the metric is up. +- Week 2: adoption flat. The launch announcement spike has passed; the new users have tried the feature. +- Week 3: adoption declining. Users who tried the feature once are not coming back. +- Week 4: adoption near pre-launch baseline. The metric has reverted. +- The team had already declared the launch a success in week 1 and moved on. + +The cost. The team's roadmap is now built on a launch that did not actually work. The next quarter's plan assumes the metric is at the elevated level; when it does not stay there, the plan does not deliver. + +The fix. Declare success or failure based on the stable post-launch trend, not the launch-week spike. The minimum measurement window is four weeks; for retention or LTV signals, eight to twelve weeks. + +The discipline. The four-week checkpoint is on the calendar before launch. The team holds itself accountable to revisit; the executive sponsor holds the team accountable to revisit. Launches that are reported as successful in week 1 and never revisited are silent failures. + +--- + +## The "no measurement plan" failure + +The pattern. + +- Feature ships. +- Team moves on to the next feature. +- Six months later, someone asks "did feature X work?" Nobody knows. +- The feature becomes maintenance debt; the team cannot decide whether to invest in iteration. + +The cost. The team accumulates features whose value is unknown. Roadmap decisions get harder because the historical track record is opaque. Engineering investment is wasted on features that did not work; the team does not learn from them because they did not measure. + +The fix. Every launch has a measurement plan. The plan is short (one page); it names the four dimensions, the metrics, the time horizons, and the decision rules. The plan is reviewed at week 4 and again at week 8 or 12 depending on the signal. + +The discipline. The measurement plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +--- + +## When the metric did not move + +If the outcome metric did not move at week 4, the next investigation. + +1. Is adoption strong? If adoption is below target, the launch may be a comms or discovery problem, not a feature problem. +2. Is engagement strong? If engagement is below target among adopters, the value is not landing for the right reasons. +3. Is the metric correctly attributed? Did another concurrent change interfere with the measurement. +4. Did the side-effects analysis catch a counterweight? A negative side effect could be cancelling the positive primary effect. + +Each diagnosis maps to a different fix. + +- Adoption problem: more comms, repeat comms, deeper sales reactivation, in-app discovery surface. +- Engagement problem: usability or value-prop iteration. The feature may need redesign. +- Attribution problem: re-run measurement after the concurrent change has been accounted for. +- Side-effect counterweight: fix the side effect, then re-measure the primary. + +--- + +## When the launch worked but quietly + +Sometimes the launch works at every level (adoption strong, engagement strong, outcome metric moved) but the team does not feel like it succeeded. Usually the gap is internal awareness. + +Signs. + +- Sales is not using the feature in pitches. +- Customer success is not mentioning it in customer calls. +- The product narrative has not updated to include the feature. + +The fix. Internal launch effectiveness is part of the launch playbook. Even successful feature launches need ongoing internal advocacy. + +The discipline. After the four-week checkpoint, briefly re-engage internal stakeholders. Share the metrics. Highlight customer use cases. The internal awareness is not a one-time event at launch; it is sustained for a quarter or more. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md b/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md new file mode 100644 index 0000000..a7e0c83 --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/rollout-strategy-patterns.md @@ -0,0 +1,185 @@ +# Rollout strategy patterns + +Four rollout patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. + +The principle. The rollout is the mechanism by which users actually encounter the feature. The pattern depends on what would happen if the feature breaks, how confident the team is in correctness, and whether external comms are tied to a specific date. + +--- + +## Pattern 1: all-at-once (big bang) + +Mechanism. Zero to 100 percent of eligible users in a single deploy. No gradual rollout. + +Right for. + +- Marketing-coordinated launches where the announcement IS the rollout. The press is briefed for a specific date; the feature has to be live for everyone at that moment. +- Low-blast-radius features. The feature affects a small portion of the user experience; even if it breaks, the customer impact is limited. +- High-confidence releases. The feature has been tested thoroughly, used internally, validated with a beta cohort. + +Risky for. + +- High-traffic critical paths (checkout, login, primary navigation). Any bug affects a meaningful share of users immediately. +- Features without a clean rollback path. If the deploy breaks, recovery is hard. +- Features with cohort-specific risk (works for free users, breaks for enterprise). The cohort variance is not exposed before launch. + +Operational shape. One deploy. Health check after deploy. Rollback path ready but rarely used. Monitoring tightens for 24 hours post-deploy. + +--- + +## Pattern 2: gradual percentage rollout + +Mechanism. 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days. Health checks at each step. + +Right for. + +- Most feature launches. The default unless there is a reason to deviate. +- Features touching critical paths. The 1 percent rollout catches errors before they affect a meaningful share of users. +- Features with uncertain interaction effects. Other systems may behave differently when the feature is on; gradual rollout surfaces interactions safely. + +Risky for. + +- Marketing-coordinated launches with a fixed announcement date. The press writes about a feature that 90 percent of users do not have yet. + +Operational shape. + +- 1 percent to 10 percent: 4 to 24 hours. Watch error rates, latency, feature usage rate. +- 10 percent to 25 percent: 24 to 48 hours. Watch the same metrics plus support volume. +- 25 percent to 50 percent: 48 to 72 hours. Watch all metrics plus customer feedback. +- 50 percent to 100 percent: 24 to 72 hours. + +The pace is configurable. Faster for low-risk features; slower for high-risk. + +The rollback at any step. If a metric breaches a threshold, the rollout pauses. If the issue is severe, rollback to 0 percent. If the issue is minor, fix forward at the current percentage. + +--- + +## Pattern 3: flag-gated cohort rollout + +Mechanism. Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Specific named accounts first, then broad rollout. + +Right for. + +- Features with cohort-specific risk profiles. A pricing change affects existing customers differently from new customers; roll out to new customers first. +- Features that need cohort-specific configuration. Enterprise customers may need a setup step; roll out to them after they are configured. +- Features where the cost of a bad rollout varies by cohort. Bug in front of a Fortune 500 prospect costs more than a bug in front of a free-tier user. + +Operational shape. + +- The flag service controls which cohorts have the feature enabled. +- Cohorts are defined explicitly: account tier, account ID list, region, signup date range. +- Each cohort gets its own monitoring slice. Issues affecting one cohort do not pause the rollout to other cohorts. + +Risky for. + +- Features that interact across cohorts. If enterprise customers can see what free-tier customers create, a partial cohort rollout exposes a feature inconsistency that breaks workflows. + +--- + +## Pattern 4: phased launch (multi-week) + +Mechanism. Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Multi-week timeline. + +Right for. + +- Tier 1 launches with high uncertainty about user reception. Pricing changes often launch this way. +- Major UX redesigns. The team needs to learn what users do with the new design before broader rollout. +- Features that depend on user behavior change. The team needs to see whether users adopt before declaring readiness. + +Operational shape. + +- Phase 1: limited rollout (5 to 10 percent of eligible users). 1 to 2 weeks. Heavy feedback collection. +- Phase 2: iteration based on phase 1 feedback. Could be days; could be weeks. +- Phase 3: expanded rollout (25 to 50 percent). 1 to 2 weeks. +- Phase 4: general availability. + +The total timeline is 4 to 8 weeks for a typical phased launch. Longer for major UX changes; shorter for feature additions. + +Risky for. + +- Features that need to be all-on for users to encounter them naturally. A change to the homepage hero needs to be either visible or not; phased rollout creates inconsistent experiences across users. + +--- + +## The decision framework + +Three factors. Pick the rollout that matches. + +### Factor 1: blast radius + +What happens if the feature breaks for a meaningful share of users? + +- Low. Optional new tool that users opt into. Bug affects only users who tried the new tool. +- Medium. New surface in an existing flow. Bug affects users mid-flow but not users on other paths. +- High. Critical path change. Bug affects most active users immediately. + +### Factor 2: confidence in correctness + +How confident is the team that the feature works. + +- Low. First time the team has built this kind of feature. Edge cases unknown. +- Medium. The team has built similar features before. Most edge cases anticipated. +- High. Iterative refinement of an existing feature. Behavior well-understood. + +### Factor 3: external commitments + +Is the launch date tied to external press, partner coordination, or a public commitment. + +- None. Internal team knows the rough timeline; no external coordination. +- Soft. Marketing has scheduled comms but the date can shift by a few days. +- Hard. Press is briefed for a specific day. Partner is coordinating launches. The date is fixed. + +### The decision matrix + +\| Blast radius \| Confidence \| External commitment \| Recommended pattern \| +\|---\|---\|---\|---\| +\| Low \| High \| Hard \| All-at-once \| +\| Low \| High \| Soft or none \| All-at-once or gradual \| +\| Low \| Medium \| Any \| Gradual \| +\| Low \| Low \| Any \| Gradual or phased \| +\| Medium \| High \| Hard \| Gradual fast \| +\| Medium \| High \| Soft or none \| Gradual \| +\| Medium \| Medium \| Any \| Gradual \| +\| Medium \| Low \| Any \| Phased \| +\| High \| High \| Any \| Gradual slow \| +\| High \| Medium \| Any \| Gradual or flag-gated \| +\| High \| Low \| Any \| Phased \| + +The defaults. Most launches use gradual percentage rollout. The other patterns are for specific situations. + +--- + +## Cohort-specific rollout sequencing + +When using flag-gated cohort rollout, the sequence matters. + +Internal users first. Eat your own dog food. Catch the obvious issues before any external user sees them. + +Free or trial users next. Lower-stakes; if the feature has issues, the cost of a bad experience is lower than for paying customers. + +Self-service paid users. Customers who use the product without a sales rep. They will encounter the feature naturally; their feedback is high-quality. + +Top accounts last (with sales-led briefing first). Top accounts hear about the feature from their account executive before encountering it. By the time they have access, the feature is stable. + +Reverse the sequence in specific cases. + +- A feature designed specifically for enterprise customers should roll out to those customers first; the feedback is the design feedback. +- A feature gated by configuration that only enterprise customers complete should roll out to them first; otherwise the feature is invisible to the cohort that can use it. + +--- + +## What "rollback trigger" means + +A pre-defined rule that determines when the team rolls back without further debate. + +Examples. + +- Error rate above 1 percent sustained for 5 minutes. +- Latency above the pre-launch P95 by 50 percent for 10 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline for any cohort. +- Support tickets mentioning the feature exceed 50 in the first hour. + +The trigger fires automatically; the team executes the rollback without re-litigating whether to do it. + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate. + +The discipline. Define the trigger before launch. Write it down. Rehearse the rollback. Make the trigger automatic where possible (alerting plus on-call paging); make the rollback execution one command, not a multi-step process. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md b/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md new file mode 100644 index 0000000..07b7cca --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/sales-enablement-template.md @@ -0,0 +1,173 @@ +# Sales enablement template + +Battlecard, demo script, deal coaching, training session structure. For B2B; skip for B2C and PLG. + +The principle. Sales reps cannot pitch a feature they were briefed on yesterday. Enablement is the structured way to give sales the language and the mechanics they need to talk about the feature accurately and quickly. + +--- + +## When to skip this section + +For B2C products and PLG products without a sales motion, this section does not apply. The user is the buyer; there is no rep in the middle. Skip ahead to the support readiness checklist. + +For B2B products, this section is non-negotiable for Tier 1 launches and most Tier 2 launches. + +--- + +## The battlecard + +One page. Sales can read it in two minutes and pitch the feature in five. + +### Section 1: positioning summary + +Two to three sentences. The user-visible promise plus the target customer profile plus the differentiator vs the status quo. Pulled directly from the positioning canvas. + +### Section 2: target customer profile + +The specifics sales needs to qualify. Industry, company size, role of the buyer, role of the user (often different), use case, current pain. + +### Section 3: top objections and answers + +Three to five expected objections with the answer for each. The answers are written, not improvised; reps should be able to quote them back. + +Example. + +\| Objection \| Answer \| +\|---\|---\| +\| "We already have a routing solution that works fine." \| "Most solutions are keyword-based. Ours uses ML trained on the customer's actual routing decisions, so it adapts to their specific team structure. Customers report 95 percent accuracy vs 60 to 70 percent on keyword-based systems." \| +\| "How is this different from what [Competitor] just shipped?" \| "Both products do automated routing. The difference: ours retrains weekly on the customer's data; theirs uses a fixed model. Customers with non-standard team structures see materially better routing on our system." \| +\| "What if the model gets it wrong?" \| "Below the configurable confidence threshold, the ticket falls back to manual routing. Manager corrections feed back into the model, so accuracy improves over time." \| + +### Section 4: proof points + +The same proof points from the positioning canvas. Three to five concrete capabilities or outcomes. + +### Section 5: deal coaching + +Specific guidance on how this affects deals. + +- Deals to revisit. Customers in the pipeline who were blocked by the gap this feature now closes. Names where appropriate. +- Deals it complicates. Customers on the existing pricing or feature set who may need migration support. Names where appropriate. +- Common pricing questions. What customers ask about cost; the answers reps should give. + +### Section 6: where to learn more + +Links to the demo recording, the full launch brief, the FAQ, the support documentation, and the PM contact for sales questions. + +--- + +## The demo script + +A repeatable demo the rep can run with a customer. + +### Structure + +Open (1 minute). State the customer's pain in their language. Reference what they told the rep in discovery (use a generic placeholder if the rep is in a first-call demo). + +Show the problem (2 minutes). Demonstrate the status quo workflow that the feature replaces. The rep walks through the manual process, naming the friction points. + +Show the feature (5 minutes). Walk through the feature solving the same workflow. Highlight the proof points. Pause at the moments where the customer would feel the difference. + +Show the safety net (2 minutes). Walk through the failure mode. What happens when the feature does not work perfectly. The customer needs to trust the safety net before they trust the feature. + +Close (1 minute). Summarize the value. Ask the customer what they think. Surface objections. + +Total. 11 minutes. Demos longer than 15 minutes lose attention; demos shorter than 7 minutes feel rushed. + +### The recorded demo + +For reps who join after the launch or who want a refresher, a recorded version of the demo. Same structure. Annotated with timestamps. Stored where reps can find it (sales enablement platform, shared drive, internal wiki). + +The recorded demo is not a substitute for the live demo with a customer. It is reference material for the rep. + +--- + +## Deal coaching guide + +Beyond the battlecard's deal-coaching section, a longer-form guide for the top sales scenarios. + +### Scenario 1: deal blocked by missing capability + +The rep has a customer in the pipeline who was blocked by a feature gap that this launch closes. Coaching. + +- Confirm the gap was the actual blocker via discovery questions before pitching the new feature. +- Reference the customer's specific pain in the demo. +- If the deal stalled with a competitor, address the competitor head-on with the differentiator section of the battlecard. +- Time the outreach. Reach out one to three days after public launch comms; the customer will already be aware of the announcement. + +### Scenario 2: existing customer expansion + +The rep has an existing customer using a smaller plan; this launch could justify expansion. Coaching. + +- The customer success team should brief the customer first if the customer is in a top-account tier. +- The rep follows up with an upgrade conversation tied to the specific value the customer gets from the new feature. +- Pricing change documentation if applicable; reps should not improvise pricing. + +### Scenario 3: defensive against churn + +The rep has a customer at risk of churning to a competitor whose product had the feature this launch adds. Coaching. + +- The customer success team should flag the at-risk customer; the rep delivers the briefing in coordination. +- Acknowledge the gap that existed; explain the timeline of the launch; show the feature. +- Offer migration support if the customer was already starting to evaluate the competitor. + +### Scenario 4: net-new pipeline + +The rep is targeting net-new prospects for whom the launch is a relevant capability. Coaching. + +- Lead with the launch as the recent product update; reference the blog post or release. +- Tie the feature to the buyer's expected pain. +- The launch announcement is the conversation starter; the demo is the conversion. + +--- + +## The training session + +Live, 30 minutes, with Q&A. Recorded for reps who cannot attend. + +### Structure + +0 to 5 minutes. PM walks through the positioning canvas. Target user, problem, promise, proof points, anti-positioning. + +5 to 15 minutes. PM (or sales-engineering partner) demos the feature using the demo script. Reps see what the rep version of the demo looks like. + +15 to 25 minutes. Q&A. Reps ask the questions they expect customers to ask. The answers feed back into the FAQ. + +25 to 30 minutes. Coaching on top deal scenarios. Brief discussion of which named accounts in the pipeline are affected. + +### After the session + +- Recording posted to the sales enablement platform. +- Q&A captured in the launch brief's FAQ section. +- Battlecard finalized with any new objections that surfaced. +- Demo script updated with any clarifications from the live demo. + +--- + +## What to skip + +Do not. + +- Hand sales a 12-page document and call it enablement. +- Train sales the morning of public launch. +- Skip the recorded demo because "we can do it live." +- Assume sales will read the launch brief before the customer call. + +The discipline. Sales enablement is short, opinionated, and rehearsed. Reps internalize it once and pitch the feature naturally for the rest of the launch period. + +--- + +## The "shadow launch" failure + +The pattern. + +- Feature ships. +- Sales hears about it from product team Slack. +- No battlecard. +- No demo recording. +- Sales reps either ignore the feature in customer conversations (because they cannot pitch it) or misrepresent it (because they are improvising). +- Customers churn or escalate when the feature does not match what they were told. + +The cost. Engineering investment is captured at zero or negative value. The next product team launch is met with sales skepticism. + +The fix. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. The battlecard takes a half day to write. The training session takes 30 minutes. The recorded demo takes an hour. The investment is small relative to the engineering investment behind the feature. diff --git a/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md b/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md new file mode 100644 index 0000000..50f031c --- /dev/null +++ b/dist/pi/.agents/skills/feature-launch-playbook/references/support-readiness-checklist.md @@ -0,0 +1,137 @@ +# Support readiness checklist + +Training, FAQ, escalation paths, monitoring access. The pattern of training support before customer-facing launch comms. + +The principle. Support is the first to encounter the failure modes of a new feature. They need the same context as sales but oriented toward post-purchase questions and incident resolution. + +--- + +## The four deliverables + +### 1. Training + +Live or recorded, with Q&A. + +The same content as the sales training, adapted for support workflows. Differences. + +- Sales pitches the feature; support solves problems with it. The training emphasizes how to diagnose customer issues, not how to position the feature. +- Sales sees the happy path; support sees the failure modes. The training includes the FAQ of expected support tickets and the escalation paths for unexpected ones. +- Sales has a 30-minute training; support often has 60 minutes because the breadth of expected questions is larger. + +Schedule. Support training one week before customer-facing launch comms. Recorded for reps who cannot attend live. + +### 2. FAQ document + +The questions that support expects customers to ask, with the answers. + +Categories. + +- What does the feature do. The basic explanation. Same content as the user-visible promise plus a short "how it works" paragraph. +- How do I turn it on. Configuration steps. Permissions required. Plan tier required. +- What are the limits. Rate limits, size limits, supported regions, supported plans. +- What if it does not work. Troubleshooting steps. When to escalate. +- How do I turn it off. For users who tried it and want to revert. Often forgotten until the first customer asks. +- Pricing or billing questions. If the feature affects billing, support needs the answer. + +The FAQ updates daily during the first week of launch as new questions surface. Support reps add questions they encountered to the FAQ; the PM reviews and approves daily. + +### 3. Escalation path + +When support cannot answer a question or solve an issue, who do they escalate to and how fast. + +The escalation contract. + +- Tier 1 (in-product issue). Support resolves with the customer using the FAQ and product knowledge. Target response: under 1 hour during business hours. +- Tier 2 (product question support cannot answer). Escalate to the PM. Target response from PM: same day during business hours. +- Tier 3 (product is broken for the customer). Escalate to engineering on-call. Target response from engineering: under 2 hours regardless of hours during launch week. + +For Tier 1 launches, the on-call rotation should include a launch-week PM contact in addition to the regular engineering on-call. + +### 4. Monitoring access + +Support reps should be able to verify whether a customer's issue is feature-specific. + +The minimum. + +- A dashboard showing feature health (overall error rate, feature-specific error rate, rollout percentage). +- A way to look up whether a specific customer is in the rollout cohort. (For flag-gated rollouts; some customers will not have access to the feature on launch day, and support needs to be able to confirm that.) +- A way to look up the customer's recent feature usage (or the lack thereof). + +Without monitoring access, support reps escalate every feature-related ticket to engineering or the PM. The escalation queue gets noisy; real Tier 3 issues get drowned in Tier 2 questions. + +--- + +## The training-before-comms rule + +The discipline. Support training happens before customer-facing comms launch. + +The reason. Customers will start asking support about the feature within minutes of the public announcement. Support needs to be ready before customers ask, not while customers are asking. + +The pattern. + +- Day T minus 7: support training delivered. FAQ published internally. Escalation paths confirmed. +- Day T minus 1: support team huddle. Last-minute questions. FAQ refresh. +- Day T (launch day): support staffed for elevated volume. PM and engineering on-call paths confirmed open. + +The "training day-of" failure. Support is trained the morning of public launch. By the afternoon, they have already encountered three customer questions they cannot answer well. The support team's confidence with the feature degrades; customers feel the rep does not know the product. Trust loss. + +--- + +## The "support is overwhelmed" failure + +The setup. The launch generates more support volume than the team expected. The feature is novel; customers ask many basic questions; the FAQ does not anticipate the actual questions; support reps escalate everything to the PM. + +The signs. + +- Support ticket queue length doubles or triples on launch day vs the prior week. +- Tickets tagged with the feature exceed the support team's capacity for new conversations. +- The PM's Slack is full of support questions that should have FAQ answers. + +The fix. + +- Pre-launch: estimate support volume. Look at ticket volume from prior comparable launches; double the estimate. +- Pre-launch: staff support for the launch window. Pull in cross-functional help if needed. +- Pre-launch: write the FAQ deeper than feels necessary. Most launches have 20 to 30 expected questions; document them all in advance. +- Launch day: PM is available for FAQ updates throughout the day. New questions get answers within an hour and propagate to support. + +--- + +## What support needs that sales does not + +Two specific differences. + +Failure modes documentation. Support needs to know what happens when the feature breaks. The error messages users see, the recovery flows, the limitations. Sales does not need this depth; support requires it. + +Customer-facing language for limits. Sales pitches the feature and addresses the limits at the negotiation stage. Support encounters the limits the moment a customer hits them. Support reps need pre-written language for "the feature supports up to X; for higher volumes, contact your account manager." + +Without these two, support is improvising at the moment of customer pain. Improvisation produces inconsistent answers across reps; customers compare notes and lose trust. + +--- + +## The post-launch FAQ refresh cycle + +For two to four weeks post-launch, the FAQ refreshes daily. + +- Support reps log new questions they encountered, with the answers they gave. +- PM reviews daily, approves or corrects answers, adds them to the canonical FAQ. +- Support team gets a daily summary of new FAQ entries. + +After two to four weeks, the FAQ stabilizes. The refresh moves to weekly, then monthly. + +The cost of the daily refresh is small. The benefit is that support builds confidence with the feature in the first month, instead of struggling for the first quarter. + +--- + +## When support flags an issue larger than a question + +Sometimes the support volume on a feature reveals a real problem with the feature, not just a need for better FAQ. + +Signs. + +- Many customers ask the same question, and the answer is "the feature does not do that." The customers expected something the feature does not deliver. Positioning was misaligned. +- Many customers report the same bug. The bug is real and affects a meaningful share of users. +- Support tickets cluster on a specific cohort (e.g., users on a specific plan, in a specific region). The feature does not work correctly for that cohort. + +The pattern. Support is the early-warning system for launch quality. The PM should review the support ticket digest daily during the first week and at least weekly thereafter. If the support volume reveals a feature problem, the launch may need to pause for a fix before further rollout. + +The discipline of treating support as a quality signal is the cheapest way to catch launch problems before they show up in revenue or churn metrics. diff --git a/dist/pi/.agents/skills/form-strategy/SKILL.md b/dist/pi/.agents/skills/form-strategy/SKILL.md new file mode 100644 index 0000000..75b63cb --- /dev/null +++ b/dist/pi/.agents/skills/form-strategy/SKILL.md @@ -0,0 +1,257 @@ +--- +name: form-strategy +description: "Design forms that convert, validate well, resist spam, and integrate cleanly with downstream systems. Use this skill when designing or auditing any form (contact, signup, checkout, multi-step, embedded), planning validation logic, fighting spam, choosing form tooling, or improving form conversion. Triggers on form design, form validation, form conversion, multi-step form, form spam, captcha, honeypot, form abandonment, signup form, contact form. Also triggers when form completion rates are low or spam is overwhelming." +category: cross-cutting +catalog_summary: "Form design, validation patterns, spam prevention, conversion tuning" +display_order: 1 +--- + +# Form Strategy + +Forms are where intent becomes action. Design them well or lose conversions, frustrate users, and drown in spam. Stack-agnostic. + +--- + +## When to use + +- Designing or redesigning a form +- Conversion is dropping on a key form +- Spam volume is overwhelming the inbox or database +- Auditing forms across a site +- Planning validation logic +- Choosing form tooling (form service, custom build, no-code) +- Integrating forms with CRM, email, or other downstream systems +- Multi-step form decisions + +## When NOT to use + +- Generic conversion optimization (use `cro-optimization`) +- The copy on the form (use `landing-page-copy`) +- Backend handling beyond form-specific concerns (use `frontend-component-build`, `code-review-web`) +- General accessibility (use `accessibility-audit`) + +--- + +## Required inputs + +- The form's purpose (what action, what outcome) +- Current form (URL, screenshot, or fields) +- Current performance (completion rate, spam rate, conversion to next step) +- Downstream system (where submissions go: CRM, email, database, support tool) +- Business context (volume, urgency of leads, cost of false vs missed signups) + +--- + +## The framework: 5 dimensions + +Every form decision falls into one of these dimensions. + +### Dimension 1: Field strategy + +The biggest lever. Every additional field reduces conversion. + +Questions to ask for each field: +- Is this required to deliver value to the user? +- Is this required to deliver value to the business? +- Can it be inferred from another source (email domain, behavior, context)? +- Can it be asked later (after first contact, on second visit, on settings page)? + +Default rule: ask for the minimum to make the next step happen. Everything else later. + +For a B2B contact form: name and email get you started. Phone, company size, role are nice-to-haves that often hurt conversion more than they help qualification. + +For a checkout: country, postal code, address, name, payment. Anything else (referral source, marketing opt-in, account creation) is optional or moved to post-purchase. + +### Dimension 2: Field design + +How each field looks and behaves. + +- Labels above inputs beat placeholders. Placeholder labels disappear when typing. +- Inline labels (floating labels) work for very compact forms. +- Single column for almost every form. Eyes flow vertically. +- Logical grouping with visible spacing. Don't put unrelated fields next to each other. +- Right input type: `email` for emails, `tel` for phone, `number` for numbers, `date` for dates. Mobile keyboards adapt. +- Autocomplete attributes: `autocomplete="email"`, `autocomplete="given-name"`, etc. Browsers and password managers fill them in. +- Sensible defaults for fields where one applies (country pre-selected by IP, etc.). Don't default to anything that would mislead if wrong. + +### Dimension 3: Validation + +Tell users what's wrong, when, and how to fix it. + +- Validate on blur, not on every keystroke. Inline errors that appear as someone types are jarring. +- Re-validate on submit (catch fields the user skipped). +- Specific messages: "Email must include @" beats "Invalid email." +- Position errors next to the field they refer to. +- Don't submit a form when there are errors. Highlight the first errored field. Scroll to it. +- Validate server-side too. Client validation is UX. Server validation is correctness. + +For format-flexible fields (phone numbers, postal codes), validate liberally. Reject only what's clearly wrong, not what's "non-standard." Many phone formats exist. + +### Dimension 4: Spam defense + +Public forms attract spam. Plan for it from day one. + +Layered defense: + +1. Honeypot field. A hidden field that humans don't fill in but bots do. If it's filled, reject silently. Free, low-friction, surprisingly effective for low-effort spam. +2. Time-based detection. Reject submissions completed in under 2-3 seconds (bots) or after very long delays (suspicious sessions). +3. Rate limiting. Reject if the same IP submits too many times. +4. CAPTCHA as a last resort. Modern invisible CAPTCHAs (hCaptcha, reCAPTCHA v3, Turnstile) are low-friction. Old image CAPTCHAs are conversion-killers. +5. Behavioral signals. Did the cursor move? Was there scroll? Modern services track this. +6. Content filtering. Reject obvious spam content (links, foreign-language content if your audience is local, common spam words). +7. Server-side review. A queue rather than direct delivery to inboxes for high-spam-target forms. + +For most contact forms: honeypot + time check + Turnstile (or similar) is sufficient. + +### Dimension 5: Submission flow + +What happens after submit. + +- Inline success message for short forms. Don't redirect just to confirm. +- Confirmation page for high-value submissions (to provide next steps, set expectations). +- Email confirmation for signups, purchases, RSVPs. Always. +- Save data on errors so the user doesn't re-enter everything. +- Optimistic UI (show success before the server confirms) for low-stakes forms; risky for high-stakes. + +For multi-step forms: +- Show progress (3 of 5) +- Save state between steps (in case of refresh or navigation) +- Allow back navigation without losing data +- Validate per step, not just at the end + +--- + +## Workflow + +### Step 1: Audit current state + +For each form on the site: +- What's its purpose? +- Number of fields, required vs optional +- Current completion rate +- Current spam rate +- Validation rules +- What happens after submit +- Where the data goes downstream + +### Step 2: Define success per form + +Different forms have different success metrics: +- Lead form: qualified leads (defined by sales) +- Newsletter: confirmed subscriptions (after double opt-in) +- Contact: substantive replies (not just submissions) +- Checkout: successful payments + +Track the metric that matters, not just submissions. + +### Step 3: Cut fields ruthlessly + +Apply the field strategy filter. For each field, answer: +- Required to deliver value? Keep. +- Nice to have? Move to optional or later. +- Used for routing or qualification? Often can be inferred. + +A 7-field form becomes a 3-field form. Conversion rises. + +### Step 4: Set up spam defense + +Before launching a public form: +- Add a honeypot field +- Add time-based detection +- Add rate limiting +- Add a modern CAPTCHA if the form is high-traffic or high-spam + +After launch, monitor. Tune layers based on what's actually getting through. + +### Step 5: Improve validation + +Walk through each field: +- Is validation specific? +- Does it run at the right time (blur or submit, not on keystroke)? +- Are error messages actionable? +- Is server-side validation matching client-side? + +### Step 6: Verify accessibility + +Critical baseline: +- Every input has an associated label (visually visible or `aria-label`) +- Errors are associated with inputs (`aria-describedby`, `aria-invalid`) +- Focus order matches visual order +- Color isn't the only way to indicate errors +- Form is fully keyboard-navigable + +See `accessibility-audit` for the full WCAG audit. + +### Step 7: Test downstream + +Submit the form. Verify: +- Data lands where it should +- Required fields are populated correctly +- Spam defenses are working (test with a script) +- The user gets the confirmation they expect +- Internal notification is timely + +Forms break silently when downstream systems change. Test after any integration update. + +### Step 8: Monitor + +- Completion rate over time +- Spam rate over time +- Errors per submission (high errors = bad UX) +- Drop-off field (where do people abandon?) + +--- + +## Failure patterns + +Too many fields. Most B2B contact forms have 3x more fields than they need. Cut. + +Validation that fires while typing. Annoying. Causes errors before the user has finished. + +Generic error messages. "Invalid input." Where? Why? Be specific. + +Required fields not marked. Users discover they're required only after submission fails. Mark required (or, for short forms, mark optional). + +Autocomplete disabled. "For security." It's almost never a security improvement and always a UX cost. Leave autocomplete on. + +Tab order is broken. Tab key skips fields or jumps backward. Set `tabindex` only when necessary; use natural DOM order. + +Submit button below the fold. Especially on mobile. Users don't see it. + +No save on error. User submits, has one error, returns to the form, all fields empty. Nightmare. Save the state. + +Captcha as the only spam defense. Captchas are friction. Layered defense beats brute-force friction. + +Captcha visible by default. Modern CAPTCHAs (Turnstile, reCAPTCHA v3) are invisible most of the time and only escalate when needed. Use those. + +Newsletter signup that's actually a marketing list. Honor opt-in scope. If the user signed up for product updates, don't add them to the marketing newsletter. + +Confirmation page that's a dead end. "Thanks for submitting" with no next step. What now? Provide an action (read related content, return to homepage, follow on social). + +No double opt-in for marketing email. Bots and typos pollute the list. See `email-deliverability` for why this matters. + +Email field accepting `name@` as valid. Browser spec validation is loose. Validate against an actual format. + +Custom date pickers worse than native. The native `<input type="date">` is now good on most platforms. Don't reinvent unless you have a specific reason. + +Forms that lose state on refresh. For long forms, save to localStorage and restore on load. + +--- + +## Output format + +A form audit document includes: + +- Form inventory: every form on the site +- Per-form review: purpose, fields, performance +- Recommendations: field cuts, validation improvements, spam defense, design changes +- Spam defense plan: layers per form +- Accessibility status: WCAG compliance per form +- Downstream integration map: where each form's data goes +- Monitoring plan: what's tracked + +--- + +## Reference files + +- [`references/form-anatomy-checklist.md`](references/form-anatomy-checklist.md): A field-by-field, behavior-by-behavior checklist for auditing or designing a form, covering structure, accessibility, validation, and spam defense. diff --git a/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md b/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md new file mode 100644 index 0000000..14f651f --- /dev/null +++ b/dist/pi/.agents/skills/form-strategy/references/form-anatomy-checklist.md @@ -0,0 +1,243 @@ +# Form Anatomy Checklist + +A field-by-field, behavior-by-behavior checklist for auditing or designing a form. Walk through it for any form before shipping. + +--- + +## Overall structure + +- [ ] Purpose is clear from headline, subheadline, or surrounding context +- [ ] Single column layout (multi-column forms are slower to scan and complete) +- [ ] Form is reasonably short (cut fields you don't strictly need) +- [ ] Required vs optional is clear (mark one or the other based on which is shorter) +- [ ] Logical grouping of related fields with visible spacing +- [ ] Submit button is visible without scrolling on common viewports +- [ ] Submit button text is specific to the action ("Get the report" beats "Submit") + +--- + +## Per-field checklist + +For each field, verify: + +### Label + +- [ ] Has a visible label (or, for compact forms, a clearly associated visible cue) +- [ ] Label is above the input (preferred) or floats (acceptable for compact) +- [ ] Label is descriptive (not just the field name from the database) +- [ ] Label is associated with the input via `for=` and `id=` or a wrapping `<label>` + +### Input type + +- [ ] Uses semantic input type: + - `email` for emails + - `tel` for phone + - `number` for numeric (when not formatted, like a count or amount) + - `date` for dates + - `url` for URLs + - `text` for general +- [ ] Native input where possible (date, color, range) before custom widgets +- [ ] `inputmode` attribute set when it differs from type (e.g., `inputmode="decimal"` on a price) + +### Autocomplete + +- [ ] `autocomplete=` attribute set with the appropriate value + - `name`, `given-name`, `family-name` + - `email` + - `tel` + - `street-address`, `address-line1`, `postal-code`, `country` + - `cc-name`, `cc-number`, `cc-exp`, `cc-csc` + - `current-password`, `new-password` +- [ ] Doesn't disable autocomplete without good reason + +### Validation + +- [ ] Validates on blur, not on every keystroke +- [ ] Validates again on submit (in case fields were skipped) +- [ ] Error message is specific ("Email must include @" not "Invalid") +- [ ] Error message appears next to the field +- [ ] Error state is visually distinct (not just color; also icon or pattern) +- [ ] `aria-invalid="true"` on errored fields +- [ ] `aria-describedby` linking the field to its error message + +### Server-side validation + +- [ ] Server validates everything client validates (client validation is UX, server is correctness) +- [ ] Server validates fields the client can't (uniqueness, business rules, etc.) +- [ ] Server returns specific error messages +- [ ] Server is the source of truth for "save" + +### Hint text + +- [ ] If a field needs explanation, hint text is below the field (not in placeholder) +- [ ] Hint text uses `aria-describedby` to associate with the input +- [ ] Hint text doesn't contain critical info that would be missed if not read + +### Required vs optional + +- [ ] Marked clearly (consistently use either "required" markers or "optional" markers, not both) +- [ ] `required` attribute set on truly required fields +- [ ] Required fields announced to assistive tech (the `required` attribute does this) +- [ ] Field has a fallback if accidentally skipped (server validation catches it gracefully) + +### Width + +- [ ] Field width matches expected input length (don't make a postal code field as wide as a name field) +- [ ] Mobile field width is full-width minus reasonable margins + +### Specific field types + +Password: +- [ ] `autocomplete="current-password"` for login, `"new-password"` for signup +- [ ] Toggle to show password (not in lieu of, but in addition to, dots) +- [ ] Length and complexity hints visible before typing +- [ ] Allow long passphrases (no max length under 64+ chars) + +Email: +- [ ] `type="email"` and `autocomplete="email"` +- [ ] Server validates format more strictly than the browser default +- [ ] Confirms for high-stakes use (with a second email field) or relies on confirmation email + +Phone: +- [ ] `type="tel"` and `autocomplete="tel"` +- [ ] Liberal validation (accept various formats) +- [ ] Country code handling if international + +Date: +- [ ] `type="date"` for native picker, or a well-tested custom picker +- [ ] Timezone handling thought through (server side) + +Address: +- [ ] Multiple fields (line 1, line 2, city, region, postal code, country) +- [ ] `autocomplete` on each +- [ ] Validation by country (US ZIP differs from UK postcode) +- [ ] Optional autocomplete via address API for high-conversion forms + +File upload: +- [ ] Accepted types declared with `accept=` +- [ ] Size limit communicated and enforced (client and server) +- [ ] Drag-and-drop and click-to-browse both work +- [ ] Selected file feedback (name, size, preview if image) +- [ ] Progress indicator for slow uploads +- [ ] Server scans uploads if user-generated content goes public + +Select / dropdown: +- [ ] Native `<select>` for short lists (under ~15 options) +- [ ] Custom searchable component for long lists +- [ ] Default option that's not selectable (e.g., "Select a country") +- [ ] Sort by likelihood (popular options first), or alphabetical, not random + +Radio buttons: +- [ ] Use for 2-7 mutually exclusive options +- [ ] All options visible (no scrolling) +- [ ] One option pre-selected only if a sensible default exists + +Checkboxes: +- [ ] Use for boolean choices and multi-select +- [ ] Label is clickable (associated with checkbox) +- [ ] Marketing opt-ins are off by default (legal requirement in many regions) +- [ ] Terms-of-service is unchecked by default (active acceptance) + +Multi-step forms: +- [ ] Progress indicator (3 of 5) +- [ ] State saved between steps (refresh-resilient) +- [ ] Back navigation doesn't lose data +- [ ] Validation per step +- [ ] Final review step before submit (high-stakes only) + +--- + +## Spam defense + +- [ ] Honeypot field (hidden, must remain empty) +- [ ] Time-based detection (reject very fast or very slow submissions) +- [ ] Rate limiting per IP / per session +- [ ] Modern CAPTCHA (Turnstile, hCaptcha invisible, reCAPTCHA v3) if needed +- [ ] Server-side spam content filtering for high-volume forms +- [ ] Logging of rejected submissions for tuning + +--- + +## Accessibility + +- [ ] Form is fully keyboard-navigable (Tab, Shift+Tab, Enter to submit) +- [ ] Tab order matches visual order +- [ ] Focus is visible (don't remove the focus outline) +- [ ] Form errors are announced to screen readers +- [ ] Color contrast meets WCAG (4.5:1 for text, 3:1 for UI) +- [ ] Errors aren't communicated only by color +- [ ] Form works at 200% zoom +- [ ] Touch targets at least 44px on mobile +- [ ] No time limits without warning and the option to extend + +--- + +## Submission + +- [ ] Submit button is disabled while submission is in flight (prevent double-submit) +- [ ] Loading state on the button or near the form +- [ ] Success state is clear (inline message, redirect to confirmation page, or both) +- [ ] Failure state is clear (specific reason, what to do, support contact) +- [ ] State preserved on submission failure (user doesn't lose data) +- [ ] Email confirmation sent for signups, purchases, RSVPs +- [ ] Internal notification (if applicable) is timely + +--- + +## Privacy and compliance + +- [ ] Privacy notice or link visible near the form +- [ ] Terms of service link if relevant +- [ ] Marketing consent (where required by jurisdiction) is explicit and unchecked by default +- [ ] Data sent over HTTPS only +- [ ] Sensitive fields (passwords, payment) not autofilled by URL params (don't appear in browser history) + +--- + +## Performance + +- [ ] Form loads quickly (lazy-load any heavy assets like CAPTCHAs until needed) +- [ ] Submit handler doesn't block the UI +- [ ] No unnecessary fetches on field interaction +- [ ] CAPTCHA loads asynchronously + +--- + +## Monitoring + +- [ ] Completion rate tracked +- [ ] Field-level drop-off tracked (where do people abandon?) +- [ ] Errors tracked (which fields cause the most errors?) +- [ ] Spam rate tracked (compare layers of defense over time) +- [ ] Submission failures tracked (server errors, integration failures) + +--- + +## Pre-launch test + +Before publishing a form publicly: + +- [ ] Submit successfully with valid data +- [ ] Submit unsuccessfully with bad data (verify error UX) +- [ ] Submit with no data (verify required-field UX) +- [ ] Submit with the honeypot filled (verify silent rejection) +- [ ] Submit very fast (verify time-based rejection) +- [ ] Submit on mobile (verify mobile UX) +- [ ] Submit with keyboard only (verify accessibility) +- [ ] Submit with a screen reader (verify announcements) +- [ ] Submit with autocomplete enabled (verify it works) +- [ ] Verify data lands in the correct downstream system +- [ ] Verify confirmation email arrives (if applicable) +- [ ] Verify internal notification arrives (if applicable) +- [ ] Try to submit duplicate (verify deduplication if applicable) + +--- + +## Post-launch review (after first week) + +- [ ] Completion rate vs target +- [ ] Spam rate (tune defense if needed) +- [ ] Errors (most common errors? could be UX problems) +- [ ] Drop-off (which field loses people?) +- [ ] Downstream system happy? (CRM data clean, no broken integrations) +- [ ] Customer reports (anyone reporting a broken form?) diff --git a/dist/pi/.agents/skills/frontend-component-build/SKILL.md b/dist/pi/.agents/skills/frontend-component-build/SKILL.md new file mode 100644 index 0000000..fb5f5f7 --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/SKILL.md @@ -0,0 +1,184 @@ +--- +name: frontend-component-build +description: "Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with proper states and accessibility. Triggers on build a component, create a button, create a modal, create a form input, component API, props design, component states, refactor component, accessible component. Also triggers when implementing UI from a design that needs to be reusable." +category: development +catalog_summary: "Component architecture, props design, accessibility from the start" +display_order: 2 +--- + +# Frontend Component Build + +Build production-ready components. Stack-agnostic principles. Most patterns translate to React, Vue, Svelte, or vanilla web components. + +This skill is about implementing a component well. For broader system design see `design-system`. For day-to-day visual decisions see `design-standards`. + +--- + +## When to use + +- Building a new component from scratch +- Refactoring an existing component +- Designing a component API (props, slots, events) +- Adding accessibility to an existing component +- Implementing a component from a design + +## When NOT to use + +- Building a full design system (use `design-system`) +- Page-level design decisions (use `design-standards`) +- Backend or data work (use `code-review-web`) +- Performance-only optimization (use `performance-optimization`) + +--- + +## Required inputs + +- The component's purpose (what UI need it serves) +- The design (or willingness to design it) +- The framework or technical context +- The states the component must support +- Accessibility requirements + +--- + +## The framework: 6 dimensions + +A complete component handles six dimensions. Skip any one and the component is incomplete. + +### 1. Anatomy + +Identify the parts that make up the component before writing any markup. + +Common anatomies: +- Button: container + label + (optional) icon + (optional) loading indicator +- Modal: backdrop + container + header + body + footer + close affordance +- Form input: label + input + (optional) help text + (optional) error message +- Card: container + (optional) header + body + (optional) footer + (optional) media + +Naming the parts up front makes the API obvious. + +### 2. Variants + +What variations does the component support? + +- Visual variants (primary, secondary, ghost, danger) +- Size variants (small, medium, large) +- Functional variants (with icon, without icon, icon-only) + +Variants should be a managed set, not a free-for-all. Document the supported set; reject requests for new variants without a real use case. + +### 3. States + +What states must the component handle? + +- Default +- Hover (when pointer is supported) +- Focus (always - keyboard navigation requires it) +- Active / pressed +- Disabled +- Loading (where applicable) +- Error (for inputs, forms, validation-bound components) +- Empty (for components that display data) + +Every state needs visual treatment AND accessibility treatment. + +### 4. Props / API + +Design the component's contract. + +API design principles: + +- Required props minimal. What's truly needed every time? That's required. Everything else has a sensible default. +- Boolean props are red flags. Three booleans means seven combinations. Prefer enum strings: `variant: "primary" \| "secondary" \| "ghost"` over `primary={true} ghost={false}`. +- Children > props. Where content is content, accept children. Don't invent `headerText` and `bodyText` props when slots work. +- Composition > configuration. A component that does 5 things via 12 props often should be 5 smaller components. +- Type the props. TypeScript or PropTypes or JSDoc. The type is documentation that won't go out of date. + +### 5. Accessibility + +Build it accessible from the start. Adding accessibility later is 5x harder. + +Universal: +- Semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<form>`, etc.) over generic `<div>` +- Keyboard navigable (Tab, Shift+Tab, Enter/Space for buttons) +- Focus visible +- Tap targets minimum 44 by 44 pixels +- ARIA only where semantic HTML is insufficient + +Component-specific: + +- Button: use `<button>`. Don't fake one with a `<div>`. +- Modal: focus trap, ESC to close, returns focus to trigger on close, `role="dialog"` and `aria-labelledby`. +- Form input: label associated via `for`/`id` or `aria-labelledby`. Error messages linked via `aria-describedby`. `aria-invalid` when in error state. +- Toggles: `<button>` with `aria-pressed` for two-state, or `role="switch"` for on/off. +- Tabs: `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected` and arrow-key navigation. +- Tooltips and popovers: triggered by focus AND hover. Dismissible with ESC. +- Loading states: announce with `aria-live` so screen readers know something changed. + +### 6. Tests + +Verify the component works before declaring it done. + +Test types by priority: + +1. Visual regression. Renders correctly across variants and states. (Storybook + visual diff tools, or manual screenshots.) +2. Accessibility. Passes axe or equivalent automated checks. +3. Keyboard navigation. Tab, Enter, Escape, arrow keys all work as expected. +4. Component logic. Props produce expected output. Events fire correctly. (Unit tests.) +5. Integration. Component works inside its expected parent contexts. + +A component without at least automated accessibility testing is not done. + +--- + +## Workflow + +1. Understand the use case. What UI need does this component serve? Where will it appear? Adjacent components? +2. Sketch the anatomy. Name the parts. +3. List variants and states. Match the design system or define new ones if needed. +4. Design the API. Required props, optional props, children, events. Type it. +5. Build the markup with semantic HTML. Choose the right elements. Avoid generic `<div>` for interactive things. +6. Style with tokens. No hardcoded colors, spacing, or sizes. +7. Add interaction. Focus management, keyboard handlers, ARIA. +8. Add states. Hover, focus, active, disabled, loading, error. +9. Test. Automated accessibility, keyboard navigation, visual regression. +10. Document. Usage, API, examples, anti-patterns. + +--- + +## Failure patterns + +- Building with `<div onClick>`. Loses keyboard accessibility, screen reader semantics, and focus. Use `<button>` or `<a>`. +- Hardcoding colors and sizes. Tokens exist for a reason. Hardcoded values resist theming and consistency. +- Boolean prop explosion. `<Button primary large rounded fullWidth disabled icon />`. Too many booleans means you actually need fewer variants designed more thoughtfully. +- Forgetting focus states. Hover gets attention; focus gets neglected. Keyboard users see invisible buttons. +- Skipping disabled-state thought. A disabled button should look obviously disabled AND be `aria-disabled` AND not respond to clicks. +- Inventing ARIA. ARIA roles and properties have specific behaviors. Made-up ARIA is worse than no ARIA. Use semantic HTML first. +- Loading state that doesn't announce. Screen readers don't know the spinner appeared. Use `aria-live="polite"` or `role="status"`. +- Tooltip-only critical content. Hover-only content is invisible to keyboard and touch users. Critical content goes in the visible UI. +- Component without docs. Future-you, your teammate, or the next maintainer cannot use what they cannot understand. + +--- + +## Output format + +A complete component delivery includes: + +- Component code (in the appropriate framework) +- Storybook (or equivalent) entry showing all variants and states +- Documentation: + - Anatomy diagram or description + - Props/API table + - Usage examples (basic, advanced, edge cases) + - When to use vs. when to use an alternative + - Anti-patterns (what to avoid) + - Accessibility notes +- Tests (visual regression + accessibility + logic) + +--- + +## Reference files + +- [`references/component-spec-template.md`](references/component-spec-template.md) - Template for documenting a component (props, states, accessibility, edge cases) before building. +- [`references/component-api-patterns.md`](references/component-api-patterns.md) - Common patterns for designing flexible component APIs (compound components, controlled vs uncontrolled, polymorphic `as` prop, render props, slots). +- [`references/accessibility-patterns.md`](references/accessibility-patterns.md) - ARIA patterns for common interactive components. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md b/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md new file mode 100644 index 0000000..d32ab58 --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/accessibility-patterns.md @@ -0,0 +1,354 @@ +# Accessibility Patterns + +ARIA patterns for common interactive components. Each follows the WAI-ARIA Authoring Practices guidelines. + +When in doubt, use semantic HTML. Reach for ARIA only when semantic HTML cannot express what's needed. + +--- + +## Button + +```html +<button type="button"> + Click me +</button> +``` + +That's it. Don't reinvent it. + +For buttons that toggle a state: +```html +<button type="button" aria-pressed="false"> + Bookmark +</button> +``` +Toggle `aria-pressed` between `"true"` and `"false"` on click. + +For buttons that disclose content: +```html +<button type="button" aria-expanded="false" aria-controls="menu-1"> + Menu +</button> +<ul id="menu-1" hidden>...</ul> +``` +Toggle `aria-expanded` and `hidden` together. + +Anti-patterns: +- `<div onClick>` instead of `<button>` +- Buttons that look like buttons but use `<a href="#">` +- Missing `type="button"` (defaults to `type="submit"` inside forms, causing accidental submits) + +--- + +## Link + +```html +<a href="/destination"> + Link text +</a> +``` + +For external links opening in new tab: +```html +<a href="https://external.com" target="_blank" rel="noopener noreferrer"> + External site +</a> +``` + +Anti-patterns: +- `<a>` without `href` (breaks keyboard navigation; use `<button>` instead) +- `<a href="#">` for buttons (causes URL pollution and unexpected behavior) +- Generic link text ("click here," "read more") + +--- + +## Form input with label + +```html +<div> + <label for="email">Email address</label> + <input id="email" type="email" name="email" required /> + <p id="email-help">We'll never share your email.</p> +</div> +``` + +With help text linked: +```html +<input id="email" type="email" aria-describedby="email-help" /> +<p id="email-help">We'll never share your email.</p> +``` + +With error state: +```html +<input + id="email" + type="email" + aria-invalid="true" + aria-describedby="email-error" +/> +<p id="email-error" role="alert">Please enter a valid email.</p> +``` + +Anti-patterns: +- Placeholder as label (placeholder disappears on input, leaving field unlabeled) +- Label not associated (visual proximity isn't enough) +- Error indicated by color only (color-blind users miss it) + +--- + +## Modal / dialog + +```html +<div + role="dialog" + aria-modal="true" + aria-labelledby="dialog-title" + aria-describedby="dialog-description" +> + <h2 id="dialog-title">Confirm action</h2> + <p id="dialog-description">Are you sure you want to delete this?</p> + <button type="button" data-close>Cancel</button> + <button type="button" data-confirm>Delete</button> +</div> +``` + +Behavior requirements: +- Trap focus inside the modal while open +- Return focus to the trigger element on close +- Close on Escape key +- Close on backdrop click (optional, but expected) +- Background content should be inert (`inert` attribute or `aria-hidden`) +- Body scroll locked while modal is open + +Anti-patterns: +- Modal without focus trap (Tab escapes to background page) +- Modal without `aria-modal` and `role="dialog"` +- Modal that doesn't return focus on close +- Background content remains tabbable + +--- + +## Disclosure (accordion section) + +```html +<button + type="button" + aria-expanded="false" + aria-controls="section-1" +> + Section title +</button> +<div id="section-1" hidden> + Section content... +</div> +``` + +For full accordion (multiple disclosures, optionally limit one open at a time), repeat the pattern. + +--- + +## Tabs + +```html +<div role="tablist" aria-label="Settings sections"> + <button + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0" + > + Profile + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1" + > + Notifications + </button> +</div> + +<div role="tabpanel" id="panel-1" aria-labelledby="tab-1"> + Profile content... +</div> +<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden> + Notifications content... +</div> +``` + +Behavior requirements: +- Arrow keys navigate between tabs +- Active tab has `aria-selected="true"` and `tabindex="0"` +- Inactive tabs have `aria-selected="false"` and `tabindex="-1"` +- Selecting a tab shows the corresponding panel +- Home / End keys jump to first / last tab + +--- + +## Toggle switch + +```html +<button + type="button" + role="switch" + aria-checked="false" + id="darkmode-toggle" +> + <span class="visually-hidden">Dark mode</span> +</button> +<label for="darkmode-toggle">Dark mode</label> +``` + +Toggle `aria-checked` between `"true"` and `"false"` on click. + +Alternatively, use a real checkbox styled as a switch: +```html +<label> + <input type="checkbox" role="switch" /> + Dark mode +</label> +``` + +--- + +## Combobox / autocomplete + +```html +<label for="city">City</label> +<input + id="city" + type="text" + role="combobox" + aria-autocomplete="list" + aria-controls="city-listbox" + aria-expanded="false" + autocomplete="off" +/> +<ul id="city-listbox" role="listbox" hidden> + <li role="option" id="city-1" aria-selected="false">London</li> + <li role="option" id="city-2" aria-selected="false">Lagos</li> +</ul> +``` + +Behavior requirements: +- Down arrow opens listbox +- Arrow keys navigate options +- Enter selects highlighted option +- Escape closes listbox +- `aria-activedescendant` on the input points to highlighted option +- Type-ahead filtering + +This is one of the most complex patterns. Test thoroughly with screen readers. + +--- + +## Menu / menubar + +```html +<button + type="button" + aria-haspopup="menu" + aria-expanded="false" + aria-controls="user-menu" +> + Account +</button> +<ul role="menu" id="user-menu" hidden> + <li role="menuitem" tabindex="-1"><a href="/profile">Profile</a></li> + <li role="menuitem" tabindex="-1"><a href="/settings">Settings</a></li> + <li role="menuitem" tabindex="-1"><a href="/logout">Sign out</a></li> +</ul> +``` + +Behavior requirements: +- Down arrow / up arrow navigate menu items +- Escape closes menu +- Click outside closes menu +- Focus returns to trigger on close + +Important: `role="menu"` is for command-style menus (like a desktop application's File menu). For navigation, use `<nav>` with regular links instead. + +--- + +## Loading and live regions + +```html +<div role="status" aria-live="polite"> + Loading results... +</div> +``` + +Use `role="status"` (or `aria-live="polite"`) for non-urgent updates. +Use `role="alert"` (or `aria-live="assertive"`) for urgent errors. + +Anti-patterns: +- Spinners with no announcement (screen readers don't know anything changed) +- Live regions that announce too aggressively (`aria-live="assertive"` for non-critical updates) + +--- + +## Skip link + +```html +<a href="#main-content" class="skip-link">Skip to main content</a> +... +<main id="main-content">...</main> +``` + +CSS: +```css +.skip-link { + position: absolute; + top: -100px; + left: 0; +} +.skip-link:focus { + top: 0; +} +``` + +The skip link should be the first focusable element on the page. Visible only when focused. + +--- + +## Visually hidden but available to screen readers + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +Use for content that screen readers need but sighted users don't (e.g., the label of an icon-only button). + +```html +<button type="button"> + <SearchIcon aria-hidden="true" /> + <span class="visually-hidden">Search</span> +</button> +``` + +Anti-pattern: `display: none` or `visibility: hidden` removes content from the accessibility tree too. Use `visually-hidden` for content meant for screen readers only. + +--- + +## Generic notes + +- Test with a real screen reader. VoiceOver (macOS, iOS) and NVDA (Windows) are free. +- Test with keyboard alone. Unplug the mouse. Can you accomplish the task? +- Run automated tests. axe DevTools, Lighthouse, WAVE catch the basics. +- Don't fake elements that exist. A `<div role="button">` is worse than a `<button>`. +- Less ARIA is more. Most components need little or no ARIA. Semantic HTML does the work. + +For deep accessibility audits, use `accessibility-audit`. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md b/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md new file mode 100644 index 0000000..96283bc --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/component-api-patterns.md @@ -0,0 +1,311 @@ +# Component API Patterns + +Common patterns for building flexible, predictable component APIs. Examples assume React idioms but the patterns translate to Vue, Svelte, and Web Components. + +--- + +## Pattern 1: Compound components + +Multi-part components where each part is a separate sub-component sharing state via context. + +Use when: +- The component has distinct, repeating sub-parts (header, body, footer) +- Consumers need flexibility in arrangement and content +- Internal state needs to coordinate across parts + +```jsx +<Card> + <Card.Header>Title</Card.Header> + <Card.Body> + <Text>Content</Text> + </Card.Body> + <Card.Footer> + <Button>Action</Button> + </Card.Footer> +</Card> +``` + +Pros: +- Highly composable +- Consumers control arrangement +- Internal state stays encapsulated + +Cons: +- More API surface to maintain +- Less guidance for the consumer (any arrangement is "valid") + +--- + +## Pattern 2: Slots / render children + +A single component that accepts content through specific slots. + +Use when: +- The component has one or two specific insertion points +- Compound components feel like overkill + +```jsx +<Modal + title="Confirm action" + footer={<Button>Confirm</Button>} +> + <p>Are you sure?</p> +</Modal> +``` + +In Web Components: `<slot name="title">`. In Vue: named slots. In React: prop-as-element. + +Pros: +- Smaller API surface than compound components +- Clear insertion points + +Cons: +- Less flexible if the consumer wants to vary arrangement + +--- + +## Pattern 3: Render props / function as children + +The component provides state, the consumer provides UI. + +Use when: +- The component has reusable behavior (e.g., dropdown logic) +- Multiple visual variations should share the behavior +- Headless component libraries (Radix, Headless UI) use this heavily + +```jsx +<Dropdown> + {({ isOpen, toggle, items }) => ( + <> + <button onClick={toggle}>Menu</button> + {isOpen && <ul>{items.map(item => <li>{item}</li>)}</ul>} + </> + )} +</Dropdown> +``` + +Pros: +- Maximum flexibility +- Behavior and presentation cleanly separated + +Cons: +- Steeper learning curve +- More boilerplate at the call site + +--- + +## Pattern 4: Headless components + +Components that ship behavior and accessibility without prescribing visual style. + +Use when: +- Multiple consumers want different looks +- Accessibility is hard and worth centralizing +- Building a primitive layer + +```jsx +// Headless: behavior + accessibility, no visual style +<Listbox value={selected} onChange={setSelected}> + <Listbox.Button>{selected}</Listbox.Button> + <Listbox.Options> + {options.map(option => ( + <Listbox.Option key={option} value={option}>{option}</Listbox.Option> + ))} + </Listbox.Options> +</Listbox> +``` + +The consumer styles each part however they want. + +Pros: +- Reusable across visual styles +- Accessibility hard work centralized + +Cons: +- Consumers must style every part +- Less batteries-included + +--- + +## Pattern 5: Controlled vs uncontrolled + +Two modes: + +Uncontrolled (component owns its state): +```jsx +<Input defaultValue="initial" onChange={handleChange} /> +``` + +Controlled (consumer owns the state): +```jsx +<Input value={value} onChange={setValue} /> +``` + +Pattern: Support both. Uncontrolled is convenient for simple cases. Controlled is required when state needs to live in the parent. + +```jsx +function Input({ value, defaultValue, onChange, ...props }) { + const isControlled = value !== undefined; + const [internalValue, setInternalValue] = useState(defaultValue); + const currentValue = isControlled ? value : internalValue; + + const handleChange = (e) => { + if (!isControlled) setInternalValue(e.target.value); + onChange?.(e); + }; + + return <input value={currentValue} onChange={handleChange} {...props} />; +} +``` + +Convention: `value` for controlled, `defaultValue` for uncontrolled. Documented behavior when both are provided (typically: warn, treat as controlled). + +--- + +## Pattern 6: Polymorphic components (the `as` prop) + +A component that can render as different HTML elements while preserving its API. + +Use when: +- Visual style should apply to multiple HTML elements (e.g., a Heading that could be h1, h2, etc.) +- Consumers occasionally need to override the rendered element + +```jsx +<Text as="h1">Page title</Text> +<Text as="span">Inline text</Text> +<Text as="a" href="/path">Link</Text> +``` + +Pros: +- Style and semantics decoupled when needed + +Cons: +- Type complexity (TypeScript polymorphic types are non-trivial) +- Easy to misuse (rendering an h1 styled as a span breaks structure) + +Use sparingly. The default rendered element should fit most cases. + +--- + +## Pattern 7: Context for cross-component state + +When sub-components in a tree need shared state, use context. Don't drill props. + +```jsx +const TabContext = createContext(); + +function Tabs({ children, defaultIndex = 0 }) { + const [activeIndex, setActiveIndex] = useState(defaultIndex); + return ( + <TabContext.Provider value={{ activeIndex, setActiveIndex }}> + {children} + </TabContext.Provider> + ); +} + +function Tab({ index, children }) { + const { activeIndex, setActiveIndex } = useContext(TabContext); + return ( + <button + role="tab" + aria-selected={activeIndex === index} + onClick={() => setActiveIndex(index)} + > + {children} + </button> + ); +} +``` + +Convention: Context tied to a specific component family. Don't overload one context across unrelated components. + +--- + +## Pattern 8: forwardRef and ref forwarding + +Components should pass refs through to their underlying DOM element when reasonable. + +```jsx +const Button = forwardRef(function Button({ children, ...props }, ref) { + return <button ref={ref} {...props}>{children}</button>; +}); +``` + +Why: +- Consumers need DOM access (focus, measure, scroll) +- Form libraries need refs to inputs +- Animation libraries need refs to elements + +Convention: Forward refs on any component that wraps a single primary DOM element. Document where the ref attaches. + +--- + +## Pattern 9: Variant / size enums via discriminated unions + +Use string enums for variant and size props. + +```typescript +type ButtonProps = { + variant?: 'primary' \| 'secondary' \| 'ghost' \| 'danger'; + size?: 'sm' \| 'md' \| 'lg'; + // ... +}; +``` + +Why: +- Self-documenting +- Type-safe +- Consumers see options via autocomplete + +Anti-pattern: Boolean variant props. + +```typescript +// Bad +type ButtonProps = { + primary?: boolean; + secondary?: boolean; + danger?: boolean; +}; +``` + +Boolean variants permit invalid combinations (`primary={true} danger={true}`). + +--- + +## Pattern 10: Event handler conventions + +\| Convention \| Example \| +\|---\|---\| +\| `onX` for events \| `onClick`, `onChange`, `onClose` \| +\| `onXChange` for state changes \| `onValueChange`, `onOpenChange` \| +\| Pass event object as first arg \| `onClick(event)` \| +\| For state changes, pass new state as first arg \| `onOpenChange(isOpen)` \| + +Anti-patterns: +- `handleClick` as a prop name (consumer confusion - this is the implementation, not the API) +- `change` instead of `onChange` +- Passing transformed event without the original + +--- + +## API audit checklist + +Before shipping a component: + +- [ ] Default behavior is reasonable with zero props +- [ ] Variant prop uses string enum, not booleans +- [ ] Size prop uses string enum, not numbers (when sizes are constrained) +- [ ] Event handlers use `onX` convention +- [ ] Required props are minimal (ideally zero, often one) +- [ ] Optional props document defaults +- [ ] Component is forwardable (refs work) +- [ ] Polymorphic only where genuinely useful +- [ ] No boolean explosion (more than 5 booleans is a smell) +- [ ] State is controllable when it makes sense (controlled/uncontrolled support) +- [ ] Accessibility props are first-class (`aria-label`, `aria-describedby`, etc.) +- [ ] className/style override pattern documented +- [ ] All variants have visual examples in docs +- [ ] All states have visual examples in docs +- [ ] Keyboard interactions documented + +If any item fails, the API needs another pass before ship. diff --git a/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md b/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md new file mode 100644 index 0000000..bae7d3f --- /dev/null +++ b/dist/pi/.agents/skills/frontend-component-build/references/component-spec-template.md @@ -0,0 +1,250 @@ +# Component Spec Template + +Fillable template for documenting a component before writing code. The cost of writing a spec is small. The cost of building, shipping, and rebuilding a component because the API was wrong is large. + +Fill every section. If a section is "N/A", say why. + +--- + +## Identity + +Component name: [PascalCase. e.g., `Button`, `DatePicker`, `DropdownMenu`] +Layer: [Primitive / Pattern / Template] +Status: [Proposal / Draft / In review / Production] +Owner: [Name] +Related components: [Sibling components, parent components, components this composes or replaces] + +--- + +## Purpose + +One paragraph. What this component does, who uses it, and why it exists at all. + +If you cannot articulate why this is a system component (vs a one-off in product code), it should not be in the system yet. + +> [Purpose statement] + +--- + +## Use cases + +List the real, concrete use cases this component must serve. If the list is empty or hypothetical, the component is premature. + +1. [Specific scenario, e.g., "Submit a form on the checkout page"] +2. [Specific scenario] +3. [Specific scenario] + +### Anti-use cases + +When NOT to use this component. Helps consumers pick the right primitive. + +- [Scenario, e.g., "Triggering navigation - use `Link` instead"] +- [Scenario] + +--- + +## API + +### Props + +\| Prop \| Type \| Default \| Required \| Description \| +\|---\|---\|---\|---\|---\| +\| `variant` \| `'primary' \\| 'secondary' \\| 'ghost'` \| `'primary'` \| No \| Visual treatment \| +\| `size` \| `'sm' \\| 'md' \\| 'lg'` \| `'md'` \| No \| \| +\| `disabled` \| `boolean` \| `false` \| No \| \| +\| `loading` \| `boolean` \| `false` \| No \| Shows spinner; auto-disables interaction \| +\| `leadingIcon` \| `ReactNode` \| - \| No \| \| +\| `trailingIcon` \| `ReactNode` \| - \| No \| \| +\| `as` \| `ElementType` \| `'button'` \| No \| Polymorphic root element \| +\| `onClick` \| `(e: MouseEvent) => void` \| - \| No \| \| +\| `children` \| `ReactNode` \| - \| Yes \| Visible label \| +\| (etc.) \| \| \| \| \| + +### Slots / composition + +If this is a compound component, describe each sub-component and its role. + +\| Slot / sub-component \| Purpose \| Required \| +\|---\|---\|---\| +\| `Card.Header` \| Title and optional icon \| No \| +\| `Card.Body` \| Main content \| Yes \| +\| `Card.Footer` \| Actions \| No \| + +### Events + +\| Event \| Payload \| When fires \| +\|---\|---\|---\| +\| `onChange` \| `{ value: string }` \| User changes value, on blur or on each keystroke depending on `mode` prop \| + +### Refs / imperative handles + +If the component exposes imperative methods, list them. + +\| Method \| Signature \| Purpose \| +\|---\|---\|---\| +\| `focus` \| `() => void` \| Move focus to the component's primary interactive element \| + +--- + +## States + +List every state the component can be in. Each state needs a visual treatment. + +\| State \| Visual \| Trigger \| +\|---\|---\|---\| +\| Default \| \| Initial render \| +\| Hover \| \| Pointer over (non-touch) \| +\| Focus \| \| Keyboard focus \| +\| Active / pressed \| \| Mouse down or `Enter`/`Space` \| +\| Disabled \| \| `disabled` prop true \| +\| Loading \| \| `loading` prop true \| +\| Error \| \| Error context (validation failure, API error) \| +\| Empty / no data \| \| (For data-bearing components) \| +\| Read-only \| \| (For form inputs) \| + +### State combinations + +Some states combine. Document the priority rules. + +- Loading + disabled: spinner shows, looks disabled. +- Error + focus: focus ring shows in error color. +- (etc.) + +--- + +## Accessibility + +This section is non-negotiable. Every interactive component has an accessibility section. If the component is decorative, say so explicitly. + +### Role and semantics + +- Native element: [What HTML element is the root, e.g., `<button>`, `<input type="text">`] +- ARIA role (if not native): [e.g., `role="dialog"`] +- Label requirement: [How is the accessible name set? `aria-label`, visible label, etc.] + +### Keyboard interaction + +\| Key \| Action \| +\|---\|---\| +\| `Tab` \| \| +\| `Shift + Tab` \| \| +\| `Enter` \| \| +\| `Space` \| \| +\| `Escape` \| \| +\| `Arrow keys` \| \| +\| `Home / End` \| \| + +### Screen reader behavior + +- What is announced on focus? +- What is announced on state change (loading, error)? +- Are there `aria-live` regions for status updates? + +### Focus management + +- Where does focus go on mount? On unmount? +- Is focus trapped (e.g., modals)? +- Is focus visible (focus ring)? + +### Color contrast + +Confirm WCAG AA at minimum (3:1 for non-text, 4.5:1 for body text, 3:1 for large text). Note any state where contrast is at risk (disabled state often fails AA on purpose; document the choice). + +### Touch target size + +- Minimum 44x44px on mobile (WCAG 2.5.5). +- Document if smaller and why. + +--- + +## Edge cases + +The cases that always come up after launch. Document them now. + +- [ ] Empty content: What if `children` is empty? +- [ ] Very long content: What if the label is 200 characters? Truncate, wrap, or expand? +- [ ] No data: For data-bearing components, what does the empty state look like? +- [ ] Loading: What does the loading state look like? Skeleton? Spinner? Disabled? +- [ ] Error: Inline error? Toast? Both? +- [ ] Disabled with tooltip: A disabled `<button>` cannot receive focus, so a tooltip explaining why it is disabled needs special handling. +- [ ] Right-to-left: Does the layout flip correctly? +- [ ] High zoom (200%): Does the layout hold? +- [ ] Dark mode: Are tokens used so dark mode works automatically? +- [ ] Reduced motion: Are animations disabled when `prefers-reduced-motion: reduce`? + +--- + +## Variants and customization + +### Built-in variants + +What variants ship out of the box (`size`, `variant`, etc.). Document each. + +### Customization API + +How can consumers customize without forking? `className` pass-through? Style props? Slots? CSS custom properties? + +### What is NOT customizable + +Be explicit about what consumers cannot override. This is the system's stance, not a bug. + +--- + +## Internationalization + +- [ ] Text is via prop or children (not hardcoded) +- [ ] Plural and count formatting uses `Intl.PluralRules` +- [ ] Date / time formatting uses `Intl.DateTimeFormat` +- [ ] Layout works in RTL (logical properties: `margin-inline-start`, `padding-inline-end`) +- [ ] Bidirectional text (mixed LTR / RTL strings) handled + +--- + +## Performance + +- Bundle weight target: [KB compressed] +- Render cost: [Should be cheap. If expensive, document why.] +- Re-render risk: [Memoize? Stable callbacks expected from consumers?] +- Lazy-loadable: [Yes / no] + +--- + +## Testing + +### Unit tests + +- [ ] Renders default state +- [ ] Renders all variants +- [ ] Fires events on interaction +- [ ] Respects disabled / loading state +- [ ] Forwards refs + +### Accessibility tests + +- [ ] Axe passes on default state +- [ ] Axe passes on each variant +- [ ] Keyboard navigation tested +- [ ] Screen reader pass (manual or automated) + +### Visual regression tests + +- [ ] Each variant snapshot +- [ ] Each state snapshot +- [ ] RTL snapshot +- [ ] Dark mode snapshot + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +- Design approved: [Name, date] +- Engineering approved: [Name, date] +- Accessibility reviewed: [Name, date] +- Ready for production: [Date] diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md b/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md new file mode 100644 index 0000000..ffa49be --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/SKILL.md @@ -0,0 +1,306 @@ +--- +name: funnel-flow-architecture +description: "Architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. Honest about silo-funnels (every tool standalone), kitchen-sink-funnels (every audience squeezed through one path), and matched-funnels (architecture matched to audience-and-stage) patterns. Triggers on funnel design, conversion architecture, marketing funnel, growth funnel, lifecycle architecture, nurture sequence design, multi-tool funnel orchestration. Also triggers when the team's growth tools are working individually but not together, when audience segments share one nurture path, or when a funnel is being architected from scratch." +category: growth-tooling +catalog_summary: "Architecting cross-tool conversion flows that match audience and stage. Distinguishes silo-funnels (every tool standalone) from kitchen-sink-funnels (every audience squeezed through one path) from matched-funnels (architecture matched to audience-and-stage)" +display_order: 6 +--- + +# Funnel Flow Architecture + +A senior growth practitioner's playbook for architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. The discipline of building a funnel architecture, not just collecting tools. + +Most growth programs accumulate tools without architecture. A chatbot, a calculator, a quiz, a lead magnet, a newsletter signup, a demo CTA. Each tool works individually; none of them work together. Visitors hit one tool, leave, and never enter the broader nurture sequence. The funnel is a collection of orphans. + +The growth programs that compound do something different. They architect the funnel deliberately. Different entry points lead to different nurture sequences. Different stages get different CTAs. Different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. + +This skill is the architecture skill that orchestrates the other 5 growth-tooling skills (lead-magnet-design, calculator-design, quiz-and-assessment-design, multi-step-form-design, chatbot-flow-design). Where those skills zoom into specific tool design, this skill zooms out to the cross-tool architecture that determines whether the tools compound. + +The voice is the senior growth practitioner who has watched funnels architecture compound and watched siloed funnel collections produce engagement metrics with no business impact. Practical, opinionated about the difference between collecting tools and architecting funnels, willing to call out when a team's growth program needs architecture rather than another tool. + +When to use this skill: architecting a funnel from scratch, auditing a growth program where tools work individually but conversion is flat, designing the cross-tool data flow that captures audience signal across touchpoints, or deciding which segments warrant which funnel paths. + +--- + +## What this skill covers + +This skill spans cross-tool funnel architecture. The growth-tooling distinctions: + +- `lead-magnet-design`, `calculator-design`, `quiz-and-assessment-design`, `multi-step-form-design`, `chatbot-flow-design` are tools that LIVE INSIDE the funnel architecture this skill designs. They zoom into specific tool design. +- `content-distribution` covers how content reaches audiences. This skill is what audiences DO once they reach content. +- `experiment-design` validates funnel changes. This skill designs the architecture; experiment-design tests it. +- `landing-page-copy` covers page-level copy. This skill is the cross-page architecture. +- `funnel-flow-architecture` (this skill) is audience-and-stage segmentation, entry-point architecture, tool-to-funnel mapping, nurture sequence architecture, cross-tool data flow. + +The audience: growth marketing leads, product marketing leads, marketing directors at SMB and mid-market companies, agencies running funnel architecture for clients, founders architecting growth programs from scratch. + +Out of scope: specific tool design (covered by the 5 sister growth-tooling skills); content distribution mechanics (covered by `content-distribution`); A/B testing methodology (covered by `experiment-design`); page-level copy (covered by `landing-page-copy`). + +--- + +## Silo-funnels vs kitchen-sink-funnels vs matched-funnels + +The keystone framing. + +Silo-funnels. Each tool (chatbot, calculator, lead magnet, quiz) lives independently. No coordinated flow; users hit one tool, leave, never enter the broader nurture sequence. Tools as orphans. Cost: each tool's investment does not compound; the audience that interacts with one tool is not connected to any next step; the team has tools but no architecture. + +Kitchen-sink-funnels. One funnel for everyone. Same nurture sequence regardless of audience or entry point. SMB and enterprise get the same emails. New visitors and bottom-of-funnel get the same CTAs. Conversion rates regress to mediocre on every segment. Cost: the funnel optimizes for the average; no segment is well-served; downstream conversion is uniformly low. + +Matched-funnels. Funnel architecture matches audience and stage. Different entry points lead to different nurture sequences; different stages get different CTAs; different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. Cost: the design effort upfront is significant; the maintenance is real; downstream conversion is meaningfully higher per segment. + +The litmus test. Pick a recent visitor to the site. Can the team explain which segment the visitor falls into, which entry point they used, which nurture sequence they are in, and what the next-step CTA they will see is? If yes, the funnel is matched. If the answer is "they got the same flow as everyone else," the funnel is kitchen-sink. If the answer is "they used the calculator but I do not know what comes next," the funnel is silo. + +--- + +## Audience and stage segmentation + +The foundation. + +The principle. Funnel architecture starts with audience and stage segmentation. Without segmentation, every visitor goes through the same path; the funnel cannot match. + +Audience dimensions. + +- Company size or buyer type. Solo, SMB, mid-market, enterprise. +- Industry or vertical. Healthcare, finance, retail, technology. +- Use case. What the audience is trying to accomplish. +- Role. Founder, PM, marketer, executive, IC. +- Source. Paid traffic, organic, referral, partner. + +Stage dimensions. + +- Awareness. Just discovered the brand or the topic. +- Consideration. Evaluating options actively. +- Decision. Choosing between specific options. +- Customer. Already a customer; ongoing relationship. + +The intersection. Audience x stage produces the matrix the funnel architecture serves. An enterprise PM in consideration is a different segment from an SMB founder in awareness; each warrants a different path. + +Segmentation discipline. Start with 3-5 audiences and 3 stages. 9-15 cells in the matrix. Some cells may share paths; some may have unique paths. The discipline is naming the segments deliberately rather than treating "everyone" as the audience. + +Detail in [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md). + +--- + +## Entry-point architecture + +How visitors land vs how they're routed. + +The principle. The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). + +Common entry points. + +- Paid landing page. Visitor arrives via ad; high intent; specific to the ad's promise. +- Organic content page. Visitor arrives via search or content discovery; awareness or research stage. +- Direct. Visitor arrives by typing URL or via bookmark; often returning. +- Referral. Visitor arrives via partner or word-of-mouth; warmer than paid. +- Social. Visitor arrives via social post; awareness or interest. +- Tool entry. Visitor arrives via a calculator, quiz, or chatbot directly. + +Entry-point routing. + +- Each entry point has expected segments and stages. +- The first action available at the entry point should match likely segment and stage. +- Different entry points may route to different downstream tools and sequences. + +Worked example. A visitor arriving via a paid ad about "B2B SaaS pricing" is likely in consideration stage looking for pricing information. The landing page should serve that need (clear pricing, comparison, calculator); the next-step offer should match consideration (demo, talk to sales). Same visitor arriving via an organic blog post about "B2B SaaS pricing strategy" is likely in awareness stage; the landing page should serve education (depth on pricing strategy); the next-step offer should match awareness (subscribe to content, get the framework). + +Detail in [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md). + +--- + +## Tool-to-funnel mapping + +Which tools serve which entry points. + +The principle. Each tool in the growth toolkit has a place in the funnel architecture. The tool serves specific segments at specific stages from specific entry points. + +Mapping examples. + +- Lead magnet. Often serves awareness-to-consideration transition. Captured email leads to nurture sequence. +- Calculator. Often serves consideration stage. The audience evaluating options uses the calculator to defend a specific decision. +- Quiz. Can serve any stage depending on design. Awareness quizzes for content marketing; consideration quizzes for product matching; decision quizzes for plan selection. +- Multi-step form. Often serves decision or qualification stage. The form captures qualified intent. +- Chatbot. Cross-cutting. Can serve any stage with intent recognition routing. + +The tool-segment fit. Tools should serve segments that match their value proposition. A calculator for solo founders may need different inputs and outputs than a calculator for enterprise buyers; the same calculator cannot serve both well. + +The portfolio approach. A team often has multiple tools serving different segments. The architecture maps each tool to its specific segments and stages. + +Detail in [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md). + +--- + +## Nurture sequence architecture + +Per-segment, per-stage. + +The principle. Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. + +Sequence variation by stage. + +- Awareness sequence. Educational; broad value; brand-building. Soft offers if any. +- Consideration sequence. Comparative; specific value; product-fit signals. Demo or trial CTAs. +- Decision sequence. Confidence-building; risk-reversal; urgency cues. Direct purchase or commitment CTAs. + +Sequence variation by audience. + +- Enterprise audiences get different content (white papers, case studies, ROI analysis) than SMB audiences (templates, quick wins, peer testimonials). +- Different roles get different framing (founder content emphasizes business outcomes; IC content emphasizes practitioner depth). +- Different industries get different examples and language. + +The kitchen-sink sequence failure. One sequence for everyone. Generic enough to send to all; specific enough for none. Conversion uniformly mediocre. + +The matched sequence win. Sequence specific to segment-and-stage. The audience perceives the brand as understanding their situation; conversion compounds. + +Detail in [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md). + +--- + +## Cross-tool data flow + +Capturing context from tool to tool. + +The principle. When the audience moves from one tool to another in the funnel, the audience signal travels with them. The chatbot conversation context informs the calculator's defaults; the calculator inputs inform the lead-magnet sequence; the quiz result informs the demo-request prefill. + +Cross-tool data flow patterns. + +- Identity threading. When the audience is identified at any point (logged in, opted in, identified by email), their identity carries forward across tools. +- Context capture. Inputs from one tool (calculator values, quiz results, form submissions) feed into the next interaction. +- Segment tagging. Each interaction tags the audience with segment information that informs future routing. +- Sequence-tool integration. Email sequences include links to specific tools matched to the audience's segment. + +The siloed-tool failure. Each tool captures its own data; nothing flows between them. The chatbot conversation is forgotten when the user opens the calculator; the calculator inputs are forgotten when the user opens the lead magnet. + +The integrated-funnel win. Data flows. The audience experiences continuity; the brand can match content and offers to the audience's specific journey. + +Detail in [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md). + +--- + +## Funnel measurement + +What to measure, what is noise. + +The principle. Funnel measurement should reveal architecture quality, not just tool quality. + +Architecture-level metrics. + +- Cross-tool conversion. What percentage of audience that hits tool A then engages with tool B? +- Sequence-to-tool conversion. What percentage of nurture sequence subscribers engage with downstream tools? +- Segment-level downstream conversion. Per-segment conversion to the program's main goal (trial, demo, purchase). +- Funnel-stage progression. What percentage of audience moves from awareness to consideration to decision over time? + +Tool-level metrics. + +- Conversion rate per tool (covered by each tool's skill). + +Architecture-level vs tool-level. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. Both matter; architecture is often the missing measurement. + +Detail in [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md). + +--- + +## Funnel iteration discipline + +When to redesign, when to refine. + +The principle. Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +Refine when: + +- Specific tools are underperforming relative to baseline. +- Specific segments have lower conversion than peer segments. +- Specific transitions in the funnel are producing drop-off. +- Sequence engagement is declining for specific cohorts. + +Redesign when: + +- Audience composition has fundamentally shifted. +- Product or service strategy has changed. +- Competitive landscape has shifted significantly. +- Multiple refine cycles have not produced expected results, suggesting architectural issues. + +Continuous-redesign trap. Teams that constantly redesign never benefit from architectural compounding. Each redesign resets the learning; nothing accumulates. + +Frozen-architecture trap. Teams that never iterate watch their architecture decay as audiences and markets evolve. + +The middle ground. Refine continuously; redesign infrequently and deliberately. + +Detail in [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md). + +--- + +## Architecture anti-patterns + +Patterns that look like funnel architecture but degrade conversion. + +The silo-funnels pattern. Tools as orphans; no architecture. + +The kitchen-sink-funnels pattern. One funnel for everyone. + +The over-segmented funnel. So many segments that maintenance is impossible; segments are not actually distinguishable. + +The unmaintained-funnel. Architecture designed once, never reviewed; decay accumulates. + +The tool-driven-architecture. Architecture organized around tools rather than around audience-and-stage; each tool gets its own funnel regardless of whether that serves the audience. + +The metric-blind-architecture. Architecture without measurement; cannot diagnose where it works and where it does not. + +The single-tool-funnel. Architecture that depends on one tool (just the calculator, just the chatbot); no resilience if that tool underperforms. + +The hand-off-broken-funnel. Tools work individually but the transitions between them break. + +Detail in [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md). + +--- + +## The framework: 12 considerations for funnel flow architecture + +When designing or auditing a funnel architecture, walk these 12 considerations. + +1. Matched-funnels, not silo or kitchen-sink. Architecture matches audience-and-stage; each tool is part of the architecture, not a standalone artifact. +2. Audience and stage segmentation defined. 3-5 audiences x 3 stages; the matrix the architecture serves. +3. Entry-point architecture mapped. Each entry point routed to expected segments and stages. +4. Tool-to-funnel mapping documented. Each tool serves specific segments at specific stages. +5. Nurture sequence architecture per segment. Sequences vary by audience and stage; not one sequence for everyone. +6. Cross-tool data flow integrated. Context travels across tools; the audience experiences continuity. +7. Architecture-level metrics tracked. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion. +8. Funnel iteration discipline. Refine continuously; redesign deliberately; avoid both extremes. +9. Tool portfolio balanced. Multiple tools serving different segments; not over-reliant on any single tool. +10. Audience-fit honest. The architecture serves the segments the brand can actually serve; out-of-fit audiences are filtered or routed elsewhere. +11. Maintenance ownership clear. Someone owns the architecture; quarterly review is calendared. +12. Expansion plan defined. When adding new tools, the architecture says where they fit; new tools earn their place rather than being added decoratively. + +The output of the framework is a funnel architecture that compounds over time, matches audience-and-stage segments, integrates tool data flows, and produces measurable downstream conversion. + +--- + +## Reference files + +- [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md) - The foundation. Audience dimensions, stage dimensions, the intersection matrix. +- [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md) - How visitors land vs how they're routed. Common entry points and their routing. +- [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md) - Which tools serve which entry points and segments. +- [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md) - Per-segment, per-stage sequence variation. The matched sequence win. +- [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md) - Identity threading, context capture, segment tagging, sequence-tool integration. +- [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md) - Architecture-level vs tool-level metrics. What to measure, what is noise. +- [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md) - When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. +- [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md) - The patterns that look like funnel architecture but degrade conversion. +- [`references/common-funnel-architecture-failures.md`](references/common-funnel-architecture-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: funnels are architecture, not collections + +The growth programs that compound are the ones that architect their funnels deliberately. Not collect tools. Not optimize one-tool-at-a-time. Architect. + +The architecture is the difference between tools that produce engagement and a funnel that produces business outcomes. The chatbot, the calculator, the quiz, the lead magnet, the multi-step form: each one is a tool. None of them are a funnel. The funnel is the architecture that makes them work together. + +That is the bar. Below the bar are silo-funnels (tools as orphans) and kitchen-sink-funnels (one path for everyone). Above the bar are matched-funnels where audience-and-stage segmentation drives entry-point routing, tool-to-funnel mapping, nurture sequence design, cross-tool data flow, and architecture-level measurement. + +## Closing: funnels earn investment when they compose + +Each tool in the growth toolkit costs investment to build and maintain. The investment compounds when the tools compose; the investment dilutes when the tools sit in silos. Architecture is the discipline of composition. + +The compounding mechanism. A visitor arrives. The architecture routes them based on entry point and observable signals. The first tool they encounter serves their segment-and-stage. The data they generate informs the next tool they encounter. The sequence they enter matches their context. Each interaction deepens the brand's understanding of the audience; each tool's contribution compounds with the others. + +When in doubt, ask: does each tool in the program serve a defined segment-and-stage, do the tools share data and context, can the team explain the architecture in one diagram, and does the team measure architecture-level outcomes (not just tool-level metrics)? If yes to all of those, the funnel is real architecture. If no to any, the gap is where the program's tools are failing to compose. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md new file mode 100644 index 0000000..6595f7a --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/architecture-anti-patterns.md @@ -0,0 +1,198 @@ +# Architecture anti-patterns + +The patterns that look like funnel architecture but degrade conversion. Anti-patterns are easy to ship; the cost shows up in downstream conversion, lead quality, and brand reputation over time. + +--- + +## The silo-funnels pattern + +The pattern. Tools as orphans. No coordinated flow. + +The signal. Each tool's metrics look fine individually; cross-tool metrics non-existent or near-zero. Downstream conversion does not match the sum of tool conversions. + +The cost. Each tool's investment does not compound. The audience that interacts with one tool is not connected to any next step. The team has tools but no architecture. + +The cure. Add cross-tool data flow and explicit funnel architecture. Detail in `references/cross-tool-data-flow-patterns.md` and the broader skill. + +--- + +## The kitchen-sink-funnels pattern + +The pattern. One funnel for everyone. Same nurture sequence regardless of audience or entry point. + +The signal. Conversion rates regress to mediocre on every segment. No segment is well-served. + +The cost. The funnel optimizes for the average; downstream conversion is uniformly low. + +The cure. Segment-and-stage architecture. Different paths for different cells in the matrix. Detail in `references/audience-and-stage-segmentation.md` and `references/nurture-sequence-architecture.md`. + +--- + +## The over-segmented funnel + +The pattern. So many segments that maintenance is impossible. 60 cells in the matrix; 60 distinct paths; nobody can keep up. + +The signal. Specific paths get little attention; maintenance backlog grows; specific cells are theoretical with no real visitors. + +The cost. The architecture exists on paper but not in execution. Tools and sequences for theoretical cells cost effort without producing value. + +The cure. Reduce to 9-15 cells. Start with the minimum viable matrix; expand only when data justifies. Detail in `references/audience-and-stage-segmentation.md`. + +--- + +## The unmaintained-funnel + +The pattern. Architecture designed once, never reviewed. Decay accumulates. + +The signal. Conversion declines slowly; tools age; sequences go stale; segments shift; the architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; the brand falls behind. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## The tool-driven-architecture + +The pattern. Architecture organized around tools rather than around audience-and-stage. Each tool gets its own funnel regardless of whether that serves the audience. + +The signal. The site has many tool-specific landing pages; users navigate to tools rather than tools serving users; the architecture is organized for the team, not the audience. + +The cost. Audiences cannot find what they need; tools cannibalize each other; the architecture cannot scale because each tool is its own funnel. + +The cure. Reorganize around audience-and-stage. The matrix drives the architecture; tools serve the matrix. + +--- + +## The metric-blind-architecture + +The pattern. Architecture without measurement. Cannot diagnose where it works and where it does not. + +The signal. Decisions made on intuition; no data to validate; iteration is guesswork. + +The cost. The architecture cannot improve through measurement; refinement is random; redesign happens reactively. + +The cure. Architecture-level metrics. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## The single-tool-funnel + +The pattern. Architecture that depends on one tool. Just the calculator. Just the chatbot. No resilience if that tool underperforms. + +The signal. The tool's quarterly performance dictates overall funnel performance. A bad month for the tool is a bad month for the funnel. + +The cost. The architecture is fragile. Tool failures cascade; redesigns of the central tool are high-risk. + +The cure. Portfolio approach. Multiple tools serving different segments. The architecture's resilience comes from diversification. + +--- + +## The hand-off-broken-funnel + +The pattern. Tools work individually but the transitions between them break. + +The signal. Each tool's metrics look fine; cross-tool conversion is low. The architecture's transitions are silently failing. + +The cost. The audience experiences the funnel as disconnected. Downstream conversion suffers because the bridges between tools are broken. + +The cure. Audit transitions. Cross-tool data flow. Sequence-tool integration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## The continuous-redesign funnel + +The pattern. Architecture redesigned every quarter. Each iteration starts over. + +The signal. Conversion does not improve over time. Each redesign resets the learning. Tools never reach maturity. + +The cost. Investment dilutes across redesigns. Compounding does not happen. + +The cure. Refine continuously; redesign infrequently and deliberately. Detail in `references/funnel-iteration-discipline.md` (continuous-redesign trap). + +--- + +## The frozen-architecture funnel + +The pattern. Architecture designed once; never iterated; treated as finished. + +The signal. Conversion declines slowly; tools and sequences feel dated; segments no longer match the audience. + +The cost. The architecture's value erodes; the brand becomes uncompetitive. + +The cure. Set refinement cadences. Quarterly audits. Detail in `references/funnel-iteration-discipline.md` (frozen-architecture trap). + +--- + +## The vanity-metric architecture + +The pattern. Architecture measured by surface metrics (tool engagement, total visitors, email signups) without measuring downstream outcomes. + +The signal. Metrics report looks healthy; business outcomes do not match. + +The cost. The team optimizes for the wrong metrics; the architecture appears successful while underperforming on what matters. + +The cure. Measure downstream conversion. Per-segment downstream conversion. Architecture-level metrics rather than tool-level activity. + +--- + +## The over-personalized funnel + +The pattern. Architecture designed for personalization the team cannot actually deliver. Many entry points; many sequences; many tools; team capacity exceeded. + +The signal. Personalization in design; generic in execution. Specific paths exist on paper; default to generic in practice. + +The cost. The team built complexity that does not get used. Maintenance burden without payoff. + +The cure. Match architecture complexity to team capacity. Start simple; add personalization where it produces meaningful lift; do not personalize for its own sake. + +--- + +## The under-personalized funnel + +The pattern. Architecture treats every visitor the same when meaningful personalization would lift conversion. + +The signal. Specific segments underperform; the audience's actual differences are not reflected in the funnel. + +The cost. Conversion stays at the average; no segment exceeds. + +The cure. Add personalization where data shows it would help. Start with segment-level differentiation; refine over time. + +--- + +## The orphan-tool architecture + +The pattern. Tools added to the funnel without explicit segment-and-stage assignment. Each new tool exists; no architecture says where it fits. + +The signal. The funnel's tool count grows; the architecture's clarity does not. + +The cost. Tools compete for the same audience; users see overlapping options; conversion fragments. + +The cure. Each tool earns its place. Architecture documents which segments and stages the tool serves. New tools are added with explicit mapping. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of the architecture, looking specifically for these anti-patterns. + +Audit questions. + +- Do the tools work together (anti-pattern check: silo, hand-off-broken)? +- Is there segment-and-stage architecture (anti-pattern check: kitchen-sink, tool-driven)? +- Is the matrix maintainable (anti-pattern check: over-segmented, over-personalized)? +- Are tools mapped to specific segments (anti-pattern check: orphan-tool, single-tool, under-personalized)? +- Are architecture-level metrics tracked (anti-pattern check: metric-blind, vanity-metric)? +- Is there iteration discipline (anti-pattern check: continuous-redesign, frozen-architecture, unmaintained)? + +The retire decision. Anti-pattern architectures often warrant redesign. Patching anti-patterns rarely produces a good architecture. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md new file mode 100644 index 0000000..f2ce571 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md @@ -0,0 +1,200 @@ +# Audience and stage segmentation + +The foundation. Audience dimensions, stage dimensions, the intersection matrix. + +Funnel architecture starts with audience and stage segmentation. Without it, every visitor goes through the same path; the funnel cannot match. With it, the architecture has a definable map of who the audience is and where they are in their journey. + +--- + +## The segmentation principle + +The funnel cannot be tailored without segments. Segments are the architecture's unit of design. + +The discipline. Define 3-5 audience segments and 3 stages. The intersection produces 9-15 cells; each cell is a potential funnel path. + +The trap. Over-segmenting. Defining 12 audiences x 5 stages produces 60 cells; the team cannot maintain that many distinct paths. Most cells end up sharing paths or being indistinguishable. + +The discipline boundary. Start with the minimum viable segmentation. 3-5 audiences and 3 stages is enough to start. Expand only if the data shows meaningful differentiation that justifies more cells. + +--- + +## Audience dimensions + +The dimensions that distinguish meaningful audience segments. + +Company size or buyer type. Solo founders, SMB (10-50), mid-market (50-500), enterprise (500+). Different sizes have different buying processes, different budgets, different needs. + +Industry or vertical. Healthcare, finance, retail, technology, education. Different industries have different language, regulations, examples, competitors. + +Use case. What the audience is trying to accomplish. "Customer support automation," "sales pipeline management," "content production at scale." + +Role. Founder, PM, marketer, sales lead, executive, IC. Different roles have different perspectives and different content preferences. + +Source or channel. Paid traffic, organic search, content referral, partner referral, direct. Different sources signal different intent and stage. + +Geography or language. Domestic vs international; English-first vs other-language audiences. May warrant different funnels for compliance, currency, or cultural reasons. + +The audience dimensions to use depend on the brand's strategy. Most B2B brands segment primarily by company size and use case; most consumer brands segment by demographic and behavioral attributes. + +--- + +## Stage dimensions + +The dimensions that distinguish where the audience is in their journey. + +Awareness. Just discovered the brand or the topic. Has not yet committed to research or evaluation. The audience is open but uncommitted. + +Content fit: educational, broad value, brand-building. +CTAs that fit: subscribe to content, get a framework, follow. +CTAs that do not fit: book a demo, start a trial, buy now. + +Consideration. Evaluating options actively. Has identified a need; comparing solutions. The audience is engaged but not yet decided. + +Content fit: comparative, specific value, product-fit signals. +CTAs that fit: see a calculator, take a quiz, download a comparison, book a demo. +CTAs that do not fit: just-published-content awareness asks; or hard sell. + +Decision. Choosing between specific options. The audience has narrowed the field; selecting is imminent. + +Content fit: confidence-building, risk-reversal, urgency cues. +CTAs that fit: start a trial, talk to sales, sign up. +CTAs that do not fit: top-of-funnel awareness; long-form education. + +Customer. Already a customer; ongoing relationship. Often left out of growth-funnel architecture even though it matters for retention and expansion. + +Content fit: success-deepening, capability-expanding, community. +CTAs that fit: upgrade, refer, join community, attend event. + +The four stages cover most audiences. Some programs combine awareness-and-consideration or consideration-and-decision into 2-stage models; the principle is the same. + +--- + +## The intersection matrix + +Audience x stage produces the matrix the funnel architecture serves. + +Example matrix for a B2B SaaS company. + +\| Audience \| Awareness \| Consideration \| Decision \| +\|----------\|-----------\|---------------\|----------\| +\| Solo founder \| Path A \| Path B \| Path C \| +\| SMB team \| Path D \| Path E \| Path F \| +\| Mid-market \| Path G \| Path H \| Path I \| +\| Enterprise \| Path J \| Path K \| Path L \| + +12 cells. Some may share paths (Path A and Path D might be similar awareness content for solo and SMB). The matrix is the architecture's map. + +Cell-sharing patterns. + +- Awareness paths often share more than decision paths (broad content can serve multiple audience segments). +- Consideration paths often diverge by audience (the comparison content for enterprise differs significantly from SMB). +- Decision paths almost always diverge (the offer for enterprise is different from SMB). + +The matrix shows where the funnel architecture invests in unique paths and where it shares. + +--- + +## Segmentation discipline + +The discipline boundaries. + +Discipline 1: Define segments before designing paths. Without segments, paths are arbitrary. Always start with the matrix. + +Discipline 2: Name segments specifically. "Solo founder pre-launch" beats "small business." Specific names reflect specific audiences. + +Discipline 3: Validate segments with data. A segment that does not appear in actual audience data is theoretical. Validate against site analytics, sales data, or audience research. + +Discipline 4: Maintain the matrix. Audiences shift; the matrix should be reviewed quarterly. Segments may merge or split over time. + +Discipline 5: Avoid over-segmentation. 60-cell matrices are not maintainable. Start with 9-15 cells; expand only with justification. + +--- + +## Segmentation worked example + +A B2B SaaS analytics platform. + +Audiences (4). + +- Data analysts at SMB companies (50-200 employees). +- Data leaders at mid-market companies (200-1000 employees). +- Engineering leaders at enterprise companies (1000+ employees). +- Solo data practitioners and consultants. + +Stages (3). + +- Awareness (researching the analytics topic). +- Consideration (evaluating analytics platforms). +- Decision (selecting and signing up). + +Matrix (12 cells). + +\| Audience \| Awareness \| Consideration \| Decision \| +\|----------\|-----------\|---------------\|----------\| +\| Data analyst SMB \| Educational content \| Calculator, quiz \| Trial, demo \| +\| Data leader mid-market \| Strategic content \| Comparison, ROI calc \| Demo, custom quote \| +\| Engineering enterprise \| Technical depth \| Technical demo, security \| Custom evaluation \| +\| Solo practitioner \| Practical content \| Self-serve resources \| Free tier signup \| + +Each cell has a defined path. The architecture invests where the cells need unique treatment; shares where the cells can use the same path. + +--- + +## Segmentation maintenance + +Segments decay. + +What decays. + +- Audience definitions that no longer match actual visitors. +- Stage definitions that have shifted as buying processes evolved. +- Cells that have become empty (no visitors fit the segment). +- Cells that have become bloated (too many visitors fit one segment; needs sub-segmentation). + +Maintenance cadence. Quarterly review of the matrix against actual audience data. + +The drift indicator. Sales reports that the funnel-sourced leads do not match expected segments; analytics show segments combining or splitting unexpectedly. + +--- + +## Segmentation and the rest of the architecture + +How segmentation drives the rest of the architecture. + +Entry-point architecture. Each entry point routes to expected segments. The matrix tells the architecture where each entry point's traffic likely lands. + +Tool-to-funnel mapping. Each tool serves specific cells in the matrix. The matrix tells the architecture which tools belong where. + +Nurture sequence architecture. Each cell may have its own sequence (or sequences may be shared across similar cells). The matrix is the sequence design map. + +Cross-tool data flow. As the audience moves through the matrix (awareness to consideration to decision), data flows with them. The matrix tracks the journey. + +Funnel measurement. Per-cell conversion is the architecture-level metric. The matrix is the measurement framework. + +--- + +## Common segmentation failures + +No segmentation. "Everyone" treated as the audience. Funnel cannot match. + +Theoretical segments. Segments defined that do not exist in actual audience data. + +Over-segmentation. 60-cell matrix that the team cannot maintain. + +Under-segmentation. 4-cell matrix when the audience genuinely splits into more meaningful segments. + +Stale segmentation. Matrix designed once; audience shifted; matrix not updated. + +Segments without paths. Matrix defined but no funnel paths designed for the cells; segmentation is decorative. + +Paths without segments. Funnel paths designed without clear segment mapping; treatments are arbitrary. + +--- + +## Methodology-level choices that stay in the public skill + +The segmentation principle and discipline boundaries. Audience dimensions. Stage dimensions. The intersection matrix. Segmentation discipline (5 disciplines). Worked example. Segmentation maintenance. Segmentation and the rest of the architecture. Common failures. + +## Implementation choices that stay internal + +Specific segments for the team's audience. Specific tooling for segment tagging and analysis. The team's matrix maintenance calendar. Specific path designs per cell. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md new file mode 100644 index 0000000..8f45320 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md @@ -0,0 +1,179 @@ +# Common funnel architecture failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the funnel is not converting" or "tools work individually but conversion is flat" or "we cannot tell where the funnel is broken." + +--- + +## "Tools work individually; conversion is flat." + +The diagnosis. Silo-funnels pattern. Tools as orphans; no architecture connects them. + +The cure. Add cross-tool data flow; map tools to specific segments; design transitions between tools. Detail in `references/cross-tool-data-flow-patterns.md` and `references/tool-to-funnel-mapping.md`. + +--- + +## "Every audience gets the same nurture sequence." + +The diagnosis. Kitchen-sink-funnels pattern. One sequence for everyone. + +The cure. Segment-and-stage sequences. Different cells in the matrix get different sequences. Detail in `references/nurture-sequence-architecture.md`. + +--- + +## "We have 12 tools and no clear architecture." + +The diagnosis. Tool-driven architecture. Tools accumulated without explicit segment mapping. + +The cure. Build the matrix; map each tool to specific cells; retire tools that do not have a mapping or that compete with better-mapped alternatives. + +--- + +## "Specific segments convert at half the rate of others." + +The diagnosis. Architecture for those segments may be broken. Or the segments may not be served by the current tools and sequences. + +The cure. Audit those segments' funnel paths. Are tools mapped to them? Are sequences designed for them? If not, build for those segments. If yes, refine the existing path. + +--- + +## "We cannot tell which tools or sequences are driving conversion." + +The diagnosis. Architecture-level metrics not tracked. Cannot attribute outcomes to architecture choices. + +The cure. Instrument cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## "We redesign every quarter; nothing improves." + +The diagnosis. Continuous-redesign trap. Each redesign resets learning; nothing compounds. + +The cure. Establish "no major redesign for X months" discipline. Refine continuously; redesign deliberately and rarely. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "The funnel was great at launch; now conversion has dropped 40 percent." + +The diagnosis. Frozen-architecture trap. Designed once; never iterated; decay accumulated. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "Specific transitions in the funnel have high drop-off." + +The diagnosis. Hand-off-broken pattern. Tools work but the bridges between them break. + +The cure. Audit transitions. Add cross-tool data flow so context travels. Promote downstream tools at upstream tools' exits. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Our chatbot, calculator, and quiz all serve consideration-stage audiences." + +The diagnosis. Tool overlap without differentiation. Three tools competing for the same audience. + +The cure. Differentiate the tools' purposes. Calculator for ROI questions; quiz for product matching; chatbot for FAQ. Or consolidate to fewer tools with clearer roles. + +--- + +## "Sales says quiz-sourced leads, calculator-sourced leads, and lead-magnet-sourced leads are different qualities." + +The diagnosis. Tools may be attracting different segments; the architecture's segmentation is working but the tools are not all matched to high-quality segments. + +The cure. Investigate which tools attract which segments. Optimize tool placement and design for the segments the brand serves best; deprioritize tools that attract low-quality segments. + +--- + +## "We added a new tool last quarter; it does not seem to help conversion." + +The diagnosis. Orphan-tool pattern. Tool added without architecture mapping. + +The cure. Map the new tool to specific segments. Decide where it fits in the matrix. Promote it where it fits; remove it from places it does not. + +--- + +## "Our funnel has 8 stages; visitors only complete 2." + +The diagnosis. Funnel may be over-architected. Too many steps; audience cannot or will not progress through them all. + +The cure. Simplify the funnel. Combine stages; remove unnecessary tools; align the funnel length to the audience's likely journey. + +--- + +## "Cross-tool tracking is broken; we cannot tell who used what." + +The diagnosis. Identity threading or event tracking issue. Architecture's measurement infrastructure is broken. + +The cure. Audit identity threading. Verify event tracking. Fix the infrastructure before further iteration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Audiences arriving from paid traffic and organic traffic perform completely differently." + +The diagnosis. Either entry-point routing is not differentiating, or the funnel paths are not serving paid and organic audiences differently. + +The cure. Different routing for different entry points. Specific landing pages and sequences for paid vs organic. Detail in `references/entry-point-architecture-patterns.md`. + +--- + +## "The team built personas; the funnel does not reflect them." + +The diagnosis. Segments defined but not implemented in the funnel architecture. Decorative segmentation. + +The cure. Map personas to funnel cells. Build paths for the cells. The personas should drive the architecture, not sit in a deck. + +--- + +## "Our sequence-to-trial conversion is high; trial-to-paid is low." + +The diagnosis. Architecture handles funnel up to trial well; the trial-to-paid stage may need its own architecture (or may be a product issue rather than funnel issue). + +The cure. Treat trial-to-paid as its own funnel-stage progression. Build paths for trial users; nurture toward paid conversion. + +--- + +## "We have 15 lead magnets; 3 produce most of the leads." + +The diagnosis. Magnet portfolio not maintained. Most magnets are dead but still on the site. + +The cure. Audit and retire dead magnets. Free capacity for the strong ones. Detail in `lead-magnet-design`. + +--- + +## "We built a fancy architecture; the team cannot maintain it." + +The diagnosis. Over-architecture. Architecture exceeds team capacity. + +The cure. Simplify. Match architecture complexity to team capacity. Expand only when capacity grows. + +--- + +## "Funnel-sourced leads are different from sales-sourced leads." + +The diagnosis. Likely fine. Funnel and direct sales serve different segments and stages. Both can be valuable. + +The action. Track them separately. Optimize each for its specific path. + +--- + +## The pattern across failures + +Most funnel architecture failures fall into one of three patterns. + +Pattern 1: Tools without architecture. Silo, kitchen-sink, tool-driven, orphan-tool. The fix is to add explicit architecture (matrix, mapping, data flow). + +Pattern 2: Architecture without measurement. Metric-blind, vanity-metric, broken tracking. The fix is to instrument architecture-level metrics. + +Pattern 3: Architecture without maintenance. Frozen, decayed, unmaintained. The fix is iteration discipline (refine continuously, redesign rarely). + +The metric pattern: funnel architecture failures often look fine on tool-level metrics. The signal is in cross-tool conversion, segment-level outcomes, and funnel-stage progression. Programs that track only tool metrics keep shipping the same architectural patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (tools-without-architecture, architecture-without-measurement, architecture-without-maintenance). The principle that tool-level metrics alone are insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific architecture-level dashboards. Specific cures the team applies. The team's audit and redesign processes. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md new file mode 100644 index 0000000..a74f62a --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md @@ -0,0 +1,252 @@ +# Cross-tool data flow patterns + +Identity threading, context capture, segment tagging, sequence-tool integration. + +When the audience moves from one tool to another in the funnel, the audience signal travels with them. Done well, cross-tool data flow makes the audience experience continuous and lets the brand match content to the audience's specific journey. Done poorly, every tool starts from scratch and the audience signal is lost. + +--- + +## The continuity principle + +The audience experience should feel continuous across tools. Their interactions in one tool inform their experience in the next. + +The win. A visitor takes a quiz; the quiz tags them as "mid-market mid-funnel." When they later open the calculator, the defaults reflect mid-market context. When they download a lead magnet, the sequence delivered matches the segment. The visitor experiences a coordinated brand journey. + +The fail. The same visitor takes the quiz; the calculator does not know they took it; the lead magnet sequence is generic. Each tool is an island. The audience signal captured in one tool is wasted in the next. + +The discipline. Data flows. Each tool's interactions inform subsequent interactions. + +--- + +## Pattern A: Identity threading + +When the audience is identified, their identity carries forward across tools. + +How it works. + +- The audience opts in (email submission, account creation, login). +- Subsequent interactions are associated with that identity. +- Tools across the funnel access the identity record to personalize. + +Strengths. + +- Most powerful continuity mechanism. +- Lets all tools share context for the same person. + +Weaknesses. + +- Requires identity infrastructure (CRM, data warehouse, customer data platform). +- Privacy considerations (handling identity data carefully). + +When to use. When the program has identity infrastructure and the audience is willing to be identified (typically post lead-magnet download or account creation). + +--- + +## Pattern B: Context capture + +Inputs from one tool feed into the next interaction. + +How it works. + +- Tool A captures specific inputs (calculator values, quiz answers, form responses). +- Those inputs are stored with the identity (or with an anonymous session token). +- Tool B reads the inputs; uses them as defaults or context. + +Example. + +- Quiz captures "team size: 75." +- Calculator's defaults reflect team size 75. +- Lead magnet's recommended resource matches team size 75. + +Strengths. + +- Concrete continuity; the audience sees their inputs reflected. +- Reduces re-entry friction. + +Weaknesses. + +- Requires structured data capture (not just behavioral signals). +- Inputs from different tools must align (no conflict if quiz and calculator both capture team size). + +When to use. When tools capture overlapping or related context that benefits from shared use. + +--- + +## Pattern C: Segment tagging + +Each interaction tags the audience with segment information that informs future routing. + +How it works. + +- Tool A determines the audience's segment based on inputs (the quiz result; the calculator's input pattern). +- The segment tag attaches to the audience record. +- Subsequent tools and sequences route based on the tag. + +Example. + +- Quiz result: "Mid-market operator." +- Tag: segment = mid-market. +- Subsequent: lead magnet sequence is the mid-market sequence; calculator defaults are mid-market; chatbot routing is mid-market-aware. + +Strengths. + +- Lightweight. The tag is small; the routing logic uses it. +- Compatible with most marketing automation. + +Weaknesses. + +- Tag accuracy depends on the source tool's accuracy. +- Tags can conflict (different tools assign different segments). +- Tag staleness (the audience's segment may change over time). + +When to use. Default pattern for cross-tool routing. + +--- + +## Pattern D: Sequence-tool integration + +Email sequences include links to specific tools matched to the audience's segment. + +How it works. + +- Sequence email includes a CTA: "based on your situation, this calculator can help you compare." +- The CTA link includes parameters that pre-fill the calculator with the audience's known context. +- Audience clicks; calculator opens with their context already populated. + +Strengths. + +- Explicit cross-tool connection; the audience sees the journey. +- Reduces friction at the calculator (audience does not re-enter known information). + +Weaknesses. + +- Requires tooling for parameterized links and pre-fill. +- The pre-fill must respect what the audience consented to share. + +When to use. When the sequence is steering the audience toward specific tools and pre-fill would meaningfully reduce friction. + +--- + +## Conflict and source-of-truth + +When different tools capture different values for the same attribute. + +The pattern. The quiz says team size 75; the multi-step form says team size 60. Which is correct? + +Approaches. + +- Latest wins. The most recent capture overrides earlier captures. +- Source authority. Specific tools are designated as authoritative for specific attributes (form > quiz for verified data). +- User confirmation. Conflict surfaces a confirmation prompt: "We have you down as 75; is that still correct?" + +The discipline. Define source-of-truth for important attributes. Latest-wins is simple but can lose data; source authority is more disciplined but requires explicit definition. + +--- + +## Privacy and consent + +Cross-tool data flow involves handling user data. Consent matters. + +The principle. The audience should know what data flows where. Pre-filling a calculator with previously captured information is fine if the audience expects it; surprising them with knowledge they did not consent to share breaks trust. + +Consent patterns. + +- Explicit opt-in to identity tracking ("save my progress"). +- Disclosure of data flow ("we use your quiz answers to personalize subsequent recommendations"). +- Easy data deletion or account closure. + +Privacy regulations. GDPR, CCPA, and other regulations affect what data can flow and how. Compliance is essential; the architecture must respect the regulations applicable to the audience. + +--- + +## Anonymous-session continuity + +When the audience is not yet identified. + +The pattern. Browser-based continuity (cookies, local storage) lets tools share context within the same session even before identity capture. + +Strengths. + +- Continuity without requiring early opt-in. +- Smooth experience across same-session tool interactions. + +Weaknesses. + +- Lost when the audience switches devices or clears cookies. +- Limited persistence (typically days, not weeks). +- Privacy considerations (cookies-based tracking has its own complications). + +When to use. As a supplement to identity-based continuity; for early-funnel interactions before opt-in. + +--- + +## Cross-tool data flow architecture + +How to design the data flow at the architecture level. + +The data layer. A single data layer (CRM, customer data platform, data warehouse) holds the audience records. All tools read from and write to this layer. + +The integration layer. Tools integrate with the data layer either directly (API) or through a middleware (Zapier, Segment). + +The privacy layer. Consent and data-control mechanics live across the architecture; the data layer respects them. + +Architecture-level discipline. Cross-tool data flow is infrastructure work, not just tool work. Building the infrastructure is part of the funnel architecture investment. + +--- + +## Cross-tool measurement + +Track how data flows across tools. + +Metrics. + +- Cross-tool engagement. What percentage of subscribers who engaged with tool A also engaged with tool B? +- Identity capture rate. What percentage of visitors who interact with tools become identified? +- Pre-fill usage. When pre-fill is offered, what percentage of users engage with the pre-filled tool? +- Segment tag accuracy. Sample-based audit of whether segment tags match actual audience profiles. + +Diagnostic uses. Low cross-tool engagement signals tools are not connecting in the audience's journey; low pre-fill usage signals the pre-fill is not visible or not valued. + +--- + +## Cross-tool data flow audit + +Periodically audit the data flow. + +The audit. + +- Walk through critical journeys end-to-end. Does data actually flow? +- Verify identity threading works (logged-in user is recognized across tools). +- Verify context capture works (inputs in tool A appear in tool B as expected). +- Verify segment tagging works (quiz result tag triggers correct downstream sequences). +- Verify sequence-tool integration works (sequence links pre-fill correctly). + +The drift. Integrations break silently. Tool updates change data formats. Audit catches the drift. + +--- + +## Common data flow failures + +No data flow. Each tool isolated; identity and context lost between tools. + +Identity threading broken. Logged-in user not recognized across tools; same person treated as new visitor multiple times. + +Context capture incomplete. Tool A captures inputs but tool B does not access them. + +Segment tag conflicts. Different tools tag the same person differently; downstream routing inconsistent. + +Pre-fill broken. Sequence link includes parameters but the tool does not honor them; audience re-enters known information. + +Privacy violations. Cross-tool data flow happens without consent; audience surprised; trust damaged. + +Stale data. Audience's situation has changed but tools still use old captured data. + +--- + +## Methodology-level choices that stay in the public skill + +The continuity principle. Patterns A through D (identity, context, segment, sequence-tool integration). Conflict and source-of-truth. Privacy and consent. Anonymous-session continuity. Cross-tool data flow architecture. Cross-tool measurement. Audit cadence. Common failures. + +## Implementation choices that stay internal + +Specific data layer choices for the team's stack. Specific integration tooling. Specific consent flows and privacy disclosures. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md new file mode 100644 index 0000000..d3cb1a1 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md @@ -0,0 +1,190 @@ +# Entry-point architecture patterns + +How visitors land vs how they're routed. Common entry points and their routing. + +The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). Without entry-point architecture, every visitor goes through the same first experience regardless of where they came from. + +--- + +## The entry-routing principle + +Each entry point has expected segments and stages. The first action available at the entry point should match those expectations. + +The win. A visitor arrives via an ad about "B2B SaaS pricing." The landing page serves consideration-stage pricing content. The first available action is a pricing calculator and a demo CTA. The entry point's routing matches the visitor's likely intent. + +The fail. Same visitor arrives via the same ad. The landing page is the homepage. The visitor lands in awareness-stage content with no clear next step. The mismatch costs the conversion. + +The discipline. Each entry point's first experience matches the visitor's likely segment and stage. + +--- + +## Common entry points + +The entry points most growth programs work with. + +Paid landing page. Visitor arrives via paid ad (search, social, display). High intent; specific to the ad's promise. + +Expected segment: usually narrow (the ad targeted specific audience). +Expected stage: usually consideration or decision (paid traffic is rarely awareness-stage). +Routing: landing page should serve the ad's specific promise; next-step action should match consideration or decision stage. + +Organic content page. Visitor arrives via search or content discovery; awareness or research stage. + +Expected segment: variable (organic search may surface multiple audience types). +Expected stage: usually awareness or early consideration (research-driven). +Routing: content should serve the search intent; secondary CTAs offer movement toward consideration. + +Direct or returning visitor. Visitor arrives by typing URL or via bookmark; often returning. + +Expected segment: variable (depends on prior interactions). +Expected stage: variable (could be any stage). +Routing: homepage should provide multiple entry paths to different segments and stages; navigation matters more than single CTA. + +Referral. Visitor arrives via partner or word-of-mouth; warmer than paid. + +Expected segment: variable (depends on referral source). +Expected stage: usually consideration or decision (referrals indicate active interest). +Routing: page should match the referral context; next-step action should reflect the warmth (free trial, demo, talk to sales often work). + +Social. Visitor arrives via social post; awareness or interest. + +Expected segment: variable (depends on social audience). +Expected stage: usually awareness (social discovery is rarely buying intent). +Routing: page should serve the social post's promise; soft CTAs (follow, subscribe, learn more) often work better than hard sells. + +Tool entry. Visitor arrives via a calculator, quiz, or chatbot directly (often via shared link or specific tool URL). + +Expected segment: matches the tool's audience. +Expected stage: usually consideration (the tool is a consideration-stage artifact). +Routing: tool should serve its specific value; next-step actions should connect tool output to broader funnel. + +--- + +## Entry-point routing patterns + +How to route each entry point. + +Pattern A: Direct match. Entry point routes directly to a specific landing page and CTA. Simple; works when the entry point's segment and stage are well-defined. + +Pattern B: Routing layer. Entry point routes to a routing page that asks 1-2 questions and then sends to the matched destination. Useful when the entry point's segment is variable. + +Pattern C: Personalized landing. Entry point routes to a landing page that adapts based on visitor attributes (source, behavior, profile). Sophisticated; requires personalization infrastructure. + +Pattern D: Quiz-as-router. Entry point routes to a quiz that segments and recommends. Detail in `quiz-and-assessment-design`. + +The choice depends on entry-point variability and infrastructure. Most programs start with Pattern A and add complexity as data shows the need. + +--- + +## Entry-point and segment matching + +Each entry point likely surfaces specific segments. + +The discipline. For each entry point, document the expected segments. The first experience should serve those segments. + +Worked example. + +- Entry point: paid ad targeting "data analytics for SaaS." +- Expected segments: data analysts and data leaders at SaaS companies. +- Expected stage: consideration. +- Routing: landing page on data analytics for SaaS; calculator showing ROI; CTA to demo. + +The match is deliberate. Visitors arriving via this entry point get a first experience that fits their segment and stage. + +--- + +## Entry-point and stage matching + +The first experience should match the visitor's likely stage. + +Common mismatches. + +- Awareness-stage visitor lands on a hard-sell decision-stage page; bounces because not ready. +- Decision-stage visitor lands on awareness-stage content; bounces because oversold on what they already know. +- Consideration-stage visitor lands on either; serves the wrong intent. + +The cure. Match the entry point's expected stage to the page's stage. Awareness pages serve awareness traffic; decision pages serve decision traffic. + +--- + +## Multi-entry funnels + +When the same visitor arrives via different entry points across visits. + +The pattern. A visitor sees an ad on Tuesday (paid entry); reads a blog post on Wednesday (organic entry); types the URL on Thursday (direct entry). Each entry point may surface a different first experience. + +Architecture implications. + +- Personalization across visits requires identity threading. +- Nurture sequences may need to acknowledge prior visits. +- Cross-channel attribution becomes important. + +The discipline. Architecture should accommodate multi-entry without confusion. The visitor's progression through the funnel respects their cumulative interactions, not just the latest entry. + +--- + +## Entry-point measurement + +Track per-entry-point performance. + +The metric. Per entry point: visitors, segment composition, stage composition, conversion to next action. + +Diagnostic uses. + +- Entry points with low conversion: routing may be mismatched. +- Entry points with high conversion: investigate what is working; replicate to other entries. +- Entry points whose segment composition does not match expectations: the source may have shifted; review. + +--- + +## Entry-point and audience-segment audit + +Periodically audit entry-point routing. + +The audit. + +- For each entry point: what segments and stages are arriving? +- Does the first experience match those segments and stages? +- Is conversion at this entry point above or below baseline? + +The drift. Entry points decay as ad targeting shifts, content rankings change, partners evolve. Quarterly audit catches the drift. + +--- + +## Entry-point anti-patterns + +The single-funnel-for-every-entry. All visitors go through the same first experience regardless of entry. Routing not matching segments or stages. + +The over-personalized-entry. Entry routing so specific that maintenance is impossible; many entries route to landing pages that exist only for one entry source. + +The mismatched-entry. Entry expects one segment; landing page serves a different one. Conversion suffers. + +The unmeasured-entry. Per-entry data not tracked; routing decisions are guesswork. + +The orphan-entry. Entry point exists; no landing page or routing defined; visitors land somewhere generic. + +--- + +## Common entry-point failures + +One landing page for everyone. Different entry points get the same first experience; routing not matching variability. + +Wrong stage routing. Awareness traffic gets decision-stage CTAs; decision traffic gets awareness content. + +Personalization without infrastructure. Architecture designed for personalization that the team cannot actually implement. + +Entry-point drift. Entry sources shifted; routing not updated. + +Single-tool entry. Only one tool serves an entry point; if the tool fails, the entry has no recovery. + +Entry-conversion attribution missing. Cannot tell which entry points produce which downstream conversion. + +--- + +## Methodology-level choices that stay in the public skill + +The entry-routing principle. Common entry points (6 patterns). Entry-point routing patterns (4 patterns). Entry-point and segment matching. Entry-point and stage matching. Multi-entry funnels. Entry-point measurement. Audit cadence. Anti-patterns. Common failures. + +## Implementation choices that stay internal + +Specific entry points for specific programs. Specific routing logic per entry. Specific landing pages per entry. The team's audit calendars. These vary by team and program. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md new file mode 100644 index 0000000..22a62e8 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md @@ -0,0 +1,189 @@ +# Funnel iteration discipline + +When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. + +Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +--- + +## The compound-vs-reset distinction + +Refinement compounds. Redesign resets. + +Refinement. Targeted changes to specific tools, sequences, or transitions within the existing architecture. The architecture's bones stay; the muscles get stronger. + +Redesign. Overhaul of the architecture. Segments redefined; tool-to-funnel mapping changed; sequences rebuilt. The architecture restarts. + +The discipline. Refine continuously; redesign deliberately and rarely. Constant redesign prevents compounding; never iterating allows decay. + +--- + +## When to refine + +Five conditions that signal refinement is appropriate. + +Specific tools are underperforming relative to baseline. A calculator with declining conversion benefits from input adjustment, default updates, or methodology refinement. The architecture is fine; the tool needs attention. + +Specific segments have lower conversion than peer segments. A segment that converts at 4 percent while peer segments convert at 10 percent has a fixable architecture issue. Refine the segment's path. + +Specific transitions in the funnel are producing drop-off. The transition from quiz to recommended product page has high drop-off. Audit the transition; fix. + +Sequence engagement is declining for specific cohorts. Newer subscribers to a sequence engage less than older subscribers. The sequence may have decayed; refresh content. + +Specific entry points are routing wrong segments. A paid ad source has shifted; visitors arriving from it no longer match the segment the landing page serves. Adjust the routing. + +These are refinements. The architecture is sound; specific elements need attention. + +--- + +## When to redesign + +Four conditions that signal redesign is appropriate. + +Audience composition has fundamentally shifted. The brand pivots; the target audience changes; the segments are no longer accurate. The matrix needs redesign. + +Product or service strategy has changed. The brand offers a fundamentally different product line; the funnel that served the old products no longer fits. Redesign. + +Competitive landscape has shifted significantly. A new competitor reshapes the buying process; the funnel needs to respond. Redesign may follow. + +Multiple refine cycles have not produced expected results. The team has refined repeatedly; conversion has not moved. The issue may be architectural rather than tactical. Redesign worth considering. + +These are redesigns. The architecture's fundamentals need to change. + +--- + +## The continuous-redesign trap + +Teams that constantly redesign never benefit from architectural compounding. + +The pattern. Every quarter, the team rethinks the funnel. New segments; new tools; new sequences. Each redesign is partially built before the next redesign starts. + +The signal. Conversion does not improve over time. Each iteration starts over. Learning does not accumulate because the structure keeps changing. + +The cost. The team's investment dilutes across redesigns. Tools never reach maturity. Sequences never stabilize. + +The cure. Redesign infrequently. Refine continuously between redesigns. Set a "no major redesign for X months" discipline if needed. + +--- + +## The frozen-architecture trap + +Teams that never iterate watch their architecture decay. + +The pattern. The funnel was designed once; the team treats it as finished. No refinement; no redesign; no audit. + +The signal. Conversion declines slowly over months and years. Tools age; sequences go stale; segments shift. The architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; competitors improve; the brand falls behind. + +The cure. Set refinement cadences. Quarterly audit; targeted refinements based on data. Acknowledge that no architecture stays optimal forever. + +--- + +## The middle ground + +Refine continuously; redesign infrequently and deliberately. + +Refinement cadence. Monthly or quarterly. Targeted; data-driven; small enough to test in isolation. + +Redesign cadence. Annually at most. Often longer. Major triggers (audience pivot, product change, competitive shift) drive redesign rather than calendar. + +The discipline. Both rhythms running in parallel. Refinement maintains; redesign responds to fundamental change. + +--- + +## Refinement workflow + +How to iterate productively. + +Step 1: Identify the gap. Data-driven; specific to a tool, segment, transition, or sequence. + +Step 2: Hypothesize the cause. What might explain the gap? + +Step 3: Design a treatment. What change would address the hypothesis? + +Step 4: Test if possible. A/B test or before-after measurement when feasible. + +Step 5: Validate. Did the metric move? Did downstream metrics also benefit? + +Step 6: Roll out or roll back. Successful refinements stick; unsuccessful ones revert. + +The discipline. Each refinement is hypothesis-driven and validated. Random changes do not compound. + +--- + +## Redesign workflow + +How to redesign without resetting everything. + +Step 1: Articulate why. What has fundamentally changed that warrants redesign? + +Step 2: Preserve what works. Identify elements of the current architecture that are still appropriate. Do not throw away learning. + +Step 3: Design the new architecture. Segment matrix; entry-point routing; tool-to-funnel mapping; sequence architecture. Document everything. + +Step 4: Plan migration. How to transition existing audience and tools to the new architecture without losing momentum. + +Step 5: Pilot before full rollout. Test the new architecture with a subset of audience or one segment before full deployment. + +Step 6: Migrate. Roll out the new architecture; retire the old one. + +Step 7: Monitor closely. Architecture-level metrics in the first months show whether the redesign delivered. + +The discipline. Redesign is a project, not a flip of a switch. Plan it; pilot it; migrate; monitor. + +--- + +## The decay-driven redesign signal + +How to know decay has accumulated to redesign level. + +Signals. + +- Multiple refine cycles have not moved the metric. +- Segments no longer describe the audience accurately. +- Tools designed for one segment are being used by others (mapping has drifted). +- The architecture diagram no longer matches the actual experience visitors have. +- Quarterly audits surface the same issues quarter after quarter without fix. + +When these signals accumulate, refinement is not enough. Redesign is needed. + +--- + +## Iteration measurement + +How to know iterations are working. + +The metric. Architecture-level metrics improving over time. Cross-tool conversion rising; segment-level conversion rising; funnel-stage progression accelerating. + +The trap. Improving one metric while others decline. A refinement that lifts cross-tool conversion but tanks lead quality is not net positive. + +The discipline. Watch the portfolio of metrics, not individual ones. Refinement should improve the architecture's overall outcomes, not just one measure. + +--- + +## Common iteration failures + +Continuous redesign. Architecture never stabilizes; learning does not compound. + +Frozen architecture. Architecture never iterates; decay accumulates. + +Random refinement. Changes without hypothesis or testing; results are noise. + +Refinement without measurement. Cannot tell if changes are working. + +Redesign without preserving learning. Throws away what was working alongside what was not. + +Redesign without migration plan. Audience and tools left in transition; experience suffers. + +Iteration without portfolio metrics. Improving one metric while damaging others. + +--- + +## Methodology-level choices that stay in the public skill + +The compound-vs-reset distinction. When to refine (5 conditions). When to redesign (4 conditions). The continuous-redesign trap. The frozen-architecture trap. The middle ground. Refinement workflow. Redesign workflow. The decay-driven redesign signal. Iteration measurement. Common failures. + +## Implementation choices that stay internal + +Specific iteration calendars for the team. Specific refinement and redesign processes. Specific tooling for testing iterations. The team's iteration history and lessons. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md new file mode 100644 index 0000000..d23c914 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md @@ -0,0 +1,222 @@ +# Funnel measurement patterns + +Architecture-level vs tool-level metrics. What to measure, what is noise. + +Funnel measurement should reveal architecture quality, not just tool quality. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. + +--- + +## The architecture-vs-tool measurement distinction + +Two layers of measurement. + +Tool-level metrics. Each tool's individual performance (calculator conversion, quiz completion, lead-magnet downloads). Detail in each tool's skill. + +Architecture-level metrics. How the tools and sequences compose. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. + +The discipline. Measure both layers. Architecture-level metrics are often the missing measurement. + +--- + +## Architecture-level metric: Cross-tool conversion + +What percentage of audience that hits tool A then engages with tool B. + +The metric. Count the visitors who interact with tool A (calculator, quiz, lead magnet, etc.). Of those, how many subsequently interact with tool B? + +Why it matters. Cross-tool engagement signals whether the funnel is composing. High cross-tool conversion means the architecture is working; low cross-tool conversion means tools are silos. + +Measurement methods. + +- Identity-based tracking (same identified user across tools). +- Session-based tracking (same session sees multiple tools). +- Cohort analysis (cohorts entering through tool A and their downstream tool engagement). + +Diagnostic uses. + +- Low cross-tool conversion: tools may not be promoted to each other's audiences; transitions may be broken. +- Specific tool pairs underperforming: those transitions need design attention. + +--- + +## Architecture-level metric: Sequence-to-tool conversion + +What percentage of nurture sequence subscribers engage with downstream tools. + +The metric. Count subscribers in a sequence. Of those, how many click through to a tool the sequence promoted? + +Why it matters. Sequences should drive subscribers toward tools matched to their segment-and-stage. Low sequence-to-tool conversion signals that the sequences are not effectively bridging to tools. + +Diagnostic uses. + +- Specific sequence emails with low click-through: the email's tool promotion may not match the audience. +- Specific tools with low sequence-driven traffic: the sequences may not be promoting those tools enough. + +--- + +## Architecture-level metric: Segment-level downstream conversion + +Per-segment conversion to the program's main goal. + +The metric. For each segment in the matrix: what percentage convert to the main goal (trial, demo, purchase) within a defined timeframe? + +Why it matters. Different segments will convert at different rates; segments significantly underperforming relative to peers signal architecture issues. + +Diagnostic uses. + +- Segments with low downstream conversion: the funnel architecture for that segment may be broken or under-developed. +- Segments with high downstream conversion: investigate what is working; replicate to other segments. + +--- + +## Architecture-level metric: Funnel-stage progression + +What percentage of audience moves from awareness to consideration to decision over time. + +The metric. Track audience as they progress through stages. Awareness audience this month; what percentage are in consideration next month; what percentage in decision the following. + +Why it matters. The funnel's job is to progress audience through stages. Low progression signals the nurture sequences and tools are not advancing the relationship. + +Diagnostic uses. + +- Slow progression: sequences may be too educational without enough advancement; or the audience may be getting stuck. +- Fast progression but low conversion: progression without quality. + +--- + +## Tool-level metrics + +Each tool has its own metrics. Detail in each tool's skill. + +Calculator. Conversion rate per visitor; tier-2 (email gate) conversion; downstream conversion of calculator-sourced leads. + +Quiz. Completion rate; per-segment downstream conversion; recommendation click-through. + +Lead magnet. Download rate; sequence engagement; downstream conversion of magnet-sourced subscribers. + +Multi-step form. Completion rate; per-step drop-off; lead quality. + +Chatbot. Resolution rate per intent; escalation rate; downstream conversion. + +The tool-level metrics tell you whether each tool is doing its job. The architecture-level metrics tell you whether the tools are doing the funnel's job. + +--- + +## What is noise + +Metrics that look important but are not. + +Total tool engagements. Volume without context. A tool with 10000 engagements per month tells you nothing without conversion context. + +Email open rate alone. Open rate is a leading indicator at best; sequence-to-conversion is the metric that matters. + +Time on page or session length. Often correlates with confusion as much as engagement. + +Bounce rate alone. High bounce rate on awareness content may be normal; on decision content may signal a problem; aggregate bounce rate is noise. + +The discipline. Measure outcomes, not activity. Activity metrics are noise unless connected to outcome metrics. + +--- + +## Measurement granularity + +How granular to measure. + +Per-tool measurement. Standard. Each tool tracked. + +Per-segment-per-tool measurement. Measure each tool's performance per segment. Surfaces segment-specific tool issues. + +Per-segment-per-stage measurement. Measure progression and conversion per cell in the matrix. + +Per-cohort measurement. Track cohorts (groups arriving in the same period) over time. Surfaces evolution and decay. + +The discipline. Granularity matters when it informs decisions. Per-segment-per-stage is often where the diagnostic value lives; per-cohort surfaces decay. + +--- + +## Attribution + +Connecting outcomes to specific tools and sequences. + +The challenge. Audiences interact with multiple tools and sequences. Which one drove the conversion? + +Approaches. + +- First-touch attribution. Credit goes to the first interaction. +- Last-touch attribution. Credit goes to the most recent interaction. +- Multi-touch attribution. Credit distributed across interactions. +- Position-based attribution. Credit weighted by position (often U-shaped or W-shaped). + +The honest framing. Attribution is a model. No model is perfectly accurate. Choose a model deliberately; understand its biases; report consistently. + +--- + +## Measurement and architecture decisions + +How metrics inform architecture changes. + +The pattern. Metrics surface gaps; architecture decisions address them; subsequent metrics validate. + +Examples. + +- Cross-tool conversion low: redesign transitions; promote tool B in tool A's exit; measure improvement. +- Specific segment underperforming: review segment's funnel path; adjust tools or sequences; measure. +- Funnel-stage progression slow: review sequence design; add or refine; measure. + +The discipline. Metrics inform decisions; decisions are tested; results validated. Without measurement, architecture changes are guesswork. + +--- + +## Measurement instrumentation + +What needs to be in place. + +Identity tracking. Identified users tracked across tools. +Event tracking. Each tool interaction logged with event data. +Funnel definition. The funnel stages and segments defined in the analytics tool. +Cohort capability. Ability to define and track cohorts. +Reporting. Dashboards or reports that surface architecture-level metrics. + +The discipline. Instrumentation should be in place before launch, not added later. Retrofitting measurement is harder than building it in. + +--- + +## Measurement cadence + +How often to look at architecture-level metrics. + +Weekly review. For high-velocity programs or recently launched architectures. Catches regressions and informs rapid iteration. + +Monthly review. For stable programs. Tracks trends and surfaces gradual decay. + +Quarterly review. Comprehensive architecture audit. Per-cell analysis; segment-level deep dive; funnel-stage progression. + +Triggered review. When tools change, when segments shift, when external factors (market, competition) change. + +--- + +## Common measurement failures + +Tool-level only. Architecture-level metrics not tracked; cannot diagnose composition issues. + +Vanity metrics. Volume metrics without conversion context. + +No segment-level granularity. Aggregate metrics hide segment-specific issues. + +Attribution model not chosen. Reports inconsistent because attribution is ad-hoc. + +No cohort tracking. Cannot see decay or evolution. + +Metrics without action. Metrics reviewed but no decisions follow. + +Confounded data. Multiple changes deployed without isolation; cannot attribute outcomes to changes. + +--- + +## Methodology-level choices that stay in the public skill + +The architecture-vs-tool measurement distinction. Architecture-level metrics (cross-tool, sequence-to-tool, segment-level, funnel-stage). Tool-level metrics (cross-reference). What is noise. Measurement granularity. Attribution approaches. Measurement and architecture decisions. Instrumentation requirements. Measurement cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific programs. Specific tooling for measurement. Specific attribution models. The team's reporting conventions. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md new file mode 100644 index 0000000..6469028 --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md @@ -0,0 +1,256 @@ +# Nurture sequence architecture + +Per-segment, per-stage sequence variation. The matched sequence win. + +Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. Done well, sequences compound the brand's relationship with the audience; done poorly, sequences treat everyone the same and convert no one well. + +--- + +## The matched-sequence principle + +Each segment-and-stage cell warrants a sequence designed for that cell. Different cells get different sequences. + +The win. An SMB consideration-stage subscriber gets a 5-email sequence focused on SMB-relevant comparison content, ROI examples from similar SMB customers, and a soft demo invitation. The sequence reads as if written for them. + +The fail (kitchen-sink sequence). Every subscriber regardless of segment or stage gets the same 5-email sequence. The content is generic enough to send to all; specific enough for none. SMB subscribers see enterprise examples; enterprise subscribers see SMB examples; conversion uniformly low. + +The discipline. Sequences vary by segment and stage. The matrix from `audience-and-stage-segmentation` is the sequence design map. + +--- + +## Sequence variation by stage + +Stage-specific sequence patterns. + +Awareness sequence. + +- Goal: build relationship; deepen brand association with the topic. +- Content: educational, broad value, brand-building. +- Frequency: typically lower (weekly to bi-weekly); the audience is not in active research. +- Soft offers: subscribe to newsletter, follow on social, attend webinar. +- Hard offers: rare; awareness audiences are not buying yet. + +Consideration sequence. + +- Goal: move from "evaluating" to "selecting." +- Content: comparative, specific value, product-fit signals. +- Frequency: higher (every 3-7 days); audience is actively evaluating. +- Soft offers: see comparison guide, take quiz, calculator. +- Hard offers: demo, trial, talk to sales (toward end of sequence). + +Decision sequence. + +- Goal: commit; sign up; purchase. +- Content: confidence-building, risk-reversal, urgency cues, case studies of similar customers. +- Frequency: high (every 2-4 days); audience is close to deciding. +- Soft offers: rarely; mostly hard offers. +- Hard offers: trial, signup, talk to sales, custom quote. + +Customer sequence (often missed). + +- Goal: deepen success; expand and retain. +- Content: feature deep-dives, success stories from similar customers, community invitations. +- Frequency: ongoing; matches product cadence. +- Soft offers: attend events, refer others. +- Hard offers: upgrade, add-on, expansion. + +--- + +## Sequence variation by audience + +Audience-specific sequence patterns. + +SMB audience. + +- Tone: practical, fast-execution, peer-to-peer. +- Examples: SMB customers; focus on quick wins and resource constraints. +- Content depth: shorter, scannable, action-oriented. + +Mid-market audience. + +- Tone: strategic, considered, multi-stakeholder. +- Examples: mid-market customers; focus on team adoption and process change. +- Content depth: moderate; depth where it matters; summaries for executives. + +Enterprise audience. + +- Tone: rigorous, evidence-based, formal. +- Examples: enterprise customers; focus on security, scale, integration. +- Content depth: deep; white papers, technical documentation, case studies with metrics. + +Solo or creator audience. + +- Tone: personal, founder-to-founder. +- Examples: similar solo practitioners; focus on individual impact and time savings. +- Content depth: practical; templates and how-tos over strategy. + +--- + +## Sequence design discipline + +How to design each sequence. + +Step 1: Define the goal. What conversion does this sequence drive? Awareness to consideration; consideration to demo; demo to decision; decision to purchase. + +Step 2: Define the audience. Which segment-and-stage cell does this sequence serve? + +Step 3: Outline the arc. What is the email-by-email progression? Each email should have a purpose; cumulatively the arc moves the subscriber toward the goal. + +Step 4: Match content to arc. What specific content (template, case study, framework, demo invitation) fits each step? + +Step 5: Define triggers and cadence. What triggers the sequence (lead magnet download, demo request, behavior signal)? What is the spacing? + +Step 6: Define the soft and hard offers. Where do soft offers appear? Where do hard offers appear? At what point does the sequence make a direct ask? + +Step 7: Define the exit. When does the sequence end? Where do subscribers go after (newsletter, segment-specific stream, retired)? + +The output is a documented sequence ready to build and ship. + +--- + +## Sequence cadence + +How frequently to send. + +Awareness cadence. Weekly to bi-weekly typical. The audience is not in active research; over-sending feels intrusive. + +Consideration cadence. Every 3-7 days typical. The audience is actively evaluating; cadence matches their consideration pace. + +Decision cadence. Every 2-4 days typical. The audience is close to deciding; cadence reflects urgency. + +Customer cadence. Variable. Match product cadence and customer engagement patterns. + +The cadence-too-frequent risk. Daily sends can fatigue; unsubscribe rates climb. + +The cadence-too-infrequent risk. Weekly sends to consideration audiences can lose momentum; the audience moves on. + +--- + +## Sequence content sourcing + +Where the content for sequences comes from. + +Repurposed content. Existing blog posts, case studies, white papers can populate sequences. Cost-effective; benefits from existing content investments. + +Sequence-original content. Content written specifically for the sequence. More effort; can be highly tailored to the audience and arc. + +Hybrid. Most sequences mix repurposed and original. Original content for the key arc moments; repurposed content for supplementary value. + +The discipline. Sequence content should fit the sequence's audience and stage; off-fit content (even good content) weakens the sequence. + +--- + +## Sequence triggers + +What launches the sequence. + +Trigger types. + +- Lead magnet download. Most common trigger. +- Calculator completion. With segment data captured. +- Quiz completion. With segment matched to result. +- Multi-step form submission. Demo request, qualification. +- Behavior signal. Visited specific pages, viewed pricing, abandoned cart. +- Manual addition. Sales team adds a contact. + +The trigger discipline. The trigger informs which sequence the subscriber enters. A lead-magnet download for an awareness-stage resource enters the awareness sequence; a calculator completion with consideration-stage signals enters the consideration sequence. + +Trigger-segment routing. Multiple triggers can route to multiple sequences based on captured segment information. The trigger is one signal; segment is another. + +--- + +## Sequence intersection and routing + +When subscribers might enter multiple sequences. + +The challenge. A subscriber downloads two lead magnets in the same week. Each magnet has its own sequence. Should they enter both? + +Approaches. + +- Override. Latest trigger overrides; subscriber enters the latest sequence and exits prior ones. +- Concatenate. Subscriber completes the first sequence, then enters the next. +- Pause. Active sequence pauses other triggers; subscriber returns to queue after current sequence. +- Multi-path. Subscriber enters multiple sequences simultaneously (risk of frequency overload). + +The choice depends on subscriber experience and sequence design. Most programs benefit from override or pause patterns to avoid frequency overload. + +--- + +## Sequence and offer alignment + +The offers in the sequence must match the audience. + +The principle. A sequence for SMB consideration-stage subscribers should pitch SMB-appropriate offers. Pitching enterprise offers in this sequence wastes the audience signal. + +Offer alignment failures. + +- Magnet attracts SMB; sequence pitches enterprise. +- Awareness sequence pitches hard sales offers prematurely. +- Decision sequence pitches awareness content the subscriber outgrew. + +The cure. Sequence offers reflect the audience and stage the sequence serves. + +--- + +## Sequence measurement + +Per-sequence metrics. + +Open rate. Per email; per sequence overall. + +Click-through rate. Per email; per sequence. + +Conversion to next step. What percentage of subscribers in this sequence completed the desired conversion? + +Unsubscribe rate. Per email; per sequence. + +Sequence-to-customer conversion. What percentage of subscribers in this sequence eventually became customers? + +Diagnostic uses. Low open rates per email signal subject-line issues; low click-through signals content fit issues; high unsubscribe rates signal cadence or content problems. + +--- + +## Sequence maintenance + +Sequences decay. + +What decays. + +- Content references go stale (outdated case studies, retired products). +- Offers change (new products, new pricing, new programs). +- Audience composition shifts; sequence content no longer fits. +- Email deliverability changes; subject lines that worked stop working. + +Maintenance cadence. Quarterly review of every active sequence. Update content; refresh offers; verify links. + +The drift indicator. Sequence performance declining over time signals decay; specific cohorts (newer subscribers vs older) performing differently signals audience shift. + +--- + +## Common sequence failures + +One sequence for everyone. Kitchen-sink pattern; matches no segment specifically. + +Sequence-trigger mismatch. The trigger captured one segment; the sequence is designed for another. + +Offer misalignment. Sequence pitches offers that do not match the audience. + +Cadence wrong for stage. Awareness cadence on consideration audience; consideration cadence on awareness audience. + +No trigger logic. Subscribers enter the same default sequence regardless of how they were captured. + +Sequence-orphan magnets. Lead magnets without follow-up sequences; subscribers go cold. + +Stale sequence content. Sequence designed once; content no longer reflects the brand or product. + +No sequence measurement. Sequence performance unknown; maintenance is guesswork. + +--- + +## Methodology-level choices that stay in the public skill + +The matched-sequence principle. Sequence variation by stage (4 stages). Sequence variation by audience (4 audiences). Sequence design discipline (7 steps). Sequence cadence. Sequence content sourcing. Sequence triggers. Sequence intersection and routing (4 approaches). Sequence and offer alignment. Sequence measurement. Sequence maintenance. Common failures. + +## Implementation choices that stay internal + +Specific sequences for specific segments. Specific email content in brand voice. Specific tooling for sequence automation and measurement. The team's cadence baselines. These vary by team. diff --git a/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md b/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md new file mode 100644 index 0000000..61de4bf --- /dev/null +++ b/dist/pi/.agents/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md @@ -0,0 +1,225 @@ +# Tool-to-funnel mapping + +Which tools serve which entry points and segments. Each tool in the growth toolkit has a place in the funnel architecture; the mapping makes the place explicit. + +Without explicit mapping, tools end up serving everyone (and serving no one well) or getting deployed where they do not fit. With explicit mapping, each tool serves the segments where it adds the most value. + +--- + +## The mapping principle + +Each tool serves specific segments at specific stages from specific entry points. The mapping is documented, not implicit. + +The win. A team's calculator is mapped to consideration-stage SMB and mid-market visitors arriving via organic content. The calculator's design (inputs, defaults, methodology) reflects this segment. Other segments do not see the calculator featured prominently; they see tools matched to their segment. + +The fail. A team's calculator is featured on every page for every visitor. The calculator's design is generic to serve everyone. SMB visitors see enterprise inputs; enterprise visitors see SMB defaults. The calculator serves nobody well. + +The discipline. Each tool has a defined place. The architecture documents which segments and stages and entry points the tool serves. + +--- + +## Common tool-to-funnel mappings + +How each growth tool typically maps. + +Lead magnet. Often serves awareness-to-consideration transition. + +- Audience: awareness-stage visitors who would benefit from a focused resource. +- Entry points: blog posts, content discovery, paid ads on educational topics. +- Position in funnel: captures email; routes to nurture sequence that bridges to consideration. +- Detail in `lead-magnet-design`. + +Calculator. Often serves consideration stage. + +- Audience: visitors evaluating options who need to defend a specific decision. +- Entry points: pricing pages, comparison content, paid ads on solution-evaluation. +- Position in funnel: provides defensible numeric output; routes to demo or trial CTA. +- Detail in `calculator-design`. + +Quiz. Variable depending on design. + +- Awareness quizzes: content marketing, brand-building. Captures email; routes to broad nurture sequence. +- Consideration quizzes: product matching, fit assessment. Captures email; routes to product-specific sequence. +- Decision quizzes: plan selection, configuration. Captures email and routes to specific sales motion or signup. +- Detail in `quiz-and-assessment-design`. + +Multi-step form. Often serves decision or qualification stage. + +- Audience: visitors with high intent who need to provide structured information. +- Entry points: demo CTAs, talk-to-sales pages, application flows. +- Position in funnel: captures qualified intent; routes to sales or to next-stage automation. +- Detail in `multi-step-form-design`. + +Chatbot. Cross-cutting; can serve any stage with intent recognition routing. + +- Audience: any visitor who has questions the bot can handle. +- Entry points: any page where conversation might add value. +- Position in funnel: handles in-conversation routing; escalates to humans for complex cases. +- Detail in `chatbot-flow-design`. + +--- + +## Mapping examples by audience segment + +How tools map for specific segments. + +Solo founder, awareness stage. + +- Lead magnet: practical template they can use today. +- Quiz (optional): "what stage of growth are you in" with matched recommendations. +- Chatbot: yes, for FAQ; lightweight routing. +- Calculator, multi-step form: probably not at this stage. + +SMB team, consideration stage. + +- Calculator: ROI estimate matched to SMB context. +- Lead magnet: comparison guide or worked example. +- Multi-step form: demo request capture. +- Chatbot: yes, for product-specific questions. +- Quiz (optional): plan recommendation. + +Mid-market team, consideration-to-decision. + +- Calculator: ROI estimate with mid-market context. +- Multi-step form: demo request with qualification. +- Chatbot: yes, with escalation to sales for complex questions. +- Lead magnet (optional): white paper or case study. +- Quiz: probably not (mid-market buyers often skip quizzes). + +Enterprise, decision stage. + +- Multi-step form: enterprise demo request with detailed qualification. +- Chatbot: lightweight; escalation-heavy. +- Custom calculator: with enterprise-specific inputs and ROI factors. +- Lead magnet, quiz: usually not (enterprise buyers expect direct human attention). + +The mapping is segment-aware. Tools that fit one segment may not fit another. + +--- + +## Mapping examples by stage + +How tools map for specific stages. + +Awareness stage. + +- Lead magnets prominent. Quizzes can serve. Calculators less common (consideration is when calculators earn their value). Chatbots support. +- Goal: capture awareness-stage email; route to nurture sequence. + +Consideration stage. + +- Calculators central. Quizzes useful for product matching. Lead magnets can deepen value. Chatbots support specific questions. +- Goal: convert consideration into qualified intent; route to demo or trial. + +Decision stage. + +- Multi-step forms central (demo requests, qualified intent capture). Calculators support specific decisions. Chatbots route to sales. +- Goal: convert decision-stage intent into commitment. + +Customer stage. + +- Onboarding flows (which can use multi-step forms). Chatbots for support. Lead magnets and quizzes less central; replaced by in-product education. +- Goal: deepen customer success; expand and retain. + +--- + +## Mapping discipline + +How to make the mapping rigorous. + +Discipline 1: Document the mapping. Write down which tools serve which segments and stages. The document is the architecture's reference. + +Discipline 2: Match tool design to mapping. A tool serving SMB should have SMB-relevant inputs and defaults; a tool serving enterprise should reflect enterprise context. + +Discipline 3: Promote tools where they fit. Show calculators on consideration-stage pages; show lead magnets on awareness-stage pages. Generic tool placement on every page dilutes their value. + +Discipline 4: Retire tools that do not fit. A tool that does not have a mapping is decorative. Either find its place or retire it. + +Discipline 5: Audit the mapping quarterly. Mappings decay as audience composition shifts. Quarterly review catches drift. + +--- + +## Multi-tool segments + +Some segments use multiple tools across their journey. + +The pattern. A consideration-stage SMB visitor uses a lead magnet (awareness arrival), a calculator (consideration depth), then a multi-step demo form (decision intent). Three tools across the journey. + +Architecture implications. + +- Each tool serves a specific moment in the visitor's journey. +- Cross-tool data flow lets each tool benefit from earlier interactions. +- Tools should not duplicate each other's value. + +The discipline. Tools complement, not duplicate. Each tool earns its place in the segment's journey. + +--- + +## Tool overlap and choice + +When multiple tools could serve the same segment-and-stage cell. + +The pattern. A team has both a calculator and a quiz that could serve consideration-stage SMB. + +The decision. Choose the tool that serves the segment best, or use both with clear differentiation. + +- Calculator: when the consideration involves a specific calculation (ROI, savings, sizing). +- Quiz: when the consideration involves categorization or product matching. +- Both: when the segment benefits from both, with clear positioning of when each helps. + +The discipline. Avoid having multiple tools competing for the same segment without clear differentiation. Audiences pick the most prominent; the others underperform. + +--- + +## Tool gaps + +When the mapping reveals gaps. + +The pattern. The architecture documents which tools serve which segments. Some cells in the matrix have no tool; the audience there has no relevant tool to engage with. + +The decision. Either build a tool to fill the gap, or accept that some cells use generic content rather than tools. + +- Build when the segment is high-value and the tool would meaningfully improve conversion. +- Accept when the segment is small or the tool would not earn its build cost. + +The architecture surfaces gaps; the team decides what to do about them. + +--- + +## Tool-mapping audit + +Periodically audit which tools serve which segments and how well. + +The audit. + +- For each tool: which segments does it currently serve? Which segments does it actually attract? +- For each cell in the matrix: which tools are mapped to it? Are they performing? +- Are any tools serving segments outside their intended mapping (drift)? + +The drift indicators. Tool conversion drops; tool's audience composition changes; tool gets traffic from segments it was not designed for. + +--- + +## Common mapping failures + +No mapping. Tools deployed without explicit segment-and-stage assignment. + +Mismatched mapping. Tool serving segments it was not designed for; tool's design does not fit the audience. + +Decorative mapping. Mapping documented but not enforced; tool appears everywhere regardless of mapping. + +Stale mapping. Mapping designed once; not updated as tools or audiences evolved. + +Tool overlap without differentiation. Multiple tools competing for the same segment; audience splits; none performs well. + +Mapping gaps unaddressed. Cells in the matrix have no tool support; the architecture has holes. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle. Common tool-to-funnel mappings (5 tools). Mapping examples by audience segment (4 examples). Mapping examples by stage (4 examples). Mapping discipline (5 disciplines). Multi-tool segments. Tool overlap and choice. Tool gaps. Tool-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific tool-to-segment mappings for specific programs. Specific tool placement decisions on specific pages. The team's audit calendars. These vary by team and program. diff --git a/dist/pi/.agents/skills/incident-response/SKILL.md b/dist/pi/.agents/skills/incident-response/SKILL.md new file mode 100644 index 0000000..f484749 --- /dev/null +++ b/dist/pi/.agents/skills/incident-response/SKILL.md @@ -0,0 +1,260 @@ +--- +name: incident-response +description: "Manage active production incidents through detection, triage, mitigation, communication, and resolution with structured roles and decision-making. Use this skill whenever the user has an active incident, a production issue, a service outage, a security incident, or needs to plan incident response procedures. Triggers on incident response, production incident, outage, service down, site down, P0, P1, severity, downtime, on-call, incident commander, status page, postmortem prep. Also triggers when something is actively broken in production and the user is figuring out what to do." +category: operations +catalog_summary: "Incident triage, comms, mitigation, escalation" +display_order: 2 +--- + +# Incident Response + +Manage active production incidents from detection to resolution. Stack-agnostic. Tool-agnostic. + +This skill is for active incidents and incident process. For after-the-fact analysis, use `after-action-report`. For planned launches, use `launch-runbook`. + +--- + +## When to use + +- An active incident is happening +- Building incident response procedures +- Defining severity levels +- Setting up on-call rotations +- Training a team on incident response + +## When NOT to use + +- Post-incident retrospective (use `after-action-report`) +- Planned launches (use `launch-runbook`) +- Pre-launch issue triage (use `qa-testing`) + +--- + +## Required inputs + +- Awareness of the incident (alert, customer report, internal observation) +- Access to production systems and monitoring +- Roles and authorities clearly defined +- Communication channels operational + +--- + +## The framework: 5 phases + +### 1. Detection + +How the incident becomes known. + +Detection sources: + +- Automated alerts (monitoring, SLO violations, error rate spikes) +- Customer reports (support tickets, social media, status page subscribers) +- Internal observation (engineer notices something off) +- Third-party (security researchers, partners) + +On detection: + +- Acknowledge within target time (typically 5 to 15 minutes for critical) +- Assess severity (see severity rubric below) +- Page the on-call if not already paged +- Open the incident channel + +### 2. Triage + +Establish severity and impact. + +Severity rubric: + +\| Severity \| Definition \| Response \| +\|---\|---\|---\| +\| SEV-1 (Critical) \| Major customer-facing functionality broken. Data integrity at risk. Security breach. \| All-hands. Incident commander. Active war room. Public communication required. \| +\| SEV-2 (Major) \| Significant degradation. Some customers affected. Revenue impact. \| Incident commander assigned. Active response. Internal communication. May or may not need public communication. \| +\| SEV-3 (Minor) \| Limited impact. Workaround available. Affecting a small group of users. \| Standard on-call response. Single owner. \| +\| SEV-4 (Low) \| Cosmetic, edge-case, or low-frequency. No urgent action needed. \| Tracked as bug. Addressed in normal queue. \| + +Severity can change. Re-evaluate as more info emerges. + +### 3. Mitigation + +Stop the bleeding before fixing the cause. + +Mitigation patterns (faster than full fix): + +- Rollback (revert recent deploy) +- Feature flag off (disable the broken feature without deploy) +- Failover (route to healthy replica or region) +- Scale up (more capacity to absorb the load) +- Throttle (reject some traffic to protect the rest) +- Graceful degradation (turn off non-essential features to keep core functional) +- Maintenance mode (last resort, blocks all users) + +Mitigation principle: Stop user impact first. Cause analysis second. + +### 4. Communication + +Three audiences during an incident: + +Internal team: +- Real-time updates in incident channel +- Cadence: every 15 minutes minimum during active incident +- Format: timestamped status updates with what we know, what we're doing, ETA + +Internal stakeholders: +- Higher-level updates to broader org +- Cadence: every 30 to 60 minutes +- Format: business-impact framing, not technical detail + +External / customers: +- Status page updates +- Cadence: every 30 minutes minimum during active incident +- Format: plain language, no blame, what users are experiencing, what to expect + +Communication principles: +- Acknowledge before you have answers ("We're aware and investigating") +- Update on schedule even if no progress ("Still investigating, no new information") +- Never speculate publicly about cause +- Confirm resolution explicitly when restored + +### 5. Resolution + +Verified fix, customers restored, incident closed. + +Resolution criteria: + +- Mitigation in place and verified +- Root cause identified (or explicitly deferred to AAR) +- All affected systems back to normal +- Customers can resume normal use +- Final status update posted (internal and external) +- Incident channel can be closed (or archived for AAR) + +After closure: +- Schedule AAR within 1 to 2 weeks +- Capture initial timeline while memories are fresh +- Track follow-up action items + +--- + +## Roles during an incident + +\| Role \| Responsibility \| +\|---\|---\| +\| Incident commander (IC) \| Owns the response. Calls decisions. Assigns work. Not necessarily the most technical person; needs to coordinate. \| +\| Communications lead \| Owns internal and external messaging. Reduces IC's communication burden. \| +\| Operations lead \| Drives the technical investigation and mitigation. Often the most senior on-call engineer. \| +\| Scribe \| Captures the timeline as the incident unfolds. Critical for AAR. \| +\| Subject matter experts \| Pulled in as needed. Service owners, database experts, security experts. \| + +For small teams or low-severity incidents, one person can hold multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Decision-making during an incident + +The IC's authority: + +- Call rollback or other mitigations +- Pull additional people in +- Escalate severity +- Make the call when unclear options exist + +Non-decisions to avoid: + +- "Let's wait and see" when mitigations are available and impact is occurring +- Discussing root cause while users are actively impacted (mitigate first) +- Premature resolution announcements before verification +- Death-by-committee (pull in lots of people, no one decides) + +When in doubt: act. A wrong action that can be rolled back beats inaction while users suffer. + +--- + +## Status page communication patterns + +Initial: +> "We are investigating reports of [issue]. Updates to follow." + +Identified: +> "We have identified the issue affecting [scope]. Engineers are working on a fix. Next update by [time]." + +Monitoring: +> "A fix has been applied. We are monitoring to confirm resolution. Next update by [time]." + +Resolved: +> "This incident has been resolved. Service has been restored. A full incident report will be posted within [timeframe]." + +Patterns to avoid: + +- Vague language ("experiencing some issues" - what kind?) +- Missing affected scope ("login is down" - everywhere or just one region?) +- Missing time commitments +- "Should be resolved soon" without verification +- Using "back up" before verification + +--- + +## Workflow + +1. Acknowledge. First responder acknowledges within target time. +2. Assess severity. Use the rubric. Open the appropriate response channel. +3. Assign roles. IC, comms, ops at minimum. +4. Communicate. Initial status update. Internal channel active. +5. Investigate. Logs, metrics, recent changes. The four most common causes: a recent deploy, a configuration change, a third-party dependency change, a load spike. +6. Mitigate. Stop the bleeding. Don't wait for full root cause. +7. Verify mitigation. Don't trust dashboards alone; test the user flow. +8. Communicate resolution. Internal and external. +9. Close incident. Final timeline noted. Action items tracked. +10. Schedule AAR. Within 1 to 2 weeks. + +--- + +## Failure patterns + +- No clear IC. Multiple people debugging in parallel, no coordination. Slower to mitigate, easier to make conflicting changes. +- Skipping mitigation, going straight to root cause. Users keep suffering while engineers debug. +- Premature "all clear." Announcing resolution before verification. +- Communication silence. Users don't know if anyone is working on it. +- Status updates too vague. "We're working on it" with no detail. +- Speculating publicly about cause. Often wrong, always damaging trust. +- Pulling in too many people. Coordination overhead exceeds value. +- No scribe. The timeline gets lost. AAR has to reconstruct from chat logs. +- Skipping AAR for "minor" incidents. Patterns get missed. Lessons get re-learned. +- Blame culture. People hide mistakes, incidents take longer. + +--- + +## Output format + +During an active incident: incident channel updates and status page updates as per the framework above. + +After incident close: a brief incident summary feeding into the AAR. + +```markdown +# Incident: [Brief title] + +Date: [YYYY-MM-DD] +Severity: [SEV-1 / 2 / 3 / 4] +Duration: [Detection to resolution] +Customer impact: [Who, how many, how] + +## Summary +[1 to 2 paragraphs] + +## Timeline +[Timestamped events] + +## Mitigation +[What was done] + +## Action items +[Follow-ups, with owners] + +## AAR scheduled for +[Date] +``` + +--- + +## Reference files + +- [`references/incident-playbook.md`](references/incident-playbook.md) - Severity definitions, roles, status page templates, decision rubrics. diff --git a/dist/pi/.agents/skills/incident-response/references/incident-playbook.md b/dist/pi/.agents/skills/incident-response/references/incident-playbook.md new file mode 100644 index 0000000..b960f45 --- /dev/null +++ b/dist/pi/.agents/skills/incident-response/references/incident-playbook.md @@ -0,0 +1,280 @@ +# Incident Playbook + +The reference document during an incident. Severity definitions, role responsibilities, communication templates, and decision rubrics. + +--- + +## Severity rubric + +### SEV-1: Critical + +Definition: +- Major customer-facing functionality completely broken +- Data loss or data integrity at risk +- Active security breach or vulnerability being exploited +- Significant revenue impact ongoing + +Response: +- All-hands response activated +- Incident commander assigned (within 10 minutes of detection) +- War room (video call) opened +- Public status page updated immediately +- Executive notification within 15 minutes +- Customer-facing communication within 30 minutes + +Acknowledgment SLA: 5 minutes +Update cadence: Every 15 minutes +Resolution target: As fast as humanly possible + +### SEV-2: Major + +Definition: +- Significant degradation affecting many users +- Important feature unavailable +- Performance severely degraded +- Revenue impact, but limited + +Response: +- Incident commander assigned (within 30 minutes) +- Active investigation in incident channel +- Status page updated +- Internal communication to broader org +- Public communication if customer-facing + +Acknowledgment SLA: 15 minutes +Update cadence: Every 30 minutes +Resolution target: Within hours + +### SEV-3: Minor + +Definition: +- Limited impact (specific feature, specific user segment) +- Workaround available +- No revenue impact, or minor + +Response: +- Single owner assigned +- Standard on-call response +- No status page update unless customer-facing +- No public communication unless trending + +Acknowledgment SLA: 1 hour +Update cadence: As progress dictates +Resolution target: Within a day + +### SEV-4: Low + +Definition: +- Cosmetic issue +- Edge case affecting few users +- No customer impact + +Response: +- Track as bug, not incident +- Address in normal queue + +Acknowledgment SLA: Next business day +Resolution target: As prioritized + +--- + +## Roles + +### Incident Commander (IC) + +Responsibilities: +- Owns the response +- Makes decisions when options exist +- Assigns work to others +- Decides when to escalate severity +- Decides when to declare resolution +- Coordinates without doing technical work themselves + +NOT the IC's job: +- Doing the actual debugging +- Speculating about cause publicly +- Writing status page updates (delegates to comms lead) + +Selection criteria: Calm under pressure, good at coordination, clear communicator. Does not need to be the most senior or most technical. + +### Communications Lead + +Responsibilities: +- Posts internal updates on schedule +- Drafts status page updates +- Coordinates with customer support +- Drafts executive notifications +- Manages external messaging + +Removes: Communication burden from IC and ops lead. + +### Operations Lead + +Responsibilities: +- Drives the technical investigation +- Identifies the cause +- Identifies and applies mitigations +- Coordinates with subject matter experts +- Verifies fixes + +### Scribe + +Responsibilities: +- Captures the timeline as the incident unfolds +- Records decisions and rationale +- Records actions taken +- Provides material for the AAR + +Often filled by: A junior engineer (good learning experience), someone not in the active investigation, or anyone tasked specifically with note-taking. + +### Subject Matter Experts (SMEs) + +Pulled in as needed. Service owners, database experts, security experts, third-party vendors. Pulled by IC, not self-deploying. + +--- + +## Status page templates + +### SEV-1 / SEV-2 initial + +> "We are currently investigating reports of [user-facing description of impact]. Affected users may experience [specific symptoms]. We will update by [time, typically +30 minutes]." + +### Identified + +> "We have identified the cause of the issue affecting [scope]. Engineers are deploying a fix. Next update by [time]." + +### Monitoring + +> "A fix has been applied. We are monitoring to confirm full resolution. Next update by [time]." + +### Resolved + +> "This incident has been resolved. All services have returned to normal. A full incident report will be posted within [typically 1 week]. Thank you for your patience." + +### Patterns to avoid + +\| Avoid \| Why \| Use instead \| +\|---\|---\|---\| +\| "Some users may be experiencing issues" \| Vague \| "Users in [region] may experience [specific symptom]" \| +\| "We are working on it" \| Empty \| "Engineers are investigating [hypothesis or symptom]" \| +\| "Should be resolved shortly" \| Speculative \| "Next update by [specific time]" \| +\| "We apologize for the inconvenience" \| Hollow \| Acknowledge specifically, then state action \| +\| Technical jargon \| Excludes users \| Plain language describing user experience \| +\| Blame language \| "Our database vendor failed" \| Focus on user impact and our response \| + +--- + +## Decision rubrics + +### Should we roll back? + +Roll back if: +- A recent deploy correlates with the start of the incident +- Rollback can be completed safely +- The risk of leaving the broken state exceeds the risk of rollback + +Don't roll back if: +- The incident clearly predates the recent deploy +- Rollback would cause data loss or worse impact +- A targeted fix is available and faster + +When unsure: roll back. Recovery from rollback is usually cheaper than continued debugging in a broken state. + +### Should we declare SEV-1? + +Declare SEV-1 if any are true: +- Most users cannot use the core product +- Revenue is being lost at significant rate +- Data integrity is at risk +- A security breach is happening +- Senior leadership awareness is required + +When unsure between SEV-1 and SEV-2: start with SEV-1. Easier to de-escalate than to scale up. + +### Should we communicate publicly? + +Communicate publicly if any are true: +- Customers are experiencing impact and will notice +- Customer support is receiving inquiries +- The incident is visible externally (status page, social media chatter) +- Regulatory notification may be required (data breach, certain financial systems) + +Don't communicate publicly if: +- Impact is invisible to users +- Confidence is high that it will be resolved before users notice (but lean toward communication) + +When unsure: communicate. Silence on the status page is worse than a brief acknowledgment. + +### Should we escalate? + +Escalate to senior leadership if: +- Severity has reached SEV-1 +- Resolution is taking longer than expected at SEV-2 +- Decisions are needed that exceed the IC's authority +- Reputational risk is material + +--- + +## On-call rotation principles + +A healthy on-call: + +- Rotates regularly. Same person on call indefinitely is unsustainable. +- Has a clear primary and secondary. Backup if primary is unavailable. +- Has documented runbooks. On-call is not pop quiz. +- Has acknowledgment SLAs that match severity. A 1-hour SLA on SEV-1 is too slow. +- Is paid or compensated in some form. Time on-call has cost. +- Includes a hand-off ritual. Outgoing on-call briefs incoming on open issues, recent deploys, hot spots. + +Anti-patterns: + +- One person who is "always on" because they know the system best +- On-call without monitoring (you can only respond to what you know) +- On-call who lacks production access (cannot mitigate) +- No primary/backup, just one person + +--- + +## Common mitigation patterns + +\| Symptom \| Try first \| +\|---\|---\| +\| Errors after recent deploy \| Roll back the deploy \| +\| Errors with no recent deploy \| Check third-party dependencies, recent config changes \| +\| Database errors \| Check connection pool, recent query changes, capacity \| +\| Latency spike \| Check load, capacity, slow downstream \| +\| Specific feature broken \| Feature flag off if available \| +\| Security incident \| Isolate affected systems, rotate credentials, preserve logs \| +\| Data integrity issue \| Stop writes, snapshot, investigate before continuing \| + +When unsure of cause but mitigation is available: mitigate. Investigate cause separately. + +--- + +## After the incident + +Once resolved: + +1. Final status page update (resolved) +2. Final internal update +3. Capture initial timeline (the scribe's notes) +4. Identify obvious follow-up action items, file tickets +5. Schedule AAR within 1 to 2 weeks +6. Hand off any monitoring to normal operations + +In the next 24 to 48 hours, while memory is fresh: + +- Each participant writes their own brief account of what they observed and did +- These individual accounts become primary source material for the AAR +- This avoids reconstruction errors that come from trying to piece together what happened weeks later + +--- + +## Anti-patterns to call out + +- Hero culture. One person stays up all night to fix it; gets praised. Real lesson: the system is too brittle, and the team has too little redundancy. +- Blame in retrospectives. "Whose fault was this?" produces hidden mistakes next time. +- Skipping AARs for "minor" incidents. The minor incidents are often the patterns that predict major ones. +- Action items that never close. Action items get filed, never actioned. The same incident recurs. +- Status pages updated only at start and end. "Updating every 30 minutes" with the same content is still better than silence. +- Investigating root cause while users are impacted. Mitigate first. diff --git a/dist/pi/.agents/skills/information-architecture/SKILL.md b/dist/pi/.agents/skills/information-architecture/SKILL.md new file mode 100644 index 0000000..b77d8a7 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/SKILL.md @@ -0,0 +1,254 @@ +--- +name: information-architecture +description: "Design the structure of a website or product including sitemap, navigation, URL structure, content types, taxonomy, and labeling. Use this skill whenever the user asks to plan a sitemap, design navigation, structure URLs, define content types, build taxonomies, design site search, or organize content at the system level. Triggers on sitemap, site structure, navigation, IA, information architecture, URL structure, content types, taxonomy, categorization, breadcrumbs, hub pages, faceted navigation, site search, labeling. Also triggers when content is being created without a structural plan, or when an existing site's structure is being audited or restructured." +category: strategy-and-discovery +catalog_summary: "Sitemap, navigation, URL structure, content types, taxonomy" +display_order: 4 +--- + +# Information Architecture + +Design the structure that holds the content. Stack-agnostic. Applies to marketing sites, product surfaces, knowledge bases, e-commerce, and editorial content. + +A well-designed IA makes the rest of the project easier. A poorly-designed IA forces every downstream decision to fight the structure. + +--- + +## When to use + +- Designing a new site or major section from scratch +- Restructuring an existing site +- Adding a new content type or category +- Designing site navigation or menu systems +- Defining URL structure and slug patterns +- Building taxonomies or tag systems +- Auditing an existing IA for problems + +## When NOT to use + +- Single-page design (use `design-standards`) +- Content production (use `content-and-copy`) +- SEO-driven content planning (use `seo-keyword`) +- Initial brand and audience discovery (use `brand-discovery`) + +--- + +## Required inputs + +- The site or product scope +- The audience and what they're trying to do +- The content that exists or is planned +- Any constraints (parent IA, regulatory, technical) + +If audience is unclear, run `brand-discovery` first. If content scope is unclear, run `content-strategy` first. + +--- + +## The framework: 6 layers + +Information architecture has six layers. Each builds on the one below. + +### 1. Mental models + +Before structure, understand how the audience thinks about the domain. + +- What concepts do they group together naturally? +- What words do they use? (Often different from what the company uses.) +- What is the dominant frame of reference? (By task? By role? By topic? By time?) +- What do they expect to find where, based on conventions in similar products? + +Methods: + +- Card sorting (open or closed): Give the audience the content items, ask them to group them. Open card sorts surface natural groupings. Closed card sorts validate proposed groupings. +- Tree testing: Give a proposed structure, ask users to find specific items. Surfaces where the structure breaks down. +- First-click testing: Given a goal, where do users click first? If first clicks are wrong, the labels and structure are wrong. + +### 2. Sitemap + +The map of all pages and how they relate. + +Sitemap deliverables: + +- A hierarchy diagram showing parent-child relationships +- Indication of page types (static, dynamic, listing, detail) +- Cross-references showing how pages relate beyond the hierarchy +- Sometimes a separate user-flow overlay for key journeys + +Sitemap types: + +- Hub-and-spoke (cornerstone content + supporting content): Common for content marketing +- Tree (strict hierarchy, every page has one parent): Common for product documentation +- Faceted (content lives in many overlapping categories): Common for e-commerce +- Flat (everything reachable from the home): Common for small sites + +Most sites blend types. Pick the dominant pattern and document the exceptions. + +### 3. URL structure + +URLs are part of the IA. They are user-facing, indexed by search engines, and shape how content is referenced. + +URL principles: + +- Reflect the content hierarchy +- Lowercase, hyphen-separated +- Predictable (same pattern across same content type) +- Stable (URLs don't change without redirects) +- Short (under 60 characters where possible) +- Descriptive (slug indicates the content) +- Free of dates unless time-bound +- Free of session IDs and tracking parameters in canonical form + +Common patterns: + +``` +/ home +/[section] section landing +/[section]/[subsection] subsection landing +/[section]/[subsection]/[item] detail page +/blog blog index +/blog/[slug] blog post +/blog/category/[category] category index +/blog/tag/[tag] tag index +/products product catalog +/products/[category] category page +/products/[category]/[product] product detail +``` + +Pick a pattern and stick to it. Inconsistent URL patterns confuse users, crawlers, and analytics. + +### 4. Navigation + +The chrome that gets users where they need to go. + +Primary navigation: + +- The top-level structure of the site +- Should reflect what the audience cares about, not what the org chart looks like +- 5 to 7 items maximum (more becomes cognitively heavy) +- Each label is recognizable in 2 to 3 words +- Order matters (left/first gets the most attention) + +Secondary navigation: + +- Within-section navigation +- Often shown as sidebars, sub-menus, or in-page tabs +- Supports the primary nav, doesn't duplicate it + +Utility navigation: + +- Account, search, login, support +- Visually subordinate to primary nav +- Often top-right (LTR languages) + +Breadcrumbs: + +- For nested hierarchies (3+ levels deep) +- Always linked except the current page +- Match the URL hierarchy or the conceptual hierarchy +- Marked up with BreadcrumbList schema + +Footer navigation: + +- Comprehensive; sometimes includes everything +- Organized by category for findability +- Includes secondary content (privacy, terms, contact) + +### 5. Taxonomy and metadata + +The classification system applied to content. + +Categories: + +- A small, controlled list (typically 5 to 15) +- Mutually exclusive ideal (one item, one category) +- Used for structural navigation + +Tags: + +- A larger, often growing list (50+) +- Multi-assignment (one item, many tags) +- Used for cross-cutting connections, related-content, and long-tail discovery + +Metadata fields: + +- Author, date, content type, audience segment +- Whatever is useful for filtering, sorting, and surfacing + +Common failures: + +- Categories that overlap (item could go in 3 different categories) +- Tags that are unmaintained (sprawl into thousands, become useless) +- Metadata fields that get filled inconsistently +- Different content types using different taxonomies for the same thing (chaos) + +### 6. Labeling + +What you call things. + +Label principles: + +- Audience language, not internal language +- Specific enough to be useful, short enough to scan +- Consistent across the site (call it "Product" or "Solutions" but not both) +- Tested with real users (closed card sort or tree test surfaces label problems) + +Common label problems: + +- "Solutions" (vague; usually means "products with marketing copy") +- "Resources" (catch-all; everything ends up there) +- Internal jargon ("PRD," "OKRs") that doesn't match user vocabulary +- Labels that change meaning across the site + +--- + +## Workflow + +1. Understand the audience and content. Use existing discovery and content strategy if available. +2. Card sort or interview to surface mental models. +3. Draft the sitemap. Hierarchy, page types, cross-references. +4. Define URL patterns. One pattern per content type. +5. Design navigation. Primary, secondary, utility, footer, breadcrumbs. +6. Build taxonomy. Categories (controlled, small) and tags (open, large). +7. Validate labels. Tree test or closed card sort with target users. +8. Document. Use the template in [`references/ia-document-template.md`](references/ia-document-template.md). +9. Hand off to design and development. IA decisions inform navigation components, URL routing, and taxonomy implementation. + +--- + +## Failure patterns + +- IA designed by org chart. "Engineering" and "Marketing" sections make sense to the company, not to the audience. +- Categories that proliferate. Every team adds a category for their thing. Becomes unscannable. Hold the line at 5 to 15. +- Tags that sprawl. No tag governance. Tags become a junk drawer. +- Inconsistent URL patterns. Some posts at /blog/[slug], some at /[slug], some at /articles/[slug]. Pick one. +- Navigation that hides primary content. The most important pages should be one click from home. +- Search as a substitute for IA. "Just use search" is not a structure. Search supports IA, doesn't replace it. +- No validation. Card sorts, tree tests, and first-click tests are cheap and surface huge problems early. +- Treating IA as a one-time deliverable. IA evolves with content. Plan for evolution. + +--- + +## Output format + +Default output is an IA document at `information-architecture.md` plus visual assets: + +1. Executive summary +2. Audience and mental models (synthesized) +3. Sitemap (hierarchical diagram) +4. URL structure (per content type) +5. Navigation specification (primary, secondary, utility, footer, breadcrumbs) +6. Taxonomy (categories and tag governance) +7. Labels (validated wording for navigation, categories, content types) +8. Implementation notes for design and development + +Visual deliverables: +- Sitemap diagram (Whimsical, Figma, OmniGraffle, etc.) +- Navigation wireframes for primary surfaces +- Optional: card sort and tree test results + +--- + +## Reference files + +- [`references/ia-document-template.md`](references/ia-document-template.md) - Template for the IA deliverable. +- [`references/url-pattern-library.md`](references/url-pattern-library.md) - URL pattern conventions for common content types. diff --git a/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md b/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md new file mode 100644 index 0000000..4f7ad12 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/references/ia-document-template.md @@ -0,0 +1,298 @@ +# Information Architecture Document Template + +A fillable template for the IA deliverable. Captures the sitemap, navigation, content types, taxonomy, and URL conventions. + +The IA document is the single source of truth for "what is this site, structurally." Engineering, design, content, and SEO all reference it. + +--- + +## Project metadata + +Site / app: [Name] +Phase: [New build / restructure / refresh] +Date: [YYYY-MM-DD] +IA lead: [Name] +Status: [Draft / In review / Approved] + +--- + +## 1. Audience and intent + +The IA serves audience tasks. Start with the tasks. + +### Primary audiences + +\| Audience \| Top tasks on this site \| +\|---\|---\| +\| \| \| +\| \| \| +\| \| \| + +### Top tasks + +The 5-10 things people most commonly want to do or find. + +1. [Task] +2. [Task] +3. [Task] +4. [Task] +5. [Task] + +Each task should be discoverable in 3 clicks or fewer from the homepage. + +--- + +## 2. Sitemap + +The full set of pages the site contains, organized by hierarchy. + +### Top-level navigation + +The 4-7 sections that appear in the main nav. + +``` +Home +├── [Section 1] +├── [Section 2] +├── [Section 3] +├── [Section 4] +├── [Section 5] +└── [Utility nav: Login, Search, Cart, etc.] +``` + +### Full sitemap + +``` +Home (/) +├── Section 1 (/section-1/) +│ ├── Sub-page 1.1 (/section-1/sub-page-1-1/) +│ ├── Sub-page 1.2 (/section-1/sub-page-1-2/) +│ └── Sub-page 1.3 (/section-1/sub-page-1-3/) +├── Section 2 (/section-2/) +│ ├── Category 2.1 (/section-2/category-2-1/) +│ │ └── Detail pages (/section-2/category-2-1/[slug]/) +│ └── Category 2.2 (/section-2/category-2-2/) +├── Section 3 (/section-3/) +├── About (/about/) +├── Contact (/contact/) +├── Legal +│ ├── Privacy (/privacy/) +│ ├── Terms (/terms/) +│ └── Cookies (/cookies/) +└── 404 (/[unmatched]) +``` + +### Pages outside primary nav + +Pages that exist but are not in the top nav. Reachable from footers, contextual links, search, or direct entry. + +\| Page \| URL \| Reached from \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## 3. Navigation + +### Primary nav + +- Items: [List] +- Behavior on desktop: [Always visible / dropdown / mega menu] +- Behavior on mobile: [Hamburger / bottom nav / slide-in] +- Active state indicator: [Underline / color / weight] +- Sticky on scroll: [Yes / no] + +### Secondary nav + +If applicable. Examples: section nav within a section, sidebar nav for docs, breadcrumbs. + +- Used in: [Sections] +- Pattern: [Sidebar / breadcrumbs / tabs / pills] + +### Utility nav + +Login, search, cart, language switcher, account. Where they live on desktop and mobile. + +### Footer nav + +Comprehensive map of the site, plus legal and contact. + +- Sections: [Group names and what is in each] +- Treatment: [Links only / links + descriptions / multi-column / single column on mobile] + +--- + +## 4. Content types + +The reusable patterns that pages fall into. Each content type has a defined schema. + +### Content type: [Name, e.g., "Article"] + +- Purpose: [What this content type is for] +- Required fields: [Title, body, author, publish date, etc.] +- Optional fields: [Hero image, related articles, summary] +- URL pattern: [`/blog/[slug]/`] +- Template: [Which page template renders this] +- SEO defaults: [Default title pattern, meta description pattern, schema type] +- Open Graph defaults: [OG image source, OG type] + +(Repeat for each content type: page, article, product, case study, landing page, author, category, tag, etc.) + +--- + +## 5. Taxonomy + +How content is organized and tagged for filtering, related-content surfacing, and navigation. + +### Categories (hierarchical) + +The primary classification, often used in URLs. + +- Category 1 + - Subcategory 1.1 + - Subcategory 1.2 +- Category 2 + +Categories are typically mutually exclusive (a piece belongs to one). + +### Tags (flat, multi-select) + +Cross-cutting attributes a piece can have multiple of. + +- [Tag] +- [Tag] +- [Tag] + +### Custom taxonomies + +Domain-specific facets (e.g., for a recipe site: cuisine, dietary, cook time, meal type). + +\| Taxonomy \| Values \| Used by content types \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## 6. URL conventions + +See `url-pattern-library.md` for the full URL pattern reference. The IA document captures decisions specific to this site. + +\| Type \| Pattern \| Example \| +\|---\|---\|---\| +\| Home \| `/` \| `/` \| +\| Static page \| `/[slug]/` \| `/about/` \| +\| Section landing \| `/[section]/` \| `/products/` \| +\| Article detail \| `/blog/[slug]/` \| `/blog/how-to-x/` \| +\| Product detail \| `/products/[slug]/` \| `/products/widget/` \| +\| Category archive \| `/category/[slug]/` \| `/category/news/` \| +\| Tag archive \| `/tag/[slug]/` \| `/tag/announcements/` \| +\| Author page \| `/author/[slug]/` \| `/author/jane-doe/` \| +\| Search results \| `/search/?q=[query]` \| `/search/?q=widget` \| + +### Trailing slash policy + +[All URLs end with trailing slash / no trailing slash. Pick one and enforce via redirect.] + +### Casing + +[Lowercase only. Hyphens for word separation.] + +--- + +## 7. Search + +- In-site search included?: [Yes / no] +- Source of truth: [Internal index, Algolia, Elasticsearch, native CMS search] +- Surface in nav: [Always visible / icon-only / hidden behind utility nav] +- Result page URL: [`/search/?q=[query]`] +- Result types: [Pages, articles, products, etc.] +- Filters: [What filters appear on the result page] +- Empty-state message: [Text and suggested actions] + +--- + +## 8. Cross-linking strategy + +How pages link to other pages within the site. + +### Hub-and-spoke + +Pillar pages (hubs) link to related detailed pages (spokes). Spokes link back to the hub. + +\| Hub \| Spokes \| +\|---\|---\| +\| `/topic-area/` \| `/topic-area/[detail-1]`, `/topic-area/[detail-2]` \| + +### Related content blocks + +Where they appear, what populates them. + +- Article footer: [Same category / same tag / manually curated] +- Product detail page: [Same category, similar price, frequently bought with] +- Sidebar: [Trending, recent] + +### Contextual links in body copy + +The single highest-value cross-link mechanism. Editorial guidelines: + +- Link the first natural mention of a related topic +- 2-5 contextual links per article +- Anchor text describes the destination, not "click here" + +--- + +## 9. Pagination, infinite scroll, and load more + +For listing pages (archives, search, category, etc.). + +\| Listing type \| Pattern \| Page size \| URL behavior \| +\|---\|---\|---\|---\| +\| Article archive \| Pagination \| 10 per page \| `/blog/page/2/` \| +\| Search results \| Load more \| 20 per page \| URL stays at `/search/?q=...` \| +\| Product grid \| Pagination \| 24 per page \| `/products/?page=2` \| + +Pick deliberately. Each pattern affects SEO, accessibility, and analytics. + +--- + +## 10. Multilingual / multi-region + +If applicable. See `internationalization` skill for full guidance. + +- Languages supported: [List] +- Regions supported: [List] +- URL pattern for locale: [`/en/`, `/es/` subdir / `en.example.com` subdomain / no prefix on default locale] +- Hreflang strategy: [How locale alternates are declared] +- Default locale fallback: [What happens for unmatched locales] + +--- + +## 11. Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## 12. Change log + +\| Date \| Change \| Approved by \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## Sign-off + +IA approved by: + +- IA lead: [Name, date] +- Engineering lead: [Name, date] +- Content lead: [Name, date] +- SEO lead: [Name, date] + +Implementation can begin: [Date] diff --git a/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md b/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md new file mode 100644 index 0000000..75bf052 --- /dev/null +++ b/dist/pi/.agents/skills/information-architecture/references/url-pattern-library.md @@ -0,0 +1,377 @@ +# URL Pattern Library + +Conventional URL patterns for common content types. Use as a starting point. Adapt for the specific site. + +URL patterns matter because: +- Users see them in the address bar +- Search engines use them as a relevance signal +- They appear in shared links and citations +- Inconsistent patterns are a structural smell that creates downstream problems + +--- + +## Universal principles + +Apply to every URL on every site: + +- Lowercase. `/about` not `/About`. +- Hyphens, not underscores. `/blog/getting-started` not `/blog/getting_started`. +- No trailing slash for non-folder URLs (or always with trailing slash; pick one and be consistent). +- No file extensions. `/about` not `/about.html` or `/about.php`. +- No query strings in canonical URLs. Filters and sorts can use query strings, but the canonical version is parameter-free. +- Stable. URLs do not change without a 301 redirect from the old URL. +- Predictable. Same content type uses the same URL pattern site-wide. + +--- + +## Marketing site patterns + +### Home + +``` +/ +``` + +### Top-level pages + +``` +/about +/contact +/pricing +/careers +/blog +/help +``` + +Avoid generic catch-alls like `/info` or `/page`. + +### Sub-pages within sections + +``` +/about/team +/about/values +/about/history +/careers/engineering +/careers/design +``` + +Two levels deep is the typical maximum for marketing site pages. Beyond that, structure usually breaks down. + +### Marketing landing pages + +``` +/[campaign-slug] short, memorable, often used in print/ads +/lp/[campaign-slug] namespaced under /lp for clarity +/[product]/[campaign] nested under product if relevant +``` + +For high-traffic ad campaigns, a short root-level URL is fine. For evergreen marketing pages, namespace them. + +--- + +## Blog and editorial patterns + +### Blog index + +``` +/blog +``` + +### Blog posts + +``` +/blog/[slug] +``` + +The dominant pattern. Simple, scannable, no dates in the URL (so updates don't change the URL). + +If dates are genuinely required (news sites, time-sensitive content): + +``` +/blog/[year]/[month]/[slug] +``` + +But avoid dates by default. They make URLs longer and stale-looking when content gets updated. + +### Categories and tags + +``` +/blog/category/[category-slug] +/blog/tag/[tag-slug] +``` + +Or, if you prefer cleaner URLs: + +``` +/blog/[category-slug]/[post-slug] embeds category in the post URL +``` + +The embedded version is cleaner but creates URL changes when posts move categories. Pick based on whether posts move categories. + +### Author pages + +``` +/author/[author-slug] +/blog/author/[author-slug] +``` + +The first if authors are site-wide. The second if authors are blog-specific. + +### Archive pages + +``` +/blog/archive/[year] +/blog/archive/[year]/[month] +``` + +Optional, mostly for SEO and historical browsing. Often noindexed if they don't add unique value. + +--- + +## Product / e-commerce patterns + +### Product catalog + +``` +/products +/shop +``` + +Pick one and use site-wide. Don't have both. + +### Categories + +``` +/products/[category] +``` + +### Sub-categories + +``` +/products/[category]/[subcategory] +``` + +Two levels of category is typical maximum. Deeper hierarchies hurt findability. + +### Product detail + +``` +/products/[category]/[product-slug] +/products/[product-slug] if categorization isn't critical +``` + +The first is more SEO-friendly (signals category relevance). The second is cleaner but loses the hierarchy signal. + +### Filters and search + +``` +/products/[category]?filter=value&sort=price-asc filters as query strings +``` + +Canonical URL ignores query strings. Use the bare category URL as the canonical. + +--- + +## Documentation patterns + +### Docs root + +``` +/docs +/help +/support +``` + +### Sections + +``` +/docs/getting-started +/docs/api +/docs/integrations +``` + +### Pages within sections + +``` +/docs/getting-started/installation +/docs/api/authentication +/docs/integrations/slack +``` + +Two to three levels is typical. Deeper hierarchies become hard to navigate. + +### API reference + +``` +/docs/api/[endpoint] +/docs/api/v[N]/[endpoint] versioned APIs +/api-reference/[endpoint] if API docs are separate +``` + +--- + +## Account and product surface patterns + +These are the URLs inside an authenticated product. Not visible to crawlers but still matter for usability and consistency. + +### Dashboard + +``` +/dashboard +/app +/home inside the product, not the marketing site +``` + +### Settings + +``` +/settings +/settings/[section] +/account +/account/[section] +``` + +### Resources within an account + +``` +/projects +/projects/[id] +/projects/[id]/[resource] +/projects/[id]/[resource]/[item-id] +``` + +For e-commerce or SaaS, IDs matter more than slugs since these are user-specific items. + +--- + +## Special URL patterns + +### Search results + +``` +/search?q=[query] +``` + +Or, for SEO-friendly search landing pages: + +``` +/search/[query] +/find/[query] +``` + +The second pattern creates indexable search pages, which can be useful or harmful depending on the site. + +### Filter/facet pages (e-commerce or directory) + +``` +/[category]/[filter-slug] e.g., /running-shoes/men +/[category]?[filter]=[value] filters via query string +``` + +Static filter pages are SEO-friendly. Dynamic query strings are cleaner but don't index. + +### Pagination + +``` +/blog/page/2 +/blog/page/3 +/blog?page=2 via query string +``` + +The path-based version is more SEO-friendly. Either works as long as you canonical correctly. + +### Profile pages + +``` +/u/[username] +/users/[username] +/profile/[username] +/[username] if usernames don't conflict with other paths +``` + +The last (root-level usernames) is the cleanest but requires careful conflict prevention. + +### Internationalization + +``` +/[locale]/[path] e.g., /en/about, /es/about +[subdomain].domain.com/[path] e.g., en.domain.com/about +domain.[ccTLD]/[path] e.g., domain.fr/about +``` + +Each has tradeoffs. Path-based is most flexible. Subdomain is good for cleanly separated content. ccTLD is best for genuine country targeting. + +Use hreflang tags to indicate language pairs regardless of the URL strategy. + +--- + +## URL anti-patterns + +### Anti-pattern: Tracking parameters in canonical URLs + +``` +Bad: /post?utm_source=newsletter +Good: /post (with utm parameters preserved at runtime but stripped from canonical) +``` + +UTM parameters are for analytics, not for canonical URLs. + +### Anti-pattern: Session IDs in URLs + +``` +Bad: /products?sid=ABC123 +Good: /products (session in cookies, not URL) +``` + +URLs should be safe to share. Session IDs in URLs leak sessions when shared. + +### Anti-pattern: Verb-heavy URLs + +``` +Bad: /show-product/[id] +Good: /products/[id] +``` + +URLs are nouns, not verbs. + +### Anti-pattern: Date in URLs for evergreen content + +``` +Bad: /blog/2024/05/how-to-write-headlines +Good: /blog/how-to-write-headlines +``` + +Dates make URLs feel stale. They also break when posts get updated. + +### Anti-pattern: Stop words in URLs + +``` +Acceptable: /the-best-running-shoes +Better: /best-running-shoes +``` + +Removing "the," "and," "of" makes URLs shorter without losing meaning. + +### Anti-pattern: Fragment-only navigation + +``` +Bad: /home#features (no /features page) +Good: /features (real URL) +``` + +Fragments don't index. Real pages do. + +--- + +## Migration considerations + +When changing URL patterns on an existing site: + +1. Map every old URL to a new URL. No exceptions. +2. 301 redirect old URLs to new. Permanent redirect preserves SEO equity. +3. Avoid redirect chains. Old URL should redirect directly to the new URL, not to an intermediate. +4. Update internal links. Every internal link should point at the new URL, not the old. +5. Update sitemap. New URLs only, no legacy URLs. +6. Wait 90+ days before removing redirects. Search engines and external sites take time to update. + +See `seo-technical/references/migration-checklist.md` for the full migration playbook. diff --git a/dist/pi/.agents/skills/integration-orchestrator/SKILL.md b/dist/pi/.agents/skills/integration-orchestrator/SKILL.md new file mode 100644 index 0000000..9a80690 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/SKILL.md @@ -0,0 +1,171 @@ +--- +name: integration-orchestrator +description: "Generate a phased delivery orchestration plan for creative-direction-driven work: which skills run when, what locks at which gate, how handoffs occur, and how the cadence implements in the team's tools (Jira, Linear, Notion, Figma, GitHub) with AI agents via MCP and CLI. A temporal map of phases, lock points, handoff specs, gate definitions, and QA verification gates. Distinct from `creative-brief` (static project brief) and `creative-direction` (aesthetic direction). Triggers on integration orchestrator, delivery cadence, project orchestration, when does the brief lock, how to phase creative direction, design-development handoff, QA gate, agent-driven QA, and when a creative-direction project is starting, mid-flight with broken cadence, or integrating AI agents into PM workflow. Does NOT fire for project scoping (use `creative-brief`), aesthetic direction (use `creative-direction`), or general project management without a creative-direction throughline." +category: product +catalog_summary: "Sequence creative-direction work across phases, gates, handoffs, and QA verification" +display_order: 3 +--- + +# Integration Orchestrator + +A brief tells a team what to make. Creative direction tells them what it should feel like. Neither tells them when each decision locks, who reviews what, or what stops the next phase from starting before the prior one is done. That is the gap this skill fills. + +The output is a phased orchestration plan the PM can paste into a calendar Monday morning and start running Tuesday. Phases, gates, lock points, handoffs, QA verification rules, and a platform-specific implementation guide for whatever stack the team actually uses (Jira, Linear, Notion, Figma, GitHub, agile sprints). + +--- + +## What this skill is + +A creative-direction project has three layers. The brief layer defines scope, audience, deliverables, constraints, success criteria. The direction layer defines tone, aesthetic, relationship, and sensory ambition. Both produce written artifacts. Neither answers the temporal question: when does the brief lock, when does identity lock, when does copy lock, who reviews each, what gets blocked while a gate is open, what happens when a downstream task discovers the brief is wrong, and what makes "Done" mean tested rather than self-reported. + +This skill produces that temporal layer. Most teams have briefs and creative direction but no orchestration plan. The result, by week 3, is everyone working in parallel with no shared sense of which decisions are still open and which are locked. Brief drift. Re-work. Identity tokens shifted after copy was already drafted against the old ones. Engineering shipping before design had a chance to review. "Done" tickets that were never actually verified. + +The orchestration plan answers all of that. It is not theory. It is a phased timeline with calendar weeks, ticket templates the PM can paste into Jira or Linear, MCP commands for setup, gate definitions with measurable pass criteria, handoff specs with artifact requirements, and QA verification gates with Playwright or Chrome MCP invocations. + +--- + +## When to use + +- Starting a new brand build, rebrand, or campaign and the team needs to sequence the work +- Mid-flight project where the brief is being revisited and downstream work is suffering from constant resets +- Setting up a new team's agent-driven workflow with MCPs and CLI integration +- Multi-team work where handoffs between brand, design, and engineering have broken down +- Establishing QA verification gates so "Done" is measurable, not self-reported +- Migrating from ad-hoc orchestration to a documented cadence +- Onboarding a new PM or design lead onto an existing project that has running tickets but no documented sequencing +- Adding new platforms or tools to an existing workflow and the cadence needs to be re-mapped + +--- + +## When NOT to use + +- Use `creative-brief` instead if the deliverable is the project brief itself: scope, audience, deliverables, constraints, success criteria. The orchestrator skill takes the brief as input. +- Use `creative-direction` if the deliverable is the aesthetic direction: tone, aesthetic, relationship, sensory. The orchestrator schedules the work that answers to the direction; it does not produce the direction. +- Generic project management software is the platform; this skill produces the plan that runs IN the platform. Do not run this skill if the team needs help picking a tool; it assumes the tool stack is already chosen. +- Sprint-planning tactics (story-pointing, retros, velocity charts) live downstream of orchestration. The skill produces the cadence; sprint planning fills it in. + +--- + +## Required inputs + +- Project type. New brand build, rebrand, single landing page, campaign, identity refresh, website refresh, microsite, product launch. The type implies a default phase decomposition that the skill adapts to the specific project. +- Team composition. Total size and role mix. Solo, small (2-3), medium (4-7), large (8+). Whether AI agents (Claude Code, Claude in Chrome, others) participate in production, QA, or both. +- Tool stack. Which of Jira, Linear, Notion, Figma, GitHub the team uses. Plus QA tooling (Playwright, Chrome MCP, Windows MCP, mobile testing harnesses) if known. Plus communication and paging channel (Slack, email, in-tool mention). The output adapts to the actual stack. +- Timeline target. Express (compressed timelines, fewer reviewers, accept higher rework risk), standard (typical cadence at the project type's default duration), or thorough (more reviewers, formal phase reviews, lower rework risk at the cost of slower delivery). +- Existing constraints. What is already locked? Brief approved, identity locked, platform fixed, brand voice already shipped, content management system non-negotiable. The orchestrator plan handles greenfield and mid-flight equally; the existing constraints input is how mid-flight projects are accommodated. +- AI agent participation. Which workflows include agents and at what fidelity. Examples: Claude Code does production tasks against a state file in the repo; Claude in Chrome runs human-readable QA flows on the staging deployment; the agent has access to the Linear MCP and the GitHub MCP but not Jira; the agent can move tickets between Todo, In Progress, Waiting, and Blocked but cannot move to Done (Done requires a human verification step). +- Risk profile. Optional input naming the failure modes the team is most worried about: brief drift, parallel-work conflicts, QA gaps, agent runaway. The orchestration plan front-loads mitigations for the named risks. + +--- + +## The framework: 7 considerations for orchestration + +A delivery orchestration plan sits at the intersection of seven considerations. Each filters the choices that follow. + +### 1. Phasing + +How the project decomposes into phases. The standard shape is discovery, direction, identity, production, QA, and launch. Not every project type uses every phase. A campaign skips identity (it inherits the locked brand identity). A landing page collapses discovery and direction into a single brief phase. A rebrand replaces discovery with audit (positioning is known; the audit assesses what to keep). + +The shape of the phases matters less than the explicit answer to two questions per project: which phases run sequentially because the downstream phase cannot start without the prior phase's output, and which phases overlap because their outputs do not depend on each other. Identity must complete before copy starts (copy depends on tone-axis position, which is part of identity). QA must complete before launch. Discovery and audit may overlap with brief drafting, because the brief consumes discovery findings as they emerge. + +### 2. Gates + +A gate is the approval moment that governs phase transition. The standard gates are brief approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, and launch readiness. Each gate has a trigger (the work that opens it), an approver (the person or test suite that passes it), required-to-pass criteria (the measurable thing that says yes or no), what's blocked until the gate passes, and what's already locked from prior gates. + +Gates work when the criteria are measurable. "Brief approved" is too vague; "client signed the brief artifact in writing or in a recorded review" is measurable. "QA passed" is too vague; "Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained" is measurable. Gates that are not measurable become political; gates that are measurable become structural. + +### 3. Lock points + +A lock point is the moment an artifact becomes immutable. The brief locks after direction is approved. Identity tokens lock after the identity gate. Voice rules lock after voice approval. Copy locks per page after copy approval. Once locked, the artifact cannot be changed by downstream work; it can only change via a formal change request that triggers re-review of dependent work. + +Without explicit lock points, every artifact is conceptually editable forever. That is the source of brief drift. The orchestrator plan names what locks at which gate, where the locked artifact lives, who can request a change, and what gets re-reviewed if a change is approved. Locked is not the same as final; locked means "any further change to this triggers downstream review work, so make changes deliberately." + +### 4. Handoffs + +A handoff is the moment work transfers between phases or skills. The standard handoffs are discovery to brief, brief to identity, brief to voice, identity plus voice to copy, identity plus copy to design, design to engineering, engineering to launch. Each transfers specific artifacts and decisions. Each leaves some things open and locks others. + +There is also a cross-cutting handoff: the adjacent observation handoff. While working on the homepage hero, an agent or person notices the footer copy is inconsistent with the new voice. That observation is not the current task. It is filed as an observation in the project triage queue. The PM or tech lead reviews observations on a regular cadence and triages them into proper tickets. This pattern keeps current work focused while not losing the contextually-relevant findings the team would otherwise either drop or derail current work to address. + +### 5. Team-size modulation + +A 2-person team and a 12-person team need different orchestration. Solo work is one person playing every role. Small (2-3) means a single reviewer per gate and async handoffs are fine. Medium (4-7) needs multiple reviewers and async sync points. Large (8+) needs formal phase reviews, a dedicated PM for orchestration, and explicit cross-track sync ceremonies because parallel tracks drift apart without them. + +The orchestration plan output modulates by scale. Solo gets self-review checklists per phase. Small gets per-gate "review by" assignments. Medium gets reviewer rotation and within-phase mini-gates. Large gets formal phase reviews, cross-track sync, and a brief-owner role. The framework is the same; the cadence's review density and ceremony level change. + +### 6. Tool-stack implementation + +Phases and gates exist in concept; they implement in tools. The orchestration plan specifies the implementation per platform: in Jira, phases become Epics with custom fields for "Phase", "Locked", "Approver", and "Gate Status"; in Linear, phases become Projects with cycles and label-driven views; in Notion, the brief becomes a database row with relation properties tying to direction docs, identity specs, voice guides, and copy decks; in Figma, phases become library folders with frame-level review status; in GitHub, phases interact with branch protection, PR templates, and CODEOWNERS-driven review routing. + +Where MCPs exist (Atlassian, Linear, Notion, GitHub), the plan specifies which orchestration setup operations the MCP can execute and which remain manual UI work. Where MCPs are limited (Figma's Dev Mode MCP is dev-mode-focused; the design library setup remains manual), the plan documents the recommendation without claiming end-to-end automation. + +### 7. Automation and QA verification + +The single most consequential discipline in the framework. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The standard status taxonomy is Todo, In Progress, Waiting, Blocked, Done. Blocked is a first-class status, distinct from Waiting. Waiting means the task is paused for normal handoff or scheduled review; Blocked means the task cannot proceed without human resolution of a specific issue. Agents move tasks to Blocked when they cannot autonomously resolve work; this prevents agents from spinning on un-resolvable problems and burning context. + +QA verification gates fire automatically. Playwright MCP runs critical-flow tests; Chrome MCP runs human-readable walkthroughs and captures evidence; Windows MCP handles desktop apps; mobile testing harnesses cover mobile applications. Failure routes to Blocked, files an adjacent observation if the failure surfaced something unrelated, pages the human via the configured channel, and stops. The agent does not retry autonomously. + +--- + +## Common project-type cadences + +Seven templates. Each is a skeletal phase map; the cadence-patterns reference file expands each. + +- New brand build. 6 to 8 weeks across 5 phases: Discovery (1 week), Direction (1 week), Identity (1 to 2 weeks), Production (2 to 3 weeks), Launch (1 week). Gates fire after each phase; identity locks before copy starts. +- Rebrand. 4 to 6 weeks across 4 phases: Audit (1 week, replaces Discovery), Direction (1 week), Identity (1 to 2 weeks), Production (1 to 2 weeks). Audit assumes positioning and audience are known; the work is assessing what to keep, drop, or refresh. +- Single landing page. 1 to 2 weeks across 3 phases: Brief (2 to 3 days), Production (5 to 7 days), QA-Launch (1 to 2 days). Identity is assumed locked. Voice is assumed locked. The work is page-specific copy, design, and engineering. +- Campaign. 2 to 4 weeks across 4 phases: Brief (3 to 5 days), Production (1 to 2 weeks), QA (3 to 5 days), Launch (1 to 2 days). Campaign assumes brand identity and voice exist and are locked. +- Identity refresh. 3 to 4 weeks across 3 phases: Audit (1 week), Identity (1 to 2 weeks), Production (1 week). Skips discovery and positioning. The output is a refreshed identity system that goes into production for application examples. +- Website refresh. 4 to 8 weeks across 4 phases: Audit (1 week), Direction (1 week), Production (2 to 4 weeks), QA-Launch (1 to 2 weeks). Direction may produce a refreshed brief if the audit surfaces positioning gaps. +- Microsite or product launch. 3 to 5 weeks across 4 phases: Brief (3 to 5 days), Production (2 to 3 weeks), QA (3 to 5 days), Launch (2 to 3 days). The microsite or product launch usually has a fixed launch date that drives backward planning. + +Each cadence reads as if the PM could paste it into a calendar and start running. Phase boundaries align with calendar weeks where possible, because that is how teams actually plan. + +--- + +## Failure patterns + +The orchestration plan exists to prevent these. Each is a real failure mode, observed in the wild on real projects. + +- Brief becomes a write-once doc. The brief is drafted, signed, then nobody references it again. Downstream work drifts. The fix: lock the brief at a gate and treat any reference to it as a reading, not an edit. +- Brief gets unfrozen mid-flight without re-reviewing dependent work. Someone tweaks the brief's audience or positioning; the change does not propagate to identity, voice, or copy that already depend on the old version. The fix: a formal change-request protocol that triggers re-review of dependent artifacts. +- Identity locks before voice. The typography is finalized before the voice is approved. Result: the type and the voice register conflict (a friendly voice in austere type, or a serious voice in casual type). The fix: voice approval gate fires before or alongside identity lock. +- Copy starts before voice locks. Writers draft against a moving target. Rework is invisible because the original draft never gets compared against the locked voice. The fix: voice approval before copy production. +- Multiple parallel design tracks lose brief alignment. Track A and Track B both interpret the brief slightly differently; by week 3 the two tracks read as different brands. The fix: cross-track sync ceremonies and a brief-owner role. +- Engineering starts before design freeze. Components get built against design that is still moving. Rework downstream when design lands somewhere else. The fix: design approval gate before engineering starts on the affected surface. +- Reviews stack at end of phase. Everyone defers their review to the final day; the gate becomes a 10-hour review marathon and approvers approve under fatigue. The fix: within-phase mini-gates that flatten review demand. +- Async handoffs without artifact specification. "Hand the design over to engineering" without specifying what artifacts (Figma file URL, exported tokens, asset library reference, PR draft template) means engineering opens half a dozen Slack threads to find what they need. The fix: explicit artifact specification per handoff. +- QA gate is self-reported. "Done" tickets get moved to Done without verification. Bugs land in production. The fix: automated verification that fires before status transitions to Done; failure routes to Blocked. +- Agents spin on un-resolvable work. A Claude Code task cannot resolve itself; the agent retries, burns context, runs out of tokens, leaves the work in a worse state than when it started. The fix: Blocked is a first-class status; agents move tasks to Blocked when they cannot autonomously resolve, document the blocker, and stop. + +--- + +## Output format + +Default output is a markdown document, typically saved as `ORCHESTRATION.md` at the project root or in a `docs/` subdirectory. The document contains the full plan and is the canonical reference for the team. + +Structure: + +1. Project orchestration plan. Phased timeline with calendar weeks, milestone dates, phase outputs. +2. Per-phase gate specs. What enters, what exits, who approves, the measurable pass criteria for each gate including the QA verification gate. +3. Lock-point register. What becomes immutable when, where the locked artifact lives, who can request a change, and what re-review work a change triggers. +4. Tool-stack implementation guide. Concrete setup for Jira, Linear, Notion, Figma, and GitHub as applicable, with MCP commands or CLI invocations for the parts that automate. +5. QA verification gate spec. Which automated tests must pass, which MCPs run them, where evidence attaches, what happens on failure. +6. Handoff specs. Artifacts transferred per handoff, locked items, change-request protocols, adjacent-observation routing. +7. Cross-skill dependency graph. Which skills run in which phase, what each skill consumes, what each produces. +8. Risk register. Cadence-specific risks with mitigations. + +The document is the orchestration plan. The next step after delivery is for the PM to set up the team's tools to match (Jira epics, Linear projects, Notion databases, Figma libraries, GitHub branch protection) and start running the plan. + +--- + +## Reference files + +- [`references/cadence-patterns.md`](references/cadence-patterns.md). The 7 project-type cadences in detail with phase decomposition, timelines, gate definitions, and tool-stack implementation skeletons. +- [`references/gate-definitions.md`](references/gate-definitions.md). Each standard gate with trigger, approver, pass criteria, what's blocked, what's already locked, and change-request protocols. +- [`references/handoff-protocols.md`](references/handoff-protocols.md). The standard handoffs between phases and skills, plus the adjacent observation handoff for filing things noticed while working nearby. +- [`references/platform-implementation.md`](references/platform-implementation.md). How the orchestration maps to Jira, Linear, Notion, Figma, and GitHub, including MCP integration notes per platform and CLI alternatives where MCP is the wrong tool. +- [`references/team-size-modulation.md`](references/team-size-modulation.md). How cadences scale across solo, small, medium, and large teams. +- [`references/automation-and-qa-tooling.md`](references/automation-and-qa-tooling.md). The QA verification gate pattern, MCP vs CLI tradeoffs, session memory and momentum patterns, code-to-ticket linkage, and evidence trails. +- [`references/example-orchestration.md`](references/example-orchestration.md). A complete worked example showing all sections populated for a representative scenario. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md b/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md new file mode 100644 index 0000000..d1649a5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/automation-and-qa-tooling.md @@ -0,0 +1,167 @@ +# Automation and QA tooling + +The QA verification gate, MCP vs CLI tradeoffs at the strategic level, session memory and momentum patterns, code-to-ticket linkage, evidence trails, and failure routing. This file pairs with platform-implementation.md (which covers per-platform specifics) but stays at strategic-pattern level. + +--- + +## Section 1: The QA verification gate + +The single most important pattern in this reference file. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The orchestration plan specifies, per project type: + +- Which automated tests must pass. Defined in writing as part of the orchestration plan output. Different project types have different test suites. + - Web project. Playwright critical-flow tests covering signup, checkout, contact form, navigation, and any other paths that move money or capture data. Visual regression on key pages (homepage, pricing, top-traffic landing pages). Console error count not exceeding baseline (specify baseline as 0 errors at hero load and during critical flows). Accessibility floor (WCAG AA contrast, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled). Performance budgets (Lighthouse mobile and desktop scores at or above project target, Core Web Vitals at or above project target). + - Microsite or landing page. Subset of the above scoped to the page; performance budgets often tighter. + - Campaign. Cross-deliverable consistency check (do all assets reference the same brand identity? do all touchpoints use the locked voice?) plus per-deliverable QA. + - Identity refresh. Visual regression on the design library plus an audit of downstream files using deprecated components. + +- Which MCPs run them. + - Playwright MCP for browser-driven user-flow tests. The agent invokes the test suite, captures pass/fail per test, and attaches results to the ticket. + - Claude in Chrome / Chrome MCP for human-readable QA flows with screenshot or GIF evidence trails. Useful when the test isn't a deterministic pass/fail (e.g., "does the checkout flow feel right?" requires a human-readable record). Chrome MCP captures the agent's walkthrough as a GIF or screenshot sequence. + - Windows MCP for desktop applications. Covers Windows-specific testing scenarios when the project is desktop-app-shaped. + - Mobile testing MCPs (Detox-based, Appium variants) for mobile apps when applicable. + +- What gets verified in a typical web QA pass. + - Critical user-flow tests (signup, checkout, contact form submission, search if applicable). + - Visual regression on key pages (typically 5-10 pages flagged as critical). + - Console error count not exceeding baseline. + - Accessibility floor (WCAG AA contrast, keyboard navigation, screen reader landmarks). + - Performance budgets (Lighthouse, Core Web Vitals). + +- Where the evidence attaches. + - Linked to the ticket as a comment with screenshot or GIF. + - Optionally stored in a `.evidence/` folder in the repo (engineering projects) or a designated cloud bucket (S3, GCS). + +- What happens on failure. + - Status moves to Blocked (not back to In Progress). + - The blocker reason is documented in the ticket comment. + - If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. + - The human is paged via the configured channel. + - The agent does NOT keep retrying autonomously; it documents the state and waits. + +--- + +## Section 2: MCP vs CLI tradeoffs at the strategic level + +The platform-implementation reference covers per-platform specifics. This section is the strategic frame for choosing between MCP and CLI as the orchestration's primary interface. + +### MCP excels at + +- Small reads and writes (single ticket update, single comment posting, single page edit). +- Real-time data (current status of a project, current PRs awaiting review). +- API-shaped operations that map cleanly to JSON-in / JSON-out. +- Agent-friendly contracts (structured tool calls with typed responses). +- Navigation queries ("show me all open tickets in this project", "find the PR that touches this file"). +- Status reads (what's the current gate state, what's locked). + +### CLI excels at + +- Bulk content updates (large Confluence pages, multi-page Notion exports, repo-wide search-and-replace). +- File-tree-aware operations (operating on multiple files in a repo, generating a directory of artifacts). +- Git-like workflows (the gh CLI's strengths around branches, PRs, releases). +- Lower token cost on heavy operations. MCP roundtrips become expensive at scale; CLI runs locally with no token cost per operation. +- Scripted automation (CI workflows, deploy pipelines, scheduled jobs). + +### Decision pattern + +- For setup and orchestration. Prefer MCP. PM-friendly, declarative, easy to inspect. The agent can explain what it did via tool-call traces. +- For bulk operations. Prefer CLI. More efficient, lower token cost, better formatting preservation. +- For QA verification. Playwright CLI when the same test runs repeatedly (CI integration, pre-commit hooks). Playwright MCP when verification is ad-hoc and needs to interact with surrounding context (the agent reading a Linear ticket, then running specific tests against the deployed staging site). + +### Hybrid pattern + +Most production setups use both. MCP for the orchestration plan's setup operations and ongoing navigation; CLI for ongoing bulk work, CI integration, and operations the MCP can't handle efficiently. The orchestration plan specifies which interface fires when. + +--- + +## Section 3: Session memory and momentum + +The agent-starts-from-zero problem. Each new Claude Code session re-reads files, re-discovers decisions, re-learns the same gotchas. MCP gives the task list; it doesn't give working momentum. + +Patterns to bridge the gap: + +### Project state file + +Committed alongside code. Typical paths: `CLAUDE.md`, `AGENTS.md`, `.agent/state.md`. Contents: + +- Last completed task with brief outcome notes ("RAMP-123: homepage hero rewrite. Shipped in PR #456. Worth noting: the existing copy was longer than the new copy, so the design has extra whitespace below the hero now. May need design follow-up."). +- Current task in progress with current status ("RAMP-124: pricing page CTA test. In Progress. Blocking on getting the test variant ID from Mira."). +- Open decisions awaiting human input ("Should we use the new monogram on the favicon, or keep the existing letterform-as-symbol? Pending design lead review."). +- Known gotchas the agent should avoid re-discovering ("The CMS export step takes 8 minutes. Don't kick it off until you're ready to wait. The export contains stale image references; replace with current image URLs from the asset library before publishing."). +- Convention reminders specific to the project ("Branch names use uppercase ticket prefix: feat/RAMP-123-slug. PR descriptions include 'Closes RAMP-123'. Squash merge only."). + +### Per-task observation trail + +After completing each task, the agent records observations: + +- What was unexpected ("The CMS API returned a 429 on the first attempt; had to wait 60 seconds before retry succeeded."). +- What broke before it worked ("Initial regex for the slug pattern matched too broadly; tightened to require dash separators."). +- What workaround was found ("The token export script doesn't handle nested groups in Figma; flattened the groups manually before export."). +- What pattern might generalize ("All API endpoints return null when the resource doesn't exist, not 404. Worth refactoring the error handling to assume null rather than 404."). + +### Trail-as-next-task generation + +When N observations accumulate (typically 5 to 10), hand them back as the brief for the next iteration: "here are 10 observations from this week, turn them into improvements." Keeps the agent's capability pointed at code quality and process refinement, not just task completion. + +The orchestrator skill's output bakes these mechanisms into the plan: specifies which state file to use, what content goes in it, when observations get reviewed by the human (typically weekly grooming), how the observation trail informs next-cycle planning. + +--- + +## Section 4: Code-to-ticket linkage + +Standard but worth specifying so the orchestration plan can call out exactly which conventions the team uses. + +- Branch naming. `{type}/{ticket-id}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform. +- PR descriptions. Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- Commit messages. Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. +- CODEOWNERS. When set up, PR review routing happens automatically and the orchestration plan's review-by assignments align with platform-native routing. + +The orchestration plan specifies the convention per platform combination (Jira+GitHub uses RAMP-123 prefix style; Linear+GitHub uses LIN-456 or the team's chosen prefix). Without that specification, branch names drift across team members and the auto-linking breaks. + +--- + +## Section 5: Evidence trails and recording + +Some pattern, some practical advice. + +### Recording tools + +- Claude in Chrome auto-records GIFs of QA flows. Useful for evidence attached to tickets. Limitations: GIF format is large and not video-quality; for longer flows, prefer MP4 or WebP if the recording tool supports it. +- Screenshot evidence is sufficient for most ticket-level QA artifacts. Tools like Playwright auto-capture on test failure; Chrome MCP can take ad-hoc screenshots during human-readable QA. +- Loom or similar for human-narrated walkthroughs when the audience needs context (client review of the staging site, stakeholder review of a complex flow). + +### Where evidence lives + +Three options, each with tradeoffs: + +- Attached directly to the ticket as a comment. Most discoverable but bloats the ticket. Best for evidence that pairs tightly with a specific ticket. +- In a designated cloud bucket (S3, GCS) with a link in the ticket. Ticket stays clean, evidence has a stable URL. Best for projects with high evidence volume. +- In a `.evidence/` folder in the repo. Works for engineering-heavy projects but cumbersome for design or copy work. Pairs well with the project state file pattern; evidence and state co-locate. + +### Retention + +Most projects don't need permanent evidence retention beyond the ticket. Specify a retention policy in the orchestration plan: + +- 30 days for QA evidence (passing tests don't need long retention). +- 90 days for bug-related evidence (bug reproduction often resurfaces within 90 days). +- Indefinite for design final approvals (the audit trail matters for years). + +--- + +## Section 6: Failure routing + +When automated verification fails OR an agent hits something it cannot autonomously resolve, the failure follows a defined routing. + +1. Status moves to Blocked. Not back to In Progress, not to Waiting. Blocked is a first-class status that means "human action required to unblock". +2. The blocker reason is documented in the ticket comment with specifics: which test failed, which file was the locus, which assertion didn't pass, what the agent already tried. +3. If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. +4. The human is paged via the configured channel. + - Slack (preferred for in-team work, fastest response). + - Email (for cross-team or external-stakeholder blockers). + - Linear or Jira mention (for in-tool routing when the team prefers a single channel). +5. The agent does NOT continue retrying. It documents the state and waits. Retrying is the path that turns a single failure into a context-burning loop. + +This routing is itself part of the orchestration plan output: the skill specifies which channels are configured, who's on the escalation tree, and what response time is expected per blocker severity (typically: P0 blockers paged immediately; P1 paged within a working hour; P2 surfaced at next standup; P3 added to the triage queue without a page). + +The discipline of Blocked-as-first-class-status is what makes agent participation safe at scale. Without it, agents either burn context retrying or silently abandon work; with it, the agent has a clear "I'm stuck" signal that keeps the work visible to the human team. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md b/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md new file mode 100644 index 0000000..e21adb9 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/cadence-patterns.md @@ -0,0 +1,245 @@ +# Cadence patterns + +The 7 project-type cadences in working detail. Each cadence covers phase decomposition, calendar timelines, gate definitions, lock-point map, and tool-stack implementation skeleton. + +## The 5-status taxonomy + +Every cadence in this file uses the same 5-status taxonomy: + +- Todo. Work scoped, not yet started. +- In Progress. Work being actively done. +- Waiting. Work paused for normal handoff or scheduled review. Examples: a ticket waiting for the next standup, a PR waiting for its assigned reviewer, a design awaiting client review at the next scheduled session. +- Blocked. Work cannot proceed without human resolution of a specific issue. Distinct from Waiting. An agent moves a task to Blocked when it cannot autonomously resolve and documents the blocker. The agent then stops; it does not retry. +- Done. Work complete AND verified. The QA verification gate must pass before transition to Done. Self-reported "I think this works" does not transition to Done; the automated test gate (or, in non-engineering contexts, the explicit reviewer signoff) does. + +Status transitions are restricted at the gate level. The QA gate prevents transition to Done. The approval gates prevent forward progress until the gate passes. Blocked tickets generate a paging signal to the configured channel. + +--- + +## 1. New brand build (6 to 8 weeks) + +The full lifecycle. Greenfield brand or a brand whose existing assets are being replaced wholesale. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Discovery \| 1 week \| Audience, positioning, competitive landscape, references \| +\| Direction \| 1 week \| Creative direction brief (axes locked) \| +\| Identity \| 1 to 2 weeks \| Logo system, color, typography, imagery direction, motion \| +\| Production \| 2 to 3 weeks \| Voice guide, copy, design system, page builds \| +\| Launch \| 1 week \| QA, soft launch, full launch \| + +### Gates + +- End of Discovery. Brief approval. Required: client signed brief artifact (in writing or recorded review). +- End of Direction. Direction approval. Required: axis positions locked, references curated. +- End of Identity. Identity approval. Required: logo system, color tokens, typography, imagery direction documented. +- Mid-Production. Voice approval. Required: voice guide signed. +- End of Production. Copy approval and design approval. Required: per-page copy and design signed. +- Pre-Launch. QA verification. Required: Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained. +- Launch readiness. Final go/no-go. Required: deployment checklist complete, rollback plan documented. + +### Lock points + +Brief locks at end of Direction. Identity tokens lock at end of Identity. Voice locks mid-Production. Copy locks per page at end of Production. Design tokens lock with identity; design final lock at end of Production. + +### Tool-stack implementation + +- Jira: 1 Epic per phase, Stories per work item, custom fields for Phase / Locked / Approver / Gate Status. Workflow scheme with the 5-status taxonomy. +- Linear: 1 Project per phase, Cycles per week, Labels per skill (`brand-identity`, `brand-voice`, `landing-page-copy`, etc.). +- Notion: Brief database with one row, related databases for direction docs, identity specs, voice guides, copy decks. Phase dashboard views. +- Figma: Library structure: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status. +- GitHub: Branch protection on `main`. PRs from `phase/{phase-name}/` branches. + +### Example ticket titles + +- Discovery: "Audience: 5 archetypes interviewed", "Positioning: locate the brand against 3 competitors" +- Direction: "Direction: confirm tone-axis position", "Direction: rejection list signed off" +- Identity: "Identity: logo lockup variants for review", "Identity: color tokens locked" +- Production: "Voice guide: tone-shift table approved", "Copy: homepage hero v3 reviewed" +- Launch: "QA: Playwright critical flow regression green", "Launch: deploy to production" + +--- + +## 2. Rebrand (4 to 6 weeks) + +Existing brand. Audience and positioning known. Audit replaces discovery. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| What to keep, drop, refresh; positioning gaps \| +\| Direction \| 1 week \| Creative direction brief \| +\| Identity \| 1 to 2 weeks \| Refreshed logo, color, type, imagery \| +\| Production \| 1 to 2 weeks \| Updated voice guide, copy, design library, page builds \| + +### Gates + +Audit approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, launch readiness. Same gates as new brand build minus the Launch phase (rebrand often launches with the production push rather than a separate phase). + +### Lock points + +Audit findings lock at end of Audit (decisions about what to keep stay in scope; revisiting requires change request). All other lock points match new brand build. + +### Tool-stack implementation + +Same as new brand build. The Audit phase typically uses a Notion database with rows for "Existing asset / Decision (keep/drop/refresh)/Owner / Status". + +--- + +## 3. Single landing page (1 to 2 weeks) + +The brand identity and voice are locked. The work is page-specific copy, design, and engineering. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 2 to 3 days \| Page brief, success criteria \| +\| Production \| 5 to 7 days \| Copy, design, build \| +\| QA-Launch \| 1 to 2 days \| QA, deploy \| + +### Gates + +- End of Brief.* Page brief approval. Required: success metric defined. +- Mid-Production. Copy approval. Required: signed against existing voice guide. +- End of Production. Design approval and engineering review. Required: design final, build complete. +- End of QA-Launch. QA verification and launch readiness combined. Required: Playwright run green, console errors at baseline, deploy executed. + +### Lock points + +Page brief locks at end of Brief. Copy locks mid-Production. Design tokens are inherited from the brand identity (already locked). Design final locks at end of Production. + +### Tool-stack implementation + +- Jira / Linear: Single Epic for the page, 5 to 8 Stories. +- Notion: Single brief row, one direction artifact (the page brief). +- Figma: Working file referencing the brand library; one set of frames. +- GitHub: Single feature branch, PR template, branch protection on `main`. + +--- + +## 4. Campaign (2 to 4 weeks) + +Brand identity and voice locked. Multiple deliverables under one campaign theme. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 3 to 5 days \| Campaign brief, deliverable list \| +\| Production \| 1 to 2 weeks \| Per-deliverable copy, design, build \| +\| QA \| 3 to 5 days \| Cross-deliverable QA \| +\| Launch \| 1 to 2 days \| Coordinated launch \| + +### Gates + +Campaign brief approval, per-deliverable copy approval, per-deliverable design approval, cross-deliverable QA verification, launch readiness. + +### Lock points + +Campaign brief locks at end of Brief. Per-deliverable copy locks at copy approval. Per-deliverable design locks at design approval. Cross-deliverable consistency checked at QA gate (a single change request on the campaign brief triggers re-review across all deliverables). + +### Tool-stack implementation + +- Jira / Linear: 1 Epic for campaign, 1 Story per deliverable plus per-deliverable subtasks. +- Notion: Campaign brief row plus deliverable rows in a related database. +- Figma: Library file plus one frame per deliverable. +- GitHub: Multiple feature branches off a campaign branch, single PR per deliverable. + +--- + +## 5. Identity refresh (3 to 4 weeks) + +Existing brand. Voice and positioning stay. Identity gets refreshed. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| What stays, what changes \| +\| Identity \| 1 to 2 weeks \| Refreshed logo, color, type, imagery \| +\| Production \| 1 week \| Application examples (web, signage, social) \| + +### Gates + +Audit approval, identity approval, production review. Voice and copy gates skipped (voice stays locked; copy gets light updates if any). + +### Lock points + +Audit findings lock at end of Audit. Identity tokens lock at end of Identity. Application examples lock at end of Production but tokens remain canonical. + +### Tool-stack implementation + +- Figma: Refresh of existing library; new component versions; old components deprecated rather than deleted (downstream files still reference them). +- Notion: Identity spec row with relations to before/after asset databases. +- Jira / Linear: Smaller scope than rebrand; 1 Epic, 8 to 15 Stories. +- GitHub: Library updates land via versioned PR; downstream consumers update on their own cadence. + +--- + +## 6. Website refresh (4 to 8 weeks) + +Existing site. Either a partial refresh (specific sections) or a full overhaul. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| Current site assessment, gaps, priorities \| +\| Direction \| 1 week \| Refreshed brief if positioning has shifted \| +\| Production \| 2 to 4 weeks \| Voice updates, copy, design, build \| +\| QA-Launch \| 1 to 2 weeks \| Cross-page QA, soft launch, full launch \| + +### Gates + +Audit approval, direction approval (if direction phase happens; some refreshes skip), per-section copy approval, per-section design approval, QA verification, launch readiness. + +### Lock points + +Audit findings lock at end of Audit. Direction (if produced) locks at end of Direction. Per-section copy locks at copy approval per section. Design tokens lock with the design library; design final per section locks at design approval. + +### Tool-stack implementation + +- Jira / Linear: 1 Epic per phase, sub-Epics per section if the site is large. +- Notion: Brief plus per-section page in a database. +- Figma: Library refresh plus per-section design files. +- GitHub: Per-section feature branches, branch protection, CI gates per section. + +--- + +## 7. Microsite or product launch (3 to 5 weeks) + +Fixed launch date. Plan backward from the launch. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 3 to 5 days \| Launch brief, microsite scope \| +\| Production \| 2 to 3 weeks \| Copy, design, build, integrations \| +\| QA \| 3 to 5 days \| Cross-flow QA \| +\| Launch \| 2 to 3 days \| Coordinated launch sequence \| + +### Gates + +Launch brief approval, copy approval, design approval, QA verification, launch readiness. + +### Lock points + +Launch brief locks at end of Brief. Copy locks at copy approval. Design locks at design approval. The launch date is the hardest lock; if QA fails, the launch slips rather than launching with bugs. + +### Tool-stack implementation + +- Jira / Linear: 1 Epic, multiple Stories per surface (microsite, supporting pages, integrations). +- Notion: Launch brief plus dependency table (assets, integrations, third parties). +- Figma: Microsite design file referencing brand library. +- GitHub: Microsite feature branch plus per-surface sub-branches; branch protection plus pre-launch CI gate. + +--- + +## How to use this file + +Pick the cadence whose project type matches yours. Follow the phase decomposition for your team size (use the team-size-modulation reference for adjustments). Implement in your tool stack using the platform-implementation reference for per-platform setup. Configure the QA verification gate using the automation-and-qa-tooling reference. The pieces compose; this file is the cadence skeleton. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md b/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md new file mode 100644 index 0000000..c481fb5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/example-orchestration.md @@ -0,0 +1,267 @@ +# Example orchestration + +A complete worked example showing all sections of the orchestration plan populated for a representative scenario. The PM should be able to read this Monday morning and start setting up tools Tuesday. + +## Scenario + +A 4-person team is doing a rebrand for a 15-year-old hospitality brand. The existing brand has a loyal customer base and recognizable identity assets, but the visual register has aged poorly and the digital surfaces haven't been updated since 2019. + +- Team. PM (Mira), design lead (Karim), copy lead (Jess), senior engineer (Dax). +- Timeline. 6 weeks. +- Tool stack. Jira (existing, the team's main work tracker) + Figma + GitHub. Notion is not used by this team. Slack for communication. Loom for client review walkthroughs. +- AI agent participation. Claude Code participates in production phase tasks (component library updates, page builds). Claude in Chrome runs QA gates on the staging deployment. Agents have access to the Atlassian MCP and GitHub MCP. Agents move tickets between Todo, In Progress, Waiting, and Blocked but do NOT move to Done; Done requires human verification. +- Client. Hospitality brand owner is non-technical. Reviews happen via Loom-recorded walkthroughs scheduled at end of each phase. + +--- + +## 1. Project orchestration plan + +### Phased timeline + +- Week 1 (Audit). Existing brand assessment. Audience already known; the audit assesses what to keep, drop, refresh. Output: audit findings document. +- Week 2 (Direction). Refreshed creative direction brief. Tone, aesthetic, relationship, sensory positions confirmed. Output: direction artifact. +- Weeks 3-4 (Identity). Refreshed logo lockup, color tokens, typography selections, imagery direction. Output: locked identity tokens published to Figma library, identity spec document. +- Weeks 5-6 (Production). Voice guide refresh, copy update for top 8 pages, design final per page, engineering implementation, QA verification, launch. + +### Calendar boundaries + +Week 1: Mon-Fri Audit, Friday phase review with brand owner via Loom walkthrough. +Week 2: Mon-Fri Direction, Friday phase review. +Weeks 3-4: Mon-Fri Identity, mid-Week 4 voice approval gate, Friday Week 4 identity approval gate plus Loom walkthrough. +Weeks 5-6: Mon-Tue Week 5 copy approval per page, Wed-Fri Week 5 design final per page (rolling), Mon-Wed Week 6 engineering implementation (rolling), Thu Week 6 QA verification, Fri Week 6 launch. + +--- + +## 2. Per-phase gate specs + +### Audit approval gate (end of Week 1) + +- Trigger. All Audit tasks transitioned to Done. Audit findings document complete. +- Approver. Brand owner (via Loom walkthrough plus email signoff). Mira reviews internally first. +- Required to pass. Audit findings document complete (existing assets categorized as keep / drop / refresh, gaps identified). Brand owner signed off in writing. +- Blocks until passed. Direction phase work. + +### Direction approval gate (end of Week 2) + +- Trigger. Tone, aesthetic, relationship, sensory positions selected. References curated. Rejection list documented. +- Approver. Brand owner plus Karim (design lead). +- Required to pass. All four axis positions confirmed in writing. Reference brand list documented. Rejection list signed off. +- Blocks until passed. Identity phase production work. + +### Voice approval gate (mid Week 4) + +- Trigger. Refreshed voice guide drafted by Jess against locked direction. +- Approver. Brand owner plus Jess (copy lead). +- Required to pass. Voice guide complete (attributes, tone shifts, vocabulary, paired examples). At least 3 paired examples per major content type. +- Blocks until passed. Copy production for shipping pages. + +### Identity approval gate (end of Week 4) + +- Trigger. Refreshed logo, color tokens, typography, imagery direction documented and rendered. +- Approver. Brand owner plus Karim. +- Required to pass. Logo lockup variants reviewed. Selected variants documented. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented. +- Blocks until passed. Design production at scale. + +### Copy approval gate (per page, Week 5) + +- Trigger. Per-page copy drafted against locked voice guide. +- Approver. Brand owner (via Loom walkthrough for top 3 pages; email approval for the other 5) plus Jess. +- Required to pass. Copy matches voice guide. Calls-to-action consistent with success criteria. +- Blocks until passed. Design final for that page. + +### Design approval gate (per page, Week 5-6) + +- Trigger. Design final rendered against locked copy and locked identity tokens. +- Approver. Karim plus Mira. +- Required to pass. Design references locked identity tokens. Copy reflected exactly as approved. Responsive states designed. Empty/loading/error states accounted for. +- Blocks until passed. Engineering of that page. + +### QA verification gate (Thu Week 6) + +- Trigger. Engineering signaled complete; ticket transitioned to QA status. +- Approver. Automated test suite (Playwright via MCP) plus Claude in Chrome walkthrough; human review on test failure. +- Required to pass. Playwright critical-flow suite green. Console error count at 0 for hero load and during critical flows. Accessibility floor maintained (WCAG AA contrast, keyboard navigation, screen reader landmarks). Lighthouse mobile score at or above 85, desktop at or above 95. Visual regression on top 8 pages within tolerance. +- Blocks until passed. Status transition to Done. Launch readiness for the affected page. + +### Launch readiness gate (Fri Week 6) + +- Trigger. All 8 affected pages have passed QA verification. +- Approver. Mira (project owner) plus Dax (launch coordinator). +- Required to pass. Deployment checklist complete. Rollback plan documented. On-call coverage assigned for the launch window. Brand owner notified. + +--- + +## 3. Lock-point map + +- Audit findings lock at end of Week 1. Existing-asset decisions cannot be revisited without change request triggering re-review of Direction work. +- Direction locks at end of Week 2. Axis positions cannot be revisited without change request triggering re-review of Identity, Voice, and Copy work. +- Identity tokens lock at end of Week 4. Color tokens, typography selections, logo lockup committed to Figma library v2.0. Downstream design and engineering work references the locked library version. +- Voice rules lock mid Week 4. Voice guide v2.0 committed to canonical Confluence page. Downstream copy production references the locked voice guide. +- Per-page copy locks at copy approval gate (Week 5). Each page's copy locks individually as it passes its approval gate; design final for that page can begin. +- Per-page design locks at design approval gate (Week 5-6). Each page's design locks individually; engineering for that page can begin. +- Code merges to main (Week 5-6, rolling). Branch protection prevents direct pushes; PRs merge after CODEOWNERS review and CI gates pass. + +--- + +## 4. Handoff specs + +- Audit to Direction (Friday Week 1). Audit findings document URL, summary of gaps and opportunities. Filed in Jira as a Confluence page link in the Direction phase Epic description. +- Direction to Identity (Friday Week 2). Direction artifact URL, axis positions documented, reference brand list, rejection list. Filed in Jira as Confluence page links in the Identity phase Epic description. +- Direction to Voice (Friday Week 2, parallel to Direction-to-Identity). Same artifacts; Voice phase work begins in parallel with Identity. +- Identity plus Voice to Copy (Mid-Week 5). Locked identity tokens (Figma library v2.0 URL), locked voice guide (Confluence URL), per-page scope (Jira tickets). Filed in Jira as Story descriptions per page. +- Identity plus Copy to Design (Per page, Week 5). Locked copy (Confluence URL with "approved" marker), locked identity tokens (Figma library v2.0 URL). Filed in Jira as the design-phase Story description per page. +- Design to Engineering (Per page, Week 5-6). Final design (Figma frame URL), exported asset library (cloud bucket URL), responsive notes (Figma annotations), motion specifications. Filed in Jira as the engineering-phase Story description per page. +- Engineering to QA (Per page, Week 6). Verified deployed-to-staging surface, QA evidence (Playwright run results URL, accessibility audit URL), deployment checklist URL. + +### Adjacent observation routing + +The team's triage queue is a Jira project labeled "Project triage". Filed observations route there without an assignee. Mira triages every Monday and Thursday at standup. Observation content includes: what was observed, why it might matter, link to the work that was happening when noticed, suggested triage priority. The agent uses the Atlassian MCP to file observations. + +--- + +## 5. Tool-stack implementation + +### Jira + +Issue type scheme: +- Epic: one per phase (Audit, Direction, Identity, Production-Voice, Production-Copy, Production-Design, Production-Engineering, Production-QA, Launch). +- Story: one per work item within a phase. +- Task: subtasks under stories. +- Bug: for issues filed during QA. + +Custom fields: +- Phase (single-select with the 8 phase names). +- Locked (checkbox). +- Approver (user picker). +- Gate Status (single-select with the 8 standard gates). + +Workflow scheme: 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) with workflow validators preventing premature transitions to Done without QA verification. + +Confluence space: +- Brief page (rebrand brief). +- Direction page (creative direction artifact). +- Audit findings page. +- Identity spec page (logo, color, typography, imagery). +- Voice guide page. +- Copy doc per page (top 8 pages). +- Orchestration plan page (this document, committed to the project space). + +MCP setup: +- Atlassian MCP configured with OAuth credentials (admin one-time setup). +- Initial Epic creation: 8 epics, one per phase, populated by the agent on Day 1. +- Initial Story creation per phase: agent populates from the orchestration plan. + +### Figma + +Library file structure: +- "Tokens" page: color, typography, spacing, motion. +- "Components" page: identity components (logo, badges, branded UI elements). +- "Patterns" page: page-level patterns (hero variants, card patterns, footer). +- "Page templates" page: top 8 page templates for the rebrand. +- "Working files" page: per-page design working files. + +Library publish discipline: +- v1.0 published at start of Week 3 (existing identity, used as baseline). +- v2.0 published at end of Week 4 (refreshed identity, locks at identity gate). +- Per-page working files reference v2.0 starting Week 5. + +### GitHub + +Repository: existing repo for the brand's website. + +Branch protection on main: +- Require PR reviews (1 reviewer minimum). +- Require status checks (lint, type-check, build, accessibility audit, Playwright run). +- Require linear history (squash merges only). + +CODEOWNERS: +- Frontend code: Dax. +- Design tokens: Karim. +- Copy markdown: Jess. + +PR template: +- Ticket reference (Closes RAMP-XXX or Refs RAMP-XXX). +- Summary. +- Test plan. +- Screenshots/GIFs for UI changes. +- QA evidence URL. + +GitHub MCP setup: +- GitHub MCP configured with the repo's PAT. +- Initial PR template committed via MCP. +- CODEOWNERS file committed via MCP. + +--- + +## 6. Automation and QA verification + +### Playwright test suite spec + +Critical flows to test: +- Homepage hero loads and renders. +- Reservation flow (the brand's primary conversion path) end-to-end through booking confirmation. +- Contact form submission (validation, submission, success state). +- Newsletter signup. +- Top-traffic landing pages render without console errors. + +Visual regression on top 8 pages: +- Homepage, About, Reservations, Locations, Menu, Press, Contact, Loyalty. + +Accessibility audit per page using axe-core or equivalent: +- WCAG AA contrast. +- Keyboard navigation reaching all interactive elements. +- Screen reader landmarks present and labeled. + +### Chrome MCP walkthrough scenarios + +For Loom-recorded brand owner reviews and ad-hoc human-readable QA: +- Reservation flow walkthrough with screenshots at each step. +- Brand consistency walkthrough (top 8 pages, evaluating typography and color consistency). +- Mobile responsive walkthrough (the brand's audience is heavily mobile). + +### Evidence trail policy + +- QA evidence (test results, screenshots, GIFs) attached to each ticket as comments. +- 90-day retention for engineering-related evidence. +- Indefinite retention for design final approvals (committed to Confluence with the design spec page). + +### Failure routing + +- Slack channel #project-rebrand-launch is the team's coordination channel. Blockers page Mira via Slack mention. +- P0 blockers (broken reservation flow): page Dax immediately via direct Slack mention. +- P1 blockers (broken page render): surface at next standup. +- P2-P3 blockers: file as adjacent observation in the triage queue. + +--- + +## 7. Risk register + +Cadence-specific risks and mitigations. + +### Risk 1: Brand owner availability for Loom reviews + +The brand owner is busy and may delay phase reviews, slipping the timeline. Mitigation: Mira schedules Loom reviews 1 week in advance with calendar holds. Backup reviewer for direction approval gate is the head of marketing on the brand owner's team (Mira identified this person at project kickoff). + +### Risk 2: Identity refresh expectations vs reality + +The brand owner may expect a more dramatic refresh than the audit recommends, OR may reject the refresh as too dramatic. Mitigation: Karim shares 3 directional moodboards at end of Week 1 to align expectations BEFORE Direction phase locks in. The moodboards are not the final identity; they're directional samples to confirm the team and the brand owner are pointing in the same direction. + +### Risk 3: Engineering surface area + +The website has 8 pages but also a custom CMS, a reservation integration, and an email pipeline. The 6-week timeline assumes only the page surface gets touched. Mitigation: Mira confirmed at project kickoff that CMS, reservations, and email pipeline are out of scope. Documented in the brief. If the brand owner requests adding any of these mid-flight, formal change request triggers timeline review. + +### Risk 4: Agent coordination overhead + +Claude Code participates in production tasks; Claude in Chrome runs QA gates. The agents access the Atlassian and GitHub MCPs. Risk: agent action and human action collide on the same ticket; human commits something the agent had also drafted. Mitigation: agents are not assigned tickets; they take tickets from the "Available for agent" queue (a Jira label). Humans take tickets from the "Available for human" queue. Mira moves tickets between queues at standup. + +### Risk 5: QA verification baseline drift + +Console error baseline is set at start of project. If a third-party script (analytics, heatmap, customer support chat) lands during the project and adds console errors, the baseline shifts. Mitigation: console error baseline is reset weekly during standup. Any new errors that appear get triaged immediately as either an accepted change to baseline (third-party expected) or a regression that needs fixing. + +--- + +## How to use this example + +This example is the format the orchestration plan output takes. Real outputs differ in specifics (different team, different timeline, different stack, different risks) but the structure is the same. The PM reads through, sets up the tools to match, and starts running the plan Tuesday. + +The discipline that makes this work: every section is specific. Generic plans fail. "QA gate must pass" is not a plan; "Playwright critical flows pass, console errors at baseline 0, accessibility floor WCAG AA, Lighthouse mobile at or above 85, visual regression on top 8 pages within tolerance" is a plan. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md b/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md new file mode 100644 index 0000000..74ea2ff --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/gate-definitions.md @@ -0,0 +1,119 @@ +# Gate definitions + +The 8 standard gates. Each gate includes its trigger, approver, pass criteria, what's blocked until passing, what's already locked from prior gates, and the change-request protocol if the gate is failed or reopened later. + +A gate is the moment a phase transition gets approved. Gates work when their pass criteria are measurable. "Approved" is too vague; "client signed the artifact in writing or in a recorded review" is measurable. The orchestration plan specifies measurable criteria per gate. + +--- + +## 1. Brief approval gate + +Closes the Discovery phase (or Audit phase, on rebrand projects) and opens Direction. + +- Trigger. All Discovery tasks transition to Done. The brief artifact is drafted. +- Approver. Project owner (typically the client or the founder). For internal work, the senior stakeholder. +- Required to pass. The brief artifact is complete (audience, positioning, deliverables, constraints, success criteria all populated). Approver signed in writing OR a recorded review session captured agreement. The brief artifact is committed to its canonical location (Notion brief database row, Confluence page, or repo file). +- Blocks until passed. Direction phase work, identity phase work, voice phase work, copy work. +- Already locked. Nothing yet; this is the first gate. +- Change-request protocol. If the brief is reopened after this gate, the project re-enters Discovery briefly to assess what changed, then re-runs Direction starting from the updated brief. Identity, voice, copy, and design work that depends on the changed brief sections gets re-reviewed. + +--- + +## 2. Direction approval gate + +Closes Direction phase and opens Identity. + +- Trigger. Axis positions selected (tone, aesthetic, relationship, sensory). References curated. Rejection list documented. +- Approver. Project owner plus the design lead. +- Required to pass. All four axis positions confirmed in writing. Reference brands documented with one-line rationale each. Rejection list signed off (what the brief explicitly says no to). +- Blocks until passed. Identity phase production work. Voice production work. Any copy production. +- Already locked. The brief. +- Change-request protocol. If a direction axis is changed after this gate, identity work and voice work that depend on the changed axis get re-reviewed. Tone changes ripple to voice; aesthetic changes ripple to identity; relationship changes ripple to copy register; sensory changes ripple to motion and rhythm decisions. + +--- + +## 3. Identity approval gate + +Closes Identity phase. Opens production at full volume. + +- Trigger. Logo system, color tokens, typography selections, imagery direction documented and rendered. +- Approver. Project owner plus design lead. +- Required to pass. Logo lockup variants reviewed (typically 6 to 12). Selected variants documented with rationale. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented (style, palette, treatment). +- Blocks until passed. Design production at scale (component library, page designs). Engineering work that depends on design tokens. +- Already locked. Brief, direction. +- Change-request protocol. If identity tokens change after this gate, design files that reference the tokens get re-rendered. Engineering work that consumed the old tokens gets reviewed. Voice work is typically unaffected unless typography selection changes the implied tone register. + +--- + +## 4. Voice approval gate + +Closes voice production. Opens copy production at scale. + +- Trigger. Voice guide drafted. Tone-shift table populated. Vocabulary list compiled. Paired examples written. +- Approver. Project owner plus copy lead. +- Required to pass. Voice guide complete (attributes, tone shifts, vocabulary, grammar, paired examples). At least 3 paired examples per major content type (hero copy, body, microcopy). Voice signed off in writing. +- Blocks until passed. Copy production for shipping pages. +- Already locked. Brief, direction, identity (or identity in progress; voice can lock alongside identity if both phases overlap). +- Change-request protocol. If voice rules change after this gate, all copy that has been drafted against the old rules gets re-reviewed. The copy rework varies by scope: a vocabulary substitution is light; a tone-shift table change can mean rewriting from scratch. + +--- + +## 5. Copy approval gate + +Per-page or per-deliverable. Closes copy production for that page or deliverable. + +- Trigger. Copy drafted against the locked voice guide. Internal review complete. +- Approver. Project owner plus copy lead. For per-page copy, the page owner if different. +- Required to pass. Copy matches the voice guide (verifiable by running the voice-guide checklist). All sections complete. Microcopy populated. Calls-to-action consistent with the brief's success criteria. +- Blocks until passed. Design final for that page or deliverable. Engineering of the copy-dependent surface. +- Already locked. Brief, direction, identity, voice. +- Change-request protocol. Per-page copy changes after this gate trigger re-review of the design final for that page (because design length, hierarchy, and rhythm depend on copy length). Engineering work for that page may need to be revisited if the copy change affects layout. + +--- + +## 6. Design approval gate + +Per-page or per-deliverable. Closes design production for that page or deliverable. + +- Trigger. Design final rendered against locked copy and locked identity tokens. +- Approver. Design lead plus project owner. +- Required to pass. Design references the locked identity tokens (no off-token color, type, or spacing values). Copy is reflected exactly as approved (no copy edits hidden in the design). Responsive states designed. Empty states, loading states, error states accounted for. +- Blocks until passed. Engineering of the design-dependent surface. +- Already locked. Brief, direction, identity, voice, copy. +- Change-request protocol. Design changes after this gate trigger engineering re-review for the affected surface. The change-request protocol routes through the design lead to assess scope (token-level changes are light; component or layout changes are heavy). + +--- + +## 7. QA verification gate + +Per-surface. Closes engineering and verification, opens launch readiness for that surface. + +- Trigger. Ticket transitions to "QA" status (developer signaled engineering complete). +- Approver. Automated test suite, with human review on test failure or ambiguous result. +- Required to pass. Defined Playwright critical-flow test suite green. Console error count at or below baseline (specify the baseline per project; for a typical web app, 0 errors at hero load, 0 errors during critical flows). Accessibility floor maintained: WCAG AA contrast ratios on all text, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled. Performance budgets met (Lighthouse mobile score at or above project target, Core Web Vitals at or above project target). Visual regression on key pages within tolerance. +- Blocks until passed. Status transition to Done. Launch readiness for the affected surface. +- Already locked. Code merged to main, design tokens, copy, identity, voice, direction, brief. +- Change-request protocol. Failure routes the ticket to Blocked status (not back to In Progress). The blocker reason is documented in the ticket comment. If the failure surfaced something unrelated to the ticket's scope (e.g., a regression in a sibling page), an adjacent observation is filed in the project triage queue. The human is paged via the configured channel. The agent does NOT continue retrying autonomously. + +--- + +## 8. Launch readiness gate + +Closes the project (or the launch phase of a multi-phase project). + +- Trigger. All affected surfaces have passed the QA verification gate. +- Approver. Project owner plus the launch coordinator (typically the PM or the senior engineer on rotation). +- Required to pass. Deployment checklist complete (environment variables set, secrets rotated, third-party integrations live, monitoring active, alerting configured). Rollback plan documented (which command, who runs it, where logs go). Launch communications drafted (internal: who knows the launch is happening; external: any customer-facing announcement). On-call coverage assigned for the launch window. +- Blocks until passed. The actual production deploy. +- Already locked. Everything: brief, direction, identity, voice, copy, design, code, QA evidence. +- Change-request protocol. Launch readiness failure typically delays the launch rather than reopening upstream gates. If the failure is severe (a critical bug found in pre-launch QA), the affected surface returns to In Progress for fix, then re-runs through Engineering and QA verification before launch can proceed. + +--- + +## How gates compose + +Gates are not isolated. Each gate locks artifacts that downstream gates assume are stable. A QA verification failure that traces to a copy bug means the copy approval gate produced bad output, which traces back to either a voice rule that wasn't applied or a brief that wasn't reflected. The gate chain is the audit trail. + +When a gate is reopened, the change-request protocol cascades downstream. The orchestration plan specifies the protocol per gate so the team knows in advance what re-review work a change triggers. The cost of a change is visible at the moment it's requested, not discovered after the fact. + +The QA verification gate is the gate that does the most work for the team. It is the gate that prevents "Done" from being self-reported. Configure it carefully; trust it once configured. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md b/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md new file mode 100644 index 0000000..0fd39c5 --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/handoff-protocols.md @@ -0,0 +1,143 @@ +# Handoff protocols + +A handoff is the moment work transfers between phases or skills. Without explicit handoff specs, the receiving phase opens a half-dozen Slack threads to find what they need. With them, the work moves cleanly because the receiving phase knows exactly what artifacts to expect, what's locked, and what's still open. + +This file covers the 7 standard handoffs plus an 8th cross-cutting handoff: the adjacent-observation routing. + +--- + +## 1. Discovery to Brief + +The first handoff. Discovery findings transfer to brief drafting. + +- What's transferred. Audience research notes (interview summaries, persona documents, audience-side observations). Positioning notes (competitive landscape, differentiation hypotheses). Reference materials gathered during discovery (brands, articles, examples that surfaced). +- What's locked. Nothing yet. Everything is still open. +- What stays open. All of it. Discovery is input, not decision. +- Common breakdown. Discovery findings get summarized too aggressively; the brief drafter loses the nuance. Mitigation: hand off the full notes plus a synthesis, not just the synthesis. +- Artifact specification. Discovery findings live in a Notion database, a Google Doc, or a folder of markdown files. The handoff includes a link plus a one-paragraph synthesis. +- Platform support. Notion: relation property from brief row to discovery findings. Jira: linked issue. Linear: project relationship. + +--- + +## 2. Brief to Identity + +After brief approval. The identity work begins against the locked brief. + +- What's transferred. Approved brief (audience, positioning, deliverables, constraints). Direction artifact (axis positions). Reference brand list. Rejection list. +- What's locked. Brief is locked. Direction is locked. Audience and positioning cannot be revisited without change request. +- What stays open. Everything inside the identity scope: logo system, color, typography, imagery direction, motion. The identity team picks within the constraints the brief and direction set. +- Common breakdown. The identity team interprets the rejection list loosely. A "no laurel mark" rejection becomes "well, our laurel is different". Mitigation: rejection-list adherence is a gate criterion at identity approval. +- Artifact specification. Brief lives in its canonical location (Notion brief row, Confluence page, or repo file). Direction artifact is a sibling document. Both URLs go in the identity-phase Epic or Project description. +- Platform support. Jira: Epic description with links. Linear: Project description with attached docs. Notion: relation properties. + +--- + +## 3. Brief to Voice + +In parallel with Brief-to-Identity. Voice work begins against the locked brief and direction. + +- What's transferred. Approved brief. Direction artifact (specifically the tone-axis position). Reference voice samples (other brands the team likes for their voice). +- What's locked. Brief, direction. +- What stays open. Voice attributes, tone-shift rules, vocabulary choices, grammar rules, paired examples. +- Common breakdown. Voice gets started without referencing the locked tone-axis position; the writer drafts in their natural voice rather than the project's. Mitigation: voice production opens with a tone-axis check ("the brief says Provocative; here is what Provocative implies for vocabulary, sentence shape, and rejection list"). +- Artifact specification. Tone-axis position from direction artifact. Reference voice samples as a Notion subpage or a markdown file with quoted samples. +- Platform support. Same as Brief-to-Identity. + +--- + +## 4. Identity plus Voice to Copy + +After identity approval and voice approval. Copy production begins. + +- What's transferred. Identity tokens (typography selections, color tokens, spacing). Voice guide (attributes, tone shifts, vocabulary, paired examples). Page or deliverable scope (which pages, which sections, what each section needs). +- What's locked. Brief, direction, identity tokens, voice rules. +- What stays open. Per-page copy choices within the locked voice. Calls-to-action language. Section ordering decisions where the design has not yet been finalized. +- Common breakdown. Copy is drafted for length without the typography in mind, and lands in design as either too long or too short for the rendered hero. Mitigation: copy production references the typography selection from the start; the writer drafts knowing which weight and size the copy will live in. +- Artifact specification. Identity tokens published in Figma library or in a tokens markdown file. Voice guide as a Notion page or markdown file. Page scope as a Jira/Linear ticket per page. +- Platform support. Figma library is the canonical token source. Jira/Linear ticket per page or section. + +--- + +## 5. Identity plus Copy to Design + +After copy approval per page. Design final begins for that page. + +- What's transferred. Locked copy (final approved text). Identity tokens (typography, color, spacing). Voice guide (for microcopy and any error or empty states the design generates). +- What's locked. Brief, direction, identity, voice, copy for the affected page. +- What stays open. Design layout decisions, responsive breakpoint behavior, motion design, empty/loading/error states. +- Common breakdown. Design starts before copy locks. Length, rhythm, and hierarchy get designed against placeholder text; when copy lands, the design has to be reworked. Mitigation: copy locks per page before design final starts. If parallel work is needed, design produces a wireframe with placeholder copy AND a flag noting "real copy pending; layout subject to revision". +- Artifact specification. Locked copy in the canonical copy doc with an explicit "approved" marker. Identity tokens in Figma library. Page scope from copy-phase ticket. +- Platform support. Figma frame per page, linked to ticket in Jira/Linear. + +--- + +## 6. Design to Engineering + +After design approval per page. Engineering builds the page. + +- What's transferred. Final design (Figma file URL). Tokens (referenced from Figma library). Asset library (images, icons, illustrations exported and named per convention). Component specifications (any new components designed). Responsive behavior notes. Motion specifications (entry, exit, hover, loading states). +- What's locked. Brief, direction, identity, voice, copy, design final. +- What stays open. Implementation choices (state management, framework patterns, accessibility implementation, performance optimization). Component naming if new components. +- Common breakdown. Asset exports happen ad-hoc as engineering needs them, leading to inconsistent file names, missing variants, and back-and-forth Slack messages. Mitigation: design phase exports a complete asset library (using the team's naming convention) before handoff. Engineering pulls from the library, does not request new exports during build unless missing. +- Artifact specification. Figma URL, exported asset folder (cloud bucket or repo path), responsive notes as Figma annotations or a sibling markdown doc. +- Platform support. Figma URL in the engineering ticket. Asset folder URL or path in the ticket. PR template references the design ticket. + +--- + +## 7. Engineering to Launch + +After QA verification per surface. The surface goes to launch. + +- What's transferred. Verified surface (deployed to staging, tested). QA evidence (Playwright run results, accessibility audit results, performance audit results, console error counts). Deployment checklist for this surface. Rollback plan. +- What's locked. Everything: brief, direction, identity, voice, copy, design, code merged to main, QA evidence. +- What stays open. Launch coordination (which surface launches first, monitoring during launch window, on-call coverage). +- Common breakdown. Launch happens before all surfaces have passed QA verification. Result: one surface launches with bugs, recoverable with rollback if monitoring catches it. Mitigation: launch readiness gate requires ALL surfaces to have passed QA verification, not just the most-prominent surface. +- Artifact specification. QA evidence linked to ticket (screenshots, GIFs, test result logs). Deployment checklist as a runbook document. Rollback plan as a sibling runbook document. +- Platform support. GitHub PR with QA artifact attachments or evidence URL. Linear or Jira ticket with the runbook URL. + +--- + +## 8. Adjacent observation handoff (cross-cutting) + +The handoff that fires when an agent or person, while working on Task X, notices something about Task Y or Surface Z that is not the current task but is contextually adjacent. + +### Examples + +- Working on copy for the homepage hero, the writer notices the footer copy is inconsistent with the new voice. Filing the footer inconsistency as an observation, not stopping the homepage work. +- Running QA on the pricing page, an agent notices the contact form on the about page has a console error. Filing the contact form error as an observation, not pausing the pricing-page QA. +- Updating the Figma design library, the designer notices a deprecated component is still being used in the dashboard mockups. Filing a usage-cleanup observation, not modifying the dashboard mockup. +- Reviewing a PR, an engineer notices a typo in a docstring in an unrelated file. Filing a typo observation, not blocking the PR review on it. + +### Why this handoff matters + +Without it, the team has two bad options. Option one: stop the current work and address the observation, derailing focus. Option two: ignore it, lose the context, never come back to it. The adjacent-observation handoff lets the current work proceed while preserving the finding for triage. + +### Routing + +The observation gets filed in a project triage queue, NOT directly assigned to anyone. The triage queue is reviewed on a regular cadence (typically daily standup or weekly grooming). The PM or tech lead triages the observation: discard if it's not relevant, file as a normal ticket if it is, attach to an existing ticket if it's a fragment of larger work. + +### Content of the observation + +Each filed observation includes: + +- What was observed. A specific factual statement (the footer says "Get in Touch" while the new voice would say "Reach out"). +- Why it might matter. A brief rationale (voice consistency, user-facing inconsistency, latent bug). +- Where it was noticed. A link to the work that was happening when the observation surfaced (the PR, the Figma frame, the Notion page). +- Suggested triage priority. The reporter's gut call (low / medium / high). The triager makes the actual call; the suggestion is just signal. + +### Platform support + +- Jira. A separate "triage" project or a labeled queue inside the main project. Observations get filed without an assignee; the triager assigns at triage time. +- Linear. A "Triage" inbox is built into Linear and works exactly for this purpose. +- Notion. A triage database; the assignee field stays empty until triage. +- GitHub. Observations filed as issues without an assignee; CODEOWNERS may auto-route the issue to the relevant team for triage. + +The orchestration plan specifies which platform's triage queue is the canonical one for the project (typically the same platform as the main work) and the triage cadence (daily standup or weekly grooming). Without those specifics, observations either pile up untriaged or scatter across channels and get lost. + +--- + +## How handoffs compose with gates + +A gate closes a phase. A handoff opens the next phase's work against the gate's locked output. The two patterns reinforce each other: gates make sure nothing premature ships; handoffs make sure the receiving work has what it needs to start. + +A failed gate triggers a handoff backward (rework the prior phase). A failed handoff (artifact missing, scope unclear) is itself often the symptom of a gate that didn't enforce its pass criteria. When a handoff goes wrong, audit the prior gate's criteria. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md b/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md new file mode 100644 index 0000000..f62ee1b --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/platform-implementation.md @@ -0,0 +1,174 @@ +# Platform implementation + +How the orchestration plan implements in each platform. Per platform: workflow representation (how phases, gates, lock points, and handoffs map), MCP integration notes (what AI agents can do via the platform's MCP), and CLI alternatives (where the CLI is the better tool than MCP). + +For setup screenshots and additional team patterns, consult each platform's official documentation alongside this file. + +--- + +## Jira / Atlassian + +### Workflow representation + +- Phase representation. Each phase becomes an Epic. Stories or Tasks live within the Epic. Custom fields tag the Phase explicitly. +- Gate representation. Workflow status. The 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) maps to Jira's workflow statuses, with workflow validators or transitions enforcing gate rules. A custom "Gate Status" field tracks gate state separately from issue status. +- Lock-point representation. Custom field "Locked" (boolean) on the parent artifact (Epic for phase locks, Story for per-page locks). Locked issues display a visible label so reviewers know not to make untracked changes. +- Handoff representation. Issue link types ("Blocks", "Is blocked by", "Relates to"). Linked Confluence page for the artifact (brief, direction, voice guide, copy doc). +- Concrete setup snippet. Issue type scheme: Epic, Story, Task, Subtask, Bug. Custom fields: Phase (single-select with phase names), Locked (checkbox), Approver (user picker), Gate Status (single-select with the 8 standard gates). Workflow scheme: 5-status taxonomy with validators preventing premature transitions. + +### MCP integration notes + +- Availability. Official remote MCP server, launched 2025. +- References. [Atlassian's Remote MCP Server announcement](https://www.atlassian.com/blog/announcements/remote-mcp-server) and [github.com/atlassian/atlassian-mcp-server](https://github.com/atlassian/atlassian-mcp-server). +- Capabilities. Jira issue CRUD, status transitions, comment posting, JQL queries, Confluence page operations (read, write, update). Authentication via OAuth or API token. +- What the orchestrator skill can populate via MCP. Initial epic structure from the orchestration plan (one epic per phase). Initial issue tree (stories per work item). Custom field values from the orchestration plan (Phase, Approver, Gate Status). Comments documenting handoffs and gate transitions. Confluence pages for the brief, direction artifact, voice guide, and orchestration plan itself. +- Practical limits. Workflow scheme creation typically requires admin-level UI setup; MCP is better at populating against an existing scheme than at configuring the scheme from scratch. Heavy Confluence content edits lose Atlassian Document Format (ADF) details through MCP roundtrips when the content is rich (tables, callouts, complex code blocks). For simple page content, MCP roundtrips work; for heavily-formatted content, edit in the UI or use the CLI. + +### CLI alternatives and when to use them + +- Atlassian official CLI (acli) plus community alternatives (jira-cli, etc.). +- When CLI is the better choice. + - Bulk operations across many tickets (200+ issues). MCP roundtrips become token-expensive at scale; CLI is more efficient. + - Heavy Confluence content edits where ADF formatting matters. CLI tools that parse and write ADF directly preserve formatting better than MCP roundtrips. + - Scripted reporting (export issues to CSV, generate burndown reports, run JQL across multiple projects). + - CI integration (running JQL in a CI step to validate that all blockers are resolved before deploy). +- Pattern note. Some teams mirror Jira and Confluence content as local markdown files in a `.atlassian/` folder, syncing periodically via CLI. This pattern trades simplicity for power. Document it as one viable approach for engineering-heavy teams; PMs will rarely need it. + +--- + +## Linear + +### Workflow representation + +- Phase representation. Each phase becomes a Project. Cycles (Linear's time-boxed sprints) sit within the project for week-by-week granularity. +- Gate representation. Project status workflow plus issue status workflow. Linear's status workflow customizes to the 5-status taxonomy. Labels mark gate state per issue (e.g., "gate:identity-approved", "gate:qa-pending"). +- Lock-point representation. Labels (e.g., "locked:identity-tokens", "locked:voice"). Locked issues stay visible in their project but cannot be reopened without an explicit label removal. +- Handoff representation. Project relationships (predecessor / successor projects), issue dependencies, and Linear's automatic mention parsing for cross-references. +- Concrete setup snippet. Project template per project type (new brand build, rebrand, etc.) with phases pre-populated as projects, cycles configured, label taxonomy defined. Status workflow customized to include Blocked as a first-class status (Linear ships with Backlog, Todo, In Progress, Done, Cancelled by default; add Waiting and Blocked). + +### MCP integration notes + +- Availability. Official, well-supported. +- Reference. [linear.app/docs/mcp](https://linear.app/docs/mcp). +- Capabilities. Issues, projects, cycles, teams, labels, comments, attachments. Full CRUD on most entities; webhooks for event-driven workflows. +- What the orchestrator skill can populate via MCP. Project setup with cycles. Label taxonomy from the orchestration plan. Initial issue population per phase. Project description and milestones. Status workflow customization. Initial assignee and reviewer assignments per the orchestration plan's review-by routing. +- Coverage note. Linear's MCP coverage is the most complete of the 5 platforms. For teams running a Linear-based stack with AI agents, this MCP is the recommended starting point. The agent can do almost everything programmatically. + +### CLI alternatives and when to use them + +- CLI status. No widely-adopted Linear CLI. The MCP coverage is sufficient that CLI is rarely needed. +- API direct calls remain an option for scripted setup if MCP isn't available in the runtime context. +- When the API is the better choice. Bulk import scripts when migrating from another platform. Scheduled reports run from CI. Webhook handlers for event-driven external integrations. + +--- + +## Notion + +### Workflow representation + +- Phase representation. Brief database with one row per project. Related databases for direction docs, identity specs, voice guides, copy decks. Each related database has its own rows; relation properties tie everything to the canonical brief. +- Gate representation. Status property on each artifact row. Phase view filters the database by status to surface what's open vs locked. +- Lock-point representation. A "Locked" checkbox or status property on each artifact row. Filtered views surface locked vs unlocked artifacts. +- Handoff representation. Relation properties between databases. The brief row relates to the direction row, which relates to the identity spec row, which relates to the voice guide row, etc. +- Concrete setup snippet. Brief database schema: Title, Status, Phase, Locked, Approver, Owner, Notes. Related databases: Direction, Identity, Voice, Copy, Design, QA Evidence. Relation properties tie each related row back to the brief. Dashboard view per phase. + +### MCP integration notes + +- Availability. Official. +- Reference. [developers.notion.com/guides/mcp/overview](https://developers.notion.com/guides/mcp/overview). +- Capabilities. Database queries, page CRUD, property updates, block-level reads, search. +- What the orchestrator skill can populate via MCP. Brief-as-database-row schema creation (with the property set from the orchestration plan). Relation property setup between briefs and project artifacts. Initial brief content population from the orchestration plan. Dashboard view configuration where the view config supports it (with caveats; some view configurations remain UI-only). +- Practical limits. Workspace-level permissions and team membership remain UI-driven; MCP is most useful AFTER initial workspace setup. Some view types (calendar views, certain board views with custom grouping) cannot be created via MCP and must be set up in the UI. + +### CLI alternatives and when to use them + +- Community CLIs. notion-cli and similar tools exist but are less mature than the MCP. +- When the CLI is the better choice. Exporting databases for backup. Bulk content migration from another tool. Scripted database schema changes (adding properties across hundreds of rows). +- For most teams. The MCP is sufficient. CLI tools become useful only for specialized operations the MCP can't handle. + +--- + +## Figma + +### Workflow representation + +- Phase representation. Library file with frame folders per phase: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status surfaces in the Figma comments and frame metadata. +- Gate representation. Frame status (Ready for review / In review / Approved). Components versioned in the library; outdated components marked as deprecated rather than deleted (downstream files still reference them). +- Lock-point representation. Library publish state. Once a library version is published, dependent files reference that version. Token changes ship as a new library version, which downstream files explicitly opt into. +- Handoff representation. Frame URL plus exported assets. Engineering handoff uses Dev Mode for token export and component spec. +- Concrete setup snippet. Library file structure: top-level pages for "Tokens", "Components", "Patterns", "Page templates", "Working files". Within each, frame folders per phase. Frame-level review status set via Figma's standard comment-and-status workflow. Library publish discipline: identity tokens publish at the identity gate; the library version is the lock point. + +### MCP integration notes + +- Availability. Figma Dev Mode MCP exists but is dev-mode-focused (component inspection, code generation, design token export). +- Reference. Figma's [Dev Mode documentation](https://www.figma.com/dev-mode/). +- Capabilities (Dev Mode MCP). Component property reads. Design token export (color, typography, spacing). Frame inspection (layer tree, properties, constraints). Component variant queries. +- What the orchestrator skill can populate via MCP. Limited. Library structure recommendations and frame organization remain primarily manual setup. The MCP is more useful for downstream developer handoff than upstream design ops. +- Practical limits. Design library creation, frame organization, library-level permissions, and team membership are UI-driven. Treat the orchestrator skill's Figma recommendations as documentation for the design lead, not as automation targets. + +### CLI alternatives and when to use them + +- Figma API. Can be invoked via custom scripts for token export, asset download, and metadata queries. No first-party CLI for design ops. +- When the API is the better choice. Token export scripts that run in CI to update a design system repository. Asset download automation for engineering handoffs. Metadata reporting (audit how many frames are in review status across the library). +- For most cases. The design lead implements Figma orchestration manually following the skill's recommendations. Automation is layered in only when the project is large enough to warrant the engineering investment. + +--- + +## GitHub + +### Workflow representation + +- Phase representation. Issues for non-engineering tracking (when GitHub is the canonical platform; otherwise Jira/Linear lead). Branches per feature with naming convention `{type}/{ticket}-{slug}`. PRs for design and engineering review. +- Gate representation. Branch protection on `main`. PR review requirements. CODEOWNERS for review routing. GitHub Actions for CI gates (lint, test, build, deploy preview). +- Lock-point representation. Branch state. Once code is merged to main, it's locked unless a follow-up PR amends it. Tags mark release lock points. +- Handoff representation. PR description references the originating ticket. PR review by CODEOWNERS routes to the right reviewer. PR merge triggers ticket auto-transition (configured per platform combination). +- Concrete setup snippet. Branch protection: require PR reviews before merge, require status checks (CI), require linear history (rebase or squash, no merge commits). CODEOWNERS file routes PRs to the relevant team. PR template requires ticket reference, summary, test plan, screenshots/GIFs for UI changes. GitHub Actions workflow runs CI gates on every PR. + +### MCP integration notes + +- Availability. Official. +- Reference. [github.com/github/github-mcp-server](https://github.com/github/github-mcp-server). +- Capabilities. PR ops (create, comment, review, merge). Issue ops (create, comment, close, label). File content (read, write). Branch protection (read; configuration is mostly UI/API-driven). Repository search. Code search. Workflow runs (read). +- What the orchestrator skill can populate via MCP. PR template files. Issue templates. CONTRIBUTING.md and review-protocol docs. Initial issue tree from the orchestration plan when GitHub is the canonical work tracker. CODEOWNERS file. GitHub Actions workflow files committed to `.github/workflows/`. +- Practical limits. Branch protection rulesets are typically configured via GitHub UI or repository settings API (not MCP); the orchestrator skill's branch protection recommendations remain documentation rather than automation. Repository creation, team membership, and organization-level settings are UI-driven. + +### CLI alternatives and when to use them + +- gh CLI. The dominant tool for GitHub operations. Officially maintained, broadly adopted. +- When to prefer gh CLI over MCP. + - Bulk PR operations (merging 20 dependabot PRs in a single sweep). + - Scripted workflows (a deploy script that creates a release, tags, and updates a changelog). + - Repository setup automation (create a new repo, push initial commits, set up labels and branch protection). + - When token cost matters on heavy operations. The CLI is more efficient than MCP roundtrips for repetitive tasks. +- Hybrid pattern. Most production setups use both. MCP for navigation and orchestration ("show me open PRs assigned to me", "comment on PR #123 with this summary"); gh CLI for transactional and bulk operations ("create a PR from this branch with these reviewers", "merge these 10 dependabot PRs"). The two tools complement each other. + +--- + +## Cross-platform patterns + +### Code-to-ticket linkage + +The standard convention for linking PRs and commits back to tickets: + +- Branch naming. `{type}/{ticket}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform (RAMP for the team's main project in Jira, LIN for Linear, etc.). +- PR descriptions. Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- Commit messages. Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. + +### Status synchronization + +When a PR merges, the linked ticket auto-transitions. Configure via the linked platform's automation: + +- Jira automation. "When PR merged, transition issue to Done" (with QA verification gate enforced upstream so this is safe). +- Linear's auto-transition. Linear-GitHub integration auto-moves issues based on PR state. +- GitHub Actions. A workflow that runs on PR merge and posts a comment to the linked Linear/Jira issue. Useful when the platform's native integration doesn't cover the team's exact transition rules. + +### Multi-platform stacks + +Common combinations: + +- Linear + GitHub. Most common for tech teams. Linear's MCP is mature; GitHub's MCP is mature. The two integrate well via Linear's GitHub integration plus PR/branch naming conventions. +- Jira + GitHub. Most common for enterprise. Atlassian remote MCP plus GitHub MCP cover the orchestration; workflow setup is more involved than Linear because Jira's workflow flexibility means more setup decisions. +- Notion + Linear + GitHub. PM-led with engineering sub-tracking. Notion holds the brief and creative artifacts; Linear holds the engineering work; GitHub holds the code. Notion-Linear linking is via relation property pointing to the Linear issue URL; Linear-GitHub linking is via Linear's native integration. +- Notion + Figma + GitHub. Creative-led with engineering handoff. Notion holds the brief; Figma holds the design; GitHub holds the code. This combination has the lightest engineering tooling and works for design-led projects with simple production paths. + +The orchestration plan specifies the canonical platform for each work type and the linkage convention between platforms. Without that specification, work scatters across platforms and links break. diff --git a/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md b/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md new file mode 100644 index 0000000..246ba2f --- /dev/null +++ b/dist/pi/.agents/skills/integration-orchestrator/references/team-size-modulation.md @@ -0,0 +1,65 @@ +# Team-size modulation + +A 2-person team and a 12-person team need different orchestration. The framework (phases, gates, lock points, handoffs) is the same; the cadence's review density, sync ceremony, and tool-stack adjustments scale with team size. + +This file covers four scales: solo, small (2-3), medium (4-7), large (8+). For each: review density, sync cadence, handoff formality, risk profile, tool-stack adjustments, and AI agent participation pattern. + +--- + +## Solo (1 person) + +Everything is the same person playing every role. The brief author, identity designer, voice writer, copy writer, design lead, and engineer are all you. + +- Review density. Self-review only. Per-phase self-review checklists replace formal gates. The risk is that nothing actually catches mistakes; the discipline is to step away from the work between drafting and reviewing (overnight is best, an afternoon walk is the minimum). +- Sync cadence. Daily plan, weekly review against the orchestration plan. Document the daily plan and the weekly review in a project state file (CLAUDE.md, AGENTS.md, or .agent/state.md). +- Handoff formality. Inline. Self-handoffs document themselves in the project state file rather than as separate artifacts. +- Risk profile. Phases blur together. Lock points get unfrozen without ceremony. The brief that was approved last week becomes "well, I had a better idea, let me just edit it" and downstream work drifts. +- Tool-stack adjustments. Skip Jira workflow validators, Linear cycle ceremony, formal review routing. Use the simplest tool the project needs (often Notion or markdown files in a repo). Resist setting up tooling beyond what's actually used; solo projects fail more often from over-tooling than from under-tooling. +- AI agent participation pattern. Heavy. Solo work benefits most from agent participation because the agent is the second pair of eyes that solo work otherwise lacks. The agent runs QA verification gates, reviews copy against the locked voice, runs accessibility audits, and surfaces patterns the solo person might miss. The orchestration plan output specifies which agent runs at which gate. + +--- + +## Small (2-3 people) + +Single reviewer per gate. Async handoffs are fine. Daily standup is sufficient for sync. + +- Review density. One reviewer per gate. The team picks a primary reviewer per phase based on expertise (design lead reviews identity gates, copy lead reviews voice and copy gates, the senior engineer reviews QA verification and launch readiness). +- Sync cadence. Daily 15-minute standup. Weekly 60-minute phase review. Async messaging in between. +- Handoff formality. Documented but inline (a Notion page comment, a Linear issue description, a Slack message in the project channel). The small team can rely on shared context that larger teams cannot. +- Risk profile. The single reviewer becomes a bottleneck. When the design lead is the only person who can pass the identity approval gate and they're on PTO, the project blocks. Mitigation: the orchestration plan specifies a backup reviewer per gate. +- Tool-stack adjustments. Light tool setup. Linear's default workflow is fine; Jira can run with a basic workflow scheme; Notion runs with basic database schemas. Don't set up complex automations until the team feels the lack of them. +- AI agent participation pattern. Moderate. Agents handle production tasks, QA verification, and adjacent observation filing. Humans handle reviews, gate approvals, and decisions that require taste or political judgment. The orchestration plan specifies which roles agents fill and which stay human. + +--- + +## Medium (4-7 people) + +Multiple reviewers, async sync points, weekly phase reviews. The team is large enough that shared context erodes; documentation matters more. + +- Review density. Two reviewers per gate (one primary, one secondary for cross-check). Reviewer rotation across phases prevents one person from becoming the bottleneck. +- Sync cadence. Daily standup. Weekly phase review. Bi-weekly cross-track sync if there are parallel tracks. Async messaging in between with explicit channels per phase. +- Handoff formality. Documented in the canonical platform (Jira issue, Linear project, Notion database row). Slack threads are fine for discussion but the canonical record lives in the work-tracking platform. +- Risk profile. Review density becomes the gating factor. Reviewers stack up at end of phase, leading to fatigue reviews and rubber-stamped approvals. Mitigation: within-phase mini-gates that flatten review demand. Instead of reviewing 8 deliverables on phase-end Friday, review 2 mid-week and 6 at phase-end. +- Tool-stack adjustments. Custom fields, labels, and automation start to matter. Set up workflow validators that prevent premature transitions. Set up custom views per role (designer view, engineer view, PM view) so each person sees only what's relevant to them. +- AI agent participation pattern. Agents handle QA verification gates, surface adjacent observations, and run reports (which tickets are stuck, which gates are open, which assignees are overloaded). Humans handle reviews and approvals. The agent's role expands from "do production work" to "monitor the orchestration plan and surface drift". + +--- + +## Large (8+ people) + +Formal phase reviews, dedicated PM for orchestration, multiple parallel tracks. Cross-track drift is the dominant risk. + +- Review density. Three or more reviewers per gate. Phase reviews become formal meetings with prepared agendas. Reviewer rotation is mandatory; the project cannot rely on any one person. +- Sync cadence. Daily standup per track. Weekly cross-track sync. Bi-weekly project-wide review. Monthly stakeholder review for projects spanning multiple months. +- Handoff formality. Strict. Every handoff specifies artifacts, locked items, and change-request protocols in writing. Async handoffs without artifact specification break large teams; the receiving track wastes a week trying to figure out what was actually handed off. +- Risk profile. Cross-track drift. Track A and Track B both interpret the brief differently; by week 3 the two tracks read as different brands. Mitigation: a dedicated brief-owner role whose job is to maintain the brief as canonical reference, plus cross-track sync ceremonies and explicit change-request protocols. Brief drift is a leading indicator; the brief-owner role exists to catch it before it becomes track drift. +- Tool-stack adjustments. Full workflow scheme with validators. Custom fields tracking phase, gate status, approver, locked status. Multiple boards or views per track. Automation rules for status synchronization across linked platforms (Jira-GitHub, Linear-GitHub). Reporting dashboards. +- AI agent participation pattern. Agents become orchestration monitors. The agent's role is to track phase status across tracks, surface drift, run cross-track sync prep (which tracks are on schedule, which are slipping), file adjacent observations across track boundaries, and run QA verification gates. The agent is most valuable at the cross-track surface where humans cannot easily hold all the context. + +--- + +## How to choose your scale's pattern + +Match the cadence to actual team size. The most common mistake is to use a small-team cadence on a medium-team project, which leads to the single-reviewer bottleneck, OR to use a large-team cadence on a small-team project, which leads to ceremony overhead that nothing earns. + +When the team scales mid-project (a 2-person small team grows to 5 people during production phase, for example), the orchestration plan should specify the transition: at what point does the cadence shift, what new reviewers come online, what additional ceremonies start. The plan's risk register should flag scaling moments as a known risk because cadence transitions are themselves a source of drift. diff --git a/dist/pi/.agents/skills/interactive-product-tour/SKILL.md b/dist/pi/.agents/skills/interactive-product-tour/SKILL.md new file mode 100644 index 0000000..59256aa --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/SKILL.md @@ -0,0 +1,251 @@ +--- +name: interactive-product-tour +description: "Designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. Honest about tooltip-spam (visual noise that users develop blindness to), one-and-done (help invisible at the moment of need), and contextual-when-needed (surfaces help at the moment friction occurs) patterns. Triggers on product tour, in-product tooltip, contextual help, walkthrough, feature tour, hint system, in-app guidance, tour platform. Also triggers when feature adoption is low, when users miss key product capabilities, or when an in-product help system is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing in-product tours and contextual help. Distinguishes tooltip-spam (every button has a tour stop) from one-and-done (tour shows once, never seen again) from contextual-when-needed (surfaces help at the moment friction occurs)" +display_order: 8 +--- + +# Interactive Product Tour + +A senior product marketing director's playbook for designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. The discipline of building help systems that surface at moments of need and disappear when not needed. + +Most product tours fail in one of two ways. They paint every button, link, and feature with "click for tour" hints until the visual noise is so great that users develop blindness to the dots. Or they show a single first-login tour the user skips or skims, after which the same help never re-surfaces when the user actually hits a moment of friction. Help that is invisible at the moment of need is help that does not exist. + +The tours that work do something different. They trigger when the user is at a moment of friction, not all the time. They surface contextual hints when the user enters a section they have not explored, clicks into a feature requiring setup, or returns after a long absence. The system knows what the user knows and surfaces help at the right moment. + +The voice is the senior product marketing director who has watched feature adoption double when tours were redesigned and watched it collapse when more tooltips were piled onto every surface. Practical, opinionated about the trigger logic that distinguishes useful help from visual noise, willing to call out when no in-product tour at all is the right answer. + +When to use this skill: scoping an in-product help system for the first time, auditing a tour system that produces engagement metrics with no adoption lift, designing the trigger logic that decides when help surfaces, or deciding which features warrant tours vs documentation. + +--- + +## What this skill covers + +This skill spans in-product tours, tooltips, and contextual help. The growth-tooling distinctions: + +- `onboarding-wizard-design` is the sequential first-run experience. This skill is contextual help WITHIN the product, surfacing across the lifecycle. +- `chatbot-flow-design` is conversational help. This skill is non-conversational tour and tooltip help. +- `interactive-product-tour` (this skill) is trigger logic, tour architecture, contextual placement, completion tracking, and the discipline of being absent until needed. +- `discovery-research-synthesis` is research that informs tour content. Input, not part of. +- `pm-spec-writing` is the spec for engineers building the tour. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams, agencies running activation work for SaaS clients. + +Out of scope: first-run wizards (covered by `onboarding-wizard-design`); conversational help (covered by `chatbot-flow-design`); the engineering implementation; specific Userpilot/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The tour decision: when tours earn vs when documentation suffices + +Before designing the tour system, decide whether tours are the right tool. + +Tours earn investment when: + +- The product has features users genuinely miss without prompting. Specific functionality buried in menus, advanced workflows that require sequence, integrations users do not know exist. +- The audience benefits from in-context guidance more than out-of-context documentation. Tours teach in the place the user will use the feature; docs require context-switching. +- The team can maintain tours as the product evolves. Tour content decays; without maintenance commitment, tours point to deprecated UI. +- The success metric is defined. Feature adoption, time-to-value for specific capabilities, reduction in support tickets for tour-covered features. + +Tours do NOT earn investment when: + +- The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. +- The audience prefers self-directed discovery. Some audiences resent in-product guidance and prefer to explore. +- The team cannot maintain tours alongside product changes. Stale tours are worse than no tours. +- The product changes frequently. Tour maintenance can exceed tour value if the product churns rapidly. + +The decision is not "should we have a tour system"; it is "is in-product tour the right tool for this product and audience." + +Detail in [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md). + +--- + +## Tooltip-spam vs one-and-done vs contextual-when-needed + +The keystone framing. + +Tooltip-spam. Every button, link, and feature has a "click for tour" hint or pulsing dot. Visual noise. Users develop blindness to the dots; the tour system fails as a teaching surface. Cost: the design effort produces help nobody perceives; the visual clutter degrades the product overall. + +One-and-done. A single tour shown on first login. Users skip or skim. The same tour never re-surfaces when the user actually hits a moment of friction. Cost: help that is invisible at the moment of need does not help. Feature adoption stays low; support tickets persist for features the tour covered. + +Contextual-when-needed. Tours and tooltips trigger when the user is at a moment of friction (entered a section they have not explored, clicked into a feature requiring setup, returned after a long absence, hit a feature flag's first activation). The system knows what the user knows and surfaces help at the right moment. Cost: trigger logic is meaningful work; payoff is help that compounds adoption over time. + +The litmus test. Watch a user encounter a feature for the first time. Does the help system surface useful guidance at that moment, or did it surface guidance at first-login that the user has long forgotten? If the former, contextual-when-needed. If the latter, one-and-done. If the help is competing with 14 other tooltip dots scattered across the page, tooltip-spam. + +--- + +## Trigger logic: event-based vs time-based vs state-based + +The mechanism that decides when help surfaces. + +Event-based triggers. Help appears in response to a user action. Clicked a feature for the first time, entered a new section, completed a flow. + +When to use. Default for most contextual help. The user did something; help responds. + +Time-based triggers. Help appears after time elapsed. Returned to the product after 30 days of absence; been on this page for 60 seconds without acting. + +When to use. Time can signal need (long absence; stuck on a page). Use sparingly; time alone is a noisy signal. + +State-based triggers. Help appears based on user state. New user vs power user; account size; feature usage history. + +When to use. When the help differs by user segment. State-based triggers personalize help. + +Combined triggers. Most production tour systems combine all three. Event-driven, with time and state modulating frequency and content. + +The discipline. The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. + +Detail in [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md). + +--- + +## Tour architecture: single tour vs branched vs library of micro-tours + +How help is organized. + +Single tour. One linear tour covering the product. Simple; rigid; rarely fits how users actually explore. + +Branched tour. Tour adapts based on user choices or path through the product. More relevant; more complex. + +Library of micro-tours. Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. Most flexible; most maintenance. + +The choice. Most modern systems use the micro-tour library approach. Single tours feel canned; branched tours are hard to maintain at scale; a library of contextual micro-tours matches how users actually explore. + +Detail in [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md). + +--- + +## Contextual placement: where help appears, how it dismisses + +The visual design of help. + +Placement patterns. + +- Tooltip on hover. Help appears next to the element on hover. Lightweight; familiar. +- Spotlight overlay. Element highlighted, help appears alongside. More prominent; more disruptive. +- Sidebar. Help appears in a side panel. Can persist while the user works. +- Inline. Help appears in the page flow. Non-disruptive; harder to dismiss. + +Dismissal mechanics. + +- Click X. Standard close. Always available. +- Click outside. Help dismisses if the user interacts with anything else. Implies non-modal help. +- Auto-dismiss. Help fades after a few seconds. Risky; users may not have read it. +- Persistent until acted on. Help stays until the user takes the suggested action. Powerful for guided flows; intrusive otherwise. + +Non-intrusion principle. Help should be findable when wanted, ignorable when not. Modal help that blocks the screen is intrusive; help that disappears too easily fails to teach. + +Detail in [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) and [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md). + +--- + +## Completion tracking and re-trigger logic + +Knowing what each user has seen, deciding when to show again. + +Per-user state tracking. + +- Which tours has the user completed? +- Which tours has the user dismissed? +- Which tours has the user seen but not completed? +- Time since last interaction. + +Re-trigger logic. + +- Completed tours: usually do not re-show. +- Dismissed tours: respect the dismissal; possibly re-show after a long delay if the feature becomes relevant again. +- Skipped tours: re-show at moments of relevance. +- Long-absent users: re-orient with abbreviated help. + +The over-trigger trap. Showing the same tour to users who have completed it. Trust degrades; users disable tours. + +The under-trigger trap. Tours never re-surfacing when the user hits the same friction again. Help fails at the moment of need. + +Detail in [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md). + +--- + +## Power-user vs new-user differentiation + +Different users need different help. + +The principle. Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference. + +Differentiation signals. + +- Feature usage history (has the user used this feature before?). +- Tenure (how long has the user been on the product?). +- Engagement frequency (active daily vs returning monthly). +- Self-reported skill level (rare; usually inferred). + +Differentiation patterns. + +- Power users see help only on new features. +- New users see help on the features matching their stage of exploration. +- Returning users see re-orientation help if their last session was long ago. + +The over-helping trap. Helping power users with features they mastered. Trust degrades. + +The under-helping trap. Treating all users as power users. New users miss critical help. + +Detail in [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-tour-failures.md`](references/common-tour-failures.md). + +- "Tours show but feature adoption does not improve." Help may be visually present but not contextually relevant. Audit trigger logic. +- "Users disable tours globally." The system is annoying users. Audit frequency, dismissal, and over-triggering. +- "First-login tour completion is 80 percent; feature adoption is unchanged." One-and-done pattern; tour content not retained at moment of need. +- "Tooltips appear everywhere; nobody clicks them." Tooltip-spam; rebalance to contextual triggers. +- "Tour content references features we deprecated 6 months ago." Maintenance lapse. +- "Power users complain about pop-ups for things they already know." No power-user differentiation. +- "Tours work on desktop, break on mobile." Mobile UX of help system not tested. +- "Some teams ship tours; others don't bother. Inconsistent." No tour governance; some teams build, others ignore. +- "Tours triggered correctly but users do not act on the suggestion." Help content unclear or call-to-action absent. + +--- + +## The framework: 12 considerations for product tour design + +When designing or auditing an in-product tour system, walk these 12 considerations. + +1. The tour decision. Are tours the right tool, or does documentation suffice? +2. Contextual-when-needed, not tooltip-spam or one-and-done. Help surfaces at moments of friction. +3. Trigger logic sound. Event-based primary, with time and state modulation. +4. Tour architecture matches usage. Library of micro-tours preferred for most products. +5. Contextual placement non-intrusive. Help findable when wanted, ignorable when not. +6. Dismissal mechanics honest. Standard close, click-outside dismiss, no auto-dismiss before reading. +7. Completion tracking instrumented. Per-user state, per-tour status. +8. Re-trigger logic respectful. Completed tours do not re-show; dismissed tours respected. +9. Power-user vs new-user differentiation. Help calibrated to user state. +10. Mobile parity. Help works on the devices the audience uses. +11. Maintenance discipline. Tours updated alongside product changes; quarterly audit. +12. Adoption as success metric. Not just tour completion; feature adoption is the metric that matters. + +The output of the framework is a tour system that earns the user's attention by being absent until needed, surfaces help at moments of relevance, and produces feature adoption. + +--- + +## Reference files + +- [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md) - When tours earn the build vs when documentation suffices. +- [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md) - Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. +- [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md) - Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. +- [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) - Tooltip, spotlight, sidebar, inline. Placement and visual design. +- [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md) - Per-user state, re-trigger logic, the over-trigger and under-trigger traps. +- [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md) - Differentiation signals and patterns. The over-helping and under-helping traps. +- [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md) - Dismissal mechanics. The non-intrusion principle. +- [`references/tour-anti-patterns.md`](references/tour-anti-patterns.md) - The patterns that look like tours but degrade the product. +- [`references/common-tour-failures.md`](references/common-tour-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: tours earn the user's attention by being absent until needed + +The tour systems that work as compounding assets are the ones the user does not perceive as a tour system. Help surfaces at the moment of friction; disappears when the friction passes; never piles up as visual noise. The user encounters a feature for the first time, sees a brief contextual hint, takes the suggested action, and moves on. The system did its job; the user did not have to think about the system. + +That is the bar. Below the bar are tooltip-spam (visual noise that users develop blindness to) and one-and-done (help invisible at the moment of need). Above the bar are contextual-when-needed systems where trigger logic, tour architecture, contextual placement, and re-trigger respect work together to make help feel ambient rather than imposed. + +The discipline is in the design choices. The decision to build a tour system at all, or rely on documentation. The trigger logic that decides when help surfaces. The architecture that organizes micro-tours by feature and workflow. The placement and dismissal that make help non-intrusive. The completion tracking that prevents re-showing what users already know. The power-user differentiation that respects expertise. The maintenance cadence that keeps tours in sync with the product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md b/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md new file mode 100644 index 0000000..09a5d4d --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/common-tour-failures.md @@ -0,0 +1,171 @@ +# Common tour failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Tours show but feature adoption does not improve." + +The diagnosis. Help may be visually present but not contextually relevant. Tour content may be unclear or call-to-action absent. + +The cure. Audit trigger logic (`references/trigger-logic-patterns.md`). Verify tours fire at moments of friction. Audit content; ensure tours have clear CTAs. + +--- + +## "Users disable tours globally." + +The diagnosis. The system is annoying users. Audit frequency, dismissal, over-triggering. + +The cure. Frequency caps (`references/dismissal-and-non-intrusion-patterns.md`). Per-user state tracking (`references/completion-tracking-and-re-trigger.md`). Audit cumulative exposure per session. + +--- + +## "First-login tour completion is 80 percent; feature adoption is unchanged." + +The diagnosis. One-and-done pattern. Tour content not retained at moment of need. + +The cure. Move from single first-login tour to library of contextual micro-tours. Detail in `references/tour-architecture-patterns.md`. + +--- + +## "Tooltips appear everywhere; nobody clicks them." + +The diagnosis. Tooltip-spam. Visual blindness has set in. + +The cure. Audit triggers. Remove tooltips that are not earning their place. Reserve hints for moments of friction. + +--- + +## "Tour content references features we deprecated 6 months ago." + +The diagnosis. Maintenance lapse. + +The cure. Quarterly tour audit. Tag tours by feature; deprecate tours when features deprecate. + +--- + +## "Power users complain about pop-ups for things they already know." + +The diagnosis. No power-user differentiation. + +The cure. Add feature-usage gating. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tours work on desktop, break on mobile." + +The diagnosis. Mobile UX of help system not tested. + +The cure. Mobile-first design and testing. Different placement patterns for mobile. + +--- + +## "Some teams ship tours; others don't bother. Inconsistent." + +The diagnosis. No tour governance. Some teams build tours, others ignore them. + +The cure. Tour ownership. Designate who maintains the system. Tour authoring guidelines. + +--- + +## "Tours triggered correctly but users do not act on the suggestion." + +The diagnosis. Help content unclear or call-to-action absent. + +The cure. Audit tour content. Each tour should have a clear, actionable CTA matched to the user's likely intent. + +--- + +## "Tour completion looks fine; adoption is mixed by feature." + +The diagnosis. Some tours work, others do not. Per-tour adoption tracking surfaces which. + +The cure. Per-tour adoption-lift measurement. Retire or redesign tours that do not produce adoption lift. + +--- + +## "We added more tours; user complaints went up." + +The diagnosis. Cumulative frequency overload. Each tour reasonable; total exposure too much. + +The cure. Per-session frequency caps. Audit cumulative exposure. + +--- + +## "Returning users miss new features we shipped during their absence." + +The diagnosis. No re-orientation help for long-absent users. + +The cure. Returning-user re-orientation pattern. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tour analytics broke after the last release." + +The diagnosis. Instrumentation drift. + +The cure. Verify analytics after every release. Add to deployment smoke test. + +--- + +## "Tour fires but user is mid-task; they abandon." + +The diagnosis. Trigger logic does not respect ongoing tasks. + +The cure. Detect mid-task state; defer tour. Trigger at moments of natural pause. + +--- + +## "We A/B tested tour content; adoption did not move." + +The diagnosis. Content was not the issue. Could be trigger, audience, or feature design. + +The cure. Test variables that matter. Trigger logic, audience targeting, feature design itself. Sometimes the tour cannot save a bad feature. + +--- + +## "Tours are clear; adoption is good; users still file support tickets." + +The diagnosis. Tours covered the feature but not the edge cases. Documentation is needed for depth. + +The cure. Tours plus docs. Tours teach the common case; docs cover edge cases. + +--- + +## "Power users say tours feel patronizing." + +The diagnosis. Copy tone wrong; or tours fire on features power users have mastered. + +The cure. Match copy to brand voice (treat users as adults). Add power-user differentiation. + +--- + +## "Tour platform broke after last platform update." + +The diagnosis. Tour platform changes (Userpilot/Pendo/Appcues SDK updates) can break existing tours. + +The cure. Test after platform updates. Have a rollback plan. + +--- + +## The pattern across failures + +Most tour failures fall into one of three patterns. + +Pattern 1: The tour does not surface at the right moment. Tooltip-spam, one-and-done, over-trigger, under-trigger. The fix is trigger logic. + +Pattern 2: The tour does not match the audience or device. No power-user differentiation, mobile-broken, patronizing. The fix is matching to user state. + +Pattern 3: The tour decays. Stale references, broken triggers, deprecated features still tour-covered. The fix is maintenance. + +The metric pattern: tour failures often look fine on completion alone. The signal is in feature adoption, support ticket reduction, user retention. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (trigger, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md b/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md new file mode 100644 index 0000000..fd7a8d5 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md @@ -0,0 +1,203 @@ +# Completion tracking and re-trigger + +Per-user state, re-trigger logic, the over-trigger and under-trigger traps. + +Knowing what each user has seen, deciding when to show again. Done well, tours feel ambient; done poorly, tours either re-show endlessly or fail to re-surface when needed. + +--- + +## The state-aware principle + +The tour system should know what each user has seen, completed, dismissed, and ignored. Decisions about whether to show, re-show, or skip a tour should be based on this state. + +The win. A user who completed the advanced filtering tour does not see it again. A user who skipped it might see it again at a moment of more relevance. A user who dismissed all tours sees nothing. + +The fail. Users see the same tour every time they log in. Users who dismissed tours globally still get them. Users who would benefit from a re-shown tour at the right moment never see it again. + +The discipline. Track state per user per tour; use state to inform re-trigger logic. + +--- + +## Per-user state tracking + +What to track. + +Per tour, per user. + +- Has the user seen this tour? +- Did they complete it? +- Did they dismiss it without completing? +- When did they last interact with it? +- Did they take the suggested action after the tour? + +Globally per user. + +- Are tours globally enabled or disabled? +- What is their tenure on the product? +- What user state attributes apply (plan, role, segment)? + +Aggregate. + +- Tour completion rate. +- Tour dismissal rate. +- Action-taken-after-tour rate. + +The data informs both individual and system decisions. + +--- + +## Re-trigger logic + +When to re-show. + +Completed tours. + +- Default: do not re-show. The user got what they needed. +- Exception: re-show if the feature changed materially. The tour is no longer the same tour. + +Dismissed tours. + +- Respect the dismissal. +- If the feature becomes relevant again much later (60+ days, significant feature change), consider gentle re-surfacing with respect. + +Skipped tours (saw but did not complete). + +- Re-trigger at moments of more relevance. The user did not commit; help may land better contextually. +- After 2-3 skip events, treat like dismissed; respect the pattern. + +Ignored tours (saw but did not interact). + +- Treat similarly to skipped. +- Re-trigger at moments of higher friction. + +--- + +## The over-trigger trap + +Showing the same tour to users who have completed it. + +The pattern. No completion tracking; tours fire on every page load. + +The signal. Users complain about repeat tours; users disable tours globally; trust drops. + +The cost. The tour system loses credibility. Users who would have benefited from new tours dismiss them along with the over-triggered repeats. + +The cure. Track completion. Tours that have been completed do not re-fire (with rare exceptions for material feature changes). + +--- + +## The under-trigger trap + +Tours never re-surfacing when the user hits the same friction again. + +The pattern. First-login tours that show once and never come back. + +The signal. Users hit the same feature later; have forgotten the tour; ask support; the help failed at the moment of need. + +The cost. The tour system was decorative; the help did not compound adoption. + +The cure. Re-trigger logic at moments of need. Even completed tours can re-surface in abbreviated form when the user hits the relevant feature months later. + +--- + +## Re-trigger conditions + +Specific conditions that warrant re-triggering. + +Material feature change. The feature the tour covers has changed enough that the tour content is materially different. Re-show with "this feature has changed; here is what is new." + +Long absence. User returned after 60+ days; subset of tours can re-surface as re-orientation. + +Plan change. User upgraded plan; tours for previously-locked features become relevant. + +Role change. User's role changed (e.g., promoted to admin); admin-relevant tours become applicable. + +Time-based decay. Some tours benefit from periodic refreshers (rare; use carefully). + +The discipline. Each re-trigger condition should be deliberate, not default. + +--- + +## Frequency limits + +Even thoughtful re-triggers can over-fire. + +Per-tour frequency. + +- Default: never re-show after completion. +- Re-trigger conditions: maximum once per condition met. + +Per-session frequency. + +- Maximum tours per session (cumulative across all tours): often 1-3. +- Beyond that, defer additional tours to next session. + +Per-week frequency. + +- Some users encounter many features in a week; the system should not fire 20 tours. +- Cap weekly tour exposure to maintain attention. + +The discipline. Audit cumulative tour exposure per session and per week. Individual tour decisions are not enough. + +--- + +## Dismiss vs disable distinction + +Two different signals. + +Dismiss. User closed a specific tour. Tells the system "this tour is not for me right now." + +Disable. User turned off all tours via settings. Tells the system "I do not want any tours." + +Treatment. + +- Dismiss: respect for that tour; consider re-trigger at moments of higher relevance. +- Disable: respect globally; do not show any tours. + +The disable-respect failure. Some tour systems override the global disable for "important" tours. This breaks user trust. Disable should mean disable (compliance triggers excepted, with disclosure). + +--- + +## Tour analytics for completion + +Track what each tour produces. + +Per-tour metrics. + +- Trigger rate (how often does this tour fire?). +- Completion rate (of users who saw it, how many completed?). +- Dismissal rate (how many dismissed without completing?). +- Action-taken rate (how many took the suggested action after?). +- Adoption lift (do users who saw the tour adopt the feature at higher rates than those who did not?). + +The metrics inform whether the tour is earning its place. + +The adoption-lift question. If users who saw the tour adopt the feature at the same rate as users who did not, the tour is not adding value. Either redesign or retire. + +--- + +## Common completion-tracking failures + +No tracking. Tours fire repeatedly; users complain. + +Tracking exists but ignored. State stored but trigger logic does not use it; over-trigger persists. + +Stale state. User dismissed tour 6 months ago; product changed; tour does not re-show despite being newly relevant. + +Cross-device gaps. State tracked per device; user switches device and re-encounters every tour. + +Disable not respected. Global disable ignored for "important" tours; user trust collapses. + +No adoption-lift measurement. Tours track completion but not whether they produced adoption; weak tours persist. + +Re-trigger overzealous. Re-trigger conditions fire too liberally; users see tours they completed re-appear without justification. + +--- + +## Methodology-level choices that stay in the public skill + +The state-aware principle. Per-user state tracking. Re-trigger logic. The over-trigger and under-trigger traps. Re-trigger conditions. Frequency limits. Dismiss vs disable distinction. Tour analytics. Common failures. + +## Implementation choices that stay internal + +Specific tracking implementations. Specific re-trigger logic per tour. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md new file mode 100644 index 0000000..9887927 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/contextual-placement-patterns.md @@ -0,0 +1,245 @@ +# Contextual placement patterns + +Tooltip, spotlight, sidebar, inline. Placement and visual design. + +The placement decides whether help feels ambient or imposed. Done well, help is findable when wanted, ignorable when not. Done poorly, help blocks the user or disappears before they read it. + +--- + +## The non-imposition principle + +Help should be findable when wanted, ignorable when not. Help that demands the user's full attention is help that costs trust. + +The win. A tooltip appears next to a feature, visible but not blocking. The user reads if interested, dismisses or ignores if not. The interaction is brief and respectful. + +The fail. A modal overlay blocks the entire screen, demanding the user click to dismiss before continuing. The user loses momentum; resents the interruption. + +The discipline. Match placement intensity to help importance. Most help should be lightweight. + +--- + +## Pattern A: Tooltip on hover + +Help appears next to the element on hover. + +How it works. + +- User hovers over the element. +- Tooltip appears next to it. +- Tooltip dismisses when hover ends. + +Strengths. + +- Lightweight. +- Familiar pattern. +- Non-intrusive. + +Weaknesses. + +- Mouse-only by default; keyboard users may miss. +- Limited content (cannot fit much in a tooltip). +- Dismisses too easily for content the user needs to read. + +When to use. Brief hints, definitions, quick clarifications. Not for multi-step guidance. + +--- + +## Pattern B: Spotlight overlay + +Element highlighted; help appears alongside. + +How it works. + +- The relevant element is highlighted (often via dimmed surrounding area). +- A help card appears nearby explaining the element. +- User clicks "Got it" or similar to dismiss. + +Strengths. + +- More prominent; harder to miss. +- Can fit more content than tooltip. +- Good for feature-specific tours. + +Weaknesses. + +- More disruptive. +- Dimming the page can frustrate users who wanted to do something else. + +When to use. Feature-specific tours, the kind of help that warrants the user's full attention briefly. + +--- + +## Pattern C: Sidebar + +Help appears in a side panel. + +How it works. + +- Help opens in a panel (often right side of screen). +- User can read while the main content remains accessible. +- Panel persists until dismissed. + +Strengths. + +- Persistent reference; user can refer back. +- Does not block main content. +- Can fit substantial content. + +Weaknesses. + +- Takes screen space. +- May not work on mobile. + +When to use. When the help is reference material the user may want to consult while working. Multi-step guides where the user is doing the steps in the main content. + +--- + +## Pattern D: Inline + +Help appears in the page flow. + +How it works. + +- Help is embedded directly in the page content. +- Often appears as a banner, inline hint, or contextual section. +- User scrolls past or interacts with it. + +Strengths. + +- Non-disruptive. +- Always findable (does not appear and disappear). +- Works well on mobile. + +Weaknesses. + +- Can be missed entirely. +- Adds page length. + +When to use. Empty states, contextual hints that should always be visible, supplementary information that some users want. + +--- + +## Pattern E: Modal overlay + +Help blocks the screen until dismissed. + +How it works. + +- A full-screen or large modal appears. +- User must dismiss to continue. + +Strengths. + +- Highest visibility. +- Forces attention on critical messages. + +Weaknesses. + +- Most disruptive. +- Easily abused; produces annoyance. +- Should be reserved for critical messages. + +When to use. Compliance-critical messages, terms updates, data-loss warnings. Almost never for routine help. + +--- + +## Placement choice by content type + +What pattern fits what content. + +Brief hints (1 sentence): tooltip on hover. + +Feature explanations (2-3 sentences plus example): spotlight overlay. + +Multi-step guides (3-5 steps): spotlight overlay sequence or sidebar. + +Reference material (multiple paragraphs): sidebar. + +Empty states and contextual hints: inline. + +Compliance / critical messages: modal overlay. + +The match between content and placement is part of the design discipline. + +--- + +## Visual design discipline + +How help looks. + +Visual weight. + +- Tooltips: light, almost invisible until needed. +- Spotlights: medium; visible but not aggressive. +- Modals: heavy; demand attention. + +Brand consistency. + +- Help styling matches the product's design system. +- Tone matches brand voice. +- Colors should not feel "this is a tour"; they should feel like part of the product. + +Iconography. + +- Help often uses small icons (info, lightbulb) to signal "this is help." +- Icons should be consistent across help surfaces. + +--- + +## Animation discipline + +How help appears and disappears. + +Subtle animation. Fade in, slight slide. Reinforces transition without distracting. + +Aggressive animation. Bounce, attention-grabbing motion. Useful sparingly; abused, becomes annoyance. + +No animation. Instant appear/disappear. Snappy; some users prefer it. + +Prefers-reduced-motion. Respect user system preferences. No bouncing for users who configured reduced motion. + +--- + +## Mobile placement considerations + +Mobile changes everything. + +Tooltips. Hover does not exist on mobile; tooltips need touch alternative. Often replaced with tap-to-show. + +Spotlights. Spotlight overlays need to fit mobile screens. Smaller content; fewer steps. + +Sidebars. Often impossible on mobile; replaced with full-screen modals or omitted. + +Inline. Works well on mobile. Usually the safest mobile-first pattern. + +Modal overlays. Take over the screen on mobile; even more disruptive than on desktop. + +The mobile discipline. Test help on actual devices. Mobile help should be lighter and more inline-oriented. + +--- + +## Common placement failures + +Wrong pattern for content. Modal for a brief hint; tooltip for a multi-step guide. + +Visual weight wrong. Aggressive animation for routine help; invisible animation for critical messages. + +Mobile broken. Tooltips that do not work on touch; sidebars that take over the mobile screen. + +Brand-inconsistent. Help styled differently from the rest of the product; feels bolted on. + +Animation distracting. Bouncing tooltips that draw the eye constantly. + +No reduced-motion respect. Animations fire regardless of system preferences. + +Help blocks the action it is teaching. Spotlight overlays the very element the user needs to click. + +--- + +## Methodology-level choices that stay in the public skill + +The non-imposition principle. Patterns A through E. Placement choice by content type. Visual design discipline. Animation discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific placement designs for specific tours. Specific tooling. Specific brand styles. The team's mobile testing benchmarks. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md new file mode 100644 index 0000000..ea74d3c --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md @@ -0,0 +1,229 @@ +# Dismissal and non-intrusion patterns + +Dismissal mechanics. The non-intrusion principle. + +How tours close, how they respect the user's path, how they avoid becoming friction. The discipline that makes tours feel ambient rather than imposed. + +--- + +## The non-intrusion principle + +Help should be findable when wanted, ignorable when not. Tours that demand the user's full attention earn user resentment quickly. + +The win. A tooltip appears next to a feature. The user reads, dismisses, moves on. Two seconds total. The interaction was brief. + +The fail. A modal blocks the screen. The user has to read or dismiss before continuing. The interruption costs momentum and trust. + +The discipline. Match intensity to importance. Most tours should be light. + +--- + +## Dismissal patterns + +How tours close. + +Pattern A: Click X. + +How it works. A standard close button (often X or "Close") dismisses the tour. + +When to use. Default. Always available; users always know how to dismiss. + +Pattern B: Click outside. + +How it works. Tour dismisses if the user clicks anywhere outside the help element. + +When to use. For non-modal tooltips; lightweight help. + +Pattern C: Auto-dismiss. + +How it works. Tour fades after a few seconds of no interaction. + +When to use. Sparingly. Risky because users may not have read it. Best for very brief notifications. + +Pattern D: Persistent until acted on. + +How it works. Tour stays until the user takes the suggested action. + +When to use. For guided flows where the user is meant to perform the action. Discouraged for routine help (intrusive). + +Pattern E: Dismiss-and-don't-show-again. + +How it works. Dismissing offers an explicit "don't show me this again" option. + +When to use. For tours users may want to never see again (low-priority recurring tips). + +--- + +## Dismiss prominence + +How visible the dismiss is. + +Equal prominence. Dismiss and primary action have similar visual weight. + +Primary-prominent. Primary action ("Got it" or "Try it") is bold; dismiss is secondary. + +Hidden dismiss. Dismiss requires clicking outside or finding a small X. Discouraged; users feel trapped. + +The discipline. Dismiss should be findable in under 2 seconds without searching. + +--- + +## Click-outside dismissal + +When the user clicks elsewhere, what happens. + +Pattern: Dismiss fully. Tour closes; user continues with what they were doing. + +Pattern: Pause and resume. Tour pauses; if the user comes back, it resumes. Rarely the right choice; introduces unpredictability. + +Pattern: Block click. Tour stays; click outside is captured but does not pass through. Most intrusive; reserved for compliance. + +The discipline. Click-outside should usually dismiss. Users want to continue; let them. + +--- + +## Auto-dismiss design + +When help fades automatically. + +Time-based. Help disappears after N seconds. + +- 3-5 seconds: too short for anything but a single sentence. +- 8-12 seconds: reasonable for short help. +- 15+ seconds: probably too long; users have moved on. + +Action-based. Help disappears when the user takes the suggested action. + +- Useful for guided steps. +- Risk: user does something else; help disappears confusingly. + +Hover-based. Help disappears when hover ends. + +- Tooltip default. +- Brief by nature. + +The auto-dismiss risk. Users who needed the help may have been reading slowly; auto-dismiss takes the help away before they finish. + +The cure. Either give enough time, or let users explicitly dismiss. + +--- + +## Frequency caps for non-intrusion + +How many tours can fire in a session. + +Per-session caps. + +- Maximum tours per session: 1-3 typical. +- Beyond that, additional tours defer to next session. + +Per-page caps. + +- Maximum tours per page load: usually 1. +- Multiple tooltips on a page can stack; visual noise climbs. + +Per-day caps. + +- For users who use the product all day, daily caps prevent fatigue. + +The discipline. Cumulative exposure matters as much as individual tour quality. + +--- + +## Spacing and animation + +How tours appear and disappear. + +Subtle entry. Fade in; slight slide. Reinforces transition without distracting. + +Aggressive entry. Bounce, pulse, shake. Gets attention; abused, becomes annoyance. + +Subtle exit. Fade out; quick. + +The animation discipline. Subtle entries and exits. Save aggressive animation for rare attention-needed moments. + +--- + +## Spatial respect + +Where the help appears matters. + +Avoid blocking the action. Help should not cover the element it is teaching. + +Avoid blocking critical content. Help should not obscure the user's primary work area. + +Avoid covering navigation. Help that hides nav prevents the user from leaving. + +Allow scroll. If the user needs to scroll while help is visible, scroll should still work. + +--- + +## Help dismissal preserves user state + +When the user dismisses, what is preserved. + +Form data: preserved. Dismissing help should not reset form inputs. + +Page state: preserved. Dismissing help should not navigate away. + +User progress: preserved. Dismissing help should not undo work. + +The state-loss failure. Help dismissal that resets the page or loses inputs costs trust catastrophically. + +--- + +## Power-user dismissal patterns + +Power users want to dismiss faster. + +Keyboard dismissal. ESC closes help. Power users use keyboard. + +Click-anywhere-to-dismiss. Allows fast dismissal without targeting the X. + +Settings to disable globally. Allows opting out of all tours. + +The discipline. Power users should be able to dismiss in under a second. + +--- + +## New-user dismissal patterns + +New users may need more time. + +Persistent tooltips for guided flows. Help stays visible during the flow it is teaching. + +Linked help. Dismissing help leaves a way to find it again ("Need help? Check our guides"). + +Contextual reminders. Help re-surfaces if the user struggles with the same area later. + +The discipline. New users should not lose access to help permanently from a single dismissal. + +--- + +## Common dismissal failures + +Dismiss too prominent. User dismisses before reading; misses the help. + +Dismiss hidden. User cannot find the dismiss; feels trapped. + +Auto-dismiss too short. Help disappears before reading; user does not know what was there. + +Dismiss does not respect. Tour reappears after dismiss. + +Dismiss loses state. Form inputs reset; user loses work. + +No keyboard dismiss. Power users cannot dismiss quickly. + +Modal blocks until dismissed. User cannot continue without engaging. + +Help blocks the action. Spotlight covers the very element being taught. + +--- + +## Methodology-level choices that stay in the public skill + +The non-intrusion principle. Patterns A through E for dismissal. Dismiss prominence. Click-outside dismissal. Auto-dismiss design. Frequency caps. Spacing and animation. Spatial respect. State preservation on dismiss. Power-user vs new-user dismissal patterns. Common failures. + +## Implementation choices that stay internal + +Specific dismissal designs for specific tours. Specific animation timings. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md new file mode 100644 index 0000000..646a365 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md @@ -0,0 +1,204 @@ +# Power-user vs new-user patterns + +Differentiation signals and patterns. The over-helping and under-helping traps. + +Different users need different help. The discipline is to know which user is which and tailor the help system to their state. + +--- + +## The state-respect principle + +Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference and respect both. + +The win. A power user encounters a newly-shipped feature; sees a brief tour. A new user encounters a feature for the first time; sees the same tour. A power user encounters a feature they have used 50 times; sees nothing. + +The fail. Both users see the same tour every time. Power users disable tours; new users miss critical help when they need it most. + +The discipline. Tour visibility should depend on user state, not user category alone. + +--- + +## Differentiation signals + +What lets the system know which user is which. + +Feature usage history. Has the user used this feature before? + +- Most reliable signal. +- Tracks per-feature, per-user state. +- Updates in real time as the user uses the feature. + +Tenure on the product. How long has the user been a customer? + +- Approximate signal; new accounts vs old accounts. +- Useful when feature usage data is missing. + +Engagement frequency. Daily active vs returning monthly. + +- Active users tend to know the product better. +- Returning users may need re-orientation. + +Plan or role. Free vs paid; admin vs end-user; user vs viewer. + +- Different roles use different feature sets. +- Plan changes can unlock new features. + +Self-reported skill level. Rare; usually inferred. + +- Some products ask during signup. +- Useful but unreliable; people self-assess inaccurately. + +The discipline. Combine signals. Single signals are noisy. + +--- + +## Differentiation patterns + +How to surface different help. + +Pattern A: Feature-usage gating. + +How it works. Each tour has a "show only if user has not used this feature" condition. Power users with usage history skip; new users see. + +When to use. Default for feature-specific tours. Most reliable. + +Pattern B: Tenure-based filtering. + +How it works. New users (under 7 days) see all relevant tours. Established users (over 30 days) see tours only for newly-shipped features. + +When to use. When feature usage data is incomplete or unavailable. + +Pattern C: Engagement-based modulation. + +How it works. Daily active users see fewer tours; returning monthly users may see re-orientation help. + +When to use. When engagement frequency predicts product knowledge. + +Pattern D: Role-based differentiation. + +How it works. Admins see admin-specific tours; end-users see end-user tours. + +When to use. When the product has materially different surfaces for different roles. + +Pattern E: Newly-shipped feature highlighting. + +How it works. New feature ships; tour fires for ALL users (power users and new users) because everyone is new to this feature. + +When to use. Feature launches. Power users benefit from the tour just as much as new users for this case. + +--- + +## The over-helping trap + +Helping power users with features they have mastered. + +The pattern. Tours fire regardless of user state; power users see tours they do not need. + +The signal. Power user complaints; tour disable rate climbs; trust degrades. + +The cost. Power users disable tours globally; the system loses access to them for genuinely new features. + +The cure. Add feature-usage gating. Respect tenure and engagement signals. + +--- + +## The under-helping trap + +Treating all users as power users. + +The pattern. Tours fire only on first-login or never. New users miss help when they need it. + +The signal. Feature adoption stays low among new users; support tickets persist for tour-covered features. + +The cost. New users churn or stay underactivated. + +The cure. Tours fire when users encounter features for the first time, regardless of how long they have been on the product. + +--- + +## Returning-user re-orientation + +Long-absent users may need re-orientation. + +The pattern. User has not logged in for 60+ days. On return, abbreviated re-orientation help surfaces. + +Design. + +- Brief (2-3 steps max). +- Highlights what changed in the user's absence. +- Easy to dismiss for users who do not need it. + +The over-helping risk. Users returning from a 1-week absence do not need re-orientation. Set the absence threshold appropriately. + +--- + +## Newly-shipped feature handling + +When a feature ships, the help system has new content. + +The pattern. A new tour ships with the feature. Trigger fires for all users (power and new alike) because everyone encounters this feature for the first time. + +Discipline. + +- Tag the tour as "new feature." +- Fire on first encounter regardless of user tenure. +- After most users have seen it (e.g., 80 percent of monthly active users), the tour can transition to standard new-user-only logic. + +Power-user respect. Even new feature tours should be brief. Power users will read what they need; do not slow them with five-step explanations. + +--- + +## Plan or role change handling + +User state can change. + +Plan upgrade. User moves from free to paid; new features become available; relevant tours become applicable. + +Role change. User promoted to admin; admin tours become applicable. + +The discipline. Re-evaluate tour eligibility on state change. Plan upgrade triggers a "you have new features available" re-orientation. + +--- + +## Inferred vs asked differentiation + +When to ask the user vs when to infer. + +Ask sparingly. Asking adds friction; users tire of being categorized. + +Infer when possible. Behavioral signals usually outperform self-report. + +When to ask. + +- Onboarding (use case, role). +- Major plan changes that affect tour eligibility. + +When not to ask. + +- After onboarding; let behavior speak. + +--- + +## Common power-user vs new-user failures + +No differentiation. All users see all tours; over-helping power users. + +Differentiation only by tenure. New accounts vs old; misses that some new accounts have power users (came from competitor) and some old accounts have casual users. + +No re-orientation for returning users. Users who left 90 days ago re-encounter as if first-time; they remember enough to skip re-orientation; but the help fails when they hit a changed feature. + +Newly-shipped features not flagged. Tour does not surface for power users who have used adjacent features; they miss the new capability. + +Plan upgrade not triggering re-evaluation. User upgrades; new features available; tours for those features do not surface. + +Inferring poorly. Inference logic mistakes user state; help is wrong for the user. + +--- + +## Methodology-level choices that stay in the public skill + +The state-respect principle. Differentiation signals (5 signals). Patterns A through E. The over-helping and under-helping traps. Returning-user re-orientation. Newly-shipped feature handling. Plan or role change handling. Inferred vs asked differentiation. Common failures. + +## Implementation choices that stay internal + +Specific differentiation rules for specific products. Specific signals weighted by team. The team's plan and role mapping. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md new file mode 100644 index 0000000..752725d --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-anti-patterns.md @@ -0,0 +1,224 @@ +# Tour anti-patterns + +The patterns that look like tours but degrade the product. Easy to ship; the cost shows up in feature adoption, user trust, and brand reputation. + +--- + +## The tooltip-spam tour + +The pattern. Every button, link, and feature has a "click for tour" hint or pulsing dot. + +The signal. Users develop blindness to the dots; click rates collapse; tour completion rates near zero. + +The cost. The visual clutter degrades the product; users learn to ignore all tooltips, including useful ones. + +The cure. Audit triggers. Reserve hints for moments of genuine friction. Detail in `references/trigger-logic-patterns.md`. + +--- + +## The one-and-done tour + +The pattern. A single first-login tour. Never re-surfaces. + +The signal. Users skip or skim; help unavailable at moments of later need. + +The cost. Feature adoption suffers; support tickets persist for tour-covered features. + +The cure. Library of micro-tours triggered contextually. Detail in `references/tour-architecture-patterns.md`. + +--- + +## The mega-tour + +The pattern. A single tour with 25 steps covering the whole product. + +The signal. High abandonment mid-tour; high skip rate; activation does not lift. + +The cost. Tutorial-overload pattern applied to tours. Users abandon; help fails. + +The cure. Break into micro-tours, each tied to a specific feature. + +--- + +## The over-trigger tour + +The pattern. Tour fires on every page load; no completion tracking. + +The signal. Repeat exposure; user complaints; tours globally disabled. + +The cost. Tour system loses credibility. + +The cure. Per-user state tracking. Completed tours do not re-fire. + +--- + +## The under-trigger tour + +The pattern. Tour fires only on first-login. Users hit the same friction later; help does not return. + +The signal. Specific features show low adoption among long-tenured users; help failed at the moment of need. + +The cost. The tour system was decorative for everyone after their first session. + +The cure. Re-trigger logic at moments of relevance, even for tours seen long ago. + +--- + +## The dismissive-of-disable tour + +The pattern. User disabled all tours globally; system fires tours anyway because they are deemed important. + +The signal. User trust collapses; explicit complaints. + +The cost. The tour system overrode the user's clear preference; trust does not recover quickly. + +The cure. Respect the global disable. Use compliance-only triggers for legally required messages, with clear disclosure. + +--- + +## The blocks-the-action tour + +The pattern. Spotlight overlay covers the element it is teaching; user cannot click through. + +The signal. User confusion; users dismiss and abandon the action they were about to take. + +The cost. The tour failed at its job; the user did not learn the feature because the tour blocked the feature. + +The cure. Spotlight placement that highlights without blocking. The user should be able to take the action while the help is visible. + +--- + +## The auto-dismiss-too-fast tour + +The pattern. Help fades after 3 seconds. + +The signal. Users complain about help disappearing before they read it. + +The cost. The help is technically present but functionally absent. + +The cure. Either longer auto-dismiss (8-12 seconds), or let users dismiss explicitly. + +--- + +## The validation-strict tour + +The pattern. Tour requires the user to take a specific action to proceed; the user takes a different valid path. + +The signal. Tour gets stuck; user abandons. + +The cost. Forced linearity penalizes users who explore. + +The cure. Tour either accepts multiple valid paths or dismisses if the user explores elsewhere. + +--- + +## The brand-inconsistent tour + +The pattern. Tour styling looks different from the rest of the product. Generic platform styling rather than brand-aligned. + +The signal. Users perceive the tour as bolted on; brand consistency suffers. + +The cost. The product feels less polished; tours feel like a separate system. + +The cure. Custom-styled tours matching the product's design system. + +--- + +## The mobile-broken tour + +The pattern. Tour designed for desktop; breaks on mobile. + +The signal. Mobile completion rates much lower; mobile-specific complaints. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. Detail in `references/contextual-placement-patterns.md` (mobile section). + +--- + +## The unmaintained tour + +The pattern. Tour built once; product evolved; tour content references deprecated features. + +The signal. Users hit broken steps; references that no longer apply. + +The cost. Trust degrades; users ignore tours expecting them to be wrong. + +The cure. Quarterly maintenance. Product changes trigger tour updates as part of the change. + +--- + +## The orphan-tour + +The pattern. Tour exists for a feature that was deprecated 6 months ago; nobody removed it. + +The signal. Tour fires; clicks lead to 404 or to a removed UI; users confused. + +The cost. The tour points to nothing; user trust degrades. + +The cure. Tour deprecation alongside feature deprecation. + +--- + +## The fake-engagement tour + +The pattern. Tour optimizes for click-through rate by making the action button huge and the dismiss tiny. + +The signal. Click-through rate looks high; downstream feature adoption does not match. + +The cost. Surface metrics look fine; real adoption does not improve. + +The cure. Track adoption as the metric; design honestly. Click-through alone is not enough. + +--- + +## The interrupting tour + +The pattern. Tour fires while the user is mid-task; takes over the screen. + +The signal. User abandonment spikes at the interruption; users complain. + +The cost. The tour cost the user a task completion. + +The cure. Tour triggers should respect ongoing tasks. Detect mid-task state; defer. + +--- + +## The patronizing-copy tour + +The pattern. Tour copy talks down to users. "Welcome! Let me show you around. Here's how to do something simple." + +The signal. Power users dismiss; new users feel patronized. + +The cost. Tone hurts trust. + +The cure. Match copy to brand voice. Treat users as adults. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active tour, looking for these anti-patterns. + +Audit questions per tour. + +- Is the tour triggered relevantly (anti-pattern check: tooltip-spam, over-trigger, under-trigger)? +- Does the tour respect dismissal (anti-pattern check: dismissive-of-disable)? +- Does the tour block the action it teaches (anti-pattern check: blocks-the-action)? +- Is auto-dismiss timed appropriately (anti-pattern check: auto-dismiss-too-fast)? +- Does the tour match the brand's design (anti-pattern check: brand-inconsistent)? +- Does the tour work on mobile (anti-pattern check: mobile-broken)? +- Is the tour current (anti-pattern check: unmaintained, orphan)? +- Is adoption tracked (anti-pattern check: fake-engagement)? + +The retire decision. Anti-pattern tours often warrant retirement or redesign. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md new file mode 100644 index 0000000..9048eaf --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-architecture-patterns.md @@ -0,0 +1,225 @@ +# Tour architecture patterns + +Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. + +The architecture is how help is organized at the system level. Bad architecture produces canned tours that nobody finishes; good architecture matches how users actually explore. + +--- + +## The exploration-fit principle + +The architecture should match how users actually move through the product. Linear architecture fits linear products; library architecture fits exploration. + +The win. A library of focused micro-tours, each tied to a specific feature, triggered contextually as users encounter features. Each tour is small (2-4 steps); each fires only at relevant moments. Users feel helped without feeling herded. + +The fail. A single linear tour covering 25 features in sequence. Users who care about feature 17 get nothing relevant in the first 16 steps; they skip everything; help fails. + +The discipline. Match architecture to exploration patterns; do not impose linearity on non-linear products. + +--- + +## Pattern A: Single tour + +One linear tour covering the product. + +How it works. + +- Tour starts at first-login or via a "Take the tour" prompt. +- Steps cover features in a defined order. +- User completes or skips entirely. + +Strengths. + +- Simple to design and maintain. +- Predictable for users. + +Weaknesses. + +- Linear; rarely fits how users explore. +- Can become tutorial-overload if comprehensive. +- One-and-done; rarely re-shown. + +When to use. Very simple products with linear flows. Rarely the right answer for production tour systems. + +--- + +## Pattern B: Branched tour + +Tour adapts based on user choices or path. + +How it works. + +- User selects role/use case at start. +- Subsequent steps adapt based on the selection. +- Different users effectively complete different tours. + +Strengths. + +- More relevant than single tour. +- Personalized. + +Weaknesses. + +- Complex to build and maintain. +- Hard to instrument cleanly. +- Still linear in execution. + +When to use. When the audience splits into 2-3 clear segments with different exploration paths. Use sparingly. + +--- + +## Pattern C: Library of micro-tours + +Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. + +How it works. + +- Many small tours (2-4 steps each). +- Each tour is tied to a specific feature, workflow, or moment. +- Trigger logic decides when each fires. +- Users see only the tours relevant to their current exploration. + +Strengths. + +- Matches how users actually explore. +- Each micro-tour is small enough to complete. +- Re-trigger logic can re-surface as features become relevant. +- Most flexible. + +Weaknesses. + +- Most maintenance. +- Trigger logic complexity. +- Requires per-tour completion tracking. + +When to use. Default for production tour systems. Most modern products benefit from this approach. + +--- + +## Pattern D: Hybrid + +Combining patterns. Often a brief opening tour plus a library of micro-tours for ongoing help. + +How it works. + +- First-login: brief 3-4 step orientation tour (single). +- Ongoing: library of micro-tours triggered contextually. + +Strengths. + +- Orientation for new users + ongoing help for everyone. +- Combines the simplicity of single tour for the moment of arrival with the flexibility of library for the ongoing relationship. + +Weaknesses. + +- Two systems to maintain. + +When to use. When new users genuinely benefit from an opening orientation AND ongoing contextual help is also valuable. + +--- + +## Architecture choice criteria + +Which pattern fits which product. + +Use single tour when: + +- Product is genuinely linear. +- Audience expects guided sequence. +- Maintenance capacity is limited. + +Use branched tour when: + +- Audience splits into 2-3 distinct segments. +- Each segment has a different linear path. + +Use library of micro-tours when: + +- Product has many features users explore non-linearly. +- Audience is segmented in many ways. +- Maintenance capacity supports many tours. + +Use hybrid when: + +- New-user orientation matters AND ongoing help also matters. + +The simplest architecture that fits the product is usually the best choice. + +--- + +## Micro-tour discipline + +Each micro-tour should be small. + +Size guideline. 2-4 steps per micro-tour. + +Why small. + +- Completable in under a minute. +- Easy to maintain. +- Targeted to a specific feature or moment. +- Less likely to be skipped. + +Anti-pattern. Micro-tours that grow into 8-10 steps lose their micro nature; they become single tours that happen to be triggered contextually. Re-scope. + +--- + +## Tour tagging and organization + +When you have a library, organize it. + +Tagging axes. + +- Feature (which feature the tour covers). +- Workflow (which user workflow the tour fits in). +- User type (new, power, returning). +- Plan (free, paid, enterprise). + +Why tagging matters. + +- Trigger logic can use tags to decide which tour fires. +- Maintenance can find tours by feature when the feature changes. +- Audit can identify orphan tours not tied to current features. + +--- + +## Tour deprecation + +When features change, tours need to retire or update. + +Retire when: + +- Feature was deprecated; tour points to nothing. +- Feature changed enough that tour content is wrong; redesign instead of patch. + +Update when: + +- Feature changed in details but tour structure still applies. + +The deprecation hygiene. Quarterly audit of tours against current product. Tours pointing to deprecated features get retired; tours that still apply but need refresh get updated. + +--- + +## Common architecture failures + +Single tour for non-linear product. Users skip; help fails. + +Branched tour with too many branches. Maintenance burden; quality degrades per branch. + +Library without tagging. Tours accumulate; nobody can find them; some are stale. + +Mega-tours. Micro-tours that grew to 10+ steps; lose their micro nature. + +Orphan tours. Tours pointing to features that no longer exist; not retired. + +Inconsistent micro-tour quality. Some tours polished, others slapdash; users notice. + +--- + +## Methodology-level choices that stay in the public skill + +The exploration-fit principle. Patterns A through D. Architecture choice criteria. Micro-tour discipline. Tour tagging and organization. Tour deprecation. Common failures. + +## Implementation choices that stay internal + +Specific architectures for specific products. Specific tooling for tour authoring and management. The team's tagging conventions. Specific quarterly audit calendars. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md b/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md new file mode 100644 index 0000000..5bdf154 --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/tour-decision-criteria.md @@ -0,0 +1,154 @@ +# Tour decision criteria + +When tours earn the build vs when documentation suffices. + +A tour system is meaningful work. Trigger logic, tour architecture, contextual placement, completion tracking, ongoing maintenance. Tours earn this investment only when specific conditions are present. + +--- + +## When tours earn the build + +Five conditions that, when present, make tours a strong investment. + +The product has features users genuinely miss. Specific functionality buried in menus, advanced workflows requiring sequence, integrations users do not know exist. Without prompting, users do not find these features. + +The audience benefits from in-context guidance more than documentation. Tours teach in the place the user will use the feature; docs require context-switching. Some audiences prefer the immediacy of in-context help. + +The team can maintain tours. Tour content decays as the product evolves. Without maintenance commitment, tours point to deprecated UI; users hit broken steps. + +The success metric is defined. Feature adoption per tour-covered feature, time-to-value for specific capabilities, reduction in support tickets. Without the metric, evaluation is impossible. + +The product changes at a sustainable pace. Tours can keep up. Products that change weekly may have tour-maintenance burden exceeding tour value. + +When all five are present, tours are a strong investment. When two or fewer are present, documentation often serves better. + +--- + +## When tours do NOT earn the build + +Funnels where tours add complexity without value. + +The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. Building a full tour infrastructure is overkill. + +The audience prefers self-directed discovery. Some audiences resent in-product guidance. Developer tools, professional creative tools, specialist software often have audiences who want to explore on their own. + +The team cannot maintain tours. Stale tours are worse than no tours. Without commitment, tours decay into liability. + +The product changes too frequently. A product churning weekly may have tours that go stale within days of being shipped. The maintenance cost exceeds the tour benefit. + +The audience is small enough that direct outreach is more efficient. Onboarding calls, customer success engagement, and direct help may serve a small audience better than tour infrastructure. + +The honest assessment matters. Tours are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Documentation vs tours: the comparison + +Both teach features; they differ in delivery. + +Documentation strengths. + +- Stable; changes don't require tour updates. +- Searchable; users find what they need. +- Comprehensive; can cover edge cases. +- Accessible from outside the product (sharing, linking). + +Documentation weaknesses. + +- Requires context-switching from product to docs. +- Users may not know to consult docs. +- Static; cannot react to user state. + +Tour strengths. + +- In-context; help where the user will use the feature. +- Dynamic; can react to user state and behavior. +- Non-disruptive when designed well. + +Tour weaknesses. + +- Maintenance burden. +- Can become tooltip-spam if undisciplined. +- Less comprehensive than docs. + +The combined approach. Most production teams use both. Tours for the moments where in-context guidance matters; docs for depth and reference. + +--- + +## The opportunity-cost frame + +Tour systems are significant work. + +The build cost. Trigger logic infrastructure, tour authoring, instrumentation, integration with the product, design and copy. A meaningful tour system often takes 60-200 engineering hours plus design and copy per major tour. + +The maintenance cost. Quarterly review minimum; product changes trigger tour updates. 4-12 hours per active tour per quarter. + +The opportunity cost. What else could the team have built? Direct in-product improvements, better empty states, contextual prompts that do not require tour infrastructure. The tour system has to clear the bar of those alternatives. + +The decision frame. Tours earn investment when they produce more adoption lift than the alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering an in-product tour system. + +Conditions check. + +- Features users miss: yes. Advanced analysis modes, custom dashboard creation, integration setup all underused. +- In-context guidance benefits: yes. Users explore in-product; pulling them to docs breaks flow. +- Maintenance commitment: yes. Customer success team owns tours. +- Success metric defined: yes. Feature adoption per tour-covered feature within 30 days of first encounter. +- Product change pace: moderate. Major features ship monthly; minor changes weekly. Tour updates fit the cadence. + +Decision. Build the tour system. The conditions warrant it. + +Architecture. Library of micro-tours, each tied to a specific feature. Triggered contextually when users first encounter the feature. + +Maintenance commitment. CS team reviews quarterly; major product changes trigger tour updates as part of the change. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A developer-tool company considering in-product tours. + +Conditions check. + +- Features users miss: somewhat. Some advanced features underused, but the audience tends to find them through docs. +- In-context guidance benefits: weak. Developers strongly prefer docs and prefer not to be interrupted. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined. +- Product change pace: moderate. + +Decision. Do not build a full tour system. Invest in better docs, smarter empty states, and a few high-value contextual hints. The audience's preference for self-directed discovery argues against tour infrastructure. + +The decision was right-sized to the audience. + +--- + +## When to retire a tour system + +Tour systems can become wrong over time. + +Retire when: + +- Feature adoption (the tour's success metric) has declined consistently and refinements have not moved it. +- Users globally disable tours via settings. +- The product changes have outpaced maintenance; tours are stale. +- A redesigned product surface (better empty states, better contextual prompts) makes tours redundant. +- The team can no longer maintain tours. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant tours. The five conditions that argue against. Documentation vs tours comparison. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tour decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md b/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md new file mode 100644 index 0000000..aa489aa --- /dev/null +++ b/dist/pi/.agents/skills/interactive-product-tour/references/trigger-logic-patterns.md @@ -0,0 +1,226 @@ +# Trigger logic patterns + +Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. + +The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. Useful triggers surface help at moments of friction. + +--- + +## The relevance principle + +Trigger help when the user is at a moment of friction or genuine need. Do not trigger help when the user is moving through familiar territory. + +The win. A user clicks into a feature for the first time. The tour system recognizes this is the user's first encounter and surfaces a brief contextual hint. The user reads, takes the suggested action, moves on. + +The fail. Same user, same feature. The tour system has no first-encounter detection; it triggers on every page load. The user has dismissed the same tooltip 12 times; develops blindness to all tooltips. + +The discipline. Each trigger should answer "why this user, why now." + +--- + +## Pattern A: Event-based triggers + +Help appears in response to a user action. + +How it works. + +- The user performs an action (clicks a feature, enters a section, completes a flow). +- The trigger fires based on the event. +- Help appears contextually. + +Examples. + +- First click into a new section. +- Completed a flow for the first time. +- Hit a state where help would be useful (empty list, no data connected, no teammates invited). + +Strengths. + +- Most relevant; help responds to what the user just did. +- Naturally contextual. + +Weaknesses. + +- Requires per-event tracking. +- Can over-trigger if events are too granular. + +When to use. Default for most contextual help. Events drive the trigger. + +--- + +## Pattern B: Time-based triggers + +Help appears after time elapsed. + +How it works. + +- A timer starts when relevant condition is met. +- After a defined interval, help triggers. +- Time can be session time, time on page, time since last action, or time since last login. + +Examples. + +- User has been on a page for 60 seconds without acting (signals stuck). +- User returned after 30 days of absence (signals re-orientation needed). +- User has been a customer for 90 days (signals capacity for advanced features). + +Strengths. + +- Catches stuck users events alone might miss. +- Useful for re-engagement of long-absent users. + +Weaknesses. + +- Time alone is a noisy signal. +- "Stuck" might just be reading. +- Easy to misuse and produce annoyance. + +When to use. Sparingly. Time-based triggers should always combine with event or state signals. + +--- + +## Pattern C: State-based triggers + +Help appears based on user state. + +How it works. + +- The user has attributes (new vs power; small vs large account; specific role; specific plan). +- Trigger fires based on attribute match. + +Examples. + +- Power users see help only on newly-shipped features. +- Enterprise customers see different tour on workspace features than SMB. +- Users on free plan see different upgrade-related help than paid. + +Strengths. + +- Personalizes help to user segment. +- Avoids over-helping users who do not need it. + +Weaknesses. + +- Requires user-state infrastructure. +- State changes (plan upgrade, role change) need to update triggers. + +When to use. When help differs significantly by user segment. State modulates event triggers. + +--- + +## Pattern D: Combined triggers + +Most production tour systems combine event, time, and state. + +Example combined trigger. + +"Show tour for advanced filtering feature when: +- User clicks the filter icon for the first time (event). +- User has been on the platform more than 7 days (state, not too new). +- User is on a paid plan (state, feature is paid-only). +- User has not dismissed this specific tour before (state, respect prior dismissal)." + +The combination produces relevant triggers without false positives. + +The discipline. Trigger conditions accumulate. Each condition prevents over-triggering. + +--- + +## Trigger frequency limits + +Even relevant triggers can over-fire. + +Per-tour limits. + +- Once per user (most tours). +- Once per quarter (re-orientation tours). +- Once per session per page (low-priority hints). + +Per-session limits. + +- Cap total tour interruptions per session (e.g., max 2 tours per session). +- Cap total tooltip appearances per session. + +The cumulative-frequency problem. Each individual tour may be reasonable; the cumulative count across many tours can become noise. + +The discipline. Audit cumulative triggers per session, not just per tour. + +--- + +## Trigger disabling and respect + +Users may disable tours globally. + +The pattern. A settings option lets users disable all tours. + +The discipline. Respect the disable. No tour should override the global setting (compliance triggers may be exception). + +Re-engaging disabled users. + +- Do not auto-re-enable. +- Surface specific high-value features as one-time prompts that respect the disable. +- Trust that users who disabled know what they want. + +--- + +## Trigger logic and accessibility + +Triggers must work for users with assistive technology. + +Considerations. + +- Triggers should not assume mouse hover (keyboard users miss them). +- Triggers should not auto-fire to overwhelm screen readers. +- Triggers should respect prefers-reduced-motion. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Trigger logic testing + +Test triggers across user paths. + +Test cases. + +- New user encounters feature: trigger fires. +- Returning user encounters same feature: trigger does not re-fire (respects history). +- Power user encounters newly-shipped feature: trigger fires. +- User who dismissed a tour: dismissed tour does not re-fire. +- User who disabled tours globally: no tours fire. +- User on mobile vs desktop: triggers behave consistently. + +Production monitoring. + +- Track trigger fire rate per tour. +- Track tour completion rate per tour. +- Track unique users who saw each tour. +- Anomalies (sudden spike in triggers) often indicate logic issues. + +--- + +## Common trigger logic failures + +Over-triggering. Triggers fire on every page load; users develop blindness. + +Under-triggering. Triggers fire only on first-login; users miss help when they need it later. + +No state awareness. Power users see beginner tours; new users see tours for features they have not unlocked. + +No frequency limits. Each individual tour is fine; cumulative triggers per session are noise. + +Disabled users not respected. Tours fire despite global disable. + +Stale triggers. Triggers reference features deprecated 6 months ago. + +Untested edge cases. Specific user paths produce broken triggers; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through D (event, time, state, combined). Trigger frequency limits. Trigger disabling and respect. Accessibility considerations. Trigger testing. Common failures. + +## Implementation choices that stay internal + +Specific trigger configurations for specific tours. Specific tooling for trigger management. The team's testing protocols. Specific frequency baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/internationalization/SKILL.md b/dist/pi/.agents/skills/internationalization/SKILL.md new file mode 100644 index 0000000..01f91ab --- /dev/null +++ b/dist/pi/.agents/skills/internationalization/SKILL.md @@ -0,0 +1,278 @@ +--- +name: internationalization +description: "Plan and run a multi-language or multi-region site. Use this skill when adding new locales, choosing URL structure for languages (subfolders vs subdomains vs ccTLDs), implementing hreflang, planning translation workflow, handling currency and date formats, designing for RTL languages, or auditing a stalled internationalization rollout. Triggers on internationalization, i18n, localization, l10n, hreflang, multi-language, translation workflow, RTL, locale, ccTLD, subfolder vs subdomain, language switcher. Also triggers when international audiences underperform or translations are stale." +category: cross-cutting +catalog_summary: "Locale strategy, hreflang, translation workflow, RTL design" +display_order: 3 +--- + +# Internationalization + +Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic. + +--- + +## When to use + +- Adding the first non-English (or non-default) language +- Adding additional locales to an existing internationalized site +- Choosing URL structure for languages +- Implementing hreflang tags +- Designing translation workflow +- Handling currency, date, time, and number formats +- Designing or fixing layout for RTL languages +- Auditing an internationalization rollout that's underperforming + +## When NOT to use + +- Single-language site (use other skills) +- Domain strategy that's not language-driven (use `domain-strategy`) +- Content strategy independent of locale (use `content-strategy`) +- Marketing copy production (use `content-and-copy`) + +--- + +## Required inputs + +- The locales in scope (language + region, e.g., `en-US`, `de-DE`, `fr-CA`) +- Business reason per locale (priority, audience size) +- Existing site architecture +- Translation resources (in-house, agency, AI-assisted, community) +- Content volume and update frequency + +--- + +## The framework: 5 layers + +Internationalization touches everything. Five layers, each with their own decisions. + +### Layer 1: URL structure + +How locales are reflected in URLs. + +\| Pattern \| Example \| When \| +\|---\|---\|---\| +\| ccTLD \| example.de, example.fr \| Strong country focus, distinct legal entities, willing to maintain separate domains \| +\| Subdomain \| de.example.com, fr.example.com \| Logical separation, willing to host separately, common for large sites \| +\| Subfolder \| example.com/de/, example.com/fr/ \| SEO equity unified, simplest to manage, default for most \| +\| URL parameter \| example.com?lang=de \| Avoid; weak SEO signal \| + +For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand). + +Within the chosen pattern, decide: +- Language only (`/de/`) or language plus region (`/de-de/`, `/de-at/`, `/de-ch/`)? +- Default locale: at the apex (`example.com`) or in a folder (`example.com/en/`)? + +The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an `x-default` and the canonical for the default language). + +### Layer 2: Content structure + +How content is organized across locales. + +Pattern A: Mirror. Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content. + +Pattern B: Subset. Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences. + +Pattern C: Local. Each locale has its own content largely independent of other locales. Common for media or community sites. + +Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial. + +The pattern affects: +- How content models are designed (does each piece have parent/translation relationships?) +- How translation is managed (workflow assumes the structure) +- How the team coordinates + +### Layer 3: hreflang and canonicals + +Telling search engines what's translated vs distinct. + +hreflang specifies the language and optional region for each version. + +```html +<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page"> +<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page"> +<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page"> +<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page"> +``` + +Rules: +- Every page lists every translated equivalent (including itself) +- Pages must reciprocate (page A says page B is its German version; page B says page A is its English version) +- `x-default` is the fallback for users in unspecified regions +- Each page has its own canonical pointing to itself (not to the default language) + +hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small. + +Canonicals: +- Self-referential per page +- Don't canonical the German page to the English page (search engines won't index the German page) + +### Layer 4: Translation workflow + +How content gets translated, kept fresh, and quality-controlled. + +Sources of translation: +- In-house translators (full-time staff) +- Translation agency (paid per word, professional) +- Community contributors (volunteer, variable quality, free) +- AI-assisted plus human review (cheap, fast, growing in quality) +- AI only (acceptable for some content, not for brand-critical) + +Workflow stages: + +1. Source content authored in the source language +2. Translation requested through a TMS (translation management system) or spreadsheet +3. Translation produced with translation memory (avoids retranslating reused phrases) +4. Review by a second translator or in-region staff +5. Localization beyond translation (currency, units, examples, cultural references) +6. Publishing in the destination locale +7. Update propagation when source content changes + +The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine. + +Update propagation is the hardest part. Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source. + +### Layer 5: Locale-aware UX + +Beyond translation, the experience must adapt. + +Currency: display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page. + +Numbers: thousand separators and decimals differ. `1,000.50` in en-US is `1.000,50` in de-DE. + +Dates and times: format and order vary. `MM/DD/YYYY` in en-US, `DD/MM/YYYY` in en-GB, `YYYY-MM-DD` (ISO) is universal but unfamiliar to many. + +Names and addresses: field order and required components differ. Country-aware address forms. + +Phone numbers: E.164 international format universally; display formatting per locale. + +Units: metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both. + +Right-to-left (RTL) languages: Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (`margin-inline-start` instead of `margin-left`) make this manageable. + +Language switcher: prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back. + +Cultural sensitivity: colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized. + +--- + +## Workflow + +### Step 1: Decide which locales + +Don't add languages just because you can. Each locale has ongoing maintenance cost. + +- Audience research: where are visitors and prospects? +- Business priority: which markets are growth targets? +- Content readiness: do you have the resources to maintain it? +- Legal: do regulations require localization (GDPR, accessibility laws)? + +### Step 2: Pick URL structure + +Subfolder for most. Document the choice and rationale. + +### Step 3: Pick content structure + +Mirror, subset, or local. Be honest about what's sustainable. + +### Step 4: Set up hreflang and canonicals + +Implement before launching the second locale, even if it's just one extra page. + +### Step 5: Set up translation workflow + +Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers. + +### Step 6: Localize beyond translation + +For each locale: +- Currency, numbers, dates, units +- Locale-specific images if needed +- Address forms +- Customer service hours and contact + +### Step 7: Implement language switcher + +- Prominent in the header or footer +- Shows the current locale clearly +- Lists all available locales in their own language +- Persists the choice (cookie or local storage) +- Doesn't auto-redirect based on browser; suggests instead + +### Step 8: Test + +- Each locale renders correctly +- hreflang links are valid (use a checker) +- Canonicals are self-referential per page +- Currency and dates are correct +- RTL layout is correct (for RTL locales) +- Language switcher works and persists +- Search-engine perspective: each locale is crawlable and indexable + +### Step 9: Launch and monitor + +Per locale: +- Indexing rate +- Traffic from intended geographies +- Engagement metrics in the locale +- Translation freshness (when did source content change without translation update?) + +### Step 10: Maintain + +- Translation update cadence (when source changes, when translations follow) +- Quarterly review of locale performance +- Sunset locales that aren't viable (better than maintaining a dead locale poorly) + +--- + +## Failure patterns + +Auto-redirect based on browser language. User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect. + +Single canonical to default language. Search engines can't index the translations. Self-canonical per page. + +Reciprocal hreflang missing. German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed. + +hreflang language without region when region matters. `hreflang="es"` is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions. + +Auto-translated content treated as final. Machine translation is an acceptable starting point. Human review is necessary for any user-facing content. + +Currency baked into copy. "$99/month" in body text breaks for European users. Use templated currency that adapts. + +Hardcoded date formats. "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale. + +Field labels left in source language. Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization. + +Untranslated error messages. User submits a form, gets an error in English on a French page. Frustrating. Translate UI states. + +Untranslated emails. Site is in French; transactional emails are English. Translate emails to match. + +Forgotten locales in CMS. Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift. + +Locale switcher that doesn't work mid-flow. User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale. + +RTL layouts that don't actually flip. Margin and padding hardcoded for LTR. Use CSS logical properties. + +Sunset language without redirect. Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language. + +--- + +## Output format + +An internationalization plan includes: + +- Locale list: with priority and audience rationale +- URL structure: chosen pattern and reason +- Content structure: mirror, subset, or local +- hreflang plan: how it's implemented +- Translation workflow: sources, stages, tools +- Localization checklist: beyond translation (currency, dates, etc.) +- Language switcher design: position, behavior, persistence +- Test plan: what's verified per locale +- Maintenance plan: update cadence, drift detection + +--- + +## Reference files + +- [`references/locale-checklist.md`](references/locale-checklist.md): Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal). diff --git a/dist/pi/.agents/skills/internationalization/references/locale-checklist.md b/dist/pi/.agents/skills/internationalization/references/locale-checklist.md new file mode 100644 index 0000000..8bb3bd8 --- /dev/null +++ b/dist/pi/.agents/skills/internationalization/references/locale-checklist.md @@ -0,0 +1,233 @@ +# Locale Checklist + +A per-locale checklist of everything that needs to adapt beyond translation. Walk through this for each locale before launch, and revisit when adding new content. + +--- + +## URL and structure + +- [ ] Locale URL pattern chosen and consistent (subfolder, subdomain, or ccTLD) +- [ ] Locale code uses standard format (BCP 47: `en`, `en-US`, `de-DE`, `zh-Hant`) +- [ ] Default locale handling decided (apex vs folder) +- [ ] URL slugs translated where appropriate (e.g., `/products/` → `/produkte/` for German) +- [ ] Or URL slugs kept consistent across locales (acceptable for many sites; prioritizes consistency over native readability) + +--- + +## Search engine signals + +- [ ] hreflang tags present on every page, every locale +- [ ] hreflang reciprocity verified (page A links to B, B links to A) +- [ ] hreflang includes `x-default` pointing to the fallback +- [ ] Canonical tags self-reference (each locale page canonicals to itself) +- [ ] Sitemaps include all locales (one sitemap per locale or a combined sitemap) +- [ ] robots.txt allows all locale paths +- [ ] Schema.org `inLanguage` attribute on appropriate types + +--- + +## Translation completeness + +- [ ] Page content translated +- [ ] Page titles and meta descriptions translated +- [ ] Image alt text translated +- [ ] Form labels translated +- [ ] Form validation messages translated +- [ ] Error pages (404, 500) translated +- [ ] Success messages translated +- [ ] Email templates translated (transactional, marketing) +- [ ] PDF or downloadable assets translated (or alternate version provided) +- [ ] Help and FAQ content translated +- [ ] Legal pages translated (privacy, terms, cookies) + +--- + +## Currency and money + +- [ ] Currency displayed matches the locale (EUR for euro zone, GBP for UK, JPY for Japan, etc.) +- [ ] Currency symbol position correct ($1,000 vs 1.000 €) +- [ ] Decimal separator correct (1,000.50 vs 1.000,50 vs 1 000,50) +- [ ] Thousand separator correct (comma, period, space, or none) +- [ ] Pricing tables localized to native pricing (not direct conversion) +- [ ] Tax handling (inclusive vs exclusive) matches local convention + +--- + +## Numbers and units + +- [ ] Number format follows locale (1,234.56 vs 1.234,56) +- [ ] Negative numbers (-5 vs (5)) follow convention +- [ ] Percentages format correctly (5% vs 5 %) +- [ ] Measurement units match (km vs miles, kg vs lb, °C vs °F) +- [ ] Paper sizes if relevant (A4 vs Letter) + +--- + +## Dates and times + +- [ ] Date format matches (DD/MM/YYYY for most of Europe, MM/DD/YYYY for US, YYYY-MM-DD ISO) +- [ ] Day-of-week localization (Monday vs Lundi vs 月曜日) +- [ ] Month names localized +- [ ] First day of week (Monday in Europe, Sunday in US) +- [ ] Time format (12-hour with AM/PM vs 24-hour) +- [ ] Time zone display where relevant +- [ ] Relative time strings localized ("2 hours ago" → "il y a 2 heures") + +--- + +## Names and addresses + +- [ ] Name field structure matches (single name field for some cultures, given/family for others, family-first ordering for some Asian languages) +- [ ] Address form fields adapt to country + - US: street, city, state, ZIP + - UK: street, town, county, postcode + - Germany: street, postal code, city + - Japan: postal code, prefecture, city, ward, block, building +- [ ] Postal code validation per country +- [ ] State/region/prefecture/county field renamed appropriately +- [ ] Country dropdown ordered by region or alphabetical (avoid US-first if not US-centric audience) + +--- + +## Phone numbers + +- [ ] Country code defaulted appropriately +- [ ] E.164 format stored (+CCNNNNNNNNNN) +- [ ] Display format adapts to country +- [ ] Validation accepts international formats + +--- + +## Imagery and media + +- [ ] Images depict locally relevant people, places, products +- [ ] Avoided imagery that's offensive in the locale (gestures, symbols, color associations) +- [ ] Cultural references in screenshots/examples are appropriate +- [ ] Image text translated (text in images doesn't auto-translate) +- [ ] Video subtitles or dubbing in the locale language + +--- + +## Layout and direction + +- [ ] LTR/RTL handling correct for the script +- [ ] CSS logical properties used (`margin-inline-start` instead of `margin-left`) +- [ ] Icons that imply direction (arrows, chevrons) flip for RTL +- [ ] Numbers display LTR even within RTL text (per Unicode bidi algorithm) +- [ ] Tables and lists adjusted for direction + +--- + +## Typography + +- [ ] Fonts support the script (not all fonts cover Cyrillic, CJK, Arabic, etc.) +- [ ] Font sizes adjusted if needed (some scripts read smaller; CJK often needs slightly larger) +- [ ] Line height appropriate (CJK often needs more) +- [ ] Word breaking handled (no breaking in the middle of CJK characters; break opportunities for Thai) +- [ ] Quotation marks correct ("..." in English, „..." in German, «...» in French, 「...」 in Japanese) + +--- + +## Search and sort + +- [ ] Search handles diacritics ("café" matches "cafe" or doesn't, by design) +- [ ] Sort order respects locale (German sorts ä with a, Swedish sorts ä after z) +- [ ] Search results in the same locale as the user (don't show English results to French users) + +--- + +## Forms and inputs + +- [ ] Input methods supported (IMEs for CJK, etc.) +- [ ] Pasting from clipboard works with non-Latin characters +- [ ] Field validation accepts non-Latin characters where appropriate (names should accept any Unicode) +- [ ] Min/max length constraints work for the script (Japanese names are often shorter; Arabic/Hebrew names use different character counts) + +--- + +## Legal and compliance + +- [ ] Privacy policy adapted to local laws (GDPR for EU, LGPD for Brazil, CCPA for California, etc.) +- [ ] Cookie consent matches local requirements +- [ ] Terms of service in local language and acknowledging local law +- [ ] Required disclaimers present (consumer protection, financial services, healthcare, etc.) +- [ ] Tax handling per locale (display inclusive in EU, exclusive in US, etc.) +- [ ] Local payment methods supported where customer expectations require + +--- + +## Customer support and contact + +- [ ] Support hours displayed in local timezone +- [ ] Support contact options match (phone numbers, chat, email, varies by region) +- [ ] Office address (if shown) is appropriate for the locale +- [ ] Local language support team or clear "support in [language]" indication + +--- + +## Marketing and SEO + +- [ ] Keyword research done in the local language (not just translated keywords) +- [ ] Meta titles and descriptions are locally compelling, not just translated +- [ ] Open Graph tags adapted (translated, locale-appropriate images) +- [ ] Schema.org markup translated where text-based +- [ ] Local search engines considered (Baidu in China, Yandex in Russia) +- [ ] Backlink strategy adapted to local web (local directories, local press) + +--- + +## Testing per locale + +- [ ] Page renders correctly in all major browsers +- [ ] Page renders correctly on mobile +- [ ] All links work and stay within the locale (or correctly switch locale) +- [ ] Forms submit correctly +- [ ] Confirmation flows work end-to-end (form → email → next step) +- [ ] No untranslated strings (search HTML for source-language strings) +- [ ] No broken images +- [ ] No layout breakage from longer or shorter text (German is often longer than English; CJK often shorter; Arabic similar to English in length but different layout) +- [ ] Performance comparable to default locale + +--- + +## Language switcher + +- [ ] Switcher visible on every page +- [ ] Available locales shown in their own language +- [ ] Current locale clearly indicated +- [ ] Switcher preserves the current page (not just sends to homepage) +- [ ] Switcher persists user choice (cookie or local storage) +- [ ] Switcher doesn't auto-redirect on first visit (suggests, doesn't force) + +--- + +## Maintenance + +- [ ] Translation update workflow defined +- [ ] Drift detection in place (when source changes, translation needs update) +- [ ] Per-locale analytics set up +- [ ] Per-locale error monitoring +- [ ] Translation quality reviewed periodically +- [ ] Locale sunset criteria defined (when to retire a poorly-performing locale) + +--- + +## Per-locale metrics to watch + +\| Metric \| Target \| +\|---\|---\| +\| Page completion rate \| Comparable to default locale \| +\| Form completion rate \| Comparable to default locale \| +\| Bounce rate \| Comparable to default locale \| +\| Time on page \| Comparable to default locale \| +\| Conversion rate \| Comparable to default locale \| +\| Translation freshness \| Source content updates reflected within X days \| + +A locale persistently underperforming on user metrics may have: +- Translation quality issues +- Cultural mismatches in copy or imagery +- Missing local payment or contact options +- Slow performance from far hosting +- Unmet user expectations (US e-commerce conventions used in markets that prefer different patterns) + +Investigate before scaling investment. diff --git a/dist/pi/.agents/skills/journey-mapping/SKILL.md b/dist/pi/.agents/skills/journey-mapping/SKILL.md new file mode 100644 index 0000000..c65508e --- /dev/null +++ b/dist/pi/.agents/skills/journey-mapping/SKILL.md @@ -0,0 +1,244 @@ +--- +name: journey-mapping +description: "Build customer journey maps and service blueprints that visualize the end-to-end user experience including touchpoints, emotions, friction, and underlying systems. Use this skill whenever the user wants to map a customer journey, build a service blueprint, identify friction across an experience, align teams on the user experience, or visualize touchpoints and pain points. Triggers on customer journey, journey map, service blueprint, user journey, experience map, touchpoint analysis, friction map, journey audit, end-to-end experience, customer experience map. Also triggers when the team has departmental views of users but no shared map of what the experience actually feels like." +category: research +catalog_summary: "Customer journey maps, service blueprints, friction analysis" +display_order: 3 +--- + +# Journey Mapping + +Build journey maps and service blueprints that surface friction, align teams, and identify opportunities. Stack-agnostic. Tool-agnostic. + +This skill is for mapping the experience. For testing specific touchpoints, use `usability-testing`. For broader generative research, use `ux-research`. For analyzing conversion, use `cro-optimization`. + +--- + +## When to use + +- Departments have different mental models of the customer experience +- Customer experience feels disjointed across touchpoints +- Specific friction or drop-off points need diagnosis +- Strategic planning needs a shared view of the user +- Service design (front-stage and back-stage) needs alignment +- New product or feature needs to be designed in context of broader experience + +## When NOT to use + +- Testing a single touchpoint or page (use `usability-testing`) +- Generative research before journey mapping (use `ux-research`) +- Operational process mapping that doesn't involve users +- Funnel optimization (use `cro-optimization`) + +--- + +## Required inputs + +- Identified user persona or segment to map (one map per segment) +- Existing research and data about that segment +- Cross-functional access (you cannot map back-stage without ops/support/engineering input) +- Time and stakeholder commitment (a real journey map is a project, not an afternoon) + +--- + +## The framework: 3 deliverables + +### 1. Customer journey map + +The user-facing view of the experience. + +Structure (rows / lanes): + +- Phase. The major stages in the journey (e.g., Awareness, Consideration, Onboarding, Activation, Retention, Advocacy). Phases vary by product type. +- Steps. Specific things the user does within each phase. +- Touchpoints. Where the user interacts with the product, brand, or service (web, app, email, support, social, in-person). +- Goals. What the user is trying to accomplish at this step. +- Thoughts. What's going through their mind. +- Emotions. The emotional state (often visualized on a curve). +- Pain points. Where things go wrong, friction, frustration. +- Opportunities. Where the experience could improve. + +Format: + +Typically a horizontal timeline with vertical lanes for each row. Phases across the top, touchpoints, thoughts, emotions, etc. underneath. + +### 2. Service blueprint + +The back-stage view that supports the customer-facing experience. + +Adds these layers below the journey map: + +- Front-stage actions. What employees do that the user sees (sales calls, support chats, in-store interactions). +- Back-stage actions. What happens behind the scenes (order fulfillment, data processing, internal handoffs). +- Supporting processes. Systems, vendors, infrastructure (CRM, payment processors, fulfillment partners). +- Lines of visibility. The line between front-stage (visible to user) and back-stage (invisible). + +The service blueprint shows where customer-facing problems originate in back-stage failures (e.g., the user's "shipping is slow" experience traces to a vendor handoff issue). + +### 3. Synthesized opportunity map + +Output of the mapping work. + +Captures: + +- Top friction points. Where the experience consistently fails users. +- Untapped opportunities. Moments where the experience could surprise and delight. +- Disconnects. Where front-stage and back-stage are misaligned. +- Strategic gaps. Where competitors have something the brand lacks (or vice versa). +- Quick wins. Low-effort, high-impact improvements. +- Strategic bets. Higher-effort transformations. + +This is the deliverable that produces decisions. The journey map and service blueprint are inputs; the opportunity map is the output that drives action. + +--- + +## Common phases by product type + +### Most products + +``` +Awareness → Consideration → Decision → Onboarding → Active use → Renewal/Repurchase → Advocacy +``` + +### SaaS + +``` +Trigger → Discovery → Evaluation → Trial → Onboarding → Activation → Habit → Expansion → Renewal → Advocacy +``` + +### Ecommerce + +``` +Need recognition → Discovery → Research → Decision → Purchase → Wait/Anticipation → Receive → Use → Reorder/Recommend +``` + +### Service + +``` +Awareness → Inquiry → Quote → Decision → Service delivery → Resolution → Follow-up → Repeat business +``` + +### Healthcare / high-stakes purchases + +``` +Trigger → Research → Provider selection → Appointment → Treatment → Recovery → Follow-up → Long-term outcome +``` + +Phases are not mandatory. Start with the user's actual experience and let the phases emerge from the steps. + +--- + +## How to gather the inputs + +A good journey map combines multiple sources of truth. + +### From users + +- In-depth interviews. Walk users through their actual experience. Ask for specifics from a recent occurrence. +- Diary studies. Users log their experience over the duration of the journey. +- Surveys. Quantitative signal at scale; less depth. + +### From the business + +- Internal interviews. Sales, support, success, ops. They see the experience from different angles than product or design. +- Operational data. Funnel data, support ticket categories, NPS responses, churn reasons. +- System inventory. What touchpoints exist, what tools support them, what data flows where. + +### Cross-validate + +- The user's experience as they describe it +- The data the business has about their behavior +- The internal team's perception of the experience + +These three views often disagree. The disagreements are themselves findings. + +--- + +## Workflow + +1. Define scope. One persona, one journey, one timeframe. Trying to map all users in one map produces a mess. +2. Gather inputs. User interviews, internal interviews, operational data. Plan 2 to 4 weeks for inputs. +3. Draft the journey. Phases, steps, touchpoints. Get to a working draft fast; iterate. +4. Add the layers. Goals, thoughts, emotions, pain points. +5. Build the service blueprint. Front-stage, back-stage, supporting processes. +6. Identify opportunities. Use the friction points and disconnects. +7. Validate with users. Does this match their actual experience? Refine. +8. Workshop with stakeholders. Walk teams through the map. Ensure shared understanding. +9. Translate to action. Specific projects, owners, timelines. +10. Maintain. A journey map is a living document. Revisit annually or after major changes. + +--- + +## Failure patterns + +- Mapping without research. A journey map built from internal assumptions reflects assumptions, not users. +- One map for all users. The mid-market buyer and enterprise buyer have different journeys. Don't merge. +- No back-stage layer. The map shows symptoms, not causes. +- Beautiful map, no action. Investment in production value at the expense of decisions. +- Map as artifact, not tool. Filed in Figma, never re-opened. +- Ignoring emotional layer. The "what" without the "how it feels" misses the point of journey mapping. +- Vague pain points. "Frustrating onboarding" - what specifically? When? Why? +- Quick wins identified, never executed. Same as research findings that don't ship. +- Annual exercise without followup. Year-old journey map describes year-old user. + +--- + +## Output format + +Default outputs: + +1. Journey map (visual, typically Figma / FigJam / Miro, plus a markdown narrative version) +2. Service blueprint (visual, typically same tool) +3. Opportunity map (markdown, prioritized list) + +Markdown narrative version of journey map: + +```markdown +# [Persona] journey map + +## Phase 1: [Phase name] + +### Step: [Step name] +- Touchpoint: [Where this happens] +- Goal: [What the user wants here] +- Thoughts: [What they're thinking] +- Emotion: [State on the emotional curve] +- Pain points: [Friction] +- Opportunities: [Improvement potential] + +### Step: [Step name] +[Same structure] + +## Phase 2: [Phase name] +[Repeat] + +## Service blueprint additions + +### Phase 1 +- Front-stage actions: [What employees do user-visibly] +- Back-stage actions: [What happens behind the scenes] +- Supporting processes: [Systems involved] + +[Repeat per phase] + +## Opportunity map + +### Critical friction +1. [Specific issue, with evidence] +2. [Specific issue, with evidence] + +### Quick wins +1. [Specific opportunity, with effort/impact] + +### Strategic bets +1. [Specific opportunity, with effort/impact] + +### Cross-team disconnects +1. [Specific disconnect, with implication] +``` + +--- + +## Reference files + +- [`references/journey-map-template.md`](references/journey-map-template.md) - Fillable journey map and service blueprint template. diff --git a/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md b/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md new file mode 100644 index 0000000..372ea22 --- /dev/null +++ b/dist/pi/.agents/skills/journey-mapping/references/journey-map-template.md @@ -0,0 +1,317 @@ +# Journey Map Template + +Fillable journey map and service blueprint template. Customize phases to fit the specific product or service. + +--- + +## Map metadata + +Persona / segment mapped: [Specific persona. Not "users" - "First-time buyers in the 25-40 age range exploring B2B project management tools."] + +Time horizon mapped: [Pre-purchase to first 90 days? Full lifetime? Specific feature?] + +Map version: [X.Y] + +Last updated: [YYYY-MM-DD] + +Owner: [Person or team] + +Source data: [Interviews, surveys, support tickets, analytics. List with counts.] + +--- + +## Map structure + +\| Phase \| Step \| Touchpoint \| Goal \| Thoughts \| Emotion \| Pain points \| Opportunities \| +\|---\|---\|---\|---\|---\|---\|---\|---\| + +--- + +## Phase 1: [Phase name, e.g., Awareness] + +### Step 1.1: [Step name, e.g., Encounters problem] + +Touchpoint: [Where this happens. Could be offline. "Conversation with peer." Or online: "LinkedIn post."] + +Goal: [What the user is trying to accomplish at this step] + +Thoughts: +- "[Specific thought, ideally a real quote from research]" +- "[Specific thought]" +- "[Specific thought]" + +Emotion: [Emotional state, ideally from a defined set: confused, hopeful, frustrated, curious, anxious, confident, etc.] + +Emotional intensity: [1 to 5, for plotting on the emotional curve] + +Pain points: +- [Specific pain, with evidence] +- [Specific pain, with evidence] + +Opportunities: +- [Specific improvement opportunity] +- [Specific improvement opportunity] + +Time spent at this step: [Minutes / hours / days / weeks - average and range] + +--- + +### Step 1.2: [Step name] + +[Repeat structure] + +--- + +## Phase 2: [Phase name, e.g., Consideration] + +### Step 2.1: [Step name, e.g., Searches for solutions] + +Touchpoint: [e.g., Google search, then 4 to 6 vendor websites] + +Goal: [Build a shortlist of options that could fit] + +Thoughts: +- "[Quote]" +- "[Quote]" + +Emotion: [State] + +Emotional intensity: [1 to 5] + +Pain points: +- [Specific pain] +- [Specific pain] + +Opportunities: +- [Opportunity] + +Time spent: [Range] + +--- + +### Step 2.2: [Step name] + +[Repeat] + +--- + +## Phase 3: [Phase name, e.g., Decision] + +[Repeat structure] + +--- + +## [Continue with phases relevant to the journey...] + +--- + +## Emotional curve + +Plot the emotional intensity across the journey. The curve typically reveals the moments of highest joy and highest frustration. + +``` +Emotion +intensity + 5 │ + 4 │ ● + 3 │ ● ● ● + 2 │ ● ● ● ● + 1 │ ● ● + └────────────────────── + 1.1 2.1 3.1 4.1 + Phase / Step +``` + +[Document the emotional curve in your visual tool. Note the peaks (highest joy) and troughs (highest frustration). These are the most strategic points in the journey.] + +--- + +## Service blueprint layers + +For each phase, document the back-stage view. + +### Phase 1: [Phase name] + +Front-stage actions (employees in user view): +- [Action] +- [Action] + +Back-stage actions (employees behind the scenes): +- [Action] +- [Action] + +Supporting processes (systems, tools, vendors): +- [Process / system] +- [Process / system] + +Lines of visibility issues: +- [Where back-stage failures cause front-stage problems] + +--- + +### Phase 2: [Phase name] + +[Repeat] + +--- + +## Disconnects and gaps + +The most valuable findings often come from comparing layers. + +### Front-stage / back-stage disconnects + +\| Issue \| Front-stage symptom \| Back-stage cause \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +### Internal team perception vs user reality + +\| Internal belief \| User reality \| Gap \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +### Touchpoint / message inconsistencies + +\| Touchpoint A says \| Touchpoint B says \| Confusion result \| +\|---\|---\|---\| +\| \| \| \| + +--- + +## Persona context (for reference) + +A reminder of who this map represents. + +Persona: [Name and one-line description] + +Demographics: +- Age range: +- Role / job: +- Company size or context: +- Geography: +- Tech savviness: + +Goals: +- [Primary goal] +- [Secondary goal] +- [Secondary goal] + +Frustrations: +- [Frustration] +- [Frustration] + +Behavior patterns: +- [Pattern] +- [Pattern] + +Quote that captures them: +> "[Quote from a research participant who exemplifies this persona]" + +--- + +## Data sources + +Document where the map's claims come from. Builds credibility and traceability. + +\| Claim \| Source \| Evidence \| +\|---\|---\|---\| +\| [Pain point at step 2.1] \| 8 of 10 interviews \| [Quote samples] \| +\| [Behavior at step 1.2] \| Analytics: 73% drop-off \| [Funnel data] \| +\| [Emotion at step 3.1] \| Survey, 45 responses \| [Score data] \| + +--- + +## Opportunity map + +The output that drives action. + +### Critical friction (fix soon) + +\| Friction \| Phase / step \| Evidence \| Recommended action \| Effort \| Owner \| +\|---\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| \| S/M/L \| \| +\| [Specific] \| \| \| \| S/M/L \| \| + +### Quick wins (low effort, meaningful impact) + +\| Opportunity \| Phase / step \| Recommended action \| Effort \| Impact \| +\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| S \| M \| + +### Strategic bets (high effort, transformative) + +\| Opportunity \| Phase / step \| Recommended action \| Effort \| Impact \| +\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| L \| H \| + +### Cross-team alignment opportunities + +[Issues that require multiple teams to coordinate, not single-team fixes.] + +- [Issue, teams involved, recommended approach] +- [Issue, teams involved, recommended approach] + +--- + +## Action plan + +Specific projects from the opportunity map. + +### Immediate (next 30 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Near-term (60 to 90 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Strategic (next 2 to 4 quarters) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +--- + +## Re-mapping schedule + +Journey maps decay. Schedule re-mapping: + +- Triggering events: Major product launch, new persona segment, significant business model change, drop in NPS or retention +- Default cadence: Annual review, with light updates quarterly + +--- + +## Workshop outputs + +Use this map in stakeholder workshops. Capture outputs: + +Workshop 1: Validation +- Date: +- Attendees: +- Findings validated: +- Findings disputed: +- New findings surfaced: + +Workshop 2: Prioritization +- Date: +- Attendees: +- Top opportunities agreed: +- Decisions made: +- Open questions: + +--- + +## Companion artifacts + +Often produced alongside a journey map: + +- Persona document. Detailed persona that this journey map represents. +- Quote library. Direct user quotes organized by phase. Powerful in stakeholder presentations. +- Highlight reel video. 5 to 10 minute compilation of user moments mapped to journey phases. +- Service blueprint. Detailed back-stage map (this template includes a layer; a full blueprint deserves its own document). +- Opportunity backlog. All opportunities, scored and queued for execution. diff --git a/dist/pi/.agents/skills/jtbd-framing/SKILL.md b/dist/pi/.agents/skills/jtbd-framing/SKILL.md new file mode 100644 index 0000000..56313a8 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/SKILL.md @@ -0,0 +1,260 @@ +--- +name: jtbd-framing +description: "The Jobs-to-be-Done framework as applied product methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity (discovery, prioritization, positioning) and where it becomes performative ritual (job-statement workshops that do not drive decisions, persona-theater disguised as JTBD). Triggers on jobs-to-be-done, JTBD, job statements, struggling moments, hire criteria, fire criteria, switch triggers, functional emotional social jobs, outcome-driven innovation. Also triggers when a team is over-relying on feature-request lists or persona archetypes that do not drive product decisions, when a positioning conversation needs the framing JTBD provides, or when discovery is producing outputs that do not connect to product strategy." +category: product +catalog_summary: "Jobs-to-be-Done framework. Job statements, struggling moments, hire/fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD earns its keep and where it becomes performative" +display_order: 11 +--- + +# Jobs-to-be-Done Framing + +A senior product leader's playbook for the Jobs-to-be-Done framework as applied methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity and where it becomes performative ritual. + +JTBD has become one of the more cited and less practiced frameworks in product. Teams cite it in strategy docs, run job-statement workshops, produce wall-sized artifacts, and continue building from feature requests and persona archetypes the next quarter. The methodology gets the credit; the practice gets skipped. + +This skill is JTBD as applied product methodology. The framework's actual contribution: surfacing what users are trying to ACCOMPLISH (the job) rather than treating users as preference-aggregators (feature requests) or demographic archetypes (persona theater). When the framing is grounded in struggling moments and hire/fire criteria, it produces decisions; when it stops at the job-statement worksheet, it produces ritual. + +This skill is honest about both modes. JTBD genuinely earns its keep in discovery, prioritization, and positioning when applied with rigor. It becomes ceremony when teams treat job statements as deliverables rather than as analytical tools. + +The voice is the senior product leader who has used JTBD well and watched plenty of teams use it badly. Concrete, opinionated about what the framework actually contributes, willing to call out where it gets oversold. + +When to use this skill: applying JTBD to a discovery cycle, replacing persona-driven prioritization with job-driven prioritization, reframing positioning around what users hire the product to do, or auditing whether existing JTBD work in the org is driving decisions. + +--- + +## What this skill is for + +This skill spans JTBD as a framing technique within product work. The PM-skill distinction: + +- `discovery-research-synthesis` is broader synthesis discipline; JTBD is one framing technique within it. +- `jtbd-framing` (this skill) is the specific JTBD methodology, its strengths, and its failure modes. +- `pm-spec-writing` is downstream: specs reference jobs as input. +- `creative-direction` is positioning territory; JTBD informs positioning but does not replace creative direction. +- `roadmap-planning` is downstream: roadmap can be organized around jobs rather than features. + +The audience: senior PMs, product directors, product strategists, agencies running discovery and positioning work, in-house teams considering or already using JTBD. + +What is not in scope: other product strategy frameworks (Wardley mapping, North Star, OKRs); the broader synthesis discipline (`discovery-research-synthesis` covers it); the demographic-persona work that sometimes gets confused with JTBD. + +--- + +## Feature-request-list vs persona-theater vs job-framing + +The keystone framing. + +Feature-request-list. "Users want X, Y, Z." Treats users as preference-aggregators. The product team builds the most-requested features. Output: a product that satisfies stated preferences but misses what users were actually trying to accomplish. Users do not always know what would solve their problem; they describe symptoms, not solutions. Feature-list-driven products often improve incrementally without becoming meaningfully better. + +Persona-theater. Demographic personas with cute names. "Marketing Manager Maria, 35, urban, Pinterest user, drinks oat milk lattes." Decorative, not decision-driving. Persona characteristics rarely correlate with what the user needs from the product; demographic detail substitutes for behavioral insight. Personas in the wild often live as wall posters that nobody references in actual prioritization debates. + +Job-framing. Users hire products to do jobs. The job is what the user is trying to accomplish, not who the user is or what features they request. The framing surfaces struggling moments (when do users feel pulled toward an alternative); hire criteria (what makes them adopt a product); fire criteria (what makes them switch away). Output: product decisions grounded in user motivation rather than user description. + +The litmus test. Take a product decision the team is debating. Can JTBD ground the decision? "Should we build feature X?" Reframed: "What job would feature X help users do? What job is currently done badly that this addresses?" If the JTBD framing produces clearer arguments on both sides, the framing is earning its keep. If the JTBD framing just adds vocabulary without resolving the debate, the framing is ritual. + +--- + +## The job statement structure + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." + +Situation. The context, trigger, or moment when the job becomes active. Not a demographic; a moment. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck..." +- "When I get a customer escalation outside of business hours..." + +Motivation. What the user is trying to do in that situation. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage and respond without disrupting my evening too much..." + +Outcome. What success looks like; what the user is trying to achieve by doing the job. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." + +The structure forces specificity at all three levels. Vague situations, vague motivations, or vague outcomes produce job statements that drive nothing. + +Detail in [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md). + +--- + +## Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when the alternative tools they have feel inadequate, when they would actively prefer a different way of doing the job. + +The signal. Users describe friction in their current approach. They describe workarounds. They describe wishing they had something better. They describe specific moments when the current approach broke down. + +The methodology. Discovery interviews surface struggling moments through specific prompts: "Walk me through the last time you did X." "What was hardest about that?" "What would you have done differently if you could?" Specific recent moments produce richer data than abstracted descriptions of "how I usually do this." + +The pattern recognition. Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well in the market. + +The pitfall. Teams that interview without grounding in specific moments produce abstracted job descriptions that cannot drive decisions. "Users want to be more productive" is not a struggling moment; "I lost an hour on Tuesday assembling the board metrics from three different dashboards because none of them had the slice I needed" is. + +Detail in [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md). + +--- + +## Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground the framework in real decisions users make. + +Hire criteria. + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +Fire criteria. + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +Why hire/fire matters. + +- Hire criteria reveal what the product needs to be excellent at to win adoption. +- Fire criteria reveal what the product needs to maintain to retain users. +- The two are often different: features that win adoption are not always the features that prevent churn. + +The methodology. Customer interviews surface hire/fire through specific prompts: "What were you doing before you adopted X?" "What made you switch?" "If you switched away from X tomorrow, what would the trigger be?" Recent switch decisions are particularly rich; users remember the specific moment. + +Detail in [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md). + +--- + +## Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. + +Functional dimension. What the user is mechanically trying to accomplish. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." + +Emotional dimension. How the user feels (or wants to feel) doing the job. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." + +Social dimension. How the user wants to be perceived doing the job. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." + +Why three dimensions matter. + +- Products that win on functional alone often lose to alternatives that also serve emotional and social. +- Some product decisions hinge on emotional dimensions ("the user wants to feel in control"); functional analysis alone misses these. +- Social dimensions inform positioning more than functional descriptions do. + +The discipline. For each job statement, ask the three dimensions explicitly. Most early job statements are functional-only; the addition of emotional and social often reveals what the product actually needs to address. + +Detail in [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md). + +--- + +## Where JTBD adds clarity vs where it becomes ritual + +The honest framing. + +Where JTBD genuinely earns its keep. + +- Discovery. When research is grounded in struggling moments and hire/fire decisions, JTBD surfaces the user motivation that feature-list discovery misses. Discovery interviews structured around jobs produce richer data than ones structured around feature preferences. +- Prioritization. When the team is debating which work to prioritize, jobs ground the debate in what users are trying to accomplish. "Does this work help users do an important job better?" cuts through the politics of feature-request prioritization. +- Positioning. When marketing or sales is articulating what the product does, jobs frame the product as a way of accomplishing something the customer cares about, rather than as a feature list. + +Where JTBD becomes ritual. + +- Job-statement workshops as deliverables. The team runs a workshop, produces a wall of job statements, and never references the artifacts in subsequent decisions. The workshop became the deliverable; the analytical work did not happen. +- Job statements substituted for personas without analytical rigor. "We have JTBD now" but the team treats job statements as named characters (Job Bob, Job Alice) instead of as analytical tools. +- Mandatory JTBD for every product question. Every meeting starts with "what's the job?" Even when the question does not benefit from the framing. The methodology becomes a tax rather than a tool. +- JTBD as compliance. The org adopts JTBD because a leadership book or conference talk endorsed it; teams produce JTBD artifacts to show they are using the framework; nobody actually uses the framework to decide. + +The honest signal. If the team can show how a recent product decision was different because of JTBD analysis, the framework is earning its keep. If the team uses JTBD vocabulary but cannot trace decisions to JTBD analysis, the framework is ritual. + +--- + +## Applying JTBD to discovery, prioritization, positioning + +The three modes where JTBD genuinely contributes. + +Discovery. Structure interviews around recent struggling moments, hire decisions, and fire decisions. Gather job statements after the interviews from the data, not before. Cluster jobs across users. Name jobs from the clusters. Pair with `discovery-research-synthesis` for the broader synthesis discipline. + +Detail in [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md). + +Prioritization. When evaluating roadmap candidates, frame each candidate by the job(s) it addresses. Ask: which jobs is the product currently doing badly? Which candidates address those jobs vs adjacent or unrelated work? Pair with `roadmap-planning` for the broader prioritization discipline. + +Detail in [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md). + +Positioning. When articulating what the product is for, lead with the job rather than the features. "Help product teams synthesize discovery research into decisions" is a job framing; "AI-powered research synthesis with collaboration tools" is a feature framing. Pair with `creative-direction` and `brand-discovery` for the broader positioning work. + +Detail in [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md). + +- "We did the JTBD workshop but nothing changed in our roadmap." Job-statement workshop as deliverable; no analytical work after the workshop. +- "Our job statements all sound the same." Generic job statements; not grounded in specific struggling moments. Re-ground in interview data. +- "Our jobs read like feature requests." "When I am using product X, I want feature Y" is not a job; the job is what the user was trying to accomplish, independent of the product. +- "We have personas and jobs and they contradict each other." Personas are demographic; jobs are situational. They do not have to align; if they conflict, jobs usually carry more decision weight. +- "JTBD says we should build everything." Without prioritization across jobs, JTBD identifies many opportunities and does not pick. Pair with prioritization discipline. +- "We dropped JTBD because it became theater." Common; the recovery is JTBD as analytical tool, not JTBD as ritual. Use the framework where it earns its keep; do not force it everywhere. +- "Our job statements are functional only." Add emotional and social dimensions; many product decisions hinge on the latter two. +- "We cannot agree on the job." Often signals different segments with different jobs. Surface the segment differences. +- "Our marketing copy uses JTBD vocabulary but our product does not." Positioning-product gap; the marketing claim is not load-bearing in product decisions. + +--- + +## The framework: 12 considerations for JTBD framing + +When applying JTBD or auditing JTBD work, walk these 12 considerations. + +1. Job-framing, not feature-list or persona-theater. Users hire products to accomplish jobs. +2. Job statement structure: situation, motivation, outcome. Specific at all three levels. +3. Struggling moments ground the jobs. Specific recent moments, not abstractions. +4. Hire criteria identified. What makes users adopt the product over alternatives. +5. Fire criteria identified. What makes users switch away (or would). +6. Functional, emotional, social dimensions surfaced. All three; not functional only. +7. Jobs derived from data, not workshop output. Job statements emerge from interview data, not from whiteboard sessions. +8. JTBD applied where it earns its keep. Discovery, prioritization, positioning. Not as ritual. +9. Segment differences in jobs surfaced. When the same product is hired for different jobs by different segments. +10. Decisions traceable to JTBD analysis. Each major decision can be explained through the job framing. +11. JTBD vocabulary not substituted for analytical work. Vocabulary without analysis is ritual. +12. Honest assessment of where JTBD does not help. Some questions do not benefit from the framing; force-fitting produces ritual. + +The output of the framework is product decisions grounded in user motivation rather than user description, with the framing applied where it adds clarity and held back where it would become ritual. + +--- + +## Reference files + +- [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md) - The situation/motivation/outcome structure with worked examples. Common structural failures (vague situations, motivation as feature request, outcome as feature output). +- [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md) - Discovery prompts that surface struggling moments. Pattern recognition across users. The specific-moment vs abstraction distinction. +- [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md) - Methodology for surfacing hire and fire criteria. Why the two are often different. Recent-switch interview discipline. +- [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md) - Three dimensions per job. Why functional-only fails. Worked examples per dimension. Positioning implications of social dimension. +- [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md) - Discovery interview structure around jobs. Job clustering. Naming jobs from data. Pair with discovery-research-synthesis. +- [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md) - Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. Pair with roadmap-planning. +- [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md) - Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pair with creative-direction. +- [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md) - 9+ failure patterns with diagnoses and cures. The cross-cutting pattern: JTBD as ritual vs JTBD as analytical tool. + +--- + +## Closing: jobs over features + +The Jobs-to-be-Done framework is one of the most useful product methodologies available when applied with rigor, and one of the most performative when applied as ritual. The difference is in whether the framework drives decisions or decorates documentation. + +Jobs over features is a real shift in product thinking. Feature-list discovery treats users as preference-aggregators; persona archetypes treat users as demographic categories; job-framing treats users as people trying to accomplish things, where the product is one tool they hire (or fire) for the job. + +The teams that benefit from JTBD are the ones that take the analytical work seriously: grounding jobs in struggling moments, identifying hire and fire criteria, surfacing functional-emotional-social dimensions, deriving jobs from data, and applying the framing where it earns its keep. The teams that adopt JTBD vocabulary without the analytical work produce ritual. + +When in doubt about whether a JTBD application is real or ritual, ask: can a recent product decision be traced to the JTBD analysis, or did the JTBD work happen in parallel with decisions that were made on other grounds? If the former, JTBD is doing its work. If the latter, the framework is decoration. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md new file mode 100644 index 0000000..cddb634 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-discovery.md @@ -0,0 +1,211 @@ +# Applying JTBD to discovery + +How JTBD shapes discovery interview structure, job clustering, and naming jobs from data. Pairs with `discovery-research-synthesis` for the broader synthesis discipline. + +JTBD's strongest contribution to discovery is structural: interviews grounded in struggling moments and hire/fire decisions produce richer data than interviews that ask about feature preferences or use cases. + +--- + +## Structuring discovery interviews around jobs + +The JTBD discovery interview structure differs from feature-elicitation interviews. + +Feature-elicitation interview pattern. + +- "What problems are you trying to solve?" +- "What features would help?" +- "What is your ideal product?" + +This structure produces user-prescribed solutions: feature requests, ideal-product fictions, and abstracted preferences. The data is hard to act on because users do not always know what would actually help. + +JTBD interview pattern. + +- "Walk me through the last time you did [task]. What happened? What was hardest?" +- "What were you doing before you adopted [current solution]? What made you switch?" +- "Tell me about a recent time when [task] went badly. What was different about that time?" +- "If you switched away from [current solution] tomorrow, what would the trigger be?" + +This structure grounds the data in specific moments and real decisions. Users describe their experience; the PM doing synthesis interprets what the experience implies. + +--- + +## Interview prompts that work + +Recent specific moments. + +- "Walk me through the most recent time you did [task]." +- "What was the last week when [task] cost you more time than usual?" +- "When was the last time [task] surprised you in a bad way?" + +Hire decision prompts. + +- "Tell me about the moment you decided to start using [product]." +- "What were you doing before? What made you switch?" +- "What alternatives did you consider? What ruled them out?" + +Fire decision prompts (for users who switched). + +- "Tell me about the moment you decided to switch away from [product]." +- "What was the alternative starting to look better? What tipped you?" +- "Looking back, why didn't you switch sooner?" + +Workaround prompts. + +- "What's something you do that takes longer than it should?" +- "What workarounds have you built?" +- "When was the last time you accepted a worse outcome because the better path was too painful?" + +--- + +## Interview prompts that fail + +Hypothetical prompts. + +- "What would your ideal product look like?" (produces fiction) +- "If you had a magic wand, what would you change?" (produces wishlist) +- "What features would you like?" (produces feature lists) + +Abstracted prompts. + +- "How do you usually do [task]?" (produces averaged descriptions) +- "What's your typical experience?" (loses the specifics) +- "What kind of user are you?" (produces self-categorization) + +Leading prompts. + +- "Don't you find [feature] frustrating?" (confirms the team's hypothesis) +- "Wouldn't it be great if [feature]?" (produces agreement, not data) + +--- + +## The interview length and depth + +JTBD interviews benefit from depth. Surface answers come quickly; deeper jobs surface in the second half of an interview. + +Typical structure. + +- Minutes 0-15: warm-up, general context, what the user does and how their work fits together. +- Minutes 15-45: the recent specific moments, walk-throughs, struggling moments. The richest data emerges here. +- Minutes 45-60: hire and fire decisions, alternatives considered, switch decisions. +- Minutes 60-75 (when warranted): emotional and social dimensions, how the user wants to be perceived doing the work. +- Minutes 75-90: closing prompts, what the user wishes was different, what they would have done differently. + +The depth payoff. Users open up after 30-40 minutes. The struggling moments they describe in the second half are usually richer than the first-half answers. Cutting interviews short at 45 minutes loses the depth. + +The 90-minute upper bound. Beyond 90 minutes, fatigue degrades data quality. Schedule for 90; complete in 60-75; leave room for the depth without forcing it. + +--- + +## Job clustering from interview data + +After interviews, jobs emerge through clustering (per the synthesis sequence in `discovery-research-synthesis`). + +The clustering work. + +- Tag struggling moments and hire/fire decisions across interviews. +- Cluster moments that share underlying jobs (the user was trying to accomplish the same thing). +- Each cluster becomes a candidate job. +- Name the job from the cluster, not from a pre-built list. + +Common clustering patterns. + +- Multiple users described the same kind of friction in similar contexts. The cluster becomes one job. +- Multiple users described different surface-level frictions but the same underlying motivation and outcome. The cluster reveals a job that surfaces differently across users. +- One user's described moment is unique. May be an edge case, may be a job worth surfacing as smaller-segment. + +--- + +## Naming jobs from data + +Jobs are named from the cluster, not from a pre-built taxonomy. + +The naming process. + +- Read the cluster's contributing moments. +- Identify the situation, motivation, and outcome that recurred. +- Write the job statement: "When [situation], I want to [motivation], so I can [outcome]." +- Test the statement against the source moments: does it capture what users were trying to accomplish? + +The iteration discipline. First-pass job statements are usually too narrow or too broad; refine through iteration. + +Worked example. A cluster of moments around quarterly board prep: + +- Multiple users described assembling data from multiple sources. +- Multiple described uncertainty about whether they had the right slice. +- Multiple described the time pressure and the disruption to other work. +- Multiple described wanting to walk into the board with confidence. + +First-pass job statement: "When preparing the board deck, I want to assemble data from multiple sources, so I can present numbers correctly." + +Second-pass refinement: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The second pass captures the situation more specifically (quarterly business reviews, not just any board deck), the motivation more specifically (coherent narrative I can defend, not just data assembly), and the outcome more specifically (answer questions confidently without grinding the night before, not just present numbers correctly). + +--- + +## How many jobs emerge from typical discovery + +Strong discovery cycles often surface 3-8 jobs across the research batch. + +Smaller numbers (1-2 jobs). May indicate the discovery scope was narrow (only one user task investigated) or the synthesis under-clustered. + +Mid numbers (3-8 jobs). Typical for substantive discovery cycles. Jobs cover the major user motivations the research surfaced. + +Larger numbers (10+ jobs). May indicate over-clustering (each cluster is small and the overall synthesis is fragmented) or genuine breadth (the research investigated multiple distinct user contexts). + +The discipline. Job count should reflect the underlying patterns the data reveals, not a target number. Force-fitting to 7 jobs because "that feels right" produces synthesis that does not match the data. + +--- + +## Pairing JTBD discovery with quantitative validation + +Qualitative job patterns often warrant quantitative validation. + +The pattern. + +- Job statement claims a specific frequency or severity ("users hit this friction in 40% of attempts"). +- Quantitative data validates: analytics shows configuration step abandonment rate; survey data confirms the segment proportion; product instrumentation captures the in-the-moment frequency. +- If validation confirms: the job statement is strongly supported. +- If validation contradicts: revise the job statement to reflect the data. + +Pair with `experiment-design` for rigorous validation methodology and `product-analytics-setup` for the instrumentation that makes validation possible. + +--- + +## When JTBD discovery does not fit + +Some discovery does not benefit from JTBD framing. + +Greenfield categories. When the product is a category-defining product, users may not have struggling moments because the alternative is not having the capability at all. JTBD framing is useful but may need to be supplemented with broader product strategy. + +Highly novel use cases. When users have not yet developed mental models for the use case (e.g., new technology categories), struggling moments may not exist because the activity itself does not exist. Discovery may need to focus on adjacent activities and what users would do if the new capability existed. + +Pure positioning research. When the discovery is about how to position an existing product, hire and fire criteria interviews are useful, but emotional and social dimensions of positioning matter as much as the JTBD-framed jobs. + +The discipline. JTBD is a tool, not a mandate. When the discovery question fits the framework, use it. When it does not fit cleanly, supplement with other discovery techniques. + +--- + +## Common JTBD-discovery failures + +Eliciting feature lists instead of jobs. Interview prompts ask "what features do you want" rather than "what are you trying to accomplish." Restructure prompts. + +Pre-built job taxonomy. Researchers arriving with named jobs and slotting interview data into them. Jobs should emerge from data; pre-built taxonomies confirm what the team already thinks. + +Skipping struggling moments. Interviews capture preferences and use-cases without grounding in specific friction events. Add struggling-moment prompts. + +Skipping hire/fire decisions. Interviews ask about current usage but not about adoption or switch decisions. Add hire and fire prompts. + +Job statements written from intuition rather than data. Researchers writing jobs based on what they think users are trying to do, without grounding in interview clusters. + +Force-fitting all data to JTBD. Some interview data does not fit the JTBD framing cleanly; the team forces it in anyway. Better: surface what JTBD captures and supplement with other framings for the rest. + +--- + +## Methodology-level choices that stay in the public skill + +The interview structure that grounds in jobs. Prompts that work and fail. Interview length and depth. Job clustering from interview data. Naming jobs from data. Typical job counts. Pairing with quantitative validation. When JTBD discovery does not fit. Common failures. + +## Implementation choices that stay internal + +Specific interview templates. Specific recording and tagging tools. Specific synthesis tooling for job clustering. Specific recruitment criteria. The team's own conventions for interview cadence and batch sizing. These vary by team. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md new file mode 100644 index 0000000..8d40f19 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-positioning.md @@ -0,0 +1,201 @@ +# Applying JTBD to positioning + +Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pairs with `creative-direction` and `brand-discovery` for the broader positioning work. + +JTBD's contribution to positioning is the lead message: positioning that names the job the product helps users accomplish creates affinity in ways feature lists do not. The functional, emotional, and social dimensions of jobs all inform positioning differently. + +--- + +## Job-led vs feature-led positioning + +The two positioning approaches. + +Feature-led positioning. + +- "AI-powered analytics with collaborative dashboards and integrations." +- "Cloud-native CRM with automation and reporting." +- "Project management software with timelines, kanban, and integrations." + +Characteristics: lists features; competes on feature comparison; gets compared head-to-head with alternatives that have similar feature lists; produces buyer behavior of feature-checklist evaluation. + +Job-led positioning. + +- "Help product teams synthesize discovery research into decisions." +- "The CRM your sales team will actually use because it stays out of their way." +- "Run the project, not the project management tool." + +Characteristics: names what the product helps users accomplish; competes on outcome rather than feature parity; produces buyer behavior of job-fit evaluation; harder to copy because the positioning is built on understanding the job. + +The trade-off. Feature-led positioning is easier to write and easier for buyers to evaluate. Job-led positioning is harder to write but produces stronger affinity and is more durable to feature-parity competition. + +--- + +## When job-led positioning works + +Job-led positioning works best when: + +- The product addresses a job that users currently do badly with alternatives. +- The job has emotional or social dimensions that the positioning can serve. +- The user can recognize themselves in the job description. +- The market category is mature enough that feature comparison is no longer differentiating. + +Job-led positioning is less effective when: + +- The product is a new category and users do not yet recognize the job. +- The product is a commodity where job-fit is similar across alternatives. +- The buyer is not the user, and the buyer evaluates on different criteria than job-fit. + +--- + +## The lead message structure + +The lead message is the first thing prospects encounter (homepage hero, ad headline, sales pitch opener). + +Job-led lead message structure. + +- "[Product/category] for [user trying to do job in situation], so [outcome]." +- "[Action verb describing the job] without [the friction users currently encounter]." +- "[Outcome the product produces] for [user in situation]." + +Worked examples. + +- "Help product teams synthesize discovery research into decisions, not deck performance." +- "Run quarterly business reviews without spending Sunday night reconciling spreadsheets." +- "Onboard new engineers without becoming their full-time guide." + +Each example names a job, an outcome, and either a contrast (without the friction) or a quality (the way the product accomplishes the job). + +--- + +## Functional, emotional, social in positioning + +Positioning leans on different dimensions of the job for different effects. + +Functional dimension in positioning. + +- "[Product] does [job]." Direct and informative; lower-affinity. +- Worked example: "Synthesize discovery research from interview transcripts and support tickets." + +Functional dimension positioning is useful for product details, not for lead messages. Lead messages on functional alone compete on feature comparison. + +Emotional dimension in positioning. + +- "[Product] lets you do [job] feeling [desired emotional state]." +- Worked example: "Run discovery cycles feeling in control, not buried in transcripts." + +Emotional dimension positioning creates affinity. Users recognize the emotional state they want and connect with positioning that names it. + +Social dimension in positioning. + +- "[Product] for [user identity]." +- Worked example: "For PMs who run discovery seriously." + +Social dimension positioning creates identity affinity. Users want to belong to the kind of users the positioning describes. This dimension is often the strongest for positioning because it is hardest to copy and creates the most durable affinity. + +The composition. Strong positioning often combines all three dimensions: a functional lead with emotional and social undertones. "Run discovery cycles for PMs who take synthesis seriously, without burying yourself in transcripts." Functional (run discovery cycles), social (PMs who take synthesis seriously), emotional contrast (without burying yourself in transcripts). + +--- + +## Avoiding job-positioning that misses + +Job-led positioning fails when the named job does not match the user's actual situation. + +The pattern. Marketing crafts a job-led message that sounds compelling but does not match how target users describe their work. Users do not recognize themselves; the positioning underperforms. + +Worked failure example. A productivity SaaS positions as "Eliminate the chaos in your day." + +The pattern. The job named (eliminating chaos) is too abstract; users describe specific frictions ("I cannot find the right meeting notes when I need them; I spend 20 minutes a day reconciling calendar conflicts; I miss commitments because tasks are scattered across tools"). The positioning is generic; users cannot recognize their specific situation. + +The cure. Ground positioning in specific job statements that emerged from user research. The positioning should sound like users describing their own work, not like marketing describing users. + +--- + +## Positioning testing for JTBD-led messages + +Job-led positioning benefits from user testing. + +The test. Show the positioning to target users. Ask: + +- "Does this describe your work?" +- "Would you keep reading this?" +- "What product would you expect to be behind this positioning?" + +What good responses look like. + +- "Yes, that's exactly what I do." (positive recognition) +- "I would want to see what this is." (interest signal) +- "It sounds like a [accurate product description]." (the positioning communicates accurately) + +What bad responses look like. + +- "I'm not sure this applies to me." (mismatch) +- "It sounds generic." (not specific enough to the job) +- "I expect this to be a [different product type]." (positioning misleads) + +The iteration. Positioning often improves through 2-3 rounds of testing and revision. The ground-truth from target users surfaces the gap between what marketing wrote and what users recognize. + +--- + +## Positioning across multiple jobs + +Many products serve multiple jobs. Positioning must decide whether to lead with one job or surface multiple. + +Lead-with-one approach. + +- Pick the most differentiating, most strategically important job. +- Lead with that job in the primary positioning. +- Surface other jobs in secondary positioning (feature pages, segment-specific pages). + +Worked example. A productivity SaaS that serves task management, team coordination, and reporting jobs: + +- Primary positioning leads with team coordination (the most strategic, most differentiating job). +- Feature pages address task management for users who land there. +- Reporting positioning lives on a dedicated page for evaluators looking specifically for that job. + +Lead-with-many approach. + +- The product genuinely serves several jobs equally; leading with one would mislead. +- Use a multi-job message: "[Product] for [job A], [job B], and [job C]." +- Risk: looks like a feature list dressed in job language. + +The discipline. Most products benefit from leading with one job and supplementing. Lead-with-many positioning often collapses into "do everything" messaging that creates no specific affinity. + +--- + +## Positioning for jobs vs positioning for users + +JTBD positioning leads with jobs; persona positioning leads with user identity. + +Job-led positioning. "Help product teams synthesize discovery research into decisions." + +Persona-led positioning. "For senior product managers at high-growth SaaS companies." + +The two can compose. Strong positioning often pairs job and identity: "Help senior PMs at high-growth SaaS companies synthesize discovery research into decisions." + +The discipline. Lead with the job (what the user is trying to do); add identity (who the user is) to create the affinity layer. Identity-only positioning is persona theater; job-only positioning may not create enough affinity. Job + identity is often the strongest form. + +--- + +## Common JTBD-positioning failures + +Job-led messages that are too abstract. "Eliminate the chaos in your day" is job-flavored but does not name a specific job. Replace with the specific job from research. + +Feature-led messages dressed in job language. "Use our analytics to make better decisions" is feature-led; "make better decisions" is too generic to be a job. + +Job-led positioning that does not match user vocabulary. Marketing wrote the positioning without grounding in user research; users do not recognize the language. + +Lead-with-many positioning that becomes "do everything." Multiple jobs surfaced equally; positioning loses specificity. + +Positioning ignores the social dimension. Strong positioning often leans on social dimension; positioning that omits it competes only on functional and emotional. + +Positioning not user-tested. Marketing crafts the positioning in isolation; target users have not validated that they recognize themselves in it. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led vs feature-led distinction. When job-led works and does not. The lead message structure. Functional, emotional, social in positioning. Avoiding job-positioning that misses. Positioning testing methodology. Positioning across multiple jobs. Job vs persona positioning. Common failures. + +## Implementation choices that stay internal + +Specific positioning frameworks the team uses. Specific copy templates. Specific A/B testing setups for positioning variants. Specific user-testing methodologies. The team's own conventions for primary vs secondary positioning. These vary by team and brand discipline. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md new file mode 100644 index 0000000..57c1a53 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md @@ -0,0 +1,206 @@ +# Applying JTBD to prioritization + +Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. The framing that cuts through feature-list politics. + +JTBD's contribution to prioritization is grounding the debate in user motivation rather than feature requests or stakeholder volume. Pairs with `roadmap-planning` for the broader prioritization discipline. + +--- + +## The job-led prioritization frame + +Each roadmap candidate gets evaluated by the jobs it addresses. + +The questions. + +- Which jobs is the product currently doing badly? +- Which roadmap candidates address those jobs vs adjacent or unrelated work? +- Which jobs matter most to the product's strategy and user base? +- What is the cost of addressing each candidate vs the value of the job improvement? + +Why this frame works. + +- It grounds prioritization in what users are trying to accomplish, not in what features they happen to have requested. +- It cuts through stakeholder politics: a roadmap candidate's value is measured against jobs, not against who is requesting it. +- It makes "we should not build this" defensible: candidates that do not address a load-bearing job get deprioritized clearly. + +The compose-with-strategy discipline. Job-led prioritization is downstream of strategy. The team needs to know which jobs matter for the product's market position; not all jobs are equally strategic. Pair with broader strategy work for the upstream framing. + +--- + +## Identifying jobs the product does badly + +The starting point for job-led prioritization. + +The methodology. + +- For each major job the product is meant to serve, evaluate how well it currently does the job. +- Use multiple inputs: user research (struggling moments, fire criteria), support data (where users hit friction), competitive analysis (where alternatives are stronger), in-product analytics (where users abandon). +- Score or rank jobs by how well they are currently served. Jobs done badly are candidates for prioritization investment. + +Worked example. A team productivity SaaS evaluating four core jobs: + +- Job A (creating tasks): well-served. Low priority for new investment. +- Job B (collaborating on tasks across teams): partially served. Some friction; alternatives are stronger; users describe workarounds. +- Job C (reporting on team progress): poorly served. High struggling-moment frequency; users export to spreadsheets; competitive products do this better. +- Job D (integrating with external tools): partially served. Friction at scale; mid-size customers describe pain. + +The badly-served jobs (B, C, D) are candidates for prioritization. Job A is not a fertile area for new investment. + +--- + +## Mapping roadmap candidates to jobs + +Each roadmap candidate gets associated with the jobs it addresses. + +The mapping. + +- Roadmap candidate: "Build cross-team task assignment with permissions." + - Job addressed: Job B (collaborating across teams). + - Job impact: addresses the core friction users describe; closes the gap with stronger alternatives. + +- Roadmap candidate: "Add custom report builder." + - Job addressed: Job C (reporting on team progress). + - Job impact: enables the reporting users currently export to spreadsheets to do. + +- Roadmap candidate: "Build mobile app for task creation." + - Job addressed: Job A (creating tasks) on mobile context. + - Job impact: extends a well-served job to a context where it currently is not served. Useful but not addressing a struggling job. + +- Roadmap candidate: "Redesign sidebar navigation." + - Job addressed: unclear. Possibly across multiple jobs. + - Job impact: hard to evaluate without clarification on which job this serves. + +The fourth example signals a problem. Roadmap candidates that do not clearly address a specific job often get prioritized on internal preferences rather than user value. The job mapping forces clarity: what job does this candidate serve, and how badly is that job currently being done? + +--- + +## The "no job, no priority" discipline + +Roadmap candidates that do not clearly address a job tied to user motivation often should not be prioritized. + +The pattern. + +- Candidate: "Migrate to a new internal framework." + - Job addressed: none directly; serves engineering velocity. + - Disposition: may be valuable for engineering reasons; do not prioritize on user-job grounds. If the team values engineering velocity, prioritize it on that basis explicitly. + +- Candidate: "Add dark mode." + - Job addressed: weak (some users describe preference). + - Disposition: low job-priority unless dark mode addresses an emotional dimension of jobs the team is also addressing. + +- Candidate: "Improve admin permissions." + - Job addressed: depends on which segment is asking. For enterprise: addresses fire criteria around compliance. For small teams: weak job impact. + - Disposition: prioritize for the segment whose job it serves; do not generalize. + +The discipline. Surface the job each candidate addresses (or does not). Candidates that do not serve jobs may still be valuable but should be prioritized on different grounds. The candidates the team can defend on jobs are the ones with the clearest user-value case. + +--- + +## Prioritization across jobs + +Different jobs have different strategic weights. The roadmap should reflect the strategy. + +The questions. + +- Which jobs are most load-bearing for the product's market position? +- Which jobs are most differentiated from competitors? (Where addressing the job better produces lasting advantage.) +- Which jobs serve the segments the strategy is targeting? +- Which jobs are growing in importance based on market trends? + +Worked example. A team productivity SaaS in mid-market growth: + +- Job B (cross-team collaboration): high strategic weight. Mid-market customers grow into multi-team workflows; the product needs to scale with them. +- Job C (reporting): high strategic weight. Mid-market customers need reporting that small-team customers did not require. +- Job D (integration): medium strategic weight. Important for retention; less differentiating than B and C. +- Job A (task creation): low strategic weight for new investment. Already served; not where competitors are winning. + +The strategic weighting biases the roadmap: B and C get more capacity than D; D gets more than A. + +--- + +## The "what job is this serving" review for in-flight work + +Job-led prioritization applies to existing work, not just new candidates. + +The review. + +- Take in-flight roadmap items. +- For each, ask: what job is this serving? How well does the work address that job? +- Items that cannot articulate a clear job may be candidates for re-scoping or cancellation. + +The honest case. Many roadmap programs accumulate work that started for reasons unrelated to user jobs (engineering preference, executive request, "we said we would"). The job review surfaces these and creates space to reconsider. + +The kindness. The review is not aimed at blame; sometimes work was committed before the team had the JTBD framing. The cure is reconsidering, not punishing. + +--- + +## Avoiding the JTBD-prioritization-religion failure + +JTBD as prioritization framework can become rigid in ways that hurt the team. + +Patterns to avoid. + +- Mandatory job-mapping for every roadmap item, including small bug fixes. The framework becomes overhead for low-value items. +- Treating job-impact estimates as precise numbers. Job-impact is often qualitative; pretending precision misleads. +- Over-weighting JTBD to the exclusion of other prioritization inputs. Strategic, technical, and operational considerations matter alongside jobs. + +The discipline. Use JTBD where it adds clarity to prioritization debates. Do not force the framework where it adds overhead without value. + +--- + +## Worked prioritization example + +A quarterly roadmap review at a team productivity SaaS. + +Available capacity. 5 large initiatives. + +Candidates with job mapping. + +1. Cross-team task assignment with permissions (Job B; high impact; high strategic weight). +2. Custom report builder (Job C; high impact; high strategic weight). +3. Mobile app for task creation (Job A on mobile; medium impact; low strategic weight). +4. Sidebar redesign (no clear job; serves general usability). +5. Slack integration upgrade (Job D; medium impact; medium strategic weight). +6. Onboarding redesign (multiple jobs; high impact on hire criteria for new customers). +7. Admin role overhaul (Job D for enterprise; high impact for that segment; matches enterprise expansion strategy). +8. Migration to new search backend (technical; serves multiple jobs indirectly). + +Prioritization decision (5 of 8). + +- Cross-team task assignment (1): yes. Top job priority. +- Custom report builder (2): yes. Top job priority. +- Onboarding redesign (6): yes. High hire-criteria impact. +- Admin role overhaul (7): yes. Enterprise strategy alignment. +- Migration to new search backend (8): yes. Technical foundation; serves multiple jobs. + +Deferred. + +- Mobile app for task creation (3): Job A is well-served on desktop; mobile is convenient but not high-priority. +- Sidebar redesign (4): no clear job. Reconsider for next cycle if a specific job emerges. +- Slack integration upgrade (5): Job D is medium-priority; can wait a quarter. + +The defense. The decisions can be explained on jobs and strategy. Stakeholders who pushed for items that did not make the cut can hear a clear rationale. The cut items can be reconsidered next quarter against jobs at that point. + +--- + +## Common JTBD-prioritization failures + +Job-mapping all candidates without segmenting strategic weight. Jobs treated as equal; the team picks based on impact estimates that obscure which jobs actually matter for strategy. + +No job assigned to many candidates. The team treats job mapping as optional; non-mapped candidates get prioritized on volume of requests or stakeholder preference. + +Job-impact precision theater. Numerical scores for job impact (Job B: 8/10) when the underlying assessment is qualitative. Decisions look quantitative but are not. + +Forcing all decisions through JTBD. Some decisions (technical migrations, strategic bets) do not benefit from JTBD framing. Force-fitting produces bad decisions. + +JTBD as cover for predetermined prioritization. The team ranks items by JTBD theater after deciding what to prioritize on other grounds. The framework becomes documentation rather than decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led prioritization frame. Identifying jobs done badly. Mapping candidates to jobs. The "no job, no priority" discipline. Strategic weighting across jobs. The in-flight work review. Avoiding JTBD-religion. Worked prioritization example. Common failures. + +## Implementation choices that stay internal + +Specific roadmap-tracking tools. Specific scoring rubrics for job impact. Specific stakeholder-review formats. Specific job-strategic-weight reviews. The team's own conventions for prioritization meetings. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md b/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md new file mode 100644 index 0000000..a36a25e --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/common-jtbd-failures.md @@ -0,0 +1,166 @@ +# Common JTBD failures + +Nine-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most JTBD failures share a single root, which is treating JTBD vocabulary as a substitute for analytical work. + +--- + +## Failure 1: We did the JTBD workshop but nothing changed in our roadmap + +Symptom. A workshop was held. Job statements were produced. The wall has Post-its. The next quarter's roadmap looks the same as the prior quarter's. + +Diagnosis. Job-statement workshop as deliverable. The workshop became the artifact; the analytical work that should have followed never happened. + +Cure. Treat job statements as analytical input, not as workshop output. Re-evaluate roadmap candidates against the jobs. Apply the "no job, no priority" discipline. The roadmap should look different than it would have looked without the JTBD work; if it does not, the work is ritual. + +Prevention. Do not run JTBD workshops as standalone events. Pair the workshop with prioritization or positioning work that uses the job statements as input. Without downstream application, the workshop produces ritual. + +--- + +## Failure 2: Our job statements all sound the same + +Symptom. Multiple job statements share similar situations, motivations, or outcomes. They are hard to distinguish. + +Diagnosis. Generic job statements; not grounded in specific struggling moments. The statements were written from intuition rather than from interview data. + +Cure. Re-ground in interview data. Each job should be traceable to specific moments in specific interviews. Statements that cannot be traced are projections; rewrite from the ground up. + +Prevention. Job statements emerge from clustering, not from whiteboard sessions. The clustering work surfaces the distinctions; whiteboard sessions tend to produce homogeneous statements. + +--- + +## Failure 3: Our jobs read like feature requests + +Symptom. Job statements describe what users want from the product, not what users are trying to accomplish. + +Examples that fail. + +- "When using the dashboard, I want to see all my metrics on one screen." +- "When in the settings page, I want to configure permissions easily." + +The motivations and outcomes describe product features, not job-doing. + +Diagnosis. Product-bound job statements. The motivation is bound to the product; the outcome is feature output. + +Cure. Apply the product-independence test. The motivation should make sense without naming any specific product. If the user is "in the dashboard," they are using a product; the underlying job is what they are trying to accomplish that brought them to the dashboard. + +Prevention. During job-statement writing, check each statement: could this make sense if the user had no product to use? If no, rewrite the motivation and outcome to describe the underlying job. + +--- + +## Failure 4: We have personas and jobs and they contradict each other + +Symptom. The team has both demographic personas and JTBD job statements. Decisions get made differently depending on which framework the conversation invokes. + +Diagnosis. Personas are demographic; jobs are situational. They serve different purposes. Conflict often signals confusion about which framework drives which decisions. + +Cure. Decide the role of each framework. JTBD is usually better for product decisions (what to build, how to prioritize); demographic personas are sometimes useful for marketing audience targeting (who to advertise to). Use each where it adds clarity; do not require both for every decision. + +Prevention. When introducing JTBD, surface the relationship to existing personas. If personas are not driving decisions, consider deprecating them. If personas are useful for specific marketing work, keep them but separate from product decision-making. + +--- + +## Failure 5: JTBD says we should build everything + +Symptom. Job statements identify many job-improvement opportunities. The team cannot pick. The roadmap becomes a list of all the jobs to address. + +Diagnosis. Without prioritization across jobs, JTBD identifies opportunities but does not pick. The framework is doing its discovery work; it is not doing prioritization work. + +Cure. Pair JTBD with strategic weighting (which jobs matter most for the strategy?), capacity constraints (what can the team actually deliver?), and impact estimation (which job improvements move the needle most?). JTBD informs prioritization but does not replace prioritization frameworks. + +Prevention. When applying JTBD to roadmap prioritization, surface the strategic-weight question explicitly. Some jobs matter more than others; the team's strategy decides which ones. + +--- + +## Failure 6: We dropped JTBD because it became theater + +Symptom. The team adopted JTBD; produced workshop artifacts; never used them in decisions; and concluded JTBD does not work. + +Diagnosis. JTBD as ritual produced ritual. The framework was applied without the analytical work. + +Cure. Reintroduce JTBD as analytical tool, not as ritual. Apply where it earns its keep (discovery, prioritization, positioning). Skip the artifacts that decorate without informing decisions. Demonstrate the value through specific decisions JTBD informed. + +Prevention. When introducing JTBD, frame it as a tool for specific decisions, not as a methodology to be adopted org-wide. Start with one application (one discovery cycle, one prioritization debate) and show value before expanding. + +--- + +## Failure 7: Our job statements are functional only + +Symptom. Job statements describe mechanical tasks. The product strategy prioritizes functional features. The product wins on functional dimension and loses to alternatives on emotional and social. + +Diagnosis. Functional-only synthesis. The interview prompts and synthesis stayed at the functional dimension; emotional and social dimensions were not surfaced. + +Cure. Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing job statements. Re-evaluate strategy considering all three dimensions. + +Prevention. Interview structure should explicitly prompt for all three dimensions. Synthesis should surface all three. Single-dimension job statements are usually a sign that prompts or synthesis missed dimensions. + +--- + +## Failure 8: We cannot agree on the job + +Symptom. Different team members describe the user's job differently. The team debates the framing; the framing does not converge. + +Diagnosis. Often signals different segments with different jobs. The team is right that there is more than one job; they are wrong to think there should be one consensus job. + +Cure. Surface the segment differences. The same product may serve different jobs for different segments. Naming the segments and their distinct jobs resolves the disagreement and improves strategy. + +Prevention. When defining jobs, ask explicitly: do all target users share this job, or does it differ across segments? Often the answer is "differs"; surface the segments rather than forcing consensus. + +--- + +## Failure 9: Our marketing copy uses JTBD vocabulary but our product does not + +Symptom. Marketing positioning describes the job the product helps users accomplish. The product itself is built around feature-list thinking. Users adopt expecting one experience and encounter another. + +Diagnosis. Positioning-product gap. The marketing claim is not load-bearing in product decisions; product decisions are still made on feature-list grounds. + +Cure. Either align product decisions to the JTBD positioning (apply JTBD to prioritization), or revise the positioning to match what the product actually does. The mismatch erodes trust over time. + +Prevention. When introducing JTBD-led positioning, simultaneously apply JTBD to product strategy. Positioning that describes what the product is becoming should drive what the product becomes. + +--- + +## Failure 10: JTBD vocabulary substituted for analytical work + +Symptom. The team uses JTBD language ("the job," "struggling moment," "hire criteria") in conversations but cannot trace decisions to specific JTBD analyses. + +Diagnosis. Vocabulary without analysis is ritual. The framework provides language; the language does not produce decisions on its own. + +Cure. Audit recent decisions: which were grounded in JTBD analysis (specific job statements, specific hire/fire criteria, specific user research)? Which used JTBD vocabulary as decoration around decisions made on other grounds? Re-anchor in analytical work. + +Prevention. When the team uses JTBD vocabulary, surface the underlying analytical work explicitly. "What job is this serving?" should produce a specific job statement traceable to research, not a hand-wavy answer. + +--- + +## Failure 11: Force-fitting JTBD where it does not help + +Symptom. Every product question gets framed in JTBD. Even questions where the framing adds no clarity. + +Diagnosis. JTBD as mandate. The framework gets applied universally; tax for the team; signal-to-noise drops. + +Cure. Use JTBD where it earns its keep. Some questions (technical migrations, infrastructure decisions, urgent bug fixes) do not benefit from JTBD framing. Apply other frameworks where they fit better; apply JTBD where it fits. + +Prevention. Establish that JTBD is one tool among many. Frame the question first; then pick the framework. Do not start with the framework and look for questions to apply it to. + +--- + +## The cross-cutting pattern + +Most JTBD failures share a single root: treating JTBD vocabulary as a substitute for analytical work. + +The vocabulary is easy: "job," "struggling moment," "hire criteria," "fire criteria," "functional, emotional, social dimensions." Teams adopt the vocabulary and signal that they have adopted JTBD. + +The analytical work is hard: structured interviews, struggling-moment grounding, clustering across users, naming jobs from data, surfacing all three dimensions, applying the framework to specific decisions, validating that the analysis informs decisions. + +When the vocabulary is adopted without the analytical work, JTBD produces ritual. When the analytical work is done with discipline, JTBD produces decisions and the vocabulary is incidental. + +The fix for almost any JTBD failure starts with the same question: where is the analytical work happening, and what decisions is it informing? If the answers are clear, the framework is doing its job. If the answers are vague, the framework is ritual. + +--- + +## Methodology-level choices that stay in the public skill + +The eleven failure patterns with diagnoses and cures. The cross-cutting vocabulary-vs-analysis pattern. The discipline of using JTBD where it earns its keep. + +## Implementation choices that stay internal + +Specific JTBD-application audits. Specific reviewer training on failure detection. Specific tooling that surfaces JTBD ritual vs analytical use. The team's own conventions for catching ritual before it spreads. These vary by team. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md b/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md new file mode 100644 index 0000000..4460b0b --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/functional-emotional-social-dimensions.md @@ -0,0 +1,201 @@ +# Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. The omission of emotional and social dimensions is one of the most common JTBD failure modes. + +--- + +## The three dimensions + +### Functional + +What the user is mechanically trying to accomplish. + +Worked examples. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." +- "Prepare a customer-facing announcement for a feature launch." +- "Reconcile vendor payments at month-end." + +Characteristics. + +- Describable in task language. +- Often the easiest dimension to surface in interviews. +- Often the dimension product teams default to. + +--- + +### Emotional + +How the user feels (or wants to feel) doing the job. + +Worked examples. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." +- "Comfortable that the announcement will not surprise anyone in a way that lands badly." +- "Confident that the reconciliation is correct without spending the whole week verifying." + +Characteristics. + +- Describes the user's internal experience. +- Often surfaces through how users describe what went well or badly. +- Distinguishes products that feel good to use from products that work mechanically but feel exhausting. + +--- + +### Social + +How the user wants to be perceived doing the job. + +Worked examples. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." +- "Seen by customers as transparent and proactive, not evasive." +- "Seen by audit as someone whose work the team can trust without re-checking." + +Characteristics. + +- Describes how the user wants others to perceive their work. +- Often the most overlooked dimension. +- Drives positioning more than the other two dimensions. + +--- + +## Why three dimensions matter + +Products that win on functional alone often lose to alternatives that also serve emotional and social. + +Worked example. Two analytics tools serving the same functional job. + +- Tool A: technically thorough, full-featured, hard to learn, intimidating-feeling. Functional excellence; weak emotional dimension. +- Tool B: focused on the specific job, faster to confidence, feels manageable. Slightly less functional power; stronger emotional dimension. + +For users who could complete the job with either, Tool B often wins. The emotional dimension (feeling in control, confidence) tipped the decision even though Tool A's functional dimension was technically stronger. + +Worked example, social dimension. A board reporting tool serving CFOs. + +- Tool A: produces correct numbers; layout is utilitarian. +- Tool B: produces the same numbers; layout signals "this CFO knows their numbers" through design. + +The social dimension (how the CFO is perceived presenting from this tool) tips many decisions. Tool B is hired in part because it makes the CFO look good in front of the board. + +--- + +## Surfacing emotional and social dimensions in interviews + +Emotional and social dimensions often surface only when the interview prompts for them. + +Functional prompts. "Walk me through the task. What did you do?" + +Emotional prompts. "How did you feel doing this? What was the most stressful part? When did you feel relieved?" + +Social prompts. "Who else was watching this work? How did you want to come across to them? What did you do specifically because of how it would look?" + +The interview discipline. Surface all three dimensions; do not assume the functional dimension is the whole job. Many users will not volunteer emotional or social dimensions; the prompts surface them. + +--- + +## When functional alone is sufficient + +Some jobs are dominantly functional and the emotional/social dimensions are minor. + +Worked example. A backup utility that runs in the background. The functional dimension (data is backed up correctly) is the whole job; the user does not have an emotional relationship with the tool and is not perceived doing it. + +The discipline. Some products are appropriately functional-only. The team's job is to recognize when the dimensions matter and when they do not. Force-fitting emotional and social dimensions onto purely functional jobs produces false signal. + +--- + +## Functional-only failure mode + +The most common JTBD failure: surfacing only the functional dimension. + +The pattern. Job statements describe what the user is mechanically doing; the team prioritizes functional features; the product wins on functional excellence and loses on emotional and social. + +The cure. Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing jobs. Re-evaluate strategy considering all three dimensions. + +The signal. Products that are technically excellent but lose to "lesser" alternatives often have an emotional or social dimension the strategy missed. Investigate. + +--- + +## Emotional dimension and product feel + +The emotional dimension shows up in product feel: the way using the product makes users feel. + +Examples of emotional dimensions in product design. + +- A complex configuration interface vs a guided wizard. Both can be functionally equivalent; the wizard often serves the emotional dimension of "feeling in control rather than overwhelmed." +- An error message that explains and offers recovery vs one that just reports the failure. Both can be technically accurate; the explaining one serves the emotional dimension of "feeling supported rather than stuck." +- A success state that celebrates the milestone vs one that proceeds silently. Both can be functionally complete; the celebrating one serves the emotional dimension of "feeling progress rather than grinding." + +The discipline. Product designers often instinctively address emotional dimensions; the JTBD work makes this explicit and prioritizable. Emotional dimension can be a deliberate strategy choice rather than a designer's intuition. + +--- + +## Social dimension and positioning + +The social dimension informs positioning more than the other dimensions. + +Examples of social dimensions in positioning. + +- "Used by senior engineers at companies that ship reliable software." (positions the user as a senior engineer at a reliable company.) +- "The board reporting tool CFOs at high-growth startups trust." (positions the CFO as someone who works for a high-growth startup.) +- "Built for product teams that ship every week." (positions the product manager as part of a high-velocity team.) + +Why social dimension is positioning-relevant. + +- Users want to be perceived as belonging to the kind of teams the positioning describes. +- Positioning that names the social dimension creates affinity; positioning that names only functional features competes on feature comparison. +- The social dimension is durable; functional dimensions can be matched, social dimensions are harder to copy. + +The discipline. Positioning work should explicitly identify the social dimension of the jobs the product serves. Positioning that ignores social dimension misses one of the strongest tools available. + +--- + +## Worked synthesis combining all three dimensions + +A job statement enriched with all three dimensions: + +Job: "When my team is rolling out a new feature and I need to communicate it to customers, I want to write a clear announcement that explains what changed and why it matters, so I can ship the rollout without flooding support with confusion." + +Functional dimension: Write the announcement, distribute it to customers, prepare support for incoming questions. + +Emotional dimension: Confident that the announcement will land well, not anxious that it will trigger a wave of confused tickets, in control of the rollout rather than reactive to its fallout. + +Social dimension: Seen by the team as someone who handles rollouts smoothly, seen by customers as a brand that communicates clearly about changes, seen by support team as someone whose announcements reduce their workload rather than create it. + +Product implications. A tool that helps with this job needs to: + +- Functionally: support drafting, distribution, and support-team coordination. +- Emotionally: provide confidence-inducing review (preview tools, sentiment checks, changelog patterns). +- Socially: produce announcements that carry the brand voice the user wants associated with their rollouts. + +The three-dimensional analysis surfaces product needs the functional analysis alone would miss. + +--- + +## Common dimension-related failures + +Functional-only synthesis. Job statements describe mechanical tasks; strategy prioritizes functional features; product loses on feel. + +Decorative emotional dimension. Adding "feels good" without specifying which emotional state the product should support. The dimension exists on paper but does not drive design decisions. + +Missing social dimension. Strategy and positioning work that ignores how users want to be perceived. Positioning ends up generic; product fails to create affinity. + +Force-fitting all three to every job. Some jobs are functional-dominant. Adding emotional and social dimensions where they do not matter produces noise. + +Treating dimensions as separate jobs. Functional, emotional, and social dimensions are aspects of the same job, not separate jobs. Treating them separately produces fragmented strategy. + +--- + +## Methodology-level choices that stay in the public skill + +The three dimensions and their characteristics. Worked examples per dimension. Interview prompts per dimension. The functional-only failure mode. Emotional dimension and product feel. Social dimension and positioning. Worked three-dimensional synthesis. Common failures. + +## Implementation choices that stay internal + +Specific interview prompt templates per dimension. Specific synthesis templates that capture all three. Specific design-review patterns that check for emotional dimension. Specific positioning frameworks that lead with social dimension. These vary by team and design practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md b/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md new file mode 100644 index 0000000..d3aee67 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/hire-and-fire-criteria.md @@ -0,0 +1,189 @@ +# Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground JTBD in real decisions users make. + +Hire and fire criteria are the JTBD methodology's most actionable contribution to product strategy. They surface what the product needs to be excellent at to win adoption (hire) and what the product needs to maintain to retain users (fire). The two are often different; products that win on hire criteria can lose on fire criteria. + +--- + +## Hire criteria + +What makes a user adopt a product. + +The components. + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +Worked example. A PM user adopting a new analytics tool: + +- Struggling moment: "I was spending hours every week assembling product metrics from three different sources before standup, and I was always uncertain whether I had the right slice." +- Alternatives considered: "Continued the manual spreadsheet approach. Tried to extend the existing BI tool. Considered building an internal dashboard." +- Why this product won: "It connected to all three sources out of the box, the slice I needed was a 30-second config, and the team could share the same view." +- Expected job output: "I would walk into standup with the metrics ready, with no manual reconciliation work the night before." + +The discovery prompt. "Tell me about the moment you decided to start using [product]. What were you doing before? What made you switch?" + +--- + +## Fire criteria + +What makes a user switch away. + +The components. + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +Worked example. A PM user switching away from an analytics tool: + +- Struggling moment: "Once we hit cross-source aggregations the basic config could not handle, I was back to manual workarounds." +- Alternative looking better: "A team I respect started using a different tool that handled cross-source natively." +- Tipping point: "When I had to rebuild a report three weeks in a row because the workaround broke whenever the source schemas changed." +- Failed job output: "The 30-second-config promise did not hold for the analyses that mattered most." + +The discovery prompt. "If you switched away from [product] tomorrow, what would the trigger be? What would the alternative need to do that [product] does not?" + +For users who have actually switched: "What was the moment you decided to switch away?" + +--- + +## Why hire and fire are often different + +Hire criteria reveal what the product needs to be excellent at to win adoption. Fire criteria reveal what the product needs to maintain to retain users. The asymmetry is consequential. + +Examples of the asymmetry. + +- A product that wins adoption with a fast onboarding (hire criterion) can lose users to depth limitations once they get past onboarding (fire criterion). The product needs both: fast onboarding AND depth that handles harder cases. +- A product that wins adoption with a single integration (hire criterion) can lose users when their tooling stack expands and the product does not keep up (fire criterion). The product needs both: a strong landing integration AND breadth as users grow. +- A product that wins adoption with a low price (hire criterion) can lose users when their budget expands and competitors offer more value at higher tiers (fire criterion). The product needs both: accessible entry AND value at higher tiers. + +The implication. Strategy work that focuses only on hire criteria builds for adoption. Strategy work that focuses only on fire criteria builds for retention. Mature strategy addresses both, often through different parts of the product or different lifecycle stages. + +--- + +## Recent-switch interview discipline + +Users who recently switched (in either direction) are particularly rich for JTBD interviews. + +Why recent switches matter. + +- The user remembers the specific moment of the switch decision; older switches get smoothed into abstractions. +- The user remembers the alternatives they considered, the criteria they used, the moment of tipping. +- The data is grounded in real decisions, not hypothetical preferences. + +The recruiting target. Users who switched in the last 30-90 days are the highest-value recruits for hire/fire interviews. Users who switched 6+ months ago provide weaker data. + +The interview structure. + +- Walk through the situation that prompted the switch consideration. +- Identify the alternatives evaluated. +- Surface the criteria the user used to evaluate. +- Identify the tipping moment. +- Compare expected vs realized outcomes after the switch. + +--- + +## Hire and fire across segments + +Different segments often have different hire and fire criteria. + +Worked example. A team productivity SaaS: + +- Small-team segment: hire criterion is "fast setup; works without admin"; fire criterion is "team grew and the product feels limiting." +- Mid-size segment: hire criterion is "supports our existing roles and permissions"; fire criterion is "missing reporting and audit features as we standardize." +- Enterprise segment: hire criterion is "compliance and security pass our review"; fire criterion is "vendor responsiveness during incidents." + +The discipline. Surface segment differences in hire and fire criteria explicitly. A product that wins on small-team hire criteria but loses on mid-size fire criteria has a known retention pattern that strategy must address. + +--- + +## The "why didn't you switch sooner" question + +A specific prompt that reveals the friction barrier to switching. + +The prompt. "Looking back, why didn't you switch sooner?" + +What it surfaces. + +- The switching cost the user had to overcome (data migration, team retraining, contract obligations). +- The alternatives that almost won earlier but did not (and why). +- The accumulated frustration that finally broke through the inertia. + +Why it matters. + +- High switching costs protect incumbents. Users tolerate friction longer when switching is expensive. +- The pattern of frustration accumulation reveals which fire criteria are load-bearing (the ones users finally cannot tolerate). +- The almost-won alternatives reveal what would have been compelling enough earlier. + +--- + +## Hire and fire criteria for non-switching users + +Not every user has switched. Some users are at the start of their relationship with the product; others have used it for years without considering alternatives. + +For new users: focus on hire criteria. The recent decision is the adoption decision; the fire criteria are hypothetical. + +For long-tenured users: focus on fire criteria. The hypothetical "what would make you switch" reveals the latent fire criteria even without a switch event. The product can use these to address fire risks before they become switch events. + +For users who tried and abandoned: rich data. They evaluated, found the product wanting, and stuck with the prior alternative. The reasons reveal both hire criteria the product failed and fire criteria for the alternative they kept. + +--- + +## Patterns across hire criteria + +Common patterns in hire criteria across product domains. + +Speed-to-value. Users hire products that get them to first value quickly. Long onboarding loses adoption races; fast onboarding wins. + +Specific job fit. Users hire products that look like they will solve the specific job. Generic products that "could be used for many things" lose to specific products that "solve this exact problem." + +Confidence in continuity. Users hire products they trust will be there in 2 years. Established products win on this; startups have to compensate with other criteria. + +Workflow continuity. Users hire products that fit their existing workflows. Products that demand workflow change face higher hire bars. + +Recommendation chain. Users hire products that someone they trust recommended. Word-of-mouth is often a stronger hire criterion than feature comparison. + +--- + +## Patterns across fire criteria + +Common patterns in fire criteria across product domains. + +Reliability degradation. Users fire products that become unreliable. A product that ships bugs faster than it ships fixes loses users. + +Scaling friction. Users fire products that get harder to use as they grow. The product that was great for 5 users may be painful at 50. + +Vendor responsiveness. Users fire products whose vendors stop responding. Support quality, account management, and incident response all matter. + +Pricing trajectory. Users fire products whose pricing escalates faster than the value they get. Enterprise tiers that gate basic functionality drive fire decisions. + +Competitive pressure. Users fire products when alternatives reach feature parity plus advantage. Products that stop innovating lose to products that overtake them. + +--- + +## Common hire-and-fire failures + +Asking only about hire. The team interviews about adoption decisions but never about switch decisions. The strategy biases toward adoption; retention concerns surface late. + +Asking only about fire. The team focuses on churn analysis without understanding hire criteria. New customer acquisition struggles because the team does not know what wins adoption. + +Treating hire and fire as the same. The team assumes the criteria match. Strategy ends up optimized for hire-with-no-fire-attention or vice versa. + +Hypothetical-only fire data. Long-tenured users describing what they "would" switch over. Useful but weaker than real-switch data. + +Ignoring segment differences. Hire and fire criteria collapsed across segments. Strategy that works for one segment fails for another. + +--- + +## Methodology-level choices that stay in the public skill + +The hire and fire criteria components. Why they are often different. The recent-switch interview discipline. Hire and fire across segments. The "why didn't you switch sooner" question. Hire and fire for non-switching users. Patterns across hire and fire criteria. Common failures. + +## Implementation choices that stay internal + +Specific interview templates for hire and fire interviews. Specific recruitment criteria for recent switchers. Specific synthesis tooling for hire and fire data. The team's own conventions for hire-fire balance in strategy work. These vary by team and research practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md b/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md new file mode 100644 index 0000000..a7e8590 --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/identifying-struggling-moments.md @@ -0,0 +1,176 @@ +# Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when alternatives feel inadequate, when they would prefer a different way of doing the job. + +The struggling moment is the JTBD methodology's most direct contribution to discovery research. Most discovery interviews surface preferences and feature requests; well-structured JTBD interviews surface struggling moments, which produce richer data and clearer jobs. + +--- + +## What a struggling moment is + +A specific moment in time when: + +- The user encountered friction in trying to accomplish something. +- The current approach failed them or felt inadequate. +- They considered or wished for an alternative. +- They built a workaround or accepted suboptimal output. + +Strong struggling-moment examples. + +- "Last Tuesday I lost an hour assembling the board metrics from three different dashboards because none of them had the slice I needed. I ended up exporting CSVs and combining them manually, and then second-guessing whether I had pulled the right data." +- "When the customer escalation came in at 9pm, I was at dinner and tried to triage from my phone, but the support tool's mobile experience was unusable. I had to go back to my laptop and the whole evening was disrupted." +- "Last quarter I spent the whole onboarding week pair-programming with the new engineer because our docs assumed knowledge they did not have, and I could not point them anywhere that would work without me there." + +Each example names a specific time, a specific friction, and the workaround or impact. + +Weak struggling-moment examples. + +- "I wish dashboards were better." (general; not a moment) +- "It would be nice if the support tool was more mobile-friendly." (preference; not a friction-in-context) +- "Onboarding new engineers takes a lot of time." (abstracted; no specific moment) + +--- + +## Discovery prompts that surface struggling moments + +Specific prompts produce specific data. + +Prompts that work. + +- "Walk me through the last time you did [task]. What was hardest about it?" +- "What was the most recent time you wished you had a better way of doing [task]?" +- "When was the last time [task] went badly? What happened?" +- "Describe the last time you considered switching from [current tool] to something else. What triggered that?" +- "What's something you do that takes longer than it should? When was the last time it cost you?" + +The prompts share two characteristics: they ground in recent specific moments, and they invite the user to describe friction without pre-judging it. + +Prompts that fail. + +- "What features would you like to see?" (produces feature requests, not jobs) +- "How do you usually do [task]?" (produces abstracted descriptions, not moments) +- "Are you satisfied with [tool]?" (produces preferences, not behaviors) +- "What would your dream solution look like?" (produces fiction, not data) + +--- + +## The recency bias as a feature + +JTBD interviewing exploits recency. Recent moments are remembered with specifics; older moments get smoothed into abstractions. + +The methodology. Ask about the last time, the most recent occurrence, the situation that happened this week. Users can recall details from recent moments that they cannot recall from older ones. The details are where the job lives. + +The trade-off. Recent moments may not represent the dominant pattern; the most recent occurrence may be an outlier. The mitigation is interview volume: 8-15 interviews each grounded in recent moments produce a pattern; one interview grounded in one moment is one data point. + +--- + +## Pattern recognition across users + +Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well. + +The clustering work. + +- Across interviews, struggling moments get tagged with what the user was trying to accomplish, what failed, what alternative they wished for. +- Tags cluster: multiple users describe the same kind of friction in similar contexts. +- Each cluster suggests a job: the underlying thing users were trying to do that the cluster's friction was blocking. + +Worked example. Across 12 interviews with PM users: + +- Multiple users describe assembling data from multiple dashboards before quarterly business reviews. +- Multiple describe building Excel exports because their dashboard tool does not produce the right slice. +- Multiple describe second-guessing whether the data they assembled is correct. +- Multiple describe the time pressure and disruption these workarounds create. + +The cluster suggests a job: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The job emerges from the moments; the moments came from the prompts. + +--- + +## Distinguishing struggling moments from venting + +Not every friction users describe is a struggling moment for product purposes. + +Struggling moments. + +- Specific friction that interferes with the user accomplishing something they care about. +- The friction is reproducible (other users encounter similar friction in similar contexts). +- The friction has a workaround or alternative the user has tried. + +Venting that is not a struggling moment. + +- General complaint without specific friction context ("everything is too slow"). +- Preference for cosmetic differences ("I do not like the color"). +- One-off issues with no pattern across users. + +The discipline. Tag specific friction; do not over-weight venting. The struggling moments that drive product decisions are the ones with reproducible context across users. + +--- + +## The "what would you have done differently" question + +A specific prompt that surfaces both struggling moments and the implicit alternative. + +The prompt. "If you could have done [task] any way you wanted, how would you have done it?" + +What it surfaces. + +- The user's mental model of the ideal approach. +- The gap between current tools and the user's mental model. +- Sometimes the alternative tools the user has used or considered. + +What it does not surface. + +- Always-correct product solutions. Users often describe alternatives that would not actually work; the value is in understanding their mental model, not adopting their proposed solution. + +The interpretation. The user's described "would have done differently" is informative about the gap, not prescriptive about the fix. Synthesis interprets the gap and proposes product responses; users do not directly produce the responses. + +--- + +## When users do not have struggling moments + +Sometimes the interview reveals that the user is not struggling with the area the team is researching. They have a workable approach; they would not change it; the friction the team thought existed does not exist for this user. + +The honest interpretation. The team's hypothesis about a job that needs better tooling may be wrong, or this user may not be in the target segment for the job, or the job may be done well enough by existing solutions that there is no struggle. + +The discipline. Surface this finding rather than discounting it. "Some users are not struggling here" is data; ignoring it because it does not match the team's hypothesis is confirmation bias. + +--- + +## Struggling moments by product type + +Different product domains surface different kinds of struggling moments. + +Tools that fit into existing workflows. Struggling moments are workflow disruptions: the moment the existing tool failed and the user had to switch to a workaround. + +Tools that change workflows. Struggling moments are transition points: the moment the user realized the old workflow was unsustainable and considered changing it. + +Consumer products. Struggling moments are often emotional: the moment the user felt frustrated, blocked, or in conflict with their own goals. + +B2B platforms. Struggling moments often involve coordination: the moment the user could not align with a colleague, customer, or vendor because the tooling did not support the coordination. + +The discipline. Tailor interview prompts to the kind of struggling moment most likely in the product domain; do not assume one prompt works for all domains. + +--- + +## Common struggling-moment failures + +Eliciting preferences instead of moments. "What features do you wish existed?" produces preferences. Reframe: "What's the last task that took longer than it should have?" + +Abstracting moments to patterns prematurely. Users describing "what I usually do" instead of specific recent moments. Bring them back to the last specific time. + +Ignoring countervailing data. Users who do not struggle in the researched area. Their data is signal; do not discard it. + +Treating venting as struggling moments. General complaint without specific context does not produce jobs. + +Over-relying on the "wish" question. Users describe ideal alternatives that do not necessarily reflect what would work; treat as gap-revealing data, not as product specs. + +--- + +## Methodology-level choices that stay in the public skill + +What a struggling moment is and is not. Discovery prompts that work and fail. The recency bias as a feature. Pattern recognition across users. Distinguishing struggling moments from venting. The "what would you have done differently" question. When users do not struggle. Domain-specific struggling moment patterns. Common failures. + +## Implementation choices that stay internal + +Specific interview templates and discussion guides. Specific recording and tagging conventions. Specific recruitment criteria for who the team interviews. The team's own conventions for interview length and structure. These vary by team and research practice. diff --git a/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md b/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md new file mode 100644 index 0000000..663b49a --- /dev/null +++ b/dist/pi/.agents/skills/jtbd-framing/references/job-statement-structure-patterns.md @@ -0,0 +1,198 @@ +# Job statement structure patterns + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." Each level demands specificity. Vague levels produce job statements that drive nothing. + +--- + +## The three levels + +### Situation + +The context, trigger, or moment when the job becomes active. + +Strong situation patterns. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck the night before the meeting..." +- "When I get a customer escalation outside of business hours..." +- "When a new engineer joins my team mid-quarter..." + +Weak situation patterns. + +- "When I am at work..." (too broad) +- "As a marketing manager..." (demographic, not situational) +- "Whenever I need to communicate..." (lacks the specific trigger) + +Why specificity matters. Situations name the moment when the job activates. Different situations can produce different jobs even for the same user; collapsing situations together loses the patterns. + +--- + +### Motivation + +What the user is trying to do in that situation. + +Strong motivation patterns. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage the escalation and respond without disrupting my evening too much..." +- "...I want to onboard the new engineer to our codebase without becoming their full-time guide..." + +Weak motivation patterns. + +- "...I want to do my job better..." (too vague) +- "...I want to use feature X..." (motivation is a feature, not a goal) +- "...I want to be more productive..." (universal; not actionable) + +Why specificity matters. Motivations name what the user is trying to accomplish in their own words. The motivation should describe the job the user is doing, not the product the user is using. "I want to use Slack to communicate" is not a motivation; "I want to coordinate with the team on the rollout" is. + +The product-independence test. A good motivation should make sense without naming any specific product. If the motivation is bound to the product, it has slid into feature framing. + +--- + +### Outcome + +What success looks like; what the user is trying to achieve by doing the job. + +Strong outcome patterns. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." +- "...so the new engineer can ship their first PR within two weeks without depending on me for every question." + +Weak outcome patterns. + +- "...so I can succeed." (too vague) +- "...so I can use the feature." (outcome is feature use, not user goal) +- "...so I can be efficient." (universal; not specific) + +Why specificity matters. Outcomes name what success looks like in the user's terms. Different outcomes for the same situation+motivation can produce different jobs. The outcome anchors the job in the user's success criteria, not the product's metrics. + +--- + +## Worked examples across product domains + +### B2B SaaS for engineering teams + +- "When a production incident is detected and I am the on-call engineer, I want to identify the root cause and roll back if needed, so I can restore service before the SLO breach without escalating unnecessarily." + +### Consumer fitness app + +- "When I have 30 minutes between meetings and I want to use the time well, I want to do a workout that fits the time budget and uses the equipment I have at hand, so I can stay consistent without skipping when life gets busy." + +### Internal tools for finance teams + +- "When the month-end close is starting and I need to reconcile vendor payments, I want to identify discrepancies and document explanations, so the auditors can review without follow-up questions." + +### Creator-tools SaaS + +- "When I am editing a podcast episode the day before publication, I want to remove background noise and balance audio levels across speakers, so the episode sounds professional without spending another two hours on mastering." + +Each example specifies the moment, what the user is trying to do, and what success looks like. Each is product-independent at the motivation level: the user is trying to accomplish the job regardless of which tool they use. + +--- + +## Common structural failures + +### Vague situations + +Failure. "When I am at work..." + +Diagnosis. The situation does not name the trigger that activates the job. Most users are at work most of the time; the situation should name the specific moment. + +Cure. Re-ground in interview data. What was the user actually doing when this job became urgent? Use that moment. + +--- + +### Motivation as feature request + +Failure. "...I want to use the dashboard..." + +Diagnosis. Motivation is a feature, not a goal. The user does not want to use the dashboard; they want to accomplish something the dashboard supports. + +Cure. Ask the why-question. Why does the user want to use the dashboard? What are they trying to learn from it? The answer is the motivation. + +--- + +### Outcome as feature output + +Failure. "...so I can see the metrics." + +Diagnosis. Outcome is feature output, not user success. Seeing the metrics is intermediate; the user wants something the metrics enable. + +Cure. Ask another why. Why does the user want to see the metrics? What does seeing the metrics enable? The answer is the outcome. + +--- + +### Demographic as situation + +Failure. "As a marketing manager..." + +Diagnosis. Demographic, not situational. Different marketing managers in different moments have different jobs. + +Cure. Replace with the specific moment. "When the marketing manager is preparing the quarterly campaign retrospective..." + +--- + +### Universal as motivation or outcome + +Failure. "...I want to be more productive, so I can be efficient." + +Diagnosis. Universal language; could apply to any user, any job. Says nothing. + +Cure. Specificity at both motivation and outcome. What kind of productivity? What does productivity enable? The specifics are the job. + +--- + +## Multiple jobs per situation + +A single situation can produce multiple jobs. Different motivations or outcomes within the same situation are different jobs. + +Worked example. + +Situation: "When I am preparing the quarterly board deck..." + +Job A: "...I want to assemble revenue and engagement data into a coherent narrative, so I can answer the board's likely questions before they ask them." + +Job B: "...I want to flag the risks I want the board to engage with, so I can get their input on the calls I cannot make alone." + +Both jobs share the situation but have different motivations and outcomes. They may need different product responses. + +The discipline. Do not collapse multiple jobs into one because they share a situation. The motivation and outcome distinguish them. + +--- + +## Job statements vs alternatives in JTBD literature + +The "When... I want to... so I can..." format is the most widely used job statement structure. Other formats exist (outcome statements in outcome-driven innovation, struggle statements in switch interviews). They each name the same fundamental thing: the user's situation, motivation, and success criteria. + +This skill uses the When/I-want-to/So-I-can structure because it is the most teachable and the most consistently understood. Teams familiar with other JTBD lineages can translate; the underlying principles are the same. + +The structure-vs-substance discipline. The structure is a scaffold for analytical work. Job statements written in the right structure but without grounding in interview data are still ritual. Job statements written in slightly different structures but grounded in interview data and driving decisions are still jobs. + +--- + +## The job statement editing pass + +Strong JTBD work runs an editing pass focused on job-statement quality. + +Per job statement, the editing questions. + +1. Is the situation specific (a moment, not a demographic)? +2. Is the motivation product-independent and goal-directed? +3. Is the outcome the user's success criterion, not a feature output? +4. Is the statement specific enough that another team could distinguish it from related jobs? +5. Could the team use this job statement to evaluate a product decision? + +The editing investment. 1-2 hours per round of revisions on a typical job-statement set. The investment pays off in clarity for downstream applications (discovery, prioritization, positioning). + +--- + +## Methodology-level choices that stay in the public skill + +The three-level structure (situation, motivation, outcome). Strong vs weak patterns at each level. The product-independence test for motivation. Common structural failures and their cures. Multiple-jobs-per-situation discipline. The structure-vs-substance principle. The editing pass. + +## Implementation choices that stay internal + +Specific job-statement templates in the team's writing system. Specific document conventions for job-statement libraries. Specific A/B testing of statement variants in interview prompts. The team's own conventions for how many job statements per discovery cycle. These vary by team. diff --git a/dist/pi/.agents/skills/landing-page-copy/SKILL.md b/dist/pi/.agents/skills/landing-page-copy/SKILL.md new file mode 100644 index 0000000..cb3defd --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/SKILL.md @@ -0,0 +1,260 @@ +--- +name: landing-page-copy +description: "Write landing page copy with attention to the hero, value proposition, social proof, objection handling, and conversion-focused CTAs. Use this skill whenever the user wants to write a landing page, sales page, hero section, or any conversion-focused web copy. Triggers on landing page, sales page, hero copy, value proposition, headline, subheadline, hero section, CTA copy, conversion copy, opt-in page, squeeze page. Also triggers when the user has a marketing campaign or product launch needing dedicated conversion copy." +category: content +catalog_summary: "Landing pages, sales pages, hero-to-CTA flow" +display_order: 4 +--- + +# Landing Page Copy + +Write copy for pages with a single conversion goal: signup, purchase, demo request, download, lead capture. Stack-agnostic. + +This skill is narrower than `content-and-copy`. Landing pages exist to drive a specific action, not to inform broadly. + +--- + +## When to use + +- Writing a hero section for a homepage or product page +- Writing a sales page or long-form sales letter +- Drafting opt-in or lead-capture page copy +- Campaign-specific landing pages +- Pricing page copy +- Demo or signup CTAs + +## When NOT to use + +- Long-form blog content (use `content-and-copy`) +- Email sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- Page design and layout decisions (use `design-standards`) + +--- + +## Required inputs + +- The product, service, or offer +- The target audience and the specific objection they bring +- The conversion goal (one specific action) +- Brand voice +- Existing customer language (testimonials, support tickets, sales calls) +- Any constraints (length, format, regulatory) + +If audience is unclear or objections are unknown, run `brand-discovery` or pull from sales call recordings before writing. + +--- + +## The framework: 7 sections + +A landing page does seven things in sequence. The structure can flex (combine, reorder, expand), but the elements stay constant. + +### 1. Hero + +The first 3 to 5 seconds. Decides whether the visitor stays. + +Three components: + +- Headline. The promise. Specific, outcome-focused, free of cliche. +- Subheadline. The mechanism. How you deliver the promise. +- Primary CTA. The action. One button, descriptive label. + +Strong hero patterns: + +- Outcome + audience + mechanism. "Ship features 3x faster, for engineering teams who hate meetings, with our async-first project tool." +- Pain reversal. "Stop losing customers to slow page loads." +- Surprising claim. "The note-taking app that gets used. We have data." +- Direct address. "You have 47 unread Slack messages. Here's what to do about it." + +Weak hero patterns: + +- Generic adjective stacking ("Powerful, intuitive, scalable") +- "Welcome to our platform" +- Brand-name-only headlines ("Acme: The Future of X") +- Vague benefits ("Streamline your workflow") + +### 2. Social proof (early) + +Within the first scroll, prove someone else trusts you. + +Forms: +- Customer logos (recognizable beats unknown) +- Quantitative trust signal ("Over 10,000 teams") +- One strong testimonial with name and role +- Press mentions (logos of where you've been featured) + +Placement: Right below the hero, before the visitor invests in reading more. + +### 3. Problem / promise + +Establish that you understand the visitor's situation. + +Pattern: +- 1 to 3 paragraphs naming the specific problem +- Use the visitor's language (mined from research, not your marketing language) +- Stop before you sell. Resonate first. + +Test: Read the problem section aloud. Does the target audience nod? If they don't, you don't understand them yet. + +### 4. Solution / mechanism + +How you solve the problem. The "what we actually do" section. + +Effective structure: +- One headline summarizing the solution +- 3 to 5 specific features or capabilities, each with a 1-2 sentence explanation +- Each feature framed as the benefit it produces, not the technical detail +- Visual support (screenshots, illustrations, video clips) + +Failure mode: Listing features without translating to outcomes. "Real-time collaboration" is a feature. "Edit together without copying-pasting from email" is the outcome. + +### 5. Proof and detail + +The expanded social proof and case studies section. + +Components: +- 1 to 3 detailed case studies (specific customer, specific outcome, specific numbers) +- Multiple testimonials with attribution +- Specific data points (usage stats, success metrics, growth) +- Awards, certifications, or third-party validation + +The deeper proof section is where committed visitors convert. Skim-readers won't make it here, but the ones who do are ready to buy. + +### 6. Objection handling + +Anticipate the reasons people say no. Address them directly. + +Common objection types: +- Price. "Is this worth it?" +- Time. "Will this take forever to set up?" +- Trust. "Will this actually work for my situation?" +- Risk. "What if I commit and it's wrong?" +- Comparison. "How is this different from [competitor]?" +- Implementation. "Can my team handle the change?" + +Handling formats: +- FAQ section. Structured, scannable. +- Comparison table. Vs. competitors or vs. alternatives. +- Risk reversal. Money-back guarantee, free trial, no-contract terms. +- Proof of effort needed. "Setup takes 5 minutes, not 5 weeks." + +### 7. Final CTA + +The closer. Re-state the offer. Re-state the action. + +Strong final CTAs: +- Repeat the primary CTA from the hero (consistency) +- Frame in terms of the visitor's situation ("Get your team set up in 5 minutes") +- Remove friction ("No credit card required") +- One action only (avoid offering 5 alternatives that paralyze decision) + +Avoid: +- Multiple CTAs competing for attention at the bottom +- New offers introduced only at the bottom (visitor is now confused) +- Long forms that ask for more information than needed for the action + +--- + +## The CTA itself + +Buttons matter. Treat the button copy as a whole-page-worth of attention. + +Strong CTA patterns: + +- Action + outcome. "Start your free trial," "Get my pricing," "Send me the guide" +- First-person. "Show me how" outperforms "Show you how" +- Specific. "Book a 15-minute demo" beats "Contact us" +- Low-friction. "Free trial, no credit card" reduces commitment cost + +Weak CTAs: +- "Submit" (functional but lifeless) +- "Click here" (no value statement) +- "Learn more" (vague; about what?) +- "Get started" (started doing what?) + +--- + +## Workflow + +1. Confirm the offer. What exactly is being offered? At what price (if any)? What does the visitor get? +2. Confirm the audience and objection. Specific segment. The specific worry they bring. +3. Mine the language. Customer testimonials, support tickets, sales calls. Use real customer phrases. +4. Draft the hero. Headline, subheadline, CTA. Test 5 to 10 variations. +5. Build the structure. All 7 sections in order. Sections can combine for shorter pages. +6. Draft sections. Section by section. Don't polish until the structure is sound. +7. Edit for friction. Remove every word that doesn't earn its place. Landing pages do not have words to spare. +8. Test the CTA. Read the page aloud. By the end, is the visitor's next action obvious? +9. Pre-publish: check links, spell-check, mobile preview, SEO basics if SEO is a goal. + +--- + +## Failure patterns + +- Hero that explains instead of sells. "We're an X for Y" is description. "Get X without Y" is sell. +- Feature lists with no outcomes. Features without benefits read as a spec sheet. +- Generic testimonials. "Great product!" is worth less than nothing. "We cut onboarding time from 2 weeks to 4 days" is gold. +- Multiple competing CTAs. Pick one primary action. Everything else is noise. +- Walls of text. Visitors scan. Use short paragraphs, bullet lists, and visual breakpoints. +- No social proof. Trust is the first hurdle. Without proof, the rest of the page does not earn the chance to be read. +- Mismatched headline and CTA. Hero promises X, CTA asks for Y. Visitor confused. +- Writing for everyone. "Our solution works for any business" appeals to no one. Specificity converts. +- Ignoring mobile. Most visitors are on mobile. Test the page at 375px first. + +--- + +## Output format + +Default output is a structured markdown document for the page, with each section labeled. The markdown is ready to import into the CMS or hand to design. + +Structure: + +```markdown +# [Page Title] + +## SECTION: Hero +- Headline: [text] +- Subheadline: [text] +- Primary CTA: [button text] +- Supporting cue: [optional, e.g., "No credit card required"] +- Hero visual notes: [if any] + +## SECTION: Social proof (early) +- Logo bar: [list customer/press logos] +- Trust statistic: [if any] + +## SECTION: Problem / promise +[2 to 3 paragraphs] + +## SECTION: Solution +- Headline: [text] +- Feature 1: [headline + description] +- Feature 2: [headline + description] +- Feature 3: [headline + description] + +## SECTION: Proof +- Case study 1: [customer, outcome, numbers] +- Testimonials: [list] +- Data points: [list] + +## SECTION: Objection handling +- FAQ: [questions and answers] +- OR Comparison table: [vs alternatives] +- OR Risk reversal: [guarantee, terms] + +## SECTION: Final CTA +- Headline: [text] +- Final CTA button: [text] +- Supporting cue: [optional] + +## Variants for testing +- [Alternate headlines] +- [Alternate CTAs] +- [Alternate proof framings] +``` + +--- + +## Reference files + +- [`references/hero-formulas.md`](references/hero-formulas.md) - Patterns and formulas for hero headlines. +- [`references/objection-library.md`](references/objection-library.md) - Common objections by category, with handling strategies. diff --git a/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md b/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md new file mode 100644 index 0000000..d14a980 --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/references/hero-formulas.md @@ -0,0 +1,230 @@ +# Hero Headline Formulas + +The hero headline is the most-read line on the page. It earns the rest of the read or it doesn't. + +These are not magic templates. They are starting points. Apply them, then make them sound like the brand. + +--- + +## Formula 1: Outcome + audience + mechanism + +Pattern: [Specific outcome] for [specific audience] with [specific mechanism] + +Examples: +- "Ship features 3x faster, for engineering teams who hate meetings, with async-first project management." +- "Cut payroll processing from days to minutes, for finance teams of 50+, with one connected system." +- "Build a remote team that doesn't burn out, for founders scaling past 20 people, with rituals that actually work." + +Strengths: Highly specific. Hard to confuse with a competitor. + +Weaknesses: Can become long and clunky. Not always elegant. + +When to use: Product is in a crowded category and needs to differentiate quickly. + +--- + +## Formula 2: Pain reversal + +Pattern: Stop [specific pain]. Start [specific outcome]. + +Examples: +- "Stop losing customers to slow checkout. Start converting at industry-leading speeds." +- "Stop digging through Slack threads. Start finding answers in seconds." +- "Stop guessing what your users want. Start knowing." + +Strengths: Direct. Names the visitor's current frustration. + +Weaknesses: Depends on the pain being widely felt. If the pain isn't recognized, the headline doesn't connect. + +When to use: The audience is actively frustrated by something specific. + +--- + +## Formula 3: Surprising claim + +Pattern: A specific claim that contradicts what the audience expects. + +Examples: +- "The note-taking app most people actually use." +- "Email outreach that doesn't feel like spam." +- "The CRM that sales reps don't try to escape from." + +Strengths: Pattern-breaks. Creates curiosity. + +Weaknesses: Must be defensible. A surprising claim with no proof feels like marketing puffery. + +When to use: You can back up the claim with evidence in the page below. + +--- + +## Formula 4: Direct address + +Pattern: Speak to a specific situation the visitor is in right now. + +Examples: +- "You have 47 unread Slack messages. Here's what to do." +- "Your team just lost three candidates this month. Here's why." +- "Your app crashed at 3 AM. We watched your monitoring system miss it." + +Strengths: Visitor recognizes themselves immediately. + +Weaknesses: Risk of feeling presumptuous if the situation is wrong. + +When to use: The audience is highly specific and the scenario is universal among them. + +--- + +## Formula 5: Question they're already asking + +Pattern: Pose the question the visitor came to find an answer to. + +Examples: +- "How much should you actually spend on Google Ads?" +- "Should you build it or buy it? Here's the framework." +- "Why does your team's productivity drop after lunch?" + +Strengths: Aligns with search intent. Strong for SEO landing pages. + +Weaknesses: Less common in product hero copy. Better for content-driven landing pages. + +When to use: The page answers a specific question the visitor brought. + +--- + +## Formula 6: Comparison (us vs. them) + +Pattern: [Our category] without the [familiar pain of the category]. + +Examples: +- "CRM software without the bloat." +- "Project management without the meetings." +- "Customer support without the tickets." + +Strengths: Defines you in opposition to known alternatives. + +Weaknesses: Lazy version becomes "X but better." Specific version requires you to actually deliver on the difference. + +When to use: The category has a well-known pain point you avoid. + +--- + +## Formula 7: Number + outcome + +Pattern: Specific number that quantifies the value. + +Examples: +- "Cut your churn in half within 90 days." +- "Onboard your team in 15 minutes, not 15 weeks." +- "Generate 200 hours of meeting transcripts per month." + +Strengths: Specific and credible. + +Weaknesses: The number must be defensible. Made-up numbers undermine trust. + +When to use: You have real data backing the claim. + +--- + +## Formula 8: First-person promise + +Pattern: "Get [specific thing]" or "Find [specific thing]" - speaking as if to a friend. + +Examples: +- "Get insurance quotes in 60 seconds. Compare 30 carriers." +- "Find a contractor your neighbors actually recommend." +- "Get back the 6 hours a week you spend on email." + +Strengths: Conversational. Low-friction. + +Weaknesses: Casual register may not fit every brand. + +When to use: Brand voice supports a conversational first-person register. + +--- + +## Subheadline patterns + +The subheadline supports the headline. It usually does one of three jobs: + +### Job 1: Mechanism +The subheadline explains how you deliver the headline's promise. + +> Headline: Ship features 3x faster. +> Subheadline: Our async workflow eliminates the meetings that slow your team down. + +### Job 2: Audience qualifier +The subheadline names the audience precisely. + +> Headline: The simplest way to manage your inventory. +> Subheadline: Built for ecommerce stores doing $1M to $10M in revenue. + +### Job 3: Specificity / proof +The subheadline adds the credible detail. + +> Headline: Stop losing leads. +> Subheadline: Top performers reduce response time from hours to minutes. We help you do the same. + +--- + +## What to avoid in hero copy + +### Generic adjective stacking + +Bad: "Powerful. Intuitive. Scalable." + +These adjectives apply to anything. They distinguish nothing. + +### Vague benefits + +Bad: "Streamline your workflow with our innovative platform." + +What workflow? What's innovative? What does the visitor actually do? + +### Brand-name-only headlines + +Bad: "Acme: The Future of Work." + +The visitor doesn't know what Acme is yet. The headline must tell them. + +### Cleverness over clarity + +Bad: "Where productivity meets possibility." + +Sounds nice. Means nothing. Visitors do not have time to decode poetry. + +### "Welcome to" openers + +Bad: "Welcome to the [Brand] platform." + +Treats the visitor as a guest rather than a person trying to solve a problem. Wastes the most important real estate on the page. + +--- + +## Testing hero headlines + +Don't ship the first headline you write. Generate 5 to 10 variations using different formulas. Read them aloud. Show them to people. Pick the one that: + +1. A target-audience reader recognizes themselves in +2. Differentiates from at least 3 specific competitors +3. Sets up the rest of the page (the rest of the page must deliver on the headline's promise) +4. Sounds like the brand (not generic marketing speak) +5. Survives the "why now" test (why does this matter to the visitor today) + +If a headline can't survive all five, generate more variations. + +--- + +## CTA patterns to pair with hero headlines + +The headline and CTA must rhyme. If they don't, the visitor's mental model breaks. + +\| Hero promise \| CTA pattern \| +\|---\|---\| +\| Get specific outcome \| "Get [the outcome]" \| +\| Save time / money \| "Save [the thing]" \| +\| See how it works \| "Watch demo" / "See it in action" \| +\| Try the product \| "Start free trial" / "Try it free" \| +\| Get information \| "Get the guide" / "Show me how" \| +\| Talk to a person \| "Book a call" / "Talk to sales" \| + +The CTA copy is part of the hero, not an afterthought. Treat it with the same care as the headline. diff --git a/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md b/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md new file mode 100644 index 0000000..23ae871 --- /dev/null +++ b/dist/pi/.agents/skills/landing-page-copy/references/objection-library.md @@ -0,0 +1,244 @@ +# Objection Library + +Common objections by category, with handling strategies. Use this to pressure-test landing page copy and to make sure each major objection is met somewhere on the page. + +If a landing page does not name and answer the audience's real objections, it will not convert no matter how strong the hero is. + +--- + +## How to use this library + +1. Identify your audience and the specific decision they are facing. +2. Walk this library and flag every objection that applies. +3. For each flagged objection, decide where on the page it gets handled (and whether it gets handled with copy, social proof, a guarantee, an FAQ, or a feature). +4. Pressure-test the page: read it as a skeptical reader. Are the flagged objections answered before the CTA? + +Most pages handle 5-8 objections. Pages that handle 0-2 read as too good to be true. Pages that handle 15+ feel defensive. + +--- + +## Category 1: trust + +The audience does not know if you are real, competent, or honest. + +### "I have never heard of you" + +- Symptom: Bounce rate high, low time on page. +- Handling: Logo bar of customers, press mentions, founder photo and one-line bio, "since [year]" line, recognizable case study, security badges if relevant. + +### "How do I know this works?" + +- Symptom: Visitors read the whole page but do not act. +- Handling: Specific case studies with real names and specific outcomes ("X reduced Y by Z%"). Demo or trial. Money-back guarantee. Free assessment. + +### "How do I know you will be around in a year?" + +- Symptom: Common in B2B with switching costs, regulated industries, long-term commitments. +- Handling: Funding announcements, customer count, years in business, prominent enterprise customers, industry awards or compliance attestations. + +### "Who is behind this?" + +- Symptom: Common in personal brands, consultancies, or expertise-based services. +- Handling: Founder photo, credentials, prior work, authentic origin story. + +--- + +## Category 2: fit + +The audience cannot tell if this is for them. + +### "Is this for someone like me?" + +- Symptom: General-audience visitors converting; specific-segment visitors bouncing. +- Handling: Audience-specific copy, role-based or industry-based pages, named segments in the hero ("for [role] at [company size]"), audience-specific case studies. + +### "Will this work for my situation?" + +- Symptom: Visitors get to features and bounce. +- Handling: Use case sections, conditional FAQ ("if you are X, here is how this works"), filterable case studies, decision tree or quiz. + +### "Is my problem big enough to need this?" + +- Symptom: SMB visitors looking at enterprise products, or vice versa. +- Handling: Plan or tier comparison, "right-sized for [size]" messaging, alternatives section ("if you have [smaller problem], try [lighter approach]"). + +### "I have already solved this with [alternative]" + +- Symptom: Visitors compare and leave. +- Handling: Comparison page, "vs [competitor]" page, "in addition to" framing, integrations section. + +--- + +## Category 3: complexity and time + +The audience worries this will be hard, slow, or distracting. + +### "How long will this take to set up?" + +- Symptom: Time-on-page high; conversion low. Common in dev tools, SaaS. +- Handling: "5 minutes to set up" messaging, video walkthrough showing real timing, testimonials from peers about onboarding, white-glove option. + +### "Will I have to migrate or change what I am doing?" + +- Symptom: Switching anxiety. Common in any tool replacement. +- Handling: Migration guides, importer features highlighted, "works alongside [current tool]" framing, migration assistance offered. + +### "Will my team need training?" + +- Symptom: Buyer is enthusiastic; champion is worried about adoption. +- Handling: Onboarding program, in-product training, role-based docs, video library, account manager for enterprise. + +### "Is this going to add to my plate?" + +- Symptom: Visitors are already overworked. Common pitch to operators, ICs. +- Handling: Time-saving framing with specific numbers ("saves 4 hours per week"), automation highlighted, replace-not-add positioning. + +--- + +## Category 4: cost + +The audience worries about price, value, or hidden costs. + +### "How much does this cost?" + +- Symptom: Anyone visiting the pricing page bounces. Conversion only on free trial. +- Handling: Transparent pricing on the marketing site (or "starts at" if pricing varies), no "request a quote" for low-tier pricing, ROI calculator. + +### "Is it worth the price?" + +- Symptom: Pricing page visited; nothing happens. +- Handling: Specific ROI examples ("customers see X return in Y months"), comparison to alternative ("instead of hiring a [role], you get [tool]"), free trial or money-back, value framing throughout. + +### "Are there hidden fees?" + +- Symptom: Visitors abandon at checkout or in sales calls when extras come up. +- Handling: "No setup fees" line, "no per-seat charges" if true, "all features included" if true, transparent pricing page with all variables surfaced. + +### "I do not have budget right now" + +- Symptom: Common in macro slowdowns. Visitors say "interesting, send info." +- Handling: Annual discount, smaller plan, free tier, ROI-led copy, ROI calculator, "self-funding within X months" claim if defensible. + +--- + +## Category 5: risk + +The audience fears what happens if this goes wrong. + +### "What if it does not work?" + +- Symptom: Visitors explore deeply but do not commit. +- Handling: Money-back guarantee, free trial, free pilot, money-back specifically tied to outcome ("if you do not see X, we refund"), case studies of customers who got results. + +### "What if my data is at risk?" + +- Symptom: Common in B2B, data tools, financial, healthcare. +- Handling: Security page linked from footer (and from sales-relevant pages), compliance badges (SOC 2, ISO 27001, GDPR, HIPAA), data-handling explainer, "your data is yours" framing. + +### "What if I am locked in?" + +- Symptom: Visitors ask about export, contracts, cancellation in sales calls. +- Handling: "Export your data anytime," "no long-term contract," "cancel any time," month-to-month option visible. + +### "What if my team will not adopt it?" + +- Symptom: Champion deals stall. +- Handling: Onboarding program, role-based pricing or trials, internal-rollout playbook, customer testimonials from peer companies on adoption. + +--- + +## Category 6: timing + +The audience does not see urgency. + +### "I will get to this later" + +- Symptom: Sign-ups but no follow-through. Long sales cycles. +- Handling: Cost-of-inaction framing ("each month you wait costs X"), time-bound offer (tasteful, real, not fake), seasonal hook if relevant, before-and-after framing showing time loss. + +### "I am evaluating multiple options" + +- Symptom: Pipeline takes 6+ months to close. +- Handling: Comparison page, evaluation guide ("how to evaluate [category]"), trial that gets the buyer hands-on quickly, customer references for direct calls. + +--- + +## Category 7: politics and process + +The audience cannot decide alone. + +### "I need to get my boss to approve this" + +- Symptom: Champion engagement high; deal stuck above champion's authority. +- Handling: Business case template, ROI calculator, exec one-pager, "make the case to [role]" content, customer references at peer companies (named role buying the same tool). + +### "I need legal/security/procurement to review" + +- Symptom: Long lag between handshake and contract signature. +- Handling: Security questionnaire pre-completed, MSA boilerplate available, vendor onboarding kit, named legal/security contact for buyer-side reviewers. + +### "I need to align with [other team]" + +- Symptom: Multi-stakeholder deals stall. +- Handling: Team-specific pages, team-specific demos, multi-stakeholder ROI framing, internal advocacy kit (slide deck, FAQ). + +--- + +## Category 8: emotional / status + +The audience worries about how they will look. + +### "What if this is the wrong call?" + +- Symptom: Decision-maker stalls. Common with high-visibility purchases. +- Handling: Peer customer testimonials ("[Title] at [Recognizable Company] said X"), industry analyst recognition, awards, money-back guarantee that limits downside. + +### "Will this make me look behind / ahead?" + +- Symptom: First-mover anxiety or laggard anxiety. Industry-specific. +- Handling: "Industry standard now" framing for laggards, "ahead of the curve" framing for first-movers, social proof from peer companies in either case. + +--- + +## How objection handling shows up on the page + +The library is the inventory. The page is where it lands. The most common placements: + +- Hero: answers the "is this for me" objection. +- Logo bar: answers "are you real." +- Feature sections: answer "does this do what I need." +- Use case sections: answer "will this work for my situation." +- Case study sections: answer "does this work." +- Comparison sections: answer "what about alternatives." +- Pricing section: answers "what does it cost." +- FAQ section: answers the long tail of objections. +- Guarantee / trial offer: answers "what if it does not work." +- Footer trust block: answers "is my data safe" via compliance badges. + +If an objection from your audience is not answered anywhere on the page, the page is incomplete. + +--- + +## Worked example + +Audience: Engineering manager at a series-B startup, 30-50 person engineering org, evaluating an observability tool to replace an in-house Grafana setup. + +Top 5 objections (filtered from the library): + +1. "How long will this take to set up?" (Category: complexity) +2. "Will I have to migrate?" (Category: complexity) +3. "What does this cost at our scale?" (Category: cost) +4. "What if my engineers do not adopt it?" (Category: risk + politics) +5. "What if our data is at risk?" (Category: risk) + +Page placements: + +\| Objection \| Where it gets handled \| +\|---\|---\| +\| Setup time \| Hero ("Live in 10 minutes" + 60-second product video) \| +\| Migration \| Migration section ("imports from Grafana automatically") + case study showing migration story \| +\| Cost at scale \| Pricing page with engineer-count slider, transparent monthly cost \| +\| Adoption \| Adoption section showing in-product onboarding, plus a customer quote ("80% of engineers logged in week one") \| +\| Data risk \| Footer trust block (SOC 2, ISO, GDPR) + a "your data" explainer linked from pricing \| + +Page is built around answering these five, in order, from hero to CTA. diff --git a/dist/pi/.agents/skills/launch-runbook/SKILL.md b/dist/pi/.agents/skills/launch-runbook/SKILL.md new file mode 100644 index 0000000..0fb3e62 --- /dev/null +++ b/dist/pi/.agents/skills/launch-runbook/SKILL.md @@ -0,0 +1,236 @@ +--- +name: launch-runbook +description: "Plan and execute a launch runbook covering pre-launch verification, go-live procedures, DNS cutover, post-launch monitoring, and rollback procedures. Use this skill whenever the user is preparing to launch a website or product, planning a DNS cutover, building a go-live checklist, or executing a launch day. Triggers on launch runbook, go-live, launch day, DNS cutover, deploy to production, site launch, product launch, cutover plan, launch checklist, deployment procedure. Also triggers when a launch is approaching and the team needs structured coordination, even if 'runbook' is not explicitly stated." +category: operations +catalog_summary: "Go-live runbook, DNS cutover, deploy day procedures" +display_order: 1 +--- + +# Launch Runbook + +Plan and execute the launch of a website, product, or major release. The runbook is the document everyone uses on launch day. Stack-agnostic. + +This skill is for the launch event. For pre-launch QA, use `qa-testing`. For post-launch incident handling, use `incident-response`. + +--- + +## When to use + +- Launching a new website or major redesign +- Migrating from one platform to another +- Releasing a major product or feature +- Coordinating cross-team launches +- Building a runbook for a recurring deploy + +## When NOT to use + +- Pre-launch testing (use `qa-testing`) +- Post-launch incident response (use `incident-response`) +- After-launch retrospective (use `after-action-report`) + +--- + +## Required inputs + +- The launch scope (what's being launched) +- The launch window (date, time, duration) +- The team (roles, on-call rotation) +- The rollback criteria (when to abort) +- The communication plan (who tells whom what, when) + +--- + +## The framework: 4 phases + +A launch has four phases. The runbook covers all four. + +### Phase 1: Pre-launch (T-30 days to T-1 hour) + +Verify everything is ready before the launch window. + +T-30 days: +- Final scope locked +- Cross-team commitments confirmed +- Pre-launch QA scheduled +- Comms plan drafted + +T-7 days: +- Pre-launch QA complete +- All critical and major issues resolved +- Performance baseline measured +- Rollback procedures documented and tested +- DNS TTL lowered (if DNS change is part of launch) + +T-1 day: +- Final go/no-go meeting +- Roles confirmed +- Communication channels set up +- Backup of current production state + +T-1 hour: +- Team assembled in shared communication channel +- Tools and access verified +- Final smoke test on staging + +### Phase 2: Cutover (T-0) + +The actual launch. Sequenced steps with owners and verifications. + +Standard cutover steps: + +1. Announce start to internal team +2. Enable maintenance mode (if applicable) +3. Run final database migrations (if applicable) +4. Deploy code to production +5. Verify deploy completed without errors +6. Run smoke tests on production +7. DNS cutover (if applicable) +8. Verify DNS propagation +9. Disable maintenance mode +10. Run full smoke tests on production +11. Announce launch to internal team +12. Begin monitoring window + +Each step has: +- Owner +- Pre-conditions +- Action +- Verification +- Time estimate +- Rollback procedure + +### Phase 3: Verification (T+0 to T+24 hours) + +Confirm the launch is healthy. + +Within first hour: +- Critical user flows working (checkout, signup, login) +- No spike in error rates +- Performance within expected ranges +- Analytics tracking firing +- Email and notifications working + +Within first 24 hours: +- No regression in key business metrics +- No accumulating error patterns +- Core Web Vitals stable +- Search Console showing no critical issues (if SEO-relevant) + +### Phase 4: Stabilization (T+24 hours to T+7 days) + +Monitor the long tail. + +- Track error rates day over day +- Track performance day over day +- Track key business metrics vs baseline +- Address any non-blocking issues identified +- Plan the AAR (after-action report) + +--- + +## Roles and responsibilities + +A launch has clear role assignments. Ambiguity here is the most common cause of launch chaos. + +\| Role \| Responsibility \| +\|---\|---\| +\| Launch lead \| Owns the runbook. Calls go/no-go. Calls rollback. \| +\| Deploy operator \| Executes the technical deploy steps. \| +\| QA lead \| Runs verification tests and confirms each milestone. \| +\| Comms lead \| Posts internal updates, manages external messaging. \| +\| On-call engineer \| Available for issues during and after launch. \| +\| Stakeholder rep \| Approves on behalf of business stakeholders. \| + +For small teams, one person may fill multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Rollback criteria + +Define before the launch. Decisions are easier to make pre-emptively than under pressure. + +Automatic rollback triggers: +- Error rate exceeds X percent of normal +- Critical user flow (defined) is broken +- Database integrity issue +- Security vulnerability discovered post-deploy + +Discretionary rollback triggers: +- Performance degradation beyond Y percent +- Significant degradation in key business metric +- Customer-facing error patterns + +Decision authority: The launch lead calls rollback. Pre-define who acts as deputy if launch lead is unavailable. + +--- + +## Communication plan + +### Internal channels + +- Primary launch channel: Real-time chat for the launch team only +- Status channel: Broader internal updates +- War room: Optional video call for high-stakes launches + +### Update cadence during launch + +- Every 15 minutes during cutover +- Every hour during verification phase +- Daily during stabilization phase + +### External communication + +- Customer-facing announcement: Pre-drafted, scheduled to publish at confirmed-success milestone +- Status page: Updated proactively if any user impact +- Support team: Briefed in advance on what's launching, common questions, escalation path + +--- + +## Workflow + +1. Build the runbook 30 days out. Scope, sequence, roles, rollback criteria, comms plan. +2. Test the rollback procedure. Untested rollback is hope, not procedure. +3. Run a tabletop exercise. Walk through the runbook with the full team. Find gaps. +4. Lower DNS TTL 48 to 72 hours before launch (if DNS change is part of launch). +5. Day-of: Run the runbook step by step. Verify each step before moving to next. +6. Monitor. First hour, first day, first week. Document anything noteworthy. +7. Schedule the AAR within 1 to 2 weeks of launch. + +--- + +## Failure patterns + +- Runbook written by one person, not reviewed. Single perspective misses scenarios. +- No tested rollback. Discovering rollback is broken at the moment you need it. +- Vague step descriptions. "Deploy to production" without specifying which tool, which command, which environment. +- No verification step after each action. Errors propagate. +- Communication gaps. Team doesn't know launch is happening, or doesn't know it succeeded. +- Launching at end of day Friday. Or before a holiday. Reduce the time available to respond. +- Skipping pre-launch QA to hit a date. The bugs appear on launch day instead. +- Launch fatigue. Long launches without breaks lead to errors. Plan rest cycles for multi-day launches. +- No on-call for first 24 hours. Someone must be reachable. + +--- + +## Output format + +Default output: a markdown runbook at `launch-runbook-[project].md` plus supporting checklists. + +Structure: + +1. Launch metadata (what, when, who) +2. Roles and responsibilities +3. Pre-launch checklist (T-30, T-7, T-1, T-1hr) +4. Cutover sequence (numbered steps, owners, verifications) +5. Rollback procedure +6. Rollback criteria (automatic and discretionary) +7. Communication plan +8. Verification checklist (first hour, first day) +9. Stabilization plan (first week) +10. Contacts (escalation paths, on-call) + +--- + +## Reference files + +- [`references/runbook-template.md`](references/runbook-template.md) - Fillable runbook template with example cutover sequences. diff --git a/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md b/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md new file mode 100644 index 0000000..bd2a9c2 --- /dev/null +++ b/dist/pi/.agents/skills/launch-runbook/references/runbook-template.md @@ -0,0 +1,289 @@ +# Launch Runbook Template + +Fillable runbook for a launch. Copy this template, fill in specifics for your launch. + +--- + +## Launch metadata + +What's launching: [Specific scope. "New marketing site at example.com replacing the legacy site."] + +Launch date: [YYYY-MM-DD] + +Launch window start: [Time, timezone] + +Launch window end: [Time, timezone] + +Maintenance window required: [Yes / No, and if yes, expected duration] + +Launch lead: [Name + contact] + +Deputy launch lead: [Name + contact, in case primary is unavailable] + +--- + +## Roles + +\| Role \| Person \| Backup \| Contact \| +\|---\|---\|---\|---\| +\| Launch lead \| \| \| \| +\| Deploy operator \| \| \| \| +\| QA lead \| \| \| \| +\| Comms lead \| \| \| \| +\| On-call engineer (post-launch) \| \| \| \| +\| Stakeholder rep \| \| \| \| + +--- + +## Pre-launch checklist + +### T-30 days +- [ ] Final scope locked and signed off +- [ ] Cross-team commitments confirmed +- [ ] Pre-launch QA scheduled +- [ ] Communications plan drafted +- [ ] Rollback procedure documented + +### T-14 days +- [ ] Pre-launch QA in progress +- [ ] Performance baseline measured (current production) +- [ ] Critical and major issues triaged +- [ ] Internal launch announcement drafted + +### T-7 days +- [ ] All critical issues resolved +- [ ] All major issues resolved or accepted with mitigation +- [ ] Rollback procedure tested in staging +- [ ] DNS TTL lowered to 60 to 300 seconds (if DNS change is part of launch) +- [ ] Final go/no-go date confirmed + +### T-2 days +- [ ] Final go/no-go meeting held +- [ ] Decision: GO / NO-GO / DEFER +- [ ] All team members confirmed available for launch window +- [ ] Backup of current production state taken +- [ ] Customer support briefed on what's launching + +### T-1 day +- [ ] Final smoke test on staging passes +- [ ] Communication channels set up +- [ ] On-call rotation confirmed for first 24 hours +- [ ] Pre-drafted internal and external messaging ready + +### T-1 hour +- [ ] Team assembled in launch communication channel +- [ ] All required tools and access verified +- [ ] Final smoke test on staging passes +- [ ] Launch lead confirms GO + +--- + +## Cutover sequence + +For each step: +- Owner: Person executing +- Pre-condition: What must be true to start +- Action: What to do +- Verification: How to confirm success +- Estimated time: How long this should take +- Rollback: What to do if this step fails + +--- + +### Step 1: Announce start + +- Owner: Comms lead +- Pre-condition: Launch lead has confirmed GO +- Action: Post in internal status channel: "Starting launch of [scope] at [time]. Expected duration: [X minutes]." +- Verification: Message posted, key stakeholders confirmed they saw it +- Time: 2 minutes + +### Step 2: Enable maintenance mode + +- Owner: Deploy operator +- Pre-condition: Step 1 complete +- Action: [Specific command or action to enable maintenance mode] +- Verification: Visit production URL, confirm maintenance page is showing +- Time: 2 minutes +- Rollback: Disable maintenance mode + +### Step 3: Final database migrations + +- Owner: Deploy operator +- Pre-condition: Step 2 complete, database backup confirmed +- Action: [Specific migration command] +- Verification: Migration log shows success, schema verified +- Time: [estimate] +- Rollback: Restore from backup taken in T-2 + +### Step 4: Deploy code to production + +- Owner: Deploy operator +- Pre-condition: Step 3 complete +- Action: [Specific deploy command or CI trigger] +- Verification: Deploy log shows success, version endpoint returns new version +- Time: [estimate based on past deploys] +- Rollback: Re-deploy previous version + +### Step 5: Run smoke tests on production + +- Owner: QA lead +- Pre-condition: Step 4 complete +- Action: Run smoke test suite against production +- Verification: All smoke tests pass +- Time: [estimate] +- Rollback: If failures, evaluate severity. Critical failures = rollback to step 4. + +### Step 6: DNS cutover (if applicable) + +- Owner: Deploy operator +- Pre-condition: Step 5 passes +- Action: Update DNS records: [specific records and values] +- Verification: Use `dig` or DNS lookup tools to confirm new records propagating +- Time: Propagation up to 5 minutes (if TTL was lowered) up to 24+ hours (if not) +- Rollback: Revert DNS records to previous values + +### Step 7: Disable maintenance mode + +- Owner: Deploy operator +- Pre-condition: Step 6 verified +- Action: [Specific command to disable maintenance mode] +- Verification: Visit production URL, confirm new site loads +- Time: 2 minutes + +### Step 8: Full smoke test on production + +- Owner: QA lead +- Pre-condition: Step 7 complete +- Action: Run full smoke test suite (more comprehensive than step 5) +- Verification: All tests pass; critical user flows verified manually +- Time: [estimate] +- Rollback: If failures, evaluate. Critical failures = full rollback. + +### Step 9: Announce success + +- Owner: Comms lead +- Pre-condition: Step 8 passes +- Action: Post in internal status channel: "Launch complete. All checks pass." +- Verification: Confirmed by stakeholders +- Time: 2 minutes + +### Step 10: Begin monitoring window + +- Owner: On-call engineer +- Pre-condition: Step 9 complete +- Action: Begin elevated monitoring for first 60 minutes. Watch error rates, performance, key business metrics. +- Verification: Dashboards open, alerts armed +- Time: Continuous + +--- + +## Rollback procedure + +If rollback is called, execute these steps: + +1. Announce rollback in internal status channel +2. Re-enable maintenance mode (if applicable) +3. Revert DNS records to previous values (if changed) +4. Re-deploy previous code version +5. Restore database from backup (if migrations were destructive) +6. Verify previous version is functioning +7. Disable maintenance mode +8. Run smoke tests on rolled-back state +9. Announce rollback complete +10. Schedule post-mortem + +Estimated total rollback time: [Estimate, typically 15 to 60 minutes] + +Authority to call rollback: Launch lead (or deputy if launch lead unavailable) + +--- + +## Rollback criteria + +### Automatic rollback (no debate, just do it) +- [ ] Production error rate exceeds [X]% above baseline +- [ ] Critical user flow broken: [specify which flows] +- [ ] Database integrity issue detected +- [ ] Security vulnerability discovered + +### Discretionary rollback (launch lead's call) +- [ ] Performance degradation beyond [Y]% +- [ ] Significant degradation in [specific business metric] +- [ ] Customer-facing error pattern emerging + +--- + +## Communication plan + +### Internal updates during launch +- Cadence: Every 15 minutes during cutover +- Channel: [Specific Slack channel / Teams channel / etc.] +- Format: "[Time] - [Step name] - [Status: started / in progress / complete / blocked]" + +### Customer-facing announcement +- When: After step 9 (success announce internal) +- Where: [Specific channels: blog post, email, social, etc.] +- Pre-drafted: [Link to draft] +- Approver: [Name] + +### Status page updates +- Pre-launch: [Status set to "Maintenance scheduled"] +- During: [Status set to "Maintenance in progress"] +- Post-success: [Status set to "Operational"] +- If issues: [Status set to "Investigating" or "Identified"] + +### Support team brief +- Pre-launch brief covers: what's launching, what users may notice, common questions, escalation path +- During-launch updates posted to support channel + +--- + +## Verification checklist (first hour) + +- [ ] Homepage loads +- [ ] Critical user flow 1: [specify] - works +- [ ] Critical user flow 2: [specify] - works +- [ ] Critical user flow 3: [specify] - works +- [ ] Sign-up / sign-in - works +- [ ] Payment flow (if applicable) - works +- [ ] Email sending - works +- [ ] Analytics tracking firing +- [ ] Error rate within normal range +- [ ] Performance within normal range +- [ ] No security alerts triggered +- [ ] Search Console shows no critical issues (if SEO-relevant launch) + +--- + +## Verification checklist (first 24 hours) + +- [ ] No regression in key business metrics: [list specific metrics] +- [ ] Error rate stable +- [ ] Performance stable +- [ ] No accumulating error patterns +- [ ] Core Web Vitals stable +- [ ] Customer support volume within normal range + +--- + +## Contacts + +\| Role \| Name \| Phone \| Slack \| Email \| +\|---\|---\|---\|---\|---\| +\| Launch lead \| \| \| \| \| +\| Deputy lead \| \| \| \| \| +\| Engineering on-call \| \| \| \| \| +\| Database admin \| \| \| \| \| +\| DNS / infrastructure \| \| \| \| \| +\| Customer support lead \| \| \| \| \| +\| Executive sponsor \| \| \| \| \| + +--- + +## Post-launch + +- [ ] Schedule AAR within 1 to 2 weeks +- [ ] Document any deviations from runbook +- [ ] Capture metrics: rollback rate, time to launch, issues found, etc. +- [ ] File improvements to runbook for next launch diff --git a/dist/pi/.agents/skills/lead-magnet-design/SKILL.md b/dist/pi/.agents/skills/lead-magnet-design/SKILL.md new file mode 100644 index 0000000..29da923 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/SKILL.md @@ -0,0 +1,282 @@ +--- +name: lead-magnet-design +description: "Designing lead magnets that earn the email. The discipline of building gated content (ebooks, templates, checklists, swipe files, mini-courses, free tools) that delivers genuine standalone value while qualifying the lead and warming them for what comes next. Honest about thin-bait (overpromises, underdelivers), kitchen-sink-resource (everything, helps with nothing), and earned-value-magnet (delivers standalone value while qualifying the lead). Triggers on lead magnet, gated content, opt-in offer, ebook, checklist, template, swipe file, mini-course, free tool, content upgrade, freebie, opt-in, list-building offer. Also triggers when an audience is being asked for an email and the offer attached to that ask needs design discipline, when previous lead magnets converted but did not produce qualified leads, or when a lead magnet is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing gated content that earns the email. Distinguishes thin-bait (overpromises, underdelivers) from kitchen-sink-resource (everything, helps with nothing) from earned-value-magnet (delivers standalone value while qualifying the lead)" +display_order: 1 +--- + +# Lead Magnet Design + +A senior growth practitioner's playbook for designing lead magnets that earn the email. Templates, checklists, swipe files, mini-courses, free tools, ebooks. The discipline of building gated content that delivers genuine standalone value while qualifying the lead and warming them for the next conversation. + +Most lead magnets are bait. A vague headline, a thin PDF, an email gate, a follow-up sequence the reader resents. Conversion-rate metrics look fine because the form converted; the email list grows; and the unsubscribe rate climbs because the magnet was a transaction the reader regrets the moment they download. + +The lead magnets that work as compounding assets do something different. They deliver value the reader would have paid for if they had to. They qualify the lead by audience-fit, so the list that grows is the right list. They set up the next conversation honestly, so the follow-up sequence is a continuation rather than an apology. + +This skill is the parent-frame methodology for the growth tooling track. Calculators (`calculator-design`) and quizzes (`quiz-and-assessment-design`) are specific lead-magnet types covered as their own skills. This skill provides the methodology for deciding WHAT to build before deciding WHAT TYPE. + +The voice is the senior growth practitioner who has watched lead magnets earn long-term subscribers and watched them burn list trust within a single send. Practical, opinionated about format selection, willing to tell the reader when a lead magnet is the wrong investment for the goal. + +When to use this skill: scoping a lead magnet for the first time, auditing a lead magnet that converts but does not qualify, deciding which format fits a specific audience and offer, or designing the post-download sequence that turns the magnet into a relationship. + +--- + +## What this skill covers + +This skill spans lead magnet design as the parent discipline. The growth-tooling distinctions: + +- `lead-magnet-design` (this skill) is the parent-frame methodology. WHAT a magnet is, when to invest in one, which format fits, how to qualify the lead, how to set up the follow-up. +- `calculator-design` is one specific lead-magnet type with its own methodology (calculation transparency, tiered value, methodology disclosure). +- `quiz-and-assessment-design` is another specific lead-magnet type (scoring algorithms, result categorization, recommendation matching). +- `landing-page-copy` is the page-level discipline that wraps the magnet's offer. +- `content-distribution` is how the magnet reaches its audience. +- `content-strategy` is upstream: the topic decisions that earn investment in any one magnet. + +The audience: growth marketers, in-house product marketers, marketing teams, agencies running list-building work for clients, founders building their own funnels. + +Out of scope: long-form content marketing (covered by `content-strategy`); landing-page copy (covered by `landing-page-copy`); email sequence design at scale (covered by `email-sequences`); the specific tooling configurations that deliver the magnet (those stay implementation-side). + +--- + +## The lead magnet decision: when to build one, when not to + +Before designing the magnet, decide whether a magnet is the right investment. + +A lead magnet earns investment when: + +- The audience exists in volume but is not yet on the list. Traffic without conversion is the gap a magnet fills. +- The product or service has a long consideration cycle. The list builds the relationship across the consideration window. +- The audience has a specific, immediate problem that a focused resource can address. Magnets work when the gap they fill is concrete. +- The follow-up sequence has a real purpose. Without a sequence that turns subscribers into something (customers, community members, qualified leads), the magnet is list-building theater. + +A lead magnet does NOT earn investment when: + +- The audience would convert directly without a magnet. SaaS with a free trial, ecommerce with a discount code, or freemium with a low-friction signup may not need a magnet between the visitor and the product. +- The team cannot commit to the follow-up. A list without a sequence is a list that decays. +- The topic is too broad to focus a single resource. "Marketing" is not a magnet topic; "the welcome-email template that 4x'd our trial-to-paid rate" is. +- Sales calls or demos are the next step. If the goal is a booked call, design the call-booking flow, not the magnet. + +The decision is not "should we have a magnet"; it is "is the magnet the right next investment for this specific audience and goal." + +Detail in [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md). + +--- + +## Thin-bait vs kitchen-sink-resource vs earned-value-magnet + +The keystone framing. + +Thin-bait. "10 tips for X" PDFs that are 200 words of fluff behind an email gate. The headline overpromises; the contents underdeliver. The reader downloads, skims, deletes, and unsubscribes within a week. The conversion-rate metric looks fine; the list quality and brand trust both degrade. Cost: every subscriber acquired through thin-bait costs more than they appear to, because the unsubscribe rate, the reduced sender reputation, and the reduced list-trust each compound. + +Kitchen-sink-resource. 80-page "Ultimate Guide" containing everything anyone could want about the topic. Includes nothing the reader actually needs RIGHT NOW. Bookmarked, never read, eventually forgotten. Cost: the magnet does not produce the moment of "I needed this and got it," which is the moment the relationship starts. Subscribers stay on the list out of inertia; the relationship never deepens; future emails get ignored. + +Earned-value-magnet. Solves a specific, immediate problem the reader has. Genuine standalone value, the kind that would be worth paying for if it were not free. Qualifies the lead by audience-fit. Warms the reader for a specific related offer that follows. The reader downloads, uses the resource, gets the result, and remembers the brand as the source of that result. + +The litmus test. Hand the magnet to a non-subscriber in the target audience. Watch them use it. Does the resource produce the promised outcome inside the time the reader was willing to spend? If yes, the magnet is earned-value. If the reader downloads and never opens, the magnet is thin-bait or kitchen-sink-resource regardless of how the headline reads. + +--- + +## Format selection + +Magnets come in formats. Each format has strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +Templates. A starting artifact the reader fills in or adapts. Strong for audiences who need to produce a specific deliverable (a brief, a spec, a pitch deck, an email). Strong because the value is immediate and concrete. Weak when the template is too generic to feel custom. + +Checklists. A sequence of items to verify or complete. Strong for audiences executing a known process where the gap is comprehensiveness, not direction. Strong because the format signals "you can use this in 10 minutes." Weak when the checklist reads as marketing rather than as a working tool. + +Swipe files. A curated collection of examples (subject lines, headlines, ad copy, design references). Strong for audiences who learn from examples and need inspiration rather than instruction. Weak when the swipes are stale or unattributed. + +Mini-courses. A multi-part email or video sequence delivering structured learning. Strong for audiences willing to invest sequential attention; strong because the sequence creates multiple touchpoints. Weak when the course is filler or when each lesson does not stand on its own. + +Free tools (calculators, quizzes, generators). Interactive web tools that produce a result. Strong for audiences who want a personalized output rather than a generic resource. Strong because the interaction qualifies the lead by inputs. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Ebooks. Long-form treatment of a topic. Strong for audiences researching a complex decision; strong when the ebook reads as a definitive resource. Weak when used as a default format for topics that would have served the reader better as a checklist or template. + +Video series. Sequential video content delivered behind a gate. Strong for topics that benefit from demonstration; strong for audiences who learn from video. Weak when the production overhead exceeds the topic's value or when the audience does not consume video content at the time-of-magnet moment. + +The choice depends on the audience's preferred consumption mode, the topic's natural shape, and the production overhead the team can sustain. A great template often outperforms a mediocre ebook on the same topic. + +Detail in [`references/format-selection-patterns.md`](references/format-selection-patterns.md). + +--- + +## The "would they pay for this" test + +The single test that distinguishes earned-value from thin-bait. + +The question. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails this test is signaling that the value is below the threshold of "I would pay for this," which means the reader's time investment to download and consume it is at the edge of "worth it." + +The test is not perfect. Some valuable resources are hard to price (how much is a great checklist worth?). But the test catches the magnets that exist primarily to capture an email rather than to deliver value. + +Three failure modes the test catches. + +- The 5-page PDF that summarizes blog content. Free elsewhere; not pay-worthy. +- The "Ultimate Guide" that nobody finishes. Pay-worthy in theory; not delivered in usable form. +- The template that is so generic it adds no value over starting from scratch. Pay-worthy framing; thin in execution. + +The test the magnet should pass. + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +If the magnet passes the test, it earns the email. If it fails, redesign before launching. + +Detail in [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md). + +--- + +## Audience-fit qualification + +The magnet as filter, not just bait. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). + +Filter through the headline. The headline tells the wrong audience to opt out. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, and consumer-app PMs. The conversion rate from the visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +Filter through the topic. A magnet on a niche topic attracts a niche audience. Generic topics attract generic audiences who churn off the list. Specific topics attract specific audiences who stay. + +Filter through the format. A 60-minute video course filters out audiences who will not invest 60 minutes. A 2-page checklist filters in audiences who want quick wins. The format signals what the brand expects of the relationship. + +Filter through the offer adjacent to the magnet. The follow-up sequence often makes a soft offer for a related product or service. The magnet should be tightly enough scoped that the audience who downloads it is also the audience who would consider the adjacent offer. + +The filtering principle. A magnet that converts 50 percent of visitors but produces 5 percent qualified leads is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. Optimize for the qualified lead, not for the surface conversion rate. + +Detail in [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md). + +--- + +## Title and presentation discipline + +The magnet's title is the conversion lever and the qualification filter at the same time. + +Title patterns that work. + +- Specific outcome + specific audience. "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." +- Specific deliverable + specific situation. "The pricing one-pager for SaaS founders raising a seed round." +- Specific framework + specific problem. "The 4-question framework for deciding whether to fire a customer." +- Specific count + specific value. "23 onboarding emails, with the open and click rate for each." + +Title patterns to avoid. + +- "Ultimate Guide to X." Vague. Promises too much. Underdelivers reliably. +- "The Complete X Playbook." Same failure mode. Promises completeness; delivers volume. +- "Free [Topic] Resource." Generic. Tells the reader nothing about why this resource is the one to download. +- "10 Tips for Better X." Listicle framing signals thin content. + +Presentation discipline beyond the title. + +- The cover or preview image should reinforce the specificity. A clean type-driven cover often outperforms a cluttered one. +- The landing page (handled by `landing-page-copy`) should preview the magnet, not just describe it. +- The first page of the magnet should deliver value within the first read, not warm up with author bio and brand-positioning. + +Detail in [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md). + +--- + +## Delivery and follow-up sequence design + +The sequence is the magnet's second act. Without it, the magnet is one transaction; with it, the magnet starts a relationship. + +The delivery moment. The reader fills the form and expects the resource immediately. Delivery delay (manual review, scheduled send) breaks the moment. The first email should deliver the asset and confirm the next step. + +The first 7 days. The reader is most engaged in the days right after download. The sequence should make use of that window: a follow-up that helps them apply the resource, a related artifact that extends the value, a soft introduction to the brand and the next step. + +The medium-term. Days 8 to 30, the sequence transitions from "value-add" to "ongoing relationship." Newsletter signup, related-content rotation, or a soft offer for the adjacent product or service. + +The honest offer. When the sequence makes an offer, the offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course; the audience signal would be wasted. + +The opt-out. A reader who unsubscribes from the magnet sequence is not a failure; they are a clean filter. The list quality stays higher when the unfit subscribers leave on their own. + +Detail in [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md). + +--- + +## Format-specific quality gates + +Each format has quality gates specific to that format. A great template fails different tests than a great mini-course. + +Template gates. Does the reader produce a usable artifact in under 30 minutes? Are the prompts specific enough to feel custom? Is the template adaptable across the segment of the audience or rigidly bound to one situation? + +Checklist gates. Is each item actionable today? Does the checklist sequence reflect actual workflow order? Is the checklist scoped narrowly enough to feel comprehensive within scope? + +Swipe file gates. Are the swipes attributed (where possible)? Are they current (not 5 years stale)? Is the curation visible (the reader can see why each swipe is included)? + +Mini-course gates. Does each lesson deliver standalone value (not "you will learn the answer in lesson 4")? Is the cumulative time commitment honest in the title? Does the course end with a clear next step (not just "thanks for taking the course")? + +Calculator and quiz gates. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Ebook gates. Is the ebook navigable (table of contents, page numbers, summary boxes) such that a reader who does not finish still extracts value? Is the production quality consistent with the brand it represents? + +Video series gates. Is each video shot at a quality the brand can sustain? Is the audio consistently clear? Is the runtime honest in the listing? + +Each format's gates exist because thin-bait can hide in any format. The quality gates make hiding harder. + +Detail in [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md). + +- "Conversion rate is great, list quality is terrible." Thin-bait pattern; magnet attracts the wrong audience or fails to deliver the promised value. +- "We ship a magnet; nothing happens after." No follow-up sequence; the magnet is one transaction rather than the start of a relationship. +- "Our 80-page Ultimate Guide gets downloaded but never read." Kitchen-sink-resource; comprehensive in scope, useless in application. +- "We changed the format from PDF to webinar; conversion rate dropped." Format mismatched to audience; the audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. +- "The magnet works in paid traffic but not organic." The audience reaching the magnet through paid is different from the organic audience; the magnet may fit one but not the other. +- "Subscribers go cold after the first email." Sequence absent or poorly designed; the value evaporates after delivery. +- "We have 5 magnets; one converts well, the others are dead." Magnet portfolio not maintained; audiences move and topics decay; periodic audit missing. +- "The follow-up offer mismatches the magnet's audience." Magnet attracted one segment; offer pitches a different one; conversion to the offer near zero. +- "We cannot tell which traffic source produces qualified leads." Attribution missing or rolled up at the wrong level; lead-quality signal not connected back to source. +- "The team built three magnets last quarter; the team avoids talking about results." Magnets shipped without success metric definition; results ambiguous or quietly underwhelming. + +--- + +## The framework: 12 considerations for lead magnet design + +When designing or auditing a lead magnet, walk these 12 considerations. + +1. The magnet decision. Is a magnet the right investment for this audience and goal, or does the funnel work without one? +2. Earned-value, not thin-bait or kitchen-sink-resource. The magnet would be worth paying for; it solves a specific problem in usable form. +3. Format matched to audience and topic. The format reflects how the audience consumes content and how the topic naturally shapes. +4. The "would they pay for this" test. Pass before launching. +5. Audience-fit qualification. The magnet filters for the right audience, not just maximum conversion. +6. Title and presentation discipline. Specific, honest, signals what is inside. +7. Delivery in the moment. First email arrives immediately; the asset is in that email. +8. Follow-up sequence designed. The 30 days after download have a purpose, an arc, and a soft offer that matches the audience. +9. Format-specific quality gates passed. The format's specific tests verified before launch. +10. Lead quality measured, not just conversion rate. What percentage of subscribers fit the audience the magnet was designed for? +11. Attribution to source. The team can tell which source produced which leads at which quality. +12. Audit cadence. The magnet portfolio gets reviewed periodically; underperformers retired. + +The output of the framework is a lead magnet that earns the email by delivering real value, qualifies the audience by filtering at the headline and topic level, and starts a relationship through a sequence the team has actually designed. + +--- + +## Reference files + +- [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md) - When a lead magnet is the right investment and when it is not. The conditions that make magnets worth the build. +- [`references/format-selection-patterns.md`](references/format-selection-patterns.md) - Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit, conversion baselines. +- [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md) - The pricing thought experiment that distinguishes earned-value from thin-bait. Worked examples and failure modes. +- [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md) - The magnet as filter. Filtering through headline, topic, format, and follow-up offer. +- [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md) - Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. +- [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md) - Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. +- [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md) - Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. +- [`references/lead-magnet-anti-patterns.md`](references/lead-magnet-anti-patterns.md) - The patterns that look like lead magnets but do not behave like them. +- [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: magnets earn the email when they earn the reader's afternoon + +The magnets that work as compounding assets are the ones the reader uses. Not downloads. Not bookmarks. Uses. The reader opens the resource, applies it, and gets a result they would have paid for if they had to. + +That is the bar. Below the bar is thin-bait (the resource is too thin to use) or kitchen-sink-resource (too much to consume). Above the bar is the relationship: the reader remembers the brand as the source of the result, opens the next email, and considers the offer when it comes. + +The discipline is in the design choices upstream of the form. The format matched to the audience and topic. The title that filters and earns. The pricing thought experiment that catches the thin magnets before launch. The follow-up sequence designed before the magnet ships, not after. The audit cadence that retires the magnets that stopped working. + +When in doubt, ask: would the audience pay for this if it were not free, and will the team commit to the sequence after the download? If yes to both, the magnet earns the email. If no to either, redesign or do not ship. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md b/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md new file mode 100644 index 0000000..7278886 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/audience-fit-qualification.md @@ -0,0 +1,171 @@ +# Audience-fit qualification + +The magnet as filter, not just bait. Filtering through headline, topic, format, and follow-up offer. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). The filtering is the difference between a list that grows and a list that grows in the right direction. + +--- + +## The filtering principle + +The magnet's job is not to maximize email captures. It is to maximize qualified email captures. + +A magnet that converts 50 percent of visitors but produces 5 percent qualified leads (visitors who match the audience the magnet was designed for) is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. The qualified-lead-rate metric matters more than the surface conversion rate. + +The filtering happens at multiple points: the headline, the topic, the format, the landing-page copy, and the follow-up offer. Each is a filter that lets in the right audience and turns away the wrong one. + +--- + +## Filter through the headline + +The headline is the first filter. The right audience self-selects in; the wrong audience self-selects out. + +Specific outcome plus specific audience. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, consumer-app PMs. The conversion rate from visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +Specific situation. "The pricing one-pager for SaaS founders raising a seed round" filters out everyone except SaaS founders raising a seed round. That is a tiny audience; the audience that converts is exactly the audience the brand wants. + +Specific deliverable. "The 23-email sequence we send to trial signups who go cold" filters in PMs, growth marketers, and founders running SaaS funnels. Filters out everyone else. + +The headline test. Read the headline. Who in the broader audience self-selects out? If the answer is "no one, anyone might want this," the headline is not filtering. Generic headlines attract generic audiences; specific headlines attract specific audiences. + +--- + +## Filter through the topic + +The topic itself filters before the headline polishes the message. + +Niche topics attract niche audiences. "Pricing for B2B SaaS founders raising a seed round" is a topic that filters by definition. The audience for this topic is small but precise. + +Generic topics attract generic audiences. "Marketing tips" attracts everyone, which means it attracts no one specifically. The list grows; the lead quality dilutes. + +The topic-segmentation question. What audience segment is this topic specifically valuable for? If the answer is "everyone," the topic is too broad. Narrow until the answer is "the segment we want to serve." + +Topic-narrowing examples. + +- Too broad: "Email marketing tips." +- Narrowed: "Welcome-email sequences for B2B SaaS trials." +- Narrowed further: "The 7-email welcome sequence for B2B SaaS trials in the 5-50 employee segment." + +Each narrowing reduces the addressable audience and increases the qualification of those who convert. + +--- + +## Filter through the format + +The format signals what the brand expects of the relationship. + +A 60-minute video course filters out audiences who will not invest 60 minutes. This is sometimes the right filter (for high-investment audiences) and sometimes the wrong one (for skim-and-apply practitioners). + +A 2-page checklist filters in audiences who want quick wins. This is often the right filter for practitioners executing known processes. + +A free tool with detailed inputs filters in audiences with concrete situations the tool addresses. The inputs themselves qualify the lead. + +An 80-page ebook filters in audiences researching a complex decision. Filters out audiences seeking quick artifacts. + +The format choice should match the audience the magnet is designed to attract. A mismatch (a 60-minute course for a skim audience, a 2-page checklist for an in-depth research audience) breaks the filter. + +--- + +## Filter through the landing-page copy + +The landing page is the magnet's marketing layer. It filters by amplifying the headline and topic signals. + +Audience-specific copy. "For SaaS founders" beats "For founders" beats "For everyone." Each audience-specific cue filters. + +Situation-specific copy. "If you are scaling from 100 to 1000 customers, here is the playbook." Filters by situation. + +Result-specific copy. "After implementing this template, our trial-to-paid rate moved from 8 percent to 14 percent." Filters by who cares about that result. + +Anti-filter copy. "This is for everyone in marketing." Generic. No filter. Attracts the wrong audience and dilutes the list. + +The landing page should sharpen the filter the headline and topic establish, not dilute it. + +--- + +## Filter through the follow-up offer + +The follow-up offer is the late-stage filter. The audience who downloads the magnet and then engages with the offer is the audience the program needs to compound. + +Offer-magnet alignment. A magnet on B2B onboarding should be followed by an offer relevant to B2B teams. A misalignment (a magnet on B2B onboarding followed by an offer for consumer-app courses) wastes the qualification the magnet did. + +Offer-audience alignment. The offer should fit the audience the magnet attracted. If the magnet attracted SaaS founders and the offer is for enterprise sales teams, the audience signal is wasted. + +Offer-stage alignment. A top-of-funnel magnet should be followed by an offer at the right consideration stage (not "buy now" 3 emails after download for a high-ticket product). + +The follow-up offer's conversion rate is the qualification metric that matters most. A list that engages with the offer is a list the magnet qualified well. + +--- + +## The qualified-lead metric + +Beyond conversion rate, qualified-lead rate is the metric the magnet's filter should be measured by. + +Definition. Of the subscribers acquired through the magnet, what percentage match the audience profile the magnet was designed for? + +Measurement methods. + +- Self-reported segment data. Capture audience-segment data on the form (company size, role, industry). Measure the percentage that match. +- Email engagement. Measure open and click rates on follow-up emails relevant to the target audience. Low engagement signals audience mismatch. +- Downstream conversion. Measure conversion to the next step (trial, demo, purchase). Low downstream conversion despite high upstream engagement signals audience mismatch. + +The qualified-lead-rate target. Programs vary, but 40-70 percent of subscribers matching the target audience is a reasonable bar for a well-filtered magnet. Below 30 percent suggests the filter is broken; above 70 percent suggests the filter may be too narrow (and the magnet may be missing audience the brand could serve). + +--- + +## When to widen the filter, when to narrow + +Filter-tuning is part of the magnet's lifecycle. + +Widen the filter when: + +- Conversion rate is healthy but the audience the brand serves is broader than the magnet captures. +- The qualified-lead rate is high (suggesting the filter could let in more without sacrificing quality). +- The team is launching a broader product or service that fits a wider audience. + +Narrow the filter when: + +- Lead quality is diluting (the magnet attracts subscribers who do not match the brand's offering). +- The follow-up sequence's engagement is low because the audience does not match the offers. +- The team is focusing on a specific segment and wants the magnet to filter for it. + +The discipline. Filter tuning is iterative. The magnet's headline, topic, and follow-up can be adjusted to widen or narrow the filter as the program evolves. + +--- + +## Common filter failures + +The headline does not filter. Generic title; attracts everyone; lead quality dilutes. + +The topic is too broad. "Marketing" rather than "B2B SaaS pricing." Generic topic; generic audience. + +The format is mismatched. A long-form video for a skim audience; the wrong audience self-selects. + +The landing page softens the filter. Audience-specific headline followed by generic landing-page copy that anyone could read; the filter weakens. + +The follow-up offer mismatches. Magnet attracts one audience; offer pitches a different one; downstream conversion drops. + +The team measures conversion rate but not lead quality. The surface metric looks fine; the real metric (qualified-lead rate) is unmeasured; the magnet looks like a success while the list quality degrades. + +The pattern across failures: the team optimizes for the easier metric (conversion rate) and loses the harder metric (qualified-lead rate). The discipline is to measure both and to tune for the lead quality the program needs. + +--- + +## The high-conversion-low-quality trap + +A magnet can convert at exceptional rates while producing terrible lead quality. The trap surfaces when the team celebrates the conversion rate and ignores the downstream signal. + +The pattern. A generic, broadly-appealing magnet ("Marketing Tips for 2026") converts at 25 percent. The list grows quickly. The follow-up sequence sees low engagement; the offers convert at near-zero rates; the unsubscribe rate is high. + +The diagnosis. The magnet attracted everyone, including audiences the brand cannot serve. The high conversion rate masked the low lead quality. + +The fix. Narrow the magnet's filter. The conversion rate will drop; the lead quality will rise; the program's compounding metric (qualified-lead growth) will improve. + +--- + +## Methodology-level choices that stay in the public skill + +The filtering principle. Filter through headline, topic, format, landing-page, and follow-up offer. The qualified-lead metric and how to measure it. When to widen and when to narrow. The high-conversion-low-quality trap. Common filter failures. + +## Implementation choices that stay internal + +Specific filter-tuning conventions for the team's audience. Specific qualified-lead-rate baselines for specific magnets. Specific segment-data capture methods on forms. Specific tooling for engagement and downstream-conversion measurement. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md b/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md new file mode 100644 index 0000000..30ea197 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/common-lead-magnet-failures.md @@ -0,0 +1,187 @@ +# Common lead magnet failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the magnet underperformed" or "the list is not converting" or "we cannot tell if the magnet worked." + +--- + +## "Conversion rate is great, list quality is terrible." + +The diagnosis. Thin-bait pattern. The magnet attracts the wrong audience or fails to deliver promised value. Conversion-rate metric looks fine because the form converted; the lead quality metric (which is the metric that matters for downstream conversion) is poor. + +The cure. Apply the "would they pay for this" test (`references/would-they-pay-for-this-test.md`). Apply audience-fit qualification (`references/audience-fit-qualification.md`). Strengthen the magnet until it earns the email rather than baits it. + +--- + +## "We ship a magnet; nothing happens after." + +The diagnosis. No follow-up sequence. The magnet is one transaction rather than the start of a relationship. + +The cure. Design the sequence before shipping the magnet (`references/delivery-and-follow-up-sequences.md`). The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## "Our 80-page Ultimate Guide gets downloaded but never read." + +The diagnosis. Kitchen-sink-resource pattern. Comprehensive in scope, useless in application. The reader cannot consume the resource in the time they were willing to spend. + +The cure. Narrow the topic until the magnet addresses one specific problem in usable form. The 80-page guide often becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## "We changed the format from PDF to webinar; conversion rate dropped." + +The diagnosis. Format mismatched to audience. The audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. + +The cure. Format selection (`references/format-selection-patterns.md`). Match the format to the audience's preferred consumption mode and the topic's natural shape. The format change might still be right (if the new format better serves a different segment) but the metric drop is signal. + +--- + +## "The magnet works in paid traffic but not organic." + +The diagnosis. The audience reaching the magnet through paid is different from the organic audience. The magnet may fit one but not the other. + +The cure. Understand the audience differences. Paid traffic often has different intent and different audience composition than organic. The magnet may need a separate version for each, or the magnet may need to be retitled to match the actual audience reaching it. + +--- + +## "Subscribers go cold after the first email." + +The diagnosis. Sequence absent or poorly designed. The value evaporates after delivery. + +The cure. Design the first-7-days arc to add value progressively (`references/delivery-and-follow-up-sequences.md`). Each email should add something the reader can use; the cumulative arc deepens the relationship. + +--- + +## "We have 5 magnets; one converts well, the others are dead." + +The diagnosis. Magnet portfolio not maintained. Audiences move and topics decay; the periodic audit is missing. + +The cure. Audit the portfolio (`references/lead-magnet-anti-patterns.md`, "How to detect anti-patterns in the portfolio"). Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## "The follow-up offer mismatches the magnet's audience." + +The diagnosis. Magnet attracted one segment; offer pitches a different one. The audience signal the magnet captured was wasted. + +The cure. Align the offer to the audience the magnet attracts (`references/delivery-and-follow-up-sequences.md`, "The offer-magnet alignment"). If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## "We cannot tell which traffic source produces qualified leads." + +The diagnosis. Attribution missing or rolled up at the wrong level. Lead-quality signal is not connected back to source. + +The cure. Capture source attribution at the form level. Measure lead quality (audience-fit, downstream conversion) per source. The diagnostic data informs which sources warrant further investment. + +--- + +## "The team built three magnets last quarter; the team avoids talking about results." + +The diagnosis. Magnets shipped without success metric definition. Results ambiguous or quietly underwhelming. + +The cure. Define the success metric before building (`references/lead-magnet-decision-criteria.md`, "The success metric is defined"). What does "the magnet worked" look like? Without the definition, evaluation is impossible and underperformers do not get retired. + +--- + +## "Downloads are high; trial signups are unchanged." + +The diagnosis. The magnet captures emails but does not move the downstream metric the team cares about. Either the magnet's audience does not match the trial-buying audience, or the sequence does not bridge to the offer. + +The cure. Trace the funnel from magnet download to trial signup. Identify the drop. The drop is often at the offer step (audience misalignment) or at the sequence step (no clear path from magnet to offer). + +--- + +## "The magnet got shared on social; we got 1000 subscribers; none converted." + +The diagnosis. The magnet's distribution outpaced its audience-fit. A viral magnet attracts an audience that does not match the brand's offer. + +The cure. This is a design tradeoff. Shareable magnets are great for reach but often produce diluted lead quality. Either accept the dilution and have a long path to qualification, or design the magnet to be less shareable but more audience-specific. + +--- + +## "We tried 12 different titles; conversion rate did not move." + +The diagnosis. Title testing without addressing the underlying audience-fit. The title is the surface; the audience-fit is the substance. If the substance is wrong, no title fixes it. + +The cure. Step back from title testing. Apply the audience-fit qualification (`references/audience-fit-qualification.md`). The title can amplify a strong audience-fit; it cannot create one. + +--- + +## "The magnet's references are stale and conversion is dropping." + +The diagnosis. Magnet decay. Screenshots, statistics, tooling references go out of date. The reader notices and engagement drops. + +The cure. Maintenance discipline (`references/lead-magnet-decision-criteria.md`, "When to retire a magnet"). Quarterly review for active magnets. Update or retire when references decay. + +--- + +## "We have a great magnet; the landing page does not convert." + +The diagnosis. The magnet is strong but the landing page (which is `landing-page-copy`'s domain) does not preview the value, frame the audience, or close the visitor. + +The cure. Apply landing-page-copy discipline. Show pages from inside the magnet. Frame the audience explicitly. Make the conversion action obvious and the friction minimal. + +--- + +## "The magnet got featured in [a major newsletter]; we lost the signal we built." + +The diagnosis. A traffic spike from a misaligned audience can dilute the qualified-lead-rate metric. The featured audience may not match the brand's offer. + +The cure. Distinguish "qualified subscriber" from "any subscriber" in the metric. The traffic spike grew the list; the qualified list grew less. The signal is intact; the metric needs disaggregation. + +--- + +## "We cannot keep the sequence content fresh." + +The diagnosis. The sequence's content needs ongoing maintenance. The team did not budget for it. + +The cure. Either reduce the sequence to evergreen content the team can sustain, or accept the maintenance cost as part of the magnet's true cost. Quarterly review of every active sequence (`references/delivery-and-follow-up-sequences.md`, "The maintenance discipline"). + +--- + +## "The magnet had great reviews; the lead-quality metric is mediocre." + +The diagnosis. Reviews are signal about the resource's quality. Lead quality is signal about the audience-fit. The two are different. A great resource for the wrong audience produces good reviews and mediocre lead quality. + +The cure. Audience-fit qualification (`references/audience-fit-qualification.md`). The magnet may need a tighter filter at the title and topic level, even if the resource itself is strong. + +--- + +## "We built a magnet for our PMM team's pet topic; nobody downloaded." + +The diagnosis. Vanity-magnet pattern. The topic was chosen for internal interest, not audience need. + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. + +--- + +## "The team ships magnets every quarter; conversion rate is the only metric we track." + +The diagnosis. Single-metric tracking misses lead quality, sequence engagement, downstream conversion, and retention. The conversion rate can look fine while the broader signal is weak. + +The cure. Multi-metric tracking. Conversion rate, qualified-lead rate, sequence engagement, downstream conversion, and unsubscribe rate together tell the story. Single-metric tracking misleads. + +--- + +## The pattern across failures + +Most lead magnet failures fall into one of three patterns. + +Pattern 1: The magnet does not deliver value. Thin-bait, kitchen-sink, undelivered-promise. The fix is to strengthen or kill the magnet. + +Pattern 2: The magnet attracts the wrong audience. Everyone-magnet, viral-but-misaligned, vanity-magnet. The fix is to tighten the filter or reframe the audience. + +Pattern 3: The relationship after the download fails. Orphan-magnet, sequence-too-short, misaligned-offer, follow-up-spam. The fix is to design the sequence with as much care as the magnet itself. + +The metric pattern: lead magnet failures often look fine on the conversion rate. The signal is in the lead quality, the sequence engagement, and the downstream conversion. Programs that track only the conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, relationship). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md b/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md new file mode 100644 index 0000000..1354ac6 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md @@ -0,0 +1,188 @@ +# Delivery and follow-up sequences + +Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. The sequence is the magnet's second act; without it, the magnet is one transaction. + +A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams that build the magnet but skip the sequence capture emails that go cold. + +--- + +## The delivery moment + +The reader fills the form and expects the resource immediately. The first email confirms the moment. + +What the delivery email should do. + +- Deliver the asset directly (link, attachment, or in-line content). The reader did not opt in to wait. +- Confirm the audience-fit signal. Acknowledge what the reader is here for. +- Set up the next email. "I will send you [related artifact] tomorrow" creates a hook for the next touchpoint. +- Avoid friction. No double opt-in unless required by jurisdiction. No survey-before-asset. The reader gets the resource first. + +What the delivery email should NOT do. + +- Make an offer. The reader has not yet experienced the magnet's value; offering anything is premature. +- Bury the asset. The link or attachment should be near the top, not after three paragraphs of brand-positioning. +- Apologize for the email. "Thanks for downloading, here is your resource" without filler is honest. + +Delivery delay risk. Delays of more than 5 minutes break the moment. Manual review, scheduled sends, or batch processing all introduce delay. Automate the delivery to minimize lag. + +--- + +## The first 7 days arc + +The reader is most engaged in the days right after download. The sequence should make use of that window. + +Day 0: Delivery. Asset in hand. The reader can act on the magnet immediately. + +Day 1-2: Application help. A follow-up that helps the reader apply the resource. "The 3 things people miss when implementing the [magnet]" or "the worked example we use ourselves." Adds value to the magnet without yet pitching anything. + +Day 3-4: Adjacent value. A related artifact, case study, or insight that extends the magnet's value. Reinforces the brand as a source of useful resources. + +Day 5-7: Soft introduction to the brand. Who the team is, what they work on, what kinds of problems they solve. Soft framing of the next step (newsletter signup, related product, demo). + +The 7-day arc principle. Every email in the first 7 days should add value, not extract. The relationship is being built; extraction breaks the trust the magnet earned. + +--- + +## The medium-term sequence + +Days 8-30, the sequence transitions from "value-add" to "ongoing relationship." + +The transition options. + +- Newsletter signup. Move the subscriber to the regular newsletter cadence. The relationship continues at the brand's normal pace. +- Related-content rotation. A series of additional resources, case studies, or insights related to the magnet's topic. The subscriber stays engaged in the topic area. +- Soft offer for the adjacent product or service. A demo invitation, a trial signup, a case study of a similar customer. The offer matches the audience the magnet attracted. + +The honest offer principle. The offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course. The audience signal would be wasted. + +The hard-sell trap. Some sequences pivot too early to hard selling, before the reader has had time to recognize the value. The early hard sell breaks trust. The discipline is to earn the right to pitch through demonstrated value first. + +--- + +## The offer-magnet alignment + +The offer that follows the magnet must match the audience the magnet attracted. + +Worked example: aligned offer. + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: SaaS founders, growth marketers, and PMs running SaaS funnels. +The offer: a B2B SaaS lifecycle email tool with a 14-day trial. + +The audience the magnet attracted is the audience the offer serves. The conversion to trial is high relative to baseline. + +Worked example: misaligned offer. + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: as above. +The offer: a marketing analytics platform aimed at enterprise marketing teams. + +The audience the magnet attracted is not the audience the offer serves. The conversion to demo is near zero. The audience signal was wasted. + +The alignment discipline. Before designing the magnet, identify the offer the magnet's audience will be pitched. If the offer does not exist or does not match, redesign the magnet (or the offer) before shipping. + +--- + +## The clean opt-out + +A reader who unsubscribes from the magnet sequence is not a failure. They are a clean filter. + +The principle. The list quality stays higher when the unfit subscribers leave on their own. A subscriber who is not the right audience for the offer is a subscriber whose engagement will be low; their unsubscribe is signal, not loss. + +The mechanics. + +- Make unsubscribe easy. One-click is honest; multi-step is friction the brand pays for in trust. +- Do not interrogate on the way out. "We are sorry to see you go, please answer 3 questions" is friction. +- Acknowledge the unsubscribe gracefully. The reader was a subscriber; they should leave with the brand intact. + +The unsubscribe-as-feedback loop. High unsubscribe rates after specific emails signal that the email did not match the audience or the value proposition. The signal informs sequence revision. + +--- + +## Sequence cadence considerations + +How frequently to send. + +Day 0-7: daily or every-other-day is honest. The reader just downloaded; engagement is high; the sequence can use the window without feeling spammy. + +Day 8-30: 2-4 emails per week is reasonable. Frequency depends on the value being delivered; if each email adds value, higher frequency is sustained. + +Day 30+: settle into the brand's normal cadence. Newsletter weekly, monthly, or per-publication. Whatever the brand sustains. + +Cadence-too-frequent risk. Daily emails for 30+ days exhaust the reader. The unsubscribe rate climbs. + +Cadence-too-infrequent risk. Weekly cadence in the first 7 days lets the magnet's momentum fade. The reader downloads, applies, and forgets the brand. + +--- + +## Sequence-engagement measurement + +The sequence's metrics surface whether the magnet did its qualifying job. + +Open rates. The audience opens what is interesting to them. Low open rates after the first email signal audience mismatch or sequence-content mismatch. + +Click-through rates. Clicks signal interest in specific content or offers. Low click-through on the offer email signals offer-magnet misalignment. + +Conversion to next step. Trials, demos, purchases. The downstream metric that matters most. Low conversion despite high engagement signals offer mismatch or pricing-mismatch. + +Unsubscribe rates. A reasonable rate (2-5 percent over the first 30 days) is normal. Higher rates signal cadence mismatch or audience mismatch. + +The metrics together tell the story. The sequence either qualifies and converts the audience the magnet attracted, or it surfaces the mismatch the magnet missed. + +--- + +## When the sequence fails + +The sequence sends; engagement drops; conversion is low. The diagnosis often surfaces magnet-side failures. + +Diagnosis: the magnet attracted the wrong audience. The sequence's content is right for the audience the magnet was designed for, but the audience the magnet actually attracted is different. The fix is upstream: tighten the magnet's filter. + +Diagnosis: the offer is misaligned. The audience is right; the offer does not match. The fix is to change the offer (or the magnet, if the offer is fixed). + +Diagnosis: the sequence is too long or too frequent. Engagement starts strong and drops as fatigue sets in. The fix is to trim the sequence or space the emails. + +Diagnosis: the sequence's value drops off. The first emails added value; the later emails became repetitive or extractive. The fix is to redesign the later emails to continue adding value. + +Diagnosis: the sequence's tone shifted. The early emails were honest; the later emails became salesy. The fix is to restore the honest tone. + +The sequence is part of the magnet's design. Failures in the sequence often surface as conversion-rate or engagement metrics, but the fix is sometimes upstream in the magnet itself. + +--- + +## The maintenance discipline + +Sequences decay. Email links break, references go stale, offers change. + +The maintenance cadence. Quarterly review of every active sequence. Are links working? Are references current? Does the offer at the end still match the brand's current product or service? + +Stale-sequence risk. A subscriber who clicks a broken link or sees a reference to a discontinued product disengages immediately. The brand looks careless. + +The retire decision. Sequences for retired magnets should be retired. Subscribers acquired through the magnet should be moved to the appropriate ongoing sequence (newsletter or other). + +--- + +## Common sequence failures + +No sequence. The magnet ships; subscribers download; nothing follows. The list goes cold. + +Sequence too short. 2-3 emails and done. The relationship does not deepen. + +Sequence too long. 30+ emails over months. Subscribers fatigue. + +Sequence pivots to hard sell too early. The trust the magnet earned gets spent before the value has been demonstrated. + +Offer misaligned. Magnet attracts one audience; offer pitches another. + +Stale references. Links break; product names changed; case studies outdated. + +Cadence mismatch. Too frequent or too infrequent for the engagement the audience can sustain. + +--- + +## Methodology-level choices that stay in the public skill + +The delivery moment principles. The first-7-days arc. The medium-term transition. The offer-magnet alignment principle. The clean opt-out. Cadence considerations. Sequence-engagement measurement. Diagnostic patterns when the sequence fails. The maintenance discipline. + +## Implementation choices that stay internal + +Specific email copy for specific magnets. Specific sequence templates the team uses. Specific tooling for delivery automation, sequence platforms, and engagement measurement. The team's cadence baselines. Specific offer-design choices for specific products. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md b/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md new file mode 100644 index 0000000..97e7ce8 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/format-selection-patterns.md @@ -0,0 +1,245 @@ +# Format selection patterns + +Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +A great template often outperforms a mediocre ebook on the same topic. The format is half the design decision; the topic is the other half. + +--- + +## Templates + +A starting artifact the reader fills in or adapts. + +Strengths. + +- Immediate, concrete value. The reader produces a usable artifact in minutes. +- High perceived value because the artifact is practical. +- Strong audience signal: people who download templates are people who execute, not just consume. +- Sustainable production: a single template, well-designed, can serve thousands of downloads with minimal updating. + +Weaknesses. + +- Generic templates feel useless; the bar for "custom enough" is high. +- The format does not work when the deliverable is non-standardizable (the reader's context varies too much for a template to fit). +- Distribution can be tricky if the template requires specific tools (a Notion template is unusable to teams not on Notion). + +Audience-fit signals. + +- Strong fit: practitioners who produce specific deliverables (specs, briefs, plans, decks, sequences). +- Weak fit: strategic readers who want frameworks rather than artifacts. + +Conversion-rate baseline. Templates often convert 3-12 percent on landing pages with reasonable traffic-fit. The high end is for templates that signal exceptional specificity in the title. + +Production overhead. Moderate. A polished template often takes 8-20 hours including design, instructions, and worked example. + +--- + +## Checklists + +A sequence of items to verify or complete. + +Strengths. + +- Fast to consume, fast to apply. Reader gets value in 10-20 minutes. +- Format signals "you can use this today." +- Strong for processes where the gap is comprehensiveness rather than direction (the reader knows what to do; the checklist verifies they did not miss steps). + +Weaknesses. + +- Easy to make thin. A 12-item generic checklist reads as marketing rather than a working tool. +- Sequence matters; an unordered checklist on a process is less useful than the same items in workflow order. +- Limited topic range; checklists fit verification-style tasks, not strategy-style decisions. + +Audience-fit signals. + +- Strong fit: practitioners executing known processes who need verification (launch checklists, audit checklists, onboarding checklists). +- Weak fit: strategic decisions where each situation differs. + +Conversion-rate baseline. Strong checklists convert 5-15 percent. The format signals quick wins, which lifts conversion. + +Production overhead. Low to moderate. 4-12 hours including design and field-testing. + +--- + +## Swipe files + +A curated collection of examples (subject lines, headlines, ad copy, design references, email templates). + +Strengths. + +- High perceived value. The reader gets a body of work to study and adapt. +- Strong for audiences who learn from examples rather than instruction. +- Often shareable; readers tell peers about a strong swipe file. + +Weaknesses. + +- Requires curation discipline; a 200-item swipe file with no commentary is less useful than 30 swipes with curation notes. +- Decays faster than templates or frameworks; swipes go stale as conventions change. +- Attribution matters; uncredited swipes can be perceived as theft. + +Audience-fit signals. + +- Strong fit: copywriters, designers, marketers, and creators who need inspiration plus example. +- Weak fit: audiences seeking instruction or process. + +Conversion-rate baseline. Strong swipe files convert 4-12 percent. + +Production overhead. Moderate to high. 12-30 hours including curation, attribution, and commentary. + +--- + +## Mini-courses + +A multi-part email or video sequence delivering structured learning. + +Strengths. + +- Multiple touchpoints, which deepens the relationship. +- Sequential structure can take the reader from "novice" to "competent" on a topic. +- The course format can charge implicit time investment, which qualifies the lead as serious. + +Weaknesses. + +- Each lesson must stand on its own; "the answer is in lesson 4" loses the reader by lesson 2. +- Production overhead is significant. +- Completion rates are honestly low (often 10-30 percent finish), which limits the cumulative value delivered. + +Audience-fit signals. + +- Strong fit: audiences willing to invest sequential attention and seeking structured learning. +- Weak fit: audiences who want quick wins or specific artifacts. + +Conversion-rate baseline. 3-10 percent. Lower than templates or checklists because the perceived time commitment is higher. + +Production overhead. High. 30-100 hours for a 5-7 lesson course depending on format. + +--- + +## Free tools (calculators, quizzes, generators, configurators) + +Interactive web tools that produce a personalized result. + +Strengths. + +- Highest perceived value among magnet types when the tool genuinely helps. +- Personalization makes the result feel custom. +- Often shareable; results can drive earned traffic. +- Lead-quality signal embedded in the inputs (a calculator's inputs reveal the lead's situation). + +Weaknesses. + +- Build cost is significant; a quality tool is engineering work, not just copy. +- Maintenance is ongoing as inputs and methodology evolve. +- Easy to fall into vanity-tool patterns (inputs and outputs that do not produce a meaningful result). + +Audience-fit signals. + +- Strong fit: audiences with concrete decisions or calculations the tool can address. +- Weak fit: topics that do not naturally produce a personalized output. + +Conversion-rate baseline. Wide range, 5-25 percent depending on tool quality and audience-fit. + +Production overhead. High. 40-150+ hours for a polished tool. + +Detail in `calculator-design` and `quiz-and-assessment-design`. + +--- + +## Ebooks + +Long-form treatment of a topic. + +Strengths. + +- Comprehensive coverage when comprehensiveness matters. +- Authority signal; a well-produced ebook positions the brand as a definitive source. +- Bookmarkable; readers may return over time. + +Weaknesses. + +- Easy to default to ebook for topics that would have been better as a checklist or template. +- Completion rates are honestly low; many ebooks are downloaded and never read. +- Production overhead and design overhead are high. +- The format invites kitchen-sink-resource patterns ("we have to cover everything"). + +Audience-fit signals. + +- Strong fit: audiences researching a complex decision who want depth. +- Weak fit: practitioners who want immediate-use artifacts. + +Conversion-rate baseline. 2-8 percent. Lower than other formats because the perceived time investment to read is high and many readers know they will not finish. + +Production overhead. High. 40-120 hours for a 30-50 page ebook. + +--- + +## Video series + +Sequential video content delivered behind a gate. + +Strengths. + +- Strong for topics that benefit from demonstration (UI walkthroughs, design critique, code review). +- Personality and brand presence land more directly in video than in text. +- Audiences who prefer video learning are well-served. + +Weaknesses. + +- Production overhead is high; video quality has to match the brand it represents. +- Audiences who do not consume video at the moment of magnet delivery underuse the resource. +- Updates require re-recording, which is more expensive than updating text. + +Audience-fit signals. + +- Strong fit: audiences who consume video for learning and have time to watch. +- Weak fit: practitioners who want skim-and-apply content. + +Conversion-rate baseline. 3-9 percent. + +Production overhead. Very high. 50-200+ hours for a 4-6 video series at quality. + +--- + +## Hybrid formats + +Some magnets combine formats. A template plus a worked-example video. A checklist plus a 5-day email mini-course that walks through it. + +Strengths. + +- Multiple consumption modes serve broader audience preferences. +- The hybrid often outperforms either format alone. + +Weaknesses. + +- Production overhead compounds. +- Risk of confusing the reader about what they are getting. + +When hybrids work. When the second format genuinely extends the first. A template that includes a video walkthrough adds value; a template that includes a 60-page ebook the reader did not ask for adds bloat. + +--- + +## Format-decision frame + +When choosing the format for a specific topic and audience. + +Step 1: Audience consumption mode. How does this audience consume content? Do they read long-form? Skim PDFs? Watch video? Use templates? + +Step 2: Topic shape. Does the topic naturally produce an artifact (template), a verification (checklist), inspiration (swipe), instruction (course), a calculation (tool), depth (ebook), or demonstration (video)? + +Step 3: Production capacity. What can the team sustain? A great template the team can ship beats a mediocre ebook the team is straining to finish. + +Step 4: Conversion-rate target. Templates and checklists generally convert higher; ebooks and courses convert lower. The expected conversion rate informs the topic-volume calculation. + +Step 5: Maintenance overhead. Some formats decay faster than others. Swipes go stale; templates with software-specific instructions decay; videos with UI screenshots decay. Choose formats the team can maintain. + +The right format is the one that fits the topic, the audience, the team's capacity, and the maintenance reality. There is no universal best format; there is only the format that fits the situation. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format strengths, weaknesses, audience-fit signals, conversion-rate baselines, and production overhead. The hybrid format consideration. The format-decision frame. The principle that there is no universal best format. + +## Implementation choices that stay internal + +Specific format choices for specific topics in the team's catalog. Specific production benchmarks for the team's capacity. Specific tooling for each format. The team's audit baselines for conversion rate and lead quality. These vary by team, topic, and audience. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md b/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md new file mode 100644 index 0000000..b781609 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/format-specific-quality-gates.md @@ -0,0 +1,196 @@ +# Format-specific quality gates + +Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. Each format has gates specific to that format. A great template fails different tests than a great mini-course. + +The quality gates exist because thin-bait can hide in any format. The gates make hiding harder. Apply them before launch; if the magnet fails a gate, redesign before shipping. + +--- + +## Template gates + +A template earns the email when the reader produces a usable artifact in minimal time. + +Gate 1: Time-to-usable-artifact. Can the reader produce a usable artifact in under 30 minutes? If the template requires hours of customization to be useful, the format is failing. + +Gate 2: Specificity of prompts. Are the prompts specific enough to feel custom? "Insert your unique value proposition here" is too generic. "What is the specific outcome your customer needs in the first week" is specific enough to guide the reader. + +Gate 3: Adaptability across the segment. Is the template adaptable across the segment of the audience, or rigidly bound to one situation? A template for "B2B SaaS pricing one-pager" should work across multiple B2B SaaS situations; a template that only fits one company's exact circumstances is too rigid. + +Gate 4: Worked example included. Does the template include a worked example showing what a completed version looks like? Worked examples reduce the time-to-usable-artifact and signal that the template was real-tested. + +Gate 5: Tooling honesty. If the template requires specific tools (a Notion template, a Figma file, an Airtable base), is the tool dependency honestly disclosed in the title? Surprise dependencies frustrate readers who do not have the tool. + +--- + +## Checklist gates + +A checklist earns the email when each item is actionable today. + +Gate 1: Each item actionable today. No "consult your team about X" or "decide on the strategy for Y." Each item should be something the reader can verify or complete. + +Gate 2: Workflow order. Does the checklist sequence reflect actual workflow order? An out-of-order checklist forces the reader to mentally re-sort, which costs the speed advantage the format promised. + +Gate 3: Scope discipline. Is the checklist scoped narrowly enough to feel comprehensive within scope? "Pre-launch checklist for B2B SaaS" is narrower than "Pre-launch checklist for any product" and produces a tighter, more useful resource. + +Gate 4: Item count sanity. Strong checklists are usually 12-30 items. Fewer than 8 items often signals thin-bait; more than 50 often signals that the format should have been an ebook or playbook instead. + +Gate 5: Verification cues. Does each item include enough cue for the reader to know they actually verified it? "Email sequence tested in production" is verifiable; "Email sequence reviewed" is not. + +--- + +## Swipe file gates + +A swipe file earns the email when the swipes are real, attributed, and curated. + +Gate 1: Real swipes. The swipes should be examples actually used in the wild, not invented for the magnet. Real swipes have specificity that invented ones lack. + +Gate 2: Attribution where possible. Each swipe attributed to source where the source is public. Unattributed swipes can read as theft. + +Gate 3: Currency. Are the swipes current? Swipes from 5 years ago may have specific dating cues that signal staleness. Periodic refresh is part of the swipe-file discipline. + +Gate 4: Curation visible. Is the curation visible? The reader can see why each swipe is included? A 200-swipe dump with no commentary is less useful than 30 curated swipes with notes on why each was included. + +Gate 5: Categorization. Are the swipes categorized by use case (subject lines, headlines, ad copy, design references)? A flat list of unsorted swipes is harder to extract value from than a categorized collection. + +--- + +## Mini-course gates + +A mini-course earns the email when each lesson stands on its own and the cumulative arc adds up. + +Gate 1: Each lesson standalone. A reader who only completes lesson 1 should still extract value. "You will learn the answer in lesson 4" loses readers who do not make it to lesson 4. + +Gate 2: Cumulative time honesty. Is the total time commitment honestly disclosed in the title or landing page? "5-day course" should mean 5 days of meaningful engagement, not 5 days of one paragraph emails. + +Gate 3: Production consistency. Are all lessons at consistent production quality? Courses that decay in production quality across lessons signal that the team ran out of capacity. + +Gate 4: Clear next step at end. Does the course end with a clear next step (related product, related resource, ongoing community)? "Thanks for taking the course" without a next step is a missed opportunity. + +Gate 5: Completion tracking. Does the course include progress markers ("Lesson 3 of 5") so the reader knows where they are? Lack of progress markers correlates with low completion. + +Gate 6: Each lesson's central insight. Can the team articulate the central insight of each lesson in one sentence? Lessons without a central insight are filler. + +--- + +## Free tool gates + +Free tools (calculators, quizzes, generators) earn the email when the result is meaningful. + +Gate 1: Meaningful result. The output should help the reader make a decision or understand a situation. "Your score is 73" without interpretation is meaningless. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Gate 2: Calculation transparency or methodology disclosure. Detail in `calculator-design`. + +Gate 3: Email-capture honesty. Detail in `calculator-design`. + +--- + +## Ebook gates + +An ebook earns the email when the resource produces value for readers who do not finish. + +Gate 1: Navigability. Table of contents, page numbers, summary boxes. A reader who jumps to chapter 3 should be able to extract value without reading 1 and 2. + +Gate 2: Production quality consistent with the brand. A poorly-produced ebook (typos, inconsistent formatting, low-resolution images) signals that the brand did not invest. The reader's expectation of the brand drops. + +Gate 3: Length honesty. Is the page count honestly disclosed? "30-page guide" should mean 30 pages of substance, not 30 pages including 12 of brand-positioning. + +Gate 4: Chapter summaries. Each chapter ends with a summary that lets a reader who skimmed extract the key insight. Summaries reduce the cost of skimming, which raises the value the reader gets even if they do not finish. + +Gate 5: First-chapter discipline. The first chapter should deliver value, not warm up. Author bio and brand-positioning belong in the appendix or the about-the-author note, not chapter 1. + +--- + +## Video series gates + +A video series earns the email when production quality and consumption shape match the audience. + +Gate 1: Production quality consistent. Audio clear, video stable, lighting reasonable. Production quality the brand can sustain across all videos. + +Gate 2: Runtime honesty. Total runtime disclosed honestly. "5-video series" with one video 30 seconds and another 45 minutes is dishonest. + +Gate 3: Audio-first viability. Many video viewers consume in audio-only contexts (commutes, exercise). Does the video work as audio? If the video has heavy on-screen reading required, the audio-only viewer loses the value. + +Gate 4: Transcripts available. A transcript reaches the audience that prefers reading and improves accessibility. + +Gate 5: Each video standalone. Same as the mini-course gate. A viewer who only watches video 1 should extract value. + +--- + +## Cross-format gates + +Some gates apply regardless of format. + +Gate A: The "would they pay for this" test. Detail in `references/would-they-pay-for-this-test.md`. + +Gate B: Audience-fit signal. Does the magnet attract the audience the brand serves? Detail in `references/audience-fit-qualification.md`. + +Gate C: Title-content alignment. Does the magnet deliver on the title's specific promise? Detail in `references/title-and-presentation-discipline.md`. + +Gate D: First-impression quality. Whatever the format, does the first impression (first page, first lesson, first calculator output) deliver something useful immediately? + +Gate E: Update cadence. Is the magnet updated when references go stale, screenshots change, or methodology evolves? Stale magnets degrade the brand. + +--- + +## When a magnet fails a gate + +The magnet fails a gate. Now what. + +Option 1: Fix the magnet. Add the worked example, narrow the scope, improve the production quality. Often the right answer. + +Option 2: Change the format. Sometimes the topic is wrong for the chosen format. A topic that fails ebook gates might pass checklist gates. + +Option 3: Do not ship. Some magnets should not exist. Killing the magnet at the gate stage is honest; shipping a failing magnet costs more than killing it. + +The team's response to gate failures is the discipline marker. Strong programs fix or kill at the gate; weak programs ship despite failed gates and accept the downstream cost. + +--- + +## The gate review process + +Gates are most useful when applied as a structured pre-launch review. + +The review. + +- Identify the format. +- List the gates for that format (plus the cross-format gates). +- For each gate, score pass / fail / marginal. +- Marginal gates warrant strengthening before launch. +- Failed gates require redesign before launch. + +Who reviews. + +- The magnet's author should self-review. +- A second person (outside the magnet's authoring team) should also review. Outside-in honesty catches what the authoring team rationalizes. + +Document the review. A short note on which gates passed and which were strengthened. Useful for future magnet design and team learning. + +--- + +## Common gate failures + +Templates. Generic prompts; no worked example; tool dependency hidden. + +Checklists. Items that are not actionable; out-of-workflow order; thin item count. + +Swipe files. Invented swipes; no attribution; uncategorized dump. + +Mini-courses. Lessons that depend on each other; production quality decays; no clear next step. + +Free tools. Vanity outputs without interpretation; misleading methodology; manipulative gates. + +Ebooks. Poor navigability; production quality below brand standard; length padded with brand-positioning. + +Video series. Inconsistent production; no transcripts; long runtime hidden. + +The pattern across formats: the gates surface the failures that conversion-rate metrics hide. A magnet can convert at high rates while failing the gates; the gate failures show up downstream as poor lead quality and poor sequence engagement. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format quality gates with specific tests. Cross-format gates. The gate review process. The decision tree when a magnet fails a gate. Common gate failures. + +## Implementation choices that stay internal + +Specific gate-scoring conventions for the team. Specific review processes and reviewers. Specific worked-example libraries. Specific production-quality benchmarks. Specific update-cadence calendars. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md new file mode 100644 index 0000000..e2d1f8f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md @@ -0,0 +1,197 @@ +# Lead magnet anti-patterns + +The patterns that look like lead magnets but do not behave like them. Anti-patterns are easy to ship and easy to celebrate; the cost shows up in lead quality, sequence engagement, and brand trust over time. + +--- + +## The thin-bait magnet + +The pattern. A vague-headline PDF that contains 200 words of fluff behind an email gate. + +The signal. Conversion-rate metric looks fine; unsubscribe rate after delivery is high; subsequent email open rates collapse. + +The cost. Every subscriber acquired through thin-bait costs more than they appear to. Reduced sender reputation, reduced list trust, and the brand reputation as a source of bait all compound. + +The cure. Apply the "would they pay for this" test before launch. Strengthen the resource until it would be worth paying for. If it cannot be strengthened, do not ship. + +--- + +## The kitchen-sink-resource magnet + +The pattern. An 80-page "Ultimate Guide" that covers everything anyone could want about the topic. Nothing the reader needs RIGHT NOW. + +The signal. Strong conversion rate (the title sounds comprehensive); low usage rate (the resource is too long to consume); no traceable downstream conversion. + +The cost. The magnet does not produce the moment of "I needed this and got it." The relationship never starts. Subscribers stay on the list out of inertia; future emails get ignored. + +The cure. Narrow the topic until the magnet addresses one specific problem. The 80-page guide becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## The undelivered-promise magnet + +The pattern. A title that promises a specific outcome ("the framework that doubled our conversion rate") followed by a magnet that delivers something less specific ("here is general advice on conversion rate optimization"). + +The signal. Reader downloads, opens, encounters the gap, and unsubscribes (or stays subscribed but disengages). + +The cost. The brand becomes the source of the gap. Future titles by the same brand are less trusted; conversion rates on future magnets decay. + +The cure. Either deliver on the title's promise (which often requires strengthening the magnet) or revise the title to be honest about what the magnet contains. + +--- + +## The bait-and-switch magnet + +The pattern. The magnet promises one resource and delivers another. "Free template" that turns out to be a 10-email mini-course; "calculator" that turns out to be a contact-sales form. + +The signal. Reader engagement collapses; the brand earns "deceptive" descriptors in support tickets and social mentions. + +The cost. Trust damage that extends beyond the magnet. The brand becomes harder to trust on any future offering. + +The cure. Match the title to what the magnet actually delivers. If the team wants to deliver a mini-course, title the magnet as a mini-course. If the team wants to gate a sales form, do not call it a calculator. + +--- + +## The orphan-magnet (no sequence) + +The pattern. The magnet ships; subscribers download; nothing follows. No sequence, no offer, no relationship-building. + +The signal. List grows; engagement on subsequent emails (when they happen) is low; downstream conversion to anything is near zero. + +The cost. The list is a list of cold contacts. The brand has the email but not the relationship. + +The cure. Design the sequence before shipping the magnet. The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## The misaligned-offer magnet + +The pattern. The magnet attracts one audience; the follow-up offer pitches a different one. Magnet on B2B onboarding; offer for consumer-app courses. + +The signal. Magnet conversion is fine; offer conversion is near zero; the audience signal the magnet captured was wasted. + +The cost. The team builds the magnet, runs the sequence, and gets no downstream conversion. The investment does not pay back. + +The cure. Align the offer to the audience the magnet attracts. If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## The dead-magnet portfolio + +The pattern. The team has shipped 12 magnets over 3 years. 3 still convert; 9 are dead but still on the site. Maintenance attention spreads thin; nothing is great. + +The signal. Aggregate conversion-rate metrics look fine; per-magnet metrics show 75 percent of the portfolio underperforming. + +The cost. Maintenance overhead on dead magnets; brand looks cluttered; team capacity diluted across underperformers. + +The cure. Audit the portfolio. Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## The everyone-magnet + +The pattern. A magnet titled to attract "everyone in marketing" or "any founder." Generic by design. + +The signal. Conversion rate may be high; lead quality is low; downstream engagement is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly because the audience is not aligned to any specific offer. + +The cure. Narrow the magnet's audience. Specific magnets attract specific audiences who convert well to specific offers. The everyone-magnet is the wrong tool for any specific goal. + +--- + +## The vanity-magnet + +The pattern. A magnet built because the team wanted to ship a magnet, not because the audience needed one. The topic was chosen for "we should write about this" rather than "the audience would download this." + +The signal. Low conversion rate; few signs that the audience cares about the topic; the magnet collects dust. + +The cost. Sunk effort; team morale drop; the team learns that magnets do not work (when in fact this specific magnet did not work because the topic was wrong). + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. Vanity-magnets often fail at the topic-validation step. + +--- + +## The follow-up-spam magnet + +The pattern. The magnet ships; the sequence follows; the sequence is 30 emails over 14 days, all of them sales-driven. + +The signal. Strong unsubscribe rate; high spam-complaint rate; the brand earns "spammy" descriptors. + +The cost. Sender reputation damage that affects all future emails. The brand's email program degrades. + +The cure. Redesign the sequence to add value rather than extract it. Cadence should match the audience's tolerance; content should be honest. + +--- + +## The interrogation-form magnet + +The pattern. The form before the magnet asks for 12 fields (name, company, role, company size, current tools, biggest challenge, etc.) before delivering the resource. + +The signal. Conversion rate collapses; the audience self-selects out at the form. + +The cost. The magnet's reach drops dramatically. The team gets rich data on the few who convert; the team loses the broader audience the magnet could have served. + +The cure. Ask only for what is needed (often just an email). Capture additional data later in the sequence as the relationship deepens. + +--- + +## The hidden-cost magnet + +The pattern. The magnet promises a free resource; the resource includes upselling, integrated ads, or links to paid offerings on every page. + +The signal. Reader downloads expecting a resource; experiences the upsells as bait; engagement collapses. + +The cost. The magnet is perceived as commercial-disguised-as-resource. Trust damages. + +The cure. Keep the magnet substantive. Soft offers can appear at the end or in the follow-up sequence; the body of the magnet should deliver the promised value. + +--- + +## The unfindable-asset magnet + +The pattern. The magnet is delivered as a link to a Google Drive folder, a Notion page, or some other location that the reader has to navigate to find the actual asset. The asset is buried 2-3 clicks away. + +The signal. Reader downloads the email link; cannot find the asset; abandons. + +The cost. The download metric counts but the consumption metric collapses. The reader's experience is friction. + +The cure. Deliver the asset directly (attachment or in-line link). Click count from email to asset should be 1. + +--- + +## The team-pat-on-the-back magnet + +The pattern. The magnet is content the team wanted to make (a thought-leadership piece, a brand statement, a manifesto) gated behind a form. The audience may not specifically want it. + +The signal. Conversion rate underwhelms; the team rationalizes ("brand-building is hard to measure"); the magnet does not produce relationship signal. + +The cost. The team builds the wrong thing for the audience and learns the wrong lesson. + +The cure. Design magnets for the audience's needs, not for the team's preferences. Brand-building content can exist as ungated content; gated content should be magnet-shaped. + +--- + +## How to detect anti-patterns in the portfolio + +Audit cadence. Quarterly review of every active magnet, looking specifically for these anti-patterns. + +Audit questions per magnet. + +- Is the conversion rate consistent with the audience-fit, or is it suspiciously high (suggesting thin-bait or everyone-magnet)? +- Is the lead quality consistent with the audience the magnet was designed for, or is it diluted (suggesting weak filters)? +- Does the sequence's engagement match the magnet's promise, or is there a drop (suggesting an undelivered-promise or misaligned-offer)? +- Is the asset usable in the form delivered, or is it hard to find (suggesting unfindable-asset)? +- Does the magnet have a sequence at all, or is it orphaned? + +The retire decision. Anti-pattern magnets often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-magnet plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md new file mode 100644 index 0000000..9fd5b1f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md @@ -0,0 +1,137 @@ +# Lead magnet decision criteria + +When a lead magnet is the right investment for the funnel and when it is not. The conditions that make magnets worth the build, and the funnels where the magnet is friction the audience does not need. + +A lead magnet is a long-lived asset. The build cost is upfront; the conversion lift compounds across visitors. But the long-lived asset only compounds if the audience and the goal warrant it. Magnets built without the conditions in place become dead PDFs in CMS folders. + +--- + +## When a magnet earns the build + +Five conditions that, when present, make a magnet a strong investment. + +Traffic exists but conversion is missing. The audience reaches the site (organic, paid, referral, social) but does not convert to the primary action (signup, purchase, demo). The magnet fills the gap between "interested enough to land" and "ready to commit." Without traffic, the magnet has no audience; without a conversion gap, the magnet adds friction. + +The consideration cycle is long. B2B SaaS, high-ticket services, and considered consumer purchases share the trait that buyers research over weeks or months before committing. The list-building motion lets the brand stay present across the consideration window. Short-cycle purchases (impulse ecommerce, low-stakes signups) often do not need a magnet between visitor and conversion. + +The audience has a specific, immediate problem the magnet can address. Generic problems do not focus a magnet. "Improve my marketing" is too broad; "the email sequence I send to trial signups who go cold" is specific enough to focus a checklist or template. The magnet lives or dies on specificity. + +The team can commit to the follow-up sequence. A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams without sequence-building capacity should fix that before building the magnet. + +The success metric is defined. What does "the magnet works" look like? List growth at quality, lead-quality signal, conversion to the next step, downstream revenue attribution. Without a defined success metric, the magnet's results cannot be evaluated, and underperformers do not get retired. + +When all five are present, the magnet is a strong investment. When two or fewer are present, the magnet is probably the wrong tool. + +--- + +## When a magnet does NOT earn the build + +Funnels where the magnet adds friction the audience does not need. + +Frictionless conversion already exists. A SaaS with a 14-day free trial, no credit card required, may not need a magnet between the visitor and the trial. The magnet adds a step where the trial alone would convert. + +The next step is a sales call or demo. When the goal is a booked call, design the call-booking flow rather than a magnet that delays the call. The magnet might still serve a separate audience (top-of-funnel readers not ready for a call), but the primary funnel is the call. + +The audience is too small for list-building economics. Building, hosting, and maintaining a magnet (plus the sequence) costs ongoing time. For very small target audiences, direct outreach or a simpler conversion path may be more efficient. + +The team has no sequence capacity. If the team cannot design and maintain the post-download sequence, the magnet captures emails that decay into unsubscribes. The list grows on paper and shrinks in trust. + +No specific topic that focuses a magnet. When the topic is "we do everything," no single magnet focuses. The honest move is to narrow the audience first (which produces the topic that focuses) rather than build a generic magnet. + +The current funnel is already converting at a rate the magnet would not improve. If the visitor-to-customer rate is already strong, the magnet adds steps without lifting the outcome. + +The honest assessment matters more than the default. "Should we have a lead magnet" is not the question. "Is the magnet the right investment for this audience and goal" is. + +--- + +## The opportunity-cost frame + +A magnet's cost is not just the build. It is the build plus the maintenance plus the sequence plus the team attention diverted from other work. + +The build cost. Format selection, copy, design, asset production, landing page, form integration, delivery automation. A meaningful magnet often takes 20-80 hours from scoping to launch. + +The maintenance cost. Magnets decay. References go stale, screenshots get outdated, the topic moves on. Maintenance often runs 2-4 hours per quarter per active magnet. + +The sequence cost. The post-download sequence is itself a build. 5-12 emails, copy and integration. 10-30 hours upfront. + +The opportunity cost. What else could the team have built with that time? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The magnet's success has to clear the bar of those alternatives. + +The decision frame. The magnet earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The audience precondition + +Without an audience, the magnet has no one to convert. + +The chicken-and-egg pattern. Teams sometimes build magnets to "drive traffic." That works only if the magnet itself is shareable enough to attract traffic (rare) or if the team has a separate plan to drive traffic to the magnet's landing page. + +The realistic frame. The magnet converts traffic that already exists. Driving traffic is a separate problem (covered by `content-distribution`, paid media, SEO, and partnerships). Build the magnet for the traffic that already lands; do not expect the magnet to do the traffic-driving work. + +The exception. Genuinely shareable magnets (free tools, viral calculators, definitive industry reports) can drive their own traffic. But these are the minority of magnets, and the design effort to reach shareability is significant. + +--- + +## The portfolio frame + +A team often has multiple magnets, not one. The portfolio earns more thought than any individual magnet. + +The audience-segmentation frame. Different magnets for different audience segments. The B2B SaaS founder magnet does not need to also serve the consumer marketer; segment-specific magnets often outperform generic ones. + +The funnel-stage frame. Magnets for top-of-funnel readers, magnets for middle-of-funnel evaluators, magnets for bottom-of-funnel near-buyers. Each stage has different value to deliver and different next-step offers. + +The maintenance frame. A portfolio of 4-6 active magnets is often more sustainable than 12 mediocre ones. Periodic audit retires the underperformers and frees capacity for the strong magnets. + +The cross-magnet promotion frame. The follow-up sequence from one magnet can promote another. Subscribers who downloaded the templates checklist may also want the pricing one-pager. + +The portfolio approach amplifies the value of each strong magnet and makes maintenance manageable. + +--- + +## The decision worked example + +A B2B SaaS targeting product managers at mid-market companies. + +Conditions check. + +- Traffic: 8000 monthly organic visitors, 1200 paid visitors. Yes. +- Consideration cycle: typical PM tool evaluation takes 6-12 weeks. Yes. +- Specific problem: PMs at mid-market companies struggle to define product metrics that the engineering team can instrument quickly. Yes. +- Sequence capacity: marketing team has built two prior sequences; capacity exists. Yes. +- Success metric: list growth at audience-fit (PMs at 50-500 person companies), conversion to product trial within 60 days. Yes. + +Decision. Build the magnet. The conditions warrant it. + +Format selection. Template plus worked example. The PM produces a usable artifact (the metric definition spec) inside 30 minutes. + +Sequence. 7-email arc over 21 days. Email 1 delivers the asset. Emails 2-4 deepen the value with related artifacts. Email 5 introduces the product as the next step. Emails 6-7 case study and offer. + +Audit cadence. Quarterly review of conversion rate, lead quality, sequence open and click rates, downstream trial conversion. + +The decision was not "should we have a magnet" but "given these conditions, this is the magnet to build." + +--- + +## When to retire a magnet + +Magnets decay. Retiring them is part of the discipline. + +Retire when: + +- Conversion rate has dropped below baseline for two consecutive quarters. +- The topic has shifted (the audience no longer cares about the problem the magnet solves). +- A newer magnet on the same topic is outperforming and the older one is cannibalizing. +- The follow-up sequence is no longer maintained and the leads go cold. +- The references and screenshots are stale and updating them costs more than retiring. + +The retiring discipline frees capacity. A portfolio of dead magnets costs maintenance attention without producing results. Honest retirement is part of the program. + +--- + +## Methodology-level choices that stay in the public skill + +The decision conditions for whether to build a magnet. The opportunity-cost frame. The audience precondition. The portfolio frame. The retirement discipline. The decision worked example. The honest "no" cases where a magnet adds friction. + +## Implementation choices that stay internal + +Specific magnet topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence work. Specific tooling for landing pages, forms, delivery, and sequence. Specific success-metric definitions and baselines. The team's portfolio composition and audit calendar. These vary by team and audience. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md b/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md new file mode 100644 index 0000000..f3b990f --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/title-and-presentation-discipline.md @@ -0,0 +1,190 @@ +# Title and presentation discipline + +Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. + +The magnet's title is the conversion lever and the qualification filter at the same time. Beyond the title, the cover, the landing-page preview, and the first page each carry signal about whether the resource will deliver. Get any of these wrong and the rest of the magnet's design effort is wasted. + +--- + +## Title patterns that work + +Specific, honest, signals what is inside. + +Specific outcome plus specific audience. "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." + +What works: the specific outcome (3x'd, 14-day activation), the specific audience (SaaS founders), the specific deliverable (email sequence). The reader knows exactly what they get and can predict whether it applies. + +Specific deliverable plus specific situation. "The pricing one-pager for SaaS founders raising a seed round." + +What works: the artifact (pricing one-pager), the situation (raising a seed round). Niche by design; the audience that converts is exactly the audience the brand wants to engage. + +Specific framework plus specific problem. "The 4-question framework for deciding whether to fire a customer." + +What works: the framework's structure (4 questions), the specific decision (fire a customer). Promises a tool, not a treatise. + +Specific count plus specific value. "23 onboarding emails, with the open and click rate for each." + +What works: the count (signals scope), the value-add (real metrics, not just templates). The reader knows the resource includes evidence. + +Specific transformation. "The audit that took our trial-to-paid rate from 8 percent to 14 percent." + +What works: the before-state (8 percent), the after-state (14 percent), the mechanism (the audit). The reader can imagine running their own version. + +--- + +## Title patterns to avoid + +Vague, overpromising, or generic. These titles correlate with thin-bait and kitchen-sink-resource patterns. + +"Ultimate Guide to X." Vague. Promises completeness; underdelivers reliably. The "Ultimate" qualifier signals that the team did not narrow the topic. + +"The Complete X Playbook." Same failure mode. Promises volume; suggests the resource is big and unfocused. + +"Free X Resource." Generic. Tells the reader nothing about what makes this resource the one to download. The "free" framing implies the resource has to apologize for asking for the email. + +"10 Tips for Better X." Listicle framing signals thin content. "10 tips" is rarely a useful resource; "the 1 specific change that doubled our X" is. + +"X 101" or "Beginner's Guide to X." Targets a low-investment audience. The list that grows from these titles tends to convert poorly to anything beyond the magnet. + +"The Definitive X Resource." Self-aggrandizing. Definitive is the reader's judgment, not the marketer's claim. + +Vague verbs. "Master," "Unlock," "Transform." Without specificity about what or how, these are filler. + +--- + +## The honesty discipline in titles + +The title should not promise more than the magnet delivers. + +The check. Read the title. Then open the magnet. Does the magnet deliver on the title's specific promise? If yes, the title is honest. If the title overpromises, redesign the title (or strengthen the magnet) before launching. + +The consequence of dishonesty. Readers download, find the gap between title and content, and unsubscribe. Worse, they remember the brand as the source of the gap. The conversion-rate metric looks fine; the brand reputation degrades. + +The conservative title. A title that slightly under-promises and then delivers more is better than a title that overpromises and disappoints. + +--- + +## Cover and visual presentation + +The cover is the second visual the reader processes (after the landing page hero). It should reinforce the title's specificity. + +Strong cover patterns. + +- Type-driven covers. The title in clean, large type. Color-blocked. Reads at thumbnail size. +- Single-image covers. A specific image (a screenshot, a diagram, a person) that signals what the magnet contains. +- Brand-consistent covers. Visual style matches the brand the magnet represents. + +Weak cover patterns. + +- Stock-image covers. Generic stock photos signal generic content. +- Cluttered covers. Too many visual elements; the title gets lost. +- Off-brand covers. Cover that does not match the brand the reader saw on the landing page; signals inconsistency. + +The cover-as-thumbnail test. The cover will be displayed at thumbnail size in social shares, in landing-page previews, and in delivery emails. Does it read at thumbnail size? If not, redesign. + +--- + +## Landing-page preview + +The landing page (which is the `landing-page-copy` skill's domain) should preview the magnet, not just describe it. + +Strong preview patterns. + +- Show pages from inside. Screenshots of actual pages from the magnet. The reader sees the resource before they download. +- Show worked examples. A specific page from the template, the checklist, or the swipe file. Concreteness lifts conversion. +- Show the table of contents. For longer magnets, show what is inside. The reader can predict whether the resource will help. + +Weak preview patterns. + +- Stock-image hero only. The landing page shows nothing of the actual magnet. The reader has to trust the marketing without evidence. +- Generic descriptions. "Learn the framework that..." without showing the framework. +- Hidden contents. "You will learn..." without showing what learning looks like in the resource. + +The preview is the second-best evidence that the magnet delivers (the best evidence is post-download, but the preview is the pre-download proxy). Strong previews lift conversion and reduce post-download disappointment. + +--- + +## First-page discipline + +The first page of the magnet is what the reader sees on opening. It sets the expectation for the rest. + +The first page should deliver value within the first read. The reader has just downloaded; they are most engaged in the first 30 seconds. Use the first page to deliver the headline insight, the first checklist item, the template's first prompt, the calculator's first input. + +The first page should NOT. + +- Warm up with author bio. The reader did not download the magnet to read about the author. +- Spend space on brand-positioning. The reader knows whose brand they downloaded from; they want the value. +- Recap the marketing. The landing page already sold the magnet; the first page should deliver, not re-sell. +- Defer the value. "In Chapter 3, you will learn..." loses the reader who wanted the value now. + +The first-page test. Open the magnet. Does the first page deliver something useful? If yes, the first-page discipline holds. If no, redesign the first page to deliver value upfront. + +--- + +## Title-magnet alignment audit + +Periodically audit titles against the magnets they represent. Drift accumulates: titles get polished while magnets remain unchanged, and the gap between promise and delivery widens. + +The audit. + +- For each active magnet, read the title and open the magnet. +- Does the magnet deliver on the title's specific promise? +- If not, the gap is either a title that overpromises (fix the title) or a magnet that underdelivers (strengthen the magnet). + +The audit cadence. Quarterly is reasonable for active magnets. Drift detection is part of magnet portfolio maintenance. + +--- + +## Worked title revisions + +Original title: "Marketing Automation Guide." + +Failure: vague, generic, overpromises (which guide?). + +Revised title: "The 7-email re-engagement sequence we send to trial signups who go cold (with open and click rates)." + +What changed: specific deliverable (7-email sequence), specific situation (trial signups who go cold), specific evidence (open and click rates). + +Original title: "B2B Lead Generation Playbook." + +Failure: "Playbook" suggests volume without focus. "B2B Lead Generation" is too broad to focus a single resource. + +Revised title: "The cold-email template for B2B SaaS founders selling into mid-market product teams." + +What changed: specific format (template), specific audience (B2B SaaS founders), specific buyer (mid-market product teams). Niche by design. + +Original title: "The Complete Pricing Guide." + +Failure: "Complete" overpromises; "Pricing Guide" suggests volume; the guide will likely be a kitchen-sink-resource. + +Revised title: "The pricing one-pager template for SaaS founders raising a seed round." + +What changed: specific deliverable (one-pager template), specific situation (raising a seed round). Tight scope; usable immediately. + +The pattern: replace vague nouns and adjectives with specific deliverables, audiences, and situations. The revision often shrinks the addressable audience and improves the qualified-lead rate. + +--- + +## Common title and presentation failures + +Title overpromises. The reader downloads, opens, finds less than expected, and unsubscribes. + +Title is generic. Anyone could want this; no one specifically wants it. + +Cover signals stock content. Generic visual; reader's expectation drops before opening. + +Landing page hides the magnet. The reader has no evidence the resource will deliver; conversion suffers. + +First page warms up instead of delivering. Author bio, brand statement, table of contents. The reader's engagement drops. + +Drift between title and content. The title was strong at launch; the magnet has not been updated; the gap has widened over time. + +--- + +## Methodology-level choices that stay in the public skill + +Title patterns that work and fail. The honesty discipline. Cover and visual presentation patterns. Landing-page preview discipline. First-page discipline. The title-magnet alignment audit. Worked title revisions. Common failures. + +## Implementation choices that stay internal + +Specific titles for the team's magnets. Specific cover-design conventions and brand application. Specific landing-page templates and layout choices. Specific first-page templates and brand voice. The team's audit calendar and revision processes. These vary by team. diff --git a/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md b/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md new file mode 100644 index 0000000..3b1db15 --- /dev/null +++ b/dist/pi/.agents/skills/lead-magnet-design/references/would-they-pay-for-this-test.md @@ -0,0 +1,158 @@ +# The "would they pay for this" test + +The pricing thought experiment that distinguishes earned-value from thin-bait. A single test the magnet either passes or fails before launch. + +The question is simple. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails the test is signaling that the value is below "I would pay for this," which means the reader's time investment to download and consume is at the edge of "worth it." The unsubscribe rate, the reduced trust, and the wasted email gate all follow from a failed test. + +--- + +## How to apply the test + +The test is a thought experiment, not a market study. Run it before the magnet ships. + +Step 1: Imagine a stranger in the target audience. Not the team's existing customer; not someone already on the list. A stranger who has not yet committed to the brand. + +Step 2: Imagine showing them the magnet (the actual content, not the marketing). Not the landing page; not the headline; the resource itself in the form they would receive it. + +Step 3: Ask: would this person, having seen this resource, pay something for it? A small amount, an honest amount. + +Step 4: Be specific about the price. Would they pay 5 dollars? 25 dollars? 100 dollars? The specific number forces an honest answer. + +The test fails when the honest answer is "no, they would not pay for this; they would expect it to be free or to come bundled with something else." The test passes when the honest answer is "yes, this is worth paying for, even at a small price, because the value is concrete." + +--- + +## What the test catches + +Three failure modes the test catches reliably. + +The 5-page PDF that summarizes blog content. Free elsewhere, available without a gate, worth 0 dollars in a paid context. Fails. + +The "Ultimate Guide" that nobody finishes. Pay-worthy in theory (comprehensive coverage), not delivered in usable form. The reader pays for the resource and never extracts the value because the resource is too long to consume. The test surfaces this when the team imagines whether the reader would actually use what they paid for. + +The template that is so generic it adds no value over starting from scratch. Pay-worthy framing (templates feel valuable), thin in execution (the template's content is "Insert your value here" 30 times). The test catches this when the team imagines the reader's reaction on opening the template. + +The test catches these failures because the question forces honesty about the resource's actual value rather than the resource's marketing claim. + +--- + +## What the test the magnet should pass looks like + +A magnet that passes is one where: + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +The first criterion is about value. The second is about usability. The third is about uniqueness or curation. A magnet that hits all three earns the email reliably. + +Worked example: A passing magnet. + +The B2B SaaS founder magnet "the welcome-email template that 4x'd our trial-to-paid rate." + +- Pay-worthy: a SaaS founder would pay 25-50 dollars for a template that demonstrably 4x'd a real trial-to-paid rate. The specificity (4x, real metric, real source) makes the payment plausible. +- Usable: 7 emails, copy-paste ready, with sender-side context for each. A founder can implement in 60 minutes. +- Unique: the specific template plus the specific result is not freely available elsewhere. + +The magnet passes. It is worth the email. + +Worked example: A failing magnet. + +The "Marketing Trends 2026" PDF. + +- Pay-worthy: a generic trends roundup is not worth paying for. Freely available analyses cover the same ground. The specificity is missing. +- Usable: a 30-page PDF of trend descriptions does not produce a result; it produces awareness, which the reader could have gotten elsewhere. +- Unique: marketing trend roundups are commoditized; this one is not differentiated. + +The magnet fails. It captures emails that decay because the resource did not earn the relationship. + +--- + +## When the test surfaces "almost passes" + +Sometimes the answer is "they might pay 5 dollars but not 25 dollars." This is signal, not failure. + +The action. Strengthen the resource until the answer becomes "yes, they would pay 25 dollars." This often means adding the specific worked example, the specific case study, or the specific tooling that makes the resource concretely useful. + +The risk of skipping. Shipping the "5 dollar" version saves time but produces conversion-rate metrics that look fine and lead-quality metrics that disappoint. The strengthened version costs more upfront and pays back in lead quality and downstream conversion. + +The test surfaces the gap between the magnet as built and the magnet at value-strong. The work to close the gap is often the difference between thin-bait and earned-value-magnet. + +--- + +## When the test surfaces "this should not be a magnet" + +Sometimes the honest answer is that the resource would not be paid for at any price. + +The action. Do not ship the magnet. Either redesign the resource until it would be paid for, or accept that the resource is content (not a magnet) and publish it ungated. + +The release valve. Not every piece of content has to be gated. Free, ungated content has its own value (SEO, distribution, brand). Forcing a gate onto thin content costs more than it adds. + +The test sometimes leads to "this should not be a magnet at all." That outcome is fine; it prevents shipping a thin-bait magnet that costs list trust. + +--- + +## When the test surfaces "this is so valuable we should sell it" + +Occasionally the honest answer is that the resource would be paid for at a meaningful price (200 dollars, 500 dollars). + +The decision. The team has a choice. Sell the resource (and use a different, more right-sized magnet for list-building) or use the high-value resource as the magnet (which signals exceptional generosity and often produces strong conversion at high lead quality). + +The high-value-as-magnet pattern. Some brands give away exceptionally valuable resources as magnets specifically to signal expertise and generosity. The conversion to paid offerings often increases because the magnet establishes credibility. + +The test surfaces this opportunity. The team's decision depends on the broader strategy. + +--- + +## The team-honesty discipline + +The test only works if the team answers honestly. Pressure to ship, sunk cost in production, attachment to the magnet's framing all bias the answer toward "yes." + +The discipline. + +- Have someone outside the magnet's authoring team apply the test. Outside-in honesty often catches what the authoring team rationalizes. +- Show the actual resource, not the marketing. The pretty landing page is not the test; the PDF or the template is. +- Be specific about the price. "Would they pay something" is too vague; "would they pay 25 dollars" forces specificity. +- Take the answer seriously. If the team applies the test and answers no, do not ship the magnet without redesign. + +The test's value is in the honesty it surfaces. A team that applies it and ignores the answer is worse off than a team that does not apply it at all. + +--- + +## What to do when the test fails + +The magnet fails the test. Now what. + +Option 1: Strengthen the magnet. Add the specific worked example, case study, tooling, or framework that brings the value to pay-worthy. This is often the right answer. + +Option 2: Redesign as a different format. The topic might not be magnet-shaped in the current format. A 30-page ebook on a topic might fail; a 2-page checklist on the same topic might pass. + +Option 3: Reframe the audience. The magnet's value depends on the audience. A magnet that fails for the broad audience might pass for a narrower segment that genuinely needs the resource. + +Option 4: Do not ship. Some magnets should not exist. Killing the magnet is honest; shipping a thin one costs more in list trust than killing it costs in sunk effort. + +The team's response to a failed test is the discipline marker. Strong programs redesign or kill; weak programs ship anyway. + +--- + +## Common test failure modes + +The team rationalizes the failure. "It is good enough; readers will appreciate it being free." This is the path to thin-bait. + +The team applies the test to the wrong audience. "Would a generalist marketer pay for this" when the magnet is for SaaS founders. The test must use the actual target audience. + +The team applies the test to the marketing, not the resource. The landing page sounds great; the resource is thin. The test surfaces this when applied to the actual content. + +The team skips the test under deadline pressure. The magnet ships, the metrics look fine, the unsubscribe rate quietly climbs. The test was the protection against this; skipping it costs trust. + +--- + +## Methodology-level choices that stay in the public skill + +The test as a thought experiment with specific steps. The failure modes the test catches. The criteria a passing magnet meets. The team-honesty discipline. The decision tree when the test fails. The test failure modes. + +## Implementation choices that stay internal + +Specific magnets the team has tested and the outcomes. Specific price-point conventions for the team's audience. The team's outside-team review process. Specific redesign patterns the team uses for failing magnets. These vary by team and audience. diff --git a/dist/pi/.agents/skills/logo-design/SKILL.md b/dist/pi/.agents/skills/logo-design/SKILL.md new file mode 100644 index 0000000..75d1e26 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/SKILL.md @@ -0,0 +1,206 @@ +--- +name: logo-design +description: "Generate logo variants for a brand, producing multiple production-grade marks across different architectures (wordmark, lockup, symbol-only, letterform-as-symbol, monogram) with rationale, application specs, and decision-ready presentation. Distinct from `brand-identity`, which produces the complete system (logo plus color, type, voice, applications). Goes deep on the logo specifically: typographic register, symbol approach, application-context discipline (16px favicon, embroidery, signage, motion), and production specs (SVG-ready, single-color, reverse). Triggers on logo design, design a logo, wordmark, monogram, lockup, mark variants, logo iterations, redesign or refine the logo, logo refresh, letterform-as-symbol, and exploring mark variants for an established brand. Does NOT fire for full brand identity (use `brand-identity`), positioning or strategy (use `brand-discovery`), project-wide creative direction (use `creative-direction`), or one-off illustration." +category: brand +catalog_summary: "Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol), with rationale and application specs" +display_order: 5 +--- + +# Logo Design + +A logo is a system of marks, not a single drawing. This skill produces multiple production-grade variants exploring different architectural approaches, each with rationale, application specs, and a clear position on what it signals and rejects. + +The output is decision material, not a finished logo. The brand owner selects from the variants and the skill produces production refinement on the chosen direction. + +--- + +## When to use + +- The brand has a name and tonal direction; the deliverable is logo work specifically +- Generating 6 to 12 variants for client review and selection +- Refining a wordmark to production: kerning, optical adjustments, weight selection +- Exploring symbol options to pair with an existing wordmark +- Designing a monogram from a longer name for use in constrained contexts +- Adapting an existing logo across application contexts (small-size, signage, motion, embroidery) +- The brand owner has reviewed a first round and wants iteration on a specific direction + +## When NOT to use + +- Use `brand-identity` instead when the deliverable is the complete identity system (logo plus color plus type plus voice plus applications). This skill is the logo-specific layer; brand-identity is the system layer. +- Use `brand-discovery` for brand positioning, audience, and voice work. A logo without strategy is a drawing. +- Use `creative-direction` for project-wide aesthetic direction. Creative direction calibrates many decisions; logo design produces specific marks. +- One-off illustration, icon, or pictogram work +- Designing brand patterns, textures, or supporting graphics +- Pure typographic exploration unrelated to a brand name + +--- + +## Required inputs + +- Brand name. Exact spelling. Capitalization and punctuation preferences if any. Whether the name has a category descriptor that travels with it (e.g., "Atlas Coffee" vs just "Atlas"). +- Industry or category. Legal firm, consumer goods, B2B SaaS, hospitality, etc. Category implies defaults that can be honored or broken. +- Audience. Who sees the logo, where, in what state of mind. The audience-side perception drives selection more than the founder-side aesthetic. +- Tonal direction. Where on the formal-to-casual axis. Where on the restrained-to-expressive axis. Where on the heritage-to-modern axis. +- Application contexts. Common set: web header, mobile app icon (28px), favicon (16 to 32px), business card, letterhead, email signature, social profile picture, signage (large format), embroidery patch (1.5 inch), single-color print, video motion lockup, merch (apparel, hats, totes). +- Reference logos liked, with a sentence each on what specifically resonates. The reference clarifies which architecture and register fit better than abstract description does. +- Reference logos disliked, with a sentence on what to avoid. Negative space sharpens positive selection. +- Hard constraints. Must include element X. Must avoid color Y due to industry conventions. Must reproduce in single color. Must work as a 16px favicon. Must survive embroidery. +- Optional: existing brand assets if the project is a refresh, not greenfield. Existing wordmark if the work is symbol-only. Existing color palette if it must remain locked. + +--- + +## The framework: 5 considerations for logo design + +A logo decision sits at the intersection of five considerations. Each one filters subsequent choices. + +### 1. Mark architecture + +What IS the logo, structurally? + +Architectures: + +- Wordmark only. The logo is the brand name set in a chosen typeface, possibly with custom letterforms. Stripe, Google, Pinterest. The discipline is letter-by-letter, with kerning, optical adjustments, sometimes a single distinguishing custom character. Strongest when the name is distinctive enough to own as type. +- Lockup (wordmark plus symbol). Standard architecture for most brands. The wordmark and symbol are positioned in a fixed relationship. Slack, Airbnb, Asana. Variants: symbol left of wordmark, symbol above wordmark, symbol right (rare). Each lockup may also have a stacked alternate for square contexts. +- Symbol only. The mark is a single symbol with no wordmark. Apple, Twitter, Target. Earned over decades through brand recognition. New brands rarely succeed with symbol-only as the primary mark, though most mature brands eventually develop a symbol-only fallback. +- Letterform-as-symbol. A single letter from the name (often the first) becomes the symbol. Beats by Dre's "b", McDonald's "M", Underscore's "_". Cleanest path to symbol when the wordmark is too long for a tight lockup or when the name has a letter that lends itself to visual play. +- Monogram. Multiple letters combined as a symbol. CN (Chanel), GG (Gucci), HBO, MN (a hypothetical Morgan Northrop monogram for an institutional financial firm). Common in legal, financial, hospitality, and heritage brands. Can read as initials or as ligature. + +How to choose: What does the brand need to do at small sizes? At 16px, most lockups fail. A favicon-grade mark needs either a strong symbol component or a letterform-as-symbol fallback. Lockups also need stacked alternates for square contexts (social profile pictures, app icons). A pure wordmark works only if the brand has another mark that can stand in at small sizes, often a letterform-as-symbol or monogram. + +A common production setup is: primary lockup for most contexts, monogram for square contexts, letterform-as-symbol for favicon and embroidery. All three derive from the same wordmark and share visual DNA. + +### 2. Typographic register + +If wordmark or lockup, what typographic family carries the type? + +Registers: + +- Geometric sans. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde. Built from circles and verticals. Reads modern, considered, often optimistic. Risks reading cold or generic-tech-startup if not warmed up by color, custom letterform, or context. +- Humanist sans. Gill Sans, Optima, Frutiger, Source Sans, Inter at higher optical sizes. Has serif-like calligraphic gestures without serifs. Reads professional but warm. Excellent neutral choice when the category demands restraint with personality. +- Neo-grotesque sans. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America. The modern professional default. Reads competent and contemporary. Risks reading generic if not paired with strong color or symbol. +- Transitional serif. Source Serif, Charter, Lyon, IBM Plex Serif. Modern serifs with high contrast and readability. Reads editorial, considered, intellectual. Good for legal, publishing, financial, editorial brands. +- Old-style serif. Garamond, Caslon, Sabon, Adobe Garamond. Classical serifs with low contrast and warm shapes. Reads heritage, traditional, institutional. Common in academic, legal, financial, and heritage brands. +- Slab serif. Sentinel, Adelle, Roboto Slab, Tisa. Heavy structural serifs. Reads strong, declarative, sometimes journalistic. Common in editorial and publishing. +- Display custom. A custom-drawn or heavily-modified typeface. Reads distinctive but expensive in time. Justified when the brand needs a wordmark no one else has and the budget supports drawing one. + +How to choose: What does the brand reject? Most categories have a default register. Legal firms default to old-style or transitional serif. Tech startups default to geometric or neo-grotesque sans. Choosing within the category default reads as competence; choosing outside reads as positioning. A boutique legal firm in geometric sans signals "modern, accessible". A SaaS startup in old-style serif signals "we take ourselves seriously". + +### 3. Symbol approach + +If the architecture includes a symbol (lockup, symbol-only, letterform-as-symbol), what KIND of symbol? + +Approaches: + +- Literal. The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. Fast recognition, low ambiguity. Risks reading as cliche if the depiction is generic. Saved by distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. +- Abstract gesture. The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity". Slower recognition, higher distinctiveness. Risks reading as arbitrary if the gesture is too abstract. Saved by clear formal logic and consistent visual vocabulary. +- Geometric reduction. The symbol is a formal abstraction with no specific referent. A hexagon, a triangle, a stack of horizontal lines, a circle bisected by a vertical. Reads modern and confident. Risks reading as identical to many other geometric-reduction marks. Saved by specific proportions, considered execution, and pairing with a distinctive wordmark. +- Letterform-derived. The symbol is built from the name's letterforms. The "M" of McDonald's, the "b" of Beats, a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. Strong wordmark-symbol coherence. Risks reading as wordmark-only if the letterform isn't emphasized enough. Saved by exaggerated character: the letter must read as both the letter AND the visual metaphor. +- Monogram. Multiple initials combined. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). Common in legal, financial, hospitality. Risks reading as old-fashioned if the type treatment is too conservative. Saved by modern execution within traditional architecture. + +How to choose: What does the brand name already do? Descriptive names (Atlas, Forge, Pulse, Anchor) invite literal symbols and letterform-as-symbol approaches. Abstract names (Stripe, Anthropic, Linear) demand abstract or geometric-reduction symbols. Heritage names (a founder's surname, a place name) often use monograms. The wrong approach disconnects symbol from name. + +### 4. Application context discipline + +A logo is not a single drawing. It must work in every context the brand touches. + +Contexts and their constraints: + +- 16px favicon. The most aggressive small-size test. Lockups usually fail here; the symbol or letterform-as-symbol carries. Plan a fallback mark for this context from the start. +- 28px app icon. Slightly more headroom than favicon. Still demands strong silhouette. Often uses the symbol or monogram, not the lockup. +- 1.5 inch embroidery patch. Limits color count (often 4 to 6 max), demands clean shapes without fine detail. Eliminates gradient and photographic elements. Tests the mark's reproducibility in a tactile medium. +- Single-color reproduction. Etching, foil stamp, single-color print, fax. All gradient and color-dependent decisions must collapse cleanly to one color. Test by converting the design to pure black on white. +- Reverse (light on dark). Many marks fail when reversed. Test on the brand's expected dark backgrounds early. Gradient marks particularly struggle here. +- Large-format signage. Requires sharp vector with no rasterization. Tests construction grid quality. Tests whether thin strokes survive scaling. +- Motion lockup. Tests whether the logo has natural entry and exit animation. Wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts. +- Social profile picture (square). Lockups need a stacked alternate or monogram fallback. Symbol-only works natively. +- Apparel embroidery (thread on fabric). Tighter constraints than patch embroidery. Fine letterforms and detail die here. The mark needs a chunky-friendly variant. +- Foil stamp on paper or leather. Single-color, no gradients, requires substantial line weight to survive the impression. + +The discipline: Every variant must pass the application-context test before it's a contender. Generate each variant, then mentally test each context. If a variant fails three or more contexts, it's not a primary mark; it might still serve as a secondary or display lockup but it isn't carrying the brand. Build a fallback hierarchy: primary lockup, secondary monogram, favicon-grade letterform-as-symbol. + +### 5. Restraint discipline + +Most logo failure happens through over-design. The discipline is subtractive. + +Tests: + +- Silhouette test. Squint at the logo. If you cannot identify it from silhouette alone (with type stripped), the silhouette is too generic. Apple, Nike, Twitter pass. Most generic SaaS marks fail. +- Distinctiveness test. Search Google Images for "[your category] logo". If your candidate looks identical to three or more existing logos, it's not distinctive enough. Especially watch out for geometric-reduction marks that have already been done a thousand times. +- Sketchability test. A 7-year-old draws the logo from memory after 30 seconds of looking. If they can't, it's too detailed to live in cultural memory. +- Single-color test. Strip all color. Does it still read? If no, color is doing too much work. +- Reproducibility test. Print at 1 inch on a black-and-white printer. Is it still recognizable? If no, the mark won't survive embroidery, foil stamps, or low-resolution applications. +- The two-second test. Show the logo to someone unfamiliar with the brand for two seconds. Ask what they remember. The features they recall are the ones doing real work; the rest is noise. + +The discipline doesn't reject all detail. It rejects detail that doesn't earn its place. Every visual element should pass the question "does this read at the smallest application size?". + +--- + +## Workflow + +1. Gather inputs. Required inputs above. If the user has reference logos, walk through what specifically resonates in each. The references calibrate which architecture and register actually fit. + +2. Establish primary architecture. Wordmark-only? Lockup? Letterform-as-symbol? Monogram? This is the foundational decision; everything else flows from it. For most new brands with a distinctive descriptive name, the right architecture is lockup with literal or letterform-derived symbol, plus a monogram fallback for square contexts. + +3. Generate typographic explorations. Produce 3 to 4 wordmark-only variants exploring different typographic registers. Each variant should be a complete, kerned, optically-adjusted wordmark. These serve as both standalone candidates and as the foundation for subsequent symbol pairing. + +4. Generate symbol explorations (if architecture includes a symbol). For each typographic exploration, generate 1 to 2 symbol pairings using different symbol approaches (literal, abstract gesture, letterform-derived, monogram). The symbol must visually agree with the wordmark's type weight, optical density, and tonal register. A heavy slab wordmark needs a chunky symbol; a hairline geometric wordmark needs a thin symbol. + +5. Test each variant against application contexts. For each candidate, walk through 16px favicon, 1.5 inch embroidery, single-color reproduction, square stacked alternate. Eliminate variants that fail more than two contexts. Document which contexts each variant excels in versus needs a fallback for. + +6. Pick top candidates for client review. Typically 6 to 12 final variants. Each variant must be visually distinct from the others. Variants that are too similar dilute the review and frustrate the client (they cannot tell why they should pick one over the other). + +7. Document each variant. Per-variant: descriptive name (e.g., "01, Light geometric wordmark, Avenir Next"), architecture, typography, symbol approach if applicable, color tokens, application notes, signals (what it communicates), rejects (what it explicitly is NOT). + +8. Provide production specs for the top 3 candidates. SVG-ready construction notes, color hex codes (primary plus single-color black plus single-color white plus reverse), sizing guidelines (minimum sizes per medium), motion entry and exit recommendation, embroidery and foil-stamp adaptations. + +9. Provide application mockups. Render each top candidate in 3 to 5 representative contexts: web header, business card, favicon at 16 and 32px, embroidery patch, signage. Mockups can be image-generated or schematic. The point is to show the client how the mark lives across contexts, not to deliver finished marketing material. + +10. Hand off. Output is decision material. The brand owner selects a direction. The skill (or a follow-up iteration) then produces production refinement on the chosen path: cleaner construction, refined kerning, color system finalization, application library. + +--- + +## Failure patterns + +- Designing for the founder's taste, not the audience's perception. The founder sees the logo every day; the audience sees it for 3 seconds in a bad mood. The audience-side test wins. +- Skipping the silhouette test. Logos that fail silhouette die at small sizes and in motion. Test early. +- Ignoring small-size legibility. A favicon test at 16px is the single most overlooked discipline. Most lockups fail here. Plan a fallback symbol or letterform-as-symbol mark from the start. +- Trying to depict everything the brand does. Logos can hold one idea, sometimes two. Three is too many. Symbols stuffed with multiple metaphors read as committee work. +- Picking a typeface for trend. Monoline geometric sans (Cabinet Grotesk, GT Pressura) read as "2024 startup" in a way that ages quickly. Pick for category-fit and longevity, not for design-trend currency. +- Over-customizing letterforms. Custom letterforms should solve a specific problem (a flat-bottomed "g" that conflicts with a descender, an "a" that breaks the rhythm, an "A" that becomes a mountain peak). Custom for novelty's sake reads as gimmicky. +- Lockups that fall apart at certain sizes. Test the lockup at 200%, 100%, 50%, 25%. If proportions break or elements clash at any size, the lockup needs adjustment. +- Color-dependent marks. A logo that requires color to be recognizable cannot survive single-color reproduction. Color is the last layer, not the foundation. +- Letterform-as-symbol marks that fail the silhouette test for the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. +- Reviewing too many similar variants. Showing a client 10 wordmark variants in different geometric sans typefaces dilutes the decision. Show 3 architectures, with 2 to 3 typographic options each. The client can see the architectural choice clearly. +- Skipping the embroidery test. Many brands eventually want a hat or a polo. A logo with fine detail or photographic gradients cannot be embroidered cleanly. Test before client signoff. + +--- + +## Output format + +Default output is a markdown spec with multiple variants, typically saved as `logo-variants.md` at the project root or in a `design/` subdirectory. The spec is paired with rendered images for each variant, saved alongside (typically in `design/logo-variants/`). + +Per-variant structure: + +1. Variant name. Descriptive identifier with index (e.g., "01, Light geometric wordmark, Avenir Next" or "07, Mountain peak A lockup, IBM Plex Sans"). +2. Architecture. Wordmark / Lockup / Symbol / Letterform-as-symbol / Monogram. +3. Typography. Specific typeface name and weight. Custom letterform notes if any. Tracking and kerning treatments. +4. Symbol description (if applicable). Approach (literal / abstract gesture / geometric reduction / letterform-derived / monogram) and visual description. Construction grid notes if relevant. +5. Color tokens. Hex codes for primary palette, single-color black version, single-color white version, reverse-on-dark treatment. +6. Application notes. Which contexts the variant excels in (e.g., "strong at large signage and letterhead") and which contexts need a fallback mark (e.g., "favicon falls back to letterform-as-symbol at 16px"). Embroidery adaptation notes if relevant. +7. Signals. What this variant communicates about the brand. The features it foregrounds. +8. Rejects. What this variant explicitly is NOT. The negative space the variant creates. +9. Mockups. Rendered in 3 to 5 application contexts. At minimum: web header, business card, favicon. Bonus: embroidery patch, large-format signage, social profile. + +The spec is decision material. The next step after delivery is selection plus production refinement on the chosen direction. + +--- + +## Reference files + +- [`references/architectures-explained.md`](references/architectures-explained.md). The 5 mark architectures with examples, when each fits, when each fails, and how to combine them in a primary plus fallback hierarchy. +- [`references/typographic-registers.md`](references/typographic-registers.md). The typographic registers with named typefaces, category-fit notes, and example brands per register. +- [`references/symbol-approaches.md`](references/symbol-approaches.md). The 5 symbol approaches with pattern examples, calibrating the agent's vocabulary for symbol generation. +- [`references/application-contexts.md`](references/application-contexts.md). The contexts every logo must pass, with constraint specs (favicon size, embroidery color count, single-color rules, motion entry recommendations). +- [`references/category-conventions.md`](references/category-conventions.md). A survey of common conventions across major brand categories, with defaults that work, conventions worth honoring, conventions worth breaking for positioning, and category-specific application contexts. +- [`references/example-variant-spec.md`](references/example-variant-spec.md). A complete example showing all nine per-variant fields filled in for a representative project. +- [`references/client-package.md`](references/client-package.md). The package format clients expect at delivery: file format matrix, variant matrix, folder structure, naming convention, documentation layer (usage guide plus brand colors plus license), delivery mechanisms, and the failure patterns that send the client back asking for a missing variant. diff --git a/dist/pi/.agents/skills/logo-design/references/application-contexts.md b/dist/pi/.agents/skills/logo-design/references/application-contexts.md new file mode 100644 index 0000000..a9cba88 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/application-contexts.md @@ -0,0 +1,312 @@ +# Application contexts + +A logo is not a single drawing. It is a system of marks that must work in every context the brand touches. Most logo failure happens because a designer optimized for one context (typically the web header at 200px wide) and never tested the others. This file expands the application contexts in [SKILL.md](../SKILL.md) with specific constraint specs, common failure modes, and mitigation patterns. Use it as the working checklist for every variant before declaring a candidate ready for review. + +The discipline is to design for the smallest, harshest application FIRST, then scale up. Most brand systems do the opposite: they design at the marketing scale and discover at production time that the mark cannot survive its smaller, harsher applications. + +--- + +## 16px favicon + +The most aggressive small-size test. The mark renders inside a 16x16 pixel grid (some browsers go to 32x32, but 16x16 is the historical baseline and still the test that reveals construction problems first). + +### Constraints + +- 16x16 pixels means roughly 4 to 6 distinguishable visual elements maximum +- No fine detail; lines under 2px disappear +- No gradients (gradients render as muddy color washes at this scale) +- No more than 3 to 4 colors before the rendering algorithm dithers +- Symbol or letterform must read at thumbnail scale, not as a logo + +### Failure modes + +- Lockups (wordmark plus symbol) almost always fail; the wordmark becomes illegible +- Fine letterform details (custom serifs, decorative crossbars) disappear +- Multi-color symbols dither into pixel noise +- Symbols with internal cutouts or fine negative space lose the cutout at 16px +- Geometric reductions with multiple primitives blur together + +### Mitigation patterns + +- Ship a dedicated 16x16 favicon-grade asset, not a downscaled version of the lockup +- Use a single element from the lockup (the symbol alone, the letterform-as-symbol, or the monogram) at favicon scale +- Test the favicon on actual browser tabs (Chrome, Safari, Firefox) at the operating system level; the rendering differs from a Photoshop preview +- If the favicon-grade asset cannot be derived from the lockup, the lockup itself is over-detailed; redesign the lockup so a clean 16x16 fallback exists + +--- + +## 28px app icon + +iOS, Android, and PWA app icons. Slightly more headroom than favicon (28x28 to 60x60 depending on rendering context) but still demanding strong silhouette. + +### Constraints + +- 28x28 to 60x60 pixels (varies by OS rendering context: notification badge, home screen, settings menu) +- Must work inside rounded-square or circle masks (iOS), rounded-square (Android) +- 4 to 8 distinguishable visual elements maximum +- Background color matters: app icons have visible bounds, so the mark either fills the icon background or sits inside a colored field +- No fine detail; lines under 3px disappear at the smallest rendering scales + +### Failure modes + +- Lockups fail at this scale almost as often as at favicon scale +- Symbols with thin strokes lose definition +- Multi-color symbols clash with the icon background fill +- Marks that depend on negative-space cutouts lose those cutouts +- Marks designed for a square ratio fail when rendered inside a circle mask + +### Mitigation patterns + +- Design the app icon as a separate asset, not a downscaled lockup +- Use the symbol or monogram, not the wordmark +- Pick a strong fill color that supports the symbol (not a generic white background) +- Test the app icon at every required size (29, 40, 60, 76, 80, 87, 120, 152, 167, 180, 1024 for iOS) and at every mask shape (rounded-square iOS, circle for some Android launchers) +- Ship a "monochrome" or "tinted" variant for iOS dark mode and tinted home screen modes (a single-color silhouette of the app icon) + +--- + +## 1.5 inch embroidery patch + +Tactile reproduction at small scale. Embroidered patches for hats, jackets, polos, and merchandise. The most demanding physical reproduction context. + +### Constraints + +- 1.5 inch diameter is the common patch size (some go to 2 or 2.5 inches) +- Color count: 4 to 6 maximum (each thread color is a separate setup cost) +- Minimum stroke weight: roughly 1mm (depends on the embroidery machine and thread weight) +- No gradients, no photographic elements, no fine textures +- Letterforms below 2mm tall do not embroider cleanly +- Sharp inside corners and acute angles fail under the needle path + +### Failure modes + +- Marks with more than 6 colors require expensive multi-step embroidery or get simplified by the embroiderer in ways the brand owner did not approve +- Fine letterforms (Garamond at small sizes, Helvetica Light) become muddy or fall apart +- Gradient marks fail entirely; the embroiderer either drops the gradient (changes the brand) or refuses the job +- Symbols with thin internal lines lose those lines under the thread weight +- Marks designed for screen do not anticipate the chunky construction embroidery requires + +### Mitigation patterns + +- Design an embroidery-grade variant of the mark from the start: simplified silhouette, chunky stroke weights, 4 colors maximum +- Test the variant against an actual embroidery sample (not a screen preview) before committing +- Pick a typeface for the wordmark that survives embroidery (slab serifs, heavy sans-serifs, custom thick letterforms work; thin sans-serifs and Garamond do not) +- For brands that anticipate substantial merchandise (apparel brands, hospitality brands, sports teams), build the embroidery-grade variant into the primary system, not as an afterthought + +--- + +## Single-color reproduction + +The mark must render in a single color, on any background, for any reproduction medium that does not support color. Etching, foil stamp, single-color print (offset or letterpress), faxed documents (still happens for legal and financial), engraving, screen printing limited to a single color. + +### Constraints + +- Pure black on white, pure white on black, or single ink color +- No gradients (must collapse to flat color) +- No color-dependent meaning (a symbol that means one thing in red and another in blue fails) +- No subtle color contrasts (a symbol with two shades of gray loses information when reduced to one color) + +### Failure modes + +- Color-dependent marks (the brand identity is the color, not the form) cannot be reproduced +- Gradients become muddy in single-color etching or foil +- Multiple-color symbols collapse to a single shape that does not read as the original +- Marks that rely on color-coded brand meaning (red = action, blue = trust) lose meaning +- Embossed or debossed reproductions test the construction grid; thin lines fail under embossment + +### Mitigation patterns + +- Test the design as a pure black-on-white silhouette early; if it does not read in monochrome, color is doing too much work +- Build a dedicated single-color version of the mark with stroke weights and proportions adjusted for monochrome reproduction +- Make sure the single-color version reads as the brand without color +- Pick application contexts that match the single-color variant (foil stamp on letterhead, engraved signage, etched glass, leather embossing, single-color print) + +--- + +## Reverse on dark + +The mark on a dark background. The brand's web header in dark mode. The signage at night. The product photography on a black field. The letterhead variant for black envelopes. Many marks fail when reversed because the negative space and stroke balance shift. + +### Constraints + +- Light strokes on dark background; the form is what is visible, not what is empty +- Gradient marks particularly struggle (the gradient direction may need to invert) +- Color contrast must remain readable (a brand color that works on white may disappear on black) +- Negative-space marks (where the brand identity is the empty space, like FedEx's hidden arrow) require careful inversion handling + +### Failure modes + +- Marks designed for light backgrounds invert into something that looks like a different mark +- Color contrast fails (yellow on black is fine; pale yellow on black is illegible) +- Thin strokes optimized for white-on-black render too heavy when inverted to black-on-white +- Symbols with internal cutouts work in one direction but not the other +- Brand color decisions made for one direction read wrong in the other + +### Mitigation patterns + +- Test every mark on dark backgrounds early in the process, not at production time +- Build dedicated reverse-on-dark variants where stroke weights or proportions are adjusted +- For marks that must work on both light and dark, design the construction grid so it is direction-neutral (Apple's apple, Nike's swoosh) +- For marks that cannot be neutral, ship two variants: light-on-dark and dark-on-light, with construction tuned for each + +--- + +## Large-format signage + +The mark at building scale. Storefront signage, lobby walls, conference signage, billboard, vehicle wrap. The opposite end of the scale spectrum from favicon. + +### Constraints + +- Sharp vector with no rasterization; print resolution must support 12+ feet output +- Construction grid integrity matters at every scale (proportional adjustments that work at 1 inch may not work at 12 feet) +- Thin strokes that survive at marketing scale may look anemic at signage scale +- Color reproduction differs (a brand color that prints clean on paper may print different on backlit acrylic, vinyl, or painted aluminum) +- Distance reading: the mark must read at street scale (50 to 200 feet) + +### Failure modes + +- Wordmarks with thin strokes look anemic at 12 feet +- Fine letterform details that read at marketing scale disappear at signage scale +- Color decisions based on screen rendering do not match the actual material (vinyl, paint, acrylic, illuminated channels) +- Lockups designed for desktop scale crowd or stretch when forced into signage's typical aspect ratios + +### Mitigation patterns + +- Test the mark at 8 to 12 feet wide as a printed mock-up before committing +- Build signage-grade variants where stroke weights are adjusted for distance reading +- Specify Pantone colors (not RGB or hex) for signage color reproduction +- For illuminated signage (channel letters, backlit acrylic), test the mark with the illumination direction the actual sign will use (front-lit, halo-lit, edge-lit each render differently) + +--- + +## Motion lockup + +The mark in animation. Brand entry sequences in video, app launches, motion identity. The mark is no longer static; it moves, scales, fades, transforms. + +### Constraints + +- The mark must have a natural entry and exit animation +- The construction must support stage-by-stage reveal (wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts) +- Frame rate: 30 to 60 fps for web, 24 fps for film +- Total animation duration: typically 1 to 3 seconds for brand entry; 0.5 to 1 second for app launch +- Easing curves must feel intentional, not generic + +### Failure modes + +- Marks with arbitrary construction have no natural animation; they snap into place rather than assembling +- Wordmarks animated with random letter entrance look generic; the entrance must follow the letterform construction +- Symbols animated with rotation or scale alone read as obvious; the animation should reveal something about the symbol's construction +- Animation duration too long becomes annoying; too short and the mark does not register + +### Mitigation patterns + +- Design the mark with animation in mind: the construction should suggest its own assembly +- Specify the motion direction: how does the mark enter, hold, and exit? +- Build a 1-second motion identity that works for app launch, video brand entry, and social media +- Test the motion at the actual deployment surface (app launch screen, social video, in-product brand entry) + +--- + +## Social profile picture (square) + +The mark in a square crop, usually inside a circle mask (Twitter, Instagram, LinkedIn, most social platforms). Lockups need a stacked alternate or symbol-only fallback. Symbol-only marks work natively. + +### Constraints + +- Square aspect ratio (often 400x400 to 800x800 pixels for social profile) +- Often rendered inside a circle mask, so the corners of the square are cropped +- Small enough size that fine detail disappears +- Must read in the user's notification feed at thumbnail scale (60-80 pixels) +- Color contrast against various background colors (light and dark mode platforms) + +### Failure modes + +- Horizontal lockups crop badly inside square; the wordmark loses its left and right edges +- Marks not designed for circle masking lose corners and read as cropped +- Detail that survives at 200x200 disappears at the 60-80 pixel notification feed scale +- Color choices that work on white backgrounds clash with the platform's darker UI + +### Mitigation patterns + +- Design a stacked alternate (symbol above wordmark, centered) for square contexts +- Use the symbol-only or monogram fallback for the social profile +- Test the mark inside a circle mask, not just inside a square +- Verify the mark reads at notification feed scale (60-80px), not just at the profile picture display scale (200-400px) + +--- + +## Apparel embroidery + +Thread on fabric, smaller scale than patch embroidery. Polo shirts, hats, beanies, t-shirts, aprons. The mark is embroidered directly into the fabric, often without a patch backing. + +### Constraints + +- Color count: 4 to 6 maximum (each thread color is a setup cost) +- Minimum stroke weight: 1.5mm to 2mm (heavier than patch embroidery because the fabric is the substrate) +- No gradients, no fine detail, no photographic elements +- Letterforms below 2.5mm tall do not embroider cleanly +- Fabric texture affects the read (cotton vs polyester vs wool render differently) +- The mark must survive washing (thread that bleeds or unravels on first wash is a quality failure) + +### Failure modes + +- Fine wordmark letterforms become muddy or fall apart +- Multi-color marks become expensive or get simplified without approval +- Marks with thin strokes do not survive washing cycles +- Marks not designed for fabric look pasted-on rather than embroidered + +### Mitigation patterns + +- Design a dedicated apparel-embroidery variant with chunky stroke weights and minimal color +- Specify thread colors (Madeira, Robison-Anton, or other professional embroidery thread brands) rather than CMYK or hex +- Test the variant on the actual fabric weight and color before committing +- Pick the variant of the mark that survives apparel embroidery (the symbol alone, the monogram, the simplified lockup) + +--- + +## Foil stamp on paper or leather + +Single-color metallic stamping. Business cards, letterhead, bound books, leather portfolios, signet rings, wax-seal-style stamps. The mark is impressed into the substrate with metallic foil. + +### Constraints + +- Single color (gold, silver, copper, black foil, etc.); no gradients +- Substantial line weight required (1mm+ minimum for gold or silver foil) +- No fine letterforms; thin serifs disappear under the foil impression +- The substrate matters (matte vs glossy paper, leather vs vellum); each renders differently +- The mark must read in metallic, not as a flat color + +### Failure modes + +- Thin letterforms disappear or look uneven under the foil +- Marks that depend on color contrast lose meaning in single-color metallic +- Heavy fills require more foil and may bleed at the edges +- Marks designed for screen rendering do not translate to the tactile, reflective surface of foil + +### Mitigation patterns + +- Design a foil-stamp variant with chunky stroke weights +- Specify foil color (PMS gold, silver, copper) and finish (matte vs glossy foil) +- Test the variant against the actual substrate (the brand's letterhead paper, the brand's leather portfolio cover) before committing +- Treat foil-stamp applications as a hierarchy decision: which mark goes here, given the constraints? + +--- + +## The discipline, restated + +Every variant under consideration must pass the application context test before it is a contender. The working checklist: + +1. 16px favicon. Does the mark survive at smallest scale? +2. 28px app icon. Does the mark work inside rounded-square or circle masks? +3. 1.5 inch embroidery patch. Can the mark be embroidered with 4-6 colors and chunky strokes? +4. Single-color reproduction. Does the mark read in pure black on white? +5. Reverse on dark. Does the mark hold up inverted on a dark background? +6. Large-format signage. Does the mark survive scaling to 12 feet? +7. Motion lockup. Does the mark have a natural entry and exit animation? +8. Social profile picture. Does the mark work inside a circle mask at 80px? +9. Apparel embroidery. Does the mark survive thread on fabric? +10. Foil stamp. Does the mark survive single-color metallic impression? + +If a candidate fails three or more of these, it is not a primary mark. It might still serve as a secondary or display lockup, but it is not carrying the brand. The brand needs a fallback hierarchy: primary lockup, secondary monogram or symbol-only, tertiary letterform-as-symbol or simplified mark for the harshest applications. + +The hierarchy is the system. The system is what makes the brand readable across every context the audience encounters. diff --git a/dist/pi/.agents/skills/logo-design/references/architectures-explained.md b/dist/pi/.agents/skills/logo-design/references/architectures-explained.md new file mode 100644 index 0000000..4eac4c8 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/architectures-explained.md @@ -0,0 +1,165 @@ +# Mark architectures explained + +The architectural decision is the foundational one. Every other choice (typographic register, symbol approach, application context discipline) flows from it. This file expands the five architectures listed in [SKILL.md](../SKILL.md) with reference brands, fit and failure modes, and a working pattern for combining them in a primary-plus-fallback hierarchy. + +--- + +## Wordmark only + +The logo is the brand name set in a chosen typeface, possibly with custom letterform interventions. No standalone symbol. The wordmark IS the mark. Stripe, Google, Pinterest, FedEx, eBay, Coca-Cola, Visa. + +The discipline is letter-by-letter. Kerning is not optional. Optical adjustments matter at every weight. A wordmark earns its place when the brand name is distinctive enough that the type alone carries identity. Stripe's wordmark uses a single-character optical adjustment on the lowercase "r" that makes the word read as a unit; without it, the word fragments visually. FedEx hides an arrow in the negative space between the "E" and the "x", a famous earned detail that the brand's audience finds and remembers. Google's wordmark redrew its own custom geometric sans (Product Sans) so the brand owns the wordmark's specific letterforms. + +Wordmark-only works hardest at small sizes. The full wordmark fails at favicon scale almost universally. A wordmark-only brand still needs a fallback mark for 16px contexts, embroidery, and stacked square applications, even if that fallback never appears in the primary lockup hierarchy. + +### When this fits + +- The name is short (4 to 8 letters works best; 9 to 12 is the upper edge) +- The name has at least one distinguishing letter or letter combination +- The brand has high enough recognition that the wordmark alone signals identity +- The category rewards type-led restraint (editorial, financial, professional services) +- There is room and willingness to pay for custom letterform work + +### When this fails + +- The name is long (10+ letters) and the wordmark cannot fit common contexts +- The category demands instant visual recognition (consumer goods at shelf, app icons) +- The wordmark's letterforms are generic and the brand cannot afford custom drawing +- The brand has no fallback mark for square contexts, social profiles, embroidery +- The wordmark looks identical to many other brands' wordmarks in the same category + +### Combining in a hierarchy + +Wordmark-only as the primary requires a separate symbol-grade asset for square and small contexts. The most common production setup pairs a wordmark with a letterform-as-symbol fallback. Pinterest does this: the wordmark is the primary, the "P" inside a circle is the avatar mark. Stripe does this with a custom geometric "S" for the favicon. The fallback shares visual DNA with the wordmark (same weight class, same custom letterform language) so the system reads as one mark with two surfaces. + +--- + +## Lockup (wordmark plus symbol) + +A wordmark and a symbol locked into a fixed relationship. Slack, Airbnb, Asana, Spotify, MasterCard. This is the default architecture for most brands because it covers the widest range of application contexts with the fewest fallbacks. + +Lockups have variants. Symbol-left-of-wordmark is most common (left-to-right reading languages naturally pull the eye to the symbol first, then the wordmark). Symbol-above-wordmark works when the symbol is tall and narrow or when the lockup must fit a vertically constrained space. Symbol-right-of-wordmark is rare and usually reserved for editorial or signature treatments. Each lockup also tends to have a stacked alternate (symbol above wordmark, centered) for square contexts and an isolated symbol-only fallback for the smallest applications. + +The construction discipline is geometric. The symbol's optical weight should match the wordmark's stroke weight. The space between symbol and wordmark should be tied to the wordmark's x-height or cap height (e.g., the gap equals one x-height of the wordmark). Slack's lockup uses a tightly proportioned hash symbol whose stroke matches the wordmark's stroke at every weight, and the gap is sized to the wordmark's x-height. Without this geometric discipline, lockups fall apart at scale: stretched at large sizes, crowded at small ones. + +### When this fits + +- The brand needs a symbol-grade asset alongside the wordmark +- The wordmark alone is not distinctive enough at small sizes +- The category benefits from a symbol's ability to travel beyond text contexts (apps, signage, branded merchandise) +- The brand will deploy both the symbol and the lockup in different contexts +- The brand has the budget for two finished assets (symbol and wordmark) instead of one + +### When this fails + +- The lockup falls apart at small sizes because the symbol carries detail that disappears +- Symbol and wordmark visually compete (different weight class, different optical density) +- The lockup has no stacked alternate for square contexts +- The brand uses the lockup at favicon scale, where the symbol-only or letterform-as-symbol fallback should carry +- The symbol is too literal or too abstract for the wordmark's tonal register + +### Combining in a hierarchy + +The most common production hierarchy: lockup primary, symbol-only fallback for square and small contexts (social profile, app icon, favicon at 24-32px), letterform-as-symbol or monogram for embroidery and 16px favicon. Slack ships exactly this: the lockup for marketing surfaces, the hash symbol alone for app icons, a simplified hash for favicon and embroidery. The hierarchy is one identity expressed across three asset grades. + +--- + +## Symbol only + +The mark is a symbol with no accompanying wordmark in the primary asset. Apple, Twitter (the bird era and the X era), Target, Nike's swoosh, Mercedes-Benz, Mastercard's circles. This is the highest-recognition tier and is almost never available to new brands. + +Symbol-only as the primary mark requires brand recognition the audience already holds. Apple did not start as symbol-only; the original Apple logo was a Newton-under-an-apple-tree illustration with the word "Apple Computer Co." beside it. The bitten apple symbol earned its standalone status across decades of advertising, product placement, and cultural ubiquity. New brands that try to launch as symbol-only typically fail to break through the recognition barrier and end up adding their wordmark back into the primary lockup. + +The exception is brands launching with massive marketing budgets that can purchase recognition directly. Some legacy financial and luxury brands (Mercedes-Benz, Mastercard) achieved symbol-only status by spending decades and billions on awareness. New brands attempting the same path almost always fail. + +### When this fits + +- The brand has decades of recognition and the symbol carries the brand alone +- The brand is in a category where symbols travel further than wordmarks (sports apparel, automotive, luxury goods) +- The symbol is distinctive enough that no other brand uses anything similar +- The brand has secondary contexts (signage, packaging, apparel) where wordmark space is not available +- The brand can afford the multi-decade investment in recognition + +### When this fails + +- The brand is new and lacks the recognition required for symbol-only to read as the brand +- The symbol is generic (a hexagon, a triangle, a circle) and could belong to thousands of other brands +- The brand has not invested in recognition through advertising or distribution +- Symbol-only is chosen as the primary because the wordmark is too long, when the real solution is a different architecture entirely +- The category demands wordmark presence (B2B SaaS, professional services, anything where the brand name needs to register before the symbol does) + +### Combining in a hierarchy + +Symbol-only is rarely the only asset. Even Apple ships a wordmark for legal contexts, contractual documents, marketing surfaces where the wordmark adds clarity. The hierarchy for symbol-only-primary brands is: symbol primary, wordmark for legal and contextual surfaces, lockup for select marketing applications. The symbol carries; the wordmark plays a supporting role. + +--- + +## Letterform-as-symbol + +A single letter from the brand name (often the first) is treated as the symbol. The letter is custom-drawn or aggressively styled to read as both letter and visual element. Beats by Dre's "b", McDonald's "M", Underscore's "_", a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. + +The cleanest path to symbol when the full wordmark is too long for a tight lockup, when the name has a letter that lends itself to visual play, or when the brand wants the symbol and the wordmark to share construction. Beats's "b" inside a circle is the exact "b" weight and proportion as the rest of the wordmark; the symbol IS the same lettering language. McDonald's "M" reads as the golden arches and as the letter; both readings are simultaneous and reinforce each other. + +The discipline is the silhouette test on the underlying letter. If the letterform is over-styled and the silhouette no longer reads as the letter, the symbol fails one direction of its job. If the letterform is under-styled and reads as just a typed letter, the symbol fails the other direction. The custom letterform must do double duty. + +### When this fits + +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to read as one identity +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands +- The brand needs a small-size and embroidery-friendly fallback that derives from the wordmark + +### When this fails + +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it +- The brand uses the letterform-as-symbol at sizes where it is illegible + +### Combining in a hierarchy + +A common setup: lockup primary, letterform-as-symbol for square contexts and embroidery, full wordmark for legal and large-format contexts. Beats does this. The letterform-as-symbol is the favicon, the app icon, the embroidered patch on Beats apparel. The wordmark in lockup is the marketing primary. The hierarchy makes one identity across asset grades. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol is the initials, often with ligature treatment, tight kerning, geometric framing (ring, shield, diamond), or stacked composition. CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent). + +Common in legal, financial, hospitality, fashion, and heritage brands where institutional gravity is the positioning. A monogram says "we have a long name" and "we own the initials of that name". It also says "we are old enough that abbreviating is acceptable", which is a positioning move. + +Monograms come in three flavors. Pure ligature (the letters share strokes; CN and GG are ligatures). Stacked or geometrically framed (the letters sit inside a ring, shield, or diamond; HBO is framed; YSL is geometrically composed). Tight kerning with no framing (the letters are simply set together with optical adjustments; VW reads as initials without frame). + +### When this fits + +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit (M and N, C and N, V and W work; I and J or O and U are harder) +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +### When this fails + +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials +- The brand uses the monogram alone in contexts where the audience does not yet recognize the initials + +### Combining in a hierarchy + +The classic hierarchy is: full wordmark for marketing primary, monogram for square contexts (social profile, embroidery, foil stamp, signet, wax seal), lockup with both wordmark and monogram for transitional surfaces (letterhead, business card, signage). Chanel, Gucci, and most luxury houses ship exactly this. The monogram is the most-applied mark on physical goods (apparel, hardware, bottles), the wordmark is the most-applied mark on digital and marketing surfaces, and the lockup is reserved for specific institutional surfaces. + +--- + +## Putting it together: the three-asset working pattern + +For most brands, the working asset hierarchy is three marks: + +1. Primary lockup for marketing, web, packaging, signage. Wordmark plus symbol locked into a fixed relationship. +2. Stacked or square alternate for social profiles, app icons, square contexts. Same elements as the lockup but recomposed for square. +3. Small-grade fallback for favicon, embroidery, foil stamps. A single element (symbol-only, letterform-as-symbol, or monogram) that derives from the lockup. + +All three must share visual DNA. Same letterform language, same construction grid, same optical weight class. A brand whose three marks read as three different brands has a system problem, not a logo problem. The discipline is to design the small-grade fallback FIRST, before the lockup, so the constraints of the smallest application drive the construction of the largest. diff --git a/dist/pi/.agents/skills/logo-design/references/category-conventions.md b/dist/pi/.agents/skills/logo-design/references/category-conventions.md new file mode 100644 index 0000000..6533083 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/category-conventions.md @@ -0,0 +1,489 @@ +# Category conventions + +Every category has a default visual register the audience expects. Working inside the default signals competence; the brand reads as belonging. Working outside the default signals positioning; the brand reads as making a deliberate move. Both are legitimate. The trap is doing either by accident. + +This file surveys ten major brand categories at parity. For each: the defaults that work, the conventions worth honoring, the conventions worth breaking for positioning, the cliches to avoid, the application contexts unique to the category, and reference brands as visual shorthand. + +--- + +## 1. Legal firms + +The category is dominated by heritage positioning. White-shoe firms, century-old partnerships, names tied to founding partners' surnames. The audience reading the logo is general counsel, founders raising or selling, CFOs in industries where the wrong attorney is materially expensive. The buyer brings high stakes and trusts visual signals of institutional gravity. + +### Defaults that work + +- Old-style or transitional serif typography for the wordmark. Garamond, Caslon, Sabon, Source Serif. The serif reads as institutional and serious. +- Lockup with monogram OR wordmark with monogram fallback. The full firm name is often long (multiple partner surnames) so the monogram does heavy lifting in constrained contexts. +- Restrained color palette. Navy, deep charcoal, oxblood, deep forest green. No primary red, no bright blue, no anything that reads as casual. +- Single-color reproduction built into the system from day one (court filings reproduce in black on white, foil stamps on letterhead are common, embossed signage on lobby walls). + +### Conventions worth honoring + +- Heritage signaling through old-style serif type and monogram architecture +- Single-color reproducibility for court filings and formal documents +- Geometric framing (ring, shield) only in restrained executions; heavy ornament reads as fake heritage + +### Conventions worth breaking for positioning + +- Geometric sans for the wordmark signals "modern, accessible" (boutique firms, tech-adjacent practices, plaintiff-side firms) +- Lighter color palette signals approachability (firms competing for client comfort, not gravity) +- Asymmetric lockup signals contemporary execution (firms positioning against the traditional white-shoe model) + +### Common cliches to avoid + +- The Roman-pillar-as-justice. Pillars are exhausted. +- The scales-of-justice icon. Done thousands of times; signals nothing. +- The gavel. Cliche. +- The lady-Justice silhouette. Same. + +### Application contexts unique to the category + +- Court filings (single-color black on white at small scale) +- Embossed letterhead and business cards (the foil-stamp test is real) +- Lobby and conference room signage (engraved brass, etched glass) +- Email signatures with the firm wordmark and individual attorney name +- Billable-hours invoices (the wordmark must look reproducible at low quality) + +### Reference brands + +- Latham & Watkins (LW monogram in serif, conservative palette) +- Wachtell, Lipton, Rosen & Katz (full firm name as wordmark, no symbol; positioning as "we don't need a symbol") +- Skadden, Arps, Slate, Meagher & Flom (Skadden monogram, restrained sans) + +--- + +## 2. Consumer goods / CPG + +The category is dominated by retail competition. The mark must register at shelf distance (10 to 15 feet), at thumbnail scale (online product imagery), and at rapid scan speed (the shopper has 2 seconds per shelf section). Distinctiveness is survival. + +### Defaults that work + +- Custom display typography for the wordmark. The brand owns its letterforms because the wordmark is on every package. +- Lockup with literal symbol OR strong wordmark only. The symbol depicts what the brand is about; the wordmark carries the brand name. +- Bold color palettes. Bright colors register at distance. Restraint is the exception. +- Pattern systems that extend the brand identity onto packaging surfaces. + +### Conventions worth honoring + +- Distinctiveness at small scale (online product thumbnails, 80x80 pixels) +- Single-color or simplified versions for embossed packaging, foil stamps, hot-metal printing +- Color recognition: the brand color is the first signal on shelf, before the wordmark even reads + +### Conventions worth breaking for positioning + +- Restrained typography signals premium positioning (Method, Brandless, Aesop) +- Black-and-white-only signals minimalist or anti-CPG positioning +- Hand-drawn or organic letterforms signal craft or small-batch positioning + +### Common cliches to avoid + +- The swoosh-as-growth. Borrowed from Nike. +- The leaf-as-natural. Done thousands of times in wellness and organic. +- The dot-or-circle-as-modernity. The 2010s startup tier. +- The hand-drawn brushstroke under the wordmark. Saturated. + +### Application contexts unique to the category + +- Retail packaging at shelf scale +- Online product thumbnails (80x80 to 200x200 pixels) +- Print catalog imagery (offset print, sometimes single-color) +- In-store signage and end-cap displays +- Branded merchandise (hats, totes, t-shirts the brand sells) + +### Reference brands + +- Method (custom geometric sans, restrained palette, premium positioning in a category dominated by aggressive color) +- Hu Chocolate (hand-drawn wordmark, organic typography, craft positioning) +- Brandless (anti-brand brand: minimalist sans, monochrome, the wordmark IS the absence of conventional branding) + +--- + +## 3. B2B SaaS + +The category is dominated by visual interchangeability. Most B2B SaaS brands use neo-grotesque sans typography, geometric reduction symbols, and a primary color in the blue-to-purple range. The mark blurs into the category default unless the brand makes deliberate distinguishing choices. + +### Defaults that work + +- Neo-grotesque sans typography (Inter, Söhne, GT America, custom). The default register reads as competent and contemporary. +- Lockup with abstract or geometric-reduction symbol. The symbol carries small-size and app-icon contexts. +- Single-accent color palette. A primary brand color plus monochrome, no busy palette. +- Custom letterform in the wordmark to escape the interchangeable default. + +### Conventions worth honoring + +- Screen rendering optimization (the wordmark must read at every screen size and DPI) +- App icon construction (the symbol must work inside rounded-square and circle masks) +- Monochrome reproducibility (single-color and reverse-on-dark should both work) + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in SaaS; positions against the modern startup tier) +- Bright primary color (red, orange, yellow) signals energy in a category that defaults to blue and gray +- Custom display typography signals long-term brand investment in a category where most brands look interchangeable + +### Common cliches to avoid + +- The geometric hexagon. The most overused symbol in tech. +- The three-bars stacked horizontally. The 2018-2020 SaaS tier. +- The triangle pointing right. Done. +- The bisected circle. Same. +- The single-letter-inside-circle without distinctive letterform construction. + +### Application contexts unique to the category + +- App icons (iOS, Android, web app, browser extension) +- Marketing site at desktop scale +- Documentation site at small scale (favicon, header, footer) +- In-product brand display (loading screens, empty states, account avatars) +- Slack and email integration logos (small thumbnails) + +### Reference brands + +- Stripe (custom Sohne wordmark, abstract gesture symbol, restrained palette) +- Linear (Inter wordmark, geometric reduction symbol, signature single-color execution) +- Vercel (custom Geist wordmark, geometric reduction triangle, bold black-and-white) +- Notion (custom letterform with notebook reference) + +--- + +## 4. Hospitality (hotels, restaurants, resorts) + +The category sits between heritage luxury and contemporary craft. The audience experiences the brand across many surfaces simultaneously: building exteriors, interior signage, room key cards, menus, uniforms, towels, sheets, packaging. Multi-surface coherence is the discipline. + +### Defaults that work + +- Custom display typography OR transitional serif for the wordmark. The brand often becomes the visual identity of the property. +- Lockup with monogram fallback. The monogram appears on towels, sheets, room keys, embroidered uniforms. +- Restrained palette with a single signature color. The palette extends to interior design, materials, lighting. +- Embroidery-grade variant built into the system from day one. + +### Conventions worth honoring + +- Embroidery on uniforms, towels, robes, sheets (the monogram does this work) +- Foil-stamp on stationery, room key cards, room service menus +- Engraved or etched signage on building exteriors and interior wayfinding +- Restraint in palette (heritage hospitality avoids loud color) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "boutique, design-forward" (Ace Hotel, Standard Hotels) +- Bold color signals contemporary or playful positioning +- Asymmetric lockup signals contemporary execution +- Display custom typography signals investment in a unique brand identity + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in heritage hospitality. +- The shield-with-year-founded. Every craft beer label uses this. +- The crossed-keys (Hermes-derived). Done. +- The mountain-or-palm-tree literal symbol for resort properties. Done. + +### Application contexts unique to the category + +- Building exterior signage (channel letters, illuminated) +- Room key cards (foil stamp on plastic or paper) +- Towels, robes, sheets (embroidery) +- Glassware, china, silverware (etched, engraved) +- Stationery (letterhead, envelopes, business cards, foil stamp) +- Uniforms (embroidered name tags and lapel pins) +- Bag tags and luggage labels + +### Reference brands + +- Aman Resorts (restrained typographic identity, Asian-influenced design discipline) +- Soho House (custom display typography, monogram primary, modern member-club positioning) +- Ace Hotel (custom display typography, contemporary boutique positioning, regional variation across properties) + +--- + +## 5. Healthcare + +The category is dominated by trust signaling. The audience may be anxious, stressed, or grieving. The brand must read as competent and calm without reading as cold or clinical. Trust is built through restraint, not through aggressive visual claims. + +### Defaults that work + +- Humanist sans typography for the wordmark. The calligraphic warmth carries trust. +- Lockup with abstract gesture symbol. The symbol suggests care, balance, or healing without depicting it literally. +- Calm color palette. Blue, green, soft warm neutrals dominate. +- Plenty of whitespace in the brand system. Density reads as anxiety. + +### Conventions worth honoring + +- Accessibility floor: WCAG AA contrast ratios on every brand color combination +- Restrained palette: no aggressive red (reads as emergency or alarm) +- Avoid imagery that could be misread (a symbol that suggests a religious cross when the brand is secular, a symbol that suggests a specific medical specialty when the brand is generalist) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "tech-forward primary care" (One Medical, Forward) +- Warmer color palette (coral, peach, soft yellow) signals "we are not your old doctor's office" +- Custom display typography signals contemporary positioning (rare in legacy healthcare) + +### Common cliches to avoid + +- The medical cross. Trademark-protected by the Red Cross in some uses; otherwise generic. +- The caduceus (snakes around a staff). Misread by audiences as Hermes; not actually the medical symbol. +- The heartbeat-line. Saturated in fitness and healthcare. +- The blue-and-green gradient. The default healthcare palette to a fault. + +### Application contexts unique to the category + +- Wayfinding signage in clinics and hospitals +- Patient-facing materials (intake forms, appointment reminders, billing statements) +- Medical equipment branding (the wordmark on a screen, on a printed report) +- Insurance and billing communications (the wordmark on bills the patient hopes are accurate) +- Clinic uniforms and badges + +### Reference brands + +- One Medical (humanist sans wordmark, simplified circle symbol, restrained palette, primary care positioning) +- Forward (custom display typography, geometric reduction symbol, tech-forward primary care) +- Hims (custom geometric sans, single-color execution, modern men's health positioning) + +--- + +## 6. Financial services + +The category splits between heritage and fintech-modern. Heritage banks (Goldman Sachs, JPMorgan, Morgan Stanley) lean into old-style serif and institutional gravity. Fintech challengers (Ramp, Mercury, Stripe) lean into neo-grotesque sans and modern restraint. The split is itself a positioning decision. + +### Defaults that work + +- Old-style serif OR neo-grotesque sans (the heritage-vs-fintech axis) +- Lockup with monogram fallback (heritage) OR wordmark with abstract symbol (fintech) +- Restrained palette. Navy, gold, deep green for heritage. Black, white, single-accent for fintech. +- Single-color reproducibility built into the system (foil stamps, embossed checks, single-color regulatory documents) + +### Conventions worth honoring + +- Single-color reproducibility (foil stamps, regulatory filings, embossed checks) +- Trust signals through restraint and material quality (heavy paper, foil stamps) +- Color choice signals heritage (navy, gold, deep green) vs fintech (black, white, electric accent) + +### Conventions worth breaking for positioning + +- Modern geometric sans in heritage financial services signals "boutique, contemporary" (rare and high-stakes) +- Bright color in heritage financial services signals "we are not your father's bank" (high-risk positioning) +- Old-style serif in fintech signals "we take regulatory compliance seriously" (positions against fast-and-loose fintech) + +### Common cliches to avoid + +- The eagle-as-strength. Heritage cliche. +- The shield-as-security. Cliche across heritage and fintech. +- The bull-as-bullish. Wall Street cliche. +- The geometric chevron pointing up. Fintech cliche. +- The blue-and-gold gradient. Heritage default that reads as visually unconsidered. + +### Application contexts unique to the category + +- Embossed credit and debit cards (the mark is impressed, not printed) +- Regulatory filings and disclosures (single-color reproduction) +- Bank checks (single-color print, MICR-encoded routing numbers) +- Branch signage (channel letters, illuminated) +- ATM screens and branded interfaces + +### Reference brands + +- Goldman Sachs (old-style serif wordmark, restrained palette, heritage positioning) +- Ramp (custom Söhne wordmark, abstract symbol, modern restrained palette) +- Mercury (custom geometric sans, abstract gesture symbol, fintech positioning with restraint) + +--- + +## 7. Editorial / publishing + +The category is dominated by typography. The masthead IS the logo. Most editorial brands have no separate symbol; the wordmark in a specific custom serif IS the entire identity. The discipline is letterform and proportional refinement. + +### Defaults that work + +- Custom display typography OR old-style serif OR transitional serif for the wordmark +- Wordmark only OR wordmark with monogram fallback +- Black-on-white as the default reproduction (newsstand, print, digital header) +- Restrained palette (typically a single accent color, often the brand's signature) + +### Conventions worth honoring + +- Single-color reproducibility (every newspaper masthead must work in black on white at masthead scale) +- Custom letterform investment (the masthead is the brand's most-rendered asset) +- Typographic heritage (the masthead often references the publication's founding-era typography) + +### Conventions worth breaking for positioning + +- Geometric sans signals contemporary editorial (Vox, BuzzFeed, Vice attempted versions of this) +- Bold color signals contemporary positioning (rare in legacy editorial) +- Modern asymmetric layouts signal contemporary craft + +### Common cliches to avoid + +- The blackletter masthead. Saturated for newspapers; reads as German tabloid. +- The decorative initial cap drop. Editorial cliche. +- The pen-nib symbol for writing or journalism brands. Cliche. +- The book-and-ribbon. Cliche. + +### Application contexts unique to the category + +- Newsstand at street scale (the masthead must read at 50 to 100 feet) +- Print body and headline typography (the wordmark sits at the top of every printed page) +- Digital masthead at desktop and mobile scale +- Subscription and renewal direct mail (single-color print) +- Cover photography (the masthead overlays photographic backgrounds) + +### Reference brands + +- The Atlantic (custom transitional serif, restrained palette, editorial heritage) +- The New Yorker (custom Caslon-derived masthead, the mark is unmistakable) +- Cereal (custom display sans, considered minimalism, contemporary editorial) + +--- + +## 8. Tech / AI + +The category is dominated by abstract gesture and geometric reduction. Most AI and tech brands lean into one of two modes: either neo-grotesque sans with abstract gesture symbol (Anthropic's flower, OpenAI's geometric mark) or aggressive geometric reduction (every blockchain logo, every web3 brand). Visual fatigue in the category is real. + +### Defaults that work + +- Neo-grotesque sans OR custom geometric sans for the wordmark +- Lockup with abstract gesture or geometric reduction symbol +- Single-accent color palette. Often the brand's "signature color" plus monochrome. +- Construction grid discipline in the symbol + +### Conventions worth honoring + +- Screen rendering optimization (the brand lives on screens at every size) +- App icon construction (rounded-square and circle masks, every iOS/Android size) +- Monochrome and reverse-on-dark variants + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in tech, signals against the dominant aesthetic) +- Hand-drawn or organic letterforms signal craft or human-centered positioning +- Bright primary color signals energy in a sea of muted palettes + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain. The most overused symbol in crypto. +- The neural-network-circles symbol for AI brands. Done thousands of times. +- The brain-with-circuit-traces. Cliche. +- The triangle-with-an-eye. Cliche. +- The default purple gradient. The 2018-2022 tech tier. + +### Application contexts unique to the category + +- Developer documentation sites (the wordmark sits in dense technical contexts) +- API and CLI integrations (the brand appears in terminal output, error messages, log lines) +- Loading screens and empty states in product +- Open-source repository profile pictures +- Conference talk slide branding + +### Reference brands + +- Anthropic (custom display typography, abstract gesture symbol, restrained palette) +- OpenAI (custom geometric mark, simple wordmark, monochrome execution) +- Hugging Face (custom emoji-as-symbol, distinctive in a category that doesn't usually allow it) + +--- + +## 9. Outdoor / lifestyle / apparel + +The category sits at the intersection of illustration, heritage, and embroidery. Many outdoor brands use illustration-driven marks with hand-drawn or vintage-inspired execution. The application context is frequently embroidered (apparel, hats, packs) so the mark must survive thread on fabric. + +### Defaults that work + +- Custom display typography OR slab serif for the wordmark +- Lockup with literal symbol depicting the brand's outdoor world (mountain, river, tree, animal silhouette) +- Heritage color palette. Earth tones, warm reds, deep greens, cream-and-coffee +- Embroidery-grade variant built into the primary system + +### Conventions worth honoring + +- Embroidery on apparel, hats, and packs (the mark must survive 4-6 colors on thread) +- Patch-friendly construction for hats and uniforms +- Hand-drawn or vintage-inspired execution that signals craft and authenticity +- Color palette referencing the brand's outdoor environment + +### Conventions worth breaking for positioning + +- Modern geometric sans signals contemporary outdoor (Topo Designs, Outdoor Voices) +- Bright color signals younger or athletic positioning +- Wordmark-only signals premium or design-led positioning (rare) + +### Common cliches to avoid + +- The bear silhouette. Saturated for outdoor and lifestyle. +- The mountain peak with a sun rising. Done. +- The compass rose. Saturated for travel and outdoor. +- The Pacific-Northwest cabin aesthetic. Saturated since 2015. +- The tent silhouette. Cliche. + +### Application contexts unique to the category + +- Apparel embroidery (hats, polos, jackets, packs) +- Patch embroidery (jackets, packs, vests) +- Heat-transfer printing on technical fabrics +- Hangtags and care labels on apparel +- Retail signage at small specialty stores + +### Reference brands + +- Patagonia (custom display typography, Fitz Roy mountain silhouette, signature gradient palette) +- REI (custom slab serif wordmark, the wedge symbol, outdoor heritage positioning) +- Filson (custom slab serif, monogram and shield treatments, heritage workwear positioning) +- Topo Designs (custom display typography, contemporary outdoor positioning, designed in Colorado) + +--- + +## 10. Fashion / luxury + +The category is dominated by monogram and ligature conventions. Most heritage luxury brands use monograms (Chanel CN, Gucci GG, Yves Saint Laurent YSL, Louis Vuitton LV). Modern accessible-luxury brands lean toward custom display typography (The Row, Aimé Leon Dore, Jacquemus). The split is the positioning question. + +### Defaults that work + +- Old-style serif OR custom display typography OR ligature monogram for the primary mark +- Lockup with monogram fallback OR wordmark with monogram on goods +- Restrained palette. Black, white, gold, and the brand's signature accent +- Embroidery-grade variant for apparel and accessories + +### Conventions worth honoring + +- Embroidery on apparel and accessories (the monogram does this work) +- Foil stamp and emboss on packaging (the wordmark or monogram impressed in metallic foil) +- Material quality (heavy paper, leather, metallic foil) +- Restraint in palette and ornamentation + +### Conventions worth breaking for positioning + +- Modern geometric sans signals accessible-luxury (The Row, Aimé Leon Dore lean restrained-modern) +- Bright color signals contemporary or playful luxury (rare and risky) +- Hand-drawn or expressive letterforms signal craft positioning + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in fashion and hospitality. +- The decorative monogram with filigree. Reads as Renaissance Faire, not as Hermès. +- The shield-with-year-founded. Done. +- The gold-foil-with-Old-English-typeface. Cliche fake-heritage. + +### Application contexts unique to the category + +- Apparel embroidery (logos, monograms, signatures stitched into garments) +- Hardware embossing (buttons, rivets, zipper pulls, leather goods) +- Foil stamp on packaging (boxes, dust bags, ribbon) +- Engraved or etched hardware (jewelry, watches) +- Vellum and tissue paper printing (gift wrap, bag liners) +- Window displays at flagship stores + +### Reference brands + +- Chanel (CN monogram, no symbol beyond initials, the most institutionally consistent fashion brand) +- Gucci (GG monogram, custom display typography for the wordmark) +- The Row (custom display typography, restrained accessible-luxury positioning) +- Aimé Leon Dore (custom display typography, contemporary heritage positioning, restrained monogram on apparel) + +--- + +## How to use this file + +When designing for a category not your own, start with the defaults. They exist because they work. The audience reads them as competence. + +When designing for a category you want to position against, identify which convention you are breaking and why. The break should be deliberate and supported by the rest of the brand system. A boutique law firm in geometric sans signals modern positioning IF the rest of the brand (color, photography, voice, materials) also signals modern positioning. Breaking type without breaking the rest of the system reads as random. + +When designing without category context, the defaults are still the right starting point. Most brands sit inside a category. Most brands benefit from being recognizable inside that category before they push for distinctiveness. Distinctiveness without belonging reads as outsider; belonging without distinctiveness reads as forgettable. The discipline is to start with the category default and earn each departure. diff --git a/dist/pi/.agents/skills/logo-design/references/client-package.md b/dist/pi/.agents/skills/logo-design/references/client-package.md new file mode 100644 index 0000000..e41adf0 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/client-package.md @@ -0,0 +1,187 @@ +# Logo client package + +The package format clients expect when handing logo work back. The discipline here is doing the boring work upfront so the client never has to ask for "the SVG version" or "a small one for favicons" or "white-on-dark for the slide deck." + +## When this applies + +- Final delivery of logo work to a client (internal or external) +- Mid-project handoff where another team needs to start building against the mark +- Brand-refresh deliverables where existing applications need to update + +## When this does NOT apply + +- Concept presentation. Concept stage is for direction-setting, not delivery. Concept decks include 2-3 mark variations with rationale, not a full package. +- Style-guide level brand systems. The client package is the deliverable for the mark itself; a brand-style-guide is a separate concern covering color, type, voice, photography, motion. See the brand-style-guide skill. +- Individual application-specific exports. If the client needs a 2400x1260 LinkedIn cover image with the mark composed against a photo, that is a one-off design request, not a package update. + +## The package format + +### File formats (the matrix) + +Every variant ships in formats that cover the contexts the client will actually use: + +\| Format \| Use case \| Notes \| +\|---\|---\|---\| +\| SVG \| Web, scalable applications, modern email clients \| Primary delivery format. Vector. \| +\| AI or EPS \| Editable source for designers \| Source file. Layered if the mark has multiple components. \| +\| PDF \| Print, vector applications, archival \| Vector. Embedded fonts or outlined. \| +\| PNG (transparent) \| Web, slide decks, raster contexts where background is unknown \| Multiple sizes: 64, 128, 256, 512, 1024, 2048. \| +\| JPG \| Email signatures, contexts where transparency is not supported \| Solid background; usually white. Single size, 1024px wide. \| +\| ICO \| Favicon \| Multi-resolution: 16x16, 32x32, 48x48 packed into one file. \| +\| Apple touch icon (PNG) \| iOS home-screen bookmarks \| Single size, 180x180. \| + +The asymmetry matters. Vector formats (SVG, AI, PDF) are the source of truth; raster formats (PNG, JPG, ICO) are derived from the vector source at delivery time. Never deliver only raster; clients eventually need to scale up and they cannot. + +### Variant matrix + +The client gets every meaningful combination of the variant axes: + +Color treatment: +- Primary (full color, the canonical mark) +- Reverse (white on dark, for dark backgrounds) +- Mono black (single black, for grayscale or low-fidelity contexts) +- Mono white (single white, for full-bleed dark photography) +- Mono brand (single color in the brand color, for one-color print) + +Composition (where the mark has multiple lockups): +- Primary lockup (the canonical composition, usually horizontal) +- Stacked (vertical, for narrow contexts like favicons or app tiles) +- Symbol-only (when the wordmark is unavailable or unnecessary, like profile avatars) +- With tagline (where a tagline is part of the mark system) +- Without tagline + +The client gets every relevant combination. A simple wordmark might have 5 variants total (primary across 5 color treatments). A complex lockup with tagline plus symbol variants might have 30+. Either way: the matrix is exhaustive within the system, not arbitrary. + +### Folder structure + +Organized so the client can find what they need without thinking: + +``` +{brand-name}-logo-package/ +├── 01-primary/ +│ ├── primary-color.svg +│ ├── primary-color.ai +│ ├── primary-color.pdf +│ ├── primary-color-2048.png +│ ├── primary-color-1024.png +│ ├── primary-color-512.png +│ ├── primary-color-256.png +│ ├── primary-color-128.png +│ ├── primary-color-64.png +│ └── primary-color.jpg +├── 02-reverse/ +│ └── (same format set, white-on-dark) +├── 03-mono/ +│ ├── mono-black/ (full set) +│ ├── mono-white/ (full set) +│ └── mono-brand/ (full set) +├── 04-stacked/ +│ └── (same format set, vertical lockup) +├── 05-symbol/ +│ └── (symbol-only variants if applicable) +├── 06-favicon/ +│ ├── favicon.ico +│ ├── apple-touch-icon.png +│ ├── favicon-16.png +│ ├── favicon-32.png +│ └── favicon-48.png +├── 07-applications/ +│ ├── business-card-mockup.pdf +│ ├── letterhead-mockup.pdf +│ ├── email-signature.png +│ └── social-avatar.png +├── 08-documentation/ +│ ├── usage-guide.pdf +│ ├── brand-colors.pdf +│ └── license.pdf +└── README.md +``` + +Numbered prefixes ensure the client opens folders in the order that matches how they will use them. Documentation last because nobody reads it first; applications second-to-last because they are reference, not deliverable. + +### File naming convention + +Inside each folder, files follow this pattern: + +``` +{variant}-{color}-{size or context}.{ext} +``` + +Examples: +- `primary-color.svg` +- `primary-color-2048.png` +- `reverse-white.svg` +- `mono-black-1024.png` +- `stacked-color.pdf` +- `symbol-color.svg` + +Consistent naming means the client can guess a filename before looking. + +## The documentation layer + +Inside `08-documentation/`: + +### usage-guide.pdf + +Covers: +- Clear space: minimum padding around the mark, expressed as a multiple of a recurring element (often the x-height of the wordmark or the diameter of the symbol) +- Minimum size: smallest legible application, with explicit size for digital (px) and print (mm or in) +- Do's: contexts where the mark works +- Don'ts: stretching, recoloring outside the variant set, rotating, applying effects (drop shadow, gradient, embossed), placing on busy photography without sufficient contrast, replacing the typography in a wordmark +- Co-branding rules: how the mark composes with partner marks, including spacing and order + +A usage guide that just lists the variants is documentation theater. The do's-and-don'ts section is what protects the mark in the wild. + +### brand-colors.pdf + +Color values for every meaningful representation: +- Hex (web) +- RGB (digital) +- CMYK (print) +- Pantone (spot color print) +- HSL (where the brand has a programmatic color system) + +If the mark uses gradients, document the gradient stops and direction explicitly. Gradients vary in unpredictable ways across rendering engines; precise documentation is the only protection. + +### license.pdf + +Covers: +- Who owns the mark (usually the client) +- Who the designer is (for attribution, if required) +- Usage terms (typically: client has full and exclusive use; designer retains the right to display in portfolios) +- Modification rights (typically: client cannot modify without designer consent during a defined warranty period; after that, all rights to modify pass to the client) +- Successor terms (what happens if the client sells the brand or merges with another company) + +License documentation is the part most independent designers skip and most agencies overformat. The middle path is a 1-page document that names the parties, defines usage, and is signed. + +## Delivery mechanisms + +Three patterns, in increasing formality: + +ZIP archive over email. Smallest projects. The client gets a single `.zip`, downloads, expands, drops into their workspace. Works for packages under ~50 MB. Watch out for email size limits. + +Cloud storage link. Most common pattern. Drive, Dropbox, Box, OneDrive. Client gets a link, downloads at leisure, can re-share within their organization. Set link to view-only with download enabled. Set an expiration date if warranty terms are time-bound. + +Brand portal. Largest projects. Paid tools like Frontify, Brandfolder, Brandkit. The portal becomes the canonical source of truth; the client gets logins for stakeholders. Worth the cost when there are 10+ internal stakeholders downloading assets ad hoc, or when the brand system has dozens of marks (parent plus sub-brands). + +Match the mechanism to the client's actual workflow, not their stated preference. Clients will say they want a brand portal, then download the ZIP and never log in to the portal again. + +## Failure patterns + +Delivering only raster. PNG-only or JPG-only packages mean the client cannot scale up cleanly. Always include vector. If the work was done in raster (rare for logo work, but it happens), trace to vector before delivery. + +Delivering only the primary variant. A primary-mark-only package fails the moment the client needs to put the mark on a dark background or print it in one color. The variant matrix is the deliverable, not an optional extra. + +Delivering source files without a license document. Clients who paid for the work expect to own it. Source files (AI/EPS) without an explicit license create ambiguity that surfaces during acquisitions or partnerships. Always include the license PDF. + +Variant naming drift across the package. `Primary_Logo_Color.svg` in one folder and `primary-color.svg` in another means the client's tooling (CMS, design system) will not recognize the assets consistently. Pick a convention; apply it everywhere. + +Skipping the favicon. Almost every client will host a website. The website needs a favicon. Adding the favicon variant adds one folder; omitting it means the client comes back asking for it. + +Embedding fonts in the SVG without confirming licensing. SVG with embedded font glyphs is fine when the font is open-source. When the font is licensed (e.g., a Monotype or Adobe Fonts file), embedding the glyphs may violate the license. Outline the font in the SVG before delivery; the visual remains identical, and the licensing risk disappears. + +## What "done" looks like + +The client opens the ZIP (or the cloud link), sees a numbered folder structure, opens `01-primary/primary-color.svg`, and ships the mark to production within 5 minutes. + +If the client emails back asking "do you have a white version?" or "is there an SVG?" or "can you send the favicon?", the package was incomplete. diff --git a/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md b/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md new file mode 100644 index 0000000..111b6b2 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/example-variant-spec.md @@ -0,0 +1,100 @@ +# Example variant spec + +A fully populated single-variant spec for a fictitious brand, Atlas Coffee. Atlas is a hypothetical specialty coffee company sourcing single-origin beans from Latin American producers, roasting in small batches, retailing through a single flagship cafe and an online subscription. The brand brief calls for considered craft positioning, outdoor adjacency without literal outdoor imagery, warmth without rusticity. + +This file shows what one variant looks like when documented for client review. A complete deliverable contains 6 to 12 such variants. The agent uses this format as the per-variant template; the client uses it to evaluate, compare, and select. + +--- + +## Variant 07, Mountain peak A lockup, IBM Plex Sans + +### Architecture + +Lockup. The wordmark sits to the right of a custom letterform-as-symbol "A". The "A" reads as both the first letter of "Atlas" and as a stylized mountain peak. The lockup also has a stacked alternate (the "A" centered above the wordmark) for square contexts and a symbol-only fallback (the "A" alone) for favicon, embroidery, and stamping. + +### Typography + +- Wordmark typeface. IBM Plex Sans, Medium weight (500), tracking +5 (10 units, on a 1000-unit em). +- Custom letterform. The "A" is a custom drawing, not IBM Plex Sans. The crossbar is replaced with a single horizontal stroke at 38 percent height; the apex rises to a sharp peak; the legs are slightly splayed (8 degrees from vertical) to suggest mountain base width without exaggeration. The custom "A" replaces the typed "A" in the wordmark "Atlas Coffee" so the entire wordmark reads as a unit. +- Wordmark composition. "Atlas Coffee" set as one word, with a small visual gap between "Atlas" and "Coffee" (one half x-height of additional spacing) so the eye reads both words as parallel parts of the same name without forcing a hyphen or stacked composition. +- Optical adjustments. The "t" of "Atlas" is shortened by 4 units to balance against the rising "A" to its left. The "f" of "Coffee" has its terminal pulled inward by 3 units to prevent it from reading as an extra bar. + +### Symbol description + +The custom "A" is the symbol. The construction is built on a 4-unit grid: + +- Apex height: 4 units, sharp peak +- Crossbar: at 1.5 unit height, single horizontal stroke +- Leg width at base: 4 units, splayed 8 degrees from vertical +- Stroke weight: matches the wordmark's stroke weight at the chosen Medium weight (approximately 90 units on a 1000-unit em) + +The peak silhouette is ungenerous on the apex (sharp, not rounded). The crossbar is single-stroke (no double bars). The legs end with a flat foot, not a serif. At every scale, the silhouette reads first as a peak, then as the letter A. The double-reading test passes. + +### Color tokens + +- Primary. Warm charcoal `#2A2521`. The wordmark and the "A" symbol both use this color in standard reproduction. +- Accent. Rust `#B85C38`. The accent appears in marketing surfaces (web header backgrounds, packaging trim) but not in the lockup itself. +- Single-color black. `#000000`. For court filings is irrelevant; for embossed letterhead, foil stamp on paper, single-color print, fax (yes, still). The mark renders as pure black on white. +- Single-color white. `#FFFFFF`. For reverse-on-dark applications (web header in dark mode, signage at night, embossed on dark leather). +- Reverse-on-dark variant. White on a dark background; the symbol's negative space inversion is direction-neutral so the mark reads identically in either direction. + +### Application notes + +The variant excels at: +- Large-format signage. The peak silhouette reads at street scale; the wordmark holds at 8 to 12 feet wide. +- Retail packaging. The lockup at coffee bag scale (4 inches wide) is the natural size; the symbol carries the front, the wordmark anchors the side. +- Mug and ceramic stamping. The lockup with stacked alternate works on cylindrical surfaces. +- Embossed letterhead. The custom "A" embossed at the top, the wordmark printed below in standard color. +- Web header at desktop scale (200 to 400 pixels wide). The lockup reads cleanly at this size. + +The variant needs fallbacks at: +- 16 px favicon. The full lockup fails; the symbol-only "A" carries. +- 1.5 inch embroidery patch. The lockup is too wide; the symbol-only "A" with the wordmark stacked below in a chunky weight (e.g., IBM Plex Sans Bold) is the patch variant. +- App icon at 28 to 60 pixels. The symbol-only "A" inside a colored field (warm charcoal background, white "A") is the app icon variant. +- Square social profile. The stacked alternate (the "A" above the wordmark, centered) is the social profile variant. + +Embroidery adaptation: thread color matched to the warm charcoal primary (Madeira Polyneon `1842` is the closest match for the primary, with `1338` for the rust accent). The embroidery-grade variant of the symbol-only "A" requires a 3 unit minimum stroke weight scaled for 1.5 inch patch reproduction. + +### Signals + +- Considered craft. The wordmark's optical adjustments (shortened "t", pulled-in "f") signal that the brand has thought about every letterform, which signals that the brand thinks about every other detail. +- Outdoor / adventure adjacency without literal outdoor imagery. The mountain peak silhouette references outdoor without depicting a trail, a tree, or a campsite. The audience associates the brand with adventure-adjacent positioning without the brand becoming a Pacific-Northwest cliche. +- Warmth without rusticity. The warm charcoal primary and rust accent read as warm but considered. The palette avoids the heritage-coffee browns and the third-wave-minimalist whites; the in-between space signals contemporary craft. +- Single-origin discipline. The restrained execution (one symbol, one wordmark, one accent color) signals that the brand chooses few things deliberately. The same discipline appears in single-origin coffee sourcing. + +### Rejects + +- Not a typical coffee shop laurel mark. Atlas does not use a laurel wreath, a coffee bean, a coffee cup, or any direct depiction of coffee. The brand is about the experience and origin, not the commodity. +- Not a third-wave-minimalist wordmark with no symbol. Many specialty coffee brands have moved toward wordmark-only with no symbol. Atlas chooses a lockup because the brand wants a symbol-grade asset for embroidery, hardware stamping, and merchandise. +- Not a literal coffee bean. No bean, no berry, no plant in the symbol. The category cliche is rejected. +- Not a Pacific-Northwest-cabin aesthetic. No tree silhouette, no compass rose, no flannel-pattern background. The brand's outdoor adjacency is structural (peak silhouette in the letter), not stylistic. + +### Mockups + +The mockups would be rendered as image assets in a complete deliverable. Described in prose: + +1. Storefront signage at street scale. The lockup as channel letters above the cafe entrance, illuminated, mounted on stained wood paneling. The peak silhouette reads from across the street; the wordmark anchors the brand name as visitors approach. + +2. Retail bag at shelf scale. The 12 oz coffee bag with the lockup printed at 4 inches wide on the front, the wordmark-only with origin information on the side panel. The symbol's peak references the high-altitude growing regions where Atlas sources beans. + +3. Espresso cup at table scale. Double-walled glass cup with the symbol-only "A" stamped in warm charcoal at 1 inch tall on the cup wall. The lockup is on the saucer rim. The customer sees both marks during a 4-minute espresso experience. + +4. Embroidered apron. Black cotton apron with the symbol-only "A" embroidered in rust on the chest pocket. The wordmark is embroidered on the back at the lower hem, in warm charcoal thread, smaller scale. The aprons are durable goods that get washed weekly; the embroidery is built for that. + +5. Social profile picture as stacked mark. The stacked alternate (the "A" above the wordmark, centered, white on warm charcoal background) renders cleanly inside Twitter/Instagram circle masks at 80 to 400 pixel display sizes. + +--- + +## Notes for the agent reading this file + +This single-variant spec is one of typically 6 to 12 in a complete deliverable. The brand owner reads through all variants, marks preferences, asks questions, and selects 1 to 3 finalists for production refinement. + +The discipline in writing the spec: + +- Be specific. "IBM Plex Sans Medium with tracking +5" is specific. "Modern sans-serif" is not. +- Show the system. Each variant is a primary mark plus its fallbacks. Document the fallback hierarchy, not just the primary. +- Justify with signals and rejects. What does the variant communicate? What does it explicitly NOT communicate? The negative space in the rejects sharpens the positive selection. +- Render mockups, in image or in prose. The brand owner needs to see the mark in context to evaluate. A spec without mockups is half-finished. +- Prepare for production. The color tokens, embroidery thread color matches, foil stamp specifications, and minimum sizes are production information. The spec is the bridge from decision to manufacture. + +The output of this skill is decision material. The next step after delivery is selection. The step after that is production refinement on the chosen direction: cleaner construction, refined kerning, color system finalization, application library. diff --git a/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md b/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md new file mode 100644 index 0000000..a0a1027 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/symbol-approaches.md @@ -0,0 +1,266 @@ +# Symbol approaches + +A symbol is the part of the logo that does the most work outside of literacy. It travels where wordmarks cannot fit (favicon, embroidery, app icon, signet) and where wordmarks would not register (signage at distance, motion lockups, square contexts). The symbol approach is the question of WHAT KIND of symbol the brand needs. This file expands the five approaches in [SKILL.md](../SKILL.md) with reference brands, pattern vocabulary, decision criteria, and the cliches each approach has to escape. + +--- + +## Literal + +The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. A bicycle for a bicycle maker. A dog silhouette for a dog food brand. The mark and the meaning are tied together: see the mark, name the thing, recall the brand. + +Literal symbols deliver fast recognition and low ambiguity. The audience does not have to learn what the symbol means. They have to learn that THIS specific peak, rocket, leaf, or bird is THIS specific brand. That is a smaller cognitive load than abstract or geometric-reduction approaches require, which is why literal symbols often work for new brands without large marketing budgets. + +The risk is cliche. Every coffee shop has used a coffee bean. Every sustainable brand has used a leaf. Every fitness brand has used a flexed arm. Generic literal symbols disappear into the category background. The save is distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. Patagonia's mountain peaks (the Fitz Roy silhouette) are literal but read as Patagonia because no other outdoor brand uses that specific silhouette in that specific gradient. The execution carries the distinctiveness; the symbol approach is just the starting point. + +### Reference examples + +- Apple's apple (literal but with the bite, which is the distinctive execution) +- Patagonia's Fitz Roy mountain silhouette (literal landscape, specific peak) +- Twitter's bird era (literal bird, specific Larry-the-bird construction) +- Shell's shell (literal scallop shell, custom construction now near-symbol-only) +- Burger King's burger (literal but stylized; the bun, patty, and bun stack render as a unit) + +### Pattern vocabulary + +- Single-object silhouettes (peak, rocket, leaf, bird, fish, tree, building) +- Stylized object reductions (the apple bite, the burger as stacked rectangle, the shell as fan) +- Object-plus-frame compositions (the mountain inside a circle, the tree inside a shield) +- Repeated-object patterns (multiple stylized peaks, paired forms) +- Object combined with letterform (the mountain silhouette that doubles as a letter, see Letterform-derived approach below) + +### Decision criteria + +Literal symbols fit when: +- The brand name is descriptive (Atlas, Forge, Pulse, Anchor) and depicting the thing the name refers to is a natural move +- The category benefits from fast recognition (consumer goods at shelf, retail signage at street scale) +- The brand wants to feel approachable rather than abstract or institutional +- The audience reads symbols faster than they read wordmarks (younger audiences, retail audiences, audiences in low-literacy contexts) + +Literal symbols fail when: +- The brand name is abstract (Stripe, Anthropic, Linear) and forcing a literal symbol creates a metaphor the name does not invite +- The category has been saturated with literal symbols (every wellness brand using a leaf) +- The literal symbol cliches the category (every blockchain logo using a literal chain) +- The brand needs to feel institutional or premium and the literal depiction reads as childlike + +### Common cliches to avoid + +- The leaf-as-natural for any sustainability, wellness, or organic brand. The leaf is exhausted. +- The swoosh-as-growth for any growth-stage brand. Borrowed from Nike but watered down. +- The mountain-as-aspiration for any wellness or productivity brand. The mountain has been climbed. +- The bullseye-as-precision for any analytics or targeting brand. Done. +- The shield-as-security for any security or finance brand. Shields are everywhere. + +The escape is specific execution. A brand that uses a leaf must draw a specific leaf with specific construction (the maple leaf with eight points, drawn at this specific angle, with this specific stroke weight) so the audience reads "this leaf" not "a leaf". + +--- + +## Abstract gesture + +The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity" or "cycle". A spiral for "expansion". The symbol does not show the thing the brand does; it shows the quality the brand wants to be associated with. + +Abstract gesture marks read slower than literal marks but distinctively higher. The audience cannot name the thing in the symbol because there is no specific thing. Instead, the audience associates the symbol with the brand through repetition: see the symbol, recall the brand. Once associated, abstract gesture marks deliver more brand-specific recognition than literal marks because no other brand can use the same specific gesture. + +The risk is arbitrariness. A swoosh that suggests motion is fine. A swoosh that suggests motion AND innovation AND momentum AND speed is over-loaded. Abstract gesture marks work when the gesture is single, clear, and consistent. They fail when the gesture is multi-layered, when the symbol's construction does not visibly support the claimed gesture, or when the gesture is too abstract to register as anything at all. + +### Reference examples + +- Nike's swoosh (abstract gesture for motion, originally inspired by the wing of Nike, the Greek goddess of victory) +- Mastercard's circles (two overlapping circles, abstract gesture for connection or transaction) +- Audi's four rings (abstract gesture for the four merged companies, rendered geometrically) +- Adidas's three stripes (abstract gesture for ascension, originally a sports performance reference) +- The PBS logo (multiple human silhouettes implying community) + +### Pattern vocabulary + +- Arcs and curves (rising arc, descending arc, S-curve, spiral) +- Repeated forms (multiple stripes, multiple circles, multiple bars) +- Opposing forms (two halves meeting, mirrored shapes, yin-yang variants) +- Implied motion (lines that read as flow, shapes that suggest movement) +- Geometric primitives at scale (a single triangle, a single square, a single hexagon used as the gesture) + +### Decision criteria + +Abstract gesture fits when: +- The brand name is abstract and a literal symbol would feel forced +- The brand wants to claim a quality (motion, balance, growth, connection) without depicting it +- The category rewards distinctiveness over fast recognition (B2B, professional services, established mature brands) +- The brand has the recognition runway to teach the audience that this gesture means this brand + +Abstract gesture fails when: +- The brand is new and does not have the recognition to associate the gesture with the brand +- The gesture is borrowed from a saturated visual vocabulary (every fintech using a rising arc) +- The construction does not support the claim (a swoosh that does not actually swoop) +- The gesture is over-complicated and the audience cannot extract a single quality from it + +### Common cliches to avoid + +- The swoosh-as-growth for SaaS, fintech, or productivity brands. Swooshes are saturated. +- The geometric-hexagon-as-blockchain for crypto, web3, or distributed systems. Hexagons are the new dot-com blue. +- The three-bars-as-tech-startup for SaaS or developer tools. Three bars (or two, or four) are the most common geometric reduction in tech and now read as generic. +- The infinity-as-continuous for any "always-on" brand. Infinity loops are exhausted. +- The ascending-arc-as-progress for any analytics, growth, or financial services brand. Ascending arcs are the visual language of every dashboard ever. + +The escape is specific construction. A brand that uses a swoosh must draw a specific swoosh with specific weight, angle, and proportion so the gesture is identifiable as the brand's, not as a category default. + +--- + +## Geometric reduction + +The symbol is a formal abstraction with no specific referent. A hexagon. A triangle. A stack of horizontal lines. A circle bisected by a vertical. A square with a corner removed. The symbol is constructed from primitive geometric shapes with no narrative meaning attached. + +Geometric reduction reads modern and confident. The discipline of pure geometry signals "we made deliberate constructive choices". The risk is identical-to-everyone: thousands of brands use hexagons, triangles, circles, and squares. The reduction is so far from a specific narrative that the audience cannot distinguish one brand's geometric reduction from another's. + +The save is specific proportions, considered execution, and pairing with a distinctive wordmark. Microsoft's four-square mark is geometric reduction (four colored squares in a 2x2 grid) but works because the specific proportions, colors, and four-pane reference are unmistakably Microsoft. Pinterest's "P" inside a circle is geometric reduction but works because the specific letterform, the specific circle proportions, and the cultural recognition are Pinterest. Geometric reduction without distinctiveness in proportions or pairing reads as interchangeable. + +### Reference examples + +- Microsoft's four-square (four colored squares, the geometric reduction works because of color and arrangement) +- Adidas's three stripes (geometric reduction reading) (also abstract gesture, depending on read; the geometric reduction reading is three parallel diagonals) +- Mastercard's two circles (two overlapping geometric primitives) +- Audi's four rings (four overlapping circles) +- Various B2B SaaS marks (Linear's stacked horizontal bars, Slab's geometric construction) + +### Pattern vocabulary + +- Polygons (hexagon, octagon, triangle, square, diamond) +- Primitive intersections (overlapping circles, intersecting squares) +- Linear primitives (stacked bars, parallel lines, grids) +- Single primitives at scale (a single hexagon, a single triangle, a single square as the entire mark) +- Negative-space primitives (a hexagon defined by what surrounds it, a triangle defined by negative space) + +### Decision criteria + +Geometric reduction fits when: +- The brand has a budget for distinctive construction (the proportions and pairing must be specific enough to escape the category default) +- The brand wants to feel modern, technical, infrastructural +- The category rewards reduction over expression (B2B SaaS, infrastructure, fintech, distributed systems) +- The wordmark is distinctive enough that the geometric symbol can be quietly supportive rather than narratively loaded + +Geometric reduction fails when: +- The brand is new and the construction is generic +- The geometric primitive is the most common one in the category (every blockchain logo using a hexagon) +- The reduction is too far from any narrative the brand wants to tell +- The geometric symbol is not paired with a distinctive wordmark and the system reads as interchangeable + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain for any crypto, web3, or distributed systems brand. Hexagons are the most overused geometric primitive in tech. +- The triangle-as-direction for any productivity, navigation, or strategy brand. Triangles point everywhere now. +- The square-as-foundation for any platform or infrastructure brand. Squares are the new shipping container. +- The stacked-three-bars-as-tech-startup for any SaaS brand. The three bars (or four) are the new dot-com gradient. +- The bisected-circle-as-balance for any wellness, productivity, or balance-claiming brand. Done. + +The escape is proportional specificity. A brand that uses a hexagon must use specific proportions (the regular hexagon vs the wide hexagon vs the tall hexagon, drawn at this specific angle, with this specific stroke or fill discipline) and pair it with a specific wordmark so the symbol is identifiable as the brand's specific reduction, not as a category default. + +--- + +## Letterform-derived + +The symbol is built from the name's letterforms. A custom letter, often the first, that doubles as a visual element. The "M" of McDonald's that reads as the golden arches and as a letter. The "b" of Beats inside a circle that reads as both a "b" and a stylized headphone. A custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. The Underscore brand's "_" that IS the symbol. + +Letterform-derived symbols deliver strong wordmark-symbol coherence. The wordmark and the symbol share construction language because they ARE the same construction language. The risk is that the letterform reads as just-a-typed-letter and adds nothing. The save is exaggerated character: the letter must read as both the letter AND the visual metaphor simultaneously. + +The discipline is the silhouette test on the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. The double-reading is what separates letterform-derived from wordmark-only or from literal symbols. + +### Reference examples + +- McDonald's "M" (the golden arches read as a letter and as the architectural arches of the original restaurant signage) +- Beats by Dre's "b" (the lowercase "b" inside a circle reads as a "b" and as a stylized headphone) +- Underscore's "_" (the underscore character IS the brand mark, read as a punctuation mark and as a structural element) +- The Hoover Dam's "H" (architectural lettering on signage that doubles as monumental ornament) + +### Pattern vocabulary + +- First-letter exaggeration (a custom "A", "B", "M", "S" that reads as both letter and shape) +- Letter-inside-frame (a letter inside a circle, square, or shield that reads as identity) +- Punctuation-as-symbol (an underscore, an asterisk, an ampersand used as the entire mark) +- Letter-as-object (a letter drawn so it doubles as a recognizable object: the M as arches, the A as a peak) +- Stacked or overlapping letterforms (one letter rendered on top of another, ligature-style) + +### Decision criteria + +Letterform-derived fits when: +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to share construction +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands + +Letterform-derived fails when: +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it + +### Common cliches to avoid + +- The "letter inside circle" as the universal letterform-derived solution. Beats works because the specific b-shape and the specific circle proportion are distinctive; copies of "letter inside circle" in B2B SaaS read as generic. +- The "letter with an angled corner" as a cheap attempt at distinctiveness. The angled corner does not read as a metaphor; it reads as decoration. +- The "letter with extreme styling" that no longer reads as the letter. If the styling is so heavy that the letterform fails the silhouette test, the metaphor is not earning its place. + +The escape is specific letterform decisions that produce a double reading. The "A as mountain peak" must work both ways. The "M as arches" must work both ways. The double reading is the only thing that justifies the custom drawing investment. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent), AOL. + +Monograms come in three flavors: +- Pure ligature. The letters share strokes; the two letters are drawn as one shape. CN and GG are ligatures. +- Geometrically framed. The letters sit inside a ring, shield, or diamond. HBO, with its rectangular framing. YSL, with its stacked geometric composition. +- Tight kerning, no framing. The letters are simply set together with optical adjustments and read as a unit. VW, with its overlapping V and W. AOL, set tight. + +Monograms signal institutional gravity. The audience reads "we have a long name" and "we own the initials of that name" and "we are old enough that abbreviating is acceptable". For brands wanting heritage, financial competence, hospitality polish, or luxury exclusivity, monograms are often the right architectural choice. + +### Reference examples + +- Chanel's CN (pure ligature, two letters share a counter) +- Gucci's GG (pure ligature, mirrored) +- HBO (geometrically framed inside a rectangle) +- YSL (stacked geometric composition, the three letters set as a tower) +- Volkswagen's VW (tight kerning, overlapping) + +### Pattern vocabulary + +- Ligature pairs (CN, GG, MN, AB, SR with shared counters or strokes) +- Stacked initials (the top letter above the bottom letter, often with a horizontal divider) +- Framed initials (letters inside a ring, shield, diamond, oval) +- Overlapping initials (the V and W of Volkswagen, the H and B of various heritage brands) +- Crowned or filigreed monograms (heritage luxury treatment with ornamental frame elements) + +### Decision criteria + +Monograms fit when: +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +Monograms fail when: +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials + +### Common cliches to avoid + +- The "monogram inside a heavy ring" for any brand wanting heritage. Heavy rings around initials read as fake-heritage logo template; rings work when they are restrained, geometrically specific, and earn their place. +- The "heritage shield with a year" for any brand wanting legacy. Founded-in-1923 shields look like every craft beer label. +- The "ornamental monogram with filigree" for any brand attempting traditional luxury. Heavy ornamentation reads as Renaissance Faire, not as Hermès. +- The "monogram with a serif crown" for any boutique heritage attempt. Crowns are exhausted. + +The escape is restrained execution. A monogram that earns its place uses specific letterform construction, specific kerning, and minimal framing. The discipline is what makes Chanel's CN read as Chanel and not as a costume version of Chanel. + +--- + +## How to choose, in summary + +Match the symbol approach to the brand name and the category positioning. + +- Descriptive names invite literal or letterform-derived symbols. Atlas, Forge, Pulse, Anchor, Falcon, Mountain. The name suggests something to depict. +- Abstract names demand abstract or geometric-reduction symbols. Stripe, Anthropic, Linear, Notion. The name does not point at anything specific, so the symbol cannot either. +- Heritage names default to monograms. A founder's surname, a place name, a multi-word firm. The monogram turns the long name into a positioning statement. +- Tech-modern names often default to geometric reduction. Anthropic's hex grid, OpenAI's flower, the universe of B2B SaaS marks built from primitives. The risk is interchangeability; the save is specific proportions and pairing. + +The wrong approach disconnects symbol from name. A literal peak on Stripe would read as a brand mistake. A geometric reduction on Atlas Coffee would feel cold. The approach is downstream of the name, the category, and the positioning intention. diff --git a/dist/pi/.agents/skills/logo-design/references/typographic-registers.md b/dist/pi/.agents/skills/logo-design/references/typographic-registers.md new file mode 100644 index 0000000..1d22e57 --- /dev/null +++ b/dist/pi/.agents/skills/logo-design/references/typographic-registers.md @@ -0,0 +1,263 @@ +# Typographic registers + +Type carries the wordmark. Type carries half the lockup. Type drives more of a logo's read than any other single decision because type is the voice of the brand, frozen. This file expands the seven registers listed in [SKILL.md](../SKILL.md) with named typefaces, category-fit notes, example brands, pairing guidance, and the failure mode each register tends toward. + +--- + +## Geometric sans + +Built from circles and verticals. Letterforms are constructed from primitive geometric shapes (circle, square, triangle) with consistent stroke weight and minimal optical adjustment. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde, Gotham, Proxima Nova. + +Geometric sans reads modern, considered, often optimistic. The discipline of the geometry signals "we made deliberate choices". Used well, it carries restraint. Used poorly, it reads as cold or interchangeable with every other modern startup. + +Futura was the original (1927, Paul Renner). Avenir is Adrian Frutiger's warmer, more humanist take on the same idea (1988). Avenir Next is the modern release with broader weights and language coverage. Cabinet Grotesk is a recent geometric sans that became a signature of the 2020-2023 startup wave (and now reads dated for that reason). Gotham (Tobias Frere-Jones) is the American-vernacular geometric sans, derived from New York signage; warmer than Futura, more grounded than Avenir. + +### Categories that default to geometric sans + +- Tech startups (the modern default; risk of looking like every other startup) +- Architecture and design firms (where the geometry signals craft) +- Modern hospitality (boutique hotels, restaurant groups built post-2010) +- Wellness and fitness brands at the considered end (not the energetic end) +- Real estate at the modern positioning end (urban, design-forward) + +### Example brands + +- Spotify (custom geometric sans, derived from Circular) +- Airbnb (Cereal, custom geometric sans by Dalton Maag) +- Headspace (Apercu Pro, geometric humanist sans) +- Nike's wordmark (custom Futura-derived) + +### Pairing notes + +Geometric sans pairs well with old-style serifs (the contrast between modern geometry and classical curves reads as intentional) and with slab serifs of similar weight class (both are structurally heavy, the contrast is in the silhouette). Avoid pairing geometric sans with neo-grotesque sans; the two registers are too close in feel and the pairing reads as indecisive. + +### Common pitfalls + +- The trend-chasing risk. Cabinet Grotesk became "2022-2023 startup typeface"; using it now codes the brand as late to a trend. +- The cold-tech risk. Pure geometric sans can feel emotionally distant. Warming requires color, custom letterform, or strong context. +- The interchangeability risk. Geometric sans wordmarks all start to look the same after a category saturates. Distinctiveness comes from custom letterforms or weight/proportion choices, not just typeface selection. + +--- + +## Humanist sans + +Has serif-like calligraphic gestures without serifs. The strokes vary in weight (subtle thick-thin contrast). The letterforms have movement, not just geometry. Gill Sans, Optima, Frutiger, Source Sans Pro, Inter at higher optical sizes, Hermann Zapf's Kabel, Jeremy Tankard's Bliss. + +Humanist sans reads professional but warm. The calligraphic origin gives the type a hand, where geometric sans has none. Excellent neutral choice when the category demands restraint with personality. Old enough to feel timeless; not old enough to feel dated. + +Gill Sans (Eric Gill, 1928) is the original British humanist sans, derived from Edward Johnston's London Underground typeface. Optima (Hermann Zapf, 1958) is the most calligraphic of the humanist sans, with strong thick-thin contrast that reads as sophisticated. Frutiger was designed for Charles de Gaulle airport signage in 1976 and has been the workhorse humanist sans for transit and wayfinding ever since. Source Sans Pro is Adobe's open-source humanist sans (Paul Hunt, 2012); Inter (Rasmus Andersson) crosses humanist and neo-grotesque registers depending on optical size. + +### Categories that default to humanist sans + +- Professional services (consulting, agencies, professional partnerships) +- Education and academic publishing +- Healthcare at the calm end (One Medical, Forward) +- Civic and institutional work (museums, libraries, public services) +- Editorial brands at the modern restrained end + +### Example brands + +- BBC (Gill Sans) +- BMW Group's corporate identity (custom humanist sans, derived from Helvetica with humanist warming) +- One Medical (FF Tisa Sans, humanist with slab adjacency) +- Various university identities (Penn, Stanford, MIT all use humanist or near-humanist marks) + +### Pairing notes + +Humanist sans pairs well with old-style serifs (the calligraphic origins of both registers complement each other) and with transitional serifs (humanist sans for body, transitional serif for display creates a coherent editorial system). Avoid pairing humanist sans with geometric sans; the calligraphic warmth of humanist clashes with the geometric coldness. + +### Common pitfalls + +- The "British civic" risk. Gill Sans is so coded as British civic that using it for a non-British brand can feel anachronistic. +- The dated risk for old humanist sans. Frutiger reads as 1990s transit unless deployed deliberately. Optima reads as 1970s pharmaceutical unless restored to its original sophistication. +- The lukewarm risk. Humanist sans is the safest choice; it can also be the most forgettable. Distinctiveness still requires custom letterform or strong color discipline. + +--- + +## Neo-grotesque sans + +The modern professional default. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America, Univers, Akzidenz-Grotesk. Neo-grotesque is descended from 19th-century grotesque sans typefaces but rationalized for the modern era. Even stroke weight, closed apertures, neutral letterform construction. + +Neo-grotesque reads competent and contemporary. It is the typographic equivalent of a black t-shirt: tasteful, defensible, easy to specify. The trade-off is that everyone else is wearing the same black t-shirt. Without strong color, distinctive symbol, or considered execution, a neo-grotesque wordmark blends into the category default. + +Helvetica (Max Miedinger, 1957) is the prototype. Akzidenz-Grotesk preceded it (1898) but Helvetica became the dominant version. Söhne (Klim Type Foundry, 2019) is the modern revival of the neo-grotesque tradition, with sharper detailing and broader weights. GT America (Grilli Type) crosses American grotesque and Swiss neo-grotesque traditions. Inter (Rasmus Andersson, 2016) is the modern open-source workhorse, designed for screen rendering at every size. + +### Categories that default to neo-grotesque sans + +- B2B SaaS (the unmistakable default; nearly every modern SaaS brand uses Inter, Söhne, or a custom neo-grotesque) +- Modern financial services (Stripe, Mercury, Ramp all use neo-grotesque or near-neo-grotesque) +- Tech at scale (Apple's San Francisco is a neo-grotesque-influenced humanist; Google's Product Sans is neo-grotesque-influenced geometric) +- Modern professional services rejecting the humanist sans default +- Editorial brands at the contemporary end (Bloomberg, modern news brands) + +### Example brands + +- Stripe (custom Sohne Mono and Sohne Schmal) +- Ramp (Söhne) +- Linear (Inter) +- Vercel (Inter, then custom Geist) +- Notion (Söhne) + +### Pairing notes + +Neo-grotesque sans pairs well with serif typefaces of similar weight class (both transitional and old-style serifs work), creating a clean modern-classical contrast for editorial systems. Avoid pairing neo-grotesque with geometric sans or humanist sans; the registers are too close and the pairing reads as indecisive. Custom-drawn neo-grotesque (Söhne, Geist) pairs especially well with stencil display faces, slab serifs, or condensed display sans for brand-system contrast. + +### Common pitfalls + +- The interchangeability risk is highest in this register. Neo-grotesque B2B SaaS wordmarks blur together. The brand that uses neo-grotesque without custom letterforms or strong supporting elements risks becoming visually identical to its category. +- The Helvetica problem. Helvetica is so over-used and so neutral that it now reads as "we did not make a typographic decision". Modern alternatives (Inter, Söhne, GT America) carry similar discipline with more current detailing. +- The screen-versus-print problem. Some neo-grotesque cuts are optimized for screen and look thin at print sizes; others are optimized for print and look chunky at small screen sizes. Pick based on primary application. + +--- + +## Transitional serif + +Modern serifs with high contrast (thick stems, thin transitions, sharp brackets). Source Serif, Charter, Lyon, IBM Plex Serif, Mrs Eaves, Caslon Pro at smaller sizes. Transitional serif sits between old-style serif (low contrast, organic) and modern Didone serif (extreme contrast, geometric). + +Transitional serif reads editorial, considered, intellectual. It carries the long-form heritage of book typography while reading as contemporary. Excellent for legal, publishing, financial, and editorial brands that want serif gravity without the heritage signal of old-style serif. + +Source Serif (Frank Grießhammer, 2014) is Adobe's open-source transitional serif, designed for both print and screen. Charter (Matthew Carter, 1987) is the original screen-optimized transitional serif, designed for low-resolution rendering before high-DPI displays existed; still excellent. Lyon (Kai Bernau, Commercial Type) is the contemporary editorial transitional serif of choice, used by The New York Times Magazine and many editorial brands. IBM Plex Serif (Mike Abbink, IBM, 2017) is IBM's open-source corporate serif, deployed across IBM's global identity. + +### Categories that default to transitional serif + +- Modern legal firms wanting serif gravity without old-fashioned positioning +- Editorial brands and publications (NYT Magazine, The Atlantic in some treatments, Cereal magazine) +- Financial services at the considered end +- Academic publishing (university presses, scholarly journals) +- Modern luxury at the editorial end (not the heritage-luxury end) + +### Example brands + +- The Atlantic (custom transitional serif, derived from Mrs Eaves and Filosofia) +- Vox Media (Lyon) +- Apple's editorial type (custom New York, transitional serif) +- IBM's identity system (Plex Serif) + +### Pairing notes + +Transitional serif pairs well with neo-grotesque sans (the modern-classical contrast is clean and editorial) and with humanist sans (both share calligraphic origins). The classic pairing for editorial is transitional serif for headlines and body, neo-grotesque sans for captions and metadata. Avoid pairing transitional serif with old-style serif; the readers will register the contrast as a mistake rather than an intention unless the deployment is deliberate. + +### Common pitfalls + +- The "magazine logo" trap. Transitional serif is so coded as editorial that using it for non-editorial brands can feel like the brand is trying to wear an editorial costume. +- The screen-rendering problem. Transitional serif's thin strokes can break at small screen sizes if the typeface wasn't optimized for low-DPI rendering. Pick a screen-optimized cut (Charter, Source Serif, Plex Serif) or set the wordmark large enough that the thin strokes survive. +- The "trying too hard" risk. Transitional serif communicates considered restraint; over-styling (italic, weight contrast, custom ligatures) can flip the register to ornate and undermine the restraint signal. + +--- + +## Old-style serif + +Classical serifs with low contrast and warm, organic shapes. Garamond, Caslon, Sabon, Adobe Garamond, Bembo, Janson Text. The letterforms reference 16th-18th century book typography. Diagonal stress, bracketed serifs, gentle thick-thin variation. + +Old-style serif reads heritage, traditional, institutional. It carries weight that newer registers cannot. Used in legal firms whose history runs to a partner's name from 1923, in academic institutions that predate the country, in luxury brands whose claim is centuries-long craft. Used poorly, it reads as a fake heritage costume. + +Garamond (Claude Garamond, mid-1500s) is the prototype; Adobe Garamond (Robert Slimbach, 1989) is the most-deployed modern revival. Caslon (William Caslon, 1722) is the British equivalent, long called "the safe choice for legal documents". Sabon (Jan Tschichold, 1967) is a modernized Garamond designed for industrial typesetting. Bembo (Stanley Morison's revival of Aldus Manutius's 1495 type) is the Italian Renaissance reference. All four predate every other typeface in this file by centuries. + +### Categories that default to old-style serif + +- Legal firms with heritage positioning (white-shoe firms, partnerships founded before 1950) +- Academic institutions (universities, presses, scholarly journals) +- Heritage luxury brands (centuries-old jewelers, watchmakers, fashion houses) +- Editorial brands with literary positioning (literary magazines, book publishers) +- Whiskey, wine, and other categories where "we have been doing this for generations" is the marketing claim + +### Example brands + +- The Economist (custom Caslon-derived display) +- The New Yorker (custom Caslon-derived masthead and ITC New Baskerville for body) +- Most university press identities (Yale, Oxford, Princeton) +- Most heritage law firm identities (Wachtell, Cravath, Latham use serifs derived from this register) + +### Pairing notes + +Old-style serif pairs well with humanist sans (both share calligraphic origins) and with neo-grotesque sans for editorial systems wanting modern-classical contrast. Avoid pairing old-style serif with geometric sans; the registers fight each other (geometric coldness vs old-style warmth). Avoid pairing old-style serif with transitional serif; the contrast is too subtle to register as intentional. + +### Common pitfalls + +- The dated risk. Old-style serif used without deliberate restraint reads as old-fashioned, which can be the goal (heritage) or the failure (trying to look serious by using old-looking type). +- The thin-stroke screen problem. Old-style serif's hairline serifs and thin strokes can disappear at small screen sizes. Either pick a screen-optimized old-style cut (Adobe Garamond Pro, EB Garamond) or accept that the wordmark must be set large. +- The fake-heritage risk. Using Garamond on a brand founded last year reads as costume, not heritage. The audience is not fooled by typography alone; the rest of the brand system has to carry the heritage claim. + +--- + +## Slab serif + +Heavy structural serifs with strong thick-thin uniformity. The serifs are blocky, rectangular, often nearly equal in weight to the stems. Sentinel, Adelle, Roboto Slab, Tisa, Rockwell, Archer, Vitesse. The visual register is strong, declarative, sometimes journalistic. + +Slab serif reads strong, structural, declarative. It carries authority without the heritage baggage of old-style serif. Common in editorial work, sports brands, journalistic identities, and brands that want serif weight without the ornament of transitional or old-style serifs. + +Sentinel (Hoefler & Frere-Jones, 2009) is the modern editorial slab. Adelle (TypeTogether, 2009) is the screen-optimized slab serif of choice for digital editorial. Roboto Slab is Google's open-source slab. Rockwell (Frank Hinman Pierpont, 1934) is the British slab serif of railway and industrial heritage. Tisa (Mitja Miklavčič) is the modern slab with humanist warming, used in editorial systems. + +### Categories that default to slab serif + +- Editorial and publishing (when the brand wants more weight than transitional serif provides) +- Sports brands (the typographic equivalent of athletic gravity) +- Journalistic identities (some newspapers, news magazines) +- Industrial and engineering brands (the structural quality reads as "we make real things") +- Outdoor and adventure brands (Filson, Patagonia in some treatments, REI's wordmark) + +### Example brands + +- Mailchimp's wordmark (custom slab-derived script) +- The Wall Street Journal (in older treatments) +- Various sports league identities (NFL teams, college athletics) +- Filson's wordmark (custom slab serif) + +### Pairing notes + +Slab serif pairs well with neo-grotesque sans (the structural similarity reads as one design language at different ornament levels) and with geometric sans (both are constructed registers). Avoid pairing slab serif with old-style serif; the contrast between structural and organic serifs reads as system inconsistency. + +### Common pitfalls + +- The "newspaper from 1985" risk. Some slab serifs read as 1980s editorial unless paired with current typographic systems. +- The clunky risk. Slab serifs' structural weight can feel heavy at large sizes; the wordmark needs to be sized carefully so the slabs do not overpower the letterforms. +- The genre-trapping risk. Slab serifs are so coded for sports, journalism, or industrial that using them outside those categories can feel like the brand is borrowing the register's gravity rather than earning its own. + +--- + +## Display custom + +Custom-drawn or heavily-modified typeface designed specifically for the brand. Reads distinctive but expensive in time and budget. The wordmark uses letterforms that exist nowhere else. + +Custom display is the highest distinctiveness tier. Stripe's wordmark, Google's Product Sans, Pinterest's custom geometric, Spotify's Circular variant, Airbnb's Cereal. Each is a custom typeface drawn to solve a specific problem in the brand's wordmark or identity system. + +The justification is when the brand needs a wordmark no one else has and the budget supports drawing one. Custom display is rarely justified for new brands without significant marketing investment because the brand has not yet earned the recognition that makes the custom letterforms register as distinctive. For mature brands, custom display is the ceiling of typographic discipline. + +### Categories where custom display fits + +- Mature brands at scale where custom letterforms become a competitive moat +- Tech-led brands with budget for type design partnerships +- Heritage luxury brands whose wordmark must be unique (not Garamond plus a name) +- Editorial brands with recognizable masthead type (The New York Times, The New Yorker) +- Sports leagues and major sports brands + +### Example brands + +- Stripe (custom Sohne, then Söhne plus custom optical adjustments on the wordmark) +- Google (Product Sans, custom geometric) +- Spotify (Circular variant, then custom Spotify Mix) +- Airbnb (Cereal, custom geometric humanist by Dalton Maag) +- Pinterest (custom geometric for the wordmark) + +### Pairing notes + +Custom display is rarely paired in lockup; the custom typeface IS the wordmark. The pairing decision is which body and metadata typefaces support the custom display in larger system applications. The body typeface is typically chosen for legibility at small sizes (a screen-optimized neo-grotesque or humanist sans) rather than for visual harmony with the custom display. + +### Common pitfalls + +- The cost risk. Custom letterform drawing is expensive (5-figure to 6-figure engagements depending on scope). The investment must match the brand's recognition trajectory. +- The over-customization risk. Custom letterforms should solve specific problems, not announce themselves. The custom "g" that reads as cleverly drawn rather than as just-the-letter-g signals committee work. +- The aging risk. Custom display typefaces age with the era they were drawn in. The Spotify wordmark from the 2010s reads as 2010s; the brand has had to update the system multiple times. Plan for redrawing every 5-10 years. + +--- + +## How to choose, in summary + +The choice flows from category default and positioning intention. + +- In-category choice signals competence. Legal in old-style serif, SaaS in neo-grotesque sans, sports in slab serif. The audience reads "this brand understands the category". +- Out-of-category choice signals positioning. Legal in geometric sans signals "we are modern". SaaS in old-style serif signals "we take the work seriously". Outdoor in geometric sans signals "we are not your grandfather's outdoor brand". The shift is intentional and the rest of the brand system has to support it. +- Custom display is reserved for mature brands with recognition that earns the investment. +- Pairing logic combines the wordmark register with body and metadata registers to build the system. The pairing should read as one design intention, not as two competing ones. + +The wrong typographic register is not always obvious in isolation. It becomes obvious in deployment: the wordmark on the business card, the lockup at retail, the favicon at 16px. Test the chosen register against the brand's actual application contexts before committing. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md b/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md new file mode 100644 index 0000000..b80133a --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/SKILL.md @@ -0,0 +1,311 @@ +--- +name: long-form-content-frameworks +description: "Patterns for individual long-form content pieces. Case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials. The structural disciplines that distinguish publication-quality long-form from bloggy-long padding or academic bloat. Different from pillar-content-architecture (which covers hub structure); this skill covers individual deep-dive pieces. Triggers on long-form content, case study writing, whitepaper, research report, definitive guide, ebook, manifesto, long-form tutorial, deep-dive article, anchor piece, foundational article, structural archetypes. Also triggers when a piece is over 3,000 words and the team is unsure how to structure it, when a long-form draft feels padded or saggy, or when a flagship asset needs the depth to actually earn the length." +category: content +catalog_summary: "Structural patterns for individual long-form pieces (case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials) that distinguish publication-quality work from bloggy-long padding or academic bloat" +display_order: 9 +--- + +# Long-Form Content Frameworks + +A senior editorial leader's playbook for individual long-form content pieces. The structural disciplines that distinguish publication-quality work from bloggy-long padding or academic bloat. + +Long-form is where most content programs lose their nerve or lose their way. Teams either stretch a 1,500-word post to 5,000 with filler (the bloggy-long failure mode), or they over-document the topic with no editorial spine (the academic-bloat failure mode). The pieces that earn their length are the ones where each section justifies its weight, the lede sets a thesis the body actually delivers, and the closing leaves the reader with something specific. + +This skill covers the individual long-form piece: the case study, the whitepaper, the research report, the manifesto, the ebook chapter or full ebook, the definitive guide, the long-form tutorial. Different from `pillar-content-architecture` (which covers HUB architecture: how a pillar plus cluster system fits together), this skill covers the long-form PIECE itself, regardless of whether it sits at the center of a hub or stands alone. + +The voice is the senior editorial leader who has shipped dozens of flagship long-form assets and watched plenty of others fail. Honest about which formats earn their length, which structural archetypes fit which problems, and where long-form most often goes wrong. + +When to use this skill: planning a flagship long-form piece, structuring a draft that feels saggy, reviewing a long-form piece that is technically correct but emotionally flat, or auditing a content library to find the long-form pieces that should have been blog posts. + +--- + +## What this skill is for + +This skill spans individual long-form content pieces. The content suite distinction: + +- `content-strategy` is program scope: what to produce across the program. +- `pillar-content-architecture` is HUB scope: pillar plus cluster as a topical hub system. +- `long-form-content-frameworks` (this skill) is PIECE scope for long-form: individual deep-dive pieces, standalone or as pillars. +- `content-and-copy` is execution scope at any length: writing the words. +- `content-brief-authoring` is per-piece brief scope at any length: the contract. +- `editorial-qa` is gate scope: pre-publish verification. +- `ai-content-collaboration` is workflow scope: how humans and AI compose. + +A pillar page IS often a long-form piece. The two skills compose: pillar-content-architecture decides the hub shape and which pieces sit where; this skill is how you structure the long-form pieces themselves so they earn the length they take up. + +The audience: editorial leads, content directors, in-house teams shipping flagship long-form, agencies producing whitepapers and research reports, anyone planning a piece that will run 3,000+ words and need to hold a reader to the end. + +What is not in scope: blog-post-length writing (covered by `content-and-copy`), the brief itself (covered by `content-brief-authoring`), the hub architecture around a long-form piece (covered by `pillar-content-architecture`), or the pre-publish QA pass (covered by `editorial-qa`). + +--- + +## Bloggy-long vs academic-bloat vs publication-quality + +The keystone framing. Two failure modes plus the discipline. + +Bloggy-long. A regular blog post stretched to 5,000 words via padding. Same structural shape as 1,500 words, just inflated: more transitional paragraphs, more "before we get into it," more recap sections, more bullet expansions of single ideas. The reader notices within 600 words and skims. Output: a piece that ranked because it was long, never gets read all the way through, never gets shared, never earns links because nobody finished it. + +Academic-bloat. Exhaustive coverage that loses the thread. 8,000 words where 4,500 would have served. Every adjacent topic surveyed; every definition restated; every caveat documented. Reader respects the effort and skims for the parts they need. Output: a "comprehensive" piece that nobody reads end-to-end, that does not change anyone's mind, that performs in search but underperforms in trust. + +Publication-quality. Structural depth that earns the length. Each section justifies its weight. The lede establishes a thesis the body delivers. The closing is specific. Reading flow varies in density, register, and rhythm so the piece sustains attention. The piece reads as the work of someone who had something specific to say and the discipline to say it well at length. + +The litmus test. Ask of any long-form draft: would cutting this section weaken the argument, or would it just make the piece shorter? If cutting strengthens it, the section was filler. The piece earns its length when each section is doing structural work the argument requires. + +--- + +## Long-form formats and when each fits + +Seven formats, each with a different structural shape and a different reader contract. + +Case study. A specific company, project, or initiative with quantified outcomes. Reader contract: "Show me what worked and why, with specifics." Length: 2,000 to 4,000 words typical. Structural archetype: usually problem-solution. The case-study tax: real numbers, real names, real specificity. Generic case studies signal nothing. + +Whitepaper. A position document on a substantive topic, typically with original analysis. Reader contract: "Take me through your reasoning on this question with the rigor I would expect from a serious source." Length: 3,000 to 8,000 words. Structural archetype: layered argument or comparative analysis. Often gated. The whitepaper tax: original synthesis, not survey of existing literature. + +Research report. Original primary research presented with methodology, findings, implications. Reader contract: "Show me the data, how you collected it, what it means." Length: 4,000 to 12,000 words. Structural archetype: taxonomic survey or comparative analysis. The research-report tax: actual primary research, not "we surveyed 300 marketers" with leading questions. + +Definitive guide. Comprehensive coverage of a topic for a specified audience. Reader contract: "Be the canonical resource on this." Length: 4,000 to 10,000 words. Structural archetype: taxonomic survey. The definitive-guide tax: actual comprehensiveness; gaps reveal that the guide is not actually definitive. + +Manifesto. A position paper on what the writer believes and why, often confrontational. Reader contract: "Tell me what you think and convince me." Length: 1,500 to 6,000 words. Structural archetype: layered argument or narrative arc. The manifesto tax: actual conviction, not diplomatic hedging. + +Ebook. Multi-chapter long-form, often a sequence of related pieces with introduction and conclusion. Reader contract: "Take me through a body of work." Length: 8,000 to 30,000+ words. Structural archetype: usually narrative arc across chapters. The ebook tax: each chapter earns its place; the table of contents is not padding. + +Long-form tutorial. Instructional content where the reader is following along. Reader contract: "Take me from where I am to where I want to be, step by step." Length: 3,000 to 8,000 words. Structural archetype: problem-solution with sequential steps. The long-form-tutorial tax: every step actually works; gaps in the sequence break the reader. + +Detail in [`references/format-decision-framework.md`](references/format-decision-framework.md). + +--- + +## Structural archetypes + +Five archetypes that fit different long-form problems. + +Problem-solution. State the problem with weight; develop why it matters; present the solution; show how it works; address objections. Fits case studies, long-form tutorials, manifestos with a clear opposition. Risk: feels formulaic if every piece uses it. + +Narrative arc. Beginning, middle, end. A protagonist (often the company, sometimes a person, sometimes the reader) faces a complication and resolves it. Fits ebooks, some case studies, longer manifestos. Risk: forced narrative on topics that are not actually stories. + +Layered argument. Position stated; layer 1 evidence; layer 2 evidence; counter-arguments addressed; synthesis. Fits whitepapers, manifestos, position pieces. Risk: feels academic if the layers do not build to a real synthesis. + +Taxonomic survey. A topic mapped into categories; each category explored; relationships among categories surfaced. Fits definitive guides, research reports surveying a landscape. Risk: feels like a list with subheads if the taxonomy is not actually load-bearing. + +Comparative analysis. Multiple options, frameworks, or positions compared along defined axes; tradeoffs surfaced; the writer's recommendation argued. Fits whitepapers, decision-guide research reports, technology comparisons. Risk: feels like a feature matrix if the analysis is shallow. + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. A whitepaper might be a layered argument with comparative-analysis sections. A definitive guide might be a taxonomic survey with problem-solution chapters. The archetype is the spine; variation prevents the piece feeling formulaic. + +Detail in [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md). + +--- + +## Section weight calibration + +How long sections should be relative to each other, varying by format. + +The general principle: section weights match how much load the section is bearing in the argument. Throat-clearing introductions get cut. Setup sections are short. Argument-bearing middle sections are longest. Closings are specific and tight. + +Whitepaper / research report typical weights. Introduction 8-12% (thesis stated, scope set). Methodology or framing 10-15% (how the analysis works). Body 60-70% (the actual argument or findings, divided into 3-5 weighted sections). Implications 10-15%. Closing 3-5%. + +Case study typical weights. Setup and context 15-20% (the company, the problem, why it mattered). Solution narrative 50-60% (what was done, in sequence). Outcomes 15-20% (quantified results, what worked, what did not). Reflection 5-10% (what the team would change). + +Manifesto typical weights. Position 5-10% (what is believed, stated early and clearly). Argument 70-80% (why, with the layers building intensity). Call 10-15% (what should change as a result). + +Definitive guide typical weights. Introduction 5-8% (what the guide covers, who it serves). Body across taxonomic sections 80-85% (each section roughly even). Closing and additional resources 7-10%. + +Long-form tutorial typical weights. Setup 10-15% (what the reader will achieve, what they need). Sequential steps 70-80% (each step its own subsection). Troubleshooting and edge cases 10-15%. + +The audit. If one section is more than 3x the length of another bearing similar argumentative load, the piece is structurally unbalanced. Either the long section needs to be split, or the short section needs to be deepened, or the imbalance reflects an actual content problem the writer has not surfaced. + +Detail in [`references/section-weight-calibration.md`](references/section-weight-calibration.md). + +--- + +## Lede patterns for long-form + +Long-form ledes do different work than blog-post ledes. + +A blog-post lede answers the user's likely query in the first 200 words. A long-form lede establishes a thesis the next 5,000 words will deliver, sets the reader's expectations for the piece's depth, and earns the reader's attention for the time investment ahead. + +Patterns that work. + +- The contested-claim opener. A surprising or contested position stated cleanly, then the rest of the piece argues for it. Fits manifestos, opinionated whitepapers. +- The problem-with-stakes opener. A problem stated with the stakes made tangible. Fits case studies, problem-solution pieces. +- The data-anomaly opener. A piece of data that does not fit the consensus, framed as the question the piece will answer. Fits research reports, analytical whitepapers. +- The scene opener. A specific moment, person, or scene that grounds the abstract topic. Fits narrative-arc pieces, magazine-style longform. +- The orientation opener. What this piece covers, who it is for, what reading it costs and pays. Fits definitive guides and tutorials where the reader's first question is "is this the right resource for me." + +Patterns that fail. + +- The throat-clear opener ("Content marketing has changed dramatically over the past decade. In this article, we will explore...") signals filler ahead. +- The dictionary-definition opener ("According to Merriam-Webster, X is defined as...") signals an unwillingness to commit a position. +- The history-of-the-topic opener (paragraphs of background before the argument starts) loses readers before the thesis lands. +- The "in this article we will discuss" tour opener flattens the piece into an outline before the writer has earned attention. + +The first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. Spending it on filler is the most common long-form failure. + +Detail in [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md). + +--- + +## Sustaining attention across 5,000+ words + +Long pieces that hold readers vary their density, register, and rhythm. Pieces that lose readers feel uniform: same paragraph length, same sentence rhythm, same density of claim, page after page. + +Density variation. Some sections argue tightly (claim, evidence, claim, evidence). Others reflect, illustrate, or breathe. The argument-tight sections earn the breathing sections; the breathing sections give readers room to absorb. + +Register variation. Most long-form pieces sustain a primary register (analytical, narrative, instructional) while occasionally shifting to a secondary register (anecdotal, reflective, declarative) for variation. A whitepaper that is purely analytical for 6,000 words exhausts the reader; a whitepaper with a mid-piece anecdote or a closing reflection lands harder. + +Rhythm variation. Sentence length variation matters more in long-form than short. Strings of 25-word sentences blur; strings of 8-word sentences fragment. The pattern that holds attention: medium sentences with occasional short punches and occasional layered longer constructions. + +Visual rhythm. Subheads, pull quotes, callouts, charts, illustrations break the page into navigable units. Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. The rhythm: visual element every 600-1,000 words on average, varied in type. + +Mid-piece micro-thesis. Around the 40-60% mark, restate the central claim with new framing. Long-form readers' attention naturally dips mid-piece; the mid-piece restatement reorients them and refreshes engagement. + +Detail in [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md). + +--- + +## Citations and source authority + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. + +Source hierarchy for long-form. + +- Primary research: original studies, datasets, interviews, the writer's own data work. Highest authority. +- Authoritative secondary sources: peer-reviewed papers, government data, established research firms, primary reporting from credible outlets. +- Industry-credible sources: vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners. +- Linked-aware secondary sources: reputable blogs and publications where the source is verifying claims, not just amplifying them. +- Avoid: citation laundering through other content marketing pieces, "studies show" claims with no link, anonymous "experts," reposts of reposts. + +Citation density. Long-form arguments need citations roughly proportional to claim density. A piece making 30 falsifiable claims needs 30 citations; a piece making 5 strong claims with extensive elaboration may need 5. The audit: every falsifiable claim is either cited or attributed to the writer's own analysis. + +Source freshness. Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. The "85% of marketers" stat from 2018 in a 2026 piece signals stale research. + +Inline vs endnote citations. Long-form on the web typically uses inline links to authoritative sources. For research-heavy pieces, endnote-style citations (numbered footnotes) signal academic rigor; for editorial whitepapers, inline links keep momentum. Either works; pick one and stay consistent within the piece. + +Detail in [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md). + +--- + +## Visualization and breakouts + +Long-form earns visual breakouts; blog posts often do not. The discipline is which breakouts earn their place. + +Visual element types. + +- Charts and graphs: data visualization that the prose alone cannot convey efficiently. +- Diagrams: relationships, flows, architectures, taxonomies that benefit from visual structure. +- Pull quotes: moments where a single sentence deserves visual weight. +- Sidebars: tangential but valuable context that does not fit the main thread. +- Tables: comparison data, structured reference material. +- Inline callouts: definitions, warnings, "if you only read one section" pointers. + +Earned-position rule. Each visual element earns its place by carrying argumentative load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. + +Production tax. Each visual element costs design time, accessibility work (alt text, screen-reader-friendly tables), and revision overhead when the underlying content changes. Long-form pieces with 25 charts each take meaningful production time to maintain. Plan visual count against production capacity, not against ideal-world maximalism. + +Anti-pattern: the stock-image header. Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. Either commission specific visual work (custom illustrations, branded data visualizations, scene photography) or skip the hero image. + +Detail in [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md). + +--- + +## Closing patterns + +Long-form pieces with strong closings get shared, get linked, and get remembered. Pieces with throat-clearing closings disappear after the last subhead. + +Closings that work. + +- The specific call. What should the reader do, decide, or change as a result of reading this. Concrete, not generic. +- The reframed thesis. The opening claim restated with the weight the body has now earned, often inverted or sharpened. +- The open question. The question this piece's findings raise but do not answer, framed as the next investigation. +- The personal reflection. The writer's stake in the topic surfaced briefly. Fits manifestos, opinionated long-form. +- The provocation. A challenge to the reader, the field, or the consensus. Fits manifestos. + +Closings that fail. + +- The recap closing ("In this piece we covered X, Y, Z") signals the writer ran out of energy. +- The "more research is needed" closing on every research report signals the writer did not commit a position. +- The throat-clear closing ("As we have seen, content is important and only getting more so") delivers no payload. +- The CTA-as-closing ("Book a demo") on a long-form piece breaks the editorial contract; if a CTA belongs, it sits below the closing, not as the closing. + +The audit. Ask of any long-form closing: does this leave the reader with something specific to do, decide, or think about, or does it just signal the piece is ending? If the latter, rewrite. + +Detail in [`references/closing-patterns.md`](references/closing-patterns.md). + +--- + +## Distribution implications for long-form + +Long-form's distribution shape differs from blog-post distribution. The format choices echo through how the piece reaches readers. + +Gated vs ungated. Whitepapers and research reports often gate behind a form to capture leads; ebooks frequently do; case studies sometimes do. The tradeoff: gating cuts reach by 70-90%; the gated audience is qualified but small. Manifestos and definitive guides typically stay ungated to maximize reach and link equity. The decision turns on whether the piece's primary value is reach (ungated) or qualified-lead capture (gated). + +Format choices. Long-form web page (HTML), downloadable PDF, mixed (web with PDF download option), interactive (web with embedded tools or visualizations). Web pages earn search traffic; PDFs earn email-shareable assets; mixed maximizes both. The production cost rises with format count. + +Syndication and excerpting. Long-form pieces lend themselves to chapter excerpts, summary blog posts, and email-newsletter serializations. Plan the excerpting at piece-design time so the chapters or sections are excerpt-ready. See `content-repurposing` for the cross-format adaptation discipline. + +Refresh schedule. Long-form pieces with research components need annual or quarterly refresh on the data; long-form pieces with timeless framings need lighter touch. See `content-refresh-system` for refresh prioritization. + +The decision sequence: format first, distribution shape second. A research report's distribution shape (often gated, often PDF, often paired with a webinar) follows from the format choice; trying to retrofit distribution onto a piece that was written for the wrong shape produces friction. + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-long-form-failures.md`](references/common-long-form-failures.md). + +- "We wrote 5,000 words and traffic is flat." Bloggy-long: stretched to length, no structural depth. Cut to 1,800 words or rewrite as publication-quality. +- "Our whitepaper looked authoritative but nobody finished it." Academic-bloat: comprehensive but not load-bearing. Cut sections that did not move the argument. +- "The lede took 800 words to get to the thesis." Throat-clearing opener; rewrite to land the position in the first 150-250 words. +- "Each section is the same length and rhythm." No section weight calibration; sections all bearing the same argumentative load suggests an undifferentiated piece. +- "The piece sags around the 60% mark." Standard mid-piece attention dip; add a mid-piece micro-thesis and rhythm variation. +- "The closing repeated the introduction." Recap closing; rewrite to a specific call, reframed thesis, or open question. +- "Citations are mostly other blog posts." Citation laundering; replace with primary or authoritative secondary sources. +- "We commissioned 12 charts, the team is exhausted, traffic is the same." Visual count exceeded production capacity and earned-position discipline; cut to charts that bear argumentative load. +- "The case study has no specifics." Generic case-study failure; the case-study tax is real numbers, real names, real specificity. Without those, the format does not work. +- "Our manifesto reads as diplomatic." Manifesto failure: the format demands conviction; if the writer cannot commit, write a different format. +- "The definitive guide has obvious gaps." Definitive-guide failure: the format requires actual comprehensiveness. Either fill the gaps or rename the piece. + +--- + +## The framework: 12 considerations for long-form content + +When planning or auditing a long-form piece, walk these 12 considerations. + +1. Format fits the work. Case study, whitepaper, research report, definitive guide, manifesto, ebook, or long-form tutorial. Format chosen for reader contract, not arbitrary length. +2. Structural archetype selected. Problem-solution, narrative arc, layered argument, taxonomic survey, or comparative analysis as the spine. +3. Lede earns the next 30 minutes. Thesis stated, stakes set, position committed within the first 150-250 words. +4. Section weights calibrated to argumentative load. No section 3x another bearing similar load; throat-clearing sections cut. +5. Density variation. Argument-tight sections balanced with reflective or illustrative sections. +6. Register variation. Primary register sustained with secondary-register moments for variation. +7. Rhythm variation. Sentence and paragraph length varies; visual breakouts every 600-1,000 words. +8. Mid-piece micro-thesis. Central claim restated around the 40-60% mark. +9. Citations match claim density. Falsifiable claims cited; primary or authoritative sources preferred; sources fresh. +10. Visual elements earn position. Each chart, diagram, sidebar carries load the prose alone cannot. +11. Closing is specific. Specific call, reframed thesis, open question, or provocation. Not recap. +12. Distribution shape matches format choice. Gating, format mix, syndication plan, refresh schedule planned at piece-design time. + +The output of the framework is a long-form piece that earns its length: every section justified, every page sustaining attention, every claim verifiable, every closing specific. + +--- + +## Reference files + +- [`references/format-decision-framework.md`](references/format-decision-framework.md) - When each long-form format fits. Reader contracts, length norms, structural archetype tendencies, format-specific taxes. +- [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md) - Five archetypes (problem-solution, narrative arc, layered argument, taxonomic survey, comparative analysis) with worked examples and combination patterns. +- [`references/section-weight-calibration.md`](references/section-weight-calibration.md) - Typical weight ratios by format. Whitepaper, case study, manifesto, definitive guide, long-form tutorial profiles. The 3x audit. +- [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md) - Five patterns that work, four that fail. The first-paragraph sales-pitch frame. +- [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md) - Density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis discipline. +- [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md) - Source hierarchy, citation density, freshness, inline vs endnote conventions, citation-laundering anti-pattern. +- [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md) - Visual element types, earned-position rule, production-tax discipline, the stock-image-header anti-pattern. +- [`references/closing-patterns.md`](references/closing-patterns.md) - Five closings that work, four that fail. The specific-call, reframed-thesis, open-question, personal-reflection, provocation patterns. +- [`references/common-long-form-failures.md`](references/common-long-form-failures.md) - 11+ failure patterns with diagnoses, including bloggy-long, academic-bloat, throat-clearing leads, visual-count overruns, citation laundering, format-tax failures. + +--- + +## Closing: long-form earns its length or it does not + +Length is not a virtue. A 5,000-word piece is only worth more than a 1,500-word piece if those extra 3,500 words carry structural and argumentative load the shorter version could not. Most long-form content underperforms because the team chose length first and structural depth second. + +The discipline is the inversion. Decide what the piece needs to deliver, choose the format and archetype that fit, calibrate sections to actual argumentative load, and let the length follow. Pieces written that way earn their length and read as the work of someone who had something to say. Pieces written length-first read as filler, no matter how many subheads dress them up. + +When in doubt about whether a long-form piece is ready, ask: does each section justify its weight, does the lede earn the next 30 minutes, does the closing leave the reader with something specific, are claims cited, do visuals carry load, does the mid-piece micro-thesis refresh attention? If yes to all of those, the piece is publication-quality. If no to any, the gap is where the reader stops reading. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md new file mode 100644 index 0000000..90a251c --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md @@ -0,0 +1,129 @@ +# Attention-sustaining techniques + +How long-form pieces hold readers across 5,000+ words. The patterns that keep reader attention across the time investment, and the underlying observation: readers leave because pieces feel uniform. + +The pieces that lose readers in long-form are the ones that feel monotone. Same paragraph length, same sentence rhythm, same density of claim, page after page. Even competent writing reads as exhausting under that pattern. The pieces that hold readers vary their density, register, and rhythm so the reader's attention has somewhere to recover and somewhere to engage. + +--- + +## Density variation + +Long-form pieces should alternate between argument-tight sections and breathing sections. + +Argument-tight sections. Claim, evidence, claim, evidence. Specific, direct, intellectually demanding. The reader is doing work to follow the argument. + +Breathing sections. Reflection, illustration, anecdote, restatement. Lower density of new claims; higher density of integration with what was just argued. + +The pattern that holds. After an argument-tight section, a breathing section gives the reader room to absorb. After a breathing section, the reader returns to argument-tight work refreshed. Pieces that are argument-tight throughout exhaust readers; pieces that breathe throughout never feel substantive. + +The audit. For each section, characterize it as argument-tight or breathing. If the sequence is all argument-tight, the piece is dense and exhausting. If the sequence is all breathing, the piece is shallow despite its length. The mix is the discipline. + +--- + +## Register variation + +Most long-form pieces sustain a primary register while shifting briefly to secondary registers for variation. + +Primary registers. + +- Analytical: claim-evidence-implication, measured tone, distance from the topic. +- Narrative: scene-driven, character-driven, time-progressive. +- Instructional: do-this-then-this, addressed to the reader directly. +- Declarative: positions stated, opinions committed, weight on conviction. + +Secondary registers. Anecdotal moments inside an analytical piece. Reflective moments inside an instructional piece. A specific scene inside a declarative manifesto. A measured analytical section inside a narrative. + +The pattern that holds. A whitepaper sustained in analytical register for 6,000 words exhausts readers; the same whitepaper with a mid-piece anecdote and a closing reflection lands harder. A long-form tutorial sustained in instructional register for 5,000 words feels mechanical; the same tutorial with a brief reflective section on common failures and a personal note from the writer feels human. + +The discipline. Choose the primary register first; insert secondary-register moments at section transitions where the shift will refresh attention rather than disorient. + +--- + +## Rhythm variation + +Sentence and paragraph length variation matters more in long-form than in short. + +Sentence length. + +- Strings of 25-word sentences blur. The reader's eye glides over the text without the cognitive checkpoints short sentences create. +- Strings of 8-word sentences fragment. The text reads as choppy, and the reader's attention is interrupted constantly. +- The pattern that holds: medium sentences with occasional short punches and occasional layered longer constructions. + +Paragraph length. + +- Long paragraphs (8+ sentences) feel academic. Suitable for argument-tight sections; exhausting if sustained. +- Short paragraphs (1-2 sentences) feel staccato. Suitable for emphasis and for breaking dense passages; fragmenting if sustained. +- The pattern that holds: most paragraphs 3-5 sentences with occasional shorter ones for emphasis and occasional longer ones for layered argument. + +Heading rhythm. H2 every 600-1,200 words on average. H3 within H2 sections to break navigation. Headings that come at uniform intervals feel mechanical; headings that follow the actual structural breaks feel natural. + +The audit. Read the piece aloud. Does the rhythm vary, or does every sentence and paragraph land with the same beat? If the latter, the piece needs rhythm work even if every individual sentence is competent. + +--- + +## Visual rhythm + +Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. + +The norm. A visual element every 600-1,000 words on average. Visual elements include subheads, pull quotes, callouts, charts, diagrams, sidebars, tables, and images. + +Variation in type. All-subheads-no-charts feels under-designed for the piece's length. All-charts-no-pull-quotes feels like a research dump. The visual rhythm should vary: a subhead, then 800 words of prose, then a chart, then 600 words of prose, then a pull quote, then 700 words of prose, then a callout, then 900 words and the next subhead. + +The earned-position rule. Each visual element earns its place by carrying load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. See `breakouts-and-visualization.md` for the discipline. + +Mobile reading reality. Long-form on mobile gets read in landscape stretches. Subheads should be visible without scrolling on each major section transition; pull quotes should be visible early to preview the piece's depth; charts should be readable without horizontal scrolling. + +--- + +## Mid-piece micro-thesis + +Long-form readers' attention naturally dips around the 40-60% mark. Pieces that survive the dip have a structural move that refreshes engagement at that point. + +The micro-thesis pattern. Around the midpoint, restate the central claim with new framing. The restatement does three things at once: it reorients readers who have been following sections, it gives drifting readers a checkpoint to re-engage, and it sets up the second half of the piece. + +Worked example. A whitepaper opens with the claim "Most teams treating content marketing as a volume problem will continue to underperform." At the midpoint, after the structural argument and the first empirical layer, the writer restates: "The pattern across the data is consistent. The teams that broke the volume-first cycle did not produce more; they produced less, and committed harder to what they produced." The reader is reoriented; the second half of the piece can build on the restatement. + +Anti-pattern: the recap micro-thesis. Restating "as we have seen so far, content marketing is changing" is filler, not micro-thesis. The micro-thesis should add framing or sharpen the claim, not recap. + +Where the micro-thesis sits structurally. Often at the boundary between two body sections, especially the boundary between the first and second halves of a layered argument or the boundary between the third and fourth chapters of an ebook. + +--- + +## Combining the techniques + +A 6,000-word whitepaper using all five techniques. + +- Lede. Contested-claim opener, declarative register, short paragraphs for opening punch. +- Setup section. Analytical register, medium-density argument, 3-5 sentence paragraphs. +- First body section. Argument-tight density, analytical register sustained, longer paragraphs as the argument layers. +- Mid-piece micro-thesis. A short paragraph that restates the claim with new framing. Brief register shift to declarative. +- Second body section. Argument-tight density, but with a worked example inserted as a breathing pause. Worked example shifts briefly to narrative register. +- Counter-argument section. Argument-tight again, analytical register, with the counter-arguments engaged seriously. +- Synthesis. Density lower, register declarative, paragraphs short and emphatic. +- Closing. Declarative, short, specific. + +The piece reads as varied across its length even though it is a single sustained argument. + +--- + +## Common attention-loss patterns + +Patterns that show up when readers drop off mid-piece. + +The mid-piece sag. Around the 50% mark, the piece becomes harder to follow. Cause: no micro-thesis, no rhythm variation, the reader is exhausted from sustained argument-tight density. Cure: add micro-thesis at the section boundary nearest the midpoint; insert a breathing section. + +The wall-of-text section. A 1,500-word body section with no subheads, no visuals, no rhythm variation. Cause: the writer was deep in the argument and stopped attending to the reader. Cure: identify the natural sub-structure within the section, add subheads or visuals at the boundaries. + +The abstract drift. The piece's specifics decrease as it progresses. Concrete examples in the early sections; vague generalizations in the later sections. Cause: the writer ran low on specific examples; padded with abstraction. Cure: cut to the depth where specificity holds; better a shorter piece with sustained specificity than a longer piece that drifts abstract. + +The energy-decline closing. The closing reads as a writer who ran out of energy. Cause: writers fatigue before readers do. Cure: write the closing first or revise the closing last with fresh attention; the closing is too important to deliver tired. + +--- + +## Methodology-level choices that stay in the public skill + +The five techniques (density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis), the combining pattern, the common attention-loss patterns and their cures, the read-aloud audit. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags rhythm patterns. Specific reading-time analytics that detect mid-piece drop-off in the team's content. Specific paragraph-length analyzers in the team's writing tool. Specific A/B testing of structural variants. The team's own conventions for visual-element budgets per long-form piece. These vary by team, stack, and analytics setup. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md new file mode 100644 index 0000000..f361487 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/breakouts-and-visualization.md @@ -0,0 +1,147 @@ +# Breakouts and visualization + +Visual element types for long-form, the earned-position rule, the production-tax discipline, and the stock-image-header anti-pattern. The patterns that distinguish visual rhythm from visual clutter. + +Long-form earns visual breakouts; blog posts often do not. A 1,500-word blog post can carry one image; a 5,000-word whitepaper can carry six or eight visual elements before they feel like clutter. The discipline is not visual count but earned position: which visuals carry argumentative load, and which are decoration. + +--- + +## Visual element types + +Six categories, each with different work to do. + +Charts and graphs. Data visualization that conveys patterns the prose alone cannot convey efficiently. Line charts for time series, bar charts for comparisons, scatter plots for correlations, distributions for spread. The chart's value is showing the pattern; if the prose can summarize the pattern in one sentence and the chart adds nothing, the chart is decoration. + +Diagrams. Relationships, flows, architectures, taxonomies that benefit from visual structure. Process diagrams, system architectures, hierarchical relationships, decision trees. The diagram's value is making structure visible; topics with simple linear structure rarely need diagrams. + +Pull quotes. Moments where a single sentence deserves visual weight. Used sparingly for emphasis; one or two per long-form piece typical. The pull quote's value is signaling "this matters"; using pull quotes too often dilutes the signal. + +Sidebars. Tangential but valuable context that does not fit the main thread. Background detail, related concepts, optional deeper coverage. The sidebar's value is letting the main thread stay focused while preserving context for readers who want it. + +Tables. Comparison data, structured reference material. Side-by-side option comparisons, parameter listings, multi-axis evaluations. The table's value is making parallel data scannable; tables for non-parallel data are confusing. + +Inline callouts. Definitions, warnings, "if you only read one section" pointers. Short, focused, specific. The callout's value is interrupting flow for a specific purpose; callouts without specific purpose are decoration. + +--- + +## The earned-position rule + +Each visual element earns its place by carrying argumentative load the prose alone cannot. + +Earned visuals. + +- A chart that shows a pattern the prose can only summarize in vague terms ("increasing over time" becomes specific with the line chart). +- A diagram that makes a complex relationship instantly visible (a system architecture; a process flow with decision points). +- A pull quote that captures a position the writer wants to stand alone for emphasis. +- A sidebar with context that would derail the main thread if inline. +- A table that makes parallel comparison instant when the prose would require careful reading. + +Decorative visuals. + +- A chart that restates a number the prose just stated (the chart adds visual interest, not information). +- A diagram of a relationship the prose described in one sentence ("the marketing funnel" diagrammed, when the prose said "marketing has stages"). +- A pull quote of a sentence that did not deserve standalone weight. +- A sidebar with information that should have been cut entirely or integrated into the main thread. +- A table where the rows or columns are not actually parallel. +- A stock image at the top of the piece that signals only that the writer wanted a hero image. + +The audit. For each visual, ask: does cutting this visual lose information or capability that the prose alone cannot replace? If yes, the visual is earned. If no, the visual is decoration. + +--- + +## Production tax + +Visual elements cost more than writers often estimate. + +Per-visual costs. + +- Design time. Even simple charts require choices about color, scale, labeling, formatting. +- Accessibility work. Charts need alt text or alternative-format descriptions; tables need proper header markup; complex visuals need text equivalents. +- Revision overhead. When the data changes, the chart changes. When the framing changes, the diagram changes. Visual elements that go stale because they were not updated when the underlying content changed are worse than no visuals. +- Production review. Editors review prose; design or production review visuals. Pieces with many visuals need more review cycles. + +The capacity audit. Before committing to a visual count for a piece, check: does the team have the design capacity, the data-engineering capacity (for charts based on data), and the maintenance capacity to keep this number of visuals current? Pieces that ship with 12 visuals and decay because nobody updates them are worse than pieces that ship with 4 visuals that stay current. + +The MVP-visuals approach. Plan the minimum viable visual count: which visuals are load-bearing for the argument, which would be nice to have, which would be decoration. Ship the load-bearing ones. Add nice-to-haves only if capacity permits and the piece is genuinely long enough to need more visual rhythm. + +--- + +## The stock-image-header anti-pattern + +Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. + +The pattern. A whitepaper opens with a generic stock photo of "diverse business team meeting around laptop with charts." The image conveys nothing specific; readers tune it out within milliseconds. + +Why it fails. Long-form's value proposition includes signaling that the work is serious. Stock imagery undermines the signal: a serious piece would have commissioned specific visual work or skipped the hero image. Stock imagery says "we wanted a hero image and did not invest in one." + +The cure options. + +- Commission specific visual work. Custom illustration matched to the piece's argument. Branded data visualization based on the piece's findings. Scene photography directly related to the piece's case study. +- Skip the hero image entirely. Long-form pieces can open without a hero image; many of the strongest editorial pieces do. +- Use a content-specific opening visual. The first chart in the piece appears at the top, doing dual duty as hero image and load-bearing visual. + +The discipline. If the piece's hero image could be on any other piece on the same general topic, it is generic and should be cut or replaced. + +--- + +## Chart conventions for long-form + +Charts in long-form pieces have specific expectations. + +Title and caption. Every chart should have a title that describes what the chart shows and a caption that explains the source of the data. Charts without titles or captions read as decoration. + +Source attribution. The data behind the chart should be cited. "Source: 2024 Industry Survey, n=412, methodology in appendix" or similar. Charts without source attribution are unverifiable. + +Mobile readability. Charts should be readable on mobile without horizontal scrolling. Wide charts should be redesigned for mobile or marked as "view on desktop for full detail." Charts that are unreadable on mobile lose mobile readers. + +Color and contrast. Charts should pass accessibility contrast guidelines (WCAG AA minimum). Color-coded charts need either patterns or labels for readers with color-blindness. Charts that rely on color alone fail accessibility. + +Data integrity. Truncated y-axes that exaggerate effects, cherry-picked time ranges, and apples-to-oranges comparisons violate the implicit chart contract. Long-form readers who notice deceptive charts lose trust in the entire piece. + +--- + +## Diagram conventions for long-form + +Diagrams should make structure visible without becoming the main attraction. + +Simplicity. A diagram with 30 boxes and 50 arrows is a diagram nobody reads. Diagrams should be visually parse-able in seconds. Complex topics may need multiple simple diagrams rather than one comprehensive one. + +Labeling. Every box, arrow, and group should be labeled clearly. Diagrams with unlabeled elements assume the reader can infer the labels from context, which often fails. + +Reading order. Diagrams should have an obvious reading order (top to bottom, left to right, or numbered steps). Diagrams without obvious reading order leave readers uncertain how to traverse them. + +Mobile rendering. Wide diagrams that work on desktop become unreadable on mobile. Either redesign for mobile, accept that mobile readers will scroll, or split into multiple smaller diagrams. + +--- + +## Sidebar conventions + +Sidebars should be visually distinct from the main thread but not overwhelming. + +Length. Most sidebars run 100-300 words. Sidebars longer than 500 words probably should have been their own section in the main thread or their own piece. + +Visual treatment. Background color or border that distinguishes the sidebar from main prose. Different typography weight or font (where the design system supports it). + +Skip-readability. Sidebars should be skippable without losing the main argument. If the main argument depends on the sidebar's content, that content belongs in the main thread, not in a sidebar. + +--- + +## Pull-quote discipline + +Pull quotes should be earned moments, not decoration. + +Selection. A pull quote is a sentence the writer wants to stand alone for emphasis. It should be a sentence whose weight justifies the visual treatment. Generic sentences pulled into pull-quote treatment dilute the device. + +Frequency. One or two pull quotes per long-form piece is typical. Three or four can work for very long pieces (8,000+ words). More than that and the device loses meaning. + +Attribution within pull quotes. Pull quotes from interviews or external sources need attribution; pull quotes of the writer's own sentences do not need attribution but should still earn the visual weight. + +--- + +## Methodology-level choices that stay in the public skill + +The six visual element types and their work, the earned-position rule, the production-tax discipline, the stock-image-header anti-pattern, the chart conventions, the diagram conventions, the sidebar and pull-quote discipline, the MVP-visuals approach. + +## Implementation choices that stay internal + +Specific design tokens for charts in the team's brand system. Specific charting libraries the team uses. Specific accessibility-checking automation. Specific design-review workflow for visual elements. Specific custom-illustration commissioning processes. Specific stock-photo blocklist or sourcing guidelines. The team's own visual-budget conventions per format. These vary by team, design capacity, and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md new file mode 100644 index 0000000..5e961f6 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/citation-and-source-authority.md @@ -0,0 +1,130 @@ +# Citation and source authority + +Source hierarchy for long-form, citation density discipline, freshness norms, inline vs endnote conventions, and the citation-laundering anti-pattern. + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. Pieces that fail at citation discipline read as if the writer wanted authority without paying the verification cost. + +--- + +## Source hierarchy + +Sources are not interchangeable. The same claim cited from a peer-reviewed paper carries different weight than the same claim cited from a vendor blog post. + +Tier 1: Primary research. Original studies, datasets, interviews, the writer's own data work. The writer is producing the data, not citing it. Highest authority. Pieces with primary research signal that the writer or team did the work. + +Tier 2: Authoritative secondary sources. Peer-reviewed papers, government data (BLS, Census, equivalent), established research firms (Gartner, Forrester, Pew, IDC, etc.), primary reporting from credible outlets. The writer is citing rigorous secondary work where the source's reputation does the verification work. + +Tier 3: Industry-credible sources. Vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners with track records. The writer is citing sources that practitioners in the field would recognize as substantive even if they are not academically rigorous. + +Tier 4: Linked-aware secondary sources. Reputable blogs, publications, and commentary where the source is verifying claims rather than just amplifying them. The writer is citing sources that did some level of verification work, even if the source is a blog post rather than a study. + +Tier 5 and below: Avoid. Other content marketing pieces (citation laundering), "studies show" claims with no link, anonymous "experts," reposts of reposts, vendor marketing pages cited as research, AI-generated synthesis cited as primary source. + +The discipline. Long-form arguments should cite from tiers 1-3 wherever possible. Tier 4 is fine for color and context but should not bear primary argumentative load. Tier 5 sources signal the writer did not do the verification work. + +--- + +## Citation density + +Citations should be roughly proportional to claim density. + +A piece making 30 falsifiable claims. Roughly 30 citations or attributions to primary analysis. Each claim either points to a verifiable source or is identified as the writer's own analysis (in which case the analysis itself should be defended). + +A piece making 5 strong claims with extensive elaboration. May need only 5 citations if the elaboration is reasoning rather than fact-claim. Manifestos and position pieces often work this way: a small number of central claims, deeply argued, with citations supporting the claims rather than every elaboration. + +The audit. Mark every falsifiable claim in the piece. For each claim, check: is it cited, is it identified as the writer's own analysis, or is it floating? Floating claims are the failure mode. Either cite, attribute to the writer, or cut. + +The over-citation failure. Some long-form pieces cite every sentence as if academic rigor were the goal. The result reads as a literature review, not a piece of editorial writing. Citations should support the argument, not perform credibility theater. + +--- + +## Source freshness + +Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. + +Fast-moving topics. Technology, marketing tactics, AI capabilities, software stacks, social platforms. A 2018 stat in a 2026 piece on these topics signals stale research unless the writer is citing it specifically as historical context. + +Stable topics. Behavioral psychology research, structural economics, mathematical results, established scientific consensus. A 2015 stat on these topics may be perfectly current. + +The acknowledgment pattern. When citing older data on a fast-moving topic deliberately, acknowledge it: "A 2018 survey, the most recent rigorous data on the question, found..." The acknowledgment signals the writer knows the data is old and chose to cite it anyway, with reasoning. + +The hidden-stale-data failure. Citing a "2024 study" that turns out to be a 2024 republication of 2019 data. Verify primary publication date before citing. + +--- + +## Inline vs endnote citations + +Two conventions for how citations appear. + +Inline links. The cited source appears as a hyperlink within the prose. Reader clicks to verify. Common in editorial long-form, content marketing whitepapers, and most web-published research reports. + +- Strength: keeps reader momentum; the prose flows without numerical interruptions. +- Weakness: harder to verify without leaving the page; less academically formal. + +Endnote-style citations. Numbered footnotes at the end of the piece, with each citation numbered in the prose. Common in academic-influenced research reports, policy whitepapers, and some long-form published with print-style conventions. + +- Strength: signals academic rigor; preserves the citation list for verification. +- Weakness: interrupts reading flow; readers rarely follow endnotes in web reading. + +The convention rule. Pick one and stay consistent within the piece. Mixing conventions (some claims inline-linked, some endnoted) reads as inconsistent. The choice depends on audience expectations: B2B technical research often expects endnotes; editorial whitepapers usually expect inline. + +Hybrid: inline + bibliography. Inline links throughout the piece plus a "sources" or "further reading" section at the end. Common compromise. Works well when the piece has both casual references and core sources. + +--- + +## The citation-laundering anti-pattern + +Citing other content marketing pieces as authoritative when the cited piece itself does not have primary support. + +The pattern. Piece A claims X with a citation. Piece B cites A as the source for X. Piece C cites B. The original claim X may have been weak, made-up, or misinterpreted; each successive citation amplifies the appearance of authority without adding verification. + +How it happens. A writer searching for support for a claim finds another content marketing piece making the same claim and links to it. The writer feels they have cited a source. The source is itself unsourced or weakly sourced. The chain of laundering can run several pieces deep. + +The cure. When citing, follow the chain back. If the cited piece does not have primary or authoritative-secondary support, do not cite it. Either find a primary source, or remove the claim, or attribute it as the writer's own observation. + +Why it matters in long-form. The reader is investing time. Citation laundering produces pieces that read as authoritative because of citation count but fall apart under verification. Readers who verify discover the laundering; readers who do not develop a slow-decaying trust in the writer. + +--- + +## The own-analysis citation + +When the writer is making a claim from their own analysis rather than citing a source, the claim should be visibly the writer's analysis with the analytical work shown. + +The pattern. "Looking at the data across [scope], the pattern that emerges is X." The pattern claim is the writer's; the data is cited; the analytical work is described. + +The discipline. Own-analysis claims still need defensibility. The writer should be able to defend, if challenged: where the data came from, how the analysis was performed, what alternative interpretations were considered. + +The hidden-claim failure. Sentences that read as fact ("The reality is that programmatic SEO is dying") without acknowledgment that the claim is the writer's interpretation. If the claim is contested, frame it as the writer's view; if the claim is empirical, cite a source. The hidden middle (claim presented as fact when it is interpretation) is where readers lose trust. + +--- + +## Quote attribution + +Long-form pieces often include quotes from named experts, executives, or practitioners. + +Verification. Every quote should be from a real person who actually said the words attributed to them. Hallucinated quotes (especially in AI-assisted long-form) are an ethical failure regardless of whether the position is plausibly something the named person might say. See `editorial-qa`'s fact-accuracy reference for the discipline. + +Context. Quotes work best when the person's role is identified, the context of the statement is clear (interview, public statement, prior writing), and the quote earns its place by saying something specific. + +The throwaway-quote failure. A generic quote ("Content is king," John Smith, CEO) that does not advance the argument. If the quote does not say something specific the prose alone cannot convey, cut it. + +--- + +## Citation in research reports specifically + +Research reports have particularly strict citation expectations because they are claiming primary research authority. + +- Methodology disclosed. Sample size, recruitment method, dates, instrument design. Without these, the research is not verifiable. +- Sample limits acknowledged. What the sample does and does not represent. A sample of 300 marketers in B2B SaaS does not represent "marketers"; the report should not claim it does. +- Statistical limits acknowledged. Confidence intervals, margins of error, significance tests where applicable. Reports presenting cherry-picked data points without distribution context are weak research. +- Original data made available. Where possible, the underlying data should be shareable for verification. Reports that hide the data behind the headline findings invite skepticism. + +--- + +## Methodology-level choices that stay in the public skill + +The source hierarchy and tier definitions, the citation-density principle, the freshness rule and acknowledgment pattern, the inline-vs-endnote convention rule, the citation-laundering anti-pattern, the own-analysis discipline, the quote-attribution rules, the research-report citation expectations. + +## Implementation choices that stay internal + +Specific citation management tools the team uses. Specific bibliography generators integrated with the team's writing system. Specific link-checking automation that catches dead links and stale data. Specific data-publication conventions for research reports the team produces. The team's own internal source-tier classification when sources are ambiguous. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md new file mode 100644 index 0000000..34995e0 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/closing-patterns.md @@ -0,0 +1,161 @@ +# Closing patterns + +Five closings that work, four that fail, and the underlying frame: the closing is the writer's last opportunity to leave the reader with something specific. Closings that do not leave anything specific signal a writer who ran out of energy, and the piece is remembered accordingly. + +Long-form pieces with strong closings get shared, get linked, get remembered. Pieces with throat-clearing closings disappear after the last subhead. The closing is one of the most consequential 200-400 words of any long-form piece, and one of the easiest places for writers to under-invest. + +--- + +## The underlying frame + +The closing has three jobs at once. + +1. Resolve the piece. Whatever the lede promised, the closing delivers (or acknowledges what was not delivered). +2. Leave the reader with something specific. A specific call, a sharpened framing, a question to consider. The reader should be different at the closing than they were at the lede. +3. Earn the reader's attention for next time. The closing is the reader's last impression. Readers who finish a piece with a strong closing think of the writer as someone who delivers; readers who finish a piece with a weak closing think of the writer as someone who runs out of energy. + +Closings that do all three are memorable. Closings that do none are forgettable. Closings that do one or two are common and produce pieces that are technically complete but emotionally flat. + +--- + +## Pattern 1: The specific call + +Shape. What should the reader do, decide, or change as a result of reading this. Concrete, not generic. + +Fits. Most long-form pieces. Particularly strong for problem-solution archetype, manifestos, decision-guide research reports, long-form tutorials. + +Worked example. A 5,000-word whitepaper on content distribution closes: "If your team is producing content faster than you can distribute it, the bottleneck is not your production rate. It is your channel-fit decisions. Audit one piece you shipped in the last quarter against the channel-fit framework. Find the one channel where the audience-content match was strongest but the piece never reached that channel. That gap is where the next quarter's distribution work should focus." + +Why it works. The reader has a specific action. The action is grounded in the piece's framework, so the framework keeps working after the reading is over. + +The discipline. The call must be specific to the piece. Generic calls ("rethink your content strategy") signal that the writer did not commit to a specific recommendation. + +--- + +## Pattern 2: The reframed thesis + +Shape. The opening claim restated with the weight the body has now earned, often inverted, sharpened, or made more specific. + +Fits. Layered-argument pieces. Whitepapers. Manifestos. Pieces where the body's evidence justifies a stronger version of the opening claim. + +Worked example. A whitepaper that opens "Most teams treating content marketing as a volume problem will continue to underperform" closes: "The volume problem is not actually a content problem. It is a strategy problem the team has chosen to express through content. Teams that solve the strategy problem produce less content and more value; teams that try to solve the strategy problem with more content produce more content and less value. The path forward is not better content production. It is harder strategy decisions." + +Why it works. The reframed thesis lands the argument with weight the lede could not have carried. The body has done the work; the closing collects the payoff. + +The discipline. The reframing must be earned by the body. Pieces that restate the lede unchanged are recapping; pieces that restate it with sharpened framing the body justifies are doing the closing's work. + +--- + +## Pattern 3: The open question + +Shape. The question this piece's findings raise but do not answer, framed as the next investigation. + +Fits. Research reports. Analytical whitepapers. Pieces where the writer has gone as far as the available evidence allows but the topic continues. + +Worked example. A research report on AI search citation patterns closes: "The data is clear that statistics with named sources earn citations at 4x the rate of unsourced claims. The data does not tell us why. The hypothesis worth testing in the next research cycle: do AI engines weight named sources because they are training on a corpus that itself weights named sources, or because the engine providers have built explicit credibility-weighting into the retrieval logic? The answer matters because the answer changes how content programs should respond." + +Why it works. The reader is left with intellectual momentum. The piece does not pretend to have answered everything; it acknowledges what it did not answer and frames that as productive rather than as a limit. + +The discipline. The open question must be a real question, not a rhetorical one. "What does the future hold?" is rhetorical filler. "Is the citation pattern downstream of the training corpus or of explicit retrieval logic?" is a real question. + +--- + +## Pattern 4: The personal reflection + +Shape. The writer's stake in the topic surfaced briefly. What the writer thinks the piece illustrates beyond its specific argument. + +Fits. Manifestos. Opinionated long-form. Pieces where the writer has personal authority on the topic. Some case studies where the writer was personally involved. + +Worked example. A manifesto on content marketing's drift toward generic AI-assisted output closes: "I have been writing about content for a decade. The pattern that worries me is not that AI is involved; the pattern that worries me is that teams have stopped noticing when their content stopped sounding like them. The discipline this piece argues for is not anti-AI. It is pro-craft. The teams holding the line on craft will be readable in five years. The teams not holding the line will not be." + +Why it works. The personal stake adds weight to the argument. The writer's investment in the topic is the closing's payoff: the reader sees that the argument is not abstract for the writer. + +The discipline. The personal reflection must be earned by the writer's actual position. Personal reflections from writers without a real stake feel performed. + +--- + +## Pattern 5: The provocation + +Shape. A challenge to the reader, the field, or the consensus. Often paired with a refusal to soften the position. + +Fits. Manifestos. Position pieces. Long-form criticism. Pieces where the writer is staking out an unpopular or contested position deliberately. + +Worked example. A manifesto on programmatic SEO closes: "The teams that will survive the next three years of search-algorithm pressure are the ones that stop treating programmatic as a volume strategy and start treating it as a depth strategy. Most programmatic operations will not make this change. They will not survive. This piece is for the few that will." + +Why it works. The provocation establishes that the writer means it. The reader either accepts the provocation and reads the piece as a call to action, or rejects it and reads the piece as wrong; either response is engaged. The middle response (mild interest, no engagement) is what kills long-form's reach. + +The discipline. The provocation must be defensible. Provocations the body did not actually argue for read as posturing. Provocations the body argued for and the closing committed to with conviction read as serious. + +--- + +## Failure 1: The recap closing + +Shape. "In this piece, we covered X, Y, Z. As we have seen, content is important and only getting more so..." + +Why it fails. Signals the writer ran out of energy. Recap is what the table of contents does; the closing should add weight, not summarize. Readers who just spent 30 minutes reading do not need the recap; they need the writer to land the argument. + +The cure. Cut the recap. Replace with one of the five working patterns. The closing is not a tour through what the piece said; it is the writer's final position. + +--- + +## Failure 2: The "more research is needed" closing + +Shape. Most research reports default to "More research is needed in this area" as a closing. + +Why it fails. Signals the writer did not commit a position even when the data warranted one. "More research is needed" is the default closing of academic papers because academic papers have specific norms about hedging; editorial long-form does not have those norms, and the default reads as evasive. + +The cure. If the data does support a position, commit the position. If the data does not support a position, frame the closing as an open question (Pattern 3) rather than a generic call for more research. + +--- + +## Failure 3: The throat-clear closing + +Shape. "As we have seen, [topic] is important. Going forward, [generic platitude about the topic continuing to evolve]. Teams that [generic recommendation] will be best positioned to [generic outcome]." + +Why it fails. Delivers no payload. Every word could appear in any other piece on the same topic. The reader's response is "I read 5,000 words for this?" + +The cure. Strip the closing of every generic phrase. What is left is usually nothing; rewrite from scratch with one of the working patterns. + +--- + +## Failure 4: The CTA-as-closing + +Shape. The closing is "Book a demo with us today" or "Sign up for our newsletter" or "Download the full report." + +Why it fails. Breaks the editorial contract. Long-form readers who reached the closing have invested 30+ minutes in editorial content; pivoting to a sales call reads as bait-and-switch. Trust is damaged. + +The cure. If a CTA belongs in the piece, place it after the closing, visually distinct, framed as an offer rather than as the closing itself. The piece's editorial closing does its work first; the CTA appears afterward as a separate element. + +--- + +## The closing audit + +A short framework for auditing a draft closing. + +1. Does the closing leave the reader with something specific to do, decide, or think about? If not, rewrite. +2. Could this closing appear at the end of any other piece on this topic? If yes, the closing is generic. Rewrite to be specific to this piece. +3. Does the closing have approximate weight to the piece? A 5,000-word piece with a 50-word closing under-invests; a 1,500-word piece with a 600-word closing over-invests. +4. Read the closing aloud. Does it have energy? Closings that read as tired signal the writer was tired. The reader registers the energy. Rewrite when fresh. +5. Does the closing match one of the five working patterns? If it matches one of the failure patterns, rewrite using a working pattern. + +--- + +## When to write the closing first + +Some long-form writers write the closing first and write the body toward it. + +The argument for closing-first. Knowing where the piece lands clarifies what the body needs to argue. Writers who draft the body without knowing the closing often discover at the closing that the body did not actually support the planned closing, and have to rework substantial sections. + +The argument against closing-first. Some pieces' closings emerge from the body's argument; predetermining the closing constrains where the body can go. Research reports particularly may benefit from following the data and writing the closing once the analysis is complete. + +The middle path. Draft a target closing before writing the body. Revisit the target after the body draft. The target may stand, or the body may have produced a stronger closing than the target predicted. + +--- + +## Methodology-level choices that stay in the public skill + +The five working patterns and the four failure patterns, the underlying frame, the closing audit, the closing-first discussion, and the CTA-vs-editorial-closing distinction. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags closing patterns. Specific style guides on closing length and weight in the team's editorial system. Specific A/B testing of closing variants for engagement metrics. Specific conventions for whether and where CTAs appear after closings. These vary by team, audience, and analytics setup. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md new file mode 100644 index 0000000..2310a3b --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/common-long-form-failures.md @@ -0,0 +1,179 @@ +# Common long-form failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear repeatedly across long-form drafts, regardless of topic, format, or writer experience. Diagnosing them early saves the rewrite work that catches them late. + +The pattern across most failures: writers reaching for length without doing the structural work that justifies it, and writers under-investing in the structural decisions that make long-form land. + +--- + +## Failure 1: Bloggy-long + +Symptom. A 5,000-word piece reads as a 1,500-word piece stretched. Padding paragraphs. Recap sections. "Before we get into it" preludes. Bullet expansions of single ideas. The reader notices within 600 words and skims. + +Diagnosis. The writer chose length first and structural depth second. The piece needed to be longer than 1,500 words for SEO or marketing reasons but did not have 5,000 words of substantive content. + +Cure. Two options. Cut to actual substantive length (often 1,800-2,500 words). Or expand the structural depth: add original analysis, primary research, case study specificity, or comparative dimensions that justify the length. + +Prevention. Choose length based on substantive content, not based on competitor length or SEO targets. SEO algorithms are getting better at detecting padded length; the strategy of "outranking by being longer" is increasingly counterproductive. + +--- + +## Failure 2: Academic-bloat + +Symptom. A 7,000-word whitepaper that is exhaustive but loses the thread. Every adjacent topic surveyed. Every definition restated. Every caveat documented. Reader respects the effort and skims for the parts they need. + +Diagnosis. The writer aimed for comprehensiveness rather than for argumentative load. The piece treats inclusion as the metric instead of treating each section's contribution as the metric. + +Cure. Apply the section-weight audit: which sections are actually load-bearing, which are surveying. Cut surveying sections that do not support specific claims in the load-bearing sections. Often takes 7,000 words to 4,500 with the argument intact. + +Prevention. Outline the argument before drafting. Each section should answer: what does this section contribute to the argument? If a section's answer is "comprehensive coverage" rather than a specific contribution, question whether the section earns its place. + +--- + +## Failure 3: Throat-clearing lede + +Symptom. The lede took 800 words to get to the thesis. Multiple paragraphs of "content marketing has changed dramatically" before the piece's actual claim appears. + +Diagnosis. The writer was warming up. Drafts often have throat-clearing ledes; finished pieces should not. + +Cure. Cut the first 400-700 words of the lede. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clearing draft. + +Prevention. After drafting, ask: where does the piece's specific argument actually start? Whatever appears before that point is throat-clearing and can usually be cut. + +--- + +## Failure 4: Even-section padding + +Symptom. All H2s come within 10% of each other in word count. Each section running 800-1,000 words regardless of its argumentative load. + +Diagnosis. The writer treated section length as a quota. Long sections were padded; short sections were either padded or not deepened. + +Cure. Identify which sections are actually load-bearing. Let them grow. Cut filler from non-load-bearing sections. + +Prevention. Plan section weights in the outline based on argumentative load, not on parallel structure. Allow 2x or 3x weight differences between sections doing different amounts of work. + +--- + +## Failure 5: Mid-piece sag + +Symptom. The piece sags around the 60% mark. Reader-attention analytics show drop-off at this point. + +Diagnosis. Standard mid-piece attention dip, untreated. No micro-thesis, no rhythm variation; the reader is exhausted from sustained density. + +Cure. Add a mid-piece micro-thesis at the section boundary nearest the midpoint. Insert a breathing section (anecdote, illustration, or reflective moment) into a stretch of argument-tight prose. Vary visual rhythm in the mid-piece section. + +Prevention. During outlining, mark the midpoint and plan the micro-thesis explicitly. During drafting, audit the middle third for rhythm variation. + +--- + +## Failure 6: Recap closing + +Symptom. The closing repeated the introduction. "In this piece we covered X, Y, Z. As we have seen, content is important..." + +Diagnosis. The writer ran out of energy. The closing was drafted last, in fatigue, and it shows. + +Cure. Rewrite the closing using one of the five working patterns: specific call, reframed thesis, open question, personal reflection, or provocation. + +Prevention. Write the closing first, or revise the closing last with fresh attention. Closings deserve disproportionate effort because they are disproportionately consequential. + +--- + +## Failure 7: Citation laundering + +Symptom. Citations are mostly other content marketing pieces rather than primary or authoritative-secondary sources. + +Diagnosis. The writer searched for support for claims and found other content marketing pieces making the same claims. Citing them feels like sourcing; it is not. + +Cure. Follow each citation chain back to the original. If the chain ends at a primary source, cite the primary source. If the chain ends at unsourced or weakly sourced content marketing, either find a primary source for the claim or cut the claim. + +Prevention. Default to Tier 1-3 sources (primary research, authoritative secondary, industry-credible). Only cite Tier 4 sources for color and context, never for argumentative load. + +--- + +## Failure 8: Visual-count overrun + +Symptom. The piece commissioned 12 charts. The team is exhausted from production. Six months later, charts are stale because nobody updated them. Traffic is the same as it would have been with 4 charts. + +Diagnosis. Visual count exceeded production capacity and earned-position discipline. + +Cure. Cut to the visuals that bear argumentative load the prose alone cannot. Update them on a maintainable cadence. Future pieces budget visuals against capacity rather than against ideal-world maximalism. + +Prevention. Apply the MVP-visuals approach: which visuals are load-bearing, which would be nice to have, which would be decoration. Ship the load-bearing ones first; add others only if capacity permits. + +--- + +## Failure 9: Generic case study + +Symptom. The case study has no specifics. "A leading enterprise SaaS company" rather than the company name. "Significant revenue growth" rather than the actual percentage. "Several months" rather than the timeline. + +Diagnosis. The case study format failed at its primary tax: specificity. Either the case was too confidential to share specifics, or the specifics were never gathered. + +Cure. Get specifics. Negotiate with the customer for what can be shared. If specifics genuinely cannot be shared, abandon the case study format and write a different format (general thought-leadership piece on the lessons learned, with the specific case relegated to background). + +Prevention. Do not commit to the case study format until specifics are confirmed shareable. Generic case studies fail the format and are less valuable than honest pieces about the lessons without claiming case-study authority. + +--- + +## Failure 10: Diplomatic manifesto + +Symptom. The manifesto reads as diplomatic. "Both sides have valid points." "The answer probably lies somewhere in the middle." Hedge stacking on positions that should be specific. + +Diagnosis. The writer chose the manifesto format but could not commit to the conviction the format requires. Often reflects organizational risk-aversion: the manifesto's bold framing was approved but its actual conviction was edited out. + +Cure. Either rewrite to commit a position (the format demands it), or change the format. A diplomatic position paper that is not pretending to be a manifesto is fine; a manifesto that hedges is broken. + +Prevention. Before committing to the manifesto format, confirm the writer (and the organization) actually has a contested position to argue. If hedging is required, write a different format. + +--- + +## Failure 11: Definitive guide with gaps + +Symptom. The "definitive" guide has obvious sub-topic gaps that the audience would notice. The piece claims comprehensiveness but does not deliver it. + +Diagnosis. The format implies coverage that the piece does not have. Either the gaps reflect topics the writer did not cover deliberately (and should have flagged), or the writer did not realize the gaps existed. + +Cure. Either fill the gaps or rename the piece. "The definitive guide to X" with gaps is broken; "A practitioner's guide to X" with the same content but without the comprehensiveness claim is fine. + +Prevention. Before claiming definitive-ness, audit against the audience's likely sub-topic expectations. Confirm coverage or change the framing. + +--- + +## Failure 12: Wrong archetype + +Symptom. The piece is fighting itself. The writer is trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. The reader senses the structural friction even when they cannot articulate it. + +Diagnosis. Archetype-format mismatch or archetype-topic mismatch. The writer chose an archetype that does not fit the work. + +Cure. Identify the natural archetype for the topic and the format. Restructure. This is often a substantial revision because the archetype is the spine; changing it changes how sections fit together. + +Prevention. Choose archetype before drafting. Confirm the archetype fits the format and the topic. Do not commit to draft until the archetype-format-topic combination is coherent. + +--- + +## Failure 13: Format-tax unpaid + +Symptom. The piece is published in a long-form format but does not pay the format's specific tax. A whitepaper without original synthesis. A research report without primary research. A long-form tutorial with broken steps. + +Diagnosis. The writer reached for the format's authority without paying the cost the format demands. + +Cure. Either pay the tax (do the original work the format requires) or change the format. A piece published in the wrong format reads as a category error to readers familiar with the format. + +Prevention. Confirm the format-tax is payable before committing to the format. Format choice is a downstream decision from "what work is the team prepared to do." + +--- + +## The cross-cutting pattern + +Most long-form failures share a single root: the writer chose length, format, or visual ambition first, and chose the structural and substantive depth second. The pieces that read as publication-quality are the ones where the inverse choice is made: substantive depth first, then length, format, and visual ambition follow from the depth. + +The fix for almost any long-form failure starts with the same audit: what is the piece actually doing, what is each section actually contributing, what does the format require, what does the topic need? When those questions get clear answers, the piece either earns its length or shrinks to a length that fits its substance. + +--- + +## Methodology-level choices that stay in the public skill + +The thirteen-plus failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the prevention discipline. + +## Implementation choices that stay internal + +Specific draft-review checklists the team uses. Specific failure-pattern detection in the team's editing tools. Specific reviewer training on the patterns. Specific case-study negotiation templates for getting customer specifics. The team's own conventions for archetype-format fit confirmation. These vary by team, format mix, and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md new file mode 100644 index 0000000..c624e14 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/format-decision-framework.md @@ -0,0 +1,139 @@ +# Format decision framework + +When each long-form format fits, what reader contract it implies, and the format-specific taxes that distinguish credible work from filler dressed in the format's clothes. + +Format selection is the first long-form decision. The wrong format produces predictable failure: a thinly-researched whitepaper reads as a blog post in formal clothing; a manifesto written diplomatically reads as a position paper that committed nothing. Each format has a reader contract. Failing the contract is what readers detect even when they cannot articulate why a piece is not landing. + +--- + +## Case study + +Reader contract. "Show me what worked, what did not, and the specifics that let me apply lessons to my own situation." + +Length norm. 2,000 to 4,000 words. Shorter feels like a marketing snippet; longer feels padded unless the case is unusually rich. + +Structural archetype tendency. Problem-solution, sometimes narrative arc. + +Format-specific tax. Specifics. Real company names (or, where confidential, well-disclosed anonymization with enough context to verify the case is real). Real numbers. Real timelines. Real failures alongside successes. Generic case studies that read like marketing collateral fail because the format's value proposition was specificity. + +Common failures. Anonymized to the point of meaninglessness ("a leading enterprise SaaS company saw 3x growth"); uncritical success narrative with no failures or surprises; missing methodology (what was measured, how, over what period); no reflection (what would the team change, what limits the lesson's applicability). + +When the format does not fit. When the case is too thin to support 2,000+ words of specificity, write a short customer story instead. When the case is so confidential that real numbers cannot be shared, the case study format is the wrong choice. + +--- + +## Whitepaper + +Reader contract. "Take me through your reasoning on this question with the rigor I would expect from a serious source. Make an argument I have not seen elsewhere." + +Length norm. 3,000 to 8,000 words. + +Structural archetype tendency. Layered argument or comparative analysis. + +Format-specific tax. Original synthesis. A whitepaper that surveys what other sources already said is not a whitepaper; it is a literature review. The whitepaper format implies the writer is contributing analysis, framing, or synthesis the reader cannot find elsewhere. + +Common failures. Survey of the field with no original argument; vendor-thinly-disguised pitch document; methodological hand-waving on the data the argument rests on; conclusion that hedges the position the introduction stated. + +When the format does not fit. When the writer does not have an original synthesis to contribute, write a different format. A survey-style "state of the industry" report is a research report, not a whitepaper. A vendor pitch is a pitch deck, not a whitepaper. Calling either a whitepaper to borrow the format's authority is the genre-mismatch failure mode. + +--- + +## Research report + +Reader contract. "Show me the data, how you collected it, what it means." + +Length norm. 4,000 to 12,000 words. Often longer when methodology and full data appendices are included. + +Structural archetype tendency. Taxonomic survey or comparative analysis. + +Format-specific tax. Actual primary research. Survey data with disclosed methodology, sample sizes, dates, and limits. Interview data with sample composition disclosed. Original quantitative work the writer did or commissioned. Citing other firms' research and calling the result a research report fails the contract. + +Common failures. "We surveyed 300 marketers" with leading questions and no methodology disclosure; cherry-picked data points presented without distribution or variance; methodology paragraph that gestures at rigor without delivering it; findings overstated relative to the sample's actual representativeness. + +When the format does not fit. When primary research budget is unavailable. Calling a literature synthesis a research report is genre fraud; write a whitepaper or a definitive guide instead. + +--- + +## Definitive guide + +Reader contract. "Be the canonical resource on this topic for the audience the piece names." + +Length norm. 4,000 to 10,000 words. + +Structural archetype tendency. Taxonomic survey. + +Format-specific tax. Actual comprehensiveness. A definitive guide that has obvious topic gaps fails the format. The audience the piece names matters: a definitive guide for senior practitioners and a definitive guide for newcomers are different pieces; trying to be definitive for both audiences usually fails both. + +Common failures. Comprehensive on the easy parts of the topic, thin on the hard parts; outdated when published because the format suggests timeless authority but the topic moves quickly; not actually definitive because key sub-topics are missing or treated as out-of-scope without justification. + +When the format does not fit. When the topic is too broad for a single piece to cover canonically (then write a hub: see `pillar-content-architecture`). When the topic is so specialized that "definitive" is a category of one and the format's value disappears. + +--- + +## Manifesto + +Reader contract. "Tell me what you believe, why, and convince me. Take a position I can argue with." + +Length norm. 1,500 to 6,000 words. + +Structural archetype tendency. Layered argument or narrative arc. + +Format-specific tax. Conviction. The manifesto format demands the writer commit a position with weight. Diplomatic hedging produces a piece that reads as a manifesto in form but a position paper in substance. Readers detect the gap. + +Common failures. "Both sides have valid points" framings that the manifesto format does not support; hedge-stacked claims ("typically", "generally", "often") on positions that should be specific; closing that walks back the opening's strength; fear of alienating audience segments producing a piece that alienates everyone by committing to nothing. + +When the format does not fit. When the writer does not actually have a contested position to argue. Calling a survey of consensus views a manifesto is a category error. Write a whitepaper or a position paper if hedging is required. + +--- + +## Ebook + +Reader contract. "Take me through a body of work as a sequence of related pieces." + +Length norm. 8,000 to 30,000+ words across multiple chapters. + +Structural archetype tendency. Narrative arc across chapters, with each chapter using its own archetype. + +Format-specific tax. Each chapter earns its place. A 12-chapter ebook with 3 chapters that should have been cut signals the format was reached for to add length, not because the work justified the format. Table of contents reading reveals the discipline: are the chapters distinct contributions, or is the ebook one argument padded into 12 pieces? + +Common failures. Repetitive chapters covering the same ground from slightly different angles; introduction and conclusion that are throat-clearing rather than load-bearing; missing connective tissue between chapters that leaves the reader uncertain how the chapters fit; no reason for the work to be an ebook rather than a long-form whitepaper. + +When the format does not fit. When the work fits in 6,000 words. Stretching a long-form whitepaper to ebook length usually weakens it. Write the long-form whitepaper. + +--- + +## Long-form tutorial + +Reader contract. "Take me from where I am to where I want to be, step by step, and make sure every step works." + +Length norm. 3,000 to 8,000 words. + +Structural archetype tendency. Problem-solution with sequential steps. + +Format-specific tax. Every step works. Long-form tutorials fail catastrophically when one step is broken: the reader stops there, cannot continue, and the rest of the tutorial is wasted. The tutorial-tax is verification that each step in the sequence delivers the result the next step assumes. + +Common failures. Skipped steps that were obvious to the writer but blocking to the reader; outdated steps that worked when written but no longer (especially common with tutorials referencing fast-moving tools); broken sequences where step 6 assumes a configuration step 4 did not actually create. + +When the format does not fit. When the topic does not have a clean sequential path. Branching tutorials where the path varies by reader context are usually better as a hub of shorter pieces (see `pillar-content-architecture`) than as one long-form tutorial trying to handle every branch. + +--- + +## The format-fit decision + +A short framework for choosing. + +1. What is the reader contract? What is the reader investing 30+ minutes to get? Specifics (case study)? Original analysis (whitepaper)? Original data (research report)? Comprehensive coverage (definitive guide)? Conviction (manifesto)? A body of work (ebook)? Sequential instruction (long-form tutorial)? +2. Can the team pay the format-specific tax? If the format demands specifics and the case is too confidential to share specifics, the format does not fit. If the format demands conviction and the writer wants to hedge, the format does not fit. +3. Is there an original contribution? Whitepapers, manifestos, and research reports particularly require original contribution. Definitive guides and tutorials can be valuable as comprehensive synthesis without original argument. +4. Does the audience expect this format? Some audiences expect whitepapers (B2B technical), some manifestos (founder-led brands), some research reports (analyst-influenced markets). Format choice signals genre-fit to the audience. +5. Is the production capacity available? Long-form tutorials with verified sequential steps cost meaningful verification time. Research reports cost primary-research budget. Format choice must match capacity, or the format-tax goes unpaid and the piece reads as the format-it-pretended-to-be. + +--- + +## Methodology-level choices that stay in the public skill + +The seven format definitions and their reader contracts. The format-specific taxes that distinguish credible work from filler dressed in the format. The decision framework that matches format to work. The genre-mismatch failure modes. The when-the-format-does-not-fit handling. + +## Implementation choices that stay internal + +Specific case study templates the team uses. Specific whitepaper layouts in the brand's design system. Specific research-report data presentation conventions matching the team's design tokens. Specific PDF production tooling. Specific gating workflow integrations with the team's marketing automation. Specific tutorial step-verification scripts that match the stack the tutorials cover. These vary by team, brand, and tooling; methodology applies regardless. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md new file mode 100644 index 0000000..0e357f1 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md @@ -0,0 +1,148 @@ +# Lede patterns for long-form + +Five patterns that work, four that fail, and the underlying frame: the first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. + +Long-form ledes do different work than blog-post ledes. A blog-post lede answers the user's likely query in the first 200 words for SEO. A long-form lede earns attention for the time investment ahead. Both can be true at once (an SEO-driven long-form piece needs to do both), but the long-form discipline is the harder of the two: the lede that answers a query in 200 words is not necessarily the lede that earns 30 minutes of reader attention. + +--- + +## The underlying frame + +Treat the first 150-250 words of a long-form piece as the writer's pitch to the reader. The reader is deciding, paragraph by paragraph, whether the time investment is going to be worth it. The lede has to: + +- Establish that the writer has something specific to say (not a survey). +- Set the thesis or central question the body will deliver. +- Earn enough attention to get the reader past the first H2. + +If the lede does not do these three things, readers leave at the first H2 boundary, before the body has a chance to deliver. + +--- + +## Pattern 1: The contested-claim opener + +Shape. A surprising or contested position stated cleanly, then the rest of the piece argues for it. + +Fits. Manifestos. Opinionated whitepapers. Position pieces. Long-form analysis where the writer has a specific view. + +Example shape. "Most teams treating content marketing as a volume problem will continue to underperform their budget through the end of the decade. The discipline that produces durable content programs is the one most teams skip: deciding what NOT to publish." + +Why it works. The reader's response is "wait, why?" The piece exists to answer that. The contested claim earns the reader's attention because the reader is now invested in seeing whether the argument holds. + +The discipline. The contested claim must actually be defensible across the piece. Lede claims that the body fails to support produce broken contracts; readers feel deceived. + +--- + +## Pattern 2: The problem-with-stakes opener + +Shape. A problem stated with the stakes made tangible. The reader sees themselves or their situation in the problem and wants the solution. + +Fits. Case studies. Problem-solution pieces. Long-form tutorials. Manifestos with a clear opposition. + +Example shape. "Three months after the migration, organic traffic was down 38%, the team had spent four hundred hours on the project, and nobody could explain where the loss was coming from. The migration had been planned for six months. Every checklist item had been completed. And the search-console graph was still pointing the wrong direction." + +Why it works. Stakes ground the abstract. The reader feels the problem before reading any solution, which earns attention for the solution that follows. + +The discipline. The stakes must be real, not invented for dramatic effect. Inflated stakes ("the future of marketing is at stake") read as filler. Specific stakes ("the migration cost $400K and three quarters of trust with the executive team") read as honest. + +--- + +## Pattern 3: The data-anomaly opener + +Shape. A piece of data that does not fit the consensus, framed as the question the piece will answer. + +Fits. Research reports. Analytical whitepapers. Evidence-driven long-form. + +Example shape. "The median programmatic SEO program in 2025 generated more than 80% of its traffic from fewer than 5% of its pages. The pattern held across e-commerce, B2B SaaS, marketplaces, and travel. This piece is about why." + +Why it works. The data point creates a specific question. The reader wants the answer. The body's job is to deliver the answer with the analytical depth the question deserves. + +The discipline. The data point must be load-bearing. If the body's argument does not actually flow from the opening data, the lede was decoration rather than scaffolding. + +--- + +## Pattern 4: The scene opener + +Shape. A specific moment, person, or scene that grounds the abstract topic. The reader enters the piece through a concrete situation, and the abstract argument follows. + +Fits. Narrative-arc pieces. Magazine-style longform. Pieces where human stakes are part of the argument. Some manifestos. + +Example shape. "On a Tuesday morning in September 2024, two engineers stood in front of a whiteboard covered in arrows and tried to explain to the new VP what the data pipeline actually did. The VP had been at the company three weeks. The whiteboard had been there four years. Neither of them could finish a sentence without contradicting the other." + +Why it works. Specific scenes hold attention. Readers complete narrative-arc pieces at higher rates than other archetypes; the scene opener uses that pull from the first paragraph. + +The discipline. The scene must connect to the piece's argument. Scene openers that are decorative ("imagine you are a marketer in 2026...") rather than load-bearing waste reader attention on prelude. + +--- + +## Pattern 5: The orientation opener + +Shape. What this piece covers, who it is for, what reading it costs and what it delivers. Orientation, not throat-clearing. + +Fits. Definitive guides. Long-form tutorials. Reference-type long-form where the reader's first question is "is this the right resource for me." + +Example shape. "This guide is for engineering leaders deciding whether to migrate from a service mesh to a sidecar-less alternative. It assumes familiarity with Kubernetes and basic mesh concepts. Reading it costs about 30 minutes. It will not cover the original arguments for adopting a mesh; that is a different question. It will cover the migration decision: when it makes sense, what to expect, what fails." + +Why it works. Reference-type readers self-select on relevance. The orientation opener saves the wrong reader's time and earns the right reader's attention. Pieces that the right reader does not finish often fail because the wrong readers came in and the right readers left. + +The discipline. The orientation must be honest. Guides that overpromise relevance ("for anyone interested in cloud infrastructure") draw wrong readers; guides that underpromise lose right readers. + +--- + +## Failure 1: The throat-clear opener + +Shape. "Content marketing has changed dramatically over the past decade. In this article, we will explore how to..." + +Why it fails. Filler signal. The reader knows the piece is about content marketing because of the title; restating it wastes attention. The "in this article we will explore" frame is a tour, not an argument; readers respond to arguments more than to tours. + +The cure. Cut the throat-clear paragraphs entirely. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clear draft. + +--- + +## Failure 2: The dictionary-definition opener + +Shape. "According to Merriam-Webster, X is defined as..." + +Why it fails. Signals an unwillingness to commit a position. The reader assumes the writer does not have a specific framing of their own and is hiding behind the dictionary's framing. For long-form, this is fatal: long-form earns reader attention through specific framing. + +The cure. State the writer's framing. If the writer needs to disambiguate the term, do so in their own words after stating their position. + +--- + +## Failure 3: The history-of-the-topic opener + +Shape. Three or four paragraphs of background before the argument starts. + +Why it fails. Long-form readers tolerate background but only after they know why they should care. Front-loading background means the reader leaves before the thesis lands. The history-of-the-topic opener typically reflects the writer's research process leaking into the piece structure: the writer learned the history while researching, so they put it first, even though the reader does not need it first. + +The cure. Move history into the body where it supports specific claims. Lead with the thesis or the question the piece answers. + +--- + +## Failure 4: The "in this article we will discuss" tour opener + +Shape. "In this article, we will discuss A, then B, then C, then D, then conclude with E." + +Why it fails. Flattens the piece into an outline before the writer has earned attention. Tours signal a writer who is not confident the body will hold the reader, so they preview it. The preview itself is what loses the reader: outlines are less interesting than the argument they describe. + +The cure. Trust the body to deliver. If the piece needs a navigation aid, use a table of contents or jump links, not an opening tour. + +--- + +## The lede audit + +A short framework for auditing a draft lede. + +1. Does the first paragraph establish a specific position, problem, data point, scene, or orientation? If it does general throat-clearing instead, cut. +2. By the end of the first 250 words, has the thesis or central question of the piece been stated? If not, the lede is too long. +3. Does the lede earn the reader's next 30 minutes? Read the lede as a stranger to the topic. Would you keep reading? If you would skim, the lede is filler. +4. Does the body deliver on the lede's promise? Some failed ledes are technically fine but make promises the body does not keep. The audit happens after the body is drafted: does the lede's framing match what the piece actually argues? + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns and the four failures, the underlying frame, the lede audit, the format-tendency mapping, and the lede-body integrity discipline. + +## Implementation choices that stay internal + +Specific lede templates the team has built. Specific draft-review tooling that flags throat-clearing language patterns automatically. Specific A/B testing of lede variants against engagement metrics. The team's own conventions for lede-length norms within the bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md new file mode 100644 index 0000000..9a95f94 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/section-weight-calibration.md @@ -0,0 +1,128 @@ +# Section weight calibration + +How long sections should be relative to each other, varying by format. The audit pattern that catches structural imbalance, and the underlying principle that section weight should match argumentative load. + +Most long-form pieces fail at section weight before they fail at any other dimension. A 6,000-word whitepaper with seven sections of similar length signals that the writer treated each H2 as a quota rather than as an argument-bearing unit. The pieces that read as publication-quality are the ones where some sections breathe and others compress, where argumentative load is reflected in word count, and where filler sections were cut rather than evened out. + +--- + +## The underlying principle + +Section weight should match how much argumentative load the section is bearing. + +Throat-clearing introductions get cut or compressed. Setup sections that orient the reader without making the argument yet are short. Body sections that are doing the actual work of the piece are longest. Closings are specific and tight. When section weights deviate from this, the piece is either padded (sections doing too little for their length) or under-developed (sections doing too much for their length). + +The audit is straightforward. For each section, ask: what argumentative work is this section doing, and is the word count proportional to that work? Sections doing little work that take up much space are filler. Sections doing much work that take up little space are under-developed. + +--- + +## Whitepaper / research report typical weights + +For a 5,000-word whitepaper or research report. + +- Introduction. 8-12%. Roughly 400-600 words. Thesis stated, scope set, why the piece exists. +- Methodology or framing. 10-15%. Roughly 500-750 words. How the analysis works, what data the argument rests on, what the reader should know about how the writer arrived at the position. +- Body. 60-70%. Roughly 3,000-3,500 words. Divided into 3-5 weighted sections. The actual argument or findings. The largest body sections are the load-bearing ones; smaller body sections support or transition. +- Implications. 10-15%. Roughly 500-750 words. What the argument means for the reader's situation. +- Closing. 3-5%. Roughly 150-250 words. Specific call, reframed thesis, or open question. + +--- + +## Case study typical weights + +For a 3,000-word case study. + +- Setup and context. 15-20%. Roughly 450-600 words. The company, the problem, why the problem mattered, what was at stake. +- Solution narrative. 50-60%. Roughly 1,500-1,800 words. What the team did, in sequence, with the decision points that mattered. +- Outcomes. 15-20%. Roughly 450-600 words. Quantified results, what worked beyond expectations, what did not work as planned. +- Reflection. 5-10%. Roughly 150-300 words. What the team would change, what limits the case's applicability. + +The case-study weight discipline. The setup and the outcomes can be roughly even; the solution narrative is the longest section because it is doing the most work; the reflection is short because it is concentrated honest assessment. + +--- + +## Manifesto typical weights + +For a 3,500-word manifesto. + +- Position. 5-10%. Roughly 175-350 words. What is believed, stated early and clearly. Manifestos that bury the position lose readers before the argument starts. +- Argument. 70-80%. Roughly 2,450-2,800 words. Why, with the layers building intensity. The argument's later layers should be more intense, more specific, or more confrontational than the earlier layers; intensity that flattens loses momentum. +- Call. 10-15%. Roughly 350-525 words. What should change as a result of accepting the position, who should change it, what the writer asks of the reader. + +The manifesto weight discipline. Position is short and load-bearing. Argument is long and intensifies. Call is specific and demands action or position-taking from the reader. + +--- + +## Definitive guide typical weights + +For a 7,000-word definitive guide. + +- Introduction. 5-8%. Roughly 350-560 words. What the guide covers, who it serves, what reading it costs and pays. +- Body across taxonomic sections. 80-85%. Roughly 5,600-5,950 words. Each category in the taxonomy treated with parallel structure. The categories should be roughly even in length unless the taxonomy itself implies asymmetry (some categories are more important than others). +- Closing and additional resources. 7-10%. Roughly 490-700 words. Synthesis, recommendation about which categories matter most, pointers to next steps. + +The definitive-guide weight discipline. Most of the weight is in the body categories. The introduction is short because the guide's value is in the taxonomy treatment, not in extended setup. The closing's value is synthesis, not recap. + +--- + +## Long-form tutorial typical weights + +For a 5,000-word long-form tutorial. + +- Setup. 10-15%. Roughly 500-750 words. What the reader will achieve, what they need to start, what the success state looks like. +- Sequential steps. 70-80%. Roughly 3,500-4,000 words. Each step its own subsection. Steps doing more work get more words; trivial steps stay short. The temptation to even out step lengths produces tutorials that feel padded on simple steps and rushed on hard ones. +- Troubleshooting and edge cases. 10-15%. Roughly 500-750 words. What goes wrong, what to do about it, when the reader has likely diverged from the success path. + +The tutorial weight discipline. Steps are weighted by actual difficulty, not by parallel structure. The troubleshooting section is load-bearing because tutorials fail at the failure-points; documenting them is the difference between a tutorial that works and one that strands readers. + +--- + +## Ebook typical weights + +For a 20,000-word ebook with 8 chapters. + +- Introduction. 3-5%. Roughly 600-1,000 words. Why the ebook exists, who it serves, how the chapters fit together. +- Each chapter. 10-13%. Roughly 2,000-2,600 words per chapter. Chapter weights can vary; a load-bearing chapter at the center may run 3,500 words while a transitional chapter runs 1,500. The variation should reflect actual content load, not arbitrary balancing. +- Closing chapter or synthesis. 5-8%. Roughly 1,000-1,600 words. What the body of work amounts to. + +The ebook weight discipline. Chapter weights match chapter load; introduction and closing earn their place by doing connective work the body chapters cannot. + +--- + +## The 3x audit + +A practical heuristic for catching section-weight problems. + +Compare any two sections bearing similar argumentative load. If one is more than 3x the length of the other, the piece is structurally unbalanced. Three responses: + +1. Split the long section. If the long section is genuinely doing 3x the work, it is probably actually two or three sections that should be separated for the reader's navigation. +2. Deepen the short section. If the long section's length is correct, the short section is probably under-developed and the argument it is making is being skipped. +3. Acknowledge the imbalance. If the asymmetry reflects an actual content reality (one category in the taxonomy genuinely matters 3x as much as another), the piece can keep the imbalance but should signal it to the reader so the structure does not feel arbitrary. + +--- + +## Common section-weight failures + +Patterns that show up repeatedly in long-form drafts. + +Even-section padding. All H2s come out within 10% of each other in word count. Signal: writer is treating section length as a quota. Cure: identify which sections are actually load-bearing and let them grow while cutting the filler ones back. + +Front-loaded setup. Introduction is 25% of the piece. Signal: writer was not confident enough in the thesis to commit it early; spent the first quarter of the piece warming up. Cure: cut the introduction by half, lead with the thesis. + +Body imbalance. One body section is 50% of the piece while three others are 10% each. Signal: either the long section is actually multiple sections that should be separated, or the short sections are filler that should be cut. + +Missing closing. Closing is 1-2% of the piece. Signal: writer ran out of energy. Cure: rewrite the closing to actual proportional weight; specific call, reframed thesis, or open question. + +Throat-clearing across sections. Each section starts with 100-200 words of "as we discussed in the previous section" before getting to the section's actual work. Signal: writer is over-managing reader navigation. Cure: trust the reader; cut the recap paragraphs. + +Bullet inflation. A section's word count comes mostly from bulleted lists where each bullet is one expanded sentence. Signal: writer is using bullets to inflate length without doing the integration work. Cure: rewrite the bullets as prose if the integration matters; cut to a tighter list if the items are genuinely parallel. + +--- + +## Methodology-level choices that stay in the public skill + +The underlying principle (weight matches argumentative load), the format-specific weight profiles, the 3x audit, the common section-weight failure patterns and their cures. + +## Implementation choices that stay internal + +Specific word-count tracking tools the team uses to audit drafts. Specific outline templates with weight targets per section in the team's writing system. Specific reviewer dashboards that surface section-weight imbalance for editorial review. The team's own conventions for which formats run shorter or longer than the typical bands. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md b/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md new file mode 100644 index 0000000..1e56d54 --- /dev/null +++ b/dist/pi/.agents/skills/long-form-content-frameworks/references/structural-archetype-patterns.md @@ -0,0 +1,145 @@ +# Structural archetype patterns + +Five archetypes that fit different long-form problems, with worked examples and the patterns for combining archetypes within a single piece. + +The archetype is the spine of a long-form piece. It determines how the argument unfolds, how the reader's attention is structured, and which structural moves feel natural versus which would jar. Selecting the wrong archetype produces a piece that fights itself: the writer trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. + +--- + +## Archetype 1: Problem-solution + +Shape. State the problem with weight. Develop why it matters and who is affected. Present the solution. Show how it works in detail. Address objections. Close with implications. + +Fits. Case studies. Long-form tutorials. Manifestos with a clear opposition. Pieces where the writer has a specific recommendation and a specific framing of what the recommendation answers. + +Worked example: a 3,500-word case study. + +- Setup: the company, the problem, why the problem mattered (15-20% of the piece). +- The solution narrative: what the team did, in sequence, with the decision points that mattered (50-60%). +- Outcomes: quantified results, what worked beyond expectations, what did not work as planned (15-20%). +- Reflection: what the team would change, what limits the case's applicability (5-10%). + +Strengths. Direct, action-oriented, satisfies readers looking for "show me how to solve this." Clear forward momentum prevents reader drift. + +Risks. Feels formulaic when overused (every case study reading the same shape). Tempts oversimplification: real situations rarely fit a clean problem-solution arc, and forcing them to flattens the case's interest. + +--- + +## Archetype 2: Narrative arc + +Shape. Beginning establishing characters and stakes. Middle developing complications. End resolving (or refusing to resolve) the central tension. Time progresses; events follow each other. + +Fits. Ebooks across chapters. Some case studies, particularly founder stories, transformation cases, multi-year initiatives. Magazine-style longform. Manifestos where the writer's own journey is part of the argument. + +Worked example: a 6,000-word transformation case study. + +- Opening: a specific scene that grounds the abstract topic (the Monday-morning meeting where the problem became inescapable). +- Rising action: the situation getting worse before it gets better, the failed attempts, the false starts. +- Turning point: the specific decision or insight that shifted the trajectory. +- Resolution: what the new state looks like, what the team learned, what is still in progress. +- Coda: the writer's broader observation about what the story illustrates. + +Strengths. Most engaging archetype for sustained attention. Readers complete narrative-arc pieces at higher rates than other archetypes. Memorable; readers tell other readers. + +Risks. Forced narrative on topics that are not stories. A whitepaper trying to be a narrative arc usually fails because the topic does not naturally have characters, complication, and resolution. The forcing is detectable. + +--- + +## Archetype 3: Layered argument + +Shape. Position stated. Layer 1 evidence supporting the position. Layer 2 evidence, often deeper or addressing a different aspect. Layer 3, often counter-arguments or caveats. Synthesis tying the layers together. + +Fits. Whitepapers. Manifestos. Position pieces. Analytical long-form. Pieces where the writer is making a case that requires building support across multiple distinct kinds of evidence. + +Worked example: a 5,000-word whitepaper. + +- Position: the central claim, stated cleanly in the first 200 words (10%). +- Layer 1: the structural argument (why the position follows from how the system works). 25%. +- Layer 2: the empirical argument (what data supports the position). 25%. +- Layer 3: counter-arguments engaged seriously and answered. 20%. +- Synthesis: what the layers together imply, including implications the position-statement alone did not surface. 15%. +- Closing: specific call or reframed thesis. 5%. + +Strengths. Rigorous, defensible, persuasive to skeptical readers. Readers engaging seriously with the position find their objections engaged in the counter-argument layer. + +Risks. Feels academic if the synthesis is weak. Layers that do not actually build to a synthesis read as three separate articles stacked. The audit: cut one layer; does the synthesis still work? If yes, that layer was filler. + +--- + +## Archetype 4: Taxonomic survey + +Shape. A topic mapped into categories. Each category explored. Relationships among categories surfaced. Sometimes a recommendation about which categories matter most, often a synthesis about what the taxonomy reveals. + +Fits. Definitive guides. Research reports surveying a landscape. Long-form tutorials covering a topic with parallel rather than sequential structure. Comparative pieces. + +Worked example: a 7,000-word definitive guide. + +- Introduction: what the guide covers, who it serves, what reading it costs and pays (5-8%). +- Taxonomy framing: how the topic divides, why these categories rather than other possible categories (8-12%). +- Category 1, 2, 3, 4 (etc.): each treated with parallel structure (definition, examples, when-it-fits, how-it-works) so readers can navigate. 70-75% across all categories. +- Synthesis: what the taxonomy reveals about the topic as a whole; which categories the writer thinks matter most and why. 7-10%. +- Closing: what to do with the taxonomy. 3-5%. + +Strengths. Reference-friendly. Readers come back to taxonomic surveys multiple times to look up specific categories. SEO-friendly because each category often answers a discrete query. + +Risks. Feels like a list with subheads if the taxonomy is not actually load-bearing. The audit: does the taxonomy reveal something that a list of items would not? If no, the piece is a list pretending to be a taxonomy. + +--- + +## Archetype 5: Comparative analysis + +Shape. Multiple options, frameworks, or positions. Defined axes of comparison. Each option scored or characterized along each axis. Tradeoffs surfaced. The writer's recommendation argued. + +Fits. Whitepapers comparing approaches. Decision-guide research reports. Technology comparisons. Evaluations. Pieces where the reader's question is "which of these should I choose." + +Worked example: a 4,500-word technology comparison. + +- Setup: the decision the reader is making, why it matters, who this comparison serves (8-10%). +- Comparison axes: the dimensions the writer chose to compare on, with justification for why these axes (5-8%). +- Each option treated along the axes: parallel structure so readers can compare at-a-glance. 50-60%. +- Tradeoff synthesis: what the comparison reveals about which option fits which context. 15-20%. +- Recommendation: the writer's view, with the conditions under which the recommendation holds. 8-10%. +- Closing: how to decide. 3-5%. + +Strengths. Decision-useful. Readers facing the decision the comparison addresses get clear input. Pairs well with comparison tables and side-by-side data. + +Risks. Feels like a feature matrix if the analysis is shallow. The axes matter: shallow axes (price, speed, ease) produce shallow analysis. Deep axes (failure modes under load, what the platform optimizes for, what the platform forces you to give up) produce useful comparison. + +--- + +## Combination patterns + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. + +Layered argument with comparative-analysis sections. A whitepaper arguing a position with a comparative-analysis section showing how the position handles edge cases that competing positions do not. + +Taxonomic survey with problem-solution chapters. A definitive guide where each category in the taxonomy includes a problem-solution treatment of how to apply it. + +Narrative arc with layered-argument moments. An ebook where the narrative carries the reader through a transformation while individual chapters argue for specific positions encountered along the way. + +Problem-solution with taxonomic-survey frame. A long-form tutorial that introduces a taxonomy of failure modes and then walks through the solution sequentially. + +Comparative analysis with case-study illustration. A whitepaper comparing approaches with a case study embedded for one of the approaches to ground the analysis. + +The discipline. One archetype as spine; another as variation. Pieces using three archetypes simultaneously fragment; pieces using one archetype rigidly feel formulaic. + +--- + +## Selecting the archetype + +A short framework. + +1. What is the reader's relationship to the question? "Tell me how" suggests problem-solution. "Tell me what happened" suggests narrative arc. "Convince me" suggests layered argument. "Map the landscape" suggests taxonomic survey. "Help me decide" suggests comparative analysis. +2. What does the topic naturally have? Topics with a clear protagonist, complication, and resolution naturally fit narrative arc. Topics with parallel categories naturally fit taxonomic survey. Topics with a contested position naturally fit layered argument or manifesto-flavored layered argument. +3. What does the format expect? Case studies expect problem-solution or narrative arc; whitepapers expect layered argument or comparative analysis; definitive guides expect taxonomic survey. Format-archetype mismatch is detectable to readers even when they cannot articulate it. +4. What is the writer's strength? Different writers have different archetype strengths. A writer who naturally argues should not force themselves into narrative-arc longform; a writer who naturally narrates should not force themselves into taxonomic surveys. Assign archetype to writer skill where possible. + +--- + +## Methodology-level choices that stay in the public skill + +The five archetype shapes, the worked examples, the combination patterns, the selection framework, the format-archetype fit tendencies, the writer-skill matching consideration. + +## Implementation choices that stay internal + +Specific archetype templates the team has built for repeat formats. Specific section-length scaffolds the team uses. Specific document templates per archetype in the team's writing tool. Specific archetype tagging in the team's content calendar so editorial mix can be reviewed. The decision rubric the team uses for archetype assignment when multiple writers are working on the same format. These are team-specific operationalizations of the methodology. diff --git a/dist/pi/.agents/skills/media-asset-management/SKILL.md b/dist/pi/.agents/skills/media-asset-management/SKILL.md new file mode 100644 index 0000000..85511d5 --- /dev/null +++ b/dist/pi/.agents/skills/media-asset-management/SKILL.md @@ -0,0 +1,305 @@ +--- +name: media-asset-management +description: "Plan and run a media pipeline for images, video, and downloadable assets. Use this skill when designing image storage and delivery, choosing formats (WebP, AVIF), setting up responsive images, picking a video host, organizing a brand asset library, or auditing a slow image pipeline. Triggers on image pipeline, asset library, DAM, image optimization, WebP, AVIF, responsive images, video hosting, image CDN, asset workflow, media management. Also triggers when images are slow, broken, or scattered across systems." +category: operations +catalog_summary: "Image pipelines, video hosting, asset libraries, format selection" +display_order: 9 +--- + +# Media Asset Management + +Design how images, video, and downloadable files get stored, processed, organized, and served. Stack-agnostic. The principles apply whether you're running a custom pipeline or using a hosted service. + +--- + +## When to use + +- Designing or redesigning the image and media pipeline +- Choosing a media CDN or image service +- Setting up responsive image delivery +- Planning a digital asset management (DAM) system +- Auditing media performance issues +- Picking video hosting and embedding strategy +- Setting up workflows for designers and writers to upload assets +- Migrating media from one platform to another + +## When NOT to use + +- Performance optimization beyond media (use `performance-optimization`) +- Brand identity or photography direction (use `brand-identity`, `art-direction`) +- Content production strategy (use `content-strategy`) +- Single-image optimization (covered in `performance-optimization`) + +--- + +## Required inputs + +- Current media inventory: where assets live, in what formats +- Volume: how many assets, how much storage, how much traffic +- Sources: who creates and uploads media (designers, writers, automated tools) +- Platforms: where media is consumed (web, email, app, partners) +- Performance baseline: current image sizes, load times +- Budget reality: hosted services have monthly costs + +--- + +## The framework: 4 stages + +The media pipeline has four stages. Each has its own decisions. + +### Stage 1: Source + +Where assets enter the system. + +Sources: +- Designers (Figma exports, Photoshop, Illustrator) +- Photographers (RAW or JPEG from camera) +- Stock photo libraries +- AI-generated images +- User-generated content (uploads) +- Automated systems (e.g., screenshots, generated thumbnails) + +At source, decide: +- File formats accepted (RAW, TIFF, PSD, AI vs delivered formats) +- Naming conventions +- Required metadata (alt text, captions, credits, rights) +- Maximum source resolution (high enough to derive any size; not so high it's wasteful) +- Where source files live (separate from delivered assets) + +Anti-pattern: sources and delivered assets in the same place. Hard to find masters. Hard to regenerate. Hard to audit usage. + +### Stage 2: Process + +Transforming source files into delivery formats. + +Processing decisions: +- Resize to standard sizes (e.g., a fixed set of widths: 320, 640, 960, 1280, 1920, 2560) +- Compress (lossy or lossless, with quality targets) +- Convert formats (JPEG, WebP, AVIF for raster; SVG for vector) +- Generate thumbnails and previews +- Strip metadata (EXIF, GPS) unless intentionally retained +- Color profile management (sRGB for web) + +Process options: +- Build-time: Static assets processed during deploy. Predictable, fast at runtime, hard to vary. +- On-demand: A service generates the right format/size when requested. Flexible, requires a processing layer. +- Hybrid: Static processed sizes plus on-demand for edge cases. + +For sites with many image variants and ongoing change, on-demand wins. For tightly controlled marketing sites, build-time can be simpler. + +### Stage 3: Deliver + +Getting assets to users efficiently. + +Delivery decisions: +- CDN: required for any non-trivial volume. Edge caching, global distribution. +- Format negotiation: serve AVIF to browsers that support it, WebP otherwise, JPEG as fallback. Use the `<picture>` element or content negotiation. +- Responsive images: `srcset` and `sizes` attributes so browsers pick the right size for the viewport. +- Lazy loading: `loading="lazy"` for below-the-fold images. +- Async decoding: `decoding="async"` for non-critical images. +- Width and height attributes: always set, prevents layout shift. + +Modern HTML pattern: + +```html +<img + src="/image-1280.jpg" + srcset="/image-640.jpg 640w, /image-960.jpg 960w, /image-1280.jpg 1280w, /image-1920.jpg 1920w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +Or for format negotiation: + +```html +<picture> + <source type="image/avif" srcset="/image.avif"> + <source type="image/webp" srcset="/image.webp"> + <img src="/image.jpg" alt="Descriptive alt text" width="1280" height="720"> +</picture> +``` + +### Stage 4: Manage + +Keeping the system organized and useful over time. + +Management decisions: +- Asset library or DAM (digital asset management): centralized place for the team to find assets +- Tagging and search +- Version control (designers updating an asset, old version still in use) +- Rights and licensing tracking +- Audit and cleanup (what's not used anymore?) +- Permissions (who can upload, edit, delete) + +A simple shared folder works at low scale. A real DAM is necessary above a few thousand assets or with multiple teams. + +--- + +## Format reference + +For typical web use: + +\| Format \| Use for \| Avoid for \| +\|---\|---\|---\| +\| AVIF \| Photographs, complex images. Best compression. \| Browser support edge cases (rare in 2026, ubiquitous now) \| +\| WebP \| Photographs, illustrations. Good compression. Wide support. \| Print, archival \| +\| JPEG \| Photographs (fallback). Universal support. \| Sharp-edged graphics, transparent backgrounds \| +\| PNG \| Sharp-edged graphics, transparent backgrounds, screenshots. Lossless. \| Photographs (file size) \| +\| SVG \| Logos, icons, simple illustrations. Scalable. \| Photographs, complex art \| +\| GIF \| Effectively obsolete. Use video formats for animation. \| Anything modern \| +\| MP4 (H.264) \| Video, universal support. \| Static content \| +\| WebM (VP9 / AV1) \| Video, better compression. \| Older browsers \| + +For most sites: serve AVIF/WebP for modern browsers, JPEG/PNG fallback. SVG for vector. MP4 for video. + +--- + +## Workflow + +### Step 1: Inventory + +What assets exist? Where? In what state? + +- Image count and total storage +- Average sizes (KB) per format +- Image-related performance metrics +- Number of pages with broken or missing images +- Source files vs delivered files + +### Step 2: Audit performance + +For a sample of pages: +- Image weight per page (target: under 500KB total for marketing pages) +- Number of image requests +- Are responsive images used? +- Are modern formats served? +- Is there layout shift from missing dimensions? + +Tools: Lighthouse, WebPageTest, your CDN's analytics. + +### Step 3: Pick the pipeline + +Three reasonable patterns: + +Pattern A: Static, build-time +- Assets in repo or storage bucket +- Build process generates sizes and formats +- Served via CDN +- Good for: static sites, low asset churn, tight performance control + +Pattern B: Image CDN with on-demand +- Source uploads to a bucket or service +- An image CDN (Cloudinary, imgix, Cloudflare Images, Bunny, etc.) processes on-demand via URL parameters +- Good for: mid-to-large sites, frequent asset changes, multiple variants + +Pattern C: Headless CMS with built-in image API +- CMS holds source assets +- CMS provides image API for resizing, format conversion +- Good for: content-heavy sites, non-technical content uploaders, when CMS is already chosen + +The patterns aren't mutually exclusive. Big sites often use Pattern A for design assets, Pattern B for content images. + +### Step 4: Define standards + +Document: +- Naming conventions +- Required metadata (alt text, attribution) +- Maximum source dimensions +- Minimum source dimensions per use case +- Approved formats +- File size targets + +Make these enforceable through tooling where possible (CI checks on file sizes, alt text required by CMS). + +### Step 5: Set up workflows + +For each source type: + +\| Source \| Workflow \| +\|---\|---\| +\| Designer \| Export from Figma, drop into bucket, automated processing handles the rest \| +\| Writer \| Upload through CMS, CMS prompts for alt text \| +\| Photographer \| RAW into source bucket, designer or automation creates web variants \| +\| User upload \| Pass through the image service, automatic moderation if applicable \| + +Document who does what. Workflows that aren't documented break. + +### Step 6: Build the asset library + +For all but the smallest sites: +- Centralized DAM or shared library +- Tag taxonomy (subject, style, brand, campaign, etc.) +- Search across tags and metadata +- Documented rights for each asset (stock license, custom commission, work-for-hire, etc.) +- Sunset workflow (rights expire, asset retires) + +### Step 7: Monitor and audit + +- Performance metrics on image-heavy pages +- Storage costs +- CDN costs +- Broken image alerts (404 on referenced media) +- Unused asset cleanup (storage costs accumulate) + +### Step 8: Document the pipeline + +A pipeline document covers: +- Diagram of source → process → deliver → manage +- Tools used at each stage +- Standards and naming conventions +- Workflows for common cases +- Escalation when something breaks + +--- + +## Failure patterns + +Source files in the delivery bucket. 50MB RAW files served to users. Fix: separate sources from delivered. + +Single image format for every browser. JPEG-only when AVIF could be 30-50% smaller. Use format negotiation. + +Missing width and height attributes. Causes layout shift, hurts CLS metric. Set always. + +Lazy loading hero images. Above-the-fold images shouldn't be lazy-loaded. Lazy below the fold. + +Eager loading everything. All images load on page load. Use `loading="lazy"` for below-fold. + +No responsive images. Mobile gets the desktop image. Wasteful, slow. Use `srcset` and `sizes`. + +One source resolution. Source is the delivery resolution. Can't generate retina or larger. Source should be 2-3x the largest delivered size. + +Stripping all metadata. Removes alt text, removes attribution. Strip GPS and personal EXIF; keep semantic metadata. + +Random naming. `IMG_4823.jpg`, `Screenshot 2024-03-15.png`. Hard to find later. Use a naming convention. + +No alt text. Accessibility failure, SEO failure. Make alt text required at upload. + +Storage growing unbounded. Old, unused assets pile up. Quarterly cleanup or automated lifecycle policies. + +One person knows the pipeline. When they're out, no one can fix issues or onboard new sources. Document. + +--- + +## Output format + +A media pipeline document includes: + +- Inventory: current asset count, formats, storage +- Pipeline diagram: source → process → deliver → manage with tools at each stage +- Format and size standards: what gets generated, when +- Naming and metadata conventions: with examples +- Workflows by source type: designer, writer, photographer, user +- Performance baseline and targets: weight per page, format adoption, etc. +- Asset library: tool, taxonomy, search, rights tracking +- Monitoring: performance, costs, broken assets +- Roadmap: improvements over the next 1-2 quarters + +--- + +## Reference files + +- [`references/responsive-image-patterns.md`](references/responsive-image-patterns.md): Copy-paste HTML patterns for common responsive image scenarios (hero, content, art-directed, format negotiation), with explanations. diff --git a/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md b/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md new file mode 100644 index 0000000..721f670 --- /dev/null +++ b/dist/pi/.agents/skills/media-asset-management/references/responsive-image-patterns.md @@ -0,0 +1,373 @@ +# Responsive Image Patterns + +Copy-paste HTML patterns for common image scenarios. Each pattern is annotated with what it does and when to use it. + +The principles work across stacks. The HTML is the same whether you're in Next.js, WordPress, Webflow, or vanilla HTML. + +--- + +## Pattern 1: Simple responsive image + +The default for most content images. Same image at different sizes. + +```html +<img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w, + /img/photo-1920.jpg 1920w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +What's happening: +- `src`: fallback for browsers that don't support srcset (rare today, still good practice) +- `srcset`: list of available sizes with their widths +- `sizes`: tells the browser how wide the image will display at different viewport widths +- `width`/`height`: prevents layout shift; the browser reserves space before the image loads +- `loading="lazy"`: delays loading until near the viewport +- `decoding="async"`: doesn't block rendering on this image +- `alt`: accessibility and SEO + +When to use: Most content images, blog post bodies, article illustrations. + +--- + +## Pattern 2: Hero image (above the fold) + +The hero image needs special handling because it's critical to first paint. + +```html +<img + src="/img/hero-1920.jpg" + srcset=" + /img/hero-640.jpg 640w, + /img/hero-960.jpg 960w, + /img/hero-1280.jpg 1280w, + /img/hero-1920.jpg 1920w, + /img/hero-2560.jpg 2560w + " + sizes="100vw" + width="1920" + height="1080" + fetchpriority="high" + decoding="async" + alt="Descriptive alt text"> +``` + +Differences from Pattern 1: +- No `loading="lazy"` (hero must load immediately) +- `fetchpriority="high"` (hint to load this first) +- Larger size options for full-width displays +- `sizes="100vw"` (image takes full viewport width) + +Optionally preload the hero in the document head: + +```html +<link + rel="preload" + as="image" + href="/img/hero-1280.jpg" + imagesrcset="/img/hero-640.jpg 640w, /img/hero-960.jpg 960w, /img/hero-1280.jpg 1280w, /img/hero-1920.jpg 1920w, /img/hero-2560.jpg 2560w" + imagesizes="100vw"> +``` + +This tells the browser to start the request before HTML parsing reaches the `<img>`. + +When to use: The single hero or banner at the top of a page. Don't preload more than one image; it competes with critical resources. + +--- + +## Pattern 3: Format negotiation + +Serve modern formats to browsers that support them, fall back to JPEG. + +```html +<picture> + <source + type="image/avif" + srcset=" + /img/photo-640.avif 640w, + /img/photo-960.avif 960w, + /img/photo-1280.avif 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <source + type="image/webp" + srcset=" + /img/photo-640.webp 640w, + /img/photo-960.webp 960w, + /img/photo-1280.webp 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +What's happening: +- The browser tries each `<source>` in order +- The first one with a supported `type` is used +- The `<img>` is the fallback if no `<source>` matches +- The `<img>` also provides the alt text and dimensions for all formats + +When to use: Whenever your pipeline can produce multiple formats. AVIF is now well-supported; WebP is universal. JPEG is the safe fallback. + +Easier alternative: A modern image CDN can do format negotiation server-side based on the `Accept` header. The HTML stays as Pattern 1; the CDN serves the right format. Often the better approach. + +--- + +## Pattern 4: Art direction (different crops at different breakpoints) + +Sometimes you want a different image (not just a different size) on mobile vs desktop. + +```html +<picture> + <source + media="(max-width: 768px)" + srcset=" + /img/portrait-640.jpg 640w, + /img/portrait-960.jpg 960w + " + sizes="100vw"> + <source + media="(min-width: 769px)" + srcset=" + /img/landscape-1280.jpg 1280w, + /img/landscape-1920.jpg 1920w + " + sizes="100vw"> + <img + src="/img/landscape-1280.jpg" + width="1920" + height="1080" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +What's happening: +- On screens 768px wide or less, use the portrait crop +- On larger screens, use the landscape crop +- Different aspect ratios per device + +When to use: Marketing pages where the image composition matters at each breakpoint. Often for hero images of people or products. + +Caution: Set explicit dimensions to match each crop, or be careful about layout shift between crops. CSS aspect-ratio can help. + +--- + +## Pattern 5: Background images + +For decorative backgrounds set in CSS, use `image-set()` for responsive selection: + +```css +.hero { + background-image: image-set( + url('/img/hero-1280.jpg') 1x, + url('/img/hero-2560.jpg') 2x + ); +} +``` + +For format negotiation in CSS: + +```css +.hero { + background-image: image-set( + url('/img/hero.avif') type('image/avif'), + url('/img/hero.webp') type('image/webp'), + url('/img/hero.jpg') type('image/jpeg') + ); +} +``` + +Note: Background images are decorative. If the image carries meaning, it should be an `<img>` with alt text, not a CSS background. + +--- + +## Pattern 6: SVG (vectors) + +For logos, icons, simple illustrations: + +```html +<img + src="/img/logo.svg" + width="200" + height="40" + alt="Brand name"> +``` + +Or inline for icons (better for theming with CSS): + +```html +<svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true"> + <path d="..."/> +</svg> +``` + +Notes: +- SVG is resolution-independent. No `srcset` needed. +- For decorative icons, use `aria-hidden="true"`. For meaningful icons, provide a label. +- Inline SVG can be styled with CSS. Linked SVG cannot. + +--- + +## Pattern 7: Lazy-loaded video + +Treat video like a heavy image: + +```html +<video + width="1280" + height="720" + poster="/img/video-poster.jpg" + preload="metadata" + controls> + <source src="/video/clip.webm" type="video/webm"> + <source src="/video/clip.mp4" type="video/mp4"> + <track kind="captions" src="/video/clip-captions.vtt" srclang="en" label="English"> + Your browser does not support the video tag. +</video> +``` + +Notes: +- `poster`: image shown before play, sized to match video +- `preload="metadata"`: only loads enough to know duration, not the whole file +- `<track>`: captions for accessibility (always include for non-decorative video) +- Multiple `<source>`: browser picks the first supported format + +For autoplay video (decorative, no audio): + +```html +<video + autoplay + muted + loop + playsinline + poster="/img/poster.jpg" + preload="auto"> + <source src="/video/loop.mp4" type="video/mp4"> +</video> +``` + +`muted` and `playsinline` are required for autoplay on most browsers. Be cautious about autoplay; many users disable it or find it annoying. + +--- + +## Pattern 8: User-uploaded images + +For images uploaded by users (avatars, content), set defensive defaults: + +```html +<img + src="/uploads/avatar-medium.jpg" + width="200" + height="200" + loading="lazy" + decoding="async" + alt="" + onerror="this.style.display='none'"> +``` + +Notes: +- Process uploads through a moderation step before serving (especially for public sites) +- Generate consistent sizes (small, medium, large) +- Strip EXIF (GPS, etc.) for privacy +- Have a fallback (default avatar, broken image hidden) +- alt text from user-provided context where possible + +--- + +## Pattern 9: Image with caption + +Use `<figure>` for semantically grouped image and caption. + +```html +<figure> + <img + src="/img/photo-1280.jpg" + srcset="/img/photo-640.jpg 640w, /img/photo-960.jpg 960w, /img/photo-1280.jpg 1280w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> + <figcaption>Caption visible to all users.</figcaption> +</figure> +``` + +Notes: +- alt text describes the image for users who can't see it +- caption provides context for everyone +- They serve different purposes; both are useful when there's a caption + +--- + +## Anti-patterns + +Lazy-loading the hero image. Above-the-fold images should load immediately. + +Missing width and height. Causes layout shift. Always set. + +Same image, different file extensions. `image.jpg` and `image.JPG` for the same content. Pick one convention. + +Tracking pixels masquerading as images. Use proper analytics, not 1x1 GIFs. + +Decorative images with descriptive alt text. A decorative pattern with `alt="ornamental swirl background"` is noise for screen readers. Use `alt=""` for purely decorative. + +Decorative images with no alt attribute at all. Screen readers may announce the filename. Use `alt=""` (empty, not missing). + +Inline base64 images for non-trivial sizes. Bloats HTML. Use a URL. + +Forgetting captions in non-English contexts. Captions and alt text need translation just like any other content. + +--- + +## Alt text guidelines + +- Decorative: `alt=""` (empty) +- Functional (e.g., a search button icon): describes the action: `alt="Search"` +- Informative: describes the content the user is missing: `alt="Hand holding a coffee cup at a wooden desk"` +- Complex (charts, infographics): brief alt + a fuller description in nearby text or `aria-describedby` + +Alt text should: +- Convey what the image conveys, not what it depicts +- Be concise (typically under 125 characters) +- Not start with "Image of" or "Picture of" (screen readers say that already) +- Include important text that's part of the image + +--- + +## Tooling notes + +Most modern frameworks have an `<Image>` component that wraps these patterns. Examples include Next.js Image, Astro Image, Nuxt Image. They handle: + +- Format negotiation automatically +- Responsive sizes +- Lazy loading defaults +- Width/height enforcement + +If you're using a framework with such a component, prefer it over hand-rolling the HTML. The framework version usually includes optimizations the hand-rolled version misses. + +If you're not using a framework, the patterns here are the right baseline. diff --git a/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md b/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md new file mode 100644 index 0000000..971d963 --- /dev/null +++ b/dist/pi/.agents/skills/monitoring-and-alerting/SKILL.md @@ -0,0 +1,256 @@ +--- +name: monitoring-and-alerting +description: "Design and run a monitoring system for a website or web app. Use this skill when setting up uptime checks, defining SLOs, configuring error tracking, choosing what to alert on, designing on-call rotations, or fixing alert fatigue. Triggers on monitoring, alerts, uptime, SLO, SLA, error rate, on-call, pager, alert fatigue, observability, dashboards, what should we monitor. Also triggers when an incident reveals a gap in monitoring." +category: operations +catalog_summary: "SLO design, uptime checks, alert routing, on-call rotations" +display_order: 5 +--- + +# Monitoring and Alerting + +Decide what to watch, what to alert on, and how to make sure the right person finds out when things break. + +--- + +## When to use + +- Setting up monitoring on a new site or service +- Defining SLOs (service level objectives) and error budgets +- Choosing which alerts page someone vs which go to a quiet channel +- Designing or fixing on-call rotation +- Diagnosing alert fatigue +- Filling monitoring gaps revealed by an incident +- Migrating monitoring vendors + +## When NOT to use + +- Responding to an active incident (use `incident-response`) +- Writing the post-mortem (use `after-action-report`) +- Designing analytics dashboards for product metrics (use `analytics-strategy`) +- Performance optimization itself (use `performance-optimization`) + +--- + +## Required inputs + +- The system you're monitoring (URLs, services, dependencies) +- Existing monitoring tools (uptime, errors, logs, APM) +- Business hours and team timezone(s) +- Who is on-call or available for incidents +- Existing SLOs or success metrics, if any + +--- + +## The framework: 4 layers + +Monitoring works in layers. Skip a layer and you'll miss a class of problems. + +### Layer 1: Availability + +Is the site up? The simplest, most important layer. + +- HTTP checks from multiple regions (every 1-5 minutes) +- DNS resolution checks +- Certificate expiration checks +- Status code checks (alert on 5xx, not just timeout) + +Threshold: any sustained downtime (more than 2 consecutive failed checks) pages. + +### Layer 2: Correctness + +The site is up, but is it serving the right thing? + +- Synthetic checks (a script that loads the homepage, clicks a button, validates expected text) +- Critical user journeys (signup, checkout, search) +- Content presence checks (homepage hasn't gone blank) +- API contract checks (response shape and key fields are present) + +Threshold: failures of critical-path synthetics page. Non-critical page-level synthetics alert during business hours only. + +### Layer 3: Performance + +The site is up and correct, but is it fast enough? + +- Core Web Vitals (LCP, INP, CLS) from real users (RUM) +- Synthetic performance (Lighthouse, WebPageTest, custom) +- API response times (p50, p95, p99) +- Database query times for slow queries +- Dependency response times (third-party APIs) + +Threshold: regressions from baseline (e.g., p95 doubled in 5 minutes). Don't alert on absolute thresholds without baselines. + +### Layer 4: Errors and anomalies + +The site is up, correct, and fast for most, but errors are happening. + +- Error rate (% of requests returning 5xx) +- Client-side error rate (uncaught JS exceptions) +- Log error volume (unexpected spikes) +- Anomaly detection (traffic falling off a cliff) +- Background job failures +- Queue depth + +Threshold: rate-based, not count-based. "Error rate above 1% for 5 minutes" beats "more than 100 errors per minute." + +--- + +## SLOs and error budgets + +A Service Level Objective is the target for reliability. Common form: "99.9% of homepage requests succeed in under 2 seconds, measured over 30 days." + +The components: +- The thing you're measuring (homepage requests) +- The success criterion (returns 2xx in under 2 seconds) +- The target (99.9% of them) +- The window (over 30 days) + +The error budget is the inverse: 0.1% of requests can fail. If you've used the whole budget, slow down on risky changes. + +### Picking SLOs + +Don't aim for 100%. Don't aim for "five nines" (99.999%) unless you really need it. Each nine costs an order of magnitude more. + +\| SLO \| Allowed downtime per month \| +\|---\|---\| +\| 99% \| 7 hours, 18 minutes \| +\| 99.9% \| 43 minutes \| +\| 99.95% \| 21 minutes \| +\| 99.99% \| 4 minutes, 22 seconds \| +\| 99.999% \| 26 seconds \| + +For most marketing sites, 99.9% is plenty. For SaaS, 99.95% is reasonable. Anything higher needs significant infrastructure investment. + +### Using error budgets + +When the budget is healthy, ship aggressively. When the budget is half-spent, slow down. When the budget is exhausted, freeze risky changes until reliability recovers. + +This is what makes SLOs useful: they create a feedback loop between reliability and velocity. + +--- + +## Workflow + +### Step 1: Inventory what's already monitored + +What tools are in place? What checks exist? What dashboards? What alerts? + +Many teams have a tangle of half-configured tools. The first job is the inventory. + +### Step 2: Map the system + +Draw the architecture. Front-end, back-end, database, third-party APIs, queues, workers. Each box is a candidate for monitoring. + +For each box, ask: +- What does "up" mean? +- What does "correct" mean? +- What does "fast" mean? +- What's the most common failure mode? + +### Step 3: Define the SLOs + +Pick 3-5 SLOs. They should be: +- Tied to user-visible behavior (not internal metrics) +- Achievable with current infrastructure +- Measured automatically +- Reviewed at least quarterly + +### Step 4: Set up checks across the 4 layers + +For each box, configure checks at each layer. Some boxes won't have all four; that's fine. + +\| Box \| Availability \| Correctness \| Performance \| Errors \| +\|---\|---\|---\|---\|---\| +\| Homepage \| HTTP check \| Synthetic \| LCP/INP \| JS errors \| +\| Login API \| HTTP check \| Synthetic flow \| p95 latency \| 5xx rate \| + +### Step 5: Decide what pages and what doesn't + +Three tiers: + +1. Page (wakes someone up): site down, critical flow broken, error rate spike, security incident. +2. Notify (during business hours): non-critical synthetic failure, performance regression, slow query, dependency degradation. +3. Log (no notification): anomalies for later review, low-priority warnings, info-level events. + +Anything in tier 1 must be: +- Actionable (the on-call can do something about it) +- Important (it represents real impact) +- Rare (less than 1-2 per week is the goal) + +If tier 1 alerts fire frequently, alert fatigue sets in. People stop responding. + +### Step 6: Configure routing + +Where do alerts go? + +- Tier 1: paging system (e.g., PagerDuty, Opsgenie). Direct to on-call. +- Tier 2: chat channel (Slack, Teams). Tagged with the area. +- Tier 3: dashboard or log only. + +Each tier should have a documented escalation path. If the on-call doesn't ack within 5-15 minutes, escalate. + +### Step 7: Build dashboards + +One dashboard per audience: + +- Real-time ops dashboard: current health, recent alerts, error rates, throughput +- SLO dashboard: SLO status and error budget consumption +- Per-service dashboards: detail for individual services or pages +- Executive dashboard: uptime over weeks/months, key business metrics + +Dashboards are different from alerts. Alerts say "look now." Dashboards say "here's what's happening." + +### Step 8: Run an alert audit + +Every quarter, audit: +- Which alerts fired? Were they actionable? +- Which alerts didn't fire when they should have? +- Are any alerts noisy (more than once a week, low actionability)? +- Are runbooks up to date? +- Have SLOs been met? Any consistently breached? + +Tune the system. Monitoring drifts without active maintenance. + +--- + +## Failure patterns + +Alert on cause, not symptom. "CPU is high" is a cause. "Users are slow" is a symptom. Alert on symptoms; investigate causes. + +Alert without a runbook. If the on-call doesn't know what to do, the alert is useless. Every paging alert needs a runbook (even a one-line one). + +No baselines for "normal." Alerting on "more than 100 errors per minute" sounds reasonable but a busy day might exceed that without anything being wrong. Use rate-based and anomaly-based alerts. + +Single-region monitoring. Your monitoring service in the same region as your site means you'll miss regional outages and you'll get woken up when monitoring itself has issues. + +Monitoring the monitoring. Or rather, not. If your alerting platform is down, who tells you? Most paging services offer their own status feeds. Subscribe. + +Too many tiers of severity. P0/P1/P2/P3/P4 with different SLAs becomes a sorting exercise. Three tiers (page, notify, log) is plenty. + +Synthetics that don't match reality. A synthetic that hits the homepage every minute tests "is the homepage up." It doesn't test "is the actual user flow working." Build synthetics for the journeys that matter. + +Static thresholds that never get tuned. Traffic grows, behavior changes, thresholds set last year are wrong. Review thresholds quarterly. + +On-call rotation with no handoffs. Each new on-call has to figure out the system. Document. Run weekly handoff meetings or async updates. + +Pager fatigue. If on-call is paged more than once or twice a week, something is wrong. Audit the alerts. Reduce, tune, or fix the underlying issues. + +--- + +## Output format + +A monitoring plan includes: + +- System map: what's being monitored +- SLOs: the 3-5 reliability targets +- Checks per layer: availability, correctness, performance, errors +- Alert tiering: what pages, what notifies, what logs +- Routing: where alerts go, escalation paths +- Dashboards: what audiences see +- Runbooks: linked from each paging alert +- Audit cadence: when this gets reviewed + +--- + +## Reference files + +- [`references/slo-design-guide.md`](references/slo-design-guide.md): Detailed walkthrough of writing SLOs, error budget policies, and common SLO mistakes for web services. diff --git a/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md b/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md new file mode 100644 index 0000000..1f5ec49 --- /dev/null +++ b/dist/pi/.agents/skills/monitoring-and-alerting/references/slo-design-guide.md @@ -0,0 +1,246 @@ +# SLO Design Guide + +A walkthrough for designing Service Level Objectives that are useful, achievable, and aligned to user experience. + +--- + +## What an SLO is and isn't + +A Service Level Objective is a target for reliability, expressed as a percentage of "good" events out of all events, measured over a specific time window. + +An SLO is: +- A reliability target the team commits to +- Measured automatically +- Tied to user-visible behavior +- Reviewed and adjusted over time + +An SLO is not: +- A guarantee (that's an SLA, which has contractual consequences) +- A goal to maximize (100% is the wrong target) +- A vanity metric (uptime alone tells you almost nothing) +- Permanent (revise as the system evolves) + +--- + +## The structure of a good SLO + +Every SLO has four components: + +1. The thing being measured (the SLI - Service Level Indicator) +2. The success criterion (what counts as "good") +3. The target (the percentage of events that should be "good") +4. The window (the time period over which to measure) + +Example: + +> "99.9% of homepage requests return a 2xx status code in under 2 seconds, measured over a rolling 30-day window." + +Breaking it down: +- SLI: latency and status of homepage requests +- Good event: 2xx response in under 2 seconds +- Target: 99.9% +- Window: rolling 30 days + +If the system serves 1 million homepage requests in 30 days, this SLO allows 1,000 bad events. That's the error budget. + +--- + +## Picking SLIs + +The SLI is what you measure. Pick SLIs that reflect what users actually experience. + +### Good SLI categories + +Availability: the proportion of valid requests that succeed. +- "% of HTTP requests that return non-5xx" +- "% of API calls that complete without error" + +Latency: the proportion of requests that complete fast enough. +- "% of homepage requests with TTFB under 600ms" +- "% of search queries returning results in under 1 second" + +Quality: the proportion of requests that produce correct results. +- "% of recommendations served from the personalized model (vs fallback)" +- "% of search queries returning at least one result" + +Freshness: the proportion of data that's fresh enough. +- "% of cached pages updated within the last 24 hours" +- "% of analytics data ingested within 15 minutes of event" + +Throughput: the proportion of time the system handles required load. +- "% of minutes during which queue depth was below 1000" + +### Bad SLI patterns + +CPU or memory utilization. These are causes of problems, not symptoms users feel. Don't make them SLIs. + +Number of incidents. Too coarse. One nasty incident can blow it for the whole window. + +Average response time. Averages hide tail latency. P95 or P99 is closer to user experience. + +Internal metrics that don't map to user impact. "Database replica lag." Useful to monitor. Not a great SLO unless it directly affects users. + +--- + +## Picking targets + +Target percentages have specific implications. Here's the practical math: + +\| Target \| Allowed bad time per 30 days \| Allowed bad events per million \| +\|---\|---\|---\| +\| 90% \| 3 days \| 100,000 \| +\| 99% \| 7 hours, 18 minutes \| 10,000 \| +\| 99.9% \| 43 minutes, 30 seconds \| 1,000 \| +\| 99.95% \| 21 minutes, 48 seconds \| 500 \| +\| 99.99% \| 4 minutes, 22 seconds \| 100 \| +\| 99.999% \| 26 seconds \| 10 \| + +Each "9" added is roughly 10x harder. Pick the lowest target that's acceptable to users. + +### How to pick + +1. Look at current performance. What's the system actually achieving? Use that as the floor. +2. Look at user expectations. What do users tolerate? For a marketing site, occasional slow pages are fine. For a payment system, they're not. +3. Look at competitive bar. What do similar services achieve? +4. Pick something achievable but slightly aspirational. If the current achievement is 99.5%, set the SLO at 99.7%. Don't jump to 99.99%. + +### Common mistakes + +Setting the SLO at 100%. Impossible. Wastes infrastructure. Creates false promises. + +Setting the SLO based on what marketing wants to advertise. If marketing says "99.99% uptime!" but engineering can't deliver, the SLO is fiction. + +Setting different SLOs for different teams without coordination. End-to-end user experience depends on all of them. If one team has a 99.9% SLO and another has 99%, the combined experience is worse than either. + +--- + +## Picking windows + +The window affects how SLOs feel. + +Calendar windows: "99.9% in March." Resets at month boundaries. Good for reporting, bad for operating (the budget can be exhausted on March 1 with nothing you can do until April). + +Rolling windows: "99.9% over the last 30 days." Always current. Better for operations because the budget continuously updates. + +Common windows: +- 7 days: too short, noise dominates +- 28-30 days (rolling): the sweet spot for most operations +- 90 days: better for SLAs and stability assessment, worse for fast feedback + +For most teams: 30-day rolling. + +--- + +## Error budgets + +The error budget is `1 - SLO`. If your SLO is 99.9%, your error budget is 0.1%. + +The budget is what allows for change. Every release, every config change, every dependency update consumes some budget. The budget exists so the team can ship. + +### Error budget policy + +A written policy that says what happens when the budget is at different levels. Example: + +\| Budget remaining \| What's allowed \| +\|---\|---\| +\| > 50% \| Normal operation. Ship features, run experiments. \| +\| 25-50% \| Caution. Postpone risky migrations. Prefer smaller releases. \| +\| 10-25% \| Slow down. Only ship reliability fixes and security patches. Defer feature releases. \| +\| < 10% \| Freeze. No non-urgent changes. Focus on reliability. \| + +This is the operationally useful part of SLOs. It connects reliability to product velocity in a measurable way. + +### Burning the budget + +If the budget burns at a rate of, say, 10% in an hour, that's a fast burn. Alert on fast burns: "we'll exhaust the budget in 4 hours at this rate." + +Slow burn alerts catch sustained low-grade issues. Fast burn alerts catch acute incidents. + +### Refilling the budget + +The budget refills as the rolling window moves forward. If today is the last day of a bad month, tomorrow the worst day rolls off and the budget recovers slightly. + +Don't "make up" budget by tightening the SLO temporarily. SLOs are user-facing commitments. Don't move them to make numbers look better. + +--- + +## Multi-tier SLOs + +For complex systems, one SLO isn't enough. Multi-tier SLOs cover different aspects. + +A typical web app might have: + +1. Availability SLO: 99.95% of requests return non-5xx. +2. Latency SLO: 99% of requests complete in under 1 second. +3. Critical flow SLO: 99.9% of checkout flows complete successfully. + +Each has its own error budget and policy. + +For products with multiple tiers of importance, you can also have different SLOs per tier: + +- Critical pages (homepage, checkout): 99.95% +- Standard pages (product, category): 99.9% +- Long-tail pages (search, archive): 99% + +This reflects user impact: a slow checkout matters more than a slow archive page. + +--- + +## Reviewing and revising SLOs + +SLOs aren't set-and-forget. Review: + +- Quarterly: is the SLO still right? Has the system or user expectation changed? +- After major incidents: did the SLO catch it? Should the SLO be tighter? +- After major launches: did the new feature change the math? +- Annually: big-picture review of all SLOs. + +Common revisions: +- Tightening (e.g., 99.9% → 99.95%) when the system has improved and the team can sustain it +- Loosening (e.g., 99.95% → 99.9%) when the previous target was too aggressive (rare, requires justification) +- Splitting an SLO into multiple (e.g., one combined SLO becomes separate availability and latency SLOs) +- Retiring SLOs that no longer reflect what matters + +--- + +## Example: a marketing site + +For a typical marketing site: + +\| SLO \| Target \| Window \| +\|---\|---\|---\| +\| Homepage availability (2xx response) \| 99.9% \| 30-day rolling \| +\| Homepage latency (TTFB < 800ms) \| 95% \| 30-day rolling \| +\| Form submission success \| 99.5% \| 30-day rolling \| +\| Critical-page availability (top 10 pages 2xx) \| 99.9% \| 30-day rolling \| + +Error budget policy: +- Above 50% budget: ship freely +- 10-50% budget: defer risky changes +- Below 10%: freeze non-essential changes + +This is a reasonable starting point. Tune based on actual operating history. + +--- + +## Example: a SaaS product + +For a SaaS product with paying customers: + +\| SLO \| Target \| Window \| +\|---\|---\|---\| +\| API availability (non-5xx) \| 99.95% \| 30-day rolling \| +\| API latency (p95 under 500ms) \| 99% \| 30-day rolling \| +\| Login success \| 99.99% \| 30-day rolling \| +\| Critical action success (e.g., save data) \| 99.95% \| 30-day rolling \| +\| Background job completion within 1 hour \| 99% \| 7-day rolling \| + +Error budget policy is stricter (paying customers have higher expectations). Below 25% budget triggers a slowdown; below 10% triggers a freeze with executive approval needed to override. + +--- + +## When you don't have an SLO yet + +Start small. Pick one SLO that maps to the most important user-facing behavior. Live with it for a quarter. Add more once the team is comfortable. + +Trying to roll out 10 SLOs at once usually fails. Trying to roll out 1 SLO and using it well usually succeeds. diff --git a/dist/pi/.agents/skills/multi-step-form-design/SKILL.md b/dist/pi/.agents/skills/multi-step-form-design/SKILL.md new file mode 100644 index 0000000..5e53791 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/SKILL.md @@ -0,0 +1,332 @@ +--- +name: multi-step-form-design +description: "Designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. Honest about kitchen-sink-single-page (overwhelms before the user starts), progress-theater (steps without genuine staging), and genuinely-staged (each step earns its own page) patterns. Triggers on multi-step form, multi-page form, form wizard, signup wizard, lead form, application form, intake form, configurator, onboarding form. Also triggers when a long form is converting poorly, when an audience is dropping off mid-form, or when a multi-step form is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing multi-step forms that respect cognitive load while maintaining completion intent. Distinguishes kitchen-sink-single-page (overwhelms) from progress-theater (steps without genuine staging) from genuinely-staged (each step earns its own page)" +display_order: 4 +--- + +# Multi-Step Form Design + +A senior growth practitioner's playbook for designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. + +Most multi-step forms are either kitchen-sink-single-pages dressed up as steps or arbitrary chunking that adds friction without adding clarity. The form looks more sophisticated; the completion rate does not move; the audience is no better served than before. + +The multi-step forms that work do something different. Each step represents a coherent unit of cognitive work the user can complete with confidence. Progress indicators reinforce momentum. Conditional logic responds to earlier answers and removes irrelevant fields. The form feels like a guided process, not an obstacle course. + +The voice is the senior growth practitioner who has watched multi-step forms convert at twice the single-page rate and watched them collapse to half. Practical, opinionated about when steps add value and when they add friction, willing to call out arbitrary chunking that does not earn its complexity. + +When to use this skill: scoping a multi-step form for the first time, auditing a long single-page form that converts poorly, deciding when to break a form into steps and when to keep it on one page, or designing the conditional logic that makes the form feel adaptive. + +--- + +## What this skill covers + +This skill spans multi-step form design across acquisition, onboarding, and intake contexts. The growth-tooling distinctions: + +- `lead-magnet-design` covers lead-magnet methodology; forms are one delivery surface for lead magnets but this skill is about the form itself. +- `landing-page-copy` is the page wrapping the form. This skill is the form itself. +- `accessibility-audit` covers accessibility deeply; forms have specific accessibility requirements; this skill references but does not replace accessibility-audit. +- `pm-spec-writing` is the spec for engineers building the form. This skill is about WHAT to build; pm-spec-writing is about communicating it. +- `multi-step-form-design` (this skill) is the form's structure, step architecture, progression, and validation. + +The audience: growth marketers, product marketers, marketing teams designing acquisition forms, in-house teams designing onboarding flows, agencies running form-based growth tooling for clients. + +Out of scope: form-builder platform configurations (those stay implementation-side); deep accessibility audits (covered by `accessibility-audit`); landing-page copy that wraps the form (covered by `landing-page-copy`). + +--- + +## The multi-step decision: when to break into steps vs keep single-page + +Before designing the steps, decide whether the form should be multi-step at all. + +Multi-step earns the build when: + +- The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. +- The fields naturally group into logical categories. Personal info, then situation, then preferences. Steps that reflect real groupings respect cognitive load. +- The audience benefits from progressive commitment. Each step builds investment; the user is more likely to complete after they have engaged with step 2 than they would have been if they had seen step 5's complexity upfront. +- Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page. + +Multi-step does NOT earn the build when: + +- The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. +- The fields do not group naturally. Arbitrary chunking is friction. +- The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. +- The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes; the maintenance overhead is real. + +The decision is not "should the form be multi-step"; it is "is multi-step the right structure for this specific data collection and audience." + +Detail in [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md). + +--- + +## Kitchen-sink-single-page vs progress-theater vs genuinely-staged + +The keystone framing. + +Kitchen-sink-single-page. 30 fields on one page. Overwhelms before the user even starts. Drop-off near 100 percent on anything beyond a contact form. The audience scrolls, sees the length, and leaves. Cost: the form's data collection scope is correct; the structure is wrong; nobody completes it. + +Progress-theater. The form is broken into 5 steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone. Step 4: company. Step 5: role." The progress bar exists; the staging logic does not. Cost: the form feels broken; users reach step 3 wondering why they did not just fill a single page; the completion rate may be slightly better than kitchen-sink but the audience perceives the format as gimmicky. + +Genuinely-staged. Each step represents a coherent unit of cognitive work. The user finishes a step and feels they accomplished something. Steps progress from low-friction to higher-commitment as intent compounds. Cost: the design effort upfront is significant; the maintenance is real; the conversion rate often outperforms both alternatives meaningfully. + +The litmus test. Ask a user who completed step 2 what they just did. Can they describe the unit of work as something coherent ("I gave you the basics about my company") or is the answer atomized ("I typed my company name in a field")? Coherent answers signal genuinely-staged; atomized answers signal progress-theater. + +--- + +## Step architecture: what belongs on each step + +The structure that makes steps coherent. + +The principle. Each step should represent a coherent unit of work from the user's perspective. + +Common step patterns. + +- Identity step. Who the user is. Name, email, basic role. Low-friction; opens the form. +- Context step. What the user's situation is. Company size, industry, current setup. Medium-friction; user shares context. +- Need step. What the user is trying to accomplish. Goals, challenges, priorities. Higher-friction; user articulates intent. +- Detail step. Specifics needed to act on the user's request. Budget, timeline, specific requirements. Highest-friction; saved for last. +- Confirmation step. Review and submit. Summarizes what the user provided. + +Step sequencing principle. Low-friction first; commitment compounds; high-friction at the end after the user has invested. + +Step coherence test. Can each step be described in one sentence as a unit of work? "Step 2: tell us about your company's situation" beats "Step 2: company name, size, industry, and revenue range." + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## Progress indicator design + +When to show progress, what to show, how it builds momentum. + +The principle. Progress indicators reinforce momentum and reduce uncertainty about how much is left. + +Progress indicator patterns. + +- Step counter. "Step 2 of 4." Simple, common, effective for short forms (3-6 steps). +- Progress bar. Visual fill showing percentage complete. Effective for forms with variable-length steps where step count alone is misleading. +- Step list. Named steps shown with the current one highlighted. Useful when the user benefits from seeing what comes next. +- No indicator. Sometimes appropriate for very short forms (2-3 steps) where the indicator overhead exceeds its value. + +Progress indicator failures. + +- Indicator that shifts mid-form. "Step 4 of 5" becomes "Step 4 of 7" because conditional logic added steps. The user feels misled. +- Indicator that hides remaining work. Showing "almost done" when 5 fields remain on the next step. +- Indicator that is decorative without being honest. Progress that looks fast but the next step is the longest one. + +Progress indicator discipline. The indicator must reflect the actual remaining work, not flatter the user. + +Detail in [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md). + +--- + +## Conditional logic + +Branching that responds to earlier answers. + +The principle. Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +Conditional logic patterns. + +- Show or hide fields based on previous answers. "If user selected 'enterprise,' show enterprise-specific fields." +- Skip entire steps. "If user does not have a current CRM, skip the 'CRM details' step." +- Adapt the language. "If user is in healthcare, use healthcare-specific terminology in subsequent fields." +- Adapt the destination. "If user selected 'integration question,' route to the integration team after submission." + +Conditional logic strengths. + +- Removes irrelevant friction. +- Makes the form feel adaptive and intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +Conditional logic risks. + +- Maintenance complexity grows quickly. +- Testing becomes harder (more paths through the form). +- Progress indicators must adapt or honestly disclose the variability. + +The simplicity preference. Add conditional logic only when it produces real value. Conditional logic for decoration adds maintenance without lift. + +Detail in [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md). + +--- + +## Save-and-resume mechanics + +When to offer save-and-resume, how to communicate trust. + +The principle. Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. + +When save-and-resume helps. + +- Forms that require document uploads or specific information (W-2, financial details, technical configurations). +- Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms). +- Forms where the user benefits from coming back to verify or update. + +When save-and-resume does not help. + +- Quick lead-capture forms (under 60 seconds to complete). +- Single-session forms where save-and-resume adds complexity without lift. + +Save-and-resume mechanics. + +- Email-link recovery. "Save your progress; we will email you a link to continue." The most common pattern. +- Account-based persistence. Forms that require account creation persist by default. +- Anonymous-session save. Browser-based save without identification. Lowest friction but limited to the same browser/device. + +Trust communication. Users hesitate to save partial sensitive information. The form should communicate clearly: what is saved, how long it persists, who can access it, how to resume. + +Detail in [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md). + +--- + +## Validation strategy + +Per-step vs end-only. + +Per-step validation. Each step's fields are validated before allowing progression. The user catches errors early. + +Strengths. + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +Weaknesses. + +- Can feel intrusive if validation is too strict on every keystroke. +- May block the user from progressing when they want to revise later. + +End-only validation. All validation runs at submission. + +Strengths. + +- User completes uninterrupted. +- Validation logic is simpler. + +Weaknesses. + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. + +The hybrid pattern. Required-field validation per step; full validation at end. The user gets immediate feedback on critical issues; nuanced validation runs at submission. + +Validation message discipline. + +- Helpful messages: "Phone number must include area code" beats "Invalid phone number." +- Inline placement: errors appear next to the field, not in a banner. +- Specific guidance: "Try a value between 1 and 1000" beats "Out of range." + +Detail in [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon, and how to fix it. + +Step-by-step drop-off tracking. Track the percentage of users who reach each step and the percentage who complete it. The diagnostic data informs which steps need redesign. + +Common drop-off points. + +- First field. User clicked into the form, looked at it, and left. Often signals the form is too long or the value of completing is not clear. +- Mid-form. User abandoned mid-process. Often signals fatigue, sensitive questions, or unclear progress. +- Final submission. User completed all fields but did not submit. Often signals submission anxiety, validation error fear, or unclear next-step. + +Remediation patterns. + +- First-field drop-off. Reduce form length; clarify the value of completing; add social proof or trust signals. +- Mid-form drop-off. Audit the specific step where drop-off concentrates; add progress indicator; reduce field count on that step; reword sensitive questions. +- Final-submission drop-off. Add a confirmation step; reduce final-step requirements; clarify what happens after submission. + +The instrumentation requirement. Without per-step tracking, drop-off remediation is guesswork. Set up tracking before the form launches. + +Detail in [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md). + +--- + +## Form anti-patterns + +Patterns that look like multi-step forms but degrade conversion. + +The kitchen-sink-single-page. 30 fields on one page. Detail in keystone framing. + +The progress-theater form. Steps without genuine staging. Detail in keystone framing. + +The arbitrary-chunking form. Each step has 1-2 fields; user wonders why this is multi-step. + +The hidden-length form. No progress indicator; user does not know how long the form is; abandonment climbs. + +The interrogation-form-with-steps. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The validation-strict form. Validation that rejects too aggressively, frustrating users with valid inputs. + +The mobile-broken form. Form works on desktop, breaks on mobile. + +The trust-broken form. Save-and-resume offered without clear trust communication; user does not save because they distrust persistence. + +The variable-step form. Conditional logic that changes the step count visibly; user feels misled about remaining work. + +Detail in [`references/form-anti-patterns.md`](references/form-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md). + +- "Form converts at 4 percent; we expected 12 percent." Likely too long, or the value of completing is not clear, or the form is mobile-broken. +- "Drop-off concentrates at step 3." Specific-step issue; audit step 3's field count, sensitivity, and clarity. +- "Mobile completion is half of desktop." Mobile design issue; audit form behavior on actual devices. +- "Validation rejects valid inputs." Validation strictness; relax the validation or improve the input formats accepted. +- "Users abandon at submission." Final-step anxiety; add confirmation, reduce final requirements, clarify next step. +- "Save-and-resume is offered but nobody uses it." Trust communication missing; users do not save because they distrust persistence. +- "We added conditional logic; the form feels confusing." Conditional logic complexity outweighs benefit; simplify. +- "We split the form into more steps; conversion did not change." Steps were not coherent; progress-theater pattern. +- "Progress indicator shifts mid-form." Conditional logic added steps unexpectedly; either fix the indicator or fix the conditional logic. + +--- + +## The framework: 12 considerations for multi-step form design + +When designing or auditing a multi-step form, walk these 12 considerations. + +1. The multi-step decision. Is multi-step the right structure for this data and audience, or would single-page serve? +2. Genuinely-staged, not kitchen-sink or progress-theater. Each step represents a coherent unit of work from the user's perspective. +3. Step architecture sound. Identity, context, need, detail, confirmation. Low-friction first; commitment compounds. +4. Progress indicator honest. Reflects actual remaining work; does not shift mid-form. +5. Conditional logic adds value. Removes irrelevant fields without adding maintenance overhead. +6. Save-and-resume mechanics fit the form. Offered when the form length warrants; trust clearly communicated. +7. Validation strategy matched to form. Per-step for required fields; end-only for nuanced validation. +8. Drop-off measurement instrumented. Per-step tracking from launch. +9. Mobile experience tested. Form works on the devices the audience uses. +10. Field count audited. Each field necessary; non-essential fields removed. +11. Final-step clear. Submission action obvious; what happens after submission communicated. +12. Maintenance discipline. Quarterly review of conversion, drop-off, validation, and conditional logic. + +The output of the framework is a multi-step form that respects cognitive load, maintains completion intent, and converts the audience into the action the form is designed to capture. + +--- + +## Reference files + +- [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md) - When to break into steps vs keep single-page. The conditions that warrant the multi-step structure. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. +- [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md) - Step counter, progress bar, step list. When each works. Indicator failures. +- [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md) - Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. +- [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md) - When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. +- [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md) - Per-step vs end-only vs hybrid. Validation message discipline. +- [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md) - Step-by-step tracking. Common drop-off points and remediation patterns. +- [`references/form-anti-patterns.md`](references/form-anti-patterns.md) - The patterns that look like multi-step forms but degrade conversion. +- [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: multi-step forms earn completion when each step earns its place + +The multi-step forms that work as compounding assets are the ones the audience completes without resentment. Not because the form is short. Not because the steps are decorative. Because each step represented a coherent unit of cognitive work the user could complete with confidence, and the cumulative experience felt guided rather than obstructed. + +That is the bar. Below the bar are kitchen-sink-single-pages (overwhelm before the user starts) and progress-theater forms (decorative steps without coherence). Above the bar are genuinely-staged forms where the structure earns its complexity. + +The discipline is in the design choices upstream of the form. The decision to make the form multi-step (or not). The step architecture that makes each step coherent. The progress indicator that reflects honest progress. The conditional logic that removes friction without adding confusion. The validation that catches errors helpfully. The drop-off measurement that informs ongoing improvement. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md b/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md new file mode 100644 index 0000000..7281d88 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/common-multi-step-form-failures.md @@ -0,0 +1,187 @@ +# Common multi-step form failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the form did not convert" or "audiences abandon mid-form" or "we cannot tell what is going wrong." + +--- + +## "Form converts at 4 percent; we expected 12 percent." + +The diagnosis. Likely one of: too long, value of completing not clear, mobile-broken, or the audience-fit is wrong. + +The cure. Audit the form length (`references/multi-step-decision-criteria.md`); audit the value proposition on the landing page (`landing-page-copy`); test on mobile devices; verify the audience matches the form's purpose. + +--- + +## "Drop-off concentrates at step 3." + +The diagnosis. Specific-step issue. Audit step 3's field count, sensitivity, and clarity. + +The cure. Per-step audit. Reduce field count if step 3 has too many; reword sensitive questions; clarify why step 3 is needed; consider whether step 3's content belongs there at all. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## "Mobile completion is half of desktop." + +The diagnosis. Mobile design issue. The form was designed for desktop and breaks on mobile. + +The cure. Mobile-first redesign. Touch-friendly inputs, single question per screen on long steps, sliders sized for thumb interaction, progress indicator visible without scroll. Test on actual devices. + +--- + +## "Validation rejects valid inputs." + +The diagnosis. Validation strictness. Rules are over-specified, rejecting inputs the system can handle. + +The cure. Audit validation rules (`references/validation-strategy-patterns.md`). Email with plus-signs, international phone formats, non-Latin names should all pass. + +--- + +## "Users abandon at submission." + +The diagnosis. Final-step anxiety. The CTA is unclear; the user does not know what happens; the final field requires information they did not have. + +The cure. Clarify the CTA ("Get my PDF" beats "Submit"). Add post-submission preview. Add a confirmation step. Move final-field demands earlier if the user needs time to gather info. + +--- + +## "Save-and-resume is offered but nobody uses it." + +The diagnosis. Trust communication missing. Users do not save because they distrust persistence. + +The cure. Trust copy alongside the save option. What is saved, how long, who can access. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## "We added conditional logic; the form feels confusing." + +The diagnosis. Conditional logic complexity outweighs benefit. Either too many rules or rules that change the user's experience visibly without explanation. + +The cure. Simplify the conditional logic. Remove rules that do not justify their value. Communicate variability if it remains. Detail in `references/conditional-logic-patterns.md`. + +--- + +## "We split the form into more steps; conversion did not change." + +The diagnosis. Steps were not coherent. Progress-theater pattern. Splitting fields without grouping them into meaningful units does not produce the multi-step benefit. + +The cure. Restructure into genuinely-staged steps. Each step should represent a coherent unit of cognitive work. Detail in `references/step-architecture-patterns.md`. + +--- + +## "Progress indicator shifts mid-form." + +The diagnosis. Conditional logic added or removed steps unexpectedly. + +The cure. Either fix the indicator to handle conditional steps honestly, or fix the conditional logic to not change step counts visibly. Detail in `references/progress-indicator-patterns.md`. + +--- + +## "We cannot tell where users abandon." + +The diagnosis. Instrumentation missing. No per-step tracking. + +The cure. Add per-step tracking before any further changes. Without data, remediation is guesswork. Detail in `references/drop-off-measurement-and-remediation.md` (instrumentation requirement). + +--- + +## "Conversion is fine; lead quality is poor." + +The diagnosis. The form is converting the wrong audience. Either the audience-fit on the landing page is broad, or the form does not filter for the audience the team needs. + +The cure. Tighten the audience-fit upstream. The form may need fewer fields (less interrogation) but more qualifying fields (audience-segmentation). Detail in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Conversion was strong at launch; it has declined 30 percent over a year." + +The diagnosis. Form decay. Stale references, broken integrations, validation rules that no longer match reality. + +The cure. Quarterly maintenance audit. Update references, fix broken integrations, refresh validation rules. + +--- + +## "We A/B tested adding a progress indicator; conversion did not change." + +The diagnosis. Either the form was already short enough that an indicator was not needed, or the indicator was poorly designed (dishonest, hidden, or confusing). + +The cure. Audit the indicator's design. If the form is genuinely short (3-4 steps), the indicator may not lift conversion much. If the form is longer, the indicator should help; redesign if it is not. + +--- + +## "The form looks great in QA; users complain it is broken." + +The diagnosis. QA tested with the team's devices and browsers; users have different setups. + +The cure. Cross-browser, cross-device, cross-network testing. Consider real-world conditions (slow connections, older devices, accessibility tools). + +--- + +## "The form's submit button is gray; we cannot figure out why." + +The diagnosis. Validation logic is preventing submission but the error is not surfaced. Common cause: a hidden required field or a cross-field validation that fails silently. + +The cure. Surface all validation errors visibly. Submit button state should follow form state visibly; the user should see why submit is disabled. + +--- + +## "We added save-and-resume; nobody resumes." + +The diagnosis. Either users save but the recovery link does not arrive, or the resume experience is broken, or the form's value did not persist (the user's interest faded). + +The cure. Test the recovery email deliverability. Test the resume experience end-to-end. Consider whether save-and-resume is genuinely needed or whether it is decorative. + +--- + +## "Sales says the form-sourced leads are wrong type." + +The diagnosis. Audience-fit mismatch. The form is converting the wrong segment. + +The cure. Audit the form's qualifying fields and the landing page that drives traffic. Either tighten the audience filter at the landing page, or add qualifying fields to the form that route based on segment. + +--- + +## "We made the form shorter; submissions went up but lead quality went down." + +The diagnosis. The fields removed were qualifying fields. Conversion improved because friction dropped; quality dropped because the qualifying signal was lost. + +The cure. Decide whether quality or quantity matters more. Restore qualifying fields if quality matters; accept the lower quality if volume is the priority. Often the right answer is to restore some fields and accept some conversion impact. + +--- + +## "The form works on Chrome desktop; it crashes on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The form was tested on the team's primary platform. + +The cure. Cross-browser, cross-device testing. The audience uses what they use. + +--- + +## "We translated the form to Spanish; conversion is half what English is." + +The diagnosis. Translation quality, cultural mismatch, or audience-fit issue specific to the Spanish-speaking audience. Often a combination. + +The cure. Audit the translation quality (idiomatic vs literal). Audit cultural assumptions (date formats, phone formats, name conventions). Verify the audience matches. + +--- + +## The pattern across failures + +Most multi-step form failures fall into one of three patterns. + +Pattern 1: The form is the wrong structure. Kitchen-sink-single-page, progress-theater, arbitrary-chunking, hidden-length. The fix is structural. + +Pattern 2: The form does not match the audience or the device. Mobile-broken, validation-strict-against-international-inputs, audience-fit weak. The fix is matching the form to where the audience actually is. + +Pattern 3: The form decays. Stale references, broken integrations, drift in conditional logic, instrumentation drift. The fix is maintenance discipline. + +The metric pattern: form failures often look fine on submission count alone. The signal is in completion rate, drop-off per step, lead quality, and downstream conversion. Programs that track only submission counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (structure, audience-device match, decay). The principle that submission count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md new file mode 100644 index 0000000..c24901b --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/conditional-logic-patterns.md @@ -0,0 +1,270 @@ +# Conditional logic patterns + +Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. + +Conditional logic responds to earlier answers and removes irrelevant fields. Done well, it makes the form feel adaptive and intelligent. Done poorly, it adds maintenance complexity without improving the user experience. + +--- + +## The relevance principle + +Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +The principle's win. A user who answered "no, I do not have a CRM today" should not be asked "what CRM do you use today" three steps later. The conditional logic removes the friction. + +The principle's risk. Conditional logic adds maintenance complexity. Each branch has to be tested. Each branch can break. The simplicity preference: add conditional logic only when it produces real value. + +--- + +## Pattern A: Show or hide fields based on previous answers + +The most common conditional logic pattern. + +How it works. + +- A field appears or disappears based on the answer to an earlier question. +- "If user selected 'enterprise,' show enterprise-specific fields." +- "If user selected 'has current solution,' show 'current solution name' field." + +Example. + +Question: "Do you currently use a CRM?" +- Yes → show field "Which CRM do you use today?" +- No → hide that field; show "What is your current process for managing customer data?" + +The form adapts to the user's situation in real time. + +Strengths. + +- Removes irrelevant fields. +- Makes the form feel intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +Weaknesses. + +- Each branch needs testing. +- Late additions to the form can break conditional logic in unexpected ways. + +When to use. When showing all fields would be confusing or when irrelevant fields cause significant drop-off. + +--- + +## Pattern B: Skip entire steps + +Conditional logic at the step level. + +How it works. + +- Based on early answers, an entire step is skipped or included. +- "If user does not have a current CRM, skip the 'CRM details' step entirely." +- "If user is in healthcare, include the 'compliance requirements' step." + +Strengths. + +- Removes whole sections of irrelevant content. +- Form length adapts to the user. + +Weaknesses. + +- Progress indicators must adapt or honestly disclose variability. +- The user may notice the form's variability and feel confused. + +When to use. When entire categories of fields are irrelevant to some users (e.g., enterprise-only fields for non-enterprise users). + +--- + +## Pattern C: Adapt the language + +Conditional logic that changes terminology based on user context. + +How it works. + +- The form's wording adapts to the user's industry, role, or context. +- "If user is in healthcare, use 'patient' terminology in subsequent fields." +- "If user is technical, use technical terms; if non-technical, use plain language." + +Strengths. + +- Form feels personalized. +- Reduces cognitive load on the user (they see terminology that matches their context). + +Weaknesses. + +- Significantly more copy to maintain. +- Risk of inconsistent or awkward language. + +When to use. When the audience spans contexts where terminology genuinely differs (B2C vs B2B, technical vs non-technical, regulated vs unregulated industries). + +--- + +## Pattern D: Adapt the destination + +Conditional logic that affects what happens after submission. + +How it works. + +- Based on answers, the form routes to different teams or triggers different follow-ups. +- "If user selected 'integration question,' route to the integration team after submission." +- "If user selected 'enterprise,' trigger an enterprise-sales follow-up sequence." + +Strengths. + +- The user gets matched to the right team or sequence. +- Sales and support efficiency improve. + +Weaknesses. + +- Routing complexity grows; failure modes (wrong team, missed routing) increase. +- The user does not see the routing logic; mistakes are invisible to the user but visible in downstream impact. + +When to use. When the form serves multiple downstream paths and the routing materially affects the user's experience. + +--- + +## Pattern E: Branching forms + +Different paths through the form for different users. + +How it works. + +- Based on early answers, the user takes a different path entirely. +- "If user selects 'individual,' show the individual flow; if 'team,' show the team flow." + +Strengths. + +- Highly tailored experience. +- Each user only sees fields relevant to them. + +Weaknesses. + +- Significantly more complex to build and test. +- Hard to compare paths because users took different forms. +- Maintenance is hard. + +When to use. When the audience genuinely splits into distinct groups that need fundamentally different forms. Use sparingly. + +--- + +## The simplicity preference + +Add conditional logic only when it produces real value. + +The discipline. For each piece of conditional logic, ask: +- Does this remove genuine friction? +- Is the maintenance cost justified by the friction removed? +- Could a simpler approach (single-page with sectioned design) achieve the same goal? + +The over-conditional form. A form with 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively, the form is fragile and hard to maintain. + +The cure. Audit conditional logic periodically. Remove rules that do not justify their maintenance overhead. + +--- + +## Conditional logic and progress indicators + +The interaction matters. + +The challenge. A form with conditional steps may have variable total step count. The progress indicator must accommodate. + +Approaches. + +- Variable indicator. "Step 2 of 5-7" or "Step 2 (about halfway)." Communicates the variability. +- Range indicator. "Step 2 of about 5." Approximate but honest. +- Dynamic indicator. Updates as the user's answers determine the path. Risk of feeling unstable. +- Step-list indicator. Shows all possible steps; current step highlighted. Variability visible upfront. + +The discipline. Choose an approach that does not lie about progress. + +--- + +## Conditional logic testing + +Test every branch of conditional logic. + +The challenge. A form with 5 conditional rules has 32 possible paths through the form. Testing all paths is infeasible at scale; testing critical paths is the discipline. + +Critical paths. + +- The most common path (most frequent user type). +- Each conditional rule's branch (one path that triggers it, one that does not). +- Edge cases (combinations that could produce unexpected behavior). + +Testing methods. + +- Manual testing. Walk through critical paths. +- Automated testing. Programmatic tests for each branch. +- User testing. Watch users complete the form; surface confusion or paths that break. + +Production monitoring. Track which paths users take. Sudden shifts may indicate logic issues. + +--- + +## Conditional logic and analytics + +Track which conditional branches trigger. + +Why. Understanding which branches are common informs maintenance priorities. A branch nobody triggers may not be worth maintaining; a branch everyone triggers may not need to be conditional. + +The metric. Per-branch trigger rate. Per-branch conversion rate. + +The discipline. Periodically review the data. Retire conditional rules that do not pay off. + +--- + +## Conditional logic and form maintenance + +Conditional logic decays. + +What decays. + +- Rules that point to fields that have been renamed or removed. +- Rules that produce paths now unused as the audience shifts. +- Rules whose triggering questions have been reworded. + +Maintenance cadence. Quarterly audit alongside the broader form audit. + +The drift indicator. Bug reports about specific paths failing; analytics showing unexpected branching behavior; testing surfaces broken rules. + +--- + +## Common conditional logic failures + +Hidden complexity. Many rules silently affecting many fields; the form's behavior is hard to reason about. + +Unintended interactions. Two rules that work individually but conflict when combined. + +Stale rules. Rules that point to fields no longer in the form. + +Dead branches. Conditional paths nobody triggers; maintenance overhead with no payoff. + +Indicator-rule mismatch. Progress indicator that does not handle conditional step count. + +Untested edge cases. Unusual answer combinations that produce broken paths. + +Rule-driven layout shifts. Fields appearing and disappearing causing visual jumpiness. + +Over-conditional forms. 25+ rules across the form; the maintenance burden exceeds the friction-reduction value. + +--- + +## When NOT to use conditional logic + +Some situations work better without conditional logic. + +Short forms. Adding conditional logic to a 5-field form rarely justifies the complexity. + +Forms with stable audiences. When everyone takes roughly the same path, conditional logic adds variability without value. + +Forms in early stages. A new form benefits from simplicity before adding complexity. Launch simple; add conditional logic when data shows where it would help. + +Forms with high maintenance constraints. Teams that cannot maintain complex forms should default to simpler designs. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. The simplicity preference. Conditional logic and progress indicators. Conditional logic testing. Conditional logic and analytics. Maintenance considerations. Common failures. When NOT to use conditional logic. + +## Implementation choices that stay internal + +Specific conditional rules for specific forms. Specific tooling for rule implementation and testing. The team's audit calendars and rule-retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md b/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md new file mode 100644 index 0000000..7f88000 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md @@ -0,0 +1,263 @@ +# Drop-off measurement and remediation + +Step-by-step tracking. Common drop-off points and remediation patterns. + +Drop-off is where the form fails. Measuring drop-off per step is the diagnostic that informs every other improvement. Without per-step tracking, drop-off remediation is guesswork. + +--- + +## The instrumentation requirement + +Set up per-step tracking before the form launches. + +The minimum tracking. + +- Step start. User landed on this step. +- Step completion. User completed this step (clicked Next). +- Step abandonment. User left without completing. + +The derived metrics. + +- Step completion rate. Of users who reached this step, what percentage completed it? +- Step drop-off rate. Of users who reached this step, what percentage abandoned at this step? +- Funnel completion rate. Of users who started the form, what percentage submitted? + +Why instrumentation matters. Drop-off remediation requires knowing where users abandon. Aggregate "the form converts at 8 percent" tells you something is wrong; per-step data tells you where. + +--- + +## Common drop-off points + +Three patterns recur across multi-step forms. + +First-field drop-off. User clicked into the form, looked at it, and left at the first field. + +Common causes. +- Form is too long; user saw the length and bounced. +- The value of completing is not clear; user does not know what they get. +- Form is mobile-broken; user could not interact. +- Form looks suspicious or untrustworthy. + +Mid-form drop-off. User abandoned partway through. + +Common causes. +- Fatigue; the form is too long and the user lost interest. +- Sensitive question they did not want to answer. +- Confusion about what is being asked. +- Loading delay or technical issue. +- The form's value did not justify the continued effort. + +Final-submission drop-off. User completed all fields but did not submit. + +Common causes. +- Submission anxiety; the user is not sure what happens next. +- Validation errors at submission lost them. +- The submission CTA is not clear. +- Final field requires information they did not have ready. + +--- + +## Remediation: first-field drop-off + +When users abandon at the first field. + +Diagnostic questions. + +- Is the form's value proposition clear at the start? +- Is the form length visible (creating bounce-on-length behavior)? +- Does the form work on mobile? +- Are trust signals present (privacy policy, security badges where appropriate)? + +Remediation patterns. + +- Clarify the value. "Get a personalized PDF in 5 minutes" beats "Fill out this form." +- Hide the length. Multi-step forms hide subsequent steps; the user does not see "this will take 20 minutes" upfront. +- Add social proof. "Trusted by 5000 teams" or "Used by [recognizable customer]" reduces hesitation. +- Add trust signals. Privacy assurance, security indicators, or testimonial near the form. +- Reduce form to single page. Sometimes the right answer is to revert from multi-step to single-page. + +The diagnostic test. A/B test variations. The treatment that improves first-field completion validates the diagnosis. + +--- + +## Remediation: mid-form drop-off + +When users abandon partway through. + +Diagnostic. + +- Which specific step has the highest drop-off? +- Are there sensitive questions on that step? +- How long does that step take to complete? +- Is the step's relevance clear? + +Remediation patterns. + +- Reduce field count on the high-drop-off step. Audit each field; remove non-essential fields. +- Reword sensitive questions. "How much do you spend on this today" beats "What is your annual budget?" Soft framing reduces abandonment. +- Add progress indicator if missing. Users abandon less when they know how much remains. +- Add encouragement at the high-drop-off step. "You are halfway there; just a few more questions to get your personalized result." +- Restructure the step architecture. If step 3 is a drop-off black hole, the architecture may be wrong; reconsider whether step 3's content belongs there at all. + +The diagnostic test. Watch real users complete the form (usability testing). The behavior often reveals the cause. + +--- + +## Remediation: final-submission drop-off + +When users complete fields but do not submit. + +Diagnostic. + +- Is the submission CTA clear? +- Does the user know what happens after submission? +- Are there validation errors at submission? +- Is the final field demanding information they did not have ready? + +Remediation patterns. + +- Clarify the submission CTA. "Get my personalized PDF" beats "Submit." The CTA should describe what the user gets. +- Add post-submission preview. "When you submit, we will email you within 5 minutes with..." sets expectations. +- Move final-field demands earlier. If the final field requires hard-to-find information, move it earlier so users gather it during the form. +- Add a confirmation step. A review-and-submit step where the user verifies their inputs reduces submission anxiety. +- Validation pre-submission. Surface errors before the user clicks Submit; do not let submission fail with surprise errors. + +--- + +## Tracking conditional-logic paths + +Multi-step forms with conditional logic have multiple paths through the form. + +Per-path tracking. + +- Tag each user's path through the form. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +Path-specific remediation. + +- A path that drops off at step 4 may need step-4 redesign for users on that path. +- A path that drops off rarely may not need attention. + +The instrumentation challenge. Conditional-logic paths multiply quickly. Track at the granularity that informs decisions, not at the granularity that overwhelms. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +Segment-level tracking. + +- Tag users by source, device, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +Common segment patterns. + +- Mobile users drop off more at long steps; desktop users push through. +- Paid-traffic users drop off earlier than organic; the audience-fit may be weaker. +- New visitors drop off more than returning visitors; trust matters. + +Remediation by segment. Sometimes the right answer is segment-specific. Mobile users may benefit from a shorter form variant; paid traffic may benefit from stronger trust signals. + +--- + +## Drop-off and time-of-completion + +Some drop-off correlates with how long the form takes. + +Time-to-complete tracking. + +- Average time per step. +- Total time across the form. +- Time-to-completion distribution. + +Patterns. + +- Forms taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Distribution skew (some users fast, some users slow) often signals usability issues that affect the slow users. + +Remediation by time. Forms taking too long should be shortened; steps taking too long should be split or simplified. + +--- + +## Drop-off audit cadence + +How often to audit drop-off data. + +Weekly review. For high-volume forms or recently launched forms. Catches regressions and informs rapid iteration. + +Monthly review. For stable forms. Tracks trends and surfaces gradual decay. + +Quarterly review. For all active forms as part of the broader form audit. + +Triggered review. When form structure changes, when traffic source shifts, or when conversion drops. Ad-hoc reviews catch specific issues. + +The cadence depends on traffic volume and the form's importance. High-traffic forms warrant more frequent attention. + +--- + +## A/B testing for drop-off remediation + +Test remediation hypotheses rather than guessing. + +The discipline. Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall conversion. + +Common test types. + +- Form length: shorter vs longer. +- Step count: fewer vs more steps. +- Field count: fewer vs more fields per step. +- Validation strictness: stricter vs looser. +- Progress indicator: present vs absent. +- Trust signals: present vs absent. + +Test discipline. + +- One treatment variable per test. +- Long enough to capture statistical significance. +- Measure both the targeted metric and downstream metrics. + +The data informs which remediation actually moves the metric. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +The signal. The wrong audience self-selecting out is honest filtering. A multi-step form that drops 60 percent of visitors but produces 5x the qualified leads vs a single-page form is doing its job. + +The discipline. Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream metrics (lead quality, conversion to next step) reveal which is happening. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. Sometimes the right answer is to accept higher drop-off in exchange for higher qualification. + +--- + +## Common measurement failures + +No instrumentation. Form launched without per-step tracking; drop-off data unavailable. + +Aggregate-only tracking. Conversion rate tracked but not step-by-step; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; field renames or step changes broke the tracking. + +Confounded data. Multiple changes deployed simultaneously; cannot attribute conversion change to any one change. + +Vanity metrics. Tracking number of starts without tracking completion; the high-volume forms look successful even when conversion is poor. + +Segment-blind tracking. Aggregate data hides segment-specific issues. + +Time-blind tracking. No data on time-to-complete; cannot diagnose fatigue-driven drop-off. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points (first-field, mid-form, final-submission) with diagnoses and remediation patterns. Tracking conditional-logic paths. Drop-off and audience segmentation. Drop-off and time-of-completion. Audit cadence. A/B testing for drop-off remediation. When drop-off is signal not failure. Common measurement failures. + +## Implementation choices that stay internal + +Specific drop-off baselines for specific forms. Specific tooling for tracking and analysis. Specific A/B test designs and treatments. The team's audit calendars. These vary by team and form. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md new file mode 100644 index 0000000..999e4c7 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/form-anti-patterns.md @@ -0,0 +1,224 @@ +# Form anti-patterns + +The patterns that look like multi-step forms but degrade conversion. Anti-patterns are easy to ship; the cost shows up in completion rates, lead quality, and brand reputation over time. + +--- + +## The kitchen-sink-single-page + +The pattern. 30 fields on one page. Overwhelms before the user starts. + +The signal. First-field drop-off near 100 percent on anything beyond a contact form. Users scroll, see the length, and leave. + +The cost. The form's data collection is correct; the structure is wrong; nobody completes it. + +The cure. Multi-step the form; group fields into coherent steps. Detail in `references/multi-step-decision-criteria.md` and `references/step-architecture-patterns.md`. + +--- + +## The progress-theater form + +The pattern. The form is broken into steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone." + +The signal. Completion rate marginally better than kitchen-sink; users feel the form is gimmicky; some abandon mid-form because each step feels pointless. + +The cost. The build effort produced a form that is no better than the alternative. The audience perceives the format as decorative. + +The cure. Restructure into genuinely-staged steps. Detail in `references/step-architecture-patterns.md`. + +--- + +## The arbitrary-chunking form + +The pattern. Each step has 1-2 fields; the user wonders why this is multi-step. + +The signal. Quick completions but high abandonment; the format adds friction without value. + +The cost. The user perceives the form as gimmicky; trust degrades. + +The cure. Either consolidate to single-page (if the form has only 4-6 fields) or expand the staging to coherent units (if the form has more fields that group naturally). + +--- + +## The hidden-length form + +The pattern. No progress indicator; the user does not know how long the form is. + +The signal. Mid-form drop-off climbs as users lose patience; abandonment correlates with time spent. + +The cost. Users who would have completed if they knew the length abandon out of uncertainty. + +The cure. Add an honest progress indicator. Detail in `references/progress-indicator-patterns.md`. + +--- + +## The interrogation-form-with-steps + +The pattern. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The signal. Drop-off at every step; cumulative completion rate is poor; the form earns "interrogation" reputation. + +The cost. The audience that completes is over-disclosed and may resent the friction; the audience that does not complete walks away with a negative impression. + +The cure. Audit the field set. Remove fields that are not necessary for the form's purpose. The right field count is often half what teams initially design. + +--- + +## The validation-strict form + +The pattern. Validation rejects valid inputs because the rules are over-specified. Email validation rejects plus-sign aliases; phone validation rejects international formats; name validation rejects non-Latin characters. + +The signal. Users with valid but unusual inputs abandon when validation fails. Reports of "the form would not let me submit." + +The cost. The form filters out valid users. The team perceives the form as working because submissions look clean; the team does not see the audience that could not get past validation. + +The cure. Audit validation rules against actual business requirements. Detail in `references/validation-strategy-patterns.md`. + +--- + +## The mobile-broken form + +The pattern. Form works on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; touch targets too small. + +The signal. Mobile completion drops to half of desktop or worse. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. + +--- + +## The trust-broken form + +The pattern. Save-and-resume offered without clear trust communication. Users do not save because they distrust persistence. + +The signal. Save-rate is low; users abandon mid-form rather than save. + +The cost. The save mechanism's investment produces no value; the audience that would have saved instead leaves permanently. + +The cure. Trust communication. What is saved, what is not, how long it persists, who can access it. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## The variable-step form + +The pattern. Conditional logic that changes the step count visibly. "Step 4 of 5" becomes "Step 4 of 7" mid-form. + +The signal. Users feel misled; abandonment climbs at the moment the indicator shifts. + +The cost. Trust damage. The user trusted the indicator; the indicator lied. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). Detail in `references/progress-indicator-patterns.md`. + +--- + +## The submission-anxiety form + +The pattern. The submit button is unclear, or the user does not know what happens after submission, or the final step demands information they did not have ready. + +The signal. Final-submission drop-off is high; users completed all fields but did not submit. + +The cost. The form gets near-completion and loses the conversion at the last step. + +The cure. Clear submission CTA, explicit post-submission preview, optional confirmation step. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## The popup-interrupted form + +The pattern. The user is mid-form; a popup appears (newsletter signup, chat invitation, special offer). The user's flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about the interruption. + +The cost. The form's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Suppress popups during form completion. Save promotional content for after submission or for the next visit. + +--- + +## The reset-on-error form + +The pattern. The user submits; validation fails; the form resets, losing the user's inputs. + +The signal. Users who hit the error do not retry; they leave. + +The cost. The form treats errors punitively. Trust collapses. + +The cure. Preserve inputs on error. Show the error inline; let the user fix and resubmit without re-entering everything. + +--- + +## The slow-validation form + +The pattern. Real-time validation that lags. The user types; validation runs; the form feels sluggish. + +The signal. Users feel the form is slow; abandonment climbs at long-validation steps. + +The cost. The form's perceived performance damages the brand. + +The cure. Move validation to on-blur (when the user leaves the field) instead of on every keystroke. Reserve real-time validation for instant checks (format, character count). + +--- + +## The incompatible-with-autofill form + +The pattern. Form does not support browser autofill. The user has to type every field manually. + +The signal. Mobile completion is worse than desktop; users with password managers abandon. + +The cost. The form treats users as if autofill does not exist. Friction without justification. + +The cure. Support standard autofill attributes. Use semantic HTML input types. Test with browser autofill enabled. + +--- + +## The save-but-lose-on-resume form + +The pattern. Save-and-resume offered; user saves; resume returns the user to the start of the form, losing their progress. + +The signal. Resume rate is high (users click the recovery link) but completion rate from resume is low (users abandon when they see they have to redo work). + +The cost. The save mechanism's apparent value disappears at resume; trust collapses worse than if save had not been offered. + +The cure. Test the resume experience. Verify that resuming returns the user to their actual progress with inputs preserved. Detail in `references/save-and-resume-mechanics.md` (resume experience section). + +--- + +## The over-conditional form + +The pattern. 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively the form is fragile and hard to maintain. + +The signal. Bug reports about specific paths failing; testing surfaces broken rules; conditional logic decays unnoticed. + +The cost. Maintenance burden compounds. Form behavior becomes hard to reason about. + +The cure. Audit conditional logic. Remove rules that do not justify their maintenance overhead. Detail in `references/conditional-logic-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active form, looking specifically for these anti-patterns. + +Audit questions per form. + +- Does the form have natural step groupings (anti-pattern check: progress-theater, arbitrary-chunking)? +- Is the progress indicator honest and stable (anti-pattern check: hidden-length, variable-step)? +- Does each field affect the form's outcome (anti-pattern check: interrogation-form)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Does the form work on mobile (anti-pattern check: mobile-broken)? +- Is save-and-resume tested end-to-end (anti-pattern check: save-but-lose-on-resume, trust-broken)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is conditional logic maintained (anti-pattern check: over-conditional)? + +The retire decision. Anti-pattern forms often warrant retirement or redesign. Maintaining broken forms costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md b/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md new file mode 100644 index 0000000..92ced61 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/multi-step-decision-criteria.md @@ -0,0 +1,159 @@ +# Multi-step decision criteria + +When to break a form into steps vs keep it on a single page. The conditions that warrant the multi-step structure, and the funnels where multi-step adds friction without lift. + +A multi-step form is a meaningful build. Step architecture, progress indicators, conditional logic, validation, save-and-resume, drop-off instrumentation. The multi-step form earns this investment only when specific conditions are present. + +--- + +## When multi-step earns the build + +Five conditions that, when present, make multi-step the right structure. + +The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. The user scrolls, sees the length, and leaves. Multi-step breaks the visual length into manageable pieces. + +The fields naturally group into logical categories. Personal info, then situation, then preferences, then specifics. Steps that reflect real groupings respect cognitive load. Arbitrary chunking does not. + +The audience benefits from progressive commitment. Each step builds investment. The user is more likely to complete after engaging with step 2 than they would have been if they had seen step 5's complexity upfront. + +Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page; multi-step makes the adaptation feel natural. + +The success metric warrants the build. Higher completion rate, lower drop-off, better lead quality, faster review for the receiving team. Without a defined success metric, the build is hard to justify. + +When all five are present, multi-step is a strong structure. When two or fewer are present, single-page often serves better. + +--- + +## When multi-step does NOT earn the build + +Funnels where multi-step is the wrong structure. + +The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. Multi-step adds friction (step transitions, progress indicators, save-and-resume mechanics) without adding clarity. + +The fields do not group naturally. Arbitrary chunking is friction. "Step 1: name. Step 2: email. Step 3: phone." The user wonders why this is multi-step and the question itself signals friction. + +The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. The multi-step format implies "this will take a while," which depresses high-intent users. + +The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes (conditional logic bugs, progress indicator drift, validation issues across steps). The maintenance overhead is real; teams that cannot commit to it should choose single-page. + +The form is a follow-up to a hot conversation. A demo-request form right after a sales call should be quick. Multi-step here adds friction the audience is not ready for. + +The honest assessment matters more than the default. "Should the form be multi-step" is not the question. "Is multi-step the right structure for this specific data collection and audience" is. + +--- + +## The opportunity-cost frame + +A multi-step form is meaningful work. Account for the cost honestly. + +The build cost. Step architecture, progress indicators, conditional logic, save-and-resume, validation across steps, drop-off instrumentation. A meaningful multi-step form often takes 30-80 engineering hours plus design. + +The maintenance cost. Steps decay as the brand evolves; conditional logic bugs surface; progress indicators need updating. Quarterly review and maintenance run 2-6 hours per active form. + +The opportunity cost. What else could the team have built? A simpler form that converts adequately, a different growth-tooling investment, a content piece. The multi-step form's success has to clear the bar of those alternatives. + +The decision frame. The multi-step form earns investment when it produces more conversion than the single-page alternative, accounting for the full cost of build plus maintenance. + +--- + +## The grouping precondition + +Without natural field groupings, multi-step is arbitrary. + +The check. Can the fields be grouped into 3-5 coherent categories? Each category representing a unit of cognitive work the user can describe in one sentence? + +If yes, multi-step has natural step boundaries. + +If no (the fields do not group; the only structure is "first half" and "second half"), multi-step will feel arbitrary. Either restructure the data collection (some fields may not be needed) or choose single-page. + +Examples of natural groupings. + +- Identity (name, email, role) + Context (company size, industry, current setup) + Need (goal, challenge, timeline) + Confirmation. +- Personal info + Loan details + Property details + Financial verification + Submission (mortgage application). +- Account info + Use case + Plan selection + Payment + Confirmation (signup wizard). + +Examples of forced groupings. + +- Page 1 (name, email, phone) + Page 2 (company, role, source, industry, size). The page break is arbitrary; nothing groups these fields meaningfully. +- Page 1 (most fields) + Page 2 (one final field). The split is purely decorative. + +The discipline. If the team cannot articulate the unit of work each step represents, the steps are arbitrary; either rework the steps or use single-page. + +--- + +## The decision worked example + +A B2B SaaS company considering whether to make a "Talk to sales" form multi-step. + +Conditions check. + +- Field count: 12 fields (name, work email, company name, company size, industry, role, current solution, primary use case, timeline, budget range, source attribution, additional context). Above the 8-10 threshold; multi-step is on the table. +- Natural groupings: yes. Identity (name, email, role), company context (name, size, industry), current state (current solution, use case), buying intent (timeline, budget), additional (source, context). 5 natural groups. +- Progressive commitment: yes. The audience giving budget at the end after engaging with the early steps is more likely to give it than if asked upfront. +- Conditional logic value: yes. If the audience selects "evaluating" timeline, additional fields appear; if "active project," different additional fields appear. +- Success metric: defined. Conversion rate to submission, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo within 21 days. + +Decision. Build multi-step. The conditions warrant it. + +Step architecture. 5 steps: Identity, Company, Current State, Buying Intent, Submission Confirmation. + +Maintenance commitment. Quarterly audit of conversion, drop-off per step, and conditional logic. + +The decision was not "should we make this multi-step" but "given these conditions, this is the multi-step structure to build." + +--- + +## The single-page worked example + +The same B2B SaaS company considering whether to make a "Subscribe to newsletter" form multi-step. + +Conditions check. + +- Field count: 2 fields (email, name). Below the 8-10 threshold. +- Natural groupings: no. Two fields do not group. +- Progressive commitment: no. The audience subscribing benefits from speed. +- Conditional logic value: no. No branching needed. +- Success metric: simple conversion rate. + +Decision. Single-page. Multi-step would add friction without value. + +The decision was "what is the right structure" and the answer was single-page even though multi-step was nominally available. + +--- + +## The hybrid pattern + +Some forms work best with a "main" single-page form plus one optional follow-up step. + +The pattern. A short single-page form (3-5 fields) gets the user committed; an optional follow-up appears after submission for users who want personalization. + +When this works. When the primary action is fast (signup, lead-capture) but a richer follow-up benefits some users. + +When this does not work. When the follow-up has to be required for the primary action to be useful. + +The hybrid avoids both kitchen-sink-single-page and forced multi-step. It serves the speed-seeking audience and the depth-seeking audience separately. + +--- + +## When to retire a multi-step form (or convert to single-page) + +Multi-step forms can become wrong as the form evolves. + +Retire-or-convert when: + +- Field count has dropped below 6 over time as fields were removed. +- Conditional logic has been simplified out, leaving the steps with no real differentiation. +- Drop-off concentrates uniformly across steps, suggesting the staging is not working. +- A simpler single-page form might convert better. + +The conversion-to-single-page move. Sometimes the right answer is to revert. The multi-step format earned the build at one point; conditions changed; single-page is now better. Honest reversion is part of the discipline. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant multi-step. The opportunity-cost frame. The grouping precondition. The decision worked example. The single-page worked example. The hybrid pattern. The retire-or-convert decision. + +## Implementation choices that stay internal + +Specific multi-step decisions for specific forms. The team's capacity benchmarks for build and maintenance. Specific tooling for form engineering. Specific success-metric definitions and baselines. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md new file mode 100644 index 0000000..2051213 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/progress-indicator-patterns.md @@ -0,0 +1,289 @@ +# Progress indicator patterns + +Step counter, progress bar, step list. When each works. Indicator failures. + +The progress indicator reinforces momentum and reduces uncertainty about how much is left. Bad indicators flatter or mislead; good indicators reflect honest progress. + +--- + +## The honesty principle + +The progress indicator must reflect actual remaining work. Indicators that flatter the user or hide remaining complexity break trust. + +The honest indicator. "Step 3 of 5" when there are exactly 5 steps and the user is on step 3. + +The dishonest indicator. + +- "Almost done" when 5 fields remain on the next step. +- Progress bar that fills to 80 percent when 50 percent of fields remain. +- Step counter that shifts from "5 of 7" to "5 of 9" because conditional logic added steps. + +The honesty discipline. Match the indicator to the actual work; do not flatter; communicate variability when it exists. + +--- + +## Pattern A: Step counter + +"Step 2 of 4." Simple, common, effective for short forms. + +How it works. + +- The current step number is shown. +- The total step count is shown. +- The format is consistent across the form. + +Strengths. + +- Easy to implement. +- Easy to understand. +- Compact. + +Weaknesses. + +- Does not reflect within-step progress. +- Misleading when step lengths vary significantly. +- Breaks if conditional logic changes the total step count. + +When to use. Forms with 3-6 steps where step lengths are roughly similar. + +--- + +## Pattern B: Progress bar + +Visual fill showing percentage complete. + +How it works. + +- A bar fills from left to right (or follows other visual progression). +- The fill represents percentage of fields completed (or percentage of weight in some weighted scheme). +- Optionally includes a percentage label. + +Strengths. + +- Reflects continuous progress. +- Handles variable-length steps better than step counter. +- Visually engaging. + +Weaknesses. + +- More complex to design and implement. +- Risk of dishonest fill (bar fills fast, last 10 percent represents most of the remaining work). + +When to use. Forms with variable step lengths or where the user benefits from continuous-progress signal. + +--- + +## Pattern C: Step list + +Named steps shown with the current one highlighted. + +How it works. + +- All step names visible (often in a sidebar or header). +- Current step highlighted. +- Completed steps marked (checkmark or different color). +- Future steps indicated. + +Strengths. + +- Shows the user the full form path. +- Reduces uncertainty about what is coming. +- Lets the user navigate back to specific steps. + +Weaknesses. + +- Takes more screen real estate. +- Can overwhelm if there are many steps. +- Forces the form to commit to step names upfront. + +When to use. Forms with 3-7 well-named steps where the user benefits from seeing the structure. + +--- + +## Pattern D: No indicator + +Sometimes appropriate for very short forms. + +When to use. + +- Forms with 2-3 steps where the indicator overhead exceeds its value. +- Forms where the user's expectation is "this is short" and the indicator would imply length. + +Risks. + +- Without indication, longer forms can feel endless. +- Users may abandon because they cannot predict the form's length. + +The discipline. No indicator is rarely the right answer for forms with more than 3 steps. + +--- + +## Pattern E: Hybrid + +Combining patterns. A step counter plus a progress bar; or a step list plus a percentage. + +Strengths. + +- Multiple signals reinforce each other. +- Different users benefit from different indicators. + +Weaknesses. + +- Visual complexity grows. +- Risk of redundant or conflicting signals. + +When to use. Long forms (5+ steps) where rich indication helps the user understand the form's shape. + +--- + +## Indicator failures + +Patterns that break trust. + +Failure 1: Indicator that shifts mid-form. + +The form starts as "Step 4 of 5"; conditional logic adds steps; the form is now "Step 4 of 7." The user feels misled. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). + +Failure 2: Indicator that hides remaining work. + +"Almost done" when 5 fields remain on the next step. The user trusted the indicator and now feels betrayed. + +The cure. Calibrate the indicator to reflect remaining fields, not just remaining steps. + +Failure 3: Indicator that fills fast and slows down. + +Progress bar fills to 70 percent in the first 2 steps; the remaining 30 percent takes the next 5 steps. The user expects the form to end soon and is frustrated when it does not. + +The cure. Weight the progress bar by actual work, not just step count. If step 5 represents most of the remaining work, the bar should reflect that. + +Failure 4: Indicator with no current-step context. + +The progress bar shows 50 percent but the user does not know what the current step is about. Reduces orientation. + +The cure. Include both progress (where you are) and current-step name (what you are doing). + +Failure 5: Indicator that is decorative without being honest. + +Progress that looks fast but the next step is the longest one. The indicator misleads about pacing. + +The cure. Honest pacing. The indicator should reflect actual time-to-complete, not just step count. + +--- + +## Indicator placement + +Where the indicator lives on the page. + +Top placement. Above the form fields. Common; user sees it on every step. + +Sidebar placement. Alongside the form. Good for step-list patterns; takes more space. + +Bottom placement. Below the form fields. Less common; user has to scroll to see it on long steps. + +Sticky placement. Indicator stays visible as the user scrolls within a step. Useful for long steps. + +The choice depends on form length per step and visual hierarchy. Top placement is the safe default. + +--- + +## Indicator and mobile + +The indicator must work on mobile. + +Mobile-specific considerations. + +- Step counter: easy to mobile (small footprint). +- Progress bar: easy (full-width fits). +- Step list: harder; may need to collapse to step counter on mobile. +- Hybrid: simplify on mobile; do not stack multiple indicators. + +The mobile discipline. Ensure the indicator is visible without scrolling. Mobile users should see "Step 2 of 5" or the progress bar without searching for it. + +--- + +## Indicator messaging + +Optional language alongside the indicator. + +Encouragement messages. "Halfway there!" or "Almost done!" Can boost motivation; can also feel patronizing. + +Time estimates. "About 2 minutes left." Useful when honest; misleading when wrong. + +Step-name labels. "Step 2: Your Company." Useful when steps have meaningful names. + +The discipline. Encouragement and estimates should be honest. Patronizing or wrong messaging breaks trust faster than no messaging. + +--- + +## Indicator updating + +When the indicator updates. + +On step transition. The indicator updates as the user moves to the next step. Common pattern. + +On field completion. The indicator updates as fields within a step are filled. More granular; less common. + +Smooth animation. Subtle animation on transition reinforces progress. + +No animation. Instant update is fine; flashy animation can be distracting. + +--- + +## When indicators add no value + +Some forms work without indicators. + +Very short forms. 2-step forms often do not need indication. The user knows it is short. + +High-frequency forms. Forms the user fills repeatedly may not need indication after the first time. + +Single-action forms. A subscription form with email and submit does not need a progress indicator. + +The discipline. Default to including an indicator for multi-step forms. Skip only when the form is genuinely simple enough that the indicator adds noise. + +--- + +## Indicator audit + +Periodically audit the indicator. + +The audit. + +- Read the indicator on each step. Does it reflect honest progress? +- Test the form with conditional logic. Does the indicator handle the variability? +- Check mobile rendering. Does the indicator work on touch devices? +- Check accuracy. Does "almost done" actually mean almost done? + +The drift. Indicators decay as forms evolve. Steps get added; conditional logic gets added; the indicator falls out of sync. + +The cure. Quarterly audit alongside form audit. Update the indicator when the form structure changes. + +--- + +## Common indicator failures + +No indicator on a long form. User does not know how much remains; abandons. + +Indicator shifts mid-form. Conditional logic surprised the user. + +Dishonest pacing. Bar fills fast, work remains slow. + +Indicator without current-step context. Progress without orientation. + +Indicator overflowing on mobile. Step list designed for desktop; cramped on mobile. + +Patronizing language. "Almost done" repeatedly when the user is at step 2 of 6. + +Wrong time estimates. "About 1 minute left" when 5 minutes remain. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. Indicator failures (5 patterns). Indicator placement, mobile considerations, messaging, updating. When indicators add no value. Indicator audit. Common failures. + +## Implementation choices that stay internal + +Specific indicator designs for specific forms. Specific tooling for indicator implementation. Specific brand-voice messaging alongside indicators. The team's mobile testing benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md b/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md new file mode 100644 index 0000000..dc1b7a3 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/save-and-resume-mechanics.md @@ -0,0 +1,267 @@ +# Save-and-resume mechanics + +When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. + +Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. Done well, it earns the user's trust and recovers what would otherwise be lost completions. + +--- + +## When save-and-resume helps + +Three conditions that, when present, make save-and-resume valuable. + +Form length warrants it. Forms taking more than 5 minutes to complete benefit. Below 5 minutes, the user can usually push through; above, the cost of starting over is high. + +Information may not be at hand. Forms requiring documents, technical configurations, or specific data the user may need to gather. Save-and-resume lets the user collect the information and return. + +Multi-session use is expected. Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms, complex onboarding). Save-and-resume is required, not optional. + +When all three are present, save-and-resume is a strong investment. When none are present, the mechanic adds complexity without lift. + +--- + +## When save-and-resume does not help + +Quick lead-capture forms. Under 60 seconds to complete. The save mechanic adds complexity; the audience does not need it. + +Single-session forms. Forms designed to be completed in one sitting. Save-and-resume can encourage abandonment ("I will come back later") that becomes permanent. + +Forms that require trust. Sensitive information may not be safe to persist; the user may not save because they distrust persistence. Adding save-and-resume without addressing trust degrades the form. + +Forms with strict expiration. Application deadlines or session timeouts may make save-and-resume confusing or counterproductive. + +--- + +## Pattern A: Email-link recovery + +The most common save-and-resume pattern. + +How it works. + +- The user clicks "Save and resume later." +- A form appears asking for an email address. +- The user enters email; a recovery link is sent. +- The user opens the email later, clicks the link, returns to the form with progress preserved. + +Strengths. + +- Familiar pattern; users understand it. +- Works across devices (user can save on desktop, resume on mobile). +- Simple to implement. + +Weaknesses. + +- Requires the user to give an email address before completing the form (which may itself be friction). +- Depends on email deliverability. +- Recovery link can expire or get lost. + +When to use. Default for most save-and-resume needs. The familiar UX reduces friction. + +--- + +## Pattern B: Account-based persistence + +Forms that require account creation persist by default. + +How it works. + +- The user creates an account at the start. +- Form progress saves automatically as the user completes fields. +- The user logs back in to resume. + +Strengths. + +- Persistence is automatic; user does not have to choose to save. +- Works across devices. +- Account integration may extend to other features beyond the form. + +Weaknesses. + +- Account creation is significant friction at the start. +- Adds engineering complexity. +- May not be appropriate for one-shot forms. + +When to use. Forms that are part of an account-based product or service where account creation is justified by ongoing use. + +--- + +## Pattern C: Anonymous-session save + +Browser-based save without identification. + +How it works. + +- Form progress saves to browser local storage as the user completes fields. +- The user returns to the same browser, picks up where they left off. + +Strengths. + +- Lowest friction; no email or account required. +- Automatic; user does not have to choose to save. + +Weaknesses. + +- Works only on the same browser/device. +- Lost if the user clears cookies or switches devices. +- Limited persistence (typically days, not weeks). + +When to use. Forms where the audience likely returns from the same device within a short window. Often used as a fallback or supplement to other patterns. + +--- + +## Pattern D: Hybrid + +Combining patterns. Anonymous-session save by default; email-link recovery as a backup. + +How it works. + +- Form auto-saves to browser as user completes. +- A "save and resume from any device" option offers email-link recovery. + +Strengths. + +- Lowest-friction default; user benefits even without explicit action. +- Cross-device option for users who want it. + +Weaknesses. + +- More complex to design and explain. +- Multiple save mechanisms can confuse the user. + +When to use. Forms with significant length where many users return same-device but some need cross-device. + +--- + +## Trust communication + +Users hesitate to save partial sensitive information. The form must communicate clearly. + +What to communicate. + +- What is saved. "Your answers so far will be saved." +- What is not saved. "We do not save passwords or payment information until submission." +- How long it persists. "Your progress will be available for 7 days." +- Who can access it. "Only you can access your saved progress through the link we email you." +- How to delete. "You can clear your saved progress by completing or abandoning the form." + +Trust copy patterns. + +- "We never share your saved information." +- "Your progress is encrypted at rest." +- "You control whether to come back." + +Trust copy that fails. + +- Generic privacy boilerplate. +- Long legal text the user will not read. +- Vague reassurances without specifics. + +The discipline. Trust copy should be specific, scannable, and honest. Generic privacy text does not earn trust. + +--- + +## When in the form to offer save-and-resume + +Timing matters. + +Pattern: Always available. A "Save and resume" link visible on every step. The user can save at any moment. + +Pattern: Triggered by inactivity. After 60-90 seconds of inactivity, prompt the user to save. Risk: the prompt feels intrusive. + +Pattern: Offered at logical breakpoints. Save prompts at the end of each step or at known long-pause points. Less intrusive than continuous availability. + +Pattern: Offered before high-friction steps. "The next step requires document uploads. You can save now and come back when you have your documents." + +The choice depends on form length and the audience's likely pause points. Always-available is the safe default for long forms. + +--- + +## Resume experience + +The user clicks the recovery link or logs in. What happens next. + +The principle. The resume experience should be uninterrupted. The user lands on the step they were on; their previous answers are preserved; they can continue without re-doing work. + +The resume page. + +- Welcome back message confirming the resume. +- Preserved progress visible (the user sees what they had done). +- Clear path to continue (button to proceed to current step). + +Resume failures. + +- The user lands at the start; previous answers lost. Trust collapses. +- The user lands at the right step but answers are wrong. Worse than starting over. +- The recovery link expires; the user is told their progress is gone. The save mechanism failed. + +The discipline. Test the resume experience as carefully as the form itself. A broken resume is worse than no save. + +--- + +## Save-and-resume measurement + +Track how many users save and resume. + +The metrics. + +- Save rate. What percentage of users who reach the save option choose to save? +- Resume rate. What percentage of users who saved actually resume? +- Resume-to-completion rate. What percentage of users who resumed complete the form? + +Diagnostic uses. + +- Low save rate: the option is not visible or trust is missing. +- Low resume rate: the recovery email failed or the user lost interest. +- Low resume-to-completion: the resume experience is broken or the form is too long. + +The decision. If save-and-resume is offered but rarely used, audit whether the offering is justified or whether the mechanic adds complexity without payoff. + +--- + +## Save-and-resume for sensitive information + +Some forms collect sensitive information. Save-and-resume requires extra care. + +The principle. Sensitive information may not be safe to persist. Audit what is saved and what is not. + +Common patterns. + +- Save non-sensitive only. Names, emails, situational information saved; passwords, SSNs, payment details not saved. +- Encrypt at rest. Saved data encrypted in storage; only retrievable through recovery flow. +- Limit persistence window. Sensitive forms may save only for 24-48 hours rather than 7+ days. + +Compliance considerations. + +- Some jurisdictions or regulations restrict what can be persisted. +- The form's save behavior should be reviewed against applicable compliance. +- Trust copy should disclose persistence honestly. + +The discipline. Sensitive forms warrant more conservative save behavior. The convenience of save-and-resume is not worth privacy or compliance risk. + +--- + +## Common save-and-resume failures + +Save offered without trust communication. Users do not save because they distrust persistence. + +Recovery link expires too quickly. User receives the link, intends to come back, finds the link expired by the time they do. + +Resume to wrong step. User clicks recovery link, lands at the start, has to redo everything. + +Saved answers corrupted. User resumes, answers are wrong or partial. + +Save mechanic decays. Storage backend changes; saved data becomes inaccessible. + +Multiple save mechanisms confuse. Anonymous-session and email-link both offered; user does not know which to use. + +Save offered on a form that does not need it. Quick form gets save mechanic; complexity without payoff. + +--- + +## Methodology-level choices that stay in the public skill + +When save-and-resume helps and does not. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Trust communication discipline. Timing of save offering. Resume experience. Measurement. Save-and-resume for sensitive information. Common failures. + +## Implementation choices that stay internal + +Specific save-and-resume implementations for specific forms. Specific persistence backends and expiration policies. Specific trust copy in brand voice. The team's compliance review processes. These vary by team. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..de0e936 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/step-architecture-patterns.md @@ -0,0 +1,279 @@ +# Step architecture patterns + +What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. + +The architecture is the structure that makes steps coherent. Bad architecture produces progress-theater (decorative steps); good architecture produces genuinely-staged forms (each step is a coherent unit of work). + +--- + +## The coherence principle + +Each step should represent a coherent unit of work from the user's perspective. + +The test. Can the user describe what they just did at the end of the step in one sentence? + +- Coherent: "I told you the basics about my company." +- Atomized: "I typed my company name in a field." + +Coherent answers signal genuinely-staged. Atomized answers signal progress-theater. + +The discipline. Each step should bundle related fields into a single cognitive unit. The user processes the step as a whole, not as 5 isolated fields. + +--- + +## Common step patterns + +Patterns that recur across acquisition, onboarding, and intake forms. + +Identity step. Who the user is. + +- Fields: name, email, role. +- Friction level: low. +- Position: opens the form. +- The user provides minimal commitment; the form earns the right to ask for more. + +Context step. What the user's situation is. + +- Fields: company size, industry, current setup, current tools. +- Friction level: medium. +- Position: after Identity, before Need. +- The user shares context that lets the form (or the receiving team) understand them. + +Need step. What the user is trying to accomplish. + +- Fields: goal, challenge, timeline, urgency. +- Friction level: medium-to-high. +- Position: middle of the form. +- The user articulates intent. This step often includes the highest-value fields for the receiving team. + +Detail step. Specifics needed to act on the user's request. + +- Fields: budget, specific requirements, constraints, integrations. +- Friction level: high. +- Position: late in the form. +- The user shares specifics. By this point, commitment is built; the user is more willing to share. + +Confirmation step. Review and submit. + +- Fields: review summary, submission action, optional final fields (preferences, follow-up). +- Friction level: low. +- Position: last. +- The user reviews what they provided and submits. + +--- + +## Sequencing principles + +The order of steps matters as much as the steps themselves. + +Principle 1: Low-friction first. The opening step should be easy to complete. The user invests their first 30-60 seconds in something simple; commitment compounds. + +Principle 2: Commitment compounds. Each step builds on the previous. The user who completed step 2 is more invested than they were before step 1; later steps can ask for more. + +Principle 3: High-friction at the end. The most demanding fields (budget, specific requirements, sensitive info) belong later. By that point, the user has invested enough to push through. + +Principle 4: Confirmation explicit. A final review-and-submit step lets the user verify their inputs. Reduces submission anxiety. + +Anti-pattern: high-friction first. Asking for budget in step 1 depresses completion. The user has not yet committed; the high-friction question feels premature. + +Anti-pattern: commitment-resetting. A late step that requires the user to make decisions they thought they had already made. The user feels their earlier work was wasted. + +--- + +## Step coherence test + +For each step, ask: can this step be described in one sentence as a unit of work? + +Coherent step examples. + +- "Step 1: tell us who you are." (Identity) +- "Step 2: tell us about your company." (Context) +- "Step 3: tell us what you are trying to accomplish." (Need) +- "Step 4: tell us the specifics so we can help." (Detail) +- "Step 5: review and submit." (Confirmation) + +Each step has a coherent description. The user can predict what is coming and feel they accomplished something at the end of each step. + +Incoherent step examples (progress-theater). + +- "Step 1: name and email." +- "Step 2: phone and company." +- "Step 3: role and industry." + +Each step is two fields. The fields are unrelated. The grouping is arbitrary. The user wonders why this is multi-step. + +--- + +## Field count per step + +How many fields per step is too many or too few. + +Too few. 1-2 fields per step often signals over-staging. The user wonders why this needed its own step. + +Right range. 3-7 fields per step. Enough to represent a coherent unit of work; few enough to complete in 30-60 seconds. + +Too many. 10+ fields per step starts to recreate the kitchen-sink-single-page problem within a step. Audit for non-essential fields. + +The variance. Some steps may have more fields than others; that is fine if each step's fields cohere. The Detail step often has more fields than the Identity step because it captures more specific information. + +--- + +## Step length variability + +Steps do not have to be the same length. + +The pattern. Identity step: 3 fields. Context step: 5 fields. Need step: 4 fields. Detail step: 7 fields. Confirmation step: 1 action. + +The variability is fine because each step represents a coherent unit. The user does not expect equal length; they expect coherence. + +The progress indicator implication. A step counter ("Step 2 of 5") may not reflect time-to-complete accurately when steps vary. A progress bar based on percentage of fields complete reflects the variability better. + +--- + +## Conditional step inclusion + +Some forms include or exclude steps based on earlier answers. + +The pattern. "If user has a current CRM, include the 'CRM details' step. If not, skip it." + +Strengths. + +- Removes irrelevant fields entirely. +- Makes the form feel adaptive. + +Risks. + +- Progress indicators must accommodate the variability honestly. +- The user may notice the variability and feel confused. + +The discipline. Use conditional steps when the variability genuinely benefits the user; communicate the dynamic nature in the progress indicator if it shifts. + +--- + +## Step transitions + +How the user moves from one step to the next. + +The forward transition. A clear "Next" or "Continue" button. Validation runs before the transition. + +The backward transition. A "Back" or "Previous" button. The user can return to earlier steps without losing later inputs. + +The skip transition. Some forms allow skipping optional steps. Use sparingly; skipping creates inconsistent paths. + +Transition friction. Each transition should feel snappy. Loading delays at transitions break the flow. + +Transition cues. Brief visual confirmation that the step changed (slide animation, fade transition). Helps the user understand the navigation. + +--- + +## Step naming + +Each step should have a clear name visible to the user. + +Strong step names. + +- "Tell us about you." +- "About your company." +- "What you are looking for." +- "The details." +- "Review and submit." + +Weak step names. + +- "Step 1," "Step 2," "Step 3." (Numbers without names; user does not know what each represents.) +- "Personal Info," "Company Info," "Other Info." (Generic; does not signal what the step is about.) +- "Contact," "Business," "Submission." (Truncated; does not warm the user.) + +The voice match. Step names should match the brand voice. Casual brands use casual names; serious brands use serious names. + +--- + +## Step architecture for specific use cases + +How the architecture varies by form purpose. + +Lead-capture form (5-8 fields). + +- Identity (name, email) +- Context (company, role) +- Need (use case, urgency) + +3 steps; the form moves quickly. + +Demo-request form (10-15 fields). + +- Identity (name, work email, role) +- Company (name, size, industry) +- Current state (current solution, key pain points) +- Buying intent (timeline, budget range) +- Confirmation + +5 steps; meaningful staging. + +Application form (20+ fields with documents). + +- Identity +- Eligibility (qualifying questions) +- Personal details +- Financial details +- Document upload +- Review +- Submit + +7+ steps; long form benefits significantly from staging. + +Onboarding wizard (configuration-driven). + +- Welcome +- Account setup +- Use-case selection +- Preferences +- Connect-your-tools +- Confirmation + +6 steps; each step represents a coherent setup unit. + +--- + +## Step architecture audit + +Periodically audit the step architecture. + +The audit. + +- Read each step's name. Does it represent a coherent unit? +- Read each step's fields. Do they cohere? +- Check field count per step. Within the 3-7 range? +- Check conversion per step. Are some steps disproportionately drop-off-heavy? + +The drift. Steps decay as the form evolves. New fields get added to the wrong step; steps become incoherent; field counts drift. + +The cure. Quarterly audit. Re-group fields into the right steps; remove non-essential fields; restructure if the original architecture no longer fits. + +--- + +## Common architecture failures + +Arbitrary chunking. Steps that group fields by visual length rather than coherence. + +Atomized steps. Each step has 1-2 fields; the user wonders why it is multi-step. + +Field-count overload. Some steps have 15+ fields; recreates the kitchen-sink problem within a step. + +High-friction-first. Budget or sensitive question in step 1; user is not committed enough to push through. + +Commitment-resetting steps. Late steps that require the user to make decisions they thought were already made. + +Generic step names. "Step 1, Step 2" without descriptive names; user cannot predict the form. + +No confirmation step. Form ends at the data-collection step; user is not given the chance to review. + +--- + +## Methodology-level choices that stay in the public skill + +The coherence principle. Common step patterns. Sequencing principles. The step-coherence test. Field count per step. Step length variability. Conditional step inclusion. Step transitions. Step naming. Step architecture for specific use cases. Step-architecture audit. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific forms. Specific step naming in brand voice. Specific tooling for step transitions and validation. The team's audit calendars. These vary by team and form. diff --git a/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md b/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md new file mode 100644 index 0000000..2c53366 --- /dev/null +++ b/dist/pi/.agents/skills/multi-step-form-design/references/validation-strategy-patterns.md @@ -0,0 +1,288 @@ +# Validation strategy patterns + +Per-step vs end-only vs hybrid. Validation message discipline. + +The validation strategy determines when errors are caught and how they are communicated. Done well, validation catches errors helpfully and protects the form from invalid submissions. Done poorly, validation rejects valid inputs or surfaces errors at the worst time. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. Errors caught too early feel intrusive; errors caught too late waste the user's investment. + +The win. A user enters an invalid email; inline validation catches it immediately; the user fixes it and continues. + +The fail (too early). A user is mid-typing an email; "must contain @" appears before they have finished typing. + +The fail (too late). A user completes 5 steps; submission fails because of a step-1 error they did not see flagged. + +The strategy choice depends on the form's length, the audience, and the validation complexity. + +--- + +## Pattern A: Per-step validation + +Each step's fields are validated before allowing progression to the next step. + +How it works. + +- The user completes the current step. +- Validation runs on all fields in the step. +- If errors exist, they are shown; the Next button does not advance. +- The user fixes errors and proceeds. + +Strengths. + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +Weaknesses. + +- Can feel intrusive if validation is too strict on every step transition. +- May block the user from progressing when they want to revise the field later. + +When to use. Default for most multi-step forms. Each step's data is validated as a coherent unit. + +--- + +## Pattern B: End-only validation + +All validation runs at submission. + +How it works. + +- The user completes all steps. +- Validation runs only when the user clicks Submit. +- All errors surface at once. + +Strengths. + +- User completes uninterrupted. +- Validation logic is simpler (one validation pass). + +Weaknesses. + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. +- Errors that span multiple steps are confusing to surface. + +When to use. Rarely. Sometimes appropriate for very short forms where per-step validation overhead is not worth it. + +--- + +## Pattern C: Hybrid + +Required-field validation per step; full validation at end. + +How it works. + +- Per-step: critical errors (missing required fields, malformed email format) catch immediately. +- End: nuanced validation (cross-field consistency, business rules) catches at submission. + +Strengths. + +- Combines the responsiveness of per-step with the simplicity of end-only. +- The user gets immediate feedback on critical issues. +- Complex validation logic does not interrupt the flow. + +Weaknesses. + +- More complex to design (two validation tiers). +- Risk of inconsistent user experience if the tiers are not well-coordinated. + +When to use. When validation has both critical-immediate components (required fields, format checks) and nuanced-end components (cross-field rules, business logic). The default pattern for most multi-step forms with significant validation needs. + +--- + +## Pattern D: Real-time validation + +Validation runs as the user types or interacts with each field. + +How it works. + +- As the user types, validation runs on the field. +- Errors appear inline as soon as they are detectable. +- Some implementations validate on field blur (when the user leaves the field) rather than every keystroke. + +Strengths. + +- Earliest possible error detection. +- User sees the result of their input immediately. + +Weaknesses. + +- Can feel intrusive if validation appears before the user finishes typing. +- Real-time validation on complex rules can lag. +- Easy to surface errors prematurely. + +When to use. When the validation is simple enough to run instantly (format checks) and when the audience benefits from immediate feedback. Best practice: validate on blur rather than every keystroke. + +--- + +## Validation message discipline + +The error messages themselves matter. + +Helpful messages. + +- "Phone number must include area code" (specific guidance). +- "Try a value between 1 and 1000" (specific range). +- "Email must include @ and a domain" (specific format). +- "This field is required" (when blank). + +Unhelpful messages. + +- "Invalid input" (generic). +- "Error" (no information). +- "Out of range" (no range specified). +- "You must enter..." (scolding tone). + +Tone discipline. Messages should be helpful, not scolding. "Try a value between 1 and 1000" beats "You must enter a value between 1 and 1000." + +Specificity. "Phone number must be 10 digits" beats "Invalid phone number." Specific guidance lets the user fix the issue immediately. + +--- + +## Inline placement + +Where errors appear matters. + +Inline placement. Errors appear next to the field that triggered them. The user sees the error in context. + +Banner placement. Errors appear in a banner at the top of the step. Easy to miss; less helpful. + +Mixed placement. Some errors inline, some in a banner. Confusing. + +The discipline. Inline placement is the default. Banners can supplement (summarizing all errors on the step) but should not replace inline. + +--- + +## Validation timing + +When validation triggers. + +On blur. Validation runs when the user leaves the field. Default for most field types. + +On change. Validation runs as the user types. Useful for some real-time feedback (password strength, character count) but intrusive for most validation. + +On submit. Validation runs when the user clicks the Next or Submit button. Always required as the final check. + +The combination matters. Most fields work well with on-blur for individual validation plus on-submit for final check. + +--- + +## Cross-field validation + +Validation that depends on multiple fields. + +Examples. + +- "End date must be after start date." +- "Sum of allocations must equal 100 percent." +- "If selected 'enterprise,' company size must be above 200." + +The challenge. Cross-field validation does not fit per-field timing. The validation can only run when both fields have values. + +Approaches. + +- End-only validation for cross-field rules. The cross-field check runs at submission. +- End-of-step validation. The cross-field check runs when the step containing both fields is completed. +- Reactive cross-field validation. Each time either field changes, the cross-field check runs. + +The choice depends on the form's complexity and the user's likely workflow. + +--- + +## Validation strictness + +How aggressively to reject inputs. + +Too strict. Rejects valid inputs because the validation is over-specified. "Email format invalid" for an email with a plus-sign alias. + +Too loose. Accepts invalid inputs that fail at submission. The user finds out late. + +The right strictness. Match validation rules to actual business requirements. Do not reject inputs the system can handle; do not accept inputs the system will choke on. + +Common over-strictness mistakes. + +- Email validation that rejects plus-sign aliases. +- Phone validation that rejects international formats. +- Name validation that rejects non-Latin characters. +- Address validation that rejects valid international addresses. + +The discipline. Validation should reflect what the system actually requires, not what is stereotypical. + +--- + +## Validation and accessibility + +Validation must work for users with assistive technology. + +Screen reader announcements. Errors should be announced when they appear. ARIA live regions for inline errors; focus management for error summaries. + +Keyboard navigation. Users should be able to navigate to error messages with keyboard alone. + +Visual cues alongside text. Color-coding for errors should not be the only signal; text labels and icons help users who cannot perceive color. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Validation and mobile + +Mobile validation has specific considerations. + +Touch-friendly error states. Error indicators should be visible without pinch-zoom. + +Inline placement on mobile. Errors appearing below or above the field; do not push critical content off-screen. + +Mobile keyboards. Use input types (email, tel, number) so mobile keyboards adapt; this also helps validation. + +Real-time validation latency. On mobile, real-time validation can lag and feel sluggish; default to on-blur for performance. + +--- + +## Validation testing + +Test validation across edge cases. + +Test cases to include. + +- Empty required fields. +- Format-invalid inputs (malformed emails, invalid phone numbers). +- Format-valid but business-invalid inputs (email without account, valid date in the past for a future-only field). +- Boundary inputs (minimum, maximum, just-outside). +- Special characters and international inputs. + +The discipline. Validation should pass valid inputs and reject invalid ones consistently. Test with realistic edge cases the audience will encounter. + +--- + +## Common validation failures + +Generic error messages. "Invalid input" without guidance. + +Over-strict validation. Rejecting valid inputs that fall outside narrow expectations. + +Late validation. Errors caught only at submission for issues that should have surfaced earlier. + +Banner-only error placement. User cannot see which field has the issue. + +Validation that rejects internationally. US-only formatting rules applied to international audiences. + +Inconsistent validation rules. Same field validated differently in different contexts. + +Validation without accessibility. Errors invisible to screen readers; color-only cues. + +Validation that interrupts typing. Real-time validation surfacing errors before the user finishes typing. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Validation message discipline (helpful vs unhelpful). Inline placement. Validation timing. Cross-field validation. Validation strictness. Validation and accessibility (cross-reference). Validation and mobile. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific forms. Specific tooling for validation implementation. Specific brand-voice error messages. The team's accessibility review processes. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/SKILL.md b/dist/pi/.agents/skills/okr-design/SKILL.md new file mode 100644 index 0000000..83f3ea1 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/SKILL.md @@ -0,0 +1,310 @@ +--- +name: okr-design +description: "OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the difference between sandbagged OKRs (always 100%) and aspirational OKRs (always 30%) and stretch OKRs (genuine ambition with quarterly accountability). Triggers on OKR design, OKR setting, key result design, OKR scoring, mid-quarter recalibration, OKR cascading, outcomes vs outputs, quarterly planning, goal setting. Also triggers when a team's OKRs are always hit and producing no learning, when OKRs are demoralizing because they were set as fantasy, or when the team uses OKR vocabulary but the practice has decayed." +category: product +catalog_summary: "OKR design discipline. Outcome statements, key results, scoring, mid-quarter recalibration. Distinguishes sandbagged OKRs (always hit, useless) from aspirational fantasy (impossible, demoralizing) from stretch OKRs (genuine ambition with quarterly accountability)" +display_order: 12 +--- + +# OKR Design + +A senior product leader's playbook for OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the practical disciplines that distinguish OKRs from quarterly to-do lists or impossible-fantasy goal-setting. + +OKRs are accountability infrastructure. When designed well, they produce a quarterly rhythm of ambitious goal-setting, mid-quarter learning, end-of-quarter scoring, and adjustment for the next quarter. When designed badly, they become a tax on the team that produces no signal: sandbagged OKRs that always hit 100% (no ambition, no learning), aspirational fantasy OKRs that nobody can hit (demoralizing, ignored after week 2), or vague OKRs that the team scores generously regardless of outcome. + +This skill is OKR design as practical methodology. The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, key results that actually measure the outcome, scoring honestly even when uncomfortable, recalibrating mid-quarter when warranted, and using the OKR review cadence to drive learning rather than performance theater. + +The voice is the senior product leader who has run OKRs in healthy organizations and watched the practice decay in others. Concrete, opinionated about what actually works, willing to call out the failure modes that conference talks gloss over. + +When to use this skill: designing OKRs for the next quarter, auditing why current OKRs are not driving decisions, recalibrating an OKR practice that has decayed, or onboarding a team to OKRs that has never used them. + +--- + +## What this skill is for + +This skill spans OKR design and the operational rhythm around them. The PM-skill distinction: + +- `okr-design` (this skill) is outcomes (results to be achieved). +- `roadmap-planning` is outputs (features and initiatives sequenced). +- `feature-launch-playbook` is post-ship execution. +- `product-analytics-setup` is measurement infrastructure (the metrics that key results depend on). +- `experiment-design` is the discipline for testing whether specific initiatives produce outcomes. +- `discovery-research-synthesis` informs which outcomes to pursue. + +The audience: senior PMs, product directors, engineering leaders, executives setting org-wide OKRs, in-house teams operating in OKR-driven cultures. + +What is not in scope: the broader strategic planning that decides which outcomes matter (other strategy frameworks); the execution of specific initiatives toward OKRs (covered by roadmap-planning, pm-spec-writing, feature-launch-playbook); the analytics infrastructure (covered by product-analytics-setup, analytics-strategy). + +--- + +## Sandbagged vs aspirational-fantasy vs stretch + +The keystone framing. + +Sandbagged. OKRs designed to hit 100%. The key results target outcomes the team is already on track to deliver. End of quarter: 100% scores across the board. The team celebrates; nobody learns anything. Output: an OKR practice that produces no signal. The team has the same OKRs every quarter dressed in different vocabulary because nothing pushes them past where they would have gone anyway. + +Aspirational-fantasy. OKRs that nobody can hit. 1000% growth in 90 days. Demoralizing, performative, ignored after week 2. Teams that ship aspirational-fantasy OKRs typically discover by week 6 that no realistic effort path produces the targets; they disengage; the OKRs become decoration on the planning doc that nobody references. + +Stretch. Genuine ambition with quarterly accountability. Designed to hit 60-70% on average. Hits and misses both teach something. The 60% case ("we hit 60% of our key results") is informative about what the team can deliver in a quarter; the 100% case is rare and usually signals sandbagging in retrospect; the 30% case signals either fantasy or the team encountered something unexpected (which is also informative). + +The litmus test. Look at the team's last four quarters of OKRs. If the average score is 95%+, the OKRs are sandbagged. If the average is below 30%, they are fantasy. If the average is 50-75%, the design is in the stretch zone. Adjust upcoming OKRs to bring the practice into stretch territory. + +--- + +## Objective design + +Objectives are outcome statements. They name what the team is trying to achieve in the quarter. + +Strong objective characteristics. + +- Outcome-focused, not output-focused. "Improve activation for new sign-ups" is an outcome; "Ship the new onboarding flow" is an output. +- Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. +- Inspiring without being fantasy. The team should feel pulled toward the objective, not crushed by it. +- Few in number. Most teams should have 2-4 objectives per quarter; more than 5 dilutes focus. + +Worked examples. + +- "Improve activation for new sign-ups so that more reach the value-realization moment within the first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +Weak objective characteristics. + +- Output-disguised-as-outcome. "Ship the activation redesign" is an output; the objective should be the result the redesign is meant to produce. +- Too vague. "Improve user experience" is too broad to focus quarterly work. +- Too tactical. "Refactor the auth service" is a tactical decision, not a quarterly objective. +- Too many. 8 objectives produces no focus; the team works on too many things and excels at none. + +Detail in [`references/objective-design-patterns.md`](references/objective-design-patterns.md). + +--- + +## Key result design + +Key results measure progress toward the objective. They are the quantitative or testable indicators that show whether the objective is being achieved. + +Strong key result characteristics. + +- Measurable. There is a specific number or testable threshold. +- Outcome-aligned. Achieving the key result actually moves the objective forward. +- Within team influence. The team can affect the key result through their work. +- Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +Worked example. Objective: "Improve activation for new sign-ups." + +Strong key results: + +- "Increase the percentage of new sign-ups reaching the value-realization moment within their first week from 32% to 45%." +- "Reduce the median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on the onboarding flow (up from 64%)." + +Each key result is measurable, ties to activation, the team can influence it through onboarding redesign work, and is time-bounded to the quarter. + +Weak key results. + +- Vague: "Improve activation significantly." +- Output: "Ship 5 onboarding redesign initiatives." (counts work done, not outcomes produced.) +- Outside influence: "Increase total signups by 50%." (signups are mostly upstream of activation work.) +- Vanity: "Reach 1M users." (impressive number; not directly tied to activation outcome.) + +The 3-5 key results rule. Most objectives benefit from 3-5 key results. One key result is fragile (single measurement may not capture the outcome); 6+ key results dilute focus. + +Detail in [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md). + +--- + +## Cascading OKRs across the org + +When and how to cascade OKRs from leadership to teams. + +The trade-off. + +- Cascaded OKRs ensure team work aligns with company priorities. The product team's objective derives from the company's objective; the engineering team's objective derives from the product team's. +- Strict cascading produces top-down OKRs that miss bottom-up insight. The team closer to the work sometimes knows what to prioritize better than the layer above. +- Too-loose cascading produces team OKRs that do not connect to company priorities; teams optimize locally without contributing to org goals. + +The middle path. + +- Company-level OKRs set quarterly. Team-level OKRs set with reference to company OKRs but with team-level autonomy on how to contribute. +- Each team's OKRs explicitly identify which company OKRs they ladder up to. +- Some team OKRs may be team-specific (technical debt, infrastructure, experimentation infrastructure) without direct company-OKR ladders. Surface these explicitly so the team's full work is visible. + +When to cascade strictly. Early-stage companies aligning around a small number of company priorities. Times of strategic shift where the org needs to move in a coordinated direction. + +When to cascade loosely. Mature organizations with established team mandates. Cross-functional teams where strict cascading would over-constrain. + +The honest disclosure. Cascading is harder than conference talks suggest. Most orgs over-cascade in the first few cycles and learn to relax it; some never learn and produce OKRs that are increasingly performative as they propagate down. + +Detail in [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md). + +--- + +## Scoring discipline + +End-of-quarter scoring is where OKR practice succeeds or decays. + +The 0.0-1.0 scale. Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +The 60-70% target. Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. Higher average suggests sandbagging; lower suggests fantasy or unexpected disruption. + +Scoring honesty. + +- Score the actual outcome, not the effort. The team that worked hard but did not move the metric scores low; the team that got lucky and moved the metric without much effort scores high. The score reflects outcome. +- Do not round up. A key result at 0.55 is 0.55, not 0.6. Honest scoring produces honest signal. +- Acknowledge what changed mid-quarter. Some misses reflect priority shifts; surface those without using them as excuses. + +What 100% means. 100% scores warrant scrutiny. Either the OKR was sandbagged (under-set), the team had a great quarter (informative), or the team is rounding up. Investigate which. + +What 30% means. 30% scores warrant scrutiny. Either the OKR was fantasy (over-set), the team encountered unexpected disruption (informative), or the work was deprioritized mid-quarter (also informative). Investigate which. + +The compensation question. OKRs work best when not directly tied to compensation. When OKRs determine bonuses, sandbagging incentives become severe; teams set OKRs they know they can hit. Most healthy OKR cultures separate goal-setting from compensation. + +Detail in [`references/scoring-discipline.md`](references/scoring-discipline.md). + +--- + +## Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. + +The default. OKRs hold for the quarter. Teams adapt their tactics to the OKR; OKRs do not change to match what the team is doing. + +When to recalibrate. + +- Strategic shift. The company's strategy changed materially mid-quarter; OKRs that no longer reflect the strategy are no longer the right targets. +- Major external disruption. A market change, regulatory event, or significant outage warrants resetting the quarter's targets. +- Information that invalidates the OKR. The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +When NOT to recalibrate. + +- The team is not on track. OKRs that are missing should remain as set; the miss is the signal. +- The OKR is uncomfortable. Teams uncomfortable with stretch OKRs should not lower them mid-quarter to feel better. +- Easier OKRs would feel achievable. The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +The recalibration discipline. Recalibration should be rare (1-2 quarters out of 8). Frequent recalibration signals OKR design failure: either too aggressive or not strategically aligned. The recalibration itself should be transparent: surface what changed, why, and what the new targets are. + +Detail in [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md). + +--- + +## The OKR review cadence + +OKRs benefit from a structured review rhythm. + +Weekly check-ins. + +- Team reviews progress on each key result. 15-30 minutes. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Not for adjusting OKRs; for adjusting tactics to keep moving toward them. + +Mid-quarter review. + +- Roughly week 6 of the quarter. 60-90 minutes. +- Honest assessment of trajectory: which key results are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +End-of-quarter review. + +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +Quarterly retrospective. + +- Distinct from the scoring review. The retrospective examines the OKR practice itself: were the OKRs the right ones, did the cadence work, what should change. +- Often combined with the next-quarter OKR setting session. + +Detail in [`references/review-cadence-templates.md`](references/review-cadence-templates.md). + +--- + +## OKRs vs roadmap items vs metrics + +Three concepts often conflated. Each serves a different purpose. + +OKRs. Outcome targets for the quarter. "Improve activation for new sign-ups" is an OKR; "Increase first-week activation rate from 32% to 45%" is a key result. + +Roadmap items. Initiatives the team is building or doing. "Onboarding redesign" is a roadmap item. Roadmap items contribute to OKRs but are not the OKRs themselves. + +Metrics. Ongoing measurements the team tracks. "First-week activation rate" is a metric. Metrics inform key results (which are quarterly targets on metrics) and are tracked continuously regardless of whether the team has an OKR aimed at them. + +The relationship. + +- OKR: "Improve activation for new sign-ups." +- Key result: "First-week activation rate from 32% to 45%." +- Metric: "First-week activation rate" (tracked continuously). +- Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +Common conflations. + +- Treating roadmap items as OKRs. "Ship the onboarding redesign" as an OKR; the OKR should be the outcome the redesign is meant to produce. +- Treating every metric as needing an OKR. Some metrics matter for the team to track without setting quarterly targets on them. +- Treating OKRs as roadmap commitments. OKRs name outcomes; the team is committed to pursuing them but may shift tactics; treating OKRs as roadmap commitments locks in tactics that may need to change. + +Detail in [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-okr-failures.md`](references/common-okr-failures.md). + +- "Our OKRs are always 100% and produce no signal." Sandbagged. Set with stretch ambition; expect 60-70% scores. +- "Our OKRs are always 30% and demoralizing." Fantasy. Recalibrate to genuine stretch; investigate whether the targets are achievable in any realistic effort path. +- "Our key results measure work, not outcomes." Output-disguised-as-outcome. Rewrite key results to measure the result, not the work. +- "We have 12 OKRs and the team is working on 47 things." Too many OKRs; cap at 2-4 objectives, 3-5 KRs each. +- "Our OKRs are vague." Lack measurable targets; rewrite key results with specific numbers and thresholds. +- "Our cascading produces team OKRs that do not match team work." Strict cascading mismatched to team mandate; loosen cascading or change team mandate. +- "We never recalibrate even when the strategy shifts." Recalibration too tightly avoided; surface strategic-shift criteria and use them. +- "We recalibrate every quarter." Recalibration too easy; OKR design is failing; investigate. +- "Our weekly check-ins became status reports." Tactical-discussion missing; reform the check-in format. +- "Our scoring rounds up." Scoring discipline missing; commit to honest scoring. +- "OKRs and bonuses are tied; people sandbag." Predictable; decouple OKRs from compensation. + +--- + +## The framework: 12 considerations for OKR design + +When designing or auditing OKRs, walk these 12 considerations. + +1. Stretch, not sandbagged or fantasy. 60-70% average score target. +2. Objectives are outcomes, not outputs. What we are trying to achieve. +3. Few objectives, well-focused. 2-4 per team per quarter. +4. Key results are measurable. Specific numbers or testable thresholds. +5. Key results are outcome-aligned. Achieving them moves the objective forward. +6. Key results are within team influence. Not entirely dependent on external factors. +7. 3-5 key results per objective. Single key results are fragile; many dilute focus. +8. Cascading explicit but not over-constrained. Team OKRs ladder up but with autonomy on how. +9. Scoring honest, not rounded. 0.0-1.0 reflects actual outcomes. +10. Recalibration rare. OKRs hold absent strategic shift or major disruption. +11. Review cadence weekly + mid-quarter + end-of-quarter. Tactical, then strategic, then scoring. +12. OKRs separate from roadmap items and metrics. Each serves a different purpose. + +The output of the framework is OKRs that produce quarterly accountability infrastructure: ambitious goal-setting, mid-quarter learning, end-of-quarter scoring honest enough to inform the next quarter. + +--- + +## Reference files + +- [`references/objective-design-patterns.md`](references/objective-design-patterns.md) - Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. +- [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md) - Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. +- [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md) - When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. +- [`references/scoring-discipline.md`](references/scoring-discipline.md) - The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. +- [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md) - When to recalibrate vs adapt tactics. Strategic shift vs uncomfortable OKRs. The recalibration discipline. +- [`references/review-cadence-templates.md`](references/review-cadence-templates.md) - Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. +- [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md) - The three concepts and their relationships. Common conflations. The complete picture across all three. +- [`references/okr-anti-patterns.md`](references/okr-anti-patterns.md) - 8+ anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling. +- [`references/common-okr-failures.md`](references/common-okr-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: OKRs are accountability infrastructure + +OKRs at their best produce quarterly accountability that informs the org's strategic learning. The team commits to outcomes; works toward them; scores honestly; learns from the gap between target and outcome; designs the next quarter's OKRs better. + +OKRs at their worst produce ritual that consumes time without producing signal. Sandbagged OKRs that always hit. Fantasy OKRs that nobody can. Vague OKRs that score generously regardless of outcome. The vocabulary persists; the practice has decayed. + +The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, measurable key results, stretch ambition, scoring honesty, recalibration only when warranted, and the review cadence that drives learning rather than performance theater. + +When in doubt about whether an OKR practice is working, ask: do the OKRs drive decisions about what to prioritize, do the scores produce learning that informs the next quarter, are key results actually measuring outcomes the team can influence, is the average score in the 60-70% range that stretch OKRs target? If yes to all of those, the practice is real. If no to any, the gap is where the OKR work is failing to produce the accountability infrastructure it is meant to provide. diff --git a/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md b/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md new file mode 100644 index 0000000..9ce7eb6 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/cascading-okrs-decisions.md @@ -0,0 +1,187 @@ +# Cascading OKRs decisions + +When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. + +Cascading is one of the most contested OKR practices. Conference talks describe clean ladders from company to team to individual; in practice, strict cascading produces over-constrained team OKRs, while loose cascading produces team work disconnected from company priorities. The middle path is harder than the talks suggest. + +--- + +## The trade-off + +Cascading exists on a spectrum. + +Strict cascading. + +- Company sets OKRs. +- Each function (product, engineering, sales) cascades to function-level OKRs. +- Each team cascades to team OKRs. +- Each individual cascades to personal OKRs. +- All ladders trace cleanly upward. + +Loose cascading. + +- Company sets OKRs. +- Teams set their own OKRs informed by company priorities but with autonomy on scope and contribution. +- Teams may set OKRs not directly tied to company OKRs (technical debt, team-specific work). +- Individual OKRs often skipped. + +The trade-off. + +- Strict produces alignment but over-constrains. Teams set OKRs they think leadership wants rather than OKRs they can credibly commit to. +- Loose produces autonomy but risks misalignment. Team work optimizes locally without contributing to org goals. + +--- + +## When to cascade strictly + +Early-stage companies aligning around small priorities. When the company has 2-3 critical priorities and everyone needs to focus on them, strict cascading enforces the focus. + +Times of strategic shift. When the company is changing direction (new market, new segment, new product line), strict cascading helps the org turn together. + +Crisis or focus periods. When the company faces a specific challenge requiring all hands, strict cascading ensures everyone is rowing the same direction. + +Common to these cases: strategic clarity is high, alignment is more valuable than autonomy, and the org has fewer concurrent priorities to balance. + +--- + +## When to cascade loosely + +Mature organizations with established mandates. Teams have clear scope; their OKRs naturally fit company priorities through team mandate; strict cascading adds overhead without value. + +Cross-functional teams where strict cascading would over-constrain. Teams that span functions cannot cleanly ladder to a single function-level OKR; loose cascading lets them pursue cross-functional outcomes. + +High-trust environments. Teams trusted to set their own OKRs and credibly commit to them; the org accepts the autonomy in exchange for the engagement and creativity it produces. + +Common to these cases: team mandates are clear, autonomy is more valuable than tight alignment, and the org tolerates some local optimization in exchange for team engagement. + +--- + +## The middle path + +Most healthy OKR cultures sit between strict and loose. + +The pattern. + +- Company sets 3-5 OKRs at the start of the quarter. +- Teams set OKRs that explicitly identify which company OKRs they ladder up to (when applicable). +- Teams have autonomy on how to contribute (which key results, which initiatives, what scope). +- Some team OKRs are team-specific (technical debt, infrastructure, experimentation foundations) without direct company ladders. Surface these explicitly. +- Individual OKRs are usually skipped; commitment is at the team level. + +The "explicit ladder when applicable" rule. Each team OKR either: + +- Explicitly identifies the company OKR it ladders to. +- Explicitly identifies that it is team-specific without a company ladder. + +Both are honest; the failure mode is implicit ambiguity where the team is not sure whether their OKR connects to anything. + +--- + +## Worked example: middle path + +Company OKRs for Q3: + +1. Improve net new ARR through enterprise segment growth. +2. Improve activation for self-serve sign-ups. +3. Reduce infrastructure costs through architecture optimization. + +Product team OKRs: + +- "Improve activation for new sign-ups" (ladders to company OKR 2). +- "Establish enterprise-readiness foundations" (ladders to company OKR 1). +- "Reduce technical debt in the activation funnel" (team-specific; does not ladder directly). + +Engineering team OKRs: + +- "Ship onboarding redesign by week 6" (ladders to company OKR 2 via product team OKR). +- "Migrate to new search architecture" (ladders to company OKR 3). +- "Strengthen test coverage in critical paths" (team-specific). + +Sales team OKRs: + +- "Close 8 enterprise deals in Q3" (ladders to company OKR 1). +- "Improve discovery-call to demo conversion from 24% to 35%" (ladders to company OKR 1). +- "Build the design partner program" (team-specific). + +The pattern. Most team OKRs ladder up; some are team-specific. Each ladder is explicit. Teams have autonomy on how they contribute (which KRs, which initiatives). + +--- + +## Cascading anti-patterns + +Strict cascading enforced top-down without team input. Team OKRs become wishlist receivers from leadership; commitment is shallow because the team did not author what they are committing to. + +Loose cascading without explicit ladders. Team OKRs are set without any visible connection to company priorities. Some team work happens to align; some does not. Leadership cannot tell what is contributing to company OKRs. + +Cascade theater. OKR documents include ladders that look connected but do not actually drive anything. The team's work shows up the same regardless of which company OKR they "ladder to." + +Over-cascading. Every team OKR is required to ladder to a company OKR. Teams contort their work to fit. Team-specific work (technical debt, infrastructure) gets dressed up as ladder work or gets de-prioritized despite being important. + +Personal OKRs as default. Individual OKRs cascaded down. Most OKR cultures find this produces overhead without proportional value; commitment at team level is usually sufficient. + +--- + +## Cascading and team mandate + +Teams whose OKRs do not naturally ladder to company priorities often have a team-mandate problem. + +The signal. A team consistently sets OKRs that are team-specific. None of their work ladders to company priorities. + +The interpretation. + +- Possibly the team's mandate does not match the company's current priorities. Either the mandate should change (broader scope, different focus) or the team's work is not strategically critical (consider deprioritizing or restructuring). +- Possibly the team's work is foundational and supports many company priorities indirectly (platform teams, infrastructure teams). Their OKRs may legitimately be team-specific. + +The audit. Annually, review whether team mandates match company strategy. Teams whose mandates have drifted from strategy benefit from explicit redirection. + +--- + +## Cascading frequency + +The cascading work happens at OKR-setting time (start of quarter) and is generally locked for the quarter. + +Quarterly cascading. Most common. Company OKRs set; teams cascade; quarter executes. + +Mid-quarter cascade revision. Rare. Strategic shift mid-quarter may warrant rewriting team OKRs. See `mid-quarter-recalibration.md`. + +The honest frequency. Most orgs over-cascade in the first few quarters of OKR adoption (treating cascading as a thing to perfect) and learn to relax it. Some orgs never relax and produce increasingly performative cascading. Recognize the pattern; loosen when it stops adding value. + +--- + +## Cascading and individual goals + +Individual goals are usually a separate practice from OKRs. + +Common patterns. + +- Team OKRs commit at team level; individual contributors work toward team OKRs without separate personal OKRs. +- Individual goals (career development, skill-building, role expectations) live in performance management, separate from OKRs. +- Some orgs do cascade to individual OKRs; most find this produces overhead without value and stop after a few cycles. + +The discipline. Be intentional about whether to cascade to individuals. The default should be "no, commit at team level"; individual cascading should be justified rather than assumed. + +--- + +## Common cascading failures + +Top-down enforced cascading. Teams receive OKRs from leadership; commitment is shallow. + +Implicit cascading. Team OKRs do not explicitly identify their ladders; alignment is ambiguous. + +Over-cascading. Every team OKR forced to ladder to company; team-specific work dressed up artificially. + +Cascade theater. Ladders documented but not driving anything. + +Personal-OKR overhead. Individual cascading without proportional value. + +Mandate-strategy drift. Teams with mandates disconnected from current strategy producing OKRs that ladder to nothing. + +--- + +## Methodology-level choices that stay in the public skill + +The cascading trade-off. When to cascade strictly and loosely. The middle path with explicit ladders. Worked example. Cascading anti-patterns. Team mandate considerations. Cascading frequency. Individual goals separation. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that visualize ladders. Specific cascade-review meeting formats. Specific role-based templates. The team's own conventions for surfacing team-specific OKRs. These vary by org and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md b/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md new file mode 100644 index 0000000..675ddb3 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/common-okr-failures.md @@ -0,0 +1,205 @@ +# Common OKR failures + +Eleven-plus failure patterns with diagnoses and cures. Cross-references the OKR anti-patterns reference; this file covers operational failures that arise during the OKR cycle. + +The cross-cutting pattern: most OKR failures share a single root, which is treating OKRs as ceremony rather than as accountability infrastructure. + +--- + +## Failure 1: Our OKRs are always 100% and produce no signal + +Symptom. End-of-quarter scoring shows the team hitting 95%+ on every KR. The OKR practice feels positive but does not produce learning. + +Diagnosis. Sandbagging. Targets set at or below the team's natural trajectory. The OKR practice has decayed into "what we know we can hit." + +Cure. Set targets above the historical trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The target should be meaningfully above that. + +Prevention. Track the average score over multiple quarters. Drift toward 0.85+ is a sandbagging signal; intervene before the practice fully decays. + +--- + +## Failure 2: Our OKRs are always 30% and demoralizing + +Symptom. End-of-quarter scoring shows the team consistently missing OKRs. Team disengages from OKRs by mid-quarter. + +Diagnosis. Aspirational fantasy. Targets have no realistic effort path. The OKR practice has decayed into "inspirational numbers nobody believes." + +Cure. Recalibrate to genuine stretch. Validate against the effort-path test: can the team identify specific initiatives that would produce the target? + +Prevention. During OKR setting, require effort-path reasoning. If the team cannot articulate what work would produce the target, the target is fantasy. + +--- + +## Failure 3: Our key results measure work, not outcomes + +Symptom. KRs read as roadmap items. "Ship X by Y." "Run Z interviews." + +Diagnosis. Output-disguised-as-outcome. The team is committing to work, not to results. + +Cure. Rewrite each output KR to measure the outcome the output is meant to produce. The output itself lives in the roadmap. + +Prevention. During KR drafting, apply the outcome test: is this measuring a result, or counting work? + +--- + +## Failure 4: We have 12 OKRs and the team is working on 47 things + +Symptom. Quarterly OKRs span many objectives and KRs; the team's work is scattered across many priorities. + +Diagnosis. OKR proliferation. Too many objectives produces no focus. + +Cure. Cap at 2-4 objectives, 3-5 KRs each. Surface deferred work explicitly so the team can see what they are choosing not to commit to. + +Prevention. Cap OKRs at the start of the cycle. Adding "just one more" OKR is a recurring pressure that should be resisted. + +--- + +## Failure 5: Our OKRs are vague + +Symptom. Objectives like "improve user experience" or KRs like "make activation better." Cannot be scored honestly. + +Diagnosis. Lack of measurable specificity. + +Cure. Rewrite KRs with specific numbers, baselines, and targets. "Increase first-week activation rate from 32% to 45%" instead of "improve activation." + +Prevention. During KR review, apply the specificity test: could two reasonable people disagree on whether this KR was hit at end of quarter? If yes, it is too vague. + +--- + +## Failure 6: Our cascading produces team OKRs that do not match team work + +Symptom. Team OKRs cascade to company OKRs but the team's actual capacity and mandate produce different work. + +Diagnosis. Strict cascading mismatched to team mandate. + +Cure. Loosen cascading; allow team-specific OKRs that do not directly ladder. Or change team mandate if it does not match strategy. + +Prevention. Use the middle path on cascading. Surface team-specific OKRs explicitly. + +--- + +## Failure 7: We never recalibrate even when the strategy shifts + +Symptom. The org's strategy changed mid-quarter. Team OKRs no longer reflect strategy. The team holds them anyway. + +Diagnosis. Recalibration too tightly avoided. + +Cure. Surface the strategic shift; recalibrate the affected OKRs explicitly. Document the trigger. + +Prevention. Make strategic-shift criteria for recalibration explicit. The team should know when recalibration is appropriate. + +--- + +## Failure 8: We recalibrate every quarter + +Symptom. OKRs get revised mid-quarter routinely. The team uses recalibration to soften uncomfortable OKRs. + +Diagnosis. Recalibration too easy. OKR design is failing or stretch ambition is being avoided. + +Cure. Hold OKRs absent the recalibration triggers (strategic shift, major disruption, invalidating information). Investigate why frequent recalibration is happening. + +Prevention. Track recalibration frequency. Drift toward "every quarter recalibrates" is a signal to intervene. + +--- + +## Failure 9: Our weekly check-ins became status reports + +Symptom. Weekly OKR check-ins lost their tactical decision focus; they became "here's what I did this week" updates. + +Diagnosis. Check-in format drift. The session is no longer producing tactical adjustments. + +Cure. Reform the format. Per KR: trajectory, blockers, planned work for the upcoming week. End with explicit commitments. + +Prevention. The team lead facilitates the check-in's tactical scope. Status reports happen elsewhere. + +--- + +## Failure 10: Our scoring rounds up + +Symptom. End-of-quarter scoring shows 0.85 average. Closer inspection shows scores were rounded up across most KRs. + +Diagnosis. Generous scoring. Honesty has decayed. + +Cure. Commit to honest scoring. A 0.55 KR scores 0.55, not 0.6. Document context; the context surfaces what produced the actual outcome regardless of the number. + +Prevention. Surface the rounding pattern explicitly. The team should know that rounding up is the failure mode. + +--- + +## Failure 11: OKRs and bonuses are tied; people sandbag + +Symptom. OKR scores directly determine bonuses. Targets set conservatively; scoring round up; stretch ambition gone. + +Diagnosis. Compensation coupling. + +Cure. Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs. + +Prevention. Establish from the start that OKRs are accountability infrastructure, not performance management. Compensation tied loosely or not at all. + +--- + +## Failure 12: OKRs were set but never referenced + +Symptom. OKRs documented at start of quarter. Mid-quarter prioritization debates ignore them. End-of-quarter scoring is generous because nobody tracked rigorously. + +Diagnosis. OKR theater. The practice produces overhead without value. + +Cure. Reform the cadence. Weekly check-ins reference OKRs explicitly. Mid-quarter review uses OKRs as the assessment lens. Scoring informs next quarter. + +Prevention. Tie OKRs to specific decisions. If OKRs are not load-bearing for prioritization, surface the disconnect and reform or abandon. + +--- + +## Failure 13: KRs depend on factors outside team influence + +Symptom. KRs miss because of external factors the team could not affect (market conditions, sales execution, infrastructure issues). The team cannot credibly own the KR. + +Diagnosis. KR design failure. Targets set on outcomes the team cannot meaningfully drive. + +Cure. Rewrite to focus on what the team can move. The team's contribution to a larger outcome may be the right KR, not the larger outcome itself. + +Prevention. During KR design, validate that the team can identify how their work moves the KR. + +--- + +## Failure 14: Cross-team OKRs produce coordination failures + +Symptom. Multiple teams have KRs aimed at the same outcome. Teams pursue independently; the outcome lags because nobody owns the integration. + +Diagnosis. Cross-team coordination missing. Either single ownership should have been assigned, or split KRs need stronger coordination. + +Cure. Establish single ownership for outcome OKRs that span multiple teams. Or use split-KR pattern where each team's KR is their specific contribution. + +Prevention. During OKR design, surface cross-team dependencies. Decide single-owner or split-KR explicitly. + +--- + +## Failure 15: OKRs are roadmap commitments to stakeholders + +Symptom. Stakeholders treat OKRs as commitments to specific work. Mid-quarter tactical adjustments feel like broken promises. + +Diagnosis. OKR-as-roadmap conflation. Stakeholders interpret outcomes as outputs. + +Cure. Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Both are visible; the OKR is the accountability; the roadmap is the team's current best guess at what work will produce the outcome. + +Prevention. When communicating OKRs to stakeholders, explicitly surface the distinction. Use different vocabulary. + +--- + +## The cross-cutting pattern + +Most OKR failures share a single root: treating OKRs as ceremony rather than as accountability infrastructure. + +Ceremony focuses on the appearance of OKR practice: documents produced, meetings held, scores generated. Accountability focuses on the work the practice is meant to support: stretch goal-setting, mid-quarter learning, end-of-quarter scoring honesty, next-quarter improvement. + +The fix for almost any OKR failure starts with the same question: what decision is this OKR practice supposed to inform? When the answer is clear, the practice becomes load-bearing. When the answer is "we should follow the OKR process," the practice becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-accountability pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md b/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md new file mode 100644 index 0000000..8ad33d3 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/key-result-design-patterns.md @@ -0,0 +1,242 @@ +# Key result design patterns + +Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. + +Key results are where the OKR practice succeeds or fails operationally. Objectives can be inspiring without measurable; key results have to be measurable. Most OKR failure at the operational level shows up in the key result design. + +--- + +## The four characteristics of strong key results + +Measurable. A specific number, percentage, or testable threshold. + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." + +Outcome-aligned. Achieving the key result actually moves the objective forward. + +- For the activation objective, the key results above are aligned: they all measure aspects of activation. +- A key result like "ship the onboarding redesign" is not outcome-aligned; it measures the work, not the activation outcome. + +Within team influence. The team can affect the key result through their work. + +- "First-week activation rate" is influenced by onboarding design, welcome email content, in-product guidance. The team can affect it. +- "Total signups" depends primarily on marketing acquisition; the activation team's onboarding work affects it weakly. Not a strong key result for the activation team. + +Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +- "Increase first-week activation rate from 32% to 45% by end of Q3." +- "Reach 80% completion rate by week 10 of the quarter." + +The four characteristics together produce key results the team can commit to credibly and measure honestly. + +--- + +## Strong key result examples by objective + +Objective: "Improve activation for new sign-ups so more reach value-realization in week one." + +Strong KRs: + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." +- "Reduce signup-to-first-key-action time from 8 minutes to under 4 minutes." + +Each measures an aspect of activation. The team can influence each through their work. Each has a baseline and target. + +Objective: "Make support experience deflect predictable issues." + +Strong KRs: + +- "Reduce ticket volume on the top 3 deflection-eligible categories by 40%." +- "Increase self-service resolution rate from 22% to 38%." +- "Maintain CSAT at or above 4.4/5 (no degradation while deflecting)." + +The third KR matters: deflecting tickets without protecting CSAT could damage the experience; the KR keeps both in scope. + +Objective: "Establish enterprise-readiness foundations." + +Strong KRs: + +- "Pass SOC 2 Type II audit with zero high-severity findings." +- "Complete admin role and permissions overhaul; reach 95% of enterprise-prospect compliance checklist items." +- "Onboard 3 design partners from the enterprise segment to the alpha enterprise build." + +Each measures a foundation outcome the enterprise readiness depends on. + +--- + +## Weak key result examples + +Vague. + +- "Improve activation significantly." +- "Reduce ticket volume." + +No specific number; cannot be scored honestly. + +Output disguised as outcome. + +- "Ship 5 onboarding redesign initiatives." +- "Run 12 customer interviews." + +Counts work done, not outcomes produced. The team can hit these by doing work without producing the outcome the objective targets. + +Outside influence. + +- "Increase total signups by 50%." +- "Maintain market share." + +Total signups are upstream of activation work; market share depends on competitive dynamics largely outside the team's control. + +Vanity. + +- "Reach 1M users." +- "Reach 10K NPS responses." + +Impressive numbers; not directly tied to the outcome the objective targets. + +Single-data-point dependent. + +- "Have one customer reference our product publicly." + +Fragile; a single data point may not represent progress. + +--- + +## The 3-5 key results rule + +Most objectives benefit from 3-5 key results. + +Why not 1. Single key results are fragile. If the metric does not move for reasons outside the team's tactical choices, the team has no way to show progress on the objective. Multiple KRs triangulate. + +Why not 6+. Too many KRs dilute focus. The team scatters attention across many metrics; trade-offs across KRs become impossible because all are claimed as priority. + +The 3-5 sweet spot. + +- Enough KRs to triangulate the outcome. +- Few enough that the team can pay attention to each. +- Allows for KRs that protect against unintended degradation (e.g., deflect tickets while protecting CSAT). + +The KR composition. + +- 1-2 KRs measure the primary outcome. +- 1-2 KRs measure secondary aspects of the outcome. +- 0-1 KRs protect against unintended consequences. + +--- + +## Baseline and target setting + +Each KR needs a baseline and target. + +Baseline. The current value of the metric. Pulled from analytics or recent measurement; should be honest, not aspirational. + +Target. The value the team commits to reaching by end of quarter. + +Setting the target. + +- Stretch: target a value that requires real work to reach. Should hit 60-70% of the time on average across KRs. +- Not sandbagged: target should not be where the team would land without focused effort. +- Not fantasy: target should be reachable through realistic effort paths the team can identify. + +The historical-trajectory test. Look at the metric over the past 4 quarters. Where would the metric be at end of next quarter on its current trajectory? The target should be meaningfully above that trajectory; otherwise, the OKR is sandbagged. + +The effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, the target is fantasy. + +--- + +## Leading vs lagging key results + +Key results can measure leading indicators (early signals) or lagging indicators (final outcomes). + +Lagging. The outcome the team ultimately wants. "First-week activation rate" measures the activation outcome. + +Leading. Early signals that the lagging outcome will move. "Onboarding flow completion rate" leads first-week activation rate. + +The blend. + +- Some KRs measure leading indicators (so the team has signal early in the quarter). +- Some KRs measure lagging indicators (so the team is accountable to the actual outcome). +- A blend produces both early signal and end-of-quarter accountability. + +The lagging-only failure. OKRs that only measure lagging indicators produce no mid-quarter signal. The team cannot tell if they are on track until end of quarter. + +The leading-only failure. OKRs that only measure leading indicators produce no end-of-quarter accountability. Leading indicators can move without lagging indicators following. + +--- + +## When binary KRs are appropriate + +Most KRs are quantitative (a number to reach). Some are binary (a milestone to achieve). + +When binary works. + +- Audit-pass milestones: "Pass SOC 2 Type II with zero high-severity findings." +- Foundational milestones: "Complete admin role overhaul." +- Launch milestones: "Ship the activation redesign to all users." + +When binary fails. + +- Used for KRs that should be quantitative. "Successfully implement activation improvements" is binary disguised as outcome; should be quantitative. +- Used to dodge measurement. Binary KRs that are not actually milestones become "we did it" claims without underlying outcome verification. + +The discipline. Use binary KRs sparingly and only when the milestone genuinely is the outcome. Most outcome KRs benefit from quantitative measurement. + +--- + +## KRs across teams + +When multiple teams contribute to the same outcome, KRs need careful design. + +The split-KR pattern. Each team has KRs that contribute to the cross-team outcome. + +- Product team KR: "Increase first-week activation rate from 32% to 45%." +- Engineering team KR: "Ship onboarding redesign by week 6 of the quarter." +- Customer success team KR: "Reduce activation-related support ticket volume by 30%." + +Each team is accountable for its contribution; the cross-team outcome benefits from all. + +The single-owner pattern. One team owns the outcome KR; other teams support without explicit KRs on the same metric. + +- Product team owns the activation KR. +- Engineering and CS support without separate KRs. +- Cross-team coordination happens outside the OKR structure. + +The discipline. Pick a pattern. Hybrid approaches (sometimes shared KRs, sometimes single-owner) produce confusion about accountability. + +--- + +## Common KR design failures + +Output KRs. Counts of work shipped instead of outcomes produced. Cure: rewrite. + +Vague KRs. Lack measurable targets. Cure: specify number and threshold. + +Out-of-influence KRs. Depend on factors the team cannot affect. Cure: rewrite to what the team can move. + +Vanity KRs. Impressive numbers not tied to outcome. Cure: tie to the actual outcome. + +Too few KRs. Single KR fragility. Cure: 3-5 KRs per objective. + +Too many KRs. 6+ KRs dilute focus. Cure: cap at 5. + +No baseline. "Reach X" without naming current value. Cure: include baseline. + +Sandbagged targets. Targets at or below current trajectory. Cure: stretch beyond what the team would do without focus. + +Fantasy targets. Targets with no realistic effort path. Cure: validate against effort-path test. + +Lagging-only. No leading indicators. Cure: add leading-indicator KRs. + +--- + +## Methodology-level choices that stay in the public skill + +The four characteristics. Strong and weak KR examples. The 3-5 KR rule. Baseline and target setting. Leading vs lagging KRs. Binary KRs when appropriate. Cross-team KR patterns. Common failures. + +## Implementation choices that stay internal + +Specific KR templates. Specific metrics tooling and dashboards. Specific historical-trajectory analysis. Specific KR scorecards. The team's own conventions for KR wording. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md b/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md new file mode 100644 index 0000000..91b96a0 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/mid-quarter-recalibration.md @@ -0,0 +1,214 @@ +# Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. Strategic shift vs uncomfortable OKRs. The recalibration discipline. + +The default is that OKRs hold for the quarter. Teams adapt their tactics; OKRs do not change to match what the team is doing. Recalibration is the exception, not the rule. Recalibrating frequently signals OKR design failure. + +--- + +## The default: OKRs hold + +OKRs are quarterly commitments. The team commits at the start of the quarter and works toward them through the quarter regardless of whether progress feels comfortable. + +Why holding matters. + +- OKRs are accountability infrastructure. Changing them mid-quarter weakens the accountability. +- Stretch OKRs are uncomfortable by design. The discomfort is the work. +- Teams that recalibrate when uncomfortable train themselves to recalibrate as a coping mechanism. + +Adapting tactics, not OKRs. + +- The OKR target stays. +- The team's tactics for reaching the target adapt as they learn what works. +- New initiatives may be launched; existing ones may be scrapped; the OKR remains the destination. + +--- + +## When to recalibrate + +Three conditions warrant recalibration. + +### Strategic shift + +The company's strategy changed materially mid-quarter. OKRs that no longer reflect the strategy are no longer the right targets. + +Examples. + +- The company pivoted to a new market segment; OKRs aimed at the prior segment are no longer strategic. +- A major acquisition or restructure changed the team's mandate. +- Leadership announced a new strategic priority that supersedes the quarter's OKRs. + +The handling. Recalibrate explicitly. Document what changed strategically and how OKRs are revised. Communicate to stakeholders so the recalibration is visible and intentional. + +### Major external disruption + +A market change, regulatory event, or significant outage warrants resetting the quarter's targets. + +Examples. + +- A major outage consumed weeks of engineering capacity that was meant for OKR work. +- Regulatory changes required compliance work that displaced planned OKRs. +- Market conditions shifted dramatically (recession, supply chain disruption) and the OKRs no longer reflect realistic ambition for the new conditions. + +The handling. Recalibrate explicitly. Surface the disruption and its impact. Set new targets that reflect the post-disruption reality. + +### Information that invalidates the OKR + +The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +Examples. + +- Analytics work revealed that the activation metric the team was targeting is not the right measure of activation success; a better metric exists. +- Customer research revealed that the user segment the team was prioritizing is smaller or less important than expected. +- Technical investigation revealed that the planned approach to an OKR has fatal limitations that were not visible at planning time. + +The handling. Recalibrate explicitly. Document what was learned. Set new OKRs reflecting the new understanding. + +--- + +## When NOT to recalibrate + +Three patterns that look like recalibration triggers but are not. + +### The team is not on track + +OKRs that the team is missing should remain as set; the miss is the signal. + +Why. Stretch OKRs are designed to miss sometimes. Hitting 60-70% on average means roughly 30-40% of KRs miss the target. The miss is informative; lowering the target to match the trajectory eliminates the signal. + +The cure. Hold the OKR. Score honestly at end of quarter. Use the miss to inform next quarter's design. + +### The OKR is uncomfortable + +Teams uncomfortable with stretch OKRs sometimes want to recalibrate to feel better. + +Why. Stretch is uncomfortable by design. Teams that learn to lower OKRs when uncomfortable lose the stretch discipline; OKRs drift toward sandbagging quarter over quarter. + +The cure. Hold the OKR. Acknowledge the discomfort. Surface what the team would need to push toward the target. Use the discomfort productively rather than recalibrating it away. + +### Easier OKRs would feel achievable + +The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +Why. Hard OKRs are the point. Swapping for easier ones removes the accountability infrastructure stretch OKRs provide. + +The cure. Hold the OKR. If the original was genuinely fantasy (no realistic effort path), recalibrate per the strategic-shift pattern. If the original was genuine stretch but uncomfortable, hold. + +--- + +## The recalibration discipline + +When recalibration is warranted, the discipline matters. + +Surface the trigger. What changed? Strategic shift, external disruption, or invalidating information. Be specific. + +Document the original target and the revised target. The history of recalibration is part of the OKR record. Future audits should be able to see what changed. + +Explain the new target. Why this revised target? What effort path produces it? How does it reflect the new reality? + +Communicate to stakeholders. Recalibration is visible. Stakeholders who expected the original target should know it changed and why. + +Score against the revised target at end of quarter. The recalibrated OKR is the OKR for scoring purposes. Do not score against the original. + +--- + +## Frequency of recalibration + +Recalibration should be rare. + +Healthy frequency. 1-2 quarters out of 8 may include recalibration on at least one OKR. Most quarters should have no recalibrations. + +Concerning frequency. Every quarter includes recalibration on some OKR. This signals either: + +- The OKR design is consistently aggressive (fantasy targets). +- The strategy is shifting too frequently (lack of strategic stability). +- The team has learned to recalibrate as a coping mechanism for stretch. + +The diagnosis. Frequent recalibration is a signal to investigate, not a feature to lean into. The investigation surfaces whether the issue is OKR design, strategic stability, or team behavior. + +--- + +## Recalibration as honest tool vs avoidance + +The line between honest recalibration and avoidance. + +Honest recalibration. + +- The trigger is specific and external (strategic shift, disruption, invalidating information). +- The revised target reflects the new reality, not the team's preference. +- The recalibration is documented and visible. + +Avoidance dressed as recalibration. + +- The trigger is vague ("things changed"). +- The revised target is conveniently achievable. +- The recalibration happens when the OKR is uncomfortable, not when external conditions warrant it. + +The honest test. If a stakeholder asked the team to defend the recalibration, could the team point to a specific external trigger? If the answer is "we just thought the target was too ambitious," the recalibration is avoidance. + +--- + +## Recalibration in the OKR system + +How recalibration affects the broader OKR practice. + +Trust effects. + +- Recalibration that is rare and well-justified preserves trust in OKRs. +- Recalibration that is frequent or poorly justified erodes trust; stakeholders learn to expect targets to slide. + +Org-wide signaling. + +- One team's recalibration affects how other teams perceive recalibration norms. +- Leaders that recalibrate strict targets signal to teams that recalibration is acceptable; teams take the cue. +- Leaders that hold targets even when uncomfortable signal that stretch is real; teams take that cue. + +The practice's calibration over time. Recalibration norms accumulate. Healthy practices stay disciplined; decaying practices loosen. The annual review of OKR practice should look at recalibration frequency as one signal of practice health. + +--- + +## Communicating recalibration + +When recalibration happens, communication matters. + +To the team. + +- Surface the trigger before the recalibration is decided. The team should understand what changed. +- Discuss the revised target before committing. The team should be able to commit credibly to the new target. +- Document the change in the OKR system. + +To stakeholders. + +- Notify stakeholders explicitly. Do not let recalibration appear as a quiet edit. +- Explain the trigger and the revised target. +- Invite questions; stakeholder concerns may surface issues with the recalibration that warrant further discussion. + +To the org. + +- Recalibration patterns inform org-wide OKR discussion. If multiple teams recalibrate in the same quarter, surface the pattern; the strategic clarity may be lacking. + +--- + +## Common recalibration failures + +Recalibration as the default. Teams routinely revise OKRs mid-quarter. The OKR system collapses into rolling targets that always reflect current state. + +Recalibration to avoid stretch discomfort. Teams revise when OKRs feel uncomfortable; targets drift toward sandbagging. + +Recalibration without trigger documentation. OKRs change without surfaced reason; the change becomes invisible to stakeholders. + +Refusal to recalibrate when warranted. Teams hold OKRs even when strategy genuinely shifted; quarter ends with OKRs disconnected from strategy. + +Recalibration to avoid scoring low. Teams revise targets in the last weeks of the quarter to make the score look better. Scoring loses honesty. + +Org-wide recalibration cascade. One team's recalibration triggers others; the whole quarter resets; the OKR system loses meaning. + +--- + +## Methodology-level choices that stay in the public skill + +The default-to-hold principle. When to recalibrate (strategic shift, major disruption, invalidating information). When not to recalibrate (uncomfortable, off-track, easier-feels-better). The recalibration discipline. Frequency norms. Honest vs avoidance recalibration. Communication. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that capture recalibration history. Specific approval workflows for recalibration. The team's own conventions for recalibration communication. These vary by org. diff --git a/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md b/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md new file mode 100644 index 0000000..e1fc8fa --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/objective-design-patterns.md @@ -0,0 +1,191 @@ +# Objective design patterns + +Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. + +Objectives are the outcome statements that name what the team is trying to achieve in the quarter. Most OKR failure begins at the objective level: outputs disguised as outcomes, vague aspirations, or too many objectives diluting focus. Getting the objective right is upstream of everything else. + +--- + +## Outcome vs output + +The most consequential distinction. + +Output objectives. Describe work the team plans to do. + +- "Ship the activation redesign." +- "Migrate to the new auth service." +- "Run 12 customer interviews." + +Outcome objectives. Describe results the team is trying to achieve. + +- "Improve activation for new sign-ups so more reach value-realization in week one." +- "Establish auth foundations that support enterprise compliance review." +- "Build a research-grounded picture of how mid-market customers actually use the product." + +Why the distinction matters. Outputs can be shipped without producing outcomes. The activation redesign ships; activation rate stays the same. The auth migration completes; compliance review still fails. The interviews happen; the team cannot point to decisions that changed. + +The output-as-outcome failure. Output objectives shift the team's incentives toward shipping rather than achieving. The team optimizes for the work; the work gets done; the underlying goal goes unachieved. + +The cure. Each output objective gets rewritten to name the outcome the output is meant to produce. If the team cannot name the outcome, the output's value is unclear and may not warrant quarterly priority. + +--- + +## Strong objective characteristics + +Outcome-focused. Names the result, not the work. + +Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. The objective should be specific enough that the team knows when they have moved it forward. + +Inspiring without being fantasy. The team should feel pulled toward the objective. Fantasy demoralizes; sandbag bores. Stretch motivates. + +Few in number. 2-4 objectives per team per quarter. More dilutes focus; the team works on too many things and excels at none. + +Connected to strategy. Objectives ladder up to company-level priorities or to the team's strategic mandate. Disconnected objectives produce work that does not contribute to the org's direction. + +Within team influence. The team can affect the outcome through their work. Objectives entirely dependent on external factors are not the team's to commit to. + +--- + +## Weak objective characteristics + +Output-disguised-as-outcome. "Ship the redesign" is the work; the outcome should be the result the redesign produces. + +Too vague. "Improve user experience" is too broad to focus a quarter's work. What aspect of UX, in what part of the product, for which users? + +Too tactical. "Refactor the auth service" is a tactical decision the team makes within larger initiatives, not a quarterly objective. + +Too many. 8 objectives produces no focus. Each objective gets less attention; trade-offs become impossible because everything is priority. + +Disconnected from strategy. Objectives that do not ladder to company priorities or team mandate produce work that does not contribute. + +Outside team influence. "Total revenue grows 30%" may not be the product team's to commit to if revenue depends on sales execution, market conditions, and product work combined. + +--- + +## Worked objective examples by domain + +### B2B SaaS product team + +- "Improve activation for new sign-ups so that more reach the value-realization moment within their first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +### Consumer mobile app team + +- "Increase retention through the first month so users build habit before the typical churn window." +- "Improve performance and reliability so the experience matches the brand's reputation." + +### Internal platform team + +- "Reduce the time it takes engineering teams to ship a new service from days to under a day." +- "Eliminate the top three reasons engineering teams escalate to platform support." + +### Marketing-product team + +- "Convert more product trial users to paid by removing friction in the upgrade path." +- "Position the product clearly enough that prospects evaluating against alternatives understand the differentiation." + +Each objective is outcome-focused, specific to the quarter, and within the team's ability to influence. The work that produces these outcomes is multiple roadmap items; the OKR is the result, not the work. + +--- + +## The few-objectives discipline + +Most teams should have 2-4 objectives per quarter. The discipline produces focus. + +Why fewer is better. + +- Each objective gets serious attention. The team thinks about it weekly, makes trade-offs against it, surfaces blockers. +- Trade-offs are possible. With 3 objectives, the team can decide that work on objective A takes priority over work on objective C this week. With 12 objectives, all work claims priority. +- The team can credibly commit. 3 objectives are credible; 12 are not. + +Why more feels tempting. + +- Multiple stakeholders want their priorities reflected. Adding objectives feels like accommodating; capping objectives feels like saying no. +- The team sees many things they could pursue. Picking 3 means deferring others. +- Past quarters' OKRs sometimes accumulate; teams forget to retire objectives that no longer fit. + +The discipline. + +- Cap objectives. 4 is the upper bound for most teams. +- Surface what is being deferred. The objectives that did not make the cut get named explicitly; the team's choice to defer is transparent. +- Retire objectives quarter-over-quarter. Objectives are quarterly; they do not carry over by default. + +--- + +## Objectives across an org + +When the org has multiple teams, objectives should compose without overlap or contradiction. + +Cross-team coordination. + +- Objectives that depend on multiple teams should name the dependencies explicitly. The product team's objective may depend on engineering hiring; the engineering team's objective may depend on product prioritization. +- Objectives that conflict across teams need resolution before the quarter starts. Teams pulling in opposite directions waste capacity. + +Team mandate alignment. + +- Each team's objectives should fit the team's mandate. Product team objectives are product outcomes; engineering team objectives are engineering outcomes; design team objectives are design outcomes. +- Cross-functional outcomes (e.g., "improve activation") require multiple teams to commit. The lead team owns the OKR; the supporting teams commit dependencies in their own OKRs. + +--- + +## Objective writing process + +How objectives get drafted. + +Draft sources. + +- Strategy work that named the priorities for the quarter or year. +- Discovery synthesis that identified user-job priorities. +- Roadmap-planning work that surfaced major initiatives. +- Performance review that identified gaps from the prior quarter. + +Draft method. + +- Start from the outcome the team is trying to produce. +- Surface multiple draft phrasings. +- Test each: is this an outcome or an output? Is it specific enough? Is it within team influence? +- Iterate to a 2-4 objective set that the team can commit to and that ladders to strategy. + +Stakeholder review. + +- Draft objectives circulate to stakeholders before commit. Surfaces dependencies and conflicts. +- Stakeholder feedback informs revisions; the team owns the final commit. + +The commitment. Objectives published and visible to the org. The team is on the hook for them. + +--- + +## Objective revision through the quarter + +Objectives generally hold for the quarter. See `mid-quarter-recalibration.md` for when revision is appropriate. + +The default. Objectives stay; tactics adapt to keep moving toward them. + +The exception. Strategic shift, major external disruption, or invalidating information warrants revision. Rare. + +--- + +## Common objective design failures + +Output objectives. "Ship X" instead of "Achieve outcome Y through X." Cure: name the outcome. + +Vague objectives. "Improve experience" without specifying what or where. Cure: specificity. + +Too many objectives. 8+ per team per quarter. Cure: cap at 4. + +Tactical objectives. Specific implementation decisions framed as objectives. Cure: tactical decisions belong in roadmap items, not OKRs. + +Strategic-disconnect. Objectives that do not ladder to company or team priorities. Cure: explicit ladder before commit. + +Out-of-influence. Objectives entirely dependent on factors the team does not control. Cure: rewrite to focus on what the team can affect. + +--- + +## Methodology-level choices that stay in the public skill + +The outcome-vs-output distinction. Strong and weak objective characteristics. Worked examples across domains. The few-objectives discipline. Cross-team coordination. The drafting and review process. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools the team uses. Specific document templates for objectives. Specific stakeholder-review formats. The team's own conventions for objective wording within the principles. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md b/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md new file mode 100644 index 0000000..f70fe2f --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/okr-anti-patterns.md @@ -0,0 +1,249 @@ +# OKR anti-patterns + +Eight-plus anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling, and others. Each anti-pattern names a recurring failure mode that decays OKR practice over time. + +--- + +## Anti-pattern 1: OKR-as-roadmap + +The pattern. OKRs are written as a list of features the team plans to ship. + +Examples. + +- "Objective: Ship the activation redesign. KR: Activation redesign launched by week 8. KR: Welcome email v2 launched by week 4." + +Why it fails. + +- Outputs disguised as outcomes. The team is committing to work, not to results. +- The outcome the work is meant to produce goes unspecified; the team can ship the redesign without producing the activation outcome. +- OKRs become roadmap commitments to stakeholders; mid-quarter tactical changes feel like broken promises. + +The cure. Each OKR names the outcome the work is meant to produce. The work itself lives in the roadmap. + +--- + +## Anti-pattern 2: Sandbagging + +The pattern. OKRs designed to hit 100%. Targets at or below the team's current trajectory. + +How it manifests. + +- KR targets within 5% of current values. +- KR targets achievable on standard execution without focused effort. +- Average end-of-quarter scores at 95%+. +- Team consistently celebrates "hitting all our OKRs." + +Why it fails. + +- No stretch; no learning. The team did not commit to ambition; the OKR practice produced no signal beyond what the team would have done anyway. +- Sandbagging compounds. Teams that sandbag once learn that sandbagging is safe; subsequent quarters get worse. +- Stakeholder trust degrades. Stakeholders learn that "hitting OKRs" does not mean ambitious work was done. + +The cure. Set targets above the team's current trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The OKR target should be meaningfully above that. + +--- + +## Anti-pattern 3: Aspirational fantasy + +The pattern. OKRs that nobody can hit. Targets with no realistic effort path. + +How it manifests. + +- KR targets at 5x or 10x current values without underlying capacity changes. +- Targets set for inspiration rather than commitment. +- Average end-of-quarter scores at 30% or below. +- Team disengages from OKRs by week 3-4 of the quarter. + +Why it fails. + +- Demoralizing. Teams cannot hit fantasy targets; the targets become decoration. +- Loss of meaning. When OKRs cannot be hit, scoring loses meaning; teams stop tracking. +- Compensation distortion. If OKRs are tied to compensation, fantasy targets create unfairness; teams cannot earn rewards regardless of effort. + +The cure. Validate against the effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, recalibrate. + +--- + +## Anti-pattern 4: Vanity metrics + +The pattern. KRs that measure impressive numbers not tied to the outcome. + +Examples. + +- "Reach 1M users." +- "Generate 10K leads." +- "Reach 500K social followers." + +Why it fails. + +- Numbers can be moved without producing the outcome the OKR was meant to address. +- Vanity targets often correlate with marketing or acquisition spend rather than with product outcomes. +- The team can hit vanity KRs while the underlying outcome (engagement, retention, revenue) does not improve. + +The cure. Each KR should connect to the outcome the OKR targets. If the connection is unclear, the KR is probably vanity. Replace with a KR that more directly measures the outcome. + +--- + +## Anti-pattern 5: OKR theater + +The pattern. OKRs are documented and presented but do not drive decisions. + +How it manifests. + +- OKRs are set at the start of the quarter and not referenced again until end of quarter. +- Mid-quarter prioritization decisions ignore OKRs. +- The team makes the same prioritization choices that they would have made without OKRs. +- OKR scores are produced at end of quarter but do not inform the next quarter's planning. + +Why it fails. + +- The OKR practice produces overhead without value. The team spends time on OKR ceremony without changing what they would have done. +- Stakeholder skepticism builds. Stakeholders learn that OKRs are not load-bearing. +- The practice decays further over time as the team rationalizes that the ceremony does not matter. + +The cure. Tie OKRs to specific decisions. Mid-quarter prioritization debates should reference OKRs. Roadmap items should map to OKRs. Scoring should inform the next quarter. If none of these happen, the OKR practice is theater; reform or abandon. + +--- + +## Anti-pattern 6: Compensation coupling + +The pattern. OKR scores directly determine bonuses or performance ratings. + +Why it fails. + +- Sandbagging incentives become severe. Teams set OKRs they know they can hit to protect their compensation. +- Honest scoring suffers. Teams round scores up to avoid compensation impact. +- Stretch ambition disappears. The OKR practice collapses to "what we are confident we can hit." +- Team trust in OKRs degrades; the practice becomes performance management theater. + +The cure. Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs (manager assessment, peer feedback, role expectations); OKR scores may be one input but should not be dominant. + +The transition. Orgs that have coupled OKRs and compensation need explicit decoupling communication. Teams need to trust that scoring honestly will not affect bonuses; the trust takes 2-3 cycles to establish. + +--- + +## Anti-pattern 7: OKR proliferation + +The pattern. Teams set 8-12 OKRs per quarter. Every team member's work is reflected in some OKR. + +Why it fails. + +- Focus dilutes. The team works on too many things; trade-offs become impossible because everything is priority. +- Tracking burden grows. Weekly check-ins become status reports across too many KRs. +- Scoring becomes performative. Teams cannot honestly score 40+ KRs at end of quarter. + +The cure. Cap OKRs. 2-4 objectives per team; 3-5 KRs per objective. Surface what is not in OKRs as deferred work that the team is choosing not to commit to this quarter. + +--- + +## Anti-pattern 8: Cascade theater + +The pattern. OKR documents include cascading ladders that look connected but do not actually drive work. + +How it manifests. + +- Team OKRs claim ladders to company OKRs but the team's actual work would have happened regardless. +- Cascading documents look impressive but do not coordinate cross-team work. +- The cascade is performed for stakeholders rather than for execution. + +Why it fails. + +- Cascading work is overhead without value. +- Cross-team coordination does not actually happen through the cascade. +- Stakeholders learn that the cascade is theater. + +The cure. Make ladders explicit only when they genuinely connect. Loosen cascading where strict ladders produce theater. See `cascading-okrs-decisions.md` for the discipline. + +--- + +## Anti-pattern 9: Mid-quarter recalibration as default + +The pattern. OKRs get revised mid-quarter routinely. The team uses recalibration to soften OKRs that feel uncomfortable. + +Why it fails. + +- OKRs lose accountability. Teams learn that revising mid-quarter is acceptable; commitment loosens. +- Stretch ambition disappears. Discomfort triggers recalibration rather than effort. +- Targets drift toward sandbagging quarter over quarter. + +The cure. Hold OKRs absent strategic shift, major disruption, or invalidating information. See `mid-quarter-recalibration.md` for the discipline. + +--- + +## Anti-pattern 10: Output-only KRs + +The pattern. Key results count work shipped rather than measure outcomes produced. + +Examples. + +- "Ship 5 onboarding initiatives." +- "Run 12 customer interviews." +- "Publish 8 marketing pieces." + +Why it fails. + +- Counts work, not outcomes. The team can hit these by doing work without producing the outcome. +- Optimizes for shipping volume rather than impact. +- Loses the connection between work and result. + +The cure. For each output KR, identify the outcome the output is meant to produce. Replace the count with a measurement of the outcome. + +--- + +## Anti-pattern 11: KRs entirely outside team influence + +The pattern. KRs depend on factors the team cannot control. + +Examples. + +- "Total revenue grows 30%" (depends on sales execution and market conditions, not just product work). +- "Maintain market share" (depends on competitive dynamics). +- "Reach Series B" (depends on investor decisions outside the team). + +Why it fails. + +- The team cannot credibly commit. Effort does not produce predictable outcomes. +- Failure is not informative. Misses do not reveal what the team should have done differently. +- Demoralizing. Teams hit fail OKRs they had little ability to affect. + +The cure. Rewrite KRs to focus on what the team can move. Total revenue may not be the team's KR; the team's contribution to revenue (e.g., product-led acquisition rate) might be. + +--- + +## Anti-pattern 12: Generous scoring + +The pattern. End-of-quarter scoring rounds up systematically. + +How it manifests. + +- KRs at 0.55 score 0.6 or 0.7. +- KRs at 0.85 score 1.0. +- The team's average score is 0.85+ even when objective outcomes were mid-range. + +Why it fails. + +- Honest signal lost. Scoring no longer reflects outcomes. +- Sandbagging compounds. Teams learn that scoring high is rewarded; subsequent quarters drift further. +- Lessons get lost. Misses scored as hits do not inform improvement. + +The cure. Hold the discipline of honest scoring. Document context per score; the context surfaces what produced the actual outcome regardless of the number. + +--- + +## The cross-cutting pattern + +Most OKR anti-patterns share a single root: optimizing for the appearance of OKR success rather than for the underlying outcomes. + +Sandbagging optimizes for hitting 100%. Fantasy optimizes for inspirational targets. OKR theater optimizes for documentation. Compensation coupling optimizes for bonus protection. Generous scoring optimizes for end-of-quarter celebration. + +Each anti-pattern produces apparent OKR success while undermining the OKR practice's actual purpose. The fix in every case is the same: focus on the underlying outcomes the practice is meant to produce, not on the OKR ceremony itself. + +--- + +## Methodology-level choices that stay in the public skill + +The twelve anti-patterns with diagnoses and cures. The cross-cutting appearance-vs-outcome pattern. + +## Implementation choices that stay internal + +Specific anti-pattern detection in the team's tracking tools. Specific reviewer training. Specific intervention patterns when anti-patterns are detected. The team's own conventions for catching drift early. These vary by team. diff --git a/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md b/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md new file mode 100644 index 0000000..9f9514c --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md @@ -0,0 +1,235 @@ +# OKRs vs roadmap vs metrics + +The three concepts and their relationships. Common conflations. The complete picture across all three. + +OKRs, roadmaps, and metrics are often conflated. Each serves a different purpose; conflating them produces confusion that decays each practice. Distinguishing them clarifies what each is for and how they compose. + +--- + +## OKRs + +Outcome targets for the quarter. + +Characteristics. + +- Quarterly time horizon. +- Outcome-focused. +- Stretch-ambition. +- Designed for accountability and learning, not for execution sequencing. + +Examples. + +- Objective: "Improve activation for new sign-ups." +- Key result: "Increase first-week activation rate from 32% to 45%." + +What OKRs are not. + +- A roadmap. OKRs do not specify which initiatives to ship. +- A metric. OKRs are quarterly targets on metrics; the metrics themselves are tracked continuously regardless of OKRs. +- A commitment to specific work. The team commits to pursuing the outcome; the tactics adapt. + +--- + +## Roadmap items + +Initiatives the team is building or doing. + +Characteristics. + +- Variable time horizon (weeks to months per initiative). +- Output-focused (the work being done). +- Sequenced by priority and dependency. +- Designed for execution coordination. + +Examples. + +- "Onboarding redesign." +- "Migrate to new auth service." +- "Build admin role overhaul." + +What roadmap items are not. + +- OKRs. Roadmap items are work; OKRs are outcomes. +- Metrics. Roadmap items contribute to moving metrics but are not metrics themselves. +- Permanent commitments. Items can be added, dropped, or re-prioritized as circumstances change. + +--- + +## Metrics + +Ongoing measurements the team tracks. + +Characteristics. + +- Continuous time horizon (always tracked). +- Quantitative, time-stamped, queryable. +- Designed for monitoring, learning, and OKR target-setting. + +Examples. + +- "First-week activation rate." +- "Median time-to-first-value." +- "Onboarding flow completion rate." + +What metrics are not. + +- OKRs. Metrics are continuous; OKRs are quarterly targets on metrics. +- Roadmap items. Metrics are measurements; roadmap items are work. +- Targets. Metrics are values; targets on metrics are KRs (or more generally, performance targets). + +--- + +## The relationship + +How the three compose. + +OKR: "Improve activation for new sign-ups." + +- Key result: "First-week activation rate from 32% to 45% by end of quarter." + - Underlying metric: "First-week activation rate" (tracked continuously). + - Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +The composition. + +- OKR names the outcome. +- Key result quantifies the outcome with a metric and target. +- Metric is the underlying measurement. +- Roadmap items are the work the team does to move the metric. + +The flow. + +- Strategy informs OKRs. +- OKRs inform roadmap prioritization (which work moves which OKR). +- Roadmap items get executed. +- Metrics track the impact. +- Scoring at end of quarter assesses the OKR's actual outcome. + +--- + +## Common conflations + +### OKRs treated as roadmap commitments + +The pattern. "Ship the onboarding redesign" written as an OKR. + +The diagnosis. This is a roadmap item, not an OKR. The OKR is the outcome the redesign is meant to produce. + +The cure. Rewrite as outcome: "Improve activation through onboarding redesign that reaches first-week activation 45%." The redesign is the contributing work; the outcome is what the work is meant to produce. + +### Roadmap items treated as OKRs + +The pattern. Quarterly OKRs are a list of features the team plans to ship. + +The diagnosis. Output disguised as outcome. The team is committing to work, not to results. + +The cure. For each output OKR, identify the outcome the output is meant to produce. The OKR is the outcome; the output is roadmap work that contributes. + +### Every metric needing an OKR + +The pattern. The team feels every metric they track must have an OKR target. + +The diagnosis. Metrics serve monitoring purposes regardless of whether the team is currently driving them. Some metrics are leading indicators the team watches without driving; some are protective metrics the team watches to ensure they do not degrade. + +The cure. OKRs select which metrics the team is actively driving this quarter. Other metrics get tracked without OKR targets. + +### OKRs as roadmap commitments to stakeholders + +The pattern. Stakeholders ask "what are you committing to ship next quarter?" The team answers with OKRs. + +The diagnosis. The team is using OKRs as roadmap; stakeholders interpret them as roadmap commitments; mid-quarter tactical adjustments feel like broken promises. + +The cure. Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Stakeholders can see both; the OKR is what the team is accountable for; the roadmap is the team's current best guess at what work will produce the outcome. + +### Treating metrics as OKRs + +The pattern. "Maintain CSAT at 4.5" written as an OKR for a quarter when the team has no specific work aimed at CSAT. + +The diagnosis. This is metric monitoring, not an OKR. OKRs are stretch outcomes the team is actively pursuing; metric monitoring continues regardless. + +The cure. Track CSAT as a metric. Set an OKR if the team is actively driving CSAT improvement; otherwise, the metric is monitored without an OKR. + +--- + +## When the three diverge + +Sometimes OKRs, roadmap, and metrics tell different stories. + +The pattern. + +- OKR is on track (KR moving toward target). +- Roadmap items are shipping on schedule. +- A different metric the team tracks is degrading. + +The interpretation. The OKR work is succeeding at its target; an unintended consequence may be hurting another metric. The team must decide whether to address the unintended consequence within the quarter or to defer. + +The discipline. OKRs are the formal commitment; roadmap items contribute to OKRs; metrics monitor everything (including OKR targets and protective metrics). When the three diverge, the team has decisions to make. + +--- + +## Roadmap-OKR alignment + +How the roadmap maps to OKRs. + +The mapping. + +- Each roadmap item gets associated with the OKR(s) it contributes to. +- Items not associated with any OKR are either team-specific work (technical debt, tooling) or candidates for deferral. + +Worked example. + +- OKR: "Improve activation for new sign-ups." +- Contributing roadmap items: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +- OKR: "Establish enterprise-readiness foundations." +- Contributing roadmap items: "Admin role overhaul," "SOC 2 audit preparation." + +- Team-specific roadmap items (no OKR ladder): "Migrate to new auth service" (foundational; supports many OKRs), "Strengthen test coverage in critical paths" (engineering health). + +The discipline. All roadmap items have either an OKR ladder or an explicit team-specific designation. Items with neither are candidates for deprioritization. + +--- + +## Metric coverage and OKR targets + +How metrics are selected and how OKR targets relate. + +Metric coverage. The team tracks metrics that: + +- Reflect strategic outcomes (input metrics for OKRs). +- Monitor protective concerns (metrics that should not degrade). +- Surface leading indicators of larger outcomes. +- Provide diagnostic signal for issues. + +OKR target selection. Each quarter, the team selects which metrics to set OKR targets on: + +- Metrics tied to the quarter's strategic priorities. +- Metrics where stretch progress is plausible and meaningful. +- Often a subset of the broader metric set. + +The remaining metrics. Tracked without OKR targets. Monitored for movement; surfaced if they shift unexpectedly. + +--- + +## Common failures across the three + +OKR-as-roadmap. Quarterly commitments written as features rather than outcomes. + +Roadmap-as-OKR. Roadmap items called OKRs; output disguised as outcome. + +Every-metric-as-OKR. OKRs proliferate to cover every tracked metric; focus diluted. + +OKR-without-roadmap-mapping. OKRs set without identifying which work will move them; teams miss the OKRs because no work is aimed at them. + +Roadmap-without-OKR-mapping. Work happens without explicit OKR connection; teams cannot tell what their work is contributing to. + +Metrics-without-OKR-distinction. All metrics treated as targets; team cannot prioritize. + +--- + +## Methodology-level choices that stay in the public skill + +The three concepts and their characteristics. The relationship and composition. Common conflations and cures. When the three diverge. Roadmap-OKR alignment. Metric coverage and OKR target selection. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools. Specific roadmap tools. Specific metrics dashboards. Specific integration between OKR system and roadmap system. The team's own conventions for OKR-roadmap-metric documentation. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md b/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md new file mode 100644 index 0000000..8ca8934 --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/review-cadence-templates.md @@ -0,0 +1,230 @@ +# Review cadence templates + +Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. + +OKRs benefit from a structured review rhythm. The cadence produces accountability infrastructure: weekly tactical adjustment, mid-quarter strategic assessment, end-of-quarter scoring, and quarterly practice review. Teams that skip the cadence often watch OKRs decay into year-end reckoning that produces no learning. + +--- + +## Weekly check-ins + +The shortest, most frequent review. + +Format. + +- 15-30 minutes per team. +- Team reviews progress on each key result. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Decides tactical adjustments for the upcoming week. + +Structure. + +- Per KR: current value, trajectory, blockers, planned work for the upcoming week. +- Cross-OKR: any priority shifts, dependencies needing attention. +- Closing: commitments for the week. + +Purpose. + +- Tactical adjustment, not OKR adjustment. +- Surface blockers early so they can be addressed. +- Maintain focus on OKRs across the quarter (without weekly check-ins, OKRs get forgotten in the press of immediate work). + +What this is not for. + +- Adjusting the OKR or its targets. That is mid-quarter or end-of-quarter work. +- Status reports for stakeholders. Status reports may flow from the check-in but are a separate output. +- Detailed work review. The check-in is OKR-focused; other work happens elsewhere. + +Common failures. + +- Becoming status reports. The check-in turns into "here's what I did this week"; OKR-driven decisions get crowded out. Reform the format. +- Becoming OKR adjustment sessions. Teams uncomfortable with OKRs sometimes use weekly check-ins to soften them. Hold to tactical scope. +- Skipping when busy. Weeks where the check-in feels less urgent are exactly when discipline is needed. Skip rarely. + +--- + +## Mid-quarter review + +A longer, more strategic review. + +Format. + +- 60-90 minutes per team. +- Roughly week 6 of the quarter (mid-point). +- Honest assessment of trajectory: which KRs are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +Structure. + +- Per OKR: current state vs target, trajectory analysis, on-track or off-track assessment. +- Cross-OKR: priority adjustments, capacity reallocations, blockers requiring escalation. +- Recalibration check: is any OKR a candidate for revision per the strategic-shift / disruption / invalidating-information criteria? (See `mid-quarter-recalibration.md`.) +- Closing: tactical decisions for the second half of the quarter. + +Purpose. + +- Strategic assessment of OKR progress. +- Course correction before end-of-quarter when there is still time. +- Surface OKRs that may need recalibration (with the discipline that recalibration should be rare). + +What this is not for. + +- Routine recalibration. Most mid-quarter reviews end with no recalibration; tactical adjustments are the typical output. +- Scoring. Scoring is end-of-quarter; mid-quarter assesses trajectory toward the score. +- Postmortem. Postmortems are for completed work; mid-quarter is for live work in progress. + +Common failures. + +- Becoming a recalibration session. Teams uncomfortable with stretch use mid-quarter review to lower OKRs. Hold to the rare-recalibration discipline. +- Becoming a status meeting. The session becomes a presentation rather than a decision-making review. Reform format to surface decisions. +- Skipping. Teams that skip mid-quarter review often discover at end of quarter that they could have course-corrected; the missed opportunity is the cost. + +--- + +## End-of-quarter scoring + +The OKR-cycle closing review. + +Format. + +- 60-90 minutes per team. +- Last week of the quarter. +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +Structure. + +- Per KR: actual outcome, score (0.0-1.0), context (what produced this score). +- Per objective: average KR score, context. +- Cross-OKR: average score across all OKRs (informs whether the quarter was stretch, sandbag, or fantasy). +- Lessons: what this quarter's scoring reveals about OKR design, team capacity, or strategic clarity. +- Closing: insights to carry into next quarter's OKR setting. + +Purpose. + +- Honest scoring of outcomes. +- Learning from the gap between target and outcome. +- Input to the next quarter's OKR design. + +What this is not for. + +- Compensation discussions. OKRs work best decoupled from compensation; scoring should not feel like a performance evaluation. +- Blame allocation. Misses are informative; the discussion is about what produced the gap, not who failed. +- Setting next quarter's OKRs. That is a separate session. + +Common failures. + +- Generous scoring. Scores rounded up; the team protects feelings; honest signal lost. Hold the discipline. +- Skipping context. Scores published without explanation of what produced them. Lessons get lost. +- Treating scores as performance. Compensation coupling produces sandbagging in subsequent quarters. +- Not informing next quarter. Scores reviewed but lessons do not influence the next OKR setting. The cycle does not learn. + +--- + +## Quarterly retrospective + +A separate review focused on the OKR practice itself. + +Format. + +- 60-90 minutes per team or org. +- After end-of-quarter scoring. +- Reviews the OKR practice, not the OKR outcomes. +- Often combined with the next-quarter OKR setting session. + +Structure. + +- What worked in this quarter's OKR practice (cadence, format, design)? +- What did not work? +- What should change in the next cycle? +- What patterns are emerging across multiple quarters? + +Purpose. + +- Improve the OKR practice itself. +- Surface decay or drift in OKR discipline. +- Inform process changes for the next cycle. + +What this is not for. + +- Scoring or recalibrating current OKRs. That is end-of-quarter work. +- Setting next quarter's OKRs. That is a separate session that uses the retrospective's inputs. + +Common patterns surfaced. + +- Sandbagging or fantasy drift. Average score patterns over multiple quarters reveal practice decay. +- Cadence breakdown. Weekly check-ins becoming status reports; mid-quarter reviews becoming recalibration sessions. +- Cascading misalignment. Teams setting OKRs that do not ladder; cross-team coordination failing. +- Compensation coupling. OKRs becoming performance theater because they are tied to bonuses. + +Common retrospective failures. + +- Skipping the retrospective. The OKR practice does not improve; decay accumulates. +- Conflating with next-quarter OKR setting. Both can happen in one session, but the retrospective lens (process review) should be distinct from the OKR design lens (setting). +- Producing recommendations without follow-through. Retrospectives surface improvements; the team must implement them in the next cycle for the retrospective to matter. + +--- + +## The cadence as a system + +The four cadences compose. + +The system. + +- Weekly check-ins maintain tactical focus and surface blockers. +- Mid-quarter review provides strategic assessment and rare recalibration opportunity. +- End-of-quarter scoring produces honest signal on outcomes. +- Quarterly retrospective improves the practice over time. + +The reinforcement. + +- Weekly check-ins make mid-quarter assessment honest (the team has been tracking trajectory all along). +- Mid-quarter review surfaces issues end-of-quarter scoring will face. +- End-of-quarter scoring informs the retrospective. +- The retrospective informs the next cycle's design. + +The skip risk. Teams that skip cadences often skip several. Weekly check-ins falter; mid-quarter review becomes ad-hoc; end-of-quarter scoring becomes generous because the team has not been tracking honestly all along; the retrospective never happens. + +--- + +## Cadence ownership + +Each cadence has a clear owner. + +Weekly check-ins. Owned by the team lead (manager, PM, engineering lead). Facilitates the meeting; ensures it stays tactical. + +Mid-quarter review. Owned by the team lead, often with cross-functional partners attending. Surfaces strategic decisions. + +End-of-quarter scoring. Owned by the team lead. Ensures honest scoring; documents context. + +Quarterly retrospective. Owned by the team lead or by a process-focused role (chief of staff, ops lead). Often facilitated by someone slightly outside the team to bring fresh perspective. + +Cross-team coordination. When multiple teams have OKRs that compose, coordination across teams happens at the cadence boundaries (typically mid-quarter review). + +--- + +## Common cadence failures + +Skipping cadences. Weekly check-ins falter; mid-quarter review becomes ad-hoc; the system breaks. + +Cadence merging. Mid-quarter review and end-of-quarter scoring combined into one session. Loses the distinct purposes. + +Status-report drift. Weekly check-ins become status reports; tactical decisions get displaced. + +Recalibration drift. Mid-quarter review becomes a recalibration session; OKRs lose accountability. + +Generous-scoring drift. End-of-quarter scoring rounds up; honest signal lost. + +Retrospective skipping. OKR practice does not improve; decay accumulates. + +--- + +## Methodology-level choices that stay in the public skill + +The four cadence formats. Time investment per cadence. Structure and purpose per cadence. The cadence-as-system reinforcement. Ownership. Common failures. + +## Implementation choices that stay internal + +Specific meeting templates. Specific OKR-tracking tools that support each cadence. Specific facilitation conventions. Specific cross-team coordination formats. The team's own conventions for cadence cadence (no pun intended). These vary by team and tooling. diff --git a/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md b/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md new file mode 100644 index 0000000..b51963d --- /dev/null +++ b/dist/pi/.agents/skills/okr-design/references/scoring-discipline.md @@ -0,0 +1,191 @@ +# Scoring discipline + +The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. + +End-of-quarter scoring is where OKR practice succeeds or decays. Honest scoring produces signal: which OKRs the team hit, which they missed, what the gap reveals about the work. Dishonest scoring produces theater: 100% scores claimed regardless of outcome, generous rounding, partial credit for effort rather than outcome. + +--- + +## The 0.0-1.0 scale + +Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +Key result scoring examples. + +- KR: "Increase first-week activation rate from 32% to 45%." +- Outcome: rate reached 41%. +- Score: (41 - 32) / (45 - 32) = 9/13 = 0.69. + +- KR: "Reduce median time-to-first-value from 4.2 days to under 2 days." +- Outcome: reduced to 2.6 days. +- Score: (4.2 - 2.6) / (4.2 - 2.0) = 1.6/2.2 = 0.73. + +- KR: "Pass SOC 2 Type II audit with zero high-severity findings." +- Outcome: passed with zero high-severity findings. +- Score: 1.0 (binary KR; achieved). + +Objective scoring. Average of the key result scores. + +- Objective with 3 KRs scoring 0.69, 0.73, 1.0: objective scores (0.69 + 0.73 + 1.0) / 3 = 0.81. + +--- + +## The 60-70% target + +Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. + +Why this target. + +- Average above 0.85 suggests sandbagging. The team set OKRs they were already on track to deliver. +- Average below 0.4 suggests fantasy. The team set OKRs that no realistic effort path would have produced. +- Average between 0.6-0.7 suggests stretch. The team committed to ambition and delivered most of it. + +The trajectory check. Track the team's average score over multiple quarters. Drift toward 0.85+ signals sandbagging is creeping in; drift toward 0.4 signals fantasy. The target zone is 0.55-0.75 over a multi-quarter window. + +Variance is normal. Some quarters will hit 0.8 average; some will hit 0.5. The variance reflects the genuine uncertainty in stretch OKRs. Programs that hit 0.65 every single quarter are usually managing scores rather than honestly scoring outcomes. + +--- + +## Scoring honesty + +Score the actual outcome, not the effort. A team that worked hard but did not move the metric scores low. A team that got lucky and moved the metric without much effort scores high. The score reflects outcome. + +Do not round up. A KR at 0.55 scores 0.55, not 0.6. Honest scoring produces honest signal. Rounding up across multiple KRs accumulates into systemic over-scoring. + +Acknowledge what changed. Some misses reflect mid-quarter priority shifts. Surface these without using them as excuses. "We deprioritized this in week 5 to address the security incident" is honest context; "we hit our priorities even though we missed this OKR" is hand-waving. + +Scoring sessions are honest, not adversarial. The scoring conversation is for capturing reality, not for blame. Honest low scores are fine; effort recognition happens elsewhere. + +--- + +## What 100% scores mean + +100% scores warrant scrutiny. + +Possibilities. + +- The OKR was sandbagged. The team set targets they were already on track to hit. +- The team had a great quarter. Sometimes hitting 100% reflects unusual progress; informative. +- The team is rounding up. The actual outcome was 0.85 but got rounded. +- Binary KRs that hit 1.0. A milestone-based KR that achieves the milestone is 1.0; this is not sandbagging. + +The investigation. + +- Compare the target to the historical trajectory. Was the target above what the metric would have done without focused effort? +- Compare the target to other teams setting similar OKRs. Was this target genuinely stretch? +- Look at the work the team did. Did the team push beyond their normal capacity, or did they hit the target on standard execution? + +The interpretation. Single-quarter 100% scores are not necessarily problematic. Repeated 100% scores across many KRs across multiple quarters are a sandbagging signal. The next OKR cycle should set targets above the prior quarter's actuals to prevent sandbagging compounding. + +--- + +## What 30% scores mean + +30% scores warrant scrutiny. + +Possibilities. + +- The OKR was fantasy. Targets had no realistic effort path; the team could not have hit them. +- Unexpected disruption. A market event, security incident, or priority shift consumed capacity that would have gone to the OKR. +- Mid-quarter deprioritization. The team chose to deprioritize this OKR for other work. +- Underperformance. The team did not execute well; the score reflects the execution gap. + +The investigation. + +- Was the target reachable? At setting time, could the team identify effort paths that would produce the target? +- What changed during the quarter that affected the trajectory? +- What did the team actually work on? Did effort match the OKR, or did effort go elsewhere? + +The interpretation. 30% scores are informative regardless of cause. Fantasy targets need recalibration in the next quarter. Disruption-driven misses inform what to plan around. Deprioritization-driven misses surface tension between OKRs and other work. Execution gaps surface team-capability or process issues. + +The non-recovery. Repeated 30% scores quarter after quarter signal that OKR design is failing. Either the org is consistently setting fantasy targets, or the team is consistently mismatched to its commitments. Investigate. + +--- + +## The compensation question + +OKRs work best when not directly tied to compensation. + +The problem with compensation-coupling. When OKRs determine bonuses or reviews, sandbagging incentives become severe. Teams set OKRs they know they can hit. The 60-70% target collapses to 95% target because nobody wants to risk their bonus on stretch. + +Why decoupling works. OKRs become genuine accountability infrastructure. The team can stretch without risking compensation. Honest scoring is safe. Misses produce learning rather than punishment. + +Compensation alternatives. + +- Compensation tied to overall performance (manager assessment, peer feedback, role expectations) rather than to OKR scores specifically. +- OKR scores inform performance review as one input among many, not as the dominant signal. +- Bonus structures based on company performance rather than team-OKR scores. + +The transition for orgs already coupled. Decoupling requires explicit communication. Teams need to trust that scoring honestly will not affect their bonuses. The transition can take 2-3 cycles before teams believe the decoupling is real. + +--- + +## Scoring formats + +How scoring sessions get run. + +The format. + +- Team meets at end of quarter (60-90 minutes). +- Each KR scored honestly. +- Each objective scored as the KR average. +- Discussion: what produced the scores, what worked, what did not. +- Output: published scores with brief context per OKR. + +The discussion content. + +- For high-scoring OKRs: was this stretch? What worked? What can be replicated? +- For low-scoring OKRs: what got in the way? What does the team need next quarter? +- For mid-scoring OKRs: where did the work land? What was the gap between target and actual? + +The output. Scores published to the team and stakeholders. Brief context per OKR. The published record informs the next quarter's setting and the org's broader OKR practice. + +--- + +## Scoring across multiple teams + +When multiple teams cascade to a company OKR, scoring composes. + +The composition. + +- Each team scores its KRs independently. +- The company OKR's score reflects the cumulative outcome (not the average of team scores). +- A company OKR can score high even if some contributing team OKRs scored low, depending on which contributions mattered most. + +Worked example. Company OKR: "Improve net new ARR through enterprise segment growth." + +- Sales team KR (close 8 enterprise deals): scored 0.85 (closed 7). +- Product team KR (enterprise-readiness foundations): scored 0.7 (achieved most foundations; SOC 2 in progress). +- Marketing team KR (enterprise-segment marketing campaigns): scored 0.5 (delayed launch). + +Company OKR score: depends on the actual ARR outcome, not the average of team scores. If ARR met the target despite the marketing delay (because sales over-delivered), the company OKR scores high. + +The discipline. Score outcomes, not averages of inputs. + +--- + +## Common scoring failures + +Rounding up. Systemic over-scoring through small individual rounds. + +Effort-based scoring. Scoring based on how hard the team worked rather than what was achieved. + +Compensation-coupled scoring. Sandbagging incentives produce 95%+ scores. + +Avoidance of low scores. Teams reluctant to score low; OKRs renamed or rewritten retroactively to avoid the miss. + +Aggregate-of-input scoring. Company OKR scored as average of team scores rather than as the actual outcome. + +Scoring without context. Scores published without the conditions that produced them. Lessons get lost. + +One-quarter-at-a-time view. Scoring evaluated only against the current quarter; trajectory over multiple quarters not surfaced. + +--- + +## Methodology-level choices that stay in the public skill + +The 0.0-1.0 scale and worked examples. The 60-70% target. Scoring honesty. What 100% and 30% scores mean. The compensation question. Scoring formats. Scoring across teams. Common scoring failures. + +## Implementation choices that stay internal + +Specific scoring tools and dashboards. Specific scoring-session facilitation formats. Specific compensation structures. The team's own conventions for context publishing. These vary by org. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md b/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md new file mode 100644 index 0000000..28ccaa7 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/SKILL.md @@ -0,0 +1,280 @@ +--- +name: onboarding-wizard-design +description: "Designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. Honest about tutorial-overload (dump everything upfront), skip-friendly-empty (skipped onboarding leads to abandoned product), and earned-progressive-disclosure (right things at the right moments) patterns. Triggers on onboarding wizard, product onboarding, first-run experience, signup flow, activation flow, FRX, time-to-value, ah-ha moment design. Also triggers when activation rates are low, when users skip onboarding and never return, when onboarding flows are being scoped for the first time, or when audience research shows users not finding key features." +category: growth-tooling +catalog_summary: "Designing first-run product onboarding wizards. Distinguishes tutorial-overload (dump everything upfront) from skip-friendly-empty (skipped onboarding leads to abandoned product) from earned-progressive-disclosure (right things at the right moments)" +display_order: 7 +--- + +# Onboarding Wizard Design + +A senior product marketing director's playbook for designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. The discipline of building an onboarding sequence the user actually completes. + +Most product onboarding wizards fail in one of two ways. They cram every feature into a 12-step intro the user has not earned the patience for. Or they offer a "skip onboarding" button so prominent that users skip into an empty product with no context, and then churn the next day because they never found the value. The activation rate is the metric that matters, and most wizards are optimizing for the wrong thing. + +The wizards that work do something different. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is balanced against staying engaged. The user reaches the ah-ha moment with a sense that the product respected their time. + +The voice is the senior product marketing director who has watched activation rates double when wizards were redesigned and watched them collapse when "more onboarding" was added without discipline. Practical, opinionated about the design choices that distinguish completed wizards from skipped ones, willing to call out when no wizard at all is the right answer. + +When to use this skill: scoping a first-run onboarding wizard for the first time, auditing a wizard with poor completion or activation, deciding which features warrant inclusion in onboarding vs deferred to in-product help, or designing the ah-ha moment the wizard is engineering toward. + +--- + +## What this skill covers + +This skill spans first-run product onboarding wizards. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access). This skill is post-signup product onboarding. Different phase, different audience state. +- `interactive-product-tour` is contextual help WITHIN the product, surfacing across the lifecycle. This skill is the sequential first-run experience. +- `chatbot-flow-design` is conversational help. This skill is non-conversational sequential setup. +- `onboarding-wizard-design` (this skill) is the post-signup wizard's structure, ah-ha moment design, progressive disclosure, skip mechanics, drop-off measurement. +- `pm-spec-writing` is the spec for engineers building the wizard. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams designing activation flows, agencies running activation work for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); in-product contextual tours (covered by `interactive-product-tour`); the engineering implementation; specific Userpilot/Userflow/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The wizard decision: when wizards earn vs when contextual help suffices + +Before designing the wizard, decide whether a wizard is the right tool. + +Wizards earn investment when: + +- The product has a meaningful setup step before value emerges. Connect a data source, invite a teammate, configure a workspace. Without setup, the product is empty; the wizard makes setup tractable. +- The ah-ha moment requires multiple actions in sequence. Single-action ah-ha moments (paste a URL, see a result) often work better with contextual prompts than with wizards. +- The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products. Some audiences (consumer, frictionless tools) reject wizard friction. +- The team can maintain the wizard. Wizards decay as the product evolves; without maintenance commitment, the wizard becomes a liability. + +Wizards do NOT earn investment when: + +- The product reaches value immediately. Single-input tools, simple consumer products. A wizard adds friction without lift. +- Contextual help would suffice. Tooltips, in-feature hints, and progressive in-product education sometimes serve better than upfront wizards. +- The audience expects no friction. Some audiences abandon at any wizard; meet them where they are. +- The team cannot maintain the wizard alongside product changes. Stale wizards point to deprecated features; users hit broken steps. + +The decision is not "should we have an onboarding wizard"; it is "is the wizard the right tool for this specific product and audience." + +Detail in [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md). + +--- + +## Tutorial-overload vs skip-friendly-empty vs earned-progressive-disclosure + +The keystone framing. + +Tutorial-overload. Every feature explained in a 12-step intro before the user has touched the product. Cognitive overload. Users skip if they can; abandon if they cannot. Cost: the wizard's design effort produces a sequence almost nobody completes; activation rate suffers because the user did not reach the value-giving moment. + +Skip-friendly-empty. "Skip onboarding" button at every step, so prominent that users always take it. Users skip; arrive at an empty product with no context; churn within hours. Cost: activation rate falls off a cliff because users never set up the basics that make the product functional. + +Earned-progressive-disclosure. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is friction-balanced against staying engaged (e.g., skip places the user in a partially-set-up state with clear callouts to complete setup later). Cost: design effort is significant; activation rate often climbs significantly as a result. + +The litmus test. Watch a new user complete (or skip) the wizard. Did they reach a moment where the product visibly demonstrated value within their first session? If yes, the wizard is earned-progressive-disclosure. If they completed every step but never reached value, tutorial-overload. If they skipped and never returned, skip-friendly-empty. + +--- + +## Step architecture: what belongs in each step, sequence logic + +The structure that makes wizards actually work. + +The principle. Each step should move the user one step closer to value. Steps that do not should be cut. + +Common step patterns. + +- Welcome and orientation. Quick context-setting, often skippable. Sets expectations for what the wizard will do. +- Identity and account context. Who are you, what's your role, what brought you here. Often used to personalize subsequent steps. +- Critical setup step. The one thing the product cannot work without (connect data source, invite teammates, set primary use case). This is often where wizards justify their existence. +- First-action step. Get the user to take a meaningful action that produces visible result. The ah-ha moment lives here or right after. +- Configuration deferral. Surface the things that can be set up later but are commonly needed; let the user defer with a clear path back. +- Confirmation and next steps. Recap what was set up; surface what to do next; route to in-product home. + +Step coherence test. Each step should answer: did this step move the user closer to value? Steps that exist for completeness or feature-pride should be cut. + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## The ah-ha moment design + +What the wizard is actually trying to engineer. + +The principle. The ah-ha moment is the moment the user feels "oh, this is what the product does for me." The wizard's structure should engineer toward that moment. + +Identifying the ah-ha moment. + +- It is the visible demonstration of value, not just feature explanation. +- It is action-tied, not knowledge-tied. The user did something and saw the result. +- It is single-shot. One clear moment, not a checklist of moments. +- It is honest. The user genuinely got value; not a contrived demo. + +Design implications. + +- The wizard's path should converge on the ah-ha moment. Steps that do not contribute should be deferred or cut. +- The ah-ah moment should appear within the user's first session, ideally within 5-10 minutes of signup. Longer time-to-value correlates with churn. +- The ah-ha moment differs by audience. The B2B admin's ah-ha moment differs from the end-user's. Wizards may need to differentiate. + +Common ah-ha moment patterns. + +- First successful query/output. The user ran something against their data and saw a useful result. +- First meaningful collaboration moment. The user shared something with a teammate and saw the response. +- First saved configuration. The user set up something they will return to. +- First value-demonstrating insight. The user saw a metric, recommendation, or pattern that surprised them. + +Detail in [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md). + +--- + +## Progressive disclosure patterns + +How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Pattern A: Default-heavy. Each step has smart defaults. The user can accept or override. Most users accept; advanced users override. Reduces cognitive load. + +Pattern B: Required-now, optional-later. Required fields surface in the wizard; optional configuration surfaces in-product after activation. The wizard stays focused. + +Pattern C: Expand-on-demand. Sections collapsed by default; the user expands if interested. Rare; works when the user has agency to explore. + +Pattern D: Branching. Different users see different steps based on earlier answers. Powerful but adds maintenance complexity. + +The discipline. Each piece of information shown in the wizard must justify its inclusion. Decorative information adds friction; surface it later. + +Detail in [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md). + +--- + +## Skip and resume mechanics + +When users skip, where they land. When they resume, what they see. + +The skip principle. Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +Skip patterns. + +- Soft skip with context. "Skip for now" deposits the user into a partially-set-up state with clear callouts to complete deferred setup. +- Skip-and-defer. Skipped steps are queued for later in-product prompts. +- Skip-with-warning. "Skipping setup will limit your experience to X. Continue?" Honest about consequences. +- No skip. For wizards that absolutely require completion (compliance forms, paid signups). Use sparingly. + +Resume patterns. + +- Auto-resume on next login. The user lands at the step they left. +- Manual resume from in-product entry. A persistent "Complete setup" surface that returns the user to the wizard. +- Soft resume. Wizard fades out as the user completes equivalent actions in-product naturally. + +The skip-friendly-empty failure. Skip is too prominent and consequence-free; the user lands in an unconfigured product and has no path back. Activation collapses. + +The cure. Skip is honest about consequences and offers a path back. The user who skips knows what they skipped. + +Detail in [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon the wizard, and how to fix it. + +Per-step instrumentation. Track step start, step completion, step abandonment for every step. The metrics inform every other improvement. + +Common drop-off patterns. + +- First-step drop-off. User landed on the wizard, looked at it, left. Often signals the wizard's value proposition is not clear or the audience expected no wizard. +- Mid-wizard drop-off. User abandoned mid-process. Audit the specific step; field count, sensitive info, unclear progress. +- Skip-everything drop-off. User skipped every available step. Either the wizard is not earning its time or the skip is too prominent. + +Remediation patterns. + +- First-step drop-off: clarify the wizard's purpose; reduce upfront fields; consider whether the wizard is needed at all. +- Mid-wizard drop-off: audit the high-drop step; reduce friction; reconsider whether that step belongs in the wizard. +- Skip-everything drop-off: rebalance skip prominence; consider whether the wizard should be replaced with contextual prompts. + +The instrumentation requirement. Without per-step tracking, drop-off remediation is guesswork. Set up tracking before launch. + +Detail in [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md). + +--- + +## Wizard variations by user type + +Different users may need different wizards. + +The admin vs end-user distinction. Admins set up the workspace; end-users start using it. Wizards aimed at both fail both. Differentiated wizards serve each. + +The technical vs non-technical distinction. Technical users skip explanations; non-technical users need them. The wizard's tone and depth should match. + +The size-of-team distinction. Solo founders have different setup needs than 50-person teams. Wizards may branch. + +Differentiation patterns. + +- Role-based branching. First step asks role; subsequent steps adapt. +- Use-case-based branching. First step asks use case; wizard tailors. +- Size-based branching. Solo, team, enterprise paths differ. + +The over-differentiated trap. Too many variants produce unmaintainable wizards. Most wizards work with 2-3 variants at most. + +Detail in [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md). + +- "Activation rate is low; completion rate is high." Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. +- "Skip rate is over 50 percent." Either the wizard is not earning its time or skip is too prominent. Audit both. +- "Users complete the wizard then abandon the product within 24 hours." Time-to-value too long; ah-ha moment not in first session. +- "Wizard works for new users; existing users hit broken steps." Wizard not maintained alongside product; deprecated features still in flow. +- "Different segments complete at very different rates." Audience-fit varies; consider role-based or use-case-based branching. +- "Mobile completion is half of desktop." Mobile UX of the wizard broken. +- "We added more onboarding steps; activation went down." Tutorial-overload pattern; more is not better. +- "Skip mechanics work but users do not return to complete setup." Skip-and-defer not working; in-product prompts to return are missing or ignored. +- "Wizard analytics broke after the last release." Instrumentation drift; track and refresh. + +--- + +## The framework: 12 considerations for onboarding wizard design + +When designing or auditing an onboarding wizard, walk these 12 considerations. + +1. The wizard decision. Is a wizard the right tool, or do contextual prompts suffice? +2. Earned-progressive-disclosure, not tutorial-overload or skip-friendly-empty. Each step earns one step closer to value. +3. Step architecture sound. Each step moves the user closer to value; non-contributing steps cut. +4. The ah-ha moment engineered. Single visible value moment, action-tied, in the first session. +5. Progressive disclosure applied. Show only what is needed now; defer the rest. +6. Skip mechanics honest. Skip exists but does not produce an empty product. +7. Resume mechanics work. Skipped users have a path back; instrumented for follow-through. +8. Drop-off measurement instrumented. Per-step tracking from launch. +9. User-type variations balanced. 2-3 variants max; over-differentiation avoided. +10. Mobile parity. Wizard works on the devices the audience uses. +11. Activation as success metric. Not just completion rate; the metric is post-wizard product engagement. +12. Maintenance discipline. Wizard updated alongside product changes; quarterly audit. + +The output of the framework is an onboarding wizard that gets users to the ah-ha moment, respects their time, and produces activation rates the team can defend. + +--- + +## Reference files + +- [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md) - When wizards earn the build vs when contextual help suffices. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs in each step. Sequence logic. Step coherence test. +- [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md) - Identifying the ah-ha moment; designing the wizard to converge on it. +- [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md) - Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. +- [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md) - Skip patterns and resume patterns. The skip-friendly-empty failure. +- [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md) - Per-step instrumentation. Common drop-off patterns and remediation. +- [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md) - Admin vs end-user, technical vs non-technical, size-based branching. +- [`references/wizard-anti-patterns.md`](references/wizard-anti-patterns.md) - The patterns that look like onboarding but degrade activation. +- [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: wizards earn the user's first session + +The onboarding wizards that work as compounding assets are the ones that get the user to value within their first session. Not because the wizard had every feature explained. Not because the wizard was skipped quickly. Because the wizard engineered the ah-ha moment, respected the user's time, and surfaced the right thing at the right moment. + +That is the bar. Below the bar are tutorial-overload (everything upfront, nobody completes) and skip-friendly-empty (skip too prominent, nobody activates). Above the bar are earned-progressive-disclosure wizards where each step earns the user one step closer to value, skip is honest about consequences, and the activation metric reflects the wizard's actual job. + +The discipline is in the design choices. The decision to build a wizard at all, or defer to contextual help. The step architecture that converges on the ah-ha moment. The progressive disclosure that surfaces the right thing at the right moment. The skip mechanics that protect the user from an empty product. The drop-off instrumentation that informs ongoing improvement. The maintenance cadence that keeps the wizard in sync with the product it represents. + +When in doubt, ask: did the user reach the ah-ha moment in their first session, and did the wizard help or hinder that? If yes to the first and helped on the second, the wizard earned its build. If no to either, redesign. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md new file mode 100644 index 0000000..0ca8f3e --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md @@ -0,0 +1,167 @@ +# Ah-ha moment engineering + +Identifying the ah-ha moment; designing the wizard to converge on it. The single visible moment when the user feels "oh, this is what the product does for me." + +The wizard's job is not completion. It is engineering the ah-ha moment within the user's first session. Without an identifiable ah-ha moment, the wizard has nothing to engineer toward; the result is a sequence that completes without producing activation. + +--- + +## The ah-ha principle + +The ah-ha moment is action-tied, single-shot, and visible. The user did something and saw the value the product promised. The wizard's structure should make that moment likely within the first session. + +The win. A new user finishes the wizard and immediately sees their first dashboard with their actual data, with a number that surprises them in a useful way. They get it. + +The fail. The user finishes the wizard with a tour of features but never sees the product produce something specifically for them. They completed the wizard; they did not activate. + +--- + +## Identifying the ah-ha moment + +The hardest design step is also the most upstream. + +Methods. + +- Customer research. Interview activated users (those who returned and engaged) about the moment they felt the product clicked. Patterns emerge. +- Usage analysis. Compare cohorts that activated vs cohorts that churned. What action did the activated cohort take that the churned cohort did not? +- Sales-call mining. Sales conversations often surface the moment prospects say "now I get it." That moment, in-product, is the ah-ha moment. + +Signals of a real ah-ha moment. + +- It is action-tied (the user did something), not knowledge-tied (the user learned something). +- It is single-shot (one specific moment), not a checklist of moments. +- It is visible (the user saw the result), not internal (the user felt understanding). +- It is honest (the user got real value), not contrived (a demo with fake data). + +If the team cannot articulate the ah-ha moment, that is the design problem to solve before building the wizard. + +--- + +## Common ah-ha moment patterns + +By product type. + +Analytics products. First successful query against the user's actual data. Not a demo dataset; their data, their result. + +Collaboration products. First meaningful interaction with a teammate. A shared comment, a delegated task, a thread that produces a decision. + +Content products. First saved item the user returns to. The content was useful enough to revisit. + +Tooling products. First completed task that would have taken longer without the tool. The time savings is visible. + +Marketplace products. First successful match. Buyer found a seller; seller got a lead. + +Configurator products. First saved configuration. The user committed to a setup they want to see again. + +The ah-ha moment varies by product. The discipline (action-tied, single-shot, visible, honest) holds. + +--- + +## Designing the wizard around the ah-ha moment + +The wizard's path should converge on the moment. + +Step 1: identify the prerequisites. What does the user need before the ah-ha moment can happen? Connect data, invite teammate, configure workspace. Those steps are mandatory. + +Step 2: identify the path. What sequence of actions leads to the moment? The wizard's steps mirror that sequence. + +Step 3: identify the friction. What can break the path? Missing inputs, ambiguous decisions, validation errors. The wizard should pre-empt or smooth those. + +Step 4: place the ah-ha moment intentionally. The moment should appear at step 3-5 of the wizard, not after a 10-step setup. Earlier is better; aim for the user's first session, ideally first 5-10 minutes. + +--- + +## Time-to-value as design constraint + +The shorter the time to ah-ha, the higher the activation rate. + +The benchmark. First session ah-ha moment correlates with strong activation. Multi-session ah-ha (user has to come back) correlates with moderate activation. Multi-day ah-ha (user has to wait or work for it) correlates with poor activation. + +The design implication. If the ah-ha moment naturally takes hours or days (e.g., AI training, audit results), the wizard needs an interim ah-ha, something visible the user can see in their first session that signals the eventual ah-ha is coming. + +Examples. + +- AI product where training takes 24 hours: interim ah-ha is "see how your data looks; we will message you when training is done." +- Audit product where results take 48 hours: interim ah-ha is "see what we are auditing; preview a partial result." + +The user's first session should produce something visible and meaningful, even if the full ah-ha comes later. + +--- + +## The ah-ha moment for different audiences + +Different users may need different moments. + +Admin vs end-user. The admin's ah-ha moment may be configuration-related ("the workspace is set up, the team can use it"). The end-user's ah-ha moment is in-product engagement ("I did the thing I came to do"). Wizards may differentiate. + +Technical vs non-technical. Technical users often want depth (see the API work, see the integration succeed). Non-technical users want outcome (see the result, no API). Different ah-ha moments. + +Solo vs team. Solo users often want individual productivity. Team users want collaboration moments. The wizard's path may differ. + +The discipline. Identify the ah-ha moment per relevant audience segment. Wizards may branch based on segment. + +--- + +## Anti-patterns in ah-ha moment design + +Tutorial-as-ah-ha. Treating "learned about the features" as activation. The user knows what the product does but has not seen it do something specifically for them. Knowledge-tied, not action-tied; not real activation. + +Demo-as-ah-ha. Showing a polished demo that does not use the user's data. The user sees what is possible but not what is true for them. Contrived; activation does not stick. + +Multi-moment ah-ha. Treating "see all features" as the moment. No single moment lands; the user feels they need to see everything before getting it. + +Delayed ah-ha. The ah-ha moment lands two sessions in. The user does not return for the second session. + +Theoretical ah-ha. "When users connect their data and run their first analysis, they will love it." Belief without evidence. Without research validating the moment, the wizard is built on theory. + +--- + +## Measuring ah-ha moment effectiveness + +Activation rate is the metric. Completion rate is leading indicator at best. + +Activation as the metric. Define activation explicitly (e.g., user returned within 7 days and engaged with feature X). Track it. + +Wizard completion as leading indicator. Useful but insufficient. A high completion rate with low activation rate signals the wizard's ah-ha moment is wrong. + +Time-to-activation. Hours from signup to activation. Shorter correlates with retention. + +Per-segment activation. Different segments may have different activation rates. Surfaces audience-fit issues. + +--- + +## Validating the ah-ha moment + +Once defined, validate. + +Cohort analysis. Compare cohorts that hit the moment vs cohorts that did not. Did hitting it correlate with retention? If not, the moment is wrong. + +User research. Interview users who hit the moment. Did they recognize it as the ah-ha moment, or just another step? + +A/B testing. Test wizard variations that converge on the moment vs variations that do not. Activation rate difference quantifies the moment's value. + +The discipline. The ah-ha moment is a hypothesis until validated. Treat it as such. + +--- + +## Common ah-ha moment failures + +No defined moment. Wizard built without identifying the moment; result is decorative. + +Wrong moment defined. Moment defined based on intuition; cohort analysis shows it does not predict retention. + +Moment too late. Moment lands after multiple sessions; users do not return. + +Moment requires too much work. Moment is real but the user has to do significant setup; drop-off before the moment. + +Moment varies wildly by segment. Single-moment design fails for an audience with different needs. + +--- + +## Methodology-level choices that stay in the public skill + +The ah-ha principle. Methods for identifying the moment. Common patterns by product type. Designing the wizard around the moment. Time-to-value as design constraint. Audience-specific moments. Anti-patterns. Measurement. Validation. Common failures. + +## Implementation choices that stay internal + +Specific ah-ha moments for specific products. Specific cohort definitions. Specific research methodologies. The team's research capacity. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md new file mode 100644 index 0000000..63b23a1 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/common-onboarding-failures.md @@ -0,0 +1,171 @@ +# Common onboarding failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "activation is low" or "users skip the wizard" or "we cannot tell if the wizard works." + +--- + +## "Activation rate is low; completion rate is high." + +The diagnosis. Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. + +The cure. Redesign around the ah-ha moment (`references/ah-ha-moment-engineering.md`). Define activation explicitly; verify the wizard produces it; cut steps that do not contribute. + +--- + +## "Skip rate is over 50 percent." + +The diagnosis. Either the wizard is not earning its time or skip is too prominent. Audit both. + +The cure. Audit step value (each step contribute to ah-ha?). Audit skip prominence (skip too easy?). Detail in `references/step-architecture-patterns.md` and `references/skip-and-resume-mechanics.md`. + +--- + +## "Users complete the wizard then abandon the product within 24 hours." + +The diagnosis. Time-to-value too long; ah-ha moment not in first session. + +The cure. Move the ah-ha moment earlier. If the moment naturally takes longer, design an interim ah-ha for the first session. + +--- + +## "Wizard works for new users; existing users hit broken steps." + +The diagnosis. Wizard not maintained alongside product; deprecated features still in flow. + +The cure. Maintenance discipline. Quarterly audit. Product changes trigger wizard updates as part of the change. + +--- + +## "Different segments complete at very different rates." + +The diagnosis. Audience-fit varies; consider role-based or use-case-based branching. + +The cure. Differentiate by segment where the differentiation produces materially different paths. Detail in `references/user-type-variation-patterns.md`. + +--- + +## "Mobile completion is half of desktop." + +The diagnosis. Mobile UX broken or compromised. + +The cure. Mobile-first design and testing. Test on actual devices. + +--- + +## "We added more onboarding steps; activation went down." + +The diagnosis. Tutorial-overload pattern; more is not better. + +The cure. Cut steps that do not contribute to the ah-ha moment. Defer feature explanations to in-product tours. + +--- + +## "Skip mechanics work but users do not return to complete setup." + +The diagnosis. Skip-and-defer not working; in-product prompts to return are missing or ignored. + +The cure. Audit prompt logic. Ensure prompts trigger at moments of relevance, with frequency limits, and route to the right setup flow. + +--- + +## "Wizard analytics broke after the last release." + +The diagnosis. Instrumentation drift; track and refresh. + +The cure. Verify analytics after every release. Add a smoke test to the deployment process. + +--- + +## "We A/B tested wizard length; conversion did not change." + +The diagnosis. Length alone may not be the issue. Could be step content, skip prominence, or the underlying ah-ha definition. + +The cure. Test variables that matter (skip prominence, ah-ha placement, step coherence). Length is one variable; isolate the right one. + +--- + +## "Activation looks good; retention is poor." + +The diagnosis. Activation metric may be wrong. Users hit a moment that does not predict retention. + +The cure. Validate the ah-ha moment with cohort analysis. Did users who hit it actually retain? If not, the moment is wrong. + +--- + +## "We cannot tell which step needs work." + +The diagnosis. Aggregate completion tracked but not per-step. + +The cure. Per-step instrumentation (`references/drop-off-measurement-templates.md`). + +--- + +## "Wizard worked great at launch; activation has declined." + +The diagnosis. Decay. Audience shifted; product evolved; references stale. + +The cure. Quarterly audit. Update what has decayed. + +--- + +## "Sales says the leads from signup are different than they used to be." + +The diagnosis. Audience composition shifted; the wizard's segmentation may be obsolete. + +The cure. Update branching or differentiation. Audit the audiences arriving and what they need. + +--- + +## "We built a wizard; the team thinks the bot would have been better." + +The diagnosis. Possibly. Different products warrant different activation tools. + +The cure. Validate. If the bot would serve better, test or migrate. The wizard format is not always the right tool. + +--- + +## "Power users complete the wizard then abandon." + +The diagnosis. Wizard does not respect power users' speed. They want to skip ahead. + +The cure. Add power-user paths. Skip should be available; advanced configuration should be findable post-wizard. + +--- + +## "We localized the wizard; activation in some locales dropped." + +The diagnosis. Translation quality, cultural mismatch, or audience-fit specific to the locale. + +The cure. Audit translation. Audit cultural assumptions. Verify audience-fit per locale. + +--- + +## "The wizard works on Chrome; it crashes on Safari mobile." + +The diagnosis. Browser/device-specific bugs. + +The cure. Cross-browser, cross-device testing. + +--- + +## The pattern across failures + +Most onboarding wizard failures fall into one of three patterns. + +Pattern 1: The wizard does not engineer the ah-ha moment. Tutorial-overload, decoration steps, demo-as-ah-ha, late ah-ha. The fix is to redefine and converge on the moment. + +Pattern 2: The wizard does not match the audience. Skip-friendly-empty, validation-strict, mobile-broken, segment mismatch. The fix is matching the wizard to where the audience actually is. + +Pattern 3: The wizard decays. Stale references, broken steps, analytics drift. The fix is maintenance discipline. + +The metric pattern: wizard failures often look fine on completion alone. The signal is in activation, retention, drop-off per step. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (ah-ha, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md new file mode 100644 index 0000000..6012f5a --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md @@ -0,0 +1,230 @@ +# Drop-off measurement templates + +Per-step instrumentation. Common drop-off patterns and remediation. Without per-step tracking, drop-off remediation is guesswork. + +The metrics inform every other improvement. Set up tracking before the wizard launches. + +--- + +## The instrumentation requirement + +Track step start, step completion, step abandonment for every step. + +Minimum tracking. + +- Wizard start (user landed on step 1). +- Step start (user reached step N). +- Step completion (user finished step N, advanced to step N+1). +- Step abandonment (user left without completing). +- Wizard completion (user finished all steps, reached end). +- Skip events (per step where applicable). + +Derived metrics. + +- Step completion rate (users who reached step / users who completed it). +- Step skip rate (users who reached step / users who skipped). +- Funnel completion rate (started wizard / finished). +- Time per step. + +Without this data, every diagnostic is theoretical. + +--- + +## Common drop-off points + +Three patterns recur across onboarding wizards. + +First-step drop-off. User landed on the wizard, looked at it, left. + +Common causes. +- Wizard length visible upfront and intimidating. +- Value proposition unclear. +- Audience expected no wizard. +- Mobile UX broken. + +Mid-wizard drop-off. User abandoned mid-process. + +Common causes. +- Specific step too demanding (high field count, sensitive question, ambiguous input). +- Cumulative fatigue (wizard too long). +- Friction at validation or backend processing. +- Time pressure (user expected faster). + +Late-step drop-off. User completed most steps but abandoned near the end. + +Common causes. +- Final step requires information the user does not have. +- Wizard length felt longer than expected. +- Submission anxiety (user does not know what happens after). + +--- + +## Remediation patterns + +For each drop-off pattern. + +First-step drop-off. + +- Reduce visible upfront length (defer to multi-screen or progressive disclosure). +- Clarify value ("This 5-step setup connects your data and shows your first insight"). +- Reduce step-1 cognitive load (start with the easiest step). +- Test mobile experience. + +Mid-wizard drop-off. + +- Audit the high-drop step. Is it too demanding? Sensitive? Ambiguous? +- Reduce field count or split into multiple smaller steps. +- Add progress indicator if missing. +- Add reassurance copy if the step is sensitive. +- Reword ambiguous fields. + +Late-step drop-off. + +- Reduce final-step requirements (move some fields earlier). +- Add post-submission preview ("After this, we'll set up your dashboard"). +- Add explicit confirmation step before submission. + +--- + +## Drop-off and skip distinction + +Skip is intentional; drop-off is involuntary. Track them separately. + +Skip metrics. + +- Skip rate per step (users who reached step / users who skipped). +- Resume rate per skip (users who skipped step / users who returned to complete). +- Activation rate per skip (users who skipped specific steps and still activated). + +Drop-off metrics. + +- Abandonment rate per step (users who reached step / users who left without completing or skipping). +- Time-to-abandonment. +- Re-engagement rate (users who came back to retry the wizard). + +The diagnostic value. Skip suggests the user does not value this step right now. Drop-off suggests the wizard failed to engage the user. + +--- + +## Tracking conditional paths + +Wizards with branching logic have multiple paths. + +Per-path tracking. + +- Tag each user's path through the wizard. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +Path-specific remediation. A path that drops off at step 4 may need step-4 redesign for users on that path. Other paths may not need attention. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +Segment-level tracking. + +- Tag users by source, device, role, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +Common segment patterns. + +- Mobile users drop off more on long steps. +- Paid-traffic users drop off earlier than organic. +- New users drop off more than returning visitors. + +Remediation by segment. Sometimes the right answer is segment-specific (e.g., shorter wizard variant for mobile). + +--- + +## Time-to-completion tracking + +How long the wizard takes. + +Total time distribution. Plot the time-to-complete distribution. Median, p25, p75, p95. + +Per-step time. Which steps take longest? Are they earning the time? + +Patterns. + +- Wizards taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Long-tail completers (p95) often signal usability issues. + +Remediation by time. Wizards or steps taking too long should be split or simplified. + +--- + +## A/B testing wizards + +Test changes rigorously. + +Test design. Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall activation. + +Common test types. + +- Wizard length (shorter vs longer). +- Step ordering (different sequences). +- Field count per step. +- Skip prominence. +- Help text presence/absence. +- Default-heavy vs required-now-optional-later. + +Test discipline. One variable at a time. Long enough to capture activation signal. Measure both wizard metrics and downstream activation. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +The signal. Wrong audience self-selecting out. A wizard that filters out audiences who would not activate anyway is doing its job. + +The discipline. Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream activation metric reveals which. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. + +--- + +## Wizard analytics dashboard + +What to surface. + +Per-step funnel. Start rate, completion rate, drop-off rate per step. + +Skip rates per step. Where skip is enabled. + +Time-to-completion distribution. With percentile breakdown. + +Activation rate per cohort. Wizard completers vs non-completers; activation by skip pattern. + +Trend over time. Have the metrics changed since the last release? + +--- + +## Common analytics failures + +No instrumentation. Wizard launched without tracking; quality is invisible. + +Aggregate-only tracking. Wizard completion tracked but not per-step; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; field renames or step changes broke the tracking. + +Skip and drop-off conflated. Cannot distinguish intentional skip from involuntary drop-off. + +Activation not tracked. Wizard metrics in isolation; cannot tell if completion correlates with activation. + +No segment-level data. Aggregate hides segment-specific issues. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points and causes. Remediation patterns. Drop-off vs skip distinction. Tracking conditional paths. Per-segment analytics. Time-to-completion. A/B testing. When drop-off is signal. Dashboard composition. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific wizards. Specific tooling. Specific A/B test designs. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md new file mode 100644 index 0000000..8b831d9 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md @@ -0,0 +1,238 @@ +# Progressive disclosure patterns + +Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Wizards that try to show everything become tutorial-overload. Wizards that defer everything become skip-friendly-empty. Progressive disclosure is the discipline that surfaces what matters when it matters. + +--- + +## Pattern A: Default-heavy + +Each step has smart defaults; the user can accept or override. + +How it works. + +- Inputs come pre-filled with sensible defaults. +- The user reviews; accepts most; overrides where their context differs. +- Most users move through quickly; advanced users find the override controls. + +Strengths. + +- Reduces cognitive load. +- Faster completion. +- Users without strong preferences proceed; users with strong preferences customize. + +Weaknesses. + +- Defaults must be honest. Bias-flattering defaults erode trust. +- Defaults need maintenance as the product evolves. + +When to use. Default for most wizards. Smart defaults reduce friction without removing customization. + +--- + +## Pattern B: Required-now, optional-later + +Required fields surface in the wizard; optional configuration surfaces in-product after activation. + +How it works. + +- Each step has only required fields. +- Optional configuration appears as in-product prompts after the wizard. +- The wizard stays focused on minimum-viable activation. + +Strengths. + +- Shortest possible wizard. +- Optional configuration happens when the user has product context. +- Activation rate improves; configuration completeness rises. + +Weaknesses. + +- Requires in-product prompt infrastructure for the deferred configuration. +- Some users may never return to complete deferred setup. + +When to use. When the wizard has accumulated optional fields that bloat completion time. The strongest pattern for trimming bloated wizards. + +--- + +## Pattern C: Expand-on-demand + +Sections collapsed by default; the user expands if interested. + +How it works. + +- Step shows the minimal interface. +- An "advanced options" or "more details" toggle expands additional fields. +- Most users skip; advanced users explore. + +Strengths. + +- Surfaces depth without forcing it. +- Power users get what they need. + +Weaknesses. + +- Risk of hiding important fields the user does not realize they need. +- Adds visual complexity to the step. + +When to use. When some users genuinely need depth that most do not. Use sparingly; default-heavy plus required-now-optional-later usually serves better. + +--- + +## Pattern D: Branching + +Different users see different steps based on earlier answers. + +How it works. + +- Step 1 asks about role, use case, or context. +- Subsequent steps adapt based on the answer. +- Different users effectively complete different wizards. + +Strengths. + +- Each user sees only steps that apply to them. +- Wizard feels personalized. + +Weaknesses. + +- Significant maintenance complexity. +- Testing burden grows (more paths). +- Analytics must accommodate variable paths. + +When to use. When the audience genuinely splits into segments with materially different needs. 2-3 branches max; more becomes unmaintainable. + +--- + +## Pattern E: Hybrid + +Combining patterns. Default-heavy plus required-now-optional-later plus a single branch for major audience split. + +Strengths. + +- Reduces friction at multiple levels. +- Different users benefit from different mechanisms. + +Weaknesses. + +- Design and maintenance complexity. + +When to use. When the wizard's audience and content warrant the combination. Most production wizards land in some hybrid configuration. + +--- + +## What to surface vs defer + +The decision per field. + +Surface in the wizard. + +- Fields without which the product cannot work for the user. +- Fields that affect the ah-ha moment. +- Fields that branch downstream steps. +- Fields that personalize the immediate experience. + +Defer to in-product. + +- Fields that affect long-term configuration but not immediate value. +- Fields that benefit from product context (the user understands what they are configuring). +- Fields that are commonly skipped anyway; surface them at moments of relevance. + +The deferable test. For each wizard field, ask: would the user be better served setting this up after seeing the product, with relevant context? If yes, defer. + +--- + +## Default discipline + +Defaults are powerful. They must be honest. + +Honest defaults. + +- Defaults reflect the typical case for the audience. +- Defaults are sourced (from cohort data, common practice, or team judgment). +- Defaults can be overridden visibly. + +Bias-flattering defaults. + +- Defaults set to produce favorable signup metrics (cheap plan pre-selected, opt-in checked) without disclosure. +- Defaults that misrepresent the user's real choice. +- Defaults that change over time without user notice. + +The discipline. Defaults reduce friction; they should not extract data or commitment the user did not consent to. + +--- + +## Information density per step + +How much to show. + +Minimal density. Just the required fields plus a sentence of context. Shortest, fastest. + +Moderate density. Required fields plus brief explanation plus optional toggle. Balanced. + +Heavy density. Multiple sections, expandables, detailed help text. Most cognitive load. + +The right density depends on the audience and the step's complexity. Default to minimal; add density only when the step's complexity warrants it. + +--- + +## Help text discipline + +When to include explanatory text. + +Strong help patterns. + +- Inline tooltip on non-obvious fields. +- One-sentence explanation per step ("we use this to tailor your dashboard"). +- Examples for fields where the format is ambiguous. + +Weak help patterns. + +- Long help text on every field. +- Help text that is marketing rather than explanation. +- Help text that explains things the user already knows. + +The discipline. Help text earns its inclusion when it reduces friction. Help text for the sake of completeness adds clutter. + +--- + +## Mobile considerations + +Progressive disclosure on mobile. + +Mobile-first defaults. Default values matter more on mobile because typing is harder. + +Single question per screen. Mobile screens are small; multi-field steps cramp. + +Touch-friendly toggles. Expand/collapse must be touch-targetable. + +Minimal help text. Mobile users skim; long help text is dismissed. + +--- + +## Common progressive disclosure failures + +No defaults. Every field blank; the user does work the wizard could have done. + +Bias-flattering defaults. Defaults extract commitment the user did not consent to. + +Over-disclosed. Every field surfaced; tutorial-overload. + +Under-disclosed. Important fields hidden; the user finishes the wizard with a misconfigured product. + +Branching without need. Branches that do not produce materially different paths add complexity without benefit. + +Help text bloat. Every field has a paragraph of explanation; cognitive load climbs. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns (default-heavy, required-now-optional-later, expand-on-demand, branching, hybrid). Strengths, weaknesses, when-to-use guidance. What to surface vs defer. Default discipline. Information density. Help text discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific wizards. Specific help copy in brand voice. Specific tooling for progressive disclosure. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md new file mode 100644 index 0000000..b41edba --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md @@ -0,0 +1,205 @@ +# Skip and resume mechanics + +Skip patterns and resume patterns. The skip-friendly-empty failure. Honest skip, honest resume. + +When users skip, where they land. When they resume, what they see. Skip mechanics done well let users escape without abandoning; done poorly, they produce skip-friendly-empty wizards where users skip into a useless product and churn. + +--- + +## The skip principle + +Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +The win. A user clicks "Skip for now" on a setup step. The product places them in a partially-configured state with a clear callout: "Your workspace needs a connected data source to show insights. Set it up here when you're ready." The user understands; engages later. + +The fail (skip-friendly-empty). A user clicks "Skip" on every step. The product places them in an empty state with no context; the user does not know what to do; they leave and never return. + +The discipline. Skip exists, but skip is consequence-honest and recoverable. + +--- + +## Skip patterns + +Common patterns for offering skip. + +Pattern A: Soft skip with context. + +How it works. The skip option is available but explains what gets deferred. "Skip for now; we will remind you to connect your data source later." + +When to use. Most wizards. Honest about the consequence; provides a path back. + +Pattern B: Skip-and-defer. + +How it works. Skipped steps are queued for later in-product prompts. The wizard does not require completion; the prompts handle re-engagement. + +When to use. When the wizard would otherwise be too long; defer everything that can be deferred. + +Pattern C: Skip-with-warning. + +How it works. Skipping triggers an honest warning. "Skipping setup means you won't see [X] until you complete it. Continue?" + +When to use. When skipping has real consequences the user should know about. Use sparingly; warnings on every step desensitize. + +Pattern D: No skip. + +How it works. The step must be completed. No skip option. + +When to use. For wizards that absolutely require completion (compliance forms, paid signups, regulatory required steps). Use sparingly; users who cannot skip and cannot complete leave instead. + +--- + +## Skip prominence + +How visible the skip option is. + +Equal prominence. Skip and continue have similar visual weight. Honest about both options. Most common. + +Continue-prominent. Continue is the visual primary; skip is a secondary link. Encourages completion without forbidding skip. + +Skip-prominent. Skip is more visible than continue. Almost never the right choice; produces skip-friendly-empty. + +Hidden skip. Skip exists but is hidden behind a "more options" toggle. Discouraged; users cannot find escape if they need it. + +The discipline. Continue-prominent for important steps; equal prominence for most steps; never skip-prominent. + +--- + +## Skip-friendly-empty: the failure mode + +The pattern where skip is too prominent and consequence-free. + +The pattern. Every step has a "Skip" button as prominent as "Continue." Skip is consequence-free; users skip every step. + +The result. Users land in an empty product; they have no context; they leave. + +The cost. Activation rate falls off a cliff. The wizard's design effort produces an experience nobody actually completes. + +The cure. Rebalance skip prominence. Make consequences visible. Add resume mechanics so skipped steps can be completed later. + +--- + +## Resume patterns + +Where users land when they return. + +Auto-resume on next login. + +How it works. The user returns; the wizard automatically lands at the step they left. + +When to use. When wizard completion is genuinely required for product use. + +Manual resume from in-product entry. + +How it works. A persistent "Complete setup" surface in-product returns the user to the wizard. + +When to use. When the wizard is recommended but not required; users can engage with the product partially. + +Soft resume. + +How it works. The wizard fades out as the user completes equivalent actions in-product naturally. No explicit re-entry needed. + +When to use. When the in-product experience surfaces equivalent prompts; the wizard becomes redundant. + +No resume. + +How it works. Skipped steps are skipped permanently; the wizard runs once. + +When to use. Rarely. Most wizards benefit from some resume mechanism. + +--- + +## Skip-and-defer in-product prompt design + +The prompts that bring users back. + +Trigger logic. Prompts trigger based on user behavior, time elapsed, or context. "You have not connected a data source yet; here is how" appears when the user attempts to use a feature requiring data. + +Frequency limits. Prompts should not nag. One reminder per session is often enough; some prompts should appear once and dismiss permanently. + +Dismiss mechanics. "Don't show this again" is honest. Hidden dismiss options are hostile. + +Completion routing. When the user accepts the prompt, route to the right setup flow (often shorter than the original wizard step). + +--- + +## Skip mechanics by step type + +Different steps warrant different skip treatment. + +Critical setup steps (without which the product cannot work). Skip should be possible but consequence-warned. Resume mechanics aggressive. + +Optional configuration steps. Skip easy and consequence-free; resume mechanics gentle. + +Identity/personalization steps. Skip easy; the product can default; resume not necessary. + +Marketing/data-collection steps. Skip easy; the product does not need this; resume rarely warranted (skip is a clean signal of opt-out). + +The discipline. Skip prominence and resume aggressiveness should match the step's importance. + +--- + +## Resume measurement + +Track resume effectiveness. + +Skip rate per step. What percentage of users skip each step? + +Resume rate per step. What percentage of users who skipped a step later return to complete it? + +Activation rate per skip pattern. Do users who skipped step X activate at lower rates? + +Diagnostic uses. + +- High skip + low resume: wizard losing users who never come back. Audit consequences. +- High skip + high resume: skip-and-defer working. The wizard is producing graceful escapes. +- Low skip overall: wizard is engaging users; check completion and activation as next metrics. + +--- + +## Resume copy discipline + +What the resume prompt says. + +Helpful resume copy. + +- "Connect your data source to see insights. It takes 2 minutes." +- "You skipped inviting teammates earlier. Want to do that now?" +- "Almost done. Two steps left to finish setup." + +Unhelpful resume copy. + +- "You did not finish onboarding." +- "Complete setup." +- "You missed steps." + +The voice discipline. Resume copy should be helpful, not scolding. The user did not fail; they deferred. + +--- + +## Common skip-and-resume failures + +Skip too prominent. Users skip everything; activation collapses. + +No skip option. Users who need to escape leave entirely. + +Hidden skip. Users cannot find escape; frustration builds; they leave. + +No resume mechanism. Skipped users never return to complete; configuration stays incomplete. + +Aggressive resume prompts. Prompts every session; users dismiss permanently. + +Resume routes to wrong place. User accepts prompt; lands in unrelated flow. + +Resume copy scolds. User feels punished for skipping; trust degrades. + +Skip without consequence-disclosure. Users skip not knowing what they will miss; abandon when they discover. + +--- + +## Methodology-level choices that stay in the public skill + +The skip principle. Skip patterns (4 patterns). Skip prominence guidance. The skip-friendly-empty failure. Resume patterns (4 patterns). Skip-and-defer prompt design. Skip mechanics by step type. Resume measurement. Resume copy discipline. Common failures. + +## Implementation choices that stay internal + +Specific skip and resume implementations for specific wizards. Specific prompt copy in brand voice. Specific tooling for resume infrastructure. The team's resume measurement baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..b610daf --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/step-architecture-patterns.md @@ -0,0 +1,225 @@ +# Step architecture patterns + +What belongs in each step. Sequence logic. The step coherence test. + +The architecture is the structure that makes wizards work. Bad architecture produces decorative steps that do not move the user closer to value; good architecture converges on the ah-ha moment with discipline. + +--- + +## The convergence principle + +Each step should move the user one step closer to value. Steps that do not should be cut. + +The test. For each step, ask: did this step move the user toward the ah-ha moment? If no, cut it or defer it to in-product help. + +The discipline. Wizards accumulate steps over time as teams add "while we have them" requests (collect more data, surface more features, etc.). The discipline is to resist accumulation; the wizard's job is convergence, not feature pride. + +--- + +## Common step patterns + +Patterns that recur across product onboarding wizards. + +Welcome and orientation. + +- Purpose: set expectations for what the wizard will do. +- Skippable: usually yes, low cost. +- When to include: when the wizard's purpose is not obvious from context. +- When to skip: when the wizard's purpose is obvious; welcome adds friction without value. + +Identity and account context. + +- Purpose: capture who the user is, what brought them here. +- Required fields: minimal. Name and role are often enough. +- When to include: when subsequent steps adapt to identity. +- When to skip: when subsequent steps do not adapt; identity capture is just data collection. + +Critical setup step. + +- Purpose: the one thing the product cannot work without. +- Examples: connect data source, invite first teammate, set primary use case. +- This is often where wizards justify their existence. Without this step, the user lands in an empty product. + +First-action step. + +- Purpose: get the user to take a meaningful action that produces visible result. +- The ah-ha moment lives here or right after. +- Should be guided enough that success is likely; honest enough that the success is real. + +Configuration deferral. + +- Purpose: surface things that can be set up later but are commonly needed. +- Lets the user defer with a clear path back. +- Reduces wizard length without losing coverage. + +Confirmation and next steps. + +- Purpose: recap what was set up; surface what to do next; route to in-product home. +- Closes the wizard cleanly. +- Often skipped in design but useful for orientation. + +--- + +## Step sequencing principles + +The order matters as much as the steps themselves. + +Principle 1: Earn the patience. Open with low-friction steps; the user invests; deeper setup follows. Critical setup demanding effort works better at step 2-3 than step 1. + +Principle 2: Ah-ha moment by step 3-5. If the wizard runs longer than 5 steps before any visible value, drop-off climbs sharply. + +Principle 3: Deferable last. Steps that can be deferred should sit late in the wizard, where skip is least costly. + +Principle 4: Confirmation explicit. Close the wizard with a clear "you are done; here is what's next" step. Without it, users feel dropped. + +--- + +## Step coherence test + +For each step, can it be described in one sentence as a unit of work that contributes to the ah-ha moment? + +Coherent steps. + +- Step 1: tell us about your role so we can tailor what comes next. +- Step 2: connect your data source so we can show you something useful. +- Step 3: run your first query and see a result. +- Step 4: save the result so you can return to it. +- Step 5: optionally invite a teammate; otherwise, you are ready. + +Each step has clear purpose tied to value. + +Incoherent steps. + +- Step 1: name and email (already collected at signup; redundant). +- Step 2: tour of features (does not move toward action). +- Step 3: branding preferences (irrelevant to ah-ha moment). +- Step 4: marketing opt-in (data collection, not value). + +Steps without clear purpose should be cut or deferred. + +--- + +## Step count discipline + +How many steps is too many. + +Sweet spot. Most effective wizards run 3-7 steps. The user can predict completion time; the convergence is tight. + +Too few. 1-2 steps usually means the wizard format is overkill; contextual prompts often serve better. + +Too many. 10+ steps signals tutorial-overload. Drop-off climbs sharply; users skip when they can. + +The deferable test. For wizards exceeding 7 steps, audit each step. Which can be deferred to in-product? Often half can. + +--- + +## Field count per step + +Within each step, how many fields. + +3-5 fields per step. Sweet spot. Coherent unit; completable in 30-60 seconds. + +1-2 fields per step. Often signals over-staging. The user wonders why the field needed its own step. + +6+ fields per step. Recreates the kitchen-sink problem within a step. Audit; usually some fields can be cut or deferred. + +--- + +## Branching and conditional steps + +When wizards adapt based on earlier answers. + +The pattern. First step asks about role or use case; subsequent steps adapt. + +Strengths. The wizard feels relevant; users see only what applies to them. + +Weaknesses. Maintenance complexity; testing across paths. + +The discipline. Branch only when the variability genuinely benefits the user. Decorative branching adds cost without lift. + +--- + +## Step transitions + +How the user moves between steps. + +Forward transitions. Clear "Next" or "Continue" CTA. Validation runs before the transition. Snappy; no loading delays. + +Back transitions. "Back" or "Previous" available. Returning to earlier steps preserves answers. + +Skip transitions. Skip available but honest about consequences. Skip lands the user in a partially-set-up state with clear callouts to complete deferred setup. + +Loading state. When the wizard's step requires backend work (connecting data source, processing input), show progress. Silent loading kills momentum. + +--- + +## Step examples by product type + +How architecture varies by product. + +B2B SaaS analytics. + +- Welcome → role/use case → connect data source → first query → first saved view → invite team (deferable) → in-product home. + +7 steps; meaningful staging; ah-ha at step 5. + +Project management tool. + +- Welcome → workspace setup → first project → first task → invite team → in-product home. + +6 steps; ah-ha around step 4. + +Marketing automation. + +- Welcome → connect site → connect data source → first audience → first campaign → in-product home. + +6 steps; ah-ha at first audience visualization. + +Consumer note-taking. + +- Probably no wizard. Empty-state prompts and contextual hints serve better. + +The patterns vary. The discipline (each step earns its place; ah-ha moment by step 3-5) holds. + +--- + +## Step architecture maintenance + +Steps decay. Product changes mean wizard updates. + +Maintenance triggers. + +- Product feature added that the wizard should reference. +- Product feature deprecated that the wizard still references. +- Setup process changed; wizard steps no longer match. +- Audience composition shifted; old role-branching no longer fits. + +Maintenance cadence. Quarterly review minimum; product changes trigger updates as part of the change. + +--- + +## Common architecture failures + +Decorative steps. Steps that do not move toward value. + +Tutorial steps. Steps explaining features the user has not asked about. + +Front-loaded effort. High-friction step first; users abandon at step 1. + +Late ah-ha moment. Wizard runs 10 steps before visible value. + +Mandatory steps that should be deferable. Forces friction users would have accepted later. + +No confirmation step. User finishes the wizard, lands somewhere unclear. + +Step transitions sluggish. Loading delays kill momentum. + +--- + +## Methodology-level choices that stay in the public skill + +The convergence principle. Common step patterns. Sequencing principles. The step coherence test. Step count discipline. Field count per step. Branching considerations. Step transitions. Step examples by product type. Maintenance discipline. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific products. Specific copy and tone. Specific tooling. Specific testing protocols. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md new file mode 100644 index 0000000..d274a99 --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/user-type-variation-patterns.md @@ -0,0 +1,199 @@ +# User type variation patterns + +Admin vs end-user, technical vs non-technical, size-based branching. When one wizard does not serve all users. + +Different users may need different wizards. The discipline is to differentiate where the audience genuinely splits, without producing unmaintainable proliferation. + +--- + +## The differentiation principle + +Differentiate where the audience genuinely splits into segments with materially different needs, language, or paths. Do not differentiate where one wizard serves all. + +The win. Admins set up the workspace; end-users start using it. A single wizard tries to serve both and fails both. Differentiated wizards serve each meaningfully. + +The fail. A team builds 5 wizard variants for 5 imagined personas. Maintenance burden compounds; the variants diverge over time; no variant is excellent. + +The discipline. Start with one wizard. Differentiate only when data shows segments with different needs and the differentiation produces meaningfully different paths. + +--- + +## Common differentiation axes + +Three axes recur. + +Admin vs end-user. + +- Admins set up the workspace, invite teammates, configure integrations. +- End-users start using what admins set up. +- Their first sessions look different; the ah-ha moments differ. + +Technical vs non-technical. + +- Technical users want depth (see the API, see the integration succeed, configure deeply). +- Non-technical users want outcome (see the result, no API). +- Tone, content, and step coverage differ. + +Size of team. + +- Solo founders configure for one. +- Small teams configure for collaboration. +- Enterprise teams have additional setup (SSO, governance, compliance). + +--- + +## Differentiation patterns + +How to implement. + +Pattern A: Role-based branching. + +How it works. First step asks role; subsequent steps adapt. + +When to use. When the role split is clear and produces different paths. + +Pattern B: Use-case-based branching. + +How it works. First step asks use case; wizard tailors to that use case. + +When to use. When the product serves multiple use cases that warrant different ah-ha moments. + +Pattern C: Size-based branching. + +How it works. First step asks team size; solo, team, enterprise paths differ. + +When to use. When the product has materially different setups for different scales. + +Pattern D: Inferred branching. + +How it works. Wizard uses signals (signup source, email domain, prior interaction) to infer the segment without asking. + +When to use. When asking would feel intrusive but the inference is reliable. + +Pattern E: No branching. + +How it works. Single wizard for all. + +When to use. Most products. Branching adds maintenance; only branch when the value is clear. + +--- + +## Admin vs end-user wizard design + +How they differ. + +Admin wizard. + +- Setup-heavy. Connect data, invite team, configure permissions. +- Ah-ha moment: "the workspace is ready; my team can use it." +- Often longer; admins accept guided setup. + +End-user wizard. + +- Action-light. Find the feature, take the first action, see the result. +- Ah-ha moment: "I did the thing I came to do." +- Often shorter; end-users want to start using. + +Cross-talk. Admins sometimes also become end-users in single-person teams. The wizard may need to detect and serve both modes. + +--- + +## Technical vs non-technical wizard design + +How they differ. + +Technical wizard. + +- API depth visible (configuration shown, integration tested). +- Tone: precise, terse, references documentation. +- Ah-ha moment: "the integration works; my data is flowing." + +Non-technical wizard. + +- Outcome visible (result shown, no API exposed). +- Tone: warm, supportive, hides technical complexity. +- Ah-ha moment: "I see the result the product promised." + +Cross-talk. Some users are technical for some products and not for others. The wizard may infer rather than ask. + +--- + +## Size-based wizard design + +How they differ. + +Solo founder wizard. + +- Single-user setup. +- Skip team-related steps. +- Ah-ha moment: individual productivity. + +Small team wizard. + +- Collaboration setup highlighted. +- Invite-team step prominent. +- Ah-ha moment: team coordination. + +Enterprise wizard. + +- SSO, governance, compliance setup. +- Often involves admin handoff to IT or security. +- Ah-ha moment: deployment-ready configuration. + +--- + +## When to combine vs separate + +Designing the matrix. + +Combine when: + +- The differentiation is small (1-2 different steps). +- Maintenance burden is the bigger concern. +- The audiences overlap significantly. + +Separate when: + +- The paths differ in 3+ steps. +- Tone and language differ significantly. +- Audience-fit is critical (B2B SaaS where different roles experience the product very differently). + +The 2-3 variants max rule. More than 3 wizard variants becomes unmaintainable. If 4+ variants seem necessary, reconsider whether the segmentation is too granular or whether different wizards should be different products. + +--- + +## Differentiation testing + +Verify the differentiation works. + +Cohort comparison. Compare activation rates across variants. Did differentiation help? + +Per-segment satisfaction. Survey users post-wizard. Does each segment feel served? + +Drop-off per variant. Are some variants dropping off more than others? Which steps? + +The data informs whether the differentiation earned its complexity. + +--- + +## Common differentiation failures + +Over-differentiation. Too many variants; maintenance burden; no variant is excellent. + +Under-differentiation. One wizard for distinct audiences; everyone feels poorly served. + +Wrong axis. Differentiated by an axis that does not predict need (e.g., gender when role would have been the right split). + +Inferred wrongly. Inference logic mistakes audience; users see wrong wizard. + +Stale differentiation. Audience composition shifted; old branching no longer fits. + +--- + +## Methodology-level choices that stay in the public skill + +The differentiation principle. Common differentiation axes. Patterns A through E. Admin vs end-user design. Technical vs non-technical design. Size-based design. Combine-vs-separate decision. Differentiation testing. Common failures. + +## Implementation choices that stay internal + +Specific wizard variants for specific products. Specific copy per variant in brand voice. Specific inference logic. The team's variant maintenance calendars. These vary by team and product. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md new file mode 100644 index 0000000..01f9cfc --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-anti-patterns.md @@ -0,0 +1,212 @@ +# Wizard anti-patterns + +The patterns that look like onboarding but degrade activation. Anti-patterns are easy to ship; the cost shows up in activation rate, retention, and brand reputation over time. + +--- + +## The tutorial-overload wizard + +The pattern. Every feature explained in a 12-step intro before the user has touched the product. + +The signal. High skip rate; users abandon mid-wizard; activation rate poor. + +The cost. Design effort produces a sequence almost nobody completes. Users who do complete have not seen value; activation suffers. + +The cure. Prune steps to those that contribute to the ah-ha moment. Defer feature explanations to in-product tours and contextual help. + +--- + +## The skip-friendly-empty wizard + +The pattern. "Skip onboarding" button at every step, so prominent that users always take it. + +The signal. Skip rate near 100 percent; users land in unconfigured product; activation rate falls. + +The cost. The product appears empty to users who skipped; they do not know what to do; they leave. + +The cure. Rebalance skip prominence. Add consequence-honest skip warnings. Add resume mechanisms so skipped steps come back as in-product prompts. + +--- + +## The decoration-step wizard + +The pattern. Steps that exist for completeness or feature pride, not for value. + +The signal. Drop-off concentrates on specific steps users perceive as pointless; analytics shows steps users always skip. + +The cost. Wizard length without value; user perceives the wizard as bloated. + +The cure. Audit each step. Cut steps that do not contribute to the ah-ha moment. + +--- + +## The tutorial-as-ah-ha wizard + +The pattern. Treating "learned about features" as activation. Wizard ends; user has seen a tour; team treats this as success. + +The signal. High completion rate, low retention. Users completed the wizard but did not engage afterward. + +The cost. The wizard's success metric is wrong. Real activation never happens. + +The cure. Define the ah-ha moment as action-tied. Redesign the wizard to converge on the moment. + +--- + +## The demo-as-ah-ha wizard + +The pattern. The wizard ends with a polished demo using fake data. + +The signal. Users see what is possible; do not return because their actual data has not been touched. + +The cost. The wizard's value is contrived; activation does not stick because the value was hypothetical. + +The cure. Make the ah-ha moment real. Use the user's actual data. + +--- + +## The over-branched wizard + +The pattern. 5 wizard variants for 5 imagined personas. Maintenance burden compounds. + +The signal. Variants diverge over time; some break; activation per variant is uneven. + +The cost. Maintenance overhead high; quality of any one variant degrades. + +The cure. Reduce variants to 2-3 max. Combine variants where the differentiation does not produce materially different paths. + +--- + +## The under-branched wizard + +The pattern. One wizard for distinct audiences. Admins, end-users, technical, non-technical all see the same flow. + +The signal. Some segments activate well; others do not. Per-segment data shows the gap. + +The cost. The audiences underserved leave; the wizard's design effort produces good outcomes for one segment and bad for others. + +The cure. Differentiate where the audience genuinely splits. + +--- + +## The hidden-skip wizard + +The pattern. Skip exists but is hidden behind a "more options" toggle or appears only after the user struggles. + +The signal. Users who need to escape leave the product entirely instead of skipping. + +The cost. Forced friction loses users who would have engaged later if they had been allowed to defer. + +The cure. Make skip findable. Make consequences clear. Add resume. + +--- + +## The validation-strict wizard + +The pattern. Validation rejects valid inputs because rules are over-specified. + +The signal. Users with valid but unusual inputs cannot proceed; abandon. + +The cost. Filter loses real users. + +The cure. Audit validation. Email plus-aliases, international phone, non-Latin names should pass. + +--- + +## The mobile-broken wizard + +The pattern. Wizard works on desktop; breaks on mobile. + +The signal. Mobile completion half of desktop or worse. + +The cost. Mobile audience underserved; mobile is often majority of traffic. + +The cure. Mobile-first design and testing. + +--- + +## The unmaintained wizard + +The pattern. Wizard built once; product evolved; wizard not updated. + +The signal. Users hit broken steps; references to deprecated features; analytics drift. + +The cost. The wizard becomes liability; current users get worse experience than past users. + +The cure. Quarterly maintenance. Product changes trigger wizard updates as part of the change. + +--- + +## The interrogation-disguised-as-wizard + +The pattern. Wizard asks 12 fields, of which 5 affect product setup. The other 7 are sales-qualification or marketing data. + +The signal. Drop-off climbs at fields that feel like sales forms; users sense the manipulation. + +The cost. Filter loses users who would have engaged with a product-focused wizard. + +The cure. Audit fields. Remove or defer fields that do not contribute to product setup. Capture sales/marketing data later in the relationship. + +--- + +## The popup-interrupted wizard + +The pattern. User is mid-wizard; a popup appears (newsletter, chat, special offer); flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about interruption. + +The cost. Wizard's user experience hostile; brand earns annoying reputation. + +The cure. Suppress popups during wizard completion. Save promotional content for after. + +--- + +## The reset-on-error wizard + +The pattern. User submits; validation fails; wizard resets, losing user inputs. + +The signal. Users who hit error do not retry; they leave. + +The cost. The wizard treats errors punitively; trust collapses. + +The cure. Preserve inputs on error. Show error inline; let the user fix and resubmit. + +--- + +## The wizard-without-activation-metric + +The pattern. Wizard tracked by completion rate alone. Activation not measured. + +The signal. Completion looks fine; team cannot diagnose whether the wizard is producing engaged users. + +The cost. The wizard's success metric is wrong; bad wizards look good in dashboards. + +The cure. Define and track activation explicitly. Wizard completion is leading indicator at best. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active wizard, looking for these anti-patterns. + +Audit questions per wizard. + +- Does each step contribute to the ah-ha moment (anti-pattern check: tutorial-overload, decoration)? +- Is skip honest about consequences and recoverable (anti-pattern check: skip-friendly-empty, hidden-skip)? +- Does the wizard match the product's current state (anti-pattern check: unmaintained)? +- Is activation tracked (anti-pattern check: completion-only metrics)? +- Does the wizard work on mobile (anti-pattern check: mobile-broken)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is the audience segmentation right (anti-pattern check: over-branched, under-branched)? + +The retire decision. Anti-pattern wizards often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md new file mode 100644 index 0000000..f1ec10b --- /dev/null +++ b/dist/pi/.agents/skills/onboarding-wizard-design/references/wizard-decision-criteria.md @@ -0,0 +1,133 @@ +# Wizard decision criteria + +When wizards earn the build vs when contextual help suffices. The conditions that warrant the wizard format, and the funnels where a wizard adds friction without lift. + +A wizard is meaningful work. Step architecture, ah-ha moment design, progressive disclosure, skip mechanics, drop-off instrumentation, ongoing maintenance. The wizard earns this investment only when specific conditions are present. + +--- + +## When wizards earn the build + +Five conditions that, when present, make a wizard a strong investment. + +The product has meaningful setup before value emerges. Connect a data source, invite a teammate, configure a workspace, choose a use case. Without setup, the product is empty; the wizard makes setup tractable. Products that work immediately on signup do not need this. + +The ah-ha moment requires multiple actions in sequence. Single-action ah-ah moments (paste a URL, see a result) often work better with contextual prompts. Multi-action ah-ha moments benefit from a guided sequence. + +The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products often work well with wizards. Some audiences (frictionless consumer tools) reject wizard friction regardless of product complexity. + +The team can maintain the wizard. Wizards decay as the product evolves; deprecated features still in flow break the experience. Without maintenance commitment, the wizard becomes a liability. + +The success metric is defined. Not just completion rate; activation rate (post-wizard product engagement) and time-to-value. Without the success metric, evaluation is impossible. + +When all five are present, the wizard is a strong investment. When two or fewer are present, contextual prompts often serve better. + +--- + +## When wizards do NOT earn the build + +Funnels where the wizard adds friction without lift. + +The product reaches value immediately. Single-input tools, simple consumer products, frictionless utilities. A wizard adds steps where the user could already see value. + +Contextual help would suffice. Tooltips, in-feature hints, progressive in-product education sometimes serve better than upfront wizards. The user explores naturally; help surfaces when needed. + +The audience expects no friction. Some audiences abandon at any wizard. Consumer-facing high-volume products, embedded tools, prosumer utilities. Meet the audience where they are. + +The team cannot maintain the wizard. Stale wizards point to deprecated features; users hit broken steps. Without maintenance capacity, no wizard is better than a stale one. + +The setup work is genuinely better in-product. Some setup is better done after the user understands the product. Wizards that try to set up something the user does not yet understand produce poor configuration. + +The honest assessment matters more than the default. "Should we have an onboarding wizard" is not the question. "Is the wizard the right tool for this product and audience" is. + +--- + +## The opportunity-cost frame + +A wizard is significant work. Account for it. + +The build cost. Step architecture, copy, design, instrumentation, integration with the product, maintenance scaffolding. A meaningful wizard often takes 40-150 engineering hours plus design and copy. + +The maintenance cost. Quarterly review minimum; product changes trigger wizard updates. 4-12 hours per active wizard per quarter. + +The opportunity cost. What else could the team have built? Direct in-product improvements, contextual help, documentation, a simpler activation funnel. The wizard's success has to clear the bar of those alternatives. + +The decision frame. The wizard earns investment when it produces more activation lift than the alternatives, accounting for build plus maintenance. + +--- + +## The ah-ha-moment precondition + +Without an identifiable ah-ha moment, the wizard has nothing to engineer toward. + +The check. Can the team articulate the single visible moment when the user feels "oh, this is what the product does for me"? + +If yes, the wizard can be designed to converge on that moment. If no, the team has not yet defined what activation means; the wizard cannot be designed coherently until that is settled. + +Defining the ah-ha moment is upstream of wizard design. Sometimes the right move is to spend time identifying the ah-ha moment first (often through customer research) before scoping the wizard. The wizard built without a defined ah-ha moment is the wizard that produces high completion and low activation. + +--- + +## The decision worked example + +A B2B SaaS analytics platform considering an onboarding wizard. + +Conditions check. + +- Meaningful setup before value: yes. Connect at least one data source. +- Ah-ha moment multi-action: yes. Connect data, run first query, see useful result. +- Audience expects guided onboarding: yes. Data analysts and data leaders generally accept guided setup. +- Maintenance commitment: yes. Activation team owns the wizard. +- Success metric defined: yes. Activation = ran at least one query within 7 days of signup. + +Decision. Build the wizard. The conditions warrant it. + +Step architecture. Welcome (skippable) → connect first data source → confirm connection → guided first query → see result (ah-ha moment) → invite teammates (deferable) → in-product home. + +Maintenance commitment. Activation team reviews quarterly; product changes trigger wizard updates. + +The decision was not "should we have a wizard" but "given these conditions, this is the wizard to build." + +--- + +## The decision worked example: when to choose differently + +A consumer note-taking app considering an onboarding wizard. + +Conditions check. + +- Meaningful setup: no. The user can start typing immediately. +- Ah-ha moment multi-action: no. The ah-ha moment is "I can save a note and find it later," reachable without setup. +- Audience expects guided onboarding: no. Consumer note-taking audiences resist friction. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined (returned within 7 days). + +Decision. Do not build a wizard. Contextual prompts (sample notes, brief tooltip on first save, short empty-state prompts) serve better. + +The decision was "is this wizard right for this product" and the answer was no even though the team had capacity. + +--- + +## When to retire a wizard + +Wizards can become wrong even after being right initially. + +Retire when: + +- Activation rate has dropped below baseline for two consecutive quarters and refinements have not moved it. +- The product has changed enough that the wizard guides users toward deprecated paths. +- Customer research shows users skipping the wizard and activating fine without it. +- A redesigned in-product activation flow makes the wizard unnecessary. +- The team can no longer maintain the wizard. + +The retiring discipline frees capacity. Stale wizards are worse than no wizards. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant a wizard. The five conditions that argue against. The opportunity-cost frame. The ah-ha-moment precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific wizard scope decisions for specific products. The team's capacity benchmarks. Specific tooling for wizard implementation and instrumentation. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/paid-media-strategy/SKILL.md b/dist/pi/.agents/skills/paid-media-strategy/SKILL.md new file mode 100644 index 0000000..2d0a67b --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/SKILL.md @@ -0,0 +1,256 @@ +--- +name: paid-media-strategy +description: "A discipline for running paid media that does not light money on fire. Hypothesis writing for paid spend, channel selection, budget allocation, audience targeting, bid strategy, campaign types, what NOT to spend on, attribution reality, and the failure modes that produce expensive lessons. Triggers on paid media strategy, ad budget allocation, channel selection, paid media plan, audit my Google Ads, audit my Meta Ads, scale paid media, kill underperforming campaign, paid media hypothesis, ad spend strategy, attribution reality, performance marketing strategy. Also triggers when a team is asking how to scale paid media, or whether to add a new channel, or how to reallocate spend across channels." +category: marketing +catalog_summary: "Hypothesis to spend: channel selection, budget allocation, audience targeting, bid strategy, attribution reality, and the failure modes that burn agency-scale budgets" +display_order: 1 +--- + +# Paid Media Strategy + +A senior performance marketer's playbook for running paid media that produces real outcomes. + +The default state of paid media is wasted spend. Most accounts have campaigns running because they always have, audiences targeting because the rep suggested it, bid strategies on auto because manual is hard, creative not refreshed because there is no system. The cost compounds. A 20% efficiency gain on a $500K-per-year account is $100K back to the business. A 50% gain on a $5M-per-year account is $2.5M. + +This skill is the discipline that produces those gains. It assumes you have a paid media platform (Google Ads, Meta, LinkedIn, TikTok, or aggregators like Synter) connected. It assumes you have working analytics and conversion tracking. The hard part is the strategic discipline behind the spend, and that is what is here. + +When to use this skill: any time you are designing a paid media plan, evaluating whether to scale or kill a campaign, allocating budget across channels, or auditing an existing account. + +--- + +## What this skill is for + +This skill spans paid media strategy and operations. It does not cover ad creative production (use `ads-creative-development`), result interpretation in depth (use `ads-performance-analytics`), or platform-specific MCP tooling (consult each ad platform's official documentation for current MCP setup, auth, and example prompts). + +The audience is a performance marketer (in-house or agency), a growth lead allocating spend across channels, or a founder making early paid budget decisions. The voice is tactical. There is no "evaluate every option yourself with no opinion." Paid media decisions have shape, and a senior practitioner can map a situation to a defensible plan in an afternoon. + +--- + +## Hypothesis discipline for paid spend + +Most paid media failures start with a vague reason for spending. A real spend hypothesis has five parts: audience, offer, channel, outcome metric, and magnitude. Missing any of them and the campaign cannot be evaluated honestly. + +A bad reason: "We need to scale Google Ads spend." No audience, no outcome metric, no magnitude. Nothing is falsifiable. + +A good hypothesis: "Top-of-funnel SaaS prospects searching for project management tools convert from a free-trial CTA at 3.2% CAC under $80. Increasing Search budget from $40K to $80K per month should hold CAC under $80 and add roughly 500 trial signups based on Q3 search volume." + +That hypothesis names the audience (top-of-funnel SaaS prospects on PM-tool keywords), the offer (free trial), the channel (Google Search), the outcome metric (CAC, trial signups), and the magnitude (500 signups, CAC under $80). It is falsifiable: if CAC blows past $80 or signups come in below 250, the hypothesis is wrong and you pull back. + +Pre-commit the falsification rule. Decide before scale: at what CAC do we hold? At what CAC do we pull back? At what trial-signup count do we kill? Without pre-commit, every result becomes a debate. With pre-commit, the decision is mechanical. + +Primary metric is the one you are optimizing for (CAC, ROAS, CPL). Guardrails are the metrics you do not want to break (LTV, retention, brand search lift). Scaling the primary metric while breaking a guardrail is a Pyrrhic win. + +--- + +## Channel selection: when to use which platform + +Pick the channel where intent matches your offer. Run the wrong channel and your CAC reads as a channel problem when it is actually a fit problem. + +Google Search. High-intent demand capture. Best when you have a real product people search for and the query volume justifies the floor. Worst when category awareness is low and no one is searching. Predictable, expensive at scale, the highest floor of any channel. + +Google Performance Max. Automated multi-channel within the Google ecosystem. Best when you have a strong product feed (e-commerce) or want to lean into Google's automation. Worst when you need control over placements; PMax is a black box and disagreements with the algorithm cost money. + +Meta (Facebook plus Instagram). Broad-targeting demand creation. Best for visual products, lifestyle brands, B2C scale, and direct response with strong creative. Worst when targeting is too narrow (audiences saturate fast) or when the offer is high-consideration B2B. + +TikTok. Discovery-mode advertising. Best for native-feeling video creative, younger audiences, and brand awareness. Worst for direct response with high consideration cycles. Spark Ads (boosting organic posts) outperform pure paid creative. + +LinkedIn. B2B targeting precision. Best for high-LTV B2B with clear job-title targeting. Worst for low-AOV products; the floor is too high to be efficient. + +Reddit, Pinterest, Snapchat, X. Niche or supplementary. Best as scale-out channels after primary channels are working. Worst as starting points; spreading thin across niches before you have proven any channel is the most common waste pattern. + +YouTube (Google). Video at scale. Best for awareness or for B2C consideration. Underrated for B2B SaaS in some categories where the buyer-research path includes long-form video. + +The decision rule. Start with the channel where intent matches your offer. Search for high-intent demand capture. Meta or TikTok for demand creation. LinkedIn for B2B precision. Do not run all of them at once until you have proven any of them. Detail in [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md). + +--- + +## Budget allocation: brand vs performance, baseline vs test + +Four splits operate at the same time. Get them all right and the budget compounds. + +Brand vs performance. Brand keeps the demand pipeline filled (long term); performance captures it (short term). 70-30 to 80-20 performance-heavy is typical for most B2C. Brand-heavy splits fit high-consideration B2B where the buying cycle is months long and pipeline visibility matters more than week-over-week conversions. + +Baseline vs test. 70 to 80% of budget to channels, campaigns, and audiences that are working. 20 to 30% to systematic testing of new channels, new audiences, new creative. Without test budget, you stagnate. Without baseline budget, you have nothing to scale. + +Primary vs secondary channel. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the equal-split temptation; spreading across channels before any one is proven is the most expensive way to learn nothing. + +Daily vs lifetime budgets. Daily for ongoing campaigns where you want a stable spend floor. Lifetime for finite tests where the platform should pace itself across the test window. Lifetime budgets prevent runaway spend during testing. + +Budget pacing matters too. Front-load some weeks to test creative aggressively. Back-load others to capture seasonality (holiday, end-of-quarter, category-specific moments). Do not run flat; flat budgets miss the demand peaks. + +Detail and templates in [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md). + +--- + +## Audience targeting: prospecting vs retargeting vs exclusion + +Three audience types. Treat them as separate strategies. + +Prospecting. New people who have not heard of you. Lookalike audiences (Meta), in-market audiences (Google), interest stacks, lookalikes seeded from high-LTV customers. Largest budget share for growth-mode brands; this is where new demand comes from. + +Retargeting. People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC. Do not bid too aggressively or you train the platform to charge a premium for users who would have converted anyway. + +Exclusion. Current customers and recent converters kept out of prospecting and retargeting. Saves spend, keeps frequency low, prevents creative fatigue from people who are already paying you. + +Common mistakes. Prospecting too narrow (not enough audience for the platform to optimize). Retargeting too aggressive (cannibalizing organic conversions). No exclusions (paying to advertise to your own paying customers). Lookalikes off the wrong source (use top-LTV customers, not all customers). + +Detail in [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md). + +--- + +## Bid strategy: when each fits + +Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. + +Manual CPC or CPM. Full control, slow to scale. Useful for diagnostics and very early campaigns where you do not trust the platform's machine learning yet. + +Maximize Conversions. Platform optimizes for volume within budget; the platform decides CPC. Use when you want as many conversions as possible regardless of cost. Good early-stage strategy while you gather data. + +Target CPA (tCPA). Set a max CPA, platform delivers within. Use when CPA is the constraint and you have at least 30 conversions in the recent window for the platform to optimize against. + +Target ROAS (tROAS). Set a min ROAS, platform delivers above. Use when revenue per conversion varies and you care about value, not count. + +Maximum Conversion Value. Like maximize conversions but optimizes for total revenue, not count. Use when high-value conversions are the goal and you have the conversion-value data wired in. + +Enhanced CPC. Manual CPC with platform adjustments. Hybrid; rarely the right answer because it muddies the signal. + +The progression for new campaigns: start manual or maximize conversions to gather data, switch to tCPA or tROAS once you have 30+ conversions, revisit periodically. + +Common mistakes. Using tCPA before you have 30+ conversions (no data to optimize against). Setting tROAS too aggressively (platform throttles delivery). Switching strategies too often (each change resets the learning phase). Detail in [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md). + +--- + +## Campaign types + +For each major platform, the campaign types and when to use them. + +Google Ads. Search, Shopping, Performance Max, Display, Video (YouTube), Demand Gen, Discovery, App. Search for direct demand capture. PMax for catalog-driven e-commerce. Display for retargeting. Video for awareness or consideration. + +Meta. Sales, Leads, Engagement, Awareness, Traffic, App Promotion. Sales for direct response. Awareness for brand at scale. Leads for B2B with native lead forms. + +LinkedIn. Sponsored Content, Message Ads, Conversation Ads, Lead Gen Forms. Format types: Single Image, Carousel, Video. Lead Gen Forms convert hardest because they pre-fill from LinkedIn profile data. Message Ads have stigma in many B2B segments; use carefully. + +TikTok. In-Feed, TopView, Spark Ads, Branded Hashtag Challenge. Spark Ads (boost organic posts) outperform pure paid creative because they retain organic-feel signal. Use Spark when you have organic posts performing. + +Detail per platform in [`references/campaign-type-reference.md`](references/campaign-type-reference.md). + +--- + +## What NOT to spend on + +Direct list. Audit any account against these and you will usually find easy savings. + +- Branded keywords beyond defensive. When ranking number one organically, branded paid clicks cannibalize free traffic. Some defensive spend is fine to block competitor bidding. Aggressive bidding on your own brand is waste. +- Display network without targeting. Broad display drives garbage traffic. Use only for retargeting unless you have specific contextual targeting. +- Geographic markets you do not serve. Sounds obvious, fails 30% of accounts. Audit geo targeting quarterly. +- Hours you cannot service. For service businesses (legal, B2B, medical). Pause off-hours unless lead form clearly converts asynchronously. +- Devices that do not convert. If mobile converts at 1% and desktop at 5% with the same CPC, bid down mobile aggressively. +- Audiences who never convert. Pull last 90 days of converters, build exclusion lists for everyone else who repeatedly clicks but never converts. +- Creative that is tired. Frequency above 4 with declining CTR means refresh. Refusing to refresh because "it still works ok" is incremental loss. + +The pattern across these is the same. Default settings or accumulated cruft generate spend without producing outcomes. Audit, exclude, and reclaim. + +--- + +## Creative testing: within campaign vs across campaign + +Two modes. Different learning rates, different overhead. + +Within-campaign testing rotates 4 to 6 ad variations and lets the platform optimize delivery to top performers. Lower test risk because all variations live inside one campaign with one budget. Slower learning because the platform's optimization muddies the signal of which variation actually wins. + +Across-campaign testing runs entire campaign concepts (audience plus offer plus creative) against each other. Higher learning rate because each campaign has its own audience and budget. Higher setup overhead and harder to keep apples-to-apples. + +Cadence. Refresh top creative every 30 to 60 days at scale. Weekly for high-frequency campaigns. Keep the top one or two evergreen winners running and rotate others. + +The "winning creative is the floor" principle. Do not kill winners to test new ideas. Test alongside. The downside of running the proven winner is small; the downside of killing it for an unproven concept is large. + +--- + +## Frequency capping + +Ad fatigue is real. Same audience seeing the same creative eight times in a week tunes it out, or worse, develops negative associations. + +Typical caps. Three to four impressions per user per week for Awareness campaigns. Six to eight per week for Direct Response. Lower for B2B (one to two per week per LinkedIn target). Platform defaults are usually too high; set explicit caps. + +Rotation as alternative. If you have enough creative variants, rotate often enough that no individual creative hits fatigue threshold. Rotation plus capping is the strongest pattern for high-spend, long-running campaigns. + +--- + +## Attribution mismatch: platform-reported vs actual + +The trap. Platform-reported conversions are inflated by view-through attribution, generous click attribution windows, and platform self-attribution bias. + +Last-click in GA vs platform-reported. Google Ads typically reports 1.3 to 1.5x the conversions GA reports. The gap comes from multi-touch attribution differences and view-through that GA does not credit. + +iOS 14.5+ impact. Meta and other platforms underreport iOS conversions because of App Tracking Transparency. Modeled conversions try to fill the gap; they are imperfect. Treat iOS-heavy reporting with extra skepticism. + +View-through attribution. Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Useful for awareness; misleading for performance optimization. + +Cross-platform interference. Meta retargeting captures users who would have converted from Google Search anyway. Both platforms claim the conversion. You pay for the same conversion twice. + +The discipline. Single source of truth in your warehouse or analytics platform. Report against that for incrementality decisions. Use platform metrics for in-flight optimization only. The deeper interpretation work belongs in `ads-performance-analytics` (forthcoming); this skill names the trap so you do not optimize against the wrong number. + +Per-platform reporting quirks in [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md). + +--- + +## Common failures + +Twelve patterns recur across paid media work. The short version. Detail in [`references/common-failures.md`](references/common-failures.md). + +- "We are scaling but CAC went up." Saturation on the primary audience. Expand the audience or diversify the channel mix. +- "Conversions look fine in the platform, terrible in revenue." Attribution mismatch plus customer quality, not just count. The platform is selecting low-LTV converters because they are easier to find. +- "We A/B tested and one wins, but only by 5%." Within margin of platform noise. Not a real signal. +- "We turned off the underperforming campaign and conversions dropped overall." View-through or assist conversions you were not counting. Test with hold-out, not flat off. +- "Frequency hit 8 last week." Refresh creative. Do not blame the audience. +- "We are trying to scale Meta to $100K per day from $20K per day." That is not scaling, that is a 5x jump. Expect efficiency drop; phase the increase. +- "We tried LinkedIn for our B2C product." Wrong channel for the offer. Not a LinkedIn problem. +- "tROAS will not deliver." You set it too aggressive. Loosen the target or switch strategy. +- "We saw a click-through bump after the Super Bowl ad." That is brand effect on existing demand, not paid attribution. Read it as a brand signal. +- "Search Impression Share dropped." Either competition increased or budget is constrained. Check both before tuning bids. +- "PMax is hard to optimize." Yes. Treat PMax as a tested channel with constrained levers, not a place to fine-tune at the keyword level. +- "Lookalike performance dropped after we expanded to 5%." Wider lookalikes are looser; the floor is lower. Tighten back to 1 to 2% if CAC is the constraint. + +--- + +## The framework: 11 considerations for sustainable paid media + +When designing or auditing paid media, walk these 11 considerations. Skipping any of them is how teams burn budget at scale. + +1. Hypothesis. Audience, offer, channel, outcome metric, magnitude. Pre-commit the falsification rule. +2. Channel fit. Intent matches offer. Search for capture, Meta and TikTok for creation, LinkedIn for B2B precision. +3. Budget shape. Brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. +4. Audience strategy. Prospecting, retargeting, exclusion. Treated as separate strategies. +5. Bid strategy. Manual, max conversions, tCPA, tROAS, max conversion value. Matched to data state. +6. Campaign type. Right type for the platform and the goal. +7. What not to spend on. Branded beyond defensive, untargeted display, wrong geos, off-hours, low-converting devices, never-convert audiences, tired creative. +8. Creative testing. Within campaign and across campaign, plus refresh cadence. +9. Frequency capping. Explicit caps and creative rotation. +10. Attribution reality. Single source of truth, platform metrics for in-flight only. +11. Decision rule. Pre-committed scale up, hold, or pull back at known thresholds. + +The output of the framework is one of three answers. Scale (the hypothesis is confirmed at the magnitude needed to justify more spend). Hold (results are at the falsification line; gather more data before committing). Kill (the hypothesis is wrong or the campaign is no longer pulling its weight). + +--- + +## Reference files + +- [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md) - Context-to-channel matrix with worked examples for the most common business contexts. +- [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md) - Typical splits and pacing patterns: growth-mode, steady-state, brand-heavy, performance-heavy. +- [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md) - Prospecting, retargeting, exclusion templates plus cross-platform reconciliation. +- [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md) - Each strategy's fit, common mistakes, and migration paths as data accumulates. +- [`references/campaign-type-reference.md`](references/campaign-type-reference.md) - Per-platform campaign type guide with pitfalls. +- [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md) - Platform reporting quirks, attribution differences, and the single-source-of-truth pattern. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, and prevention. + +--- + +## Closing: when in doubt, kill the campaign + +Most paid media decisions reduce to scale, hold, or kill. When the analysis is genuinely ambiguous, default to kill. + +The cost of a campaign that is not clearly working is real money flowing out the door every day. The cost of killing a marginal campaign is mostly just the inconvenience of restarting it later. Asymmetric risk. Default to kill. + +The follow-on rule is symmetric. When the hypothesis is clearly confirmed at the magnitude that matters, scale aggressively. The cost of slow-rolling a working campaign is opportunity cost; competitors compound on the same demand pool. Default to scale once the data justifies it. + +Marginal results are the trap. They invite more analysis, more meetings, more "let us give it another two weeks." Two weeks of marginal CAC is two weeks of lost money. Pre-commit the decision rule and execute it. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md b/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md new file mode 100644 index 0000000..3a181f8 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/ads-platform-comparison.md @@ -0,0 +1,106 @@ +# Ads platform comparison + +Per-platform reporting quirks, attribution differences, and the single-source-of-truth pattern. + +The platforms do not agree on what counts as a conversion or how long a click should attribute. Reading the platform's reported numbers as truth is the most expensive mistake in paid media. + +--- + +## Google Ads + +Default attribution model. Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on the platform's machine learning. Single touch attribution (last-click) is available but no longer the default. + +Conversion windows. Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA reports by default, which produces the typical 1.3 to 1.5x conversion overcount versus GA. + +Quirks to know. +- DDA gives partial credit to keywords that touched the path even if the user did not click. The reported conversion volume under DDA is higher than under last-click. +- Smart Bidding optimizes against the DDA-reported conversions, not GA-reported. Optimizing for one number while measuring against another produces drift. +- View-through attribution on Display and Video is opt-in; default is off. + +Reading the numbers. Compare Google Ads conversions against GA's "Google Ads" channel rather than against total GA conversions. The gap between the two is the attribution-model gap; treat with awareness. + +--- + +## Meta (Facebook + Instagram) + +Default attribution. 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +Conversion windows. 7-day click is the standard. Wider windows are more generous to Meta; narrower windows are more conservative. + +iOS 14.5+ impact. App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated based on aggregated behavior) and Conversions API (server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +Quirks to know. +- View-through attribution counts impressions even if the user did not click. Often half the reported conversions are view-through. Treat with skepticism for direct response. +- Modeled conversions are a meaningful share of iOS-reported conversions in 2025-2026. They are statistically estimated, not directly observed; do not trust them with the precision you would trust click-based conversions. +- Conversions API (CAPI) sends server-side events that complement pixel events. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. + +Reading the numbers. Disaggregate by attribution window in the Ads Manager (1-day click, 7-day click, 1-day view, 7-day view). The 1-day click number is the most conservative and the closest to incremental. + +--- + +## LinkedIn + +Default attribution. 30-day click and 7-day view-through. + +Conversion windows. Longer than B2C platforms because B2B buying cycles are longer. The 30-day click window matches the typical B2B consideration cycle for many categories. + +Quirks to know. +- LinkedIn's reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair with self-reported attribution surveys for B2B. +- Lead Gen Forms count form submissions as conversions; downstream lead qualification is on you to track. +- Demographic insights (job title, seniority, company size, industry) are unique to LinkedIn and uniquely valuable for B2B audience refinement. + +Reading the numbers. Lead Gen conversions are easy to overcount because form friction is low; some leads are accidental. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. + +--- + +## TikTok + +Default attribution. 7-day click and 1-day view-through (similar to Meta). + +Conversion windows. Adjustable. TikTok also supports a "video view" event that is unique to the platform. + +Quirks to know. +- Video-completion-based attribution: TikTok counts conversions even when the user did not click but watched the full video. This is real signal for awareness; it inflates direct-response numbers. +- iOS impact similar to Meta but less mature in the modeling. +- Spark Ads attribution is shared between paid and organic. The same view that drove a conversion shows up in both surfaces; be careful not to double-count when reconciling. + +Reading the numbers. Click-based conversions are the most reliable. Video-view-based conversions are real signal but should be reported separately. + +--- + +## Cross-platform interference + +Two platforms claiming the same conversion is the single most common attribution mistake. + +The classic case. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). GA might attribute it to organic if the brand search was not paid. Three different views of one conversion. + +The defense. A single source of truth in your warehouse or analytics platform. Multi-touch attribution at the warehouse level distributes credit fairly. Marketing-mix modeling (MMM) at the budget-allocation level cuts through the platform-self-attribution bias. + +--- + +## Single-source-of-truth pattern + +Three layers, each serving a different decision. + +Layer 1: platform metrics. Use for in-flight optimization only. Ad set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +Layer 2: warehouse multi-touch attribution. Use for cross-platform comparison. Each conversion gets attributed across all platforms that touched the path. Common patterns: last-click, first-click, linear, position-based, time-decay, data-driven. Pick one and standardize across the team. + +Layer 3: marketing-mix modeling (MMM). Use for budget allocation across channels. MMM treats spend as an input and revenue as an output, modeling the contribution of each channel net of the others. The strongest defense against platform-self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## What the numbers mean in practice + +A typical mid-stage account has the following attribution gap pattern: + +- Google Ads reports: 1.3 to 1.5x what GA reports for "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA reports for "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform-self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md b/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md new file mode 100644 index 0000000..9cedf2a --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/audience-segmentation-patterns.md @@ -0,0 +1,87 @@ +# Audience segmentation patterns + +Three audience types treated as separate strategies: prospecting, retargeting, exclusion. Plus cross-platform reconciliation patterns and the most common anti-patterns. + +--- + +## Prospecting + +New people who have not engaged with your brand. The largest budget share for growth-mode brands. + +Lookalike audiences (Meta, TikTok). Seed from a high-quality source (top 10% LTV customers, paying customers from the last 90 days, repeat purchasers) and ask the platform for similar users. 1 to 2% lookalikes are tightest and convert best at lower volumes; 5 to 10% lookalikes are looser and scale to volume but convert at lower rates. Start narrow, expand only if the floor holds. + +In-market audiences (Google). Google's behavioral signals identify users actively researching a category. Pair with category-relevant keywords for capture, or use as broad targeting on Display, Video, and PMax. + +Interest stacks (Meta). Stack multiple interest groups within an ad set. The stack approach lets the algorithm find the overlap. Single interests are usually too narrow; flat lists of 30 interests are too broad. Aim for 5 to 10 related interests. + +Custom intent or affinity (Google). Build audiences from URL lists or keyword lists. Useful for niche categories where in-market is not a clean fit. + +Account lists (LinkedIn). Upload a target account list and target by company. Pair with job-title or seniority filters to narrow further. The strongest pattern for ABM-style B2B paid. + +The prospecting principle. Start with one well-defined audience that matches your hypothesis. Prove CAC. Then expand. Running five prospecting audiences in parallel before any one is proven is the most expensive way to learn nothing. + +--- + +## Retargeting + +People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC if executed correctly. + +Window splits. Different windows have different conversion intents. Run three retargeting tiers with different creative. + +\| Window \| Audience intent \| Creative \| +\|---\|---\|---\| +\| 0 to 7 days \| Hot. Recent visitors. \| Direct conversion offer. Reinforce value prop. \| +\| 8 to 30 days \| Warm. Considered but did not convert. \| Address objections. Social proof. Comparison content. \| +\| 31 to 90 days \| Cool. Long consideration cycle or churned interest. \| Reactivate with new offers, new content, or value updates. \| + +Cart abandoner specific. If e-commerce, cart abandonment is its own retargeting tier. Window: 0 to 7 days. Creative: cart contents reminder, often with a small incentive (free shipping, 10% off). CTR and CAC are usually the strongest of any retargeting segment. + +Page-specific retargeting. Visitors to high-intent pages (pricing, demo request, product detail) are warmer than homepage visitors. Run page-specific retargeting at higher bids. + +The retargeting trap. Bidding too aggressively trains the platform to charge a premium for users who would have converted anyway. Cap retargeting CPM and CPC; the high CTR and conversion rate produce strong results without aggressive bids. + +--- + +## Exclusion + +The audiences you do not want paying for clicks from. Saves spend and keeps frequency low. + +Current customers. Users with active subscriptions, recent purchases, or active accounts. Exclude from prospecting and most retargeting. Exception: lapsed-cart-from-paying-customer retargeting, which can lift add-to-cart-to-purchase rates. + +Recent converters. Users who converted in the last 30 to 90 days. Exclude from prospecting. The platform will keep showing them ads otherwise, which produces frequency fatigue and zero new revenue. + +Failed-conversion audiences. Users who clicked repeatedly across a 60 to 90 day window without converting. Build an exclusion list from this segment. They have signaled they are not converting from paid; stop paying to show them ads. + +Employee lists. Upload employee email lists and exclude from all paid traffic. Employees clicking on company ads inflate spend and pollute attribution. + +Cross-platform exclusion. When running both Meta and Google, exclude Meta retargeting from Google retargeting (and vice versa). Two platforms hitting the same user with the same offer produces frequency fatigue and double-billing. + +--- + +## Cross-platform audience reconciliation + +When running multiple platforms, audience definitions should align so attribution comparisons are meaningful. + +The seed list problem. If Meta sees a customer file and Google sees a different customer file, the lookalike sources differ. Reconcile by uploading the same customer list to both, segmented identically (top 10% LTV, last 90 days, etc.). + +The retargeting overlap problem. A user who visited the site appears in both Meta retargeting and Google retargeting. Both platforms claim the conversion. Reconcile by running one retargeting platform at a time, or by setting platform-specific retargeting budgets that match the actual incremental contribution. + +The exclusion problem. A user who converts on Meta should be excluded from Google paid prospecting (and vice versa). Without cross-platform exclusion, you pay to advertise the same offer to the same user twice. Pipe conversions to a unified audience layer (CDP, warehouse, or audience-sync tool like Synter or Hightouch) and push exclusions back to each platform. + +--- + +## Anti-patterns + +Common mistakes that recur across accounts. + +Prospecting too narrow. Audience size below the platform's optimization minimum (Meta: roughly 1M users; Google: roughly 100K). The platform cannot optimize against signal that thin. Expand the audience until it has at least 1 to 5 million reachable users (Meta) or in-market scale (Google). + +Retargeting too aggressive. Bidding above the value of the incremental conversion. Half the retargeting "conversions" would have happened anyway from organic; if you bid for them at full attribution, you overpay. + +No exclusions. The most common audit finding. Current customers, recent converters, and employees all clicking on paid ads. + +Lookalike from the wrong source. Building a 5% lookalike from "all customers" (including low-LTV churners). The platform returns users similar to the average, not similar to your best. Always seed from top-LTV or paid-and-retained customers. + +Too many ad sets per campaign. Splitting one campaign into 10 ad sets fractures the data the platform needs to optimize. Consolidate into 2 to 4 ad sets per campaign with audience size sufficient for each to learn. + +Audience overlap across ad sets. Two ad sets in the same campaign targeting similar users compete with each other and inflate CPC. Audit overlap with the platform's overlap tool; consolidate ad sets that overlap above 30%. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md b/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md new file mode 100644 index 0000000..f2a4630 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/bid-strategy-reference.md @@ -0,0 +1,104 @@ +# Bid strategy reference + +Each major bid strategy with definition, fit criteria, common mistakes, and the migration path as data accumulates. + +The decision shape. Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. Pick the strategy that fits the current data state, run it long enough to gather signal, then promote. + +--- + +## Manual CPC or CPM + +Definition. Set a max cost per click or cost per thousand impressions. The platform charges no more than the cap. + +When to use. Diagnostics. Very early campaigns with no data history. Niche audiences where the platform's machine learning would over-broaden. Branded keyword campaigns where you want explicit cost control. + +When not to use. Most production campaigns at scale. Manual scales slowly because every adjustment requires a human decision; automated strategies optimize across thousands of micro-decisions per hour. + +Common mistakes. Setting CPC caps below the auction floor (the campaign delivers nothing). Switching from manual to automated too early before there is enough data for the automated strategy to optimize against. + +--- + +## Maximize Conversions + +Definition. Platform optimizes for conversion volume within the budget. The platform decides CPC. + +When to use. Early-stage campaigns where you want as many conversions as possible regardless of unit cost. Good for gathering the conversion data needed to graduate to tCPA later. Good for awareness or list-building campaigns where volume matters more than per-unit cost. + +When not to use. Once CAC is the binding constraint. Maximize Conversions does not respect CAC; it just optimizes for count. + +Common mistakes. Running Maximize Conversions for too long when CAC is creeping up. Set a cadence to evaluate the migration to tCPA once you have 30+ conversions in the recent window. + +--- + +## Target CPA (tCPA) + +Definition. Set a max CPA. Platform delivers conversions within the target. + +When to use. Once you have 30+ conversions in the recent 30 day window for the platform to optimize against. Use when CPA is the constraint and you have enough data for the platform's machine learning to converge. + +When not to use. Before you have enough conversion data. The platform cannot optimize tCPA without enough signal; it will either underdeliver or learn against noise. + +Common mistakes. Setting tCPA below the prior 30-day actual CPA (platform throttles delivery to almost zero). Setting tCPA too aggressive in a thin-data campaign (same effect; throttled delivery and no learning). Switching tCPA targets every week (each change resets the learning phase). Set the target reasonably (within 15% of recent actual) and let it run. + +--- + +## Target ROAS (tROAS) + +Definition. Set a min ROAS. Platform delivers conversions above the target. + +When to use. When revenue per conversion varies substantially (e-commerce with mixed AOV, marketplaces with mixed take rates). Once you have 50+ conversions and conversion-value tracking is wired in. + +When not to use. Before conversion-value tracking is reliable. Without conversion values, tROAS has nothing to optimize against and falls back to behavior similar to Maximize Conversions but with throttled delivery. + +Common mistakes. Setting tROAS too aggressively (platform delivers almost nothing). Not feeding accurate conversion values (the platform optimizes for the wrong number). Switching tROAS targets too often. + +--- + +## Maximum Conversion Value + +Definition. Like Maximize Conversions, but the platform optimizes for total conversion value rather than count. + +When to use. Same conditions as tROAS, but without a fixed target. Good when you want to maximize revenue within budget without specifying the per-unit ROAS floor. + +When not to use. Without conversion-value tracking. Without volume confidence; same as tROAS, the platform needs enough conversions to optimize against value. + +Common mistakes. Running without conversion values configured (the platform falls back to count). Treating it identically to Maximize Conversions; the value optimization changes which conversions the platform finds. + +--- + +## Enhanced CPC + +Definition. Manual CPC with platform adjustments based on conversion likelihood. + +When to use. Rarely. The hybrid muddies the signal. If you want manual control, run pure manual CPC. If you want automation, graduate to Maximize Conversions or tCPA. + +When not to use. Most situations. The hybrid is a transitional state from a previous platform default; modern campaigns should pick a clear strategy. + +Common mistakes. Treating Enhanced CPC as the safe default. It is neither full control nor full automation; the worst of both. + +--- + +## The migration path + +The progression for a new campaign as data accumulates. + +\| Data state \| Strategy \| Rationale \| +\|---\|---\|---\| +\| Day 1 to ~30 conversions \| Manual CPC or Maximize Conversions \| Gather data. Platform machine learning has nothing to optimize against yet. \| +\| 30 to 100 conversions \| Target CPA \| Platform has enough signal to optimize against a CPA target. Set within 15% of recent actual. \| +\| 100+ conversions, value tracking on \| Target ROAS or Max Conversion Value \| Optimize for revenue or ROAS rather than count. \| +\| Mature campaign at scale \| Whichever produces best CAC + ROAS \| Stay there. Switching strategies on a mature campaign restarts the learning phase. \| + +The migration cadence. Evaluate the migration after every 30 days or every 50% conversion volume increase, whichever comes first. Do not switch every week; the learning phase reset cost is real. + +--- + +## When to NOT switch strategy + +Three signals that suggest staying on the current strategy even when something else looks better. + +1. Recent change. If you switched strategy in the last 14 days, give it more time. The learning phase needs at least 2 weeks of consistent volume to converge. +2. Volatile conversion volume. If conversion volume is bouncing 50%+ week-over-week, the platform's optimization signal is noisy. Stabilize volume before switching. +3. Active creative test. If you are mid-test on creative or audience, do not also change bid strategy. One variable at a time. The bid strategy change muddies the creative test signal. + +The rule. Switch strategy when one variable is stable and the data state has clearly progressed. Avoid stacking changes; you cannot tell which change drove the result. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md b/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md new file mode 100644 index 0000000..9ff0017 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/budget-allocation-templates.md @@ -0,0 +1,107 @@ +# Budget allocation templates + +Four split patterns plus pacing guidance. Pick the template closest to your situation and adapt. + +The splits operate at the same time: brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. + +--- + +## Template 1: Growth-mode allocation + +For brands actively scaling with a working unit economic model. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Prospecting \| 70% \| New audience reach. Largest share because growth comes from new demand. \| +\| Retargeting \| 20% \| Engaged-but-not-converted users. Small audience, high CTR, low CAC. \| +\| Test \| 10% \| Systematic tests of new audiences, channels, or creative concepts. \| + +Plus brand-vs-performance: 25% brand, 75% performance for B2C. 50-50 for B2B with longer cycles. + +Plus channel: 60-70% to one primary channel that has proven its CAC, 25% to a secondary, 5-15% to scale-out experiments. + +--- + +## Template 2: Steady-state allocation + +For brands holding scale rather than aggressively pushing it. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Prospecting \| 50% \| Lower share because steady-state needs less new demand. \| +\| Retargeting \| 30% \| Higher share because the existing pipeline is the main flow. \| +\| Test \| 20% \| Higher share than growth-mode; steady-state is when systematic testing pays off. \| + +Plus brand-vs-performance: 40% brand, 60% performance. The brand share is higher than growth-mode because steady-state is about defending position. + +--- + +## Template 3: Brand-heavy allocation + +For categories where brand investment compounds (premium consumer, B2B with long consideration, regulated industries). + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Brand \| 60% \| Awareness, reach, video at scale. Long-term demand pipeline. \| +\| Performance \| 40% \| Search and retargeting on the demand the brand creates. \| + +Within performance, 60% prospecting and 40% retargeting is typical. Test budget comes out of the brand share. + +--- + +## Template 4: Performance-heavy allocation + +For DTC and direct-response B2C where the unit economics are tight and brand effects are slow to compound. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Brand \| 20% \| Minimum viable awareness investment. Mostly content and organic. \| +\| Performance \| 80% \| Direct-response paid; CAC is the binding metric. \| + +Within performance, growth-mode splits apply: 70% prospecting, 20% retargeting, 10% test. + +--- + +## Pacing patterns + +Budgets that run flat through the month miss the demand peaks and overspend during the troughs. Three pacing patterns to layer onto the daily template. + +Front-load testing weeks. When launching a new creative concept or a new audience, front-load 60% of the test budget in the first 7 to 10 days. The platform learning phase needs concentrated signal; spreading too thin means slower convergence. + +Back-load seasonality. For categories with a seasonal peak (holiday, end-of-quarter, category-specific moments), shift 30 to 50% of monthly budget into the peak two-week window. Flat budgets through Q4 leave money on the table. + +Front-load for launch. For new campaigns with no historical data, front-load creative testing in week one. Accept lower efficiency in week one in exchange for picking the winning creative quickly. By week three the winning concept should be running at scale. + +Steady for evergreen. For mature campaigns hitting consistent CAC at scale, run flat daily. The platform's learning is stable; introducing pacing variance creates noise that reduces optimization quality. + +--- + +## Daily vs lifetime budgets + +Daily budget. Use for ongoing campaigns where you want a stable spend floor. The platform charges up to your daily cap regardless of opportunity, which is what you want for predictable production work. + +Lifetime budget. Use for finite tests where the platform should pace itself across a defined window. Lifetime budgets prevent runaway spend during testing; the platform optimizes pacing so the test ends on the planned date with the planned spend. + +Mistakes. Using daily for tests (the test runs forever or stops abruptly when budget is paused). Using lifetime for evergreen campaigns (the platform front-loads or back-loads in ways you do not want). + +--- + +## Channel split mistakes + +The most common channel-budget mistake is the equal split. Spreading $100K across four channels at $25K each produces four underperforming campaigns; one campaign at $80K plus three at $7K each produces one strong learning signal and three quick reads on whether the others are worth scaling. + +The principle. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the temptation to be balanced. Balanced budgets across unproven channels is the most expensive way to learn nothing. + +The exception. After two channels are proven independently, splitting toward equal is fine because each channel has its own efficient scale. Before that point, concentrate. + +--- + +## Reallocation triggers + +Three signals that the current split needs to shift. + +1. Primary channel CAC drifted up by 25% over two weeks. The audience is saturating or competition increased. Shift some budget to the secondary channel and drop the primary's daily. +2. Test budget produced a new winner. A test channel or audience is hitting CAC equal to or better than baseline. Promote it to baseline at 15% of total budget; the previous baseline holds 55 to 60%. +3. Frequency exceeded threshold across the prospecting audience. The audience saw the creative more than the cap. Either rotate creative or expand the audience; if both are constrained, pull back budget. + +Reallocation cadence: monthly review minimum. Weekly during high-spend periods or active scale-up. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md b/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md new file mode 100644 index 0000000..2d3e007 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/campaign-type-reference.md @@ -0,0 +1,197 @@ +# Campaign type reference + +Per-platform campaign type guide. For each campaign type: what it is, when it fits, common pitfalls. + +--- + +## Google Ads + +### Search + +What it is. Text ads on Google search results pages, triggered by keyword auctions. + +When to use. Direct demand capture. Users searching for category, product, or competitor terms. + +Pitfalls. Branded over-spend (cannibalizing free traffic). Broad match on weak keywords (drives garbage clicks). Missing negative keyword lists (paying for irrelevant search terms). Audit search-term reports monthly and add negatives. + +### Shopping + +What it is. Product listing ads driven by your Google Merchant Center feed. + +When to use. E-commerce with a structured catalog. Comparison-shopping intent. + +Pitfalls. Bad feed quality (missing GTINs, weak titles, wrong categories). The feed is the bottleneck; clean it before scaling spend. + +### Performance Max (PMax) + +What it is. Automated multi-channel campaign that runs across Search, Shopping, Display, YouTube, Discover, and Gmail. The platform decides placement. + +When to use. E-commerce with a strong feed. When you want Google's automation to do the placement work. As a complement to Search, not a replacement. + +Pitfalls. Black box optimization makes manual tuning hard. Cannibalizes branded Search traffic; exclude branded queries via account-level negatives. Asset group quality drives results; weak creative produces weak results regardless of platform automation. + +### Display + +What it is. Banner and image ads on the Google Display Network (millions of partner sites). + +When to use. Retargeting (small audiences, defined intent). Specific contextual targeting where you trust the placement list. + +Pitfalls. Display without targeting drives garbage traffic. Default placements include low-quality sites that hurt brand. Use only for retargeting unless you have explicit placement controls. + +### Video (YouTube) + +What it is. Video ads on YouTube. Various formats (skippable, non-skippable, bumper, in-feed). + +When to use. Awareness at scale. B2C consideration. Underrated for B2B SaaS in some categories where buyer research includes long-form video. + +Pitfalls. Direct-response on Video rarely works as well as Meta video. Use for awareness or as an upper-funnel layer. Skippable ads with strong first-5-seconds work; non-skippable annoys. + +### Demand Gen + +What it is. Successor to Discovery ads. Visual ads across Discover, Gmail, YouTube Shorts, and YouTube in-feed. + +When to use. Visual-first products targeting users in discovery mode (not search mode). + +Pitfalls. Newer campaign type with less optimization history; results are more volatile than Search or Shopping. Treat as a tested channel. + +### Discovery + +What it is. Visual ads across Google's discovery surfaces. Being merged with Demand Gen. + +When to use. Largely deprecated in favor of Demand Gen. Migrate existing Discovery campaigns. + +### App + +What it is. Universal App Campaigns for app installs and engagement. + +When to use. App promotion. Mostly automated; you provide creative and budget. + +Pitfalls. Hard to optimize beyond budget and creative inputs. Track post-install events (subscription, retention) not just installs. + +--- + +## Meta (Facebook + Instagram) + +### Sales + +What it is. Campaigns optimized for conversions. The default for direct response. + +When to use. E-commerce, subscriptions, lead capture with measurable conversion events. + +Pitfalls. Wrong conversion event optimization (optimizing for "Add to Cart" when "Purchase" is what matters). Inadequate pixel setup (the conversion data feeding the algorithm is incomplete). + +### Leads + +What it is. Campaigns with native lead forms inside Facebook or Instagram. + +When to use. B2B with mid-funnel offers (whitepaper, demo request, newsletter signup). Native forms have lower friction than off-platform forms. + +Pitfalls. Lead quality is lower than off-platform forms (less friction, more accidental submissions). Build a CRM enrichment step to filter low-quality leads before passing to sales. + +### Engagement + +What it is. Optimizes for likes, comments, shares, page follows. + +When to use. Building an organic audience. Almost never as a primary objective for performance work. + +Pitfalls. Engagement does not predict conversion. Vanity metrics if used as a primary objective for revenue work. + +### Awareness + +What it is. Optimizes for reach and frequency. Brand-style budget. + +When to use. Brand at scale. New product launches. Competitor-conquest moments. + +Pitfalls. No conversion signal feeding the algorithm. Cannot evaluate against CAC. Use as a brand layer, not a performance layer. + +### Traffic + +What it is. Optimizes for clicks (link clicks or landing page views). + +When to use. Driving traffic to long-form content, blog posts, awareness pages where the user journey is multi-touch. + +Pitfalls. Click-optimized traffic does not predict conversion. The platform finds users likely to click, not users likely to convert. Only use for top-funnel content distribution. + +### App Promotion + +What it is. App install campaigns within Meta. + +When to use. App promotion specifically. Compare against Google App Campaigns. + +Pitfalls. iOS 14.5+ tracking restrictions impact attribution; modeled conversions fill the gap imperfectly. + +--- + +## LinkedIn + +### Sponsored Content + +What it is. Sponsored posts in the LinkedIn feed. + +When to use. B2B awareness and consideration. Native to the LinkedIn experience. + +Pitfalls. High floor (CPM 5 to 10x consumer platforms). Justify with B2B LTV; otherwise unprofitable. + +### Message Ads + +What it is. Direct messages delivered via LinkedIn InMail. + +When to use. High-intent B2B nudges where the message reads as a personal note. + +Pitfalls. Stigma in many segments. Treated as spam if the message reads generic. Personalize aggressively or skip. + +### Conversation Ads + +What it is. Multi-step interactive messages with branching CTAs. + +When to use. Mid-funnel B2B where multiple value propositions need to be tested in one experience. + +Pitfalls. Setup complexity. Many teams underuse the branching capability and run them as glorified Message Ads. + +### Lead Gen Forms + +What it is. Native lead forms pre-filled from LinkedIn profile data. + +When to use. Highest converting LinkedIn objective. Use whenever the offer is a lead capture (demo, whitepaper, content offer). + +Pitfalls. Lead quality varies by form length. Shorter forms get more leads; longer forms filter to higher quality. Iterate. + +### Format types + +Single image, carousel, video. Carousel often outperforms single image for product or feature explainers. Video performs best when shot LinkedIn-native with first-3-seconds hook and captions on by default. + +--- + +## TikTok + +### In-Feed + +What it is. Standard ads in the For You Page feed. + +When to use. Default TikTok format. Most direct-response and awareness work runs here. + +Pitfalls. Polished ad creative is rejected by the algorithm; native-feeling content wins. Iterate creative weekly to avoid fatigue. + +### TopView + +What it is. Premium first-impression placement when users open the app. + +When to use. Brand moments at scale. Product launches. + +Pitfalls. Expensive. Only justify with measurable brand lift or product launch impact. + +### Spark Ads + +What it is. Boost an existing organic post as an ad. Retains organic engagement and signal. + +When to use. Whenever you have organic posts performing. Spark Ads outperform pure paid creative because they retain the organic-feel signal. + +Pitfalls. Requires organic content to exist. If the brand has no organic presence, build one first. + +### Branded Hashtag Challenge + +What it is. Sponsored hashtag with branded content prompts. + +When to use. Major brand campaigns where user-generated participation matters. + +Pitfalls. Expensive. Hard to measure direct response. Best for brands with cultural-moment ambitions, not direct response. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md b/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md new file mode 100644 index 0000000..bf8ec6d --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/channel-decision-matrix.md @@ -0,0 +1,56 @@ +# Channel decision matrix + +A context-to-channel map. The left column is the situation. The center columns are the recommended channels. The right column is reasoning and what NOT to start with. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. Use the remaining rows as cross-checks. + +--- + +## The matrix + +\| Situation \| Primary channel \| Secondary channel \| Reasoning and what to avoid early \| +\|---\|---\|---\|---\| +\| Pre-PMF B2B SaaS \| LinkedIn (precision) or Google Search (intent) \| Content + organic; defer paid scale \| Avoid Meta and TikTok early; the audience is not on those platforms. Avoid PMax; you do not have the data state for it. \| +\| High-AOV B2B (>$5K LTV) \| LinkedIn Sponsored Content + Lead Gen Forms \| Google Search on category and intent terms \| LinkedIn floor is high but justified at this LTV. Avoid TikTok, Reddit, and broad Meta until the LinkedIn motion is repeating. \| +\| Low-AOV consumer product (<$50 LTV) \| Meta (Sales objective) \| TikTok (Spark Ads if organic exists) \| Avoid LinkedIn (floor too high). Avoid Search unless category-defining query volume exists. Watch payback period; low LTV with paid CAC is razor-thin. \| +\| DTC with strong visual brand \| Meta (Sales + Reels) \| TikTok In-Feed and Spark Ads \| Avoid LinkedIn. Avoid Display network. Visual-first creative is the moat; double down on the platforms that surface it. \| +\| Local services \| Google Search + Local Service Ads \| Meta with geo radius targeting \| Avoid TikTok and LinkedIn (wrong intent). Pause off-hours. Geo-radius is the most important targeting lever. \| +\| Enterprise SaaS (>$50K ACV) \| LinkedIn (job-title precision) \| Account-Based Marketing platforms + Google Search on category terms \| Avoid Meta and TikTok. Avoid broad Display. Pair with ABM on a target account list; audiences are too small for Meta lookalikes to work. \| +\| E-commerce with catalog \| Google Performance Max + Shopping \| Meta (Catalog Sales) \| Avoid Search-only spend; PMax includes Search and adds catalog placements. Avoid LinkedIn. Feed quality is the bottleneck; fix the feed before spending on PMax. \| +\| Subscription consumer \| Meta (Sales objective with subscriber LTV) \| Google Search on intent + brand terms \| Avoid LinkedIn. Watch retention; CAC paid back over multiple months means the unit economics window matters more than first-month CAC. \| +\| Marketplace (two-sided) \| Channel-by-side: Meta for consumer side, LinkedIn or Search for supplier side \| Reddit niche communities for the supplier side \| Run two separate strategies, not one unified plan. The two sides have different intent and need different channels. \| +\| Pre-launch waitlist \| Meta (Engagement or Lead) \| Reddit and TikTok organic + light paid \| Avoid Search; no one is searching for an unlaunched product. Avoid LinkedIn unless B2B. Cheap CPL but low intent; expect waitlist conversion under 20%. \| + +--- + +## Worked examples + +### Example 1: Series B B2B SaaS, $25K ACV, North American sales motion + +The team has a working sales motion and is scaling outbound. They want paid media to add inbound demand without killing CAC. + +Recommendation. LinkedIn Sponsored Content as the primary, plus Google Search on category and competitor terms as secondary. Run Lead Gen Forms within LinkedIn to capture demos. Avoid Meta and TikTok early; the buying committee is on LinkedIn and at the office. Budget split: 60% LinkedIn, 30% Search, 10% test (Reddit B2B subreddits, niche newsletters). Watch CAC against the $25K ACV and a 3:1 LTV-to-CAC target. + +### Example 2: DTC adaptogenic soda, $24 AOV, US-only + +The brand has strong visual identity and an organic TikTok presence with one viral post per month. They want to scale paid. + +Recommendation. Meta (Sales objective with Catalog) as the primary. TikTok Spark Ads on the existing organic posts as the secondary. Avoid LinkedIn entirely. Avoid Search unless brand search volume justifies defensive spend. Budget split: 60% Meta, 30% TikTok, 10% test (Pinterest for visual discovery). The viral organic posts are the asset; Spark Ads recycle them at scale. Watch payback period; $24 AOV with paid CAC is razor-thin. + +### Example 3: Local home services, three-state operating area + +The team operates plumbing services across three states. They want predictable lead flow. + +Recommendation. Google Search plus Local Service Ads as the primary. Meta with geo radius as the secondary for awareness in the operating area. Avoid LinkedIn and TikTok (wrong intent). Pause off-hours unless 24-hour service is a positioning angle. Budget split: 70% Search and LSAs, 20% Meta geo, 10% test (Nextdoor where available). The geo-radius lever is the most important; a 2% mistargeting rate compounds at scale. + +### Example 4: E-commerce, 2,000 SKU catalog, $80 AOV + +The brand has a working e-commerce operation and wants to scale paid media efficiently. + +Recommendation. Google Performance Max as the primary (it includes Search, Shopping, Display, YouTube, Discover all in one). Meta Catalog Sales as the secondary. Avoid LinkedIn. Avoid Search-only campaigns; PMax already includes Search. Feed quality is the bottleneck; clean the feed (titles, categories, attributes, GTINs) before spending on PMax. Budget split: 70% PMax, 25% Meta, 5% test. Audit the geo and device cuts inside PMax weekly until the algorithm stabilizes. + +### Example 5: Pre-PMF B2B SaaS, $300K ARR, founders selling + +The team is pre-PMF. The founders are still doing all sales. They want to test paid media without burning runway. + +Recommendation. Defer paid scale. Use small Search budget ($2K to $5K per month) on category terms to capture in-market intent. Use LinkedIn organic plus founder-led content as the primary growth motion until PMF is clearer. The signal you would get from paid spend at this stage is too noisy to act on; the budget is better spent on content and outbound. Revisit paid in 6 months if PMF signals firm up. diff --git a/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md b/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md new file mode 100644 index 0000000..c60f2a8 --- /dev/null +++ b/dist/pi/.agents/skills/paid-media-strategy/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across paid media accounts. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Scaling but CAC went up + +Symptom. You doubled budget on the primary audience. Conversion volume rose less than 2x. CAC drifted up by 20 to 40%. + +Root cause. Audience saturation on the primary segment. The platform finds the easiest converters first; pushing more spend into the same audience produces diminishing returns at higher cost. + +Fix. Either expand the audience (broader lookalike, additional interests, geo expansion) or diversify across channels. Do not keep pushing the same audience harder; the marginal CAC will keep climbing. + +Prevention. Project the saturation curve before scaling. If a 1.5x spend increase doubled CAC over the prior 90 days, expect another 1.5x to push CAC past your threshold. Plan the diversification before the saturation. + +--- + +## 2. Conversions look fine in the platform, terrible in revenue + +Symptom. Platform reports stable conversion volume and CAC. Revenue per conversion or LTV is dropping. + +Root cause. Attribution mismatch plus customer-quality drift. The platform optimizes for finding "any conversion." The optimizer drifts toward lower-quality converters because they are easier to find. + +Fix. Switch from conversion-count optimization to conversion-value optimization (Maximum Conversion Value or tROAS). Feed accurate conversion values into the platform. Tighten audiences toward higher-LTV proxies. + +Prevention. Track LTV cohorts per channel monthly. If channel-LTV diverges from blended LTV by more than 15%, investigate the cohort quality before defending the channel. + +--- + +## 3. A/B test winner by 5% + +Symptom. Two variations tested. One wins by 5%. The team wants to ship the winner. + +Root cause. 5% is within typical platform noise. Across-campaign tests have higher variance than statistical lift implies. + +Fix. Re-run the test with more volume. Or run it longer. Or accept that the difference is not meaningful and pick the one that is easier to maintain (cheaper to produce, easier to refresh). + +Prevention. Set the minimum detectable effect (MDE) before testing. If the test cannot detect anything below 10%, do not act on a 5% difference. + +--- + +## 4. Turned off underperformer, total conversions dropped + +Symptom. A campaign was reading as underperforming. Pause it. Total account conversions drop more than the campaign's reported conversions would suggest. + +Root cause. View-through or assist conversions you were not counting in the campaign's CAC. The campaign was contributing upper-funnel exposure that drove conversions on other campaigns. + +Fix. Restart the campaign with a held-out portion of the audience to measure incrementality. Compare the held-out cohort against the exposed cohort over 30 days. + +Prevention. Run hold-out tests, not flat off-ons. The flat-off causes a discontinuity that is hard to attribute back to the right campaign. + +--- + +## 5. Frequency hit 8 last week + +Symptom. Frequency report shows 8 impressions per user last week. CTR is dropping. + +Root cause. Creative fatigue. Audience has seen the creative too many times. + +Fix. Refresh creative. Rotate in 3 to 5 new variations. Cap frequency explicitly at 4 to 6 per week. + +Prevention. Set explicit frequency caps at campaign launch. Track frequency weekly. Refresh creative on a 30 to 60 day cadence at scale, weekly for high-frequency campaigns. + +--- + +## 6. Trying to scale Meta from $20K to $100K per day + +Symptom. Aggressive scale plan. Budget multiplier is 5x in one move. + +Root cause. That is not scaling. That is a 5x jump that will crash through the audience at the new spend level. Expect efficiency drop of 30 to 50% in the first 14 days. + +Fix. Phase the increase. 25% per week is a typical safe pace. Larger jumps should pair with audience expansion or new channels to absorb the spend. + +Prevention. Plan the scale curve before starting. 5x in a month is fine if it is 4 weekly 1.4x increases. 5x in a single move is not fine. + +--- + +## 7. LinkedIn for a B2C product + +Symptom. Tested LinkedIn for a $40 AOV consumer product. CAC came in at $200. + +Root cause. Wrong channel for the offer. LinkedIn's floor is set for B2B economics; B2C does not justify it. + +Fix. Stop. Move budget to Meta, TikTok, or Search. + +Prevention. Match channel to offer at the strategy stage. Use the channel decision matrix. Do not try platforms because "we should be on LinkedIn"; be on LinkedIn only when the math supports it. + +--- + +## 8. tROAS will not deliver + +Symptom. Set tROAS at 4.0. Platform delivers almost no impressions. + +Root cause. tROAS target is too aggressive relative to recent performance. The platform throttles delivery to almost zero rather than deliver below the floor. + +Fix. Loosen the target to 110 to 115% of the prior 30-day actual ROAS. Let the platform learn at the new target, then incrementally tighten. + +Prevention. Set tROAS based on actual recent performance, not aspirational targets. Aspirational targets shut off delivery; pragmatic targets keep volume flowing while improving efficiency. + +--- + +## 9. Search Impression Share dropped + +Symptom. Search Impression Share fell from 70% to 50% over two weeks. Conversions held but you are missing volume. + +Root cause. Either competition increased (someone else is bidding more aggressively) or budget is constrained (you ran out of daily budget at peak hours). + +Fix. Check both. Compare auction-insight reports for new entrants. Check the time-of-day spend distribution; if budget runs out at noon, raise the daily cap. + +Prevention. Track Impression Share weekly. Set alerts on 10%+ week-over-week drops. The signal is leading; conversion drops typically follow within 2 to 3 weeks. + +--- + +## 10. PMax is hard to optimize + +Symptom. Performance Max is running. CAC is fine. You want to push it harder but cannot find levers. + +Root cause. PMax is by design a black box. The platform manages placements, audiences, and creative weighting. The levers you have are budget, asset groups, and exclusions. + +Fix. Treat PMax as a tested channel with constrained levers. Optimize via asset group quality (better creative, more variants), audience signals (Customer Match, in-market lists), and exclusions (branded queries, low-value SKUs). + +Prevention. Set expectations at launch. PMax is not a place to fine-tune at the keyword level. It is a place to feed strong inputs and let the platform optimize. + +--- + +## 11. Lookalike performance dropped after expansion + +Symptom. Expanded the lookalike from 1% to 5% to add volume. CAC drifted up. + +Root cause. Wider lookalikes are looser; the floor is lower. The expansion brought in users less similar to the seed. + +Fix. Tighten back to 1 to 2% if CAC is the constraint. Or split into two ad sets: the 1% as the workhorse and the 1 to 5% as a separate scale-out audience with its own budget. + +Prevention. When you need volume, expand horizontally (add a new audience type) rather than vertically (loosen the existing audience). The horizontal expansion preserves the working audience's CAC. + +--- + +## 12. Brand search lift after a Super Bowl-style ad + +Symptom. Brand search volume jumped after a brand campaign ran. Paid attribution did not credit it. + +Root cause. Brand effect on existing demand, surfaced in organic and branded paid search rather than the brand campaign's direct-attribution column. The platform's direct response metrics did not capture it. + +Fix. Track brand-search lift as a separate metric. Define a baseline brand-search rate before the campaign. Measure the lift during and after. + +Prevention. Plan brand campaigns with brand-search lift as a primary KPI, not direct response. Direct response measurement underrates brand campaigns; using it as the only success metric kills brand investment unfairly. + +--- + +## The pattern across all twelve + +Most paid media failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale CAC at the cost of LTV. Pause an underperformer at the cost of total volume. Expand the audience at the cost of the floor. Optimize one platform without checking incrementality. + +The fix at the meta level. Decide on the success metric (CAC, ROAS, LTV-adjusted) and the guardrails (volume, frequency, creative quality, customer-cohort quality) before scaling. Audit guardrails monthly. Pull back the moment a guardrail breaks, even if the success metric still looks fine. diff --git a/dist/pi/.agents/skills/performance-optimization/SKILL.md b/dist/pi/.agents/skills/performance-optimization/SKILL.md new file mode 100644 index 0000000..1bac7fb --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/SKILL.md @@ -0,0 +1,274 @@ +--- +name: performance-optimization +description: "Diagnose and fix web performance issues including Core Web Vitals (LCP, INP, CLS), bundle size, asset optimization, render performance, and runtime efficiency. Use this skill whenever the user wants to improve page speed, fix Core Web Vitals, optimize assets, reduce bundle size, debug slow renders, or systematically improve a site's performance. Triggers on performance, page speed, Core Web Vitals, LCP, INP, CLS, FID, TTFB, bundle size, code splitting, image optimization, lazy loading, render blocking, slow page, performance audit, Lighthouse score. Also triggers when traffic or conversion is dropping due to perceived slowness." +category: development +catalog_summary: "Core Web Vitals, asset optimization, render performance" +display_order: 4 +--- + +# Performance Optimization + +Diagnose web performance issues and produce a remediation plan. Stack-agnostic. Anchored to Core Web Vitals and standard browser performance patterns. + +This skill goes deeper than the performance checks in `qa-testing` and `seo-technical`. Use this when performance itself is the goal. + +--- + +## When to use + +- Fixing Core Web Vitals (LCP, INP, CLS) +- Diagnosing slow page loads +- Reducing JavaScript bundle size +- Optimizing images, fonts, and other assets +- Fixing layout shift, render-blocking resources, jank +- Pre-launch performance verification +- Annual performance health check + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Technical SEO including indexing and crawling (use `seo-technical`) +- Code review for general bugs (use `code-review-web`) + +--- + +## Required inputs + +- The site or page under audit +- Specific performance complaints if any +- Target metrics (Core Web Vitals thresholds, Lighthouse score, custom) +- Browser dev tools access +- Performance monitoring data if available (Real User Monitoring, lab data) + +--- + +## The framework: Core Web Vitals + +Three metrics carry most of the weight for both user experience and SEO: + +### LCP (Largest Contentful Paint) + +What it measures: Time until the largest visible content element finishes rendering. + +Targets: +- Good: under 2.5 seconds +- Needs improvement: 2.5 to 4.0 seconds +- Poor: over 4.0 seconds + +Common causes of poor LCP: +- Slow server response time (TTFB over 800ms) +- Render-blocking JavaScript or CSS +- Large unoptimized images for the LCP element +- Late-loading fonts that delay text render +- Client-side rendering of the LCP element + +Common fixes: +- Server-render the LCP element (no client-side render) +- Optimize the LCP image (right format, right size, preloaded) +- Reduce render-blocking resources (defer non-critical CSS and JS) +- Use modern image formats (WebP, AVIF) +- Specify image dimensions to skip layout pass + +### INP (Interaction to Next Paint) + +What it measures: Responsiveness to user interactions. Replaces FID as the standard interactivity metric. + +Targets: +- Good: under 200ms +- Needs improvement: 200 to 500ms +- Poor: over 500ms + +Common causes of poor INP: +- Long-running JavaScript blocking the main thread +- Heavy event handlers +- Excessive React/framework re-renders +- Synchronous operations in event handlers +- Large DOM with expensive layouts + +Common fixes: +- Break long tasks into chunks (`scheduler.yield()` or `setTimeout`) +- Memoize expensive computations +- Debounce or throttle high-frequency event handlers (scroll, mousemove, input) +- Avoid synchronous storage or DOM operations in handlers +- Reduce DOM size (under 1500 elements ideal) +- Use CSS over JS for animations where possible + +### CLS (Cumulative Layout Shift) + +What it measures: How much the page jumps around as it loads. Unexpected layout shifts hurt usability. + +Targets: +- Good: under 0.1 +- Needs improvement: 0.1 to 0.25 +- Poor: over 0.25 + +Common causes of poor CLS: +- Images without explicit dimensions +- Ads, embeds, iframes that load late +- Dynamically injected content above existing content +- Web fonts causing FOIT/FOUT (flash of invisible/unstyled text) +- CSS that depends on JS-loaded data + +Common fixes: +- Always specify `width` and `height` (or `aspect-ratio`) on images and videos +- Reserve space for ads and embeds before they load +- Use `font-display: optional` or `font-display: swap` thoughtfully +- Avoid injecting content above the fold after initial render +- Preload critical fonts + +--- + +## Beyond Core Web Vitals + +### Time to First Byte (TTFB) + +The server response time. Bad TTFB makes everything else worse. + +Targets: under 800ms ideal. + +Common causes: +- Slow database queries on the request path +- N+1 query patterns +- Missing caching +- Server geographic distance from users (no CDN) +- Cold starts on serverless + +Fixes: +- Cache database queries +- Use a CDN for static and cacheable dynamic content +- Optimize critical-path queries +- Pre-render where possible (SSG, ISR) +- Edge functions for low-latency dynamic content + +### Bundle size + +JavaScript shipped to the browser. + +Targets: +- Initial JS under 170KB compressed for typical pages +- Lazy-loaded chunks under 100KB compressed each + +Common causes of bloat: +- Importing entire libraries when only one function is used +- Bundling polyfills for modern browsers +- Including dev-only code in production +- Duplicate dependencies (multiple versions of the same library) +- Large client-side state (Redux store snapshots, etc.) + +Fixes: +- Tree-shake imports (`import { fn } from 'lib'` not `import lib from 'lib'`) +- Code-split per route +- Lazy-load below-the-fold components +- Audit dependencies; replace heavy ones (e.g., moment.js → date-fns or native Intl) +- Build-time bundle analyzer to spot bloat +- Dynamic imports for rarely-used features + +### Image optimization + +Images are typically 60 to 80 percent of page weight. + +Best practices: +- Modern formats: WebP everywhere supported, AVIF where supported +- Responsive images: `srcset` for different viewport sizes +- Lazy loading: `loading="lazy"` for below-the-fold +- Explicit dimensions: prevents CLS +- Right size: don't ship 4000px images for 800px display +- LCP image: preload, never lazy-load + +### Font loading + +Web fonts often delay text render and cause CLS. + +Best practices: +- Self-host fonts (avoid third-party blocking) +- Preload critical fonts (`<link rel="preload" as="font">`) +- Use `font-display: swap` for non-critical fonts +- Subset fonts to remove unused glyphs +- Use variable fonts where possible +- Provide system-font fallback that visually matches + +### Third-party scripts + +Third parties (analytics, ads, chat widgets) often dominate performance budgets. + +Audit each: +- Is it required? +- Can it load after page interaction (defer)? +- Can it run from a worker (off main thread)? +- Is the third party itself fast? +- Are there lighter-weight alternatives? + +A common pattern: 50 percent of performance issues come from third-party scripts. + +--- + +## Workflow + +1. Establish a baseline. Lighthouse scan, WebPageTest run, or Real User Monitoring data. Capture current Core Web Vitals. +2. Identify the worst offender. LCP, INP, or CLS - which is failing? Focus there first. +3. Diagnose specifically. Browser dev tools (Performance tab, Network tab, Coverage tab). Identify the actual cause of the metric failure. +4. Plan fixes. Per identified issue, plan a specific change. Estimate impact and effort. +5. Implement. One fix at a time where possible. Easier to measure impact. +6. Re-measure. After each major fix, re-run Lighthouse and check Real User Monitoring. +7. Iterate. Performance is rarely solved in one pass. Plan for ongoing monitoring and fixes. + +--- + +## Tools + +Lab tools (run on demand): +- Lighthouse (built into Chrome DevTools) +- PageSpeed Insights (online) +- WebPageTest (online, more configurable) +- Browser Performance tab (deep flame graph analysis) + +Field tools (real user data): +- Chrome User Experience Report (CrUX) - public data for any site +- Real User Monitoring (RUM) - your own users (DataDog, New Relic, custom, etc.) +- Search Console Core Web Vitals report + +Lab tools are useful for diagnosis. Field tools are the source of truth for what users actually experience. + +--- + +## Failure patterns + +- Optimizing without measuring. Performance theater without baseline metrics. Always measure first. +- Optimizing the wrong metric. A great Lighthouse score with bad real-user metrics means your test conditions don't match users. +- Over-optimizing. Spending weeks shaving 10ms off TTFB while CLS is 0.4. Fix the worst offender first. +- Lighthouse-driven optimization only. Lighthouse runs in idealized conditions. Always check field data. +- Single-page optimization. Performance regressions creep in across the codebase. Build performance budgets and CI checks. +- Treating every byte as equal. A render-blocking 100KB script is worse than a deferred 500KB script. +- Bundle size obsession. Bundle size matters, but execution time matters more. A small bundle that takes 5 seconds to parse is worse than a larger bundle that runs fast. +- Ignoring third parties. "It's the analytics tag, not us." Third parties run on your domain in your users' eyes. Own them. + +--- + +## Output format + +Default output is a performance report at `performance-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools, conditions, sample pages) +3. Current state (Core Web Vitals, Lighthouse scores, RUM data) +4. Critical issues (Core Web Vitals failures) +5. Important issues (sub-optimal but not failing) +6. Polish (further-than-required wins) +7. Remediation roadmap (sequenced) +8. Performance budget recommendations +9. Monitoring plan + +For complex audits, include: +- Per-page Lighthouse exports +- Bundle analysis output +- Network waterfall screenshots +- Specific code snippets to change + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Full performance audit report template. +- [`references/optimization-checklist.md`](references/optimization-checklist.md) - Quick-reference checklist of common optimizations by priority. +- [`references/optimization-playbook.md`](references/optimization-playbook.md) - Symptom-to-fix playbook for the common Core Web Vitals problems (LCP, INP, CLS). diff --git a/dist/pi/.agents/skills/performance-optimization/references/audit-template.md b/dist/pi/.agents/skills/performance-optimization/references/audit-template.md new file mode 100644 index 0000000..a4b256a --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/audit-template.md @@ -0,0 +1,203 @@ +# Performance Audit Report + +A fillable template for documenting a web performance audit. Fill every section. Empty sections signal an incomplete audit. + +The output is the report. The report is what the team acts on. Weak reports produce no fixes. + +--- + +## Audit metadata + +Site / app: [Name and URL] +Pages audited: [List the specific URLs, not "the site"] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Devices and conditions tested: +- Mobile: [Device class, network throttling] +- Desktop: [Network throttling] +- Geographies: [If multi-region tested] +Tools used: [Lighthouse, WebPageTest, Chrome DevTools, real-user data source, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall state of performance. +2. Whether the site passes Core Web Vitals at the 75th percentile. +3. The single biggest issue and what it costs. +4. The recommended next move. +5. Estimated effort and impact for the top fix. + +> [Summary] + +--- + +## Core Web Vitals scorecard + +Use field data (CrUX, RUM) where available. Lab data (Lighthouse) is a fallback and a diagnostic, not a final verdict. + +\| Metric \| Target (good) \| Mobile p75 \| Desktop p75 \| Status \| +\|---\|---\|---\|---\|---\| +\| LCP (Largest Contentful Paint) \| < 2.5s \| \| \| Pass / Needs work / Fail \| +\| INP (Interaction to Next Paint) \| < 200ms \| \| \| Pass / Needs work / Fail \| +\| CLS (Cumulative Layout Shift) \| < 0.1 \| \| \| Pass / Needs work / Fail \| +\| TTFB (Time to First Byte) \| < 800ms \| \| \| Pass / Needs work / Fail \| +\| FCP (First Contentful Paint) \| < 1.8s \| \| \| Pass / Needs work / Fail \| + +### Trend + +- [ ] Improving over the past 28 days +- [ ] Stable +- [ ] Regressing + +### Field data source + +[CrUX history, Search Console, Sentry, RUM tool. Note the date range and traffic volume that the data covers.] + +--- + +## Page-level findings + +For each audited page, fill out: + +### Page: [URL or template name] + +Type: [Marketing / product / app shell / API-driven] +Traffic share: [Rough % of site traffic] +Field metrics (if available): +- LCP p75: +- INP p75: +- CLS p75: + +#### Lab metrics (Lighthouse mobile, slow 4G) + +- Performance score: +- LCP: +- INP (or TBT as proxy): +- CLS: +- Total page weight: +- Total requests: +- JS payload (parsed): + +#### Top issues on this page + +\| # \| Issue \| Impact metric \| Severity \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| LCP / INP / CLS / TTFB \| High / Med / Low \| S / M / L \| +\| 2 \| \| \| \| \| +\| 3 \| \| \| \| \| + +(Repeat the page block for each audited page.) + +--- + +## Cross-cutting findings + +Issues that affect many pages or the whole site. Often higher leverage than per-page fixes. + +### Asset pipeline + +- [ ] Images served in modern formats (WebP, AVIF)? +- [ ] Images served at appropriate sizes (responsive `srcset`)? +- [ ] Critical above-the-fold images preloaded? +- [ ] Below-the-fold images lazy-loaded? +- [ ] Video uses `preload="none"` or poster image until interaction? +- [ ] Fonts subsetted, woff2, `font-display: swap` (or `optional` for stable layout)? +- [ ] Self-hosted vs third-party fonts considered? + +### JavaScript + +- [ ] Bundle size budget defined? +- [ ] Code splitting per route? +- [ ] Third-party scripts inventoried, justified, and budgeted? +- [ ] Unused JavaScript flagged (Coverage tab in DevTools)? +- [ ] Long tasks (>50ms) inventoried? + +### CSS + +- [ ] Render-blocking CSS minimized? +- [ ] Critical CSS inlined for above-the-fold? +- [ ] Unused CSS flagged? + +### Server / network + +- [ ] HTTPS, HTTP/2 or HTTP/3 enabled? +- [ ] Compression (Brotli or gzip) enabled for text assets? +- [ ] Cache headers correct for static assets (long max-age, immutable)? +- [ ] CDN in front of origin? +- [ ] Origin response time (TTFB) measured and acceptable? + +### Layout stability + +- [ ] Images and embeds have explicit `width` and `height` (or `aspect-ratio`)? +- [ ] No layout shift from late-loading fonts? +- [ ] No layout shift from injected ads or banners? + +### Interactivity + +- [ ] Main-thread blocking under 200ms p75? +- [ ] Heavy listeners debounced or moved off main thread? +- [ ] Hydration cost measured (for SSR / partially hydrated frameworks)? + +### Third-party scripts + +\| Vendor \| Purpose \| Bytes \| Main-thread cost \| Necessary? \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| + +--- + +## Recommendations + +Prioritized action list. Each item is concrete, owned, and sized. + +### Now (this week) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Next (this sprint or month) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Later (this quarter or beyond) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| + +--- + +## Monitoring and re-test plan + +- Re-test cadence: [When will the audit be re-run?] +- Field data tracking: [Where will Core Web Vitals be tracked over time? CrUX dashboard, RUM tool, Search Console.] +- Performance budget: [Define and link the budget. Example: LCP under 2.0s p75 mobile, JS payload under 200KB compressed per route.] +- Alert thresholds: [When does someone get paged?] +- Owner of ongoing performance: [Person or team] + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- Lab tests run: [Tool, settings, run count] +- Field data window: [Date range, traffic volume] +- Throttling profile: [Slow 4G, Fast 3G, etc.] +- Geographies tested: [List] +- Caveats: [Anything that limits the audit's confidence, e.g., no field data, low traffic, single-page sample] diff --git a/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md b/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md new file mode 100644 index 0000000..3c53a5a --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/optimization-checklist.md @@ -0,0 +1,138 @@ +# Performance Optimization Checklist + +Quick-reference checklist of common performance optimizations, ordered by typical impact-per-effort. Use it as a triage list, not a script. Skip what does not apply. + +For symptom-to-fix walkthroughs, see `optimization-playbook.md`. For a structured audit report, see `audit-template.md`. + +--- + +## P0: blocks Core Web Vitals at the 75th percentile + +These optimizations almost always pay back. If a site is failing CWV, start here. + +### Images + +- [ ] LCP image is preloaded with `<link rel="preload" as="image" fetchpriority="high">` +- [ ] LCP image is NOT lazy-loaded +- [ ] Images use modern formats (WebP, AVIF) with fallback +- [ ] Images use responsive `srcset` with appropriately sized variants +- [ ] All `<img>` and `<video>` tags have explicit `width` and `height` (or `aspect-ratio` CSS) +- [ ] Below-the-fold images use `loading="lazy"` +- [ ] Decorative images use `decoding="async"` + +### Fonts + +- [ ] Web fonts use `font-display: swap` (or `optional` for layout stability) +- [ ] Font files are woff2 and subsetted to actual glyphs used +- [ ] Critical font files are preloaded +- [ ] Preconnect to font origin if hosted off-domain + +### JavaScript on the critical path + +- [ ] No render-blocking scripts in `<head>` (use `defer` or `async` or move to `<body>` end) +- [ ] Heavy third-party scripts (chat widgets, A/B test tools, analytics) are deferred until interaction or after load +- [ ] Bundle size budget enforced per route +- [ ] Code split per route or feature +- [ ] Unused JavaScript removed (Coverage tab in DevTools) + +### Layout stability + +- [ ] No content insertion above the fold after initial render (banners, ads, popups) +- [ ] Skeleton states or placeholders prevent layout shift on async content +- [ ] Avoid `@font-face` with no fallback chain +- [ ] Avoid web fonts that change metrics significantly between fallback and loaded state (use `size-adjust` and `ascent-override`) + +--- + +## P1: significant gains, moderate effort + +### Server and network + +- [ ] HTTP/2 or HTTP/3 enabled +- [ ] Brotli compression enabled (or gzip if Brotli unavailable) +- [ ] Cache headers correct for static assets: long `max-age` and `immutable` for hashed files +- [ ] CDN in front of origin for static assets (and dynamic where applicable) +- [ ] Origin response time (TTFB) under 800ms at p75 +- [ ] DNS prefetch and preconnect for critical third-party origins + +### Rendering strategy + +- [ ] Above-the-fold content is server-rendered (or static) where possible +- [ ] Critical CSS inlined for above-the-fold +- [ ] Non-critical CSS loaded asynchronously +- [ ] Partial / progressive hydration considered for heavy SPA pages + +### Resource loading + +- [ ] `<link rel="preload">` used for critical assets only (overuse hurts) +- [ ] `<link rel="modulepreload">` used for ESM critical chunks +- [ ] Resource hints (`prefetch`, `prerender`) used for likely next pages on key flows + +### Long tasks + +- [ ] Main-thread tasks over 50ms identified and broken up (`scheduler.yield()`, `requestIdleCallback`, web workers) +- [ ] Hydration cost measured for SSR sites; large components hydrated lazily + +--- + +## P2: smaller gains, useful in aggregate + +### Images and media + +- [ ] Hero video uses `preload="none"` or poster image until interaction +- [ ] Animated GIFs replaced with looped video (smaller, smoother) +- [ ] SVGs optimized (SVGO) and inlined where small +- [ ] Image delivery service (Cloudinary, ImgIX, native CDN image transform) used for on-the-fly resizing + +### Third-party scripts + +- [ ] Each third-party script audited: necessary, budgeted, and optimized +- [ ] Tag manager rules audited; remove unfired or duplicate tags +- [ ] Self-host third parties where licensing allows and origin caching helps + +### CSS + +- [ ] Unused CSS removed +- [ ] CSS specificity audited; avoid expensive selectors (deeply nested, universal) +- [ ] `will-change` and `transform`/`opacity` animations preferred over animating layout properties + +### JavaScript + +- [ ] Tree shaking confirmed working (check final bundle for dead code) +- [ ] Polyfills served only to browsers that need them (differential serving, `module/nomodule` pattern) +- [ ] Date / time / number formatting uses `Intl` instead of large libraries +- [ ] Heavy utility libraries replaced with smaller alternatives or native code where reasonable + +--- + +## P3: polish + +- [ ] Service worker caches critical assets for repeat visits +- [ ] Speculation Rules API used for likely next-page prerender +- [ ] HTTP early hints (103) used for critical preloads +- [ ] Server timing headers exposed for diagnostic visibility +- [ ] Real user monitoring (RUM) feeds CWV dashboard + +--- + +## Anti-patterns to remove + +These appear often, hurt always, and warrant a same-day fix. + +- [ ] Lazy-loaded LCP image +- [ ] Render-blocking analytics or tag manager in `<head>` without `async` +- [ ] Multiple competing fonts (more than 2 families or more than 4 weights) +- [ ] CSS-in-JS that ships runtime style generation to the client without static extraction +- [ ] Hero image larger than its rendered size by more than 2x +- [ ] Synchronous third-party scripts above any user-visible content +- [ ] Layout-shifting cookie banner or consent modal +- [ ] Background images that are CSS-loaded above the fold (preload friendlier as `<img>`) + +--- + +## How to use this checklist + +1. Run a Lighthouse + CrUX read of the 3-5 most important pages. +2. Walk this checklist top to bottom for each page. Mark passes, gaps, and not-applicable. +3. Triage gaps into the audit report (`audit-template.md`) under Now / Next / Later. +4. Re-test after each fix lands. Performance is a moving average, not a snapshot. diff --git a/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md b/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md new file mode 100644 index 0000000..b0419cf --- /dev/null +++ b/dist/pi/.agents/skills/performance-optimization/references/optimization-playbook.md @@ -0,0 +1,300 @@ +# Optimization Playbook + +A step-by-step playbook for common performance problems. Pick the symptom, follow the steps. + +--- + +## Symptom: LCP failing (>2.5s) + +The largest content element on the page takes too long to paint. + +### Step 1: Identify the LCP element + +In Chrome DevTools Performance panel: +1. Record a page load +2. Find the LCP marker +3. Note which element is the LCP (usually a hero image or large heading) + +### Step 2: Optimize that specific element + +If LCP element is an image: +- Use modern format (WebP, AVIF) +- Serve appropriately sized version (don't ship a 4000px image to a 800px container) +- Preload it: `<link rel="preload" as="image" href="hero.webp" fetchpriority="high">` +- Avoid lazy-loading the LCP image (use eager loading) +- Use `fetchpriority="high"` on the image element + +If LCP element is text/heading: +- Ensure web fonts don't block rendering (`font-display: swap`) +- Inline critical CSS for the heading section +- Preconnect to font origin: `<link rel="preconnect" href="https://fonts.example.com">` + +If LCP is loading slowly because the page is slow overall: +- See "Symptom: TTFB slow" below +- Reduce render-blocking resources +- Reduce total payload before LCP element + +### Step 3: Measure + +Re-test in Lighthouse and DevTools. Verify LCP under 2.5s on a slow connection (Slow 4G simulation in DevTools). + +--- + +## Symptom: INP failing (>200ms) + +Interactions feel sluggish. The page takes too long to respond to user input. + +### Step 1: Find the slow interactions + +In Chrome DevTools Performance panel: +1. Record while clicking, typing, or interacting +2. Look for long tasks (orange bars >50ms) following input events +3. Identify the function calls that take the longest + +### Step 2: Reduce the work + +For event handlers: +- Move heavy work out of the synchronous path +- Use `setTimeout` or `requestIdleCallback` to yield to the main thread +- Debounce or throttle frequent events (scroll, mouse move, resize) + +For component re-renders (React, Vue, etc.): +- Memoize expensive computations +- Avoid creating new objects/arrays/functions in render that get passed as props +- Use virtualization for large lists (react-window, virtua, or framework equivalent) +- Profile to find which components re-render and why + +For startup hydration (SSR/SSG frameworks): +- Defer hydration of non-critical components +- Use island architecture or partial hydration where supported +- Code-split aggressively below-the-fold + +### Step 3: Verify + +INP should be under 200ms at the 75th percentile of real user data. + +--- + +## Symptom: CLS failing (>0.1) + +Content jumps around as the page loads. + +### Step 1: Identify the shifts + +In Chrome DevTools: +1. Open Performance Insights or Performance panel +2. Look for "Layout Shifts" markers +3. Click each to see what shifted + +### Step 2: Reserve space for dynamic content + +Common offenders and fixes: + +- Images without dimensions. Add `width` and `height` attributes (or `aspect-ratio` CSS). +- Late-loading ads or embeds. Reserve a fixed-size container. +- Web fonts swapping. Use `font-display: optional` or size-adjust descriptors. +- Skeleton loaders that don't match final size. Match dimensions exactly. +- Animations triggering layout. Animate only `transform` and `opacity`. +- Insertion of content above existing content. Reserve space or insert below. + +### Step 3: Verify + +Run Lighthouse. Real-user CLS at 75th percentile should be under 0.1. + +--- + +## Symptom: TTFB slow (>800ms) + +Server takes too long to respond. + +### Step 1: Check the server response + +Use WebPageTest or `curl -w "@curl-format.txt" -s -o /dev/null https://example.com` to measure just TTFB. + +### Step 2: Identify the bottleneck + +Common causes: + +- No caching at the edge. Add a CDN. Set Cache-Control headers correctly. +- Slow database queries. Run EXPLAIN on slow queries. Add indexes. Eliminate N+1 patterns. +- Slow third-party API calls in the render path. Defer to client or precompute. +- Heavy server-side rendering. Profile the SSR work. Memoize what's repeated. +- Cold starts (serverless). Provisioned concurrency or warming pings. + +### Step 3: Verify + +TTFB under 600ms at the 75th percentile is the target. Under 200ms is excellent. + +--- + +## Symptom: Bundle size too large + +JavaScript payload bloating the page. + +### Step 1: Audit the bundle + +Run a bundle analyzer (Webpack Bundle Analyzer, source-map-explorer, etc.). Sort by size. + +### Step 2: Identify the offenders + +Common bloat sources: + +- Unused dependencies. Tree-shaking missing or broken. +- Whole-library imports. `import { debounce } from 'lodash'` pulls all lodash. Use `import debounce from 'lodash/debounce'`. +- Polyfills shipped to modern browsers. Use differential serving. +- Source maps in production bundle. Should be separate files, not inline. +- Moment.js, Lodash, jQuery. Often replaceable with smaller alternatives or native APIs. +- Multiple versions of the same library. Check `npm ls [library]`. Dedupe. + +### Step 3: Reduce + +- Replace heavy libraries with lighter alternatives (date-fns or dayjs instead of moment, native fetch instead of axios) +- Code-split routes +- Code-split heavy components (modals, charts, editors) +- Use dynamic imports for below-the-fold features + +### Step 4: Set a budget + +In your build config or CI, fail builds that exceed the budget. + +--- + +## Symptom: Image-heavy page loads slowly + +### Step 1: Audit images + +- Count images on the page +- Note current sizes and formats +- Note which are above-the-fold (eagerly loaded) vs below (should be lazy) + +### Step 2: Optimize each + +Format: +- Photos: WebP or AVIF (with JPEG fallback) +- Graphics: SVG or PNG (with WebP fallback) +- Animations: video (MP4/WebM) instead of GIF for size + +Sizing: +- Generate multiple sizes via `srcset` +- Use `sizes` attribute to tell the browser the rendered size + +```html +<img + src="hero-800.webp" + srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1600.webp 1600w" + sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px" + width="1600" + height="900" + alt="Description" + loading="eager" + fetchpriority="high" +/> +``` + +For below-the-fold: +- `loading="lazy"` +- Without `fetchpriority` + +Compression: +- Use a build-time image pipeline (sharp, imagemin) to compress automatically +- Quality 75-85 is usually invisible to users while halving file size + +--- + +## Symptom: Web fonts blocking text + +### Step 1: Audit font loading + +In DevTools Network tab, filter by font. Note: +- File size +- When they load relative to first paint +- Whether text is invisible or fallback during load + +### Step 2: Optimize + +- Use `font-display: swap` to show fallback text immediately +- Subset fonts to only the characters needed (Latin only is much smaller than full Unicode) +- Self-host critical fonts instead of CDN where possible +- Preload critical fonts: + ```html + <link rel="preload" href="/fonts/regular.woff2" as="font" type="font/woff2" crossorigin> + ``` +- Use `size-adjust`, `ascent-override`, `descent-override` in `@font-face` to match metrics with fallback fonts (reduces CLS) + +--- + +## Symptom: Third-party scripts dragging performance + +### Step 1: Inventory third-parties + +In DevTools Network tab, list all third-party domains. For each: +- Size +- Blocking or non-blocking? +- Necessary? + +### Step 2: Decide on each + +For every third-party script, ask: does the business value justify the performance cost? + +Common offenders: +- Heavy analytics (audit if all pixels are necessary; consider server-side tagging) +- Customer support chat widgets (load on user intent, not on page load) +- A/B testing tools (defer non-critical experiments) +- Multiple ad networks (consolidate) +- Tag managers loading hundreds of tags + +Fixes: +- Remove unused tags +- Defer non-critical scripts (`async` or `defer`) +- Self-host where licensing allows (avoids extra DNS lookup) +- Load chat widgets on user interaction, not on page load +- Consolidate analytics where possible + +### Step 3: Set a third-party budget + +Number of third-party domains, total third-party JS payload. Block-add for new third-parties without explicit performance review. + +--- + +## Performance budget template + +Set hard limits in your CI to prevent regression: + +```yaml +budget: + - resourceSizes: + - resourceType: total + budget: 500 # kilobytes + - resourceType: script + budget: 200 + - resourceType: image + budget: 200 + - resourceType: stylesheet + budget: 50 + - resourceType: font + budget: 100 + - resourceType: third-party + budget: 100 + - timings: + - metric: largest-contentful-paint + budget: 2500 # milliseconds + - metric: cumulative-layout-shift + budget: 0.1 + - metric: total-blocking-time + budget: 200 +``` + +Tools like Lighthouse CI, Calibre, or SpeedCurve can enforce these budgets in CI. + +--- + +## When to call it done + +A page is "performance optimized" when: + +1. Real-user Core Web Vitals at 75th percentile pass thresholds +2. Lighthouse performance score >90 on representative pages +3. Performance budgets enforced in CI +4. Periodic re-audit scheduled (quarterly minimum) + +Performance is not a one-time project. New code adds weight. New features add complexity. Plan for ongoing maintenance. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md b/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md new file mode 100644 index 0000000..a0bf78d --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/SKILL.md @@ -0,0 +1,260 @@ +--- +name: pillar-content-architecture +description: "How to design a content hub that earns topical authority. Pillar topic selection, cluster planning, internal linking architecture, URL structure, pillar and cluster page anatomy, topical authority signals for SEO and AEO/GEO, and the maintenance discipline that distinguishes intentional hubs from accidental orphans. Triggers on pillar content, content hub, topic cluster, topical authority, content architecture, hub and spoke, pillar page, cluster page, content silo, internal linking strategy. Also triggers when a content set is not ranking despite individual piece quality, when a pillar was launched without a cluster, or when content has accumulated without an architecture." +category: content +catalog_summary: "Hub-level content architecture: pillar topic selection, cluster planning, internal linking, URL structure, pillar and cluster page anatomy, topical authority signals, refresh discipline" +display_order: 1 +--- + +# Pillar Content Architecture + +A senior content architect's playbook for designing content hubs that earn topical authority. + +Most content programs accumulate accidentally. Pieces ship one at a time, internal linking happens (or does not) in editing, similar topics get covered by multiple pieces with no coordination, and six months later the team has a content set that looks like a sitemap but feels like a yard sale. Search engines see disconnected pages; AI engines see scattered citations; readers cannot tell which piece is the entry point and which is the reference. + +This skill is the discipline of intentional hub architecture. It assumes you have decided which topic areas to invest in (see `content-strategy`) and have keyword data (see `seo-keyword`). It does not write any individual piece (see `content-brief-authoring` for per-piece work and `content-and-copy` for execution). What it does is design the structure: which topic gets a pillar, which subtopics get cluster pieces, how the pieces link to each other, where they live in the URL hierarchy, and what topical authority signals the architecture is engineered to produce. + +When to use this skill: launching a new content hub, restructuring an existing content set into a hub, deciding whether a piece should be a pillar or a cluster, or auditing why a content area is not ranking despite individual piece quality. + +--- + +## What this skill is for + +This skill spans hub-level content architecture. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: multiple topic pillars, editorial calendar, governance, formats. Decides what topic areas to invest in across a quarter or year. +- `seo-keyword` is upstream-input: keyword research that surfaces candidate pillar topics with volume, difficulty, and intent data. +- This skill is hub-scope: one pillar plus its cluster, the architecture that ties them together. The structural decisions, not the per-piece content. +- `content-brief-authoring` is per-piece scope: brief for one content artifact. Each cluster piece (and the pillar itself) gets briefed via that skill. +- `content-and-copy` is execution scope: writing the piece itself. +- `seo-content-gap-audit` is audit-side: finds missing pieces in an existing content set after the fact. This skill prevents the gaps; that skill catches the ones that emerge. + +The clean composition: `content-strategy` decides which topics, `seo-keyword` surfaces opportunities, this skill designs the hub, `content-brief-authoring` briefs each piece, `content-and-copy` writes each piece, `seo-content-gap-audit` later catches what slipped. Six skills, sequential. + +The audience: SEO content strategists, content architects, in-house teams designing content hubs, agencies running topical authority programs. The voice is senior content architect to junior content marketer. Concrete, opinionated, honest about what makes a hub earn authority versus decorate the sitemap. + +--- + +## Pillar vs cluster vs orphan content + +The keystone distinction. Three categories of content in any program. + +Pillar. Comprehensive piece covering a major topic area. 2,500 to 5,000 words plus. Anchors the topical authority claim for the topic. Receives links from cluster pieces; links out to cluster pieces selectively, not as a footer dump. The pillar is the entry point for the topic and the reference the cluster orbits. + +Cluster. Narrower piece covering a specific facet of the pillar topic. 800 to 2,000 words. Links up to pillar; may link sideways to other clusters in the same hub when a connection is natural. Each cluster answers one specific question within the pillar's scope. + +Orphan. Piece that does not connect to a pillar or cluster. May rank or convert on its own merits, but does not compound into topical authority. Some orphans are fine by design (release-note pages, customer stories, one-off campaigns); most orphans are accidents. + +The pathology. Most content programs are 80% orphans, 15% accidental clusters, 5% accidental pillars. The discipline is moving toward 70% intentional clusters, 20% intentional pillars, 10% standalone-by-design. Same total content volume; different architectural outcome. + +The reading model. Search engines and AI engines both read internal-link graphs to infer topical authority. A pillar with 12 well-linked cluster pieces signals depth on a topic. 12 orphans on the same topic signal scattered, less-authoritative coverage. The architecture is the signal. + +Detail and decision tree in [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md). + +--- + +## Topic selection for pillar pages + +Not every topic deserves a pillar. The five-criterion selection framework: + +1. Search volume justifies the investment. Pillar topic has enough monthly volume to support a 3,000 to 5,000-word effort plus 8 to 15 cluster pieces. Sub-100 monthly searches usually does not. +2. Topic has natural facets. You can identify 8 to 15 distinct subtopics that could each be their own piece. If you can only think of 3, it is probably a cluster, not a pillar. +3. Commercial relevance. The topic connects to your business model. A pillar without commercial signal is content marketing for content marketing's sake. +4. Competitive feasibility. Top 10 SERP for the pillar keyword is achievable. If the SERP is dominated by Wikipedia, government sites, and Fortune 500 brands, your pillar will rank position 47 no matter how good it is. +5. Editorial commitment. The team will maintain the pillar (refresh annually, add new clusters, update statistics). Pillars are not ship-and-forget; they are 5-year commitments. + +The "everything is a pillar" anti-pattern. Teams call any 3,000-word piece a pillar. Length does not make a pillar. The architecture does. Pillar is the role a piece plays in the hub structure, not the word count. + +Detail in [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md). + +--- + +## Cluster planning + +Once a pillar is selected, plan its cluster: + +1. Cluster size. Typically 8 to 15 pieces for a strong hub. Below 5 reads thin; above 25 becomes unmanageable; sweet spot is 10 to 12. +2. Cluster facets. Each cluster piece covers one facet of the pillar topic. Facets are surfaced from keyword research (long-tail variations of pillar keyword), "people also ask" data, sub-headings in top-ranking pillar pages on the SERP, competitor cluster maps, and first-party customer questions (sales calls, support tickets). +3. No facet duplication. Two cluster pieces should not target overlapping queries. If they do, consolidate to one piece. +4. Cluster heterogeneity. Clusters should cover the topic from multiple angles (definition, how-to, comparison, examples, common mistakes, costs, alternatives, case studies) rather than 12 variations of "what is X." +5. Sequence. Ship pillar first (or alongside the first 3 to 5 clusters). The link graph will not form without the pillar in place; clusters that link to a non-existent pillar are orphans-in-waiting. + +Detail in [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md). + +--- + +## Internal linking architecture + +The hub's internal-link graph is what actually produces topical authority signals. The architecture has three directions: + +Pillar to cluster (top-down). Pillar links out to each cluster piece via contextual anchors, typically once per cluster from within the pillar's body. Do not bury cluster links in a "related reading" footer; weave them into the relevant section of the pillar where the reader's curiosity peaks. + +Cluster to pillar (bottom-up). Every cluster piece links up to the pillar at least once, typically in the first 200 words and again in the closing section. Bottom-up is the discipline that makes the pillar compound; without it the pillar is just a long article. + +Cluster to cluster (lateral). Selective lateral linking when one cluster naturally references another. Do not force lateral links; an "everyone links to everyone" cluster is messy and dilutes anchor text relevance. + +Anchor text discipline. Vary the anchor text. "Click here" is dead; exact-match keyword stuffing is dead; descriptive natural-language anchors are alive. The brief for each piece (see `content-brief-authoring`) specifies anchor text per outbound link. + +The "linking inventory" pattern. Maintain a sheet (or database row, or dbt model) tracking every link in the hub, who links to whom, and the anchor text used. Audit quarterly to catch broken links, anchor-text drift, and missing connections that should exist. + +Detail in [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md). + +--- + +## URL structure and information architecture + +URL patterns matter for both crawl clarity and reader navigation. Decision factors: + +Subfolder vs subdomain. Subfolder is the default (`example.com/hub-topic/cluster-piece`) for SEO consolidation; both pillar and cluster live on the same domain authority. Subdomain is appropriate only for genuinely distinct properties (`docs.example.com`, `community.example.com`). + +Hub URL pattern. `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. Avoid `/blog/cluster-piece/` if the goal is hub authority; the URL itself signals topical grouping to crawlers and readers. + +Slug conventions. Short, descriptive, keyword-aware but not stuffed. `/seo-content-strategy/keyword-research-for-pillars/` not `/the-ultimate-guide-to-seo-content-strategy-keyword-research-for-pillar-pages-2026/`. + +Breadcrumbs. Surface the hub structure in breadcrumb navigation. Helps readers see where they are; helps crawlers see the hierarchy. + +The "/blog/ trap." Teams put pillar and clusters under `/blog/` because that is where the CMS folder is. This works structurally but loses the URL signal that says "these pieces belong together as a topical hub." + +Detail in [`references/url-structure-patterns.md`](references/url-structure-patterns.md). + +--- + +## Pillar page anatomy + +A pillar page does specific work. The standard sections: + +- Hero. Defines the topic, signals scope ("The complete guide to X for Y audience"), establishes authority quickly. +- TL;DR or executive summary. 150 to 250 words at the top. AI engines often cite this section verbatim. Treat it as the citation-ready summary, not as a marketing intro. +- Comprehensive body. Covers the topic's major facets, with internal-link callouts to cluster pieces for deep dives. The body is not a comprehensive treatment of every facet; it is a guided tour with depth links. +- Use cases or examples. Anchor the abstract topic to concrete instances. +- Common mistakes / FAQ. AI-citation friendly section with structured Q&A. Pair with FAQ schema markup. +- Closing or next steps. Directs reader into the cluster (which piece to read next based on intent). +- Schema markup. Article or HowTo schema depending on intent; FAQPage schema for the FAQ section. + +Pillar length. 3,000 to 5,000 words is the typical range. Pillar quality is comprehensiveness AND depth, not just word count. A 6,000-word pillar that covers 3 facets is worse than a 4,000-word pillar that covers 12 facets. + +Detail in [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md). + +--- + +## Cluster piece anatomy + +Cluster pieces have a different shape: + +- Hero. Focused on one specific question or task, not broad. +- Pillar callout. Link up to pillar in the first 200 words. Typical phrasing: "This piece covers X. For the broader context on Y, see our guide to [pillar topic]." +- Focused body. Answers the specific question with depth, but does not expand into adjacent facets (those have their own cluster pieces). +- Lateral callouts (selective). When relevant, link to 1 or 2 sibling cluster pieces. +- Closing. Link back to pillar OR to the next logical cluster piece in a reader journey. + +Cluster length. 800 to 2,000 words typical. A cluster piece longer than 2,500 words is probably a mini-pillar that should either get promoted to its own pillar or be split into two cluster pieces. + +Detail in [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md). + +--- + +## Topical authority signals + +Signals that make hub architecture compound into authority. The two-engine view: pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +SEO signals: + +- Internal-link graph density on the topic (PageRank flow within the hub) +- Comprehensive entity coverage across pillar plus clusters (mentioned entities, statistics, citations) +- URL structure clarity +- Breadcrumb hierarchy +- Schema markup (Article, HowTo, FAQPage as appropriate) +- E-E-A-T signals: author credentials, expertise demonstrated, trust signals on every piece + +AEO and GEO signals: + +- Answer-paragraph format directly under H2 headings (40 to 60 words, citation-ready) +- TL;DR section on pillars (highly citable; AI engines extract it verbatim) +- FAQ schema (still cited heavily by AI engines including Perplexity and ChatGPT) +- Specific statistics with cited sources +- Named experts and named methods (entities AI engines weight heavily for citation) +- Distinctive POV that AI engines can attribute to your brand + +The two-engine optimization is complementary, not competing. Both reward depth, structure, and entity coverage. The hub architecture creates more surface area for both signal types than scattered orphan content can. + +Detail in [`references/topical-authority-signals.md`](references/topical-authority-signals.md) and the `seo-aeo-geo` skill for AEO/GEO strategy at the program level. + +--- + +## Maintenance and refresh patterns + +Hubs decay if not maintained. The discipline: + +- Annual pillar refresh. Every 12 months, audit the pillar against current SERP, update statistics, add new sections for emerged facets, prune sections that no longer matter, refresh internal-link callouts to cluster pieces (since the cluster has likely grown). +- Cluster refresh as triggered. Clusters refresh when keyword performance drops, when a new sub-topic emerges, or when a cluster's links go stale. +- Cluster expansion. Add new cluster pieces as the topic surfaces new facets. A hub at year 1 might have 8 clusters; year 3 could have 18. +- Cluster pruning. Kill cluster pieces that fail to rank or get cited after 12 months. Redirect to the most-relevant remaining cluster or to the pillar. Pruning is not failure; it is hygiene. +- Hub lifecycle. Hubs themselves have a lifespan. After 5 to 7 years, even mature hubs may need wholesale restructuring as the topic landscape shifts. + +The "set and forget" failure. Hub launches, ranks, drives traffic for 2 years, then decays without anyone noticing because nobody owns the hub long-term. Hub ownership is durable: single owner across 3 to 5 year horizons, not "the team that launched it." + +Detail in [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pillar-failures.md`](references/common-pillar-failures.md). + +- "We have 80 blog posts but no rankings." Orphan content; no hub architecture. +- "Our 8,000-word pillar does not rank." Comprehensive but no cluster support; pillar without a hub is just a long article. +- "We launched the pillar, never built the cluster." Architecture half-built signals nothing. +- "Cluster pieces do not link to the pillar." Top-down link graph but no bottom-up; the pillar does not compound. +- "Two cluster pieces target the same keyword." Self-cannibalization; consolidate. +- "Pillar URL is /blog/the-ultimate-guide-to..." Losing the URL hub signal. +- "Our pillar is 12 sections of 'what is X'." Facet homogeneity; covers one angle 12 ways. +- "We cannot tell which piece to refresh first." No maintenance ownership; no signals being tracked. +- "Pillar ranks but does not get cited by AI engines." Missing AEO/GEO signals (no TL;DR, no answer paragraphs, no FAQ schema). +- "Hub launched 3 years ago; nobody owns it now." Lifecycle ownership gap. +- "We have 25 clusters and it is chaos." Over-built; sweet spot was 12. + +--- + +## The framework: 12 considerations for hub architecture + +When designing or auditing a content hub, walk these 12 considerations. + +1. Topic earns the pillar. Search volume, facet count, commercial relevance, competitive feasibility, editorial commitment. +2. Cluster size targets 10 to 12. Sweet spot, not the maximum. +3. Facet heterogeneity. Definition, how-to, comparison, examples, mistakes, costs, alternatives. Not 12 variations of "what is X." +4. No facet duplication. Clusters cover distinct queries; consolidate when they overlap. +5. Pillar to cluster to pillar link graph. Top-down plus bottom-up plus selective lateral. +6. Anchor text discipline. Varied, descriptive, natural-language. No stuffing, no "click here." +7. URL structure signals the hub. `/topic/` not `/blog/`. +8. Pillar anatomy includes TL;DR and FAQ. Citation-ready sections for AI engines. +9. Cluster anatomy links UP to pillar early. First 200 words and closing. +10. AEO/GEO and SEO together. Two-engine optimization, complementary not competing. +11. Annual pillar refresh plus triggered cluster refresh. Maintenance is part of the architecture. +12. Hub ownership is durable. Single owner across 3 to 5 year horizons; not "the team that launched it." + +The output of the framework is an architecture document the team can reference at every stage: pillar selected, cluster planned, links specified, URLs chosen, page anatomies templated, refresh cadence set, owner named. + +--- + +## Reference files + +- [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md) - Pillar vs cluster vs orphan decision tree with worked examples and the "everything is a pillar" anti-pattern. +- [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md) - Five-criterion framework expanded with B2B SaaS, ecommerce, services, and media examples. +- [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md) - Facet sourcing methods, sequencing patterns, heterogeneity check. +- [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md) - Top-down, bottom-up, lateral patterns; anchor text discipline; linking inventory; quarterly audit checklist. +- [`references/url-structure-patterns.md`](references/url-structure-patterns.md) - Subfolder vs subdomain decision; slug conventions; breadcrumbs; the /blog/ trap. +- [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md) - Section-by-section anatomy; TL;DR placement; FAQ schema; internal-link callouts; schema choices; length calibration. +- [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md) - Focused-question framing; pillar callout placement; lateral linking judgment. +- [`references/topical-authority-signals.md`](references/topical-authority-signals.md) - SEO and AEO/GEO signals at hub level; two-engine optimization framing. +- [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md) - Annual pillar refresh; triggered cluster refresh; cluster expansion and pruning; hub lifecycle. +- [`references/common-pillar-failures.md`](references/common-pillar-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: architecture is the moat + +Comprehensive content can be replicated. Authoritative sources can be cited. Individual pieces can be matched in quality by competitors with similar resources. What is harder to replicate is the compounding of an intentional hub built and maintained over years: the link graph, the entity coverage, the maintenance discipline, the topical depth signals that build over a 3 to 5 year horizon. + +That is the moat. Architecture is the only part of content marketing that compounds reliably; everything else is execution that can be matched. + +When in doubt about whether a hub is ready, ask: is the pillar selected against the five criteria, are the 10 to 12 clusters planned with facet heterogeneity, is the link graph specified top-down and bottom-up, is the URL structure clean, is the pillar anatomy templated with TL;DR and FAQ, is the refresh cadence set, and is the durable owner named? If yes to all of those, ship the hub plan and let the per-piece briefs and writers work. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md new file mode 100644 index 0000000..85ca692 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-piece-anatomy.md @@ -0,0 +1,120 @@ +# Cluster piece anatomy + +Focused-question framing. Pillar callout placement. Lateral linking judgment. + +--- + +## The shape of a cluster piece + +A cluster piece is not a mini-pillar. Different shape, different work. + +### Hero (first 100 to 150 words) + +Focused on one specific question or task. The hero does not introduce the broader topic; the pillar does that. The hero introduces the cluster piece's specific facet. + +- Title. Includes the cluster's primary keyword. Often question-form ("What is a feature flag kill switch?") or task-form ("How to design a feature flag kill switch"). +- Subhead. One sentence promising the specific answer. + +### Pillar callout (within first 200 words) + +The bottom-up link to the pillar. Required. + +Pattern. "This piece covers feature flag kill switches in depth. For the broader context on rollout strategies that include kill switches as one safety mechanism, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +Why required. The pillar callout is the structural signal that this cluster belongs to the hub. Without it, the piece reads as a standalone article and the hub does not compound. + +Why early. Crawlers and AI engines weight links higher when they appear near the top of the page. The first 200 words is the citation-prime real estate; the pillar callout there has more impact than the same callout in the closing. + +### Focused body (the bulk of the cluster) + +Answers the specific question with depth. Does not expand into adjacent facets. + +The discipline. When the writer notices an interesting tangent into an adjacent facet, they note it as a candidate for another cluster piece and stay on topic. The cluster piece does one thing well; expansion belongs in a different piece. + +Section structure. 4 to 6 H2 sections covering the cluster's question from different angles. Each H2 has a featured-snippet-bait answer paragraph (40 to 60 words) followed by 200 to 400 words of development. + +### Lateral callouts (selective) + +When the cluster's body naturally references a sibling cluster, link to it. + +Pattern. A cluster on percentage rollouts naturally references kill switches in the section on "what happens when the rollout shows problems." A 1-sentence aside with a contextual link to the kill switches cluster. + +Frequency. 0 to 3 lateral links per cluster piece. Some clusters need none; some clusters at the topic's center connect to several siblings. + +Anti-pattern. Forced lateral linking. If the connection is not natural to the body's flow, the link is decorative and dilutes anchor signal. + +### Closing + +Two equally valid closing patterns. + +Pattern A: link back to pillar. "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns." + +Pattern B: link to next cluster in a journey. "If you have your kill switches designed and want to think about progressive rollouts, read our [percentage rollout guide](/feature-flag-rollout/percentage-rollouts/) next." + +The choice. Pattern A is the safe default; it reinforces the pillar and works for most cluster pieces. Pattern B is appropriate when the cluster has a clear "next step" in a reader journey (foundational concept → next concept). + +--- + +## Length calibration + +800 to 2,000 words is the typical cluster range. Calibrate to: + +- The SERP for the cluster's specific keyword. Top 10 word counts tell you the band. +- The cluster's place in the hub. Foundational clusters (definitions, intros) often run shorter; advanced clusters (deep how-tos, comparisons) often run longer. + +The 2,500-word cluster trap. A cluster piece longer than 2,500 words is probably a mini-pillar. Two diagnostic questions: + +1. Does it cover 2+ distinct facets? If yes, split into two cluster pieces. +2. Does it have 8+ H2 sections? If yes, it is structurally a pillar; either promote it (with cluster support) or trim. + +The 600-word cluster trap. A cluster piece shorter than 800 words is often too thin to rank for its target keyword. Either: + +- Expand to 1,000+ words with deeper coverage of the question. +- Merge with a sibling cluster if the topic does not have enough depth. +- Demote to a non-hub blog post if the piece is just a brief observation. + +--- + +## Featured snippet bait at H2 level + +Cluster pieces benefit from featured-snippet-bait answer paragraphs at every H2, not just at the top. + +Pattern. + +> ## What is a feature flag kill switch? +> +> A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. + +The 40 to 60 word answer paragraph is self-contained and citation-ready. AI engines extract these paragraphs as the canonical answers. + +Frequency. Every H2 should have a snippet-bait paragraph. The pattern repeats throughout the piece; it is a structural discipline. + +--- + +## Schema markup for clusters + +Cluster pieces typically use Article schema (or HowTo if the cluster is a step-by-step guide). FAQPage schema applies if the cluster has a real FAQ section. + +BreadcrumbList schema is required for cluster pieces; it tells crawlers the cluster is part of the hub. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +--- + +## When the cluster piece is also useful as a standalone + +Some cluster pieces will rank for queries unrelated to the pillar's topic. A cluster on "kill switches" might also rank for queries about software safety patterns generally. + +The decision: keep the cluster piece in the hub even when it ranks for non-hub queries. The pillar callout costs nothing for the standalone-query reader; the hub-traffic reader benefits from the link. Both audiences are served. + +The exception: when the cluster piece's standalone ranking dominates and the pillar context is misleading to the standalone-query reader, consider splitting into two pieces. Rare; usually the pillar callout works fine for both audiences. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md new file mode 100644 index 0000000..ba1195e --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/cluster-planning-patterns.md @@ -0,0 +1,108 @@ +# Cluster planning patterns + +Facet sourcing methods, sequencing patterns, heterogeneity check. + +--- + +## Facet sourcing methods + +A pillar's cluster is built from 8 to 15 facets. Source them deliberately rather than from the writer's imagination. + +### Method 1: keyword research expansion + +Start with the pillar keyword. Pull the long-tail variations from keyword tools (Ahrefs, Semrush, GSC, dataForSEO). Filter by intent: each cluster facet should have its own SERP intent and dominant format. Variations that share intent with the pillar are not separate facets; they belong inside the pillar itself. + +### Method 2: "people also ask" extraction + +Pull the PAA box for the pillar keyword and 3 to 5 supporting keywords. Each unique question is a candidate cluster facet. PAA is the cleanest signal of what readers actually ask in this topic space. + +### Method 3: top-ranking competitor outline mining + +Pull the top 5 SERP results for the pillar keyword. Extract H2 sections from each. Cluster the H2s across the 5 competitors; sections that appear in 3+ competitors are facets the topic objectively requires. Sections unique to 1 or 2 competitors may be differentiation opportunities. + +### Method 4: first-party customer questions + +Sales calls, support tickets, customer success notes, sales enablement Q&A. The questions customers actually ask are facets the pillar needs to address even if SERP signal is weak. First-party questions also produce differentiation: questions your customers ask but that competitor content does not address. + +### Method 5: Frase or AirOps SERP analysis + +Frase's entity gap analysis and AirOps' workflow builder both run versions of methods 1 to 3 in software. The output is a candidate facet list with SERP coverage scores. Use the tool output as the starting point; refine with first-party questions (method 4) for differentiation. + +--- + +## Sequencing patterns + +How to ship the hub over time. + +### Pattern A: pillar first, cluster follows + +Ship the pillar as a 3,000 to 5,000 word piece. Over the next 6 to 12 weeks, ship 1 to 2 cluster pieces per week. By month 3, the hub has the pillar plus 8 to 12 clusters and starts compounding. + +When this works. Strong editorial team that can ship a pillar quickly. The pillar drives initial rankings; clusters fill in topical depth as they ship. + +The risk. Pillar ranks for 6 weeks before the cluster is complete; AI engines see a thin hub and may not return to crawl when clusters land. Mitigated by including cluster placeholders in the pillar with "coming soon" or by pre-publishing cluster stubs. + +### Pattern B: pillar plus first 5 clusters concurrent + +Ship the pillar and the first 5 clusters within the same 4-week window. The hub launches with the link graph already partially formed; rankings start with depth signals already in place. + +When this works. Larger team or agency support. The launch produces a more credible hub on day 1. + +The cost. Higher up-front investment. The first 5 clusters lock the team's editorial capacity for the launch window. + +### Pattern C: prove with 3 clusters, then commit to pillar + +Ship 3 cluster pieces under a planned-but-not-yet-shipped pillar slot. Measure performance over 8 to 12 weeks. If the clusters draw traffic and the topic shows commercial signal, commit to the pillar. If not, pivot to a different pillar topic without the sunk cost. + +When this works. Uncertain topic where the commercial signal needs validation before the pillar investment. Common in agencies running pillars for clients without strong upfront conviction. + +The discipline. The 3 clusters must be writeable as standalones during the validation window; they cannot reference the pillar by name yet because it does not exist. Once the pillar ships, retrofit the cluster pieces with pillar callouts and bottom-up links. + +--- + +## Heterogeneity check + +A cluster passes heterogeneity if its facets cover the topic from multiple distinct angles. The check: + +Categorize each facet by primary angle: + +- Definition (what is X) +- How-to (how to do X) +- Comparison (X vs Y) +- Examples (5 examples of X, X case studies) +- Mistakes (common X mistakes) +- Costs (how much X costs, X pricing models) +- Alternatives (alternatives to X) +- Best-of (best X tools, top X providers) +- Use cases (when to use X) +- Niche variants (X for [specific audience]) +- Foundational (related concept Y that supports X) +- Advanced (advanced X techniques) + +The rule. A 12-cluster hub should have facets across 6+ distinct angles. If 10 of 12 are "how-to," the cluster is homogeneous and the pillar will look like a how-to series rather than a topical authority hub. + +The fix. When facet brainstorming over-indexes on one angle, deliberately add 2 to 3 facets from different angles. The "5 examples of X" cluster piece is often the most under-served angle; teams forget to add concrete-example pieces and over-invest in abstract how-tos. + +--- + +## No facet duplication + +Two cluster pieces should not target overlapping queries. The check: + +- For each cluster piece, list the 3 to 5 keywords it would target. +- For each pair of cluster pieces, check whether their keyword lists overlap by more than 30%. +- Overlapping clusters compete for the same SERP and self-cannibalize. Consolidate to one piece. + +The most common duplication. "What is X" and "X explained" and "X definition" are the same facet. Pick one slug and one focus; do not split the foundational definition across three pieces. + +--- + +## When the cluster is too big + +A planned cluster with 25+ pieces is over-built. The hub becomes unmanageable: maintenance burden too high, link graph too dense to audit, reader navigation confusing. + +Fix 1. Split into two pillars under a parent pillar. The original pillar covers the broadest topic; sub-pillars cover major sub-territories with their own clusters. Three-level hierarchy is rare but valid for very broad topics. + +Fix 2. Trim to the 12 most-impactful facets. Rank facets by combined search volume + commercial relevance + heterogeneity contribution; keep the top 12; archive the rest as future-cluster candidates. + +The 12-cluster sweet spot is empirical. Below 8, the hub looks thin; above 15, maintenance overhead kicks in; 10 to 12 is the band where most healthy hubs sit. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md b/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md new file mode 100644 index 0000000..9ec094c --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/common-pillar-failures.md @@ -0,0 +1,150 @@ +# Common pillar failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "We have 80 blog posts but no rankings" + +Symptom. The team has been publishing for 2+ years; 80 pieces shipped; organic traffic is flat or declining. + +Diagnosis. Orphan content; no hub architecture. 80 disconnected pieces produce no topical authority signal regardless of individual quality. + +Fix. Audit the 80 pieces. Group by topic. For each major topic group, identify or build a pillar; refactor the existing pieces into clusters by adding pillar callouts and bottom-up links. Some pieces will not fit and become standalone-by-design; some will need consolidation. + +The expected outcome: 4 to 6 hubs, each with a pillar plus 8 to 12 clusters; 15 to 20 standalones; the rest pruned. See `pillar-cluster-decision.md`. + +--- + +## "Our 8,000-word pillar does not rank" + +Symptom. Team invested in a long, comprehensive pillar; 6 months in, position 23 on the primary keyword. + +Diagnosis. Comprehensive but no cluster support; the pillar is a long article without a hub. Length without architectural support does not signal authority. + +Fix. Build the cluster. Plan 10 to 12 cluster pieces under the pillar; ship 3 to 5 in the next 8 weeks; complete the cluster within 6 months. Update the pillar with internal-link callouts to each cluster as they ship. See `cluster-planning-patterns.md`. + +The expected outcome: ranking improves over 3 to 6 months as the cluster matures. The pillar that did not rank standalone will rank as the hub forms. + +--- + +## "We launched the pillar, never built the cluster" + +Symptom. Pillar shipped 8 months ago; team's editorial focus shifted; the planned cluster never landed. Pillar has 2 supporting pieces shipped haphazardly. + +Diagnosis. Architecture half-built. The 2 supporting pieces are functioning as orphans because the hub is not formed; the pillar gets minimal compounding. + +Fix. Either commit to completing the cluster (8 to 10 more pieces over 4 to 6 months) or prune the hub. Half-built hubs are worse than no hub; commit or unwind. If completing, prioritize facets the team can ship within 12 weeks. + +--- + +## "Cluster pieces do not link to the pillar" + +Symptom. Hub has pillar plus 12 clusters; pillar links to all clusters; only 4 of 12 clusters link back to the pillar. + +Diagnosis. Top-down link graph but no bottom-up. The pillar does not compound. Cluster pieces have not been required to include pillar callouts. + +Fix. Audit each cluster; add pillar callouts in the first 200 words and the closing of any cluster that lacks them. Update the brief template to require both pillar callouts on every future cluster piece. See `internal-linking-architecture.md`. + +--- + +## "Two cluster pieces target the same keyword" + +Symptom. Cluster includes "what is a feature flag" and "feature flags explained." Both rank position 8 to 12 alternately; neither breaks into the top 5. + +Diagnosis. Self-cannibalization. Two pieces competing for the same SERP; PageRank splits across two URLs; neither piece gets enough authority to rank top 5. + +Fix. Consolidate. Pick the stronger piece (higher current rank, more inbound links, longer URL history). 301 redirect the weaker piece to the stronger one. Merge any unique content from the weaker into the stronger. Update the linking inventory. + +--- + +## "Pillar URL is /blog/the-ultimate-guide-to..." + +Symptom. The pillar lives at `/blog/the-ultimate-guide-to-feature-flag-rollout-strategies/` because the CMS routes everything under `/blog/`. + +Diagnosis. Losing the URL hub signal. Crawlers cannot infer hub topology from the URL; readers cannot tell from the URL that this is a pillar. + +Fix. Migrate to `/feature-flag-rollout/` for the pillar; cluster pieces to `/feature-flag-rollout/[slug]/`. 301 redirect old URLs. Take a short-term ranking hit; gain long-term hub-signal clarity. See `url-structure-patterns.md`. + +The migration is not always worth it. If the pillar is small or the brand's overall content investment is modest, the cost may exceed the benefit. Score against the hub's commercial value. + +--- + +## "Our pillar is 12 sections of 'what is X'" + +Symptom. Pillar covers the topic comprehensively in length but every H2 is a definitional question. "What is X." "What does X do." "What are the parts of X." 12 variations of the same angle. + +Diagnosis. Facet homogeneity. The pillar covers one angle 12 ways instead of 12 distinct angles. + +Fix. Rewrite the pillar's outline using the heterogeneity check (definition, how-to, comparison, examples, mistakes, costs, alternatives, etc.). Replace 8 of the 12 definitional sections with sections covering different angles. See `cluster-planning-patterns.md`. + +--- + +## "We cannot tell which piece to refresh first" + +Symptom. Hub has 14 pieces; team knows refresh is needed; cannot prioritize where to start. + +Diagnosis. No maintenance ownership; no signals being tracked. Without per-piece performance data, refresh prioritization is guesswork. + +Fix. Assign a hub owner (see `content-refresh-patterns.md`). Track 4 metrics per piece: organic traffic, primary-keyword rank, AI citation count if measurable, last-updated date. Prioritize refresh on pieces with declining traffic, slipping ranks, or oldest update dates. The metrics make the prioritization mechanical. + +--- + +## "Pillar ranks but does not get cited by AI engines" + +Symptom. Pillar ranks position 4 on Google; brand mention rate from Profound is unchanged after the pillar shipped. + +Diagnosis. Missing AEO/GEO signals. Pillar may have no TL;DR, no answer paragraphs under H2s, no FAQ schema, vague statistics, no named experts. + +Fix. Audit the pillar against the AEO/GEO signals checklist (see `topical-authority-signals.md`). Add a 150 to 250 word TL;DR at the top. Add 40 to 60 word answer paragraphs under each H2. Mark FAQ section with FAQPage schema. Replace vague statistics with specific numbers and cited sources. Add named experts where the topic supports them. + +The AEO/GEO refresh is faster than the SEO refresh; expect citation improvement within 4 to 8 weeks of changes propagating. + +--- + +## "Hub launched 3 years ago; nobody owns it now" + +Symptom. Hub built by a content lead who left 18 months ago. No formal owner since. Performance has degraded; nobody noticed. + +Diagnosis. Lifecycle ownership gap. The "set and forget" failure mode. + +Fix. Assign a new owner. Allocate 1 to 2 weeks of editorial time for an emergency refresh: re-validate the SERP, update statistics, prune dead sections, refresh internal links. Set the annual refresh cadence going forward; track ownership renewal in the hub's planning doc. See `content-refresh-patterns.md`. + +Some hubs at this stage are unrecoverable. If the SERP has shifted enough that the original architecture no longer fits, restructure rather than refresh; treat as a year-5+ lifecycle event. + +--- + +## "We have 25 clusters and it is chaos" + +Symptom. Hub started at 12 clusters; expanded over 3 years to 25; the linking inventory is unmanageable; new pieces tangle with old pieces; readers cannot find what they need. + +Diagnosis. Over-built. The cluster expanded beyond the manageable sweet spot. + +Fix. Prune. Apply the cluster pruning criteria (see `content-refresh-patterns.md`): clusters that have not ranked in top 30 after 12 months, clusters with zero search volume, clusters that duplicate other clusters. Aim to trim back to 12 to 15 active clusters; archive the rest with redirects. + +Alternative: split into two pillars under a parent topic. Rare; valid only for genuinely broad topics. + +--- + +## "We did all the SEO work but the AI engines do not cite us" + +Symptom. Pillar ranks well; clusters rank well; brand mention rate from Profound is flat. AI engines cite competitors instead. + +Diagnosis. Could be either: + +- The hub is structurally fine for SEO but missing AEO/GEO signals (see "pillar ranks but does not get cited" above). +- The hub is missing distinctive POV. AI engines preferentially cite content with attributable claims; content that reads as SEO consensus does not get cited even when it ranks. + +Fix. Audit each pillar and high-traffic cluster for distinctive claims. Add at least one strong POV per piece: a position the team is willing to defend, a recommendation that is not "it depends," a specific claim with named experts and statistics behind it. Bland comprehensive content does not get cited; opinionated comprehensive content does. + +--- + +## "We have a hub but conversions are flat" + +Symptom. Hub drives traffic, ranks well, gets cited; trial signups attributable to the hub are flat. + +Diagnosis. Topical authority is working; commercial conversion is not. The hub's content does not connect cleanly to the buyer journey. + +Fix. Audit the pillar and clusters for commercial CTAs. Each cluster should have a clear next step that is NOT just "read another cluster." Trial signup, demo request, content download, newsletter subscription. The hub is producing the audience; the conversion path needs separate design work. + +This failure is outside this skill's scope to fully solve; pair with `landing-page-copy` for conversion-focused next-step pages and `content-strategy` for funnel-aware content planning. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md new file mode 100644 index 0000000..3517077 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/content-refresh-patterns.md @@ -0,0 +1,164 @@ +# Content refresh patterns + +Annual pillar refresh checklist. Triggered cluster refresh signals. Cluster expansion patterns. Cluster pruning criteria. Hub lifecycle (5 to 7 year horizon). + +--- + +## Why refresh matters + +Hubs decay. Statistics go stale; SERPs shift; new facets emerge; existing pieces drift from current best practice. A hub that ranks at year 1 often falls to position 12 by year 3 if nobody refreshes it. + +The discipline is built into the architecture: refresh is not an afterthought; it is a budgeted activity. + +--- + +## Annual pillar refresh checklist + +Run every 12 months on each pillar. Allocate 1 to 2 weeks of editorial time per pillar. + +### Step 1: re-validate the SERP + +Pull the current SERP top 10 for the pillar's primary keyword. Compare to the last refresh's top 10. + +- Are new competitors in the top 10? What are they covering that you are not? +- Have existing competitors updated their pillars? What new sections did they add? +- Has the SERP intent shifted (e.g., from informational to commercial-investigation)? + +### Step 2: update statistics + +Find every numeric claim in the pillar. Verify each is still accurate; replace stale numbers with current ones; cite the new source. + +Common stale numbers. Industry statistics that were "as of 2023" and now are 2 years old. Pricing references that have shifted. Tool capabilities that have evolved. + +### Step 3: add new sections for emerged facets + +Did the topic surface new facets in the last 12 months? Add H2 sections covering them. Each new section should be 300 to 500 words; if it grows beyond 700, promote it to a new cluster piece and reduce the pillar section to a callout. + +### Step 4: prune sections that no longer matter + +Did old sections become irrelevant? Maybe a tool you covered shut down; maybe a method you described was deprecated. Cut or significantly trim those sections. Pillar bloat from un-pruned content is the most common pillar-decay symptom. + +### Step 5: refresh internal-link callouts to clusters + +The cluster has likely grown since last refresh. Add callouts to any new cluster pieces that did not exist before. Verify all existing callouts still link to live cluster URLs. + +### Step 6: update the TL;DR + +The TL;DR captures the pillar's argument as of the refresh date. Revise to reflect any structural changes: new facets, removed sections, shifted POV. + +### Step 7: bump the last-updated date + +Set the publish-modified date to the refresh completion date. The freshness signal matters; do not skip it. + +### Step 8: re-submit to search engines + +Submit the updated pillar URL to Google Search Console for re-crawl. Some teams also ping AI engine indexing endpoints (Perplexity, Bing for Copilot) where available. + +--- + +## Triggered cluster refresh signals + +Clusters do not need annual refresh; they need triggered refresh when specific signals appear. + +### Trigger 1: keyword performance drops + +The cluster's primary keyword falls 5+ positions in 30 days. The drop is the signal; pull the SERP, identify what is now ranking ahead, and update the cluster to compete. + +### Trigger 2: new sub-topic emerges + +Within the cluster's facet, a new sub-topic appeared (new tool launched, new technique published, new regulation issued). Update the cluster to reference the new sub-topic. + +### Trigger 3: cluster's links go stale + +The quarterly link audit (see `internal-linking-architecture.md`) finds broken outbound links from the cluster. Update the cluster with new links. + +### Trigger 4: AI citation drops + +The cluster was being cited by AI engines and the citation count drops. Check whether content drifted, whether new entities should be added, whether the answer paragraphs need tightening. AI citation drops are slower-moving than ranking drops; act on month-over-month trends, not week-over-week. + +### Trigger 5: customer feedback surfaces a gap + +A sales rep, support agent, or customer success manager flags that the cluster does not cover a question customers actually ask. Add the section. + +--- + +## Cluster expansion patterns + +A hub at year 1 might have 8 clusters. Year 3 could have 18. Expansion happens deliberately, not opportunistically. + +### When to expand + +- A new facet emerges and customer questions confirm demand. +- Competitor analysis shows a facet your hub does not cover. +- Keyword research surfaces new long-tail variations with traffic. +- AI citation patterns show queries your hub does not address. + +### When not to expand + +- Tempting facet but no customer demand. Adds maintenance burden without driving traffic. +- Facet already covered by another piece on the site outside the hub. Either move that piece into the hub or update its links. +- Facet is too narrow (sub-100 monthly searches with no commercial signal). Add as a section to an existing cluster, not as its own cluster. + +### Expansion cap + +Max 20 clusters per pillar. Above that, the hub becomes unmanageable. If the topic genuinely supports 25+ facets, split into two pillars under a parent topic (rare; valid for very broad topics). + +--- + +## Cluster pruning criteria + +Some clusters should die. Pruning is hygiene, not failure. + +### Prune when + +- Cluster has not ranked in top 30 after 12 months despite refresh attempts. +- Cluster's keyword has gone to zero search volume. +- Cluster duplicates another cluster (consolidate). +- Cluster covers a tool, technique, or topic that no longer exists. + +### How to prune + +- 301 redirect the URL to the most-relevant remaining cluster, or to the pillar. +- Remove links from the pillar and other clusters to the pruned URL. +- Update the linking inventory. + +### What not to do + +- Do not delete the URL without redirecting; 404s waste any acquired authority. +- Do not redirect to the homepage; redirect to the most topically-relevant alternative. + +--- + +## Hub lifecycle (5 to 7 year horizon) + +Hubs themselves have lifespans. After 5 to 7 years, the topic landscape often shifts enough that wholesale restructuring becomes appropriate. + +### Signs the hub needs restructuring (vs annual refresh) + +- The pillar's primary keyword has shifted intent (the SERP is now showing a different content type). +- Competitors have rebuilt their hubs around a different angle that better matches current reader needs. +- The cluster has grown unwieldy (25+ pieces) and the topical organization no longer makes sense. +- AI citation patterns suggest readers are asking questions the original hub structure cannot answer. + +### Restructuring approach + +- Treat the restructuring as a new hub launch. Plan the new pillar and cluster shape first. +- 301 redirect old pillar and cluster URLs to new equivalents where possible. +- Archive content that does not fit the new structure rather than force-fitting. +- Communicate the change in a release-note-style post linked from both old and new URLs during the transition. + +The 5-to-7 year cycle is empirical. Some hubs last longer (foundational topics like "what is SEO"); some need restructuring sooner (fast-moving topics like "AI search"). Ownership tracks the lifecycle; the durable hub owner is the one who decides when to restructure. + +--- + +## Maintenance ownership + +The pillar owner is named and durable. Common patterns: + +- Single editor. One person owns the hub for a 12-month commitment. Renewed annually. +- Editor + SEO partner. Editor owns content; SEO partner owns rankings and link audits. +- Cross-functional team. Editor, SEO, product marketing rotate quarterly reviews. Works for large teams; falls apart in small teams (rotation diffuses ownership). + +The "set and forget" failure mode happens when ownership dissolves. The team that launched the hub disbanded, was reorganized, or moved on; nobody picks up maintenance. Six quarters later, the hub has decayed and recovery costs more than the original launch. + +The fix. Assign a durable owner before the hub launches. Renew the assignment annually. Track the owner's continued ownership in the hub's planning doc; surface in quarterly reviews. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md b/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md new file mode 100644 index 0000000..805f61f --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/internal-linking-architecture.md @@ -0,0 +1,100 @@ +# Internal linking architecture + +Top-down, bottom-up, lateral linking patterns. Anchor text discipline. The linking inventory pattern. Quarterly link audit checklist. + +--- + +## The three link directions + +A hub's link graph has three directions; all three need discipline. + +### Top-down: pillar to cluster + +The pillar links out to each cluster piece via contextual anchors woven into the pillar's body. The reader is reading the section on, for example, "kill switches"; that section includes a contextual link to the cluster piece on kill switches. + +Pattern. "Most rollouts include a kill switch as a final safety net. For the full pattern including code-level implementations, see [our guide on kill switch design](/feature-flag-rollout/kill-switches/)." + +Anti-pattern. A "Related reading" footer at the bottom of the pillar listing 12 cluster links. Footer links pass less topical signal and read as decorative; contextual body links read as load-bearing. + +Frequency. One link per cluster from within the pillar. Two links to the same cluster from the pillar is fine if the cluster covers two distinct sections; three links to the same cluster suggests the pillar should reference the cluster more selectively. + +### Bottom-up: cluster to pillar + +Every cluster piece links up to the pillar at least twice. First in the introduction (within the first 200 words); second in the closing. + +Pattern in introduction. "This piece covers kill switches in feature flag rollouts. For the broader context on rollout strategies, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +Pattern in closing. "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns, or jump to [percentage rollouts](/feature-flag-rollout/percentage-rollouts/)." + +Why two. First link tells crawlers and readers the topical context immediately. Second link captures readers who got value from the cluster piece and want to dig deeper into the hub. + +### Lateral: cluster to cluster + +Selective. When one cluster piece naturally references another, link with descriptive anchor text. Do not force lateral links. + +Pattern. A cluster on "percentage rollouts" naturally references "kill switches" when discussing what to do if the rollout shows problems. The lateral link is contextual; the reader is at a moment where the related cluster is actually useful. + +Anti-pattern. Every cluster piece links to every other cluster piece. The link graph becomes complete-graph-shaped; anchor text relevance dilutes; PageRank flow is undirected and weaker. + +Frequency. 1 to 3 lateral links per cluster piece is typical. Some clusters need zero lateral links; some clusters that sit at the center of a topic naturally connect to 5 sibling clusters. + +--- + +## Anchor text discipline + +Anchor text is the signal that tells search engines what the linked-to page is about. The discipline: + +Vary the anchor text. Do not link to the pillar with the exact same phrase every time. Use the pillar's primary keyword, secondary keywords, and natural-language phrases that describe the linked page. + +Descriptive natural-language anchors. "See our guide to feature flag rollout strategies" beats "click here to read more." The anchor text should make sense if it is the only thing the reader reads. + +No over-optimization. Do not stuff every link with exact-match keywords. Anchor text that varies naturally is what a real authority cluster looks like; uniform exact-match anchors signal manipulation to ranking systems. + +Brand-mention anchors. Sometimes the right anchor is the brand name or product name when linking to a product page. "RampStack's experimentation skill" is a brand anchor; "experimentation skills documentation" is a descriptive anchor. Mix both. + +Common dead anchors. "Click here," "this article," "read more," "more info." All dead. They pass minimal topical signal and waste the link's potential. + +--- + +## The linking inventory pattern + +Maintain an inventory of every link in the hub. The format depends on the team's tooling. + +Spreadsheet. Columns: source page slug, target page slug, anchor text, link section (intro / body / closing / sidebar), link direction (top-down / bottom-up / lateral / external). + +Notion database. Same columns as relations, queryable per page or per direction. + +dbt model with content metadata. For warehouse-native content tracking; the link graph becomes a queryable table that compounds with other content metrics (rank, citation count, conversion). + +CMS audit fields. Some CMSs (Contentful, Sanity, custom WordPress) allow per-page metadata fields. Track outbound links per piece; aggregate at the hub level. + +The inventory enables the quarterly audit; without it, the audit becomes a manual scan that misses things. + +--- + +## Quarterly link audit checklist + +Run every 90 days. Catches the failures that compound silently. + +1. Broken outbound links. Crawl every cluster piece for 404s on outbound links. Common cause: cluster piece was renamed or moved without redirect. +2. Missing bottom-up links. Every cluster should link to the pillar in intro and closing. Audit checks both. +3. Missing top-down links. Pillar should link to every cluster from within the body. Audit checks each cluster has at least one body link from the pillar. +4. Anchor text drift. Same anchor text used by 5+ links to the same target reads as over-optimized. Vary by editing 2 to 3 of them. +5. Dead anchors. "Click here" or "read more" anchors that crept in during writing. Replace with descriptive anchors. +6. Lateral over-linking. Cluster pieces linking to 5+ siblings reads as complete-graph noise. Trim to 2 to 3 most-relevant siblings. +7. Orphan clusters. Cluster piece that no other piece links to (besides the pillar). The pillar's top-down link is required; ideally 1 to 2 sibling lateral links also exist. +8. Stale references. Cluster pieces that reference statistics, products, or pages that no longer exist. Update the references; refresh the piece if the underlying topic shifted. +9. New cluster integration. When a new cluster piece ships, audit confirms it received its top-down link from the pillar AND its bottom-up plus lateral links. New clusters often miss the inbound updates that would prevent orphan status. +10. Anchor diversity. Pull the inventory; group anchor texts by target page. If 8 of 10 links to a page use the same anchor, edit 3 to 5 to vary. + +The audit takes 1 to 3 hours per hub. The cost is real but smaller than the cost of letting the link graph decay. + +--- + +## When the link graph is too dense + +Some teams over-link. Every cluster piece has 8 outbound contextual links plus 5 lateral plus 3 external. The reader is bombarded; the anchor text relevance dilutes. + +Heuristic. A cluster piece with more than 6 outbound internal links per 1,000 words is over-linked. Trim to the 4 to 6 highest-relevance links. + +The trim improves both reader experience and PageRank concentration. Each remaining link gets more weight; the link graph becomes more legible to crawlers. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md new file mode 100644 index 0000000..a5fe670 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-cluster-decision.md @@ -0,0 +1,98 @@ +# Pillar vs cluster vs orphan decision + +The decision tree, worked examples, and the "everything is a pillar" anti-pattern. + +--- + +## The decision tree + +When a new piece is being planned, walk these questions in order. + +Question 1. Does this topic have 8 to 15 distinct facets that could each be a separate piece? + +- Yes: this might be a pillar. Continue to question 2. +- No: this is not a pillar. Continue to question 4 to test cluster fit. + +Question 2. Is the topic competitive enough to require comprehensive coverage to rank? + +- Yes (top 10 SERP shows long-form pillars from authoritative sources): pillar candidate confirmed. Continue to question 3. +- No (top 10 SERP shows short articles or tools): the topic does not need a pillar. A cluster piece probably suffices. + +Question 3. Is the team committed to maintaining this pillar for 3 to 5 years (annual refresh, cluster expansion, ownership)? + +- Yes: ship as pillar. Plan the cluster. +- No: do not start. A pillar without maintenance is worse than no pillar; it ranks for a year, then decays. + +Question 4. Is there an existing pillar this piece could connect to as a cluster? + +- Yes: ship as cluster. Specify the pillar callout and the bottom-up link in the brief. +- No: continue to question 5. + +Question 5. Is this piece intentionally standalone (release note, customer story, one-off campaign, executive announcement)? + +- Yes: ship as standalone. Standalone-by-design is fine. +- No: this is an accidental orphan. Either build the pillar first, or postpone the piece until a pillar exists, or rescope the piece to fit an existing pillar's cluster. + +--- + +## Worked examples + +### Example 1: "Feature flag rollout strategies" + +A B2B SaaS team is planning a piece on feature flag rollout strategies. + +- 8 to 15 facets? Yes: percentage rollout, ring deployment, canary, blue-green, kill switches, automatic rollbacks, rollout per cohort, rollout by geography, rollout by plan tier, etc. ✓ +- Competitive SERP? Top 10 are long-form articles from LaunchDarkly, Statsig, Optimizely. Pillar candidate confirmed. ✓ +- 3 to 5 year commitment? The team plans to expand the cluster as new patterns emerge. ✓ + +Decision: pillar. Plan 10 to 12 cluster pieces around it. + +### Example 2: "How to set up a Statsig experiment" + +The same team is planning a how-to on Statsig experiment setup. + +- 8 to 15 facets? No. The topic is one task with maybe 5 sub-steps. ✗ +- Existing pillar to connect to? Yes: the team has an "experimentation" pillar. + +Decision: cluster. Pillar callout to "experimentation" pillar; link up in first 200 words and closing. + +### Example 3: "Q3 2026 product release notes" + +The marketing team is planning a quarterly release-notes post. + +- 8 to 15 facets? No. ✗ +- Existing pillar to connect to? Not a topical fit; release notes are a different content type. +- Standalone-by-design? Yes; release notes serve customers tracking the product, not topical authority. + +Decision: standalone. Do not force into a hub; serve the customer tracking purpose. + +### Example 4: "What is a feature flag?" + +A piece on the basic definition. + +- 8 to 15 facets? No. The topic is one definition. ✗ +- Existing pillar to connect to? Yes: the "feature flag rollout strategies" pillar from example 1 needs a "what is a feature flag" cluster piece for the foundational facet. + +Decision: cluster under the feature flag rollout pillar. The pillar gets the cluster it needs; the piece gets the topical context it needs. + +--- + +## The "everything is a pillar" anti-pattern + +The symptom. Every 3,000-word piece on the team's site is called a pillar. The marketing team uses the word loosely; the SEO team uses it strictly; nobody agrees on what makes a pillar. + +The diagnosis. Length is being treated as the pillar criterion. Length does not make a pillar. The architectural role does. A 3,000-word piece with no cluster supporting it is a long article, not a pillar. A 1,500-word piece with 12 cluster pieces linking up to it is closer to a pillar than the 3,000-word standalone, even though the word counts are reversed. + +The fix. Use the word "pillar" precisely. Pillar is a piece that anchors a hub. If there is no hub, there is no pillar. Long articles that are not anchoring hubs are just long articles, and that is fine; they do not need to be promoted to "pillar" to justify the investment. + +The diagnostic question. "What pieces link up to this pillar?" If the answer is "none yet" or "we are planning to add some," the pillar is not yet a pillar. It is a planned pillar that becomes a real pillar when the cluster ships. + +--- + +## When the decision is hard + +The "almost a cluster" case. A piece is 1,800 words, covers a specific facet of an existing pillar, and would link up to the pillar. Sounds like a cluster. But the piece also stands alone for non-hub queries. Decision: ship as cluster. The pillar callout is cheap; the topical compounding is real. The "standalone-by-design" exception is for pieces that have a different purpose (release notes, customer stories), not for pieces that happen to be readable alone. + +The "almost a pillar" case. A piece is 3,500 words, covers a topic with 6 facets (not 8 to 15), and the SERP for the topic is moderately competitive. Decision: ship as a long cluster piece under a broader pillar, or postpone until the topic surfaces more facets. Forcing 3,500 words into a 6-facet topic creates the "pillar with 12 sections of 'what is X'" failure mode. + +The "we already have 5 standalone pieces on this topic" case. No pillar exists; 5 orphans cover related facets. Decision: build the pillar, then refactor the 5 orphans into clusters by adding pillar callouts and bottom-up links. The hub is being created from existing content rather than from scratch; this is faster than starting over and works well when the orphans are already decent. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md new file mode 100644 index 0000000..c3ba778 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/pillar-page-anatomy.md @@ -0,0 +1,144 @@ +# Pillar page anatomy + +Section-by-section anatomy. TL;DR placement and length. FAQ schema. Internal-link callout placement. Schema markup choices. Length calibration. + +--- + +## Section-by-section structure + +A pillar page does specific work across a recognizable set of sections. + +### Hero (first 200 words) + +Defines the topic, signals scope, establishes authority quickly. + +- Title. Includes the primary keyword. Reads as comprehensive ("The complete guide to feature flag rollout strategies"). +- Subhead. One sentence promising specific value to a specific audience. +- Author / publish / update line. Author name with link to bio (E-E-A-T signal); last-updated date (freshness signal). + +### TL;DR or executive summary (150 to 250 words) + +The most important section for AI citation. AI engines extract this verbatim and use it as the canonical answer when users ask the topic question. + +What goes in. A self-contained summary of the pillar's argument. Read alone, it answers the topic. Read in context, it sets up the comprehensive body. + +What does not go in. Marketing fluff. Throat-clearing meta-commentary that announces what the page is about to do instead of doing it. Cut it. + +Format. Either a single dense paragraph (150 to 250 words) or 5 to 7 bullet points. Both work; bullets often extract more cleanly to AI engines. + +### Table of contents + +Auto-generated from H2 and H3 structure. Anchors to each section. Helps readers scan; helps crawlers see structure. + +### Comprehensive body (the bulk of the pillar) + +12 to 20 H2 sections covering the topic's major facets. The body is a guided tour with depth links, not a comprehensive treatment of every facet. + +Per H2 section. + +- Featured snippet bait. A 40 to 60 word answer paragraph immediately following the H2 question. AI engines often quote this as the citation. +- Body of the section. 200 to 600 words developing the answer with examples, formulas, edge cases. +- Cluster link callout. When the section maps to a cluster piece, link to the cluster contextually within the body. "For the full pattern including [specific facet], see our [cluster piece guide]." + +### Use cases or examples + +Anchor the abstract topic to concrete instances. 3 to 5 worked examples. Each example named, scoped, and referenced in the body. + +### Common mistakes / FAQ + +Structured Q&A. Each Q is a real question; each A is a 40 to 80 word answer. + +Pair with FAQPage schema. Mark the Q&A section with FAQPage structured data. AI engines (Perplexity especially) cite FAQPage content heavily. + +Anti-pattern. "Frequently asked questions" that nobody actually asks. The FAQ should source from real customer questions, sales-call transcripts, support tickets. Fabricated FAQs are obvious to readers and to AI engines. + +### Closing or next steps + +Directs the reader into the cluster. "If you are starting fresh, read [intro cluster piece]. If you have rollouts running and need to harden them, read [advanced cluster piece]." + +The closing is also where the second bottom-up pillar reinforcement lands for cluster pieces; for the pillar itself, the closing names the next-best clusters by reader intent. + +--- + +## TL;DR placement and length + +Place immediately after the hero, before the table of contents. The reader sees TL;DR within the first scroll. AI engines scrape from the top of the page; TL;DR placed early gets prioritized. + +150 words minimum. Below 150, the TL;DR is too thin to serve as a citation candidate. + +250 words maximum. Above 250, the TL;DR loses its punch and starts duplicating the body. + +Self-contained. A reader who reads only the TL;DR should walk away with the topic's core. No throat-clearing or hedging; the TL;DR IS the answer. + +--- + +## FAQ schema + +The FAQ section gets FAQPage schema. The format: + +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is a feature flag kill switch?", + "acceptedAnswer": { + "@type": "Answer", + "text": "A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. Kill switches are configured at deploy time and remain available throughout the feature's lifecycle." + } + } + ] +} +``` + +Common mistake. FAQPage schema on questions that are not real FAQs. Schema markup that misrepresents page content can trigger manual penalties; mark only genuine FAQ sections. + +--- + +## Internal-link callout placement + +The pillar links to cluster pieces from within the body, not from a "related reading" footer. + +Pattern. Inside the H2 section that maps to a cluster, place one contextual link to the cluster piece. Position the link at the moment in the section where the reader's curiosity peaks: typically after the section has set up the question and before the answer goes deep. + +Example. In the H2 "What is a kill switch?" section, after the 40 to 60 word answer paragraph, link to the cluster piece on kill switches with the phrase "For the full pattern including code-level implementations, see our [kill switch design guide]." + +Frequency. One link per cluster from the pillar. Two if the cluster maps to two distinct sections of the pillar. Avoid more than two; the second link is the reinforcement, not a third or fourth. + +--- + +## Schema markup choices + +The pillar's primary schema depends on intent. + +Article schema. Default for most pillars. Marks the page as long-form editorial content. + +HowTo schema. When the pillar is a step-by-step guide ("how to launch a feature flag rollout"). HowTo gives Google more structured data to render in SERPs. + +FAQPage schema. Always pair with the FAQ section, not the pillar overall. + +BreadcrumbList schema. Always include for hub navigation context. + +Author schema. Embed Person schema for the author with credentials, bio link, and same-as references to LinkedIn or X. E-E-A-T signal. + +--- + +## Length calibration + +3,000 to 5,000 words is the typical pillar range. Calibrate to the SERP, not to a quota. + +SERP top 10 average word count tells you the band. Pull the top 10; tag word counts; aim for the top 3 average. If the top 3 average 4,200 words, your pillar should target 4,000 to 4,500. + +The depth-vs-length tradeoff. Pillar quality is comprehensiveness AND depth, not just length. A 6,000-word pillar that covers 3 facets in massive depth is worse than a 4,000-word pillar that covers 12 facets at appropriate depth. Length without breadth is not a pillar; it is a long article. + +The cluster offload. Each cluster piece reduces the depth required in the pillar's corresponding section. If kill switches has its own cluster piece, the pillar's kill-switches section can be 300 words pointing to the cluster, not 1,200 words duplicating the cluster. The cluster offload is what keeps the pillar at the right length. + +--- + +## Updates and freshness signals + +The pillar's "last updated" date is a freshness signal. Update it whenever you make material changes (statistics refreshed, new section added, cluster expanded). Do not update it for cosmetic edits; spurious freshness signals are noticed by ranking systems. + +The annual pillar refresh (see `content-refresh-patterns.md`) is the discipline that produces honest freshness signals. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md b/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md new file mode 100644 index 0000000..f5505a5 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/topic-selection-criteria.md @@ -0,0 +1,104 @@ +# Topic selection criteria + +The five-criterion framework for pillar topic selection, with worked examples across business types. + +--- + +## The five criteria + +A topic earns pillar status only when all five hold. Failing one is a hard signal to stop. + +### 1. Search volume justifies the investment + +The pillar will cost 3 to 6 weeks of editorial effort and 8 to 15 cluster pieces. The topic needs enough monthly search demand to repay the investment over a 3 to 5 year horizon. + +Heuristic. Pillar topic with combined volume across the keyword cluster of 1,000+ monthly searches usually justifies a pillar. Below 500 combined monthly searches, the topic is probably a single cluster piece under a broader pillar, not its own pillar. + +Exception. High-commercial-value topics with low volume (enterprise B2B SaaS niches, expensive professional services) can justify pillars at lower volumes because each ranking visit is worth more. + +### 2. Topic has natural facets + +A pillar covers a topic with internal structure. The team should be able to brainstorm 8 to 15 distinct subtopics, each capable of being a standalone cluster piece. + +The test. Spend 30 minutes listing facets. If the list reaches 12 organically, the topic has the structure. If the list stalls at 5, the topic is a cluster, not a pillar. + +Common false positive. Listing 12 keyword variations of "what is X" is not 12 facets. It is one facet (definition) said 12 ways. True facets are dimensionally different (definition, how-to, comparison, mistakes, costs, alternatives, examples, case studies). + +### 3. Commercial relevance + +The topic connects to the business model. A pillar without commercial signal is content marketing for content marketing's sake. + +The test. Can you draw a line from "reader lands on this pillar" to "reader becomes customer or contributor of customer-related signal"? If yes, the topic is commercially relevant. If the line requires three hops and a leap of faith, the topic is too far from the business. + +### 4. Competitive feasibility + +Top 10 SERP for the pillar keyword is achievable for the brand at its current authority. If the SERP is dominated by Wikipedia, government sites, and global household-name brands, your pillar will rank position 47 no matter how good it is. + +The test. Pull the SERP top 10. Tag each result by domain authority and commercial profile. If the top 10 are all DR 80+ household names and your brand is DR 35, do not start the pillar. Either pick a less-competitive long-tail variant or build authority on adjacent topics first. + +### 5. Editorial commitment + +The team will maintain the pillar for 3 to 5 years: annual refresh, cluster expansion, ownership through team changes. + +The test. Name the durable owner. If the owner is "the marketing team" instead of a specific person with a 12-month commitment, the pillar will not get maintained. Pillars without owners decay; the decay is invisible until the traffic drop is unrecoverable. + +--- + +## Worked example: B2B SaaS + +The brand is a feature-flag platform competitor (DR 45). Considering a pillar on "feature flag rollout strategies." + +- Volume: 2,400 combined monthly searches across the cluster. ✓ +- Facets: 14 listed (rollout strategies, naming conventions, lifecycle, governance, kill switches, technical debt, multi-environment, A/B testing integration, etc.). ✓ +- Commercial: pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes LaunchDarkly (DR 78), Statsig (DR 65), and several DR 60+ blogs. Tight but not impossible at DR 45 with strong cluster support. ✓ (with effort) +- Commitment: PM and content lead jointly own; renewal review every 12 months. ✓ + +Decision: pillar candidate. Plan a 12-cluster hub. + +--- + +## Worked example: ecommerce + +A direct-to-consumer skincare brand (DR 38). Considering a pillar on "retinol routine for beginners." + +- Volume: 8,500 combined monthly searches. ✓ +- Facets: 11 listed (intro, how to start, percentages, frequency, side effects, sun pairing, age considerations, mixing with other actives, sensitive-skin variant, pregnancy considerations, troubleshooting). ✓ +- Commercial: high; pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes The Ordinary blog, Paula's Choice, Reddit threads, dermatology sites. Mixed authority; achievable at DR 38 with cluster depth and original photography. ✓ +- Commitment: brand educator owns; refresh every 12 months. ✓ + +Decision: pillar. Plan a 10 to 12 cluster hub. + +--- + +## Worked example: services business + +A regional accounting firm (DR 28). Considering a pillar on "small business tax preparation." + +- Volume: 1,200 combined monthly searches. ✓ +- Facets: 12 listed (deductions, quarterly estimates, software comparison, when to hire vs DIY, common mistakes, audit risk, retirement contributions, payroll tax, sales tax, state-specific notes, multi-state operations, business structure choice). ✓ +- Commercial: very high; readers are local prospective clients. ✓ +- Competitive: top 10 includes Intuit, H&R Block, IRS itself, AICPA. Hard at DR 28. ✗ + +Decision: do not pursue this pillar. Instead, scope to a niche the brand can win: "small business tax preparation in [city]" with a pillar focused on the local-business audience and local SEO signals where DR matters less. + +--- + +## Worked example: media or publishing + +A career-focused publication (DR 55). Considering a pillar on "remote work productivity." + +- Volume: high. ✓ +- Facets: easily 15+. ✓ +- Commercial: ad-driven; pillar traffic monetizes through display and email signups. Indirect but real. ✓ +- Competitive: top 10 is moderately authoritative; achievable. ✓ +- Commitment: senior editor owns. ✓ + +Decision: pillar. Note the commercial-signal pattern is different from B2B SaaS or ecommerce; the funnel is impressions to audience growth rather than impressions to qualified lead. Same architecture, different success metrics. + +--- + +## When to walk away + +If three or more criteria fail, walk away from the pillar idea. If exactly one criterion fails (usually competitive feasibility), see whether a long-tail variant of the topic resolves the failed criterion. The "long-tail variant pivot" is the most common save: instead of "feature flags" (DR 78 incumbents), pick "feature flags for [niche]" (DR 50 incumbents) where the brand can compete. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md b/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md new file mode 100644 index 0000000..547a43d --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/topical-authority-signals.md @@ -0,0 +1,126 @@ +# Topical authority signals + +SEO and AEO/GEO signals at the hub level. Two-engine optimization framing. + +--- + +## Why hubs produce stronger signals than orphans + +Search engines and AI engines both read internal-link graphs and content patterns to infer topical authority. A hub with 12 connected pieces produces signals an orphan set cannot match: + +- Density of internal links on the topic. PageRank flows within the hub; pages reinforce each other. +- Comprehensive entity coverage across pieces. The hub mentions more named tools, methods, experts, and statistics than any single piece could. +- Repeated topical signal at scale. Multiple pieces with overlapping topical vocabulary, distinct facets, consistent structure. +- Crawl-rate compounding. Search engines crawl high-link-density clusters more frequently; AI engines re-index hubs more aggressively. + +Same total content volume; different architectural outcome. 12 orphans on the same topic produce scattered, weaker signals than a 12-piece hub. + +--- + +## SEO signals at the hub level + +### Internal-link graph density + +Google's PageRank algorithm flows authority through internal links. A pillar with 12 cluster pieces linking back to it concentrates PageRank on the pillar; the pillar in turn passes authority to clusters via top-down links. The graph shape compounds. + +Heuristic. Compare PageRank on a pillar before and after the cluster ships. Most teams see ranking improvements on the pillar within 3 to 6 months as the cluster matures. + +### Comprehensive entity coverage + +The hub mentions more named entities than any single page could: tools, methods, experts, datasets, frameworks. Search engines extract entity graphs at crawl time; comprehensive coverage signals topical depth. + +The discipline. Each piece in the hub mentions the topic's required entities (entities the SERP top 10 share) and the gap entities (entities only 1 or 2 SERP results mention). The hub-level entity graph is the union across all pieces. + +### URL structure clarity + +The `/topic/cluster-piece/` pattern signals topical grouping. Crawlers follow the URL hierarchy and infer the hub structure even before parsing internal links. + +### Breadcrumb hierarchy + +BreadcrumbList schema tells crawlers the hub structure explicitly. Some SERPs surface breadcrumb URLs as rich-result enhancements. + +### Schema markup at scale + +Article, HowTo, FAQPage, BreadcrumbList schema across the hub. Each schema type passes additional structured data to crawlers. The hub is structured for extraction in a way that orphan content rarely is. + +### E-E-A-T signals + +Experience, Expertise, Authoritativeness, Trustworthiness. Google's quality framework. Hub-level E-E-A-T comes from: + +- Author credentials displayed on every piece (with Person schema) +- Expertise demonstrated through depth and accuracy +- Authoritativeness signaled by entity coverage and citations +- Trustworthiness signaled by clear authorship, last-updated dates, and corrections to prior work when relevant + +E-E-A-T is not a discrete signal; it is the aggregate of many small signals. Hubs accumulate E-E-A-T faster than orphans because the signals compound across pieces. + +--- + +## AEO and GEO signals at the hub level + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) cite content based on different patterns than traditional search ranking. Hubs serve AI engines as well as search engines if the right signals are present. + +### Answer-paragraph format under H2 headings + +40 to 60 word self-contained answers immediately following H2 questions. AI engines extract these as citation candidates. The pattern repeats across pillar and clusters; the hub becomes a structured set of citation-ready answers. + +### TL;DR section on pillars + +The pillar's TL;DR (150 to 250 words) is the most-cited section by AI engines. Place it at the top, make it self-contained, write it as the canonical summary. + +### FAQPage schema + +AI engines (Perplexity especially) heavily cite FAQPage-marked content. Pair every pillar's FAQ section with FAQPage schema. Cluster pieces with genuine FAQs also benefit. + +### Specific statistics with cited sources + +"23% of feature flag rollouts include a kill switch (Feature Flag Survey 2025, n=412)" cites better than "many feature flag rollouts include a kill switch." Specific numbers with sources are higher-citation signals; vague qualifiers are lower-citation. + +### Named experts and named methods + +"As Adam Kalai noted in the original CUPED paper" cites better than "experts have shown." Named attribution earns citation; anonymous attribution does not. The hub should mention 5+ named experts or methods across pillar and clusters. + +### Distinctive POV + +AI engines preferentially cite content with a clear, attributable position. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. The hub's POV is the brand's editorial position; consistency across pieces reinforces attribution. + +--- + +## The two-engine optimization + +Pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +Both reward depth. Search engines reward comprehensive treatment of a topic. AI engines reward citation-ready depth. Same content; different extraction. + +Both reward structure. Search engines parse heading hierarchy for ranking. AI engines parse heading hierarchy for citation extraction. Same structure; different use. + +Both reward entity coverage. Search engines use entities for topical relevance. AI engines use entities for retrieval and citation. Same entities; different scoring. + +Both reward freshness. Search engines reward recent updates. AI engines re-index recently-updated content more aggressively. Same updates; different cadence. + +The implication. Optimizing for AEO/GEO does not trade off against SEO. The hub architecture that earns search rankings is the same architecture that earns AI citations. Teams that treat them as separate optimizations under-invest in both. + +--- + +## Measuring topical authority signals + +Hub-level metrics worth tracking: + +Search-side: + +- Aggregate organic traffic to all pieces in the hub +- Average position for the pillar's primary keyword +- Number of cluster pieces ranking in top 10 for their target keywords +- Internal-link count per cluster piece (from inventory) +- Crawl frequency (Google Search Console) + +AI-side: + +- Brand mention rate from Profound, Frase, AirOps, or similar tools +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude) +- Top-cited pieces (which clusters get cited most often) +- AI crawler hit frequency (server logs, Profound Agent Analytics) + +The hub-level dashboard composes these metrics. Tracking at the hub level (not per piece) is what surfaces architecture-level patterns: which clusters drive traffic, which clusters drive citations, which clusters are dead weight. + +See the `seo-aeo-geo` skill for AEO/GEO program-level strategy. diff --git a/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md b/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md new file mode 100644 index 0000000..1b498c0 --- /dev/null +++ b/dist/pi/.agents/skills/pillar-content-architecture/references/url-structure-patterns.md @@ -0,0 +1,105 @@ +# URL structure patterns + +Subfolder vs subdomain decision, slug conventions, breadcrumbs, the /blog/ trap. + +--- + +## Subfolder vs subdomain + +The default for hubs is subfolder. Subdomain has narrow valid use cases. + +Subfolder pattern. `example.com/feature-flag-rollout/` for the pillar; `example.com/feature-flag-rollout/kill-switches/` for cluster pieces. Both pillar and cluster live on the same domain authority; PageRank flow is consolidated; the hub compounds within the brand's existing SEO equity. + +Subdomain pattern. `docs.example.com`, `community.example.com`, `support.example.com`. Used when the property is genuinely distinct (different audience, different content type, different team ownership). Subdomains receive less of the parent domain's authority signal in most analyses; do not split a hub across subdomains without a strong reason. + +Decision rule. Pillar plus cluster always on the same subdomain as the rest of the marketing content. If the brand's marketing content lives at `example.com`, the hub lives at `example.com/[hub]/`. Splitting the hub onto a subdomain treats the hub as a separate property, which is almost never correct. + +--- + +## Hub URL pattern + +The pattern: `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. + +Why this pattern. The URL itself signals topical grouping. Crawlers see the path structure and infer that pages under `/feature-flag-rollout/` belong to a topical hub. Readers see the breadcrumb in the URL and know where they are. + +The /blog/ alternative. `/blog/feature-flag-rollout/` and `/blog/kill-switches/`. This works structurally; the pieces still rank. But the hub signal is weaker because the URL groups by content type (blog) rather than by topic. Two unrelated blog posts share the `/blog/` path; nothing in the URL says "kill-switches is part of the feature-flag-rollout hub." + +The fix when migrating off /blog/. Change the URL pattern via 301 redirects from old to new. Lose some short-term ranking equity during the redirect; gain long-term hub-signal clarity. The migration is worth it for major hubs; not worth it for smaller content sets. + +--- + +## Slug conventions + +Short, descriptive, keyword-aware but not stuffed. + +Good: `/feature-flag-rollout/kill-switches/` + +Bad: `/feature-flag-rollout/the-ultimate-guide-to-implementing-kill-switches-in-feature-flag-rollouts-2026/` + +Why short. Long slugs read as keyword-stuffed and break in social shares, email previews, and conversational mentions. Search engines do not need every keyword in the URL; they parse the page content. + +Why descriptive. The slug should make sense as a standalone string. `/feature-flag-rollout/kill-switches/` is self-describing; `/post-1247/` is not. + +Keyword-aware. Include the primary keyword for the cluster piece. Do not include the supporting cluster keywords (those go in the page content, not the URL). + +Date-free. Avoid dates in slugs (`/2026-rollout-guide/`). Dated slugs anchor the piece in time; refreshing the piece in 2027 is awkward. Pieces with date-relevant content (annual reports, year-in-review) are exceptions. + +Hyphens, not underscores. Search engines treat hyphens as word separators; underscores as part of one word. `kill-switches` reads as two words; `kill_switches` reads as one. + +Lowercase. Mixed-case URLs cause case-sensitivity confusion across servers and create duplicate-content issues. + +--- + +## Breadcrumb structure + +Breadcrumbs surface the hub structure in the page UI and the page schema. The pattern: + +`Home > Hub topic > Cluster piece` + +In the UI, breadcrumbs typically render as a small horizontal nav above the title. In schema, BreadcrumbList markup tells crawlers the path. + +Why breadcrumbs help. Readers see they are in a hub and can navigate up. Crawlers parse the BreadcrumbList schema and reinforce the hub hierarchy. Some SERPs also surface breadcrumb URLs in rich results. + +Breadcrumb anti-pattern. Breadcrumbs that show URL segments instead of human-readable labels. `Home > /feature-flag-rollout > /kill-switches` is the wrong format. Use the hub's display name and the cluster piece's title, not the URL slug. + +Schema example. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +The third item omits "item" because breadcrumbs typically do not link to the current page. + +--- + +## The /blog/ trap + +The symptom. The team's content all lives at `/blog/[slug]/` because that is how the CMS is configured. Pillar and cluster live alongside unrelated blog posts in the same flat URL space. + +The diagnosis. The CMS folder defaulted to `/blog/`. Nobody changed it because changing CMS routing is non-trivial. Hub structure exists in the editorial team's head but not in the URL. + +The cost. Hub signal is weakened; PageRank flow is less topically concentrated; readers cannot tell from the URL that a piece is part of a hub. + +The fix. Change CMS routing to support topic-based subfolders. Migration via 301 redirects from old `/blog/` URLs to new `/[hub]/` URLs. Take a short-term ranking hit during redirect; gain long-term hub authority. + +The "do not migrate" exception. If the existing `/blog/` URL structure is generating significant traffic and the hub investment is small, the migration may not pay back. Score the migration cost against the hub's commercial value; migrate only when the hub justifies it. + +--- + +## Multilingual or multi-region URL patterns + +Hubs that span languages or regions add another structural decision. The two main patterns: + +Subfolder per locale. `example.com/en/[hub]/`, `example.com/de/[hub]/`. Cleanest for SEO consolidation; clearest for crawlers. + +ccTLD per region. `example.de/[hub]/`, `example.fr/[hub]/`. Stronger for regional ranking but splits domain authority. + +The decision usually depends on the brand's existing internationalization choice; the hub follows the existing pattern. Do not use the hub launch as the moment to switch internationalization strategies. diff --git a/dist/pi/.agents/skills/pm-spec-writing/SKILL.md b/dist/pi/.agents/skills/pm-spec-writing/SKILL.md new file mode 100644 index 0000000..abb72ad --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/SKILL.md @@ -0,0 +1,226 @@ +--- +name: pm-spec-writing +description: "Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks." +category: product +catalog_summary: "PRDs, user stories, acceptance criteria, dev briefs" +display_order: 1 +--- + +# PM Spec Writing + +Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work. + +--- + +## When to use + +- Translating an idea into a buildable feature spec +- Writing a PRD or product requirement document +- Filing a bug report that someone else can act on +- Scoping a project before kickoff +- Prioritizing a backlog of feature requests +- Writing acceptance criteria for an existing feature +- Breaking a large initiative into shippable increments + +## When NOT to use + +- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`) +- Code review or debugging existing code (use `code-review-web`) +- Design decisions for a feature already specced (use `design-standards`) +- User research to validate an idea (use `ux-research`) + +--- + +## Required inputs + +- The idea, request, or problem being addressed +- The audience or user affected +- Any existing constraints (stack, deadlines, dependencies) +- The success metric (how will you know it worked?) + +If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness. + +--- + +## The framework: 4 phases + +Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary. + +### Phase 1: Clarify the idea + +Before any spec, answer four questions. If any answer is "I don't know," go back to the user. + +1. What user problem does this solve? Not "what does it do." The problem comes first; the feature is the proposed solution. +2. Who specifically benefits? Be precise. "Users" is not specific. "First-time visitors who don't convert" is. +3. What is the success metric? How will you know it worked? Pick one primary metric. +4. Why now? What changed that makes this the right time to build it? If "nothing changed," it might not be the right time. + +### Phase 2: Scope by impact and effort + +Plot every candidate idea on the impact/effort grid: + +``` +HIGH IMPACT / LOW EFFORT Ship immediately + Examples: copy fixes, contrast fixes, meta tags, + broken links, missing alt text, redirects + +HIGH IMPACT / HIGH EFFORT Plan and batch + Examples: new page type, new feature, schema overhaul, + major redesign, new integration + +LOW IMPACT / LOW EFFORT Nice-to-have batch + Examples: tooltip improvements, minor copy polish, + cosmetic UX touches + +LOW IMPACT / HIGH EFFORT Skip or defer indefinitely + Examples: rebuilding what already works, exotic + edge case features, premature optimization +``` + +This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions. + +### Phase 3: Write the spec + +Three formats based on the type of work. + +#### Format A: Feature spec (for new features) + +``` +TITLE: [Specific, action-oriented] + +PROBLEM +[1-2 sentences. The user problem and current state.] + +USERS +[Who specifically benefits. Be precise about the user segment.] + +PROPOSAL +[1 paragraph. The proposed solution. Stay at the conceptual level.] + +USER STORIES +- As a [user type], I want to [action], so that [outcome] +- As a [user type], I want to [action], so that [outcome] + +ACCEPTANCE CRITERIA +- Given [context], when [action], then [expected outcome] +- Given [context], when [action], then [expected outcome] + +OUT OF SCOPE +[What this spec explicitly does NOT cover. Important for scope control.] + +DEPENDENCIES +[Other systems, APIs, designs, content needed before this can ship.] + +SUCCESS METRIC +[The one primary metric that tells us this worked. With current baseline if known.] + +ESTIMATED EFFORT +[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)] + +PRIORITY +[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog] +``` + +#### Format B: Dev brief (for handing to a developer or AI agent) + +For tactical, ready-to-build work. Lighter than a full spec. + +``` +CONTEXT: [1-2 sentences explaining why this matters] + +TASK: [Specific files, exact changes needed] + +CONSTRAINTS: [What must NOT change, what to preserve] + +VERIFY: [Exact steps to confirm the work is done correctly] +``` + +The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means. + +#### Format C: Bug report + +``` +URL or context: [Where it happens] + +Symptom: [What the user sees or experiences] + +Expected: [What should happen instead] + +Steps to reproduce: +1. [Specific step] +2. [Specific step] +3. [Specific step] + +Hypothesis: [Likely root cause if known] + +Files to investigate: [Likely files involved if known] + +Priority: + P0 - blocking critical user flow, ship immediately + P1 - degrades UX significantly, fix this sprint + P2 - minor issue, fix when convenient + P3 - nice-to-have improvement + +Browser/device: [If reproducibility might be browser-specific] +``` + +### Phase 4: Sequence and ship + +Specs without sequencing become dust on a shelf. + +For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate. + +For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels. + +--- + +## Workflow + +1. Clarify. If the idea is vague, ask the four phase-1 questions before proceeding. +2. Scope. Plot the work on the impact/effort grid. +3. Pick the right format. Feature spec for new features, dev brief for tactical work, bug report for defects. +4. Write the spec. Use the template format. Fill in every section. Empty sections are flags. +5. Define done. Verify steps must be unambiguous. "Test it" is not a verify step. +6. Get buy-in. Walk through the spec with whoever will build it before they start. +7. Sequence. Identify the smallest shippable increment. + +--- + +## Failure patterns + +- Specs that describe solutions before problems. Always start with the user problem. The solution is downstream. +- Specs without a success metric. Without a metric, you cannot tell if the feature worked. +- Acceptance criteria that are not testable. "User experience is improved" is not testable. "User completes signup in under 60 seconds" is. +- Specs that include the "how" instead of the "what." Implementation details belong in the dev brief, not the spec. The spec is the desired outcome. +- No "out of scope" section. Without explicit boundaries, scope creeps. +- Bug reports without reproduction steps. Cannot be acted on. Always include steps. +- Verify steps that are vague. "Make sure it works." Useless. Must be specific actions with observable outcomes. +- Skipping the smallest-shippable-increment exercise. Leads to 6-month projects that should have been 2-week experiments. + +--- + +## Output format + +Output is one of three formats based on work type, all in markdown: + +- `spec-[feature-name].md` for feature specs +- `brief-[task-name].md` for dev briefs +- `bug-[summary].md` for bug reports + +For larger initiatives, group related specs in a folder: +``` +specs/ + initiative-name/ + spec-feature-1.md + spec-feature-2.md + brief-task-1.md + README.md (overview and sequencing) +``` + +--- + +## Reference files + +- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template. +- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work. +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW. diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md b/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md new file mode 100644 index 0000000..289ffef --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/dev-brief-template.md @@ -0,0 +1,207 @@ +# Dev Brief Template + +A dev brief is the lightweight version of a spec. Used for tactical work that does not need a full PRD: bug fixes, copy changes, small feature additions, infrastructure tweaks. + +The brief is structured to be handed directly to a developer or AI agent. They should be able to act on it without follow-up questions. + +--- + +## Template + +``` +TASK: [One-sentence summary of what to do] + +CONTEXT +[1 to 2 sentences. Why this matters. What problem it solves.] + +WHAT TO DO +[Specific changes. List the exact files (if known), the exact behavior to change, the exact copy to update. Be unambiguous.] + +CONSTRAINTS +[What must NOT change. What to preserve. What's out of bounds.] + +VERIFY +[Exact steps to confirm the work is done correctly. Each step should produce an observable outcome that proves the change worked.] + +DEPENDENCIES +[Anything that must be done first, or that this depends on.] + +PRIORITY +[P0 / P1 / P2 / P3 with one-line reason] + +ESTIMATED TIME +[Minutes or hours - not days. If it would take days, write a feature spec instead.] +``` + +--- + +## Example: Bug fix brief + +``` +TASK: Fix the broken submit button on the contact form + +CONTEXT +Users reported that the contact form submit button does not respond on mobile Safari. +This is blocking lead capture from a major traffic source. + +WHAT TO DO +- Investigate components/forms/ContactForm.tsx +- Check the onClick handler and form submission logic +- The issue is likely related to a recent change to the button onClick handler; + check git log for the most recent commit touching this component +- Fix so submit fires on tap as well as click + +CONSTRAINTS +- Do not change any other forms in the codebase +- Do not modify the form validation logic +- Preserve the existing visual design of the button + +VERIFY +1. Open contact form on mobile Safari (or device-mode in browser) +2. Fill required fields with valid data +3. Tap submit button +4. Confirm form submits and success message displays +5. Repeat on Chrome and Firefox to ensure no regression +6. Check browser console for errors after submit + +DEPENDENCIES +None. Self-contained fix. + +PRIORITY +P1 - blocking lead capture from primary traffic source + +ESTIMATED TIME +30 to 60 minutes +``` + +--- + +## Example: Copy change brief + +``` +TASK: Update homepage hero copy to match new positioning + +CONTEXT +The marketing team has finalized the new positioning statement. +The current hero copy is from the previous brand iteration and needs updating. + +WHAT TO DO +File: pages/index.tsx (or app/page.tsx in App Router) + +Change the hero H1 from: + "The all-in-one platform for modern teams" +To: + "Move work forward without moving the meeting" + +Change the hero subheadline from: + "Streamline your workflow with our innovative collaboration suite" +To: + "Async-first project management for distributed teams that ship." + +Change the primary CTA button text from: + "Get started" +To: + "Start free trial" + +CONSTRAINTS +- Do not change the hero image +- Do not change the secondary CTA +- Preserve all existing styling and component structure + +VERIFY +1. Reload the homepage in a browser +2. Confirm new H1, subheadline, and CTA text display correctly +3. Confirm visual layout is unchanged (no new layout shifts) +4. Confirm responsive behavior on 375px viewport +5. Run a Lighthouse pass to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P1 - aligned with brand launch on [date] + +ESTIMATED TIME +15 to 30 minutes +``` + +--- + +## Example: Small feature brief + +``` +TASK: Add an estimated reading time to blog post pages + +CONTEXT +Users have asked for an indication of how long a post takes to read. +Improves perceived value and helps users decide whether to start reading. + +WHAT TO DO +- Calculate reading time as word count / 200 words per minute, rounded up +- Display below the post title, alongside the publish date +- Format: "5 min read" (with the minute count appropriate to length) +- Apply to all blog post pages (single post template) + +Suggested implementation: +- Compute server-side from the post body content +- Add to the post component's metadata section +- Style consistently with the existing publish date + +CONSTRAINTS +- Must work for posts of any length (test 1 minute to 30+ minute posts) +- Must not affect SEO (e.g., no JS-rendering for crawlers) +- Must not regress page load performance + +VERIFY +1. Open 3 different blog posts of varying length +2. Confirm reading time displays correctly for each +3. Verify the calculation is right (count words manually for a short post) +4. Check the rendered HTML to confirm the value is server-rendered, not JS +5. Confirm visual styling matches the publish date treatment +6. Run Lighthouse to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P2 - nice user enhancement, no urgency + +ESTIMATED TIME +1 to 2 hours including QA +``` + +--- + +## What makes a good brief + +Context answers "why am I doing this?" Without it, the implementer cannot make good judgment calls. + +What to do is specific. Names files when known. Quotes exact copy when copy is changing. Describes desired behavior unambiguously. + +Constraints prevent scope creep. Especially for AI agents who tend to "improve" things outside the task. + +Verify is the most-skipped section and the most important. Each verify step must be: +- Observable (you can see whether it passed or failed) +- Specific (no "make sure it works") +- Sufficient (if all verify steps pass, the work is genuinely done) + +Dependencies prevent the implementer from starting work that's blocked. + +Priority sets expectations on order. + +Estimated time sets expectations on effort. Briefs are for work measured in minutes to a few hours. Days-long work should be a feature spec. + +--- + +## When NOT to use a dev brief + +If the work has any of the following, write a feature spec instead: + +- Multiple stakeholders need to weigh in +- The user-facing behavior needs design review +- The change affects multiple parts of the system +- The estimate exceeds 1 day of work +- The success metric is non-obvious +- The work cannot be verified by a few specific steps + +A dev brief is for "do this exact thing." A feature spec is for "build this product capability." diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md b/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md new file mode 100644 index 0000000..48c4447 --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/feature-spec-template.md @@ -0,0 +1,192 @@ +# Feature Spec: [Feature Name] + +Author: [Name] +Date: [YYYY-MM-DD] +Status: [Draft / In Review / Approved / In Development / Shipped] +Target ship: [Date or sprint] + +--- + +## TL;DR + +[2 to 3 sentences. What this is, who it's for, why it matters. If a stakeholder reads only this section, they should understand the proposal.] + +--- + +## Problem + +[1 to 2 paragraphs. The user problem. The current state and why it's inadequate. Include data if available (analytics, support tickets, user research quotes).] + +### Evidence + +- [Specific data point or research finding] +- [Specific data point or research finding] +- [Specific data point or research finding] + +--- + +## Users + +Primary user: [Specific user segment that benefits most] + +Use cases: +1. [Specific scenario where this user encounters the problem] +2. [Specific scenario] +3. [Specific scenario] + +Secondary users: [Other segments affected] + +Anti-users: [Segments this feature is NOT for; helps prevent scope creep] + +--- + +## Proposal + +[1 paragraph at the conceptual level. The solution, not the implementation. Stay at "what" not "how".] + +### How it works (high level) + +[3 to 5 bullets describing the user experience flow. Still high level; not implementation details.] + +1. [User action] +2. [System response] +3. [User action] +4. [System response] + +--- + +## User stories + +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. + +--- + +## Acceptance criteria + +The feature ships when ALL of these are true. + +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Given [context], when [action], then [expected outcome] +- [ ] [Additional criteria] +- [ ] [Additional criteria] + +Each criterion must be observable and testable. If you cannot verify it with a specific check, rewrite it. + +--- + +## Out of scope + +[Explicit boundaries. What this spec does NOT cover. Critical for scope control.] + +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] + +--- + +## Dependencies + +### Required before development can start +- [ ] [Design completed and approved] +- [ ] [API contracts defined] +- [ ] [Content delivered] +- [ ] [Legal/compliance review if applicable] + +### External systems or services +- [System or service]: [What we depend on] +- [System or service]: [What we depend on] + +### Team dependencies +- Design: [What's needed and who owns it] +- Engineering: [Specific resources and timeline] +- Content: [If applicable] +- Marketing: [If launch-related] + +--- + +## Success metric + +Primary metric: [The one metric that tells us this worked] + +Current baseline: [If known] + +Target: [What success looks like quantitatively] + +Measurement window: [When and for how long we measure] + +Secondary metrics (signals to watch): +- [Metric] - [why it matters] +- [Metric] - [why it matters] + +Negative signals (what would tell us this hurt): +- [Metric] - [threshold for concern] +- [Metric] - [threshold for concern] + +--- + +## Estimated effort + +Size: [Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (multiple sprints)] + +Breakdown: +- Design: [hours/days] +- Frontend: [hours/days] +- Backend: [hours/days] +- QA: [hours/days] +- Content: [hours/days] +- Total: [estimated] + +--- + +## Priority + +P0 Launch blocker - must ship before [event/launch] +P1 Next sprint - high impact, addressable now +P2 Within quarter - valuable but not urgent +P3 Backlog - nice-to-have, no commitment + +This spec: [P0 / P1 / P2 / P3] + +Reasoning: [Why this priority] + +--- + +## Open questions + +[Things that need to be decided before development can start, or before the feature can ship.] + +- [ ] [Question] - Owner: [Who decides] - Decision needed by: [Date] +- [ ] [Question] - Owner: [Who decides] - Decision needed by: [Date] + +--- + +## Risks and mitigations + +\| Risk \| Likelihood \| Impact \| Mitigation \| +\|---\|---\|---\|---\| +\| [Risk description] \| High/Med/Low \| High/Med/Low \| [How we'll mitigate] \| +\| [Risk description] \| \| \| \| + +--- + +## Smallest shippable increment + +MVP: What is the simplest version that delivers user value? + +[Description of the MVP. Shippable in 1 to 2 weeks for most features. If you can't describe an MVP that fits, the feature is too big and should be split.] + +Future iterations (NOT in MVP, may come later): +- [Iteration 1] +- [Iteration 2] +- [Iteration 3] + +--- + +## Changelog + +\| Date \| Author \| Change \| +\|---\|---\|---\| +\| YYYY-MM-DD \| [Name] \| Initial draft \| diff --git a/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md b/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md new file mode 100644 index 0000000..0fb7f3d --- /dev/null +++ b/dist/pi/.agents/skills/pm-spec-writing/references/prioritization-frameworks.md @@ -0,0 +1,219 @@ +# Prioritization Frameworks + +Beyond the simple impact/effort grid, there are several frameworks for prioritizing work. Each is useful in different situations. None is universally correct. + +--- + +## Impact / Effort matrix + +The simplest and most common. + +How it works: plot every candidate on a 2x2 grid. + +``` + Low Effort High Effort + +High Impact Quick wins Major projects + (Ship now) (Plan and batch) + +Low Impact Backlog batch Skip or defer + (When time allows) (Reconsider) +``` + +Strengths: Fast. Forces blunt judgment. Useful for triage. + +Weaknesses: Subjective. "Impact" and "effort" are estimates that get inflated. + +When to use: Triage of a long list. Initial sorting. + +--- + +## RICE + +A weighted scoring method that produces a numeric priority score. + +How it works: + +``` +RICE Score = (Reach × Impact × Confidence) / Effort +``` + +- Reach: How many users this affects per period (e.g., per quarter). Use real numbers. +- Impact: The per-user impact, scored on a fixed scale: + - 3 = Massive (transformative) + - 2 = High (significant lift) + - 1 = Medium (modest lift) + - 0.5 = Low (minor lift) + - 0.25 = Minimal (barely noticeable) +- Confidence: How certain you are of the reach and impact estimates, as a percentage. + - 100% = high confidence (data-backed) + - 80% = medium confidence (some evidence) + - 50% = low confidence (mostly intuition) +- Effort: Person-months (or person-weeks for smaller work). + +Example: + +A new onboarding flow: +- Reach: 5,000 new users per quarter +- Impact: 1 (modest improvement to activation) +- Confidence: 80% +- Effort: 2 person-months + +RICE = (5000 × 1 × 0.8) / 2 = 2,000 + +A bug fix on a rarely-used page: +- Reach: 50 users per quarter +- Impact: 2 (significant for those affected) +- Confidence: 100% +- Effort: 0.25 person-months + +RICE = (50 × 2 × 1) / 0.25 = 400 + +The onboarding flow scores higher. + +Strengths: Numeric. Forces explicit estimates. Surfaces the math behind judgment. + +Weaknesses: Garbage-in-garbage-out. Reach and impact estimates can be wildly wrong. + +When to use: Comparing across many candidate features. When stakeholders disagree on priority. + +--- + +## MoSCoW + +Categorical, used for release scoping. + +How it works: every item is one of four: + +- Must have - non-negotiable for this release +- Should have - important but not critical +- Could have - nice if time allows +- Won't have - explicitly out of scope (this release) + +Example for a redesign launch: + +- Must: New navigation, mobile responsive, all P0 pages migrated +- Should: New blog template, updated forms +- Could: New illustrations on lower-traffic pages +- Won't: Internationalization (deferred to phase 2) + +Strengths: Clear scope boundaries. Forces explicit "won't have" decisions, which prevent scope creep. + +Weaknesses: Not a framework for relative priority within categories. + +When to use: Defining the scope of a release. Cutting features when timeline pressure hits. + +--- + +## Cost of Delay / Weighted Shortest Job First + +A framework from lean product development. Optimizes for delivering value sooner. + +How it works: + +``` +Priority = Cost of Delay / Job Duration +``` + +- Cost of Delay: What is the cost (in revenue, risk, customer impact) of NOT doing this for one more period? +- Job Duration: How long will this take? + +The work with the highest "Cost of Delay per unit time" gets done first. + +Example: + +A revenue-impacting bug: +- Cost of Delay: $5,000 per week of lost conversions +- Duration: 1 week +- Priority score: 5,000 + +A large feature: +- Cost of Delay: $20,000 per week of unrealized revenue +- Duration: 12 weeks +- Priority score: 1,667 + +Even though the feature has higher absolute cost of delay, the bug ships first because it delivers value faster. + +Strengths: Captures urgency. Useful for revenue-sensitive decisions. + +Weaknesses: Cost of Delay is hard to estimate. + +When to use: Operational backlogs. Revenue-sensitive features. + +--- + +## Value vs Effort with strategic alignment + +A 3-axis variant for when strategic fit matters more than raw impact. + +How it works: score each candidate on: + +- Value (1 to 5) +- Effort (1 to 5, inverted - 5 means low effort) +- Strategic fit (1 to 5) + +Composite score: Value + Effort + Strategic fit. + +Candidates with the highest composite score win. + +Strengths: Captures that some valuable work is wrong for the company right now. + +Weaknesses: Three axes is more complex than most teams can sustain. + +When to use: When the team is being pulled toward locally-valuable work that does not advance the strategy. + +--- + +## The "next thing" framework + +The simplest, for solo founders or very small teams. + +How it works: ask one question: + +> "What is the single most important thing I could ship in the next two weeks?" + +Ship it. Then ask the question again. + +Strengths: Maximum focus. Avoids analysis paralysis. + +Weaknesses: Misses opportunities to batch related work. Susceptible to recency bias. + +When to use: Solo work. When the backlog is short. When velocity matters more than precision. + +--- + +## Choosing a framework + +\| Situation \| Framework \| +\|---\|---\| +\| Long backlog, need triage \| Impact / Effort matrix \| +\| Comparing features for the next quarter \| RICE \| +\| Defining a release scope \| MoSCoW \| +\| Revenue-sensitive operations work \| Cost of Delay / WSJF \| +\| Strategic misalignment risk \| Value + Effort + Strategic fit \| +\| Solo founder, weekly cadence \| "Next thing" \| + +The frameworks are tools. The output is a prioritized list. If the list is helpful and team agrees, the framework worked. If it's not, try another framework or revisit the inputs. + +--- + +## Common pitfalls + +- Framework theater. Spending more time on the framework than the work. Pick one. Move on. +- Estimate inflation. Engineers underestimate effort by 2x. PMs overestimate impact by 3x. Calibrate over time. +- Static prioritization. A one-time sort that never gets revisited. Re-prioritize at least monthly. +- Ignoring sunk cost dynamics. Just because you've worked on something for 3 months does not mean it deserves to ship. Cut your losses if the priority math no longer works. +- Optimizing the wrong metric. A framework's output is only as good as the metric you're optimizing for. Make sure that metric is correct. +- Treating the score as truth. A RICE score is a directional signal, not a verdict. Use judgment alongside the math. + +--- + +## Recommended default + +For most teams, the default is: + +1. Impact / Effort matrix for triage and backlog grooming +2. RICE for comparing feature candidates within a quarter +3. MoSCoW for release scoping when timeline is fixed + +That covers 90 percent of prioritization decisions a typical product team faces. diff --git a/dist/pi/.agents/skills/product-analytics-setup/SKILL.md b/dist/pi/.agents/skills/product-analytics-setup/SKILL.md new file mode 100644 index 0000000..926677a --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/SKILL.md @@ -0,0 +1,308 @@ +--- +name: product-analytics-setup +description: "How to actually instrument product analytics correctly. Event taxonomy, property design, naming conventions, schema versioning, identity stitching, funnel design, retention cohorts, North Star metric selection, dashboard hygiene, instrumentation debt, and the failure modes that produce data nobody trusts. Triggers on product analytics setup, event taxonomy, tracking plan, instrumentation, schema versioning, North Star metric, retention cohorts, funnel design, naming conventions, instrument new feature, audit existing analytics, dashboard reconciliation, instrumentation debt, Mixpanel setup, Amplitude setup, PostHog setup, warehouse-native analytics. Also triggers when the team has data but cannot trust it, or when designing instrumentation for a new feature, or when auditing an existing setup that has drifted." +category: product +catalog_summary: "Instrument product analytics correctly: event taxonomy, properties, naming conventions, schema versioning, funnels, retention cohorts, North Star selection, and the instrumentation debt that compounds without discipline" +display_order: 8 +--- + +# Product Analytics Setup + +A senior PM and analyst's playbook for instrumenting product analytics correctly the first time. + +Most product analytics setups are some combination of inherited mistakes, dashboard sprawl, and events nobody trusts. The team launches a new feature; instrumentation gets bolted on under deadline pressure; naming drifts; properties are inconsistent; six months later nobody can answer simple questions because the answer depends on which event you trust. + +This skill is the discipline that prevents that. It assumes you have answered the strategic questions about what to measure (see `analytics-strategy`). It assumes you have a tool connected (Mixpanel, Heap, PostHog, Amplitude, or warehouse-native via BigQuery, Snowflake, or dbt). The hard part is the systematic execution: naming conventions, property design, schema versioning, funnel construction, cohort definitions, retention measurement. + +When to use this skill: setting up product analytics from scratch, auditing an existing instrumentation, fixing a "we have data but cannot trust it" problem, or designing instrumentation for a new feature. + +--- + +## What this skill is for + +This skill spans instrumentation execution. It does not cover measurement strategy (use `analytics-strategy`), experimentation result interpretation (use `experimentation-analytics`), paid media analytics (use `ads-performance-analytics`), or platform decisions (use `experimentation-platform-orchestrator`). Pair this skill with the relevant integrations microsite for your specific tool. + +The clean distinction from analytics-strategy. That skill (Growth category) is strategic: what to measure and why, KPI hierarchy, dashboard architecture, attribution models. This skill (Product category) is execution: how to actually instrument the product correctly. The two compose. Read analytics-strategy first to decide what matters; read this skill to instrument it. + +--- + +## The instrumentation hierarchy + +The mental model. Every analytics setup is a stack of layers. Each layer depends on the one below it being correct. + +- Events are the atomic facts: `user_signed_up`, `checkout_completed`, `feature_x_used`. +- Properties describe events: who, what, where, when, with what context. +- Identities map events to people: `anonymous_id`, `user_id`, `account_id`. +- Cohorts are filters across events: "users acquired via paid in March." +- Funnels are sequences of events: signup, then activated, then first paid action. +- Retention measures repeat behavior: signups still active at week N. + +You cannot construct higher levels without correct lower levels. Garbage events produce garbage funnels. The discipline is bottom-up. Most "we have data but cannot trust it" problems trace back to the bottom two layers. + +--- + +## Event taxonomy design + +Three rules for event design. + +1. Past tense, action-oriented. `checkout_completed`, not `checkout_complete` or `completing_checkout`. Past tense reads as "this happened" rather than as a state. +2. Object-action format. Noun then verb. `video_played`, `form_submitted`, `email_opened`. Reading the event name aloud should describe what happened. +3. Granular but not redundant. Track distinct user actions, not button clicks. Fire `checkout_completed` once at the moment of completion, not `submit_button_clicked` plus `checkout_completed`. UI events are noise; semantic events are signal. + +The verbs vs states trap. + +- Verbs ARE events. `checkout_completed`, `subscription_canceled`, `account_upgraded`. +- States are NOT events; they are properties. `user_status: active` is a property on the user, not an event. Setting state via events ("status_changed_to_active") is a code smell that produces double-counting. + +How many events to design. Thirty to fifty events is the sweet spot for a typical SaaS product. Below twenty means under-instrumented; above one hundred almost always means tracking UI noise or duplicating events in different formats. + +Detail and a canonical event spec in [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md). + +--- + +## Property design: event-level vs user-level + +Two property types, treated separately. + +Event-level properties describe THIS event. The `checkout_completed` event has properties like `cart_value`, `item_count`, `payment_method`, `discount_code`. They live on the event payload and are immutable once fired. + +User-level properties describe the USER over time. `subscription_tier`, `lifetime_value`, `acquisition_channel`. Set them once on the user profile; the analytics tool joins them onto every event the user fires. They update over time as the user changes. + +The trap. Putting user-level properties on every event. Do not track `subscription_tier` on every event payload; set it once on the user profile and rely on the join. Putting it on the event creates payload bloat, schema drift when the value changes, and reporting confusion when a user upgrades mid-session. + +Data type discipline. + +- Strings for enums: status, tier, channel, region. Enumerable values where the set is bounded. +- Numbers only for actual numbers: count, value, duration, score. Never use strings for numeric data ("free trial day 7" should be `trial_day: 7`). +- Booleans for actual booleans: `is_admin`, `has_trial`, `is_new_user`. Two values; nothing else. +- Timestamps in ISO 8601, always. Always. The number of bugs caused by inconsistent date formats is uncountable. +- Arrays rarely. An array property is usually a sign you should split into multiple events with one item per event. + +Worked example in [`references/property-design-patterns.md`](references/property-design-patterns.md) showing right and wrong design for a `product_viewed` event. + +--- + +## Naming conventions + +Pick ONE convention and enforce it. Three conventions worth picking. + +- snake_case for events and properties: `user_signed_up`, `cart_value`. Most platforms default to this; pushback is rarely worth it. +- Object-action format for events: `user_signed_up`, `video_played`. Reading the name should describe what happened. +- Verb-noun for user properties (or just nouns): `subscription_tier`, `is_admin`, `last_active_at`. + +What NOT to do. + +- Mixed case across events. `user_signedUp`, `User Signed Up`, `userSignedUp` all coexisting in the same project. Pick one and migrate. +- Spaces in event or property names. "Sign Up Completed" breaks every URL-encoding scenario and confuses every tool. +- Inconsistent verbs. `user_signed_up` plus `completedCheckout` plus `VIEW_PRODUCT` in the same project means nobody can predict an event name without looking it up. +- Brand names in event names. `mailchimp_email_opened` ages badly when you switch to Customer.io. + +The naming convention reference file provides a complete style guide. Cite it in your team's data contract. + +Detail in [`references/naming-convention-reference.md`](references/naming-convention-reference.md). + +--- + +## Schema versioning + +Schema changes are inevitable. The pattern. + +Additive changes are safe. New event, new property on an existing event, new value in an enum. Just ship. Existing dashboards continue to work. + +Breaking changes require migration. Renamed event, removed property, changed property type, narrowed enum. These break dashboards downstream; the migration plan is part of the change. + +Versioning patterns. + +- Append `_v2` to events when semantics change. `checkout_completed_v2` fires alongside `checkout_completed` during a transition. +- Keep old events firing during the transition (90 days is typical). Both versions fire; analytics queries gradually migrate to v2. +- Migrate dashboards to v2 before retiring v1. Then deprecate v1 explicitly with a documentation note. + +The data contract idea. + +- Document the canonical schema in code: TypeScript interface, JSON Schema, or Protobuf definition. +- Code review every schema change. Schema is product, not afterthought. +- CI lint rejects schema violations before they hit production. The deploy that adds an event with the wrong type fails the build. + +Detail in [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md). + +--- + +## Funnel design + +Funnels measure progression through a sequence. Four rules. + +1. Order matters. A then B then C is a different funnel from B then A then C. The platform will compute different conversion rates depending on order. +2. Time windows matter. Most funnels use a 1 to 30 day window from the first event. Document the window explicitly; "users who completed signup AND activated" is meaningless without "within 14 days." +3. Drop-off interpretation is hard. Eighty percent of users dropping at step 2 might be the funnel design (audience is wrong), might be the audience (timing is wrong), or might be the product (genuine drop-off). Investigate before declaring. +4. The anchor event pattern. Every funnel starts with a high-intent action: signup, trial start, key feature use. Not a vanity event like `page_view` or `session_start`. Vanity-event-anchored funnels show 99% drop-off and tell you nothing. + +Common funnel mistakes. + +- Funnels that include events firing automatically. `session_started` happens for every visit; using it as a step inflates the denominator and makes the rest of the funnel meaningless. +- Funnels too long (10+ steps). Break into two or three shorter funnels. A 10-step funnel produces near-zero end-to-end conversion that is hard to interpret. +- Funnels with the same event in multiple positions. The platform handles this poorly; the analyst handles it worse. +- Mixing different time windows in one funnel. "Users who signed up within 7 days AND converted within 30 days" is two different cohort definitions glued together. + +Common funnel shapes and time-window guidance in [`references/funnel-design-templates.md`](references/funnel-design-templates.md). + +--- + +## Cohort definitions + +A cohort is a group of users sharing an attribute or behavior. Useful patterns. + +- Acquisition cohorts. Users acquired in month X. The standard for retention analysis. +- Behavioral cohorts. Users who completed action Y. Useful for activation analysis ("users who sent first message in week 1"). +- Property cohorts. Users with `subscription_tier: pro`. Useful for segment-level analysis. +- Combined cohorts. Signup in March AND completed onboarding AND in EU. The most common in real analytics work. + +Cohort discipline. + +- Define cohorts in code (or in your tool's saved-cohort feature) so they are reusable. +- Version them when criteria change. Compare apples-to-apples. +- Do not compare a 30-day-old cohort to a 365-day-old cohort on retention; the older cohort has had more time to retain by definition. + +Detail in [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md). + +--- + +## Retention measurement + +Retention is repeat behavior over time. Three flavors. + +- N-day retention. Did user X come back on day 7, day 14, day 30 specifically. High noise on any single day; useful for short-cycle products. +- Bracket retention. Did user X come back at any point during the week 7 to 13 window. More stable than N-day; reads cleaner on retention curves. +- Unbounded (rolling) retention. Did user X come back any time after signup. Useful for longer-cycle products where weekly cadence is misleading. + +For most SaaS products, bracket retention is the right default. Day-7 is high-noise; week-2 (bracket) is more stable. Day-1 retention is almost always over-indexed to onboarding effects rather than product-market-fit signal. + +Retention curve interpretation. + +- Steep early drop, then plateau. The product has core users; the rest churn fast. Typical for most SaaS products. +- Gradual decay across weeks with no plateau. No one is sticking. Usually a value-prop or onboarding problem; the product is not delivering recurring value. +- Flat line at low percentage. A power-user product with a small but engaged base. Not a problem; just a different shape. + +Detail in [`references/retention-measurement-patterns.md`](references/retention-measurement-patterns.md). + +--- + +## North Star and supporting metrics + +North Star metric (NSM) selection rules. + +- Reflects user value, not company value alone. +- Captures the core action that, if it grows, the business grows. +- Measurable consistently across time. +- Hard to game. + +Bad NSMs. Signups (vanity; many signups never activate). Revenue (lagging; not action-oriented; varies by mix). DAU (only useful for engagement-driven products; misleads on monthly-cadence products). + +Better NSMs. Weekly active editors (Figma). Nights booked (Airbnb). Messages sent per day (Slack). Products created per workspace per week (Linear). Each names a user-value action that maps to business growth. + +Supporting metrics framework. + +- One NSM. +- Three to five input metrics that drive the NSM. For "weekly active editors" these might be: signups per week, signup-to-active conversion rate, week-over-week active retention. +- Five to ten health metrics that warn of problems. Monthly churn rate, account-level concentration, support ticket volume. + +Detail and product-type-specific examples in [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md). + +--- + +## The trustable dashboard principle + +A dashboard is trustable when four things are true. + +1. Each metric has a clear definition documented inline. Not "active users" but "users who fired any event in the last 7 days, deduplicated by user_id, excluding employees." +2. Each metric has a known data source. Not "from the warehouse" but "from `fct_orders`, last 30 days, joined to `dim_customers`." +3. Each metric has known caveats. Modeled iOS conversions excluded. Internal employees excluded. Test users in QA accounts excluded. +4. Each metric is reproducible. The same query, run tomorrow, produces the same number for the same time period. + +The stale dashboard failure mode. A dashboard built two years ago is still in use. The underlying schema changed; the dashboard's query points at columns that no longer exist or now mean something different. The team makes decisions on broken numbers and does not realize until something breaks loudly. + +Prevention. Every dashboard has an owner, a refresh cadence, and a quarterly audit. Dashboards without an owner get deprecated. Dashboards that have not been refreshed in 90 days get deprecated. The half-life of a dashboard is shorter than the half-life of the product. + +--- + +## Instrumentation debt + +The compounding cost of cutting corners. + +- New feature ships without instrumentation: 1 hour saved. +- Six months later: nobody can answer "is feature X working?" +- Cost to retroactively instrument: 20 hours (re-deploy, backfill, validate). +- Cost in lost decisions during the gap: untrackable but real. Decisions get made on intuition rather than data; sometimes the intuition is wrong. + +Instrumentation debt is real and compounds like technical debt. The discipline. + +- Every PR for new functionality includes instrumentation. The PR template asks "what events does this fire?" and rejects the PR if the answer is none. +- Quarterly schema audits. Identify orphan events (firing but not used in any dashboard or query) and deprecate them. Identify gaps (features without events) and fill them. +- "If we cannot measure it, we do not ship it" with explicit exceptions for genuinely experimental features where the cost of instrumentation exceeds the value of the data. + +Detail in [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md). + +--- + +## Common failure modes + +Twelve patterns recur across product analytics setups. The short version. + +- "We have data but cannot trust it." Naming and schema drift. Fix is a schema audit plus naming convention enforcement. +- "Our funnel says 80% drop-off but real conversion is fine." Wrong anchor event or wrong window. Fix the funnel definition. +- "Retention curve is flat at 5%." Often not a problem. Power-user products genuinely have small engaged bases. Compare against business reality before treating as a fix-it. +- "Mixpanel says 1000 conversions, warehouse says 800." Attribution plus identity stitching mismatch. Reconcile against warehouse for canonical numbers. +- "Dashboards take 30 seconds to load." Over-broad queries, unindexed properties, or schema bloat. Profile and refactor. +- "Everyone has their own definition of MAU." No canonical metric document. Ship one; force everyone to use the same definition. +- "We track every button click." UI noise. Audit and remove events that are not used by any dashboard or query. +- "Our event names changed three times." No versioning. Migrate to a versioning pattern; freeze further renames. +- "Analytics tool says iOS users converted 3% but warehouse says 5%." iOS Intelligent Tracking Prevention plus modeled conversions. Treat platform iOS data with extra skepticism. +- "We cannot answer simple questions." Under-instrumented or wrong abstraction layer. Audit the events list against the questions the team is asking; fill the gaps. +- "Two analysts compute different MAU." Different identity stitching. Pick one canonical identity layer and make everyone query from it. +- "Numbers are different than last quarter for no reason." Underlying schema changed without versioning. The dashboard quietly broke; nobody noticed until the gap got large. + +Detail in [`references/common-failures.md`](references/common-failures.md). + +--- + +## The framework: 12 considerations for trustable product analytics + +When designing or auditing product analytics, walk these 12 considerations. Skipping any of them is how the team ends up with data nobody trusts. + +1. Event taxonomy. Past tense, object-action, granular but not redundant. Verbs are events; states are properties. +2. Property design. Event-level vs user-level. Type discipline. ISO 8601 timestamps everywhere. +3. Naming conventions. Pick one and enforce it. snake_case wins by default. +4. Schema versioning. Additive vs breaking. `_v2` suffix during transitions. Data contract in code. +5. Identity stitching. Anonymous to authenticated, cross-device, cross-tool. One canonical identity layer. +6. Funnel design. Anchor on high-intent events. Document time windows. No auto-firing events as steps. +7. Cohort definitions. Reusable, versioned, apples-to-apples. Defined in code or saved in the tool. +8. Retention measurement. Bracket over N-day for stability. Compare cohorts at matched ages. +9. North Star. Captures user value. Hard to game. One NSM, three to five inputs, five to ten health metrics. +10. Dashboard hygiene. Definitions, sources, owners, refresh cadence. Stale dashboards get deprecated. +11. Instrumentation debt. Every PR includes instrumentation. Quarterly audits. +12. Single source of truth. Warehouse for board metrics. Tool for in-flight optimization. Reconcile when they disagree. + +The output of the framework is a tracking plan. A list of events with their properties, the canonical user identity, the named cohorts, the named funnels, the retention measurement choice, the named NSM, the dashboard owners. The plan lives in code and gets reviewed like any other product spec. + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Canonical event spec for typical SaaS: account, user, activation, engagement, conversion, retention events with required properties. +- [`references/property-design-patterns.md`](references/property-design-patterns.md) - Event-level vs user-level patterns. Type discipline. Worked example: `product_viewed` right vs wrong. +- [`references/naming-convention-reference.md`](references/naming-convention-reference.md) - Complete style guide. snake_case, past tense, object-action. Boolean prefixes. Money in cents. Timestamps with `_at` suffix. Do/don't side-by-side. +- [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md) - Additive vs breaking changes. `_v2` suffix pattern. Data contract in TypeScript. CI lint patterns. +- [`references/funnel-design-templates.md`](references/funnel-design-templates.md) - Activation, conversion, engagement, feature adoption funnels. Time windows, anchor events, drop-off interpretation. +- [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md) - Acquisition, behavioral, property, combined cohorts. SQL examples plus tool-specific examples. +- [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md) - NSM rules with examples by product type. Anti-patterns. Migration patterns when changing NSM. +- [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md) - Quarterly audit playbook: schema review, volume sanity checks, dashboard freshness, owner audit, deprecation candidates. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: when in doubt, instrument less + +Most product analytics setups are over-instrumented, not under-instrumented. Tracking every button click produces noise that drowns the signal. The discipline of saying "we do not need to track that" is harder than "let us track that just in case." Default to less. + +The data you do not have can be added later. The data you over-collected costs you forever, in dashboard performance, in schema complexity, in signal-to-noise. The team that ships with thirty well-designed events and a small set of named cohorts outperforms the team that ships with two hundred events and no cohort discipline. + +When the team disagrees on whether to add an event, the question is not "could this be useful?" but "what specific decision will this event inform, and is the decision worth the instrumentation cost?" If the answer is "we might want to know" the answer to the question is no. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md new file mode 100644 index 0000000..1dc8ca5 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/cohort-definition-patterns.md @@ -0,0 +1,202 @@ +# Cohort definition patterns + +Four cohort patterns: acquisition, behavioral, property, combined. With SQL examples for warehouse-native and tool-specific examples for Mixpanel, Amplitude, and PostHog. + +--- + +## Pattern 1: acquisition cohort + +Users acquired in a specific time window. The standard for retention analysis. + +### Definition + +```sql +-- Warehouse-native (BigQuery / Snowflake / Postgres) +SELECT user_id +FROM dim_users +WHERE first_seen_at >= '2026-04-01' + AND first_seen_at < '2026-05-01'; +``` + +### Tool-specific + +Mixpanel. Cohort builder, condition: "First time the user did `user_signed_up` was between April 1 and April 30, 2026." + +Amplitude. User segment, condition: "First event date between April 1 and April 30, 2026." + +PostHog. Cohort, condition: "Person property `first_seen` is between April 1 and April 30, 2026." + +### Use cases + +- Retention analysis. Compare retention curves across acquisition cohorts to detect product or onboarding regressions. +- Onboarding A/B test results. The treatment cohort and control cohort are both acquisition cohorts. +- Cohort revenue tracking. How much did April's signups generate over the next 12 months? + +### Common mistakes + +- Comparing cohorts at different ages. A 30-day-old cohort has lower retention than a 90-day-old cohort by definition. +- Using "user created" vs "first event" inconsistently. Pick one and document it. + +--- + +## Pattern 2: behavioral cohort + +Users who completed a specific action. The standard for activation and engagement analysis. + +### Definition + +```sql +-- Users who fired first_value_action_completed within 14 days of signup +SELECT u.user_id +FROM dim_users u +JOIN fct_events e ON e.user_id = u.user_id +WHERE e.event_name = 'first_value_action_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '14 days'; +``` + +### Tool-specific + +Mixpanel. Cohort builder, condition: "User did `first_value_action_completed` at least once where event time was within 14 days of `user_signed_up`." + +Amplitude. Behavioral cohort, "Performed event `first_value_action_completed` within 14 days after first event." + +PostHog. Cohort, condition: "Person performed event `first_value_action_completed` and the event happened within 14 days of person creation." + +### Use cases + +- Activation funnel: activated users vs non-activated users. +- Feature adopters: users who used feature X. How does their retention compare to non-adopters? +- Power users: users who fired a specific high-value event 5 or more times. + +### Common mistakes + +- Using behavioral cohorts for retention without a time anchor. "Users who completed onboarding" includes users from January and users from October; their retention curves are at different ages. +- Confusing "users who ever did X" with "users who did X recently." Specify the time window. + +--- + +## Pattern 3: property cohort + +Users with a specific property value. The standard for segment-level analysis. + +### Definition + +```sql +SELECT user_id +FROM dim_users +WHERE subscription_tier = 'pro' + AND region = 'us' + AND is_admin = false; +``` + +### Tool-specific + +Mixpanel. Cohort, condition: "User properties: `subscription_tier = pro` AND `region = us`." + +Amplitude. User segment, condition: "User properties match: `subscription_tier = pro` AND `region = us`." + +PostHog. Cohort, condition: "Person properties: `subscription_tier = pro` AND `region = us`." + +### Use cases + +- Segment performance: how does the Pro tier behave differently from the Free tier? +- Geographic analysis: do EU users convert at a different rate than US users? +- Role-based analysis: do admins use the product differently than members? + +### Common mistakes + +- Using event-level properties as if they were user-level. "Users who fired any event with `cart_value > 100`" returns events, not users; use a behavioral cohort for "users who fired a high-value event." +- Snapshot vs current property values. "Users who were Pro in March" vs "users who are Pro now" are different cohorts; some platforms default to current values without warning. + +--- + +## Pattern 4: combined cohort + +Combinations of the above. The most common in real analytics work. + +### Definition + +```sql +-- Users who signed up in March, completed onboarding within 7 days, +-- are in EU, and are on the Pro tier +SELECT u.user_id +FROM dim_users u +WHERE u.first_seen_at >= '2026-03-01' + AND u.first_seen_at < '2026-04-01' + AND u.region = 'eu' + AND u.subscription_tier = 'pro' + AND EXISTS ( + SELECT 1 FROM fct_events e + WHERE e.user_id = u.user_id + AND e.event_name = 'onboarding_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '7 days' + ); +``` + +### Tool-specific + +All three platforms support combined cohorts via boolean composition (AND, OR, NOT). The composition gets unwieldy past 4 or 5 conditions; consider whether the cohort is genuinely useful or whether the team is over-segmenting. + +### Use cases + +- Activation analysis by acquisition channel: "Paid Meta users who signed up in March and activated within 7 days." +- Quality cohorts: "Pro tier users acquired via organic search who reached aha_moment within 14 days." +- Test cohorts: "Treatment group users who completed the onboarding A/B test within 7 days." + +### Common mistakes + +- Cohorts so narrow that the population is too small for analysis. A cohort of 50 users has high variance on every metric. +- Combining conditions that contradict each other. "Pro tier free users" returns nothing. +- Forgetting to time-box. A combined cohort without acquisition or behavioral time bounds drifts as users join and leave. + +--- + +## Cohort discipline + +Three rules that apply across all four patterns. + +### Rule 1: define cohorts in code (or saved in the tool) + +Re-querying the same cohort definition by hand each time produces inconsistencies. Define the cohort once; reuse the definition across analyses. + +In SQL: a `WITH` clause or a saved view. + +```sql +WITH march_cohort AS ( + SELECT user_id + FROM dim_users + WHERE first_seen_at >= '2026-03-01' + AND first_seen_at < '2026-04-01' +) +SELECT COUNT() FROM march_cohort; +``` + +In analytics tools: saved cohorts. Every analysis references the saved cohort by name. + +### Rule 2: version when criteria change + +A cohort definition that evolves over time produces non-comparable results. If you change the activation definition, the new cohort is a different cohort. + +Pattern. Append `_v2` to the cohort name when criteria change. Keep the old definition queryable for historical comparison. + +### Rule 3: compare apples-to-apples + +Two cohorts compared at different ages produce misleading conclusions. Always compare at matched ages. + +If comparing March cohort retention against November cohort retention, both should be measured at the same number of days post-acquisition. November cohort at 30 days vs March cohort at 60 days is not a fair comparison. + +--- + +## When to introduce a cohort + +The team has a question that filters on a user attribute or behavior. The question repeats across analyses. The team is computing the same filter 5+ times by hand. + +That is the trigger. Define the cohort once; reuse it. + +--- + +## When to deprecate a cohort + +The cohort has not been queried in 90 days. The cohort criteria no longer match a real product question (e.g., the feature it tracked was deprecated). The team has built a more precise replacement cohort. + +Stale cohorts in the analytics tool produce dropdown clutter and tempt analysts to use them when newer cohorts are appropriate. Deprecate explicitly. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md b/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md new file mode 100644 index 0000000..9e5fa5e --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across product analytics setups. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. We have data but cannot trust it + +Symptom.* The team has years of events. Two analysts run the same query and get different numbers. Stakeholders ask for "the real number" and the answer is "it depends." + +Root cause. Naming and schema drift over time. Same event name has slightly different semantics in different code paths. Properties have inconsistent types or values. + +Fix. Schema audit. Identify the canonical events; deprecate the duplicates and aliases. Standardize property types. Document the canonical definitions. + +Prevention. Schema in code (TypeScript interface or JSON Schema). CI lint that rejects schema violations. Naming convention enforcement. + +--- + +## 2. Funnel says 80% drop-off but real conversion is fine + +Symptom. The activation funnel shows 20% conversion. The team knows from revenue numbers that real activation is 60%. + +Root cause. Wrong anchor event (using a too-broad event like `page_view` as the start) or wrong time window (asking for activation within 24 hours when the real cycle is 14 days). + +Fix. Audit the funnel definition. Anchor on a high-intent event (signup, trial start). Set the time window to match the actual activation cycle. + +Prevention. Document the funnel anchor and window in the funnel definition itself, not implicit in dashboard text. Review funnels at each quarterly audit. + +--- + +## 3. Retention curve is flat at 5% + +Symptom. Retention curve drops fast then plateaus at 5%. The team panics; only 5% of users are active. + +Root cause. Not always a problem. Some products are power-user products with small but engaged bases (developer tools, niche B2B software). The 5% may be the natural shape. + +Fix. Compare against business reality. If 5% retention with strong unit economics, the curve is healthy. If 5% retention and the business model assumes 20% retention, then it is a problem and the cohort needs investigation. + +Prevention. Set retention targets based on business model assumptions, not industry benchmarks. The right retention for a niche tool is different from the right retention for a consumer app. + +--- + +## 4. Mixpanel says 1000 conversions, warehouse says 800 + +Symptom. Two systems report different conversion counts for the same event. + +Root cause. Identity stitching mismatch. Mixpanel may stitch anonymous-to-authenticated differently than the warehouse. Server-side and client-side fires of the same event may not deduplicate correctly. Time-window differences (Mixpanel using event time, warehouse using ingest time). + +Fix. Pick one source as canonical (warehouse for board metrics, tool for in-flight). Reconcile the gap by understanding the cause. Document the expected gap so stakeholders are not surprised. + +Prevention. Identity stitching pattern documented and consistent. Server-side and client-side firing for the same event handled with explicit deduplication. Use a single time field consistently. + +--- + +## 5. Dashboards take 30 seconds to load + +Symptom. The team's main dashboard takes 30+ seconds to refresh. Reviewing a metric becomes a coffee break. + +Root cause. Over-broad queries (scanning years of data for a 30-day metric). Unindexed properties used as filters. Schema bloat from too many events or too many properties on each event. + +Fix. Profile the slow queries. Add date filters. Index the filter properties. Pre-aggregate metrics into a daily summary table; query the summary, not the raw events. + +Prevention. Set query budgets per dashboard (target: under 5 seconds). Audit performance during the quarterly audit. Cap the data volume per query. + +--- + +## 6. Everyone has their own definition of MAU + +Symptom. Three people compute MAU; three different numbers. + +Root cause. No canonical definition. One person counts unique user_ids firing any event. Another counts users who fired a specific qualifying event. Another counts authenticated users only. + +Fix. Write a canonical metric document. "MAU is unique user_ids firing any event in the last 30 days, deduplicated, excluding employee accounts (employees identified by email domain) and excluding test accounts (account_type = 'test')." Force everyone to use this definition. + +Prevention. Canonical metric document maintained as living documentation. Every dashboard's metric definitions reference the canonical document. Disagreements get resolved by updating the document, not by recomputing on the fly. + +--- + +## 7. We track every button click + +Symptom. The event list has 800 events. Many are individual button clicks. Dashboards are slow; analyses produce noise. + +Root cause. Tracking UI events (clicks, hovers, page views) rather than semantic events (created, completed, shared). Each button gets its own event "for completeness." + +Fix. Audit the event list. Deprecate UI events. Replace with semantic events that capture user intent. + +Prevention. Naming convention enforcement (verbs are events; UI states are properties). Code review on new events asks "is this a semantic event or a UI event?" UI events get rejected unless there is a specific use case. + +--- + +## 8. Our event names changed three times + +Symptom. `signup_complete`, then `signupCompleted`, then `user_signed_up`. Dashboards reference all three; nobody knows which is current. + +Root cause. No versioning. Each rename happened without coordination, leaving old events in the warehouse and old queries in the dashboards. + +Fix. Migrate to a single canonical version. Use the `_v2` pattern if semantics changed. Deprecate old versions explicitly. Update all dashboards. + +Prevention. Versioning pattern in the schema documentation. Schema review on every PR that adds or modifies an event. CI lint on event names. + +--- + +## 9. Analytics tool says iOS users converted 3% but warehouse says 5% + +Symptom. iOS conversion rate looks bad in the analytics tool but fine in the warehouse. + +Root cause. iOS Intelligent Tracking Prevention (ITP) blocks third-party cookies, breaking attribution for iOS users. The analytics tool models the missing data; the warehouse uses server-side conversion tracking that is unaffected. + +Fix. Treat iOS analytics-tool data with extra skepticism. Use the warehouse for canonical iOS metrics. Set up server-side event tracking (Conversions API for Meta, server-side GA4) where possible. + +Prevention. Document the iOS measurement gap. Pair every iOS-specific metric with a note on the data source. + +--- + +## 10. We cannot answer simple questions + +Symptom. Stakeholder asks: "How many users came back this week?" Three days of analyst time later, still no clean answer. + +Root cause. Under-instrumented or wrong abstraction layer. The events list does not include the right event. The user identity layer does not stitch correctly. The cohort definition is too narrow or too broad. + +Fix. Audit the event list against the questions the team actually asks. Fill gaps with new events; fix identity stitching; create canonical cohorts for the most common questions. + +Prevention. Quarterly review of the question backlog. Map questions to events; identify gaps. Fill gaps proactively, not after the question goes unanswered. + +--- + +## 11. Two analysts compute different MAU on the same data + +Symptom. Same query, same data, different numbers. The discrepancy is not because of a definition disagreement; it is because the queries silently return different rows. + +Root cause. Different identity stitching layers. One query uses user_id; another uses anonymous_id with stitching applied at query time. Edge cases (users who logged out and back in, users on multiple devices) get counted differently. + +Fix. Pick one canonical identity layer. Build a `dim_users` table in the warehouse that resolves identity once. Force all queries to join through this table. + +Prevention. Identity-stitching pattern documented. New queries use the canonical table. Code review rejects queries that bypass the layer. + +--- + +## 12. Numbers different than last quarter for no reason + +Symptom. A dashboard's metrics shifted between Q1 and Q2 by 30%. No product change, no instrumentation change... or so it seems. + +Root cause. Underlying schema changed without versioning. An event was renamed; the dashboard's query points at the old name and now silently returns nothing or returns a different cohort. Often discovered weeks after the fact. + +Fix. Audit the dashboard's query against the current schema. Update to current event names. Check for similar drift in other dashboards. + +Prevention. Versioning pattern enforced. CI lint catches event renames before they ship. Quarterly dashboard audit catches drift early. + +--- + +## The pattern across all twelve + +Most product analytics failures share one root cause: cutting corners during instrumentation produces compounded debt that surfaces months later as untrustworthy data. The team that ships without a tracking plan saves an hour at instrumentation time and pays 20+ hours at audit time. + +The fix at the meta level. Treat instrumentation as a first-class engineering concern. Schema in code. Naming convention enforced. Quarterly audits. Single source of truth for canonical metrics. Instrumentation debt is real; the discipline of paying it down regularly is the only thing that keeps the data trustworthy. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md b/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md new file mode 100644 index 0000000..86bb1df --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/event-taxonomy-template.md @@ -0,0 +1,114 @@ +# Event taxonomy template + +A canonical event spec for typical SaaS. Six event categories with the events that belong in each, when they fire, who fires them (client or server), required properties, and common pitfalls. + +The principle. Thirty to fifty events covers most SaaS products. Below twenty is under-instrumented; above one hundred is usually UI noise. The categories below are the durable shape; the specific event names map to your product. + +--- + +## Account events + +Account-level lifecycle. Server-side firing typical because billing is server-side. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `account_created` \| A new account (workspace, organization) is provisioned. \| `account_id`, `plan_tier`, `seat_count` \| Distinct from `user_signed_up` (a user can join an existing account). \| +\| `account_upgraded` \| The account moves to a higher plan tier. \| `account_id`, `from_tier`, `to_tier`, `change_reason` \| Fires server-side from the billing webhook. \| +\| `account_downgraded` \| The account moves to a lower plan tier. \| `account_id`, `from_tier`, `to_tier`, `change_reason` \| Same source as upgrade. \| +\| `account_canceled` \| The account cancels and stops renewing. \| `account_id`, `cancellation_reason`, `final_term_end_at` \| Cancellation reason is critical; capture it from the cancellation flow. \| +\| `seat_added` \| A new seat is provisioned on the account. \| `account_id`, `seat_count_after`, `added_by_user_id` \| Useful for net-revenue-retention analysis. \| +\| `seat_removed` \| A seat is released from the account. \| `account_id`, `seat_count_after`, `removed_by_user_id`, `removal_reason` \| \| + +Common pitfall. Firing account events client-side from the admin UI. The admin's browser may not be open during the cancellation; server-side from the billing webhook is the right source. + +--- + +## User events + +User-level lifecycle. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `user_signed_up` \| A user creates an account or joins an existing account. \| `user_id`, `account_id`, `signup_source`, `referrer_source` \| Distinct from `account_created`; one account, many users. \| +\| `user_invited` \| An existing user invites a new user. \| `inviter_user_id`, `invited_email`, `account_id`, `invitation_role` \| The invitation event; `user_signed_up` fires later when the invite is accepted. \| +\| `user_role_changed` \| A user's role within the account changes. \| `user_id`, `account_id`, `from_role`, `to_role`, `changed_by_user_id` \| \| +\| `user_logged_in` \| A user authenticates after a logged-out state. \| `user_id`, `auth_method`, `device_type` \| Different from session start. Logged-in across multiple sessions. \| +\| `user_logged_out` \| A user explicitly signs out. \| `user_id`, `logout_reason` \| Often missed; explicit signout vs session timeout. \| +\| `user_deactivated` \| A user's account is deactivated. \| `user_id`, `account_id`, `deactivation_reason` \| Soft delete pattern. \| + +--- + +## Activation events + +The first-value moment. Critical for activation analysis. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `onboarding_step_completed` \| The user completes a step in the onboarding flow. \| `user_id`, `step_name`, `step_number`, `time_in_step_s` \| Step name is canonical; do not change it without versioning. \| +\| `onboarding_completed` \| The user finishes all onboarding steps. \| `user_id`, `total_time_s`, `steps_completed_count` \| Distinct from activation; onboarding completion does not equal activation. \| +\| `first_value_action_completed` \| The user does the thing that delivers product value for the first time. \| `user_id`, `action_name`, `time_since_signup_s` \| Define this carefully per product. For Slack, first message sent. For Figma, first frame created. \| +\| `aha_moment_reached` \| The user crosses the activation threshold. \| `user_id`, `threshold_metric`, `threshold_value` \| Tied to the activation definition (e.g., "5 messages in week 1"). \| + +--- + +## Engagement events + +Recurring product use. The bulk of event volume. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `feature_x_used` \| The user invokes feature X. Replace x with the actual feature name. \| `user_id`, `feature_name`, `entry_point` \| Granularity guidance: one event per feature, not one event per button. \| +\| `content_y_created` \| The user creates a new asset (document, project, message, etc.). \| `user_id`, `content_type`, `content_id`, `creation_source` \| \| +\| `content_y_edited` \| The user modifies an existing asset. \| `user_id`, `content_type`, `content_id`, `edit_type` \| High volume; consider sampling if storage is a concern. \| +\| `content_y_shared` \| The user shares an asset externally. \| `user_id`, `content_type`, `content_id`, `share_method`, `recipient_count` \| Sharing is often the strongest engagement signal. \| +\| `search_executed` \| The user runs an in-product search. \| `user_id`, `query_length`, `result_count`, `clicked_result_position` \| Capture click-through rates. \| + +--- + +## Conversion events + +Money moves. Server-side firing required. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `trial_started` \| The user starts a free trial. \| `user_id`, `account_id`, `trial_plan`, `trial_length_days` \| Server-side from the billing system. \| +\| `trial_converted` \| The trial converts to paid. \| `user_id`, `account_id`, `from_plan`, `to_plan`, `mrr_added` \| Server-side. The MRR property feeds revenue analysis. \| +\| `trial_expired_no_conversion` \| The trial ends without converting. \| `user_id`, `account_id`, `trial_plan`, `usage_during_trial` \| Useful for win-back campaigns. \| +\| `subscription_purchased` \| A subscription begins (any path). \| `user_id`, `account_id`, `plan_tier`, `mrr_added`, `purchase_source` \| Includes trial conversions and direct purchases. \| +\| `subscription_renewed` \| A subscription renews for the next term. \| `account_id`, `plan_tier`, `mrr_at_renewal` \| \| +\| `payment_failed` \| A payment attempt fails. \| `account_id`, `failure_reason`, `attempt_number` \| Critical for involuntary churn analysis. \| + +--- + +## Retention events + +Repeat behavior markers. Useful for retention curve construction. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `weekly_active_marker` \| The user fires any qualifying event in a given week. \| `user_id`, `week_of_year`, `qualifying_event_count` \| Some teams compute this in the warehouse rather than fire it as an event; either pattern works. \| +\| `returned_after_n_days` \| The user returns after N days of inactivity. \| `user_id`, `inactive_days_count`, `last_active_at` \| Useful for resurrection-flow analytics. \| + +--- + +## Property requirements across all events + +Every event payload should include: + +- `user_id` (or `anonymous_id` for pre-auth events) +- `account_id` (where applicable; for B2B SaaS especially) +- `timestamp` (ISO 8601, server-stamped) +- `device_type` and `platform` (mobile, web, desktop) +- `app_version` (for change-tracking) +- `session_id` (for path analysis) + +Some platforms inject these automatically. Verify; do not assume. + +--- + +## Common pitfalls in event taxonomy + +- Tracking page views as the primary engagement signal. Page views are noise. Track semantic events (created, edited, shared) instead. +- Treating onboarding completion as activation. Many users complete onboarding without ever returning. Define activation as a recurring-value action, not as flow completion. +- Inconsistent fire timing across the funnel. Some events fire client-side, some server-side. Reconcile by picking one source per event and documenting it. +- Adding new events without checking existing ones. Six months in, the event list has three versions of "subscription started." Audit before adding. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md b/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md new file mode 100644 index 0000000..f7b110a --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/funnel-design-templates.md @@ -0,0 +1,174 @@ +# Funnel design templates + +Common funnel shapes with anchor events, time windows, and drop-off interpretation guidance. + +The principle. Every funnel measures progression through a sequence. The shape of the funnel must match the shape of the user behavior; mismatch produces conversion rates that are uninterpretable. + +--- + +## Activation funnel + +Signup to first value. The most important funnel for product-led growth. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `user_signed_up` \| The anchor. High intent. \| +\| 2 \| `onboarding_started` \| The user begins the guided onboarding. \| +\| 3 \| `onboarding_completed` \| The user finishes onboarding. Note: this is not activation. \| +\| 4 \| `first_value_action_completed` \| The user does the action that delivers product value. THIS is activation. \| +\| 5 \| `aha_moment_reached` \| Optional. The threshold beyond which retention curves stabilize. \| + +### Time window + +7 to 14 days from signup. Longer windows include users who activated after a long delay; shorter windows undercount slow adopters. + +### Anchor selection + +`user_signed_up` is the standard anchor. Avoid `landing_page_viewed` (too noisy) and `email_collected` (too low-intent). + +### Drop-off interpretation + +- 70%+ drop between signup and onboarding_started: the post-signup experience is the problem. Often a friction issue (email verification, account setup steps). +- 30%+ drop between onboarding_completed and first_value_action_completed: onboarding is teaching the wrong thing. Users complete the tour but do not understand the product. +- High drop at first_value_action_completed: the value action is too hard or too far from the user's natural path. Move it earlier in the experience. + +--- + +## Conversion funnel + +Trial to paid. The most important funnel for SaaS subscription businesses. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `trial_started` \| The anchor. High intent and ready to evaluate. \| +\| 2 \| `aha_moment_reached` \| The user experiences product value. Critical predictor of conversion. \| +\| 3 \| `paywall_viewed` \| The user sees the upgrade prompt. \| +\| 4 \| `checkout_started` \| The user begins the payment flow. \| +\| 5 \| `subscription_purchased` \| The conversion. \| + +### Time window + +The trial length plus a 7-day grace period. A 14-day trial uses a 21-day funnel window. Shorter windows undercount last-day conversions. + +### Anchor selection + +`trial_started` is the standard anchor. Funnels that start at signup (rather than trial start) include users who never engaged with the trial; the conversion rate looks lower than it actually is for engaged users. + +### Drop-off interpretation + +- High drop between aha_moment_reached and paywall_viewed: users got value but the paywall did not appear (timing issue) or did not feel relevant. Audit the paywall trigger logic. +- High drop between paywall_viewed and checkout_started: pricing or feature gating is the friction. Often a positioning issue rather than a UX issue. +- High drop between checkout_started and subscription_purchased: payment flow friction. UX audit the checkout pages; check failed-payment rates. + +--- + +## Engagement funnel + +Visit to action. Useful for understanding session-level conversion. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `feature_x_landing_page_viewed` \| The anchor. Specific intent (feature page, not homepage). \| +\| 2 \| `feature_x_used` \| The user performs the core action. \| +\| 3 \| `feature_x_completed_workflow` \| The user finishes the workflow. \| +\| 4 \| `content_y_shared` or similar high-intent action \| Optional. Strongest engagement signal. \| + +### Time window + +Single session, typically 30 to 60 minutes from the first event. + +### Anchor selection + +A feature-specific landing or entry point. Avoid `homepage_viewed` (too broad) and `session_started` (auto-firing, not intent). + +### Drop-off interpretation + +- High drop from landing to use: the page promises something the feature does not deliver, or the activation friction is too high. +- High drop from use to workflow completion: the workflow has too many steps, or a specific step has UX issues. + +--- + +## Feature adoption funnel + +Awareness to repeat use. Tracks how a feature spreads through the user base. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `feature_x_announced_to_user` \| The anchor. The user saw a notification, prompt, or in-app message about feature X. \| +\| 2 \| `feature_x_first_used` \| The user tried feature X for the first time. \| +\| 3 \| `feature_x_used_in_week_2` \| The user used feature X again in a different week. \| +\| 4 \| `feature_x_used_in_week_4` \| Sustained adoption. \| + +### Time window + +4 weeks from announcement. + +### Anchor selection + +The announcement event is the right anchor for measuring rollout effectiveness. For organic discovery (no announcement), use `feature_x_first_used` as the anchor and measure the feature's reach as a denominator. + +### Drop-off interpretation + +- High drop from announcement to first use: the announcement was missed, the announcement was unclear, or the feature was not relevant to the audience. Audit by user segment. +- High drop from first use to repeat use in week 2: the feature did not deliver value on first use. Either the use case was wrong (user tried it for the wrong thing) or the value-prop is weak. +- Adoption stalls at 5% of the user base: the feature is for a niche; this may be expected. Compare against the projected target audience size. + +--- + +## Common funnel design mistakes + +### Mistake 1: vanity-event anchor + +Using `homepage_viewed` or `session_started` as the anchor. The denominator is huge; the conversion rate is tiny; the funnel says nothing about user behavior. + +Fix. Anchor on a high-intent action: signup, trial_started, feature-specific page view. + +### Mistake 2: too long + +Ten or more steps. The end-to-end conversion rate is near zero; the funnel is hard to interpret; small numerator changes look like dramatic shifts. + +Fix. Break into 2 or 3 shorter funnels. An activation funnel plus a conversion funnel beats one 10-step funnel. + +### Mistake 3: auto-firing events as steps + +Including `session_started`, `app_opened`, or any event that fires automatically. The denominator is the entire user base; the meaning of conversion rates is muddled. + +Fix. Use only intentional, semantic events as funnel steps. + +### Mistake 4: same event in multiple positions + +Using `feature_used` at step 2 and step 5. The platform double-counts; the analyst gets confused. + +Fix. Distinguish via different events (`feature_first_used` vs `feature_used_in_week_2`) or via a property filter. + +### Mistake 5: mixed time windows + +The funnel definition allows step 2 within 7 days but step 4 within 30 days. The math becomes interpretable only by the analyst who built it; everyone else gets it wrong. + +Fix. One time window for the entire funnel. Document it explicitly. + +### Mistake 6: forgetting the cohort + +Running the funnel against "all users ever" rather than a specific acquisition cohort. The cohort matters; January users behave differently from November users. + +Fix. Always specify the cohort. "Users who signed up in March, evaluated against the activation funnel within 14 days." + +--- + +## Comparing funnels across cohorts + +The strongest analytical use of funnels is comparing how the funnel performs across cohorts. + +- This month's signup cohort vs last month's: is the funnel stable, or are recent users dropping more? +- Paid acquisition cohort vs organic: are paid users converting at the same rate, or are paid users worse-quality? +- Mobile vs web: is the experience parity issue real? + +Always compare cohorts at matched ages. A 30-day-old cohort vs a 60-day-old cohort has different conversion rates by definition. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md b/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md new file mode 100644 index 0000000..b481bff --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/instrumentation-audit-checklist.md @@ -0,0 +1,119 @@ +# Instrumentation audit checklist + +The quarterly playbook for keeping product analytics trustworthy. Five categories: schema, volume, dashboard freshness, ownership, deprecation. + +The principle. Instrumentation decays without active maintenance. Quarterly audits catch decay early; without them, the team ends up with the "we have data but cannot trust it" problem. + +--- + +## 1. Schema review + +Goal. Ensure the event taxonomy and property schema match the canonical contract. + +Steps. + +- Pull the event list from the analytics tool. Mixpanel: Lexicon. Amplitude: Govern. PostHog: Data Management. Or directly from the warehouse if warehouse-native. +- Compare against the schema definition in code. Every event in the tool should appear in the schema; every event in the schema should appear in the tool. +- Flag drift. Events firing without a schema entry. Schema entries with no events firing in the last 90 days. Property type mismatches between schema and observed values. +- Audit naming. Events that do not match the naming convention (snake_case, past tense, object-action). Property names with inconsistent casing or typo variants. +- Action items. For each drift item, decide: fix the schema, fix the tracking code, or deprecate the event. Document the decision. + +Cadence. Quarterly. More frequently if the team is shipping rapidly. + +--- + +## 2. Volume sanity check + +Goal. Confirm event volumes match expectations. + +Steps. + +- Pull weekly event counts for the last 90 days. Group by event name. +- Identify volume anomalies. Sudden drops (deployment broke instrumentation). Sudden spikes (a new code path is firing the event excessively or a bot is hitting the endpoint). Events whose volume drifts steadily down (the feature behind them was deprecated; instrumentation should follow). +- Check ratios. If `signup_started` fires 10x more than `signup_completed`, signup completion is broken or the events fire under different conditions than expected. If `checkout_started` fires more than `add_to_cart`, the events are misordered or one fires automatically. +- Compare against business reality. The dashboard says 50,000 weekly signups; the warehouse says 38,000 paying customers were acquired in the same period. The gap is fine if the business is in trial mode; alarming if the gap should be smaller. +- Action items. For each anomaly, identify the cause. Either the instrumentation is broken (fix it), the business changed (update expectations), or the event semantics drifted (version it). + +Cadence. Quarterly minimum. Real-time alerts on the highest-volume events for major deviations. + +--- + +## 3. Dashboard freshness review + +Goal. Identify dashboards that have rotted. + +Steps. + +- Pull the dashboard inventory from the analytics tool or BI platform. +- Check last-viewed dates. Dashboards not viewed in the last 90 days are candidates for deprecation. Dashboards not viewed in the last 180 days are almost always stale. +- Check last-edited dates. A dashboard last edited 18 months ago whose underlying schema changed is silently broken. Audit whether the dashboard's metrics still compute correctly. +- Check ownership. Every dashboard should have a named owner. Dashboards with no owner or with an owner who has left the company need reassignment or deprecation. +- Spot-check key metrics. Pick 5 to 10 dashboards. Compute the same metric directly from the warehouse. Compare. Drift over 5% needs investigation. +- Action items. Reassign orphan dashboards. Deprecate stale dashboards. Fix or rewrite dashboards that have drifted from underlying truth. + +Cadence. Quarterly. + +--- + +## 4. Owner assignment audit + +Goal. Every event, dashboard, cohort, and saved query has a named owner who can answer questions about it. + +Steps. + +- Pull the ownership map for events, dashboards, cohorts, saved queries. Most analytics tools support tagging or property fields for owner. +- Identify orphans. Items with no owner. Items whose owner has left the company. +- Reassign. For each orphan, assign a new owner or deprecate. Owner means "the person who can explain why this exists and what depends on it." It is not a vanity tag. +- Document the chain of custody. If the original owner left and the new owner is unfamiliar with the history, write down what you know. +- Action items. Update the ownership tags. Notify owners of items they are now responsible for. Set up a review cycle (every 6 months minimum) for owners to confirm or release ownership. + +Cadence. Quarterly minimum. Whenever someone leaves the team, immediately for their owned items. + +--- + +## 5. Deprecation candidates + +Goal. Identify and remove instrumentation, cohorts, and dashboards that no longer serve a purpose. + +Steps. + +- Identify candidate events. Events whose volume is below 10 per week. Events not referenced in any active dashboard or query in the last 90 days. Events that are duplicate or near-duplicate of other events. +- Identify candidate cohorts and saved queries. Items not used in the last 90 days. Items whose source data is now stale. +- Identify candidate dashboards. Already covered in step 3; gather candidates here. +- Soft deprecation. Tag items as deprecated; remove from default views. Wait 30 days. If anyone notices, reverse the deprecation; if nobody notices, hard delete. +- Communicate. Post the deprecation list to the data channel. Anyone with a use case has 14 days to push back. +- Action items. Soft deprecate. Wait. Hard delete on the next audit if no objections. + +Cadence. Quarterly. Hard deletion happens at the next audit, not the same one. + +--- + +## The audit deliverable + +Each quarterly audit produces a written report with five sections matching the steps above. The report includes. + +- What changed since the last audit. Events added, removed, renamed. Schema migrations completed. +- Drift identified. Events firing without schema entries. Property type mismatches. Volume anomalies. +- Decisions made. What was fixed, what was deprecated, what was deferred. +- Open items. Drift not yet resolved. Pending decisions. Owners reassigned but not yet confirmed. +- Forward planning. Schema changes anticipated next quarter. Dashboards likely to be migrated. Events likely to be deprecated. + +The report goes to the data team and the eng leads. It does not need to go to the entire company; the value is in the discipline of writing it. + +--- + +## When to skip an audit + +Never. The cost of skipping a quarter compounds. The team that audits twice a year ends up doing 3x the work each audit; the team that audits quarterly maintains a steady state. + +The exception. A team in a 30-day sprint to launch a major product version may defer one audit by 4 to 6 weeks. After that, the audit is overdue and the discipline is at risk. + +--- + +## What the audit is not + +Three things to avoid. + +- Not a witch hunt. The audit identifies drift, not blame. Many drift items are produced by good-faith engineering decisions that did not include the analytics-debt cost. +- Not perfectionism. Some drift is acceptable. Aim for 95% clean, not 100%. Spending the audit cycle chasing the last 5% leaves real problems unaddressed. +- Not silent. The audit produces a deliverable. Without the deliverable, the audit happened in someone's head; it does not transfer to the next quarter or the next team. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md b/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md new file mode 100644 index 0000000..c4572a7 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/naming-convention-reference.md @@ -0,0 +1,125 @@ +# Naming convention reference + +A complete style guide. Pick one convention; enforce it via CI lint. + +--- + +## The canonical conventions + +snake_case for events and properties. `user_signed_up`, `cart_value`, `trial_day`. + +Past tense, action-oriented for events. `checkout_completed`, not `complete_checkout` or `completing_checkout`. + +Object-action format for events. Noun then verb. `video_played`, `form_submitted`, `email_opened`. + +Boolean prefix for boolean properties. `is_`, `has_`, `can_`. `is_admin`, `has_trial`, `can_invite`. + +Counting suffix for count properties. `_count` or `_total`. `seat_count`, `total_purchases`, `signup_count`. + +Money in smallest unit with currency named. `price_cents` not `price` (and currency on `currency` property). + +Timestamp suffix for date-time properties. `_at` for absolute timestamps. `created_at`, `last_active_at`. `_s` or `_ms` for durations. `time_since_signup_s`. + +Period suffix for relative-time properties. `_days`, `_weeks`. `inactive_days_count`, `trial_length_days`. + +--- + +## Do and don't + +\| Don't \| Do \| Why \| +\|---\|---\|---\| +\| `Sign Up Completed` \| `signup_completed` \| snake_case, no spaces. URL-safe. \| +\| `userSignedUp` \| `user_signed_up` \| snake_case wins by default; consistent across the platform. \| +\| `signup` (event) \| `user_signed_up` \| Past tense, object-action. Reads as "this happened." \| +\| `complete_checkout` \| `checkout_completed` \| Past tense for events. \| +\| `completing_checkout` \| `checkout_completed` \| Past tense, not progressive. \| +\| `Sign Up` \| `signup` or `signed_up` \| Pick one form for the same concept. Document it. \| +\| `price: "$19.99"` \| `price_cents: 1999` plus `currency: "USD"` \| Money in smallest unit. Currency separate. \| +\| `quantity: "5"` \| `quantity: 5` \| Numbers as numbers, not strings. \| +\| `is_premium: "yes"` \| `is_premium: true` \| Booleans as booleans. \| +\| `viewed: 1` \| `is_viewed: true` \| If it is yes/no, it is boolean, not 0/1. \| +\| `created: "5/5/2026"` \| `created_at: "2026-05-05T14:30:00Z"` \| ISO 8601, always. UTC. \| +\| `tags: "a,b,c"` \| `tag_list: ["a", "b", "c"]` \| Arrays for bounded lists, not delimiter-strings. \| +\| `signup_source` (one event) plus `source` (another event) \| `signup_source` plus `referral_source` \| Disambiguate when the same name means different things. \| +\| `User Signed Up` (event), `signupCompleted` (event), `SIGN_UP` (event) \| `user_signed_up` (event), `signup_completed` (event) \| Pick one casing, stick to it. \| +\| `mailchimp_email_opened` \| `email_opened` plus `provider: "mailchimp"` property \| Brand-neutral event names; vendor as a property. \| +\| `feature_x_clicked` \| `feature_x_used` \| Track usage, not button clicks. UI events are noise. \| + +--- + +## Boolean property prefixes + +The prefix should make the property read as a yes-or-no question. + +- `is_admin` reads as "is admin?" Yes or no. +- `has_trial` reads as "has trial?" Yes or no. +- `can_invite` reads as "can invite?" Yes or no. +- `should_notify` reads as "should notify?" Yes or no. + +What NOT to do. + +- `admin: true`. Reads as "admin is true." Awkward in queries. +- `premium: 1`. Reads as a count, not a yes-or-no. +- `trial: "yes"`. String, not boolean. + +--- + +## Time, date, and duration suffixes + +\| Suffix \| Meaning \| Example \| +\|---\|---\|---\| +\| `_at` \| Absolute timestamp (ISO 8601 UTC) \| `created_at`, `last_active_at`, `event_timestamp` \| +\| `_s` \| Duration in seconds \| `time_in_step_s`, `session_duration_s` \| +\| `_ms` \| Duration in milliseconds \| `response_time_ms` \| +\| `_days` \| Duration in days (integer) \| `inactive_days_count`, `trial_length_days` \| +\| `_weeks` \| Duration in weeks (integer) \| `weeks_since_signup` \| +\| `_months` \| Duration in months (integer) \| `months_active` \| + +Mixing units across the schema produces bugs. Pick one unit per concept and document it. + +--- + +## Money + +Two rules. + +1. Smallest unit, integer. `price_cents`, `mrr_cents`, `total_revenue_cents`. Float arithmetic on money produces rounding errors. +2. Currency named separately. `currency: "USD"`. Do not assume USD; international users break the assumption. + +When the smallest unit varies (yen has no decimals; bitcoin has 8), pick a precision and document it. The integer math discipline still applies. + +--- + +## Identifiers + +Three identifier patterns. + +- Stable IDs are immutable. `user_id`, `account_id`, `product_id`. Use UUIDs or a system-generated identifier. +- Human-readable names are mutable. `product_name`, `account_name`. Useful for reporting; never use as a join key. +- Display IDs are user-visible. `invoice_number`, `order_number`. Often distinct from the database primary key. + +Always include a stable ID in event payloads. Optionally include the human-readable name for reporting convenience. + +--- + +## What NOT to encode in event names + +Three categories of detail belong on properties, not in event names. + +1. State or status. Not `user_active`, `user_inactive`. Use `user_signed_in` (event) plus `status` (user property). +2. Variant or treatment. Not `signup_variant_a`. Use `user_signed_up` (event) plus `experiment_variant` (property). +3. Source or channel. Not `signup_from_facebook`. Use `user_signed_up` (event) plus `acquisition_channel: "facebook"` (property). + +The principle. Event names answer "what happened?" Properties answer "with what context?" + +--- + +## Enforcement + +A naming convention without enforcement decays. Two patterns. + +CI lint. A schema definition (TypeScript interface, JSON Schema) plus a CI step that rejects events whose payload does not match. The lint catches new violations before they hit production. + +Code review checklist. PRs that add or modify events include a snippet showing the event name, properties, and types. The reviewer compares against the naming convention reference and the existing taxonomy. + +Without enforcement, the convention becomes documentation that nobody reads. With enforcement, it becomes a constraint that the codebase respects. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md b/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md new file mode 100644 index 0000000..979ffe8 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/north-star-metric-selection.md @@ -0,0 +1,159 @@ +# North Star metric selection + +Rules for picking a North Star metric (NSM), examples by product type, anti-patterns, and migration patterns when changing NSM. + +The principle. The NSM is the single number the team optimizes against. Picking the wrong number focuses the team on the wrong work for as long as the team uses it. + +--- + +## NSM selection rules + +A trustworthy NSM passes four tests. + +1. Reflects user value, not company value alone. Revenue is company value; the NSM should track an action that delivers user value. Revenue can be the trailing measure; the NSM is the leading driver. +2. Captures the core action that, if it grows, the business grows. The NSM should be cause-correlated with revenue growth, retention, and any other business goal. If you double the NSM and the business does not improve, the NSM is wrong. +3. Measurable consistently across time. The definition should not drift. If the NSM definition changes every quarter, year-over-year comparison is impossible. +4. Hard to game. The team should not be able to grow the NSM via shortcuts that do not deliver user value. A gameable NSM produces local maxima that the team optimizes toward at the expense of the actual mission. + +--- + +## Examples by product type + +### Engagement-driven products + +The product creates ongoing value through repeated use. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Slack \| Messages sent in workspaces of 3+ active users per week \| Captures recurring value; harder to game than DAU; size threshold filters out trial-only users. \| +\| Figma \| Weekly active editors \| The action that delivers value (creating in Figma); active editors filters out viewers who do not get full product value. \| +\| Notion \| Weekly content blocks created per workspace \| Captures the core verb (creating); per-workspace normalizes for team size variance. \| +\| Linear \| Weekly issues created per workspace \| The product use case is project tracking; issues created is the load-bearing action. \| + +### Transaction-driven products + +The product makes money on each transaction. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Airbnb \| Nights booked (not bookings) \| Nights captures the value delivered to hosts and guests; bookings count is gameable via short stays. \| +\| Uber \| Rides completed (not requests) \| Completion includes the driver-side fulfillment; requests alone misses the supply-side metric. \| +\| Etsy \| GMV per active buyer \| GMV per buyer is more stable than total GMV; it tracks user value rather than top-line growth alone. \| + +### Conversion-driven products (SaaS subscription) + +The product is sold via subscription; the NSM tracks recurring engagement that drives renewal. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| HubSpot \| Activated workspaces (defined as workspaces using 3+ products) \| Multi-product use is the activation signal that drives expansion revenue. \| +\| Stripe (developer-side) \| Production payments processed per merchant per week \| Captures the core transaction; per-merchant per-week filters for active integrations. \| +\| Calendly \| Meetings booked via Calendly per user per week \| The exact value delivered (meetings booked) and the recurring cadence. \| + +### Content-driven products (media, publishing) + +The product delivers value through content consumption. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Spotify \| Hours listened per active user \| Hours captures depth of engagement; per active user normalizes for catalog growth. \| +\| YouTube (creator-side) \| Watch time per video per audience cohort \| Watch time is the core metric that drives ads and creator earnings. \| +\| Substack (writer-side) \| Paid subscribers added per month \| The action that converts to revenue; not just total subscribers (which is lagging). \| + +--- + +## Anti-patterns + +Six NSMs that consistently produce the wrong incentives. + +### Bad NSM 1: signups + +Captures top-of-funnel volume, not value. A team optimizing for signups loosens activation criteria and chases low-quality acquisition channels. The NSM grows; the business does not. + +### Bad NSM 2: revenue + +Lagging, not action-oriented. The team can optimize against revenue only by changing pricing or sales tactics. Revenue is the trailing outcome; the NSM should be the leading action that produces revenue. + +### Bad NSM 3: DAU (daily active users) + +Useful for engagement-driven products with a daily cadence. Misleading for products with a longer cadence (weekly, monthly). DAU on a B2B SaaS often shows an unhealthy daily ritual the product does not actually need. + +### Bad NSM 4: page views or sessions + +Captures traffic, not value. A team optimizing for page views or sessions loosens content quality and adds engagement loops that do not deliver user value. + +### Bad NSM 5: feature usage + +The team optimizes for "feature X used" by promoting feature X aggressively. The feature usage grows; the underlying user value may not. NSM should capture cross-cutting value, not feature-specific use. + +### Bad NSM 6: reviews or NPS + +Captures sentiment, not value. NPS is useful as a health metric but a poor NSM because it is heavily influenced by survey design and customer-service interactions, neither of which the product team controls directly. + +--- + +## Supporting metrics framework + +The NSM does not stand alone. Around it lives a framework of input metrics and health metrics. + +### One NSM + +The single number the team optimizes against. + +### Three to five input metrics + +The metrics that drive the NSM. If the input metrics improve, the NSM should follow. + +For "weekly active editors" (Figma's NSM): +- Signups per week (the top of the funnel) +- Signup-to-active conversion rate (the activation step) +- Week-over-week active retention (the repeat-use step) + +For "messages sent in workspaces of 3+ active users per week" (Slack's NSM): +- Workspaces created per week +- Workspaces reaching 3+ active members +- Messages per active workspace per week + +The team's roadmap should map every initiative to one or more input metrics. + +### Five to ten health metrics + +Metrics that warn of problems. They should not regress while the NSM grows. + +- Monthly churn rate +- Account-level concentration (is growth coming from one big customer?) +- Support ticket volume per active user +- Latency or error rate +- Activation rate (signup-to-NSM-action) + +If any health metric regresses while the NSM grows, the team should investigate before declaring success. + +--- + +## Migration patterns when changing NSM + +The NSM should change rarely. When it does, the migration is high-risk. + +### Pattern 1: phased migration + +Run both NSMs in parallel for a quarter. Track team behavior; document where the new NSM produces different incentives. Decide based on real evidence, not speculation. + +### Pattern 2: shadow mode first + +The new NSM is tracked privately by the data team. The team continues to optimize against the old NSM. After 90 days, the data team reports on the divergence. Public switch happens only if the new NSM clearly aligns better with business outcomes. + +### Pattern 3: replace plus reinforce + +The new NSM replaces the old. The old metric becomes a health metric (still tracked, no longer the primary target). Over the next 6 months, ensure the old metric does not regress while the new NSM grows. + +--- + +## When to refuse to change the NSM + +Three signs that a proposed NSM change is wrong. + +1. The change is reactive to a single quarter's bad numbers. "Our NSM went down so we should change the NSM" is not a reason to change the NSM. +2. The proposed new NSM is gameable. A new NSM that the team can grow without delivering user value is worse than the existing NSM, even if the old one is imperfect. +3. The change has no concrete decision the team will make differently. If switching from old NSM to new NSM does not change which initiatives the team prioritizes, the change is theater. + +The NSM should be stable for years. Change it when the business model changes substantively or when the existing NSM is producing demonstrably wrong incentives. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md new file mode 100644 index 0000000..7c75d02 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/property-design-patterns.md @@ -0,0 +1,168 @@ +# Property design patterns + +Event-level vs user-level properties, with type discipline and a worked example. + +The principle. Event-level properties describe a specific event. User-level properties describe a user across all events. Mixing them up creates payload bloat, schema drift, and reporting confusion. + +--- + +## Event-level vs user-level + +Event-level properties belong on the event payload. They describe the specific event, snapshot at the moment it fires. + +- `cart_value` on `checkout_completed` +- `item_count` on `checkout_completed` +- `payment_method` on `checkout_completed` +- `discount_code` on `checkout_completed` +- `referrer_source` on `user_signed_up` + +User-level properties belong on the user profile. They describe the user over time. Set them once; the analytics tool joins them onto every event the user fires. + +- `subscription_tier` +- `acquisition_channel` +- `lifetime_value` +- `account_role` +- `is_admin` +- `last_active_at` + +The trap. Putting user-level properties on every event payload. Three problems. + +1. Payload bloat. Every event carries the same `subscription_tier` value. Multiplied across millions of events, the storage and bandwidth cost is real. +2. Schema drift when the value changes. A user upgrades mid-session. Some events have `subscription_tier: free`; later events have `subscription_tier: pro`. Reporting becomes ambiguous about which value to use. +3. Reporting confusion. Analyst writes "WHERE subscription_tier = 'pro'" thinking they are filtering users. The query actually filters events, returning a different cohort. + +The fix. Set user-level properties on the user profile via the platform's identify/track-user API. Let the analytics tool perform the join. + +--- + +## Type discipline + +Property types matter. The analytics tool will accept any value, but the reporting breaks when types are inconsistent. + +Strings for enumerable values. + +- `status`, `tier`, `channel`, `region`, `category` +- Bounded sets. Document the allowed values in the schema. +- Wrong: storing numbers as strings. `quantity: "5"` breaks every numeric aggregation. + +Numbers for actual numbers. + +- `count`, `value`, `duration_s`, `score` +- Cents (or smallest unit) for money. Never floats. `price_cents: 1999`, not `price: 19.99`. +- Wrong: `trial_day: "day 7"`. Use `trial_day: 7`. + +Booleans for actual booleans. + +- `is_admin`, `has_trial`, `is_new_user` +- Two values: `true` and `false`. Nothing else. Not "yes"/"no", not 1/0, not strings. +- Prefix discipline: `is_`, `has_`, `can_`. Reading the property name should suggest a yes/no question. + +Timestamps in ISO 8601, always. + +- `created_at`, `last_active_at`, `event_timestamp` +- Format: `2026-05-05T14:30:00Z` (UTC, with the Z suffix). +- Wrong: Unix timestamps as strings, locale-specific formats, or any other variant. ISO 8601 across the entire schema. +- Suffix discipline: `_at` for timestamps, `_s` or `_ms` for durations. + +Arrays rarely. + +- An array property usually means you should split into multiple events with one item per event. +- Example: instead of `cart.items: [item_a, item_b, item_c]` on `checkout_completed`, fire one `item_purchased` event per item plus one `checkout_completed` event with the item count. +- Exception: small bounded arrays where the use case is clear (e.g., `tag_list: ["urgent", "billing"]`). + +--- + +## Worked example: product_viewed event + +A `product_viewed` event fires when a user views a product detail page in an e-commerce app. + +### Wrong design + +```json +{ + "event": "Product Viewed", + "user_id": "u_12345", + "product": "Premium Hoodie", + "price": "$49.99", + "category": "Apparel", + "user_subscription_tier": "Premium", + "user_lifetime_purchases": 8, + "user_acquisition_source": "Meta", + "is_premium_user": "true", + "viewed_at": "5/5/2026 2:30 PM", + "tags": "summer, hoodie, sale" +} +``` + +Problems. + +- Event name uses spaces and mixed case. `Product Viewed` should be `product_viewed`. +- `price` is a money string with currency symbol. Should be `price_cents: 4999`. +- User-level properties on the event: `user_subscription_tier`, `user_lifetime_purchases`, `user_acquisition_source`, `is_premium_user`. These belong on the user profile. +- `is_premium_user` is a string `"true"`, not a boolean. +- `viewed_at` is a locale-specific date format. Should be ISO 8601: `2026-05-05T14:30:00Z`. +- `tags` is a comma-delimited string. Should be an array of strings, or split into separate events. +- `product` is the human-readable name; lacks the stable identifier. Should include `product_id`. + +### Right design + +User profile (set via `identify`): + +```json +{ + "user_id": "u_12345", + "subscription_tier": "premium", + "lifetime_purchase_count": 8, + "acquisition_channel": "meta", + "is_premium": true, + "last_active_at": "2026-05-05T14:30:00Z" +} +``` + +Event payload (`product_viewed`): + +```json +{ + "event": "product_viewed", + "user_id": "u_12345", + "product_id": "p_premium_hoodie_v2", + "product_name": "Premium Hoodie", + "price_cents": 4999, + "currency": "USD", + "category": "apparel", + "tag_list": ["summer", "hoodie", "sale"], + "viewed_at": "2026-05-05T14:30:00Z" +} +``` + +Differences. + +- Event name is `snake_case`. +- Money in cents with currency named. +- User-level properties live on the user profile, not the event. The analytics tool joins them. +- Boolean is an actual boolean. +- Timestamp is ISO 8601 UTC. +- Tags are a bounded array (acceptable here because the use case is faceted filtering). +- Stable identifier (`product_id`) included alongside the human-readable name. + +--- + +## When to put a property on every event + +A small set of properties should appear on every event regardless of category. + +- `app_version` and `platform` (web, ios, android, desktop) +- `device_type` and `device_id` +- `session_id` +- `experiment_assignments` if the user is in active experiments + +These are technically event-level (they describe the context of the event) but they are required across every event for path analysis and segmentation. + +--- + +## Common property design mistakes + +- Property names that are also event names. `signup` as a property and `signup` as an event creates queries that depend on context. Disambiguate. +- Free-text properties for things that should be enums. "Where did you hear about us?" with free-text answers produces 47 unique values that map to 5 actual channels. Force the enum at collection time. +- Storing PII in properties. Email addresses, full names, phone numbers should not be in event properties. Use a hashed identifier and look up PII separately. +- Reusing property names across events with different meanings. `source` on `user_signed_up` means acquisition source. `source` on `email_opened` means email campaign source. Same name, different meaning, breaks queries. diff --git a/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md b/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md new file mode 100644 index 0000000..cd610a4 --- /dev/null +++ b/dist/pi/.agents/skills/product-analytics-setup/references/schema-versioning-patterns.md @@ -0,0 +1,167 @@ +# Schema versioning patterns + +Schema changes are inevitable. The discipline is distinguishing safe changes from breaking ones, then versioning the breaking ones. + +--- + +## Additive vs breaking changes + +Additive changes are safe. They preserve existing dashboards and queries. + +- New event. `feature_y_used` ships alongside existing events. Old dashboards continue to work. +- New property on an existing event. `checkout_completed` gains a `discount_code` property. Old dashboards ignore it; new dashboards can use it. +- New value in an enum. The `acquisition_channel` enum gains `"tiktok"`. Old dashboards may filter incorrectly if they hard-code values; usually low-risk. + +Breaking changes require migration. + +- Renamed event. `signup_complete` becomes `user_signed_up`. Every dashboard, query, and saved cohort referencing the old name breaks. +- Removed property. `cart_value_cents` is removed because it was redundant with `total_value_cents`. Queries referencing the removed property fail. +- Changed property type. `price` was a string; now it is a number. Existing queries cast or compare differently. +- Narrowed enum. `acquisition_channel` previously had `"organic"` and `"paid"`; the new schema removes `"organic"` and replaces it with `"organic_search"` and `"organic_social"`. Old queries break. +- Changed semantics. The same event name now fires under different conditions. The dashboard reading "weekly active users" silently gets a different number. + +The rule. If old code or old queries continue to work after the change, it is additive. Otherwise, it is breaking. + +--- + +## The `_v2` suffix pattern + +Versioning in the event name makes the change visible at every layer. + +``` +checkout_completed <- v1, fires alongside v2 during transition +checkout_completed_v2 <- new semantics, new schema +``` + +The transition. + +1. Phase 1: ship v2 alongside v1. Both events fire. Dashboards continue to read v1. New queries can use v2. +2. Phase 2: migrate dashboards. Update every saved query, dashboard tile, and downstream consumer to read v2. Document each migration. +3. Phase 3: deprecate v1. Stop firing v1. Mark it deprecated in the schema. Remove from event tracking instrumentation. +4. Phase 4: cleanup. Six months after deprecation, remove v1 from any historical reference documentation. Existing v1 data in the warehouse stays for historical analysis but is not used in current dashboards. + +Typical transition window. 90 days from v2 ship to v1 deprecation. Longer if the team is small or the dashboard inventory is large. + +--- + +## The data contract idea + +The canonical schema lives in code, not in the analytics tool. + +### TypeScript interface + +```typescript +// schema/events.ts + +export interface CheckoutCompletedEvent { + event: "checkout_completed"; + user_id: string; + account_id: string; + cart_value_cents: number; + currency: string; + item_count: number; + payment_method: "card" \| "paypal" \| "apple_pay" \| "google_pay"; + discount_code?: string; + event_timestamp: string; // ISO 8601 UTC +} + +export interface UserSignedUpEvent { + event: "user_signed_up"; + user_id: string; + account_id: string; + signup_source: "homepage" \| "pricing_page" \| "blog" \| "invite" \| "other"; + referrer_source: string \| null; + event_timestamp: string; +} + +export type AnalyticsEvent = + \| CheckoutCompletedEvent + \| UserSignedUpEvent; + // ... etc. +``` + +The interface is the contract. TypeScript catches type mismatches at compile time. The CI pipeline runs the type check. + +### JSON Schema + +For non-TypeScript projects, JSON Schema serves the same role. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "checkout_completed", + "type": "object", + "required": ["event", "user_id", "account_id", "cart_value_cents", "currency", "item_count", "payment_method", "event_timestamp"], + "properties": { + "event": { "const": "checkout_completed" }, + "user_id": { "type": "string" }, + "account_id": { "type": "string" }, + "cart_value_cents": { "type": "integer", "minimum": 0 }, + "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, + "item_count": { "type": "integer", "minimum": 1 }, + "payment_method": { "enum": ["card", "paypal", "apple_pay", "google_pay"] }, + "discount_code": { "type": "string" }, + "event_timestamp": { "type": "string", "format": "date-time" } + } +} +``` + +A CI step validates events against the schema before they ship. + +--- + +## CI lint patterns + +Three lint rules catch most schema drift. + +1. Type validation. Every event payload validates against its declared type. Failed validations fail the build. +2. Naming convention check. Event names match snake_case. Property names match snake_case. Boolean properties have `is_`, `has_`, or `can_` prefix. +3. Forbidden-event check. Removed or deprecated events do not appear in the codebase. The deploy that adds a deprecated event back fails. + +Implementation. A pre-commit hook plus a GitHub Actions workflow plus a runtime sampling check (random 1% of events validated against the schema in production; failures alert). + +--- + +## Migration patterns for breaking changes + +Three common migration patterns. + +### Pattern 1: rename + +The event name changes. The semantics are the same. + +1. Ship v2 with the new name; old name continues to fire. +2. Migrate dashboards, queries, saved cohorts. +3. Deprecate v1. + +### Pattern 2: split + +One event splits into two or more events with narrower meanings. + +1. Ship the new events; the old event continues to fire alongside. +2. Update tracking code to fire the appropriate new event instead of the old one. +3. Migrate dashboards. +4. Deprecate the old event. + +Example. `subscription_changed` splits into `subscription_upgraded` and `subscription_downgraded`. Both new events provide more analytical power than the old single event. + +### Pattern 3: merge + +Two events merge into one event with a discriminating property. + +1. Ship the new event with the discriminating property. +2. Update tracking code to fire the new event with the appropriate property value. +3. Migrate dashboards (often: queries that filtered on event name now filter on property value). +4. Deprecate the old events. + +Example. `signup_via_facebook` and `signup_via_google` merge into `user_signed_up` with `auth_method: "facebook" \| "google"`. + +--- + +## Common schema versioning mistakes + +- Renaming events without versioning. The dashboards break overnight; the team blames the analytics tool. +- Skipping the transition period. v2 ships and v1 stops firing the same day. Historical analysis of v1 data is fine, but in-flight queries break. +- Versioning everything pre-emptively. `event_v3_v2` is overkill. Version when semantics change, not at every iteration. +- Letting the analytics tool be the schema source of truth. The tool's "events you have ever fired" list is a graveyard, not a contract. Maintain the schema in code; export to the tool. +- No CI enforcement. The discipline becomes an etiquette that decays as the team grows. Enforcement is the only thing that scales. diff --git a/dist/pi/.agents/skills/product-configurator-design/SKILL.md b/dist/pi/.agents/skills/product-configurator-design/SKILL.md new file mode 100644 index 0000000..593b80c --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/SKILL.md @@ -0,0 +1,289 @@ +--- +name: product-configurator-design +description: "Designing build-your-own product configurators (Tesla-style, custom-pricing, plan-builders) with constraint logic, real-time pricing, validation, and save-and-share mechanics. Honest about infinite-options (decision paralysis), canned-bundles-only (no real customization), and guided-configuration (smart defaults plus meaningful constraints plus escape hatches) patterns. Triggers on configurator design, build-your-own, custom configuration, plan builder, product customizer, configuration tool. Also triggers when users abandon mid-configuration, when configurator conversion is poor, or when a configurator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive product configurators. Distinguishes infinite-options (decision paralysis from too many options) from canned-bundles-only (no real customization) from guided-configuration (smart defaults plus meaningful constraints plus escape hatches)" +display_order: 12 +--- + +# Product Configurator Design + +A senior product marketing director's playbook for designing build-your-own product configurators. Tesla-style vehicle configurators, custom-pricing builders, plan-builders, product customizers. Constraint logic, real-time pricing, validation, save-and-share mechanics. The discipline of building a configurator that produces configurations users actually commit to. + +Most configurators fail in one of two ways. They expose every parameter at full granularity (47 toggles, 12 sliders) and produce decision paralysis; users abandon halfway through. Or they pretend to be configurators but are actually three pre-built bundles labeled "Custom"; the configurator framing was marketing while the product is bundles. + +The configurators that work do something different. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations and surface why; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Users feel guided rather than overwhelmed. + +The voice is the senior product marketing director who has watched configurators double conversion when redesigned with smart defaults and watched them collapse when "more options" were added without constraint logic. Practical, opinionated about the constraints that protect users from themselves, willing to call out when canned bundles are the right answer. + +When to use this skill: scoping a build-your-own configurator for the first time, auditing a configurator with high abandonment, designing the constraint logic that prevents invalid combinations, or deciding which parameters earn exposure vs which should default. + +--- + +## What this skill covers + +This skill spans build-your-own product configurators. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number from inputs. This skill builds a product configuration with multiple decisions. +- `comparison-tool-design` is comparing known options. This skill builds a custom option. +- `multi-step-form-design` is data capture. This skill is configuration design. +- `product-configurator-design` (this skill) is constraint logic, real-time pricing, validation, save-and-share, and configurator-to-cart handoff. +- `pm-spec-writing` is the spec for engineers building the configurator. + +The audience: product marketers, growth marketers, ecommerce teams, B2B teams shipping configurable products, agencies running configurator work for clients. + +Out of scope: calculator design (covered by `calculator-design`); comparison tools (covered by `comparison-tool-design`); the engineering implementation; specific configurator-platform configurations (those stay implementation-side). + +--- + +## The configurator decision: when configurators earn investment vs when bundles suffice + +Before designing the configurator, decide whether a configurator is the right answer. + +Configurators earn investment when: + +- The product has genuinely customizable parameters that affect outcome and cost. +- The audience values customization beyond what bundles offer. +- The team can support the configuration logic (validation, pricing, fulfillment). +- The combinatorial space is meaningful but constrained (not literally infinite). + +Configurators do NOT earn investment when: + +- The product is essentially bundles. Calling them "configurations" is marketing, not product. +- The audience does not value customization. Some audiences want to choose from curated options, not build. +- The combinatorial space is so large that no audience can navigate it. +- Customization produces invalid combinations the team cannot prevent. +- A simpler comparison or selection tool would serve. + +The decision is not "should we have a configurator"; it is "is the configurator the right tool for this product and audience." + +Detail in [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md). + +--- + +## Infinite-options vs canned-bundles-only vs guided-configuration + +The keystone framing. + +Infinite-options. Every parameter exposed at full granularity. 47 toggle switches and 12 sliders. Decision paralysis. Users abandon halfway through; few complete a configuration. Cost: design effort produces a configurator nobody completes; conversion suffers. + +Canned-bundles-only. "Configurator" that is actually three pre-built bundles labeled Basic/Pro/Enterprise. No real customization. The configurator framing was marketing; the product is bundles. Cost: audience that came expecting customization feels deceived; conversion suffers because expectations did not match reality. + +Guided-configuration. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Cost: design effort upfront is significant; conversion typically improves meaningfully because users complete configurations they commit to. + +The litmus test. Hand the configurator to a stranger in the target audience. Do they reach a configuration they would actually buy in under 5 minutes without expert help? If yes, guided-configuration. If they paralyze at the options, infinite-options. If they only see bundles, canned-bundles-only. + +--- + +## Default-configuration design + +The starting point. + +The principle. The configurator opens with a sensible default configuration. The user adjusts from there. + +Default selection. + +- The configuration most audiences would choose. +- Reflects audience research (sales-call mining, prior configurations). +- Inferable from referrer, query, or stated preference. + +Default presentation. + +- Default visible immediately; user sees a complete configuration with price. +- Adjust controls obvious; user knows what is changeable. +- Reset-to-default available; users who experiment can return. + +The blank-canvas trap. Configurator opens empty; user must build from scratch. Decision paralysis at the start. + +The cure. Default-heavy. The user adjusts; never builds from zero. + +Detail in [`references/default-configuration-design.md`](references/default-configuration-design.md). + +--- + +## Constraint logic + +Preventing invalid combinations; surfacing why. + +The principle. The configurator should not let users build invalid configurations (combinations that cannot ship, cannot be priced, or do not work together). When constraints engage, the configurator surfaces why. + +Constraint patterns. + +- Hard constraints. "Option A and Option B are incompatible." Configurator prevents the combination; explains why. +- Soft constraints. "Combining Option A with Option C is unusual but possible." Configurator allows; warns. +- Implication constraints. "Selecting Option A requires Option D." Configurator auto-includes D; explains. +- Capacity constraints. "This configuration exceeds shipping capacity." Configurator caps; explains. + +Constraint communication. + +- Why this constraint engaged. +- What user can do (different option, contact for custom). +- No friction-only blocking; always offer a path. + +The over-constrained trap. Too many constraints; user feels boxed in. + +The under-constrained trap. User builds configuration that fails at checkout or fulfillment. + +Detail in [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md). + +--- + +## Real-time pricing and impact display + +Pricing that responds to choices. + +The principle. Price updates as the user adjusts. The user sees the cost impact of each choice immediately. + +Strong pricing display. + +- Total price prominent and updated in real time. +- Per-choice impact visible ("Adds $X" or "Saves $X"). +- Breakdown available ("How is this priced"). +- Currency and locale appropriate. + +Weak pricing display. + +- Price hidden until the end. +- Per-choice impact invisible; user does not know what each option costs. +- Breakdown not available; total is opaque. + +The price-shock trap. User configures heavily; reaches checkout; sees a price they did not expect; abandons. + +The cure. Price visible throughout. No surprises at checkout. + +Detail in [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md). + +--- + +## Validation and error patterns + +When the configurator catches invalid input. + +The principle. Validation should be helpful, not punitive. + +Validation patterns. + +- Inline validation. Error appears next to the invalid choice. +- Pre-emptive validation. Constraint logic prevents the error from being possible. +- Final validation. Pre-checkout review surfaces any remaining issues. + +Error communication. + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +The validation-strict trap. Validation rejects valid edge-case inputs. + +The validation-loose trap. Configurator accepts inputs that fail downstream. + +Detail in [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md). + +--- + +## Save-and-share mechanics + +Configurations users return to or send to others. + +The principle. Configurators that serve real decision-making produce configurations users want to save and share. + +Save patterns. + +- Email-link save. User enters email; configuration link emailed. +- Account-based save. Logged-in users save automatically. +- Anonymous-session save. Browser-based persistence. + +Share patterns. + +- Shareable URL. Configuration encoded in URL; share via any channel. +- Embed code. Configuration embeddable on other sites or in proposals. +- Email share. Direct email-to-recipient with configuration. + +Why save-and-share matters. + +- Multi-decision purchases require deliberation. +- B2B configurations often need stakeholder review. +- Returning users continue rather than restart. + +Detail in [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md). + +--- + +## Configurator-to-cart handoff + +When the user commits. + +The principle. Handoff from configurator to cart should preserve the configuration entirely. + +Handoff patterns. + +- Configuration becomes the cart item. +- Cart shows the configuration summary. +- Edit-from-cart returns to configurator with state preserved. + +The handoff failure. Configuration partially preserved; cart shows a generic SKU; user cannot tell if their custom build is reflected. + +The cure. Handoff loop closed. Configuration visible in cart; price matches; edits possible. + +Detail in [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-configurator-failures.md`](references/common-configurator-failures.md). + +- "Users abandon halfway through configuration." Likely infinite-options pattern; too many decisions. +- "Configurator generates valid-looking configs that fail at fulfillment." Under-constrained; constraint logic missing. +- "Users complain about price surprises at checkout." Pricing not real-time or hidden until end. +- "Sales says many users contact for help configuring." Configurator too complex for audience; defaults wrong. +- "Users save configurations but do not return." Save mechanism works but follow-up missing. +- "Configurator works on desktop, breaks on mobile." Mobile UX broken. +- "Audience completes but conversion to purchase is low." Configurator works; commitment friction at handoff. +- "We added more options; abandonment climbed." Crossed the cognitive-load threshold. +- "Constraint engaged but user did not understand why." Communication broken; users feel arbitrarily blocked. + +--- + +## The framework: 12 considerations for configurator design + +When designing or auditing a configurator, walk these 12 considerations. + +1. The configurator decision. Is configurator the right tool, or do bundles serve? +2. Guided-configuration, not infinite-options or canned-bundles-only. Smart defaults plus meaningful constraints plus escape hatches. +3. Default configuration sensible. User adjusts from default; does not build from zero. +4. Constraint logic prevents invalid combinations. Hard, soft, implication, capacity constraints. +5. Constraint communication clear. Why constraint engaged; what user can do. +6. Real-time pricing visible. Price updates with choices; breakdown available. +7. Validation helpful. Inline; specific; offers paths. +8. Save-and-share works. Multi-session; shareable; B2B-friendly. +9. Configurator-to-cart handoff preserves state. Cart shows configuration. +10. Mobile parity. Configurator works on the devices the audience uses. +11. Conversion as success metric. Not just completion rate; downstream purchase. +12. Maintenance discipline. Configurations updated as product changes; quarterly audit. + +The output of the framework is a configurator that earns the configuration that ships, with constraint logic, pricing, and handoff working together to produce commitments users keep. + +--- + +## Reference files + +- [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md) - When configurators earn the build vs when bundles serve. +- [`references/default-configuration-design.md`](references/default-configuration-design.md) - The starting point. Default selection and presentation. +- [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md) - Hard, soft, implication, capacity constraints. Communication patterns. +- [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md) - Price updates with choices. Breakdown and impact display. +- [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md) - Helpful validation. Inline, pre-emptive, final. +- [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md) - Email-link, account, anonymous, shareable URL, embed. +- [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md) - Handoff that preserves configuration; cart visibility; edit-from-cart. +- [`references/configurator-anti-patterns.md`](references/configurator-anti-patterns.md) - The patterns that look like configurators but degrade conversion. +- [`references/common-configurator-failures.md`](references/common-configurator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: configurators earn investment when they earn the configuration that ships + +The configurators that work as compounding assets are the ones that produce configurations users commit to. Not 50-cell decision matrices. Not bundles dressed as configurators. Configurations the user built, priced, validated, saved, and bought. + +That is the bar. Below the bar are infinite-options (decision paralysis; users abandon) and canned-bundles-only (configurator framing without real customization; users feel deceived). Above the bar are guided-configuration tools where smart defaults, meaningful constraints, real-time pricing, validation, and save-and-share work together to produce commitments. + +The discipline is in the design choices. The decision to build a configurator at all. The default configuration that opens the experience. The constraint logic that protects users from invalid combinations. The pricing that updates with choices. The validation that helps without punishing. The save-and-share that supports multi-decision purchases. The cart handoff that preserves the configuration. The maintenance that keeps the configurator in sync with the product it represents. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md b/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md new file mode 100644 index 0000000..2e5c19c --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/common-configurator-failures.md @@ -0,0 +1,179 @@ +# Common configurator failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Users abandon halfway through configuration." + +The diagnosis. Likely infinite-options pattern; too many decisions. + +The cure. Smart defaults; reduce option count; escape hatches into deeper customization. + +--- + +## "Configurator generates valid-looking configs that fail at fulfillment." + +The diagnosis. Under-constrained; constraint logic missing. + +The cure. Add constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## "Users complain about price surprises at checkout." + +The diagnosis. Pricing not real-time or hidden until end. + +The cure. Real-time pricing throughout. Detail in `references/real-time-pricing-patterns.md`. + +--- + +## "Sales says many users contact for help configuring." + +The diagnosis. Configurator too complex for audience; defaults wrong. + +The cure. Audit defaults; reduce option exposure; consider canned bundles for simple cases. + +--- + +## "Users save configurations but do not return." + +The diagnosis. Save mechanism works but follow-up missing. + +The cure. Reminder email after save; nudge before configuration expires. + +--- + +## "Configurator works on desktop, breaks on mobile." + +The diagnosis. Mobile UX broken. + +The cure. Mobile-first design and testing. + +--- + +## "Audience completes but conversion to purchase is low." + +The diagnosis. Configurator works; commitment friction at handoff. + +The cure. Audit cart handoff; ensure configuration preserved; reduce checkout friction. + +--- + +## "We added more options; abandonment climbed." + +The diagnosis. Crossed cognitive-load threshold. + +The cure. Cut options; surface fewer; defer complexity behind escape hatches. + +--- + +## "Constraint engaged but user did not understand why." + +The diagnosis. Communication broken. + +The cure. Constraint copy specific; explains why; offers paths. + +--- + +## "Configurations frequently differ from cart." + +The diagnosis. Handoff broken. + +The cure. Test cart handoff. Configuration ID system; single pricing source. + +--- + +## "Sales says enterprise customers want full configurations sales-led." + +The diagnosis. Enterprise audience wants white-glove; configurator self-serve does not match expectation. + +The cure. Enterprise path: configurator surfaces "Talk to sales for custom" for above-threshold configurations. + +--- + +## "We A/B tested adding more options; conversion went down." + +The diagnosis. Crossed the threshold. + +The cure. More is not always better. Maintain option discipline. + +--- + +## "Returning users see different prices than they saved." + +The diagnosis. Pricing shifted; configurator silently updated. + +The cure. Honest about price changes on resume. + +--- + +## "Mobile configuration completion is half of desktop." + +The diagnosis. Mobile UX significantly worse. + +The cure. Mobile-first redesign; reduce option exposure on mobile. + +--- + +## "Validation rejects valid international inputs." + +The diagnosis. Validation too strict. + +The cure. Audit validation rules; allow international formats. + +--- + +## "Some configurations work; others fail post-checkout." + +The diagnosis. Constraint logic incomplete; some invalid combinations slip through. + +The cure. Audit constraints. Add missing rules. + +--- + +## "Configurator's average configuration is more expensive than baseline." + +The diagnosis. May not be a problem (real customization adds cost) or may be (default biased toward expensive). + +The cure. Audit defaults. Defaults should reflect typical use, not flatter revenue. + +--- + +## "Sales pipeline shrunk after configurator launch; people self-serve." + +The diagnosis. Configurator absorbed the audience that would have called. + +The cure. This may be intentional (cost reduction) or unintentional (loss of complex deals). Decide if the shift is desired. + +--- + +## "Configurator launched; analytics broke." + +The diagnosis. Instrumentation missed. + +The cure. Verify analytics post-launch. Per-step instrumentation for diagnostic. + +--- + +## The pattern across failures + +Most configurator failures fall into one of three patterns. + +Pattern 1: Cognitive overload. Infinite-options, too many decisions, no defaults. The fix is guided-configuration. + +Pattern 2: Trust damage. Hidden pricing, price drift, unclear constraints, lost state. The fix is transparency. + +Pattern 3: Handoff failures. Cart loses configuration; checkout disappears it. The fix is loop closure. + +The metric pattern: configurator failures often look fine on engagement. Signal is in completion rate, conversion to purchase, downstream order accuracy. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (cognitive overload, trust damage, handoff). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md new file mode 100644 index 0000000..d31b61b --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-anti-patterns.md @@ -0,0 +1,193 @@ +# Configurator anti-patterns + +The patterns that look like configurators but degrade conversion. Easy to ship; the cost shows up in completion rates, downstream conversion, and brand trust. + +--- + +## The infinite-options configurator + +The pattern. Every parameter exposed at full granularity. + +The signal. Decision paralysis; high abandonment. + +The cure. Smart defaults; meaningful constraints; escape hatches into deeper customization. + +--- + +## The canned-bundles-only configurator + +The pattern. Three pre-built bundles labeled "Custom." + +The signal. Audience expecting customization feels deceived. + +The cure. Real configuration logic; or honest bundle framing. + +--- + +## The blank-canvas configurator + +The pattern. Configurator opens empty; user must build from scratch. + +The signal. First-step abandonment. + +The cure. Default-heavy. Open with sensible default. + +--- + +## The hidden-pricing configurator + +The pattern. Price not visible until checkout. + +The signal. Users abandon at checkout when total surprises. + +The cure. Real-time pricing throughout. + +--- + +## The under-constrained configurator + +The pattern. User can build invalid configurations that fail downstream. + +The signal. Sales gets calls about failed orders. + +The cure. Constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## The over-constrained configurator + +The pattern. Too many constraints; user feels boxed in. + +The signal. User abandons; sales gets calls for "custom" configurations. + +The cure. Reduce constraints to genuine requirements; offer custom path for edge cases. + +--- + +## The unclear-constraint configurator + +The pattern. Constraint engages without explanation. + +The signal. Users confused; bounce rate climbs. + +The cure. Constraint communication. Why constraint engaged; what user can do. + +--- + +## The lose-state-on-error configurator + +The pattern. Validation engages; configuration resets. + +The signal. Users abandon at first error. + +The cure. Preserve state; errors local. + +--- + +## The mobile-broken configurator + +The pattern. Configurator works on desktop; breaks on mobile. + +The signal. Mobile completion much lower than desktop. + +The cure. Mobile-first design. + +--- + +## The lost-on-cart configurator + +The pattern. Cart shows generic SKU; configuration not visible. + +The signal. Users edit; configurator restarts; abandonment. + +The cure. Cart presentation preserves configuration. + +--- + +## The price-drift configurator + +The pattern. Configurator shows one price; cart shows another. + +The signal. Users feel deceived. + +The cure. Single source of truth for pricing. + +--- + +## The save-mechanism-broken configurator + +The pattern. User saves; recovery link broken; configuration lost. + +The signal. Users complain; abandonment increases on long configurations. + +The cure. Test save mechanism end-to-end. + +--- + +## The validation-strict configurator + +The pattern. Validation rejects valid edge-case inputs. + +The signal. Users with valid inputs cannot proceed. + +The cure. Audit validation; allow international, plus-aliased, non-Latin inputs. + +--- + +## The unmaintained configurator + +The pattern. Product changed; configurator did not. + +The signal. Configurator references deprecated options; pricing wrong. + +The cure. Quarterly maintenance; product changes trigger configurator updates. + +--- + +## The aggressive-pricing-anchoring configurator + +The pattern. Strikethrough prices that were never charged; "$X for a limited time" perpetually. + +The signal. Sophisticated audiences notice; trust collapses. + +The cure. Honest anchoring; real discounts only. + +--- + +## The orphan-configuration configurator + +The pattern. Configurations save; user returns; configuration valid but pricing changed silently. + +The signal. Users surprised at price difference. + +The cure. Honest about price changes on resume. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +Audit questions per configurator. + +- Is default sensible (anti-pattern check: blank-canvas)? +- Are constraints calibrated (anti-pattern check: over-constrained, under-constrained, unclear)? +- Is pricing visible and consistent (anti-pattern check: hidden-pricing, price-drift)? +- Does state preserve on error (anti-pattern check: lose-state-on-error)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Does cart preserve configuration (anti-pattern check: lost-on-cart)? +- Is validation calibrated (anti-pattern check: validation-strict)? +- Is configurator current (anti-pattern check: unmaintained)? +- Are saved configurations honest about price changes (anti-pattern check: orphan-configuration)? + +The retire decision. Configurators failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md new file mode 100644 index 0000000..60185a6 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-decision-criteria.md @@ -0,0 +1,129 @@ +# Configurator decision criteria + +When configurators earn the build vs when bundles serve. + +A configurator is meaningful work. Constraint logic, real-time pricing, validation, save-and-share, cart handoff, ongoing maintenance. The configurator earns this investment only when specific conditions are present. + +--- + +## When configurators earn the build + +Five conditions that, when present, make a configurator a strong investment. + +The product has genuinely customizable parameters that affect outcome and cost. Not just cosmetic options; real parameters that change what the user gets. + +The audience values customization beyond what bundles offer. Some audiences want choice; others prefer curated bundles. + +The team can support the configuration logic. Validation, pricing, fulfillment for variable configurations. + +The combinatorial space is meaningful but constrained. Not literally infinite; not so small that bundles would suffice. + +The success metric is defined. Configuration completion rate, configuration-to-purchase rate, average configuration price. + +When all five are present, a configurator is strong investment. When two or fewer are present, bundles often serve better. + +--- + +## When configurators do NOT earn the build + +Funnels where configurators add complexity without lift. + +The product is essentially bundles. Calling them configurations is marketing. + +The audience prefers curated options. Some audiences resent customization friction. + +The combinatorial space is too large. No audience can navigate. + +Customization produces invalid combinations. Team cannot prevent; users hit failures. + +A simpler tool would serve. Comparison, calculator, or selection tool. + +The honest assessment matters. Configurators are sometimes the wrong tool. + +--- + +## Configurators vs bundles + +When each fits. + +Bundles strengths. Simple; clear; no decision paralysis. Easy to maintain. + +Bundles weaknesses. Audiences that need customization underserved. + +Configurators strengths. Match real customer needs; capture revenue from edge cases. + +Configurators weaknesses. Build cost; complexity. + +The combined approach. Some products offer bundles AND a configurator for users who want custom. + +--- + +## The opportunity-cost frame + +Configurators are significant work. + +Build cost. Constraint logic, pricing engine, save-and-share, validation, cart integration. 60-200 engineering hours typical. + +Maintenance cost. Product changes trigger configurator updates. 4-12 hours per quarter. + +Opportunity cost. Better bundles, comparison tool, calculator. The configurator has to clear those alternatives. + +The decision frame. Configurators earn investment when they produce more revenue than bundle-only or alternative formats. + +--- + +## Decision worked example + +A B2B SaaS with seat-based + add-on pricing. + +Conditions check. + +- Genuinely customizable: yes (seats, add-ons, integrations). +- Audience values customization: yes; team size and add-ons vary. +- Team can support: yes. +- Combinatorial space: meaningful but constrained. +- Success metric: defined. + +Decision. Build the configurator. + +The decision was deliberate. + +--- + +## Decision worked example: when bundles serve + +A consumer SaaS with three plans. + +Conditions check. + +- Genuinely customizable: no; plans are bundles. +- Audience values customization: no; users pick plans. +- Combinatorial space: trivial. + +Decision. Bundles. No configurator needed. + +The decision was right-sized. + +--- + +## When to retire a configurator + +Configurators can become wrong over time. + +Retire when: + +- Conversion declined and refinements have not moved it. +- Most users default-and-purchase; customization unused. +- Product changed; configurator no longer matches. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions for configurators. The five against. Configurators vs bundles. Opportunity-cost frame. Decision worked examples. The retire decision. + +## Implementation choices that stay internal + +Specific configurator decisions for specific products. Capacity benchmarks. Tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md b/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md new file mode 100644 index 0000000..36bbf43 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/configurator-to-cart-handoff.md @@ -0,0 +1,159 @@ +# Configurator-to-cart handoff + +Handoff that preserves configuration; cart visibility; edit-from-cart. + +When the user commits, the handoff to cart determines whether the commitment sticks. Done well, handoff preserves the configuration; done poorly, the cart shows generic SKUs and the user feels their custom build was lost. + +--- + +## The preserve-the-build principle + +The configuration becomes the cart item. The cart shows the configuration. Editing returns to the configurator with state preserved. + +The win. User finishes configuration; clicks add to cart; cart shows the custom configuration with breakdown and price; user can edit, returning to configurator with all choices preserved. + +The fail. User finishes; clicks add to cart; cart shows "Custom Product - $X" with no detail. User cannot tell if their build is reflected. + +The discipline. Handoff loop closed. + +--- + +## Cart presentation + +How the configuration appears in cart. + +Configuration summary. Key choices listed (not all; not none). + +Price breakdown. Subtotal matches configurator's price. + +Edit link. Clear path back to configurator with state preserved. + +Visual. If configurator shows visual configuration, cart shows it too (or summary image). + +--- + +## Edit-from-cart + +When user wants to change. + +Pattern. Cart includes "Edit configuration" link. + +Behavior. + +- Click; return to configurator. +- All choices loaded. +- Adjust; commit; cart updates. + +The lose-state-on-edit failure. User clicks edit; configurator restarts; previous choices lost. + +The cure. State preserved through the handoff loop. + +--- + +## Multi-item handoff + +When the user configures multiple items. + +Pattern. Each configuration becomes a separate cart item with its own summary. + +Edit each independently. User can edit one without affecting others. + +--- + +## B2B configurator-to-quote + +When the configurator generates a quote rather than direct cart. + +Pattern. Configuration generates a quote; quote can be shared, approved, then converted to order. + +Strengths. B2B workflows often require approval. + +The discipline. Quote includes everything the configuration includes; conversion to order preserves. + +--- + +## Handoff to checkout + +After cart, checkout. + +The principle. Configuration details flow through checkout. Confirmation email reflects the configuration. + +The drop-config-at-checkout failure. Configuration disappears at checkout; user cannot verify. + +The cure. Configuration visible throughout the funnel. + +--- + +## Configuration ID + +The technical bridge. + +Pattern. Each configuration gets an ID. Cart, checkout, fulfillment all reference the ID. + +Strengths. Stable reference. + +Weaknesses. Requires backend infrastructure. + +--- + +## Pricing consistency + +Prices match across configurator, cart, checkout. + +The principle. No price drift between stages. + +The drift failure. Configurator shows $X; cart shows $Y; user feels deceived. + +Causes. Caching, currency conversion, tax estimation, discount expiration. + +The cure. Single source of truth for pricing; all stages query. + +--- + +## Save-and-share-to-cart + +When users return from saved configurations. + +Pattern. Saved configuration link opens configurator with state; user can add to cart from there. + +The discipline. Save mechanism integrates with cart workflow. + +--- + +## Mobile cart handoff + +On mobile, the handoff transition matters. + +Considerations. + +- Cart visible without horizontal scroll. +- Edit returns work on mobile. +- Configuration summary readable. + +--- + +## Common handoff failures + +Cart shows generic SKU. User cannot verify configuration. + +Edit restarts configurator. Previous choices lost. + +Pricing drifts between stages. User confused. + +Configuration disappears at checkout. Cannot verify. + +Multi-item handoff broken. Configurations conflict in cart. + +B2B quote misses details. Quote does not match configuration. + +Confirmation email lacks configuration. User cannot verify post-purchase. + +--- + +## Methodology-level choices that stay in the public skill + +The preserve-the-build principle. Cart presentation. Edit-from-cart. Multi-item handoff. B2B configurator-to-quote. Handoff to checkout. Configuration ID. Pricing consistency. Save-and-share-to-cart. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific cart implementations for specific configurators. Specific configuration-ID systems. Specific backend integrations. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md new file mode 100644 index 0000000..809e52b --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/constraint-logic-patterns.md @@ -0,0 +1,173 @@ +# Constraint logic patterns + +Hard, soft, implication, capacity constraints. Communication patterns. + +Constraints prevent invalid configurations. Done well, they protect users from errors and surface why; done poorly, they feel arbitrary or fail to prevent invalid configurations. + +--- + +## The protect-and-explain principle + +Constraints should prevent invalid configurations and explain why when they engage. + +The win. User selects Option A. System recognizes A is incompatible with currently-selected Option B. Inline message: "Option A and Option B are incompatible. Choose A or B." User adjusts; understands. + +The fail. User builds configuration. Submits. Backend rejects. User confused; no path forward. + +The discipline. Constraints engage at choice-time; explain why; offer paths. + +--- + +## Pattern A: Hard constraints + +Combinations that cannot exist. + +How it works. + +- Two options incompatible; configurator prevents both selected. +- User selects A; B becomes unavailable (greyed; with explanation). +- Or vice versa. + +Strengths. Prevents invalid configurations. + +Weaknesses. Can frustrate users who do not understand the constraint. + +When to use. Genuinely incompatible options. + +--- + +## Pattern B: Soft constraints + +Combinations that are unusual but possible. + +How it works. + +- User selects unusual combination. +- System warns: "This combination is unusual. Most teams choose [alternative]." +- User can proceed. + +Strengths. Respects user agency; provides guidance. + +Weaknesses. Some users will ignore warning; downstream issues. + +When to use. Combinations that work but are uncommon. + +--- + +## Pattern C: Implication constraints + +When choosing one option requires another. + +How it works. + +- User selects A. +- System auto-selects required B (or surfaces it for selection). +- Explains: "Selecting A requires B because [reason]." + +Strengths. Prevents missing-dependency errors. + +Weaknesses. Implication chains can grow complex. + +When to use. When dependencies are clear and predictable. + +--- + +## Pattern D: Capacity constraints + +Configuration exceeds product or fulfillment capacity. + +How it works. + +- User configures heavily; reaches capacity ceiling. +- System caps; explains: "Max [X] supported per configuration." +- Offers contact for custom. + +Strengths. Prevents impossible configurations. + +Weaknesses. Can frustrate enterprise audiences; offer contact for custom. + +When to use. Hard product limits. + +--- + +## Pattern E: Combinatorial constraints + +When multiple choices interact in complex ways. + +How it works. + +- Configurator evaluates the full configuration after each change. +- Constraints engage based on combinations, not individual options. +- Surface conflicts as they emerge. + +Strengths. Handles complex products. + +Weaknesses. Maintenance complexity. + +When to use. Products with genuine combinatorial constraints. + +--- + +## Constraint communication + +How constraints surface. + +Inline. Message next to the constrained choice. + +Modal. Full-screen explanation for major constraints. + +Toast. Brief notification for minor. + +The discipline. Match intensity to constraint importance. + +--- + +## Constraint copy + +What the message says. + +Strong copy. "Option A and Option B are incompatible because [specific reason]. Choose A or B." + +Weak copy. "Invalid configuration." + +The discipline. Specific; explanatory; offers paths. + +--- + +## Constraint maintenance + +Constraints decay. + +What decays. + +- Constraints from old product variants. +- Constraints inherited from deprecated options. +- New options not yet constrained. + +Maintenance cadence. Quarterly review with product changes. + +--- + +## Common constraint failures + +Over-constrained. Too many constraints; user feels boxed in. + +Under-constrained. User builds invalid configuration; fails downstream. + +Constraint without explanation. User confused by arbitrary blocking. + +Stale constraints. Inherited from old product. + +Constraint surface inappropriate. Modal for minor; toast for major. + +No path offered. Constraint blocks; user has no alternative. + +--- + +## Methodology-level choices that stay in the public skill + +The protect-and-explain principle. Patterns A through E. Constraint communication. Constraint copy. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific constraints for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md b/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md new file mode 100644 index 0000000..aee99bf --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/default-configuration-design.md @@ -0,0 +1,109 @@ +# Default-configuration design + +The starting point. Default selection and presentation. + +The configurator opens with a default configuration. Done well, the default makes the user feel guided rather than overwhelmed; done poorly, the user faces a blank canvas and abandons. + +--- + +## The default-heavy principle + +Configurators should open with a sensible default, not a blank canvas. + +The win. User opens the configurator; sees a complete configuration with price; can adjust from there. + +The fail. User opens the configurator; sees empty fields and 0 fields completed. Decision paralysis. + +The discipline. Default-heavy; user adjusts from default; never builds from zero. + +--- + +## Default selection + +Which configuration is the default. + +Common-case default. The configuration most audiences would choose. Reflects audience research. + +Inferred default. Based on referrer, query, or stated preference. + +Audience-segment default. Different defaults for different segments (small vs enterprise). + +The most-popular default. Use what most users actually pick. + +--- + +## Default presentation + +How the default appears. + +Visible immediately. User sees a complete configuration with price. + +Adjust controls obvious. User knows what is changeable. + +Reset-to-default available. Users who experiment can return to default. + +Summary-and-detail. Default shown as summary with expandable detail. + +--- + +## The blank-canvas trap + +When configurators open empty. + +The pattern. Empty fields; user must build from scratch. + +The signal. High first-step abandonment. + +The cost. Users abandon before reaching ah-ha moment of seeing a configuration. + +The cure. Default-heavy. Open with a complete configuration. + +--- + +## Default updating + +Defaults decay. + +What decays. + +- Most-popular configuration shifts. +- Audience composition changes. +- Product changes invalidate defaults. + +Maintenance cadence. Quarterly review. + +--- + +## Default-by-segment + +Different audiences may warrant different defaults. + +Pattern. Detect or ask about audience; default adapts. + +Detection. Referrer, query, stated input, or inferred from context. + +The discipline. Audience-fit defaults serve better than one-size-fits-all. + +--- + +## Common default failures + +Blank canvas. No default; user paralyzes. + +Wrong default. Most users adjust away; default does not match audience. + +Stale default. Reflects old product or pricing. + +Default obscures customization. User does not realize options exist. + +Default biased toward expensive. Default flatters revenue, not user fit. + +--- + +## Methodology-level choices that stay in the public skill + +The default-heavy principle. Default selection. Default presentation. The blank-canvas trap. Default updating. Default-by-segment. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific configurators. Specific detection logic. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md new file mode 100644 index 0000000..b562309 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/real-time-pricing-patterns.md @@ -0,0 +1,157 @@ +# Real-time pricing patterns + +Price updates with choices. Breakdown and impact display. + +Pricing that responds to choices. Done well, users see cost impact immediately; done poorly, price-shock at checkout drives abandonment. + +--- + +## The no-surprises principle + +Price visible throughout the configuration. No surprises at checkout. + +The win. Total price visible at top of configurator. Updates as user adjusts. Per-choice impact visible ("Adds $X"). Breakdown available. + +The fail. Price hidden until checkout. User configures heavily. Sees price; abandons. + +The discipline. Price visible; breakdown available; surprises eliminated. + +--- + +## Total price display + +How the total appears. + +Prominent placement. Top or top-right of configurator. + +Real-time updates. Updates immediately as user changes choices. + +Currency and locale. Match the user's locale. + +Period. Per-month, per-year, one-time. Match the product's pricing model. + +--- + +## Per-choice impact + +Showing what each option costs. + +Inline impact. "+$X/month" next to the option. + +Strikethrough for upgrades. Old price strikethrough; new price highlighted. + +Free options labeled. "Free" or "Included" explicit. + +The discipline. User can see the cost of each choice without computing. + +--- + +## Pricing breakdown + +How the total breaks down. + +Expandable breakdown. "How is this priced" toggle reveals detail. + +Categorized breakdown. Base + add-ons + fees. + +Subscription vs one-time. Recurring vs one-time costs distinguished. + +The discipline. Breakdown available on demand; not forced. + +--- + +## Annual vs monthly + +Subscription periods. + +Toggle visible. User can switch between annual and monthly. + +Discount disclosed. "Save X% with annual billing." + +Both totals shown. Annual total and monthly equivalent. + +--- + +## Hidden cost surfacing + +Costs that often hide. + +Setup fees. Disclosed at configuration; not at checkout. + +Implementation costs. If applicable, visible. + +Per-user vs flat. Mode disclosed. + +Overage pricing. What happens beyond capacity, disclosed. + +The hidden-cost trap. Costs surfaced only at checkout; user feels deceived. + +--- + +## Tax and shipping + +Where applicable. + +Tax estimate. Approximate tax visible if jurisdiction can be inferred. + +Shipping estimate. Approximate shipping visible if applicable. + +Final calculation at checkout. Estimate at configurator; final at checkout. + +The discipline. Estimates clearly labeled; final disclosed. + +--- + +## Price comparison anchoring + +Showing alternative configurations. + +Comparison anchoring. "If you upgrade to X, the price increases to Y." + +Bundle anchoring. "Equivalent bundle is Z." + +Use carefully. Anchoring can manipulate; honesty matters. + +--- + +## Pricing maintenance + +Pricing decays. + +What decays. + +- Pricing levels from old pricing models. +- Currency conversions stale. +- Discount terms expired. + +Maintenance cadence. When pricing changes, configurator pricing updates as part of the change. + +--- + +## Common pricing failures + +Hidden pricing. Total not visible until checkout. + +Per-choice impact hidden. User does not know what each choice costs. + +Surprise fees. Setup, implementation costs hidden until checkout. + +Stale pricing. Reflects old prices. + +Tax surprise. Tax not estimated; user surprised at checkout. + +Currency wrong. Local user sees wrong currency. + +No annual-vs-monthly toggle. User locked into one period. + +False discount anchoring. Strikethrough prices that were never charged. + +--- + +## Methodology-level choices that stay in the public skill + +The no-surprises principle. Total price display. Per-choice impact. Pricing breakdown. Annual vs monthly. Hidden cost surfacing. Tax and shipping. Price comparison anchoring. Pricing maintenance. Common failures. + +## Implementation choices that stay internal + +Specific pricing displays for specific configurators. Specific currency and tax logic. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md b/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md new file mode 100644 index 0000000..5ca6010 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/save-and-share-mechanics.md @@ -0,0 +1,218 @@ +# Save-and-share mechanics + +Email-link, account, anonymous, shareable URL, embed. + +Configurations users return to or send to others. Multi-decision purchases require deliberation; B2B configurations often need stakeholder review. Save-and-share supports these workflows. + +--- + +## The deliberation-friendly principle + +Configurators that serve real decision-making produce configurations users want to save and share. + +The win. User configures complex purchase. Saves via email-link. Shares with stakeholders. Returns days later. Configuration intact; price unchanged; ready to buy. + +The fail. User configures; cannot save; loses work between sessions; abandons. + +The discipline. Save mechanisms support multi-session and multi-stakeholder workflows. + +--- + +## Pattern A: Email-link save + +User enters email; link emailed. + +How it works. + +- "Save and resume later" CTA. +- User enters email. +- Link emailed; user clicks to return. + +Strengths. No account required; cross-device. + +Weaknesses. Email deliverability; link expiration. + +When to use. Default for non-authenticated configurators. + +--- + +## Pattern B: Account-based save + +Logged-in users save automatically. + +How it works. + +- User logs in. +- Configurations save to account. +- User returns; finds saved configurations. + +Strengths. Multi-configuration management. + +Weaknesses. Account creation friction. + +When to use. When configurator is part of a logged-in product. + +--- + +## Pattern C: Anonymous-session save + +Browser-based persistence. + +How it works. + +- Configuration saved to browser local storage. +- User returns same browser; configuration restored. + +Strengths. Lowest friction. + +Weaknesses. Lost on browser change; limited persistence. + +When to use. As supplement to other patterns. + +--- + +## Pattern D: Shareable URL + +Configuration encoded in URL. + +How it works. + +- Configurator encodes the configuration in URL parameters. +- User shares URL; recipient opens; sees same configuration. + +Strengths. Easy sharing across channels. + +Weaknesses. URL length; pricing may shift over time. + +When to use. Shareable configurations; B2B stakeholder review. + +--- + +## Pattern E: Embed code + +Configuration embeddable on other sites. + +How it works. + +- Configurator generates embed code. +- User pastes into other sites or proposals. + +Strengths. Used in B2B proposals. + +Weaknesses. Cross-site complexity. + +When to use. B2B sales contexts. + +--- + +## Pattern F: Hybrid + +Combining patterns. Common for production configurators. + +Common combination. Email-link save + shareable URL + anonymous-session backup. + +Strengths. Multiple paths. + +Weaknesses. Complexity. + +--- + +## Save trust communication + +Users hesitate to save partial sensitive configurations. + +What to communicate. + +- What is saved. +- How long it persists. +- Who can access it. +- How to delete. + +The discipline. Trust communication explicit; not buried in privacy policy. + +--- + +## Resume experience + +When user returns. + +The principle. Resume should be uninterrupted. + +The pattern. + +- User clicks recovery link or logs in. +- Lands at the configuration; rest preserved. +- Continues without re-doing. + +Resume failures. + +- Configuration partially preserved; values lost. +- Pricing changed; user surprised. +- Constraint logic shifted; configuration now invalid. + +The discipline. Resume preserves; communicate any changes (e.g., "Pricing has updated since you last visited"). + +--- + +## Pricing on resume + +When prices change between save and resume. + +Honest pattern. Show the saved configuration with original price; surface "Pricing has changed; updated price is X" with explanation. + +Dishonest pattern. Silently update price; user does not notice. + +The discipline. Honesty about price changes. + +--- + +## Sharing privacy + +Shared configurations may include sensitive info. + +Considerations. + +- What is in the URL/embed. +- Who can see it. +- How long links are valid. + +The discipline. Sharing respects user privacy; sensitive details may need account-based sharing rather than URL. + +--- + +## Save-and-share analytics + +Track usage. + +Metrics. + +- Save rate. +- Resume rate per saved configuration. +- Share rate. +- Configurations completed via save-and-share path. + +--- + +## Common save-and-share failures + +No save mechanism. Users lose work; abandon. + +Save mechanism brittle. Links expire; account access broken. + +Resume loses state. User lands at start; loses work. + +Pricing surprise on resume. Silent price update. + +Sharing exposes sensitive info. Embedded URLs share more than intended. + +Save trust missing. Users do not save because they distrust persistence. + +--- + +## Methodology-level choices that stay in the public skill + +The deliberation-friendly principle. Patterns A through F. Save trust communication. Resume experience. Pricing on resume. Sharing privacy. Analytics. Common failures. + +## Implementation choices that stay internal + +Specific save mechanisms for specific configurators. Specific tooling for URL encoding and embed generation. Privacy review processes. These vary by team. diff --git a/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md b/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md new file mode 100644 index 0000000..7375621 --- /dev/null +++ b/dist/pi/.agents/skills/product-configurator-design/references/validation-and-error-patterns.md @@ -0,0 +1,191 @@ +# Validation and error patterns + +Helpful validation. Inline, pre-emptive, final. + +Validation catches invalid input. Done well, validation is helpful and inline; done poorly, validation is punitive or arrives only at submission. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. + +The win. User selects an option that requires another. Inline validation surfaces immediately; explains; auto-corrects or guides. + +The fail. User configures complete configuration. Submits. Validation runs at backend. User sees error; loses momentum. + +The discipline. Validation timing matters; specific, helpful messages matter; preserve user inputs on error. + +--- + +## Pattern A: Inline validation + +Validation runs as the user makes choices. + +How it works. + +- User selects an option. +- System validates against the rest of the configuration. +- If invalid, message appears next to the choice. + +Strengths. Errors caught at point of input. + +Weaknesses. Real-time validation can lag; intrusive if too aggressive. + +When to use. Default for most configurators. + +--- + +## Pattern B: Pre-emptive validation + +Constraints prevent invalid choices from being selectable. + +How it works. + +- Options that would create conflicts are disabled with explanation. +- User cannot select the invalid option. + +Strengths. Errors prevented; user does not encounter them. + +Weaknesses. Some users want to see the option even if disabled. + +When to use. When the constraint is hard and explanation is clear. + +--- + +## Pattern C: Final validation + +Validation runs at submission. + +How it works. + +- User completes configuration. +- Submit; system runs full validation. +- Errors surfaced at this stage. + +Strengths. Catches errors that span multiple fields. + +Weaknesses. Late; user invested in completing. + +When to use. As supplement to inline validation; not primary. + +--- + +## Pattern D: Hybrid + +Combining patterns. + +Common combination. Pre-emptive for hard constraints; inline for soft validation; final as backup. + +Strengths. Multiple safety nets. + +Weaknesses. Complexity. + +When to use. Production configurators with multiple constraint types. + +--- + +## Validation message discipline + +What the message says. + +Strong messages. + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +Examples. + +- "Option A requires Option B; we have selected B for you." +- "Option C is incompatible with Option D. Choose one or contact us for custom." +- "Quantity exceeds 1000; for larger quantities contact our team." + +Weak messages. + +- "Invalid configuration." +- "Error." +- "Please correct the issues." + +The discipline. Specific, helpful, offers paths. + +--- + +## Validation strictness + +How aggressively to validate. + +Too strict. Rejects valid inputs at edge cases. Frustrates users. + +Too loose. Accepts invalid inputs that fail downstream. + +The right strictness. Validation matches actual product constraints. + +--- + +## Preserve inputs on error + +What happens when validation engages. + +The principle. Errors should not lose user inputs. + +The pattern. Error appears; rest of configuration preserved; user adjusts the specific issue. + +The reset-on-error failure. Form resets entirely on error. User loses all work; abandons. + +The cure. Errors are local; configuration state preserved. + +--- + +## Mobile validation + +Validation on mobile. + +Mobile considerations. + +- Inline messages must fit mobile screens. +- Auto-correct should work with touch. +- Error states must be visible without zoom. + +The mobile discipline. Test validation on actual devices. + +--- + +## Validation testing + +Test validation across cases. + +Test cases. + +- Valid configurations: pass through. +- Invalid configurations (each constraint type): caught with helpful message. +- Edge cases (boundary values, unusual combinations): handled. +- Mobile: works on touch. + +--- + +## Common validation failures + +Late validation. Errors caught only at submission. + +Generic error messages. No guidance. + +Strict validation rejects valid inputs. Edge cases lost. + +Loose validation accepts invalid. Fails downstream. + +Reset-on-error. User loses work. + +Validation interrupts typing. Real-time validation too eager. + +Mobile-broken validation. Errors invisible or off-screen. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D. Validation message discipline. Validation strictness. Preserve inputs on error. Mobile validation. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/dist/pi/.agents/skills/programmatic-seo/SKILL.md b/dist/pi/.agents/skills/programmatic-seo/SKILL.md new file mode 100644 index 0000000..124d85f --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/SKILL.md @@ -0,0 +1,279 @@ +--- +name: programmatic-seo +description: "How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. Data source identification, template design, schema patterns, quality control at scale, internal linking architecture, crawl budget management, AEO/GEO for programmatic pages, refresh discipline, and the make-or-break question of whether pSEO is the right answer for your program at all. Triggers on programmatic SEO, pSEO, scaled content, page generation, template SEO, location pages, comparison pages, directory site, listing site, scaled landing pages, programmatic content. Also triggers when a content set is not ranking, has been hit by an algorithm update, or when a team is considering pSEO as a growth lever." +category: content +catalog_summary: "Designing pSEO programs that work: data sources, template design, quality control at scale, internal linking, crawl budget, AEO/GEO patterns, refresh discipline, and when pSEO is and is not the right answer" +display_order: 6 +--- + +# Programmatic SEO + +A senior SEO strategist's playbook for designing and running programmatic SEO programs that produce durable traffic instead of penalty-bait. + +Programmatic SEO has a complicated reputation. Sites like Zillow, Airbnb, TripAdvisor, Indeed, and Yelp have built billion-dollar traffic engines on pSEO. Other sites have built pSEO programs that got hit by Google's helpful-content updates and lost 80% of their traffic in a week. The difference is rarely the technique; it is the underlying data quality and the quality control discipline at scale. + +This skill is the playbook for getting that distinction right. It assumes you have decided what keyword space to target (see `seo-keyword`) and how the broader content program is shaped (see `content-strategy`). It does not write individual editorial pieces (see `content-and-copy` for that) and does not architect editorial topic hubs (see `pillar-content-architecture` for that). What it does is teach the discipline of generating high-volume pages programmatically from structured data sources without producing thin content, duplicate content, or scale-without-substance pages that get penalized. + +When to use this skill: deciding whether pSEO is a fit for the program at all (the most important question), designing a new pSEO system, auditing an existing pSEO set that is not ranking or has been hit by an algorithm update, or building quality-control discipline for a pSEO program that grew faster than its quality processes. + +--- + +## What this skill is for + +This skill spans scaled-content programs from data source through quality control. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: editorial pillars, calendar, governance. Decides whether pSEO fits the program at all. +- `pillar-content-architecture` is hub-scope: one topic with 10 to 15 intentional editorial pieces. Editorial in nature. +- `content-brief-authoring` is per-piece scope: brief for one editorial artifact. +- `content-and-copy` is execution scope: writing individual editorial pieces. +- This skill is scaled scope: 100s to 100,000s of pages generated programmatically from structured data sources, each targeting a long-tail query. + +The clean reading order: `content-strategy` decides whether pSEO is a fit, `seo-keyword` surfaces the long-tail keyword space, this skill designs the pSEO system, `editorial-qa` (forthcoming) provides the QA discipline for sampled quality control across the set. `content-and-copy` and `content-brief-authoring` are not in the loop for pSEO at scale; those skills are for editorial pieces, not data-driven generated pages. + +The audience: SEO content strategists, content engineers, agencies running pSEO programs, in-house teams considering pSEO as a growth lever. The voice is senior SEO strategist to junior PM or marketer. Specific, opinionated, honest. The reputation problem is not pSEO; it is pSEO without underlying value. + +--- + +## When pSEO is the right answer + +The keystone question. pSEO works when all of the following are true. + +1. Real underlying data. A genuine structured data source with depth: 10+ fields per record, ideally 20+, with first-party data, expert-curated data, or licensed datasets. Not just scraped data or AI-generated facts dressed as structured records. + +2. Long-tail query volume justifies the effort. The queries the program would target have meaningful aggregate volume even if individual queries are small. Real estate "homes for sale in {neighborhood}" works at scale. "Blue widget reviews 2026" generated for every adjective times widget combination does not, because the queries are not actually searched. + +3. User intent is queryable. The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +4. Update cadence aligns with query volatility. Real estate listings update daily and the data refresh aligns. "Best [thing] for [year]" pages get stale annually and need a refresh discipline budgeted in. + +5. Quality control is operationally feasible. The team has the capacity to sample-audit the set, fix failures, and maintain quality as the set grows. Not aspirationally; budgeted in headcount. + +pSEO does NOT work when: + +- The underlying data is shallow (3 to 5 fields, mostly AI-generated, no first-party signal) +- The query volume is illusory (long-tail keywords nobody actually searches) +- User intent requires narrative or judgment that data cannot supply +- Quality control is not budgeted (write a bunch of pages, ignore them) +- The program is scaling AI-generated thin pages without unique data + +The honest framing. Most teams that ask "should we do pSEO?" should hear "probably not, unless the underlying data is unique or first-party expertise makes the pages actually useful." The reputation problem is not the technique; it is the technique applied without underlying value. + +Detail in [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md). + +--- + +## Data source identification + +The data source is the pSEO program. Common sources with different defensibility profiles. + +First-party data. Customer transactions, content database, user-generated content. Defensible because nobody else has it. Examples: Glassdoor's employee reviews, Yelp's user ratings, TripAdvisor's traveler reviews. + +Licensed datasets. Industry databases, regulatory data, government datasets, licensed third-party feeds. Defensible by license terms and integration depth. Examples: Zillow's MLS partnerships, real estate brokerage feeds, sports statistics licenses. + +Aggregated public data. Scraped, cleaned, enriched. Judgment call on legality (often gray area depending on robots.txt, terms of service, jurisdictional rules). Defensibility depends on the cleaning and enrichment work. Easy to copy if the cleaning is shallow. + +Expert-curated content. The dataset is built by hiring experts to populate it. Slow, high-quality, defensible. Examples: Wirecutter's product testing, expert-reviewed medical content, curated editorial databases. + +Synthesized data. Combining multiple sources into a unique view. "Neighborhoods times schools times prices" combining three datasets into a comparison view. Defensibility comes from the synthesis logic and the ongoing maintenance of multi-source pipelines. + +The "moat" question. Would a competitor be able to replicate the data source? If yes, the pSEO program has no defensibility; anyone can copy. If no, the data source becomes a moat that compounds. Zillow's MLS partnerships, Glassdoor's employee reviews, Crunchbase's funding data, are moats. "Scraped Wikipedia plus AI rewrite" is not. + +Detail in [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md). + +--- + +## Template design + +The template is the structure that data fills. Design principles. + +Above-the-fold answer. The user's specific question answered in the first 200 words of the rendered page, structured for both human reading and AI extraction. The answer is what gets cited; the rest is supporting depth. + +Variable density. The template accommodates records with sparse fields (some have 5 data points, others have 50) without looking broken. Sparse pages need fallback patterns; dense pages need progressive disclosure to avoid overwhelming. + +Heading hierarchy that reflects data. H2s and H3s map to data sections (overview, details, comparisons, related). The heading structure is not decorative; it tells crawlers and AI engines what the page covers. + +Schema markup as part of template. Structured data (JSON-LD, microdata, or RDFa depending on the stack) embedded in the template renders machine-readable signals at scale across the entire set. Without schema, the set is invisible to the structured-data extraction layer search and answer engines run. + +Internal linking placeholders. The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. 5 to 15 internal links per page is typical for a well-linked set. + +Distinctive value per page. Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. If the page is just a re-pivot of the parent's data, the page is filler. + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. If a randomly sampled page is thin, the entire set is thin. + +Detail in [`references/template-design-patterns.md`](references/template-design-patterns.md). + +--- + +## Schema design + +The data shape that drives the template. Design principles. + +Field count signals depth. 5 fields per record is thin. 15 to 20 is competent. 30+ is deep. The field count is not a vanity metric; it determines what the template can render at depth versus what falls back to filler. + +Required vs optional fields. Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. A page with 3 of 30 optional fields populated should not ship; a page with 25 of 30 should. + +Computed fields. Derived from source data. Average price per square foot computed from listings adds depth without requiring more source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +Cross-record fields. Fields that reference other records in the set enable internal linking and comparison. The "5 most similar neighborhoods" field on every neighborhood page powers the sibling-link section without manual curation. + +Update frequency tags. Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). Without tagging, refresh becomes "audit everything" instead of "refresh the volatile fields." + +The "schema-as-product" principle. The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. Versioned, reviewed, documented, breaking-change-aware. + +Detail in [`references/schema-design-patterns.md`](references/schema-design-patterns.md). + +--- + +## Quality control at scale + +Auditing all 100,000 pages individually is infeasible. The discipline. + +Sampling strategy. Random sample 50 to 200 pages per audit cycle, balanced across data shape (sparse, dense, recent, old, popular categories, niche categories). The sample is not "the latest 50 pages"; it is a stratified sample that exposes problems specific to particular data shapes. + +Automated checks. Heading structure, schema validity, internal link count, word count thresholds, duplicate-content checks, broken-link checks. Run on every page on a cadence; surface failures as a queue. + +Manual review checklist. For sampled pages, check the top-200-word answer quality, check whether the page would satisfy the user's query, check whether the page reads as distinctive versus templated. The manual review is the layer automated checks miss. + +Failure thresholds. If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. The threshold is not negotiable; without it, quality drift compounds invisibly until the algorithm update reveals it. + +Cohort tracking. Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. Cohort tracking is the pSEO equivalent of the experimentation team's drift detection. + +The team budget question. A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. If that is not budgeted, the program will decay. The set will look fine on launch and degrade over 6 to 12 months as data drifts, templates ship without QC, and the gap between the QC plan and the actual cadence widens. + +Detail in [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md). + +--- + +## Internal linking across the set + +pSEO sets need intentional internal linking architecture to compound. + +Hub pages. Parent-level pages (e.g., "homes for sale in Denver") that link to all child pages (specific neighborhoods). Hub pages are linked from main navigation; they are the entry point for the set's traffic. + +Sibling linking. Each page links to 5 to 15 related sibling pages: similar neighborhoods, similar price ranges, similar features. Sibling links are computed from cross-record fields in the schema; they are not manual curation at scale. + +Reverse-direction linking. Child pages link up to hub; sibling links go both directions. The graph is bidirectional; PageRank flows both ways. + +Anchor text variation. Avoid every page using the same anchor text. Vary by record characteristic (the record name, a descriptive phrase, the parent category). Uniform anchor text at scale signals manipulation to ranking systems. + +Crawl-friendly architecture. Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +The PageRank flow principle. Internal linking is what makes pSEO sets compound. A well-linked set distributes ranking signal across all pages; a poorly-linked set has hub pages ranking and child pages orphaned. The link architecture is half the program; the data is the other half. + +Detail in [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md). + +--- + +## Crawl budget management + +Search engines have crawl budgets. Large pSEO sets can exhaust them. + +Sitemap segmentation. Split sitemaps by category or recency so crawlers prioritize active pages. A single sitemap with 100,000 entries is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each, organized by category or last-update. + +Noindex on thin pages. Pages with insufficient data should noindex rather than ship as bait. The discipline: pages that fail the schema's required-field threshold do not get a public URL; they sit in the system as drafts until their data populates. + +Canonical handling. Comparison pages (X vs Y) often have inverse pages (Y vs X). Canonicalize to one. Comparison-pivot duplicates without canonicalization split ranking signal. + +Crawl rate signals. Monitor Google Search Console crawl stats. If crawl rate is plateauing while page count grows, the set is hitting budget limits. The fix is not "publish more pages"; it is "noindex thin pages and improve internal linking so crawlers prioritize better." + +Pruning criteria. Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. Pruning is hygiene, not failure. A 100,000-page set with 60% earning traffic is healthier than the same set with 40% earning traffic plus 60% dead weight crawlers waste budget on. + +Detail in [`references/crawl-budget-management.md`](references/crawl-budget-management.md). + +--- + +## AEO and GEO for programmatic pages + +Answer engines treat programmatic pages differently from editorial pages. + +Direct-answer extraction. AI engines extract the top-200-word answer; templates that lead with the answer get cited. The opening of the page is the citation candidate; everything after it is supporting depth. + +Structured data signals. JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. Programmatic pages with minimal schema lose to programmatic pages with deep schema even when the underlying data is similar. + +Citation patterns. AI engines tend to cite programmatic data pages for factual queries (prices, statistics, comparisons, factual details) and editorial pages for analytical queries (why, how, what should I think). Design templates to fit the factual-query lane; do not try to make programmatic pages compete for analytical queries that editorial content owns. + +Quality crackdown sensitivity. AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. The pSEO penalty risk has migrated to AI surfaces; the same quality-at-scale discipline applies, with less tolerance. + +The "two-engine optimization" framing applies. pSEO pages should serve both search engines and answer engines. Most pSEO programs were designed pre-AEO and need template updates for the new surface: stronger top-200-word answers, deeper schema markup, FAQPage schema where the page contains FAQ structure. + +Detail in [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md). + +--- + +## Refresh and maintenance at scale + +pSEO sets decay if not maintained. + +Data refresh cadence. Quarterly minimum for most datasets. Daily or weekly for time-sensitive data (real estate listings, prices, availability, current statistics). The refresh cadence is set when the program launches; retrofitting is expensive. + +Template version migration. When the template improves, all existing pages need migration. Cohort-by-cohort migration with monitoring beats big-bang migration. Each cohort gets the new template, sits for 30 days under monitoring, then the next cohort migrates. + +Pruning lifecycle. Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. The 24-month checkpoint is the standard cutoff; some categories warrant earlier or later pruning. + +Set-level refresh. Occasionally the entire set's template needs a refresh as user expectations evolve, AI engine signals shift, or category conventions change. Set-level refreshes are 6-month projects, not weekend cleanups. + +Detail in [`references/refresh-at-scale.md`](references/refresh-at-scale.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pseo-failures.md`](references/common-pseo-failures.md). + +- "We generated 50,000 pages and got penalized." Thin content, scaled too fast, no QC discipline. +- "We have 10,000 pages but only 200 rank." Internal linking architecture missing; child pages are orphans. +- "Crawl rate plateaued." Crawl budget exhausted; noindex thin pages and improve sitemap segmentation. +- "Pages look identical." Template lacks variable density; data is too sparse to differentiate. +- "We cannot update the templates without 10,000 manual fixes." Template versioning was not designed for scale. +- "Our quality control is whoever has time." No sampling discipline, no thresholds, no ownership. +- "AI engines do not cite our pages." Top-200-word answer was not designed; structured data is thin. +- "We are at 100,000 pages and engagement is dropping." The set has outgrown its data depth. +- "Competitors copied our pages." The data source was not a moat. +- "Refresh is overwhelming." Cadence was not designed for scale; templates are not migration-friendly. +- "Our pSEO drives traffic but no conversions." Query intent does not match buyer intent; reconsider whether pSEO was the right channel for the program goal. + +--- + +## The framework: 12 considerations for programmatic SEO + +When designing or auditing a programmatic SEO program, walk these 12 considerations. + +1. Right answer for the program. pSEO needs real underlying data, queryable intent, and quality-control budget. Default to no if any is missing. +2. Data source as moat. Replicable data is not defensible; first-party, licensed, expert-curated, or synthesized data is. +3. Schema depth. 15+ fields per record minimum; 30+ for competitive depth. +4. Template variable density. Accommodates sparse and dense records gracefully. +5. Above-the-fold answer. First 200 words answer the user's specific query. +6. Schema markup at scale. Structured data on every page; this is the AEO/GEO signal. +7. Internal linking architecture. Hub-and-spoke plus sibling linking, no orphans. +8. Quality control sampling. 50 to 200 pages per audit, balanced across data shape. +9. Failure thresholds. 5% sample failure halts generation until template or data fixes ship. +10. Crawl budget discipline. Sitemap segmentation, noindex on thin pages, canonicalization on duplicates. +11. Refresh cadence. Quarterly minimum data refresh; cohort-by-cohort template migration. +12. Pruning lifecycle. Pages that fail to earn traffic in 12 to 24 months get noindexed or removed. + +The output of the framework is a pSEO design document the team can reference at every stage: data source named, schema versioned, template specified, QC discipline budgeted, internal linking architecture mapped, refresh cadence set. + +--- + +## Reference files + +- [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md) - Five-criterion decision framework with worked examples of yes, no, and maybe. +- [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md) - First-party, licensed, public, expert-curated, synthesized; defensibility analysis. +- [`references/template-design-patterns.md`](references/template-design-patterns.md) - Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. +- [`references/schema-design-patterns.md`](references/schema-design-patterns.md) - Field count, computed fields, cross-record fields, update tags, schema-as-product. +- [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md) - Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. +- [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md) - Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. +- [`references/crawl-budget-management.md`](references/crawl-budget-management.md) - Sitemap segmentation, noindex patterns, canonicalization, crawl rate monitoring, pruning criteria. +- [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md) - Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. +- [`references/refresh-at-scale.md`](references/refresh-at-scale.md) - Data refresh cadence, template versioning, cohort migration, pruning lifecycle. +- [`references/common-pseo-failures.md`](references/common-pseo-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: quality at scale or not at all + +The only durable pSEO programs are the ones that hold quality at scale. The temptation to scale quantity at the cost of quality has produced the entire bad reputation pSEO carries. Sites that resist that temptation, that maintain real data depth, real quality control, real refresh discipline, keep producing meaningful traffic for years. Sites that do not get penalized within months of an algorithm update. + +The discipline is not optional and it is not free. Budget for it before generating the first page, or do not start at all. + +When in doubt about whether a pSEO program is ready, ask: is the data source actually unique, is the schema deep, does the template lead with the answer, is the internal linking architecture mapped, is QC budgeted in headcount, is the refresh cadence set? If yes to all of those, ship the design document and let the engineering work begin. If no to any of them, fix the gap before any pages generate. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md b/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md new file mode 100644 index 0000000..2300287 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md @@ -0,0 +1,106 @@ +# AEO and GEO for programmatic pages + +Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. + +Answer engines treat programmatic pages differently from editorial pages. The differences shape how pSEO templates should be designed for the AI search era. + +--- + +## Direct-answer extraction + +AI engines extract the top-200-word answer; templates that lead with the answer get cited. + +The pattern. The opening of the page is the citation candidate. AI engines pull from the first answer-shaped paragraph, FAQPage schema entries, and structured-data fields. Everything after the opening is supporting depth that justifies the citation but is rarely cited directly. + +Template implication. The first 200 rendered words must answer the user's specific query in a self-contained way. A page about "homes for sale in Denver under $500k" should answer that exact query in the opening: count of listings, average price, top neighborhoods, with structured data backing each claim. + +Anti-pattern. Welcome paragraphs, navigation hints, "below you will find" filler. These dilute the citation candidate and reduce the page's AI-engine pull. + +Snippet-bait paragraphs at H2 level. Beyond the top-200-word answer, each H2 should have a 40 to 60 word snippet-bait paragraph. AI engines often quote multiple snippet-bait paragraphs as multi-paragraph citations. + +--- + +## Structured data signals + +JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. + +The "thin schema" penalty. Programmatic pages with minimal schema (just the basic Article or Product type, with required fields only) lose to programmatic pages with deep schema (complete schema graph, optional fields populated, cross-entity references). The underlying data may be similar; the schema markup is what AI engines see. + +Schema patterns that signal quality at scale. + +- Type-appropriate schema. Product for product pages, LocalBusiness for location pages, Article for editorial pages, FAQPage for FAQ sections, BreadcrumbList for navigation context. +- Cross-entity references. Schema entries that reference other entities in the dataset (relatedProduct, parentOrganization, hasPart) signal a connected knowledge graph rather than isolated pages. +- Aggregate schema. Reviews, ratings, statistics presented as structured aggregateRating, aggregateOffer, aggregateProperty fields. +- FAQPage schema on FAQ sections. AI engines (Perplexity especially) cite FAQPage-marked content heavily; programmatic pages that include FAQ sections should mark them. + +Schema validation. Run schema validation on every page; failures produce silent invisibility in AI surfaces. The validation is automated and gates publish. + +--- + +## Citation patterns + +AI engines cite programmatic data pages and editorial pages for different query types. + +Factual-query lane. AI engines tend to cite programmatic data pages for factual queries: prices, statistics, comparisons, factual details, specifications, locations, ratings. The page renders the fact as structured data; the AI engine cites the structured data as the answer. + +Analytical-query lane. AI engines tend to cite editorial pages for analytical queries: why, how, what should I think, recommendations with reasoning, opinions, judgments. Programmatic pages cannot compete in this lane; the data does not supply the analysis the user wants. + +Implication for pSEO design. Design templates to fit the factual-query lane. Do not try to make programmatic pages compete for analytical queries that editorial content owns. The two lanes coexist; pSEO is one half of a two-lane content strategy. + +The "hybrid page" pattern. Some pSEO programs add an editorial layer to programmatic pages (per-page expert commentary, AI-summarized analysis with human review). Hybrid pages can compete in both lanes when the editorial layer is genuinely substantive. Without substantive editorial layer, hybrid pages read as factual pages with filler attached and lose in both lanes. + +--- + +## Quality crackdown sensitivity + +AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. + +The migration of penalty risk. Pre-AI search era, thin pSEO sets could rank for 12 to 24 months before quality crackdowns hit. AI engines apply quality signals more aggressively. Thin pSEO sets in 2026 lose AI citations within 3 to 6 months even when traditional search rankings are still holding. + +Signals AI engines use beyond traditional search signals. + +- Distinctiveness. Pages that read as templated boilerplate get deprioritized. Pages that surface page-specific data prominently get cited. +- Source credibility. Pages with named authors, expert credentials, and citation chains get cited preferentially. Anonymous pSEO pages with no attribution lose to attributed pages. +- Citation traceability. Pages that cite their underlying data sources (with links to the source) get treated as authoritative. Pages that present facts without sourcing get treated as unreliable. +- Freshness. Pages with recent update dates get cited preferentially for time-sensitive queries. Stale pages lose AI citations even when traditional search rankings hold. + +The implication. pSEO programs designed pre-AEO need template updates: stronger above-the-fold answers, deeper schema markup, FAQPage schema on FAQ sections, source citations on factual claims, named authorship where the program supports it. + +--- + +## Two-engine optimization + +pSEO pages should serve both search engines and answer engines. + +Both engines reward depth. Search engines reward comprehensive coverage; AI engines reward citation-ready depth. Same content, different extraction. + +Both engines reward structure. Search engines parse heading hierarchy for ranking; AI engines parse heading hierarchy for citation extraction. Same structure, different use. + +Both engines reward freshness. Search engines reward recent updates; AI engines re-index recently updated content more aggressively. Same updates, different cadence. + +The two-engine implication. Designing for AEO does not trade off against SEO. The template improvements that earn AI citations (top-200-word answers, FAQPage schema, named authorship, source citations) also earn search rankings. Teams that treat AEO and SEO as separate optimizations under-invest in both. + +--- + +## Set-level reputation signals + +Beyond individual page signals, AI engines apply set-level reputation. The set's overall quality affects each page's citation likelihood. + +Domain-level reputation. A domain with a substantive editorial content layer plus a high-quality pSEO set ranks both layers more strongly than a domain with only pSEO. The editorial layer establishes the domain's expertise; the pSEO layer benefits. + +Set-level signal compounds. A 10,000-page pSEO set with 90% high-quality pages and 10% thin gets the entire set treated as high-quality. The same set with 60% high-quality pages and 40% thin gets the entire set deprioritized. The bad pages drag the good ones down. + +The implication. Set-level QC discipline (covered in `quality-control-at-scale.md`) is also AEO discipline. Holding the quality threshold across the set protects the set's AI-citation reputation, not just its search ranking. + +--- + +## Measurement + +Hub-level AEO/GEO metrics worth tracking on the pSEO set: + +- Brand mention rate from AI search visibility tools (Profound, Frase visibility tracking, AirOps AEO data) +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude, Google AI Mode) on the set's target queries +- Top-cited pages within the set (which template patterns get cited most) +- AI crawler hit frequency from server logs (GPTBot, PerplexityBot, ClaudeBot) + +Track at the set level, not just per page. Aggregate trends surface patterns that per-page tracking misses. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md b/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md new file mode 100644 index 0000000..175bb9b --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/common-pseo-failures.md @@ -0,0 +1,161 @@ +# Common pSEO failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: pSEO programs that ship without one of the five readiness criteria (real data, queryable intent, sufficient volume, refresh cadence, QC budget) and assume the gap will close later. The gap rarely closes; the failure compounds. + +--- + +## "We generated 50,000 pages and got penalized" + +Symptom. Algorithm update lands; the set loses 60 to 90% of its traffic in days. + +Diagnosis. Thin content scaled too fast without QC discipline. The set was generating filler pages, sometimes from AI-summarized public data, sometimes from sparse first-party data with bolt-on AI text. The algorithm update detected the scale-without-substance pattern. + +Fix. Halt new generation. Run a triage audit: which pages have substantive data backing them, which are filler. Noindex the filler. The remaining pages may recover ranking once the set's quality signal improves; the filler ones will not. Sometimes the right call is removing the entire pSEO surface and rebuilding from a higher-quality data source. + +Prevention. The five-criterion check (`when-pseo-works-decision.md`) before launch. The QC discipline (`quality-control-at-scale.md`) before scaling. + +--- + +## "We have 10,000 pages but only 200 rank" + +Symptom. Pages exist in the set; few of them rank for their target queries. + +Diagnosis. Internal linking architecture missing or incomplete. Hub pages rank because they receive site-wide navigation links. Child pages do not rank because they have no in-page link votes; they are partial orphans reachable only via sitemap. + +Fix. Build the link graph. Add sibling-link slots to the template. Compute cross-record similarity to populate sibling links. Backfill the link graph across the existing set. Audit for orphans; surface them in the QC queue (`internal-linking-at-scale.md`). + +--- + +## "Crawl rate plateaued" + +Symptom. Page count grows; pages crawled per day stays flat or declines. + +Diagnosis. Crawl budget exhaustion. The set has more pages than the search engine's crawl budget supports. + +Fix. Noindex thin pages. Segment sitemaps. Improve internal linking so crawlers prioritize substantive pages. Reduce server response time. Prune the dead-page tail. Detail in `crawl-budget-management.md`. + +The wrong fix: publishing more pages to "catch up" on traffic targets. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## "Pages look identical" + +Symptom. Random sampling of pages from the set finds them indistinguishable in substance, only different in identifiers. + +Diagnosis. Template lacks variable density, or the data is too sparse to differentiate. The template renders the same boilerplate for every record because the records do not actually differ on the dimensions the template surfaces. + +Fix. Two paths. + +- If the template is the problem (the data has variation but the template hides it): redesign the template to surface distinctive fields prominently. Move the differentiating data above the fold; demote the boilerplate. +- If the data is the problem (the records genuinely lack distinctive fields): the schema is too thin. Either deepen the schema with more source data, or accept that the program does not justify pSEO and pivot to editorial content. + +--- + +## "We cannot update the templates without 10,000 manual fixes" + +Symptom. A template change requires manually editing every existing page. + +Diagnosis. Template versioning was not designed for scale. Pages were generated as static output rather than as renders from the schema; updating the template now requires updating each rendered page. + +Fix. Architectural rebuild. Pages need to be re-rendered from the schema each time the template changes. The schema is the source of truth; the rendered pages are the output. Without this discipline, every template change becomes a per-page migration project. + +Prevention. Design pages as renders from data, not as static artifacts. The specific stack choice (build-time generation that re-runs on template change, server rendering with template version in the cache key, hybrid approaches) varies by team; the methodology principle is the same. + +--- + +## "Our quality control is whoever has time" + +Symptom. No regular QC cadence. Sample audits happen sporadically when someone notices a problem. + +Diagnosis. No sampling discipline, no thresholds, no ownership. The QC was assumed to be everyone's job, which means it is nobody's job. + +Fix. Assign a QC owner. Set the sampling cadence (monthly minimum for active programs). Codify the failure threshold (5% sample failure halts new generation). Track cohort metrics. Detail in `quality-control-at-scale.md`. + +--- + +## "AI engines do not cite our pages" + +Symptom. Traditional search rankings are stable; brand mention rate from AI search visibility tools is flat or declining. + +Diagnosis. Multiple possible causes. + +- The top-200-word answer was not designed; pages start with welcome paragraphs instead of answers. +- Schema markup is thin; AI engines see the pages as low-authority. +- FAQPage schema is missing on FAQ sections. +- Source citations are missing on factual claims. +- The pages read as templated boilerplate rather than as distinctive answers. + +Fix. Audit the template against the AEO/GEO patterns (`aeo-geo-for-programmatic-pages.md`). Update the template; migrate cohorts; monitor citation count by cohort to confirm the fix earned gains. + +--- + +## "We are at 100,000 pages and engagement is dropping" + +Symptom. Traffic continues but bounce rate climbs, time-on-page falls, conversion rate decays. + +Diagnosis. The set has outgrown its data depth. Early pages were the highest-data-quality records; later pages were lower-quality data backfilled to grow the set. Users are landing on pages that do not satisfy their query. + +Fix. Reverse the growth and prune. The set should be smaller and higher-quality, not larger and lower-quality. Identify the data-quality threshold below which pages do not satisfy queries; noindex pages below the threshold; let the set's average quality recover. + +Prevention. The required-field threshold in the schema enforces a quality floor. Pages that fail the threshold should not have shipped in the first place. + +--- + +## "Competitors copied our pages" + +Symptom. A competitor launched a similar pSEO set; the brand's traffic share is shrinking. + +Diagnosis. The data source was not a moat. The pSEO pages were replicable. + +Fix. Two paths. + +- Deepen the data source. First-party data accumulation, expert curation investment, licensed-feed integration that competitors cannot match. The defensibility comes from the data, not from the pSEO build. +- Pivot. If the data cannot be deepened, the program does not have a long-term moat. Consolidate the strongest pages, prune the rest, redirect the team to higher-defensibility work. + +Prevention. The defensibility test (`data-source-identification-patterns.md`) before launch. If competitors could replicate the data source within 6 months at reasonable cost, do not launch the program. + +--- + +## "Refresh is overwhelming" + +Symptom. Quarterly refresh cycles are missed or partially completed; data drifts; pages get stale. + +Diagnosis. Refresh cadence was not designed for scale. The team thought "we will refresh quarterly" but the actual work to refresh 10,000 to 100,000 pages exceeds the team's quarterly capacity. + +Fix. Automate the volatile-field refresh through data pipelines (mostly hands-off after pipeline build). Reduce slow-changing-field refresh frequency to annual on most fields. Cohort-migrate the template refresh rather than big-bang. Detail in `refresh-at-scale.md`. + +If the work still exceeds capacity after these fixes, the set is too large for the team's resources. Prune to a sustainable size. + +--- + +## "Our pSEO drives traffic but no conversions" + +Symptom. Traffic from pSEO pages is high; signups, sales, or engagement on the funnel goal are flat or low. + +Diagnosis. Query intent does not match buyer intent. The pSEO pages are answering informational queries; the buyer the program needs to capture is searching with different intent. + +Fix. Audit the queries the pSEO traffic is coming from. If the queries are not in the buyer's funnel, the program is producing non-converting traffic regardless of how well the pages are optimized. The fix is not "add more CTAs to pSEO pages"; the fix is recognizing that pSEO was not the right channel for the program's conversion goal. + +The reconsider-pSEO moment. If the program's metric is conversions and the pSEO traffic does not convert, pSEO is the wrong tool. Editorial content with stronger buyer-intent alignment, paid acquisition with conversion tracking, or product-led growth surfaces may be the better fit. + +--- + +## "Our QC discipline drifted over time" + +Symptom. The program launched with strong QC. Months in, the cadence slipped, the threshold became aspirational rather than enforced, the cohort tracking went unread. + +Diagnosis. QC ownership rotated, accountability dispersed, the metric dashboard stopped being reviewed. The pattern is the same as the "set and forget" failure for editorial pillar maintenance. + +Fix. Assign a durable QC owner with quarterly accountability. Reinstate the cadence. Audit the set for the drift that accumulated; fix or noindex pages that ship below the threshold. + +Prevention. The QC owner is named in the program's planning doc and renewed annually. The dashboard that tracks cohort metrics has an actual owner who reviews it monthly. The threshold is treated as enforced, not aspirational. + +--- + +## The pattern across all failures + +Most pSEO failures are designed-in. They were predictable from the program's launch shape. The five-criterion check, the schema-as-product principle, the QC budget, the refresh cadence, the link architecture: each one shipped or did not at design time. The set's eventual success or decay was largely determined before the first page generated. + +The discipline is upstream. Hold the line at design time; the operational discipline at scale becomes manageable. Skip the design discipline; the program produces filler at scale and gets penalized. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md b/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md new file mode 100644 index 0000000..8d28d56 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/crawl-budget-management.md @@ -0,0 +1,115 @@ +# Crawl budget management + +Sitemap segmentation, noindex on thin pages, canonicalization on duplicates, crawl rate monitoring, pruning criteria. + +Search engines have crawl budgets. Large pSEO sets can exhaust them. Crawl budget management is the discipline that keeps the set crawlable as it scales past 10,000+ pages. + +--- + +## Sitemap segmentation + +A 100,000-page sitemap is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each. + +Segmentation by category. One sitemap per top-level category. Crawlers prioritize sitemaps differently; segmentation helps the crawler prioritize active categories over dormant ones. + +Segmentation by recency. A "recent" sitemap surfaces pages generated in the last 30 days. Crawlers find new content faster; existing content remains crawlable through category sitemaps. + +Segmentation by update frequency. A "frequently-updated" sitemap surfaces pages whose volatile fields refresh weekly or daily. Crawlers re-crawl these pages on a tighter cadence. + +Sitemap index. A parent sitemap-of-sitemaps points to all segmented sitemaps. The index is what gets submitted to Search Console; the segments handle the actual page lists. + +Sitemap size limits. 50,000 URLs per sitemap is the hard limit. 10,000 to 25,000 per segmented sitemap is the typical practical size; smaller is fine for niche categories, larger is fine for high-volume categories. + +--- + +## Noindex on thin pages + +Pages with insufficient data should noindex rather than ship as bait. + +The discipline. Pages that fail the schema's required-field threshold do not get a public URL. They sit in the system as drafts until their data populates. + +Why noindex matters. Thin pages drag down the entire set's quality signal. Search engines and AI engines both apply set-level quality scoring; a set with 10,000 thin pages and 90,000 substantive pages scores worse than a set with just the 90,000 substantive pages, even though the absolute page count is lower. + +Noindex implementation patterns. + +- The thin pages render with a `noindex` meta tag in the head. +- The thin pages are excluded from the sitemap. +- The thin pages are not linked from any other page in the set. + +The "we'll fix it later" trap. Teams ship thin pages with `index, follow` and plan to backfill data later. The data backfill rarely happens; the thin pages accumulate; the set's quality signal degrades over time. + +--- + +## Canonical handling + +Comparison pages and other pivot patterns produce duplicate-content risks. + +The X-vs-Y pattern. A page comparing X to Y often has an inverse page comparing Y to X. The two pages cover the same content from different orderings. Canonicalize one to the other. + +Canonical decision. Pick the canonical based on search volume, alphabetical order, or category hierarchy. The choice itself matters less than picking one consistently. + +Other pivot patterns. + +- Filter pivots. "Homes in Denver under $500k" and "Homes under $500k in Denver" should canonicalize to one. +- Sort pivots. "Top hotels in Paris by rating" and "Top hotels in Paris by price" might be distinct enough to live separately, or might canonicalize depending on the user-intent overlap. +- Date pivots. "Best [thing] for 2025" and "Best [thing] for 2026" usually live separately because the content genuinely differs by year; canonicalization would lose the time-relevance signal. + +The discipline. Canonical decisions are designed at template time, not retroactively. The template either generates canonical-pair URLs (and chooses one as canonical from the start) or it does not generate the duplicate at all. + +--- + +## Crawl rate monitoring + +Search engines publish crawl statistics. Monitor them. + +Google Search Console crawl stats. Pages crawled per day, average response time, crawl request distribution by category. Monitor monthly; investigate drops or plateaus. + +Crawl rate plateauing while page count grows. The set is hitting crawl budget limits. The fix is not "publish more pages." The fix is: + +- Noindex thin pages to remove low-value crawl targets +- Improve internal linking so crawlers prioritize the substantive pages +- Segment sitemaps so the crawler can prioritize active categories +- Reduce server response time so crawlers can crawl more in the same budget + +Crawl rate dropping unexpectedly. Investigate. Common causes: server errors that the crawler is encountering, robots.txt changes that excluded important paths, sitemap submissions that broke, large-scale URL pattern changes without redirects. + +--- + +## Pruning criteria + +Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. + +The 6-month checkpoint. A page that has been in the set for 6+ months and has earned zero impressions in Search Console is dead weight. The fix is not "wait longer." + +Pruning options. + +- Noindex. The page stays accessible to direct visitors but is removed from the search index. Reversible if the page later starts earning impressions. +- 410 Gone. The page is removed entirely; the URL returns 410. Permanent; appropriate for genuinely obsolete content. +- 301 Redirect. The page redirects to a more-relevant alternative. Appropriate when the user's intent for the dead page can be served by an alternative page that still exists. + +The 12-month and 24-month checkpoints. Pages that have not earned traffic by month 12 should be reviewed for noindex or removal; pages that have not earned traffic by month 24 should be removed unless there is a specific strategic reason to keep them. + +Why pruning matters. Dead pages waste crawl budget. Crawlers visit them, find nothing useful, and the set's average quality signal degrades. Pruning concentrates the set's PageRank on the pages that earn traffic. + +--- + +## When the set is too large for the budget + +Symptoms: + +- Crawl rate is permanently below the page count's natural crawl demand +- New pages take weeks or months to get indexed +- Existing pages drop out of the index unexpectedly +- The site's overall ranking is degrading despite the set being substantively unchanged + +The diagnosis is usually crawl budget exhaustion. The fix is set reduction (prune to the substantive pages), set restructuring (split into multiple subdomains or sites if appropriate), or technical optimization (server response time, sitemap discipline). + +The temptation is to publish more pages to "catch up" with traffic targets. The temptation is wrong. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## Methodology vs implementation + +The principles above are methodology: which pages to noindex, when to canonicalize, how to segment sitemaps, how to read crawl stats. + +The specific implementation (the framework's noindex meta tag pattern, the sitemap generation library, the canonical link helpers, the deployment-time crawl-test integration) is stack-specific. Each team implements crawl budget management within their own stack's tooling; the methodology applies regardless of the implementation choice. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md new file mode 100644 index 0000000..e6fa193 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/data-source-identification-patterns.md @@ -0,0 +1,104 @@ +# Data source identification patterns + +First-party, licensed, public, expert-curated, synthesized. Defensibility analysis for each pattern. + +The data source IS the pSEO program. A weak data source produces a weak set regardless of template quality, internal linking, or QC discipline. A strong data source produces durable traffic that compounds across years. + +--- + +## Pattern 1: first-party data + +Data the team owns because the business produced it. + +Sources. Customer transactions, content database, user-generated content, support ticket history, internal product analytics, sales call records, customer feedback databases. + +Defensibility. Maximum. Nobody else has the data. A competitor would have to build the same business and accumulate the same usage history to replicate. + +Examples. Glassdoor's employee reviews (built by getting employees to submit). Yelp's restaurant ratings (built by getting users to rate). TripAdvisor's traveler reviews (built by getting travelers to write). Reddit's discussion threads (built by getting users to post). + +Watchouts. Privacy and terms-of-service compliance. User-generated content used for pSEO needs explicit consent in the original collection terms; retrofitting consent is not legal in most jurisdictions. PII in pSEO pages is a separate liability. + +The "moat compounds over time" effect. First-party data sources get stronger as the business runs longer. A 10-year-old review database is more defensible than a 2-year-old one with the same volume because the time-series depth itself becomes valuable. + +--- + +## Pattern 2: licensed datasets + +Data acquired through commercial licensing. + +Sources. Industry databases (real estate MLS, automotive VIN databases, sports statistics feeds), regulatory data (SEC filings, government statistics), third-party content licenses (medical content, legal precedent). + +Defensibility. Medium to high. Defensibility depends on license exclusivity and integration depth. An exclusive license is a moat; a non-exclusive license that anyone can also buy is not. + +Examples. Zillow's MLS partnerships (licensed feeds with depth integration). Sportradar customers building stats sites. Bloomberg Terminal customers building financial content. Real estate brokerages with regional MLS access. + +Watchouts. License costs scale with usage; the unit economics need to work at scale. License terms typically restrict redistribution, which can complicate pSEO scaling (the data can power the pSEO pages but cannot be exported as a downloadable dataset). + +--- + +## Pattern 3: aggregated public data + +Data scraped, cleaned, enriched from public sources. + +Sources. Open government data, public web pages, academic research, public APIs. + +Defensibility. Low to medium. Anyone can scrape the same sources; the defensibility comes from the cleaning and enrichment work. If the cleaning is shallow, the defensibility is none. + +Examples. Sites built on government statistics (census data, BLS data). Sites built on academic research summaries. Sites built on public company filings (EDGAR data plus enrichment). + +Watchouts. Legality is jurisdictional and often gray. robots.txt compliance, terms-of-service review, copyright considerations, anti-circumvention rules in some jurisdictions. The legal review is mandatory, not optional, even when the data is "public." + +The "scraped Wikipedia plus AI rewrite" anti-pattern. The lowest-effort form of this category. The data is not really enriched (AI rewrite of public encyclopedia entries adds no defensible value). The pSEO sets built on this pattern are the ones that get penalized first when algorithm updates run. + +--- + +## Pattern 4: expert-curated content + +Data produced by hired experts who populate the dataset by hand. + +Sources. Expert-written reviews, expert-curated lists, professionally-tested products, professionally-evaluated services, professional translations. + +Defensibility. High. The defensibility is in the curation cost. A competitor would have to hire and pay the same experts for the same time to replicate. + +Examples. Wirecutter's product testing (experts test products in lab conditions). Consumer Reports' product reviews. Edmunds' car reviews. Specialty publications with paid expert contributors. + +Watchouts. Slow to build. The set scales at the speed of expert capacity, not at the speed of automated generation. Budget reflects the headcount, not the engineering effort. + +The combination pattern. Expert-curated content often combines with structured data (the expert reviews a car; the dataset captures the expert's score plus structured specifications) to produce pages with both narrative depth and queryable structure. + +--- + +## Pattern 5: synthesized data + +Data produced by combining multiple sources into a unique view. + +Sources. Multi-source pipelines that produce derived analyses unavailable from any single source. + +Defensibility. Medium to high. Defensibility comes from the synthesis logic and the ongoing pipeline maintenance. + +Examples. "Neighborhoods times schools times prices" combining three datasets into a comparison view. "Companies times salaries times employee reviews" combining three sources into a candidate-decision view. Aggregator pages that show "best X for Y use case" combining multiple product databases with use-case classification. + +Watchouts. The synthesis logic is the moat, not the underlying sources. Changes to source schemas break the pipelines. The pSEO program inherits the operational fragility of multi-source pipelines. + +--- + +## The defensibility test + +For each candidate data source, walk this question: would a competitor be able to replicate this source within 6 months at reasonable cost? + +- Yes, easily. No moat. Pursue editorial content instead, or invest in expert curation to build a moat. +- Yes, with effort. Partial moat. The first-mover advantage matters; ship before competitors. +- No, requires major investment. Real moat. pSEO compounds. +- No, requires assets the competitor cannot acquire. Strongest moat. The pSEO program becomes a long-term competitive advantage. + +--- + +## Combining patterns + +The strongest pSEO programs combine multiple patterns. + +- First-party data plus licensed data (Glassdoor: user reviews plus salary licenses) +- Licensed data plus expert curation (Wirecutter: licensed product databases plus expert testing) +- First-party data plus synthesized data (Yelp: user ratings synthesized with location data and external attributes) + +Single-pattern programs are simpler to ship but easier to replicate. Multi-pattern programs are harder to build and harder to copy. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md new file mode 100644 index 0000000..6c4d441 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/internal-linking-at-scale.md @@ -0,0 +1,116 @@ +# Internal linking at scale + +Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. + +The internal-link graph is half the program; the data is the other half. A well-linked pSEO set distributes ranking signal across all pages and compounds. A poorly-linked set has hub pages ranking and child pages orphaned. + +--- + +## Hub-and-spoke architecture + +The standard pSEO link topology. + +Hub pages. Parent-level pages that aggregate the children. "Homes for sale in Denver" is a hub for the neighborhoods; "Software engineer salaries" is a hub for the company-specific salary pages; "Hotels in [city]" is a hub for individual hotel pages. + +Hub-level discipline. + +- Hub pages are linked from main site navigation, not just from sitemaps. Crawlers reach hubs first and traverse to children from there. +- Hub pages link to all children in the category. The hub's body or a paginated listing exposes the full set. +- Hub pages are not just link aggregators; they have their own content (category overview, comparison tables, top-of-category aggregates) that earns ranking on its own. + +Spoke pages. The individual records. Each spoke links up to the hub and laterally to siblings. + +--- + +## Sibling linking + +Each page links to 5 to 15 related sibling pages. + +The pattern. The sibling-link section of the template renders 5 to 15 related records computed from cross-record fields in the schema. Most-similar-by-attribute, similar-price-range, similar-features, geographic neighbors. + +Why sibling linking matters. Without it, the link graph is a star (hub to spokes only). PageRank concentrates at the hub; spokes get minimal flow. With sibling linking, the graph is dense; PageRank distributes across the set. + +Bidirectional linking. Sibling links go both directions. If A links to B as a sibling, B should link to A. Asymmetric sibling linking creates ranking dead ends. + +Avoiding the "everyone links to everyone" trap. Every page linking to every other page is a complete graph; anchor text relevance dilutes; the link graph reads as algorithmic rather than semantically meaningful. The 5 to 15 sibling-link cap keeps each page's outbound graph navigable and signal-dense. + +--- + +## Reverse-direction (bottom-up) linking + +Spoke pages link UP to hub. + +The first-200-words pattern. The spoke page's introduction includes a contextual link up to the hub: "This page covers [specific record]. For the broader [category] overview, see [hub page]." + +The closing pattern. The spoke page's closing includes a link back to the hub or to the next-most-relevant sibling, giving readers a navigation path back to broader content. + +Why bottom-up matters. Without it, the hub does not compound. The spokes inherit traffic from their long-tail queries; without bottom-up links, that traffic does not flow back to lift the hub. + +--- + +## Anchor text variation + +Avoid every page using the same anchor text. + +The principle. Anchor text is the signal that tells search engines what the linked-to page is about. Identical anchor text across thousands of links to the same page reads as manipulation; varied anchor text reads as natural authority. + +Variation patterns for pSEO. + +- Record-name variation. "View [neighborhood name]" / "[neighborhood name] homes for sale" / "Browse [neighborhood name] listings" / "[neighborhood name] guide" used across different siblings linking to the same record. +- Descriptive variation. Anchor text that describes the linked page's distinctive attribute. "Affordable [neighborhood]" / "Top-rated [neighborhood]" / "Family-friendly [neighborhood]" computed from the target record's attributes. +- Context-driven variation. The anchor text shifts based on what the linking page is about. A page about prices uses price-relevant anchor text; a page about schools uses school-relevant anchor text. + +Anti-pattern. Every sibling link uses "[Record name]" as the anchor. Easy to ship at scale, signals manipulation, dilutes the page's anchor profile. + +--- + +## Crawl-friendly architecture + +Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +Sitemap segmentation. A pSEO set with 50,000 child pages does not put all 50,000 in a single sitemap. Segment by category, by recency, by data freshness. Crawlers process segmented sitemaps more reliably. + +Sitemap-only access is not enough. A child page only reachable via sitemap, with no other page linking to it, is a partial orphan. Crawlers may visit it; the page will struggle to compound ranking signal because no in-page link votes for it. + +The orphan check. Pages with zero inbound internal links besides the sitemap are orphans. Audit quarterly; surface in QC. The fix: add the page to the hub's listing, add it to sibling sets it should belong to, expose it through breadcrumb navigation. + +--- + +## The PageRank flow principle + +Internal linking is what makes pSEO sets compound. + +The pattern that compounds. Hub linked from main nav (high PageRank concentration). Hub links to all children (PageRank distributes). Children link laterally to siblings (PageRank circulates within the set). Children link back up to hub (PageRank reinforces). + +The pattern that does not compound. Hub linked from main nav. Hub links to children. Children do not link to siblings, do not link back to hub. PageRank flows hub-to-child but does not circulate; child pages slowly accumulate independent ranking signal but never compound. + +The auditable signal. Average internal-links-in per page. The set's average should be 8 to 20 inbound internal links per page. Below 5, the set is under-linked and orphans dominate. Above 30, the set is link-dense and anchor signal dilutes. + +--- + +## Linking inventory + +Maintain an inventory of every internal link in the pSEO set. + +Inventory format. A queryable dataset (typically a database table or analytics schema) tracking source page, target page, anchor text, link slot (breadcrumb / hub / sibling / related-record / related-content), link direction, last-validated date. + +Why inventory matters. + +- Quarterly audits run queries against the inventory: orphan check, sibling symmetry check, anchor diversity check, broken-link check. +- Template changes that affect linking (slot adjustments, anchor pattern changes) can be analyzed against the inventory before shipping. +- Pruning decisions reference the inventory: "if we noindex these 200 pages, what siblings lose links and need their slots refilled?" + +The "no inventory" failure. Without inventory, audits become "crawl the site each time," which is slow and produces inconsistent results. The inventory turns audit into a query operation. + +--- + +## When linking architecture is broken + +Symptoms: + +- Hub pages rank, child pages do not (under-linked spokes; add sibling linking) +- Specific category cluster does not rank as well as siblings (the category's internal links are sparse; investigate) +- Crawl rate plateaus while page count grows (link graph cannot absorb new pages; sitemap and link slots need restructuring) +- Algorithm update hits child pages disproportionately (children read as orphans without hub-and-spoke reinforcement) + +The fix is rarely "more pages." The fix is usually "better link graph through the existing pages." Internal linking is the structural multiplier. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md new file mode 100644 index 0000000..c108409 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/quality-control-at-scale.md @@ -0,0 +1,126 @@ +# Quality control at scale + +Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. The discipline that distinguishes durable pSEO from penalty-bait. + +Auditing all 100,000 pages individually is infeasible. Quality control at scale is sampling discipline plus automated checks plus failure thresholds plus cohort tracking. Without it, pSEO sets degrade silently until algorithm updates expose the rot. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle, balanced across data shape. + +Stratified sampling. Not "the latest 50 pages" or "the top-traffic 50 pages." A stratified sample exposes problems specific to particular data shapes. + +Stratification dimensions: + +- Sparse vs dense data. Sample some records with minimum-required fields; sample some with most-fields-populated. +- Recent vs old. Sample some pages generated in the last 30 days; sample some generated 12+ months ago. +- Popular vs niche categories. Sample some pages from high-traffic parent categories; sample some from low-traffic ones. +- Different cohort versions. If the template has shipped revisions, sample some pages from each cohort. + +Sample size by set size. + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +Cycle frequency. Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks + +Run on every page on a cadence; surface failures as a queue. + +Heading-structure check. Validates H1 exists once, H2s are in order, no orphan H3s, no H2-H3-H4 cascades that nobody scrolls. + +Schema-validity check. Validates JSON-LD against the page's intended schema type; flags missing required fields, type mismatches, malformed structured data. + +Internal-link-count check. Flags pages with fewer than 10 internal links (under-linked) or more than 50 (link-dense, anchor-signal-diluting). + +Word-count threshold check. Flags pages below the template's minimum (typically 300 to 500 words depending on category). Pages below the threshold either need data backfill or should sit as drafts. + +Duplicate-content check. Hash similarity across the set; flags pages with >80% content overlap with another page in the set. Common cause: comparison pages where X-vs-Y duplicates Y-vs-X without canonicalization. + +Broken-link check. Crawl outbound and internal links; flag 404s and 5xx responses. Ages quickly without the check; cluster pieces that linked to deleted records become orphan-link generators. + +Schema-population-rate check. For each optional schema field, the percentage of pages that populate it. Flag fields with population rates below 50%; these usually need either to be required, dropped, or backfilled. + +--- + +## Manual review checklist + +For sampled pages, the human review covers what automation misses. + +Above-the-fold answer quality. Read the first 200 words. Does it answer the user's likely query? Is the language specific to this record or templated boilerplate? + +Distinctive vs templated. Compare the page to two siblings. Could you tell them apart on substance, not just on the names? If they read identically, the template lacks variable density or the data is too sparse to differentiate. + +Citation-readiness. Would an AI engine cite this page for the user's query? Specifically: is there a self-contained answer paragraph, are statistics with sources present, is FAQPage or Article schema marked correctly? + +User-intent satisfaction. If a real user landed on this page from the target SERP, would they stay or bounce? Bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +Off-brand or off-tone signals. Does the page read consistently with the brand voice? Templated pSEO tends to drift toward generic neutral voice; the brand voice should still be present. + +--- + +## Failure thresholds + +If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. + +The 5% threshold. Empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +What "halt" means. New page generation stops. The template or data fix is shipped. The next sample audit confirms the fix improved the failure rate before generation resumes. + +Why halt instead of "fix as you go." Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +The threshold is not negotiable. "Just ship the next batch and we'll fix later" is the failure mode. The pattern produces pSEO sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. + +Cohort cuts. Pages from a given month, pages from a given template version, pages from a given data-source version. Track ranking, click-through rate, citation count (from AEO measurement), and engagement metrics by cohort. + +Drift signals. + +- Cohort A pages rank top 10; cohort B pages rank position 30. Template or data changed between cohorts; identify the change. +- Cohort A pages get cited; cohort B pages do not. Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- Cohort A pages have stable engagement; cohort B pages have decaying engagement. Cohort B may have a data freshness problem. + +Why cohorts matter. Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically; aggregate tracking misses it. + +--- + +## Team budget + +A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. A 100,000-page set requires 2 to 4 FTE. + +Where the headcount goes. + +- Sample audit cycles (monthly to quarterly) +- Automated check failure queue triage +- Manual review of sampled pages +- Template or data fixes when failures surface +- Cohort tracking analysis and investigation +- Refresh cycle execution (volatile-field refresh, template-version migration) + +The "we'll get to QC later" failure. Programs that ship without QC headcount budgeted typically degrade within 6 to 12 months. The set looks fine on launch day; the data drifts, the template ships untracked changes, the cohort gap widens, and by month 12 the algorithm update finds the rot. + +The discipline. Budget the QC headcount before generating the first page. If the budget cannot absorb 0.5+ FTE for ongoing QC, the program's scope is too large; reduce scope until QC fits. + +--- + +## When QC reveals the program is broken + +Sometimes the QC discipline reveals that the underlying program is wrong, not just that individual pages need fixes. Signals: + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole in that category; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. The sunk cost is real but smaller than the cost of continuing to generate filler. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md b/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md new file mode 100644 index 0000000..a402ea8 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/refresh-at-scale.md @@ -0,0 +1,100 @@ +# Refresh at scale + +Data refresh cadence, template versioning, cohort migration, pruning lifecycle. + +pSEO sets decay if not maintained. Refresh discipline is built into the program at design time; retrofitting refresh on a 50,000-page set that was not designed for it costs more than building it from the start. + +--- + +## Data refresh cadence + +Match the refresh cadence to the data's volatility and the query's freshness reward. + +Volatile fields. Daily to weekly refresh. Real estate listings, current prices, current availability, recent reviews, current ratings. The data feed updates daily; the pages update daily; the search and AI surfaces see fresh data. + +Slow-changing fields. Quarterly refresh. Population statistics, business categories, attribute classifications, neighborhood demographics. The data updates seasonally or annually; the refresh cycle aligns. + +Static fields. No refresh required. Geographic coordinates, founding years, fixed attributes. Set at record creation; tracked in the schema's update-tag system. + +Mixed-cadence pages. Most pSEO pages are mixed: some volatile fields, some slow-changing, some static. The refresh pipeline updates each field on its own cadence; the page renders the latest data on each request (or rebuilds when fields change). + +The "refresh cadence wasn't designed in" failure. A program ships with annual refresh as the plan. Six months in, the volatile fields are stale (prices moved, listings expired). The fix is expensive: retrofit a daily pipeline for fields that should have had one from launch. + +--- + +## Template version migration + +When the template improves, all existing pages need migration. + +Why templates ship revisions. AEO patterns evolve, SERP intent shifts, schema requirements update, brand voice tightens. Templates from 18 months ago may need significant updates to compete in the current search and AI environment. + +Cohort-by-cohort migration. Migrate one cohort at a time, monitor, then migrate the next. The cohort might be a category, a generation period, a data-density tier. The cohort approach surfaces problems specific to particular page shapes before they spread across the entire set. + +Big-bang migration. Migrate all pages at once. Higher risk; if the new template has a regression, the entire set degrades simultaneously. Sometimes the right call when the migration is small or the team can roll back fast; usually the wrong call for large changes. + +Migration monitoring. Each cohort post-migration is monitored for 30 days minimum: ranking changes, citation count changes, click-through rate changes, engagement metric changes. Negative trends pause the migration and surface the regression before it propagates. + +Rollback discipline. The template migration ships with a rollback path. If a cohort's metrics degrade post-migration, the cohort rolls back to the previous template while the regression is investigated. Without rollback discipline, a bad migration produces permanent damage. + +--- + +## Cohort migration patterns + +Three common patterns. + +Category-based cohort migration. Migrate one parent category at a time. Real estate: migrate Denver pages first, monitor 30 days, then migrate Seattle. The advantage: category-level metrics are clean; investigation is scoped. + +Generation-period cohort migration. Migrate the oldest cohort first (pages generated in year 1), then the next, then the next. The advantage: oldest pages have the most accumulated decay; migrating them first improves the set's average quality fastest. + +Data-density cohort migration. Migrate the dense-data pages first (most fields populated), then the medium, then the sparse. The advantage: dense pages have the most upside from template improvements; sparse pages may need data backfill before template migration earns gains. + +The right pattern depends on the migration's intent. AEO-focused migrations often prefer dense-data first. Algorithm-update recovery migrations often prefer category-based. Maintenance migrations often prefer generation-period. + +--- + +## Pruning lifecycle + +Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. + +The 24-month checkpoint. Standard cutoff. A page that has been indexed for 24+ months and has earned zero impressions in Search Console is dead weight. Pruning options: noindex, 410, or 301 redirect to a more-relevant alternative. + +Earlier pruning for some categories. Time-sensitive pages (annual "best of [year]" pages, event-specific pages, deal-specific pages) prune earlier. A "best of 2024" page generated in 2024 should be archived or pruned by mid-2026; the freshness signal has decayed. + +Later pruning for stable categories. Some categories support evergreen pages that earn traffic for decades. Geographic pages (neighborhoods, cities), historical reference pages, foundational definitional pages. The 24-month checkpoint is too aggressive for these; review case-by-case. + +Pruning is hygiene, not failure. Pruning a page that did not earn traffic is not abandoning the program; it is removing dead weight that drags the set's quality signal down. The set is healthier with 40,000 traffic-earning pages than with the same 40,000 plus 60,000 dead pages. + +--- + +## Set-level refresh + +Occasionally the entire set's template needs a refresh. + +Triggers for set-level refresh. + +- AEO patterns shifted significantly (the entire set needs better above-the-fold answers, FAQPage schema, or source citations) +- The dataset's underlying source changed schema (the new data exposes fields the old template did not render) +- User expectations evolved (the category's accepted page shape shifted; the set's pages now read as dated) +- An algorithm update affected the set disproportionately (the set's design needs to adapt to the new ranking signals) + +Set-level refresh is a 6-month project. Plan accordingly. The work includes template redesign, cohort-by-cohort migration, post-migration monitoring, and pruning of pages that the new template cannot improve. Underestimating the duration is the most common mistake. + +The "do not refresh and let the set decay" anti-pattern. Some teams treat the initial pSEO build as ship-and-forget. The set ranks for 12 to 18 months, then declines as competitors with refreshed sets pass it. The decline accelerates when an algorithm update finds the set's accumulated drift. Refresh is part of the program's ongoing cost; teams that do not budget for it should not start the program. + +--- + +## Refresh budget + +The ongoing refresh cost in headcount. + +Volatile-field refresh. Mostly automated (data pipelines pull new data into the schema). 0.1 to 0.5 FTE for pipeline maintenance and exception handling. + +Slow-changing-field refresh. Quarterly cycles. 0.2 to 0.5 FTE during cycles; lower between cycles. + +Template version migration. Project-based when migrations ship. 1 to 3 FTE for the duration of the migration; varies by set size and migration scope. + +Pruning lifecycle. Quarterly review of dead pages. 0.1 to 0.3 FTE. + +Total ongoing refresh budget. A 10,000-page set: roughly 0.5 FTE steady state plus migration projects when they ship. A 100,000-page set: 1 to 2 FTE steady state plus larger migration projects. + +The refresh budget is in addition to the QC budget. Programs that under-budget either degrade; programs that budget both produce durable traffic for years. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md new file mode 100644 index 0000000..563400f --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/schema-design-patterns.md @@ -0,0 +1,114 @@ +# Schema design patterns + +Field count, computed fields, cross-record fields, update tags, schema-as-product. The data shape that drives the template. + +The schema design here is the methodology layer: what shape the data takes, what fields earn their keep, what derivations add depth. Specific framework type signatures, ORM bindings, and database column choices are stack-specific implementation that varies by team. + +--- + +## Field count signals depth + +5 fields per record is thin. 15 to 20 is competent. 30+ is deep. + +Why field count matters. Field count determines what the template can render at depth versus what falls back to filler. A record with 5 fields can produce a 200-word page; a record with 30 fields can produce a 1,500-word page that reads as substantive across multiple sections. + +The "thin schema" failure mode. Teams design with 5 to 10 fields, ship, find pages reading as thin, then try to bolt on additional fields after the fact. Bolt-on fields rarely populate consistently across the existing dataset; the result is a half-thin set with a thin tail and a thicker head. + +The "too-many-fields" trap. 50+ fields per record where most are sparsely populated. The schema looks deep on paper but most fields are empty for most records. The template either renders empty sections (looks broken) or hides them (back to thin pages). Better to design 25 fields with 90% population than 50 fields with 30% population. + +--- + +## Required vs optional fields + +Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. + +Required field discipline. Define a minimum field-count threshold below which a record does not get a public page. The threshold ships in the schema validation; pages that fail validation sit as drafts until their data populates. + +Optional field handling. Each optional field has a render rule: if populated, render this section; if empty, hide this section or substitute a computed default. The render rules are part of the template, not afterthoughts. + +The discipline. A page with 25 of 30 optional fields populated is fine. A page with 3 of 30 should not ship; it produces filler content that drags the entire set's quality signal down. + +--- + +## Computed fields + +Derived from source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +Common computed-field patterns. + +- Aggregations. "Average price per square foot" computed from listing data; "median rating" computed from review data. +- Derived classifications. "Price tier" computed from price percentiles; "freshness tier" computed from data age. +- Comparisons. "Price vs neighborhood average" computed from the record's price and the parent category's average; "rating vs category average." +- Trends. "Price trend over 12 months" computed from time-series source data; "review-volume trend" from review-date stamps. +- Rankings. "Top 10 percent by [field]" computed across the set; "ranked by [field] within [category]." + +Why computed fields earn their keep. Each computed field adds a section to the template without requiring more source-data collection. The pipeline does the work; the template renders the result. This is how 15-field source data produces 30-field rendered pages. + +--- + +## Cross-record fields + +Fields that reference OTHER records in the set. Enable internal linking and comparison without manual curation. + +Common cross-record patterns. + +- Most similar records. "5 most similar neighborhoods" computed by attribute distance. +- Parent and child references. "Parent category" and "list of child records" computed from the hierarchy. +- Sibling-comparison aggregates. "Average price across sibling neighborhoods" computed across the parent's children. +- Recommended-related. "Users who viewed X also viewed Y" computed from analytics data (when first-party analytics is available). + +How they power linking. The sibling-link slot in the template renders from the "most similar records" cross-record field. Without this field, sibling linking becomes manual curation at scale, which is infeasible. + +--- + +## Update frequency tags + +Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). + +Tag categories. + +- Static. Set at record creation; rarely changes (geographic coordinates, neighborhood name, founding year). +- Slow-changing. Updates quarterly to annually (population statistics, business categories, attribute classifications). +- Volatile. Updates daily to weekly (current price, current availability, current rating, recent reviews). +- Real-time. Updates within minutes (live availability, dynamic pricing). Only relevant when the underlying data feed supports it. + +Why tagging matters. Without tags, refresh becomes "audit everything every cycle," which does not scale. With tags, refresh becomes "refresh volatile fields daily, slow-changing fields quarterly, static fields never," which scales. + +--- + +## Schema-as-product principle + +The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. + +Schema versioning. Major schema changes (renaming required fields, restructuring nested objects, changing field types) bump a version. Minor changes (adding optional fields, adding computed fields) do not. All schema changes are reviewed; breaking changes require migration plans. + +Schema documentation. Every field has a description, a source (where the data comes from), an update tag, a population rate (what percentage of records have this field), and example values. Documentation lives alongside the schema; it is not a separate doc that drifts. + +Schema review. Before adding fields or changing field types, the schema change goes through review with stakeholders who depend on the schema (template authors, QC reviewers, analytics consumers). Schema changes affect downstream rendering; review catches breakage before it ships. + +Schema testing. Validation rules ship as automated tests. Required fields, type constraints, value-range constraints, cross-field consistency checks. The tests run on every record in the dataset on a cadence; failures surface in the QC queue. + +--- + +## When the schema is wrong + +The schema is wrong when: + +- Required-field threshold produces too few publishable pages (relax the threshold or fix the data pipeline) +- Required-field threshold produces too many shallow pages (raise the threshold; let thin records sit as drafts) +- Optional fields are sparsely populated, dragging the average page quality down (drop them and refocus on dense fields) +- Computed fields are not actually used by the template (cut them; reduce schema bloat) +- Cross-record fields produce poor sibling matches (revise the similarity algorithm; the sibling-link section is doing real work for users) +- Update tags are wrong (refresh cadence is missing or over-shooting; recalibrate) + +The schema is iterated, not designed once. The "schema-as-product" principle makes that iteration safe by enforcing review and migration discipline; without it, every schema change risks breaking the template. + +--- + +## Methodology-level choices that stay in the public skill + +Field-count thresholds, computed-field patterns, cross-record patterns, update-tag categories, the schema-as-product principle. + +## Implementation choices that stay internal + +The specific schema language (TypeScript type definitions, dbt YAML, Sanity schema config, Prisma schema, etc.). The specific ORM or query layer. The specific validation framework. The specific deployment pipeline for schema migrations. These vary by stack. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md b/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md new file mode 100644 index 0000000..e56000d --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/template-design-patterns.md @@ -0,0 +1,104 @@ +# Template design patterns + +Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. + +The template is the structure that data fills. Templates are designed at the methodology level here; specific framework implementations (rendering, slot composition, build-time generation versus on-demand rendering) are stack-specific and belong in internal team documentation. + +--- + +## Above-the-fold answer + +The first 200 words of the rendered page answer the user's specific query. + +Why. Search engines and AI engines both extract the top of the page disproportionately. Featured snippets pull from the first answer-shaped paragraph. AI engines extract the first 200 words as the canonical citation. The reader who lands on the page from a SERP decides within 5 seconds whether to stay; the answer needs to be visible. + +The pattern. Lead with the structured answer to the specific query: the price, the rating, the count, the comparison, the location, the recommendation. Follow with supporting details that justify or expand the answer. The opening is not a marketing introduction; it is the answer paragraph. + +Anti-pattern. "Welcome to our [page type] page. Below you will find information about [topic]." This intro reads as filler to crawlers and humans. Cut it; lead with the answer. + +--- + +## Variable density + +The template accommodates records with sparse fields and dense records gracefully. + +Sparse-record handling. Some records will have fewer fields populated. The template needs fallback patterns: hide sections that depend on missing fields, substitute computed defaults, surface "limited data available" rather than rendering empty headings. + +Dense-record handling. Some records will have many fields. The template needs progressive disclosure: collapse less-essential sections behind expandable headings, paginate long lists, prioritize the most-queried fields above the fold. + +The shape principle. Two pages from the same template can differ significantly in length and depth based on data density without either looking broken. A page with 20% of optional fields populated should still feel competent; a page with 95% should not feel overstuffed. + +--- + +## Heading hierarchy reflects data + +H2s and H3s map to data sections, not to template decoration. + +The pattern. The H2 set is the same across all pages in the template, but the content under each H2 reflects each page's specific data. "Overview," "Details," "Comparisons," "Related" might be the H2 set; what populates each varies per page. + +Snippet-bait paragraphs at H2 level. Each H2 has a 40 to 60 word answer paragraph immediately following it that summarizes that section's specific content. AI engines often quote these as multi-paragraph citations. + +Anti-pattern. Every page has a different H2 set because the template branches on data. The inconsistency confuses crawlers; the heading structure should be predictable across the set. + +--- + +## Schema markup as part of template + +Structured data renders machine-readable signals at scale. + +The principle. Pick the schema type that matches the page's content (Product, Article, LocalBusiness, FAQPage, BreadcrumbList, etc.). Embed the schema in the template; populate from the same data that renders the visible page. The schema is generated, not hand-written; the template ensures every page has it. + +Validation discipline. Run schema validation as an automated check on every generated page. Schema errors produce silent failures in search and AI surfaces; the validation catches them before publish. + +Schema field coverage. Populate every relevant schema field, not just the required ones. Optional schema fields (aggregateRating, additionalProperty, areaServed, etc.) signal depth at scale even when individual fields are not visibly rendered. + +--- + +## Internal linking placeholders + +The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. + +Standard slot patterns. + +- Breadcrumb slot. Path from home to current record. 3 to 4 levels typical. +- Parent-category slot. Link up to the hub page for the record's category. +- Sibling slot. 5 to 15 related sibling records. Computed from cross-record fields in the schema. +- Related-record slot. 3 to 5 records related across categories (different parent, similar attributes). +- Related-content slot. Editorial content related to the record (blog posts, guides, comparison editorials). + +Total internal links per page. 15 to 30 typical for a well-linked pSEO page. Below 10, the page is under-linked; above 50, the page reads as link-dense and dilutes anchor signal. + +--- + +## Distinctive value per page + +Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. + +The test. Generate three sample pages from the template using different records. Read all three. Can you tell them apart on substance, not just on the names? If the pages are interchangeable in everything but identifiers, the template is not generating distinct value. + +The fix. Surface the distinctive fields prominently. The fields that vary most across the set are the ones that justify the page's existence; those should be in the above-the-fold answer and in the H2 structure, not buried as "additional details." + +--- + +## Quality bar: the random-sample test + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. + +The test sequence. + +1. Pick 5 random records from the dataset. +2. Render them through the template. +3. Read each page as if you arrived from a search results page. +4. Score each page on three dimensions: does it answer the query, is the depth competitive with editorial content for the same query, would you trust this page as a source. + +If any of the 5 fails, the template needs work before scaling. The 5-page sample is the minimum viable QC; the cohort tracking discipline scales it across the program's lifetime. + +--- + +## Methodology-level design choices that stay in the public skill + +The principles above. Field-count heuristics, slot patterns, hierarchy choices, validation discipline, sample-test discipline. + +## Implementation choices that stay internal + +The framework rendering choice (build-time generation, server rendering, hybrid), the specific component composition pattern, the specific data-fetching layer, the deployment topology, the cache-invalidation strategy. These vary by stack and team and should not be prescribed at the methodology level. diff --git a/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md b/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md new file mode 100644 index 0000000..269fb79 --- /dev/null +++ b/dist/pi/.agents/skills/programmatic-seo/references/when-pseo-works-decision.md @@ -0,0 +1,107 @@ +# When pSEO works decision + +The five-criterion framework for deciding whether programmatic SEO is the right answer, with worked examples across business types. + +The default answer is no. Most teams asking "should we do pSEO?" should hear "probably not." pSEO works only when all five criteria are met; failing any one is a hard signal to pursue editorial content or paid acquisition instead. + +--- + +## The five criteria + +### 1. Real underlying data + +A genuine structured data source with depth. 10+ fields per record, ideally 20+. First-party data, licensed datasets, expert-curated content, or synthesized multi-source data. Not scraped Wikipedia plus AI rewrite. + +The test. Could a competent reader extract genuine value from a single page in the set without reading any other page? If yes, the data is real. If no, the page is filler dressed as pSEO. + +### 2. Long-tail query volume justifies the effort + +The queries the program targets have meaningful aggregate volume. Individual queries can be small (10 to 100 monthly searches each) as long as the aggregate across the set is large. + +The test. Pull the top 20 candidate queries from keyword research. Sum their volumes. If the aggregate is below 5,000 monthly searches, pSEO probably does not justify the build. If above 50,000, the volume case is strong. + +The illusion to watch for. Long-tail keywords that look reasonable in keyword tools but are not actually searched by humans. Permutation keywords (every adjective times every noun) often have keyword-tool volume because the tools generate the data; the queries themselves are dead. + +### 3. User intent is queryable + +The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +Queryable intent examples. "Homes for sale in [neighborhood]" answered by listing data. "Software engineer salary at [company]" answered by salary data. "Restaurants near [landmark]" answered by location and rating data. + +Non-queryable intent examples. "Should I buy a house in [neighborhood]" requires personal financial judgment. "Why is Y better than X" requires editorial argumentation. "How do I choose [thing]" requires guidance. + +If the intent requires narrative, choose editorial. If the intent requires data presented well, choose pSEO. + +### 4. Update cadence aligns with query volatility + +Real estate listings update daily; the data feed updates daily; pSEO refresh aligns with the volatility. "Best [thing] for [year]" pages get stale annually; the refresh cadence is annual. + +The test. Match the data's update frequency to the query's volatility. If the data is static (geographic features, founding dates) and the queries are stable, low maintenance. If the data shifts daily and the queries reward freshness, daily refresh. + +The trap. Underestimating refresh effort at design time. A team designs for "annual refresh" because that feels reasonable, ships 50,000 pages, and discovers the refresh requires 2 FTE for 6 weeks every year. The cadence was real; the resourcing was not. + +### 5. Quality control is operationally feasible + +Headcount is budgeted to sample-audit the set, fix failures, and maintain quality. Not aspirationally; in actual hours allocated. + +The rule of thumb. A 10,000-page set requires roughly 0.5 to 1.0 FTE of ongoing quality control. A 100,000-page set requires 2 to 4 FTE. If the budget cannot absorb the QC headcount, the program will degrade within 12 months of launch. + +--- + +## Worked examples + +### Example 1: real estate listings (yes) + +A regional brokerage considering pSEO for "homes for sale in [neighborhood]" pages. + +- Real underlying data: yes. MLS feeds with 30+ fields per listing. +- Long-tail volume: yes. Each neighborhood query has 50 to 500 monthly searches; aggregate across 200 neighborhoods is significant. +- Queryable intent: yes. Buyers want listings. +- Update cadence: data updates hourly; pSEO refresh aligns daily; manageable. +- QC feasible: yes; the brokerage already has data ops headcount. + +Decision: yes. This is the canonical pSEO use case. + +### Example 2: SaaS comparison pages (maybe) + +A B2B SaaS considering "X vs Y" pages for every competitor combination. + +- Real underlying data: judgment call. If the comparison data is licensed (G2 reviews, feature databases) or first-party (the team's actual evaluation), yes. If the data is "scraped competitor websites plus AI summary," no. +- Long-tail volume: yes for major competitors; thin for niche ones. +- Queryable intent: yes for "X vs Y," but readers often want narrative judgment ("which is better for my use case") that data alone cannot supply. +- Update cadence: feature databases drift; quarterly refresh required. +- QC feasible: depends on team size. + +Decision: maybe, leaning yes if the team commits to combining structured comparison data with brief editorial analysis per page. Pure-data comparison pages tend to underperform pages that include the analytical layer. + +### Example 3: AI-generated city guides (no) + +A travel content site considering "things to do in [city]" pSEO across 5,000 cities. + +- Real underlying data: no. The plan is "AI-generate the content from public sources." Anyone can replicate. +- Long-tail volume: yes for major cities; thin for small ones. +- Queryable intent: yes, but the queries reward editorial depth (curation, recommendations, taste). +- Update cadence: events change weekly; the AI-generated approach cannot match. +- QC feasible: no; "AI-generate 5,000 pages" is the plan because QC was not budgeted. + +Decision: no. This is the pattern that produces penalty-bait. Either invest in real expert-curated data or pursue editorial content for the highest-volume cities only. + +### Example 4: enterprise B2B pricing pages (no) + +An enterprise B2B SaaS considering "pricing for [industry] companies" pSEO across 50 industries. + +- Real underlying data: no. Pricing for enterprise SaaS is typically negotiated; there is no structured data feed to render. +- Long-tail volume: yes for some industries. +- Queryable intent: no. Buyers want a sales conversation, not a price table. +- Update cadence: not relevant. +- QC feasible: not relevant. + +Decision: no. The intent is not queryable. Editorial content explaining the buying process plus a sales-led conversion path is the right approach, not pSEO. + +--- + +## When two of five criteria fail, walk away + +If two or more criteria fail, walk away from the pSEO idea. The temptation is to start anyway and "improve as you go," but pSEO programs that launch with weak foundations rarely recover. The data depth, the QC budget, and the refresh cadence are designed in or they are missing forever. + +If exactly one criterion fails, see whether a smaller scope resolves the failure. "5,000 pages across all cities" failing on data depth might become "500 pages across major cities with expert-curated depth" that succeeds on all five criteria. diff --git a/dist/pi/.agents/skills/qa-testing/SKILL.md b/dist/pi/.agents/skills/qa-testing/SKILL.md new file mode 100644 index 0000000..22a57a5 --- /dev/null +++ b/dist/pi/.agents/skills/qa-testing/SKILL.md @@ -0,0 +1,294 @@ +--- +name: qa-testing +description: "Run QA testing on a page, feature, or full site at one of three depth tiers (smoke, standard, full). Use this skill whenever the user asks to test a page, audit a site, check for bugs, verify a deploy, run a QA sweep, or review accessibility, performance, or SEO basics. Triggers on test, QA, audit, verify, check, is it working, does it look right, broken, 404, image not loading, post-deploy check, regression test. Also triggers proactively after any significant code change or new page launch where verification matters." +category: qa +catalog_summary: "Pre-launch QA, regression testing, cross-browser checks" +display_order: 1 +--- + +# QA Testing + +Verify that a page, feature, or site is working before declaring it shipped. Stack-agnostic. Console-snippet driven for speed. + +This skill is faster than `accessibility-audit` (which goes deeper on WCAG) and `performance-optimization` (which goes deeper on Core Web Vitals). Use this skill for general QA. Use the specialists for deep audits. + +--- + +## When to use + +- After every deploy (smoke test) +- After launching a new page or feature (standard audit) +- Before a major release (full release matrix) +- Investigating a "something looks off" report +- Pre-launch verification of a site or section + +## When NOT to use + +- Deep accessibility compliance work (use `accessibility-audit`) +- Deep performance investigation (use `performance-optimization`) +- Code review or debugging (use `code-review-web`) +- Initial site setup or technical SEO baseline (use `seo-technical`) + +--- + +## Required inputs + +- The page URL or site under test +- The tier of QA needed (smoke, standard, or full) +- Browser dev tools access +- Any specific concerns to check beyond the standard tier + +--- + +## The framework: 3 tiers + +QA scales with the stakes. Pick the tier that matches the context. + +\| Tier \| When to run \| Time \| Coverage \| +\|---\|---\|---\|---\| +\| Smoke \| After every deploy \| 2 minutes \| Critical signals only \| +\| Standard \| New page or feature \| 10 minutes \| On-page basics, accessibility, structure \| +\| Full \| Major release, pre-launch \| 30+ minutes \| Comprehensive across all dimensions \| + +### Tier 1: Smoke test + +The 2-minute "did the deploy break anything obvious?" check. Run after every deploy. + +Console snippet (paste in browser dev tools): + +```javascript +const smoke = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + h1Count: document.querySelectorAll('h1').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { try { return JSON.parse(s.innerText)['@type'] } catch(e) { return 'invalid' } }), + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete \|\| i.naturalWidth === 0).length, +}; +console.log(JSON.stringify(smoke, null, 2)); +``` + +Pass criteria: +- Title exists and is 30 to 60 characters +- Canonical points at the production domain (never staging or preview URLs) +- Exactly one H1 +- Zero missing alts +- Zero broken images +- Schema includes the expected types for the page + +If any of these fail, do not proceed with deeper testing until the smoke issue is fixed. + +### Tier 2: Standard page audit + +The 10-minute new-page-or-feature audit. Covers the on-page basics plus accessibility and structure. + +Console snippet: + +```javascript +const audit = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + metaDesc: document.querySelector('meta[name="description"]')?.content, + metaDescLen: document.querySelector('meta[name="description"]')?.content?.length, + ogImage: document.querySelector('meta[property="og:image"]')?.content, + ogTitle: document.querySelector('meta[property="og:title"]')?.content, + twitterCard: document.querySelector('meta[name="twitter:card"]')?.content, + h1Count: document.querySelectorAll('h1').length, + h1Text: document.querySelector('h1')?.innerText, + h2Count: document.querySelectorAll('h2').length, + h2s: [...document.querySelectorAll('h2')].map(h => h.innerText.trim().slice(0, 60)), + totalImages: document.querySelectorAll('img').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete \|\| i.naturalWidth === 0).length, + externalLinksWithoutNoopener: [...document.querySelectorAll('a[target="_blank"]')] + .filter(a => !a.rel?.includes('noopener')).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { + try { + const d = JSON.parse(s.innerText); + return d['@graph'] ? d['@graph'].map(x => x['@type']) : d['@type']; + } catch(e) { return 'invalid' } + }), + hasSkipLink: !!document.querySelector('a[href^="#"]:first-of-type'), + pageLanguage: document.documentElement.lang \|\| 'NOT SET', + hasFavicon: !!document.querySelector('link[rel="icon"]'), +}; +console.log(JSON.stringify(audit, null, 2)); +``` + +Pass criteria* (in addition to smoke): +- Meta description: 120 to 160 characters +- og:image, og:title, twitter:card present +- H2s present and descriptive +- All external links with `target="_blank"` have `rel="noopener"` +- Page language declared (`lang` attribute on `<html>`) +- Favicon present + +### Tier 3: Full release matrix + +The 30-minute pre-launch check. Cover all dimensions. + +\| Dimension \| Pass criteria \| +\|---\|---\| +\| Smoke and standard \| All pass \| +\| Accessibility (basic) \| Run browser audit tool (e.g., Lighthouse), score above 90 \| +\| Performance (basic) \| Lighthouse Performance score above 80, LCP under 2.5s, CLS under 0.1 \| +\| Mobile responsiveness \| Tested at 375px, 768px, 1024px, 1440px \| +\| Cross-browser \| Tested in Chrome, Safari, Firefox (and Edge if relevant audience) \| +\| Forms \| All forms submit successfully and validate correctly \| +\| Internal links \| No broken internal links (sample 20 random) \| +\| External links \| All return 200 (sample 10) \| +\| Sitemap \| Returns 200, lists canonical URLs only \| +\| robots.txt \| Allows production crawlers, blocks staging if applicable \| +\| Security headers \| HSTS, X-Frame-Options, X-Content-Type-Options present \| +\| HTTPS \| All resources load over HTTPS, no mixed content \| +\| 404 handling \| 404 pages return HTTP 404 (not soft 200) \| +\| Schema validation \| All schema validates in Rich Results Test \| +\| Analytics \| Events fire as expected on key user actions \| +\| Cache behavior \| Cache headers appropriate for page type \| + +For headers, run: + +```javascript +fetch(window.location.origin, { method: 'HEAD' }) + .then(r => { + const headers = {}; + for (const [k, v] of r.headers.entries()) headers[k] = v; + console.log(JSON.stringify(headers, null, 2)); + }); +``` + +Look for: `strict-transport-security`, `x-frame-options`, `x-content-type-options`. + +--- + +## Specific QA snippets + +### Image audit + +```javascript +const imgs = [...document.querySelectorAll('img')].map(i => ({ + src: i.src.split('/').pop().split('?')[0].slice(0, 60), + alt: i.alt \|\| 'MISSING', + width: i.naturalWidth, + height: i.naturalHeight, + loaded: i.complete && i.naturalWidth > 0, +})); +console.table(imgs); +console.log({ + total: imgs.length, + broken: imgs.filter(i => !i.loaded).length, + noAlt: imgs.filter(i => i.alt === 'MISSING').length, +}); +``` + +### Heading hierarchy check + +```javascript +const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')].map(h => ({ + level: parseInt(h.tagName[1]), + text: h.innerText.trim().slice(0, 80), +})); +console.table(headings); + +// Check for skipped levels +const levels = headings.map(h => h.level); +let skipped = false; +for (let i = 1; i < levels.length; i++) { + if (levels[i] > levels[i-1] + 1) { + console.warn(`Skipped from H${levels[i-1]} to H${levels[i]}: "${headings[i].text}"`); + skipped = true; + } +} +if (!skipped) console.log('No skipped heading levels'); +``` + +### Contrast spot-check + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + const r = ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2); + return r + ':1 ' + (parseFloat(r) >= 4.5 ? 'PASS body' : parseFloat(r) >= 3 ? 'PASS large only' : 'FAIL'); +} + +// Examples +contrast('#FFFFFF', '#4B5563'); // body color check +contrast('#FFFFFF', '#9CA3AF'); // verify gray choices +``` + +### Form audit (per form) + +```javascript +[...document.querySelectorAll('form')].forEach((form, i) => { + const fields = [...form.querySelectorAll('input, select, textarea')].map(field => ({ + type: field.type \|\| field.tagName.toLowerCase(), + name: field.name, + hasLabel: !!form.querySelector(`label[for="${field.id}"]`) \|\| !!field.closest('label'), + required: field.required, + })); + console.log(`Form ${i + 1}:`); + console.table(fields); +}); +``` + +### External link audit + +```javascript +const externalLinks = [...document.querySelectorAll('a[href^="http"]')] + .filter(a => !a.href.includes(window.location.host)); +const issues = externalLinks.filter(a => + a.target === '_blank' && (!a.rel?.includes('noopener') \|\| !a.rel?.includes('noreferrer')) +); +if (issues.length) { + console.warn(`${issues.length} external links missing noopener/noreferrer:`); + issues.forEach(a => console.warn(a.href)); +} else { + console.log(`All ${externalLinks.length} external links properly attributed`); +} +``` + +--- + +## Workflow + +1. Pick the tier. Smoke for routine deploys. Standard for new work. Full for releases. +2. Run the snippet. Paste the appropriate console snippet, review output. +3. Note failures. Each failure either gets fixed before ship or filed as a known issue. +4. For Standard tier, add: visual review at 375px, 768px, 1440px. Test the primary user flow. +5. For Full tier, add: cross-browser testing, Lighthouse audit, schema validation, security headers, 404 handling. +6. Document. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md) for full audits. + +--- + +## Failure patterns + +- Skipping smoke tests on "small" deploys. Half of broken-production incidents start with a deploy that "looked safe." +- Running snippets but not reading the output. The console snippet is a tool. The judgment is reading what it returns. +- Visual-only QA. Eyeballing a page misses missing alt text, broken schema, missing canonical. Always run the snippet. +- Single-browser testing. Mobile Safari and Chrome differ enough to surprise you. Test at least Chrome and Safari. +- No mobile QA. The 375px viewport is where most users live. Test there or get burned later. +- Pass-fail with no remediation. A failed QA must produce a fix or a known-issue ticket. Failed QA that ships unfixed is process theater. + +--- + +## Output format + +For smoke tests: console output is the report. + +For standard and full audits: a markdown report at `qa-report-[date].md`. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md). + +--- + +## Reference files + +- [`references/qa-report-template.md`](references/qa-report-template.md) - Markdown report template for standard and full audits. diff --git a/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md b/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md new file mode 100644 index 0000000..91b7bdd --- /dev/null +++ b/dist/pi/.agents/skills/qa-testing/references/qa-report-template.md @@ -0,0 +1,200 @@ +# QA Report: [Page or Site URL] + +Date: [YYYY-MM-DD] +Tier: [Smoke / Standard / Full] +Tester: [Name] +Browser(s): [List] +Device(s): [Desktop, mobile device, viewport width] + +--- + +## Summary + +Overall: [Pass / Pass with minor issues / Fail] + +[1 to 3 sentences. The headline finding. What works, what's broken, what to do.] + +Critical issues found: [N] +Important issues found: [N] +Minor issues found: [N] + +--- + +## Smoke check + +\| Check \| Pass \| Notes \| +\|---\|---\|---\| +\| Title tag present and 30-60 chars \| ☐ \| \| +\| Canonical = production URL \| ☐ \| \| +\| Exactly one H1 \| ☐ \| \| +\| Zero missing image alts \| ☐ \| \| +\| Zero broken images \| ☐ \| \| +\| Schema present and valid \| ☐ \| \| + +--- + +## Standard audit (if applicable) + +### Meta tags +\| Field \| Value \| Pass \| +\|---\|---\|---\| +\| Title \| \| ☐ \| +\| Title length \| \| ☐ \| +\| Meta description \| \| ☐ \| +\| Meta description length \| \| ☐ \| +\| og:image \| \| ☐ \| +\| og:title \| \| ☐ \| +\| twitter:card \| \| ☐ \| + +### Structure +\| Check \| Result \| Pass \| +\|---\|---\|---\| +\| H1 text \| \| ☐ \| +\| H2 count \| \| ☐ \| +\| Skipped heading levels \| \| ☐ \| +\| Page language declared \| \| ☐ \| +\| Favicon present \| \| ☐ \| + +### Images +\| Check \| Count \| +\|---\|---\| +\| Total images \| \| +\| Broken images \| \| +\| Missing alt text \| \| + +### Links +\| Check \| Count \| +\|---\|---\| +\| External links \| \| +\| External missing `noopener` \| \| + +### Schema +[List schema types found and any validation issues] + +--- + +## Full release matrix (if applicable) + +### Accessibility +- [ ] Lighthouse Accessibility score above 90 (actual: __) +- [ ] No skipped heading levels +- [ ] All form fields have labels +- [ ] Skip link present +- [ ] Page operable by keyboard alone +- [ ] Focus indicators visible + +### Performance +- [ ] Lighthouse Performance score above 80 (actual: __) +- [ ] LCP under 2.5s (actual: __) +- [ ] CLS under 0.1 (actual: __) +- [ ] INP under 200ms (actual: __) + +### Mobile responsiveness +- [ ] 375px viewport: layout intact, no horizontal scroll +- [ ] 768px viewport: layout adapts cleanly +- [ ] 1024px viewport: desktop variant works +- [ ] 1440px viewport: max-width holds, no awkward stretch +- [ ] Tap targets minimum 44px + +### Cross-browser +- [ ] Chrome: tested +- [ ] Safari: tested +- [ ] Firefox: tested +- [ ] Edge: tested (if relevant audience) +- [ ] Mobile Safari: tested +- [ ] Mobile Chrome: tested + +### Forms +- [ ] All forms submit successfully +- [ ] Validation works as expected +- [ ] Error states display clearly +- [ ] Success states display clearly + +### Links +- [ ] No broken internal links (sample of 20 tested) +- [ ] No broken external links (sample of 10 tested) + +### Site infrastructure +- [ ] Sitemap returns 200 and lists canonical URLs +- [ ] robots.txt correct (allows production, blocks staging) +- [ ] HTTPS on all resources, no mixed content +- [ ] HSTS header present +- [ ] X-Frame-Options header present +- [ ] X-Content-Type-Options header present + +### 404 handling +- [ ] 404 pages return HTTP 404 (not 200) +- [ ] 404 page provides helpful navigation + +### Schema +- [ ] All schema validates in Rich Results Test +- [ ] Required properties filled +- [ ] No mixed signals (canonical vs sitemap vs internal links) + +### Analytics +- [ ] Page view fires correctly +- [ ] Key events fire on user actions +- [ ] No PII in event parameters + +### Cache behavior +- [ ] Cache headers appropriate for page type +- [ ] No stale content displayed +- [ ] Cache invalidation works after content updates + +--- + +## Critical issues + +[Things that block ship.] + +### 1. [Issue title] +- Where: [URL or component] +- What: [What's broken] +- Impact: [Who is affected] +- Fix: [Specific remediation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Things that should be fixed but might not block ship.] + +### 1. [Issue title] +- Where: +- What: +- Impact: +- Fix: + +--- + +## Minor issues + +[Polish items.] + +- [Issue] +- [Issue] +- [Issue] + +--- + +## Recommendations + +[Suggestions beyond fixing the identified issues.] + +- [Recommendation] +- [Recommendation] + +--- + +## Sign-off + +- [ ] All critical issues resolved +- [ ] Important issues resolved or have known-issue tickets +- [ ] Minor issues acknowledged + +Approved for ship: [Yes / No / Conditional] +Approved by: [Name] +Date: [YYYY-MM-DD] diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md b/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md new file mode 100644 index 0000000..d364cea --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/SKILL.md @@ -0,0 +1,283 @@ +--- +name: quiz-and-assessment-design +description: "Designing quizzes, personality assessments, and recommendation tools that segment users into actionable categories rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping, lead capture integration. Honest about clickbait-quiz (engagement only), vanity-result (entertaining, not useful), and actionable-segmentation (genuine categorization that drives next-step recommendations) patterns. Triggers on quiz, assessment, personality test, recommendation tool, scorecard, diagnostic, fit evaluator, what-type-of-X-are-you, persona quiz. Also triggers when an audience needs a categorization-driven lead magnet, when a vanity quiz is producing engagement but no qualified leads, or when an assessment is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing quizzes and assessments that produce actionable segmentation. Distinguishes clickbait-quiz (engagement only) from vanity-result (entertaining, not useful) from actionable-segmentation (genuine categorization that drives next-step recommendations)" +display_order: 3 +--- + +# Quiz and Assessment Design + +A senior growth practitioner's playbook for designing quizzes and assessments that produce actionable segmentation rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping. The discipline of building a quiz the audience actually uses to make a decision. + +Most quizzes on the web are clickbait. "What kind of pizza are you?" energy applied to brand-building, with results that flatter the taker but drive no specific next step. The quiz captures emails because the format implies fun; the leads are unqualified because the result told them nothing they could act on. + +The quizzes that work as compounding assets do something different. They categorize the taker into a defined segment with a specific recommendation matched to that segment. The taker comes away knowing what to do next, not just what they are. The brand becomes the source of the recommendation the audience acted on. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the quiz-specific methodology (scoring algorithms, result categorization, recommendation matching) lives here. + +The voice is the senior growth practitioner who has watched quizzes earn long-term subscribers and watched them produce engagement metrics with no downstream impact. Practical, opinionated about the difference between fun-quiz and decision-quiz, willing to call out when a quiz is the wrong format for the goal. + +When to use this skill: scoping a quiz or assessment for the first time, auditing a quiz that produces engagement but no qualified leads, designing the result categories that drive specific recommendations, or deciding which inputs warrant the lead-capture step. + +--- + +## What this skill covers + +This skill spans quiz and assessment design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology. Quizzes are one specific lead-magnet type. +- `calculator-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `quiz-and-assessment-design` (this skill) is quiz-specific methodology (question architecture, scoring algorithms, result categorization, recommendation matching). +- `discovery-research-synthesis` is customer-research synthesis (this skill is user-facing assessment, not internal research). +- `landing-page-copy` is the quiz landing page (downstream of quiz design). + +The audience: growth marketers, product marketers, content marketers, agencies running quiz-based growth tooling for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); calculator design (covered by `calculator-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the quiz (handed off via `pm-spec-writing`). + +--- + +## The quiz/assessment decision: when this format earns investment + +Before designing the quiz, decide whether a quiz is the right tool for the audience and the goal. + +Quizzes earn investment when: + +- The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. +- The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation; 30 questions stops being a quiz and becomes a survey. +- The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation does not justify the format; the segment-recommendation mapping is the value. +- The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage; audiences who do not (technical buyers, enterprise) often see quizzes as gimmicks. + +Quizzes do NOT earn investment when: + +- The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. +- The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. +- The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. +- The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional; the format choice has to fit the audience. + +The decision is not "should we have a quiz"; it is "is the quiz the right next investment for this specific audience and decision." + +Detail in [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md). + +--- + +## Clickbait-quiz vs vanity-result vs actionable-segmentation + +The keystone framing. + +Clickbait-quiz. "What kind of pizza are you?" energy. Generates engagement (shares, comments, brief virality), segments nothing useful. Fun but not strategic. Cost: the engagement metric looks fine; the leads have no qualification signal because the quiz did not reveal anything actionable about them. + +Vanity-result. Elaborate-feeling result that flatters the taker but does not drive any specific next step. "You are an INTJ visionary entrepreneur" with a description that reads like horoscope, no actionable follow-up. Cost: the taker enjoyed the result, did not act on it, did not return. The quiz produced a moment of attention, not a relationship. + +Actionable-segmentation. Result places the taker into a defined category with a specific recommendation matched to that category. The result tells them what to DO next, not just what they ARE. The category and the recommendation are the value; the taker comes away with a next step. + +The litmus test. After taking the quiz, can a stranger in the target audience name the next thing they should do? Can they describe the recommendation matched to their result? If yes, the quiz is actionable-segmentation. If they got a flattering description with no clear next step, the quiz is vanity-result. If they got entertainment with no segmentation, the quiz is clickbait. + +--- + +## Question architecture + +The questions are the mechanism that produces the segmentation. Bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +Question count. Most effective quizzes use 5-10 questions. Fewer than 5 rarely produces meaningful segmentation; more than 12 stops feeling like a quiz and starts feeling like an interrogation. + +Question types. + +- Multiple-choice (single-select). The most common. Each option maps to a segment or scoring weight. +- Multiple-select. Useful when multiple attributes apply. Care needed; multi-select complicates scoring. +- Slider or scale. "On a scale of 1-5, how often do you..." Useful for intensity questions; less useful for categorical segmentation. +- Yes/no. Useful for binary qualifying questions; rarely produces nuanced segmentation alone. +- Free text. Avoid in quizzes. Free text breaks the scoring flow and adds friction. + +Question ordering. Start with engaging, low-friction questions. Save more revealing or sensitive questions for later when commitment has built. Demographic or qualifying questions belong at the end, not the start. + +Question phrasing. + +- Plain language. Avoid jargon. +- Specific situations the audience recognizes. +- Avoid leading questions ("How much do you struggle with X" presumes struggle). +- Avoid double-barreled questions ("How much do you value speed AND simplicity" mixes two dimensions). + +Question-segment mapping. Each question should contribute to the segmentation in a defined way. Questions that do not affect the result are filler; remove them. + +Detail in [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md). + +--- + +## Scoring algorithms + +The math that turns answers into a segment. + +Pattern A: Direct mapping. Each answer corresponds directly to a segment. The dominant answer choice determines the result. Simple, transparent, easy to explain. + +Pattern B: Weighted scoring. Each answer adds points to one or more segments. The highest-scoring segment wins. Allows for nuance; one answer can contribute to multiple segments. + +Pattern C: Multi-dimensional. The quiz produces scores across multiple axes (e.g., introvert/extrovert AND analytical/intuitive). The result combines the scores into a 2D or 3D segment. Common in personality assessments. + +Pattern D: Branching logic. The next question depends on the previous answer. Allows for adaptive questioning; complicates scoring. + +Choice criteria. + +- Direct mapping when the segments are well-defined and the questions clearly distinguish them. +- Weighted scoring when nuance matters and most answers contribute to multiple segments. +- Multi-dimensional when the segmentation is genuinely multi-axis (personality, fit-evaluation). +- Branching when later questions make sense only in the context of earlier answers. + +Scoring transparency. Some quizzes show the score during or after the quiz; others present only the segment. The choice depends on whether the score is meaningful to the user. Personality assessments benefit from showing dimensions; recommendation quizzes often do not. + +Detail in [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md). + +--- + +## Result categorization + +How many segments, named how, distinguishable from each other. + +Segment count. Most quizzes work well with 4-8 result categories. Fewer than 4 makes the categorization feel coarse; more than 8 makes individual segments feel under-developed. + +Segment naming. + +- Memorable. The taker should be able to describe their segment to a friend. +- Specific. "The Strategic Planner" beats "Type 3." +- Honest. Names should not flatter universally; some segments are more flattering than others, which is honest segmentation. +- Brand-voice consistent. The names should sound like the brand the quiz represents. + +Segment distinguishability. Each segment should be meaningfully different. If two segments have similar descriptions and similar recommendations, the segmentation is fake. + +Segment balance. The quiz should not always route 80 percent of takers to one segment. Balanced segmentation (each segment receives a meaningful share of takers) signals that the questions actually distinguish. + +Detail in [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md). + +--- + +## Result-to-recommendation mapping + +The action attached to each category. This is where the quiz earns its conversion. + +The principle. Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +Mapping examples. + +- B2B SaaS quiz: "Which CRM tier fits your team" maps each segment to a recommended plan. +- Content quiz: "What kind of marketer are you" maps each segment to a different content series matched to that maturity level. +- Onboarding quiz: "What is your readiness for X" maps each segment to a different onboarding path or resource. + +The recommendation has to be real. The brand should actually offer the recommended next step; the recommendation should match the segment specifically; the recommendation should be valuable to the segment. + +Mapping discipline. + +- Each segment has a distinct recommendation. No two segments share the same next step. +- Each recommendation is actionable. The taker can act on it without additional research. +- Each recommendation is valuable to that specific segment. Generic recommendations for one segment do not earn the segmentation. +- The recommendation is delivered in context of the result. Not buried 3 emails later. + +The vanity-result failure. Result describes the segment without a recommendation. "You are a Strategic Planner" with a description but no next step. The taker enjoys the segment, does nothing. + +The actionable-segmentation win. Result describes the segment, then says: "Strategic Planners benefit most from [specific resource or product or path]. Here is the next step." The taker has a specific action. + +Detail in [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md). + +--- + +## Lead capture integration + +When and where to ask for the email, with what value-add. + +The principle. Capture the email in exchange for the personalized result delivery, not in exchange for seeing the result at all. + +Pattern A: Email after questions, before result. "Enter your email to see your personalized result." Common; works when the perceived value of the result is high. Risk: lead-trap pattern if the result was already calculated and is being held hostage. + +Pattern B: Email after result, for personalized delivery. "See your result here. Want a PDF with personalized recommendations matched to your segment? Enter your email." Honest; the result is free, the additional value justifies the email. + +Pattern C: Email integrated with optional features. "See your result. Save this scenario, get notified when new content for your segment is available, or download a personalized resource." Gradual opt-in; less aggressive. + +The value-add at lead capture. What the user gets for their email matters. A personalized PDF report, a follow-up email series matched to their segment, a curated resource list specific to their result. Generic delivery (just sending the same result by email) does not justify the gate. + +Conversion vs lead quality. Pattern A converts higher; Pattern B and C produce higher lead quality. Pattern choice depends on what the program optimizes for. + +Detail in [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md). + +--- + +## Quiz anti-patterns + +Patterns that look like quizzes but degrade trust. + +The clickbait-quiz. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you" with 4 personality types and no recommendations. + +The vanity-result quiz. Flattering descriptions for every segment; no honest segmentation; no specific recommendations. + +The forced-result quiz. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The interrogation-quiz. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The leading-question quiz. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The black-box quiz. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The no-recommendation quiz. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The mismatched-recommendation quiz. Recommendation does not match the segment. Audience that catches the mismatch loses trust. + +Detail in [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-quiz-failures.md`](references/common-quiz-failures.md). + +- "Quiz gets shared widely; lead quality is poor." Clickbait pattern; the audience taking and sharing is not the audience the brand serves. +- "Engagement is high; downstream conversion is near zero." Vanity-result pattern; takers enjoyed the segment but had no next step. +- "Most takers route to the same segment." Question architecture not distinguishing; algorithm needs review. +- "Drop-off mid-quiz is high." Too many questions; or questions feel uncomfortable; or the value of finishing is not clear. +- "Segments feel similar." Distinguishability problem; segments need more divergent descriptions and recommendations. +- "Recommendations feel generic." Mapping problem; each segment needs a specific recommendation, not a default. +- "We cannot tell which segment converts best downstream." Attribution missing; segments need tracking through the funnel. +- "Audience comments that the result was wrong." Either question or scoring problem; the segments do not match audience self-perception. + +--- + +## The framework: 12 considerations for quiz and assessment design + +When designing or auditing a quiz, walk these 12 considerations. + +1. The quiz decision. Is a quiz the right format for this audience and decision, or would a comparison table or assessment-as-content serve better? +2. Actionable-segmentation, not clickbait or vanity. The result places the taker into a category with a specific recommendation. +3. Question architecture sound. 5-12 questions; each contributes to segmentation; phrased plainly without leading. +4. Scoring algorithm fits the segmentation. Direct mapping, weighted scoring, multi-dimensional, or branching as appropriate. +5. Result categories distinguishable and balanced. 4-8 segments; each meaningfully different; each receives a meaningful share of takers. +6. Segment naming memorable and brand-consistent. Names the taker can describe to a friend. +7. Recommendations specific to each segment. No two segments share the same recommendation; each recommendation is valuable to that segment. +8. Lead capture honest. Email exchange for personalized delivery, not for seeing the result. +9. Result delivery in context. Recommendation appears with the result, not buried 3 emails later. +10. Drop-off measured. Question-by-question drop-off tracked; questions that lose audience flagged for review. +11. Lead quality measured by segment. Downstream conversion tracked per segment; some segments may be more valuable than others. +12. Audit cadence. Periodic review of segment balance, recommendation alignment, and conversion-by-segment. + +The output of the framework is a quiz that segments the audience meaningfully, produces specific recommendations, and converts the segments into action. + +--- + +## Reference files + +- [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md) - When a quiz is the right tool for the audience and goal, and when a comparison table or other format would serve. +- [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md) - Question count, types, ordering, phrasing, and segment mapping discipline. +- [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md) - Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. +- [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md) - Segment count, naming, distinguishability, balance. +- [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md) - The action attached to each category. Mapping discipline and worked examples. +- [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md) - When and where to ask for the email. Pattern choices and tradeoffs. +- [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md) - The patterns that look like quizzes but degrade trust. +- [`references/clickbait-vs-actionable-distinctions.md`](references/clickbait-vs-actionable-distinctions.md) - Detailed treatment of the keystone framing with worked examples and counter-examples. +- [`references/common-quiz-failures.md`](references/common-quiz-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: quizzes earn engagement when they earn the next step + +The quizzes that work as compounding assets are the ones the audience acts on. Not shares. Not engagement metrics. Action. The taker runs the quiz, gets a segment with a matched recommendation, and does the recommendation. + +That is the bar. Below the bar are clickbait-quizzes (engagement without action) and vanity-results (flattery without action). Above the bar are actionable-segmentation tools that produce specific next steps the taker actually takes. + +The discipline is in the design choices. The questions that genuinely distinguish segments. The scoring algorithm that maps answers to meaningful categories. The recommendations that match each segment specifically. The result-delivery that surfaces the recommendation in context, not 3 emails later. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md new file mode 100644 index 0000000..43f8d87 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md @@ -0,0 +1,192 @@ +# Clickbait vs actionable distinctions + +Detailed treatment of the keystone framing with worked examples and counter-examples. The single distinction that separates quizzes that compound credibility from quizzes that produce engagement without action. + +--- + +## The three-state framing + +Three states a quiz can land in. Only one of them produces compounding value. + +State 1: Clickbait. The quiz exists primarily to generate engagement. "What kind of pizza are you?" energy. The result is fun but means nothing. No segmentation that maps to a decision. No recommendation. Engagement metrics look healthy; downstream metrics are zero. + +State 2: Vanity-result. The quiz produces a result that feels meaningful but does not drive action. "You are an INTJ visionary entrepreneur." The taker reads the description, may share it, does not act on it. The result is descriptive without being prescriptive. + +State 3: Actionable-segmentation. The quiz produces a result that includes a specific recommendation matched to that segment. The taker can act immediately on the recommendation. The result is both descriptive (this is who you are) and prescriptive (this is what to do next). + +The states are not always obvious from the outside. A quiz can look polished and still be vanity-result; a quiz can look simple and still be actionable-segmentation. The distinction is in the design, not the surface. + +--- + +## What separates the states + +The three differences that separate actionable-segmentation from the others. + +Difference 1: The result includes a recommendation. + +- Clickbait: result is a label or description. "You are a 'Strategic Visionary'." +- Vanity: result is an elaborate description. "You are a 'Strategic Visionary': big-picture thinker, comfortable with ambiguity, drawn to long-term impact..." +- Actionable: result is a description plus a recommendation. "You are a 'Strategic Visionary'. The next step that fits this profile: [specific resource, product, or path]." + +Difference 2: The recommendation is specific to the segment. + +- Clickbait: no recommendation, so the question does not apply. +- Vanity: every segment may get a similar generic next step ("read our blog"); the recommendation is decorative. +- Actionable: each segment gets a distinct recommendation matched to that segment specifically. + +Difference 3: The recommendation is actionable today. + +- Clickbait: no recommendation. +- Vanity: recommendation is aspirational ("consider whether you might be ready for X someday"). +- Actionable: recommendation is concrete and immediate ("start your trial here," "book a 30-minute call here," "download the playbook here"). + +The pattern. Clickbait has no recommendation. Vanity has decorative recommendation. Actionable has specific, matched, concrete recommendation. + +--- + +## Worked example: the same topic in three states + +A quiz on "what kind of marketer are you" treated three ways. + +Clickbait version. + +- 5 questions about content preferences and personality. +- Result: "You are 'The Storyteller'." Description: "Storytellers love narrative and connect deeply with their audience." +- Action: share the result. + +The taker enjoys the result, may share it, learns nothing actionable. The quiz produces engagement; the brand earns no qualified leads. + +Vanity-result version. + +- 8 questions about marketing approach, content, audience interaction. +- Result: "You are 'The Storyteller': a marketer who values narrative, audience connection, and emotional resonance. Storytellers thrive in brands that prioritize voice and depth..." +- Action: 3 paragraphs of description; soft CTA at the bottom: "Want more? Subscribe to our newsletter." + +The taker reads the elaborate description; may subscribe to the newsletter; does not take a specific action that converts. The quiz produces a moment of attention; the brand earns subscribers but no qualified leads. + +Actionable-segmentation version. + +- 7 questions about marketing approach, content, audience interaction, current tools, current challenges. +- Result: "You are 'The Storyteller'. Storytellers benefit most from our 4-part 'Brand Voice Workshop' series. Here is the first lesson; the next 3 arrive over the following week. Or, if you prefer, start with our 'Brand Voice Audit Template' [direct download]." +- Action: clear next step with two options matched to the segment's likely preference (sequence or self-serve). + +The taker gets a matched recommendation. The taker who wants the sequence opts in; the taker who wants the template downloads. Either way, action is taken; the brand earns a qualified lead. + +The same topic, three quizzes, three different outcomes. The actionable version compounds value; the others do not. + +--- + +## How to evaluate which state a quiz is in + +Diagnostic questions to apply to any quiz. + +Question 1: Does the result include a specific recommendation? + +- No: the quiz is clickbait or vanity. +- Yes: continue. + +Question 2: Does each segment have a distinct recommendation, or do all segments share the same recommendation? + +- All same: the quiz is forced-result; segmentation is decorative. +- Distinct: continue. + +Question 3: Is the recommendation actionable today? + +- No (aspirational, vague, "consider"): the quiz is vanity. +- Yes (specific link, button, or action): the quiz is actionable-segmentation. + +Question 4: Does the recommendation match the segment specifically (not a generic offer)? + +- No: the quiz is vanity with decorative recommendations. +- Yes: the quiz is actionable-segmentation. + +When all four questions get the right answer, the quiz is actionable-segmentation. When any fails, the quiz is somewhere between clickbait and vanity. + +--- + +## The compounding-value mechanism + +Why actionable-segmentation compounds and the others do not. + +Actionable-segmentation compounds. + +- The taker acts on the recommendation; the brand becomes the source of the action. +- The taker sees results from the action; the brand earns credit. +- The taker returns or refers; the brand's reach grows. +- The brand's recommendations become trusted; future quizzes earn more conversion. + +Clickbait does not compound. + +- The taker engages; the engagement does not convert. +- The brand's quiz is one of many forgotten amusements. +- No relationship deepens; no credibility builds. + +Vanity does not compound. + +- The taker enjoys; the enjoyment does not convert. +- The brand's quiz is one of many flattering distractions. +- The newsletter subscription (if any) decays without engagement. + +The compounding effect is the difference between quizzes that earn ongoing investment and quizzes that get retired. + +--- + +## Why teams build clickbait and vanity quizzes + +The patterns are easy to ship. Understanding why teams default to them helps teams choose actionable-segmentation instead. + +Reason 1: Engagement metrics are easier to measure. Conversion rate to email, share counts, time on page are all available immediately. Downstream conversion takes weeks or months to measure. Teams optimize what they measure. + +Reason 2: Designing recommendations is hard. Each segment needs a matched recommendation; the brand has to have the recommendations to give. Designing the segment-recommendation mapping is more work than designing the quiz alone. + +Reason 3: Templates default to clickbait. Many quiz-platform templates are designed for engagement, not for segmentation-driven action. Using a template often produces clickbait by default. + +Reason 4: The vanity-result feels safer. Flattering descriptions feel safer than honest segmentation; teams worry about "telling someone they are not a fit." Honest segmentation is harder but produces more trust. + +Reason 5: Short-term thinking. Engagement is immediate; downstream conversion is delayed. Teams optimizing for the next quarter default to engagement. + +The cure. Track downstream conversion as the primary metric. Build the recommendation portfolio before designing the quiz. Avoid templates that default to engagement. Practice honest segmentation. + +--- + +## Counter-example: when engagement is the goal + +Some quizzes are intentionally engagement-driven, and that is fine. + +The legitimate engagement-quiz. A consumer brand running a viral quiz to drive social shares and brand awareness. The goal is reach, not lead-capture. The quiz is intentionally entertainment. + +The pattern. Light, fun, shareable. No email gate. Result is shareable. Brand association is the value. + +Why this is fine. The brand has chosen reach as the metric. The quiz delivers on that goal. The quiz is not pretending to be something it is not. + +The discipline. Be honest about the goal. If the goal is engagement, do not pretend the quiz is for lead-capture; do not include a half-hearted email gate that produces neither real engagement nor real leads. + +The clickbait pattern fails when teams pretend it is something else. When teams own the engagement goal and design for it explicitly, the quiz can serve that goal well. + +--- + +## Common patterns by industry + +How clickbait, vanity, and actionable-segmentation play differently across industries. + +Consumer brands. Consumer brands often run engagement-quizzes successfully when the brand-association goal is the value. Lead-capture quizzes are harder; consumer audiences resist email gates more. + +B2B SaaS. B2B SaaS audiences expect actionable-segmentation. Clickbait and vanity are read as unprofessional. Actionable quizzes that route to specific plans or resources work well. + +Education and creators. Mixed. Some audiences engage with personality-style quizzes; some want practical assessment. The audience the brand serves determines which works. + +Enterprise. Enterprise audiences usually skip quizzes entirely. When they engage, only actionable-segmentation works; clickbait or vanity is read as unserious. + +Ecommerce. Recommendation quizzes ("which of our products fits you") work well as actionable-segmentation when the product portfolio supports it. + +The discipline. Match the quiz pattern to the audience expectation. Audiences that expect actionable-segmentation will reject anything else; audiences that engage with personality quizzes will not be converted by overly-formal segmentation. + +--- + +## Methodology-level choices that stay in the public skill + +The three-state framing. The three differences that separate actionable-segmentation from clickbait and vanity. The diagnostic questions. The compounding-value mechanism. Why teams default to clickbait and vanity. The counter-example for legitimate engagement-quizzes. Industry patterns. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. Specific recommendation portfolios. Specific tracking for downstream conversion per pattern. The team's measurement framework for engagement vs action. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md new file mode 100644 index 0000000..a350ba8 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/common-quiz-failures.md @@ -0,0 +1,187 @@ +# Common quiz failures + +8+ failure patterns with diagnoses and cures. The patterns that surface as "the quiz did not produce qualified leads" or "engagement is high but nothing converts" or "we cannot tell if the quiz worked." + +--- + +## "Quiz gets shared widely; lead quality is poor." + +The diagnosis. Clickbait pattern. The audience taking and sharing is not the audience the brand serves; the quiz attracts engagement from a broader audience than the brand's target. + +The cure. Tighten the quiz's audience-fit. Specific titles, specific topics, specific recommendations matched to the brand's actual buyers. Detail in `references/quiz-investment-criteria.md` (recommendation-portfolio precondition) and `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Engagement is high; downstream conversion is near zero." + +The diagnosis. Vanity-result pattern. Takers enjoyed the segment but had no next step. The quiz produced moments of attention without action. + +The cure. Add specific recommendations to each segment. Detail in `references/result-to-recommendation-mapping.md`. Each result page must include a clear next step. + +--- + +## "Most takers route to the same segment." + +The diagnosis. Question architecture not distinguishing. Either the questions do not actually capture differentiating signals, or the scoring algorithm biases toward one segment. + +The cure. Audit the question-segment mapping (`references/question-architecture-patterns.md`). Ensure each question contributes meaningfully to multiple segments. Audit the scoring weights for unintended bias. + +--- + +## "Drop-off mid-quiz is high." + +The diagnosis. Too many questions, or questions feel uncomfortable, or the value of finishing is not clear. + +The cure. Reduce question count if over 12. Audit questions for those that feel sensitive or repetitive. Add a progress indicator and a teaser of the result ("almost done; see your result next") to reduce late-stage drop-off. + +--- + +## "Segments feel similar." + +The diagnosis. Distinguishability problem. Either over-segmentation (more segments than the questions can support) or weak descriptions that do not differentiate. + +The cure. Reduce segment count to what the questions can distinguish (`references/result-categorization-patterns.md`). Strengthen the descriptions to make each segment meaningfully different. + +--- + +## "Recommendations feel generic." + +The diagnosis. Mapping problem. Each segment needs a specific recommendation, not a default. + +The cure. Audit the segment-to-recommendation mapping (`references/result-to-recommendation-mapping.md`). Verify each segment has a distinct, valuable, actionable recommendation. + +--- + +## "We cannot tell which segment converts best downstream." + +The diagnosis. Attribution missing. Segments need tracking through the funnel. + +The cure. Tag leads by segment at capture. Track downstream conversion per segment. The data informs which segments warrant continued investment and which segments may need different recommendations. + +--- + +## "Audience comments that the result was wrong." + +The diagnosis. Either question or scoring problem. The segments do not match audience self-perception. + +The cure. Persona testing. Have personas representing each segment take the quiz; verify each persona reaches the intended segment. Adjust questions or scoring weights to align. + +--- + +## "The quiz earns 5000 takers; the email list grows by 200." + +The diagnosis. Either the result is not perceived as valuable enough to opt in for additional value (Pattern B failure), or the email gate is for the result itself with no value-add (lead-trap risk). + +The cure. Design a substantive value-add for the email opt-in (PDF, sequence, resource). Make the value-add visible at the result. Detail in `references/lead-capture-integration-patterns.md`. + +--- + +## "We added a quiz; our other lead magnets stopped converting." + +The diagnosis. Cannibalization. The quiz absorbed the audience that previously converted via other magnets. + +The cure. This may not be a failure. If the quiz-sourced leads are higher quality than the previous magnets, the cannibalization is portfolio improvement. If not, the quiz may have replaced a working magnet with a worse one; audit and decide. + +--- + +## "Sales says quiz-sourced leads are low-fit." + +The diagnosis. Either the audience-fit at the quiz is wrong (the quiz attracts non-target audiences) or the recommendation-mapping routes audiences to wrong products. + +The cure. First, audit the audience-fit. If the quiz is attracting the wrong audience, tighten the targeting (title, topic, distribution channels). Second, audit the recommendation-mapping. If the audience-fit is right but the recommendation is wrong, fix the mapping. + +--- + +## "The quiz looks great; nobody completes it." + +The diagnosis. Either the topic does not engage the audience (audience-fit weak) or the question count is too high (drop-off too early). + +The cure. First, validate the topic with audience research. If the topic is right, audit the question count and question phrasing. + +--- + +## "Engagement was great at launch; conversion has dropped 40 percent over a year." + +The diagnosis. Decay. Recommendations have shifted; segments have evolved; references are stale. + +The cure. Audit and refresh. Update recommendations to match current portfolio; verify segments still describe the audience accurately; refresh any stale references in question phrasing or result descriptions. + +--- + +## "We made the quiz shorter; conversion went up but downstream conversion went down." + +The diagnosis. Question removal removed differentiating signals. The quiz now produces engagement faster but the segmentation is weaker. + +The cure. Restore the questions that contributed to segmentation. Speed-of-completion is a metric; segmentation quality is a separate metric. Optimize for the right one. + +--- + +## "The result page is fine; the email follow-up sequence converts terribly." + +The diagnosis. Sequence does not match the segment. Either the sequence is generic across segments, or the sequence does not deepen the matched recommendation. + +The cure. Design segment-specific sequences (or at least segment-specific opening emails). The sequence should extend the result's recommendation, not start over with generic content. + +--- + +## "We tried branching logic; the quiz felt confusing." + +The diagnosis. Branching added complexity without value. Different takers got different question sets; comparison across takers became hard. + +The cure. Revert to linear quiz unless branching is genuinely warranted. The simplicity often produces better outcomes. + +--- + +## "The quiz works on Chrome; it breaks on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The quiz was tested on the team's primary platform; the audience's actual devices were not covered. + +The cure. Cross-browser, cross-device testing. The audience uses what they use; the quiz has to work there. + +--- + +## "The recommendation links to a product we discontinued." + +The diagnosis. Maintenance lapse. The quiz's recommendation drifted out of sync with the brand's actual offering. + +The cure. Set a maintenance trigger: when products are discontinued or pricing changes, the quiz updates are part of the change. Quarterly review at minimum. + +--- + +## "Audiences take the quiz multiple times to get different results." + +The diagnosis. This is fine, often. Audiences exploring the segmentation may take it multiple times to understand how the algorithm works. Track unique users vs total completions. + +The action. Make sure the algorithm is stable enough that repeated takes with consistent answers produce consistent results. Inconsistency at this level signals algorithm issues. + +--- + +## "The quiz produces good leads; the sales team does not follow up." + +The diagnosis. Sequence or routing missing. Quiz-sourced leads should be tagged, routed to sales, and prioritized appropriately. + +The cure. Design the post-conversion flow. Calculator-sourced leads should be tagged with their segment, routed to the appropriate sales rep, and the sales rep should know which segment the lead represents. + +--- + +## The pattern across failures + +Most quiz failures fall into one of three patterns. + +Pattern 1: The quiz does not deliver actionable segmentation. Clickbait, vanity-result, no-recommendation, mismatched-recommendation. The fix is to add or correct the recommendations. + +Pattern 2: The quiz does not match the audience. Audience-fit weak, topic-audience mismatch, format-audience mismatch (e.g., quizzes for enterprise audiences who reject the format). The fix is to align the quiz to the audience the brand serves. + +Pattern 3: The quiz decays. Recommendations point to retired products; segments no longer describe the audience; references are stale. The fix is maintenance discipline. + +The metric pattern: quiz failures often look fine on engagement metrics. The signal is in lead quality, downstream conversion, and audience self-recognition. Programs that track only engagement keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that engagement alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md new file mode 100644 index 0000000..d10544c --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md @@ -0,0 +1,240 @@ +# Lead capture integration patterns + +When and where to ask for the email. Pattern choices and tradeoffs. The decision that affects both conversion and lead quality. + +The lead-capture integration is where the quiz earns its email. Done well, the audience opts in for personalized value; done poorly, the quiz becomes a lead-trap that the audience resents. + +--- + +## The capture-honest principle + +Capture the email in exchange for personalized result delivery, not in exchange for seeing the result at all. + +The honest pattern. The taker completes the quiz; the result is shown; an offer is made for additional value (PDF, follow-up sequence, saved scenario) that requires the email. + +The dishonest pattern. The taker completes the quiz; the result is calculated but hidden; the email is required to reveal it. This is the lead-trap pattern (described in `calculator-design`'s email-capture-decision-tree but applies equally to quizzes). + +--- + +## Pattern A: Email after questions, before result + +The taker completes the quiz; before the result is shown, an email gate appears. + +How it works. + +- The taker answers all questions. +- A form appears: "Enter your email to see your personalized result." +- The taker enters email; the result is shown. + +Strengths. + +- Highest conversion to email opt-in. +- Common pattern; audiences are familiar. + +Weaknesses. + +- Lead-trap pattern. The audience that recognizes the manipulation feels resentment. +- Lead quality is lower; some takers enter throwaway emails. +- Downstream conversion suffers because some leads are unqualified or actively annoyed. + +When to use. When the quiz is genuinely entertainment-driven and the audience expects the format (consumer brands sometimes work here). For B2B and considered purchases, this pattern often degrades trust. + +--- + +## Pattern B: Email after result, for personalized delivery + +The result is shown; an offer is made for personalized PDF or follow-up. + +How it works. + +- The taker answers all questions. +- The result is shown immediately, including segment description and matched recommendation. +- Below or alongside the result, an offer: "Want this as a PDF you can share?" or "Want a personalized 5-day sequence with deeper resources for your segment?" +- The taker who wants the additional value enters email. + +Strengths. + +- Honest. The audience gets what they came for. +- Lead quality is higher; takers who opt in are signaling real interest. +- Trust is preserved; audience that does not opt in still leaves with positive brand association. + +Weaknesses. + +- Lower conversion rate to email than Pattern A. +- Requires designing additional value (PDF, sequence) that justifies the email. + +When to use. Default pattern for B2B and considered purchases. The honest exchange compounds trust over time. + +--- + +## Pattern C: Email integrated with optional features + +The result is shown; multiple optional opt-ins are offered. + +How it works. + +- The taker answers all questions. +- The result is shown. +- Multiple opt-in options appear, each with distinct value: "Save this scenario for later," "Get notified when new content for your segment is available," "Download a personalized resource." +- The taker chooses which (if any) to opt into. + +Strengths. + +- Most flexibility for the audience. +- Allows different audience segments to engage at different levels. +- Lead quality is high because each opt-in is for specific value. + +Weaknesses. + +- More complex to design and implement. +- Multiple options can dilute conversion ("paradox of choice"). +- Requires the brand to actually deliver on each opt-in. + +When to use. When the quiz has multiple legitimate value-add follow-ups and the audience benefits from choice. + +--- + +## Pattern D: Progressive opt-in across the quiz + +Email is captured early but only used after the quiz completes. + +How it works. + +- The quiz starts with optional email entry ("get a personalized PDF report when you finish"). +- Takers can enter email upfront or skip. +- The quiz proceeds; the result is shown for everyone. +- Takers who entered email get the PDF; others see the result and an opt-in offer. + +Strengths. + +- Captures highly committed takers early. +- Does not gate the result. +- Provides a soft opt-in path for less-committed takers. + +Weaknesses. + +- Asking for email upfront can depress quiz starts. +- Two-path design (email-given vs not-given) adds complexity. + +When to use. When the audience benefits from setting expectations upfront and when the brand can deliver value differently to opted-in vs walk-up takers. + +--- + +## The value-add at lead capture + +What the user gets for their email matters as much as when the email is asked. + +Strong value-adds. + +- A personalized PDF report matched to the segment. +- A follow-up email series that deepens the segment-matched content. +- A curated resource list specific to the result. +- Notifications about new resources, products, or events relevant to the segment. + +Weak value-adds. + +- Just sending the same result by email (no value-add over what is on screen). +- A generic newsletter signup (not personalized to the result). +- A "join our community" offer with no clear value. + +The discipline. The value-add should be substantively better than what the audience saw on screen. If it is not, the email gate is not justified. + +--- + +## Conversion vs lead quality + +The patterns trade off these two metrics. + +Conversion-optimized. Pattern A captures the most emails but produces lower lead quality. Suitable when the goal is volume or when the audience is highly aligned (every taker is a target lead). + +Quality-optimized. Pattern B and C capture fewer emails but produce higher lead quality. Suitable when the goal is downstream conversion or when the audience is mixed (only some takers are target leads). + +The choice. Depends on what the program optimizes for. Brands optimizing for downstream revenue often choose Pattern B or C. Brands optimizing for list growth may default to Pattern A. + +The trap. Optimizing for conversion at the expense of lead quality is short-term thinking. The conversion metric looks fine; the downstream metrics suffer; the program quietly underperforms. + +--- + +## The "no email needed" alternative + +Some quizzes do not capture email at all. + +When this works. When the quiz's purpose is brand-building, SEO, or audience-engagement rather than lead-capture. The quiz's existence and shareability are the value; the email is incidental. + +The pattern. The taker takes the quiz; the result is shown; share buttons are prominent; no email gate. + +Why it can work. Some brands earn more from a widely-shared quiz than from a gated quiz that captures fewer emails. The brand association is the value. + +When it fails. When the program needs leads and the no-gate design produces nothing for the funnel. + +--- + +## Lead-capture form design + +The form itself matters. + +Field count. Email only is the strong default. Each additional field reduces conversion. + +Field justification. If additional fields are required (name for personalization, company for B2B sales context), justify them inline. "We use your name to personalize your follow-up" is honest; uncontextualized fields feel like sales-form padding. + +Form placement. Inline with the result is honest; popup that interrupts the result viewing is hostile. + +CTA copy. "Get my personalized PDF" beats "Submit." Specific value statement beats generic action. + +Loading state. After submission, show progress and confirm receipt. "Sending your PDF now... check your inbox in 2 minutes." + +--- + +## Post-capture experience + +What happens after the email is captured. + +Immediate delivery. The promised PDF, sequence, or resource arrives within minutes. Delays break trust. + +Confirmation message. On the result page or in the email, confirm what was sent and what to expect next. + +Sequence integration. If a follow-up sequence was offered, the first email arrives within 24 hours. The sequence delivers the promised cadence. + +Opt-out clarity. Easy unsubscribe from the start. Audiences that find unsubscribe friction lose trust permanently. + +--- + +## Capture-pattern testing + +Test pattern choice with real metrics. + +Test design. A/B test Pattern A vs Pattern B with the same quiz. Measure both conversion to email and downstream conversion (trial signup, demo request, purchase). + +The metric that matters. Downstream conversion per visitor, not conversion to email. A pattern that captures fewer emails but produces more downstream conversion is the better pattern. + +Test duration. Long enough to capture downstream signal (often 30-60 days minimum, depending on consideration cycle). + +--- + +## Common capture failures + +Lead-trap pattern. Result hidden behind email; downstream conversion drops; trust degrades. + +Email gate without value. Email required for the same content; gate is not justified; conversion drops. + +Too many fields. Form asks for name, company, role, phone in addition to email; conversion plummets. + +Generic CTA copy. "Submit" rather than "Get my personalized PDF"; conversion suffers. + +Popup that interrupts. Result loads; popup appears; user's flow breaks. + +Slow delivery. PDF arrives 30 minutes later; trust drops. + +No confirmation. User submits, sees no acknowledgment, wonders if it worked. + +Hard unsubscribe. Multi-step or hidden unsubscribe; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The capture-honest principle. Pattern A through D with strengths, weaknesses, and when-to-use guidance. The value-add at lead capture. The conversion-vs-quality tradeoff. The no-email-needed alternative. Lead-capture form design. Post-capture experience. Capture-pattern testing. Common failures. + +## Implementation choices that stay internal + +Specific capture pattern choices for specific quizzes. Specific PDF templates and sequence designs. Specific form copy and CTAs in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md new file mode 100644 index 0000000..8fca5ba --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/question-architecture-patterns.md @@ -0,0 +1,212 @@ +# Question architecture patterns + +Question count, types, ordering, phrasing, and segment mapping discipline. The questions are the mechanism that produces the segmentation; bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +--- + +## Question count + +Most effective quizzes use 5-10 questions. + +Fewer than 5 questions. Rarely produces meaningful segmentation. The taker reaches the result quickly, but the result feels arbitrary because too few signals were captured. Useful only for very simple categorizations (binary or 3-segment outcomes). + +5-7 questions. The sweet spot for most quizzes. Enough to produce nuanced segmentation; few enough that the audience completes without fatigue. + +8-12 questions. Acceptable when the segmentation is genuinely multi-dimensional or when the audience has high commitment. Watch drop-off carefully; the last few questions are where audiences abandon. + +13+ questions. Stops feeling like a quiz; starts feeling like a survey. Drop-off rises sharply. If the segmentation truly needs this many questions, consider whether quiz is the right format. + +--- + +## Question types + +Choose the type that fits the variable being captured. + +Multiple-choice (single-select). The most common quiz question type. Each option maps to a segment or scoring weight. + +When to use: when the answer space is well-defined and mutually exclusive. +When to avoid: when the audience genuinely could choose multiple answers; forcing single-select frustrates the taker. + +Multiple-select. Useful when multiple attributes apply to the taker. + +When to use: when the answer space includes overlapping options ("which features matter most" with multiple selections). +When to avoid: when scoring complexity outweighs the value; multi-select complicates segmentation. + +Slider or scale. "On a scale of 1-5, how often do you..." Useful for intensity questions. + +When to use: when the variable is continuous (frequency, importance, satisfaction). +When to avoid: when the categorization is genuinely categorical; sliders force false continuity. + +Yes/no. Useful for binary qualifying questions. + +When to use: as part of a broader question set when one binary attribute matters (does the team use a CRM today, yes or no). +When to avoid: as the primary question type; quizzes built only on yes/no questions feel coarse. + +Free text. Avoid in quizzes. Free text breaks the scoring flow and adds friction. The few quizzes that genuinely need free text often work better as forms or assessments. + +--- + +## Question ordering + +The order matters as much as the questions themselves. + +Open with engaging, low-friction questions. "What kind of role best describes you?" or "What size is your team?" These warm up the taker and build commitment. + +Mid-quiz: substantive segmentation questions. The questions that most influence the segmentation belong in the middle. The taker has invested enough to commit; you have not yet exhausted their patience. + +Late-quiz: more revealing or sensitive questions. "How effective is your current process?" or "What is your biggest challenge?" These questions benefit from the trust built earlier. + +End: qualifying questions, if needed. Demographic data, company-size confirmation, or contact-channel preferences. These belong at the end, not the start. Asking demographic questions first signals "this is a sales form" and depresses completion. + +--- + +## Question phrasing + +Plain language. No jargon. No leading. + +Plain language. Avoid technical terms the audience may not know. If the quiz is for SaaS founders, "ARR" is fine; if it is for general business owners, "annual revenue" is clearer. + +Specific situations. Frame questions around situations the audience recognizes. "When you onboard a new customer, do you..." beats "What is your customer-onboarding maturity." + +Avoid leading questions. Phrasing that pushes toward a specific answer biases the result. + +- Leading: "How much do you struggle with X?" (presumes struggle) +- Honest: "How would you describe your experience with X?" + +Avoid double-barreled questions. Questions that mix two dimensions confuse scoring. + +- Double-barreled: "How much do you value speed AND simplicity?" +- Cleaned up: split into two questions if both dimensions matter. + +Avoid "all of the above" or "none of the above" defaults. These options are escape valves that produce uninterpretable answers. + +--- + +## Question-segment mapping + +Each question should contribute to the segmentation in a defined way. + +The principle. For each question, document which answer choices map to which segments and with what weight. + +Example: "What size is your team?" + +- 1-5 employees → segment "Solo or small" (+3 to that segment) +- 6-25 employees → segment "Growing team" (+3) +- 26-100 employees → segment "Mid-market" (+3) +- 101+ employees → segment "Enterprise" (+3) + +Example: "What is your sales process maturity?" + +- "Founder-led, no defined process" → "Solo or small" (+2), "Growing team" (+1) +- "Some defined steps, owner driven" → "Growing team" (+2), "Mid-market" (+1) +- "Defined sales playbook, multiple reps" → "Mid-market" (+2), "Enterprise" (+1) +- "Multi-stage enterprise sales process" → "Enterprise" (+3) + +The mapping is explicit. Each question contributes specific weight to specific segments. The mapping should be documented so future maintenance can verify it. + +Filler questions. Questions that do not affect the segmentation are filler. They add friction without adding value. Audit and remove. + +--- + +## Question count vs segmentation depth + +The relationship between question count and segmentation accuracy. + +Few questions, broad segments. A 5-question quiz produces 4-5 segments reliably; trying to produce 10 segments from 5 questions makes each segment poorly distinguished. + +More questions, narrower segments. An 8-question quiz can produce 6-8 segments with enough distinction. + +The over-segmentation trap. Too many segments produced from too few questions creates segments that are not really different. The audience that lands in different segments gets similar recommendations; the segmentation is fake. + +The right ratio. Roughly 1.5-2 questions per segment is a useful baseline. 5-7 segments from 8-12 questions; 4-5 segments from 5-7 questions. + +--- + +## Conditional questions and branching + +Whether to ask different questions based on earlier answers. + +Branching when it helps. Later questions make sense only in the context of earlier ones. "If you have a CRM today, which one?" is a useful follow-up to "Do you use a CRM today?" + +Branching when it hurts. When branching adds complexity without value, when the branching makes the quiz feel different for different takers in confusing ways, when the scoring becomes hard to reason about. + +The simplicity preference. Linear quizzes (everyone gets the same questions in the same order) are easier to maintain, easier to test, and easier for the audience to predict. Use branching only when the value justifies the complexity. + +--- + +## Drop-off considerations + +Where audiences abandon, and why. + +The first question. Some takers click into the quiz and leave at question 1. Often the question or the format made them realize this is not for them. This is fine; honest filtering. + +Mid-quiz (questions 4-7). Drop-off here usually signals fatigue or discomfort. Audit the questions; are they too long, too sensitive, too repetitive? + +Late-quiz (final questions). Drop-off here often signals that the user got bored or the value of finishing was not clear. A progress indicator and a teaser of the result ("almost done; see your result next") can reduce late-stage drop-off. + +Question-by-question tracking. Tracking drop-off per question is the diagnostic. Questions with disproportionate drop-off warrant review. + +--- + +## Mobile question design + +Most quiz takers are on mobile. The question UX has to work there. + +Mobile-specific considerations. + +- Touch-friendly answer options (minimum 44x44 pixel touch targets). +- Single question per screen on mobile (multi-question screens cramp). +- Progress indicator visible without scroll. +- Answer options large enough to tap accurately; spacing prevents accidental taps. +- Sliders sized for thumb interaction. + +Mobile testing. Test the quiz on actual devices. Real-device behavior often differs from browser dev-tools simulation. + +--- + +## Question-mapping audit + +Periodically audit the question-segment mapping. + +The audit. For each segment, verify that the questions actually produce that segment for takers who should get it. Run the quiz with personas representing each segment; confirm each persona reaches the right result. + +The audit cadence. When the recommendation portfolio changes, when the audience composition shifts, or at least quarterly. + +Drift indicators. + +- One segment now receives 70+ percent of takers. +- Another segment receives less than 5 percent. +- Specific personas reach the wrong segment when audited. +- Audience comments that the result was wrong. + +These signals warrant question or scoring revision. + +--- + +## Common question architecture failures + +Too many questions. 15+ questions feels like a survey; drop-off climbs. + +Filler questions. Questions that do not affect segmentation; audit and remove. + +Leading questions. Phrasing that biases the answer. + +Double-barreled questions. Two dimensions in one question; scoring becomes ambiguous. + +Demographic questions first. Signals "sales form"; depresses completion. + +Vague answer options. "Sometimes" vs "often" without anchors; the taker cannot calibrate. + +Inconsistent question types. Mixing 5-point sliders with yes/no without coherent rationale; the rhythm breaks. + +Mobile-broken questions. Sliders that do not work on touch; answer options that overflow. + +--- + +## Methodology-level choices that stay in the public skill + +Question count, types, ordering, phrasing. Question-segment mapping discipline. Question count vs segmentation depth. Conditional questions and branching. Drop-off considerations. Mobile question design. Question-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific question sets for specific quizzes. Specific scoring weights and segment mappings. Specific tooling for quiz engineering and analytics. The team's drop-off benchmarks and audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md new file mode 100644 index 0000000..533a111 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md @@ -0,0 +1,223 @@ +# Quiz anti-patterns + +The patterns that look like quizzes but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The clickbait-quiz + +The pattern. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you?" with 4 personality types and no recommendations. + +The signal. Engagement metrics are high (shares, completions); downstream metrics are flat. The quiz is fun; it does not produce qualified leads or conversions. + +The cost. The build cost is wasted on entertainment that does not compound business value. The brand earns "fun but not useful" association. + +The cure. Add actionable segmentation. Each segment maps to a specific recommendation matched to that segment. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The vanity-result quiz + +The pattern. Flattering descriptions for every segment. No honest characterization. No specific recommendations. + +The signal. Takers enjoy the result; do not act on it; do not return. The quiz produces a moment of attention without a relationship. + +The cost. The audience associates the brand with horoscope-style content. The quiz does not differentiate the brand from competitors offering similar entertainment. + +The cure. Honest segmentation. Some segments are more flattering than others; honest descriptions produce respect; recommendations that match each segment specifically produce action. + +--- + +## The forced-result quiz + +The pattern. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The signal. Sales team or product team notices that quiz-sourced leads all look the same; the segmentation is not differentiating. + +The cost. The quiz misleads the audience. Takers who answered honestly believing they would get a matched recommendation get a generic one; trust degrades. + +The cure. Real segmentation that produces real different recommendations per segment. If the brand only has one recommendation, do not use a quiz format; use a clear landing page. + +--- + +## The interrogation-quiz + +The pattern. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The signal. High drop-off rate, especially at questions 8-15. Few takers reach the result. + +The cost. The build effort produces a quiz few people complete. The audience that drops off remembers the brand as the source of the long form they abandoned. + +The cure. Reduce question count. 5-12 questions is the working range. Audit questions for those that do not affect segmentation; remove them. + +--- + +## The leading-question quiz + +The pattern. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The signal. The result distribution is biased; takers report that the result felt predetermined; analytical audiences notice the leading. + +The cost. The audience that catches the leading loses trust. The result is artificially produced rather than reflecting the taker's actual situation. + +The cure. Plain phrasing without bias. "How would you describe your experience with X?" beats "How much do you struggle with X?" + +--- + +## The black-box quiz + +The pattern. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The signal. Audience comments asking how the result was calculated; some takers question whether the result is real or random. + +The cost. The quiz feels arbitrary. Even when the segmentation is real, the audience cannot verify; trust suffers. + +The cure. Some transparency about the methodology. "Your result reflects your answers to questions 2, 4, and 6" or a brief explanation of what the segments represent. + +--- + +## The no-recommendation quiz + +The pattern. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The signal. Strong engagement; near-zero downstream conversion; the quiz captures a moment without converting it. + +The cost. The brand has the audience's attention and does nothing with it. The quiz produces brand impression without business impact. + +The cure. Every result page must include a specific next step. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The mismatched-recommendation quiz + +The pattern. The recommendation does not match the segment. A taker classified as "enterprise" gets a "starter plan" recommendation, or vice versa. + +The signal. Sales team feedback that quiz-sourced leads do not match the recommended product. Audience feedback that the recommendation felt wrong. + +The cost. Trust damage. The taker who notices the mismatch feels misled; the brand earns "doesn't get me" reputation. + +The cure. Audit the segment-to-recommendation mapping. Verify each segment's recommendation actually fits. + +--- + +## The over-segmentation quiz + +The pattern. 12+ segments produced from 5 questions. Most segments end up similar; segmentation is fake. + +The signal. Segments that read the same; segments that get the same recommendation; segments that receive less than 3 percent of takers each. + +The cost. Design and copy effort wasted on segments that do not really exist. The audience that lands in similar segments cannot tell them apart. + +The cure. Reduce segment count to what the questions can actually distinguish. 4-7 segments from 5-7 questions; 6-8 segments from 8-10 questions. + +--- + +## The under-segmentation quiz + +The pattern. 2 segments that could have been a yes/no question. The quiz format is over-engineering. + +The signal. The audience completes the quiz quickly; the result feels obvious; the quiz adds friction without adding value. + +The cost. Build effort wasted on a quiz that did not need to be a quiz. The audience that recognizes the over-engineering questions the brand's judgment. + +The cure. Either expand the segmentation to justify the format or replace the quiz with a simpler tool (yes/no qualifier, comparison table). + +--- + +## The lead-trap quiz + +The pattern. The result is calculated but hidden behind an email gate. The taker enters 8 fields, hits Calculate, sees "enter your email to see your result." + +The signal. Email-form conversion is high; downstream conversion is low; audience that recognizes the pattern bounces immediately. + +The cost. Lead quality suffers. The brand earns "lead-trap" reputation. Detail in `references/lead-capture-integration-patterns.md`. + +The cure. Show the result freely; gate the additional value (PDF, follow-up sequence) instead. + +--- + +## The cookie-cutter quiz + +The pattern. The quiz looks and behaves like every other quiz from a template platform. Generic UI, generic question style, generic result format. + +The signal. The quiz does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The quiz becomes commodity. The brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Question phrasing in brand voice. Result presentation that feels distinct. + +--- + +## The mobile-broken quiz + +The pattern. Quiz works on desktop; breaks on mobile. Answer options that overflow; sliders impossible to grab; result hidden below the fold. + +The signal. High mobile bounce rate; mobile completion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Detail in `references/question-architecture-patterns.md` (mobile section). + +--- + +## The popup-interrupted quiz + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. + +The signal. Bounce rate spikes at the result moment; users complain about the interruption. + +The cost. The quiz's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. + +--- + +## The orphan-quiz + +The pattern. The quiz exists; no follow-up sequence; no integration with the broader funnel. Takers complete; nothing happens. + +The signal. Email captures sit on a list with no engagement; downstream conversion is near zero. + +The cost. The lead-capture work was for nothing. The brand has emails but no relationship. + +The cure. Design the post-quiz sequence as part of the quiz design (similar to the lead-magnet sequence discipline in `lead-magnet-design`). + +--- + +## The everyone-quiz + +The pattern. Quiz designed to appeal to "everyone." Generic segments; generic recommendations. + +The signal. Conversion may be high; lead quality is low; downstream conversion is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly. + +The cure. Narrow the audience the quiz serves. Specific quizzes for specific segments produce specific recommendations that convert. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active quiz, looking specifically for these anti-patterns. + +Audit questions per quiz. + +- Does each segment have a specific, distinct recommendation (anti-pattern check: forced-result, mismatched-recommendation)? +- Is segment distribution balanced across takers (anti-pattern check: over-segmentation, under-segmentation)? +- Is drop-off concentrated at specific questions (anti-pattern check: interrogation, leading questions)? +- Does the result page include a clear next step (anti-pattern check: no-recommendation, vanity-result)? +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Does the quiz feel branded or templated (anti-pattern check: cookie-cutter)? +- Does the quiz work on mobile (anti-pattern check: mobile-broken)? + +The retire decision. Anti-pattern quizzes often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-quiz plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md new file mode 100644 index 0000000..11cf765 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md @@ -0,0 +1,145 @@ +# Quiz investment criteria + +When a quiz is the right tool for the audience and the goal, and when a comparison table or other format would serve. The conditions that warrant the quiz format. + +A quiz is a meaningful build. Question architecture, scoring algorithm, result categorization, recommendation mapping, lead-capture integration. The quiz earns this investment only when specific conditions are present. + +--- + +## When a quiz earns the build + +Five conditions that, when present, make a quiz a strong investment. + +The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. + +The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation. If the categorization needs 30+ questions, the format is closer to a survey or assessment than a quiz; the audience drop-off makes the format wrong. + +The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation is decorative; the segment-recommendation mapping is the value. + +The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage well. Audiences who do not (technical buyers, enterprise sales) often see quizzes as gimmicks. + +The success metric is defined. Lead volume from the quiz, lead quality by segment, downstream conversion per segment, the audience acting on the recommendation. Without the success metric defined, evaluation is impossible. + +When all five are present, the quiz is a strong investment. When two or fewer are present, a different format (comparison table, worked example, calculator) often serves better. + +--- + +## When a quiz does NOT earn the build + +Funnels where the quiz is the wrong tool. + +The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. Quizzes earn investment when the categorization is non-trivial. + +The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. The categorization needs to map to action. + +The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. Without a portfolio of segment-matched recommendations, the quiz cannot deliver the actionable-segmentation value. + +The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional. Technical decision-makers often skip quizzes in favor of direct documentation. The format choice has to fit the audience the brand wants to serve. + +The team cannot maintain the quiz. Quizzes decay as recommendations change, segments evolve, and audience preferences shift. Without maintenance commitment, the quiz becomes stale. + +The audience would convert without the quiz. When the funnel is already producing the conversion the quiz would serve, the quiz adds friction without lift. + +The honest assessment matters more than the default. "Should we have a quiz" is not the question. "Is the quiz the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A quiz is a meaningful build. Account for the cost honestly. + +The build cost. Question design, scoring algorithm, result categorization, recommendation mapping, UI design, mobile responsiveness, integration. A meaningful quiz often takes 30-100 engineering hours plus design, copy, and content for the recommendations. + +The maintenance cost. Recommendations change; segments evolve; question phrasing decays. Quarterly review and updates run 3-8 hours per active quiz. + +The recommendation portfolio cost. Each segment needs a matched recommendation. Building or curating those recommendations is itself work. + +The opportunity cost. What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization. The quiz's success has to clear the bar of those alternatives. + +The decision frame. The quiz earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus recommendation portfolio. + +--- + +## The recommendation-portfolio precondition + +Without a portfolio of segment-matched recommendations, the quiz cannot deliver actionable segmentation. + +The check. For the segmentation the quiz will produce, does the brand have a distinct, valuable recommendation for each segment? + +If yes, the quiz can deliver actionable segmentation. The takers get matched to a recommendation that fits their result. + +If no (the brand has one product, one resource, one recommendation regardless of segment), the quiz becomes vanity. The segmentation is decorative; the recommendation was predetermined. + +How to assess the recommendation portfolio. + +- Does the brand have multiple products, services, or content paths that fit different audience segments? +- Can the brand articulate which recommendation fits which segment specifically? +- Are the recommendations valuable enough to that segment to justify the quiz? + +If yes to most of these, the recommendation portfolio supports the quiz. If no, the quiz is the wrong format until the portfolio exists. + +--- + +## The decision worked example + +A B2B SaaS company considering a "What CRM fits your team" quiz. + +Conditions check. + +- Decision benefits from categorization: yes. Prospects evaluate CRMs based on team size, use case, sales process maturity, integration needs. The categorization is non-trivial. +- Small number of questions sufficient: yes. 6-8 questions can capture team size, use case, sales process, integration needs. +- Recommendation portfolio: yes. The brand offers 3 plan tiers plus 2 industry-specific configurations. Each segment can map to a distinct recommendation. +- Audience-fit for quiz format: yes. B2B mid-market PMs and sales leads engage with quizzes when the recommendation is genuinely useful. +- Success metric: yes. Lead volume from the quiz, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo or trial within 60 days. + +Decision. Build the quiz. The conditions warrant it. + +Result categorization. 5 segments: "Solo founder just starting," "Growing team without CRM," "Mid-market with multiple sales reps," "Enterprise with complex sales cycles," "Integration-heavy team." + +Recommendation per segment. Each segment maps to a specific plan and onboarding path. The segment description explains why that recommendation fits. + +Lead capture. Email after result for personalized PDF showing the recommendation, alternative options considered, and case study from a similar customer. + +The decision was not "should we have a quiz" but "given these conditions, this is the quiz to build." + +--- + +## When to choose a different format + +The quiz is the wrong tool. What works. + +Comparison table. When the choice is between 2-4 well-defined options with clear distinguishing features, a comparison table often serves better. The audience compares directly without going through questions. + +Worked-example resource. When the audience benefits from seeing how others in their situation chose, a 2-page worked-example resource often serves better than a quiz. The audience identifies which example matches them. + +Calculator. When the decision benefits from a calculation rather than a categorization, a calculator serves better. Detail in `calculator-design`. + +Direct documentation. When the audience prefers self-directed research, a clear documentation page about which option fits which situation often serves better than a quiz. + +The pattern. Many "we need a quiz" intuitions are actually "we need a clear way to communicate which option fits which audience." Often the simpler format works as well or better, at lower build cost. + +--- + +## When to retire a quiz + +Quizzes decay. Retiring them is part of the discipline. + +Retire when: + +- Lead volume has dropped below baseline for two consecutive quarters. +- The recommendation portfolio has shifted enough that the quiz routes to outdated recommendations. +- One segment now receives 80 percent of takers, suggesting the question architecture no longer distinguishes. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. Stale quizzes route audience to outdated recommendations and damage trust. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a quiz. The opportunity-cost frame. The recommendation-portfolio precondition. The decision worked example. When to choose a different format. The retirement discipline. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. The team's capacity benchmarks for build, maintenance, and recommendation curation. Specific tooling for quiz engineering and integration. Specific recommendation portfolios per segment. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md new file mode 100644 index 0000000..f9e74d7 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-categorization-patterns.md @@ -0,0 +1,233 @@ +# Result categorization patterns + +Segment count, naming, distinguishability, balance. The shape of the result categories that the quiz produces. + +The categorization is the quiz's segmentation product. Bad categorization produces results that feel arbitrary or that fail to help the audience act. Good categorization produces results the audience recognizes and uses. + +--- + +## Segment count + +Most quizzes work well with 4-8 result categories. + +Fewer than 4 segments. The categorization feels coarse. Two-segment quizzes (e.g., "is this for you, yes or no") rarely earn the quiz format; a comparison or qualifying form serves better. + +4-6 segments. The sweet spot for most quizzes. Enough segments to feel nuanced; few enough that each gets adequate development. + +7-8 segments. Acceptable when the segmentation is genuinely multi-dimensional. Each segment needs a distinct description, distinct recommendation, and clear distinguishability. + +9+ segments. Often a sign of over-segmentation. Many segments end up similar in description and recommendation; the segmentation becomes fake. + +--- + +## Segment naming + +Memorable. Specific. Honest. Brand-voice consistent. + +Memorable. The taker should be able to describe their segment to a friend. "The Strategic Planner" is memorable; "Type 3" is not. + +Specific. Names should distinguish the segment from others. + +- Specific: "The Hands-On Builder" (vs "Type B") +- Specific: "Solo founder just starting" (vs "Beginner") +- Specific: "Mid-market operator with multiple sales reps" (vs "Mid-tier user") + +Honest. Names should not flatter universally. Some segments are more flattering than others; honest segmentation reflects this. + +- Honest: "Just exploring" alongside "Already executing" alongside "Mature operator." Each describes a real position. +- Dishonest: every segment named with a flattering descriptor regardless of where the taker actually is. + +Brand-voice consistent. The names should sound like the brand the quiz represents. A serious brand uses serious names; a playful brand can use playful names. Consistency matters. + +--- + +## Segment distinguishability + +Each segment should be meaningfully different from the others. + +The test. Read the descriptions of two adjacent segments. Are they meaningfully different in: +- Who the segment describes? +- What the segment's situation is? +- What the segment's recommendation is? + +If yes, the segments are distinguished. If no (the descriptions are similar, the recommendations overlap), the segmentation is fake. + +The fake-segmentation pattern. A quiz produces 5 segments, but segments 2, 3, and 4 are described in similar terms with similar recommendations. The audience that lands in different segments gets indistinguishable results; the segmentation is decorative. + +The cure. Either reduce the segment count (if the segmentation does not support 5 segments, do not pretend it does) or strengthen the distinctions (rewrite descriptions and recommendations so each segment is distinct). + +--- + +## Segment balance + +Each segment should receive a meaningful share of takers. + +Balanced segmentation. Each segment receives roughly 10-30 percent of takers (depending on segment count). The audience is genuinely distributed across segments. + +Imbalanced segmentation. One segment receives 70+ percent of takers; another receives less than 5 percent. The segmentation is not working; the questions do not distinguish meaningfully. + +Why balance matters. + +- Imbalance signals the segmentation is broken. +- The unused segments waste design and copy effort. +- The dominant segment becomes a default that does not really categorize anyone. + +The cure. Audit the question architecture (`references/question-architecture-patterns.md`). Often the questions do not produce balanced segmentation because they bias toward one segment. Adjust questions or weights to produce more even distribution. + +The exception. Some quizzes intentionally produce imbalanced segmentation because the audience genuinely skews. A "what is your team size" quiz may produce 60 percent "small team" because the audience is mostly small teams. Honest imbalance reflecting real audience composition is fine; imbalance from broken questions is not. + +--- + +## Segment description + +What appears at the result, beyond the segment name. + +The description should include: + +- A 2-3 sentence summary of the segment (who they are, what their situation is). +- Specific characteristics the audience will recognize. +- The matched recommendation (what to do next). +- Optional: case study or worked example of someone in this segment. + +Example segment description. + +``` +Segment: "The Mid-Market Operator" + +You are running a sales team of 5-25 people across multiple +products or regions. You have a defined sales process but +inconsistent execution; some reps follow it, others freelance. +Your top priority is unifying the team's process without +slowing your fastest performers. + +Recommendation: Our Growth plan with the multi-region +playbook configuration. We have a 30-day onboarding path +for teams in your situation. + +[Link to PDF: see how 3 mid-market operators implemented +this and the results] +``` + +The description is specific. The recommendation is matched. The next step is clear. + +Description antipatterns. + +- Generic descriptions that could fit multiple segments. +- Flattering descriptions with no honest characterization. +- Descriptions that describe but do not recommend. +- Recommendations that are the same across segments. + +--- + +## Segment naming patterns + +Common patterns and their tradeoffs. + +Pattern A: Role-based names. "The Strategic Planner," "The Hands-On Builder." Useful when segments correspond to functional roles. + +Pattern B: Maturity-based names. "Just Starting," "Growing," "Mature." Useful when segments correspond to stages of development. + +Pattern C: Style-based names. "The Optimizer," "The Connector," "The Visionary." Common in personality assessments. Risk of feeling horoscope-like. + +Pattern D: Situation-based names. "Solo founder pre-launch," "Mid-market operator with multi-region team." Useful when segments correspond to specific situations the audience recognizes. + +Pattern E: Outcome-based names. "Cost-focused buyer," "Time-saver-focused buyer." Useful when segments correspond to what the buyer is optimizing for. + +The pattern choice depends on the quiz's purpose and the audience the brand serves. The discipline is that whatever pattern is chosen, names should be specific and honest. + +--- + +## Result-page composition + +What the result page contains beyond the segment description. + +The standard structure. + +- The segment name and key visual. +- The segment description (2-3 sentences). +- The matched recommendation. +- The clear next step (CTA: download PDF, talk to team, explore product). +- Optional: comparison to other segments (so the taker sees the full picture). +- Optional: share button (if the quiz is shareable). + +The clear-next-step principle. Every result page must include a specific next step. Without it, the quiz produces awareness without action. + +The optional comparison. Showing the other segments lets the taker see the full segmentation. Useful when the audience benefits from understanding where they sit; less useful when the segments would distract from the matched recommendation. + +--- + +## Result-page mobile design + +The result page must work on mobile. + +Mobile considerations. + +- Segment name and recommendation visible without scroll. +- Visual elements sized for mobile screens. +- CTA button large and prominent. +- Share buttons functional on mobile platforms. + +Common mobile failures. + +- Result hidden below the fold; user does not know it loaded. +- Recommendation buried after a long scroll. +- CTA button tiny or hard to tap. + +--- + +## Segment maintenance + +Segments decay along with the quiz. + +What decays. + +- Segment descriptions that no longer match the audience composition. +- Recommendations that point to retired products or content. +- Brand voice that has shifted. + +Maintenance cadence. Quarterly review of segment descriptions and recommendations. Update as the recommendation portfolio evolves. + +The retire-segment decision. A segment that receives less than 3 percent of takers consistently may not warrant maintenance. Either restructure the segmentation to merge underused segments or accept that the segmentation has segments that exist but are rarely produced. + +--- + +## The segmentation-recommendation alignment audit + +Periodically verify that each segment's recommendation still matches. + +The audit. For each segment: +- Does the recommendation still exist (not pointing to a retired product)? +- Does the recommendation still match the segment's situation? +- Does the recommendation deliver value to that specific segment? + +The drift. Recommendations decay. Products are retired, content is updated, the brand evolves. Audit cadence catches the drift. + +--- + +## Common categorization failures + +Too few segments. Categorization feels coarse; quiz earns no segmentation value. + +Too many segments. Over-segmentation; segments end up similar; categorization feels fake. + +Generic segment names. Names that could apply to multiple segments; not memorable. + +Flattering-everyone descriptions. No honest segmentation; all segments feel positive. + +Indistinguishable segments. Two segments that read the same; categorization is decorative. + +Imbalanced distribution. One segment dominates; segmentation is broken. + +Result without recommendation. Description but no next step; quiz produces awareness without action. + +Recommendations all the same. Different segments routed to the same product or path; segmentation is decorative. + +--- + +## Methodology-level choices that stay in the public skill + +Segment count guidance. Naming patterns and discipline (memorable, specific, honest, brand-voice consistent). Distinguishability test. Balance principle. Segment description structure. Naming patterns A through E. Result-page composition. Mobile design. Segment maintenance. Segmentation-recommendation alignment audit. Common failures. + +## Implementation choices that stay internal + +Specific segment names for specific quizzes. Specific descriptions in brand voice. Specific recommendations matched to segments. Specific result-page layouts. The team's audit calendars. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md new file mode 100644 index 0000000..e94131f --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md @@ -0,0 +1,255 @@ +# Result-to-recommendation mapping + +The action attached to each category. Mapping discipline and worked examples. The recommendation is what the taker does next; without it, the quiz produces awareness without action. + +The mapping is where the quiz earns its conversion. A great segmentation produces nothing if each segment lacks a matched, actionable recommendation. + +--- + +## The mapping principle + +Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +The principle's three requirements. + +- The recommendation is real (the brand actually offers the recommended next step). +- The recommendation matches the segment specifically (no two segments share the same recommendation). +- The recommendation is valuable to that specific segment (not a generic offer applied to everyone). + +Quizzes that hit all three produce action. Quizzes that miss any of the three produce vanity-result patterns. + +--- + +## What a recommendation can be + +The next step the taker should take. Many forms. + +Product or service. "Solo founders benefit most from our Starter plan with the founder-led onboarding path." The recommendation is a specific tier or configuration matched to the segment. + +Content or resource. "Mid-market operators benefit most from our 30-day playbook for unifying multi-rep teams." The recommendation is a specific resource matched to the segment. + +Conversation or consultation. "Enterprise buyers benefit most from a 30-minute conversation with our team." The recommendation is a specific human touchpoint. + +Path or sequence. "Creators just starting benefit most from our 4-part onboarding sequence." The recommendation is a structured next experience. + +Configuration or setup. "Teams using Salesforce benefit most from our integration setup wizard." The recommendation is a specific technical configuration. + +The form depends on the brand's offerings and the segment's situation. The discipline is that the recommendation is specific, not generic. + +--- + +## The mapping discipline + +Each segment-to-recommendation mapping should pass these tests. + +Test 1: Does the recommendation actually exist? The brand currently offers it; it is not aspirational or in development. + +Test 2: Does the recommendation match the segment specifically? Other segments would not benefit from this recommendation as much; the matching is real. + +Test 3: Does the recommendation deliver value to this segment? The segment that gets this recommendation can act on it and benefit from it. + +Test 4: Is the recommendation deliverable? The brand can provide what is being recommended in the timeframe and form the taker expects. + +Test 5: Does the recommendation include a clear action? The taker knows what to do (click here, start here, talk to someone, download this). + +When all five pass, the mapping is honest. When any fails, the mapping is decorative or misleading. + +--- + +## Worked example: B2B SaaS pricing quiz + +A SaaS platform offering 4 plan tiers with industry-specific configurations. + +Segments and recommendations. + +Segment 1: "Solo founder just starting" +- Description: 1-person team, exploring options, pre-revenue or early revenue. +- Recommendation: Starter plan ($X / month) with the founder-led onboarding path. Free for first 30 days; no credit card required. +- Action: "Start your 30-day trial." Direct link to signup pre-filled with the recommended plan. + +Segment 2: "Growing team without CRM" +- Description: 2-15 people, no CRM today, sales process is informal but starting to need structure. +- Recommendation: Growth plan ($Y / month) with the team-onboarding path. 30-day setup support included. +- Action: "Talk to our team about your setup." Calendar booking link. + +Segment 3: "Mid-market with multiple reps" +- Description: 16-100 people, multiple sales reps, defined process but inconsistent execution. +- Recommendation: Business plan ($Z / month) with multi-rep configuration and 60-day implementation support. +- Action: "Get a custom demo." Form for demo request. + +Segment 4: "Enterprise with complex sales cycles" +- Description: 100+ people, multi-stage sales process, integration-heavy environment. +- Recommendation: Enterprise plan (custom pricing) with dedicated implementation manager. +- Action: "Talk to enterprise sales." Direct line to enterprise contact. + +Segment 5: "Integration-heavy team" +- Description: Any size, but the primary need is integrating with their existing tool stack. +- Recommendation: Any plan plus the integration setup wizard. Detailed integration documentation linked. +- Action: "Explore our integrations." Integration catalog page. + +Each segment maps to a distinct, specific recommendation. Each recommendation includes a clear action. + +--- + +## Worked example: content-marketing quiz + +A content-marketing brand offering multiple content paths. + +Segments and recommendations. + +Segment 1: "Just starting in content" +- Recommendation: 4-part email course covering content fundamentals. +- Action: "Get the 4-part course." Signup form. + +Segment 2: "Producing content but inconsistent results" +- Recommendation: Content audit template + worked-example case study. +- Action: "Download the audit template." Direct download. + +Segment 3: "Scaling a content team" +- Recommendation: Team-management playbook + interview with a content director. +- Action: "Read the playbook." Resource page with playbook and interview. + +Segment 4: "Optimizing for distribution" +- Recommendation: Distribution-strategy framework + 5 worked examples. +- Action: "Read the framework." Resource page. + +Each segment routes to a distinct content path matched to where the audience is. + +--- + +## Worked example: readiness-assessment quiz + +A consultancy offering readiness assessments before engagement. + +Segments and recommendations. + +Segment 1: "Not yet ready" +- Description: Foundation work needed before the consultancy's offering would help. +- Recommendation: Self-serve resources for foundation work. Honest acknowledgment that engagement is not warranted yet. +- Action: "Explore the foundation library." Free resources. + +Segment 2: "Ready for assessment" +- Description: Foundation in place; specific gaps need addressing. +- Recommendation: 60-minute assessment call to identify specific engagement scope. +- Action: "Book the assessment call." Calendar link. + +Segment 3: "Ready for full engagement" +- Description: Foundation in place; clear gaps; ready to engage. +- Recommendation: Direct engagement conversation. +- Action: "Talk to our partner." Direct contact. + +Segment 4: "Ongoing support" +- Description: Already engaged, looking for continued partnership. +- Recommendation: Continuity-engagement options. +- Action: "Discuss your next phase." Direct contact. + +The honest segmentation includes a "not yet ready" segment. This is honest and earns trust; not every taker should be sold to immediately. + +--- + +## The "not for you" segment + +Honest segmentation sometimes includes a segment that is not the brand's audience. + +The pattern. A segment for takers who are not a fit. The recommendation acknowledges the lack of fit and offers something useful (a referral, a different brand's resource, a self-serve path). + +Why it works. + +- The taker who would have churned anyway leaves with respect for the brand. +- The brand earns "honest" reputation that compounds across audience segments. +- The unfit taker may refer fit takers later. + +The dishonest alternative. Pretending every taker is a fit; routing everyone to a sales contact regardless of segment. Audiences that catch the dishonesty disengage. + +--- + +## Recommendation freshness + +Recommendations decay; the mapping needs maintenance. + +What decays. + +- Recommendations pointing to retired products. +- Recommendations referencing outdated pricing or features. +- Recommendations linking to broken pages or moved resources. +- Recommendations that no longer match the brand's strategic priorities. + +Maintenance cadence. Quarterly review of every active recommendation. Update or replace as the brand's portfolio evolves. + +The drift indicator. Sales-team feedback that quiz-sourced leads are landing on the wrong recommendation. The mapping has drifted; refresh. + +--- + +## Recommendation testing + +Test the recommendations as part of quiz launch and updates. + +Click-through testing. What percentage of takers in each segment click the recommendation's CTA? Low click-through suggests the recommendation does not feel matched. + +Conversion testing. What percentage of takers in each segment complete the recommended action (sign up, book a call, download the resource)? Low conversion suggests the recommendation does not deliver expected value. + +Feedback testing. Direct user feedback ("does this recommendation feel right for you?"). Useful for early validation; rarely scalable. + +--- + +## The recommendation-as-CTA discipline + +The recommendation is also the call to action. + +The pattern. The recommendation includes a specific button or link that takes the taker to the next step. + +Specific CTAs. + +- "Start your 30-day trial" (specific action, specific timeframe). +- "Book a 30-minute assessment call" (specific format, specific duration). +- "Download the audit template" (specific deliverable). + +Generic CTAs to avoid. + +- "Learn more" (about what?). +- "Get started" (started doing what?). +- "Click here" (no value statement). + +The recommendation deserves a specific CTA matched to the action. + +--- + +## Multi-recommendation results + +Some quizzes produce multiple recommendations per segment. + +The pattern. The result includes a primary recommendation and one or more secondary recommendations. + +When this works. When the segment genuinely benefits from multiple paths (e.g., "you can start with X, or if you have specific need Y, consider Z instead"). + +When this fails. When multiple recommendations dilute the call to action; the taker does not know which to choose. + +The discipline. Default to one primary recommendation. Add secondary recommendations only when the segment genuinely benefits from a choice. + +--- + +## Common mapping failures + +Same recommendation across segments. Different segments route to the same product or path; segmentation is decorative. + +Generic recommendations. "Talk to our team" for every segment without segment-specific framing. + +Aspirational recommendations. Recommendations for products or services not yet available; the taker tries the action and hits dead ends. + +Mismatched recommendations. Recommendation does not match the segment's situation; takers feel unheard. + +Buried recommendations. Recommendation appears 3 emails after the result rather than in the result itself. + +No clear CTA. Recommendation describes what to do without providing the link or button to do it. + +No "not for you" segment. Every taker routed toward sales; the audience that does not fit is treated as fitting; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle and three requirements. Forms a recommendation can take. The mapping discipline (5 tests). Worked examples across quiz types. The "not for you" segment. Recommendation freshness. Recommendation testing. Recommendation-as-CTA discipline. Multi-recommendation results. Common failures. + +## Implementation choices that stay internal + +Specific segment-to-recommendation mappings for specific quizzes. Specific recommendation copy and CTAs in brand voice. Specific tracking for click-through and conversion per recommendation. The team's quarterly mapping audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md b/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md new file mode 100644 index 0000000..31c9328 --- /dev/null +++ b/dist/pi/.agents/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md @@ -0,0 +1,284 @@ +# Scoring algorithm patterns + +Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. The math that turns answers into a segment. + +The scoring algorithm is the bridge from question answers to result categorization. The right algorithm produces meaningful segments; the wrong algorithm produces results that do not match audience self-perception. + +--- + +## Pattern A: Direct mapping + +Each answer corresponds directly to a segment. The dominant answer choice determines the result. + +How it works. + +- Each question's answer choices map to specific segments. +- Each answer adds 1 point (or fixed weight) to its corresponding segment. +- The segment with the most points wins. + +Example. + +Question: "What size is your team?" +- 1-5 → "Solo" (+1) +- 6-25 → "Growing" (+1) +- 26-100 → "Mid-market" (+1) +- 100+ → "Enterprise" (+1) + +After all questions, the segment with the highest count wins. + +Strengths. + +- Simple, transparent, easy to explain. +- Easy to maintain (changes are obvious in their effect). +- The scoring logic can be displayed to the audience without confusion. + +Weaknesses. + +- Limited nuance; one answer cannot contribute to multiple segments meaningfully. +- Risk of ties when multiple segments score equally. + +When to use. When segments are well-defined and questions clearly distinguish them. The default starting point for many quizzes. + +--- + +## Pattern B: Weighted scoring + +Each answer adds points (with weights) to one or more segments. The highest-scoring segment wins. + +How it works. + +- Each question's answer choices add weighted points to one or more segments. +- An answer might add 3 points to segment A and 1 point to segment B. +- After all questions, the segment with the highest total score wins. + +Example. + +Question: "What is your sales process maturity?" +- "Founder-led, no defined process" → "Solo" (+3), "Growing" (+1) +- "Some defined steps" → "Growing" (+3), "Mid-market" (+1) +- "Defined sales playbook" → "Mid-market" (+3), "Enterprise" (+1) +- "Multi-stage enterprise process" → "Enterprise" (+4) + +This question is more central to segmentation, so its weights are higher. + +Strengths. + +- Allows nuance; one answer can contribute to multiple segments. +- Different questions can have different importance through their weights. +- Reduces tie likelihood by spreading weights. + +Weaknesses. + +- Less transparent (audience cannot easily reverse-engineer the result). +- More complex to maintain (changes to weights have non-obvious effects). +- Easy to bias accidentally if weights are not audited. + +When to use. When segmentation needs nuance, when some questions are more important than others, when the segmentation is multi-attribute. + +--- + +## Pattern C: Multi-dimensional + +The quiz produces scores across multiple axes. The result combines the scores into a 2D or 3D segment. + +How it works. + +- The quiz captures scores across 2-3 distinct dimensions (e.g., introvert/extrovert AND analytical/intuitive). +- The result is determined by the position on each dimension (introvert + analytical = one quadrant; extrovert + intuitive = another). +- Common in personality assessments, fit-evaluations, and any segmentation that is genuinely multi-axis. + +Example. + +A 2-dimensional quiz might score: +- Dimension 1: technical depth (low to high) +- Dimension 2: collaboration preference (solo to team) + +Result quadrants: +- High technical, solo → "Solo specialist" +- High technical, team → "Team specialist" +- Low technical, solo → "Solo generalist" +- Low technical, team → "Team generalist" + +Strengths. + +- Captures genuine multi-dimensional segmentation. +- Produces results that feel nuanced and accurate. +- Allows for richer recommendations matched to the dimensional combination. + +Weaknesses. + +- Significantly more complex than single-axis scoring. +- Larger result-set to design and maintain (4 quadrants from 2 dimensions; 8 from 3 dimensions). +- Harder for the audience to predict their result before taking. + +When to use. When segmentation is genuinely multi-axis (personality, fit-evaluation, learning style, decision-making style). + +--- + +## Pattern D: Branching logic + +The next question depends on the previous answer. Allows for adaptive questioning. + +How it works. + +- The quiz starts with a few common questions. +- Based on early answers, the quiz routes to different question sets. +- Different paths through the quiz produce different results. + +Example. + +Question 1: "Do you currently use a CRM?" +- Yes → branch A (questions about current CRM, satisfaction, gaps) +- No → branch B (questions about why not, what would change, current process) + +The two branches produce different question sets that map to different segments. + +Strengths. + +- Adaptive; questions feel relevant to the taker. +- Can produce highly specific segmentation. +- Reduces irrelevant questions for any one taker. + +Weaknesses. + +- Significantly more complex to build and test. +- Harder to compare segments because not all takers answered the same questions. +- Maintenance is harder; changes to one branch can affect overall scoring. + +When to use. When later questions make sense only in the context of earlier ones, when the audience genuinely needs different questions based on their initial situation. + +--- + +## Choice criteria + +Which pattern fits which quiz. + +Use direct mapping when: + +- Segments are well-defined and clearly distinguished. +- Each question maps cleanly to one segment. +- Transparency matters (audience benefits from being able to reason about their result). + +Use weighted scoring when: + +- Segmentation needs nuance. +- Some questions are more central to segmentation than others. +- Most answers contribute to multiple segments meaningfully. + +Use multi-dimensional when: + +- Segmentation is genuinely multi-axis. +- The audience expects a richly textured result (personality assessments, learning styles). +- Each dimension can be measured by a coherent subset of questions. + +Use branching when: + +- Later questions depend on earlier context. +- The audience genuinely splits into distinct groups that need different question sets. +- The maintenance complexity is justified by the segmentation value. + +The simplest pattern that produces the right segmentation is usually the best choice. Complexity has cost; only spend it where it produces value. + +--- + +## Tie-breaking + +What happens when two segments score equally. + +Pattern A: First-tied-segment wins. The segment that reached the top score first (in the order segments are evaluated) wins. Simple but can introduce bias if the order is not deliberate. + +Pattern B: Tie-breaker question. A specific question whose answer breaks the tie. Useful when ties are common. + +Pattern C: Combined-segment result. A result for the tie itself ("You are between segment A and segment B"). Useful when the tie is genuinely meaningful. + +Pattern D: Re-prompt or randomize. Ask one more clarifying question to break the tie. Adds friction but produces a definitive result. + +The choice. Depends on how often ties occur and how meaningful the distinction between tied segments is. If ties are rare and the segments are similar, Pattern A is fine. If ties are common and the segments differ significantly, Pattern B or C is warranted. + +--- + +## Edge-case handling + +What happens at the boundaries of the scoring. + +The all-segments-zero edge case. A taker answers in a way that gives zero points to every segment. Rare but possible. Default to the most common segment, or surface a "we could not categorize you" message that prompts re-engagement. + +The very-high-single-segment edge case. A taker scores extremely high on one segment, far above any other. Often signals strong segmentation; the result is reliable. + +The all-segments-equal edge case. A taker scores equally across all segments. Often signals the questions did not distinguish; the result is unreliable. May warrant a different question set or a different recommendation flow. + +The contradictory-answers edge case. A taker's answers contradict each other in ways the scoring did not anticipate. Often surfaces in audit; the question set may need clarification. + +--- + +## Scoring transparency to the user + +Whether to show the score during or after the quiz. + +Show the score. When the dimensions or score are themselves meaningful to the user (personality assessments often benefit from showing dimensional scores). + +Hide the score. When the score is implementation detail and the segment is the meaningful output (most recommendation quizzes hide the score). + +Hybrid. Show segment + a brief explanation of how it was determined. "Your result is X. The questions that most influenced this were Y and Z." + +The choice depends on whether the score helps the user understand or distract from the result. + +--- + +## Algorithm decay + +Scoring algorithms decay along with quizzes. + +What decays. + +- Question weights that no longer reflect the segmentation reality. +- Segments that have shifted in audience composition. +- Edge cases that have become more common. + +Maintenance cadence. Quarterly review of the scoring algorithm. Audit a sample of takers to confirm results match expectations. + +Drift indicators. + +- One segment receiving 70+ percent of takers. +- Audience comments that the result feels wrong. +- Sales-team feedback that quiz-sourced leads are misclassified. + +--- + +## Algorithm testing + +Test the scoring algorithm before launch and after changes. + +Persona testing. Create personas representing each intended segment. Take the quiz as each persona; verify each persona reaches the intended segment. + +Edge-case testing. Try answer combinations that should produce ties, contradictions, or boundary conditions. Verify the algorithm handles them gracefully. + +Volume testing. Run the quiz with synthetic data simulating expected audience composition. Verify segment distribution matches expectations. + +Production monitoring. Track segment distribution over time. Sudden shifts may indicate question or scoring issues. + +--- + +## Common scoring failures + +Algorithm too simple for the segmentation. Direct mapping when weighted scoring is needed; segments end up poorly distinguished. + +Algorithm too complex for the segmentation. Multi-dimensional when single-axis would have served; complexity without value. + +Hidden bias in weights. Weights that systematically favor one segment regardless of true audience composition. + +Tie-breaking arbitrary. Ties resolved in inconsistent or biased ways. + +No production monitoring. Algorithm drifts unnoticed; segment distribution becomes skewed. + +Scoring not documented. Future maintainers cannot reason about the algorithm; changes break in unexpected ways. + +--- + +## Methodology-level choices that stay in the public skill + +The four scoring patterns with how-it-works, strengths, weaknesses, and when-to-use guidance. Choice criteria. Tie-breaking patterns. Edge-case handling. Scoring transparency. Algorithm decay and maintenance. Algorithm testing. Common failures. + +## Implementation choices that stay internal + +Specific scoring algorithms for specific quizzes. Specific weights and segment mappings. Specific testing personas. Specific tooling for algorithm implementation and monitoring. These vary by team. diff --git a/dist/pi/.agents/skills/roadmap-planning/SKILL.md b/dist/pi/.agents/skills/roadmap-planning/SKILL.md new file mode 100644 index 0000000..ba9cc5e --- /dev/null +++ b/dist/pi/.agents/skills/roadmap-planning/SKILL.md @@ -0,0 +1,228 @@ +--- +name: roadmap-planning +description: "Build a multi-quarter roadmap from a backlog of ideas, requests, and ongoing initiatives. Use this skill when planning the next quarter, sequencing dependent work, balancing build vs improve vs maintain, or making the case for what NOT to do. Triggers on roadmap, quarterly planning, what should we build next, sequencing, prioritization, OKR planning, capacity planning, what's on the roadmap, plan the year, what to ship next quarter. Also triggers when stakeholders are pulling in different directions and the team needs a defensible plan." +category: product +catalog_summary: "Quarterly planning, prioritization, dependency mapping" +display_order: 2 +--- + +# Roadmap Planning + +Take a pile of ideas, requests, and ongoing work. Produce a defensible plan for what to ship, when, and why. The output is a roadmap document plus the prioritization work that made it credible. + +--- + +## When to use + +- Planning the next quarter or the next year +- Sequencing work where some items depend on others +- Balancing new builds, improvements, and maintenance +- Saying no (or "not yet") to specific requests with a defensible reason +- Aligning a team around a single shared plan +- Communicating the plan to stakeholders outside the team +- Replanning after a strategy shift, a missed quarter, or new constraints + +## When NOT to use + +- Specifying a single feature for development (use `pm-spec-writing`) +- Validating whether the idea is worth building (use `ux-research`) +- Designing the feature itself (use `design-standards`) +- Writing the launch plan for a single initiative (use `launch-runbook`) +- Reviewing what shipped vs what was promised (use `after-action-report`) + +--- + +## Required inputs + +- The team's strategy or top-level goals (1 to 5 OKRs, themes, or pillars) +- The backlog: every candidate item, with at least a one-sentence description +- The team's capacity (people × time) +- Known constraints (deadlines, dependencies, hiring, budget) +- The planning horizon (a quarter, two quarters, a year) + +If the strategy is missing, the roadmap will be a list of features, not a plan. Push back and get the strategy first. A roadmap without strategy is just a queue. + +--- + +## The framework: 5 layers + +Roadmaps fail at five different layers. A roadmap is only as good as its weakest one. + +### Layer 1: Themes (the WHY) + +Top-level groupings tied to strategy. Every theme answers: "If we do nothing else this period, this is the outcome we want." + +Good themes are: +- Outcome-shaped, not feature-shaped ("Reduce time-to-first-value" beats "Build onboarding") +- Limited (3 to 5 max) +- Defensible (you can explain why this and not something else) +- Measurable (each maps to one or two metrics) + +Bad themes look like a junk drawer: "Improvements," "Tech debt," "Misc." If it can't be defended in one sentence, it isn't a theme. + +### Layer 2: Initiatives (the WHAT) + +Multi-week or multi-month efforts that ladder up to a theme. Each initiative is bigger than a feature but smaller than a theme. Initiatives have: + +- A clear outcome (the metric or result it should produce) +- A rough size (S / M / L / XL) +- A confidence rating (how sure are we this is the right initiative?) +- A dependency map (what has to happen first) + +Initiatives are where stakeholders push hard. Resist the urge to commit to dates here. Commit to outcomes and rough sizes. + +### Layer 3: Sequencing (the WHEN) + +The order things happen. Sequencing is constrained by: + +- Dependencies (X must finish before Y can start) +- Capacity (the team can do N things at once) +- Calendar reality (Q4 has fewer working days, certain teams have hiring gaps) +- Strategic windows (some launches need to land before a season, conference, or competitive moment) + +Build the sequence after the prioritization. Putting things in time-order before deciding what matters produces a plan optimized for calendar fit, not impact. + +### Layer 4: Capacity reality (the HOW MUCH) + +Most roadmaps fail here. The plan looks good on paper but assumes 100% of every person's time on roadmap work. Real capacity is much lower. + +Default capacity assumptions: + +- Engineers: 60-70% of time on roadmap initiatives. The rest is meetings, reviews, on-call, support, interviews, debugging, ramp-up. +- Designers: 50-60%. Same reasons plus more cross-team support. +- PMs: 40-50%. The rest is planning, comms, stakeholder management, async writing. +- New hires: assume 50% of full capacity for the first quarter, 75% for the second, 100% from Q3 on. +- On-call rotations, leave, holidays: subtract before sizing. + +If the math says the plan needs 100% of the team, the plan is wrong. Cut. + +### Layer 5: Trade-off communication (the WHY NOT) + +Every roadmap has a "Not now" list as important as the "Doing" list. The "Not now" is what makes the plan defensible. + +Include: +- The top requests you considered and rejected +- The reason for each rejection (not the right time, not the right size, conflicts with theme, lower expected impact) +- The condition that would make it move into "Doing" (a metric, a date, a finished prerequisite) + +Stakeholders pushing for cut items can argue against the rejection criteria, not the omission. That's a productive argument. + +--- + +## Workflow + +### Step 1: Anchor the strategy + +Before touching the backlog, write down 3 to 5 themes. If the team's OKRs or strategy doc gives you these, copy them. If not, draft them and validate with the people who own strategy. + +If the strategy is missing or vague, stop. Producing a roadmap against an unclear strategy is worse than producing nothing. Surface the gap. + +### Step 2: Catalog the backlog + +Every candidate gets: +- Name (one phrase) +- Theme it ladders up to (or "no theme" - flag for later) +- Source (request, OKR, retro, customer feedback, leadership ask, technical need) +- Rough size (S / M / L / XL) +- Owner or proposed owner +- Status (idea, validated, scoped, ready) + +Items with "no theme" are warning flags. Either the theme list is incomplete, or the item should be cut. + +### Step 3: Prioritize within each theme + +Inside each theme, rank the initiatives. Use one prioritization framework consistently. Common ones: + +- RICE (Reach × Impact × Confidence ÷ Effort): good for feature-heavy roadmaps +- MoSCoW (Must / Should / Could / Won't): good for fixed-deadline projects +- Kano (Threshold / Performance / Excitement): good for product investment decisions +- Cost of delay: good when timing matters more than effort +- Strategic alignment + impact: good for executive-facing roadmaps + +The framework matters less than the consistency. Pick one. Use it the same way for every initiative. Document the math. + +See [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) for the full breakdown. + +### Step 4: Build the dependency map + +For every "Doing" initiative, list what must happen first: +- Other initiatives +- Hiring +- External dependencies (vendor delivery, partner readiness) +- Research or validation work +- Infrastructure or platform readiness + +Visualize as a graph or a Gantt-style sequence. Items with no dependencies can start immediately. Items with multiple unmet dependencies are warning flags. + +### Step 5: Lay out the sequence + +Now place initiatives in time. Use the dependency map. Use the capacity math. Match initiatives to people who can actually do them. + +Default cadence: month-by-month for one quarter, quarter-by-quarter beyond that. Weekly is too granular for most roadmaps. Half-year buckets are too vague to commit to. + +### Step 6: Validate with the team + +Before sharing externally, validate with the people doing the work: +- Are the size estimates realistic? +- Are the dependencies correctly mapped? +- Are the capacity assumptions accurate? +- Is anyone overcommitted? + +If the team says the plan is impossible, the plan is impossible. Adjust. Going to leadership with a plan the team disagrees with is how trust gets broken. + +### Step 7: Write the "Not now" list + +For every "Doing" item, name what got cut to make room. Document why. Document the trigger that would move it to "Doing" later. + +### Step 8: Communicate + +Different audiences need different views: + +- Team: detailed sequence, owners, dependencies, sizes +- Cross-functional partners: themes, initiatives, rough timing, what they need to provide +- Leadership: themes, expected outcomes, key initiatives, top trade-offs +- Public or customer-facing: themes, no specific dates, "what to expect" + +The same roadmap should produce all four. If it can't, the roadmap is incomplete. + +--- + +## Failure patterns + +A list of features instead of a plan. Themes are missing. The roadmap is a backlog with months attached. Fix: start over from strategy. + +Date-driven thinking. "What can we ship by end of Q2?" instead of "What is the most important thing to do in Q2?" Dates are constraints, not goals. + +Capacity fantasy. The plan adds up to 100% of every person's time. No room for support, interrupts, planning, or unknown unknowns. Roadmap dies in week three. + +Stakeholder pressure overrides strategy. A loud customer or executive request gets prioritized because they pushed hard, not because it ladders up. The "Not now" list saves you here. + +Missing dependencies. Initiative B depends on initiative A, but A is scheduled later. Or A depends on a hire that hasn't happened. The plan looks fine until execution starts. + +Too far out. Specific commitments six months out create promises the team can't keep. Use ranges or themes for far horizons, specifics for near horizons. + +One framework for every level. RICE for the whole roadmap including platform work, infra, and exploration. RICE is great for features, weak for foundational work. Use different lenses for different initiative types. + +No "Not now." Stakeholders rediscover their cut requests every two weeks because there's no record of why they were cut. Document once, point to it forever. + +--- + +## Output format + +The roadmap document includes: + +- Strategy summary (1 page or section): themes, why these themes, how they ladder to top-level goals +- The plan (the visual): a quarter-by-quarter or month-by-month view, color-coded by theme +- Initiative briefs (one per initiative): outcome, size, owner, dependencies, success metric +- Capacity model: who is doing what, with utilization math +- Trade-offs and "Not now": top items considered and rejected, with reasons +- Risks and assumptions: what could derail the plan +- Update cadence: when the roadmap will be revisited (monthly is typical) + +The roadmap is a living document. Plan to revisit it monthly. Replan it formally each quarter. Do not treat it as a contract. + +--- + +## Reference files + +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Detailed breakdown of RICE, MoSCoW, Kano, Cost of Delay, and Strategic Alignment frameworks. When to use each, how to apply them, common mistakes. diff --git a/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md b/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md new file mode 100644 index 0000000..fead81c --- /dev/null +++ b/dist/pi/.agents/skills/roadmap-planning/references/prioritization-frameworks.md @@ -0,0 +1,192 @@ +# Prioritization Frameworks + +Five frameworks for prioritizing work. Each suits different problems. Pick one per planning cycle. Use it consistently. + +--- + +## RICE + +Best for: feature-heavy roadmaps where features are roughly comparable in shape. + +### The math + +``` +RICE Score = (Reach × Impact × Confidence) ÷ Effort +``` + +- Reach: how many people will this affect in a fixed period (e.g., users per quarter). Use real numbers, not relative scores. +- Impact: how much will it affect each person? Use a fixed scale: 3 (massive), 2 (high), 1 (medium), 0.5 (low), 0.25 (minimal). +- Confidence: how sure are you in the estimates? 100% (high), 80% (medium), 50% (low). Below 50%, you don't know enough to score. +- Effort: total person-months to deliver. Be honest. Include design, dev, QA, launch. + +Higher score = higher priority. + +### Where it shines + +Comparing many similarly-shaped feature ideas. Forces conversation about the inputs (Reach, Impact, Confidence) instead of a gut "I think this is more important." + +### Where it fails + +- Foundational work (infra, platform, refactors). Reach and Impact don't apply cleanly. +- Strategic bets where Confidence is low but the upside is huge. RICE punishes low-confidence work. +- "Cost of inaction" items (security, compliance). These often score badly but must ship. + +### Common mistakes + +- Inventing Reach numbers without a basis. If you don't have data, your Reach is a guess wrapped in math. +- Effort estimates that come from PMs, not engineers. Effort is always the engineer's call. +- Treating Impact as a continuous variable. The scale is fixed for a reason - so it's comparable. +- Re-scoring each cycle without checking what shipped last cycle and what its actual Reach × Impact turned out to be. + +--- + +## MoSCoW + +Best for: fixed-deadline projects where you have to decide what's in scope and what isn't. + +### The buckets + +- Must have: without these, the project fails. Non-negotiable for launch. +- Should have: important but not deal-breaking. Plan to include unless capacity tightens. +- Could have: nice to include if there's room. First to be cut. +- Won't have (this time): explicitly out of scope. Documented to prevent drift. + +### Where it shines + +Deadline-driven launches. New site builds. Migrations. Anything with a fixed go-live date. + +### Where it fails + +- Open-ended product work without a hard deadline. Everything tends to drift to "Must have." +- Long-running platforms. The buckets don't help sequence multi-quarter work. + +### Common mistakes + +- "Must have" creeping. By the end of planning, 80% of items are Must. Hard rule: "Must have" should be 30-50% of items, never more. +- No "Won't have." The "Won't have" list is the discipline. Without it, scope grows. +- Ambiguous lines between Must and Should. Define each explicitly. "If we ship without X, will the product work?" If yes, X is Should, not Must. + +--- + +## Kano + +Best for: product investment decisions about feature investment vs polish vs new bets. + +### The categories + +- Threshold features: users expect them. Their absence causes dissatisfaction. Their presence is barely noticed. (Examples: a working login. Email password reset.) +- Performance features: users notice them and value them linearly. More is better. (Examples: speed, search relevance, design quality.) +- Excitement features: users don't expect them. Their presence is delight. Their absence is unnoticed. (Examples: a clever zero state, an unexpected automation.) + +### How to use + +Audit the product. Categorize every feature. Decide where to invest: + +- Threshold features must be present and working. Underinvestment is a tax on everything else. +- Performance features should get sustained investment. They are how the product stays competitive. +- Excitement features are the differentiation budget. Spend selectively, expect them to age into Performance and eventually Threshold. + +### Where it shines + +Product strategy conversations. "Should we polish what we have or ship something new?" Kano answers it: are the Thresholds shipped? Then Performance. Then Excitement. + +### Where it fails + +- Doesn't help with sequencing among features in the same category. +- The categories shift over time. Today's Excitement is tomorrow's Threshold. + +### Common mistakes + +- Treating Excitement as the most valuable category. It's not. Threshold gaps will sink you faster than missing Excitement features. +- Confusing Excitement with novelty. Many "innovative" features are just Performance features in disguise. + +--- + +## Cost of Delay + +Best for: portfolios where timing matters more than effort, especially under capacity constraints. + +### The math + +``` +Cost of Delay per Week = Value Lost Per Week the Item Doesn't Ship +``` + +For each candidate, estimate: if we delay this by one week, what does it cost in revenue, retention, market position, or risk? + +Then divide by effort: + +``` +Cost of Delay Divided by Duration (CD3) = Cost of Delay per Week ÷ Duration in Weeks +``` + +The highest CD3 ships first. + +### Where it shines + +Sequencing inside a constrained team. Surfaces items where every week of delay matters (compliance deadlines, seasonal launches, competitive responses). + +### Where it fails + +- Estimating Cost of Delay is hard. Many items have qualitative cost ("brand damage," "team morale") that resists numerical estimates. +- Bias toward urgent over important. Recurring time-sensitive items (deadlines, customer escalations) keep beating strategic work. + +### Common mistakes + +- Treating all delays as having the same cost shape. Some items have flat cost (delay a week or a year, same outcome). Others have step changes (miss a deadline, lose 80% of the value). +- Ignoring the cost of NOT delaying (opportunity cost from working on this instead of something else). + +--- + +## Strategic Alignment + Impact + +Best for: executive-facing roadmaps and any planning where the question is "should we do this at all?" + +### The matrix + +A 2×2 grid: Strategic Alignment (low/high) on one axis, Impact (low/high) on the other. + +- High alignment / High impact: ship now. Resource heavily. +- High alignment / Low impact: ship if cheap. Question if expensive. +- Low alignment / High impact: dangerous. Either redefine strategy or cut. Items here drag the team away from the plan. +- Low alignment / Low impact: cut. Always. + +### Where it shines + +Cutting noise from the backlog. The bottom-right quadrant (Low/Low) is where most of the noise lives, and the matrix makes it obvious. + +Communicating with leadership. "This is high impact but not aligned" is a defensible reason to deprioritize. + +### Where it fails + +- Doesn't sequence within quadrants. Inside "High/High," you still need a tiebreaker. +- "Strategic alignment" is judgment, not math. Different people will plot the same item differently. + +### Common mistakes + +- Plotting everything as High/High to avoid the conversation. The matrix is only useful if there's a Low quadrant. +- Treating Strategic Alignment as fixed. Strategy changes. Re-plot every cycle. + +--- + +## Picking a framework + +\| If your team is... \| Use \| +\|---\|---\| +\| Building features for a product, comparable in shape \| RICE \| +\| Launching against a fixed deadline \| MoSCoW \| +\| Deciding investment levels across product areas \| Kano \| +\| Sequencing under capacity constraints with timing-sensitive items \| Cost of Delay \| +\| Cutting noise and aligning with leadership \| Strategic Alignment + Impact \| + +You can use more than one in a single planning cycle, but apply each consistently within its scope. Don't switch frameworks halfway through to justify a pre-decided answer. + +--- + +## The meta-rule + +Every framework has known weaknesses. Every framework can be gamed by stakeholders who learn how the math works. + +The frameworks are conversation tools, not decision tools. Their value is forcing the team to articulate inputs (reach, impact, alignment, urgency) instead of arguing about outputs. + +A good roadmap can be defended without the framework. The framework is the work, not the result. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md b/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md new file mode 100644 index 0000000..1057df6 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/SKILL.md @@ -0,0 +1,273 @@ +--- +name: scheduler-and-booking-design +description: "Designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic Calendly link. Availability logic, qualification gating, prep automation, follow-up sequencing. Honest about any-time-friction (no qualification, just a booking link), interrogation-gate (so much qualification it scares users off), and qualified-fast-path (just enough qualification to set up the call well) patterns. Triggers on scheduler design, meeting booking, demo scheduling, sales call scheduling, calendar tool, booking page, qualification flow. Also triggers when sales team complains about cold demos, when booking conversion is poor, or when scheduler is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing schedulers and booking flows. Distinguishes any-time-friction (no qualification, just a booking link) from interrogation-gate (so much qualification it scares users off) from qualified-fast-path (just enough qualification to set up the call well)" +display_order: 10 +--- + +# Scheduler and Booking Design + +A senior growth practitioner's playbook for designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic booking link. Availability logic, qualification gating, prep automation, follow-up sequencing. The discipline of building a scheduler that earns the booking by earning a better call. + +Most schedulers fail in one of two ways. Generic booking links produce cold demos where reps know nothing about the person they are about to talk to. Conversion stays at the rate of unqualified raw demos. Or qualification forms with 12 fields scare users off before they can book; drop-off at the form approaches 90 percent; only the leads who happen to survive the form actually convert. + +The schedulers that work do something different. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads route differently), prep automation that briefs the rep before the call. The booking is honest about who the audience is; the call is set up to succeed. + +The voice is the senior growth practitioner who has watched schedulers double demo conversion when redesigned and watched them collapse when more qualification was added. Practical, opinionated about which fields earn their place, willing to call out when the booking flow is the wrong tool. + +When to use this skill: scoping a scheduler for the first time, auditing a booking flow with poor conversion or poor downstream call quality, designing the qualification gate that produces context without producing friction, or deciding routing logic that matches leads to the right reps. + +--- + +## What this skill covers + +This skill spans meeting schedulers and booking experiences across acquisition and sales contexts. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access to anything). This skill is meeting-booking specifically; qualification fields exist but the goal is the call, not the data. +- `funnel-flow-architecture` is broader funnel architecture. This skill is the scheduler specifically. +- `lead-magnet-design` is different commitment level. Magnets earn an email; bookings earn time. +- `scheduler-and-booking-design` (this skill) is the qualification, availability, routing, prep automation, and follow-up sequencing for meetings. +- `pm-spec-writing` is the spec for engineers building the scheduler. + +The audience: growth marketers, product marketers, marketing operations leads, sales operations leads, agencies running booking optimization for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); broader funnel orchestration (covered by `funnel-flow-architecture`); the engineering implementation; specific Calendly/Cal.com/Chili Piper/SavvyCal platform configurations (those stay implementation-side). + +--- + +## The booking-flow decision: scheduler vs forms vs sales-pipeline tools + +Before designing the scheduler, decide whether a scheduler is the right tool. + +Schedulers earn investment when: + +- The conversion goal is a meeting (demo, sales call, consultation). Email-only conversions do not need a scheduler. +- The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. +- The team has enough sales or success capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. +- The team can support qualification logic and routing. Without these, a generic booking link is the result. + +Schedulers do NOT earn investment when: + +- The conversion goal is a download or signup. Use forms or magnet flows. +- The audience volume is too low for routing logic. A handful of bookings per month does not need infrastructure. +- The team's capacity is variable and routing cannot reflect that. Scheduling without capacity awareness produces no-shows on both sides. +- A simpler contact form would serve the same purpose. + +The decision is not "should we have a scheduler"; it is "is the scheduler the right next investment for this audience and goal." + +Detail in [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md). + +--- + +## Any-time-friction vs interrogation-gate vs qualified-fast-path + +The keystone framing. + +Any-time-friction. Generic booking link with no qualification, no context capture. Reps show up to calls cold; they spend the first 10 minutes asking the same qualification questions the form should have captured. Conversion stays at the rate of unqualified raw demos. Cost: sales capacity used inefficiently; high-fit leads get the same experience as low-fit leads; downstream conversion suffers. + +Interrogation-gate. Qualification form with 12 fields before the user can book. Drop-off at the form approaches 90 percent. The qualification works for the leads who survive but the system loses everyone else. Cost: high-fit leads who would have converted abandon at the form; conversion rate is poor even though the post-form leads are well-qualified. + +Qualified-fast-path. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads see SDRs or are routed to async), prep automation that briefs the rep before the call. Cost: design effort upfront is significant; conversion plus downstream call quality both improve meaningfully. + +The litmus test. Does the rep arrive at the call already knowing the prospect's situation? Did the prospect feel respected by the booking experience? If yes to both, qualified-fast-path. If the rep starts cold, any-time-friction. If the prospect dropped at the form, interrogation-gate. + +--- + +## Qualification field design + +Which fields earn their place; which create friction. + +The principle. Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +Strong qualification fields. + +- Company size or team size. Routes to the right rep tier; enables enterprise vs SMB tracking. +- Use case or primary goal. Lets the rep prepare for the conversation that matches. +- Current solution or stack. Tells the rep where the prospect is starting. +- Timeline or urgency. Routes to active-pipeline vs nurture. +- Role or job function. Lets the rep tailor framing. + +Weak qualification fields. + +- Phone number (often unnecessary if email and meeting time are captured). +- Generic comments box (free-text; rarely informs prep). +- Marketing data not used in the call (industry codes, lead-source detail). +- Demographic data unrelated to the call (gender, age). + +The five-field rule. Most production schedulers work well with 3-5 qualification fields. More than 5 starts producing interrogation-gate dynamics. Less than 3 does not give the rep useful prep context. + +Detail in [`references/qualification-field-design.md`](references/qualification-field-design.md). + +--- + +## Availability logic + +Round-robin, weighted by fit, calendar integration. + +Pattern A: Pure round-robin. Bookings cycle through available reps in order. + +When to use. Simple distribution; small teams. + +Strengths. Even distribution; simple logic. + +Weaknesses. Does not match high-fit leads to senior reps; does not load-balance based on capacity. + +Pattern B: Weighted round-robin. Bookings cycle but weighted by rep performance, capacity, or specialty. + +When to use. Teams with rep specialization; teams where capacity differs. + +Pattern C: Fit-based routing. High-fit leads (large company, high urgency) route to senior reps; lower-fit leads route to SDRs or async resources. + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +Pattern D: Hybrid. Combines patterns. Fit-based routing for top tier; round-robin within tier. + +When to use. Most production teams. + +The match-to-rep discipline. The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +Detail in [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md). + +--- + +## Routing patterns + +Different reps for different lead types. + +By company size. SMB to SDRs, mid-market to AEs, enterprise to senior AEs. + +By use case. Different specialists for different product use cases. + +By geography. Different reps for different time zones or regions. + +By language. Native-language reps for non-English-primary leads. + +By account ownership (B2B). If the lead's company is already a customer or prospect of an AE, route to that AE. + +The unrouted lead. Some leads do not fit obvious routing. Default rule needed: round-robin or specific catchall. + +Detail in [`references/routing-patterns.md`](references/routing-patterns.md). + +--- + +## Prep automation + +Briefing the rep before the call. + +The principle. The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused. + +Prep automation patterns. + +- CRM enrichment. Qualification data populates the CRM record; rep sees it in their pre-call review. +- Calendar invite enrichment. Qualification data appears in the meeting invite description; rep sees it on their calendar. +- Slack or email brief. Pre-call brief sent to the rep with synthesized prospect info. +- Account research. Qualification data triggers automated research (company size verification, recent news). + +Strong prep automation. The rep arrives at the call already knowing: who the prospect is, what they are trying to accomplish, what they are using today, when they need a solution. + +Weak prep automation. The rep has the qualification data but it is buried in a CRM field nobody opens. The rep starts the call cold despite the data. + +Detail in [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md). + +--- + +## Confirmation and reminder sequences + +The communications around the booking. + +Booking confirmation. Sent immediately after booking. Confirms time; restates context; sets expectations. + +Pre-meeting reminder. Sent 24 hours and/or 1 hour before. Reduces no-shows. + +Post-meeting follow-up. Sent within hours of the call. Recap; next steps; resources. + +Reschedule and no-show flows. Different flows for different outcomes. + +The reminder discipline. Reminders are useful; over-reminding is friction. Two reminders (24-hour and 1-hour) is typical. + +Detail in [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md). + +--- + +## Reschedule and no-show handling + +What happens when meetings do not go to plan. + +Reschedule patterns. + +- Easy self-serve reschedule (no friction). +- Reschedule preserves qualification data. +- Reschedule notifies the rep proactively. + +No-show patterns. + +- Auto-detect (rep reports no-show; or system detects unattended meeting). +- Follow-up to the prospect (gentle; not punitive). +- Re-engagement sequence (one or two attempts to rebook). +- Eventual deactivation (do not pursue forever). + +The respect-the-no principle. Prospects who no-show twice often do not want the meeting. Multiple aggressive reschedule attempts feel like pressure. + +Detail in [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md). + +- "Booking conversion is high; demo conversion to sale is low." Qualification too thin; cold demos do not convert. +- "Booking conversion is low; demo conversion to sale is high." Interrogation-gate; qualification scares off would-be buyers. +- "Sales says many bookings come from wrong-fit leads." Routing logic not connecting qualification to rep tier. +- "No-show rate is over 30 percent." Reminder sequence broken; or commitment friction at booking too low. +- "Reps complain they get no context before calls." Prep automation broken; data captured but not delivered to rep. +- "Calendar integration breaks every few weeks." Brittle integration; or rep calendar permissions changing. +- "Mobile booking conversion is half of desktop." Mobile UX issue. +- "Booking link gets shared by reps; routing logic bypassed." Generic link in use alongside structured flow; bypass undermines routing. +- "Round-robin produces uneven workload." Reps with different capacity treated equally. + +--- + +## The framework: 12 considerations for scheduler and booking design + +When designing or auditing a scheduler, walk these 12 considerations. + +1. The booking-flow decision. Is a scheduler the right tool, or a form / sales-pipeline tool? +2. Qualified-fast-path, not any-time-friction or interrogation-gate. Just enough qualification to set up the call well. +3. Qualification fields earn their place. 3-5 fields; each routes or preps. +4. Availability logic matches team structure. Round-robin, weighted, fit-based, or hybrid. +5. Routing connects qualification to rep tier. High-fit leads to senior reps. +6. Prep automation delivers data to reps. CRM enrichment, calendar invite, Slack brief. +7. Confirmation and reminders reduce no-shows. 24-hour and 1-hour typical. +8. Reschedule is friction-low. Self-serve; preserves data. +9. No-show flow honest. Re-engagement attempts limited; respect non-response. +10. Mobile parity. Booking works on the devices the audience uses. +11. Conversion to sale as success metric. Not just booking rate; downstream call-to-sale conversion. +12. Maintenance discipline. Routing rules updated as team changes; quarterly audit. + +The output of the framework is a scheduler that earns the booking by earning a better call, with conversion that compounds because the calls themselves are better. + +--- + +## Reference files + +- [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md) - When schedulers earn the build vs when forms or sales-pipeline tools serve. +- [`references/qualification-field-design.md`](references/qualification-field-design.md) - Strong and weak qualification fields. The five-field rule. +- [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md) - Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. +- [`references/routing-patterns.md`](references/routing-patterns.md) - By size, use case, geography, language, account ownership. Unrouted-lead default. +- [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md) - CRM enrichment, calendar invite, Slack brief, account research. +- [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md) - Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. +- [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md) - Reschedule patterns, no-show patterns, respect-the-no principle. +- [`references/scheduler-anti-patterns.md`](references/scheduler-anti-patterns.md) - The patterns that look like schedulers but degrade conversion. +- [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: schedulers earn the booking when they earn the better call + +The schedulers that work as compounding assets are the ones that produce better calls. Not just more bookings. Calls where the rep arrives prepared; the prospect feels respected; the conversation moves faster because qualification was already done. Conversion compounds because the calls themselves convert better. + +That is the bar. Below the bar are any-time-friction (cold demos, conversion suffers) and interrogation-gate (90 percent abandon at the form). Above the bar are qualified-fast-path schedulers where qualification, availability, routing, prep automation, and follow-up sequencing combine into a system that earns the booking and the call. + +The discipline is in the design choices. The decision to use a scheduler at all. The qualification fields that earn their place. The availability logic that matches lead to rep. The routing that respects rep tier and capacity. The prep automation that delivers context to reps before the call. The reminder cadence that reduces no-shows without becoming spam. The reschedule and no-show handling that respects the prospect. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md new file mode 100644 index 0000000..a2c9192 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/availability-logic-patterns.md @@ -0,0 +1,272 @@ +# Availability logic patterns + +Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. + +How the scheduler decides which rep gets which booking. Done well, availability logic distributes load while matching high-fit leads to senior reps; done poorly, leads land on the wrong reps and conversion suffers. + +--- + +## The match-to-rep principle + +The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +The win. A high-fit enterprise lead (large company, urgent timeline) sees availability for senior AEs. Low-fit lead (small team, exploring) sees availability for SDRs. Each lead gets the right call. + +The fail. Same scheduler with pure round-robin. Enterprise lead lands on an SDR; SDR is unprepared; conversion drops. + +The discipline. Routing is not separate from qualification; the two are coupled. + +--- + +## Pattern A: Pure round-robin + +Bookings cycle through available reps in order. + +How it works. + +- Available reps in the queue. +- Each booking goes to the next rep. +- Cycle continues. + +Strengths. + +- Even distribution. +- Simple logic. +- Easy to explain to the team. + +Weaknesses. + +- Does not match high-fit leads to senior reps. +- Does not load-balance based on capacity. +- Does not account for rep specialization. + +When to use. Small teams; reps are interchangeable; volume is low. + +--- + +## Pattern B: Weighted round-robin + +Bookings cycle but weighted by rep performance, capacity, or specialty. + +How it works. + +- Each rep has a weight (performance score, capacity, etc.). +- Distribution skews toward higher-weighted reps. +- Still distributes; just unevenly. + +Strengths. + +- Higher-performing reps get more bookings. +- Capacity differences accommodated. + +Weaknesses. + +- Lower-performing reps get fewer learning opportunities. +- Weighting must be maintained. + +When to use. Teams with significant rep performance differences; teams where capacity differs. + +--- + +## Pattern C: Fit-based routing + +High-fit leads route to senior reps; lower-fit leads route to SDRs or async resources. + +How it works. + +- Qualification fields determine fit score. +- High-fit leads see availability for senior reps only. +- Lower-fit leads see availability for SDRs. + +Strengths. + +- Senior reps focus on high-value conversations. +- SDRs handle qualification and nurture. +- Resource allocation matches lead value. + +Weaknesses. + +- Requires clear fit signals from qualification. +- May produce uneven workload (senior reps light, SDRs heavy). + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +--- + +## Pattern D: Specialty-based routing + +Bookings route to reps with specific expertise. + +How it works. + +- Qualification captures use case or industry. +- Bookings route to the rep with matching specialty. + +Strengths. + +- Rep is genuinely prepared for the specific conversation. +- Higher conversion when specialty matches. + +Weaknesses. + +- Specialist reps can become bottlenecks. +- Requires per-rep specialty tagging. + +When to use. Products with multiple distinct use cases or verticals. + +--- + +## Pattern E: Account-ownership routing (B2B) + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +How it works. + +- Qualification or domain matching detects existing-account leads. +- Bookings route to the AE who owns the account. +- Override default routing. + +Strengths. + +- Account owner has context. +- Avoids confusion of multiple reps on the same account. + +Weaknesses. + +- Requires CRM integration to detect ownership. +- Account ownership must be current. + +When to use. B2B teams with account-ownership models. + +--- + +## Pattern F: Hybrid + +Combining patterns. Most production teams use hybrid. + +Common combinations. + +- Account-ownership routing first (existing accounts to AEs). +- Then fit-based routing (high-fit new leads to senior AEs). +- Then specialty-based routing within tier. +- Then round-robin within remaining pool. + +Strengths. + +- Handles common cases. +- Routes lead to best-matched rep. + +Weaknesses. + +- More complex to maintain. +- More edge cases to handle. + +When to use. Mature production teams with multi-tier sales motion. + +--- + +## Calendar integration + +How availability connects to actual calendars. + +Direct calendar integration. Scheduler reads rep calendars; shows actual availability. + +Strengths. No double-booking; reflects reality. + +Weaknesses. Requires calendar permissions; integration brittle. + +Office hours definition. Reps define availability windows; scheduler shows those. + +Strengths. Simpler integration; no calendar permissions needed. + +Weaknesses. Manual maintenance; reps may forget to update. + +Hybrid. Scheduler uses office hours plus calendar busy/free for fine-grain. + +Strengths. Resilient to integration issues. + +Weaknesses. More complex. + +--- + +## Buffer time + +Time between meetings. + +Why it matters. Back-to-back meetings produce rushed reps and late starts. Buffer protects rep effectiveness. + +Common buffers. 10-15 minutes between meetings. + +The discipline. Buffer should be in the calendar logic, not optional. + +--- + +## Capacity caps + +How many meetings per day per rep. + +Why caps matter. Reps booked solid produce poor calls; quality drops; conversion suffers. + +Common caps. 3-5 demos per day per rep typical for B2B SaaS. + +The discipline. Caps respect rep effectiveness, not just calendar availability. + +--- + +## Time zone handling + +The scheduler shows availability in the prospect's time zone. + +The principle. Display in prospect's time zone; reps see in their own. + +Common patterns. + +- Auto-detect from browser; show prospect that detection. +- Allow manual override. +- Display rep's time zone for clarity ("PT" badge). + +Anti-pattern. Showing all times in rep's time zone; prospect has to convert mentally. + +--- + +## Out-of-office and holiday handling + +Real life intervenes. + +Patterns. + +- Calendar integration handles vacation as busy time. +- Manual office-hours updates handle planned absences. +- Holiday calendars block company-wide closures. + +The discipline. Out-of-office should be respected automatically; otherwise no-shows happen. + +--- + +## Common availability failures + +Pure round-robin for tiered teams. High-fit leads land on junior reps. + +No capacity caps. Reps overbooked; quality drops. + +No buffer. Meetings run late; reps are stressed. + +Time zone confusion. Prospect sees rep's time zone; bookings happen at wrong times. + +Stale rep weights. Weighted round-robin uses last-quarter performance; recent changes ignored. + +Specialty routing without specialty data. Specialty-based routing requires per-rep tagging; missing tags route incorrectly. + +Account-ownership not detected. Existing-account lead bounces around between reps. + +Calendar integration broken. Double-bookings happen; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The match-to-rep principle. Patterns A through F (round-robin, weighted, fit-based, specialty, account-ownership, hybrid). Calendar integration. Buffer time. Capacity caps. Time zone handling. Out-of-office and holiday handling. Common failures. + +## Implementation choices that stay internal + +Specific routing logic for specific teams. Specific weights and caps. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md new file mode 100644 index 0000000..be02c42 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/common-scheduler-failures.md @@ -0,0 +1,179 @@ +# Common scheduler failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Booking conversion is high; demo conversion to sale is low." + +The diagnosis. Qualification too thin; cold demos do not convert. + +The cure. Add 3-5 strategic qualification fields. Detail in `references/qualification-field-design.md`. + +--- + +## "Booking conversion is low; demo conversion to sale is high." + +The diagnosis. Interrogation-gate; qualification scares off would-be buyers. + +The cure. Cut qualification to 3-5 fields. Defer non-essential questions to in-call. + +--- + +## "Sales says many bookings come from wrong-fit leads." + +The diagnosis. Routing logic not connecting qualification to rep tier. + +The cure. Add fit-based routing. Detail in `references/routing-patterns.md`. + +--- + +## "No-show rate is over 30 percent." + +The diagnosis. Reminder sequence broken; or commitment friction at booking too low. + +The cure. Audit reminder cadence. Strengthen pre-meeting communications. Detail in `references/reminder-sequence-patterns.md`. + +--- + +## "Reps complain they get no context before calls." + +The diagnosis. Prep automation broken; data captured but not delivered. + +The cure. CRM enrichment, calendar invite enrichment, Slack brief. Detail in `references/prep-automation-patterns.md`. + +--- + +## "Calendar integration breaks every few weeks." + +The diagnosis. Brittle integration; or rep calendar permissions changing. + +The cure. Monitor integration; fix permissions; have a manual fallback for downtime. + +--- + +## "Mobile booking conversion is half of desktop." + +The diagnosis. Mobile UX issue. + +The cure. Mobile-first design and testing. + +--- + +## "Booking link gets shared by reps; routing logic bypassed." + +The diagnosis. Generic link in use alongside structured flow. + +The cure. Disable generic links. Train reps; provide rep-specific structured links if needed. + +--- + +## "Round-robin produces uneven workload." + +The diagnosis. Reps with different capacity treated equally. + +The cure. Weighted round-robin or capacity-aware routing. + +--- + +## "Time zone errors cause no-shows." + +The diagnosis. Time zone display unclear or auto-detection wrong. + +The cure. Display time zone clearly at booking and in invites. Auto-detect prospect time zone; allow override. + +--- + +## "Reps reschedule manually frequently." + +The diagnosis. Routing produces wrong-fit bookings; reps fix manually. + +The cure. Audit routing logic; fix the source of the wrong-fit bookings. + +--- + +## "Conversion was strong; quality dropped after sales team change." + +The diagnosis. New rep tier or specialization mix; routing not updated. + +The cure. Routing rules updated as team changes. Quarterly review. + +--- + +## "We added more qualification fields; conversion dropped." + +The diagnosis. Crossed the five-field threshold. + +The cure. Cut back. Five-field rule from `references/qualification-field-design.md`. + +--- + +## "Some segments convert; others do not." + +The diagnosis. Single scheduler treats all segments the same. + +The cure. Per-segment qualification or routing. Different segments may need different schedulers. + +--- + +## "Schedulers work for direct traffic; partner-sourced leads convert poorly." + +The diagnosis. Partner-sourced leads have different fit profile; routing or qualification not adapted. + +The cure. Source-based routing. Partner leads may need different rep tier or different prep. + +--- + +## "We tried different reminder cadences; no-shows did not move." + +The diagnosis. No-show may not be reminder-driven. Could be commitment friction at booking, time zone errors, or audience mismatch. + +The cure. Test other variables. Audit booking commitment level, time zone clarity, audience-fit. + +--- + +## "Sales says enterprise prospects skip the scheduler and email instead." + +The diagnosis. Enterprise audiences sometimes want personal contact rather than self-serve booking. + +The cure. Offer a "talk to sales" alternative for enterprise leads. Hybrid approach. + +--- + +## "Conversion dropped after we updated the booking flow." + +The diagnosis. Specific change introduced friction. + +The cure. Compare metrics pre- and post-change. Roll back if necessary; isolate the issue. + +--- + +## "Reschedule flow loses qualification data." + +The diagnosis. Reschedule treated as new booking; data not preserved. + +The cure. Reschedule preserves qualification. Detail in `references/reschedule-and-no-show-handling.md`. + +--- + +## The pattern across failures + +Most scheduler failures fall into one of three patterns. + +Pattern 1: Qualification miscalibrated. Any-time-friction, interrogation-gate, or wrong fields. The fix is calibrating qualification to the team's needs. + +Pattern 2: Routing or prep miscalibrated. Wrong-rep-tier, no-prep-automation, broken integrations. The fix is connecting qualification to rep workflow. + +Pattern 3: Communication miscalibrated. Aggressive reminders, brittle no-show flows, missing reschedule paths. The fix is gentle, useful communication. + +The metric pattern: scheduler failures often look fine on booking conversion alone. The signal is in demo-to-sale conversion, no-show rates, rep prep quality. Programs that track only booking rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (qualification, routing/prep, communication). The principle that booking rate alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md new file mode 100644 index 0000000..fe9f876 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/prep-automation-patterns.md @@ -0,0 +1,247 @@ +# Prep automation patterns + +CRM enrichment, calendar invite, Slack brief, account research. + +The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused and the rep starts the call cold despite the data being captured. + +--- + +## The data-reaches-rep principle + +Prep automation closes the loop between qualification capture and rep readiness. + +The win. Prospect books; qualification data populates the CRM record, appears in the calendar invite, and triggers a brief Slack message to the rep with synthesized prep notes. The rep arrives at the call already knowing the prospect's situation. + +The fail. Qualification data captured; sits in a database; rep does not see it until they search for it. Most reps do not search; they start the call cold. + +The discipline. Capture qualification AND deliver it to the rep where they will see it. + +--- + +## Pattern A: CRM enrichment + +Qualification data populates the CRM record. + +How it works. + +- Booking submission writes to CRM (Salesforce, HubSpot, etc.). +- Fields populate the lead/contact record. +- Rep sees the data when they review the lead. + +Strengths. + +- Single source of truth. +- Fits existing rep workflow (reps already check CRM). + +Weaknesses. + +- Reps may not check CRM before every call. +- CRM custom fields require setup. + +When to use. Default; baseline for any prep automation. + +--- + +## Pattern B: Calendar invite enrichment + +Qualification data appears in the meeting invite description. + +How it works. + +- When the meeting is created, the invite description includes the qualification data. +- Rep sees it on their calendar; visible at-a-glance. + +Strengths. + +- Rep cannot miss it; calendar is the moment of action. +- Works regardless of CRM access. + +Weaknesses. + +- Calendar invite descriptions can be long; reps may not read fully. +- Updates after booking do not appear in the invite. + +When to use. Strong complement to CRM enrichment. + +--- + +## Pattern C: Slack or email brief + +Pre-call brief sent to the rep with synthesized prospect info. + +How it works. + +- Booking triggers a Slack message or email to the rep. +- Brief includes qualification data plus context (account history, company info, prior interactions). +- Often delivered hours or a day before the call. + +Strengths. + +- Active delivery; rep receives it without searching. +- Can include synthesized context (CRM history, news, prior touches). + +Weaknesses. + +- Slack noise can dilute brief; reps may scroll past. +- Email may sit unread. + +When to use. When the team's workflow includes Slack or email-driven prep. + +--- + +## Pattern D: Account research + +Qualification data triggers automated research. + +How it works. + +- Booking triggers automated lookup (company size verification via Clearbit/ZoomInfo, recent news search, social media check). +- Research results appended to CRM or prep brief. + +Strengths. + +- Rep gets richer context than qualification alone provides. +- Catches data prospects did not provide. + +Weaknesses. + +- Research tools cost. +- Can miss for small companies or international. + +When to use. Enterprise sales motion; high-value calls warrant research investment. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production teams use multiple. + +Common combination. + +- CRM enrichment as baseline. +- Calendar invite enrichment for at-a-glance visibility. +- Slack brief 24 hours before the call for richer prep. +- Account research for high-fit leads. + +The hybrid produces multiple touchpoints; rep sees prep data wherever they happen to look first. + +--- + +## What to include in prep automation + +The fields that matter to the rep. + +Standard inclusions. + +- Prospect name and role. +- Company name and size. +- Use case or primary goal. +- Current solution. +- Timeline or urgency. +- Source (paid, organic, referral). + +Sometimes useful. + +- Company industry and recent news. +- Prior interactions with the brand. +- LinkedIn profile link. +- Account history (existing customer, prior trial). + +Avoid in prep. + +- Free-text fields the prospect filled with noise. +- Marketing data not relevant to the call (UTM details, lead source granularity). +- Personal data not needed for the call. + +--- + +## Prep timing + +When the brief reaches the rep. + +At-booking. Brief delivered immediately after booking. Rep can prepare any time. + +Day-before. Brief delivered 24 hours before. Forces prep into the rep's workflow. + +Hour-before. Brief delivered 1 hour before. Last-minute prep; useful for back-to-back calls. + +The combined approach. Most teams use at-booking (CRM record) plus day-before (Slack) plus calendar visibility throughout. + +--- + +## Prep brief copy + +What the brief says. + +Strong brief copy. + +- "Sarah Lee, Director of Marketing at [Company], 200-500 employees, evaluating analytics tools to replace [current solution] within 60 days." + +What works. Specific; structured; gives rep enough to prepare. + +Weak brief copy. + +- "New booking from Sarah Lee." + +What fails. No context; rep starts cold despite the data being captured upstream. + +The discipline. Brief should be specific enough that the rep arrives ready. + +--- + +## Prep automation testing + +Verify the loop works. + +Test cases. + +- Booking happens; CRM record created; data populates. +- Booking happens; calendar invite shows the qualification data. +- Booking happens; Slack brief arrives at the right time. +- Edge case: prospect updates booking; prep updates accordingly. + +Production monitoring. If reps consistently arrive at calls cold, prep automation is broken somewhere. + +--- + +## Privacy and consent + +Prep automation involves handling user data. + +The principle. Data captured at booking flows to internal systems for prep. The prospect has implicitly consented to internal use through the booking. + +Limits. + +- Data should not flow to systems unrelated to the booking purpose. +- Account research should respect privacy norms. +- GDPR and other regulations apply. + +--- + +## Common prep automation failures + +No automation. Data captured; reps do not see it. + +CRM enrichment without rep CRM use. Data is in CRM; reps do not check CRM before calls. + +Slack brief lost in noise. Prep brief among 50 other Slack messages; rep misses. + +Calendar invite truncated. Invite description too long; reps see only opening. + +Stale account research. Research data from months ago. + +Brief copy generic. Brief contains data but not synthesized context. + +Updates after booking not propagated. Prospect updates info; prep stays old. + +No testing. Prep loop broken; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The data-reaches-rep principle. Patterns A through E (CRM, calendar, Slack, research, hybrid). What to include in prep. Prep timing. Prep brief copy discipline. Prep automation testing. Privacy and consent. Common failures. + +## Implementation choices that stay internal + +Specific prep configurations for specific teams. Specific Slack templates and CRM custom fields. Specific research tooling. The team's privacy review processes. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md new file mode 100644 index 0000000..ea83e3c --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/qualification-field-design.md @@ -0,0 +1,221 @@ +# Qualification field design + +Strong and weak qualification fields. The five-field rule. + +The fields decide the booking flow's friction and the call's quality. Done well, qualification produces context for the call without scaring off prospects; done poorly, it produces interrogation-gate dynamics. + +--- + +## The earns-its-place principle + +Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +The win. Four fields: company size, role, primary use case, timeline. Each routes or preps. Conversion is high; rep prep is concrete. + +The fail. Twelve fields including industry code, employee count range, marketing source, lead-source detail, gender. Most do not affect routing or prep; conversion drops 70 percent. + +The discipline. Audit each field. Cut fields that do not earn placement. + +--- + +## Strong qualification fields + +Patterns that earn placement. + +Company size or team size. + +Why it works. Routes to the right rep tier (SMB vs mid-market vs enterprise); enables segment tracking; concrete signal of fit. + +Format. Dropdown with bands ("1-10," "11-50," "51-200," "201-1000," "1000+"). + +Use case or primary goal. + +Why it works. Lets the rep prepare for the conversation that matches. + +Format. Dropdown with 5-7 use cases; or short open text if use cases are not enumerable. + +Current solution or stack. + +Why it works. Tells the rep where the prospect is starting; informs migration vs greenfield framing. + +Format. Dropdown of common alternatives plus "other" with text field. + +Timeline or urgency. + +Why it works. Routes to active-pipeline vs nurture; signals urgency to the rep. + +Format. Dropdown ("Within 30 days," "1-3 months," "3-6 months," "Just exploring"). + +Role or job function. + +Why it works. Lets the rep tailor framing; routes to specialist reps if role-aligned. + +Format. Dropdown of common roles; "Other" field for unusual cases. + +--- + +## Weak qualification fields + +Patterns that fail. + +Phone number. + +Why it fails. Often unnecessary if email and meeting time are captured. Reps can request phone in the call. Phone field adds friction without value for the booking itself. + +When to include. If the call is by phone (not video), phone is necessary. + +Generic comments box. + +Why it fails. Free-text rarely informs prep. Most prospects skip; some over-share; few provide useful context. + +When to include. Sparingly; if structured fields cannot capture the necessary context. + +Marketing data not used in the call. + +Why it fails. Industry codes, lead-source detail, etc. add friction without affecting the call's quality. + +When to include. Capture later (post-meeting follow-up form, CRM enrichment) rather than at the booking. + +Demographic data unrelated to the call. + +Why it fails. Gender, age, etc. rarely inform a B2B sales conversation. + +When to include. Almost never. Only if regulatory or product-specific reasons require. + +--- + +## The five-field rule + +Most production schedulers work well with 3-5 qualification fields. + +Why 3-5. + +- 3 fields is the minimum for useful qualification. +- 5 fields is the threshold beyond which drop-off climbs. +- Production data across many SaaS products supports this range. + +Exceptions. + +- Some enterprise sales contexts warrant 5-7 fields because the audience expects qualification. +- Some highly specialized products warrant fewer fields (1-2) because conversion volume matters more. + +The over-five trap. Each additional field beyond 5 reduces conversion meaningfully. The marginal value of field 6 rarely justifies the conversion cost. + +--- + +## Field ordering + +Within the form, the order matters. + +Open with low-friction. Identity fields (name, email) first. Familiar; easy. + +Build to value. Use-case or goal fields next. The prospect engages with what the call will be about. + +Save commitment for later. Timeline or budget fields late. The prospect has invested; harder ask is acceptable. + +End with optional. Comments or "anything else?" at the end if included. The prospect can leave or skip. + +--- + +## Field formats + +How each field captures input. + +Dropdowns. Best for categorical fields. Constrains responses; easy to route on. + +Text fields. For free-form fields (name, email, sometimes use case). + +Sliders. Rarely useful in qualification. + +Yes/No toggles. For binary qualifying questions (e.g., "Do you currently use a CRM?"). + +Conditional fields. Some fields appear based on earlier answers. Use sparingly; complexity adds maintenance. + +--- + +## Field validation + +What to validate. + +Email format. Standard validation; respect plus-aliases and international domains. + +Required vs optional. Mark explicitly. + +Length and character. Don't reject international names or non-Latin characters. + +The validation-strict failure. Validation that rejects valid inputs (international phone formats, plus-sign emails) loses real prospects. + +--- + +## Inferred vs asked fields + +What to ask vs what to infer. + +Ask sparingly. Each field is friction. + +Infer when possible. + +- Lead source: from URL parameters or referrer. +- Company info: from email domain. +- Geography: from IP or browser. +- Timezone: from browser. + +The discipline. If the system can infer a value reliably, do not ask. + +--- + +## Field-level analytics + +Track per-field drop-off. + +Per-field completion rate. Where in the form do prospects abandon? + +Diagnostic uses. + +- Specific field with high abandonment: friction at that field. +- Field rarely completed even by survivors: often signals the field can be cut. +- Specific segment abandons specific fields: segment-specific friction. + +The data informs which fields earn their place over time. + +--- + +## Field maintenance + +Fields decay. + +What decays. + +- Dropdowns with options that no longer match audience. +- Fields the rep team stopped using for prep. +- Fields whose routing logic changed without update. + +Maintenance cadence. Quarterly review of each field. Are reps using the data? Is routing connecting field-to-tier? + +--- + +## Common field failures + +Too many fields. Drop-off at the form. + +Fields not used. Captured but reps do not prep with them. + +Wrong field types. Free text where dropdown would route better. + +Validation too strict. Loses valid prospects. + +No analytics. Cannot tell which fields are working. + +Stale field options. Dropdowns no longer match audience. + +Fields asked that could be inferred. Friction without need. + +--- + +## Methodology-level choices that stay in the public skill + +The earns-its-place principle. Strong qualification fields (5 patterns). Weak qualification fields (4 patterns). The five-field rule. Field ordering. Field formats. Field validation. Inferred vs asked. Field-level analytics. Field maintenance. Common failures. + +## Implementation choices that stay internal + +Specific fields for specific schedulers. Specific dropdown options. Specific tooling for inference. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md new file mode 100644 index 0000000..05b3b4d --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md @@ -0,0 +1,256 @@ +# Reminder sequence patterns + +Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. + +The communications around the booking. Done well, reminders reduce no-shows without becoming spam; done poorly, reminders are either insufficient (no-shows climb) or excessive (prospect resents). + +--- + +## The reduce-no-shows-without-spam principle + +Reminders matter; their volume should be calibrated. + +The win. Confirmation immediately after booking; one reminder 24 hours before; one reminder 1 hour before. Three communications total. No-show rate drops; prospects feel reminded but not nagged. + +The fail. Confirmation; 5-day reminder; 2-day reminder; 1-day reminder; 1-hour reminder; 15-minute reminder. Six communications. Prospects mute the channel; no-shows persist for users who muted. + +The discipline. Reminders earn their place; cumulative volume should be capped. + +--- + +## Pattern A: Booking confirmation + +Sent immediately after booking. + +What it includes. + +- Confirmed time and meeting type. +- Calendar invite attached. +- Brief restate of expectations (e.g., "Looking forward to learning about your X"). +- Reschedule and cancel links. + +Strengths. + +- Immediate; reduces buyer's remorse. +- Sets expectations. +- Provides reschedule path. + +Weaknesses. + +- One-touch communication. + +When to use. Always. + +--- + +## Pattern B: Pre-meeting reminder + +Sent 24 hours and/or 1 hour before. + +24-hour reminder. + +- Useful for users who book days in advance. +- Lets them prepare or reschedule with notice. + +1-hour reminder. + +- Useful for last-minute prep. +- Catches calendar drift. + +Both useful or one only? + +- Most production teams use both. +- For very short booking windows (same-day), 1-hour is enough. +- For longer-lead bookings, 24-hour matters. + +--- + +## Pattern C: Post-meeting follow-up + +Sent within hours of the call. + +What it includes. + +- Brief recap. +- Action items (rep's commitments). +- Resources mentioned in the call. +- Next-step CTA (next meeting, document, trial). + +Strengths. + +- Captures momentum from the call. +- Documents commitments. + +Weaknesses. + +- Requires rep to populate after the call (or rep-side tooling to auto-generate). + +When to use. Sales conversations where next steps matter. + +--- + +## Pattern D: Reschedule prompts + +When the prospect cannot make the meeting. + +What it includes. + +- Easy reschedule link. +- Brief check-in copy ("Need to reschedule? No problem."). + +Strengths. + +- Reduces no-shows; users reschedule rather than ghost. + +Weaknesses. + +- Some users use this to reschedule indefinitely. + +When to use. Always available; not aggressive. + +--- + +## Pattern E: No-show follow-up + +When the prospect does not attend. + +What it includes. + +- Acknowledgment of missed meeting. +- Reschedule link. +- Brief context-restatement. + +Tone. Gentle, not punitive. The prospect may have had a real reason. + +The respect-the-no-show principle. After 1-2 reschedule attempts, accept that the prospect is not engaging. + +--- + +## Reminder timing + +When each communication fires. + +Common cadence. + +- T+0: Confirmation immediately after booking. +- T-24h: Reminder 24 hours before. +- T-1h: Reminder 1 hour before. +- T+15m: Late-arrival check (sometimes). +- T+24h: Post-meeting follow-up. + +The discipline. Each communication earns its place. Drop the ones that do not. + +--- + +## Channel choice + +Which channels to use. + +Email. Default. Reliable; familiar. + +SMS. Higher attention; more friction. Use selectively for high-value bookings. + +In-app notification. If the booking is for a logged-in user, in-app reminders work. + +Slack or Teams. For B2B internal-team meetings. + +The cumulative discipline. Multiple channels for the same reminder is excessive. Pick one channel per reminder. + +--- + +## Reminder copy + +What the reminders say. + +Strong reminder copy. + +- "Looking forward to our call tomorrow at 2 PM PT. Here's what we'll cover: [agenda]." +- "Reminder: 1 hour until our call. Join here: [link]." +- "Thanks for the call today. Here's what we discussed: [recap]." + +What works. Specific; useful; brief. + +Weak reminder copy. + +- "Don't forget your meeting!" +- "Your meeting is in 1 hour." +- "Did you know..." + +What fails. Generic; no value-add; just a notification. + +--- + +## Reminder personalization + +How much to personalize. + +Default personalization. Name; meeting time; rep name. + +Strong personalization. Brief context tied to qualification ("Looking forward to discussing your [use case] situation"). + +Over-personalization. Long personalized paragraphs that read as marketing. + +The discipline. Personalize where it adds value; do not pad with personalization for its own sake. + +--- + +## Reminder analytics + +Track effectiveness. + +Metrics. + +- Open rate per reminder. +- Reschedule rate per reminder. +- No-show rate (cumulative across cadence). +- Cancellation rate. + +Diagnostic uses. + +- Low open rate: subject line weak or channel wrong. +- High reschedule rate after specific reminder: that reminder triggers reconsideration. +- High no-show despite reminders: friction at the meeting itself, not the reminder. + +--- + +## Reminder maintenance + +Reminders decay. + +What decays. + +- Templates with stale rep names or roles. +- Calendar links that broke after platform changes. +- Channel preferences that no longer fit audience. + +Maintenance cadence. Quarterly review of reminder templates and channels. + +--- + +## Common reminder failures + +Too many reminders. Cumulative volume is spam; users mute. + +Too few reminders. No-show rate climbs. + +Generic copy. No value; users dismiss. + +Wrong channel. SMS for an audience that prefers email. + +Stale templates. Rep names from former employees; broken calendar links. + +No post-meeting follow-up. Conversation momentum lost. + +Aggressive no-show follow-up. Multiple reminder attempts after a no-show; respect non-response. + +Personalization padding. Long personalized text that reads as marketing. + +--- + +## Methodology-level choices that stay in the public skill + +The reduce-no-shows-without-spam principle. Patterns A through E (confirmation, pre-meeting, post-meeting, reschedule, no-show). Reminder timing. Channel choice. Reminder copy discipline. Reminder personalization. Reminder analytics. Reminder maintenance. Common failures. + +## Implementation choices that stay internal + +Specific reminder cadences for specific teams. Specific copy in brand voice. Specific channel choices. The team's no-show baselines. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md new file mode 100644 index 0000000..081a420 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md @@ -0,0 +1,241 @@ +# Reschedule and no-show handling + +Reschedule patterns, no-show patterns, respect-the-no principle. + +What happens when meetings do not go to plan. Done well, reschedule and no-show handling protect the relationship and capture re-engagement; done poorly, they punish the prospect for ordinary life events. + +--- + +## The respect-the-no principle + +Prospects who reschedule or no-show often have real reasons. Handling should be gentle, not punitive. + +The win. Prospect no-shows; gentle follow-up offers easy reschedule. Prospect reschedules once; offered again at a new convenient time. After two no-shows, the system stops aggressive pursuit and routes to nurture. + +The fail. Prospect no-shows; system fires three reminder emails over two days; phone call follows; prospect feels harassed. + +The discipline. Acknowledge that life intervenes; offer a path back; do not pressure. + +--- + +## Reschedule patterns + +When prospects need to change the meeting. + +Pattern A: Self-serve reschedule. + +How it works. The booking confirmation includes a reschedule link. Prospect clicks; sees new availability; selects new slot. + +Strengths. No friction; respect for the prospect's time. + +Weaknesses. Some abuse possible (repeated reschedules). + +When to use. Default for most schedulers. + +Pattern B: Reschedule preserves qualification data. + +How it works. Reschedule keeps all the qualification info; rep does not lose context. + +Strengths. Reschedule does not cost prep work. + +Weaknesses. None significant. + +When to use. Always. + +Pattern C: Reschedule notifies the rep. + +How it works. When prospect reschedules, rep gets notified. Original calendar slot freed up. + +Strengths. Rep can use the freed slot. + +Weaknesses. None. + +When to use. Always. + +Pattern D: Reschedule limits. + +How it works. After N reschedules, the system flags the booking for review or routes to nurture. + +Strengths. Prevents abuse. + +Weaknesses. Risks alienating prospects with legitimate scheduling difficulty. + +When to use. Sparingly; usually 3+ reschedules before flagging. + +--- + +## No-show patterns + +When prospects do not attend. + +Detection. + +- Rep reports no-show after the meeting time. +- System detects unattended meeting (if integrated with video platform). +- Manual reports from CS or sales ops. + +Pattern A: Single follow-up. + +How it works. Within 4-24 hours of the no-show, send a single gentle email offering reschedule. + +Strengths. Catches genuine forgetfulness. + +Weaknesses. Single touch may not catch users on vacation. + +When to use. Default. + +Pattern B: Two-touch follow-up. + +How it works. First email immediate. Second email 3-5 days later if no response. + +Strengths. Catches prospects who were genuinely busy. + +Weaknesses. Risks feeling persistent. + +When to use. Higher-value bookings where multi-touch is justified. + +Pattern C: Sales-led recovery. + +How it works. For high-value no-shows, sales rep reaches out personally. + +Strengths. Most engaging; can recover the relationship. + +Weaknesses. Expensive; only viable for high-value accounts. + +When to use. Enterprise no-shows or accounts with strategic value. + +Pattern D: Async route. + +How it works. Send the no-show prospect resources or content rather than another booking attempt. Re-engagement deferred. + +Strengths. Respects the no-show as a signal. + +Weaknesses. May lose prospects who would have rebooked. + +When to use. After 1-2 unsuccessful reschedule attempts. + +--- + +## Reschedule cadence + +How often to retry. + +Single reschedule attempt: offer once; respect non-response. + +Multiple attempts: at most 2 attempts spaced 3-7 days apart. Stop after that. + +No reschedule attempts: for bookings flagged as low-fit; route to nurture. + +The discipline. Each reschedule attempt earns its place. Cumulative attempts become harassment. + +--- + +## When to abandon reschedule + +Some no-shows should be respected as final. + +Signals to stop. + +- Prospect explicitly asked to stop contact. +- Multiple no-shows from same prospect. +- No response to 2 reschedule attempts. +- Email bounced or unsubscribed. + +The respect-the-pattern principle. Multiple no-shows often signal the prospect's needs changed. Continuing pursuit damages the brand. + +--- + +## No-show flow design + +The full sequence. + +T+0 (no-show happens). + +- Rep marks no-show in CRM. +- Free the calendar slot. + +T+4-24h (first follow-up). + +- Email: "Sorry we missed you. Want to reschedule? [Link]." + +T+3-5d (second follow-up if needed). + +- Email: "We're still interested in connecting if your schedule changed. Here's the reschedule link." + +T+10d (final attempt or async route). + +- Send relevant content; surface re-engagement option without pressure. + +T+30d+. + +- Treat as nurture; pursue through other channels (email newsletter, content). + +The cadence respects multiple touchpoints without becoming aggressive. + +--- + +## No-show analytics + +Track patterns. + +Per-segment no-show rate. + +- Different sources, sizes, or use cases may no-show at different rates. + +Per-rep no-show rate. + +- Some reps may correlate with higher no-shows (timing, time zone, prep gaps). + +Reschedule conversion rate. + +- Of rescheduled bookings, what percentage attend. + +Diagnostic uses. + +- High overall no-show: reminder sequence weak or commitment friction at booking too low. +- Specific segment no-shows more: that segment may need different cadence. +- Specific rep no-shows more: their availability or prep may be off. + +--- + +## Time zone and travel mistakes + +Common reasons for no-shows that are not the prospect's fault. + +Prevention. + +- Display time zone clearly at booking. +- Calendar invites include time zone. +- Reminders include time zone. + +The cure for time zone mistakes. Quick reschedule; do not penalize. + +--- + +## Common reschedule and no-show failures + +Aggressive recovery. Multiple touches over short periods; harassment. + +Reschedule limits too tight. Genuine prospects flagged after 2 reschedules; lost. + +Reschedule loses qualification data. Rep loses context on reschedule. + +No reschedule path. Prospect cannot reschedule; ghosts instead. + +No-show no follow-up. Prospect's missed meeting is just lost; could have rebooked. + +Punitive copy. No-show follow-up shames the prospect. + +Time zone confusion. Prospect missed because of time zone error; system blames the prospect. + +Stale reschedule links. Link works at booking; broken later. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-no principle. Reschedule patterns A through D. No-show patterns A through D. Reschedule cadence. When to abandon. No-show flow design. No-show analytics. Time zone considerations. Common failures. + +## Implementation choices that stay internal + +Specific reschedule limits for specific teams. Specific follow-up cadences. Specific copy in brand voice. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md new file mode 100644 index 0000000..fe64b71 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/routing-patterns.md @@ -0,0 +1,235 @@ +# Routing patterns + +By size, use case, geography, language, account ownership. Unrouted-lead default. + +The specific routing rules that translate qualification answers into rep assignments. Done well, routing matches lead to rep cleanly; done poorly, leads bounce around or land on wrong reps. + +--- + +## Routing-by-company-size + +The most common routing axis. + +Pattern. + +- 1-50 employees: SDR or self-serve. +- 51-500 employees: AE. +- 501-2000 employees: senior AE. +- 2000+ employees: enterprise AE. + +Why it works. Different sizes have different sales motions; rep tier should match. + +Failure modes. + +- Size bands set years ago; team scaled; bands no longer right. +- Size data missing or stale. +- Solo founders with backed companies appear "small" but warrant senior treatment. + +--- + +## Routing-by-use-case + +Different specialists for different product use cases. + +Pattern. + +- Use case A: rep with A specialty. +- Use case B: rep with B specialty. +- General use case: any AE. + +Why it works. Specialists arrive with deeper context; conversion higher. + +Failure modes. + +- Specialist becomes bottleneck. +- New use cases without assigned specialist. +- Use case overlap; multiple specialists could fit. + +--- + +## Routing-by-geography + +Different reps for different regions or time zones. + +Pattern. + +- Americas: US-based AEs. +- EMEA: European AEs. +- APAC: APAC AEs. + +Why it works. Time zone alignment; cultural fit; language fit. + +Failure modes. + +- Insufficient coverage in some regions. +- Cross-region accounts confuse routing. +- Geography data missing or wrong. + +--- + +## Routing-by-language + +Native-language reps for non-English-primary leads. + +Pattern. + +- English-primary: US/UK AEs. +- Spanish-primary: Spanish-speaking AEs. +- Etc. + +Why it works. Native-language conversation produces better calls. + +Failure modes. + +- Incomplete language coverage. +- Multi-language leads bounce. +- Language inferred wrong from email or location. + +--- + +## Routing-by-account-ownership + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +Pattern. + +- Detect domain match against CRM. +- If match, route to AE who owns the account. +- If no match, default routing. + +Why it works. Account owner has context; avoids confusion. + +Failure modes. + +- Domain detection misses subsidiaries or aliases. +- Account ownership stale (former AE). +- New lead from existing account but for unrelated use case. + +--- + +## Routing-by-source + +Different reps for different lead sources (paid, organic, partner, referral). + +Pattern. + +- Partner-sourced leads: partner-channel AE. +- Paid-sourced leads: marketing-aligned AEs. +- Organic-sourced: general AEs. + +Why it works. Different sources signal different commitment; specialists handle differently. + +Failure modes. + +- Source data missing or attribution wrong. +- Paid traffic includes high-fit leads who would have come organically. + +--- + +## Routing-by-tier + +Combining size, use case, and other signals into a tier score. + +Pattern. + +- Lead score 80-100: senior AE. +- Lead score 50-79: AE. +- Lead score 0-49: SDR or async. + +Why it works. Single score combines multiple signals. + +Failure modes. + +- Score model out of date. +- Score thresholds wrong for current capacity. +- Score data incomplete; defaults dominate. + +--- + +## The unrouted-lead default + +Some leads do not fit obvious routing. + +Patterns for default. + +- Round-robin among all available reps. Simple. +- Catchall AE. One rep gets all unrouted leads. +- Async or self-serve. Lead goes to a self-serve resource if no obvious rep. + +The discipline. Default rule should be explicit. Unrouted leads should not silently fail or bounce. + +--- + +## Routing transparency + +Prospect-side vs rep-side visibility. + +Prospect-side. Generally, prospects do not see routing logic. They see a calendar with available times. + +Rep-side. Reps should see why they were assigned (lead score, fit signals). Helps with prep. + +Anti-pattern. Routing happens silently; rep does not know what made this lead route to them. + +--- + +## Routing changes and team transitions + +When the team changes, routing must follow. + +Common transitions. + +- Rep leaves; their accounts and routing reassign. +- New rep hires; routing weights adjust. +- Tier restructure (rep promoted from SDR to AE). +- Specialty changes. + +The maintenance discipline. Routing rules update as team changes. Stale routing can route leads to absent reps. + +--- + +## Routing analytics + +Track routing effectiveness. + +Metrics. + +- Per-rep booking volume. +- Per-rep conversion (booking-to-sale). +- Per-route conversion (route x → sale rate). +- Routing override rate (manual reassignments). + +Diagnostic uses. + +- Per-rep volume uneven without reason: routing logic skewing. +- Per-route conversion uneven: routing matching wrong. +- High override rate: routing logic not capturing real fit. + +--- + +## Common routing failures + +Routing data missing. Qualification did not capture; routing defaults dominate. + +Stale routing rules. Team changed; rules did not. + +Stale rep weights. Performance scores from quarters ago. + +Account-ownership detection wrong. Subsidiary leads route to unfit AE. + +Specialty routing without specialty data. Specialty-based routing requires tagging; tags miss. + +Default rule unclear. Unrouted leads silently fail. + +Routing override frequent. Reps reassign manually; routing logic does not match reality. + +Round-robin for tiered team. High-fit leads land on junior reps. + +--- + +## Methodology-level choices that stay in the public skill + +Routing patterns by size, use case, geography, language, account ownership, source, tier. The unrouted-lead default. Routing transparency. Team transitions. Routing analytics. Common failures. + +## Implementation choices that stay internal + +Specific routing rules for specific teams. Specific size bands and tier thresholds. Specific tooling. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md new file mode 100644 index 0000000..6b3c225 --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md @@ -0,0 +1,209 @@ +# Scheduler anti-patterns + +The patterns that look like schedulers but degrade conversion. Anti-patterns are easy to ship; the cost shows up in booking conversion, downstream call quality, and brand reputation. + +--- + +## The any-time-friction scheduler + +The pattern. Generic booking link with no qualification. + +The signal. Reps show up cold; downstream demo-to-sale conversion poor. + +The cost. Sales capacity used inefficiently; call quality suffers. + +The cure. Add 3-5 qualification fields; route to right rep tier; deliver prep to reps. + +--- + +## The interrogation-gate scheduler + +The pattern. 12-field qualification form before booking. + +The signal. 90 percent drop-off at the form. + +The cost. Lose conversions from would-be buyers; only the most committed survive the form. + +The cure. Cut to 3-5 fields; defer additional questions to in-call or post-meeting. + +--- + +## The wrong-rep-tier scheduler + +The pattern. Round-robin routing for tiered team. + +The signal. Enterprise leads land on SDRs; SDRs unprepared; conversion drops. + +The cost. High-value leads get junior reps; senior reps underutilized. + +The cure. Fit-based routing tied to qualification. + +--- + +## The no-prep-automation scheduler + +The pattern. Qualification captured but not delivered to reps. + +The signal. Reps start calls cold despite qualification data existing. + +The cost. Qualification work wasted; cold-call dynamics return. + +The cure. CRM enrichment, calendar invite enrichment, Slack briefs. + +--- + +## The no-buffer scheduler + +The pattern. Back-to-back meetings without buffer time. + +The signal. Reps run late; calls feel rushed; quality drops. + +The cost. Reps stressed; calls poorer; conversion suffers. + +The cure. 10-15 minute buffer between meetings. + +--- + +## The no-capacity-cap scheduler + +The pattern. Reps booked solid all day every day. + +The signal. Quality drops; rep burnout. + +The cost. Calls that book are lower quality; reps eventually leave. + +The cure. Cap meetings per day per rep (3-5 typical). + +--- + +## The time-zone-confused scheduler + +The pattern. Times shown in rep's time zone; prospect has to convert mentally. + +The signal. Wrong-time bookings; no-shows from time zone errors. + +The cost. Prospects miss meetings; assume their fault. + +The cure. Auto-detect prospect time zone; display explicitly. + +--- + +## The aggressive-reminder scheduler + +The pattern. Multiple reminders per booking (5+ touchpoints). + +The signal. Prospects mute or unsubscribe; reminder effectiveness drops. + +The cost. Reminders trained to be ignored; no-shows persist. + +The cure. Two reminders typical (24-hour, 1-hour). Cap cumulative volume. + +--- + +## The aggressive-no-show-recovery scheduler + +The pattern. Multiple reschedule attempts over short period. + +The signal. Brand earns harassment reputation; recovery rate drops. + +The cure. One-to-two reschedule attempts max; respect non-response. + +--- + +## The aggressive-cancellation-prevention scheduler + +The pattern. Cancellation requires multi-step or contact with sales. + +The signal. Public complaints; trust damage. + +The cost. Reputation harm; sometimes regulatory issues. + +The cure. Self-serve cancellation; one click. + +--- + +## The unmaintained scheduler + +The pattern. Routing rules from years ago; team changed; rules did not. + +The signal. Leads route to absent reps; bookings sit unread. + +The cure. Quarterly maintenance. Team transitions trigger routing updates. + +--- + +## The mobile-broken scheduler + +The pattern. Booking flow works on desktop; breaks on mobile. + +The signal. Mobile conversion half of desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. + +--- + +## The double-booking scheduler + +The pattern. Calendar integration broken; multiple bookings for same time. + +The signal. Reps and prospects both arrive; one waits or leaves. + +The cost. Rep frustration; prospect confusion; brand damage. + +The cure. Calendar integration tested. Buffer time. Conflict detection. + +--- + +## The shared-link bypass scheduler + +The pattern. Reps share generic booking links alongside structured flow. + +The signal. Routing logic bypassed; cold demos return. + +The cost. Investment in qualification and routing partially undone. + +The cure. Disable generic links. Train reps to use structured links. + +--- + +## The integration-brittle scheduler + +The pattern. Calendar, CRM, or video integration breaks frequently. + +The signal. Reps complain about manual workarounds. + +The cost. Operational friction; data inconsistency. + +The cure. Stable integrations; monitoring; rollback plans. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of scheduler portfolio. + +Audit questions. + +- Is qualification calibrated (anti-pattern check: any-time-friction, interrogation-gate)? +- Does routing match team tier (anti-pattern check: wrong-rep-tier)? +- Does prep automation deliver (anti-pattern check: no-prep-automation)? +- Is calendar logic sound (anti-pattern check: no-buffer, no-capacity-cap, double-booking)? +- Are reminders calibrated (anti-pattern check: aggressive-reminder)? +- Is no-show recovery respectful (anti-pattern check: aggressive-no-show-recovery)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does the system work on mobile (anti-pattern check: mobile-broken)? +- Are integrations stable (anti-pattern check: integration-brittle)? + +The retire decision. Anti-pattern schedulers warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md new file mode 100644 index 0000000..62327fe --- /dev/null +++ b/dist/pi/.agents/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md @@ -0,0 +1,175 @@ +# Scheduler decision criteria + +When schedulers earn the build vs when forms or sales-pipeline tools serve. + +A scheduler is meaningful work. Qualification logic, availability rules, routing, prep automation, follow-up sequences, ongoing maintenance. The scheduler earns this investment only when specific conditions are present. + +--- + +## When schedulers earn the build + +Five conditions that, when present, make a scheduler a strong investment. + +The conversion goal is a meeting. Demo, sales call, consultation. Email-only or trial-signup conversions do not need a scheduler. + +The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. Top-of-funnel awareness audiences are usually not ready; consideration-stage audiences often are. + +The team has enough capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. Reps booked solid for two weeks lose conversions to faster competitors. + +The team can support qualification logic and routing. Without these, a generic booking link is the result. Generic booking links produce cold demos. + +The success metric is defined. Booking conversion, demo-to-sale conversion, no-show rate, call quality (often measured via rep self-reports). Without the success metric, evaluation is impossible. + +When all five are present, a scheduler is strong investment. When two or fewer are present, simpler tools (contact forms, sales pipeline outreach) often serve better. + +--- + +## When schedulers do NOT earn the build + +Funnels where the scheduler is the wrong tool. + +The conversion goal is a download or signup. Use forms (covered by `multi-step-form-design`) or magnet flows (covered by `lead-magnet-design`). + +The audience volume is too low. A handful of bookings per month does not need routing infrastructure; a contact form may serve better. + +The team's capacity is variable and routing cannot reflect it. Scheduling without capacity awareness produces booked-too-tight or booked-too-loose patterns; both fail. + +A simpler contact form would serve. Inbound leads where sales does outbound contact may not need a scheduler; the prospect just provides info; the rep reaches out. + +The audience prefers async communication. Some audiences (technical buyers, asynchronous teams) prefer email or document exchange to scheduled calls. + +The honest assessment matters. Schedulers are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Schedulers vs forms + +Both capture lead info; they differ in commitment. + +Form strengths. + +- Lower commitment from the prospect. +- Higher top-of-funnel volume. +- Suitable for any conversion type (download, demo request, contact). + +Form weaknesses. + +- No automatic time commitment. +- Requires sales follow-up to schedule. +- Wait time between form submission and meeting. + +Scheduler strengths. + +- Time committed at booking; no scheduling delay. +- Higher prospect commitment signal. +- Direct conversion to a calendar slot. + +Scheduler weaknesses. + +- Higher friction; not all prospects ready. +- Requires capacity to handle bookings. +- Routing complexity. + +The choice. When the conversion is a meeting and the audience is consideration-stage, scheduler. When the conversion is more open or the audience is awareness-stage, form. + +--- + +## Schedulers vs sales-pipeline tools + +For B2B sales, alternatives exist. + +Sales pipeline strengths. + +- Sales-led; rep makes contact on their schedule. +- Can prioritize based on fit before reaching out. + +Sales pipeline weaknesses. + +- Slower response. +- Higher acquisition cost per booking. + +Scheduler advantages. + +- Self-serve; faster response. +- Lower acquisition cost. + +The combined approach. Many production teams use both: scheduler for self-serve high-intent leads; sales pipeline for outbound and complex deals. + +--- + +## The opportunity-cost frame + +A scheduler is significant work. Account for it. + +The build cost. Qualification logic, availability rules, routing, prep automation, reminder sequences, integration with CRM and calendar, mobile responsiveness. A meaningful scheduler often takes 40-150 engineering hours plus operational setup. + +The maintenance cost. Routing rules update as team changes; integrations need maintenance. Quarterly review and updates run 4-8 hours. + +The opportunity cost. What else could the team have built? A simpler contact form, a better sales-led process, direct outreach. The scheduler has to clear the bar of those alternatives. + +The decision frame. Scheduler earns investment when it produces more meeting volume at acceptable quality than alternatives. + +--- + +## Decision worked example + +A B2B SaaS with 50 demo requests per week. + +Conditions check. + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes (mid-market audience). +- Team capacity: yes; 4 reps with capacity for 12-15 demos per week each. +- Qualification and routing supported: yes; reps differ by industry vertical. +- Success metric defined: booking conversion, demo-to-trial within 14 days. + +Decision. Build the scheduler. The conditions warrant it. + +Architecture. 4-field qualification (size, role, use case, timeline); fit-based routing (enterprise to senior AE, mid-market to AE, SMB to SDR); CRM enrichment and Slack brief for prep automation. + +Maintenance commitment. Quarterly review; team-change updates as part of onboarding. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A consumer-facing financial advisory company with 5 inbound consultations per week. + +Conditions check. + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes. +- Team capacity: yes (3 advisors). +- Qualification and routing supported: not really; advisors are interchangeable. +- Volume justifies scheduler infrastructure: low. + +Decision. Do not build a custom scheduler. Use a generic booking link with a brief 2-field qualification form. The volume does not justify routing infrastructure; the simplicity is fine. + +The decision was right-sized. + +--- + +## When to retire a scheduler + +Schedulers can become wrong over time. + +Retire-or-redesign when: + +- Conversion has dropped below baseline consistently and refinements have not moved it. +- Team structure changed; routing logic no longer fits. +- Volume changed; infrastructure no longer matches need. +- Integration with CRM or calendar has broken repeatedly. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant schedulers. The five conditions that argue against. Schedulers vs forms. Schedulers vs sales-pipeline tools. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific scheduler decisions for specific teams. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/dist/pi/.agents/skills/security-baseline/SKILL.md b/dist/pi/.agents/skills/security-baseline/SKILL.md new file mode 100644 index 0000000..bd3f1ec --- /dev/null +++ b/dist/pi/.agents/skills/security-baseline/SKILL.md @@ -0,0 +1,296 @@ +--- +name: security-baseline +description: "Establish a security baseline for a website or web app. Use this skill when configuring HTTPS and TLS, setting security headers, planning secrets management, evaluating CSP policies, doing a basic security audit, or hardening a site before launch. Triggers on security headers, HTTPS, TLS, CSP, content security policy, HSTS, secrets management, vulnerability scan, security audit, harden, OWASP, security baseline. Also triggers when a security review is required for compliance or before going live." +category: operations +catalog_summary: "HTTPS, security headers, CSP, secrets management, vulnerability scans" +display_order: 7 +--- + +# Security Baseline + +Establish the security floor for any production website or web app. Stack-agnostic. Covers the things that should be in place before public launch and verified periodically after. + +--- + +## When to use + +- Pre-launch security review +- Setting up a new site or environment +- Periodic security audit (quarterly recommended) +- Onboarding a new vendor or third-party integration +- Responding to a security finding or report +- Hardening after an incident + +## When NOT to use + +- Active incident response (use `incident-response`) +- Code-level security review (use `code-review-web`) +- Email-specific authentication (SPF/DKIM/DMARC) (use `email-deliverability`) +- DNS-level security (CAA, DNSSEC) (use `domain-strategy`) +- Performance-related security (DDoS protection sizing) (use `performance-optimization`) + +--- + +## Required inputs + +- The site or app in scope (URLs, environments) +- The hosting platform and CDN +- Authentication method (if any) +- Third-party scripts and integrations +- Compliance context (PCI, SOC2, GDPR, etc., if applicable) +- Existing security tooling + +--- + +## The framework: 6 layers + +Security is layered. Each layer addresses a different attack surface. + +### Layer 1: Transport security + +How data moves from server to client. + +- HTTPS everywhere. No HTTP variants serving content. +- TLS 1.2 minimum, TLS 1.3 preferred. Disable TLS 1.0 and 1.1. +- HSTS (Strict-Transport-Security) header set, with `includeSubDomains` and `preload` for high-confidence sites. +- Strong cipher suites only. Modern browsers handle this if you pick a modern config from your provider. +- Certificates from a trusted CA, monitored for expiration. + +### Layer 2: Response headers + +What the browser is told about your site. + +\| Header \| Purpose \| Default value \| +\|---\|---\|---\| +\| `Strict-Transport-Security` \| Force HTTPS \| `max-age=31536000; includeSubDomains` \| +\| `Content-Security-Policy` \| Restrict resource loading \| Site-specific \| +\| `X-Content-Type-Options` \| Prevent MIME sniffing \| `nosniff` \| +\| `X-Frame-Options` \| Clickjacking protection \| `DENY` or `SAMEORIGIN` \| +\| `Referrer-Policy` \| Control referrer info \| `strict-origin-when-cross-origin` \| +\| `Permissions-Policy` \| Control browser features \| Site-specific (camera, mic, etc.) \| +\| `Cross-Origin-Opener-Policy` \| Process isolation \| `same-origin` (where compatible) \| +\| `Cross-Origin-Embedder-Policy` \| Cross-origin restrictions \| `require-corp` (where applicable) \| + +CSP deserves its own attention. See the framework section below. + +### Layer 3: Authentication and authorization + +How users prove who they are and what they can do. + +- Strong password requirements (length over complexity rules; allow long passphrases) +- Account lockout or rate limiting on login +- 2FA available, required for admin accounts +- Session tokens: short-lived, secure, HttpOnly cookies +- Logout invalidates tokens server-side, not just client-side +- Password reset flows that don't reveal account existence +- Authorization checked on every request (don't rely on UI hiding) + +### Layer 4: Input handling + +How untrusted input is processed. + +- Validate on the server (client validation is UX, not security) +- Parameterized queries for any database access (no string concatenation into SQL) +- Output encoding by context (HTML, JS, URL, CSS) +- File upload restrictions (type, size, location, scanning) +- Rate limiting on endpoints that could be abused +- CSRF tokens on state-changing requests + +### Layer 5: Secrets management + +Where credentials and keys live. + +- No secrets in code, config files in repos, or environment variables baked into images +- Secrets in a dedicated secrets manager +- Different secrets per environment (no shared dev/prod secrets) +- Rotation schedule documented and followed +- Audit log of secret access +- Limited blast radius (each service has its own credentials, scoped narrowly) + +### Layer 6: Operational security + +How the team operates. + +- Access controls reviewed quarterly (offboard immediately on departure) +- 2FA enforced on every admin account (hosting, DNS, registrar, code host, deploy tools) +- Audit logs enabled and reviewed +- Vulnerability scanning (dependencies, containers, infrastructure) +- Patch cadence defined +- Incident response runbook exists (see `incident-response`) +- Backups exist and are tested (see `backup-and-disaster-recovery`) +- Security contact published (security.txt at /.well-known/security.txt) + +--- + +## Content Security Policy + +CSP is the most powerful response header and the most often misconfigured. Worth its own treatment. + +### What CSP does + +CSP tells the browser which sources are allowed for various resource types: scripts, styles, images, frames, connections, etc. A strict CSP prevents most XSS attacks even when input handling has bugs. + +### Two flavors + +Strict CSP (recommended): uses `nonce-` or `hash-` based source allowlists. Inline scripts must be explicitly allowed via nonce. + +``` +Content-Security-Policy: script-src 'self' 'nonce-{random}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; +``` + +Allowlist CSP (legacy): lists allowed domains. Easier to set up, much weaker. + +``` +Content-Security-Policy: script-src 'self' https://trusted.com; ... +``` + +Strict CSP requires application changes (every inline script needs a nonce). The investment pays off. + +### Roll out CSP gradually + +1. Start with `Content-Security-Policy-Report-Only` to log violations without blocking. +2. Set up a violation report endpoint. +3. Watch for legitimate violations (third-party scripts, inline handlers). +4. Tune the policy. +5. Switch to enforcing mode once violations are mostly false positives. +6. Continue monitoring violation reports for new issues. + +### Common CSP mistakes + +- `unsafe-inline` in script-src. Defeats most of CSP's value. +- `unsafe-eval` in script-src. Often required by older libraries; refactor or replace. +- Wildcard sources (``). Defeats the policy. +- Allowing CDNs that host arbitrary user content. Attackers can upload scripts to the CDN. +- Not restricting `frame-ancestors`. Use this for clickjacking defense (more flexible than `X-Frame-Options`). + +--- + +## Workflow + +### Step 1: Run a baseline scan + +Use a free scanner: securityheaders.com, observatory.mozilla.org. Get a current grade. This is the floor. + +### Step 2: Inventory the surface + +- Domains and subdomains in scope +- Public endpoints (forms, APIs) +- Authentication entry points +- Admin interfaces +- Third-party integrations and their permissions + +### Step 3: Audit each layer + +Walk the 6 layers. For each, document: +- What's in place +- What's missing +- Risk level (high, medium, low) + +### Step 4: Prioritize + +High risk, easy fixes go first: +- HSTS not set +- Default headers missing +- Admin without 2FA +- Old TLS versions enabled + +Medium risk, medium fixes next: +- CSP rollout +- Input validation gaps +- Secret management improvements + +Low risk, nice-to-haves last: +- Permissions-Policy refinements +- Optional headers (Cross-Origin- family) + +### Step 5: Implement and verify + +For each fix: +- Make the change +- Test in a non-production environment +- Verify with a scanner +- Roll out +- Re-verify in production + +### Step 6: Set up monitoring + +- Certificate expiration alerts +- CSP violation reporting +- Failed login monitoring +- Unusual admin activity alerts +- Dependency vulnerability alerts (Dependabot, Snyk, or equivalent) + +### Step 7: Document the baseline + +Write a security baseline document. It says what's expected on every site: +- Required headers +- Required configurations +- Required practices + +New sites get audited against this. Existing sites get re-audited periodically. + +### Step 8: Schedule review + +Quarterly is the floor. Add reviews after major changes or incidents. + +--- + +## Common compliance touchpoints + +Not legal advice. Surfaces where security baseline meets compliance requirements: + +- PCI DSS (if handling payment cards): much more involved than baseline. The baseline is a starting point, not sufficient. +- SOC 2: baseline aligns with most CC controls (CC6 series). Documented baseline plus evidence of execution is the audit ask. +- GDPR / privacy regs: baseline supports security obligations (Article 32). Privacy is broader than security. +- HIPAA, HITRUST, FedRAMP: baseline is necessary, far from sufficient. Get specialized help. + +When compliance applies, the baseline is necessary but not the full answer. + +--- + +## Failure patterns + +HSTS without `includeSubDomains`. Attacker tricks browser into HTTP on a subdomain you haven't HTTPS'd yet. + +HSTS preload without commitment. Once preloaded, removing it takes weeks. Don't preload until HTTPS is solid across all subdomains forever. + +CSP with `unsafe-inline`. Defeats most of CSP. Either go strict (nonce-based) or accept that CSP is providing limited protection. + +Default headers missing. `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` are easy and free. Set them. + +Admin without 2FA. The single most common high-impact vulnerability across small teams. Fix today. + +Secrets in environment variables baked into images. Anyone with image access has the secrets. Use a runtime secret manager. + +No security.txt. Researchers find issues; they need somewhere to report. Publish a security.txt at /.well-known/security.txt. + +Old TLS versions enabled. Disable TLS 1.0 and 1.1. Most providers offer this as a checkbox. + +CDN allowing arbitrary inline scripts via misconfigured CSP. The CDN proxies user content; attackers leverage that. Audit the CSP against actual loaded resources. + +No incident response plan. When (not if) something happens, no runbook = chaos. See `incident-response`. + +Vulnerability scanning without remediation. Reports pile up. The scan is theater unless someone fixes findings. + +Penetration test ignored. Pen test report sits on a shelf. Test results without remediation are worse than no test. + +--- + +## Output format + +A security baseline document includes: + +- Inventory: what's in scope +- Layer-by-layer status: what's in place, what's missing +- Required headers: with values, applied per environment +- Required configurations: TLS, secrets, auth +- Required operational practices: access reviews, patch cadence, audit logging +- Findings: prioritized list of gaps +- Remediation plan: owners, dates +- Re-audit cadence: when this is reviewed next + +--- + +## Reference files + +- [`references/headers-checklist.md`](references/headers-checklist.md): A copy-paste checklist of recommended security headers with example values, organized by tier of importance. diff --git a/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md b/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md new file mode 100644 index 0000000..3a847f9 --- /dev/null +++ b/dist/pi/.agents/skills/security-baseline/references/headers-checklist.md @@ -0,0 +1,311 @@ +# Security Headers Checklist + +Copy-paste reference for HTTP response headers that improve security. Organized by tier of importance. + +Test current headers with: securityheaders.com or observatory.mozilla.org. + +--- + +## Tier 1: Set on every site, no excuse + +These are simple to deploy, low risk of breaking things, and material security improvements. + +### Strict-Transport-Security (HSTS) + +Forces browsers to use HTTPS for all future requests to this domain. + +``` +Strict-Transport-Security: max-age=31536000; includeSubDomains +``` + +- `max-age`: lifetime in seconds (31536000 = 1 year, recommended for stable HTTPS deployments) +- `includeSubDomains`: applies to all subdomains. Only enable when every subdomain serves HTTPS reliably. +- `preload`: optional. Enables inclusion in browser preload lists. Once enabled, removal takes weeks. Only add when committed. + +Common mistake: Setting `includeSubDomains` before all subdomains are HTTPS-ready. Internal staging or admin subdomains break. + +--- + +### X-Content-Type-Options + +Prevents browsers from MIME-sniffing the content type, which can lead to confusion attacks. + +``` +X-Content-Type-Options: nosniff +``` + +No nuance. Set it everywhere. + +--- + +### X-Frame-Options + +Prevents your site from being framed by other sites (clickjacking defense). + +``` +X-Frame-Options: DENY +``` + +Use `SAMEORIGIN` instead if your own site uses iframes of itself. + +`X-Frame-Options` is largely superseded by CSP's `frame-ancestors`, but setting both is fine for backward compatibility with older browsers. + +--- + +### Referrer-Policy + +Controls how much information is sent in the Referer header on outbound links and resource loads. + +``` +Referrer-Policy: strict-origin-when-cross-origin +``` + +This sends full URL on same-origin requests, only the origin on cross-origin HTTPS-to-HTTPS, and nothing on HTTPS-to-HTTP downgrades. + +For privacy-sensitive sites: + +``` +Referrer-Policy: no-referrer +``` + +--- + +## Tier 2: Material security improvements, requires planning + +These add real protection but may require code changes or rollout planning. + +### Content-Security-Policy + +The most powerful header. Prevents most XSS attacks even when input handling has bugs. + +Strict CSP (recommended for new sites): + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' 'nonce-{random}' 'strict-dynamic'; + style-src 'self' 'nonce-{random}'; + img-src 'self' data: https:; + font-src 'self'; + connect-src 'self'; + frame-ancestors 'none'; + base-uri 'self'; + form-action 'self'; + object-src 'none'; + upgrade-insecure-requests; +``` + +Notes: +- `nonce-{random}` is replaced per request with a fresh random token, included on legitimate inline scripts. +- `'strict-dynamic'` allows scripts loaded by trusted scripts (recursive trust). Most modern apps need this. +- `frame-ancestors 'none'` is the modern equivalent of `X-Frame-Options: DENY` and is more flexible. +- `object-src 'none'` blocks Flash and similar (still useful even though Flash is dead). +- `base-uri 'self'` prevents base tag hijacking. + +Allowlist CSP (if you can't do strict): + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' https://trusted-cdn.com; + style-src 'self' 'unsafe-inline'; + img-src 'self' data: https:; + ... +``` + +This is weaker than strict CSP. Plan to migrate to strict. + +Roll out via Report-Only first: + +``` +Content-Security-Policy-Report-Only: ...; report-uri /csp-violation-report +``` + +Watch reports, tune, then switch to enforcing. + +--- + +### Permissions-Policy + +Controls which browser features (camera, microphone, geolocation, etc.) can be used. + +Conservative default: + +``` +Permissions-Policy: + accelerometer=(), + camera=(), + geolocation=(), + gyroscope=(), + magnetometer=(), + microphone=(), + payment=(), + usb=(), + interest-cohort=() +``` + +This denies all listed features by default. Allow specific ones if needed: + +``` +Permissions-Policy: camera=(self), geolocation=(self "https://maps.example.com") +``` + +`interest-cohort=()` opts the site out of FLoC and similar third-party tracking. + +--- + +## Tier 3: Newer, useful in specific contexts + +These provide additional isolation and protection. Some require more careful integration. + +### Cross-Origin-Opener-Policy (COOP) + +Isolates your site's window from cross-origin windows. Defends against cross-origin attacks like Spectre. + +``` +Cross-Origin-Opener-Policy: same-origin +``` + +May break some popup-based OAuth flows. Test carefully. + +--- + +### Cross-Origin-Embedder-Policy (COEP) + +Required for `SharedArrayBuffer` and high-resolution timers. Restricts what can be loaded. + +``` +Cross-Origin-Embedder-Policy: require-corp +``` + +Means every cross-origin resource you load must explicitly opt in via `Cross-Origin-Resource-Policy: cross-origin`. + +Often impractical for sites with many third-party resources. Use `credentialless` as a softer option: + +``` +Cross-Origin-Embedder-Policy: credentialless +``` + +--- + +### Cross-Origin-Resource-Policy (CORP) + +For your own resources (images, scripts, styles), declares who can include them. + +``` +Cross-Origin-Resource-Policy: same-origin +``` + +For resources you want others to be able to embed (a public CDN, a sharing widget): + +``` +Cross-Origin-Resource-Policy: cross-origin +``` + +--- + +### Reporting-Endpoints + +Modern way to specify where violation reports go (replaces the older `report-uri`). + +``` +Reporting-Endpoints: csp-endpoint="https://example.com/csp", default="https://example.com/reports" +Content-Security-Policy: ...; report-to csp-endpoint +``` + +--- + +## Headers to remove or set carefully + +### Server + +The `Server` header reveals what server software is running. + +``` +Server: nginx/1.18.0 +``` + +Reveals software and version. Helps attackers target known vulnerabilities. Set to a generic value or remove: + +``` +Server: web +``` + +(Or remove entirely if your stack allows.) + +--- + +### X-Powered-By + +Reveals the framework or language. + +``` +X-Powered-By: Express +X-Powered-By: PHP/8.0 +``` + +Same issue as `Server`. Remove. + +--- + +### X-AspNet-Version, X-AspNetMvc-Version + +Same. Remove. + +--- + +## What to skip + +These are deprecated, not useful, or actively harmful: + +- `X-XSS-Protection`: deprecated. Modern browsers ignore it. Use CSP instead. +- `Public-Key-Pins` (HPKP): removed from browsers. Don't bother. +- `Expect-CT`: deprecated. Certificate Transparency is enforced automatically. +- `Feature-Policy`: replaced by `Permissions-Policy`. Use the latter. + +--- + +## Quick reference table + +\| Header \| Tier \| Default value \| +\|---\|---\|---\| +\| `Strict-Transport-Security` \| 1 \| `max-age=31536000; includeSubDomains` \| +\| `X-Content-Type-Options` \| 1 \| `nosniff` \| +\| `X-Frame-Options` \| 1 \| `DENY` (or `SAMEORIGIN`) \| +\| `Referrer-Policy` \| 1 \| `strict-origin-when-cross-origin` \| +\| `Content-Security-Policy` \| 2 \| Site-specific (see strict CSP example) \| +\| `Permissions-Policy` \| 2 \| Site-specific (deny by default) \| +\| `Cross-Origin-Opener-Policy` \| 3 \| `same-origin` \| +\| `Cross-Origin-Embedder-Policy` \| 3 \| `require-corp` or `credentialless` \| +\| `Cross-Origin-Resource-Policy` \| 3 \| `same-origin` (resources), `cross-origin` (public) \| +\| `Server` \| Remove \| Set generic or remove \| +\| `X-Powered-By` \| Remove \| Remove \| + +--- + +## Verification + +After deploying, verify: + +```bash +curl -I https://example.com +``` + +Look for the headers in the response. + +Test grade: securityheaders.com gives a letter grade. Aim for A or A+. + +--- + +## Setting headers by stack + +Where you set these depends on the stack. Common locations: + +- Reverse proxy (Nginx, Caddy, HAProxy): in the proxy config +- CDN (Cloudflare, Fastly, Akamai): in the CDN's response header rules +- Application (Express, Django, Rails, etc.): middleware or filter +- Hosting platform (Vercel, Netlify, Cloudflare Pages): platform-specific config file (e.g., `vercel.json`, `_headers`) + +Setting at the edge (CDN or proxy) is preferred when possible: applies to every response without depending on application code. + +For dynamic values (like the CSP nonce), the header has to be set per-request from the application. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md b/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md new file mode 100644 index 0000000..c60a7b4 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-aeo-geo +description: "Optimize content and site structure for AI-driven search experiences including AI overviews, large language model citations, generative answer engines, and AI assistants. Use this skill whenever the user wants to optimize for AI search, get cited by language models, appear in AI overviews, build llms.txt, structure content for AI extraction, or future-proof their SEO for the shift from blue links to AI answers. Triggers on AEO, GEO, AI search, AI SEO, AI overview, generative search, LLM optimization, llms.txt, AI citation, ChatGPT search, Perplexity, Gemini, Claude search, AI assistant optimization, answer engine. Also triggers when the user expresses concern about AI eating their organic traffic or wants to understand how to remain visible as search shifts." +category: seo-foundation +catalog_summary: "AI search optimization, llms.txt, extraction-friendly content" +display_order: 7 +--- + +# AEO and GEO + +Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO). Make content discoverable, extractable, and citable by AI search experiences. + +This skill encodes principles. AI search products evolve fast. The principles age slower than the products. + +--- + +## When to use + +- Optimizing content for AI overviews and generative answer engines +- Building or updating llms.txt +- Structuring content so AI assistants can extract and cite it correctly +- Future-proofing a site as search shifts from blue links to AI answers +- Auditing whether existing content is AI-friendly +- Adding signals that help AI assistants identify the site as a trustworthy source + +## When NOT to use + +- Traditional on-page or technical SEO (use `seo-onpage` or `seo-technical`) +- Keyword research (use `seo-keyword`) +- Off-page authority and link building (use `seo-offpage`) + +This skill stacks on top of those. Strong AEO/GEO requires strong fundamental SEO underneath. + +--- + +## Required inputs + +- The site or page to optimize +- The topic area or query types AI should cite the site for +- Access to inspect rendered HTML and structured data + +--- + +## The framework: 5 layers + +AI search visibility comes from five stacked layers. Each layer compounds. + +### 1. Extractable content structure + +AI systems extract facts and pull citations from content. Make extraction easy. + +- Direct answers. Open major sections with a definitive 1 to 3 sentence answer to the question that section addresses. AI extracts the first answer it sees. +- Question-headers. Use H2s and H3s phrased as questions when natural. Mirrors how people prompt AI. +- Atomic facts. When stating a fact, state it once, clearly, with the supporting context next to it. AI struggles when claims are spread across paragraphs. +- Tables and lists. AI parses these reliably. Use them for comparisons, specs, steps, and data. +- Definitions early. When introducing a concept, define it inline. Do not assume the reader (or AI) saw a definition three pages ago. +- Numbered steps. For procedural content, number every step. Avoid prose disguised as instructions. + +### 2. Citation worthiness + +AI cites sources it considers authoritative. Earn that consideration. + +- Original data. Surveys, studies, proprietary research, internal benchmarks. AI prefers primary sources over restatements. +- Specific numbers. "Roughly 40 percent" beats "many." Specific stats with sources beat round-number generalizations. +- Named experts. Author bios with credentials, links to professional profiles, schema-marked-up Person entities. +- Date stamps. Publication date AND last-updated date, both visible AND in schema. AI heavily weights recency for time-sensitive queries. +- Methodology disclosure. When stating a finding, briefly note how it was reached. AI rewards transparency. +- Citations of other sources. Linking to authoritative sources you used builds reciprocal credibility. + +### 3. Structured data depth + +Schema is how you speak machine-readable language. AI assistants parse it heavily. + +- Schema.org types appropriate to content (Article, FAQPage, HowTo, Recipe, Product, Organization, Person, LocalBusiness, etc.) +- Required AND recommended properties filled in (most sites only fill required, leaving signal on the table) +- Person schema for authors, with `sameAs` links to verifiable profiles +- Organization schema on the homepage with logo, contact, social links +- FAQPage schema for content with genuine question-answer pairs +- HowTo schema for procedural content +- BreadcrumbList schema site-wide +- Validates in Schema.org Validator AND Rich Results Test (some properties differ) + +### 4. AI-readable accessibility + +Beyond traditional SEO, AI tools need access patterns of their own. + +- llms.txt at the site root. A markdown file at `/llms.txt` describing the site's content, key URLs, and what topics the site covers. See [`references/llms-txt-guide.md`](references/llms-txt-guide.md). +- llms-full.txt (optional) - a complete content dump for AI training and context, if the site permits it. +- robots.txt allowing AI crawlers. Decide explicitly which AI crawlers to allow (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, etc.) or disallow. Do not block by default if visibility matters. +- Clean HTML semantics. Semantic tags (`article`, `section`, `nav`, `main`) help AI parse structure. +- Avoid client-side-only rendering for critical content. Many AI crawlers render less reliably than Googlebot. + +### 5. Real-world entity signals + +AI builds knowledge graphs and prefers entities with multiple consistent signals. + +- Wikipedia entry if the brand or person qualifies for notability (do not force this; it requires genuine notability) +- Wikidata entry for the entity, with consistent properties +- Consistent NAP (Name, Address, Phone) across all citations +- Brand mentions across multiple authoritative sources. AI cross-references entity claims across the open web. +- Social profile schema linking owned profiles via `sameAs` properties +- Reviews and reputation signals. Aggregate ratings on Google Business, Trustpilot, industry-specific review sites where applicable + +--- + +## Workflow + +1. Audit current state. Run the 5-layer framework against the existing site. Score each. +2. Identify the priority queries. What questions should AI cite this site for? List 10 to 20. +3. Test current AI visibility. Query each of the major AI products (those relevant to the audience) with the priority questions. Note which sources they cite. +4. Identify gaps. Is the site cited? On which queries? Why does it lose to the cited sources? +5. Layer-by-layer plan. + - Fix extractable structure on top 20 priority pages + - Add citation-worthy signals (original data, expert authorship, methodology) + - Deepen schema implementation + - Build/update llms.txt + - Strengthen entity signals +6. Implement and re-test. AI products update frequently. Re-test priority queries quarterly. + +--- + +## Failure patterns + +- Treating AEO/GEO as separate from SEO. Strong fundamental SEO is a prerequisite. AI cites pages, not magic. +- Stuffing FAQ schema on pages that have no genuine FAQs. Search engines and AI alike penalize manufactured FAQ blocks. +- Hiding key content behind heavy JavaScript. AI crawlers render less reliably. Server-render or pre-render critical content. +- Optimizing for one AI product only. Different products use different ranking and citation logic. Optimize for the principles, not for one product's quirks. +- Ignoring entity strength. Content alone, with no real-world entity signals, will not get cited reliably for branded or expertise-related queries. +- Treating llms.txt as a magic bullet. It helps, but it is one of many signals. +- Static optimization. AI products evolve faster than search algorithms historically did. Re-audit at least quarterly. + +--- + +## Output format + +Default output is a markdown plan at `aeo-geo-strategy.md`. Structure: + +1. Current AI visibility audit (which queries cite the site, which do not) +2. 5-layer scorecard +3. Priority queries (the 10 to 20 the site should be cited for) +4. Layer-by-layer remediation plan +5. Implementation roadmap +6. Re-test schedule (quarterly) + +--- + +## Reference files + +- [`references/llms-txt-guide.md`](references/llms-txt-guide.md) - How to write a useful llms.txt, with examples. +- [`references/extraction-friendly-patterns.md`](references/extraction-friendly-patterns.md) - Content patterns that AI extracts cleanly, with before/after examples. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md b/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md new file mode 100644 index 0000000..2906fb1 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/references/extraction-friendly-patterns.md @@ -0,0 +1,266 @@ +# Extraction-Friendly Patterns + +Content patterns that AI search experiences extract cleanly, with before-and-after examples. The goal is not to write for AI exclusively. The goal is to write so a human reader gets the answer fast and an AI extractor gets it fast too. The two overlap more than people think. + +--- + +## The principle + +AI extractors and skim-readers want the same thing: the answer first, the supporting context second. Content that buries the answer behind preamble loses both audiences. + +Three structural moves do most of the work: + +1. Lead with the answer. First sentence of the section answers the section's question. +2. Use semantic structure. Headings name the question. Lists separate items. Tables compare options. Code blocks contain code. +3. Be self-contained. Each section should make sense without depending on the section above. + +Everything below is an application of these three moves. + +--- + +## Pattern 1: question-led headings + +Headings phrased as the question the user actually asks. + +### Bad + +> ## Onboarding optimization + +### Better + +> ## How long should employee onboarding take? + +The question form does three jobs at once: it matches likely search queries, it tells the reader what they will learn, and it tells the AI extractor what answer follows. + +--- + +## Pattern 2: answer-first paragraph + +The first sentence answers the question. Subsequent sentences provide context, caveats, and depth. + +### Bad + +> ## How long should employee onboarding take? +> +> Onboarding has many definitions across organizations. Some companies define onboarding as the first day, some as the first week, and others as the entire ramp-up period. There is no industry consensus, and the question depends on many factors. With that said, most modern companies aim for a structured program lasting somewhere between 30 and 90 days. + +### Better + +> ## How long should employee onboarding take? +> +> Most structured onboarding programs run 30 to 90 days, with 90 being the most common. The exact length depends on role complexity, company size, and how much time managers can dedicate. The first week typically covers logistics and culture; the first month adds shadowing and small projects; the second and third months ramp the new hire into full ownership. + +The "Better" version puts the extractable answer in the first sentence. The follow-up adds context without burying the lead. + +--- + +## Pattern 3: definitions in inverse pyramid + +Define the term in one sentence, then expand. + +### Bad + +> ## What is a service blueprint? +> +> A service blueprint is a versatile tool used by many designers and product teams. Originally developed in the 1980s by G. Lynn Shostack at Bankers Trust, it has since been adopted across industries from healthcare to retail. Service blueprints help teams visualize the relationships between people, processes, and physical evidence in a service experience. + +### Better + +> ## What is a service blueprint? +> +> A service blueprint is a diagram that maps every step of a service experience, both what the customer sees and what happens behind the scenes. It typically uses lanes for the customer journey, frontstage actions, backstage actions, and supporting systems. Originally developed by G. Lynn Shostack in the 1980s, it is now standard in service design, healthcare workflow design, and operations planning. + +The first sentence is a complete, extractable definition. AI assistants quoting your page will quote this sentence. Search snippets will lift it. + +--- + +## Pattern 4: numbered lists for sequenced steps + +Sequenced procedures go in numbered lists. Not in prose. + +### Bad + +> To deploy with the CLI, first you'll want to run npm install. Once that completes, run npm run build to generate the production bundle, then npm run deploy to push to your environment. After that, verify the deployment by checking the status endpoint. + +### Better + +> ## How to deploy with the CLI +> +> 1. Install dependencies: `npm install` +> 2. Build the production bundle: `npm run build` +> 3. Deploy to your environment: `npm run deploy` +> 4. Verify the deployment by checking the status endpoint. + +The numbered list extracts cleanly into "how-to" snippets, FAQ-style answers, and HowTo schema. The prose version forces the extractor (human or AI) to do the work of parsing the steps. + +--- + +## Pattern 5: bullet lists for parallel items + +Parallel items go in bullets. Especially "what is included" or "options" lists. + +### Bad + +> Our enterprise tier includes single sign-on, audit logs, advanced role-based access controls, dedicated support, and custom data retention policies. + +### Better + +> ## What is included in the enterprise tier +> +> - Single sign-on (SSO) +> - Audit logs +> - Advanced role-based access controls +> - Dedicated support +> - Custom data retention policies + +The bullet form is extractable. An AI assistant asked "what does the enterprise tier include" can quote this list verbatim. + +--- + +## Pattern 6: tables for comparisons + +When comparing 2+ options across 2+ criteria, use a table. AI extractors handle tables well; prose comparisons get garbled. + +### Bad + +> The free plan supports up to 3 projects and 5 team members, with email support only. The pro plan extends this to 25 projects and 25 team members, adds priority support, and includes the API. The enterprise plan removes all limits, adds SSO, audit logs, and a dedicated success manager. + +### Better + +> \| Feature \| Free \| Pro \| Enterprise \| +> \|---\|---\|---\|---\| +> \| Projects \| 3 \| 25 \| Unlimited \| +> \| Team members \| 5 \| 25 \| Unlimited \| +> \| Support \| Email \| Priority \| Dedicated CSM \| +> \| API access \| - \| ✓ \| ✓ \| +> \| SSO \| - \| - \| ✓ \| +> \| Audit logs \| - \| - \| ✓ \| + +--- + +## Pattern 7: explicit Q&A blocks + +For pages where the user is asking a direct question (FAQs, help docs, glossaries), use explicit Q&A formatting. + +### Pattern + +> Q: [The question phrased as the user would ask it] +> +> A: [Direct answer in 1-3 sentences. Optional supporting paragraph after.] + +This is what FAQ schema lifts directly. AI extractors recognize the pattern and treat it as a discrete answerable unit. + +--- + +## Pattern 8: self-contained sections + +Each section under an H2 should make sense if read in isolation. AI extractors often pull a single section as the answer to a query. If the section depends on context from earlier sections, the answer it surfaces will be incomplete or wrong. + +### Bad + +> ## Setup +> +> Use the same approach we discussed in the previous section, but with the production endpoint instead of staging. + +### Better + +> ## Setup for production +> +> Run the deploy command against the production endpoint: +> +> ```bash +> npm run deploy --target=production +> ``` +> +> The production endpoint requires the `PROD_API_KEY` environment variable. See "Environment variables" for setup. + +The "Better" version stands alone. A reader (or AI assistant) landing here from search gets a complete answer. + +--- + +## Pattern 9: explicit data and units + +State numbers, ranges, and units explicitly. Vague modifiers ("a lot," "fast," "some users") do not extract. + +### Bad + +> Our customers see a major improvement in conversion after switching. + +### Better + +> On average, our customers see a 23% lift in conversion within the first 30 days after switching, based on data from 412 customers measured between January and March 2025. + +The "Better" version has extractable specifics: the metric, the magnitude, the time window, the sample size, and the date range. Trustworthy AI assistants prefer extracting specifics. + +--- + +## Pattern 10: structured author and date metadata + +For any content that depends on currency or expertise, expose the metadata visibly and in schema. + +- Author byline with a real name and a credential or one-line bio. +- Publish date and last updated date in human-readable form. +- Reviewer if the content is reviewed by an SME. +- Article schema with `author`, `datePublished`, `dateModified`, and (where applicable) `reviewedBy`. + +AI search uses author and date signals as part of trustworthiness scoring. + +--- + +## Pattern 11: explicit topic boundaries + +Tell the reader (and the extractor) what the page is and is not about. + +### Pattern + +> ## What this guide covers +> +> This guide covers backup strategies for Postgres databases on managed services (AWS RDS, GCP Cloud SQL, Supabase). It does not cover self-hosted Postgres tuning, backup of file storage, or disaster recovery testing. +> +> If you are self-hosting Postgres, see [other guide]. If you are designing DR drills, see [other guide]. + +This pattern protects against AI summaries that conflate your scope with adjacent topics. + +--- + +## Pattern 12: predictable summary blocks + +Sections like "Summary," "Key takeaways," "TL;DR" at the top or bottom of an article extract well. Keep them tight: 3-7 bullets, one short sentence each. + +### Pattern + +> ## Key takeaways +> +> - Aim for 30-90 day onboarding, with 90 being the most common. +> - First week: logistics and culture. First month: shadowing and small projects. Months 2-3: full ramp. +> - The single highest-impact factor is manager time, not program design. +> - Track time-to-productivity, not arbitrary onboarding completion. + +A summary block doubles as the AI snippet, the social card excerpt, and the email digest line. + +--- + +## What to avoid + +These patterns hurt extraction: + +- Walls of text without headings. The reader and the extractor both lose place. +- Inline references that depend on prior sections. "As mentioned above" is invisible to a snippet. +- Vague modifiers in place of numbers. "Many users," "several studies," "a long time." +- Jargon without definition. AI assistants will define it incorrectly if you do not. +- Marketing fluff in lead sentences. "Discover the powerful possibilities of..." extracts as gibberish. +- PDFs and images for content that should be text. Tables and key data trapped in images cannot be extracted. +- Iframe-embedded content. AI assistants do not consistently follow iframes. + +--- + +## How to test + +After writing a page, simulate extraction: + +1. Read only the H1 and the first sentence under each H2. Does the page still make sense? +2. Read only the bullet lists, tables, and Q&A blocks. Do they answer the obvious questions? +3. Ask an LLM (in a fresh context) the questions your page answers. Does it pull useful, accurate snippets from your page? +4. Check Google's "People also ask" for your topic. Does your page answer those exact questions? + +If a test fails, the structure needs more semantic markup, not more words. diff --git a/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md b/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md new file mode 100644 index 0000000..5360369 --- /dev/null +++ b/dist/pi/.agents/skills/seo-aeo-geo/references/llms-txt-guide.md @@ -0,0 +1,227 @@ +# llms.txt Guide + +`llms.txt` is a markdown file at the root of a domain (e.g., `example.com/llms.txt`) that helps AI systems understand what the site is, what it covers, and which URLs are most valuable. + +It is the AI-era equivalent of `robots.txt` plus a sitemap, written in plain language for language models. + +This guide walks through how to write a useful one. + +--- + +## What llms.txt is for + +- Tell AI assistants what the site is and what it covers +- Point AI to the most valuable URLs for citation +- Provide structured context that helps AI summarize and cite the site accurately +- Reduce the chance of AI hallucinating about your brand or content + +What it is NOT: + +- A ranking signal (yet, possibly ever) +- A guarantee of citation +- A replacement for sitemap.xml or robots.txt +- A way to block AI crawlers (use robots.txt for that) + +--- + +## The format + +llms.txt is a markdown file with a specific structure: + +```markdown +# [Site or Brand Name] + +> [One-sentence description of what the site is and who it serves] + +[1 to 3 paragraphs of context. Who runs the site, what topics it covers, what makes it credible, what audience it serves. Plain language.] + +## [Section 1 - typically content categories or product lines] + +- [Title](URL): [One-line description] +- [Title](URL): [One-line description] + +## [Section 2] + +- [Title](URL): [One-line description] + +## Optional + +[Less critical resources.] +``` + +Section headers are flexible. Use whatever organization fits the site's content. + +--- + +## Example: a simple content site + +```markdown +# Example Knowledge Base + +> A free guide library on [topic area] for [audience]. + +We publish in-depth guides, comparisons, and how-tos on [topic area]. Content is written by [credentials of authors] and updated [frequency]. Our methodology is documented at /methodology. + +## Core guides + +- [The Complete Guide to X](https://example.com/complete-guide-x): A 5,000-word reference covering fundamentals through advanced topics. +- [How to Choose Y](https://example.com/how-to-choose-y): Decision framework with comparison tables and worked examples. +- [The Beginner's Guide to Z](https://example.com/beginner-z): A 30-minute primer for someone new to the topic. + +## Comparisons + +- [A vs B](https://example.com/a-vs-b): Head-to-head feature, pricing, and use case comparison. +- [Top 10 [Category]](https://example.com/top-10): Ranked list with selection criteria. + +## Tools + +- [Calculator](https://example.com/calculator): Free interactive tool for [purpose]. +- [Templates](https://example.com/templates): Downloadable templates with examples. + +## About + +- [About us](https://example.com/about) +- [Methodology](https://example.com/methodology) +- [Editorial standards](https://example.com/editorial-standards) +``` + +--- + +## Example: a SaaS product site + +```markdown +# ProductName + +> [Product category] for [target audience]. [Core value proposition in one phrase]. + +ProductName is built and operated by a team of [size and background]. We serve [audience description]. The product is used by [scale, e.g., "over 10,000 teams" or "from solo founders to Fortune 500 companies"]. + +## Product + +- [How it works](https://example.com/product): Overview of core functionality and architecture. +- [Pricing](https://example.com/pricing): Transparent pricing tiers and what each includes. +- [Integrations](https://example.com/integrations): Third-party tools we connect with. + +## Documentation + +- [Getting started](https://docs.example.com/getting-started): 15-minute setup guide. +- [API reference](https://docs.example.com/api): Complete API documentation. +- [Best practices](https://docs.example.com/best-practices): How successful customers use the product. + +## Resources + +- [Customer stories](https://example.com/customers): How specific customers achieved specific outcomes. +- [Blog](https://example.com/blog): Engineering posts, product updates, and industry analysis. +- [Changelog](https://example.com/changelog): Recent product changes. + +## Trust + +- [Security](https://example.com/security): SOC 2, encryption, compliance. +- [Privacy policy](https://example.com/privacy) +- [Terms of service](https://example.com/terms) +``` + +--- + +## What to include + +A good llms.txt is curated, not exhaustive. Include: + +- Cornerstone content. Your 10 to 30 best, most authoritative pieces. +- Decision-support pages. Comparisons, calculators, frameworks. +- Authority signals. Methodology, editorial standards, about pages. +- Trust signals. Security, privacy, compliance, certification pages. +- Recency cues. A changelog or "latest" link if you publish frequently. + +What to leave out: + +- Every URL on the site (use sitemap.xml for that) +- Marketing fluff with no informational substance +- Pages that exist primarily for SEO (low-quality programmatic content, doorway pages) +- Internal admin URLs + +--- + +## What to write in the description + +The opening description (under the title, prefixed by `>`) is what AI extracts when asked "what is [site]?" Make it count. + +Bad description: +> A leading provider of innovative solutions in the digital space. + +Good description: +> A free guide library on home renovation for first-time buyers, with calculators and template contracts. + +The good description names: what it is (guide library), what topic (home renovation), who it serves (first-time buyers), and what's unique (calculators and templates). + +--- + +## Length and depth + +- Title and one-sentence description: required +- Context paragraphs: 1 to 3 paragraphs, 100 to 400 words total +- Sections: 3 to 8 sections is typical +- URLs per section: 3 to 10 is the sweet spot +- Total file length: 500 to 2000 words for most sites + +A 50-word llms.txt is too thin to be useful. A 5000-word llms.txt buries the signal. + +--- + +## Updating + +- Update llms.txt when you launch a major new content category, product, or section +- Re-review at least quarterly +- Remove dead links (broken URLs in llms.txt actively damage credibility with AI) +- Keep the description fresh as the site evolves + +--- + +## llms-full.txt (the optional sibling) + +Some sites also publish `llms-full.txt`, which contains the full text content of the linked pages concatenated into one file. This is more aggressive: it offers AI systems the entire content for context. + +Reasons to publish it: + +- You want maximum AI context, including verbatim content +- Your content is freely licensed or you accept it being used for AI training +- Your content is short enough that the file is manageable (under 10MB, ideally under 5MB) + +Reasons NOT to publish it: + +- You sell or gate content (e.g., paid courses, premium reports) +- Your terms of service disallow AI training on your content +- File size would exceed reasonable limits + +If you do publish it, link to it from llms.txt: + +```markdown +## Full content + +- [Full content dump](https://example.com/llms-full.txt): The complete content of all linked pages. +``` + +--- + +## Common mistakes + +- Auto-generating llms.txt from sitemap.xml. Defeats the purpose. The point is editorial curation. +- Treating it as a sitemap. Sitemap is for crawlers. llms.txt is for AI context. +- Stuffing it with thin content. Every URL listed should be content you would proudly cite if a human asked. +- Forgetting to update it. A 2-year-old llms.txt makes you look abandoned. +- Hosting it at a non-root path. It belongs at `/llms.txt` (root of the domain), not `/docs/llms.txt`. +- Returning HTML instead of plain text. Serve as `text/markdown` or `text/plain`, not as a rendered HTML page. + +--- + +## Verification + +After publishing: + +- [ ] File is at `https://yourdomain.com/llms.txt` (root) +- [ ] File serves with content type `text/markdown` or `text/plain` +- [ ] All linked URLs return 200 +- [ ] All linked URLs use the canonical URL form (no redirects) +- [ ] File is referenced (or at least not blocked) in robots.txt +- [ ] File renders cleanly in a plain text viewer +- [ ] Description and section headings accurately describe the site diff --git a/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md b/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md new file mode 100644 index 0000000..92c3e96 --- /dev/null +++ b/dist/pi/.agents/skills/seo-audit-orchestration/SKILL.md @@ -0,0 +1,182 @@ +--- +name: seo-audit-orchestration +description: "Master orchestrator for a full SEO audit suite powered by the Ahrefs MCP. Use this skill when running a comprehensive SEO audit, scoping a quarterly health check, doing pre-acquisition SEO due diligence, or post-migration verification. Triggers on full SEO audit, comprehensive SEO review, SEO health check, audit my site, SEO due diligence, audit suite, comprehensive audit, end-to-end SEO. Also triggers when a stakeholder wants the complete picture rather than a single-dimension audit." +category: seo-audit-suite +catalog_summary: "Master orchestrator: sequences the suite, produces a rollup report" +display_order: 1 +--- + +# SEO Audit Orchestration + +Run a complete SEO audit by sequencing the sibling audit skills in a defined order. Stack-agnostic. Assumes the Ahrefs MCP is connected. Produces a single rollup report that synthesizes findings across backlinks, keywords, content, traffic, technical health, and rankings. + +--- + +## When to use + +- Running a full SEO audit (quarterly, biannual, annual) +- Pre-acquisition SEO due diligence +- Post-migration verification (after content move, replatform, or domain change) +- Onboarding a new client or new property +- Building a baseline before a major SEO investment +- Diagnosing chronic underperformance + +## When NOT to use + +- Single-dimension audits (use the specific child skill: `seo-onpage`, `seo-backlink-audit`, etc.) +- Investigating a specific traffic drop (use `seo-traffic-diagnosis`) +- Tactical questions like "which keywords should we target" (use `seo-keyword-gap-audit`) +- Routine monitoring (use `seo-rank-tracking`) + +--- + +## Required inputs + +- The site or properties in scope +- Target market and primary languages +- Competitor set (3-5 properties) +- Goal of the audit (baseline, due diligence, fix plan, growth roadmap) +- Time and reporting constraints +- Confirmation that the Ahrefs MCP is connected and the workspace has access to the target property + +--- + +## The framework: 6 phases of an end-to-end audit + +A complete audit moves through six phases in order. Skipping phases produces gaps. Reordering them produces rework. + +### Phase 1: Scope and baseline + +Define the audit before running it. + +- What is in scope (subdomains, paths, languages) +- What is out of scope +- Goal of the audit (baseline, fix plan, growth roadmap, due diligence) +- Stakeholders and their priorities +- Reporting format and length expectations + +Output: a 1-page audit charter. + +### Phase 2: Data gather + +Pull the raw data from Ahrefs and any companion sources. + +Required pulls: + +- Site Explorer: organic keywords, organic traffic, top pages, top countries, referring domains, backlinks, anchor text profile +- Site Audit: full crawl results +- Keywords Explorer: target keyword universe and competitor keyword overlap +- Content Explorer: top performing content in target topics +- Rank Tracker: current tracked positions if set up + +Companion pulls (not Ahrefs-native): + +- Search Console: query and page data, coverage issues +- Analytics: traffic, conversions, segment by source +- Server logs (if available): bot crawl behavior + +Document data freshness for every pull. Stale data yields wrong conclusions. + +### Phase 3: Run the sub-audits + +Run each child audit. Each produces its own findings doc. + +\| Sub-audit \| Skill \| What it produces \| +\| --- \| --- \| --- \| +\| Site health \| `seo-site-health-audit` \| Prioritized technical fix backlog \| +\| Backlinks \| `seo-backlink-audit` \| Profile health, toxic list, reclamation list \| +\| Keywords \| `seo-keyword-gap-audit` \| Prioritized opportunity list \| +\| Content \| `seo-content-gap-audit` \| Create/update/merge roadmap \| +\| Page-level \| `seo-onpage` \| Per-page audit on top pages \| +\| AI search \| `seo-aeo-geo` \| AI search readiness gaps \| + +The child skills do the analysis. This skill sequences them and integrates the outputs. + +### Phase 4: Synthesize + +Combine findings into themes. A list of 200 issues is not an audit. A list of 5-7 themes is. + +Themes typically emerge in categories like: + +- Technical foundation gaps that cap upside +- Content depth gaps in priority topics +- Backlink profile concentration risks +- Keyword opportunities the site is leaving on the table +- Cannibalization or thin coverage +- AI search readiness + +Each theme should answer: what is happening, why it matters, what is the size of prize, what is the fix. + +### Phase 5: Prioritize + +Rank the themes. Use a simple impact/effort matrix. + +- Quick wins: high impact, low effort. Do now. +- Strategic plays: high impact, high effort. Plan and resource. +- Maintenance: low impact, low effort. Backlog. +- Avoid: low impact, high effort. Drop. + +Tie each theme to a measurable target (organic clicks, ranked keywords in target band, conversions from organic). + +### Phase 6: Deliver + +Produce the rollup report. See [`references/audit-rollup-template.md`](references/audit-rollup-template.md). + +Structure: + +- Executive summary (1 page) +- Themes and recommendations (5-7 themes, 1 page each) +- Sub-audit findings (linked or appended) +- Roadmap (next 90 days) + +Walk stakeholders through it. Get commitment to the next 90 days of work. + +--- + +## Workflow + +1. Charter the audit. 1-page scope, goal, stakeholders, format. +2. Confirm Ahrefs MCP access. Verify the workspace has the target property and recent data. +3. Pull all data. Run the gather list in phase 2. Document freshness. +4. Run each sub-audit. Use the child skills. Each produces its own findings doc. +5. Synthesize themes. 5-7 themes max. Each ties to an impact and a fix. +6. Prioritize. Impact/effort matrix. Quick wins surface to the top. +7. Draft the rollup. Use the template. Executive summary first. +8. Review with the team. Pressure-test conclusions before stakeholder readout. +9. Deliver. Walk stakeholders through. Get commitment to next 90 days. +10. Schedule the next one. Audits decay. Rerun on a cadence. + +--- + +## Failure patterns + +- Audit without a goal. Produces a 60-page document nobody reads. Charter the audit first. +- All findings, no themes. A list of 200 issues is data, not an audit. Synthesize into themes. +- Skipping the sub-audits. Running one big audit instead of six focused ones produces shallow analysis everywhere. +- No prioritization. "Here are 47 things to fix" gets nothing fixed. Rank them. +- Stale data. Ahrefs index updates on a delay. Note freshness. Do not draw conclusions from week-old movement. +- Tool worship. Ahrefs is one source. Search Console, analytics, and logs add ground truth. Triangulate. +- Audit-to-audit drift. Running every audit differently makes trends impossible to spot. Standardize the structure. +- No 90-day roadmap. Without a plan after the audit, the audit is shelfware. +- Solo audit. Audits done alone miss context. Pull in the people who own the work. + +--- + +## Output format + +A rollup audit report with: + +1. Executive summary (1 page). +2. Audit charter (scope, goal, methodology). +3. Themes and recommendations (5-7 themes, each with what, why, size of prize, fix). +4. Sub-audit appendix (linked outputs from each child skill). +5. 90-day roadmap (sequenced work with owners and targets). +6. Methodology notes (data sources, pull dates, caveats). + +Total length: 15-30 pages including appendices. Executive summary readable in 5 minutes. + +--- + +## Reference files + +- [`references/audit-rollup-template.md`](references/audit-rollup-template.md) - Template for the rollup report including executive summary, theme structure, and roadmap format. diff --git a/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md b/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md new file mode 100644 index 0000000..2343b76 --- /dev/null +++ b/dist/pi/.agents/skills/seo-audit-orchestration/references/audit-rollup-template.md @@ -0,0 +1,236 @@ +# Audit rollup template + +A template for the final SEO audit deliverable. Adapt sections to fit the audit goal and stakeholder appetite. + +--- + +## Document structure + +``` +1. Executive summary (1 page) +2. Audit charter (1 page) +3. Themes and recommendations (5-7 themes, 1 page each) +4. 90-day roadmap (1-2 pages) +5. Sub-audit appendix (linked or attached) +6. Methodology notes (1 page) +``` + +Total: 15-30 pages. Executive summary always readable in 5 minutes. + +--- + +## 1. Executive summary template + +``` +# [Property] SEO Audit + +Audit date: [date] +Period covered: [date range] +Auditor: [name or team] + +## Headline + +[One sentence. The state of SEO at this property.] + +## Top 3 themes + +1. [Theme name]. [One sentence. Why it matters.] +2. [Theme name]. [One sentence. Why it matters.] +3. [Theme name]. [One sentence. Why it matters.] + +## Top 3 quick wins + +1. [Action]. Estimated impact: [target metric movement]. Effort: [size]. +2. [Action]. Estimated impact: [target metric movement]. Effort: [size]. +3. [Action]. Estimated impact: [target metric movement]. Effort: [size]. + +## Recommended next 90 days + +[3-5 bullets describing the proposed plan.] + +## What is going well + +[2-4 bullets. Avoid an audit that reads as 100% negative.] +``` + +--- + +## 2. Audit charter template + +``` +## Scope + +- Properties in scope: [list] +- Languages: [list] +- Subdomains: [list] +- Out of scope: [list] + +## Goal + +[Baseline / fix plan / growth roadmap / due diligence] + +## Stakeholders + +\| Name \| Role \| Priority \| +\| --- \| --- \| --- \| +\| [name] \| [role] \| [their main concern] \| + +## Methodology + +- Data sources: [Ahrefs, Search Console, Analytics, logs] +- Pull dates: [dates] +- Sub-audits run: [list] + +## Limitations + +[Anything that limits confidence: data gaps, access restrictions, time constraints.] +``` + +--- + +## 3. Theme template + +Use one page per theme. 5-7 themes total. + +``` +## Theme [N]: [Name] + +What is happening + +[2-3 sentences describing the pattern.] + +Why it matters + +[2-3 sentences linking the pattern to a business outcome.] + +Size of prize + +[Quantified opportunity. E.g., "+12,000 monthly clicks" or "+$80k annual revenue at current conversion."] + +Evidence + +- [Data point with source] +- [Data point with source] +- [Data point with source] + +Recommendation + +[The proposed fix or action. 1 paragraph.] + +Effort and timeline + +[Effort: S/M/L. Timeline: weeks or sprints. Dependencies: list.] + +Owners + +[Who needs to do what.] +``` + +--- + +## 4. 90-day roadmap template + +Sequence the work. Tie to themes. Assign owners. + +``` +## Days 1-30 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Days 31-60 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Days 61-90 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Review cadence + +[Weekly, biweekly, monthly. Who attends. What is reviewed.] +``` + +--- + +## 5. Sub-audit appendix + +Link or attach the output from each child skill: + +- Site health audit: [link or attachment] +- Backlink audit: [link or attachment] +- Keyword gap audit: [link or attachment] +- Content gap audit: [link or attachment] +- Page-level audits (top pages): [link or attachment] +- AI search readiness: [link or attachment] + +Do not paste full sub-audits into the rollup. Reference them. Stakeholders who want detail can drill in. + +--- + +## 6. Methodology notes + +``` +## Data sources and freshness + +\| Source \| Pull date \| Coverage \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Ahrefs Site Explorer \| [date] \| [scope] \| [caveats] \| +\| Ahrefs Site Audit \| [date] \| [scope] \| [caveats] \| +\| Search Console \| [date range] \| [scope] \| [caveats] \| +\| Analytics \| [date range] \| [scope] \| [caveats] \| + +## Caveats + +- Ahrefs metrics are estimates, not ground truth. +- Search Console data is sampled and capped. +- Analytics may have tagging gaps. +- Server log data was [available / unavailable] for this audit. + +## Repeatability + +To rerun this audit: + +- [Steps to reproduce data pulls] +- [Saved Ahrefs reports or filters] +- [Companion data pull instructions] +``` + +--- + +## Style guidance + +- Lead with the "so what." Stakeholders skim. +- Quantify wherever possible. Vague impact claims get ignored. +- Pair every problem with a proposed fix. Audits without recommendations are reports. +- Keep technical jargon out of the executive summary. +- Use tables and bullets. Avoid wall-of-text. + +--- + +## Common length targets by audit type + +\| Audit type \| Total length \| Executive summary \| Themes \| +\| --- \| --- \| --- \| --- \| +\| Quarterly health check \| 10-15 pages \| 1 page \| 3-4 themes \| +\| Full annual audit \| 25-40 pages \| 1-2 pages \| 5-7 themes \| +\| Pre-acquisition due diligence \| 30-50 pages \| 2 pages \| 6-10 themes \| +\| Post-migration verification \| 10-20 pages \| 1 page \| 3-5 themes \| + +--- + +## Pre-delivery checklist + +- [ ] Executive summary readable in 5 minutes +- [ ] Every theme tied to a quantified impact +- [ ] Every recommendation tied to an owner +- [ ] Quick wins called out separately +- [ ] 90-day roadmap is sequenced and resourced +- [ ] Methodology and caveats are documented +- [ ] Internal review completed before stakeholder readout +- [ ] Next audit date scheduled diff --git a/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md b/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md new file mode 100644 index 0000000..31e223d --- /dev/null +++ b/dist/pi/.agents/skills/seo-backlink-audit/SKILL.md @@ -0,0 +1,166 @@ +--- +name: seo-backlink-audit +description: "Audit a backlink profile using Ahrefs MCP data: profile health, anchor text distribution, toxic link identification, lost link reclamation, and gap analysis against competitors. Use this skill when reviewing backlink health, scoping a disavow project, recovering from a manual action, planning link building, or doing M&A due diligence on a property's link equity. Triggers on backlink audit, link profile, toxic links, disavow, anchor text analysis, lost links, link reclamation, referring domains, link gap. Also triggers when traffic decline correlates with link loss or when an unnatural link warning appears in Search Console." +category: seo-audit-suite +catalog_summary: "Profile health, anchor mix, toxic links, reclamation, gap analysis" +display_order: 2 +--- + +# SEO Backlink Audit + +Audit a backlink profile using data pulled from the Ahrefs MCP. Stack-agnostic. Produces a profile health assessment, a toxic link list (if needed), a reclamation list, and a gap analysis against competitors. + +--- + +## When to use + +- Periodic backlink health check (quarterly or biannual) +- Recovering from a Google manual action or unnatural link warning +- Scoping a disavow file +- Pre-acquisition due diligence on link equity +- Planning a link building campaign (need a baseline) +- Investigating ranking drops correlated with link loss +- Recovering lost links after a migration or replatform + +## When NOT to use + +- Building new links (use `seo-offpage`) +- General SEO audits (use `seo-audit-orchestration`) +- Keyword opportunity analysis (use `seo-keyword-gap-audit`) +- Technical issues unrelated to links (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Target property (root domain, subdomain, or URL prefix) +- Competitor set (3-5 properties with comparable strategies) +- Time window (typically last 12-24 months) +- Confirmation Ahrefs MCP is connected and has access to the property +- Search Console manual action status (if any) +- Recent SEO history (migrations, link campaigns, penalties) + +--- + +## The framework: 5 dimensions of a backlink profile + +A profile is healthy when all five dimensions are healthy. Issues in any one can cap rankings or invite penalties. + +### Dimension 1: Referring domain quality + +Volume of links matters less than the quality and relevance of the linking domains. + +Pull from Ahrefs: + +- Total referring domains (current and trended) +- Domain Rating distribution (DR bands) +- Topical relevance of linking domains +- Geographic distribution (where appropriate) +- Domain age and trust signals + +Healthy signal: a long tail of relevant, established domains. Concentration in any single source is a risk. + +### Dimension 2: Link velocity + +How fast links are gained or lost. + +Pull from Ahrefs: + +- New referring domains per month (trended 12-24 months) +- Lost referring domains per month +- Net change + +Healthy signal: steady positive growth. Sudden spikes suggest paid campaigns or negative SEO. Sudden drops correlate with redirect mistakes, content removal, or the linking sites going down. + +### Dimension 3: Anchor text distribution + +The mix of anchor types tells search engines what the property is about and whether the profile looks natural. + +Categories to map: + +- Branded (the brand name) +- Naked URL +- Generic ("click here", "this page") +- Exact-match keyword +- Partial-match keyword +- Image (alt text or none) + +Healthy signal: branded and naked URL anchors dominate. Exact-match keyword anchors are a small minority. Heavy exact-match concentration triggers spam filters. + +### Dimension 4: Link types + +Not all links are equal. + +Categories: + +- Dofollow versus nofollow +- Editorial versus directory or comment +- In-content versus footer or sidebar +- Sponsored or UGC tagged +- Redirect chains +- Lost links recoverable via outreach + +Healthy signal: editorial in-content dofollow links from relevant sites dominate. + +### Dimension 5: Competitive gap + +What links do peers have that you do not? + +Pull from Ahrefs: + +- Domains linking to 2+ competitors but not the target +- Domains linking to 1 competitor with high relevance to the target +- Top performing competitor pages by referring domain count + +Healthy signal: the gap is shrinking over time. A widening gap is a strategic risk. + +--- + +## Workflow + +1. Charter the audit. Goal, scope, time window, competitor set. +2. Pull baseline data. Referring domains, anchor text, link types, lost links, competitor overlap. +3. Map the profile across 5 dimensions. One section per dimension. +4. Identify red flags. Velocity spikes, anchor concentration, low-DR concentration, suspect TLDs, repeated footprints. +5. Build the toxic list (if needed). Use the criteria in [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md). +6. Build the reclamation list. Lost links worth recovering via outreach. +7. Build the gap list. Domains linking to peers, prioritized by relevance. +8. Synthesize. Profile health verdict, top 3 risks, top 3 opportunities. +9. Recommend. Disavow (rare), reclamation outreach, link building targets, monitoring cadence. +10. Document and hand off. Outputs feed `seo-offpage` and `seo-audit-orchestration`. + +--- + +## Failure patterns + +- Disavow happy. Most profiles do not need a disavow. Disavowing legitimate links damages rankings. Use it only after a manual action or clear algorithmic signals. +- Counting links instead of evaluating them. A profile with 10,000 referring domains can be weaker than one with 200 high-quality editorial links. +- Ignoring lost links. Recovering a lost link is faster and cheaper than building a new one. +- No competitor benchmark. Profile health is relative. A "low" backlink count for a tier-1 competitor is a "great" count for a niche site. +- Anchor text panic. A high exact-match percentage in absolute terms is fine for niche sites where the brand and keyword overlap. Investigate before disavowing. +- One-time audit. Profile health drifts. Audit on a cadence (quarterly minimum for active properties). +- Treating Ahrefs as ground truth. Ahrefs sees most links but not all. Triangulate with Search Console for completeness. +- Over-indexing on Domain Rating. DR is a relative metric, not a quality signal. A DR-30 niche site can be more valuable than a DR-80 generalist. + +--- + +## Output format + +A backlink audit document with: + +1. Executive summary. Profile health verdict and top risks. +2. Profile snapshot. Key metrics: referring domains, DR distribution, anchor mix, velocity. +3. 5-dimension analysis. One section per dimension with findings. +4. Toxic link list. If needed. Disavow file ready format. +5. Reclamation list. Lost links worth recovering, with contact paths. +6. Gap list. Top 50 domains linking to competitors but not target. +7. Recommendations. Disavow (Y/N), reclamation outreach plan, link building targets. +8. Methodology. Data sources, pull dates, criteria used. + +Length: 8-15 pages depending on profile complexity. + +--- + +## Reference files + +- [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md) - Decision framework for classifying a link as toxic, including the disavow file format and threshold guidance. diff --git a/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md b/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md new file mode 100644 index 0000000..8e26d42 --- /dev/null +++ b/dist/pi/.agents/skills/seo-backlink-audit/references/toxic-link-criteria.md @@ -0,0 +1,182 @@ +# Toxic link criteria + +A decision framework for classifying a backlink as toxic and worth disavowing. Bias the framework toward keeping links unless the case is clear. Disavowing legitimate links damages rankings. + +--- + +## The disavow bar + +Disavow when one or more of the following is true: + +1. The site has been hit with an algorithmic devaluation that correlates with link-based signals. +2. The site has received a manual action citing unnatural links. +3. There is clear evidence of a negative SEO attack with low-quality links pointed at the property. +4. Pre-acquisition due diligence on a property reveals a known toxic profile. + +Outside these cases, the default is to leave links alone. Google has stated repeatedly that they ignore most low-quality links automatically. + +--- + +## Per-link signals (any one is concerning, multiple is decisive) + +### Site-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Site is in a known link network \| High \| +\| Site exists primarily to host links \| High \| +\| Site has thin or auto-generated content \| High \| +\| Site is on a suspect TLD pattern (mass registered) \| Medium \| +\| Site has no organic traffic per Ahrefs estimates \| Medium \| +\| Site is in an irrelevant language or geography \| Medium \| +\| Site has been deindexed or penalized \| High \| +\| Site is parked or for sale \| High \| +\| Site has a footprint shared with many other suspect sites \| High \| + +### Page-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Page is a low-effort link page or directory \| Medium \| +\| Page has a high outbound link count with no editorial logic \| Medium \| +\| Page is hidden from the site's main navigation \| Medium \| +\| Page is in a foreign language with no relevance \| Medium \| +\| Page has been hacked or is serving malware \| High \| + +### Link-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Anchor text is exact-match commercial and unnatural in context \| High \| +\| Link is in a footer with hundreds of others \| Medium \| +\| Link is part of a sitewide footer link \| Medium \| +\| Link is in a comment with promotional text \| Low \| +\| Link is paid without disclosure \| High \| + +--- + +## Deciding by domain versus by URL + +Disavow at the domain level when: + +- The entire site is suspect. +- Multiple pages from the same site link to you. +- You expect the site to keep adding links. + +Disavow at the URL level when: + +- Only one specific page is suspect on an otherwise legitimate site. +- The site has editorial credibility but a single contributor placed the link. + +Default to domain-level disavow when in doubt. URL-level disavows are fragile: the site can move the content and the disavow no longer applies. + +--- + +## Outreach before disavow + +Disavow is a last resort. Before disavowing, attempt outreach for high-value but problematic links: + +1. Find a contact (whois, contact page, social). +2. Send a polite link removal request. +3. Wait 14 days. +4. Send a follow-up. +5. If no response after 30 days, disavow. + +Document outreach attempts. If a manual action review is needed later, Google requires evidence of cleanup effort beyond just a disavow file. + +--- + +## Disavow file format + +The disavow file is a plain text file submitted to Google Search Console. + +Format: + +``` +# Disavow file for [property] +# Last updated: [date] +# Submitted: [date or pending] + +# Section 1: Domain-level disavows + +domain:lowqualitysite-example.com +domain:linkfarm-example.net +domain:hackedsite-example.org + +# Section 2: URL-level disavows + +https://otherwiselegitimate-example.com/sponsored-post-page + +# Section 3: Notes for future me + +# - Disavowed lowqualitysite-example.com after manual action 2024-03 +# - Reviewed quarterly +``` + +Rules: + +- One entry per line +- `domain:` prefix for domain-level +- Full URL for URL-level +- Lines starting with `#` are comments and ignored +- File must be UTF-8 plain text +- Maximum 100,000 lines or 2 MB + +--- + +## Bulk classification heuristic + +When auditing thousands of referring domains, use this triage: + +### Round 1: filter obvious keepers + +Mark as KEEP without further review: + +- Domain Rating above a relevance-appropriate threshold and topical match +- Known media, government, education domains +- Linking from a page with organic traffic + +Skip these. They are not toxic. + +### Round 2: filter obvious toxics + +Mark as TOXIC for further review: + +- Domain Rating zero with no organic traffic +- TLDs in known spam patterns +- Domains matching known link network footprints +- Sites that link to thousands of unrelated properties + +### Round 3: review the middle + +The remaining domains need manual review. Apply the per-link signal table above. + +Expected breakdown for a healthy profile: 80%+ keep, 5-15% review, under 5% toxic. If toxic exceeds 20%, the profile has structural problems beyond a disavow. + +--- + +## After disavow + +- Submit the file in Search Console. +- Document submission date in your audit log. +- Wait 4-8 weeks before evaluating impact. +- Recrawl can take longer for larger sites. +- Do not submit revised disavows weekly. Submit, wait, evaluate. + +If a manual action was the trigger, file a reconsideration request with: + +- Summary of the cleanup effort +- Evidence of outreach attempts +- The submitted disavow file +- An honest acknowledgment of the cause + +--- + +## Common mistakes + +- Disavowing low-traffic links indiscriminately. Most have no negative effect. Disavowing them can lose minor positive equity. +- Disavowing competitor links by accident. Double-check the file before submission. +- Forgetting that disavow is reversible. Resubmit a file without the entry to remove a disavow. Test cautiously. +- Treating disavow as a recurring task. It is not. Audit and submit when needed. Otherwise leave it alone. +- Disavowing without documenting why. Six months later you will not remember which entries were intentional. +- Using disavow as a substitute for outreach. For high-value links, removal is better than disavow. diff --git a/dist/pi/.agents/skills/seo-competitor/SKILL.md b/dist/pi/.agents/skills/seo-competitor/SKILL.md new file mode 100644 index 0000000..39e585d --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/SKILL.md @@ -0,0 +1,137 @@ +--- +name: seo-competitor +description: "Run a competitive SEO analysis comparing the user's site to chosen competitors across SERP overlap, content depth, backlink profiles, technical posture, and brand presence. Use this skill whenever the user wants to analyze competitors, find content gaps, identify backlink opportunities, understand why competitors outrank them, or benchmark against the rest of their category. Triggers on competitor analysis, competitive analysis, SERP analysis, content gap, backlink gap, why is X ranking, who is winning the SERP, beat my competitor, benchmark, market positioning. Also triggers when planning a content strategy and the question 'what are competitors doing' is implicit." +category: seo-foundation +catalog_summary: "SERP overlap, content gaps, backlink gaps, technical comparison" +display_order: 4 +--- + +# SEO Competitor Analysis + +Compare a site to its competitors and find the gaps worth closing. Stack-agnostic. Tool-friendly but tool-optional. + +--- + +## When to use + +- Identifying which competitors to study +- Finding content gaps (topics they cover, you do not) +- Finding backlink gaps (sites linking to them, not you) +- Understanding why a specific competitor outranks the user +- Benchmarking authority, technical posture, and content depth + +## When NOT to use + +- Single-page optimization (use `seo-onpage`) +- Initial keyword research with no competitors yet identified (use `seo-keyword` first to find them) +- Auditing one's own existing content (use `seo-content-audit`) + +--- + +## Required inputs + +- The user's site +- 3 to 5 named competitors (or the topic area, if competitors are not yet identified) +- Access to a keyword tool, a backlink tool, and any crawler + +If competitors are unknown, start by listing the top 10 ranking domains for the user's top 10 priority keywords. Pick the 3 to 5 that appear most often. + +Where competitor traffic estimation is the input you need (relative scale, channel mix, audience overlap), Similarweb MCP is the strongest source. Pair with Ahrefs (for backlink and keyword overlap) and Semrush (for SERP feature presence and SEO-PR overlap). Each platform gives a different cut of the same competitive landscape; using them together produces sharper signal than any one alone. + +--- + +## The framework: 5 angles + +Competitor analysis covers five angles. Run all five for a full picture, or pick two or three for a focused investigation. + +### 1. SERP overlap +Where do you and the competitor compete head-to-head? + +- For each priority keyword, who ranks in the top 10? +- For each top-10 ranking, what page type wins (article, product, comparison, video)? +- Are there SERP features (featured snippet, AI overview, video, image pack) one party holds and the other does not? +- Which queries do competitors rank for that the user does not? (the content gap) + +### 2. Content depth +What does their winning content look like? + +- Word count and structure of their top-ranking pages +- Information types they include (data tables, original research, video, calculators, downloadable assets) +- Update frequency on key pages (last modified date, change history) +- Internal linking patterns (do their winning pages link to commercial pages?) +- Topical breadth (how many related topics do they cover?) + +### 3. Backlink profile +Where does their authority come from? + +- Total referring domains +- Domain rating (or equivalent authority metric) +- Top 50 referring pages by traffic value +- Backlink types (editorial, directory, partner, paid, spam) +- Link velocity (gaining or losing referring domains over time) +- Pages on their site attracting the most links (these are their "linkable assets") + +### 4. Technical posture +How clean is their technical foundation? + +- Core Web Vitals (LCP, INP, CLS) +- Mobile usability +- Schema implementation (which types, on which page types) +- Site architecture and internal linking density +- Crawl efficiency (are they wasting crawl budget?) +- HTTPS, security headers +- llms.txt and AI search readiness + +### 5. Brand and entity strength +How well-known are they outside organic search? + +- Branded search volume (how many people search their name?) +- Entity recognition in knowledge graph (do they have a Wikipedia page, knowledge panel, structured data feeding entity status?) +- Mention frequency in their topic area (PR coverage, podcast appearances, citations) +- Social signals (followers, engagement, share rates) +- Reviews and reputation + +--- + +## Workflow + +1. Confirm the competitors. Either named, or derive from SERP overlap on top 10 priority keywords. +2. Pick the angles. Run all 5 for a full audit, or 2 to 3 for a focused dive. +3. Pull the data. Keyword tool exports, backlink tool exports, manual SERP inspection, technical crawl. +4. Score each angle. Where does the user lead? Where do they trail? +5. Identify gaps. Specific content gaps, specific backlink gaps, specific technical gaps. +6. Prioritize. Which gaps are highest leverage to close? (Big traffic potential, achievable effort, strategic fit.) +7. Write the report. Use the template in [`references/competitive-audit-template.md`](references/competitive-audit-template.md). + +--- + +## Failure patterns + +- Picking the wrong competitors. A site that outranks you on one keyword but operates a different business is not a competitor. Pick by SERP overlap and audience overlap, not by who you think you compete with. +- Treating "more content" as the takeaway. They are not winning because they have 500 articles. They are winning because of specific content + links + UX. Find the actual lever. +- Copying their pages verbatim. Diminishing returns. Beat them by being more useful, not by paraphrasing them. +- Ignoring brand strength. A weaker site with a stronger brand wins on branded queries you cannot touch with content alone. +- Static analysis. Re-run the analysis at least annually. Competitor strategies shift. + +--- + +## Output format + +Default output is a markdown report at `competitive-analysis.md` plus accompanying spreadsheets for the keyword and backlink data. + +Structure: +1. Executive summary (3 to 5 critical findings) +2. Competitor profiles (one per competitor, brief) +3. SERP overlap analysis +4. Content gap analysis +5. Backlink gap analysis +6. Technical comparison +7. Brand and entity comparison +8. Prioritized gap-closing roadmap + +--- + +## Reference files + +- [`references/competitive-audit-template.md`](references/competitive-audit-template.md) - Fillable competitive audit template. +- [`references/content-gap-method.md`](references/content-gap-method.md) - Detailed methodology for finding content gaps with example. diff --git a/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md b/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md new file mode 100644 index 0000000..556d013 --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/references/competitive-audit-template.md @@ -0,0 +1,160 @@ +# Competitive SEO Analysis: [Your Site] vs Competitors + +Date: [YYYY-MM-DD] +Site under audit: [URL] +Competitors analyzed: [List] +Analyst: [Name] + +--- + +## Executive summary + +[3 to 5 critical findings. Lead with the most important. What is the single biggest gap to close, and what is the single biggest strength to defend?] + +Top 3 priorities: +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Competitor profiles + +### Competitor 1: [Name] +- Domain rating: [X] +- Estimated organic traffic: [X / month] +- Total referring domains: [X] +- Top 3 ranking categories: [What they win on] +- Why they matter: [1 to 2 sentences] +- Their key advantage over us: [1 sentence] + +### Competitor 2: [Name] +[Same structure] + +### Competitor 3: [Name] +[Same structure] + +--- + +## SERP overlap analysis + +Keywords where we both rank top 10: [N] +Keywords where they rank, we don't: [N] +Keywords where we rank, they don't: [N] +Keywords where they hold a SERP feature we don't: [N] + +### Head-to-head wins +[Top 10 keywords where we currently rank above them] + +\| Keyword \| Our rank \| Their rank \| Volume \| +\|---\|---\|---\|---\| +\| \| \| \| \| + +### Head-to-head losses +[Top 10 keywords where they rank above us] + +\| Keyword \| Our rank \| Their rank \| Volume \| Likely reason they win \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +### Their territory (we don't rank) +[Top 20 keywords they rank for that we don't, ranked by traffic potential] + +\| Keyword \| Their rank \| Volume \| Difficulty \| Strategic fit for us \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +--- + +## Content gap analysis + +[Topics or page types they cover that we don't, organized by theme.] + +### Theme 1: [e.g., "How-to guides for beginners"] +- Their coverage: [X pages, including these top performers...] +- Our coverage: [None / weak / partial] +- Estimated traffic value if closed: [X visits/month] +- Recommended action: [Produce / partial coverage / skip] + +### Theme 2: [e.g., "Comparison content"] +[Same structure] + +--- + +## Backlink gap analysis + +Their referring domains we don't have: [N] +Their unique referring domains (in our category): [N] + +### Top 10 backlink opportunities +[Domains linking to multiple competitors but not us. These are the highest-probability outreach targets.] + +\| Domain \| Domain rating \| Links to (competitors) \| Why they link to them \| +\|---\|---\|---\|---\| +\| \| \| \| \| + +### Their linkable assets +[Pages on competitor sites that attract the most backlinks. These are the asset types we could replicate.] + +\| URL \| Referring domains \| Asset type \| +\|---\|---\|---\| +\| \| \| \| + +--- + +## Technical comparison + +\| Dimension \| Us \| Comp 1 \| Comp 2 \| Comp 3 \| +\|---\|---\|---\|---\|---\| +\| LCP (mobile) \| \| \| \| \| +\| INP (mobile) \| \| \| \| \| +\| CLS (mobile) \| \| \| \| \| +\| Mobile-friendly \| \| \| \| \| +\| HTTPS / HSTS \| \| \| \| \| +\| Schema types \| \| \| \| \| +\| Sitemap quality \| \| \| \| \| +\| llms.txt present \| \| \| \| \| +\| Internal links per page (avg) \| \| \| \| \| + +Key takeaways: [Where are we ahead, where are we behind?] + +--- + +## Brand and entity comparison + +\| Dimension \| Us \| Comp 1 \| Comp 2 \| Comp 3 \| +\|---\|---\|---\|---\|---\| +\| Branded search volume \| \| \| \| \| +\| Wikipedia entity \| \| \| \| \| +\| Knowledge panel \| \| \| \| \| +\| Editorial mentions / month \| \| \| \| \| +\| Social following \| \| \| \| \| +\| Reviews aggregate \| \| \| \| \| + +--- + +## Prioritized gap-closing roadmap + +[Sequenced list of actions, with effort and expected impact.] + +### Quarter 1 +1. [Action] - [effort] - [expected impact] +2. [Action] - [effort] - [expected impact] + +### Quarter 2 +1. [Action] + +### Quarter 3+ +[Strategic plays that take longer to execute.] + +--- + +## What we should defend + +Areas where we currently lead and need to maintain: + +- [Strength] +- [Strength] +- [Strength] + +A defensive strategy is as important as a gap-closing one. diff --git a/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md b/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md new file mode 100644 index 0000000..f7f0083 --- /dev/null +++ b/dist/pi/.agents/skills/seo-competitor/references/content-gap-method.md @@ -0,0 +1,225 @@ +# Content Gap Method + +A detailed methodology for finding content gaps between your site and competitors. The output is a prioritized list of topics or queries the competition ranks for and you do not, ranked by opportunity. + +This is the methodology. For the orchestrated version that runs against the Ahrefs MCP, use `seo-content-gap-audit`. + +--- + +## What a content gap is (and is not) + +A content gap is a query or topic where: + +- One or more competitors rank in the top 10 +- You do not rank in the top 100 (or rank weakly) +- The query is plausibly something your audience cares about +- You could credibly produce content that addresses it + +A content gap is not: + +- Every keyword a competitor ranks for. Many of those will not match your audience. +- Branded queries for the competitor. You will never rank for "[CompetitorName] login" and should not try. +- Queries with unwinnable SERPs (dominated by Reddit, video, or marketplace listings) unless you have an unusual asset. + +--- + +## Step 1: define the competitor set + +Three categories of competitors. Include all three. + +### Direct competitors + +Same product, same audience. Found in your "industry," your sales process, your churn data. + +### Search competitors + +Whoever ranks for the queries you care about. Often surprising. Often includes industry publications, aggregators, and adjacent SaaS tools you do not consider competition commercially. + +To find search competitors: + +1. Pull your top 20 priority queries. +2. Note the top 10 ranking domains for each. +3. Aggregate. Domains that appear 5+ times are search competitors, even if they are not direct. + +### Aspirational competitors + +Brands that own the topic-area you want to own. Often larger or older. Useful for surfacing topics, less useful for direct comparison. + +Build a final set of 5-10 competitors. More than that gets noisy. + +--- + +## Step 2: pull keyword data + +For each competitor, pull the queries they rank for in the top 10 (or top 20 for completeness). + +Filter out: + +- Branded queries containing the competitor name +- Queries with monthly volume below your relevance threshold (commonly 50-100, lower for niche industries) +- Queries with no clear commercial or informational intent (typos, location-specific irrelevant queries, etc.) +- Queries with parent topic that does not apply to your business + +Tools: Ahrefs Site Explorer (Organic keywords), Semrush Organic Research, or DataForSEO equivalents. + +--- + +## Step 3: build the gap matrix + +Cross-reference all competitors against your site. + +\| Query \| Competitor 1 position \| Competitor 2 position \| Competitor 3 position \| Your position \| Monthly volume \| Difficulty \| +\|---\|---\|---\|---\|---\|---\|---\| +\| query a \| 3 \| 7 \| - \| 45 \| 1,200 \| 32 \| +\| query b \| 5 \| 4 \| 8 \| not ranking \| 800 \| 28 \| +\| query c \| 1 \| - \| 5 \| 12 \| 500 \| 41 \| + +Three categories emerge: + +- Pure gaps: competitors rank, you do not. Highest opportunity. Filter for queries where 2+ competitors rank. +- Weak coverage: you rank but poorly (positions 11-50). Often the fastest wins. +- Saturated topics: you and 1+ competitors all rank well. Defensive territory; opportunity to leapfrog. + +Focus the next steps on Pure gaps and Weak coverage. + +--- + +## Step 4: cluster by topic + +Raw query lists are unmanageable. Cluster by topic so you can plan content, not chase individual keywords. + +### Method + +Group queries that share intent and can be answered by the same piece of content. + +- "best crm for startups," "top crm small business," "crm software comparison" - one cluster, one comparison piece. +- "how to choose a crm," "crm buying guide" - same cluster. +- "what is a crm," "crm definition" - separate cluster (top-of-funnel, glossary or pillar lead-in). + +A cluster is one piece of content (or a closely-related set: pillar + spokes). + +### Output + +\| Cluster \| Sample queries \| Total monthly volume \| Avg difficulty \| Recommended format \| Lead competitor \| +\|---\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| \| +\| \| \| \| \| \| \| + +--- + +## Step 5: assess each cluster + +For each cluster, answer: + +### Audience fit + +Does this cluster match your audience? If you sell to enterprise but the cluster is dominated by SMB intent ("free crm for solopreneurs"), score it low. + +### SERP analysis + +Open the SERP for the highest-volume query in the cluster. Note: + +- Result types: organic blue links, video, AI overview, featured snippet, local pack, shopping. Some SERPs leave little real estate for new entrants. +- Result formats: what kind of pages rank? Blog posts, comparison pages, product pages, free tools, video? +- Domain mix: dominated by big publishers (HubSpot, Forbes), niche players, Reddit, or peer companies? +- SERP volatility: has the top 10 been stable, or churning? + +### Effort estimate + +How long would it take to produce content competitive with what is ranking? Be honest. Some clusters need a 4,000-word definitive guide with original research. Others need a 1,200-word how-to. + +### Scoring + +Combine into a simple opportunity score per cluster. Example: + +``` +Opportunity = (Volume × Audience Fit × SERP Winnability) / Effort +``` + +Where: + +- Volume: total monthly volume across cluster +- Audience Fit: 1 (poor), 2 (decent), 3 (perfect match) +- SERP Winnability: 1 (saturated, big domains), 2 (mixed), 3 (gettable) +- Effort: hours of writing, research, asset creation + +This is not a precise formula. Use it to rank clusters, then sanity-check the top of the list against editorial judgment. + +--- + +## Step 6: produce the gap report + +A typical output deliverable: + +### Section 1: executive summary + +- Top 10 clusters ranked by opportunity score +- Estimated total monthly traffic potential if you captured the average competitor position +- Estimated effort (in hours or pieces of content) to address the top 10 + +### Section 2: cluster details + +For each top cluster: + +- Cluster name and theme +- Sample queries with volume and difficulty +- SERP analysis snapshot +- Lead competitor's content URL with a one-line note on what makes it strong +- Recommended content format and length +- Recommended hook or angle +- Estimated effort +- Why we should rank: the unique asset, perspective, or data we can bring + +### Section 3: clusters to skip + +Clusters that surfaced but should not be pursued, with the reason. (Audience mismatch, SERP unwinnable, etc.) Documenting skips prevents re-litigation. + +### Section 4: next steps + +- Hand-off to `content-strategy` for editorial planning +- Production sequencing (which cluster ships first) +- Measurement: how will you track whether the gap is closing + +--- + +## Worked example + +Site: B2B project management tool, 50-person company, target audience is engineering leads at series-B SaaS startups. + +Competitors (5): +1. Linear (direct, peer) +2. Jira (direct, incumbent) +3. Notion (adjacent, encroaching) +4. Asana (direct, larger) +5. Height (direct, peer) + +### Gap matrix excerpt + +\| Cluster \| Sample queries \| Volume \| Difficulty \| Lead competitor \| Audience fit \| SERP winnable \| Effort \| Opportunity \| +\|---\|---\|---\|---\|---\|---\|---\|---\|---\| +\| "linear vs jira" \| 5,400 \| 38 \| linear.app \| High \| Mixed \| Med \| High \| +\| "engineering project management" \| 2,100 \| 42 \| linear.app \| High \| Big domains \| Med \| High \| +\| "agile sprint planning" \| 14,000 \| 55 \| atlassian.com \| Med \| Saturated by Atlassian \| High \| Low \| +\| "github issue templates" \| 3,200 \| 28 \| github.com \| High \| Owned by github.com \| Med \| Skip \| + +### Recommendations + +- Pursue: "linear vs jira" cluster (5 related comparison queries, 7,200 combined monthly volume, mid-effort, audience-perfect). Format: comparison page anchored by an internal POV piece. +- Pursue: "engineering project management" cluster (broader topic, 4 related queries, requires a pillar piece + 3 spokes). Format: pillar guide + spokes. +- Skip: "agile sprint planning." Atlassian owns this with deep, mature content; effort to compete is too high vs opportunity. +- Skip: "github issue templates." github.com itself ranks #1; even strong content will not displace. + +### Next steps + +- Hand the two pursued clusters to content-strategy for editorial sequencing. +- Track positions weekly for the cluster's primary queries. +- Re-run the gap analysis quarterly to spot new gaps as competitors publish. + +--- + +## When to re-run + +- Quarterly as a routine. +- After a major competitor launch (new product page, big content push, redesign). +- After a search algorithm update (especially core updates that reshuffle SERPs). +- When entering a new audience segment (segment-specific competitors emerge). diff --git a/dist/pi/.agents/skills/seo-content-audit/SKILL.md b/dist/pi/.agents/skills/seo-content-audit/SKILL.md new file mode 100644 index 0000000..36ecee8 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/SKILL.md @@ -0,0 +1,193 @@ +--- +name: seo-content-audit +description: "Audit existing content across a site to decide what to keep, update, merge, redirect, or delete. Use this skill whenever the user wants to audit existing content, fix content decay, resolve keyword cannibalization, prune underperforming pages, prioritize content updates, or apply a keep/update/merge/redirect/delete framework to a content library. Triggers on content audit, content decay, content refresh, cannibalization, keyword cannibalization, prune content, delete pages, redirect old pages, content inventory, what to keep, what to update, content scorecard, evergreen refresh. Also triggers when traffic is dropping site-wide and the cause might be content quality, even if 'audit' is not said explicitly." +category: seo-foundation +catalog_summary: "Keep/update/merge/redirect/delete decisions across a site" +display_order: 6 +--- + +# Content Audit + +Inventory existing content, score it, and decide for each piece: keep, update, merge, redirect, or delete. Stack-agnostic. Works on blogs, marketing sites, knowledge bases, and product content. + +--- + +## When to use + +- Inheriting a content library you did not create +- Diagnosing site-wide traffic decline +- Resolving cannibalization (two pages competing for the same query) +- Pre-migration cleanup +- Annual or semi-annual content health check +- Pruning before a redesign or replatform + +## When NOT to use + +- Optimizing a single page (use `seo-onpage`) +- Planning new content (use `seo-keyword`) +- Comparing your content to competitors (use `seo-competitor`) +- Site-level technical issues (use `seo-technical`) + +--- + +## Required inputs + +- The site URL and access to crawl it (or a complete URL list) +- Search console access (or a 12-month export) +- Analytics access (sessions, conversions, engagement) +- A backlink tool (to identify pages with referring domains worth preserving) + +--- + +## The framework: 5 actions + +For every content piece, the audit produces one of five decisions. + +### 1. Keep +The page performs well, has clear intent, and needs no changes. + +Signals: +- Top 10 ranking for its primary query +- Consistent traffic with no decay +- Healthy engagement (above-site-average time on page or interaction rate) +- Up-to-date information + +### 2. Update +The page has potential but is underperforming due to fixable issues. + +Signals: +- Page 2 ranking for high-value queries (rank 11 to 30) +- Traffic decay over the last 6 to 12 months +- Information gone stale +- Title or meta need rewriting for CTR +- Thin content that could expand to match competitor depth +- Missing schema or other technical hygiene + +### 3. Merge +Two or more pages target overlapping queries and should consolidate. + +Signals: +- Cannibalization (multiple pages ranking for the same query, none ranking well) +- Significant content overlap between pages +- Combined, they would outperform either alone +- Both have backlinks worth preserving + +### 4. Redirect +The page has no future but has assets (links, equity) worth preserving. + +Signals: +- No traffic, no rankings +- Holds backlinks (especially editorial ones) +- A relevant target page exists that would benefit from the equity +- Topic is still relevant but this specific page is not + +### 5. Delete (and let return 404 or 410) +The page has no future and no assets worth preserving. + +Signals: +- No traffic, no rankings, no backlinks +- Content is outdated and not worth updating +- Topic is no longer relevant +- Even thin or spam content from a previous era + +Note: In most cases, return 410 (gone) for intentionally deleted content. 410 is processed faster than 404 and signals the deletion was deliberate. + +--- + +## Scoring inputs + +Pull these for every URL before deciding: + +\| Metric \| Source \| Threshold for "low" \| +\|---\|---\|---\| +\| Sessions (last 90 days) \| Analytics \| <10/month \| +\| Organic traffic (last 90 days) \| Search console or analytics \| <5/month \| +\| Average position for top query \| Search console \| >30 \| +\| Impressions (last 90 days) \| Search console \| <100/month \| +\| Click-through rate \| Search console \| <1% (when impressions exist) \| +\| Referring domains \| Backlink tool \| 0 \| +\| Engagement (avg time on page) \| Analytics \| <30 seconds \| +\| Last meaningful update \| Manual / git \| >24 months \| +\| Word count \| Crawler \| <300 (for articles) \| +\| Internal links in \| Crawler \| 0 \| + +A page can survive low scores on a few metrics. A page that fails on most is a delete or redirect candidate. + +--- + +## Decision matrix + +A simplified decision tree: + +``` +Has traffic? ─── Yes ──── Recent decay? ─── Yes ── UPDATE + │ │ + │ └── No ─── KEEP + │ + └── No ──── Has backlinks? ─── Yes ── Has relevant target? ─── Yes ── REDIRECT + │ │ + │ └── No ─── UPDATE (rebuild) + │ + └── No ──── Cannibalizing another page? ─── Yes ── MERGE + │ + └── No ─── DELETE (410) +``` + +For overlapping pages, "merge" usually wins over "delete" because it preserves both link equity and any topical authority. + +--- + +## Workflow + +1. Inventory. Pull a complete URL list from the crawl, sitemap, and search console (some indexed pages may not be in the sitemap). +2. Pull the metrics. Sessions, organic, search console rank/CTR, backlinks, last-modified date, word count. +3. Score each URL. Use the framework. Mark a decision: Keep / Update / Merge / Redirect / Delete. +4. Identify cannibalization clusters. Group URLs targeting the same query. Decide which becomes the canonical, what to merge, what to redirect. +5. Sequence the work. Do redirects and deletes in batches. Plan updates by priority (highest-traffic-recovery potential first). +6. Implement. With change tracking. Re-crawl after each batch to confirm no broken redirect chains. +7. Measure. Track aggregate organic traffic 30, 60, 90 days post-audit. + +--- + +## Failure patterns + +- Deleting pages with backlinks. Always check referring domains before deleting. A redirect preserves equity at near-zero cost. +- Updating pages that should be merged. Two thin pages updated to medium pages still cannibalize. Merge first. +- Merging without preserving the better URL. Pick the merge target by which URL has stronger signals (older URL, more backlinks, better URL slug, currently better ranking), not which one has more content. +- Mass-deleting low-traffic pages. Some have value: fresh pages still ramping, niche pages serving a specific audience, evergreen pages with seasonal traffic. Do not bulk-delete by sessions alone. +- Over-aggressive pruning of "old" content. Date alone is not a delete signal. Topic relevance and intent quality are. +- No post-audit measurement. Without measurement, you cannot tell if the audit worked. + +--- + +## Output format + +Default output: a spreadsheet with one row per URL, plus a summary markdown report. + +Spreadsheet columns: +- URL +- Page type (article, product, category, etc.) +- Sessions (90d), organic clicks (90d), impressions (90d), avg position +- Referring domains +- Word count +- Last modified +- Decision (keep / update / merge / redirect / delete) +- Merge target / redirect target (if applicable) +- Priority (1-5) +- Notes + +Summary report: +1. Inventory totals (URLs by decision) +2. Cannibalization clusters identified +3. Top 20 update priorities +4. Redirect map (CSV) +5. Delete list +6. Implementation roadmap (sequenced by priority) +7. Measurement plan + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Spreadsheet column definitions and report template. +- [`references/cannibalization-resolution.md`](references/cannibalization-resolution.md) - Detailed methodology for resolving cannibalization clusters. diff --git a/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md b/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md new file mode 100644 index 0000000..246de40 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/references/audit-template.md @@ -0,0 +1,223 @@ +# Content Audit Template + +Spreadsheet column definitions and report template for a site-wide content audit. The output is a per-URL decision (keep / update / merge / redirect / delete) plus a summary report for stakeholders. + +--- + +## What this audit produces + +- A spreadsheet (one row per URL) with all signals and the final decision +- A report that summarizes the decisions, the rationale, and the next-step backlog +- A roll-up of expected SEO impact and effort + +--- + +## Required spreadsheet columns + +Every row is one URL. Every column below is required. + +\| Column \| Type \| Source \| Description \| +\|---\|---\|---\|---\| +\| URL \| Text \| Crawl \| Full URL \| +\| Title tag \| Text \| Crawl \| Current `<title>` \| +\| H1 \| Text \| Crawl \| Current H1 \| +\| Word count \| Number \| Crawl \| Body text words \| +\| Publish date \| Date \| CMS / inferred \| Original publish date \| +\| Last updated \| Date \| CMS \| Most recent meaningful update \| +\| Page type \| Pick list \| Manual / patterned URL \| Article / product / category / landing / utility / legal / etc. \| +\| Topic cluster \| Pick list \| Manual \| Which topic cluster (from content strategy) \| +\| Primary query target \| Text \| Manual / GSC top query \| The query the page should rank for \| +\| Sessions (last 90d) \| Number \| Analytics \| Organic sessions \| +\| Conversions (last 90d) \| Number \| Analytics \| Goal completions attributable to this URL \| +\| Top ranking position \| Number \| GSC / rank tracker \| Best position achieved in last 90d \| +\| Average position \| Number \| GSC \| Average position in last 90d \| +\| Impressions (last 90d) \| Number \| GSC \| \| +\| CTR (last 90d) \| Number \| GSC \| \| +\| Backlinks (referring domains) \| Number \| Backlink tool \| \| +\| Internal inlinks \| Number \| Crawl \| Number of internal pages linking to this URL \| +\| Last meaningful traffic \| Date \| Analytics \| Most recent month with traffic above threshold \| +\| Decision \| Pick list \| Manual \| Keep / Update / Merge / Redirect / Delete \| +\| Reasoning \| Text \| Manual \| One sentence per decision \| +\| Action notes \| Text \| Manual \| What needs to happen if Update or Merge \| +\| Owner \| Person \| Manual \| Who executes \| +\| Target completion \| Date \| Manual \| When the action ships \| +\| Status \| Pick list \| Manual \| Backlog / In progress / Shipped / Verified \| + +--- + +## Optional but recommended columns + +\| Column \| Description \| +\|---\|---\| +\| Cannibalization risk \| Other URLs ranking for the same primary query. See `cannibalization-resolution.md`. \| +\| Schema present \| Yes / No / Type \| +\| Has index tag \| Indexable / noindex \| +\| Status code \| 200 / 301 / 404 etc. (catches accidental noindex or broken pages) \| +\| Time on page \| From analytics; rough engagement signal \| +\| Bounce rate or scroll depth \| From analytics \| +\| Current canonical \| Self / other URL \| +\| Image count \| Helps identify thin pages \| +\| Outbound external links \| \| +\| Topic authority signal \| Original research, expert author, structured comparison, etc. - subjective but useful \| + +--- + +## The 5 decision types + +### Keep + +Page is performing or recently published. No action needed. Track for future audits. + +Default for: +- Top 20% of pages by sessions +- Pages within 3 months of publish (too early to judge) +- Cornerstone pages with strong rankings or backlinks + +### Update + +Page is on the right topic but has decayed (rankings down, content stale, broken links, missing schema). + +Action: add to the editorial backlog with a specific update brief. Common updates: refresh examples and dates, expand thin sections, add new H2s for related queries surfacing in GSC, improve title and meta, add schema, update screenshots and links. + +### Merge + +Two or more pages cover the same intent and split signals. Combine into one stronger page. + +Action: pick the canonical winner (usually the one with more backlinks and more search visibility), redirect the loser(s) to the winner, fold the loser's unique content into the winner. + +### Redirect + +Page no longer relevant but has equity (backlinks, traffic, internal links) worth preserving. + +Action: 301 redirect to the closest topical match. If no match exists, redirect to the parent category or topic hub. Avoid blanket redirects to homepage (Google often treats them as soft 404s). + +### Delete + +Page has no traffic, no rankings, no backlinks, no internal links pointing to it, and no strategic role. + +Action: return 410 Gone (preferred) or 404 if 410 is not supported. Update sitemap. Remove internal links pointing to the deleted page. + +### Decision tree + +``` +Page is performing well? +├── Yes → Keep +└── No → Page is on a relevant topic? + ├── Yes → Page is the only one on this topic? + │ ├── Yes → Update (refresh and expand) + │ └── No → Merge (consolidate into stronger version) + └── No → Page has equity (backlinks, internal links)? + ├── Yes → Redirect to closest topical match + └── No → Delete (410 Gone) +``` + +--- + +## Triage thresholds + +The audit looks at hundreds or thousands of URLs. Triage thresholds let you focus. + +### Performing (default Keep) + +- 100+ organic sessions in last 90 days, OR +- 1+ conversions in last 90 days, OR +- 10+ referring domains, OR +- Average position 1-10 for primary query + +### Decaying (default Update or Merge) + +- 5-100 sessions in last 90 days +- Average position 11-50 +- Last meaningful traffic 6-24 months ago + +### Dormant (default Redirect or Delete) + +- 0-5 sessions in last 90 days +- Average position 51+ +- Last meaningful traffic 24+ months ago + +These are starting points. Adjust to your site's volume. + +--- + +## Cannibalization check + +For each primary query target, group URLs targeting the same query. If 2+ URLs target the same query: + +- One ranking, one not: the non-ranking one is a Merge or Redirect candidate. +- Both ranking but neither in top 5: classic split-signal case. Merge into one definitive page. +- One ranking strong, one ranking weak: the weak one is a Merge candidate. + +For deeper diagnosis and resolution patterns, see `cannibalization-resolution.md`. + +--- + +## Report template + +The audit produces a stakeholder-readable report. + +### Section 1: executive summary + +- Total URLs audited +- Decisions: Keep / Update / Merge / Redirect / Delete (with counts and percentages) +- Estimated SEO impact: traffic preserved, traffic potential unlocked, traffic risk if action delayed +- Estimated effort: hours of writing, engineering URL work, design work + +### Section 2: decisions by topic cluster + +Per cluster: how many pages, decisions, top action items. + +### Section 3: top opportunities + +The 10-20 highest-leverage actions (typically Updates and Merges that protect strong rankings or unlock obvious wins). + +### Section 4: risks if no action + +What happens if the team does not act. Common: continued ranking decay, cannibalization that suppresses both URLs, technical risk (crawl budget), content sprawl that confuses readers. + +### Section 5: backlog and sequencing + +Prioritized backlog with owners and target dates. Sequence so that: + +- Redirects ship first (they are mechanical and preserve equity) +- Merges ship second (combine before refreshing) +- Updates ship third (work on what remains) +- Deletes happen last (after all redirects and merges that depend on those URLs are in) + +--- + +## Pre-audit checklist + +Before running the audit: + +- [ ] Analytics access granted (GA4 or equivalent) +- [ ] Search Console access granted +- [ ] Crawl tool ready (Screaming Frog, Sitebulb, or hosted equivalent) +- [ ] Backlink data source identified (Ahrefs, Semrush, GSC limited data) +- [ ] Topic clusters defined (from content strategy) +- [ ] Threshold values agreed (sessions, position, age) +- [ ] Decision authority confirmed (who can approve Delete and Merge actions) +- [ ] Implementation owner confirmed (who runs the post-decision work) + +--- + +## Post-audit verification + +After the actions ship: + +- [ ] Verify all redirects resolve correctly (no chains, no loops) +- [ ] Verify all 410/404 pages return correct status +- [ ] Update sitemap to remove deleted URLs and reflect canonical changes +- [ ] Resubmit sitemap in Search Console +- [ ] Monitor the merged URLs for ranking confirmation (typically 2-8 weeks) +- [ ] Re-run a slim audit at 90 days to confirm decay was halted + +--- + +## Sign-off + +Audit produced by: [Name, date] +Decisions approved by: [Name, role, date] +Implementation owner: [Name, date] + +Next audit scheduled: [Date - typically annual or after major content investment] diff --git a/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md b/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md new file mode 100644 index 0000000..e4ad239 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-audit/references/cannibalization-resolution.md @@ -0,0 +1,148 @@ +# Cannibalization Resolution + +When two or more pages on the same site compete for the same query, all of them lose. Search engines either pick the wrong one to rank, split the ranking signal across both, or rotate between them unpredictably. + +This reference walks through how to identify and resolve cannibalization. + +--- + +## How to identify cannibalization + +You have cannibalization when: + +- Two or more URLs from your site appear in the top 50 for the same query +- A query has multiple URLs ranking and rotating across the top 30 over time (search console shows this as inconsistent) +- A new page appears for a query and the previously-ranking page drops sharply +- Two URLs on the same site share the same primary intent and substantial content overlap + +How to find it: + +1. Export search console queries with multiple ranking URLs +2. Look for queries where the same site appears more than once in the data +3. Check rank stability: if a query bounces between URLs week to week, that is the signal +4. Internal: search your own site (`site:yourdomain.com "exact query"`) and see how many results appear + +--- + +## Resolution decision tree + +For each cannibalization cluster, you have four options. + +``` +Same intent? ─── Yes ──── Substantial content overlap? ─── Yes ── MERGE + │ + └── No ── Different angles, same intent? ─── DIFFERENTIATE + │ + └── No ──── Confirm intent classification, may not be cannibalization +``` + +### Option 1: Merge + +Combine the pages into one canonical page. Use this when: +- Both pages serve the same intent +- Content overlaps substantially +- Combined, the page would be stronger than either alone + +Steps: +1. Pick the merge target. Best signals win: highest-ranking URL, most backlinks, older URL, cleaner URL slug. +2. Pull the unique content from the loser pages, integrate into the winner. +3. 301 redirect the loser URLs to the winner. +4. Update internal links pointing at loser URLs to point at the winner. +5. Submit the winner URL for re-crawling. +6. Monitor rankings for 30 to 60 days. + +### Option 2: Differentiate + +Keep both pages, but reposition each to target distinct sub-intents. Use this when: +- The pages serve genuinely different queries that just look similar +- Both have meaningful traffic and rankings that are worth preserving +- The category supports nuanced sub-topics + +Steps: +1. Identify the distinct intent each page should target (e.g., "best running shoes" vs "best running shoes for beginners") +2. Rewrite titles, meta, H1, and intros to reinforce the distinct intent +3. Update internal links to use distinct anchor text +4. Cross-link the two pages so each acknowledges the other +5. Update any sitemap or hub page that lists them + +### Option 3: Redirect + +Pick a winner, kill the rest. Use this when: +- One page is clearly stronger +- The losers have no unique content worth preserving +- There is no benefit to maintaining multiple pages + +Steps: +1. Pick the winner using the same criteria as merge. +2. 301 redirect the losers to the winner. +3. Pull any unique content from the losers and integrate into the winner if useful. +4. Update internal links. + +### Option 4: Noindex the secondary page + +Keep both pages, but tell search engines to only consider one for ranking. Use this when: +- One page has a strong UX or business reason to exist (e.g., a product variant page) +- It does not need to rank, but does need to exist +- Merging would damage UX + +Steps: +1. Add `<meta name="robots" content="noindex, follow">` to the secondary page +2. Confirm the canonical of the secondary page points at itself (not the primary), since canonical and noindex serve different purposes +3. Verify in search console after a week that the noindex took effect +4. Maintain the user-facing functionality of the page + +--- + +## Picking the merge winner + +When you have to choose which URL becomes canonical, use this prioritized scoring: + +1. Current ranking position. If one URL is on page 1 and the other on page 3, keep page 1. +2. Backlinks. Highest count of referring domains usually wins. +3. URL quality. Cleaner slug, fewer parameters, shorter, descriptive. +4. Internal links in. More inbound internal links signals existing site structure. +5. Page age. Older URLs often have accumulated trust signals. +6. Content quality. If all else is tied, pick the one with better content (or the one easier to expand). + +Do not pick by recency of publication or "I just wrote it." Search engines reward signals that have accumulated over time. + +--- + +## Common cannibalization patterns + +### Pattern 1: Old article + new article on same topic + +Common in evergreen sites. Resolution: merge, with the older URL as canonical (preserves backlinks and age signals). + +### Pattern 2: Category page + product page targeting same query + +Resolution: differentiate. Category page targets the broad query ("running shoes"). Product pages target product-specific queries ("[brand] [model] running shoes"). + +### Pattern 3: Blog post + landing page + +Resolution: differentiate aggressively or merge. Blog post targets informational intent. Landing page targets commercial intent. If they keep cannibalizing, the keyword is fundamentally one-intent and one of them needs to retire. + +### Pattern 4: Multiple "best X" listicles for slight variants + +E.g., "best running shoes," "best running shoes for women," "best running shoes for marathons." Resolution: maintain a clear hub-and-spoke structure. The hub page targets the broad query. Spoke pages target specific variants. Cross-link. + +### Pattern 5: Geographic variants + +E.g., "best plumber" vs "best plumber in Denver." Resolution: differentiate by geo modifier in title, H1, content. Use schema (LocalBusiness) for the geo-specific pages. + +--- + +## Verification after resolution + +For 60 days post-resolution, monitor: + +- Rank for the canonical URL on the target query (should stabilize and improve) +- Rank for the merged/redirected URLs (should drop out, which is expected) +- Aggregate impressions and clicks for the cluster (should rise as ranking signals consolidate) +- Internal links pointing at deprecated URLs (should be zero after cleanup) + +If the canonical URL does not improve in rank within 60 days, recheck: + +- Did the redirects fire correctly? (Test 5 random old URLs) +- Are there still other pages on the site competing for the same query? +- Is the canonical URL strong enough on its own to rank? (Compare to top-ranking competitors) diff --git a/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md b/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md new file mode 100644 index 0000000..f7fcf21 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-gap-audit/SKILL.md @@ -0,0 +1,159 @@ +--- +name: seo-content-gap-audit +description: "Audit content gaps and decay using Ahrefs MCP data: missing topics, thin coverage, outdated content, and decaying pages. Use this skill when planning a content roadmap, refreshing a stale catalog, building topical authority, or identifying which existing pages need update versus replacement. Triggers on content gap, content audit, content refresh, content roadmap, decaying content, content decay, topical authority, what topics should we cover, where is competitor content stronger. Also triggers when organic traffic is flat despite consistent publishing." +category: seo-audit-suite +catalog_summary: "Missing topics, thin coverage, outdated content, decay diagnosis" +display_order: 4 +--- + +# SEO Content Gap Audit + +Find content gaps and decay using Ahrefs MCP data. Stack-agnostic. Produces a roadmap of create, update, merge, and prune actions across the existing content catalog and identified topic gaps. + +--- + +## When to use + +- Planning the next quarter or half of content investment +- Refreshing a stale or underperforming content catalog +- Building topical authority in a target space +- Identifying decaying pages before they tank traffic +- Audit prep before a major site redesign or migration +- Diagnosing why content investment is not driving organic growth + +## When NOT to use + +- Pure keyword research (use `seo-keyword`) +- Competitor keyword gap (use `seo-keyword-gap-audit`) +- Single-page optimization (use `seo-onpage`) +- Pure prune-and-redirect decisions (use `seo-content-audit`) +- New site planning with no existing content (use `content-strategy`) + +--- + +## Required inputs + +- Target property and content scope +- Competitor set (3-5 properties with comparable content depth) +- Target topics or pillars (if defined) +- Existing content inventory with URLs, primary topics, publish dates +- Performance data (organic clicks per page, ranked keywords per page) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: 4 categories of content opportunity + +Every content opportunity falls into one of four categories. Different categories need different actions. + +Content gap analysis is sharper with multiple data sources. Ahrefs surfaces keyword and topic gaps (the primary backend below). Similarweb surfaces traffic-driving page-level gaps (which of a competitor's pages earn meaningful traffic, not just rankings). Semrush surfaces SERP-feature gaps (where competitors win answer boxes, knowledge panels, People Also Ask placements). The three platforms often disagree on individual data points; that disagreement is itself a useful signal. + +### Category 1: Missing topics + +Topics with traffic potential where the property has no relevant page at all. Competitors often rank in the top 10. The fix: create new content. + +Pulled from: + +- Ahrefs Content Explorer (top performing content in target topics) +- Competitor top pages (Ahrefs Site Explorer) +- Keyword gap audit output (clustered into topics) + +### Category 2: Thin coverage + +Topics where the property has a page but it is too shallow, narrow, or single-keyword to compete with topical hubs. Competitor pages cover the topic across multiple subtopics. The fix: deepen the existing page or expand into a topic cluster. + +Pulled from: + +- Pages ranking on page 2-3 for target keywords +- Pages with low organic click share relative to ranked keyword volume +- Pages where competitors have longer or broader equivalents + +### Category 3: Outdated content + +Pages that ranked well historically but have lost ground due to staleness. Information is dated, examples are old, the SERP intent has shifted. The fix: refresh with current information and re-promote. + +Pulled from: + +- Pages with declining organic clicks over the last 6-12 months +- Pages with publish dates over 18 months old +- Pages with ranked keywords slipping in position + +### Category 4: Decaying content + +Pages that have lost traffic for reasons not obviously about staleness: SERP feature changes, competitor publishing, intent shifts, internal linking dilution. The fix: diagnose why, then refresh, merge, or redirect. + +Pulled from: + +- Pages with sharp recent traffic drops +- Pages where SERP composition has shifted (more video, more featured snippets, AI overviews) +- Pages that compete with newer pages on the same site (cannibalization) + +--- + +## Workflow + +1. Charter the audit. Scope (whole site or section), goal, time window for performance data. +2. Pull the inventory. Every URL, with publish date, primary topic, organic clicks, ranked keywords. +3. Pull competitor coverage. Top pages and content clusters from each competitor. +4. Classify each existing page. Healthy / thin / outdated / decaying / off-topic. +5. Identify missing topics. Cross-reference competitor top pages and keyword gap output. +6. Score each opportunity. See [`references/content-decision-matrix.md`](references/content-decision-matrix.md). +7. Cluster. Group related missing topics into pillar concepts. +8. Decide actions. Create / update / merge / redirect / prune for each opportunity. +9. Sequence the roadmap. Quarter by quarter, with effort estimates and traffic forecasts. +10. Hand off. Output feeds `content-strategy`, `content-and-copy`, and `seo-onpage`. + +--- + +## The action decision matrix + +For each piece of existing content or proposed new content, decide one action. + +\| Signal \| Action \| +\| --- \| --- \| +\| Strong page, healthy traffic, current information \| Keep. Defend with internal linking and refresh on schedule. \| +\| Page exists, ranking on page 2-3, content is thin vs SERP \| Update. Deepen, restructure, broaden. \| +\| Page exists, traffic declining, content is dated \| Refresh. Update facts, examples, year references, screenshots. \| +\| Page exists, low or zero traffic, low ranking, no improvement path \| Prune or merge. Redirect to a stronger relative if one exists. \| +\| Multiple pages on overlapping topics \| Merge into one canonical page. Redirect the others. \| +\| Topic missing entirely, competitor coverage strong \| Create new page or pillar. \| +\| Topic missing, but competitors do not rank well either \| Validate intent before investing. Could be an opportunity or could be a dead end. \| +\| Page is off-topic for the property \| Redirect to most relevant page or remove from sitemap. \| + +--- + +## Failure patterns + +- All-create, no-update bias. Teams default to creating new content. Updates and merges often outperform new pieces by a wide margin and at lower cost. +- Treating publish date as currency. A 5-year-old page can outrank a 1-month-old page if it is better. Stop deleting old content reflexively. +- Cannibalization blind spots. Two pages on overlapping topics dilute each other. Audit for it explicitly. +- No effort estimates. A roadmap without effort sizes cannot be sequenced realistically. +- No traffic forecast. A roadmap without forecasted impact loses funding fights. Forecast even with wide confidence bands. +- Refreshing without re-promotion. A refreshed page needs a re-crawl signal: update sitemap, internal links, distribution. +- Ignoring intent shift. Some keywords have shifted from informational to transactional or to AI-answer-dominated. Recognize when the SERP is no longer addressable by the existing format. +- Confusing decay with seasonality. A 30% click drop in summer for a back-to-school topic is not decay. Compare year-over-year, not month-over-month. +- Auditing in isolation from the keyword gap. The two audits feed each other. Run them adjacent. + +--- + +## Output format + +A content gap audit document with: + +1. Executive summary. Top 3 themes, content health verdict, recommended quarterly investment split. +2. Content inventory snapshot. Counts by health classification. +3. Missing topics. Prioritized list with cluster mapping and traffic forecast. +4. Thin coverage. Pages to deepen, with recommendation for each. +5. Outdated content. Pages to refresh, with refresh scope. +6. Decaying content. Pages to diagnose and act on, with hypothesis for each. +7. Cannibalization findings. Page pairs to merge. +8. Action roadmap. Quarter by quarter, with effort and forecast. +9. Methodology. Data sources, classification criteria, caveats. + +Length: 8-15 pages plus an attached inventory spreadsheet. + +--- + +## Reference files + +- [`references/content-decision-matrix.md`](references/content-decision-matrix.md) - Detailed decision tree for classifying pages and choosing the create/update/merge/prune action, with worked examples. diff --git a/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md b/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md new file mode 100644 index 0000000..65f3685 --- /dev/null +++ b/dist/pi/.agents/skills/seo-content-gap-audit/references/content-decision-matrix.md @@ -0,0 +1,177 @@ +# Content decision matrix + +A decision tree for classifying every page in a content audit and picking the right action. Use it after pulling the inventory and performance data. + +--- + +## The 6 actions + +Every page gets exactly one of these: + +1. Keep. Page is healthy. Defend it. +2. Refresh. Update facts, examples, screenshots, year references. +3. Update. Deeper rework. New sections, restructured argument, expanded scope. +4. Merge. Combine with another page. Redirect the loser. +5. Redirect. Page has no path forward. Redirect to closest relative. +6. Prune. Remove from sitemap, return 410 or noindex. + +--- + +## The decision tree + +Follow the tree top to bottom. The first match wins. + +### Step 1: Is the page on-topic for the property? + +If no: redirect to the most relevant page. If no relative exists, prune. + +### Step 2: Is the page duplicative of another page on the same site? + +If yes: merge. Pick the stronger of the two as the canonical, redirect the other. See "Merge selection criteria" below. + +### Step 3: Has traffic declined sharply over the last 6-12 months? + +Define "sharp": a drop of 40% or more, sustained for 3+ months, not explainable by seasonality. + +If yes: investigate. Likely actions are refresh, update, or redirect depending on root cause. See "Decay diagnosis" below. + +### Step 4: Is the page over 18 months old with stale specifics? + +Stale specifics include: outdated year references, old screenshots, dated examples, products no longer available, statistics from old reports. + +If yes: refresh. Keep the structure. Replace the stale parts. + +### Step 5: Is the page ranking on page 2-3 for relevant terms? + +Page 2-3 means positions 11-30 for keywords with meaningful volume. + +If yes: update. The page has potential. It needs more depth, better structure, or broader scope to break into top 10. + +### Step 6: Is the page getting steady traffic but the content is shallow vs the SERP? + +Shallow means: shorter than the top 3 SERP results, missing subtopics they cover, or single-keyword focused while they cover a topic cluster. + +If yes: update. The page is winning despite being thin. Make it stronger before competitors push it down. + +### Step 7: Is the page getting low traffic with no growth trend? + +Low traffic: under 50 organic clicks per month for an established page (over 12 months old). + +If yes and no clear path to improvement: prune or redirect. Do not waste effort trying to rescue every page. + +### Step 8: Default + +If none of the above, the page is healthy. Keep. Schedule a routine refresh on a 12-18 month cadence. + +--- + +## Merge selection criteria + +When two pages cover overlapping topics, decide which becomes canonical. + +Pick the page with: + +1. Stronger backlink profile (Ahrefs Site Explorer) +2. More ranked keywords with meaningful volume +3. Better URL (cleaner, more descriptive, shorter) +4. Higher current position for the head term + +If the pages have different strengths, often the right move is to keep the better URL and migrate the better content into it. + +Always: + +- 301 redirect the loser to the winner +- Update internal links to point at the canonical +- Notify Search Console (resubmit sitemap) +- Wait 4-8 weeks before evaluating impact + +--- + +## Decay diagnosis + +Sharp traffic decline can have multiple root causes. Diagnose before deciding action. + +### Possible causes and their signatures + +\| Cause \| Signature \| Action \| +\| --- \| --- \| --- \| +\| SERP feature steal (featured snippet, PAA, AI overview) \| Position stable, click-through rate fell \| Refresh + restructure for snippet capture, or accept the new normal \| +\| Competitor published better content \| Position fell, SERP composition includes new domain \| Update to match or exceed competitor depth \| +\| Intent shifted (informational to transactional, etc.) \| SERP composition is now a different content type (e.g., now product pages dominate) \| Re-evaluate format, or pivot URL purpose \| +\| Internal cannibalization \| A newer page on same site now ranks for the same term \| Merge or differentiate \| +\| Site-wide ranking decline \| Multiple pages lost position simultaneously \| Likely site-wide issue, see `seo-traffic-diagnosis` \| +\| Content went stale \| Year references and stats are outdated \| Refresh \| +\| Algorithm update \| Decline correlates with a known update date \| Audit content quality and E-E-A-T \| +\| Lost backlinks \| Referring domain count fell \| See `seo-backlink-audit` for reclamation \| +\| Migration aftermath \| Decline started immediately after a migration \| Audit redirect chains and structural changes \| + +Always confirm the cause before acting. Wrong diagnosis equals wrong fix. + +--- + +## Worked examples + +### Example 1: keep + +Page: pillar guide on a core topic, 2 years old, top 3 ranking, steady traffic, 800+ clicks/month, content is current. + +Decision: keep. Schedule routine refresh in 6 months. + +### Example 2: refresh + +Page: how-to guide, 3 years old, position 6-8, traffic flat for 12 months, screenshots show old UI, references "in 2023". + +Decision: refresh. Update screenshots, year references, and any tool versions. Re-promote internally. + +### Example 3: update + +Page: 1,200 word article on a category topic, position 14 for the head term, low CTR, top 3 results are 3,000+ word topic hubs covering 8-10 subtopics. + +Decision: update. Expand to cover the missing subtopics. Restructure for skim. Add internal links from related pages. + +### Example 4: merge + +Pages: two articles on closely overlapping topics, both ranking somewhere between positions 8-15 for related terms, splitting traffic. + +Decision: merge. Pick the page with stronger backlinks as canonical. Migrate the unique content from the other. 301 redirect the loser. Update internal links. + +### Example 5: redirect + +Page: outdated tutorial for a tool no longer in use, no organic traffic, no ranked keywords, off-topic for current site direction. + +Decision: redirect to closest relevant page. If none, prune (410 or noindex). + +### Example 6: prune + +Page: thin tag archive with under 5 items, no organic traffic, no internal links, indexed only because of CMS defaults. + +Decision: prune. Noindex via meta tag or remove from sitemap. Add to robots disallow if appropriate. + +--- + +## Effort and traffic forecast cheat sheet + +For sequencing the roadmap, use these rough estimates: + +\| Action \| Typical effort per page \| Traffic impact timeline \| +\| --- \| --- \| --- \| +\| Keep \| 0 (or routine refresh in 6-12 months) \| None \| +\| Refresh \| 2-4 hours \| 30-60 days to see ranking impact \| +\| Update \| 6-16 hours \| 60-120 days \| +\| Merge \| 4-8 hours per pair \| 60-120 days \| +\| Redirect \| 30 min \| Immediate (no ranking impact) \| +\| Prune \| 30 min \| Immediate (positive if it removes thin content drag) \| +\| Create new \| 12-30 hours \| 90-180 days for new pages to gain traction \| + +Updates and merges typically deliver more traffic per hour invested than new content. Most teams underweight them. + +--- + +## Common mistakes + +- Pruning aggressively without verifying low value. Some low-traffic pages have backlinks, internal link equity, or seasonal traffic. Audit these before pruning. +- Refreshing pages that need updates. A surface refresh on a thin page does not move rankings. Match the action to the root cause. +- Updating pages that need merges. Two competing pages on the same topic will keep splitting traffic. Merge first, then optimize. +- Skipping internal link audit. Updates and refreshes underperform without renewed internal links pointing to them. +- Optimizing pages with intent mismatch. If the SERP is now product pages and the page is an article, no amount of editing fixes that. Either pivot the page type or redirect. +- Forgetting to notify Search Console. Resubmit sitemap after major content moves to accelerate recrawl. diff --git a/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md b/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md new file mode 100644 index 0000000..ac38d93 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword-gap-audit/SKILL.md @@ -0,0 +1,161 @@ +--- +name: seo-keyword-gap-audit +description: "Find keywords competitors rank for that the target property does not, and prioritize them by opportunity. Uses Ahrefs MCP for keyword and competitor data. Use this skill when planning content investment, identifying quick wins, building a content calendar against a competitor set, or scoping a market entry. Triggers on keyword gap, content gap, competitor keywords, opportunity keywords, what should we target, where are competitors winning, keyword opportunity. Also triggers when planning content for a new market or after losing organic share to a specific competitor." +category: seo-audit-suite +catalog_summary: "Competitor keyword gaps with opportunity scoring and clustering" +display_order: 3 +--- + +# SEO Keyword Gap Audit + +Find keyword opportunities by comparing the target property's organic footprint against a competitor set, using Ahrefs MCP data. Stack-agnostic. Produces a prioritized list of keywords to target with new or improved content. + +--- + +## When to use + +- Planning content investment for the next quarter +- Identifying quick-win keywords for fast organic gains +- Scoping market entry into a new vertical +- Refreshing a stale content strategy +- Diagnosing why a competitor is gaining organic share +- Pre-acquisition due diligence on growth ceiling + +## When NOT to use + +- Pure keyword discovery without a competitor frame (use `seo-keyword`) +- Single-page optimization (use `seo-onpage`) +- Content audit on existing pages (use `seo-content-audit`) +- Topic and pillar planning (use `content-strategy`) + +--- + +## Required inputs + +- Target property +- Competitor set (3-5 properties with overlapping intent and audience) +- Target market and language +- Business priorities (which segments matter most) +- Existing content inventory (URLs and primary topics) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: the gap matrix + +A keyword can fall into one of four cells based on whether the target ranks and whether competitors rank. + +\| \| Target ranks \| Target does not rank \| +\| --- \| --- \| --- \| +\| Competitors rank \| Shared territory (defend and grow) \| Pure gap (the opportunity) \| +\| Competitors do not rank \| Unique territory (asset to protect) \| Untouched (validate before investing) \| + +The audit focuses primarily on the "pure gap" cell. The other cells get secondary treatment. + +### Pure gap (top focus) + +Keywords where one or more competitors rank in the top 10 and the target does not rank at all or ranks past page 3. These are the primary opportunities. + +### Shared territory + +Keywords where both target and competitors rank. Useful for defending position and finding pages to push from page 2 to page 1. + +### Unique territory + +Keywords where the target ranks and no competitor does. These are differentiators. Audit to confirm they are actually valuable (not just irrelevant terms). + +### Untouched + +Keywords no one in the set ranks for. Could be opportunity or could be irrelevant. Validate intent before investing. + +--- + +## Opportunity scoring + +Not every gap keyword is worth pursuing. Score each candidate. + +### Scoring dimensions + +\| Dimension \| What it measures \| Weight \| +\| --- \| --- \| --- \| +\| Search volume \| Estimated monthly searches in target market \| 20% \| +\| Business relevance \| How close to a money topic for the target \| 30% \| +\| Difficulty \| How hard to rank (Ahrefs KD or proxy) \| 15% \| +\| Intent match \| Whether target can satisfy the dominant intent \| 20% \| +\| Position potential \| Realistic top 3 reach within 6 months \| 15% \| + +Weights adjust based on goal. For quick wins, weight position potential and difficulty higher. For strategic territory, weight business relevance and volume higher. + +### Opportunity score formula + +``` +score = (volume_normalized * 0.2) + + (relevance_score * 0.3) + + (difficulty_inverted * 0.15) + + (intent_match * 0.2) + + (position_potential * 0.15) +``` + +Where each input is normalized to 0-100. The result is a 0-100 score. + +### Banding for action + +\| Score \| Action \| +\| --- \| --- \| +\| 80-100 \| Top priority. Plan content this quarter. \| +\| 60-79 \| Strong priority. Plan within 6 months. \| +\| 40-59 \| Watch list. Revisit if competitive landscape shifts. \| +\| Below 40 \| Park or drop. \| + +--- + +## Workflow + +1. Define the competitor set. 3-5 properties. Confirm they share intent and audience. +2. Pull keyword data. For each property: organic keywords, top pages, traffic estimates. +3. Build the gap matrix. Label each keyword with which property ranks where. +4. Filter to the pure gap cell. Strip out the other cells for now. +5. Validate intent. For each keyword, confirm the SERP intent matches what the target can produce. +6. Score by opportunity. Use the formula. See [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md). +7. Cluster. Group related keywords into topics. One topic, one piece of content. +8. Map to existing content. Some gap keywords are addressable by updating an existing page rather than creating new. +9. Sequence. Build the prioritized list with action (create / update / merge / new pillar). +10. Hand off. Output feeds `content-strategy` and `seo-onpage`. + +--- + +## Failure patterns + +- Wrong competitor set. Choosing competitors by brand recognition rather than SERP overlap produces gap lists that are not actually competitive. Pick competitors that fight you in the SERPs. +- Volume worship. High-volume gap keywords are often unrealistic. A 50-volume keyword you can rank for beats a 5,000-volume keyword you cannot. +- Ignoring intent. A gap keyword where the SERP is dominated by tools or marketplaces is not addressable by an article. Match content type to intent. +- Skipping clustering. Targeting individual keywords instead of topics produces thin content that loses to topical hubs. +- Over-relying on Ahrefs KD. Difficulty scores are heuristics. Look at the actual SERP. If it is dominated by Forbes and Wikipedia, KD is misleadingly low. +- No business filter. A high-volume gap with zero buyer intent is a vanity opportunity. Filter for relevance. +- One-shot audits. Gap closes and reopens as competitors publish. Rerun on a cadence. +- Forgetting unique territory. Defending what you uniquely rank for can be more valuable than chasing gaps. Audit both directions. +- Single-language audits in multi-market sites. Run separate gap audits per market. Patterns differ. + +--- + +## Output format + +A keyword gap audit document with: + +1. Executive summary. Top 3 themes and top 10 priority keywords. +2. Competitor set. Who, why selected, SERP overlap evidence. +3. The gap matrix. Counts and patterns across the four cells. +4. Pure gap analysis. The opportunity list, scored and banded. +5. Topic clusters. Groups of related keywords mapped to content concepts. +6. Action map. Create / update / merge decisions per cluster. +7. Quick wins. Top 5-10 highest-confidence opportunities. +8. Strategic plays. High-impact, longer-horizon investments. +9. Methodology. Data sources, scoring weights, caveats. + +Length: 6-15 pages plus an attached opportunity spreadsheet. + +--- + +## Reference files + +- [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md) - Scoring rubric with normalization rules, formula, and worked examples. diff --git a/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md b/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md new file mode 100644 index 0000000..3b9af2a --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md @@ -0,0 +1,233 @@ +# Opportunity scoring rubric + +A scoring framework for ranking keyword gap opportunities. The score combines five normalized inputs into a single 0-100 ranking. Use it to convert a long gap list into a prioritized roadmap. + +--- + +## The 5 inputs + +### 1. Search volume (weight: 20%) + +Monthly search volume in the target market. + +Normalize on a log scale because volume is heavily skewed: + +\| Volume range \| Normalized score (0-100) \| +\| --- \| --- \| +\| 0-100 \| 20 \| +\| 100-500 \| 40 \| +\| 500-2,000 \| 60 \| +\| 2,000-10,000 \| 80 \| +\| 10,000+ \| 100 \| + +Use Ahrefs Keywords Explorer for the volume figure. Confirm the country setting matches the target market. + +### 2. Business relevance (weight: 30%) + +How close is this keyword to a revenue or conversion topic? + +Score on intent stage: + +\| Stage \| Normalized score \| Examples \| +\| --- \| --- \| --- \| +\| Direct purchase intent \| 100 \| "buy [product] online", "[product] price" \| +\| Comparison and evaluation \| 80 \| "best [product] for [use case]", "[product A] vs [product B]" \| +\| Problem-aware research \| 60 \| "how to [solve problem]", "what is [problem]" \| +\| Top-of-funnel education \| 40 \| "[broad topic] guide", "[topic] meaning" \| +\| Tangentially related \| 20 \| Adjacent topic with weak conversion path \| +\| Off-topic \| 0 \| Drop \| + +Adjust based on business model. SaaS values evaluation-stage highly. Ecommerce values direct purchase highly. Media values volume across all stages. + +### 3. Difficulty (weight: 15%) + +How hard is it to rank in the top 10? Use Ahrefs Keyword Difficulty as the starting input, but verify against the actual SERP. + +Invert the score. Lower difficulty equals higher opportunity: + +\| KD score \| Inverted normalized score \| +\| --- \| --- \| +\| 0-10 \| 100 \| +\| 11-30 \| 80 \| +\| 31-50 \| 60 \| +\| 51-70 \| 40 \| +\| 71-100 \| 20 \| + +Override KD if the SERP visibly contradicts it. A KD-15 SERP dominated by Forbes, Reddit, and Wikipedia is harder than a KD-40 SERP of niche bloggers. + +### 4. Intent match (weight: 20%) + +Can the target produce content that matches the dominant SERP intent? + +Look at the top 10 results and classify what they are: + +\| SERP type \| Match score for an article \| Match score for a tool \| Match score for a product page \| +\| --- \| --- \| --- \| --- \| +\| Articles dominate \| 100 \| 20 \| 0 \| +\| Tools or calculators dominate \| 20 \| 100 \| 0 \| +\| Product pages dominate \| 0 \| 0 \| 100 \| +\| Marketplaces dominate \| 20 \| 40 \| 60 \| +\| Video dominates \| 40 \| 60 \| 0 \| +\| Mixed (no dominant type) \| 60 \| 60 \| 60 \| + +If the target cannot produce the matching content type, drop the keyword regardless of other scores. + +### 5. Position potential (weight: 15%) + +Realistic top 3 reach within 6 months given current site authority. + +Estimate based on: + +- Current ranking position (if any) +- Domain Rating relative to the SERP +- Content depth required +- Topical authority in this space + +\| Current position \| DR vs SERP avg \| Position potential score \| +\| --- \| --- \| --- \| +\| Top 3 already \| Any \| Skip (defend, do not gap-target) \| +\| Position 4-10 \| At or above \| 100 \| +\| Position 11-20 \| At or above \| 80 \| +\| Position 11-20 \| Below \| 60 \| +\| Position 21+ \| At or above \| 50 \| +\| Not ranking \| Above SERP avg \| 60 \| +\| Not ranking \| At SERP avg \| 40 \| +\| Not ranking \| Below SERP avg \| 20 \| + +--- + +## The formula + +``` +score = (volume_normalized * 0.20) + + (relevance_score * 0.30) + + (difficulty_inverted * 0.15) + + (intent_match * 0.20) + + (position_potential * 0.15) +``` + +Score ranges 0-100. Apply the action banding: + +\| Score \| Action \| Typical timeline \| +\| --- \| --- \| --- \| +\| 80-100 \| Top priority. Plan content this quarter. \| 0-90 days \| +\| 60-79 \| Strong priority. Plan within 6 months. \| 90-180 days \| +\| 40-59 \| Watch list. Revisit on landscape shift. \| Quarterly review \| +\| Below 40 \| Park or drop. \| Annual review \| + +--- + +## Worked example 1: high-priority gap + +Keyword: "[mid-funnel evaluation phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 1,800/month \| 60 \| +\| Relevance \| Comparison stage \| 80 \| +\| Difficulty \| KD 25, SERP confirms accessible \| 80 \| +\| Intent \| Articles dominate, target produces articles \| 100 \| +\| Position \| Currently position 14, DR above SERP avg \| 80 \| + +``` +score = (60 * 0.20) + (80 * 0.30) + (80 * 0.15) + (100 * 0.20) + (80 * 0.15) + = 12 + 24 + 12 + 20 + 12 + = 80 +``` + +Band: top priority. Plan this quarter. + +--- + +## Worked example 2: borderline opportunity + +Keyword: "[broader top-of-funnel phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 9,500/month \| 80 \| +\| Relevance \| Top-of-funnel education \| 40 \| +\| Difficulty \| KD 55 with Forbes in top 3 \| 30 (override) \| +\| Intent \| Mixed SERP, target produces articles \| 60 \| +\| Position \| Not ranking, DR below SERP avg \| 20 \| + +``` +score = (80 * 0.20) + (40 * 0.30) + (30 * 0.15) + (60 * 0.20) + (20 * 0.15) + = 16 + 12 + 4.5 + 12 + 3 + = 47.5 +``` + +Band: watch list. Revisit if domain authority grows or if priority shifts. + +--- + +## Worked example 3: drop + +Keyword: "[high-volume but off-topic phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 22,000/month \| 100 \| +\| Relevance \| Tangentially related \| 20 \| +\| Difficulty \| KD 65 \| 30 \| +\| Intent \| Marketplaces dominate, target produces articles \| 20 \| +\| Position \| Not ranking, DR well below SERP avg \| 20 \| + +``` +score = (100 * 0.20) + (20 * 0.30) + (30 * 0.15) + (20 * 0.20) + (20 * 0.15) + = 20 + 6 + 4.5 + 4 + 3 + = 37.5 +``` + +Band: drop. High volume is not enough. + +--- + +## Adjusting weights for goal + +Default weights work for general opportunity audits. For specific goals: + +### Quick wins focus + +- Volume: 15% +- Relevance: 25% +- Difficulty: 25% +- Intent: 20% +- Position: 15% + +### Strategic territory focus + +- Volume: 25% +- Relevance: 35% +- Difficulty: 10% +- Intent: 20% +- Position: 10% + +### Defensive (protect rankings) + +Reuse the formula but apply to "shared territory" cell. Position potential weights higher. + +--- + +## Clustering after scoring + +After scoring individual keywords, cluster them. Targeting clusters beats targeting one-off keywords. + +Cluster rules: + +- Same dominant intent +- Overlapping SERP results (top 5 results match for 60%+ of the cluster) +- Naturally addressable by one piece of content + +Apply the highest score in the cluster as the cluster's score for prioritization. + +--- + +## Common mistakes when scoring + +- Trusting volume estimates blindly. Ahrefs estimates have wide confidence intervals at low volumes. A "50/month" keyword may be 5 or 200. +- Treating KD as ground truth. Always look at the SERP. KD is a heuristic, not a verdict. +- Scoring before intent matching. A keyword with mismatched intent scores high on paper but cannot rank for the target. Filter intent first. +- One-time scoring. Re-score quarterly. SERPs evolve. Competitor moves change difficulty. +- No business filter. A high score on a topic with zero conversion path is not an opportunity. Add a sanity check on relevance. +- Optimizing for the formula, not the goal. The score informs the call. The goal makes the call. diff --git a/dist/pi/.agents/skills/seo-keyword/SKILL.md b/dist/pi/.agents/skills/seo-keyword/SKILL.md new file mode 100644 index 0000000..f635e1f --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/SKILL.md @@ -0,0 +1,163 @@ +--- +name: seo-keyword +description: "Run keyword research, classify by search intent, cluster into topical groups, and prioritize for content production. Use this skill whenever the user asks to do keyword research, find target keywords, identify ranking opportunities, classify search intent, build a topical map, or plan a content strategy around what people search for. Triggers on keyword research, keyword strategy, search intent, keyword clustering, topic clusters, keyword difficulty, search volume, ranking opportunity, content gap, what should I write about, target keyword, primary keyword, secondary keyword, long-tail. Also triggers when planning a content calendar or new site without keywords yet defined." +category: seo-foundation +catalog_summary: "Discovery, intent classification, clustering, prioritization" +display_order: 3 +--- + +# Keyword Research + +Find the queries worth ranking for, classify them by intent, cluster them into topics, and prioritize what to produce. Stack-agnostic. Tool-agnostic (works with any keyword tool). + +--- + +## When to use + +- Starting a new site or content section +- Planning a content calendar +- Looking for ranking opportunities on an existing site +- Understanding search intent before writing +- Building topic clusters for internal linking +- Identifying content gaps vs competitors + +## When NOT to use + +- Optimizing a single page where the target query is already known (use `seo-onpage`) +- Comparing your site to a competitor across many dimensions (use `seo-competitor`) +- Auditing existing content for performance (use `seo-content-audit`) + +--- + +## Required inputs + +- The site or topic area +- The target audience and what they need +- A keyword tool (Ahrefs, Semrush, Moz, Google Keyword Planner, or similar) OR access to search console for an existing site +- Optional: 3 to 5 known competitors to seed the research + +If no tool is available, the skill still works using SERP inspection and search console data alone, but the volume estimates will be rough. + +--- + +## The framework: 4 stages + +### Stage 1: Discover + +Cast a wide net. Sources: + +- Seed terms from the brief or the user's vocabulary +- Competitor keywords (any keyword tool will export these) +- Search console queries for an existing site (find the page-1 and page-2 queries) +- Related searches and "People also ask" in actual SERPs +- Customer language (support tickets, sales calls, reviews) +- Forum and community language (Reddit, niche forums, Stack Overflow) + +Goal: 200 to 500 candidate keywords for a typical content sprint. More if planning a year of content. + +### Stage 2: Classify by intent + +Every keyword maps to one of four intents. Get this right or the rest is noise. + +\| Intent \| Signal \| Page type that wins \| +\|---\|---\|---\| +\| Informational \| "how to," "what is," "why," "best way to" \| Article, guide, tutorial \| +\| Navigational \| brand or product name + modifier \| Brand homepage, product page \| +\| Commercial \| "best," "review," "vs," "comparison," "alternatives" \| Listicle, comparison, review \| +\| Transactional \| "buy," "price," "deal," "near me," "for sale" \| Product page, category page \| + +A keyword tool's volume tells you the demand. The SERP tells you the intent. When in doubt, look at what's actually ranking. If page 1 is articles, the query is informational. If page 1 is product pages, it's transactional. + +Hybrid intents exist. "Best running shoes" is commercial-investigational. "Best running shoes under $100" is the same intent narrowed by a budget filter. Treat hybrids as their dominant intent and note the modifier. + +### Stage 3: Cluster + +Group keywords that should target the same page (or topic cluster). + +Two clustering approaches: + +Approach A: SERP overlap. If two keywords share at least 3 of the top 10 results, they target the same page. This is mechanical and reliable. + +Approach B: Topical relevance. Group keywords by the underlying topic, not just word overlap. "How to start a podcast" and "podcast equipment for beginners" are the same topic, different facets. + +Use both. A typical cluster has: +- 1 primary keyword (highest volume, broadest intent) +- 5 to 15 secondary keywords (variations and long-tails) +- 1 page that targets them all + +### Stage 4: Prioritize + +For each cluster, score on three dimensions: + +Opportunity (1 to 5): +- Volume (raw search demand) +- Click potential (some queries answer themselves in the SERP, lowering CTR) +- Conversion potential (does this query attract buyers or browsers?) + +Difficulty (1 to 5): +- Domain authority of top results +- Backlink count of top results +- Content depth and freshness of top results +- Whether the SERP has features (featured snippets, AI overview, video carousel) that compete with organic + +Strategic fit (1 to 5): +- Does it serve our audience? +- Does it support our positioning? +- Does it link to commercial pages naturally? + +Priority score = Opportunity + Strategic fit - Difficulty. + +Rank the clusters. Top 20 percent get produced first. + +--- + +## Workflow + +1. Define the scope. What site, what topic area, what audience. +2. Run discovery. Pull seeds, competitor exports, search console data, SERP inspections. Aim for 200 to 500 candidates. +3. Deduplicate and clean. Remove obvious junk, brand misspellings, irrelevant terms. +4. Classify by intent. Mark each keyword. +5. Cluster. Group into topical clusters. Aim for 20 to 50 clusters. +6. Score each cluster on opportunity, difficulty, and strategic fit. +7. Prioritize. Rank by composite score. Identify the top 10 to 20 clusters to produce first. +8. Output. Use the template in [`references/keyword-research-template.md`](references/keyword-research-template.md). + +--- + +## Failure patterns + +- Chasing volume without intent. A 10,000-volume informational keyword does not drive purchases. Match query to commercial outcome. +- Targeting impossibly competitive keywords. New sites cannot rank for "credit cards." Find the underserved long-tail variant. +- Ignoring search console. Existing sites already rank for queries they did not target. These are the easiest wins. +- Treating clusters as one-keyword-per-page. A page can target 10 to 30 related keywords. One-keyword-per-page leads to thin, cannibalized content. +- Ignoring SERP features. A query with a featured snippet, AI overview, and a video carousel above the organic results may not be worth pursuing. +- Static keyword research. Search demand shifts. Refresh the research at least annually for evergreen sites, quarterly for fast-moving topics. + +--- + +## Output format + +Default output: a spreadsheet (CSV or sheet) with one row per keyword and one row per cluster, plus a markdown summary with the top 10 to 20 clusters detailed. + +Recommended columns for the keyword sheet: + +\| Column \| Source \| +\|---\|---\| +\| Keyword \| Discovery \| +\| Volume \| Tool \| +\| Difficulty \| Tool \| +\| Intent \| Manual classification \| +\| SERP features \| Manual or tool \| +\| Cluster \| Stage 3 \| +\| Cluster role (primary/secondary) \| Stage 3 \| +\| Opportunity score \| Stage 4 \| +\| Strategic fit \| Stage 4 \| +\| Priority \| Composite \| +\| Notes \| Free text \| + +--- + +## Reference files + +- [`references/keyword-research-template.md`](references/keyword-research-template.md) - Spreadsheet column definitions and a markdown summary template. +- [`references/intent-classification-guide.md`](references/intent-classification-guide.md) - Detailed examples of each of the four intent categories. diff --git a/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md b/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md new file mode 100644 index 0000000..0b145f2 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/references/intent-classification-guide.md @@ -0,0 +1,246 @@ +# Intent Classification Guide + +Detailed examples of each of the four search intent categories. Use this to tag every keyword in research with its intent before deciding what content (if any) to build. + +Intent classification is the most important and most-skipped step in keyword research. Tools surface volume and difficulty. They do not tell you whether the searcher wants to learn, compare, navigate, or buy. Without intent, you produce content that ranks for words but converts nothing. + +--- + +## The four intents + +\| Intent \| The searcher wants to \| Right content \| Right CTA \| +\|---\|---\|---\|---\| +\| Informational \| Learn something \| Article, guide, video \| Subscribe, related content \| +\| Navigational \| Reach a specific destination \| Branded page, login, location \| Direct link \| +\| Commercial investigation \| Compare options before buying \| Comparison, review, list, buyer's guide \| Demo, trial, deeper guide \| +\| Transactional \| Take an action (buy, sign up, download) \| Product page, pricing, signup, checkout \| Buy / sign up / download \| + +The same root word can fall into multiple intents depending on modifier. "Crm" alone is ambiguous. "What is a crm" is informational. "Salesforce login" is navigational. "Best crm for startups" is commercial investigation. "Buy salesforce" is transactional. + +--- + +## Informational intent + +The searcher wants to understand, learn, or solve a problem. + +### Signals + +- Question words: what, why, how, when, where, who +- "Guide," "tutorial," "examples," "definition," "explained" +- Topic-only queries with no commercial modifier ("dmarc records," "css grid") +- "How to" + a task + +### Examples + +\| Query \| Intent depth \| Notes \| +\|---\|---\|---\| +\| "what is a service blueprint" \| Top-of-funnel learning \| Definition piece \| +\| "how to write a creative brief" \| How-to \| Step-by-step guide \| +\| "service blueprint examples" \| Mid-funnel learning \| Examples gallery \| +\| "service blueprint vs customer journey map" \| Comparison-flavored learning \| Overlaps with commercial; treat as info if no products in result \| +\| "why is css grid useful" \| Conceptual \| Explainer with code examples \| +\| "history of bauhaus design" \| Background \| Editorial / long-form \| +\| "node js error eaddrinuse" \| Troubleshooting \| Specific fix article \| + +### What to publish + +Long-form articles, guides, glossary entries, video tutorials, original research. Content that earns subscribers, social shares, and backlinks. Not where conversion happens; where awareness builds. + +### CTA approach + +Soft. "Subscribe to the newsletter," "read the related guide," "join the community." A pricing CTA at the end of an informational piece reads as a bait-and-switch. + +### Failure mode + +Producing informational content with hard sales CTAs because someone metric'd it as "low conversion." Informational content's job is awareness and authority. Measure it on assists, brand recall, and downstream conversions, not last-click. + +--- + +## Navigational intent + +The searcher knows what they want and is using search to get there. + +### Signals + +- Brand names ("HubSpot," "Notion") +- Brand + modifier ("HubSpot login," "Notion pricing," "Salesforce careers") +- Product names ("MacBook Pro M4," "Tesla Model Y") +- Domain-style queries ("github.com," "facebook") + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "linear" \| Linear's homepage \| +\| "linear login" \| Linear's login page \| +\| "salesforce careers" \| Salesforce's careers page \| +\| "amazon prime" \| Amazon Prime's page \| +\| "github status" \| GitHub's status page \| + +### What to publish + +For your own brand: own the navigational queries. The homepage, login page, status page, careers page, contact page, pricing page should rank #1 for branded variants. + +For other brands' navigational queries: do not pursue. You will not rank, you should not try, and even if you did, the user does not want you. + +The exception: comparison queries ("Linear alternatives," "vs Linear") are not navigational; they are commercial investigation. See below. + +### CTA approach + +Whatever the destination expects. Login page → login form. Pricing page → buy or trial. Careers page → application. + +### Failure mode + +Treating "alternatives to" queries as navigational. They are not. They are commercial investigation, and a comparison page is the right format. + +--- + +## Commercial investigation intent + +The searcher is in the buying process but not ready to buy. They are comparing, reading reviews, building a shortlist. + +### Signals + +- "Best [category]" ("best crm for small business") +- "Top [category]" ("top hosting providers") +- "[Category] comparison" ("crm comparison") +- "[Brand] vs [brand]" ("notion vs obsidian") +- "[Brand] alternatives" ("alternatives to mailchimp") +- "[Brand] review" ("notion review") +- "[Category] for [audience]" ("crm for startups") +- "Cheap / affordable / free [category]" +- "Buyer's guide for [category]" + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "best email marketing tool" \| A ranked list of options \| +\| "mailchimp vs convertkit" \| A direct comparison \| +\| "alternatives to mailchimp" \| A shortlist of competitors with pros and cons \| +\| "convertkit review" \| Honest assessment from a third party (or the brand's own page if positioning) \| +\| "crm for solo consultants" \| Curated shortlist for a niche \| +\| "free project management software" \| Filtered list with feature notes \| + +### What to publish + +- For your category (high traffic, broad): "best of" lists, ranked comparisons, buyer's guides. Honest about tradeoffs. Include yourself if relevant; do not lie about ranking. +- For your brand vs others: comparison pages on your own domain ("[YourBrand] vs [Competitor]"). These are the highest-converting content type after pricing pages. +- For your category by use case: segment-specific landing pages ("CRM for solo consultants," "CRM for series-A startups"). Use case + CTA. + +### CTA approach + +Stronger than informational, lighter than transactional. "Try [product] free," "see how it compares," "book a demo," "download the buyer's guide." Multiple CTAs are OK because the visitor's progress is uncertain. + +### Failure mode + +Writing a "best of" list that is transparently a sales pitch for your product. Readers and Google can both spot this. Honest comparison pages, even when they include you, perform far better than disguised brochures. + +--- + +## Transactional intent + +The searcher wants to act now. Buy, sign up, download, contact, get a quote. + +### Signals + +- "Buy," "purchase," "order" +- "Sign up," "create account" +- "Download" +- "Get a quote," "request a demo," "contact sales" +- Brand + transactional modifier ("buy [product]," "[product] coupon," "[product] discount") +- "[Product] near me" (local-transactional) +- "[Product] free trial" + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "buy iphone 16 pro" \| Purchase, fast \| +\| "salesforce free trial" \| Trial signup \| +\| "download notion mac" \| Direct download \| +\| "request a demo hubspot" \| Demo form \| +\| "plumber near me" \| A plumber to call \| +\| "amazon prime sign up" \| Amazon Prime signup flow \| + +### What to publish + +Product pages, pricing pages, signup pages, checkout flows, contact pages. Make the transactional path frictionless. Strong CTAs above the fold. Trust signals near the action. + +### CTA approach + +The CTA is the page. One primary action, sized and placed so the user cannot miss it. Secondary actions allowed if they protect the primary (e.g., "talk to sales" alongside "start free trial" for enterprise vs SMB). + +### Failure mode + +Burying the transactional action behind marketing copy. The user came to act. Get out of the way. + +--- + +## Mixed and ambiguous intent + +Many queries do not fit cleanly. Use the SERP to disambiguate. + +### Method + +Open the query in incognito. Look at the top 10 results. + +- All articles? Informational. +- All branded landing pages? Navigational or transactional. +- Mix of comparison pages, "best of" lists, and product pages? Commercial investigation. +- Mix of articles and product pages? Mixed - the safer bet is to produce both kinds of content. + +### Example: "crm software" + +Could be informational ("what is CRM software"), commercial investigation ("which CRM should I pick"), or transactional ("crm software to buy now"). The SERP shows: a definition (HubSpot's), a "best of" list (multiple), several product pages, and a Wikipedia entry. Mixed intent leaning commercial investigation. + +The right play: produce a comparison page that opens with a one-paragraph definition. Catches both intents. + +--- + +## Intent shifts across the funnel + +The same audience moves through intents. + +\| Stage \| Example query \| Intent \| Right content \| +\|---\|---\|---\|---\| +\| Aware of problem \| "team is missing deadlines" \| Informational \| Article on missed-deadline diagnosis \| +\| Aware of category \| "project management software" \| Informational + commercial \| Pillar guide \| +\| Comparing options \| "linear vs jira" \| Commercial investigation \| Comparison page \| +\| Ready to commit \| "linear pricing" \| Transactional \| Pricing page \| +\| Already a customer \| "linear keyboard shortcuts" \| Informational \| Help docs \| + +Build coverage across the funnel for your category. A site that only addresses transactional intent has nothing to rank for at the top of funnel and loses the audience to category-defining publishers. + +--- + +## Tagging in research + +When pulling keyword research, tag every row. + +\| Query \| Volume \| Difficulty \| Intent \| Notes \| +\|---\|---\|---\|---\|---\| +\| "service blueprint" \| 8,100 \| 32 \| Informational \| Definition + examples piece \| +\| "service blueprint vs customer journey" \| 1,200 \| 28 \| Commercial investigation \| Comparison piece \| +\| "service blueprint template" \| 2,400 \| 25 \| Informational + transactional \| Template page with download CTA \| +\| "service blueprint software" \| 880 \| 41 \| Commercial investigation \| Buyer's guide \| + +The intent tag drives the format and the CTA. Without it, content drifts into whatever the writer felt like producing. + +--- + +## Decision rule + +Once intent is tagged: + +- Informational: publish if the topic supports authority-building and the SERP is winnable. Skip if the SERP is dominated by big publishers and you have no asset. +- Navigational (your brand): make sure you own it. If not, fix. +- Navigational (someone else's brand): skip. +- Commercial investigation: publish if you compete in the category. These convert. +- Transactional: make sure your product / pricing / signup pages rank for the obvious branded transactional queries. Optimize them aggressively. + +--- + +## When intent surprises you + +Sometimes a query you assumed was one intent reveals as another. Trust the SERP over your assumption. The SERP reflects what Google has learned about searcher behavior at scale, which is more reliable than your guess. diff --git a/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md b/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md new file mode 100644 index 0000000..b701650 --- /dev/null +++ b/dist/pi/.agents/skills/seo-keyword/references/keyword-research-template.md @@ -0,0 +1,115 @@ +# Keyword Research: [Site or Topic Area] + +Date: [YYYY-MM-DD] +Scope: [What this research covers] +Audience: [Who we are writing for] +Tools used: [Which keyword tools were used] + +--- + +## Summary + +Total keywords analyzed: [N] +Clusters identified: [N] +Priority clusters (top 20%): [N] + +[2 to 3 sentence overview. The headline themes, the surprising finds, the strategic priorities.] + +--- + +## Top priority clusters + +The following clusters scored highest on opportunity, strategic fit, and reasonable difficulty. Produce these first. + +### Cluster 1: [Cluster name] +- Primary keyword: [keyword] (volume: X, difficulty: Y) +- Intent: [Informational / Commercial / Transactional / Navigational] +- Recommended page type: [Article / guide / comparison / product page / category] +- Secondary keywords: [list 5 to 15] +- Suggested URL: [/proposed-slug] +- Estimated effort: [Hours or days] +- Why this cluster: [1 to 2 sentences on strategic fit] + +### Cluster 2: [Cluster name] +- Primary keyword: +- Intent: +- Recommended page type: +- Secondary keywords: +- Suggested URL: +- Estimated effort: +- Why this cluster: + +[Continue for top 10 to 20 clusters.] + +--- + +## Full keyword sheet + +[Link to or attach the spreadsheet.] + +Columns: +1. Keyword +2. Volume +3. Difficulty +4. Intent (I/N/C/T) +5. SERP features (featured snippet, AI overview, PAA, video, image, local pack) +6. Cluster +7. Cluster role (primary / secondary / long-tail) +8. Opportunity score (1-5) +9. Strategic fit (1-5) +10. Priority (composite) +11. Notes + +--- + +## Topic map + +A visual or hierarchical view of how the clusters relate. This becomes the basis for internal linking and information architecture. + +``` +[Top-level topic] + ├── [Cluster A] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + ├── [Cluster B] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + └── [Cluster C] + └── ... +``` + +--- + +## Quick wins + +Existing pages that already rank on page 2 or low page 1 for high-value keywords. Optimizing these is faster than producing new content. + +\| URL \| Current rank \| Target query \| Volume \| Recommended action \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| + +(Pull from search console: queries with average position 5 to 20 and impressions over 100/month.) + +--- + +## Deferred clusters + +Clusters that did not make the priority cut and why. + +\| Cluster \| Reason \| +\|---\|---\| +\| [Cluster name] \| Too competitive for current authority \| +\| [Cluster name] \| Low commercial value \| +\| [Cluster name] \| Audience mismatch \| +\| [Cluster name] \| Better suited for paid acquisition \| + +--- + +## Refresh schedule + +This research should be revisited: +- Quarterly for fast-moving topics (tech, news, trends, finance) +- Annually for evergreen topics +- After any major SERP feature change (e.g., AI overviews appearing on key queries) +- After authority increases that unlock harder keywords (e.g., domain rating going up by 10+ points) diff --git a/dist/pi/.agents/skills/seo-offpage/SKILL.md b/dist/pi/.agents/skills/seo-offpage/SKILL.md new file mode 100644 index 0000000..fc103e6 --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/SKILL.md @@ -0,0 +1,168 @@ +--- +name: seo-offpage +description: "Plan and execute off-page SEO including link building, digital PR, brand mentions, citation building, and external authority signals. Use this skill whenever the user wants to build backlinks, plan a digital PR campaign, list local citations, run guest post outreach, develop linkable assets, recover lost links, or audit a backlink profile for risk. Triggers on link building, backlinks, digital PR, brand mentions, citation building, guest post, outreach, linkable asset, broken link building, HARO, podcast outreach, off-page SEO, anchor text, link velocity, toxic backlinks, disavow. Also triggers when the user is trying to grow domain authority or earn coverage." +category: seo-foundation +catalog_summary: "Link building, digital PR, citations, linkable assets" +display_order: 5 +--- + +# Off-Page SEO + +Build the external signals that earn rankings: backlinks, brand mentions, citations, and trusted sources pointing back to the site. Stack-agnostic. + +--- + +## When to use + +- Planning a link-building strategy +- Running digital PR or earned-media campaigns +- Building citations for a local business +- Developing linkable assets (research, tools, calculators) +- Recovering lost backlinks after a migration or audit +- Auditing a backlink profile for spam or toxicity +- Pitching guest posts, podcast appearances, or expert quotes + +## When NOT to use + +- On-site optimization (use `seo-onpage` or `seo-technical`) +- Keyword research and content planning (use `seo-keyword`) +- Competitor backlink research alone (start with `seo-competitor`, then return here for outreach planning) +- Paid link buying (this skill does not endorse or facilitate that) + +--- + +## Required inputs + +- The site or brand getting the links +- The audience and category +- A backlink tool (Ahrefs, Semrush, Moz, Majestic, or similar) for prospecting and monitoring +- A target outcome (rank for X, build authority in Y, recover from Z) + +--- + +## The framework: 4 strategies + +Off-page work splits into four strategy types. Most programs blend them. Pick the mix that fits your phase. + +### 1. Earned media +Links and mentions you earn through coverage, journalism, or contribution. + +- Digital PR (data-driven studies, original research, surveys) +- Expert quotes (HARO, journalist platforms, expert request services) +- Podcast appearances (relevant shows in your category) +- Speaking engagements and conference content +- Newsworthy product launches or company milestones + +Strength: Highest authority, hardest to replicate. +Cost: Time-intensive, often requires PR or content budget. +Volume: Low to medium per quarter. + +### 2. Owned assets +Linkable assets on your own site that attract links passively over time. + +- Original research and reports +- Free tools, calculators, and generators +- Comprehensive guides (the kind that become "the X resource for Y") +- Visualizations and interactive content +- Templates and frameworks +- Industry data trackers (regularly updated benchmarks) + +Strength: Compounds over time. Each link points at an evergreen asset. +Cost: Upfront content investment. +Volume: Slow to start, accelerates as the asset earns mentions. + +### 3. Partnerships and relationships +Links earned through real business relationships. + +- Customer case studies (where they link back) +- Partner programs and integrations +- Co-marketing campaigns +- Industry association memberships +- Speaker and expert contributor relationships +- Affiliate and referral programs + +Strength: Trustworthy, contextually relevant. +Cost: Time to develop relationships. +Volume: Medium and consistent. + +### 4. Citations and listings +Local and category-specific listings that establish entity legitimacy. + +- Google Business Profile (for local businesses) +- Bing Places, Apple Maps Connect +- Industry directories (review-quality only, skip spam directories) +- Niche association directories +- Wikipedia entry (where the brand qualifies for notability) +- Wikidata entry +- Trade publications and category indexes + +Strength: Foundational for local and entity SEO. +Cost: Low to medium, mostly setup time. +Volume: One-time foundation, occasional refresh. + +--- + +## Workflow + +1. Audit the current profile. + - Total referring domains + - Domain rating trend + - Top referring pages by traffic value + - Anchor text distribution (over-optimized exact-match anchors are a risk) + - Toxic links (spam directories, link farms, irrelevant categories) + - Lost links (referring domains that disappeared) + +2. Define the goal. "Rank top 3 for X by Q4" requires a different tactic mix than "build category authority." + +3. Pick the strategy mix. Allocate effort across the 4 strategies. A new site typically goes 70/20/10/0 (assets/citations/partnerships/earned) for the first year. An established site can lean more toward earned media. + +4. Build the prospecting list. + - For earned media: relevant journalists, podcast hosts, publication beats + - For owned assets: identify what assets to build based on what gets linked in your category + - For partnerships: list 50 to 100 potential partner sites + - For citations: standard list per category, plus niche directories + +5. Outreach. Personalized, value-first. Generic templated pitches damage the brand more than they help. + +6. Track and measure. + - Referring domains gained per month + - Domain rating trend + - Anchor text mix (avoid over-optimization) + - Pages on the site attracting links + - Lost link recovery rate + +7. Audit and disavow. Quarterly review for toxic links. Disavow only when there is real evidence of harm (manual penalty notice, sudden drop after spam attack). Most sites should not need to disavow. + +--- + +## Failure patterns + +- Volume over quality. 100 directory submissions help less than 5 editorial links from category-relevant sites. +- Buying links. Risk of manual penalties is real. Cost-adjusted, the ROI rarely works out. +- Over-optimized anchor text. If 40 percent of your inbound anchors are "best running shoes," it looks engineered. Aim for natural distribution: brand, naked URL, generic, partial-match, exact-match (in roughly that order of frequency). +- Generic outreach templates. "Dear [first name], I love your blog about [topic]" gets archived in seconds. Personalize or do not send. +- Ignoring lost links. A 5 percent monthly loss in referring domains compounds. Build a recovery workflow. +- Treating disavow as a routine cleanup tool. Disavow is for confirmed spam attacks or penalty recovery, not preemptive hygiene. +- Working off-page before the site is worth linking to. A poorly-designed, thin-content site will not convert outreach. Fix on-site first. + +--- + +## Output format + +Default output is a markdown plan at `offpage-strategy.md` plus tracking spreadsheets for prospects and outreach. + +Structure: +1. Current backlink profile summary +2. Goal and target metrics +3. Strategy mix (allocation across the 4 types) +4. Q1, Q2, Q3, Q4 tactical plan +5. Prospecting lists (in spreadsheets) +6. Outreach templates (personalized, never generic) +7. Tracking and measurement plan + +--- + +## Reference files + +- [`references/outreach-templates.md`](references/outreach-templates.md) - Templates for guest posting, expert quotes, broken-link outreach, podcast pitches. +- [`references/linkable-assets-guide.md`](references/linkable-assets-guide.md) - Categories of linkable assets with examples and effort estimates. diff --git a/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md b/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md new file mode 100644 index 0000000..ed9c7d7 --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/references/linkable-assets-guide.md @@ -0,0 +1,353 @@ +# Linkable Assets Guide + +Categories of linkable assets, with examples and effort estimates. A linkable asset is content (or a tool, or a dataset) that other sites have a reason to link to. Without a linkable asset, link building is begging. With one, it is offering value. + +--- + +## What makes an asset linkable + +A linkable asset has at least one of these properties: + +- It is the only place to find this thing. Original data, original tool, original framework. +- It is the best place to find this thing. Most comprehensive, most current, most carefully built. +- It saves the linker time. A reusable resource the linker would otherwise have to build or explain. +- It carries authority. Survey from a recognized brand, published research, expert-authored. +- It is current. Updated more recently than alternatives, with the year visible. + +Pages that fail all five are not linkable. They might be useful, but they are not assets that earn links. + +--- + +## Category 1: original research + +Surveys, studies, or data analyses you ran and nobody else has. + +### Examples + +- Annual industry survey (e.g., "State of [category] 2026") +- Benchmark report from your own product data ("the average [metric] across 1,000 companies using us") +- Trend analysis from public data sources you cleaned and synthesized +- Salary or compensation report for your industry +- Pricing transparency report ("what [category] really costs") + +### Effort + +- Low end: 40-80 hours (existing data, in-house analysis, single-author write-up) +- High end: 200-400 hours (custom survey, n=1,000+, design and PR investment) + +### Link earning rate + +Highest of any category, when done well. A defensible original research asset can earn 100+ referring domains over its life. + +### When to invest + +If you have unique access to data (your product's data, your customer base, your industry network) and you can update annually, this is the highest-leverage asset category. + +### When to skip + +If the data is shallow, the sample is small, or the analysis is obviously self-serving, the asset will be ignored or worse, criticized publicly. + +--- + +## Category 2: free tools + +Calculators, validators, generators, viewers - small interactive utilities that solve a specific problem. + +### Examples + +- Calculators (mortgage, ROI, paycheck, conversion rate) +- Validators (HTML, schema markup, robots.txt, regex) +- Generators (favicon, color palette, password, lorem ipsum, og image) +- Converters (currency, units, file format) +- Viewers (JSON, EXIF, certificate) + +### Effort + +- Low end: 20-40 hours (single-purpose calculator, basic UI) +- High end: 200+ hours (rich tool with saved state, account integration, PWA, accessibility-perfect) + +### Link earning rate + +High and durable. Tools earn links steadily for years if they remain useful and current. + +### When to invest + +When the problem is recurring, you can build something cleaner than what exists, and the tool naturally surfaces your product as the next step (e.g., a "how much will this site weigh" tool from a perf optimization vendor). + +### When to skip + +When the space is saturated with free tools that already work well. A new "color picker" is unlikely to displace the entrenched ones. + +--- + +## Category 3: definitive guides + +Long-form, exhaustive coverage of a topic that becomes the reference everyone links to. + +### Examples + +- "The complete guide to DMARC" +- "The HTTP status code reference" +- "Web performance metrics explained" +- "The 2026 GDPR compliance checklist" +- "All the CSS units, with examples" + +### Effort + +- Low end: 40-80 hours +- High end: 200+ hours, plus annual maintenance + +### Link earning rate + +High when the topic has natural inbound demand and the asset is genuinely the best version. Lower when 5+ competitor guides already exist. + +### When to invest + +When you can credibly produce something better than the current best (more comprehensive, more current, better organized, better examples, better visuals). When the topic supports your business strategically. + +### When to skip + +When the topic is dominated by an evergreen entrenched guide (Wikipedia-level reference, MDN, NN/g) that you cannot displace. + +--- + +## Category 4: visual / interactive assets + +Infographics, interactive explainers, micro-sites built around a single concept. + +### Examples + +- Interactive timelines +- Animated explainers ("how does HTTPS work") +- Map-based visualizations +- Comparison interactive ("the size of every JavaScript framework") +- Single-purpose explainer micro-sites (e.g., "supply chain visualizer") + +### Effort + +- Low end: 40-80 hours (static infographic, simple interactive) +- High end: 400+ hours (complex interactive, custom illustration, browser-based simulation) + +### Link earning rate + +High when the visual is genuinely useful and shareable. Often peaks early and decays unless the topic has lasting interest. + +### When to invest + +When visual treatment unlocks something prose cannot show. When the topic has strong visual storytelling potential. When you have design capacity to do it well. + +### When to skip + +When the same value can be delivered as a normal article. Visual treatment is not a substitute for substance; it is a multiplier on substance that already exists. + +--- + +## Category 5: templates and frameworks + +Reusable structures the audience can copy, adapt, and use. + +### Examples + +- Project plan templates +- Notion / Airtable templates with download +- Email outreach templates +- Pitch deck templates +- Resume / CV templates +- Code starter templates (CodeSandbox, Stackblitz, GitHub repos) +- Frameworks ("the SPADE framework for decisions") + +### Effort + +- Low end: 8-20 hours per template +- High end: 40-80 hours for a polished template suite + +### Link earning rate + +Moderate. Templates earn references in roundups and resource lists. Less likely to earn high-authority editorial links. + +### When to invest + +When the template solves a frequent problem in your audience's work and naturally connects to your product. + +### When to skip + +When the template space is crowded with free, polished alternatives. + +--- + +## Category 6: glossaries and reference indexes + +Comprehensive, well-organized indexes of terms, codes, status messages, error codes, etc. + +### Examples + +- "All HTTP status codes with examples" +- "Glossary of marketing terms" +- "Every accessibility WCAG criterion explained" +- "The full list of CSS pseudo-classes" + +### Effort + +- Low end: 40-80 hours +- High end: 200+ hours, plus continuous updates + +### Link earning rate + +Moderate to high. Reference assets earn links steadily as authors writing on related topics need a place to link the term. + +### When to invest + +When you have the patience to be exhaustive and the topic supports it. + +### When to skip + +When canonical references already exist and dominate (MDN, W3C, official docs). + +--- + +## Category 7: industry rankings and lists + +Annual or continuous lists ranking companies, products, or trends in a category. + +### Examples + +- "The 100 fastest-growing [category] companies" +- "The 50 best [job role] to follow" +- "[Industry] state-of-the-art software comparison" + +### Effort + +- Low end: 60-100 hours +- High end: 200+ hours with PR + +### Link earning rate + +Moderate to high. Ranked companies link to the list as a credibility signal. Higher rankings earn more links. + +### When to invest + +When you have the credibility to be the ranker (your audience trusts your judgment in the category). + +### When to skip + +When you would be ranking yourself or competitors with no objectivity. + +--- + +## Category 8: events and community assets + +Conferences, summits, awards, communities you sponsor or run. + +### Examples + +- Industry conference recap and highlight reels +- Annual awards +- Slack / Discord community +- Recurring meetup +- Podcast + +### Effort + +- High. Events and communities require continuous investment, not one-time. + +### Link earning rate + +Moderate. Earns links from participants, partners, press coverage. + +### When to invest + +When the audience-building flywheel is part of your strategy and you can sustain investment for 2+ years. + +### When to skip + +When the team cannot commit to sustained investment. + +--- + +## Category 9: opinionated takes and POVs + +Strong, well-argued positions on industry questions. Not lists, not data; arguments. + +### Examples + +- "Why we stopped using [framework]" +- "The case against [common practice]" +- "[Industry standard] is wrong, and here is why" +- Manifestos + +### Effort + +- Low. A great POV piece can be 1,500-3,000 words and 10-30 hours. + +### Link earning rate + +Highly variable. A POV that hits a nerve in the industry can earn 50+ links in a week. Most POVs earn nothing. + +### When to invest + +When the author has standing to take the position credibly (track record, role, prior writing). When the POV is genuinely held and well-defended. + +### When to skip + +When the POV is contrarian for the sake of being contrarian. Bad-faith hot takes earn ire and short-term traffic, not durable links. + +--- + +## How to pick + +Score candidates against four dimensions: + +\| Dimension \| Weight \| Score 1-5 \| +\|---\|---\|---\| +\| Strategic fit \| 30% \| Does it serve a topic cluster you want to own? \| +\| Defensibility \| 25% \| Can you build something competitors will not easily match? \| +\| Effort \| 25% \| What does it cost to ship and maintain? (Lower effort = higher score) \| +\| Audience pull \| 20% \| Will the right people link to it? \| + +Build the highest-scoring candidate first. Ship one asset all the way through promotion before starting the next. Two well-promoted assets beat ten orphaned ones. + +--- + +## Promotion plan (a separate but linked task) + +A linkable asset that nobody knows about earns no links. The promotion plan must exist before the build starts. + +Typical promotion plan elements: + +- 5-10 pre-launch outreach contacts (industry voices, friendly press, peer companies who would benefit) +- Coordinated social, email, and content launch +- Explicit "ask" templates for outreach (no link begging; offer the asset as relevant, let the linker decide) +- Follow-up content that references the asset for the next 3-6 months +- Ongoing maintenance plan (annual update for research, evergreen updates for tools) + +Without a promotion plan, even great assets sit unlinked. + +--- + +## Common failure modes + +- Asset is too thin. Calling a 600-word article a "definitive guide" earns no respect. +- Asset is dated. "2022 industry report" still on the site in 2026. Looks abandoned. +- No promotion plan. Built, shipped, never told anyone. +- Self-serving disguised as research. Survey questions written to produce a result that flatters your product. +- Tool that breaks. Calculator with stale data, validator that misses common cases. Returns negative trust. +- Asset that offers no follow-up. Visitor arrives, uses it, leaves. No reason to subscribe, register, or convert. + +--- + +## Rough effort vs durable links matrix + +\| Category \| Effort \| Typical referring domains over asset's life \| +\|---\|---\|---\| +\| Free tool (single-purpose) \| 30 hours \| 40-200 \| +\| Free tool (rich) \| 200 hours \| 100-1,000 \| +\| Original research (annual) \| 100 hours \| 50-500 per edition \| +\| Definitive guide \| 80 hours \| 30-300 \| +\| Visual / interactive \| 80 hours \| 30-200 \| +\| Templates suite \| 40 hours \| 10-100 \| +\| Glossary / reference index \| 80 hours \| 50-300 \| +\| Industry ranking (annual) \| 100 hours \| 50-300 per edition \| +\| Community / event \| 1,000+ hours \| 100-1,000 \| +\| POV piece \| 20 hours \| 0-200 (high variance) \| + +These are rough ranges from typical SaaS and content-led businesses. Industry, audience size, and promotion quality all shift them substantially. diff --git a/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md b/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md new file mode 100644 index 0000000..4db4f4b --- /dev/null +++ b/dist/pi/.agents/skills/seo-offpage/references/outreach-templates.md @@ -0,0 +1,213 @@ +# Outreach Templates + +Templates for the most common off-page outreach scenarios. Personalize every send. The templates are scaffolding, not ready-to-fire copy. + +A few rules across all templates: + +- Subject lines under 60 characters +- First line never says "I love your blog" or any variant +- One specific reference to their actual work (not a generic compliment) +- One clear ask +- One reason it benefits them, not you +- Sign with a real name and link to a real profile +- Plain text, no formatting, no images, no tracking pixels + +--- + +## Guest post pitch + +Subject: [Topic] for [their site name]? + +Hi [first name], + +I just read your piece on [specific article, published Date] and noticed [specific observation about an angle they did not cover, or a question their piece raised but did not answer]. + +I write about [your topic area] and I think the gap there could become a strong follow-up. Working title: "[Specific working title]." It would cover: + +- [Specific point 1] +- [Specific point 2] +- [Specific point 3] + +I can have a draft to you in two weeks. Recent samples of my writing: +- [URL 1] +- [URL 2] + +If this is not a fit, no worries. Let me know either way. + +Thanks, +[Name] +[Title and where you write] + +--- + +## Expert quote / source pitch + +Subject: Expert source on [topic] for your [piece type] + +Hi [first name], + +I saw your request for sources on [topic] via [HARO / Twitter / their site]. + +Quick credentials: [one sentence on why you're qualified - title, years, specific work]. Happy to provide a quote, full interview, or background on: + +- [Specific angle 1] +- [Specific angle 2] +- [Specific angle 3] + +Available for a quick reply via email today, or a call this week. + +[Name] +[Title] +[Profile / portfolio link] + +--- + +## Broken link outreach + +Subject: Broken link on your [page topic] page + +Hi [first name], + +I was reading your [page name] page (great resource) and noticed the link to [specific old URL] is broken - the destination returns a 404. + +I run [your site] and we have a piece on the same topic that might be a relevant replacement: [your URL]. It covers [specific overlap with what the broken link was for]. + +No pressure either way. Just wanted to flag the broken link. + +[Name] + +--- + +## Podcast pitch + +Subject: [Specific topic angle] for [show name]? + +Hi [first name], + +I have been listening to [show name] for [time period]. The recent episode with [guest name] on [topic] resonated because [specific reason]. + +I would love to come on and talk about [specific topic angle]. Why this is a fit for your audience: + +- [Specific angle 1] +- [Specific angle 2] +- [What I bring that other guests have not covered] + +Past appearances: +- [Show name] - [topic] - [link] +- [Show name] - [topic] - [link] + +If the topic resonates, I can send a one-page brief with sample questions. + +[Name] +[Title] +[Headshot / bio link] + +--- + +## Resource page link request + +Subject: Resource for your [page topic] roundup + +Hi [first name], + +Your [page name] page is one of the better roundups I have seen on [topic]. I noticed it includes [example resource they list]. + +I run [site] and recently published [your URL], which covers [specific angle]. A few reasons it might earn a spot in the list: + +- [Differentiator 1: e.g., original data, more detail, recently updated] +- [Differentiator 2] + +If it is a fit, I would be grateful for the inclusion. If not, completely understood. + +[Name] + +--- + +## Linkable asset announcement + +Subject: New [asset type] on [topic] + +Hi [first name], + +We just published [asset type, e.g., "an interactive calculator", "a 50-source benchmark study", "a free template"] on [topic]: [URL]. + +The reason I am sending it your way: [specific reason this person or publication would care - their audience overlap, a stated interest, a recent piece they wrote]. + +Three things that make it different from existing resources: +1. [Specific differentiator] +2. [Specific differentiator] +3. [Specific differentiator] + +If it is useful for your readers, I would love a mention. Either way, I would value your read of it. + +[Name] + +--- + +## Citation / mention reclamation + +When your brand is mentioned online but not linked to. + +Subject: Quick note on the [piece] you published + +Hi [first name], + +Thanks for mentioning [your brand] in your [piece title, with link]. Genuinely appreciated. + +Quick request: would you be open to linking the mention back to [your URL]? Helps your readers find us, and helps us track the reach of the piece. + +No worries if it is not your editorial standard to add links retroactively. + +Thanks, +[Name] + +--- + +## Partnership pitch (low-key) + +Subject: [Brand] x [their brand]? + +Hi [first name], + +I run [your brand]. We share an audience with [their brand] - both serving [audience description]. + +A few low-effort ways we could collaborate: + +1. [Specific idea: e.g., cross-promote in newsletters, swap quotes for content, co-host a webinar] +2. [Specific idea] +3. [Specific idea] + +If any resonate, I would love a 20-minute call to figure out the simplest version we could ship in 30 days. + +[Name] +[Title] +[Site] + +--- + +## Universal don'ts + +- Do not start with "Hope you are doing well." +- Do not call yourself a "fellow [profession]" unless you actually know them. +- Do not say "I'll keep this brief" and then write 600 words. +- Do not attach files in cold outreach. +- Do not follow up more than twice. Three+ follow-ups damage reputation. +- Do not use subject lines like "Quick question" or "Re: [topic]" if it is not actually a reply. +- Do not include phrases like "value-add," "synergy," or "leverage." +- Do not pitch yourself as the expert in their field. They are. + +--- + +## Personalization checklist + +Before sending any outreach: + +- [ ] Used their first name correctly (spelled right) +- [ ] Referenced specific recent work of theirs (not from 5 years ago) +- [ ] Stated the ask clearly in the first 3 lines +- [ ] Gave them a reason to say yes that benefits them +- [ ] Plain text, no HTML, no images, no tracking pixel +- [ ] Subject line under 60 characters and not deceptive +- [ ] Signature includes real credentials and a way to verify the sender + +If any are missing, do not send. diff --git a/dist/pi/.agents/skills/seo-onpage/SKILL.md b/dist/pi/.agents/skills/seo-onpage/SKILL.md new file mode 100644 index 0000000..ae226fe --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-onpage +description: "Run a comprehensive on-page SEO audit or optimization pass covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, URL hygiene, and on-page schema. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review header structure, check internal linking, improve a single URL's search performance, or write SEO-friendly copy. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization, optimize this page, SEO this page. Also triggers for any single-page review where ranking, click-through, or relevance signal quality is the goal, even if the user does not say 'SEO' explicitly." +category: seo-foundation +catalog_summary: "Single-page audits and optimization across 8 dimensions" +display_order: 1 +--- + +# On-Page SEO + +Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site. + +--- + +## When to use + +- Auditing or optimizing a single page (homepage, product page, article, landing page) +- Writing or reviewing title tags and meta descriptions +- Fixing header structure or content hierarchy +- Reviewing internal links from or to a page +- Improving a page's CTR from search results + +## When NOT to use + +- Site-wide crawl, indexing, or speed issues (use `seo-technical`) +- Keyword research or intent mapping (use `seo-keyword`) +- Competitor SERP analysis (use `seo-competitor`) +- Auditing many pages at once for prune/merge decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- The page URL or the draft content if pre-launch +- The primary target query (one phrase the page should rank for) +- The page's role in the site (commercial, informational, navigational) + +If the target query is unknown, run `seo-keyword` first or ask the user to name one. + +--- + +## The framework: 8 dimensions + +A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix. + +### 1. Title tag +- One unique title per URL across the site +- Roughly 50 to 60 characters (longer gets truncated in SERPs) +- Primary query near the front +- Brand at the end if it earns inclusion +- Distinct from the H1 (often very similar, but should not be identical word-for-word) + +### 2. Meta description +- One unique description per URL +- Roughly 150 to 160 characters +- Restates the value proposition, not the title +- Includes a soft CTA where natural +- Treats the description as ad copy that earns the click + +### 3. Header structure +- Exactly one H1 per page +- H1 contains or paraphrases the primary query +- H2 sections cover the major sub-topics +- H3+ used only when an H2 has genuine sub-points +- No skipped levels (no H2 followed by H4) +- Headers describe sections accurately enough that a reader could navigate by them alone + +### 4. Body content +- Opens with the primary user intent answered in the first paragraph +- Covers the topic comprehensively (define your competition's depth, then match or exceed it) +- Includes related entities and supporting concepts naturally +- Avoids keyword stuffing (write for the reader, not the bot) +- Reading level matches the audience (run a readability check) +- Paragraphs short enough to scan on mobile (3 to 5 lines) + +### 5. Internal links +- At least 2 to 3 outbound internal links to closely related pages +- At least 2 to 3 inbound internal links from related pages +- Anchor text is descriptive, not "click here" or "learn more" +- Links to canonical URLs, not redirects +- No broken internal links + +### 6. Images and media +- Every meaningful image has descriptive alt text (skip alt for purely decorative images) +- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg") +- Modern format used where supported (WebP, AVIF) +- Lazy loading on below-the-fold images +- Width and height attributes set to prevent layout shift + +### 7. URL slug +- Lowercase, hyphen-separated +- Includes the primary query naturally (no stuffing) +- Short (under 60 characters where possible) +- No dates unless the page is genuinely time-bound +- No session IDs, tracking parameters, or random hashes +- Matches the site's URL pattern conventions + +### 8. On-page schema +- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.) +- Required properties filled (review Schema.org docs for the type) +- Validates in Google's Rich Results Test or equivalent +- Matches what is visible on the page (do not lie to crawlers) +- Author and publisher schema linked correctly for content pages + +--- + +## Workflow + +1. Confirm the target query. If unclear, ask. Do not optimize without one. +2. Render the page. View it as a user would. Read the content top to bottom. +3. View the rendered HTML. Inspect the actual served markup, not just the visual page. Check `<title>`, `<meta>`, headers, and schema in the source. +4. Run the 8-dimension framework. Score each, note specific fixes. +5. Prioritize. Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish). +6. Write the report. Use the template in [`references/audit-template.md`](references/audit-template.md). +7. Offer to draft fixes. If the user wants, draft the new title, meta, headers, or copy directly. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Make it more SEO." Vague. Ask for the target query and what's broken first. +- "Add the keyword 5 times in the body." Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead. +- Optimizing a page that is not crawlable or indexable. Check `seo-technical` first. No on-page work helps a noindexed page. +- Optimizing a page with no clear user intent. A page that does not serve a real query will not rank no matter how well-tagged it is. +- Targeting the same query as another page on the site. This is cannibalization. Use `seo-content-audit` to decide which page should rank. + +--- + +## Output format + +Default output is a markdown audit at `seo-audit-[page-slug].md` in the project root. Structure: + +1. Page summary (URL, target query, role) +2. Score across 8 dimensions +3. Critical fixes +4. Important fixes +5. Nice-to-have polish +6. Drafted replacements (if requested) + +Keep audits under 1500 words. If a page needs more detail, link to deeper appendices. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable audit template, copy and use. +- [`references/onpage-checklist.md`](references/onpage-checklist.md) - Quick-reference checklist for the 8 dimensions. +- [`references/title-and-meta-patterns.md`](references/title-and-meta-patterns.md) - Patterns for writing strong titles and meta descriptions. diff --git a/dist/pi/.agents/skills/seo-onpage/references/audit-template.md b/dist/pi/.agents/skills/seo-onpage/references/audit-template.md new file mode 100644 index 0000000..ab15d58 --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/audit-template.md @@ -0,0 +1,112 @@ +# On-Page SEO Audit: [Page URL] + +Target query: [The primary phrase this page should rank for] +Page role: [Commercial / Informational / Navigational] +Audit date: [YYYY-MM-DD] +Auditor: [Name] + +--- + +## Summary + +[2 to 3 sentence overview. What's working, what's broken, what to fix first.] + +Overall score: [Pass / Needs work / Fail] + +\| Dimension \| Score \| One-line note \| +\|---\|---\|---\| +\| Title tag \| \| \| +\| Meta description \| \| \| +\| Header structure \| \| \| +\| Body content \| \| \| +\| Internal links \| \| \| +\| Images and media \| \| \| +\| URL slug \| \| \| +\| On-page schema \| \| \| + +--- + +## Critical fixes + +[Things that are broken, missing, or actively hurting the page.] + +### 1. [Fix name] +- Current: [What it is now] +- Problem: [Why it's broken] +- Fix: [Specific replacement] + +### 2. [Fix name] +- Current: +- Problem: +- Fix: + +--- + +## Important fixes + +[Things that are suboptimal but not broken.] + +### 1. [Fix name] +- Current: +- Problem: +- Fix: + +--- + +## Nice-to-have polish + +[Things that would lift the page from good to great.] + +- [Item] +- [Item] + +--- + +## Drafted replacements + +### Title tag +> Current: [exact current title] +> Proposed: [exact proposed title, with character count] + +### Meta description +> Current: [exact current meta] +> Proposed: [exact proposed meta, with character count] + +### H1 +> Current: [exact current H1] +> Proposed: [exact proposed H1] + +### Header outline +``` +H1: [proposed H1] + H2: [proposed section title] + H3: [if needed] + H2: [proposed section title] + H2: [proposed section title] +``` + +### URL (only if changing) +> Current: [current URL] +> Proposed: [proposed URL] +> Redirect required: Yes / No + +--- + +## Implementation notes + +[Any stack-specific considerations, deploy gotchas, or order-of-operations notes.] + +- [Note] +- [Note] + +--- + +## Verify after deploy + +- [ ] Rendered title in SERP preview tool matches proposed +- [ ] Rendered meta description matches proposed +- [ ] H1 visible and matches proposed +- [ ] Schema validates in Rich Results Test +- [ ] Internal links resolve, no broken anchors +- [ ] Images load with correct alt text +- [ ] If URL changed: 301 redirect in place, old URL no longer in sitemap diff --git a/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md b/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md new file mode 100644 index 0000000..283cf3e --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/onpage-checklist.md @@ -0,0 +1,90 @@ +# On-Page SEO Checklist + +A condensed checklist for the 8 dimensions. Use as a pre-publish gate or a quick audit pass. + +--- + +## Title tag + +- [ ] Unique across the site +- [ ] 50 to 60 characters +- [ ] Primary query near the front +- [ ] Brand at end (only if it earns inclusion) +- [ ] Not identical to H1 +- [ ] Reads as a compelling search snippet, not a list of keywords + +## Meta description + +- [ ] Unique across the site +- [ ] 150 to 160 characters +- [ ] Restates value, does not repeat title verbatim +- [ ] Includes a soft CTA where natural +- [ ] No keyword stuffing +- [ ] Treats it as ad copy + +## Header structure + +- [ ] Exactly one H1 +- [ ] H1 contains or paraphrases primary query +- [ ] H2s cover the major sub-topics +- [ ] No skipped levels (H2 to H4 with no H3) +- [ ] Headers describe the section accurately +- [ ] A reader could navigate by headers alone + +## Body content + +- [ ] First paragraph answers the primary user intent directly +- [ ] Topical depth matches or exceeds top-ranking competitors +- [ ] Related entities and concepts appear naturally +- [ ] No keyword stuffing +- [ ] Reading level matches the audience +- [ ] Paragraphs are mobile-scannable (3 to 5 lines) +- [ ] Includes original perspective or proprietary data where possible + +## Internal links + +- [ ] At least 2 to 3 outbound internal links to related pages +- [ ] At least 2 to 3 inbound internal links from related pages +- [ ] Anchor text is descriptive +- [ ] Links to canonical URLs (no redirects) +- [ ] No broken internal links + +## Images and media + +- [ ] Every meaningful image has descriptive alt text +- [ ] Decorative images use empty alt (`alt=""`) +- [ ] File names are descriptive +- [ ] Modern format used (WebP or AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] Width and height attributes set +- [ ] Captions where they aid comprehension + +## URL slug + +- [ ] Lowercase, hyphen-separated +- [ ] Includes primary query naturally +- [ ] Under 60 characters where possible +- [ ] No dates unless time-bound +- [ ] No tracking parameters +- [ ] Matches site URL conventions + +## On-page schema + +- [ ] Appropriate Schema.org type +- [ ] Required properties filled +- [ ] Validates in Rich Results Test +- [ ] Matches what is visible on the page +- [ ] Author and publisher schema linked for content pages +- [ ] BreadcrumbList schema for nested pages + +--- + +## Quick wins (fastest to implement, biggest typical impact) + +1. Rewrite title tag for CTR +2. Rewrite meta description for CTR +3. Fix any missing or duplicate H1 +4. Add 2 to 3 internal links from existing related pages +5. Add alt text to images that lack it + +If a page is underperforming and you only have 30 minutes, run those five. diff --git a/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md b/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md new file mode 100644 index 0000000..71d1dd1 --- /dev/null +++ b/dist/pi/.agents/skills/seo-onpage/references/title-and-meta-patterns.md @@ -0,0 +1,306 @@ +# Title and Meta Patterns + +Patterns for writing strong title tags and meta descriptions. The title tag and meta description are the two most-edited and most-impactful elements in on-page SEO. They are also the two most often left as defaults. + +--- + +## Title tag patterns + +### The job of the title tag + +- Tell Google what the page is about (ranking signal) +- Tell the human what the page is about (CTR signal) +- Distinguish from other pages on the same site (uniqueness signal) +- Earn the click against 9 other titles in the SERP + +A title that does all four wins on rankings AND clicks. A title that does only the first ranks but earns no clicks. A title that does only the last earns clicks but ranks badly. + +### Length + +- 50-60 characters is the safe range for most desktop and mobile SERPs. +- Longer titles get truncated (Google appends "..."). +- Truncation is not catastrophic if the most important words are in the first 50 characters. + +### Character priority + +The most important word (typically the primary query target) goes near the front. Secondary words and brand go at the end. + +``` +[Primary query target] \| [Modifier or value prop] \| [Brand] +``` + +Examples: + +\| Bad \| Better \| +\|---\|---\| +\| "Welcome to Acme - your trusted partner in widgets since 1995" \| "Widgets for industrial use - Acme" \| +\| "Acme Inc. - Best widgets - Buy online" \| "Industrial widgets - free shipping - Acme" \| +\| "About us" \| "About Acme - 25 years building industrial widgets" \| + +### Patterns by page type + +#### Homepage + +``` +[Brand]: [One-line value prop] +``` + +Examples: +- "Notion: the all-in-one workspace for your notes and tasks" +- "Linear: built for modern software teams" +- "Acme Hardware: industrial widgets for builders" + +#### Category page + +``` +[Category name] - [Modifier or differentiator] \| [Brand] +``` + +Examples: +- "Industrial widgets - in stock, free shipping \| Acme" +- "Project management software for engineers \| Linear" +- "Recipes by region - 1,000+ tested recipes \| RecipeCo" + +#### Product / detail page + +``` +[Product name] - [Key benefit or spec] \| [Brand] +``` + +Examples: +- "10mm steel widget - 50 lb capacity \| Acme" +- "Linear Free - up to 10 users, unlimited issues \| Linear" +- "Mediterranean lentil soup recipe \| RecipeCo" + +#### Article / blog post + +``` +[Headline that promises value] - [Brand] +``` + +Examples: +- "How to choose an industrial widget supplier - Acme" +- "Linear vs Jira: 5 differences that actually matter - Linear" +- "Why your meta descriptions are getting rewritten - Search Engine Journal" + +The blog title is usually the H1 + brand. If the H1 is long, shorten for the title. + +#### Comparison / vs page + +``` +[Brand A] vs [Brand B]: [Differentiating angle] \| [Your brand] +``` + +Examples: +- "Linear vs Jira: speed, opinions, and team size \| Linear" +- "MongoDB vs PostgreSQL: when to pick which \| Engineering Blog" + +#### Pricing page + +``` +[Brand] pricing - [What is included] \| [Brand] +``` + +Examples: +- "Linear pricing - free forever for small teams \| Linear" +- "Pricing - simple, transparent, no surprises \| Acme" + +#### Geographic / location page + +``` +[Service] in [City], [State] \| [Brand] +``` + +Examples: +- "Plumbing services in Austin, TX \| Smith Plumbing" +- "Coworking in Brooklyn - day passes and memberships \| WorkSpace" + +--- + +## Title rules and anti-patterns + +### Do + +- Put the primary query near the front +- Include brand at the end +- Use a separator that the SERP renders cleanly (`\|`, `-`, `:`) +- Be specific (numbers, modifiers, segments earn attention) +- Match the H1 in spirit, not word-for-word + +### Do not + +- Repeat the primary query multiple times ("Widgets, industrial widgets, buy widgets - Widgets.com") +- Start with the brand on every page (homepage is the exception) +- Use ALL CAPS for emphasis +- Use clickbait phrasing that mismatches the page content +- Pad with filler words ("Welcome to," "Find the best," "Looking for") +- Append "Home" / "Default" / "Untitled" +- Leave it as the CMS default + +--- + +## Meta description patterns + +### The job of the meta description + +- Earn the click in the SERP +- Set expectations for what the page delivers +- Reinforce the primary query (Google bolds matched terms) + +The meta description is not a ranking signal directly. It is a CTR signal, which feeds back into ranking via behavioral signals. + +### Length + +- 140-160 characters. Longer gets truncated on most devices. +- Mobile truncates earlier than desktop. Front-load the value. + +### Structure + +Three moves in 1-3 sentences: + +1. Promise the value. What does the reader get if they click? +2. Justify it. Why is this credible? (Numbers, recency, specificity, authority.) +3. Cue the action. What should they expect to do or learn? + +Not every meta description does all three. The strongest do. + +### Examples + +\| Bad \| Better \| +\|---\|---\| +\| "Welcome to our blog where we write about widgets." \| "How to pick the right industrial widget for your project. 10 specs that matter, with a comparison chart." \| +\| "Acme Inc. is a leading provider of widgets and other products." \| "Industrial widgets in 50+ sizes. Free shipping over $100. Same-day dispatch from Austin, TX." \| +\| "Click here to learn more about our pricing." \| "Linear pricing: free forever for teams up to 10. Pro is $8/user/month. No setup fee. See plans and limits." \| + +--- + +## Meta description patterns by page type + +### Homepage + +``` +[What the brand does, one sentence]. [The audience or use case]. [The differentiator or social proof]. +``` + +Example: "Modern issue tracking for software teams. Built for speed. Used by 5,000+ teams from startups to enterprise." + +### Category page + +``` +[What the category contains]. [The selection or differentiator]. [Trust or shipping signal]. +``` + +Example: "Industrial widgets in 50+ sizes from 10mm to 200mm. Free shipping over $100. In stock and ready to ship from Austin." + +### Product / detail page + +``` +[Product, with key spec]. [Use case]. [Trust signal or guarantee]. +``` + +Example: "10mm steel widget rated to 50 lb. Built for industrial assembly lines. 5-year warranty, free returns." + +### Article / blog post + +``` +[The promise of the article in one sentence]. [The substance or evidence]. [Optional: who it is for]. +``` + +Example: "How to choose between Linear and Jira: 5 specific differences in workflow, speed, and pricing. With screenshots and benchmarks. For engineering managers comparing the two." + +### Pricing page + +``` +[The headline pricing]. [What is included]. [Anti-friction language]. +``` + +Example: "Linear is free forever for teams up to 10. Pro plan starts at $8/user/month. No setup fee, cancel anytime." + +--- + +## Meta description rules + +### Do + +- Front-load the value +- Use the primary query naturally (Google bolds it) +- Include numbers, specifics, and proof points +- Match the page's actual content +- Write for humans (it is a sales line, not a ranking line) + +### Do not + +- Pad with marketing-speak ("revolutionary," "industry-leading") +- Repeat the title verbatim +- End mid-sentence +- Stuff keywords (Google will rewrite the description if it looks unnatural) +- Leave the CMS default +- Use the same description on multiple pages + +--- + +## When Google rewrites your meta description + +Google rewrites meta descriptions when it thinks its rewrite will earn more clicks. Common triggers: + +- The description does not match the query +- The description is too short, too generic, or stuffed +- The page content has clearly different value from the description +- The page is matched against a long-tail query the description does not address + +To avoid rewrites: + +- Match the description to the page's actual content +- Make sure the primary query appears naturally in the description +- Keep the description specific and current + +If Google rewrites your description and the rewrite is wrong (low CTR, misleading), tighten the description and consider adding `name="description"` plus alternative phrasings via `<meta property="og:description">` for parity. + +--- + +## CTR optimization tips (beyond pattern) + +- Numbers earn attention. "5 ways," "100+ examples," "in 10 minutes." +- Year in title for evergreen-but-current content. "(2026)" earns clicks in fast-moving categories. Update annually. +- Brackets and parens are click-bait when overused, useful when accurate. "[Free Template]," "(2026 update)." +- Question titles work for some intents. "How do I [task]?" earns clicks for how-to. +- Comparison titles are click magnets. "X vs Y: [angle]." +- Promise-and-deliver framing. Title promises a specific value; the page delivers it. + +--- + +## Title and description audit shortcut + +For any page, ask: + +1. Does the title contain the primary query in the first 30 characters? +2. Is the title under 60 characters? +3. Is the title unique on the site? +4. Does the meta description promise value, justify it, and read as a human-written sentence? +5. Is the meta description under 160 characters? +6. Has Google rewritten the description? (Check Search Console performance report.) + +If 4 of 6 are "no," the title or description is the highest-leverage fix on the page. + +--- + +## A/B testing titles and descriptions + +For high-traffic pages, A/B test alternates. Tools that support this: native CMS tools, edge workers, dedicated SEO testing platforms. + +Test one variable at a time (title length, vs comparison hook vs question form, etc.). Run for 2-4 weeks per variant. Measure CTR and downstream conversion, not just rank position. + +--- + +## Snippet appearance is not just title and description + +What the SERP shows can include: + +- The title and description (this guide) +- Sitelinks (Google-auto, can be encouraged via clean IA) +- Rich results from schema (recipe, FAQ, product, review) +- Breadcrumbs (improves CTR, requires breadcrumb schema) +- Author and date (article schema) +- Featured snippets (a separate optimization layer) + +Title and description are the foundation. Schema and sitelinks are leverage on top. diff --git a/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md b/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md new file mode 100644 index 0000000..c1cb198 --- /dev/null +++ b/dist/pi/.agents/skills/seo-rank-tracking/SKILL.md @@ -0,0 +1,250 @@ +--- +name: seo-rank-tracking +description: "Set up and run rank tracking using Ahrefs MCP: pick the right keywords to track, segment them by purpose, set baselines, and define alert thresholds. Use this skill when starting a new tracking project, baselining for a campaign, choosing what to monitor, or building a rank reporting cadence. Triggers on rank tracking, keyword tracking, monitor rankings, track positions, what should we track, ranking dashboard, baseline rankings, alert thresholds. Also triggers when a stakeholder wants weekly or monthly ranking visibility." +category: seo-audit-suite +catalog_summary: "Setup, baseline, segmentation, alerting, dashboarding" +display_order: 7 +--- + +# SEO Rank Tracking + +Set up and run an ongoing rank tracking program using Ahrefs MCP data. Stack-agnostic. Produces a tracked keyword set, segmentation, baseline, alert thresholds, and a review cadence. + +--- + +## When to use + +- Starting rank tracking for a new property or section +- Baselining before a campaign, content launch, or major site change +- Deciding what keywords are worth tracking +- Setting up a ranking dashboard for stakeholders +- Establishing alert thresholds for ranking drops +- Reviewing whether the current tracked set is still meaningful + +## When NOT to use + +- Keyword discovery (use `seo-keyword`) +- Competitor keyword analysis (use `seo-keyword-gap-audit`) +- Diagnosing a ranking change that already happened (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) + +--- + +## Required inputs + +- Target property +- Target market and language +- Business priorities (which segments matter) +- Existing ranked keywords (Ahrefs Site Explorer) +- Stakeholder reporting cadence (weekly, monthly, quarterly) +- Confirmation Ahrefs MCP and Rank Tracker access + +--- + +## The framework: tracking taxonomy + +A good tracked keyword set has structure. Random keyword lists produce noisy dashboards. Segmented keyword sets produce signal. + +Group every tracked keyword into one of four buckets. + +### Bucket 1: Brand keywords + +Queries containing the brand name (and major variants and misspellings). + +Why track: + +- Detect brand visibility issues +- Catch competitors bidding on the brand +- Spot reputation problems early + +Volume in this bucket: typically 10-30 keywords for most brands. + +Healthy signal: position 1 for all variants. Anything else is investigate-worthy. + +### Bucket 2: Money keywords + +Queries that drive (or should drive) revenue: high-intent transactional and evaluation-stage queries directly tied to the business model. + +Why track: + +- These are the keywords that pay the bills +- Movement here directly affects revenue +- Stakeholders care most about these + +Volume in this bucket: 30-100 keywords for most properties. More for ecommerce. + +Healthy signal: top 3-5 positions. Watch for position drift in either direction. + +### Bucket 3: Opportunity keywords + +Queries the property is currently ranking on page 2-3 (positions 11-30) with potential to break into top 10. + +Why track: + +- These are the active growth bets +- Movement reflects whether content investment is working +- Quick wins typically come from this bucket + +Volume in this bucket: 50-200 keywords typically. + +Healthy signal: trending toward page 1 over a 90-day window. + +### Bucket 4: Competitor benchmark keywords + +A representative sample of head and torso queries shared with the competitor set, used to track relative position over time. + +Why track: + +- Measure share of voice +- Spot competitor gains in real time +- Provide industry context for movement + +Volume in this bucket: 50-150 keywords. + +Healthy signal: relative position improving or holding within a defined competitive band. + +--- + +## Selection criteria + +### Brand bucket + +- Brand name (exact) +- Brand name + product or service +- Brand name common misspellings +- Brand name + "review", "vs", "alternative" +- Brand-owned product names if relevant + +### Money bucket + +- Top 20 ranked keywords by traffic value (Ahrefs Site Explorer) +- Top transactional queries from Search Console with non-trivial impressions +- Conversion-driving queries identified in analytics +- Strategic head terms from `seo-keyword-gap-audit` output + +Quality over volume. 50 well-chosen money keywords beats 500 noisy ones. + +### Opportunity bucket + +- All keywords currently ranking positions 11-30 with monthly volume above a relevance-appropriate threshold +- Queries with rising impression volume in Search Console +- Output from the keyword gap audit's quick wins list + +Refresh this bucket quarterly. Opportunity is a moving target. + +### Competitor benchmark bucket + +- Keywords where 3+ competitors rank in top 20 +- Mix of head, torso, and informational queries +- Sized to represent the broader category + +This bucket is for relative comparison, not absolute targeting. + +--- + +## Segmentation beyond buckets + +Tag every tracked keyword on additional dimensions for filtering: + +\| Tag \| Purpose \| +\| --- \| --- \| +\| Topic or pillar \| Group by editorial theme \| +\| Funnel stage \| TOFU, MOFU, BOFU \| +\| Content type expected \| Article, product page, calculator, etc. \| +\| Page mapped \| Which URL is targeting this query \| +\| Country and language \| For multi-market sites \| +\| Device \| Desktop, mobile \| +\| SERP feature presence \| Featured snippet, AI overview, video, etc. \| + +Tagging up front pays off when filtering reports later. + +--- + +## Baselines + +Capture the starting state on day one. + +For each keyword, record: + +- Current position +- Current SERP composition (top 10 domains, dominant content type, SERP features present) +- Current click-through rate at that position (from Search Console if available) +- Date of baseline + +Baselines are the reference for measuring future movement. Without one, every dashboard is just current state. + +--- + +## Alert thresholds + +Not every position change deserves attention. Set thresholds that filter noise. + +### Default thresholds + +\| Bucket \| Alert if \| +\| --- \| --- \| +\| Brand \| Position drops below 1 for any tracked variant \| +\| Money \| Position drops by 5+ places, or out of top 10 \| +\| Opportunity \| Position rises into top 10 (positive alert), or drops past 30 \| +\| Competitor benchmark \| Aggregate share-of-voice changes by 10%+ \| + +Adjust thresholds based on volatility of the niche. High-competition spaces need looser thresholds to reduce false alarms. + +### Alert routing + +- Brand alerts: notify SEO lead and brand manager immediately +- Money alerts: notify SEO lead within a daily digest +- Opportunity alerts: weekly summary +- Competitor alerts: monthly summary + +--- + +## Workflow + +1. Define scope. Target property, market, language, stakeholders. +2. Pull starting data. Existing ranked keywords, Search Console queries, competitor overlap. +3. Build the tracked set. 4 buckets, 200-500 total keywords for most properties. +4. Segment with tags. Topic, funnel stage, page mapped, etc. +5. Configure tracking. Set up Ahrefs Rank Tracker projects with tags and locations. +6. Capture baseline. Day-one positions and SERP composition. +7. Define alert thresholds. By bucket. Wire to notification system. +8. Build the dashboard. See [`references/dashboard-template.md`](references/dashboard-template.md). +9. Set the cadence. Weekly review of money + brand. Monthly review of all. Quarterly rebuild of opportunity bucket. +10. Iterate. Drop dead keywords. Add new ones. Recalibrate thresholds based on noise. + +--- + +## Failure patterns + +- Tracking too many keywords. A 5,000-keyword tracker is unreadable. Pick fewer, watch closer. +- Tracking too few. A 30-keyword tracker misses the picture. Most properties need 200-500. +- No segmentation. Untagged tracked keywords produce dashboards that cannot be filtered. +- No baseline. Without day-one snapshots, "did the campaign work" becomes unanswerable. +- Alert fatigue. Loose thresholds produce too many alerts. Stakeholders stop reading. Tighten. +- Set and forget. Tracked keyword sets need quarterly review. Opportunity moves. Money keywords shift. +- Conflating position with traffic. A position-1 keyword with no clicks is worse than a position-5 keyword with steady traffic. Layer in CTR and clicks data. +- Single-device tracking on a mobile-dominant business. Track the device that matches the audience. +- Tracking aggregate position only. Aggregate position averages can hide important movement in specific buckets. Always show by bucket. +- Reporting absolute position without context. "We are position 4" means nothing. "Up from position 11 over 60 days" means something. + +--- + +## Output format + +A rank tracking setup document with: + +1. Tracking charter. Property, scope, stakeholders, cadence. +2. Tracked keyword set. All keywords with bucket and tag assignments. +3. Baseline snapshot. Position, SERP composition, CTR per keyword. +4. Alert configuration. Thresholds by bucket, routing. +5. Dashboard layout. What charts, what filters, what is visible. +6. Review cadence. Weekly, monthly, quarterly responsibilities. +7. Methodology notes. Country and device settings, refresh frequency, data caveats. + +Plus a recurring rank report at the chosen cadence (typically weekly or monthly). + +--- + +## Reference files + +- [`references/dashboard-template.md`](references/dashboard-template.md) - Template for the rank tracking dashboard layout, including the recurring report structure for weekly and monthly cadences. diff --git a/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md b/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md new file mode 100644 index 0000000..f3ec228 --- /dev/null +++ b/dist/pi/.agents/skills/seo-rank-tracking/references/dashboard-template.md @@ -0,0 +1,273 @@ +# Rank tracking dashboard template + +A template for the rank tracking dashboard and the recurring weekly and monthly rank reports. + +--- + +## Dashboard layout principle + +The dashboard should answer three questions in order: + +1. Are we okay? (brand and money buckets) +2. Are we growing? (opportunity bucket) +3. How do we compare? (competitor benchmark bucket) + +Anything that does not serve those three questions is clutter. + +--- + +## Section 1: Brand health (top of dashboard) + +Single panel. Status indicator. Should be glanceable. + +Display: + +- Position 1 status across all brand variants (count: e.g., "27 of 30 variants at position 1") +- Any brand variant not at position 1, listed below the status + +Alert color coding: + +- Green: all brand variants at position 1 +- Yellow: 1-3 variants below position 1 +- Red: 4+ variants below position 1, or any branded query showing competitor in top 3 + +--- + +## Section 2: Money keyword health + +The keystone section. Show: + +### Headline metric + +- Average position across all money keywords (current vs 30 days ago vs 90 days ago) +- Count of money keywords in top 3, top 10, top 20, beyond + +### Movement table + +Top 10 movers (positive and negative) over the chosen window: + +\| Keyword \| Bucket \| Current position \| Change \| Page mapped \| +\| --- \| --- \| --- \| --- \| --- \| +\| [keyword] \| Money \| 4 \| +6 \| /products/[slug] \| + +### Distribution chart + +Stacked bar showing how many money keywords are at each position band: + +- Top 3 +- Positions 4-10 +- Positions 11-20 +- Positions 21-50 +- Beyond 50 or unranked + +Track this distribution over time. Improving SEO shifts the distribution upward. + +--- + +## Section 3: Opportunity progress + +The growth section. + +### Headline metric + +- Count of opportunity keywords that broke into top 10 over the chosen window +- Count that fell out of opportunity range (past 30 or to top 10) +- Net opportunity bucket size (with quarterly refresh) + +### Top breakthroughs + +Keywords that crossed from positions 11-30 into top 10: + +\| Keyword \| Previous position \| Current position \| Page mapped \| Likely cause \| +\| --- \| --- \| --- \| --- \| --- \| +\| [keyword] \| 14 \| 7 \| /guides/[slug] \| Refresh shipped 30 days ago \| + +### Top regressions + +Keywords moving the wrong way: + +\| Keyword \| Previous position \| Current position \| Page mapped \| Likely cause \| +\| --- \| --- \| --- \| --- \| --- \| + +--- + +## Section 4: Competitor benchmark + +### Share of voice + +Aggregate position-weighted share of voice across the benchmark keyword set: + +\| Property \| SOV (current) \| SOV (90 days ago) \| Change \| +\| --- \| --- \| --- \| --- \| +\| [Target] \| 18% \| 14% \| +4 \| +\| [Competitor A] \| 22% \| 23% \| -1 \| +\| [Competitor B] \| 15% \| 16% \| -1 \| +\| [Competitor C] \| 12% \| 10% \| +2 \| + +### Head-to-head + +For top 20 strategic head terms, show position for target and each competitor side by side. + +--- + +## Section 5: SERP feature awareness + +Dashboard should call attention to SERP composition changes. + +Track: + +- Featured snippets owned by target (count, change) +- AI overviews appearing on target's tracked queries (count, change) +- Featured snippets owned by competitors on tracked queries +- New SERP feature types appearing (video carousels, image packs, etc.) + +A position-1 ranking that loses its featured snippet can lose 30%+ clicks while position stays the same. + +--- + +## Section 6: Filters + +The dashboard must be filterable by: + +- Bucket (brand, money, opportunity, benchmark) +- Topic or pillar tag +- Funnel stage tag +- Country and language +- Device +- Page mapped (URL) + +Filters let stakeholders drill from "the dashboard" to "my section". + +--- + +## Weekly report template + +The weekly report is for the SEO team and immediate stakeholders. + +``` +# Weekly rank report: [property] +Week of: [date range] +Prepared: [date] + +## Brand health + +[Green/Yellow/Red indicator] +[1-2 sentences. Anything not at position 1.] + +## Money keyword movement + +- Average position: [N] (vs [N] last week, [N] 90 days ago) +- Top 3 count: [N] (vs [N] last week) +- Top 10 count: [N] (vs [N] last week) + +### Notable gainers + +\| Keyword \| Previous \| Current \| Change \| +\| --- \| --- \| --- \| --- \| + +### Notable decliners + +\| Keyword \| Previous \| Current \| Change \| +\| --- \| --- \| --- \| --- \| + +## Opportunity progress + +- Breakthroughs to top 10: [N] +- Regressions out of opportunity range: [N] + +## Alerts triggered this week + +\| Date \| Keyword \| Bucket \| Alert \| Action taken \| +\| --- \| --- \| --- \| --- \| --- \| + +## Hypothesis or call-out + +[1-2 sentences on the most interesting movement and what it suggests.] +``` + +Length: 1 page. Readable in 3 minutes. + +--- + +## Monthly report template + +The monthly report is for broader stakeholders. Add narrative. + +``` +# Monthly rank report: [property] +Month: [month] +Prepared: [date] + +## Headline + +[1 paragraph. State of organic visibility.] + +## Brand and money keywords + +- Brand health: [status, with any concerns] +- Money keyword distribution: [chart description, key shifts] +- Notable wins: [bullet list] +- Notable concerns: [bullet list] + +## Opportunity progress + +- Breakthroughs to top 10 this month: [N] +- Quarterly target progress: [N of target N] +- Top opportunities watched + +## Competitive landscape + +- Share of voice: [target % vs competitor set] +- Notable competitor movement +- New SERP features observed + +## Themes for the month + +[3-5 themes from the data. Each is 1 paragraph.] + +## Recommendations for next month + +[Specific actions with owners and expected outcomes.] + +## Methodology + +- Tracking set: [N] keywords across [N] buckets +- Country: [list] +- Device: [list] +- Last refresh: [date] +- Data caveats: [list] +``` + +Length: 4-8 pages. + +--- + +## Quarterly rebuild + +Every 90 days, audit the tracked set itself. + +### Rebuild checklist + +- [ ] Brand bucket: any new product names, brand variants, or PR-driven query patterns? +- [ ] Money bucket: any keywords no longer aligned with current product or content focus? +- [ ] Money bucket: any new high-value queries identified by analytics or Search Console? +- [ ] Opportunity bucket: rebuild from current page 2-3 rankings; remove keywords that broke into top 10 (move to money) or fell past 30 (drop) +- [ ] Benchmark bucket: still representative of competitive landscape? +- [ ] Tags: any new pillars or topics that need tagging? +- [ ] Alert thresholds: too noisy? too quiet? recalibrate +- [ ] Reporting cadence: still useful at this frequency? + +Document the rebuild in a short changelog so historical comparisons remain interpretable. + +--- + +## Common dashboard pitfalls + +- Single big number. "Average position" alone hides bucket-level signal. +- No trend lines. Current state without trend is half the picture. +- No segmentation visible. A dashboard that cannot be filtered cannot answer follow-up questions. +- Showing every keyword. Stakeholders cannot read 500 rows. Show distributions and movers. +- Hiding SERP features. Feature changes cause invisible click drops. Always show them. +- Showing only target, not competitors. Movement is meaningless without context. +- Static data. A rank dashboard updated monthly is too slow for fast-moving niches. Match refresh to volatility. +- No annotations. Mark deploy dates, content launches, and known algorithm updates on charts so movement has context. diff --git a/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md b/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md new file mode 100644 index 0000000..a47c414 --- /dev/null +++ b/dist/pi/.agents/skills/seo-site-health-audit/SKILL.md @@ -0,0 +1,184 @@ +--- +name: seo-site-health-audit +description: "Triage technical SEO findings from Ahrefs Site Audit (and similar crawlers) by SEO impact, not just severity. Use this skill when reviewing crawl results, prioritizing technical fixes, scoping a technical SEO sprint, or after running any site-wide crawl. Triggers on site audit results, technical fix list, crawl errors, technical SEO triage, prioritize technical issues, what should we fix first, broken links, redirect chains. Also triggers when a long list of crawler issues is creating decision paralysis." +category: seo-audit-suite +catalog_summary: "Triage Ahrefs Site Audit findings by SEO impact, not severity" +display_order: 6 +--- + +# SEO Site Health Audit + +Triage technical SEO findings from Ahrefs Site Audit (or any equivalent crawler) by impact on rankings and traffic, not by raw issue count or severity label. Stack-agnostic. Produces a prioritized backlog of fixes mapped to business impact. + +--- + +## When to use + +- After running an Ahrefs Site Audit or other site-wide crawl +- Reviewing a long list of technical issues and needing to prioritize +- Scoping a technical SEO sprint +- Pre-launch or post-migration technical verification +- Quarterly technical health check +- When developer time is limited and you must pick the highest-leverage fixes + +## When NOT to use + +- Running the crawl itself (use the crawler tool directly) +- Diagnosing specific traffic drops (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) +- Pure technical strategy or schema design (use `seo-technical`) + +--- + +## Required inputs + +- Crawl results from Ahrefs Site Audit (or equivalent) +- Search Console coverage and Core Web Vitals data +- Property's organic traffic profile (which pages drive traffic) +- Stakeholder time and developer capacity available +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: triage by SEO impact, not severity + +Crawlers label issues "critical", "warning", "notice". These labels are useful but not sufficient. Two issues both labeled "critical" can have wildly different actual impact on the property. + +Triage on three axes. + +### Axis 1: Page-level traffic impact + +Does the issue affect a page that drives meaningful organic traffic, or one that does not? + +A "critical" issue on a tag archive with zero traffic is lower priority than a "warning" on a top-10-traffic landing page. + +Tier the affected URLs: + +- Tier 1: Top 10% of pages by organic traffic +- Tier 2: Pages that rank but do not yet drive significant traffic (page 2-3 results) +- Tier 3: Pages that exist but do not rank meaningfully + +A fix on Tier 1 is worth 10x a fix on Tier 3 in most cases. + +### Axis 2: Mechanism of impact + +Does the issue actually move rankings or traffic? Some "critical" issues are aesthetic or theoretical. + +Categories of real impact: + +\| Mechanism \| Examples \| +\| --- \| --- \| +\| Indexability \| Accidental noindex, robots.txt blocks, canonical errors, X-Robots-Tag \| +\| Crawlability \| Crawl traps, infinite redirects, 5xx errors, slow server response \| +\| Renderability \| JS errors blocking critical content, blocked resources \| +\| Core Web Vitals \| LCP, INP, CLS in the poor band \| +\| Structured data \| Errors on rich-result-eligible pages (not warnings) \| +\| Internal link integrity \| 404s on internally linked URLs, broken canonicals \| +\| Hreflang \| Errors on multilingual deployments \| + +Categories of low or theoretical impact: + +\| Type \| Why it is lower priority \| +\| --- \| --- \| +\| Title tag length warnings \| Not a ranking factor in itself \| +\| Meta description length \| Not a ranking factor \| +\| H1 absence on low-traffic pages \| Marginal impact \| +\| Alt text missing on decorative images \| Accessibility issue, low SEO impact \| +\| Schema warnings (not errors) \| Often best-practice nudges, not ranking issues \| + +Fix the high-mechanism categories first. + +### Axis 3: Effort + +Some issues are 5-minute fixes. Some are multi-sprint projects. + +- S (small): Configuration change, single template edit, sitemap regeneration +- M (medium): Theme or component change, redirect map work, template-level fixes +- L (large): Architecture change, re-platform, framework migration, schema overhaul + +--- + +## The triage matrix + +Combine the three axes into a priority score. + +\| Tier \| Mechanism \| Effort \| Priority \| +\| --- \| --- \| --- \| --- \| +\| Tier 1 \| High mechanism \| S \| P0 (do this week) \| +\| Tier 1 \| High mechanism \| M \| P1 (do this sprint) \| +\| Tier 1 \| High mechanism \| L \| P2 (plan as project) \| +\| Tier 1 \| Low mechanism \| S \| P3 (batch when convenient) \| +\| Tier 1 \| Low mechanism \| M-L \| Park unless evidence emerges \| +\| Tier 2 \| High mechanism \| S \| P1 \| +\| Tier 2 \| High mechanism \| M-L \| P2 \| +\| Tier 3 \| High mechanism \| S \| P3 \| +\| Tier 3 \| Anything else \| Anything \| Park \| + +P0-P1 work earns the team's attention. P2 goes on the roadmap. P3 batches into routine maintenance. Park is honest about deprioritization. + +--- + +## Workflow + +1. Pull the crawl results. Ahrefs Site Audit + Search Console + Core Web Vitals. +2. Tier the URLs. Use organic traffic data. Tag every affected URL as Tier 1, 2, or 3. +3. Categorize each issue by mechanism. High or low impact mechanism. +4. Estimate effort per fix type. Group similar fixes into one effort estimate. +5. Apply the triage matrix. Assign P0-P3 or Park. +6. Cluster the fixes. Group fixes that share an effort: one template change can resolve hundreds of issues. +7. Build the backlog. P0 first, P1 next, etc. Add fix descriptions, owners, expected impact. +8. Add measurement. What metric will confirm the fix worked? Define before shipping. +9. Hand off. Output feeds the development backlog and `seo-audit-orchestration`. +10. Re-crawl after fixes. Confirm resolution. Update the backlog. + +--- + +## High-leverage clusters worth looking for + +These patterns commonly produce outsized impact when fixed: + +- Wholesale redirect chain cleanup. One sitemap update plus internal link updates can resolve thousands of "redirect chain" issues at once. +- Accidental noindex on a template. A single line of code change can re-index hundreds or thousands of pages. +- Sitemap freshness pipeline. A broken sitemap regeneration job affects every issue that depends on Search Console seeing the right URLs. +- Canonical inconsistencies on faceted navigation. A template-level canonical fix can resolve duplicate content issues across an entire ecommerce category tree. +- Robots.txt restored. A reverted production robots.txt can recover a sitewide drop in days. +- Hreflang block fix. One template change resolves hreflang issues across the whole multilingual site. +- Image optimization at the asset pipeline. Fixing the build process resolves thousands of individual asset issues. + +When you spot one of these, prioritize even if individual issues look small. The cluster impact is large. + +--- + +## Failure patterns + +- Severity worship. Treating every "critical" label as truly critical. Many are not. Triage by mechanism and traffic impact. +- Counting issues. Reporting "we fixed 1,200 issues" without showing traffic or ranking impact wastes engineering credibility. +- Skipping the tiering. Fixing 100 Tier-3 issues before 5 Tier-1 issues is busy work. +- Single-issue fixes. Most issues come in clusters. Fixing one redirect chain when 800 share the same root cause is the wrong unit of work. +- No re-crawl. "Fixed" without verification leaves doubt. Always re-crawl after major fixes. +- Ignoring Search Console. Ahrefs sees what its crawler finds. Search Console reflects what Google actually sees and indexes. Use both. +- Treating Core Web Vitals like a checklist. CWV is field data, not lab data. Optimize for real-user experience, not synthetic scores. +- Fixing low-mechanism issues for show. A clean technical report with no traffic gain helps no one. +- Not measuring. Define the metric that proves the fix worked before fixing. + +--- + +## Output format + +A site health triage document with: + +1. Summary. Total issues, top 3 fix clusters, expected impact. +2. URL tiering. How URLs were classified and counts per tier. +3. Issue categorization. Counts by mechanism category, by tier, by priority band. +4. Prioritized backlog. P0-P3 ordered. Each item has: issue, affected URLs, fix description, effort, expected impact, owner. +5. Fix clusters. Groups of issues that share a fix. Highest leverage at the top. +6. Measurement plan. Per fix or cluster, what proves it worked. +7. Methodology. Crawler used, date, scope, caveats. + +Length: 5-12 pages plus a backlog spreadsheet. + +--- + +## Reference files + +- [`references/issue-impact-table.md`](references/issue-impact-table.md) - Mapping table of common crawler issues to mechanism impact and typical fix effort, plus the triage matrix in detailed form. diff --git a/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md b/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md new file mode 100644 index 0000000..672e1b0 --- /dev/null +++ b/dist/pi/.agents/skills/seo-site-health-audit/references/issue-impact-table.md @@ -0,0 +1,190 @@ +# Issue impact table + +A reference table mapping common crawler-reported issues to their actual SEO impact mechanism and typical fix effort. Use it to triage Ahrefs Site Audit (or any equivalent) findings without treating every "critical" label as equally important. + +--- + +## How to use + +For each issue type from the crawler: + +1. Look up the mechanism and effort here. +2. Combine with URL tier (Tier 1 = top 10% by traffic) using the triage matrix. +3. Assign priority band P0-P3 or Park. + +Mechanism tiers: + +- HIGH: Direct effect on indexing, rankings, or Core Web Vitals. +- MEDIUM: Indirect effect via crawl, equity flow, or user signals. +- LOW: Best practice nudge or cosmetic. Real impact is usually marginal. + +--- + +## Indexability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Page returns noindex on indexed URL \| HIGH \| S \| Template fix usually resolves at scale \| +\| Robots.txt blocks important URLs \| HIGH \| S \| One file edit \| +\| X-Robots-Tag header set to noindex \| HIGH \| S-M \| Often a CDN or hosting config \| +\| Canonical points to non-canonical URL \| HIGH \| M \| Often template-level \| +\| Canonical points to redirect \| HIGH \| S \| Update canonical to final URL \| +\| Self-canonical missing on important page \| MEDIUM \| S \| Add to template \| +\| URL not in sitemap but indexed \| MEDIUM \| S \| Regenerate sitemap \| +\| URL in sitemap but noindexed \| HIGH \| S \| Decide indexability, fix one or the other \| + +--- + +## Crawlability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| 5xx errors on URLs \| HIGH \| M-L \| Investigate hosting and app errors \| +\| 4xx errors on internally linked URLs \| HIGH \| M \| Fix links or add redirects \| +\| Redirect chain (3+ hops) \| MEDIUM \| M \| Update final destination in links \| +\| Redirect loop \| HIGH \| S \| Fix immediately \| +\| Slow time to first byte \| MEDIUM \| M-L \| Hosting, caching, or app changes \| +\| Crawl trap (infinite parameter combinations) \| HIGH \| M \| Robots disallow patterns or canonical \| +\| Orphan page (indexed but no internal links) \| MEDIUM \| S-M \| Add internal links or noindex \| +\| Excessive redirects in sitemap \| MEDIUM \| S \| Update sitemap to final URLs \| +\| 301 used where 302 intended (or vice versa) \| LOW-MEDIUM \| S \| Audit and fix per case \| + +--- + +## Renderability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Critical content rendered only via JS (with crawler issues) \| HIGH \| L \| Server render, prerender, or hybrid \| +\| Blocked CSS or JS resources \| MEDIUM \| S \| Allow in robots.txt \| +\| Excessive client-side dependencies for above-fold content \| MEDIUM \| M-L \| Code splitting and SSR \| +\| Render mismatch (HTML differs from rendered DOM in important ways) \| HIGH \| M-L \| Investigate framework rendering \| + +--- + +## Core Web Vitals (field data) + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| LCP > 4 seconds (poor band) on Tier 1 pages \| HIGH \| M-L \| Image optimization, caching, render path \| +\| LCP 2.5-4 seconds (needs improvement) \| MEDIUM \| M \| Lower priority but still worth fixing \| +\| INP > 500ms (poor band) \| HIGH \| M-L \| JS optimization, hydration deferral \| +\| CLS > 0.25 (poor band) \| HIGH \| S-M \| Reserve space for images, ads, embeds \| +\| CLS 0.1-0.25 \| LOW-MEDIUM \| S \| Often quick wins \| + +CWV thresholds are based on the 75th percentile of real-user data per URL group. + +--- + +## Structured data issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Schema error blocking rich result eligibility \| HIGH \| S-M \| Fix the offending field \| +\| Schema warning (recommended field missing) \| LOW \| S \| Optional improvement \| +\| Wrong schema type for content \| MEDIUM \| S \| Replace with correct type \| +\| Schema markup but content does not match \| HIGH \| M \| Either fix schema or fix content (Google penalizes mismatch) \| +\| Duplicate schema across multiple types \| LOW-MEDIUM \| S \| Clean up duplicates \| + +Pages eligible for rich results (FAQ, How-to, Recipe, Product, etc.) deserve high priority. Schema on pages without rich result eligibility is lower priority. + +--- + +## Internal link integrity + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Internal link to 404 \| MEDIUM \| S \| Update or remove link \| +\| Internal link to redirect \| LOW \| S \| Update to final URL when batching \| +\| Internal link with empty anchor \| LOW \| S \| Add descriptive anchor \| +\| Page receiving zero internal links (orphan) \| MEDIUM \| S-M \| Add links or reassess if page should exist \| +\| Important page with very few internal links \| MEDIUM \| S \| Identify and add link points \| +\| Footer or sitewide internal link to broken URL \| MEDIUM \| S \| High visibility, fix quickly \| + +--- + +## Hreflang (multilingual sites) + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing return tag (hreflang reciprocity) \| HIGH \| M \| Template fix often resolves at scale \| +\| Hreflang points to redirected URL \| MEDIUM \| S \| Update to final URL \| +\| Hreflang points to noindexed URL \| HIGH \| S \| Decide indexability or remove hreflang \| +\| Hreflang language code malformed \| HIGH \| S \| Use ISO 639-1 + ISO 3166-1 alpha-2 \| +\| Mixing x-default and specific tags incorrectly \| MEDIUM \| S \| Audit pattern across site \| + +Multilingual sites with broken hreflang often see the wrong locale rank in the wrong market. Real ranking impact. + +--- + +## On-page elements + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing title tag \| MEDIUM \| S \| Add via template \| +\| Duplicate title tag across many pages \| MEDIUM \| S-M \| Template fix or unique-by-default \| +\| Missing meta description \| LOW \| S \| Affects CTR, not ranking \| +\| Duplicate meta descriptions \| LOW \| S \| Affects CTR, not ranking \| +\| Missing H1 on Tier 1 page \| MEDIUM \| S \| Add to template \| +\| Missing H1 on Tier 3 page \| LOW \| S \| Park unless trivial to fix \| +\| Multiple H1s \| LOW \| S \| Modern HTML allows; rarely a real issue \| +\| Title or H1 that does not match content topic \| MEDIUM \| S \| Audit content and update \| + +--- + +## Image issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing alt text on content images \| LOW (SEO), HIGH (accessibility) \| S \| Important for accessibility regardless \| +\| Missing alt text on decorative images \| LOW \| S \| Use empty alt="" \| +\| Image weight (large file size) on Tier 1 page \| HIGH \| M \| Asset pipeline fix at scale \| +\| Image format not modern (no WebP/AVIF) \| MEDIUM \| M \| Pipeline change \| +\| Image lazy loading missing \| MEDIUM \| S \| Add `loading="lazy"` to off-screen images \| +\| Hero image lazy loaded \| MEDIUM \| S \| Should be `loading="eager"` for LCP \| + +--- + +## Security and trust + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Mixed content (HTTPS page loading HTTP resources) \| MEDIUM \| S \| Update resource URLs \| +\| Expired or misconfigured SSL \| HIGH \| S \| Fix immediately \| +\| HSTS missing \| LOW \| S \| Best practice \| +\| Internal links use HTTP, page is HTTPS \| LOW \| S \| Update links to relative or HTTPS \| + +--- + +## Cluster opportunities + +When you see multiple issues from the same root cause, treat as one fix: + +\| Cluster signal \| Single fix \| +\| --- \| --- \| +\| Hundreds of "redirect chain" warnings \| Update internal links and sitemap to final URLs \| +\| Sitewide "missing canonical" \| Add canonical to base template \| +\| Mass "noindex on indexable URL" \| Audit template-level meta tag \| +\| Many "page not in sitemap" \| Regenerate sitemap from canonical URL list \| +\| Many slow LCP pages with same image pattern \| Optimize image pipeline once \| +\| Many hreflang errors with same pattern \| Template-level hreflang fix \| +\| Many H1 issues on archive pages \| Theme or template change \| + +Always look for clusters before fixing one-off. Cluster fixes are 10-100x more efficient. + +--- + +## Park or skip + +These rarely deserve dedicated work even when flagged: + +- Title tag length warnings (within reason; only fix if truncation visibly hurts CTR on a Tier 1 page) +- Meta description length warnings (same logic) +- "URL contains uppercase" if redirects already handle it +- "URL contains underscore" if URLs are stable and ranking +- Trailing slash inconsistency if redirects handle it +- Schema warnings (not errors) on pages with no rich result eligibility +- HTML validation issues that do not affect rendering or indexing +- Old browser-specific issues (IE-era) + +Park them. Document why. Move on. diff --git a/dist/pi/.agents/skills/seo-technical/SKILL.md b/dist/pi/.agents/skills/seo-technical/SKILL.md new file mode 100644 index 0000000..ef9c358 --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/SKILL.md @@ -0,0 +1,154 @@ +--- +name: seo-technical +description: "Run a comprehensive technical SEO audit covering crawlability, indexability, rendering, site architecture, structured data, page experience, security, and internationalization. Use this skill whenever the user asks about technical SEO, crawl issues, indexing problems, sitemaps, robots.txt, canonical tags, schema markup, page speed, Core Web Vitals, hreflang, redirects, or site-wide search performance. Triggers on technical SEO, site audit, crawlability, indexability, sitemap, robots.txt, canonical, redirect chain, schema, JSON-LD, Core Web Vitals, page speed, hreflang, mobile usability, HTTPS, security headers, render-blocking, JavaScript SEO. Also triggers when a site has indexing problems, traffic drops, or migration concerns, even if 'technical SEO' is not said explicitly." +category: seo-foundation +catalog_summary: "Crawlability, indexability, rendering, schema, page experience" +display_order: 2 +--- + +# Technical SEO + +Audit and fix the layer beneath the content: how search engines crawl, render, index, and trust a site. Stack-agnostic. + +--- + +## When to use + +- Site-wide audit before or after a migration +- Investigating indexing or ranking drops +- Setting up SEO foundations on a new site +- Auditing Core Web Vitals or page experience signals +- Fixing crawl waste, redirect chains, or canonical issues +- Setting up multilingual or multi-regional sites + +## When NOT to use + +- Single-page on-page optimization (use `seo-onpage`) +- Keyword strategy or content planning (use `seo-keyword`) +- Competitor backlink or SERP analysis (use `seo-competitor`) +- Pure performance optimization without SEO context (use `performance-optimization`) + +--- + +## Required inputs + +- The site URL or staging URL +- Access to (at minimum) view the rendered HTML, robots.txt, and sitemap +- Ideally: search console access, server logs, and a crawler + +If the site is large (10K+ URLs), confirm whether the audit is a full crawl or a sample. + +--- + +## The framework: 6 layers + +Technical SEO has six layers, stacked. A failure in a lower layer breaks everything above it. + +### 1. Crawlability +Can search engines access the URLs? + +- robots.txt does not block important paths +- No accidental `noindex` on indexable pages +- No accidental `disallow` patterns blocking CSS or JS (rendering breaks) +- Sitemap is present, returns 200, and lists canonical URLs only +- Sitemap is referenced in robots.txt +- No infinite spaces (faceted nav generating endless URLs) +- Crawl budget is not wasted on low-value URLs + +### 2. Indexability +Of crawlable URLs, which should be indexed? + +- One canonical URL per piece of content (no duplicates) +- Canonical tags self-reference on canonical pages +- `noindex` on staging, search results, filter pages, thank-you pages, internal admin +- No mixed signals (canonical pointing one way, sitemap another, internal links a third) +- Pagination handled correctly (rel=next/prev is deprecated, but consistent canonicals matter) +- Parameter handling deliberate (UTM, session IDs, sort orders) + +### 3. Rendering +Does the rendered HTML match what crawlers see? + +- Critical content visible without JavaScript (or properly server-rendered) +- For SPAs: confirm Googlebot sees the rendered content (test with the URL Inspection tool) +- No cloaking (showing different content to bots vs users) +- Lazy-loaded content has proper loading attributes +- Hydration errors do not strip content from the rendered DOM + +### 4. Site architecture +Is the site structured for both users and crawlers? + +- Clear URL hierarchy that mirrors site structure +- Important pages reachable in 3 clicks or fewer from the homepage +- Internal linking distributes authority logically +- Breadcrumb navigation present and marked up with schema +- No orphan pages (pages with no internal links) +- No redirect chains (one redirect max) +- No 4xx errors on internally-linked URLs + +### 5. Structured data and signals +Does the site speak crawler language? + +- Schema.org markup on appropriate page types +- JSON-LD format (preferred over microdata) +- Validates in the Rich Results Test +- Organization or LocalBusiness schema on the homepage or about page +- BreadcrumbList schema on nested pages +- Author and publisher schema linked correctly on content pages +- llms.txt present at the root (for AI crawlers, see `seo-aeo-geo`) + +### 6. Page experience and security +Does the site meet the page experience baseline? + +- HTTPS on all pages, no mixed content +- HSTS header set +- Core Web Vitals pass (LCP, INP, CLS within thresholds) +- Mobile-friendly (responsive, no horizontal scroll, tap targets sized correctly) +- No intrusive interstitials on mobile +- Stable URL structure (no random URL changes between deploys) +- 404 pages return 404, not 200 with "page not found" content (soft 404) + +--- + +## Workflow + +1. Define scope. Whole site, a subfolder, a migration check, or a specific issue. +2. Confirm access. What can you actually see (HTML, robots, sitemap, search console, server logs, staging)? +3. Crawl. Use a crawler to enumerate URLs and statuses. Sample if the site is huge. +4. Run the 6-layer framework. Score each, note specific issues with example URLs. +5. Cross-reference. Search console for what's actually indexed. Compare to sitemap and crawl output. +6. Prioritize. Critical (blocks indexing or causes traffic loss), Important (suboptimal), Nice-to-have (polish). +7. Write the report. Use the template in [`references/audit-template.md`](references/audit-template.md). + +--- + +## Failure patterns + +- Optimizing rankings on a page that is `noindex`. Always check indexability before content work. +- Adding sitemaps without fixing canonical issues. A sitemap of duplicate URLs is worse than no sitemap. +- Blocking crawlers from CSS or JS. Breaks Google's rendering. Common in over-aggressive robots.txt files. +- Over-relying on canonical tags. Canonicals are hints, not directives. Use redirects when content actually moved. +- Migrating without a redirect map. Single biggest cause of post-migration traffic loss. +- Treating Core Web Vitals as the only ranking signal. Page experience matters but does not override relevance. + +--- + +## Output format + +Default output is a markdown audit at `seo-technical-audit.md`. Structure: + +1. Scope and methodology +2. Executive summary (3 to 5 critical findings) +3. 6-layer score +4. Critical issues (with example URLs) +5. Important issues +6. Nice-to-have polish +7. Implementation roadmap (sequenced) + +For migrations, include a redirect map as a CSV alongside the report. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable technical SEO audit template. +- [`references/migration-checklist.md`](references/migration-checklist.md) - Pre and post-migration checklist (covers the highest-risk scenario). diff --git a/dist/pi/.agents/skills/seo-technical/references/audit-template.md b/dist/pi/.agents/skills/seo-technical/references/audit-template.md new file mode 100644 index 0000000..a424d3f --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/references/audit-template.md @@ -0,0 +1,321 @@ +# Technical SEO Audit Template + +Fillable template for a technical SEO audit. The audit covers crawlability, indexability, rendering, schema, page experience, and site architecture. + +The output is a stakeholder-readable report plus a prioritized backlog. For migration scenarios specifically, also use `migration-checklist.md`. + +--- + +## Audit metadata + +Site: [Domain] +Pages audited: [Sample size and selection method] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Tools used: [Crawler, GSC, log analyzer, Lighthouse, schema validator, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall technical state. +2. The single biggest blocker. +3. The estimated traffic at risk if technical issues persist. +4. The recommended next move. +5. Estimated effort for the top fix. + +> [Summary] + +--- + +## 1. Crawlability + +Can search engines crawl the site? + +### Robots.txt + +- [ ] File exists at `/robots.txt` +- [ ] File is syntactically valid (test in GSC) +- [ ] Critical sections of the site are not accidentally disallowed +- [ ] Specific user agents are not blocked (`Googlebot`, `Bingbot`) +- [ ] Sitemap location is declared (`Sitemap: https://example.com/sitemap.xml`) + +### XML sitemap(s) + +- [ ] Sitemap exists and is reachable +- [ ] Sitemap is referenced in robots.txt +- [ ] Sitemap is submitted in Search Console +- [ ] Sitemap contains only canonical, indexable URLs +- [ ] Sitemap is updated automatically when content changes +- [ ] Sitemap is split if over 50,000 URLs or 50MB +- [ ] `lastmod` reflects the actual last meaningful update (not the build date) + +### Internal linking + +- [ ] No important pages are orphaned (zero internal inlinks) +- [ ] Crawl-discoverable from the homepage within 4 clicks +- [ ] No internal links go to redirected URLs +- [ ] No internal links go to broken URLs (404) +- [ ] Anchor text is descriptive (avoid "click here," "read more") +- [ ] No `nofollow` or `noindex` on important internal pages + +### Crawl budget + +- [ ] Log analysis confirms Googlebot reaches the important sections regularly +- [ ] No crawl traps (calendar pages, infinite faceted nav, session ID parameters) +- [ ] Faceted nav uses `noindex,follow` or controlled parameter handling +- [ ] No duplicate URLs from URL parameter variations (UTMs, tracking, sort orders) +- [ ] Pagination handled with `rel="next"` and `rel="prev"` or paginated URL structure (no infinite scroll for important content) + +--- + +## 2. Indexability + +Can search engines index the site? + +### Index status + +- [ ] GSC "Indexed" count matches expected (production URL count) +- [ ] GSC "Not indexed" reasons are reviewed and addressed +- [ ] "Discovered - currently not indexed" pages are not high-value (or are addressed) +- [ ] "Crawled - currently not indexed" pages are not high-value (or are addressed) + +### Index directives + +- [ ] No `<meta name="robots" content="noindex">` on important pages +- [ ] No `X-Robots-Tag: noindex` HTTP header on important pages +- [ ] Staging or dev environments are noindexed (and not bypassable) +- [ ] Login pages, internal search results, and tag archives are noindex (or otherwise low-priority) + +### Canonicalization + +- [ ] Every page has a `rel="canonical"` tag +- [ ] Self-canonical URLs match the actual URL (no http/https mismatch, no trailing slash mismatch) +- [ ] Cross-canonical references point to indexable, live URLs +- [ ] Pagination uses self-canonicals (not pointing to page 1) +- [ ] No conflicting signals (canonical to URL A, redirect to URL B) + +### Status codes + +- [ ] 200 for live pages +- [ ] 301 for permanently moved pages +- [ ] 302 used only for genuinely temporary redirects +- [ ] 404 for genuinely missing pages (with helpful 404 page) +- [ ] 410 for intentionally removed pages +- [ ] 5xx errors investigated and resolved + +### Redirect chains + +- [ ] No redirect chains over 1 hop (A → B is fine; A → B → C → D is not) +- [ ] No redirect loops +- [ ] HTTPS redirect from HTTP is single-hop +- [ ] Trailing-slash redirect is single-hop + +--- + +## 3. Rendering + +Can search engines render JavaScript-dependent content? + +### Rendering strategy + +- [ ] Critical content is in the initial HTML response (server-rendered or static) +- [ ] If JS-rendered, "fetch as Google" via URL Inspection in GSC shows full content +- [ ] No reliance on user interaction to load primary content (no "click to load article") + +### Specific rendering risks + +- [ ] No JS-rendered title tags or meta descriptions (these often fail to be picked up) +- [ ] No JS-injected canonical tags +- [ ] Lazy-loaded images use native `loading="lazy"` or proper IntersectionObserver implementation +- [ ] Lazy-loaded content above the fold is not lazy-loaded +- [ ] CSS is not blocking critical content rendering + +### JavaScript SEO sanity check + +- [ ] Disable JS in DevTools and reload key pages. Critical content should still appear. +- [ ] Use the URL Inspection tool in GSC and view the rendered HTML. Compare to user-rendered version. + +--- + +## 4. Schema and structured data + +- [ ] Pages have appropriate schema (Article, Product, Organization, BreadcrumbList, FAQ, HowTo, Recipe, etc.) +- [ ] Schema validates in Google's Rich Results Test +- [ ] Schema validates in Schema.org validator +- [ ] No schema violations in GSC enhancement reports +- [ ] BreadcrumbList schema implemented (often-overlooked CTR boost) +- [ ] Organization schema on the homepage +- [ ] WebSite schema with SearchAction (enables sitelinks search box) +- [ ] No schema for content not visible on the page + +--- + +## 5. Page experience + +### Core Web Vitals + +Field data preferred (CrUX, RUM). Lab data is a fallback diagnostic. + +\| Metric \| Target \| Mobile p75 \| Desktop p75 \| Status \| +\|---\|---\|---\|---\|---\| +\| LCP \| < 2.5s \| \| \| \| +\| INP \| < 200ms \| \| \| \| +\| CLS \| < 0.1 \| \| \| \| + +For detailed performance audit, see `performance-optimization` skill. + +### HTTPS + +- [ ] Entire site served over HTTPS +- [ ] No mixed content warnings +- [ ] HSTS header set +- [ ] Certificate valid and not approaching expiry + +### Mobile + +- [ ] Responsive (single URL, single HTML, CSS adapts) +- [ ] Mobile usability passes in GSC +- [ ] No tap targets too close together +- [ ] Viewport meta tag set + +### Safe browsing + +- [ ] No security warnings in GSC +- [ ] No malware or phishing flags + +--- + +## 6. International SEO + +If the site is multilingual or multi-region: + +- [ ] `hreflang` tags present and correct on every locale alternate +- [ ] `hreflang` includes self-reference +- [ ] `x-default` set for language picker fallback +- [ ] Language and region codes follow ISO standards +- [ ] No hreflang errors in GSC International Targeting report +- [ ] URL structure follows a consistent pattern (subdir / subdomain / ccTLD) + +--- + +## 7. Site architecture and URLs + +### URL hygiene + +- [ ] URLs are lowercase +- [ ] URLs use hyphens, not underscores or spaces +- [ ] URLs are short and descriptive +- [ ] No session IDs or tracking parameters in canonical URLs +- [ ] URL structure reflects content hierarchy (category → subcategory → page) + +### Trailing slash + +- [ ] Consistent trailing slash policy (with or without) +- [ ] One version redirects to the other (no duplicates) + +### Subdomains vs subdirectories + +- [ ] Strategic decision documented (subdir typically pools authority better; subdomain better for separate sites) +- [ ] `www` and non-`www` consolidated via 301 + +--- + +## 8. Search Console hygiene + +- [ ] Both `https://www` and `https://` (and `http://` versions) verified as separate properties +- [ ] Domain property verified (the recommended approach) +- [ ] Sitemap submitted and showing "Success" +- [ ] No critical issues in Coverage report +- [ ] No manual actions or security issues +- [ ] Crawl stats reviewed (sudden drops or spikes investigated) + +--- + +## 9. Log file analysis (advanced) + +For larger sites, server logs reveal what crawlers actually do, vs what the site allows. + +- [ ] Top crawled pages match top-priority pages +- [ ] Googlebot does not waste crawl on noindex / parameter / faceted URLs +- [ ] No orphaned pages getting crawler traffic +- [ ] No 5xx errors served to Googlebot + +--- + +## Findings summary + +\| Severity \| Issue \| Pages affected \| Recommended fix \| Effort \| +\|---\|---\|---\|---\|---\| +\| P0 (blocking) \| \| \| \| \| +\| P1 (high) \| \| \| \| \| +\| P2 (medium) \| \| \| \| \| +\| P3 (low) \| \| \| \| \| + +### Severity definitions + +- P0: Critical content cannot be crawled or indexed; major technical errors causing exclusion from search. +- P1: Significant indexability or rendering issues affecting traffic; broken canonicals; large redirect chains. +- P2: Suboptimal but not blocking; missing schema, suboptimal sitemap, partial CWV failures. +- P3: Polish; minor inefficiencies, documentation gaps. + +--- + +## Recommendations + +### Now (this week) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Next (this sprint or month) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Later (this quarter) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| + +--- + +## Monitoring after fixes ship + +- [ ] GSC Coverage report rechecked weekly until stable +- [ ] Position tracking for top queries to confirm no regression +- [ ] Log analysis re-run 2-4 weeks after fixes ship +- [ ] CWV field data tracked for affected page templates +- [ ] Set alerts for: 5xx errors, sudden index drops, certificate expiry + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- Crawl tool config: [tool, depth, render mode, user agent] +- Sample selection: [How URLs were selected for deep review] +- Field data window: [Date range] +- Caveats: [What this audit did not cover] + +--- + +## Sign-off + +Audit conducted by: [Name, date] +Reviewed with: [Stakeholders] +Implementation owner: [Name] +Re-audit scheduled: [Date] diff --git a/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md b/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md new file mode 100644 index 0000000..c812907 --- /dev/null +++ b/dist/pi/.agents/skills/seo-technical/references/migration-checklist.md @@ -0,0 +1,118 @@ +# Migration Checklist + +A site migration (domain change, platform change, URL restructure, HTTPS move) is the single highest-risk SEO event. Follow this checklist to avoid the typical 30 to 70 percent traffic loss most migrations cause. + +--- + +## Pre-migration (T minus 30 days) + +### Document the current state +- [ ] Crawl the entire current site, save URL list +- [ ] Export top 1000 organic landing pages from search console (last 12 months) +- [ ] Export top 1000 organic queries from search console +- [ ] Note current rankings for the top 50 commercial queries +- [ ] Save current XML sitemap +- [ ] Save current robots.txt +- [ ] Document current schema implementation +- [ ] Screenshot current SERP appearance for top 10 queries + +### Plan the new structure +- [ ] Map every old URL to its new URL (redirect map) +- [ ] Confirm every important URL has a destination (no orphan redirects) +- [ ] Decide on canonical URL structure (trailing slash, www vs non-www, http to https) +- [ ] Plan handling of parameter URLs (UTM, sort, filter) +- [ ] Plan handling of pagination +- [ ] Plan internal linking structure (avoid relying on redirects) + +### Build and stage +- [ ] Set staging environment to `noindex` +- [ ] Block staging from search engines via robots.txt and HTTP auth +- [ ] Build redirect logic for the redirect map +- [ ] Implement the new sitemap +- [ ] Implement schema on all page types +- [ ] Verify Core Web Vitals on staging +- [ ] Test mobile usability on staging +- [ ] Test HTTPS configuration (HSTS, no mixed content) + +--- + +## Migration day + +### Just before cutover +- [ ] Final crawl of the production site (baseline for comparison) +- [ ] Final export of indexed URL list from search console +- [ ] Confirm DNS TTLs lowered if changing hosts (24 to 48 hours prior) +- [ ] Backup the current site fully +- [ ] Communicate the migration window to stakeholders + +### During cutover +- [ ] Deploy the new site +- [ ] Confirm 301 redirects firing for old URLs (test 20 random samples) +- [ ] Remove `noindex` from new site +- [ ] Update robots.txt on new site (allow crawling) +- [ ] Submit new sitemap in search console +- [ ] Submit change of address (if domain changed) +- [ ] Update canonical references on the new site + +### Within 24 hours of cutover +- [ ] Crawl the new site, compare to baseline +- [ ] Spot-check 50 redirected URLs end-to-end +- [ ] Verify search console shows the new sitemap as processed +- [ ] Check for unexpected 4xx or 5xx errors in server logs +- [ ] Submit top 20 priority URLs for re-indexing + +--- + +## Post-migration (T plus 1 to 30 days) + +### Week 1 +- [ ] Daily check on indexed page count in search console +- [ ] Daily check on crawl errors +- [ ] Daily check on average position for top 50 queries +- [ ] Verify no traffic anomalies in analytics +- [ ] Fix any redirect loops or chains identified in logs + +### Week 2 to 4 +- [ ] Verify all old URLs redirecting to new URLs (full crawl) +- [ ] Verify no redirect chains (max one hop) +- [ ] Verify schema validates on key page types +- [ ] Check Core Web Vitals trend (any regressions vs pre-migration) +- [ ] Update external backlinks where feasible (highest-value links first) +- [ ] Check social media platforms display new URLs correctly + +### Month 2 +- [ ] Compare organic traffic to pre-migration baseline +- [ ] Compare keyword rankings to pre-migration baseline +- [ ] Note any pages that lost rankings, investigate +- [ ] Begin pruning redirect rules for URLs that no longer receive traffic (after 90 days minimum) + +--- + +## Common migration failures (and how to prevent each) + +\| Failure \| Prevention \| +\|---\|---\| +\| Old URLs returning 404 \| Comprehensive redirect map, tested before cutover \| +\| Redirect chains (2+ hops) \| Direct redirect old → new, never old → middle → new \| +\| Lost rankings on key pages \| Same content, same intent, same internal linking on new pages \| +\| Crawl waste from old parameters \| Clean URL structure, parameter handling rules \| +\| Mixed HTTPS and HTTP content \| Audit all asset URLs, force HTTPS via HSTS \| +\| Search console disconnect \| Verify both old and new properties, submit change of address \| +\| Sitemap mismatch \| New sitemap lists new canonical URLs only, no legacy URLs \| +\| Hreflang breaks (international sites) \| Map hreflang to new URLs, preserve language pair relationships \| + +--- + +## Recovery if traffic drops + +If organic traffic drops more than 20 percent within 14 days: + +1. Verify all critical URLs return 200 or 301 (no 404 or 500) +2. Verify search console is processing the new sitemap +3. Spot-check top 50 lost-traffic URLs for content parity (does the new page actually answer the same query?) +4. Check robots.txt and meta robots for accidental noindex +5. Check for hreflang errors if international +6. Submit affected URLs for re-indexing manually +7. Audit internal linking - are key pages still well-linked? + +Most migration drops recover within 60 to 90 days IF the redirect map is complete and the content is preserved. If not recovering by day 90, the issue is structural and needs deeper investigation. diff --git a/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md b/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md new file mode 100644 index 0000000..cd5c87b --- /dev/null +++ b/dist/pi/.agents/skills/seo-traffic-diagnosis/SKILL.md @@ -0,0 +1,180 @@ +--- +name: seo-traffic-diagnosis +description: "Diagnose organic traffic changes (drops, stalls, or unexpected wins) using Ahrefs MCP plus Search Console data. Use this skill when traffic suddenly dropped, has been flat despite investment, after an algorithm update, after a migration or deploy, or when a competitor seems to be taking share. Triggers on traffic dropped, traffic decline, traffic stalled, organic decline, lost rankings, why is traffic down, algorithm update, post-migration traffic loss, traffic diagnosis. Also triggers when stakeholders are panicking about analytics." +category: seo-audit-suite +catalog_summary: "Diagnose drops, stalls, or wins via 5-layer root cause analysis" +display_order: 5 +--- + +# SEO Traffic Diagnosis + +Diagnose why organic traffic moved (down, flat, or unexpectedly up) using Ahrefs MCP combined with Search Console and analytics data. Stack-agnostic. Produces a root-cause diagnosis and an action plan. + +--- + +## When to use + +- Organic traffic dropped sharply +- Organic traffic has been flat for months despite content investment +- After a known Google algorithm update +- After a migration, replatform, or domain change +- After a deploy that touched routing, redirects, or rendering +- When a competitor is visibly taking organic share +- When a single page dropped from a ranked position +- When stakeholders need an explanation, fast + +## When NOT to use + +- Routine performance reporting (use `analytics-strategy`) +- Pre-emptive content planning (use `seo-content-gap-audit`) +- Backlink-only investigations (use `seo-backlink-audit`) +- Technical issue triage outside of traffic concerns (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Description of the symptom (what changed, when, magnitude) +- Date the change started (best estimate) +- Recent SEO history: deploys, migrations, content changes, link campaigns +- Access to Ahrefs MCP, Search Console, and analytics +- Confirmation the change is real (not a tracking artifact) + +--- + +## The framework: 5 layers of diagnosis + +A traffic change has one or more root causes. Move through the layers in order. Stop when you have enough evidence. + +### Layer 1: Confirm the change is real + +Before diagnosing, rule out: + +- Tracking gaps (analytics outages, tag manager issues) +- Bot traffic changes +- Reporting comparison errors (different date ranges, wrong segment) +- Seasonality (compare year-over-year, not just month-over-month) +- Holiday or weekday effects + +Cross-check Search Console clicks against analytics organic sessions. Significant divergence often points to a tracking issue, not a real traffic change. + +### Layer 2: Localize the change + +Where is the change happening? + +Segment by: + +- Country and language +- Device (mobile, desktop, tablet) +- Page or section (homepage, blog, product, category) +- Query type (branded vs non-branded) +- Landing page + +A change in one segment requires different diagnosis than a change everywhere. + +\| Pattern \| Likely cause \| +\| --- \| --- \| +\| One country dropped \| Local algorithm update, hreflang issue, geo redirect issue \| +\| Mobile dropped, desktop flat \| Mobile usability or page speed regression \| +\| One section dropped \| Topical algorithm update or section-specific quality issue \| +\| Branded queries dropped \| Brand-level issue: site outage, reputation, manual action \| +\| Non-branded dropped \| Algorithmic ranking issue \| +\| Single page dropped \| Page-level issue: content, technical, or competitive \| +\| Sitewide dropped \| Sitewide issue: penalty, technical, migration, or algorithm \| + +### Layer 3: Page-level analysis + +For affected pages, audit: + +- Position changes per ranked keyword (Ahrefs Rank Tracker history) +- SERP composition changes (more ads, AI overviews, featured snippets, video) +- Click-through rate changes +- Index status (Search Console coverage) +- Crawl errors and accessibility +- Recent content changes +- Internal link changes +- Backlink changes (lost links, redirect chains) + +A page can lose traffic without losing rank if SERP composition changed. + +### Layer 4: Technical analysis + +Did anything break technically? + +Check: + +- Robots.txt changes +- Canonical tag changes +- Meta robots changes (accidental noindex) +- Redirect chains and loops +- Render issues (especially for JS-heavy frameworks) +- Site speed regressions +- Hreflang errors +- Sitemap freshness +- HTTP status codes (4xx, 5xx spikes) +- Server log evidence of crawl behavior changes + +Recent deploys are the prime suspect. Compare deploy dates to traffic change dates. + +### Layer 5: External analysis + +If layers 1-4 do not explain the change, look outward. + +- Algorithm update calendar (cross-reference timing) +- Competitor moves (new content, new SERP features they captured) +- Industry trend (declining search demand for the topic) +- Manual action (Search Console security and manual actions) +- Negative SEO (sudden link velocity changes) + +External-factor diagnosis benefits from competitive context: did your traffic drop while competitors held steady (suggests an algorithm-specific issue), or did the entire vertical lose ground (suggests a user-behavior shift)? Similarweb shows competitor traffic trends; Ahrefs shows competitor SERP movement; pairing both surfaces whether the issue is yours alone or the category's. + +--- + +## Workflow + +1. Confirm the symptom. Get exact dates, magnitude, segment if known. +2. Validate the data. Layer 1 checks. Rule out tracking and seasonality. +3. Localize. Layer 2. Segment until the pattern is clear. +4. Page-level dive. Layer 3 on the most affected pages. +5. Technical check. Layer 4. Recent deploys, robots, canonicals, redirects. +6. External check. Layer 5. Algorithm updates, competitors, industry. +7. Build the hypothesis. State the cause as a single sentence. +8. Validate the hypothesis. Find the evidence that confirms or refutes it. See [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md). +9. Action plan. Specific fixes mapped to specific evidence. +10. Communicate. Write up the diagnosis. Stakeholders want clarity, not exhaustive analysis. + +--- + +## Failure patterns + +- Jumping to algorithm update. "It must be the algorithm" is the lazy answer. Eliminate technical and page-level causes first. +- Solving the wrong problem. A drop diagnosed as "content quality" when the real cause was an accidental noindex on a deploy. Validate the hypothesis before fixing. +- No baseline for "normal." Without a baseline, every fluctuation looks alarming. Establish what normal noise looks like before reacting. +- Treating one page as the site. Site-wide and page-level diagnoses are different. Confirm scope first. +- Ignoring branded vs non-branded. A drop in branded queries means a brand-level problem. A drop in non-branded means an SEO problem. Different teams own them. +- Comparing wrong date ranges. Comparing 28 days to the previous 28 days during a holiday distorts the picture. Use year-over-year for seasonal businesses. +- Stopping at correlation. A deploy and a drop on the same day is a strong correlation, not proof. Find the mechanism. +- Single-source diagnosis. Ahrefs sees position. Search Console sees clicks and queries. Analytics sees behavior. Logs see crawl. Use them together. +- Premature reassurance. Telling stakeholders "it is just an algorithm update, will recover" without evidence sets up a worse conversation later. + +--- + +## Output format + +A diagnosis document with: + +1. Summary. What changed, when, magnitude, root cause in one paragraph. +2. The symptom. Charts and segment breakdowns. +3. Layer-by-layer findings. What each layer ruled in or out. +4. Root cause hypothesis. Single statement with evidence. +5. Action plan. Ordered fixes with owners and timelines. +6. Recovery forecast. Realistic expectations on timeline and ceiling. +7. Monitoring plan. What to watch for confirmation of recovery. + +Length: 4-10 pages. Stakeholders read this fast. + +--- + +## Reference files + +- [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md) - Layer-by-layer diagnostic checklist with the specific data to pull at each layer and how to interpret each signal. diff --git a/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md b/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md new file mode 100644 index 0000000..2895ed3 --- /dev/null +++ b/dist/pi/.agents/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md @@ -0,0 +1,209 @@ +# Diagnosis checklist + +A layer-by-layer checklist for diagnosing organic traffic changes. Use it after the symptom is confirmed real and you need to narrow root cause. + +--- + +## Layer 1: Confirm the change is real + +### Pulls + +- Search Console clicks and impressions (last 90 days, day-by-day) +- Analytics organic sessions (matching window) +- Year-over-year same-period comparison +- Bot or crawler traffic if filterable + +### Checks + +- [ ] Date range comparison is apples to apples +- [ ] No tracking outage in analytics during the window +- [ ] No tag manager deploys during the window +- [ ] Search Console clicks and analytics organic sessions move together (within 10-20%) +- [ ] Year-over-year shows the same pattern (rules out seasonality) +- [ ] No major holiday or industry event explains the change + +If clicks and sessions diverge significantly: the issue may be tracking, not traffic. +If year-over-year shows the same pattern: the change is seasonal, not anomalous. + +--- + +## Layer 2: Localize the change + +### Pulls + +- Search Console: clicks segmented by country, device, query type, page +- Analytics: organic sessions segmented by landing page, country, device + +### Checks for each segment + +- [ ] One country dropped, others stable: local algorithm or geo issue +- [ ] One device dropped, others stable: device-specific issue +- [ ] One section dropped, others stable: section-specific quality or technical issue +- [ ] Branded queries dropped: brand-level issue +- [ ] Non-branded dropped: SEO ranking issue +- [ ] Single page dropped: page-level issue +- [ ] Everything dropped: sitewide issue + +### Decision + +Pick the dominant pattern. Carry the most affected segment into Layer 3. + +--- + +## Layer 3: Page-level analysis + +For each affected page or page cluster: + +### Pulls + +- Ahrefs: ranked keywords with current and historical positions +- Ahrefs: SERP overview for top 5-10 ranked keywords (current and from before the drop) +- Search Console: queries, impressions, clicks, position, CTR for each affected page +- Analytics: landing page sessions, conversion rate, bounce rate +- Index status in Search Console +- Recent edits to the page (CMS history) +- Internal links pointing to the page (Ahrefs Site Explorer) +- Backlinks to the page (Ahrefs) + +### Checks + +- [ ] Did position drop, or did position stay flat with CTR drop? +- [ ] Did the SERP composition change (new AI overviews, featured snippet steal, more ads, more video)? +- [ ] Are click-through rates lower than benchmarks for the position? +- [ ] Has the page been recently edited (intentionally or accidentally)? +- [ ] Has the page lost backlinks? +- [ ] Have internal links to the page decreased? +- [ ] Is the page indexed? + +### Interpretation + +\| Pattern \| Cause \| +\| --- \| --- \| +\| Position fell, SERP same \| Quality, freshness, or competitor improved \| +\| Position stable, CTR fell \| SERP feature change (snippet, AI overview, ads) \| +\| Position fell, SERP added new strong domain \| Competitor took share \| +\| Position fell after a CMS edit \| Recent edit broke something \| +\| Page deindexed \| Technical issue (robots, canonical, noindex) \| +\| Backlinks fell \| Link-based ranking signal decline \| +\| Internal links fell \| Internal link equity dilution \| + +--- + +## Layer 4: Technical analysis + +### Pulls + +- Robots.txt (current and historical via web archive if needed) +- Canonical tag check on affected pages +- Meta robots tag check on affected pages +- Redirect map for any URL changes +- HTTP status codes for affected URLs +- Sitemap freshness +- Hreflang implementation (multilingual sites) +- Server logs (Googlebot crawl behavior) +- Recent deploy log +- Recent infrastructure changes (CDN, DNS, hosting) + +### Checks + +- [ ] Robots.txt has not blocked anything new +- [ ] No accidental `noindex` on affected pages +- [ ] No accidental canonical to a different URL +- [ ] Redirects resolve in 1 hop with 301 status +- [ ] No 4xx or 5xx spikes for affected URLs +- [ ] Sitemap includes affected URLs and is current +- [ ] Hreflang is reciprocal and points to live URLs (multilingual) +- [ ] Googlebot is crawling at normal rates +- [ ] No deploy date matches the traffic drop date + +### Common technical regressions + +\| Symptom \| Likely cause \| +\| --- \| --- \| +\| Sudden full-site drop after a deploy \| Robots.txt blocked everything, accidental sitewide noindex, or routing broke \| +\| Pages return 404 or 410 \| URL structure changed, redirects missing \| +\| Pages return 5xx \| Server or hosting issue, possible CDN misconfiguration \| +\| Render mismatch \| JS rendering broke for crawlers (especially with framework upgrades) \| +\| Hreflang broken \| Cross-country traffic falls but other markets shift \| +\| Mass canonical change \| Pages canonicalized to wrong URLs after redesign \| + +--- + +## Layer 5: External analysis + +### Pulls + +- Algorithm update calendar (cross-reference traffic change date) +- Ahrefs SERP overview for affected keywords (looking for new ranking domains) +- Ahrefs competitor traffic estimates (their gain may be your loss) +- Search Console security and manual actions +- Backlink velocity changes (sudden gains or losses) +- News or industry trend search interest + +### Checks + +- [ ] No manual action notice in Search Console +- [ ] Drop date does not align with a known algorithm update +- [ ] No competitor has visibly taken share on affected keywords +- [ ] Industry-wide search demand for the topic has not shifted +- [ ] No spike in suspicious backlinks (negative SEO signal) +- [ ] No negative news or PR event affecting the brand + +### If layers 1-4 are clean + +- Drop on a known update date is likely algorithmic. Audit content quality and E-E-A-T signals. Recovery often takes the next update cycle. +- Drop with new dominant SERP domain is likely a competitive shift. Audit their content and update yours. +- Drop with industry-wide demand decline is not your fault. Manage stakeholder expectations. + +--- + +## Hypothesis statement template + +After working through the layers, state the hypothesis as a single sentence: + +``` +[Property] lost [magnitude] organic traffic starting [date] +because [root cause], +evidenced by [specific data points], +and recovery requires [specific actions] +with an expected timeline of [duration]. +``` + +Examples: + +> Site organic clicks dropped 35% starting March 12 because a deploy on March 11 added an accidental `noindex` meta tag sitewide, evidenced by Search Console coverage going from 2,400 indexed pages to 180 in 14 days, and recovery requires removing the noindex tag and resubmitting the sitemap with an expected timeline of 4-8 weeks. + +> Blog section organic clicks dropped 22% starting August 8 because Google rolled out a core update on that date that emphasizes E-E-A-T signals our author bylines lacked, evidenced by position drops on informational queries while transactional queries held, and recovery requires adding author E-E-A-T signals and improving content depth with an expected timeline of 1-2 update cycles (3-6 months). + +--- + +## When the diagnosis is unclear + +Sometimes the data points in multiple directions. In that case: + +1. State the top 2 hypotheses with evidence for each. +2. Recommend the lowest-risk action that helps in either case. +3. Identify the data that would distinguish the hypotheses. +4. Propose a monitoring plan to gather that data. + +Avoid forcing a clean conclusion when the evidence does not support one. Stakeholders prefer honest uncertainty to confident-but-wrong. + +--- + +## Communication template + +When delivering the diagnosis to stakeholders: + +``` +What happened: [1 sentence] + +Why it happened: [1 sentence] + +What we are doing: [3-5 specific actions] + +When to expect recovery: [timeline with confidence level] + +What to watch for: [leading indicators of recovery or further decline] +``` + +Stakeholders rarely want the layer-by-layer detail. They want clarity, accountability, and timeline. Keep the full diagnosis as an appendix. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md b/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md new file mode 100644 index 0000000..7683255 --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/SKILL.md @@ -0,0 +1,261 @@ +--- +name: skill-creation-walkthrough +description: Step-by-step guide for creating your own Claude Skills, from deciding whether a skill is the right tool to writing the SKILL.md file, structuring reference material, and making it trigger reliably. Use when you want to package a workflow, framework, or repeated task into a reusable Skill, when an existing skill is not triggering or not loading the right context, when you are auditing a skill that is underperforming, or when you want to publish a skill for others. Also triggers when someone asks "how do I make a skill" or "what makes a good skill". Useful for individuals, teams, and anyone publishing skills publicly. +category: process-and-team +catalog_summary: "The meta-skill: how to write your own custom skills" +display_order: 5 +--- + +A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate. + +## When to use + +- You catch yourself writing the same prompt or instructions repeatedly. +- You want to package a workflow or framework for reuse. +- An existing skill of yours is not triggering when it should. +- You are publishing skills for others to use. +- You want to teach Claude a domain-specific way of working. +- You are reviewing a skill someone wrote and need a quality bar. + +## When NOT to use + +- For one-off prompts (just write the prompt). +- For information that should live in system context, not progressive disclosure. +- For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills). +- For replacing tool calls (skills are instructions, not tools). + +## Required inputs + +- The task or workflow you want to encode. +- The audience: who will trigger this skill, in what kind of conversation. +- Existing artifacts: prompts you have used, docs you have written, examples of good output. + +## The framework: how skills work + +A Skill is a folder with a `SKILL.md` file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed. + +The key property: progressive disclosure. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context. + +What this means for you: + +- The description is everything for triggering. Get it right or the skill never loads. +- The SKILL.md body is for the workflow itself. +- The references are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material. + +## Workflow + +### Phase 1: Decide if a skill is the right shape + +Not everything should be a skill. Run this test: + +\| Sign it should be a skill \| Sign it should not be \| +\| --- \| --- \| +\| You repeat the same workflow 5+ times. \| You used it once. \| +\| The output benefits from a consistent structure. \| Each output is bespoke. \| +\| The task has a clear trigger (a question shape, a file type, a domain). \| The task is part of every conversation already. \| +\| The instructions exceed 200 words. \| A one-line system instruction would do. \| +\| Templates or reference material would help. \| Pure prose is enough. \| +\| Other people might benefit from the same workflow. \| Only relevant to your single project. \| + +If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction. + +### Phase 2: Define the trigger + +Before writing anything, ask: when should this skill load? + +Be concrete. Write down the exact phrases or situations that should trigger it. Examples: + +- "When the user asks for a creative brief, kickoff doc, or project brief." +- "When the user uploads a CSV and wants tabular analysis." +- "When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related." +- "When the user mentions they want to pick a vendor or compare tools." + +The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably. + +### Phase 3: Write the description + +This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill. + +Good descriptions have 4 parts: + +1. What it does (one sentence, action-oriented). +2. When to use it (the trigger phrases or situations). +3. Edge cases with "Also triggers when..." (catches less obvious situations). +4. Useful for... (audience or use cases, helps disambiguation). + +Bad description: + +> "Helps with SEO." + +Why it fails: vague, no trigger phrases, will not fire when the user actually needs it. + +Good description: + +> "Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits." + +Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity. + +### Phase 4: Structure the SKILL.md body + +A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills: + +``` +--- +name: [your-skill-name] +description: [your description] +--- + +[One-sentence purpose statement] + +## When to use +[Bulleted list of trigger situations] + +## When NOT to use +[Bulleted list, ideally redirecting to sibling skills] + +## Required inputs +[What Claude needs from the user to run this skill] + +## The framework +[The durable IP: the model, the steps, the dimensions, the layers] + +## Workflow +[Numbered steps Claude follows] + +## Failure patterns +[Common mistakes to avoid or push back on] + +## Output format +[What the deliverable looks like] + +## Reference files +[List of files in the references/ folder with descriptions] +``` + +Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed. + +### Phase 5: Add references for what does not belong in SKILL.md + +References are the second tier of progressive disclosure. They load when Claude reads them, not by default. + +Use references for: + +- Long checklists (a 100-item audit checklist). +- Templates with worked examples. +- Detailed playbooks for specific scenarios. +- Reference material like spec links, glossaries, decision tables. +- Anything over 100 lines that not every invocation needs. + +Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides. + +Naming patterns that work: + +- `references/[noun]-template.md` for templates. +- `references/[noun]-checklist.md` for checklists. +- `references/[noun]-playbook.md` for end-to-end runbooks. +- `references/example-[scenario].md` for worked examples. + +Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each. + +### Phase 6: Test and iterate + +Skills do not work the first time. Plan to iterate. + +Testing checklist: + +- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong. +- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire? +- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad. +- [ ] Output test: run the skill on a real task. Is the output what you expected? +- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim. + +After testing, common fixes: + +- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..." +- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience. +- Output is generic → add a clearer framework or workflow with more specifics. +- Reference is overwhelming → split into multiple references, keep each focused. + +## Deep dive: description anatomy + +The description is hard to get right. Here is the formula in detail. + +### Sentence 1: What it does + +Lead with the verb. Be specific. + +- Good: "Audit on-page SEO." +- Bad: "Help with SEO things." + +### Sentence 2: When to use it + +State the primary triggers. Use phrases users would actually say. + +- Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'." +- Bad: "Use for SEO improvements." + +### Sentence 3: "Also triggers when..." + +Catch the secondary triggers and edge cases. + +- Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup." +- Bad: (omitted) + +### Sentence 4: Useful for... + +Explain audience or scope to help with disambiguation. + +- Good: "Useful for both individual page reviews and small-batch audits." +- Bad: (omitted) + +If your skill description is one sentence, it is probably not specific enough. + +## Deep dive: worked example + +Imagine you keep writing technical post-mortem documents and want to skill-ify it. + +Step 1: Decide it's a skill. You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill. + +Step 2: Trigger. "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong." + +Step 3: Description. + +> "Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews." + +Step 4: SKILL.md body. Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up). + +Step 5: References. A `post-mortem-template.md` with the document structure and a `facilitator-checklist.md` for running the post-mortem meeting. + +Step 6: Test. Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro). + +You iterate until the triggers fire correctly, then ship. + +## Failure patterns + +- Description too narrow. The skill never fires because your description requires exact phrases the user does not say. +- Description too broad. The skill fires constantly, including for unrelated tasks. +- No trigger phrases. The description describes what the skill does but not when to load it. Triggering is unreliable. +- SKILL.md too long. A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references. +- References that duplicate SKILL.md. If a reference repeats what the body says, prune one. +- No "When NOT to use". Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly. +- No examples. A framework without a worked example is hard to apply. Include at least one in the reference material. +- Optimizing for one example. A skill written around your single use case fails at adjacent ones. Generalize. +- No iteration. Shipping a skill once and never revisiting it. Skills decay. Audit yearly. +- Branding or product-specific assumptions in a public skill. Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md) for the full discipline and the user-outcome reasons it matters. + +## Output format + +When using this skill to create another skill, deliver: + +1. Trigger analysis: a short list of phrases and situations that should fire the skill. +2. Description draft: the 2-4 sentence description for the YAML frontmatter. +3. SKILL.md body: the full body of the skill, following the standard structure. +4. Reference plan: a list of reference files to create with one-line descriptions. +5. First reference file: at least one reference written end to end as a starting point. +6. Test plan: 3-5 test prompts that should trigger the skill, plus 2-3 that should not. + +## Reference files + +- [`references/skill-template.md`](references/skill-template.md): A blank SKILL.md template with annotated section guidance, ready to copy and fill in. +- [`references/description-cookbook.md`](references/description-cookbook.md): A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs). +- [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md): What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md new file mode 100644 index 0000000..ff3ba60 --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/description-cookbook.md @@ -0,0 +1,214 @@ +# Description cookbook + +The skill description is the single most important sentence (or paragraph) in your skill. It is what Claude sees in the system prompt to decide whether to load the rest of the skill. If the description is wrong, the skill never fires when it should, or fires when it should not. + +This cookbook gives you description patterns for common skill types, each with a worked example. + +## The 4-part formula + +A reliable description has 4 parts: + +1. Action: what the skill does (verb-led, specific). +2. Primary triggers: when to use it (the obvious cases). +3. Edge cases: secondary triggers introduced with "Also triggers when...". +4. Audience or scope: who this serves, introduced with "Useful for...". + +Not every skill needs all four parts. Most benefit from at least three. + +## Pattern 1: The audit skill + +For skills that evaluate something against a rubric. + +### Template + +``` +[Verb] [the thing] for [purpose]. Use when the user asks for [a concrete request], wants to [common task], or asks "[likely user phrasing]". Also triggers when the user mentions [related concepts] or shares [input that implies the audit]. Useful for [scope: one-off vs ongoing, individual vs batch]. +``` + +### Worked example + +``` +Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks "why is this page not ranking". Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits. +``` + +Why this works: + +- "Audit" is a clear verb. +- The "on a single URL or a small set of pages" sets scope, which prevents this from competing with bulk audit skills. +- Three primary triggers in different phrasings. +- "Also triggers when..." catches secondary signals. +- "Useful for..." narrows the use case. + +## Pattern 2: The template or generator skill + +For skills that produce a structured artifact. + +### Template + +``` +Generate [the artifact] following [methodology or structure]. Use when the user asks to write [artifact name], needs [related deliverable], or describes [the work this artifact captures]. Also triggers when the user has [precondition] and is preparing to [downstream action]. Useful for [audience or use case]. +``` + +### Worked example + +``` +Generate a creative brief that aligns stakeholders before a project starts. Use when the user asks to write a brief, kickoff doc, or project brief, or describes a project that has a goal but no shared context document. Also triggers when the user is starting design or development work without an agreed scope. Useful for individual project briefs and recurring brief templates. +``` + +Why this works: + +- "Generate" is the verb. +- "That aligns stakeholders before a project starts" tells Claude the context. +- Multiple ways the user might phrase the request. +- The "also triggers" catches the upstream signal (no shared context yet). + +## Pattern 3: The framework or methodology skill + +For skills that teach or apply a way of thinking. + +### Template + +``` +Apply [framework name or shape] to [the problem]. Use when the user is [the situation], asks "[likely question]", or needs to think through [the kind of decision]. Also triggers when [secondary condition]. Useful for [scope]. +``` + +### Worked example + +``` +Apply the Diataxis framework to documentation problems: separate tutorials, how-to guides, references, and explanations. Use when the user is reorganizing docs, asks "where should I put this", or has docs that try to do too much at once. Also triggers when the user is starting a fresh docs site and needs a content structure. Useful for both internal and external documentation. +``` + +Why this works: + +- Names the framework explicitly. +- Concrete trigger phrases. +- "Has docs that try to do too much at once" is a specific symptom that maps to this framework. + +## Pattern 4: The walkthrough or playbook skill + +For skills that take the user through a multi-step process. + +### Template + +``` +Walk through [the process] step by step. Use when the user is [the situation], asks how to [the goal], or needs a structured approach to [complex task]. Also triggers when [edge case]. Useful for [first-time vs repeat use, individuals vs teams]. +``` + +### Worked example + +``` +Walk through a domain migration step by step, including DNS, redirects, content mapping, and post-launch validation. Use when the user is moving content between platforms, changing domains, or restructuring URLs at scale. Also triggers when the user mentions hreflang updates, sitemap regeneration, or 301 redirect maps. Useful for both small migrations (a few hundred URLs) and large ones (tens of thousands). +``` + +Why this works: + +- "Step by step" sets expectation. +- Names the components ("DNS, redirects, content mapping, and post-launch validation") so users with one of these in mind still trigger correctly. +- Scale guidance in "useful for" helps with disambiguation. + +## Pattern 5: The decision or evaluation skill + +For skills that help the user pick between options. + +### Template + +``` +Compare [option type] and recommend [outcome]. Use when the user is choosing between [options], asks "[option A] vs [option B]", or needs to decide [the question]. Also triggers when [renewal/replacement/scaling situation]. Useful for [scope]. +``` + +### Worked example + +``` +Compare vendors and recommend a pick for a specific job. Use when the user is choosing between SaaS tools, asks "X vs Y", or needs to evaluate options before signing a contract. Also triggers when an existing vendor is up for renewal or being replaced. Useful for both small SaaS decisions and large infrastructure choices. +``` + +Why this works: + +- "Compare and recommend" frames the action. +- Multiple trigger phrasings. +- "Also triggers when..." catches the renewal/replacement situation that often forces a decision. + +## Pattern 6: The diagnostic or troubleshooting skill + +For skills that help find what is wrong. + +### Template + +``` +Diagnose [the problem class] and propose fixes. Use when the user reports [symptom], asks "why is [thing] [bad state]", or shares [evidence of the problem]. Also triggers when [related signal]. Useful for [scope of diagnosis]. +``` + +### Worked example + +``` +Diagnose slow page performance and propose specific fixes. Use when the user reports slow load times, asks "why is my site slow", or shares a Core Web Vitals report. Also triggers when the user mentions Lighthouse scores, LCP, INP, or CLS issues. Useful for both individual page diagnosis and site-wide performance reviews. +``` + +Why this works: + +- "Diagnose and propose fixes" is the action. +- Catches the user's likely phrasing ("why is my site slow"). +- Catches technical phrasings (Core Web Vitals report, Lighthouse, specific metric names). + +## Pattern 7: The strategy or planning skill + +For skills that produce a plan or strategy. + +### Template + +``` +Design [the plan or strategy] for [outcome]. Use when the user is [the situation], asks for a [plan / strategy / roadmap], or needs to align [stakeholders or work] around [the goal]. Also triggers when [precondition or constraint]. Useful for [scope]. +``` + +### Worked example + +``` +Design a content strategy that supports a specific business goal. Use when the user is starting a content program, asks for an editorial plan, or needs to align content production with marketing or SEO objectives. Also triggers when the user mentions topical authority, content calendar, or pillar pages. Useful for both new programs and reboots of stalled ones. +``` + +Why this works: + +- "Design a content strategy that supports a specific business goal" sets the action and the constraint. +- Catches both fresh starts and reboots in "useful for". + +## Anti-patterns: descriptions that fail + +### "Helps with X" + +Too vague. No triggers. Will fire constantly or never. + +### "When the user wants help with technical SEO and on-page SEO and off-page SEO" + +Too broad. Should be split into multiple skills or narrowed. + +### "Use when the user mentions XYZ" + +Too narrow. Real users will not always use the exact phrase. + +### "Comprehensive guide to [topic]" + +Marketing copy, not a trigger. Does not tell Claude when to load. + +### "[no description, just a name]" + +The skill never loads except by accident. + +## How to test a description + +Before publishing: + +1. Write down 5 prompts that should trigger the skill. +2. Write down 3 prompts that should not. +3. In a fresh conversation with the skill installed, try each prompt. +4. Check whether the skill loaded. +5. Adjust the description until trigger and non-trigger prompts behave correctly. + +If a should-trigger prompt does not fire, broaden the description: add the phrasing the user used, add an "also triggers" clause. + +If a should-not-trigger prompt fires, narrow the description: add scope boundaries, name the sibling skill the user actually wants, or add a "Do not trigger when..." clause if needed (most skill descriptions do not need this, but it is available). + +## Final tip: match the user's vocabulary + +Users do not say "perform an SEO audit". They say "can you check my page" or "is my site optimized". Your description should anticipate the user's vocabulary, not yours. + +If your description is full of expert jargon and the user is a beginner, the skill will not fire. Use the words your audience actually says. Use jargon as a backup, not the lead. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md new file mode 100644 index 0000000..55c6f4f --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md @@ -0,0 +1,96 @@ +# Methodology vs implementation + +What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. + +A public skill is methodology, not implementation. Skills teach the framework, the decision criteria, the taxonomies, the anti-patterns. They do not teach the specific page architecture, type definitions, image generation script structure, or stack-specific patterns that any one team uses to ship polished delivery. + +This is not gatekeeping. It is user-aligned. Methodology produces work that is distinctive to each team's stack and judgment. Cookie-cutter implementation produces homogenized output that looks identical across users. Stack-agnosticism makes the catalog actually portable. Implementation specificity makes it useless to teams on different stacks. + +--- + +## What belongs in a public skill (methodology layer) + +- Conceptual frameworks (architectures, registers, taxonomies, classifications) +- Decision criteria (when to choose X versus Y, with the tradeoffs surfaced) +- Anti-patterns and common failure modes +- The shape of artifacts the skill produces, described in generic terms (a markdown brief with these sections; a JSON object with these fields; a design spec with these decisions documented), not as type signatures bound to a specific framework +- Voice and style guidance for the work +- Workflow descriptions at the methodology level (the sequence of decisions and handoffs, not the platform commands) +- General principles applicable across stacks +- Worked examples with fictional or anonymized actors that demonstrate the framework concretely without prescribing a specific tooling stack + +The 12-consideration framework pattern (or 5-pillar, 4-axis, etc.) lives here. Frameworks are durable; they survive stack migrations and team transitions because they teach judgment, not code. + +--- + +## What does not belong in a public skill (implementation layer) + +- Specific Next.js, React, Vue, Svelte, or other framework-specific page architectures +- TypeScript or other type definitions optimized for a specific application's data shapes +- Component patterns with stack-specific code (JSX, template syntax, framework directives) +- Image generation script structures matching a specific implementation +- Application-context CSS-rendered mockup component code +- Theme integration patterns tied to specific design tokens (brand-color names, spacing scales, font tokens that exist only in one team's design system) +- Tailwind class strings or other utility-CSS specifics that prescribe one stack's idioms +- Schema markup component shapes that match one team's component library +- Vercel, Netlify, or specific deployment patterns + +If a section of a skill cannot be applied by a reader on a different stack, it does not belong in the public skill. It belongs in an internal playbook, a productized client deliverable, or a stack-specific reference implementation maintained separately. + +--- + +## Why the line matters + +Three principles, each user-outcome framed. + +### 1. Methodology produces distinctive work + +A skill that teaches "five logo architectures" leaves the user to choose, design, and execute the architecture that fits their brand. A skill that teaches "render this Next.js component with these Tailwind classes" produces work that looks identical across every user who runs the skill. Cookie-cutter implementation homogenizes; methodology requires the user to engage with why, which produces work distinctive to each team's context. + +The user outcome that matters: did the skill help the user produce work that is theirs, or did it produce work that signals "I ran a skill"? + +### 2. Stack-agnosticism is real value + +A skill that mandates a specific Next.js component is useless to teams on Astro, vanilla HTML, Figma-only workflows, WordPress, Shopify, or anywhere off the prescribed stack. Methodology applies across all of them. + +The catalog gets used by people writing in plain markdown, working in Notion, building on a static site generator, running in WordPress, or shipping in something that did not exist when the skill was written. Methodology survives all of those. Stack-coupled implementation does not. + +### 3. The catalog compounds because skills are durable + +Skills last across stack changes, framework migrations, and team transitions because they teach judgment, not code. A skill that hardcodes the framework du jour decays as the framework changes. A skill that teaches the framework-agnostic principle the framework was implementing keeps working when teams migrate to the next framework. + +Implementation-leaking skills decay as their implementations become outdated. Methodology-pure skills compound across years. + +--- + +## The audit pattern + +The catalog is audited periodically for methodology versus implementation drift. The first formal audit (May 2026) reviewed 18 flagship skills against the criteria in this reference and found zero implementation-leakage findings; the discipline had been held by instinct from the catalog's earliest skills onward. Future audits will land as the catalog grows past current size. + +Findings shape the discipline. Recently shipped skills tend to carry the discipline more cleanly than the earliest ones, which reflects the maturation any catalog goes through. The principle is not "perfection from day one"; it is "audit, learn, codify, hold the line going forward." + +--- + +## How to apply this when authoring new skills + +A short checklist for skill authors: + +1. Before writing, identify the methodology versus implementation boundary explicitly. What part of this skill teaches a framework that applies across stacks? What part teaches your specific stack's implementation? The framework part goes in the public skill; the implementation part stays internal. +2. When tempted to include specific code, ask: is this teaching the framework, or is this teaching my stack? If it teaches the framework using your stack as one illustration, keep it; if it teaches your stack using the framework as scaffolding, move it. +3. When referring to tooling, prefer general categories ("a feature flag platform," "a data warehouse," "a CMS with structured content models") over specific products. Name specific products when the category needs concretization, and name multiple alternatives so readers see the category rather than locking into one vendor. +4. Cross-references to specific tools or services should be sparse. Each cross-reference should earn its inclusion through methodology relevance, not marketing value. If a cross-reference exists primarily to drive traffic, it is not earning its keep in a methodology skill. +5. Run the audit checklist before merge. Any specific code? Any type signatures matching your application? Any framework-specific patterns? If yes, move to internal playbook. + +--- + +## What stays internal + +Implementation specifics live somewhere; they just do not live in the public skill. Common locations: + +- Internal playbooks in private repositories +- Internal documentation in team wikis or knowledge bases +- Productized client deliverables produced by combining methodology plus playbook plus judgment +- Stack-specific reference implementations maintained as separate properties +- Onboarding materials for team members joining the implementation work + +The principle: anyone reading the public skill should be able to produce quality methodology-driven work on their own stack. Teams that want polished productized delivery in a specific stack do that work themselves, build their own internal playbooks, or engage practitioners who specialize in that delivery. The public skill is the upstream input; the implementation is the downstream work, owned by whoever is doing it. diff --git a/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md b/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md new file mode 100644 index 0000000..eb5f92f --- /dev/null +++ b/dist/pi/.agents/skills/skill-creation-walkthrough/references/skill-template.md @@ -0,0 +1,153 @@ +# Skill template + +A blank SKILL.md template with annotated guidance. Copy this, fill it in, and you have a skill that fits the pattern. + +## How to use this template + +1. Copy the YAML and structure below into a new file at `your-skill-name/SKILL.md`. +2. Replace the placeholder text in `[brackets]`. +3. Delete sections you do not need (most skills do not need every section). +4. Read the annotations to understand what each section is doing. +5. Test the skill on a real task. Iterate. + +## The template + +``` +--- +name: [your-skill-name] +description: [2-4 sentences. What the skill does. When to use it. "Also triggers when..." for edge cases. "Useful for..." for audience clarity.] +--- + +[One-sentence purpose statement. What this skill exists to do.] + +## When to use + +- [Trigger situation 1] +- [Trigger situation 2] +- [Trigger situation 3] +- [Trigger situation 4] + +## When NOT to use + +- [Situation that looks similar but should use a different skill] +- [Situation that is out of scope for this skill] +- [Sibling skill cross-reference: "For X, use the [other-skill] skill."] + +## Required inputs + +- [Information Claude needs from the user before it can do good work] +- [Or context Claude needs to gather] +- [Or files, links, or examples needed] + +## The framework + +[The durable IP. The model, dimensions, layers, principles that make this skill different from a freeform response. This is where the skill earns its keep.] + +[Format options: numbered list of layers, table of dimensions, hierarchy of concepts. Pick what fits the content.] + +## Workflow + +1. [First step Claude takes] +2. [Second step] +3. [Third step] +4. [...] +5. [Final step or output] + +## Failure patterns + +- [Common mistake]: [Why it happens, how to avoid]. +- [Common mistake]: [Why it happens, how to avoid]. +- [Common mistake]: [Why it happens, how to avoid]. + +## Output format + +Deliverables from this skill: + +1. [Artifact 1]: [What it is]. +2. [Artifact 2]: [What it is]. +3. [Artifact 3]: [What it is]. + +[Optional: notes on format, length, or delivery mechanism.] + +## Reference files + +- `references/[name].md`: [One-line description of what is in this reference]. +- `references/[name].md`: [One-line description]. +``` + +## Annotations: what each section is for + +### YAML frontmatter + +The `name` should match the folder name and use lowercase hyphens. The `description` is the most important field in the entire skill. It is what Claude sees in the system prompt to decide whether to load the skill body. Be specific about triggers. + +### Purpose statement (one sentence) + +This is the elevator pitch. A reader should know what the skill does after this one sentence. If you cannot summarize it in a sentence, the skill may be doing too much. + +### When to use + +Be concrete. List the actual situations where the skill should fire. These map to the trigger phrases in the description but in more detail. + +### When NOT to use + +Just as important as "when to use". This is where you redirect to sibling skills and prevent overlap. Without this section, related skills compete and Claude makes ambiguous choices. + +### Required inputs + +What does Claude need before it can do good work with this skill? Sometimes this is information ("the URL to audit"). Sometimes it is context ("the user's audience"). Listing it explicitly helps Claude ask the right question if it is missing. + +### The framework + +This is the durable IP. The thing that makes your skill better than a generic LLM response on the topic. A model, a set of dimensions, a hierarchy, a checklist of layers. + +If you cannot articulate the framework, the skill may be more about output structure than methodology. That is fine. Skip this section. + +### Workflow + +The numbered steps Claude follows when running the skill. Should be repeatable across different invocations. If the steps differ wildly per use case, you may need multiple skills or a more abstract framework. + +### Failure patterns + +What goes wrong in practice. This section is what makes a skill feel earned. It signals "we have done this many times and these are the mistakes". Specific failure patterns are more useful than abstract ones. + +### Output format + +What the deliverable looks like. Not "good output" - actually structured and named. This is what Claude produces at the end. + +### Reference files + +The list of `references/` files with brief descriptions. Each reference should be standalone and useful even if read out of order. + +## Sizing guidance + +\| Component \| Target \| Hard limit \| +\| --- \| --- \| --- \| +\| Description \| 2-4 sentences \| 1 paragraph \| +\| SKILL.md total \| Under 250 lines \| 500 lines \| +\| Single reference file \| Under 400 lines \| 800 lines \| +\| Number of references \| 1-3 \| 5 \| + +If you are over the targets, split or trim. Skills get heavier and more brittle as they grow. + +## Naming conventions + +- Skill folder: `lowercase-hyphenated` +- SKILL.md: always exactly `SKILL.md` (case-sensitive) +- References: `references/[name].md` +- Templates: `[noun]-template.md` +- Checklists: `[noun]-checklist.md` +- Playbooks: `[noun]-playbook.md` +- Examples: `example-[scenario].md` + +## Common adaptations + +Not every skill needs the standard structure. Examples of valid adaptations: + +- Pure how-to skill: skip the "framework" section, lead with workflow. +- Pure template skill: skip framework and workflow, focus on the structure of the output. +- Audit skill: heavy on the framework (the dimensions to score), lighter on workflow. +- Walkthrough skill: numbered phases as the spine, no separate framework section. +- Decision skill: heavy on options and tradeoffs, lighter on workflow. + +The structure exists to make sure you cover the right ground. If a section does not earn its place, drop it. But know what you are dropping and why. diff --git a/dist/pi/.agents/skills/stakeholder-communication/SKILL.md b/dist/pi/.agents/skills/stakeholder-communication/SKILL.md new file mode 100644 index 0000000..f5a1950 --- /dev/null +++ b/dist/pi/.agents/skills/stakeholder-communication/SKILL.md @@ -0,0 +1,360 @@ +--- +name: stakeholder-communication +description: "Communicate effectively with stakeholders across functions and seniority levels. Use this skill when writing status updates, preparing executive reviews, sharing technical decisions with non-technical audiences, managing up, communicating bad news, or designing the communication cadence for a project. Triggers on stakeholder update, status report, executive summary, exec review, manage up, communicate bad news, project comms, status meeting, weekly update. Also triggers when a project is going off track and the team needs to communicate it." +category: process-and-team +catalog_summary: "Status updates, exec readouts, project communications" +display_order: 1 +--- + +# Stakeholder Communication + +Get the right information to the right people at the right time, in a form they can act on. Stack-agnostic. Applies to any team operating with cross-functional stakeholders. + +--- + +## When to use + +- Writing weekly or monthly status updates +- Preparing for an executive review or board update +- Sharing a technical decision with a non-technical audience +- Communicating a delay, miss, or quality problem +- Asking for help, resources, or decisions +- Managing up to a manager or sponsor +- Designing the communication cadence for a project +- Drafting an internal announcement + +## When NOT to use + +- Customer-facing communication (use marketing/support skills) +- Public comms or press (different framework, different stakes) +- Incident communication during an active incident (use `incident-response`) +- Internal documentation that isn't time-sensitive (use `documentation-strategy`) +- Specific delivery formats (slide deck design, email tone) - this skill is about content and structure + +--- + +## Required inputs + +- The audience (who specifically, what's their context, what do they care about) +- The purpose (inform, decide, escalate, ask, celebrate) +- The substance (what's actually happening) +- The medium (email, doc, meeting, slide, chat) +- Time constraints (when do they need this) + +--- + +## The framework: 5 questions + +Before any stakeholder communication, answer: + +### Question 1: Who is the audience? + +Specifically. "Leadership" is too vague. The CFO and the VP of Engineering have different concerns. + +For each named audience: +- What do they care about? (revenue, risk, quality, velocity, costs, customers) +- What do they already know? (background you can skip) +- What's their level of detail tolerance? (executives want headlines; ICs want details) +- What action do you want from them? (acknowledgment, decision, help, no action) + +### Question 2: What's the headline? + +If they read only one sentence, what should they take away? + +The headline goes first. Always. The narrative supports it; the data confirms it. + +This is the biggest gap in most stakeholder communication: people start with context and build to a conclusion. Stakeholders want the conclusion first. + +### Question 3: What's the so-what? + +Stakeholders ask "and?" implicitly. Answer it explicitly. + +- "We hit 80% of the milestone." → so what? +- "We hit 80% of the milestone, which puts the launch one week behind plan." → that's the so-what. + +The so-what makes the information actionable. + +### Question 4: What do you want? + +Communications generally have one of these requests: + +- Inform: no action needed. Just keeping them in the loop. +- Decide: a decision is needed; here are the options and recommendation. +- Escalate: something is stuck; we need help. +- Ask: a specific request (resource, introduction, review). +- Celebrate: a win to share; no action needed but morale matters. + +State which. Don't bury the request. + +### Question 5: What format? + +- Async written (doc, email): rich content, decision trail, easy to reference +- Sync written (chat, ticket comment): quick exchange, conversational +- Sync spoken (meeting, call): nuance, debate, alignment +- Mixed (doc + meeting): the doc is read in advance; meeting is decision + +For most updates: async written. Save sync time for actual discussion. + +--- + +## The structure: the inverted pyramid + +Stakeholder communication reads like a news article, not an essay. + +``` +Headline (one sentence) + +The "so what" and the request (one paragraph) + +Status / progress (the body) + +Risks and asks (what we need) + +Detail / appendix (what curious readers want) +``` + +Cut from the bottom. If your update gets shortened, the top survives. + +--- + +## Update templates + +### Weekly project update + +``` +Project: [Name] +Status: [On track / At risk / Off track] +Headline: [One-sentence summary] + +This week: +- [Specific accomplishment] +- [Specific accomplishment] +- [Specific accomplishment] + +Next week: +- [Specific plan] +- [Specific plan] + +Risks / blockers: +- [Risk + what we're doing about it / what we need] + +Metrics: +- [Metric: value vs target] +- [Metric: value vs target] +``` + +The status indicator (on track / at risk / off track) is essential. Stakeholders scan for it. + +### Executive review + +``` +Headline: [The summary, one sentence] + +Key points: +1. [Point with one supporting sentence] +2. [Point with one supporting sentence] +3. [Point with one supporting sentence] + +Decisions needed: +- [Decision A: options and recommendation] +- [Decision B: options and recommendation] + +Asks: +- [Specific request] + +Detail: [Linked doc or appendix] +``` + +Executives skim. They click into detail when interested. + +### Bad news + +The hardest update to write well. + +``` +Headline: [The bad news, plainly stated] + +What happened: +[Specific facts, no euphemisms] + +Impact: +[Who's affected, how much, by when] + +What we're doing: +[Specific actions and owners] + +What we need: +[Specific asks, if any] + +Timeline: +[When the next update will land] +``` + +Don't soften the headline. Soft headlines on bad news erode trust faster than the news itself. + +### Decision request + +``` +Decision: [What needs to be decided] + +Context: [The minimum needed to understand] + +Options: +1. [Option A: description, pros, cons] +2. [Option B: description, pros, cons] +3. [Option C: description, pros, cons] + +Recommendation: [Option X, because...] + +Need by: [Date] +Decision rights: [Who decides] +``` + +Recommendation matters. Not making one is putting the work back on the decider. + +--- + +## Tone and register + +### Across audiences + +\| Audience \| Tone \| Detail \| Length \| +\|---\|---\|---\|---\| +\| Direct manager \| Candid, briefer \| Mid \| Medium \| +\| Skip-level / VP \| Polished, sharper \| Low \| Short \| +\| Cross-functional peer \| Collaborative, specific \| Mid-high \| Medium \| +\| Executive / board \| Headlines, confident \| Low (with detail available) \| Short \| +\| Team / IC stakeholders \| Detailed, direct \| High \| Long \| + +### What to avoid + +- Hedging when confident. "I think maybe we might be able to..." Just say what you mean. +- Confidence when uncertain. "Definitely launching Friday" when there's risk. Calibrate. +- Jargon for non-technical audiences. Replace with plain language. +- Burying the lede. Headline first. +- Implicit asks. State explicitly what you want. +- Status updates that are 90% activity, 10% outcome. Focus on outcomes; activity is supporting evidence. + +--- + +## Workflow + +### Step 1: Define the audience and purpose + +Before writing, answer Q1-Q5 above. Often this clarifies the message before any drafting. + +### Step 2: Draft the headline + +One sentence. The takeaway. If you can't write the headline, you don't know yet what you're communicating. + +### Step 3: Write inverted pyramid + +Headline, so-what, body, asks, detail. + +### Step 4: Cut + +A first draft is usually 30-50% too long. + +- Cut activities that don't have outcomes +- Cut adjectives (great, awesome, excellent, exciting) +- Cut filler (just, really, very, actually) +- Cut hedging (kind of, sort of, somewhat) when confident +- Cut sentences that don't add information + +### Step 5: Verify the request + +Reread. Is the ask clear? Is it specific? Is the deadline named? + +### Step 6: Check the audience + +Imagine the recipient reading. Will they understand the headline? Have you skipped context they need? Have you given context they don't need? + +### Step 7: Send and follow up + +After sending: +- Did the right people see it? Acknowledge the right channel. +- Did they understand? Watch for confused replies; address them. +- Did they act? Follow up on stale asks. + +--- + +## Cadence design + +Different audiences need different cadences. + +### High-frequency (weekly or more) + +- Direct team, manager, sponsor +- Active project stakeholders +- People making day-to-day decisions + +### Medium-frequency (biweekly to monthly) + +- Skip-level +- Cross-functional partners +- Adjacent teams +- Strategic stakeholders + +### Low-frequency (quarterly) + +- Executive review +- Board update +- Wider organization +- External stakeholders (where relevant) + +The right cadence is what's needed, not what fills the calendar. Update people when there's something new; don't manufacture updates. + +--- + +## Failure patterns + +Long preamble before the point. Three paragraphs of context, then the one sentence that mattered. Lead with the point. + +Status: yellow. Same status three weeks in a row. Yellow with no change is red. Be honest about progress. + +Update without a clear ask. "We're working on it." OK, what do you want? If nothing, say "no action needed." + +Sandwiching bad news in good news. "We've done X and Y, and unfortunately Z is delayed, but we've also done W." The bad news gets lost. Lead with it if it's the headline. + +Walls of text. Too long, unread. Cut to the structure. + +Activity vs outcome. "Met with team. Reviewed plan. Updated tickets." So what? "Cut scope to hit launch date" is an outcome. + +Different update for every audience. Maintaining 5 versions doubles work. Have one core update; tailor the framing. + +Status update that's actually a request. Buries an ask in a wall of status. Pull the ask out. Make it visible. + +Optimistic projections. "We'll be back on track next week." Then we're not. Then again. Trust erodes. Be honest about the path. + +No follow-up on asks. Asked for a decision; didn't get one; moved on. Now the project is stuck. Follow up. + +Communicating bad news only when forced to. Stakeholders find out from someone else, or from a missed deadline. Lose trust. Communicate proactively. + +Performative comms for the audience of one. Every update reads like a sales pitch to the boss. Stakeholders see through it. Be direct. + +No comms when no news. Silence is worse than "no change this week." Set expectations on cadence and stick to it. + +--- + +## Output format + +A communication plan for a project includes: + +- Stakeholder map: named people, their interests, their decision rights +- Cadence: what updates go to whom, how often +- Templates: standardized formats for repeated updates +- Escalation paths: who to involve when something's at risk +- Decision log: running record of decisions made, by whom, why + +For individual communications: + +- Headline: the takeaway +- Body: the supporting structure +- Ask: the request, explicitly +- Distribution: who gets it, in what form + +--- + +## Reference files + +- [`references/update-templates.md`](references/update-templates.md): Ready-to-use templates for the most common stakeholder communications, with annotated examples. diff --git a/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md b/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md new file mode 100644 index 0000000..70d88d4 --- /dev/null +++ b/dist/pi/.agents/skills/stakeholder-communication/references/update-templates.md @@ -0,0 +1,452 @@ +# Update Templates + +Ready-to-use templates for the most common stakeholder communications. Annotated with what each section is doing. + +Adapt to your house style. The structure matters more than the exact wording. + +--- + +## Template 1: Weekly project status + +For internal teams, manager, sponsor. Sent same day each week. + +``` +Subject: [Project] weekly update: [date] + +Status: On track + +We're on plan to ship [milestone] by [date]. + +This week: +- Shipped [specific outcome] +- Started [specific work], [N]% complete +- Decision: chose [option] for [problem] + +Next week: +- Complete [specific work] +- Begin [specific work] +- Review: [decision needed by sponsor] + +Risks: +- [Risk]: [what we're doing about it] + +Asks: +- [Specific ask, if any] + +Detail: [link to project doc] +``` + +Annotations: +- Status indicator (On track / At risk / Off track) is the first thing readers scan +- "This week" is outcomes, not activities +- "Next week" is specific commitments, not vague intentions +- Risks have plans attached +- Asks are explicit and called out + +--- + +## Template 2: At-risk update + +When the project is no longer comfortably on track. + +``` +Subject: [Project] update: at risk for [milestone] + +Status: At risk + +The [milestone] target of [date] is at risk because [specific reason]. + +What's happening: +- [Fact 1] +- [Fact 2] +- [Fact 3] + +Impact: +- If we miss by a week: [specific impact] +- If we miss by a month: [specific impact] + +What we're doing: +- [Action 1] (owner: [name], by: [date]) +- [Action 2] (owner: [name], by: [date]) + +What we need from you: +- [Specific decision or help] + +Next update: [date] +``` + +Annotations: +- Doesn't pretend to be on track +- Names the specific cause +- Quantifies the impact +- Has a plan with owners and dates +- Has a clear ask +- Sets expectations for next update + +--- + +## Template 3: Off-track / missed milestone + +When the milestone has been missed or will be. + +``` +Subject: [Project] off track: [milestone] will miss [date] + +Status: Off track + +We will miss the [date] milestone for [specific reason]. Revised target: [new date]. + +What happened: +[2-3 sentences of what specifically caused the miss. Direct, no euphemisms.] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we're doing: +- [Action 1] +- [Action 2] + +Lessons we're applying: +- [Lesson learned] + +What we need: +- [Specific ask, if any] + +Next milestone: [date for the next checkpoint] +``` + +Annotations: +- States the miss in the headline +- Names cause without scapegoating +- Quantifies impact +- Has a plan +- Includes lessons (shows learning, builds trust) +- Sets the next checkpoint + +--- + +## Template 4: Decision request + +When you need a decision from a stakeholder. + +``` +Subject: Decision needed: [decision] by [date] + +The decision: [What needs to be decided] + +Context (60 seconds): +[The minimum needed for someone to understand. Include only what's relevant.] + +Options: + +Option A: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option B: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option C: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Recommendation: Option [X], because [reason]. + +Need by: [Date] + +Detail: [Link to fuller analysis] +``` + +Annotations: +- The decision is named at the top +- Context is bounded (60 seconds) +- Options are parallel in structure +- Recommendation is explicit +- Deadline is named + +--- + +## Template 5: Executive review + +For exec audiences: monthly, quarterly, or per major milestone. + +``` +Subject: [Initiative] exec review: [date] + +Headline: [One-sentence summary of the state of things] + +Key points: + +1. [Point 1 with one supporting sentence] +2. [Point 2 with one supporting sentence] +3. [Point 3 with one supporting sentence] + +Metrics: + +\| Metric \| Target \| Actual \| Trend \| +\|---\|---\|---\|---\| +\| [Metric 1] \| [Target] \| [Actual] \| ↑/↓/→ \| +\| [Metric 2] \| [Target] \| [Actual] \| ↑/↓/→ \| +\| [Metric 3] \| [Target] \| [Actual] \| ↑/↓/→ \| + +Decisions needed: +- [Decision 1: brief context, options summary, recommendation] +- [Decision 2: brief context, options summary, recommendation] + +Risks: +- [Top risk and mitigation] + +Asks: +- [Specific ask] + +Detail: [Link to fuller documentation] +``` + +Annotations: +- Executives skim. Headline carries the load. +- 3 key points (not 7) +- Metrics in table form, with trend +- Decisions called out, with recommendations +- Detail is linked, not inlined +- One page max for the email body + +--- + +## Template 6: Launch announcement (internal) + +For announcing something shipped. + +``` +Subject: Launched: [Thing] + +We've launched [Thing]. + +What it is: +[1-2 sentences of plain description. What it does, who it's for.] + +Why it matters: +[1-2 sentences of impact. What problem it solves, what changes.] + +How to learn more: +- [Link to docs / demo / page] +- [Contact for questions] + +Thanks to: +[The team that did the work, by name] +``` + +Annotations: +- Short and clear +- Includes the why (not just the what) +- Acknowledges the team + +--- + +## Template 7: Asking for help + +When you need expertise, time, or introduction from a colleague. + +``` +Subject: [Specific ask]: [N] minutes + +Hi [Name], + +I'm working on [brief context, one sentence]. I'd value your help with [specific ask]. + +What I need: +- [Specific item 1] +- [Specific item 2] + +What I've already tried: +- [Approach 1, outcome] +- [Approach 2, outcome] + +Time I'm asking for: [N minutes / specific session / specific deliverable] +Need by: [Date or "no rush"] + +If you're not the right person, who would you suggest? + +Thanks, +[Name] +``` + +Annotations: +- Subject is specific +- Specific ask, not vague +- Shows you've tried (respect for their time) +- States time required +- Provides an out (suggest someone else) + +--- + +## Template 8: Update for skip-level / VP + +For your manager's manager. Shorter, sharper than direct-manager update. + +``` +Subject: [Initiative]: quick update + +[Initiative] is [on track / at risk] for [milestone]. + +Highlights: +- [Outcome 1] +- [Outcome 2] +- [Decision: what was decided] + +What's coming: +- [Next big milestone] + +Risks I'm watching: +- [Top risk] + +I'll come to you for: [specific upcoming need] + +Detail: [link] +``` + +Annotations: +- Half the length of a manager update +- Emphasizes outcomes, not activities +- "I'll come to you for" sets expectations on when you'll need them +- Detail is linked, not inlined + +--- + +## Template 9: Quarterly business review (QBR) + +Cross-functional, leadership audience. Substantive. + +``` +Subject: [Function/team] QBR: Q[N] + +Quarter at a glance: + +[3-sentence narrative summarizing the quarter] + +Goals vs results: + +\| Goal \| Target \| Result \| Status \| +\|---\|---\|---\|---\| +\| [Goal 1] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| +\| [Goal 2] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| +\| [Goal 3] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| + +Wins this quarter: +- [Specific win 1] +- [Specific win 2] +- [Specific win 3] + +What didn't go as planned: +- [Specific miss 1: what happened, what we learned] +- [Specific miss 2: what happened, what we learned] + +Next quarter: +- [Top priority 1] +- [Top priority 2] +- [Top priority 3] + +Risks and asks: +- [Risk and what we're doing] +- [Ask if any] + +Headcount / budget changes: +[If relevant, brief] +``` + +Annotations: +- Narrative summary up front +- Goals table with clear pass/fail +- Wins AND misses (honest) +- Forward-looking section +- Asks are explicit + +--- + +## Template 10: Bad news, broader audience + +For when something significant has gone wrong and a wider audience needs to know. + +``` +Subject: [Plain description of what happened] + +[1 sentence: what happened, in plain language] + +What happened: +[2-4 sentences of specific facts. No euphemisms.] + +Who's affected: +- [Specific group 1] +- [Specific group 2] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we've done so far: +- [Action 1] +- [Action 2] + +What's next: +- [Action and timeline] +- [Action and timeline] + +If you have questions: +[Contact and channel] + +[Sign-off from named accountable person, with their role] +``` + +Annotations: +- Plain subject. No spin. +- Facts before reassurance +- Impact stated, not hedged +- Forward path is clear +- Named accountable person at the bottom +- Channel for questions + +--- + +## What to avoid in any template + +Vague status indicators. "Things are going well" is not status. On track / at risk / off track is. + +Activity dumps. "We met. We reviewed. We updated." Stakeholders care about what changed, not what you did. + +Hedge words on certainty. "We should probably maybe be on track." If you know, say it. If you don't, say what you don't know. + +Buried asks. Asks at the bottom in a paragraph go unread. Pull them out. Bold them. Make them findable. + +Different units in different sections. "5 days" in one place, "by next Tuesday" in another. Pick a convention and stick with it. + +Acronyms not understood by the audience. Especially across functions. Spell out on first use. + +No links. Detail in the email forces everyone to read the same wall of text. Link the detail. Let people choose. + +Missing accountable owner. Who owns each next step? If the answer is "the team," nothing happens. Name people. + +Inconsistent cadence. Update Monday, then nothing for three weeks, then a wall on a Friday. Set cadence. Hold it. + +--- + +## Customizing for your context + +The templates above are starting points. Customize for: +- Your organization's tone (formal vs casual) +- Your stakeholders' preferences (some want bullets, some want narrative) +- Your medium (email vs doc vs slide) +- Your project's complexity (more or less detail in the body) + +Whatever you customize, keep: +- Headline first +- Status indicator visible +- Asks explicit +- Owners and dates named +- Consistent structure across updates (so readers can scan reliably) diff --git a/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md b/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md new file mode 100644 index 0000000..180e5c4 --- /dev/null +++ b/dist/pi/.agents/skills/team-onboarding-playbook/SKILL.md @@ -0,0 +1,189 @@ +--- +name: team-onboarding-playbook +description: Design a structured onboarding experience that gets new team members productive in 30, 60, and 90 days. Use when a new hire is joining, when contractors or agency partners need to ramp up, when an existing team is restructuring and members are switching focus, or when current onboarding feels chaotic and slow. Also triggers when one person owns all the tribal knowledge and you need to capture it, when you keep losing people in their first 90 days, or when a new project has many fresh members joining at once. Useful for engineering, design, product, marketing, and operations roles. +category: process-and-team +catalog_summary: "30-60-90 onboarding plans for new hires and contractors" +display_order: 4 +--- + +A repeatable framework for building an onboarding playbook that ramps new team members predictably without burning out the people training them. + +## When to use + +- A new hire is joining and you do not have a written onboarding plan. +- An existing onboarding process is informal and inconsistent. +- A team is growing fast and onboarding is the bottleneck. +- A contractor or agency partner needs to ramp up quickly. +- A team member is leaving and their knowledge needs capturing. +- Onboarding currently takes too long and you want to reduce it. + +## When NOT to use + +- For ongoing performance management (different problem). +- For training on a specific technology (use targeted docs and tutorials). +- For documentation strategy in general (use `documentation-strategy`). +- For role definition or hiring (different upstream problem). + +## Required inputs + +- The role: what the person will do, what success looks like at 90 days. +- Existing artifacts: docs, runbooks, codebases, design files. +- The team: who will mentor, who will pair, who answers what kind of question. +- Tools and access: what accounts and systems the new person needs. +- Time budget: how much time team members can invest in onboarding. + +## The framework + +A good onboarding plan operates on 4 layers. Build all four. + +### Layer 1: Belonging (Day 1 to Week 1) + +The first week is mostly about belonging, not productivity. Get this right and everything else accelerates. + +- Welcome message before they start. +- Workspace and accounts ready before day 1. No "we will get to that". +- A buddy or onboarding partner assigned (someone other than the manager). +- Day 1 schedule that is not 8 hours of meetings, but is also not zero meetings. +- Introductions to the people they will work with regularly. +- A first-week rhythm: daily check-in with manager or buddy. + +### Layer 2: Context (Week 1 to Week 4) + +The next phase is context. The new person needs to understand the system before they can change it. + +- The product or business: what we do, who we serve, why we exist. +- The team: who owns what, how decisions get made. +- The technical or operational landscape: the architecture diagram, the main tools, the key files. +- The recent past: major decisions, recent launches, current priorities. +- Active projects: what is in flight and how it fits. + +A reading list is part of this. Keep it short. Annotated. Curated. + +### Layer 3: Contribution (Week 2 to Week 6) + +By week 2 or 3, the new person should be making real contributions. Not because they are fully ramped, but because contribution is how ramping happens. + +- A first task that is small, scoped, and shippable in week 2. +- Pairing or shadowing on a real piece of work in week 3. +- Independent ownership of a small project by week 4 or 5. +- Code review, design critique, or equivalent peer feedback from the start. + +The first task matters. Pick something that touches the main systems but cannot break anything important. Something that ships gives confidence and visibility. + +### Layer 4: Mastery (Month 2 to Month 3) + +By the end of 90 days, the new person should be a full member of the team. + +- Owning a project end to end. +- On-call or on-rotation if the team has one. +- Contributing to roadmap discussions, not just executing them. +- Mentoring or supporting the next new hire. + +90 days is a checkpoint, not a finish line. Document what worked and what was missing for the next person. + +## The 30/60/90 plan + +Every onboarding plan should have explicit milestones at 30, 60, and 90 days. + +### 30 days + +- Workspace, tools, and access fully set up. +- Has met every team member. +- Understands the product, the team, and the recent context. +- Has shipped or contributed to at least one real piece of work. +- Has a clear picture of their first major project or area. + +### 60 days + +- Owns a project or area independently. +- Knows where to find answers without asking every time. +- Has formed working relationships beyond the immediate team. +- Has made at least one meaningful improvement to a process, doc, or codebase. + +### 90 days + +- Fully productive in the role. +- Participating in roadmap and planning discussions. +- Capable of training the next new hire on parts of the system. +- Comfortable raising concerns and pushing back. + +If someone is significantly behind these markers at the 30/60/90 checkpoints, address it directly. Either the plan is wrong, the support is wrong, or the role fit is wrong. Hoping it resolves itself does not work. + +## The role-specific overlay + +The framework above applies to every role. The specifics differ. + +### Engineering + +- Day 1: dev environment running, first commit (a docs fix or trivial change). +- Week 1: read the architecture doc, read the main service code paths. +- Week 2: ship a small bug fix or refactor. +- Week 4: own a feature or component. +- Month 2: on-call shadow, then on-call. + +### Design + +- Day 1: design tools set up, design system access, brand guidelines reviewed. +- Week 1: studio crit and design review participation. +- Week 2: own a small surface (a setting page, an empty state). +- Week 4: lead a design review for a feature in flight. +- Month 2: own a feature design end to end. + +### Product + +- Day 1: read the strategy doc, the roadmap, and the latest 3 PRDs. +- Week 1: shadow customer calls, attend support sync, join standup of all relevant teams. +- Week 2: write a discovery doc or competitive analysis. +- Week 4: own a feature spec. +- Month 2: own a roadmap area. + +### Marketing or content + +- Day 1: brand voice doc, recent campaigns, top performing content. +- Week 1: customer research artifacts and persona docs. +- Week 2: ship a small piece of content (a social post, a blog edit). +- Week 4: own a content piece end to end. +- Month 2: own a campaign or channel. + +Adapt to your role and stack. The shape stays the same. + +## Workflow + +1. Start the playbook before the new person arrives. Do not write it on day 1. +2. Pre-stage accounts, hardware, and access. This is the most common day-1 failure point. +3. Assign a buddy. Tell the buddy what is expected of them. +4. Send the welcome message and the day-1 schedule before they start. +5. Run the first week with a focus on belonging and context, not output. +6. Check in daily for the first week, weekly for the first month. +7. Run formal 30/60/90 check-ins with explicit milestones. +8. After 90 days, do a retrospective: what worked, what was missing. +9. Update the playbook based on the retrospective. Onboarding is a living doc. + +## Failure patterns + +- No plan. Day 1 with no schedule, no laptop, no accounts. Sets a tone. +- Drinking from a firehose. 8 hours of meetings on day 1. People remember nothing. +- No real work for too long. Three weeks of "reading docs" is demoralizing. Ship something small early. +- All buddy, no manager. Buddies are great but cannot evaluate or advocate. Manager is still on the hook. +- Tribal knowledge as gating. "Just ask Sara if you have questions" works until Sara is on vacation. Document the answers Sara keeps giving. +- No 30/60/90 milestones. Onboarding "ends" when someone seems busy. That is not a milestone. +- Generic plan for every role. Engineering and marketing have different first-week needs. Use the role overlay. +- No retrospective. The same gaps catch every new hire because nobody updated the playbook. +- Buddy with no time. Assigning a buddy who is also drowning is a recipe for poor onboarding and burnout. Protect their time. +- Skipping the customer or product context. Engineers who do not know who the customer is build the wrong things. Marketers who do not know how the product works write thin copy. + +## Output format + +Deliverables: + +1. Pre-day-1 checklist: accounts, hardware, access, buddy assignment, welcome message. +2. Day-1 schedule: meeting list, intros, first deliverable. +3. First-week reading list: 5-10 curated, annotated docs. +4. 30/60/90 milestones: the explicit checkpoints for this role. +5. Buddy guide: what is expected of the onboarding partner. +6. Manager check-in cadence: scheduled 1:1s and milestone reviews. +7. Retrospective template: to fill out at 90 days for next-time improvement. + +## Reference files + +- [`references/onboarding-checklist.md`](references/onboarding-checklist.md): A day-by-day, week-by-week checklist for the first 30 days, with role-specific variants and a 30/60/90 review template. diff --git a/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md b/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md new file mode 100644 index 0000000..c82acb7 --- /dev/null +++ b/dist/pi/.agents/skills/team-onboarding-playbook/references/onboarding-checklist.md @@ -0,0 +1,214 @@ +# Onboarding checklist + +A day-by-day, week-by-week checklist for the first 30 days. Adapt the role-specific items to fit your team. + +## Before day 1 (1 week ahead) + +Manager prep: + +- [ ] Confirm start date and any logistics (remote, hybrid, in-office). +- [ ] Assign onboarding buddy. Brief them on expectations. +- [ ] Order hardware. Confirm delivery before start date. +- [ ] Create accounts: email, chat, source control, design tools, project management, calendar, password manager. +- [ ] Add to relevant team channels and meeting invites. +- [ ] Block manager calendar for daily check-ins in week 1. +- [ ] Send welcome email to new hire 3-5 days before start. Include: day-1 logistics, what to expect, where to be, what to bring. +- [ ] Notify the team via channel: who is starting, when, what role. +- [ ] Prep first task. Something small, scoped, shippable in week 1 or 2. + +## Day 1 + +Morning: + +- [ ] Welcome from manager (30 min, not 90 min). +- [ ] Tour of tools, accounts, and where things live. +- [ ] Lunch with buddy or team (whatever is normal for your team). + +Afternoon: + +- [ ] Read the welcome doc or onboarding hub. +- [ ] Set up local environment. Buddy or buddy-channel available for help. +- [ ] First commit, design upload, doc edit, or equivalent. Trivial. Just to validate the workflow. + +End of day: + +- [ ] 15-minute check-in with manager. How did it go. + +## Week 1 + +Goals: belonging and basic context. Not productivity. + +- [ ] Daily 15-minute check-in with manager. +- [ ] 1:1 with buddy at least twice. +- [ ] Read the curated reading list (5-10 docs, no more). +- [ ] Meet with 5-7 people they will work with. 30 minutes each. Casual. +- [ ] Attend team standup and one team meeting (without obligation to contribute). +- [ ] Submit at least one trivial fix or improvement (typo, doc clarification, small refactor). +- [ ] Set up time tracking, expense, or admin systems if your org uses them. +- [ ] Confirm hardware, software, and access are all working. + +End of week 1: + +- [ ] Manager check-in: what is unclear, what felt wrong, what is missing. + +## Week 2 + +Goals: contributing to real work, even in a small way. + +- [ ] Pair with a teammate on a real task. Half day to a full day. +- [ ] Take ownership of the first small task. Should be shippable in 3-5 days. +- [ ] Attend customer call, support sync, or equivalent customer touchpoint. +- [ ] Read the recent decision log or major PRDs from the last 3 months. +- [ ] First contribution to standups: what they are working on. + +End of week 2: + +- [ ] Manager check-in: how is the first task going. What is blocking. What feels overwhelming. + +## Week 3 + +Goals: independent ownership starts. + +- [ ] Ship the first small task. +- [ ] Take on a slightly larger task. 1-2 weeks of work. +- [ ] Participate in code review, design critique, or equivalent. +- [ ] Meet with 3-5 cross-functional partners (PM ↔ Eng, Design ↔ PM, etc.). +- [ ] Begin to recognize patterns: "this is the third time someone asked X, where is that documented?" + +End of week 3: + +- [ ] Buddy check-in: how is the experience. What is the new hire stuck on that they will not raise to the manager. + +## Week 4 / 30-day mark + +Goals: validate the ramp is on track. + +- [ ] Complete the first medium-sized project or be visibly in flight. +- [ ] Have a working mental model of the product, team, and stack. +- [ ] Have at least one improvement filed (a doc fix, process suggestion, automation). +- [ ] Manager 30-day review (see template below). + +## 30-day review + +Manager runs this with the new hire, in 1:1, around day 30. + +``` +30-day review for [name] + +What is going well: +- [Two or three things] + +What is unclear or hard: +- [Two or three things] + +What I have shipped or contributed to: +- [List] + +What I want to be doing more of: +- [List] + +What I want help with: +- [List] + +Manager observations: +- [What you have noticed] + +Action items: +- [Specific things to address before 60-day mark] +``` + +The output of the 30-day review is honest signal. If the new hire is behind, the manager addresses the cause, not the symptom. If they are ahead, accelerate. + +## 60-day milestones + +By day 60: + +- [ ] Owning a project or area independently. +- [ ] Asking targeted questions, not "how does anything work" questions. +- [ ] Has working relationships outside the immediate team. +- [ ] Has been on customer or user calls if applicable. +- [ ] Has flagged at least one process improvement. +- [ ] 60-day review complete. + +## 90-day milestones + +By day 90: + +- [ ] Fully productive in the role at expected level. +- [ ] Participating in planning and roadmap discussions. +- [ ] On call or on rotation if the team has one. +- [ ] Capable of teaching parts of the system to a peer. +- [ ] Has identified gaps in onboarding from their perspective. +- [ ] 90-day review and onboarding retrospective complete. + +## 90-day onboarding retrospective + +Run this with the new hire at the end of 90 days. Capture the answers. Update the playbook. + +``` +What was great about your onboarding: +- [List] + +What was confusing or hard: +- [List] + +What was missing: +- [List] + +What you would have liked on day 1: +- [List] + +What you would change for the next person: +- [List] + +What you wish you had known earlier: +- [List] +``` + +The output of this retro feeds the next version of the playbook. Without this loop, every new hire faces the same gaps. + +## Role-specific first tasks + +Examples of good first tasks (shippable in week 1-2): + +### Engineering + +- Fix a small bug from the bug tracker (not customer-blocking, but real). +- Add a missing test or improve a flaky one. +- Update a deprecated API call in one place. +- Improve a developer doc that has been out of date. + +### Design + +- Audit a small part of the product against the design system. +- Design an empty state, error state, or settings sub-page. +- Update an outdated illustration or asset. +- Document a component that is in production but not in the design system. + +### Product + +- Write a competitive analysis on one feature area. +- Document a customer pain point heard in support. +- Update a stale PRD with current state. +- Write a one-pager on a roadmap item that needs sharper framing. + +### Marketing / Content + +- Edit and update a stale blog post. +- Audit recent campaign performance and write a 1-page summary. +- Repurpose an existing piece of content into a new format. +- Write a short customer quote roundup or testimonial summary. + +The pattern: real, scoped, ships in days, low risk, builds context. + +## What "fully ramped" looks like + +A new hire is fully ramped when: + +- They no longer ask "how does this work" but "why was it built this way". +- They contribute to direction, not just execution. +- They identify gaps and fill them without being asked. +- They mentor or assist the next new hire. +- They push back on things that do not make sense. + +This usually lands somewhere between 90 and 180 days, depending on the role and the system's complexity. Track it. If 180 days passes and the person is still not at this bar, dig into why. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md b/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md new file mode 100644 index 0000000..da26f0f --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/SKILL.md @@ -0,0 +1,309 @@ +--- +name: upgrade-flow-design +description: "Designing free-to-paid conversion flows for SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. Honest about paywall-everywhere (gates everything aggressively), free-forever-trap (no upgrade path surfaces), and value-triggered-upgrade (paywall surfaces at moments of demonstrated value) patterns. Triggers on upgrade flow, paywall, free-to-paid, freemium conversion, trial conversion, plan upgrade, subscription upgrade, win-back flow, churn prevention. Also triggers when free-to-paid conversion is low, when paywalls are blocking the wrong moments, or when upgrade flows are being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing free-to-paid conversion flows. Distinguishes paywall-everywhere (gates everything aggressively) from free-forever-trap (no upgrade path surfaces) from value-triggered-upgrade (paywall surfaces at moments of demonstrated value)" +display_order: 9 +--- + +# Upgrade Flow Design + +A senior product marketing director's playbook for designing free-to-paid conversion flows in SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. The discipline of asking for the upgrade at the moment the user has a reason to say yes. + +Most upgrade flows fail in one of two ways. They block meaningful product use behind paywalls so aggressively that users churn before reaching the moment that would justify paying. Or they offer a generous free tier with no upgrade path that ever surfaces; users get everything they need; conversion stays at single-digit percentages indefinitely. + +The upgrade flows that work do something different. They surface paywalls at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next; the user is positioned to say yes because the value is fresh. + +The voice is the senior product marketing director who has watched conversion rates double when paywalls were re-timed and watched them collapse when more aggressive paywalls were added. Practical, opinionated about the moments that earn the upgrade ask, willing to call out when the product's free tier is too generous to convert. + +When to use this skill: scoping a free-to-paid conversion flow for the first time, auditing paywalls that block conversion or never surface, designing the trigger moments that earn upgrade asks, or deciding plan structure that supports upgrades over time. + +--- + +## What this skill covers + +This skill spans free-to-paid conversion flows in SaaS products. The growth-tooling distinctions: + +- `lead-magnet-design` is top-of-funnel email capture. This skill is free-to-paid conversion in-product. +- `funnel-flow-architecture` is the cross-tool funnel architecture. This skill is the upgrade flow specifically. +- `upgrade-flow-design` (this skill) is trigger-moment design, paywall presentation, plan structure, win-back, churn prevention. +- `landing-page-copy` is pricing-page copy; lives downstream of this skill's plan-structure decisions. +- `pm-spec-writing` is the spec for engineers building the upgrade flow. + +The audience: product marketers, growth marketers, in-house product teams, agencies running SaaS conversion work for clients. + +Out of scope: cross-funnel architecture (covered by `funnel-flow-architecture`); pricing-page copy (covered by `landing-page-copy`); the engineering implementation; specific Stripe/Chargebee/Recurly/Paddle billing-platform configurations (those stay implementation-side). + +--- + +## The free-tier decision: freemium vs free-trial vs no-free + +Before designing the upgrade flow, decide the free-tier structure. + +Freemium (free-forever tier). + +- Users use the product indefinitely without paying. +- Paid tier offers more value (capacity, features, support). +- Conversion typically 2-5 percent; volume compensates. + +When it works: products with strong network effects, or where free users provide product value (data, content, virality). + +Free-trial (time-limited). + +- Users get full or near-full product for a defined period. +- After trial, must pay to continue. +- Conversion typically 10-25 percent of trial signups. + +When it works: products where the value is clear quickly; audiences willing to commit time before paying. + +Reverse trial. + +- Users start on paid plan; auto-downgrade to free after period. +- Less common; mixes signals; can produce surprise churn. + +No-free (paid-only). + +- No free tier; users pay to start. +- Conversion is from prospects rather than free users. +- Conversion rates depend on sales motion, not in-product upgrade flows. + +When it works: enterprise products, high-touch sales, products where free would dilute brand or capacity. + +The decision is upstream of upgrade flow design. Different free-tier structures warrant different upgrade flows. + +Detail in [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md). + +--- + +## Paywall-everywhere vs free-forever-trap vs value-triggered-upgrade + +The keystone framing. + +Paywall-everywhere. Paywall blocks meaningful product use. Free tier exists but is too constrained to demonstrate value. Users churn before reaching the moment that would justify paying. Cost: users who would have paid after seeing value never reach that moment; conversion suffers despite aggressive paywalling. + +Free-forever-trap. Generous free tier with no upgrade path that ever surfaces. Users get everything they need; never see why they would pay. Conversion rate stays at single-digit percentages indefinitely. Cost: the team has built a product users like for free; revenue does not follow because the upgrade ask never lands. + +Value-triggered-upgrade. Paywall surfaces at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next. Cost: design effort upfront is significant; conversion typically meaningfully higher than either alternative. + +The litmus test. After a user encounters the upgrade flow, can they articulate why they should pay? "Because I just hit my limit on this feature I have used 200 times" is value-triggered. "Because the product told me to pay before letting me use it" is paywall-everywhere. "I have not seen an upgrade ask" is free-forever-trap. + +--- + +## Trigger-moment design: where paywalls earn their interruption + +The single most consequential decision in upgrade flow design. + +The principle. Paywalls surface at moments where the user has demonstrated they are getting the product's value. The interruption is justified because the user has a reason to say yes. + +Strong trigger moments. + +- Usage threshold reached. User has used a feature N times; further use requires paid plan. Honest because they are clearly getting value. +- Capacity limit hit. User has reached free-tier capacity; upgrade unlocks more. Predictable; expected. +- Advanced feature attempted. User clicked into a feature that requires paid plan. Interest is fresh. +- Workflow completed successfully. User has seen value through a completed action; upgrade ask connects that value to recurring access. +- Team-collaboration moment. User wants to invite teammates; team capabilities require paid plan. +- Time-trial ending. Trial-based products surface upgrade as trial nears end. + +Weak trigger moments. + +- First-login. User has not yet seen value; upgrade ask is premature. +- Random in-product placement. Paywall on the dashboard with no specific trigger; users dismiss. +- Every-page banner. Persistent upgrade banner across all surfaces; users develop blindness. + +The discipline. Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +Detail in [`references/trigger-moment-design.md`](references/trigger-moment-design.md). + +--- + +## Paywall presentation: modal vs banner vs inline + +How the paywall surfaces. + +Pattern A: Modal paywall. Full-screen overlay blocks the action; user must upgrade or dismiss. + +When to use. Capacity limits, feature gates the user has hit. The interruption is warranted by the trigger. + +Pattern B: Banner paywall. Persistent banner at top of page suggesting upgrade. + +When to use. Soft prompts; awareness without interruption. Risk of becoming visual noise. + +Pattern C: Inline paywall. Upgrade ask embedded in the surface where the trigger occurred. + +When to use. Contextual prompts that integrate with the workflow. + +Pattern D: Toast or notification. Brief paywall surfaced as a notification. + +When to use. Soft prompts; low-priority upgrade asks. + +Choice criteria. + +- The trigger's strength determines the presentation's intensity. +- Strong triggers (capacity hit, feature gate) warrant modal. +- Soft triggers (general awareness) warrant inline or toast. + +Copy and value-prop discipline. + +- The paywall copy should connect to what the user just did. +- "You have used [feature] 50 times. Upgrade to remove the limit and unlock [related capabilities]." matches the trigger. +- "Upgrade for more features" is generic and weak. + +Detail in [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md). + +--- + +## Upsell vs downsell logic + +When the user does not accept the primary upgrade. + +Upsell. User is on basic plan; ask them to upgrade to higher tier. + +Cross-sell. User is paying; offer add-ons or related products. + +Downsell. User declined the higher tier; offer a smaller commitment (smaller plan, monthly vs annual, basic vs full feature set). + +The downsell discipline. Some users will not upgrade to the proposed tier but will upgrade to something. Downsell captures revenue otherwise lost. + +Examples. + +- User declined Pro upgrade; offer Starter plan as a path to begin paying. +- User declined annual plan; offer monthly with explicit cost difference disclosed. +- User declined full team plan; offer single-seat upgrade. + +Anti-pattern. Aggressive downsell that makes the user feel manipulated. Honest framing: "If Pro is more than you need, here is something that fits." + +Detail in [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md). + +--- + +## Win-back flow design + +Lapsed users, downgrades, partial-churn. + +Win-back triggers. + +- User has not logged in for 30/60/90 days. +- User downgraded plan. +- User canceled but did not delete account. +- User churned and signed up again later. + +Win-back patterns. + +- Email-based. Outreach with renewed value-prop, sometimes with discount or trial extension. +- In-product upon return. When the lapsed user returns, surface re-engagement help and (if appropriate) an upgrade-back ask. +- Personal outreach. For high-value lapsed users, sales or customer success conversation. + +Discount discipline. + +- Discounts to win back can create reverse-incentive (user churns to get discount). +- Discount sparingly; emphasize new value first. + +Detail in [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md). + +--- + +## Churn prevention upstream of upgrade + +The best upgrade flow is the one the user does not need because they did not churn. + +Upstream churn signals. + +- Declining engagement; sessions per week dropping. +- Last login distant. +- Support ticket pattern (frustration signals). +- Plan downgrade interest signals. + +Prevention patterns. + +- Engagement re-orientation. Surface help when engagement drops. +- Outreach. Customer success contact for high-value accounts at risk. +- Friction reduction. Audit the reasons users disengage; fix the friction. + +The prevention-vs-recovery economics. Preventing churn is much cheaper than winning back churned users. Invest upstream. + +Detail in [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md). + +--- + +## Plan structure: tier count, feature gating, pricing-page design + +The plans that the upgrade flow leads to. + +Tier count. + +- 2-tier (Free + Paid): simple; clear upgrade path; works for many products. +- 3-tier (Starter + Pro + Enterprise): broader audience; harder to design. +- 4+ tier: rarely better; complexity confuses users. + +Feature gating. + +- Capacity-based. Free tier limited by use volume; paid unlocks more. +- Feature-based. Free tier missing specific features; paid unlocks them. +- Hybrid. Both capacity and features differ. + +Discipline. Each tier should have a clear "this is for [X audience] because of [Y]." Tiers without clear audience-fit produce weak conversions. + +Pricing-page design. The pricing page is downstream of plan structure but lives close to upgrade flow. Detail in `landing-page-copy` for pricing-page copy specifically. + +Detail in [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md). + +- "Conversion rate is low; users churn before reaching upgrade." Paywall-everywhere; gates blocking value demonstration. +- "Conversion rate is single-digit; free users use the product for years." Free-forever-trap; no upgrade path surfaces. +- "Paywall fires; users dismiss; conversion does not lift." Trigger moments wrong; paywall not connected to demonstrated value. +- "Users hit paywall and churn." Wrong moment; paywall blocks before value is fresh. +- "Upgrade rate looks fine; downgrade rate is high." Plan structure wrong; users upgrade then realize they did not need the higher tier. +- "Win-back attempts have low conversion." Re-engagement timing wrong, or value-prop unchanged from what failed initially. +- "Annual plans not converting; monthly plans dominate." Annual value-prop weak; or commitment friction too high. +- "Sales says many leads come from churned users coming back." Win-back working but the previous churn was avoidable; audit upstream. +- "Conversion did not change after we redesigned the paywall." Paywall design was not the problem; trigger or plan structure may be. + +--- + +## The framework: 12 considerations for upgrade flow design + +When designing or auditing an upgrade flow, walk these 12 considerations. + +1. The free-tier decision. Freemium, free-trial, reverse trial, or no-free. +2. Value-triggered-upgrade, not paywall-everywhere or free-forever-trap. Paywalls at moments of demonstrated value. +3. Trigger-moment design sound. Paywalls connect to specific user-demonstrated value. +4. Paywall presentation matches trigger intensity. Strong triggers warrant modal; soft triggers inline. +5. Copy connects to the trigger. Specific value-prop tied to what the user just did. +6. Upsell, cross-sell, downsell logic. When primary upgrade is declined, secondary paths exist. +7. Win-back flows designed. Lapsed users have a clear re-engagement path. +8. Churn prevention upstream. Upstream signals trigger prevention; downstream upgrade flow is one of multiple defenses. +9. Plan structure clear. Tier count appropriate; each tier has clear audience-fit. +10. Pricing-page coordinates with upgrade flow. Plan structure decisions reflected on the pricing page. +11. Conversion as success metric. Not just paywall display; downstream conversion to paid. +12. Maintenance discipline. Plans, paywalls, win-back flows updated alongside product and pricing changes. + +The output of the framework is an upgrade flow that earns the user's "yes" by asking at the moment the user has a reason to say yes, with plan structure that fits the audience the product serves. + +--- + +## Reference files + +- [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md) - Freemium, free-trial, reverse trial, no-free. Choice criteria. +- [`references/trigger-moment-design.md`](references/trigger-moment-design.md) - Where paywalls earn their interruption. Strong vs weak trigger moments. +- [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md) - Modal, banner, inline, toast. Copy and value-prop discipline. +- [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md) - When primary upgrade is declined, secondary paths. +- [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md) - Lapsed users, downgrades, partial-churn re-engagement. +- [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md) - Preventing churn before the upgrade flow is needed. +- [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md) - Tier count, feature gating, audience-fit per tier. +- [`references/upgrade-flow-anti-patterns.md`](references/upgrade-flow-anti-patterns.md) - The patterns that look like upgrade flows but degrade trust. +- [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: upgrade flows earn revenue when they earn the user's yes + +The upgrade flows that compound revenue are the ones that ask at the moment the user has a reason to say yes. Not because the paywall blocked them. Not because the upgrade prompt happened to appear. Because the user just did something that demonstrated value, and the upgrade ask connected that value to continued or expanded access. + +That is the bar. Below the bar are paywall-everywhere (gates before value, conversion suffers) and free-forever-trap (no upgrade path, conversion never starts). Above the bar are value-triggered-upgrade flows where trigger-moment design, paywall presentation, plan structure, win-back, and churn prevention work together to convert the right users at the right moments. + +The discipline is in the design choices. The free-tier decision (freemium, trial, paid-only) sets the funnel shape. Trigger-moment design decides when paywalls earn their interruption. Paywall presentation decides how the ask lands. Plan structure decides what the user is upgrading to. Win-back and churn prevention catch the cases that escaped the primary upgrade flow. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md b/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md new file mode 100644 index 0000000..d20876e --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/churn-prevention-upstream.md @@ -0,0 +1,250 @@ +# Churn prevention upstream + +Preventing churn before the upgrade flow is needed. + +The best upgrade flow is the one the user does not need because they did not churn. Investing upstream of churn produces more revenue than recovering churned users. + +--- + +## The prevention-vs-recovery economics + +Preventing churn is much cheaper than winning back churned users. + +The math. Cost of preventing one churn (engagement program, support intervention, friction reduction): X. Cost of winning back one churned user (outreach, discount, re-acquisition): often 3-10X. + +The implication. Programs that detect churn risk early and intervene save more revenue than win-back programs that activate only after churn. + +The discipline. Build upstream signals; intervene before churn happens. + +--- + +## Upstream churn signals + +What predicts churn. + +Engagement decline. + +- Sessions per week dropping over 4-week period. +- Time-in-product per session declining. +- Feature usage breadth narrowing. + +Engagement gap. + +- Last login distant. +- Specific feature stopped being used. +- Days since last meaningful action. + +Support pattern. + +- Support tickets indicating frustration. +- Multiple unresolved issues. +- Tone shift in support conversations. + +Plan-related signals. + +- Asked about cancellation. +- Researched competitors (sometimes detectable through partner data). +- Downgrade interest. + +Team-level signals (B2B). + +- Champion left the company. +- Team reduced seats internally. +- Decision-maker became unresponsive. + +The signals combine. Single signals are noisy; combinations predict more reliably. + +--- + +## Detection systems + +How to know which users are at risk. + +Engagement scoring. Composite score based on usage signals; threshold for at-risk classification. + +Health scores. Often used by customer success teams; combines product engagement, support pattern, contract data. + +Predictive models. Statistical or ML models that predict churn probability per user. + +Manual flags. Account managers flag accounts they sense are at risk. + +The discipline. Detection should be operationalized; signals should fire alerts to teams who can act. + +--- + +## Intervention patterns + +What to do when at-risk users surface. + +Pattern A: Engagement re-orientation. + +How it works. In-product help surfaces when engagement drops. Re-orients the user to value. + +When to use. Soft signals; users who may have forgotten what the product does for them. + +Pattern B: Outreach. + +How it works. Customer success or sales reaches out to at-risk accounts. + +When to use. High-value accounts; B2B contexts where personal touch matters. + +Pattern C: Friction reduction. + +How it works. Audit reasons users disengage; fix the friction. Often product changes rather than outreach. + +When to use. When patterns of disengagement reveal product issues. + +Pattern D: Educational re-engagement. + +How it works. Send the user content (case study, advanced feature explanation) that re-anchors value. + +When to use. Soft re-engagement; cheap to scale. + +Pattern E: Plan adjustment. + +How it works. If usage shows the user is over-paying, suggest a downgrade. Counterintuitive but builds trust. + +When to use. When the user is genuinely on the wrong plan; saves the relationship. + +--- + +## The engagement-re-orientation pattern + +In-product help that surfaces when engagement drops. + +Implementation. + +- Trigger fires when engagement signal drops below threshold. +- In-product surface shows: "It looks like you have not used [specific feature] in a while. Here is how others use it." +- Optional brief tour or case study. + +Strengths. + +- Cheap. +- Scalable. +- Often catches users who simply forgot. + +Weaknesses. + +- May feel intrusive. +- Cannot address all reasons for disengagement. + +--- + +## The customer success outreach pattern + +Personal contact for high-value accounts. + +Implementation. + +- Health score crosses at-risk threshold. +- Account manager or CS lead reaches out. +- Conversation: what is happening, what would help, can we address. + +Strengths. + +- Highest engagement potential. +- Surfaces real reasons. +- Builds relationship. + +Weaknesses. + +- Expensive. +- Only viable for accounts above revenue threshold. + +--- + +## The friction-reduction pattern + +Fixing the underlying reason rather than just intervening per user. + +Implementation. + +- Audit common reasons for disengagement. +- Identify product changes that would address. +- Ship the changes. + +Strengths. + +- Compounds across all users. +- Often the highest-impact intervention. + +Weaknesses. + +- Slower; requires product team prioritization. +- Some friction reasons cannot be product-fixed (audience-fit issues). + +--- + +## The educational-re-engagement pattern + +Send content that re-anchors value. + +Implementation. + +- Email or in-product content showing case studies, advanced features, or use cases. +- Targeted to the user's profile. + +Strengths. + +- Cheap and scalable. +- Educates without demanding immediate action. + +Weaknesses. + +- Lower engagement than personal outreach. +- May feel like marketing. + +--- + +## When intervention has limits + +Not all churn can be prevented. + +Genuinely unfit users. Some users signed up but are not the right audience. Their churn is appropriate. + +Genuinely changed needs. User changed jobs; product no longer relevant. Cannot be retained. + +Genuinely better alternatives. Competitor genuinely better fit. Recovery may not be appropriate. + +The honest assessment. Recognizing unpreventable churn is part of the discipline. Intervention should focus on preventable churn. + +--- + +## Churn prevention vs upgrade flow + +Different problems; complementary disciplines. + +Churn prevention. Keeps users engaged; avoids churn. + +Upgrade flow. Converts engaged users to paid (or higher paid). + +The interaction. Strong churn prevention produces engaged users; engaged users are the audience for upgrade flow. Programs running both produce more revenue than either alone. + +--- + +## Common prevention failures + +No detection. Churn happens; nobody flagged it; recovery is the only option. + +Detection without intervention. Signals fire but nobody acts. + +Intervention timing wrong. Action too late; user already disengaged emotionally. + +Generic intervention. Same outreach to all at-risk users; no segmentation. + +Discount-led intervention. Lead with discount instead of value; trains discount-seeking behavior. + +Prevention misses fixable friction. Patterns of disengagement reveal product issues; team focuses on per-user intervention instead. + +No measurement. Cannot tell if prevention reduces churn rate. + +--- + +## Methodology-level choices that stay in the public skill + +The prevention-vs-recovery economics. Upstream churn signals (5 categories). Detection systems. Intervention patterns A through E. When intervention has limits. Churn prevention vs upgrade flow interaction. Common failures. + +## Implementation choices that stay internal + +Specific signals and thresholds for specific products. Specific health-score formulas. Specific intervention copy and protocols. The team's CS staffing model. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md b/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md new file mode 100644 index 0000000..bdc5116 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/common-upgrade-failures.md @@ -0,0 +1,179 @@ +# Common upgrade failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Conversion rate is low; users churn before reaching upgrade." + +The diagnosis. Paywall-everywhere; gates blocking value demonstration. + +The cure. Loosen free tier. Surface paywalls at moments of demonstrated value. Detail in `references/trigger-moment-design.md`. + +--- + +## "Conversion rate is single-digit; free users use the product for years." + +The diagnosis. Free-forever-trap; no upgrade path surfaces. + +The cure. Add value-triggered paywalls. Connect upgrade asks to demonstrated value. + +--- + +## "Paywall fires; users dismiss; conversion does not lift." + +The diagnosis. Trigger moments wrong; paywall not connected to demonstrated value. + +The cure. Audit trigger logic. Each paywall should answer "what value did the user just demonstrate?" + +--- + +## "Users hit paywall and churn." + +The diagnosis. Wrong moment; paywall blocks before value is fresh. + +The cure. Move paywalls to moments of demonstrated value, not pre-value moments. + +--- + +## "Upgrade rate looks fine; downgrade rate is high." + +The diagnosis. Plan structure wrong; users upgrade then realize they did not need the higher tier. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit. Detail in `references/plan-structure-patterns.md`. + +--- + +## "Win-back attempts have low conversion." + +The diagnosis. Re-engagement timing wrong, or value-prop unchanged from what failed initially. + +The cure. Lead with value-prop change. Avoid discount-only win-back. Detail in `references/win-back-flow-patterns.md`. + +--- + +## "Annual plans not converting; monthly plans dominate." + +The diagnosis. Annual value-prop weak; or commitment friction too high. + +The cure. Strengthen annual value (better discount, additional features). Reduce commitment friction (easier mid-year cancellation, prorated refunds). + +--- + +## "Sales says many leads come from churned users coming back." + +The diagnosis. Win-back working but the previous churn was avoidable; audit upstream. + +The cure. Invest in churn prevention upstream. Detail in `references/churn-prevention-upstream.md`. + +--- + +## "Conversion did not change after we redesigned the paywall." + +The diagnosis. Paywall design was not the problem; trigger or plan structure may be. + +The cure. Test variables that matter. Trigger moment, plan structure, value-prop copy. Paywall presentation alone often does not move the needle. + +--- + +## "Upgrade flow works for new users; existing users do not upgrade." + +The diagnosis. Triggers designed for new-user behavior; existing users do not hit them. + +The cure. Segment trigger logic. Existing users may need different triggers (feature-launch upgrades, capacity-growth upgrades). + +--- + +## "Conversion increased but new customer churn climbed." + +The diagnosis. Paywall too aggressive; converting users who do not see value. + +The cure. Audit conversion-to-retention correlation. Aggressive conversion may produce buyer's remorse. + +--- + +## "Users complain about hidden charges after upgrade." + +The diagnosis. Pricing not transparent; users surprised by total cost. + +The cure. Surface all costs upfront. Annual price, monthly price, taxes if applicable. Hidden costs damage trust. + +--- + +## "Cancellation rate spikes 3 months after upgrade." + +The diagnosis. Upgrade was made but value did not materialize; users gave it 3 months and left. + +The cure. Post-upgrade welcome and onboarding. Surface paid features; help users access value of paid plan. + +--- + +## "Different audience segments convert at different rates; we cannot tell why." + +The diagnosis. Per-segment data not tracked. + +The cure. Per-segment conversion analytics. Different segments may need different upgrade flows. + +--- + +## "Win-back outreach has unsubscribe rate climbing." + +The diagnosis. Outreach too frequent or generic. + +The cure. Segment outreach. Respect non-response. Reduce frequency. + +--- + +## "We A/B tested annual vs monthly default; result was wash." + +The diagnosis. Default may not have been the issue; price-anchoring or commitment friction may be. + +The cure. Test different variables. Price level, discount magnitude, presentation order. + +--- + +## "Sales-led upgrades convert at higher rate than self-serve." + +The diagnosis. Self-serve flow misses something that sales touches address. + +The cure. Audit what sales does that the flow does not. Often: clarifies value, addresses objections, customizes recommendation. + +--- + +## "We added more upsell prompts; existing customer churn went up." + +The diagnosis. Prompt fatigue. Existing customers feel squeezed. + +The cure. Frequency limits on upsell. Less is often more. + +--- + +## "Conversion drops at the credit-card-entry step." + +The diagnosis. Form friction or trust signals missing. + +The cure. Optimize the credit-card form. Add trust signals (security badges, refund policy). Reduce required fields. + +--- + +## The pattern across failures + +Most upgrade flow failures fall into one of three patterns. + +Pattern 1: Paywalls at wrong moments. Paywall-everywhere, premature, unconnected, free-forever-trap. The fix is to align paywalls with demonstrated value. + +Pattern 2: Plan structure misaligned. Plan-paralysis, plan-mismatch, post-upgrade-empty. The fix is clearer tier audiences and post-upgrade experience. + +Pattern 3: Trust damage. Bait-and-switch, hidden-price, aggressive-downsell, hard-to-cancel. The fix is transparency and respect for the user. + +The metric pattern: upgrade flow failures often look fine on conversion alone. The signal is in retention post-upgrade, churn rate, win-back conversion. Programs that track only conversion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (paywall timing, plan structure, trust). The principle that conversion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md b/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md new file mode 100644 index 0000000..6111ee4 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/free-tier-decision-criteria.md @@ -0,0 +1,253 @@ +# Free-tier decision criteria + +Freemium, free-trial, reverse trial, no-free. Choice criteria. + +The free-tier decision is upstream of upgrade flow design. The structure determines what the upgrade flow looks like, which trigger moments matter, and what conversion rates are achievable. + +--- + +## The free-tier decision matters + +Different free-tier structures warrant different upgrade flows. + +The win. A SaaS product chooses freemium because users provide product value (data, virality, network). Upgrade flow surfaces capacity-based paywalls. Conversion is 3 percent but volume produces meaningful revenue. + +The fail. Same product chooses free-trial without realizing user value matters more than time-bound trial. Trial ends; users churn rather than convert; the product loses the network effect users were providing for free. + +The decision is strategic; downstream design choices follow from it. + +--- + +## Pattern A: Freemium (free-forever tier) + +Users use the product indefinitely without paying. + +How it works. + +- Free tier offers core value with constraints (capacity limits, feature limits). +- Paid tier removes constraints or unlocks more. +- Users may stay free forever; conversion happens when they hit constraints they value enough to pay around. + +Conversion baseline. 2-5 percent typical for B2B SaaS; varies widely. + +Strengths. + +- Volume. +- Network effects from free users. +- Users provide product value (data, content, virality). +- Lower acquisition cost. + +Weaknesses. + +- Most users do not convert. +- Free-tier capacity costs. +- Plan-design pressure to gate the right things. + +When to use. Products with strong network effects, or where free users genuinely contribute to product value. + +--- + +## Pattern B: Free-trial (time-limited) + +Users get full or near-full product for a defined period. + +How it works. + +- Trial period (7-30 days typical). +- After trial, must pay to continue. +- Often credit-card-required at start (with auto-charge) or credit-card-not-required (with explicit conversion at end). + +Conversion baseline. 10-25 percent of trial signups; higher with credit-card-required. + +Strengths. + +- Strong commitment from users who start. +- Clear conversion deadline. +- Revenue arrives quickly post-trial. + +Weaknesses. + +- Friction at signup if credit card required. +- Users churn if trial ends before they reach value. +- Trial extension dynamics can become a negotiation. + +When to use. Products where value is clear within the trial period; audiences willing to commit time before paying. + +--- + +## Pattern C: Reverse trial + +Users start on paid plan; auto-downgrade to free after period. + +How it works. + +- Signup grants paid features for a defined period. +- After period, auto-downgrades to free tier. +- Users who want continued paid features upgrade. + +Conversion baseline. Moderate; mixes signals. + +Strengths. + +- Users see paid features; familiarity may drive conversion. +- Easier to start than credit-card-required trial. + +Weaknesses. + +- Surprise when downgrade hits. +- Some users dislike the loss-aversion framing. +- Less common; users may not know what to expect. + +When to use. When the team has tested both freemium and free-trial and reverse-trial outperforms; specific product-audience fits. + +--- + +## Pattern D: No-free (paid-only) + +No free tier; users pay to start. + +How it works. + +- Sales conversation or demo; user signs contract or starts subscription. +- No self-serve free path. + +Strengths. + +- Higher revenue per signup. +- Clearer signal of intent. +- No free-tier capacity costs. + +Weaknesses. + +- Lower top-of-funnel volume. +- Higher acquisition cost. +- Sales-motion dependent. + +When to use. Enterprise products, high-touch sales, products where free would dilute brand or capacity. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production products mix. + +Common combinations. + +- Freemium with free-trial of paid tier (free forever; trial of higher tier for free users). +- Free-trial with credit-card-not-required for self-serve, plus paid-only for enterprise. +- Reverse-trial for new users, freemium for users who downgrade at end of reverse-trial. + +The hybrid challenge. More complexity; more paths to maintain. Justify complexity with conversion data. + +--- + +## Choice criteria + +How to decide. + +Use freemium when: + +- Network effects matter; free users contribute value. +- Audience expects free; paid-only would limit reach. +- Conversion rate at scale produces meaningful revenue. + +Use free-trial when: + +- Value is clear within a trial period. +- Audience willing to commit time before paying. +- Conversion economics favor higher rate over higher volume. + +Use reverse-trial when: + +- Both freemium and free-trial have been tested and reverse-trial outperforms. +- Audience signal-strength is high (paid features get used). + +Use no-free when: + +- Audience is enterprise or high-touch. +- Product capacity costs prohibit freemium. +- Sales motion is the dominant funnel. + +Use hybrid when: + +- Different audience segments warrant different free structures. +- Data justifies the complexity. + +--- + +## Free-tier capacity design + +For freemium, the capacity decision. + +The principle. Free tier offers enough capacity to demonstrate value; not enough to replace paid tier. + +Capacity dimensions. + +- Use volume. Number of items, queries, exports per month. +- Capacity. Storage, seats, integrations. +- Feature set. Specific features paid only. +- Support level. Self-serve only on free; live support on paid. +- Branding. Free tier shows brand; paid removes. + +Design discipline. Free tier should let users hit the ah-ha moment; paid tier should be necessary for sustained or scaled use. Too generous: users do not convert. Too constrained: users do not reach ah-ha. + +--- + +## Trial period length + +For free-trial, how long. + +Common periods. + +- 7 days. Aggressive; works when ah-ha moment is clear and quick. +- 14 days. Common B2B; balances time-to-value with urgency. +- 30 days. Generous; works for products with longer evaluation cycles. +- 60+ days. Rare; usually reflects enterprise sales cycles. + +Decision factors. + +- Time-to-value of the product. +- Audience evaluation cycle. +- Conversion rate by trial length (test if uncertain). + +--- + +## Free-tier maintenance + +Free-tier structures decay. + +What decays. + +- Capacity limits set years ago no longer match current product capability. +- Features moved between tiers without comprehensive update. +- Audience composition shifted; old free-tier no longer fits. + +Maintenance cadence. Quarterly review of free-tier structure alongside pricing review. + +The decay-driven redesign. When refinements have not moved conversion, the free-tier structure may need redesign. + +--- + +## Common free-tier failures + +Free-tier too generous. Users get everything they need; conversion never starts. + +Free-tier too constrained. Users do not reach value; churn before conversion. + +Trial too short. Users do not reach ah-ha moment; trial ends with low conversion. + +Trial too long. Conversion incentive weak; users defer decision. + +Wrong free-tier structure for audience. Freemium chosen for enterprise audience that wanted no-free; adoption suffers. + +No maintenance. Free-tier static; conversion declines as product evolves. + +--- + +## Methodology-level choices that stay in the public skill + +The free-tier decision matters principle. Patterns A through E. Choice criteria. Free-tier capacity design. Trial period length. Maintenance considerations. Common failures. + +## Implementation choices that stay internal + +Specific free-tier structures for specific products. Specific capacity limits. Specific trial lengths. The team's pricing review calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md new file mode 100644 index 0000000..a08b9ea --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/paywall-presentation-patterns.md @@ -0,0 +1,293 @@ +# Paywall presentation patterns + +Modal, banner, inline, toast. Copy and value-prop discipline. + +How the paywall surfaces. Done well, the presentation matches the trigger's intensity; done poorly, presentation fights the trigger and conversion suffers. + +--- + +## The presentation-matches-trigger principle + +Strong triggers warrant prominent presentation; soft triggers warrant subtle presentation. + +The win. A user hits a capacity limit; a modal surfaces explaining the limit and offering upgrade. The modal is justified because the trigger is hard (the user cannot continue without resolving). The user accepts the interruption. + +The fail. Same user, soft trigger (general awareness moment). A modal surfaces the same way. The interruption is not justified by the trigger; user resents. + +The discipline. Match presentation intensity to trigger strength. + +--- + +## Pattern A: Modal paywall + +Full-screen overlay blocks the action. + +How it works. + +- Modal overlay appears. +- User must engage (upgrade) or dismiss to continue. +- Often blocks the action that triggered it. + +Strengths. + +- Highest visibility. +- Clear demand for attention. +- Works for hard triggers (capacity hit, feature gate). + +Weaknesses. + +- Most disruptive. +- Easily abused; produces annoyance. + +When to use. Hard triggers where the user cannot proceed without resolution. + +--- + +## Pattern B: Banner paywall + +Persistent banner at top of page. + +How it works. + +- Banner remains visible across pages. +- Often dismissable for the session. +- Soft prompt; does not block action. + +Strengths. + +- Persistent awareness without blocking. +- Reaches users who have not hit hard triggers. + +Weaknesses. + +- Visual noise; users develop blindness. +- Cumulative exposure can feel like spam. + +When to use. Awareness campaigns. Use sparingly; persistent banners abused become noise. + +--- + +## Pattern C: Inline paywall + +Upgrade ask embedded in the surface where the trigger occurred. + +How it works. + +- Paywall content appears within the workflow. +- User reads in context; can act or scroll past. +- No overlay; no modal. + +Strengths. + +- Contextual; integrated with the workflow. +- Non-disruptive. +- Respectful of user momentum. + +Weaknesses. + +- Easier to miss. +- May not produce conversion if too easy to ignore. + +When to use. Soft triggers; awareness without interruption. + +--- + +## Pattern D: Toast or notification + +Brief paywall surfaced as a notification. + +How it works. + +- Small notification appears (often corner of screen). +- Auto-dismisses after time or on click. +- Brief content. + +Strengths. + +- Lightest weight. +- Easy to dismiss. + +Weaknesses. + +- Easy to miss entirely. +- Limited content. + +When to use. Soft prompts; low-priority awareness. + +--- + +## Pattern E: Hybrid + +Combining patterns. + +Common combinations. + +- Modal for hard triggers + inline for soft triggers. +- Banner for awareness + modal at hard trigger moments. +- Inline for in-feature prompts + modal at capacity limits. + +The hybrid discipline. Each presentation has a clear role; users do not see overlapping or competing paywalls. + +--- + +## Choice criteria + +Which presentation fits which trigger. + +Use modal when: + +- Trigger is hard (cannot proceed without resolution). +- Capacity limit reached. +- Feature gate hit. + +Use inline when: + +- Trigger is contextual but soft. +- User can continue without resolving. +- Workflow integration is the priority. + +Use banner when: + +- Awareness campaign across pages. +- Soft prompt for users who have not hit hard triggers. + +Use toast when: + +- Low-priority awareness. +- Brief acknowledgment. + +The simplest pattern that matches the trigger is usually right. Most upgrade flows benefit from inline + occasional modal. + +--- + +## Copy and value-prop discipline + +What the paywall says. + +The principle. Paywall copy should connect to what the user just did and what they get next. + +Strong copy patterns. + +- "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [advanced capabilities]." +- "You have hit your free tier's [capacity]. Upgrade to expand to [paid capacity]." +- "Inviting teammates requires our [team plan]. Upgrade to invite up to [number] teammates." + +What works: specific connection to user action; specific value of upgrade. + +Weak copy patterns. + +- "Upgrade for more features." (Generic; no connection.) +- "Get the full experience." (Vague; no specifics.) +- "Don't miss out." (FOMO without value.) + +What fails: no connection to user behavior; no specific value-prop. + +--- + +## Plan presentation in paywalls + +Showing the upgrade options. + +Single-plan paywall. One upgrade option presented. Simple; clear. + +When to use. When the upgrade is unambiguous (capacity hit; one obvious path). + +Multi-plan paywall. Two or three upgrade options presented (e.g., Pro vs Enterprise). + +When to use. When multiple plans could fit; let the user choose. + +Presentation discipline. + +- Highlight the recommended plan. +- Make pricing clear. +- Make value differences clear. + +Anti-pattern. Showing 5 plans in a paywall. Decision paralysis; user does not choose. + +--- + +## Pricing presentation + +How prices appear. + +Per-month vs per-year. Default to the user's likely commitment level; offer the alternative. + +Price anchoring. Show what the upgrade saves vs equivalent value (use carefully; can feel manipulative). + +Currency and locale. Match the user's locale. + +Discounts. Surface honest discounts (annual discount, promotion). Avoid fake urgency. + +--- + +## Action design + +The buttons and CTAs. + +Primary CTA. "Upgrade to Pro" with specific plan name. Bold; visible. + +Secondary CTA. "Maybe later" or "See plans." Allows decline without forcing. + +No third option. Two paths (upgrade or decline) preferred. Three or more paths confuse. + +The decline-respect principle. "Maybe later" should respect the decline. The same paywall should not re-fire immediately. + +--- + +## Paywall as opportunity to communicate value + +Even when the user declines, the paywall is a touchpoint. + +The principle. Paywall copy explains what paid offers in concrete terms. Even users who decline understand more about the paid plan than they did before. + +Why this matters. Future trigger moments find users with more context. The decline today may convert next month because the value is now understood. + +--- + +## Paywall analytics + +Track the paywall's performance. + +Metrics. + +- Display rate (how often does it surface?). +- Click rate (how many engage with upgrade button?). +- Conversion rate (of clicks, how many complete upgrade?). +- Decline rate (how many dismiss?). +- Re-show rate per declined paywall. + +Diagnostic uses. + +- High display, low click: copy or value-prop weak. +- High click, low conversion: friction in upgrade flow downstream. +- High decline rate: trigger may be wrong, or copy unclear. + +--- + +## Common presentation failures + +Wrong presentation for trigger. Modal on soft trigger; inline on hard trigger. + +Generic copy. Paywall does not connect to user behavior. + +Plan paralysis. Too many options in the paywall. + +Hidden price. User has to dig to find the cost. + +Decline ignored. Same paywall re-fires immediately after dismiss. + +Cumulative exposure. User sees too many paywalls per session. + +Mobile-broken paywall. Modal on mobile blocks all interaction. + +Loading delay. Paywall takes time to appear; user has moved on. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation-matches-trigger principle. Patterns A through E. Choice criteria. Copy and value-prop discipline. Plan presentation. Pricing presentation. Action design. Paywall as value communication. Paywall analytics. Common failures. + +## Implementation choices that stay internal + +Specific paywall designs for specific products. Specific copy in brand voice. Specific tooling. The team's analytics dashboards. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md new file mode 100644 index 0000000..da29b03 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/plan-structure-patterns.md @@ -0,0 +1,240 @@ +# Plan structure patterns + +Tier count, feature gating, audience-fit per tier. + +The plans the upgrade flow leads to. Done well, plan structure makes upgrade decisions clear; done poorly, plan structure produces decision paralysis or upgrade-then-downgrade churn. + +--- + +## The clear-tier-fit principle + +Each tier should have a clear "this is for [audience] because of [reason]." Tiers without clear audience-fit produce weak conversions. + +The win. A SaaS analytics product has 3 tiers. Starter ("solo analysts and small teams"), Growth ("10-50 person analytics teams"), Enterprise ("complex analytics needs at scale"). Each tier maps to a specific audience; users self-select by recognizing themselves. + +The fail. Same product has 3 tiers labeled Bronze, Silver, Gold with feature checkmarks. Audiences cannot tell which is for them; many pick the wrong tier; downgrade rates climb. + +The discipline. Each tier has clear audience-fit articulated. + +--- + +## Tier count + +How many tiers. + +2-tier (Free + Paid). + +How it works. Free for some users, paid for everyone else. + +Strengths. Simple; clear upgrade path. + +Weaknesses. Cannot capture enterprise-tier revenue; cannot serve segmented audiences differently. + +When to use. Single-audience products; products with limited feature differentiation. + +3-tier (Starter + Pro + Enterprise). + +How it works. Three plans serving three audiences. + +Strengths. Captures entry-level, mid-market, and enterprise. Industry-standard. + +Weaknesses. Requires clear audience differentiation; can create decision paralysis if audiences are not clear. + +When to use. Most B2B SaaS products. Default for products with diverse audiences. + +4+ tier. + +How it works. Four or more plans. + +Strengths. Highly granular; serves many audiences. + +Weaknesses. Decision paralysis; users cannot tell which tier fits. + +When to use. Rarely. Most products do better with 3 tiers and add-ons rather than 4+ tiers. + +The simplest tier count that fits the audience is usually best. + +--- + +## Feature gating patterns + +How features differ between tiers. + +Pattern A: Capacity-based gating. + +How it works. All tiers have most features; tiers differ in volume (seats, queries, storage). + +Strengths. Clear upgrade trigger when capacity hit. Easy to understand. + +Weaknesses. Encourages users to optimize against limits. + +When to use. Products where capacity is the key cost driver. + +Pattern B: Feature-based gating. + +How it works. Lower tiers missing specific features; higher tiers unlock them. + +Strengths. Clear value differentiation between tiers. + +Weaknesses. Feature gating can feel arbitrary; users may want one paid feature but not the rest. + +When to use. Products with clearly tiered feature sets (basic vs advanced vs enterprise). + +Pattern C: Hybrid gating. + +How it works. Both capacity and features differ between tiers. + +Strengths. Most flexibility; serves diverse audiences. + +Weaknesses. More complex to communicate; feature comparison tables get long. + +When to use. Default for production B2B SaaS; most products benefit from hybrid. + +Pattern D: Service-based gating. + +How it works. Tiers differ in service level (support, onboarding, SLA). + +Strengths. Aligns with enterprise expectations. + +Weaknesses. Service costs scale with tier. + +When to use. Often for top tier (Enterprise); rarely the only differentiation. + +--- + +## Plan naming + +What to call the plans. + +Audience-named plans. "For solo creators," "For growing teams," "For enterprise." + +Strengths. Self-selecting; users know which fits. + +Weaknesses. Audience names age; "for startups" can feel limiting. + +Tier-named plans. "Starter," "Pro," "Enterprise" or "Basic," "Pro," "Premium." + +Strengths. Industry-standard; users recognize. + +Weaknesses. Generic; does not differentiate from competitors. + +Outcome-named plans. "Build," "Grow," "Scale." + +Strengths. Aspirational; aligns with user goals. + +Weaknesses. Vague; users may not know which outcome describes them. + +The discipline. Names should be specific enough that users self-select correctly. + +--- + +## Pricing structure + +How prices map to tiers. + +Per-seat. Cost scales with team size. + +When to use. Team collaboration products. + +Per-feature. Cost scales with feature set. + +When to use. Modular products. + +Per-usage. Cost scales with use volume. + +When to use. Capacity-driven products. + +Flat per-tier. Each tier has fixed price regardless of usage. + +When to use. Predictable-budget audiences (often enterprise). + +Hybrid pricing. Combinations of the above. + +When to use. Most production products use hybrid (per-seat with usage caps; flat tier with feature differences). + +--- + +## Annual vs monthly + +Commitment options. + +Monthly. Lower commitment; higher friction at cancellation; users can leave easily. + +Annual. Higher commitment; usually discounted; reduces churn but requires upfront payment. + +Both offered. Most products offer both; annual discount incentivizes commitment. + +Discipline. Discount on annual should reflect real value to the company (lower churn, predictable revenue) rather than arbitrary marketing percent-off. + +--- + +## Plan transition design + +How users move between plans. + +Free to paid. First commitment. Smooth experience matters most. + +Tier upgrade (within paid). From Pro to Enterprise. Often involves billing transition. + +Downgrade (within paid). From Enterprise to Pro. Should be friction-low to maintain trust; aggressive downgrade prevention damages trust. + +Cancellation to free. Some products auto-downgrade on cancellation; others fully cancel. Each has tradeoffs. + +The transitions should be smooth. Friction at transition damages trust. + +--- + +## Pricing-page coordination + +Plan structure decisions reflect on the pricing page. + +The principle. Plan structure decisions made for the upgrade flow appear on the pricing page. Users should see consistent information. + +The integration. Pricing-page copy (covered by `landing-page-copy`) implements the plan structure decisions made here. The two skills coordinate. + +--- + +## Plan maintenance + +Plans decay. + +What decays. + +- Capacity limits set years ago no longer match product capability. +- Features moved between tiers over time without comprehensive update. +- Pricing levels no longer match market. +- Tier audiences shifted. + +Maintenance cadence. Annual review at minimum; major product or market changes trigger more frequent. + +The decay-driven redesign. When plan structure no longer reflects reality, redesign rather than patch. + +--- + +## Common plan structure failures + +Too many tiers. Decision paralysis; users pick wrong tier. + +Tiers without clear audience-fit. Generic names without differentiation. + +Misaligned pricing. Prices that do not reflect value differences between tiers. + +Feature gating arbitrary. Features gated based on what is easy rather than what audiences need. + +No annual discount. Users default to monthly; cumulative revenue lower. + +Aggressive downgrade prevention. Users want to downgrade; friction damages trust. + +Plans not updated. Pricing or tiers from years ago no longer fit current product or market. + +Pricing-page mismatched. Plans on the page differ from plans in the upgrade flow. + +--- + +## Methodology-level choices that stay in the public skill + +The clear-tier-fit principle. Tier count guidance. Feature gating patterns A through D. Plan naming patterns. Pricing structure patterns. Annual vs monthly. Plan transition design. Pricing-page coordination. Plan maintenance. Common failures. + +## Implementation choices that stay internal + +Specific plans for specific products. Specific feature gating decisions. Specific pricing levels. Specific naming conventions. The team's pricing review calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md b/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md new file mode 100644 index 0000000..7b4af5d --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/trigger-moment-design.md @@ -0,0 +1,217 @@ +# Trigger-moment design + +Where paywalls earn their interruption. Strong vs weak trigger moments. + +The single most consequential decision in upgrade flow design. Paywalls surface at moments where the user has demonstrated they are getting value. Get this wrong and conversion suffers regardless of paywall design quality. + +--- + +## The earned-interruption principle + +Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +The win. User has used a feature 50 times. Hits the 50th-use limit. Paywall surfaces: "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [related advanced capabilities]." The trigger is fresh; the value is demonstrated; the user is positioned to say yes. + +The fail. Same user. Paywall surfaces on first login: "Upgrade for more features." User has not yet demonstrated value; the upgrade ask is premature; user dismisses. + +The discipline. Paywalls earn their interruption by connecting to recent demonstrated value. + +--- + +## Strong trigger moments + +Patterns that recur across products. + +Usage threshold reached. + +How it works. User has used a feature N times in a period. Further use requires paid plan. + +Why it works. The user clearly values the feature. The threshold is predictable; the paywall is honest about the constraint. + +Capacity limit hit. + +How it works. User reached free-tier capacity (storage, seats, queries). Upgrade unlocks more. + +Why it works. User encountered an unambiguous block. The block is part of the free-tier promise; the upgrade is the resolution. + +Advanced feature attempted. + +How it works. User clicked into a feature that requires paid plan. + +Why it works. Interest is fresh; the user wanted this specific feature. Upgrade ask connects to the specific interest. + +Workflow completed successfully. + +How it works. User completed an action that produced visible value (saved view, exported result, completed flow). Upgrade ask connects continuing or expanding that value to paid plan. + +Why it works. Value is fresh; user just experienced what the product does. Upgrade frames continuation. + +Team-collaboration moment. + +How it works. User wants to invite teammates; team capabilities require paid plan. + +Why it works. The collaboration intent is concrete; team capabilities are a clear value extension. + +Time-trial ending. + +How it works. Trial-based products surface upgrade as trial nears end. + +Why it works. Predictable; user expected it; the conversion conversation is timely. + +Multi-session usage. + +How it works. User has returned multiple times; engagement signal strong; soft upgrade prompt. + +Why it works. The user has demonstrated commitment through return; soft prompt fits. + +--- + +## Weak trigger moments + +Patterns that fail. + +First-login paywall. + +The pattern. Upgrade ask on first login. + +Why it fails. User has not yet seen value; the ask is premature. + +Random in-product placement. + +The pattern. Persistent paywall on the dashboard with no specific trigger. + +Why it fails. Not connected to user behavior; users develop blindness. + +Every-page banner. + +The pattern. Persistent upgrade banner across all surfaces. + +Why it fails. Visual noise; users learn to ignore. + +Paywall on the action the user expected free. + +The pattern. User believed a feature was free (because of marketing or onboarding); paywall surfaces when they try to use it. + +Why it fails. Trust damage. The user feels deceived. + +Paywall on irrelevant moments. + +The pattern. Paywall surfaces during user actions unrelated to the paid feature. + +Why it fails. Confusing; user does not connect the ask to anything. + +Paywall right after an error. + +The pattern. User just had a bad experience; immediately gets an upgrade ask. + +Why it fails. Tone-deaf; trust degrades. + +--- + +## Trigger moment design discipline + +Designing each trigger. + +Step 1: Identify the demonstrated value. What did the user just do that demonstrates value? + +Step 2: Identify the connection to paid. How does the paid plan extend or continue that value? + +Step 3: Time the ask. When in the user's flow does the ask land cleanly without breaking momentum? + +Step 4: Match presentation to importance. Strong triggers warrant modal; soft triggers inline. + +Step 5: Plan the response paths. What if user accepts? Declines? Asks for info? Each path designed. + +The output is a trigger moment that the user perceives as fair. + +--- + +## Trigger frequency + +How often paywalls fire. + +Per-trigger. A specific trigger should not fire repeatedly. Once it has fired and been declined, give space before re-asking. + +Cumulative session frequency. Total paywall exposures per session capped (often 1-2). Beyond that, additional triggers defer. + +Per-week. For users who use the product frequently, weekly cap prevents fatigue. + +The over-trigger trap. Each individual trigger looks reasonable; cumulative exposure is annoying. + +--- + +## Personalized trigger logic + +Different users may warrant different triggers. + +Power-user vs new-user. Power users may have different trigger thresholds; new users may need more time. + +Plan tier. Free users see free-to-paid triggers; paid users see paid-to-higher-paid triggers. + +Engagement frequency. Daily active vs returning monthly may warrant different timing. + +The discipline. Personalize where data justifies; do not over-segment. + +--- + +## Trigger testing + +Test triggers before launching. + +Test cases. + +- New user encounters trigger: appropriate timing? +- Returning user encounters trigger: re-fire respect? +- Power user encounters trigger: relevant? +- User who declined trigger encounters again: respectful? + +Production monitoring. + +- Per-trigger fire rate. +- Per-trigger conversion rate. +- Decline rate per trigger. +- Cumulative session exposure. + +The data informs which triggers earn their place and which should be retired. + +--- + +## Trigger maintenance + +Triggers decay. + +What decays. + +- Thresholds set years ago no longer match current usage patterns. +- Features the trigger references have changed or been deprecated. +- Audience composition shifted; old triggers no longer fit. + +Maintenance cadence. Quarterly review. Triggers that fire too often, too rarely, or with low conversion warrant attention. + +--- + +## Common trigger-moment failures + +Premature triggers. Asking before value is demonstrated. + +Unconnected triggers. Paywall not tied to the user's recent action. + +Over-frequent triggers. Cumulative exposure becomes noise. + +Stale triggers. Threshold values set long ago no longer match usage. + +Mistimed triggers. Right concept, wrong moment in the user's flow. + +Triggers right after errors. Tone-deaf placement after frustration. + +Triggers that violate free-tier promise. Asking the user to pay for something they were told was free. + +--- + +## Methodology-level choices that stay in the public skill + +The earned-interruption principle. Strong trigger moments (7 patterns). Weak trigger moments (6 patterns). Trigger moment design discipline. Trigger frequency. Personalized trigger logic. Trigger testing. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific triggers for specific products. Specific thresholds. Specific tooling. The team's audit calendar. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md new file mode 100644 index 0000000..3c9cb48 --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md @@ -0,0 +1,212 @@ +# Upgrade flow anti-patterns + +The patterns that look like upgrade flows but degrade trust. Easy to ship; the cost shows up in conversion, retention, and brand reputation. + +--- + +## The paywall-everywhere flow + +The pattern. Paywall blocks meaningful product use; free tier too constrained. + +The signal. Users churn before reaching value; conversion stays low despite aggressive paywalling. + +The cost. Users who would have paid after seeing value never reach it. + +The cure. Loosen the free tier; surface paywalls at moments of demonstrated value. + +--- + +## The free-forever-trap flow + +The pattern. Generous free tier; no upgrade path surfaces. + +The signal. Conversion stays at single-digit indefinitely. + +The cost. Product is loved free; revenue does not follow. + +The cure. Add value-triggered paywalls. Connect upgrade to demonstrated value. + +--- + +## The premature-paywall flow + +The pattern. Paywall on first login or before value is demonstrated. + +The signal. High dismiss rate; conversion does not lift. + +The cost. Users associate the brand with hard-sell early; some leave entirely. + +The cure. Move paywalls to moments of demonstrated value. + +--- + +## The unconnected-paywall flow + +The pattern. Paywall not connected to user behavior; appears at random or on every page. + +The signal. Visual noise; users develop blindness. + +The cost. Cumulative exposure becomes spam; trust degrades. + +The cure. Tie each paywall to specific user-demonstrated value. + +--- + +## The plan-paralysis flow + +The pattern. 5+ tiers presented in upgrade flow; users cannot decide. + +The signal. Click rate on plans is even across tiers; conversion does not match interest. + +The cost. Decision paralysis prevents conversion. + +The cure. Reduce tier count to 3. Recommend a default plan based on user signals. + +--- + +## The hidden-price flow + +The pattern. Prices buried; users have to dig to find them. + +The signal. Users abandon at the price-discovery step. + +The cost. Friction at the moment of decision; users leave. + +The cure. Surface prices clearly. Hidden pricing damages trust. + +--- + +## The decline-ignored flow + +The pattern. User dismisses paywall; same paywall fires immediately. + +The signal. Users disable tours globally; complain about persistent paywalls. + +The cost. Trust degrades; users may churn from the friction itself. + +The cure. Respect declines. Wait substantial time before re-asking. + +--- + +## The aggressive-downsell flow + +The pattern. User declines primary; multiple decline-and-counter rounds; user feels pressured. + +The signal. Users associate the brand with manipulation. + +The cost. Even users who eventually convert leave with negative impressions. + +The cure. One downsell at most. Respect the second decline. + +--- + +## The bait-and-switch flow + +The pattern. User believed feature was free (because of marketing); paywall surfaces when they try to use it. + +The signal. Users complain about deception; trust collapses. + +The cost. Long-term brand damage. + +The cure. Marketing and product align on what is free. No surprise paywalls on advertised-as-free features. + +--- + +## The discount-led-win-back flow + +The pattern. Win-back discount-only; no value-prop change. + +The signal. Re-engaged users churn again; users learn to lapse for discounts. + +The cost. Reverse incentive; lapse rate rises strategically. + +The cure. Lead with value-prop change; discount sparingly. + +--- + +## The aggressive-cancellation-prevention flow + +The pattern. User wants to cancel; flow makes cancellation hard (multi-step, hidden, support-only). + +The signal. Users complain publicly; brand earns "hard to cancel" reputation. + +The cost. Long-term trust damage; sometimes regulatory issue. + +The cure. Cancellation should be as easy as signup. Friction at exit damages reputation. + +--- + +## The plan-mismatch flow + +The pattern. Tier audiences not clearly differentiated; users pick wrong plan. + +The signal. Upgrade rate looks fine; downgrade rate climbs as users realize they picked wrong. + +The cost. Churn through dissatisfaction. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit visible. + +--- + +## The post-upgrade-empty flow + +The pattern. User upgrades; nothing changes immediately. New features unlocked but not surfaced. + +The signal. Upgraded users do not engage with paid features they paid for. + +The cost. Buyer's remorse; downgrade rate climbs. + +The cure. Post-upgrade welcome; surface what changed; help users access new features immediately. + +--- + +## The aggressive-upsell flow + +The pattern. Customers paying already; upsell asks fire constantly. + +The signal. Customer fatigue; cross-sell rate drops over time. + +The cost. Existing customer relationship damaged. + +The cure. Frequency limits on upsell. Cross-sell at moments of relevance, not constantly. + +--- + +## The win-back-spam flow + +The pattern. Lapsed users get win-back outreach repeatedly without segmentation. + +The signal. Unsubscribe rate climbs; brand earns spammy reputation. + +The cost. Loses users who might have returned with better outreach. + +The cure. Segment win-back; respect non-response; abandon after reasonable attempts. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of upgrade flows. + +Audit questions per flow. + +- Are paywalls connected to demonstrated value (anti-pattern check: paywall-everywhere, premature, unconnected)? +- Is decline respected (anti-pattern check: decline-ignored, aggressive-downsell)? +- Is plan structure clear (anti-pattern check: plan-paralysis, plan-mismatch)? +- Is pricing visible (anti-pattern check: hidden-price)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does post-upgrade experience deliver (anti-pattern check: post-upgrade-empty)? +- Is win-back honest (anti-pattern check: discount-led, win-back-spam)? +- Is marketing-product alignment maintained (anti-pattern check: bait-and-switch)? + +The retire decision. Anti-pattern flows often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md b/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md new file mode 100644 index 0000000..f5497ed --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md @@ -0,0 +1,214 @@ +# Upsell vs downsell logic + +When the user does not accept the primary upgrade. Secondary paths. + +Not every user accepts the proposed upgrade. The discipline is to capture revenue from users who would pay something but not the proposed amount, while respecting users who genuinely do not want to upgrade. + +--- + +## The secondary-path principle + +When the primary upgrade is declined, secondary options may capture revenue otherwise lost. + +The win. User is offered Pro plan ($X/month). Declines. System offers Starter plan ($X/3/month). User accepts Starter. Some revenue beats no revenue. + +The fail. User declines Pro; sees no other path; remains free; revenue is zero. + +The discipline. Design secondary paths thoughtfully; do not aggressive-downsell into manipulation. + +--- + +## Pattern A: Upsell + +User on basic plan; ask them to upgrade to higher tier. + +How it works. + +- Trigger fires when user demonstrates value of higher-tier features. +- Upgrade flow surfaces with the higher plan. + +Strengths. + +- Higher revenue per converted user. +- Aligned with demonstrated value. + +Weaknesses. + +- User may not need the higher tier; conversion can be poor. + +When to use. When the user has hit limits or used features that the higher tier addresses. + +--- + +## Pattern B: Cross-sell + +User is paying; offer add-ons or related products. + +How it works. + +- Trigger fires when user shows interest in adjacent capabilities. +- Cross-sell surfaces complementary product or add-on. + +Strengths. + +- Expands revenue from existing customer. +- Often easier than acquiring new customers. + +Weaknesses. + +- Risks fatigue if cross-sells are too frequent. +- Users may feel they are being squeezed. + +When to use. When add-ons or related products genuinely fit the customer's profile. + +--- + +## Pattern C: Downsell + +User declined the higher tier; offer a smaller commitment. + +How it works. + +- User dismisses upgrade. +- Secondary paywall offers a lower-tier plan, monthly instead of annual, or smaller seat count. + +Strengths. + +- Captures revenue from users not ready for the primary plan. +- Establishes paying relationship that may upgrade later. + +Weaknesses. + +- Aggressive downsell feels manipulative. +- Users may downgrade to the lowest option even when they would have paid more. + +When to use. When the primary plan is decline-prone; downsell catches users who would pay something. + +--- + +## Pattern D: Annual-vs-monthly downsell + +User declined annual; offer monthly. + +How it works. + +- Annual plan offered first (with discount). +- Decline; monthly offered as backup. + +Strengths. + +- Some users avoid annual commitment but accept monthly. +- Captures revenue from commitment-averse users. + +Weaknesses. + +- Cumulative revenue lower. +- Can train users to expect monthly when annual was the goal. + +When to use. When annual is the desired commitment but conversion suffers from upfront cost. + +--- + +## Pattern E: Seat-count downsell + +User declined full team plan; offer single-seat upgrade. + +How it works. + +- Team plan offered first. +- Decline; single-seat upgrade offered. + +When to use. When the user's situation suggests they would value paid features for themselves but cannot commit team-wide yet. + +--- + +## Downsell discipline + +When downsell crosses into manipulation. + +Honest framing. "If Pro is more than you need, here is something that fits your team size." + +Manipulative framing. Aggressive flow that pressures the user. Multiple decline-and-counter rounds. Hidden costs. Switching plan terms after acceptance. + +The discipline. Downsell respects the decline; offers an alternative; does not pressure. + +--- + +## When NOT to downsell + +Some declines should be respected. + +The user explicitly does not want any plan. Continued upgrade asks become harassment. + +The user has signaled disengagement. Aggressive downsell on a disengaged user accelerates churn. + +The user is on a free tier that fits. Forcing an upgrade where the user is happy on free degrades trust. + +The user is in a bad moment. After an error, support ticket, or negative experience, downsell is tone-deaf. + +--- + +## Sequencing upsell, cross-sell, downsell + +In a typical flow. + +Step 1: Primary upgrade ask (matched to trigger). +Step 2 (if declined): Downsell (smaller commitment alternative). +Step 3 (if declined): Soft acknowledgment ("No problem; here is the link to plans whenever you are ready."). +Step 4 (later): Cross-sell (when the user has continued use signals). + +The flow respects each decline before re-engaging at a later moment. + +--- + +## Frequency limits across upsell/downsell + +How often these surface. + +Within session. Once primary + once downsell + soft acknowledgment. No more. + +Across sessions. Wait days or weeks before re-ask. The user's circumstances may have changed. + +Per quarter. Major upgrade pushes per quarter at most. + +--- + +## Conversion economics of upsell vs downsell + +Different patterns have different revenue dynamics. + +Upsell. Higher revenue per converted user. Lower conversion rate. + +Cross-sell. Adds revenue per existing customer. Conversion depends on fit. + +Downsell. Lower revenue per converted user. Higher conversion rate. Captures users who would otherwise stay free. + +The math question. Total revenue = (upsell rate × upsell revenue) + (downsell rate × downsell revenue) + (free-to-paid rate × paid revenue). Optimize the sum. + +--- + +## Common upsell/downsell failures + +Aggressive downsell rounds. Multiple decline-and-counter loops; user feels manipulated. + +Downsell that breaks the upsell. Users learn to decline upsell to get downsell discount. + +No downsell. Users decline primary; revenue is zero. + +Cross-sell fatigue. Customers see too many cross-sells; resent. + +Wrong sequencing. Cross-sell before user has paid first plan. + +No frequency limits. Cumulative upgrade asks become spam. + +Tone-deaf timing. Downsell after a customer support escalation. + +--- + +## Methodology-level choices that stay in the public skill + +The secondary-path principle. Patterns A through E (upsell, cross-sell, downsell, annual-vs-monthly, seat-count). Downsell discipline. When NOT to downsell. Sequencing logic. Frequency limits. Conversion economics. Common failures. + +## Implementation choices that stay internal + +Specific upsell, cross-sell, downsell flows for specific products. Specific copy. Specific tooling. The team's revenue economics modeling. These vary by team and product. diff --git a/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md b/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md new file mode 100644 index 0000000..80eb6ab --- /dev/null +++ b/dist/pi/.agents/skills/upgrade-flow-design/references/win-back-flow-patterns.md @@ -0,0 +1,240 @@ +# Win-back flow patterns + +Lapsed users, downgrades, partial-churn re-engagement. + +When users disengage, downgrade, or churn, win-back flows attempt to bring them back. Done well, win-back captures revenue from users who left due to specific (often fixable) reasons; done poorly, win-back becomes spam that confirms the user's decision to leave. + +--- + +## The respect-the-decline principle + +Users who left often left for reasons. Win-back should be honest about the reasons and offer something genuinely changed, not just a discount. + +The win. A user lapsed 60 days ago. Win-back email surfaces with: "Since you last logged in, we shipped [specific feature you mentioned wanting]. Want to try it?" The user returns; the value-prop is fresh. + +The fail. Same user. Win-back email surfaces with: "We miss you! Come back for 20 percent off." The user dismisses; the discount feels like manipulation; the previous problems remain. + +The discipline. Win-back is most effective when something has changed (new feature, fixed problem) the user would value. + +--- + +## Win-back triggers + +When to fire. + +User has not logged in for 30 days. Soft trigger; light re-engagement. + +User has not logged in for 60-90 days. Moderate trigger; more substantive re-engagement. + +User has not logged in for 6+ months. Aggressive trigger; usually the last attempt before treating as fully churned. + +User downgraded plan. Trigger surfaces post-downgrade; win-back attempts to retain the higher tier. + +User canceled but did not delete account. Soft trigger; re-engage before full churn. + +User churned and signed up again. Different trigger; usually treat as new signup with prior context. + +The triggers vary by product and audience. + +--- + +## Pattern A: Email-based win-back + +Outreach with renewed value-prop. + +How it works. + +- Email sent to lapsed user. +- Content focuses on what has changed since they left. +- May include discount or trial extension. + +Email design discipline. + +- Subject line concrete; not generic "we miss you." +- Body specific to what has changed. +- One clear CTA back to product. +- Easy unsubscribe; respect users who do not want re-engagement. + +Strengths. + +- Cheap; can scale. +- Reaches users outside the product. + +Weaknesses. + +- Easy to feel like spam. +- Email deliverability for lapsed users is harder. + +When to use. Default for lapsed-user re-engagement. + +--- + +## Pattern B: In-product upon return + +When a lapsed user returns, surface re-engagement help. + +How it works. + +- User logs in after long absence. +- In-product surfaces re-orientation and (if appropriate) upgrade-back ask. + +Design. + +- Welcome-back banner with what has changed. +- Brief tour of new features added during absence. +- Soft upgrade-back if user downgraded. + +Strengths. + +- The user has already returned; engagement is fresh. +- Can be specific to the user's prior usage. + +Weaknesses. + +- Misses users who do not return on their own. + +When to use. When email or other re-engagement has produced a return. + +--- + +## Pattern C: Personal outreach + +For high-value lapsed users, sales or customer success conversation. + +How it works. + +- Customer success or sales reach out directly. +- Often via email or call. +- Conversation about what changed for the user; what would bring them back. + +Strengths. + +- Highest engagement potential. +- Surfaces real reasons; can address them. + +Weaknesses. + +- Expensive; only viable for high-value accounts. +- Risk of harassment if not done well. + +When to use. Enterprise lapsed accounts, high-revenue lapsed customers, accounts with strategic value. + +--- + +## Pattern D: Offer-based win-back + +Discount or trial extension as primary motivator. + +How it works. + +- Offer (e.g., 30 percent off, 3 months free, extended trial) presented to lapsed user. +- Limited time; explicit terms. + +Strengths. + +- Can move users who left for cost reasons. +- Easy to implement. + +Weaknesses. + +- Can train users to lapse intentionally to get discounts. +- Discount alone does not address why they left. + +When to use. Sparingly. Combine with value-prop changes; do not lead with discount alone. + +The discount-as-only-strategy failure. Discounts to win back can create reverse incentives. If users learn that lapsing gets them discounts, lapse rate climbs strategically. + +--- + +## Win-back sequence design + +A multi-touch win-back rather than single email. + +Typical sequence. + +- Day 30: light re-engagement (what's new). +- Day 60: more substantive (specific feature; case study). +- Day 90: explicit win-back offer (if appropriate). +- Day 120: final outreach; respect non-response. +- Beyond Day 120: treat as fully churned. + +The sequence respects the user's silence; multiple touches at different intensities. + +--- + +## When to abandon win-back + +Some users genuinely do not want to come back. Respect that. + +Signals to stop. + +- User unsubscribed from emails. +- User explicitly stated they do not want contact. +- Multiple win-back attempts produced no response. +- User left for reasons unfixable by the product (changed jobs, changed needs). + +The respect-the-no principle. Continuing win-back after clear no signals is harassment. + +--- + +## Discount discipline in win-back + +When discounts make sense. + +Use discount when: + +- The user explicitly stated cost was a factor. +- The product's price has not changed but the user's situation has. +- A time-limited promotion is genuinely available. + +Avoid discount when: + +- The user left for non-cost reasons (poor experience, missing features). +- The discount would train lapse-for-discount behavior. +- The discount cannibalizes existing customer revenue. + +--- + +## Win-back analytics + +Track effectiveness. + +Metrics. + +- Re-engagement rate (lapsed users who returned after win-back outreach). +- Conversion rate (returned users who paid or upgraded back). +- Retention of returned users (do they stay or lapse again?). + +Diagnostic uses. + +- Low re-engagement: outreach not relevant or not delivered. +- High re-engagement, low conversion: returns happen but value-prop weak. +- Returns lapse again quickly: underlying issue not fixed. + +--- + +## Common win-back failures + +Generic outreach. "We miss you" with no specifics; user dismisses. + +Discount-only strategy. Discount without value-prop change; trains lapse-for-discount. + +Frequency overload. Too many win-back attempts; harassment. + +No segmentation. Same outreach to all lapsed users regardless of why they left. + +Ignoring unsubscribes. Outreach continues despite explicit no. + +No measurement. Cannot tell if win-back works. + +Returns-lapse-again. Win-back succeeds short-term; underlying issue persists; user lapses again. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-decline principle. Win-back triggers. Patterns A through D (email, in-product, personal, offer-based). Win-back sequence design. When to abandon. Discount discipline. Win-back analytics. Common failures. + +## Implementation choices that stay internal + +Specific win-back sequences for specific products. Specific outreach copy in brand voice. Specific discount levels. The team's segment-specific approaches. These vary by team and product. diff --git a/dist/pi/.agents/skills/usability-testing/SKILL.md b/dist/pi/.agents/skills/usability-testing/SKILL.md new file mode 100644 index 0000000..26f0a9e --- /dev/null +++ b/dist/pi/.agents/skills/usability-testing/SKILL.md @@ -0,0 +1,238 @@ +--- +name: usability-testing +description: "Plan and run usability tests on existing or prototype designs including test design, task scripts, moderation, observation, and findings synthesis. Use this skill whenever the user wants to test usability, run a moderated test, run an unmoderated test, validate a design, find usability issues, or improve task completion. Triggers on usability test, usability testing, moderated test, unmoderated test, task script, think aloud, prototype testing, user testing, design validation, task completion. Also triggers when the user has built something and wants to know if real users can use it before shipping." +category: research +catalog_summary: "Test design, moderation, findings reports" +display_order: 2 +--- + +# Usability Testing + +Plan and run tests that find usability problems before users hit them in production. Stack-agnostic. Tool-agnostic. + +This skill is for testing existing designs or prototypes. For broader discovery research, use `ux-research`. For conversion testing in production, use `cro-optimization`. + +--- + +## When to use + +- Before launching a new flow or major redesign +- After a redesign to verify it doesn't introduce new problems +- When analytics show drop-off but you don't know why +- When customer support tickets pattern around specific UI areas +- Pre-launch user validation +- Comparing two design directions + +## When NOT to use + +- Discovery / generative research (use `ux-research`) +- Live conversion optimization (use `cro-optimization`) +- Mapping the broader experience (use `journey-mapping`) +- Pure quantitative measurement (use `analytics-strategy`) + +--- + +## Required inputs + +- The design or prototype to test (functional or near-functional) +- Specific tasks users would do +- The audience (who should be tested) +- Testing infrastructure (moderated tool, unmoderated tool, in-person setup) + +--- + +## The framework: 5 phases + +### 1. Define what to test + +Don't test the whole product. Test specific tasks. + +Task selection criteria: + +- The task represents a real user goal (not "click around and explore") +- The task has a clear start and end +- The task is achievable in 2 to 10 minutes +- The task is one of: most common, most strategic, most problematic + +Examples of testable tasks: + +> "You want to find a contractor near you who can install a fence. Show me how you'd do that on this site." + +> "You're a first-time visitor. You want to understand if this product fits your needs. Walk me through how you'd evaluate it." + +> "Your team needs a new tool to manage projects. Use this site to figure out which plan is right for a 12-person team." + +Task framing rules: + +- State the user goal, not the system action ("find a place to stay" not "click the search button") +- Provide context (why are you doing this?) +- Don't reveal the path +- Don't use product terminology in the task framing + +### 2. Choose moderated or unmoderated + +Moderated (live, with researcher): + +- Researcher observes and probes in real time +- Best for early-stage prototypes, complex tasks, novel concepts +- Higher cost, smaller sample (5 to 8 participants typical) +- Catches surprises and probe deeper + +Unmoderated (recorded, asynchronous): + +- Participant completes alone, often via tool (UserTesting, Maze, Lookback) +- Best for stable designs, simple tasks, larger sample +- Lower cost, larger sample (15 to 30 participants typical) +- Catches patterns at scale, less depth per session + +For most teams: moderated for early/critical decisions, unmoderated for ongoing validation. + +### 3. Recruit + +Target audience - not just convenience. + +Recruit criteria: + +- Match real users (target audience, not just "anyone") +- Mix of experience levels with the product (new and existing if applicable) +- Mix of relevant device types (mobile, desktop, tablet if relevant) +- Exclude friends, family, employees + +Sample size: + +- Moderated: 5 to 8 participants (Nielsen's "5 users find 85% of usability issues" for the most common segment) +- Unmoderated: 15 to 30 participants (more participants compensate for less probing) +- Multi-segment testing: 5 to 8 per segment + +### 4. Run the test + +Pre-task setup: + +- Confirm recording works +- Brief participant (purpose, anonymity, recording, "no wrong answers") +- Get verbal consent +- Have participant share screen if remote + +Moderated session structure: + +1. Warm-up (2 to 3 min). Easy questions to put participant at ease. +2. Pre-test questions (3 to 5 min). Background context, current behavior with similar products. +3. Task 1 (5 to 10 min). Describe task. Have participant attempt while thinking aloud. +4. Post-task questions (1 to 2 min). What was easy/hard? Anything confusing? +5. Repeat for tasks 2, 3, 4 (typically 3 to 5 tasks per 60-minute session). +6. Overall debrief (5 to 10 min). General reactions, comparisons to alternatives, anything else. +7. Close (2 min). + +Moderation principles: + +- Encourage think-aloud ("What's going through your mind?") +- Don't help unless they're truly stuck (and even then, only after a long pause) +- Don't lead ("Are you looking for the menu?" - bad) +- Note where they hesitate, scroll, or backtrack +- Note their language vs the product's language +- Note emotional reactions + +Anti-patterns: + +- Talking too much (researcher should talk maybe 20% of the time) +- Defending the design when participants struggle +- Helping prematurely +- Asking participants to predict their future behavior +- Treating participant suggestions as features ("Users want X" - test demand for X separately) + +### 5. Synthesize and report + +Patterns across participants are signal. Single-participant complaints are weaker (but worth investigating). + +Synthesis steps: + +1. Issue inventory. Every issue observed, with which participant, which task, severity. +2. Cluster. Issues that are the same root problem. +3. Severity. + - Critical: Blocks task completion. Most users hit this. + - Major: Significantly slows task. Many users hit this. + - Minor: Friction. Some users hit this. Workaround exists. + - Cosmetic: Polish. Doesn't affect task. +4. Recommendations. For each issue, propose specific fixes. +5. Prioritize. By severity and effort. + +Report structure: + +```markdown +# Usability Test: [Design / flow] + +## Summary +[2 to 3 paragraphs covering: what was tested, headline findings, top 3 priorities] + +## Method +[Moderated/unmoderated, sample size, audience, dates, tasks] + +## Critical findings +[Each with description, frequency, supporting evidence (quotes/clips), recommendation] + +## Major findings +[Same structure] + +## Minor findings +[Brief] + +## Cosmetic findings +[Briefest] + +## What worked well +[Calibration: capture successes too] + +## Recommendations +[Prioritized list with effort estimates] + +## Next steps +[Test re-run schedule, design iteration plan] +``` + +--- + +## Workflow + +1. Define the goals. What decisions hinge on this? What tasks matter most? +2. Design tasks. 3 to 5 specific, realistic, goal-framed tasks. +3. Choose moderated vs unmoderated. Match to stage and depth needed. +4. Recruit. Specific to audience. +5. Pilot. 1 to 2 sessions before main batch. Refine tasks if needed. +6. Run. Follow the protocol. Stay disciplined. +7. Synthesize during, not just after. Patterns emerge by session 4 or 5. +8. Report. Multiple formats - written report + highlight clips. +9. Track fixes. Every critical issue should have an owner and date. +10. Re-test after fixes. Verify the fix worked, didn't introduce new issues. + +--- + +## Failure patterns + +- Testing the whole product instead of specific tasks. Vague results. +- Tasks that reveal the path. ("Click the menu and find...") +- Friends and family as participants. Biased, not representative. +- Researcher leading the participant. Findings reflect the researcher. +- Defending the design when participants struggle. Misses real issues. +- Helping too quickly. Participant doesn't experience the friction. +- Treating participant suggestions as features. Users solve their problem; product team designs the solution. +- One participant = data point. A single strong opinion isn't a finding. +- Skipping severity scoring. All findings treated equally; team can't prioritize. +- Reports no one reads. Highlight clips and live walkthroughs work better than 80-page decks. +- Testing once, never re-testing. Fixes that introduce new problems go undetected. + +--- + +## Output format + +Default outputs: + +1. Test plan (before testing) - `usability-test-plan-[topic].md` +2. Task script (per session) - `usability-tasks-[topic].md` +3. Findings report (after synthesis) - `usability-findings-[topic].md` +4. Highlight clips (separately produced) + +--- + +## Reference files + +- [`references/task-script-patterns.md`](references/task-script-patterns.md) - Task framing patterns by common product type, with good and bad examples. diff --git a/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md b/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md new file mode 100644 index 0000000..bcc0cd7 --- /dev/null +++ b/dist/pi/.agents/skills/usability-testing/references/task-script-patterns.md @@ -0,0 +1,315 @@ +# Task Script Patterns + +Patterns for writing usability test tasks that produce real findings rather than scripted compliance. Includes good and bad examples by common product type. + +--- + +## Universal task framing rules + +### Rule 1: State the user goal, not the system action + +\| Bad (system action) \| Good (user goal) \| +\|---\|---\| +\| "Click the search button at the top." \| "Find a place to stay in Lisbon for a weekend." \| +\| "Open the settings menu and change your password." \| "You think someone else might know your password. Update it." \| +\| "Add this product to your cart." \| "You want to buy this jacket. Walk me through purchasing it." \| + +The system-action version reveals the path. Findings tell you whether the participant could follow instructions, not whether they could use the product. + +### Rule 2: Provide motivating context + +\| Bare task \| Better with context \| +\|---\|---\| +\| "Find a hotel in Paris." \| "You're planning a 3-day trip to Paris next month for your anniversary. Find a hotel that fits." \| +\| "Sign up for an account." \| "You decided this looks promising and want to try it. Get started." \| + +Context shapes how participants approach the task. Without it, they make their own assumptions, often differently from each other. + +### Rule 3: Avoid product terminology + +\| Bad (uses our terms) \| Good (uses user's terms) \| +\|---\|---\| +\| "Create a workspace." \| "Set this up so your team can collaborate." \| +\| "Find an experience." \| "Find an activity to do this Saturday." \| + +If the participant doesn't already know the product's terminology, using it in the task gives them the answer. + +### Rule 4: Don't reveal the path + +\| Bad (path revealed) \| Good (open) \| +\|---\|---\| +\| "Use the filters to narrow the results to under $100." \| "Find something within your budget of $100." \| +\| "Click on the FAQ section to find the return policy." \| "Find out if you can return this if it doesn't fit." \| + +If the path is in the task, you're not testing whether the participant can find the path. + +### Rule 5: Make it specific + +\| Bad (vague) \| Good (specific) \| +\|---\|---\| +\| "Try out the product." \| "Find out if this product would work for tracking your team's meetings." \| +\| "Look around." \| "Walk me through how you'd evaluate whether this is right for you." \| + +Vague tasks produce vague findings. Specific tasks produce actionable findings. + +--- + +## Common pre-test framing + +Use a script for the opening so it's consistent across sessions. + +### Standard opener + +> "Thanks again for joining. As I mentioned, we're testing a [website / app / prototype]. The point is to learn from your experience, not to test you. There are no right or wrong ways to do anything. If you get confused or stuck, that's information for us, not a problem with you. +> +> A few things to know: +> 1. I'll ask you to do some tasks. As you go, please think out loud. Tell me what you're looking at, what you're thinking, what you expect to happen, what's confusing. +> 2. I won't be able to help much during the tasks. The whole point is to see how you'd use this without help. After each task, we'll talk about what was easy and what wasn't. +> 3. We're recording this session for our own notes. The recording stays internal. Sound good? +> +> Any questions before we start?" + +### Pre-task framing + +> "OK, here's the first task. Take your time, think out loud, and there's no rush. +> +> [Read the task aloud, slowly. Send it in chat if remote so they can refer back.] +> +> Go ahead and start whenever you're ready." + +### Mid-task probes (use sparingly) + +When participant is silent for a while: +> "What are you thinking?" + +When participant pauses on something: +> "What's going through your mind right now?" + +When participant takes an unexpected action: +> "What did you expect to happen there?" + +### When participant gets truly stuck + +Wait at least 30 seconds before intervening. Real frustration is signal. + +> "Take a moment. What would you typically do at a point like this?" + +Or: + +> "Is there anything you'd want to do that you're not seeing a way to do?" + +If they're still stuck after another 30 seconds, you can offer a hint: "What might happen if you scrolled?" But this is a last resort. The struggle is the data. + +### Post-task probes + +> "On a scale of 1 to 5, how easy or hard was that?" + +> "What was hardest?" + +> "What was easiest?" + +> "If you could change one thing about how that worked, what would it be?" + +### Closing + +> "Thanks for working through these tasks. Two last questions: +> +> Overall, what's your impression? +> +> If you imagine using this regularly, what would make it work for you? What might keep you from using it? +> +> Anything else you want to mention before we wrap?" + +--- + +## Task patterns by product type + +### Ecommerce + +#### Browse and discovery + +> "You're looking for a gift for a friend who loves cooking. They've been getting into making bread. You have a budget of about $75. Find something that might work." + +[Tests: navigation, search, filtering, product browsing] + +#### Specific product purchase + +> "You've decided to buy [specific product]. Walk me through purchasing it. Stop just before you'd actually enter your payment info." + +[Tests: cart flow, checkout flow, friction points] + +#### Comparison + +> "You're trying to decide between two of these products. Use the site to figure out which one is better for your needs." + +[Tests: comparison features, product pages, decision support] + +#### Returns + +> "You bought something from this store last month. It doesn't fit. Find out how to return it." + +[Tests: help center, account flows, post-purchase support] + +--- + +### SaaS / B2B + +#### Self-service evaluation + +> "You're a [role] at a 30-person company. Your team needs better [tool category]. Use this site to figure out if this is the right fit, and if so, what plan to pick." + +[Tests: positioning, value prop, pricing, evaluation flow] + +#### Onboarding (post-signup) + +> "You just signed up for an account. Walk me through what you'd do next. Try to get to the point where the product would be useful for you." + +[Tests: onboarding, time-to-value, activation friction] + +#### First key task + +> "You're new to this product. Try to [specific key action: create your first project, set up an integration, invite a teammate]. Think out loud as you go." + +[Tests: feature discovery, task completion] + +#### Existing-user task + +> "You're an experienced user of this product. You need to [specific advanced task]. Show me how you'd do that." + +[Tests: depth of features, expert workflows] + +--- + +### Marketplaces + +#### Buyer side: discovery + +> "You need someone to [service]. Find a few options that look good to you." + +[Tests: search, filters, listing pages] + +#### Buyer side: deciding + +> "You've narrowed it down to a few options. Pick the one you'd actually book and walk me through what you'd do next." + +[Tests: details pages, social proof, booking flow] + +#### Seller side: setup + +> "You [run a business / offer a service]. You're considering listing it here. Use this site to figure out how to get started." + +[Tests: onboarding, value prop for the supply side] + +#### Seller side: ongoing + +> "You're an existing seller. You want to [check on inquiries / update your availability / respond to a review]. Show me how you'd do that." + +[Tests: account management, dashboard] + +--- + +### Content / publisher + +#### Reading flow + +> "Read [specific article / topic that interests you]. As you go, tell me what's working or not working about the experience." + +[Tests: readability, page experience, ads, related content] + +#### Discovery + +> "Spend a few minutes exploring this site. Find articles that interest you. Tell me how you decide what to click." + +[Tests: navigation, recommendations, browse paths] + +#### Subscribe + +> "You've decided you want to read more from this publication. Sign up for whatever you think makes sense." + +[Tests: paywall flow, subscription page, account setup] + +--- + +### Mobile app + +#### Initial impression + +> "You just downloaded this app. Open it and start using it. Tell me what you do, what you expect." + +[Tests: app onboarding, initial value] + +#### Specific feature + +> "You want to [specific feature use]. Show me how you'd do that." + +[Tests: feature discovery, mobile-specific patterns] + +#### Push / notification flow + +> "Your phone just buzzed with a notification from this app. Show me what you'd do." + +[Tests: notification design, deep links, post-notification flow] + +--- + +## Task script common pitfalls + +### Pitfall 1: Multiple tasks in one + +> "Sign up, create a project, and invite a teammate." + +This is three tasks. Run as three separate tasks so you can score and analyze each. + +### Pitfall 2: Tasks that aren't realistic + +> "Imagine you're an enterprise CFO evaluating procurement tools." + +If the participant is not a CFO, they're roleplaying. Findings tell you about roleplay, not real CFO behavior. Recruit real CFOs or pick a different task. + +### Pitfall 3: Tasks the participant has already done + +> "Sign up for an account." +> +> Participant: "I already have one." + +Either log them out for the test, or change the task to first-time-user-feeling tasks. + +### Pitfall 4: Tasks tied to specific data the participant doesn't have + +> "Update your billing address." +> +> Participant: "I don't have an account on this site." + +Provide a test account with realistic data, or pick tasks that work for first-time users. + +### Pitfall 5: Asking about future behavior as a task + +> "Tell me what you'd pay for this." + +Hypothetical questions are weak signal. Test actual behavior (do they get to the pricing page? where do they hesitate?) and ask post-task what they'd be willing to pay if useful. + +--- + +## Severity scoring rubric + +Use after testing to score each issue. + +\| Severity \| Definition \| Example \| +\|---\|---\|---\| +\| Critical \| Most users cannot complete the task. Hard blocker. \| "5 of 6 participants gave up trying to find pricing." \| +\| Major \| Most users complete the task, but with significant struggle. \| "4 of 6 participants needed multiple tries to find the search." \| +\| Minor \| Some users hit friction. Most complete the task fine. \| "2 of 6 participants paused on the form, but all completed." \| +\| Cosmetic \| Polish issue. No effect on task completion. \| "Multiple participants noted a typo." \| + +Critical and Major issues block ship. Minor issues prioritize on cost/benefit. Cosmetic gets fixed in normal iteration. + +--- + +## Reporting tips + +- Lead with the most surprising finding, not the easiest fix +- Include at least one quote per major finding (specifics persuade) +- Include video clips for critical findings (no document beats seeing it) +- For each finding, include both the issue and the recommended fix +- Sort by severity, not by section of the product +- Make it scannable. Stakeholders skim. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md b/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md new file mode 100644 index 0000000..0336049 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/SKILL.md @@ -0,0 +1,302 @@ +--- +name: user-feedback-aggregation +description: "Collecting and synthesizing user feedback across channels (support tickets, NPS, in-app feedback, sales calls, social mentions, customer councils) into a continuous signal that informs product decisions. The triage discipline that distinguishes loudest-voice (whoever complains most wins) from averaged-noise (every signal weighted equally) from triaged-synthesis (signal weighted by source quality, frequency, and decision relevance). Triggers on user feedback, customer feedback aggregation, NPS, support ticket analysis, customer councils, feedback synthesis, voice of customer, feedback triage, in-app feedback. Also triggers when feedback channels overflow with volume that does not produce decisions, when the loudest-voice problem is steering roadmap, or when continuous feedback streams need synthesis discipline." +category: research +catalog_summary: "Collecting and synthesizing user feedback across channels into continuous decision signal. Triage discipline that distinguishes loudest-voice (whoever complains most) from averaged-noise (every signal weighted equally) from triaged-synthesis (weighted by source quality and decision relevance)" +display_order: 5 +--- + +# User Feedback Aggregation + +A senior product leader's playbook for collecting and synthesizing user feedback across channels into continuous decision signal. Support tickets, NPS surveys, in-app feedback, sales calls, social mentions, customer councils, all aggregated into a triaged synthesis the team can actually act on. + +Most product programs accumulate feedback they do not use. Channels overflow with submissions; CSAT and NPS scores get reported in monthly updates; customer council meetings produce notes that nobody references. The loudest voices steer roadmap because they are easiest to hear; quieter signal that matters more goes unaddressed. + +This skill is the triage discipline that turns continuous feedback streams into continuous decision signal. Each channel surfaces different signal at different reliability. Each signal type warrants different weight in different decisions. The team that aggregates feedback well makes better decisions; the team that drowns in feedback makes the same decisions they would have made without the feedback. + +Different from `discovery-research-synthesis`, which covers one-off research projects (a defined batch of artifacts, a defined synthesis output). This skill covers the always-on streams: feedback that arrives every day, every week, every month, and that the team must continuously triage and synthesize. + +The voice is the senior product leader who has watched feedback aggregation work and watched it fail. Concrete, opinionated about which channels matter for which decisions, willing to call out where loudest-voice or averaged-noise patterns produce bad outcomes. + +When to use this skill: building a feedback aggregation system, auditing a feedback program that is producing volume without decisions, deciding which feedback channels matter for the program, or designing the synthesis cadence for ongoing feedback streams. + +--- + +## What this skill is for + +This skill spans continuous user-feedback aggregation. The PM-skill distinction: + +- `discovery-research-synthesis` is one-off discovery research. Defined batch, defined output. +- `user-feedback-aggregation` (this skill) is ongoing feedback streams. Always-on channels needing continuous synthesis. +- `beta-program-management` covers feedback specific to beta participants. This skill spans all users continuously. +- `ux-research` is structured research projects. This skill is unsolicited feedback. +- `pm-spec-writing` is downstream: specs use feedback aggregation as input. +- `roadmap-planning` is downstream: roadmap uses feedback patterns as input. + +The audience: senior PMs, product directors, customer success and support managers running feedback programs, in-house teams aggregating feedback across many channels. + +What is not in scope: structured discovery research (covered by `discovery-research-synthesis`); beta-specific feedback (covered by `beta-program-management`); commissioned research projects (covered by `ux-research`). + +--- + +## Loudest-voice vs averaged-noise vs triaged-synthesis + +The keystone framing. + +Loudest-voice. Whoever complains the most gets their feature. Vocal minorities steer roadmap. Silent majority's needs go unaddressed. The squeaky-wheel anti-pattern. Cost: the program optimizes for the loudest customer, not for the broader customer base; quieter customers leave for products that addressed their needs. + +Averaged-noise. Every signal weighted equally. 1 enterprise customer's feedback = 1 trial user's feedback = 1 angry social mention. Volume aggregates without weighting; noise drowns signal. Cost: the team cannot tell which feedback matters; decisions get made on aggregate sentiment that does not reflect the customers who matter most for the strategy. + +Triaged-synthesis. Signal weighted by source quality, frequency, and decision relevance. Different feedback types have different weights for different decisions. The team that does this well makes decisions grounded in the signal that matters; the team that does it badly defaults to loudest-voice or averaged-noise. + +The litmus test. Pick a recent product decision. Can the team explain why specific feedback signals weighted into the decision the way they did? If yes, the aggregation is triaged. If the answer is "we heard a lot about this from customers," without specificity about which customers in which contexts, the aggregation is loudest-voice or averaged-noise. + +--- + +## Feedback channels and what each surfaces + +Six common channels. Each surfaces different signal at different reliability. + +Support tickets. What users hit when things break or confuse them. High volume, high signal-on-friction, biased toward users willing to contact support. + +NPS surveys. Aggregate sentiment toward the product or specific features. Periodic, quantitative-with-comments, bias toward respondents who feel strongly (positive or negative). + +In-app feedback. Friction at the moment users encounter it. Contextualized to specific product moments; volume varies; quality varies. + +Sales calls. Pre-purchase prospect perspective. Objections, competitive mentions, gaps between marketing and what sales leads with. Bias toward prospects, not existing customers. + +Social mentions. Public commentary about the product. Real-time but biased toward customers willing to post publicly; often skews negative or hyper-positive. + +Customer councils. Curated panels of customers in structured forums. High-quality feedback from selected customers; bias depends on selection. + +Each channel has strengths and weaknesses. Strong feedback aggregation triangulates across channels rather than relying on one. + +Detail in [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md). + +--- + +## Channel-source weighting + +The discipline that distinguishes triaged-synthesis from averaged-noise. + +The principle. Different sources warrant different weights in different decisions. + +Worked example. A decision about whether to prioritize an enterprise admin feature. + +- Sales call data showing enterprise prospects asking for the feature: high weight (the decision is about enterprise; the source matches). +- Support ticket data from enterprise customers: high weight (existing enterprise customers' friction is directly relevant). +- NPS data from small-team customers: low weight (the feature is not for them; their satisfaction is not load-bearing for the decision). +- Social mentions: variable weight (signal depends on who is mentioning; enterprise practitioners on LinkedIn carry more weight than anonymous trial users on social). + +The discipline. For each decision, identify which sources matter most. Weight accordingly. Volume from low-weight sources should not override signal from high-weight sources. + +The averaged-noise failure. Decisions made on aggregate volume regardless of source. The enterprise admin feature gets deprioritized because more total feedback came from small-team customers who do not need it; enterprise customers churn because their needs went unaddressed. + +Detail in [`references/channel-source-weighting.md`](references/channel-source-weighting.md). + +--- + +## Categorization and tagging discipline at scale + +How feedback gets organized when it arrives at high volume. + +The taxonomy. + +- Feature area or product surface (where in the product the feedback applies). +- Issue type (bug, friction, feature request, positive signal, edge case). +- User segment (who is providing the feedback). +- Severity or urgency (how blocking is it for the user). +- Source channel (where the feedback came from). + +The discipline. + +- Tags emerge from feedback patterns, not from a pre-built taxonomy. +- Tags get refined over time as patterns clarify. +- Multiple tags per feedback item; do not force single-category. +- Periodic taxonomy review surfaces categories that need to merge or split. + +The volume challenge. A program receiving 500-2000 feedback items per week needs aggregation tooling that supports tagging at scale. Manual tagging at scale burns out the team; AI-assisted tagging with human review on patterns is often the practical middle path. + +Detail in [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md). + +--- + +## Frequency vs intensity + +Two dimensions of feedback signal. + +Frequency. How often the same feedback recurs. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +Intensity. How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive, or describe satisfaction as transformative. +- Low-intensity feedback: minor friction or mild satisfaction. + +The matrix. + +- High-frequency, high-intensity: top priority. Many users hit this; it matters to them. +- High-frequency, low-intensity: papercuts. Address in batches; individual items are minor but cumulatively erode experience. +- Low-frequency, high-intensity: the affected users are deeply impacted but few. Often segment-specific. +- Low-frequency, low-intensity: noise. Capture; do not action individually. + +The discipline. Triage assigns each piece of feedback a frequency-intensity assessment. The combination informs prioritization weight. + +Detail in [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md). + +--- + +## From feedback to product decision + +The synthesis loop that turns aggregated feedback into roadmap input. + +The loop. + +- Feedback arrives across channels. +- Triage categorizes and weights. +- Periodic synthesis (weekly, monthly, quarterly) surfaces patterns. +- Patterns inform roadmap discussions, spec drafts, prioritization debates. +- Decisions reference specific feedback patterns as input. + +The cadences. + +- Daily: critical feedback (security, data loss, broken core flows) handled immediately. +- Weekly: team review of recent patterns. Adjusts current-quarter execution. +- Monthly: synthesis review. Surfaces trending patterns; informs next-quarter roadmap. +- Quarterly: strategic synthesis. Patterns over the quarter inform strategic planning. + +The discipline. Feedback aggregation has cadence. Without cadence, feedback accumulates without producing decisions. + +Detail in [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md). + +--- + +## Closing the loop with users + +When feedback shapes product, telling users matters. + +The practice. + +- When feedback drives a change, communicate to the users who provided that feedback. +- "We heard from many of you that X was painful; we shipped Y this week to address it. Thanks for the feedback that informed this work." +- Communication can be public (release notes, blog posts) or targeted (email to users who opened tickets on the issue). + +Why it matters. + +- Users who see their feedback acted on engage more in the future. +- The closed loop signals that the team is listening, which strengthens the relationship. +- Users without feedback follow-through stop providing feedback over time. + +The risk of over-promising. Promising changes that do not ship erodes trust faster than not promising. Communicate what shipped, not what might ship. + +Detail in [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md). + +--- + +## Detecting drift in feedback patterns over time + +What changes in feedback signal over time can reveal. + +Drift patterns. + +- Increasing feedback volume in a category: either the issue is worsening, the user base is growing, or awareness of the channel is increasing. Investigate the cause. +- New patterns emerging: previously-rare feedback becomes more common. Often signals product or market change. +- Patterns disappearing: feedback that used to be common stops. The issue may be resolved, or users may have given up reporting it. +- Sentiment shifts: NPS or CSAT trending differently than before. Often signals broader experience changes. + +The investigation discipline. Drift signals warrant investigation. Why did the volume increase? Why did this pattern emerge? The root cause often informs product decisions more than the surface signal. + +Detail in [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md). + +--- + +## Feedback aggregation tooling considerations + +Tooling choices without endorsing specific products. + +Tooling categories. + +- Customer feedback platforms (aggregate across multiple sources, support tagging, surface patterns). +- Support ticket systems with analytics layers. +- NPS or survey platforms with response aggregation. +- Customer relationship management systems with feedback fields. +- Custom dashboards combining feedback signal with usage analytics. + +The criteria for tooling selection. + +- Does it support multi-channel aggregation, or is it single-channel? +- Does it support tagging at scale? +- Does it surface patterns, or is it just storage? +- Does it integrate with the team's other systems (roadmap, ticketing, communication)? +- Does it scale with program volume? + +The build-vs-buy tension. Many programs end up with a mix: dedicated tooling for some channels, custom dashboards for cross-channel synthesis. Pure single-tool solutions often miss the multi-channel pattern detection. + +Detail in [`references/tooling-considerations.md`](references/tooling-considerations.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md). + +- "Loudest customers steer the roadmap." Loudest-voice pattern; vocal minorities dominate; silent majority underaddressed. +- "We have lots of feedback but no decisions." Aggregation without synthesis; no triage cadence. +- "Our channels overflow; we cannot keep up." Aggregation without weighting or tooling that scales. +- "Different teams cite different feedback for the same decision." Channel-source weighting absent; teams reach for whatever feedback supports their position. +- "Customer council meetings produce notes nobody references." Council without synthesis loop; the meeting is the deliverable. +- "NPS is reported monthly but does not inform decisions." NPS as compliance metric, not as decision input. +- "Feedback we shipped against did not move sentiment." Wrong feedback prioritized; the loud feedback was not the most consequential. +- "Users gave feedback once and never returned." Closed-loop missing; users feel ignored. +- "We tagged everything but cannot find patterns." Taxonomy too granular or too noisy; periodic taxonomy review missing. +- "Drift in feedback caught us by surprise." Drift detection missing; the team did not investigate trending patterns until they became problems. +- "Sales call data and support ticket data tell different stories." Cross-channel synthesis missing; each channel's signal stays in its own silo. + +--- + +## The framework: 12 considerations for feedback aggregation + +When designing or auditing a feedback aggregation system, walk these 12 considerations. + +1. Triaged-synthesis, not loudest-voice or averaged-noise. Signal weighted by source, frequency, decision relevance. +2. Channel taxonomy known. Support, NPS, in-app, sales, social, councils. What each surfaces. +3. Channel-source weighting per decision. Different decisions weight channels differently. +4. Categorization and tagging at scale. Taxonomy that emerges from data; tooling that supports volume. +5. Frequency-intensity matrix. Each feedback item assessed on both dimensions. +6. Synthesis cadence. Daily critical, weekly patterns, monthly review, quarterly strategic. +7. Cross-channel triangulation. Patterns that appear across channels are stronger. +8. Closing the loop with users. When feedback drives change, communicate. +9. Drift detection. Patterns over time reveal changes. +10. Tooling that scales. Multi-channel aggregation, pattern surfacing, integration. +11. Specific feedback informs specific decisions. Decisions traceable to specific signals. +12. Honest assessment of source bias. Each channel's bias acknowledged in synthesis. + +The output of the framework is feedback aggregation that produces decision-grade signal continuously, scales with program volume, and treats users well enough that they keep providing feedback over time. + +--- + +## Reference files + +- [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md) - Six common channels with strengths, weaknesses, biases, and synthesis implications. +- [`references/channel-source-weighting.md`](references/channel-source-weighting.md) - Decision-relative weighting. Worked examples of how channels weight differently for different decisions. +- [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md) - Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. +- [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md) - The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. +- [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md) - The synthesis loop. Cadences. The discipline of decisions traceable to feedback. +- [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md) - When and how to communicate feedback-driven changes. The over-promising risk. +- [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md) - Drift patterns. Investigation discipline. Drift as early signal of change. +- [`references/tooling-considerations.md`](references/tooling-considerations.md) - Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. +- [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: feedback as continuous signal, not periodic survey + +The teams that make good product decisions over time are the ones that aggregate feedback continuously and synthesize it into decision input. Not as compliance with a feedback-collection mandate; not as monthly NPS reporting; not as ad-hoc reactions to whoever complains loudest. As a continuous discipline that surfaces what users are actually experiencing, weighted appropriately, synthesized for the decisions the team is actually making. + +Feedback aggregation done well is invisible: the team makes better decisions, but the feedback work itself does not feel heroic. Feedback aggregation done badly is loud: channels overflow, NPS gets reported, customer councils produce decks, and decisions still get made on gut feel because the feedback work did not produce decision input. + +The discipline is in the triage. Each channel weighted by what it reveals. Each piece of feedback assessed on frequency and intensity. Patterns surfaced through synthesis. Decisions traceable to specific feedback. The closed loop with users that keeps feedback flowing. + +When in doubt about whether a feedback program is working, ask: can the team trace recent decisions to specific feedback patterns, are channels weighted differently for different decisions, is the synthesis cadence producing input the team uses, are users seeing their feedback acted on? If yes to all of those, the program is real. If no to any, the gap is where the feedback work is failing to convert into decisions. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md new file mode 100644 index 0000000..5faac7a --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md @@ -0,0 +1,213 @@ +# Categorization and tagging at scale + +Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. + +How feedback gets organized when it arrives at high volume. The discipline that prevents the "we tagged everything but cannot find patterns" failure. + +--- + +## The taxonomy dimensions + +Each feedback item gets tagged across multiple dimensions. + +Feature area or product surface. Where in the product the feedback applies. Examples: onboarding, dashboard, billing, integrations, mobile app. + +Issue type. Bug, friction, feature request, positive signal, edge case. + +User segment. Who is providing the feedback. Examples: free tier, pro tier, enterprise, trial, churned. + +Severity or urgency. How blocking is the issue. Examples: critical (blocks core flow), high (significant friction), medium (workaround exists), low (minor). + +Source channel. Where the feedback came from. Examples: support ticket, NPS comment, in-app widget, sales call, social mention, customer council. + +Date or time period. When the feedback was submitted. Useful for drift detection. + +Most programs use 3-6 of these dimensions. More dimensions produce richer queries; more dimensions also increase tagging burden. + +--- + +## Tags emerge from data, not from a pre-built taxonomy + +The same principle as discovery research synthesis (see `discovery-research-synthesis`). + +The pattern. Tags emerge from feedback patterns. Initial tagging captures what users actually said; the taxonomy builds up from the data. + +The anti-pattern. Pre-built taxonomies that force feedback into categories. Patterns the taxonomy did not anticipate get missed; categories that do not match the data get used anyway. + +Why emergent tagging matters. + +- Users describe issues in their own language; pre-built categories often miss the actual issues. +- New product features generate new categories; emergent tagging adapts. +- Issues evolve over time; emergent tagging captures the evolution. + +The transition. Programs starting feedback aggregation often need a starting taxonomy to begin with. The starting taxonomy is provisional; it gets refined as feedback accumulates and patterns clarify. + +--- + +## Multiple tags per feedback item + +Most feedback items deserve multiple tags. + +The pattern. A single feedback item often touches multiple feature areas, issue types, or context dimensions. + +Worked example. Support ticket: "I'm an enterprise admin trying to set up SSO for the team and the configuration step keeps timing out." + +Tags: + +- Feature area: SSO configuration, admin settings. +- Issue type: bug (timeout) + friction (configuration is hard). +- User segment: enterprise. +- Severity: high (blocks core enterprise setup). +- Source channel: support ticket. + +Multiple tags capture the feedback's full context. Single-tag forcing loses information. + +--- + +## Tagging at volume + +Programs receiving 500-2000+ feedback items per week need tooling support. + +Tooling approaches. + +- Manual tagging. Each item tagged by a human. Highest quality; lowest scale. Works for low-volume programs (under 100 items per week). +- AI-assisted tagging. AI suggests tags; humans review and adjust. Scales better; quality depends on the AI's training and the team's review discipline. +- Automated tagging. AI tags without human review. Scales highest; quality is lowest because no one validates. +- Hybrid. Manual tagging for high-priority items (enterprise feedback, critical issues), AI-assisted for the bulk. + +The recommended pattern for most programs. AI-assisted tagging with human review on patterns. The AI handles bulk classification; humans review aggregate patterns and validate that the categorization is producing useful signal. + +The volume calibration. + +- Under 100 items/week: manual tagging is feasible and preferred. +- 100-500 items/week: AI-assisted with sample review. +- 500+ items/week: AI-assisted with pattern review; manual handling reserved for high-priority items. + +--- + +## Tag quality vs tag granularity + +Two competing pressures. + +Granularity helps. More specific tags surface more specific patterns. "Onboarding configuration step 3 friction" is more useful than "onboarding friction." + +Granularity also harms. More specific tags fragment data. If 10 different tags split what should be one pattern, the pattern is invisible. + +The middle path. + +- Start with moderate granularity. +- Refine over time. Tags that consistently co-occur may need to merge; tags that combine distinct patterns may need to split. +- Periodic taxonomy review (see below) catches granularity issues. + +--- + +## Periodic taxonomy review + +Quarterly or bi-annual review of the taxonomy. + +The questions. + +- Are there tags that consistently co-occur and could merge? +- Are there tags that contain multiple distinct patterns and should split? +- Are there new patterns that need new tags? +- Are there tags that no longer apply (deprecated features, resolved issues)? +- Is the taxonomy too granular (fragmenting patterns) or too coarse (hiding patterns)? + +The output. A revised taxonomy. Old tags may get retired; new tags may get added; some tags may get renamed. + +The discipline. Without periodic review, taxonomies decay. Old tags accumulate; new patterns get tagged into wrong categories; the taxonomy stops surfacing useful patterns. + +The frequency. Quarterly works for most programs. Annual works for stable programs with low product change rate. Bi-annual works as a middle path. + +--- + +## Tag conflicts and resolution + +Sometimes feedback could be tagged in multiple ways. + +Resolution approaches. + +- Multi-tagging. When in doubt, apply multiple tags. Captures the ambiguity rather than forcing a choice. +- Convention. Document conventions for ambiguous cases. "Friction with the dashboard's filter functionality" gets tagged "dashboard" + "filtering" + "friction" rather than choosing. +- Reviewer judgment. Train reviewers (human or AI) on conventions. Ambiguous cases get reviewed for consistency. + +The cost of inconsistent tagging. Patterns become invisible because the same kind of feedback gets tagged differently. The "we tagged everything but cannot find patterns" failure often traces to inconsistent tagging. + +--- + +## Tag distribution as signal + +The distribution of tags across feedback can be informative beyond individual tags. + +Examples. + +- Spike in volume on a specific tag: trending issue or feature area in flux. +- Decline in volume on a tag: issue resolved or users gave up reporting. +- Co-occurrence patterns: tags that consistently appear together suggest related issues. +- Segment-specific tag distributions: enterprise vs free-tier feedback patterns differ. + +The dashboard view. Most feedback aggregation tooling supports tag-distribution dashboards. The dashboards surface patterns the team would not see in individual feedback items. + +--- + +## Tagging discipline at the channel level + +Different channels need different tagging conventions. + +Support tickets. Often pre-tagged by the support system (issue type, product area). Augment with feedback-specific tags. + +NPS comments. Lighter tagging. Often just sentiment + topic area. Open-ended comments are mined for patterns; not every comment needs comprehensive tagging. + +In-app feedback. Auto-tagged by context (which page, which feature). Augment with issue-type and severity. + +Sales calls. Often summarized rather than tagged at the moment level. Summaries get tagged. + +Social mentions. Auto-classified by sentiment and topic; manual review for high-impact mentions. + +Customer council notes. Manually tagged after each council session. Higher tagging investment because volume is low and signal is high. + +--- + +## Cross-channel tag consistency + +Tags should mean the same thing across channels. + +The risk. "Onboarding friction" in support tickets means something slightly different than "onboarding friction" in NPS comments because the channels surface different aspects. + +The mitigation. + +- Document tag definitions explicitly. "Onboarding friction" includes X, Y, Z signals. +- Periodic cross-channel calibration. Review tagged samples from each channel to ensure consistency. +- Channel-specific sub-tags where appropriate. "Onboarding-friction-support" vs "Onboarding-friction-nps" if the distinction matters. + +The honest framing. Cross-channel tag consistency is hard. Strong programs work toward it; perfect consistency is rare. + +--- + +## Common tagging failures + +Pre-built taxonomy forced. Patterns the taxonomy did not anticipate get missed. + +Single-tag forcing. Multi-dimensional feedback gets reduced to one tag; information lost. + +Inconsistent tagging. The same kind of feedback gets tagged differently across reviewers or time periods. + +Tag bloat. Too granular; patterns fragment across many tags. + +Tag coarseness. Too broad; distinct patterns hide within the same tag. + +No taxonomy review. Tags decay over time without periodic review. + +Volume overwhelms tagging. High-volume programs without tooling support; tagging falls behind; old feedback never gets tagged. + +Tag-without-purpose. Tagging happens because it is supposed to; nobody uses the tags for synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The taxonomy dimensions. Emergent tagging. Multi-tag discipline. Tagging at volume (manual, AI-assisted, automated, hybrid). Tag quality vs granularity tradeoffs. Periodic taxonomy review. Tag conflict resolution. Tag distribution as signal. Channel-specific tagging. Cross-channel consistency. Common failures. + +## Implementation choices that stay internal + +Specific tagging tools and AI models. Specific tag definition documents. Specific reviewer training. Specific dashboard configurations. The team's own conventions for tagging within the principles. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md new file mode 100644 index 0000000..aac3763 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-source-weighting.md @@ -0,0 +1,216 @@ +# Channel-source weighting + +Decision-relative weighting. Worked examples of how channels weight differently for different decisions. + +The discipline that distinguishes triaged-synthesis from averaged-noise. Different sources warrant different weights for different decisions; treating all sources as equal produces decisions made on aggregate volume rather than on signal that matters. + +--- + +## The weighting principle + +Each piece of feedback has a source. The source's weight in a decision depends on how relevant the source is to that decision. + +Worked principle. A piece of feedback from an enterprise customer has different weight than a piece of feedback from a trial user when the decision is about enterprise pricing. The enterprise customer's feedback is high-weight; the trial user's feedback is low-weight (they are not the audience for the decision). + +The same piece of feedback from a trial user has different weight when the decision is about trial conversion. Now the trial user is the audience; their feedback is high-weight. + +The weighting is decision-relative, not source-absolute. + +--- + +## Worked examples of channel weighting + +### Decision: Should we prioritize the enterprise admin role overhaul this quarter? + +Audience for the decision. Existing enterprise customers and enterprise prospects. + +Channel weights for this decision. + +- Sales call data with enterprise prospects: high weight. They directly inform the decision. +- Support ticket data from enterprise customers: high weight. Existing enterprise friction is directly relevant. +- Customer council data from enterprise members: high weight. Curated enterprise perspective. +- NPS data from enterprise customers: moderate weight. Aggregate signal but not specific to admin features. +- NPS data from small-team customers: low weight. Different segment; admin features not relevant. +- Social mentions: variable weight. Enterprise practitioners' posts higher than anonymous trial accounts. +- In-app feedback from small-team users: low weight. Different segment. + +The decision weighs enterprise sources heavily. Volume from non-enterprise sources should not displace enterprise signal. + +### Decision: Should we redesign the onboarding flow for new free-tier signups? + +Audience for the decision. Free-tier new signups. + +Channel weights for this decision. + +- Support tickets from free-tier users in their first week: high weight. Direct friction signal. +- In-app feedback from free-tier users during onboarding: high weight. Moment-of friction. +- NPS data from free-tier users: moderate weight. Aggregate sentiment. +- Sales call data: low weight. Sales calls are usually with prospects, not free signups; pre-decision conversation differs from post-signup experience. +- Customer council data: low weight. Councils usually have established customers, not new signups. +- Support tickets from long-tenured customers: low weight. Their onboarding friction was a year ago; current onboarding may differ. + +The decision weighs new-signup sources heavily. Long-tenured customer feedback is informative for other decisions but not this one. + +### Decision: Should we launch a new pricing tier? + +Audience for the decision. Both prospects and existing customers (existing customers may move tiers; prospects' tier choice affects acquisition). + +Channel weights for this decision. + +- Sales call data on pricing conversations: high weight. Prospects' pricing perception is critical. +- Support tickets about pricing or upgrade requests: high weight. Existing customer pricing pain points. +- Customer council discussion on pricing: high weight. Strategic discussion with curated customers. +- NPS data with pricing comments: moderate weight. Some signal but not decision-specific. +- Social mentions about pricing: moderate weight. Public perception affects acquisition. +- In-app feedback unrelated to pricing: low weight. Off-topic for this decision. + +Multiple high-weight channels because the decision spans audiences. + +### Decision: Should we invest in social mention monitoring as a primary channel? + +Audience for the decision. Strategic question about feedback aggregation infrastructure. + +Channel weights for this decision. + +- Past examples of social signal driving decisions: high weight. Direct evidence. +- Past examples where social signal misled (vocal minority, anonymous accounts): high weight as counter-evidence. +- Other companies' published patterns on social signal: moderate weight. Indicative but not specific. +- Internal team intuition about social signal: low weight unless backed by data. + +The decision weighs evidence of past signal-driven decisions heavily. + +--- + +## The averaged-noise failure + +When sources are weighted equally regardless of decision relevance. + +The pattern. + +- The team aggregates all feedback equally. +- Volume from any source counts the same. +- The most-feedback issue gets prioritized regardless of source. + +Why it fails. + +- Decisions get made on aggregate volume rather than on signal that matters for that decision. +- Decisions that should be enterprise-driven get displaced by volume from segments that do not matter for that decision. +- The team optimizes for the squeaky-wheel signal because it is loudest in the aggregate. + +Worked failure. The team is deciding whether to prioritize enterprise admin features. NPS and in-app feedback show low priority for this area (because most respondents are small-team users who do not need enterprise admin). Sales calls and enterprise support tickets clearly indicate the priority. The team aggregates volume, sees more total feedback against enterprise admin priority, and deprioritizes. Enterprise customers churn. + +The cure. Weight by decision relevance. Enterprise channels weight high for enterprise decisions; small-team feedback should not displace enterprise signal on enterprise decisions. + +--- + +## The loudest-voice failure + +When the most vocal source dominates regardless of representativeness. + +The pattern. + +- A small number of customers complain frequently and loudly. +- Their feedback dominates synthesis because they generate the most volume. +- Their preferences shape the roadmap. + +Why it fails. + +- Vocal minorities do not represent the broader user base. +- Silent majority's needs go unaddressed. +- The roadmap optimizes for the customers most likely to complain rather than the customers most strategic for the business. + +The cure. Weight by source quality and representativeness, not by volume. A complaint repeated 50 times by one user is not 50x the signal of one complaint by 50 distinct users. + +--- + +## How to set weights + +In practice, weighting is qualitative. Quantitative scoring schemes often produce false precision. + +The discipline. + +- For each decision, identify the audience (who the decision serves). +- Identify which channels surface signal from that audience. +- Identify which channels do not (and why their feedback is less relevant for this decision). +- In synthesis, give high-weight channel signal more attention than low-weight channel signal. + +Quantitative weighting risks. + +- Scoring systems (this channel = 3x weight; that channel = 1x) often produce false precision. +- Decisions made on weighted scores rather than on judgment can miss qualitative nuances. +- The discipline is qualitative judgment informed by source-relevance, not arithmetic. + +The honest framing. Weighting is a judgment call. The synthesis names the weighting choices explicitly: "We weighted enterprise channel signal heavily here because the decision is about enterprise priorities." Readers can disagree with the weighting; disagreement is productive. + +--- + +## Source bias acknowledgment + +Each source has biases that affect its signal. + +Sources skew toward. + +- Support: users willing to contact support; tend toward problem-reporting. +- NPS: users with strong opinions; middle-ground underrepresented. +- In-app feedback: users who interact with widgets; specific segments may dominate. +- Sales calls: prospects, not existing customers; pre-purchase context. +- Social: users who post publicly; enthusiasts and angry voices. +- Councils: curated members; specific selection criteria. + +The synthesis discipline. When weighting, acknowledge the bias. "Support tickets show high friction in this area" should be paired with "noting the support-channel bias toward users who contact support." The acknowledgment makes synthesis more honest and readers more informed. + +--- + +## Multi-channel triangulation as weighting + +When patterns appear across multiple channels, weighting becomes easier. + +Strong cross-channel signal. Same pattern in support, NPS, in-app, and sales. The cross-channel pattern survives any single channel's bias. + +Single-channel signal. Pattern in only one channel. Weighting depends on channel reliability for the decision; treat with more caution. + +Conflicting cross-channel signal. Different channels disagree. Investigate the source of the conflict; the disagreement often reveals segment differences or context-specific patterns. + +The discipline. Cross-channel triangulation is a form of weighting: patterns that survive multiple channels' biases are more reliable signal. + +--- + +## Weighting in tooling + +Some feedback aggregation tools support explicit weighting (priority scores, segment-specific dashboards). + +Tooling support. + +- Tagging by source channel and segment. +- Filtering and grouping by tag combinations. +- Dashboards that show signal per segment or channel. + +The tooling principle. Tooling supports weighting; the weighting judgment still belongs to humans. Tools that automate weighting away from human judgment risk false precision. + +The build-vs-buy tension. Many programs end up with custom dashboards or filtering that supports their specific weighting. Generic tooling rarely supports the program's specific decision-relative weighting needs out of the box. + +--- + +## Common weighting failures + +No weighting. All sources treated equally. Averaged-noise pattern. + +Static weighting. Same weights regardless of decision. Misses that different decisions need different weights. + +Quantitative false precision. Scoring systems that produce decisions without judgment. + +Volume as proxy for weight. Loudest-voice pattern; whoever generates most feedback wins. + +Bias acknowledgment skipped. Synthesis claims stronger signal than the channel's bias warrants. + +Single-channel reliance. Decisions made on one channel's signal without triangulation. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relative weighting principle. Worked weighting examples for different decisions. The averaged-noise and loudest-voice failures. How to set weights. Source bias acknowledgment. Multi-channel triangulation. Weighting in tooling. Common failures. + +## Implementation choices that stay internal + +Specific weighting conventions for specific decision types. Specific tooling that supports weighting. Specific dashboard configurations. The team's own conventions for naming weighting choices in synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md new file mode 100644 index 0000000..c2c0ec3 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md @@ -0,0 +1,263 @@ +# Channel types and what each surfaces + +Six common feedback channels with strengths, weaknesses, biases, and synthesis implications. Each channel surfaces different signal at different reliability; strong aggregation triangulates across channels. + +--- + +## Channel 1: Support tickets + +What users hit when things break or confuse them. + +What support surfaces. + +- Functional friction (where the product breaks down for users). +- Documentation gaps (questions users ask repeatedly). +- Feature requests that arrive in the form of complaints. +- Edge case failures. +- Confusion about intended behavior vs actual behavior. + +Strengths. + +- High volume; signal accumulates from many users. +- Grounded in specific user contexts (the user was trying to do something specific). +- Captures friction users actually encountered, not friction they speculated about. + +Weaknesses. + +- Bias toward users willing to contact support. Users who silently leave the product do not appear here. +- Bias toward fixable issues. Users who struggle but figure it out (or give up) without contacting support are invisible. +- Sentiment skew: users contact support when frustrated; positive experience is underrepresented. + +Synthesis implications. + +- Support volume on a feature area is a strong signal of friction; absence of volume is weak signal of satisfaction. +- Pattern-detection across tickets reveals systemic issues better than individual tickets. +- Combine with usage analytics: a feature with high support volume and low usage suggests broken value; high support volume and high usage suggests meaningful friction in something users still want. + +--- + +## Channel 2: NPS surveys + +Aggregate sentiment toward the product or specific features. + +What NPS surfaces. + +- Aggregate sentiment trend lines. +- Distribution between promoters, passives, and detractors. +- Open-ended comments (often the most useful part). +- Sentiment differences across segments. + +Strengths. + +- Quantitative signal that aggregates across many users. +- Trends over time reveal whether sentiment is improving or degrading. +- Open-ended comments provide qualitative depth. +- Industry-standard metric makes benchmarking possible. + +Weaknesses. + +- Response bias. Users with strong opinions (positive or negative) respond at higher rates than users in the middle. +- Cultural and segment biases in scoring (some segments score lower on average than others for cultural reasons). +- The 0-10 scale loses granularity; many decisions need more than promoter/passive/detractor categorization. +- Surveys on specific features can have small sample sizes that produce noisy signal. + +Synthesis implications. + +- NPS as a single number is less useful than NPS distribution and trend. +- Open-ended comments are often the highest-value section; mine them for patterns. +- Segment-specific NPS is more actionable than aggregate NPS. +- Single-quarter NPS shifts can be noise; multi-quarter trends are more reliable signal. + +--- + +## Channel 3: In-app feedback + +Friction at the moment users encounter it. + +What in-app feedback surfaces. + +- Contextual friction (the user was at a specific moment in the product when they submitted). +- Ratings or sentiment scoped to specific features or flows. +- Quick observations users would not bother to file as a ticket. + +Strengths. + +- Captures the moment. Friction is fresh; context is automatic (the system knows where the user was). +- Lower friction submission than support tickets; surfaces issues users would not formally report. +- Volume varies; some products see high in-app feedback, others minimal. + +Weaknesses. + +- Bias toward users who interact with the feedback widget. Some segments use it heavily; others rarely. +- Quality varies. Quick submissions are often shallow. +- Volume can overwhelm if the widget triggers too aggressively. + +Synthesis implications. + +- In-app feedback is best for detecting moment-specific friction. +- Pair with usage analytics: where users submit feedback in the product is informative. +- Filter by submission length and pattern; one-word submissions ("frustrating!") are weak signal compared to specific submissions ("I expected the export to include the filters I had applied; it did not"). + +--- + +## Channel 4: Sales calls + +Pre-purchase prospect perspective. + +What sales calls surface. + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Prospect vocabulary for describing their situation (often different from internal product language). + +Strengths. + +- Prospect view of the product before they have invested in it. Reveals what attracts and what blocks adoption. +- Competitive intelligence in the form of comparisons prospects make. +- Hire criteria signal (why prospects would choose the product). + +Weaknesses. + +- Bias toward prospects, not existing customers. Existing-customer experience differs. +- Sales-team interpretation can color how calls are tagged. +- Stage selection matters: early-stage discovery calls reveal different things than late-stage closing calls. + +Synthesis implications. + +- Sales call data informs positioning, pricing, and adoption-hire-criteria decisions. +- Combine with existing-customer feedback to understand the full lifecycle. +- Lost-deal analysis (specifically, calls with prospects who did not buy) is a separate research mode that surfaces what the product would need to win. + +--- + +## Channel 5: Social mentions + +Public commentary about the product. + +What social mentions surface. + +- Public sentiment in real time. +- Comparison to competitors (often more honest than survey responses). +- Use cases and use contexts the team did not anticipate. +- Reputation signals (how the product is perceived in the broader market). + +Strengths. + +- Real-time signal. +- Public visibility means the team can respond to issues that affect brand reputation. +- Captures users who post publicly but would not file feedback through formal channels. + +Weaknesses. + +- Bias toward users willing to post publicly. Often skews toward enthusiasts (positive) or angry (negative); middle-ground users are quiet. +- Volume can overwhelm; signal-to-noise ratio is low. +- Anonymous accounts complicate weighting (who is this person? are they a real customer?). +- Platform algorithms shape what is visible; the visible signal is not the full signal. + +Synthesis implications. + +- Social signal is one input, rarely a primary driver. Triangulate with other channels. +- Track reputational themes (what the product is known for in the broader market). +- Respond to specific issues that affect brand reputation; do not use social as the primary feedback prioritization channel. + +--- + +## Channel 6: Customer councils + +Curated panels of customers in structured forums. + +What customer councils surface. + +- Curated customer perspective on strategic questions. +- Deep discussion that reveals motivations and priorities. +- Cross-customer patterns (council members compare notes; the team sees what they share). +- Long-term relationship signal (council members commit time and engagement). + +Strengths. + +- High-quality feedback from selected customers. +- Structured forum makes discussion deeper than ad-hoc feedback. +- Council members often become advocates and references. + +Weaknesses. + +- Bias depends on selection. A council selected for size, role, or vocal customers will skew accordingly. +- Council members are often outliers (engaged, willing to commit time); their perspective may not represent broader users. +- Small sample size (usually 5-30 members); patterns from one council are weak signal. +- Cost: councils require curation, scheduling, and ongoing relationship management. + +Synthesis implications. + +- Council feedback is valuable but limited; do not treat as representative of the full user base. +- Use councils for strategic discussions, not for tactical prioritization. +- Council patterns can be a leading indicator of broader user patterns; validate with other channels. + +--- + +## Channels not covered here + +Some feedback channels are out of scope for this skill but worth naming. + +Beta participants. Covered by `beta-program-management`. Beta feedback is bounded to the beta period; this skill covers ongoing streams. + +Discovery research interviews. Covered by `discovery-research-synthesis`. One-off research projects, not always-on streams. + +App store reviews. A specific channel for consumer products. Similar dynamics to social mentions: public, biased toward strong opinions, real-time but volume-heavy. + +Customer success quarterly business reviews. Often produce structured customer feedback; can be treated as a council-like channel for top customers. + +Internal employee feedback. Sometimes valuable (employees are users of internal tools, or use the product alongside customers); always biased toward internal context. + +--- + +## Cross-channel triangulation + +Patterns that appear across channels are stronger than patterns from a single channel. + +Worked example. A feature area showing: + +- Support tickets: increasing volume in this area. +- NPS comments: this area mentioned negatively in detractor comments. +- In-app feedback: friction submissions in this area. +- Sales calls: prospects asking about this area as a comparison point against competitors. + +The cross-channel pattern is stronger than any single-channel signal. The feature area is a load-bearing issue across multiple lenses. + +Worked counter-example. A loud single-channel signal: + +- Social mentions: vocal complaints about a feature. +- Support tickets: minimal volume on the same feature. +- NPS: feature not flagged in detractor comments. +- Sales calls: feature not raised by prospects. + +The cross-channel pattern shows the social signal is loud but not load-bearing. Loud-on-one-channel-only is often vocal-minority signal. + +--- + +## Channel reliability calibration + +Different channels have different reliability for different kinds of decisions. + +Functional friction decisions. Support tickets and in-app feedback are most reliable. NPS is moderate. Social and sales are less reliable. + +Adoption hire-criteria decisions. Sales calls are most reliable. Support tickets and in-app feedback are less reliable (existing-customer bias). + +Positioning decisions. Sales calls and social mentions are most reliable (prospect/public perception). NPS and councils are moderate. + +Strategic prioritization. Customer councils and NPS trends are useful inputs. Support tickets indicate friction but not strategic priority. + +Reputation decisions. Social mentions are direct signal. Support and NPS are indirect. + +The discipline. For each decision, identify which channels are most reliable. Weight accordingly. + +--- + +## Methodology-level choices that stay in the public skill + +The six channel types with strengths, weaknesses, biases, and synthesis implications. Channels not covered. Cross-channel triangulation. Channel reliability calibration for different decision types. + +## Implementation choices that stay internal + +Specific tooling per channel. Specific tagging schemas. Specific integration patterns across channels. The team's own conventions for channel coverage. These vary by team and tooling. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md new file mode 100644 index 0000000..5c70fb4 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md @@ -0,0 +1,246 @@ +# Closing the loop with users + +When and how to communicate feedback-driven changes. The over-promising risk. + +Closing the loop is the practice of telling users when their feedback drove a product change. Done well, it strengthens the feedback relationship; users see their input matter. Done badly, it over-promises or appears performative; trust erodes. + +--- + +## Why closing the loop matters + +Users who provide feedback are doing the team a favor. The cost is their time and attention. The return on their investment is, in part, seeing their input acted on. + +What happens when the loop is open. + +- Users provide feedback. +- The team uses it (or does not). +- Users do not know what happened. +- Engagement decays. Why provide feedback if it does not seem to matter? + +What happens when the loop is closed. + +- Users provide feedback. +- The team uses it (or explains why not). +- Users see their input matter. +- Engagement strengthens. Future feedback flows. + +--- + +## What gets communicated + +Three categories of communication. + +Changes shipped. "We shipped X this week. Many of you reported Y was painful; X addresses that." + +- Specific, actionable, ties to specific feedback. +- Best when the team can quantify the change ("Step 3 deferral; activation rate increased from 32% to 41% in the first month"). + +Changes coming. "We are working on X for Q3. Several of you have asked about this; here is the timeline." + +- Specific timeline. +- Honest about uncertainty if applicable. +- Risk: over-promising. Communicating coming changes that do not ship erodes trust. + +Decisions to defer or decline. "We have heard feedback about X; we are choosing not to prioritize it because Y. Here is the reasoning." + +- Honest about the deferral. +- Explains the reasoning. +- Treats users as capable of understanding tradeoffs. + +The third category is rarely done; it is the most credibility-building. Teams that explain why something was not prioritized earn more trust than teams that promise everything. + +--- + +## Communication channels + +How to close the loop. + +Public channels. + +- Release notes. Standard post-launch communication. Includes feedback context where relevant. +- Blog posts or changelog. Longer-form for major changes. Names the feedback patterns that drove the work. +- Public roadmap. Shows what is coming; signals that user feedback informs prioritization. + +Targeted channels. + +- Email to users who reported the issue. "You reported X; we shipped Y to address it." Personalized; high impact for specific users. +- In-app notification at the moment of relevance. When the user encounters the changed flow, an in-product banner: "We changed this based on feedback like yours; here is what is different." +- Customer success outreach. For high-value or high-engagement users, direct outreach is appropriate. + +Community channels. + +- Beta or community forums. Where applicable, communicate to the engaged community. +- Social media. For high-visibility changes; risk of public attention if poorly communicated. + +The channel should match the audience and the change. High-impact public changes warrant public communication; targeted changes warrant targeted communication. + +--- + +## Frequency and timing + +When to close the loop. + +Immediately after shipping. Most effective. The change is fresh; users remember providing feedback. + +Periodic recap (monthly or quarterly). "Here are the changes we shipped this quarter, and the feedback patterns that motivated them." + +- Useful for changes that did not warrant individual announcement. +- Builds an aggregate sense that feedback is shaping the product. + +Before shipping (preview). "We are about to ship X; here is what to expect." + +- Heads-up for users who will encounter the change. +- Risk: pre-launch announcements that get delayed; users wonder when the change is coming. + +The frequency calibration. Avoid silence (users feel ignored). Avoid over-communication (users tune out). Calibrate to the change cadence and audience attention. + +--- + +## The over-promising risk + +Communicating future changes that do not ship erodes trust. + +The pattern. + +- The team announces "we are working on X" with a timeline. +- The work gets deprioritized, delayed, or canceled. +- Users who counted on the change feel deceived or ignored. + +Why it happens. + +- Marketing or stakeholder pressure to share roadmap information. +- The team's own optimism about timelines. +- Failure to communicate when plans change. + +The cure. + +- Communicate shipped changes with confidence. +- Communicate coming changes with appropriate hedging ("we are exploring this," "we are planning this for next quarter"). +- Communicate plan changes when they happen, not silently. + +The honest framing. Promising "X will ship in Q3" is high-risk; promising "X is on our radar; we are evaluating priority" is honest. The first looks more confident; the second is more credible over time. + +--- + +## Communication for declined or deferred feedback + +When the team decides not to prioritize requested changes. + +The pattern. + +- User provides feedback requesting a change. +- The team evaluates and decides not to prioritize. +- The team communicates the decision. + +Strong communication. + +- "Several of you have asked about [feature]. We have evaluated and are choosing not to prioritize it this year because [reason]. Here are alternatives or workarounds that may help in the meantime." +- "We hear the feedback about [issue]. We are choosing not to address this for now because [tradeoff]. We are open to reconsidering if the pattern strengthens." + +Why it builds trust. + +- Acknowledges the feedback was heard. +- Explains the reasoning. +- Treats the user as capable of understanding tradeoffs. + +The risk of avoiding. + +- Silence. The user wonders if the feedback was heard. +- "Maybe in the future." Vague commitments that do not commit. +- "We will consider it." Performative. + +The decline communication is rare in practice but disproportionately valuable. + +--- + +## Communication for high-volume feedback + +When many users have provided similar feedback. + +The pattern. + +- A specific change addresses widely-reported feedback. +- The team has many users to potentially notify. + +Approaches. + +- Public announcement referencing the feedback pattern. "Many of you reported X; we shipped Y." +- Targeted email to users who reported the issue (using support ticket history, NPS comments, etc.). +- In-product notification at the moment of relevance. + +The capacity calibration. Targeted communication is high-effort; public communication scales. Most programs combine: public announcement for visibility, targeted communication for highest-impact users. + +--- + +## Personal vs aggregate + +Sometimes the closing-the-loop communication is to a specific user; sometimes it is aggregate. + +Personal. + +- "John, you reported X two months ago. We shipped Y this week to address it. Thanks for the feedback that informed this work." +- Direct email or in-app message. +- High impact for the specific user; low cost; very high relationship value. + +Aggregate. + +- "Many of you have asked about X; we shipped Y this week." +- Public announcement; reaches many users. +- Lower per-user impact but scales. + +The discipline. Personal communication for high-impact users (long-tenured customers, design partners, council members). Aggregate for broader changes. + +--- + +## When closing the loop fails + +Common failures. + +Silence. The most common failure. Users provide feedback; the team uses it (or does not); users never know what happened. Engagement decays. + +Generic acknowledgment. "Thanks for the feedback! We will look into it." Standard auto-reply that everyone gets. Feels performative; closes the loop technically but not meaningfully. + +Over-promising. "We will ship this in Q3." The team misses the date or cancels; users feel deceived. + +Late communication. Changes shipped months ago; communication never happens; users stopped using the product. + +Vague communication. "We have heard your feedback and are working on improvements." No specifics; users cannot tell what was actually changed. + +No deferral communication. Changes the team decided not to prioritize go uncommunicated. Users keep wondering or assume the feedback was ignored. + +Communication only on shipping. Successes communicated; failures and deferrals never. Trust erodes when users notice the asymmetry. + +--- + +## Closing the loop and feedback volume + +Programs that close the loop well often see feedback volume increase over time. Users who saw their input matter contribute more. + +The virtuous cycle. + +- Feedback closes the loop. +- Users see their input matter. +- Engagement strengthens. +- Feedback volume and quality increase. +- The team has more signal to act on. + +The vicious cycle. + +- Feedback aggregation happens in silos. +- Closing the loop does not happen. +- Users feel ignored. +- Engagement decays. +- Feedback volume and quality decrease. +- The team has less signal. + +The discipline. Closing the loop is an investment in the future of the feedback program. + +--- + +## Methodology-level choices that stay in the public skill + +Why closing the loop matters. What gets communicated. Communication channels. Frequency and timing. The over-promising risk. Communication for declined or deferred feedback. Communication for high-volume feedback. Personal vs aggregate. Common failures. The virtuous and vicious cycle. + +## Implementation choices that stay internal + +Specific email templates for closing-the-loop communication. Specific automation that triggers communication. Specific in-product notification systems. The team's own conventions for personal vs aggregate. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md new file mode 100644 index 0000000..c16ce67 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md @@ -0,0 +1,193 @@ +# Common feedback aggregation failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most feedback aggregation failures share a single root, which is treating feedback aggregation as collection rather than as decision input. + +--- + +## Failure 1: Loudest customers steer the roadmap + +Symptom. A small number of vocal customers dominate roadmap discussions. Quieter customers' needs go unaddressed. The product evolves to serve the loudest, not the broadest. + +Diagnosis. Loudest-voice pattern. Volume from vocal users mistaken for broad signal. + +Cure. Apply channel-source weighting. Distinguish between distinct-user signal and per-user volume. Triangulate across channels to validate that loud signal represents broad pattern. + +Prevention. Synthesis names the source distribution explicitly. "This pattern came from 50 distinct users across 3 channels" is different from "this pattern came from 5 users with 200 tickets." + +--- + +## Failure 2: We have lots of feedback but no decisions + +Symptom. Feedback channels overflow. Tagging happens. Dashboards exist. Decisions get made on intuition rather than on the feedback signal. + +Diagnosis. Aggregation without synthesis. The triage cadence is missing or broken; feedback is collected without being turned into decision input. + +Cure. Establish the synthesis cadence (weekly, monthly, quarterly). Each cadence produces output the team uses for decisions. + +Prevention. Synthesis ownership explicit. Whoever owns synthesis is accountable for the loop's continuity. + +--- + +## Failure 3: Our channels overflow; we cannot keep up + +Symptom. Feedback volume exceeds the team's capacity to triage, tag, and synthesize. Old feedback never gets reviewed; new feedback piles up. + +Diagnosis. Capacity mismatch. Either tooling does not scale, or the team is under-staffed for the volume, or both. + +Cure. Scale tooling: AI-assisted tagging, aggregated channels, automated pattern surfacing. Or reduce capture: not every channel needs to be aggregated. + +Prevention. Match tooling and capacity to expected volume. Plan for growth; the volume that is comfortable today often is not in 6 months. + +--- + +## Failure 4: Different teams cite different feedback for the same decision + +Symptom. Engineering team cites one feedback pattern; product team cites another; sales team cites a third. The teams reach for whatever feedback supports their position. + +Diagnosis. Channel-source weighting absent. Each team uses the channel that is most accessible to them, regardless of decision relevance. + +Cure. Establish weighting per decision. The synthesis surfaces what the relevant channels say, weighted appropriately. Teams use the synthesis rather than going to channels independently. + +Prevention. Centralize synthesis ownership. The synthesis owner produces the canonical view; teams reference it rather than producing parallel interpretations. + +--- + +## Failure 5: Customer council meetings produce notes nobody references + +Symptom. Customer council convenes regularly. Notes are taken. Decks summarize. The notes get filed; no roadmap discussions reference them. + +Diagnosis. Council without synthesis loop. The meeting is the deliverable; the analytical follow-through is missing. + +Cure. Apply the synthesis loop to council inputs. Each council meeting produces specific actionable input that feeds product decisions. + +Prevention. Treat council inputs as part of the broader feedback aggregation, not as a separate stream that produces ceremonial outputs. + +--- + +## Failure 6: NPS is reported monthly but does not inform decisions + +Symptom. NPS scores get reported in monthly business reviews. The number is part of compliance reporting. It does not inform product decisions. + +Diagnosis. NPS as compliance metric. The number gets tracked; the underlying signal does not. + +Cure. Mine NPS comments for patterns. Segment NPS by user segment. Use NPS trends as drift signal. The number itself is less informative than the underlying signal. + +Prevention. NPS reporting includes the qualitative signal alongside the quantitative score. Decisions reference what NPS comments revealed, not just the score. + +--- + +## Failure 7: Feedback we shipped against did not move sentiment + +Symptom. Major feature shipped to address feedback. Post-launch sentiment did not improve. The team is confused. + +Diagnosis. Wrong feedback prioritized. The loud feedback was not the most consequential; the patterns the team addressed were not the patterns that drove sentiment. + +Cure. Re-examine the synthesis that motivated the work. Was the pattern strong across channels, or was it loud in one channel? Was the segment broad or narrow? Was the change the right response to the pattern? + +Prevention. Strong synthesis grounds prioritization in cross-channel patterns and frequency-intensity assessment. Single-channel signals get treated cautiously. + +--- + +## Failure 8: Users gave feedback once and never returned + +Symptom. Users submit feedback through channels. They never engage again. Repeat feedback rates are low. + +Diagnosis. Closed-loop missing. Users feel ignored after providing feedback. + +Cure. Establish closing-the-loop communication. Tell users when their feedback drove change. Personal communication for high-impact users; aggregate for broader changes. + +Prevention. Closing the loop is part of the feedback workflow, not an afterthought. Decisions to ship include closing-the-loop communication as a step. + +--- + +## Failure 9: We tagged everything but cannot find patterns + +Symptom. Tagging happens systematically. The team applies tags to most feedback items. But synthesis cannot identify clear patterns. + +Diagnosis. Taxonomy too granular, too coarse, or noisy. Periodic taxonomy review missing. + +Cure. Run a taxonomy review. Merge tags that fragment patterns; split tags that hide distinct issues; deprecate tags that no longer apply. + +Prevention. Quarterly or bi-annual taxonomy review. The taxonomy evolves with the program. + +--- + +## Failure 10: Drift in feedback caught us by surprise + +Symptom. A feedback category grew significantly over weeks or months. The team discovered the change only when it became a problem. + +Diagnosis. Drift detection missing. The team did not investigate trending patterns until they became urgent. + +Cure. Establish drift detection: trend dashboards, threshold alerts, periodic trend review. + +Prevention. Weekly quick scans for sharp drift. Monthly systematic review of category trends. Tooling that surfaces changes automatically. + +--- + +## Failure 11: Sales call data and support ticket data tell different stories + +Symptom. Sales suggests one priority; support suggests another. Both teams have data; the data conflicts. + +Diagnosis. Cross-channel synthesis missing. Each channel's signal stays in its own silo. + +Cure. Run cross-channel synthesis. Compare what sales calls reveal (prospect view) to what support tickets reveal (existing customer view). Often the conflict surfaces meaningful differences (different segments, different lifecycle stages); sometimes it surfaces inconsistency that warrants investigation. + +Prevention. Synthesis includes cross-channel triangulation. Conflicts get surfaced and resolved or acknowledged. + +--- + +## Failure 12: Feedback aggregation as compliance + +Symptom. Feedback collection happens because customers expect it or because leadership mandates it. The collection is performative; the synthesis is minimal. + +Diagnosis. Feedback aggregation treated as ceremony rather than as decision input. + +Cure. Tie feedback aggregation to specific decisions. The synthesis informs roadmap; decisions reference patterns. If the team cannot trace decisions to feedback, the program is compliance, not aggregation. + +Prevention. Feedback program goals are explicit and tied to decisions. The program's success is measured by whether decisions reference its synthesis, not by whether feedback was collected. + +--- + +## Failure 13: Synthesis that does not surface patterns + +Symptom. Monthly or quarterly synthesis happens. The output is descriptive but does not surface patterns or inform decisions. + +Diagnosis. Synthesis writing is documentation rather than analytical work. The patterns are not extracted; the implications are not drawn. + +Cure. Apply discovery-research-synthesis discipline to feedback synthesis. Patterns named with conviction; implications drawn; decisions informed. + +Prevention. Synthesis ownership includes analytical responsibility, not just documentation responsibility. + +--- + +## Failure 14: Tooling-led process + +Symptom. The team's process follows what the tooling supports. Capabilities the tooling does not support do not happen. + +Diagnosis. Tooling drives the process rather than the process driving tooling selection. + +Cure. Step back. Define what the team needs the feedback aggregation to produce. Evaluate tooling against those needs. + +Prevention. Tooling decisions are downstream of process design. The team designs the process, then selects or builds tooling that supports it. + +--- + +## The cross-cutting pattern + +Most feedback aggregation failures share a single root: treating feedback aggregation as collection rather than as decision input. + +Collection focuses on capturing feedback: channels integrated, items tagged, dashboards built, scores reported. Output: a record that feedback was collected. + +Decision input focuses on what the feedback informs: which decisions, what signal will inform them, what synthesis surfaces patterns the team needs. Output: decisions traceable to feedback patterns. + +The fix for almost any feedback aggregation failure starts with the same question: what specifically is this feedback program supposed to inform, and is the synthesis loop producing that input? When the answer is clear, the program becomes load-bearing. When the answer is "we should be aggregating feedback," the program becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting collection-vs-decision-input pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md new file mode 100644 index 0000000..cff4b6c --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md @@ -0,0 +1,236 @@ +# Detecting drift in feedback + +Drift patterns. Investigation discipline. Drift as early signal of change. + +Feedback signal changes over time. Volume in a category increases or decreases; new patterns emerge; old patterns disappear; sentiment shifts. The team that detects drift early often catches issues before they compound; the team that does not detect drift often discovers problems after they are large. + +--- + +## The drift patterns + +Common ways feedback signal changes over time. + +### Increasing volume in a category + +Signal. Feedback volume in a specific area is rising over weeks or months. + +Possible causes. + +- The issue is worsening. +- The user base is growing (more total volume across all categories). +- Awareness of the channel is increasing (more users finding the feedback channel). +- Recent product changes introduced or amplified an issue. + +The investigation. Look at the cause: + +- Is the percentage of total feedback in this category increasing? (If yes, this category is growing relative to others; the issue is real, not just user-base growth.) +- Did recent product changes affect this area? (Often the cause when volume increases sharply.) +- Are users describing similar issues in different ways? (Could be one underlying issue surfacing through multiple feedback styles.) + +### Decreasing volume in a category + +Signal. Feedback volume in a specific area is declining over weeks or months. + +Possible causes. + +- The issue was resolved. +- Users gave up reporting (resignation rather than satisfaction). +- The user base shifted (fewer users in the affected segment). +- Channel access changed (users stopped using the feedback channel for this category). + +The investigation. Decreasing volume can be good or bad: + +- If a fix shipped and volume dropped: fix worked. +- If no fix shipped but volume dropped: investigate. Are users churning? Are they working around the issue silently? + +### New patterns emerging + +Signal. Feedback that was rare or non-existent starts appearing more frequently. + +Possible causes. + +- Recent product changes introduced new patterns. +- Market conditions changed (new competitors, new user expectations). +- User base expansion brought new use cases. +- Existing users developed new workflows. + +The investigation. Investigate the cause; new patterns often inform roadmap decisions. + +### Patterns disappearing + +Signal. Feedback patterns that used to be common stop appearing. + +Possible causes. + +- Product changes addressed the issue. +- Users migrated away from the affected workflows. +- The user base shifted. + +The investigation. Validate that the disappearance reflects resolution, not silent abandonment. + +### Sentiment shifts + +Signal. Aggregate sentiment (NPS, CSAT, in-app rating) trends differently than before. + +Possible causes. + +- Specific changes affected sentiment. +- External factors (market conditions, competitor actions, news cycles). +- User base composition changed. +- Cumulative experience changes that the team did not flag individually. + +The investigation. Sentiment shifts warrant root-cause analysis; both improvements and degradations are informative. + +--- + +## The drift detection cadence + +When the team checks for drift. + +Weekly: quick scans for sharp drift in critical categories. Sharp increases in support volume on specific issues, sudden NPS drops, viral social mentions. + +Monthly: systematic review of category-level trends. Compare the past month to prior months. Identify categories with significant increases or decreases. + +Quarterly: strategic drift review. Long-term trends, sentiment shifts, emerging patterns. Pairs with quarterly strategic synthesis. + +Annually: taxonomy and aggregate drift. Are tag categories still appropriate? Has the user base composition changed? Long-term sentiment trends. + +--- + +## Tooling for drift detection + +What infrastructure helps catch drift. + +Trend dashboards. Time-series views of feedback volume per category. Visual surfacing of changes. + +Threshold alerts. Automated alerts when a category's volume changes significantly (e.g., 50%+ increase week-over-week). + +Sentiment tracking. NPS or CSAT trends over time, segmented by user segment and product area. + +Cross-channel views. Aggregate trends across channels surface patterns that single-channel views miss. + +Period comparisons. Compare current period to prior periods (this month vs last month, this quarter vs same quarter last year). + +The tooling supports detection; humans interpret. + +--- + +## Investigation discipline + +When drift is detected, what to investigate. + +The questions. + +- What changed in the product or in the user base that could explain the drift? +- Is the drift persistent or a temporary spike? +- Is the drift segment-specific or universal? +- Is the drift correlated with other signals (churn, engagement, support volume)? +- What is the underlying cause vs the surface signal? + +The investigation methodology. + +- Pull a sample of feedback from the drifting category. +- Compare it to feedback in the same category from before the drift started. +- Identify what changed: language, contexts, severity, user segments. +- Map to product changes or external events that could explain. +- Form a hypothesis; test it through additional investigation. + +--- + +## Drift as early signal + +Drift often signals issues before they become large. + +The leading-indicator pattern. + +- A category's volume starts increasing. +- The team investigates and identifies the cause. +- The cause is addressed before it affects more users. + +Without drift detection, the same issue might compound for months before the team notices. + +Worked example. + +- Support tickets in the "configuration step 3" category increase 30% in two weeks. +- Investigation reveals: a recent change to the configuration form introduced a confusing default. +- The change is reverted or fixed within a week. +- Without drift detection, the issue might have continued for months, affecting many more users. + +--- + +## Drift in segments + +Drift can be segment-specific. + +The pattern. Aggregate metrics look stable; segment-specific metrics show drift. + +Worked example. Aggregate NPS is stable. Enterprise NPS is dropping; small-team NPS is improving. The aggregate hides the segment-specific drift. + +The investigation. Segment-level views surface patterns the aggregate hides. Enterprise drift may indicate a specific issue with enterprise features or experience that aggregate metrics miss. + +The discipline. Drift detection should include segment views, not just aggregate views. + +--- + +## Drift in cross-channel patterns + +Sometimes drift appears across channels even when individual channels look stable. + +The pattern. Each channel shows mild changes; the cross-channel aggregate shows a stronger pattern. + +Worked example. Support tickets in onboarding category up 15%. NPS comments mentioning onboarding up 10%. In-app feedback in onboarding up 20%. No single channel signals an emergency; the cross-channel aggregate suggests a real issue. + +The investigation. Cross-channel drift detection requires unified views or manual cross-channel review. + +--- + +## False-positive drift + +Not every change is real drift. + +Common false positives. + +- Seasonal patterns: support volume drops over holidays; NPS dips during certain campaigns. +- One-off events: a viral social mention spikes social signal but does not represent persistent change. +- Product launches: short-term volume spikes around new features, then normalize. +- Channel changes: a new feedback channel launches; volume in that channel grows from zero, not because the underlying issue grew. + +The investigation discipline. Before declaring drift, validate that the change is persistent and not explained by known factors. + +--- + +## Drift acknowledgment in synthesis + +Drift signals get surfaced in monthly and quarterly synthesis. + +The pattern. Synthesis documents include a drift section: what is changing, what may explain it, what action (if any) is recommended. + +The honest framing. Some drift gets acknowledged but not actioned (low-priority categories, edge cases). Some drift drives investigation. Some drift drives roadmap decisions. The synthesis names the disposition for each drift signal. + +--- + +## Common drift detection failures + +No detection. Aggregate volume is the only metric tracked; trends invisible. + +Aggregate only. Segment-specific drift hidden by aggregate stability. + +Single-channel only. Cross-channel patterns missed. + +Late detection. Drift caught after it has compounded for months. + +False positives treated as real drift. Seasonal patterns or one-off events trigger investigation that wastes time. + +Real drift treated as false positive. The team dismisses signals as noise; underlying issues compound. + +Investigation without follow-through. Drift detected; team investigates; finds cause; does not act. The detection was performative. + +--- + +## Methodology-level choices that stay in the public skill + +The drift patterns (increasing/decreasing volume, new/disappearing patterns, sentiment shifts). The drift detection cadence. Tooling for drift detection. Investigation discipline. Drift as early signal. Drift in segments. Drift in cross-channel patterns. False-positive drift. Drift acknowledgment in synthesis. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for drift detection. Specific threshold settings for alerts. Specific seasonality models. Specific segment-view configurations. The team's own conventions for drift acknowledgment in synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md new file mode 100644 index 0000000..3f96062 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/frequency-vs-intensity.md @@ -0,0 +1,231 @@ +# Frequency vs intensity + +The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. + +Feedback signal varies along two dimensions: how often the same feedback recurs (frequency) and how strongly users feel about it (intensity). The combination produces a matrix that informs prioritization. + +--- + +## The two dimensions + +Frequency. How often the same feedback recurs across users. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +Intensity. How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive ("I cannot use the product because of this"), or describe satisfaction as transformative ("This feature changed how my team works"). +- Low-intensity feedback: minor friction ("Slightly annoying") or mild satisfaction ("It's fine"). + +The two dimensions are independent. High frequency does not imply high intensity; high intensity does not imply high frequency. + +--- + +## The four-quadrant matrix + +### Quadrant 1: High frequency, high intensity + +Top priority. Many users hit this; it matters to them. + +Examples. + +- A bug that affects core flow for many users. +- A friction point users describe as "I almost canceled because of this." +- A feature gap that users repeatedly cite as a competitive disadvantage. + +The disposition. Address quickly. The combination of broad impact and high stakes warrants priority investment. + +### Quadrant 2: High frequency, low intensity + +Papercuts. Many users hit this but it is minor. + +Examples. + +- A confusing button label that users figure out within seconds. +- A slight delay in a flow that users tolerate. +- A small visual inconsistency. + +The disposition. Address in batches. Individual papercuts are minor; cumulatively they erode experience. Periodic "papercut sprints" address many at once. + +The risk of ignoring papercuts. Papercuts compound. Users who tolerate one papercut leave when they accumulate. The cumulative experience is worse than the sum of individual papercuts. + +### Quadrant 3: Low frequency, high intensity + +Affected users deeply impacted but few. Often segment-specific. + +Examples. + +- A bug that affects users in a specific configuration that 5% of customers use, but for those users it is blocking. +- A feature gap that prevents enterprise customers from passing compliance review. +- An accessibility issue that excludes a specific user group entirely. + +The disposition. Depends on segment importance and reversibility. + +- If the affected segment is strategically important: high priority. +- If the affected segment is marginal: lower priority but documented. +- If the issue is a complete blocker for the affected users (cannot use the product at all): often warrants urgency regardless of segment size. + +### Quadrant 4: Low frequency, low intensity + +Noise. Capture; do not action individually. + +Examples. + +- One-off observations from users with unusual contexts. +- Minor preferences that one user mentions. +- Edge cases nobody else encounters. + +The disposition. Note in the system. Do not invest action on individual items. Aggregate sometimes reveals patterns; the noise can become signal if patterns emerge. + +--- + +## Frequency assessment + +How to assess frequency. + +Quantitative signals. + +- Number of distinct users reporting the same issue across channels. +- Volume of feedback items in the relevant tag or category. +- Trend over time: is the frequency increasing or stable? + +Cautions. + +- Volume can reflect channel bias rather than actual frequency. A loud single user generating 50 tickets is not high-frequency feedback (50x). +- Channel coverage matters. If a feedback channel only reaches a subset of users, frequency in that channel does not reflect frequency across all users. + +The cross-channel triangulation. Issues that show up across multiple channels are higher-frequency than issues that appear in one channel only. + +--- + +## Intensity assessment + +How to assess intensity. + +Verbal signals. + +- Strong language: "I cannot use this," "This is unacceptable," "I love this," "This changed my workflow." +- Specific impact descriptions: "I lost 3 hours," "This made my quarterly review possible," "I missed a deadline." +- Workaround intensity: heavy workarounds suggest high-intensity friction; light workarounds suggest low-intensity. + +Behavioral signals. + +- Churn correlation: users with feedback in a category churn at higher rates. +- Engagement correlation: users with positive feedback in a category engage more. +- Escalation patterns: users escalating to higher support tiers or to executive contacts signal high intensity. + +Cautions. + +- Some users naturally use stronger language than others. +- Cultural differences affect verbal intensity. +- Triangulate verbal and behavioral signals. + +--- + +## The matrix in practice + +Worked example: a feedback aggregation review for a product team's quarterly planning. + +Top-of-list items (high frequency, high intensity). + +- Onboarding configuration step 3 abandonment (broad signal across support, NPS comments, in-app feedback; users describe it as "I almost gave up"). +- Mobile app stability issues (frequent mobile crashes; users describe them as blocking). +- Enterprise admin role limitations (consistent across enterprise sales calls and support tickets; described as compliance blockers). + +Papercut batch (high frequency, low intensity). + +- Inconsistent button labeling across the product. +- Slow page transitions in the dashboard. +- Filter resets when navigating between views. +- Date format inconsistencies. + +Strategic-decision items (low frequency, high intensity). + +- Specific accessibility issues affecting screen reader users. +- Compliance gaps for healthcare-segment customers (small segment but blocking for them). +- Bug affecting users in specific timezone configurations (5% of users, but blocking). + +Noise-watch (low frequency, low intensity). + +- Various individual feature requests with no aggregate pattern. +- Cosmetic preferences mentioned by single users. + +The team's quarterly planning weights the four quadrants differently: + +- Top-of-list: included in the next quarter's roadmap. +- Papercut batch: scheduled for a dedicated sprint. +- Strategic decisions: discussed at strategy review for prioritization. +- Noise-watch: captured but not actioned. + +--- + +## When the matrix is misapplied + +Common matrix misuses. + +Volume as proxy for frequency. Loudest-voice users generate volume that does not reflect distinct-user frequency. + +Intensity assessed only verbally. Some users complain loudly about minor issues; some users underreport severe ones. Triangulate verbal and behavioral signals. + +Quadrant 4 dismissed too quickly. Some apparent noise is early-signal of patterns that will grow. Periodic review of low-frequency items catches emerging patterns. + +Quadrant 3 generalized to quadrant 1. Strategic-segment issues weighted as if they affected all users. Or marginal-segment issues weighted as if they were strategic. + +Frequency-only or intensity-only prioritization. Looking at one dimension misses the matrix. + +--- + +## Frequency over time + +Frequency dimensions can shift over time. + +Increasing frequency. Issue is worsening, user base is growing, or reporting awareness is increasing. Investigate the cause. + +Decreasing frequency. Issue is resolving, users are giving up reporting, or the user base shifted. The decreasing frequency may not mean problem solved. + +Stable frequency. Issue is recurring at consistent rate. May indicate steady-state or chronic issue. + +The drift detection (see `detecting-drift-in-feedback.md`) covers temporal changes in feedback signal. + +--- + +## Intensity at scale + +Intensity assessments at high feedback volume. + +The challenge. Reading every piece of feedback to assess intensity is impractical at high volume. + +The approach. + +- Sample-based intensity assessment. Read a sample; characterize the intensity distribution. +- Behavioral signal as proxy. Churn rates, escalation patterns, support-tier escalations. +- AI-assisted intensity classification. AI flags high-intensity feedback for human review. + +The discipline. Even at high volume, the team should be able to identify high-intensity feedback and weight it appropriately. + +--- + +## Common frequency-intensity failures + +Loudest-voice as high-frequency. A few loud users generate volume; the team mistakes volume for frequency. + +Intensity ignored. Volume drives prioritization; intensity is not assessed; quadrant 1 and quadrant 2 get treated similarly. + +Frequency ignored. A single emotional submission gets prioritized as if it were broad-pattern signal. + +Papercuts ignored as "low priority." Cumulative papercut impact erodes experience; treating each papercut as too minor to address misses the cumulative effect. + +Strategic-segment issues underweighted. Quadrant 3 treated as quadrant 4 because the affected segment is small. + +Noise treated as signal. Quadrant 4 items that are genuinely one-off get actioned as if they were broad patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The two dimensions (frequency and intensity). The four-quadrant matrix with worked dispositions. Frequency assessment. Intensity assessment. The matrix in practice. When the matrix is misapplied. Frequency over time. Intensity at scale. Common failures. + +## Implementation choices that stay internal + +Specific tooling for frequency tracking. Specific intensity classification (manual or AI-assisted). Specific dashboard views by quadrant. The team's own conventions for matrix application in prioritization. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md new file mode 100644 index 0000000..3f911df --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md @@ -0,0 +1,225 @@ +# From feedback to product decision + +The synthesis loop. Cadences. The discipline of decisions traceable to feedback. + +Feedback aggregation produces value when it informs decisions. Without the synthesis loop that turns aggregated feedback into decision input, the program produces volume without action. + +--- + +## The synthesis loop + +The cycle that turns continuous feedback into continuous decisions. + +The stages. + +1. Feedback arrives across channels. +2. Triage categorizes and weights. +3. Periodic synthesis surfaces patterns. +4. Patterns inform roadmap discussions, spec drafts, prioritization debates. +5. Decisions reference specific feedback patterns as input. +6. Decisions ship; the loop continues with new feedback informed by the changes. + +The discipline. The loop is continuous. Feedback aggregation is not a one-time research project; it is a steady-state discipline. + +--- + +## The cadences + +Feedback synthesis benefits from multiple cadences operating in parallel. + +Daily: critical issues. + +- Critical feedback (security incidents, data loss, broken core flows) handled immediately. +- The triage system surfaces critical items for immediate attention. +- Response within hours to a day. + +Weekly: pattern review. + +- Team review of recent feedback patterns. +- Categorization, tagging, and pattern identification. +- Adjusts current-quarter execution where patterns suggest changes. +- 1-2 hours per week typical. + +Monthly: synthesis review. + +- Surfaces trending patterns over the past month. +- Identifies what to escalate to roadmap discussions. +- Compares current month patterns to prior months (drift detection). +- 2-4 hours per month. + +Quarterly: strategic synthesis. + +- Patterns over the quarter inform strategic planning and next-quarter roadmap. +- Customer council inputs and other longer-cadence channels integrated. +- Pairs with the team's broader strategic planning. +- A multi-day effort within the quarter's planning cycle. + +The cadences compose. Critical issues do not wait for weekly review; weekly review captures patterns that monthly review aggregates; monthly synthesis informs quarterly strategic decisions. + +--- + +## The synthesis output + +What each cadence produces. + +Daily/critical: specific incidents handled, no formal output beyond the response. + +Weekly: internal team notes on emerging patterns. May include a short summary email or dashboard update. + +Monthly: a synthesis document covering the month's patterns. Surfaces what is emerging, what is stable, what has resolved. Roadmap discussions reference this document. + +Quarterly: a strategic synthesis document. Trends over the quarter, recommendations for next quarter, strategic implications. Senior product leadership reviews this. + +The output gets richer at longer cadences. Daily and weekly are tactical; monthly and quarterly are strategic. + +--- + +## Decisions traceable to feedback + +The discipline that distinguishes triaged-synthesis from feedback ceremony. + +The pattern. Each major product decision can be traced to specific feedback patterns. The team can articulate: "We decided to prioritize X because feedback showed Y pattern across Z channels." + +The anti-pattern. Decisions get made on intuition or politics. Feedback aggregation happens in parallel but does not inform the decisions. The team uses general impressions ("we hear a lot about this from customers") rather than specific patterns. + +The discipline. + +- Roadmap items reference the feedback patterns that motivated them. +- Prioritization debates reference specific signal weight. +- Spec drafts include feedback context for the design decisions. +- Stakeholder communication explains decisions in terms of feedback patterns. + +The audit. For recent decisions, can the team trace each to specific feedback signals? If yes, the program is informing decisions. If the answer is "we generally know what customers want," the program is feedback theater. + +--- + +## Roadmap input from feedback + +How feedback aggregation informs roadmap planning. + +The roadmap inputs. + +- High-frequency-high-intensity patterns (quadrant 1 from the frequency-intensity matrix). +- Strategic-segment patterns (quadrant 3 from segments that matter for strategy). +- Cross-channel patterns that have validated across multiple sources. +- Drift signals that suggest emerging issues. + +The roadmap-output mapping. Roadmap candidates get characterized by which feedback patterns they address. + +- Candidate: "Onboarding redesign." Feedback motivation: configuration step 3 abandonment pattern across support, NPS, in-app feedback. +- Candidate: "Enterprise admin overhaul." Feedback motivation: enterprise sales-call objections + enterprise customer support patterns. + +The mapping makes the roadmap defensible: each item has a feedback-grounded reason. + +The "no feedback signal, no priority" discipline. Candidates that lack feedback grounding may still be valuable but should be defensible on other grounds (technical foundation, strategic bet). Candidates without any defensible grounding should be deprioritized. + +Pair with `roadmap-planning` for the broader prioritization discipline. + +--- + +## Spec input from feedback + +How feedback aggregation informs spec writing. + +The pattern. Specs reference feedback context for design decisions. + +Worked example. A spec for an onboarding redesign: + +- Background: feedback shows 40% of new signups abandon at configuration step 3. Cross-channel pattern (support tickets, in-app feedback, NPS comments). +- User stories: grounded in the specific feedback patterns. "As a new signup, I want to defer credit-card configuration until after I have seen the value, so I do not need my card on hand at signup." +- Design decisions: tied to the feedback. "Step 3 deferral chosen because feedback specifically cites credit-card-not-on-hand as the abandonment cause; alternative approaches that do not address this would not move the metric." + +The spec is grounded in feedback rather than in intuition. + +Pair with `pm-spec-writing` for the broader spec discipline. + +--- + +## Stakeholder communication from feedback + +How feedback aggregation informs stakeholder discussions. + +The pattern. Decisions presented to stakeholders are explained in terms of feedback patterns. + +Strong stakeholder communication. + +- "We are prioritizing the onboarding redesign because feedback across support, NPS, and in-app surveys consistently shows 40%+ abandonment at configuration step 3, with users citing credit-card friction as the cause." +- "We are deferring the dashboard expansion because feedback signal is mixed: enterprise customers want it; small-team customers do not need it; the strategic priority for this quarter is small-team activation." + +Weak stakeholder communication. + +- "We have heard a lot of feedback about onboarding." +- "Customers want this feature." + +The strong version is defensible; readers can engage substantively. The weak version is hand-waving. + +--- + +## Closing the synthesis loop + +After decisions ship, feedback responds. + +The post-decision feedback. + +- Did the change reduce the feedback patterns that motivated it? +- Did new patterns emerge as a result? +- Did the change introduce new friction in adjacent areas? + +The discipline. Track post-decision feedback to validate that the decision worked. Decisions that ship without post-decision feedback tracking lose the loop's learning value. + +--- + +## Cadence drift + +When the synthesis cadence breaks down. + +Common drift patterns. + +- Critical issues handled but no weekly pattern review. Tactical signal lost. +- Weekly review happens but does not aggregate to monthly synthesis. Patterns over time invisible. +- Monthly synthesis happens but does not inform quarterly planning. Strategic input missing. +- Quarterly strategic synthesis happens but the team does not act on it. Synthesis ceremony. + +The signal. When decisions stop being traceable to feedback, the cadence has drifted. The fix is restoring the cadence rather than blaming the team. + +--- + +## Synthesis ownership + +Who owns the synthesis loop. + +Common ownership patterns. + +- A dedicated feedback program owner (often a senior PM, product ops, or customer-success-product liaison). +- The product team's PM rotates through synthesis duties. +- A customer feedback team that synthesizes and feeds product teams. + +The discipline. Whoever owns synthesis is accountable for the loop's continuity. Without explicit ownership, synthesis falls to whoever has time, which often means it does not happen. + +--- + +## Common decision-loop failures + +Synthesis without decisions. Patterns surfaced; team does not use them. Documentation theater. + +Decisions without synthesis grounding. Team makes decisions on intuition; feedback aggregation happens in parallel but does not inform. + +Cadence breakdown. Daily critical handled; weekly and monthly synthesis fall behind. Loop loses continuity. + +No post-decision tracking. Decisions ship; feedback response not tracked; learning lost. + +Synthesis ownership missing. No clear owner; synthesis falls between roles. + +Synthesis output not actionable. Documents produced but framed in ways that do not inform decisions. Dense, generic, or unfocused. + +Stakeholder communication still hand-waving. Synthesis happens internally but stakeholder communication does not reference the patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The synthesis loop. The cadences (daily, weekly, monthly, quarterly). The synthesis output per cadence. Decisions traceable to feedback. Roadmap input. Spec input. Stakeholder communication. Closing the loop after decisions ship. Cadence drift. Synthesis ownership. Common failures. + +## Implementation choices that stay internal + +Specific tooling for synthesis production. Specific document templates per cadence. Specific reviewer workflows. Specific dashboard configurations. The team's own conventions for owning synthesis. These vary by team. diff --git a/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md b/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md new file mode 100644 index 0000000..5669fc4 --- /dev/null +++ b/dist/pi/.agents/skills/user-feedback-aggregation/references/tooling-considerations.md @@ -0,0 +1,247 @@ +# Tooling considerations + +Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. + +Feedback aggregation tooling shapes what the program can do. The right tooling supports multi-channel aggregation, tagging at scale, pattern surfacing, and integration with adjacent systems. The wrong tooling produces silos, manual labor, and synthesis bottlenecks. + +This skill is platform-agnostic; specific products are not endorsed. The categories below describe what kinds of tooling exist; the team's actual product choices depend on stack, budget, and program shape. + +--- + +## Tooling categories + +Several categories of tooling support feedback aggregation. + +### Customer feedback platforms + +What they do. Aggregate feedback from multiple sources. Support tagging and categorization. Surface patterns through dashboards and analytics. + +Strengths. + +- Multi-channel support (often integrate with support, NPS, in-app, and other sources). +- Built-in tagging and pattern detection. +- Often include AI-assisted categorization. + +Weaknesses. + +- Pre-built taxonomies may not fit team-specific needs. +- Vendor-locked: switching costs grow over time. +- Coverage varies by vendor; some channels may not integrate. + +### Support ticket systems with analytics + +What they do. Track support tickets with tagging, routing, and reporting. Often the primary support channel. + +Strengths. + +- Native to support workflows. +- Strong tagging and routing for support-specific work. +- Analytics on support-team metrics. + +Weaknesses. + +- Often single-channel (support only). +- Cross-channel synthesis requires additional tooling or custom integration. + +### NPS or survey platforms + +What they do. Distribute surveys, collect responses, track sentiment trends. + +Strengths. + +- Specialized for survey distribution and response collection. +- Built-in NPS or CSAT methodology. +- Trend tracking over time. + +Weaknesses. + +- Single-modality (surveys only). +- Limited integration with other feedback sources. + +### Customer relationship management (CRM) systems + +What they do. Manage customer relationships, contact history, deal pipelines, customer feedback fields. + +Strengths. + +- Rich customer context (segment, deal stage, account history). +- Integration with sales workflows. + +Weaknesses. + +- Feedback aggregation is often a side feature, not a core function. +- Cross-channel feedback synthesis requires additional configuration. + +### Custom dashboards combining feedback signal with usage analytics + +What they do. Custom-built views combining feedback data with product analytics. + +Strengths. + +- Tailored to the team's specific needs. +- Cross-channel synthesis built-in to the design. +- Combines feedback patterns with behavioral signals. + +Weaknesses. + +- Build cost and ongoing maintenance. +- Skill requirements: data engineering or analytics expertise. + +--- + +## The criteria for tooling selection + +What to evaluate when choosing tooling. + +Multi-channel aggregation. Does it integrate with the channels the team uses? Or does it cover one channel only? + +Tagging at scale. Does it support the tagging volume the program needs? Manual tagging at low volume; AI-assisted at high volume. + +Pattern surfacing. Does it surface patterns, or is it just storage? Some tools store feedback without making it analyzable. + +Integration with other systems. Does it connect to roadmap tools, ticketing systems, communication channels? Isolated tools produce silos. + +Scaling. Does it scale with program volume? Tools that work at 100 items/week may break at 1000 items/week. + +Cost. License or build cost vs the value produced. Expensive tooling that fits is sometimes worth it; cheaper tooling that does not fit is often more expensive in practice. + +Team skill match. Does the team have skills to use the tool effectively? Sophisticated tools that the team cannot operate produce value that does not get realized. + +--- + +## The build-vs-buy tension + +Most programs end up with a mix. + +The reasons to buy. + +- Faster setup. Off-the-shelf tools work immediately. +- Specialized expertise. Vendors have built tooling for many programs. +- Standard features that the team would not build themselves. + +The reasons to build. + +- Cross-channel synthesis often requires custom work that off-the-shelf tools do not support. +- Team-specific tagging schemas and dashboards. +- Integration with the team's specific stack. + +The hybrid pattern. + +- Off-the-shelf tools for primary channels (support ticketing, NPS surveys). +- Custom dashboards for cross-channel synthesis. +- Custom integration to bring data together. + +The hybrid is more common than pure build-or-pure-buy in practice. + +--- + +## Volume considerations + +Different volume tiers warrant different tooling approaches. + +Low volume (under 100 items/week). + +- Manual tagging is feasible. +- Off-the-shelf tools usually sufficient. +- Custom build often overkill. + +Mid volume (100-1000 items/week). + +- AI-assisted tagging often worth the investment. +- Multi-channel aggregation tools earn their keep. +- Custom dashboards often add value. + +High volume (1000+ items/week). + +- Heavy AI-assisted or automated tagging. +- Custom infrastructure for cross-channel synthesis. +- Team capacity becomes the bottleneck; tooling must reduce manual work substantially. + +Very high volume (10,000+ items/week). + +- Often requires custom data engineering. +- Sampling and aggregation strategies replace per-item review. +- Tooling investment is substantial. + +--- + +## Integration considerations + +Feedback aggregation rarely lives alone. + +Common integrations. + +- Roadmap tools. Feedback patterns feed roadmap candidates. Tools that integrate (or are linked through workflows) reduce manual transfer. +- Spec writing. Feedback context for spec drafts. +- Communication channels. Slack or email for surfacing patterns to the team. +- Customer success systems. Closing the loop with users; account-level feedback views. +- Product analytics. Cross-reference feedback with usage patterns. + +The integration discipline. Tooling that integrates produces value compound across the systems. Isolated tooling produces silos that the team must manually bridge. + +--- + +## AI-assisted feedback work + +AI plays an increasing role in feedback aggregation. + +Common AI uses. + +- Automatic categorization and tagging. +- Sentiment classification. +- Pattern surfacing across feedback items. +- Summary generation for synthesis documents. +- Anomaly detection for drift identification. + +The discipline. + +- AI suggestions get human review at pattern-level. +- Critical decisions remain human-driven; AI accelerates the work. +- AI's biases (overfitting to training data, surface-level patterns) get checked through human pattern review. + +The honest framing. AI does not replace human synthesis; it supports it. Programs that automate synthesis entirely produce volume without judgment; programs that integrate AI with human review produce signal at scale. + +See `ai-content-collaboration` for the broader workflow discipline that applies to AI-assisted feedback work. + +--- + +## Privacy and data considerations + +Feedback often contains user information. + +Considerations. + +- User consent for feedback use beyond the immediate channel. +- Anonymization where appropriate (especially for sensitive feedback). +- Data retention policies. +- Compliance with regulations (GDPR, CCPA, industry-specific). + +The discipline. Tooling choices include data handling considerations. Vendors with poor data practices can create compliance issues regardless of tool capability. + +--- + +## Common tooling failures + +Single-channel reliance. Tooling supports only one channel; cross-channel synthesis impossible without additional work. + +Overly generic tools. Pre-built taxonomies and dashboards do not match team needs. + +Custom build that consumes capacity. Building feedback infrastructure absorbs PM and engineering capacity that should produce product. + +Volume mismatch. Tools that fit current volume break when the program scales. + +Integration neglected. Feedback tooling isolated from roadmap, spec, customer success systems. + +AI without review. Automated categorization without human pattern review produces patterns the team cannot trust. + +Tooling-led process. The tool drives the process rather than the process driving tool selection. The team adopts a tool's workflow rather than designing for their needs. + +--- + +## Methodology-level choices that stay in the public skill + +The tooling categories. The criteria for selection. The build-vs-buy tension. Volume considerations. Integration considerations. AI-assisted feedback work. Privacy and data considerations. Common failures. + +## Implementation choices that stay internal + +Specific tooling vendor selections. Specific integration configurations. Specific dashboard designs. Specific data pipelines. The team's own conventions for tool evaluation. These vary by team, stack, and program shape. diff --git a/dist/pi/.agents/skills/ux-research/SKILL.md b/dist/pi/.agents/skills/ux-research/SKILL.md new file mode 100644 index 0000000..2de3cb2 --- /dev/null +++ b/dist/pi/.agents/skills/ux-research/SKILL.md @@ -0,0 +1,252 @@ +--- +name: ux-research +description: "Plan and execute user research including research planning, recruiting, interview design, qualitative synthesis, and translating findings into product decisions. Use this skill whenever the user wants to plan user research, design interviews, recruit participants, conduct discovery, run formative research, or synthesize qualitative findings. Triggers on user research, UX research, user interviews, discovery research, generative research, formative research, qualitative research, user insights, research synthesis, recruitment, interview guide, jobs to be done. Also triggers when product decisions are being made without user input and the user wants to fix that." +category: research +catalog_summary: "Research planning, user interviews, qualitative synthesis" +display_order: 1 +--- + +# UX Research + +Plan and execute user research that produces decisions, not just decks. Stack-agnostic. Tool-agnostic. + +This skill is for generative and discovery research. For testing existing designs, use `usability-testing`. For mapping the full customer experience, use `journey-mapping`. + +--- + +## When to use + +- Starting a new product or major feature without sufficient user understanding +- Diagnosing why something isn't working without clear data signals +- Generating new opportunity hypotheses +- Validating a strategic direction before significant investment +- Building empathy across a team that's drifted from users +- Translating "we should talk to users" intent into a real plan + +## When NOT to use + +- Testing a specific design or prototype (use `usability-testing`) +- Mapping the full journey of an existing experience (use `journey-mapping`) +- Quantitative measurement (use `analytics-strategy`) +- Conversion testing (use `cro-optimization`) + +--- + +## Required inputs + +- The research question(s) - what you need to answer +- Stakeholder buy-in (who needs the findings, what decisions hinge on them) +- Access to users (current customers, prospects, lapsed users, target segments) +- Timeline and budget +- Any prior research to build on + +--- + +## The framework: 6 phases + +### 1. Frame the question + +Bad questions produce bad research. Spend disproportionate time on framing. + +Good research questions: +- Specific (not "How do users feel about our product?") +- Open-ended (not "Do users like feature X?") +- Decision-relevant (the answer changes what gets built) +- Researchable (can be answered through user contact, not just analysis) + +Examples: + +\| Weak question \| Better question \| +\|---\|---\| +\| "Do users like our onboarding?" \| "Where in onboarding do new users feel uncertain about whether to continue?" \| +\| "What features should we build?" \| "What unmet needs do current users have when [specific job]?" \| +\| "Why is conversion low?" \| "What's the user mental model when they reach the pricing page, and where does it diverge from our intent?" \| + +### 2. Choose the method + +The method follows the question. + +Generative methods (what's true?): + +- In-depth interviews. 60 minutes, 5 to 15 participants. Best for understanding context, motivation, mental models. +- Contextual inquiry. Observe users in their environment doing their work. Best for workflow understanding. +- Diary studies. Participants log their experience over days/weeks. Best for behaviors that don't manifest in a single session. +- Field research. Spend time where users live/work. Best for cultural and contextual understanding. +- Surveys (qualitative-heavy). When you need broad signal with open-ended responses. + +Validation methods (is this hypothesis right?): + +- Concept testing. Show a description, mockup, or prototype. Get reactions. +- Card sorts. Validate information architecture. +- Tree tests. Validate findability without visual design influence. + +(For testing usability of working designs, see `usability-testing`.) + +### 3. Recruit + +The recruit makes or breaks the research. + +Recruit criteria: + +- Match the audience the research targets (not "anyone willing") +- Mix of behaviors (active users, lapsed users, never-users) +- Mix of demographics where relevant +- Excludes friends, family, employees (biased) +- Excludes professional research participants if possible (different population) + +Recruit channels: + +- In-product recruiting (intercept current users) +- Email outreach to user segments +- Recruiting platforms (UserInterviews, Respondent, etc.) +- Customer support team referrals +- Field intercept for in-person + +Incentive: Pay participants. Standard rates: $50 to $150 for 60 minutes, more for executives or specialized professions. + +Recruit volume: Plan for 20 to 30 percent no-show. Recruit 7 to schedule 5. + +### 4. Conduct + +The interview or session itself. + +Pre-interview: + +- Send confirmation 24 hours and 1 hour before +- Test recording setup (audio quality is non-negotiable) +- Prepare interview guide (see template) +- Have a notetaker if possible (frees the interviewer to focus) + +During the interview: + +- Record video and audio (with consent) +- Open with rapport-building, not the research questions +- Use open-ended questions ("Tell me about the last time...") +- Use silence (let participants fill it; don't rush to the next question) +- Ask "why" but not too many times in a row (becomes interrogation) +- Ask for specifics and examples ("Can you walk me through what you did?") +- Probe contradictions gently ("Earlier you said X, now you're saying Y; help me understand") +- Watch for moments of emotion (often signal something important) +- Don't sell or convince - this is listening, not pitching + +Anti-patterns: + +- Leading questions ("Don't you find this confusing?") +- Hypothetical questions ("Would you use a feature that...?") - poor predictor of behavior +- Multiple questions at once +- Interrupting +- Filling silence +- Interviewing your hypothesis (only asking questions that confirm what you already think) + +### 5. Synthesize + +Notes don't become insights automatically. + +The synthesis process: + +1. Capture observations. From recordings, notes, transcripts. Each observation is a single data point: a quote, a behavior, an emotion, a moment. +2. Affinity mapping. Cluster observations into themes. Physical sticky notes or digital equivalents. +3. Find patterns. Themes that appear across multiple participants are signal. One-off observations are interesting but weaker. +4. Identify insights. An insight is more than a theme. It's a non-obvious finding that explains a why or implies a so what. +5. Test the insight against the data. If the insight only fits some interviews, it's a hypothesis, not an insight. +6. Distinguish signal from noise. A belief that 1 of 8 participants holds may be noise. A belief 6 of 8 hold is signal. + +Heuristics for strong insights: + +- They surprise the team (insights you already knew aren't insights) +- They explain a "why" the team has been guessing about +- They imply specific actions (so what?) +- They hold up across multiple data points +- They can be stated in one or two sentences + +### 6. Communicate + +Findings die in slide decks. Plan distribution. + +Outputs that work: + +- Top-line insights document. 5 to 10 insights, clearly stated, with supporting quotes. +- Highlight reels. Edited 5 to 10 minute video of key participant moments. More persuasive than any document. +- In-room workshops. Walk stakeholders through the synthesis themselves. They internalize when they participate. +- Per-stakeholder briefs. Different audiences need different framings. CEO wants strategic implications. Designers want pain points. Engineers want use cases. + +Outputs that fail: + +- 80-slide decks that get skimmed +- Reports that no one reads past the executive summary +- Verbose narrative summaries +- Insights that sit in a doc no one re-opens + +--- + +## Workflow + +1. Frame the research question. With stakeholders. Multiple iterations. +2. Pick the method. Match to the question. +3. Plan logistics. Timeline, budget, recruit, tools, team. +4. Recruit. Start early. Slow recruits delay everything. +5. Pilot. Run 1 to 2 sessions before the main batch. Refine the guide. +6. Conduct. Stay disciplined to the guide while staying open to surprises. +7. Synthesize. Don't wait until all sessions are done; start mid-way. +8. Communicate. Multiple formats. Multiple audiences. +9. Track impact. Did decisions change because of the research? If not, the research failed regardless of quality. + +--- + +## Failure patterns + +- Research without a decision. Findings have no home. Effort wasted. +- Vague research questions. Bad questions produce uninterpretable answers. +- Recruiting "anyone willing." Sample doesn't match audience. +- Over-recruiting professional participants. Pattern-matched answers, not real users. +- Leading questions in the guide. Findings reflect the researcher, not the user. +- Skipping synthesis. Notes alone aren't insights. +- Insights that confirm the team's existing beliefs. Suspect those especially. +- Findings that never ship. Research findings that don't change product decisions are decoration. +- Single research project for years of decisions. Research has a shelf life. Refresh. +- Research as one-time project. Continuous discovery beats episodic research. + +--- + +## Output format + +Default outputs: + +1. Research plan (before research starts) - `research-plan-[topic].md` +2. Interview guide - `interview-guide-[topic].md` +3. Findings doc (after synthesis) - `research-findings-[topic].md` +4. Highlight reel (video, separately produced) + +Findings document structure: + +```markdown +# [Topic] research findings + +## Question we set out to answer +[Specific question] + +## Method +[Approach, sample size, dates] + +## Top insights +1. [Insight, stated in one sentence] + - Supporting evidence: [Quotes, behaviors] + - Implication: [What this means for product/strategy] +2. [Insight 2] + ... + +## Themes (less prominent than top insights, still worth noting) +[List] + +## Outliers worth investigating +[Single-participant observations that may be signal in disguise] + +## Recommended next steps +[Specific actions] +``` + +--- + +## Reference files + +- [`references/interview-guide-template.md`](references/interview-guide-template.md) - Structured interview guide template with example openings, probes, and closes. diff --git a/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md b/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md new file mode 100644 index 0000000..88fcb00 --- /dev/null +++ b/dist/pi/.agents/skills/ux-research/references/interview-guide-template.md @@ -0,0 +1,241 @@ +# Interview Guide Template + +A structured template for in-depth research interviews. Customize the sections to your topic. Length: typically 60 to 75 minutes. + +--- + +## Pre-interview prep + +Participant info: +- Name: +- Role / context: +- How they were recruited: +- Anything noteworthy from screener: + +Research question being answered: [The specific question this interview is helping answer] + +Top 3 things I'm trying to learn: +1. +2. +3. + +Hypotheses I'm holding loosely: +- [What I think I'll find. Naming this helps me notice when I confirm vs disconfirm it.] + +Recording setup: +- [ ] Audio recorder tested +- [ ] Video recorder (if applicable) tested +- [ ] Notetaker confirmed (or not present) +- [ ] Consent form sent + +--- + +## Section 1: Welcome and rapport (5 to 10 minutes) + +Goal: Put the participant at ease. Start collecting context. + +### Opening + +> "Thanks so much for joining today. As I mentioned, we're [purpose: studying how people do X / learning about Y / etc.]. There are no right or wrong answers; I'm here to learn from your experience. +> +> Before we start, do you have any questions? +> +> A few practical notes: I'll be recording so I can focus on listening rather than note-taking. The recording stays internal and is used only for our research. I'll never quote you by name without permission. You can ask me to stop the recording any time. Sound good? +> +> Great. Let's start with something easy." + +### Easy opener + +> "Tell me a little about yourself. What's your role, what does a typical [day / week / project] look like?" + +[Listen for context: industry, role, scale, constraints. Take notes on anything you want to come back to.] + +--- + +## Section 2: Context (10 to 15 minutes) + +Goal: Understand the world the participant lives in. Establish the context that shapes their decisions and behavior. + +### Probes (pick 3 to 5 that fit your topic) + +> "Walk me through how you handle [task] today, from start to finish." + +> "What's the last time you [specific behavior or event]? Tell me about that." + +> "Who else is involved when you [activity]? What's their role?" + +> "What tools do you use? Why those specifically?" + +> "What's typical, and what's unusual about how you approach this?" + +> "Where does your [organization / team] stand on [topic]? Any constraints I should understand?" + +### Listening notes + +- Look for specific examples, not generalities. "I've never been frustrated by X" is less reliable than "Tell me about the last time X frustrated you." +- Watch for emotional tone: where do they perk up, get quiet, or shift body language? +- Note any language they use that's different from how the team frames things. + +--- + +## Section 3: The core question (20 to 30 minutes) + +Goal: Address the heart of the research. + +### Sample probes for common research goals + +#### If exploring problems / unmet needs + +> "Tell me about the last time you had to [specific situation related to research]." + +> "What was hardest about that?" + +> "What did you try? What worked, what didn't?" + +> "If you had a magic wand and could change one thing about how this works, what would it be?" + +> "When you think about [topic], what frustrates you most?" + +#### If exploring mental models + +> "How would you explain [concept] to someone who's never heard of it?" + +> "When you hear [term we use], what comes to mind?" + +> "Can you draw or sketch how you think about [process]?" + +> "What's the goal when you [action]? What does success look like?" + +#### If exploring evaluation behavior + +> "Walk me through the last time you decided to [action]. How did you decide?" + +> "What were you comparing? How did you compare them?" + +> "What information would have helped you decide?" + +> "What made you confident in your decision? What made you nervous?" + +#### If exploring product or feature use + +> "Tell me about a time you used [product / feature]. Why? What happened?" + +> "When does [product] work well for you? When does it fall short?" + +> "What's the first thing you do when you open [product]?" + +> "What would have to be true for you to [action: recommend, expand use, switch]?" + +### Probe library (use as needed) + +> "Tell me more about that." + +> "What was that like for you?" + +> "Why does that matter to you?" + +> "Give me an example." + +> "Help me understand what you mean by [term]." + +> "Earlier you said X, now you're saying Y. Help me understand." + +> "What were you thinking at that moment?" + +> "What did you do next?" + +### Things to avoid + +- Leading questions ("Don't you think it would be better if...?") +- Hypothetical questions about future behavior ("Would you pay for...?") +- Multi-part questions +- Filling silence too quickly +- Defending the product +- Selling the product +- Asking "why" more than 2 to 3 times in a row (becomes interrogation) + +--- + +## Section 4: Reactions to specific stimuli (optional, 10 to 15 minutes) + +Goal: Get specific reactions to a concept, prototype, message, or design. Skip if research is purely generative. + +> "I'd love to show you something we're thinking about. There are no wrong reactions - whatever comes up for you is helpful. Take a look [share screen / show prototype / read description]." + +[Wait. Don't fill the silence.] + +> "What's your initial reaction?" + +> "What questions does this raise?" + +> "If you saw this in [context], what would you do next?" + +> "What's confusing or unclear?" + +> "Is there anything that doesn't fit your situation?" + +[Be especially alert to confused expressions, silences, and "I'm not sure what this is for." These are signal.] + +--- + +## Section 5: Wrap-up (5 to 10 minutes) + +Goal: Capture anything missed. Leave the participant feeling good about the experience. + +### Catch-all questions + +> "Is there anything I should have asked but didn't?" + +> "Is there anything you'd want me to know about this topic that didn't come up?" + +> "If you could give one piece of advice to the team building this, what would it be?" + +### Closing + +> "This was incredibly helpful. Thank you for the time and the candor. The [incentive] should arrive [timeline]. If you think of anything else after we hang up, my email is [email]; happy to hear from you. +> +> Last question: would it be okay if I reached out for follow-up research? I won't bombard you, but if something specific comes up and your perspective would be helpful, I'd love to be able to ask." + +--- + +## Post-interview (within 1 hour) + +While memory is fresh: + +- [ ] Write down 3 to 5 most surprising or vivid moments +- [ ] Note any quotes worth coming back to +- [ ] Note any new questions raised by this interview that should change subsequent ones +- [ ] Add to the running synthesis (don't wait to start synthesis until all interviews are done) + +--- + +## Common interview pitfalls and recoveries + +\| Pitfall \| Recovery \| +\|---\|---\| +\| Participant gives short, surface answers \| "Tell me more about that." Or wait silently. Often produces depth. \| +\| Participant goes far off-topic \| "That's interesting. Let me bring us back to [topic]." \| +\| You realize the question was leading \| "Let me ask that differently. What's been your experience with [topic], in your own words?" \| +\| Participant asks what you're working on \| "I want to hear your unbiased thoughts first. Happy to share more at the end." \| +\| Participant tries to give you the "right" answer \| "Honestly, the more frank you can be, including frustrations or criticisms, the more valuable for us." \| +\| You realize you're 20 minutes over \| Wrap promptly. Ask the most important remaining question. End on time. \| +\| Participant has emotional reaction \| Pause. Acknowledge. "That sounds like it was really frustrating. Take your time." Don't rush past. \| + +--- + +## Customization notes + +This template is a scaffold. Adapt: + +- The sections to fit the topic +- The number and type of probes +- The amount of time per section +- Whether to include stimuli (Section 4) + +What stays constant: + +- Open with rapport, not the research question +- Use specific recent examples, not abstract opinions +- Use silence +- Don't lead +- Wrap on time, with grace diff --git a/dist/pi/.agents/skills/vendor-evaluation/SKILL.md b/dist/pi/.agents/skills/vendor-evaluation/SKILL.md new file mode 100644 index 0000000..03b9d4c --- /dev/null +++ b/dist/pi/.agents/skills/vendor-evaluation/SKILL.md @@ -0,0 +1,280 @@ +--- +name: vendor-evaluation +description: "Evaluate, select, and contract with vendors and SaaS tools. Use this skill when comparing alternatives, running an RFP, scoring vendors against criteria, negotiating contracts, planning a switch, or assessing a vendor's risk. Triggers on vendor evaluation, RFP, vendor selection, build vs buy, SaaS evaluation, vendor scorecard, vendor comparison, contract negotiation, vendor switch, procurement. Also triggers when a renewal is coming up or when a tool isn't meeting expectations." +category: process-and-team +catalog_summary: "Tool and vendor selection using a structured rubric" +display_order: 3 +--- + +# Vendor Evaluation + +Pick the right tool or service, negotiate fair terms, and avoid the lock-in traps. Stack-agnostic. Applies to SaaS, infrastructure providers, agencies, and any external dependency. + +--- + +## When to use + +- Selecting a tool or vendor for a new need +- Evaluating alternatives to a current vendor +- Build vs buy analysis +- Renewal coming up: should we stay or switch? +- Running a formal RFP or RFI +- Comparing finalists in a vendor selection +- Negotiating a contract +- Assessing vendor risk (financial, security, dependency) + +## When NOT to use + +- General cost reduction (use `cost-optimization`) +- Specific contract legal terms (those go to legal) +- Performance issues with an existing vendor (try fixing before switching) +- Hiring an agency for a one-off project (lighter framework needed) + +--- + +## Required inputs + +- The need (what problem are you solving, what would success look like) +- Constraints (budget, timeline, integration requirements) +- Stakeholders (users, IT, security, finance, legal) +- Existing context (what's already used, what's been tried) +- Compliance requirements + +--- + +## The framework: 5 phases + +A structured vendor evaluation. Skip phases at your peril. + +### Phase 1: Define the need + +Before looking at vendors, define what you actually need. + +- What problem are you solving? +- What's the user / use case? +- What does "success" look like in 6 months? In 2 years? +- What's the budget (range, not just ceiling)? +- What's the timeline? +- Are there must-have integrations or constraints? + +The temptation: skip this and start demoing. Vendors are happy to show off; you end up choosing what looks shiny rather than what fits. + +### Phase 2: Build vs buy + +Before evaluating vendors, decide whether you should build instead. + +Build when: +- It's core to the business (differentiating) +- The need is so specific no vendor matches +- The economics work at your scale +- You have the team to maintain it +- Vendor lock-in would be unacceptable + +Buy when: +- It's table stakes (not differentiating) +- The need is well-served by existing products +- The economics favor it +- The team should focus elsewhere +- The vendor's specialization beats your generalism + +Most teams over-build. The rule of thumb: buy unless there's a strong reason to build. Then question even that strong reason. + +### Phase 3: Generate the shortlist + +Cast a wider net than feels comfortable, then narrow. + +Sources: +- Internal team's existing knowledge +- Industry analyst reports (Gartner, Forrester, etc.) +- Peer recommendations (other companies similar to yours) +- Reviews (G2, Capterra; with caveats about review quality) +- Adjacent vendors you already use (often have the feature you need) +- Open-source alternatives + +Cast wide first. Aim for 5-8 candidates. Then narrow to 2-4 finalists for deep evaluation. + +### Phase 4: Score the finalists + +Use a scorecard. Without one, you'll be swayed by demo theatrics or who has the friendliest sales rep. + +Scorecard dimensions (weight by your situation): + +Functional fit (40%): Does it do what you need? Edge cases handled? UX quality. Workflow fit. + +Technical fit (15%): Integration with your stack. API quality and completeness. Data export and portability. Performance at your scale. Self-hosted, hybrid, or SaaS-only. + +Operational fit (10%): Onboarding effort. Training and adoption. Documentation quality. Support quality (test by submitting a ticket). SLAs. + +Security and compliance (10%): SOC 2, ISO 27001, HIPAA, etc., as applicable. Data residency. Encryption at rest and in transit. Access controls and audit logs. Penetration test results (ask). Subprocessors. + +Vendor health (10%): Years in business. Funding and runway (or revenue if private). Customer base size and similar customers. Public references. Roadmap visibility. + +Cost (10%): License or subscription cost. Implementation and onboarding cost. Training cost. Integration cost. Opportunity cost (in-house resource time). Switching cost (in case of failure). + +Lock-in risk (5%): Data export quality. Standard formats vs proprietary. Migration paths to alternatives. Open standards alignment. Contract escape clauses. + +Score each finalist 1-5 on each dimension. Multiply by weight. Sum. + +The score isn't gospel. It surfaces the tradeoffs. + +### Phase 5: Negotiate + +Most enterprise contracts are negotiable. Most aren't negotiated. + +What's negotiable: +- Price (multi-year, volume, prepayment, end-of-quarter timing) +- Terms (payment schedule, renewal terms) +- Success commitments (training, onboarding, support) +- SLAs (uptime, response time, credits) +- Termination clauses (auto-renewal, notice period, data export) +- Liability caps and indemnity (legal will care about these) +- Subprocessors and data handling (security/legal cares) + +Common negotiation moves: +- Multi-year discount (3-year for a 15-30% discount is common) +- Volume tiers (commit to higher usage for a per-unit discount) +- Annual prepayment for a discount +- Free or discounted onboarding +- Pilot pricing (trial period at reduced rate) +- "Most favored customer" clauses (if your size warrants) + +What to avoid: +- Multi-year lock with no escape clause for material breach +- Auto-renewal with short notice window (under 60 days; want longer) +- "All right, no further negotiation" stance from the start +- Signing without legal review + +--- + +## Workflow + +### Step 1: Define the need + +Write a one-page brief: what we need, why, success criteria, constraints, stakeholders. + +### Step 2: Build vs buy + +Honestly answer the build/buy question. Document the rationale. + +### Step 3: Generate shortlist + +Wider net first, narrowed via desk research: +- Read summaries +- Skim reviews +- Look at customer logos +- Skim docs +- Skim API specs + +Eliminate obvious misfits. Land on 2-4 finalists. + +### Step 4: Run demos and trials + +For each finalist: +- Demo with the use case (don't take their default demo; bring yours) +- Trial period if possible +- Reference calls with similar customers +- Pilot with real data if feasible + +Don't be charmed by the polished demo. Try it with your real workflow. + +### Step 5: Run security and compliance review + +Critical for any vendor handling sensitive data: +- Request SOC 2 / ISO 27001 reports +- Review their security questionnaire (most have one ready) +- Verify data handling matches your requirements +- Identify subprocessors + +This can take weeks for enterprise vendors. Start early. + +### Step 6: Score + +Apply the scorecard. Do this collaboratively with stakeholders. + +The scoring conversation matters more than the final number. It surfaces disagreement (one person scored UX 5, another scored 2: why?). + +### Step 7: Negotiate + +With the apparent winner: +- Open negotiation by asking for terms (not just price) +- Be willing to walk +- Run negotiations with #2 in parallel where appropriate (gives you leverage) + +### Step 8: Plan the rollout + +Contract signing is the start, not the end. Plan: +- Onboarding owner +- Training plan +- Migration plan if replacing an incumbent +- Success criteria at 30, 90, 180 days +- Renewal calendar + +### Step 9: Document + +Record: +- The decision and the rationale +- Alternatives considered +- Scorecard results +- Negotiated terms +- Renewal date and notice deadlines +- Owner of the relationship + +This is gold for the next renewal or the next similar evaluation. + +--- + +## Failure patterns + +Skipping the needs definition. Demoing first. Buying what's shiny. Realizing 6 months in that the actual need wasn't met. + +Single-source decisions. Talking to one vendor; deciding. No comparison. Probably overpaying or under-fitting. + +Charisma-driven decisions. Buying based on the sales rep's likability. The product is what you'll use for years; the rep won't be there. + +Reference calls that the vendor curated. Of course their references love them. Find references the vendor didn't suggest. + +Glossing over security. Security review skipped because of timeline pressure. Then a breach. Slow down or accept the risk explicitly. + +Demos that don't match the use case. Their default demo, not yours. Always do a use-case demo. + +Trial that doesn't simulate real usage. A trial with synthetic data tells you the product works in synthetic conditions. Use real (or close to real) data. + +Negotiating only on price. Terms, SLAs, and exit clauses matter more for long-term satisfaction than 5% price. + +Auto-renewal without notice tracking. Renewal happens; rate goes up 15%. No one was watching. Track renewals; review with notice. + +Lock-in without exit plan. Tightly integrating into a vendor's proprietary surface. When you want to leave, you can't. Plan exit at the start. + +Multi-year contract for an unproven vendor. Save the multi-year for vendors you trust. New vendor: shorter term, evaluate after. + +No internal champion. Tool selected; no one drives adoption. Tool sits unused. Identify the champion before signing. + +Negotiating after a verbal commitment. "Yes, we want to buy" means they have less reason to negotiate. Keep options open until terms are settled. + +Ignoring red flags in security review. Vendor's security responses are evasive or incomplete. Treat as a no. + +Comparing apples to oranges. Vendors price differently (per user, per usage, flat). Build a comparable cost model at your scale. + +--- + +## Output format + +A vendor evaluation document includes: + +- Need brief: problem, success criteria, constraints +- Build vs buy decision: with rationale +- Shortlist: 2-4 finalists with brief description +- Scorecard: filled out per finalist +- Demo and trial notes: what was learned +- Security and compliance summary: findings per finalist +- Reference call notes: what customers said +- Recommendation: which vendor, with rationale +- Negotiated terms: what was agreed +- Rollout plan: onboarding, training, migration +- Renewal calendar: with notice deadline + +--- + +## Reference files + +- [`references/evaluation-rubric.md`](references/evaluation-rubric.md) - Scoring template with weighted dimensions, 1-5 scale criteria for each dimension, and a worked vendor-comparison example. diff --git a/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md b/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md new file mode 100644 index 0000000..6689c2f --- /dev/null +++ b/dist/pi/.agents/skills/vendor-evaluation/references/evaluation-rubric.md @@ -0,0 +1,178 @@ +# Evaluation rubric + +A scoring template for vendor evaluations. Adapt the dimensions, weights, and scale to fit the decision. + +## The rubric structure + +Score each candidate on each dimension using a 1-5 scale. Multiply by the dimension's weight. Sum for a total. + +Numbers do not make the decision. They make differences visible. Use the totals to challenge your gut, not replace it. + +## Dimensions and what to score + +### Functional fit (typical weight: 25%) + +How well does the product do the specific job? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Does the job exactly. Built for this use case. \| +\| 4 \| Does the job with minor configuration. \| +\| 3 \| Does the job with workarounds or extensions. \| +\| 2 \| Partial fit. Significant gaps. \| +\| 1 \| Wrong tool for the job. \| + +Evaluation method: trial the product on real (or representative) data. + +### Total cost (typical weight: 20%) + +Three-year total cost of ownership, including hidden fees and scaling. + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Cost is well below alternatives. Pricing is predictable. No hidden fees. \| +\| 4 \| Cost is competitive. Pricing scales gracefully. \| +\| 3 \| Cost is fair. Some scaling concerns. \| +\| 2 \| Cost is high or scaling is punitive. \| +\| 1 \| Cost is prohibitive or pricing is opaque. \| + +Evaluation method: project cost at 1x, 5x, and 10x current usage. Read the pricing page line by line. Ask sales for a custom quote at projected scale. + +### Reliability (typical weight: 15%) + +How often does it work? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Strong SLA, public status page, low historical incidents. \| +\| 4 \| Reasonable SLA, transparent status, infrequent incidents. \| +\| 3 \| Standard SLA, some visibility, occasional issues. \| +\| 2 \| Weak SLA, limited visibility, frequent issues. \| +\| 1 \| No SLA, no status page, customer reports of unreliability. \| + +Evaluation method: read the SLA, browse status page history for 90 days, search for outage reports. + +### Integrations and ecosystem (typical weight: 15%) + +How well does it fit your stack and what is the exit story? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Native integrations to your stack, comprehensive API, easy data export. \| +\| 4 \| Most integrations exist or are easy to build. Clean export path. \| +\| 3 \| Some integrations, partial API, exportable with effort. \| +\| 2 \| Limited integrations, weak API, hard to export. \| +\| 1 \| Closed ecosystem, no API, vendor lock-in. \| + +Evaluation method: list the integrations you need. Check each. Test the export. + +### Operational fit (typical weight: 10%) + +How easy is it to run? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Self-service, well-documented, low ongoing burden. \| +\| 4 \| Mostly self-service. Support responds when needed. \| +\| 3 \| Requires some hand-holding from vendor. \| +\| 2 \| Requires significant ops effort or vendor intervention. \| +\| 1 \| Black box that needs constant management. \| + +Evaluation method: read the docs, send a test support question, ask "who would own this internally" and gauge the answer. + +### Vendor durability (typical weight: 10%) + +Will they be around in 3 years? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Profitable, established, deep customer base, growing. \| +\| 4 \| Well-funded, growing, healthy customer base. \| +\| 3 \| Stable but uncertain. Some risk signals. \| +\| 2 \| Layoffs, leadership turnover, customer churn signals. \| +\| 1 \| Likely to be acquired, shut down, or pivot. \| + +Evaluation method: company news search, LinkedIn for headcount trends, customer review sites for sentiment. + +### Support quality (typical weight: 5%) + +What happens when something goes wrong? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Fast, technical, available 24/7 if needed. \| +\| 4 \| Reliable, knowledgeable, business-hours coverage. \| +\| 3 \| Adequate. Sometimes slow. \| +\| 2 \| Slow, scripted, escalation needed for real issues. \| +\| 1 \| Unreachable or unhelpful. \| + +Evaluation method: send a real technical question during the trial. Time the response. Read the answer. + +## Worked example: picking an email service provider + +Job statement: "Send 200K transactional emails per month, 50K marketing emails per month, with deliverability above 98%, webhook delivery confirmation, and integration with our CRM." + +### Weighted scores + +\| Dimension \| Weight \| Vendor A \| Vendor B \| Vendor C \| +\| --- \| --- \| --- \| --- \| --- \| +\| Functional fit \| 25% \| 5 (1.25) \| 4 (1.00) \| 5 (1.25) \| +\| Total cost \| 20% \| 3 (0.60) \| 4 (0.80) \| 2 (0.40) \| +\| Reliability \| 15% \| 5 (0.75) \| 4 (0.60) \| 5 (0.75) \| +\| Integrations \| 15% \| 4 (0.60) \| 3 (0.45) \| 5 (0.75) \| +\| Operational fit \| 10% \| 4 (0.40) \| 5 (0.50) \| 3 (0.30) \| +\| Vendor durability \| 10% \| 5 (0.50) \| 3 (0.30) \| 5 (0.50) \| +\| Support quality \| 5% \| 4 (0.20) \| 4 (0.20) \| 5 (0.25) \| +\| Total \| 100% \| 4.30 \| 3.85 \| 4.20 \| + +### What the numbers say + +Vendor A and Vendor C are close. The difference comes down to cost (B and A both better than C) vs integrations (C better than A and B). + +### What the numbers do not say + +The numbers do not capture: + +- A's pricing has a cliff at 500K monthly emails. We project crossing that within 18 months. +- C has best-in-class deliverability for our specific industry. +- B is rumored to be in acquisition talks. + +The numbers narrow the field to A and C. The qualitative read picks one. In this hypothetical: Vendor C wins on the strength of deliverability and ecosystem fit, despite being more expensive, because deliverability is the actual job and cost is recoverable. + +### What the decision memo looks like + +``` +Vendor: C +Reasoning: +- Best functional fit on deliverability and webhook reliability. +- Strongest ecosystem and exit story. +- Higher cost is justified by ROI from deliverability lift. +- A was a strong second; we will revisit if C disappoints in + year 1. + +Decision date: [date] +Reviewer: [person] +Next review: [date + 12 months] +Contract terms: +- 1-year commit, with option to extend +- Termination notice: 60 days +- Data export confirmed working in trial +``` + +## Adapting the rubric + +Different decisions weight dimensions differently. Some examples: + +- Hosting decision: reliability and operational fit weighted higher. +- CMS decision: functional fit and integrations weighted higher. +- Analytics decision: vendor durability and integrations weighted higher (you keep data here for years). +- Payment processor decision: reliability, support quality, and vendor durability weighted higher. + +Adjust weights before scoring. If you adjust after, you are rationalizing. + +## How to use the rubric without lying to yourself + +- Score independently first if multiple stakeholders are evaluating. Compare scores. Discuss the differences. +- Sleep on the scores before deciding. +- If the math points to a vendor your gut hates, find out why. Either the rubric is missing a dimension or your gut is wrong. Both happen. +- Document the score, the weights, and the qualitative notes. Store with the contract. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md b/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md new file mode 100644 index 0000000..b9f6e22 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/SKILL.md @@ -0,0 +1,213 @@ +--- +name: vertical-site-conventions +description: "Compose pages and sites that read as their vertical: ecommerce-catalog storefronts that look like storefronts, hospitality-food sites that look like restaurants, b2b-manufacturer sites that look industrial. Use this skill whenever the user wants to build a site that looks like the vertical it serves, fix a build that reads as generic or off-vertical, build to an experience bar produced by competitor-experience-audit, or compose pages with the merchandising, density, and layout conventions a credible site in the category is expected to carry. Triggers on vertical conventions, storefront layout, ecommerce layout, retail conventions, merchandising layout, category page composition, site composition, build to the experience bar, make it look like the vertical, off-vertical, looks generic, build conventions for a vertical, site grammar. Also triggers when a build that is technically clean reads wrong for its category, and the cause is composition, not visual taste." +category: design +catalog_summary: "Vertical page and site composition built to the experience bar" +display_order: 4 +--- + +# Vertical Site Conventions + +Compose pages and whole sites to the layout, density, and merchandising conventions that make a build read as a credible member of its vertical. Stack-agnostic. Works on any framework that can express server-rendered pages and component composition. + +This skill owns vertical-level composition: which modules go where, how dense the page is, how much of the catalog or offering is surfaced, and which paths the navigation serves. It routes the day-to-day visual decisions to `design-standards`, the aesthetic register to `creative-direction`, the site-structure modeling to `information-architecture`, and the component implementation to `frontend-component-build`. It does not duplicate any of them; it composes their outputs into a vertical-correct site. + +It is the build-side counterpart to `competitor-experience-audit`. The audit measures the field on seven dimensions; this skill builds to those same seven, dimension by dimension. The two are deliberately structured as two sides of one standard so an experience bar produced by the audit maps one-to-one onto what this skill builds. + +--- + +## When to use + +- Building a new site in a vertical you have not built in before +- Fixing a build that reads as generic or off-vertical even though it is technically clean (the SEO, accessibility, and component implementation are correct, but the page does not read like its category) +- Building to an experience bar produced by `competitor-experience-audit` (the audit-fed path is the intended use) +- Adding the merchandising, density, and navigation conventions a site in this category is expected to carry +- Building a showcase or demo where the build must read as its vertical, not as a generic SaaS landing page + +## When NOT to use + +- Day-to-day visual decisions on a known build (use `design-standards`) +- Defining the brand register or aesthetic from scratch (use `creative-direction`, `brand-archetype-system`, `brand-discovery`) +- Building one component well (use `frontend-component-build`) +- Modeling site structure and navigation hierarchy from scratch (use `information-architecture`) +- Building a formal design system or token system (use `design-system`) +- Auditing the competitive field for what conventions exist (use `competitor-experience-audit`; this skill consumes that audit's output, it does not produce it) + +--- + +## Required inputs + +- The site shape the build is for, from the controlled list: `ecommerce-catalog`, `inventory-listing`, `directory-marketplace`, `local-service-booking`, `subscription-app`, `hospitality-food`, `institution-mission`, `b2b-manufacturer`, `ecommerce-standout`, `hospitality-experience`. +- An experience bar from `competitor-experience-audit` (the cross-site patterns and gaps for the vertical). If absent, the skill falls back to the per-shape default conventions in the references; the audit-fed path is stronger and is the intended use. +- The brand register and aesthetic decisions (from `creative-direction` or already settled). This skill does not redefine them. +- The framework or technical context the build will use (the skill is stack-agnostic but the consumer needs to know). + +If the site shape is unclear, ask. Building to the wrong shape's conventions produces a build that reads off-vertical, which is the exact failure this skill exists to prevent. + +--- + +## The framework: build to the seven dimensions + +The framework mirrors the seven dimensions `competitor-experience-audit` measures. Each is expressed here as build guidance (what to do) rather than audit questions (what to observe). Run them in order; the synthesis in dimension 7 is the composition checklist that catches what the earlier six missed. + +### 1. Build the primary task as the dominant, earliest element + +The visitor arrives with a primary job. The leaders in the vertical lead with that job; off-vertical builds bury it behind marketing copy or competing CTAs. + +- Identify the vertical's primary task from the experience bar or the per-shape reference. (Ecommerce-catalog: a fitment, search, or category-entry interaction. Hospitality-food: a menu or reservation entry. Inventory-listing: a search-and-filter. Local-service-booking: a "book now" or service-picker.) +- Give that task the largest, earliest interactive treatment in the hero. +- Demote competing CTAs. The hero gets one primary action; secondary actions live below the fold or in the chrome. +- Reach the core task without scrolling on the device class the vertical's visitors use. +- For commercial pages, sticky a compact version of the primary task to the chrome so it stays reachable on scroll. + +If the primary task cannot be the hero (a constraint from a stakeholder, a regulated vertical), surface the closest equivalent and document the compromise. Do not silently push the primary task below the fold. + +### 2. Build to the vertical's layout register and density + +Most off-vertical builds default to a generic SaaS-airy landing page. Retail and catalog verticals are denser; editorial verticals are calmer; hospitality is image-led. Build to the field's density, not to a default. + +- Identify the register from the experience bar or the per-shape reference (storefront-dense, editorial-calm, marketing-airy, image-led). +- Match the field's content-per-viewport: a catalog vertical surfaces more modules above the fold than a SaaS landing page. +- Choose the module count above the fold deliberately. State the count in the build notes. +- Route the actual color, type, and aesthetic choice to `creative-direction` and `design-standards`. This skill owns the density and module-count decision, not the visual register itself. + +Composition decision lives here. Visual register lives there. Do not redefine either; route to the right skill. + +### 3. Build the merchandising and category surface the vertical uses + +How much of the catalog or offering is surfaced at once, and in what shape, is a per-vertical decision the build must own. + +- Surface the catalog the way the vertical does: how many category, collection, or entry-point modules appear before scroll. +- Signal depth the way the vertical signals it: mega-menu hover, grid of category cards, faceted-search side rail, breadcrumb-driven hierarchy. Pick one and commit; do not stack three. +- Choose flat (one tier visible) or hierarchical (parent plus child categories shown together) per the vertical's convention. +- Use icon / image / text / hybrid category presentation per the vertical. + +Cross-reference `information-architecture` for the structural modeling of the nav tree. This skill owns the compositional surface; that skill owns the structural model. + +### 4. Build both the know-what-I-want and the browse path the vertical expects + +Verticals differ on which path is primary. A catalog vertical needs both search and category browse, with search often primary. A hospitality-food site rarely needs search but always needs a menu and a reservation entry. Build to the paths the field actually offers, in the prominence the field gives them. + +- List the paths the experience bar names (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience). +- Score each path as primary, secondary, or absent per the vertical. +- Build the primary paths into the hero or primary nav. Build the secondary paths into the chrome or below the fold. Drop the paths the field does not use. +- Search input prominence is a per-vertical decision: header-primary, secondary in a side rail, or absent. Match the field. + +Route the structural nav modeling to `information-architecture`; route the search UX patterns to that skill or to the project's existing search component. This skill owns which paths exist and how prominent each is. + +### 5. Build the brand posture consistently across the page + +The brand register is set by `creative-direction` and `brand-archetype-system`. This skill does not redefine it. But composition decides whether the posture holds across the page or only in the hero. + +- Carry the brand register from the hero into the nav, the cards, the empty states, the trust signals, and the footer. A premium-utilitarian register that disappears below the hero is a composition failure, not a brand failure. +- Apply the voice consistently in headings, microcopy, CTAs, and empty states. Do not let the empty states default to generic copy. +- Hold the imagery posture across the page: a vertical that uses studio product photography in the hero does not switch to abstract illustration in the trust section. + +Route the actual register choice and the voice attributes to `creative-direction` and `brand-voice`. Own the consistency requirement here. + +### 6. Build the trust and conversion signals the vertical requires + +Each vertical has a different set of trust signals it is expected to carry. A build that ships without them reads as not-yet-credible. Build them in. + +- Identify the required signals from the experience bar or the per-shape reference. (Ecommerce-catalog: reviews, guarantees, pricing transparency, stock signals, fitment confirmation, shipping promises. Hospitality-food: hours, location, reservation availability, menu price range. B2b-manufacturer: certifications, customer logos, spec sheets. Local-service-booking: licensing, insurance, service-area, response time.) +- Surface them where the field surfaces them. Reviews near the buying action; service-area in the hero; certifications in the chrome. +- Honor the functional-vs-demo line for showcase builds: real where touchable (real reviews if they exist, real cart state), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment). + +### 7. Run the synthesis as a composition checklist + +The seventh dimension is the synthesis: the specific conventions a credible build in this vertical must have, named explicitly. Run this as a pre-ship checklist before declaring the composition done. + +- Pull the conventions from the experience bar's dimension 7, or from the per-shape reference's recurring-conventions section. +- For each, confirm the build does it. Mark each item present, absent, or routed elsewhere (with a link to the routing decision). +- If three or more conventions are absent, the build is off-vertical. Go back to the earlier dimensions; this is not a polish-pass fix. +- If one or two are absent, name the reason: deliberate positioning (the wedge the build is exploiting from the audit's gaps section), constraint (stakeholder, technical), or oversight (fix before ship). + +The synthesis is what catches builds that pass dimensions 1 through 6 individually but compose into something off-vertical anyway. Run it. + +--- + +## How the skill consumes an experience bar + +When `competitor-experience-audit` has run for the vertical, its output is the input to this skill. The audit's seven dimensions map directly onto this skill's seven, in order. Concretely: + +- The audit's `Primary-task prominence` pattern names what to build in this skill's dimension 1. +- The audit's `Layout register and density` pattern names the density target for dimension 2. +- The audit's `Merchandising and category surface` pattern names the surface shape for dimension 3. +- The audit's `Primary navigation and search paths` pattern names the path inventory for dimension 4. +- The audit's `Brand register and conviction` pattern names the register `creative-direction` should be working from, which this skill carries across the page in dimension 5. +- The audit's `Trust and conversion signals` pattern names the required signals for dimension 6. +- The audit's `Recurring vertical conventions` are the checklist for dimension 7. +- The audit's `Gaps` section names the positioning opportunity the build can exploit as its wedge. + +If no audit has been run, fall back to the per-shape reference files in `references/`. The default conventions there are derived from observable cross-site patterns and are honest, but a vertical-specific audit is stronger and is the intended path. + +--- + +## Stays in its lane (load-bearing) + +This skill owns one thing: vertical-level page and site composition. It routes everything else, and that routing discipline is what keeps it useful and what keeps the catalog clean. + +- Visual tokens, color, type, contrast, spacing scale: route to `design-standards`. +- Aesthetic register, archetype, voice attributes: route to `creative-direction` and `brand-archetype-system`. +- Site structure, nav hierarchy, URL design: route to `information-architecture`. +- Component API, states, accessibility implementation: route to `frontend-component-build`. +- Formal design system, token library, component documentation: route to `design-system`. +- The audit that produces the experience bar: route to `competitor-experience-audit`. +- On-page SEO and accessibility audits: route to `seo-onpage` and `accessibility-audit`. + +If a build decision sits inside one of those skills, do not restate the standard here. Link to the skill and let it own its territory. + +--- + +## Workflow + +1. Confirm the site shape and the experience bar. Site shape from the controlled list. Experience bar from `competitor-experience-audit` if run; the per-shape reference otherwise. +2. Run dimensions 1 through 6 in order. For each, name the build decision and which other skill it routes to (for the parts that route elsewhere). +3. Run dimension 7 as a checklist. Confirm every recurring convention from the vertical is present, absent for a stated reason, or routed elsewhere. +4. Write the composition notes. Use the template in [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md). The notes are what `frontend-component-build` and `design-standards` read as the spec to implement against. +5. Hand off to the implementation skills. This skill's output is composition decisions, not finished components. The build is done when those decisions have been implemented through `frontend-component-build`, `design-standards`, and the project's component library. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Make it look modern." Vague. Ask which vertical, which experience bar, which conventions. "Modern" without a vertical produces the generic SaaS-airy build this skill exists to prevent. +- Building to a generic / SaaS-airy default when the vertical wants a denser storefront. Retail and catalog verticals surface more per viewport than a marketing page. If the build looks calm and roomy, check the density against the field. +- Burying the primary task. A hero stuffed with marketing copy and three competing CTAs is the most common off-vertical failure. Dimension 1 is not optional. +- Redefining aesthetic vocabulary instead of routing to `creative-direction`. This skill does not coin new register names or invent new voice attributes. If the question is what posture the brand takes, that is `creative-direction`'s call. +- Treating the experience bar as optional when it is available. If `competitor-experience-audit` has run for the vertical, the bar is the spec. Building to the per-shape default while ignoring the audit's bar is half a build. +- Producing a template instead of building to the field's actual conventions. Per-shape references are starting points, not finished templates. They name the patterns the field shares; the build still has to land them in this brand and this brief. +- Skipping dimension 7. A build that passes dimensions 1 through 6 individually can still compose off-vertical. The synthesis check is the one that catches it. +- Calling implementation detail "composition". Button radius, font size, color contrast are `design-standards` decisions. Module count, primary-task prominence, category-surface depth are this skill's decisions. Do not bleed across the line. + +--- + +## Output format + +Default output is a markdown set of composition notes at `composition-[site-shape]-[brand-slug].md` in the project root. Structure: + +1. The site shape and the experience bar consulted (or "no audit available; per-shape reference used") +2. Dimension-by-dimension build decisions (1 through 6) +3. The synthesis checklist (dimension 7), each convention marked present / absent / routed +4. The wedge (which gap from the audit's gaps section this build is exploiting, if any) +5. The hand-off list: what `frontend-component-build`, `design-standards`, and `creative-direction` need from these notes to implement + +Keep notes under 1500 words. The notes are a spec for the implementation skills; if they need more detail, that is a sign one of those skills should own the deeper specification. + +--- + +## Reference files + +- [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md) - The per-dimension build checklist applied as a pre-ship review. Mirror of the audit's dimension checklist on the build side. +- [`references/shape-ecommerce-catalog.md`](references/shape-ecommerce-catalog.md) - Default conventions for the ecommerce-catalog shape (first test case; auto-parts and similar dense storefronts). +- [`references/shape-inventory-listing.md`](references/shape-inventory-listing.md) - Stub; fill when the first inventory-listing demo is built. +- [`references/shape-directory-marketplace.md`](references/shape-directory-marketplace.md) - Stub. +- [`references/shape-local-service-booking.md`](references/shape-local-service-booking.md) - Stub. +- [`references/shape-subscription-app.md`](references/shape-subscription-app.md) - Stub. +- [`references/shape-hospitality-food.md`](references/shape-hospitality-food.md) - Stub. +- [`references/shape-institution-mission.md`](references/shape-institution-mission.md) - Stub. +- [`references/shape-b2b-manufacturer.md`](references/shape-b2b-manufacturer.md) - Stub. +- [`references/shape-ecommerce-standout.md`](references/shape-ecommerce-standout.md) - Stub. +- [`references/shape-hospitality-experience.md`](references/shape-hospitality-experience.md) - Stub. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md new file mode 100644 index 0000000..5b9abf4 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md @@ -0,0 +1,120 @@ +# Shape: b2b-manufacturer + +Industrial manufacturers, robotics, machine tools, components, OEMs, industrial integrators. The reader arrives as a buying engineer, a procurement specialist, an operations leader, or an industrial integrator, wanting specs, applied examples with named metrics, certifications, and a short path to an engineer-not-a-sales-rep. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (robotics, machine tools, semiconductor equipment, industrial sensors), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: see the products with specs visible, see the applied examples with named metrics, and request a demo or working session with an application engineer. The B2B-manufacturer conversion is a sales conversation, not a transactional add-to-cart; the page is a credibility document and a routing tool. + +Build conventions: +- The demo / contact action is in the chrome on every page AND in the hero AND at the end of each product detail page. Three placements, one form. +- The form is short. Six fields at most (name, company, work email, role, product of interest, problem statement). Long forms signal funnel-thinking; the field's leaders treat the first call as a working session, not a qualification step. +- Specs are surfaced in HTML, not in a PDF gated behind a marketing form. PDF datasheets exist for downloading after the page has done its job, not as the only path to the spec. +- The site does not invent dollar figures for products that are quote-based. Quote-based products carry "request a quote" or "talk to engineering," not "$ X." + +## 2. Layout register and density + +Register: technical-considered. Denser than a SaaS marketing page; less dense than an ecommerce catalog. Photography is industrial: factory floor, product close-up on a clean concrete surface, single subject. Cinematic, restrained, not Instagram. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: a single-subject hero photograph of a product (or a representative product), a declarative one-line manifesto or capability statement, the demo CTA, AND a product-or-application strip. A B2B-manufacturer hero that leads with a marketing slogan and no product visible reads as a brochure, not equipment. +- The hero photograph is industrial, not lifestyle. Equipment on the factory floor or in studio; no humans in lab coats unless they are doing real work. +- Whitespace is engineered, not generous. The page is a working document. Editorial-airy layouts read as off-vertical; catalog-dense layouts read as wrong too. A considered mid-density grid is the convention. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be cinematic-premium (anode-ev style: drivetrain-as-design), technical-considered (edge-devtools style: spec-as-page), institutional-professional (counsel-law style: certification-led), or rugged-utilitarian (forge-fitness style: equipment-as-tool); not flowery or expressive. + +## 3. Product surface + +Conventions: +- A product listing page carries each product line with a name, a tagline (one declarative sentence), three to six headline specs, a product image, and a link to the detail page. +- A product detail page carries: full spec table (payload, reach, repeatability, latency, IP rating, safety standards, integration interfaces), the blurb, a primary product image plus at least one secondary image (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot), the certifications applicable to this product, the applications that use it, a demo CTA wired to this product, integration-interface section (OPC UA, EtherNet/IP, REST API, etc.). +- Specs are an HTML table, not an image of a table from a PDF. Crawlers and screen readers read it; copy-paste works. +- Product imagery is real, single-subject, industrial-product photography. Premium register matching the brand (factory-floor or studio backdrop, controlled lighting, the machine as the subject). Spec tables alone read as a brochure-with-numbers; a buyer needs to see the machine. Specs remain the spine of the page; imagery supports the specs, it does not replace them. +- Certifications are carried at the product level on the detail page, not buried on About. A buyer screening for "must be ISO 10218 certified" should see the certification on the product page in under three seconds. +- Quote-based pricing is named openly. "Quote-based"; "Talk to engineering"; "Configurations vary by integration." A blank price field signals "this is hidden from me" rather than "this is configured to your line." +- Product imagery is honest-demo where the build is a showcase: unbranded equipment, no fabricated competitor logos, no real-world manufacturer brand marks, no baked-in pricing or spec text in the image (specs live in HTML). Industrial-product image generation is prone to hallucinating brand badges and control-panel writing; the image-pipeline gate's brand-name and fabricated-logo checks are load-bearing here. + +## 4. Applications surface (the case studies) + +Conventions: +- An applications page with named industries and named metrics. Battery cell assembly, warehouse throughput, precision machining, automotive sub-assembly. Each application named with the cycle time, the throughput change, the payback period, the first-pass yield, the operator-hours saved. +- Genericized marketing prose ("a global leader in X partnered with us") is the field's miss; the convention is to name the metric even if the customer is anonymized. "Throughput up 38%. Scrap rate down 22%. Cycle time per module under nine seconds." Pattern-level facts are credible; vague success language is not. +- Each application links to or references the products it uses, so a reader who arrived via Products can cross-walk to Applications and back. +- For showcase or demo builds, the functional-vs-demo line: pattern-level facts are acceptable but should be labeled as such in the workup; the build should not imply a real anonymized customer when one does not exist. + +## 5. Company, certifications, and engineering posture + +Conventions: +- A Company page with founding year, headquarters, certifications, plain-language about the engineering posture. Not a brand story. +- Certifications baseline at the company level (ISO 9001, ISO 10218, UL, AS9100, IEC 61508, etc.) and at the product level on each detail page. Buyers screen for these; making them findable is a credibility move. +- Made-in-X is named openly if relevant (made in Pittsburgh, designed in Munich, assembled in Taiwan). Country of design and country of manufacture are different and both are surfaceable. +- Founding team, depth of bench, customer count, plant size are facts a buyer's committee asks for; the page should answer them without forcing a sales conversation first. +- The engineering posture (what the company believes about how to build equipment) is a real thing to name. "The factory is the test bench" or "every product runs on our own line before it ships" is the kind of plain claim that does the work brand-essay generic copy fails to do. + +## 6. JSON-LD and structured data + +Conventions: +- Organization schema at the layout level: name, description, url, logo, founding date, address. +- Product schema on each product detail page: name, description, category, brand, manufacturer, sku, identifier. +- Where pricing is quote-based, omit the price field rather than fake one. Structured-data validators flag missing price; the buyer reads quote-based as honest. +- BreadcrumbList on every page beneath the home. + +## 7. Demo / contact flow + +Conventions: +- The demo form is on-site, six fields, no third-party gating. Form mounts the same component everywhere. +- The form does not require a phone number to submit; phone is optional. +- The "what happens next" copy is honest. "An application engineer reaches out within one business day to schedule a working session" is the field's leader posture. "A representative will be in touch shortly" is the field's miss. +- Phone-as-fallback: a visible phone number for buyers who would rather call. +- For procurement-led conversations, a separate "Request a quote" path that asks for the line spec (units per year, integration constraints, certifications required) is conventional; for a single-build demo, the demo form covers both. + +## 8. Trust and conversion signals + +Signals this shape carries: +- Specs visible, in HTML, on every product page. +- Applications named with named metrics. +- Certifications surfaced at the product level. +- Plain company facts (founding, headquarters, plant size, deployment geography). +- Engineering-posture statement that names what the company believes. +- Optional but conventional: a named-publication pull-quote or analyst quote ("X named Volta to the top tier"). Logo walls are the field's miss; one named pull-quote is the convention. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction, real spec tables), honestly demo where it needs a backend (clearly labeled demo request modal, no fake CRM entry, no fake customer logos). + +## 9. Recurring vertical conventions (the synthesis) + +A credible B2B-manufacturer site, against the field of leaders, carries eleven conventions: + +1. A single-subject industrial hero photograph above the fold at a 1280x800 desktop viewport, with a declarative one-line manifesto and the demo CTA. +2. (Density-bearing) Specs surfaced as an HTML table per product, not gated behind a PDF. +3. A product listing page with each product line, its tagline, three to six headline specs, and a product image visible per line. +4. A product detail page with full spec table, certifications at the product level, applied applications, and a demo CTA wired to the product. +5. (Density-bearing) An applications page with named industries and named metrics (cycle time, throughput change, payback period, first-pass yield); no genericized "global leader in X" prose. +6. A Company page with founding year, headquarters, certifications, and an engineering-posture statement that names what the company believes. +7. JSON-LD Organization at the layout level; Product schema on each product detail page (with the primary and secondary image URLs populated under image). +8. (Density-bearing) A demo / contact form that is on-site, six fields, no third-party gating; the demo flow lives within the site's visual contract. +9. Honest "what happens next" copy on the demo path; phone-as-fallback visible. +10. Where pricing is quote-based, no fake dollar figures; the page names the quote-based posture openly. +11. (Density-bearing, new) Real product imagery on the product surface. Each product detail page carries a primary product image plus at least one secondary (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot). Product listing cards lead with a product image above the spec table, not specs alone. Premium / industrial / single-subject register, honest-demo where the build is a showcase (no fabricated brand marks or pricing baked into the imagery). Spec tables remain the spine of the page; imagery supports the specs, it does not replace them. + +Threshold and density-bearing items. A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 5, 8, and 11 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a brochure, a lead-gen funnel, or a half-built equipment site instead of a credibility document. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of the density-bearing four will make the build read off-vertical regardless of how many other conventions it hits. Treat the density-bearing items as non-skippable. + +Why convention 11 needed to be added separately. The first b2b-manufacturer build (Volta Robotics) carried conventions 1 through 10 cleanly: spec tables in HTML, named-metric applications, six-field on-site demo form, certifications at the product level, JSON-LD Product schema. It passed the checklist and still read thin against a premium-industrial buyer's eye: one hero image, then spec-only product cards on the lineup and spec-only detail pages. A premium capital-equipment buyer expects to see the machine, multiple angles, in-context on a line. The model flagged it, the human confirmed it. A spec-led build can be checklist-correct and still register as a brochure-with-numbers rather than equipment. Convention 11 closes that gap: the product surface carries real product imagery as a chrome-level convention, not a polish extra; the spec table is the spine and the imagery is the evidence the spine describes a real machine. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Specs are the page. Most competitors gate specs behind a marketing form for a PDF download. A build that surfaces the full spec table in HTML on every product page owns the "we are not afraid of comparison" position. +- Named metrics on the applications page. Most competitors write applications in genericized marketing prose. A build that names cycle time, throughput change, and payback period (even with the customer anonymized) owns the "we ship outcomes, not narratives" position. +- Engineer-facing demo flow. Most competitors route demo requests through marketing-gated long forms with MQL scoring. A build that runs a six-field on-site form and connects to an application engineer (not a sales rep) owns the "first call is a working session" position. +- Certifications at the product level. Most competitors mention certifications on About. A build that carries the applicable certifications on each product detail page owns the "we screen the way your committee does" position. +- Engineering-posture statement. Most competitors write a brand story. A build that names a plain engineering belief ("the factory is the test bench"; "every product runs on our own line before it ships") owns the "we mean what we say" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md new file mode 100644 index 0000000..17b57ae --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-conventions-checklist.md @@ -0,0 +1,97 @@ +# Vertical Site Conventions Checklist + +Run this checklist as the composition pre-ship review. It mirrors the seven dimensions `competitor-experience-audit` measures, on the build side. Mark each item present, absent for a stated reason, or routed elsewhere (with a link). + +Three or more absences across the seven dimensions means the build is off-vertical and needs composition work, not a polish pass. + +--- + +## 1. Primary-task prominence + +- [ ] The vertical's primary task is named (from the experience bar or per-shape reference). +- [ ] The primary task is the largest, earliest interactive element in the hero. +- [ ] No competing CTA is louder than the primary task in the hero. +- [ ] The primary task is reachable without scroll on the device class the vertical's visitors use. +- [ ] A compact version of the primary task is sticky to the chrome on scroll (for commercial pages). +- [ ] If the primary task is not the hero, the compromise is documented and the closest equivalent is surfaced. + +## 2. Layout register and density + +- [ ] The vertical's register is named (storefront-dense, editorial-calm, marketing-airy, image-led). +- [ ] The module count above the fold is decided deliberately, not by default, and matches the field's content-per-viewport. +- [ ] The visual register (color, type, aesthetic) is routed to `creative-direction` and `design-standards`, not redefined here. +- [ ] The page does not default to a generic SaaS-airy layout when the field uses a denser register. + +## 3. Merchandising and category surface + +- [ ] The number of category, collection, or entry-point modules above the fold matches the field. +- [ ] The depth signaling pattern is chosen and committed to (mega-menu, grid, faceted side rail, breadcrumb hierarchy). Not stacked. +- [ ] Flat or hierarchical category presentation matches the vertical. +- [ ] Category presentation style (icon, image, text, hybrid) matches the field. +- [ ] The nav tree structural modeling is routed to `information-architecture`, not redefined here. + +## 4. Navigation and search paths + +- [ ] The paths the field offers are inventoried (by category, brand, attribute, vehicle, location, occasion, audience). +- [ ] Each path is scored primary, secondary, or absent against the vertical. +- [ ] Primary paths land in the hero or primary nav; secondary paths land in chrome or below the fold. +- [ ] Search input prominence matches the vertical (header-primary, secondary side-rail, or absent). +- [ ] Paths the field does not use are not surfaced (do not invent paths the vertical does not carry). + +## 5. Brand register and conviction + +- [ ] The brand register is set by `creative-direction` and `brand-archetype-system`, not by this skill. +- [ ] The register carries from the hero into the nav, cards, empty states, trust signals, and footer. +- [ ] Voice is applied consistently in headings, microcopy, CTAs, and empty states. Empty states do not fall back to generic copy. +- [ ] Imagery posture is consistent across the page (no switch from studio photography to abstract illustration mid-page without a reason). + +## 6. Trust and conversion signals + +- [ ] The vertical's required signals are inventoried from the experience bar or per-shape reference. +- [ ] Each required signal is built into the page where the field places it (reviews near the buying action, service-area in the hero, certifications in the chrome, etc.). +- [ ] For showcase or demo builds, the functional-vs-demo line is honored: real where touchable, honestly demo where it needs a backend (clearly labeled demo modals, no fake payment, no real account creation). + +## 7. The synthesis: recurring vertical conventions + +Pull the conventions from the experience bar's dimension 7 (or the per-shape reference's "recurring conventions" section). For each: + +- [ ] Convention 1: __________________ , [present / absent (reason) / routed to ____] +- [ ] Convention 2: +- [ ] Convention 3: +- [ ] Convention 4: +- [ ] Convention 5: +- [ ] Convention 6: +- [ ] Convention 7: +- [ ] Convention 8: +- [ ] Convention 9: +- [ ] Convention 10: +- [ ] (Add rows as needed for the vertical's full convention list.) + +Density-bearing items. Some conventions are density-bearing: their absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. For the ecommerce-catalog shape, conventions 2 (category surface band above the fold at 1280x800), 9 (a promotional or deal surface near the top), and 10 (an inventory or catalog-depth signal a first-time visitor sees) are the density-bearing trio. Each shape's per-shape reference names its own density-bearing items. + +Mark the density-bearing items explicitly in the list above. Missing any one density-bearing item is sufficient to fail the synthesis on its own, regardless of how many other conventions hit. This rule comes from a real build hitting 6 of 8 conventions in an earlier (pre-density-bearing) form of this reference and still reading off-vertical because the density-bearing items it missed were the load-bearing ones. + +Threshold: a build hitting 8 of 10 (or the equivalent ratio for shapes with a different convention count) is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more conventions, OR any density-bearing item, is off-vertical and needs composition work, not a polish pass. Go back to dimensions 1 through 6. + +--- + +## The wedge + +If the experience bar named a recurring gap across the field, the build can exploit it as positioning. State which gap is being exploited and how the build addresses it. + +- Gap exploited: [from the audit's gaps section] +- How the build addresses it: +- What that buys the build: + +If the build is not exploiting a gap, that is fine; the build hits the experience bar and competes on execution. Say so explicitly. + +--- + +## Hand-off list + +- [ ] `frontend-component-build`: the components the build needs and the states each must support. +- [ ] `design-standards`: the tokens, contrast, and spacing the composition assumes. +- [ ] `creative-direction`: the register and voice the composition carries. +- [ ] `information-architecture`: the nav tree and URL structure the composition expects. + +The hand-off list is what makes this skill's output a real spec for the implementation skills, not a wish list. Each item should be specific enough that the implementation skill can read it and start. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md new file mode 100644 index 0000000..50a1acd --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-directory-marketplace.md @@ -0,0 +1,19 @@ +# Shape: directory-marketplace + +Service-provider directories, home services marketplaces, freelance / contractor matching. The reader arrives wanting to find a provider for a need they can name. + +## Status + +Stub. Fill when the first directory-marketplace demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: describe the need (service, location, urgency) and surface ranked providers. Often a wizard pattern (service picker, then ZIP, then refine). +- Layout register: trust-led and service-led. Photos of providers, ratings, and quoted response time carry the page. +- Merchandising: the provider list is the merchandising. Hero often carries a service-picker plus a band of top categories. +- Paths: by service category primary; by location primary; by provider (named) secondary. +- Brand register: marketplace-neutral or strongly opinionated (premium-curated vs widest-net). Cross-reference `creative-direction`. +- Trust signals: verified, licensed, insured, response time, ratings with review count, dispute resolution promise. +- Synthesis (provisional): service picker as the first interaction, location capture early, provider ratings with substantive review counts, response-time signal, clarity on what is curated vs open. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md new file mode 100644 index 0000000..fae3e57 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md @@ -0,0 +1,119 @@ +# Shape: ecommerce-catalog + +Dense catalog storefronts. Auto-parts, hardware, industrial supply, mass-merchant retail. The reader arrives with a part to find or a category to browse. The build leads with the path that gets them to the part. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (auto-parts, hardware, tooling), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: the path to a part. For verticals where compatibility matters (auto-parts, electronics), this is a fitment / compatibility selector. For undifferentiated catalogs (hardware, office supply), this is a search input. For mass merchants, this is category-entry-grid. + +Build conventions: +- The primary task is the largest, earliest interactive element. Not a sidebar widget; not a modal triggered by a marketing CTA. +- Competing CTAs (newsletter, account, brand pitch) live below the fold or in the chrome. +- The primary task is sticky to the chrome on scroll. A visitor mid-page who realizes the fitment is wrong can change it without scrolling back to the hero. +- For fitment-led verticals: setting the vehicle / compatibility once carries to every subsequent page. The selection is the global context, surfaced visibly. + +## 2. Layout register and density + +Register: storefront-dense. Not editorial; not marketing-airy. The page is a working surface, not a brand brochure. + +Build conventions: +- More than four modules above the fold on desktop is normal for this shape. Two-module heros are off-vertical. +- Above the fold at a 1280x800 desktop viewport (not "the first or second viewport"; the assertion is hard) the page carries: the primary task, the category surface band, AND at least one merchandising or trust signal. A category band that requires any scroll to reach reads as airy and off-vertical for this shape; a real build verifies this against a rendered capture, not in prose. +- Whitespace is functional, not generous. The leaders in this shape are dense; an airy build reads as not-a-real-store. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be utilitarian, premium-utilitarian, or technical; not flowery or expressive. + +## 3. Merchandising and category surface + +Conventions: +- A category surface band sits above the fold at a 1280x800 desktop viewport. Eight to twelve category entry points is typical for a wide catalog; four to six for a focused one. ("First or second viewport" is too loose; a real build hit that and still read airy because the band slipped below the fold.) +- Depth signaling is one of: mega-menu hover (broad catalogs), grid of category cards on the home (narrow catalogs), faceted-search side rail on category pages. Pick one; do not stack. +- Category cards carry an icon, an image, or a tight text-only treatment. Hybrid icon-plus-text reads as catalog; image-only reads as marketing. +- Hierarchical surface (parent plus child categories) is conventional for broad catalogs. Flat surface fits focused catalogs. +- A promotional or deal surface lives near the top: a deal-of-the-week strip, a promo band, a featured-offer row. The field carries it to signal "this is an active store with offers." Its absence reads as brochure-like rather than storefront-like. The promo can be a single strip with one or two offers; it does not have to be a full module. +- An inventory or catalog-depth signal appears somewhere a first-time visitor will see it: a part count, "12,000+ parts in stock," a category-count figure, or a near-equivalent that establishes the catalog has real depth. The field carries it as a credibility move; its absence reads as a thin or demo catalog. The figure can be approximate, can be in the hero, the trust band, or the chrome. +- Featured / promoted collections appear below the category surface, not above; categories carry the navigation load. (The promotional surface above is distinct from featured collections; one is a deal band, the other is a curation grid.) + +## 4. Navigation and search paths + +Paths the shape carries: +- By category: primary. Always present. +- By search: primary. Always present, in the header. +- By brand or manufacturer: secondary to primary for broad catalogs (often a band in the chrome or a top-level page). +- By attribute (price, size, color, condition): primary on category pages via the faceted side rail. +- By vehicle / compatibility / fitment: primary for compatibility-led verticals; absent for undifferentiated catalogs. +- Newsletter, account, cart: chrome-level secondary affordances. + +Build conventions: +- Search input is in the header, not in a side panel. Visible width meaningful (not collapsed to an icon). +- Faceted filtering on the listing page is conventional; flat lists are off-vertical for broad catalogs. +- Sort options (price asc, price desc, name, relevance) are visible on the listing. +- Search and category browse coexist; one is not gated behind the other. + +## 5. Brand register and conviction + +Typical postures: utilitarian, premium-utilitarian, technical, value-led. Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; do not invent new register names here. + +Build conventions (consistency, not register choice): +- The register carries into the empty states, the cart, the demo modals, and the trust signals. A premium-utilitarian register that dissolves into generic copy below the fold is a composition failure. +- Voice consistency in headings, microcopy, CTAs, and empty states. +- Product imagery posture is consistent: studio product photography across listing and detail; lifestyle imagery in the hero or category headers, if used at all. + +## 6. Trust and conversion signals + +Signals this shape carries: +- Reviews / ratings: average plus count on listing cards and at the top of the detail page. If reviews are absent, surface an alternative (warranty, return policy, brand reputation). +- Pricing transparency: price visible on the listing card; total cost (price plus shipping plus tax) surfaced before checkout, not after. +- Stock signals: in stock, low stock, lead time, backorder. Surfaced on the listing and detail. +- Fitment / compatibility confirmation: required for fitment-led verticals. The confirmation badge ("confirmed to fit your {vehicle}") on the detail page is conventional. +- Shipping promises: free over $X, same-day, two-day. Surfaced in the chrome or hero. +- Return policy: linked from the cart and the detail page. The exact text is in `terms` or `returns`. +- Brand or store badges: certifications, "X years in business", authorized-dealer, where relevant. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real cart state, real fitment filtering), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment, no real account creation). + +## 7. Recurring vertical conventions (the synthesis) + +A credible ecommerce-catalog storefront, against the field of leaders, carries eleven conventions: + +1. A primary task that owns the hero (fitment, search, or category-grid; not a brand pitch). +2. (Density-bearing) A category surface band above the fold at a 1280x800 desktop viewport, not buried in a menu and not requiring scroll to reach. +3. Working faceted filtering on category pages. +4. A persistent global context indicator if the vertical is fitment-led (the confirmed vehicle, the selected compatibility, the active filter set). +5. Visible price on every listing card, with no "click to reveal". +6. Reviews or an explicit substitute (warranty, return policy) near the buying action. +7. A working cart with real client-side state across pages. +8. A clearly labeled checkout flow (real in production; honestly demo in showcase builds). +9. (Density-bearing) A promotional or deal surface near the top: a deal-of-the-week strip, a promo band, or a featured-offer row. +10. (Density-bearing) An inventory or catalog-depth signal a first-time visitor will see (a part count, an SKU total, a category count, or a near-equivalent). +11. (Density-bearing, new) Section count and merchandising volume at the field's level, not at a token-row level. A credible storefront carries roughly thirteen-plus distinct merchandising surfaces top-to-bottom on the home (desktop and mobile each, mobile typically taller), three SKU rails carrying twelve-plus product cards in total, a multi-card deals grid of four-to-eight distinct deal cards (not a single thin promo strip), a category grid of eight-plus photographic tiles, a four-to-six-cell services and trust band, twenty-five-plus distinct images on the home, and a five-to-seven-column footer. A build that hits conventions 2, 9, and 10 with one four-card rail and a five-tile category band passes the presence-check and still reads thin against the field; the bar is volume, not presence. + +Threshold and density-bearing items. A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 9, 10, and 11 are the density-bearing ones, the items whose absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. A build can miss a nice-to-have (a strong substitute for reviews, for example) and still read as the vertical; missing any of the density-bearing four is the failure mode the auto-parts builds exposed across multiple iterations. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +Why convention 11 needed to be added separately. Before this entry, a build could carry the category band, the promo strip, and the inventory signal (conventions 2, 9, 10) and still read thin, because the prior conventions named which sections, never how many or how full. A category band with five tiles passed convention 2; a promo strip with one offer passed convention 9; a part-count badge passed convention 10. The build read storefront-correct on the checklist and read SaaS-airy in a rendered comparison against the field. Convention 11 closes that gap: the bar is the field's actual volume, observed top-to-bottom on a rendered home page, not a presence-check that any single token instance satisfies. + +--- + +## Capture-path note (audit infrastructure) + +The named field leaders in heavily-defended verticals (auto-parts is one) sit behind CDN/WAF bot-mitigation layers that block Fork A rendered capture even with realistic User-Agent strings. In a render-and-match attempt against the four leading parts retailers, all four were intercepted (Cloudflare, Akamai 403, DataDome interstitial, network-idle timeout) and Fork A returned zero homepage content. A synthesis pass on zero captured content silently falls back to training-knowledge abstraction, which is the exact failure mode this shape was added to defend against. + +The lesson, recorded as audit-infrastructure guidance for this shape: in bot-walled verticals, the realistic capture path is screenshot ingestion (a human takes desktop and mobile screenshots of each leader and drops them at a known path; the audit reads the PNGs with vision and produces the section-and-density target from observed evidence). Render-and-match through Fork A alone is not a reliable capture path for this shape. The audit script's selection of capture path should treat Fork A as the default and fall back to screenshot ingestion when zero or trivial content is returned; absent that fallback, the audit silently degrades to abstraction and the build it informs reads thin. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Fitment-first as the entire navigation pattern. Most catalogs treat fitment as a sidebar widget. A build that makes fitment the primary, persistent, single-source-of-truth navigation owns the "wrong-fit return is impossible" position. +- Pricing transparency to the dollar. Most catalogs hide total cost until checkout. A build that surfaces shipping plus tax on the listing card owns the "no surprises" position. +- Honest stock and lead-time signals. Most catalogs use "low stock" theatrically. A build that names actual lead time owns the "we tell you when it ships, not what we want you to feel" position. +- Real reviews vs review theater. Most catalogs surface 4.7-star aggregates that no one trusts. A build that surfaces verified-buyer reviews with the bad ones visible owns the trust position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md new file mode 100644 index 0000000..d1d528d --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-ecommerce-standout.md @@ -0,0 +1,19 @@ +# Shape: ecommerce-standout + +Single-product or narrow-line ecommerce where the brand and the object carry the page. Premium boots, designer goods, single-product subscriptions, expressive consumer brands. The reader arrives because of the brand, not because of a category need. + +## Status + +Stub. Fill when the first ecommerce-standout demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: see the product (image-led), see the story (brand-led), buy. Hero often carries large product photography or a brand statement. +- Layout register: expressive or premium-considered. The opposite of a dense catalog; air and image carry the load. +- Merchandising: one product line, surfaced as a few SKUs or one product with options. The product story is the merchandising; spec lists are short. +- Paths: by SKU or by product secondary (the catalog is small); by story / about primary; press or recognition often surfaced; size / fit guides important. +- Brand register: expressive-maximalist or premium-considered. Cross-reference `creative-direction`; this shape is where strong register choices land. +- Trust signals: materials, where-made, founder story, press, reviews focused on quality and longevity, return policy generous and visible. +- Synthesis (provisional): large product photography in the hero, brand story or founding line surfaced early, size / fit / materials guide reachable, press logos if they exist, reviews emphasizing quality and longevity (not quantity), generous and clearly stated return policy. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md new file mode 100644 index 0000000..bdf348c --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-experience.md @@ -0,0 +1,19 @@ +# Shape: hospitality-experience + +Tours, balloon rides, escape rooms, adventure outfitters, immersive experiences. The reader arrives wanting to understand what the experience is, see real photos, and book. + +## Status + +Stub. Fill when the first hospitality-experience demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: book a date and time. The hero CTA is "book" or "check availability"; secondary is "what to expect" for first-timers. +- Layout register: image-led, atmosphere-heavy. The hero is the experience itself, in photography or video. +- Merchandising: experiences as packages with dates, durations, and prices. What-to-expect content carries the trust load. +- Paths: by experience or package primary; by date / availability primary; private events or group secondary. +- Brand register: expressive, premium-considered, or warm-considered. Often regionally-anchored (place-led brand). +- Trust signals: what-to-expect, what-to-bring, age and accessibility constraints, cancellation policy, weather policy (for outdoor experiences), safety briefing, real customer photos, recent reviews on a trusted platform. +- Synthesis (provisional): book or check-availability in the hero, what-to-expect content surfaced before the booking choice, constraints (age, accessibility, weather) clearly stated, cancellation and weather policies visible, recent real photography and reviews, no stock imagery that does not match the actual experience. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md new file mode 100644 index 0000000..d1b76d1 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-hospitality-food.md @@ -0,0 +1,115 @@ +# Shape: hospitality-food + +Restaurants, cafés, bakeries, food halls, ghost kitchens with a storefront. The reader arrives wanting to know if they want to eat there: what the food is, what it costs, when the place is open, whether they can get a table. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (fine dining, neighborhood restaurant, café, bakery), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: see the menu. The reservation action is the secondary primary task. For walk-in-only restaurants and cafés, the menu and the hours-and-address pair are the primary tasks; for reservation-led restaurants, the menu and the reservation flow share the lead. + +Build conventions: +- The menu is reachable in one click from the home page. A site that buries the menu behind a PDF link, behind a modal, or below the fold without a clear cue is off-vertical. The menu is the page, not a download. +- The reservation action is the largest CTA in the chrome (after the menu link). For walk-in-only shops, the equivalent is "where we are" and "when we open." +- The reservation flow is on-site, not punted to a third-party widget iframe. A widget that breaks the site's visual contract dissolves the room's identity at the moment the visitor is closest to deciding. +- The site's primary task is the same component everywhere. One reservation modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +Register: image-led, atmospheric. Less dense than a catalog; more density than a marketing page; more atmosphere than a service-booking page. The page should feel like the room. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: an edge-to-edge dish or room photograph, the restaurant name and one-line identity, AND the reservation CTA. A hospitality-food hero without a real photograph reads as a marketing template. +- The hero photograph is a single subject (one dish, one corner of the room, one moment of service), not a collage. Tiled grids of every dish lose focus; stock food imagery loses identity; single-subject photography on a confident background is the convention. +- Whitespace is generous and atmospheric. The dish gets to breathe. Catalog-dense layouts are off-vertical for this shape unless the vertical is a fast-casual chain. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be editorial-restrained (fine dining), warm-neighborhood (everyday), industrial-bright (fast-casual), or playful-soft (bakery, café); not corporate-flat. + +## 3. The menu + +Conventions: +- A menu page, not a PDF, with each item carrying a name, a description, and a price visible per item. Hiding prices is off-vertical; it tells the visitor the shop is luxury-pretense rather than confidence. +- Items are grouped by course (starters, mains, sides, desserts, drinks). For tasting menus, the courses are the structure. For diner-style menus, the categories are functional. +- Item descriptions are written, not enumerated. Two or three short sentences per item. Adjective stacks ("savory, hearty, comforting") read as marketing; ingredient-and-method copy ("twenty-four-hour bone broth, brisket, eye round") reads as the kitchen. +- Signature dishes carry a small visible mark (badge, label) so the visitor knows what to order. Hiding the signature inside the list misses the assist. +- Allergen notes are surfaced (peanut, shellfish, gluten) where the kitchen's handling requires it. Generic "ask your server" copy is acceptable but less confident than naming the handling. + +## 4. Chef, provenance, and story + +Conventions: +- A short chef-perspective or chef-partner passage is conventional, on the home page or the about page. Two short paragraphs at most; first-person, ingredient-literate, no marketing register. +- Provenance content (where the ingredients come from, who farms what, who supplies the seafood) carries the hospitality wedge for restaurants whose positioning leans on it. For places where it does not, this is absent. +- Staff bios beyond the chef are absent in fine dining and present in neighborhood restaurants and cafés (named baristas, pastry chefs, line cooks). Match the register of the shop. +- The story is not a brand history; it is a kitchen perspective. Brands tell origin stories; restaurants tell what they care about. + +## 5. Reservations flow + +Conventions: +- The form asks: name, party size, date, time, email, allergies and notes. Nothing more at this stage; not an account, not a password, not marketing consent. +- Confirmation is honest. Real production: email confirmation within the hour, sometimes within minutes. Demo build: clearly labeled demo-only, no fake confirmation copy. +- Cancellation, late, and allergy policies are visible on the reservation page, not hidden in terms or buried in confirmation email. +- Walk-in policy is named openly if relevant ("walk-ins welcome at the bar", "no walk-ins"). +- Phone-as-fallback: a visible phone number for visitors who would rather call. Restaurant customers vary; the field's best builds carry both. + +## 6. Address, hours, and visit info + +Conventions: +- Address visible in the chrome on every page. Hours visible at minimum in the footer; the home page should carry "open tonight" or the day's hours above the fold. +- Hours that vary (brunch on Sundays, late on weekends, closed Mondays) are listed line-by-line, not summarized. +- Transit and parking notes belong on a Visit page; they are a trust signal for visitors planning to travel to the restaurant. +- Accessibility notes (step-free entrance, accessible restroom, dress code, noise level) are conventional on the Visit page and rare in the field; their presence reads as care. +- A live map embed is optional; a static "find us" image plus a deep link to the visitor's preferred map app works as well and avoids the embed's accessibility and performance overhead. + +## 7. Press, reviews, and aggregate trust + +Conventions: +- One named-publication pull-quote is the conventional press treatment, not a logo wall. A short, specific quote that names what the restaurant is good at carries more credibility than five logos. +- Aggregate ratings (Google, Yelp, Resy) are present in the chrome or near the reservation action, not in a logo grid. Numbers plus counts; not stars alone. +- Awards (Michelin, James Beard, regional press) are listed plain text in the chrome or on About, not in a badge wall. +- For demo or showcase builds, the functional-vs-demo line: a placeholder press quote is acceptable but should be labeled as such in the workup, not implied to be a real publication. + +## 8. Trust and conversion signals + +Signals this shape carries: +- The dish photograph itself, edge-to-edge, dramatic light, single subject. +- The chef's-perspective passage that does the work of branding. +- Plain-language menu descriptions with prices. +- Open cancellation, late, and allergy policies on the reservation page. +- Visible address and hours. +- Aggregate ratings near the reservation action. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo reservation modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible hospitality-food site, against the field of leaders, carries ten conventions: + +1. An edge-to-edge hero photograph of a single dish, room, or moment, above the fold at a 1280x800 desktop viewport. +2. (Density-bearing) A menu page, not a PDF, with name, description, and price visible per item, reachable in one click from the home. +3. Item descriptions in ingredient-and-method voice, not adjective stacks; signature dishes marked. +4. A reservation action that is on-site, not a third-party widget iframe, available from the chrome on every page. +5. (Density-bearing) A short chef-perspective or chef-partner passage, first-person, two short paragraphs at most. The story of the kitchen, not a brand history. +6. Address and hours visible above the fold; full hours line-by-line on the home or visit page. +7. JSON-LD Restaurant with hasMenu, servesCuisine, acceptsReservations, openingHoursSpecification, and aggregateRating. +8. Cancellation, late, and allergy policies stated openly on the reservation page. +9. (Density-bearing) One named-publication press pull-quote OR a visible aggregate rating (count plus number), placed near the reservation CTA. Not a logo wall. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +Threshold and density-bearing items. A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 1, 5, and 9 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a template instead of the room. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of conventions 1, 5, or 9 will make the build read as a marketing page about food rather than a restaurant. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- The menu is the page. Most competitors hide the menu behind a PDF or a modal. A build that surfaces the menu in plain HTML with ingredient-literate descriptions owns the "we know what we cook" position. +- On-site reservations. Most competitors punt to a third-party reservation widget. A build that keeps the reservation flow visually within the site's identity owns the "the room is the experience" position. +- Single-subject photography. Most competitors either tile every dish or use stock food imagery. A build that leads with edge-to-edge single-subject photography on a confident background owns the "this is the dish" position. +- Chef's-perspective voice. Most competitors write in marketing register (adjective stacks, brand voice). A build that writes the menu in the chef's voice (ingredient, method, restraint) owns the "we are not selling you, we are cooking for you" position. +- Provenance literacy. Most competitors gesture vaguely at "local, seasonal." A build that names the farmer, the supplier, the cut, owns the "we know where the food came from" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md new file mode 100644 index 0000000..b5c9e03 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-institution-mission.md @@ -0,0 +1,19 @@ +# Shape: institution-mission + +Nonprofits, museums, foundations, public-interest organizations. The reader arrives wanting to understand what the institution does and decide whether to give, attend, volunteer, or read further. + +## Status + +Stub. Fill when the first institution-mission demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: depends on the moment. Donate during a campaign; visit / attend for an institution with a physical presence; sign up or read for a research or advocacy group. The hero CTA matches the institution's primary ask. +- Layout register: editorial-considered. More text than a catalog, less than a long-form publication. Trust load is heavy; expressive maximalism is rare in this shape. +- Merchandising: the cause or mission is the merchandising. Programs, impact, and recent work carry the page. +- Paths: by program primary; by impact / outcomes primary for established institutions; news / press / blog secondary; financials / 990 secondary but conventional for nonprofits. +- Brand register: institutional, considered, mission-led. Premium-considered for arts and culture; restrained-authoritative for advocacy. +- Trust signals: mission statement, board / leadership, financial transparency (for nonprofits, the 990 or audit), accreditations, named donors or partners, recent impact numbers with sources. +- Synthesis (provisional): mission statement above the fold, a clear primary ask (donate, attend, sign up), program or impact surface, leadership and governance reachable from the chrome, financial transparency linked (for nonprofits), no over-emotive imagery that reads as manipulative. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md new file mode 100644 index 0000000..ca1fa7f --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-inventory-listing.md @@ -0,0 +1,19 @@ +# Shape: inventory-listing + +Used-car lots, real estate, equipment rental, marketplace listings. The reader arrives wanting to filter a finite inventory down to the right item. + +## Status + +Stub. Fill when the first inventory-listing demo is built, or when a `competitor-experience-audit` for an inventory-listing vertical has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: filtered search with high-fidelity facets (price range, location, condition, year, make, model, beds, square feet). Search and faceted filtering are co-primary. +- Layout register: dense, but more grid-led than catalog-led. Each listing carries multiple attributes that need room to read. +- Merchandising: the listing is the merchandising. Hero carries a search-and-filter entry plus a few featured items. +- Paths: search-and-filter primary; saved-search and favorites secondary (account-gated); browse-by-attribute primary on category pages. +- Brand register: transactional, trust-led. Premium-led for high-ticket inventory (real estate, luxury cars). +- Trust signals: verified seller, listing freshness, photos count, condition reports, response time. +- Synthesis (provisional): persistent filter chip row, listing freshness indicators, photo count signal, save-this-listing affordance, contact-the-seller path. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md new file mode 100644 index 0000000..2628de6 --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-local-service-booking.md @@ -0,0 +1,125 @@ +# Shape: local-service-booking + +Barber shops, salons, gyms, BJJ schools, dental practices, repair shops, dog groomers. The reader arrives wanting to book a time, see prices, or confirm the place exists. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (barbershops, dentists, repair shops), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: book an appointment. For unbookable services (drop-in only), the primary task is to call or to confirm hours. The booking action is the largest CTA on the page; everything else competes for second place. + +Build conventions: +- The book-now action is in the chrome (persistent on every page) AND in the hero, not one or the other. +- A first-time visitor who arrived to book should reach a booking surface in one click from the home page. A flow that requires "services then pick then book" is one click too many. +- For services where the picked practitioner matters (barber, stylist, trainer, dentist), the booking action surfaces the practitioner choice before the time choice. For services where practitioner does not matter (oil change, dog wash), it does not. +- The booking action is the same component everywhere on the site so a visitor cannot get lost. One booking modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +Register: image-led-warm. Less dense than a catalog; more dense than a marketing page. The page should feel like a room the visitor wants to be in. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: the booking CTA, an interior photograph of the space, AND a trust signal (years, license, review average, or named practitioners). A booking page without a photograph of the room reads as a third-party scheduler iframe, not a shop. +- A hero image of the space (or a close-up of the craft) is conventional and load-bearing. Stock or generic imagery reads as "any salon"; the shop's specific room reads as the shop. +- Whitespace is generous but purposeful. Editorial-airy is off-vertical; the visitor needs to see the menu and book without scrolling far. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be warm-classic, considered-premium, institutional-professional (medical, legal), or rugged-craft; not corporate-flat or marketing-flashy. + +## 3. Service menu and pricing + +Conventions: +- A service menu with duration and price visible per item lives above the fold at a 1280x800 desktop viewport, OR is one click from the home page and clearly signposted. Hiding prices behind a phone call is off-vertical for the field's modern bar; it tells the visitor the shop is friction-tolerant. +- Service descriptions are plain language, not marketing. Two sentences max per service. +- Service categories (haircut, shave, beard, package) are grouped, not flat-listed, for shops with more than five services. +- Packages (cut-and-shave, cut-and-color) are surfaced as their own line items with their own price, not as "add $X to the base service". +- For services where duration varies (skin fade vs classic cut), the longer duration is named honestly; the shop blocks the chair for the time the cut takes. + +## 4. Trust block and identity + +Signals this shape carries above the fold: +- Years in business ("Est. 2014", "11 years on Walnut Street"). +- License or certification, where the vertical has one (master barber license, dental board, state cosmetology, ASE certification for repair shops). +- Review average plus count (not just the stars; the count is the credibility). +- Address visible, not buried in a footer-only treatment. +- Hours visible, not buried in a footer-only treatment. A visitor planning a drop-in needs to know if the shop is open right now. +- For practitioner-driven shops: the practitioners' names and faces. Anonymous "our team" copy reads as franchise; named, photographed practitioners read as shop. + +Build conventions: +- The trust block is aggregated, not scattered. Years in one footer line, reviews on a separate widget, hours on a separate page is the field's miss; pulling them into a single above-the-fold block is the field's lever. +- JSON-LD `LocalBusiness` (or the more specific subtype: `HairSalon`, `BarberShop`, `Dentist`, `AutoRepair`) carries address, hours, telephone, and aggregateRating in structured form. Most competitors ship none. + +## 5. Practitioner roster + +Conventions for practitioner-driven shops (barber, stylist, trainer, dentist): +- A roster with faces above the booking CTA is the conversion lever the field leaves on the table. Most competitors gate the practitioner choice inside the booking flow; surfacing it before the booking choice removes a decision point. +- Each practitioner card carries: name, face, years of experience, specialties (one to three short tags). +- Bio length is one or two sentences, plain language. Long bios read as profile pages, not a roster. +- For non-practitioner-driven shops (drop-in repair, walk-in clinic), this section is absent or replaced by a "what makes this shop different" block. + +## 6. Booking flow specifics + +Conventions: +- The booking surface is a modal or a single-page form, not a multi-step wizard. Local-service appointments are not enterprise sales. +- The form asks: name, service, practitioner (if applicable), preferred date, preferred time window, notes. It does not ask for an account, a password, or marketing consent at this stage. +- Confirmation is honest. Real production: SMS or email within the hour. Demo build: clearly labeled demo-only, no fake confirmation copy ("you're booked!" with no booking). +- Cancellation policy, late policy, and payment policy are visible on the booking page, not hidden in terms. +- Phone-as-fallback: a visible phone number for visitors who would rather call. Local-service customers vary in digital comfort; the field's best builds carry both. + +## 7. Navigation paths + +Paths the shape carries: +- Services (menu, prices, durations): primary. +- Book: primary, persistent. +- Visit (address, hours, directions, parking, accessibility): primary. +- About / story / team: secondary. +- Newsletter, account, cart: absent or chrome-level afterthought. Local-service shops are not subscription products. + +Build conventions: +- Hours and address are in the chrome (footer at minimum) on every page. +- Accessibility info (step-free entrance, adjustable chairs, accessible restroom, quieter hours) sits on the Visit page; competitors rarely carry it and it is a real differentiator. + +## 8. Trust and conversion signals + +Signals this shape carries: +- Reviews / ratings: average plus count, surfaced above the fold. A four-and-up rating without a count reads as theater. +- Years in business: visible in the chrome or hero. Local shops earn trust over time and the field rewards saying so. +- License or certification number: visible, on the Visit or About page if not in the chrome. +- Plain-language service descriptions: no upcharge surprises. +- Cancellation and late policies stated openly. Generous grace windows read as confident; harsh ones read as defensive. +- Quieter hours / accessibility / language spoken: trust signals the field rarely carries; presence reads as care. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo booking modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible local-service-booking site, against the field of leaders, carries ten conventions: + +1. A book-now action that owns the hero and persists in the chrome on every page. +2. (Density-bearing) An interior or craft photograph of the specific shop above the fold at a 1280x800 desktop viewport, not stock or generic. +3. A service menu with duration and price visible per item, one click from the home page at most. +4. (Density-bearing) A trust block aggregated above the fold: years in business, license or certification, review average plus count. Not scattered across footer and about page. +5. For practitioner-driven shops: a roster with faces and specialties above the booking CTA. +6. Address and hours in the chrome (footer at minimum) on every page. +7. JSON-LD LocalBusiness (or vertical-specific subtype) with address, hours, telephone, and aggregateRating. +8. A booking flow that is a single-page form or modal, not a multi-step wizard; asks for name, service, time, and nothing more at this stage. +9. (Density-bearing) A cancellation, late, and payment policy stated openly on the booking page, not hidden in terms. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +Threshold and density-bearing items. A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 4, and 9 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a third-party scheduler iframe or a franchise template instead of a specific shop with a specific room. A build can miss a nice-to-have (the practitioner roster for a drop-in shop, for example) and still read as the vertical; missing any of conventions 2, 4, or 9 makes the build read as anyone's shop. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Booking-first composition. Most competitors bury the booking action below the fold or behind a third-party scheduler iframe that breaks the visual contract. A build that makes the booking action the largest element on every page, with the shop's identity intact, owns the "we want you to book" position. +- Roster-before-booking. Most competitors gate the practitioner choice inside the booking flow. A build that surfaces a small, photographed roster above the booking CTA owns the "you pick the chair, then the time" position. +- Honest service menu. Most competitors hide prices behind a phone call or list services without durations. A build that posts duration and price for every service owns the "no surprises" position. +- Specific-room photography. Most competitors use stock or generic salon imagery. A build that leads with the shop's actual room owns the "this is the place" position. +- Aggregated trust above the fold. Most competitors scatter the trust signals (years, license, reviews) across the chrome and about page. A build that pulls them into a single above-the-fold block owns the "we are real, we are local, we are licensed" position before the visitor scrolls. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md new file mode 100644 index 0000000..2e3919a --- /dev/null +++ b/dist/pi/.agents/skills/vertical-site-conventions/references/shape-subscription-app.md @@ -0,0 +1,19 @@ +# Shape: subscription-app + +Weather apps, productivity tools, news readers, fitness trackers, language learning. The reader arrives wanting to understand the app and decide whether to install or subscribe. + +## Status + +Stub. Fill when the first subscription-app demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: install (App Store / Play Store buttons) or start trial. The download or trial CTA is the hero. +- Layout register: marketing-led with strong product imagery (device frames, screen captures). Editorial-airy is common. +- Merchandising: features as a vertical scroll of capability sections; not a catalog grid. +- Paths: by feature primary (scroll); pricing secondary (navigable but not first); blog / support tertiary. +- Brand register: wide range. Consumer apps lean expressive or playful; productivity leans considered or technical. +- Trust signals: App Store rating, install count, press logos, customer testimonials, screenshots that read as the actual product. +- Synthesis (provisional): install CTAs (real store buttons) in the hero and chrome, feature-by-feature scroll with real product imagery, pricing surfaced clearly with the free / paid line drawn, App Store rating and review count surfaced, no fake screenshots. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/dist/pi/PORT_NOTES.md b/dist/pi/PORT_NOTES.md new file mode 100644 index 0000000..45677c0 --- /dev/null +++ b/dist/pi/PORT_NOTES.md @@ -0,0 +1,128 @@ +# Pi port notes + +Spike: a Pi-compatible distribution of the RampStack skills catalog, produced +by a repeatable, dependency-free build (`scripts/build-pi.mjs`). Do not merge. + +## Count + +- Source skills (`skills//SKILL.md`): 102 +- Emitted skills (`dist/pi/.agents/skills//SKILL.md`): 102 +- Reference files preserved: 488 + +Note on the count: this dist was first built on a stale 99-skill base after a +disk-full event left a `git reset --hard origin/main` un-applied. It has since +been rebased onto the corrected `main` (PR #90), which is 102 skills with all +descriptions shortened under the 1024-char cap. The build now emits exactly 102 +skills, including `creative-brief-selector`, and validation asserts emitted +count equals source count. + +## Key decision: preserve native frontmatter (no sidecar) + +This is the one substantive difference from the Codex and Antigravity dists. + +- Codex and Antigravity trim each skill's frontmatter down to `name` and + `description`, and move the remaining keys (`category`, `catalog_summary`, + `display_order`) into a `references/_claude-frontmatter-extras.yaml` sidecar + so the port stays lossless and reversible. They do this because those agents + validate frontmatter against a fixed key set and reject or warn on unknown + keys. +- Pi does not. Pi's frontmatter type is `{ name?, description?, + "disable-model-invocation"?, [key: string]: unknown }`. Arbitrary keys are + accepted and ignored. So the correct, simplest, and most faithful port is to + copy each `SKILL.md` byte-for-byte with its native frontmatter intact. No + trimming, no sidecar, no transformation. + +Consequences: +- The build is a pure byte-for-byte directory copy. Building twice yields + byte-identical output. `--check` rebuilds to a temp dir and diffs against the + committed tree, exiting nonzero and listing any differing paths (staleness + guard). +- `category`, `catalog_summary`, and `display_order` remain visible in every + emitted `SKILL.md` exactly as authored. Pi ignores them; they cost nothing and + keep the dist a faithful mirror of source. + +## Validation results + +Run `node scripts/build-pi.mjs --validate`: + +- PASS: every emitted SKILL.md has valid `---` frontmatter +- PASS: every emitted SKILL.md has non-empty `name` and `description` +- PASS: every name conforms to Pi rules (lowercase a-z / 0-9 / hyphen, max 64 + chars, no consecutive hyphens) +- PASS: every description is <= 1024 chars +- PASS: emitted skill count equals source (102) +- PASS: every source references file has an emitted counterpart (488) + +No warnings. An earlier build on the stale 99-skill base reported three +descriptions over 1024 chars (`creative-direction`, `integration-orchestrator`, +`logo-design`). Those were shortened at source in PR #90, so the over-length +warning is now gone. Pi would have loaded those skills anyway (an over-length +description is a non-fatal warning; only a missing description prevents +loading), but the source fix removes the warning entirely. + +## Live discovery check + +Pi CLI is installable, so this was exercised for real, not skipped. + +- Installed `@mariozechner/pi-coding-agent` (v0.73.1) locally into a throwaway + directory outside the repo (so no `node_modules` or lockfile lands in the + lane). +- Called Pi's own loader, `loadSkillsFromDir({ dir, source })`, against + `dist/pi/.agents/skills/`. + +Results (on the corrected 102-skill base): +- 102 skills discovered (matches emitted count). +- 0 diagnostics. The three description-length warnings seen on the earlier + 99-skill base are gone now that PR #90 shortened those descriptions. +- `creative-brief` loaded cleanly (description length 701, + `disableModelInvocation: false`, filePath resolved). +- `formatSkillsForPrompt(skills)` rendered all 102 skills into a system-prompt + block (about 92k chars) with no errors thrown. + +Conclusion: Pi discovers and parses the entire emitted catalog with zero parse +errors and zero warnings. + +Manual repro (if installing fresh): + +``` +mkdir pi-cli-test && cd pi-cli-test +npm init -y && npm i @mariozechner/pi-coding-agent +# then, from a script that imports the package: +# import { loadSkillsFromDir } from '@mariozechner/pi-coding-agent'; +# loadSkillsFromDir({ dir: '<repo>/dist/pi/.agents/skills', source: 'check' }); +# or, to exercise the CLI interactively after configuring a provider: +cd <repo>/dist/pi && pi # ancestor discovery finds .agents/skills, then /skill:creative-brief +``` + +## Future options (NOT applied here) + +These are deliberately out of scope for this spike. Listed for whoever takes +the port forward. + +(a) Publishable Pi package wrapper. Pi can load skills from a `skills/` + directory or a `pi.skills` entry in a package's `package.json`, distributed + over npm or git. A thin wrapper package that points `pi.skills` at this + catalog would let users `pi install <source>` instead of copying `.agents` + by hand. Not applied: the spike's goal is a copy-in distribution, and a + published package is a separate release decision. + +(b) Explicit-only orchestration skills. Pi supports a frontmatter key + `disable-model-invocation: true` (the practical equivalent of a "hidden" + skill). A skill with this set is excluded from the always-in-context + descriptions and can only be invoked explicitly via `/skill:<name>`. This + would be a good fit for noisy orchestration skills (for example + `seo-audit-orchestration`) so they do not crowd the model's skill list and + are only run on purpose. Not applied: it changes runtime behavior and would + edit source frontmatter, which is outside this preserve-native build. + +## Running Pi on alternative models + +Pi is model-agnostic through its `pi-ai` provider layer, so the same skills run +unchanged on any supported provider. To run Pi on Kimi K2.6, point Pi at +Moonshot's API (platform.moonshot.ai) as a provider; Moonshot exposes both an +OpenAI-compatible and an Anthropic-compatible endpoint. Recommended sampling +temperature for K2.6 is 0.6. Important: Moonshot's Anthropic-compatible endpoint +already scales the incoming temperature by 0.6 internally, so do not apply the +0.6 a second time when using that endpoint (doing so would effectively send +0.36). This is provider/model configuration only; it is not a skills change and +nothing in this distribution depends on it. diff --git a/dist/pi/README.md b/dist/pi/README.md new file mode 100644 index 0000000..c5b280f --- /dev/null +++ b/dist/pi/README.md @@ -0,0 +1,73 @@ +# Pi-compatible skills distribution + +This directory is a Pi-compatible build of the RampStack skills catalog. It is +generated from the read-only `skills/` source tree by `scripts/build-pi.mjs`. +Every source skill is copied byte-for-byte into `.agents/skills/<name>/`, with +its native frontmatter preserved intact (Pi accepts arbitrary frontmatter keys, +so nothing is trimmed and there is no sidecar file). + +Pi reference: https://pi.dev and https://github.com/earendil-works/pi + +## What is here + +``` +dist/pi/ + .agents/ + skills/ + <skill-name>/ + SKILL.md preserved byte-for-byte from source + references/... preserved byte-for-byte from source + README.md this file + PORT_NOTES.md port decisions, live-check results, future options +``` + +102 skills, 488 reference files. See `PORT_NOTES.md` for details. + +## Pi discovery paths + +Pi resolves skills from the following locations. Later sources override earlier +ones on name collision: + +- Global / user: `~/.pi/agent/skills/` and `~/.agents/skills/` +- Project: `.pi/skills/` and `.agents/skills/`, searched in the current working + directory and every parent up to the git root (ancestor discovery) +- Packages: a `skills/` directory or a `pi.skills` entry in `package.json` +- Settings: a `skills` array (files or directories) in Pi settings +- CLI: the `--skill <path>` flag (a skill file or directory; repeatable) + +Because this build emits `.agents/skills/`, dropping the `.agents` directory at +the root of any project (or any ancestor of where you run Pi, up to the git +root) makes every skill discoverable with no further configuration. + +## Install + +Copy the `.agents` directory into the root of your target project: + +``` +cp -r dist/pi/.agents <target-project>/ +``` + +Then run `pi` from anywhere inside that project. Skills are discovered +automatically via ancestor discovery. To verify discovery without committing +the directory, you can instead point Pi at the tree directly: + +``` +pi --skill dist/pi/.agents/skills/creative-brief +``` + +## Invoking a skill + +Pi loads skill descriptions into context at startup (progressive disclosure) +and loads the full `SKILL.md` on demand when a task matches. You can also invoke +a skill explicitly: + +``` +/skill:<name> +``` + +Arguments typed after the command are appended to the skill content as a user +message (`User: <args>`). For example: + +``` +/skill:creative-brief a landing page for a B2B onboarding tool +``` diff --git a/docs/architecture-mobile.jpg b/docs/architecture-mobile.jpg new file mode 100644 index 0000000..1ae2bda Binary files /dev/null and b/docs/architecture-mobile.jpg differ diff --git a/docs/architecture-wide.jpg b/docs/architecture-wide.jpg new file mode 100644 index 0000000..76a1ccb Binary files /dev/null and b/docs/architecture-wide.jpg differ diff --git a/docs/rampstack-complete-banner.jpg b/docs/rampstack-complete-banner.jpg new file mode 100644 index 0000000..08827f7 Binary files /dev/null and b/docs/rampstack-complete-banner.jpg differ diff --git a/og-card.png b/og-card.png new file mode 100644 index 0000000..b7863cf Binary files /dev/null and b/og-card.png differ diff --git a/scripts/build-pi.mjs b/scripts/build-pi.mjs new file mode 100644 index 0000000..49a95f1 --- /dev/null +++ b/scripts/build-pi.mjs @@ -0,0 +1,281 @@ +#!/usr/bin/env node +// build-pi.mjs - Build a Pi-compatible distribution of the skills catalog. +// +// Pi (pi.dev, github.com/earendil-works/pi) discovers skills from +// `.agents/skills/<name>/SKILL.md`. Pi accepts arbitrary frontmatter keys, +// so this build copies every source skill directory byte-for-byte into +// dist/pi/.agents/skills/ with native frontmatter preserved intact. No +// trimming, no sidecar (this is the key difference from the Codex and +// Antigravity dists, which trim frontmatter into a sidecar file). +// +// Dependency-free: Node ESM, fs and path only. +// +// Usage: +// node scripts/build-pi.mjs Build dist/pi/.agents/skills/ +// node scripts/build-pi.mjs --check Rebuild to a temp dir and diff +// against committed output; exit +// nonzero if anything differs. +// node scripts/build-pi.mjs --validate Validate emitted output against +// the Pi skill rules and source. + +import { + readdirSync, + readFileSync, + writeFileSync, + mkdirSync, + rmSync, + existsSync, +} from 'fs'; +import { fileURLToPath } from 'url'; +import { dirname, join, relative } from 'path'; + +const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url)); +const REPO_ROOT = dirname(SCRIPT_DIR); +const SRC_SKILLS = join(REPO_ROOT, 'skills'); +const DIST_ROOT = join(REPO_ROOT, 'dist', 'pi'); +const DIST_SKILLS = join(DIST_ROOT, '.agents', 'skills'); + +// --- small fs helpers (sorted, deterministic) -------------------------------- + +function listDirsSorted(dir) { + return readdirSync(dir, { withFileTypes: true }) + .filter((e) => e.isDirectory()) + .map((e) => e.name) + .sort(); +} + +// Return all file paths under `dir`, relative to `dir`, sorted. Uses forward +// slashes so output is identical across platforms (determinism). +function listFilesSorted(dir) { + const out = []; + function walk(current) { + const entries = readdirSync(current, { withFileTypes: true }); + for (const e of entries) { + const full = join(current, e.name); + if (e.isDirectory()) walk(full); + else if (e.isFile()) out.push(relative(dir, full).split('\\').join('/')); + } + } + walk(dir); + return out.sort(); +} + +function copyFileBytes(srcFile, destFile) { + mkdirSync(dirname(destFile), { recursive: true }); + // Buffer copy: no encoding transform, byte-for-byte identical. + writeFileSync(destFile, readFileSync(srcFile)); +} + +// --- build -------------------------------------------------------------------- + +// Build the .agents/skills tree under `destSkills`. Returns counts. +function build(destSkills) { + // Clean target so removed source skills never linger (determinism). + if (existsSync(destSkills)) rmSync(destSkills, { recursive: true, force: true }); + mkdirSync(destSkills, { recursive: true }); + + const skills = listDirsSorted(SRC_SKILLS); + let referenceFiles = 0; + let skillFiles = 0; + + for (const name of skills) { + const srcDir = join(SRC_SKILLS, name); + const destDir = join(destSkills, name); + const files = listFilesSorted(srcDir); + for (const rel of files) { + copyFileBytes(join(srcDir, rel), join(destDir, rel)); + if (rel === 'SKILL.md') skillFiles++; + if (rel.startsWith('references/')) referenceFiles++; + } + } + + return { skills: skills.length, skillFiles, referenceFiles }; +} + +// --- check (staleness guard) -------------------------------------------------- + +function check() { + const tmp = join(REPO_ROOT, '.pi-check-tmp'); + if (existsSync(tmp)) rmSync(tmp, { recursive: true, force: true }); + const tmpSkills = join(tmp, '.agents', 'skills'); + build(tmpSkills); + + const committed = DIST_SKILLS; + if (!existsSync(committed)) { + console.error('FAIL: committed output not found at ' + rel(committed)); + rmSync(tmp, { recursive: true, force: true }); + process.exit(1); + } + + const freshFiles = new Set(listFilesSorted(tmpSkills)); + const committedFiles = new Set(listFilesSorted(committed)); + const differing = []; + + for (const f of freshFiles) { + if (!committedFiles.has(f)) { + differing.push('missing in committed: ' + f); + continue; + } + const a = readFileSync(join(tmpSkills, f)); + const b = readFileSync(join(committed, f)); + if (!a.equals(b)) differing.push('content differs: ' + f); + } + for (const f of committedFiles) { + if (!freshFiles.has(f)) differing.push('stale in committed (no source): ' + f); + } + + rmSync(tmp, { recursive: true, force: true }); + + if (differing.length) { + console.error('FAIL: committed dist/pi is stale. ' + differing.length + ' difference(s):'); + for (const d of differing) console.error(' ' + d); + process.exit(1); + } + console.log('PASS: committed dist/pi/.agents/skills matches a fresh build (byte-identical).'); +} + +// --- validate ----------------------------------------------------------------- + +// Parse the frontmatter block (between the first two `---` lines) into a flat +// map of top-level keys. Quotes are stripped from values for length checks. +function parseFrontmatter(text) { + const lines = text.split(/\r?\n/); + if (lines[0].trim() !== '---') return null; + let end = -1; + for (let i = 1; i < lines.length; i++) { + if (lines[i].trim() === '---') { + end = i; + break; + } + } + if (end === -1) return null; + const map = {}; + for (let i = 1; i < end; i++) { + const line = lines[i]; + const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]):\s?(.)$/); + if (!m) continue; + let val = m[2].trim(); + if ( + (val.startsWith('"') && val.endsWith('"')) \|\| + (val.startsWith("'") && val.endsWith("'")) + ) { + val = val.slice(1, -1); + } + map[m[1]] = val; + } + return map; +} + +const PI_NAME_RE = /^[a-z0-9-]{1,64}$/; + +function validate() { + const results = []; + const pass = (label) => results.push(['PASS', label]); + const fail = (label) => results.push(['FAIL', label]); + // WARN is reported loudly but does not fail the run. Used where Pi itself + // only warns (and still loads the skill) and where this build is forbidden + // from fixing the source (preserve-native frontmatter, no trimming). + const warn = (label) => results.push(['WARN', label]); + + if (!existsSync(DIST_SKILLS)) { + console.error('FAIL: ' + rel(DIST_SKILLS) + ' does not exist. Run the build first.'); + process.exit(1); + } + + const emitted = listDirsSorted(DIST_SKILLS); + const source = listDirsSorted(SRC_SKILLS); + + // 1. Frontmatter validity + non-empty name/description. + const badFrontmatter = []; + const emptyFields = []; + // 2. Name rules. + const badNames = []; + // 3. Description length. + const longDescriptions = []; + + for (const name of emitted) { + const text = readFileSync(join(DIST_SKILLS, name, 'SKILL.md'), 'utf8'); + const fm = parseFrontmatter(text); + if (!fm) { + badFrontmatter.push(name); + continue; + } + if (!fm.name \|\| !fm.name.trim()) emptyFields.push(name + ' (name)'); + if (!fm.description \|\| !fm.description.trim()) emptyFields.push(name + ' (description)'); + + const n = fm.name \|\| ''; + if (!PI_NAME_RE.test(n) \|\| n.includes('--')) badNames.push(name + ' -> "' + n + '"'); + + if ((fm.description \|\| '').length > 1024) { + longDescriptions.push(name + ' (' + fm.description.length + ' chars)'); + } + } + + if (badFrontmatter.length === 0) pass('Every emitted SKILL.md has valid --- frontmatter'); + else fail('Invalid frontmatter: ' + badFrontmatter.join(', ')); + + if (emptyFields.length === 0) pass('Every emitted SKILL.md has non-empty name and description'); + else fail('Empty name/description: ' + emptyFields.join(', ')); + + if (badNames.length === 0) pass('Every name conforms to Pi rules (lowercase a-z/0-9/hyphen, <=64, no consecutive hyphens)'); + else fail('Names violating Pi rules (reported, not renamed): ' + badNames.join('; ')); + + if (longDescriptions.length === 0) pass('Every description is <= 1024 chars'); + else warn('Descriptions over 1024 chars (Pi loads with a warning; preserved as-is from source, not trimmed): ' + longDescriptions.join(', ')); + + // 4. Emitted count equals source. + if (emitted.length === source.length) pass('Emitted skill count equals source (' + emitted.length + ')'); + else fail('Emitted count ' + emitted.length + ' != source count ' + source.length); + + // 5. Every source references file has an emitted counterpart. + const missingRefs = []; + let refTotal = 0; + for (const name of source) { + const srcRefDir = join(SRC_SKILLS, name, 'references'); + if (!existsSync(srcRefDir)) continue; + for (const rf of listFilesSorted(srcRefDir)) { + refTotal++; + const counterpart = join(DIST_SKILLS, name, 'references', rf); + if (!existsSync(counterpart)) missingRefs.push(name + '/references/' + rf); + } + } + if (missingRefs.length === 0) pass('Every source references file has an emitted counterpart (' + refTotal + ' files)'); + else fail('Missing emitted references: ' + missingRefs.join(', ')); + + // Report. + let failed = 0; + let warned = 0; + for (const [status, label] of results) { + console.log(status + ': ' + label); + if (status === 'FAIL') failed++; + if (status === 'WARN') warned++; + } + console.log(''); + const suffix = warned ? ' (' + warned + ' warning(s))' : ''; + console.log(failed === 0 ? 'VALIDATION PASS' + suffix : 'VALIDATION FAIL (' + failed + ' check(s) failed)'); + if (failed) process.exit(1); +} + +function rel(p) { + return relative(REPO_ROOT, p).split('\\').join('/'); +} + +// --- entrypoint --------------------------------------------------------------- + +const arg = process.argv[2]; + +if (arg === '--check') { + check(); +} else if (arg === '--validate') { + validate(); +} else if (arg) { + console.error('Unknown flag: ' + arg); + console.error('Usage: node scripts/build-pi.mjs [--check\|--validate]'); + process.exit(2); +} else { + const { skills, skillFiles, referenceFiles } = build(DIST_SKILLS); + console.log('Pi build complete -> ' + rel(DIST_SKILLS)); + console.log(' skills copied: ' + skills); + console.log(' SKILL.md files copied: ' + skillFiles); + console.log(' reference files copied: ' + referenceFiles); +} diff --git a/scripts/crosslink_pass.py b/scripts/crosslink_pass.py new file mode 100644 index 0000000..d895aff --- /dev/null +++ b/scripts/crosslink_pass.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 +r"""One-shot script for the cross-linking pass. + +Convert plain-text mentions of ``references/X.md`` and ``SKILL.md`` into +markdown links so readers can navigate between SKILL.md and reference +files in rendered markdown (GitHub web view, README catalog). + +Patterns handled: + +1. In every ``skills//SKILL.md``, replace inline-code mentions + ``\`references/X.md\`` that are NOT already part of a markdown link + with ``[\`references/X.md\`](references/X.md)``. + +2. In every ``skills//references/.md``, replace plain-text mentions + of ``SKILL.md`` that are NOT already part of a markdown link with + ``[SKILL.md](../SKILL.md)``. + +The ``skill-template.md`` template file is skipped for the SKILL.md +substitution because its mentions are templating instructions, not +references to a sibling SKILL.md. + +Run from the repo root: ``python scripts/crosslink_pass.py``. + +Idempotent: running twice produces the same result as running once. +Reports counts so the result can be diffed. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" + +# Files to skip for the SKILL.md -> [SKILL.md](../SKILL.md) substitution. +# The template file's mentions are templating instructions, not references. +SKIP_SKILL_LINK_FILES = { + SKILLS_DIR / "skill-creation-walkthrough" / "references" / "skill-template.md", +} + +# Pattern 1: ``\`references/X.md\`` that's NOT already preceded by ``[`` (which +# would mean it's the link text inside ``[\`references/X.md\`](references/X.md)``). +REF_INLINE_CODE_RE = re.compile( + r"(?<!\[)`(references/[a-z][a-z0-9-]\.md)`" +) + +# Pattern 2: bare ``SKILL.md`` (not inline code, not a link target). Match a +# word-boundary before so we don't catch ``MYSKILL.md``. Skip mentions inside +# inline code spans (between backticks) and existing links. +SKILL_BARE_RE = re.compile( + r"(?<![`/\[\w-])SKILL\.md(?!\)\|`)" +) + + +def link_references_in_skill_md(text: str) -> tuple[str, int]: + """Replace inline-code reference paths with markdown links.""" + count = 0 + + def replace(match: re.Match[str]) -> str: + nonlocal count + path = match.group(1) + count += 1 + return f"[`{path}`]({path})" + + return REF_INLINE_CODE_RE.sub(replace, text), count + + +def link_skill_md_in_reference(text: str) -> tuple[str, int]: + """Replace bare SKILL.md mentions with markdown links.""" + count = 0 + + def replace(match: re.Match[str]) -> str: + nonlocal count + count += 1 + return "[SKILL.md](../SKILL.md)" + + return SKILL_BARE_RE.sub(replace, text), count + + +def main() -> int: + if not SKILLS_DIR.exists(): + print(f"ERROR: {SKILLS_DIR} not found", file=sys.stderr) + return 1 + + skill_md_changes = 0 + skill_md_files_touched = 0 + skill_md_total = 0 + ref_changes = 0 + ref_files_touched = 0 + ref_total = 0 + + for skill_dir in sorted(SKILLS_DIR.iterdir()): + if not skill_dir.is_dir(): + continue + + # Pattern 1: SKILL.md + skill_md_path = skill_dir / "SKILL.md" + if skill_md_path.exists(): + skill_md_total += 1 + text = skill_md_path.read_text(encoding="utf-8") + new_text, count = link_references_in_skill_md(text) + if new_text != text: + skill_md_path.write_text(new_text, encoding="utf-8") + skill_md_files_touched += 1 + skill_md_changes += count + + # Pattern 2: references/.md + ref_dir = skill_dir / "references" + if ref_dir.exists(): + for ref_path in sorted(ref_dir.iterdir()): + if not ref_path.is_file() or ref_path.suffix != ".md": + continue + ref_total += 1 + if ref_path in SKIP_SKILL_LINK_FILES: + continue + text = ref_path.read_text(encoding="utf-8") + new_text, count = link_skill_md_in_reference(text) + if new_text != text: + ref_path.write_text(new_text, encoding="utf-8") + ref_files_touched += 1 + ref_changes += count + + print( + f"SKILL.md pass: {skill_md_changes} replacements across " + f"{skill_md_files_touched} of {skill_md_total} files" + ) + print( + f"references pass: {ref_changes} replacements across " + f"{ref_files_touched} of {ref_total} files" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate_og_card.py b/scripts/generate_og_card.py new file mode 100644 index 0000000..8c47c32 --- /dev/null +++ b/scripts/generate_og_card.py @@ -0,0 +1,248 @@ +#!/usr/bin/env python3 +"""Generate the GitHub Social Preview card (``og-card.png``) for this repo. + +Produces a 1280 by 640 PNG that GitHub displays when someone shares the +repo URL on Twitter, LinkedIn, Slack, etc. The output is committed to +the repo root; configuring GitHub's Social Preview is a separate manual +step (Settings to Social Preview to Upload). + +Design intent: + +- Brand-consistent palette matching rampstack.co (navy gradient base, + gold accent dot, cyan decorative pattern, white display type). +- Distinctive enough that the card does not read as the default GitHub + repo template; the dot grid on the right hints at catalog density + without being chartjunk. +- Single-line ASCII text only so it renders identically across the + fonts that ship with Pillow's bundled installations. + +Counts shown on the card are pulled live from the catalog, so the card +stays in sync as the catalog grows. Re-run after meaningful changes +(skill count change, walkthrough or integration count change). + +Run from the repo root:: + + python scripts/generate_og_card.py +""" + +from __future__ import annotations + +import os +import re +import sys +from pathlib import Path + +import numpy as np +from PIL import Image, ImageDraw, ImageFont + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" +OUTPUT = REPO_ROOT / "og-card.png" + +# Card dimensions: GitHub Social Preview recommended size. +WIDTH, HEIGHT = 1280, 640 + +# Brand palette. Hex values match rampstack.co (CSS custom properties +# in app/globals.css of the rampstackco-app repo). +BG_TOP = (15, 23, 42) # slate-900-ish +BG_BOTTOM = (21, 32, 70) # brand-navy +ACCENT = (255, 210, 125) # warm gold +CYAN = (59, 180, 224) # brand-cyan +INK = (248, 250, 252) # near-white +MUTED = (203, 213, 225) # slate-300 + +# Typography sizes. Tuned for 1280x640 against Arial which ships with +# Pillow on Windows; falls back to Arial-equivalent on other systems. +SIZE_EYEBROW = 26 +SIZE_TITLE = 100 +SIZE_SUBTITLE = 36 +SIZE_FOOTER = 24 + + +def find_font(weight_hints: list[str], size: int) -> ImageFont.ImageFont: + """Return the first available TrueType font from a hint list. + + Hints are font filenames searched against the system font path. If + none load, falls back to the PIL default bitmap font, which is + coarse but never throws. + """ + for name in weight_hints: + try: + return ImageFont.truetype(name, size) + except OSError: + continue + return ImageFont.load_default() + + +def gradient_background() -> Image.Image: + """Vertical linear gradient from BG_TOP to BG_BOTTOM.""" + top = np.array(BG_TOP, dtype=np.float32) + bottom = np.array(BG_BOTTOM, dtype=np.float32) + t = np.linspace(0.0, 1.0, HEIGHT, dtype=np.float32)[:, None] + rows = top (1.0 - t) + bottom * t + arr = np.tile(rows[:, None, :], (1, WIDTH, 1)).astype(np.uint8) + return Image.fromarray(arr, mode="RGB") + + +def draw_dot_grid(canvas: Image.Image) -> None: + """Subtle dot grid on the right portion of the card. + + Draws a 14-column by 7-row matrix of small cyan circles, with + alpha-fading toward the left so the grid blends into the headline + region rather than competing with it. + """ + overlay = Image.new("RGBA", (WIDTH, HEIGHT), (0, 0, 0, 0)) + draw = ImageDraw.Draw(overlay) + + cols, rows = 14, 7 + grid_x_start = 760 # leaves room for headline on the left + grid_x_end = 1200 + grid_y_start = 80 + grid_y_end = 560 + radius = 5 + + col_step = (grid_x_end - grid_x_start) / (cols - 1) + row_step = (grid_y_end - grid_y_start) / (rows - 1) + + for c in range(cols): + x = grid_x_start + int(round(c * col_step)) + # Fade from 30 alpha on the left edge of the grid up to 90 on the right. + edge_t = c / (cols - 1) + alpha = int(round(30 + edge_t * 60)) + for r in range(rows): + y = grid_y_start + int(round(r * row_step)) + color = (CYAN[0], CYAN[1], CYAN[2], alpha) + draw.ellipse( + (x - radius, y - radius, x + radius, y + radius), + fill=color, + ) + + canvas.alpha_composite(overlay) + + +def count_skills() -> int: + """Walk skills/ and count folders that contain a SKILL.md. + + Avoids importing the README generator to keep this script + self-contained; the heuristic matches the linter's catalog count. + """ + if not SKILLS_DIR.exists(): + return 0 + return sum( + 1 + for child in SKILLS_DIR.iterdir() + if child.is_dir() and (child / "SKILL.md").exists() + ) + + +def count_walkthroughs() -> int: + """Read the rampstackco-app sibling repo for a live walkthrough count. + + Falls back to 0 if the sibling repo is not checked out next to this + one, which keeps the script runnable in CI clones that only fetch + claude-skills. + """ + sibling = REPO_ROOT.parent.parent / "rampstackco-app" / "app" / "walkthroughs" / "_data" / "walkthroughs.ts" + if not sibling.exists(): + return 0 + text = sibling.read_text(encoding="utf-8") + # Each walkthrough entry begins with ` slug: "..."`. Match those + # specifically rather than the generic `slug: ...` pattern that also + # appears in type definitions. + return len(re.findall(r"^ slug: \"[^\"]+\"", text, re.MULTILINE)) + + +def count_audience_tracks() -> int: + """Number of audience suite tiles on the rampstack.co homepage. + + Sourced from app/page.tsx in the sibling repo. Falls back to 6, + which matches the count at the time this script was written. + """ + sibling = REPO_ROOT.parent.parent / "rampstackco-app" / "app" / "page.tsx" + if not sibling.exists(): + return 6 + text = sibling.read_text(encoding="utf-8") + match = re.search(r"const SKILL_SUITES: SuiteCard\[\]\s=\s\[(.?)\n\];", text, re.DOTALL) + if not match: + return 6 + return len(re.findall(r"^ \{$", match.group(1), re.MULTILINE)) + + +def main() -> int: + canvas = gradient_background().convert("RGBA") + draw_dot_grid(canvas) + draw = ImageDraw.Draw(canvas) + + # Type setting. + font_eyebrow = find_font(["arialbd.ttf", "DejaVuSans-Bold.ttf"], SIZE_EYEBROW) + font_title = find_font(["arialbd.ttf", "DejaVuSans-Bold.ttf"], SIZE_TITLE) + font_subtitle = find_font(["arial.ttf", "DejaVuSans.ttf"], SIZE_SUBTITLE) + font_footer = find_font(["arial.ttf", "DejaVuSans.ttf"], SIZE_FOOTER) + + skill_count = count_skills() + walkthrough_count = count_walkthroughs() + track_count = count_audience_tracks() + + eyebrow = "OPEN SOURCE - MIT LICENSED" + title_line_1 = "Brand Build Skills" + title_line_2 = "for Claude." + subtitle = ( + f"{skill_count} skills - {walkthrough_count} walkthroughs - " + f"{track_count} audience tracks" + ) + footer_left = "github.com/rampstackco/claude-skills" + footer_right = "rampstack.co" + + # Top-left accent dot + eyebrow. + pad_x = 80 + eyebrow_y = 80 + dot_radius = 7 + draw.ellipse( + (pad_x, eyebrow_y + 14, pad_x + dot_radius 2, eyebrow_y + 14 + dot_radius * 2), + fill=ACCENT, + ) + # Tighten letter-tracking by drawing the eyebrow as one block; the + # text method already kerns reasonably for caps + spacing. + draw.text( + (pad_x + dot_radius * 2 + 16, eyebrow_y), + eyebrow, + fill=MUTED, + font=font_eyebrow, + ) + + # Headline. Two lines stacked so the display size stays comfortable + # inside the 1280-wide canvas without crowding the dot grid. + title_y = 180 + line_height = SIZE_TITLE + 12 + draw.text((pad_x, title_y), title_line_1, fill=INK, font=font_title) + draw.text((pad_x, title_y + line_height), title_line_2, fill=INK, font=font_title) + + # Subtitle stat strip. + subtitle_y = title_y + line_height * 2 + 30 + draw.text((pad_x, subtitle_y), subtitle, fill=MUTED, font=font_subtitle) + + # Footer row. + footer_y = HEIGHT - 60 + draw.text((pad_x, footer_y), footer_left, fill=INK, font=font_footer) + # Right-align the rampstack.co mark. + bbox = draw.textbbox((0, 0), footer_right, font=font_footer) + text_width = bbox[2] - bbox[0] + draw.text( + (WIDTH - pad_x - text_width, footer_y), + footer_right, + fill=INK, + font=font_footer, + ) + + # Output. + canvas.convert("RGB").save(OUTPUT, "PNG", optimize=True) + print( + f"Wrote {OUTPUT.relative_to(REPO_ROOT)} " + f"({skill_count} skills, {walkthrough_count} walkthroughs, " + f"{track_count} audience tracks)" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate_readme_catalog.py b/scripts/generate_readme_catalog.py new file mode 100644 index 0000000..66eef2c --- /dev/null +++ b/scripts/generate_readme_catalog.py @@ -0,0 +1,532 @@ +#!/usr/bin/env python3 +"""Generate README.md catalog content from skill folder metadata. + +Walks ``skills/`` and parses each ``SKILL.md`` frontmatter for the fields +``name``, ``description``, ``category``, ``catalog_summary``, and +``display_order``. Produces the README catalog section, the skill count +badge, the subtitle blockquote, the "What you get" counts, the catalog +header, the table-of-contents anchor, the catalog intro line, and a +handful of inline skill counts (install block, install-all paragraph, +hub paragraph, family-table claude-skills row, contributing paragraph) +that are substituted via anchored regex rather than marker pairs. + +Two operating modes: + + --check Exit 0 if README is in sync with skill metadata. Exit 2 with + a unified diff if README is stale. + --write Update README.md in place between marker comments. Print a + one-line summary on success. + +Run from the repo root: ``python scripts/generate_readme_catalog.py --check``. + +Markers in README.md: + + <!-- COUNT_BADGE:START --> ... <!-- COUNT_BADGE:END --> + <!-- COUNT_INTRO:START --> ... <!-- COUNT_INTRO:END --> + <!-- COUNT_WHATYOUGET:START --> ... <!-- COUNT_WHATYOUGET:END --> + <!-- COUNT_TOC:START --> ... <!-- COUNT_TOC:END --> + <!-- FEATURED_SKILLS:START --> ... <!-- FEATURED_SKILLS:END --> + <!-- SURFACES:START --> ... <!-- SURFACES:END --> + <!-- COUNT_CATALOG_HEADER:START --> ... <!-- COUNT_CATALOG_HEADER:END --> + <!-- COUNT_CATALOG_INTRO:START --> ... <!-- COUNT_CATALOG_INTRO:END --> + <!-- CATALOG:START --> ... <!-- CATALOG:END --> +""" + +from __future__ import annotations + +import argparse +import re +import sys +from dataclasses import dataclass +from difflib import unified_diff +from pathlib import Path + +try: + import yaml +except ImportError: + print("ERROR: PyYAML is required. Install with: pip install pyyaml", file=sys.stderr) + sys.exit(1) + + +REPO_ROOT = Path(__file__).resolve().parents[1] +SKILLS_DIR = REPO_ROOT / "skills" +README = REPO_ROOT / "README.md" + + +# Canonical category order. Drives the README catalog section order and the +# allowed values for the ``category`` frontmatter field. Each tuple is +# (category_id, display_title, optional_intro_paragraph). +CATEGORIES: list[tuple[str, str, str \| None]] = [ + ("strategy-and-discovery", "Strategy and discovery", None), + ("brand", "Brand", None), + ("design", "Design", None), + ("content", "Content", None), + ( + "seo-foundation", + "SEO foundation", + "Tool-agnostic SEO skills. These define the conceptual frameworks. " + "The SEO audit suite below adds the Ahrefs MCP-powered execution layer.", + ), + ( + "seo-audit-suite", + "SEO audit suite (Ahrefs MCP-powered)", + "End-to-end SEO audit workflows that pull data from the Ahrefs MCP " + "and produce concrete deliverables. These skills assume the Ahrefs " + "MCP is connected.", + ), + ("product", "Product", None), + ("development", "Development", None), + ("qa", "Quality assurance", None), + ("operations", "Operations", None), + ("growth", "Growth", None), + ( + "growth-tooling", + "Growth tooling", + "Interactive web tools that turn visitors into leads. Lead " + "magnets, calculators, quizzes, multi-step forms, chatbots, " + "and the cross-tool funnel architecture that orchestrates them.", + ), + ( + "marketing", + "Marketing", + "Paid media discipline: strategy, creative, and performance " + "analytics. Pairs with the paid media platforms in the " + "/integrations catalog at rampstack.co.", + ), + ("research", "Research", None), + ("cross-cutting", "Cross-cutting workflows", None), + ("process-and-team", "Process and team", None), +] +CATEGORY_IDS = {cid for cid, _, _ in CATEGORIES} + + +MARKERS = [ + "COUNT_INTRO", + "COUNT_WHATYOUGET", + "COUNT_TOC", + "FEATURED_SKILLS", + "SURFACES", + "COUNT_CATALOG_HEADER", + "COUNT_CATALOG_INTRO", + "CATALOG", +] + + +# Featured skills section: one entry-point skill per audience track. +# These six map to the audience tracks that the rampstack.co landing +# surfaces are organized around. Order matches the homepage suite tiles. +# Tuple shape: (track_label, slug, one-line blurb). +FEATURED_SKILLS_DATA: list[tuple[str, str, str]] = [ + ( + "Brand and creative", + "creative-direction", + "Four-axis brief (tone, aesthetic, audience, sensory ambition) that gives every downstream skill a coherent direction", + ), + ( + "PM, experimentation", + "experiment-design", + "From hypothesis to decision: sample size, duration, segment analysis, and the failure modes that produce wrong shipping calls", + ), + ( + "PM, gap-closing", + "feature-launch-playbook", + "The discipline of launching a feature well: positioning, internal alignment, customer comms, enablement, rollout, monitoring", + ), + ( + "Content", + "pillar-content-architecture", + "Hub-and-cluster topical authority: pillar selection, cluster planning, internal linking, refresh discipline", + ), + ( + "Marketing", + "landing-page-copy", + "Landing pages, sales pages, hero-to-CTA flow with copy that converts", + ), + ( + "Growth tooling", + "funnel-flow-architecture", + "Cross-tool conversion flows architected to match the audience and the funnel stage", + ), +] + + +# Surfaces section: explains the layered offering (open-source methodology + +# commercial flagship surfaces at rampstack.co). Static content; the URLs +# do not change with each catalog update. +SURFACES_CONTENT = """\ +This catalog is the open-source methodology layer. Commercial surfaces at [rampstack.co](https://rampstack.co) extend it: + +- [Skills directory](https://rampstack.co/skills). Every skill on a curated landing surface with audience tracks, search, and category navigation. +- [Walkthroughs](https://rampstack.co/walkthroughs). Multi-skill recipes that orchestrate skill clusters end-to-end. Use these when one skill is not enough and a packaged sequence is. +- [Integrations directory](https://rampstack.co/integrations). Curated MCPs, APIs, and tooling that the skills hook into. +- [Showcase](https://rampstack.co/showcase). Real brand sites built from these skills, with the brief that produced each one. + +The skills in this repository remain free, open-source, and stack-agnostic. The surfaces above are how the same methodology is delivered as a product.""" + + +@dataclass(frozen=True) +class Skill: + slug: str + name: str + description: str + category: str + catalog_summary: str + display_order: int \| None + + +def parse_frontmatter(skill_md: Path) -> dict: + """Read SKILL.md and return its YAML frontmatter as a dict.""" + text = skill_md.read_text(encoding="utf-8") + match = re.match(r"^---\s\n(.?)\n---\s\n(.)$", text, re.DOTALL) + if not match: + raise ValueError(f"{skill_md}: no YAML frontmatter delimited by --- markers") + data = yaml.safe_load(match.group(1)) + if not isinstance(data, dict): + raise ValueError(f"{skill_md}: frontmatter is not a YAML dict") + return data + + +def load_skills() -> list[Skill]: + """Walk SKILLS_DIR and return validated Skill records. + + Raises SystemExit with a list of validation errors if any skill is + missing required fields or has an unknown category. + """ + skills: list[Skill] = [] + errors: list[str] = [] + for entry in sorted(SKILLS_DIR.iterdir()): + if not entry.is_dir(): + continue + skill_md = entry / "SKILL.md" + if not skill_md.exists(): + continue + try: + fm = parse_frontmatter(skill_md) + except ValueError as exc: + errors.append(str(exc)) + continue + name = fm.get("name") + description = fm.get("description") + category = fm.get("category") + catalog_summary = fm.get("catalog_summary") + display_order = fm.get("display_order") + missing = [ + label + for label, value in ( + ("name", name), + ("description", description), + ("category", category), + ("catalog_summary", catalog_summary), + ) + if not value + ] + if missing: + errors.append( + f"{entry.name}: missing frontmatter fields: {', '.join(missing)}" + ) + continue + if category not in CATEGORY_IDS: + allowed = ", ".join(sorted(CATEGORY_IDS)) + errors.append( + f"{entry.name}: unknown category '{category}'. " + f"Allowed values: {allowed}" + ) + continue + desc_len = len(str(description)) + if desc_len > 1024: + errors.append( + f"{entry.name}: description is {desc_len} characters, " + f"exceeds the 1024-character portability cap (Codex CLI, Pi, " + f"and Antigravity reject longer descriptions)" + ) + continue + skills.append( + Skill( + slug=entry.name, + name=str(name), + description=str(description), + category=str(category), + catalog_summary=str(catalog_summary), + display_order=int(display_order) if display_order is not None else None, + ) + ) + if errors: + raise SystemExit("Skill frontmatter validation failed:\n " + "\n ".join(errors)) + return skills + + +def group_by_category(skills: list[Skill]) -> dict[str, list[Skill]]: + """Bucket skills by category id and sort within each bucket. + + Sort key: (display_order ascending, slug ascending). Skills without a + display_order sort to the end alphabetically. + """ + grouped: dict[str, list[Skill]] = {cid: [] for cid, _, _ in CATEGORIES} + for skill in skills: + grouped[skill.category].append(skill) + sentinel = 10_000 + for items in grouped.values(): + items.sort( + key=lambda s: (s.display_order if s.display_order is not None else sentinel, s.slug) + ) + return grouped + + +def count_reference_files() -> int: + """Count files under any skills//references/ directory, at any depth. + + Recurses into nested reference subdirectories (for example + references/by-vertical/) so every shipped reference file is counted, + including the ones below the top level of references/. + """ + total = 0 + for entry in sorted(SKILLS_DIR.iterdir()): + if not entry.is_dir(): + continue + ref_dir = entry / "references" + if not ref_dir.exists(): + continue + for ref in ref_dir.rglob(""): + if ref.is_file(): + total += 1 + return total + + +def generate_catalog(grouped: dict[str, list[Skill]]) -> str: + """Build the full catalog markdown block: section headers and tables.""" + lines: list[str] = [] + for index, (cid, title, intro) in enumerate(CATEGORIES): + items = grouped.get(cid, []) + lines.append(f"### {title} ({len(items)})") + lines.append("") + if intro: + lines.append(intro) + lines.append("") + lines.append("\| Skill \| What it does \|") + lines.append("\|---\|---\|") + for skill in items: + lines.append( + f"\| [`{skill.slug}`](skills/{skill.slug}/SKILL.md) \| " + f"{skill.catalog_summary} \|" + ) + if index < len(CATEGORIES) - 1: + lines.append("") + return "\n".join(lines) + + +def generate_badge(total: int) -> str: + return f"[![Skills](https://img.shields.io/badge/Skills-{total}-blue.svg)](#the-{total}-skill-catalog)" + + +def generate_intro_blockquote(total: int) -> str: + return ( + f"> {total} stack-agnostic skills covering brand, design, content, " + "SEO, dev, ops, growth, and research. Includes an Ahrefs MCP-powered " + "SEO audit suite. Use them on Next.js, WordPress, Shopify, Webflow, " + "plain HTML, or anything else." + ) + + +def generate_whatyouget(total: int, ref_total: int, cat_total: int) -> str: + return ( + f"- {total} skills across {cat_total} categories, every one " + "with a complete `SKILL.md` and at least one reference file\n" + f"- {ref_total} reference files (templates, checklists, decision " + "matrices, worked examples)" + ) + + +def generate_toc_link(total: int) -> str: + return f"- [The {total}-skill catalog](#the-{total}-skill-catalog)" + + +def generate_catalog_header(total: int) -> str: + return f"## The {total}-skill catalog" + + +def generate_catalog_intro(total: int) -> str: + return ( + f"All {total} skills are shipped. Each has a complete SKILL.md " + "plus at least one reference file (template, checklist, or playbook)." + ) + + +def generate_featured_skills(skills_by_slug: dict[str, Skill]) -> str: + """Build the Featured skills section as an intro line + markdown table.""" + missing = [slug for _, slug, _ in FEATURED_SKILLS_DATA if slug not in skills_by_slug] + if missing: + raise ValueError( + "Featured skills not found in catalog: " + ", ".join(missing) + ) + lines = [ + "Six entry-point skills, one per audience track. Run any of these standalone, or compose them with the rest of the catalog.", + "", + "\| Skill \| What it does \|", + "\|---\|---\|", + ] + for track, slug, blurb in FEATURED_SKILLS_DATA: + lines.append(f"\| [`{slug}`](skills/{slug}/SKILL.md) ({track}) \| {blurb} \|") + return "\n".join(lines) + + +def generate_surfaces() -> str: + """Return the static Surfaces section body.""" + return SURFACES_CONTENT + + +def replace_block(text: str, marker: str, new_content: str) -> str: + """Replace the body between a START/END marker pair. + + The replacement body is sandwiched by single newlines, producing:: + + <!-- MARKER:START --> + {new_content} + <!-- MARKER:END --> + """ + pattern = re.compile( + rf"(<!-- {re.escape(marker)}:START -->)(.?)(<!-- {re.escape(marker)}:END -->)", + re.DOTALL, + ) + matches = list(pattern.finditer(text)) + if not matches: + raise ValueError(f"Marker pair '{marker}' not found in README.md") + if len(matches) > 1: + raise ValueError(f"Marker pair '{marker}' appears more than once in README.md") + replacement = f"\\1\n{new_content}\n\\3" + return pattern.sub(replacement, text, count=1) + + +def replace_badge_count(text: str, total: int) -> str: + """Substitute the skill count in the Skills badge markdown. + + The badge sits inline inside a centered div alongside other badges. + A line that begins with an HTML comment triggers CommonMark's HTML + block (type 2) parsing, which prevents inline markdown from being + parsed on that line. Wrapping the badge with marker comments breaks + the badge rendering. Anchor on the unique full-badge markdown + pattern instead, so the substitution touches only the badge in the + centered div and leaves the TOC link and catalog header (which + have their own marker-based substitution) alone. + """ + badge_pattern = re.compile( + r"\[!\[Skills\]\(https://img\.shields\.io/badge/Skills-(\d+)-blue\.svg\)\]" + r"\(#the-(\d+)-skill-catalog\)" + ) + matches = list(badge_pattern.finditer(text)) + if not matches: + raise ValueError("Skills badge markdown pattern not found in README.md") + if len(matches) > 1: + raise ValueError("Skills badge markdown pattern appears more than once in README.md") + replacement = ( + f"[![Skills](https://img.shields.io/badge/Skills-{total}-blue.svg)]" + f"(#the-{total}-skill-catalog)" + ) + return badge_pattern.sub(replacement, text, count=1) + + +def replace_inline_count(text: str, pattern: str, total: int, label: str) -> str: + """Substitute a skill count embedded in prose or a code fence. + + The pattern must capture the text before the count as group 1 and the + text after as group 2, with the digits ungrouped between them. Asserts + the pattern matches exactly once so a drifted or duplicated anchor fails + loudly rather than silently mis-substituting. + """ + rx = re.compile(pattern) + matches = list(rx.finditer(text)) + if not matches: + raise ValueError(f"{label}: count pattern not found in README.md") + if len(matches) > 1: + raise ValueError(f"{label}: count pattern appears more than once in README.md") + return rx.sub(rf"\g<1>{total}\g<2>", text, count=1) + + +def render_readme(text: str, skills: list[Skill]) -> str: + """Apply all marker replacements and return the updated README content.""" + grouped = group_by_category(skills) + skills_by_slug = {s.slug: s for s in skills} + total = len(skills) + ref_total = count_reference_files() + cat_total = len(CATEGORIES) + text = replace_badge_count(text, total) + text = replace_inline_count(text, r"(# full catalog \()\d+( skills\))", total, "install-block count") + text = replace_inline_count(text, r"(You do not have to install all )\d+(\.)", total, "install-all count") + text = replace_inline_count(text, r"(already uses\. )\d+( skills at the center)", total, "hub count") + text = replace_inline_count(text, r"(Full catalog \(you are here\) \\| )\d+( \\|)", total, "family-table count") + text = replace_inline_count(text, r"(authoring discipline used across all )\d+( skills)", total, "contributing count") + text = replace_block(text, "COUNT_INTRO", generate_intro_blockquote(total)) + text = replace_block( + text, "COUNT_WHATYOUGET", generate_whatyouget(total, ref_total, cat_total) + ) + text = replace_block(text, "COUNT_TOC", generate_toc_link(total)) + text = replace_block(text, "FEATURED_SKILLS", generate_featured_skills(skills_by_slug)) + text = replace_block(text, "SURFACES", generate_surfaces()) + text = replace_block(text, "COUNT_CATALOG_HEADER", generate_catalog_header(total)) + text = replace_block(text, "COUNT_CATALOG_INTRO", generate_catalog_intro(total)) + text = replace_block(text, "CATALOG", generate_catalog(grouped)) + return text + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Generate README catalog content from skill folder metadata." + ) + mode = parser.add_mutually_exclusive_group(required=True) + mode.add_argument( + "--check", + action="store_true", + help="Exit non-zero with a diff if README is stale.", + ) + mode.add_argument( + "--write", + action="store_true", + help="Update README.md in place between marker comments.", + ) + args = parser.parse_args() + + if not SKILLS_DIR.exists(): + print(f"ERROR: skills/ directory not found at {SKILLS_DIR}", file=sys.stderr) + return 1 + + try: + skills = load_skills() + except SystemExit as exc: + print(f"ERROR: {exc}", file=sys.stderr) + return 1 + + current = README.read_text(encoding="utf-8") + try: + updated = render_readme(current, skills) + except ValueError as exc: + print(f"ERROR: {exc}", file=sys.stderr) + return 1 + + if args.check: + if current == updated: + return 0 + diff = unified_diff( + current.splitlines(keepends=True), + updated.splitlines(keepends=True), + fromfile="README.md (current)", + tofile="README.md (generated)", + ) + sys.stdout.writelines(diff) + print( + "\nREADME catalog is stale. " + "Run: python scripts/generate_readme_catalog.py --write" + ) + return 2 + + # Write LF newlines explicitly so --write does not flip the file to + # CRLF on Windows, which would churn every line in the diff. + README.write_text(updated, encoding="utf-8", newline="\n") + ref_total = count_reference_files() + print( + f"Updated {len(MARKERS)} sections in README.md, " + f"{len(skills)} skills, {ref_total} reference files" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/accessibility-audit/SKILL.md b/skills/accessibility-audit/SKILL.md new file mode 100644 index 0000000..9a93d44 --- /dev/null +++ b/skills/accessibility-audit/SKILL.md @@ -0,0 +1,239 @@ +--- +name: accessibility-audit +description: "Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, accessibility report, fix accessibility, axe scan. Also triggers when accessibility issues have been reported and need systematic remediation." +category: development +catalog_summary: "WCAG compliance audit with remediation plan" +display_order: 3 +--- + +# Accessibility Audit + +Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant. + +This skill goes deeper than the accessibility checks in `qa-testing` and `design-standards`. Use this when accessibility itself is the goal. + +--- + +## When to use + +- Pre-launch accessibility verification +- Compliance preparation (ADA, EN 301 549, AODA, Section 508) +- Remediation after an audit finding or complaint +- Annual or quarterly accessibility health check +- Onboarding accessibility into a team that hasn't prioritized it before + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Component-level accessibility implementation (use `frontend-component-build`) +- Color contrast for design tokens (use `design-standards` or `brand-identity`) + +--- + +## Required inputs + +- The site or product under audit +- The scope (full site, specific section, specific user flow) +- The target standard (WCAG 2.1 AA is most common) +- Any specific concerns or known issues +- Tools available (automated scanners, screen readers, manual testing) + +--- + +## The framework: WCAG's 4 principles + +WCAG organizes accessibility around four principles. The audit covers each in depth. + +### 1. Perceivable + +Information and UI must be presentable in ways users can perceive. + +Audit checks:* + +- Text alternatives. All non-decorative images have descriptive `alt` text. Decorative images use `alt=""`. Complex images (charts, infographics) have long descriptions. +- Time-based media. Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required. +- Adaptable. Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled. +- Distinguishable. Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted. + +### 2. Operable + +UI components and navigation must be operable. + +Audit checks: + +- Keyboard accessible. All functionality available via keyboard alone. No keyboard traps. Focus visible. +- Enough time. Time limits can be adjusted, paused, or extended. Auto-updating content can be paused. +- Seizures and physical reactions. No content that flashes more than 3 times per second. +- Navigable. Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive. +- Input modalities. Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives. + +### 3. Understandable + +Information and operation must be understandable. + +Audit checks: + +- Readable. Page language declared (`<html lang="...">`). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience. +- Predictable. Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly. +- Input assistance. Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission. + +### 4. Robust + +Content must be robust enough to work with current and future user agents. + +Audit checks: + +- Compatible. Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced. + +--- + +## Audit methodology + +### Stage 1: Automated scan + +Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest. + +Tools: +- axe DevTools (browser extension) +- Lighthouse (Chrome DevTools accessibility audit) +- WAVE (browser extension) +- Pa11y (CLI for batch scanning) + +Output: A list of automated findings, by page. + +### Stage 2: Manual keyboard testing + +Unplug the mouse. Navigate the priority user flows using only keyboard. + +Test: +- Tab and Shift+Tab move through interactive elements in logical order +- Enter activates buttons and links +- Space activates buttons (and toggles checkboxes) +- Arrow keys navigate within composite widgets (tabs, menus, listboxes) +- Escape dismisses modals, popovers, menus +- Focus is always visible +- Focus returns to a sensible place after modals or popovers close +- No keyboard trap (focus can always leave) + +Document: Any flow where keyboard navigation breaks down. + +### Stage 3: Screen reader testing + +Test with at least one real screen reader. Each combination has quirks. + +Common combinations: +- VoiceOver + Safari (macOS / iOS) +- NVDA + Firefox or Chrome (Windows) +- JAWS + Chrome (Windows; commercial but common in enterprise) +- TalkBack + Chrome (Android) + +Test: +- Page structure announced correctly (headings, landmarks) +- Form labels read with their inputs +- Errors announced when they appear +- Status changes announced (loading, success, error) +- Modal context announced when opened +- Images have meaningful alt text (or are correctly identified as decorative) + +### Stage 4: Visual testing + +Verify the visual aspects of accessibility. + +Test: +- Color contrast for all text/background pairs (use a contrast checker) +- UI element contrast (3:1 for icons, borders, focus rings) +- Color-blindness simulation (deuteranopia at minimum) +- Zoom to 200% - content remains usable, no horizontal scroll +- Reflow at 320px viewport +- Text spacing applied (line height, letter spacing) - no content cut off +- Motion can be reduced (`prefers-reduced-motion` honored) + +### Stage 5: Cognitive accessibility + +Often overlooked. Critical for inclusive products. + +Test: +- Reading level appropriate +- Instructions clear +- Error messages explain how to fix the error, not just that one occurred +- Forms allow correction before submission +- Time limits avoidable or extendable +- Important content not dependent on memory of prior pages + +--- + +## Workflow + +1. Define scope. Full site? Specific flows? Specific page templates? +2. Run automated scans. Document findings per page. +3. Manual keyboard pass. Test all priority flows. +4. Screen reader pass. Test with at least one combination. +5. Visual checks. Contrast, zoom, color blindness, motion. +6. Cognitive checks. Reading level, error handling, time limits. +7. Score against WCAG. Per success criterion (level A, AA, AAA). +8. Prioritize findings. Critical (blocks users), Important (degrades experience), Minor (polish). +9. Write the report. Use the template in [`references/audit-report-template.md`](references/audit-report-template.md). +10. Build a remediation plan. Sequenced fixes with effort and impact estimates. + +--- + +## Severity classification + +For prioritization: + +Critical (P0): +- Blocks an entire user flow for an assistive-tech user +- Renders a key page completely inaccessible +- Examples: form with no labels, modal without focus management, primary CTA not keyboard-accessible + +Important (P1): +- Significantly degrades the experience for assistive-tech users +- Examples: missing alt text on key images, low-contrast body text, error messages that don't announce + +Minor (P2): +- Affects edge cases or specific assistive technology combinations +- Examples: minor focus order issues, missing decorative alt attributes, edge case keyboard handling + +Polish (P3): +- Above-AA improvements that benefit accessibility but aren't compliance-blocking +- Examples: AAA contrast targets, additional reduced-motion variants, language attributes on inline foreign words + +--- + +## Failure patterns + +- Automated scan only. Catches 30 to 50 percent of issues. The remaining 50 to 70 percent are in keyboard, screen reader, and cognitive testing. +- Testing only on the home page. The home page is usually the most accessible. Bugs hide in deeper flows. +- Treating accessibility as a one-time project. Accessibility erodes with every deploy. Bake it into the development cycle. +- Fixing without root cause. Patching individual issues without understanding why they happened means new ones keep appearing. +- Ignoring screen reader testing. Hard to do well, easy to skip. Single biggest source of "we thought we were accessible" surprises. +- Confusing AA and AAA. AAA is rarely the right target. AA is the practical baseline for most products. +- Treating accessibility as a designer or developer responsibility alone. Content, product, QA, and leadership all need to participate. +- Assuming compliance equals accessibility. WCAG conformance is a floor, not a ceiling. Real users may still struggle. + +--- + +## Output format + +Default output is a comprehensive audit report at `accessibility-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools used, pages tested, screen readers used) +3. Findings by WCAG principle +4. Critical findings (P0) with specific URLs and fixes +5. Important findings (P1) +6. Minor findings (P2) +7. Polish (P3) +8. Remediation roadmap (sequenced and prioritized) +9. Appendices (full automated scan results, keyboard navigation notes, screen reader notes) + +Plus a remediation tracking spreadsheet with one row per finding. + +--- + +## Reference files + +- [`references/audit-report-template.md`](references/audit-report-template.md) - Full audit report template. +- [`references/wcag-quick-reference.md`](references/wcag-quick-reference.md) - Condensed WCAG 2.1 AA criteria with audit checks. +- [`references/aria-patterns.md`](references/aria-patterns.md) - Decision-grade ARIA patterns. Semantic-HTML-first principle, common interactive widgets (accordion, tabs, modal, toggle, disclosure, navigation), live regions, hiding patterns, labeling, state indicators, anti-patterns. diff --git a/skills/accessibility-audit/references/aria-patterns.md b/skills/accessibility-audit/references/aria-patterns.md new file mode 100644 index 0000000..b74fc67 --- /dev/null +++ b/skills/accessibility-audit/references/aria-patterns.md @@ -0,0 +1,471 @@ +# ARIA patterns reference + +Decision-grade ARIA patterns for the audit. Covers when to use ARIA, when to skip it, and the common patterns that recur across web products. + +ARIA is powerful and easy to misuse. The most common mistake is reaching for ARIA when semantic HTML would have done the job already. The second most common mistake is applying ARIA without the supporting JavaScript that makes the attribute true (e.g., `aria-expanded="false"` on a button that does not actually toggle anything). + +This file expands the audit checks in [SKILL.md](../SKILL.md) with the specific patterns auditors should verify and the anti-patterns to flag. + +--- + +## The semantic-HTML-first principle + +Before reaching for ARIA, check whether semantic HTML already does what is needed. + +The principle. ARIA exists to fill gaps in HTML. When semantic HTML provides the same semantics natively, the semantic element is the right answer. Adding ARIA on top of semantic HTML is usually redundant and sometimes broken. + +Examples of redundant ARIA. + +- `<button role="button">` is redundant; the element is already a button. +- `<nav role="navigation">` is redundant; `<nav>` already has the role. +- `<a href="..." role="link">` is redundant; the element is already a link. +- `<input type="checkbox" role="checkbox">` is redundant. + +Examples of correct ARIA. + +- A `<div>` styled to behave like a button needs `role="button"`. A real `<button>` does not. +- A custom dropdown built on `<div>`s needs `role="combobox"` plus full keyboard handling. A `<select>` does not. +- A live status region needs `role="status"` or `aria-live`. A static element does not. + +The audit check. For every ARIA attribute on a page, ask: would this element have the same semantics without ARIA? If yes, the ARIA is redundant; flag it. + +The first ARIA rule. No ARIA is better than bad ARIA. Bad ARIA actively confuses assistive technology; missing ARIA at most leaves a feature inaccessible (which is bad, but recoverable). Bad ARIA misrepresents the UI to the user, which is worse. + +--- + +## Interactive widget patterns + +Patterns that recur across products. + +### Accordion (expandable disclosure section) + +Required ARIA. + +- Trigger button: `aria-expanded="true"` or `aria-expanded="false"` reflecting state. +- Trigger button: `aria-controls="<id-of-panel>"` pointing to the controlled region. +- Panel: `id="<the-id>"` matching `aria-controls`. + +Required behavior. + +- Trigger is a `<button>` (not a `<div>` or `<a>`). +- Trigger toggles `aria-expanded` when activated. +- Click and keyboard (Enter, Space) both work. + +Audit checks. + +- `aria-expanded` reflects current state, not a stale value. +- `aria-controls` ID exists in the DOM. +- Multiple accordions on a page: focus stays on trigger after toggle (does not jump unexpectedly). + +### Tabs + +Required ARIA. + +- Tab list: `role="tablist"`. +- Each tab: `role="tab"`, `aria-selected="true"` or `aria-selected="false"`, `aria-controls="<panel-id>"`. +- Each panel: `role="tabpanel"`, `id="<panel-id>"`, `aria-labelledby="<tab-id>"`. + +Required behavior. + +- Arrow keys move between tabs. +- Tab key moves into and out of the tablist (not between tabs). +- Selected tab has `tabindex="0"`; non-selected tabs have `tabindex="-1"` (roving tabindex). +- Activating a tab updates `aria-selected` and shows the corresponding panel. + +Audit checks. + +- All tabs reachable via arrow keys. +- Tab key escapes the tablist after one press. +- Only one tab has `aria-selected="true"` at a time. + +### Modal / dialog + +Required ARIA. + +- Container: `role="dialog"` (or `role="alertdialog"` for confirmations). +- Container: `aria-modal="true"` when modal. +- Container: `aria-labelledby="<heading-id>"` pointing to the dialog's heading, or `aria-label="<purpose>"`. +- Optional: `aria-describedby="<description-id>"` pointing to descriptive content. + +Required behavior. + +- Focus moves into the modal when opened (typically to the first focusable element or the dialog itself). +- Focus is trapped within the modal while open (Tab cycles within; cannot escape). +- Escape closes the modal. +- Focus returns to the triggering element when the modal closes. +- Background content has `inert` attribute or `aria-hidden="true"` (and is not focusable). + +Audit checks. + +- Focus management on open and close (the most common modal failure). +- Tab does not escape into background content. +- Screen reader does not read background content while modal is open. + +### Toggle button (button that holds state) + +Required ARIA. + +- `aria-pressed="true"` or `aria-pressed="false"` reflecting state. + +Examples. Mute button, favorite button, bold/italic in a text editor. + +Audit checks. + +- `aria-pressed` reflects state, not a stale value. +- Toggling produces an audible state change (some screen readers announce the new pressed state). +- Use of toggle button is appropriate (the button is genuinely a toggle, not a momentary action). + +### Disclosure widget (show/hide additional content) + +Required ARIA. + +- Trigger: `<button>` with `aria-expanded="true"` or `aria-expanded="false"`. +- Optional: `aria-controls="<region-id>"` if the controlled region is not adjacent. + +Examples. "Show more" buttons, "Read more" expansions. + +Difference from accordion. Accordions are typically grouped (multiple panels in a related set, often only one open at a time); disclosure widgets are standalone reveals. The ARIA is similar; the surrounding pattern differs. + +### Navigation + +Required ARIA. + +- `<nav>` element (semantic; no `role="navigation"` needed). +- For multiple navs on a page: each `<nav>` should have `aria-label` or `aria-labelledby` to distinguish them ("Primary", "Footer", "Breadcrumb"). +- Current page link: `aria-current="page"`. + +Audit checks. + +- Multiple navs are distinguishable to screen readers. +- The current page is identified. +- Skip link is present and works (typically "Skip to main content"). + +--- + +## Live region patterns + +Regions that announce dynamically. + +### aria-live + +Values. + +- `aria-live="polite"`: announces when the user is idle. Most common. +- `aria-live="assertive"`: announces immediately, interrupting the user. Use sparingly. +- `aria-live="off"`: do not announce. Default; rarely set explicitly. + +The polite-vs-assertive choice. + +- Polite for status updates that can wait (form save confirmation, content updates). +- Assertive for urgent messages (errors that block submission, session timeout warnings, security alerts). + +Anti-pattern. Assertive on routine updates. The screen reader interrupts whatever the user was doing; trust degrades quickly. + +### aria-atomic + +`aria-atomic="true"` tells screen readers to announce the entire region when any part changes, not just the changed part. + +When to use. When the announcement only makes sense in context (e.g., "5 of 10 items processed" should announce as a whole, not just "5"). + +When not to use. For long regions where atomic announcements would be repetitive. + +### role="status" + +Implicit `aria-live="polite"`. Use for non-urgent status messages. + +Examples. "Item added to cart," "Form saved," "Loading complete." + +### role="alert" + +Implicit `aria-live="assertive"` and `aria-atomic="true"`. Use for urgent messages. + +Examples. Form submission errors, session timeout warnings, security alerts. + +Audit checks. + +- Status and alert regions exist where needed (audit dynamic flows). +- They announce when content changes (test with screen reader). +- The region is not assertive when polite would do. +- The region is not used for static content (status/alert are for dynamic announcements). + +--- + +## Hiding from screen reader patterns + +When and how to hide content. + +### aria-hidden + +`aria-hidden="true"` removes the element and its children from the accessibility tree. + +When to use. + +- Decorative icons that have an adjacent text label (the icon is redundant; hide it). +- Background visual elements that have no semantic meaning. +- Modal closed state (when not using `inert`). + +When NOT to use. + +- On focusable elements. A focusable element with `aria-hidden="true"` produces a confusing experience: keyboard users can focus it, but screen readers will not announce it. +- On meaningful content. If the content is meaningful enough to render visually, it is meaningful enough to announce. +- On entire interactive widgets. The keyboard user can still tab into them; the screen reader cannot announce them. + +Audit check. For every `aria-hidden="true"`, verify the element is not focusable and contains no focusable descendants. The combination is the most common ARIA bug. + +### Visually-hidden CSS class + +A CSS pattern that hides content visually but keeps it in the accessibility tree. + +Common implementation. + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +When to use. + +- Skip links that should be invisible until focused. +- Form labels that the design hides but accessibility requires. +- Additional context for screen reader users (e.g., "Item 3 of 10 in shopping cart"). + +Anti-pattern. Using `display: none` or `visibility: hidden` for content that should remain in the accessibility tree. Both remove from the tree; visually-hidden does not. + +--- + +## Description and labeling patterns + +How to give elements accessible names and descriptions. + +### aria-label + +Provides an accessible name when no visible label exists. + +When to use. + +- Icon-only buttons (`<button aria-label="Close">`). +- Generic links that need context (`<a aria-label="Read more about pricing" href="...">Read more</a>`). +- Form inputs without visible labels (rare; usually a visible label is better). + +When not to use. + +- When a visible `<label>` exists. The visible label is the accessible name. +- For decorative content. Use `aria-hidden` instead. + +### aria-labelledby + +Points to one or more existing elements whose text becomes the accessible name. + +When to use. + +- When the visible label is in another element (e.g., a `<legend>` for a fieldset). +- When the accessible name comes from multiple elements (e.g., "Add to cart" combined with the product name). +- For dialogs labeled by their heading. + +Syntax. `aria-labelledby="id1 id2"` (space-separated IDs; the names concatenate). + +### aria-describedby + +Points to one or more existing elements whose text becomes the accessible description (announced after the name and role). + +When to use. + +- Form fields with help text that should announce after the label. +- Buttons with secondary explanation. +- Errors associated with form inputs (`aria-describedby="error-id"`). + +Syntax. Same as `aria-labelledby`. + +The labeling priority. Browsers compute the accessible name in this priority order: `aria-labelledby` > `aria-label` > `<label>` > placeholder/title (last-resort and unreliable). The accessible description follows: `aria-describedby` > `title`. + +--- + +## State indicator patterns + +ARIA attributes for component state. + +### aria-busy + +`aria-busy="true"` tells assistive tech that the element is in a transitional state (e.g., loading). + +When to use. + +- Sections being updated dynamically. +- Long-running operations where partial content would be confusing. + +Audit check. `aria-busy` is removed when the operation completes. + +### aria-disabled + +`aria-disabled="true"` indicates an element is disabled. + +When to use vs `disabled` attribute. + +- Native HTML `disabled` removes the element from the tab order and prevents interaction. +- `aria-disabled="true"` keeps the element focusable but indicates disabled state. Useful when you want users to focus and read why the element is disabled, but cannot activate it. + +Audit check. When using `aria-disabled`, the element should still appear disabled visually and click handlers should be suppressed. + +### aria-invalid + +`aria-invalid="true"` indicates a form input has a validation error. + +When to use. + +- After validation finds an error. +- Combined with `aria-describedby` pointing to the error message. + +Audit check. `aria-invalid` is set/cleared as validation state changes; not a stale attribute. + +--- + +## Common ARIA anti-patterns + +Patterns to flag in the audit. + +### Overusing roles on semantic elements + +Pattern. `<button role="button">`, `<nav role="navigation">`, `<a role="link">`. + +Why it fails. Redundant; clutters markup; sometimes overrides correct semantics. + +Cure. Remove the redundant role. + +### ARIA without supporting behavior + +Pattern. `aria-expanded="false"` on a button that has no JavaScript to toggle it. + +Why it fails. The attribute lies; assistive tech reports state that does not match reality. + +Cure. Either implement the behavior or remove the attribute. + +### Focusable element with aria-hidden + +Pattern. A `<button>` or `<a>` with `aria-hidden="true"`. + +Why it fails. Keyboard users can focus it; screen readers ignore it. The user encounters a focused element with no announcement. + +Cure. Either remove `aria-hidden` (if the element is meaningful) or remove from tab order with `tabindex="-1"` and disable interaction. + +### Modal without focus management + +Pattern. `role="dialog"` opens; focus stays on the triggering element behind the modal. + +Why it fails. Screen reader users do not realize a modal opened. Keyboard users can tab into background content. + +Cure. Move focus into the modal on open. Trap focus while open. Return focus to trigger on close. + +### Live region without dynamic updates + +Pattern. Static `<div role="status">Loading complete</div>` rendered in initial HTML. + +Why it fails. Live regions only announce when their content changes after page load. Static content in a live region announces nothing. + +Cure. Either remove the role (if the content is static) or update the content dynamically. + +### Assertive live region for routine updates + +Pattern. `role="alert"` on every form-save confirmation. + +Why it fails. Each confirmation interrupts whatever the user was doing. Trust degrades quickly. + +Cure. Use `role="status"` (polite) for non-urgent updates; reserve `role="alert"` for urgent messages. + +### Form input without accessible name + +Pattern. `<input type="text">` with placeholder but no label. + +Why it fails. Screen reader announces "edit" or similar generic; user does not know what the input is for. Placeholder disappears when typing, removing context. + +Cure. Add a visible `<label>` (preferred) or `aria-label`. Placeholder is not a label. + +### Error message not associated with input + +Pattern. Error text appears near a form input but no programmatic association. + +Why it fails. Screen reader users do not hear the error when focused on the input. + +Cure. Use `aria-describedby="error-id"` on the input, with the error message in an element with that ID. Optionally add `aria-invalid="true"`. + +### Tab order broken by tabindex + +Pattern. Positive `tabindex` values (`tabindex="1"`, `tabindex="2"`) used to control order. + +Why it fails. Positive tabindex creates a separate tab order that often conflicts with DOM order; very brittle; almost always wrong. + +Cure. Use `tabindex="0"` to add to natural order, `tabindex="-1"` to remove from natural order. Avoid positive values. + +--- + +## ARIA in audit reports + +What to flag in audit findings. + +Per finding, document: + +- The element (URL plus selector or screenshot). +- The current ARIA (or its absence). +- The behavior observed. +- The behavior expected. +- The fix. + +Severity calibration. + +- Modal without focus management: P0 (blocks assistive-tech users). +- Form input without accessible name: P0. +- Live region using assertive for routine updates: P1. +- Redundant `role="button"` on a `<button>`: P3 (cosmetic, but trims technical debt). + +The severity tracks user impact, not specification adherence per se. A redundant role does not block users; a missing label does. + +--- + +## ARIA testing approach + +How auditors verify ARIA. + +Tooling. + +- Browser DevTools accessibility tree (Chrome, Firefox, Safari) shows what assistive tech sees. +- axe DevTools flags many ARIA misuses. +- Screen reader testing is the ultimate verification. + +Common verification steps. + +- Inspect the accessibility tree for each interactive component. +- Verify dynamic ARIA attributes change when state changes. +- Verify focus management on open/close patterns (modals, menus, popovers). +- Test with at least one screen reader to hear what users hear. + +The accessibility tree (DevTools) often reveals issues invisible to automated scanners. Make it part of the audit. + +--- + +## ARIA references + +Beyond this file. + +- W3C ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/. Patterns and examples. +- WAI-ARIA 1.2 specification: https://www.w3.org/TR/wai-aria-1.2/. Canonical reference. +- The W3C ARIA Roles, States, and Properties listing: https://www.w3.org/TR/wai-aria-1.2/#role_definitions. Searchable. + +The APG is the most practical resource. Most patterns in this file are simplified summaries of APG patterns; for production implementation, consult the APG examples. + +--- + +## Methodology-level choices that stay in the public skill + +The semantic-HTML-first principle. Required ARIA and behavior for common interactive patterns (accordion, tabs, modal, toggle button, disclosure, navigation). Live region patterns (aria-live, aria-atomic, role="status", role="alert"). Hiding patterns (aria-hidden, visually-hidden CSS). Description and labeling patterns (aria-label, aria-labelledby, aria-describedby). State indicators (aria-busy, aria-disabled, aria-invalid). Common anti-patterns. ARIA in audit reports. ARIA testing approach. References. + +## Implementation choices that stay internal + +Specific component implementations in the team's framework. Specific JavaScript and class-name conventions for live regions, focus management, and ARIA toggling. Specific design-system patterns for dialogs, tabs, and accordions. The team's ARIA testing protocols and tooling configurations. These vary by team and stack. diff --git a/skills/accessibility-audit/references/audit-report-template.md b/skills/accessibility-audit/references/audit-report-template.md new file mode 100644 index 0000000..42c8760 --- /dev/null +++ b/skills/accessibility-audit/references/audit-report-template.md @@ -0,0 +1,228 @@ +# Accessibility Audit Report Template + +A fillable accessibility audit template. Customize the level (AA, AAA, EN 301 549) and scope (page, component, site) per project. + +--- + +## Audit metadata + +Audited: [URL or component name] +Date: [YYYY-MM-DD] +Auditor: [Name] +Compliance target: [WCAG 2.1 AA / WCAG 2.1 AAA / EN 301 549] +Scope: [What was and was not tested] +Methodology: [Tools used, manual tests performed] + +--- + +## Executive summary + +[2 to 3 paragraph overview. The state of accessibility, the most important issues, the recommended path forward.] + +Issue counts: + +\| Severity \| Count \| +\|---\|---\| +\| Critical \| \| +\| Major \| \| +\| Minor \| \| +\| Total \| \| + +Top 3 priorities: + +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Tools and methods used + +Automated: +- [ ] axe DevTools +- [ ] Lighthouse accessibility audit +- [ ] WAVE +- [ ] Pa11y (or other CI tool) + +Manual: +- [ ] Keyboard-only navigation +- [ ] Screen reader: [NVDA / JAWS / VoiceOver / TalkBack] +- [ ] 200% zoom +- [ ] Mobile reflow at 320px width +- [ ] Color blindness simulation +- [ ] Windows High Contrast (or browser equivalent) +- [ ] Reduced motion preference + +--- + +## Critical findings + +Findings that block usage for some users. Must be fixed before sign-off. + +### Critical 1: [Issue name] + +- WCAG criterion: [e.g., 2.1.1 Keyboard] +- Severity: Critical +- Affected users: [Keyboard / screen reader / low vision / etc.] +- Reproduction steps: + 1. [Step] + 2. [Step] + 3. [Step] +- Expected: [What should happen] +- Actual: [What does happen] +- Recommended fix: [Specific solution] +- Estimated effort: [Hours / days] +- Owner: [Team or person] + +### Critical 2: [Issue name] + +[Same structure] + +--- + +## Major findings + +Findings that significantly degrade experience. Should be fixed before broad launch. + +### Major 1: [Issue name] + +[Same structure as critical] + +### Major 2: [Issue name] + +[Same structure] + +--- + +## Minor findings + +Findings that add friction without blocking. Tracked and addressed in normal iteration. + +### Minor 1: [Issue name] + +[Brief structure] + +- WCAG criterion: +- Issue: +- Recommended fix: + +--- + +## WCAG 2.1 AA scorecard + +For full audits, score each criterion. For partial audits, score only those in scope. + +### 1. Perceivable + +\| Criterion \| Pass / Fail / N/A \| Notes \| +\|---\|---\|---\| +\| 1.1.1 Non-text content \| \| \| +\| 1.2.1 Audio-only and video-only \| \| \| +\| 1.2.2 Captions (prerecorded) \| \| \| +\| 1.2.3 Audio description or media alternative \| \| \| +\| 1.2.4 Captions (live) \| \| \| +\| 1.2.5 Audio description (prerecorded) \| \| \| +\| 1.3.1 Info and relationships \| \| \| +\| 1.3.2 Meaningful sequence \| \| \| +\| 1.3.3 Sensory characteristics \| \| \| +\| 1.3.4 Orientation \| \| \| +\| 1.3.5 Identify input purpose \| \| \| +\| 1.4.1 Use of color \| \| \| +\| 1.4.2 Audio control \| \| \| +\| 1.4.3 Contrast (minimum) \| \| \| +\| 1.4.4 Resize text \| \| \| +\| 1.4.5 Images of text \| \| \| +\| 1.4.10 Reflow \| \| \| +\| 1.4.11 Non-text contrast \| \| \| +\| 1.4.12 Text spacing \| \| \| +\| 1.4.13 Content on hover or focus \| \| \| + +### 2. Operable + +\| Criterion \| Pass / Fail / N/A \| Notes \| +\|---\|---\|---\| +\| 2.1.1 Keyboard \| \| \| +\| 2.1.2 No keyboard trap \| \| \| +\| 2.1.4 Character key shortcuts \| \| \| +\| 2.2.1 Timing adjustable \| \| \| +\| 2.2.2 Pause, stop, hide \| \| \| +\| 2.3.1 Three flashes or below threshold \| \| \| +\| 2.4.1 Bypass blocks \| \| \| +\| 2.4.2 Page titled \| \| \| +\| 2.4.3 Focus order \| \| \| +\| 2.4.4 Link purpose (in context) \| \| \| +\| 2.4.5 Multiple ways \| \| \| +\| 2.4.6 Headings and labels \| \| \| +\| 2.4.7 Focus visible \| \| \| +\| 2.5.1 Pointer gestures \| \| \| +\| 2.5.2 Pointer cancellation \| \| \| +\| 2.5.3 Label in name \| \| \| +\| 2.5.4 Motion actuation \| \| \| + +### 3. Understandable + +\| Criterion \| Pass / Fail / N/A \| Notes \| +\|---\|---\|---\| +\| 3.1.1 Language of page \| \| \| +\| 3.1.2 Language of parts \| \| \| +\| 3.2.1 On focus \| \| \| +\| 3.2.2 On input \| \| \| +\| 3.2.3 Consistent navigation \| \| \| +\| 3.2.4 Consistent identification \| \| \| +\| 3.3.1 Error identification \| \| \| +\| 3.3.2 Labels or instructions \| \| \| +\| 3.3.3 Error suggestion \| \| \| +\| 3.3.4 Error prevention (legal, financial, data) \| \| \| + +### 4. Robust + +\| Criterion \| Pass / Fail / N/A \| Notes \| +\|---\|---\|---\| +\| 4.1.1 Parsing \| \| \| +\| 4.1.2 Name, role, value \| \| \| +\| 4.1.3 Status messages \| \| \| + +--- + +## Remediation roadmap + +Sequenced by severity and dependency. + +### Phase 1: Critical fixes (target: [date]) + +- [ ] [Critical 1] +- [ ] [Critical 2] + +### Phase 2: Major fixes (target: [date]) + +- [ ] [Major 1] +- [ ] [Major 2] + +### Phase 3: Minor fixes (target: [date]) + +- [ ] [Minor 1] +- [ ] [Minor 2] + +### Phase 4: Process improvements + +- [ ] Add automated a11y checks to CI +- [ ] Establish a11y review in PR process +- [ ] Train design and engineering teams on common failures +- [ ] Set up regular re-audit schedule + +--- + +## Re-audit schedule + +- Verify critical fixes: [Date, typically 1 to 2 weeks post-remediation] +- Verify major fixes: [Date, typically 4 weeks] +- Full re-audit: [Date, typically 6 to 12 months] +- Trigger-based re-audit: Significant design system updates, major feature launches + +--- + +## Sign-off + +Critical fixes verified by: [Name and date] +Major fixes verified by: [Name and date] +Final approval: [Name and date] diff --git a/skills/accessibility-audit/references/wcag-quick-reference.md b/skills/accessibility-audit/references/wcag-quick-reference.md new file mode 100644 index 0000000..4e4afd1 --- /dev/null +++ b/skills/accessibility-audit/references/wcag-quick-reference.md @@ -0,0 +1,250 @@ +# WCAG 2.1 AA Quick Reference + +A condensed list of WCAG 2.1 AA success criteria with the practical audit check for each. + +For the canonical specification, refer to W3C: https://www.w3.org/TR/WCAG21/ + +--- + +## Principle 1: Perceivable + +### 1.1 Text alternatives + +1.1.1 Non-text content (A) +- All meaningful images have descriptive `alt` text +- Decorative images have `alt=""` (empty alt) +- Complex images have long descriptions +- Form inputs have associated labels +- CAPTCHA has alternatives for users who cannot perceive it +- Audit check: scan for `<img>` without `alt`, run alt-text quality review + +### 1.2 Time-based media + +1.2.1 Audio-only and video-only prerecorded (A) +- Audio-only content has a transcript +- Video-only content (no audio) has a description or transcript + +1.2.2 Captions prerecorded (A) +- Pre-recorded video content has captions + +1.2.3 Audio description or media alternative (A) +- Pre-recorded video has audio description OR an alternative + +1.2.4 Captions live (AA) +- Live video content has captions + +1.2.5 Audio description prerecorded (AA) +- Pre-recorded video has audio description + +### 1.3 Adaptable + +1.3.1 Info and relationships (A) +- Structure conveyed through markup, not just visual styling +- Headings use `<h1>` through `<h6>`, not styled `<div>` +- Lists use `<ul>`, `<ol>`, `<li>` +- Tables use `<table>`, `<th>`, `<td>` correctly with `scope` attributes +- Form inputs have `<label>` associated via `for`/`id` or `aria-labelledby` + +1.3.2 Meaningful sequence (A) +- Reading order makes sense without CSS +- Audit check: disable CSS, read the page top to bottom + +1.3.3 Sensory characteristics (A) +- Instructions don't rely solely on shape, size, color, or position +- Audit check: avoid "click the green button" or "the button on the right" + +1.3.4 Orientation (AA) +- Content does not restrict view to a single orientation (portrait or landscape) + +1.3.5 Identify input purpose (AA) +- Form fields collecting user information use `autocomplete` attributes correctly + +### 1.4 Distinguishable + +1.4.1 Use of color (A) +- Color is not the only way information is conveyed +- Audit check: check error states, status indicators, chart elements + +1.4.2 Audio control (A) +- Audio that plays automatically for more than 3 seconds has pause/stop control + +1.4.3 Contrast minimum (AA) +- Normal text contrast ratio at least 4.5:1 +- Large text (18pt regular or 14pt bold) at least 3:1 +- Audit check: contrast checker on every text/background pair + +1.4.4 Resize text (AA) +- Text can be resized to 200% without loss of content or functionality +- Audit check: zoom to 200% in the browser, verify usability + +1.4.5 Images of text (AA) +- Use real text, not images of text, except for logos or where customization is essential + +1.4.10 Reflow (AA) +- Content can be presented without horizontal scrolling at 320px viewport +- Audit check: resize to 320px, verify no horizontal scroll + +1.4.11 Non-text contrast (AA) +- UI components and graphical objects at least 3:1 contrast ratio against adjacent colors +- Audit check: borders, icons, form field outlines, focus rings + +1.4.12 Text spacing (AA) +- No loss of content or functionality when text spacing is increased to specific minimums +- Audit check: apply line-height: 1.5, letter-spacing: 0.12em, word-spacing: 0.16em, paragraph-spacing: 2x font size + +1.4.13 Content on hover or focus (AA) +- Hover/focus tooltips can be dismissed, hovered, and persist until dismissed + +--- + +## Principle 2: Operable + +### 2.1 Keyboard accessible + +2.1.1 Keyboard (A) +- All functionality available from keyboard +- Audit check: navigate the entire site without a mouse + +2.1.2 No keyboard trap (A) +- Focus can always be moved away from any component using keyboard alone +- Audit check: open every modal, dropdown, widget; verify Tab can leave + +2.1.4 Character key shortcuts (A) +- If single-character keyboard shortcuts exist, they can be turned off, remapped, or only active on focus + +### 2.2 Enough time + +2.2.1 Timing adjustable (A) +- Time limits can be turned off, adjusted, or extended (with exceptions for real-time and essential) + +2.2.2 Pause, stop, hide (A) +- Auto-updating content can be paused or stopped (with exceptions for essential) + +### 2.3 Seizures and physical reactions + +2.3.1 Three flashes or below threshold (A) +- Nothing flashes more than 3 times per second + +### 2.4 Navigable + +2.4.1 Bypass blocks (A) +- Skip link present at the top of the page +- Or, use proper landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`) + +2.4.2 Page titled (A) +- Each page has a unique, descriptive `<title>` + +2.4.3 Focus order (A) +- Focus order matches visual and logical reading order + +2.4.4 Link purpose in context (A) +- Link purpose is clear from the link text alone, or from text + immediate surrounding context +- Avoid "click here," "read more," "learn more" without context + +2.4.5 Multiple ways (AA) +- Multiple ways to find content (sitemap, search, navigation menu) + +2.4.6 Headings and labels (AA) +- Headings and labels are descriptive + +2.4.7 Focus visible (AA) +- Keyboard focus indicator is visible +- Audit check: Tab through the page; can you always see where focus is? + +### 2.5 Input modalities + +2.5.1 Pointer gestures (A) +- Multipoint or path-based gestures have single-point alternative + +2.5.2 Pointer cancellation (A) +- Down-event does not trigger action; action triggers on up-event or has way to abort + +2.5.3 Label in name (A) +- Accessible name (for screen readers) contains the visible label text + +2.5.4 Motion actuation (A) +- Motion-triggered functionality has UI alternative and can be disabled + +--- + +## Principle 3: Understandable + +### 3.1 Readable + +3.1.1 Language of page (A) +- Page language declared in HTML: `<html lang="en">` + +3.1.2 Language of parts (AA) +- Inline foreign-language passages marked: `<span lang="fr">...</span>` + +### 3.2 Predictable + +3.2.1 On focus (A) +- Receiving focus does not change context (no auto-submit, no unexpected navigation) + +3.2.2 On input (A) +- Changing a setting does not automatically change context unless user is warned + +3.2.3 Consistent navigation (AA) +- Navigation appears in the same relative order across pages + +3.2.4 Consistent identification (AA) +- Components with the same function are identified consistently + +### 3.3 Input assistance + +3.3.1 Error identification (A) +- Errors are identified and described in text (not just color or icon) + +3.3.2 Labels or instructions (A) +- Labels or instructions provided for inputs requiring user input + +3.3.3 Error suggestion (AA) +- When errors occur and suggestions are known, suggestions are provided + +3.3.4 Error prevention (legal, financial, data) (AA) +- For pages causing legal commitments or financial transactions: submissions are reversible, checked for errors, OR confirmed before final submission + +--- + +## Principle 4: Robust + +### 4.1 Compatible + +4.1.1 Parsing (A) [removed in 2.2 but still in 2.1] +- Markup is well-formed (no duplicate IDs, properly nested elements) + +4.1.2 Name, role, value (A) +- For all UI components, name and role can be programmatically determined; states, properties, and values can be set +- Use semantic HTML, ARIA where needed + +4.1.3 Status messages (AA) +- Status messages can be programmatically determined through role or properties so they can be announced by assistive technology +- Use `role="status"`, `role="alert"`, or `aria-live` + +--- + +## Audit check summary + +For each criterion, the audit needs to: + +1. Identify the requirement (what does WCAG ask for?) +2. Test against the site (does the site meet it?) +3. Document failures (which pages, which elements, what's wrong) +4. Specify the fix (what specific change resolves it) +5. Assign severity (P0 critical, P1 important, P2 minor, P3 polish) +6. Estimate effort (small, medium, large) + +A complete audit covers all 30+ AA criteria. Most sites fail 5 to 15 of them on first audit. Don't try to fix all at once. Sequence by severity and impact. + +--- + +## What WCAG does NOT cover + +WCAG is a floor, not a ceiling. Some accessibility considerations are outside its scope: + +- Cognitive accessibility nuances (reading level, attention, memory) - some basics in 3.1, but limited +- Audience-specific needs (the cognitive support a user with dyslexia needs vs. a user with autism) +- Mental models (whether the navigation makes sense to your specific audience) + +For these, supplement WCAG with usability testing including users with disabilities, and with specific design patterns aimed at cognitive accessibility. diff --git a/skills/ads-creative-development/SKILL.md b/skills/ads-creative-development/SKILL.md new file mode 100644 index 0000000..7fb0a7b --- /dev/null +++ b/skills/ads-creative-development/SKILL.md @@ -0,0 +1,231 @@ +--- +name: ads-creative-development +description: "How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting." +category: marketing +catalog_summary: "Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter" +display_order: 2 +--- + +# Ads Creative Development + +A senior creative strategist's playbook for producing ad creative that performs. + +Performance creative is a different discipline from brand creative. Brand work optimizes for memorability, emotional resonance, and distinctive identity. Performance creative optimizes for stopping the scroll, communicating value in three seconds, and producing a click. Both matter. Mixing them up costs money. Brand creative running as performance ads bleeds budget; performance creative running as brand ads erodes equity. + +This skill is the discipline that produces performance creative without diluting brand. It assumes you know your audience and offer (see `paid-media-strategy`). It assumes you have brand-voice guidance (see `brand-voice`). The hard part is the systematic production of variations that test cleanly and ship without manual approval bottlenecks, and that is what is here. + +When to use this skill: producing ad creative for paid campaigns, planning a creative testing cycle, diagnosing creative fatigue, or auditing why creative is not converting. + +--- + +## What this skill is for + +This skill spans creative production, hook patterns, testing methodology, and fatigue diagnosis. It does not cover paid media strategy (use `paid-media-strategy`), result interpretation (use `ads-performance-analytics` once it ships), or brand voice authoring (use `brand-voice`). Pair this skill with the relevant integrations microsite for platform-specific MCP details and example prompts. + +The audience is an ad creative producer, a growth marketer responsible for creative testing, or an agency producing creative at scale. The voice is tactical. There is no "consider every option." Performance creative has shape, and a senior practitioner can map a brief to a production-ready variation matrix in an afternoon. + +--- + +## Performance vs brand creative + +The two disciplines optimize for different metrics. Brand creative optimizes for memorability, distinctiveness, and emotional resonance over months. Performance creative optimizes for scroll-stop in 1 second, value comprehension by 5 seconds, and click by 15. + +The shared layer. Both should reflect brand voice. Both should look like they came from the same brand. The difference is structure, pacing, and where the creative effort concentrates. + +The failure mode. Most agency creative tries to do both and does neither well. The brand video that runs as a 60-second performance ad has a strong narrative arc and zero CTR. The performance ad that ignores brand voice converts but trains the audience to not recognize the brand. The fix is not to compromise; it is to produce both, in their respective formats, with shared voice and divergent structure. + +A worked example. A premium coffee brand running a 60-second YouTube awareness ad gets to build the world: cinematography, the founder's hands, slow-pour rituals, music that sets a mood. That same brand running a 15-second Meta Reels performance ad gets 1 second to stop the scroll (a visual pattern interrupt: the steam rising from a cup, fast cut, brand logo dropping in), 4 seconds to clarify the offer (the new flavor, the price, the deal), 8 seconds for social proof (three customer-style testimonials, fast cuts), and 2 seconds for CTA (shop now, end card with logo). Same voice. Different structure. Different pacing. Different creative effort distribution. + +--- + +## Hook patterns: the first 3 seconds + +The biggest lever in performance creative. If the hook fails, no amount of body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. The hook is the whole game until the body justifies why the user kept watching. + +Twelve hook patterns work consistently. Detail in [`references/hook-pattern-library.md`](references/hook-pattern-library.md). + +1. Problem-agitate-solve. Open with the problem the audience feels. Agitate by naming the consequence. Solve with the offer. Works when the audience recognizes the pain. +2. Direct callout to audience. "If you are a B2B founder running paid ads..." Triggers self-identification. Works when the audience is narrow and self-aware. +3. Contrarian claim. "Stop using lookalike audiences." Hooks attention by violating expectation. Works when the audience has heard the conventional wisdom too often. +4. Result-led. "How we cut CAC 40% in 30 days." Specific number, specific timeframe. Works when the result is real and documented. +5. Curiosity gap. "The mistake 80% of marketers make..." Promises a payoff after the gap. Works when the gap is real; clickbait without payoff trains the audience to scroll past. +6. Social proof at top. "Used by 10,000+ teams." Validation before pitch. Works when the proof is impressive enough to do the heavy lifting. +7. Visual pattern interrupt. A surprising visual that does not match the platform's usual feed flow. Works on TikTok and Reels where the pattern is fast and the interrupt is louder. +8. Question that hits intent. "Tired of paying $400 for project management software?" The question pre-qualifies the audience. Works when the question matches a real search query the audience has typed. +9. Number-led. "3 changes that doubled our ROAS." Lists trigger the brain's pattern-completion instinct. Works for educational content; less so for product ads. +10. Personal story open. "Last year I was burning $50K a month on Meta ads with no return..." First-person specificity is hard to skip. Works when the story is real and the conclusion is action-relevant. +11. Comparison. "X vs Y: which actually works." Pits two options against each other. Works when the audience is in evaluation mode. +12. Behind-the-scenes / process. "How we onboard a new client in 7 days..." Demystifies the work. Works when the process is the differentiator. + +For each pattern, the anti-pattern is the same: a hook that does not actually hook. Generic openings ("In today's world...", brand-logo cards, slow zooms over title cards) train the audience to scroll past. The first second is for the hook. The brand can wait. + +--- + +## Format selection + +Different formats fit different combinations of audience, platform, and offer. + +- Static image. Best for simple value props, retargeting, and quick test cycles. Lowest production cost. Limited room for narrative. +- Carousel. Best for multi-feature products, educational content, and B2B SaaS. Each card carries one idea; users swipe through at their own pace. Strong for considered purchases. +- Video (in-feed). Best for demonstration, story, and broad audiences. Higher production cost. Performance correlates strongly with hook quality. +- UGC-style video. Best for trust building, social proof, and lower production cost. Looks like an ordinary user filmed it. Especially strong on TikTok and Reels. +- Stories or Reels (vertical 9:16). Best for TikTok, Instagram, and Snap. Native to the platform's primary surface. Skipping anything not vertical here is leaving performance on the table. +- Spark Ads (boosted organic). Best for TikTok. Promotes an existing organic post as an ad. Retains organic engagement signals; consistently outperforms pure paid creative on TikTok. + +The decision rule. Match format to platform native style and to audience consumption pattern. Detail in [`references/format-decision-matrix.md`](references/format-decision-matrix.md). + +--- + +## Video pacing + +Video performance correlates more with pacing than with production value. A well-paced phone-shot video outperforms a poorly-paced agency-produced spot. Specific guidance for the 15-second performance video. + +\| Time window \| Job \| +\|---\|---\| +\| 0 to 1s \| Hook. Visual pattern interrupt plus audio hook. \| +\| 1 to 3s \| Clarify what this is. Brand and offer registered. \| +\| 3 to 7s \| Value proposition. The problem-solution moment. \| +\| 7 to 12s \| Social proof or demonstration. Show, do not just tell. \| +\| 12 to 15s \| CTA. End card with logo and call to action. \| + +Anything past 15 seconds in a performance video is awareness territory. Performance creative should resolve by 15s. + +Platform variations. TikTok performs at 15 to 30 seconds; the platform tolerates longer because the audience is in a longer dwell mode. Meta In-Feed performs at 15s. YouTube Shorts at 15 to 60s. Long-form YouTube at 30s+ for awareness, with the value prop still front-loaded. + +--- + +## Variation systems + +The systematic way to produce 20 to 50 ad variations from one core concept without manual creative authoring per variation. + +The decomposition. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. + +- 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. +- Most are not worth shipping. The matrix narrows to 20 to 40 variations the team will actually run. +- Asset library structure: organize by concept, not by date. `concepts/launch-2026/hooks/`, `concepts/launch-2026/bodies/`, etc. + +Naming convention. Use a structured naming system so the analyst can join performance data back to creative components. Example: `launch2026_meta-reel_hookA_bodyB_ctaC_v1`. The analyst pulls the report, joins on the naming components, and identifies which hook is winning across body and CTA combinations. + +Worked example in [`references/creative-variation-templates.md`](references/creative-variation-templates.md). A half-day production session produces 40 variations from one core concept by using the matrix. Without the matrix, the same 40 variations require five days of authoring overhead. + +--- + +## Sequential testing methodology + +The waterfall. Most teams test everything at once and lose the signal. Sequential testing isolates the variable that matters at each step. + +1. Test hooks first. 5 to 10 hook variants, same body, same CTA, same format. The hook is the biggest lever; isolate it first. +2. Winners advance to body testing. Top 2 to 3 hooks each get 5 to 10 body variants. Now you are testing what the audience watches after the hook lands. +3. Winners advance to CTA testing. Top hook plus body combinations each get 3 to 5 CTAs. Smaller search space at this stage; the differences are usually marginal. +4. Winners advance to format testing. Top combinations each render in 2 to 3 formats (vertical video, carousel, static). Catches format-specific drop-offs. +5. Top combos go into evergreen rotation. Two to four winners run on rotation. Refresh on the cadence below. + +The common mistake. Testing all variables at once. Variance compounds; the team cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential is slower but produces real learnings the team can apply to the next campaign. + +Detail in [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md). + +--- + +## Creative fatigue detection + +Fatigue is real. The same audience seeing the same creative six times a week tunes it out, or worse, develops negative associations. Five signals indicate fatigue. + +1. Frequency above 4 to 5 per user per week. Set explicit caps. Defaults are usually too high. +2. CTR declining 30%+ week over week. The creative is no longer fresh to the audience. +3. CPM increasing without audience saturation explanation. The platform is having to bid harder to deliver impressions because engagement signals are weakening. +4. Negative comments increasing. A direct user signal that the audience is irritated. +5. Hide ratio increasing. Meta exposes this as "negative feedback rate." TikTok exposes "not interested" rate. + +Refresh cadence. Weekly for high-spend campaigns ($50K+/month). Biweekly for medium spend. Monthly for low spend. The economics: producing a fresh variant is cheaper than running tired creative for one extra week. + +The decision tree. If a top performer's metrics are still strong but frequency is climbing, ship variants of the same concept (same hook structure, different copy and visuals). If the metrics are dropping, retire the concept and ship a new one. Detail in [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md). + +--- + +## Brand-voice alignment without conversion dilution + +The tension. Brand voice can feel off-brand when squeezed into 15-second ads. The fix is hierarchy, not compromise. + +Voice attributes that survive compression. Tone (playful, serious, expert, irreverent). Cadence (short sentences vs long-form). Vocabulary (industry-specific or accessible). Visual treatment (color, type, motion language). These survive in 15s because they live in the texture of every frame. + +Voice attributes that do not survive compression. Deep narrative arcs. Complex metaphors. Layered humor that requires setup. Long-form storytelling. These need 30s+ of runtime to land. Forcing them into 15s produces diluted versions that read as off-brand. + +The hierarchy. Brand voice in every frame; performance discipline in the structure. The brand voice shows up in tone, cadence, vocabulary, and visual treatment. The performance discipline shows up in pacing, hook strength, and CTA placement. + +A worked example. A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs three creatives. The 60-second YouTube awareness piece has the founder talking to camera, plain language, contrarian framing of the category. The 15-second Meta performance ad has fast cuts, plain language captions on screen, contrarian hook ("Stop overpaying for project management software"), specific value prop, CTA. The static carousel has 6 cards, plain language, contrarian opening card, value prop progression, CTA on the last card. Same voice. Different structure. None feels off-brand to a customer who has seen all three. + +Detail in [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md). + +--- + +## Platform-specific creative norms + +Each platform has native norms. Violating them tanks performance. The fix is producing platform-native, not repurposing. + +Meta (Facebook plus Instagram). In-feed visual hierarchy. Captions on by default (most users watch sound-off). Native-feeling production beats studio production for direct response. Vertical 9:16 for Reels and Stories; 1:1 or 4:5 for in-feed. CTAs above the fold or in first 2 lines of caption. + +TikTok. Vertical 9:16 only. Native-creator aesthetic; phone-shot is the default. Fast cuts every 1 to 2 seconds. Captions for accessibility. Music-driven; trending sounds compound reach but expire fast. Spark Ads (boost an existing organic post) consistently outperform pure paid because they retain organic engagement signal. + +LinkedIn. Professional tone. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. B2B vocabulary is fine; consumer-style copy reads as off-platform. Thought leadership angle works; product pitches feel salesy. + +Google Search. Text-only headlines plus descriptions. Character limits are real constraints (30-character headlines, 90-character descriptions). RSA (Responsive Search Ads) optimization rewards 15+ headline variations and 4+ descriptions; the platform mixes them. + +Google Display and YouTube. Depends on placement. YouTube allows longer narrative (15s to 6m); Display is fast banner-style. Skippable YouTube ads need to earn the next second of attention; non-skippable annoys. + +Detail in [`references/platform-creative-norms.md`](references/platform-creative-norms.md). + +--- + +## Common failures + +Eight patterns recur across creative production work. The short version. + +- "We made a beautiful brand video and ran it as performance." Wrong format and length for the channel. Brand video belongs in awareness; performance ads need the 15-second structure. +- "All our ads use the same hook." Saturation. Ship five to ten hook variants per concept and rotate. +- "Our ads stopped working after 3 days." Fatigue plus narrow audience. Either ship more variants or expand the audience; usually both. +- "We A/B tested 50 ad variations." Too many simultaneous variables. Run sequential tests instead. +- "Creative passes brand approval but underperforms." Brand discipline at the cost of performance discipline. The hierarchy is wrong; voice in every frame, performance in the structure. +- "TikTok ad uses Meta-style production." Platform norm violation. TikTok rejects polished ad creative; phone-shot native wins. +- "Our hooks all start with the brand logo." Kills the first-3-second hook. Brand logo belongs at second 1 to 3 (after the hook lands), not at second 0. +- "We never refresh creative because the old set still works ok." Incremental loss compounds. CTR decay is gradual; the team that does not refresh discovers a 40% performance gap when they finally check. + +--- + +## The framework: 10 considerations for sustainable creative production + +When designing or auditing ad creative, walk these 10 considerations. + +1. Performance vs brand. Name what this creative is optimizing for; do not mix. +2. Hook strength. First 3 seconds. Scroll-stopping. Specific. +3. Format-platform fit. Native to the channel. +4. Pacing. Value prop hits within 5 seconds; CTA by 15s. +5. Variation system. Matrix-based, not ad-hoc. +6. Sequential testing. Hooks, then bodies, then CTAs, then formats. +7. Fatigue monitoring. Frequency, CTR decay, CPM trend, negative feedback. +8. Brand-voice alignment. Voice that survives compression; performance in the structure. +9. Platform creative norms. Vertical for short-video platforms, captions on, native production. +10. Refresh cadence. Weekly to monthly by spend tier. + +The output of the framework is a production plan. A list of variations to ship in the next testing cycle, the testing waterfall to run, the fatigue thresholds that trigger refresh, and the platform-specific norms the variations respect. Three answers from the framework: ship as planned, revise the plan, or stop because a precondition is missing. + +--- + +## Reference files + +- [`references/hook-pattern-library.md`](references/hook-pattern-library.md) - Twelve hook patterns with worked examples and anti-patterns for each. +- [`references/format-decision-matrix.md`](references/format-decision-matrix.md) - Audience-objective context to recommended format with reasoning and common alternatives. +- [`references/creative-variation-templates.md`](references/creative-variation-templates.md) - Matrix-based production system, naming conventions, asset library structure, half-day worked example. +- [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md) - Sequential testing waterfall with per-stage variant counts, durations, and winner-advancement criteria. +- [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md) - Five fatigue signals with thresholds and refresh decision tree. +- [`references/platform-creative-norms.md`](references/platform-creative-norms.md) - Per-platform aspect ratios, lengths, audio expectations, caption norms, and native-aesthetic anti-patterns. +- [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md) - Voice attributes that survive 15-second compression vs those that do not, with a four-format worked example. + +--- + +## Closing: the hook is the whole game + +In performance creative, the hook is the whole game. If the hook fails, no body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. + +Spend the disproportionate creative effort on the first 3 seconds. The rest is delivery. The team that puts 60% of its creative effort into the hook and 40% into everything else outperforms the team that distributes effort evenly. The team that puts 90% of its effort into hooks and 10% into delivery beats both, as long as it ships enough variations for the testing waterfall to find which hooks actually work. + +When in doubt, ship the variant. A weak variant ships; a perfect variant never does. The sequential testing waterfall finds the winners; the variation system makes shipping cheap. The asymmetric cost of inaction is real; the asymmetric cost of shipping a marginal variant is small. diff --git a/skills/ads-creative-development/references/brand-voice-performance-balance.md b/skills/ads-creative-development/references/brand-voice-performance-balance.md new file mode 100644 index 0000000..2be0aa0 --- /dev/null +++ b/skills/ads-creative-development/references/brand-voice-performance-balance.md @@ -0,0 +1,101 @@ +# Brand voice plus performance balance + +How to keep brand voice intact at 15-second performance scale without diluting conversion. + +The tension. Brand voice often feels off-brand when squeezed into a 15-second ad. The instinct is to compromise: water down the voice for the format, or sacrifice the format for the voice. Both are wrong. The fix is hierarchy. + +--- + +## Voice attributes that survive compression + +Four attributes carry the brand voice in 15 seconds without consuming runtime. + +Tone. Playful, serious, expert, irreverent, warm, blunt. Tone lives in the texture of every frame; it does not need narrative space to land. A blunt brand can write blunt captions in 15 seconds. A warm brand can shoot warm faces. + +Cadence. Short sentences vs long-form. Short and punchy fits the 15-second frame; long sentences need 30+ seconds to land. The brand whose voice is short and punchy is naturally well-fit for performance creative. + +Vocabulary. Industry-specific or accessible. Plain or formal. The brand voice that uses certain words and not others can preserve that vocabulary in any format. + +Visual treatment. Color, type, motion language, photographic style. Visual identity survives in 1 second; it survives in 15. + +--- + +## Voice attributes that do not survive compression + +Three attributes need runtime to land. Forcing them into 15-second performance creates diluted versions that read as off-brand. + +Deep narrative arcs. Hero's journey, character development, story-with-resolution. These need 30 to 60 seconds minimum. A 15-second compression of a narrative is the trailer, not the story. + +Complex metaphors. A brand whose voice relies on extended metaphors needs runtime to set up the metaphor and pay it off. 15 seconds of metaphor is the setup with no payoff; the audience leaves confused. + +Layered humor that requires setup. Jokes that depend on a long setup work in long-form. In 15 seconds the joke is too rushed to land. Punchline-style humor works; setup-dependent humor does not. + +The implication. A brand whose voice is built on narrative depth or complex metaphor will struggle with performance creative. The fix is not to compromise the voice; the fix is to use the appropriate format for the voice. Long-form awareness ads carry the narrative; performance creative carries the tone, cadence, vocabulary, and visual treatment without trying to land the full narrative in 15 seconds. + +--- + +## The hierarchy + +Brand voice in every frame. Performance discipline in the structure. + +Voice in every frame. The tone, cadence, vocabulary, and visual treatment of every clip, caption, and CTA reflects the brand. The audience watching three different ad variations should recognize the same brand across all of them. + +Performance in the structure. The pacing, hook strength, value-prop placement, and CTA placement follow performance norms. Hook in 1 to 3 seconds. Value prop by 5 seconds. Social proof or demo by 7 to 12. CTA by 15. The structure is platform-driven, not voice-driven. + +The two layers do not compete. Voice operates at the texture level; structure operates at the timing level. A blunt brand can be blunt in 1 second (texture) and structured in performance pacing (timing). + +--- + +## Worked example: same voice, four formats + +A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs four creatives. + +### 60-second YouTube awareness piece + +The founder talks to camera. Plain language. Contrarian framing of the category. The opening question hooks; the middle 40 seconds tell the story of why the brand exists; the closing 10 seconds invite the audience to learn more. + +Voice carries because there is runtime. Structure is narrative-led. + +### 15-second Meta Reels performance ad + +Fast cuts. Plain language captions on screen. Contrarian hook in second 1 ("Stop overpaying for project management software"). Specific value prop in seconds 4 to 7 ("$10 per user per month, all features"). Social proof in seconds 8 to 12 ("Used by 10,000+ teams"). CTA in seconds 13 to 15 ("Start your free trial"). + +Voice carries through tone (direct, plain) and visual treatment (consistent typography). Structure is performance-led. + +### 15-second TikTok Spark Ad + +Phone-shot. Creator-style. Plain language captions. Contrarian opening line spoken to camera ("Most project management tools cost too much"). Demonstration in seconds 4 to 9 (creator showing the product on their laptop). CTA in seconds 12 to 15. + +Voice carries through tone and the conversational cadence. Production aesthetic is platform-native (phone-shot, not studio). + +### Static carousel (6 cards) + +Card 1: Contrarian opening ("Most PM tools cost too much"). Card 2: The number ($10/user). Card 3: The features. Card 4: The customer logos. Card 5: The story (one customer who switched). Card 6: CTA. + +Voice carries through plain-language copy and consistent visual treatment. Structure is card-by-card progression, not narrative. + +The check. A customer who has seen all four pieces should recognize them as the same brand. The voice is consistent. The structure is format-appropriate. None of the four feels off-brand. + +--- + +## When voice and performance genuinely conflict + +Two situations where the conflict is real, not solvable. + +The brand voice is built on narrative depth. Some brands (especially heritage brands, premium brands, brands with founders who write long-form) have voices that genuinely require runtime. Performance creative for these brands often works better as static or carousel (where the depth lives in the copy) than as 15-second video (where the runtime is too short for the voice). + +The performance objective requires a tone the brand does not use. Direct response often pushes toward urgency, scarcity, and aggressive CTAs. A brand whose voice is calm and considered will read as off-brand if the performance ad uses high-urgency CTAs. The fix is to push back on the performance team's CTA defaults; calm-and-considered brands can have calm-and-considered CTAs that still convert when the offer is right. + +The default. Resolve the conflict by adjusting the format choice (use static or carousel for narrative-deep brands; use longer awareness pieces alongside performance) or by adjusting the CTA register (calm CTAs for calm brands). Do not compromise the voice; the voice is the long-term asset. Do not compromise the performance; the performance is the short-term revenue. Find the format and register that keeps both intact. + +--- + +## Common mistakes + +Watering down the voice for the format. A brand whose voice is sharp produces a soft 15-second ad to "fit the format." The audience does not recognize the brand; the ad converts marginally; the brand erodes. + +Sacrificing the format for the voice. A brand whose voice is narrative-deep produces a 60-second performance ad with no hook. The audience scrolls past in 1 second; the voice never lands. + +Treating voice and structure as the same axis. Voice is texture; structure is timing. They do not compete unless the voice depends on structure (narrative-led brands), in which case the format choice is the lever, not the voice itself. + +No brand-voice review on performance creative. The performance team produces ads that convert but read as off-brand. A 5-minute brand-voice review on every variation catches the off-brand drift before it ships. diff --git a/skills/ads-creative-development/references/creative-variation-templates.md b/skills/ads-creative-development/references/creative-variation-templates.md new file mode 100644 index 0000000..01f6754 --- /dev/null +++ b/skills/ads-creative-development/references/creative-variation-templates.md @@ -0,0 +1,123 @@ +# Creative variation templates + +The matrix-based production system. How to produce 20 to 50 ad variations from one core concept in a half-day session. + +The principle. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. The matrix lets you ship dozens of variations from minimal authoring overhead, which is what the sequential testing waterfall requires. + +--- + +## The decomposition + +A single creative is composed of independent components. + +\| Component \| Example \| Authoring cost \| +\|---\|---\|---\| +\| Concept \| Theme or message ("the project management tax") \| High (the strategy work) \| +\| Hook \| First 3 seconds, scroll-stop \| Medium (per variant) \| +\| Body \| The middle 5 to 10 seconds \| Medium \| +\| CTA \| The closing call to action \| Low \| +\| Format \| Vertical video, carousel, static, etc. \| Medium (rendering) \| + +The math. 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. Most are not worth shipping; the matrix typically narrows to 20 to 40 the team will actually run. The point is that authoring 5 hooks plus 4 bodies plus 3 CTAs equals 12 components total, which compose into 60 hook-body-CTA combinations. + +--- + +## Variation matrix template + +A simple spreadsheet that drives the production session. + +\| Concept \| Hook ID \| Body ID \| CTA ID \| Format \| Variant ID \| Status \| +\|---\|---\|---\|---\|---\|---\|---\| +\| launch2026 \| hook_a \| body_a \| cta_a \| meta-reel \| v001 \| drafted \| +\| launch2026 \| hook_b \| body_a \| cta_a \| meta-reel \| v002 \| drafted \| +\| launch2026 \| hook_c \| body_a \| cta_a \| meta-reel \| v003 \| drafted \| +\| launch2026 \| hook_a \| body_b \| cta_a \| meta-reel \| v004 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_b \| meta-reel \| v005 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_a \| tiktok-vertical \| v006 \| drafted \| +\| launch2026 \| hook_a \| body_a \| cta_a \| static-1x1 \| v007 \| drafted \| + +The status column tracks the production pipeline: drafted, rendered, approved, shipped, paused, retired. + +--- + +## Naming conventions + +Every variation has a structured name so the analyst can join performance data back to creative components. + +``` +{concept}_{platform-format}_{hook}_{body}_{cta}_v{n} +``` + +Examples: + +``` +launch2026_meta-reel_hookA_bodyB_ctaC_v1 +launch2026_tiktok-vertical_hookE_bodyA_ctaA_v3 +launch2026_static-1x1_hookA_bodyA_ctaB_v2 +``` + +The analyst pulls the report, splits the names on the underscore, joins to a master variant table, and reports performance by component. "Hook E is winning across body and CTA combinations on TikTok" becomes a query, not a manual review. + +--- + +## Asset library structure + +Organize files by concept, not by date. + +``` +concepts/ + launch2026/ + hooks/ + hookA-direct-callout.txt + hookB-contrarian-claim.txt + hookC-result-led.txt + hookD-curiosity-gap.txt + hookE-personal-story.txt + bodies/ + bodyA-feature-list.txt + bodyB-customer-story.txt + bodyC-comparison.txt + bodyD-process-walkthrough.txt + ctas/ + ctaA-shop-now.txt + ctaB-start-trial.txt + ctaC-book-demo.txt + visuals/ + hero-product-shot.png + ugc-customer-1.mp4 + founder-camera.mp4 + rendered/ + meta-reel/ + tiktok-vertical/ + static-1x1/ +``` + +Date-based organization rots fast. Concept-based organization composes; the team that runs three concepts a quarter has three folders, each with a clean inventory of components. Six months in, the library is searchable. + +--- + +## Half-day production session worked example + +The goal. Produce 40 variations of one core concept in 4 hours. The team: one creative strategist, one editor, one copywriter. + +Hour 1: matrix planning. Strategist drafts 5 hooks, 4 bodies, 3 CTAs against the concept brief. Copywriter refines language. Output: 12 component scripts. + +Hour 2: visual asset prep. Editor pulls the visual library (hero product shot, two UGC videos, two founder-to-camera takes). Copywriter writes captions per platform. Output: visual atoms ready to compose. + +Hour 3: rendering. Editor renders the matrix using a video editor's template feature (or a tool like Pencil, Vidico Forge, or in-house automation). The hook component swaps in; the body component swaps in; the CTA component swaps in; the format renders per platform. Output: 30 rendered variations. + +Hour 4: review and final renders. Team reviews the 30 outputs, kills the 5 to 10 that fail the smell test, renders the final 10 that need higher-quality cuts. Output: 20 to 25 production-ready variations. + +The math. 12 component scripts plus a half day of editor time produces 20 to 25 variations. Without the matrix, the same 20 to 25 variations require 5 days of independent authoring per variation. + +--- + +## When the matrix breaks down + +Two situations where the matrix is the wrong shape. + +Concept-driven brand work. Awareness creative often does not decompose cleanly. The 60-second YouTube spot is one creative, not a matrix. The hook, body, and CTA are integrated into the narrative. For brand work, drop the matrix and produce one strong piece. + +Highly format-specific creative. A behind-the-scenes TikTok is not a hook plus body plus CTA; it is a single creator's continuous take. Forcing the matrix produces stilted ads that read as agency-produced. For format-native creative, accept that one format produces one creative; do not try to render the same content into static. + +The rule. Use the matrix for performance creative where direct response is the goal. Drop the matrix for awareness, brand, or format-native creative where the integrity of the piece matters more than ship volume. diff --git a/skills/ads-creative-development/references/fatigue-detection-checklist.md b/skills/ads-creative-development/references/fatigue-detection-checklist.md new file mode 100644 index 0000000..c4b52d5 --- /dev/null +++ b/skills/ads-creative-development/references/fatigue-detection-checklist.md @@ -0,0 +1,110 @@ +# Fatigue detection checklist + +Five signals that creative is fatiguing, with thresholds and a refresh decision tree. + +The principle. Creative fatigue is a real economic cost. The tired ad still spends; it just does not convert. The team that monitors fatigue catches the decay early; the team that does not discovers a 30 to 50% performance gap when they finally check. + +--- + +## The five signals + +### 1. Frequency above 4 to 5 per user per week + +Threshold. Above 4 per user per week for performance ads. Above 5 for awareness ads. + +Why it matters. The same audience sees the same creative too many times. CTR drops, irritation rises, brand association erodes. + +Where to check. Meta Ads Manager: frequency report at the ad-set level. Google Ads: frequency at the campaign level. TikTok: less granular, but available at the ad group level. + +Action. If frequency is climbing past 4, ship variants of the same concept (different copy and visuals, same hook structure). If multiple concepts are all climbing, the audience is too narrow; expand. + +### 2. CTR declining 30%+ week over week + +Threshold. A 30% drop week over week is the alarm. A 10 to 15% drop is normal noise; 30% is a signal. + +Why it matters. The audience is no longer interested in the creative. Continuing to run it spends without producing the click. + +Where to check. Each platform's reporting at the ad level over a 4-week window. Look at the trendline, not just the latest week. + +Action. Refresh the creative within 7 days. If multiple ads in the same audience are dropping simultaneously, the audience is fatigued; rotate audiences as well as creative. + +### 3. CPM increasing without audience saturation explanation + +Threshold. A 25%+ increase over 14 days, with audience size and competition both stable. + +Why it matters. The platform's algorithm is having to bid harder to deliver impressions because engagement signals are weakening. The audience is still there but the platform sees the creative as less relevant. + +Where to check. Each platform's CPM trend. Cross-reference with audience overlap reports and competitor activity (Meta Ads Library, SimilarWeb, etc.). + +Action. Refresh creative. The CPM will recover within 7 to 14 days of fresh creative landing. + +### 4. Negative comments increasing + +Threshold. Comments containing "spam," "stop showing me this," "annoying," or platform-specific negative reactions exceeding 1% of impressions. + +Why it matters. Direct user signal of irritation. The audience is mad; the brand is paying for that anger. + +Where to check. Meta Ads Manager: comments section per ad. TikTok: comments per ad. Less visible on LinkedIn. + +Action. Pull the creative within 24 hours. Negative comments compound; the audience that complains often is the audience that complains to friends. + +### 5. Hide ratio (negative feedback) increasing + +Threshold. Meta exposes "negative feedback rate"; trigger refresh when it exceeds 1.5% of impressions or rises 50% week over week. + +Why it matters. Hide is a stronger signal than scroll-past. The audience is actively rejecting the ad. Platform algorithms penalize creatives with high hide ratios by reducing reach. + +Where to check. Meta Ads Manager: customize columns to expose negative feedback. Other platforms: less direct equivalents (TikTok "not interested" rate is similar). + +Action. Pull the creative immediately. The cost is real: the platform will deliver less of all your ads to that audience as it learns to weight negative signals. + +--- + +## Refresh cadence by spend tier + +\| Monthly spend \| Refresh cadence \| Variants per refresh \| +\|---\|---\|---\| +\| Under $5K \| Monthly \| 2 to 3 \| +\| $5K to $25K \| Biweekly \| 3 to 5 \| +\| $25K to $100K \| Weekly \| 5 to 10 \| +\| Above $100K \| Twice weekly \| 10+ \| + +The economics. Producing a fresh variant costs less than running tired creative for one extra week. At $100K per month, even one day of underperformance is meaningful. Higher spend justifies higher refresh investment. + +--- + +## Refresh decision tree + +When fatigue signals trigger, three options. Pick based on the diagnosis. + +Option 1: variant of working concept. The hook structure is still working but the specific creative is fatigued. Ship 3 to 5 variants of the same concept (different copy, different visuals, same hook structure). + +When. CTR drop with frequency above threshold, but the concept itself was strong (top performer in the testing waterfall). + +Cost. Half-day production session if the matrix is in place. Variants ship within 48 hours. + +Option 2: replace concept entirely. The concept is exhausted. Ship a fresh concept (different hook structure, different angle, different value prop emphasis). + +When. Multiple variants of the same concept are dropping simultaneously, or the concept has been in market for 6 to 12 weeks at high frequency. + +Cost. Full production cycle. Variants ship within 1 to 2 weeks. + +Option 3: full creative rotation. Multiple concepts are tired across the account. The audience is over-saturated. + +When. CPM rising across multiple campaigns, hide ratio climbing across the account, multiple concepts dropping in parallel. + +Cost. Quarterly creative refresh. Plan ahead; do not let the rotation be reactive. + +--- + +## Common mistakes + +Watching only CTR. CTR is a fatigue signal but not the only one. CPM and frequency lead CTR; the team watching only CTR is reactive when leading signals would have caught it 1 to 2 weeks earlier. + +Refreshing too late. Once CTR has dropped 50%, the audience has already developed negative associations. The next creative inherits that fatigue context. Refresh on leading signals (CPM, frequency). + +Refreshing without analysis. Producing fresh creative without understanding what worked about the previous creative. The team ships variants that miss what made the original successful and reverts to baseline performance. + +Ignoring the platform algorithm's cooldown. A new creative variant goes through a learning phase (3 to 7 days). Performance during the learning phase is not representative; do not kill a new variant in week 1. + +Treating all fatigue the same. Audience fatigue is different from creative fatigue. If multiple creatives are all fatigued, the audience is the problem. Rotate audiences, not just creative. diff --git a/skills/ads-creative-development/references/format-decision-matrix.md b/skills/ads-creative-development/references/format-decision-matrix.md new file mode 100644 index 0000000..12b3bf6 --- /dev/null +++ b/skills/ads-creative-development/references/format-decision-matrix.md @@ -0,0 +1,48 @@ +# Format decision matrix + +Audience-objective context to recommended format. Read top to bottom; pick the row that matches your situation. + +--- + +## The matrix + +\| Context \| Primary format \| Secondary format \| Reasoning and what to avoid \| +\|---\|---\|---\|---\| +\| B2C direct response, fast-scroll platforms (Meta, TikTok) \| Vertical video 9:16, 15s \| Static image (retargeting) \| Native to the feed, scroll-stop in 1s. Avoid horizontal video; it gets letterboxed and ignored. \| +\| B2B SaaS demo or feature explainer \| Carousel \| Vertical video with captions \| Carousel lets users self-pace; B2B audiences are in research mode. Avoid horizontal video for B2B feed placements. \| +\| DTC visual product \| UGC-style vertical video \| In-feed product carousel \| UGC retains organic feel and beats studio production for direct response. Avoid heavily produced product shots; reads as "ad" and gets skipped. \| +\| Trust-led offer (financial, healthcare) \| Static with social proof + carousel \| UGC video with named customers \| Trust requires repeat exposure to credible signals. Avoid moving cuts and music; reads as a pitch. \| +\| Founder-led B2B SaaS \| Founder-to-camera video, 15 to 30s \| Static quote card \| First-person specificity is high-trust. Avoid voiceover with stock footage; reads as agency-produced. \| +\| Education-led content marketing \| Long-form video (60s to 3m) \| Carousel \| Long-form rewards educational content. Use for awareness or top-funnel; not direct response. \| +\| App install \| Vertical video with screen recording \| Static screenshot grid \| Screen recording shows the product in 5 seconds, faster than narration. Avoid feature lists; show the product. \| +\| Local services \| Static image + lead form \| UGC-style customer quote \| Lead capture is the goal; minimize friction. Avoid long video; the audience is conversion-ready. \| +\| Enterprise B2B (>$50K ACV) \| LinkedIn Sponsored Content with carousel or static \| Long-form video for awareness \| Professional tone, slower pacing. Avoid TikTok-style fast cuts; reads as off-platform. \| +\| Retargeting (warm audience) \| Static image with offer \| Short carousel with social proof \| Audience already knows the brand; lead with the offer or social proof, not the brand intro. Avoid full hooks; the audience does not need them. \| +\| Black Friday or peak moment \| Static with discount + countdown \| Vertical video with offer + urgency \| Speed matters in peak; the audience is decision-ready. Avoid long-form storytelling. \| +\| Pre-launch awareness \| Long-form vertical video, 30 to 60s \| Carousel for waitlist \| The audience is curious, not converting. Reward attention with substance. Avoid short performance hooks; they undersell. \| + +--- + +## Decision rules + +Three rules apply across the matrix. + +Match the platform's native style. A 1:1 video on TikTok performs worse than the same video as 9:16 vertical. A horizontal video on LinkedIn performs better than the same vertical, because LinkedIn audiences watch on desktop more than TikTok audiences do. Rules differ; produce per platform. + +Match the audience's consumption mode. Scroll mode (TikTok, Reels) needs hook in 1 second. Research mode (LinkedIn, B2B blogs) tolerates longer pacing. Decision mode (retargeting, peak moments) wants the offer up front and skips the hook. + +Match the offer's complexity to the format's information density. Simple offers (a discount, a free trial) work in static. Complex offers (a multi-feature product, a service with a process) need carousel or video. Forcing a complex offer into static fails because the audience cannot understand what is being offered in 1 second. + +--- + +## Common mistakes + +One format across all platforms. A 16:9 video produced for YouTube does not work on TikTok or Reels. The team that ships one format and adapts crops produces underperforming creative on every platform except the one the format was designed for. + +Format chosen by what is easy to produce. Static is fastest to make; teams default to it even when video would convert 3x better. The cost of one good vertical video is recouped in one strong campaign; the production overhead is real but worth it for high-spend campaigns. + +Format chosen without testing. Most teams pick a format and stick with it. The matrix gives a starting point; the testing waterfall (see `testing-cadence-playbook.md`) gives the real answer for the specific brand and audience. + +Carousel without progression. A carousel is a multi-card story. Each card should advance the narrative or value prop. Six cards of the same image with different text waste the format. + +Vertical video without captions. Most users watch sound-off. A vertical video without captions communicates only its visual; the value prop disappears. Captions are not optional on Meta and TikTok. diff --git a/skills/ads-creative-development/references/hook-pattern-library.md b/skills/ads-creative-development/references/hook-pattern-library.md new file mode 100644 index 0000000..cf7d559 --- /dev/null +++ b/skills/ads-creative-development/references/hook-pattern-library.md @@ -0,0 +1,157 @@ +# Hook pattern library + +Twelve hook patterns that work consistently in performance creative. For each: what makes it work, when it fits, the anti-pattern, and one or two worked examples. + +A hook is the first 1 to 3 seconds of an ad. If the hook fails, the rest of the creative does not get watched. The hook carries 60% of the performance weight; the body and CTA carry 40%. Spend the creative effort accordingly. + +--- + +## 1. Problem-agitate-solve + +What makes it work. Names the audience's pain in their own language, then makes the consequence vivid, then offers the way out. The structure mirrors how the audience already thinks. + +When it fits. When the audience recognizes the pain and feels it as a real cost. Less effective when the pain is abstract. + +Anti-pattern. Skipping the agitate step. The audience hears the problem named and shrugs because the consequence is not vivid. + +Example. "Spending 4 hours a week on status updates? That is 200 hours a year. (Pause.) StatusBot writes them for you in 5 minutes." + +--- + +## 2. Direct callout to audience + +What makes it work. Triggers self-identification in the first second. The viewer thinks "that is me" and watches. + +When it fits. When the audience is narrow, self-aware, and proud of the identity. Founders, doctors, parents, runners, B2B SaaS PMs. + +Anti-pattern. Calling out an audience that is too broad. "If you are a person on the internet..." triggers nothing. + +Example. "If you are a B2B founder running paid ads with no in-house marketer, this is for you." + +--- + +## 3. Contrarian claim + +What makes it work. Violates expectation. The viewer's brain pauses on the contradiction. + +When it fits. When the audience has heard the conventional wisdom too many times and is exhausted by it. + +Anti-pattern. Contrarian for its own sake. The claim has to be defensible by the body of the ad; otherwise the audience disengages by second 5. + +Example. "Stop using lookalike audiences. Here is the audience strategy that actually scales." + +--- + +## 4. Result-led + +What makes it work. Specific number plus specific timeframe. The brain treats specificity as a credibility signal. + +When it fits. When the result is real and documented. Faked numbers train the audience to scroll past the entire account. + +Anti-pattern. Vague results. "We helped a client grow" produces no curiosity; "we cut their CAC 40% in 30 days" does. + +Example. "How we cut CAC 40% in 30 days for a Series B SaaS with no creative budget." + +--- + +## 5. Curiosity gap + +What makes it work. Promises a payoff after the gap. The viewer stays to find out. + +When it fits. When the gap is real and the payoff is on-topic. Clickbait without payoff trains the audience to scroll past. + +Anti-pattern. Gap without payoff. "The mistake 80% of marketers make..." with no actual mistake named in the body of the ad. Audience feels deceived. + +Example. "The mistake 80% of marketers make on Meta Ads is the one that costs them 30% of their budget every month." + +--- + +## 6. Social proof at top + +What makes it work. Validation before pitch. The audience trusts the offer because someone they trust trusts it. + +When it fits. When the proof is impressive enough to do the heavy lifting. Specific names beat generic numbers when the audience knows the names. + +Anti-pattern. Generic proof. "Trusted by thousands" is filler. "Used by Notion, Brex, and Figma" is signal. + +Example. "Used by 10,000+ teams including Notion, Brex, and Whatnot. Now available for solo founders too." + +--- + +## 7. Visual pattern interrupt + +What makes it work. A surprising visual that does not match the platform's usual feed flow. The eye snaps to it. + +When it fits. TikTok, Reels, Stories. Platforms with fast scroll and high pattern density. Less effective on slower platforms (LinkedIn). + +Anti-pattern. Overproduced visual interrupt that reads as ad. The interrupt has to feel native to the platform; a Hollywood-style pattern interrupt on TikTok reads as "ad" and gets skipped. + +Example. A creator-style cold open: a person on screen, looking confused at their phone, then turning the camera around to show the screen. Two-second hook before the first word. + +--- + +## 8. Question that hits intent + +What makes it work. The question pre-qualifies the audience. The audience that does not match disengages immediately, which is fine. + +When it fits. When the question matches a real search query the audience has typed. "Tired of paying $400 for project management software" works because that is what the audience googles. + +Anti-pattern. Generic questions. "Want to grow your business?" filters nothing. + +Example. "Tired of paying $400 a month for project management software you barely use?" + +--- + +## 9. Number-led + +What makes it work. Lists trigger the brain's pattern-completion instinct. The viewer wants to know all three (or five, or seven) reasons. + +When it fits. Educational content, list-style ads. Less effective for product ads where the offer should be specific. + +Anti-pattern. Too many items. "10 reasons" is too many for a 15-second ad; 3 to 5 is the sweet spot. + +Example. "3 changes that doubled our ROAS in Q4. Number 2 surprised our agency." + +--- + +## 10. Personal story open + +What makes it work. First-person specificity. The brain treats personal stories as data, not pitch. + +When it fits. When the story is real and the conclusion is action-relevant. Founder-led ads especially. + +Anti-pattern. Manufactured stories that read as fictional. The audience can usually tell. + +Example. "Last year I was burning $50K a month on Meta ads with no return. Here is what I changed in 30 days." + +--- + +## 11. Comparison + +What makes it work. Pits two options against each other. The audience in evaluation mode wants the comparison. + +When it fits. When the audience is actively comparing. "X vs Y" search queries are the tell. + +Anti-pattern. Unfair comparisons. The audience smells the spin and discounts the brand. + +Example. "Notion vs Linear: which actually works for engineering teams under 50." + +--- + +## 12. Behind-the-scenes / process + +What makes it work. Demystifies the work. The audience that wonders how something is done watches to find out. + +When it fits. When the process is the differentiator. Agencies, services businesses, niche craft. + +Anti-pattern. Process content that is actually a sales pitch in disguise. Audience disengages. + +Example. "How we onboard a new client in 7 days, end to end, with one PM and no kickoff meeting." + +--- + +## The pattern across all twelve + +Every working hook does the same thing: it makes the next second non-optional. The viewer cannot skip without losing something. Specificity, surprise, identification, curiosity, proof. Different mechanisms; same effect. + +The non-working hooks all do the same thing too: they let the viewer skip with no cost. Generic openings. Brand logo cards. Slow zooms over title text. "In today's world..." The first second is for the hook. The brand can wait. diff --git a/skills/ads-creative-development/references/platform-creative-norms.md b/skills/ads-creative-development/references/platform-creative-norms.md new file mode 100644 index 0000000..cfa0389 --- /dev/null +++ b/skills/ads-creative-development/references/platform-creative-norms.md @@ -0,0 +1,111 @@ +# Platform creative norms + +Per-platform creative requirements and unwritten conventions. Each platform has native norms; violating them tanks performance. + +--- + +## Meta (Facebook plus Instagram) + +Aspect ratios. 9:16 for Reels and Stories. 4:5 for in-feed (preferred over 1:1; uses more vertical real estate). 1:1 acceptable. Avoid 16:9 horizontal in feed. + +Length. 15 seconds is the sweet spot for performance. 6-second bumpers work for awareness. Long-form (60s+) only for storytelling formats; performance ads should resolve by 15s. + +Audio. Sound-off is the default. Captions are mandatory. Music is helpful when matched to the platform's audio context (low-fi background, not stock library bombast). + +Captions. On-screen captions for spoken audio. Bold, high-contrast, animated to track delivery. Avoid tiny captions; they are unreadable at scroll speed. + +Native aesthetic. Phone-shot or polished both work. UGC-style outperforms studio for direct response; studio outperforms for awareness. The brand voice and the offer drive which fits. + +Anti-patterns. Horizontal video in feed (gets letterboxed). No captions on spoken audio. Brand logo at second 0 (kills the hook). Slow zoom over title cards. Stock music bombast. Overproduced agency-style cuts that signal "ad" before the value lands. + +What feels native. Real people on camera. Direct address. Specific value props. Social proof named with brand names. Pacing that respects the user's scroll velocity (cuts every 1 to 2 seconds in the first 5 seconds). + +--- + +## TikTok + +Aspect ratios. 9:16 vertical only. Anything else is rejected by the algorithm. + +Length. 15 to 30 seconds for performance. The platform tolerates and rewards longer dwell than Meta. + +Audio. Sound-on is default. Trending sounds compound reach but expire fast. Original audio works. Captions for accessibility, not just for sound-off viewers. + +Native aesthetic. Phone-shot, creator-style. Studio production reads as "ad" and gets skipped. Pencil-and-paper aesthetic, jump cuts, unfiltered backgrounds, daylight. + +Spark Ads. Boost an existing organic post. Retains organic engagement signal. Outperforms pure paid creative; if the brand has organic content performing, this is the format. The Pipeboard and Synter MCPs cover Spark Ad creation; the integrations microsite covers the tactical setup. + +Anti-patterns. Polished agency video. Brand logo at second 0. Voiceover with stock footage. Slow-paced narrative. Music that signals "ad" (cinematic stock library). Anything that does not look like a creator filmed it. + +What feels native. Direct-to-camera creator. Fast cuts (1 to 2 seconds). On-screen captions following the speaker. Trending sounds when they fit. Backgrounds that look like a kitchen or bedroom, not a studio. + +--- + +## LinkedIn + +Aspect ratios. 1:1 or 16:9 for feed. 9:16 vertical works for Stories but Stories has limited reach on LinkedIn relative to other platforms. + +Length. 15 to 60 seconds. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. 30 seconds is a strong default. + +Audio. Sound-off default but sound-on more common than Meta. Captions still recommended. Music optional; many high-performing LinkedIn ads use no music. + +Voice. Professional. B2B vocabulary fine; consumer-style copy reads as off-platform. Thought leadership framing works; product pitches feel salesy. + +Native aesthetic. Founder-to-camera, expert-to-camera, slide-deck style, screen-recording demos. Studio production fine for LinkedIn; the audience is more tolerant of polished production than TikTok. + +Anti-patterns. TikTok-style fast cuts. Bombastic music. Casual or irreverent tone for serious B2B categories. UGC-style production for high-trust offers (financial services, healthcare). Generic "let us help your business grow" copy. + +What feels native. Specific industry vocabulary. Named customers and case studies. Slower pacing. Captions over slides. Founder-led specificity beats agency-style polish. + +--- + +## Google Search + +Format. Text-only headlines plus descriptions plus extensions. + +Character limits. Headlines 30 characters; 15 headline variants for RSA. Descriptions 90 characters; 4 description variants. Path 1 and Path 2 in the display URL: 15 characters each. + +RSA optimization. Provide 15+ headline variants and 4 description variants. The platform mixes them. More variants give the platform more material to optimize against. + +Voice. Direct. Specific. Action-led. The search query is high-intent; the ad's job is to confirm the user is in the right place. + +Anti-patterns. Keyword stuffing in headlines. Generic "we do X" headlines. Same value prop in every headline (the platform cannot test variation). Caps lock entire headlines (rejected). Unsubstantiated superlatives. + +What works. Specific value props per headline ("Free 14-day trial", "Used by 10,000+ teams", "Deploy in 5 minutes"). Question headlines that match search intent. Geographic specificity for local. Price points where they are the differentiator. + +--- + +## Google Display and YouTube + +### Display + +Format. Static or short animated banners across the Google Display Network. + +Anti-patterns. Unhelpful targeting (broad display drives garbage clicks). Vague creative (the audience is not in search mode; they need the value prop fast). + +What works. Retargeting with specific offers. Contextual placements (publisher list filtering). Cart-abandonment creative. + +### YouTube + +Format. Skippable video ads (TrueView), non-skippable, bumper (6s), in-feed video. + +Length. Skippable: 15s to 6m. Non-skippable: 15s. Bumper: 6s. + +Audio. Sound-on default. Captions still recommended for accessibility. + +Native aesthetic. YouTube allows longer narrative; the audience is in dwell mode. Both phone-shot and studio production work depending on context. + +Anti-patterns. Saving the value prop for the unskippable end. Skippable ads need to earn the next second; the value prop has to land in 5 seconds even on skippable. + +What works. First 5 seconds earn the rest. Specific value props. Demonstrations. Skippable with strong hooks routinely outperform non-skippable because the audience self-selects into watching. + +--- + +## Cross-platform principles + +Three rules apply across the matrix. + +Native production beats repurposing. A 16:9 video produced for one platform and cropped for others performs worse than three platform-native pieces. Produce per platform; do not adapt. + +Pacing matches the platform's scroll velocity. TikTok scroll is fast; cuts every 1 to 2 seconds. LinkedIn scroll is slow; longer takes work. Meta is in between. + +Captions everywhere. Sound-off is the default on most platforms most of the time. Spoken audio without captions is wasted audio. diff --git a/skills/ads-creative-development/references/testing-cadence-playbook.md b/skills/ads-creative-development/references/testing-cadence-playbook.md new file mode 100644 index 0000000..664b7ac --- /dev/null +++ b/skills/ads-creative-development/references/testing-cadence-playbook.md @@ -0,0 +1,121 @@ +# Testing cadence playbook + +The sequential testing waterfall. How to find the winning creative without testing 50 things at once. + +The principle. Variance compounds. Testing all variables at once means you cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential testing isolates the variable that matters at each step. + +--- + +## The waterfall + +Five stages. Each stage isolates one variable and advances the winners. + +### Stage 1: Hook test + +Goal. Find which hooks stop the scroll. + +Setup. 5 to 10 hook variants, same body, same CTA, same format. Each variant gets equal budget initially. + +Duration. 7 to 14 days, or until each variant has 50+ conversions or 1M+ impressions, whichever comes first. + +Winner criteria. Top 2 to 3 hooks by CTR (the metric that isolates hook performance) plus conversion rate above the floor. Eliminate hooks with high CTR but low conversion (the click is generated by the hook but the ad does not deliver). + +Output. 2 to 3 winning hooks advance to Stage 2. + +### Stage 2: Body test + +Goal. Find which body copy or middle-section visuals convert best given the winning hooks. + +Setup. Winning hooks times 5 to 10 body variants. Same CTA, same format. If two hooks advanced, that is 2 hooks times 5 bodies equals 10 ad sets. + +Duration. 7 to 14 days, or until each combination has 50+ conversions. + +Winner criteria. Top 2 to 3 hook plus body combinations by conversion rate. CTR is no longer the primary metric; the body is what holds attention after the hook. + +Output. 2 to 3 hook plus body combinations advance to Stage 3. + +### Stage 3: CTA test + +Goal. Find which CTA produces the strongest action given the winning hook plus body. + +Setup. Winning hook plus body combinations times 3 to 5 CTAs. Same format. Differences at this stage are usually marginal; do not over-engineer. + +Duration. 5 to 10 days, or until each combination has 30+ conversions. + +Winner criteria. Top hook plus body plus CTA combinations by conversion rate plus AOV (if value matters). + +Output. 2 to 4 winning combinations advance to Stage 4. + +### Stage 4: Format test + +Goal. Find which format works best for the winning combinations. + +Setup. Winning combinations rendered in 2 to 3 formats (vertical video, carousel, static). + +Duration. 7 to 14 days. + +Winner criteria. Top combinations by conversion rate within each format. Different formats may have different winners; that is fine. Run the winning format per surface. + +Output. 2 to 4 production-ready creatives ready for evergreen rotation. + +### Stage 5: Evergreen rotation + +Goal. Run winners at scale; refresh on cadence. + +Setup. 2 to 4 winners running in rotation. Frequency capping per audience. + +Duration. Ongoing. Refresh creative on the cadence in `fatigue-detection-checklist.md`. + +--- + +## Statistical thresholds + +Two ways to call winners. Pick one and standardize across the team. + +Statistical significance. Run until the winner has 95% confidence (or whatever threshold the team agrees on). Some platforms expose a "significance" indicator; others do not. + +Pre-commit duration plus minimum volume. Decide before launching: "we will run for 14 days, each variant gets at least 50 conversions, top performer wins." This is the simpler, more honest approach for most performance work. The platform's algorithm will not run a clean test under your nose anyway, so trying for high-confidence statistical significance is often overkill. + +The trap. Calling winners on small samples. A variant with 5 conversions and 10% lift over the other looks impressive but is within margin of platform noise. Wait for volume before declaring. + +--- + +## Common mistakes + +Testing too many variables at once. The most common mistake. Six hooks times five bodies times three CTAs times two formats equals 180 ad sets. The platform cannot optimize against that many variants; the team cannot interpret the results. Sequential is slower but produces real learnings. + +Killing variants too early. A variant in the learning phase has not yet converged. The platform's first 3 days of delivery are not representative. Wait at least 7 days before killing. + +Calling winners on CTR alone. A hook can drive high CTR with no conversion follow-through. The hook is doing its job (stopping the scroll) but the body is failing. Use conversion rate as the primary winner criterion; CTR is a hook-quality signal, not a creative-quality signal. + +No exclusion of recent converters from the test audience. Recent converters click ads at higher rates because they are warm; mixing them into the test audience produces false-positive results. Exclude. + +Ignoring fatigue during the test. A variant that wins the test in week 1 because it is new can underperform in week 4 once frequency builds. Test results are read against frequency; high-frequency winners are unreliable. + +--- + +## Per-stage budget guidance + +Rough percentages for the testing budget within a campaign's total spend. + +\| Stage \| Share of testing budget \| +\|---\|---\| +\| Hook test \| 40% \| +\| Body test \| 25% \| +\| CTA test \| 10% \| +\| Format test \| 15% \| +\| Buffer (re-tests, lift checks) \| 10% \| + +The hook test gets the biggest share because it filters the most variants. CTA and format tests are smaller because the differences are usually marginal. + +--- + +## When to break the waterfall + +Two situations. + +Time pressure. A peak moment (Black Friday, product launch) does not allow 6 weeks of sequential testing. Compress: run a hook test concurrently with format test using your best-guess body and CTA. Accept lower confidence in exchange for speed. + +Discovery of an outlier. A hook variant that is winning by 5x at the end of week 1 should not wait for the full 14-day stage. Promote early, but track the long-tail performance to confirm. + +The default is the waterfall. The exceptions are real but rare; do not let "we are on a tight timeline" become the default reason to skip the discipline. diff --git a/skills/ads-performance-analytics/SKILL.md b/skills/ads-performance-analytics/SKILL.md new file mode 100644 index 0000000..2bcadc2 --- /dev/null +++ b/skills/ads-performance-analytics/SKILL.md @@ -0,0 +1,275 @@ +--- +name: ads-performance-analytics +description: "How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue." +category: marketing +catalog_summary: "Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget" +display_order: 3 +--- + +# Ads Performance Analytics + +A data-team-mentor's playbook for interpreting paid media dashboards without fooling yourself. + +The dashboard is the moment of truth for paid media decisions. The numbers on it determine whether you scale, hold, or kill. They also expose every platform's self-attribution bias, every modeled-conversion shortcut, every cross-platform double-count. Most "scale this campaign" decisions trace back to misreading the dashboard. + +This skill is the discipline that prevents misreading. It assumes the campaign was strategically sound (see `paid-media-strategy`). It assumes the creative was tested properly (see `ads-creative-development`). The hard part is knowing what each number actually means, what it does not, and how to reconcile platform-reported metrics with the truth in your warehouse. + +When to use this skill: any time you are about to scale, kill, or rebudget a campaign based on platform metrics; reconciling platform reports with revenue data; evaluating an agency's reporting; or building a paid media dashboard that will not lie to you. + +--- + +## What this skill is for + +This skill spans paid media result interpretation. It does not cover paid media strategy (use `paid-media-strategy`), creative production (use `ads-creative-development`), or platform-specific tooling (covered in the integrations microsites). Pair this skill with the relevant integrations microsite for platform-specific MCP commands and example prompts. + +The audience is a marketer, growth analyst, agency analyst, or founder evaluating paid media reports. The voice is patient and clinical. There is no "trust the platform's number" or "ignore the platform entirely." Both are wrong. The discipline is knowing which numbers from which platform mean what, and what to reconcile against to make the actual decision. + +--- + +## The result panel: what every paid media platform should expose + +A trustworthy result panel exposes nine things. Anything missing is a signal to treat reported numbers with extra skepticism. + +1. Spend, impressions, clicks. Table-stakes metrics. Should match across platforms within rounding. +2. Conversions with definition and window visible. Not just a count; the definition of what counts as a conversion and the attribution window applied. Without this, the count is unreadable. +3. Attribution breakdown. Last-click vs view-through vs modeled. The mix of how the conversions were credited. +4. Frequency. Impressions per unique user. The fatigue early-warning system. +5. Audience saturation. Where the platform exposes it. A flat audience-saturation curve means there is room to scale; a steep curve means efficiency is dropping. +6. Time series. Daily breakdown to spot novelty effects, fatigue, day-of-week patterns, and exogenous variance. +7. Cost metrics in clear currency. CPC, CPM, CPA, ROAS with the math defined and the currency labeled. Do not assume USD. +8. Conversion path data. Touchpoints before conversion, where available. Tells you whether a campaign is a closer or an opener. +9. Filters, segments, and exports. Without these, the panel is a brochure, not a tool. + +Platforms hide what makes their reporting look weakest. Google PMax hides keyword-level and placement-level data. Meta hides the modeled-conversion share. LinkedIn hides cross-device click paths. Treat hidden metrics as the place to dig. + +--- + +## Platform-reported vs reality + +Every platform's dashboard is optimized to make the platform look effective. This is not a moral failing; it is a structural incentive. Platforms with rosier reporting attract more spend. + +Conversion windows. Meta defaults to 7-day click plus 1-day view. Google defaults to 30-day click plus 1-day view. Different windows, same activity, different reported numbers. If you compare Google's 30-day-click count against Meta's 7-day-click count, you are comparing different definitions and pretending they are the same. + +View-through attribution. Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Treat view-through as a signal of awareness contribution, not as a direct response measurement. The user might have converted from organic search anyway. + +Modeled conversions. When iOS users opt out of tracking, Meta and others statistically model what the conversion would have been. Modeled numbers are educated guesses, not measurements. They are useful for direction; they are not reliable for precision. + +Self-attribution bias. Every platform's pixel fires on conversion and the platform claims credit. If you ran Meta, Google, and TikTok in the same week, all three platforms report your conversions as theirs. Sum-of-platforms is always greater than 100% of actual conversions. + +The discipline. Never report platform-reported numbers as fact in board decks. Always reconcile against the single source of truth (warehouse, GA4, or unified analytics platform). Detail in [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md). + +--- + +## Attribution models in practice + +Six models and one anti-model. None is right. They are all approximations. The discipline is picking one, committing, and reading the others as sanity checks. + +Last-click. Simple, reproducible, undercredits awareness. The conversion is fully credited to the last click before the conversion event. Easy to compute; easy to compare across channels; bad for understanding upper-funnel contribution. + +First-click. Opposite bias. Fully credits the first touchpoint, undercredits closing channels. Useful as a sanity check against last-click; rarely the right primary view. + +Linear. Equal credit across all touchpoints. Gives every channel something. Defensible; not informative. Most useful for board reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. + +Time-decay. More credit to recent touchpoints. Reflects the intuition that recent ads are more influential. Hard to argue against; hard to verify. + +U-shaped (position-based). Heavy on first and last (40% each), light on middle (20% distributed). Honors both opener and closer roles. The default in many MTA tools. + +Data-driven attribution (DDA, Google). Machine-learning model that distributes credit based on observed conversion paths. Opaque; hard to audit. The closest to "right" for digital channels but a black box. + +Marketing mix modeling (MMM). Regression-based, top-down. Uses spend and revenue time series across channels to estimate channel contributions. Requires 2+ years of data. The strongest defense against platform self-attribution because it does not rely on platform-reported conversions at all. + +The anti-model: trusting platform-reported attribution. Each platform's "DDA" or "attributed conversions" is the platform's self-attribution. Sum across platforms exceeds reality. Use platform attribution for in-flight optimization within the platform; use a unified attribution model for cross-channel decisions. + +Practical guidance. + +- Early-stage. Use last-click plus a single guardrail metric (warehouse-attributed CAC). Sophisticated attribution requires data volume you do not have. +- Mid-stage. Data-driven attribution from Google plus GA4, with explicit awareness vs closing channel labeling. +- Mature. MMM as the canonical incremental reference. MTA for in-flight optimization. Last-click for channel-level decisions where ambiguity is acceptable. + +Detail and a decision matrix in [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md). + +--- + +## Multi-platform reconciliation + +The trap. Google says you spent $50K with 800 conversions. Meta says $30K with 600. LinkedIn says $20K with 200. Total reported equals 1,600 conversions. Your warehouse says 950. Where did 650 go? + +The answer. Nowhere. They never existed. Each platform claimed conversions other platforms also claimed. + +The reconciliation pattern. + +- Trust the warehouse for total conversions and total revenue. +- Trust platforms for relative ranking within platform (which campaign won, which audience won). +- Never trust platform sums. +- Compute blended CAC as (total ad spend across platforms) divided by (total new customers from warehouse). Not from platform reports. + +The board-deck pattern. Report warehouse-attributed conversion counts, never platform-summed. Report blended CAC, not channel-by-channel CAC unless explicitly noted as platform-self-attributed. Detail and templates in [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md). + +--- + +## ROAS vs LTV: the time horizon trap + +ROAS is short-term. Revenue from purchases attributed to a campaign in a fixed window, often 7 to 30 days. LTV is long-term. Total customer lifetime revenue. + +Decisions made on ROAS can be wrong if LTV varies by channel. A worked example. + +Meta drives 2.5x ROAS at $40 CAC with $80 LTV. The 7-day-click revenue covers 1.5x payback over the customer lifetime. + +Google drives 1.8x ROAS at $60 CAC with $200 LTV. The 7-day-click revenue covers 3.3x payback over the customer lifetime. + +Google looks worse on ROAS, better on LTV-adjusted return. Allocating budget to Meta because the ROAS is higher is the wrong move. + +The fix. Cohort-based LTV by acquisition channel, updated quarterly. Compare channels on payback period or LTV-CAC ratio, not raw ROAS. The 2x ROAS heuristic is a dangerous shortcut. Same ROAS at different LTVs equals different actual returns. + +The trap that compounds. Performance teams optimize for short-term ROAS because the metric refreshes weekly. Brand and high-LTV channels get cut because their short-term ROAS is lower. Six months later, the brand pipeline has eroded and short-term ROAS itself drops because the cheap channels are saturated. The metric that drove the decision was the wrong horizon. + +--- + +## Cohort analysis vs daily metrics + +Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. + +Three cohort cuts that matter for paid media. + +By acquisition month. Are users acquired in March retaining better than users acquired in January? A declining LTV over rolling acquisition cohorts means recent acquisition is lower quality; the daily metrics will show this two to three months later when the retention starts hurting. + +By acquisition channel. Are users from Meta retaining better than users from Google? Channel-level cohort divergence is the data behind the LTV-vs-ROAS argument. Meta might drive volume at lower LTV; Google might drive lower volume at higher LTV. The cohort tells the story the daily ROAS hides. + +By acquisition campaign. Campaign-level cohort signals. Useful for diagnosing why a campaign that "works" in week 1 produces no recurring revenue. + +The signal to act on. Declining cohort LTV over two consecutive months is the alarm. Pause the channel or campaign before the daily metrics force you to. Detail in [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md). + +--- + +## Statistical noise in performance metrics + +Most "the campaign improved 15% week over week" stories are noise. Real performance changes are 30% or more in metrics that vary 10 to 20% naturally. Below that threshold, you are looking at variance and calling it signal. + +Sources of noise in paid media metrics. + +- Day-of-week effects. B2C tends to weekend dips. B2B tends to weekend gains. A "Monday morning is better" hypothesis often dissolves when day-of-week is normalized. +- Holiday and seasonal effects. Q4 dwarfs most "optimization" effects. A campaign launched in Q4 looks great because of seasonality, not strategy. +- Weather, news, competitor activity. Real exogenous variance. Last week's news cycle can shift CPMs across an entire vertical. +- Pixel fire and reporting delay. Conversions reported on a 7-day click window arrive incrementally. Reading the panel on Monday for last week's performance undercounts. + +The fix. Pre-commit to test duration before drawing conclusions. Use the experimentation discipline from `experimentation-analytics` for any directional change you want to claim is real. The signal-to-noise problem in paid media metrics is the same as the signal-to-noise problem in product experiments; the framework transfers. + +This is where `experimentation-analytics` bridges in. The statistical patterns are the same; the application is different. Read both for the full picture. + +--- + +## Incrementality testing + +The honest test. If we had not run this ad, would we still have gotten the conversion? The number above zero is the incremental contribution. + +Most paid media is 30 to 70% incremental, not 100%. Some is zero. Branded search bidding is often 5 to 20% incremental (most converters would have found you organically). Retargeting is often 20 to 40% incremental (many of those users were going to convert anyway). Prospecting is often 50 to 90% incremental. + +Four methods. + +Geo holdout. Hold one region out from the campaign. Measure the difference in conversions between the holdout region and the matched test region. The cleanest causal test for paid media at scale. + +Ghost bidding (Google). Google's own incrementality tool. Bids on a holdout share of impressions but does not actually serve the ad. Reports incremental conversions. Honest signal; some teams find the math opaque. + +Conversion lift studies (Meta). Splits audiences into test and control. Test sees the ad; control does not. Reports incremental lift. The cleanest within-Meta test. + +PSA tests. Serve some users a public service announcement instead of your ad. Compare conversion rates. Useful for legacy brands with deep budget. + +Incremental rate ranges by channel type are in [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md). The discipline is to run incrementality tests at least quarterly on the highest-spend channels. Without them, you are optimizing against platform-reported attribution that systematically overcounts. + +--- + +## Geo experiments and holdouts + +For paid media specifically, geo-based testing is the most reliable causal method. + +Geo holdout. Turn off paid media in one region. Measure baseline organic conversions. The difference between expected and actual conversions in the holdout region is the incremental paid contribution. + +Geo lift. Scale spend in one region by 2x. See if conversions scale linearly. A linear scale means the channel has headroom. A sublinear scale means saturation; further spend is diminishing returns. + +Switchback. Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. Useful when geo splitting is not feasible. + +Pre-and-post analysis. Launch in a region; measure 30 days before vs 30 days after. Weak design because external factors confound the comparison. Use only when no other test is available. + +The right setup. Matched markets (similar demographics, similar baseline conversion rates). Statistical power calculation upfront (how big a difference can the test actually detect). Pre-committed analysis window (so you do not stop early when the data looks good or wait too long when it looks bad). + +The trap. Calling a geo test successful because of timing-correlated revenue lift. A campaign launched in October will see "lift" because Q4 is starting; without a control region, the lift is not attributable to the campaign. + +--- + +## Platform self-attribution bias + +A specific failure mode worth its own section. + +The mechanism. Platform's pixel fires on conversion. Platform claims credit. The user might have converted from any channel; the platform that loaded the pixel last gets the credit on the platform's own dashboard. + +Why platforms reward this design. More credit on the platform dashboard equals better-looking ROAS equals more advertiser spend. Platforms have no incentive to underreport their own contribution. + +Detection patterns. When platform-reported conversions exceed warehouse-attributed conversions for the same channel by more than 30%, you have heavy double-counting. When sum-of-platform-reports exceeds total conversions in the warehouse, you have cross-platform double-counting. + +The fix. Warehouse as canonical for board reporting. Platform reporting as in-flight signal only. Incrementality tests at least quarterly to keep the channel-attribution honest. + +A worked example. A retargeting campaign in Meta showed 3.5x ROAS for six months. The team scaled spend from $20K to $80K per month. A geo holdout test revealed that 65% of the "conversions" would have happened anyway from organic. Real ROAS adjusted for incrementality was 1.2x, not 3.5x. The campaign got cut and warehouse-attributed CAC dropped 18% in the next quarter. + +--- + +## Common interpretation failures + +Twelve patterns recur in paid media reporting work. Detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "ROAS dropped 20% week over week, kill the campaign." Could be noise. Pre-commit a test window before acting on weekly variance. +- "Meta says 500 conversions, my warehouse says 200, who is right?" Both are wrong; warehouse is closer to truth, Meta self-attributes. Reconcile, do not pick a winner. +- "We turned off Google PMax and conversions did not drop." PMax was harvesting branded search you would have gotten free. Audit branded queries inside PMax. +- "The new campaign hit 5x ROAS in week 1." Likely retargeting hot leads. Check the audience composition before declaring victory. +- "We A/B tested and one creative wins by 12%." Within margin of platform noise. Not significant. +- "Our LTV calculation says this channel is profitable." Check cohort age. Recent cohorts may not have hit LTV yet; the calculation is a projection, not a measurement. +- "The platform says high frequency is fine because conversions are still happening." Fatigue masked by free organic conversions. The campaign is taking credit for conversions that would have happened anyway. +- "Last-click attribution shows Meta at 60% credit." Last-click bias. First-click view of the same data shows different. Pick a model and stick. +- "We scaled spend 5x and conversions only doubled." Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher. +- "Brand campaigns underperform on direct ROAS." They do not have to. Brand impact shows up in other channels' efficiency. Measure brand against brand-search lift, not direct ROAS. +- "ROAS held steady but profit dropped." The mix shifted toward lower-margin products. Channel-level ROAS hides product-mix effects. +- "Agency reported a 4x ROAS month." Whose number? Platform-reported, warehouse-attributed, or model-adjusted? The unit of measurement matters more than the magnitude. + +--- + +## The framework: 12 considerations for trustworthy paid media interpretation + +When reading a paid media dashboard about to inform a decision, walk these 12 considerations. Skipping any of them is how teams ship the wrong call. + +1. Result panel completeness. What is the platform showing vs hiding. +2. Platform-reported vs reality. View-through, modeled conversions, conversion windows. +3. Attribution model. Pick one and read the others as sanity checks. +4. Multi-platform reconciliation. Sum-of-platforms is always inflated. +5. ROAS vs LTV horizon. Short-term metric, long-term impact. +6. Cohort vs daily. Cohort tells the quality story; daily tells the volume story. +7. Statistical noise. Weekly variance, day-of-week, seasonal, exogenous. +8. Incrementality. What would have happened without the spend. +9. Geo and holdout testing. The honest causal test. +10. Self-attribution bias. Platforms claim credit they do not deserve. +11. Decision rule. Pre-committed scale up, hold, or pull back. +12. Single source of truth. Warehouse over platform reporting for board metrics. + +The output of the framework is one of three answers. Scale (the campaign is incremental and unit economics work). Hold (data is ambiguous; gather more before deciding). Kill (the campaign is not incremental enough to justify the spend). + +--- + +## Reference files + +- [`references/metric-definitions-glossary.md`](references/metric-definitions-glossary.md) - CTR, CPC, CPM, CPA, ROAS, LTV, AOV, frequency, reach, impressions, conversion window, view-through, modeled conversion, blended CAC, MER. +- [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md) - Last-click, first-click, linear, time-decay, U-shaped, DDA, MMM. Decision matrix by business stage. +- [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md) - Google PMax black box, Meta iOS impact and Conversions API, LinkedIn 30-day click defaults, TikTok video-completion attribution, programmatic viewability gates. +- [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md) - Geo holdout, ghost bidding, conversion lift, PSA tests, switchback designs. Setup, duration, analysis pattern, expected incremental rates. +- [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md) - Warehouse as canonical, platform as in-flight signal, blended CAC formula, board-deck patterns, reconciliation cadence. +- [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md) - By acquisition month, channel, and campaign. Retention curves, when to act on cohort signals. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it incremental zero + +Most paid media spend is not 100% incremental. Some channels are 70% incremental. Some are 30%. Some are zero, paying for conversions you would have gotten anyway. + +The discipline of accepting that channels can be incremental zero, and pulling spend accordingly, is the single highest-impact skill in paid media analytics. Most accounts have at least one campaign that looks profitable in the platform but is incremental zero in the warehouse. Branded paid search at $4 CPC when the same users find you at position one organically. Retargeting at $0.30 CPC for users who already added items to cart. PMax cannibalizing free brand traffic. + +The discipline of finding those campaigns and killing them is the work. The platform will not tell you. The platform's incentive is the opposite. The warehouse, paired with quarterly incrementality tests, is the only honest source. + +When in doubt about whether a campaign is incremental, run a geo holdout. The two-week test is cheaper than a quarter of unincremental spend. The team that does not run incrementality tests is optimizing against numbers that are systematically wrong, and the size of the error is exactly the size of the budget waste. diff --git a/skills/ads-performance-analytics/references/attribution-model-comparison.md b/skills/ads-performance-analytics/references/attribution-model-comparison.md new file mode 100644 index 0000000..55d3e3f --- /dev/null +++ b/skills/ads-performance-analytics/references/attribution-model-comparison.md @@ -0,0 +1,128 @@ +# Attribution model comparison + +For each major attribution model: definition, fit, bias direction, and a worked example showing how the same activity gets different attribution. + +The principle. No model is right. They are all approximations. The discipline is to pick one as the primary view, read the others as sanity checks, and report against the warehouse rather than against any single platform's view. + +--- + +## The models + +### Last-click + +Definition. Full credit to the last clickable touchpoint before conversion. + +When it fits. Early-stage measurement where simplicity matters more than precision. Final-stage decisions where the closer matters more than the opener. + +When it does not fit. Awareness-channel evaluation. Brands with multi-touch sales cycles. Anything upper-funnel. + +Bias direction. Undercredits awareness channels (display, video, top-of-funnel social). Overcredits closing channels (branded search, retargeting). + +### First-click + +Definition. Full credit to the first touchpoint in the conversion path. + +When it fits. Awareness-channel evaluation. Comparing top-of-funnel sources. + +When it does not fit. Closing-channel evaluation. Performance optimization at the bid level. + +Bias direction. Mirror image of last-click. Undercredits closing; overcredits opening. + +### Linear + +Definition. Equal credit across every touchpoint in the conversion path. + +When it fits. Board-deck reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. Defensible-by-default. + +When it does not fit. Decisions where the marginal contribution of each channel matters. Linear treats first-click and last-click the same; reality usually does not. + +Bias direction. Diffuses credit. Channels that touched the path always get something; channels that drove the conversion do not get more. + +### Time-decay + +Definition. More credit to recent touchpoints. Older touchpoints get progressively less. + +When it fits. When the intuition is that recent ads are more influential. Reasonable for short-cycle B2C. + +When it does not fit. Long sales cycles where the first touchpoint may have been months before the close. Decay underweights the opener. + +Bias direction. Skews toward the closer. Slightly less aggressive than last-click. + +### U-shaped (position-based) + +Definition. 40% credit to first touch. 40% credit to last touch. 20% distributed across middle touches. + +When it fits. When you want to honor both opener and closer roles without flattening to linear. Reasonable default for most B2C. + +When it does not fit. Single-touch paths (awards 80% to a single touchpoint, which is over-attributing). Long paths where the middle touchpoints matter as much as the ends. + +Bias direction. Balances the last-click and first-click views into one number. + +### Data-driven attribution (DDA, Google) + +Definition. Machine-learning model that distributes credit based on observed conversion paths. Compares paths that did and did not convert; assigns credit to touchpoints that correlate with conversion. + +When it fits. Mature accounts with sufficient conversion volume (Google requires 600+ conversions per month for DDA). Cross-channel optimization. + +When it does not fit. Sub-scale accounts. Accounts that need explainability for regulators or boards. The black-box nature is hard to audit. + +Bias direction. Best in class for digital channels where the data is clean. Still suffers from platform self-attribution bias because Google's DDA only sees Google touchpoints. + +### Marketing mix modeling (MMM) + +Definition. Regression-based, top-down. Models the relationship between spend across channels and revenue over time. Typically requires 2 to 3 years of data. + +When it fits. Mature accounts with cross-channel spend at scale. Brands where offline channels (TV, OOH, podcast) contribute. Anywhere platform self-attribution bias is a real concern. + +When it does not fit. Early-stage accounts without enough historical data. Fast-changing channel mixes where the historical data does not represent current reality. + +Bias direction. The strongest defense against platform self-attribution because MMM does not rely on platform-reported conversions. Limitations are statistical: confidence intervals are wide; granularity is low (channel-level, not campaign-level). + +--- + +## The same path under each model + +A worked example. A B2C SaaS user converts after this path: + +1. Sees a YouTube awareness ad (impression, not click). +2. Clicks a Meta retargeting ad three days later. +3. Searches for the brand on Google. Clicks a paid branded search ad. +4. Returns directly the next day. Converts. + +Attribution by model. + +\| Model \| YouTube \| Meta \| Branded Search \| Direct \| +\|---\|---\|---\|---\|---\| +\| Last-click \| 0% \| 0% \| 0% (depending on direct vs paid) \| 100% \| +\| First-click \| 0% (impressions excluded) \| 100% \| 0% \| 0% \| +\| Linear \| 0% \| 33% \| 33% \| 33% \| +\| Time-decay \| 0% \| 15% \| 35% \| 50% \| +\| U-shaped \| 0% \| 40% \| 20% \| 40% \| +\| Google DDA \| (only sees Google touchpoints) \| (only sees Meta touchpoints if Conversions API integration) \| varies \| varies \| +\| MMM \| partial credit (spend in YouTube correlates with conversions) \| partial credit \| partial credit \| (organic, not modeled) \| + +The takeaway. Same path. Five different attribution stories. None is right. Each tells you something different. + +--- + +## Decision matrix by business stage + +\| Stage \| Primary model \| Secondary check \| Why \| +\|---\|---\|---\|---\| +\| Pre-PMF \| Last-click + warehouse-attributed CAC \| None; insufficient volume for sophisticated models \| Sophisticated attribution needs volume you do not have \| +\| Series A or early growth \| Last-click + GA4 data-driven \| First-click as sanity check on awareness \| Volume insufficient for MMM; DDA requires more conversions than most early-stage accounts have \| +\| Mid-stage (10K+ conversions per month) \| Google DDA + GA4 path data \| Last-click for channel decisions; first-click for awareness \| DDA gets reliable here; cross-validate with simple models \| +\| Mature (100K+ conversions per month, 2+ years data) \| MMM as canonical \| Last-click for in-flight; DDA for cross-channel \| MMM is the strongest defense against self-attribution at scale \| +\| Multi-channel including offline \| MMM mandatory \| DDA for digital \| MMM is the only model that captures offline contribution \| + +The progression. As volume grows and channel mix expands, the model that fits changes. Locking in last-click forever is fine if the business stays simple; the moment offline or upper-funnel channels matter, the model has to advance. + +--- + +## How to communicate which model produced which number + +Three rules for honest reporting. + +1. Always label the model. "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions on last-click attribution with a 7-day-click window" is honest. +2. Report the same number under at least two models when stakes are high. Board decks should show the conservative view (last-click) and the generous view (linear or DDA). The range tells stakeholders what they are not learning. +3. Reconcile against the warehouse before reporting in dollars. Dollar figures attached to platform-reported conversions inherit all the platform's attribution biases. Warehouse-attributed dollars are the only dollars that have been independently verified. diff --git a/skills/ads-performance-analytics/references/cohort-analysis-templates.md b/skills/ads-performance-analytics/references/cohort-analysis-templates.md new file mode 100644 index 0000000..dbd3fdb --- /dev/null +++ b/skills/ads-performance-analytics/references/cohort-analysis-templates.md @@ -0,0 +1,113 @@ +# Cohort analysis templates + +Three cohort cuts that matter for paid media. By acquisition month, by channel, by campaign. Plus retention curves and when to act. + +The principle. Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. The difference is the leading indicator that a channel or campaign is degrading; daily metrics catch the same problem two to three months later when it shows up in revenue. + +--- + +## Template 1: Cohort by acquisition month + +The standard rolling 12-month view of LTV growth. + +Setup. For each acquisition month over the last 12 months, compute the cumulative revenue per customer at month 1, month 3, month 6, and month 12 (where data is available). + +Output. + +\| Acquisition month \| M1 revenue/customer \| M3 revenue/customer \| M6 revenue/customer \| M12 revenue/customer \| +\|---\|---\|---\|---\|---\| +\| 2025-05 \| $42 \| $86 \| $128 \| $185 \| +\| 2025-06 \| $44 \| $89 \| $135 \| $192 \| +\| 2025-07 \| $40 \| $82 \| $122 \| $178 \| +\| 2025-08 \| $43 \| $85 \| $130 \| (incomplete) \| +\| 2025-09 \| $38 \| $78 \| (incomplete) \| (incomplete) \| +\| 2025-10 \| $35 \| $72 \| (incomplete) \| (incomplete) \| +\| 2025-11 \| $33 \| $68 \| (incomplete) \| (incomplete) \| +\| 2025-12 \| $34 \| (incomplete) \| (incomplete) \| (incomplete) \| + +The signal. The M3 revenue per customer dropped from $86 to $68 over six months. Recent acquisitions are lower-quality customers. The daily metrics will show this as ROAS deterioration in two to three months when the recent cohorts hit their declining LTV plateau. + +Action. Investigate which channels or campaigns shifted in the last six months. The drop usually correlates with a specific channel scaling into lower-quality audiences. + +--- + +## Template 2: Cohort by acquisition channel + +The channel-level LTV story that ROAS hides. + +Setup. For each channel, compute LTV at fixed time windows (30, 60, 90, 180, 365 days post-acquisition). Track the trend over multiple acquisition cohorts. + +Output (cohort: 2025-Q3 acquisitions, measured at 90 days post-acquisition). + +\| Channel \| New customers \| CAC \| 90-day revenue/customer \| 90-day LTV/CAC \| Verdict \| +\|---\|---\|---\|---\|---\|---\| +\| Google brand search \| 420 \| $45 \| $128 \| 2.8x \| Strong \| +\| Google generic search \| 280 \| $95 \| $112 \| 1.2x \| Marginal \| +\| Meta prospecting \| 540 \| $72 \| $84 \| 1.2x \| Marginal \| +\| Meta retargeting \| 320 \| $48 \| $156 \| 3.3x \| Strong \| +\| LinkedIn Sponsored \| 95 \| $320 \| $580 \| 1.8x \| Long payback; B2B-typical \| +\| TikTok In-Feed \| 180 \| $58 \| $61 \| 1.1x \| Marginal \| +\| Direct (organic) \| 1,200 \| n/a \| $145 \| n/a \| Reference baseline \| + +The signal. Meta retargeting and Google brand search are the strong performers on LTV-CAC. Meta prospecting and TikTok In-Feed are marginal; the customer quality is lower than the platform-reported ROAS suggests. + +Action. The marginal channels need either CAC reduction or audience-quality improvement. Pulling back on the marginal channels and reallocating to the strong ones improves blended LTV-CAC. + +--- + +## Template 3: Cohort by acquisition campaign + +Campaign-level cohort signals. Use sparingly; sample sizes get small fast. + +Setup. For each campaign with sufficient acquisition volume (typically 100+ customers per cohort), compute LTV at 30 and 60 days. Compare against the channel average. + +Output. + +\| Campaign \| New customers \| CAC \| 60-day revenue/customer \| vs channel average \| +\|---\|---\|---\|---\|---\| +\| Meta-Lookalike-1pct \| 320 \| $58 \| $112 \| +30% \| +\| Meta-Lookalike-5pct \| 180 \| $48 \| $74 \| -15% \| +\| Meta-Interest-SaaS \| 90 \| $72 \| $86 \| -5% \| +\| Meta-Retargeting-30day \| 240 \| $42 \| $148 \| +60% \| + +The signal. The 5% lookalike is finding lower-quality customers than the 1% lookalike, even at lower CAC. The ROAS view favors the 5% lookalike (lower CAC, decent revenue); the cohort view shows the customer quality dropped. + +Action. Pull back the 5% lookalike. Concentrate spend on the 1% lookalike and the retargeting segments. Watch for next-cohort confirmation before a permanent reallocation. + +--- + +## Retention curves + +A retention curve plots customer activity over time. Three patterns to recognize. + +Plateau curve. Activity drops in the first 30 days, then stabilizes at a level it sustains long-term. The plateau height is the long-run user value. Healthy SaaS, subscription consumer, marketplace. + +Smile curve. Activity drops, plateaus, then trends upward (resurrection effect). Less common; characteristic of products with seasonal or lifecycle re-engagement. + +Decay curve. Activity drops continuously without stabilizing. The product is not retaining; the unit economics will not work no matter what CAC the channel produces. Common in low-engagement consumer apps. + +The curve to watch by acquisition channel. A channel whose retention curve plateaus higher than another is delivering higher-LTV customers, regardless of the CAC ratio. This is the data behind LTV-CAC channel comparisons. + +--- + +## When to act on cohort signals + +Three triggers. + +1. Two consecutive months of LTV decline at the same time horizon. A single month is noise; two is signal. Investigate which channels shifted. +2. Channel-level LTV-CAC ratio falls below 2x for two consecutive cohorts. Pause or reallocate the channel. The 2x threshold accounts for gross margin, payback period, and the variance in LTV measurement. +3. A campaign-level cohort underperforms the channel average by 20%+ for two consecutive cohorts. The campaign is bringing in lower-quality audiences than the rest of the channel. Pause or reallocate. + +The discipline. Watch cohort signals on a monthly cadence. Most teams over-index on weekly platform metrics and under-index on cohort signals; the cohort-watchers see the problems first. + +--- + +## Common cohort mistakes + +Reading recent cohorts as final. A 30-day cohort's "LTV" is actually 30-day revenue, not LTV. Naming matters. If the team treats 30-day revenue as LTV in spreadsheets, they will undercount channels with longer payback periods. + +Comparing cohorts at different ages. A January cohort measured at 12 months vs a November cohort measured at 2 months is comparing different things. Always compare at matched ages. + +Ignoring seasonal cohorts. Q4 cohorts often have higher first-purchase value but lower retention because Q4 acquisition includes one-time gifters. Account for the seasonal pattern; do not over-index on Q4 cohort numbers. + +Not segmenting by channel. Aggregate LTV trends hide channel-level shifts. The channel-segmented cohort is where the action signal lives. diff --git a/skills/ads-performance-analytics/references/common-interpretation-failures.md b/skills/ads-performance-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..5b6e91d --- /dev/null +++ b/skills/ads-performance-analytics/references/common-interpretation-failures.md @@ -0,0 +1,155 @@ +# Common interpretation failures + +Twelve failure patterns that recur in paid media reporting work. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. ROAS dropped 20% week-over-week, kill the campaign + +Symptom. Weekly ROAS chart shows a drop. Team wants to pause the campaign. + +Root cause. Could be noise. Day-of-week, holiday timing, conversion-window lag, exogenous variance. A 20% drop in a metric that varies 10 to 15% naturally is below the signal threshold. + +Fix. Pre-commit a test window before acting on weekly variance. For most campaigns, two consecutive weeks of decline below the threshold is the signal. Single-week swings are usually noise. + +Prevention. Establish baseline variance for each campaign before declaring "improvement" or "decline." Without the baseline, every weekly chart looks alarming. + +--- + +## 2. Meta says 500 conversions, my warehouse says 200, who is right + +Symptom. Platform-reported numbers do not match warehouse numbers. The team picks the more flattering one. + +Root cause. Both are wrong; warehouse is closer to truth. Meta self-attributes (claims credit for conversions other channels also touched). View-through and modeled conversions inflate Meta's count. + +Fix. Reconcile, do not pick a winner. Report the warehouse number as canonical for board metrics. Use Meta's number only for in-flight optimization within Meta. + +Prevention. Make the reconciliation cadence explicit. Weekly check, monthly deep dive, quarterly attribution review. The team that runs the reconciliation never has to "pick a winner." + +--- + +## 3. Turned off Google PMax, conversions did not drop + +Symptom. Paused PMax. Total account conversions held steady. + +Root cause. PMax was harvesting branded search conversions you would have gotten free from organic. The platform was claiming credit for traffic that was not incremental. + +Fix. Audit branded queries inside PMax. Add account-level negative keywords for branded queries. Restart PMax with branded excluded; the incremental contribution from non-branded inventory is the real value. + +Prevention. At PMax setup, exclude branded queries from the start. Audit PMax's spend distribution monthly to catch the cannibalization pattern early. + +--- + +## 4. New campaign hit 5x ROAS in week 1 + +Symptom. A fresh campaign's first-week ROAS is 5x. Team wants to scale immediately. + +Root cause. Likely retargeting hot leads or running on a small audience of warm prospects who would have converted anyway. The first week is unrepresentative. + +Fix. Check the audience composition. If retargeting or warm-list, the 5x is not the steady-state. Wait two to four weeks before scaling. + +Prevention. Define the success metric and the test window before launch. Do not let a strong first week change the plan; pre-commit to the four-week measurement. + +--- + +## 5. A/B tested and one creative wins by 12% + +Symptom. Two creatives tested. One wins by 12%. Team wants to ship the winner. + +Root cause. 12% is within margin of platform noise for a typical creative test. Variants compete with each other inside the platform's optimization; the platform's own decisions confound the test. + +Fix. Re-run the test with more volume, or accept that the difference is within noise and pick based on production cost or refresh ease. + +Prevention. Set the minimum detectable effect (MDE) before testing. A 12% threshold requires a specific volume; if you cannot reach it, the test cannot detect that effect cleanly. + +--- + +## 6. LTV calculation says this channel is profitable + +Symptom. A team's LTV-CAC analysis shows a channel as profitable. Spend is increased. + +Root cause. The "LTV" in the calculation may be a 60-day cumulative revenue projected forward, not actual lifetime value. Recent cohorts have not aged enough to confirm the LTV. + +Fix. Confirm the cohort age. If projecting forward, document the assumption and stress-test (what happens if actual LTV is 80% of projected). + +Prevention. Always pair LTV calculations with cohort age. A 30-day cohort has 30-day revenue, not LTV. Naming clearly prevents the substitution error. + +--- + +## 7. High frequency is fine because conversions are still happening + +Symptom. Frequency at 6 to 8 per week. Conversions on the platform are stable. Team concludes fatigue is not an issue. + +Root cause. Fatigue masked by conversions that would have happened anyway from organic, retargeting overlap, or recurring customers. The platform is taking credit for traffic the high frequency did not actually drive. + +Fix. Run an incrementality test on the high-frequency campaign. The likely finding is that incremental rate dropped substantially even as raw conversions held. + +Prevention. Watch frequency as a leading indicator. Above 4 to 5 per week is the alarm regardless of conversion levels. Refresh creative. + +--- + +## 8. Last-click attribution shows Meta at 60% credit + +Symptom. Last-click view of paid media shows Meta dominant. Team allocates budget accordingly. + +Root cause. Last-click bias. Meta may also be the closer because users who searched for the brand on Google clicked through, then later saw a Meta retargeting ad and converted. Last-click credits Meta; the conversion would have happened anyway. + +Fix. Read the same data under first-click and a multi-touch model. The picture changes. Allocate based on a balanced view, not the last-click view alone. + +Prevention. Always compare attribution under at least two models for budget decisions. The single-model view is reliable for in-flight only. + +--- + +## 9. Scaled spend 5x, conversions only doubled + +Symptom. Budget went from $20K to $100K per month. Conversions went from 800 to 1,600. + +Root cause. Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher than the average CAC the team was reporting. + +Fix. Calculate the marginal CAC, not just average CAC. The marginal CAC at the higher spend tier tells you whether more spend will produce more conversions or just spend more for the same conversions. + +Prevention. Project the saturation curve before scaling. If a 1.5x spend increase produced a 1.2x conversion increase, expect the next 1.5x to produce 1.0x or less. + +--- + +## 10. Brand campaigns underperform on direct ROAS + +Symptom. A brand campaign reports 0.8x ROAS. Team wants to cut it. + +Root cause. Brand campaigns affect downstream channel efficiency, not direct conversion. The direct ROAS is the wrong measurement for brand impact. + +Fix. Measure brand against brand-search lift, organic traffic growth, or direct-traffic growth. The brand campaign's effect shows up in cheaper performance acquisition over the next 60 to 90 days. + +Prevention. At brand campaign setup, define the success metric explicitly (brand search lift target, organic traffic target, awareness lift). Do not let direct ROAS become the unintended grading metric. + +--- + +## 11. ROAS held steady but profit dropped + +Symptom. Channel-level ROAS at 3x, stable. Profit on the same channel dropped 20% over the quarter. + +Root cause. The mix shifted toward lower-margin products. ROAS is a revenue metric; it does not see margin. The channel attracted bargain hunters at lower margin, holding ROAS but cutting profit. + +Fix. Track contribution-margin ROAS, not gross-revenue ROAS. The contribution-margin view catches the mix shift the gross view hides. + +Prevention. Build margin-aware reporting from the start. Most teams default to gross revenue; the move to contribution margin pays for itself within a quarter. + +--- + +## 12. Agency reported a 4x ROAS month + +Symptom. External agency claims a 4x ROAS for the month. Team accepts the number. + +Root cause. Whose number? Platform-reported, warehouse-attributed, or model-adjusted? Agencies often report the most generous number (their incentive). Without specifying the attribution methodology, the 4x ROAS is unreadable. + +Fix. Demand the attribution methodology in every agency report. Reconcile against the warehouse before presenting to leadership. + +Prevention. Build attribution-methodology specification into the agency contract. Reports must include the model, the window, and the source of conversion data. The contract that does not specify produces reports that cannot be evaluated. + +--- + +## The pattern across all twelve + +Most paid media interpretation failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale ROAS at the cost of LTV. Pause an underperformer at the cost of total volume. Trust platform-reported attribution at the cost of incremental truth. + +The fix at the meta level. Decide on the success metric (warehouse-attributed CAC, LTV-CAC ratio, contribution-margin ROAS) and the guardrails (volume, frequency, customer-cohort quality, brand metrics) before reading any dashboard. Pull back the moment a guardrail breaks, even if the success metric still looks fine. The dashboard is a tool, not the truth; the warehouse plus quarterly incrementality testing is closer to truth. diff --git a/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md b/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md new file mode 100644 index 0000000..1066402 --- /dev/null +++ b/skills/ads-performance-analytics/references/dashboard-reconciliation-patterns.md @@ -0,0 +1,114 @@ +# Dashboard reconciliation patterns + +The single-source-of-truth pattern for paid media reporting. Warehouse as canonical; platforms as in-flight signals. + +The principle. Sum-of-platform-reports is always greater than reality because every platform claims credit for conversions other platforms also touched. Reporting platform-summed numbers as fact in board decks is the most expensive error in paid media analytics. + +--- + +## The three-layer reporting model + +Layer 1: platform metrics. Use for in-flight optimization only. Ad-set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +Layer 2: warehouse multi-touch attribution. Use for cross-platform comparison and channel-level decisions. Each conversion gets attributed across all platforms that touched the path. Pick one model (last-click, first-click, linear, U-shaped, DDA) and standardize across the team. + +Layer 3: marketing-mix modeling (MMM) at scale. Use for budget allocation across channels. MMM treats spend as input and revenue as output; it does not rely on platform-reported attribution at all. The strongest defense against platform self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## Blended CAC + +The board-deck number. Resistant to attribution debates because it does not require choosing an attribution model. + +Formula. + +``` +Blended CAC = (total ad spend across platforms) / (total new customers from warehouse) +``` + +Worked example. + +In Q4, the team spent $200K total: $80K on Google Ads, $70K on Meta, $30K on LinkedIn, $20K on TikTok. The warehouse shows 1,250 new customers in Q4 from all sources (paid, organic, direct, referral). + +But the team needs to attribute the new customers to paid specifically. Two ways to do this: + +1. Approximate. Assume the proportion of paid-attributed customers in the warehouse roughly equals the proportion that paid contributed to traffic. If 60% of traffic in Q4 was paid-attributed, then 60% of 1,250 equals 750 paid-acquired customers. Blended paid CAC: $200K / 750 = $267. +2. Precise. Use the warehouse's multi-touch attribution to credit paid channels with a fraction of each conversion. Sum the paid-attributed share across all conversions; that becomes the denominator. + +The precise version is better when available. The approximate version works when the warehouse data is incomplete. Both produce a number that does not double-count across platforms. + +--- + +## The board-deck pattern + +Three rules for reporting paid media numbers to leadership. + +1. Lead with blended CAC, not channel CAC. Channel CAC depends on attribution model; blended CAC does not. Stakeholders not in the weeds on attribution find blended CAC easier to compare across quarters. +2. Show the range. Report the conservative view (last-click) and the generous view (linear or DDA) for any high-stakes channel decision. The range tells stakeholders what they are not learning. +3. Always label the source. "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions per Meta's 7-day-click attribution; warehouse-attributed: 540" is honest. + +A worked example board slide. + +``` +Q4 paid media performance + +Total spend: $200K (vs $185K Q3, +8%) +New customers from paid (warehouse-attributed): 750 (vs 680 Q3, +10%) +Blended paid CAC: $267 (vs $272 Q3, -2%) + +Channel CAC (warehouse-attributed, last-click): + Google: $240 (40% of new customers) + Meta: $290 (35% of new customers) + LinkedIn: $480 (15% of new customers) + TikTok: $180 (10% of new customers) + +Platform-reported CAC (for in-flight context, not board decision): + Google: $190 (Google reports 26% more attributed conversions than warehouse) + Meta: $210 (Meta reports 38% more) + LinkedIn: $475 (roughly aligned) + TikTok: $135 (TikTok reports 33% more) + +Quarterly incrementality test result (geo holdout, October): + Brand search: 12% incremental (95% CI: 6-18%). Reduced spend 30%; CAC dropped. + Meta retargeting: 31% incremental (95% CI: 22-40%). Maintained spend; CAC view adjusted. +``` + +The slide tells the truth: the warehouse number is the canonical CAC, the platform numbers are inflated, the incrementality test confirms which channels are real. + +--- + +## Reconciliation cadence + +Weekly. Pull platform-reported numbers and warehouse numbers. Confirm the sum-of-platforms vs warehouse ratio is in the expected range. A sudden divergence means a tracking break, an attribution-model change, or a platform reporting bug. Investigate. + +Monthly. Deeper reconciliation. Compare channel-level attribution across last-click, first-click, and the team's chosen model. Identify channels whose ranking changes by model. + +Quarterly. Run an incrementality test on the highest-spend channel. Update the channel-level CAC adjustment factor based on the test result. + +--- + +## Common reconciliation mistakes + +Reporting platform-summed conversions to the board. The most common error. The board sees "1,600 conversions across paid channels" when the warehouse says 950. The team gets caught when someone divides revenue by 1,600 and gets a CAC that does not match the P&L. + +Comparing platforms on platform-reported CAC. Each platform's CAC is computed against a different attribution window and a different set of self-attribution biases. Compare on warehouse-attributed CAC instead. + +Treating "lift" as incrementality without a controlled test. A campaign that ran during a period of overall conversion growth gets credit for "lift" that was actually seasonality or organic momentum. Lift requires a control group; otherwise it is correlation reported as causation. + +Updating attribution models mid-quarter. Switching from last-click to DDA mid-quarter makes the quarter's data uninterpretable. Pick a model for the quarter; switch only at quarter boundaries with a documented changelog. + +Reporting blended CAC without naming the time window. "$267 blended CAC" depends on whether you measured over 30, 60, or 90 days. Pin the window. + +--- + +## When the platforms agree more than usual + +A useful diagnostic. If platform-reported sums match warehouse total within 10%, something has changed. Possibilities: + +- The team set up Conversions API on Meta or server-side tagging on Google, which improved tracking precision. +- The mix shifted toward branded search, where attribution overlap is lower. +- One platform's conversion volume dropped significantly (saturation, fatigue, or campaign issue). + +Investigate any sudden alignment. The platforms diverging is the normal state; alignment usually has a cause worth understanding. diff --git a/skills/ads-performance-analytics/references/incrementality-testing-playbook.md b/skills/ads-performance-analytics/references/incrementality-testing-playbook.md new file mode 100644 index 0000000..a52ea6c --- /dev/null +++ b/skills/ads-performance-analytics/references/incrementality-testing-playbook.md @@ -0,0 +1,139 @@ +# Incrementality testing playbook + +The honest test in paid media analytics. If we had not run this ad, would we still have gotten the conversion? The answer above zero is the incremental contribution. + +The principle. Most paid media is not 100% incremental. Branded search bidding is often 5 to 20% incremental. Retargeting is often 20 to 40% incremental. Prospecting is often 50 to 90% incremental. The number that matters for spend decisions is the incremental rate, not the platform-reported attribution rate. + +--- + +## Method 1: Geo holdout + +The cleanest causal test for paid media at scale. + +Setup. Pick two regions with similar baseline conversion rates and demographic profiles (matched markets). Run the campaign in one region (test); turn it off in the other (holdout). + +Duration. Two to four weeks minimum. Statistical power calculation upfront determines the right length given the spend scale and expected lift. + +Analysis. Compare conversions in test vs holdout, normalized by population. The difference is the incremental contribution. + +Expected incremental rate ranges. + +\| Channel \| Typical incremental rate \| +\|---\|---\| +\| Branded search \| 5 to 20% \| +\| Retargeting \| 20 to 40% \| +\| Lookalike audiences \| 40 to 70% \| +\| Cold prospecting \| 50 to 90% \| +\| Awareness video \| 30 to 60% \| + +Common pitfalls. + +- Picking holdout regions with confounding factors (different competitive presence, weather event, retail launch). Confounded results are worse than no test. +- Stopping the test early when the data looks good. Pre-commit the duration and stick to it. +- Holding out for too long. A 6-week holdout in a small region is expensive in lost conversions; 2 to 4 weeks is usually enough at scale. + +--- + +## Method 2: Ghost bidding (Google) + +Google's own incrementality tool. The platform bids on a holdout share of impressions but does not actually serve the ad. The reported delta between served and ghost is incremental. + +Setup. Configure within Google Ads. Choose the campaigns and the holdout share (typically 5 to 20%). + +Duration. Two to four weeks. + +Analysis. Google reports incremental conversions directly. Cross-validate against your own warehouse measurement. + +Pitfalls. + +- The math is opaque to many teams. The output is a single incremental number; the underlying methodology is Google's. Trust but verify with a manual geo test on the same campaign. +- Only available within Google Ads, not cross-channel. + +--- + +## Method 3: Conversion lift studies (Meta) + +Meta's incrementality tool. Splits audiences into test (sees the ad) and control (does not). Measures lift. + +Setup. Configure within Meta Ads Manager. Specify the campaign and the test-control split. + +Duration. Three to four weeks. Meta requires a minimum spend per study. + +Analysis. Meta reports incremental lift. The reporting includes statistical significance bands. + +Pitfalls. + +- The minimum spend requirement makes it expensive for small accounts. +- Only available within Meta, not cross-channel. +- Meta's interpretation tilts toward generous (their incentive). Cross-validate with geo holdout when possible. + +--- + +## Method 4: PSA tests + +Serve some users a public service announcement instead of your ad. Compare conversion rates. + +Setup. Run two parallel campaigns: one with your ad, one with a PSA (typically a charity or public-interest message). Match audiences. + +Duration. Three to six weeks. + +Analysis. Compare conversion rate of the PSA-exposed audience against the ad-exposed audience. The difference is incremental. + +Pitfalls. + +- Ethically and brand-wise, choose PSAs that align with brand values. +- Setup overhead is high. Reserved for legacy brands with deep budgets and serious incrementality questions. + +--- + +## Method 5: Switchback designs + +Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. + +Setup. Run for at least 8 weeks. Alternate weekly: on, off, on, off. Or alternate by audience segment. + +Duration. Eight to twelve weeks. Shorter switchbacks have low statistical power. + +Analysis. Difference in conversions between on-weeks and off-weeks, normalized for week-of-year and external variance. + +Pitfalls. + +- Confounded by exogenous factors (news, competitor activity, seasonality). Best for steady-state campaigns where the external context is stable. +- Audience contamination: users who saw the ad in week 1 may convert in week 2 even when the campaign is off. The contamination dilutes the measured incremental rate. + +--- + +## Choosing the right method + +\| Constraint \| Recommended method \| +\|---\|---\| +\| Single platform, want quick answer \| Platform-native (ghost bidding for Google, conversion lift for Meta) \| +\| Cross-platform incremental test \| Geo holdout \| +\| Small account, limited budget \| Geo holdout in two small matched markets \| +\| Long campaign cycle, steady-state \| Switchback \| +\| Brand or awareness channel \| PSA test or geo holdout \| +\| Regulated industry, ethics concern \| Geo holdout (no PSA) \| + +The default. Geo holdout. It is the most honest causal test, works cross-channel, and produces results that are interpretable without trusting the platform's methodology. + +--- + +## How to run a geo holdout step by step + +1. Pick matched markets. Use designated market areas (DMAs) or postal-code-level regions with similar baseline conversion rates and demographic profiles. Aim for at least three test and three holdout regions for statistical power. +2. Calculate statistical power. Given the expected lift and the regional conversion volume, can the test detect the effect? If the regions are too small, the test is underpowered and inconclusive results are likely. +3. Pre-commit the analysis window. Define the start date and end date before the test begins. Do not adjust based on early results. +4. Run the test. Campaign on in test regions; off in holdout. No mid-test changes. +5. Wait for the full window. Analyzing early produces noise. +6. Compute the delta. Conversions in test minus conversions in holdout, normalized by population. The delta divided by spend is the incremental CPA. Compare against the platform-reported CPA; the gap is the over-attribution. +7. Report incremental contribution. Do not report platform-reported CAC alongside warehouse CAC and incremental CAC without labeling. The unit of measurement matters as much as the number. + +--- + +## Cadence + +For accounts spending $25K+ per month, run incrementality tests at least quarterly on the highest-spend channels. The cost of the test is small relative to the cost of running un-incremental spend at scale. + +For accounts under $25K per month, annual or semi-annual tests are typically enough. The test cost vs the spend savings does not pencil out as often. + +The discipline. Schedule the tests. Do not wait for a "we should test this" moment; the moment never comes voluntarily. diff --git a/skills/ads-performance-analytics/references/metric-definitions-glossary.md b/skills/ads-performance-analytics/references/metric-definitions-glossary.md new file mode 100644 index 0000000..ee569ff --- /dev/null +++ b/skills/ads-performance-analytics/references/metric-definitions-glossary.md @@ -0,0 +1,83 @@ +# Metric definitions glossary + +The paid media metrics that show up on every dashboard, with explicit definitions, formulas, and the common pitfalls in usage. + +The point of an explicit glossary. Two teams using the same metric name often compute different numbers. "Conversion rate" might mean clicks-to-conversion or impressions-to-conversion or unique-users-to-conversion. The team that does not pin definitions ends up arguing about numbers that are not the same number. + +--- + +## Volume metrics + +Impressions. Count of times an ad was displayed. Includes the same user seeing the ad multiple times. + +Reach. Count of unique users who saw the ad. Always less than or equal to impressions. + +Frequency. Impressions divided by reach. The average number of times a unique user saw the ad. Above 4 to 5 per week is the fatigue alarm. + +Clicks. Count of clicks on the ad. Some platforms count "outbound clicks" (which leave the platform) separately from "all clicks" (which include in-platform interactions like saves and shares). Use outbound for direct response. + +--- + +## Cost metrics + +CPC (cost per click). Spend divided by clicks. Formula: `spend / clicks`. The cost of one click; not the cost of one conversion. Conflating them is the most common reporting error. + +CPM (cost per thousand impressions). Spend divided by (impressions / 1000). Formula: `spend / (impressions / 1000)`. The cost of reach. Useful for comparing platforms on awareness efficiency. + +CPA (cost per acquisition). Spend divided by conversions. Formula: `spend / conversions`. The variant where "conversion" is defined matters; the same campaign reports different CPAs depending on whether the conversion is a click, a lead form submission, a purchase, or a paid customer. + +ROAS (return on ad spend). Revenue from ad-attributed conversions divided by spend. Formula: `attributed revenue / spend`. NOT profit-divided-by-spend. ROAS is a revenue metric, not a profit metric. A 3x ROAS at 30% margin is a 0.9x return on cost; the ROAS reading on its own is misleading. + +MER (marketing efficiency ratio). Total revenue divided by total marketing spend, across all channels. Formula: `total revenue / total marketing spend`. The most honest top-line number; resistant to per-channel attribution debates. + +Blended CAC. Total ad spend divided by total new customers from warehouse. Formula: `total ad spend / new customers from warehouse`. The board-deck number. Channel-level CAC depends on attribution; blended CAC does not. + +--- + +## Conversion metrics + +Conversion. The event the campaign optimizes for. Definition varies. Always document: which event, what window, which attribution model. Without these three, "conversions = 800" is unreadable. + +Conversion rate. Conversions divided by something. The denominator changes the meaning. Click-through conversion rate (`conversions / clicks`) is different from impression conversion rate (`conversions / impressions`) which is different from unique-user conversion rate (`conversions / reach`). Pin the denominator at every report. + +Conversion window. The maximum time between the ad event (click or view) and the conversion for which the platform takes credit. Meta default: 7-day click plus 1-day view. Google default: 30-day click plus 1-day view. Different windows mean different reported counts from the same activity. + +View-through conversion. A conversion attributed to an ad the user saw but did not click. Counted by Meta and Google. Often half the platform-reported conversions are view-through. Treat as a soft signal of awareness contribution, not as direct response measurement. + +Modeled conversion. A statistically estimated conversion when actual tracking is blocked (most commonly iOS users on Meta after ATT). The platform models what the conversion would have been based on aggregated data. Modeled is an estimate, not a measurement; precision is low. + +--- + +## Customer-value metrics + +LTV (lifetime value). Total revenue from a customer over their relationship with the brand. Many definitions; the right one for paid media analytics is gross revenue or contribution margin, not unit count. Pair with CAC for the LTV:CAC ratio. + +LTV:CAC ratio. LTV divided by CAC. Formula: `LTV / CAC`. The unit-economics test. 3:1 is the venture-capital benchmark; the right number for any specific business depends on payback period and gross margin. + +Payback period. Months until cumulative revenue from a customer equals the CAC to acquire them. The cash-flow companion to LTV:CAC. Investors care about payback; operators care about both. + +AOV (average order value). Revenue divided by order count. Formula: `revenue / orders`. Useful for e-commerce; less for subscription. The number that turns "increased conversion rate" into "increased revenue." + +--- + +## Engagement metrics (less direct) + +CTR (click-through rate). Clicks divided by impressions. Formula: `clicks / impressions`. Useful for hook quality. Less useful for conversion quality; high CTR with low conversion rate means the hook is too aggressive for the offer. + +Hide ratio (negative feedback). Count of users who explicitly hid or marked the ad as not-interested, divided by impressions. Above 1.5% is the alarm; the platform algorithm will throttle delivery to that audience. + +Engagement rate. Likes plus comments plus shares plus saves divided by impressions. Useful for organic-style content; less directly tied to performance for paid. + +--- + +## Common pitfalls + +Treating ROAS as profit. ROAS is revenue-divided-by-spend. Profit-divided-by-spend is "return on ad investment" or "ROI." Confusing the two leads to greenlit campaigns that lose money on every conversion. + +Ignoring conversion window in cross-platform comparisons. Meta's 7-day-click count is not comparable to Google's 30-day-click count without normalization. + +Treating frequency as a vanity number. Frequency above 4 to 5 per week is a fatigue signal. Many teams celebrate high frequency as proof of "audience saturation"; it is the inverse. + +Using CPA when conversion definitions differ across campaigns. A search campaign with a "lead-form-submission" conversion has a CPA in different units from a display campaign with a "purchase" conversion. Compare campaign-level CPA only when the conversion event matches. + +Confusing modeled conversions with measured conversions. Modeled is an estimate; measured is a count. Treating the two as interchangeable produces false confidence in the size of the effect. diff --git a/skills/ads-performance-analytics/references/platform-reporting-quirks.md b/skills/ads-performance-analytics/references/platform-reporting-quirks.md new file mode 100644 index 0000000..363477b --- /dev/null +++ b/skills/ads-performance-analytics/references/platform-reporting-quirks.md @@ -0,0 +1,108 @@ +# Platform reporting quirks + +Per-platform reporting behaviors that affect how to read the numbers. The platforms do not agree on what counts as a conversion or how to credit it; reading their dashboards as truth is the most expensive error in paid media analytics. + +--- + +## Google Ads + +Default attribution model. Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on machine learning. Single-touch attribution (last-click) is available but no longer the default. + +Conversion windows. Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA4 reports by default; this produces the typical 1.3 to 1.5x conversion overcount versus GA4 for the "Google Ads" channel. + +Modeled conversions. Google models conversions for users with consent restrictions or cross-device gaps. Modeled volume can be material in iOS-heavy traffic. Modeled is an estimate; do not treat with the precision you would treat directly observed conversions. + +Performance Max black box. PMax does not expose keyword-level, placement-level, or audience-level performance directly. The platform manages allocation across Search, Shopping, Display, YouTube, Discover, and Gmail. Levers you have: budget, asset groups (creative quality), audience signals (Customer Match seeds), and exclusions (account-level negatives). + +Branded search cannibalization in PMax. PMax includes Search by default. It will harvest branded queries you would have ranked for organically. Add account-level negative keywords for branded queries to prevent paid cannibalization. + +Lost Impression Share metrics. Search exposes "Lost IS (rank)" and "Lost IS (budget)" to indicate why your ad did not show. Lost IS rising is the leading indicator that competition increased or budget became constrained. + +Search-term reports. The list of actual queries that triggered your ad, vs your keyword targeting. Underused. Audit monthly to find irrelevant queries (negative keyword candidates) and high-performing queries you might want to add as exact-match keywords. + +--- + +## Meta (Facebook and Instagram) + +Default attribution. 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +iOS 14.5+ impact. App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated) and Conversions API (CAPI, server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +Conversions API necessity. CAPI sends server-side events directly from your backend to Meta, bypassing the browser-pixel restrictions. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. Without CAPI, the platform's optimization signal degrades significantly on iOS-heavy audiences. + +View-through attribution overcount. View-through counts impressions even when the user did not click. Often half the reported conversions on Meta are view-through. Useful as awareness signal; misleading for performance optimization. + +Modeled conversions in iOS reports. Meta reports modeled conversions inline with directly observed ones unless you filter explicitly. Use the breakdown view to disaggregate by attribution type (1-day click, 7-day click, 1-day view, modeled). + +Frequency reporting at the ad set level. Meta exposes frequency in the Ads Manager. Use it as the primary fatigue signal; CTR decay is downstream of frequency rising. + +Negative feedback rate. Meta exposes "negative feedback rate" as a customizable column. Above 1.5% is the alarm; the algorithm penalizes high-feedback creatives by reducing reach. + +--- + +## LinkedIn + +Default attribution. 30-day click and 7-day view-through. + +Why the longer windows. B2B buying cycles are longer than B2C. The 30-day-click window matches the typical B2B consideration cycle. Comparing LinkedIn's reported numbers against Meta's 7-day-click numbers without normalizing is comparing different definitions. + +Cross-device gaps. LinkedIn reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair LinkedIn paid reports with self-reported attribution surveys when the offer is high-consideration B2B. + +Lead Gen Forms reporting. Form submissions count as conversions regardless of downstream lead qualification. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. Many leads are accidental or low-quality. + +Demographic insights. LinkedIn's demographic reporting (industry, job seniority, company size, function) is unique to the platform. Use it for audience refinement; the data is not available cleanly on other platforms. + +Cost insights. LinkedIn's CPM tends to be 3 to 10x higher than B2C platforms because of the audience precision premium. The justification is B2B LTV; lower-LTV offers cannot make LinkedIn math work. + +--- + +## TikTok + +Default attribution. 7-day click and 1-day view-through, similar to Meta. + +Video-completion-based attribution. TikTok counts conversions even when the user did not click but watched the full video. This is unique among the platforms covered here. The signal is real for awareness; it inflates direct-response numbers. + +iOS impact, less mature modeling. TikTok faces similar ATT-driven tracking gaps as Meta. The modeling is less mature, which means iOS-heavy audiences see more under-reporting on TikTok than on Meta. + +Spark Ads attribution overlap. Spark Ads boost organic posts. Engagement on the boosted version shows up in both organic and paid surfaces. Be careful not to double-count when reconciling against organic engagement reports. + +Spark Ads vs paid creative differential. Spark Ads consistently outperform pure paid creative on TikTok because they retain organic engagement signals. A team comparing CPMs of Spark vs paid will see Spark consistently lower; the difference is real, not a reporting artifact. + +Trend-based volatility. TikTok performance is more sensitive to trending sounds and formats than other platforms. Reporting comparisons across long time periods are less reliable because the platform itself shifted. + +--- + +## Programmatic and Display + +Viewability gates. Programmatic display sells impressions, but only "viewable" impressions count toward billed performance. The Media Rating Council (MRC) standard is 50% of pixels in view for 1 second (display) or 2 seconds (video). Below this threshold, the impression should not be billed. + +Fraud filters. Programmatic exposes fraud-detection metrics. Without fraud filtering, 10 to 30% of programmatic impressions are bot or fraudulent traffic. Use vendors like DoubleVerify or IAS for filtering. + +Attribution decay. Programmatic display's incremental rate is usually 5 to 20%. Most clicks come from users who would have converted from other channels anyway. Treat programmatic as awareness; do not optimize for direct response unless the incrementality test confirms it. + +--- + +## Cross-platform interference + +A specific quirk worth a dedicated callout. + +The mechanism. Two platforms claim the same conversion. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). The same revenue event shows up twice in the platform totals. + +The detection. Sum-of-platforms exceeds total conversions in the warehouse. If platform-reported sum is 1.5 to 3x the warehouse total, you have heavy cross-platform double-counting. + +The defense. Warehouse as canonical for board reporting. Platform reports for in-flight tuning of the platform's own levers. MMM at scale to estimate true cross-channel contribution. + +--- + +## Reporting differences in numbers + +A typical mid-stage account has the following attribution gap pattern across platforms. + +- Google Ads reports: 1.3 to 1.5x what GA4 reports for the "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA4 reports for the "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA4 for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA4 reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/skills/after-action-report/SKILL.md b/skills/after-action-report/SKILL.md new file mode 100644 index 0000000..d1690cc --- /dev/null +++ b/skills/after-action-report/SKILL.md @@ -0,0 +1,282 @@ +--- +name: after-action-report +description: "Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings." +category: operations +catalog_summary: "Post-mortems, retros, learnings documentation" +display_order: 3 +--- + +# After-Action Report + +Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document. + +This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`. + +--- + +## When to use + +- After any incident (any severity) +- After every major launch +- At the end of a project (sprint retro, quarterly retro, project closeout) +- When a recurring issue has happened enough times to demand investigation +- When a decision didn't work out and the team wants to learn + +## When NOT to use + +- During an active incident (use `incident-response`) +- For pre-launch planning (use `launch-runbook`) +- For one-off bug fixes that don't merit broad analysis + +--- + +## Required inputs + +- The event being analyzed (incident, launch, project) +- A timeline reconstructed from logs, chat, tickets +- Participant accounts of what they observed and did +- Outcomes and impact (what actually happened to users, the business) + +--- + +## The framework: blameless analysis + +The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones. + +### What blameless means + +- Focus on systems, not individuals +- Assume everyone made reasonable decisions given what they knew at the time +- The question is "why was this decision reasonable to make?" not "who screwed up?" +- Fixing the system means the next person in that situation succeeds where this person didn't + +### What blameless does not mean + +- No accountability (action items still have owners) +- No hard truths (sometimes the system is broken in obvious ways) +- No standards (some patterns of failure are individual, not systemic) +- No discomfort (real reflection is uncomfortable) + +--- + +## The framework: 6 sections + +A complete AAR covers six sections. + +### 1. Summary + +A 2 to 3 paragraph overview. Captures: + +- What happened +- Impact (users, business, time) +- Root cause (in plain language) +- Top action items + +This is what executives read. Anyone who reads only this section should leave with the most important information. + +### 2. Timeline + +A reconstructed timeline of events. + +For incidents: +- T-0: Detection +- T+X: Acknowledgment +- T+Y: Severity assessed, IC assigned +- T+Z: Investigation began +- ... mitigation, communication, resolution events +- T+N: Resolution declared + +For launches: +- Pre-launch decisions and milestones +- Launch day events +- Post-launch monitoring observations + +For projects: +- Major milestones, decisions, pivots +- Both planned and emergent + +The timeline is the source of truth. Disagreements about what happened get resolved here. + +### 3. Root cause analysis + +What caused this, in plain language. + +Use one or both of: + +Five whys. Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology. + +Example: +- Why did the site go down? Database connection pool exhausted. +- Why was the pool exhausted? Background job opened too many connections. +- Why did the background job open too many connections? Connection cleanup code didn't run on errors. +- Why didn't cleanup run on errors? Original code review didn't cover error paths. +- Why didn't the review cover error paths? No checklist for error handling in our review process. + +The fifth why often reveals the system fix. In this case: improve the review process. + +Causal chain. Multiple contributing factors that combined. + +- Factor 1: Background job opened too many connections (technical) +- Factor 2: Connection limit was set too low for actual traffic (configuration) +- Factor 3: No alert on connection pool saturation (monitoring) +- Factor 4: Recent traffic doubled without infra capacity review (process) + +No single fix addresses the incident. Multiple gaps need attention. + +### 4. Contributing factors + +Factors that didn't cause the event but made it worse, or removed safety nets that would have caught it. + +- Monitoring gaps +- Documentation gaps +- Process gaps +- Tooling gaps +- Knowledge gaps + +A "would have been caught earlier if..." factor. + +### 5. What went well + +Real lessons require capturing successes, not just failures. + +- What detection worked? +- What response worked? +- What decisions were good? +- What tools or processes performed as expected? + +This is not consolation. It's calibration. Things that worked here should be reinforced and replicated. + +### 6. Action items + +Specific, owned, dated. + +\| Action \| Owner \| Due \| Type \| +\|---\|---\|---\|---\| +\| Add alert on connection pool saturation \| [name] \| [date] \| Monitoring \| +\| Add error handling checklist to PR template \| [name] \| [date] \| Process \| +\| Audit other background jobs for similar issue \| [name] \| [date] \| Code \| + +Action item criteria: + +- Specific. "Improve monitoring" is not actionable. "Add alert on connection pool saturation, threshold 80%, page on-call" is. +- Owned. A name. Not "the team." +- Dated. A real date. Not "soon." +- Sized. Roughly hours, days, or weeks of effort. +- Closeable. Definition of done is clear. + +Action items that don't close in their committed timeframe should re-surface in the next AAR. Patterns of unclosed actions point to deeper organizational issues. + +--- + +## Workflow + +### 1. Schedule the AAR + +Within 1 to 2 weeks of the event. Long enough that emotions cooled and facts gathered. Short enough that memories are fresh. + +For incidents: pre-decided in the response procedure. +For launches: schedule on the runbook. +For projects: schedule at project closeout. + +### 2. Gather inputs + +Before the meeting: + +- Reconstructed timeline (often the scribe's notes if there was one) +- Logs, chat transcripts, tickets, incident updates +- Individual accounts from each participant (written, before the meeting) +- Impact data (users affected, duration, revenue impact, etc.) + +### 3. Run the meeting + +Typical agenda (60 to 90 minutes): + +- Read the summary as drafted (5 min) +- Walk the timeline together. Add corrections. Resolve disagreements. (20 to 30 min) +- Discuss root cause. Use five whys or causal chain. (15 to 20 min) +- Discuss contributing factors. (10 min) +- Discuss what went well. (10 min) +- Identify action items. Owners and dates. (10 min) + +A facilitator runs the meeting. Often the IC for an incident, or a project lead for a project. The facilitator is not the scribe. + +### 4. Write the document + +Within a few days of the meeting. The full AAR includes all 6 sections. + +### 5. Distribute + +Internal: post in a known location. Make searchable. Reference in onboarding. + +For high-severity incidents: external summary may be appropriate (status page, customer email, public blog). + +### 6. Track action items + +Every action item should be tracked to closure. The next AAR re-surfaces unclosed ones. + +--- + +## Failure patterns + +- Skipping the AAR for "small" incidents. Patterns get missed. +- Naming and shaming. Real lessons get hidden when people fear blame. +- Generic action items. "Improve testing" instead of specific testing change. +- Action items that never close. Filed, forgotten. Same incident recurs. +- Theater retrospectives. Going through the motions without genuine reflection. +- Skipping "what went well." Misses calibration on what's working. +- Blame externalized. "Our vendor failed." OK, what's our system for vendor risk? +- Single-person AAR. One person writes the whole thing. Misses other perspectives. +- AAR only for failures. Successful launches deserve AARs too. Lessons from success are valuable. +- Long delays. Memories fade. Conversations cool. Get it done within 2 weeks. + +--- + +## Output format + +A markdown document at `aar-[date]-[event-name].md`. + +Structure: + +```markdown +# AAR: [Event name] + +Date of event: [YYYY-MM-DD] +AAR date: [YYYY-MM-DD] +Severity / scope: [SEV-1 / Major launch / Project closeout] +Facilitator: [Name] +Participants: [Names] + +## Summary +[2 to 3 paragraphs] + +## Impact +- Users affected: [number, segment] +- Duration: [time] +- Revenue / business impact: [if applicable] + +## Timeline +[Timestamped events] + +## Root cause analysis +[Five whys or causal chain] + +## Contributing factors +[List] + +## What went well +[List] + +## Action items +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +## Lessons +[Reflections that don't fit elsewhere. Often the most quotable section.] +``` + +--- + +## Reference files + +- [`references/aar-template.md`](references/aar-template.md) - Fillable AAR template covering incidents, launches, and projects. diff --git a/skills/after-action-report/references/aar-template.md b/skills/after-action-report/references/aar-template.md new file mode 100644 index 0000000..0d37d24 --- /dev/null +++ b/skills/after-action-report/references/aar-template.md @@ -0,0 +1,296 @@ +# AAR Template + +Fillable after-action report template. Three variations: incident AAR, launch AAR, project closeout AAR. The structure is similar; the inputs and emphasis differ. + +--- + +## Universal sections (used in all three variations) + +### Header + +```markdown +# AAR: [Event name] + +Type: [Incident / Launch / Project] +Date of event: [YYYY-MM-DD or range] +AAR date: [YYYY-MM-DD] +Severity / scope: [SEV-1 / Major launch / Project closeout] +Facilitator: [Name] +Participants: [Names] +Distribution: [Internal only / Internal + customers / Public] +``` + +--- + +## Variation 1: Incident AAR + +### Summary + +> [2 to 3 paragraphs. What happened, what was the impact, what was the root cause, what are the top action items. Should stand alone for executives who read only this section.] + +### Impact + +- Users affected: [Number and segment. "All US users" or "Approximately 12% of paid customers in EU."] +- Duration: [Detection to resolution] +- Severity: [SEV-1 / 2 / 3 / 4] +- Revenue impact: [If quantifiable] +- Customer-facing communication: [What was said, when] +- Regulatory implications: [If any] + +### Timeline + +\| Time \| Event \| Notes \| +\|---\|---\|---\| +\| T-X \| [Pre-incident state, recent deploy, etc.] \| \| +\| T-0 \| [Detection event] \| \| +\| T+5min \| [Acknowledgment] \| \| +\| T+10min \| [Severity assessed, IC assigned] \| \| +\| T+Xmin \| [Investigation milestone] \| \| +\| T+Ymin \| [Mitigation applied] \| \| +\| T+Zmin \| [Verification] \| \| +\| T+Nmin \| [Resolution declared] \| \| +\| T+Hours \| [Customer comms, post-incident] \| \| + +Timeline source: [Logs, chat, monitoring, IC notes] + +### Detection + +- How was it detected? [Alert / customer report / internal observation] +- Time to detection: [From event start to detection] +- Was detection adequate? [Should we have detected this faster? How?] + +### Response + +- Time to acknowledgment: [Detection to acknowledgment] +- Time to mitigation: [Detection to mitigation] +- Time to resolution: [Detection to resolution] +- Were the right people involved? [Yes / No, why] +- Did the response procedure work? [Yes / No, what gaps] + +### Root cause analysis + +Surface symptom: [What users experienced] + +Five whys: + +1. Why did [symptom] happen? [Answer] +2. Why did [Answer 1] happen? [Answer] +3. Why did [Answer 2] happen? [Answer] +4. Why did [Answer 3] happen? [Answer] +5. Why did [Answer 4] happen? [Answer - often the system fix] + +Or, causal chain (multiple contributing factors): + +- Factor 1 (technical): [Description] +- Factor 2 (configuration): [Description] +- Factor 3 (process): [Description] +- Factor 4 (monitoring): [Description] + +### Contributing factors + +What didn't cause this but made it worse, or removed safety nets: + +- [Factor] +- [Factor] +- [Factor] + +### What went well + +- [Detection mechanism that worked] +- [Decision that was correct] +- [Tool that performed as designed] +- [Communication that was effective] + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| [Name] \| [Date] \| Monitoring \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Code \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Process \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Documentation \| Open \| +\| [Specific action] \| [Name] \| [Date] \| Training \| Open \| + +### Lessons + +[Reflections beyond the action items. Often the most-quoted section in the long term.] + +--- + +## Variation 2: Launch AAR + +### Summary + +> [2 to 3 paragraphs. What launched, did it go well, what surprised us, what should we do differently next time.] + +### Outcomes + +- What launched: [Specific scope] +- Launch window: [Planned vs actual] +- Maintenance time: [If applicable] +- Issues during launch: [Count and severity] +- Rollback?: [Yes / No] +- Post-launch incidents: [In the first 7 days] +- Business outcomes: [If measurable, e.g., conversion impact] + +### Timeline + +\| Time \| Event \| Notes \| +\|---\|---\|---\| +\| Pre-launch \| [Major decisions, milestones] \| \| +\| Launch start \| \| \| +\| Cutover steps \| [Each step with timing] \| \| +\| Verification \| \| \| +\| Public announcement \| \| \| +\| First 24 hours \| [Notable observations] \| \| +\| First week \| [Notable observations] \| \| + +### What went according to plan + +- [Step that worked exactly as runbook described] +- [Communication that was clear] +- [Decision that proved correct] + +### What deviated from plan + +- [Deviation, why, what we did] +- [Deviation, why, what we did] + +### What surprised us + +- [Unexpected observation] +- [Unexpected user behavior] +- [Unexpected technical behavior] + +### What we'd do differently + +- [Change to runbook for next launch] +- [Change to pre-launch QA] +- [Change to communication plan] + +### What we'd repeat + +- [Practice that worked, want to keep] + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| \| \| \| \| + +### Lessons + +[Reflections.] + +--- + +## Variation 3: Project closeout AAR + +### Summary + +> [2 to 3 paragraphs. What we set out to do, what we delivered, what we learned, what comes next.] + +### Goals vs outcomes + +\| Goal \| Outcome \| Notes \| +\|---\|---\|---\| +\| [Original goal 1] \| [Met / Partially met / Not met] \| [Notes] \| +\| [Original goal 2] \| [Met / Partially met / Not met] \| [Notes] \| +\| [Original goal 3] \| [Met / Partially met / Not met] \| [Notes] \| + +### Timeline + +\| Phase \| Planned \| Actual \| Variance \| +\|---\|---\|---\|---\| +\| Discovery \| \| \| \| +\| Design \| \| \| \| +\| Build \| \| \| \| +\| QA \| \| \| \| +\| Launch \| \| \| \| + +### What went well + +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] +- [Practice / decision / process that worked] + +### What didn't go well + +- [Pain point with system-level explanation] +- [Pain point with system-level explanation] + +### What surprised us + +- [Surprising input from users / market / internal] +- [Surprising scale / complexity / opportunity] + +### What we'd do differently + +For people working on similar projects in the future: + +- [Specific change] +- [Specific change] +- [Specific change] + +### Decisions in retrospect + +\| Decision \| Was it right? \| Why or why not \| +\|---\|---\|---\| +\| [Major decision 1] \| \| \| +\| [Major decision 2] \| \| \| +\| [Major decision 3] \| \| \| + +### Action items + +\| Action \| Owner \| Due \| Type \| Status \| +\|---\|---\|---\|---\|---\| +\| [Specific action] \| \| \| \| \| + +### Lessons + +[Reflections.] + +### Recommendations for next phase + +[If the project continues. Otherwise, recommendations for what builds on this work.] + +--- + +## Universal facilitator guide + +### Before the meeting (pre-work) + +- Send the timeline draft to all participants +- Ask each participant to write their personal account of what they observed and did (1 to 2 paragraphs each) +- Compile contributing data: logs, metrics, ticket counts, customer feedback +- Send participants the agenda 24 hours in advance + +### During the meeting + +- Set the tone in the first 60 seconds: "This is blameless. Focus on systems, not individuals." +- Walk the timeline. Add corrections from participants. +- For root cause: ask "why" until the answers stop being substantive. Note when it shifts from technical to process. +- For action items: insist on specificity, owner, date. +- Don't let the meeting become a debugging session. Investigation happened before; this is for analysis. +- Capture the document live where possible. Edits in real time prevent recall errors. + +### After the meeting + +- Polish the document within 48 hours +- Distribute to broader audience +- File action items into a tracking system +- Schedule follow-up to verify action items closed (typically 30 days out) + +--- + +## Common AAR anti-patterns + +\| Anti-pattern \| What it looks like \| Better \| +\|---\|---\|---\| +\| Naming and shaming \| "Sarah deployed the bug" \| "Our review process didn't catch the issue. Why? What checklist or test would have?" \| +\| Generic actions \| "Improve testing" \| "Add a test for X scenario to the existing test suite by [date]" \| +\| No follow-through \| Action items filed, never tracked \| Action item review at next AAR; pattern of unclosed items surfaces \| +\| Skipping success \| Only failures discussed \| Equal time to what went well \| +\| Sole authorship \| One person writes the AAR \| Group discussion + sole author for polish \| +\| Long delay \| AAR happens 2 months later \| AAR within 2 weeks of event \| +\| Skipping minor incidents \| "Not worth the time" \| Patterns hide in the minors \| diff --git a/skills/ai-content-collaboration/SKILL.md b/skills/ai-content-collaboration/SKILL.md new file mode 100644 index 0000000..d04119e --- /dev/null +++ b/skills/ai-content-collaboration/SKILL.md @@ -0,0 +1,281 @@ +--- +name: ai-content-collaboration +description: "How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy." +category: content +catalog_summary: "How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production" +display_order: 8 +--- + +# AI Content Collaboration + +A senior editorial leader's playbook for how humans and AI compose in content workflows. Pragmatic, tool-agnostic, honest about both what AI in the loop enables and what it threatens. + +Most content programs in 2026 use AI somewhere in the workflow. Pretending otherwise is dishonest; treating AI as a magic content factory is the failure mode this skill exists to prevent. The discipline is in between: knowing where AI legitimately accelerates, where humans must own, what hybrid patterns produce work that earns reader trust, and what crosses the line into AI slop or intellectual dishonesty. + +This skill is the WORKFLOW layer that composes with every other content skill. Briefs can be AI-assisted; hub architectures can be AI-assisted; programmatic SEO is almost always AI-involved; editorial QA now includes AI-content audit by necessity. The collaboration discipline applies to all production stages, not to a single artifact type. + +The voice is pragmatic and tool-agnostic deliberately. The methodology applies whether the AI in your loop is one of the major commercial models, an open-source model, or whatever ships next quarter. What stays constant is the workflow shape, the participation boundaries, the voice ownership question, and the ethical frame. What changes is which specific tool you reach for, which is implementation work that varies by team and budget. + +When to use this skill: building or refining an AI-content workflow, calibrating a team on consistent AI usage, addressing the "we use AI but our work feels generic" problem, designing disclosure policies, or working through the ethics of AI-assisted content production for a regulated or trust-sensitive context. + +--- + +## What this skill is for + +This skill spans the workflow layer of AI-assisted content production. It composes with all six other content-suite skills as the cross-cutting discipline. + +- `content-strategy` is program scope: what to produce. Strategy decisions can be AI-assisted; the program-level judgment stays human. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. Hub architecture can be AI-suggested; the architectural commitment stays human. +- `content-brief-authoring` is per-piece scope: briefs each piece. Briefs can be AI-drafted from research; the contract decisions stay human. +- `content-and-copy` is execution scope: writes each piece. Drafts can be AI-produced; voice and editorial judgment stay human. +- `programmatic-seo` is scaled scope: generates pages from data. AI generation is the dominant production model; sampling QA is the human gate. +- `editorial-qa` is gate scope: verifies before publish. AI-content audit is now a load-bearing gate; the audit's judgment stays human. +- This skill is workflow scope: how the human and AI layers compose across all six stages above. + +The audience: editorial leaders, content directors, content ops managers, agencies running AI-assisted production, in-house teams calibrating AI usage across writers. The voice is senior editorial leader to junior editor or content marketer. Pragmatic, honest, tool-agnostic. + +What is not in scope: specific prompts (those are implementation; teams develop their own), specific tool endorsements (the methodology applies regardless of which tool is in the loop), specific integration code (varies by stack and team). Tool categories appear when they earn methodology relevance; specific tools appear only as illustrations of categories, never as recommendations. + +--- + +## Humans own, AI accelerates + +The keystone framing. + +The pathology to avoid is treating AI as either a magic content factory (cheap, fast, scaled, output quality optional) OR as a forbidden intruder (purity gospel that does not survive contact with deadlines). Both readings produce bad work. + +The discipline that produces durable work: humans own the content; AI accelerates the work. Specifically: + +Humans own. Editorial judgment, voice, distinctive POV, fact accuracy, ethical decisions, what to publish versus what to kill, brand voice, narrative arc, tone calibration, reader empathy, claim verification. + +AI accelerates. Research synthesis, draft generation against a brief, copy edit suggestions, alternative phrasings, summary, transcription, quality-control automation at scale. + +The line. AI does work that the human directs and verifies. AI does NOT make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +The litmus test. If your AI-assisted piece publishes without a human being able to defend every claim, every position, and every word, you have crossed the line. The piece is AI's work, dressed in your byline. Readers eventually notice. + +--- + +## Where AI legitimately participates + +A non-exhaustive list of stages where AI in the loop is fine and often improves the work. + +- Research synthesis. AI condenses long-form sources into briefs the writer reads. Saves hours; the writer still reads and verifies. +- Outline generation against a brief. AI proposes an H2 / H3 structure from a brief; the editor approves or restructures. +- First-draft generation. AI produces a draft against an explicit brief; the human edits substantially. +- Alternative phrasings. AI offers 3 versions of a sentence; the human picks one or rewrites. +- Copy edit suggestions. AI catches typos, awkward phrasings, repetition. +- Summary and abstraction. AI condenses long pieces into TL;DRs. +- Transcription. AI transcribes interview audio; the human verifies. +- Translation drafts. AI produces a translation draft; a native speaker reviews and corrects. +- Quality-control automation at scale. AI flags pages in a programmatic SEO set that need human review. +- Idea generation. AI proposes 30 angles; the human picks 3. + +In each case, AI accelerates work the human still owns. The acceleration is real; the ownership stays unchanged. + +Detail in [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md). + +--- + +## Where humans must own + +The boundary list. + +- Editorial judgment. What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. +- Voice. Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution. +- Fact verification. Every claim, every statistic, every quote, every named person. AI hallucinates; humans verify. +- Ethical decisions. What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. +- Reader empathy. What the reader actually needs from this piece, not what the algorithm scores well. +- Quote attribution. Real people who actually said the thing, with consent where relevant. +- Tone calibration on hard topics. Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. +- Narrative arc. How the piece unfolds, where the reader's attention goes. AI produces shapes; humans choose them. +- Final approval. The human who signs off is accountable for what shipped. + +The "human in the loop" framing is necessary but insufficient. A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. Ownership requires the human to have made the actual decisions the piece embodies. + +--- + +## Hybrid workflow patterns + +Five patterns that work, with tradeoffs. + +1. AI-first draft, human-edit-heavy. AI produces a 90% draft; the human spends 60% of the time editing. Output: efficient for high-volume editorial; risks generic voice if editing is light. + +2. Human-first outline + research, AI-draft, human-rewrite. Human builds the outline and gathers research; AI drafts within that scaffold; human rewrites in voice. Output: preserves voice better; slower than AI-first. + +3. AI-as-research-assistant, human-writes. AI condenses sources into a brief; human writes the entire piece from the brief. Output: highest voice fidelity; slowest. + +4. Human-writes, AI-as-editor. Human drafts; AI suggests edits, alternative phrasings, copy edits; human accepts or rejects. Output: writer voice preserved; AI catches details. + +5. AI-generates-at-scale, human-samples. For programmatic SEO. AI generates thousands of pages; human samples 50 to 200 with editorial-qa discipline. Output: scaled production; depends entirely on template quality and sampling discipline. + +The pattern that fits depends on volume, voice sensitivity, team skill, and time budget. No pattern is "the right one"; pattern selection is a real decision that should match the production context. + +Detail in [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md). + +--- + +## Voice ownership preservation + +Voice is the dominant casualty of careless AI workflows. The patterns that preserve voice. + +- Voice guidelines as prompt input. Every AI generation includes the brand voice guidelines as context. Generic AI defaults regress without this. +- Sample text as voice anchor. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. +- Mid-draft voice check. At the halfway mark of a long piece, have a human or a separate AI pass read for voice drift. Long AI generations regress halfway through almost always. +- Final pass in human voice. The human edits the closing sections in their own voice; this is where the piece's emotional register often lands. +- Reject the bland. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The honest framing. Voice is the hardest thing to preserve in AI-assisted work and the easiest thing to lose. Programs that do not actively preserve voice end up with content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +Detail in [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md). + +--- + +## The AI slop problem + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. Cross-reference `editorial-qa`'s ai-content-audit-patterns reference for the detection patterns; this section addresses prevention. + +Patterns that produce slop. + +- AI does too much of the work (no real human direction or rewriting) +- Generic prompts (no brand voice context, no audience specificity, no anti-pattern guidance) +- No editorial judgment in the loop (AI generates, human glances, ship) +- Volume prioritized over quality (10x more pages can mean 10x more slop, not 10x more value) +- No iteration (first draft ships; no rewrite for voice) + +Patterns that prevent slop. + +- Strong briefs (per `content-brief-authoring`) +- Voice guidelines as prompt context +- Heavy human editing pass +- Iteration: AI draft, then human rewrite, then AI suggestions, then human final +- Editorial judgment at every gate + +The reader-detection problem. Readers can often sense AI-flavored content even when they cannot articulate why. Generic openings, predictable structures, "perfect" grammar that is emotionally flat. Slop loses reader trust over time even when individual pieces are not penalized. + +Detail in [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) and cross-reference editorial-qa's audit patterns. + +--- + +## Disclosure and transparency + +When should AI usage be disclosed to readers? + +The tiered framework. + +- Always disclose. Journalism, news reporting, attributed expert opinion, content where AI tools are the subject. +- Default disclosure (consider context). Thought leadership where the byline is doing trust work, regulated industries, content that influences purchase decisions. +- Generally not necessary. Marketing copy, descriptive product content, programmatic data pages, copy edit assistance only. +- Clearly fine without disclosure. AI as research assistant only; AI for transcription; AI for spelling and grammar suggestions. + +The principle. Disclose when the reader's understanding of the content's origin would change their trust in it. A bylined opinion piece purportedly by a named expert that is substantially AI-drafted is a trust violation; a product description on an ecommerce site that was AI-drafted is not. + +Disclosure language patterns (when used). + +- "AI tools assisted in research and drafting; the author edited and verified all claims." +- "This piece was generated programmatically from [data source]; reviewed by [team] before publish." +- Avoid hedging language like "may have used AI" or "could have been AI-assisted"; be specific or omit. + +Industry-specific norms vary. Major journalism organizations have published explicit AI usage standards. Content marketing has weaker norms but is moving toward disclosure for high-trust pieces. + +Detail in [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md). + +--- + +## Team training and calibration + +Inconsistent AI usage across a team produces inconsistent output. The discipline. + +- Documented AI policy. Which uses are approved, which require explicit permission, which are prohibited. +- Calibration sessions. Editors review AI-assisted pieces from multiple writers, surface differences, agree on standards. +- Voice library updates. As voice evolves, the prompts and sample text fed to AI evolve with it. +- Quality benchmarks. What does "AI-assisted but on-voice" look like for your brand? Document it with examples. +- Tool standardization or intentional pluralism. Team uses one tool consistently OR documents which tools fit which tasks. +- Forbidden patterns list. This team does not use AI for X (whatever X is for your context). +- Onboarding. New writers learn the AI policy and calibration in their first 2 weeks. + +The pathology. AI usage emerges informally, every writer develops their own patterns, output drifts, editors cannot pinpoint why pieces feel off. The discipline is making AI usage explicit, calibrated, and documented. + +Detail in [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md). + +--- + +## Ethics: training data, attribution, intellectual honesty + +AI tools were trained on copyrighted material. That is the simple ethical reality of every major LLM in 2026. The catalog's position on this question is not "AI use is unethical" (that would render the catalog itself hypocritical) but "intellectual honesty about AI involvement is non-negotiable." + +The principles. + +- Do not pass AI work as fully human-written. Bylined content where the byline implies human craft requires substantial human craft. +- Do not claim AI did not help when it did. False denials are worse than disclosure. +- Do not generate content that closely mirrors copyrighted source material. AI tools can produce near-replicas of training data when prompted carelessly; humans verify originality. +- Attribute when borrowing. Ideas, frameworks, statistics that came from specific sources get cited. +- Do not fabricate quotes or expertise. Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. +- Be honest about AI capabilities and limits. Do not oversell AI as more capable than it is. + +The intellectual-honesty frame supersedes any specific policy debate. Teams that treat AI usage with intellectual honesty produce content readers can trust over time. Teams that hide, deny, or rationalize lose trust eventually. + +Detail in [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md). + +- "We used AI and the content feels generic." Voice not preserved; not enough human rewriting. +- "Hallucinated facts made it to publish." Fact-verification gate skipped or rushed. +- "Different writers produce wildly different AI-assisted output." No team calibration. +- "Our AI-assisted SEO content got penalized." Slop volume plus thin templates plus no QA discipline. +- "We cannot tell what was AI versus human." No AI usage tracking; teams should document at the workflow level. +- "Readers complained about AI-flavored content." Slop reaching audience; intensify human craft pass. +- "We disclosed AI usage and lost credibility." Depends on context; disclosure is sometimes a trust gain, sometimes a loss; calibrate to audience norms. +- "Our AI tools changed and our content shifted." Over-coupled to one tool's specific behavior; methodology should be tool-agnostic. +- "We are producing 10x more content but the same audience growth." Volume was not the constraint that was binding; quality was. +- "The team is using AI inconsistently." Calibration sessions overdue. +- "An expert byline turned out to be substantially AI-drafted." Ethics breach; correct, disclose, recalibrate. + +--- + +## The framework: 12 considerations for AI content collaboration + +When designing or auditing an AI-assisted content workflow, walk these 12 considerations. + +1. Humans own; AI accelerates. Make this explicit in your workflow, not implicit. +2. Participation boundaries. Document where AI legitimately helps, where humans must own. +3. Hybrid pattern selection. Match the pattern to volume, voice sensitivity, time budget. +4. Voice guidelines as prompt input. Every AI generation includes brand voice context. +5. Voice drift sampling. Long pieces drift mid-way; sample throughout. +6. Fact verification gate. Every claim, every quote, every stat verified before publish. +7. AI slop prevention. Heavy human editing, strong briefs, iteration. +8. Disclosure tiering. Disclose when origin would change reader trust; calibrate to audience. +9. Team calibration. Documented policy, calibration sessions, voice library. +10. Tool-agnostic methodology. Workflow shape stays constant as tools change. +11. Ethical floor. Intellectual honesty, no fabrication, no hidden AI in trust-sensitive work. +12. Final accountability. The human who signs off is accountable; AI does not sign off. + +The output of the framework is a workflow document the team can reference: AI participation rules named, hybrid pattern selected, voice preservation patterns specified, disclosure tier set, calibration cadence committed, ethical floor articulated, accountable signer named for each piece. + +--- + +## Reference files + +- [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md) - Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. +- [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md) - Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. +- [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md) - Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. +- [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) - What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. +- [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md) - Tiered disclosure framework, language patterns, industry norms. +- [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md) - Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. +- [`references/quality-calibration-with-ai-in-loop.md`](references/quality-calibration-with-ai-in-loop.md) - How editorial standards shift when AI is in the workflow. Same standards, different failure modes. +- [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md) - Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. +- [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: collaboration, not replacement + +AI in content workflows is neither magic nor menace. It is a category of tooling that, like every tooling category before it, rewards disciplined use and punishes careless use. The teams producing memorable AI-assisted content are the ones holding the line on human ownership, voice, fact accuracy, and intellectual honesty. The teams producing AI slop are the ones treating AI as a content factory. + +The discipline is not anti-AI; it is pro-craft. Craft was always what made content worth reading; AI does not change that, it just raises the cost of skipping it. + +When in doubt about whether an AI-assisted workflow is ready, ask: is human ownership specified, are participation boundaries documented, is voice preservation built into the prompt and review patterns, is fact verification a halt-condition, is disclosure tiered to audience trust, is the team calibrated, and is the ethical floor explicit? If yes to all of those, the workflow is ready. If no to any, the gap is where the program will produce slop and lose reader trust. diff --git a/skills/ai-content-collaboration/references/ai-participation-boundaries.md b/skills/ai-content-collaboration/references/ai-participation-boundaries.md new file mode 100644 index 0000000..0d6b20a --- /dev/null +++ b/skills/ai-content-collaboration/references/ai-participation-boundaries.md @@ -0,0 +1,131 @@ +# AI participation boundaries + +Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction. + +The boundary list below is the operational expression of the keystone framing: humans own the content, AI accelerates the work. The list is not exhaustive; the principle is: AI does work the human directs and verifies, AI does not make decisions about what publishes, who is quoted, what is true, or what voice the brand uses. + +--- + +## Where AI legitimately participates + +### Research synthesis + +AI condenses long-form sources (papers, interviews, prior reports, internal docs) into a research brief. The writer reads the brief, follows up on the citations the brief surfaced, and verifies anything that will become a load-bearing claim in the piece. + +The acceleration: hours of reading become minutes of reviewing. The retained ownership: the writer judges what is worth using, where the source is questionable, what additional research is needed. + +### Outline generation against a brief + +AI proposes an H2 / H3 structure based on the content brief and SERP analysis. The editor approves the outline, restructures it, or rejects it. + +The acceleration: the writer starts from a structure that fits the brief instead of from a blank page. The retained ownership: the editor decides whether the structure fits the audience and the publication. + +### First-draft generation + +AI produces a draft against an explicit brief. The human edits substantially. + +The acceleration: a 1,500-word draft in minutes that the human revises rather than composing from scratch. The retained ownership: the human chooses what to keep, what to rewrite, what to cut, what to add. A draft that ships unchanged is not collaboration; it is rubber-stamping. + +### Alternative phrasings + +AI offers 3 versions of a sentence, paragraph, or headline. The human picks one or rewrites. + +The acceleration: faster surfacing of options the writer might not have considered. The retained ownership: the writer chooses the option that fits the voice and the context. + +### Copy edit suggestions + +AI catches typos, awkward phrasings, repetition, weak connections between paragraphs. + +The acceleration: faster than a manual copy edit pass. The retained ownership: the editor decides which suggestions to accept; some of what AI flags as awkward is actually deliberate stylistic choice. + +### Summary and abstraction + +AI condenses long pieces into TL;DR summaries, executive summaries, or social media captions. + +The acceleration: faster TL;DR generation; useful for content systems that produce summaries at scale. The retained ownership: the human verifies the summary captures what matters and does not flatten the piece's distinctive points. + +### Transcription + +AI transcribes interview audio. The human verifies the transcription against the audio for accuracy, especially on names, technical terms, and quoted positions. + +The acceleration: hours of transcription become minutes of verification. The retained ownership: the human is responsible for what gets attributed; transcription errors that misquote sources are the human's accountability to catch. + +### Translation drafts + +AI produces a translation draft. A native speaker reviews and corrects. + +The acceleration: a translation starting point in seconds. The retained ownership: the native speaker is the source of truth on idiomatic correctness, cultural context, and brand-voice translation. + +### Quality-control automation at scale + +AI flags pages in a programmatic SEO set that need human review (per `editorial-qa`'s sampling discipline). + +The acceleration: automated check on every page; manual review focused on the flagged subset. The retained ownership: the editor decides what counts as a fail; the AI flags candidates, the human judges. + +### Idea generation + +AI proposes 30 angles on a topic; the human picks 3. + +The acceleration: faster brainstorm. The retained ownership: the human chooses which angles fit the brand and the audience. + +--- + +## Where humans must own + +### Editorial judgment + +What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. The judgment requires audience knowledge, brand context, and quality standards the AI does not have. + +### Voice + +Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution that the AI can mimic if shown samples but cannot originate. + +### Fact verification + +Every claim, every statistic, every quote, every named person. AI hallucinates plausible-but-fake claims; humans verify against authoritative sources. Fact verification is a halt-condition gate; pieces with unverified claims do not ship. + +### Ethical decisions + +What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. Ethics requires context, audience awareness, and accountability that the AI does not carry. + +### Reader empathy + +What the reader actually needs from this piece, not what the algorithm scores well. The reader's situation, knowledge, and emotional context shape the piece's job; the AI cannot model the specific reader the way a writer who has spent time with the audience can. + +### Quote attribution + +Real people who actually said the thing, with consent where relevant. AI hallucinates quotes; humans verify against the source. + +### Tone calibration on hard topics + +Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. A piece on bereavement should not read as if a chatbot wrote it. + +### Narrative arc + +How the piece unfolds, where the reader's attention goes, what the climax is, what the resolution is. AI produces shapes; humans choose them. + +### Final approval + +The human who signs off is accountable for what shipped. Accountability cannot be delegated to AI; the byline and the editorial chain stop at humans. + +--- + +## "Human in the loop" is not ownership + +The phrase "human in the loop" appears in many AI workflows. It is necessary but insufficient. + +A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. The piece's substance, voice, and judgment are still AI-produced; the human's role is signature only. + +Ownership requires the human to have made the actual decisions the piece embodies. Specifically: the human chose the angle, the human verified the facts, the human enforced the voice, the human made the editorial judgment calls that distinguish this piece from the AI's default output. + +The test. Could the human defend every claim, every position, and every word in the piece? If yes, the human owns it. If no, the human is rubber-stamping. + +--- + +## Methodology-level choices that stay in the public skill + +The list of where AI legitimately participates, the list of where humans must own, the "human-in-the-loop versus ownership" distinction, the verification-and-defense litmus test. + +## Implementation choices that stay internal + +The specific AI tools the team uses for each participation category (research synthesis tool, drafting tool, copy edit tool, transcription tool, translation tool, QC automation tool). The specific prompts the team has developed for each task category. The specific tracking system that records which AI participated in which piece. The specific review workflows that gate publish. These vary by team and stack. diff --git a/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md b/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md new file mode 100644 index 0000000..4e3df19 --- /dev/null +++ b/skills/ai-content-collaboration/references/ai-slop-detection-and-avoidance.md @@ -0,0 +1,134 @@ +# AI slop detection and avoidance + +What produces slop, what prevents it. Cross-references editorial-qa's audit patterns. + +AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. The detection patterns live in `editorial-qa/references/ai-content-audit-patterns.md`. This reference addresses prevention: what production patterns produce slop, what production patterns prevent it. + +--- + +## Patterns that produce slop + +### AI does too much of the work + +The pattern. The AI generates the entire piece; the human glances at it and ships. The piece reads as model-default because no human substantively rewrote it. + +The signal. Pieces ship in less time than they would take a human to write from scratch. Speed is not the problem; the problem is that the speed comes from skipped craft. + +### Generic prompts + +The pattern. The prompt is "write a 1,500-word blog post about X." No brand voice, no audience specificity, no anti-pattern guidance. The AI generates the most common kind of post about X, which is by definition generic. + +The signal. Prompts can fit in one sentence. Prompts that produce on-voice output are typically multi-paragraph, with voice guidelines, sample text, audience description, and anti-pattern lists. + +### No editorial judgment in the loop + +The pattern. The workflow is "AI generates, human reviews quickly, ship." The reviewer is not making editorial decisions; they are spell-checking. Whether the piece is good enough to publish, whether it answers the user's actual question, whether it reflects brand POV are not asked. + +The signal. The team cannot articulate the editorial judgments made on a piece because those judgments did not happen. Pieces ship with no halt-decisions, no rewrites, no "this piece does not work, kill it" calls. + +### Volume prioritized over quality + +The pattern. The team commits to publishing 50 pieces a month with the same headcount that previously produced 10. AI is the multiplier. Quality drops because the production line cannot sustain craft at the new volume. + +The signal. Publish targets defined in pieces-per-week or pages-per-month. Quality-controlled publish targets are defined differently: traffic earned, citations earned, leads converted, audience grown. Volume targets without quality targets produce slop volume. + +### No iteration + +The pattern. First draft (AI-generated) ships. No revision pass. No second draft. No "let us read this aloud and rewrite the bland sections." + +The signal. The workflow document does not include a rewrite step. Production is generation-then-publish, not generation-then-iteration-then-publish. + +--- + +## Patterns that prevent slop + +### Strong briefs + +Per `content-brief-authoring`. A brief that fills all 12 fields gives the AI enough context to produce a draft that respects audience, voice, structure, entity coverage, and success criteria. Vague briefs produce slop output regardless of how the AI is prompted. + +The discipline. Brief-adherence is the first QA gate per `editorial-qa`. AI drafts that fail brief-adherence get returned, not rubber-stamped. + +### Voice guidelines as prompt context + +Per `voice-ownership-preservation.md`. Every AI generation includes the brand voice guidelines and sample anchor text as prompt input. Without active voice prompting, AI defaults dominate. + +### Heavy human editing pass + +The discipline. The human spends substantial time editing AI drafts: rewriting flat sentences, replacing abstractions with specifics, restoring brand voice in mid-piece sections, replacing generic openings and closings with specific ones. + +The time investment. 50 to 60% of the piece's production time goes to human editing in Pattern 1 (AI-first draft, human-edit-heavy). Lower than that and the editing is light; the piece ships with AI defaults preserved. + +### Iteration + +The discipline. The workflow includes multiple revision passes: AI draft, then human rewrite, then AI suggestions for the rewrite, then human final pass. Each pass catches a different layer. + +- AI draft: structure, completeness, basic prose. +- Human rewrite: voice, specificity, claim verification, distinctive POV. +- AI suggestions: copy edit catches, alternative phrasings, repetition flagging. +- Human final: closing voice, emotional register, final polish. + +The pattern produces work that reads as human-crafted with AI assistance. Skip any pass and the piece moves toward AI default. + +### Editorial judgment at every gate + +The discipline. Each QA gate is a judgment moment, not a rubber stamp. Brief-adherence asks "did this piece execute the brief?" Voice consistency asks "does this sound like our brand?" Fact accuracy asks "is every claim verified?" Each question requires a human's actual judgment. + +The signal of editorial judgment in action. Halts happen. Pieces get sent back for revision. Some pieces get killed because they cannot be made to work. Programs that publish 100% of what they draft are not exercising editorial judgment; they are producing whatever the workflow ships. + +--- + +## The reader-detection problem + +Readers can often sense AI-flavored content even when they cannot articulate why. The signals. + +- Generic openings that could be the opening of any article on the topic +- Predictable structure (intro, three points, conclusion) +- Bullet-list overuse where prose would serve +- "Perfect" grammar that reads as emotionally flat +- Specific-but-fake details (named decimals, named sources that turn out to be fake) +- Hedge stacking that avoids commitment + +Slop loses reader trust over time even when individual pieces are not penalized by algorithm updates. Readers stop returning. Email open rates drop. Citation quality declines. The traffic numbers may hold for a year before the trust loss compounds visibly. + +The implication. Slop is not a search-engine problem; it is a reader-trust problem. Programs that optimize away from slop because of algorithm fear are missing the bigger reason: readers stop trusting the brand. + +--- + +## The slop avoidance audit + +For each AI-assisted piece, ask the following before publish. + +1. Could this piece have been published by any competitor using the same tools? If yes, the voice is not preserved. +2. Are the claims in this piece specific enough to verify? If no, the piece is hedging. +3. Does the piece take a position the reader will remember? If no, the piece is forgettable. +4. Did the human substantially rewrite, or is the AI draft mostly intact? If mostly intact, the piece is at slop risk. +5. Does the closing read as the writer's own voice? If no, the final pass was skipped. +6. Did the brief adhere to the 12-field discipline? If no, the failure is upstream. + +A piece that fails 3+ of these is slop-shaped. Halt and revise. + +--- + +## The "we are producing 10x more content but the same audience growth" pattern + +A common signal that slop has set in. The volume increased; the audience metric did not. The team often interprets this as "we need even more content"; the diagnosis is usually the opposite. + +The actual diagnosis. Volume was not the constraint. Quality was. The 10x content production has produced 10x slop, which earns less per piece and sometimes hurts the brand's overall trust signal. + +The fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## Cross-reference + +The detection patterns (AI tells, hallucination patterns, voice drift) live in `editorial-qa/references/ai-content-audit-patterns.md`. The avoidance patterns (production discipline) live here. The two skills compose: editorial-qa catches what reaches the gate; this skill prevents production patterns that produce slop in the first place. + +--- + +## Methodology-level choices that stay in the public skill + +The patterns that produce slop, the patterns that prevent slop, the reader-detection observation, the 6-question slop avoidance audit, the volume-vs-quality counter-intuition, the cross-reference to editorial-qa. + +## Implementation choices that stay internal + +The specific iteration loop the team runs (AI draft to human rewrite to AI suggestions to human final, or variations). The specific time-tracking that captures the editing-time-to-generation-time ratio. The specific prompt patterns that include voice guidelines and sample text. The specific reader-feedback channels that surface slop perception. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/common-collaboration-failures.md b/skills/ai-content-collaboration/references/common-collaboration-failures.md new file mode 100644 index 0000000..cfabbca --- /dev/null +++ b/skills/ai-content-collaboration/references/common-collaboration-failures.md @@ -0,0 +1,165 @@ +# Common collaboration failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: the team treated AI as either a magic content factory (producing slop at scale) or as a pure-replacement-or-nothing question (producing inconsistent output as writers privately negotiated their own AI usage). The discipline is in between: humans own, AI accelerates, the workflow is documented, the team is calibrated. + +--- + +## "We used AI and the content feels generic" + +Symptom. Pieces ship technically clean but feel indistinguishable from competitors using the same tools. Audience growth flat despite consistent publishing. + +Diagnosis. Voice not preserved. Editing was light; AI defaults reached publish. The pattern that produces this: AI-first drafts with a quick review pass that catches typos but does not rewrite for voice. + +Fix. Apply the voice ownership preservation patterns (`voice-ownership-preservation.md`): voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland audit. Increase editing intensity to 50-60% of production time. + +--- + +## "Hallucinated facts made it to publish" + +Symptom. A statistic, quote, citation, or product claim in a published piece turns out to be invented. + +Diagnosis. Fact-verification gate skipped or rushed. The team trusted AI output that read as authoritative. + +Fix. Fact-accuracy as halt-condition gate per `editorial-qa/references/fact-accuracy-and-citation-discipline.md`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +--- + +## "Different writers produce wildly different AI-assisted output" + +Symptom. Two writers given the same brief and the same AI tools produce pieces that read as if they came from two different programs. + +Diagnosis. No team calibration. Each writer developed their own AI patterns; the program drifted as different patterns produced different output shapes. + +Fix. Documented AI policy, calibration sessions, voice library, quality benchmarks per `team-training-and-calibration.md`. Onboarding for new writers includes calibration. + +--- + +## "Our AI-assisted SEO content got penalized" + +Symptom. A programmatic SEO set or a high-volume editorial program loses 60-90% of traffic in an algorithm update. + +Diagnosis. Slop volume plus thin templates plus no QA discipline. The set was generating filler pages with limited human direction; the algorithm update detected the scale-without-substance pattern. + +Fix. Halt new generation. Apply QA at scale per `editorial-qa/references/qa-at-scale-patterns.md`. Sampling discipline with 5% failure threshold. Noindex pages that fail the data-depth threshold. Possibly remove the entire pSEO surface and rebuild from a stronger data source. + +--- + +## "We can't tell what was AI vs human" + +Symptom. Asked to characterize AI usage on a specific piece, the team cannot answer. Workflow logs, CMS metadata, and writer recall all yield uncertain answers. + +Diagnosis. No AI usage tracking. The workflow does not capture which AI participated in which stage. + +Fix. Add AI involvement tracking to the production workflow. The metadata captures: which workflow pattern was used, which AI tools were involved, which stages, which prompts (or prompt template versions), which human made which decisions. The tracking is the input to retrospective audits and to disclosure decisions. + +--- + +## "Readers complained about AI-flavored content" + +Symptom. Direct audience feedback (comments, support tickets, social mentions) flags content as feeling AI-generated. + +Diagnosis. Slop reaching the audience. Reader detection is real even when the team's QA does not catch it. + +Fix. Intensify the human craft pass. Audit recent pieces against the slop avoidance audit (`ai-slop-detection-and-avoidance.md`). If multiple pieces fail the audit, the production patterns need to shift: heavier human editing, more rejection-of-bland, possibly pattern shift from AI-first to AI-as-editor for higher-trust content. + +--- + +## "We disclosed AI usage and lost credibility" + +Symptom. Team added AI disclosure to a piece; audience response shifted negative. + +Diagnosis. Could be either: + +- The disclosure was for content where audience norms expect human authorship (Tier 1 or Tier 2 content per the disclosure framework); disclosure was correct but audience trust calibration is moving slowly +- The disclosure language was hedging or defensive, signaling lower commitment than direct authorship would have +- The disclosure was for content where it was unnecessary (Tier 4); the disclosure created an issue where there was none + +Fix. Calibrate disclosure to audience norms per `disclosure-and-transparency-patterns.md`. Specific language matters; defensive language reads worse than no disclosure. Consider audience-research feedback to inform per-content-type disclosure tiering. + +--- + +## "Our AI tools changed and our content shifted" + +Symptom. Team updates the AI tool or model version. Output behavior changes. Content quality shifts before the team recalibrates. + +Diagnosis. Over-coupled to one tool's specific behavior. The methodology should be tool-agnostic; the team's prompts and patterns should produce similar output across tools. + +Fix. Methodology-first calibration. The voice library, prompt templates, and quality benchmarks should be portable across tools. After tool changes, run a calibration session against the new tool to verify the methodology still produces on-voice output. If the methodology no longer works, that is a signal the methodology was over-coupled to tool-specific behavior. + +--- + +## "We're producing 10x more content but the same audience growth" + +Symptom. Team committed to a 10x content target enabled by AI. Volume hit the target. Audience growth flat or declining. + +Diagnosis. Volume was not the constraint that was binding. Quality was. The 10x volume produced 10x slop, which earns less per piece. + +Fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months. + +--- + +## "The team is using AI inconsistently" + +Symptom. Team members use different AI tools in different patterns for the same kind of work. Output varies by who picked up the assignment. + +Diagnosis. Calibration sessions overdue. Either the policy is informal (no documented standards) or the documented policy has not been reinforced through calibration. + +Fix. Quarterly calibration sessions. Tool standardization (or intentional pluralism with documented selection criteria). Onboarding refresh. The cadence is calendar-anchored. + +--- + +## "An expert byline turned out to be substantially AI-drafted" + +Symptom. A piece bylined by a named expert is publicly identified as substantially AI-drafted (sometimes by AI-detection tools, sometimes by readers familiar with the expert's actual voice). + +Diagnosis. Ethics breach. The byline implied human authorship; AI authorship was substantive; the gap between claim and reality reached the audience. + +Fix. Two parts. + +- Immediate. Correct the published piece (issue an editor's note clarifying the workflow, possibly retract and republish with appropriate disclosure). Apologize where appropriate. Recalibrate. +- Process. Restore the ethical floor: bylined expert content requires substantial human authorship. Recalibrate the team. Update the AI policy to document the floor explicitly. + +The fix is not "stop using AI." The fix is using AI consistently with the byline's implied authorship. + +--- + +## "Our AI policy is 18 months stale and references tools we no longer use" + +Symptom. Team consults the AI policy doc; the doc references tools the team migrated away from a year ago. The doc is treated as not authoritative because it is obviously dated. + +Diagnosis. Policy review cadence has slipped. The doc has not been updated as tools, capabilities, and team practices have evolved. + +Fix. Quarterly policy review. Each quarter the policy gets reviewed against current practice; updates ship; the team is briefed on the changes. The policy is a living document; staleness signals process failure. + +--- + +## "The team feels guilty about AI use but uses it anyway" + +Symptom. Team members use AI substantively but do not document, do not discuss in calibration sessions, do not include in retrospectives. AI usage is treated as something to hide. + +Diagnosis. The team has not articulated its AI ethics. Without articulation, individual writers privately negotiate their own ethics; the team accumulates ethical debt. + +Fix. Run an ethics conversation explicitly. Articulate the team's position on the six ethical floors per `ethics-and-intellectual-honesty.md`. Document where AI is used substantively. Make the workflow visible. Guilt is usually a signal of unresolved ethical questions; the resolution is articulation, not avoidance. + +--- + +## The pattern across all failures + +Most AI-collaboration failures reduce to two patterns. + +1. The team treated AI as a magic content factory. Outcome: slop, hallucinations, voice loss, audience trust decline. +2. The team failed to articulate its AI workflow explicitly. Outcome: drift, inconsistency, ethics debt, calibration failures. + +The fix in both cases is the same: explicit articulation of where AI participates, where humans own, what the discipline looks like in practice, and what the team's ethical floors are. The articulation is the work; once the work is done, individual failures become per-piece corrections rather than program-level breakdowns. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the cross-references to other reference files, the underlying-pattern observation about magic-factory thinking and unarticulated workflows. + +## Implementation choices that stay internal + +The specific tracking system the team uses for AI usage. The specific calibration session cadence. The specific ethics-policy doc and its review process. The specific tool selections and their rationale. These vary per team and brand. diff --git a/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md b/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md new file mode 100644 index 0000000..454370a --- /dev/null +++ b/skills/ai-content-collaboration/references/disclosure-and-transparency-patterns.md @@ -0,0 +1,170 @@ +# Disclosure and transparency patterns + +Tiered disclosure framework, language patterns, industry norms. + +When should AI usage be disclosed to readers? The answer is not "always" or "never"; it is "calibrate to context." The framework below tiers disclosure decisions by trust sensitivity. + +--- + +## The tiered framework + +Four tiers, ordered by disclosure obligation. + +### Tier 1: Always disclose + +AI usage is disclosed regardless of how light the involvement was. + +Categories. + +- Journalism and news reporting (any AI involvement, any extent) +- Bylined expert opinion (where the byline implies human authorship of the argument) +- Content where AI tools are themselves the subject (transparency about methodology is part of the topic) +- Regulated industries with explicit AI disclosure requirements (financial advice, medical content, legal content in some jurisdictions) + +Reasoning. In these categories, the reader's understanding of the content's origin is load-bearing for trust. A news story partially AI-drafted reads differently from a story fully reported and written by a journalist; readers have a right to that information. + +### Tier 2: Default disclosure (consider context) + +Disclosure is the default; opting out requires a specific reason. + +Categories. + +- Thought leadership pieces where the byline carries trust value +- Content that influences purchase decisions (reviews, comparisons, recommendations) +- Content for trust-sensitive audiences (academia, enterprise procurement, professional services) +- Long-form pieces where the audience has reasonable expectation of human craft + +Reasoning. Readers in these contexts often assume human authorship; AI involvement that is undisclosed becomes a trust violation if discovered. Disclosure is cheap; the trust hit from undisclosed-then-discovered AI involvement is expensive. + +### Tier 3: Generally not necessary + +Disclosure is allowed but not required by audience expectations. + +Categories. + +- Marketing copy (web pages, ad copy, email marketing copy) +- Descriptive product content (product descriptions, spec listings) +- Programmatic data pages (where the page is obviously data-generated) +- Internal team content (memos, internal reports) +- Copy edit assistance only (the human wrote the piece; AI suggested edits) + +Reasoning. In these categories, audience expectations do not assume specific authorship. Readers recognize the genre as functional content; AI involvement does not violate trust the way it would in a thought leadership piece. + +### Tier 4: Clearly fine without disclosure + +Disclosure is unnecessary and would feel weird if present. + +Categories. + +- AI as research assistant (the AI condensed sources; the human wrote) +- AI for transcription only (the human is the writer; the AI was a typist) +- AI for spelling and grammar suggestions (copy edit role only) +- AI as brainstorming partner where the human took the ideas and wrote independently + +Reasoning. The AI's role was so light that disclosure would imply more involvement than there was. Readers would interpret a disclosure as misleading. + +--- + +## Language patterns + +When disclosure is used, the language matters. + +### Patterns that work + +> "AI tools assisted in research and drafting; the author edited and verified all claims." + +> "This piece was generated programmatically from [data source]; reviewed by [team] before publish." + +> "The author drafted this piece; AI tools were used for copy edit suggestions." + +> "Research synthesis assisted by AI; all sources verified by the author." + +The patterns share three features: they specify what AI did, they specify what humans did, they identify the accountability party. + +### Patterns to avoid + +- Hedge language. "May have used AI" or "could have been AI-assisted" reads as covering legal bases without committing to honesty. Be specific or omit. +- Disclosure that minimizes. "AI was minimally involved" is hedging; either AI was substantively involved (disclose substantively) or it was not (no disclosure needed for Tier 4 use). +- Disclosure that overstates. "Fully written by AI" when humans rewrote 50% is dishonest in the other direction. The disclosure should match the actual AI involvement. + +### Where to place disclosure + +- Footer or byline area. Standard placement; readers find disclosure where they expect it. +- Inline at relevant points. When AI involvement varies across a piece, inline notes are clearer than a single footer note. +- Methodology section. Long pieces with substantial AI involvement benefit from a "How this piece was produced" section that explains the workflow. + +--- + +## Industry norms + +Disclosure norms vary by industry. The principle of intellectual honesty is constant; the specific expectations differ. + +Journalism. Major journalism organizations have published explicit AI usage standards. The norm is moving toward disclosure of AI involvement in any reported piece. Journalism trust depends on transparency; AI-related opacity is a fast trust violation in the audience. + +Content marketing. Norms are weaker but moving toward disclosure for high-trust pieces. Branded thought leadership is increasingly expected to disclose AI involvement; routine marketing copy is not. + +Academic and research content. AI involvement in research papers is a contested area; conferences and journals have varying policies. The conservative default is full disclosure, including which AI tools were used and at what stages. + +Regulated industries. Financial, medical, and legal content increasingly carries explicit AI disclosure requirements. The defaults here are tighter than in unregulated marketing content; consult the specific regulatory environment. + +Ecommerce and product content. Disclosure is generally not expected on product descriptions or spec listings. AI generation is genre-typical; readers do not interpret presence or absence of disclosure as meaningful. + +--- + +## When disclosure helps and when it hurts + +The honest framing. Disclosure is sometimes a trust gain, sometimes a trust loss; the calibration depends on audience norms. + +Disclosure as trust gain. + +- Audience expects human authorship; disclosure preempts trust loss from later discovery +- Brand positions itself on transparency +- Industry is moving toward disclosure as the new norm +- The piece's value is in research and verification, which AI assisted but did not replace + +Disclosure as trust loss. + +- Audience interprets AI involvement as quality reduction (sometimes a misreading, sometimes accurate) +- Disclosure language reads as defensive or hedging +- Audience expects routine content (where AI is genre-typical) + +The decision is not "always disclose" or "never disclose" but "calibrate." The calibration is best done by someone who knows the audience and the brand's positioning, not by a generic policy. + +--- + +## Disclosure policy at the program level + +The program-level discipline. Document the disclosure policy by content type. Editors and writers know which content types require disclosure; the disclosure language is templated; the policy is reviewed quarterly. + +Template policy structure. + +- Content type: [thought leadership]. Disclosure: [required]. Language template: [template]. +- Content type: [knowledge base article]. Disclosure: [optional]. Language template: [template if used]. +- Content type: [programmatic data page]. Disclosure: [not required]. +- Content type: [marketing landing page]. Disclosure: [not required]. + +The policy gets updated as norms evolve. AI disclosure norms in 2026 are looser than they will be in 2028; policy review keeps the program aligned with audience expectations. + +--- + +## When the disclosure decision is hard + +Edge cases. + +Long-running expert byline. A column under a named expert's byline, where some pieces are pure expert authorship and others are substantively AI-assisted. Disclosure on the AI-assisted pieces is the right call; the byline's trust value depends on it. + +Pillar content with mixed authorship. A pillar piece where the lede is human-written, the body is AI-drafted-then-rewritten, the closing is human-written. Disclosure language can specify the mix: "Research and core argument by the author; AI assisted in initial drafting of body sections; all claims verified." + +Internal-only content that becomes external. An internal report that gets externalized requires retroactive disclosure if the internal version was AI-assisted. Sometimes the externalization should include rewriting to bring the disclosure inline. + +The principle. When the disclosure decision is hard, default to disclosure. Trust is recoverable from over-disclosure; trust is not always recoverable from under-disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The four-tier framework, the disclosure language patterns, the industry norms summary, the trust-gain-vs-trust-loss calibration, the program-level policy structure, the edge-case handling. + +## Implementation choices that stay internal + +The specific disclosure language the team has developed for each content type. The specific tracking that records AI involvement per piece (workflow log, CMS metadata, byline annotation). The specific review cadence for the disclosure policy. The specific audience-research feedback that informs disclosure norms for the brand's specific audience. These vary by team, brand, and industry. diff --git a/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md b/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md new file mode 100644 index 0000000..d435d59 --- /dev/null +++ b/skills/ai-content-collaboration/references/ethics-and-intellectual-honesty.md @@ -0,0 +1,154 @@ +# Ethics and intellectual honesty + +Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame. + +This is the most ethically loaded reference in the catalog. The voice is honest, pragmatic, non-preachy. The catalog itself is produced with AI assistance; pretending otherwise would render any anti-AI position hypocritical. The position is not "AI use is unethical" but "intellectual honesty about AI involvement is non-negotiable." + +--- + +## Training data realities + +Every major LLM in 2026 was trained on copyrighted material. That is the simple ethical reality. + +The legal status of training-data copyright is contested in multiple jurisdictions and is being litigated. The position the catalog takes is not "AI training is ethical" or "AI training is unethical"; the position is "the question is unresolved, the tools exist, teams use them, the way to use them ethically is the question this skill addresses." + +What this skill does not relitigate. The training-data copyright question. The compute-intensity environmental question. The labor-displacement question. These are real ethical questions; this skill is not the place to resolve them. Teams reading this skill make their own choices about whether to use AI tools at all; the skill addresses how to use them with intellectual honesty when teams have made the use-AI choice. + +--- + +## Don't pass AI work as fully human-written + +The first ethical floor. + +Bylined content where the byline implies human craft requires substantial human craft. A column under a named expert's byline that is substantially AI-drafted is a trust violation regardless of whether disclosure was technically present somewhere on the page. The byline's value depends on the audience's understanding that the named human authored the piece; AI authorship that the byline obscures is dishonest. + +What "substantial human craft" requires. + +- The argument is the human's +- The voice is recognizable as the human's +- The judgments about what to include, what to cut, what to emphasize are the human's +- The fact verification is the human's +- The final approval is the human's + +What it does not require. Every word being typed by the human (research-assistant patterns are fine). Every sentence being unrewritten (copy edit assistance is fine). The human spending a specific time-on-task (the time matters less than the substance). + +--- + +## Don't claim AI didn't help when it did + +The second ethical floor. + +False denials are worse than disclosure. A team that uses AI substantially and then claims the work is fully human is staking trust on a falsifiable claim. Discovery of the AI involvement (which becomes more reliable each year as detection tools improve) compounds the trust violation: the audience now distrusts both the work and the team's honesty about the work. + +The honest pattern. If AI was used in any way that would matter to the audience, the team is honest about it. The disclosure tiering framework (per `disclosure-and-transparency-patterns.md`) addresses when disclosure is required; the no-false-denial floor is broader: even when disclosure is not required, false denial is not allowed. + +In practice. Most teams do not face direct denial questions; the issue comes up in interview contexts ("how do you produce your content?"), retrospectives, or conversations with clients and partners. The honest answer in those contexts is the truthful one, even when no public disclosure was attached to specific pieces. + +--- + +## Don't generate content that closely mirrors copyrighted source material + +The third ethical floor. + +AI tools can produce near-replicas of training data when prompted carelessly. The team's responsibility is to verify that AI-generated content is original work and not a paraphrase of a specific copyrighted source. + +The check. For each substantive section of AI-generated content, search for the unique phrasing in quoted form. If results come back to a specific copyrighted source that the AI was likely trained on, the section is too close to source material. Revise. + +The pattern. AI tools tend to mirror training data more closely on niche topics than on common topics. Common topics have many sources to blend; niche topics have fewer. Specialized content (academic topics, technical documentation, industry-specific niches) needs more careful mirroring checks. + +--- + +## Attribute when borrowing + +The fourth ethical floor. + +Ideas, frameworks, statistics, and specific phrasings that came from identifiable sources get cited. The principle is not changed by whether AI surfaced the source or whether the human did; attribution belongs to the source, not to the discovery method. + +The pattern. + +- Statistics with sources: cite the source. +- Frameworks attributed to specific thinkers: cite the thinker. +- Specific arguments traceable to a specific publication: cite the publication. +- Common knowledge: no citation needed, but verify it actually is common knowledge and not specialized knowledge that the AI surfaced from a specific source. + +The honesty test. If the team would feel uncomfortable having the source's author read the piece and recognize their work uncited, citation is required. + +--- + +## Don't fabricate quotes or expertise + +The fifth ethical floor. + +Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. The team is accountable for what gets attributed; the AI is not the accountable party. + +The pattern. AI generates plausible-but-fake quotes in 2026; that is a known limitation. The fact-accuracy gate per `editorial-qa` catches them before publish. The ethical position is broader than the QA position: even if a fabricated quote were never caught, generating it under attribution to a real person is dishonest. + +The same applies to expertise claims. AI-drafted "expert content" attributed to a named expert who did not draft it is fabricated expertise. The expert's name carries trust value; the trust depends on the expert having actually drafted the piece. + +--- + +## Be honest about AI capabilities and limits + +The sixth ethical floor. + +Do not oversell AI as more capable than it is. Do not undersell it as less capable than it is. Both produce decision-making errors in the team and in the audience. + +The pattern. AI in 2026 is genuinely useful for research synthesis, drafting against briefs, copy edit suggestions, transcription, summary, and quality-control automation at scale. AI in 2026 is genuinely limited at editorial judgment, fact verification (it is what gets fact-checked, not what does fact-checking), voice origination, ethical decisions, and reader empathy. + +Teams that get this right calibrate AI use to the limits. Teams that oversell AI ship work that exceeds AI's actual capabilities and produces hallucinations or voice failures. Teams that undersell AI miss productivity gains the technology offers. + +--- + +## The intellectual honesty frame + +The frame that supersedes specific policy debate. + +The question is not "is AI use ethical?" The question is "can the team be intellectually honest about AI use?" If yes, the team's ethics hold. If no, the team is rationalizing. + +What intellectual honesty looks like. + +- The team can articulate its AI-usage policy without defensiveness +- The team can name the specific patterns it does and does not use +- The team can defend each pattern on the merits, not just by precedent +- The team can engage with critiques of its policy without dismissing them +- The team updates its policy when reality changes (new tools, new evidence, new audience norms, new regulatory requirements) + +What intellectual dishonesty looks like. + +- Defensiveness when AI involvement is questioned +- Refusal to articulate the policy +- Dismissing critiques without engaging +- Hiding AI involvement that would be material to audiences +- Claiming AI does what it does not, or hiding that AI does what it does + +The honest team can withstand external scrutiny because its position holds up. The dishonest team eventually faces external scrutiny that surfaces the gap between claimed and actual practice. + +--- + +## When the ethical question is hard + +Edge cases. + +Ghostwritten content historically allowed. Industries where ghostwriting has always been the norm (executive thought leadership, celebrity book authorship, political speechwriting). AI assistance in ghostwriting workflows raises questions: is the ghost an AI? does the byline still mean what it meant? + +The conservative position. The byline implies human authorship; if the ghost is an AI rather than a human writer, that distinction is material to the audience and disclosure is appropriate. The aggressive position. Ghostwriting has always been a fiction the audience tolerates; AI ghostwriting is the same fiction with different tools. + +The catalog's position. Default to the conservative reading. The byline's trust value depends on audience understanding of authorship; AI ghostwriting under a named expert byline is more honest with disclosure than without. + +Educational content with structured explanations. Topics where the explanation has a canonical shape (math, basic programming, established science). AI-drafted explanations of canonical topics may closely mirror training data because the canonical shape is what the training data contains. + +The conservative position. Cite the canonical sources where they exist; rephrase substantively where citation is impractical. + +Programmatic SEO at scale. Hundreds of thousands of pages where individual disclosure is impractical and audience expectations differ from editorial content. + +The position. Programmatic content is genre-typically machine-generated; specific disclosure per page is unnecessary; transparency about the program's overall production model is appropriate at the brand level. + +--- + +## Methodology-level choices that stay in the public skill + +The training-data realities framing, the six ethical floors, the intellectual honesty frame, the edge-case handling, the conservative-vs-aggressive position taking on contested cases. + +## Implementation choices that stay internal + +The specific ethics policy the team has documented. The specific review process when an ethics question surfaces. The specific escalation pathway for ethics decisions. The specific tracking that records ethics-related decisions for retrospective review. These vary per team and brand. diff --git a/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md b/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md new file mode 100644 index 0000000..1f91b00 --- /dev/null +++ b/skills/ai-content-collaboration/references/hybrid-workflow-patterns.md @@ -0,0 +1,121 @@ +# Hybrid workflow patterns + +Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context. + +No pattern is "the right one." Pattern selection is a real decision that should match volume, voice sensitivity, team skill, and time budget. The wrong pattern produces predictable failures: AI-first drafts on voice-sensitive pieces produce slop; human-writes patterns on programmatic-scale work produce throughput failures. + +--- + +## Pattern 1: AI-first draft, human-edit-heavy + +The shape. AI produces a 90% draft against a brief. The human spends 60% of the production time editing: rewriting flat sentences, restructuring sections that miss the brief, adding voice and specificity, verifying facts. + +Best for. High-volume editorial where the brief is well-authored and the voice is moderately tolerant of AI defaults. SaaS blog posts, knowledge-base articles, secondary editorial pieces. + +Risks. Generic voice if editing is light. The pattern fails quietly; pieces ship with AI defaults preserved because the editor was rushed. + +Time profile. 30% AI generation, 60% human editing, 10% fact verification. Faster than human-writes for the same word count but slower than naive AI-only generation because editing time scales with the piece's length. + +When this fits. The team has clear brand voice and disciplined editors. The volume requirement is real (multiple pieces per day). The audience is tolerant of AI-assisted-but-edited content (most B2B, most consumer marketing). + +--- + +## Pattern 2: Human-first outline + research, AI-draft, human-rewrite + +The shape. Human builds the outline (or extends the brief's outline). Human gathers and verifies the research. AI drafts within that scaffold. Human rewrites in voice. + +Best for. Voice-sensitive editorial where the brand voice is distinctive enough that AI drafts need substantive rewriting anyway. The pattern formalizes the rewrite as the discipline rather than treating it as cleanup. + +Risks. Slower than AI-first drafts. If the rewrite is light, output is similar to Pattern 1. The discipline is in the rewrite intensity. + +Time profile. 20% human research and outline, 20% AI drafting, 50% human rewriting, 10% fact verification. + +When this fits. Brand voice is distinctive (provocative, opinionated, or emotionally specific). The audience would notice generic drafts. Time budget allows substantive rewrites. + +--- + +## Pattern 3: AI-as-research-assistant, human-writes + +The shape. AI condenses sources into research briefs. Human writes the entire piece from the brief in their own voice. + +Best for. Highest-trust editorial: thought leadership, contributed expert pieces, journalism, regulated content. Pieces where the byline is doing trust work and any AI involvement in drafting would compromise the byline's value. + +Risks. Slowest pattern. AI's role is small enough that the team may question whether AI is helping at all; the answer is usually yes (research time savings are real) but the gain is in time-to-research, not time-to-publish. + +Time profile. 40% human reading and outlining, 60% human writing, 10% fact verification (with AI sometimes assisting in flagging fact-check candidates). + +When this fits. The byline is named and trusted (a CEO, an expert, a journalist). The publication's positioning depends on human craft. Disclosure norms in the audience expect human authorship. + +--- + +## Pattern 4: Human-writes, AI-as-editor + +The shape. Human drafts the piece. AI suggests copy edits, alternative phrasings, structural improvements. Human accepts or rejects each suggestion. + +Best for. Senior writers whose voice is established and whose drafts are mostly clean. The AI's role is the second-pair-of-eyes that catches what fatigue or close reading missed. + +Risks. AI suggestions can pull voice toward AI defaults if the writer accepts too many. The discipline is rejecting the suggestions that would homogenize voice even when they read as "cleaner." + +Time profile. 80% human writing, 15% AI suggestion review, 5% fact verification. + +When this fits. The writer is experienced, the brand voice is well-developed, the piece is high-stakes. Pattern is over-kill for routine editorial; right-sized for thought leadership and named-byline pieces. + +--- + +## Pattern 5: AI-generates-at-scale, human-samples + +The shape. For programmatic SEO. AI generates thousands of pages from structured data and templates. Human samples 50 to 200 pages per cycle with editorial-qa sampling discipline. Failures above the 5% threshold halt new generation until template or data fixes ship. + +Best for. Programmatic SEO programs (per `programmatic-seo`). Volume scales the AI does not penalize the program because the underlying data is real and the template is strong; humans sample rather than fully review. + +Risks. Without sampling discipline, the program produces slop at scale. Without threshold gating, slop compounds invisibly until algorithm updates expose it. Pattern requires the editorial-qa scaling pattern to work; without QA scaling, the pattern is just AI-content-factory thinking with extra steps. + +Time profile. 5% template and data setup (one-time, deep), 0.5% per-page generation (mostly automated), 10% sampling QA (per cycle), 5% threshold response. + +When this fits. Data depth is real, query intent is queryable, QC headcount is budgeted. All five criteria from `programmatic-seo`'s when-pseo-works-decision must be met. + +--- + +## Selection criteria + +How to pick the pattern. + +Voice sensitivity. Distinctive voice → Pattern 2, 3, or 4. Generic-tolerant voice → Pattern 1 or 5. + +Volume. Single-piece-at-a-time editorial → Pattern 2, 3, or 4. High-volume editorial → Pattern 1. Programmatic scale → Pattern 5. + +Trust requirement. Named-byline trust work → Pattern 3 or 4. Standard branded content → Pattern 1, 2, or 5. + +Time budget. Tight (hours not days) → Pattern 1. Generous (days available) → Pattern 2, 3, or 4. One-time-deep then automated → Pattern 5. + +Team skill. Junior writers → Pattern 1 or 2 (more AI scaffolding). Senior writers → Pattern 3 or 4 (less AI, more craft). + +--- + +## Combining patterns within one program + +Most content programs run multiple patterns simultaneously. Common combinations. + +- Editorial pillar + cluster: Pattern 3 (AI as research assistant) for the pillar piece; Pattern 1 (AI-first draft, human-edit-heavy) for the cluster pieces. The pillar carries the trust; the cluster scales. +- Editorial + programmatic: Pattern 2 or 4 for editorial; Pattern 5 for programmatic. Same brand, different production model per content type. +- Marketing copy + thought leadership: Pattern 1 for marketing; Pattern 3 for thought leadership. Different trust requirements; different patterns. + +The discipline. Document which pattern the team uses for which content type. Without explicit documentation, the patterns drift; one writer uses Pattern 1 on a piece that should have been Pattern 3, and the trust value of the byline is compromised. + +--- + +## Anti-pattern: pattern drift mid-piece + +Sometimes a piece starts in Pattern 4 (human-writes, AI-as-editor) and drifts into Pattern 1 (AI-first, human-edits) when the writer falls behind on deadline. The piece publishes with AI default voice in sections the writer was supposed to draft. + +The fix. Recognize the drift as a process failure, not a writing failure. The writer was over-committed; the fix is workload management, not blame. Future pieces of this type either get more time (preserving Pattern 4) or get reassigned to Pattern 1 with the editing intensity that Pattern 1 requires. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns, the tradeoffs per pattern, the selection criteria framework, the multi-pattern combinations within a program, the pattern-drift anti-pattern. + +## Implementation choices that stay internal + +The specific AI tools used in each pattern (drafting model, editing model, research model). The specific prompts each pattern uses for the AI handoff. The specific time-tracking that captures pattern adherence per piece. The specific deadline-management workflow that prevents pattern drift mid-piece. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md b/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md new file mode 100644 index 0000000..e16cab8 --- /dev/null +++ b/skills/ai-content-collaboration/references/quality-calibration-with-ai-in-loop.md @@ -0,0 +1,143 @@ +# Quality calibration with AI in the loop + +How editorial standards shift when AI is in the workflow. Same standards apply; the failure modes shift. + +The editorial standards from `editorial-qa` apply identically to AI-assisted work: brief adherence, voice consistency, fact accuracy, structure and clarity, AEO/SEO compliance, internal linking and schema validation. What shifts is the failure-mode profile. Programs that ship AI-assisted content with the same QA discipline as human-written content but without recognizing the new failure modes produce slop while believing they are calibrated. + +This reference connects the QA discipline to the AI workflow discipline. It surfaces the shifts. + +--- + +## Same standards, different failure modes + +For each editorial standard, the failure mode that dominates in AI-assisted production differs from the failure mode that dominated in human-only production. + +### Brief adherence + +Human-only failure. Writer skips a brief field because they think they know better, or misreads the brief. + +AI-assisted failure. AI ignores brief fields that were not in the prompt context. The brief is in one document; the AI prompt is in another. Brief fields that did not get pasted into the prompt do not get executed. + +The fix. Prompt templates that explicitly include all 12 brief fields. Brief-adherence QA gate runs against the brief, not against the prompt. + +### Voice consistency + +Human-only failure. Writer fatigue causes voice drift in section 4 of long pieces. Editorial style drift over months as writers absorb each other's tics. + +AI-assisted failure. AI default voice reasserts mid-piece. Long AI generations regress toward generic by section 4 reliably. The drift is faster than human drift and more consistent across pieces. + +The fix. Mid-piece voice sampling per `voice-ownership-preservation.md`. Voice anchor text in every prompt. Final pass in human voice on every long piece. + +### Fact accuracy + +Human-only failure. Lazy fact-checking. The writer "remembers reading" something but does not verify. Citations to publications without specific dates or page references. + +AI-assisted failure. AI hallucinations. Plausible-but-fake statistics with named sources that do not exist. Quotes attributed to real people who did not say them. Citations to URLs that 404. + +The fix. Fact-accuracy as halt-condition gate per `editorial-qa`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns. + +### Structure and clarity + +Human-only failure. Buried lede, vague opening, history dump in section 1. Mismatched section lengths. + +AI-assisted failure. Generic opening that could open any article on the topic. Repetitive paragraph structure (every paragraph 2 to 3 sentences). Bullet-list overuse where prose would serve. Forced bilateral framing throughout. Wrap-up filler endings. + +The fix. AI-content audit per `editorial-qa/references/ai-content-audit-patterns.md`. Read-aloud audit catches what line-review misses. + +### AEO and SEO compliance + +Human-only failure. Writer forgets to include the target keyword in title and headings. Schema markup absent or invalid. + +AI-assisted failure. AI over-optimizes the surface (keyword in every heading, schema markup over-claimed) but under-optimizes the substance (the answer paragraph is generic, the entity coverage is thin, the POV is absent). + +The fix. AEO/SEO checks that go beyond surface compliance into substance: is the top-200-word answer self-contained, is the entity coverage what the brief specified, is the POV distinctive. + +### Internal linking and schema validation + +Human-only failure. Writer skips internal-link discipline because it feels mechanical. Anchor text uses "click here" or generic phrases. + +AI-assisted failure. AI-generated links to URLs that do not exist (hallucinated link targets). Anchor text repeats the same exact-match keyword across multiple links because the AI defaults to that pattern. + +The fix. Link-target liveness check on every published piece. Anchor text variation as a explicit QA item. + +--- + +## The "QA standards must be tighter" claim is wrong + +A common misreading. Teams shipping AI-assisted work decide their QA needs to be tighter, more checks, more thresholds. The misreading produces checkbox theater. + +The accurate reading. QA needs to be calibrated to the new failure modes, not tightened indiscriminately. The standards stay the same; the patterns to look for shift. + +The discipline. When a team starts AI-assisted production, the QA process gets reviewed against the new failure-mode profile. Some checks become more important (fact accuracy, voice consistency, AI-content audit). Some checks become less important (the writer's preferred typo patterns, since the AI does not have the same typo patterns). The QA shape adjusts. + +--- + +## Calibration sessions specific to AI-assisted work + +The calibration session methodology from `team-training-and-calibration.md` adapts for AI-assisted work specifically. + +The AI-specific calibration session. + +1. Three editors independently review the same 3 to 5 AI-assisted pieces. +2. Each editor's assessment includes the AI-content audit dimensions: AI tells, hallucination patterns, voice drift, slop signals. +3. The team reads all assessments together. +4. Differences in interpretation surface; reconcile. +5. Output: addendum to the AI policy doc capturing the calibration consensus on AI-specific QA dimensions. + +The cadence. Quarterly minimum. More frequent during program build or after AI tool changes that affect output behavior. + +--- + +## When the team is calibrated but the output still feels off + +Symptoms. + +- QA gates pass, individual pieces look fine, the program's overall feel is generic +- Readers complain about AI-flavored content despite QA passing +- Audience growth flat despite shipped quality being technically high + +Diagnosis. The QA discipline catches per-piece failures. It does not catch program-level patterns: every piece passing voice review individually but the cumulative output reading as homogenized. + +The fix. Add a program-level review to the calibration cadence. Read 10 published pieces in sequence. Do they sound like one publication with a distinctive voice, or do they sound like 10 separate AI-assisted pieces from different generic publications? The latter signals voice has been preserved at the per-piece level but lost at the program level. + +The intervention. Tighter voice library, more aggressive reject-the-bland discipline, possibly a return to a heavier human-writes pattern for trust-anchor pieces (pillars, thought leadership, named-author content) while keeping AI-assisted patterns for cluster work. + +--- + +## The "ship vs hold" calibration + +In AI-assisted production, the ship-vs-hold decision shifts. More pieces marginally pass QA; the question becomes whether marginal-pass pieces should ship. + +Human-only mode. Marginal pieces usually have specific fixes. The editor flags them; the writer fixes them; the piece ships. + +AI-assisted mode. Marginal pieces often have systemic AI-tells throughout that fixing one-by-one will not address. The editor's choice is between substantial rewrite (back to Pattern 2 or 3) or kill. + +The discipline. Some AI-assisted pieces are kill candidates, not revise candidates. The team should have explicit kill criteria: pieces that fail AI-content audit on 4+ dimensions, pieces where voice was lost beyond paragraph-level recovery, pieces where the underlying brief was thin enough that the AI draft has nothing to anchor to. + +Killing pieces is part of the discipline. Programs that publish 100% of what they draft are not exercising editorial judgment. + +--- + +## The calibration-with-AI checklist + +For each AI-assisted piece, beyond the standard QA gates. + +1. AI-content audit run per `editorial-qa/references/ai-content-audit-patterns.md`? +2. Voice anchor text was used in the prompt? +3. Mid-piece voice sample taken on long pieces? +4. Final pass in human voice for the closing? +5. Fact-accuracy gate ran with AI-hallucination patterns specifically in mind? +6. Disclosure decision made per the disclosure tier framework? +7. The piece passes the "could a competitor have shipped this with the same tools" test? + +If 2+ items fail, the piece is at slop risk. Halt and revise. + +--- + +## Methodology-level choices that stay in the public skill + +The same-standards-different-failure-modes mapping, the "QA standards must be tighter" misreading correction, the AI-specific calibration session adaptation, the program-level review pattern, the kill-criteria discipline, the calibration-with-AI checklist. + +## Implementation choices that stay internal + +The specific QA tooling that surfaces AI-specific failure patterns. The specific automation that flags potential AI tells before manual review. The specific calibration session cadence and team composition. The specific kill-criteria thresholds the team has settled on. These vary by team scale and content sensitivity. diff --git a/skills/ai-content-collaboration/references/team-training-and-calibration.md b/skills/ai-content-collaboration/references/team-training-and-calibration.md new file mode 100644 index 0000000..da21f15 --- /dev/null +++ b/skills/ai-content-collaboration/references/team-training-and-calibration.md @@ -0,0 +1,149 @@ +# Team training and calibration + +Documented policy, calibration sessions, voice library, quality benchmarks, onboarding. + +Inconsistent AI usage across a team produces inconsistent output. The discipline below makes AI usage explicit, calibrated, and documented at the team level so the program ships consistent work regardless of which writer is assigned which piece. + +--- + +## Documented AI policy + +The starting point. Every team running AI-assisted content has a policy document, even if currently informal. + +What the policy specifies. + +- Approved uses. AI in research synthesis, AI in copy edit suggestions, AI in transcription, AI in alternative phrasings. The team uses these without per-piece approval. +- Conditional uses. AI in first-draft generation, AI in outline generation, AI in long-form drafting. Approved per content type (e.g., approved for cluster pieces, requires editor approval for pillar pieces). +- Prohibited uses. AI as the sole author of bylined expert content, AI for fact verification (the AI is what gets fact-checked, not what does fact-checking), AI for ethical decisions, AI for final approval. +- Tool standards. Either "the team uses [specific tool] for [specific task]" or "the team selects from this list of tools per task type." Documented either way. +- Disclosure requirements. By content type, per the disclosure framework. +- Voice library reference. Where the team's voice anchor texts and prompt templates live. + +The discipline. The policy is a document, not an oral tradition. Writers, editors, and contributors know where to find it; it is referenced in onboarding; it is updated quarterly. + +--- + +## Calibration sessions + +The discipline. Quarterly editor sessions where editors review the same AI-assisted pieces and surface differences in their judgment. + +Session structure. + +1. Three editors independently review the same 3 to 5 recently-published pieces. +2. Each editor writes a one-paragraph assessment per piece: voice, brief adherence, AI tells, fact accuracy, overall quality. +3. The team reads all assessments together. +4. Differences in interpretation surface; the team reconciles to a shared standard. +5. The session output is an addendum to the policy doc capturing the calibration consensus. + +Why this matters. Without calibration, individual editors apply individual taste. Some editors flag AI-tells aggressively; others ship the same piece without flagging. The inconsistency confuses writers and produces drift in published quality. + +Cadence. Quarterly minimum. More frequent during onboarding waves or after policy updates. + +--- + +## Voice library + +The team's collection of canonical brand-voice samples used as anchor text in AI prompts. + +What goes in the library. + +- 2 to 3 paragraphs of canonical brand voice per content type (blog, whitepaper, help doc, marketing copy, thought leadership) +- 2 to 3 paragraphs per writer voice (where the brand has multiple distinct contributor voices) +- 5 to 10 examples of AI-generated content that the team rewrote successfully (showing the before-and-after as a calibration aid) +- The vocabulary list: preferred terms, forbidden terms, term-specific usage rules + +Update cadence. Monthly during program build; quarterly once stable. + +Why this matters. The voice library is the operational expression of brand voice. Without a library, every AI prompt reinvents the voice context; the team produces inconsistent output. With a library, the prompt is templated and the voice context stays consistent. + +--- + +## Quality benchmarks + +The team's documented examples of "AI-assisted but on-voice" pieces. + +What the benchmarks show. + +- 5 to 10 published pieces where AI assistance was substantial but the output reads as on-voice +- For each benchmark: the pattern used (which workflow pattern), the editing intensity, the time profile, the quality outcome +- The benchmarks are calibration aids: writers and editors look at them when calibrating their own AI-assisted work + +Why this matters. "On-voice AI-assisted content" is an abstraction. Concrete examples make it tangible. New writers calibrate to the benchmarks; experienced writers reference them when their work feels off. + +Anti-pattern. Benchmarks that are aspirational rather than achieved. The benchmark library should be real published work, not "what we wish we shipped." Aspirational benchmarks set unrealistic expectations. + +--- + +## Tool standardization vs intentional pluralism + +Two valid models for AI tool selection at the team level. + +### Standardization + +The team uses one tool consistently for each task type. Drafting on tool A, editing on tool B, transcription on tool C. New writers learn the standard tools; the prompt templates and voice library are tool-specific. + +When this fits. Smaller teams. Predictable content types. Time-budget for tool learning is limited. Consistency matters more than per-task optimization. + +### Intentional pluralism + +The team documents which tools fit which tasks; writers select per-task. Tool A for tasks of type X, tool B for tasks of type Y, contributors choose between them as appropriate. + +When this fits. Larger teams. Diverse content types. Writers have time to learn multiple tools. Per-task optimization matters more than absolute consistency. + +The discipline either way. The choice is documented; tool selection is not arbitrary or per-writer. + +--- + +## Forbidden patterns list + +The patterns the team explicitly does not use AI for, even when AI could technically do them. + +Common forbidden patterns. + +- AI fabricating quotes (always; this is fabrication) +- AI generating content that names specific real people (consent and verification issues) +- AI as the sole author of bylined opinion (ethics) +- AI for content involving regulated topics where the team lacks AI-policy guidance (medical advice, legal advice, financial advice) +- AI for content the team would be ashamed to publish under their byline (slop test) + +Why this matters. The forbidden list is shorter than the approved list but more important. The forbidden list is what keeps the program out of ethics violations and trust failures. + +--- + +## Onboarding + +New writers learn the AI policy and calibration in their first 2 weeks. + +Onboarding components. + +- Policy read. The new writer reads the AI policy doc. +- Voice library walkthrough. The new writer reviews the voice samples and prompt templates. +- Calibration session participation. The new writer participates in the next calibration session as observer. +- Shadow assignment. The new writer's first piece is reviewed jointly with an experienced editor; the editor narrates the calibration in real-time. +- Quality benchmark walkthrough. The new writer reviews the quality benchmarks and identifies what makes each "on-voice." + +Why this matters. New writers without onboarding develop their own AI patterns. The program drifts as new writers join. Onboarding makes the team's discipline transferable. + +--- + +## When team calibration breaks + +Symptoms. + +- Different writers produce wildly different AI-assisted output (calibration overdue) +- Editors disagree on whether a piece is "AI-flavored" (calibration session needed) +- The AI policy doc is 6 months stale and references tools the team no longer uses (policy update overdue) +- New writers are using AI in ways that experienced writers do not (onboarding gap) +- Voice library has not been updated since the program launched (library refresh overdue) + +The fix. Quarterly calibration sessions, quarterly policy review, quarterly voice library updates, structured onboarding for every new writer. The cadences are calendar-anchored; skipping them is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +The documented-policy structure, the calibration session methodology, the voice library practice, the quality-benchmark library, the standardization-vs-pluralism choice, the forbidden-patterns discipline, the onboarding components, the calibration-breakdown signals. + +## Implementation choices that stay internal + +The specific format of the policy doc (Notion page, Markdown file, internal wiki). The specific tooling that hosts the voice library (database, Notion, Git repo of sample text). The specific calibration session cadence and team composition. The specific onboarding tracking system. The specific tool selections the team has standardized on. These vary by team and tooling. diff --git a/skills/ai-content-collaboration/references/voice-ownership-preservation.md b/skills/ai-content-collaboration/references/voice-ownership-preservation.md new file mode 100644 index 0000000..cbeb488 --- /dev/null +++ b/skills/ai-content-collaboration/references/voice-ownership-preservation.md @@ -0,0 +1,133 @@ +# Voice ownership preservation + +Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline. + +Voice is the dominant casualty of careless AI workflows. The patterns below are what programs do to keep voice through AI-assisted production. Programs that skip these patterns produce content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools. + +--- + +## Voice guidelines as prompt input + +The principle. Every AI generation includes the brand voice guidelines as part of the prompt context. Without explicit voice context, AI defaults to a generic register that flattens distinctive brands into industry-standard prose. + +What goes into the prompt. + +- Voice attributes (3 to 5 attributes; e.g., "direct, confident, slightly skeptical") +- Sentence rhythm preference (short and punchy, measured and layered, conversational with asides) +- Stance pattern (opinionated, diplomatic, coach-style, peer-style) +- Register (formal, casual, register that matches the surface) +- Vocabulary preferences (preferred terms, forbidden terms list) +- Anti-patterns (specific phrases or structures to avoid) + +The discipline. The voice guidelines are an input to every AI run, not a one-time setup. Teams that paste the voice guidelines into a saved prompt template ensure consistency; teams that re-type them per session produce drift. + +Why this works. Generic AI defaults are stronger than the AI's training-era voice memory. Without active voice prompting, the AI regresses to the most common patterns in its training data, which are the most common patterns in published content, which are by definition not distinctive. + +--- + +## Sample text as voice anchor + +The principle. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told. + +What to use as anchor. + +- The brand's strongest published piece in the relevant register +- A canonical opening from the brand's editorial doc +- A published piece from a writer whose voice the brand wants to maintain consistency with + +The discipline. Anchor text is updated as the brand voice evolves. Stale anchors produce stale-feeling content; the program treats anchors as living documents. + +Why this works. Description prompts ("write in a direct, skeptical voice") are abstract. AI mimics them generically. Sample text is concrete; AI mimics specific patterns: word choices, sentence shapes, transitional phrases, opening patterns. The mimicry is not perfect but it is closer to the brand voice than the abstract description. + +The combination. The strongest voice prompt combines voice guidelines (description) with sample text (concrete examples). Either alone produces drift; together they hold the line. + +--- + +## Mid-draft voice check + +The principle. Long pieces drift. At the halfway mark of a 3,000-word piece, AI generations regress toward generic. The check catches the drift before publish. + +The check. + +1. Sample paragraphs from the start (first 300 words), middle (1,200 to 1,800 words), and end (last 300 words). +2. Compare each sample to the brand voice doc. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. Send back for revision. + +Detection patterns. + +- Vocabulary regresses (words from the do-not-use list reappear; brand-specific terms drop out) +- Sentence rhythm uniforms (every paragraph 2 to 3 sentences, similar lengths) +- Stance softens (specific positions become "there are good arguments on all sides") +- Register drifts toward "professional neutral" regardless of the surface's intended register + +Cross-reference. This check is also covered in `editorial-qa/references/voice-consistency-patterns.md`. The two skills are aligned; the QA gate enforces what this skill prescribes. + +--- + +## Final pass in human voice + +The principle. The human edits the closing sections in their own voice. The closing is where the piece's emotional register often lands; AI defaults there reduce the piece to flat informational tone. + +Why the closing matters. + +- The reader's last impression +- The conversion or memory moment for the piece +- The signature moment where the brand voice is most recognizable + +The discipline. Even in Pattern 1 (AI-first draft, human-edit-heavy), the closing 100 to 300 words should be substantially or fully human-written. The opening can be AI-drafted with heavy editing; the closing benefits from being composed in the writer's own register. + +Anti-pattern. AI-drafted closing paragraphs that announce the piece is ending ("In summary," "By following these steps," "Now you have a comprehensive understanding"). These are AI tells; the human pass should replace them with specific endings: a question, an action, an observation, a direct call to action with concrete language. + +--- + +## Reject the bland + +The principle. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific. + +The audit. Read the piece. For each sentence, ask: is this distinctively from this brand, or could it have come from any competitor? The interchangeable sentences are the bland ones. + +The fix. + +- Replace abstractions with specifics. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research, do the research; if not, cut the claim. +- Replace hedges with stances. "It depends on your situation" becomes "for teams under 50 employees, [specific recommendation]; for teams over 200, [different specific recommendation]." +- Replace generic openings with brand-specific openings. Throat-clearing intros become specific entry-points tied to the piece's argument. + +The discipline. Bland sentences are not just "less interesting" sentences; they are voice-killers. A piece with 20% bland sentences reads as 80% diluted; the brand voice is present but watered down past distinction. + +--- + +## The voice library + +A program-level practice. The team maintains a library of canonical brand-voice samples that get used as anchor text in AI prompts. The library evolves as the brand voice evolves. + +Library structure. + +- Voice samples by register (formal whitepaper, casual blog post, conversational email, professional help doc) +- Voice samples by content type (pillar editorial, cluster piece, thought leadership, listicle) +- Voice samples by writer (where the brand has multiple distinct contributor voices) + +Update cadence. Quarterly. As new pieces ship that exemplify the voice, they go into the library. As old pieces feel stale, they come out. + +Why this matters. Teams without a voice library re-paste the same 3 paragraphs as anchor text for years. The voice ages; the AI mimicry ages with it; the content starts feeling dated. Library updates keep the anchor fresh. + +--- + +## When voice cannot be preserved + +Sometimes the voice is genuinely incompatible with AI assistance at the volume the program requires. Signals. + +- Brand voice is so distinctive that AI drafts always need 80% rewriting (Pattern 2 might fit; if even Pattern 2 fails, Pattern 3 or 4 are the only options) +- Audience is so trust-sensitive that any AI involvement compromises the byline (Pattern 3 only) +- Volume target requires AI involvement that voice cannot tolerate + +The honest answer in these cases. Reduce volume to match what voice tolerates, or accept voice trade-off as a strategic choice. The trade-off must be deliberate; "we did not realize voice was suffering" is the failure mode. + +--- + +## Methodology-level choices that stay in the public skill + +Voice guidelines as prompt input, sample text as voice anchor, the mid-draft sampling discipline, the final-pass-in-human-voice discipline, the reject-the-bland audit, the voice library practice, the "when voice cannot be preserved" honest framing. + +## Implementation choices that stay internal + +The specific format of the brand voice doc (Notion page, Markdown file, internal wiki). The specific AI tool prompt templates that include voice guidelines and sample text. The specific voice library storage and access pattern. The specific calibration session cadence and team composition. These vary by brand and team. diff --git a/skills/analytics-strategy/SKILL.md b/skills/analytics-strategy/SKILL.md new file mode 100644 index 0000000..c67502c --- /dev/null +++ b/skills/analytics-strategy/SKILL.md @@ -0,0 +1,230 @@ +--- +name: analytics-strategy +description: "Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track." +category: growth +catalog_summary: "Measurement frameworks, dashboard design, event taxonomy" +display_order: 1 +--- + +# Analytics Strategy + +Design measurement frameworks that produce decisions, not just dashboards. Stack-agnostic. Tool-agnostic. + +This skill is for measurement planning. For conversion optimization, use `cro-optimization`. For SEO measurement specifically, use `seo-onpage` and adjacent SEO skills. + +--- + +## When to use + +- Setting up analytics on a new product or site +- Auditing existing analytics setup +- Designing dashboards for a team or business +- Defining KPIs and a north star metric +- Building event taxonomies for product analytics +- Designing attribution models for marketing +- Translating business questions into measurement plans + +## When NOT to use + +- Conversion testing or optimization (use `cro-optimization`) +- SEO performance measurement (use SEO skills) +- Pure data infrastructure decisions (different domain) + +--- + +## Required inputs + +- The business or product context (what does success look like) +- The audience for the analytics (who needs to make what decisions) +- The current measurement state (existing tools, tracking, gaps) +- The questions the team needs to answer + +--- + +## The framework: 4 layers + +A complete measurement strategy covers all four. Each layer feeds the next. + +### 1. North star and KPI hierarchy + +The single metric that captures the most important outcome, plus the supporting metrics. + +North star metric: + +- One metric. Singular. +- Captures customer-perceived value. +- Leads to revenue, but isn't revenue itself (revenue is too far downstream). +- Examples: weekly active users, completed jobs, revenue-generating sessions, hours of value delivered. + +Underneath the north star, the KPI hierarchy: + +``` +North star metric +├── Acquisition KPI (how new users enter) +├── Activation KPI (when new users get value) +├── Engagement KPI (how often users return) +├── Retention KPI (how many stick over time) +└── Monetization KPI (how value translates to revenue) +``` + +This is the "AARRR" or "pirate metrics" framework. It works because it covers the full lifecycle. + +### 2. Event taxonomy + +The vocabulary the product uses to describe what users do. + +Event design principles: + +- Verb + noun. `signed_up`, `created_project`, `completed_checkout`. Past tense, snake_case. +- One event per discrete action. Not "interacted_with_modal" - too vague. Specifically `opened_modal_X`, `closed_modal_X`, `confirmed_in_modal_X`. +- Properties capture context. Each event has properties (key-value pairs) for context. `signed_up` has properties like `signup_method`, `referrer`, `plan`. +- Standardize property names. `user_id` everywhere, not `userId` here and `id` there. +- Document everything. A tracking plan that lives nowhere is a tracking plan no one follows. + +Event coverage: + +- All key user actions tracked +- All conversion points tracked +- All errors tracked +- All page views tracked (with consistent properties) +- All button clicks that matter (not all button clicks - that's noise) + +Anti-patterns: + +- 500+ events with no documentation +- Inconsistent naming (`buttonClicked`, `Button Clicked`, `clicked_button`) +- Property keys that vary across events +- Events fired client-side that should be server-side (and vice versa) +- PII in event properties (privacy issue and tooling issue) + +### 3. Dashboards and reports + +The interface between data and decisions. + +Dashboard design principles: + +- One audience per dashboard. Executive dashboard != product team dashboard. Different metrics, different cadence. +- One question per chart. A chart should answer one question, not three. +- Annotations matter. Note launches, experiments, holidays, outages. A spike means nothing without context. +- Context comparisons. "10,000 signups this month" - compared to what? Last month, last year, target? +- Lead with the action. What does this dashboard help someone decide? + +Common dashboard types: + +\| Dashboard \| Audience \| Metrics \| Cadence \| +\|---\|---\|---\|---\| +\| Executive \| Leadership \| North star, top 3 KPIs, big-picture trends \| Weekly review \| +\| Product \| Product team \| Funnel metrics, feature adoption, retention \| Daily / weekly \| +\| Marketing \| Marketing team \| Acquisition by channel, CAC, attribution \| Daily / weekly \| +\| Operations \| Ops / on-call \| Performance, errors, capacity \| Real-time \| +\| Custom (per team) \| Specific team \| Their specific KPIs \| Their cadence \| + +### 4. Attribution and segmentation + +How to connect cause and effect. + +Attribution models: + +- First-touch. Credit the first interaction. Useful for awareness understanding. +- Last-touch. Credit the final interaction before conversion. Default in many tools, often misleading. +- Linear. Spread credit equally across touches. Avoids over-crediting any single channel. +- Time-decay. Recent touches get more credit. Reasonable middle ground. +- Position-based. First and last get more credit, middle touches less. +- Data-driven (algorithmic). Tools like Google Analytics 4 use ML. Black box but increasingly the default. + +For most businesses: pick one primary attribution model, use multiple secondary models for validation. + +Segmentation principles: + +- Segment by what causes different behavior, not by what's easy to track +- Useful segments: source/channel, plan tier, geography, device, cohort (signup date) +- Less useful: demographic guesses without behavioral validation + +--- + +## The tracking plan document + +Output of the analytics strategy. A living document. + +Structure: + +1. Goals and KPIs. Business objectives, north star, KPI hierarchy. +2. Event catalog. Every event, with properties, when fired, why tracked. +3. User properties. Persistent attributes (plan, signup_date, role). +4. Page taxonomy. Page categories, page properties. +5. Naming conventions. Snake_case, verb_noun, etc. +6. Implementation notes. Client-side vs server-side, SDK details, sampling. +7. Privacy and compliance. PII rules, consent handling, data retention. +8. Governance. Who can add events, review process, change log. + +--- + +## Workflow + +1. Define the questions. What does the team need to answer? Working backward from questions to metrics works better than starting from metrics. +2. Define the north star. One metric. Tested against the criteria above. +3. Build the KPI hierarchy. Acquisition, activation, engagement, retention, monetization. +4. Audit existing tracking. What's there? What's broken? What's missing? +5. Design the event taxonomy. Cover the user journey. Document everything. +6. Implement with care. Test each event. Verify properties. Catch issues in staging. +7. Build dashboards. One per audience. Lead with action. +8. Establish review cadence. Weekly business review, monthly KPI review, quarterly strategy review. +9. Govern. Who adds events, who reviews, how changes propagate. + +--- + +## Failure patterns + +- Tracking everything. Noise overwhelms signal. +- Tracking nothing strategic. Page views and that's it. Cannot answer real questions. +- No documentation. Tracking plan lives in someone's head. +- Inconsistent naming. Same concept, three names. Reports become detective work. +- Events fired but never reviewed. Tracking debt accumulates. +- Dashboards no one looks at. Built for vanity, not decisions. +- Single attribution model treated as truth. All models lie. Some lie usefully. +- PII in events. Compliance and tooling problems. +- Client-side only. Critical business events should be server-side too. Ad blockers, network issues, edge cases lose client-side events. +- No connection to business outcomes. Metrics exist in a silo, never connected to revenue, retention, or strategic decisions. + +--- + +## Output format + +Default output: a markdown tracking plan at `analytics-tracking-plan.md` plus a dashboard inventory. + +Tracking plan structure: + +```markdown +# Tracking Plan + +## North star metric +[Definition, calculation, target] + +## KPI hierarchy +[Each KPI with definition, calculation, owner] + +## Event catalog +\| Event \| When fired \| Properties \| Owner \| Status \| +\|---\|---\|---\|---\|---\| +\| user_signed_up \| After successful signup form submit \| source, plan, referrer \| Marketing \| Live \| +\| project_created \| When user clicks Create Project \| project_type, template_used \| Product \| Live \| +\| ... \| \| \| \| \| + +## User properties +[List with definitions] + +## Naming conventions +[Rules] + +## Privacy and compliance +[Rules] + +## Governance +[Process] +``` + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Starter event catalog with patterns for common product types. diff --git a/skills/analytics-strategy/references/event-taxonomy-template.md b/skills/analytics-strategy/references/event-taxonomy-template.md new file mode 100644 index 0000000..69e22bb --- /dev/null +++ b/skills/analytics-strategy/references/event-taxonomy-template.md @@ -0,0 +1,407 @@ +# Event Taxonomy Template + +Starter event catalogs for common product types. Adapt to specific products. The patterns generalize. + +--- + +## Universal events (most products need these) + +### Lifecycle events + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `user_signed_up` \| New account created \| signup_method, source, referrer, plan \| +\| `user_logged_in` \| Successful login \| login_method \| +\| `user_logged_out` \| Session ended \| session_duration \| +\| `user_deleted_account` \| Account deletion \| reason (if collected) \| + +### Product/feature engagement + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `feature_used` \| Specific feature interaction \| feature_name, feature_version \| +\| `setting_changed` \| User changes a setting \| setting_name, old_value, new_value \| +\| `notification_clicked` \| User clicks a notification \| notification_type, notification_id \| + +### Errors + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `error_occurred` \| Anywhere an error is shown to user \| error_type, error_message, page, action_attempted \| +\| `form_validation_failed` \| Form submit blocked by validation \| form_name, fields_with_errors \| + +### Communication + +\| Event \| When fired \| Common properties \| +\|---\|---\|---\| +\| `email_received` \| Email delivered (server-side, via ESP webhook) \| email_type, campaign_id \| +\| `email_opened` \| Email opened (via tracking pixel) \| email_type, campaign_id \| +\| `email_clicked` \| Link in email clicked \| email_type, campaign_id, link_text \| +\| `email_unsubscribed` \| User unsubscribes \| email_type \| + +--- + +## SaaS / B2B product events + +``` +Acquisition +├── user_signed_up +├── trial_started +└── trial_extended + +Activation (the "aha" moment) +├── workspace_created +├── teammate_invited +├── first_project_created +├── first_integration_connected +└── first_value_action (product-specific - the moment user gets value) + +Engagement +├── session_started +├── project_opened +├── workflow_completed +└── feature_X_used (one per key feature) + +Conversion +├── plan_upgraded +├── seats_added +├── invoice_paid +└── annual_plan_purchased + +Retention +├── returned_after_inactivity +├── reactivated_from_email +└── usage_milestone_hit (e.g., crossed 100 actions) + +Risk signals +├── support_ticket_opened +├── billing_failure_occurred +├── trial_expiring_soon (calculated, server-side) +└── churn_risk_threshold_hit (calculated) +``` + +### Properties to capture across all events + +``` +user_id Persistent across sessions +session_id New per session +account_id For multi-user accounts +plan Current plan tier +days_since_signup +device_type +browser +os +geo_country +geo_region +referrer +utm_source / utm_medium / utm_campaign / utm_term / utm_content +``` + +--- + +## Ecommerce events + +``` +Discovery +├── page_viewed +├── search_performed +├── search_results_viewed +├── filter_applied +└── product_listing_viewed + +Consideration +├── product_viewed +├── product_image_zoomed +├── size_selected +├── color_selected +├── reviews_read +└── product_shared + +Cart +├── product_added_to_cart +├── product_removed_from_cart +├── cart_viewed +├── cart_quantity_changed +└── cart_abandoned (calculated, server-side) + +Checkout +├── checkout_started +├── shipping_info_entered +├── billing_info_entered +├── promo_code_applied +├── promo_code_failed +├── checkout_step_viewed (with step_name) +└── purchase_completed + +Post-purchase +├── order_shipped +├── order_delivered +├── product_returned +├── review_submitted +└── reorder_initiated +``` + +### Ecommerce-specific properties + +``` +For purchase_completed: + order_id + total_value + currency + shipping_method + payment_method + discount_applied + items: [ + { product_id, product_name, category, brand, variant, quantity, unit_price } + ] + +For product_viewed: + product_id + product_name + category + brand + price + in_stock + position (when viewed in a list) +``` + +--- + +## Content site / publisher events + +``` +Reading +├── page_viewed +├── article_started (when article body enters viewport) +├── article_25_percent_scrolled +├── article_50_percent_scrolled +├── article_75_percent_scrolled +├── article_100_percent_scrolled (read to end) +└── article_time_spent (calculated on page exit) + +Engagement +├── newsletter_signup_shown +├── newsletter_signup_completed +├── comment_posted +├── article_shared +├── article_bookmarked +└── related_article_clicked + +Subscription (if metered/paywalled) +├── paywall_hit +├── paywall_dismissed +├── subscribe_started +├── subscribe_completed +├── article_unlocked (free, registered, paid) +``` + +### Content-specific properties + +``` +For article events: + article_id + article_title + category + author + published_date + word_count + paywall_status (free, registered_only, paid_only) + is_premium +``` + +--- + +## Marketplace events + +Marketplaces have two-sided tracking: buyers and sellers/providers. + +``` +Buyer side +├── search_performed +├── listing_viewed +├── inquiry_sent +├── booking_started +├── booking_completed +├── review_left +└── repeat_booking_made + +Seller/provider side +├── listing_created +├── listing_published +├── listing_edited +├── inquiry_received +├── inquiry_responded +├── booking_received +├── booking_completed +├── payout_received +└── review_received +``` + +### Marketplace-specific properties + +``` +For listing_viewed: + listing_id + category + price + location + seller_id + position_in_search + +For booking_completed: + booking_id + listing_id + seller_id + buyer_id + total_value + fee_amount +``` + +--- + +## Mobile app events + +``` +App lifecycle +├── app_installed (server-side or attribution platform) +├── app_first_opened +├── app_opened (every launch) +├── app_backgrounded +├── app_foregrounded +└── app_uninstalled (often inferred, hard to track directly) + +Engagement +├── push_notification_received +├── push_notification_opened +├── deep_link_opened +└── share_extension_used + +Permissions +├── permission_requested (push, location, camera, etc.) +├── permission_granted +└── permission_denied +``` + +### Mobile-specific properties + +``` +app_version +app_build +device_model +os_version +network_type (wifi, cellular) +push_token +notification_permission_status +``` + +--- + +## Forms and surveys + +``` +Form lifecycle +├── form_viewed +├── form_started (first field interaction) +├── form_field_focused +├── form_field_completed +├── form_field_validation_failed +├── form_submitted +└── form_abandoned (left page without submit) +``` + +### Properties + +``` +form_name +form_id +fields_total +fields_completed +fields_with_errors +time_spent_seconds +``` + +--- + +## Naming convention rules + +### Verb_noun, past tense, snake_case + +✓ `user_signed_up` +✓ `product_added_to_cart` +✓ `article_50_percent_scrolled` +✗ `signupCompleted` +✗ `addProduct` +✗ `Article 50% Scrolled` + +### Properties: camelCase or snake_case (pick one and stay) + +snake_case is more common in SQL contexts (data warehouses). +camelCase is more common in JavaScript/TypeScript contexts. +The choice matters less than consistency. + +✓ `user_id`, `signup_method`, `email_type` (consistent snake_case) +✓ `userId`, `signupMethod`, `emailType` (consistent camelCase) +✗ `userId`, `signup_method`, `EmailType` (mixed) + +### Property values: standardize where possible + +Don't allow free-text where an enum should exist. + +✓ `signup_method: "email" \| "google" \| "github" \| "sso"` +✗ `signup_method: "email", "Email", "EMAIL", "via email", "with email address"` + +### Reserved properties + +Most analytics tools have built-in properties. Don't override them. + +Common reserved names: +- `id`, `userId` (or system equivalent) +- `event`, `event_name` +- `timestamp`, `time` +- `session_id` +- `anonymous_id` +- `properties`, `traits` + +--- + +## What NOT to track + +- PII in event properties. Email, phone, full name, address. Privacy issue and tooling issue. +- Every click. Track meaningful clicks. Hover events. Mouse movements. Generic interactions are noise. +- Server-side state churn. Background jobs, cron runs, internal events. These belong in monitoring, not product analytics. +- Anything you cannot define in one sentence. If you can't describe what the event represents, you won't be able to use it. + +--- + +## Privacy and consent + +Common compliance patterns: + +- Consent before tracking. Cookie banner, opt-in flow. +- Honor Do Not Track. Browsers signal preferences. +- Right to deletion. User can request all their data deleted (GDPR, CCPA). +- Right to export. User can request their data in machine-readable format. +- No cross-site tracking without consent. Some jurisdictions require explicit opt-in. +- Data residency. EU user data may need to stay in EU. + +Standard compliance approaches: + +- Server-side tagging when available (more reliable, more controllable) +- Consent management platform (CMP) for cookie consent +- Clear privacy policy that lists what you collect +- A pseudonymous user ID separate from PII + +Compliance specifics vary by jurisdiction. Consult counsel for high-stakes decisions. + +--- + +## Governance and review + +Patterns that work: + +- New events require an RFC or short proposal +- Event catalog reviewed quarterly +- Deprecated events flagged and removed after a grace period +- Tracking plan version-controlled (in Git) +- Implementation tested in staging before production +- Monitoring on event volume (sudden drops = tracking break) diff --git a/skills/art-direction/SKILL.md b/skills/art-direction/SKILL.md new file mode 100644 index 0000000..65e9452 --- /dev/null +++ b/skills/art-direction/SKILL.md @@ -0,0 +1,198 @@ +--- +name: art-direction +description: "Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables." +category: design +catalog_summary: "Photography, illustration, and visual direction for campaigns" +display_order: 3 +--- + +# Art Direction + +Direct creative work that extends the brand into specific deliverables. Photography, illustration, video, motion, campaigns, environmental design. + +This skill assumes brand identity is approved (`brand-identity` complete). Art direction is about applying and extending it, not defining it. + +--- + +## When to use + +- Briefing photographers, illustrators, videographers +- Developing campaign creative concepts +- Directing in-house creative teams +- Writing creative direction documents for vendors +- Evaluating creative deliverables for brand fit +- Adapting brand visual identity to a new format or context + +## When NOT to use + +- Setting project-wide aesthetic direction across multiple downstream skills (use `creative-direction` instead). This skill briefs specific creative deliverables; `creative-direction` produces the structured aesthetic brief that this skill consumes. +- Defining brand visual identity from scratch (use `brand-identity`) +- Day-to-day component design (use `design-standards`) +- Writing copy for creative work (use `content-and-copy` or `landing-page-copy`) +- Building a design system (use `design-system`) + +--- + +## Required inputs + +- The deliverable (photo shoot, illustration set, video, campaign) +- The brand identity (visual system, voice, imagery direction) +- The audience for this specific work +- The goal (brand awareness, conversion, education, emotional connection) +- Budget and timeline +- Distribution context (where it will be seen) + +--- + +## The framework: 5 layers + +A creative brief covers five layers. Each must be clear before the brief leaves your hands. + +### 1. The story + +What this creative work is fundamentally about. + +- The premise. The core idea in one sentence. +- The emotional through-line. What the audience feels. +- The role of the brand. How the brand shows up in the story. +- The takeaway. What the audience walks away with. + +A weak premise produces work that's pretty but says nothing. Spend time here. + +### 2. The look + +The visual treatment. + +For photography: +- Subject and composition (close-up, environmental, candid, posed) +- Lighting (natural, studio, dramatic, soft) +- Color palette (true color, treated, monochrome) +- Locations (specific or general direction) +- Wardrobe and props +- Mood references (3 to 5 reference images) + +For illustration: +- Style (flat, dimensional, hand-drawn, geometric, abstract) +- Color use (full palette, restricted, brand-only) +- Line treatment +- Composition style +- Detail level +- Reference artists or works (with explicit "we want like X but NOT like Y") + +For video / motion: +- Pacing (slow, medium, fast cuts) +- Camera movement (static, handheld, sweeping) +- Color grading +- Transitions and effects +- Audio direction (music, voiceover, ambient) +- Reference work (3 to 5 examples) + +### 3. The execution + +Production-level direction. + +Specifications: +- Deliverable formats and sizes (web hero, social square, print full-page) +- Required shots or frames +- Optional shots if budget allows +- Wardrobe and prop list (for live action) +- Color and asset specs (RGB, CMYK, hex codes for matching) + +Constraints: +- Things to avoid (specific cliches, forbidden treatments, regulatory) +- Brand-system requirements (logo placement, color use, type rules) + +### 4. The variants + +How this creative scales across distribution. + +Most creative needs to live in multiple places. Plan the variants up front. + +Common variant set for a campaign: +- Hero web image (16:9 or wider) +- Mobile web hero (4:5 or 1:1) +- Social square (1:1) +- Social vertical (9:16) +- Email banner (3:1 typical) +- Display ad sizes (300x250, 728x90, etc.) +- Print sizes if applicable + +For each variant, note: how the composition adapts, what gets cropped or repositioned, what assets are required. + +### 5. The standards + +The quality bar. + +Technical: +- Resolution and format requirements +- Color profile +- File naming conventions +- Delivery format (raw + edited, layered files, exported variants) + +Creative: +- What "approved" looks like (specific examples of acceptable work) +- What "not approved" looks like (specific examples to avoid) +- Number of revision rounds budgeted + +--- + +## Workflow + +### For briefing external creative + +1. Confirm the inputs. Brand identity locked. Audience and goal clear. Budget and timeline known. +2. Develop the concept. Premise, emotional through-line, takeaway. +3. Build the look. Mood references. Specific direction on style elements. +4. Write the spec. Production-level direction. Variants. Constraints. +5. Brief the vendor. In writing. Walk through it live. Allow questions. +6. Review milestones. Treatment review, halfway review, final review. Don't skip the early reviews; corrections compound. +7. Approve and document. What was produced, what's licensed for what use. + +### For directing in-house creative + +1. Same brief, lighter format. In-house direction can be more iterative. Still document the brief. +2. Co-create. In-house teams know the brand. Use their judgment. Don't over-direct. +3. Establish review rhythm. Daily check-ins for fast work, weekly for longer projects. + +### For evaluating existing creative + +1. Score against the brief. Did the work hit the brief? Where did it deviate? +2. Score against the brand. Does this look like the brand? Could this be confused with a competitor? +3. Score against the goal. Will this drive the intended outcome? +4. Identify fixes. What can be improved? What's a deal-breaker vs. acceptable? + +--- + +## Failure patterns + +- "Modern, clean, minimal" briefs. Means nothing. Force specificity. Use specific reference brands, named artists, or visual examples. +- No "what to avoid" direction. Vendors interpret broadly. Tell them what's out of bounds explicitly. +- Reference imagery that's actually competitor work. You'll get something that looks like the competitor. Never use direct competitors as references. +- Skipping early reviews. Every revision late in the process is 5x more expensive than catching issues at treatment stage. +- Too many cooks. 6 stakeholders all giving creative feedback produces incoherent work. Concentrate creative authority. +- Ignoring distribution. Creative that doesn't work in the actual contexts where it will live is failed creative. +- No variant planning. Discovering at delivery that you need a square crop and the photographer composed for 16:9 only. +- Approving creative that's "fine." Fine is the enemy of distinctive. If it doesn't move you, it won't move the audience. + +--- + +## Output format + +Default output is a creative brief at `creative-brief-[project].md`. + +Structure: +1. The story (premise, through-line, role of brand, takeaway) +2. The look (visual treatment with references) +3. The execution (specs, variants, constraints) +4. The standards (quality bar, examples of acceptable and unacceptable) +5. The logistics (timeline, milestones, budget, deliverables) + +Plus a separate moodboard or visual reference doc with images. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Generic art direction brief template covering any production type (photo, illustration, video, animation, mixed). +- [`references/photo-shoot-brief.md`](references/photo-shoot-brief.md) - Detailed brief template for photography commissions. +- [`references/illustration-brief.md`](references/illustration-brief.md) - Brief template for illustration commissions. diff --git a/skills/art-direction/references/creative-brief-template.md b/skills/art-direction/references/creative-brief-template.md new file mode 100644 index 0000000..feb2406 --- /dev/null +++ b/skills/art-direction/references/creative-brief-template.md @@ -0,0 +1,249 @@ +# Art Direction Brief Template + +A fillable brief for art direction projects. Fill every section before production begins. A short brief beats a generic brief; a generic brief produces generic work. + +--- + +## Project: [Name] + +Project type: [Photography / Illustration / Video / Animation / Mixed] +Channel(s): [Where this will live] +Date briefed: [YYYY-MM-DD] +Production date: [YYYY-MM-DD] +Director: [Name] +Producer: [Name] +Budget: [Range] + +--- + +## 1. Project context + +Why this project exists: +[1 to 2 paragraphs. The business reason this work needs to be made.] + +What it must accomplish: +[The specific outcome. Awareness, conversion, brand association, internal use, etc.] + +How it will be measured: +[Concrete success indicator. Engagement, completion rate, brand lift, internal feedback.] + +--- + +## 2. Concept + +The big idea (one sentence): +[The angle, insight, or opinion the creative work expresses.] + +Why this concept now: +[2 to 3 sentences. Why this idea fits the moment, the brand, and the audience.] + +What this concept rejects: +[The opposite or adjacent ideas this concept is not.] + +--- + +## 3. Audience + +Primary audience: +[Specific persona. "Mid-career operator at a B2B SaaS company evaluating tools for their team," not "B2B buyers."] + +What they currently feel about the category: +[1 to 2 sentences.] + +What we want them to feel after seeing this: +[1 to 2 sentences.] + +--- + +## 4. Subjects + +People: +- Cast: [Demographics, archetypes, specific casting direction] +- Wardrobe: [Direction] +- Expression: [What we want them showing] +- Diversity: [Explicit casting expectations] + +Products: +- What appears: [List] +- Staging: [How they're shown] +- Hierarchy: [Hero product vs supporting] + +Settings: +- Locations: [Specific or category] +- Environment: [Indoor/outdoor, real/built, public/private] +- Time of day: [If relevant] + +Objects/props: +- Required: [Specific items] +- Forbidden: [Things never to include] + +--- + +## 5. Composition + +Formats and channels: +\| Channel \| Aspect ratio \| Resolution \| Specific requirements \| +\|---\|---\|---\|---\| +\| [e.g., Instagram feed] \| 1:1 \| [px] \| [Crop-safe area for text overlay] \| +\| [e.g., Instagram stories] \| 9:16 \| [px] \| [Top/bottom safe areas] \| +\| [e.g., Web hero] \| 16:9 \| [px] \| [Subject must allow text overlay on left] \| +\| [e.g., Print] \| [Specific] \| [DPI] \| \| + +Shot list: +[Specific shots required. Include reference frame for each.] + +1. [Shot description]: [Reference image] +2. [Shot description]: [Reference image] +3. [Shot description]: [Reference image] + +Framing direction: +- Crop tendency: [Tight / medium / wide] +- Subject placement: [Centered / off-center / dynamic] +- Eye line: [To camera / away / unspecified] +- Depth: [Foreground emphasis / background environment / flat] +- Negative space: [Generous / minimal / variable] + +--- + +## 6. Lighting + +Direction: +[2 to 4 sentences describing the lighting approach.] + +Specific qualities: +- Source: [Natural / available / controlled] +- Direction: [Front / side / back / overhead] +- Quality: [Hard / soft] +- Color temperature: [Warm / neutral / cool] +- Time of day if natural: [Specific] + +Lighting references: +[3 to 5 reference images with annotations.] + +--- + +## 7. Color and treatment + +Color palette: +[Brand palette + any campaign-specific extensions] + +Treatment direction: +- Saturation: [True / muted / desaturated / heightened] +- Contrast: [Low / balanced / high] +- Color grade: [Specific look or signature] +- Film references: [Specific films, photographers, or art if relevant] + +Treatment references: +[3 to 5 reference images with annotations.] + +--- + +## 8. Tone + +Adjectives (3 to 5): +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] +- [Adjective], not [opposite tendency] + +Pacing (moving image): +[If applicable: brisk / deliberate / breathless / languid] + +Sound direction (moving image): +[If applicable: score, sound design, voice, silence] + +--- + +## 9. Reference moodboard + +[Link to moodboard with 10 to 15 curated images.] + +Each reference labeled with what we are taking from it (composition, lighting, treatment, casting, etc.). Avoid using a single reference for everything; pull specific elements from different sources. + +--- + +## 10. What to avoid + +Visual cliches in our category to reject: +- [Specific cliche with example] +- [Specific cliche with example] +- [Specific cliche with example] + +Treatments not aligned with our direction: +- [Specific treatment] +- [Specific treatment] + +Casting we will not use: +- [Specific casting type and why] + +--- + +## 11. Deliverables + +Final deliverables required: + +\| Asset \| Format \| Count \| Specifications \| +\|---\|---\|---\|---\| +\| [e.g., Hero image] \| JPG, PNG \| 5 \| 16:9, 4K \| +\| [e.g., Story crops] \| MP4 \| 10 \| 9:16, 1080p, 15s max \| +\| [e.g., Behind-the-scenes] \| MP4 \| 1 \| 16:9, 60s \| + +Editing/retouching specifications: +[Color grading approach, retouching rules, watermarking, captions] + +File naming convention: +[`project-asset-version-channel.format`] + +Delivery method: +[How files arrive. Drive, DAM, direct upload.] + +--- + +## 12. Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Pre-production complete \| \| \| +\| Production day(s) \| \| \| +\| Selects review \| \| \| +\| Edit v1 / first cut \| \| \| +\| Final delivery \| \| \| + +--- + +## 13. Approvals + +Approval path: +1. [Person / role] - [What they approve] +2. [Person / role] - [What they approve] +3. [Final approver] + +Maximum review rounds: [Typically 2 to 3] +Hard stop: [Date after which changes are out of scope] + +--- + +## 14. Talent + +Photographer / Illustrator / Director: [Name and rate] +Why we picked them: [1 to 2 sentences linking their portfolio to this brief] +Crew: [Producer, stylist, lighting, etc.] +Talent (on-camera): [Casting decisions] + +--- + +## 15. Open questions + +[Anything unresolved at brief-writing time. Resolve before production day.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: +- [Name] [Date] +- [Name] [Date] + +Production day(s) confirmed: [Date] diff --git a/skills/art-direction/references/illustration-brief.md b/skills/art-direction/references/illustration-brief.md new file mode 100644 index 0000000..46bba36 --- /dev/null +++ b/skills/art-direction/references/illustration-brief.md @@ -0,0 +1,238 @@ +# Illustration Brief + +A complete brief for commissioning illustration work. Use as a starting template, fill out fully before sending to the illustrator. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a redo (and most illustrators charge for redos). + +--- + +## Project overview + +Project name: [Working title] +Date of brief: [YYYY-MM-DD] +Delivery deadline: [Final files due] +Illustrator / studio: [If selected] +Producer / point of contact: [Name and contact] +Budget: [Total or per-illustration rate] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is each illustration fundamentally about?] + +### Audience +[Who will see these illustrations. Their context, their state of mind.] + +### Goal +[What do these illustrations accomplish? Editorial illustration, brand storytelling, product visualization, instruction, decoration?] + +### Brand role +[How does the brand show up? Subtle (illustrations stand on their own), prominent (brand mark visible in scene), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Playful," "considered," "warm," "sharp," "optimistic."] + +--- + +## The look + +### Style references + +[5 to 10 reference illustrations. Source: illustrator portfolios (Behance, It's Nice That, Cargo), editorial illustration archives, ad campaigns. AVOID: direct competitor imagery, AI-generated images, copyrighted character work used out of context.] + +For each reference, note WHAT to take from it: +- "From this illustration: the loose hand-drawn line quality" +- "From this illustration: the limited color palette" +- "From this illustration: the flat geometric construction" + +NOT just dumping references with no commentary. The illustrator needs to know which qualities matter. + +### What to AVOID + +- [Specific style cliche to avoid, e.g., "Corporate Memphis / Alegria figures"] +- [Specific style cliche to avoid, e.g., "isometric tech-startup spot illustrations"] +- [Visual treatment that's been overused in the category] + +### Style and technique + +- Medium: [Vector / raster / mixed / hand-drawn scanned / 3D] +- Line quality: [Geometric and clean / loose and gestural / no line / variable] +- Fill style: [Flat / textured / gradients / cross-hatching / watercolor] +- Detail level: [Highly detailed / minimal / mid] +- Perspective: [Flat / isometric / one-point / loose / mixed] +- Figure style (if illustrating people): [Realistic / stylized / abstract / no figures] + +### Color + +- [Specific palette with hex codes if matching brand] +- [Number of colors: limited (2-3), moderate (4-6), full] +- [Treatment: brand-matched / shifted / monochrome / sepia / saturated / muted] + +### Composition + +- [Single subject focus / scene with multiple elements / pattern / decorative] +- [Negative space treatment] +- [Orientation defaults: square, landscape, portrait, mixed] + +--- + +## Illustration list + +A specific list of illustrations needed. Each entry is a deliverable. + +### Required illustrations (must-have) + +1. [Illustration name] + - Subject: [What's depicted] + - Concept: [What it should communicate or evoke] + - Use case: [Where it will appear, e.g., "blog post hero, 1200x675"] + - Variants: [Aspect ratios or color modes needed] + +2. [Illustration name] + - Subject: + - Concept: + - Use case: + - Variants: + +[Continue for all required illustrations] + +### Optional illustrations (if time and budget allow) + +1. [Illustration name] +2. [Illustration name] + +### Variants per illustration + +Most illustrations need to work in multiple contexts: + +- Light mode and dark mode: does the illustration need a dark-background variant? +- Aspect ratios: which crops are needed (16:9, 1:1, 9:16, banner)? +- Resolution variants: retina vs standard, social vs hero +- Cropped vs full: is a cropped detail of the same illustration also needed? +- Animation: is a static illustration plus a looping animated version needed? + +When briefing, note which variants each illustration must support. + +--- + +## Technical specs + +### Source files + +- Format: [AI / SVG / PSD / PNG layered / Procreate / Figma] +- Layered structure required: [Yes - so the brand can adjust colors, swap elements, or animate later. No - flat delivery only.] +- Editability: [Editable text and shapes preferred / OK to outline] + +### Export formats + +- Web: [SVG for vector, WebP / PNG for raster] +- Print: [If applicable: CMYK, 300 DPI, with bleed] +- Resolution: [Specific minimums per use case] +- Color profile: [sRGB for web, CMYK for print] + +### Delivery + +- Format: [Cloud delivery, file sharing, hard drive] +- Naming convention: [e.g., "ProjectName_IllustrationN_VariantX.svg"] +- Asset management: [Where the files live after delivery] + +### Licensing + +- Usage: [Where the illustrations can be used; web, print, paid media, all media, in perpetuity] +- Term: [Duration of license; usually 1 year, 2 years, or perpetual] +- Geography: [Worldwide, US-only, etc.] +- Exclusivity: [Exclusive to brand, or illustrator can include in portfolio? Most illustrators want portfolio rights even on exclusive work.] +- Modification rights: [Can the brand modify the illustration in-house, or does any change require returning to the illustrator?] +- NFT / generative AI training: [Explicitly state whether the illustrator can use the work to train AI, and whether the brand can.] + +--- + +## Process and milestones + +### Stages and approvals + +A typical illustration commission moves through these stages. Define what each milestone delivers and who approves. + +\| Stage \| What is delivered \| Who approves \| +\|---\|---\|---\| +\| Brief approved \| This document, signed \| Brand lead \| +\| Sketches / thumbnails \| 2-3 rough directions per illustration \| Brand lead + creative director \| +\| Refined sketch \| Single chosen direction, more detail \| Brand lead + creative director \| +\| Color and style test \| One illustration finalized as reference \| Brand lead + creative director \| +\| Final illustrations \| All deliverables, in all variants \| Brand lead \| +\| Files handed over \| Source + exports, organized \| Brand lead \| + +### Revision rounds + +- Sketch round 1: [What is in scope. Typically composition and concept. Major changes are easier here.] +- Sketch round 2: [Refinement only. Style and composition are locked.] +- Final art rounds: [Typically 1 round of small adjustments. Beyond this, usually billed separately.] +- Beyond included rounds: [Cost or process for additional rounds.] + +### Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Brief approved \| \| \| +\| Sketches delivered \| \| \| +\| Sketch sign-off \| \| \| +\| First finished illustration \| \| \| +\| Style sign-off \| \| \| +\| Remaining illustrations delivered \| \| \| +\| Final files handed over \| \| \| + +--- + +## Budget breakdown + +\| Item \| Cost \| Notes \| +\|---\|---\|---\| +\| Illustrator fee (base) \| \| \| +\| Per-illustration rate \| \| \| +\| Style test / first finish \| \| \| +\| Revisions beyond included rounds \| \| \| +\| Rush fees (if applicable) \| \| \| +\| License fees (if separate from base) \| \| \| +\| Source file delivery (if separate) \| \| \| +\| Total \| \| \| + +--- + +## Approval process + +### Who approves at each stage + +- Brief: [Name] +- Sketches: [Names] +- Style test: [Names] +- Final illustrations: [Name] +- Final delivery: [Name] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Illustrator credit: [Required / optional / no credit. Typical: credit required where editorial use, optional where commercial.] +- Promotion: [Illustrator can / cannot promote on their own portfolio. Typical: yes after the work is publicly launched.] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/skills/art-direction/references/photo-shoot-brief.md b/skills/art-direction/references/photo-shoot-brief.md new file mode 100644 index 0000000..c3efba1 --- /dev/null +++ b/skills/art-direction/references/photo-shoot-brief.md @@ -0,0 +1,255 @@ +# Photo Shoot Brief + +A complete brief for commissioning a photo shoot. Use as a starting template, fill out fully before sending to the photographer. + +The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a reshoot. + +--- + +## Project overview + +Project name: [Working title] +Date of brief: [YYYY-MM-DD] +Shoot date(s): [Target dates] +Location(s): [Specific or "TBD - photographer recommends"] +Photographer / studio: [If selected] +Producer / point of contact: [Name and contact] +Budget: [Total or range] + +--- + +## The story + +### Premise +[The core idea in one sentence. What is this shoot fundamentally about?] + +### Audience +[Who will see these images. Be specific. Their context, their state of mind.] + +### Goal +[What do these images accomplish? Brand awareness? Conversion? Emotional connection? Editorial illustration?] + +### Brand role +[How does the brand show up? Subtle (it's about the people), prominent (the product is the hero), or in-between?] + +### The feeling +[3 to 5 adjectives describing the emotional through-line. "Confident," "intimate," "celebratory," "considered," "energetic."] + +--- + +## The look + +### Visual references + +[5 to 10 reference images. Source: photographers' portfolios, ad campaigns, editorial work. AVOID: direct competitor imagery.] + +For each reference, note WHAT to take from it: +- "From this image: the soft natural light" +- "From this image: the close composition on hands" +- "From this image: the muted color palette" + +NOT just dumping references with no commentary. + +### What to AVOID + +- [Specific visual cliche to avoid, e.g., "Stock-photo-style smiling at camera"] +- [Specific visual cliche to avoid] +- [Visual treatment that's been overused in the category] + +### Lighting + +- [Natural / studio / mixed] +- [Soft and diffused / dramatic and directional / high-contrast / low-contrast] +- [Time of day if natural] + +### Color + +- [True color / treated / monochrome / desaturated] +- [Specific color palette or mood, with hex codes if matching brand] + +### Composition + +- [Tight crops vs. wide environments] +- [Symmetrical vs. asymmetrical] +- [Subject placement preferences] +- [Portrait vs. landscape orientation defaults] + +### Wardrobe and styling + +- [Casual / formal / specific style direction] +- [Color preferences for wardrobe] +- [Things to avoid (logos other than ours, distracting patterns, etc.)] + +### Subjects / talent + +- [Demographics and casting direction] +- [Specific talent if cast, or open call criteria] +- [Diversity considerations] +- [Number of subjects per shot] + +### Props and set + +- [Required props] +- [Set direction (clean, lived-in, organized, chaotic, etc.)] +- [Branded elements (yes / no / minimal)] + +--- + +## Shot list + +A specific list of shots needed. Each entry is a shot the photographer must deliver. + +### Required shots (must-have) + +1. [Shot name] + - Description: [What's in the frame] + - Composition: [Tight, wide, environmental] + - Use case: [Where this image will be used, e.g., "homepage hero, 16:9"] + - Quantity: [How many variations] + +2. [Shot name] + - Description: + - Composition: + - Use case: + - Quantity: + +[Continue for all required shots] + +### Optional shots (if time and budget allow) + +1. [Shot name] +2. [Shot name] + +### Variants per shot + +Most shots need to work in multiple aspect ratios. Specify: + +- 16:9 (wide): for web hero, video thumbnails +- 4:5 (vertical): for social, mobile hero +- 1:1 (square): for Instagram, app icons, avatars +- 9:16 (vertical extreme): for Stories, vertical video + +When briefing, note which aspect ratios each shot must support. Photographer composes accordingly (loose enough to crop multiple ways, OR shoots specifically for each crop). + +--- + +## Technical specs + +### Resolution and format + +- Minimum resolution: [e.g., 6000x4000] +- File format: [RAW + edited high-res JPG / TIFF] +- Color profile: [sRGB / Adobe RGB] +- Color space: [Web vs. print] + +### Editing + +- Editing scope: [Color correction only / full retouch / specific retouch needs] +- Editing reference: [Examples of approved final-look] + +### Delivery + +- Format: [Cloud delivery, file sharing, hard drive] +- Naming convention: [e.g., "ProjectName_ShotN_VariantX.jpg"] +- Asset management: [Where the files live after delivery] + +### Licensing + +- Usage: [Where the images can be used; web, print, paid media, all media, in perpetuity] +- Term: [Duration of license; usually 1 year, 2 years, or perpetual] +- Geography: [Worldwide, US-only, etc.] +- Exclusivity: [Exclusive to brand, or photographer can include in portfolio?] + +--- + +## Logistics + +### Timeline + +\| Milestone \| Date \| Owner \| +\|---\|---\|---\| +\| Brief approved \| \| \| +\| Treatment / mood board sign-off \| \| \| +\| Casting / location finalized \| \| \| +\| Shoot day(s) \| \| \| +\| Selects delivered \| \| \| +\| Final edits delivered \| \| \| + +### Budget breakdown + +\| Item \| Cost \| Notes \| +\|---\|---\|---\| +\| Photographer fee \| \| \| +\| Talent \| \| \| +\| Wardrobe / styling \| \| \| +\| Hair / makeup \| \| \| +\| Location fee \| \| \| +\| Set / props \| \| \| +\| Equipment \| \| \| +\| Editing / retouching \| \| \| +\| Production / coordination \| \| \| +\| Contingency (10%) \| \| \| +\| Total \| \| \| + +### Crew + +- Photographer: [Name] +- Photo assistant: [Name] +- Producer: [Name] +- Stylist: [Name] +- Hair / makeup: [Name] +- Talent: [Names] +- Brand reps on set: [Names] + +### Logistics day-of + +- Call time: [Time] +- Wrap time (target): [Time] +- Catering / craft services: [Plan] +- Wet weather plan: [If outdoor] +- Day-of contact list: [Names and numbers] + +--- + +## Approval process + +### Who approves at each stage + +- Brief: [Name] +- Treatment / mood board: [Names] +- Day-of selects: [Names on set or remote review] +- Edited final selects: [Name] +- Final delivery: [Name] + +### Revision rounds + +- Edits round 1: [What's in scope] +- Edits round 2: [What's in scope] +- Beyond round 2: [Cost or process for additional rounds] + +### Use of work + +- All deliverables become brand-owned within the licensing terms above. +- Photographer credit: [Required / optional / no credit] +- Promotion: [Photographer can / cannot promote on their own portfolio] + +--- + +## Open questions + +[Things still being decided.] + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +Brief approved by: + +- [Name, role, date] +- [Name, role, date] + +Once signed off, scope changes require a written change order. diff --git a/skills/backup-and-disaster-recovery/SKILL.md b/skills/backup-and-disaster-recovery/SKILL.md new file mode 100644 index 0000000..3a5c787 --- /dev/null +++ b/skills/backup-and-disaster-recovery/SKILL.md @@ -0,0 +1,268 @@ +--- +name: backup-and-disaster-recovery +description: "Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability." +category: operations +catalog_summary: "RPO/RTO targets, backup strategy, restoration drills" +display_order: 6 +--- + +# Backup and Disaster Recovery + +Plan for the worst case: the database is gone, the host is down for a week, the deploy was poisoned, ransomware encrypted everything. The skill is in advance preparation, not reaction. + +--- + +## When to use + +- Setting up backups for a new system +- Reviewing and validating backup architecture +- Defining RPO (recovery point objective) and RTO (recovery time objective) +- Running a disaster recovery drill +- Diagnosing gaps after an incident +- Planning for ransomware, data corruption, or insider threats +- Migrating to a new platform (DR planning belongs in the migration plan) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Routine deploy rollbacks (use `launch-runbook`) +- Code or content versioning (covered by Git, CMS revision history) +- Routine database snapshots (use this skill to set them up; routine review goes in monitoring) + +--- + +## Required inputs + +- The systems in scope (databases, file storage, code, configs, secrets) +- The hosting platforms and providers +- Existing backup tooling and what it covers +- Tolerance for data loss (in time) +- Tolerance for downtime (in time) +- Compliance requirements (some regulations mandate specific backup standards) + +--- + +## The framework: 4 questions + +Every disaster recovery plan answers four questions explicitly. + +### Question 1: What needs to be recoverable? + +List every system that holds state. Categorize by criticality. + +Tier 1: must recover. Without it, the business stops. (Customer database, transaction log, primary content store.) + +Tier 2: should recover. Loss is painful but not fatal. (Analytics, logs, secondary services.) + +Tier 3: nice to recover. Easy to rebuild. (Caches, derived data, temporary state.) + +The tier drives RPO, RTO, backup frequency, and storage spend. + +### Question 2: How much data loss is acceptable? (RPO) + +RPO is the maximum age of data that's acceptable to lose, measured in time. + +- RPO = 1 hour: hourly backups or continuous replication needed +- RPO = 1 day: daily backups acceptable +- RPO = 1 week: weekly backups acceptable + +For most production data, RPO of 1 hour or less is the target. For critical financial systems, near-zero RPO (continuous replication). + +For derived or rebuildable data, RPO of 1 day or longer is fine. + +### Question 3: How much downtime is acceptable? (RTO) + +RTO is the maximum time to restore service after a disaster. + +\| RTO target \| Implies \| +\|---\|---\| +\| < 5 minutes \| Hot standby with automatic failover \| +\| < 1 hour \| Warm standby with manual failover or fast restore from recent snapshot \| +\| < 24 hours \| Cold backup with documented restore process \| +\| Days to weeks \| Best-effort, accept extended downtime \| + +RTO drives architecture spend. Aggressive RTOs (< 1 hour) are expensive. Loose RTOs (days) are cheap. + +### Question 4: What's the disaster? + +Plan for specific scenarios. Each has different implications. + +Hardware failure. Disk dies. Standard backups solve this. Most modern hosts handle automatically. + +Provider outage. Region or vendor goes down. Cross-region or cross-provider redundancy needed for low RTO. + +Data corruption. Bad migration, bug, accidental delete. Point-in-time restore needed. The latest backup might be corrupted; you need history. + +Ransomware or compromise. Attacker encrypts or deletes. Backups must be immutable or air-gapped, otherwise the attacker takes them too. + +Account compromise. Attacker has admin credentials, deletes everything. Same defense as ransomware: immutable backups, separate access control. + +Vendor lock-out. Account suspended, billing dispute, vendor disappears. Backups outside the vendor needed. + +Insider threat. Disgruntled employee deletes or exfiltrates. Audit logs, separation of duties, immutable backups. + +A backup strategy that handles only hardware failure isn't a strategy. It's the easiest case. + +--- + +## Workflow + +### Step 1: Inventory state + +Every system that holds state goes on a list: + +\| System \| Data type \| Tier \| Current backup \| Tested? \| +\|---\|---\|---\|---\|---\| + +If you can't list it, you can't protect it. Often the inventory itself reveals gaps (the "we forgot about that database" moment). + +### Step 2: Set RPO and RTO per tier + +For each tier, agree on RPO and RTO. Get sign-off from the people who'd be impacted by a disaster. + +Push back on aspirational targets that aren't backed by infrastructure spend. RTO of 5 minutes for a system without a hot standby is not real. + +### Step 3: Verify or design backup architecture + +For each system, ensure: + +- Frequency matches RPO. +- Retention covers point-in-time recovery (typically 30+ days for production data). +- Storage location is separate from the source. Same disk, same account, same region: not enough. +- Immutability or write-once storage for at least some backup copies. Defends against ransomware. +- Encryption at rest. Standard for compliance. +- Tested restore procedure. Untested backups are not backups. + +The "3-2-1 rule" is a useful starting point: 3 copies of data, 2 different storage types, 1 offsite (or off-account, off-platform). + +### Step 4: Document the restore runbook + +For each system, write the runbook: + +1. How to detect the disaster (cross-reference monitoring) +2. How to decide to restore (decision criteria, who authorizes) +3. The exact restore steps (commands, screenshots, sequence) +4. How to verify the restore worked +5. How to switch traffic back +6. Communication template (status page, customer notice) + +The runbook is for the worst night of someone's career. Write it for tired, panicked you. + +### Step 5: Run a drill + +The first restore should never be during a real disaster. + +Drills can be: + +- Tabletop: walk through the runbook on paper. Useful for finding gaps in the plan. +- Partial: restore to a non-production environment. Verify the data, validate the steps. +- Full: simulate the disaster. Production failover or full restore. Maximum confidence, maximum risk. + +For most teams: quarterly tabletop, annual partial drill, full drill before major launches or after major architecture changes. + +### Step 6: Document drill results + +After each drill, document: +- What was tested +- What worked +- What broke +- What the actual RPO and RTO were (vs. targets) +- Action items + +If the actual RTO was 6 hours when the target was 1 hour, the target is fiction. Either fix the gap or revise the target. + +### Step 7: Schedule the next drill + +Calendar it. Assign an owner. Backups that aren't drilled drift toward useless. + +--- + +## Special topics + +### Database point-in-time recovery + +Many managed databases offer point-in-time recovery (PITR) within a retention window (often 7-35 days). This typically achieves RPO of seconds to minutes. + +For longer retention, schedule periodic exports to immutable storage. + +PITR alone isn't enough. If the database service itself is compromised, PITR is gone too. Always have at least one backup outside the source service. + +### File storage backups + +Object stores (S3, GCS, Azure Blob) usually offer: + +- Versioning (recover overwritten objects) +- Replication (cross-region) +- Object lock or immutability (defense against deletion) + +Set all three for production-critical buckets. Don't rely on the storage provider's default retention. + +### Code and config backups + +Code lives in Git. The Git host (GitHub, GitLab, etc.) is your backup, but a single host is a single point of failure. + +For high-criticality code: +- Mirror to a second host or your own server +- Periodic offline exports + +Configs and secrets need separate handling: +- Infrastructure-as-code: in Git, mirrored +- Runtime configs: backed up alongside the system +- Secrets: in a secret manager with its own backup story + +### Backups of backups + +The backup system itself can fail. Backup metadata, backup credentials, encryption keys: all must be backed up. + +If your backup is encrypted with a key you've lost, the backup is useless. + +### Compliance backups + +Some regulations require specific retention (e.g., 7 years for financial data). Comply with the highest applicable standard. + +Don't conflate compliance retention with operational backup. Compliance often allows much slower restore (just need to be able to produce the data eventually). + +--- + +## Failure patterns + +Untested backups. The single most common failure. Backups appear to work; restore fails. Test. + +Backups in the same account or region as the source. Account compromise or region outage takes both. + +No immutability. Ransomware encrypts the backups too. Use object lock or air-gapped storage. + +RTO and RPO that aren't measured. Target says "1 hour" but no one has verified the actual RTO. Assume the actual is longer than the target until proven otherwise. + +Restore runbook only in someone's head. Person leaves or is unavailable; runbook is gone. Document. + +Backups but no DR plan. "We have backups" isn't a plan. The plan is the runbook plus the architecture plus the drilling. + +Optimism bias. "It won't happen to us." It happens. Plan as if it will. + +Backups too old or too new. Want point-in-time history (in case corruption isn't immediately discovered). Daily snapshots with 30+ day retention. Or continuous replication with separate periodic snapshots for history. + +Skipping drills "because we're busy." Then you'll be busier during the disaster. + +No communication plan. Restoring data is half the job. Telling customers, stakeholders, and internal teams what's happening is the other half. + +--- + +## Output format + +A DR plan document includes: + +- Inventory: every stateful system +- Tiering: criticality per system +- Targets: RPO and RTO per tier +- Architecture: backup tooling, frequency, storage, immutability +- Runbooks: restore procedures per system +- Drill schedule: what gets tested when +- Drill log: results of past drills +- Communication templates: what to say during a real DR event + +--- + +## Reference files + +- [`references/restore-runbook-template.md`](references/restore-runbook-template.md): Fillable template for a restore runbook, covering detection, authorization, steps, verification, and rollback. diff --git a/skills/backup-and-disaster-recovery/references/restore-runbook-template.md b/skills/backup-and-disaster-recovery/references/restore-runbook-template.md new file mode 100644 index 0000000..6adf708 --- /dev/null +++ b/skills/backup-and-disaster-recovery/references/restore-runbook-template.md @@ -0,0 +1,231 @@ +# Restore Runbook Template + +Fill out one of these per system that needs to be restorable. The runbook is read by a tired, panicked person at 3am. Optimize for that reader. + +--- + +## System: [System name] + +Owner team: [Team name] +On-call escalation: [Who, how to reach] +Last drill: [YYYY-MM-DD] +Last verified working: [YYYY-MM-DD] + +--- + +## Tier and targets + +\| \| Target \| Last measured \| +\|---\|---\|---\| +\| Tier \| [1 / 2 / 3] \| \| +\| RPO \| [Time] \| [Time] \| +\| RTO \| [Time] \| [Time] \| + +If the last measured RTO is longer than the target, the target needs revision or the architecture needs investment. + +--- + +## What this system does + +[2-3 sentences describing what the system is and why it matters. The reader may not be familiar with this system in a panic.] + +--- + +## What "lost" looks like + +The triggers for using this runbook: + +- [ ] [Specific symptom, e.g., "Database returns errors on all queries"] +- [ ] [Specific symptom, e.g., "Data has been deleted or appears corrupted"] +- [ ] [Specific symptom, e.g., "Provider region is down per their status page"] +- [ ] [Specific symptom, e.g., "Account access is locked or suspended"] + +If none of these match, this might not be the right runbook. Pause and check `incident-response`. + +--- + +## Decision: should we restore? + +Restoring is destructive. Don't do it without authorization. + +Authorize restoration if: +- [Condition 1] +- [Condition 2] +- [Condition 3] + +Do NOT restore if: +- The system is recoverable through less destructive means (failover, replica promotion, partial fix) +- The data loss is recoverable through other channels (event replay, cache rebuild) +- We're not yet sure of the cause (restoring on top of an unknown cause can make things worse) + +Authorization required from: [Role] +Backup authorization from: [Role] + +Document the authorization in the incident channel before proceeding. + +--- + +## Pre-restore checklist + +- [ ] Authorization received and documented +- [ ] Communication sent: status page updated, internal notice posted +- [ ] Recent backup identified and validated +- [ ] Backup integrity verified (checksum, sample query, etc.) +- [ ] Target environment prepared (downtime accepted, traffic redirected) +- [ ] Rollback plan understood +- [ ] Timer started (track actual RTO) + +--- + +## Restore procedure + +### Step 1: Identify the backup to restore from + +[Specific instructions: which backup system, how to find the right one, how to verify it's the right one.] + +``` +[Example commands] +``` + +### Step 2: Prepare the target + +[Specific instructions: which environment, how to ensure no traffic, how to clear or prepare destination.] + +``` +[Example commands] +``` + +### Step 3: Run the restore + +[Specific instructions: the actual restore command(s), expected duration, what success looks like.] + +``` +[Example commands] +``` + +Expected duration: [Time] + +### Step 4: Verify + +[Specific instructions: how to know the restore worked. Sample queries, row counts, data spot-checks.] + +``` +[Example commands and queries] +``` + +Expected results: [What to look for] + +### Step 5: Re-enable traffic + +[Specific instructions: how to direct traffic back to the restored system.] + +``` +[Example commands] +``` + +### Step 6: Monitor + +For [time period] after the restore: + +- [ ] Watch error rates (link to dashboard) +- [ ] Watch latency (link to dashboard) +- [ ] Spot-check user-visible behavior +- [ ] Confirm no further data anomalies + +--- + +## Rollback + +If the restore makes things worse: + +[Specific instructions for reverting. This is rarely possible for data restores, but for failover-style restores, rollback is just the failover in reverse.] + +--- + +## Post-restore + +### Communication + +- [ ] Status page updated (resolved) +- [ ] Internal notice updated (system restored) +- [ ] Customer comms (if appropriate, who and what) +- [ ] Stakeholder summary + +### Documentation + +- [ ] Actual RTO recorded +- [ ] Actual RPO measured (latest data point preserved vs latest data point lost) +- [ ] Notes on any deviations from the runbook +- [ ] Items to fix in the runbook + +### After-action + +Schedule the after-action report within 5 business days. See `after-action-report` skill for the framework. + +--- + +## Backup details + +### Backup architecture + +\| \| Detail \| +\|---\|---\| +\| Backup tool \| [Tool name] \| +\| Frequency \| [Cadence] \| +\| Retention \| [Period] \| +\| Storage location \| [Where, including account/region] \| +\| Immutable? \| [Yes / No, details] \| +\| Encryption \| [Method, key location] \| + +### How backups are tested + +- [ ] [Test method 1] +- [ ] [Test method 2] +- [ ] [Test method 3] + +Last test: [YYYY-MM-DD] +Test cadence: [How often] + +--- + +## Dependencies + +This system depends on: +- [Dependency 1, what it provides] +- [Dependency 2, what it provides] + +If a dependency is also down, the restore may need to wait or proceed with workarounds. Document the workarounds: + +- [Dependency unavailable scenario 1]: [Workaround] +- [Dependency unavailable scenario 2]: [Workaround] + +--- + +## Drill log + +\| Date \| Type (tabletop / partial / full) \| Outcome \| Issues found \| Fixes \| +\|---\|---\|---\|---\|---\| +\| YYYY-MM-DD \| [Type] \| [Pass / Partial / Fail] \| [Issues] \| [Fixes applied] \| + +--- + +## Maintenance + +This runbook needs review: +- After every restore (real or drill) +- When the system architecture changes +- When backup tooling changes +- At least quarterly + +Last review: [YYYY-MM-DD] by [Name] +Next review: [YYYY-MM-DD] + +--- + +## Common gotchas + +[List of things that have surprised people during past restores or drills. Specific to this system.] + +- [Gotcha 1] +- [Gotcha 2] +- [Gotcha 3] diff --git a/skills/beta-program-management/SKILL.md b/skills/beta-program-management/SKILL.md new file mode 100644 index 0000000..30362a4 --- /dev/null +++ b/skills/beta-program-management/SKILL.md @@ -0,0 +1,312 @@ +--- +name: beta-program-management +description: "Running closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time." +category: product +catalog_summary: "Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops)" +display_order: 13 +--- + +# Beta Program Management + +A senior product leader's playbook for running betas that produce real signal. Closed and open betas, alpha programs, design partner programs, early access. Participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). + +Most betas underperform. Teams ship a beta because they think they should run a beta; participants are recruited loosely or open-flooded; feedback is collected ad-hoc through whatever channels exist; the decision to graduate to GA happens on calendar rather than on signal. The beta produced activity but not learning; the team launches with the same uncertainty they had before the beta. + +This skill is the discipline that turns betas into decision input. Calibrated cohorts who match the post-launch user profile. Structured feedback that captures what the team needs to know. Mid-beta triage that uses what is being learned. Graduation criteria that distinguish "ready" from "we are tired of running the beta." The discipline is not bureaucratic; it is the difference between a beta that informs the GA launch and a beta that produces noise. + +The voice is the senior product leader who has run betas with real signal and watched plenty of betas produce nothing. Concrete, opinionated about what produces signal, willing to call out where beta programs slide into ceremony. + +When to use this skill: planning a beta for an upcoming launch, auditing why prior betas have not produced actionable signal, designing the beta participant experience, or deciding whether a feature is ready to graduate from beta to GA. + +--- + +## What this skill is for + +This skill spans beta program design and execution. The PM and engineering distinction: + +- `feature-flagging` is rollout mechanics; the technical layer for controlling who gets which features. +- `beta-program-management` (this skill) is participant management and feedback discipline; the human layer. +- `feature-launch-playbook` is the full launch (post-GA); this skill is what happens BEFORE GA. +- `experiment-design` is rigorous A/B testing; betas are softer, qualitative-leaning, smaller-N. +- `user-feedback-aggregation` is ongoing feedback streams; beta feedback is bounded to the beta period. +- `discovery-research-synthesis` is one-off discovery research; betas are validation-stage rather than discovery-stage. + +The audience: senior PMs, product directors, engineering leads coordinating with product, customer success and support running beta cohorts, anyone planning a closed or open beta. + +What is not in scope: the broader feature launch (covered by `feature-launch-playbook`); the technical rollout mechanics (covered by `feature-flagging`); the rigorous experimentation methodology (covered by `experiment-design`); the discovery-stage research that informs whether to build the feature in the first place. + +--- + +## Soft-launch vs kitchen-sink vs structured-beta + +The keystone framing. + +Soft-launch. "We will just turn it on for some users." No structured participant selection, no defined feedback collection, no graduation criteria. The beta runs because the team wanted to ship the feature without the full launch ceremony. Output: the feature is in production for some users; the team has no organized way to learn from their experience; signal accumulates through whatever channels happen to surface it; mid-beta course-correction does not happen because there is no structure to surface what should be corrected. + +Kitchen-sink. Everyone gets in. The beta opens to whoever signs up. 5,000 beta users; 50 useful pieces of feedback; 4,950 silent users who provide no signal. Volume drowns signal. The team cannot tell which users matched the target post-launch profile. Feedback channels overflow; useful patterns get lost in noise; mid-beta triage cannot keep up. Output: a sense of "we ran a big beta" without the actionable feedback that smaller calibrated cohorts produce. + +Structured-beta. Calibrated cohort selected by participant criteria. Intentional feedback loops the cohort knows to use. Clear graduation criteria that distinguish "ready for GA" from "tired of the beta." Mid-beta triage that uses what is being learned. Output: the beta produces decision-grade signal; the GA launch ships with confidence; problems that would have surfaced in production get caught and addressed in beta. + +The litmus test. After the beta concludes, ask: what specifically did we learn from this beta that changed the GA launch? If the team can name 3-7 specific lessons, the beta was structured. If the team can only generally say "the beta went well," the beta was soft-launch or kitchen-sink. + +--- + +## Beta type decisions + +Several axes of beta-type choice. The right combination depends on the launch context. + +Closed vs open. + +- Closed: invite-only. Participants are selected by criteria. Cohort is bounded. +- Open: anyone can join. Cohort is self-selecting. +- Closed produces calibrated signal; open produces volume signal that may not match the target user profile. + +Alpha vs beta vs RC. + +- Alpha: very early, internal or trusted-partner only, expectation of bugs. +- Beta: more polished, broader cohort, expectation of feedback rather than crash discovery. +- RC (release candidate): essentially launch-ready, last validation, expectation of production-grade quality. + +Internal vs external. + +- Internal: only employees use the feature. +- External: real customers use the feature. +- Internal betas catch only what employees would experience; external betas catch the full user-context complexity. + +Time-bounded vs open-ended. + +- Time-bounded: 4-week beta, 8-week beta, with a defined end. +- Open-ended: beta runs until the team decides to graduate. +- Time-bounded forces the graduation decision; open-ended risks beta-purgatory. + +The combination decision. A typical structured beta might be closed + beta + external + 6-week time-bounded. A design partner program might be closed + alpha + external + open-ended. An open early access might be open + beta + external + time-bounded. The combination should match the kind of signal the team needs. + +Detail in [`references/beta-type-decisions.md`](references/beta-type-decisions.md). + +--- + +## Participant selection criteria + +The discipline that makes calibrated cohorts possible. + +The criteria that work. + +- Match the post-launch user profile. If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. The beta participant profile should resemble the target GA audience. +- Variety across relevant dimensions. Not all participants identical. If the feature has segment-specific behavior, the cohort spans segments. If usage volume varies, the cohort includes high-volume and low-volume users. +- Feedback willingness. Participants who agree to provide feedback through the structured channels. Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Existing relationship strength. Customers with strong existing relationships are more likely to engage substantively. Customers in churn-risk are less likely to engage; their feedback may also be less representative. + +The criteria that fail. + +- Self-selection only. Open beta sign-ups skew toward enthusiasts and tinkerers; their feedback may not represent the broader target user. +- Highest-paying customers only. Skews toward enterprise patterns that may not generalize; misses smaller-team use cases. +- Internal employees only. Misses the customer-context complexity; signals "we tested" without "real users tested." + +The cohort size question. Calibrated cohorts are usually 20-200 participants for closed external betas. Smaller (5-20) for design partner programs. Larger (200-2,000) for open early access. Beyond 2,000 the program is a soft-launch with beta branding. + +Detail in [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md). + +--- + +## Beta cohort sizing + +How big is enough; when does signal saturate. + +Saturation patterns. + +- Critical feedback (bugs, crashes, broken flows) saturates quickly. 20-30 participants surface most critical issues in the first 2 weeks. +- Behavioral feedback (how users actually use the feature) saturates more slowly. 50-100 participants needed to see usage patterns clearly. +- Edge case feedback saturates slowly. 100+ participants needed; some edge cases never surface in beta. + +Sizing decisions. + +- For betas focused on bug discovery: 20-50 participants for 2-4 weeks. Beyond this, returns diminish. +- For betas focused on behavioral signal: 50-200 participants for 4-8 weeks. +- For betas focused on validating product-market fit assumptions: 100-500 participants over 8-12 weeks. +- For betas focused on at-scale infrastructure validation: 500-2,000 participants over 4-8 weeks. + +The "beta size matches signal need" principle. Cohort size follows from what the team needs to learn. Larger is not always better; calibrated is. + +Detail in [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md). + +--- + +## Onboarding beta participants + +How participants enter the beta and what they know going in. + +The setup. + +- Welcome communication that sets expectations: what the beta is, what feedback is expected, how long it runs, what happens at graduation. +- NDAs where relevant (for unannounced features, design partner programs). +- Feedback channel access: where participants give feedback, what format, what cadence. +- Support escalation path: who participants contact when things break. +- Compensation or incentive disclosure: free access to the feature post-GA, gift cards, swag, named recognition, etc. + +The expectations contract. + +- What the team commits to participants: communication cadence, response to feedback, transparent about graduation criteria. +- What participants commit to the team: feedback through the structured channels, not sharing externally during NDA, willingness to engage in interviews if requested. + +Common onboarding failures. + +- Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. +- No NDA where appropriate. Beta features get screenshotted on social before the team is ready. +- Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. +- No incentive clarity. Participants feel underrecognized; engagement decays. + +Detail in [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md). + +--- + +## Feedback collection patterns + +Structured channels that produce signal rather than noise. + +Channels that work. + +- Structured surveys. 5-15 question surveys at defined points (week 1, week 4, end of beta). Specific questions tied to the team's learning goals. +- Async feedback forms. Participants submit specific feedback through a defined form. Fields prompt for use case, severity, expected vs actual behavior. +- Structured interviews. 30-60 minute interviews with a subset of participants (5-15 per beta). Focused on usage patterns, decision moments, and qualitative depth. +- In-product feedback widgets. Contextualized to the moment. The feedback is timestamped to the user's actual experience. +- Support tickets routed to beta-aware support. Beta participants get faster, more contextualized support; the support interactions surface usage friction. + +Channels that fail. + +- Slack channels for venting. Beta participants vent in real time; signal mixes with noise; nobody synthesizes. +- "Reply to this email with feedback." Returns long unstructured emails; synthesis is hard; useful patterns get lost. +- "Tell us what you think in the survey at the end." End-of-beta surveys catch only what participants remember; in-the-moment friction is forgotten. + +Channel mix discipline. Most structured betas use 3-5 channels. Each channel surfaces different kinds of signal. The team synthesizes across channels. + +Detail in [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md). + +--- + +## Mid-beta triage and iteration + +How the team responds to feedback during the beta. + +The principle. Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. + +The triage cadence. + +- Weekly: review feedback across all channels. Categorize: critical bug, friction issue, feature request, positive signal, edge case. +- Bi-weekly: surface patterns. What recurring feedback are we seeing? What signal is converging? +- As-needed: critical issues get same-day response. Bugs that prevent core flows are not allowed to sit. + +The iteration discipline. + +- Critical bugs fixed during the beta. Beta participants experience the fixes; the post-fix experience informs the GA decision. +- Friction issues prioritized for fixes during the beta where feasible; documented for the GA decision where not. +- Feature requests captured for post-GA roadmap; not added during the beta unless they are graduation-blocking. +- Positive signal validated; surfaces what works, informs marketing copy and onboarding for GA. + +The communication discipline. Participants are kept informed: "We received your feedback on X; we are addressing it in next week's beta update." Silence makes participants feel ignored; over-communication signals overhead. Calibrate. + +Detail in [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md). + +--- + +## Beta-to-GA decision criteria + +Graduation gates that distinguish "ready" from "tired of running the beta." + +The criteria. + +- Critical bugs cleared. No known crashes, data loss, or core-flow failures. +- Friction issues addressed or accepted. Friction the team will not address by GA is documented and accepted as known limitation. +- Behavioral validation. Beta participants are using the feature in the patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). +- Performance under load. The feature performs adequately at the scale GA will produce. (For infrastructure betas, this is the central criterion.) +- Documentation and support readiness. Help docs reflect actual usage; support team is trained on common issues; escalation paths work. +- Positive signal sufficient. Feedback is net-positive enough to launch with confidence. Not all participants delighted, but a substantial majority finding value. + +The "we are tired of running the beta" anti-pattern. Beta has run long enough that the team wants to graduate regardless of signal. The graduation decision happens on calendar rather than on criteria. Resist this; either the criteria are met (graduate) or they are not (extend or reset). + +The "perpetual beta" anti-pattern. Beta runs indefinitely because no firm graduation criteria were set. The team avoids the GA commitment by keeping the feature in beta. Force the graduation decision; if the feature is not ready for GA, identify what would make it ready or reconsider whether to ship at all. + +Detail in [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md). + +--- + +## Beta wind-down and participant communication + +How the beta ends. + +The graduation announcement. Participants are told the feature is graduating. Specific date. What changes for them: continued access (typically yes), pricing changes (often beta participants get free access for some period), feature stability commitments (the GA version is what they will use going forward). + +The transition. + +- For most participants: nothing changes operationally. The feature stays available; the "beta" label drops. +- Pricing transitions communicated explicitly if applicable. +- Beta-only features that did not make GA are flagged. Participants who relied on those features are given alternatives or transition timelines. + +The thank-you. Beta participants invested time providing feedback. Recognition matters: named in changelog (with consent), gift cards or swag, advance access to future betas. The recognition strengthens future-beta recruitment. + +The postmortem. Internal review of what the beta produced. What was learned, what changed in the GA launch, what would be done differently in future betas. This feeds the team's beta program practice. + +Detail in [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-beta-failures.md`](references/common-beta-failures.md). + +- "Our beta produced no signal." Soft-launch pattern; no structured selection or feedback collection. +- "Our beta has 5,000 users and we cannot synthesize feedback." Kitchen-sink; cohort too large for the structured signal the team needs. +- "Our beta participants never gave feedback." Onboarding contract was unclear or feedback channels were friction-laden. +- "We graduated to GA on schedule but launched with critical bugs." Graduation criteria not enforced; calendar-driven graduation. +- "Our beta has been running for 8 months with no graduation." Perpetual beta; no firm graduation criteria; graduation decision avoided. +- "Beta participants vented on Twitter before the launch." NDA missing or unclear; trust violation early erodes participant willingness. +- "The beta surfaced patterns we did not act on." Mid-beta triage missing; feedback collected but not used during the beta. +- "The GA launch surprised us." Beta was not actually validating the GA experience; cohort or feedback structure was wrong. +- "Beta participants felt ignored after providing feedback." Communication discipline missing; participants commit time and want to know it mattered. +- "We ran a closed beta that was effectively employees only." Internal-only beta; missed customer-context complexity. + +--- + +## The framework: 12 considerations for beta program management + +When designing or auditing a beta program, walk these 12 considerations. + +1. Structured-beta, not soft-launch or kitchen-sink. Calibrated cohort, intentional feedback, clear graduation. +2. Beta type matches signal need. Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. +3. Participants match the post-launch profile. Match the user the GA serves. +4. Cohort size calibrated to signal need. Smaller for bugs; larger for behavioral signal. +5. Onboarding contract clear. Expectations on both sides documented. +6. Feedback channels structured. 3-5 channels; signal not noise. +7. Mid-beta triage active. Feedback acted on during the beta. +8. Communication keeps participants engaged. Updates on what was heard and what is changing. +9. Graduation criteria explicit. Critical bugs cleared, friction addressed, behavioral validation, performance under load, support readiness, positive signal. +10. Wind-down treats participants well. Transition clarity, recognition, thank-you. +11. Postmortem feeds practice. Each beta improves the next. +12. Honest decisions on graduation. Either criteria met (graduate) or not (extend or reconsider). No tired-of-the-beta graduation. + +The output of the framework is a beta program that produces decision-grade signal, supports the GA launch, and treats participants well enough to recruit them for future betas. + +--- + +## Reference files + +- [`references/beta-type-decisions.md`](references/beta-type-decisions.md) - Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. +- [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md) - Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. +- [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md) - Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. +- [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md) - Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. +- [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md) - Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. +- [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md) - Triage cadence. Iteration discipline (what to fix during, what to defer). Communication with participants. +- [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md) - The six graduation criteria. The "tired of the beta" anti-pattern. Perpetual beta anti-pattern. +- [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md) - Graduation announcement, transition, recognition, postmortem. Treating participants well. +- [`references/common-beta-failures.md`](references/common-beta-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: betas earn their keep with structure + +A structured beta is one of the most useful product activities available. The cohort experiences the feature; the team learns from their experience; the GA launch ships with reduced uncertainty. The discipline pays back many times its cost. + +A soft-launch or kitchen-sink beta is one of the least useful. The team spends weeks running an activity that produces ambient activity without converting to learning. The GA launches with the same uncertainty the beta was supposed to address. + +The teams that earn returns on betas are the ones that take the structure seriously: cohorts calibrated to the GA profile, feedback channels designed for signal, mid-beta triage that uses what is being learned, graduation criteria that distinguish ready from tired, wind-down communication that treats participants well enough to recruit them again. + +When in doubt about whether a beta is ready, ask: are participants matched to the GA user, are feedback channels structured, is the team responding to feedback during the beta, are graduation criteria explicit and being applied honestly, will participants want to join the next beta? If yes to all of those, the beta is real. If no to any, the gap is where the beta will fail to convert participation into learning. diff --git a/skills/beta-program-management/references/beta-onboarding-templates.md b/skills/beta-program-management/references/beta-onboarding-templates.md new file mode 100644 index 0000000..a691d40 --- /dev/null +++ b/skills/beta-program-management/references/beta-onboarding-templates.md @@ -0,0 +1,230 @@ +# Beta onboarding templates + +Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract. + +Onboarding sets the tone for the beta. Done well, participants enter with clear expectations and stay engaged through the program. Done badly, participants drop off, fail to provide feedback, or violate confidentiality unintentionally. + +--- + +## The welcome communication + +The first message participants receive after accepting the invitation. + +What it covers. + +- Welcome and thank-you for joining. +- What the beta is: the feature, the goals, what is being validated. +- Beta duration: start date, end date, what graduation looks like. +- What is expected of participants: feedback channels, cadence, format. +- What participants get: access to the feature, support, recognition or compensation, post-GA terms. +- NDA reminder where applicable. +- How to access the feature: links, accounts, configuration steps. +- Who to contact: support escalation path, beta program manager. +- First feedback prompt: what the team would like to hear about in the first week. + +What it does not cover. + +- A complete product manual. The participant should be able to use the feature; in-product guidance handles the detail. +- Internal team structure or politics. Participants do not need to know who reports to whom. +- Future roadmap. The beta is about this feature; future plans are separate communication. + +Length. 400-800 words for substantive features. Shorter for simpler features. The welcome should be readable in 3-5 minutes. + +Tone. Warm but professional. Beta participants are doing the team a favor; the welcome reflects that. Avoid corporate-stiff or overly casual. + +--- + +## The expectations contract + +Both sides commit to specific behaviors. + +What the team commits to. + +- Communication cadence: regular updates (weekly or bi-weekly). +- Response to feedback: critical issues addressed quickly; friction issues prioritized; feature requests captured. +- Transparency: participants are told what is being changed based on feedback and what is being deferred. +- Graduation criteria: explicit criteria, applied honestly. +- Post-GA continuity: participants know what their access looks like after graduation (typically continued access; sometimes special pricing). + +What participants commit to. + +- Feedback through the structured channels (specific channels named). +- Confidentiality where NDA applies (no public posts, screenshots, or sharing of beta features outside the participant's organization). +- Reasonable engagement: not required to use the feature daily, but expected to use it enough to provide informed feedback. +- Willingness to engage in interviews if requested (with the right to decline specific interviews). + +The signed-or-implicit agreement. + +- For substantial NDAs, participants sign an explicit agreement. +- For lighter beta agreements, the welcome communication may be the implicit acceptance (participation implies agreement to terms). +- The team should know which approach applies and apply it consistently. + +--- + +## NDA considerations + +When NDAs are appropriate. + +NDA appropriate. + +- Unannounced features (the beta is essentially confidential). +- Features that affect competitive positioning (the team does not want competitors to see the feature early). +- Design partner programs with deep collaboration on feature shaping. +- Enterprise features that touch sensitive customer data or workflows. + +NDA not appropriate or unnecessary. + +- Open public betas. +- Features that have already been announced. +- Features where the team welcomes public discussion (e.g., developer-tool launches that benefit from community feedback). + +NDA enforcement reality. + +- NDAs in open beta are essentially unenforceable. Pretending an open beta has NDA protection is theater. +- Closed-beta NDAs are enforceable but require trust; the team should not invite participants who are likely to violate confidentiality. +- For sensitive betas, the cohort selection itself is the primary control; NDAs are the legal backstop. + +What an NDA covers. + +- Confidentiality of the beta feature, its functionality, and the team's plans. +- Restrictions on screenshots, public posts, recordings. +- Term: typically until the feature is publicly announced or for a defined period. +- Exceptions: feedback to the team is allowed; discussion within the participant's organization is usually allowed. + +--- + +## Feedback channel access + +What participants need to know about how to give feedback. + +Channel inventory. + +- Structured surveys: when they will arrive, how long they take, how to access. +- Async feedback forms: link, instructions, what fields to fill. +- Interview signups: how to volunteer for interviews, what compensation if any. +- In-product feedback widget: how to use, what context it captures. +- Support routing: how beta participants flag issues to the support team. +- Slack or community: if a beta-only channel exists, how to join and what tone is expected. + +Channel discipline. + +- Each channel serves a different purpose. The welcome communication explains which channel is for which feedback type. +- Avoid duplicating channels (multiple Slack-like channels for the same feedback) or confusing channel mappings. + +--- + +## Support paths + +How participants escalate issues. + +The escalation map. + +- Bug reports: filed through the structured form or support ticketing system tagged "beta." +- Critical issues (crashes, data loss): escalation contact named explicitly; not buried in standard support queues. +- Feature questions and how-to: routed to in-product help or beta program manager. +- Account issues: standard support paths or beta-aware support reps. + +Support team awareness. + +- Support team should know the beta is running and how to handle beta-tagged tickets. +- Beta-tagged tickets often deserve faster response than standard tickets (the participant is doing the team a favor; long support waits damage the relationship). +- Common beta issues should be documented for the support team in advance. + +--- + +## Incentive disclosure + +What participants get for joining. + +Common incentives. + +- Free access to the feature post-GA for some period. +- Discounted pricing on the feature post-GA. +- Beta-only feature flags or capabilities preserved post-GA. +- Recognition (named in changelog, on website, in launch communications) with consent. +- Gift cards, swag, or other compensation. +- Direct access to product team during the beta (some participants value this most). + +Disclosure discipline. + +- The welcome communication names the incentives explicitly. No surprise reveals at the end. +- Different participants may have different incentive packages (design partners often get more); each participant knows their package. +- The incentives match the commitment level. Light betas have light incentives; design partner programs have substantive ones. + +The "no incentive" pattern. + +- Some betas offer no formal incentive beyond access to the feature. +- This works for high-engagement audiences (developers, enthusiasts) where access itself is the incentive. +- It does not work for audiences where the time investment is significant; participants need a reason to engage substantively. + +--- + +## First-week onboarding + +What happens after the welcome message. + +The first week's actions. + +- Day 1: welcome arrives; participants get access; first-day checklist (set up, access feature, complete profile if applicable). +- Day 2-3: first feedback prompt arrives. Could be an in-product widget triggered after first usage, or an email asking specifically about the first impression. +- End of week 1: brief check-in. Are participants able to access? Have they used the feature? Any friction with onboarding itself? + +Onboarding-specific friction. + +- Beta participants who cannot access the feature in the first 24-48 hours often disengage. Access friction is the most consequential onboarding failure. +- Documentation that does not match the actual experience (because the docs were written for a slightly different feature version) frustrates early. +- Missing context about what the feature is for. Participants who do not know what the feature is meant to accomplish use it tentatively or not at all. + +--- + +## Onboarding for different beta types + +Different beta types warrant different onboarding intensity. + +Lightweight onboarding (open beta, RC validation). + +- Email welcome with key information. +- Self-service access. +- In-product guidance handles most setup. + +Standard onboarding (closed beta, structured cohort). + +- More substantial welcome email. +- Optional onboarding call for participants who request it. +- Beta program manager available via direct channel. + +Deep onboarding (design partner program, complex feature). + +- Onboarding call with each participant or company. +- Custom configuration support. +- Direct channel to product team for ongoing collaboration. + +The onboarding intensity matches the beta type. Heavyweight onboarding for an open beta with 5,000 participants is impossible; lightweight onboarding for a 5-partner design program under-invests in the relationships. + +--- + +## Common onboarding failures + +Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels. + +Missing NDA where appropriate. Beta features get screenshotted on social before the team is ready. + +Missing support path. Participants hit issues, do not know who to contact, churn out of the beta. + +No incentive clarity. Participants feel underrecognized; engagement decays. + +Welcome communication too long or too short. Too long: participants do not read; too short: participants miss critical context. + +Access friction in first 24-48 hours. Participants cannot get into the feature; many disengage permanently. + +Onboarding intensity mismatched to beta type. Heavy onboarding for an open beta wastes effort; light onboarding for a design partner program under-invests. + +--- + +## Methodology-level choices that stay in the public skill + +The welcome communication structure. The expectations contract for both sides. NDA considerations. Feedback channel access. Support paths. Incentive disclosure. First-week onboarding. Onboarding by beta type. Common failures. + +## Implementation choices that stay internal + +Specific welcome email templates. Specific NDA boilerplate. Specific support routing automation. Specific incentive packages and approval workflows. The team's own conventions for onboarding intensity. These vary by team and beta type. diff --git a/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md b/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md new file mode 100644 index 0000000..e835ce5 --- /dev/null +++ b/skills/beta-program-management/references/beta-to-ga-graduation-criteria.md @@ -0,0 +1,239 @@ +# Beta-to-GA graduation criteria + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. + +Graduation is the decision that distinguishes a structured beta from beta theater. Honest graduation criteria, applied honestly, separate "ready for GA" from "we are tired of running the beta." Defining the criteria explicitly upfront prevents calendar-driven graduation decisions later. + +--- + +## The six graduation criteria + +The criteria that should be met before graduating from beta to GA. + +### 1. Critical bugs cleared + +The criterion. No known crashes, data loss, or core-flow failures. + +The validation. Bug tracker shows no open critical issues. The beta cohort has not reported new critical issues in the past 1-2 weeks. + +The exception. Some critical issues may be acceptable if they affect a tiny segment that the GA can either exclude or address with documentation. Decisions to graduate with known issues should be explicit. + +### 2. Friction issues addressed or accepted + +The criterion. Friction issues are either fixed before GA or documented as known limitations the team is choosing not to address pre-GA. + +The validation. Each friction issue from the beta has a disposition: fixed, fix-in-progress (with timeline), accepted-for-now (with rationale), accepted-permanently (with rationale). + +The honest disposition. "Accepted for now" is honest if the team plans to address post-GA. "Accepted permanently" is honest if the team has decided the friction is not worth the engineering cost. Hidden friction that the team hopes nobody will notice is not honest. + +### 3. Behavioral validation + +The criterion. Beta participants are using the feature in patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed). + +The validation. Usage data from the beta cohort shows the feature being used in the ways the design assumed. Significant deviations are investigated; either the design is adjusted, or the GA experience is modified to support the actual usage pattern. + +The unexpected-pattern handling. + +- Pattern A: most beta participants are using the feature in a different way than the design assumed. The design is wrong; iterate before GA. +- Pattern B: a subset of participants is using the feature in an unexpected way that suggests an additional use case. Capture for post-GA expansion; do not delay GA. +- Pattern C: participants are not using the feature much at all. The feature may not be solving a real problem; reconsider whether to ship. + +### 4. Performance under load + +The criterion. The feature performs adequately at the scale GA will produce. + +The validation. Performance testing under projected GA load. Beta cohort performance was acceptable; the GA scale projection has been tested. + +The infrastructure-validation focus. For features where scale is the primary concern (data-processing features, real-time features, multi-tenant features), this criterion is the central one. RC betas often exist primarily to validate this. + +### 5. Documentation and support readiness + +The criterion. Help docs reflect actual usage; support team is trained on common issues; escalation paths work. + +The validation. + +- Help docs match the feature as it will ship at GA. +- Support team has been briefed and has handled at least the simulated beta-tier ticket volume. +- Common issues are documented for the support team's reference. +- Escalation paths from support to engineering are tested. + +The skip risk. Teams often graduate before docs and support are ready. The GA launch then catches the support team off-guard; tickets pile up; users have a worse experience than they would have with proper readiness. + +### 6. Positive signal sufficient + +The criterion. Beta feedback is net-positive enough to launch with confidence. + +The validation. + +- Survey signal shows positive sentiment among beta participants. +- Behavioral signal shows continued usage (participants are not just trying the feature once). +- Participants would recommend the feature to others. + +The "sufficient" calibration. Not all participants need to be delighted. A substantial majority finding value, with the dissenting voices understood (segment misfit, expectations mismatch, unfixable friction), is sufficient. A divided cohort with no clear majority signal is not. + +--- + +## The "tired of the beta" anti-pattern + +Graduation that happens because the team wants to be done with the beta. + +The pattern. + +- Beta has run for the planned duration. +- Some criteria are met; some are not. +- The team graduates anyway because "we have to ship at some point" or "the beta cannot run forever." + +Why it fails. + +- Unmet criteria mean the GA launches with known issues that are not yet addressed or acknowledged. +- Support, marketing, and customer success encounter problems the beta would have caught if extended. +- Trust degrades: customers experience friction the beta participants reported but the team did not fix. + +The cure. + +- Either extend the beta until criteria are met. +- Or graduate with explicit acknowledgment of the unmet criteria (known issues, deferred work). +- Or reset the beta if significant changes are needed. + +The discipline: the graduation decision is criteria-driven, not calendar-driven. Calendar pressure can inform whether to ship a smaller scope, but it should not produce graduation despite unmet criteria. + +--- + +## The perpetual beta anti-pattern + +Graduation that does not happen because the beta drifts indefinitely. + +The pattern. + +- Beta runs without firm graduation criteria. +- Issues keep surfacing; the team keeps fixing; the beta extends. +- 6 months later, the beta is still running. The "perpetual beta" branding becomes a strategic stance ("everything is always evolving"). +- The GA commitment is avoided. + +Why it fails. + +- Beta participants experience indefinite uncertainty about the feature's status. +- The team avoids the discipline of GA readiness; the feature stays in a less-mature state than it could be. +- Marketing, support, and customer success cannot operate around a beta-forever feature. +- Stakeholder trust degrades: the team is not shipping. + +The cure. + +- Force the graduation decision. Either the criteria are met (graduate) or they are not (decide what would make them met, set a timeline, commit). +- "Perpetual beta" as a strategic stance is rare and usually a rationalization. +- Some features genuinely need extended-beta status for valid reasons (regulatory complexity, unusual scale validation); these should be exceptions documented explicitly, not the default. + +--- + +## Honest graduation patterns + +When graduation criteria are mostly but not fully met. + +Graduation with known issues. + +- Some criteria fully met; one or two have known gaps. +- Graduate with explicit acknowledgment: "We are shipping with X known limitation; documented; will address in [timeline]." +- Communicate the known issues to support, marketing, customer success. +- Customers who hit the known issue are not surprised; they were warned. + +Graduation with extended monitoring. + +- Behavioral signal not fully validated due to cohort limitations. +- Graduate with monitoring infrastructure that surfaces issues at GA scale. +- Plan for fast iteration if monitoring catches issues post-GA. + +Graduation with phased rollout. + +- All criteria met for a subset of users; less certain for broader users. +- Graduate to the validated subset first; expand the rollout in phases. + +These patterns preserve graduation discipline while accommodating real-world constraints. + +--- + +## When NOT to graduate + +Conditions that warrant extending or resetting the beta. + +Not to graduate. + +- Critical bugs are unaddressed. +- Major friction issues affect mainline usage. +- Behavioral signal contradicts the design assumptions. +- Performance under projected load is inadequate. +- Documentation and support are not ready. +- Beta sentiment is divided without clear positive signal. + +The honest extension. + +- Acknowledge the gap explicitly. +- Define what would close the gap. +- Set a new timeline. +- Communicate to participants and stakeholders. + +The reset. + +- If the gap requires significant feature changes, end the current beta and start a new one with the changed feature. +- Do not blend "old beta" and "new feature" data. + +--- + +## Graduation decision-making + +Who decides graduation and how. + +The decision-maker. Typically the product manager who owns the feature, with input from engineering lead, design lead, and beta program manager. + +The decision process. + +- Beta program manager prepares a graduation review document: status against each criterion, known issues, recommendation. +- Decision meeting (60-90 minutes): review the document, discuss any open questions, make the decision. +- Decision recorded explicitly: graduate, extend, or reset. + +Stakeholder visibility. The decision is communicated to stakeholders (executives, marketing, sales, customer success) before participants are notified. + +Graduation timing. Once the decision is made, graduation typically takes 1-2 weeks to execute (final code, marketing prep, support readiness, participant communication). + +--- + +## Graduation criteria for different beta types + +The criteria adapt to the beta type. + +Closed beta with calibrated cohort. All six criteria apply. The cohort is small enough to validate behavioral signal directly. + +Open beta with large volume. Behavioral signal validates at scale. Critical bugs and performance criteria are more central. Documentation and support readiness scale with the open-beta visibility. + +RC validation. Performance under load is the central criterion. Other criteria should already have been met in prior alpha or beta stages. + +Design partner program. The criteria apply but graduation often happens incrementally (specific design partners moving to GA terms while the program continues with new partners). Less of a single graduation moment. + +Internal beta. Customer-context criteria (behavioral validation, support readiness for external) may need to be validated at GA rather than during beta. Honest disclosure: the beta did not fully validate the customer experience. + +--- + +## Common graduation failures + +Calendar-driven graduation. Graduate when the planned duration ends regardless of criteria. + +Criteria not defined upfront. Graduation decision happens without explicit criteria; subjective decision. + +Hidden known issues. Graduate with known issues that are not surfaced; customers and support discover them later. + +Perpetual beta. Indefinite extension; graduation decision avoided. + +Premature graduation. Graduate before behavioral signal has emerged or critical bugs are fully cleared. + +No stakeholder notification. Graduation happens; support, marketing, customer success encounter the GA launch unprepared. + +No participant communication about graduation. Beta participants are not told about graduation timing or what changes for them. + +--- + +## Methodology-level choices that stay in the public skill + +The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. Honest graduation patterns. When not to graduate. Graduation decision-making. Graduation criteria for different beta types. Common failures. + +## Implementation choices that stay internal + +Specific graduation review document templates. Specific decision-meeting formats. Specific stakeholder notification workflows. The team's own conventions for graduation timing. These vary by team and tooling. diff --git a/skills/beta-program-management/references/beta-type-decisions.md b/skills/beta-program-management/references/beta-type-decisions.md new file mode 100644 index 0000000..0995f48 --- /dev/null +++ b/skills/beta-program-management/references/beta-type-decisions.md @@ -0,0 +1,228 @@ +# Beta type decisions + +Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need. + +Beta type is the upstream decision that constrains everything downstream: who participates, what feedback channels make sense, what graduation looks like. Getting the type wrong makes the rest of the program harder. + +--- + +## Closed vs open + +The cohort-control axis. + +Closed beta. Invite-only. Participants are selected by the team based on criteria. Cohort is bounded. + +Strengths. + +- Calibrated cohort: the team knows who is in the beta and can match participants to the GA user profile. +- Quality of feedback: invited participants typically engage more substantively than self-selected open-beta users. +- NDA enforceability: closed cohorts can sign NDAs; open cohorts usually cannot. +- Synthesis tractability: bounded cohort means feedback volume is manageable. + +Weaknesses. + +- Recruiting overhead: identifying and inviting participants is real work. +- Limited diversity: the cohort reflects the team's recruiting choices; gaps in selection produce gaps in feedback. +- Slower feedback volume: smaller cohorts produce less total feedback. + +Open beta. Anyone can join. Cohort is self-selecting. + +Strengths. + +- Volume: large numbers of participants quickly. +- No recruiting overhead: participants opt in. +- Marketing value: open betas can build pre-launch audience awareness. + +Weaknesses. + +- Self-selection bias: early adopters and enthusiasts skew the cohort; their feedback may not represent the broader target user. +- Signal-to-noise ratio: most participants do not provide actionable feedback; the team must mine signal from volume. +- NDA difficulty: open cohorts cannot reasonably enforce NDAs; the feature is essentially public. + +--- + +## Alpha vs beta vs RC + +The polish axis. + +Alpha. + +- Very early. Significant bugs expected. +- Internal users or trusted partners only. +- Goal: surface fundamental issues before broader exposure. +- Feedback orientation: bug discovery, fundamental flow validation. + +Beta. + +- More polished. Major bugs caught; remaining issues are friction or edge cases. +- Broader cohort. External customers in calibrated cohorts. +- Goal: validate the feature works for real users in real contexts. +- Feedback orientation: usage patterns, friction, behavioral signal, edge cases. + +RC (release candidate). + +- Essentially launch-ready. Production-grade quality expected. +- Cohort can be large (open beta or extended beta). +- Goal: last validation before GA, performance at scale, infrastructure readiness. +- Feedback orientation: scale issues, infrastructure issues, last-mile polish. + +The progression. Many features pass through all three (alpha → beta → RC) before GA. Some skip alpha (sufficient internal testing) or skip RC (the beta is the last validation). The decision depends on feature complexity and risk tolerance. + +--- + +## Internal vs external + +The audience axis. + +Internal beta. Only employees use the feature. + +Strengths. + +- Fast feedback: employees are easy to recruit and follow up with. +- High engagement: employees usually feel some ownership of company products. +- NDA simplicity: confidentiality is implicit. + +Weaknesses. + +- Missing customer context: employees experience features differently than customers (familiarity, infrastructure context, motivations). +- Bias toward team-known patterns: employees use products in ways the team designed for; customers often use products differently. +- Limited signal: internal-only cannot validate customer-context complexity. + +External beta. Real customers use the feature. + +Strengths. + +- Real customer experience: feedback reflects how customers actually use the product. +- Behavioral signal: usage patterns from real customers inform GA decisions. +- Trust building: customers who beta-test become advocates. + +Weaknesses. + +- Requires customer relationship: cannot just turn the feature on for employees. +- Recruiting overhead: identifying willing customers and managing the cohort. +- Risk: bugs reaching customers can damage trust if not handled well. + +The combination. Most strong betas pass through both: internal alpha, then external beta. Some skip internal (when internal use cases differ enough from customer use cases that internal validation is misleading). + +--- + +## Time-bounded vs open-ended + +The duration axis. + +Time-bounded beta. A defined end date. Common durations: 4 weeks, 6 weeks, 8 weeks, 12 weeks. + +Strengths. + +- Forces the graduation decision. The end date arrives; the team must decide ready or not. +- Clarity for participants: they know how long they are committing. +- Resource bounding: the team's beta-running effort is bounded. + +Weaknesses. + +- Calendar pressure can force premature graduation: "we are at the end date so we are graduating" regardless of signal. +- Some signals need longer to surface: behavioral patterns may not be visible in 4 weeks. + +Open-ended beta. No defined end. The beta runs until the team decides to graduate. + +Strengths. + +- Signal-driven graduation: the team graduates when the criteria are met, regardless of calendar. +- Allows long-running validation: behavioral signal can develop over months. +- Suits design partner programs: ongoing relationships rather than time-bounded cohorts. + +Weaknesses. + +- Beta-purgatory risk: beta runs indefinitely because nobody forces the graduation decision. +- Participant fatigue: open-ended commitments without clear duration drain engagement. +- Resource drain: the team's beta-running effort is open-ended. + +The default. Most betas should be time-bounded. Open-ended is appropriate for design partner programs and specific extended-validation scenarios. + +--- + +## The combination decision + +How to choose across the four axes. + +Worked combinations. + +Standard structured beta: closed + beta + external + time-bounded (6-8 weeks). + +- Use when: shipping a meaningful feature that needs validation before GA. Most common combination. + +Alpha: closed + alpha + internal + open-ended (typically 2-6 weeks of internal testing before external alpha). + +- Use when: very early feature; need to surface fundamental issues before exposing customers. + +Design partner program: closed + alpha or beta + external + open-ended. + +- Use when: building a feature with deep customer involvement; small set of partner customers (3-10) collaborating closely on shaping the feature. + +Open early access: open + beta or RC + external + time-bounded (4-12 weeks). + +- Use when: pre-GA marketing matters; the feature is sufficiently polished that early access can build audience; team can handle the volume. + +RC validation: open or closed + RC + external + time-bounded (2-4 weeks). + +- Use when: the feature is essentially launch-ready; need last validation at scale or in the production environment. + +Internal-only RC: closed + RC + internal + time-bounded. + +- Use when: the feature is for internal users (e.g., admin tools used by support team), or when external testing is impractical for the type of feature. + +--- + +## When the combination decision goes wrong + +Common mismatches. + +Open + alpha. Open cohorts on an alpha-stage feature exposes customers to bugs the team has not caught. Damages trust. Cure: alpha should be closed; open up at beta stage when the feature is more polished. + +Closed + RC. Closed RCs miss the at-scale validation that RCs are meant to provide. The cohort is too small to surface scale issues. Cure: RCs are usually open or large-closed. + +External + alpha + open-ended. External customers commit to an alpha that has no end date and many bugs. Engagement decays. Cure: alpha should be internal or trusted-partner only; external alpha should be time-bounded and limited. + +Open + beta + open-ended. Volume cohort with no end date. The beta runs forever; participants lose interest; the team cannot synthesize. Cure: time-bound the beta; force graduation decision. + +--- + +## Beta type for specific contexts + +Common contexts and the typical type combinations. + +B2B SaaS feature launch. Closed + beta + external + time-bounded. 20-200 participants from existing customer base, 6-8 weeks. + +Consumer product launch. Open + beta + external + time-bounded (or open + RC). 1,000-10,000+ participants, 4-8 weeks. Marketing value is part of the rationale. + +Enterprise platform major release. Closed + alpha + design-partner + open-ended initially, then closed + beta + extended cohort + time-bounded for validation. + +Developer-tool launch. Open + beta + external + time-bounded, with public roadmap and community feedback channels. + +Internal tool launch. Closed + alpha or beta + internal + time-bounded. The cohort is the internal users who will use the tool post-GA. + +Compliance-impacting feature. Closed + extended beta + external + carefully selected design partners. The validation needs to surface compliance edge cases before GA. + +--- + +## Common beta-type failures + +Defaulting to soft-launch. Skipping beta-type decisions and just turning the feature on for some users. Decide the type explicitly. + +Defaulting to open beta for everything. Open volume substituted for calibrated cohorts. Open is right for some contexts; not for all. + +Mismatching alpha/beta/RC to feature polish. Calling something "beta" when it is alpha (too many bugs); calling something "RC" when it is beta (not yet production-grade). + +Internal-only when external context matters. Validates an internal experience that does not match what customers will encounter. + +Open-ended without graduation criteria. Beta drifts into perpetual beta because no firm end was set. + +--- + +## Methodology-level choices that stay in the public skill + +The four axes (closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended). Strengths and weaknesses per axis. Worked combinations. Common mismatches. Beta type for specific contexts. Common failures. + +## Implementation choices that stay internal + +Specific platform feature-flagging configurations. Specific recruitment platforms and processes. Specific NDA templates. Specific time-bounding workflows. The team's own conventions for beta-type decisions in different contexts. These vary by team and tooling. diff --git a/skills/beta-program-management/references/beta-wind-down-communication.md b/skills/beta-program-management/references/beta-wind-down-communication.md new file mode 100644 index 0000000..8f77cc2 --- /dev/null +++ b/skills/beta-program-management/references/beta-wind-down-communication.md @@ -0,0 +1,231 @@ +# Beta wind-down communication + +Graduation announcement, transition, recognition, postmortem. Treating participants well. + +The beta's wind-down is its closing impression. Done well, participants leave the beta engaged and willing to participate in future betas. Done badly, participants feel discarded after providing significant feedback. + +--- + +## The graduation announcement + +Communication to participants when the beta graduates. + +Timing. 1-2 weeks before graduation, with confirmation at graduation. + +Content. + +- The feature is graduating to GA. Specific date. +- What changes for participants. +- What does not change. +- Recognition or thank-you for participation. +- Information about post-GA support, pricing, or special terms. +- Any beta-specific features or terms that will not carry to GA. + +Tone. Warm, appreciative. Participants invested time; the announcement reflects that. + +Length. 300-600 words. Long enough to cover the necessary information; short enough to be readable. + +--- + +## What changes for participants at graduation + +Continued access. Most beta participants retain access to the feature post-GA. The beta was their preview; GA continues their use. + +Pricing transitions. If the feature has paid tiers, participants need to know: + +- Does beta access include free use of the feature post-GA for some period? +- Does the feature require an upgraded plan for full access? +- Are there special pricing terms for beta participants (early-bird discount, lifetime grandfathering, etc.)? + +Feature stability. Communicate what level of stability participants should expect post-GA. Beta features sometimes have rough edges; GA implies stability commitments. + +Support transition. Beta-aware support routing typically ends at GA. Participants now use standard support channels. + +Beta-only features. Some features in the beta may not make GA (deprecated, simplified, removed). Participants who relied on those features need clear communication about alternatives. + +--- + +## Recognition + +Beta participants invested time providing feedback. Recognition matters. + +Forms of recognition. + +- Named in changelog or launch communications (with consent). +- Gift cards or compensation for substantial time investment. +- Swag for closed-beta participants. +- Advance access to future betas. +- Direct thank-you from product team, often via personal email. +- Public acknowledgment in marketing or community materials. + +Calibration. + +- Light betas: direct thank-you, possibly modest swag. +- Standard betas: thank-you, swag, post-GA continued access on favorable terms. +- Design partner programs: substantial recognition, sometimes including case studies, named partnerships, financial compensation. + +The discipline. Recognition matches the participant's investment. Light recognition for a heavy commitment feels dismissive; heavy recognition for a light commitment is unnecessary. + +--- + +## The post-beta survey + +A final feedback collection at graduation. + +Purpose. Capture overall reflections on the beta experience and the feature. + +Content. + +- Overall feature satisfaction. +- Likelihood to continue using post-GA. +- Likelihood to recommend. +- What worked well in the beta program (process feedback, not feature feedback). +- What could be improved in future betas. +- Optional open-ended reflections. + +Length. 5-10 questions, 5-10 minutes to complete. + +Why it matters. The post-beta survey closes the loop with participants and informs the team's beta-program practice. The process feedback is particularly valuable: future betas improve based on past feedback. + +--- + +## The beta postmortem + +Internal review of what the beta produced. + +Timing. Within 1-2 weeks of graduation. + +Participants. Beta program manager, product manager, engineering lead, design lead, customer success lead, support lead. + +Content. + +- What was learned from the beta? (Patterns, behavioral validation, friction discovery.) +- What changed in the GA launch as a result? +- What worked well in the beta program (process)? +- What did not work? What would the team do differently next time? +- What patterns recur across multiple betas? Are there lessons for the broader practice? + +Output. A short postmortem document. Surfaces lessons. Informs future betas. + +Why it matters. Beta programs improve through accumulated learning. Without postmortems, the team repeats the same mistakes; with postmortems, the practice gets sharper over time. + +--- + +## Recruiting for future betas + +The wind-down is a recruiting moment for future betas. + +The pattern. Participants who had a good beta experience are likely to participate in future ones. The wind-down communication can include an invitation: would they like to be considered for future betas? + +The benefits. + +- Builds a roster of engaged beta participants for future programs. +- Reduces recruiting overhead for future betas. +- Strengthens the participant relationship. + +The discipline. Do not over-commit; future betas should not be promised in ways that are not honored. The invitation is to be considered, not a guarantee. + +--- + +## Handling beta-only features that do not make GA + +Sometimes beta features include capabilities that are removed or simplified at GA. + +Why it happens. + +- The feature scope was reduced based on beta findings. +- Some capabilities did not perform well enough to ship at GA. +- The team learned the capability was not load-bearing. + +The communication. + +- Surface the change explicitly. Do not silently remove. +- Explain the reasoning where appropriate. +- Provide alternatives or workarounds for participants who relied on the removed capability. +- Acknowledge the impact on participants. + +The participant impact. Some participants may push back; their usage assumed the capability would persist. The team must decide whether to extend support, offer migration help, or accept the participant churn. + +--- + +## Special cases: extended beta + +Some betas extend beyond their planned duration. + +Communication for extension. + +- Tell participants when the extension is decided, not when the original end date passes. +- Explain why the extension is needed. +- Give a specific new end date. +- Acknowledge the participant impact (they committed to the original timeline). +- Provide an option to opt out if the extension is significant. + +Avoid. + +- Silent extensions where the planned end passes without acknowledgment. +- Multiple extensions that erode the timeline credibility. +- Extensions framed as "no big deal" when they affect participants' ongoing time investment. + +--- + +## Special cases: beta cancellation + +Sometimes the team decides not to graduate the feature to GA. + +Why it happens. + +- The beta revealed the feature does not work as intended. +- Strategic shift redirected resources. +- The feature would compete poorly at GA scale. + +The communication. + +- Be honest about the cancellation. +- Acknowledge the participants' time investment. +- Explain (at appropriate level of detail) why the cancellation. +- Discuss what happens to participants' beta data, configurations, etc. +- Recognize the participation despite the cancellation. + +The participant impact. Cancellation can frustrate participants who invested time. Honest communication and good recognition mitigate the impact. + +--- + +## Long-term participant relationships + +Beta participants represent ongoing relationships, not transactional interactions. + +The relationship investment. + +- Participants who had a good beta experience may become advocates, references, case study subjects. +- Future product strategy benefits from continued conversation with beta alumni. +- Customer success can use beta participation as relationship signal. + +The maintenance. Periodic check-ins with notable beta participants strengthen relationships even outside formal beta programs. Light-touch communication (annual newsletter, occasional product updates, personalized outreach for major launches) maintains the connection. + +--- + +## Common wind-down failures + +Silent graduation. Beta participants discover graduation through the public launch announcement rather than through advance communication. + +Vague transition information. Participants do not know what changes for them; uncertainty produces churn. + +Insufficient recognition. Heavy participation rewarded with thin thank-you; participants feel dismissed. + +Missing post-beta survey. Process feedback is lost; future betas do not improve. + +No postmortem. Internal lessons are lost; the team repeats mistakes. + +Surprise feature removals. Beta-only features removed without warning; participants discover at GA that capabilities they relied on are gone. + +No invitation to future betas. The relationship ends at graduation; future betas restart recruitment from scratch. + +--- + +## Methodology-level choices that stay in the public skill + +The graduation announcement structure. What changes for participants. Recognition forms and calibration. The post-beta survey. The beta postmortem. Recruiting for future betas. Handling beta-only feature removals. Extended betas. Beta cancellations. Long-term relationships. Common failures. + +## Implementation choices that stay internal + +Specific graduation announcement templates. Specific recognition packages and approval. Specific postmortem templates. Specific CRM tracking of beta alumni. The team's own conventions for relationship maintenance. These vary by team. diff --git a/skills/beta-program-management/references/cohort-sizing-patterns.md b/skills/beta-program-management/references/cohort-sizing-patterns.md new file mode 100644 index 0000000..1457a9e --- /dev/null +++ b/skills/beta-program-management/references/cohort-sizing-patterns.md @@ -0,0 +1,207 @@ +# Cohort sizing patterns + +Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. + +Cohort size is a calibration decision, not a maximize-volume decision. Each beta has a specific signal need; the right cohort size is the smallest that produces that signal reliably. + +--- + +## Saturation patterns by feedback type + +Different kinds of feedback saturate at different cohort sizes. + +Critical bugs (crashes, data loss, broken core flows). + +- Saturate fast: most surface in the first 1-2 weeks with 20-30 participants. +- Beyond ~50 participants, additional volume produces few new critical bugs. +- The cohort size for bug discovery: 20-50 participants is usually sufficient. + +Friction issues (workflow interruptions, confusing flows, slow performance in specific cases). + +- Saturate moderately: most surface in 2-4 weeks with 50-100 participants. +- Volume helps surface friction in less-common usage patterns. +- The cohort size for friction discovery: 50-200 participants typical. + +Behavioral patterns (how users actually use the feature, what flows they follow, what features they ignore). + +- Saturate slowly: 4-8 weeks with 100-500 participants needed for clear patterns. +- Patterns require usage volume; small cohorts may not generate enough usage to see patterns. +- The cohort size for behavioral signal: 100-500+ participants typical. + +Edge cases (unusual configurations, rare usage contexts, specific environment combinations). + +- Saturate very slowly: 500+ participants needed; some edge cases never surface in beta and are discovered post-GA. +- Volume is the only way to surface low-frequency edge cases. +- The cohort size for edge case discovery: 500-5,000+ participants; even at this scale, rare cases may slip through. + +Performance under load (scale-related issues, infrastructure constraints, concurrent-use issues). + +- Saturate when cohort exceeds the load threshold the issue requires. +- 1,000-10,000+ participants for at-scale validation. +- Often the central goal of RC betas. + +--- + +## Sizing decisions for different beta goals + +The cohort size matches what the team needs to learn. + +Goal: Catch critical bugs before GA. + +- Cohort size: 20-50 participants. +- Duration: 2-4 weeks. +- Closed cohort, calibrated to GA user profile. +- Most critical bugs surface fast; beyond this, returns diminish. + +Goal: Validate behavioral assumptions about how users will use the feature. + +- Cohort size: 100-300 participants. +- Duration: 4-8 weeks. +- Closed cohort with variety across usage patterns. +- Behavioral patterns need usage volume to emerge clearly. + +Goal: Validate product-market fit assumptions for a major new feature. + +- Cohort size: 200-500 participants. +- Duration: 8-12 weeks. +- Closed cohort spanning segments. +- Long enough duration to see retention and continued usage, not just initial engagement. + +Goal: Validate at-scale infrastructure for a launch. + +- Cohort size: 1,000-5,000+ participants. +- Duration: 4-8 weeks. +- Often open beta or large closed RC. +- Volume is the point; calibration is less important than scale. + +Goal: Build a design partner program for ongoing collaboration. + +- Cohort size: 3-10 partners. +- Duration: open-ended (months to years). +- Highly calibrated cohort with strong relationships. +- Depth over breadth; the program is qualitative collaboration, not at-scale validation. + +Goal: Generate pre-launch marketing and audience. + +- Cohort size: 1,000-10,000+ participants. +- Duration: 4-12 weeks. +- Open beta with marketing-driven recruitment. +- The cohort serves both validation and pre-launch buzz. + +--- + +## The size-matches-signal principle + +The cohort should be the smallest size that produces the signal the team needs. + +Why "smaller is better when calibrated." + +- Smaller cohorts produce more synthesizable feedback. The team can read every transcript, review every survey response, follow up with every participant who reports an issue. +- Smaller cohorts make participant relationships stronger. Each participant feels seen; engagement is higher. +- Larger cohorts produce volume that can drown signal. The team cannot synthesize 5,000 pieces of feedback as well as 50. + +When larger is necessary. + +- The team needs at-scale validation (load, concurrent users, edge cases). +- The team needs marketing reach. +- The team needs behavioral signal that requires substantial usage volume. + +The discipline. Default to the smallest cohort that produces the needed signal. Justify any larger size against specific signal needs. + +--- + +## Cohort size and feedback channel design + +Larger cohorts require different feedback channel design than smaller ones. + +For cohorts of 5-50. + +- Direct channels work: email, dedicated Slack, structured interviews. +- The team can engage with each participant individually. +- Synthesis can include reviewing all feedback. + +For cohorts of 50-500. + +- Mixed channels: structured surveys + sample interviews + in-product feedback widgets. +- Sampling required for synthesis: review all surveys, sample interviews and tickets. + +For cohorts of 500-5,000. + +- Aggregated channels: in-product feedback widgets, support ticket aggregation, automated surveys. +- Heavy sampling: review aggregate patterns, sample individual feedback. + +For cohorts of 5,000+. + +- Volume aggregation: NPS-style scoring, automated categorization, statistical analysis of usage patterns. +- Individual feedback rarely reviewed; patterns are the signal. + +The implication. Beta planning includes feedback channel design appropriate to cohort size. Mismatches (small cohort with aggregated channels, or large cohort with direct channels) produce friction. + +--- + +## Adjusting cohort size mid-beta + +Sometimes the team realizes mid-beta that the cohort is wrong-sized. + +Cohort too small. + +- Symptom: feedback volume is insufficient to see patterns. +- Cure: open recruitment for additional participants, applying the same selection criteria. +- Caution: late additions have less time in the beta; their feedback covers less of the beta period. + +Cohort too large. + +- Symptom: feedback volume overwhelms synthesis capacity; the team is reactive rather than analytical. +- Cure: usually do not reduce; instead, scale up synthesis capacity (more reviewers, more aggregation tooling). Reducing cohort feels like a betrayal to participants. +- Prevention: better sizing decision upstream. + +Cohort skewed. + +- Symptom: feedback patterns reflect skew (one segment over-represented). +- Cure: targeted recruitment to balance the cohort, or explicit acknowledgment of skew in synthesis. +- The cohort cannot always be re-balanced quickly; sometimes the synthesis adjusts for the skew rather than the cohort. + +--- + +## Cohort and beta duration + +Cohort size and duration interact. + +Short beta (2-4 weeks). Smaller cohort works because feedback saturates faster on critical issues. 20-100 participants typical. + +Medium beta (4-8 weeks). Mid-size cohort matches the duration. 50-300 participants typical. + +Long beta (8+ weeks). Larger cohort works because behavioral signal needs duration. 100-1,000+ participants. + +The mismatch failures. + +- Long beta with small cohort: insufficient volume; the duration produces no proportional signal. +- Short beta with very large cohort: insufficient time; the volume produces no proportional learning. + +The matching. Beta duration and cohort size both follow from signal need; they should be consistent. + +--- + +## Common cohort sizing failures + +Defaulting to "more is better." Large cohorts where small calibrated ones would produce stronger signal. + +Sizing without reference to signal need. Cohort size set arbitrarily; team cannot defend why this size. + +Cohort size mismatched to duration. Small cohort in a long beta produces sparse signal; large cohort in a short beta produces noise. + +Cohort size mismatched to feedback channel design. Direct channels with too many participants overwhelm; aggregated channels with too few participants under-utilize. + +Mid-beta cohort changes without synthesis adjustment. Cohort grows or shrinks; the synthesis approach does not adapt. + +Confusing volume with signal. Larger cohort numbers reported as success; the team did not actually learn proportionally more. + +--- + +## Methodology-level choices that stay in the public skill + +The saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. Cohort size and feedback channel design alignment. Adjusting cohort size mid-beta. Cohort and beta duration interaction. Common failures. + +## Implementation choices that stay internal + +Specific recruitment automation tooling. Specific aggregation tooling for large cohorts. Specific synthesis processes for different cohort sizes. The team's own conventions for sizing within the bands. These vary by team and tooling. diff --git a/skills/beta-program-management/references/common-beta-failures.md b/skills/beta-program-management/references/common-beta-failures.md new file mode 100644 index 0000000..204a1c2 --- /dev/null +++ b/skills/beta-program-management/references/common-beta-failures.md @@ -0,0 +1,205 @@ +# Common beta failures + +Ten-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most beta failures share a single root, which is treating beta as ceremony rather than as decision input. + +--- + +## Failure 1: Our beta produced no signal + +Symptom. The beta ran. The team has nothing actionable to show for it. The GA launch will happen with the same uncertainty the beta was supposed to address. + +Diagnosis. Soft-launch pattern. No structured selection, no defined feedback collection, no graduation criteria. + +Cure. Restructure the beta. Define the cohort, channels, criteria, and triage cadence. If the current beta cannot be saved, plan a more structured beta for the next feature. + +Prevention. Plan beta structure at the start, not after the beta has been running. + +--- + +## Failure 2: Our beta has 5,000 users and we cannot synthesize + +Symptom. Open beta or large cohort. Volume is high. The team is reactive rather than analytical. Synthesis cannot keep up. + +Diagnosis. Kitchen-sink. Cohort too large for the structured signal the team needs. + +Cure. Two paths. Scale up synthesis capacity (more reviewers, aggregation tooling). Or reduce the active cohort by focusing structured channels on a calibrated subset (e.g., select 200 active participants for interviews; let the rest contribute through aggregated channels). + +Prevention. Size cohort to match synthesis capacity. Larger cohorts require aggregated feedback infrastructure. + +--- + +## Failure 3: Our beta participants never gave feedback + +Symptom. Few survey responses. Few in-product widget submissions. Few interview signups. The cohort is silent. + +Diagnosis. Onboarding contract was unclear or feedback channels were friction-laden. Participants did not know what was expected or could not easily give feedback. + +Cure. Re-engage. Send specific, prompted requests for feedback. Make the channels easier (in-product prompts, simpler forms). Communicate what is being heard from those who do respond. + +Prevention. Onboarding makes feedback expectations explicit. Channels are designed for low friction. + +--- + +## Failure 4: We graduated to GA on schedule but launched with critical bugs + +Symptom. The GA launches. Critical issues that the beta cohort would have surfaced (or did surface but were not addressed) appear post-GA. + +Diagnosis. Graduation criteria were not enforced. The decision was calendar-driven; the team graduated before the criteria were met. + +Cure. Damage control: address the bugs quickly, communicate transparently, reset support expectations. + +Prevention. Graduation criteria are enforced honestly. The decision is criteria-driven, not calendar-driven. If criteria are not met, extend the beta or graduate with explicit acknowledgment of unmet criteria. + +--- + +## Failure 5: Our beta has been running for 8 months with no graduation + +Symptom. Beta has run far longer than planned. No firm graduation date. The team has avoided the GA decision. + +Diagnosis. Perpetual beta. No firm graduation criteria; the team avoided commitment. + +Cure. Force the graduation decision. Define criteria explicitly. Decide: graduate now, graduate by a specific date, or reset the beta. + +Prevention. Time-bound the beta from the start. Define graduation criteria upfront. Force the decision when the criteria are met or when the time is up. + +--- + +## Failure 6: Beta participants vented on Twitter before the launch + +Symptom. Beta participants posted screenshots, mentioned the feature publicly, or discussed the beta outside the cohort. + +Diagnosis. NDA missing or unclear. Trust violation early erodes participant willingness; broader visibility may damage launch plans. + +Cure. Damage control depending on impact. Reach out to participants individually. Adjust the launch plan if the leaked information affects positioning. + +Prevention. NDAs in place where appropriate. Confidentiality expectations explicit in onboarding. Cohort selection includes trust assessment. + +--- + +## Failure 7: The beta surfaced patterns we did not act on + +Symptom. The beta produced clear feedback about specific issues. The GA launches without addressing them. Customers hit the same issues post-GA. + +Diagnosis. Mid-beta triage missing. Feedback was collected but not used during the beta. + +Cure. For the GA: address the issues quickly post-launch; communicate transparently. For future betas: implement the triage cadence and iteration discipline. + +Prevention. Weekly triage cadence. Categorization of feedback. Iteration on critical and high-impact items during the beta. + +--- + +## Failure 8: The GA launch surprised us + +Symptom. Issues emerge at GA that the team did not anticipate from the beta. The beta did not actually validate the GA experience. + +Diagnosis. Cohort or feedback structure was wrong. The cohort did not match the GA user; the channels did not surface the kinds of issues the GA exposed. + +Cure. Address the surprises post-GA. Investigate the gap between beta and GA experience. Apply lessons to future betas. + +Prevention. Cohort calibrated to GA user. Channels designed to surface the kinds of signal the GA decision needs. Validation of the cohort-GA match before the beta starts. + +--- + +## Failure 9: Beta participants felt ignored after providing feedback + +Symptom. Participants gave feedback. The team did not communicate what was heard or addressed. Participants disengaged. + +Diagnosis. Communication discipline missing. Participants commit time and want to know it mattered. + +Cure. Re-engage with appreciation and specific acknowledgment. For future participants, tighten the communication discipline. + +Prevention. Weekly or bi-weekly updates to participants. Updates reference specific feedback. Participants who give substantive feedback receive direct acknowledgment. + +--- + +## Failure 10: We ran a closed beta that was effectively employees only + +Symptom. The "external beta" included primarily employees, employees' family members, or very-friendly customers. Not actual representative customers. + +Diagnosis. Internal-only beta with external branding. Missed the customer-context complexity. + +Cure. Run a true external beta before GA, even if shorter. Apply lessons to future cohort selection. + +Prevention. Cohort selection includes "are these actually external customers using the product in real conditions?" Internal-leaning cohorts get flagged in cohort review. + +--- + +## Failure 11: Cohort and channels mismatched + +Symptom. Small cohort with aggregated channels (no signal extracted from the small volume). Or large cohort with direct channels (overwhelmed synthesis). + +Diagnosis. Cohort size and channel design did not align. + +Cure. Adjust mid-beta if possible: scale synthesis for large cohorts, deepen direct channels for small ones. + +Prevention. Cohort size and channel design decided together. Mismatches caught at planning. + +--- + +## Failure 12: Feedback collected but not synthesized + +Symptom. Surveys completed; widgets submitted; interviews recorded. The beta ends; the team has not synthesized the feedback into patterns or recommendations. + +Diagnosis. Synthesis was treated as optional or postponed. Without synthesis, the feedback never produced decisions. + +Cure. Allocate synthesis time post-beta. Apply discovery-research-synthesis discipline (see that skill). Produce the synthesis even if delayed. + +Prevention. Plan synthesis as part of the beta timeline. Allocate explicit time and ownership. + +--- + +## Failure 13: Wind-down treated participants poorly + +Symptom. Participants graduated to GA without clear transition information. Recognition was thin or missing. Future-beta recruitment is harder because alumni are unenthused. + +Diagnosis. Wind-down communication missed key elements. Recognition was insufficient for the time invested. + +Cure. Reach out individually to participants who feel underrecognized. Adjust future wind-down templates. + +Prevention. Wind-down communication template covers all elements (transition, recognition, post-survey, future beta invitation). + +--- + +## Failure 14: No postmortem + +Symptom. Beta ends; team moves on. Lessons from this beta do not inform future ones. Patterns recur across multiple betas because nobody surfaced them. + +Diagnosis. Postmortem was skipped. The beta program does not improve. + +Cure. Run a delayed postmortem if feasible. Establish postmortem as a non-negotiable step. + +Prevention. Postmortem on the timeline. Owner identified. Lessons documented and applied. + +--- + +## Failure 15: Beta scope crept + +Symptom. Mid-beta, additional capabilities were added based on participant requests. The beta validated a different feature than the original. + +Diagnosis. Scope creep during the beta. Feature requests were absorbed into the live beta. + +Cure. Reset the beta if the changes are significant. Capture for post-GA roadmap rather than addressing during the beta. + +Prevention. Triage discipline rejects scope-expanding feature requests during the beta. Capture for post-GA; do not add. + +--- + +## The cross-cutting pattern + +Most beta failures share a single root: treating beta as ceremony rather than as decision input. + +Ceremony focuses on running a beta because betas are expected: invite participants, collect feedback, ship the GA. The beta is a stage gate, not a learning loop. + +Decision input focuses on what the beta needs to inform: which decisions, what signal will inform them, what cohort and channels will produce that signal. The beta is structured around the decision it serves. + +The fix for almost any beta failure starts with the same question: what specifically did the team need to learn from this beta, and how is the beta structured to produce that learning? When the answers are clear, the beta becomes load-bearing. When the answers are vague, the beta becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-decision pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/beta-program-management/references/feedback-collection-patterns.md b/skills/beta-program-management/references/feedback-collection-patterns.md new file mode 100644 index 0000000..49e1bbf --- /dev/null +++ b/skills/beta-program-management/references/feedback-collection-patterns.md @@ -0,0 +1,295 @@ +# Feedback collection patterns + +Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline. + +The feedback collection design is what determines whether the beta produces signal or noise. Structured channels capture usable data; ad-hoc venting channels produce volume that does not synthesize. + +--- + +## Structured surveys + +Surveys at defined points in the beta. + +The structure. + +- 5-15 questions per survey. +- Mix of structured questions (Likert scale, multiple choice) and 1-2 open-ended questions. +- Tied to specific learning goals: each question has a reason for being there. +- Sent at defined points: end of week 1, mid-beta, end of beta. + +Strong survey questions. + +- "On a scale of 1-7, how likely are you to use this feature daily?" (closed-ended; quantitative signal) +- "What's the most useful thing you've done with this feature so far?" (open-ended; surfaces use cases) +- "What was confusing or frustrating in your first week?" (open-ended; surfaces friction) +- "Compared to how you did this task before, is this feature better, worse, or about the same?" (specific comparison) + +Weak survey questions. + +- "Do you like the feature?" (binary; not actionable) +- "What features would you like next?" (out of beta scope; produces wishlist) +- "How can we improve?" (too open-ended; produces unfocused responses) + +Why structured surveys work. + +- Quantitative signal aggregates. Mid-beta NPS or satisfaction trend lines surface signal. +- Open-ended questions tied to specific topics produce focused qualitative data. +- Participants understand what is being asked; response rates are higher than for vague open-ended surveys. + +--- + +## Async feedback forms + +Forms participants fill when they encounter specific issues. + +The structure. + +- Always-available link or in-product entry point. +- Form fields prompt for specific information: use case, severity, expected vs actual behavior, screenshots if applicable. +- Auto-routes to the team's tracking system (issue tracker, feedback aggregation tool). + +Strong form fields. + +- "What were you trying to do?" (use case context) +- "What did you expect to happen?" (mental model) +- "What actually happened?" (observed behavior) +- "How blocking is this?" (severity) +- "Steps to reproduce" (when applicable) + +Why async forms work. + +- Captures issues at the moment they happen. +- Structured fields produce consistent data across submissions. +- Synthesis is easier when each submission has the same information shape. + +--- + +## Structured interviews + +30-60 minute interviews with a subset of participants. + +The structure. + +- 5-15 interviews per beta, depending on cohort size. +- Mid-beta or near end of beta. +- Discussion guide tied to the team's learning goals. +- Recorded with permission; transcribed for synthesis. + +Strong interview prompts. + +- "Walk me through the last time you used this feature. What were you trying to do?" +- "What was the most useful thing about it? What was the most frustrating?" +- "How did you decide to use this instead of [alternative]?" +- "Looking back, what do you wish was different?" + +Why structured interviews work. + +- Depth that surveys cannot capture. +- Specific moments and decisions surface in conversation that participants would not write into surveys. +- The qualitative data complements the quantitative survey data. + +Cross-reference `discovery-research-synthesis` for the broader interview discipline. Beta interviews are validation-stage; the interviewing methodology is similar. + +--- + +## In-product feedback widgets + +Feedback collection contextualized to the moment. + +The structure. + +- Trigger: button or prompt within the beta feature. +- Captures: what the user was doing (page or context), brief feedback text, optional rating. +- Routes to the team's tracking system. + +Strong in-product widget design. + +- Triggered after specific moments (completing the feature's primary action, abandoning a flow). +- Brief: 1-3 fields max. +- Optional severity or sentiment rating. +- Captures the page or context automatically. + +Why in-product widgets work. + +- Capture friction at the moment, not weeks later. +- Context is preserved automatically. +- Low friction encourages submissions. + +--- + +## Beta-aware support tickets + +Support tickets routed to a beta-aware support team. + +The structure. + +- Beta participants flagged in the support system. +- Tickets from beta participants get special handling: tagged "beta," routed to support reps trained on the feature, given priority response. +- Common beta issues documented for the support team in advance. + +Strong beta-support practices. + +- Faster response than standard tickets (the participant is doing the team a favor). +- Support reps escalate beta issues to product team where the issue affects beta program decisions. +- Patterns across tickets surface to the beta program manager. + +Why beta-aware support works. + +- Surfaces issues participants encounter "in the wild," not just the issues they choose to flag through formal channels. +- Captures the support burden of the feature, which informs GA support readiness. + +--- + +## Channels that fail + +Common feedback channels that produce noise rather than signal. + +Beta-only Slack channels for venting. + +- Participants vent in real time. +- Mixes critical signal with casual chat. +- Nobody synthesizes. +- High-engagement participants drown out quieter ones. +- Cure: structured channels instead, or use Slack for community building rather than feedback collection. + +"Reply to this email with feedback." + +- Returns long unstructured emails. +- Synthesis is hard; useful patterns get lost. +- Cure: structured forms or surveys. + +End-of-beta survey only. + +- Catches only what participants remember at the end. +- In-the-moment friction is forgotten. +- Cure: surveys at multiple points; in-product widgets for moment-of capture. + +"Tell us anything." + +- Unfocused open-ended prompts produce unfocused responses. +- Participants do not know what is wanted; many do not respond. +- Cure: specific prompts tied to what the team needs to learn. + +--- + +## Channel mix discipline + +Most structured betas use 3-5 channels. Each surfaces different signal. + +Typical channel mix. + +- 1 structured survey at end of week 1 (quantitative + first-impression qualitative). +- 1 structured survey at mid-beta (quantitative trend + behavior signal). +- Always-available async feedback form (specific issues as they arise). +- 5-10 structured interviews near end of beta (qualitative depth). +- In-product feedback widget (in-the-moment friction). +- Beta-aware support routing (issues participants choose to escalate). + +The synthesis. The team synthesizes across channels. Patterns that appear in multiple channels are stronger; signals from a single channel are weaker. + +Channel mix calibration. + +- Smaller cohorts (5-50): more interviews, less aggregation. +- Larger cohorts (100-500): more surveys and aggregation, fewer interviews. +- Largest cohorts (500+): heavy aggregation, sampling for interviews. + +--- + +## Feedback synthesis cadence + +How feedback gets reviewed during the beta. + +Weekly synthesis. + +- 1-2 hours weekly during the beta. +- Review feedback across all channels for the week. +- Categorize: critical bug, friction, feature request, positive signal, edge case. +- Surface patterns: what recurring feedback are we seeing? + +Bi-weekly pattern review. + +- 1-2 hours bi-weekly. +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening? +- Decide: what to fix during the beta vs what to defer to post-GA roadmap. + +End-of-beta synthesis. + +- Substantial work: 1-2 weeks of synthesis depending on cohort size. +- Apply discovery-research-synthesis discipline (see that skill). +- Output: beta synthesis document with patterns, implications, and graduation recommendation. + +--- + +## Feedback signal quality + +Not all feedback is equally valuable. + +High-signal feedback. + +- Specific moments of friction with reproducible context. +- Patterns across multiple participants. +- Behavioral data showing what users actually do (vs what they say). +- Comparison to alternatives (what users tried before, why they switched). + +Lower-signal feedback. + +- One-off complaints with no pattern. +- Hypothetical preferences ("it would be nice if..."). +- Wishlist features unrelated to the beta scope. +- Venting without specific context. + +The discipline. Synthesis weights higher-signal feedback. Lower-signal feedback gets noted but does not drive decisions. + +--- + +## Feedback volume management + +Managing the flow of feedback as the beta runs. + +Volume signals. + +- Critical issues surface fast: most appear in the first 2 weeks. +- Friction issues surface continuously through the beta. +- Behavioral signal accumulates; visible by mid-beta. + +Volume management. + +- The team's synthesis capacity bounds usable volume. Beyond that capacity, additional feedback produces less actionable signal. +- For larger cohorts, aggregate channels (surveys, in-product widgets) scale better than direct channels (Slack, email). + +Burnout risk. + +- Beta program managers reading 100+ feedback items per week burn out. +- Triage is the discipline: not all feedback gets equal attention. +- Critical and pattern feedback gets full attention; one-off venting gets noted briefly. + +--- + +## Common feedback collection failures + +Single-channel reliance. Only one feedback channel; misses signal that other channels would have caught. + +Channels not tied to learning goals. Feedback collected without clear purpose; synthesis cannot tell what to do with it. + +Noisy channels (Slack venting). High volume, low signal-to-noise ratio. + +End-of-beta only. Misses in-the-moment friction; relies on participant memory. + +Vague prompts. Open-ended questions without focus; produces unfocused responses. + +No mid-beta synthesis. Feedback collected but not reviewed until end; opportunities to address issues during the beta missed. + +Feedback channels that conflict. Multiple Slack channels for the same purpose; participants confused about where to post. + +No closing the loop. Participants give feedback; team never tells them what was heard or changed; engagement decays. + +--- + +## Methodology-level choices that stay in the public skill + +Channels that work (structured surveys, async forms, interviews, in-product widgets, beta-aware support). Channels that fail. Channel mix discipline. Feedback synthesis cadence. Signal quality discipline. Volume management. Common failures. + +## Implementation choices that stay internal + +Specific survey tools and templates. Specific feedback form integrations. Specific in-product widget implementations. Specific support ticketing systems. The team's own conventions for channel selection. These vary by team and tooling. diff --git a/skills/beta-program-management/references/mid-beta-triage-and-iteration.md b/skills/beta-program-management/references/mid-beta-triage-and-iteration.md new file mode 100644 index 0000000..aa2614c --- /dev/null +++ b/skills/beta-program-management/references/mid-beta-triage-and-iteration.md @@ -0,0 +1,216 @@ +# Mid-beta triage and iteration + +Triage cadence. Iteration discipline (what to fix during the beta, what to defer). Communication with participants. + +Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. Mid-beta triage turns a static validation into an iterative one. + +--- + +## The triage cadence + +How the team reviews feedback during the beta. + +Weekly triage (1-2 hours). + +- Review feedback across all channels for the week. +- Categorize each piece: critical bug, friction issue, feature request, positive signal, edge case. +- Tag for action: fix this week, fix later in the beta, defer to post-GA, no action needed (one-off). +- Identify any critical issues warranting immediate response. + +Bi-weekly pattern review (1-2 hours). + +- Look at patterns across the past 2-4 weeks. +- Identify converging signal: which patterns are strengthening, which are not surfacing in volume? +- Surface decisions: what to address in the remaining beta period. + +As-needed escalation. + +- Critical issues (data loss, security, broken core flows) get same-day response regardless of cadence. +- The triage cadence does not delay critical-issue response. + +--- + +## Categorization + +Each piece of feedback gets categorized. + +Categories. + +- Critical bug. Crashes, data loss, broken core flows, security issues. Must be fixed before GA. +- Friction issue. Workflows that are confusing, slow, or sub-optimal but functional. Fix during beta where feasible; document otherwise. +- Feature request. Capability the participant wants that is outside beta scope. Capture for post-GA roadmap; do not add during beta. +- Positive signal. What is working well; what users find valuable. Surfaces what to preserve in GA and what to highlight in marketing. +- Edge case. Unusual configurations or contexts. Note for post-GA monitoring; address only if affecting many participants. +- One-off. Single observation without pattern. Note briefly; do not action. + +Why categorization matters. + +- Different categories have different action paths. Treating all feedback the same overwhelms triage. +- The categorization is the basis for the iteration decisions. + +--- + +## What to fix during the beta + +The team should fix some things during the beta and defer others. + +Fix during the beta. + +- Critical bugs that prevent participants from using the feature. The beta cannot validate the feature if participants cannot use it. +- Friction issues that are clearly addressable and significantly affect participant experience. Fixing them produces stronger end-of-beta signal. +- Issues that, if unfixed, will surface again post-GA at higher cost. +- Issues that participants are about to escalate publicly (if NDA-relevant) or that damage trust if left. + +Defer to post-GA. + +- Feature requests outside beta scope. +- Friction issues that affect a small subset of users in ways the team can document. +- Polish work that does not block the GA decision. +- Edge cases that do not affect mainline usage. + +The "what changes the GA decision" test. If fixing this issue affects whether the team can ship to GA, fix it. If it does not affect the GA decision, capture it for post-GA roadmap. + +--- + +## The iteration discipline + +Mid-beta iteration adds value but has constraints. + +The discipline. + +- Iterate on the feature, not the beta scope. Adding features to the beta mid-way confuses participants and dilutes signal. +- Fix critical and high-impact friction; capture rather than fix lower-impact issues. +- Communicate iteration to participants: when they see a fix or change, they know it came from their feedback. + +The "do not redesign mid-beta" rule. + +- Significant feature changes mid-beta produce two betas: the pre-change beta and the post-change beta. Neither is fully validated. +- If significant changes are needed, end the current beta, redesign, and start a new beta. Do not blend them. + +The "no creep" discipline. + +- Mid-beta is not the time to add capabilities outside the beta's original scope. +- Feature requests get captured for post-GA, not added to the beta. +- The beta's signal depends on consistency; scope creep undermines the validation. + +--- + +## Communication with participants + +Mid-beta communication keeps participants engaged. + +The cadence. + +- Weekly or bi-weekly updates to participants. +- Format: short email or in-product notification. +- Content: what was heard, what is being addressed, what is being deferred, what to expect next week. + +Strong update content. + +- "We heard your feedback about the configuration friction in step 3. We pushed a fix this week; please let us know if it is improved." +- "Several of you reported the dashboard load time is slow at scale. We are investigating; we expect a fix in the next 1-2 weeks." +- "We are seeing strong positive signal on the new export functionality. We will expand the format options in the next iteration." +- "Several of you requested integrations beyond the beta scope. We have captured these for post-GA roadmap." + +Why communication matters. + +- Participants who see their feedback acted on engage more substantively. +- Participants who feel ignored decay. +- Communication signals to participants that the team is listening. + +Common communication failures. + +- Silence between welcome and end of beta. Participants feel ignored. +- Generic updates that do not reference specific feedback. Feels performative. +- Over-communication. Daily updates are too much; participants tune out. +- Updates that promise more than the team will deliver. Erodes trust when promises are not kept. + +--- + +## The mid-beta health check + +A specific mid-beta milestone. + +The milestone. Roughly the midpoint of the beta. The team takes stock of where the beta is. + +The questions. + +- Is the feedback volume what was expected? If not, what is causing the difference? +- Are critical issues surfacing or has the team caught them all in the first part of the beta? +- Are behavioral patterns emerging? What do they suggest for the GA experience? +- Are participants engaged? Are some segments dropping off? +- Is the trajectory toward graduation criteria? Where are gaps? + +The output. + +- Adjustments to the beta operations: more triage, more communication, additional cohort recruitment if needed. +- Surfaced concerns about graduation: are the criteria reachable in the remaining beta time? +- Surfaced wins: what is going well that the team can build on for GA. + +--- + +## Mid-beta participant churn + +Some participants will drop off during the beta. + +Why participants churn. + +- The feature did not match their use case (they expected something different). +- They lost interest or got busy. +- They hit critical friction early and gave up. +- They felt ignored after providing feedback. + +The response. + +- Investigate churn. A subset of churn is normal; high churn is signal. +- For participants who churned because of friction: address the friction; possibly re-engage them. +- For participants who churned because of misfit: the cohort may have been miscalibrated; learn for future betas. +- For participants who felt ignored: tighten the communication discipline; thank them for prior feedback even if they have stopped engaging. + +Replacement recruitment. + +- For betas that need a specific cohort size for signal, replace churned participants if possible. +- Late-recruited replacements have less time in the beta; their feedback covers less of the beta period. +- Sometimes accepting churn and a smaller-than-planned cohort is the right call. + +--- + +## Triage anti-patterns + +Common ways triage decays. + +Triage skipping. No formal triage cadence; feedback accumulates without categorization or action. + +Triage as logging. Feedback gets categorized but never actioned. The categorization is documentation theater. + +Triage by loudest voice. Loudest participants get attention; quieter ones with similar feedback do not. Skews the synthesis. + +Triage by easiness. Easy fixes get prioritized regardless of impact. Important harder fixes get deferred indefinitely. + +Triage without communication. Internal triage happens but participants are not told. They feel ignored. + +Triage that absorbs feature requests. Participants request features outside scope; the team adds them mid-beta; scope creeps; signal dilutes. + +--- + +## Common iteration failures + +No iteration during the beta. Feedback is collected; the team waits for end of beta; opportunities to address issues during the beta are missed. + +Excessive iteration. Significant feature changes mid-beta. The beta becomes two different betas; neither validates the GA experience cleanly. + +Iteration without communication. The team fixes issues; participants do not know; engagement decays. + +Iteration on participant requests outside scope. Scope creep; the beta validates a different feature than the original. + +No closing the loop. Iterations happen; participants are not told their feedback drove the change; the connection between feedback and improvement is invisible. + +--- + +## Methodology-level choices that stay in the public skill + +The triage cadence. The categorization scheme. What to fix during the beta vs defer. The iteration discipline. The "do not redesign mid-beta" rule. Communication with participants. The mid-beta health check. Mid-beta churn handling. Common failures. + +## Implementation choices that stay internal + +Specific triage tools and trackers. Specific communication templates. Specific health-check formats. The team's own conventions for what counts as critical vs friction. These vary by team and tooling. diff --git a/skills/beta-program-management/references/participant-selection-criteria.md b/skills/beta-program-management/references/participant-selection-criteria.md new file mode 100644 index 0000000..b95bbcf --- /dev/null +++ b/skills/beta-program-management/references/participant-selection-criteria.md @@ -0,0 +1,212 @@ +# Participant selection criteria + +Criteria that produce calibrated cohorts. Common selection failures. The cohort size question. + +Participant selection determines what the beta can produce. Calibrated cohorts produce decision-grade signal; misaligned cohorts produce noise that does not represent the GA user. Selection is upstream of every other beta decision. + +--- + +## Criteria that produce calibrated cohorts + +Match the post-launch user profile. If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. + +- Worked example: a feature for product managers at growth-stage SaaS companies. Beta participants should be PMs at growth-stage SaaS companies. Not designers, engineers, or PMs at very-early or very-late stage companies. +- The matching dimensions depend on the feature: role, company size, industry, usage volume, tenure, technical sophistication. + +Variety across relevant dimensions. Not all participants identical. + +- If the feature has segment-specific behavior, the cohort spans segments. +- If usage volume varies, the cohort includes high-volume and low-volume users. +- If geography matters (compliance, latency, language), the cohort spans relevant geographies. +- The variety should match the GA user diversity. + +Feedback willingness. Participants who agree to provide feedback through structured channels. + +- Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey"). +- Recruiting should make the feedback expectation explicit. Participants who agree are more likely to engage; participants who decline are honest about their availability. + +Existing relationship strength. Customers with strong existing relationships are more likely to engage substantively. + +- Champion users, design partners, customers with active customer success relationships engage more. +- Customers in churn-risk are less likely to engage; their feedback may also be less representative (the relationship is already strained). + +Real usage of the broader product. Beta participants who use the broader product actively can give grounded feedback. Participants who signed up only for the beta and do not use the product otherwise often give surface-level feedback. + +--- + +## Criteria that produce miscalibrated cohorts + +Self-selection only. Open beta sign-ups skew toward enthusiasts and tinkerers. + +- Skews toward users who try every new feature; their feedback may not represent the broader target user. +- Misses users who would adopt at GA but who do not seek out beta sign-ups. + +Highest-paying customers only. Skews toward enterprise patterns. + +- Misses smaller-team and individual use cases. +- Enterprise feedback may emphasize features that smaller customers do not need. + +Internal employees only. Misses customer-context complexity. + +- Employees experience features differently than customers (familiarity, infrastructure, motivations). +- Internal-only validation produces "we tested" without "real customers tested." + +Whoever happens to be available. No selection criteria; the cohort is whoever the team can recruit quickly. + +- The cohort may not match the GA user; signal does not transfer to the GA decision. + +Champion users only. All beta participants are existing strong advocates. + +- Enthusiastic feedback may overstate readiness; missing the friction non-champion users would hit. + +--- + +## Variety calibration + +How to ensure the cohort spans the relevant dimensions. + +The dimension audit. + +- For the feature being beta'd, identify the dimensions that affect user experience. +- Common dimensions: role, company size, industry vertical, usage volume, geographic region, technical sophistication, tenure with the product. +- Decide which dimensions matter most for this feature. + +Cohort composition. + +- For each high-priority dimension, ensure the cohort includes representation across the values. +- If role matters: cohort includes participants in each relevant role. +- If usage volume matters: cohort includes high-volume, mid-volume, low-volume users. +- If industry varies meaningfully: cohort spans industries. + +Worked example. A feature for product managers using analytics tools. + +- Role dimension: cohort is all PMs (no other roles). +- Usage dimension: high-volume PMs (active daily users) + mid-volume PMs (weekly users). Skip low-volume because they likely will not use the feature meaningfully. +- Company size dimension: 10-50 employee, 50-200 employee, 200-500 employee. Skip enterprise (different feature priorities). +- Tenure dimension: PMs who have used the product 3+ months (so they have established workflows the new feature will integrate into). Skip new users. + +The cohort composition is intentional; each participant fits multiple criteria. + +--- + +## The cohort size question + +How many participants are enough. + +The calibration is signal-need-driven. + +- Bug discovery saturates fast: 20-30 participants surface most critical issues in 2-4 weeks. +- Behavioral signal saturates slower: 50-100 participants needed to see usage patterns clearly. +- Edge case discovery: 100-500+ participants needed; some edge cases never surface in beta. + +Common cohort sizes by beta type. + +- Design partner program: 3-10 participants. +- Closed alpha: 10-30 participants. +- Closed beta: 50-200 participants. +- Open beta: 500-5,000+ participants. +- RC validation: 1,000-10,000+ participants. + +The "more is better" anti-pattern. Teams default to large cohorts thinking volume produces signal. In practice, larger-than-needed cohorts produce volume without proportional signal increase, while making feedback synthesis harder. + +The "smaller produces calibrated" principle. A 50-person calibrated cohort often produces stronger signal than a 5,000-person uncalibrated one. Pick the smallest cohort that produces the signal needed. + +--- + +## The recruitment process + +How participants get selected. + +Sources. + +- Existing customer base: customer success identifies candidates matching the criteria. +- Sales pipeline: late-stage prospects who could become customers and provide feedback. +- Past beta participants: customers who participated in prior betas and proved engaged. +- Public sign-up forms (for open betas): with screening criteria applied to actual selection. +- Partner referrals: customers who recommend other customers fitting the profile. + +The screening. + +- Define the criteria explicitly (role, dimension values, feedback willingness). +- Apply the screening to candidates: who fits the criteria? +- For closed betas, decide which subset of fitting candidates to invite (cohort sizing). +- For open betas with screening, the sign-up form captures qualifying information; the team selects from sign-ups. + +The invitation. + +- Personalized invitations engage better than mass invitations. +- The invitation explains: what the beta is, what is expected, what participants get, how long it runs. +- Acceptance is opt-in; participants who decline are honest. + +The capacity. + +- Recruiting takes real time. A 50-participant closed beta may take 2-4 weeks of recruiting work depending on customer base and selection criteria. +- Plan recruiting time as part of the beta timeline. + +--- + +## The diversity-vs-control tradeoff + +Calibrated cohorts can over-control diversity in ways that miss valuable signal. + +The tradeoff. + +- Tightly-defined selection criteria produce a cohort that is uniform along the criteria. Reduces variety; may miss signal from users who differ. +- Loosely-defined criteria produce more diverse cohorts but make the cohort less calibrated to the GA user. + +The middle path. + +- Define the must-have criteria (role, key segment markers). +- Allow variety in the optional dimensions (industry, geography, tenure). +- The cohort is calibrated on what matters and varied on what does not. + +--- + +## When recruitment fails + +What to do when selection criteria cannot be met. + +Insufficient candidates fitting criteria. + +- Reconsider whether the criteria are too narrow. +- Extend recruiting time if feasible. +- Accept a smaller cohort that fully fits the criteria, rather than a larger cohort that includes mismatches. + +Candidates fitting criteria decline to participate. + +- Investigate why. Is the beta commitment too heavy? The compensation insufficient? The timing wrong? +- Adjust the offer; re-invite. +- If still insufficient, consider whether the beta plan is realistic given customer engagement willingness. + +Cohort skew despite intentional selection. + +- Some dimensions skew despite efforts (e.g., one industry over-represented because that industry is more receptive). +- Acknowledge the skew explicitly in synthesis. Patterns from the over-represented dimension may not generalize. + +--- + +## Common selection failures + +No criteria. Whoever happens to be available joins. Cohort does not represent GA user. + +Self-selection only. Open sign-ups skew the cohort. + +Only champions. Cohort over-represents enthusiasts; misses friction non-champions hit. + +Internal employees only. Misses customer-context complexity. + +Single-dimension calibration. Cohort uniform on one dimension (role) but mismatched on others (usage, segment). + +Recruiting too late. Beta starts before the cohort is calibrated; recruitment continues mid-beta; signal is muddled. + +Enterprise-only. Cohort over-represents large customers; misses smaller use cases. + +--- + +## Methodology-level choices that stay in the public skill + +The criteria for calibrated cohorts. The criteria for miscalibrated cohorts. Variety calibration with worked example. The cohort size question. The recruitment process. The diversity-vs-control tradeoff. When recruitment fails. Common selection failures. + +## Implementation choices that stay internal + +Specific recruiting tools and CRM integration. Specific screening surveys. Specific outreach templates. Specific tracking of cohort composition. The team's own conventions for selection criteria within different beta types. These vary by team and customer base. diff --git a/skills/brand-archetype-system/SKILL.md b/skills/brand-archetype-system/SKILL.md new file mode 100644 index 0000000..feb6c98 --- /dev/null +++ b/skills/brand-archetype-system/SKILL.md @@ -0,0 +1,143 @@ +--- +name: brand-archetype-system +description: "Apply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles." +category: brand +catalog_summary: "12 archetype defaults across 18 verticals: color, type, voice, imagery starters" +display_order: 5 +--- + +# Brand Archetype System + +Pre-composed aesthetic archetype defaults that jumpstart brand design work. Each archetype bundles color tendencies, type pairings, layout patterns, voice samples, and imagery direction for a recognizable aesthetic family. Stack-agnostic. Tool-agnostic. + +This is a starting-point library, not a methodology library. The agent applies archetype defaults to a specific brief; the archetypes themselves provide anchor points, not endpoints. + +--- + +## When to use + +- The user wants a starting point rather than designing from first principles +- The user references a brand or aesthetic family they want to design near +- Need to converge faster from many directions to one +- The user wants vertical-typical defaults (for example fintech consumer, B2B developer tools) +- The user wants to test what a brief would look like in a different archetype + +## When NOT to use + +- The user wants pure methodology guidance (use `brand-identity`) +- The user is in early ideation needing positioning territories (use `brand-ideation`) +- Defining voice for an existing brand (use `brand-voice`) +- Documenting a finished brand (use `brand-style-guide`) + +--- + +## How this composes with other skills + +This skill works upstream of `brand-identity` (provides starting defaults that brand-identity refines into a finished system) and parallel to `creative-direction` (archetypes can be located by position on the 4 creative-direction axes). + +Typical flow when this skill is invoked: +1. User provides a brief or references a target archetype +2. Agent picks the most relevant core archetype, or composes from 2 adjacent archetypes +3. Agent adapts the archetype's defaults to the brief (color tokens shift, type swaps to vertical-appropriate fonts, voice samples rewrite for the brand) +4. Agent flags adaptation choices made + +Direct verbatim copying of an archetype's default palette into a new brand is a failure mode. Archetypes constrain the design space; the brief specifies the point within that space. + +--- + +## The framework: 12 core archetypes plus 18 vertical applications + +Two layers of content in `references/`: + +### Core archetypes (12 files) + +Located in `references/core-archetypes/`. Each is an aesthetic family with: +- Aesthetic summary +- Position on the 4 `creative-direction` axes +- Color palette starter (4 to 6 hex values with token names and rationale) +- Type pairing starter (Google Fonts pairing with size scale) +- Layout and composition patterns +- Voice samples (5 to 10 representative lines) +- Component pattern descriptions (heroes, buttons, cards, tables) +- Imagery direction +- When to pick and when to avoid +- Adaptation guidance +- Exemplar brands with attribution language + +### Vertical applications (18 files) + +Located in `references/by-vertical/`. Each maps named brands to core archetypes in that vertical with: +- Vertical summary +- Common archetypes +- Brand-to-archetype mapping (5 to 10 brands per vertical) +- Vertical-specific adaptation notes +- Common archetype evolution patterns as brands mature + +### Two overview files + +- `00-archetype-system-overview.md`: how the system works, the taxonomy +- `01-how-to-apply-an-archetype.md`: the adaptation discipline, the failure modes + +--- + +## The 12 core archetypes + +\| # \| Archetype \| Single-line summary \| +\|---\|---\|---\| +\| 01 \| Editorial Restrained \| Low-saturation, type-led, generous whitespace, considered \| +\| 02 \| Technical Precise \| Monospace and grid prominent, data-dense, system-feeling \| +\| 03 \| Warm Conversational \| Human imagery, mid-saturation, friendly type, approachable \| +\| 04 \| Bold Confident \| High-contrast, large display type, saturated, direct \| +\| 05 \| Playful Energetic \| Bright colors, illustration-led, dynamic, character-driven \| +\| 06 \| Luxe Considered \| Serif-led, generous spacing, restrained palette, premium \| +\| 07 \| Clinical Trustworthy \| Cool palette, sans-serif, clean medical or financial register \| +\| 08 \| Rugged Utilitarian \| Earth tones, workwear influence, no-nonsense type \| +\| 09 \| Retro Nostalgic \| Period-specific palette and type, intentional vintage reference \| +\| 10 \| Minimal Essentialist \| Black, white, single accent, sans-serif only, sparse \| +\| 11 \| Vibrant Saturated \| High-saturation across full palette, color as character \| +\| 12 \| Documentary Honest \| Photography-led, real people, low-touched imagery \| + +## The 18 vertical applications + +- B2B SaaS: Developer Tools, Business Productivity, Marketing and Sales, Data and Analytics +- Fintech: Consumer, Enterprise +- DTC: Fashion, Beauty, Home and Lifestyle, Food and Beverage +- Consumer Health and Wellness +- Hospitality and Travel +- Media and Publishing +- EdTech +- Gaming and Entertainment +- Marketplace +- Crypto and Web3 +- Real Estate and Proptech + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands. "Editorial Restrained" not "Stripe-like." Brands are referenced as exemplars in description text using attribution language: "exemplified by [brands]", "common among [brands]", "characteristic of [brands]". + +This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## The four creative-direction axes (reference) + +Each archetype positions on the 4 axes defined in the `creative-direction` skill. Brief summary for cross-reference: + +- Tone register: Professional, Conversational, Playful +- Aesthetic register: Restrained, Considered, Expressive, Maximal +- Audience relationship: Authority, Peer, Companion, Performer +- Sensory ambition: Functional, Considered, Immersive, Theatrical + +Each core archetype file specifies its position on each axis. + +--- + +## Reference files + +- [`references/00-archetype-system-overview.md`](references/00-archetype-system-overview.md) - How the two-layer system fits together, entry patterns, when archetypes compose, and the recurring failure modes. +- [`references/01-how-to-apply-an-archetype.md`](references/01-how-to-apply-an-archetype.md) - The 5-step adaptation process: locate the design space, map the brief to adjustable dimensions, adapt color, adapt type, write voice samples. Includes the cross-archetype coherence check. + +The 12 core archetype files live in the `core-archetypes/` subdirectory under references, numbered 01 (Editorial Restrained) through 12 (Documentary Honest). The 18 vertical application files live in the `by-vertical/` subdirectory under references, numbered 01 (B2B SaaS Developer Tools) through 18 (Real Estate and Proptech). Load the relevant core archetype file plus the relevant vertical file together for any brief that names both an aesthetic family and an industry. + diff --git a/skills/brand-archetype-system/references/00-archetype-system-overview.md b/skills/brand-archetype-system/references/00-archetype-system-overview.md new file mode 100644 index 0000000..b47a529 --- /dev/null +++ b/skills/brand-archetype-system/references/00-archetype-system-overview.md @@ -0,0 +1,40 @@ +# Archetype system overview + +This document explains the taxonomy and how the layers fit together. Read this first when working with the archetype system for the first time. + +## The two layers + +Core archetypes (12 files) are the aesthetic families themselves. They span verticals; an archetype like Editorial Restrained appears in B2B SaaS, in media publishing, in DTC fashion. The core archetype files describe the family in pure form: what makes it recognizable, the color tendencies, the type pairings, the voice character. + +Vertical applications (18 files) describe how the archetypes manifest in specific industries with named brands. They are discovery surfaces: a user working on a fintech brand should be able to find their vertical, see which archetypes are common, see specific brand-to-archetype mappings, and decide which core archetype to start from. + +## How the agent should use the system + +Two entry patterns: + +Entry by archetype (user references an aesthetic family): "I want something Editorial Restrained for my analytics product." Agent loads the Editorial Restrained core archetype file, plus the B2B SaaS Data and Analytics vertical file for context. Composes defaults adapted to the brief. + +Entry by vertical (user references their industry): "I'm designing a consumer fintech app, what archetypes work here?" Agent loads the Fintech Consumer vertical file first, sees the brand-to-archetype mappings, picks the most relevant core archetype, then loads that for full defaults. + +## What this system is and is not + +It is: a library of pre-composed defaults that accelerate brand work by providing known-good starting points with documented rationale. + +It is not: a substitute for design judgment. The defaults are anchor points; the brief specifies where to land within the archetype's design space. + +It is not: a comprehensive theory of brand aesthetics. The 12 archetypes capture the most recognizable contemporary Western brand aesthetics. They are not exhaustive. Regional, cultural, and historical archetypes are deferred to future expansions of the catalog. + +## When archetypes compose + +Two archetypes can blend. Linear is Editorial Restrained with Technical Precise undertones. Stripe is Technical Precise with Editorial Restrained surfaces. Glossier is Vibrant Saturated with Minimal Essentialist composition. + +When the brief calls for blending, the agent picks two core archetypes and notes which contributes which dimension (for example "Editorial Restrained for type and whitespace, Technical Precise for color and density"). + +## The failure modes + +1. Verbatim copying: pulling the exact starter palette into a new brand without adaptation. Produces generic output. +2. Archetype mismatch with audience: picking an archetype because the user likes its exemplars rather than because it fits the audience. +3. Cross-archetype tokens: pulling a color from one archetype and type from another without considering coherence. Often produces incoherent output. +4. Stale exemplars: assuming a brand still exemplifies an archetype after a redesign. The archetype is durable; the brand is not. + +Each core archetype file's "Adaptation guidance" section addresses these. diff --git a/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md b/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md new file mode 100644 index 0000000..02c6607 --- /dev/null +++ b/skills/brand-archetype-system/references/01-how-to-apply-an-archetype.md @@ -0,0 +1,69 @@ +# How to apply an archetype + +This document is the operating manual. Once an archetype is picked, follow this process to adapt it to the specific brief. + +## The 5-step adaptation process + +### Step 1: Locate the archetype's design space + +Read the core archetype file. Understand: +- Position on the 4 creative-direction axes +- The non-negotiable structural choices (for example "single accent" for Editorial Restrained, "monospace prominent" for Technical Precise) +- The adjustable dimensions (specific hue of the accent, specific serif, specific density) + +The structural choices are what make the archetype recognizable. The adjustable dimensions are where the brief lands. + +### Step 2: Map the brief to adjustable dimensions + +For each adjustable dimension, ask: what does the brief specify or imply? + +- Audience character: Younger audience usually wants warmer accent; older wants cooler. Technical audience tolerates more density; consumer audience needs more whitespace. +- Category context: Crowded categories need stronger contrast; quiet categories can be more restrained. +- Emotional direction: Trust-needing brands lean cooler; warmth-needing brands lean warmer. +- Competitive position: If the closest competitor is in the same archetype, shift one adjustable dimension hard to differentiate. + +### Step 3: Adapt the color palette + +The starter palette is a relationship between values, not absolute hex codes. Preserve the relationship; shift the values. + +Example with Editorial Restrained: +- Default: ink #0F1B2D (navy), accent #5B8B85 (muted teal) +- Adaptation for a finance brief: ink #1A1F2E (deeper navy), accent #4A5D6E (slate blue), reads more institutional +- Adaptation for a consumer wellness brief: ink #2A2520 (warm dark brown), accent #7A9B7C (sage green), reads more grounded and warm + +Preserve: low saturation, single accent, paper-not-white background, ink-not-black text. Shift: specific hues to match emotional direction. + +### Step 4: Adapt the type pairing + +The starter pairing is a relationship between display and body, not specific fonts. Preserve the relationship; shift the fonts. + +Example with Editorial Restrained: +- Default: IBM Plex Serif (display) plus Inter (body) +- Adaptation for luxe-leaning brief: Tiempos Display (display) plus Inter (body) preserves the pairing, shifts the serif character +- Adaptation for technical-leaning brief: IBM Plex Serif (display) plus IBM Plex Sans (body) keeps within one family, reads more system-like + +Preserve: serif display plus sans body, modular scale, single weight per role. Shift: specific font choices to match register. + +### Step 5: Write voice samples for the specific brand + +The voice samples in the core archetype show character; they are not copy to lift directly. Write 5 to 10 new voice samples for the specific brand using the archetype's cadence and register. + +## The cross-archetype check + +Before finalizing, verify the output reads as coherent within the archetype: + +- Color: matches the archetype's saturation and contrast character? +- Type: matches the archetype's display and body relationship? +- Voice: matches the archetype's cadence and register? +- Layout: matches the archetype's density and whitespace tendency? + +If two of the four diverge from the archetype, either pick a different archetype or accept that the brand is a blend (and document which archetype contributes which dimension). + +## When to abandon an archetype mid-flow + +The archetype is wrong if: +- Three or more dimensions resist adaptation to the brief +- The audience signals reject the archetype's defaults (for example picking Editorial Restrained for a children's app) +- Direct competitors all live in the same archetype and your brief needs differentiation + +When abandoning, return to the vertical file for that industry and pick a different starting archetype. Do not try to retrofit an archetype that does not fit. diff --git a/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md b/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md new file mode 100644 index 0000000..1241203 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/01-b2b-saas-developer-tools.md @@ -0,0 +1,44 @@ +# B2B SaaS: Developer Tools + +## Vertical summary + +Brands serving developers building software. Audience values: technical precision, documentation depth, time-to-first-API-call. Brands compete on developer experience, primitive quality, observability, and composition. The category is mature with established archetypes. + +## Common archetypes in this vertical + +The dominant archetype is Technical Precise (Stripe docs, Sentry, Datadog). Editorial Restrained is the rising adjacent archetype (Linear, Vercel, Resend). Bold Confident appears at the consumer-edge (Loom, formerly Heroku). Other archetypes are rare in this space; warmth and play do not read as credibility to developers building production systems. + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Stripe \| Technical Precise with Editorial undertones \| Best-in-category documentation aesthetic; navy and violet accents; serif display creeping into marketing \| +\| Linear \| Editorial Restrained \| Single-accent restraint; brutal type hierarchy; muted palette \| +\| Vercel \| Editorial Restrained leaning Technical Precise \| Black and white; Geist font system; minimal accents \| +\| Sentry \| Technical Precise \| Dark mode dominant; purple accent; data-dense \| +\| Datadog \| Technical Precise \| Cool palette; UI-led marketing; dense \| +\| Resend \| Editorial Restrained \| New entrant; serif display; warm paper background \| +\| Cloudflare \| Bold Confident \| Orange brand color; energetic; consumer-tilted \| +\| GitHub \| Editorial Restrained adjacent \| Octocat character softens the precision \| +\| Supabase \| Bold Confident leaning Technical Precise \| Green primary; recently more restrained \| +\| Cursor \| Technical Precise \| Dark-mode-first; tool-focused; understated \| + +## Vertical-specific adaptation notes + +- Documentation surfaces are first-class: developer brands need documentation as part of the brand surface, not an afterthought. The type system must scale to long-form technical reading. +- Code samples are brand assets: how code renders (syntax highlighting palette, line numbers, copy buttons) is brand expression. +- Dark mode is required, not optional. Most developers spend their day in dark interfaces. +- Performance signals as brand signals: page load time, animation frame rate, perceived speed are part of how developers judge developer brands. +- Density tolerance: developers tolerate (and often prefer) higher information density than other B2B audiences. + +## Common archetype evolution + +Developer brands frequently start Technical Precise and add Editorial Restrained as they mature. Stripe's evolution from pure technical to editorial-influenced marketing is the canonical example. Conversely, brands that start Bold Confident (Cloudflare, Supabase) sometimes retreat toward restraint as they target enterprise. + +The early-stage developer brand archetype shift is almost always: drop the consumer-tinted color, add a serif, lean into restraint. The mature-stage shift is sometimes: re-introduce a careful illustration system to soften pure restraint (GitHub's Octocat-era is the canonical case). + +## Vertical anti-patterns + +- Playful Energetic in developer tools: reads as unserious. Developers building production systems do not want a mascot taking up screen real estate in their dashboard. +- Luxe Considered in developer tools: reads as out-of-touch. Developer tools differentiate on substance, not premium feel. +- Vibrant Saturated in developer tools: rare and risky; works only when the brand is consumer-tilted (Cloudflare manages it with discipline). diff --git a/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md b/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md new file mode 100644 index 0000000..76f81c5 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/02-b2b-saas-business-productivity.md @@ -0,0 +1,43 @@ +# B2B SaaS: Business Productivity + +## Vertical summary + +Brands serving teams getting work done across documents, projects, communications, and design. Audience is prosumer-tilted: knowledge workers who self-serve, evaluate based on demos and free trials, and bring tools into their organizations from the bottom up. Brands compete on approachability, integration depth, and brand likeability alongside functional differentiation. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Slack, Mailchimp, Figma in marketing) and Bold Confident (Notion, Linear in launches). Playful Energetic appears at the edges (Asana classic era). Editorial Restrained is rising (Coda, Notion's recent surfaces). The category rewards personality more than developer tools but less than consumer apps. + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Notion \| Bold Confident leaning Warm Conversational \| Black on white plus illustration character; emoji-rich; oversized type \| +\| Figma \| Warm Conversational \| Multi-hue creative palette; illustration-led; community-driven \| +\| Loom \| Bold Confident \| Recent rebrand bold-purple-and-black; high contrast \| +\| Slack \| Warm Conversational \| Multi-hue saturated brand colors; hands-and-objects illustration era \| +\| Airtable \| Warm Conversational \| Multi-color brand; spreadsheet-meets-database approachable \| +\| Coda \| Editorial Restrained \| Type-led; restrained palette; document-first feeling \| +\| Asana \| Playful Energetic moving to Warm Conversational \| Mascot-era to recent considered warmth \| +\| ClickUp \| Vibrant Saturated \| Multi-hue palette; expressive; consumer-tilted \| +\| Monday.com \| Vibrant Saturated \| Saturated multi-hue; bold UI; high energy \| +\| Dropbox \| Vibrant Saturated leaning Editorial Restrained \| 2017 rebrand era is the canonical example of the shift \| + +## Vertical-specific adaptation notes + +- Illustration budget matters: brands without illustration capacity should pick Editorial Restrained or Bold Confident rather than Warm Conversational or Playful Energetic. Bad illustration kills the warm archetypes immediately. +- Onboarding surface as brand surface: in productivity, onboarding flows are heavily branded and high-impact. The archetype must extend cleanly into product chrome. +- Self-serve discovery: pricing pages, signup flows, and product tours carry brand weight. Restraint in these surfaces signals trust; warmth signals approachability. +- Bottom-up adoption pattern: brands are evaluated by individual users before procurement. The archetype should not require enterprise sign-off to feel right. + +## Common archetype evolution + +Productivity brands often start Warm Conversational with heavy illustration and pull back toward Editorial Restrained or Bold Confident as they scale into enterprise. Slack's evolution shows this: early Slack was warm-illustration-heavy; current Slack reads more restrained while retaining color personality. Notion's evolution is similar. + +The mature-stage shift is frequently: keep the personality in voice and color, remove decorative illustration from primary surfaces, lean into typographic hierarchy. + +## Vertical anti-patterns + +- Pure Technical Precise in productivity: reads as developer tool rather than productivity tool. Audience expects warmth. +- Luxe Considered in productivity: reads as enterprise theatre. Self-serve audiences read restraint as remote. +- Rugged Utilitarian: completely incompatible with the audience. diff --git a/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md b/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md new file mode 100644 index 0000000..ae51ddf --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/03-b2b-saas-marketing-sales.md @@ -0,0 +1,43 @@ +# B2B SaaS: Marketing and Sales + +## Vertical summary + +Brands serving marketers, sales teams, growth professionals, and revenue operations. Audience is mixed prosumer and enterprise: bottom-up adoption among individual marketers, top-down evaluation by RevOps and procurement. Brands compete on platform breadth, integration ecosystems, attribution claims, and trust signals to budget-holders. + +## Common archetypes in this vertical + +The dominant archetypes split by audience tier. Warm Conversational dominates SMB and prosumer (Mailchimp, Intercom, ConvertKit). Bold Confident appears at the growth-energy edge (Drift, Mutiny). Clinical Trustworthy dominates enterprise (Salesforce, Marketo). Editorial Restrained is the rising adjacent archetype (Webflow's marketing surfaces). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Mailchimp \| Warm Conversational \| Multi-hue brand; mascot-era illustration; SMB-focused \| +\| Webflow \| Editorial Restrained \| Serif-led marketing; typographic hierarchy; designer audience \| +\| HubSpot \| Warm Conversational \| Orange and white; rounded illustration; inbound voice \| +\| Intercom \| Warm Conversational \| Friendly conversational brand; chat-first UX \| +\| Drift \| Bold Confident \| Bold colors; conversational-AI positioning \| +\| Marketo \| Clinical Trustworthy \| Cool palette; enterprise-trust signals; B2B authority \| +\| Salesforce \| Clinical Trustworthy at enterprise edge \| Cloud iconography; trust-blue; enterprise authority \| +\| ConvertKit (Kit) \| Warm Conversational \| Creator-focused warmth; muted palette \| +\| Mutiny \| Bold Confident \| Saturated personalization-as-brand \| +\| Apollo \| Editorial Restrained leaning Bold Confident \| Recent restrained typography redesign \| + +## Vertical-specific adaptation notes + +- Enterprise versus prosumer split is wide: prosumer leans warm and friendly; enterprise leans clinical and authoritative. The brand should pick a lane and commit; trying to do both produces neither. +- Trust signals matter: customer logo strips, peer-reviewed comparison tables, security certifications carry brand weight in this vertical. +- Demo and trial flows: a high portion of brand perception forms during the demo or free trial. The archetype must extend cleanly into in-product surfaces. +- AI-positioning surge: many brands in this category have recent AI-features positioning that affects archetype choice; AI features tend to pull brands toward Technical Precise or Bold Confident. + +## Common archetype evolution + +Marketing and sales brands frequently start Warm Conversational at SMB and evolve toward Clinical Trustworthy or Editorial Restrained as they target upmarket. Mailchimp's evolution from playful-illustration to more restrained type-led marketing reflects this. HubSpot's evolution from friendly orange to a more institutional brand presence is another example. + +The mature-stage shift is frequently: drop heavy illustration, narrow the palette, lean into customer evidence rather than personality. + +## Vertical anti-patterns + +- Playful Energetic in enterprise marketing tools: reads as unserious to budget-holders. +- Luxe Considered in mass-market marketing tools: reads as out-of-touch with the SMB user base. +- Pure Technical Precise: works for some categories (analytics, attribution) but feels wrong for relationship-building tools (CRM, email). diff --git a/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md b/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md new file mode 100644 index 0000000..a1cff84 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/04-b2b-saas-data-analytics.md @@ -0,0 +1,43 @@ +# B2B SaaS: Data and Analytics + +## Vertical summary + +Brands serving data teams, analysts, product managers, and engineers working with data infrastructure, business intelligence, and product analytics. Audience values: query power, schema clarity, time-to-first-insight, and trust in numbers. The category overlaps with developer tools at the infrastructure end and with marketing analytics at the application end. + +## Common archetypes in this vertical + +The dominant archetypes are Technical Precise (Mixpanel, Amplitude, Snowflake) and Editorial Restrained (dbt, Hex, Threshold the fictional reference build). The category rewards precision; Clinical Trustworthy appears at the enterprise BI edge (Tableau historically); Bold Confident appears at the new-entrant edge (Hex at launch). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Mixpanel \| Technical Precise \| Cool palette; product analytics rigor; chart-as-hero \| +\| Amplitude \| Technical Precise \| Blue and white; data-density tolerant; PLG positioning \| +\| Looker \| Technical Precise \| Enterprise BI restraint; Google acquired \| +\| Snowflake \| Editorial Restrained adjacent \| Restrained type; cloud-native confidence \| +\| Tableau \| Clinical Trustworthy historically, Editorial Restrained recently \| Recent rebrand pulled toward typographic restraint \| +\| dbt \| Editorial Restrained \| Type-led; community-driven; restraint as differentiator \| +\| Hex \| Bold Confident \| Saturated brand; modern data workspace positioning \| +\| Census \| Editorial Restrained \| Recent shift toward type-led restraint \| +\| Hightouch \| Bold Confident \| Strong brand colors; reverse ETL positioning \| +\| Threshold (fictional reference) \| Editorial Restrained \| Catalog reference build; PLG onboarding analytics \| + +## Vertical-specific adaptation notes + +- Chart and table rendering as brand: how a chart looks, how table cells align, how numbers format are core brand expression. The archetype must extend cleanly into data visualization conventions. +- Documentation depth: data tools live and die on documentation. Long-form technical reading is core to the brand surface, not auxiliary. +- Trust through precision: vague claims undermine the archetype. Specific numbers, specific schemas, specific examples carry the brand. +- SQL and code as content: query examples, schema definitions, and code samples are first-class brand assets. + +## Common archetype evolution + +Data brands frequently start Technical Precise and add Editorial Restrained as they mature into prosumer territory. Snowflake's evolution from pure technical to restrained editorial is the canonical case. Conversely, brands that start Bold Confident (Hex, Hightouch) often pull back toward restraint as they target enterprise. + +The early-stage shift is usually: keep the technical precision in product surfaces, add editorial restraint to marketing. + +## Vertical anti-patterns + +- Playful Energetic in data tools: reads as untrustworthy with numbers. Audiences expecting analytical rigor reject playful brand expression. +- Luxe Considered in data tools: reads as marketing rather than substance. +- Rugged Utilitarian: completely incompatible with the audience and the category. diff --git a/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md b/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md new file mode 100644 index 0000000..1050614 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/05-fintech-consumer.md @@ -0,0 +1,43 @@ +# Fintech: Consumer + +## Vertical summary + +Brands serving individual consumers across banking, investing, payments, lending, and budgeting. Audience splits sharply by age and risk tolerance: younger audiences tolerate (and prefer) energy and playfulness; older audiences require clinical trust signals. Brands compete on trust, fee transparency, and emotional positioning around money. + +## Common archetypes in this vertical + +The dominant archetypes are Bold Confident (Cash App, Robinhood for younger audiences) and Clinical Trustworthy (Chime, SoFi, Wealthfront for trust-needing positions). Warm Conversational appears at the savings-and-budgeting edge (Acorns). Playful Energetic appears at the consumer-payments edge (Venmo historically). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Cash App \| Bold Confident \| Black plus saturated green; oversized type; consumer-payments register \| +\| Robinhood \| Bold Confident \| Saturated green plus black; recently more institutional \| +\| Chime \| Clinical Trustworthy \| Trust-blue palette; calm voice; banking-not-bank positioning \| +\| SoFi \| Clinical Trustworthy \| Multi-product trust signals; restrained palette \| +\| Venmo \| Playful Energetic historically \| Multi-color personality; payments-as-social positioning \| +\| Wealthfront \| Editorial Restrained \| Type-led; institutional confidence; long-term-investing register \| +\| Acorns \| Warm Conversational \| Warm palette; round-up framing; approachable savings \| +\| Mint \| Clinical Trustworthy historically \| Cool palette; budgeting-trust positioning \| +\| Current \| Bold Confident \| Saturated brand; younger-audience positioning \| +\| Step \| Playful Energetic leaning Bold Confident \| Teen-banking; character-driven \| + +## Vertical-specific adaptation notes + +- Trust versus energy is the central design tension: every consumer fintech brand sits somewhere on this spectrum. Picking the archetype is picking the position. +- Regulatory and compliance copy affects voice. The brand's voice must accommodate disclosures, terms, and risk language without breaking the archetype. +- Money is emotional: the archetype carries emotional positioning about money (excitement, security, freedom, control). The visual must match the emotional position. +- Mobile-first: most consumer fintech brand exposure is on phone screens. The archetype must extend cleanly to small screens with reduced ornamentation. + +## Common archetype evolution + +Consumer fintech brands frequently shift archetype as they target older audiences. Robinhood's evolution from pure bold-energy to more institutional restraint as it added retirement and IRA products is the canonical case. Cash App's evolution into financial-products-beyond-payments shows similar restraint additions. + +The mature-stage shift is usually: keep the brand color, add restraint to type, dial back the swagger in voice, add trust signals. + +## Vertical anti-patterns + +- Luxe Considered in mass-market fintech: reads as out-of-touch. +- Documentary Honest in payments and investing: photography of real people does not communicate the right thing in this category; the value is the product, not the experience. +- Rugged Utilitarian: completely incompatible. diff --git a/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md b/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md new file mode 100644 index 0000000..eb6935b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/06-fintech-enterprise.md @@ -0,0 +1,43 @@ +# Fintech: Enterprise + +## Vertical summary + +Brands serving businesses with payments, treasury, banking, spend management, and financial infrastructure. Audience splits between developer-touching (payment infrastructure) and finance-touching (corporate cards, spend management, treasury). Brands compete on integration depth, control surfaces, and operational trust. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Editorial Restrained with Technical Precise undertones dominates developer-touching fintech (Stripe, Modern Treasury). Bold Confident dominates finance-touching B2B (Ramp, Brex, recent Mercury). Technical Precise dominates pure infrastructure (Plaid). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Stripe \| Editorial Restrained with Technical Precise undertones \| Best-in-category fintech brand; serif marketing, technical product \| +\| Plaid \| Technical Precise \| Developer-first; cool palette; integration-as-product \| +\| Mercury \| Bold Confident, recently shifting to Editorial Restrained \| Recent rebrand pulled back toward restraint \| +\| Brex \| Bold Confident \| Bold colors; corporate-card energy; recent restraint additions \| +\| Ramp \| Bold Confident \| Saturated palette; spend-management-with-energy positioning \| +\| Modern Treasury \| Editorial Restrained \| Type-led; payments-infrastructure restraint \| +\| Adyen \| Editorial Restrained leaning Clinical Trustworthy \| Enterprise-payments authority \| +\| Square (now Block) \| Bold Confident historically \| Black plus accent; SMB-payments register \| +\| Bill.com \| Clinical Trustworthy \| Cool palette; finance-team-tool positioning \| +\| Carta \| Editorial Restrained \| Recent rebrand pulled toward editorial type-led \| + +## Vertical-specific adaptation notes + +- Developer-touching versus finance-touching split: payment infrastructure (Stripe, Plaid) is evaluated by developers; spend management (Ramp, Brex) is evaluated by finance. The archetype must match the evaluator. +- Compliance and trust copy is heavier than in consumer fintech: SOC 2, PCI-DSS, certifications must appear above the fold and be visually weighty. +- Documentation depth: developer-facing fintech needs documentation as primary surface; finance-facing needs reporting and dashboards as primary surface. +- Multi-product expansion: many enterprise fintech brands expand from a single product (payments, cards, banking) into a platform. The archetype must extend to multiple product lines coherently. + +## Common archetype evolution + +Enterprise fintech brands frequently start Bold Confident as challengers and shift toward Editorial Restrained as they target larger customers. Mercury's recent rebrand from bold-pastel to restrained-serif is the canonical example. Carta's recent restraint shift follows the same pattern. + +The mature-stage shift is usually: dial back the saturated color, lean into typographic restraint, add institutional confidence to voice. + +## Vertical anti-patterns + +- Playful Energetic in enterprise fintech: reads as financially unserious. Finance buyers reject playful brand expression even in modern challenger brands. +- Vibrant Saturated: tolerated only when the brand is a category challenger; mature enterprise positions require restraint. +- Documentary Honest: incompatible with the category; product surfaces and dashboards carry the brand, not real photography. diff --git a/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md b/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md new file mode 100644 index 0000000..b98fed8 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/07-dtc-fashion.md @@ -0,0 +1,43 @@ +# DTC: Fashion + +## Vertical summary + +Brands selling apparel directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability or ethical positioning where relevant. The category is dominated by photography quality; brand archetypes ride on photo direction more than on type or color. Price point splits the vertical: above 80 dollars per piece favors Luxe Considered, mass-market favors Minimal Essentialist or Warm Conversational. + +## Common archetypes in this vertical + +The dominant archetypes are Luxe Considered (Aritzia, Reformation, COS at the premium end) and Minimal Essentialist (Everlane, Allbirds at launch, Cuyana). Bold Confident appears at streetwear and challenger brands (Stüssy digital, Kith). Documentary Honest appears in heritage and outdoor-adjacent fashion (Patagonia, Filson). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Aritzia \| Luxe Considered \| Editorial photography; serif type; mid-premium positioning \| +\| Reformation \| Luxe Considered with sustainability voice \| Cream and earthy palette; sustainability framing \| +\| Everlane \| Minimal Essentialist \| Black plus white; transparency narrative \| +\| Allbirds (launch era) \| Minimal Essentialist \| Warm white plus single accent; sustainable-essentials \| +\| Cuyana \| Luxe Considered \| Cream and warm-neutral; fewer-better-things positioning \| +\| Stüssy \| Bold Confident at streetwear edge \| High-contrast; oversized lockup; streetwear authority \| +\| COS \| Minimal Essentialist \| Black on white; architectural typography; H and M premium tier \| +\| Filson \| Documentary Honest with Rugged Utilitarian \| Heritage workwear; earned authenticity \| +\| Outdoor Voices (historical) \| Vibrant Saturated leaning Warm Conversational \| Multi-hue palette; recreation-not-sport positioning \| +\| Universal Standard \| Editorial Restrained \| Size-inclusive premium; serif-led type-first \| + +## Vertical-specific adaptation notes + +- Photography quality is the gating factor: every archetype in this vertical depends on excellent product and lifestyle photography. Brands without photography budget should pick Minimal Essentialist (which can survive on product-on-white) over the other archetypes. +- Model casting is brand expression: who appears in the photography signals the audience the brand is speaking to. Casting decisions are archetype-relevant. +- Sustainability framing is increasingly default in this vertical: the archetype may need to accommodate sustainability narrative without leaning preachy. +- Seasonal updates affect archetype continuity: brands must be able to refresh imagery seasonally without breaking the brand system. + +## Common archetype evolution + +Fashion brands frequently start Minimal Essentialist at launch (low-cost archetype with high signal) and migrate toward Luxe Considered as they raise prices and add product lines. Allbirds' evolution shows this: launch era was pure Minimal Essentialist; recent surfaces lean warmer and more storied (Warm Conversational with Documentary Honest notes). + +Conversely, brands that start Luxe Considered sometimes pull back toward Minimal Essentialist when they target younger or more digitally-native audiences. + +## Vertical anti-patterns + +- Technical Precise in fashion: completely incompatible. +- Playful Energetic in mass-market fashion: reads as costume; works only at children's-or-novelty edge. +- Bold Confident in heritage fashion: undermines the heritage positioning. diff --git a/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md b/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md new file mode 100644 index 0000000..e007077 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/08-dtc-beauty.md @@ -0,0 +1,43 @@ +# DTC: Beauty + +## Vertical summary + +Brands selling skincare, cosmetics, hair care, and personal care directly to consumers. Audience values: ingredient evidence (in clinical positions), aesthetic alignment (in aspirational positions), and category authority (in challenger positions). The vertical splits sharply across three lanes that map cleanly onto archetypes. + +## Common archetypes in this vertical + +Three clear lanes: Vibrant Saturated for personality-driven challenger brands (Glossier, Drunk Elephant); Luxe Considered for premium and aspirational (Aesop, Augustinus Bader); Minimal Essentialist for clinical-and-rational positioning (The Ordinary). Documentary Honest appears at the editorial-skincare edge (Topicals). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Glossier \| Vibrant Saturated with restraint \| Pink-and-white world; soft typography; community-as-brand \| +\| Drunk Elephant \| Vibrant Saturated \| Multi-hue saturated palette; clinical ingredient framing \| +\| Aesop \| Luxe Considered \| Apothecary aesthetic; restrained palette; editorial confidence \| +\| The Ordinary \| Minimal Essentialist \| Black on white; ingredient-as-name; clinical transparency \| +\| Fenty Beauty \| Bold Confident \| Saturated brand; inclusivity-as-positioning \| +\| Topicals \| Vibrant Saturated with editorial photography \| Saturated palette plus documentary photo direction \| +\| Sunday Riley \| Luxe Considered \| Premium clinical; warm palette; ingredient narrative \| +\| Augustinus Bader \| Luxe Considered \| Pure luxury skincare; serif-led; minimal product range \| +\| Tatcha \| Luxe Considered \| Japanese-influenced premium; cream palette; heritage narrative \| +\| Bubble \| Vibrant Saturated leaning Playful Energetic \| Gen-Z skincare; bright multi-hue; accessible price point \| + +## Vertical-specific adaptation notes + +- Three-lane decision is the central archetype choice: Vibrant Saturated (personality), Luxe Considered (premium), Minimal Essentialist (clinical). Commit to one lane; trying to do two reads as confused. +- Ingredient communication: how ingredients are presented carries archetype weight. Clinical lane presents ingredients as data; premium lane treats ingredients as story; personality lane treats ingredients as character. +- Packaging design is integrated with the digital brand: the bottle, jar, or tube on the page is brand expression. Packaging design must match the archetype. +- Photography conventions: clinical lane uses product-on-white; premium lane uses editorial styled photography; personality lane uses saturated lifestyle and product-on-color. + +## Common archetype evolution + +Beauty brands frequently stay within their original archetype but refine over time. Glossier has stayed Vibrant Saturated with increasing restraint as the brand has matured. The Ordinary has stayed Minimal Essentialist with subtle additions for new product lines. Aesop has stayed Luxe Considered with consistent discipline since launch. + +Brands that try to switch archetypes (for example a clinical brand adding personality) usually undermine their original positioning. + +## Vertical anti-patterns + +- Technical Precise in beauty: incompatible; reads as cold and clinical without the trust signals to justify it. +- Rugged Utilitarian: completely incompatible. +- Mixed clinical-and-personality: a brand that tries to be both The Ordinary and Glossier ends up neither. diff --git a/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md b/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md new file mode 100644 index 0000000..5d47154 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/09-dtc-home-lifestyle.md @@ -0,0 +1,43 @@ +# DTC: Home and Lifestyle + +## Vertical summary + +Brands selling bedding, furniture, kitchenware, home accessories, and lifestyle goods directly to consumers. Audience values: aesthetic taste alignment, quality signals, sustainability framing where relevant. The vertical rides on lifestyle photography quality more than any other element; the archetype is downstream of how the brand photographs interiors and objects in use. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Brooklinen, Article, Floyd in marketing) and Luxe Considered (Parachute, West Elm, Pottery Barn premium tier). Minimal Essentialist appears at the design-purist edge (Floyd in product surfaces, Hem). Bold Confident appears at the challenger-mattress edge (Tuft and Needle historically, Casper historically). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Brooklinen \| Warm Conversational \| Friendly bedding brand; mid-saturation palette; clear value framing \| +\| Parachute \| Luxe Considered \| Cream and warm-neutral; aspirational bedding \| +\| Article \| Warm Conversational \| Mid-century furniture; muted palette; design-led \| +\| Floyd \| Minimal Essentialist \| Minimal modular furniture; clean type; restrained palette \| +\| West Elm \| Luxe Considered \| Premium home; serif type; lifestyle photography \| +\| Tuft and Needle (historical) \| Bold Confident historical, Warm Conversational now \| Direct-to-consumer mattress positioning \| +\| Casper (historical) \| Bold Confident historical \| Original sleep-better-everything campaign register \| +\| Hem \| Minimal Essentialist \| Scandinavian-influenced minimal; modular furniture \| +\| Quince \| Minimal Essentialist leaning Luxe Considered \| Premium-quality at accessible pricing; restraint as positioning \| +\| Snowe \| Luxe Considered \| Cream palette; minimal kitchenware aesthetic \| + +## Vertical-specific adaptation notes + +- Lifestyle photography is the foundation: the archetype rides on environmental photography quality. Bad room photography kills any archetype in this vertical. +- Product-in-context dominates: the bedding on a real bed, the chair in a real room. Product-on-white works only for technical specifications, not for hero photography. +- Material and craftsmanship narrative: how the brand discusses what the product is made of carries archetype weight. Luxe Considered uses material story heavily; Warm Conversational uses it lightly. +- Sustainability framing: increasingly default in this vertical; the archetype must accommodate it without leaning preachy. + +## Common archetype evolution + +Home brands frequently start Warm Conversational at launch and pull toward Luxe Considered as they raise prices and add product lines. Parachute's evolution shows this: launch era was more Warm Conversational; current Parachute is firmly Luxe Considered. Brooklinen has stayed Warm Conversational by intentionally holding its accessibility positioning. + +The mature-stage shift is usually: dial back the brand color, lean into typography and photography, drop overt accessibility framing. + +## Vertical anti-patterns + +- Technical Precise in home goods: completely incompatible. +- Vibrant Saturated in home goods: works only at the kids and novelty edge; reads as cheap on premium furniture and bedding. +- Rugged Utilitarian: works only when the brand is genuinely heritage-craftsman (cast iron, woodworking); slips into costume on mainstream home goods. diff --git a/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md b/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md new file mode 100644 index 0000000..1677ab1 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/10-dtc-food-beverage.md @@ -0,0 +1,43 @@ +# DTC: Food and Beverage + +## Vertical summary + +Brands selling beverages, snacks, supplements, and packaged food directly to consumers. Audience values: ingredient transparency, taste promise, and category disruption framing. The vertical is dominated by challenger brands using nostalgic-or-bold positioning to break into commoditized categories (soda, water, snacks, protein, energy drinks). + +## Common archetypes in this vertical + +The dominant archetype right now is Retro Nostalgic (Olipop, Liquid Death, Poppi), differentiating by era pick more than by archetype switch. Bold Confident appears at the energy and functional drink edge (AG1, Athletic Brewing). Minimal Essentialist appears at the clean-label edge (RXBar). Vibrant Saturated appears at the wellness-with-personality edge (Recess). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Olipop \| Retro Nostalgic (70s lean) \| Wellness-soda category creator; 70s wellness palette and type \| +\| Liquid Death \| Retro Nostalgic (80s metal lean) \| Water with metal-band branding; saturated metal aesthetic \| +\| Poppi \| Retro Nostalgic (90s lean) \| Pastel 90s palette; gut-health soda \| +\| AG1 (Athletic Greens) \| Bold Confident \| Black plus saturated green; premium green-powder positioning \| +\| RXBar \| Minimal Essentialist \| Black on white; no-bullshit label as brand identity \| +\| Athletic Brewing \| Bold Confident with retro undertones \| Non-alcoholic beer; heritage type plus modern energy \| +\| Recess \| Retro Nostalgic (70s wellness lean) \| Pastel palette; CBD and adaptogens with chill positioning \| +\| Magic Spoon \| Retro Nostalgic (90s cereal lean) \| Adult cereal with 90s saturated palette \| +\| Olly \| Retro Nostalgic with Playful Energetic notes \| Mass-market vitamins with playful 70s wellness register \| +\| Bare Performance Nutrition \| Bold Confident \| Black plus saturated accent; performance-supplement register \| + +## Vertical-specific adaptation notes + +- Era pick is the differentiation strategy: the F and B challenger category is dominated by Retro Nostalgic right now. Brands differentiate primarily by which era they reference, not by which archetype they pick. +- Packaging design is integrated with digital: the can, bottle, or box on the website is the brand. Packaging design must lead the digital brand expression. +- Ingredient transparency is default: nutrition facts, ingredient lists, and provenance stories must accommodate the archetype. +- Subscription mechanics: many F and B brands are subscription-driven; the archetype must extend cleanly into subscription management and unsubscribe surfaces. + +## Common archetype evolution + +F and B challenger brands frequently start strong in Retro Nostalgic and stay there. The brand identity is the era choice. Brands that try to evolve away from their original era reference usually lose differentiation. + +Mature brands sometimes dial back the era reference as they enter mass distribution: Olipop's recent surfaces are subtler about the 70s reference than its original launch. + +## Vertical anti-patterns + +- Editorial Restrained in F and B: works only at premium spirits and craft chocolate; reads as wrong-category for mass beverage and snack. +- Technical Precise: completely incompatible. +- Generic minimalism: F and B is so saturated with retro-and-bold brands that Minimal Essentialist works only when the brand has a sharp specific reason to be minimal (RXBar's no-bullshit label is the canonical case). diff --git a/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md b/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md new file mode 100644 index 0000000..3a97ae8 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/11-consumer-health-wellness.md @@ -0,0 +1,43 @@ +# Consumer Health and Wellness + +## Vertical summary + +Brands serving consumers across telehealth, mental wellness, fitness, supplements, and self-care. Audience values: trust signals, clinical credibility, and emotional positioning around health. The vertical splits between mental health (which leans warmer and softer) and physical health (which leans clinical and trust-led). + +## Common archetypes in this vertical + +The dominant archetypes split by mental versus physical: Clinical Trustworthy for telehealth and physical-meds (Hims, Ro, Cerebral, Care/of); Warm Conversational and Playful Energetic for mental wellness (Calm, Headspace); Vibrant Saturated at the gen-Z mental health edge (Bumble Health). Editorial Restrained appears at the longevity-clinic edge (Function Health). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Hims \| Clinical Trustworthy with peach warmth \| Mens-health telehealth; warm tone breaks pharmaceutical cold \| +\| Hers \| Clinical Trustworthy with warm accent \| Womens-health telehealth; same brand system, womens lens \| +\| Ro \| Clinical Trustworthy \| Trust-blue palette; multi-condition telehealth \| +\| Care/of \| Clinical Trustworthy with Warm Conversational \| Personalized supplements; warm trust register \| +\| Cerebral \| Clinical Trustworthy \| Mental-health telehealth; restraint signals seriousness \| +\| Calm \| Vibrant Saturated with restraint \| Sleep-and-meditation; gradient-rich; soft palette \| +\| Headspace \| Playful Energetic \| Orange brand; character-illustration-driven; meditation-with-personality \| +\| Talkspace \| Clinical Trustworthy \| Therapy access; cool palette; trust signals \| +\| Function Health \| Editorial Restrained \| Longevity testing; type-led restraint; institutional confidence \| +\| Whoop \| Technical Precise \| Performance health; data-density; athlete positioning \| + +## Vertical-specific adaptation notes + +- Mental versus physical health split: mental health brands lean warmer (Calm, Headspace, Talkspace); physical health brands lean clinical (Hims, Ro). The audience signals differ; the archetype must match. +- Regulatory copy affects voice. FDA disclaimers, medical disclaimers, prescription-required notices must accommodate the archetype. +- Trust through specificity: vague claims undermine the archetype. Specific dosages, specific evidence, specific licensed-clinician credentials carry the brand. +- Subscription-and-cancellation flows: the archetype must extend into ongoing subscription management; brands often lose trust here when the archetype breaks. + +## Common archetype evolution + +Health and wellness brands frequently stay in their original archetype but refine. Hims has stayed Clinical Trustworthy with growing warmth as it expanded categories. Calm has stayed in its restrained-vibrant lane as it expanded from meditation to sleep to broader wellness. + +Mental wellness brands that try to add physical-health products (or vice versa) often struggle to extend the archetype; the brand may need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- Bold Confident in clinical wellness: reads as overpromising. Health categories punish overpromise heavily. +- Rugged Utilitarian: works only in performance-athletic wellness; reads wrong in mainstream health. +- Vibrant Saturated in physical health: works only at younger-audience edges (Bumble Health for college students); reads wrong in mainstream telehealth. diff --git a/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md b/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md new file mode 100644 index 0000000..8b0b68a --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/12-hospitality-travel.md @@ -0,0 +1,43 @@ +# Hospitality and Travel + +## Vertical summary + +Brands across hotels, short-term rentals, travel platforms, and travel-adjacent services. Audience values: trust signals (especially for booking platforms), aesthetic alignment (for hotels and properties), and experiential promise. The vertical is photography-dominated; the archetype rides on photo direction. + +## Common archetypes in this vertical + +The dominant archetypes are Documentary Honest (Airbnb in marketing, Selina, Hostelworld) and Luxe Considered (Aman, Four Seasons, premium hotel collections). Editorial Restrained appears at the hotel-tech edge (Sonder). Minimal Essentialist appears at travel-product brands (Away). Bold Confident at the disruptor edge (Hopper). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Airbnb \| Documentary Honest \| Real-photography of real homes; experiential framing \| +\| Aman \| Luxe Considered (extreme) \| Pure luxury hospitality; serif-led; understated authority \| +\| Four Seasons \| Luxe Considered \| Premium hotel chain; institutional luxury aesthetic \| +\| Selina \| Documentary Honest \| Lifestyle hotels; real-photography; community framing \| +\| Sonder \| Editorial Restrained \| Boutique short-stay; type-led; quiet confidence \| +\| Away \| Minimal Essentialist \| Travel luggage; minimal product photography; restrained type \| +\| Marriott Bonvoy \| Luxe Considered \| Loyalty program brand; aspirational typography \| +\| Hopper \| Bold Confident \| Saturated brand; price-prediction positioning \| +\| Hostelworld \| Playful Energetic \| Backpacker positioning; multi-color; younger-audience \| +\| Tripadvisor \| Warm Conversational \| Trust-through-reviews; friendly approachable register \| + +## Vertical-specific adaptation notes + +- Photography defines the vertical: the archetype is downstream of photo direction. Brands without exceptional photography cannot execute Documentary Honest or Luxe Considered. +- Booking flow versus discovery flow: the brand must extend across both surfaces. Booking flow leans toward trust signals (Clinical Trustworthy notes); discovery flow leans toward aspiration (the chosen archetype). +- Trust signals matter: reviews, ratings, cancellation policies must appear with archetype-appropriate weight. Luxe Considered makes trust signals understated; Documentary Honest puts them alongside imagery. +- Multi-property versus single-property: hotel chains (Marriott, Hilton) face different brand challenges than single-property luxury (Aman individual properties). The archetype must scale. + +## Common archetype evolution + +Hospitality brands frequently stay in their original archetype. Airbnb has stayed Documentary Honest through multiple rebrand iterations. Aman has stayed Luxe Considered since launch. Travel-product brands (Away) have stayed Minimal Essentialist. + +Brands that try to switch archetypes (for example a budget brand trying to feel premium without raising prices) usually fail to land. + +## Vertical anti-patterns + +- Technical Precise in hospitality: completely incompatible. +- Rugged Utilitarian in mainstream hospitality: works only at adventure-travel edges (REI Adventures); reads wrong in city hotels. +- Vibrant Saturated in luxury hospitality: undermines the premium positioning immediately. diff --git a/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md b/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md new file mode 100644 index 0000000..588967b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/13-media-publishing.md @@ -0,0 +1,43 @@ +# Media and Publishing + +## Vertical summary + +Brands across digital publications, newsletters, books, podcasts, and editorial platforms. Audience values: editorial voice, intellectual rigor, and reading experience quality. The vertical is dominated by typography; the archetype rides on type system more than on color or photography. + +## Common archetypes in this vertical + +The dominant archetypes are Editorial Restrained (Substack, The Browser, Bloomberg, NYT Cooking) and Luxe Considered (Stripe Press, premium book design). Minimal Essentialist appears at the classic-publishing edge (Medium in its restrained era). Documentary Honest appears at journalism-as-brand (NYT visual journalism). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Substack \| Editorial Restrained \| Serif-led; cream paper; type-as-product \| +\| Stripe Press \| Luxe Considered \| Premium book design; typography excellence; collector-grade \| +\| The Browser \| Editorial Restrained \| Restrained newsletter; type-led; institutional reading register \| +\| NYT Cooking \| Editorial Restrained \| Recipe-focused; serif typography; brand-trust-through-restraint \| +\| Bloomberg \| Editorial Restrained \| Financial publishing; high-density information; institutional confidence \| +\| The Information \| Editorial Restrained \| Tech business journalism; type-led; subscriber-business model \| +\| Medium (classic) \| Minimal Essentialist \| Original era was pure restrained sans; recent evolution warmer \| +\| The New York Times \| Editorial Restrained \| Canonical example; serif-led; institutional journalism \| +\| Defector \| Editorial Restrained with personality \| Worker-owned sports; restrained with editorial voice \| +\| Lithub \| Editorial Restrained \| Literary publishing; serif throughout; reading-first \| + +## Vertical-specific adaptation notes + +- Type system carries the brand: in media and publishing, the typography is the brand. Most archetype decisions are font-pair decisions. +- Reading experience as primary surface: the article page must lead the brand expression. Marketing surfaces follow the article-reading experience. +- Long-form versus short-form: long-form journalism brands lean Editorial Restrained or Documentary Honest; newsletter and short-form brands have more archetype range. +- Subscription mechanics: paywall surfaces, subscription management, and unsubscribe flows must extend the archetype. Brands often lose archetype coherence at these surfaces. + +## Common archetype evolution + +Media brands frequently stay in their original archetype. Substack has stayed Editorial Restrained since launch. The New York Times has stayed Editorial Restrained for over a century. Bloomberg has stayed Editorial Restrained through multiple redesigns. + +Brands that try to add personality to a restrained archetype (Medium's attempts to feel warmer over time) often produce confusion. The discipline is the brand. + +## Vertical anti-patterns + +- Bold Confident in journalism: undermines credibility; reads as opinion-blog rather than reporting. +- Vibrant Saturated in publishing: works only at children's-publishing and novelty edges. +- Technical Precise in media: works only at niche publications (tech-focused) and reads wrong elsewhere. diff --git a/skills/brand-archetype-system/references/by-vertical/14-edtech.md b/skills/brand-archetype-system/references/by-vertical/14-edtech.md new file mode 100644 index 0000000..7b3d29b --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/14-edtech.md @@ -0,0 +1,43 @@ +# EdTech + +## Vertical summary + +Brands across K-12 learning, higher education, professional development, and consumer learning apps. Audience splits sharply by age and learning context: children's apps lean playful; professional development leans clinical; consumer learning leans warm; technical education leans precise. The vertical rewards personality on the consumer side and authority on the institutional side. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Playful Energetic for K-12 and habit-forming consumer learning (Duolingo, Khan Academy Kids). Warm Conversational for adult consumer learning (Khan Academy, Brilliant). Clinical Trustworthy for professional development (Coursera, edX). Luxe Considered for premium adult education (MasterClass). Technical Precise for technical education (Codecademy, Frontend Masters). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Duolingo \| Playful Energetic (canonical) \| Owl mascot; saturated green; character-driven habit formation \| +\| Khan Academy \| Warm Conversational \| Friendly approachable; muted palette; non-profit mission framing \| +\| Brilliant \| Bold Confident leaning Warm Conversational \| Math-and-science learning; saturated palette; problem-solving register \| +\| MasterClass \| Luxe Considered \| Premium adult education; editorial photography; celebrity-instructor positioning \| +\| Codecademy \| Technical Precise \| Developer education; dark mode; code-first \| +\| Coursera \| Clinical Trustworthy \| Higher-ed-credentialed; cool palette; institutional partnerships \| +\| edX \| Clinical Trustworthy \| University-courses-online; restrained academic register \| +\| Udemy \| Warm Conversational \| Mass-market courses; multi-hue palette; accessible pricing \| +\| Outschool \| Playful Energetic with Warm Conversational \| K-12 small-group learning; warm illustration; family register \| +\| Frontend Masters \| Technical Precise \| Developer-focused; dark mode; instructor-as-authority \| + +## Vertical-specific adaptation notes + +- Audience age determines archetype: K-12 leans playful; teens lean bold; adults lean warm or clinical; technical learners lean precise. Pick the audience first. +- Habit formation versus information transfer: habit-formation products (language apps, daily-skill apps) lean playful. Information-transfer products (course platforms, lectures) lean restrained or clinical. +- Credential signaling: institutional partnerships, certifications, accreditation must appear with archetype-appropriate weight. Clinical Trustworthy makes them prominent; Playful Energetic makes them secondary. +- Progress mechanics: streaks, badges, leveling are core to many edtech products. The archetype must extend into gamification surfaces. + +## Common archetype evolution + +Edtech brands frequently start in their target audience archetype and stay. Duolingo has stayed Playful Energetic since launch (with increasing character development). Coursera has stayed Clinical Trustworthy. MasterClass has stayed Luxe Considered. + +Brands that try to switch (a K-12 brand attempting to add adult learning) usually need to operate two parallel archetypes for two product lines. + +## Vertical anti-patterns + +- Playful Energetic for adult professional development: reads as unserious; adult learners reject playful brand expression for credential-building. +- Clinical Trustworthy for K-12: reads as cold and unfriendly to children and parents. +- Rugged Utilitarian: works only at outdoor-education edge (NOLS, Outward Bound); reads wrong elsewhere. diff --git a/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md b/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md new file mode 100644 index 0000000..86dba90 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/15-gaming-entertainment.md @@ -0,0 +1,43 @@ +# Gaming and Entertainment + +## Vertical summary + +Brands across gaming platforms, streaming services, game studios, and entertainment apps. Audience values: cultural alignment with the gaming or entertainment subculture, content discovery, and community signals. The vertical splits between platform brands (chrome that hosts content) and content brands (the games or shows themselves). Platforms tend toward restraint to let content carry; content brands lean toward expression. + +## Common archetypes in this vertical + +The dominant archetypes are Bold Confident (Epic Games, Riot, Discord) and Vibrant Saturated (Discord with character, Twitch). Editorial Restrained appears at the platform-chrome edge (Steam at category level). Retro Nostalgic appears at indie-gaming and arcade-revival brands. Minimal Essentialist appears at platform-distributor edges (Itch.io). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Discord \| Vibrant Saturated with character \| Multi-hue brand palette; community-focused; playful chrome \| +\| Steam \| Editorial Restrained at category level \| Platform chrome restrained to let games lead; dark mode dominant \| +\| Twitch \| Vibrant Saturated \| Saturated purple; live-streaming positioning \| +\| Epic Games \| Bold Confident \| Strong brand colors; platform energy \| +\| Riot Games \| Bold Confident \| Saturated brand; competitive-gaming positioning \| +\| Itch.io \| Minimal Essentialist \| Indie game platform; minimal chrome; lets games carry \| +\| Spotify (entertainment) \| Vibrant Saturated \| Saturated green; mood-based personalization \| +\| Netflix \| Bold Confident \| Black plus red; content-as-hero; minimal platform chrome \| +\| HBO Max (Max) \| Editorial Restrained leaning Luxe Considered \| Premium streaming positioning; restrained type \| +\| Roblox \| Playful Energetic \| Multi-color brand; family-friendly positioning \| + +## Vertical-specific adaptation notes + +- Platform versus content distinction: platform brands (the place where games or shows live) lean toward restraint to avoid competing with content. Content brands (individual games, shows, studios) lean toward expression. +- Dark mode dominance: most gaming and entertainment surfaces lean dark-mode-first to support content viewing. +- Subculture signaling: gaming brands often signal subculture alignment (esports, indie, MMO, casual mobile). The archetype must extend to subculture-appropriate visual cues. +- Live and real-time experiences: many brands in this vertical have real-time surfaces (live streams, multiplayer lobbies) that affect archetype expression. + +## Common archetype evolution + +Gaming brands frequently choose archetypes orthogonal to their content. Discord is Vibrant Saturated despite hosting communities of every register. Steam is Editorial Restrained despite hosting saturated games. The platform chrome makes a brand decision separate from the content's character. + +Mature platforms sometimes pull back ornamentation to let content lead (Netflix's evolution toward minimalist chrome shows this). + +## Vertical anti-patterns + +- Clinical Trustworthy in gaming: incompatible; gaming audiences reject clinical framing. +- Rugged Utilitarian: works only at simulation-and-mil-sim edges; reads wrong on mainstream gaming. +- Luxe Considered in mass gaming: works only at premium subscription tiers (Max, Apple TV Plus); reads wrong on free-to-play and casual. diff --git a/skills/brand-archetype-system/references/by-vertical/16-marketplace.md b/skills/brand-archetype-system/references/by-vertical/16-marketplace.md new file mode 100644 index 0000000..2148be5 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/16-marketplace.md @@ -0,0 +1,43 @@ +# Marketplace + +## Vertical summary + +Brands operating two-sided platforms connecting buyers and sellers across categories: handmade goods, secondhand, niche-expert, livestream commerce, B2B wholesale. Audience values: trust signals, seller quality verification, and category authority. Marketplace brands face a unique brand challenge: the platform brand interacts with hundreds or thousands of seller brands, and the platform must hold an identity that does not compete with seller identities. + +## Common archetypes in this vertical + +The dominant archetypes are Warm Conversational (Etsy, Faire in marketing) and Bold Confident (StockX, Whatnot). Editorial Restrained appears at the niche-expert edge (Reverb). Vibrant Saturated appears at the gen-Z commerce edge (Depop). Documentary Honest at the artisan-commerce edge (Etsy's seller stories). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Etsy \| Warm Conversational with craft emphasis \| Handmade marketplace; warm palette; seller-story framing \| +\| Reverb \| Editorial Restrained with niche-expert voice \| Musical instruments; type-led; expertise-as-trust \| +\| Faire \| Editorial Restrained \| Wholesale marketplace; restrained type; B2B confidence \| +\| StockX \| Bold Confident \| Sneakers and streetwear; saturated brand; market-data positioning \| +\| Whatnot \| Bold Confident \| Livestream commerce; saturated palette; energy register \| +\| Depop \| Vibrant Saturated \| Gen-Z fashion resale; bright multi-hue palette \| +\| Vinted \| Warm Conversational \| European resale; cream palette; friendly approach \| +\| eBay \| Bold Confident \| Established marketplace; high-energy multi-color brand \| +\| Mercari \| Warm Conversational \| Resale marketplace; soft palette; approachable \| +\| Substack (creator marketplace) \| Editorial Restrained \| Newsletter marketplace; serif type; creator-economy framing \| + +## Vertical-specific adaptation notes + +- Platform brand versus seller brands: the marketplace brand must hold an identity that does not compete with seller brands. Restraint often wins; let sellers carry visual energy. +- Trust signals matter heavily: ratings, reviews, return policies, seller verification carry brand weight. The archetype must give trust signals appropriate space. +- Multi-category challenge: marketplaces frequently span many product categories. The brand must work for fashion, electronics, home goods, and handmade simultaneously. +- Buyer-side versus seller-side surfaces: marketplace brands often have parallel surfaces for buyers (consumer-facing) and sellers (creator-or-merchant facing). The archetype must extend coherently to both. + +## Common archetype evolution + +Marketplace brands frequently start in their original archetype and stay. Etsy has stayed Warm Conversational since its early days (with refinements). StockX has stayed Bold Confident since launch. + +Brands that try to switch archetypes (Etsy's brief attempts at more polished marketing in the late 2010s) usually pull back to their original positioning. + +## Vertical anti-patterns + +- Luxe Considered in mass-market marketplaces: works only at curated-luxury marketplaces (1stDibs, Sotheby's); reads out-of-place elsewhere. +- Technical Precise: works only at B2B infrastructure marketplaces (Faire's developer-tools edge); reads wrong on consumer. +- Clinical Trustworthy: incompatible; reads as cold and corporate where marketplaces need community feeling. diff --git a/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md b/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md new file mode 100644 index 0000000..6a1e674 --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/17-crypto-web3.md @@ -0,0 +1,43 @@ +# Crypto and Web3 + +## Vertical summary + +Brands across crypto exchanges, wallets, NFT platforms, DeFi protocols, and Web3 infrastructure. Audience splits between consumer (Coinbase-tier accessibility) and infrastructure (developer-and-builder-tier precision). The vertical has unusual archetype range because crypto culture spans speculative-energy to cypherpunk-minimal to artist-luxe. + +## Common archetypes in this vertical + +The dominant archetypes split by audience. Bold Confident for consumer crypto (Coinbase, OpenSea, Rainbow). Technical Precise for protocol and infrastructure (Anchor, Alchemy). Editorial Restrained at the writing-and-publishing edge (Mirror). Luxe Considered at the NFT-art edge (Foundation, Async Art). Vibrant Saturated at the consumer-wallet edge (Rainbow). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Coinbase \| Bold Confident with blue \| Trust-blue palette; mainstream-consumer positioning \| +\| OpenSea \| Bold Confident \| Saturated palette; NFT marketplace energy \| +\| Mirror \| Editorial Restrained \| Decentralized publishing; serif-led; restrained confidence \| +\| Foundation \| Luxe Considered \| NFT art marketplace; cream palette; curated-gallery feeling \| +\| Rainbow \| Vibrant Saturated \| Multi-hue wallet brand; gradient-rich; consumer-friendly \| +\| Phantom \| Bold Confident with purple \| Solana wallet; saturated brand; consumer-tilted \| +\| Uniswap \| Bold Confident with Vibrant Saturated \| DeFi protocol; pink-and-saturated brand; consumer-DeFi \| +\| Alchemy \| Technical Precise \| Web3 infrastructure; developer-facing; cool palette \| +\| Polygon \| Bold Confident \| Layer-2 infrastructure; saturated purple; institutional positioning \| +\| Async Art \| Luxe Considered \| Programmable art; restrained gallery aesthetic \| + +## Vertical-specific adaptation notes + +- Consumer versus infrastructure split: consumer brands (Coinbase, Rainbow, Phantom) lean energetic and friendly. Infrastructure brands (Alchemy, Anchor) lean toward Technical Precise. The archetype must match the audience. +- Trust signals matter: regulatory framing, audit reports, security signals must accommodate the archetype. Bold Confident makes them inline; Technical Precise gives them dedicated surfaces. +- Cultural alignment: crypto culture has subcultures (cypherpunk, DeFi-degen, NFT-collector, builder). Brands must signal which subculture they speak to. +- Compliance copy: increasing regulatory pressure (especially post-2024) affects brand voice; the archetype must accommodate disclaimers without breaking. + +## Common archetype evolution + +Crypto brands frequently shift archetype as the regulatory environment matures and as they target broader audiences. Coinbase has moved from more energetic to more institutional over its lifetime. Many crypto brands started Vibrant Saturated (matching crypto culture energy of 2021-2022) and pulled back toward Bold Confident or Editorial Restrained. + +The mature-stage shift is typically: dial back the saturation, add trust signals, lean into typographic restraint without losing the consumer accessibility. + +## Vertical anti-patterns + +- Warm Conversational in crypto: works only at extremely consumer-tilted onboarding products; reads wrong on most surfaces. +- Rugged Utilitarian: incompatible. +- Clinical Trustworthy in pure DeFi: reads as trying to be a bank; works only at the regulated-stablecoin edge. diff --git a/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md b/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md new file mode 100644 index 0000000..d04cc2f --- /dev/null +++ b/skills/brand-archetype-system/references/by-vertical/18-real-estate-proptech.md @@ -0,0 +1,44 @@ +# Real Estate and Proptech + +## Vertical summary + +Brands across residential real estate platforms, premium real estate, proptech tools, and home-buying products. Audience splits sharply by price point: premium residential real estate leans Luxe Considered universally; mass-market platforms split between Warm Conversational, Bold Confident, and Clinical Trustworthy. The vertical rewards trust signals across every archetype because real estate transactions are high-value, high-friction, and infrequent. + +## Common archetypes in this vertical + +The dominant archetypes are Luxe Considered at the premium tier (Compass, Sotheby's International Realty, Pacaso). Bold Confident at the disruptor tier (Opendoor, Sundae). Warm Conversational at the consumer-information tier (Zillow). Clinical Trustworthy at the technology-platform tier (Redfin). Editorial Restrained at the proptech-software edge (some commercial real estate platforms). + +## Brand-to-archetype mapping + +\| Brand \| Archetype \| What's distinctive \| +\|---\|---\|---\| +\| Compass \| Luxe Considered \| Premium residential; serif typography; agent-network positioning \| +\| Zillow \| Warm Conversational at consumer edge \| Friendly approachable; muted palette; consumer-information register \| +\| Redfin \| Clinical Trustworthy \| Cool palette; technology-platform positioning; agent-as-employee model \| +\| Opendoor \| Bold Confident \| Saturated brand; instant-offer disruption framing \| +\| Sundae \| Bold Confident \| Saturated brand; off-market-property positioning \| +\| Pacaso \| Luxe Considered \| Co-ownership of vacation homes; premium photography; lifestyle framing \| +\| Sotheby's International Realty \| Luxe Considered (extreme) \| Pure premium real estate; serif throughout; institutional luxury \| +\| Cadre \| Editorial Restrained \| Commercial real estate investment platform; restrained type \| +\| Knock \| Bold Confident \| Home-trade-in services; saturated brand \| +\| Vacasa \| Warm Conversational with Documentary Honest \| Vacation rental management; real-photography of properties \| + +## Vertical-specific adaptation notes + +- Premium versus mass-market split is sharp: premium real estate is universally Luxe Considered; mass-market splits into three or four archetypes based on positioning. +- Photography is critical: real estate brands depend on excellent property photography. The archetype rides on photo direction. +- Trust signals across every archetype: license info, agent credentials, customer reviews, third-party certifications must appear with appropriate weight. Premium archetypes make these understated; consumer archetypes make them prominent. +- Local versus national: many real estate brands operate hyper-locally (individual agents and small brokerages). The archetype must extend to local agent-branded surfaces. + +## Common archetype evolution + +Real estate brands frequently stay in their original archetype. Compass has stayed Luxe Considered since launch. Zillow has stayed Warm Conversational. Redfin has stayed Clinical Trustworthy. + +Brands that try to switch archetypes (a mass-market brand attempting to feel premium) usually struggle to convince either audience. Real estate is unusually punishing of inauthentic positioning. + +## Vertical anti-patterns + +- Vibrant Saturated in real estate: incompatible; reads as untrustworthy with high-value transactions. +- Playful Energetic: incompatible. +- Rugged Utilitarian: works only at vacation-property and recreational-land edges; reads wrong on mainstream residential. +- Technical Precise: works only at commercial real estate analytics platforms (CoStar tier); reads wrong on consumer. diff --git a/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md b/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md new file mode 100644 index 0000000..0af4a7c --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/01-editorial-restrained.md @@ -0,0 +1,119 @@ +# Editorial Restrained + +## Aesthetic summary + +Low-saturation, type-led, generous whitespace. Considered rather than performed. The brand earns attention through restraint instead of demanding it through volume. Reads as institutional confidence without stiffness. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (warm but precise, comfortable with first person) +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0F1B2D \| Primary text, body, anchors \| +\| ink-muted \| #1F2D44 \| Secondary text \| +\| paper \| #FAF9F6 \| Warm off-white background \| +\| paper-soft \| #F3F1EC \| Card surfaces, subtle elevation \| +\| accent \| #5B8B85 \| Single accent for links and key actions \| +\| accent-muted \| #3F6E55 \| Hover states, secondary accent applications \| +\| highlight \| #C9A227 \| Numeric callouts, display sizes only \| +\| highlight-body \| #8E6E1A \| Same hue at body-text contrast (WCAG AA) \| +\| line \| #EDEFF2 \| Borders, separators \| + +Rationale: +- Ink at #0F1B2D not pure black. Pure black on warm paper feels harsh; navy ink reads as ink-on-paper. +- Paper at #FAF9F6 not pure white. Warm tint signals editorial register versus UI register. +- Accent restricted to one hue. Two-color systems read as institutional; multi-color reads as consumer. +- Highlight restricted to display sizes; the body-contrast variant (#8E6E1A) covers WCAG AA at smaller scales without losing the warm-gold character. + +## Type pairing starter + +- Display: IBM Plex Serif (Google Fonts, free). 700 for hero, 600 for sections. +- Body: Inter (Google Fonts, free). 400 for prose, 500 for UI labels. +- Numerics: JetBrains Mono (Google Fonts, free). 400 to 500 for KPIs and code. + +Size scale (modular, 1.2 ratio anchored at 16px): +- Hero: 56 to 72px serif +- H2: 32 to 40px serif +- H3: 22 to 26px serif +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Mono: 14 to 16px monospace + +Pairing rationale: serif display plus sans body is the classic editorial pairing (NYT, magazines). IBM Plex specifically has open apertures and modest contrast that reads as institutional but modern. JetBrains Mono for numbers communicates precision without being overtly technical. + +## Layout and composition + +- Generous whitespace. Sections separated by 96 to 128px vertical rhythm minimum. +- Single-column hero, content left-aligned, max-width around 720px for prose. +- Asymmetric grids on landing pages: 2-column with deliberate imbalance (40/60 or 60/40) more often than centered or 50/50. +- Density: low. The page should breathe. +- Cards: subtle elevation via 1px line border at line color, no drop shadows. + +## Imagery direction + +- Photography: editorial, low-touched, real environments, natural light. +- Illustration: rare. If used, line-only, single color, technical drawing register. +- Product UI: shown in stylized chrome with branded surfaces; rarely the actual app screenshot. +- Decorative imagery: avoided. Everything earns its place. + +## Voice samples + +- "Built around the question, not against the event stream." +- "Real components, real brand foundations, real working forms." +- "The measurement surface PLG teams actually need." +- "Onboarding metrics live in the cracks between general-purpose tools." +- "Focused, not just smaller." +- "Sample funnel, real benchmarks, your cohort." +- "Pre-built activation funnels. Time-to-first-value benchmarking." + +Cadence: complete sentences. Comma-separated qualifiers more often than dashed asides. Direct claims with built-in qualification. No exclamation marks. Numerals over written numbers. + +## Component pattern descriptions + +Hero: Eyebrow (uppercase, accent color, letterspaced 0.16em), then serif headline 56 to 72px, then sans subhead 18px paragraph, then 2 buttons (primary solid ink, secondary outline), optional KPI strip below. + +Buttons: Primary is solid ink, white text. Secondary is white surface, ink border 1px, ink text. No gradients. No drop shadows. Hover state shifts opacity to 0.9 or fills the secondary surface. + +Cards: Paper-soft background, 1px line border, 24 to 32px internal padding. Numerals top-left in mono. Title in serif. Body in sans. + +Tables: Paper-soft header row, line color separators between rows, monospace numerics aligned right. + +## When to pick this + +- B2B brand for a measured, considered audience (PMs, engineers, founders, finance) +- Category is loud and your differentiation is calm +- Product earns attention through depth rather than novelty +- Audience reads documentation and trusts restraint + +## When to avoid + +- Consumer brand for an audience that wants energy and warmth +- Product that needs to feel inviting at first touch +- Category where competitors are already restrained (you will disappear) +- Brand that needs to communicate playfulness or character + +## Adaptation guidance + +When applying this archetype to a specific brief: + +1. Keep the structure (whitespace, single-accent, restrained type pairing). Adapt specific values. +2. Color: shift accent hue to match emotional direction. Muted teal feels rational; muted plum feels considered; muted moss feels grounded; muted slate feels institutional. +3. Type: IBM Plex Serif is a starting point. Substitutes that fit: GT Sectra, Tiempos, Fraunces, Source Serif. +4. Density: dial up or down based on audience. Developers tolerate more density; founders prefer more whitespace. +5. Highlight color: optional. Brands without a numeric story do not need it. + +Direct copying of all defaults verbatim produces generic Editorial Restrained output. The brief should produce a meaningful variant. + +## Exemplar brands + +Editorial Restrained is exemplified by Linear, Vercel, Stripe Press, Resend, and the fictional Threshold reference build in this catalog. Earlier examples include Pentagram's institutional work and the early Medium publication system. + +These brands share: serif display, sans body, single accent, generous whitespace, editorial photography or stylized product UI, peer-relationship voice. + +The archetype overlaps with Technical Precise (Stripe docs, Sentry); blended brands typically use Editorial Restrained for marketing surfaces and Technical Precise for documentation surfaces. diff --git a/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md b/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md new file mode 100644 index 0000000..8180aea --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/02-technical-precise.md @@ -0,0 +1,122 @@ +# Technical Precise + +## Aesthetic summary + +Monospace prominent in display and numerics. Grid visible in compositions. Data density tolerated and embraced. Dark mode often dominant. Cool palette with high precision feel. The brand communicates that it understands the technical substance of what it is selling, and that its audience does too. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (precise, low-affect, treats the reader as informed) +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Functional + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0A0E1A \| Light-mode primary text \| +\| ink-muted \| #1F2937 \| Light-mode secondary text \| +\| paper \| #FFFFFF \| Light-mode background \| +\| paper-soft \| #F6F8FA \| Light-mode card surface \| +\| surface-dark \| #0F1117 \| Dark-mode primary background \| +\| surface-dark-elevated \| #161922 \| Dark-mode card surface \| +\| text-dark \| #E6E9F2 \| Dark-mode primary text \| +\| text-dark-muted \| #9DA4B4 \| Dark-mode secondary text \| +\| accent \| #7C5CFF \| Saturated single accent (violet shown) \| +\| accent-muted \| #5B3FD6 \| Active state \| +\| signal-success \| #16A34A \| Positive numeric signal \| +\| signal-warn \| #F59E0B \| Caution signal \| +\| signal-error \| #DC2626 \| Error signal \| +\| line \| #2A2F3C \| Dark-mode line, panel separators \| + +Rationale: +- Dark mode is first-class; the palette is built dark-mode primary with light-mode adaptations. +- Single saturated accent (violet, electric blue, lime, or cyan) lets the rest of the palette stay neutral. +- Signal colors are functional, not decorative; reserved for status communication in dashboards and logs. +- Lines visible (#2A2F3C in dark, #E5E7EB in light) to reinforce the grid character. + +## Type pairing starter + +- Display: Geist Sans (Vercel, free) or Inter Display. 600 to 700 weight. +- Body: Geist Sans or Inter. 400 to 500. +- Monospace: Geist Mono or JetBrains Mono. Prominent in display, numerics, code samples, KPIs, badges, and labels. + +Size scale (modular, 1.25 ratio anchored at 15px for higher density): +- Hero: 48 to 64px sans +- Hero-mono: 36 to 48px mono (for technical brands using mono in display) +- H2: 28 to 36px sans +- Body: 15 to 16px sans +- Small: 13px sans +- Code: 14 to 15px mono + +Pairing rationale: Geist (and its mono variant) was designed specifically for technical product interfaces. Inter plus JetBrains Mono is the equivalent if Geist is not available. The mono should appear regularly enough that the reader registers the brand uses it deliberately. + +## Layout and composition + +- Higher density than Editorial Restrained. The reader expects information. +- Grids are visible: hairline borders on cards and tables, monospace coordinates in nav, table-of-contents sidebars. +- Code samples are treated as primary content, not supplementary. +- Hero often pairs a clean headline with a live-looking product surface (dashboard, terminal, code editor). +- Dark mode is the design target; light mode is the adaptation. + +## Imagery direction + +- Photography: rare. When used, abstract or product-context, not people. +- Illustration: technical diagrams, network graphs, architecture maps. Single accent color over neutral background. +- Product UI: shown as real screenshots or near-real chrome. The product surface itself is the brand asset. +- Decorative imagery: minimal. The information density is the visual. + +## Voice samples + +- "Latency p99: 47ms across 12 regions." +- "Idempotent by default. Versioned endpoints. Zero-downtime migrations." +- "Built for the request volume you actually have at 3am." +- "Error budgets, not vibes." +- "Your stack already speaks this protocol." +- "Run it locally. Deploy it globally. Same primitives." +- "Observability that does not require its own observability." + +Cadence: short. Often fragments. Numerals over words. Technical specificity over abstraction. Comfortable with industry vocabulary. + +## Component pattern descriptions + +Hero: Often split layout: left side is headline plus sub plus 2 CTAs, right side is a live product surface (terminal, dashboard, code editor). Or full-bleed dark with an oversized mono headline. + +Buttons: Primary is solid accent on dark, or solid ink on light. Secondary is bordered. Often a small mono prefix on labels ("$ deploy" pattern). + +Cards: Hairline border, dark-elevated background, monospace metadata in the header row, sans body. Often with a small status dot (signal color) in the corner. + +Tables: Dense. Hairline rows. Mono numerics, right-aligned. Hover state with a faint accent tint. Sortable columns marked. + +Code blocks: First-class. Syntax highlighting palette is part of the brand. Copy button. Language label. + +## When to pick this + +- Developer audience +- Observability, platform, infrastructure, or DX product +- Audience values data density and precise specification +- Brand needs to communicate "we built this, we run it, we understand it" + +## When to avoid + +- Consumer audience that wants warmth +- Product that is not technically substantive (the archetype will read as costume) +- Brand needs to communicate approachability over rigor +- Photography or human imagery is central to the brand story + +## Adaptation guidance + +1. Accent hue: violet for product-first brands, electric blue for infrastructure, lime or cyan for AI-adjacent, soft green for sustainability-leaning. +2. Mono density: dial up for developer brands (mono in hero, mono in nav, mono in labels) and dial down for prosumer brands wanting only the precision signal. +3. Dark mode: required. Skip this archetype if the brand cannot ship a dark mode. +4. Photography: if the brand needs human imagery, blend with Editorial Restrained or Warm Conversational instead of forcing it into Technical Precise. +5. Voice density: stay specific. Vague claims in this archetype read as worse than vague claims elsewhere, because the visual is promising specificity. + +## Exemplar brands + +Technical Precise is exemplified by Stripe (especially the documentation and developer surfaces), Sentry, Datadog, Vercel, Cursor, and Linear in its most technical surfaces. Adjacent older examples include the early Heroku CLI and the original GitHub UI before its consumer-tilted redesigns. + +These brands share: dark-mode-first, monospace prominent, code as first-class content, saturated single accent, dense tables and grids, low-affect voice. + +The archetype frequently blends with Editorial Restrained at the marketing surface level (Stripe's marketing pages, Vercel's announcements) while keeping the technical surface pure Technical Precise. diff --git a/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md b/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md new file mode 100644 index 0000000..82530ab --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/03-warm-conversational.md @@ -0,0 +1,114 @@ +# Warm Conversational + +## Aesthetic summary + +Human imagery, mid-saturation palette with warm undertones, approachable type, second-person voice. The brand reads as a colleague who genuinely wants to help rather than a vendor selling. Friendly without performance; honest without coldness. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational +- Aesthetic register: Considered +- Audience relationship: Companion +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1F2937 \| Primary text \| +\| ink-muted \| #4B5563 \| Secondary text \| +\| paper \| #FFFBF5 \| Cream background \| +\| paper-soft \| #FAF3E7 \| Card surface \| +\| accent \| #D97757 \| Warm terracotta primary accent \| +\| accent-soft \| #F3B690 \| Tint of accent for backgrounds \| +\| accent-deep \| #A75440 \| Active state \| +\| support-green \| #5A8A6E \| Sage green secondary \| +\| support-blue \| #5E8FA8 \| Dusty blue secondary \| +\| line \| #E8DFCF \| Borders, separators on cream \| + +Rationale: +- Cream background (not white) is the foundation; it signals warmth before any other element fires. +- Mid-saturation accent (terracotta shown) is warm and human; cooler accents (sage, dusty blue) appear as secondary tones rather than primaries. +- The palette is calibrated mid-saturation throughout; no value is below 35% or above 70% saturation. This is what produces the "considered warmth" reading instead of either pastel or vivid. +- Lines use a warm gray rather than neutral gray to keep coherence with the paper. + +## Type pairing starter + +- Display: Hubot Sans or Söhne or GT America. 600 to 700. +- Body: Same family for body, 400 to 500. Single-family systems read warmer than serif plus sans pairings. +- Optional accent type: a friendly humanist serif (Tiempos Text, Source Serif) for editorial moments inside otherwise sans content. + +Size scale (modular, 1.2 ratio anchored at 17px for comfortable reading): +- Hero: 48 to 64px sans +- H2: 30 to 38px sans +- H3: 22 to 26px sans +- Body: 17 to 19px sans (slightly larger than B2B default) +- Small: 14 to 15px sans + +Pairing rationale: single-family sans systems read warm and consistent. Humanist or geometric-humanist sans (Hubot, Söhne, GT America) have rounder shapes than neo-grotesques like Helvetica, which is what produces the "friendly" reading without sliding into childlike. Body sizes run slightly larger than other archetypes because the reader is expected to actually read. + +## Layout and composition + +- Comfortable density. Not as breathing as Editorial Restrained, not as dense as Technical Precise. +- Sections frequently use full-bleed photography or illustration as scene-setters. +- Hero often pairs a human photo (real customer, real team member) with a friendly headline. +- Generous interior padding inside cards and forms; the page feels welcoming rather than businesslike. +- Curved corners (8 to 16px) on cards and buttons; sharp corners read colder. + +## Imagery direction + +- Photography: real people, varied skin tones and body types, candid rather than posed, natural light, real environments (homes, coffee shops, offices that look lived-in). +- Illustration: custom illustration systems are common (Mailchimp's monkey era, Slack's hands-and-objects era). When used, illustration should have a consistent vocabulary rather than stock-feeling variety. +- Product UI: shown in real photo-context (laptop on a real desk) more often than stylized chrome. +- Stock photography pitfall: this archetype dies on bad stock photo selection. Curate hard or commission custom. + +## Voice samples + +- "Sign up takes about a minute. We will not ask for a credit card." +- "Here is what we tried, what worked, and what did not." +- "You probably do not need a meeting for this. But if you do, we can hop on one." +- "Made for teams who would rather get the work done than configure the tool that does the work." +- "Yes, we send fewer emails than other tools. On purpose." +- "We charge what we charge because that is what it costs to run the thing well." + +Cadence: complete sentences. Comfortable with first and second person. Contractions and hedging are fine; performed informality ("hey friend!") is not. Reads honest, not chummy. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 or 2 CTAs, often paired with a human photo or warm illustration. Background frequently cream (not white). Headline weight is mid-bold (600), not display-heavy. + +Buttons: Primary is solid accent, white text, 10 to 16px corner radius. Secondary is bordered or text-only. Hover states use a slight color deepening rather than opacity shift. + +Cards: Soft cream surfaces, 12 to 16px radius, generous padding (32 to 40px), shadow at low intensity (0 4px 12px rgba(0,0,0,0.04)). + +Forms: Generous field height (48 to 56px). Labels above inputs (not floating). Help text below fields. Pre-fill where possible. + +## When to pick this + +- Prosumer SaaS, team productivity, marketing tools at the consumer-leaning edge +- Brand needs to communicate "we get you" more than "we are best in class" +- Audience values approachability over rigor +- Brand wants to differentiate in a category of cold competitors + +## When to avoid + +- Audience that reads warmth as unserious (most developer infrastructure, most enterprise) +- Brand with limited photography or illustration budget (the archetype dies on bad imagery) +- Brand needs to communicate authority or expertise as the primary signal +- Category is already crowded with warm brands (you will disappear) + +## Adaptation guidance + +1. Accent hue: terracotta and warm orange feel grounded; sage green and dusty blue feel calm; coral and peach feel optimistic. Pick one primary based on emotional direction. +2. Single-family vs paired type: single-family sans is the default. If the brand needs editorial moments, add a humanist serif as the accent type, not as the body. +3. Illustration vs photography: pick one as primary. Brands trying to do both usually do neither well. +4. Voice: write honest first, friendly second. Performed friendliness without honest substance reads cheap. +5. Density: avoid over-roominess. The archetype tips into "marketing fluff" when the page is too breathing and the content is too thin. + +## Exemplar brands + +Warm Conversational is exemplified by Mailchimp (especially the illustration-driven era), Webflow, Slack, Notion in its marketing surfaces, Loom, Intercom, and Figma. Adjacent examples include Khan Academy and Mailchimp's earlier mascot work. + +These brands share: cream or warm-white surfaces, single-family sans, mid-saturation warm accent, human or custom-illustration imagery, second-person voice, comfortable density. + +The archetype frequently overlaps with Playful Energetic when the illustration system carries character; the difference is that Warm Conversational keeps the illustration in service of communication, while Playful Energetic lets the illustration become the dominant visual. diff --git a/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md b/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md new file mode 100644 index 0000000..f1710a6 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/04-bold-confident.md @@ -0,0 +1,115 @@ +# Bold Confident + +## Aesthetic summary + +High-contrast color (often black plus one saturated accent). Oversized display type used as design element. Direct copy. Strong horizontal grids. The brand walks into the room and says what it is selling without flinching. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (direct, comfortable with first person) +- Aesthetic register: Expressive +- Audience relationship: Performer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0A0A0A \| Near-black primary \| +\| paper \| #FFFFFF \| White surface \| +\| paper-soft \| #F2F2F2 \| Tinted surface \| +\| accent \| #FF4D2E \| Saturated single accent (vibrant orange shown) \| +\| accent-deep \| #C13A20 \| Active state \| +\| support \| #18181B \| Off-black for layered surfaces \| +\| line \| #1F1F1F \| Heavy line color (matches the bold register) \| + +Alternative accent picks that fit this archetype (one only): +- Hot pink: #EC2877 +- Lime: #C7F11D +- Electric blue: #2563EB +- Saturated yellow: #FFD400 (use with extreme contrast) + +Rationale: +- Two-tone is the move: high-contrast black-and-white plus one saturated accent. Three or more colors dilute the boldness. +- Pure black (or near-black) and pure white reinforce the contrast register. Off-blacks or warm whites pull the archetype toward Editorial Restrained. +- The accent is loud enough that it has to be deployed sparingly. Used as background for one section, not as button color everywhere. + +## Type pairing starter + +- Display: Druk Wide, Söhne Breit, GT Sectra Display, Helvetica Now Display, or PP Editorial New (when leaning expressive editorial). Heavy weight (800 to 900) on display. +- Body: Söhne, Inter, or Helvetica Now. Mid-weight (500). + +Size scale (extreme contrast between hero and body): +- Hero: 80 to 140px display (the headline is the hero) +- H2: 48 to 72px display +- H3: 28 to 36px +- Body: 17 to 19px +- Small: 14 to 15px + +Pairing rationale: the archetype is built around extreme type contrast. Hero type runs huge (often 100px or more on desktop); body type is normal. The size ratio itself is the visual signature. Heavy display weights are non-negotiable; light or regular weights produce a different archetype entirely. + +## Layout and composition + +- Horizontal grids dominate. Heroes often full-bleed with the headline as the design element. +- Asymmetric layouts with intentional imbalance: text aligned hard-left, oversized headlines that extend past container edges. +- High contrast section transitions: black section, then white section, then accent section. The page reads as panels. +- Sharp corners more often than rounded. +- Minimal decorative imagery; the type IS the visual. + +## Imagery direction + +- Photography: high-contrast, often desaturated or single-color-tinted, real but stylized. +- Illustration: bold flat illustration when used, single accent color, no gradients. +- Product UI: shown in oversized chrome that mirrors the brand's contrast register. +- Decorative: type-as-image; the headline often becomes the visual. + +## Voice samples + +- "We do not negotiate with hidden fees." +- "Built for the people doing the actual work." +- "This is the version that works. The free trial is the version that works." +- "No setup call. No demo. Just sign up." +- "We charge once. You own the thing." +- "Our competitor's pricing page has a button to talk to sales. Ours has a price." + +Cadence: short sentences. Declarative. Contrasts and oppositions ("not X, just Y"). Comfortable with confrontation. Avoids hedging. + +## Component pattern descriptions + +Hero: Oversized headline as the dominant element (80 to 140px). Sub headline below at standard size. 1 to 2 buttons. Often a single bold visual or a horizontal divider in the accent color. + +Buttons: Primary is solid ink or accent on white. Often oversized (56 to 72px height) to match the bold register. Square or low-radius corners (0 to 4px). + +Cards: Sharp corners, heavy border (2 to 3px) or strong shadow, large internal padding. Often the card itself uses contrast (black card with white text, or accent card with black text). + +Tables: Heavy header (black background, white text). Large row height. Bold numerics. + +## When to pick this + +- Launch moments or rebrand moments where the brand needs to reset attention +- Category is full of timid competitors and your brief needs differentiation through volume +- Product confidence is high and the value prop is sharp +- Brand is comfortable being polarizing + +## When to avoid + +- Brand needs to communicate care, gentleness, or expertise-through-restraint +- Audience reads boldness as bro-culture or as insecurity +- Product value is technical and needs space to explain itself +- Brand will be embarrassed by the visual in 18 months (this archetype dates faster than restrained ones) + +## Adaptation guidance + +1. Accent pick: hot pink leans consumer, lime leans tech-edgy, electric blue leans fintech, orange leans general-purpose bold, yellow only with extreme contrast discipline. +2. Display size: do not pull this back to "reasonable." If the hero is 56px, you have made an Editorial Restrained brand instead. Commit to 100px+ or pick a different archetype. +3. Voice: easy to slip into bro-culture. Pull back the swagger by writing honest, not performed. The visual is bold; the voice is direct, not bombastic. +4. Image strategy: pick type-as-visual or one strong photo. Mixed imagery dilutes the impact. +5. Use the contrast: panel-by-panel section transitions are core. A single-color page is not Bold Confident. + +## Exemplar brands + +Bold Confident is exemplified by Loom (current era), Cash App, Robinhood, Mercury (in its recent rebrand), Notion (in product launches), Linear (in major launches), Cloudflare (consumer edge), and Brex. Adjacent older examples include the original Squarespace launch era and the original Mailchimp redesign. + +These brands share: high-contrast palette, oversized display type as visual element, direct voice, panel-based section transitions, one strong accent. + +The archetype often pairs with Technical Precise on developer-tilted brands (the marketing page is Bold Confident; the product surface is Technical Precise). It also overlaps with Vibrant Saturated when the accent is the brand color rather than a supporting note. diff --git a/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md b/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md new file mode 100644 index 0000000..3accaa3 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/05-playful-energetic.md @@ -0,0 +1,114 @@ +# Playful Energetic + +## Aesthetic summary + +Bright multi-color palette. Illustration-led, frequently character-driven. Dynamic, sometimes literally animated. Chunky display type or rounded sans. The brand has a personality, often a recurring character or mascot, and that personality is the primary asset. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Companion +- Sensory ambition: Immersive + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1B1B2A \| Soft-black text \| +\| paper \| #FFFDF7 \| Cream surface \| +\| paper-soft \| #FFF4D6 \| Pastel surface tint \| +\| accent-primary \| #58CC02 \| High-saturation primary (Duolingo green shown) \| +\| accent-secondary \| #FF4B4B \| Bright contrast accent \| +\| accent-tertiary \| #FFC800 \| Sunny yellow \| +\| accent-quaternary \| #1CB0F6 \| Bright sky blue \| +\| accent-quinary \| #CE82FF \| Bright purple \| + +Rationale: +- Multi-hue palette is the signature. Single-accent palettes do not produce Playful Energetic. +- High saturation (often above 80%) across the full palette. Pastel-only is a different archetype (Vibrant Saturated pulled toward soft). +- The palette is calibrated so any two colors can sit next to each other without clashing. This is harder than it looks and requires hue and value discipline. +- Soft black for text (not pure black) keeps the warmth of the palette intact. + +## Type pairing starter + +- Display: Recoleta, Sofia Pro Black, Pangaia, or a chunky humanist serif. Heavy weight, rounded shapes. +- Body: Nunito, Inter, or a rounded humanist sans. 500 to 600. +- Character lettering: Many brands in this archetype use custom wordmark lettering for the brand name itself (Duolingo, Mailchimp, Headspace). The custom mark sits outside the type system. + +Size scale (energetic, with playful proportions): +- Hero: 56 to 80px display (heavy weight) +- H2: 32 to 44px display +- H3: 22 to 28px +- Body: 17 to 19px sans (rounded) +- Small: 14 to 15px + +Pairing rationale: rounded shapes communicate friendliness. Heavy weights communicate playfulness over preciousness. The pairing is "chunky and round" rather than "tall and narrow." + +## Layout and composition + +- Generous use of decorative elements (mascot illustrations, sparkles, shapes, patterns). +- Asymmetric layouts; intentional cheerful imbalance. +- Diagonal motion lines, jaunty rotations on key elements (cards rotated 2 to 4 degrees), bouncy interactions on hover. +- Heavy use of card-based sections with playful borders (heavy, often colored borders rather than hairlines). +- Rounded corners are aggressive (16 to 24px); sharp corners feel wrong in this archetype. + +## Imagery direction + +- Illustration: custom illustration system is the brand's primary visual asset. Often character-driven (mascot has a personality and shows up across surfaces). +- Animation: motion design is core. The mascot moves; cards bounce on hover; loading states have personality. +- Photography: rare. When used, candid and bright, never sterile. +- Stock imagery: forbidden. The archetype requires custom illustration capacity. + +## Voice samples + +- "Hi! It is time for your daily lesson." +- "You did the thing. We are very proud." +- "Skip a day, and the streak ends. We are watching." +- "Two minutes today is better than zero minutes today." +- "Surprise! You earned a badge." +- "Your friend just passed you. Are you going to let that stand?" + +Cadence: short, punchy. First and second person. Comfortable with exclamation marks (but not abuse). Frequent direct address. Humor as a primary tool. Occasional knowing winks at the reader. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 CTA, paired with a large illustration or animated mascot. The illustration is roughly equal weight to the headline rather than supplementary. + +Buttons: Heavily rounded (12 to 20px radius). Often with a 2 to 4px solid bottom border in a darker shade (the "neumorphic toy button" pattern). Bouncy hover animations. + +Cards: 16 to 24px radius, soft drop shadows, often slightly rotated. Sometimes with character illustrations integrated into the card itself. + +Forms: Inputs are oversized, friendly, with playful focus states. Validation errors are gentle ("Hmm, that does not look right" rather than "Invalid input"). + +Loading states: have personality. The mascot waves, bounces, makes a face. Default spinners are missed opportunities in this archetype. + +## When to pick this + +- Consumer apps targeting habit formation, learning, or wellness +- B2B brands intentionally breaking category convention with humor +- Audience appreciates personality over precision +- Brand has illustration budget and willingness to build a character system + +## When to avoid + +- Brand has no illustration budget (this archetype dies on poor illustration) +- Audience reads playfulness as unserious (most enterprise, most developer tools) +- Brand is selling to risk-averse buyers (finance, health, B2B procurement) +- Brand is in a category where competitors are already playful (you will not differentiate) + +## Adaptation guidance + +1. Character commitment: decide early whether the brand has a mascot. Mascot brands need ongoing illustration. Mascot-less playful brands rely on pattern and color systems. +2. Palette discipline: defining 4 to 6 saturated hues that compose together is the hardest part. Spend real time here; the rest of the archetype is downstream. +3. Motion: the archetype needs motion to feel right in product. Static-only execution reads as toy-without-charm. +4. Voice: write to one specific reader, not "users." The archetype falls apart when the voice tries to be funny without commitment. +5. Restraint: even Playful Energetic needs editorial moments. Pages that are 100% playful all the way through exhaust the reader. + +## Exemplar brands + +Playful Energetic is exemplified by Duolingo (the canonical example, with a full character system), Mailchimp in its monkey-mascot era, Headspace, Asana classic era, Liquid Death (visual side), Ben and Jerry's, and MoonPay. Adjacent examples include the Trello mascot era and the original Slackbot personality. + +These brands share: multi-hue saturated palette, custom illustration as primary asset, second-person voice with personality, heavy use of motion, rounded everything. + +The archetype overlaps with Warm Conversational when the illustration is friendly but not character-driven; the difference is that Playful Energetic lets the personality become the brand, while Warm Conversational keeps the human relationship in the foreground. diff --git a/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md b/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md new file mode 100644 index 0000000..d97188b --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/06-luxe-considered.md @@ -0,0 +1,112 @@ +# Luxe Considered + +## Aesthetic summary + +Serif-led across display and body. Extreme whitespace. Restrained monochromatic palette plus one premium accent. Photography is editorial-grade. Voice is sparse and confident. The brand communicates premium not by saying premium but by behaving premium: in pacing, in spacing, in what it omits. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (formal but not stiff) +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Theatrical + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1A1614 \| Warm near-black \| +\| ink-soft \| #3A332E \| Secondary text \| +\| paper \| #F5F1EA \| Cream off-white background \| +\| paper-warm \| #EDE6D9 \| Warmer cream surface \| +\| accent \| #5C2A26 \| Deep oxblood (alternative: forest #2D4A38, charcoal navy #1F2A40, champagne #C3A87C) \| +\| accent-soft \| #8B4843 \| Active states \| +\| line \| #D9D0BC \| Warm beige border \| + +Rationale: +- Cream and warm-neutral palette is the foundation. Pure white feels cheap in this archetype; cool grays feel corporate. Warmth is the premium signal. +- Single deep accent (oxblood, forest, navy, champagne, deep emerald). Saturation is restrained; the depth of value carries the premium feel. +- No bright colors. Even subtle saturation reads as cheap in this archetype. +- Line color matches paper-warm; lines should be visible but not strong. + +## Type pairing starter + +- Display: Tiempos Headline, GT Super, Reckless, Reforma, or Saol Display. Light to regular weight (300 to 400). +- Body: Tiempos Text, GT Super Text, or Source Serif. Light weight (300 to 400) at comfortable reading size. +- Optional sans: Söhne or GT America at low weight (300) for UI labels and metadata only. + +Size scale (editorial proportions, smaller hero than Bold Confident, larger body than Technical Precise): +- Hero: 48 to 64px serif (light weight) +- H2: 32 to 42px serif +- H3: 22 to 26px serif +- Body: 18 to 20px serif (light weight, comfortable line height) +- Small: 14 to 15px sans + +Pairing rationale: editorial serifs throughout produce the "magazine" feeling. Light weights communicate confidence without aggression. The pairing is rare in B2B (which mostly uses serif display plus sans body) and that rarity is part of the premium signal. + +## Layout and composition + +- Extreme whitespace. Sections separated by 144 to 200px vertical rhythm. +- Often centered or left-aligned with massive horizontal margins on desktop (max content width can run 580 to 720px even on wide screens). +- Asymmetric compositions where the imbalance is intentional and editorial (a 70/30 split with text against a single dominant photograph). +- Minimal UI chrome. Buttons are often text-only with underlines, or thin-bordered, or absent entirely (the call to action is a single line of body copy with a link). +- Page transitions are slow and deliberate. Animations cross-fade rather than slide. + +## Imagery direction + +- Photography: editorial-grade, professionally lit, deliberately styled. Natural light is fine but composition is intentional. Real product, real environment, but elevated. +- Photography is large. Hero images are full-bleed or near-it. The image carries the page. +- Illustration: rare. When used, line-only, sometimes hand-drawn or engraved-feeling. +- Decorative imagery: none. The composition is the visual. +- This archetype requires real photography or excellent stock curation. Bad photo direction kills it instantly. + +## Voice samples + +- "Made from cashmere. From goats that live in places we visit." +- "One garment, one decision." +- "We do not chase trends. We do not need to." +- "Built in 1923. Refined since." +- "If it is not in this collection, it is because it was not ready." +- "The thing we changed was the thread." + +Cadence: short, often fragments. First-person plural ("we") more often than first-person singular. Comfortable with silence. Avoids superlatives ("the best," "the most"); the visual communicates premium without verbal claim. Numbers used sparingly, with deliberate weight when they appear. + +## Component pattern descriptions + +Hero: Single full-bleed photograph or a small serif headline against generous whitespace. No subhead. No CTAs in the visible hero region; the page expects the reader to scroll. + +Buttons: Often text-only with a serif underline, or thin-bordered with serif label. Solid buttons exist but are rare and reserved for primary purchase moments. Padding is generous (16 to 20px vertical). + +Cards: Often no card chrome at all; product is shown on a tinted surface with serif type alongside. When cards exist, they are bordered (1px line color) rather than shadowed, with sharp or low-radius corners (0 to 4px). + +Navigation: Minimal. Often horizontally centered with wide letter spacing. Logo small. The brand does not announce itself loudly. + +## When to pick this + +- Luxury or premium-priced products (above 50 dollars consumer, premium-tier B2B) +- Hospitality, fashion, beauty at price points where the visual must signal value +- Audience explicitly buys premium and is reassured by understated execution +- Brand has the production budget for premium photography + +## When to avoid + +- Brand is competing on price or accessibility +- Audience reads restraint as unfriendly +- Brand has no photography budget (the archetype dies immediately) +- Product is not actually premium (the visual will read as costume) + +## Adaptation guidance + +1. Accent depth: oxblood reads heritage, forest reads sustainability, deep navy reads institutional, champagne reads contemporary luxury. Pick based on brand position. +2. Photography commitment: this is a photography archetype before it is a type archetype. Lock photography direction first. +3. Type weight discipline: light weights (300 to 400) only. Bold serif display pulls the archetype toward Bold Confident. +4. CTA restraint: resist adding obvious buy buttons in hero positions. The archetype expects the reader to discover, not be sold to. +5. Sans usage: keep sans confined to UI labels and metadata. Sans body copy breaks the archetype. + +## Exemplar brands + +Luxe Considered is exemplified by Aesop, Aritzia, Reformation, La Marzocco, Loro Piana, Aman, Bottega Veneta digital, and Stripe Press (in the book design surface). Adjacent examples include the Apple mid-2010s premium product pages, Squarespace's recent rebrands, and the original Goop. + +These brands share: cream and neutral palette, serif-throughout type system, generous whitespace, editorial photography, sparse voice, premium pricing. + +The archetype overlaps with Editorial Restrained (which is the B2B-tilted cousin) and Minimal Essentialist (which strips out the serif entirely). The key difference: Luxe Considered uses the serif and warmth to signal premium; Minimal Essentialist uses absence of ornament to signal premium; Editorial Restrained uses considered ornament to signal trust. diff --git a/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md b/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md new file mode 100644 index 0000000..c3bac14 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/07-clinical-trustworthy.md @@ -0,0 +1,115 @@ +# Clinical Trustworthy + +## Aesthetic summary + +Cool palette (blue, teal, soft greens) with optional warm accent for humanity. Sans-serif throughout. Clean compositions. Medical or financial register. Photography of products and clinical environments, occasionally real hands and real people in calm contexts. The brand communicates "trust us with something important" without sliding into cold or pharmaceutical. + +## Position on the 4 creative-direction axes + +- Tone register: Professional (calm, knowledgeable, low-affect) +- Aesthetic register: Considered +- Audience relationship: Authority +- Sensory ambition: Functional + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0F2540 \| Deep navy primary \| +\| ink-soft \| #344C68 \| Secondary text \| +\| paper \| #FFFFFF \| White surface \| +\| paper-soft \| #F4F8FB \| Cool tinted surface \| +\| accent-primary \| #2D7FB8 \| Trust blue \| +\| accent-secondary \| #4CA8A0 \| Soft teal \| +\| warm-tone \| #F4B69B \| Optional peach warm accent for humanity \| +\| signal-success \| #2F8F5F \| Calm success green \| +\| line \| #DAE3EC \| Cool gray border \| + +Rationale: +- Cool palette communicates calm authority. Blues and teals are the trust signals; warm tones are optional humanizers, not primary brand colors. +- Trust blue (#2D7FB8) is calibrated to read confident without sliding into corporate cold. Bluer (toward #1976D2) reads more pharmaceutical; teal-shifted reads more wellness. +- The optional warm accent (peach, soft coral) is the single move that distinguishes contemporary Clinical Trustworthy from sterile pharma aesthetic. Without it, the brand reads dated. +- White surfaces. Off-whites and creams pull the archetype toward warmth and away from clinical. + +## Type pairing starter + +- Display: Avenir Next, Circular, Söhne, or GT America. 500 to 700 weight. +- Body: Same family, 400 to 500. Or paired with a soft humanist body (Inter, Source Sans). +- Optional accent serif: A clean serif (Source Serif, Tiempos Text) used sparingly for editorial moments or testimonials. + +Size scale (calm, generous, accessible): +- Hero: 48 to 60px sans +- H2: 30 to 38px sans +- H3: 22 to 24px sans +- Body: 17 to 19px sans (accessible default; this archetype frequently serves older audiences) +- Small: 14 to 15px + +Pairing rationale: geometric sans-serif communicates clinical without medical-sterile. Circular and Avenir specifically have open shapes that read calm rather than clinical. Body sizes run slightly larger because the audience may include older readers and the brand should not require strain. + +## Layout and composition + +- Comfortable density; not as dense as Technical Precise, not as breathing as Luxe Considered. +- Generous internal padding inside cards and forms. Trust is communicated partly through "we are not hurrying you." +- Hero often pairs a clean headline with a calm photograph (a real hand holding a product, a calm clinical environment, a portrait of a doctor or pharmacist). +- Comfortable line lengths (60 to 80 characters per line) and generous line height (1.6 to 1.8). +- Soft drop shadows on cards (gentle elevation, not floating). Rounded corners at moderate radius (8 to 12px). + +## Imagery direction + +- Photography: real hands, real products in real environments. Calm lighting (often natural). Real people who look like the audience. +- Product packaging: shown clearly, frequently against soft tinted backgrounds. +- Illustration: rare; when used, technical diagrams of how something works (a calm anatomical illustration, a process flow with annotations). +- Avoid: aggressive close-ups of medical procedures, stock photos of clinicians in lab coats with crossed arms, hands-only-on-keyboard generic stock. + +## Voice samples + +- "Reviewed by licensed clinicians." +- "Effective ingredients at evidence-backed doses." +- "Same medication. Less hassle." +- "Your doctor will see this report. So will you." +- "We do not bill you for what we do not provide." +- "If it is not safe for you, we will tell you." + +Cadence: complete sentences. Comfortable with first and second person. Calm, qualified, specific. Numbers used carefully (specific doses, specific time-to-response). Avoids superlatives. Compliance-aware writing without being legal-coded. + +## Component pattern descriptions + +Hero: Headline plus subhead plus 1 to 2 CTAs, paired with a calm photograph. Trust signals (clinician endorsements, FDA mentions, peer-reviewed citations) appear above the fold but understated. + +Buttons: Primary is solid trust-blue or solid ink-navy, white text, 8 to 12px corner radius. Secondary is bordered. Hover states use a slight darkening rather than opacity shift. + +Cards: White or paper-soft surface, 8 to 12px radius, gentle shadow (0 2px 8px rgba(15,37,64,0.06)). Generous internal padding (32 to 40px). Trust signals (clinician credentials, certification marks) frequently appear in cards. + +Forms: Generous field height (48 to 56px). Labels above inputs. Help text below explaining why each piece of information is needed (trust signal: we explain why we ask). + +Trust strip: Common pattern. Logo strip of certifications, regulatory bodies, peer-reviewed citations, or major employers using the product. + +## When to pick this + +- Telehealth, digital health platforms +- Fintech, especially at the trust-needing edge (banking, insurance, investments for older audiences) +- Insurance, retirement, anything where the conversion driver is "trust us with this" +- Health-finance intersection (HSA, healthcare benefits, prescription savings) + +## When to avoid + +- Audience is young and reads clinical as boring or institutional +- Brand needs to communicate energy or excitement +- Category is already dominated by clinical-trustworthy brands (you will disappear) +- Product is not actually substantive enough to support the trust register (the visual will read as costume) + +## Adaptation guidance + +1. Cool to warm balance: pure clinical cool reads pharmaceutical. The optional warm accent (peach, soft coral, butter yellow) is what distinguishes contemporary from dated. +2. Photography: real hands and real environments are the move. Stock photos of "doctor with arms crossed" date the brand immediately. +3. Voice density: write specific. Vague claims in a clinical archetype read as worse than vague claims in a playful one, because the visual is promising specificity. +4. Trust signals: dedicate space to credentials, certifications, citations. Hide them and the archetype is half-built. +5. Density: keep it comfortable. Both too dense and too breathing read as untrustworthy in this archetype. + +## Exemplar brands + +Clinical Trustworthy is exemplified by Hims, Ro, Care/of, Cerebral, Mercury (in finance-trust context), and Stripe (in payment-trust context). Older or adjacent examples include early One Medical, the original Headspace landing surfaces before they leaned playful, and the original Robinhood when it was selling trust over excitement. + +These brands share: cool palette with optional warm humanizer, geometric or humanist sans throughout, real-hand photography, calm voice with specific evidence, generous form fields with help text. + +The archetype frequently splits brands by surface: Clinical Trustworthy for the marketing and conversion surface, with Warm Conversational notes in customer support and post-purchase. The hand-off matters: trust converts, warmth retains. diff --git a/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md b/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md new file mode 100644 index 0000000..6690a5f --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/08-rugged-utilitarian.md @@ -0,0 +1,115 @@ +# Rugged Utilitarian + +## Aesthetic summary + +Earth tones (clay, olive, charcoal, raw paper). Workwear-influenced type (slab serifs, condensed sans, stencil). Photography of real conditions: outdoor, working, lived-in. Voice is direct and unadorned. The brand reads as built for use rather than for show, and the visual restraint communicates that the product earns its place through function. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational (plain, direct, working-class register without affectation) +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #2C2A26 \| Charcoal primary \| +\| paper \| #F0EAD8 \| Raw paper background \| +\| paper-soft \| #E2DAC2 \| Tinted surface \| +\| accent-clay \| #B8543B \| Clay red primary \| +\| accent-olive \| #5C6B3D \| Olive green secondary \| +\| accent-sand \| #C29A60 \| Warm sand tertiary \| +\| accent-charcoal \| #2C2A26 \| Heavy charcoal (alternative primary) \| +\| line \| #A89B7F \| Warm tan border \| + +Rationale: +- Earth tones throughout. The palette is derived from natural pigments: oxide reds, military olives, sun-bleached tans, deep charcoals. +- Saturation is low to medium; nothing in the palette exceeds 60% saturation. Higher saturation pulls toward Bold Confident or Vibrant Saturated. +- The palette reads as outdoor and used. Pure white feels wrong; cool grays feel wrong. Warmth and weight are signature. +- Primary color is often the clay red or charcoal; olive functions as a secondary. The reverse also works. + +## Type pairing starter + +- Display: Druk Condensed, Bebas Neue, Roboto Slab, or a workwear-influenced slab (United Sans Slab, Sentinel). Heavy weight, condensed proportions. +- Body: Inter, Söhne, or a clean humanist sans. 400 to 500. +- Optional accent type: stencil or workshop-influenced display for product callouts and signage moments. + +Size scale (utilitarian, less extreme than Bold Confident): +- Hero: 56 to 80px display +- H2: 32 to 44px display +- H3: 22 to 26px sans +- Body: 16 to 18px sans +- Small: 13 to 14px sans +- Numeric mono: 14 to 16px (for spec sheets) + +Pairing rationale: condensed display type feels like signage on industrial equipment, on workwear labels, on shipping crates. Slab serifs feel like surveyor stamps and field guides. Clean humanist sans body keeps the page legible without dressing it up. + +## Layout and composition + +- Functional density. Information shown without softening. +- Heavy use of horizontal rules and labeled sections (the page reads like a spec sheet or field manual). +- Photography is large and full-bleed; the image carries the page. +- Cards are bordered (1 to 2px) rather than shadowed. Corners are sharp or low-radius (0 to 4px). +- Type often allCAPS for labels and section headers (reinforcing the signage register). + +## Imagery direction + +- Photography: real conditions. Real users in real environments. Dirt, sweat, weather, work. Not staged. Natural light dominant; flash photography rare. +- Photography subjects: products in use rather than products on white. The brand wants to show what the product looks like after a season of work, not what it looks like in a studio. +- Illustration: technical diagrams, exploded views, blueprints. Functional rather than decorative. +- Forbidden: pristine product-on-white shots (those belong to Minimal Essentialist or Luxe Considered), happy-family-lifestyle shots (those belong to Warm Conversational). + +## Voice samples + +- "Built to outlast you." +- "If it breaks, send it back. We will fix it." +- "Designed in Bozeman. Tested where it gets cold." +- "We made it heavier on purpose." +- "Spend it on the gear. Save it on the brand." +- "Lifetime guarantee. Read that again." + +Cadence: short. Direct. First-person plural ("we") when the brand speaks. Comfortable with imperative voice. No marketing jargon, no superlatives, no exclamation marks. Honest specifications over emotional appeals. + +## Component pattern descriptions + +Hero: Photograph (full-bleed, real-conditions) with overlaid type, or split layout with text left and photograph right. Headline in display, often condensed or slab. Buttons are direct. + +Buttons: Primary is solid charcoal or clay, white or cream text, sharp or low-radius corners (0 to 4px). Heavy and substantial; never floaty. Often labeled in all caps or with stencil-style lettering. + +Cards: Bordered (1 to 2px line), low-radius, generous internal padding. Often with a labeled header strip (uppercase, condensed) that reads like a product tag. + +Tables: Specification-sheet feel. Labeled rows. Mono numerics. Heavy horizontal rules between sections. + +Product detail: Honest. Materials listed. Construction methods explained. The reader is expected to care about how it is made. + +## When to pick this + +- Outdoor, gear, work-tool products +- Brands where durability and utility are the genuine value proposition +- Audience values function over fashion +- Brand has authentic claim to ruggedness (the brand actually serves people doing the work) + +## When to avoid + +- Brand is not actually utilitarian (the archetype reads as costume when applied to delicate products) +- Audience reads ruggedness as bro-culture or as anti-intellectual +- Brand needs to communicate softness, care, or gentleness +- Brand has no claim to outdoor or work-tool authenticity + +## Adaptation guidance + +1. Authenticity test: if the brand cannot show real photography of real use, this archetype is wrong. Switch to Documentary Honest if real photography is feasible at a different intensity. +2. Palette pick: clay-and-olive feels heritage outdoor (REI, Filson register). Charcoal-and-sand feels industrial workwear (Carhartt, Dickies register). Pick based on category position. +3. Type weight: heavy is non-negotiable. Light or regular weights pull the archetype toward Editorial Restrained. +4. Voice: avoid performed toughness ("BUILT FOR THE GRIND"). Real Rugged Utilitarian voice is matter-of-fact, not bombastic. +5. Specification depth: dedicate page real estate to materials, construction, warranty, repair policy. These are the trust signals. + +## Exemplar brands + +Rugged Utilitarian is exemplified by Patagonia, Carhartt, Yeti, Filson, Snow Peak, Best Made Co (historical), Topo Designs, REI in its product detail surfaces, Stanley (recently), and Hemlock Goods. Adjacent examples include Tom Bihn and Goruck. + +These brands share: earth-tone palette, condensed display or slab serif, real-conditions photography, plainspoken voice, specification depth, lifetime guarantee or repair offering. + +The archetype overlaps with Documentary Honest when photography is the dominant visual; the difference is that Rugged Utilitarian has explicit utility framing (this is for working) while Documentary Honest is about authentic representation more broadly (this is what real life looks like). diff --git a/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md b/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md new file mode 100644 index 0000000..72a07e7 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/09-retro-nostalgic.md @@ -0,0 +1,136 @@ +# Retro Nostalgic + +## Aesthetic summary + +Period-specific palette and type. Intentional vintage reference to a specific era (70s, 80s, 90s, or earlier). Often uses textured or grainy compositions. Voice references the era in cadence or vocabulary. The brand asks the audience to associate it with a felt period rather than with a category, and that association does most of the differentiation work. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Companion +- Sensory ambition: Theatrical + +## Color palette starter + +Three era-keyed palette options. Pick ONE era; do not blend. + +70s palette (warm, earthy, optimistic): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #2A1810 \| Deep brown primary \| +\| paper \| #F4EAD0 \| Cream ground \| +\| accent-orange \| #D2602B \| Burnt orange \| +\| accent-avocado \| #6A7A3A \| Avocado green \| +\| accent-mustard \| #D4A02E \| Harvest gold \| +\| accent-rust \| #8E3F1E \| Deep rust \| + +80s palette (neon, geometric, bold): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #0D0D2A \| Deep navy primary \| +\| paper \| #FAF5EF \| Cream surface \| +\| accent-pink \| #FF2D87 \| Hot pink \| +\| accent-cyan \| #18C2D9 \| Electric cyan \| +\| accent-yellow \| #FFD30F \| Saturated yellow \| +\| accent-purple \| #6A2EB8 \| Bold purple \| + +90s palette (muted, grunge-edged, prosumer): + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1F1A14 \| Warm dark brown \| +\| paper \| #E8DEC8 \| Aged cream \| +\| accent-rust \| #9C4B2E \| Muted rust \| +\| accent-teal \| #3E7575 \| Faded teal \| +\| accent-yellow \| #C49A35 \| Aged mustard \| +\| accent-purple \| #654273 \| Muted purple \| + +Rationale: +- Each era has a recognizable palette signature. Mixed-era palettes read confused; the audience cannot place the reference. +- The 70s palette is warm and earth-toned, optimistic but not bright. The 80s palette is neon and geometric. The 90s palette is muted, with deliberate aged warmth. +- Pick the era based on the audience's nostalgia moment: 70s for late-30s and older, 80s for late-30s to mid-40s, 90s for late-20s to mid-30s, early 00s for current 20-somethings. + +## Type pairing starter + +Era-keyed type pairings. Pick ONE era. + +- 70s: Cooper Black or VAG Rounded or ITC Bauhaus (display); Cooper or Avenir (body). +- 80s: Eurostile, Avant Garde, or Compacta (display); a clean geometric sans (Avenir, Futura) for body. +- 90s: Trade Gothic, a worn grunge serif (Bureau Grot, Knockout), or a digital-feeling sans (Eurostile) for display; classic sans for body. + +Size scale (varies by era, but generally expressive): +- Hero: 56 to 96px display +- H2: 36 to 48px display +- Body: 16 to 18px sans + +Pairing rationale: type is the era signature. Cooper Black is 70s consumer; Eurostile is 80s tech-future; Trade Gothic worn is 90s grunge. The reader recognizes the era through the type before recognizing it through the color. + +## Layout and composition + +- Era-specific composition styles. 70s leans toward soft asymmetric blocks and groovy curves. 80s leans toward hard geometric grids, oversized type, and Memphis-influenced shapes. 90s leans toward grunge collage, intentional rough edges, and zine-influenced layouts. +- Textures matter: grain, scan lines, paper-aged effects, halftone. Pure digital flat surfaces fight the archetype. +- Iconography is period-keyed: hand-drawn for 70s, geometric for 80s, photocopied-feeling for 90s. + +## Imagery direction + +- Era-keyed photography: warm-tinted and grainy for 70s, neon-lit and high-contrast for 80s, muted and slightly desaturated for 90s. +- Often pairs modern product photography with period-accurate styling (the product is contemporary, but the styling and framing reference the era). +- Pattern: era-accurate decorative elements (sunbursts, stripes, Memphis shapes, halftone dots) are common. + +## Voice samples + +(80s example for an energy drink brand) +- "Soda for people who remember what soda was." +- "From the era when caffeine had personality." +- "Yes, it tastes like that on purpose." +- "Made with cane sugar. Like before." + +(70s example for a wellness brand) +- "Roots, herbs, and a generally chill outlook." +- "Wellness from when wellness was just called feeling good." +- "Brewed the long way. Drunk the slow way." + +Cadence: era-keyed. 70s reads warm and unhurried. 80s reads punchy and confident. 90s reads ironic and self-aware. The voice should evoke the era without quoting it directly. + +## Component pattern descriptions + +Hero: Often centered with oversized era-keyed display type, paired with era-accurate decorative elements (sunburst, Memphis shapes, halftone, scan lines). Background frequently textured. + +Buttons: Era-keyed. 70s buttons are rounded and warm. 80s buttons are geometric and high-contrast. 90s buttons are flat with rough edges or grunge texture. + +Cards: Often with era-specific borders (chunky 70s borders, neon 80s outlines, distressed 90s edges). Background textures common. + +Patterns: Era-keyed pattern systems are common (gingham, paisley, geometric, Memphis, halftone). Used as section backgrounds, packaging, and brand accents. + +## When to pick this + +- F&B challenger brands in commoditized categories (soda, water, snacks) +- Lifestyle brands with a clear era-of-inspiration +- Brands wanting to differentiate in categories crowded with contemporary minimalist competitors +- Brand has clear position on which era and why + +## When to avoid + +- Brand has no genuine connection to the era (the archetype reads as costume) +- Brand needs to communicate forward-looking innovation +- Audience reads the chosen era as embarrassing or dated rather than nostalgic +- Brand cannot commit to the era at production cost (this archetype requires real photography styling and packaging design) + +## Adaptation guidance + +1. Era commitment: pick one era and commit. 70s plus 80s blend reads as confused; the audience cannot place the reference. +2. Texture investment: this archetype requires real textures (grain, halftone, paper aging). Flat digital versions read as contemporary-with-retro-fonts rather than genuinely retro. +3. Voice: avoid direct era quotation ("groovy," "rad," "totally tubular"). The voice should feel like the era, not parody it. +4. Modern functionality: the archetype is visual reference, not functional regression. The website should still work well in 2026; the visual reference is decorative. +5. Photography: era-styled photography is expensive. If budget is limited, lean harder into pattern and type as era carriers. + +## Exemplar brands + +Retro Nostalgic is exemplified by Olipop (70s wellness lean), Liquid Death (80s metal lean), Poppi (90s lean), Recess (70s wellness), Athletic Brewing (early 1900s heritage lean), Magic Spoon (90s cereal lean), and Olly (70s wellness lean). Adjacent examples include Brooklyn Brewery (heritage industrial), Hoxton Hotels (period-specific by property), and Howler Brothers. + +These brands share: era-keyed palette and type, period-specific decorative elements, texture-rich compositions, era-aware voice, packaging design that reads as the period. + +The archetype frequently anchors F&B challenger brands; the era pick is the differentiation strategy within a crowded category. Olipop and Poppi are both in the gut-health soda space; they differentiate primarily through 70s versus 90s era reference. diff --git a/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md b/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md new file mode 100644 index 0000000..7bcd522 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/10-minimal-essentialist.md @@ -0,0 +1,111 @@ +# Minimal Essentialist + +## Aesthetic summary + +Black, white, single accent maximum. Sans-serif only. Extreme whitespace. Type-led but at smaller scales than Luxe Considered. Compositions almost sparse to the point of empty. Voice is short and declarative. The brand earns attention by removing rather than adding, and the absence of ornament itself becomes the brand signal. + +## Position on the 4 creative-direction axes + +- Tone register: Professional +- Aesthetic register: Restrained +- Audience relationship: Authority +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #000000 \| True black primary \| +\| paper \| #FFFFFF \| Pure white \| +\| paper-soft \| #F7F7F7 \| Tinted gray surface (only when needed) \| +\| muted \| #888888 \| Mid-gray for secondary text \| +\| line \| #E5E5E5 \| Hairline separator \| +\| accent \| #FF3B30 \| Optional single accent (red shown; reserve for one use case) \| + +Rationale: +- Pure black and pure white. Off-black or off-white pulls the archetype toward Luxe Considered or Editorial Restrained. +- Single accent if any. Many Minimal Essentialist brands use no accent at all. When used, the accent appears once per page (a single CTA, a single error state, a single quote). +- Gray is the secondary palette. Mid-gray for secondary text, hairline gray for borders. +- No gradients. No tints beyond the gray scale. No color washes. + +## Type pairing starter + +- Display and body: One sans-serif family across all surfaces. Helvetica Now, Söhne, GT America, Inter, or Suisse Int'l. Multiple weights (300 to 700) carry the hierarchy. +- Optional secondary: Sometimes the same family in a tightly-set condensed cut for labels or navigation. + +Size scale (modest contrast, hierarchy through weight more than size): +- Hero: 40 to 56px sans (smaller than Bold Confident; the hero does not need to shout) +- H2: 28 to 36px sans +- H3: 20 to 24px sans +- Body: 16 to 17px sans +- Small: 13 to 14px sans + +Pairing rationale: one family across the system reinforces the discipline. Hierarchy is communicated through weight, size, and color rather than through type pairing. Neo-grotesque sans (Helvetica, Söhne, Suisse) feel pure; geometric sans (Avenir, Circular) feel slightly warmer; humanist sans (GT America, Inter) feel slightly friendlier. Pick based on the temperature you want. + +## Layout and composition + +- Extreme whitespace, but at smaller scale than Luxe Considered. The page reads as efficient rather than ceremonial. +- Often a strict grid: 12-column desktop with deliberate column spans. Asymmetry less frequent than in Editorial Restrained. +- Type-led: type sits in space rather than being framed by photography or color blocks. +- Cards are rare. Content sits directly on the page surface with hairline separators rather than card containers. +- Sharp corners (0 to 2px). Curves feel wrong in this archetype. + +## Imagery direction + +- Photography: product on white. Studio-lit. Considered. No styling beyond the product itself. +- People photography: rare. When used, portraits against neutral backgrounds, minimal styling. +- Illustration: extremely rare. Diagrams in line-only black-on-white if at all. +- Decorative imagery: none. The whitespace is the decoration. + +## Voice samples + +- "One mattress. One price." +- "We make the product. We tell you how it works. You decide." +- "The product is described accurately on the product page." +- "Returns within 100 days. No questions." +- "There is no enterprise tier." +- "The cheapest plan is the only plan." + +Cadence: very short. Declarative. First-person plural ("we") common. Numbers when relevant; otherwise sparse. The voice is honest to the point of dryness. No salesmanship, no superlatives, no hedging. + +## Component pattern descriptions + +Hero: Headline plus subhead plus single CTA. Often centered or hard left-aligned. Sometimes paired with a single product photograph against white; often with no imagery at all. + +Buttons: Solid black, white text, or solid white with black border. Sharp corners or 2 to 4px radius. Single CTA per section. + +Cards: Rare. When present: hairline border (1px line gray), no shadow, sharp corners, minimal internal styling. + +Tables: Hairline rows. Sans body throughout (no mono). Left-aligned text, right-aligned numerics. + +Navigation: Minimal. Logo (often wordmark only), a small number of nav items, a single CTA. No mega-menus, no drawer animations, no decorative chrome. + +## When to pick this + +- Brand wants to communicate timelessness or rigor +- Product is design-focused and the audience appreciates restraint as a value signal +- Brand is competing in a category where every competitor is ornamented; restraint is the differentiator +- Brand can defend the discipline (saying no to internal requests to add color, illustration, ornament) + +## When to avoid + +- Brand has rich content that benefits from visual organization (the archetype's lack of cards and color makes dense content hard to scan) +- Audience reads minimalism as cold or unwelcoming +- Brand needs to communicate warmth, personality, or specific human values +- Brand will eventually be tempted to add ornament (better to start in a more flexible archetype) + +## Adaptation guidance + +1. Discipline is the brand: this archetype requires institutional commitment to saying no. Adding decoration over time degrades the archetype faster than other archetypes. +2. Type family pick: Helvetica reads neutral and Swiss; Söhne reads contemporary and sharp; Suisse reads precise and minimal; Inter reads accessible and modern. Pick based on temperature, not novelty. +3. Color discipline: black plus white plus one accent maximum. Brands that "just add one more color" frequently undermine the archetype. +4. Photography: product-on-white only. Lifestyle photography pulls toward Warm Conversational or Luxe Considered. +5. Voice: write honest, not poetic. Minimal Essentialist voice that tries to be evocative reads as Luxe Considered; minimal voice that is too plain reads as Editorial Restrained. + +## Exemplar brands + +Minimal Essentialist is exemplified by Apple at its most restrained (mid-2010s product pages), Allbirds at launch, Muji, Casper at launch, Everlane, Squarespace (in its minimal era), The Ordinary, and Aritzia in product detail pages. Adjacent examples include Dieter Rams' principles applied to digital and the early Medium publication system. + +These brands share: black-white-plus-accent, single sans family, extreme whitespace, product-on-white photography, terse declarative voice, no decorative ornament. + +The archetype differs from Editorial Restrained primarily in the absence of serif type and the absence of warm paper backgrounds. Editorial Restrained allows serif display and warm cream; Minimal Essentialist eliminates both. Brands frequently start Minimal Essentialist at launch and migrate toward Warm Conversational or Editorial Restrained as the audience matures and the brand needs more content depth. diff --git a/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md b/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md new file mode 100644 index 0000000..0484151 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/11-vibrant-saturated.md @@ -0,0 +1,112 @@ +# Vibrant Saturated + +## Aesthetic summary + +High saturation across the full palette. Color used as primary brand expression. Type often plays second to color. Compositions are color-blocked. Voice is energetic and personality-driven. The brand makes color the primary asset, and the audience remembers the brand by hue before they remember the wordmark. + +## Position on the 4 creative-direction axes + +- Tone register: Playful +- Aesthetic register: Expressive +- Audience relationship: Performer +- Sensory ambition: Immersive + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #181818 \| Soft-black text \| +\| paper \| #FFFFFF \| White surface \| +\| accent-primary \| #FE2D81 \| Saturated brand pink \| +\| accent-secondary \| #2BC8F4 \| Bright cyan \| +\| accent-tertiary \| #FFD426 \| Saturated yellow \| +\| accent-quaternary \| #8B3DFF \| Vivid purple \| +\| accent-quinary \| #21D17C \| Bright green \| +\| signal \| varies \| Color-blocking accents derived from the palette \| + +Rationale: +- Multi-hue saturated palette is the signature. Single-accent palettes do not produce Vibrant Saturated. +- Saturation generally above 70% across the palette. The discipline is that all colors are at similar saturation; this is what produces palette coherence despite hue variety. +- Pure white surfaces. Cream and warm-white pull the archetype toward Warm Conversational. +- The palette is calibrated so any two colors can sit next to each other. This requires hue and value discipline; brands that wing it produce chaos rather than coherent vibrancy. + +## Type pairing starter + +- Display: A clean geometric or neo-grotesque sans (Söhne, GT America, Helvetica Now, or a brand-custom face). 600 to 800 weight. +- Body: Same family, 400 to 500. +- Optional serif: A clean serif (Source Serif, Tiempos Text) for editorial moments. Used sparingly. + +Size scale (color carries the page; type is competent rather than expressive): +- Hero: 48 to 64px sans +- H2: 32 to 40px sans +- Body: 16 to 18px sans +- Small: 14 to 15px + +Pairing rationale: the type is intentionally calmer than the color. Going expressive on both type and color produces visual chaos; one element carries the personality while the other carries the functional load. In Vibrant Saturated, color carries personality and type carries function. + +## Layout and composition + +- Color-blocked compositions are signature. Sections alternate full-bleed background colors; the page reads as panels. +- Heavy use of color as section organizer. The brand may use 6 different colors across a single page, each demarcating a different content type. +- Type sits in color fields rather than on white. White-on-saturated and dark-on-light alternate. +- Rounded corners are common but not aggressive (8 to 16px). +- Motion design uses color transitions (sections fade between hues on scroll, hover states shift hue). + +## Imagery direction + +- Photography: high-saturation, often product-on-color-block, sometimes graphic-treated. +- Illustration: brand-custom illustration systems often appear, with the brand's color palette as the discipline. +- Pattern: bold pattern systems common, using the brand palette. +- Product UI: shown against brand-color backgrounds rather than neutral surfaces. The product takes on the brand's color identity. + +## Voice samples + +- "Music for whatever you're feeling. All of it. Right now." +- "The good news: this works. The better news: you do not have to figure it out." +- "Yes, we are different. That is the point." +- "Press play. We will handle the rest." +- "Built for people who pick a color and commit." + +Cadence: energetic. First and second person. Comfortable with personality. Direct address. Numbers used playfully ("100 percent honest, 0 percent boring"). The voice is the spoken version of the visual energy. + +## Component pattern descriptions + +Hero: Often a single dominant brand color as background, with white type and a contrasting accent CTA. Sometimes split between two brand colors. The hero is the color, not the photograph. + +Buttons: Solid brand color, contrast text. 8 to 16px radius. Buttons may use one of several brand colors depending on context (the CTA color signals the section's purpose). + +Cards: Often colored rather than white. Each card may use a different brand color, with the color carrying meaning (category, type, status). 12 to 16px radius. + +Sections: Strong color demarcation. Section A is pink-on-white; Section B is cyan-on-white; Section C is yellow-on-dark. The reader navigates by color. + +Patterns and shapes: Common as section dividers and decorative accents. Always within the brand palette. + +## When to pick this + +- Consumer apps with strong category brands +- B2B brands targeting prosumer or creator audiences +- Brands where memorability through color is the strategy +- Brand has color system design discipline (this archetype is harder than it looks) + +## When to avoid + +- B2B brand targeting risk-averse buyers +- Brand cannot commit to color system discipline (winging it produces chaos) +- Brand needs to communicate seriousness or rigor as primary signals +- Category is already crowded with vibrant brands + +## Adaptation guidance + +1. Palette discipline first: defining 4 to 6 saturated hues that compose together is the hardest part of this archetype. Spend real time here; the rest is downstream. +2. Saturation calibration: keep all colors at similar saturation. Mixed high-saturation and low-saturation produces incoherence. +3. Type restraint: the type should not also be expressive. Clean type plus expressive color is the formula; expressive type plus expressive color is chaos. +4. Color carries meaning: in the strongest applications of this archetype, color is functional (different colors signal different content types). Use this rather than decorative color. +5. Accessibility: contrast ratios must work despite saturated palette. Test every color combination against WCAG AA at minimum. + +## Exemplar brands + +Vibrant Saturated is exemplified by Glossier (with restraint), Spotify, Notion (in its color-era brand expressions), Headspace (overlaps with Playful Energetic), Wise, Klarna, Bumble, and Patreon. Adjacent examples include the Slack rebrand era and the early Stripe consumer-facing surfaces. + +These brands share: multi-hue saturated palette, clean sans type, color-blocked compositions, color as section organizer, expressive but not chaotic compositions. + +The archetype overlaps with Playful Energetic when illustration becomes the dominant element; the difference is that Vibrant Saturated is color-first while Playful Energetic is character-first. Spotify is Vibrant Saturated; Duolingo is Playful Energetic. Both are colorful; the dominance pattern is what distinguishes them. diff --git a/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md b/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md new file mode 100644 index 0000000..183c053 --- /dev/null +++ b/skills/brand-archetype-system/references/core-archetypes/12-documentary-honest.md @@ -0,0 +1,111 @@ +# Documentary Honest + +## Aesthetic summary + +Photography-first. Real people in real conditions. Low touch on imagery. Type recedes to let imagery lead. Compositions are large and image-dominant. Voice is direct and journalistic. The brand uses honest representation as its primary asset, and the visual restraint signals that the product or experience is the real thing rather than the constructed thing. + +## Position on the 4 creative-direction axes + +- Tone register: Conversational +- Aesthetic register: Restrained +- Audience relationship: Peer +- Sensory ambition: Considered + +## Color palette starter + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| ink \| #1B1B1B \| Near-black text \| +\| paper \| #FAFAF8 \| Off-white surface \| +\| paper-soft \| #F0EFEB \| Subtle tinted surface \| +\| accent \| varies by imagery \| Pulled from dominant photography tones \| +\| muted \| #5C5C5A \| Mid-gray for metadata \| +\| line \| #E2E0DA \| Soft line color \| + +Rationale: +- The palette derives from photography rather than being imposed on photography. Each brand expression of this archetype has a distinct accent because the accent comes from the imagery world. +- Off-white surfaces with subtle warmth; the photography sits on the page rather than being framed by aggressive surfaces. +- Mid-gray secondary text reads as caption-feeling rather than UI-feeling. +- Saturation throughout the palette is low; photographs may be saturated, but the surrounding UI is muted to let imagery be the contrast. + +## Type pairing starter + +- Display: A clean serif (Tiempos Headline, Source Serif, GT Sectra) or a humanist sans (GT America, Söhne, Inter Display). 500 to 700. +- Body: Same family or matched body weight, 400 to 500. +- Caption type: A subtle italic or smaller weight for image captions and metadata, often in muted gray. + +Size scale (modest, deferential to imagery): +- Hero: 36 to 48px (smaller than most archetypes; the photograph carries hero weight, not type) +- H2: 26 to 32px +- Body: 17 to 19px (comfortable reading) +- Caption: 14 to 15px italic or in muted gray + +Pairing rationale: type sits in service of imagery. Restrained scale and weight let the photograph dominate. Italic captions read journalistic, evoking magazine and newspaper conventions. Either serif or sans works; the pairing should be calm. + +## Layout and composition + +- Photography is large and frequently full-bleed. The image occupies more page real estate than the type. +- Compositions reference editorial design: photograph with caption, photograph with pull quote, photograph plus body text. +- Asymmetric layouts where the image leads and text follows. Often 60/40 splits with photography dominant. +- Generous internal padding around text blocks. The text breathes within the layout. +- Hover states are subtle. The page reads as a document rather than as an interface. + +## Imagery direction + +- Real people, real environments, real conditions. Candid more often than posed. +- Natural light dominant. Studio lighting rare and intentional when used. +- Documentary photography conventions: telephoto compression for environmental portraits, wide-angle for context shots, intentional grain accepted. +- The archetype assumes investment in photography. Stock imagery undermines the archetype immediately. +- Photo direction matters more than photo quantity. A few exceptional images carry the archetype better than many adequate ones. + +## Voice samples + +- "She has been on the trail for six days. Today is the first day she has had warm feet." +- "We met him in the workshop where he learned the trade. He has worked there for 31 years." +- "Three thousand miles. Six time zones. One bag." +- "Built in Vermont. Tested in places where bad gear ends careers." +- "This is what we did. These are the people we did it with. These are the results." + +Cadence: journalistic. Third-person more often than first. Comfortable with specificity (real dates, real durations, real names where appropriate). The voice reads as reporting rather than selling. + +## Component pattern descriptions + +Hero: Large photograph (full-bleed or near-it) with overlaid restrained type, or photograph above type-only headline section. The photograph IS the hero. + +Buttons: Restrained. Often text-only with underlines, or thin-bordered with calm labels. The buttons recede; the photography leads. + +Cards: Often a card is a photograph plus caption plus body excerpt. The card structure mirrors editorial conventions (photo, caption, headline, dek). + +Quotes: Pulled quotes are a recurring pattern, set in restrained type with attribution beneath. + +Sequences: This archetype frequently uses image sequences (3 to 6 photographs telling a small story) where most archetypes use a single hero image. + +## When to pick this + +- Travel, hospitality, lifestyle brands where the experience IS the value proposition +- Journalism-adjacent brands (publications, archives, documentary work) +- Brands where real stories are the differentiation +- Brand has access to genuine documentary photography (either custom or excellently curated) + +## When to avoid + +- Brand has no real photography access or budget +- Product is functional rather than experiential +- Audience expects highly designed marketing rather than journalistic restraint +- Category is built on aspiration rather than reality (Documentary Honest fights aspirational positioning by definition) + +## Adaptation guidance + +1. Photography commitment: this is a photography archetype before it is anything else. If photography is going to be stock or poorly art-directed, switch archetypes. +2. Voice register: write journalistic, not marketing. Documentary Honest voice that slides into "we are passionate about" undermines the archetype. +3. Restraint discipline: resist adding decorative elements, color accents, or pattern. The photography is the visual; everything else should recede. +4. Caption discipline: captions are first-class content. They carry the story alongside the image. Treat them with the same care as headlines. +5. Authenticity test: the brand should be able to defend each photograph with a real story. Generic stock-feeling images destroy the archetype. + +## Exemplar brands + +Documentary Honest is exemplified by Airbnb (in its early marketing surfaces), Patagonia (overlaps with Rugged Utilitarian), Outside Magazine, The New York Times' visual journalism work, REI in its editorial content, Selina, and Yeti (in its long-form brand content). Adjacent examples include Field Mag, Topo Designs in long-form marketing, and Filson's historical archives. + +These brands share: real photography as primary visual, restrained type system, journalistic voice, image-plus-caption editorial conventions, low-saturation palette derived from imagery. + +The archetype overlaps with Rugged Utilitarian (both rely on real photography) and Editorial Restrained (both rely on restrained type). The difference: Rugged Utilitarian has utility framing (this is for working); Editorial Restrained is institutional confidence applied to B2B; Documentary Honest is honest representation applied to experience and story. diff --git a/skills/brand-discovery/SKILL.md b/skills/brand-discovery/SKILL.md new file mode 100644 index 0000000..3829f09 --- /dev/null +++ b/skills/brand-discovery/SKILL.md @@ -0,0 +1,197 @@ +--- +name: brand-discovery +description: "Run upstream brand discovery covering audience research, competitive landscape, category dynamics, problem space, and positioning territory exploration. Use this skill at the very start of a brand or website project when the user needs to understand who they're for, who they compete with, what the audience actually needs, and where the brand could plausibly stand. Triggers on brand discovery, audience research, market research, competitive scan, category research, customer research, who is this for, who are we, positioning research, intake, kickoff. Also triggers when a creative brief is requested but the upstream inputs (audience, competitors, problem space) are not yet clear." +category: strategy-and-discovery +catalog_summary: "Audience research, competitive scan, positioning territory exploration" +display_order: 1 +--- + +# Brand Discovery + +Upstream of every brief, identity, and content plan. Discovery answers four questions: who the brand is for, what they need, who else is competing for that need, and where the brand could plausibly stand that competitors do not. + +--- + +## When to use + +- The very first phase of a new brand or website project +- Understanding an audience before any creative work begins +- Mapping competitors and category dynamics +- Surfacing the problem space the brand will operate in +- Generating positioning territories before brief or ideation +- When a creative brief was requested but the inputs are missing + +## When NOT to use + +- The audience and category are already well-understood (jump to `creative-brief` or `brand-ideation`) +- Validating a specific design or feature with users (use `usability-testing`) +- Mapping the customer journey of an existing audience (use `journey-mapping`) +- Generating brand names or visual directions (use `brand-ideation`) + +--- + +## Required inputs + +- The product, service, or organization being branded +- Whatever is already known about the audience and category (often very little) +- Access to existing materials (sales calls, support tickets, reviews, analytics) +- Any constraints (parent brand, regulatory, geographic) +- A timeline (a 1-week discovery looks different than a 6-week one) + +--- + +## The framework: 4 dimensions + +Discovery covers four dimensions. Each has its own sources, methods, and outputs. + +### 1. Audience + +Who specifically does this serve? + +Layers to surface: + +- Demographic: Age range, geography, language, life stage, income (only if relevant; do not over-collect demographics) +- Psychographic: Values, motivations, beliefs, fears +- Behavioral: What they currently do to address the problem, what tools they use, where they spend time online and offline +- Jobs-to-be-done: The functional, emotional, and social jobs they hire a brand to perform + +Sources: + +- Existing customer interviews (5 to 8 ideal) +- Sales call recordings or transcripts +- Support ticket themes +- Review and forum analysis (Reddit, Trustpilot, App Store, niche communities) +- First-party analytics (search console queries, on-site search, top pages) +- Social listening (what they post about the category) + +Output: 1 to 3 named audience segments, each with a one-page profile. + +### 2. Competitors + +Who else competes for the same audience and need? + +Three layers of competitor: + +- Direct: Solves the same problem the same way (e.g., another SaaS in the category) +- Indirect: Solves the same problem a different way (e.g., a spreadsheet replacing a SaaS tool) +- Status quo: Doing nothing, doing it manually, or living with the problem + +The third is most often forgotten and most often the actual competitor. + +Per competitor, document: + +- Who they target (audience overlap with you) +- How they position (what they claim to be) +- What they actually deliver (often different from positioning) +- Pricing model and structure +- Strengths and weaknesses from the audience's perspective +- Recent moves (launches, pivots, hires, departures) + +Sources: + +- Their own website and marketing +- Reviews of their product or service +- Their content and SEO presence (use `seo-competitor` for the search angle) +- Social proof and customer voices + +Competitive scan benefits from quantitative grounding: not just "who are the competitors" but "how much traffic do they earn, where does it come from, who is the audience overlap." Similarweb is the standard for this kind of competitive landscape analysis; pair with Ahrefs for the SEO-specific overlap. + +Output: Competitor matrix (3 to 8 competitors deep), plus a one-line "what makes them dangerous" for each. + +### 3. Category and problem space + +What is the broader context this brand operates in? + +Map: + +- The problem. What is the actual user problem? Not the surface symptom, the underlying job to be done. +- The category. How is the category structured? Is it new, mature, fragmenting, consolidating? +- The conventions. What does every brand in the category do the same way? (These are the conventions you can break.) +- The shifts. What is changing in the category? Technology, regulation, audience behavior, distribution. +- The moats. What protects incumbents? Brand, distribution, network effects, switching costs? +- The vocabulary. What language does the category use? What is jargon, what is meaningful, what is empty? + +Sources: + +- Industry reports and analyst coverage +- Trade publications and conferences +- Adjacent category observations +- Customer language vs. category language (the gap is informative) + +Output: A category map and a list of conventions to consider breaking (or keeping deliberately). + +### 4. Positioning territory + +Given the audience, competitors, and category, where could this brand plausibly stand? + +This is not yet "the positioning." Discovery surfaces possible territories. `brand-ideation` narrows them and commits. + +Generate territories from: + +- Underserved audience segments (audiences others ignore) +- Underserved jobs (jobs the category does not do well) +- Category convention violations (what would happen if you broke the rules everyone follows) +- Honest brand truths (what is genuinely true about this brand that competitors cannot also claim) +- Category shifts (where the puck is going) + +Per territory, document: + +- The statement (one sentence) +- Why it could work (proof point) +- Who would resonate (the audience for this territory) +- Who is competing in this territory (often, no one good) +- Risk (what makes it fragile) + +Output: 3 to 5 distinct territories. Not yet committed. Inputs to `brand-ideation`. + +--- + +## Workflow + +1. Define the discovery scope. 1 week for a startup pre-launch. 4 to 6 weeks for a major rebrand. Set expectations. +2. Audit existing inputs. Sales calls, support tickets, reviews, analytics, internal docs. Often more is known than people think. +3. Audience research. 5 to 8 interviews if possible. Plus secondary research from review and forum analysis. +4. Competitor mapping. 3 to 8 competitors deep, including indirect and status-quo competitors. +5. Category mapping. Conventions, shifts, vocabulary, moats. +6. Territory generation. 3 to 5 plausible positioning territories. +7. Write the discovery report. Use the template in [`references/discovery-report-template.md`](references/discovery-report-template.md). +8. Hand off to next phase. Discovery feeds into `creative-brief`, `brand-ideation`, or `content-strategy` depending on where the project goes next. + +--- + +## Failure patterns + +- Skipping discovery to "save time." Every shortcut here costs 10x downstream when the brand fails to land. +- Audience research that confirms what you already believe. If your audience research validates every assumption, you did not actually research. Look for surprises. +- Demographic-heavy audience profiles. "Women aged 25 to 45" is not insight. Behavior, beliefs, and jobs-to-be-done are. +- Listing every competitor as if equal. Most competitors do not matter. Pick the 3 that are genuinely dangerous. +- Forgetting status-quo as competition. The biggest competitor is usually "doing nothing" or "doing it manually." +- Outputting territories without rejection criteria. A territory without a "what this rejects" is not a territory. +- Treating discovery as a one-time event. Categories shift. Audiences evolve. Re-run discovery at least every 3 years. + +--- + +## Output format + +Default output is a discovery report at `discovery-report.md` plus appendices. + +Structure: +1. Executive summary (5 to 10 bullets) +2. Audience (1 to 3 named segments with profiles) +3. Competitors (matrix and per-competitor analysis) +4. Category and problem space +5. Positioning territories (3 to 5 candidates) +6. Implications and recommendations +7. Open questions that require further research + +Appendices: +- Interview notes (sanitized) +- Competitor research data +- Source list + +--- + +## Reference files + +- [`references/discovery-report-template.md`](references/discovery-report-template.md) - Full discovery report template. +- [`references/interview-guide.md`](references/interview-guide.md) - Audience interview guide with question prompts. diff --git a/skills/brand-discovery/references/discovery-report-template.md b/skills/brand-discovery/references/discovery-report-template.md new file mode 100644 index 0000000..68844e7 --- /dev/null +++ b/skills/brand-discovery/references/discovery-report-template.md @@ -0,0 +1,177 @@ +# Brand Discovery Report Template + +A fillable template for the discovery deliverable. The discovery report is what every later phase of brand work references. If a section is thin, later phases will be too. + +Fill every section. If a section is "N/A", say why explicitly. + +--- + +## Project metadata + +Brand / project: [Name] +Phase: [Initial discovery / refresh / repositioning] +Date: [YYYY-MM-DD] +Lead: [Name] +Stakeholders interviewed: [Names and roles] +Customers interviewed: [Number, segments] + +--- + +## Executive summary + +Three to five sentences. The single most important thing the discovery surfaced, the strongest opportunity, and the biggest risk. + +> [Summary] + +--- + +## Audience + +### Primary audience + +Who they are: [Demographic and behavioral picture. Not a persona archetype. Real, specific, current.] + +What they want: [The job they hire the category to do. Surface and underlying.] + +What they fear or doubt: [Objections, hesitations, alternative options being considered.] + +Where they are: [Channels, communities, sources of trust.] + +Quotes (verbatim from interviews): + +> "[Verbatim quote that reveals motivation or pain]" - [Segment] +> "[Verbatim quote]" - [Segment] +> "[Verbatim quote]" - [Segment] + +### Secondary audience(s) + +[Only include if they materially shape the work. Otherwise note "none material" and move on.] + +--- + +## Category and competition + +### The category as the audience sees it + +What the audience calls this category. What they group us with. (Often different from how the company sees it.) + +### Direct competitors + +\| Competitor \| Position they hold \| Strength \| Weakness \| Opportunity for us \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| +\| \| \| \| \| \| + +### Indirect / adjacent + +[Substitutes the audience considers, even if not in the same product category.] + +### Reference brands (aspirational) + +[Brands the audience admires that we want to be associated with - same audience, different category.] + +--- + +## Positioning territory + +### What we found + +The discovery process should produce 2 to 4 candidate positioning territories. Each is a defensible space the brand could own. + +#### Territory 1: [Name] + +- Core idea: [One sentence] +- Why it could work: [Audience need it serves, gap in competition, asset we have] +- Why it could fail: [Risk, what would have to be true] +- What it would look like: [How marketing, product, copy would feel under this territory] +- Evidence from research: [Specific findings that support this] + +#### Territory 2: [Name] + +[Same structure] + +#### Territory 3: [Name] + +[Same structure] + +### Recommendation + +The discovery report is allowed to recommend one. Make the case. Or explicitly punt: "Run a positioning workshop with these four candidates." + +--- + +## Brand truths + +What the discovery surfaced about who this brand actually is, not what marketing has been saying. + +### What is true + +- [Fact about the company, founders, product, or community that is real and ownable] +- [Fact] +- [Fact] + +### What is aspirational (and that is OK) + +- [Thing we want to be that we are not yet, but are credibly working toward] +- [Thing] + +### What is not true (and stop saying) + +- [Claim the company makes that did not survive scrutiny] +- [Claim] + +--- + +## Strategic implications + +What the discovery means for the work ahead. + +### For brand identity + +- [Implication, e.g., "The visual direction should signal quietness, not loudness; the audience is exhausted by category noise."] + +### For brand voice + +- [Implication, e.g., "Voice should be confident without being clever; the audience equates cleverness with sales pressure."] + +### For product + +- [Implication if discovery surfaced product-level gaps or strengths] + +### For marketing + +- [Implication for channel strategy, content focus, message hierarchy] + +--- + +## Open questions + +Things discovery raised that it did not answer. These belong in the next phase. + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Methodology and sources + +- Stakeholder interviews: [Number, role mix, format] +- Customer interviews: [Number, segment mix, format] +- Customer surveys: [Sample size, response rate] +- Competitive scan: [Number of brands, depth of review] +- Search and social listening: [Sources, time window] +- Internal docs reviewed: [Strategy decks, prior research] +- Caveats: [What this discovery did not cover, sample limitations] + +--- + +## Sign-off + +Discovery accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand ideation / positioning workshop / direct to identity / etc.] diff --git a/skills/brand-discovery/references/interview-guide.md b/skills/brand-discovery/references/interview-guide.md new file mode 100644 index 0000000..340ee32 --- /dev/null +++ b/skills/brand-discovery/references/interview-guide.md @@ -0,0 +1,193 @@ +# Audience Interview Guide + +A guide for conducting 30 to 45 minute interviews with current customers, prospects, or audience members during brand discovery. + +The goal of interviews is not to validate assumptions. It is to find surprises. Plan to be wrong about most of what you think you know. + +--- + +## Before the interview + +### Who to interview + +For a typical brand discovery, talk to 5 to 8 people across these segments: + +- Active customers who have been using the product for 3+ months (deep understanding) +- Recent customers who joined in the last 30 days (still remember the buying journey) +- Lapsed customers who churned (the most informative; understand why people leave) +- Prospects who didn't buy (understand objections) +- Power users in adjacent categories (understand alternatives and substitutes) + +If the project is for a new brand with no customers yet, interview members of the target audience using competitive products or substitutes. + +### Recruiting + +Recruit through: +- Customer email list with a thank-you incentive +- Sales team referrals +- LinkedIn outreach to titles matching the audience profile +- Existing user research panels +- Niche communities (Reddit, niche Slack groups, professional forums) + +Compensate participants. $50 to $100 in cash or product credit is reasonable for 30 minutes. + +### Logistics + +- 30 to 45 minutes is the right length. Longer fatigues both sides. +- Record (with consent). Take notes too in case the recording fails. +- Use a video tool that creates transcripts automatically. +- Send a calendar invite with a clear agenda. +- Confirm the day before. + +--- + +## Question framework + +Structure interviews in three sections: their world, the problem, and how they currently solve it. + +### Opening (3 to 5 minutes) + +Get them talking. Build rapport. Establish that there are no wrong answers. + +- "Tell me a bit about yourself and what you do." +- "Walk me through a typical day. What does work look like?" +- "How long have you been doing this kind of work?" + +These warm-up questions also surface context you'll need later. + +### Section 1: Their world (10 minutes) + +Understand the context the brand fits into. + +- "When you think about [the problem area or category], what comes to mind?" +- "What's the part of your work or life this connects to?" +- "How important is [the problem area] in the bigger picture of what you do?" +- "Who else is involved in [the problem area]? Coworkers? Family? Clients?" +- "What's the goal you're trying to hit in this area?" + +Listen for: priorities, stakeholders, vocabulary, time pressure. + +### Section 2: The problem (10 to 15 minutes) + +Surface the actual problem, not the surface symptom. + +- "Tell me about the last time you ran into [the problem]. Walk me through what happened." +- "What was frustrating about that?" +- "What did you try to do about it?" +- "What did you wish had happened instead?" +- "What's the cost of this problem? Time? Money? Stress? Relationships?" +- "Have you ever just decided to live with it instead of solving it? Why?" + +Listen for: emotional weight, the real cost, the workarounds people invent, the resignation. + +The key follow-up: "Tell me more about that." Use it relentlessly. Most insight is one or two layers below the first answer. + +### Section 3: How they solve it now (10 to 15 minutes) + +Understand the current toolkit and the alternatives considered. + +- "What do you currently use to address [the problem]?" +- "How did you start using [their current solution]? What were you using before?" +- "What did you consider but not pick? Why not?" +- "What do you wish [your current solution] did better?" +- "If you could wave a magic wand and have [the problem] solved perfectly, what would that look like?" +- "Imagine a tool came along that promised to solve [the problem]. What would it have to be true for you to switch?" + +Listen for: the switching cost, the unmet needs, the specific moments where current solutions fail. + +### Closing (3 to 5 minutes) + +- "Is there anything I should have asked but didn't?" +- "Is there anyone else you think I should talk to about this?" +- "Would you be open to a follow-up if questions come up later?" + +--- + +## Common interview pitfalls + +### Leading questions + +Bad: "Do you find it frustrating when [your assumption]?" + +Better: "Tell me about your last experience with [the activity]." + +The first question telegraphs the answer you want. The second lets them tell you what was actually frustrating, including things you didn't predict. + +### Asking for solutions + +Bad: "What features would you want in [the product]?" + +Better: "What's frustrating about how this works today?" + +Users are not product designers. They are the world's leading experts on their own frustrations. Mine the frustrations; you'll design the solutions. + +### Validating instead of investigating + +Bad: "Would you use [feature description]?" + +Better: "When was the last time you needed something like that? What did you do?" + +Hypothetical answers are useless. Past behavior is informative. + +### Closed questions + +Bad: "Was that frustrating?" + +Better: "How did you feel about that?" + +Yes/no questions kill the conversation. Open questions keep it going. + +### Talking too much + +If you're talking more than 20 percent of the time, you're talking too much. Your job is to listen, follow up, and get out of the way. + +--- + +## Synthesis + +After all interviews, synthesize across them. + +### Step 1: Tag the transcripts + +Read every transcript. Tag passages by theme: +- Pain points +- Workarounds +- Aspirations +- Vocabulary they use +- Emotional moments +- Surprising statements + +### Step 2: Identify recurring patterns + +A theme that appears in 3+ interviews is signal. A theme in 1 interview is interesting but anecdotal. + +### Step 3: Look for surprises + +The most valuable findings are things you didn't expect. List them explicitly. These often become the basis for distinctive positioning. + +### Step 4: Identify quotes + +The right quote captures more than a paragraph of synthesis. Pull 5 to 10 quotes that capture the core insights. + +### Step 5: Write the audience section of the discovery report + +For each segment: +- Who they are (with the specificity you've earned) +- What they're trying to do +- What's getting in the way +- How they currently solve it +- What they wish were different +- Anchor quote (one strong verbatim quote) + +--- + +## What to avoid + +- Treating the interview as a sales pitch +- Asking about your specific product or feature ideas (validation theater) +- Skipping interviews because "we already know our customer" (you don't) +- Interviewing only happy customers (lapsed customers are more informative) +- Doing 1 or 2 interviews and declaring "we did research" +- Skipping synthesis and going straight to "here's what we learned" without rigor + +5 interviews is the minimum to find patterns. 8 is comfortable. 12+ has diminishing returns for most projects. diff --git a/skills/brand-ideation/SKILL.md b/skills/brand-ideation/SKILL.md new file mode 100644 index 0000000..55ed7b3 --- /dev/null +++ b/skills/brand-ideation/SKILL.md @@ -0,0 +1,175 @@ +--- +name: brand-ideation +description: "Generate, evaluate, and narrow brand concepts during early ideation including positioning territories, naming candidates, mood directions, and narrative angles. Use this skill whenever the user is in the early phase of brand creation, exploring brand directions, brainstorming names, building moodboards, generating positioning options, or trying to choose between multiple brand directions. Triggers on brand ideation, brand concept, naming, brand name, name candidates, positioning, brand positioning, mood board, brand directions, exploring brands, early brand work, brand exploration, brand brainstorm, brand options. Also triggers when the user has multiple half-formed brand ideas and needs help converging on one, even if they do not say 'ideation' explicitly." +category: brand +catalog_summary: "Naming, positioning territories, mood directions, narrative angles" +display_order: 1 +--- + +# Brand Ideation + +Generate and converge on brand directions before committing to identity work. This is upstream of `brand-identity` (the visual system) and `brand-style-guide` (the documentation). It is the divergent-then-convergent thinking phase where ideas are cheap and direction matters more than polish. + +--- + +## When to use + +- Generating naming options for a new brand or product +- Exploring positioning territories before committing +- Building moodboards and visual direction options +- Drafting narrative or origin-story angles +- Helping the user converge from many half-ideas to one direction +- Stress-testing an existing brand idea before investing in identity work + +## When NOT to use + +- The brand direction is already locked, the user wants logo and identity work (use `brand-identity`) +- Documenting an existing brand system (use `brand-style-guide`) +- Defining voice for an existing brand (use `brand-voice`) +- Initial discovery and audience research (use `brand-discovery`) + +--- + +## Required inputs + +- The category or product type +- The audience (at least roughly) +- The reason this brand exists (the problem it solves or the gap it fills) +- Constraints (existing brand assumptions, parent brand, regulatory limits) +- Number of directions desired (typically 3 to 5) + +If the audience is unclear, run `brand-discovery` first. + +--- + +## The framework: 4 stages + +Brand ideation moves through four stages. Each stage diverges (generate options) then converges (pick a direction). + +### Stage 1: Positioning territories + +A positioning territory is the strategic space the brand occupies. It is not a tagline. It is the answer to "what does this brand stand for that competitors do not?" + +Generate 3 to 5 territories using these angles: + +- Functional benefit. "The fastest way to X." (Risk: easy to copy.) +- Emotional benefit. "The brand that makes you feel Y." (Risk: vague if not earned.) +- Identity. "For people who are Z." (Risk: alienates non-Z customers.) +- Antagonist. "The opposite of [incumbent]." (Risk: defines you by them.) +- Originator. "The first or only one to do W." (Risk: must be defensible.) +- Worldview. "We believe V." (Risk: must be lived, not just stated.) + +For each territory, write: +- Statement (one sentence) +- Why this is true (the proof point) +- What this rejects (the territory we are NOT going to) +- Risk (what makes this fragile) + +### Stage 2: Naming directions + +Names cluster by approach. Generate names across multiple approaches, not just one. + +\| Approach \| Description \| Examples \| +\|---\|---\|---\| +\| Descriptive \| Says what it is \| "General Electric," "American Airlines" \| +\| Evocative \| Suggests a feeling or quality \| "Patagonia," "Oasis," "Stripe" \| +\| Founder \| Person's name \| "Disney," "Ford," "Tesla" \| +\| Acronym \| Letters from longer phrase \| "IBM," "BMW," "AWS" \| +\| Coined \| Made-up word \| "Kodak," "Häagen-Dazs," "Asana" \| +\| Metaphor \| Borrowed concept \| "Apple," "Amazon," "Twitch" \| +\| Compound \| Two words combined \| "Facebook," "PayPal," "Spotify" \| +\| Suggestive \| Hints at function without describing \| "Tide," "Sprint," "Slack" \| + +Generate 8 to 15 candidates per direction. Apply naming filters before short-listing: + +- Pronounceable in target languages +- Spellable without confusion +- Available as a domain (.com or relevant TLD), social handles, and trademark +- Distinctive in the category (search the name + category, see what comes up) +- Stretchable (does the name still work if the company expands?) +- Free of negative associations (run it past native speakers of any major target market) + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high. + +### Stage 3: Mood and visual direction + +Generate visual directions BEFORE designing anything. Each direction should be distinct enough that a designer would produce visibly different work for each. + +For each mood direction (typically 2 to 4): + +- Mood adjectives (3 to 5 words) +- Color territory (warm/cool, saturated/muted, light/dark - not specific hex yet) +- Type territory (serif/sans, modern/classical, geometric/humanist) +- Imagery direction (photography style, illustration style, iconography) +- Reference brands or sites (3 to 5 that exemplify the direction) +- What this rejects (the visual territory we are NOT going to) + +A mood direction is "Editorial sophistication: Warm cream paper backgrounds, classical serifs, archival photography. Think: The New York Times Magazine meets a literary journal." + +A bad mood direction is "Modern and clean." + +### Stage 4: Narrative and origin + +Every brand has a story. The narrative answers: how do we tell people why this exists? + +Common narrative shapes: + +- Founder story. A real person solved a real problem they had. +- Mission story. A bigger purpose drives every decision. +- Discovery story. We found something the world did not know. +- Heritage story. This has always been done a certain way; we honor or refresh it. +- Frustration story. The category was broken; we built the alternative. +- Vision story. Here is the future we are pulling toward. + +For each candidate narrative: + +- One-sentence summary +- The opening line (how the story starts when told for the first time) +- The proof points (what makes it true and not marketing puff) +- The hero (who the audience identifies with - the founder, the customer, the world) + +--- + +## Workflow + +1. Confirm the inputs. Category, audience, reason for being, constraints. +2. Stage 1: Generate 3 to 5 positioning territories. Use the 6 angles above. Name what each rejects. +3. Pick 1 to 2 territories. Move forward with the strongest. +4. Stage 2: Generate 30 to 50 naming candidates across at least 4 approaches. Filter to 8 to 12 that pass the six-criteria check. +5. Stage 3: Generate 2 to 4 mood directions. Each must be distinguishable enough to brief a designer. +6. Stage 4: Generate 2 to 3 narrative shapes. Pick the one that fits the founders, the audience, and the proof points. +7. Converge. Present the user with: 1 positioning, 8 to 12 naming finalists, 2 to 4 mood directions, 2 to 3 narrative shapes. Help them pick. +8. Output. Use the template in [`references/ideation-output-template.md`](references/ideation-output-template.md). + +--- + +## Failure patterns + +- Generating one option and calling it "the answer." The point of ideation is divergence. Without options, there is no real choice. +- Skipping the rejection step. A territory that does not name what it rejects is not a territory. Same for moods. +- Naming before positioning. Names without positioning end up arbitrary. Position first. +- Falling in love with one name too early. Run the full filter on every candidate. The clever name that fails the trademark check is not a candidate. +- "Modern, clean, minimal" mood direction. Means nothing. Always require specific reference brands. +- Skipping pronunciation tests. Especially for international brands. A name that confuses non-English speakers loses search volume forever. +- Mistaking ideation for execution. The output of this stage is direction, not finished assets. Resist the urge to design logos here. + +--- + +## Output format + +Default output is a markdown brief at `brand-ideation.md` in the project root. Includes: + +1. The chosen positioning territory (with what it rejects) +2. Naming finalists (8 to 12) with notes on each +3. Mood directions (2 to 4) with reference URLs +4. Narrative shape (chosen) with opening line and proof points +5. Open questions and decisions still needed before identity work begins + +Optional: a separate `naming-explorations.md` with the full list of 30 to 50 candidates (the "kill file") in case the chosen finalists fail later checks. + +--- + +## Reference files + +- [`references/ideation-output-template.md`](references/ideation-output-template.md) - Fillable template for the ideation deliverable. +- [`references/naming-evaluation-rubric.md`](references/naming-evaluation-rubric.md) - The 6-criteria filter applied with examples. diff --git a/skills/brand-ideation/references/ideation-output-template.md b/skills/brand-ideation/references/ideation-output-template.md new file mode 100644 index 0000000..e3d208c --- /dev/null +++ b/skills/brand-ideation/references/ideation-output-template.md @@ -0,0 +1,181 @@ +# Brand Ideation Output Template + +A fillable template for the ideation deliverable. Captures the candidate names, positioning territories, mood directions, and narrative angles produced during ideation. + +The deliverable is not a single answer. It is a structured set of options the team can evaluate, narrow, and combine. + +--- + +## Project metadata + +Brand / project: [Name] +Ideation lead: [Name] +Date: [YYYY-MM-DD] +Inputs used: [Discovery report, brief, prior decks - link them] + +--- + +## Recap: what we are ideating against + +Two to four sentences. Pull from the discovery report. Anyone reading this deliverable cold should know: + +- Who the audience is +- What position the brand is trying to take +- What the constraints are (legal, geographic, category) + +> [Recap] + +--- + +## Naming candidates + +Generate widely first. Filter later. Aim for 30-50 candidates per round before applying the rubric. + +### Round 1: divergent + +\| # \| Name \| Type \| Source / inspiration \| +\|---\|---\|---\|---\| +\| 1 \| \| Coined / descriptive / metaphorical / founder / acronym / compound / portmanteau \| \| +\| 2 \| \| \| \| +\| 3 \| \| \| \| +\| ... \| \| \| \| + +### Round 2: filtered shortlist + +After applying the 6-criteria rubric (`naming-evaluation-rubric.md`), the names that survive. + +\| # \| Name \| Why it survived \| Open concerns \| +\|---\|---\|---\|---\| +\| 1 \| \| \| \| +\| 2 \| \| \| \| +\| 3 \| \| \| \| +\| 4 \| \| \| \| +\| 5 \| \| \| \| +\| 6 \| \| \| \| + +### Round 3: top 3 with full case + +For each finalist, write a one-page case. + +#### Finalist 1: [Name] + +- Pronunciation: [How it is said] +- Type: [Coined, metaphor, etc.] +- Meaning: [What it evokes, intentionally or by association] +- Why it works: [Per the 6 criteria] +- Risks: [Domain availability, trademark, cultural concerns, audience misreading] +- Domain status: [.com / alternative TLDs / acquisition cost estimate] +- Trademark status: [Cleared by counsel / preliminary search clean / requires deeper search] +- Visual potential: [How it could render as a wordmark, monogram, icon] + +#### Finalist 2: [Name] + +[Same structure] + +#### Finalist 3: [Name] + +[Same structure] + +--- + +## Positioning territories + +The territories from discovery, sharpened into ideation directions. Each territory should produce a distinct creative direction. + +### Territory 1: [Name] + +- One-sentence position: [The territory in a sentence] +- Voice direction: [How it sounds] +- Visual direction: [How it looks] +- Headline examples: [3-5 sample headlines that could only come from this territory] +- What it rules out: [Names, treatments, or messages this territory disqualifies] + +### Territory 2: [Name] + +[Same structure] + +### Territory 3: [Name] + +[Same structure] + +### Territory 4: [Name] + +[Same structure] + +--- + +## Mood directions + +Three to five mood directions, each with reference imagery, color cues, and a one-line description. These are not final design - they are starting points for art direction. + +### Mood 1: [Name, e.g., "Quiet confidence"] + +- Description: [One line] +- References: [3-5 visual references with credit and one-line note on what to take from each] +- Color cues: [General feel, not exact palette] +- Typography cues: [General feel] +- Photography or illustration direction: [General feel] +- Adjacent brands as reference: [Not to copy, to triangulate] + +### Mood 2: [Name] + +[Same structure] + +### Mood 3: [Name] + +[Same structure] + +--- + +## Narrative angles + +Three to five candidate brand stories or origin narratives. Each is a different way of telling who this brand is and why it exists. + +### Angle 1: [Name, e.g., "Founder's journey"] + +- Premise: [The narrative angle in two sentences] +- First page hero: [What the homepage hero would say under this angle] +- About page opening: [The first paragraph of the about page] +- Why it works: [What it earns the brand] +- Why it might fail: [Risk] + +### Angle 2: [Name] + +[Same structure] + +### Angle 3: [Name] + +[Same structure] + +--- + +## Synthesis: provisional recommendation + +Even though ideation produces options, the team should leave with a provisional combination to test next. + +> Provisional combination: Name [X], territory [Y], mood [Z], narrative [W]. +> +> Why this combination: [Two sentences.] +> +> What we test next: [Concept board, name validation with audience, treatment exploration, etc.] + +--- + +## Open questions + +- [ ] [Trademark search needed for finalist names] +- [ ] [Domain acquisition feasibility] +- [ ] [Audience reaction test for top 2 names] +- [ ] [Stakeholder alignment session for territory selection] +- [ ] [Other] + +--- + +## Sign-off + +Ideation accepted by: + +- [Name, role, date] +- [Name, role, date] + +Recommended next phase: [Brand identity / further name validation / board-level review / etc.] diff --git a/skills/brand-ideation/references/naming-evaluation-rubric.md b/skills/brand-ideation/references/naming-evaluation-rubric.md new file mode 100644 index 0000000..d34bbfa --- /dev/null +++ b/skills/brand-ideation/references/naming-evaluation-rubric.md @@ -0,0 +1,151 @@ +# Naming Evaluation Rubric + +A name has to clear six bars. This document walks through each, with examples of names that pass and fail. + +A short-listable name passes all six. Most names fail at least one. The bar is necessarily high because a name lives forever. + +--- + +## 1. Pronounceable + +A name people cannot say will not get said. + +Pass: +- "Stripe" - one syllable, unambiguous +- "Notion" - two syllables, common word, clear stress +- "Loom" - one syllable, common phoneme + +Fail: +- "Xobni" (the X is silent? before the b? unclear) +- Names with non-English diacritics for an English-speaking market that get stripped to ambiguity +- "Yext" - is it "yext" with a hard Y or "ekst"? People disagree + +Test: Read the name aloud to 5 people who have not seen it written. If 3 of 5 pronounce it differently, fail. + +--- + +## 2. Spellable + +A name people cannot spell will not get found. + +Pass: +- "Asana" - phonetic, spelled exactly as it sounds +- "Patagonia" - long but predictable +- "Slack" - one syllable, common word + +Fail: +- "Häagen-Dazs" - even the inventors made it hard to spell on purpose +- Names with silent letters that are not standard English +- Names with "ee" / "ea" / "ie" ambiguity +- Names with double letters in unexpected places + +Test: Read the name aloud to 5 people. Ask them to spell it. If 2 of 5 misspell it, fail. + +--- + +## 3. Available + +A name you cannot legally use is not a candidate. + +Check, in this order: + +1. Trademark search in the relevant jurisdictions. Class matters - you can have the same name as another brand if you operate in different categories, but check. +2. Domain availability. The .com (or category-relevant TLD) for the exact name. Adjacent TLDs (.io, .co, .app) are weaker; .com is still default for most categories. +3. Social handles. Check the major platforms. Inconsistent handles fragment the brand. +4. Existing brands in the category. Even if trademark is technically clear, a confusable competitor name is a problem. +5. Negative associations. Search the name in quotes. See what shows up. + +Pass: +- A name with .com available, no conflicting trademark, clean handles across major platforms + +Fail: +- A name where the .com is parked at $50,000 and no budget exists +- A name that conflicts with a registered trademark in the same class +- A name that someone notable already uses on social platforms + +--- + +## 4. Distinctive + +A name that gets confused with competitors loses every benefit of being a name. + +Pass: +- "Stripe" in payments - distinct from PayPal, Square, Adyen +- "Notion" in productivity tools - distinct from Asana, Monday, Trello +- "Loom" in async video - distinct from Zoom, Vimeo, YouTube + +Fail: +- A name one letter different from a major competitor +- A name that rhymes with a major competitor +- A name from the same conceptual family (e.g., another fruit name in a market dominated by Apple) +- A name with words common in the category (e.g., "Pay" in fintech, "Code" in dev tools, "AI" in AI products) that gets lost in search + +Test: Search the name + category. If your name is buried under unrelated content or competitor confusion, fail. + +--- + +## 5. Stretchable + +A name that locks you into one product or category will hurt as you grow. + +Pass: +- "Amazon" - was a bookstore. Now sells everything. +- "Apple" - was a computer company. Now does phones, music, services. +- "Stripe" - "stripe of code" implied developer tools. Now does broader fintech. + +Fail: +- "TomatoTracker" - locked to tomatoes +- "PDFMonkey" - locked to PDFs +- Names that explicitly describe a single product feature, when the company plans to be more than that single feature + +Note: Locked-in names can be the right choice IF the company is committed to staying narrowly focused. "PDFMonkey" works if you genuinely just want to be the best PDF tool. The failure is when you outgrow the name and have to rebrand at scale. + +Test: Imagine the company in 5 years, expanded into adjacent categories. Does the name still fit? If not, plan for it. + +--- + +## 6. Free of negative associations + +A name that means something embarrassing in another language, or that already carries cultural baggage, will hit a ceiling. + +Check: + +- Translations. Run the name through a few major target market languages. Native speakers should review (translation tools miss nuance). +- Slang. Especially Gen Z and online slang shifts fast. A name that was clean five years ago may not be clean today. +- Acronyms. Some names form embarrassing acronyms when written in caps or in initialisms. +- Visual confusions. When written in certain fonts, do letters create unfortunate combinations? (Famous example: "kidsexchange" spelled as one word.) +- Existing pop culture. Is the name a character in a recent TV show, a banned topic, or a meme? + +Pass: +- Cleared in target markets, no recent cultural collisions, no embarrassing acronyms + +Fail: +- Names that translate to insults or anatomical terms in target markets +- Names that match recent meme content (the meme will fade but the association sticks) +- Names with unfortunate acronyms (e.g., "Strategic Health Initiative Team") + +Test: Native speakers in each target market review. Plus a 5-minute search of the name in pop culture context. + +--- + +## Scoring + +For each candidate name, score 1 to 5 on each of the six criteria, where 5 is "passes cleanly" and 1 is "definite fail." + +A name is short-listable if it scores 4 or 5 on every criterion. A 3 anywhere is a yellow flag (proceed with eyes open). A 2 or 1 anywhere is disqualifying. + +--- + +## Pragmatic notes + +- Domains: .com is still default for most US/global brands. Category-specific TLDs (.app, .ai, .io) work in some categories but require more brand investment to teach the audience. +- Trademark: Get a real attorney to clear the trademark before launch. The cost of a TM search is dramatically less than a rebrand. +- Generic names (descriptive of the category) cannot be trademarked and will struggle with distinctiveness. +- Made-up names are easier to clear and trademark but require more marketing investment to load with meaning. +- Founder names carry heritage but can complicate equity and exits. + +--- + +## When to walk away + +If the top 3 candidates all fail at least 2 criteria, the naming exploration was not deep enough. Generate another 30 to 50 candidates before settling. The cost of a bad name is paid every day for the life of the brand. diff --git a/skills/brand-identity/SKILL.md b/skills/brand-identity/SKILL.md new file mode 100644 index 0000000..f3a8ef8 --- /dev/null +++ b/skills/brand-identity/SKILL.md @@ -0,0 +1,203 @@ +--- +name: brand-identity +description: "Design or evaluate a brand visual identity system covering logo, color, typography, imagery direction, iconography, and motion principles. Use this skill whenever the user wants to design a logo, build a visual identity, define brand colors, choose brand typography, develop iconography, plan brand imagery, or evaluate an existing identity for cohesion. Triggers on logo design, brand identity, visual identity, brand mark, wordmark, monogram, color palette, brand colors, brand typography, type system, iconography, brand imagery, motion design, brand system, identity system. Also triggers when the user has a brand direction approved and now needs the visual artifacts that express it." +category: brand +catalog_summary: "Logo system, color, typography, imagery, iconography, motion" +display_order: 2 +--- + +# Brand Identity + +Design or evaluate the visual artifacts that express a brand: logo system, color, typography, imagery, iconography, and motion. Stack-agnostic. Tool-agnostic. + +This skill assumes a brand direction is already approved (positioning, mood, name). If not, run `brand-ideation` first. + +--- + +## When to use + +- Designing a logo system +- Defining a brand color palette +- Choosing brand typography +- Developing iconography or illustration style +- Defining imagery direction (photography, illustration) +- Establishing motion principles +- Auditing an existing identity for cohesion or gaps + +## When NOT to use + +- Brand direction is not yet defined (use `brand-ideation`) +- Documenting a finished system (use `brand-style-guide`) +- Defining voice and tone (use `brand-voice`) +- Building UI components from an existing brand (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- The brand name and approved positioning +- The mood direction (from ideation, or supplied as references) +- Audience and category context +- Application contexts (web, print, packaging, motion - whatever applies) +- Constraints (parent brand requirements, regulatory marks, accessibility minimums) + +--- + +## The framework: 5 elements + +A complete identity has five elements. Each element should reinforce the others. Inconsistency between them is the most common identity failure. + +### 1. Logo system + +Most brands need not one logo but a system of marks for different contexts. + +Components of a logo system: + +- Primary mark. The main logo. Used wherever there is room. +- Wordmark. Just the typography, no symbol. Used in tight horizontal contexts. +- Symbol or glyph. Just the symbol, no type. Used in app icons, favicons, social avatars. +- Lockup variations. Horizontal, stacked, square - whichever apply. +- Monogram. The initial(s) styled as a mark. Optional but useful for small contexts. + +Design principles: + +- Legible at 16 pixels. Test the logo at favicon size. If it falls apart, redesign. +- Reproducible in single-color. If the logo only works in full color, it cannot be screen-printed, embroidered, or rendered in browser favicons. +- Distinctive silhouette. Squint at it. Can you still tell what it is? If it looks like every other logo in the category at silhouette, redesign. +- Construction grid. Every curve and angle is intentional. Document the construction. + +Common failure: +- Designing only the primary mark and discovering at launch that the wordmark, glyph, and small-size variants do not exist. + +### 2. Color system + +A color system is more than a palette. It is the rules for how color carries meaning. + +Components: + +- Primary color. The signature color most associated with the brand. +- Secondary colors. 1 to 3 supporting colors that extend the palette. +- Neutrals. The grays and tints that make up most of the surface area. +- Semantic colors. Success, warning, error, info - if the brand operates in product UI. +- Accent colors. Used sparingly for highlight and emphasis. + +Per color, document: +- Hex, RGB, HSL, CMYK (if print is in scope), and Pantone (if brand-critical print exists) +- WCAG AA contrast against the other colors in the system +- Allowed and disallowed pairings (some brand colors look terrible together) +- Usage notes (when to use, when not to use) + +Design principles: + +- Test for accessibility. WCAG AA requires 4.5:1 contrast for normal text, 3:1 for large text. If the brand color cannot pass either against white, you have a problem. +- Test for color blindness. Around 8 percent of men have some form of color blindness. Critical UI signals should not rely on color alone. +- Define neutrals carefully. Neutrals are 80 percent of the surface area in most brand applications. They carry more weight than the brand color. +- Limit the palette. A 30-color palette is unmanageable. 5 to 8 carefully chosen colors beats a sprawling system. + +### 3. Typography + +Type is the second-most-recognizable element of a brand after the logo. + +Components of a type system: + +- Display typeface. For headlines and brand moments. +- Body typeface. For long-form reading. Often the same as display, sometimes different. +- Monospace typeface (if applicable for technical brands). +- Type scale. The set of sizes used across applications. Typically 5 to 8 steps. +- Type weights and styles. Which weights and italics are part of the system. + +Design principles: + +- Pairing. If using two typefaces, they must work together at body and display sizes. Common pattern: serif display + sans body, or geometric sans display + humanist sans body. +- Web licensing. Confirm web licensing covers expected pageviews. Some popular typefaces have prohibitive web licenses. +- Variable fonts are increasingly the right call for performance and flexibility. +- Fallback stack. Specify system fallbacks for when the brand font fails to load. The fallback should be visually similar. +- Open-source alternatives. Document open-source equivalents for situations where licensing is impractical (third-party tools, embedded contexts). + +### 4. Imagery and illustration + +Imagery direction is often underspecified, leading to brand drift over time. + +Photography direction: + +- Subject matter. What does the brand show? +- Composition style. Tight crops, wide environments, candid, posed? +- Lighting. Bright and natural, dramatic and directional, soft and diffused? +- Color treatment. True color, warm shifted, desaturated, high-contrast? +- What to reject. Stock photo aesthetics, specific cliches in the category. + +Illustration direction: + +- Style. Flat, dimensional, hand-drawn, geometric, abstract, representational? +- Color use. Full palette, restricted palette, brand colors only? +- Line treatment. Bold and outlined, soft and shaded, no outlines? +- Subject matter. What gets illustrated and what does not? + +Iconography: + +- Style. Filled or outline. Rounded or sharp. Single weight or variable. +- Grid. Pixel-perfect grid (often 24x24 or 16x16 base). +- Stroke weight. Consistent across the icon set. +- Set. Which icons exist, and how new icons get added consistently. + +### 5. Motion + +If the brand lives in any digital product, marketing video, or animated touchpoint, motion is part of the identity. + +Motion principles to define: + +- Easing curves. Default easings used across animations. Linear, ease-in-out, custom. +- Duration scale. Fast (100ms), medium (200-300ms), slow (500ms+) and when each applies. +- Choreography. How elements enter, exit, and respond to interaction. +- Brand moments. Signature animations (logo build, page transitions, loaders). + +Design principles: + +- Restraint. Most motion in product UI should be quick and subtle. Reserve dramatic motion for brand moments. +- Reduced motion. Always provide a `prefers-reduced-motion` alternative for users with vestibular sensitivities. +- Performance. Animations must be 60fps on the target devices. Profile before shipping. + +--- + +## Workflow + +1. Confirm brand direction. Positioning, mood, audience. If unclear, return to `brand-ideation`. +2. Audit applications. List every place the brand will appear (web, print, packaging, app, social, signage, video). The application contexts drive what the system needs to handle. +3. Element-by-element design. Start with logo and color, since these constrain typography. Then type. Then imagery, iconography, motion. +4. Stress-test. Apply the system to 3 to 5 mock applications (homepage, social post, business card, product UI, signage). Where does it break? Iterate. +5. Document. Each element with rules, examples, and dos/don'ts. This becomes the input to `brand-style-guide`. +6. Get sign-off before broad rollout. Identity changes after rollout are 10x the cost of changes during design. + +--- + +## Failure patterns + +- Designing logos in isolation from application. A logo that looks great on a hi-res mockup but illegible at favicon size is a design failure. +- Picking a brand color without contrast testing. A brand color that fails WCAG AA against white means UI built on the brand will be inaccessible by default. +- Specifying typography without checking web licensing. Discovering at deploy that the foundry charges per-pageview for the chosen typeface is a budget-buster. +- Skipping imagery direction. Without it, the brand becomes whatever stock photos the next person picks. +- Treating motion as decoration. Inconsistent motion erodes brand cohesion as fast as inconsistent color. +- Designing only primary states. What does the brand look like in error? In dark mode? In a localization where the wordmark needs to flip direction? These are not edge cases; they are the brand. + +--- + +## Output format + +Default output is a structured set of files: + +- `identity/logo/` - All logo variants (SVG primary, plus PNG/JPG exports at common sizes) +- `identity/colors.md` - Color system with hex codes, contrast ratios, usage rules +- `identity/typography.md` - Type system with scale, weights, fallbacks +- `identity/imagery.md` - Imagery direction with reference examples +- `identity/iconography/` - Icon set or icon style spec +- `identity/motion.md` - Motion principles +- `identity/applications/` - 3 to 5 application mockups stress-testing the system + +These feed directly into `brand-style-guide`. + +--- + +## Reference files + +- [`references/identity-system-spec.md`](references/identity-system-spec.md) - Detailed spec template for documenting each element. +- [`references/contrast-and-accessibility.md`](references/contrast-and-accessibility.md) - Accessibility checks for color and type, with the math. diff --git a/skills/brand-identity/references/contrast-and-accessibility.md b/skills/brand-identity/references/contrast-and-accessibility.md new file mode 100644 index 0000000..d0f964e --- /dev/null +++ b/skills/brand-identity/references/contrast-and-accessibility.md @@ -0,0 +1,188 @@ +# Contrast and Accessibility for Brand Identity + +A brand color choice that fails accessibility is a design defect. Every product, page, button, and label using that color inherits the failure. + +This reference walks through the math, the standards, and the practical implications. + +--- + +## The standards + +WCAG 2.1 AA is the minimum bar for most professional brand work. + +\| Element \| Required contrast ratio \| +\|---\|---\| +\| Normal body text \| 4.5:1 \| +\| Large text (18pt regular or 14pt bold) \| 3:1 \| +\| UI components and graphical elements \| 3:1 \| + +WCAG 2.1 AAA is stricter. Required for some accessibility-focused products, optional but admirable for most. + +\| Element \| Required contrast ratio \| +\|---\|---\| +\| Normal body text \| 7:1 \| +\| Large text \| 4.5:1 \| + +--- + +## The math + +Contrast ratio is calculated as: + +``` +(L1 + 0.05) / (L2 + 0.05) +``` + +Where L1 is the relative luminance of the lighter color and L2 of the darker. Relative luminance comes from a weighted formula on RGB values that accounts for human perception (green contributes more than blue). + +Quick contrast checker (run in browser console): + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + return ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2) + ':1'; +} + +// Example +contrast('#FFFFFF', '#4B5563'); // returns '6.40:1' +``` + +--- + +## Common brand color failures + +These are color choices that look great in a logo but fail WCAG when used for text or UI: + +\| Pairing \| Ratio \| Status \| +\|---\|---\|---\| +\| Light gray (#9CA3AF) on white \| 2.85:1 \| Fails AA \| +\| Bright yellow on white \| 1.07:1 \| Fails AAA, AA, and basic legibility \| +\| Bright orange (#FF9900) on white \| 2.14:1 \| Fails AA \| +\| Sky blue (#3B82F6) on white \| 4.57:1 \| Passes AA for normal text \| +\| Most "vibrant" brand reds on white \| 3-4.5:1 \| Borderline; check exact values \| +\| White text on bright orange \| 2.14:1 \| Fails AA \| + +When in doubt, darken the brand color for text contexts. Keep the original hue for non-text brand expressions (logos, large graphics, decorative elements). + +--- + +## The "darker variant" strategy + +For brand colors that fail AA contrast, define a darker variant for use in text and UI. + +``` +Brand orange (signature): #FF9900 (used in logos, illustrations, large graphics) +Brand orange (text/UI): #B86600 (passes AA against white) +``` + +Both are "the brand color." The signature version is what people associate with the brand. The text variant is what enables accessible UI without abandoning the identity. + +This is standard practice. Most major brands have both versions, even if only the signature version is publicized. + +--- + +## Color blindness considerations + +Around 8 percent of men and 0.5 percent of women have some form of color vision deficiency. The most common is red-green (deuteranopia and protanopia). + +Tests to run: + +- Red-green confusion. Greens and reds at similar luminance look the same to deuteranopes. If your success/error indicators rely on red-green distinction, add an icon or text label. +- Tritan simulation. Less common but worth checking. Blues and yellows. +- Greyscale conversion. Convert your palette to grayscale. If two brand colors look identical in greyscale, they will be hard to distinguish for people with severe color blindness. + +Tools: Stark plugin (Figma), Coblis (online simulator), Chrome DevTools rendering tab. + +Practical rule: Critical UI signals must communicate through more than just color. Use icons, labels, position, or shape as redundant signals. + +--- + +## Typography contrast + +Type contrast is not just about color. It includes: + +- Color contrast (per the standards above) +- Weight contrast (light text on a busy background fails even at high color contrast) +- Size contrast (very small text needs higher color contrast) + +Practical rules: + +- Body text: minimum 14px on web, ideally 16px. Below 14px is uncomfortable for most readers regardless of contrast. +- Body text on photographs or busy backgrounds: add a scrim, increase the type weight, or move the text. +- Light-weight fonts (Thin, Extra Light) for body text: avoid. They fail visual contrast even at passing color contrast. + +--- + +## Dark mode considerations + +Most brand colors that work on white do not work on dark backgrounds. + +Common failure: +- Brand color = dark navy. On white: 12:1 contrast (excellent). On near-black: 1.4:1 (terrible). + +Solutions: + +- Define light-mode AND dark-mode variants of every functional color in the system. +- Brand colors typically need to be lightened or desaturated in dark mode. +- Test the entire palette against both light and dark surfaces. + +``` +Brand navy: + Light mode (on white): #0F2A4A (12:1 contrast) + Dark mode (on #111): #6B9FE8 (5.2:1 contrast against #111) +``` + +Both are "the brand color." Both express the identity. They just live in different lighting conditions. + +--- + +## Icons and graphical elements + +WCAG requires 3:1 for UI components and graphical elements. This includes: + +- Icons used to convey meaning +- Form field borders +- Focus indicators +- Chart elements that distinguish data series +- Toggle and switch states + +Common failure: +- Light gray icon (#D1D5DB) on white background: 1.4:1. Invisible to users with low vision. +- Form field borders at #E5E7EB: 1.3:1. Borderline visible. + +Fix: +- Icons that convey meaning: minimum #6B7280 on white (3.9:1). +- Form field borders: minimum #9CA3AF on white (3.0:1) for default state. Stronger for focus. + +--- + +## Practical checklist for brand color decisions + +Before locking a brand color: + +- [ ] Tested against white at WCAG AA for body text (4.5:1) +- [ ] Tested against white at WCAG AA for large text (3:1) +- [ ] Tested against the brand's dark surface color (for dark mode) +- [ ] Tested for color blindness (deuteranopia simulation) +- [ ] A "darker variant" defined for text contexts if signature color fails AA +- [ ] White text on the brand color tested for 4.5:1 (for buttons and CTAs) +- [ ] All semantic colors (success, warning, error) pass AA on white and dark +- [ ] Neutrals scale tested across the full range + +If any check fails, document the failure and provide an alternative variant for the failing context. Do not just hope it will be fine in practice. It will not be fine. + +--- + +## Resources + +- WebAIM Contrast Checker (free, browser-based) +- Stark plugin for Figma +- Chrome DevTools accessibility panel +- Coblis color blindness simulator +- WCAG 2.1 specification at w3.org diff --git a/skills/brand-identity/references/identity-system-spec.md b/skills/brand-identity/references/identity-system-spec.md new file mode 100644 index 0000000..4b08849 --- /dev/null +++ b/skills/brand-identity/references/identity-system-spec.md @@ -0,0 +1,212 @@ +# Identity System Spec + +A spec template for documenting each element of the brand identity system. This is the working document during identity build, before the polished style guide. It locks decisions and exposes gaps. + +Fill every section. The point of the spec is to surface what is undecided. + +--- + +## System metadata + +Brand: [Name] +Version: [v1.0, v1.1, etc.] +Date: [YYYY-MM-DD] +Owner: [Name] +Status: [Draft / In review / Approved] + +--- + +## 1. Logo system + +### Primary logo + +- Form: [Wordmark / lettermark / combination mark / pictorial / abstract] +- Construction notes: [Geometry, custom letterforms, optical adjustments] +- Source files: [SVG, AI, layered] +- Color versions: [Full color, single color, reversed (white on dark)] +- Minimum size: [Pixels for digital, inches/mm for print] +- Clear space: [Minimum margin around logo, defined as multiple of a logo element, e.g., "1x cap height"] + +### Logo variants + +\| Variant \| When to use \| Source file \| +\|---\|---\|---\| +\| Horizontal \| Default \| \| +\| Stacked \| Constrained widths, social avatars \| \| +\| Mark only \| Favicons, app icons, watermarks \| \| +\| Wordmark only \| Inline text contexts \| \| + +### Misuse rules + +What never to do with the logo. Ten short rules at most. + +- Do not stretch +- Do not rotate +- Do not recolor outside the approved palette +- Do not place on busy photography without a scrim +- (etc.) + +### Application examples + +Where the logo lives. Document the canonical placements. + +- Web header: [Position, size, color treatment] +- Email signature: [Position, size] +- Favicon: [Variant used, sizes generated] +- App icon: [Variant, background, padding] +- Print: [Letterhead, business card] +- Social: [Avatar variant, banner specs] + +--- + +## 2. Color + +### Primary palette + +\| Token name \| Hex \| RGB \| HSL \| Usage \| +\|---\|---\|---\|---\|---\| +\| `color-brand-primary` \| \| \| \| Primary brand color, dominant in identity \| +\| `color-brand-secondary` \| \| \| \| Secondary brand color \| +\| `color-brand-tertiary` \| \| \| \| Optional accent \| + +### Neutrals + +\| Token name \| Hex \| Usage \| +\|---\|---\|---\| +\| `color-neutral-0` \| #FFFFFF \| Background, max contrast \| +\| `color-neutral-50` \| \| \| +\| `color-neutral-100` \| \| \| +\| `color-neutral-200` \| \| \| +\| ... \| \| \| +\| `color-neutral-900` \| \| \| +\| `color-neutral-1000` \| #000000 \| \| + +### Semantic tokens + +\| Token name \| Resolves to \| Usage \| +\|---\|---\|---\| +\| `color-text-primary` \| \| Body text \| +\| `color-text-secondary` \| \| Captions, less important text \| +\| `color-text-disabled` \| \| Disabled state \| +\| `color-text-inverse` \| \| Text on dark backgrounds \| +\| `color-bg-primary` \| \| Default background \| +\| `color-bg-elevated` \| \| Cards, modals \| +\| `color-border-default` \| \| Card borders, dividers \| +\| `color-success` \| \| \| +\| `color-warning` \| \| \| +\| `color-error` \| \| \| +\| `color-info` \| \| \| + +### Color rules + +- Never invent a new color. If a use case is not covered, propose a new token. +- Brand color contrast against approved backgrounds must meet WCAG AA for text. See `contrast-and-accessibility.md`. +- Dark mode tokens defined separately or via theme switch logic. + +--- + +## 3. Typography + +### Type families + +\| Role \| Family \| Weights used \| License \| +\|---\|---\|---\|---\| +\| Display \| \| \| \| +\| Body \| \| \| \| +\| Mono (code, data) \| \| \| \| + +### Type scale + +\| Token \| Size \| Line height \| Weight \| Use case \| +\|---\|---\|---\|---\|---\| +\| `text-display-1` \| \| \| \| Hero headline \| +\| `text-display-2` \| \| \| \| Section headline \| +\| `text-h1` \| \| \| \| Page title \| +\| `text-h2` \| \| \| \| Section title \| +\| `text-h3` \| \| \| \| Sub-section \| +\| `text-body-lg` \| \| \| \| Lead paragraph \| +\| `text-body` \| \| \| \| Default body \| +\| `text-body-sm` \| \| \| \| Caption, supporting text \| +\| `text-label` \| \| \| \| UI labels \| +\| `text-overline` \| \| \| \| Eyebrow text \| + +### Typography rules + +- Display weights only at display sizes. Do not use display weights for body. +- Body line height target 1.5 to 1.65 for readability. +- Line length target 50 to 75 characters per line. +- Avoid mixing more than two type families on a single page. + +--- + +## 4. Iconography + +- Style: [Outline / filled / mixed / two-tone] +- Stroke weight: [Specific px or em value] +- Corner radius: [Specific px] +- Grid: [24x24 default, with optional 16, 32, 48 sizes] +- Source: [Custom set / Lucide / Heroicons / Phosphor / Material] +- Naming convention: [`icon-[noun]-[modifier]`] +- License: [If using a third-party set] + +### Icon rules + +- Icons paired with labels by default. Icon-only buttons require an accessible label. +- Decorative icons get `aria-hidden="true"`. +- Functional icons inherit text color via `currentColor`. + +--- + +## 5. Imagery + +### Photography + +- Style: [Editorial / lifestyle / product / documentary / abstract] +- Color treatment: [Natural / treated / desaturated / signature filter] +- Composition: [Tight / wide / asymmetrical / symmetrical / negative space] +- Subject direction: [Demographics, environments, energy] + +### Illustration + +- Style: [If applicable - flat / textured / line / mixed] +- Color usage: [Limited palette / full palette] +- Pattern library: [Where it lives] + +### Stock and AI policy + +- Stock photography: [Allowed / banned / case-by-case with approval] +- AI-generated imagery: [Allowed / banned / case-by-case] +- Sources approved: [Specific platforms or studios] + +--- + +## 6. Motion + +- Default duration: [ms - typically 200-300] +- Default easing: [Standard easing curve, e.g., `cubic-bezier(0.4, 0, 0.2, 1)`] +- Token naming: [`motion-duration-fast`, `motion-easing-standard`] +- Reduced motion: [What animates becomes static when `prefers-reduced-motion: reduce`] + +--- + +## 7. Voice (cross-reference) + +Voice has its own deliverable. See the brand voice document. The identity spec only notes voice attributes that interact with visual identity (e.g., if voice is "quiet," typography should not be loud). + +--- + +## Open questions + +- [ ] [Token naming convention finalized?] +- [ ] [Dark mode strategy defined?] +- [ ] [Brand color WCAG contrast verified across approved backgrounds?] +- [ ] [Icon set licensed for production?] +- [ ] [Photography source defined?] + +--- + +## Sign-off + +- Design lead: [Name, date] +- Creative director: [Name, date] +- Engineering lead (for token implementability): [Name, date] diff --git a/skills/brand-style-guide/SKILL.md b/skills/brand-style-guide/SKILL.md new file mode 100644 index 0000000..a852bf3 --- /dev/null +++ b/skills/brand-style-guide/SKILL.md @@ -0,0 +1,202 @@ +--- +name: brand-style-guide +description: "Build or audit a comprehensive brand style guide that documents the full brand system including story, logo system, color, typography, imagery, voice, applications, and dos/don'ts. Use this skill whenever the user wants to create brand guidelines, document an existing brand, build a brand book, audit an existing style guide for completeness, or produce the artifact that other teams will reference for years. Triggers on style guide, brand guidelines, brand book, brand standards, brand manual, style sheet, brand documentation, brand reference. Also triggers when the brand identity is finished and needs to be documented for handoff to designers, developers, vendors, or future team members." +category: brand +catalog_summary: "The canonical reference document for the full brand system" +display_order: 3 +--- + +# Brand Style Guide + +Document the brand system so other people can use it without ambiguity. This is the artifact that lives longest. Designers, developers, agencies, and vendors will reference it for years. Build it like a reference manual, not a presentation. + +This skill assumes the brand identity is designed (run `brand-identity` first if not). The output of this skill is the canonical reference document. + +--- + +## When to use + +- Creating brand guidelines for a finished identity +- Documenting an existing brand that has no formal guide +- Auditing an existing style guide for gaps or inconsistencies +- Building a brand book to hand to vendors, partners, or new team members +- Updating a guide after a major brand evolution + +## When NOT to use + +- The brand identity is not yet designed (use `brand-identity`) +- Brand voice work specifically (use `brand-voice` for the voice doc, then integrate) +- Building UI components (use `design-standards` or `design-system`) + +--- + +## Required inputs + +- Finished brand identity (logo, colors, typography, imagery direction, motion principles) +- Brand voice and tone documentation (or sufficient inputs to write a voice section) +- Application examples that show the brand in real contexts +- Decisions on what is mandatory vs flexible vs forbidden + +--- + +## The framework: 8 sections + +A complete style guide has eight sections. Most guides skip 2 or 3 of them and create downstream confusion. Build all 8 from the start. + +### 1. Story +The narrative behind the brand. Why it exists, what it stands for, what it rejects. + +- Origin / founding story +- Mission and vision +- Values (3 to 5, with what each means in practice) +- Positioning statement +- Audience (with the level of specificity from the brief) +- What we are not (the things we explicitly reject) + +### 2. Logo system +Every variant of every mark, with rules. + +- Primary logo (with construction grid showing relationships) +- Wordmark +- Symbol / glyph +- Lockup variations (horizontal, stacked, etc.) +- Monogram (if part of system) +- Clear space rules (minimum spacing around logo) +- Minimum sizes (smallest acceptable size for print and digital) +- Acceptable color treatments (full color, single color, knock-out, reverse) +- Forbidden treatments (stretching, rotating, recoloring, drop shadows, gradients - whatever is forbidden) +- File formats and where to find them + +### 3. Color +The full color system with rules. + +- Primary palette (signature colors) +- Secondary palette +- Neutrals scale +- Semantic colors (success, warning, error, info) +- Light mode and dark mode variants +- Per color: hex, RGB, HSL, CMYK, Pantone (if print-relevant) +- Contrast ratios documented +- Allowed pairings +- Forbidden pairings +- Usage hierarchy (primary first, secondary supporting, neutrals dominant) + +### 4. Typography +The full type system. + +- Display typeface (with sample sizes) +- Body typeface (with sample sizes) +- Monospace (if applicable) +- Type scale (specific sizes used) +- Weight and style usage (which weights for which contexts) +- Line height ratios +- Letter spacing standards +- Web fallback stacks +- Open-source alternatives for licensing-restricted contexts +- Forbidden treatments (all caps overuse, fake italics, etc.) + +### 5. Imagery and illustration +What pictures look like in this brand. + +- Photography direction with example library +- Illustration style with example library +- Iconography system with the full icon set (or rules for adding to it) +- Forbidden imagery (stock photo cliches, specific things never to show) +- Photo treatment rules (color treatment, crops, composition) + +### 6. Voice and tone +How the brand sounds. (Pulled from `brand-voice` work if done separately.) + +- Voice attributes (3 to 5 adjectives with "we are X, not Y" framing) +- Tone shifts by context (onboarding, error, marketing, support, legal) +- Vocabulary preferences (words we use, words we avoid) +- Grammar and style rules +- Examples (good and bad copy side by side) + +### 7. Applications +The brand applied to real contexts. + +- Web (homepage, product pages, blog template) +- Email (template, signature, transactional) +- Social (post templates, profile imagery, story formats) +- Print (business cards, letterhead, print ads) +- Packaging (if applicable) +- Signage (if applicable) +- Internal documents (slides, reports, proposals) +- Each with examples showing what good looks like + +### 8. Dos and don'ts +The boundaries, illustrated. + +- Logo dos and don'ts (visual examples of correct and incorrect use) +- Color dos and don'ts (combinations to use, combinations to avoid) +- Type dos and don'ts (treatments to use, treatments to avoid) +- Composition dos and don'ts (layout patterns that work, ones that do not) +- Voice dos and don'ts (phrases that fit, phrases that do not) + +The dos and don'ts section is what people actually reference in practice. Make it the easiest section to scan. + +--- + +## Workflow + +1. Inventory the inputs. What identity work is finished? What voice work is finished? What is missing? +2. Confirm the format. Is this a PDF, a web page, a Notion doc, a printed book, or all of the above? Different formats have different production requirements. +3. Section by section, draft. Use the template in [`references/style-guide-template.md`](references/style-guide-template.md). +4. Stress-test with real examples. For every rule, find a real application example. Rules without examples get ignored. +5. Get review from the people who will use it. Designers, developers, marketers. They will surface gaps. +6. Version control. Style guides evolve. Date the doc. Note what changed in each version. +7. Publish in the format the team will actually open. A 200-page PDF that lives on a shared drive is dead weight. A web page or Figma file with a clear URL gets used. + +--- + +## Failure patterns + +- Skipping the "what we are not" sections. Without rejection rules, anything becomes acceptable. +- Document with no examples. Rules without visual examples are abstract and ignored. +- Document with only examples. Examples without rules cannot be applied to new situations. +- Static PDF that no one opens. Ship the guide in the format the team uses daily (web page, Figma, Notion, etc.). +- No version history. When the brand evolves, no one knows which rules changed or when. +- Aspirational rules. Rules the brand does not actually follow get treated as suggestions. Document what is actually true, not what is wished. +- Treating "dos and don'ts" as filler. This section is what people use most. Invest in it. + +--- + +## Output format + +Default output is a multi-section markdown document or a structured set of files, plus a presentation-ready version (web page, PDF, or Figma) for sharing with stakeholders. + +Recommended structure: + +``` +brand/ + style-guide.md (the canonical document) + story.md (or as a section) + logo/ + construction.md + files/ (SVG, PNG, etc.) + colors.md + typography.md + imagery/ + photography.md + illustration.md + icons/ + icons.md + files/ + voice.md + applications/ + web.md + email.md + social.md + print.md + dos-and-donts.md +``` + +For consumer-facing presentation, build a web page version that imports from these source files. The source files are canonical. The presentation is a view of them. + +--- + +## Reference files + +- [`references/style-guide-template.md`](references/style-guide-template.md) - Fillable section-by-section template. +- [`references/maintenance-playbook.md`](references/maintenance-playbook.md) - How to keep the guide current after launch. diff --git a/skills/brand-style-guide/references/maintenance-playbook.md b/skills/brand-style-guide/references/maintenance-playbook.md new file mode 100644 index 0000000..33e208d --- /dev/null +++ b/skills/brand-style-guide/references/maintenance-playbook.md @@ -0,0 +1,251 @@ +# Brand Style Guide Maintenance Playbook + +A style guide that does not get maintained becomes a museum piece within a year. This playbook covers who owns it, when it gets updated, and how change requests get handled. + +--- + +## Why guides decay + +The common failure modes: + +- No owner. The guide was a project deliverable. The team disbanded. No one maintains it. +- Drift. Real work in market diverges from the guide. The guide stops reflecting reality. +- Frozen in time. The guide was right at launch. Markets, products, and audiences moved. +- Locked away. The guide lives in a tool nobody opens. Teams reinvent rather than reference. +- Too rigid. The guide bans variation that real work demands. Teams ignore it rather than challenge it. + +The maintenance playbook addresses each of these. + +--- + +## Ownership + +### The owner + +Every brand guide has one owner. Not a committee. The owner: + +- Is named in the guide itself +- Has explicit authority to approve changes +- Has time allocated (typically 5-10% of one role) for guide upkeep +- Reports to a stakeholder who cares about brand consistency + +If the role is vacant, the guide is at risk regardless of how good the content is. + +### The guidance council (optional) + +For larger organizations, a small council reviews proposed changes before the owner approves. Typically: + +- Brand lead (chair) +- Design lead +- Marketing lead +- Engineering lead (if guide includes design tokens / dev assets) +- One product representative + +The council meets quarterly to review the change queue. + +--- + +## Change types and authority + +Not every change needs the same review. Define tiers. + +### Tier 1: clarifications (owner approves directly) + +- Typo fixes +- Adding examples to existing rules +- Improving wording without changing meaning +- Adding missing assets that are already approved (new logo file format, etc.) + +Process: owner ships within a week. + +### Tier 2: extensions (owner consults, then approves) + +- New use cases for existing elements +- New approved color combinations +- New typographic patterns within the existing scale +- New illustration or photography patterns within existing direction + +Process: owner posts to a working channel for 5-day comment period, addresses feedback, ships. + +### Tier 3: changes (council reviews, owner ships) + +- Modifying or expanding the color palette +- Modifying the type scale +- Adding or removing approved photographic styles +- Updating logo construction or variants +- Voice tone adjustments + +Process: RFC document, council review at quarterly meeting (or async if time-sensitive), then owner ships. + +### Tier 4: shifts (executive approval required) + +- Logo redesign +- Brand voice repositioning +- Color palette overhaul +- Naming or positioning changes + +Process: full brand project. Treat as a separate engagement, not a maintenance ticket. + +--- + +## Update cadence + +Even without inbound change requests, schedule reviews. + +\| Cadence \| What happens \| +\|---\|---\| +\| Monthly \| Owner sweeps the change queue, ships Tier 1 fixes, queues Tier 2 for the comment period. \| +\| Quarterly \| Council reviews Tier 3 RFCs, takes a sample-based audit (see below), updates roadmap. \| +\| Annually \| Full audit (see audit playbook), refresh of examples, prune of stale content, version bump. \| +\| As-needed \| Tier 4 shifts driven by business strategy. \| + +--- + +## Change request process + +Anyone in the organization can propose a change. The process: + +1. Submit via the request channel (template below). +2. Triage by owner within 5 business days. Assigns tier. +3. Comment / review depending on tier. +4. Decide. Approve, decline (with reason), or revise. +5. Ship. Update the guide, update related assets, communicate. +6. Communicate. Announce in the brand channel. Note in the changelog. + +### Request template + +``` +What is the change? +[One paragraph] + +Why is it needed? +[Real use case that surfaced this] + +What is affected? +[Pages, assets, components] + +Proposed solution +[Specific change to the guide] + +Alternatives considered +[Other ways to solve this] + +Requester +[Name, team] +``` + +--- + +## Audit cadence + +### Monthly: surface scan + +Owner scans 5-10 randomly selected production touchpoints (web pages, ads, emails, social posts) and notes any guide violations or undocumented patterns. 30 minutes max. + +The output is a row in a tracking sheet, not a deliverable. Used to surface drift trends. + +### Quarterly: sample audit + +Owner (or council) audits 20-30 production touchpoints across channels. Categorize each: + +- Compliant +- Minor deviation (acceptable, document if recurring) +- Major deviation (followup required) +- Undocumented pattern (consider adding to guide) + +Output: a one-page summary with action items. + +### Annual: full audit + +Use the audit template (typically a separate audit deliverable, not part of the guide itself). Full review across: + +- Logo usage +- Color +- Typography +- Imagery +- Voice and copy +- Motion and interaction +- Adoption (which teams use the guide vs work around it) + +Output: a backlog for the next year. + +--- + +## Versioning + +Use semantic versioning for the guide. + +- Major (1.0 → 2.0): brand shift. Logo redesign, voice repositioning, palette overhaul. +- Minor (1.1 → 1.2): new sections, expanded color or type, new approved patterns. +- Patch (1.1.1 → 1.1.2): clarifications, typo fixes, new examples. + +Each version has a changelog entry: what changed, who approved, when, and migration notes if any. + +### Backward compatibility window + +When a Tier 3 or Tier 4 change ships, set a deprecation window: + +- Tier 3: 90 days. Old patterns acceptable in production, new patterns required for new work. +- Tier 4: 6-12 months depending on production cycle (print catalogs, manufactured goods, regulatory deliverables may need longer). + +Document deprecated patterns with a clear "Replaced by [new pattern], deprecated as of [date], removal date [date]" note. + +--- + +## Communication + +When the guide changes, people need to know. + +### Channels + +- Brand channel: standing channel for all updates, requests, questions. +- Changelog page in the guide: running list of versioned changes. +- Quarterly digest email: roundup of the past quarter's changes, plus the audit summary. +- Annual review post: the year's biggest changes, the audit findings, the next year's priorities. + +### When to push, when to publish + +- Push (announce, require attention) for Tier 3 and Tier 4 changes. +- Publish (update the guide and the changelog, no broadcast) for Tier 1 and Tier 2. + +--- + +## Adoption health metrics + +The guide is healthy when teams use it. Track: + +\| Metric \| Healthy \| Warning \| Failing \| +\|---\|---\|---\|---\| +\| Average page views per month \| Steady or growing \| Declining \| Near-zero \| +\| Change requests per quarter \| 5-15 \| <3 \| 0 (or 50+) \| +\| Audit compliance score (Tier 3+) \| >90% \| 75-90% \| <75% \| +\| Percent of new launches that referenced the guide pre-launch \| >80% \| 50-80% \| <50% \| +\| Time to ship a clarification \| <1 week \| 1-4 weeks \| >4 weeks \| + +If multiple metrics are failing simultaneously, the guide needs a refresh, not just maintenance. + +--- + +## When to retire and rewrite + +Sometimes maintenance is not enough. Signs the guide needs a rewrite: + +- The brand has shifted enough that >30% of the guide no longer applies +- The audience or category has shifted enough that the brand position is dated +- A new owner cannot make sense of the structure +- The guide reads as if it was written for a different company +- Compliance has fallen below 60% across multiple audits + +Rewriting is not a maintenance task. It is a separate brand project. The maintenance playbook ends when the rewrite begins. + +--- + +## Sign-off + +Maintenance plan accepted by: + +- Brand owner: [Name, date] +- Council members: [Names, date] +- Executive sponsor: [Name, date] + +Next quarterly review: [Date] diff --git a/skills/brand-style-guide/references/style-guide-template.md b/skills/brand-style-guide/references/style-guide-template.md new file mode 100644 index 0000000..a55b540 --- /dev/null +++ b/skills/brand-style-guide/references/style-guide-template.md @@ -0,0 +1,407 @@ +# [Brand Name] Style Guide + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Maintained by: [Team or person] +Format: This document is canonical. Other formats (PDF, web page, Figma) are views of this document. + +--- + +## How to use this guide + +[1 to 2 paragraphs explaining what the guide is for, who it serves, and where to go with questions.] + +Quick links: +- [Logo files](#logo-files) +- [Color values](#color-values) +- [Typography](#typography) +- [Voice cheat sheet](#voice) +- [Dos and don'ts](#dos-and-donts) + +--- + +## 1. Story + +### Origin +[1 to 3 paragraphs. Why this brand exists. The problem it solves. The moment it began.] + +### Mission +[One sentence. What we are trying to do in the world.] + +### Vision +[One sentence. The future we are pulling toward.] + +### Values + +We hold [N] values. + +[Value 1] +[What it means in practice. 2 to 3 sentences. Include a behavioral example.] + +[Value 2] +[Same structure.] + +[Value 3] +[Same structure.] + +### Positioning + +[The positioning statement. One paragraph. What we offer, to whom, and what makes us different.] + +### Audience + +Primary: [Who, with specificity] + +Secondary: [Who, briefly] + +Anti-personas: [Who we are not for] + +### What we are not + +- [Thing we explicitly reject] +- [Thing we explicitly reject] +- [Thing we explicitly reject] + +--- + +## 2. Logo system + +### Primary logo + +[Image of primary logo] + +[Description: what it is, what it represents, when to use it.] + +### Wordmark + +[Image of wordmark] + +[Description and usage.] + +### Symbol / glyph + +[Image of glyph] + +[Description and usage.] + +### Lockup variations + +[Images of horizontal, stacked, square variants.] + +### Construction + +[Image showing construction grid, proportions, key relationships.] + +### Clear space + +[Image showing minimum clear space around the logo.] + +The logo requires minimum clear space equal to [X] on all sides. + +### Minimum sizes + +\| Format \| Minimum size \| +\|---\|---\| +\| Digital primary \| [Xpx] wide \| +\| Print primary \| [Xmm] wide \| +\| Favicon \| [Xpx] \| +\| Mobile \| [Xpx] \| + +### Color treatments + +Allowed: +- Full color on white +- Full color on light backgrounds (with [contrast rule]) +- Single color on light backgrounds +- White (knockout) on dark backgrounds +- Single color black + +Forbidden: +- [Specific forbidden treatment with example image] +- [Specific forbidden treatment with example image] + +### Logo files + +\| File \| Use case \| Path \| +\|---\|---\|---\| +\| logo-primary.svg \| Web primary \| /brand/logo/primary.svg \| +\| logo-wordmark.svg \| Tight horizontal \| /brand/logo/wordmark.svg \| +\| logo-symbol.svg \| App icon, favicon \| /brand/logo/symbol.svg \| +\| logo-monogram.svg \| Tiny contexts \| /brand/logo/monogram.svg \| +\| [more files] \| \| \| + +--- + +## 3. Color + +### Primary palette + +\| Name \| Hex \| RGB \| Use \| +\|---\|---\|---\|---\| +\| [Name] \| #XXXXXX \| (R,G,B) \| [Use case] \| +\| [Name] \| #XXXXXX \| (R,G,B) \| [Use case] \| + +### Secondary palette + +[Same table structure] + +### Neutrals + +[Same table structure] + +### Semantic colors + +\| Name \| Hex \| Use \| +\|---\|---\|---\| +\| Success \| #XXXXXX \| Positive states, confirmations \| +\| Warning \| #XXXXXX \| Caution, attention needed \| +\| Error \| #XXXXXX \| Errors, destructive actions \| +\| Info \| #XXXXXX \| Neutral information \| + +### Dark mode variants + +\| Color \| Light mode \| Dark mode \| +\|---\|---\|---\| +\| Brand primary \| #XXXXXX \| #XXXXXX \| +\| Body text \| #XXXXXX \| #XXXXXX \| +\| Surface \| #FFFFFF \| #XXXXXX \| + +### Contrast ratios + +[For each meaningful pairing, document the ratio and pass/fail.] + +\| Pairing \| Ratio \| WCAG \| +\|---\|---\|---\| +\| Brand primary on white \| X.X:1 \| Pass AA / Pass AAA \| +\| Body text on white \| X.X:1 \| Pass AA \| + +### Allowed pairings + +[List or visual showing which colors work together.] + +### Forbidden pairings + +[List or visual showing combinations not to use.] + +--- + +## 4. Typography + +### Display typeface + +[Typeface name] + +[Sample at large size] + +Used for: [Headlines, hero copy, brand moments] + +Weights used: [list] + +### Body typeface + +[Typeface name] + +[Sample at body size] + +Used for: [Long-form reading, paragraphs] + +Weights used: [list] + +### Monospace (if applicable) + +[Typeface name] + +Used for: [Code, technical data] + +### Type scale + +\| Step \| Size \| Weight \| Line height \| Letter spacing \| Use \| +\|---\|---\|---\|---\|---\|---\| +\| Display 1 \| 64 \| 700 \| 1.0 \| -0.02em \| Hero headlines \| +\| Display 2 \| 48 \| 700 \| 1.05 \| -0.01em \| Section headers \| +\| H1 \| 36 \| 700 \| 1.1 \| 0 \| Page titles \| +\| H2 \| 28 \| 600 \| 1.2 \| 0 \| Section titles \| +\| H3 \| 22 \| 600 \| 1.3 \| 0 \| Sub-sections \| +\| Body Large \| 18 \| 400 \| 1.5 \| 0 \| Lead paragraphs \| +\| Body \| 16 \| 400 \| 1.6 \| 0 \| Default body \| +\| Small \| 14 \| 400 \| 1.5 \| 0 \| Captions, metadata \| +\| Caption \| 12 \| 400 \| 1.4 \| 0.01em \| Footnotes, labels \| + +### Web fallback stack + +``` +font-family: '[Brand display]', '[OS fallback 1]', '[OS fallback 2]', sans-serif; +``` + +### Open-source alternatives + +For contexts where the licensed brand fonts are impractical (third-party tools, embeds), use: + +- Display alternative: [Open-source typeface name] +- Body alternative: [Open-source typeface name] + +### Forbidden treatments + +- [No fake italics] +- [No fake bold] +- [No all-caps body text] +- [Other forbidden treatments] + +--- + +## 5. Imagery and illustration + +### Photography + +Subject matter: [What we photograph] + +Style: [Composition, lighting, color treatment] + +What we reject: [Stock photo aesthetics, specific cliches] + +Examples: +[Include 4 to 6 example images] + +### Illustration + +Style: [Description] + +Color use: [Rules] + +Examples: +[Include 4 to 6 example illustrations] + +### Iconography + +Style: [Filled / outline / mixed] + +Grid: [Base grid size] + +Stroke weight: [Specification] + +Set: +[Include the icon set or rules for adding new icons] + +--- + +## 6. Voice and tone + +### Voice attributes + +We sound: [adjective], [adjective], [adjective], [adjective], [adjective]. + +We do not sound: [opposite], [opposite], [opposite], [opposite], [opposite]. + +\| We are \| We are NOT \| +\|---\|---\| +\| [Adjective] \| [What it could tip into] \| +\| [Adjective] \| [What it could tip into] \| +\| [Adjective] \| [What it could tip into] \| + +### Tone shifts + +\| Context \| Tone \| +\|---\|---\| +\| Onboarding \| [Description] \| +\| Error states \| [Description] \| +\| Success states \| [Description] \| +\| Marketing \| [Description] \| +\| Support \| [Description] \| +\| Legal \| [Description] \| + +### Vocabulary preferences + +Use: [Words and phrases that fit] + +Avoid: [Words and phrases that do not fit] + +### Sample copy + +Bad (off-voice): +> [Example] + +Good (on-voice): +> [Example] + +--- + +## 7. Applications + +### Web + +[Show 2 to 3 example layouts: homepage, product page, blog template] + +### Email + +[Show template, signature, transactional examples] + +### Social + +[Show post templates, profile imagery, story formats] + +### Print (if applicable) + +[Show business cards, letterhead, print examples] + +### Packaging (if applicable) + +[Show packaging examples] + +### Internal documents + +[Show slide template, report template, proposal template] + +--- + +## 8. Dos and don'ts + +### Logo + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example with caption] \| [Visual example with caption] \| +\| \| \| + +### Color + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Type + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Composition + +\| Do \| Don't \| +\|---\|---\| +\| [Visual example] \| [Visual example] \| +\| \| \| + +### Voice + +\| Do \| Don't \| +\|---\|---\| +\| "[Example phrase]" \| "[Example phrase]" \| +\| \| \| + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial publication \| + +--- + +## Contact + +Questions or requests for clarification: [contact info] + +To suggest changes: [process] diff --git a/skills/brand-voice/SKILL.md b/skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b5c55f1 --- /dev/null +++ b/skills/brand-voice/SKILL.md @@ -0,0 +1,193 @@ +--- +name: brand-voice +description: "Develop or document a complete brand voice and tone system covering voice attributes, tone shifts by context, vocabulary preferences, grammar rules, and copy examples. Use this skill whenever the user wants to define how a brand sounds, write a voice and tone document, audit existing copy for voice consistency, train a team or AI assistant on brand voice, or refine the personality of brand writing. Triggers on brand voice, voice and tone, tone of voice, writing voice, brand personality, copy voice, voice document, voice guidelines, how should we write, voice training, voice audit. Also triggers when the user has copy that 'feels off' and the underlying issue is voice, even if not stated explicitly." +category: brand +catalog_summary: "Voice attributes, tone shifts, vocabulary, paired-example library" +display_order: 4 +--- + +# Brand Voice + +Define how a brand sounds in writing. Document it in a way that anyone (writer, designer, founder, AI assistant) can apply it consistently. + +This skill produces a standalone voice document that can either live in the brand style guide or feed into it. + +--- + +## When to use + +- Defining brand voice for the first time +- Auditing existing copy for voice consistency +- Training a team, freelancer, or AI assistant on the brand voice +- Refining a voice that exists but is inconsistent across applications +- Adapting voice when a brand evolves (new audience, new positioning) + +## When NOT to use + +- Writing specific copy (use `content-and-copy`) +- Brand visual identity work (use `brand-identity`) +- Documenting a complete brand system (use `brand-style-guide`, which incorporates voice) +- Initial brand exploration (use `brand-ideation`) + +--- + +## Required inputs + +- The brand and its positioning +- The audience and what they need to hear +- 5 to 10 examples of existing brand writing (if any) +- 3 to 5 reference brands whose voice resonates with where this brand should go +- Any voice attributes already specified in the brief + +--- + +## The framework: 4 layers + +Voice has four layers, stacked. Each layer constrains the one below it. + +### Layer 1: Voice attributes + +The constants. The personality traits that define how the brand sounds across every context. + +Pick 3 to 5 attributes. Pair each with what it is NOT (the failure mode if overdone). + +Common attribute pairings (NOT a menu - generate your own): + +- Confident, not arrogant +- Direct, not blunt +- Warm, not saccharine +- Witty, not sarcastic +- Smart, not academic +- Honest, not harsh +- Playful, not silly +- Practical, not boring +- Bold, not loud +- Curious, not unfocused + +The "not" half is what saves writers from overshooting. "Confident" alone produces swagger. "Confident, not arrogant" tells writers where the line is. + +### Layer 2: Tone shifts + +Voice is constant. Tone adapts to context. + +Map the major contexts the brand writes in. For each, document how voice expresses differently. + +Common contexts: + +\| Context \| Tone shift \| +\|---\|---\| +\| Onboarding \| Warmer, more enthusiastic, slightly slower pace \| +\| Hero / marketing \| Confident, signature voice fully on \| +\| Product copy / UX \| Direct, helpful, brief \| +\| Error messages \| Calm, matter-of-fact, no apology theater \| +\| Success states \| Brief celebration, redirect to next action \| +\| Empty states \| Helpful, slightly playful, suggest action \| +\| 404 / not found \| Self-aware, light, points the way home \| +\| Account deletion / cancellation \| Quiet, respectful, no jokes \| +\| Pricing \| Direct, transparent, confidence-inspiring \| +\| Legal / TOS \| Plain language version sits next to the legal version \| +\| Support / help center \| Patient, thorough, no condescension \| +\| Crisis communication \| Calm, factual, accountable \| +\| Product announcements \| Excited but not breathless \| +\| Email subject lines \| Specific, never click-bait \| + +Voice stays consistent across all of these. Tone is what shifts. + +### Layer 3: Vocabulary and grammar + +The granular dial settings. + +Vocabulary preferences: + +- Words and phrases the brand uses +- Words and phrases the brand avoids +- Words the brand has redefined (if any) - e.g., a SaaS product calling its features "huddles" instead of "meetings" +- Industry jargon: keep it (signals expertise) or strip it (signals approachability) +- Sentence-opening preferences (some brands lean on imperatives, some on questions, some on statements) + +Grammar and style: + +- Contractions (use them = casual, avoid them = formal) +- Sentence length default (short = punchy, medium = considered, long = literary) +- Punctuation marks favored or avoided (em dash is famously polarizing) +- Pronouns ("we" / "you" / "I") +- Capitalization style (title case, sentence case, all-lowercase deliberate) +- Number formatting (spell out under ten, or always digits) +- Oxford comma (use or skip) +- Active vs passive voice (most brands prefer active) + +### Layer 4: Examples and patterns + +Voice is taught through examples, not rules. Build a library. + +For each major content type, show: + +- Bad example (off-voice) +- Good example (on-voice) +- Brief note on what changed + +Common content types to cover: + +- Headline +- Subheadline +- Hero CTA +- Feature description +- Testimonial intro +- Email subject line +- Email opening +- Push notification +- Error message +- Success message +- About page paragraph +- Social post +- Sales page paragraph + +Aim for 15 to 25 paired examples. This is the most-used part of the voice doc in practice. + +--- + +## Workflow + +1. Audit existing copy if it exists. Identify what is on-brand, what is off, what patterns recur. +2. Layer 1: Voice attributes. Generate 5 to 8 candidates with "we are X, not Y" framing. Pick 3 to 5. +3. Layer 2: Tone shifts. List 8 to 15 contexts the brand writes in. Note the tone shift for each. +4. Layer 3: Vocabulary and grammar. Define preferences. Skip default rules unless they actually distinguish the brand. +5. Layer 4: Examples. Build the paired-example library. 15 to 25 minimum. +6. Stress-test. Pick a fresh writing brief and apply the voice doc. Does it produce on-voice copy? If not, the doc is incomplete. +7. Document. Use the template in [`references/voice-document-template.md`](references/voice-document-template.md). +8. Distribute. Voice docs only work if they get used. Make the doc easy to reference inline (link to it from CMS templates, brief templates, AI assistant prompts). + +--- + +## Failure patterns + +- Generic attributes ("friendly, professional, approachable"). Every brand says this. Means nothing. Pick attributes that genuinely distinguish. +- No "we are NOT" pairings. Without the rejection, attributes drift toward extremes. +- Voice doc with no examples. Rules without examples cannot be applied. +- Examples that are obviously bad and obviously good. Real voice work shows nuanced shifts, not cartoonish before/after. +- Skipping tone shifts. Treating voice as one-size-fits-all leads to a brand that sounds wrong in error states or legal contexts. +- Documenting aspirational voice. If the brand does not actually sound this way today and has no plan to shift, the doc is fiction. +- Voice without distribution. A perfect doc that no one references is worth nothing. + +--- + +## Output format + +Default output is a markdown document at `voice.md` in the brand folder. Sections: + +1. Voice attributes (with we-are-not pairings) +2. Tone shifts by context +3. Vocabulary preferences +4. Grammar and style rules +5. Paired examples library (the most-used section) +6. Anti-patterns (specific phrases or constructions to avoid) +7. References (the brands and writers we are inspired by) + +This doc can stand alone or feed into `brand-style-guide`. + +--- + +## Reference files + +- [`references/voice-document-template.md`](references/voice-document-template.md) - Fillable template. +- [`references/voice-frameworks.md`](references/voice-frameworks.md) - Detailed walkthrough of the Nielsen Norman 4 dimensions, Jung archetypes, and the "we are X not Y" approach. diff --git a/skills/brand-voice/references/voice-document-template.md b/skills/brand-voice/references/voice-document-template.md new file mode 100644 index 0000000..b0362e1 --- /dev/null +++ b/skills/brand-voice/references/voice-document-template.md @@ -0,0 +1,324 @@ +# [Brand Name] Voice and Tone + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Maintained by: [Team or person] + +--- + +## How to use this doc + +[1 to 2 paragraphs. Who this is for, when to reference it, where to ask questions.] + +For most writers, the section that gets used most is the paired examples library at the end. When unsure how to write something, find the closest example and pattern-match. + +--- + +## Voice attributes + +We sound: + +- [Adjective 1], not [opposite] +- [Adjective 2], not [opposite] +- [Adjective 3], not [opposite] +- [Adjective 4], not [opposite] +- [Adjective 5], not [opposite] + +### What each attribute means + +[Adjective 1] +[2 to 3 sentences. What this looks like in practice. Include one specific example phrase.] +Failure mode: when [Adjective 1] tips into [opposite], we sound [bad outcome]. + +[Adjective 2] +[Same structure.] + +[Adjective 3] +[Same structure.] + +[Adjective 4] +[Same structure.] + +[Adjective 5] +[Same structure.] + +--- + +## Tone shifts by context + +Voice stays constant. Tone adjusts based on what the user is doing and feeling. + +\| Context \| Tone \| +\|---\|---\| +\| Hero / marketing \| [How tone shifts] \| +\| Onboarding \| [How tone shifts] \| +\| Product copy / UX labels \| [How tone shifts] \| +\| Empty states \| [How tone shifts] \| +\| Error messages \| [How tone shifts] \| +\| Success states \| [How tone shifts] \| +\| 404 / not found \| [How tone shifts] \| +\| Account deletion / cancellation \| [How tone shifts] \| +\| Pricing \| [How tone shifts] \| +\| Legal / TOS \| [How tone shifts] \| +\| Support / help center \| [How tone shifts] \| +\| Crisis communication \| [How tone shifts] \| +\| Email subject lines \| [How tone shifts] \| +\| Social posts \| [How tone shifts] \| + +--- + +## Vocabulary preferences + +### Words and phrases we use + +[Bulleted list of vocabulary that fits the brand. Be specific.] + +- [Word or phrase] +- [Word or phrase] +- [Word or phrase] + +### Words and phrases we avoid + +[Bulleted list of vocabulary that does not fit. Often these are category cliches or fluff words.] + +- [Word or phrase] - [optional note on why] +- [Word or phrase] +- [Word or phrase] + +### Redefined words (if any) + +If the brand uses standard words in non-standard ways, document here. + +\| Standard term \| We say \| Why \| +\|---\|---\|---\| +\| [Standard] \| [Our term] \| [Reasoning] \| + +### Industry jargon + +We [keep / strip] industry jargon. [1 to 2 sentences explaining the call.] + +--- + +## Grammar and style + +\| Decision \| Our standard \| +\|---\|---\| +\| Contractions \| [Use / avoid] \| +\| Default sentence length \| [Short / medium / long] \| +\| Em dashes \| [Use / avoid] \| +\| Oxford comma \| [Yes / no] \| +\| Pronouns \| [we / you / I patterns] \| +\| Capitalization (headlines) \| [Title / sentence / lowercase] \| +\| Numbers under 10 \| [Spell out / digits] \| +\| Active vs passive \| [Active default] \| +\| Hashtags (in social) \| [In body / in comment / not used] \| +\| Exclamation points \| [Frequency rule] \| +\| Emoji \| [Use / avoid / context-specific] \| + +--- + +## Paired examples library + +The most-used part of this doc. When in doubt, find the closest example and pattern-match. + +### Headlines + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +[Brief note on what changed and why.] + +--- + +### Subheadlines + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Hero CTA + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Feature description + +Off-voice: +> [Bad example, 2 to 3 sentences] + +On-voice: +> [Good example, 2 to 3 sentences] + +--- + +### Testimonial intro + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Email subject line + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Email opening + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Push notification + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Error message + +Off-voice: +> "An error has occurred. Please try again later." + +On-voice: +> [Good example specific to this brand] + +--- + +### Success message + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Empty state + +Off-voice: +> "No items found." + +On-voice: +> [Good example specific to this brand] + +--- + +### About page paragraph + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Social post + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### Sales page paragraph + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +### 404 page + +Off-voice: +> "404. Page not found." + +On-voice: +> [Good example specific to this brand] + +--- + +### Cancellation flow copy + +Off-voice: +> [Bad example] + +On-voice: +> [Good example] + +--- + +## Anti-patterns + +Specific phrases or constructions that NEVER appear in our writing: + +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] +- [Anti-pattern, with a brief example] + +--- + +## References + +Brands and writers whose voice we admire and learn from: + +- [Brand or writer] - [What we learn from them] +- [Brand or writer] - [What we learn from them] +- [Brand or writer] - [What we learn from them] + +We are not copying these voices. We are calibrating against them. + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial publication \| + +--- + +## How to evolve this doc + +[1 paragraph on how the team proposes voice updates, who reviews, who approves.] + +Voice should be reviewed: +- Annually as a minimum +- After any major audience shift +- After any major positioning change +- When it consistently fails the "stress test" (writing produced from this doc no longer feels right) diff --git a/skills/brand-voice/references/voice-frameworks.md b/skills/brand-voice/references/voice-frameworks.md new file mode 100644 index 0000000..8d57718 --- /dev/null +++ b/skills/brand-voice/references/voice-frameworks.md @@ -0,0 +1,188 @@ +# Voice Frameworks + +Three established frameworks for thinking about brand voice. Each emphasizes a different layer. Mix and match. None is "right." Each is a tool. + +--- + +## Framework 1: The "We are X, not Y" approach + +The most pragmatic framework. Start here if you have not done voice work before. + +### How it works + +Pick 3 to 5 voice attributes. For each, name what the attribute is NOT. The pairing is the framework. + +``` +We are confident, not arrogant. +We are direct, not blunt. +We are warm, not saccharine. +We are smart, not academic. +``` + +### Why the "not Y" matters + +Single-word attributes are aspirational. They float. Without a counterweight, writers (and AI assistants) overshoot. + +- "Confident" alone = swagger, bravado, dismissiveness +- "Direct" alone = curtness, coldness, rudeness +- "Warm" alone = mushy, performative, over-friendly +- "Smart" alone = jargon-heavy, exclusionary + +Each "not Y" tells the writer where the line is. It is the guardrail. + +### Picking attributes + +Avoid generic words every brand claims. "Friendly," "professional," "approachable," "trustworthy," "innovative" are filler. They do not distinguish. + +Better attributes are specific enough to make some other brand a bad fit. If you can imagine your competitor saying the same word, the word is too generic. + +A good list: +- Distinctive (no other brand in your category would put it the same way) +- Honest (you actually sound this way, or are committed to) +- Useful (writers can apply it to a real piece of copy) +- Limited (3 to 5 attributes; 8+ becomes unworkable) + +### Stress test + +Take a recent piece of copy. Score it 1 to 5 against each attribute. If it scores below 3 on any, the copy is off-voice. If it scores 5 across the board, the attributes might be too generous. + +Apply the test to a competitor's copy. If their copy scores high on your attributes, the attributes are not distinctive enough. + +--- + +## Framework 2: The Nielsen Norman 4 dimensions + +Nielsen Norman Group introduced a model that treats voice as four sliders rather than a list of adjectives. + +### The 4 sliders + +1. Funny vs serious +Where on the spectrum from playful to earnest does the brand sit? + +- Far funny: jokes are signature, even in support content +- Mid: occasional wit, mostly straightforward +- Far serious: humor is rare and only when context invites it + +2. Formal vs casual +How structured and decorous is the writing? + +- Far formal: full sentences, correct grammar, no contractions, professional register +- Mid: standard professional, occasional contractions +- Far casual: contractions, fragments, conversational rhythms, slang where appropriate + +3. Respectful vs irreverent +Does the brand treat its audience and category with deference, or does it poke fun? + +- Far respectful: customers are addressed with care, category is treated with seriousness +- Mid: respectful default, willing to be playful at edges +- Far irreverent: category cliches get punctured, the brand is willing to mock conventions (its own and competitors') + +4. Matter-of-fact vs enthusiastic +What is the energy level? + +- Far matter-of-fact: calm, even, measured +- Mid: warm but not effusive +- Far enthusiastic: animated, expressive, energetic + +### How to use + +Plot the brand on each of the four. The position is the brand's voice signature. + +Example: +- Funny vs serious: 30 (mostly serious, occasional dryness) +- Formal vs casual: 70 (mostly casual, contractions standard) +- Respectful vs irreverent: 40 (respectful default, willing to be playful) +- Matter-of-fact vs enthusiastic: 50 (warm but measured) + +This produces a recognizable signature distinct from competitors plotted on the same axes. + +### Why this framework + +It forces choices. Adjective lists let you claim "warm AND professional AND witty AND smart." The dimensions force you to commit to a position, which is what voice actually is. + +### When to use it + +Best as a complement to the "We are X, not Y" approach. Use the dimensions to plot the brand. Use the attributes to give writers actionable language. + +--- + +## Framework 3: Brand archetypes (the Jung-derived model) + +A model from depth psychology, applied to brands by Margaret Mark and Carol Pearson. Twelve archetypes, each with a recognizable voice pattern. + +### The 12 archetypes + +\| Archetype \| Voice signature \| Example brands (illustrative, not endorsements) \| +\|---\|---\|---\| +\| Innocent \| Pure, optimistic, simple \| Wholesome consumer brands, family-oriented \| +\| Sage \| Wise, considered, knowledgeable \| Educational publishers, research institutions \| +\| Explorer \| Adventurous, free, restless \| Outdoor brands, travel platforms \| +\| Outlaw \| Rebellious, defiant, anti-establishment \| Disruptors, challenger brands \| +\| Magician \| Visionary, transformative, mystical \| Tech that "changes everything" \| +\| Hero \| Brave, decisive, achievement-oriented \| Athletic brands, ambitious tools \| +\| Lover \| Sensual, intimate, devoted \| Premium consumer goods, luxury \| +\| Jester \| Playful, irreverent, lighthearted \| Entertainment, fast food, fun-first \| +\| Everyman \| Down-to-earth, relatable, fair \| Mass market, "for everyone" \| +\| Caregiver \| Compassionate, generous, protective \| Healthcare, family services \| +\| Ruler \| Authoritative, sophisticated, in-control \| Premium brands, enterprise \| +\| Creator \| Imaginative, expressive, original \| Creative tools, artistic brands \| + +### How to use + +Pick a primary archetype. Optionally a secondary. The combination is the voice signature. + +A brand might be primary Sage with secondary Caregiver. That voice is wise + protective. It would write differently than a Sage + Outlaw (wise + defiant). + +### Strengths + +- Forces a clear voice character rather than a list of adjectives +- The archetypes are recognizable, which helps writers visualize the voice +- Distinguishes brands that might otherwise sound similar + +### Weaknesses + +- Some archetypes are dated or culturally specific +- "Pick one" is harder than it sounds; brands often span 2 or 3 +- Easy to pick aspirational archetypes the brand does not actually live + +### When to use it + +When the brand has a distinctive personality you want to crystallize. Less useful for utilitarian or category-defining brands. + +--- + +## Combining frameworks + +The three frameworks are not mutually exclusive. They emphasize different layers. + +A useful combination: + +1. Archetype for the high-level character +2. NN/g dimensions for the calibration +3. "We are X, not Y" attributes for the daily writing guardrails + +Example for a fictional brand: + +- Archetype: Sage (primary) + Everyman (secondary) +- Dimensions: 30 funny / 60 casual / 50 respectful / 40 enthusiastic +- Attributes: + - Knowledgeable, not academic + - Plain-spoken, not basic + - Honest, not harsh + - Patient, not condescending + +Each layer adds resolution. The archetype gives character. The dimensions give calibration. The attributes give writers the daily tool. + +--- + +## Choosing a framework + +If you have done voice work before and know what you want, the "We are X, not Y" approach alone is enough. + +If the brand voice is undefined and you need to start from zero, begin with archetypes (high-level character), move to dimensions (calibration), then derive attributes (daily guardrails). + +If voice work has been done but is too vague, the dimensions framework is the best clarifier. + +If voice has been documented but writers do not know how to apply it, the attributes framework is the missing piece. + +The frameworks are tools. The output of voice work is consistent writing across the brand. If the writing is consistent, the framework worked. If it is not, no framework is the right one yet. diff --git a/skills/calculator-design/SKILL.md b/skills/calculator-design/SKILL.md new file mode 100644 index 0000000..a9be8c1 --- /dev/null +++ b/skills/calculator-design/SKILL.md @@ -0,0 +1,296 @@ +--- +name: calculator-design +description: "Designing interactive calculators (ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments) that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. Honest about vanity-calculator (no real value), lead-trap (hides the answer behind email), and transparent-decision-tool (gives the result and earns the email through tiered value) patterns. Triggers on calculator, ROI calculator, pricing estimator, savings calculator, custom calculator, interactive tool, decision tool, financial calculator. Also triggers when an audience needs a calculation-driven lead magnet, when a vanity calculator is producing leads but no qualified ones, or when a calculator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive calculators that deliver decision-support value while qualifying leads. Distinguishes vanity-calculator (no real value) from lead-trap (hides answer behind email) from transparent-decision-tool (gives genuine value, captures leads honestly)" +display_order: 2 +--- + +# Calculator Design + +A senior growth practitioner's playbook for designing interactive calculators that deliver real decision-support value while serving as lead magnets and qualified-traffic generators. ROI calculators, pricing estimators, savings projections, mortgage calculators, custom assessments. The discipline of building a tool the audience actually trusts. + +Most calculators on the web are bait. Random multipliers behind official-looking math; an "Industry Average" number that does not cite a source; the result hidden behind a contact-sales form. The calculator captures emails because the format implies calculation; the leads are unqualified because the calculator did not actually help anyone decide anything. + +The calculators that work as compounding assets do something different. They give the audience a result they can defend to a stakeholder. They show the methodology so the result is interrogatable. They capture leads through value (a PDF report, a save-and-compare account, a custom analysis) rather than through manipulation. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the calculator-specific methodology (calculation transparency, tiered value, methodology disclosure) lives here. + +The voice is the senior growth practitioner who has watched calculators earn long-term credibility and watched them burn it within weeks of launch. Practical, opinionated about transparency, willing to say when a calculator is the wrong investment for the goal. + +When to use this skill: scoping a calculator for the first time, auditing a calculator that converts but does not qualify, designing the methodology disclosure that earns audience trust, or deciding which features warrant the email gate. + +--- + +## What this skill covers + +This skill spans calculator design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology (when to invest in any magnet, format selection, audience-fit, follow-up sequence). Calculators are one specific lead-magnet type. +- `calculator-design` (this skill) is calculator-specific methodology (calculation transparency, tiered value, methodology disclosure, input design). +- `quiz-and-assessment-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `landing-page-copy` is the calculator landing page (downstream of calculator design). +- `pm-spec-writing` is writing the spec for engineers building the calculator. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: growth marketers, product marketers, marketing teams building lead-magnet calculators, agencies running growth-tooling work for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the calculator (handed off via `pm-spec-writing`). + +--- + +## The calculator decision: when calculators earn investment + +Before designing the calculator, decide whether a calculator is the right tool for the audience and the goal. + +Calculators earn investment when: + +- The audience faces a specific calculation as part of a decision. ROI on a software purchase, savings from a refinance, monthly cost of an expense, sizing for a service tier. Without a real calculation in the audience's actual workflow, the calculator becomes a vanity tool. +- The calculation is non-trivial. Multiplying two numbers does not need a calculator; calibrating across 5-10 inputs with branching logic does. +- The brand has methodology authority. The calculator's output has to be defensible. Brands without methodology authority (or unwilling to disclose methodology) often produce calculators audiences do not trust. +- The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation); the sequence has to use that signal. + +Calculators do NOT earn investment when: + +- The audience does not actually run this calculation. A calculator solving a problem the audience does not have produces low usage. +- The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" does not earn its build. +- The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend, the calculator becomes a vanity tool by necessity. +- A simpler magnet would serve the same audience and goal. Templates and checklists are cheaper to build and maintain than calculators; choose the calculator only when the calculation is the value. + +The decision is not "should we have a calculator"; it is "is the calculator the right next investment for this specific audience and goal." + +Detail in [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md). + +--- + +## Vanity-calculator vs lead-trap vs transparent-decision-tool + +The keystone framing. + +Vanity-calculator. Inputs and outputs that do not actually help anyone decide anything. "Calculate your marketing ROI" with random multipliers; "estimate your savings" with no defensible methodology. Looks impressive in a screenshot; helps nothing in a real decision. Cost: leads downloaded the result, found it useless, and remember the brand as the source of the useless tool. + +Lead-trap. Genuine calculation logic but the result is hidden behind an email gate. The user inputs 8 fields, hits "Calculate," and sees "enter your email to see your result." Manipulative; reader resents the friction; conversion drops below baseline because the audience can tell when the gate is bait rather than value-add. + +Transparent-decision-tool. Genuine calculation that gives the result immediately. Email gate for advanced features (PDF report, custom analysis, save-and-compare across scenarios) where the additional value justifies the ask. The reader gets the answer they came for; the brand gets the email through demonstrated generosity. + +The litmus test. After running the calculator, can a stranger in the target audience defend the result to a stakeholder? Can they cite the methodology behind the number? If yes, the calculator is a transparent-decision-tool. If they got a number with no defensible source, the calculator is vanity. If they could not see the result without giving an email, the calculator is a lead-trap. + +--- + +## Input design + +The calculator's inputs are the audience's first interaction. Bad input design loses the user before the calculation runs. + +The principle. Each input should be necessary for the calculation, easy for the user to provide, and respectful of the user's time. + +Necessary. If an input does not affect the output meaningfully, do not ask for it. Calculators that ask 18 inputs but only use 5 in the actual math signal that the form is collecting data for sales rather than for the calculation. The audience can tell. + +Easy to provide. Use defaults from honest assumptions. "Average company size" preset to a reasonable industry baseline. "Typical conversion rate" preset to a defensible number. Defaults reduce the cognitive load and let the user adjust where their context differs. + +Respectful of time. Group related inputs visually. Show only the fields the user is currently working through (progressive disclosure where it helps). Indicate progress so the user knows how many steps remain. + +Input types. + +- Numeric (revenue, customer count, monthly cost). The most common. Often warrants tooltip explaining what the number represents. +- Slider (percentage estimates, conversion rates). Good for ranges where exact values are not knowable. +- Dropdown (industry, company size, region). Good for predefined categories. +- Toggle (feature on/off, scenario A vs B). Good for binary choices. +- Free text (only when the value is genuinely user-specific and cannot be calculated). Use sparingly; free text is friction. + +Detail in [`references/input-design-patterns.md`](references/input-design-patterns.md). + +--- + +## Calculation logic transparency + +The defensibility of the result is the calculator's credibility currency. + +The principle. The audience should be able to inspect the methodology. Either the calculation is shown openly, or a methodology link explains it, or the team is willing to share the spec on request. + +Methodology disclosure options. + +- Inline formulas. "Your savings = (current cost x 12) - (our cost x 12) + implementation savings of $X." Explicit and verifiable. +- Methodology page. A link from the calculator to a page explaining the assumptions, sources, and formulas. The audience can read if they care; defaults are good for those who do not. +- Source citations. When inputs come from external benchmarks ("Industry Average: 14 percent"), cite the source. Uncited benchmarks erode trust. +- Assumption list. A list of the calculator's assumptions, plain-language. "We assume you are comparing month-over-month after a 3-month implementation period." + +The vanity-calculator failure. Assumptions hidden, sources missing, formulas opaque. The audience uses the tool, gets a number, and cannot defend it. The brand is invisible in their next conversation about the decision because the calculator did not earn the credibility. + +The transparent-tool win. Assumptions visible, sources cited, formulas inspectable. The audience uses the tool, gets a number, and can defend it. The brand is in the conversation because the audience cites the calculator as their source. + +Detail in [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md). + +--- + +## Result presentation + +The result is the calculator's product. Bad result presentation wastes the calculation work. + +The principle. The result should be specific, contextualized, and actionable. + +Specific. A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." + +Contextualized. Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." The context makes the number interpretable. + +Actionable. What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step is the calculator's bridge from result to action. + +Result-presentation patterns. + +- Headline number. The single most important output, large and prominent. +- Breakdown. Sub-results that explain how the headline number was calculated. +- Visualization. Bar chart, comparison table, or simple graphic that helps the user see the relationship. +- Scenario comparison. "Your current state vs the optimized state." Useful when the calculator is illustrating a delta. + +Avoid. + +- Burying the result. The result should be visible immediately, not after a scroll. +- Result followed by 5 paragraphs of marketing. The result is what the user came for; marketing belongs after, not before. +- Result that requires re-entering all inputs to view. Persist inputs and results within the session. + +Detail in [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md). + +--- + +## Email-capture decision + +What to gate, what to give freely. + +The principle. Give the audience the result they came for. Gate the additional value (PDF report, custom analysis, save-and-compare, saved scenarios across visits). + +What to give freely. + +- The headline result. +- The breakdown of how the result was calculated. +- A visualization of the result. +- The methodology disclosure. + +What to gate (with email or account creation). + +- A formatted PDF report the user can share or save. +- A saved scenario the user can revisit and compare against alternatives. +- A custom analysis (a deeper version of the calculation, often delivered later). +- Email-based notifications when assumptions change or new benchmarks emerge. + +The lead-trap failure. The headline result is gated. The user inputs 8 fields, hits Calculate, sees "enter your email to see your result." Conversion drops because the audience perceives the manipulation. The lead-trap pattern is short-term thinking. + +The transparent-tool win. The result is free; the additional value is gated. Conversion is honest; lead quality is high because the lead opted in for the additional value, which signals real interest. + +Detail in [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md). + +--- + +## Tiered-value structures + +The architecture that lets calculators capture leads honestly. + +The principle. The calculator delivers tiered value: free immediate result + gated advanced features. + +Tier 1 (free, no gate): the headline result, the breakdown, the methodology, basic visualization. + +Tier 2 (email-gated): a formatted PDF, a saved scenario, an emailed copy of the result. + +Tier 3 (account or sign-up gated): save-and-compare across multiple scenarios over time, advanced analysis, integration with the brand's product or service. + +The tier-design discipline. + +- Each tier should add real value over the previous. If Tier 2 is just "the same result in a PDF," the tier does not justify the email ask. +- The gate at each tier should be matched to the value. Email for Tier 2; account creation only for Tier 3. +- The tier transitions should feel natural. The user gets the free result, sees the additional value visibly, and chooses whether to opt in for it. + +Worked example. + +A B2B SaaS pricing calculator. + +- Tier 1 (free): the user enters team size and use case, sees the recommended plan and the estimated monthly cost. Methodology link explains tier breakpoints. +- Tier 2 (email-gated): a PDF showing the recommended plan, the calculation, and a comparison to alternative plans the user might consider. +- Tier 3 (account-gated): a saved scenario the user can revisit; ability to compare against historical pricing if the calculator is used periodically; option to receive notifications if pricing or recommended plans change. + +Each tier earns its gate. + +Detail in [`references/tiered-value-structures.md`](references/tiered-value-structures.md). + +--- + +## Calculator anti-patterns + +Patterns that look like calculators but degrade trust. + +The lead-trap. Result hidden behind email. Detail in keystone framing. + +The vanity output. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? + +The hidden-methodology calculator. No way to see the math; no methodology page; no assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The interrogation form disguised as calculator. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The misleading-baseline calculator. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. The audience that knows the industry sees the gap. + +The misaligned-units calculator. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The static-assumption calculator. Assumptions hardcoded in 2022 that have not been updated. The calculator's outputs are stale. + +The mobile-broken calculator. Calculator works fine on desktop, breaks on mobile. The mobile audience either bounces or gets a worse experience that misrepresents the brand. + +Detail in [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-calculator-failures.md`](references/common-calculator-failures.md). + +- "Conversion rate is high; downstream conversion is near zero." Lead-trap or vanity-output pattern; the audience captured did not get value, did not engage with the follow-up, did not convert. +- "Audience visits the calculator, runs it once, never returns." Calculator does not produce a save-worthy or share-worthy result; no reason to come back. +- "Sales team says the calculator-sourced leads are unqualified." Calculator's audience-fit weak; the calculation does not match the buyer's actual decision. +- "We get questions about how the calculator works; we have no answer." Methodology not documented; the team cannot defend the calculator's outputs. +- "We updated the product; the calculator outputs are now wrong." No update cadence; the calculator drifted out of sync with the actual offering. +- "The calculator works; nobody uses it." Calculator hidden in the site; no distribution; the audience does not know it exists. +- "Our calculator looks like our competitor's." Generic calculator-template patterns produce generic calculators; the brand differentiation absent. +- "The form has 12 fields and 4 percent conversion." Interrogation-form pattern; the calculator is collecting data, not delivering value. +- "Audience trusts our brand; the calculator outputs feel arbitrary." Methodology disclosure missing; the brand's credibility does not transfer to the tool because the tool does not show its work. + +--- + +## The framework: 12 considerations for calculator design + +When designing or auditing a calculator, walk these 12 considerations. + +1. The calculator decision. Is a calculator the right investment, or would a simpler magnet serve? +2. Transparent-decision-tool, not vanity or lead-trap. Result is free; methodology is visible; gate is on additional value, not on the result. +3. Inputs are necessary, easy, respectful of time. Each input affects the math; defaults reduce friction; progressive disclosure where it helps. +4. Calculation methodology disclosed. Inline formulas, methodology page, source citations, or assumption list. +5. Result is specific, contextualized, actionable. Number with units; baseline for interpretation; clear next step. +6. Tiered value structure. Free immediate result; gated advanced features; each tier earns its gate. +7. Email-capture decision honest. Gate on real value-add (PDF, save-and-compare, custom analysis), not on the result the user came for. +8. Source attribution clear. Industry averages, benchmarks, and assumptions all cited or explained. +9. Mobile experience tested. Calculator works on the device the audience uses. +10. Update cadence defined. When inputs, benchmarks, or product details change, the calculator gets updated. +11. Distribution planned. The calculator's audience knows it exists. Landing page, navigation, content references all include the calculator. +12. Lead quality measured. Downstream conversion from calculator-sourced leads is the real metric, not surface conversion. + +The output of the framework is a calculator that delivers real decision-support value, earns the email through demonstrated generosity, and produces leads the team can convert downstream. + +--- + +## Reference files + +- [`references/calculator-investment-criteria.md`](references/calculator-investment-criteria.md) - When a calculator is the right tool for the audience and goal, and when a simpler magnet would serve. +- [`references/input-design-patterns.md`](references/input-design-patterns.md) - Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. +- [`references/calculation-logic-transparency.md`](references/calculation-logic-transparency.md) - Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. +- [`references/result-presentation-patterns.md`](references/result-presentation-patterns.md) - Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. +- [`references/email-capture-decision-tree.md`](references/email-capture-decision-tree.md) - What to give freely, what to gate. The lead-trap failure and the transparent-tool win. +- [`references/tiered-value-structures.md`](references/tiered-value-structures.md) - Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. +- [`references/methodology-disclosure-templates.md`](references/methodology-disclosure-templates.md) - Templates for assumption lists, methodology pages, source citations, formula explanations. +- [`references/calculator-anti-patterns.md`](references/calculator-anti-patterns.md) - The patterns that look like calculators but degrade trust. +- [`references/common-calculator-failures.md`](references/common-calculator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: calculators earn the email when they would have been worth paying for + +The calculators that work as compounding assets are the ones the audience trusts. Not impressive screenshots. Not high conversion rates. Trust. The audience runs the calculator, gets a result they can defend, and remembers the brand as the source of the result they used in their actual decision. + +That is the bar. Below the bar are vanity-calculators (no real result) and lead-traps (result hidden until you pay with an email). Above the bar are transparent-decision-tools that give the audience the answer freely and capture leads through additional value the audience opts in for. + +The discipline is in the design choices. The methodology disclosure that earns credibility. The input design that respects the audience's time. The tiered value structure that makes the email-capture honest. The result presentation that makes the calculator's output usable in the audience's real conversation. The update cadence that keeps the calculator in sync with the offering it represents. + +When in doubt, ask: would the audience pay for this calculator if it were not free, and can they defend the result to a stakeholder after they use it? If yes to both, the calculator earns the email. If no to either, redesign or do not ship. diff --git a/skills/calculator-design/references/calculation-logic-transparency.md b/skills/calculator-design/references/calculation-logic-transparency.md new file mode 100644 index 0000000..8afc216 --- /dev/null +++ b/skills/calculator-design/references/calculation-logic-transparency.md @@ -0,0 +1,200 @@ +# Calculation logic transparency + +Methodology disclosure options. Inline formulas, methodology pages, source citations, assumption lists. The defensibility of the result is the calculator's credibility currency. + +A calculator's output is only as trustworthy as the audience's ability to inspect how it was computed. Calculators that hide methodology produce numbers; calculators that disclose methodology produce defensible numbers. The difference shows up in whether the audience cites the calculator in stakeholder conversations. + +--- + +## The transparency principle + +The audience should be able to inspect the methodology if they care. + +Three levels of transparency, in increasing depth. + +Level 1: Inline. The methodology appears in the calculator itself, near the result. "Your annual savings: $14,200 = (current cost x 12) - (estimated new cost x 12) + first-year implementation savings of $X." + +Level 2: Methodology page. A linked page explaining the formulas, assumptions, and sources in detail. The result page links to it; users who want depth find it. + +Level 3: Spec on request. The team is willing to share the underlying spec, customer-data sources, or formula derivations on request. Useful for analytical or enterprise audiences who want full inspection. + +A calculator should at minimum support Level 1 or Level 2. Level 3 is optional and signals analytical credibility. + +--- + +## Inline formulas + +Show the math near the result. + +The pattern. Below or alongside the headline result, show the formula that produced it. + +Example: ROI calculator inline formula. + +``` +Annual savings: $14,200 + +Calculation: + Current annual cost: $36,000 ($3,000 / month x 12) + Estimated new annual cost: $24,000 ($2,000 / month x 12) + Annual savings: $36,000 - $24,000 = $12,000 + + First-year implementation savings: $2,200 + Total: $14,200 +``` + +The win. The audience can verify the math. They can adjust their inputs and predict how the result will change. They can defend the result to a stakeholder by citing the formula. + +When to use inline formulas. When the calculation is straightforward enough to display in a few lines. Most ROI, savings, and pricing calculators fit this pattern. + +When inline formulas hurt. When the calculation is so complex (multi-stage, with branching) that the formula display overwhelms the result. In those cases, link to a methodology page instead. + +--- + +## Methodology page + +A linked page explaining the calculation in depth. + +The pattern. The result page includes a "How this is calculated" or "Methodology" link. The link opens a page with formulas, assumptions, and sources. + +What a methodology page should include. + +- The central formulas in plain text (not just images). +- Each variable defined. +- Each assumption listed plainly. "We assume a 3-month implementation period." "We assume the user is comparing month-over-month." +- Sources for any external benchmarks. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025]." +- Worked example. A specific scenario with input values and the resulting calculation. +- Caveats. "This calculator does not account for [X]; for that, see [other resource]." + +The methodology page test. A skeptical reader of the methodology page should come away thinking "this is reasonable" or "I disagree with assumption Y, here is why." Either response is a sign the methodology is real and the audience can engage with it. + +Methodology pages and SEO. Methodology pages can themselves rank for search terms ("how is X calculated"), bringing additional traffic to the calculator. The page is not just transparency; it is also a content asset. + +--- + +## Source citations + +When the calculator uses external benchmarks or data, cite the source. + +The pattern. "Industry Average: 14 percent. Source: [Industry Benchmark Report 2025, page 23]." + +Why source citations matter. They signal that the benchmark is real, not invented. They let the skeptical user verify. They protect the brand if the benchmark is later disputed. + +Citation discipline. + +- Cite the most authoritative source available (industry report, academic paper, published study). +- Date the source. Benchmarks decay; an undated source could be from any year. +- Link to the source where possible. Inaccessible sources (paywalled reports cited from memory) are weaker than linked sources. +- If the source is internal customer data, say so. "Source: [Brand]'s customer cohort, n=200, 2024-2025." Internal sources are valid; honesty about their origin matters. + +The uncited-benchmark failure. "Industry Average: 14 percent" with no source. The audience that knows the industry sees the gap; the audience that does not know rolls the dice on whether to trust. Either way, credibility leaks. + +--- + +## Assumption lists + +A plain-language list of what the calculator assumes. + +The pattern. Either inline (near the result) or on the methodology page, list the assumptions in plain English. + +Example assumption list for a SaaS pricing calculator. + +- "We assume your team will use the platform daily." +- "We assume implementation takes 4-6 weeks." +- "We assume the productivity gains compound through year 1 and stabilize in year 2." +- "We assume your current solution costs include licenses, hosting, and 1 FTE for maintenance." +- "We do not account for [specific factors] in this estimate." + +Why assumption lists matter. They make the calculator's worldview visible. The audience can see whether the assumptions match their situation. If the assumptions diverge, the audience knows to discount the result accordingly. + +Honest assumptions vs flattering assumptions. Honest assumptions reflect the typical case; flattering assumptions reflect the case that produces the most attractive output. Audiences that catch flattering assumptions stop trusting the calculator. + +The assumption-decay problem. Assumptions need updating as the world changes. A calculator with assumptions from 2022 may have outdated benchmarks; review quarterly. + +--- + +## The methodology-authority spectrum + +Calculators sit on a spectrum from "fully transparent" to "fully opaque." Each position has tradeoffs. + +Fully transparent. All formulas, all assumptions, all sources visible. The audience can fully reconstruct the calculation. Trust is maximum; competitive risk (others copying the methodology) is highest. + +Largely transparent. Major formulas visible; minor weighting or proprietary elements glossed. The audience trusts the result; the brand keeps some IP. Common middle ground. + +Methodology-page transparent. The result is shown without inline formulas; the methodology page has the depth. The audience that cares finds the depth; the audience that does not, does not have to. + +Opaque. No methodology shown. The audience either trusts the brand or not; there is no inspection path. High competitive protection; low audience trust. + +The right position depends on the audience and the goal. Analytical audiences (engineers, finance teams, technical buyers) need transparency to trust. Less-analytical audiences may accept opacity if the brand has earned trust through other means. Most calculators benefit from at least Level 2 (methodology page) transparency. + +--- + +## When the calculation cannot be fully disclosed + +Some calculations include proprietary IP. Honest framing matters. + +The honest framing. "The output combines public benchmark data with proprietary insights from our customer cohort. Public elements are detailed in the methodology page; the proprietary weighting reflects our own data and is not detailed here." + +The dishonest framing. Hiding the proprietary nature; presenting opaque outputs as if they came from public methodology. + +The audience's reaction. Honest framing about proprietary IP is usually accepted. The audience understands that some IP is protected; they appreciate the honesty about what is shown and what is not. Dishonest framing breaks trust when the audience tries to interrogate and finds nothing. + +The discipline. Disclose what can be disclosed. Honestly label what cannot. The combination earns more trust than full opacity or false transparency. + +--- + +## Methodology display patterns + +How to integrate methodology into the calculator's UI. + +Pattern A: Always-visible inline formulas. The result and the formula appear together. Best for short calculations where the formula is digestible. + +Pattern B: Expandable methodology details. The result appears prominently; "How this was calculated" is an expandable section below. The user opens it if they want depth. + +Pattern C: Methodology link to a separate page. The result is shown; the methodology page is linked. Good for complex calculations that need full discussion. + +Pattern D: Hover-revealed assumption tooltips. Each variable in the result has a tooltip explaining how it was derived. Useful when the calculation has many components. + +Pattern E: Methodology in PDF report. The free result shows the headline; the gated PDF contains the full methodology. This pattern works when the PDF is genuinely the value-add and the headline result is enough for free users. + +The choice depends on calculator complexity, audience analytical depth, and the brand's transparency posture. + +--- + +## Common transparency failures + +No methodology shown. Result is a number; user has no way to verify or defend it. + +Hidden assumptions. Inputs and outputs visible; assumptions baked into the math without disclosure. + +Uncited benchmarks. "Industry Average: 14 percent" with no source. + +Stale assumptions. Methodology written in 2022, never reviewed. + +Flattering defaults. Defaults set to produce favorable outputs; the audience that catches the bias stops trusting. + +Methodology page that hides more than it reveals. Marketing copy disguised as methodology; no actual formulas or sources. + +Inconsistent precision. Result shown as "$14,237" when the inputs justify only "$14,000 (estimated)." False precision erodes trust. + +No version history on methodology. Methodology page changed over time without record; users who relied on previous outputs cannot tell what changed. + +--- + +## The credibility compounding effect + +Transparent calculators compound credibility. + +The mechanism. The audience uses the calculator, gets a defensible result, cites it in their decision-making conversation. The brand is in the conversation. The audience returns to the calculator for related decisions. The brand's authority on the topic deepens. + +The opposite. Opaque calculators do not compound. The audience uses the calculator, gets a number they cannot defend, leaves it out of their stakeholder conversation. The brand is invisible. The audience does not return. + +The metric. Track whether the calculator is being cited. Mentions in customer conversations, references in industry discussions, backlinks from other content all signal compounding credibility. + +--- + +## Methodology-level choices that stay in the public skill + +The transparency principle and the three levels. Inline formulas, methodology pages, source citations, assumption lists. The methodology-authority spectrum. Honest framing for proprietary calculations. Methodology display patterns. Common transparency failures. The credibility compounding effect. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source citations and benchmark relationships. Specific tooling for methodology display. Specific brand-voice methodology copy. The team's update calendars and version control for methodology. These vary by team. diff --git a/skills/calculator-design/references/calculator-anti-patterns.md b/skills/calculator-design/references/calculator-anti-patterns.md new file mode 100644 index 0000000..430a9c9 --- /dev/null +++ b/skills/calculator-design/references/calculator-anti-patterns.md @@ -0,0 +1,211 @@ +# Calculator anti-patterns + +The patterns that look like calculators but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The lead-trap + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +The signal. Conversion-rate metric on the email form looks fine; downstream conversion is near zero; the audience that recognizes the pattern bounces immediately. + +The cost. The leads captured are unqualified or actively annoyed. The brand earns "lead-trap" reputation; trust erodes across all future interactions. + +The cure. Restructure so the result is free and the additional value (PDF, save-and-compare, custom analysis) is gated. Detail in `references/email-capture-decision-tree.md`. + +--- + +## The vanity output + +The pattern. A number that looks impressive but does not help any real decision. "Your marketing efficiency score is 87." 87 of what? Compared to what? + +The signal. Audiences run the calculator out of curiosity; do not return; do not cite the result anywhere; do not engage with the follow-up sequence. + +The cost. The calculator's build cost was wasted. The audience does not associate the brand with useful analysis. + +The cure. Anchor the result to a decision the audience actually makes. The output should be a number with units, contextualized against a baseline, with a clear next step. + +--- + +## The hidden-methodology calculator + +The pattern. No way to see the math. No methodology page. No assumption list. The audience uses the tool, gets a number, and cannot defend it. + +The signal. Sales-team friction; prospects who used the calculator cannot bring its outputs into stakeholder conversations. + +The cost. The calculator does not compound credibility. Each user runs it once and does not return; the brand stays invisible in the audience's actual decision conversations. + +The cure. Disclose methodology. Detail in `references/calculation-logic-transparency.md`. + +--- + +## The interrogation form disguised as calculator + +The pattern. 18 input fields, of which 5 affect the math. The form is collecting sales-qualification data under cover of calculation. + +The signal. Conversion rate on the form is poor. The audience self-selects out at the form length. + +The cost. The calculator's reach drops dramatically. The leads that do convert are over-disclosed and may resent the friction; the audience the calculator could have served does not get to use it. + +The cure. Audit the input set. Remove fields that do not affect the calculation. Capture additional data later in the relationship, not at the form. + +--- + +## The misleading-baseline calculator + +The pattern. "Industry Average" or "Typical Customer" baselines that are flattering to the brand and unsourced. + +The signal. Audiences with industry knowledge notice the gap. Those audiences do not return; they may post about the bias publicly. + +The cost. Trust damage that can be hard to recover. Brand earns "spin" reputation. + +The cure. Source the baselines honestly. Use defensible benchmarks; if the brand's data is favorable, disclose that the data comes from the brand's own customer cohort and acknowledge the bias. + +--- + +## The misaligned-units calculator + +The pattern. "Estimated savings: 14X" without a base value. Or "60 percent improvement" without saying improvement in what. + +The signal. Audiences cannot interpret the result; cannot use it in their decision; do not return. + +The cost. The calculator's outputs are uninterpretable; the calculator does not produce decision-grade signal. + +The cure. Numbers with units. Percentages with bases. Multipliers with reference values. Contextualization that makes the result interpretable. + +--- + +## The static-assumption calculator + +The pattern. Assumptions hardcoded in 2022 that have not been updated. Industry benchmarks from 2 years ago. Tooling references to products that have been deprecated. + +The signal. Audiences with current knowledge see the staleness; trust drops; some users may report the inaccuracy. + +The cost. The calculator's outputs are unreliable. The brand looks careless or out of touch. + +The cure. Quarterly maintenance review. Update assumptions, refresh benchmarks, prune stale references. + +--- + +## The mobile-broken calculator + +The pattern. Calculator works fine on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; result hidden below the fold. + +The signal. High mobile bounce rate; mobile conversion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic; this failure is significant. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. Detail in `references/input-design-patterns.md` (mobile section). + +--- + +## The over-precise calculator + +The pattern. Result shown as "$14,237.42" when the inputs justify only "$14,000 (estimated)." False precision suggests the calculator knows more than it does. + +The signal. Analytical audiences see the false precision and discount the result. The calculator earns "fake math" reputation among the audience that matters most. + +The cost. Trust erosion specifically among the audience the calculator was designed to serve. + +The cure. Round to honest precision. Use "estimated" or "approximately" framing. Disclose the precision the inputs support. + +--- + +## The marketing-disguised-as-methodology calculator + +The pattern. The methodology page exists but contains marketing copy ("our proprietary algorithm draws on industry-leading data") rather than actual formulas, sources, or assumptions. + +The signal. Audiences who click through to verify find no real verification; trust drops. + +The cost. The calculator's credibility is performative rather than real; the audience that interrogates discovers the gap. + +The cure. Real methodology. Formulas, assumptions, sources. Brand voice can frame the methodology page; brand voice cannot replace the methodology itself. + +--- + +## The orphan-result calculator + +The pattern. The result loads; no next step is offered. The user gets the number and leaves. + +The signal. Conversion to next step (PDF, save, contact, demo) is near zero because no next step is offered. + +The cost. The calculator captures attention without converting it. The brand has the audience's moment of intent and does nothing with it. + +The cure. Offer a clear next step at the result. PDF, save scenario, talk to team, related resource. Detail in `references/result-presentation-patterns.md` (result-to-action transitions). + +--- + +## The popup-interrupted calculator + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. The user's flow breaks. + +The signal. Bounce rate spikes at the popup moment; users complain about the interruption. + +The cost. The calculator's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. Detail in `references/result-presentation-patterns.md`. + +--- + +## The cookie-cutter calculator + +The pattern. The calculator looks and behaves like every other calculator from a template platform. Generic UI, generic assumption set, generic output styling. + +The signal. The calculator does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The calculator becomes commodity; the brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## The pessimistic-default calculator + +The pattern. Defaults set to make the brand's outputs look favorable through pessimistic baselines. "Current cost" defaults to the high end; "savings" defaults to the optimistic end. + +The signal. Audiences who notice (often analytical audiences) discount the result. The audience the calculator was built for stops trusting it. + +The cost. Same as misleading-baseline. Trust damage; brand earns "spin" reputation. + +The cure. Honest defaults sourced from data; let the user adjust to their actual context. + +--- + +## The form-without-calculator + +The pattern. A "calculator" that is actually a form. No real calculation; the result is generic ("based on your inputs, our team will reach out") or static ("your estimated savings: 30 percent"). + +The signal. Audiences expecting a real calculation get a sales form; bounce rate spikes; the audience perceives bait-and-switch. + +The cost. The calculator's framing was a lie; trust collapses. + +The cure. Either build a real calculator with real math, or do not call the form a calculator. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active calculator, looking specifically for these anti-patterns. + +Audit questions per calculator. + +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Is the methodology disclosed in a way the audience can verify (anti-pattern check: hidden-methodology)? +- Are the inputs all necessary for the calculation (anti-pattern check: interrogation-form)? +- Are the baselines and benchmarks sourced and current (anti-pattern check: misleading-baseline, static-assumption)? +- Does the calculator work on mobile (anti-pattern check: mobile-broken)? +- Is the result actionable, with a clear next step (anti-pattern check: orphan-result)? +- Does the calculator differentiate from other calculators on similar topics (anti-pattern check: cookie-cutter)? + +The retire decision. Anti-pattern calculators often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-tool plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/calculator-design/references/calculator-investment-criteria.md b/skills/calculator-design/references/calculator-investment-criteria.md new file mode 100644 index 0000000..b0673aa --- /dev/null +++ b/skills/calculator-design/references/calculator-investment-criteria.md @@ -0,0 +1,144 @@ +# Calculator investment criteria + +When a calculator is the right tool for the audience and the goal, and when a simpler magnet would serve. The conditions that warrant the calculator's build cost. + +A calculator is one of the highest-build-cost magnet formats. Engineering, design, methodology research, and ongoing maintenance all add up. The calculator earns this investment only when specific conditions are present. + +--- + +## When a calculator earns the build + +Five conditions that, when present, make a calculator a strong investment. + +The audience faces a specific calculation as part of a real decision. ROI on a software purchase, savings from a refinance, monthly cost projection, sizing for a service tier, time-to-payback estimate. The calculation has to be one the audience actually runs in their workflow. Without a real calculation, the calculator becomes vanity. + +The calculation is non-trivial. Multiplying two numbers does not need a calculator; the audience can do that in their head. Calibrating across 5-10 inputs with branching logic, applying industry benchmarks, or running a multi-scenario comparison earns the format. + +The brand has methodology authority. The output has to be defensible. Brands with research, customer data, or industry expertise that informs the calculation can disclose methodology credibly. Brands without that authority often produce calculators audiences cannot trust. + +The follow-up sequence has a real purpose for the lead. Calculators capture a specific signal (the inputs reveal the lead's situation: company size, current configuration, projected savings). The sequence has to use that signal. A generic sequence wastes the input data. + +The success metric is defined. What does "the calculator works" look like? Lead volume, lead quality, downstream conversion, the audience citing the calculator in stakeholder conversations. Without the success metric defined, evaluation is impossible. + +When all five are present, the calculator is a strong investment. When two or fewer are present, a simpler magnet (template, checklist, or worked example) often serves better. + +--- + +## When a calculator does NOT earn the build + +Funnels where the calculator is the wrong tool. + +The audience does not actually run this calculation. The team imagines the audience would benefit from the calculation; the audience does not actually face this decision. Usage is low; the build cost was wasted. + +The calculation is trivial. A "savings calculator" that computes "monthly cost x 12" is not a calculator; it is a multiplication. The audience can do this without a tool. + +The brand cannot disclose methodology honestly. If the math depends on assumptions the brand cannot defend ("we estimate 60 percent improvement based on internal data we cannot share"), the calculator becomes a vanity tool by necessity. The audience that would benefit from a defensible calculator gets a brand-flattering one instead. + +A simpler magnet would serve the same audience and goal. A pricing PDF that shows worked examples and methodology might serve the same audience as a pricing calculator at one-tenth the build cost. Choose the simpler magnet when it would serve. + +The audience is too small to justify the build. A calculator for a niche of 200 prospects is hard to justify against the build cost. Direct outreach or a simpler resource may be more efficient. + +The team cannot maintain the calculator. Calculators decay as benchmarks change, product details evolve, and tooling updates. Without maintenance commitment, the calculator becomes a stale liability. + +The honest assessment matters more than the default. "Should we have a calculator" is not the question. "Is the calculator the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A calculator's cost is significant. Account for it honestly. + +The build cost. Methodology research, formula design, input UX, result UX, calculation engine, methodology disclosure, mobile responsiveness, edge-case handling. A meaningful calculator often takes 60-200 engineering hours plus design and copy. + +The maintenance cost. Benchmarks change; product details change; assumptions shift. Quarterly review and updates run 4-12 hours per active calculator. + +The sequence cost. The follow-up sequence using the input data is itself a build. 10-30 hours upfront. + +The opportunity cost. What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The calculator's success has to clear the bar of those alternatives. + +The decision frame. The calculator earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The methodology-authority precondition + +Without methodology authority, the calculator cannot be defensible. + +The audience's question. After running the calculator: "Where does this number come from?" + +If the team can answer with sources (industry benchmarks, customer data, public research, defensible assumptions), the calculator has methodology authority. The audience can trust the result and use it in their decision. + +If the team cannot answer ("our model just produces this number"), the calculator does not have methodology authority. The audience either does not trust the result or trusts it without understanding it (which is worse for the audience and ultimately for the brand). + +How to assess methodology authority. + +- Does the team have direct customer data on the calculation's central variables? +- Does the team have access to defensible industry benchmarks? +- Is the team willing to publish the methodology, or does the methodology have to stay proprietary? +- Can the team defend the methodology to a sophisticated stakeholder? + +If the answer to most of these is yes, the calculator has methodology authority. If the answer is no, the calculator is being built on assumptions that will not survive interrogation. + +--- + +## The decision worked example + +A SaaS analytics platform considering a "ROI of moving from spreadsheets" calculator. + +Conditions check. + +- Specific calculation: yes. Prospects evaluating the platform run an internal estimate of switching value. +- Non-trivial: yes. The calculation involves time-saved-per-week, hourly cost of analyst time, error-rate reduction, decision-speed lift, and implementation cost. +- Methodology authority: yes. The team has customer data on time saved, error reduction, and decision speed across 200+ deployed customers. +- Sequence has purpose: yes. Calculator inputs reveal company size, analytics maturity, and current tooling. Sequence can match the lead's profile. +- Success metric defined: yes. Lead volume from the calculator, lead quality (audience-fit at SaaS companies above 50 employees), downstream conversion to demo within 90 days. + +Decision. Build the calculator. The conditions warrant it. + +Tier design. Tier 1 (free): the headline annual savings number, the breakdown across time-saved, error-reduction, and decision-speed components, methodology disclosure linked. Tier 2 (email-gated): a PDF the prospect can share with their stakeholders showing the calculation in defensible form. Tier 3 (account-gated, optional): saved scenarios across multiple analyst counts and use-case configurations. + +Maintenance commitment. Quarterly review of the customer-data benchmarks. Update assumptions when the customer base shifts. + +The decision was not "should we have a calculator" but "given these conditions, this is the calculator to build." + +--- + +## When to choose a simpler magnet instead + +The calculator is the wrong tool. What works. + +Pricing one-pager template. When the calculation is "what would my pricing look like," a worked-example one-pager often serves better than a calculator. The prospect adapts the example; the team avoids building. + +ROI worked-example PDF. When the calculation is "what would I save," a PDF showing 3-5 worked-example customer scenarios often serves better. The prospect identifies which scenario matches them; the team gets a downloadable resource without engineering overhead. + +Sizing checklist. When the calculation is "what tier do I need," a checklist of features and team-size signals can guide the prospect to the right tier without a calculator. + +Comparison table. When the calculation is "is this better than the alternative," a static comparison table often serves better than a dynamic calculator. + +The pattern. Many "we need a calculator" intuitions are actually "we need a clear way to communicate this calculation to prospects." Often the simpler format works as well or better, at one-tenth the build cost. + +--- + +## When to retire a calculator + +Calculators decay. Retiring them is part of the discipline. + +Retire when: + +- Lead volume has dropped below baseline for two consecutive quarters. +- The product or pricing has changed enough that the calculator's calculations no longer reflect the offering. +- The benchmarks the calculator relies on are stale and the team cannot update them. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. A portfolio of stale calculators costs maintenance attention without producing results. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a calculator. The opportunity-cost frame. The methodology-authority precondition. The decision worked example. When to choose a simpler magnet. The retirement discipline. + +## Implementation choices that stay internal + +Specific calculator topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence. Specific tooling for calculator engineering, hosting, and integration. Specific methodology sources and update calendars. These vary by team. diff --git a/skills/calculator-design/references/common-calculator-failures.md b/skills/calculator-design/references/common-calculator-failures.md new file mode 100644 index 0000000..badb9cc --- /dev/null +++ b/skills/calculator-design/references/common-calculator-failures.md @@ -0,0 +1,179 @@ +# Common calculator failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the calculator did not work" or "the leads are unqualified" or "we cannot tell what the calculator is producing." + +--- + +## "Conversion rate is high; downstream conversion is near zero." + +The diagnosis. Lead-trap or vanity-output pattern. The audience captured did not get value; did not engage with the follow-up; did not convert downstream. + +The cure. Audit for lead-trap (`references/email-capture-decision-tree.md`). Audit for vanity-output (`references/result-presentation-patterns.md`). The result has to be specific, contextualized, and actionable; the email gate has to be on additional value, not on the result itself. + +--- + +## "Audience visits the calculator, runs it once, never returns." + +The diagnosis. The calculator does not produce a save-worthy or share-worthy result. No reason to come back. + +The cure. Add tier-2 value (PDF, saved scenario) that gives the user something to bring back to. Audit the result presentation (`references/result-presentation-patterns.md`); a result the user cannot share with stakeholders rarely produces return visits. + +--- + +## "Sales team says the calculator-sourced leads are unqualified." + +The diagnosis. Calculator's audience-fit is weak. The calculation does not match the buyer's actual decision; the audience captured is curious-but-not-buying. + +The cure. Audit the calculator's audience-fit. Does the calculation map to a real decision the buyer faces? If not, the calculator may be capturing wrong-segment leads. Detail also in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "We get questions about how the calculator works; we have no answer." + +The diagnosis. Methodology not documented. The team cannot defend the calculator's outputs. + +The cure. Document the methodology (`references/calculation-logic-transparency.md`, `references/methodology-disclosure-templates.md`). The methodology page should answer the audience's interrogation questions before they ask. + +--- + +## "We updated the product; the calculator outputs are now wrong." + +The diagnosis. No update cadence. The calculator drifted out of sync with the actual offering. + +The cure. Maintenance discipline. Quarterly review of every active calculator. Update inputs, recommendations, and pricing as the offering evolves. + +--- + +## "The calculator works; nobody uses it." + +The diagnosis. Calculator hidden in the site; no distribution; the audience does not know it exists. + +The cure. Distribution. Link to the calculator from related landing pages, blog posts, and navigation. Promote it in newsletter and social channels. Cite it in sales conversations. The calculator's existence is not enough; the audience has to know about it. + +--- + +## "Our calculator looks like our competitor's." + +The diagnosis. Generic calculator-template patterns produce generic calculators. Brand differentiation is absent. + +The cure. Custom design that reflects the brand. Methodology that reflects the brand's specific authority. The calculator should look like it could only have come from this brand. + +--- + +## "The form has 12 fields and 4 percent conversion." + +The diagnosis. Interrogation-form pattern. The calculator is collecting data, not delivering value. + +The cure. Audit the input set (`references/input-design-patterns.md`). Each input should affect the calculation. Remove fields that do not. + +--- + +## "Audience trusts our brand; the calculator outputs feel arbitrary." + +The diagnosis. Methodology disclosure missing. The brand's credibility does not transfer to the tool because the tool does not show its work. + +The cure. Disclose methodology (`references/calculation-logic-transparency.md`). The brand-trust is one part of credibility; the tool's transparency is a separate part. Both have to be present. + +--- + +## "Our pricing changed; the calculator was not updated for 6 months." + +The diagnosis. Maintenance lapse. The calculator's outputs were misleading for half a year. + +The cure. Set a maintenance trigger: when pricing or product details change, the calculator update is part of the change. Otherwise, set a calendar review at minimum quarterly. + +--- + +## "The calculator was great at launch; conversion has dropped 40 percent over a year." + +The diagnosis. Decay. Stale benchmarks; outdated references; methodology that no longer reflects the brand's offering. + +The cure. Audit and refresh. If the calculator is still relevant, update it. If it is not, retire it. + +--- + +## "The free result is just 'estimated savings: significant.'" + +The diagnosis. Vanity output. The free tier is a teaser rather than a substantive result. + +The cure. The free tier has to be substantive. "Estimated annual savings: $14,200" with breakdown and methodology beats "significant savings" with email gate. + +--- + +## "Audiences complete the inputs but do not opt for the PDF." + +The diagnosis. The PDF does not justify the email exchange. Either the PDF is the same content as the free result (no value-add) or the audience does not perceive the PDF as worth the email. + +The cure. Make the PDF genuinely better. Add comparison tables, case studies, or additional analysis. Frame the PDF as "what you can share with your CFO" so the audience sees the use case. + +--- + +## "We get traffic; we get email signups; the sales team never hears about the leads." + +The diagnosis. Sequence missing or poorly designed. The leads sit on the list without being routed to sales. + +The cure. Design the post-conversion flow. Calculator-sourced leads should be tagged, routed, and sequenced. Sales should know which leads came from the calculator and what the leads' inputs revealed. + +--- + +## "We added a calculator; our other lead magnets stopped converting." + +The diagnosis. Cannibalization. The calculator absorbed the audience that previously converted via other magnets. + +The cure. This may not be a failure. If the calculator-sourced leads are higher quality than the previous magnets, the cannibalization is a portfolio improvement. If the calculator absorbed leads but produced no incremental value, the calculator may have replaced a working magnet with a worse one. + +--- + +## "The calculator works on Chrome desktop; it breaks on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The calculator was tested on the team's primary platform; the audience's actual devices were not covered. + +The cure. Cross-browser, cross-device testing. The audience uses what they use; the calculator has to work there. + +--- + +## "The calculator estimates 60 percent savings; our actual customers see 35 percent." + +The diagnosis. The calculator's assumptions are flattering rather than accurate. The customers who used the calculator's projections are now disappointed. + +The cure. Recalibrate. Use actual customer cohort data to set the assumptions. The honest result may be less impressive on the marketing screen but earns more trust over time. + +--- + +## "We want to A/B test the calculator's email gate placement." + +The diagnosis. This is fine, but the test should be designed carefully. Moving the email gate is a gating-decision change that affects both conversion and lead quality. + +The cure. Test gate placement with both conversion-rate and downstream-conversion metrics. A change that lifts conversion but tanks downstream is a regression, not an improvement. + +--- + +## "The calculator's methodology page got 200 visits and 50 unsubscribes." + +The diagnosis. Likely the audience interrogated the methodology and found it wanting. Either the methodology has a real flaw, or the methodology page is unclear. + +The cure. Audit the methodology page. Either fix the methodology (if there is a real flaw) or clarify the page (if the issue is presentation). + +--- + +## The pattern across failures + +Most calculator failures fall into one of three patterns. + +Pattern 1: The calculator does not deliver real value. Vanity output, hidden methodology, lead-trap. The fix is to deliver real, defensible, accessible results. + +Pattern 2: The calculator does not match the audience or decision. Audience-fit weak, calculation-decision mismatch, interrogation-form. The fix is to align the calculator to the audience the brand serves and the decision the audience faces. + +Pattern 3: The calculator decays. Stale assumptions, outdated benchmarks, broken integration. The fix is maintenance discipline. + +The metric pattern: calculator failures often look fine on conversion rate. The signal is in lead quality, downstream conversion, and audience interrogation behavior. Programs that track only conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/calculator-design/references/email-capture-decision-tree.md b/skills/calculator-design/references/email-capture-decision-tree.md new file mode 100644 index 0000000..f1fb4fc --- /dev/null +++ b/skills/calculator-design/references/email-capture-decision-tree.md @@ -0,0 +1,205 @@ +# Email-capture decision tree + +What to give freely, what to gate. The lead-trap failure and the transparent-tool win. + +The single most consequential decision in calculator design is what gets shown freely and what requires an email. Get this wrong and the calculator is either a lead-trap (gating the result the user came for) or a missed opportunity (giving away everything with no capture mechanism). + +--- + +## The honest principle + +Give the audience the result they came for. Gate the additional value. + +The audience showed up to run a calculation. They want the answer. Gating the answer is bait-and-switch: the calculator promised a result, the user provided inputs, and the result is held hostage until they trade an email. + +The transparent alternative: give the result freely. The audience gets what they came for. The brand offers additional value (a PDF report, a saved scenario, a custom analysis) that the audience can opt in for. The email exchange is then for additional value, not for the result the calculator promised. + +--- + +## What to give freely + +Tier 1, no gate. + +The headline result. The number the user came for. "Your annual savings: $14,200" or "Recommended plan: Growth." + +The breakdown. The components that explain how the headline number was calculated. Necessary for the audience to defend the result. + +A basic visualization. A chart or comparison that helps the user see the relationship. + +The methodology disclosure. Either inline formulas or a methodology link. Necessary for the audience to trust the result. + +Source citations. Where the calculator's benchmarks come from. + +The assumption list. What the calculator assumes about the user's situation. + +This set is what the audience needs to use the calculator's output in their decision. Holding any of it hostage is the lead-trap pattern. + +--- + +## What to gate (with email) + +Tier 2, email-required. + +A formatted PDF report. The result, breakdown, methodology, and assumptions in a shareable format. The user can send this to their stakeholders. The PDF has to be genuinely better than a screenshot of the result; otherwise the gate is not justified. + +A saved scenario the user can revisit. Persistence across visits. The user adjusts inputs over time, returns to compare, sees how the result has changed. Email-required to identify the user. + +A custom or deeper analysis. A second-pass calculation that uses the user's inputs as a starting point and adds more depth (more variables, more scenarios, more methodology). Often delivered later (by email) rather than immediately. + +Email-based notifications. When the calculator's benchmarks change or new versions launch, the user can be notified. + +The discipline. Each gated tier has to add real value over the free tier. If the PDF is just "the same result in a PDF," the gate is not earning the email. + +--- + +## What to gate (with account or sign-up) + +Tier 3, account-required. + +Save-and-compare across multiple scenarios. The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +Integration with the brand's product or service. The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +Historical comparison. When the calculator is used periodically (monthly cost projection, quarterly review), the user's historical inputs and results are tracked. + +Collaboration features. Multiple users on the same account can model scenarios together. + +These features warrant the higher friction of account creation. Email alone is insufficient; the user needs persistent identity for these to work. + +--- + +## The lead-trap failure + +The pattern that destroys conversion. + +The pattern. The user enters inputs, hits Calculate, sees "enter your email to see your result." + +Why it fails. + +- The audience perceives the manipulation. The calculator promised a result; the result is hidden. +- Conversion drops. Many users abandon at the gate; some enter throwaway emails. +- The leads that do convert are unqualified or actively annoyed; downstream conversion is poor. +- The brand earns "lead-trap" reputation; future users who recognize the pattern bounce immediately. + +Why teams build lead-traps. Short-term thinking. The team optimizes for capture rate without measuring downstream conversion. The lead-trap looks like it works because the form-fill rate is high; the lead-trap fails because the leads do not convert. + +The cure. Restructure the calculator so the result is free and the additional value is gated. Conversion to the email gate may drop in absolute terms, but the leads that do opt in are higher-quality. + +--- + +## The transparent-tool win + +The pattern that compounds credibility. + +The pattern. The user enters inputs, sees the result immediately, and is offered a "Get this as a PDF" or "Save this scenario" option that requires email. + +Why it works. + +- The audience trusts the brand. The calculator delivered on its promise. +- The email opt-in is for additional value, not for the result. Users who opt in are signaling real interest in the topic. +- Lead quality is higher because the lead opted in for value-add, which signals genuine interest. +- The brand earns "honest" reputation; word-of-mouth and referral grow. + +The metrics that matter. + +- Free-tier completion rate (how many users finish the calculation and see the result). +- Email-tier conversion rate (of those who see the result, how many opt in for the additional value). +- Downstream conversion (of those who opted in, how many engage with the follow-up sequence and convert to the next step). + +The transparent-tool optimizes for downstream conversion, which is the metric that matters for the program. + +--- + +## The decision tree + +Walk through this for each gating decision. + +Question 1: Is this the result the user came for? + +- If yes: do not gate. Holding the user-promised result hostage is lead-trap. +- If no: continue. + +Question 2: Is this additional value the user might want? + +- If yes: gating is potentially appropriate. +- If no: do not gate; the user does not want it badly enough for the email exchange to be worthwhile. + +Question 3: Is the additional value substantial enough to justify the email? + +- If yes: gate it. The user gets real value; the brand gets the email; the exchange is honest. +- If no: do not gate; the gate is not earning its friction. + +Question 4: Could the additional value be delivered better as a follow-up after the email? + +- If yes: gate it as a follow-up offer in the post-result flow, not as a barrier to the result. +- If no: gate it as a clear "get this additional value" offer near the result. + +This decision tree separates honest gating from manipulative gating. + +--- + +## Worked examples + +Example 1: SaaS pricing calculator. + +- Free: recommended plan, monthly cost estimate, breakdown by component, methodology link. +- Email-gated: a PDF showing the recommendation, alternative plans considered, and a printable comparison table. +- Account-gated: ability to save the scenario and adjust over time as the team's needs change. + +The free tier delivers what the prospect came for. The email gate delivers a shareable artifact for the prospect's internal stakeholders. The account gate enables ongoing use. + +Example 2: ROI calculator for a B2B service. + +- Free: estimated annual savings, breakdown across cost reduction and productivity gains, methodology disclosure. +- Email-gated: PDF analysis with industry-comparison context and worked-example case study. +- Account-gated: not offered. The calculator is single-use; account creation is unnecessary friction. + +The free tier serves the audience. The email gate serves the prospect's internal stakeholders by providing a shareable analysis. + +Example 3: Mortgage calculator. + +- Free: estimated monthly payment, breakdown across principal, interest, taxes, insurance, methodology link. +- Email-gated: a personalized rate quote (which requires the bank to underwrite based on user inputs). +- Not offered: account creation. The calculator is a one-shot tool; account creation does not match the use case. + +The email gate is justified by genuine value-add (personalized rate quote requires underwriting). The free tier delivers the calculator's promise. + +--- + +## When the email gate is the wrong tool + +Sometimes no gating is the right answer. + +Calculators built primarily for SEO or brand authority. A widely-shared, well-ranked calculator can be a strong brand asset even without lead capture. The audience that uses it associates the brand with the topic; the SEO ranking compounds traffic. + +Calculators where lead-capture friction destroys the value proposition. A simple, quick-use calculator may be best as a no-gate tool. The audience uses it, gets value, returns; the brand becomes the source of the tool. + +Calculators in regulated industries. Some sectors have specific privacy or regulatory constraints on email capture. The calculator may need to operate without standard lead-capture flows. + +The decision depends on the program's goals. Not every calculator needs to be a lead magnet. Some calculators serve other purposes (SEO, brand, audience-building) better without gates. + +--- + +## Common gating failures + +Result hidden behind email. The lead-trap. Conversion drops; downstream metrics drop further. + +Gate without value. Email required to access something that should have been free; no real additional value behind the gate. + +Gate that lies about what is gated. "Get the full analysis" suggests the free version was incomplete; the user expects more depth, gets the same content reformatted, feels deceived. + +Multiple gates in sequence. Email for one tier, account for another, phone number for a third. Each step adds friction; cumulative drop-off destroys the audience. + +Gate copy that is manipulative. "Don't lose your result, give us your email" is hostile. "Want this as a PDF? Enter your email" is honest. + +Gate placement that interrupts the result viewing. The result loads; the user starts reading; a popup appears asking for email. The user's flow breaks; trust drops. + +--- + +## Methodology-level choices that stay in the public skill + +The honest principle. What to give freely. What to gate at email and at account level. The lead-trap failure pattern. The transparent-tool win pattern. The decision tree. Worked examples. When the email gate is the wrong tool. Common gating failures. + +## Implementation choices that stay internal + +Specific gating decisions for the team's calculators. Specific PDF templates and follow-up flows. Specific account-creation flows and integration patterns. Specific gate copy in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/skills/calculator-design/references/input-design-patterns.md b/skills/calculator-design/references/input-design-patterns.md new file mode 100644 index 0000000..4f8cf5d --- /dev/null +++ b/skills/calculator-design/references/input-design-patterns.md @@ -0,0 +1,218 @@ +# Input design patterns + +Input necessity, default discipline, input types, progressive disclosure. The friction the audience does not need. + +The calculator's inputs are the audience's first interaction with the tool. Bad input design loses users before the calculation runs. Good input design respects the user's time and produces inputs that genuinely affect the math. + +--- + +## The necessity principle + +Each input should be necessary for the calculation. Inputs that do not affect the output meaningfully should not be asked for. + +The test. For each input, ask: does removing this input change the result by a meaningful amount? If no, the input is not necessary; remove it. + +The interrogation-form failure. Calculators that ask 18 inputs but only use 5 in the math are signaling that the form is collecting sales-qualification data. The audience can tell. Conversion drops; trust drops. + +The honest input set. Most calculators need 4-10 inputs. Tools asking 15+ inputs almost always have non-essential fields that should move to a separate (later, optional) interaction. + +The exception: meaningful customization. When inputs do affect the result and the audience values the customization, more inputs are warranted. A pricing calculator that customizes to industry, team size, use case, and feature needs may need 8-12 inputs because each input affects the output. + +The discipline. Audit the input set against the actual math. Remove fields that do not affect the result. + +--- + +## Default discipline + +Defaults reduce cognitive load. Bad defaults bias the result. + +Honest defaults. Set defaults to honest, sourced values. "Average company size: 50" if 50 is the median across the audience. "Typical conversion rate: 14 percent" if 14 percent is a defensible benchmark. + +Sourced defaults. When defaults come from external benchmarks, source them. A footnote or tooltip explaining the default's origin earns trust. + +Adjustable defaults. The user should be able to override the default with their actual value. Defaults that look hardcoded reduce trust; defaults the user can edit signal that the calculator respects the user's situation. + +Bias-flattering defaults. Defaults set to flatter the brand's outputs (high savings, low costs) destroy credibility when the user notices. The audience that catches the bias remembers it. + +Default decay. Defaults need updating as benchmarks shift. A default set in 2022 that has not been touched is stale; the audience that knows the current benchmark sees the gap. + +--- + +## Input types + +Choose the right input control for each variable. + +Numeric input. Free-form number entry. Use for variables that are user-specific and where exact values matter (revenue, customer count, monthly cost). Often warrants a tooltip explaining what the number represents. + +Slider. Visual range control. Use for percentage estimates and ranges where exact values are not knowable (conversion rate, growth rate, retention). Sliders communicate the range and reduce cognitive load on choosing a precise number. + +Dropdown. Select from predefined categories. Use for variables that are categorical (industry, region, company size band). Dropdowns prevent invalid inputs and group similar audiences. + +Toggle. Binary on/off. Use for feature inclusion/exclusion or scenario switching (with implementation / without implementation). + +Stepper. Increment/decrement controls. Use for small whole-number variables (number of users, number of locations) where the range is bounded. + +Free text. Open-ended text input. Use sparingly. Free text adds friction and rarely affects calculation; if the calculator needs free text to function, the calculation may be the wrong format. + +The choice depends on the variable's nature. The wrong control type adds friction; the right control type makes the input feel natural. + +--- + +## Progressive disclosure + +Show only the inputs the user is currently working through. + +The pattern. The calculator presents 2-4 inputs at a time. The user completes those, the next set appears. Each step builds on the previous. + +When progressive disclosure helps. When the calculator has 8+ inputs, when input groups are conceptually distinct (company info, then current state, then desired state), or when later inputs depend on earlier choices. + +When progressive disclosure hurts. When the calculator has 4-6 inputs that the user could complete in 30 seconds, hiding any of them adds friction. Single-page calculators are fine for short input sets. + +Progress indicators. When the calculator is multi-step, show progress ("Step 2 of 4") so the user knows the time commitment. + +Back navigation. The user should be able to go back and adjust earlier inputs without losing later ones. + +--- + +## Input grouping and visual flow + +Group related inputs visually. The user processes related inputs as a unit. + +Logical groups. + +- Company info (name, size, industry). +- Current state (current cost, current process, current tools). +- Desired state (target outcome, target timeline). +- Configuration choices (tier, options, add-ons). + +Visual cues. + +- Section headers for each group. +- Spacing between groups. +- Consistent input styles within a group. + +Avoid. + +- Mixing unrelated inputs in one section. +- Inconsistent label patterns across the form. +- Required-vs-optional ambiguity (mark required inputs explicitly). + +--- + +## Tooltips and explanations + +Inputs that are not self-explanatory need explanation. Inputs that are self-explanatory do not need it. + +When tooltips help. When the input requires context the user may not have ("Customer Acquisition Cost: the marketing and sales spend per new customer"), when the input has a specific definition that varies by interpretation, or when the default needs sourcing ("Industry average from [source]"). + +When tooltips hurt. When the input is obvious (no tooltip needed for "Number of users"), when the tooltip is marketing rather than explanation, or when the tooltip overwhelms the form visually. + +Tooltip placement. Inline (right next to the field label) or hover-triggered. Hover-triggered keeps the form clean for users who do not need explanation. + +Tooltip discipline. Each tooltip should answer one question. Multiple paragraphs in a tooltip signal that the input itself needs redesign. + +--- + +## Validation and error handling + +Inputs need validation. Errors need helpful messages. + +Inline validation. Validate as the user types or after they leave the field. Catch errors at the point of input, not at submission. + +Helpful error messages. "Number must be greater than 0" beats "Invalid input." "Try a value between 1 and 1000" beats "Out of range." + +Avoid friction. Validation that rejects too aggressively (rejecting all special characters when only a few cause problems) frustrates users. Error messages that scold ("You must enter...") signal a hostile form. + +Required vs optional. Mark required inputs explicitly. Optional inputs should be obvious (and rare; if it is not used, why ask). + +--- + +## Mobile input design + +Many calculator users are on mobile. The input experience has to work there. + +Mobile-specific considerations. + +- Touch-friendly input sizes (minimum 44x44 pixel touch targets). +- Numeric keyboards for numeric inputs (use input type="number" or appropriate inputmode). +- Sliders sized for thumb interaction. +- Dropdowns that work with native mobile selection. +- Sufficient spacing between inputs to prevent accidental taps. + +Mobile testing. Test the calculator on actual mobile devices, not just browser dev tools. Real-device behavior often differs. + +Mobile-broken calculator failure. Calculator works on desktop, breaks on mobile. The mobile audience either bounces or has a worse experience. This failure is common; mobile testing prevents it. + +--- + +## Input examples and worked patterns + +Pattern: company info input set. + +- Company size (dropdown: 1-10, 11-50, 51-200, 201-500, 501-2000, 2000+) +- Industry (dropdown of 8-12 categories) +- Current annual revenue (numeric, optional, with tooltip explaining how it affects calculation) + +3 inputs, 30 seconds to complete, all affect the calculation. + +Pattern: current state input set. + +- Current monthly cost (numeric, with tooltip) +- Current team size on the relevant function (numeric) +- Current process (dropdown: manual, partially automated, fully automated) + +3 inputs, sets the baseline for the calculation. + +Pattern: desired state input set. + +- Target outcome (dropdown: cost reduction, time savings, revenue lift, all of the above) +- Target timeline (slider: 3 months to 24 months) + +2 inputs, sets the goal for the calculation. + +Total: 8 inputs across 3 logical groups. Each input affects the math. Defaults reduce friction. Progressive disclosure presents groups one at a time. + +--- + +## Input decay + +Inputs need maintenance. + +What decays. + +- Defaults based on benchmarks that have shifted. +- Tooltips referencing tools or terms that have changed. +- Dropdown options that are no longer accurate (industry categories, product tiers). +- Sources cited in tooltips that no longer exist or have moved. + +Maintenance cadence. Quarterly review of every active calculator's inputs. Update defaults, refresh tooltips, prune stale options. + +The decay-trust connection. Stale defaults erode trust. The audience notices when "Industry Average: 14 percent (2022)" appears in a 2026 tool. + +--- + +## Common input failures + +Too many inputs. 15+ inputs signal interrogation rather than calculation. Audit for non-essential fields. + +Bias-flattering defaults. Defaults that produce favorable outputs for the brand. Audiences notice; trust drops. + +Hardcoded defaults that cannot be changed. The audience cannot adjust to their actual situation. The calculator feels generic. + +Wrong input type for the variable. Free text where dropdown would be better; dropdown where slider would be better. Adds friction. + +Missing tooltips on non-obvious inputs. The audience does not know what the input means; they guess; the result is meaningless. + +Mobile-broken inputs. Sliders impossible to grab on mobile; dropdowns that overflow; numeric keyboards not triggered. + +Stale defaults. Benchmarks from years ago; tooltips referencing deprecated tools; dropdown options that no longer match reality. + +--- + +## Methodology-level choices that stay in the public skill + +The necessity principle. Default discipline. Input type guidance. Progressive disclosure. Input grouping and visual flow. Tooltip discipline. Validation and error handling. Mobile input design. Input decay and maintenance. + +## Implementation choices that stay internal + +Specific input sets for specific calculators. Specific default values from the team's data sources. Specific tooltip copy in brand voice. Specific input components and styling. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/skills/calculator-design/references/methodology-disclosure-templates.md b/skills/calculator-design/references/methodology-disclosure-templates.md new file mode 100644 index 0000000..170bf18 --- /dev/null +++ b/skills/calculator-design/references/methodology-disclosure-templates.md @@ -0,0 +1,321 @@ +# Methodology disclosure templates + +Templates for assumption lists, methodology pages, source citations, formula explanations. Patterns for disclosing calculation logic in ways the audience can use to defend the result. + +A methodology disclosure is not a marketing document. It is a technical document that lets the audience interrogate the calculator. The templates here cover the patterns that hold up to interrogation. + +--- + +## Methodology page template + +A standalone page that explains the calculator's calculations in detail. + +Structure. + +``` +# How the [calculator name] is calculated + +## What this calculator does +[2-3 sentences describing the calculation in plain language] + +## The formulas +[Plain-text formulas with each variable defined] + +## Assumptions +[Plain-language list of what the calculator assumes] + +## Sources +[Citations for any external benchmarks or data] + +## Worked example +[A specific scenario with input values and resulting calculation] + +## Caveats +[What the calculator does not account for; when to seek additional analysis] + +## Updates +[Date of last methodology review; how often the calculator is updated] +``` + +--- + +## Assumption list template + +A plain-language list of assumptions, formatted for scan-ability. + +Structure. + +``` +## What this calculator assumes + +- [Assumption 1: stated plainly] +- [Assumption 2: stated plainly] +- [Assumption 3: stated plainly] + +## What this calculator does NOT account for + +- [Excluded factor 1] +- [Excluded factor 2] + +If your situation differs significantly from these assumptions, the result is an estimate; consider [additional resource] for more precise analysis. +``` + +Example assumption list for a SaaS pricing calculator. + +``` +## What this calculator assumes + +- Your team will use the platform daily across business hours. +- Implementation takes 4-6 weeks for teams in the 50-200 employee range. +- The recommended plan is based on typical usage patterns from our customer base. +- Productivity gains compound through year 1 and stabilize in year 2. + +## What this calculator does NOT account for + +- Custom integrations or enterprise SSO requirements. +- Volume discounts available for annual contracts above $50K. +- Migration cost from your current platform. + +If your situation involves enterprise SSO, custom integrations, or migration costs, talk to our team for a tailored estimate. +``` + +--- + +## Source citation template + +How to cite external benchmarks or data. + +Inline citation pattern. + +``` +Industry Average: 14 percent (Source: [Industry Benchmark Report 2025], page 23) +``` + +Footnote pattern. + +``` +Industry Average: 14 percent [^1] + +[^1]: Industry Benchmark Report 2025. Available at [URL]. Accessed [Date]. +``` + +Multi-source pattern. + +``` +The conversion-rate benchmark we use combines: +- Industry Benchmark Report 2025 (Source A) +- Our customer cohort data (n=200, 2024-2025) +- Public conversion-rate studies from [Source C] + +The composite benchmark is 14 percent. +``` + +Internal-source pattern. + +``` +Source: [Brand]'s customer cohort data, n=200, 2024-2025. The cohort represents customers in the 50-500 employee range across SaaS, e-commerce, and B2B services. +``` + +--- + +## Formula explanation template + +How to display formulas in ways the audience can verify. + +Plain-text formula pattern. + +``` +Annual savings = (current annual cost) - (estimated new annual cost) + first-year implementation savings + +Where: + current annual cost = current monthly cost x 12 + estimated new annual cost = recommended plan price x 12 + first-year implementation savings = $500 if migrating from a manual process, otherwise $0 +``` + +Step-by-step calculation pattern. + +``` +1. Calculate current annual cost: $3,000 / month x 12 = $36,000 +2. Calculate estimated new annual cost: $2,000 / month x 12 = $24,000 +3. Calculate cost reduction: $36,000 - $24,000 = $12,000 +4. Add first-year implementation savings: $12,000 + $2,200 = $14,200 + +Annual savings: $14,200 +``` + +Conditional logic pattern. + +``` +The recommended plan is determined by: + +If team size is 1-10: Starter plan ($X / month) +If team size is 11-50: Growth plan ($Y / month) +If team size is 51-200: Business plan ($Z / month) +If team size is 201+: Enterprise (contact for pricing) + +Plan recommendations may shift based on use case (e.g., teams with heavy data needs may benefit from a higher tier even at a lower seat count). +``` + +--- + +## Worked-example template + +A concrete scenario the audience can read end-to-end. + +Structure. + +``` +## Worked example: [scenario description] + +Inputs: +- [Input 1]: [value] +- [Input 2]: [value] +- [Input 3]: [value] + +Calculation: +[Step-by-step formula application] + +Result: +[Final output with units] + +Interpretation: +[1-2 sentences explaining what the result means and how the audience would use it] +``` + +Example for a SaaS pricing calculator. + +``` +## Worked example: 75-person B2B SaaS team + +Inputs: +- Team size: 75 +- Use case: Customer support +- Current solution: Manual spreadsheets + +Calculation: +- Recommended plan: Business ($45 / user / month) +- Monthly cost: 75 users x $45 = $3,375 +- Annual cost: $3,375 x 12 = $40,500 +- Estimated time savings: 8 hours / week / agent x 75 agents x $40 / hour x 50 weeks = $1.2M +- Net annual value: $1.2M - $40,500 = $1.16M + +Result: +- Recommended plan: Business +- Monthly investment: $3,375 +- Estimated annual time-savings value: $1.2M +- Net annual value: $1.16M + +Interpretation: +A 75-person customer-support team migrating from manual spreadsheets to the Business plan would invest $40,500 annually and save approximately $1.16M in time-equivalent value. The largest contributor is hours saved per agent per week. +``` + +--- + +## Caveats template + +What the calculator does not do, stated honestly. + +Structure. + +``` +## What this calculator does not account for + +- [Excluded factor 1]: why it is excluded and what to do if it matters +- [Excluded factor 2]: why it is excluded and what to do if it matters + +For situations involving [specific complex case], the calculator's estimate may not apply; consider [additional resource or contact] for more precise analysis. +``` + +Why caveats matter. Caveats signal the calculator's honesty. The audience that knows the caveats can use the result with appropriate confidence; the audience that does not know the caveats may apply the result to a situation it does not fit. + +Common caveats to include. + +- The calculator does not account for taxes, regulations, or jurisdiction-specific factors. +- The calculator does not account for one-time setup or migration costs. +- The calculator's benchmarks reflect the typical case; outliers may differ significantly. +- The calculator's projections are estimates, not guarantees. + +--- + +## Update-history template + +How to track methodology changes over time. + +Structure. + +``` +## Updates + +This calculator's methodology was last reviewed on [date]. + +Recent updates: +- [Date]: Updated industry-benchmark source from [old] to [new]. +- [Date]: Adjusted productivity-gains assumption based on cohort data through [year]. +- [Date]: Added consideration for [new factor]. + +Major version history: +- v1.0 ([date]): Initial release. +- v1.1 ([date]): Added [feature]. +- v2.0 ([date]): Refactored methodology to include [new dimension]. +``` + +Why update history matters. Audiences who relied on previous outputs can see what changed. The transparency about updates signals that the calculator is maintained, not abandoned. + +--- + +## Methodology integration patterns + +How to integrate the methodology disclosure into the calculator UI. + +Pattern A: Inline disclosure. The methodology appears alongside the result. Best for short calculations where the formula is digestible. + +Pattern B: Expandable section. "How this is calculated" expandable below the result. The user opens it if they want depth. + +Pattern C: Linked methodology page. A "How this is calculated" link to a separate page. Best for complex calculations. + +Pattern D: Hover-revealed detail. Each result component has a tooltip explaining how it was derived. Useful for multi-component results. + +Pattern E: Methodology-in-PDF. The free result shows the headline; the gated PDF contains full methodology. Works when the PDF is genuine value-add. + +--- + +## Audience-specific methodology depth + +Calibrate methodology depth to the audience's analytical sophistication. + +Highly analytical audiences (engineers, finance, data scientists). Detailed formulas, source citations, version history. The audience expects depth and rewards transparency. + +Moderately analytical audiences (PMs, marketers, operations). Plain-language formulas, key assumptions, summary citations. The audience wants to verify but does not need every variable. + +Less analytical audiences (executives, generalists). Plain-language summary of the methodology, key assumptions, "talk to us if you want depth" option. The audience trusts based on the summary; depth is available if needed. + +The discipline. Match the methodology depth to the audience that uses the calculator. Too thin loses analytical audiences; too dense loses generalist audiences. + +--- + +## Common methodology disclosure failures + +No methodology shown. Result without explanation; audience cannot verify or defend. + +Methodology hidden behind email. Lead-trap pattern applied to methodology; audience that wants to verify must opt in first. + +Methodology in marketing language. "Our proprietary algorithm draws on industry-leading data" is not methodology; it is brand copy. + +Methodology that hides the assumptions. Formulas shown; assumptions not stated; audience cannot tell what the calculator assumes about their situation. + +Methodology that hides the sources. Industry averages cited without attribution. + +Methodology that does not match the calculation. Stated methodology and actual implementation drift apart over time. + +Methodology with no update history. Calculator changes silently; audience that relied on previous outputs cannot see what changed. + +--- + +## Methodology-level choices that stay in the public skill + +The methodology page template. The assumption list template. The source citation patterns. Formula explanation patterns. Worked-example template. Caveats template. Update-history template. Methodology integration patterns. Audience-specific methodology depth. Common disclosure failures. + +## Implementation choices that stay internal + +Specific methodology pages for specific calculators. Specific source-citation conventions and benchmark relationships. Specific formula-display tooling and styling. Specific worked-example libraries. The team's methodology update calendars and version control. These vary by team. diff --git a/skills/calculator-design/references/result-presentation-patterns.md b/skills/calculator-design/references/result-presentation-patterns.md new file mode 100644 index 0000000..5cd614b --- /dev/null +++ b/skills/calculator-design/references/result-presentation-patterns.md @@ -0,0 +1,247 @@ +# Result presentation patterns + +Specific, contextualized, actionable. Headline number, breakdown, visualization, scenario comparison. The result is the calculator's product; bad presentation wastes the calculation work. + +A calculator that runs the right math and presents the result poorly fails as completely as a calculator that runs the wrong math. Result presentation is half the user experience. Get it wrong and the audience does not know what to do with the number they computed. + +--- + +## The presentation principle + +The result should be specific, contextualized, and actionable. + +Specific. A number with units. "Estimated annual savings: $14,200." Not "Significant savings." Not "Up to 60 percent off." Precision matters; the audience uses the result in their actual decision. + +Contextualized. Compare to a baseline the user can understand. "Based on your inputs, you would save $14,200 annually compared to your current configuration." Without the baseline, the number is just a number; with the baseline, it becomes meaningful. + +Actionable. What does the user do with this number? "Use this estimate to make the case to your CFO" or "Save this scenario to compare against alternative configurations" or "Get a PDF report you can share." The next step bridges from result to action. + +A result that hits all three is one the audience can use in their actual decision. A result that misses any of the three leaves the audience with an unanswered "so what." + +--- + +## The headline number + +The single most important output, large and prominent. + +The pattern. One number, one label, large type, central placement. The audience sees the headline number first. + +Example headline outputs. + +- "Estimated annual savings: $14,200" +- "Recommended plan: Growth (37 users, 3 admins)" +- "Time to payback: 8 months" +- "Estimated monthly cost: $2,400" + +The discipline. + +- One headline number, not five. Multiple competing headlines fragment the user's attention. +- Number with units. "$14,200" beats "14200." "8 months" beats "8." +- Honest framing. "Estimated" or "Projected" is honest; "Guaranteed" is overstatement. +- Visual hierarchy. The headline is the largest text on the result screen. + +Headline number antipatterns. + +- "Up to $50,000" (range with no specific value). +- "Significant savings" (no number). +- "X% improvement" (no base). +- Multiple competing numbers (user does not know which to focus on). + +--- + +## The breakdown + +Sub-results that explain how the headline number was calculated. + +The pattern. Below the headline, show the components that make up the result. + +Example breakdown for an ROI calculator. + +``` +Annual savings: $14,200 + + Cost reduction: $9,200 + Current cost: $36,000 + New cost: $26,800 + + Productivity gains: $4,000 + Hours saved per week: 8 + Hourly cost: $50 + Weeks per year: 50 + + Implementation savings: $1,000 (first year only) +``` + +Why the breakdown matters. + +- It makes the headline number defensible. The user can cite the components. +- It helps the user understand how their inputs influenced the result. Adjusting inputs becomes meaningful. +- It surfaces the assumptions implicitly. The user sees what the calculator weighted. + +Breakdown display options. + +- Stacked text (as above). +- Expandable section (compact by default; user opens for detail). +- Visual breakdown (stacked bar chart, pie chart for components). + +--- + +## Visualization + +Charts and graphics that help the user see the relationship. + +When visualization helps. + +- Comparing the result against a baseline ("current vs new"). +- Showing components contributing to a total ("savings breakdown"). +- Showing change over time ("month-by-month savings projection"). +- Showing thresholds ("you fall in the 'mid-market' band based on your inputs"). + +When visualization hurts. + +- When the data does not warrant a chart (a single number does not need a pie chart). +- When the chart obscures rather than clarifies (3D pie charts, gratuitous animation). +- When the chart cannot be interpreted on mobile. + +Visualization patterns. + +- Bar comparison. Current state vs new state. Easy to read; instant relative comparison. +- Stacked bar (component breakdown). Total height = headline; segments = components. +- Line chart (time series). Monthly cost projection over 12-24 months. +- Threshold indicator. Position the user's result on a scale ("you are at the 73rd percentile"). + +Visualization quality discipline. + +- Charts should be readable at the size displayed. +- Labels should be present and legible. +- Color should reinforce, not decorate (different colors for different components, not random palette). +- Mobile rendering should preserve readability; charts that work on desktop and break on mobile fail half the audience. + +--- + +## Scenario comparison + +Useful when the calculator is illustrating a delta between two states. + +The pattern. Show the user's current state and the projected state side-by-side, with the delta highlighted. + +Example: SaaS migration calculator. + +``` + Current New Change +Annual cost $36,000 $24,000 -$12,000 +Hours/week 12 hrs/wk 4 hrs/wk -8 hrs/wk +Errors/month 14 3 -11 +``` + +Why scenario comparison works. + +- The delta is the value proposition; showing both states makes the delta concrete. +- The user can see what they are giving up (if anything) alongside what they are gaining. +- The comparison format is familiar from spreadsheets and decision tools. + +When scenario comparison applies. Calculators that compare a current state to a proposed state (migrations, refinances, configurations). Less applicable to calculators that produce a single recommendation without an explicit baseline. + +--- + +## Result-presentation antipatterns + +Patterns that waste the calculation. + +Buried result. The result requires scrolling past 5 paragraphs of marketing. The user came for the result; serve it first. + +Vague output. "Significant" or "Up to" framing without specific values. The audience cannot use vague results in real decisions. + +Result followed by 5 paragraphs of marketing. The result is what the user came for; the brand pitch belongs after, not before. + +Result that requires re-entering inputs to view. Persist inputs and results within the session. Forcing re-entry is a friction the user did not consent to. + +False precision. "$14,237.42" when the inputs justify only "$14,000 (estimated)." Precision the math does not support erodes trust. + +Multiple competing headlines. Five "important" numbers; the user does not know what to focus on. + +Disconnected result and breakdown. The headline number does not obviously add up from the breakdown components. The user does the mental math, finds the gap, loses trust. + +Result without a next step. The user gets the number, then what? Without a next step, the calculator does not bridge to action. + +--- + +## Mobile result presentation + +The result should work on mobile. + +Mobile-specific considerations. + +- Headline number readable without zoom. +- Breakdown components stack vertically rather than spread horizontally. +- Visualizations sized for mobile screens; complex multi-axis charts often do not translate. +- Scroll position lands on the result, not the inputs. + +Common mobile failures. + +- Headline number tiny on mobile because it was sized for desktop. +- Breakdown table requires horizontal scroll. +- Charts illegible at mobile size. +- Result hidden below the fold; user does not know it loaded. + +--- + +## Result-to-action transitions + +The result should lead naturally to a next step. + +Patterns. + +- CTA below the result. "Get a PDF of this analysis" or "Save this scenario" or "Talk to our team about implementing this." +- Multiple CTAs ranked. Primary action prominent; secondary action visible but smaller; tertiary action available but not pushy. +- Email-capture in context. When the gated tier (PDF, save) is offered, the form appears in context with the result, not in a popup that breaks flow. + +The discipline. + +- The next step should match the audience's likely intent. After a savings calculator, "talk to sales" may be premature; "get a PDF I can share" may match. +- Multiple CTAs should not compete; rank them by likely user intent. +- The next step should be honest. Promising "instant analysis from a specialist" and delivering "we will email you in 5 days" breaks trust. + +--- + +## Result update behavior + +When the user adjusts inputs, the result updates. + +Real-time updates. As the user changes a slider, the result recalculates. Useful for exploration; the audience sees the relationship between inputs and result. + +On-submit updates. The user adjusts inputs, hits Calculate, sees the new result. Useful for calculators with many inputs where real-time updates would be distracting. + +Hybrid. Real-time for sliders and toggles; on-submit for full input changes. Common middle ground. + +The choice. Depends on calculator complexity and the value of input exploration. Calculators that benefit from "what if" exploration favor real-time; calculators that produce a definitive recommendation favor on-submit. + +--- + +## Result-context for share-ability + +When users share the result with stakeholders, the result has to be self-contained. + +The principle. The shared result (PDF, email, screenshot, link) should be interpretable by someone who did not run the calculator. + +What share-able results need. + +- The headline number and what it represents. +- The breakdown so the recipient can verify the math. +- The methodology so the recipient can interrogate the assumptions. +- The inputs so the recipient knows what scenario was modeled. +- Brand attribution so the recipient knows the source. + +The non-shareable result. "Your savings: $14,200" with no inputs, no methodology, no breakdown. The recipient cannot use this; they ignore it or come back to ask follow-up questions that should not have been necessary. + +The shareable result extends the calculator's reach. The audience that shares is bringing the brand into a conversation; make the result strong enough to carry that weight. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation principle (specific, contextualized, actionable). Headline number discipline. Breakdown patterns. Visualization patterns and discipline. Scenario comparison. Result-presentation antipatterns. Mobile result presentation. Result-to-action transitions. Result update behavior. Share-ability discipline. + +## Implementation choices that stay internal + +Specific result-page layouts for specific calculators. Specific visualization libraries and styling. Specific PDF templates for share-able results. Specific brand-voice copy for next-step CTAs. The team's mobile testing benchmarks. These vary by team and calculator. diff --git a/skills/calculator-design/references/tiered-value-structures.md b/skills/calculator-design/references/tiered-value-structures.md new file mode 100644 index 0000000..ce17cf8 --- /dev/null +++ b/skills/calculator-design/references/tiered-value-structures.md @@ -0,0 +1,236 @@ +# Tiered value structures + +Tier 1 free, Tier 2 email-gated, Tier 3 account-gated. Worked examples. + +The architecture that lets calculators capture leads honestly. The user gets immediate value (free tier) and is offered progressively richer value at each tier with proportional friction. Each tier earns its gate. + +--- + +## The tier-design principle + +Each tier should add real value over the previous. Tiers that gate the same content at higher friction destroy trust. + +Tier 1 (no gate). Immediate, complete result. The audience gets what they came for. The free tier is not a teaser; it is the substantive output of the calculator. + +Tier 2 (email-gated). Additional value the user might want for sharing, persistence, or depth. Email is the appropriate friction level for this value. + +Tier 3 (account-gated). Persistent, multi-session, collaborative, or product-integrated value. Account creation is the appropriate friction level for this value. + +Each tier's friction matches its value-add. Tiers that ask for more friction than they justify destroy conversion. + +--- + +## Tier 1: free immediate result + +What lives at Tier 1. + +The calculator's primary output. The headline result the user came for. Annual savings, recommended plan, monthly cost, time to payback. + +The breakdown. Components that show how the headline was calculated. + +Basic visualization. A chart or comparison that helps the user see the relationship. + +Methodology disclosure. Either inline formulas or a methodology link. + +Assumption list. What the calculator assumes about the user's situation. + +Source citations. Where the calculator's benchmarks come from. + +The Tier 1 set is complete. A user who never opts into Tier 2 still got the calculator's full value. The brand still earns trust; the audience still associates the brand with the topic. + +What Tier 1 should NOT include. + +- A teaser version of the result that withholds the actual answer. +- A "preview" of the analysis that requires email to see in full. +- Marketing copy that displaces the result itself. + +--- + +## Tier 2: email-gated additional value + +What lives at Tier 2. + +A formatted PDF report. The Tier 1 content packaged in a shareable format. The PDF has to be genuinely better than a screenshot, or the gate is not justified. + +A saved scenario. The user's inputs and result persist; they can return to the calculator and see their previous calculation. + +A custom analysis. A deeper second-pass calculation, often delivered by email after submission. + +Notification opt-in. Updates when benchmarks change, when new calculator versions launch, or when the brand publishes related content. + +Tier 2 design discipline. + +- Each Tier 2 offering must clearly justify the email exchange. "Get a PDF that you can share with your CFO" is justifiable; "Get the same content in a PDF" is not. +- The email-capture form should appear in context with the offer, not as an interruption to the Tier 1 viewing. +- The follow-up email should deliver the promised value immediately, not delay it. + +--- + +## Tier 3: account-gated persistent value + +What lives at Tier 3. + +Save-and-compare across multiple scenarios. The user models 5 different configurations and compares them side-by-side. Account-level persistence supports this. + +Historical tracking. When the calculator is used periodically (monthly projection, quarterly review), the user's historical inputs and results are tracked over time. + +Collaboration features. Multiple users on the same account can model scenarios together. + +Product integration. The calculator's output flows into the user's account on the brand's platform; the calculation becomes part of an ongoing workflow. + +Tier 3 design discipline. + +- Account creation is significant friction. Tier 3 features must justify it. +- Tier 3 is often unnecessary. Many calculators serve their purpose with Tier 1 and Tier 2 alone; do not add Tier 3 unless the use case warrants it. +- Account-creation friction can be reduced (social login, magic link) but not eliminated. + +--- + +## Worked example: SaaS pricing calculator + +A B2B SaaS platform considering a tiered pricing calculator. + +Tier 1 (free). + +- The user enters team size, role distribution, and use case. +- Sees the recommended plan and the estimated monthly cost. +- Sees a breakdown showing per-seat cost, included features, and any add-ons. +- Sees a comparison against the next-tier-up plan with a brief explanation of when it would be worth it. +- Sees a methodology link explaining how recommendations are made. + +Tier 2 (email-gated). + +- A PDF showing the recommended plan, the breakdown, the next-tier comparison, and 2-3 customer case studies of similar teams using similar plans. +- The PDF is shareable and contains enough context for an internal stakeholder to evaluate. + +Tier 3 (account-gated). + +- The user can save the scenario and adjust inputs over time as the team grows. +- The user can model alternative scenarios (different team size, different use case) and compare side-by-side. +- The user can receive an email when their team size threshold suggests a tier change. + +Each tier earns its gate. The user can stop at Tier 1 and still get value. Tier 2 is offered as a way to share with stakeholders. Tier 3 is offered for users who want ongoing tracking. + +--- + +## Worked example: ROI calculator for a B2B service + +A B2B service company considering an ROI calculator. + +Tier 1 (free). + +- The user enters current cost, team size, and process maturity. +- Sees estimated annual savings. +- Sees a breakdown across cost reduction, productivity gains, and implementation savings. +- Sees the methodology disclosed inline. + +Tier 2 (email-gated). + +- A PDF showing the calculation in defensible form, with industry-context comparison and a worked-example case study from a similar customer. + +Tier 3. Not offered. The calculator is single-use; account creation would be unnecessary friction. + +The two-tier structure fits the use case. Adding Tier 3 would add friction without value. + +--- + +## Worked example: financial calculator (mortgage, refinance, savings) + +A financial services company considering a savings calculator. + +Tier 1 (free). + +- The user enters current loan details, target rate, and timeline. +- Sees estimated monthly savings, total savings over the loan term, and break-even point on closing costs. +- Sees the breakdown and methodology. + +Tier 2 (email-gated). + +- A PDF analysis with comparison across multiple lender scenarios. +- A personalized rate quote (which requires underwriting based on user inputs). + +Tier 3. Optional. An account that tracks the user's loan over time and notifies them when refinance opportunities emerge as rates change. + +The Tier 2 includes genuine value-add (personalized quote requires underwriting). The Tier 3 is optional for users who want ongoing monitoring. + +--- + +## Tier-design failures + +Patterns that look like tiered value but degrade trust. + +Teaser-tier-as-Tier-1. The free tier shows a partial result; the email tier shows the full result. This is lead-trap dressed as tiered value. + +Same-content-different-format. Tier 1 is the result on screen; Tier 2 is the same result in a PDF. The PDF is not value-add; the gate is not justified. + +Inverted tiers. Tier 1 is thin; Tier 2 is what should have been Tier 1; Tier 3 is what should have been Tier 2. The audience that gets Tier 1 sees nothing useful; conversion drops. + +Tier-3 friction without Tier-3 value. Account creation required for features that could have been email-only or free. Friction without value-add destroys the gate. + +Surprise upsells. The user opts into Tier 2; the email follow-up reveals additional gates the user did not anticipate. Trust drops. + +--- + +## The flat-tier alternative + +Some calculators do not need tiers. + +When flat is right. + +- Simple calculators where the result is the only output worth offering. +- Calculators built for SEO or brand authority where lead capture is secondary. +- Calculators where account creation does not match the use case. + +The flat structure. Tier 1 (free, complete result). Optional email opt-in for newsletter or related content (no gate, no friction). + +This structure works when the calculator's primary value is the calculation itself and the lead-capture motion is secondary or absent. + +--- + +## Tier transitions + +How the user moves from tier to tier. + +Tier 1 to Tier 2. The user sees the free result. Below or alongside, an offer: "Want this as a PDF you can share?" or "Save this scenario for later." Email-capture in context. + +Tier 2 to Tier 3. After the user has engaged with Tier 2 (downloaded the PDF, returned to the saved scenario), an offer: "Want to track this over time? Create an account." The friction increase is justified by the additional value. + +The discipline. Tier transitions should feel natural, not pushy. The user gets value at each tier; the next tier is offered, not demanded. + +--- + +## Tier maintenance + +Tiers decay along with the calculator. + +Tier 1 maintenance. Update defaults, refresh sources, update methodology as benchmarks shift. + +Tier 2 maintenance. Update PDF templates as the brand evolves; refresh case studies; update comparison data. + +Tier 3 maintenance. Maintain the account-side functionality; ensure persistence works; update integrations. + +The retire-tier decision. Tier 3 features that are not used can be retired. Tier 2 PDFs that no one downloads can be simplified. Periodic audit of tier usage informs maintenance. + +--- + +## Common tier failures + +Tier 1 is a teaser. Lead-trap pattern. + +Tier 2 does not justify the email. Same content, repackaged. + +Tier 3 is offered but unused. Friction without payoff; sometimes the right answer is to retire Tier 3. + +Tier transitions are pushy. Aggressive popups at each transition; the user feels pressured. + +Tier maintenance lapses. Stale PDFs, broken account features, outdated comparison data. + +--- + +## Methodology-level choices that stay in the public skill + +The tier-design principle. What lives at each tier. Tier-design discipline at each level. Worked examples across calculator types. The flat-tier alternative. Tier transitions. Tier maintenance. Common failures. + +## Implementation choices that stay internal + +Specific tier structures for specific calculators. Specific PDF templates and account-creation flows. Specific tooling for tier transitions. The team's tier-usage measurement and audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/SKILL.md b/skills/chatbot-flow-design/SKILL.md new file mode 100644 index 0000000..0cdffe9 --- /dev/null +++ b/skills/chatbot-flow-design/SKILL.md @@ -0,0 +1,266 @@ +--- +name: chatbot-flow-design +description: "Designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. Honest about scripted-bot (rigid trees, fail edge cases), hallucinating-bot (LLM without structure, makes things up), and structured-guided-conversation (LLM-powered with intent architecture and fallback discipline) patterns. Distinguishes chatbot DESIGN (this skill) from chatbot IMPLEMENTATION (engineering and platform work). Triggers on chatbot, conversational AI, AI agent, chat widget, intent design, conversational flow, bot escalation, LLM grounding. Also triggers when a chatbot is hallucinating, when a scripted bot is failing edge cases, or when a chatbot is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing conversational flows for chatbots and AI agents on websites. Distinguishes scripted-bot (rigid trees, fail edge cases) from hallucinating-bot (LLM without structure, makes things up) from structured-guided-conversation (LLM-powered with intent architecture and fallback discipline)" +display_order: 5 +--- + +# Chatbot Flow Design + +A senior growth practitioner's playbook for designing conversational flows for website chatbots and AI agents. Intent recognition architecture, branching logic, fallback handling, escalation to human, conversation analytics. The discipline of building a bot that knows what it knows and routes appropriately when it does not. + +Most chatbots on the web fail in one of two ways. Scripted bots break the moment a user phrases something the script did not anticipate; the user gets pushed through a decision tree that does not fit their situation. LLM-powered bots without structure hallucinate; they confidently answer questions about pricing, policy, or capabilities and frequently make up answers, creating support burden and trust damage. + +The chatbots that work do something different. They have an intent architecture that defines what the bot can and cannot handle. They ground their responses in a knowledge base so they do not invent facts. They have explicit fallback paths for unclear or out-of-scope intents. They escalate to humans cleanly when the bot's job is done. The audience trusts the bot because the bot is honest about its scope. + +The voice is the senior growth practitioner who has watched chatbots become trusted brand surfaces and watched them become liability risks. Practical, opinionated about the architecture that distinguishes the two outcomes, willing to call out when a chatbot is the wrong investment or when an existing chatbot needs to be redesigned rather than tuned. + +When to use this skill: scoping a chatbot for the first time, auditing a chatbot that hallucinates or fails edge cases, designing the intent architecture and fallback patterns, or deciding when to escalate to humans. + +--- + +## What this skill covers + +This skill spans chatbot design as conversational flow architecture, not chatbot implementation. The growth-tooling distinctions: + +- `ai-content-collaboration` covers AI in content workflows. This skill covers AI in customer-facing conversations. +- `integration-orchestrator` covers cross-team coordination for chatbot deployment. This skill is the conversational design itself. +- `pm-spec-writing` covers the spec for engineers building the bot. This skill is about WHAT the conversation should be; pm-spec-writing is about communicating it. +- `discovery-research-synthesis` covers customer research that informs intent architecture. Input to this skill, not part of it. +- `chatbot-flow-design` (this skill) is intent architecture, knowledge-base grounding, fallback patterns, and escalation discipline. + +The audience: growth marketers and product marketers shipping chatbot growth tooling, in-house teams designing conversational flows for marketing or support contexts, agencies running chatbot work for clients. + +Out of scope: AI in content workflows (covered by `ai-content-collaboration`); the engineering implementation of chatbots (handed off via `pm-spec-writing`); platform-specific bot configurations (those stay implementation-side); voice agents and IVR flows (different methodology though related principles apply). + +--- + +## The chatbot decision: when chatbots earn deployment + +Before designing the chatbot, decide whether a chatbot is the right tool. + +Chatbots earn deployment when: + +- The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. +- The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. +- The bot can ground its answers in real knowledge (documentation, product specs, pricing pages). Without grounding, the bot's answers are at best generic and at worst fabricated. +- The team can maintain the bot. Chatbots decay; intents drift; knowledge bases need updating. Without maintenance commitment, the bot becomes stale liability. + +Chatbots do NOT earn deployment when: + +- The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. +- The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates or stays so generic it adds no value. +- The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. +- The audience is small enough that direct human conversation is more efficient. +- The team cannot maintain the bot. Stale bots produce wrong answers. + +The decision is not "should we have a chatbot"; it is "is the chatbot the right tool for this specific audience and conversation." + +Detail in [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md). + +--- + +## Scripted-bot vs hallucinating-bot vs structured-guided-conversation + +The keystone framing. + +Scripted-bot. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. The chatbot equivalent of an automated phone tree. Cost: the user's actual question goes unanswered; the bot pushes the user through paths that do not fit; the audience leaves with a worse experience than no bot. + +Hallucinating-bot. LLM-powered with no structure. Will confidently answer questions about pricing, policy, capabilities, and frequently make up answers. Liability risk; trust-eroding; support burden when wrong answers reach customers. Cost: the bot's confident wrong answers damage the brand more than no bot would; the team learns about the hallucinations through customer complaints. + +Structured-guided-conversation. LLM-powered with intent architecture, knowledge-base grounding, defined fallback paths, and explicit escalation to humans. The bot knows what it knows, knows what it does not, and routes appropriately. Cost: the design effort upfront is significant; the maintenance is real; the audience trusts the bot because the bot is honest about its scope. + +The litmus test. Ask the bot a question outside its intended scope. Does it confidently make up an answer (hallucinating), refuse rigidly (scripted), or honestly route the user to a human or alternative resource (structured-guided)? The third response is the goal. + +--- + +## Intent architecture + +Defining what the bot can and cannot handle. + +The principle. The bot has a defined set of intents it can handle. Each intent maps to a conversation pattern (questions to ask, knowledge to ground in, response to provide). Anything outside the intent set falls to fallback. + +Intent design patterns. + +- Named intents. "Pricing question," "feature comparison," "integration question," "support escalation," "demo request." Each intent is explicit. +- Intent hierarchy. Top-level categories with sub-intents. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question." +- Intent boundaries. Each intent has clear scope. Out-of-scope topics route to fallback. + +Intent coverage. The bot's intents should cover 70-90 percent of expected conversations. The remaining percentage falls to fallback. Trying to cover 100 percent often produces bloated intent sets that the bot cannot handle reliably. + +Intent maintenance. Intents drift as products evolve, audiences shift, and conversations change. Periodic review surfaces which intents are useful and which need refining. + +Detail in [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md). + +--- + +## Knowledge-base grounding + +The bot's responses must come from real knowledge, not made-up confidence. + +The principle. The bot's response generation should reference a structured knowledge base (documentation, product specs, pricing pages, support articles). The bot does not invent answers; it retrieves and presents. + +Grounding patterns. + +- Retrieval-augmented generation (RAG). The bot searches a knowledge base for relevant content before generating a response. The response is grounded in retrieved content. +- Source-of-truth design. The knowledge base is the canonical source. When the bot answers, the underlying source is identified. +- Citation discipline. The bot can cite the source ("based on our pricing page, ..."). Audiences benefit from knowing where the answer came from. +- Knowledge-base maintenance. The knowledge base is maintained as the product evolves; the bot's answers stay current. + +The hallucinating-bot failure. No grounding. The LLM generates confident-sounding answers from nothing. The team discovers wrong answers through customer complaints. + +The structured-guided win. Grounded answers. The bot's responses match the source-of-truth. Customer-facing accuracy is maintained. + +Detail in [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md). + +--- + +## Branching and conditional logic + +How the bot adapts the conversation based on user input. + +The principle. The bot's conversation can branch based on user inputs (intent recognized, prior answers, user attributes). Branching makes the conversation feel adaptive. + +Branching patterns. + +- Intent-driven branching. Different intents lead to different conversation flows. +- Context-driven branching. "Are you asking about plan A or plan B?" routes to plan-specific information. +- User-attribute branching. Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB. +- Multi-turn branching. The conversation deepens over turns; later turns build on earlier context. + +Branching discipline. Each branch should add value. Decorative branching (asking for confirmation when none is needed) adds friction. + +Branching limits. Bots that branch too deeply lose users. 3-5 turns is often the practical limit before the user wants resolution. + +Detail in [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md). + +--- + +## Fallback patterns + +What happens when intent is unclear or out-of-scope. + +The principle. Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." + +Fallback patterns. + +- Clarifying question. "Can you tell me more about what you are looking for?" Asks the user to refine; sometimes recovers. +- Suggested intents. "I can help with X, Y, or Z. Were you asking about one of those?" Surfaces what the bot can do. +- Resource handoff. "I cannot answer that, but here is our [documentation page] that covers it." +- Human escalation. "Let me connect you with a human who can help." + +Fallback discipline. Multiple fallback layers. First, try clarification. If unclear after one round, suggest alternatives or escalate. Do not loop the user through 5 clarification attempts. + +The fallback-as-honesty principle. A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers they were given confidently. + +Detail in [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md). + +--- + +## Escalation to human + +When, how, with what context handoff. + +The principle. Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. + +Escalation triggers. + +- User-initiated. "Talk to a human." The bot escalates immediately. +- Out-of-scope intent. The bot recognizes the user's intent is outside its scope; escalates with the intent context. +- Repeated fallback. After 2-3 unclear exchanges, the bot escalates rather than loop. +- Sentiment-driven. The user's sentiment indicates frustration; the bot escalates rather than persist. +- High-stakes topic. Sensitive topics (cancellations, complaints, security) escalate by default. + +Escalation context handoff. When escalating, the bot passes the conversation history and recognized intent to the human. The human does not start from scratch; they pick up where the bot left off. + +The escalation-quality test. Does the human pick up the context smoothly, or do they have to ask the user to repeat everything? The latter signals broken handoff. + +Detail in [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md). + +--- + +## Conversation analytics + +Measuring what the bot is and is not doing well. + +The principle. Track the bot's performance per intent, per fallback, per escalation. The data informs maintenance and design improvements. + +Conversation metrics. + +- Intent recognition rate. What percentage of conversations are correctly classified into intents? +- Resolution rate per intent. What percentage of conversations starting with intent X resolve successfully (user gets the answer they needed)? +- Fallback rate. What percentage of conversations hit fallback? High fallback rates signal intent gaps. +- Escalation rate per intent. What percentage of conversations within each intent escalate? High escalation may signal the intent should not be bot-handled. +- User satisfaction. Post-conversation surveys when feasible. Useful but limited; many users do not respond. + +Diagnostic uses. + +- High fallback rate: intents missing or unclear; expand or refine intent set. +- Low resolution rate per intent: knowledge base inadequate; improve grounding. +- High escalation rate per intent: the intent may not be appropriate for bot handling. +- High repeat-fallback within conversations: clarifying questions not landing; redesign clarification. + +Detail in [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md). + +- "Bot makes up answers about pricing." Hallucinating-bot pattern; no grounding to pricing source-of-truth. +- "Users say the bot is rigid and unhelpful." Scripted-bot pattern; intents do not cover real questions. +- "Sales is angry that the bot is qualifying leads wrong." Intent recognition or routing logic broken; audit qualification flow. +- "Support tickets increase after chatbot launch." Bot is producing wrong answers that send users to support; audit grounding and resolution. +- "Users abandon mid-conversation." Bot loops or fallback patterns are inadequate. +- "We cannot tell what the bot is actually doing." Analytics missing; instrument before further changes. +- "Bot was great at launch; quality has degraded." Maintenance lapse; knowledge base or intent set out of date. +- "Bot escalates to humans for everything." Escalation logic too permissive; bot should handle more. +- "Bot tries to handle everything itself." Escalation logic too restrictive; bot should escalate more. +- "Users complain the bot does not know what they asked five minutes ago." Conversation context not preserved across turns. + +--- + +## The framework: 12 considerations for chatbot flow design + +When designing or auditing a chatbot, walk these 12 considerations. + +1. The chatbot decision. Is a chatbot the right tool for this audience and conversation, or would a different channel serve? +2. Structured-guided-conversation, not scripted or hallucinating. Intent architecture; knowledge-base grounding; fallback discipline. +3. Intent architecture sound. Named intents with clear scope; coverage targets 70-90 percent of expected conversations. +4. Knowledge-base grounded. Responses retrieved from source-of-truth; the bot does not invent answers. +5. Branching adds value. Each branch serves a real need; depth limited to 3-5 turns. +6. Fallback patterns multi-layered. Clarification, suggested intents, resource handoff, human escalation. +7. Escalation triggers defined. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. +8. Escalation context handoff clean. Humans pick up where the bot left off. +9. Analytics instrumented. Per-intent recognition, resolution, fallback, escalation rates. +10. Maintenance cadence defined. Knowledge base refreshed; intent set audited; bot quality verified. +11. Brand voice consistent. The bot sounds like the brand it represents. +12. Audience-fit honest. The bot serves the audience it can actually help; out-of-fit audiences get escalated quickly. + +The output of the framework is a chatbot that knows what it knows, grounds its answers in real knowledge, escalates appropriately, and earns trust by being honest about its scope. + +--- + +## Reference files + +- [`references/chatbot-decision-criteria.md`](references/chatbot-decision-criteria.md) - When chatbots earn deployment and when they do not. The conditions that warrant the build. +- [`references/intent-architecture-patterns.md`](references/intent-architecture-patterns.md) - Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. +- [`references/knowledge-base-grounding-patterns.md`](references/knowledge-base-grounding-patterns.md) - Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. +- [`references/branching-and-conditional-logic.md`](references/branching-and-conditional-logic.md) - How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. +- [`references/fallback-pattern-design.md`](references/fallback-pattern-design.md) - What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. +- [`references/escalation-to-human-patterns.md`](references/escalation-to-human-patterns.md) - When, how, with what context. Escalation triggers and handoff quality. +- [`references/conversation-analytics-patterns.md`](references/conversation-analytics-patterns.md) - Per-intent metrics. Diagnostic uses. The data that informs maintenance. +- [`references/chatbot-anti-patterns.md`](references/chatbot-anti-patterns.md) - The patterns that look like chatbots but degrade trust. +- [`references/common-chatbot-failures.md`](references/common-chatbot-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: chatbots earn deployment when they know what they don't know + +The chatbots that work as compounding assets are the ones the audience trusts. Not because they answer every question. Not because they are infinitely capable. Because they are honest about their scope, ground their answers in real knowledge, and escalate to humans when the bot's job is done. + +That is the bar. Below the bar are scripted-bots (rigid trees that fail edge cases) and hallucinating-bots (LLMs without structure that make things up). Above the bar are structured-guided-conversations where the bot's intent architecture, knowledge-base grounding, fallback discipline, and escalation patterns combine into a tool the audience can rely on. + +The discipline is in the design choices. The intents that define what the bot can do. The knowledge-base grounding that prevents hallucination. The fallback patterns that handle the unknown gracefully. The escalation logic that knows when to step aside. The analytics that surface what is working and what is not. The maintenance discipline that keeps the bot in sync with the brand it represents. diff --git a/skills/chatbot-flow-design/references/branching-and-conditional-logic.md b/skills/chatbot-flow-design/references/branching-and-conditional-logic.md new file mode 100644 index 0000000..7ca9f24 --- /dev/null +++ b/skills/chatbot-flow-design/references/branching-and-conditional-logic.md @@ -0,0 +1,269 @@ +# Branching and conditional logic + +How the bot adapts the conversation. Intent-driven, context-driven, user-attribute, multi-turn branching. + +The bot's conversation can branch based on user inputs. Branching makes the conversation feel adaptive; over-branching makes it feel labyrinthine. + +--- + +## The adaptive principle + +The bot adapts the conversation to the user's situation. Branching is the mechanism. + +The win. A user asks about pricing; the bot recognizes the user is on the enterprise track (from earlier inputs or context); the response includes enterprise-specific information rather than starter-tier information. + +The fail (no branching). Every user gets the same response regardless of context. The pricing question gets a generic answer that helps no one specifically. + +The fail (over-branching). The conversation branches at every turn; the user feels stuck in a labyrinth; resolution recedes. + +The discipline. Branch when branching adds value. Avoid branching when it adds friction. + +--- + +## Pattern A: Intent-driven branching + +Different intents lead to different conversation flows. + +How it works. + +- The bot recognizes the user's intent. +- The conversation flow for that intent kicks in. +- Each intent has its own scripted or templated response pattern. + +Example. + +User: "How much does the Pro plan cost?" +Bot recognizes "pricing question" intent. +Bot routes to pricing-conversation flow: +- Retrieves pricing. +- Presents Pro plan pricing. +- Offers follow-up: "Would you like to compare with other tiers, or talk to sales for a custom quote?" + +Strengths. + +- Each intent gets a dedicated, optimized flow. +- Easy to maintain (changes to one intent do not affect others). + +Weaknesses. + +- Requires intent recognition to work reliably. +- Cross-intent topics may not fit any single flow. + +When to use. Default for most chatbots. Intent-driven branching is the foundation. + +--- + +## Pattern B: Context-driven branching + +Branching within an intent based on context. + +How it works. + +- Within an intent's flow, the bot asks clarifying questions or branches based on context. +- "Are you asking about plan A or plan B?" routes the rest of the conversation to plan-specific information. + +Example. + +User: "How does the API work?" +Bot recognizes "integration question" intent. +Within the integration flow, the bot asks: "Are you looking at REST or GraphQL?" +User: "REST." +Bot routes to REST-specific information. + +Strengths. + +- Within-intent precision. +- The user feels heard; the response addresses their specific situation. + +Weaknesses. + +- Each clarifying question adds a turn; can frustrate users who want quick answers. + +The discipline. Use context-driven branching only when the context genuinely affects the response. Decorative clarifications add friction. + +--- + +## Pattern C: User-attribute branching + +Branching based on user attributes (logged-in status, role, segment). + +How it works. + +- The bot accesses user attributes (often from a CRM or session data). +- Responses adapt to those attributes. +- "Logged-in users may see different responses than anonymous users; enterprise visitors may see different responses than SMB." + +Example. + +User: "Tell me about your pricing." +Bot detects the user is from a domain associated with an enterprise account. +Bot routes to enterprise-specific pricing conversation: "For teams of 200+, we offer a custom Enterprise plan. Here are the typical components..." + +Strengths. + +- Highly personalized. +- The right information for the right audience. + +Weaknesses. + +- Requires attribute infrastructure (CRM integration, session data). +- Privacy considerations (the bot is using data the user may not have explicitly shared). +- Risk of getting attributes wrong (a freelancer with a corporate domain treated as enterprise). + +When to use. When the attribute infrastructure exists and the personalization genuinely improves the experience. + +--- + +## Pattern D: Multi-turn branching + +The conversation deepens over turns. Later turns build on earlier context. + +How it works. + +- The bot maintains conversation state across turns. +- Each turn's response considers what was said in previous turns. +- The conversation can pivot, deepen, or refocus based on the cumulative context. + +Example. + +Turn 1. +User: "I am evaluating CRMs." +Bot: "What size is your team?" +User: "We have 25 sales reps." + +Turn 2. +Bot: "For a team of 25, our Growth plan often fits. Are you looking at any specific features?" +User: "We need integration with HubSpot." + +Turn 3. +Bot: "Our HubSpot integration supports two-way sync, lead routing, and custom fields. Would you like to see a demo focused on this integration?" + +The conversation deepens. Each turn builds on the previous. + +Strengths. + +- Conversation feels natural. +- Bot can handle complex inquiries that require multiple inputs. + +Weaknesses. + +- Conversation state management is complex. +- Long conversations risk losing context. +- Users may want resolution faster than multi-turn allows. + +The discipline. Limit multi-turn conversations to 3-5 turns before either resolving, escalating, or offering a summary handoff. Beyond that, users abandon. + +--- + +## Branching depth limits + +Bots that branch too deeply lose users. + +The 3-5 turn principle. Most users want resolution within 3-5 turns. Beyond that, the bot's value declines. + +When 3-5 turns is enough. Most marketing-site Q&A, simple support, qualification. + +When more turns are needed. Complex troubleshooting, detailed product configuration. In these cases, the bot should consider escalating to a human or offering a richer interface (form, video walkthrough). + +Branching as turn-cost. Each branch adds a turn. Branches that do not resolve within the turn budget should be reconsidered. + +--- + +## Branching design patterns + +How to structure branches. + +Linear branching. A then B then C. Simple; fits intent-driven patterns. + +Tree branching. A leads to B or C; each leads to further options. Common; fits context-driven and user-attribute patterns. + +Loop-back branching. Conversation can return to earlier turns. Useful when users want to compare options. + +Open-ended branching. Conversation can take multiple paths from any point. Most flexible; hardest to maintain. + +The choice depends on conversation complexity. Most chatbots benefit from tree branching with limited depth. + +--- + +## Branching and brand voice + +The bot's voice should stay consistent across branches. + +The principle. Branching changes the conversation's content; the brand voice stays consistent. + +Voice failures across branches. + +- One intent's flow is formal; another is casual. Inconsistent. +- Bot voice shifts based on user attributes in ways that feel performative. +- Branches that adopt different personas confuse the user. + +The discipline. Voice consistent; content adaptive. + +--- + +## Conversation state management + +What the bot remembers across turns. + +Within-conversation state. + +- Recognized intent and sub-intent. +- Captured user inputs (company size, role, specific interests). +- Conversation history. +- Pending follow-up actions. + +Across-conversation state. When the user returns later (in the same session or a new session), what does the bot remember? + +- Logged-in users: bot may remember previous conversations. +- Anonymous users: bot typically starts fresh; some implementations use cookies for limited memory. +- Privacy considerations: cross-session memory should be transparent and opt-in where appropriate. + +The discipline. State management should serve the user. State that improves the experience is good; state that surprises or feels invasive is bad. + +--- + +## Branching testing + +Test the bot across branching paths. + +The challenge. A bot with multiple branching points has many paths through any given conversation. Testing all paths is infeasible; testing critical paths is the discipline. + +Critical paths. + +- The most common conversation patterns (most-frequent intents). +- Each major branch point (one path that takes each branch). +- Edge cases (unusual user inputs that could break branching). + +Testing methods. + +- Manual testing of critical paths. +- Automated testing where feasible. +- Sampling production conversations to verify branching behavior. + +--- + +## Common branching failures + +Decorative branching. Clarifying questions that do not change the response; user feels stuck. + +Branching without resolution. Conversation branches but never resolves; user gives up. + +Branching depth too deep. 8+ turns without resolution; user abandons. + +Inconsistent voice across branches. Different intents speak differently. + +State loss across turns. Bot forgets earlier context; conversation feels disjointed. + +Privacy-violating attribute branching. Bot uses attributes the user did not consent to share. + +Untested edge-case branches. Specific paths break in production. + +--- + +## Methodology-level choices that stay in the public skill + +The adaptive principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Branching depth limits. Branching design patterns. Branching and brand voice. Conversation state management. Branching testing. Common failures. + +## Implementation choices that stay internal + +Specific branching designs for specific bots. Specific state management implementations. Specific tooling for branching and testing. The team's testing protocols. These vary by team. diff --git a/skills/chatbot-flow-design/references/chatbot-anti-patterns.md b/skills/chatbot-flow-design/references/chatbot-anti-patterns.md new file mode 100644 index 0000000..52d7dda --- /dev/null +++ b/skills/chatbot-flow-design/references/chatbot-anti-patterns.md @@ -0,0 +1,224 @@ +# Chatbot anti-patterns + +The patterns that look like chatbots but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The scripted-bot + +The pattern. Rigid decision tree. "Press 1 for X, 2 for Y." Fails the moment a user phrases something the script did not anticipate. + +The signal. Users complain the bot is rigid; bot fails any conversation that does not match the predefined paths. + +The cost. The user's actual question goes unanswered. The bot pushes the user through paths that do not fit. Audience leaves with a worse experience than no bot. + +The cure. Move from rigid trees to LLM-powered intent recognition with grounded responses. Detail in `references/intent-architecture-patterns.md` and `references/knowledge-base-grounding-patterns.md`. + +--- + +## The hallucinating-bot + +The pattern. LLM-powered with no structure. Confidently answers questions about pricing, policy, capabilities, and frequently makes up answers. + +The signal. Customer complaints about wrong information from the bot; sales or support hearing audiences cite incorrect bot answers. + +The cost. Liability risk. Trust damage. Support burden when wrong answers reach customers. + +The cure. Add intent architecture and knowledge-base grounding. The bot retrieves from sources-of-truth rather than generating from training data. + +--- + +## The bot-that-tries-to-handle-everything + +The pattern. Bot scope is "anything the user asks." No defined intents; no fallback discipline. + +The signal. High hallucination rate; high resolution-rate variability across topics; users get inconsistent experiences. + +The cost. The bot is unreliable. Some conversations work; many do not. Users cannot predict what they will get. + +The cure. Define explicit intent scope. Honest fallback for everything outside scope. Detail in `references/intent-architecture-patterns.md`. + +--- + +## The bot-that-handles-nothing + +The pattern. Bot's intent set is so narrow that most conversations fall to fallback or escalation. + +The signal. High fallback rate; high escalation rate; bot adds little value over a contact form. + +The cost. The build cost was significant; the value delivered is small. + +The cure. Expand the intent set to cover the conversations the audience actually has. Detail in `references/intent-architecture-patterns.md` (intent coverage section). + +--- + +## The bot-that-loops + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. Detail in `references/fallback-pattern-design.md` (fallback loop section). + +--- + +## The bot-that-refuses-rigidly + +The pattern. Bot says "I cannot help with that" without offering paths forward. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer alternatives. Resource handoff or human escalation. The bot's "I cannot help" should be followed by "but here is what might." + +--- + +## The bot-with-no-escalation + +The pattern. Bot tries to handle everything itself; rarely escalates; users get stuck with bot for conversations needing humans. + +The signal. Specific intents have high abandonment; users complaining they could not reach a human; sensitive topics handled poorly by the bot. + +The cost. The user's frustration compounds. The brand earns "you cannot reach a human" reputation. + +The cure. Define escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## The bot-that-escalates-everything + +The pattern. Bot escalates almost every conversation; the bot is not really doing its job. + +The signal. Escalation rate near 100 percent; bot adds friction without value. + +The cost. The bot is decorative. The team built a chatbot when they needed staffing. + +The cure. Either expand the bot's intent handling capability or reconsider whether the chatbot is the right tool. Sometimes the answer is to invest in human chat instead. + +--- + +## The bot-with-broken-handoff + +The pattern. Bot escalates; human picks up; the human starts from scratch because the context was not passed. + +The signal. Users complain about repeating themselves; humans report not knowing what the bot was discussing. + +The cost. The escalation experience is broken. Users feel the bot was wasted effort. + +The cure. Test the handoff. Ensure the human sees the conversation history and recognized intent. Detail in `references/escalation-to-human-patterns.md` (context handoff section). + +--- + +## The bot-with-stale-knowledge + +The pattern. Knowledge base not updated; bot answers reflect outdated reality. + +The signal. Bot answers contradict current product; users notice; sales hears about wrong information. + +The cost. Trust damage. Each wrong answer is a moment the brand lost credibility. + +The cure. Knowledge-base maintenance discipline. Quarterly review at minimum. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## The bot-with-no-citation + +The pattern. Bot generates answers without citing sources. Users cannot verify. + +The signal. Hallucination goes undetected because there is no verification path; users with deeper questions abandon because they cannot follow up. + +The cost. Trust does not compound. Each answer is taken on faith; some are wrong. + +The cure. Citation discipline. Bot cites sources; users can verify. Detail in `references/knowledge-base-grounding-patterns.md` (citation discipline section). + +--- + +## The bot-with-inconsistent-voice + +The pattern. Different intents speak in different voices. Bot voice does not match brand voice elsewhere. + +The signal. Users report the bot feels disjointed; brand voice is fragmented. + +The cost. Brand consistency suffers. The bot is a brand surface that is undermining the brand. + +The cure. Brand voice document including bot examples. Test conversations across intents. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The bot-with-no-analytics + +The pattern. Bot launched without per-intent tracking. Quality is invisible. + +The signal. Cannot diagnose issues; cannot track decay; remediation is guesswork. + +The cost. Quality decays unnoticed. Maintenance happens only when customers complain (too late). + +The cure. Instrument before launch. Per-intent recognition, resolution, fallback, escalation rates. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## The bot-that-pretends-to-be-human + +The pattern. Bot does not disclose it is a bot; users think they are talking to a human. + +The signal. Users feel deceived when they realize; complaints about hidden automation; trust collapse. + +The cost. Trust damage that can be hard to recover. Brand earns "deceptive" descriptors. + +The cure. Disclose that the user is talking to a bot. Modern AI chatbots can be disclosed openly without losing engagement; users often appreciate the honesty. + +--- + +## The bot-with-mobile-broken-UI + +The pattern. Bot works on desktop; UI breaks on mobile. Conversation cramped; input field hidden; responses overflow. + +The signal. Mobile conversation completion is significantly lower than desktop. + +The cost. Mobile audience underserved. Mobile is often the majority of traffic. + +The cure. Mobile-first chatbot UI design. Test on actual devices. + +--- + +## The bot-without-availability-disclosure + +The pattern. Bot escalates to humans without communicating that humans may not be available. + +The signal. Users wait indefinitely for a human; abandonment after escalation; frustration. + +The cost. Escalation creates expectation that is not met. Worse than no escalation. + +The cure. Communicate availability honestly. "Our team is available [hours]." Or offer async alternatives. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active bot, looking specifically for these anti-patterns. + +Audit questions per bot. + +- Does the bot have explicit intents (anti-pattern check: bot-that-tries-to-handle-everything, hallucinating-bot)? +- Are responses grounded in source-of-truth (anti-pattern check: hallucinating-bot, bot-with-no-citation)? +- Does fallback have multiple layers including escalation (anti-pattern check: bot-with-no-escalation, bot-that-loops)? +- Does escalation pass context (anti-pattern check: bot-with-broken-handoff)? +- Is the knowledge base maintained (anti-pattern check: bot-with-stale-knowledge)? +- Is brand voice consistent across intents (anti-pattern check: bot-with-inconsistent-voice)? +- Are analytics in place (anti-pattern check: bot-with-no-analytics)? +- Does the bot disclose its nature and human availability (anti-pattern check: bot-that-pretends-to-be-human, bot-without-availability-disclosure)? + +The retire decision. Anti-pattern bots often warrant retirement or significant redesign. Patching anti-patterns rarely produces a good bot. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/chatbot-flow-design/references/chatbot-decision-criteria.md b/skills/chatbot-flow-design/references/chatbot-decision-criteria.md new file mode 100644 index 0000000..501d77a --- /dev/null +++ b/skills/chatbot-flow-design/references/chatbot-decision-criteria.md @@ -0,0 +1,163 @@ +# Chatbot decision criteria + +When chatbots earn deployment and when they do not. The conditions that warrant the build, and the funnels where a chatbot adds friction without lift. + +A chatbot is a meaningful build. Intent architecture, knowledge-base grounding, fallback patterns, escalation logic, ongoing maintenance. The chatbot earns this investment only when specific conditions are present. + +--- + +## When chatbots earn deployment + +Five conditions that, when present, make a chatbot a strong investment. + +The audience asks the same questions repeatedly. FAQ-style support, product capability questions, qualification routing. The bot handles the volume; humans handle the exceptions. Without recurring question patterns, the bot has nothing to handle reliably. + +The audience is on the site at hours when humans cannot respond. Coverage gap that the bot fills meaningfully. Off-hours visitors get something instead of nothing. + +The bot can ground its answers in real knowledge. Documentation, product specs, pricing pages, support articles. Without grounding, the bot's answers are at best generic and at worst fabricated. + +The team can maintain the bot. Intents drift; knowledge bases need updating; conversation patterns shift. Without maintenance commitment, the bot becomes stale liability. + +The success metric is defined. Resolution rate, fallback rate, escalation rate, user satisfaction, downstream conversion. Without the success metric defined, evaluation is impossible. + +When all five are present, the chatbot is a strong investment. When two or fewer are present, a different channel (human chat, structured FAQ, contact form) often serves better. + +--- + +## When chatbots do NOT earn deployment + +Funnels where the chatbot is the wrong tool. + +The audience expects human conversation. Sales conversations, complex troubleshooting, sensitive topics often warrant human-first. A chatbot in these contexts may be perceived as an obstacle to the human conversation the audience wants. + +The team cannot ground the bot in real knowledge. A bot without grounding either hallucinates (confident wrong answers) or stays so generic it adds no value (vague responses to specific questions). + +The bot would replace working human channels. Replacing a high-quality sales chat with a low-quality bot degrades the experience. The bot might be cheaper to operate but more expensive in lost conversions. + +The audience is small enough that direct human conversation is more efficient. Niche audiences with low conversation volume often work better with human-first channels; the chatbot's overhead is not justified. + +The team cannot maintain the bot. Stale bots produce wrong answers. Without quarterly maintenance commitment, the bot becomes a liability over time. + +The conversation pattern is too varied to model. Some audiences ask wildly different questions; the intent architecture cannot meaningfully cover the conversation space; the bot mostly fallbacks anyway. + +The honest assessment matters more than the default. "Should we have a chatbot" is not the question. "Is the chatbot the right tool for this audience and conversation pattern" is. + +--- + +## The opportunity-cost frame + +A chatbot is significant work. Account for the cost honestly. + +The build cost. Intent architecture, knowledge-base preparation, RAG pipeline, fallback design, escalation logic, conversation UI, brand-voice tuning, mobile responsiveness, analytics instrumentation. A meaningful chatbot often takes 80-300 engineering hours plus design and content for the knowledge base. + +The maintenance cost. Knowledge base updates, intent refinement, hallucination detection, conversation analytics review. Quarterly maintenance often runs 8-20 hours per active bot. + +The escalation infrastructure cost. Human handoff requires staffing or routing infrastructure. The bot does not eliminate the need for humans; it changes when humans are involved. + +The opportunity cost. What else could the team have built? A better support documentation site, a self-serve help center, a different growth-tooling investment. The chatbot's success has to clear the bar of those alternatives. + +The decision frame. The chatbot earns investment when it produces more value than the alternatives, accounting for build plus maintenance plus escalation infrastructure. + +--- + +## The grounding precondition + +Without knowledge-base grounding, the chatbot is the wrong tool. + +The check. Does the team have or can the team build a knowledge base that covers the conversation patterns the bot will handle? + +If yes, the chatbot can be grounded. The bot's responses retrieve from the knowledge base; hallucination risk is contained. + +If no (the team's knowledge is in people's heads, not documented), the chatbot will hallucinate or stay generic. The bot is the wrong tool until the knowledge base exists. + +Building the knowledge base. Sometimes the right move is to build the knowledge base first (which itself is valuable as documentation) before deploying the bot. The knowledge base serves users directly even before the bot accesses it. + +--- + +## The decision worked example + +A B2B SaaS company considering a chatbot for the marketing site. + +Conditions check. + +- Recurring questions: yes. Visitors ask about pricing, integrations, security, and demo requests recurringly. +- Off-hours coverage gap: yes. The team handles US business hours; international visitors get nothing in their evening hours. +- Knowledge-base grounding possible: yes. Pricing, integrations, security details all documented; FAQ exists; product specs are detailed. +- Maintenance commitment: yes. Marketing operations has capacity for quarterly bot review. +- Success metric defined: yes. Resolution rate per intent, escalation rate, downstream conversion to demo within 14 days. + +Decision. Build the chatbot. The conditions warrant it. + +Intent architecture. 7 named intents: pricing, integrations, security, demo request, support escalation, integration troubleshooting, account access. + +Knowledge-base grounding. RAG pipeline pulling from docs, pricing page, security page, integration catalog. + +Fallback strategy. Clarification on first unclear; suggested intents on second unclear; escalation to human on third or sentiment-driven. + +Escalation handoff. Bot passes conversation history and recognized intent to the human; the human picks up where the bot left off. + +The decision was not "should we have a chatbot" but "given these conditions, this is the chatbot to build." + +--- + +## The decision worked example: when to choose differently + +The same company considering a chatbot for sales conversations. + +Conditions check. + +- Recurring questions: partially. Sales conversations vary widely; while some patterns recur, the conversation often needs nuance. +- Off-hours coverage: not relevant; sales conversations work async via demo bookings already. +- Knowledge-base grounding possible: yes for product info; less so for personalized recommendations. +- Maintenance commitment: yes. +- Success metric: hard to define. Sales conversion is the goal; the bot's contribution is hard to attribute. + +Decision. Do not build a sales-focused chatbot. The audience expects human sales conversation; the bot would add friction. Use the bot for marketing-site Q&A and demo qualification; route demo requests to human sales. + +The decision was "is this chatbot right for this conversation" and the answer was "for some conversations yes, for others no." The bot's scope was constrained accordingly. + +--- + +## The audience-fit precondition + +The chatbot's audience must be willing to interact with chatbots. + +Audiences that engage with chatbots well. + +- Self-service-oriented users who want quick answers without human contact. +- Off-hours visitors who would otherwise get nothing. +- Users with specific factual questions (pricing, hours, policies). + +Audiences that resist chatbots. + +- Users who explicitly want to talk to a human (often signaled in the conversation opening). +- Sales-focused enterprise buyers expecting white-glove human attention. +- Users in distress (frustration, urgency) who need empathy not automation. + +The discipline. The chatbot should serve the audiences who engage well and escalate the audiences who do not. Trying to serve everyone with the bot fails both groups. + +--- + +## When to retire a chatbot + +Chatbots can be wrong even after being right initially. + +Retire when: + +- Resolution rate has dropped below an acceptable threshold consistently. +- Escalation rate climbs as intents fail to keep pace with audience evolution. +- The knowledge base maintenance burden exceeds the bot's value. +- A redesigned support model (better docs, expanded human team, different tooling) makes the bot unnecessary. +- The team can no longer commit to maintenance. + +The retiring discipline is part of the program. Stale bots produce wrong answers; honest retirement protects the brand. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant chatbot deployment. The conditions that argue against. The opportunity-cost frame. The grounding precondition. The audience-fit precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific chatbot scope decisions for specific audiences. The team's capacity benchmarks. Specific tooling for chatbot platforms, RAG pipelines, and analytics. Specific success-metric baselines. These vary by team. diff --git a/skills/chatbot-flow-design/references/common-chatbot-failures.md b/skills/chatbot-flow-design/references/common-chatbot-failures.md new file mode 100644 index 0000000..35d1c67 --- /dev/null +++ b/skills/chatbot-flow-design/references/common-chatbot-failures.md @@ -0,0 +1,187 @@ +# Common chatbot failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the bot is hallucinating" or "users complain the bot is unhelpful" or "we cannot tell what the bot is doing." + +--- + +## "Bot makes up answers about pricing." + +The diagnosis. Hallucinating-bot pattern. No grounding to pricing source-of-truth. + +The cure. Add knowledge-base grounding for pricing. The bot retrieves from the pricing page or pricing knowledge base; answers reflect the source. Detail in `references/knowledge-base-grounding-patterns.md`. + +--- + +## "Users say the bot is rigid and unhelpful." + +The diagnosis. Scripted-bot pattern. Intents do not cover real questions; bot fails when users phrase things unexpectedly. + +The cure. Move from rigid trees to LLM-powered intent recognition. Define more flexible intents. Add fallback that handles unexpected phrasings. Detail in `references/intent-architecture-patterns.md`. + +--- + +## "Sales is angry that the bot is qualifying leads wrong." + +The diagnosis. Intent recognition or routing logic broken. The bot is recognizing leads as one type when they should be another. + +The cure. Audit the qualification flow. Verify intent recognition with realistic test cases. Tighten routing logic. Add human review for edge cases. + +--- + +## "Support tickets increase after chatbot launch." + +The diagnosis. Bot is producing wrong answers that send users to support after the fact. Worse than no bot. + +The cure. Audit grounding and resolution. Identify the intents producing bad answers. Either improve grounding or escalate those intents to humans. Detail in `references/knowledge-base-grounding-patterns.md` and `references/escalation-to-human-patterns.md`. + +--- + +## "Users abandon mid-conversation." + +The diagnosis. Bot loops or fallback patterns are inadequate. Users get stuck without resolution path. + +The cure. Review fallback patterns. Limit clarification rounds. Add multi-layered fallback ending in human escalation. Detail in `references/fallback-pattern-design.md`. + +--- + +## "We cannot tell what the bot is actually doing." + +The diagnosis. Analytics missing. Without instrumentation, quality is invisible. + +The cure. Instrument per-intent recognition, resolution, fallback, and escalation rates before any further changes. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot was great at launch; quality has degraded." + +The diagnosis. Maintenance lapse. Knowledge base or intent set out of date. + +The cure. Quarterly maintenance review. Update knowledge base; refine intents; verify grounding. Set the maintenance trigger so updates happen alongside product changes. + +--- + +## "Bot escalates to humans for everything." + +The diagnosis. Escalation logic too permissive, or the bot's intent handling is so weak that everything ends up at humans. + +The cure. Audit which intents escalate most. If the bot can handle them with better grounding, fix that. If the bot truly cannot handle them, reconsider whether they should be in scope. + +--- + +## "Bot tries to handle everything itself." + +The diagnosis. Escalation logic too restrictive. Bot stays with conversations it should not. + +The cure. Add escalation triggers. User-initiated, out-of-scope, repeated fallback, sentiment-driven, high-stakes. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Users complain the bot does not know what they asked five minutes ago." + +The diagnosis. Conversation context not preserved across turns. Bot treats each message as standalone. + +The cure. Implement conversation state management. Bot remembers earlier turns within the same conversation; later responses build on that context. Detail in `references/branching-and-conditional-logic.md` (conversation state management section). + +--- + +## "Bot gives different answers to the same question." + +The diagnosis. Either grounding is inconsistent (different retrievals for similar queries), or the LLM generation has variability that produces different answers. + +The cure. Review grounding pipeline. Verify retrieval consistency. Tune generation parameters for consistency. Audit specific cases. + +--- + +## "We tried the bot in our pricing page; conversion went down." + +The diagnosis. Bot may be adding friction to a flow that worked. Some pages benefit from chatbots; some do not. + +The cure. A/B test bot presence vs absence on the affected pages. The data informs whether the bot is the right tool there. + +--- + +## "Bot ignores the user when sentiment is negative." + +The diagnosis. No sentiment-driven escalation. Bot continues handling conversations where the user is frustrated. + +The cure. Add sentiment-driven escalation. Recognize frustration signals; escalate to human. Detail in `references/escalation-to-human-patterns.md`. + +--- + +## "Sales team finds qualification bot data unreliable." + +The diagnosis. Bot's qualification logic does not match sales-team criteria, or recognition is misclassifying leads. + +The cure. Align bot qualification with sales criteria. Audit recognition with sales feedback. Update intents and routing. + +--- + +## "We added a chatbot; our overall site conversion dropped." + +The diagnosis. Bot may be displacing higher-converting paths (direct CTAs, contact forms). Bot is the wrong tool for this audience or page. + +The cure. A/B test bot presence vs absence at the funnel level. If the bot reduces conversion, reconsider its placement or scope. + +--- + +## "Bot answers correctly but conversation never closes." + +The diagnosis. No clear conversation-end pattern. Bot keeps offering more help; user does not know when to stop. + +The cure. Add explicit conversation closing. "Anything else I can help with?" "If not, [next step option]." Detail in fallback patterns. + +--- + +## "We migrated platforms; the bot quality dropped." + +The diagnosis. Platform migration may have broken intent recognition, knowledge base integration, or escalation routing. + +The cure. Test the migrated bot end-to-end before declaring it ready. Critical paths first. Roll back if quality dropped significantly. + +--- + +## "Mobile conversations end with no resolution." + +The diagnosis. Mobile UI may be breaking; or the bot's responses may be too long for mobile screens. + +The cure. Mobile UI testing. Audit response lengths. Mobile-specific UI adjustments. + +--- + +## "We cannot tell which intents need work." + +The diagnosis. Analytics aggregated rather than per-intent. The intent-level signal is hidden. + +The cure. Per-intent analytics. Recognition rate, resolution rate, escalation rate, hallucination rate per intent. Detail in `references/conversation-analytics-patterns.md`. + +--- + +## "Bot's voice does not sound like our brand." + +The diagnosis. Bot is using generic LLM voice; brand voice was not specifically tuned. + +The cure. Brand voice document including bot examples. Tune bot prompts and response patterns to match. Detail in `references/intent-architecture-patterns.md` (intent and brand voice section). + +--- + +## The pattern across failures + +Most chatbot failures fall into one of three patterns. + +Pattern 1: The bot does not have proper architecture. Hallucinating, scripted, no grounding, no fallback discipline. The fix is structural. + +Pattern 2: The bot does not match the audience or context. Bot in wrong context, wrong voice, wrong scope for audience. The fix is matching the bot to where it serves. + +Pattern 3: The bot decays. Knowledge base stale, intent set frozen, no maintenance. The fix is maintenance discipline. + +The metric pattern: chatbot failures often look fine on conversation count alone. The signal is in resolution rate per intent, hallucination rate, escalation quality, downstream conversion. Programs that track only conversation counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (architecture, audience-context match, decay). The principle that conversation count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/chatbot-flow-design/references/conversation-analytics-patterns.md b/skills/chatbot-flow-design/references/conversation-analytics-patterns.md new file mode 100644 index 0000000..5775305 --- /dev/null +++ b/skills/chatbot-flow-design/references/conversation-analytics-patterns.md @@ -0,0 +1,272 @@ +# Conversation analytics patterns + +Per-intent metrics. Diagnostic uses. The data that informs maintenance. + +Conversation analytics is the bot's diagnostic system. Without analytics, maintenance is guesswork; intent gaps go unnoticed; hallucination patterns persist; the bot's quality decays without anyone seeing the decay. + +--- + +## The instrumentation principle + +Track the bot's performance per intent, per fallback, per escalation. The data informs every maintenance decision. + +The minimum tracking. + +- Conversation start (a user opens the bot). +- Intent recognition (which intent the bot classified). +- Conversation outcome (resolved, fallback, escalation, abandoned). +- Per-turn data (each user message, each bot response). + +The derived metrics. + +- Intent recognition rate. +- Resolution rate per intent. +- Fallback rate. +- Escalation rate per intent. +- Abandonment rate. + +Without instrumentation, none of this data exists. Set up tracking before launch. + +--- + +## Intent recognition rate + +What percentage of conversations are correctly classified. + +The metric. Of conversations where the user expressed intent, what percentage did the bot recognize correctly? + +Measurement methods. + +- Sample auditing. Periodically sample conversations and verify intent classification manually. +- User feedback signals. Conversations where users complain or escalate often correlate with misrecognized intent. +- Conversation outcome correlation. Conversations resolved successfully often had correct intent recognition. + +Diagnostic uses. + +- Low recognition rate: intent set may not cover real conversations; recognition logic may be brittle. +- Specific intents misrecognized: those intents may be poorly defined or overlap with others. + +Target ranges. 80-90 percent recognition is achievable for well-designed chatbots. Below 70 percent suggests significant intent or recognition issues. + +--- + +## Resolution rate per intent + +What percentage of conversations starting with intent X resolve successfully. + +Resolution definition. The user got the answer they needed and the conversation ended successfully (no escalation, no abandonment, no follow-up indicating frustration). + +Measurement methods. + +- Conversation completion plus user signal. User explicitly says "thanks" or rates the conversation positively. +- No follow-up issues. User does not return with the same question or escalate later. +- Direct survey. Post-conversation survey asking if the user got what they needed. + +Diagnostic uses. + +- Low resolution per intent: the bot's grounding or response pattern for that intent is weak. +- Some intents have higher resolution than others: variation may signal intent design quality differences. + +Target ranges. 70-85 percent resolution per intent is reasonable. Lower for complex intents; higher for simple intents. + +--- + +## Fallback rate + +What percentage of conversations hit fallback at any point. + +The metric. Conversations where the bot's intent recognition failed or the bot's response did not address the user's need, requiring fallback. + +Diagnostic uses. + +- High fallback rate (above 25-30 percent): intent set may be missing common conversations. +- Specific fallback layers triggered disproportionately: that layer needs review. +- Fallback rate trending up: audience evolving away from current intent set. + +Per-layer breakdown. Track which fallback layers (clarification, suggested intents, resource handoff, human escalation) trigger most. Each tells a different story. + +--- + +## Escalation rate per intent + +What percentage of conversations within each intent escalate to humans. + +The metric. Of conversations classified as intent X, what percentage ended with human escalation? + +Diagnostic uses. + +- High escalation rate per intent: the intent may not be appropriate for bot handling; consider removing from bot scope. +- Low escalation rate per intent: bot may be over-handling; some conversations may benefit from earlier escalation. +- Specific intents with rising escalation: maintenance lapse or audience evolution. + +The 100-percent-escalation intent. An intent where the bot always escalates is not a bot intent; it should be a "tell me about [topic]; we will get back to you" intent or removed entirely. + +--- + +## Abandonment rate + +What percentage of conversations end without resolution or escalation (the user just leaves). + +The metric. Conversations where the user stops responding without indicating resolution. + +Diagnostic uses. + +- High abandonment: bot is failing to satisfy users; review fallback patterns and conversation flows. +- Abandonment concentrated at specific turn or intent: that point in the flow is breaking. +- Mid-conversation abandonment vs first-turn abandonment: different diagnostic implications. + +--- + +## User satisfaction + +When measurable, satisfaction is the highest-value metric. + +Measurement methods. + +- Post-conversation rating. "How was that conversation?" with 1-5 stars or thumbs up/down. +- Post-conversation survey. Brief survey after the conversation ends. +- Sentiment analysis. Programmatic analysis of conversation sentiment. + +Diagnostic uses. + +- Low satisfaction: bot is failing the user even when conversations technically complete. +- Satisfaction-resolution mismatch: bot resolves but users are unhappy; quality of resolution is poor. + +Limitations. + +- Many users do not respond to satisfaction surveys. +- Satisfaction can be biased (frustrated users more likely to respond than satisfied ones). +- Sentiment analysis can miss nuance. + +The metric is valuable but not the only signal. + +--- + +## Conversation length distribution + +How many turns the average conversation takes. + +The metric. Distribution of conversation turn count. + +Diagnostic uses. + +- Long average length: bot may be over-clarifying; conversations should resolve faster. +- Bimodal distribution (very short or very long): some conversations resolve quickly; others get stuck. +- Increasing trend: bot quality may be declining; users having to work harder. + +Target ranges. 2-5 turns for typical resolution. Longer for complex intents; shorter for simple ones. + +--- + +## Response time + +How quickly the bot responds. + +The metric. Time between user message and bot response. + +Diagnostic uses. + +- Slow response: user perceives the bot as sluggish; abandonment may climb. +- Variable response time: inconsistent experience; users unsure what to expect. + +Target ranges. Under 2 seconds for most responses. Longer responses (when retrieving or generating) should show typing indicators. + +--- + +## Hallucination tracking + +Specifically tracking when the bot generates wrong answers. + +Detection methods. + +- Sample auditing of bot responses against source-of-truth. +- User reports ("the bot said X; that is not right"). +- Citation verification (programmatic check that cited sources contain the cited content). + +Diagnostic uses. + +- Specific intents with hallucination rate: those intents need grounding review. +- Specific topics within intents: knowledge base may have gaps. +- Hallucination trend: if rate is rising, model or grounding may be drifting. + +The honesty discipline. Track hallucination explicitly. Teams that hide hallucination from themselves ship worse bots. + +--- + +## Conversation funnel + +Track conversations as a funnel from start to resolution. + +The funnel. + +- Conversation started. +- Intent recognized. +- First response delivered. +- User continued. +- Resolution achieved (or escalation, or abandonment). + +Diagnostic uses. Drop-off at each stage points to specific issues. + +- Drop-off after intent recognition: bot's first response is not engaging or is wrong. +- Drop-off mid-conversation: branching or follow-ups are not landing. +- Drop-off near resolution: closing or call-to-action is weak. + +--- + +## Per-segment analytics + +Different audience segments may experience the bot differently. + +Segments. + +- New visitors vs returning. +- Logged-in vs anonymous. +- Mobile vs desktop. +- Source of arrival (paid, organic, referral). + +Diagnostic uses. + +- Segments with worse outcomes signal segment-specific issues. +- Sometimes the right answer is segment-specific bot behavior. + +--- + +## Analytics review cadence + +How often to look at the data. + +Weekly review. For high-volume bots or recently launched bots. Catches regressions and informs rapid iteration. + +Monthly review. For stable bots. Tracks trends and surfaces gradual decay. + +Quarterly review. For all active bots as part of the broader bot audit. + +Triggered review. When intent set changes, when knowledge base updates, when team escalation patterns shift. Ad-hoc reviews catch specific issues. + +--- + +## Common analytics failures + +No instrumentation. Bot launched without per-intent tracking; quality is invisible. + +Vanity metrics. Tracking conversation count without tracking outcome quality. + +Aggregate-only tracking. Conversation rate tracked but not per-intent; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; intent renames or schema changes broke the tracking. + +Confounded data. Multiple changes deployed simultaneously; cannot attribute changes to any one update. + +No segment-level data. Aggregate hides segment-specific issues. + +No hallucination tracking. Bot wrongness goes unnoticed until customers complain. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation principle. Intent recognition rate. Resolution rate per intent. Fallback rate. Escalation rate per intent. Abandonment rate. User satisfaction. Conversation length distribution. Response time. Hallucination tracking. Conversation funnel. Per-segment analytics. Analytics review cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific bots. Specific tooling for analytics implementation. Specific target ranges for the team's audience. The team's audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/references/escalation-to-human-patterns.md b/skills/chatbot-flow-design/references/escalation-to-human-patterns.md new file mode 100644 index 0000000..429ba8d --- /dev/null +++ b/skills/chatbot-flow-design/references/escalation-to-human-patterns.md @@ -0,0 +1,209 @@ +# Escalation to human patterns + +When, how, with what context. Escalation triggers and handoff quality. + +Some conversations need a human. The bot escalates when its scope is exceeded, when the user requests it, or when the conversation pattern indicates the user is frustrated. Escalation done well preserves the conversation's momentum; escalation done poorly resets the user. + +--- + +## The escalation principle + +Escalation is part of the bot's job. A bot that knows when to step aside earns more trust than a bot that tries to handle everything. + +The win. The bot recognizes its scope is exceeded; escalates with the conversation context; the human picks up where the bot left off. + +The fail (no escalation). The bot tries to handle everything; produces wrong answers; the user has to start over with a human eventually. + +The fail (broken escalation). The bot escalates but the human starts from scratch; the user has to repeat everything. + +The discipline. Escalation triggers defined; context handoff clean. + +--- + +## Escalation triggers + +When the bot escalates. + +User-initiated. "Talk to a human." "I need to speak with someone." "Get me a person." + +The bot escalates immediately. Do not try to handle the request first; the user has been explicit. + +Out-of-scope intent. The bot recognizes the user's intent is outside its scope. + +The bot escalates with the intent context. "Looks like you have a [intent type] question; let me connect you with the team." + +Repeated fallback. After 2-3 unclear exchanges, the bot escalates rather than loop. + +The bot acknowledges: "I am having trouble understanding your question; let me get a human who can help." + +Sentiment-driven. The user's sentiment indicates frustration. + +The bot recognizes frustration signals (negative phrasing, repeated complaints, exclamation patterns) and escalates. + +High-stakes topic. Sensitive topics escalate by default. + +Account security, cancellations, complaints, signs of distress. The bot does not try to handle these; immediate escalation. + +Complexity-driven. The user's question requires deep customization or analysis the bot cannot provide. + +The bot acknowledges: "This needs a more detailed look; let me connect you with our team." + +--- + +## The context handoff + +When escalating, the bot passes context to the human. + +What to pass. + +- The conversation history (full transcript). +- The recognized intent (what the bot thought the user wanted). +- The user's situation (any captured attributes: company, role, source). +- The reason for escalation (user-initiated, out-of-scope, sentiment, etc.). +- Any pending follow-up actions. + +The handoff format. + +- Visible to the human in their tool of choice (CRM, support ticket system, chat panel). +- Structured so the human can scan it quickly. +- Accurate (the recognized intent matches what the user actually said). + +The handoff failure. The human picks up the conversation but does not see the context; they ask the user to repeat everything; the user feels the escalation was for nothing. + +The discipline. Test the handoff. The human should pick up the context smoothly. The user should feel the escalation moved them forward, not backward. + +--- + +## Escalation user experience + +What the user sees during escalation. + +The pattern. + +- Bot acknowledges the escalation: "Let me connect you with someone who can help." +- Bot provides expectation: "Someone from our team will be with you in [timeframe]." +- If the wait will be long, bot offers alternatives: "If you do not want to wait, you can [book a call / email us / submit a ticket]." +- Conversation transitions to human cleanly when the human joins. + +The escalation-as-transition principle. The user should feel the conversation continued, not started over. The transition from bot to human is part of the experience. + +--- + +## Escalation and human availability + +What happens when no human is available. + +During business hours. The bot escalates; a human picks up within the expected response time. + +Off-hours. The bot acknowledges: "Our team is available [hours]. I can take your information and have someone respond when they are back." + +During high-volume. The bot acknowledges the wait: "We are seeing high volume right now; expected wait is about [time]." + +The honest framing. The bot communicates availability honestly. Pretending humans are available when they are not creates frustrated users. + +Asynchronous escalation. When the user is willing, async escalation (email, ticket) is often better than waiting in chat. The bot can offer this option proactively. + +--- + +## Escalation routing + +Which human gets the conversation. + +Routing patterns. + +- Single team. All escalations go to one team (often support). Simple but may not match all conversation types. +- Intent-based routing. Different intents route to different teams (sales escalations to sales; support to support). +- Tier-based routing. Different user tiers route to different teams (enterprise to enterprise account managers; SMB to general support). +- Context-based routing. Routing combines intent, tier, and other attributes. + +Routing failures. + +- Wrong team gets the escalation; they have to re-route; user waits longer. +- Routing logic stale; teams have changed but the bot has not. +- Round-robin without consideration of expertise; users get inconsistent quality. + +Routing maintenance. Quarterly review of routing logic alongside team structure changes. + +--- + +## Escalation measurement + +Track escalation rate and quality. + +Metrics. + +- Escalation rate. What percentage of conversations escalate? +- Escalation rate per intent. Some intents may escalate more often than others. +- Time-to-human-pickup. How quickly does the human respond after escalation? +- Resolution after escalation. What percentage of escalated conversations resolve? +- User satisfaction post-escalation. When measurable. + +Diagnostic uses. + +- High escalation rate per intent: that intent may not be appropriate for bot handling. +- Long time-to-human: staffing or routing issues. +- Low resolution after escalation: handoff quality may be poor or the team may not have the resources. + +The data informs both bot maintenance and human team capacity planning. + +--- + +## Bot-to-human transition design + +The moment the human joins the conversation. + +Pattern A: Visible transition. The user sees a message: "Hi, I am [name] from the team. I see you were asking about [topic]; how can I help?" + +The transition is explicit; the user knows they are now with a human. + +Pattern B: Continuous transition. The conversation continues without explicit handoff; the bot's voice fades; the human's voice picks up. + +Less common; can confuse users about who they are talking to. + +Pattern C: Bot stays available. The bot remains in the conversation alongside the human; can be called on for specific information retrieval while the human leads. + +Useful for complex conversations; rare in simple chatbot deployments. + +Pattern A is the default. Explicit transitions reduce confusion. + +--- + +## Escalation back to bot + +Sometimes the conversation can return to the bot after a human handoff. + +When this works. The human resolves the immediate issue; the user has a follow-up question that is bot-handlable; the bot can pick back up. + +When this fails. The user expected human attention; returning to the bot feels like demotion. + +The discipline. Bot-after-human transitions need user consent. "Is there anything else? I can connect you with our chatbot for quick questions, or keep you with me." Let the user choose. + +--- + +## Common escalation failures + +No escalation logic. Bot tries to handle everything; produces wrong answers; users escalate to support after the fact (worse than escalating upfront). + +Escalation without context handoff. Human starts from scratch; user repeats everything. + +Escalation to unavailable humans. Bot creates expectation that is not met; user waits indefinitely or abandons. + +Wrong-team routing. Escalation goes to a team that cannot help; rerouting adds friction. + +Sensitive topics not escalated. Bot tries to handle account security, cancellations, complaints; makes things worse. + +Escalation triggers too restrictive. Bot rarely escalates; users get stuck. + +Escalation triggers too permissive. Bot escalates everything; the bot is not really doing its job. + +No escalation user experience. Transition to human is jarring; user is confused about whether they are still with the bot. + +--- + +## Methodology-level choices that stay in the public skill + +The escalation principle. Escalation triggers (6 patterns). Context handoff discipline. Escalation user experience. Escalation and human availability. Escalation routing. Escalation measurement. Bot-to-human transition design (3 patterns). Escalation back to bot. Common failures. + +## Implementation choices that stay internal + +Specific escalation routing for specific teams. Specific handoff formats and integration with CRM or support tools. Specific brand-voice transition copy. The team's staffing and SLA decisions. These vary by team. diff --git a/skills/chatbot-flow-design/references/fallback-pattern-design.md b/skills/chatbot-flow-design/references/fallback-pattern-design.md new file mode 100644 index 0000000..32163d1 --- /dev/null +++ b/skills/chatbot-flow-design/references/fallback-pattern-design.md @@ -0,0 +1,257 @@ +# Fallback pattern design + +What happens when intent is unclear or out-of-scope. Multi-layered fallback patterns. + +Every conversation has fallback paths. The bot has rehearsed responses for "I do not know," "I am not sure I can help with that," "Let me connect you with a human." Done well, fallback earns trust through honesty; done poorly, fallback frustrates users into abandonment. + +--- + +## The honesty principle + +A bot that admits it does not know earns more trust than a bot that fakes confidence. Audiences forgive limitations they were told about; audiences punish wrong answers given confidently. + +The win. A user asks about a topic outside the bot's scope. The bot says "I cannot help with that, but [here is the right resource or human contact]." The user gets routed to value; the brand earns trust. + +The fail (faked confidence). The bot generates an answer from training data because it has no scope discipline. The answer is wrong; the user finds out later; the brand earns "lying bot" reputation. + +The fail (rigid refusal). The bot says "I cannot help with that" and offers no alternative. The user has nowhere to go. + +The discipline. Honest about limits; helpful about alternatives. + +--- + +## Multi-layered fallback + +Multiple fallback patterns, sequenced. + +Layer 1: Clarifying question. "Can you tell me more about what you are looking for?" + +When to use: when the user's intent is unclear and clarification might resolve. + +When it fails: when the user has already been clear; clarification feels patronizing. + +The discipline: ask clarification once, not repeatedly. + +Layer 2: Suggested intents. "I can help with X, Y, or Z. Were you asking about one of those?" + +When to use: when clarification did not work, or when the user asked something the bot can almost handle. + +When it fails: when the suggestions do not match what the user wanted. + +The discipline: suggest the bot's actual capabilities, not generic options. + +Layer 3: Resource handoff. "I cannot answer that, but here is our [documentation page] that covers it." + +When to use: when the bot cannot help but a self-serve resource exists. + +When it fails: when the resource is not actually relevant. + +The discipline: route to genuinely relevant resources; do not deflect to generic help. + +Layer 4: Human escalation. "Let me connect you with a human who can help." + +When to use: when self-serve will not work or the user has expressed frustration. + +When it fails: when no human is available; the escalation creates an expectation that does not get met. + +The discipline: escalate to humans only when humans are available; otherwise communicate the wait. + +--- + +## Layer sequencing + +The order matters. + +Standard sequence. + +1. Recognize intent. If recognized, handle. +2. If not recognized, try clarification (Layer 1). +3. If clarification fails, suggest intents (Layer 2). +4. If suggestions fail, offer resources (Layer 3). +5. If resources do not match, escalate (Layer 4). + +Sequence variations. + +- High-stakes topics may skip to Layer 4 immediately. +- User-initiated escalation ("talk to a human") goes to Layer 4 immediately. +- Frustrated sentiment may trigger Layer 4 sooner. + +--- + +## Anti-pattern: fallback loop + +Multiple clarification attempts that go nowhere. + +The pattern. Bot does not understand; asks for clarification; user clarifies; bot still does not understand; asks again; loop. + +The signal. Users abandon mid-conversation after 2-3 unsuccessful clarification attempts. + +The cost. The user feels stuck. The brand earns "frustrating bot" reputation. + +The cure. Limit clarification to one round. After that, escalate or offer alternatives. The bot's job is to resolve or hand off, not to keep asking the same question. + +--- + +## Anti-pattern: rigid refusal + +Bot says "I cannot help" and offers no path forward. + +The pattern. User asks something out of scope; bot says "I cannot help with that"; conversation ends. + +The signal. Users complain that the bot is unhelpful; abandonment. + +The cost. The bot fails the user without offering recovery. + +The cure. Always offer an alternative. Resource handoff or human escalation. The bot's "I cannot help" should be followed immediately by "but here is what might." + +--- + +## Fallback copy discipline + +What the fallback messages say. + +Helpful fallback copy. + +- "I am not sure I caught that. Are you asking about [option 1] or [option 2]?" +- "I can answer questions about pricing, integrations, or features. Was your question about one of those?" +- "I cannot answer that specifically. Our team can help; would you like me to connect you?" + +Unhelpful fallback copy. + +- "I do not understand." +- "Please rephrase." +- "Sorry, I cannot help with that." + +The voice discipline. Fallback copy should sound like the brand. Apologetic but not groveling; honest but not curt; helpful but not desperate. + +--- + +## Fallback for sensitive topics + +Some topics warrant immediate escalation regardless of bot capability. + +Sensitive triggers. + +- Account security ("my account was hacked," "I think I was charged wrong"). +- Cancellation ("I want to cancel my subscription"). +- Complaints ("I want to speak to a manager"). +- Crises (any indication of user distress). + +The pattern. The bot recognizes the sensitive topic and escalates immediately rather than attempting to handle. + +Why this matters. Sensitive topics need human empathy. A bot trying to handle them often makes things worse. Immediate escalation protects the user and the brand. + +--- + +## Fallback during human unavailability + +What happens when the user wants a human but no human is available. + +The honest options. + +- "Our team is available [hours]. Can I take a message they can respond to when they are back?" +- "We are not available right now. You can [submit a ticket / book a call / email us]." +- "I can help with [list of topics]; for [out-of-scope topic], please reach out to [channel] directly." + +The dishonest option. + +- Pretending a human is available when they are not. The user waits, gets frustrated, abandons. + +The discipline. Communicate availability honestly. Set the expectation upfront if humans cannot respond immediately. + +--- + +## Fallback measurement + +Track fallback rate as a key metric. + +The metric. What percentage of conversations hit fallback at any point? + +Diagnostic uses. + +- High fallback rate (above 25-30 percent): intents are missing or recognition is poor. +- Specific fallback layers triggered disproportionately: that layer needs design review. +- Fallback escalation rate (what percentage of fallbacks lead to human escalation): high rates may signal the bot is doing less than it should; low rates may signal users abandoning rather than escalating. + +The fallback-as-signal principle. Fallback is not failure; it is the bot honestly recognizing limits. The signal is in the fallback patterns and what they reveal about intent gaps. + +--- + +## Fallback maintenance + +Fallback decays. + +What decays. + +- Suggested intents that no longer reflect the bot's actual capabilities. +- Resource links that have moved or broken. +- Escalation routing that no longer matches the team structure. + +Maintenance cadence. Quarterly review of fallback messages, suggested intents, resource links, and escalation routing. + +The drift indicator. User feedback about unhelpful fallback responses; broken links in the fallback flow; escalations going to wrong teams. + +--- + +## Fallback and brand voice + +Fallback responses are an opportunity for brand voice. + +The principle. Fallback is when the bot is most likely to lose the user. Brand voice in fallback can recover the moment. + +Voice in fallback. + +- Acknowledge the limitation honestly. +- Maintain warmth (do not become cold or robotic when failing to help). +- Offer the path forward with the same voice as the rest of the conversation. + +The voice failure. Fallback messages that sound generic; bot loses voice exactly when voice matters most. + +--- + +## Fallback testing + +Test the fallback flow as carefully as the success flow. + +Test cases. + +- User asks something clearly out of scope. +- User asks something on the edge of scope. +- User asks something within scope but phrased unusually. +- User explicitly asks for a human. +- User shows frustration in their messages. +- User asks during off-hours. + +The testing discipline. Each fallback layer should be tested with realistic triggers. + +--- + +## Common fallback failures + +No fallback patterns. Bot has no rehearsed responses for unknown intents; generates whatever the LLM produces. + +Single-layer fallback. Only "I do not understand" without alternatives. + +Fallback loops. Bot keeps asking clarification; user gets stuck. + +Rigid refusal. Bot says "I cannot help" without offering paths. + +Generic fallback copy. Fallback messages do not match brand voice. + +Stale resource links. Resource handoff points to broken URLs. + +Wrong escalation routing. Bot escalates to teams that are not appropriate. + +Hidden human availability. Bot does not communicate when humans are or are not available. + +Sensitive topics not escalated. Bot tries to handle topics that need human empathy. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Multi-layered fallback (4 layers with when to use). Layer sequencing. Anti-patterns (fallback loop, rigid refusal). Fallback copy discipline. Fallback for sensitive topics. Fallback during human unavailability. Fallback measurement. Fallback maintenance. Fallback and brand voice. Fallback testing. Common failures. + +## Implementation choices that stay internal + +Specific fallback messages for specific bots. Specific suggested intents and resource links. Specific escalation routing logic. The team's brand-voice fallback templates. These vary by team. diff --git a/skills/chatbot-flow-design/references/intent-architecture-patterns.md b/skills/chatbot-flow-design/references/intent-architecture-patterns.md new file mode 100644 index 0000000..2733529 --- /dev/null +++ b/skills/chatbot-flow-design/references/intent-architecture-patterns.md @@ -0,0 +1,238 @@ +# Intent architecture patterns + +Defining what the bot can and cannot handle. Named intents, hierarchies, boundaries, coverage. + +The intent architecture is the bot's scope definition. Bad architecture produces bots that try to handle everything (and hallucinate) or bots that handle so little they fail audience expectations. Good architecture defines explicit scope and routes the rest to fallback. + +--- + +## The named-intent principle + +The bot has a defined set of intents it can handle. Each intent has a name, a scope, and a conversation pattern. + +The win. A user asks "what does the Pro plan include?" The bot recognizes this as the "pricing question" intent. The conversation pattern for that intent retrieves from the pricing knowledge base, generates a response, and offers follow-up. + +The fail (no named intents). The bot tries to handle every question with the same generic flow. Some questions get good answers; some get hallucinated answers; the bot cannot reason about its own scope. + +The discipline. Define the intents explicitly. The bot's behavior at each intent is intentional; behavior outside the intents is fallback. + +--- + +## Common intent patterns + +Patterns that recur across marketing-site and support chatbots. + +Pricing question. "How much does the Pro plan cost?" "What is included in the Enterprise tier?" "Do you offer discounts for nonprofits?" + +Conversation pattern: retrieve from pricing knowledge base, present the relevant tier or comparison, offer follow-up (talk to sales, see comparison, view full pricing page). + +Feature comparison. "What is the difference between A and B?" "Does feature X include Y?" + +Conversation pattern: retrieve from feature documentation, present comparison or specific feature details, offer follow-up. + +Integration question. "Do you integrate with Salesforce?" "How does the API work?" + +Conversation pattern: retrieve from integration catalog or API docs, present specific integration or API details, offer follow-up. + +Support escalation. "I need help with my account." "Something is broken." + +Conversation pattern: capture the issue context, escalate to human support with the captured context. + +Demo request. "Can I see a demo?" "I want to talk to sales." + +Conversation pattern: qualify the request (capture company size, use case, timeline), route to sales with the qualified context. + +Account access. "I forgot my password." "How do I access my account?" + +Conversation pattern: route to account-recovery flow or self-serve help. + +General question. "Tell me more about [topic]." "What can you help with?" + +Conversation pattern: present overview of bot capabilities; ask what specifically the user wants. + +--- + +## Intent hierarchy + +Top-level categories with sub-intents. + +The pattern. "Pricing question" includes sub-intents for "tier comparison," "discount inquiry," "billing question," "annual vs monthly." + +Strengths. + +- Hierarchy mirrors how audiences think. +- Each sub-intent can have specific knowledge-base grounding and conversation pattern. +- Easier to maintain than flat intent set. + +Weaknesses. + +- More complex to build. +- Risk of over-decomposition (sub-intents that nobody triggers). + +When to use. When the bot's scope is broad enough that a flat intent set becomes unwieldy. Most production chatbots benefit from hierarchy. + +--- + +## Intent boundaries + +Each intent has clear scope. Out-of-scope topics route to fallback. + +The principle. The intent definition specifies what the intent covers and what it does not. + +Example: "Pricing question" intent. + +In scope: tier prices, plan inclusions, discount inquiries, billing-cycle questions. + +Out of scope: sales-specific negotiations (escalate to sales), custom pricing requests (escalate to sales), historical pricing (out-of-scope, fallback). + +The boundary discipline. Without clear boundaries, the bot tries to handle topics it should not. Boundaries are part of the intent definition. + +--- + +## Intent coverage + +The bot's intents should cover 70-90 percent of expected conversations. + +The principle. Trying to cover 100 percent often produces bloated intent sets the bot cannot handle reliably. Aiming for 70-90 percent leaves room for honest fallback on the remaining edge cases. + +Coverage measurement. + +- After launch, sample conversations and classify them by intent. +- The percentage classified into named intents is coverage. +- The percentage falling to fallback is the gap. + +Coverage targets by use case. + +- Marketing-site Q&A: 80-90 percent coverage achievable. +- Support: 60-80 percent coverage typical; support questions are more varied. +- Sales qualification: 70-85 percent coverage; depending on audience. + +The over-coverage trap. Pursuing 100 percent coverage often means adding intents that fire rarely. The maintenance overhead is significant; the value is low. Honest fallback for rare cases is often better than rarely-triggered intents. + +--- + +## Intent design discipline + +Designing each intent. + +Step 1: Name the intent. Specific name that reflects the conversation pattern. + +Step 2: Scope the intent. What topics in, what topics out. + +Step 3: Identify the knowledge base. What knowledge sources the intent grounds in. + +Step 4: Design the conversation pattern. Opening response, possible follow-ups, success state, escalation conditions. + +Step 5: Define the success criterion. What does success look like for this intent? User got the answer? User clicked through to a relevant page? User completed a follow-up action? + +Step 6: Define escalation triggers. When does this intent escalate to a human? + +The discipline. Each intent is designed deliberately. Generic conversation patterns produce generic results. + +--- + +## Intent recognition + +How the bot determines which intent the user is in. + +LLM-based intent recognition. The LLM classifies the user's message into one of the named intents. Common in modern chatbots. + +Rule-based intent recognition. Keywords or patterns trigger intent assignment. Older approach; brittle but predictable. + +Hybrid. LLM as primary; rules for high-confidence overrides. Common middle ground. + +The recognition challenge. Users phrase the same intent in many ways. "How much?" "What does it cost?" "Is there a free tier?" all map to "pricing question." The intent recognition has to handle the variety. + +Recognition failure modes. + +- Misclassification (intent A treated as intent B). +- Over-classification (too many intents recognized; conversation gets confusing). +- Under-classification (intents go unrecognized; conversations fall to fallback). + +The discipline. Test intent recognition with realistic user messages. Tune until the classification matches user intent reliably. + +--- + +## Intent maintenance + +Intents drift. Audiences shift; products evolve; conversation patterns change. + +Maintenance signals. + +- Specific intents see declining resolution rates. +- New conversation patterns emerge that no intent covers. +- Sub-intents become more or less common over time. + +Maintenance cadence. Quarterly review of intent performance. Add new intents when new patterns emerge consistently; retire intents that fire rarely. + +The intent-maintenance audit. + +- For each intent: trigger rate, resolution rate, escalation rate. +- Identify intents that are over-triggering (capture too much) or under-triggering (rarely fire). +- Identify gaps (conversations that should have an intent but do not). + +--- + +## Intent and brand voice + +Each intent's conversation pattern should sound like the brand. + +The principle. The bot's voice in each intent matches the brand voice. Consistent across intents; consistent with the brand's other surfaces. + +Brand-voice failures. + +- Different intents speaking in different voices. +- Bot voice that does not match the brand's other surfaces. +- Generic LLM voice (no brand personality). + +The cure. Voice guidance specific to the bot. Brand voice document that includes bot-specific examples. Test conversations to verify voice consistency. + +--- + +## Intent-architecture worked example + +A B2B SaaS chatbot for a project management tool. + +Top-level intents. + +1. Pricing question (sub-intents: tier comparison, discount inquiry, billing question, annual vs monthly) +2. Feature inquiry (sub-intents: specific feature, comparison to competitor, roadmap question) +3. Integration question (sub-intents: specific integration, API question, custom integration) +4. Demo request (sub-intents: standard demo, enterprise demo, technical deep-dive) +5. Support escalation (sub-intents: bug report, account issue, billing problem, general help) +6. Account access (sub-intents: password reset, account login, organization-level access) +7. General overview (sub-intent: introductory tour) + +Coverage estimate. 80-85 percent of expected conversations. + +Fallback for the remaining 15-20 percent. Multi-layered fallback (clarification, suggested intents, resource handoff, human escalation). + +The architecture is explicit. Each intent has scope, knowledge-base grounding, conversation pattern, and escalation triggers. + +--- + +## Common intent failures + +Too few intents. Bot tries to handle everything with generic flow; hallucinates or stays generic. + +Too many intents. Intents that rarely fire; maintenance overhead with no value. + +Overlapping intents. Two intents claiming the same conversations; recognition becomes ambiguous. + +Unclear intent boundaries. Bot handles topics out of scope; quality drops. + +Intent recognition unreliable. Misclassification rate high; users get wrong responses. + +No intent maintenance. Intent set frozen at launch; audiences evolve away from it. + +Brand voice inconsistent. Each intent speaks differently; bot feels disjointed. + +--- + +## Methodology-level choices that stay in the public skill + +The named-intent principle. Common intent patterns. Intent hierarchy. Intent boundaries. Intent coverage. Intent design discipline. Intent recognition approaches. Intent maintenance. Intent and brand voice. Worked example. Common failures. + +## Implementation choices that stay internal + +Specific intent sets for specific bots. Specific conversation patterns and copy. Specific recognition implementations. Specific knowledge-base mappings per intent. The team's audit calendars. These vary by team. diff --git a/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md b/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md new file mode 100644 index 0000000..4ba9fb1 --- /dev/null +++ b/skills/chatbot-flow-design/references/knowledge-base-grounding-patterns.md @@ -0,0 +1,263 @@ +# Knowledge-base grounding patterns + +Retrieval-augmented generation, source-of-truth design, citation discipline, knowledge-base maintenance. The bot's responses must come from real knowledge, not made-up confidence. + +Without grounding, the bot hallucinates. With grounding, the bot retrieves and presents. The difference is the gap between hallucinating-bot and structured-guided-conversation. + +--- + +## The grounding principle + +The bot's response generation should reference a structured knowledge base. The bot does not invent answers; it retrieves and presents. + +The win. A user asks "what is included in the Pro plan?" The bot retrieves the current pricing page, extracts the Pro plan inclusions, and presents them. The answer matches the source-of-truth. + +The fail (hallucinating). A user asks the same question. The bot has no grounding; the LLM generates a response from training data or pattern-matching. The response sounds confident but may be wrong (outdated, fabricated, partially correct). + +The discipline. Every response that could be wrong if invented must be grounded. + +--- + +## Pattern A: Retrieval-augmented generation (RAG) + +The bot searches a knowledge base for relevant content before generating a response. + +How it works. + +- The user's message is converted to a query. +- The query searches the knowledge base (often via vector embedding similarity). +- Relevant content chunks are retrieved. +- The LLM generates a response grounded in the retrieved content. + +Strengths. + +- Responses reflect current knowledge base content. +- Bot answers questions about specific topics it has been trained on. +- Easier to update than retraining a model; updating the knowledge base updates the bot. + +Weaknesses. + +- Retrieval quality depends on knowledge-base structure and embedding quality. +- Bot may still hallucinate if retrieval returns nothing or if generation strays from retrieved content. +- Latency increases (retrieval + generation). + +When to use. Default pattern for grounded chatbots. Most production bots use some form of RAG. + +--- + +## Pattern B: Source-of-truth design + +Defining the knowledge base as the canonical source. + +The principle. The knowledge base is the canonical source for the bot's responses. When the source-of-truth changes, the bot's answers change. + +Source-of-truth examples. + +- Pricing page = source for pricing answers. +- Documentation = source for feature and integration answers. +- Support knowledge base = source for support answers. +- Security and compliance docs = source for security answers. + +Source-of-truth discipline. + +- Each topic has a single source-of-truth. +- The bot retrieves from that source. +- When the source updates, the bot's answers update automatically (depending on the RAG pipeline). + +The fragmented-source failure. Multiple sources for the same topic produce inconsistent answers. The bot might cite one source; the user might rely on another. Confusion. + +The cure. Single source-of-truth per topic. If multiple documents cover the same topic, designate one as canonical and reference the others. + +--- + +## Pattern C: Citation discipline + +The bot can cite the source of its answer. + +The principle. Audiences benefit from knowing where the answer came from. Citation builds trust and lets the user verify. + +Citation patterns. + +- Inline citation. "Based on our pricing page, the Pro plan is $X per user per month." +- Source link. "You can see the full plan comparison [here]." +- Source attribution at end. "Source: [document name or link]" + +Why citation matters. + +- Trust-building. Users can verify the answer. +- Hallucination protection. If the bot cannot cite, the answer may be fabricated. +- User self-service. Users with deeper questions can follow the link. + +Citation failures. + +- Bot generates an answer without citation; the user cannot verify. +- Bot cites a source that does not actually contain the answer (citation hallucination). +- Bot cites a moved or deleted source; the link breaks. + +The discipline. Citations must point to real sources that contain the cited content. + +--- + +## Pattern D: Boundary disclosure + +The bot tells the user when it is operating outside its grounding. + +The principle. When the bot's response is not grounded (the question is outside the knowledge base), the bot says so explicitly. + +Disclosure patterns. + +- "I do not have information on that specific topic; would you like me to connect you with our team?" +- "Our pricing details are on the [pricing page]; the specific scenario you are asking about may need a custom quote from sales." +- "I can answer questions about our integrations; for product roadmap, you may want to contact our team." + +The disclosure-as-honesty principle. A bot that admits limitations earns more trust than a bot that fakes confidence on out-of-scope questions. + +--- + +## Knowledge-base structure + +How the knowledge base is organized affects retrieval quality. + +Chunking. Knowledge base content is broken into chunks for retrieval. Chunk size affects retrieval precision and context. + +- Too small chunks. Retrieval returns isolated facts without context. The bot may miss surrounding nuance. +- Too large chunks. Retrieval returns too much; relevant content is buried; generation may stray. +- Right chunks. Topically coherent units (a pricing tier description, a feature explanation, a support article section). + +Metadata. Each chunk has metadata (source document, section, last-updated date, topic tags). Metadata supports filtering and citation. + +Embeddings. Chunks are embedded for similarity search. Embedding quality affects retrieval relevance. + +Index updates. When the source-of-truth changes, the index must update. Stale index produces stale answers. + +--- + +## Knowledge-base scope + +What goes into the knowledge base. + +In scope. + +- Pricing and plan details. +- Feature and capability documentation. +- Integration catalog and API documentation. +- Support FAQs. +- Security and compliance information. +- Company overview, team, contact information. + +Out of scope. + +- Confidential information (internal-only docs, sensitive data). +- Information that changes too rapidly to keep current (real-time inventory, live availability). +- Information that requires personalization the bot cannot do (account-specific data). + +Boundary discipline. Sensitive or personalization-required topics should not be in the bot's knowledge base. The bot should escalate or route to authenticated channels for those. + +--- + +## Knowledge-base maintenance + +The knowledge base decays. Maintenance is part of the bot's lifecycle. + +What decays. + +- Pricing changes that did not propagate to the knowledge base. +- Features added or removed without docs being updated. +- Integration partners changing names or capabilities. +- Support articles that became outdated. + +Maintenance cadence. + +- Monthly review of high-traffic content (pricing, features). +- Quarterly review of broader knowledge base. +- Triggered review when the product or pricing changes (the change includes a knowledge-base update task). + +Maintenance ownership. Someone owns the knowledge base. Without owner, it decays. + +Decay indicators. + +- Bot answers that contradict current product reality. +- User complaints about wrong information from the bot. +- Sales or support hearing audiences cite outdated bot information. + +--- + +## Hallucination detection + +Even with grounding, bots can hallucinate. Detection is part of the discipline. + +Detection methods. + +- Sample auditing. Periodically sample bot conversations and verify the responses against source-of-truth. +- User feedback signals. "This response was not helpful" feedback often correlates with hallucination. +- Citation verification. Programmatic checks that cited sources actually contain the cited content. +- Anomaly detection. Conversations where the bot's response diverges significantly from retrieved content. + +Remediation. + +- Hallucinated content reported promptly. +- Knowledge base or grounding logic updated to prevent recurrence. +- Specific intent or topic may need re-design. + +The honesty discipline. Acknowledge hallucination when it happens. The team that hides hallucination from itself ships worse bots over time. + +--- + +## Knowledge-base and brand voice + +The knowledge base content informs the bot's voice. + +The principle. Source documents written in brand voice produce bot responses in brand voice. Source documents written generically produce generic bot responses. + +The discipline. When preparing source documents for the knowledge base, write in the brand voice. The bot will reflect what it retrieves. + +Brand-voice editing. Some teams edit retrieved content for the bot's response. This adds brand voice but risks drifting from the source-of-truth. Trade-off worth considering. + +--- + +## Multi-source grounding + +When the bot needs to combine information from multiple sources. + +The pattern. The bot retrieves from multiple sources and synthesizes a response. + +Strengths. + +- Bot can answer questions that span topics. +- Richer responses possible. + +Weaknesses. + +- Synthesis can introduce hallucination. +- Citation becomes more complex (multiple sources). +- Quality control harder. + +The discipline. Use multi-source grounding sparingly. When used, ensure the synthesis is grounded in retrieved content, not generated from training data. + +--- + +## Common grounding failures + +No grounding. Bot generates from training data; hallucinations are routine. + +Stale grounding. Knowledge base not updated; bot answers reflect outdated reality. + +Fragmented grounding. Multiple sources for same topic; bot answers are inconsistent. + +Citation hallucination. Bot cites sources that do not contain the cited content. + +Generic content in knowledge base. Source documents are not in brand voice; bot responses are generic. + +Out-of-scope grounding. Bot retrieves from sources that should not be in scope (confidential, personalized). + +Boundary blur. Bot answers questions outside its grounding without disclosure. + +--- + +## Methodology-level choices that stay in the public skill + +The grounding principle. Patterns A through D (RAG, source-of-truth, citation, boundary disclosure). Knowledge-base structure. Knowledge-base scope. Knowledge-base maintenance. Hallucination detection. Knowledge-base and brand voice. Multi-source grounding. Common grounding failures. + +## Implementation choices that stay internal + +Specific knowledge bases for specific bots. Specific RAG pipelines and embedding choices. Specific chunking and indexing approaches. Specific tooling for hallucination detection. The team's maintenance calendars. These vary by team. diff --git a/skills/code-review-web/SKILL.md b/skills/code-review-web/SKILL.md new file mode 100644 index 0000000..0edae47 --- /dev/null +++ b/skills/code-review-web/SKILL.md @@ -0,0 +1,213 @@ +--- +name: code-review-web +description: "Review web application code for bugs, security issues, performance problems, and stack-specific anti-patterns. Use this skill whenever the user wants to review code, debug a production issue, investigate a build failure, audit security, or check a PR before merging. Triggers on code review, review my code, debug, build error, broken, not working, why is X failing, check this code, security check, PR review, audit code, refactor. Also triggers when investigating 4xx or 5xx errors, deploy failures, environment variable issues, and CMS integration problems." +category: development +catalog_summary: "PR review, build error diagnosis, security and quality checks" +display_order: 1 +--- + +# Code Review for Web + +Review and debug web application code with a focus on the patterns that actually break production. Stack-agnostic principles in SKILL.md. Stack-specific patterns in references. + +--- + +## When to use + +- Reviewing a pull request before merging +- Debugging a production issue +- Investigating a build failure +- Auditing security or performance of existing code +- Investigating environment variable or configuration issues +- Triaging a "the site is broken" report + +## When NOT to use + +- Writing a new feature spec (use `pm-spec-writing`) +- Pre-launch QA against the running site (use `qa-testing`) +- Performance deep-dive on Core Web Vitals (use `performance-optimization`) +- Deep accessibility compliance review (use `accessibility-audit`) + +--- + +## Required inputs + +- The code, PR, error message, or symptom under review +- Access to logs (build logs, function logs, server logs) if debugging +- The stack (framework, hosting, database) - even at high level + +If just a symptom is provided ("the site is broken"), the workflow's first step is gathering enough context to investigate. + +--- + +## The framework: 5 review dimensions + +Every code review covers five dimensions. Pick the depth based on the situation. + +### 1. Correctness + +Does the code do what it claims to do? + +- Logic matches the intent stated in the spec or PR description +- Edge cases handled (empty states, error states, network failures) +- Off-by-one errors, null/undefined handling, async race conditions +- Tests exist for the change, or there's a reason they don't +- The change does not break existing functionality (regression risk) + +### 2. Security + +Does the code expose anything sensitive or open an attack surface? + +- Secrets handling. No secrets, API keys, or service-role credentials in client-side code or version control +- Auth checks. Every mutation endpoint validates the caller before acting +- Input validation. User input sanitized before use in queries, file paths, or HTML +- External requests. Outbound URLs validated; no SSRF on user-controlled inputs +- CSRF protection. State-changing requests require a token or same-origin policy +- Rate limiting. Public-facing mutation endpoints have rate limits +- HTTPS-only. No HTTP in production code paths +- Cookies. Session cookies have `Secure`, `HttpOnly`, `SameSite` attributes set +- Environment variables. Server-only secrets are not prefixed with anything that exposes them to the client bundle + +### 3. Performance + +Will this code scale and stay fast? + +- Database queries. No N+1 patterns. Joins or batch fetches preferred over loops with queries. +- Pagination. Large result sets paginated, never loaded entirely. +- Caching. Appropriate cache strategy for the data freshness needs. +- Bundle size. Client-side dependencies justified. Tree-shaking working. +- Image handling. Modern formats, lazy loading, explicit dimensions. +- Background work. Slow operations moved off the request path. +- Cold start sensitivity. Cold paths optimized if frequently triggered. + +### 4. Reliability + +What happens when this fails? + +- Error handling. Caught and handled, not swallowed. Errors logged with context. +- Retries. Network calls have retry logic for transient failures. +- Timeouts. External calls have explicit timeouts (no infinite waits). +- Graceful degradation. Failure of non-critical paths does not crash the page. +- Idempotency. Mutations that might be retried are safe to retry. +- Logging. Enough context in logs to diagnose without reproducing. + +### 5. Maintainability + +Will the next person (or future you) understand this in six months? + +- Naming. Functions and variables named for what they do, not how. +- Comments. Explain why, not what. The code says what. +- Complexity. Functions do one thing. If a function takes 200 lines, it's doing too much. +- Duplication. Same logic in multiple places gets extracted. +- Dependencies. New dependencies justified. Each one is a maintenance burden. +- Magic values. No literal `60000` in code. Use named constants. + +--- + +## Common bug patterns (stack-agnostic) + +Patterns that recur across stacks and are worth checking on every review. + +### Build and deploy + +- Build-time data fetches that timeout. Routes that query a database during static generation can fail at scale. Mark them as runtime-rendered if the data must be fresh. +- Environment variables not propagating. A var that works locally but breaks in production usually means it was not added to the production environment. +- Mismatched env between preview and production. Deploys that work in preview but break on the production domain often have stack-specific URLs hardcoded. + +### URL and domain issues + +- Canonical pointing at staging or preview URL. Caused by client-exposed environment variables that pick up the wrong domain. Canonical domain should come from a server-only environment variable. +- API URL pointing at the main domain that loops back. After a DNS cutover, the main domain may now serve a different application. APIs should live on dedicated subdomains. +- HTTPS upgrade issues. Mixed content (HTTP resources loaded into HTTPS pages) breaks browsers' security model. + +### Cache invalidation + +- Stale content after deploy. Either the cache was not invalidated, or the invalidation requires a manual trigger that did not run. +- CDN serving old asset under same filename. Always use a new filename or cache-bust query string when replacing assets. +- Cache headers too aggressive. Long max-age on resources that change frequently leads to users seeing stale content for hours or days. + +### Database and data + +- N+1 queries. Loop with a query inside the loop. Replace with batch fetch or join. +- Missing limits on table scans. Forgetting `LIMIT` on queries that hit large tables. +- Connection pool exhaustion. Too many concurrent connections, often from build-time fetches in parallel routes. +- Schema migration without backfill. Adding a NOT NULL column without populating it for existing rows. + +### Image handling + +- Image not loading after upload. CDN cached the previous filename. Use new filenames for replacements. +- Layout shift from images. Missing width/height attributes. Always specify both. +- Slow LCP from large images. Hero images not optimized for size or format. + +### External integrations + +- Bot mitigation blocking server-to-server calls. CDN or firewall is challenging legitimate automated traffic. Whitelist server IPs or disable challenges for API endpoints. +- API rate limit triggered in production. Worked locally where traffic was tiny. Add backoff and rate limiting awareness. + +### Security + +- Unprotected revalidation or admin endpoints. Always require a secret token. +- PII in URLs. Visible in server logs, browser history, referrer headers. +- Secrets exposed in client bundle. Anything that gets sent to the browser is public. + +--- + +## Workflow + +1. Gather context. What stack? What's broken or under review? Logs available? +2. Pick the depth. Quick scan for a small PR. Full review for a major change. Deep dive for a production incident. +3. Run through the 5 dimensions. Note issues by severity (blocker, important, minor). +4. Check stack-specific patterns. Reference the appropriate stack guide. +5. For incidents: identify the smallest hypothesis-driven fix. Reproduce locally if possible. +6. Write the review. Use the template in [`references/review-template.md`](references/review-template.md) for formal reviews. + +--- + +## Failure patterns + +- "Looks good to me" on a 500-line PR. If the review takes 5 minutes on a large PR, the review didn't happen. +- Reviewing without running the code. Some bugs only surface at runtime. Pull the branch and run it. +- Over-indexing on style. Bikeshedding on formatting while missing logic bugs. +- Skipping security review on "internal" features. Internal becomes external faster than expected. +- Treating warnings as decoration. Build warnings often become production errors after a dependency update. +- Debugging without reading the full error message. First line of the stack trace is often not the actual cause. Read all of it. + +--- + +## Debugging workflow + +When a production issue is reported: + +1. Read the full error message. Including the stack trace. +2. Check hosting build and function logs. The exact failing line is usually here. +3. Identify the last working version. `git log --oneline` and check recent commits. +4. Reproduce locally. Confirms it's a code issue and not an environment issue. +5. Check environment variables. Especially after deploys or DNS changes. +6. Check cache state. Force a cache invalidation before concluding it's a code bug. +7. Make the minimal fix. Big refactors during incidents create more incidents. +8. Verify in production. Check the actual fix worked, not just that the deploy succeeded. +9. Document. What was the root cause? What would have prevented it? File the learnings. + +--- + +## Output format + +For PR reviews: comments inline on the PR, plus a summary if needed. + +For formal code reviews: a markdown document at `code-review-[date].md` with: +1. Scope (what was reviewed) +2. Summary (overall assessment) +3. Critical issues (blockers) +4. Important issues +5. Minor issues +6. Suggestions for follow-up + +For incidents: a postmortem document. See `after-action-report` for that format. + +--- + +## Reference files + +- [`references/review-template.md`](references/review-template.md) - Markdown template for formal code reviews. +- [`references/nextjs-patterns.md`](references/nextjs-patterns.md) - Stack-specific patterns for Next.js (App Router, ISR, Server Components, common bugs). +- [`references/wordpress-headless-patterns.md`](references/wordpress-headless-patterns.md) - Stack-specific patterns for headless WordPress integrations. diff --git a/skills/code-review-web/references/nextjs-patterns.md b/skills/code-review-web/references/nextjs-patterns.md new file mode 100644 index 0000000..0989e7c --- /dev/null +++ b/skills/code-review-web/references/nextjs-patterns.md @@ -0,0 +1,360 @@ +# Next.js Patterns + +Stack-specific patterns and anti-patterns for Next.js projects. Covers App Router and Pages Router. Stack-agnostic principles live in [SKILL.md](../SKILL.md). + +--- + +## App Router specific + +### Server vs client components + +Default to server components. Reach for `"use client"` only when interactivity, browser APIs, or React state hooks are required. + +```typescript +// Server component (default) - runs on server, no hydration cost +// app/page.tsx +export default async function Page() { + const data = await fetchData(); + return <Article data={data} />; +} + +// Client component - hydrates in browser +// app/components/InteractiveButton.tsx +"use client"; +export default function InteractiveButton() { + const [count, setCount] = useState(0); + return <button onClick={() => setCount(c => c + 1)}>{count}</button>; +} +``` + +Anti-pattern: Marking parent components as `"use client"` when only a leaf component needs it. This pulls everything below into the client bundle. + +### ISR and revalidation + +Pick the right rendering strategy per route: + +```typescript +// Static (default) - rendered at build, served from CDN +export default async function Page() { ... } + +// ISR (revalidate periodically) - rendered at build, regenerated on schedule +export const revalidate = 3600; // 1 hour + +// Dynamic (rendered on every request) - never cached +export const dynamic = "force-dynamic"; + +// Common combination: dynamic with cache hint for downstream +export const dynamic = "force-dynamic"; +export const revalidate = 3600; +``` + +### Build timeout failures + +Common error: +``` +Failed to build /route after 3 attempts because it took more than 60 seconds +``` + +Cause: A static route that queries a database or external API at build time, and the call exceeds the build timeout. + +Fix: Add `dynamic = "force-dynamic"` to defer rendering to request time: + +```typescript +export const dynamic = "force-dynamic"; +export const revalidate = 3600; + +export async function GET() { + try { + const data = await dbQuery(); + return generateResponse(data); + } catch (e) { + console.error("Route error:", e); + return new Response("", { status: 200 }); // empty but valid + } +} +``` + +### TypeScript errors in scripts directory + +If you have a `scripts/` folder with one-off scripts, exclude it from the build: + +```json +// tsconfig.json +{ + "exclude": ["node_modules", "scripts"] +} +``` + +### Canonical URL configuration + +The canonical domain must come from a server-only environment variable. Never expose with `NEXT_PUBLIC_` prefix. + +```typescript +// next.config.ts +const config = { + env: { + SITE_URL: process.env.SITE_URL ?? "https://yourdomain.com", + }, +}; +export default config; +``` + +```typescript +// Where the canonical is set +const url = process.env.SITE_URL; // server-only, never exposed to browser +``` + +Anti-pattern: Using `NEXT_PUBLIC_SITE_URL`. Vercel preview deploys will pick up the preview URL and pollute production canonicals. + +--- + +## Pages Router specific + +### getStaticProps timeouts + +Same fundamental issue as App Router build timeouts. Solution is `getServerSideProps` for routes that need fresh data: + +```typescript +// pages/dynamic-page.tsx +export async function getServerSideProps(context) { + const data = await dbQuery(); + return { props: { data } }; +} +``` + +Or ISR: + +```typescript +export async function getStaticProps() { + const data = await dbQuery(); + return { + props: { data }, + revalidate: 3600, + }; +} +``` + +--- + +## Common patterns across both routers + +### API routes / route handlers + +Authentication on mutations: + +```typescript +// app/api/protected/route.ts (App Router) +export async function POST(req: Request) { + const secret = req.headers.get("authorization"); + if (secret !== `Bearer ${process.env.API_SECRET}`) { + return new Response("Unauthorized", { status: 401 }); + } + // ... handle the request +} +``` + +Revalidation endpoint protection: + +```typescript +// app/api/revalidate/route.ts +import { revalidatePath } from "next/cache"; + +export async function POST(req: Request) { + const url = new URL(req.url); + const secret = url.searchParams.get("secret"); + + if (secret !== process.env.REVALIDATE_SECRET) { + return Response.json({ error: "Unauthorized" }, { status: 401 }); + } + + const path = url.searchParams.get("path") ?? "/"; + revalidatePath(path); + + return Response.json({ revalidated: true, path }); +} +``` + +### Image optimization + +Use the framework's built-in image component for proper optimization: + +```typescript +import Image from "next/image"; + +<Image + src="/photo.jpg" + alt="Descriptive alt text" + width={800} + height={600} + loading="lazy" // explicit even though lazy is default for below-fold +/> +``` + +For external image domains, configure `next.config.ts`: + +```typescript +const config = { + images: { + remotePatterns: [ + { protocol: "https", hostname: "cms.yourdomain.com" }, + ], + }, +}; +``` + +### Environment variables + +Three categories. Be explicit about which is which. + +``` +Server-only secrets (never prefix with NEXT_PUBLIC_): + DATABASE_URL + API_SECRET + STRIPE_SECRET_KEY + REVALIDATE_SECRET + SITE_URL (use server-only even for canonical, despite being a "public" value) + +Client-safe variables (NEXT_PUBLIC_ prefix exposes to browser): + NEXT_PUBLIC_GA_ID + NEXT_PUBLIC_DEFAULT_LANGUAGE + NEXT_PUBLIC_FEATURE_FLAGS + +Build-time only: + ANALYZE_BUNDLE + NODE_ENV (set automatically) +``` + +Red flags during review: +- Any secret with `NEXT_PUBLIC_` prefix +- Canonical or site URL set to a preview/staging URL in production +- Service role keys exposed to the browser + +--- + +## Common bugs and fixes + +### Page renders partially after deploy + +Symptom: Hero loads but content below is missing or stale. + +Cause: Stale ISR cache from before the deploy. + +Fix: Force revalidation: + +```bash +curl -X POST "https://yourdomain.com/api/revalidate?path=/&secret=$REVALIDATE_SECRET" +``` + +If the issue persists, check server logs for rendering errors during regeneration. + +### CMS API redirects to main domain after DNS cutover + +Symptom: API calls to the CMS return 302 redirects or 403 errors. + +Cause: API URL points at the main domain, which now serves the Next.js app instead of the CMS. + +Fix: Use a dedicated CMS subdomain: + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json # correct +WP_API_URL=https://yourdomain.com/wp-json # loops back to Next.js +``` + +### Images return 502 after domain change + +Cause: Image optimizer fetching from a domain that no longer hosts the source images. + +Fix: Update `images.remotePatterns` in `next.config.ts` to match the new image origin. Rewrite media URLs in data fetches to point at the correct origin. + +### Client component re-renders excessively + +Cause: Inline object or function as prop. New reference on every render triggers re-render in the child. + +Fix: Memoize: + +```typescript +// Before (creates new object each render) +<Child config={{ foo: "bar" }} /> + +// After +const config = useMemo(() => ({ foo: "bar" }), []); +<Child config={config} /> +``` + +--- + +## Performance patterns + +### Avoid request waterfalls + +```typescript +// Bad: sequential fetches +const user = await getUser(); +const posts = await getPostsByUser(user.id); +const comments = await getCommentsForPosts(posts.map(p => p.id)); + +// Good: parallel where possible +const user = await getUser(); +const [posts, settings] = await Promise.all([ + getPostsByUser(user.id), + getSettingsForUser(user.id), +]); +``` + +### Database query patterns + +```typescript +// Bad: N+1 +for (const post of posts) { + const author = await db.user.findUnique({ where: { id: post.authorId } }); +} + +// Good: batch fetch with relation +const posts = await db.post.findMany({ + include: { author: true }, +}); + +// Always limit large scans +const data = await db.post.findMany({ + where: { ... }, + take: 100, +}); +``` + +### Streaming with Suspense + +For App Router, stream slow content to improve perceived performance: + +```typescript +// app/page.tsx +import { Suspense } from "react"; +import FastContent from "./FastContent"; +import SlowContent from "./SlowContent"; + +export default function Page() { + return ( + <> + <FastContent /> + <Suspense fallback={<Loading />}> + <SlowContent /> + </Suspense> + </> + ); +} +``` + +--- + +## Code review checklist for Next.js + +- [ ] Server components default; `"use client"` only where needed +- [ ] ISR routes have appropriate `revalidate` value +- [ ] Database-querying routes have `force-dynamic` if they can timeout at build +- [ ] Canonical/site URL uses server-only env var +- [ ] No secrets in `NEXT_PUBLIC_` variables +- [ ] API routes have auth checks on mutations +- [ ] Revalidation endpoint protected with secret +- [ ] Images use the `Image` component, with explicit width/height +- [ ] External image domains in `images.remotePatterns` +- [ ] Scripts directory excluded from tsconfig if causing type errors +- [ ] Suspense boundaries for slow content where streaming helps diff --git a/skills/code-review-web/references/review-template.md b/skills/code-review-web/references/review-template.md new file mode 100644 index 0000000..35bcea4 --- /dev/null +++ b/skills/code-review-web/references/review-template.md @@ -0,0 +1,141 @@ +# Code Review: [PR Title or Scope] + +Reviewer: [Name] +Date: [YYYY-MM-DD] +PR or commit: [Link or hash] +Author: [Name] +Scope: [Files reviewed, lines changed] + +--- + +## Summary + +[2 to 3 sentences. Overall assessment. Recommend merge, request changes, or block.] + +Recommendation: [Approve / Approve with comments / Request changes / Block] + +Critical issues: [N] +Important issues: [N] +Minor issues: [N] +Suggestions: [N] + +--- + +## Critical issues (blockers) + +[Issues that must be fixed before merge.] + +### 1. [Issue title] +- File: [path/to/file.ext] +- Line: [Line number or range] +- Issue: [What's wrong] +- Why critical: [Impact if shipped] +- Suggested fix: [Specific recommendation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Issues that should be addressed but might not block merge.] + +### 1. [Issue title] +- File: +- Line: +- Issue: +- Suggested fix: + +--- + +## Minor issues + +[Polish items, style consistency, naming.] + +- [file:line] [Description and suggestion] +- [file:line] [Description and suggestion] +- [file:line] [Description and suggestion] + +--- + +## Suggestions for follow-up + +[Things worth doing in a follow-up PR, not in this one.] + +- [Suggestion] +- [Suggestion] + +--- + +## Dimension scorecard + +\| Dimension \| Pass \| Issues \| +\|---\|---\|---\| +\| Correctness \| ☐ \| [Notes] \| +\| Security \| ☐ \| [Notes] \| +\| Performance \| ☐ \| [Notes] \| +\| Reliability \| ☐ \| [Notes] \| +\| Maintainability \| ☐ \| [Notes] \| + +--- + +## Specific checks + +### Correctness +- [ ] Logic matches PR description +- [ ] Edge cases handled (empty, null, error) +- [ ] No off-by-one or async race conditions +- [ ] Tests exist or are not needed (with reason) +- [ ] No regressions in existing functionality + +### Security +- [ ] No secrets in client-side code +- [ ] Auth checks on mutations +- [ ] Input validated before use +- [ ] No new SSRF surface +- [ ] Cookies have appropriate attributes +- [ ] Server-only env vars not exposed to client + +### Performance +- [ ] No N+1 queries +- [ ] Pagination on large result sets +- [ ] Cache strategy appropriate +- [ ] Bundle size impact reasonable +- [ ] Images handled correctly + +### Reliability +- [ ] Errors caught and handled +- [ ] Network calls have timeouts +- [ ] Graceful degradation for non-critical paths +- [ ] Mutations idempotent if retried +- [ ] Sufficient logging for diagnosis + +### Maintainability +- [ ] Naming clear +- [ ] Functions focused (one thing well) +- [ ] No unjustified duplication +- [ ] No magic values (use constants) +- [ ] Comments explain why, not what + +--- + +## Stack-specific checks (if applicable) + +[Reference the stack-specific guide for the project. Note any stack-specific patterns or anti-patterns worth flagging.] + +--- + +## Notes for the author + +[Encouraging or contextual notes. What was done well. What's a learning opportunity.] + +--- + +## Sign-off + +Approval status: [Approved / Approved with comments / Changes requested / Blocked] +Date: [YYYY-MM-DD] + +If changes were requested, link to the follow-up PR or commit when resolved: +- [Link or hash] diff --git a/skills/code-review-web/references/wordpress-headless-patterns.md b/skills/code-review-web/references/wordpress-headless-patterns.md new file mode 100644 index 0000000..cddd929 --- /dev/null +++ b/skills/code-review-web/references/wordpress-headless-patterns.md @@ -0,0 +1,265 @@ +# WordPress Headless Patterns + +Stack-specific patterns for WordPress as a headless CMS, integrated with a separate frontend (Next.js, Astro, Eleventy, custom, etc.). + +The principles in [SKILL.md](../SKILL.md) apply universally. This file covers the WordPress-specific patterns that recur in headless setups. + +--- + +## Architecture + +A headless WordPress setup typically looks like: + +``` +cms.yourdomain.com → WordPress backend (admin, REST API, media) +yourdomain.com → Frontend (renders content fetched from CMS API) +``` + +WordPress serves the data and admin. The frontend serves the user-facing site. The two are decoupled. + +This separation matters for several patterns below. + +--- + +## Always use a CMS subdomain + +Pattern: All API calls go to a dedicated subdomain. + +``` +WP_API_URL=https://cms.yourdomain.com/wp-json +``` + +Anti-pattern: API calls to the main domain. + +``` +WP_API_URL=https://yourdomain.com/wp-json # this will break after DNS cutover +``` + +Why: When the main domain points to the frontend (post-DNS cutover), API calls to the main domain hit the frontend instead of WordPress. The frontend has no `/wp-json` route, so calls fail. + +The CMS subdomain remains a stable, dedicated endpoint regardless of where the main domain points. + +--- + +## Site URL configuration in WordPress + +After moving to a subdomain, WordPress needs to know its real URL. Otherwise the admin redirects to the main domain. + +In `wp-config.php`: + +```php +define("WP_HOME", "https://cms.yourdomain.com"); +define("WP_SITEURL", "https://cms.yourdomain.com"); +``` + +Symptom if missing: Logging into `cms.yourdomain.com/wp-admin` redirects to `yourdomain.com/wp-admin`, which hits the frontend (no admin), returning a 403 or 404. + +--- + +## Media URL handling + +WordPress generates media URLs based on the configured site URL. When fetched through the API, they will reference the CMS subdomain. The frontend needs to handle these correctly. + +### Pattern 1: Reference media at the CMS subdomain (simplest) + +The frontend renders images directly from the CMS subdomain: + +```html +<img src="https://cms.yourdomain.com/wp-content/uploads/photo.jpg" alt="..." /> +``` + +Pros: Simple. No URL rewriting. +Cons: Browser makes requests to a different origin. Need to allow that origin in image optimizer config. + +### Pattern 2: Rewrite media URLs to the frontend domain + +Strip the CMS prefix and serve media via the frontend's image optimizer: + +```typescript +// Convert CMS media URL to a pattern the frontend image optimizer accepts +function rewriteMediaUrl(url: string): string { + return url.replace("https://cms.yourdomain.com", ""); +} +``` + +Configure the frontend image optimizer to allow the CMS subdomain as a remote source. + +### Anti-pattern: Hardcoded media URLs in content + +If editors paste full URLs into the content (`<img src="https://cms.yourdomain.com/...">`), changing the CMS subdomain later breaks every reference. Use relative paths or template-rendered URLs instead. + +--- + +## Permalinks and post URLs + +WordPress posts have a `link` field in the API response that returns the WordPress-rendered URL (e.g., `https://cms.yourdomain.com/post-slug/`). This is wrong for the public-facing site. + +Anti-pattern: Using the `link` field directly. + +```typescript +// Wrong - shows the CMS URL +<a href={post.link}>{post.title}</a> +``` + +Pattern: Construct the public URL from the slug. + +```typescript +// Right - build the URL the frontend serves +<a href={`/blog/${post.slug}`}>{post.title}</a> +``` + +--- + +## Caching and revalidation + +The frontend caches API responses. When content changes in WordPress, the cache must be invalidated. + +### Pattern 1: Time-based revalidation + +Cache responses for a fixed period. Simple but content can be stale up to that period. + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { revalidate: 3600 }, // 1 hour +}); +``` + +### Pattern 2: On-demand revalidation via webhook + +WordPress fires a webhook on save. The webhook calls a frontend endpoint that invalidates the cache. + +WordPress side (mu-plugin or theme function): + +```php +add_action('save_post', function ($post_id) { + $post = get_post($post_id); + if ($post->post_status !== 'publish') return; + + wp_remote_post('https://yourdomain.com/api/revalidate', [ + 'body' => json_encode([ + 'secret' => REVALIDATE_SECRET, + 'path' => '/blog/' . $post->post_name, + ]), + 'headers' => ['Content-Type' => 'application/json'], + ]); +}); +``` + +Frontend side: an endpoint that invalidates the cache for the given path. + +### Pattern 3: Tag-based invalidation + +Tag fetches with semantic identifiers, then invalidate by tag when relevant content changes. + +```typescript +const posts = await fetch(`${WP_API_URL}/wp/v2/posts`, { + next: { tags: ["posts"] }, +}); + +// Later, invalidate +revalidateTag("posts"); +``` + +--- + +## Authentication for the API + +For private content or write operations, the API requires authentication. + +### Application passwords (built into WordPress) + +WordPress supports application passwords for API authentication. Generate one in the admin under user profile. + +```typescript +const auth = btoa(`${username}:${appPassword}`); + +const res = await fetch(`${WP_API_URL}/wp/v2/posts`, { + headers: { + Authorization: `Basic ${auth}`, + }, +}); +``` + +Anti-pattern: Hardcoding credentials in client-side code. Application passwords go in server-only environment variables. + +### JWT (via plugin) + +JWT plugins offer a more standard auth flow but add a plugin dependency. + +--- + +## Common bugs and fixes + +### "API returns 403 from server-side fetch" + +Cause 1: A bot mitigation service (Cloudflare's "Attack Challenge Mode" or similar) is challenging the server-to-server request. + +Fix: Disable bot mitigation challenges for the CMS API path, or whitelist the frontend's server IPs. + +Cause 2: The API requires authentication and the request is unauthenticated. + +Fix: Add an `Authorization` header with application password or JWT. + +### "Posts list is paginated and we're only getting 10" + +Cause: WordPress default per-page is 10. + +Fix: Use `per_page` parameter and handle pagination: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?per_page=100`); +const total = parseInt(res.headers.get('x-wp-total') ?? '0'); +const totalPages = parseInt(res.headers.get('x-wp-totalpages') ?? '0'); +``` + +For very large content sets, paginate explicitly rather than fetching all at once. + +### "Custom fields are missing from the API response" + +Cause: Advanced Custom Fields (ACF) or custom post meta is not exposed by default. + +Fix: Use the ACF to REST API plugin, or register custom fields with `register_rest_field`: + +```php +add_action('rest_api_init', function () { + register_rest_field('post', 'custom_field_name', [ + 'get_callback' => function ($post) { + return get_post_meta($post['id'], 'custom_field_name', true); + }, + ]); +}); +``` + +### "Featured image is missing from the API response" + +Cause: The API returns the image ID, not the full media object. + +Fix: Use `_embed=true` to inline media: + +```typescript +const res = await fetch(`${WP_API_URL}/wp/v2/posts?_embed=true`); +// Now post._embedded["wp:featuredmedia"][0] has the full image data +``` + +### "Slug-only URLs return wrong content after rename" + +Cause: WordPress slug changes don't redirect the old slug. Frontend caches lock to the old slug. + +Fix: +1. WordPress: install a redirection plugin or maintain a redirects table +2. Frontend: handle 404s on slug routes by falling back to a search-by-title + +--- + +## Code review checklist for headless WordPress + +- [ ] All API calls use the CMS subdomain (no main domain references) +- [ ] WP_HOME and WP_SITEURL set in wp-config.php +- [ ] Media URLs handled correctly (either CMS-direct or rewritten) +- [ ] Post URLs constructed from slug, not the WordPress `link` field +- [ ] Cache invalidation strategy in place (time-based, webhook, or tag) +- [ ] Authentication credentials in server-only env vars +- [ ] API responses include needed embedded data (`_embed=true` where relevant) +- [ ] Pagination handled for large post lists +- [ ] Error handling for API failures (CMS down should not crash the frontend) +- [ ] Custom fields exposed via REST API where needed diff --git a/skills/comparison-tool-design/SKILL.md b/skills/comparison-tool-design/SKILL.md new file mode 100644 index 0000000..051888d --- /dev/null +++ b/skills/comparison-tool-design/SKILL.md @@ -0,0 +1,261 @@ +--- +name: comparison-tool-design +description: "Designing side-by-side comparison tools (plan-compare, product-compare, alternative-compare) that help users decide rather than just listing features. Axis selection, default-comparison logic, recommendation discipline. Honest about feature-list-dump (every feature in a row, no decision support), hidden-recommendation (biased comparison pretending to be neutral), and honest-comparison-with-guidance (genuine comparison plus opinionated recommendation) patterns. Triggers on comparison tool, plan compare, product compare, alternative compare, vs page, decision support tool. Also triggers when conversion through comparison stages is poor, when users are abandoning at the comparison step, or when a comparison tool is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing comparison tools that help users decide. Distinguishes feature-list-dump (every feature in a row, no decision support) from hidden-recommendation (biased comparison pretending to be neutral) from honest-comparison-with-guidance (genuine comparison plus opinionated recommendation)" +display_order: 11 +--- + +# Comparison Tool Design + +A senior product marketing director's playbook for designing side-by-side comparison tools that help users decide rather than just listing features. Plan-compare, product-compare, alternative-compare. Axis selection, default-comparison logic, recommendation discipline. The discipline of building a comparison tool that earns the user's trust. + +Most comparison tools fail in one of two ways. They dump every feature into a giant grid (4 options × 40 features = 160 cells) and ask the user to weigh everything against everything. The user leaves without choosing. Or they pretend to be neutral comparisons but are actually sales pitches with biased defaults and weighted framing; the user catches the bias and trust collapses. + +The comparison tools that work do something different. Genuine like-for-like comparison plus an explicit opinionated recommendation. "For X audience, choose Y." The recommendation is visible, defended, and not the only path; users can override. The tool helps the user decide rather than asking them to decide alone. + +The voice is the senior product marketing director who has watched comparison tools double conversion when redesigned with honest recommendations and watched them collapse when feature grids grew without decision support. Practical, opinionated about which axes matter, willing to call out when the comparison is decoration. + +When to use this skill: scoping a comparison tool for the first time, auditing a feature-grid comparison that produces no conversion lift, designing recommendation logic that is honest about the recommendation, or deciding which axes earn placement in a comparison tool. + +--- + +## What this skill covers + +This skill spans side-by-side comparison tools. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number. This skill is comparing known options. +- `quiz-and-assessment-design` is quizzes that give a category. This skill is comparing options the user already knows about. +- `comparison-tool-design` (this skill) is axis selection, default-comparison logic, recommendation engine, filter-and-toggle UX. +- `landing-page-copy` is pricing-page copy; one specific application of comparison tools is the pricing page. +- `content-strategy` is upstream; what topics warrant comparison content. + +The audience: product marketers, growth marketers, content marketers running vs-pages and decision-support tooling, agencies running comparison work for clients. + +Out of scope: calculator design (covered by `calculator-design`); quiz design (covered by `quiz-and-assessment-design`); the engineering implementation; specific Webflow/Framer/CMS configurations (those stay implementation-side). + +--- + +## The comparison-tool decision: when comparison tools earn investment + +Before designing the tool, decide whether a comparison tool is the right answer. + +Comparison tools earn investment when: + +- The audience is at a decision moment between known options (vs unknown options where a quiz or recommendation tool fits better). +- The options have meaningful differences that warrant side-by-side analysis. +- The brand can articulate honest distinctions between options without becoming sales pitch. +- The audience benefits from decision support, not just feature listing. + +Comparison tools do NOT earn investment when: + +- Options are too similar to compare meaningfully. +- The brand cannot make honest distinctions without creating sales-pitch dynamics. +- A simple comparison table or written content would serve. +- The audience does not actually face this decision (manufactured comparisons). + +The decision is not "should we have a comparison tool"; it is "is the comparison tool the right tool for this decision." + +Detail in [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md). + +--- + +## Feature-list-dump vs hidden-recommendation vs honest-comparison-with-guidance + +The keystone framing. + +Feature-list-dump. Every option's every feature in a giant grid. No decision support. The user is asked to weigh 40 cells against each other; most leave without choosing. Cost: design effort wasted on a grid that does not produce decisions; the audience perceives the grid as overwhelming. + +Hidden-recommendation. "Comparison" tool that is actually a sales pitch. Defaults favor one option; framing weights the answer; the recommendation is invisible but baked in. Trust erodes when users notice the bias. Cost: short-term conversion may look fine; long-term brand damage from "manipulative" reputation. + +Honest-comparison-with-guidance. Genuine like-for-like comparison plus an explicit opinionated recommendation ("For X audience, choose Y"). The recommendation is visible, defended, and not the only path; users can override. Cost: design effort upfront is significant; conversion typically improves because users feel respected and helped. + +The litmus test. Does the tool tell the user what to choose for their specific situation, with reasoning? If yes, honest-comparison-with-guidance. If it dumps features without guidance, feature-list-dump. If it says "the right answer is obviously [our preferred option]" without acknowledgment, hidden-recommendation. + +--- + +## Axis selection: which dimensions matter, which are noise + +The single most consequential decision in comparison tool design. + +The principle. Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision, not every feature available. + +Strong axes. + +- Decision-relevant capabilities. Features that materially affect the audience's outcome. +- Cost dimensions. Price, total cost of ownership, hidden costs. +- Constraint dimensions. Capacity, scale, integration support. +- Service dimensions. Support quality, onboarding, SLA. +- Risk dimensions. Vendor stability, security, compliance. + +Weak axes. + +- Marketing checkboxes. Features that exist on every option; checkmarks across the row. +- Nice-to-haves. Features the audience does not actually weigh. +- Vendor-specific terminology. Features named differently by each vendor; comparison becomes label confusion. +- Decoration features. Features added to the grid because the brand has them and competitors do not. + +The 8-12 axis rule. Most production comparison tools work well with 8-12 axes. Beyond that, decision paralysis sets in. + +Detail in [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md). + +--- + +## Default-comparison logic + +Which options compare by default, and why. + +The principle. Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; biased defaults shape conclusions. + +Default options. + +- Audience-fit defaults. The options the audience most commonly considers. +- Stage-fit defaults. The options that match the audience's stage of decision. +- Inferred defaults. Based on referral source, query, or prior interaction. + +Default axes. + +- The axes most relevant to the typical audience. +- Audience can expand to additional axes if interested. + +Bias-flattering defaults. + +- Defaults set so brand always wins on visible axes. +- Defaults that hide axes where competitors win. +- Defaults that frame in brand's terminology. + +The discipline. Defaults serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +Detail in [`references/default-comparison-logic.md`](references/default-comparison-logic.md). + +--- + +## Recommendation engine design + +When to recommend, how to defend the recommendation. + +The principle. Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible. + +Recommendation patterns. + +- Single recommendation. "For [audience], choose [option] because [reasons]." Clear; opinionated. +- Multi-segment recommendation. "If you are [A], choose X. If you are [B], choose Y." Honest about audience-fit. +- Conditional recommendation. "If [factor] matters most, X. If [other factor] matters most, Y." Helps the user decide based on priorities. + +Recommendation defense. + +- The reasoning shown. +- The audience for the recommendation explicit. +- The override path visible. + +Anti-pattern: hidden recommendation. Tool that defaults to one option's victory through axis selection and framing, without explicit recommendation. Users feel manipulated when they catch the pattern. + +Detail in [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) and [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md). + +--- + +## Filter and toggle UX + +What users can adjust, what should stay fixed. + +Filterable elements. + +- Which options to compare (user adds or removes options). +- Which axes to show (user filters to relevant dimensions). +- Audience or use case (user signals their context; tool adapts). + +Fixed elements. + +- Methodology disclosure (always visible). +- Recommendation reasoning (always findable). +- Source citations (always linkable). + +The filter-fatigue trap. Too many filters; user paralyzed. + +The under-filtered trap. Tool too rigid; user cannot match their context. + +The discipline. Filters that materially help; not filters for the sake of customization. + +Detail in [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md). + +--- + +## Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Pattern 1: Too many cells. 40 features × 5 options = 200 cells; cognitive overload. + +Pattern 2: All-checkmarks rows. Every option has the feature; the row produces no signal. + +Pattern 3: Inconsistent axis terminology. Each vendor names features differently; user confused. + +Pattern 4: Hidden costs. Pricing visible; fees, overage, integrations not surfaced. + +Pattern 5: Apples-to-oranges options. Comparing genuinely different things; no axis applies cleanly. + +Pattern 6: No recommendation. Tool lists; user must decide; user does not. + +The cumulative effect. The tool produces no decision; users default to the brand they already heard of. + +Detail in [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-comparison-failures.md`](references/common-comparison-failures.md). + +- "Tool gets traffic; conversion is unchanged." Likely feature-list-dump; no decision support. +- "Sales says competitor leads cite our tool as biased." Hidden-recommendation pattern; trust damage. +- "Mobile users do not engage with the tool." Comparison grids do not work well on mobile; design for it. +- "Power users criticize axis selection." Audience knows these features; tool may have used easy axes rather than decision-relevant. +- "Tool was great at launch; conversion declined over time." Features changed; comparison stale. +- "Audience says 'this is helpful' but does not convert." Recommendation absent or weak; users get information without decision support. +- "Comparison shows every option as 'good' for something." Dilution; no clear recommendation. +- "Adding more features to the comparison reduced conversion." Crossed the cell-count threshold; cognitive overload. + +--- + +## The framework: 12 considerations for comparison tool design + +When designing or auditing a comparison tool, walk these 12 considerations. + +1. The comparison-tool decision. Is a tool the right answer, or does written content serve? +2. Honest-comparison-with-guidance, not feature-list-dump or hidden-recommendation. Genuine compare plus opinionated rec. +3. Axis selection. 8-12 decision-relevant axes; cut decoration features. +4. Default-comparison logic. Honest defaults; not bias-flattering. +5. Recommendation engine designed. Visible; defended; not the only path. +6. Filter and toggle UX. Filters that help; not filters for customization theater. +7. Methodology disclosed. Source data, axis weighting, audience definition. +8. Mobile parity. Tool works on the devices the audience uses. +9. Maintenance discipline. Comparison stays current as options change. +10. Honest about competitor strengths. When competitors win on an axis, say so. +11. Audience-fit measured. Per-segment conversion through the tool. +12. Conversion as success metric. Not just engagement; downstream choice and retention. + +The output of the framework is a comparison tool that earns the user's trust by helping them decide, with recommendation that is honest and defensible. + +--- + +## Reference files + +- [`references/comparison-tool-decision-criteria.md`](references/comparison-tool-decision-criteria.md) - When comparison tools earn the build vs when written content serves. +- [`references/axis-selection-patterns.md`](references/axis-selection-patterns.md) - Strong axes, weak axes, the 8-12 rule. +- [`references/default-comparison-logic.md`](references/default-comparison-logic.md) - Honest defaults vs bias-flattering defaults. +- [`references/recommendation-engine-design.md`](references/recommendation-engine-design.md) - When to recommend, how to defend, override path. +- [`references/filter-and-toggle-patterns.md`](references/filter-and-toggle-patterns.md) - Filterable vs fixed elements; filter-fatigue trap. +- [`references/comparison-fatigue-patterns.md`](references/comparison-fatigue-patterns.md) - Why most comparisons fail to produce decisions. +- [`references/honest-recommendation-discipline.md`](references/honest-recommendation-discipline.md) - The discipline that distinguishes hidden from honest recommendations. +- [`references/comparison-anti-patterns.md`](references/comparison-anti-patterns.md) - The patterns that look like comparisons but degrade trust. +- [`references/common-comparison-failures.md`](references/common-comparison-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: comparison tools earn the choice when they earn the user's trust + +The comparison tools that work as compounding assets are the ones the audience trusts to help them decide. Not because the tool flatters the brand. Not because the tool dumps features. Because the tool genuinely helps the user pick the option that fits their situation, and is honest about which option that is. + +That is the bar. Below the bar are feature-list-dump (no decision support; user leaves without choosing) and hidden-recommendation (biased pretending to be neutral; trust collapses when caught). Above the bar are honest-comparison-with-guidance tools where axis selection, default logic, recommendation engine, and filter UX work together to produce decisions the audience trusts. + +The discipline is in the design choices. The decision to build a comparison at all. The axes that earn placement. The defaults that serve the audience. The recommendation that is visible and defended. The filters that help the user match their context. The methodology that is disclosed. The maintenance that keeps the comparison current. diff --git a/skills/comparison-tool-design/references/axis-selection-patterns.md b/skills/comparison-tool-design/references/axis-selection-patterns.md new file mode 100644 index 0000000..299644d --- /dev/null +++ b/skills/comparison-tool-design/references/axis-selection-patterns.md @@ -0,0 +1,185 @@ +# Axis selection patterns + +Strong axes, weak axes, the 8-12 rule. + +Axes (the rows of the comparison) should be the dimensions that genuinely affect the decision. Done well, axes produce decisions; done poorly, they produce overwhelm. + +--- + +## The decision-relevance principle + +Each axis should affect the audience's decision. Axes that do not are decoration. + +The win. A comparison tool with 10 axes covering capability, pricing, integration, support quality. Each axis materially affects whether the audience would choose. + +The fail. Same tool with 35 axes including marketing-checkbox features. User overwhelmed; many cells provide no signal. + +The discipline. Axes earn placement through decision relevance. + +--- + +## Strong axes + +Patterns that earn placement. + +Decision-relevant capabilities. The 5-7 capabilities the audience explicitly evaluates. + +Cost dimensions. Price, total cost of ownership, hidden costs. + +Constraint dimensions. Capacity, scale ceilings, integrations, geography. + +Service dimensions. Support quality, onboarding, SLA. + +Risk dimensions. Vendor stability, security, compliance. + +Time dimensions. Time to value, implementation timeline. + +The selection discipline. Each axis answers "will this matter to the audience?" If no, cut. + +--- + +## Weak axes + +Patterns that fail. + +Marketing checkboxes. Features on every option; checkmarks across the row. No signal. + +Nice-to-haves. Features the audience does not weigh. + +Vendor-specific terminology. Features named differently by each vendor; label confusion. + +Decoration features. Added because brand has them. + +Generic checkmarks. "Customer support: yes/yes/yes." Not differentiating. + +--- + +## The 8-12 axis rule + +Most production comparison tools work well with 8-12 axes. + +Why 8-12. + +- Below 8: comparison thin. +- Above 12: cognitive overload. + +Exceptions. + +- Highly technical audiences may absorb 15-20. +- Consumer audiences may tolerate 6-8. + +The over-12 trap. Each axis beyond 12 reduces engagement. + +--- + +## Axis ordering + +Within the comparison, order matters. + +Strong order. Most decision-relevant first. + +Weak order. Random; alphabetical; feature-category without importance weighting. + +The first-axis discipline. First axis should be one of the most important; users may skim past later axes. + +--- + +## Axis grouping + +When axes group naturally. + +Grouping patterns. Capability axes together; cost together; service together; risk together. + +Strengths. Easier to scan. + +Weaknesses. Group dividers add visual complexity. + +When to use. When axis count justifies (10+ axes). + +--- + +## Axis content per cell + +What each cell shows. + +Beyond checkmarks. "Yes/no" rarely produces decisions. Numbers, descriptions, comparisons add depth. + +Examples. + +- Cost: "$X/month" not just "Yes" to "has pricing." +- Capacity: "Up to 1000 users" not just "Yes" to "scales." +- Support: "24/7 chat plus phone" not just "Yes" to "support." + +The cell content discipline. Depth where decisions need it. + +--- + +## Axis defaults + +Which axes show by default; which behind toggle. + +Default-shown axes. The 8-12 most decision-relevant. + +Toggle-shown axes. Less critical; audience can expand. + +The hide-bias trap. Hiding axes where brand loses; detection eventual. + +The honest-default principle. Defaults reflect audience importance; not brand strength. + +--- + +## Axis updates + +Axes decay. + +What decays. + +- Axes that lost relevance. +- Axes that gained relevance. +- Axis content stale. + +Maintenance cadence. Quarterly review. + +--- + +## Axis testing + +Validate axes with the audience. + +Methods. + +- User research: which axes do they consider? +- A/B test: different axis sets. +- Sales-call mining: which axes do prospects ask about? + +The validation discipline. Axes are hypotheses; validate. + +--- + +## Common axis failures + +Too many axes. Cognitive overload. + +Too few axes. Comparison thin. + +Wrong axes. Audience does not weigh them. + +Marketing-checkbox axes. No signal. + +Vendor-specific terminology. Label confusion. + +Hidden axes where brand loses. Bias detected. + +Stale axis content. Pricing or features outdated. + +Axis ordering ignores importance. First axes are not most critical. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relevance principle. Strong axes (6 patterns). Weak axes (5 patterns). The 8-12 rule. Axis ordering. Axis grouping. Cell content. Axis defaults. Updates. Testing. Common failures. + +## Implementation choices that stay internal + +Specific axes for specific tools. Specific cell content. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/common-comparison-failures.md b/skills/comparison-tool-design/references/common-comparison-failures.md new file mode 100644 index 0000000..6dafdbb --- /dev/null +++ b/skills/comparison-tool-design/references/common-comparison-failures.md @@ -0,0 +1,179 @@ +# Common comparison failures + +8+ failure patterns with diagnoses and cures. + +--- + +## "Tool gets traffic; conversion is unchanged." + +The diagnosis. Likely feature-list-dump; no decision support. + +The cure. Add recommendation. Cut decoration axes. Detail in `references/recommendation-engine-design.md`. + +--- + +## "Sales says competitor leads cite our tool as biased." + +The diagnosis. Hidden-recommendation pattern; trust damage. + +The cure. Honest recommendation discipline (`references/honest-recommendation-discipline.md`). Acknowledge competitor strengths. + +--- + +## "Mobile users do not engage with the tool." + +The diagnosis. Comparison grids do not work well on mobile. + +The cure. Mobile-first design. Stacked layout. Reduced axis count for mobile. + +--- + +## "Power users criticize axis selection." + +The diagnosis. Audience knows these features; tool may have used easy axes rather than decision-relevant. + +The cure. Audit axes against real audience decisions. Replace marketing-checkbox axes with decision-relevant ones. + +--- + +## "Tool was great at launch; conversion declined over time." + +The diagnosis. Features changed; comparison stale. + +The cure. Quarterly maintenance. + +--- + +## "Audience says 'this is helpful' but does not convert." + +The diagnosis. Recommendation absent or weak. + +The cure. Add recommendation with reasoning and clear next-step CTA. + +--- + +## "Comparison shows every option as 'good' for something." + +The diagnosis. Dilution; no clear recommendation. + +The cure. Take a stand. Recommendation should be opinionated; tradeoffs acknowledged. + +--- + +## "Adding more features to the comparison reduced conversion." + +The diagnosis. Crossed the cell-count threshold; cognitive overload. + +The cure. Cut back. 8-12 axes is the working range. + +--- + +## "Sales says many leads come through the tool but bounce on demo." + +The diagnosis. Tool's framing oversells; reality on demo does not match. + +The cure. Honest tool produces honest leads. Audit framing for sales-pitch dynamics. + +--- + +## "Audience-segment recommendations feel stereotyped." + +The diagnosis. Segment definitions based on assumptions rather than research. + +The cure. Validate audience segments with research. Refine recommendations based on real needs. + +--- + +## "Specific competitor is missing; users ask why." + +The diagnosis. Competitor omitted from comparison. + +The cure. Include relevant competitors. If intentionally excluded, disclose why ("we focus on X category; competitor Y is in different category"). + +--- + +## "Tool methodology questioned by analyst or journalist." + +The diagnosis. Methodology hidden or weakly defended. + +The cure. Detailed methodology disclosure. Be ready to defend specific axis choices and weights. + +--- + +## "Tool conversion is fine; sales conversion does not match." + +The diagnosis. Tool optimizes for tool-conversion; downstream not aligned. + +The cure. Track downstream metrics. Optimize for downstream conversion, not just tool engagement. + +--- + +## "Filter use is low; users see default comparison only." + +The diagnosis. Filters added but not promoted; users do not realize they exist. + +The cure. Promote filters; or accept that defaults serve and reduce filter complexity. + +--- + +## "Filters produce empty result combinations." + +The diagnosis. Filter logic does not constrain combinations to those producing comparable options. + +The cure. Smart filter logic. When filters would produce empty result, surface alternatives. + +--- + +## "Recommendation fires for one option always." + +The diagnosis. Hidden-recommendation; bias-flattering logic. + +The cure. Test the recommendation engine across audience scenarios. Ensure competitors win when fit warrants. + +--- + +## "Audience tells us the comparison feels accurate but the recommendation feels off." + +The diagnosis. Comparison data accurate; recommendation engine logic does not match audience priorities. + +The cure. Validate recommendation logic. Audience research on what they weigh vs what the tool weights. + +--- + +## "We A/B tested adding axes; conversion went down." + +The diagnosis. Crossed the cell-count threshold. + +The cure. Maintain axis discipline. More is not always better. + +--- + +## "Tool produces good conversion for new visitors; returning visitors do not engage." + +The diagnosis. Tool optimized for first-time-decision audience; returning visitors have other needs. + +The cure. Different surfaces for different stages. Returning visitors may want simpler reference rather than full tool. + +--- + +## The pattern across failures + +Most comparison tool failures fall into one of three patterns. + +Pattern 1: No decision support. Feature-list-dump, no-recommendation, dilution. The fix is clear, defensible recommendation. + +Pattern 2: Bias damages trust. Hidden-recommendation, contradiction, omitted competitors, stereotypes. The fix is honest recommendation discipline. + +Pattern 3: Friction. Over-filtered, mobile-broken, fatigue patterns. The fix is reducing cognitive load and matching audience use. + +The metric pattern: comparison failures often look fine on engagement alone. The signal is in conversion, downstream metrics, audience trust. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (no-decision-support, bias, friction). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-anti-patterns.md b/skills/comparison-tool-design/references/comparison-anti-patterns.md new file mode 100644 index 0000000..35ec8f0 --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-anti-patterns.md @@ -0,0 +1,218 @@ +# Comparison anti-patterns + +The patterns that look like comparisons but degrade trust. Easy to ship; cost shows up in conversion, brand reputation, and audience trust. + +--- + +## The feature-list-dump comparison + +The pattern. Every feature × every option. No decision support. + +The signal. Users skim; do not choose; tool produces no conversion lift. + +The cure. Cut to 8-12 decision-relevant axes. Add recommendation. + +--- + +## The hidden-recommendation comparison + +The pattern. Defaults bias toward brand without disclosure. + +The signal. Sophisticated audiences notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest defaults; explicit recommendation; acknowledge competitor strengths. + +--- + +## The all-checkmarks comparison + +The pattern. Every option has every feature; checkmarks across the rows. + +The signal. Rows produce no signal; users skim. + +The cure. Cut generic-checkmark rows. Replace with specifics that differentiate. + +--- + +## The terminology-confused comparison + +The pattern. Each vendor's terminology used in their column; user cannot tell if features match. + +The signal. Users confused; comparison breaks semantically. + +The cure. Normalize terminology. Vendor names in subtext; functional descriptions in main label. + +--- + +## The hidden-cost comparison + +The pattern. Headline pricing visible; overage, fees, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cure. Total cost of ownership surfaced. + +--- + +## The apples-to-oranges comparison + +The pattern. Options compared that are genuinely different things. + +The signal. Comparison feels strained; axes do not apply cleanly. + +The cure. Compare options the audience actually considers together. Separate tools for separate categories if needed. + +--- + +## The no-recommendation comparison + +The pattern. Tool lists; user decides alone. + +The signal. High abandonment; conversion lift absent. + +The cure. Add recommendation with reasoning. + +--- + +## The contradicts-itself comparison + +The pattern. Comparison shows competitor winning on most axes; tool recommends brand anyway. + +The signal. Users notice the contradiction; trust collapses. + +The cure. Recommendation aligns with comparison; or recommendation defends the contradiction explicitly. + +--- + +## The stale comparison + +The pattern. Information from 6+ months ago. + +The signal. Users notice; trust drops. + +The cure. Quarterly maintenance. + +--- + +## The over-filtered comparison + +The pattern. 12+ filters; user paralysis at filter step. + +The signal. High drop-off before the comparison loads. + +The cure. Reduce filter count; default-heavy. + +--- + +## The under-filtered comparison + +The pattern. Tool too rigid; one fixed view. + +The signal. Specific segments convert poorly. + +The cure. Add filters where audiences split. + +--- + +## The mobile-broken comparison + +The pattern. Grid designed for desktop; mobile cramped or scroll-required. + +The signal. Mobile conversion much lower. + +The cure. Mobile-first design. + +--- + +## The methodology-hidden comparison + +The pattern. Tool shown without explaining how comparison was built. + +The signal. Sophisticated users question the tool. + +The cure. Methodology disclosure. + +--- + +## The audience-stereotype comparison + +The pattern. Audience-segment recommendations rely on stereotypes ("enterprise = big and slow"). + +The signal. Users in those segments feel mis-served. + +The cure. Audience-segment recommendations based on real needs, not assumptions. + +--- + +## The over-recommend comparison + +The pattern. Tool recommends in cases where genuine differentiator does not exist. + +The signal. Users notice the recommendation feels arbitrary. + +The cure. "We cannot rank these for you" is sometimes the honest answer. + +--- + +## The competitor-omission comparison + +The pattern. Important competitor missing from the comparison. + +The signal. Users ask "where is X?" or feel comparison is incomplete. + +The cure. Include relevant competitors. If a competitor is omitted intentionally, disclose why. + +--- + +## The bias-flattering-axis-selection comparison + +The pattern. Axes chosen where brand wins; axes hidden where brand loses. + +The signal. Sophisticated audiences notice axis selection. + +The cure. Honest axis selection. Detail in `references/axis-selection-patterns.md`. + +--- + +## The marketing-checkbox comparison + +The pattern. Every option's marketing checkboxes laid out as comparison. + +The signal. Comparison reads like marketing brochures rather than analysis. + +The cure. Replace marketing checkboxes with specific functional capabilities. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +Audit questions per tool. + +- Is the tool feature-list-dump (anti-pattern check)? +- Does the recommendation acknowledge competitor strengths (anti-pattern check: hidden-recommendation)? +- Are rows differentiating (anti-pattern check: all-checkmarks)? +- Is terminology normalized (anti-pattern check: terminology-confused)? +- Are total costs surfaced (anti-pattern check: hidden-cost)? +- Are options apples-to-apples (anti-pattern check: apples-to-oranges)? +- Is recommendation present (anti-pattern check: no-recommendation)? +- Does recommendation align with comparison (anti-pattern check: contradicts-itself)? +- Is information current (anti-pattern check: stale)? +- Are filters calibrated (anti-pattern check: over-filtered, under-filtered)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Is methodology disclosed (anti-pattern check: methodology-hidden)? + +The retire decision. Tools failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-fatigue-patterns.md b/skills/comparison-tool-design/references/comparison-fatigue-patterns.md new file mode 100644 index 0000000..10e5a0f --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-fatigue-patterns.md @@ -0,0 +1,190 @@ +# Comparison-fatigue patterns + +Why most comparisons fail to produce decisions. + +Most comparison tools accumulate cognitive load until users abandon without choosing. Comparison-fatigue patterns are the failure modes that make this happen. + +--- + +## Pattern 1: Too many cells + +The pattern. 40 features × 5 options = 200 cells. + +The signal. Users skim; pick the brand they already heard of; tool produces no decision. + +The cost. Comparison work is invisible because users cannot process the volume. + +The cure. Reduce cells. 8-12 axes × 3-5 options = 24-60 cells. The comparison density is comprehensible. + +--- + +## Pattern 2: All-checkmarks rows + +The pattern. Every option has the feature; the row produces checkmarks across. + +The signal. Users skim past; row provides no signal. + +The cost. Row earns space without earning attention. + +The cure. Cut the row, or replace generic checkmarks with specifics that differentiate. + +--- + +## Pattern 3: Inconsistent axis terminology + +The pattern. Each vendor names features differently; comparison becomes label confusion. + +The signal. User confusion; cannot tell if "Pro Workspace" and "Premium Studio" are the same thing. + +The cost. Comparison breaks at semantic level; users cannot weigh. + +The cure. Normalize terminology. Use functional descriptions; vendor labels in subtext. + +--- + +## Pattern 4: Hidden costs + +The pattern. Pricing visible; fees, overage, integrations not surfaced. + +The signal. Users compare on visible price; learn about hidden costs later; feel deceived. + +The cost. Trust damage when discovered. + +The cure. Surface total cost of ownership. Acknowledge fees, overage, expected add-ons. + +--- + +## Pattern 5: Apples-to-oranges options + +The pattern. Comparing genuinely different things; no axis applies cleanly. + +The signal. Comparison feels strained; users cannot tell why these options are being compared. + +The cost. Tool exists but produces no useful decision support. + +The cure. Compare options the audience would actually consider together. If options are too different, separate tools may serve better. + +--- + +## Pattern 6: No recommendation + +The pattern. Tool lists; user must decide; user does not. + +The signal. High abandonment; conversion rate low. + +The cost. The tool's information work does not produce decisions. + +The cure. Add explicit recommendation with reasoning. Detail in `references/recommendation-engine-design.md`. + +--- + +## Pattern 7: Stale information + +The pattern. Comparison content from 6+ months ago; competitors have updated; brand has updated. + +The signal. Users notice the staleness; trust drops. + +The cost. Tool produces decisions based on outdated information. + +The cure. Quarterly maintenance. Triggered updates when major competitor or brand changes happen. + +--- + +## Pattern 8: Bias-flattering framing + +The pattern. Comparison content frames in brand's favor (showing brand's most expensive plan vs competitors' cheap; using brand's terminology for axes). + +The signal. Sophisticated users notice; trust collapses. + +The cost. Long-term brand damage. + +The cure. Honest framing. Acknowledge competitor strengths. Use neutral terminology where possible. + +--- + +## Pattern 9: Decision paralysis at filter step + +The pattern. Tool requires extensive filter setup before showing comparison; users abandon at filter step. + +The signal. High drop-off before the comparison loads. + +The cost. Comparison work is invisible; users never see it. + +The cure. Default-heavy. Show comparison immediately; filters available but optional. + +--- + +## Pattern 10: Mobile illegibility + +The pattern. Comparison grid designed for desktop; on mobile, cells cramped or scroll-required. + +The signal. Mobile conversion much lower than desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design. Stacked layout for mobile; reduced axis count. + +--- + +## Pattern 11: No methodology disclosure + +The pattern. Comparison shown without explaining how it was assembled. Users do not know if it is honest. + +The signal. Users question the comparison; sales hears about doubts. + +The cost. Trust degrades; comparison's authority unclear. + +The cure. Disclose methodology. Where data came from; how axes were chosen; when last updated. + +--- + +## Pattern 12: Recommendation contradicts comparison + +The pattern. Comparison shows option B winning on most axes; tool recommends option A. + +The signal. Users notice the contradiction; trust collapses. + +The cost. Tool internally inconsistent; users cannot rely on it. + +The cure. Recommendation aligns with comparison. If recommendation favors A despite axis losses, defend explicitly ("Option A wins despite [losses] because [audience-specific reasoning]"). + +--- + +## The cumulative effect + +Most comparison tools fail at multiple of these patterns simultaneously. The cumulative effect: tool produces no decisions; users default to the brand they already heard of; comparison work is wasted. + +The cure. Audit each pattern. Each pattern fixed reduces cumulative friction. + +--- + +## How to audit comparison fatigue + +Quarterly review. + +Audit questions per tool. + +- Cell count: is it under 100? +- Are any rows all-checkmarks? +- Is terminology normalized across options? +- Are total costs surfaced? +- Are options apples-to-apples? +- Is recommendation present and visible? +- Is information current? +- Is framing honest? +- Is filter step lightweight? +- Does mobile work? +- Is methodology disclosed? +- Does recommendation match comparison? + +The retire decision. Tools failing multiple patterns warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 fatigue patterns. Signal-pattern-cost framing. Cures. The cumulative effect. Audit questions. + +## Implementation choices that stay internal + +Specific fatigue patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md b/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md new file mode 100644 index 0000000..527087f --- /dev/null +++ b/skills/comparison-tool-design/references/comparison-tool-decision-criteria.md @@ -0,0 +1,132 @@ +# Comparison-tool decision criteria + +When comparison tools earn the build vs when written content serves. + +A comparison tool is meaningful work. Axis selection, default logic, recommendation engine, filter UX, ongoing maintenance. The tool earns this investment only when specific conditions are present. + +--- + +## When comparison tools earn the build + +Five conditions that, when present, make a comparison tool a strong investment. + +The audience is at a decision moment between known options. They know the options exist; they need help choosing. Audiences who do not yet know the options need different tools (quizzes, recommendations). + +The options have meaningful differences. Comparing two options that differ only in branding produces nothing useful. + +The brand can articulate honest distinctions. Without becoming sales pitch. + +The audience benefits from decision support. Some audiences want a tool that helps them decide rather than weigh tradeoffs themselves. + +The success metric is defined. Conversion through the tool, downstream conversion, choice quality. + +When all five are present, a comparison tool is strong investment. When two or fewer are present, written content often serves better. + +--- + +## When comparison tools do NOT earn the build + +Funnels where comparison tools add cost without lift. + +Options too similar. Comparing genuinely interchangeable options produces no decision support. + +Options apples-to-oranges. Comparison axes do not apply across both. + +Brand cannot make honest distinctions. Tool will become hidden-recommendation; trust suffers. + +A simple table or article would serve. Static comparison content is cheaper. + +The audience does not face this decision. Manufactured comparisons feel forced. + +--- + +## Comparison tools vs written vs-pages + +Both compare options; differ in interactivity. + +Written vs-pages strengths. Cheap; SEO-friendly; easy to update. + +Written vs-pages weaknesses. Static; no recommendation logic. + +Comparison tool strengths. Adaptive; surfaces recommendations dynamically; lets users explore. + +Comparison tool weaknesses. Build cost; maintenance burden. + +The combined approach. Many production teams use both: vs-pages for SEO; tools for decision support. + +--- + +## The opportunity-cost frame + +Comparison tools are significant work. + +Build cost. Axis curation, recommendation logic, filter UX, methodology disclosure, mobile responsiveness. 30-100 engineering hours plus design and content. + +Maintenance cost. Quarterly updates run 4-8 hours. + +Opportunity cost. What else could the team have built? Better vs-pages, calculator, quiz. The tool has to clear those alternatives. + +The decision frame. Comparison tools earn investment when they produce more decision lift than alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering a comparison tool against 3 named competitors. + +Conditions check. + +- Decision moment: yes. +- Meaningful differences: yes; pricing, features, integration vary. +- Brand can articulate honest distinctions: yes. +- Audience benefits: yes. +- Success metric defined: yes. + +Decision. Build the comparison tool. + +Architecture. 10 axes; 4 options; honest recommendation per audience segment. + +The decision was deliberate. + +--- + +## Decision worked example: when written serves + +A consumer-facing financial product considering a comparison tool against generic bank accounts. + +Conditions check. + +- Decision moment: yes. +- Meaningful differences: somewhat; many banks similar. +- Brand articulate distinctions: yes for specific competitors. +- Audience benefits: somewhat. +- Success metric: signup; harder to attribute. + +Decision. Written vs-pages plus a brief comparison table. Full tool not warranted. + +The decision was right-sized. + +--- + +## When to retire a comparison tool + +Tools can become wrong over time. + +Retire when: + +- Conversion declined consistently. +- Options changed enough that comparison is misleading. +- Competitors deprecated. +- A redesigned vs-page produces equivalent results. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant comparison tools. The five conditions that argue against. Comparison tools vs written vs-pages. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tool decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/comparison-tool-design/references/default-comparison-logic.md b/skills/comparison-tool-design/references/default-comparison-logic.md new file mode 100644 index 0000000..07c542a --- /dev/null +++ b/skills/comparison-tool-design/references/default-comparison-logic.md @@ -0,0 +1,169 @@ +# Default-comparison logic + +Honest defaults vs bias-flattering defaults. + +Defaults shape the user's first impression. Honest defaults reflect the audience's likely starting point; bias-flattering defaults shape conclusions in ways that erode trust when caught. + +--- + +## The honest-default principle + +Defaults should serve the audience, not the brand. When defaults must reflect brand strength, do so honestly with disclosure. + +The win. Default comparison shows the brand alongside 2-3 commonly-considered competitors. Default axes are the 8-12 most decision-relevant. Default audience profile (if pre-selected) reflects the visitor's likely segment. + +The fail. Default comparison shows the brand alongside the 2 weakest competitors. Default axes are the ones where the brand wins. Audience defaults assume the brand's ideal customer. + +The discipline. Defaults make the comparison fair as a starting point; users can adjust. + +--- + +## Default options + +Which options compare by default. + +Audience-fit defaults. The options the audience most commonly considers. + +How to determine. Sales-call mining (which competitors do prospects mention?), referral analysis, user research. + +Stage-fit defaults. The options that match the audience's stage. + +How. Awareness audiences may compare against generic categories; decision audiences against specific products. + +Inferred defaults. Based on referral source or query. + +How. Visitor from "X vs Y" search query gets X and Y as defaults; visitor from generic landing gets default comparison set. + +--- + +## Default axes + +Which axes show by default. + +The most-critical-axes default. Top 8-12 axes by decision relevance. + +Audience-relevant axes. Default to axes most relevant to the inferred or stated audience. + +The hide-where-we-lose anti-pattern. Defaulting to axes where the brand wins; hiding where it loses. Detection by analytical audiences eventual; trust damage permanent. + +The cure. Defaults reflect audience importance, not brand strength. Honest about competitor strengths. + +--- + +## Default audience or use case + +When the tool asks (or infers) the audience. + +Pattern A: Pre-selected. Tool selects an audience based on referrer or query. + +Strengths. Lower friction; tool seems intelligent. + +Weaknesses. Inference can be wrong. + +Pattern B: Asked upfront. Tool asks "what is your role?" or "what is your team size?" + +Strengths. Accurate; user controls. + +Weaknesses. Adds friction; some audiences skip. + +Pattern C: No audience selection. Tool shows comparison; user can filter. + +Strengths. Lowest friction; works for all audiences. + +Weaknesses. Generic; no per-audience recommendation. + +The choice depends on the tool's complexity and the audience's diversity. + +--- + +## Default recommendation + +What the tool recommends by default. + +Pattern A: Single default recommendation. "For most teams, [option] is the best choice." + +Strengths. Clear; opinionated. + +Weaknesses. May not fit all visitors. + +Pattern B: Audience-conditional default. Recommendation changes based on audience selection. + +Strengths. Fits different audiences. + +Weaknesses. More complex. + +Pattern C: No default recommendation. Tool requires user to specify before recommending. + +Strengths. User commits; recommendation is matched. + +Weaknesses. Higher friction. + +The discipline. Whatever default, the recommendation is honest about who it is for. + +--- + +## Bias-flattering defaults: the failure + +Patterns that destroy trust. + +Defaults set for brand victory. Comparison tool defaults to axes where the brand wins, hides where it loses. + +Defaults that frame in brand's terminology. Other options compared in vocabulary that favors the brand's positioning. + +Defaults that misrepresent competitor pricing. Showing competitor's most expensive plan vs brand's mid-tier. + +Defaults that show outdated competitor info. Listing features competitors have updated. + +The audience reaction. Sophisticated audiences notice; trust collapses; brand earns "manipulative" reputation. + +--- + +## Honest defaults with disclosure + +When the brand legitimately stands out, honest framing matters. + +The pattern. "Default view shows the comparison most relevant to teams of [size]. Your situation may differ; use filters to adjust." + +Disclosure where defaults are brand-favorable. "We are highlighting [axis] because we think it matters most for [audience]. Let us know if you weigh things differently." + +The honest framing earns trust where bias-flattering loses it. + +--- + +## Default maintenance + +Defaults decay. + +What decays. + +- Default options no longer match audience consideration. +- Default axes no longer the most relevant. +- Default audiences shifted. + +Maintenance cadence. Quarterly review. Update as competitive landscape and audience composition shift. + +--- + +## Common default failures + +Hide-where-we-lose. Bias detected; trust collapses. + +Stale defaults. Competitor info outdated. + +Wrong default audience. Inference produces unfit comparison for visitor. + +No default at all. Tool requires extensive setup before showing comparison. + +Default obscures methodology. Defaults look like neutral; methodology is biased. + +Default ignores recent competitor changes. Defaults from 6 months ago. + +--- + +## Methodology-level choices that stay in the public skill + +The honest-default principle. Default options. Default axes. Default audience or use case. Default recommendation. The bias-flattering failure pattern. Honest defaults with disclosure. Default maintenance. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific comparison tools. Specific audience inference logic. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/filter-and-toggle-patterns.md b/skills/comparison-tool-design/references/filter-and-toggle-patterns.md new file mode 100644 index 0000000..2d5addb --- /dev/null +++ b/skills/comparison-tool-design/references/filter-and-toggle-patterns.md @@ -0,0 +1,225 @@ +# Filter and toggle patterns + +What users can adjust, what should stay fixed. The filter-fatigue trap. + +Filters and toggles let users adapt the comparison to their context. Done well, filters help users match the tool to their situation; done poorly, filters become customization theater that adds complexity without value. + +--- + +## The help-don't-customize principle + +Filters earn placement when they help users match the comparison to their context. Filters for the sake of customization options add complexity without lift. + +The win. Tool offers 3 filters: audience size, use case, must-have integrations. Each filter materially adapts the recommendation. Users find their context quickly. + +The fail. Tool offers 15 filters across multiple dimensions. Decision paralysis at the filter step; users abandon before reaching the comparison. + +The discipline. Filters that help; not filters for theater. + +--- + +## Filterable elements + +What users can adjust. + +Options to compare. User adds or removes options. + +Axes to show. User filters to relevant dimensions. + +Audience or use case. User signals their context; tool adapts. + +Pricing model preference. User selects monthly vs annual; per-seat vs flat. + +Region or geography. User selects where they operate; tool adapts to applicable options. + +--- + +## Fixed elements + +What should not be filterable. + +Methodology disclosure. Always visible. + +Recommendation reasoning. Always findable. + +Source citations. Always linkable. + +Honest framing. Tool is honest about its biases regardless of filter state. + +--- + +## Filter UI patterns + +How filters appear. + +Pattern A: Top-of-page filters. + +How it works. Filter row at top; user adjusts; comparison below updates. + +Strengths. Visible; familiar. + +Weaknesses. Takes screen space; mobile-challenging. + +Pattern B: Sidebar filters. + +How it works. Filter panel on the side; comparison main area. + +Strengths. Persistent; works on desktop. + +Weaknesses. Mobile-broken; takes space. + +Pattern C: Inline filters. + +How it works. Filters appear within the comparison (per-axis filtering, per-option toggling). + +Strengths. Contextual. + +Weaknesses. Visual complexity. + +Pattern D: Wizard-style. + +How it works. Tool asks 2-3 filter questions; then shows comparison. + +Strengths. Less overwhelming. + +Weaknesses. Adds friction upfront. + +The choice depends on filter complexity and audience preferences. + +--- + +## Filter count + +How many filters earn placement. + +3-5 filters. Sweet spot. Each filter helps; cumulative friction manageable. + +6-8 filters. Acceptable for complex tools; require strong UX. + +10+ filters. Almost always too many. Decision paralysis at filter step. + +1-2 filters. Often too few; tool feels rigid. + +--- + +## Filter defaults + +What filters are pre-set. + +Honest defaults. Reflect typical audience. + +Audience-detected defaults. Inferred from referral or context. + +No defaults (user must select). Adds friction but ensures intentionality. + +The default discipline. Defaults reflect audience importance; not brand strength. + +--- + +## Filter combinations + +When filters interact. + +Independent filters. Each filter changes one dimension; combinations multiply. + +Conditional filters. Some filters appear only after others are set. + +Smart filters. Tool suggests filters based on earlier selections. + +The discipline. Combinations should produce meaningful comparisons; not empty cells. + +--- + +## The filter-fatigue trap + +Too many filters; user paralyzed. + +The pattern. Tool offers 12 filters. User feels they need to set them all to get meaningful comparison. User leaves before completing. + +The signal. Drop-off at the filter step; users do not reach the comparison. + +The cost. Comparison tool's main value (the comparison) is invisible. + +The cure. Reduce filter count. Default-heavy. Optional filters behind a "more options" toggle. + +--- + +## The under-filtered trap + +Tool too rigid; user cannot match context. + +The pattern. Tool shows one fixed comparison; no way to adapt. + +The signal. Users complain the tool does not fit them; specific segments convert poorly. + +The cost. Tool serves only the audience the default fits. + +The cure. Add filters where audience genuinely splits. + +--- + +## Filter mobile design + +Filters on mobile have specific considerations. + +Mobile-specific patterns. + +- Filters in a collapsible drawer rather than always-visible panel. +- Reduced filter count on mobile (defer non-critical filters). +- Touch-friendly toggles. + +Mobile-broken patterns. + +- Sidebar filters cramping the comparison. +- Top-of-page filters that scroll off and require scrolling back. +- Filter modals that take over the screen. + +The mobile discipline. Filters work on mobile or do not exist there. + +--- + +## Filter analytics + +Track filter use. + +Metrics. + +- Per-filter use rate. +- Filter abandonment (started filtering; left without completing). +- Filter combinations that produce no results. + +Diagnostic uses. + +- Filter rarely used: it may not earn placement. +- Filter abandonment high: too many filters or bad defaults. +- No-result combinations: filter logic may have gaps. + +--- + +## Common filter failures + +Too many filters. Filter fatigue. + +Too few filters. Tool too rigid. + +Filters with no value. Filters that do not change anything meaningful. + +Filters that produce empty results. Combinations show no options. + +Mobile-broken filters. Filters work on desktop, fail mobile. + +Filter UX inconsistent. Mix of patterns; users confused. + +Default filters bias-flattering. Defaults make brand look better than reality. + +No filter analytics. Cannot tell which filters earn their place. + +--- + +## Methodology-level choices that stay in the public skill + +The help-don't-customize principle. Filterable vs fixed elements. Filter UI patterns A through D. Filter count. Filter defaults. Filter combinations. The filter-fatigue and under-filtered traps. Filter mobile design. Filter analytics. Common failures. + +## Implementation choices that stay internal + +Specific filters for specific tools. Specific filter UI implementations. Specific defaults. The team's mobile testing benchmarks. These vary by team. diff --git a/skills/comparison-tool-design/references/honest-recommendation-discipline.md b/skills/comparison-tool-design/references/honest-recommendation-discipline.md new file mode 100644 index 0000000..37df188 --- /dev/null +++ b/skills/comparison-tool-design/references/honest-recommendation-discipline.md @@ -0,0 +1,201 @@ +# Honest recommendation discipline + +The discipline that distinguishes hidden from honest recommendations. + +Recommendations are powerful. Honest ones earn trust; hidden ones erode it. The discipline is to know which kind your tool produces. + +--- + +## The litmus test + +A sophisticated user from the target audience tests the tool by selecting a clearly wrong-fit scenario for the brand. Does the tool recommend a competitor when fit warrants? + +The win. Tool recommends competitor X for the wrong-fit scenario, with reasoning. The sophisticated user trusts the tool because it is willing to recommend against the brand. + +The fail. Tool always recommends the brand regardless of scenario. The sophisticated user catches the pattern; trust collapses. + +The discipline. The tool's willingness to recommend competitors when warranted is the trust marker. + +--- + +## What honest recommendation looks like + +Five marks of honesty. + +Mark 1: Brand does not always win. When competitors fit better, tool says so. + +Mark 2: Reasoning is specific and verifiable. "Option B has X capability that Option A lacks" rather than "B is better." + +Mark 3: Audience-fit is articulated. "For [audience] with [needs], choose X. For different audience, choose Y." + +Mark 4: Tradeoffs acknowledged. "Option X wins on capability A but loses on capability B." + +Mark 5: Methodology disclosed. Users can see how the recommendation was generated. + +When all five are present, the recommendation is honest. When any are absent, hidden-recommendation dynamics creep in. + +--- + +## What hidden recommendation looks like + +Five marks of hidden bias. + +Mark 1: Brand always wins regardless of scenario. + +Mark 2: Reasoning is generic ("best in class") without specifics. + +Mark 3: Audience-fit not articulated; one recommendation for all. + +Mark 4: Tradeoffs not acknowledged; brand presented as superior on all axes. + +Mark 5: Methodology hidden or vague. + +When these patterns combine, the tool is hidden-recommendation regardless of whether the team intended bias. + +--- + +## The acknowledge-competitor-strengths principle + +Honest recommendation tools acknowledge where competitors are stronger. + +The pattern. "Competitor X has the strongest [capability]. We win on [different capability]. For audiences prioritizing [first], X. For audiences prioritizing [second], us." + +Why it works. Acknowledging strengths signals honesty. Audiences trust the recommendation more because the tool is willing to lose on specific axes. + +The reluctant-acknowledgment failure. Acknowledging competitor strengths only when forced; minimizing them where possible. Detection by sophisticated audiences eventual. + +--- + +## The recommendation-defense quality + +How well the tool defends its recommendation. + +Strong defense. + +- Specific to audience. +- Tied to specific axes where the recommended option wins. +- Includes tradeoffs. +- Cites data or sources. + +Example. + +"For mid-market teams (50-200 users): Option B. Reasons: B's pricing scales better at 200+ users, B's [specific feature] is unmatched, B's support response time is fastest. Tradeoff: B's onboarding is longer than Option A's. For under-50-user teams, Option A may serve better." + +Weak defense. + +- "B is the best choice." +- "Most teams choose B." +- Generic claims. + +The defense earns trust through specificity and acknowledged tradeoffs. + +--- + +## Audience-segment recommendations + +Different audiences may warrant different recommendations. + +Patterns. + +- "Solo and small teams: choose A." +- "Mid-market: choose B." +- "Enterprise: choose C." + +Why this works. Audiences self-identify; tool serves each. + +The single-recommendation-fits-all failure. One recommendation for diverse audiences misses fit. + +The discipline. When audiences differ, recommendations differ. + +--- + +## When the recommendation should be no-recommendation + +Sometimes "we cannot tell which is best for you" is the honest answer. + +Patterns. + +- "Both options fit teams in your situation; differentiator is [factor] you should weigh personally." +- "If [criterion] matters most to you, X. If [criterion] matters most, Y. We cannot rank for you." + +Why this works. Honest about the limits of recommendation; respects user agency. + +The over-recommend failure. Recommending in cases where genuine differentiator does not exist; trust suffers when users notice. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +Disclosure patterns. + +- "We weight [axes] heavily because [reasons]." +- "If you weigh different axes, your recommendation may differ." +- "Our methodology is described here." + +The audience that questions. Some users will dig. Methodology should hold up. + +--- + +## The recommendation-audit pattern + +Periodically test the tool's honesty. + +Audit method. + +- Test scenarios where competitors should win. +- Test scenarios where brand should win. +- Test edge cases. + +Audit findings. + +- Tool always recommends brand: hidden-recommendation; redesign. +- Tool sometimes recommends competitors: honest; verify the recommendations make sense. +- Tool refuses to recommend: may be appropriate for genuine ties; should not be default. + +The audit catches drift. Honest tools at launch can become hidden-recommendation through small changes over time. + +--- + +## Honest recommendation maintenance + +Honest recommendations decay. + +What decays. + +- Reasoning based on outdated capabilities. +- Audience-segment definitions that no longer fit. +- Methodology that no longer matches the tool's logic. + +Maintenance cadence. Quarterly review. Verify reasoning still holds; verify methodology matches implementation. + +--- + +## Common honest-recommendation failures + +Brand always wins. Hidden-recommendation; trust risk. + +No defense. Recommendations without reasoning. + +Generic recommendations. "Best for most teams" without specificity. + +Single recommendation for diverse audiences. Missed fit. + +Tradeoffs hidden. Brand presented as superior on all axes. + +Methodology vague. Users cannot inspect. + +No competitor-strength acknowledgment. Trust suffers. + +Stale recommendation. Reasoning based on outdated info. + +--- + +## Methodology-level choices that stay in the public skill + +The litmus test. Five marks of honest recommendation. Five marks of hidden recommendation. The acknowledge-competitor-strengths principle. Recommendation defense quality. Audience-segment recommendations. When no-recommendation is honest. Recommendation transparency. The audit pattern. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific recommendation logic for specific tools. Specific audience-segment mappings. Specific methodology copy. The team's audit calendar. These vary by team. diff --git a/skills/comparison-tool-design/references/recommendation-engine-design.md b/skills/comparison-tool-design/references/recommendation-engine-design.md new file mode 100644 index 0000000..28b7c77 --- /dev/null +++ b/skills/comparison-tool-design/references/recommendation-engine-design.md @@ -0,0 +1,172 @@ +# Recommendation engine design + +When to recommend, how to defend, override path. + +Comparison tools that recommend are more useful than tools that just list. The recommendation must be defensible, visible, and not the only path. + +--- + +## The visible-defended-overridable principle + +Recommendations are most useful when: + +- Visible. Users can see what the tool recommends. +- Defended. Reasoning is explicit. +- Overridable. Users who weigh things differently can choose otherwise. + +The win. Tool recommends "Option B for mid-market teams prioritizing scale." Recommendation prominent; reasoning shown; user can switch audience or pick differently. + +The fail. Tool dumps features; user must decide alone. + +The discipline. Recommend with reasoning; respect override. + +--- + +## Recommendation patterns + +Common patterns. + +Pattern A: Single recommendation. "For [audience], choose [option] because [reasons]." Clear; opinionated. + +Pattern B: Multi-segment recommendation. "If [A], choose X. If [B], choose Y." + +Pattern C: Conditional recommendation. "If [factor] matters most, X. If [other], Y." + +Pattern D: Recommendation with caveat. "We think X fits most teams in your situation, with these caveats." + +Pattern E: No recommendation. Rarely the right choice. + +--- + +## Defending the recommendation + +The reasoning shown. + +Strong defense. Specific reasons tied to recommended option's strengths; audience-fit articulated; tradeoffs acknowledged. + +Example. "For mid-market teams: Option B. B's pricing scales better at 200+ users (X% vs Y%), B's integration with [tool] is faster, B's support response is shortest in this tier. Tradeoff: B's interface is less polished than Option A; A wins for teams under 50." + +Weak defense. "B is our recommendation"; "B is best for most teams"; generic claims. + +The defense earns trust through specificity. + +--- + +## The override path + +How users can choose otherwise. + +Visible alternative paths. + +- Toggle to switch recommended audience. +- Filter to weight axes differently. +- Direct selection of different option. + +Friction balance. + +- Override findable in 1-2 clicks. +- Override does not require restart. +- Override preserves user context. + +The discipline. Override is honest; users who disagree are not punished. + +--- + +## Recommendation framing + +How recommendations are worded. + +Strong framing. Specific to audience; tied to reasoning; acknowledges tradeoffs; inviting override. + +Weak framing. "Obviously X is best"; "most experts agree X"; "X is the only choice for serious teams." + +What works. Specificity, humility, agency for the user. + +--- + +## Audience-fit recommendations + +Different audiences may warrant different recommendations. + +The pattern. Tool detects or asks about audience; recommendation adapts. + +Detection methods. + +- Referrer or query. +- Stated input. +- Inferred from context. + +The discipline. Audience signals inform recommendation; do not stereotype. + +--- + +## Recommendation transparency + +Users should understand how the recommendation was generated. + +Methodology disclosure. + +- "We weight [axes] heavily because [reasons]." +- "If you weigh [factor] differently, your recommendation may differ." + +The audience that questions. Some users will dig; methodology should hold up. + +--- + +## The recommendation-bias risk + +Recommendations are powerful; biased ones damage trust. + +Common biases. + +- Recommending brand in all cases. +- Recommendations always benefit recommender. +- Hidden weighting toward brand strengths. + +The trust-collapse. When users catch bias, they stop trusting entirely. + +The cure. Acknowledge competitor strengths. Recommend competitors when fit warrants. Honest about who is recommending whom. + +--- + +## Recommendation testing + +Validate. + +Methods. + +- User research: do recommendations match what audiences would have chosen with full information? +- Cohort analysis: do recommendation-followers retain better? +- Sales feedback: do recommended-option leads convert at higher rates? + +The discipline. Recommendation is hypothesis until validated. + +--- + +## Common recommendation failures + +No recommendation. Tool lists; users decide alone. + +Hidden recommendation. Tool defaults bias toward one option without disclosure. + +Generic recommendation. "Best for most teams" without specificity. + +Single recommendation for diverse audiences. Missed fit. + +Recommendation without defense. Authoritative without reasoning. + +No override path. Users who disagree have no clear alternative. + +Recommendation always favors brand. Trust collapses. + +Stale recommendation. Reasoning based on outdated capabilities. + +--- + +## Methodology-level choices that stay in the public skill + +The visible-defended-overridable principle. Patterns A through E. Defending the recommendation. The override path. Framing. Audience-fit recommendations. Transparency. The bias risk. Testing. Common failures. + +## Implementation choices that stay internal + +Specific recommendation engines for specific tools. Specific audience-segment mappings. Specific reasoning copy. The team's validation processes. These vary by team. diff --git a/skills/competitor-experience-audit/SKILL.md b/skills/competitor-experience-audit/SKILL.md new file mode 100644 index 0000000..0eee8fd --- /dev/null +++ b/skills/competitor-experience-audit/SKILL.md @@ -0,0 +1,191 @@ +--- +name: competitor-experience-audit +description: "Audit the brand, UX, and site design of the leading sites in a vertical as a set of observable cross-site patterns, producing the experience bar a new build must meet or beat. Use this skill whenever the user wants to assess the competitive design field, capture vertical conventions, identify the design and UX bar of a category, or set the experience standard before a build. Triggers on competitor experience audit, UX audit, site design audit, brand audit, design conventions, what makes these sites good, vertical conventions, storefront patterns, merchandising patterns, layout density, primary task, design bar, category conventions, retail vs marketing register, what does the field do. Also triggers when an audit of the competitive field has captured technical signals (SEO, accessibility) but never named the brand, UX, or design conventions, and the build downstream will read as off-vertical without that bar." +category: research +catalog_summary: "Cross-site experience patterns and gaps across a vertical" +display_order: 6 +--- + +# Competitor Experience Audit + +Capture the brand, UX, and site design that the leading sites in a vertical observably share, and where they fall short. The output is the experience bar a new build must meet or beat, grounded in cross-site patterns rather than aesthetic opinion. + +Stack-agnostic. Works on any SiteShape (ecommerce-catalog, inventory-listing, hospitality-food, b2b-manufacturer, and so on). Auto-parts catalogs are the first test case, not the only target. + +This skill is the brand / UX / design counterpart to a technical audit like `seo-onpage` or `accessibility-audit`. Technical findings are objective (a missing canonical is missing). Design is more subjective, so this skill is deliberately written to make the subjective assessable: every dimension is judged by observable questions about what the leading sites actually do, reported as patterns and gaps, and marked `not_assessable` whenever the evidence does not support a judgment. + +--- + +## When to use + +- Setting the experience bar for a new build in a vertical you have not built in before +- Capturing the design and UX conventions a credible site in the category is expected to carry +- Auditing the competitive field for a critic or strategy review where SEO and accessibility have been covered but design and experience have not +- Naming the positioning opportunity that recurs across the leaders (the gap even the leaders share) +- Pairing with a technical audit (SEO, accessibility) so the competitor review captures both axes + +## When NOT to use + +- Rating a single page or one brand's design taste in isolation (use `design-standards` or `brand-style-guide` for production design decisions on a known build) +- Backlink, keyword, or SERP-overlap competitive analysis (use `seo-competitor`) +- Generating a creative direction from scratch for a new brand (use `creative-direction` and `brand-discovery`) +- User research with real participants on your own product (use `ux-research`, `usability-testing`) +- Auditing a single page's on-page SEO or accessibility against the audit suite (use `seo-onpage`, `accessibility-audit`) + +--- + +## Required inputs + +- The vertical and a list of the leading sites in it (3 to 6 sites; more than 6 stops surfacing new patterns) +- Access to the rendered sites (a real browser view, not just static HTML; see "Static vs rendered" below) +- The site shape the audit feeds, if known (ecommerce-catalog, inventory-listing, etc.); this scopes which dimensions to weight +- Any explicit constraint on the build downstream (the brand voice, the audience, the conversion the build will own) + +If the list of leading sites is unknown, ask. Picking the wrong field produces an experience bar against the wrong vertical. + +### Static vs rendered + +Some dimensions can be partially assessed from static HTML (primary navigation, the catalog/category surface count, the presence of search). Most cannot. Layout density, brand register, motion, trust-signal prominence, and the rendered hierarchy of the first viewport all need the rendered page to judge honestly. If you only have static HTML for a site, mark every rendered-only dimension `not_assessable` for that site rather than guessing. + +--- + +## The framework: 7 experience dimensions + +Each dimension is judged by observable questions across the leading sites in the field, then reported as a cross-site pattern plus the gap (where the leaders converge, and where even they fall short). + +Score each dimension as `Pattern present` (the field converges on a recognizable convention), `Mixed` (the field splits across two or three approaches), or `Gap` (no convention emerges, or every leader misses it). Mark `not_assessable` when the evidence cannot support a judgment. + +Never write `Good design` or `Bad design` or any aesthetic verdict. The dimensions are about what the field observably does, not whether you like it. + +### 1. Primary-task prominence + +Does the site lead with the visitor's primary job, or bury it? + +- What is the largest, earliest interactive element on the first viewport? (For auto-parts: typically a fitment selector. For hospitality-food: a menu or reservation entry.) +- How many clicks or scrolls to the core task? +- Does the site protect the primary task from competing CTAs in the hero? + +Observable signal: count the elements that compete for first attention, identify which one the layout actually privileges, name what the field converges on as the primary task. + +### 2. Layout register and density + +Is the layout retail-dense, editorial, or marketing-airy? Cross-reference `creative-direction` aesthetic positions (editorial restrained, polished standard, controlled maximalist, expressive maximalist) for vocabulary; do not redefine that here. + +- How many distinct modules appear above the fold? +- What is the content-per-viewport ratio (dense storefront, calm editorial, generous marketing)? +- Does the page read as a storefront, a catalog, a landing page, or a brochure? + +Observable signal: count modules above the fold across the field; describe the register the leaders share, not whether you find it attractive. + +### 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape? + +- How many category, collection, or entry-point modules appear before scroll? +- How is depth signaled (mega-menu, grid, side rail, faceted search)? +- Is the surface flat (one tier visible) or hierarchical (parent plus child categories shown together)? + +Observable signal: count the category entry points and describe the navigation depth pattern the field uses. + +### 4. Primary navigation and search paths + +Do the sites serve both the know-what-I-want path and the browse path? + +- Is search prominent and primary, secondary, or absent? +- What paths are offered (by category, by brand, by attribute, by vehicle, by location, by occasion)? +- Where does the primary nav sit (top, side, sticky, mega-menu)? + +Observable signal: list the paths the field offers, score whether each path is primary, secondary, or missing. + +### 5. Brand register and conviction + +What brand posture do the leading sites take, and is it consistent across the page? + +- Color, type, imagery: utilitarian, premium, friendly, institutional, technical, expressive? +- Voice in headings and microcopy: direct, persuasive, technical, warm, plain? +- Trust signals: institutional (long-standing, association badges), social (reviews, community), or operational (in-stock, warranty, fitment confirmation)? + +Cross-reference the `creative-direction` and `brand-archetype-system` skills for the vocabulary. Report the register the field converges on. Do not rate the taste; describe what posture the leaders take. + +### 6. Trust and conversion signals + +What recurring trust and conversion conventions does the field use? + +- Reviews, guarantees, social proof, badges +- Pricing transparency (price visible, no surprises, total cost surfaced) +- Stock and availability signals +- Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it) +- Return, shipping, or service-level promises + +Observable signal: which signals appear across the field, where they appear, and which the leaders share. + +### 7. Recurring vertical conventions (the synthesis) + +The patterns that recur across the leaders and define what a credible site in this vertical is expected to have. This is the synthesis of dimensions 1 through 6 into a short list of "if your build does not do this, it will read as off-vertical." + +Observable signal: which conventions recur on 3 of N or more of the leading sites; which are absent across the field (the gap that a positioning opportunity exploits). + +--- + +## The honesty guardrail (load-bearing) + +This is not negotiable. The credibility of an experience audit erodes the moment it slides into taste: + +- Report what the leading sites observably do and where they observably fall short, as cross-site patterns. Do not render personal aesthetic judgments ("this is ugly", "good design", "the typography is clean"). Aesthetic verdicts belong in `art-direction` or `design-standards`, not here. +- When the evidence does not support a judgment, say so plainly and mark the dimension `not_assessable` for that site or that pattern. Common cases: layout and density cannot be judged from un-rendered static HTML; motion and animation cannot be judged from a screenshot; brand voice cannot be judged from a single page. +- Do not name a convention from one site. A pattern is a recurrence across the field (3 of N or more); one site doing something distinctive is a single-site observation, not a convention. +- The output is a grounded experience bar: the conventions and gaps of the field, usable as a standard a build must meet. It is not an opinion piece. + +If the user asks "is this design good", redirect to observable patterns ("the leading sites in the field share X, Y, Z; this build does X and W but not Y or Z; that is the gap"). If the user asks for an aesthetic call, point them at `design-standards` or `art-direction`. + +--- + +## Workflow + +1. Confirm the vertical and the leading sites. Ask if either is unclear; an audit against the wrong field is worse than no audit. +2. Render and view each site as a user would. Open in a real browser, on the device class the field's visitors use (desktop and mobile for ecommerce; mobile-first for hospitality-food; etc.). Do not work from static HTML alone for any dimension marked rendered-only. +3. Assess each dimension across the field. Use [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) to score each site on each dimension. Mark `not_assessable` wherever the evidence is thin. +4. Synthesize cross-site patterns. For each dimension, name the recurring convention (or the split, or the gap). Distinguish patterns the field converges on from single-site moves. +5. Name the gap (the positioning opportunity). Where do even the leaders fall short? That is where a new build's positioning can exploit the field. +6. Write the bar. Use the template in [`references/audit-template.md`](references/audit-template.md). Default output is a markdown experience bar, generalized to pattern-level if it will feed a public showcase workup (no named competitors in the public version). +7. Hand the bar to the build skills. The output is the standard `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill (`landing-page-copy`, `frontend-component-build`) read as the experience bar to meet. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Rate the design of these sites." Vague. Redirect to observable patterns: what the leading sites in the field do across the seven dimensions, not whether you like it. +- Judging un-rendered pages for layout, density, or motion. Mark `not_assessable` and get the rendered view. Static HTML supports only partial assessment; do not guess at design quality you cannot see. +- Naming a convention from one site. A pattern is a recurrence across the field. One site doing something distinctive is a single-site observation; flag it that way, not as a convention. +- Substituting personal taste for field patterns. "I think the colors are good" is not an audit finding. "The field converges on a navy-and-rust register; this site uses it" is. +- Aesthetic verdicts dressed as observations. Watch for "clean", "modern", "professional", "premium-feeling" with no observable signal underneath. If you cannot point at a specific observable thing, you are giving taste, not a pattern. +- Skipping the gap. An audit that names only what the leaders do well is half the value. The recurring weakness across the field is where a positioning opportunity lives; name it. +- Generalizing too soon. A 2-site sample is not the field. If you can only render 2 of 5 leaders, mark the audit `partial` and call out what is assessed vs what is not. + +--- + +## Output format + +Default output is a markdown experience bar at `experience-audit-[vertical-slug].md` in the project root. Structure: + +1. Vertical and the field surveyed (sites assessed, what could not be rendered) +2. Score per dimension across the field +3. Cross-site patterns (the conventions the leaders converge on) +4. Gaps (where the field falls short, the positioning opportunity) +5. The experience bar (the synthesis: what a credible build in this vertical must do) +6. `Not_assessable` items (what could not be judged and why) + +Keep the bar under 1500 words. If a dimension needs deeper treatment, link to a deeper appendix rather than expanding inline. + +### Scrub for showcase use + +If the audit will feed a public showcase workup, scrub for named competitors before publishing. The named version stays operated-side; the public workup carries the patterns and the gaps in generalized form. This mirrors how Basano's competitor review already handles named sites in its model-backed audit. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable experience-audit template, copy and use. Generalized and named variants both present. +- [`references/experience-dimensions-checklist.md`](references/experience-dimensions-checklist.md) - The observable questions per dimension, in scoring order. diff --git a/skills/competitor-experience-audit/references/audit-template.md b/skills/competitor-experience-audit/references/audit-template.md new file mode 100644 index 0000000..d244e9a --- /dev/null +++ b/skills/competitor-experience-audit/references/audit-template.md @@ -0,0 +1,136 @@ +# Competitor Experience Audit: [Vertical] + +Site shape: [ecommerce-catalog / inventory-listing / directory-marketplace / local-service-booking / subscription-app / hospitality-food / institution-mission / b2b-manufacturer / ecommerce-standout / hospitality-experience] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Field assessed: [N sites] +Rendered: [N of N] Static-only: [N of N] + +--- + +## Field surveyed + +\| Site \| Rendered \| Notes \| +\|---\|---\|---\| +\| [Site 1] \| [yes/no] \| [any access caveat] \| +\| [Site 2] \| [yes/no] \| \| +\| [Site 3] \| [yes/no] \| \| +\| [Site 4] \| [yes/no] \| \| +\| [Site 5] \| [yes/no] \| \| + +If publishing the audit publicly, prepare a generalized version that drops the named column; the named version stays operated-side. + +--- + +## Summary + +[Two to three sentences. The cross-site picture: what the field converges on, where it falls short, what the positioning opportunity is. Generalized; no aesthetic verdicts.] + +\| Dimension \| Score \| One-line pattern \| +\|---\|---\|---\| +\| Primary-task prominence \| [Pattern present / Mixed / Gap / Not assessable] \| \| +\| Layout register and density \| \| \| +\| Merchandising and category surface \| \| \| +\| Primary navigation and search paths \| \| \| +\| Brand register and conviction \| \| \| +\| Trust and conversion signals \| \| \| +\| Recurring vertical conventions \| \| \| + +--- + +## Cross-site patterns + +### 1. Primary-task prominence + +[What the field converges on as the primary task; what element carries it; how protected the task is from competing CTAs. Observable signal: what is the largest, earliest interactive element, and what is the click count to the core task.] + +Pattern: [The field's convention] +Outliers: [Any leader that breaks the pattern, and what they do instead] + +### 2. Layout register and density + +[The register the field shares (retail-dense, editorial, marketing-airy, hybrid). Cross-reference `creative-direction` aesthetic positions for vocabulary.] + +Pattern: [The field's register] +Outliers: [Any leader that uses a different register] + +### 3. Merchandising and category surface + +[How much of the offering is surfaced before scroll; the navigation depth pattern; mega-menu vs grid vs side rail.] + +Pattern: +Outliers: + +### 4. Primary navigation and search paths + +[Which paths the field offers (search-first, by-category, by-brand, by-attribute, by-vehicle, by-location). Score each path as primary / secondary / absent.] + +Pattern: +Outliers: + +### 5. Brand register and conviction + +[The brand posture the leaders converge on. Cross-reference `creative-direction` and `brand-archetype-system`.] + +Pattern: +Outliers: + +### 6. Trust and conversion signals + +[Which signals appear across the field (reviews, guarantees, pricing transparency, stock, fitment confirmation, return policy). Where they appear.] + +Pattern: +Outliers: + +### 7. Recurring vertical conventions + +[The synthesis. The conventions a credible site in this vertical is expected to have, named explicitly. A build that ignores these will read as off-vertical.] + +Conventions: +- [Convention 1] +- [Convention 2] +- [Convention 3] +- ... + +--- + +## Gaps (the positioning opportunity) + +[Where even the leaders fall short. The recurring weakness across the field. This is the wedge a new build's positioning can exploit. Observable, not speculative.] + +- [Gap 1]: [The weakness the field shares; how it shows up across N of the N leaders; what a build that fixes it would look like.] +- [Gap 2]: +- [Gap 3]: + +--- + +## The experience bar (the build standard) + +A credible build in this vertical, against this field, must: + +- [Bar item 1 - usually maps to a recurring convention from dimension 7] +- [Bar item 2] +- [Bar item 3] +- ... + +Optional positioning move: + +- [The build's wedge - exploit one or more of the gaps above] + +Hand this bar to `creative-direction`, `design-standards`, `information-architecture`, and the relevant build skill so they read as the standard to meet, not as suggestions. + +--- + +## Not assessable + +[Dimensions or sites that could not be judged honestly. Common reasons: site not renderable, motion not capturable, brand voice not derivable from a single page, depth of the category surface only visible after authentication.] + +- [Dimension or site]: [Why it cannot be judged from the evidence available. What evidence would be needed to assess it.] +- [Dimension or site]: +- ... + +--- + +## Generalized version (for showcase / public use) + +If this audit will feed a public showcase workup or a published critique, copy the sections above into a generalized form that drops the named-competitor column and the Outliers callouts. Patterns and gaps are publishable; named-and-rated competitor breakdowns are not. The named version stays operated-side. diff --git a/skills/competitor-experience-audit/references/experience-dimensions-checklist.md b/skills/competitor-experience-audit/references/experience-dimensions-checklist.md new file mode 100644 index 0000000..8313356 --- /dev/null +++ b/skills/competitor-experience-audit/references/experience-dimensions-checklist.md @@ -0,0 +1,134 @@ +# Experience Dimensions Checklist + +Score each leading site on each dimension using the observable questions below. Mark `not_assessable` whenever the evidence does not support a judgment; do not guess. The audit's value rests on honest observation. + +The rule for every dimension: name what is observably true across the field, not whether you like it. If you cannot point at a specific observable thing, you are giving taste, not a pattern. + +--- + +## 1. Primary-task prominence + +The visitor arrives with a primary job. The leading sites either lead with that job or bury it. + +- [ ] What is the largest, earliest interactive element on the first viewport? +- [ ] Does that element correspond to the visitor's primary task in the vertical? (Auto-parts: a fitment selector. Hospitality-food: a menu or reservation entry. Inventory-listing: a search or filter. Local-service-booking: a "book now" or service picker.) +- [ ] How many clicks or scrolls from arrival to completing the core task? +- [ ] How many competing CTAs share the hero with the primary task? +- [ ] Is the primary task reachable from a sticky element on scroll? + +Rendered required: partial. The primary task can usually be identified from a static fetch (it is in the markup), but its visual dominance and protection from competitors requires the rendered view. + +--- + +## 2. Layout register and density + +Storefront, editorial, marketing-airy, hybrid. Cross-reference `creative-direction` aesthetic positions (editorial-restrained, polished-standard, controlled-maximalist, expressive-maximalist) for vocabulary. + +- [ ] How many distinct modules appear above the fold on a standard desktop viewport? +- [ ] How many on a mobile viewport? +- [ ] What is the content-per-viewport ratio: dense (a catalog or storefront), calm (an editorial), generous (a landing page or brochure)? +- [ ] Where does the page read as a storefront vs a marketing page? +- [ ] Does the whitespace ratio match a retail or a publication register? + +Rendered required: yes. Static HTML cannot tell you what users see in the first viewport. + +--- + +## 3. Merchandising and category surface + +How much of the catalog or offering is surfaced at once, and in what shape. + +- [ ] How many category, collection, or entry-point modules appear before scroll? +- [ ] How is depth signaled (mega-menu hover, fly-out, side rail, faceted search, breadcrumb expansion)? +- [ ] Is the surface flat (one tier visible) or hierarchical (parent plus child)? +- [ ] Are the categories shown as text, icon, image, or hybrid? +- [ ] Is a search-first path offered alongside the category-first path? + +Rendered required: partial. Counts and structure show up in static markup; visual emphasis and reveal patterns need rendering. + +--- + +## 4. Primary navigation and search paths + +The know-what-I-want path and the browse path. Both, or only one. + +- [ ] Is a search input prominent (in the header, large input), secondary (small, in a side panel), or absent? +- [ ] Which paths does the primary nav offer (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience)? +- [ ] Score each available path: primary / secondary / absent. +- [ ] Where does the primary nav sit (top bar, side drawer, mega-menu, sticky)? +- [ ] On mobile, does the primary nav collapse into a hamburger or stay flat? + +Rendered required: partial. Path inventory is in the static markup; visual prominence and primary-vs-secondary judgment needs the rendered view. + +--- + +## 5. Brand register and conviction + +The posture the leading sites take and whether they hold it across the page. + +- [ ] Color palette: muted / saturated; warm / cool; monochrome / multi-hue. +- [ ] Typography: humanist / geometric / serif-led / display-led; one face or paired. +- [ ] Imagery: photographic (studio, lifestyle, editorial); illustrated; abstract; none. +- [ ] Voice in headings: direct, persuasive, technical, warm, plain, institutional. +- [ ] Voice in microcopy and CTAs: matches the heading voice or breaks from it. +- [ ] Brand posture: utilitarian / premium / friendly / institutional / technical / expressive. + +Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; use those terms rather than inventing new ones. + +Rendered required: yes. Brand register is a visual judgment; static HTML alone cannot support it. + +--- + +## 6. Trust and conversion signals + +The recurring conventions a credible commercial page in this vertical carries. + +- [ ] Reviews / ratings present (where, how prominent, count or average shown). +- [ ] Guarantees (return policy, money-back, warranty) surfaced or hidden. +- [ ] Pricing transparency: price visible without interaction; total cost surfaced before checkout; "starting at" or full? +- [ ] Stock or availability signals (in stock, low stock, lead time). +- [ ] Fitment, sizing, eligibility, or compatibility confirmation (where the vertical requires it). +- [ ] Shipping or service-level promises (ETA, free over $X, same-day). +- [ ] Institutional trust signals (years in business, association badges, certifications). +- [ ] Social proof (logos of customers, press mentions, testimonials). + +Rendered required: partial. Many trust signals are visible in markup; placement and emphasis are rendered judgments. + +--- + +## 7. Recurring vertical conventions (synthesis) + +The patterns that recur across the field define what a credible site in this vertical is expected to have. This is not a new measurement; it is the synthesis of dimensions 1 through 6. + +- [ ] Which conventions appear on 3 of N or more of the leaders? +- [ ] Which appear on fewer than 3 (single-site moves, not conventions)? +- [ ] Which are absent across the field (the gap a positioning opportunity exploits)? + +The output of this dimension is a short list: "If your build does not do X, Y, Z, it will read as off-vertical." That list is what goes into the experience bar. + +--- + +## Scoring rubric + +For each dimension, score the field (not a single site): + +- Pattern present. 3 of N or more leaders converge on a recognizable convention. Name it. +- Mixed. The field splits across two or three distinct approaches. Name each, and note which the new build should adopt. +- Gap. No convention emerges, or every leader misses the dimension. Often this is the positioning opportunity. +- Not assessable. The evidence does not support a judgment. Name what evidence would be needed. + +For each site (operated-side only; the public version drops named scores): + +- Mark each dimension `pattern-aligned`, `outlier`, or `not assessable`. + +--- + +## What this checklist will not do + +- Rate a single site's design taste. Use `design-standards` for production design review. +- Tell you which vertical your build belongs in. The vertical and field are inputs to this skill, not outputs. +- Replace user research. Use `ux-research` and `usability-testing` for real-user assessment. +- Generate creative direction from scratch. Use `creative-direction` and `brand-discovery` for that. +- Produce a SERP or backlink competitive analysis. Use `seo-competitor`. + +This checklist names patterns and gaps so a downstream build has a real bar to meet. Everything else is out of scope. diff --git a/skills/content-and-copy/SKILL.md b/skills/content-and-copy/SKILL.md new file mode 100644 index 0000000..e8a1f80 --- /dev/null +++ b/skills/content-and-copy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: content-and-copy +description: "Write or edit website copy, blog content, and editorial pieces with attention to voice, structure, and goal. Use this skill whenever the user wants to write an article, draft website copy, edit existing content for clarity or voice, write a blog post, or produce general editorial content. Triggers on write a blog post, draft an article, write copy for, edit this, rewrite this, write content, write a guide, draft a how-to, write web copy. Also triggers when content has been outlined and now needs to be written, or when existing content needs voice or clarity edits." +category: content +catalog_summary: "Website copy, blog content, content production frameworks" +display_order: 3 +--- + +# Content and Copy + +Write or edit content that serves a specific reader and goal. Stack-agnostic. This skill is for general content production. Specialized skills exist for landing pages (`landing-page-copy`) and email (`email-sequences`). + +--- + +## When to use + +- Writing a blog post or article +- Drafting website copy (homepage sections, about, services) +- Editing existing content for voice or clarity +- Writing how-to guides, listicles, or explainers +- Producing knowledge base or help center articles +- Adapting brand voice to a specific piece + +## When NOT to use + +- Landing pages with conversion goals (use `landing-page-copy`) +- Email campaigns or sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- SEO keyword research (use `seo-keyword`) +- Content strategy and planning (use `content-strategy`) + +--- + +## Required inputs + +- The piece to be written or edited +- The target reader (specific audience segment) +- The goal of the piece (inform, convert, rank, retain, entertain) +- The brand voice (or willingness to define it) +- Length target and any structural constraints + +If brand voice is undefined, run `brand-voice` first or use a working voice and document it as you go. + +--- + +## The framework: 5 dimensions + +Strong content is strong on all five. Weakness on any one drags the rest down. + +### 1. Hook + +The opening earns the read. Most readers decide whether to continue within 3 to 5 seconds. + +Strong hooks do one of: + +- Promise specific value. "By the end, you'll know exactly which X to pick for your situation." +- Surface a tension. "Most advice on X is wrong. Here's why." +- Open a loop. A question or scenario the rest of the piece resolves. +- State a contrarian point. Provided you can defend it. +- Show, don't summarize. A specific moment or scenario the reader recognizes. + +Weak hooks: + +- Throat-clearing ("In today's fast-paced world...") +- Dictionary-definition openers ("X is a type of Y that...") +- Stating the obvious ("Many people struggle with X.") +- Vague promises ("This article will explore X.") + +### 2. Structure + +The reader follows the flow without effort. + +Common structures: + +- Problem → Solution → Proof. Most non-fiction. +- List + reasoning. Listicles with substance, not filler. +- How-to (numbered steps). Procedural content. +- Compare → Contrast → Recommend. Comparison and review content. +- Story → Lesson. Narrative non-fiction. +- Question → Answer → Implication. Explainers and analysis. + +Pick a structure. Stick to it. Most weak content fails because the writer drifted between structures. + +### 3. Voice + +The piece sounds like the brand. + +- Voice attributes consistent throughout (per `brand-voice` definition) +- Tone shifts appropriately for context (a serious topic gets a serious tone, even from a playful brand) +- Vocabulary preferences honored +- Grammar and style standards followed (contractions, em dashes, sentence length) +- Reads aloud like the brand would actually talk + +Test: Read a paragraph aloud. Does it sound like the brand? If it sounds like AI, generic marketing, or someone else's voice, edit until it doesn't. + +### 4. Substance + +The piece earns its length. Every paragraph adds something. + +Substance comes from: + +- Specifics. "Roughly 40 percent" beats "many." Names, numbers, examples, data. +- Original perspective. Your take, not a summary of everyone else's. +- Actionable detail. What the reader does with this information. +- Honest tradeoffs. What's NOT true, what doesn't work, what's overhyped. +- Real examples. Specific scenarios, real customers, real failures. + +Lack of substance shows up as: + +- Padding ("It's important to note that...") +- Restating the same point in three different paragraphs +- Generalities that anyone in the category could write +- Word counts hit by stretching, not depth + +### 5. Closing + +The piece ends with intention. + +Strong closings: + +- Resolve the loop opened in the hook. +- Issue a specific next action. What does the reader do now? +- Land a memorable line. Something quotable. +- Return to the opening. Echo or invert the first line. + +Weak closings: + +- Summary that restates the article +- "Hope this helps!" or equivalent +- A wall of CTAs from unrelated programs +- Trailing off with no clear ending + +--- + +## Workflow + +### For new pieces + +1. Confirm the brief. Reader, goal, length, voice. If the brief is vague, do not write yet. +2. Outline. Structure first. Headlines and section purposes only. Skip prose until the structure is sound. +3. Open with the hook. Write the opening before anything else. If the hook isn't working, the rest won't either. +4. Draft for substance. First draft is about getting the substance down. Voice comes in editing. +5. Edit for voice. Read aloud. Tighten sentences. Cut padding. Apply brand voice. +6. Edit for clarity. Each paragraph: does it earn its place? Each sentence: is the meaning unambiguous? +7. Pre-publish checks. Headers in order, no skipped levels, internal links present, image alt text written, SEO basics applied (title, meta, slug). + +### For editing existing content + +1. Read the whole piece first. Do not edit on first read. Understand it before changing it. +2. Identify what's working. Note the strong sections so you don't damage them. +3. Identify what's broken. Voice mismatches, weak structure, vague claims, padding. +4. Edit by priority. Structure first (move sections, cut sections). Then substance (strengthen claims). Then voice. Then sentence-level polish. +5. Read aloud. Catch awkward phrasing the eye misses. + +--- + +## Failure patterns + +- Writing without a brief. Without reader, goal, and voice defined, the piece drifts. +- Burying the lead. The most important thing is in paragraph 8 because the writer "got there." +- Padding to hit word count. Length should serve the reader, not the production schedule. +- Generic voice. Sounds like every other article in the category. Brand voice neutralized. +- Weak transitions. Sections feel disconnected. Reader has to do the work the writer should have done. +- No closing. The piece runs out instead of ending. +- Edit by adding. Fixing weak content by piling on more words. Strong editing usually cuts. +- Ignoring the headers. Headers carry navigation weight. Bad headers fail readers who scan. + +--- + +## Output format + +Default output is a markdown document at `[content-slug].md` ready to import into the CMS. + +Structure: +```markdown +# [H1: matches the title or tightly paraphrases] + +[Hook paragraph. Earns the read in 3 to 5 seconds.] + +[Body content with H2 sections, H3 subsections where useful.] + +## [H2 section heading - descriptive, not clever] + +[Section content.] + +### [H3 if needed] + +[Subsection content.] + +## [H2 section heading] + +[Section content.] + +## [Closing section] + +[Closing that resolves and points to next action.] +``` + +Front-matter for SEO and CMS: +```yaml +--- +title: [SEO title, 50 to 60 chars] +description: [Meta description, 120 to 160 chars] +slug: [url-slug] +author: [author] +date: [YYYY-MM-DD] +last_updated: [YYYY-MM-DD] +tags: [tag1, tag2] +category: [category] +--- +``` + +--- + +## Reference files + +- [`references/content-brief-template.md`](references/content-brief-template.md) - The brief that should exist before any content is written. +- [`references/content-edit-checklist.md`](references/content-edit-checklist.md) - Pre-publish editing checklist. diff --git a/skills/content-and-copy/references/content-brief-template.md b/skills/content-and-copy/references/content-brief-template.md new file mode 100644 index 0000000..d1bc428 --- /dev/null +++ b/skills/content-and-copy/references/content-brief-template.md @@ -0,0 +1,242 @@ +# Content Brief Template + +Every piece of content needs a brief before writing. Without one, the piece will drift, miss the audience, or fail the goal. + +A brief takes 15 minutes to write. Saves hours of rewrites later. + +--- + +## Template + +```markdown +# Brief: [Working title] + +## Reader + +Who specifically is this for? Be precise. + +- Primary audience segment: [from content strategy] +- What they currently know: [their starting point] +- What they want to know: [the question they're bringing] +- What they need to do after: [the action this enables] + +## Goal + +What does this piece accomplish? + +- Primary goal: [Inform / Convert / Rank / Retain / Entertain] +- Specific outcome: [What measurable thing should happen] +- Success metric: [How we know it worked] + +## Pillar / Strategy fit + +- Content pillar this serves: [from content strategy] +- Cornerstone or supporting: [Cornerstone / Supporting] +- Internal links to / from: [related pieces] + +## Angle + +What's the take? Why does this piece exist when others on the topic already do? + +- The angle: [One sentence] +- Why ours is different: [Specific differentiator] +- The contrarian or surprising element: [If any] + +## Format + +- Type: [Article / Guide / Listicle / Comparison / Case study / How-to / Tutorial / Explainer] +- Length: [Word count or range] +- Reading level: [Beginner / Intermediate / Advanced] +- Required elements: [Images, tables, video, downloads, code blocks] + +## Structure + +Section-by-section outline. Headlines + 1 sentence on what each section does. + +### [H1: Working title] + +[Hook approach: how the piece will earn the read in 3 to 5 seconds] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Section title] +[What this section accomplishes] + +### H2: [Closing section] +[How the piece resolves and what action it points to] + +## Voice + +- Apply: [Brand voice attributes] +- Tone for this piece: [How tone adjusts for the topic] +- Specific cues: [Anything to lean into or avoid for this topic] + +## Sources and citations + +- Required sources: [Specific data, studies, or experts to cite] +- Internal data: [Anything we have that competitors don't] +- Quotes from: [SMEs, customers, founders to include] + +## SEO + +- Primary keyword: [from keyword research] +- Secondary keywords: [supporting terms] +- Search intent: [Informational / Commercial / Transactional / Navigational] +- Target SERP feature (if any): [Featured snippet / People also ask / etc.] +- Title tag (50-60 chars): [Draft] +- Meta description (120-160 chars): [Draft] +- URL slug: [Draft] + +## Distribution + +Where and how this piece gets seen after publishing. + +- Newsletter inclusion: [Yes/No] +- Social posts: [Number of variations and channels] +- Outreach: [Specific people or sites to ping] +- Internal links to add from: [Existing pieces that should link to this] + +## Constraints and notes + +- Deadline: [Date] +- Word count: [Target] +- Required approvals: [Who needs to sign off] +- Things to avoid: [Anything off-limits for this piece] + +## Out of scope + +What this piece is explicitly NOT about. Prevents scope creep during writing. + +- [Topic not in this piece] +- [Topic not in this piece] +``` + +--- + +## Filled example + +```markdown +# Brief: How to choose between SQL and NoSQL for a startup + +## Reader + +- Primary audience segment: Technical founders or first engineers at early-stage startups (under 20 employees) +- What they currently know: Basics of databases, used both SQL and NoSQL casually +- What they want to know: Which to pick for their specific situation, what they'll regret in 18 months +- What they need to do after: Make the database choice and feel confident enough to commit + +## Goal + +- Primary goal: Inform (with rank as a secondary) +- Specific outcome: Reader makes the decision and references this piece when others ask +- Success metric: Top 3 ranking on "SQL vs NoSQL for startups" within 6 months; 5+ minute average read time + +## Pillar / Strategy fit + +- Content pillar: Startup engineering decisions +- Cornerstone or supporting: Cornerstone for the pillar +- Internal links: from "Founder's guide to technical debt" and to "When to migrate your database" + +## Angle + +- The angle: Most articles compare SQL and NoSQL on technical features. We compare on regret-likelihood at 18 months in production. +- Why ours is different: Built around real failure modes, not theoretical capabilities +- Surprising element: Most startups regret choosing NoSQL for the wrong reasons, not the right ones + +## Format + +- Type: Long-form decision guide +- Length: 2,500 to 3,500 words +- Reading level: Intermediate +- Required elements: Decision flowchart, 2-3 case examples, comparison table + +## Structure + +### H1: How to choose between SQL and NoSQL for a startup + +Hook: Open with a specific founder's regret moment from a real conversation. + +### H2: The wrong question (and the right one) +Most teams ask "which is faster" or "which scales." Reframe to "what will I regret in 18 months." + +### H2: When SQL is the right call +Specific scenarios with examples. + +### H2: When NoSQL is the right call +Narrower scenarios than most articles claim. + +### H2: The hybrid that works +Real-world pattern: SQL primary, targeted NoSQL for specific use cases. + +### H2: A decision flowchart +The actionable diagram. The piece's main asset. + +### H2: What to do if you've already chosen wrong +Migration realism, with specific signals it's time to switch. + +### H2: Closing +Return to the opening founder. Where they ended up. The decision framework as the takeaway. + +## Voice + +- Apply: Direct, experienced, not-academic +- Tone: Slightly weary about industry overcomplication +- Specific cues: First-person plural ("we"), war-story examples preferred over textbook explanations + +## Sources + +- Internal: Conversations with [N] startup CTOs +- External: [List of specific studies, posts, papers] +- Quotes: [Names if any] + +## SEO + +- Primary keyword: SQL vs NoSQL startup +- Secondary: SQL vs NoSQL for small teams, when to use NoSQL, NoSQL mistakes startups +- Search intent: Informational with commercial undertone +- Target SERP feature: Featured snippet for "when to use NoSQL" +- Title tag: SQL vs NoSQL for Startups: How to Avoid 18-Month Regret +- Meta: A practical guide to picking a database when you're 5 engineers, deciding fast, and don't want to migrate twice. Includes a decision flowchart. +- URL slug: sql-vs-nosql-startup + +## Distribution + +- Newsletter: Feature in next issue +- Social: 3 LinkedIn variations, 1 X thread +- Outreach: Email to 5 startup engineering newsletter writers +- Internal links: Add from /resources/cto-decisions and /technical-debt-guide + +## Constraints + +- Deadline: [Date] +- Word count: 3,000 target +- Approvals: Editorial lead and one technical SME +- Avoid: Vendor-specific recommendations (we're not selling a product) + +## Out of scope + +- Specific NoSQL database comparisons (CouchDB vs MongoDB) - separate piece +- Schema design tutorials - separate piece +- ORM choice - separate piece +``` + +--- + +## When to skip the brief + +The brief is required for: +- Cornerstone content +- Anything over 1500 words +- Anything with a conversion goal +- Anything written by someone other than the editorial lead + +The brief can be lighter for: +- Short newsletter blurbs +- Social posts +- Pieces written by the editorial lead with the strategy fully internalized + +But "lighter" is not "absent." Even a 100-word note covering reader / goal / angle saves time. diff --git a/skills/content-and-copy/references/content-edit-checklist.md b/skills/content-and-copy/references/content-edit-checklist.md new file mode 100644 index 0000000..4e1f906 --- /dev/null +++ b/skills/content-and-copy/references/content-edit-checklist.md @@ -0,0 +1,147 @@ +# Content Edit Checklist + +A pre-publish checklist for editing content. Run it line by line before any piece of content goes live. + +The checklist catches the regular mistakes. Editing for substance is a separate pass. + +--- + +## Pass 1: substance + +Before sweating commas, confirm the piece does its job. + +- [ ] The brief is satisfied. Re-read the content brief. Does this piece deliver against every objective? +- [ ] The audience is the right one. Who is the reader? Are they assumed correctly? +- [ ] The single takeaway is clear. If a reader skims and remembers one thing, what is it? Is it what we wanted? +- [ ] The first 50 words earn the next 50. Cut throat-clearing intros. Get to the point. +- [ ] Every paragraph earns its place. If a paragraph could be removed without loss, remove it. +- [ ] The structure serves the reader. Headers form a meaningful outline. Skim test passes. +- [ ] There is one CTA per piece, and it is unmissable. Or zero, if the piece is purely informational. +- [ ] No claim is unsupported. Every fact, statistic, or assertion has a source or is hedged. +- [ ] Examples are concrete. Specific numbers, named scenarios, real artifacts beat vague "many users" generalizations. + +--- + +## Pass 2: voice and tone + +- [ ] Voice matches the brand voice document. Read aloud. If a stranger could not place this as our brand, voice is too generic. +- [ ] Tone matches the context. Promotional vs editorial vs technical vs support. Different content, different tone shifts. +- [ ] Pronouns are consistent. "You" / "we" / "our" stay stable across the piece. +- [ ] No internal voice leaked into customer-facing copy. Jargon, project names, internal team names removed. +- [ ] No first-person commentary in instructional content. ("I think you should..." → "Do this because...") + +--- + +## Pass 3: structure and scannability + +- [ ] Headings are descriptive, not clever. "How to add a payment method" beats "Money matters." +- [ ] Heading hierarchy is correct. One H1, then H2s for top-level sections, H3s under H2s. No skipping levels. +- [ ] Paragraphs are tight. Default 2-4 sentences per paragraph for web. One-sentence paragraphs are allowed for emphasis. +- [ ] Lists are used where they fit. Bullets for parallel items, numbered for sequenced steps. +- [ ] Bold and italic used sparingly. Bold for the term being defined, italic for emphasis. Not both. Not often. +- [ ] Code blocks for code. Inline code for short references. +- [ ] Tables for tabular data. Not for layout. + +--- + +## Pass 4: clarity at the sentence level + +- [ ] Active voice by default. Passive voice for specific reasons (focus on object, unknown actor, polite distancing). +- [ ] Concrete nouns and verbs. "We process" beats "processing is performed by us." +- [ ] Average sentence length under 20 words. Vary the rhythm with shorter sentences for emphasis. +- [ ] No nominalizations. "Decide" beats "make a decision." "Implement" beats "carry out the implementation of." +- [ ] No throat-clearing phrases. Cut "It is important to note that," "In order to," "At the end of the day." +- [ ] No filler intensifiers. Cut "very," "really," "quite," "actually," "basically." Each weakens the word it modifies. +- [ ] No hedge words where you mean something specific. "May," "might," "could" are honest when uncertain, weak when specific. + +--- + +## Pass 5: jargon and accessibility + +- [ ] Jargon defined on first use. Or replaced if the audience would not know it. +- [ ] Acronyms spelled out on first use. Then acronym is fine. +- [ ] No insider language. Project codenames, internal team references, deprecated product names. +- [ ] Idioms checked for global audiences. "Hit it out of the park" reads strange to non-US English readers. +- [ ] Reading level appropriate. Use a tool (Hemingway, Readable) to spot-check. For most audiences, target Grade 8-10. +- [ ] No ableist or exclusionary language. "Crazy" → "wild," "blacklist" → "blocklist," gendered defaults checked. + +--- + +## Pass 6: SEO basics + +If the piece is for organic search: + +- [ ] Primary query target identified. One phrase per piece. +- [ ] Title tag drafted. Distinct from H1, 50-60 characters, primary query near front. +- [ ] Meta description drafted. 140-160 characters, value-led, includes primary query naturally. +- [ ] H1 is unique on the site and includes the primary query. +- [ ] Internal links added. 2-5 contextual links to related content on the site. +- [ ] External links added. Link out where it adds value or substantiates a claim. +- [ ] Images have descriptive alt text. Decorative images get `alt=""`. +- [ ] URL slug is short, lowercase, hyphenated, includes primary query. +- [ ] Schema considered. Article, FAQ, HowTo, etc. - whichever fits the format. + +--- + +## Pass 7: facts and claims + +- [ ] Numbers verified. Especially statistics, dates, prices, version numbers. +- [ ] Names spelled correctly. People, products, companies, places. +- [ ] Quotes verified verbatim. Speaker name, attribution, context correct. +- [ ] Dates checked. "Last updated" reflects the actual edit date. +- [ ] Links work and go where they say. No 404s, no redirect chains, no link rot to dead resources. +- [ ] Screenshots are current. Older screenshots show outdated UI; refresh or remove. +- [ ] Claims about competitors are fair and current. Or removed. + +--- + +## Pass 8: legal and compliance + +- [ ] Trademarked terms used correctly. Capitalization, ™ or ® where required by license. +- [ ] Disclaimers present where needed. Affiliate disclosures, regulated industry disclaimers, advisory caveats. +- [ ] Customer permissions secured for testimonials. Case studies, quotes, photos. +- [ ] No confidential or pre-announcement information. Product roadmaps, unannounced pricing, internal team names. +- [ ] Image rights clear. Licensed stock, original photography, or in-house illustration. + +--- + +## Pass 9: cross-channel consistency + +If the piece appears in more than one place: + +- [ ] Web vs email vs social variants align in message. Tone may shift; substance does not contradict. +- [ ] Excerpts and meta descriptions match the piece. No bait-and-switch. +- [ ] CTAs point to current destinations. Landing page is live, has matching messaging, is not stale. + +--- + +## Pass 10: final mechanical sweep + +- [ ] Spellcheck. Twice. Once with autocorrect off so it does not silently fix names. +- [ ] Grammar check. Tool-assisted, then human-verified. +- [ ] Punctuation consistent. Oxford comma, smart quotes, dashes - per the style guide. +- [ ] No double spaces. Find-and-replace. +- [ ] No trailing whitespace at line ends. +- [ ] No placeholder text left in. "Lorem ipsum," "TBD," "[INSERT QUOTE]," "TKTK." +- [ ] No commented-out drafts in the source. Especially in CMS HTML view. + +--- + +## Sign-off + +\| Pass \| Editor \| Date \| +\|---\|---\|---\| +\| Substance \| \| \| +\| Voice and tone \| \| \| +\| Structure \| \| \| +\| Sentence-level \| \| \| +\| Jargon and accessibility \| \| \| +\| SEO \| \| \| +\| Facts and claims \| \| \| +\| Legal and compliance \| \| \| +\| Cross-channel \| \| \| +\| Mechanical \| \| \| + +Final approval: [Name, date] + +Ready to publish: [ ] diff --git a/skills/content-brief-authoring/SKILL.md b/skills/content-brief-authoring/SKILL.md new file mode 100644 index 0000000..85733df --- /dev/null +++ b/skills/content-brief-authoring/SKILL.md @@ -0,0 +1,252 @@ +--- +name: content-brief-authoring +description: "How to author a content brief that actually guides a writer (human or AI) to produce a piece that ranks, converts, or both. Per-piece editorial brief: target keyword and cluster, search intent, audience and JTBD, heading structure, entity coverage for AEO/GEO, internal linking strategy, success criteria. The middle path between thin briefs (a keyword and a deadline) and thick briefs (a 4-page document nobody reads). Triggers on content brief, brief the writer, brief the article, brief authoring, content brief template, brief audit, per-piece brief, editorial brief, target keyword brief, search intent brief. Also triggers when briefing a human writer or an AI agent on a single content piece." +category: content +catalog_summary: "Per-piece editorial brief: target keyword, intent, audience, outline, entity coverage, internal linking, success criteria, and the discipline that distinguishes useful briefs from bloat" +display_order: 2 +--- + +# Content Brief Authoring + +A senior content strategist's playbook for authoring per-piece content briefs that actually guide writers to produce content worth publishing. + +Most content briefs are some flavor of broken. The thin version is a keyword, a word count, and a deadline; the writer fills in everything else from scratch and the output is generic. The thick version is a 4-page document nobody reads, that the writer skims for the headline and the outline and ignores the rest. Either way, the brief failed at its job: making the writer's work easier and the output more predictable. + +This skill is the middle path. It defines the 12 fields that earn their keep in a content brief, the fields that bloat without helping, and the discipline of writing briefs that route a writer (human or AI) toward a content piece that ranks for its target keyword, gets cited by AI engines, converts the right reader, or whatever the success criteria say. It assumes you have decided what to write (see `content-strategy` for program-level decisions) and now you are briefing each piece. The piece itself gets written separately (see `content-and-copy`). + +When to use this skill: briefing a writer (human or AI) on an individual content piece, auditing existing briefs that are not producing good content, building a brief template for a content program, or running a brief-generation pipeline through Frase, AirOps, or another tool. + +--- + +## What this skill is for + +This skill spans the per-piece editorial brief discipline. It composes with three sister skills, and the distinction between them is what keeps each one sharp. + +- `creative-brief` is a project brief. It bridges discovery to execution at the project level: a new website, app, brand, or campaign. Audience, goals, scope, success at project scope. +- `content-strategy` is a program-level editorial strategy. Pillars, calendar, topic clusters, governance. What to produce across a quarter or a year. +- `content-and-copy` is the writing itself. Voice, structure, edit pass, tone calibration. Execution scope for general editorial. +- This skill is the per-piece brief between `content-strategy` (program decided) and `content-and-copy` (piece gets written). It briefs a single content artifact: keyword, intent, audience, outline, entities, success criteria. + +The clean reading order: `content-strategy` decides what to produce; this skill briefs each piece; `content-and-copy` writes it. If the team is briefing a redesign or a new brand build, that is `creative-brief`, not this skill. + +The audience: content strategists, SEO content marketers, editorial leads, content ops managers, agencies running content programs at scale, and any PM or marketer briefing a writer (human or AI). The voice is senior content strategist to junior content marketer. Specific, opinionated, honest about what makes a brief useful versus useless. + +--- + +## Thin vs thick vs effective briefs + +The keystone distinction. Three concrete shapes. + +Thin brief. Keyword, word count target, deadline. Maybe a one-line summary of the angle. The writer fills in everything else from scratch. Output is generic, drifts off-topic, does not rank, and does not convert. The cost is the rewrite cycle: editor spends two hours rewriting because the writer chose the wrong intent, the wrong audience, or the wrong outline. + +Thick brief. A 4-page document with executive summary, brand-guidelines refresher, comprehensive competitive analysis, voice guidelines, plus the actual brief somewhere in the middle. The writer skims for the outline, ignores the rest. Output is not materially better than from a thin brief because the writer never read most of the document. The cost is the authoring time: the strategist spends three hours producing pages of context the writer will never absorb. + +Effective brief. One to two pages. Every field earns its keep. Writer reads all of it because there is no fluff. Output is predictable enough that the editor does not have to rewrite the lede. The cost is the discipline of cutting fields that do not change writer behavior. + +The discipline. Every field in the brief has a job. If you can remove the field without degrading the output, remove it. The brief is the contract between editorial leader and writer; vague contracts produce vague output, overstuffed contracts produce output that reflects only the parts the writer read. + +Most briefs that are not working are thin, not thick. The instinct to add more usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +--- + +## The 12 fields of an effective brief + +A useful brief has 12 fields. Skip any of them and the writer fills the gap from priors; the gap is where output drifts. + +1. Target keyword + supporting cluster. Primary keyword plus 3 to 5 supporting keywords from the same cluster. The cluster is what tells the writer the topic has range; the primary is what the piece optimizes for. +2. Search intent classification. Informational, navigational, commercial, or transactional. Plus the dominant SERP format check (article, listicle, comparison, video, tool). The intent decides what kind of piece this is; the format decides the shape. +3. Target audience. Specific role and sophistication level. Not "anyone interested in X." A senior data engineer at a 500-person SaaS company is a target; "data people" is not. +4. Job to be done. The problem the reader is trying to solve when they land on the piece. One sentence. Specific. +5. Word count / depth target. Calibrated to the SERP, not to a content quota. If the top 10 are all 1,200 words, briefing 3,000 wastes effort; if the top 10 are all 4,000 words, briefing 1,500 produces a piece that cannot rank. +6. Heading structure outline. H2s and H3s explicit, ordered logically. The outline is where the writer reads the brief most carefully; spend time here. +7. Required entities, statistics, citations. For AEO and GEO, the named tools, methods, experts, and statistics the piece must cover. The entity gap is the agent's prioritization signal. +8. Internal linking strategy. 3 to 5 pages this piece should link out to with anchor text; 1 to 3 existing pages that should link back to this piece after publish. +9. External proof points. Required citations, sources, expert quotes. Not optional. +10. Anti-patterns. What not to do. Off-topic tangents the writer might wander into, off-brand voice, AI clichés the brief explicitly forbids by listing them in a do-not-use list (the standard set of overused corporate-speak adjectives, throat-clearing openers, and verbs that signal AI generation). +11. Success criteria. What good looks like. Rank for the target keyword in 90 days. Get cited by ChatGPT for the cluster within 60 days. Drive 50 trial signups in the first 30 days. Measurable, time-bound, tied to the program goal. +12. Author voice and tone reference. Link to the brand-voice guide. If the piece needs a tone shift from the default voice, note it here in one sentence. + +The fields that do not earn their keep, and should be omitted from briefs unless the writer is brand new to the program: + +- Long executive summary (the brief itself is the executive summary) +- Brand-guidelines refresher (link to it; do not repeat) +- Comprehensive competitive landscape (link to research; do not dump) +- Brief history of the publication, company, or brand (irrelevant to this piece) + +Detail and templates per content type in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## Search intent classification + +The four standard intents: + +- Informational. The reader wants to learn. SERP usually shows articles, guides, explainers. +- Navigational. The reader wants a specific brand or page. SERP usually shows the brand site at #1; ranking against navigational intent is mostly impossible unless you are the brand. +- Commercial. The reader is researching a purchase. SERP usually shows comparisons, reviews, "best X" listicles. +- Transactional. The reader is ready to buy. SERP usually shows product pages, pricing pages, signup flows. + +The dominant SERP format check. After classifying intent, scan the SERP top 10 and tag the dominant format: article, listicle, comparison, video, tool, hybrid. The dominant format tells you the shape of the piece, which is more decisive than the intent label. + +The override pattern. When the intent feels informational but the SERP shows mostly listicles, write the listicle. When the intent feels commercial but the SERP shows mostly long-form articles, write the article. The SERP is the source of truth, not your priors. Rankings come from matching the SERP's accepted shape; deviating costs ranking. + +The AEO/GEO consideration. AI engines tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. Mismatched format is a citation risk in addition to a ranking risk. + +Detail in [`references/search-intent-classification.md`](references/search-intent-classification.md). + +--- + +## Heading structure design + +Heading hierarchy patterns the brief should specify: + +- H2 sections that match common follow-up questions for the keyword. The reader's mental model is a series of questions; the H2s answer them in order. +- H3s under H2s only when they add navigational value. No orphan H3s. No H2-H3-H4 cascades that nobody scrolls through. +- Featured snippet bait pattern: a 40 to 60 word answer paragraph immediately following an H2 question. Google often pulls this paragraph as the snippet; AI engines often quote it as the citation. +- H2 ordering that matches the reader's mental model, not the writer's enthusiasm. Put the obvious answer first; the writer's clever angle goes in H2 #4, not H2 #1. + +Anti-patterns the brief should explicitly forbid: + +- H2s that all start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. +- Buried lede: H2 #4 has the actual answer. The reader bounced at H2 #2. +- Section length wildly uneven: H2 #1 is 1,500 words, H2 #2 is 80 words. The 80-word section reads as a placeholder. + +Detail in [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md). + +--- + +## Entity coverage for AEO and GEO + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that mentions the entities the SERP top-ranking pages mention, includes specific statistics with sources, contains citation-formatted proof points, and demonstrates topical depth via entity coverage. + +The entity discovery pattern, run before briefing the piece: + +1. Pull SERP top 10 for the target keyword. +2. Identify entities mentioned across multiple pages: named tools, named methods, named experts, named data sources, named statistics. +3. Identify entities mentioned by 1 to 2 pages but not in your existing content. This is the entity gap. +4. Add the gap entities to the brief as required coverage. + +The brief lists the entities the writer must mention, with light context on why each matters. The writer is not expected to research each entity from scratch; the brief includes a one-line note ("CUPED is the variance-reduction technique used by data-warehouse-experimentation teams; mention in the methodology section") so the writer can integrate without breaking flow. + +Tools that automate this: Frase has entity-gap analysis built in; AirOps composes the same analysis through its workflow builder; Surfer SEO ships entity coverage scoring. The skill is tool-agnostic; the workflow is what matters. + +Detail in [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md). + +--- + +## Internal linking strategy + +The brief should specify two link directions: + +- Outbound from this piece. 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer should not be deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. +- Inbound to this piece, post-publish. 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +The orphan-content failure mode: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. Prevented by upstream-link planning in the brief. + +The self-cannibalization check: if this piece would compete with an existing piece for the same keyword cluster, the brief flags it explicitly. The options are consolidate (merge into the existing piece), differentiate (the brief sharpens the angle so the two do not compete), or kill one. Flagging late, after the piece is written, costs more than flagging in the brief. + +Detail in [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md). + +--- + +## Brief templates by content type + +Different content types call for different brief shapes. The 12 fields are constant; the weight of each field shifts. + +- Pillar piece. Comprehensive coverage of a topic, 3,000 words plus, anchors a topic cluster. Brief emphasizes structure, comprehensiveness, internal links to and from supporting pieces. +- Supporting / cluster piece. Narrower topic, 1,000 to 2,000 words, links up to the pillar. Brief emphasizes specificity, single-question scope. +- Comparison piece (X vs Y). Commercial intent, structured comparison, decision framework. Brief emphasizes objectivity (or honest positioning if the brand is one of X or Y), table structure, "when X wins" / "when Y wins" framing. +- Listicle. Informational or commercial intent, scannable, ranked or unranked. Brief emphasizes selection criteria, ordering rationale, depth-per-item. +- How-to guide. Informational, step-by-step, screenshots. Brief emphasizes step granularity, prerequisites, troubleshooting section. +- Thought leadership / opinion. Commercial or branding, distinctive POV, signal of expertise. Brief emphasizes thesis, supporting arguments, anticipated counter-arguments. + +Each template gets a worked example in [`references/brief-templates.md`](references/brief-templates.md). + +--- + +## The brief-to-writer handoff + +Whether the writer is human or AI, the handoff has the same shape. + +- Brief delivered with all 12 fields populated. +- Writer asks clarifying questions before drafting (or the AI agent surfaces ambiguities in the brief as the first response). +- Writer or agent acknowledges the success criteria explicitly. +- First draft references the brief: "this draft hits 4 of the 5 required entities; the 5th is missing because the SERP coverage was thin and I could not find a reliable source." +- Editor reviews against the brief, not against personal taste. "The brief said X; the draft did Y" is the review framing. + +For AI handoff specifically, the brief becomes a structured prompt or a tool input. Frase, AirOps, and similar tools structure briefs as YAML or JSON for machine consumption; the same 12 fields apply. The structured format is the only difference; the contract is the same. + +Detail in [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md). + +--- + +## Brief governance + +Versioning. Every brief has a version. Significant changes (target keyword change, audience shift, scope expansion) bump the version; cosmetic edits do not. The writer always works from the current version, not a stale draft pasted into Slack three weeks ago. + +Approval. The brief approver is the editorial owner of the content program. Single approver, not a committee. The approver is also the editor on the back end, so the same person is responsible for both the contract and the review. Splitting these roles is how briefs and reviews drift apart. + +Archival. After publish, the brief is archived alongside the content piece (Notion database row, dbt model, content management system metadata, whatever the team's source of truth is). Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, a content audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +Detail in [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses and fixes in [`references/common-brief-failures.md`](references/common-brief-failures.md). + +- "The brief was too thin." Fill all 12 fields or accept generic output. +- "The brief was too thick." Every field needs a job; remove the rest. +- "The writer ignored the brief." Anchor success criteria to the brief; review against the brief. +- "The brief had the wrong target keyword." SERP-validate before briefing. +- "The piece does not match the SERP intent." SERP intent override applies; do not write an article when the SERP wants a listicle. +- "The piece has no internal links." Internal linking belongs in the brief, not as an afterthought. +- "The piece is generic; could have been written about anything." Entity coverage and POV missing from brief. +- "The brief is comprehensive but the piece does not rank." Brief was right; SERP was harder than expected; iterate based on real performance, not by adding fields to the brief. +- "We never went back to evaluate." Success criteria measured 30 / 60 / 90 days post-publish. +- "Different writers produce wildly different output from the same brief." Brief was actually too vague; tighten anti-patterns and voice notes. + +--- + +## The framework: 12 considerations for brief authoring + +When authoring or auditing a content brief, walk these 12 considerations. + +1. Target keyword + cluster. Primary plus 3 to 5 supporting. +2. Search intent + dominant SERP format. Match the SERP, not your priors. +3. Target audience + JTBD. Specific role and problem, not "anyone interested in X." +4. Word count calibrated to SERP. Not to a content quota. +5. Heading structure. Explicit H2s and H3s, ordered to match reader mental model. +6. Entity coverage. Entities the SERP top 10 mention; gap entities added explicitly. +7. Internal linking. 3 to 5 outbound links specified; 1 to 3 inbound updates queued. +8. External proof points. Citations and sources required. +9. Anti-patterns. What not to do, including AI clichés and off-brand voice. +10. Success criteria. Measurable, time-bound, tied to original program goals. +11. Brief versioning + approval. Single approver; version bumps for material changes. +12. Brief stays under 2 pages. Every field earns its keep; remove fields that do not. + +The output of the framework is a brief document the writer can absorb in 5 minutes and execute against in the next 5 hours. + +--- + +## Reference files + +- [`references/brief-templates.md`](references/brief-templates.md) - Pillar, supporting, comparison, listicle, how-to, and thought-leadership brief templates with field-weight notes per type. +- [`references/search-intent-classification.md`](references/search-intent-classification.md) - Four-intent framework, SERP format check, override patterns. +- [`references/heading-structure-patterns.md`](references/heading-structure-patterns.md) - H2 and H3 patterns, featured snippet bait, anti-patterns. +- [`references/entity-coverage-checklist.md`](references/entity-coverage-checklist.md) - Entity discovery from SERP, gap analysis, AEO/GEO citation drivers. +- [`references/internal-linking-strategy.md`](references/internal-linking-strategy.md) - Outbound and inbound linking patterns, orphan prevention, self-cannibalization check. +- [`references/writer-handoff-protocols.md`](references/writer-handoff-protocols.md) - Human-writer handoff, AI-agent handoff, success-criteria anchoring. +- [`references/brief-governance-patterns.md`](references/brief-governance-patterns.md) - Versioning, approval, archival, audit trail. +- [`references/common-brief-failures.md`](references/common-brief-failures.md) - Ten-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: the brief is the contract + +A content brief is the contract between editorial leader and writer. If the contract is vague, the output is vague. If the contract is overstuffed, the output reflects only the parts the writer read. The discipline is writing contracts the writer can absorb in 5 minutes and execute against in the next 5 hours; that is the entire job. + +Most briefs that are not working are thin, not thick. The instinct to add more pages usually makes the brief worse. The instinct to be more specific in fewer fields usually makes the brief better. + +When in doubt about whether a brief is ready, ask: are all 12 fields populated, do they each earn their keep, is the SERP intent matched, are the entities listed, are the internal links specified, is the success criteria measurable, and is the document under 2 pages? If yes to all of those, ship the brief and let the writer work. diff --git a/skills/content-brief-authoring/references/brief-governance-patterns.md b/skills/content-brief-authoring/references/brief-governance-patterns.md new file mode 100644 index 0000000..725b669 --- /dev/null +++ b/skills/content-brief-authoring/references/brief-governance-patterns.md @@ -0,0 +1,104 @@ +# Brief governance patterns + +Versioning, single-approver, archival alongside the published piece, audit trail. + +--- + +## Versioning + +Every brief has a version. Significant changes bump the version; cosmetic edits do not. + +Version-bump triggers: +- Target keyword change (the piece is now optimizing for a different keyword) +- Audience shift (the JTBD has changed) +- Scope expansion or contraction (word count target moves by 50%+; new H2s added or removed) +- Success criteria change (the metric the piece is being measured against shifts) + +No version bump for: +- Typo fixes +- Anchor text adjustments on internal links +- Adding a sentence of clarification to an existing field +- Reformatting + +The writer always works from the current version. If a writer is mid-draft when the brief bumps from v2 to v3, the strategist tells the writer immediately and decides whether to restart, integrate the changes, or freeze the v2 draft. + +The brief has a version field at the top: `brief_version: 3`. The version is the contract identifier. + +--- + +## Single approver + +The brief approver is the editorial owner of the content program. Single approver, not a committee. + +Why single approver: +- A committee bog dilutes the brief. Each member adds a field; nobody removes fields. The brief grows from 1 page to 4 pages and stops being readable. +- A committee splits accountability. When the published piece misses, no single person owns the brief that produced it. +- A single approver enforces taste. The program has a consistent editorial voice because one person is gatekeeping. + +The approver is also the editor. The same person who approves the brief reviews the draft. This prevents the gap between "what the brief asked for" and "what the editor wants"; the same person owns both sides. + +Splitting these roles is how briefs and reviews drift apart. The strategist who briefed the piece sees the gap; an external editor reads the draft and changes the lede because of personal taste, not because of the brief. + +The exception: for high-stakes pieces (pillar content, thought leadership with named author, comparison pieces involving competitors), a second reader is useful. The second reader provides input but does not approve. The single approver still decides. + +--- + +## Archival + +After publish, the brief is archived alongside the content piece. + +Common archival patterns: +- Notion database row. Brief and published-piece URL on the same row. Custom fields for brief version, approver, publish date, success-criteria results. +- dbt model with content metadata. For warehouse-native content tracking; brief stored as JSON in the model's seed data. +- CMS metadata fields. Contentful, Sanity, and similar CMSs allow custom metadata fields; the brief lives in a "brief" field on the content entry. +- Git repo. For docs sites and developer-facing content programs; brief in a sibling markdown file to the published piece. + +Why archival matters. Future content audits reference both brief and published piece to assess gap between intent and execution. Without the brief in the archive, an audit cannot tell whether the piece succeeded against the original goal or drifted from it. + +The audit question is "did we ship what we briefed, and did the briefed piece achieve its success criteria?" Both halves need source-of-truth records: the brief for what was asked, the published piece for what was delivered, the metrics for what the piece achieved. + +--- + +## Audit trail + +A content program that runs at scale needs an audit trail. The audit trail answers four questions per piece: + +1. What did we brief? The archived brief, with version history. +2. What did we publish? The published URL, with publish date and last-update date. +3. How did the piece perform against the success criteria? Rank position at 30 / 60 / 90 days; AI citation count if measured (Profound, Frase, AirOps); conversion data from the analytics stack. +4. What did we learn? A short post-publish note: what worked, what did not, what to brief differently next time. + +The audit trail compounds. After 50 pieces, the program can see patterns: pillar pieces with comprehensive outlines outperform pieces with thin outlines; comparison pieces with explicit "when X wins" / "when Y wins" framing outperform pieces with implicit positioning; entity-coverage scores above 80 correlate with citation count. + +The audit trail is what turns content production from a per-piece activity into a learning system. Without the trail, every piece is a one-off; with the trail, the program improves quarter over quarter. + +--- + +## The "post-mortem on a failed piece" pattern + +When a piece misses its success criteria, the post-mortem walks the brief. + +1. Read the brief. Was it complete? Were the 12 fields populated? +2. Read the published piece. Did it follow the brief? +3. Identify the gap. Was the brief wrong (target keyword too competitive, intent misclassified)? Was the execution off (writer drifted from outline, entities missed)? Was the SERP harder than expected (well-executed brief, well-written piece, still no rank)? +4. Update the brief template if the failure is systemic (next time, run a deeper SERP check before briefing). +5. Update the writer-handoff if the failure is communication (next time, the brief is read aloud at handoff). +6. Accept the failure if the failure is variance (some pieces miss; the program does not chase every miss). + +The post-mortem is short, half a page. It feeds the audit trail and informs the next brief. It does not turn into a multi-page analysis that nobody reads. + +--- + +## Brief field: governance metadata + +The brief carries governance metadata at the top: + +> Brief metadata +> - Brief version: 3 +> - Approver: editorial-lead@team.com +> - Approval date: 2026-04-22 +> - Writer assigned: J. Smith (or AI agent: Frase v4) +> - Target publish date: 2026-05-15 +> - Archive location: Notion content-pipeline database, row #847 + +The metadata is six lines, not a paragraph. It identifies the contract; the rest of the brief is the contract terms. diff --git a/skills/content-brief-authoring/references/brief-templates.md b/skills/content-brief-authoring/references/brief-templates.md new file mode 100644 index 0000000..5f9c94a --- /dev/null +++ b/skills/content-brief-authoring/references/brief-templates.md @@ -0,0 +1,87 @@ +# Brief templates by content type + +Six templates. The 12 fields are constant; the weight of each field shifts based on the content type. Each template names the fields that lean heavier and the fields that lean lighter for that type. + +--- + +## Pillar piece + +Comprehensive coverage of a topic, 3,000+ words, anchors a topic cluster. The piece other content links up to. + +Heavier fields: heading structure (the outline is the spine), entity coverage (a pillar that misses entities loses credibility), internal linking (links to and from the supporting cluster pieces), word count (calibrated to top SERPs, often long). + +Lighter fields: anti-patterns (the writer assigned to a pillar usually knows the topic), tone reference (default brand voice; tone shifts are rare for pillars). + +Brief shape: 2 pages. The H2 outline takes ~40% of the brief because pillar structure is decisive. Entity list is long (15 to 25 entities). Internal-link section names every cluster piece that should link in or out. + +Worked example. Target keyword: "experimentation analytics dashboards." Cluster: experimentation methodology. Intent: commercial-investigation. SERP format: long-form articles plus comparison tables. Word count target: 2,800 to 3,400. Outline: H2 #1 "what an experimentation dashboard does," H2 #2 "platform-native vs warehouse-native," H2 #3 "the metrics that earn their keep," H2 #4 "build vs buy," H2 #5 "common dashboards that ship trusted results." Entities: lift, p-value, MDE, CUPED, sequential testing, Statsig, PostHog, Optimizely, dbt, Mixpanel, Snowflake. Internal links: 5 supporting pieces queued. + +--- + +## Supporting / cluster piece + +Narrower topic, 1,000 to 2,000 words, links up to the pillar. One question, one answer. + +Heavier fields: target keyword (specific long-tail), search intent (cluster pieces have to match SERP precisely), JTBD (one specific reader problem), internal linking (must link up to pillar with anchor text matching the pillar's target). + +Lighter fields: entity coverage (smaller scope, fewer entities required), thought-leadership POV (cluster pieces serve the cluster, not the writer's opinion). + +Brief shape: 1 page. JTBD in one sentence. H2 outline is 3 to 5 sections. Entity list is short (5 to 10). The "links up to pillar" specification is mandatory; an orphan cluster piece is a wasted slot. + +Worked example. Target keyword: "CUPED variance reduction." Pillar: experimentation analytics dashboards. Intent: informational. JTBD: data analyst wants to apply CUPED in a dbt model and needs the formula plus the gotchas. Outline: H2 "what CUPED does," H2 "the formula," H2 "implementing in dbt," H2 "common pitfalls." Internal link up to pillar with anchor "experimentation analytics dashboards." + +--- + +## Comparison piece (X vs Y) + +Commercial intent, structured comparison, decision framework. The reader wants help choosing. + +Heavier fields: anti-patterns (snark and trash-talk are the failure mode), heading structure (table-style comparison plus "when X wins" / "when Y wins" sections), success criteria (commercial intent piece; the metric is signups or sales-qualified leads, not traffic alone). + +Lighter fields: word count flex (top-ranking comparison pieces vary widely; SERP-calibrate). + +Brief shape: 1 to 2 pages. The comparison criteria are listed in the brief, not invented by the writer. If the brand is one of X or Y, the brief specifies honest positioning: what the brand wins on, what the competitor wins on. The brief explicitly forbids "X is the worst, Y is the best" framing. + +Worked example. Target keyword: "Statsig vs PostHog." Intent: commercial. SERP format: comparison tables plus prose. Comparison criteria: pricing model, MAU thresholds, MCP support, custom-metric depth, frontend visual editor, mobile SDK. "When Statsig wins": teams with strong custom-metric needs, teams that already pay for Snowflake. "When PostHog wins": product analytics-led teams, teams that want session replay alongside experimentation. Anti-pattern explicitly listed: do not write "PostHog is the clear winner" or "Statsig is overpriced." Honest comparison or do not write the piece. + +--- + +## Listicle + +Informational or commercial intent, scannable, ranked or unranked list. "10 best X" or "7 ways to Y." + +Heavier fields: selection criteria (why are these 10 the chosen ones; the writer needs to defend the list), ordering rationale (why is item #1 first; explicit ranking criteria), depth-per-item (how many words per item; even depth is the discipline). + +Lighter fields: narrative arc (listicles have minimal narrative; the list itself is the structure). + +Brief shape: 1 page. The selection criteria are listed in the brief. The order is suggested in the brief, with note that the writer can reorder if the research warrants. Depth-per-item is specified (e.g., 150 words each for 10 items, plus 200-word intro and 150-word conclusion = ~1,850 words). + +Worked example. Target keyword: "best feature flag tools 2026." Intent: commercial. Selection criteria: official MCP support, free tier exists, hosting model. The 10 items pre-listed in the brief: LaunchDarkly, Statsig, PostHog, GrowthBook, Optimizely, VWO FME, Split.io, Kameleoon, Flagsmith, Unleash. Depth: 150 words per tool covering pricing, MCP status, when this tool wins. + +--- + +## How-to guide + +Informational intent, step-by-step, screenshots, prerequisites, troubleshooting. The reader wants to do something specific. + +Heavier fields: step granularity (each step is one action, not three), prerequisites (what the reader needs before starting), troubleshooting section (common failure modes the reader will hit). + +Lighter fields: thought-leadership POV (how-to guides serve the task, not the writer's perspective on it). + +Brief shape: 1 to 2 pages. The brief lists the steps in outline form so the writer can spot missing prerequisites or merged steps before drafting. The screenshot list is queued (which screens, in what state). Troubleshooting bullets are listed; the writer expands each into a paragraph. + +Worked example. Target keyword: "how to set up a Statsig experiment." Prerequisites: Statsig account, SDK installed, exposure events instrumented. Steps: H2 "create the experiment in the console," H2 "define the assignment unit," H2 "configure the metrics," H2 "set the duration and MDE," H2 "launch and monitor." Troubleshooting: SRM check failure, exposure events not firing, metric definition mismatch. + +--- + +## Thought leadership / opinion + +Commercial or branding intent, distinctive POV, signal of expertise. The piece exists to differentiate the brand voice in the category. + +Heavier fields: thesis (one sentence; the whole piece defends it), anticipated counter-arguments (what would a smart skeptic say; the piece must address them), tone reference (often a sharper voice than default; the brief specifies the shift). + +Lighter fields: SERP entity coverage (thought leadership often deliberately diverges from SERP consensus; entity coverage is a softer requirement). + +Brief shape: 1 page. The thesis is one sentence at the top. The supporting arguments are listed (3 to 5). The anticipated counter-arguments are listed with notes on how the piece responds to each. The brief explicitly names the writer or contributor; thought leadership has authorship, not anonymous editorial. + +Worked example. Thesis: "warehouse-native experimentation is the right default for any team running 50+ experiments per quarter." Supporting arguments: cost crossover at scale, custom metric flexibility, audit trail, data-team integration. Counter-arguments to address: setup cost, time-to-first-experiment, missing UI tooling. Tone shift: sharper, more declarative than default brand voice. Author: named senior data leader. diff --git a/skills/content-brief-authoring/references/common-brief-failures.md b/skills/content-brief-authoring/references/common-brief-failures.md new file mode 100644 index 0000000..b9c2cf9 --- /dev/null +++ b/skills/content-brief-authoring/references/common-brief-failures.md @@ -0,0 +1,123 @@ +# Common brief failures + +Ten-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "The brief was too thin" + +Symptom. Brief contains target keyword, word count, deadline, maybe a one-line angle. Writer fills in everything else from priors. Output is generic, drifts off-topic, does not rank. + +Diagnosis. The strategist treated the brief as a task assignment instead of a contract. The 12 fields were not populated; the writer's defaults filled the gaps; the defaults were not aligned with the program's intent. + +Fix. Populate all 12 fields. If a field cannot be populated (the success criteria is genuinely unknown, the SERP is too volatile to call), name the gap explicitly and flag it as "writer's call, defend the choice in the first draft." + +--- + +## "The brief was too thick" + +Symptom. Brief is 4 pages with executive summary, brand-voice refresher, comprehensive competitive landscape, plus the actual brief. Writer skims for the outline. Output is not better than from a thin brief. + +Diagnosis. Strategist optimized for brief authorship instead of brief consumption. Each field added felt important; nobody asked "would the writer behave differently if this field were missing?" + +Fix. Cut fields that do not change writer behavior. Brand-voice refresher: link, do not repeat. Competitive landscape: link to research, do not summarize. Executive summary: the brief is the executive summary. Target: 1 to 2 pages. + +--- + +## "The writer ignored the brief" + +Symptom. The published piece misses the SERP intent, drops required entities, ignores internal-link guidance. Editor's review surfaces the gap. + +Diagnosis. No success-criteria acknowledgment at handoff. The writer read the brief once at the start, drafted from memory plus priors, never re-read. + +Fix. Require acknowledgment at handoff (see `writer-handoff-protocols.md`). The acknowledgment restates the success criteria in the writer's voice. Saying it is what keeps it load-bearing. + +--- + +## "The brief had the wrong target keyword" + +Symptom. The piece publishes; the target keyword turns out to have search volume of 50/month, or to be navigational (a brand wins position 1 forever), or to have a SERP the team cannot win. The piece does not rank. + +Diagnosis. SERP not validated before briefing. The strategist assumed the keyword was good without pulling the SERP and the volume. + +Fix. SERP-validate before briefing. Pull the keyword volume (Ahrefs, Semrush, GSC). Pull the SERP top 10. If the SERP looks unwinnable for the brand at current authority, pick a different keyword. + +--- + +## "The piece does not match the SERP intent" + +Symptom. SERP shows mostly listicles; the briefed piece is a long-form article. Or SERP shows long-form articles; the briefed piece is a listicle. Either way, the piece does not rank. + +Diagnosis. SERP intent override was not applied. The strategist's priors about what the keyword "should" look like overrode what the SERP actually shows. + +Fix. Apply the SERP override pattern (see `search-intent-classification.md`). The format choice line in the brief must match the dominant SERP format. + +--- + +## "The piece has no internal links" + +Symptom. Piece publishes with zero internal links to other pages on the site. Or with one or two links that the writer added arbitrarily. + +Diagnosis. Internal linking was treated as an afterthought. The brief did not specify outbound links; the writer added some at the end without strategic intent. + +Fix. Specify 3 to 5 outbound links in the brief, with anchor text and target page. Queue 1 to 3 inbound updates as post-publish tasks (see `internal-linking-strategy.md`). + +--- + +## "The piece is generic; could have been written about anything" + +Symptom. Reading the piece, you cannot tell what brand it came from, what makes it different from the SERP top 10, or why this piece exists. The piece reads as AI-generated even when a human wrote it. + +Diagnosis. Entity coverage and POV were missing from the brief. The writer hit the target keyword but did not differentiate; the piece blends into SERP consensus. + +Fix. Specify gap entities (entities mentioned by 1 to 2 SERP pages but not by the rest). Specify a POV for the piece: what the brand argues that the rest of SERP does not. Generic content has no POV; effective content makes a specific claim. + +--- + +## "The brief is comprehensive but the piece does not rank" + +Symptom. Brief had all 12 fields. Writer followed the brief. Piece is well-written, hits the entities, follows the outline. Three months post-publish: position 47. + +Diagnosis. The SERP was harder than expected. The brief was right; the keyword was over-competitive at the brand's current authority. This is variance, not failure. + +Fix. Do not iterate by adding fields to the brief. Iterate by SERP-validating more carefully next time, by accepting that some keywords are out of reach until the brand earns more authority, or by pivoting to a less-competitive long-tail variant. + +--- + +## "We never went back to evaluate" + +Symptom. Pieces publish; nobody checks performance at 30 / 60 / 90 days. The program runs without feedback. + +Diagnosis. Success criteria were defined in the brief but no measurement task was queued at publish time. + +Fix. Make 30 / 60 / 90 day check-ins part of the publish checklist. The check-in is a 5-minute task: read the rank, the citation count, the conversion data; update the audit trail (see `brief-governance-patterns.md`). Not optional. + +--- + +## "Different writers produce wildly different output from the same brief" + +Symptom. Two writers given the same brief produce pieces that read like they came from two different programs. The brief was supposedly identical; the output is not. + +Diagnosis. The brief was actually too vague. Different writers filled gaps with their own priors; the gaps were where the divergence lives. + +Fix. Tighten the anti-patterns and the voice notes. The brief explicitly forbids common writer drifts (off-topic tangents, off-brand tone, AI clichés). The voice reference is specific (not "use brand voice" but "use the voice of section 3 of the voice guide; default tone, no sharper"). + +--- + +## "The piece succeeded but we cannot tell why" + +Symptom. A piece outperforms expectations: top-3 rank, high citation count, conversion above target. The team cannot explain what made it work. + +Diagnosis. The brief and the published piece have multiple distinguishing features (specific outline, gap entities, sharp POV); without controlled comparison, the team cannot isolate the cause. + +Fix. Document hypotheses about why the piece worked in the post-publish note. Test the hypotheses by briefing the next 3 pieces with the same pattern. If the pattern replicates, it is the cause; if not, the success was variance. The audit trail compounds (see `brief-governance-patterns.md`); patterns emerge over 20+ pieces. + +--- + +## "We approved the brief but the writer wrote a different piece" + +Symptom. The brief was for a comparison piece; the writer delivered a thought-leadership piece. The brief was for 1,800 words; the writer delivered 3,400 words. The brief was for a senior data engineer audience; the writer wrote for a non-technical CMO. + +Diagnosis. The handoff acknowledgment was skipped. The writer read the brief, drafted from a different mental model, and did not surface the divergence early. + +Fix. Require acknowledgment that restates the brief's parameters: word count, audience, format. If the writer's acknowledgment misstates anything, the strategist catches it before drafting starts. After 1,500 words of writing, restarting is expensive; before drafting, restating is cheap. diff --git a/skills/content-brief-authoring/references/entity-coverage-checklist.md b/skills/content-brief-authoring/references/entity-coverage-checklist.md new file mode 100644 index 0000000..54ada43 --- /dev/null +++ b/skills/content-brief-authoring/references/entity-coverage-checklist.md @@ -0,0 +1,91 @@ +# Entity coverage checklist + +Entity discovery from SERP, gap analysis, AEO and GEO citation drivers. + +--- + +## Why entity coverage matters + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to cite content that: + +- Mentions the entities the SERP top-ranking pages mention +- Includes specific statistics with sources +- Contains citation-formatted proof points +- Demonstrates topical depth via entity coverage + +Entities are the named things the topic depends on: tools, methods, experts, datasets, statistics, brands, frameworks, standards, organizations. A piece on "experimentation analytics" that does not mention CUPED, sequential testing, p-values, or named platforms (Statsig, PostHog, Optimizely) reads as thin both to humans and to ranking systems. + +Traditional SEO has known about entity coverage for years (Google's Hummingbird and BERT updates emphasized it). AEO and GEO double the stakes: AI engines explicitly use entity coverage as a citation signal because they can extract the entity graph from the page and assess topical depth at retrieval time. + +--- + +## The entity discovery workflow + +Run before authoring the brief; do not delegate to the writer. + +Step 1. Pull the SERP top 10 for the target keyword. + +Step 2. For each top-10 page, extract the named entities. Tools that automate this: Frase (built-in entity gap analysis), AirOps (workflow builder runs the same analysis), Surfer SEO (entity coverage scoring), or manual extraction with a structured prompt. + +Step 3. Tag each entity by frequency: +- Mentioned by 7+ of 10 pages: required coverage. The brief lists these. +- Mentioned by 3 to 6 pages: standard coverage. The brief lists these with shorter notes. +- Mentioned by 1 to 2 pages: gap entities. The brief includes these as differentiation opportunities. +- Mentioned by 0 pages but relevant: brand-owned entities the team knows matter even if SERP misses them. + +Step 4. For each required and standard entity, write a one-line note in the brief explaining why it matters and where to mention it. Example: + +> CUPED. Variance-reduction technique mentioned by 9 of 10 SERP pages. Mention in the methodology H2 with the formula. Required. + +Step 5. Add the gap entities (1 to 2 page mentions) as differentiation opportunities. The writer can choose to include them; they add depth without crowding the required entities. + +--- + +## AEO and GEO citation drivers + +Beyond entity coverage, AI engines weight several other signals when deciding what to cite. + +Specific statistics with sources. "Statsig charges per MAU starting at 100K MAU" cites better than "Statsig is expensive at scale." Numbers with sources are higher-citation; vague qualifiers are lower-citation. + +Named experts or quotes. "As Ronny Kohavi noted in his book Trustworthy Online Controlled Experiments, the most common SRM diagnosis is..." cites better than "experts agree that SRM diagnoses are common." Named attribution earns citation; anonymous attribution does not. + +Direct definitions. "CUPED stands for Controlled-experiment Using Pre-Existing Data" cites better than a passage that uses CUPED without defining it. AI engines extract definitions and use them as the canonical answer when users ask "what is CUPED." + +Comparison tables. Tables with explicit columns and rows cite better than prose comparisons. AI engines extract structured data preferentially. + +Specific tool names with version numbers. "dbt Cloud (v1.7+)" cites better than "dbt." Specificity is the citation signal. + +--- + +## Brief field: how to populate entity coverage + +The brief lists the required entities, the standard entities, and the gap entities, with one-line notes per entity. + +> Required entities (mention all) +> +> - CUPED: variance-reduction technique (9/10 SERP pages). Mention in methodology H2 with formula. +> - Sequential testing: confidence-adjustment for peeking (8/10). Mention in pitfalls H2. +> - MDE (minimum detectable effect): power-calculation input (10/10). Mention in setup H2. +> - Statsig, PostHog, Optimizely: named platforms (10/10 mention at least one). Brief should mention all three with one-sentence positioning. +> +> Standard entities (mention if relevant) +> +> - A/A test: sanity check (5/10). Mention in pitfalls H2. +> - Bonferroni correction: multiple-testing adjustment (4/10). Mention in pitfalls H2. +> +> Gap entities (differentiation opportunity) +> +> - CUPAC: successor to CUPED (1/10). Mention in methodology H2 as the next-generation technique. Differentiates the piece from SERP consensus. +> - Bayesian inference: alternative to frequentist hypothesis testing (1/10; mentioned occasionally in advanced experimentation content). Mention in advanced section if word budget allows. + +The "Bayesian inference" entity is the example: it is a specific technical concept that some advanced experimentation content covers, where most SERP top-10 pieces stop at frequentist hypothesis testing. Adding the gap entity differentiates the piece without crowding the required-coverage list. + +--- + +## The entity-coverage failure mode + +The most common failure: the writer mentions all the required entities once each, in passing, without weight. The piece passes the entity-coverage check on a string-match basis but does not actually demonstrate topical depth. + +The fix in the brief: specify weight per entity. "Mention CUPED in passing in H2 #2; develop CUPED with formula and example in H2 #4." The brief is not just a list of entities to include; it is a placement plan. + +The writer's draft references the brief's entity placement plan. The editor reviews against placement, not just against presence. diff --git a/skills/content-brief-authoring/references/heading-structure-patterns.md b/skills/content-brief-authoring/references/heading-structure-patterns.md new file mode 100644 index 0000000..e89841b --- /dev/null +++ b/skills/content-brief-authoring/references/heading-structure-patterns.md @@ -0,0 +1,102 @@ +# Heading structure patterns + +H2 patterns, H3 sub-section patterns, featured-snippet bait, and the anti-patterns the brief should explicitly forbid. + +--- + +## H2 patterns that work + +Question-style H2s. "What is CUPED?" "How does CUPED reduce variance?" "When should I use CUPED?" These match how readers think and how Google's "People Also Ask" box surfaces queries. They are also the easiest format for AI engines to extract as citation candidates. + +Declarative H2s. "CUPED reduces variance by adjusting for pre-experiment covariates." "The formula uses a regression coefficient computed before assignment." Declarative H2s work for pieces that have a strong thesis or that summarize before they explain. + +Comparison H2s. "Platform-native: faster, narrower, opinionated." "Warehouse-native: slower, broader, custom-metric capable." Symmetrical H2s pair to set up a comparison; the reader sees the structure on the table of contents alone. + +Imperative H2s. "Configure the assignment unit." "Define the metrics." "Set the duration and MDE." Common for how-to guides; each H2 is one action. + +The discipline: pick one pattern and use it consistently within a piece. Mixing question + declarative + imperative reads as inconsistent and signals AI generation when the mixing is random. + +--- + +## H3 patterns under H2s + +H3s should add navigational value, not just structure for its own sake. + +When to add H3s: +- The H2 covers a topic with 3 to 5 sub-topics that the reader might want to jump to +- The H2 section is long enough (700+ words) that scanning needs sub-anchors +- The piece has a table of contents that benefits from sub-entries + +When not to add H3s: +- The H2 is short (under 400 words) +- The H3s would be a cosmetic enumeration that does not add navigation +- The piece is short overall (under 1,200 words); H3s are usually unnecessary + +No orphan H3s. Every H2 either has zero H3s or 2+ H3s. A single H3 under an H2 reads as a typo or an aborted edit. + +No H2-H3-H4 cascades. If a section needs H4s, the structure is wrong. Either the H2 is too broad and should split into two H2s, or the H4 is decoration that should be a paragraph. + +--- + +## The featured snippet bait pattern + +Place a 40 to 60 word answer paragraph immediately following the H2 question. Google often pulls this paragraph as the featured snippet; AI engines often quote it as the citation. + +Example. + +> ## What is CUPED? +> +> CUPED (Controlled-experiment Using Pre-Existing Data) is a variance-reduction technique that adjusts experimental measurements using pre-treatment covariates. The covariate's regression coefficient against the outcome is computed before assignment, then used to subtract baseline variance from the experiment's measurement, increasing statistical power without changing the experiment's design. + +The paragraph is self-contained: read alone, it answers the H2 question completely. The rest of the section expands on the answer with examples, formulas, edge cases. + +The discipline: the snippet paragraph is the most important paragraph in the section. Write it first; expand the section around it. + +--- + +## H2 ordering + +H2s should match the reader's mental model, not the writer's enthusiasm. + +The standard order for informational pieces: +1. What is it (definition, plain language) +2. Why does it matter (why the reader cares) +3. How does it work (mechanism, technical depth) +4. When to use it (decision criteria) +5. Common pitfalls (what goes wrong) +6. Wrap-up or call-to-action + +The buried-lede anti-pattern. H2 #4 has the actual answer the reader came for. The reader bounced at H2 #2. + +The fix. Put the obvious answer first. The writer's clever angle goes in H2 #4 or H2 #5, not H2 #1. + +--- + +## Anti-patterns the brief should forbid explicitly + +Repetitive H2 structure. All H2s start with "How to" or all start with "The." Repetitive structure signals AI generation to AEO/GEO crawlers and to readers. Vary the patterns within a piece, but keep one dominant pattern. + +Buried lede. The actual answer is in H2 #4. The brief specifies which H2 carries the keystone answer; usually H2 #1 or H2 #2. + +Section length unevenness. H2 #1 is 1,500 words; H2 #2 is 80 words. The 80-word section reads as a placeholder. Briefs should specify approximate word counts per H2 to enforce balance. + +H3-only enumeration. A section that is just an H2 plus a list of H3s with one paragraph each. Either the H2 should hold all the content, or the H3s deserve more depth. The half-and-half shape is a sign of incomplete thinking. + +Misnumbered H2s in numbered series. "5 ways to Y" with 6 H2s, or with 4. The mismatch reads as careless. + +--- + +## Brief field: how to populate the heading structure + +The brief lists the H2s in order with one-line notes. H3s only when they earn their keep. + +> Heading structure outline +> +> - H2 #1: "What is X?" (snippet paragraph mandatory; ~250 words section) +> - H2 #2: "Why X matters" (~300 words; one specific reader scenario) +> - H2 #3: "How X works" (~600 words; H3s: "the formula," "the assumption," "the implementation"; show the math) +> - H2 #4: "When to use X" (~400 words; decision-criteria list) +> - H2 #5: "Common pitfalls" (~400 words; 3 to 5 specific pitfalls with diagnoses) +> - H2 #6: "Wrap-up" (~150 words; call-to-action to related cluster piece) + +The writer follows the outline; deviations are flagged in the first draft for editor review. diff --git a/skills/content-brief-authoring/references/internal-linking-strategy.md b/skills/content-brief-authoring/references/internal-linking-strategy.md new file mode 100644 index 0000000..85918ae --- /dev/null +++ b/skills/content-brief-authoring/references/internal-linking-strategy.md @@ -0,0 +1,97 @@ +# Internal linking strategy + +Outbound and inbound linking patterns, orphan-content prevention, self-cannibalization check. + +--- + +## Two link directions to specify + +Every brief specifies links in two directions. + +Outbound from this piece. 3 to 5 pages this piece should link to. Anchor text and target page named explicitly. The writer is not deciding internal links during drafting; the strategist already knows the cluster and which pieces should reinforce each other. + +Inbound to this piece, post-publish. 1 to 3 existing pages that should add a link to this piece after it publishes. This is a follow-up task queued in the brief, not a request to the writer. + +--- + +## Outbound link selection + +The cluster pieces. The brief lists the supporting cluster pieces this piece should link to, with anchor text that matches each target's primary keyword. + +Example for a pillar piece on "experimentation analytics dashboards": + +> Outbound links (writer integrates) +> +> 1. Link to "CUPED variance reduction" (cluster piece) using anchor "CUPED" or "variance reduction with CUPED" in the methodology H2. +> 2. Link to "warehouse-native experimentation" (sister pillar) using anchor "warehouse-native experimentation" in the platform-vs-warehouse comparison H2. +> 3. Link to "feature flag tools comparison" (commercial-intent piece) using anchor "feature flag tools" in the deployment H2. +> 4. Link to "data warehouse setup" (foundation piece) using anchor "data warehouse" in the prerequisites H2. + +The discipline: anchor text matches the target's primary keyword. Generic anchors ("click here," "this article") do not pass ranking signals; keyword anchors do. + +--- + +## Inbound link queue + +The brief queues 1 to 3 existing pages that should add a link to the new piece after it publishes. The strategist updates these as part of the publish checklist. + +Example continuing the same pillar: + +> Inbound link updates (post-publish task) +> +> 1. Update "feature flagging" pillar to link to the new piece in the "measuring feature impact" section using anchor "experimentation analytics dashboards." +> 2. Update "PostHog vs Statsig" comparison to link to the new piece in the analytics-comparison H2. +> 3. Update homepage "Resources" section to add the new piece to the "Pillars" list. + +The inbound queue prevents the orphan-content failure mode. + +--- + +## The orphan-content failure mode + +Symptom: piece publishes, no other piece links to it, search engines deprioritize it, AI engines do not see it as cluster-anchored. + +Cause: internal linking was an afterthought, handled by the writer or by SEO at publish time without strategic intent. The writer linked out to 3 pages because the brief said to; nobody linked back in because nobody owned that task. + +Fix: the brief queues the inbound updates explicitly. The publish checklist includes the inbound updates as a tracked task. Without a tracked task, the inbound updates do not happen; without inbound links, the piece is an orphan. + +The "5-link rule" diagnostic. Every published piece should have at least 5 internal links pointing to it within 30 days of publish. If a piece has fewer than 5 inbound links at the 30-day check, audit the inbound queue and add the missing links. + +--- + +## The self-cannibalization check + +Before briefing a new piece, check whether it would compete with an existing piece for the same keyword cluster. + +The check. Search the site for the target keyword. If an existing piece is in the top 5 of internal search results, flag it. + +Three options when self-cannibalization is detected: + +1. Consolidate. Merge the planned piece into the existing piece. Update the existing piece with the new angle, the new entities, the new examples. Keep one URL ranking; do not split ranking authority across two URLs. +2. Differentiate. Sharpen the angle of the new piece so it does not compete. The existing piece covers "what is feature flagging"; the new piece covers "feature flag rollout strategies for enterprise teams." Different intent, different audience, different SERP target. +3. Kill one. Determine which piece serves the cluster better. Redirect the loser to the winner. This is rare and usually signals the program does not have clear pillar structure. + +The discipline: flag self-cannibalization in the brief, not after the piece is written. Late detection is the expensive failure mode; the writer has already invested hours that now have to be either rewritten or thrown away. + +--- + +## Brief field: how to populate internal linking + +> Internal linking +> +> Outbound (3 specified, 2 optional) +> - Required: link to "CUPED variance reduction" with anchor "CUPED" in methodology H2 +> - Required: link to "warehouse-native experimentation" with anchor "warehouse-native" in comparison H2 +> - Required: link to "feature flag tools 2026" with anchor "feature flag tools" in deployment H2 +> - Optional: link to "data warehouse setup" with anchor "data warehouse" in prerequisites H2 (writer's call based on flow) +> - Optional: link to "experiment-design skill" with anchor "experiment design" in introduction (writer's call) +> +> Inbound (post-publish, queued) +> - Update "feature flagging" pillar (insert link in section 4) +> - Update "PostHog vs Statsig" comparison (insert link in analytics-comparison H2) +> +> Self-cannibalization check +> - Existing pieces on adjacent keywords: "experiment dashboards introduction" (different angle, no conflict) +> - No conflict; proceed with brief + +The brief is explicit about what is required, what is optional (writer chooses), and what is queued for post-publish. Three layers of discipline. diff --git a/skills/content-brief-authoring/references/search-intent-classification.md b/skills/content-brief-authoring/references/search-intent-classification.md new file mode 100644 index 0000000..eeaf7ce --- /dev/null +++ b/skills/content-brief-authoring/references/search-intent-classification.md @@ -0,0 +1,68 @@ +# Search intent classification + +Four-intent framework, dominant SERP format check, override patterns when intent and format mismatch. + +--- + +## The four standard intents + +Informational. The reader wants to learn. Queries: "what is CUPED," "how does feature flagging work," "experimentation analytics explained." SERP usually shows articles, guides, explainers, sometimes videos. Conversion is downstream (the reader signs up for the newsletter or returns to the site weeks later); ranking is the immediate goal. + +Navigational. The reader wants a specific brand, product, or page. Queries: "Statsig pricing," "LaunchDarkly login," "PostHog docs." SERP usually shows the brand site at #1 and a sitelinks block. Ranking against navigational intent is mostly impossible unless you are the brand. The exception: the reader-bypass pattern where adjacent brands rank for "competitor X login" by writing comparison content; play this carefully because it can read as bait. + +Commercial. The reader is researching a purchase. Queries: "best feature flag tools," "Statsig vs LaunchDarkly," "Optimizely review." SERP usually shows comparisons, reviews, "best X" listicles, sometimes detailed guides. The reader is in active evaluation; this is the highest-conversion intent for B2B SaaS content. + +Transactional. The reader is ready to buy. Queries: "Statsig signup," "buy LaunchDarkly," "PostHog free trial." SERP usually shows product pages, pricing pages, signup flows. Editorial content does not rank here; brand-owned commercial pages do. + +--- + +## The dominant SERP format check + +After classifying intent, scan the SERP top 10 and tag the dominant format. + +- Article. Long-form prose, single-author voice. Common for informational intent. +- Listicle. "10 best X," "7 ways to Y." Common for commercial-investigation intent. +- Comparison. Side-by-side X vs Y, table-heavy, decision frameworks. Common for high-funnel commercial intent. +- Video. YouTube embeds dominate the top of SERP. Common for how-to and tutorial queries. +- Tool. Calculator, generator, interactive tool. Common for "X calculator" or "X generator" queries. +- Hybrid. SERP shows a mix; usually tells you the keyword is contested or the intent is split. + +The dominant format tells you the shape of the piece, which is more decisive than the intent label. An informational keyword whose SERP is mostly listicles wants a listicle, not a long-form article. + +--- + +## The override pattern + +When intent and format mismatch, the format wins. + +Case 1. The intent feels informational ("how to design an A/B test") but the SERP shows mostly listicles ("7 steps to designing an A/B test"). Write the listicle. The SERP is the source of truth, not your priors about what the intent "should" look like. + +Case 2. The intent feels commercial ("best feature flag tools") but the SERP shows mostly long-form articles that mention many tools without ranking them. Write the long-form article. Listicle format would feel out of place against the SERP. + +Case 3. The SERP is genuinely split: half listicles, half long-form articles. Either format can rank. Pick based on the brand's voice and the piece's role in the cluster. + +The reason. Rankings come from matching the SERP's accepted shape; deviating costs ranking. Google's ranking algorithm is partly trained on what users click and stay on, which is selected from existing top-ranking content. Existing top-ranking content sets the shape; new content has to match the shape to compete. + +--- + +## The AEO and GEO consideration + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) tend to favor pieces that match SERP intent format because the intent classification was trained on the SERP corpus. + +A piece that mismatches the SERP format faces two problems: it is harder to rank in traditional search, and it is less likely to be cited by AI engines. The mismatch is a double cost. + +The exception: thought leadership that deliberately diverges. A piece arguing "the listicle format is misleading for this category; here is why" can rank by drawing traffic on the controversy and earning citations on the contrarian thesis. This is rare and risky; do not default to it. + +--- + +## Brief field: how to populate intent + format + +The brief field reads like this: + +> Search intent + SERP format +> Intent: commercial-investigation +> Dominant SERP format: long-form article + comparison table hybrid (top 5 are articles with embedded comparison tables; positions 6 to 10 are pure listicles) +> Format choice for this piece: long-form article with one comparison table at the midpoint +> SERP intent override: none (format choice matches dominant) + +The "format choice" line is decisive. The writer reads this line first and shapes the piece around it. diff --git a/skills/content-brief-authoring/references/writer-handoff-protocols.md b/skills/content-brief-authoring/references/writer-handoff-protocols.md new file mode 100644 index 0000000..ca3be09 --- /dev/null +++ b/skills/content-brief-authoring/references/writer-handoff-protocols.md @@ -0,0 +1,101 @@ +# Writer handoff protocols + +Human-writer handoff, AI-agent handoff, success-criteria anchoring. + +--- + +## The handoff has the same shape regardless of writer + +Whether the writer is a human freelancer, a staff editor, an internal SME, or an AI agent (Claude, ChatGPT, a Frase brief-runner, an AirOps workflow), the brief-to-writer handoff has the same five-step shape. + +1. Brief delivered with all 12 fields populated. +2. Writer asks clarifying questions before drafting (or the agent surfaces ambiguities as the first response). +3. Writer or agent acknowledges the success criteria explicitly. +4. First draft references the brief: which fields the draft addresses, which fields it could not address, why. +5. Editor reviews against the brief, not against personal taste. + +The shape is the same; the medium differs. Human writers acknowledge in Slack or email; AI agents acknowledge in the first message of the agent thread. Both cases: the acknowledgment is required, not optional. + +--- + +## Human-writer handoff + +Step 1: brief delivery. The brief is delivered as a single document (Notion page, Google Doc, dbt-style markdown file in the repo). The writer can read it in 5 minutes; if reading takes longer, the brief is too thick and should be cut. + +Step 2: clarifying questions. Before drafting, the writer asks clarifying questions. Common ones: + +- Is the target audience right? Is the JTBD specific enough to write to? +- Is the SERP intent classification right? Do I write a listicle or an article? +- Are these entities really required, or are some optional? +- Is the success criteria measurable from my side, or is it a downstream-only metric? + +The strategist answers questions in the same document; clarifications are versioned with the brief, not pasted into Slack and lost. + +Step 3: acknowledgment. The writer acknowledges in writing: "I have read the brief. I am writing to the success criteria of [X]. I will hit all required entities. I am clear on the SERP format choice." Acknowledgment is a 3-line message, not a treatise. + +Step 4: first draft with reference. The first draft is delivered with a reference note: "Hit 4 of 5 required entities; the 5th (CUPAC) was not in the SERP coverage I could find sources for, so I substituted the standard CUPED treatment per the brief's gap-entity guidance." The reference note tells the editor what to focus on in review. + +Step 5: editor review against brief. The editor reads the brief first, the draft second. The review framing is "the brief said X; the draft did Y; gap is Z." Personal taste comes after brief review, not before. + +--- + +## AI-agent handoff + +The shape is the same; the medium is structured. + +Step 1: brief delivery as structured input. The brief becomes a YAML or JSON object the agent ingests. Frase, AirOps, and similar tools structure briefs in their own schema; the same 12 fields appear regardless. Example minimal YAML structure: + +```yaml +target_keyword: experimentation analytics dashboards +supporting_cluster: + - CUPED variance reduction + - sequential testing + - feature flag rollout +search_intent: commercial-investigation +serp_format: long-form-article-with-comparison-table +target_audience: senior data engineer at 500-person SaaS +jtbd: choose between platform-native and warehouse-native experimentation +word_count_target: 2800 +heading_outline: + - { level: 2, text: "What an experimentation dashboard does" } + - { level: 2, text: "Platform-native vs warehouse-native" } + - { level: 2, text: "Metrics that earn their keep" } + - { level: 2, text: "Build vs buy" } + - { level: 2, text: "Common dashboards that ship trusted results" } +required_entities: + - { name: "CUPED", note: "mention with formula in methodology H2" } + - { name: "Statsig, PostHog, Optimizely", note: "mention all three" } +internal_links: + outbound: + - { target: /skills/cuped, anchor: "CUPED" } + - { target: /skills/warehouse-native, anchor: "warehouse-native experimentation" } + inbound_queued: + - { source: /pillars/feature-flagging, anchor: "experimentation analytics dashboards" } +anti_patterns: + - "do not use the team's do-not-use word list (see brand voice guide)" + - "do not write a listicle; SERP wants long-form" +success_criteria: + - "rank top 10 for target keyword in 90 days" + - "cited by ChatGPT for 'experimentation dashboard' queries within 60 days" +voice_reference: /brand/voice-guide +brief_version: 2 +brief_approver: editorial-lead@team.com +``` + +Step 2: ambiguity surfacing. The agent's first response surfaces ambiguities. "The brief lists CUPED as required, but the SERP top 10 only mention CUPED in 6 of 10 results; should I emphasize it or treat it as standard coverage?" The strategist answers; the brief gets versioned with the answer. + +Step 3: acknowledgment. The agent acknowledges in structured output: "Reading brief version 2. Target: 2,800 words. Format: long-form with comparison table. Will hit 4 required entities; need clarification on CUPED weight." Single message, machine-readable. + +Step 4: first draft with reference. The agent's draft is delivered with a structured note: which fields the draft addressed, which entities are present and where, what success criteria the draft is targeting. + +Step 5: editor review. The editor reviews the agent's draft using the same brief-first framing. Tools like Frase highlight which entities are present in the draft; the editor scans the highlights to confirm coverage. + +--- + +## Success-criteria anchoring + +The most-skipped handoff step is success-criteria acknowledgment. The writer or agent reads the brief, drafts the piece, delivers it; the success criteria sit in the brief unread. + +The fix: every handoff acknowledgment includes the success criteria verbatim. "I am writing to the success criteria: rank top 10 for 'experimentation analytics dashboards' in 90 days; get cited by ChatGPT for the topic within 60 days; drive 50 trial signups in the first 30 days." + +The acknowledgment is the contract restated in the writer's voice. Saying it out loud is what keeps it load-bearing during drafting. diff --git a/skills/content-distribution/SKILL.md b/skills/content-distribution/SKILL.md new file mode 100644 index 0000000..eeb09a6 --- /dev/null +++ b/skills/content-distribution/SKILL.md @@ -0,0 +1,307 @@ +--- +name: content-distribution +description: "Content distribution as a discipline. Owned channels (newsletter, blog, social), earned channels (PR, syndication, mentions), paid channels (boosted posts, syndication networks), and the channel-fit decisions that distinguish strategic distribution from spam-everywhere. Audience-channel matching, content-channel matching, distribution cadence. Triggers on content distribution, channel strategy for content, owned earned paid channels, content amplification, content promotion, audience-channel matching, content-channel matching, distribution cadence, syndication strategy, organic distribution. Also triggers when content is publishing but reach is low, when the team is distributing on every channel without strategy, or when the content program needs a distribution discipline rather than just publication." +category: content +catalog_summary: "Content distribution discipline: owned, earned, and paid channels matched to audience and content type. Channel-fit decisions, distribution cadence, the strategic alternative to spam-everywhere or hope-and-pray" +display_order: 12 +--- + +# Content Distribution + +A senior editorial leader's playbook for content distribution as a discipline. Owned, earned, and paid channels matched to audience and content type, with the channel-fit decisions that distinguish strategic distribution from spam-everywhere or hope-and-pray. + +Content distribution is half the work and gets a fraction of the attention. Most programs spend 90% of capacity on production and 10% on distribution; the resulting ratio of effort-to-reach is consistently poor. The teams producing content that reaches audiences are the ones who treat distribution as a real discipline: channels chosen for fit, cadence calibrated to audience attention, owned-earned-paid balance set by program strategy, and effectiveness measured per channel. + +This skill is the channel discipline. Different from `content-repurposing` (which turns one piece into many formats), this skill is about getting content TO audiences via the right channels. The two skills compose: repurpose first, then distribute the right format on the right channel. + +The voice is the senior editorial leader who has watched programs underperform because distribution was treated as posting-after-publishing rather than as the equal half of the work. + +When to use this skill: building a distribution discipline for a content program, auditing why content publishes consistently but reach is low, calibrating owned-earned-paid balance, designing channel-fit decisions for a multi-format program. + +--- + +## What this skill is for + +This skill spans channel selection, audience-channel matching, content-channel matching, and distribution cadence. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes pieces. +- `editorial-qa` verifies before publish. +- `content-repurposing` turns one piece into many formats (transformation). +- `content-distribution` (this skill) gets content TO audiences via channels (channel work). + +The distinction from `content-repurposing` is load-bearing. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. Distribution is channel work: getting content to audiences via the right channels. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content programs that need reach, agencies running distribution for clients. + +What is not in scope: paid acquisition for purposes other than content amplification (covered by `paid-media-strategy`), the specific email channel discipline (covered by `email-sequences`), the AI-search optimization layer that sits across distribution channels (covered partially by `seo-aeo-geo`). + +--- + +## Hope-and-pray vs spam-everywhere vs channel-fit + +The keystone framing. + +Hope-and-pray. Publish and assume readers will find it. The piece goes live; the team links it on the blog homepage; maybe shares it once on social; assumes search and word of mouth will carry it. Output: most pieces reach a fraction of their potential audience because no deliberate distribution work was done. The program produces good content that nobody encounters. + +Spam-everywhere. Blast every piece on every channel regardless of fit. Every piece on LinkedIn, Twitter/X, Facebook, Threads, Mastodon, Bluesky, plus 5 emails to the full list, plus paid promotion on every platform. Audience tunes out; channels deprioritize the program; trust degrades. AI tooling has made spam-everywhere cheap and increasingly common, which makes the audience reaction sharper. + +Channel-fit. Distribute through channels matched to audience and content type. Specific channels chosen for specific pieces. Cadence calibrated to each channel's audience attention rhythm. Owned-earned-paid balance set by program strategy. Output: each distribution choice produces engagement from audiences who actually want the content; the program's distribution capacity is concentrated where it produces value. + +The litmus test. Ask of any distribution decision: which audience is this piece for, where does that audience consume content, does the piece's format fit that channel's conventions, and at what cadence does the channel reward presence? If the answers are specific, the distribution is channel-fit. If the answers are "everyone, everywhere, every channel, all the time," the distribution is spam-everywhere. + +--- + +## Channel taxonomy + +Three categories with sub-types within each. + +Owned channels. Channels the program owns and controls. + +- Newsletter and email. Direct relationship with subscribers. High control over reach (every subscriber receives the email); lower scale than social. +- Blog and content site. Owned property where pieces live. Search and direct traffic; the canonical version of pieces. +- Social channels owned by the program. LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account. Owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. +- Communities and forums owned by the program. Slack communities, Discord servers, dedicated discussion forums. Direct relationship with members. + +Earned channels. Channels where content reaches audiences via third-party amplification, not paid placement. + +- PR and press coverage. Journalists, podcasters, newsletter operators who cover the program's content because it is newsworthy or insightful. +- Syndication. Other publications republishing or excerpting the program's content (with appropriate attribution and canonical signaling). +- Mentions and citations. Other content marketing programs, industry analysts, AI search engines citing the program's content. +- Word of mouth and shares. Audiences sharing pieces with their networks; the program's content becoming part of conversations. + +Paid channels. Channels where paid spending amplifies content. + +- Boosted social posts. Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. +- Promoted newsletter sends. Sponsored placements in third-party newsletters. +- Syndication networks. Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. +- Search advertising for content. Paying for clicks on content pieces (less common; usually content is the organic side and paid is the conversion side). +- Sponsored podcast or content placements. Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Detail in [`references/channel-taxonomy.md`](references/channel-taxonomy.md). + +--- + +## Audience-channel matching + +Where the target audience actually consumes content. The distribution decision starts here. + +The audit. + +- Identify the audience for the program (or for the specific piece). +- Map where that audience spends time in their professional or consumer life. +- Identify the channels in that audience map where the audience is genuinely engaged (not just present). +- Match content distribution to those channels. + +Common audience-channel maps. + +- B2B technical audiences. LinkedIn high engagement; X moderate engagement (specific communities); industry newsletters; specific industry forums; podcasts in their domain. +- B2B executive audiences. LinkedIn high engagement; specific executive newsletters and podcasts; conferences and analyst-influence channels. +- Consumer mass audiences. Instagram, TikTok, YouTube, Facebook depending on demographic; broad email if subscribed. +- Niche specialist audiences. Specific subreddits, Discord servers, specialized newsletters, niche podcasts. Often higher engagement on smaller channels than on broad social. +- Developer audiences. GitHub, Hacker News, specific subreddits, dev-focused podcasts and newsletters, Twitter/X for parts of the community. + +The mismatch failure. Distributing on channels where the audience is present but not engaged produces low reach and low engagement. A B2B technical program publishing TikToks may technically reach audiences on TikTok but engage few of them; the audience is on TikTok for entertainment, not for technical learning. + +Detail in [`references/audience-channel-matching.md`](references/audience-channel-matching.md). + +--- + +## Content-channel matching + +Which formats fit which channels. Beyond audience match, the format must fit the channel's conventions. + +Format-channel fit examples. + +- Long-form analytical text fits blog, newsletter, LinkedIn long posts, X threads (for the right communities). Does not fit TikTok, Instagram Reels, or short-form video platforms. +- Short-form video fits TikTok, Reels, Shorts, increasingly LinkedIn video. Does not fit newsletter (where text leads) or owned blog (where written long-form leads). +- Statistic-driven content fits social with quote-graphics, AI search snippets, podcast mentions. Does not fit (as primary format) newsletter where context develops the stat. +- Conversational expert content fits podcasts, video interviews, possibly long social threads. Does not fit short-form video or single-post-format social. + +The mismatch failure. Distributing a format on a channel where the format does not fit produces low engagement. A 5,000-word whitepaper on TikTok (even repurposed) may not fit the format expectations of TikTok audiences regardless of audience overlap. + +The compose-with-repurposing pattern. When the audience is on a channel but the format does not fit, the right answer is often to repurpose into a format that does fit (see `content-repurposing`), then distribute. The composition is "repurpose for fit, distribute on channel." + +Detail in [`references/content-channel-matching.md`](references/content-channel-matching.md). + +--- + +## Distribution cadence + +How often, what mix, sustaining vs campaign rhythm. + +Cadence axes. + +- Frequency per channel. How often the program posts to each channel. +- Mix. What proportion of distribution is owned vs earned vs paid; what proportion is original vs derivative. +- Rhythm. Sustaining baseline cadence vs campaign spikes around flagship launches. + +Common cadence patterns. + +- B2B program with content-led demand generation. Newsletter weekly. Blog 2-4 posts per week. LinkedIn 3-5 posts per week. X 5-10 posts per week. Quarterly campaign spikes for flagship launches. +- Consumer brand with broad-audience reach goals. Daily Instagram content. Weekly newsletter. TikTok 2-4 posts per week. Owned blog 1-2 posts per week. Continuous paid amplification. +- Niche specialist program with concentrated audience. Newsletter weekly or bi-weekly. Owned blog 1-2 posts per month. Social on specific platforms 2-3 posts per week. Earned channels prioritized over paid. + +Sustaining vs campaign. + +- Sustaining cadence. The baseline rhythm. Audiences expect this cadence; deviation (long pauses or sudden spikes) affects engagement. +- Campaign rhythm. Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +The cadence audit. Programs that publish in fits and starts (3 posts in one week, then nothing for 3 weeks) underperform programs with steady cadence. Audience attention rewards predictability. + +Detail in [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md). + +--- + +## Owned-channel discipline + +Owned channels are the program's most reliable distribution. The discipline keeps them effective. + +Newsletter. Direct subscriber relationship; near-100% delivery to inboxes (modulo spam filtering). Cadence consistency matters: weekly is the most common cadence for B2B; bi-weekly works for higher-investment formats. Each send earns the next; sloppy sends lose subscribers. + +Blog. Canonical home for long-form content. SEO compounds over time; internal linking earns authority. The blog is where pieces persist; social and email send audiences to the blog. + +Social channels owned by the program. LinkedIn, X, Instagram, etc. Reach is platform-controlled (not the program's), but the program controls what publishes and when. Algorithmic favor varies; content that the platform's algorithm rewards gets reach beyond the follower base. + +Podcast. Owned distribution is the show feed; subscribers receive new episodes. Episodes also live on the blog with show notes; the show notes are an SEO asset. + +Communities. Slack, Discord, forums where the program facilitates discussion. The community is the audience the program is most directly engaged with; distribution to the community is the most reliable engagement signal. + +The owned-channel anti-pattern: starvation. Programs that under-invest in owned channels become dependent on third-party distribution. When platforms change algorithms, when paid costs rise, when earned channels go quiet, the program's reach collapses. Owned-channel investment is the durable foundation. + +Detail in [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md). + +--- + +## Earned-channel work + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real. + +PR and press. Pitching journalists, podcasters, newsletter operators on the program's content. Effective when the content is genuinely newsworthy or insightful; ineffective when pitches feel like blast emails. + +Syndication. Negotiating with other publications to republish or excerpt the program's content with appropriate attribution and canonical signaling. The syndication earns reach; the canonical link preserves SEO value. + +Mentions and citations. Earning mentions in other programs' content. Often happens when the program's pieces are genuinely useful as references; pieces that are generic or surface-level rarely get cited. + +AI search citation. Earning citations from AI search engines. Increasingly important as AI search grows; pieces designed for citation (see `content-repurposing`'s AEO extraction patterns) get cited at higher rates. + +Word of mouth and shares. Audiences sharing pieces with their networks. The hardest to earn deliberately; pieces that are genuinely valuable get shared. + +The earned-channel investment. Earned channels require relationship-building, pitch quality, and content quality. Programs that try to "do PR" with mass-blast pitches earn nothing; programs that invest in genuine relationships earn ongoing channel access. + +Detail in [`references/earned-channel-work.md`](references/earned-channel-work.md). + +--- + +## Paid promotion of organic content + +When boosting organic content earns its keep. + +The pattern. A piece publishes organically; some pieces show strong engagement signals; the program boosts those pieces with paid spend to extend reach. The paid spend is on content that the audience has already validated. + +When boosting fits. + +- The piece has demonstrated organic engagement (high CTR, high time-on-page, organic shares). +- The audience addressable through paid amplification overlaps with the program's target audience. +- The piece's value is clear enough that paid amplification produces engagement, not just impressions. + +When boosting fails. + +- Boosting low-engagement pieces because the calendar said so. Paid spend on content the audience does not engage with produces wasted budget. +- Boosting pieces that drive volume but not value. Pieces that produce clicks but not engagement may be drawing the wrong audience; paid amplification compounds the wrong-audience problem. +- Treating paid content amplification as a substitute for organic distribution. Paid amplifies what organic validated; paid alone produces transactional reach without the audience relationship organic builds. + +The mix. Most strong programs allocate 0-20% of distribution capacity to paid content amplification. Programs heavily dependent on paid promotion are usually programs that have not yet built owned and earned distribution. + +Detail in [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md). + +--- + +## Distribution measurement + +Which channels actually drive value. The discipline that prevents distribution-theater. + +Per-channel metrics. + +- Reach. How many people the channel surfaces the content to. +- Engagement. Click-through, time-on-page, scroll depth, completion rate (varies by format). +- Conversion. Newsletter signups, content downloads, qualified-lead actions, sales-cycle progression. +- Attribution. Which channels drove the audience members who eventually converted. + +Channel-level analysis. + +- Which channels produce the highest engagement-per-distribution-effort? Some channels look impressive (high reach) but produce low engagement. +- Which channels produce the highest conversion? Reach without conversion is vanity; conversion is value. +- Which channels' performance is changing over time? Algorithm shifts, audience migrations, and competitive landscape changes affect channel effectiveness. + +Cross-channel attribution. The same audience member encounters the program on multiple channels before converting. Single-touch attribution misrepresents which channels matter; multi-touch attribution is more accurate but harder to implement. + +The measurement-honest program. Cuts channels that consistently underperform. Increases investment in channels that consistently produce. Adjusts cadence based on engagement patterns, not on arbitrary publishing schedules. + +Detail in [`references/distribution-measurement.md`](references/distribution-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-distribution-failures.md`](references/common-distribution-failures.md). + +- "We publish but reach is low." Hope-and-pray pattern; no deliberate distribution work happening. +- "We post on every channel and engagement is flat." Spam-everywhere pattern; distribution capacity diluted across channels where the audience is not engaged. +- "Newsletter open rates are dropping." Cadence may be wrong, or list quality declining, or content not earning the open. Investigate. +- "Our LinkedIn engagement keeps falling." Possible algorithm shift; possible content-channel mismatch; possible cadence issue. +- "Our PR pitches are getting ignored." Mass-blast pitching; relationships not built; pitches not specific to recipient. +- "We invest heavily in paid but engagement is low." Paid amplifying low-organic-engagement content; paid as substitute for owned development. +- "We do not know which channels are working." Measurement absent; program operating on channel-presence rather than channel-effectiveness. +- "Content publishes but audiences do not see it." Distribution treated as posting; cadence wrong; channels mismatched to audience. +- "We launched campaign distribution but it landed quietly." Campaign rhythm not earned by sustaining cadence; audiences not primed to attention-spike. +- "Our owned audience is small." Long-term investment in owned channels skipped; program dependent on third-party distribution. +- "Earned channels are not producing." Treating earned as automatic; relationships not built; pitches not earning. +- "Paid distribution costs are rising." Auction dynamics on paid platforms; programs heavily dependent on paid see costs rise without offsetting owned/earned investment. + +--- + +## The framework: 12 considerations for content distribution + +When designing or auditing a distribution program, walk these 12 considerations. + +1. Channel-fit, not hope-and-pray or spam-everywhere. Specific channels for specific audiences and formats. +2. Channel taxonomy understood. Owned, earned, paid; sub-types within each; which channels the program actually uses. +3. Audience-channel matching. Where the target audience actually engages, not just where they are present. +4. Content-channel matching. Format fits the channel's conventions and audience expectations. +5. Distribution cadence calibrated. Per-channel frequency, owned-earned-paid mix, sustaining-vs-campaign rhythm. +6. Owned-channel discipline. Newsletter, blog, social channels owned by the program, possibly podcast and community. Long-term investment. +7. Earned-channel work. PR, syndication, mentions, AI-search citation. Relationship investment. +8. Paid promotion of organic content. Boost pieces that have organic engagement; do not substitute paid for owned. +9. Cross-channel attribution. How audiences encounter the program across channels before converting. +10. Per-channel measurement. Reach, engagement, conversion. Channels that underperform get cut. +11. Sustaining-vs-campaign rhythm. Baseline cadence plus campaign spikes for flagship launches. +12. Distribution capacity allocation. Real budget; not done in the cracks. + +The output of the framework is a distribution program where each channel choice is deliberate, each cadence decision matches audience attention, each measurement informs the next decision, and the program's reach grows because the work is concentrated where it produces value. + +--- + +## Reference files + +- [`references/channel-taxonomy.md`](references/channel-taxonomy.md) - Owned, earned, paid with sub-types. Newsletter, blog, social, communities, PR, syndication, mentions, boosted social, syndication networks, sponsored placements. +- [`references/audience-channel-matching.md`](references/audience-channel-matching.md) - Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction. +- [`references/content-channel-matching.md`](references/content-channel-matching.md) - Format-channel fit. The compose-with-repurposing pattern. The format-mismatch failure mode. +- [`references/distribution-cadence-patterns.md`](references/distribution-cadence-patterns.md) - Frequency, mix, rhythm. Sustaining vs campaign. Common cadence patterns by program type. +- [`references/owned-channel-discipline.md`](references/owned-channel-discipline.md) - Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. +- [`references/earned-channel-work.md`](references/earned-channel-work.md) - PR, syndication, mentions, AI-search citation, word of mouth. Relationship investment. +- [`references/paid-promotion-patterns.md`](references/paid-promotion-patterns.md) - Boosting organic content. When paid amplification fits and when it fails. The paid-as-substitute anti-pattern. +- [`references/distribution-measurement.md`](references/distribution-measurement.md) - Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. +- [`references/common-distribution-failures.md`](references/common-distribution-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: distribution is half the work + +Most content programs are production-heavy and distribution-light. The teams producing flagship pieces typically spend 90% of capacity producing and 10% distributing; the resulting reach matches the inverse ratio. Pieces that took 60 hours to produce reach a fraction of their potential audience because the 6 hours allocated to distribution were not enough to do the channel work. + +The discipline is not "distribute more"; it is "distribute deliberately." Channel-fit decisions concentrate distribution work where it produces value. Owned-channel investment builds durable foundations. Earned-channel relationships accumulate over years. Paid promotion amplifies what organic validated. Measurement informs what to keep and what to cut. + +When in doubt about whether a distribution program is ready, ask: are channels chosen for fit, is audience-channel matching deliberate, do formats fit channels, is cadence calibrated, is owned-channel investment in place, are earned-channel relationships being built, is paid amplification on organically-validated pieces, is measurement informing the next decisions? If yes to all of those, the program is real. If no to any, the gap is where reach will fall short of what the production work earned. diff --git a/skills/content-distribution/references/audience-channel-matching.md b/skills/content-distribution/references/audience-channel-matching.md new file mode 100644 index 0000000..c1d5753 --- /dev/null +++ b/skills/content-distribution/references/audience-channel-matching.md @@ -0,0 +1,172 @@ +# Audience-channel matching + +Where audiences actually engage. Common audience-channel maps. The presence-vs-engagement distinction that prevents distributing on channels where the audience is technically present but not actually paying attention. + +The first and most consequential distribution decision is which channels to invest in. Most programs over-invest in channels with high audience presence but low audience engagement, and under-invest in smaller channels where the audience is genuinely paying attention. The audit shifts capacity to where engagement happens. + +--- + +## The presence-vs-engagement distinction + +A channel where the audience is present is not necessarily a channel where the audience is engaging. + +Presence. Members of the target audience have accounts on the platform. They could see the program's content if they encountered it. + +Engagement. Members of the target audience are actively using the platform for the kind of content the program produces. They click; they comment; they share; they convert. + +The mismatch failure mode. A B2B technical program publishing TikTok content. The audience may have TikTok accounts (presence), but the audience is on TikTok for entertainment, not for B2B technical learning (low engagement for the program's content). The presence creates a false signal that the channel might work; the engagement reality is that distribution capacity goes to a low-return channel. + +The audit question. Not "is the audience on this channel?" but "is the audience consuming this kind of content on this channel?" + +--- + +## Common audience-channel maps + +Mappings that show up repeatedly across program types. Programs should still validate against their own audience research; the maps below are starting points. + +### B2B technical audiences + +Engineers, technical decision-makers, developer-influencers, technical product managers. + +High engagement. LinkedIn (especially long-form posts and articles); X/Twitter (specific technical communities); industry-specific newsletters; specialized podcasts; specific subreddits and Discord servers; GitHub for code-adjacent content; technical conferences and analyst-influenced channels. + +Moderate engagement. YouTube for tutorial and conference-talk content; Hacker News for specific topics; vendor-platform community sites (AWS, Azure, GCP forums; specific tool communities). + +Low engagement. TikTok, Instagram, Facebook for the program's primary content. Some technical professionals consume these for entertainment but rarely for technical content. + +### B2B executive audiences + +C-suite, VPs, senior strategy leaders. + +High engagement. LinkedIn (long-form posts, articles, sometimes video); specific executive newsletters and podcasts; analyst-influence channels (Gartner, Forrester); event-driven media (high-quality conferences, executive roundtables). + +Moderate engagement. Industry-specific publications; some podcasts; X/Twitter for specific topics with executive commentary. + +Low engagement. Most consumer-focused social platforms. Executives often have low time for content consumption; the channels where they engage are concentrated. + +### Consumer mass audiences + +Broad consumer demographics for B2C brands. + +High engagement. Instagram, TikTok, YouTube, Facebook (varies by demographic age and interest). Email newsletter for engaged subscribers. Pinterest for visual-product categories. Specific subreddits for interest-driven topics. + +Moderate engagement. X/Twitter (declining for many consumer demographics). LinkedIn (low for most consumer use cases). + +Low engagement. Most B2B-oriented channels. + +### Niche specialist audiences + +Concentrated audiences within specific domains (cybersecurity professionals, fertility-tracking enthusiasts, specific hobby communities). + +High engagement. Specific subreddits, Discord servers, specialized newsletters and podcasts. Often higher engagement on smaller channels than on broad platforms. + +Moderate engagement. Domain-specific Twitter/X communities; some LinkedIn; YouTube for educational content. + +Low engagement. Broad social platforms where the audience is small fraction of total platform population. + +### Developer audiences + +Software developers across stacks and seniority levels. + +High engagement. GitHub (code-adjacent content); Hacker News (specific topics); specific subreddits; Twitter/X for parts of the dev community; dev-focused podcasts and newsletters; YouTube for tutorial content. + +Moderate engagement. LinkedIn for senior developers; Stack Overflow for Q&A-driven content (different distribution model than programs typically use); Discord servers for specific tools. + +Low engagement. TikTok, Instagram, Facebook, Pinterest for primary content. + +### Founder and startup audiences + +Founders, startup operators, early-stage investors. + +High engagement. Twitter/X (the founder community has historically been engaged here); LinkedIn for some segments; specific newsletters (Lenny's, Substack-based founder newsletters); specific podcasts; YC-adjacent forums. + +Moderate engagement. YouTube for some long-form content; specific subreddits. + +Low engagement. Most mass-consumer platforms. + +--- + +## The audience-channel audit + +A short framework for matching audience to channels. + +1. Define the target audience specifically. Not "marketers" but "B2B SaaS marketing leaders at companies with 50-500 employees, primarily in North America and Western Europe." Specificity unlocks the matching. +2. Map where this audience spends time professionally. Where do they get news, learn new ideas, hear from peers, encounter products? +3. Map where this audience spends time consuming the kind of content the program produces. Different from professional time generally; specific to the content type. +4. Identify channels where the audience engages. Not just where they have accounts. Engagement signals: comments, shares, conversion behaviors. +5. Score channels by engagement potential. High, moderate, low. The high-engagement channels get primary distribution capacity. + +--- + +## Audience-research methods for the audit + +How to actually identify where audiences engage. + +Customer interviews. Ask existing customers where they consume content related to the program's topic. The answers are the audience's revealed-preference distribution map. + +Audience surveys. Quantitative confirmation of channel-engagement patterns. Surveys can over-represent platforms respondents feel they should use; the customer interviews ground-truth the survey data. + +Existing program data. Where does the program's existing audience come from? Referral data, UTM analysis, conversion attribution. Channels that produce existing audience are channels where the audience is engaging with the program. + +Competitive analysis. Where do competing programs distribute? Where do they appear to earn engagement (visible signals: comments, shares, mentions)? Competitive distribution patterns inform but should not dictate the program's choices. + +Industry research. Some industry research firms publish channel-engagement data by audience segment. Useful as starting points; should be triangulated with the program's own data. + +--- + +## The audience-channel mismatch failure mode + +The pattern when audience-channel matching is skipped. + +The symptom. The program publishes consistently on multiple channels. Engagement is flat or declining. Distribution capacity is spread thin. The team cannot identify which channels are working because none of them are working clearly. + +The diagnosis. Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +The cure. Run the audience-channel audit. Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. The total distribution capacity stays the same; the allocation shifts. + +Recovery time. Cutting underperforming channels and concentrating capacity on engaging channels typically produces visible engagement improvements within 4-8 weeks. + +--- + +## When audience-channel maps shift + +Audiences move across channels over time. Maps that fit a program 3 years ago may not fit now. + +Common shifts. + +- Twitter/X engagement has declined for many B2B audiences as the platform has changed; LinkedIn has absorbed some of the shifted attention. +- TikTok has expanded into demographics it did not initially serve. +- Newsletter consumption has grown across most audience types as inbox-based content consumption has become more accepted. +- AI-search citation has emerged as a distribution channel that did not exist meaningfully before 2024. + +The audit cadence. Run the audience-channel audit at least annually. Maps that have not been refreshed for 18+ months are likely outdated. + +--- + +## The audience-channel-content-type triangle + +Audience-channel matching is one of three matching decisions; content-channel matching is another (see `content-channel-matching.md`); the third is content-audience matching (the source piece is for the right audience in the first place). + +The triangle. + +- Audience matches channel. +- Content matches channel. +- Content matches audience. + +The failure modes. + +- Audience-channel mismatch: distribution where the audience is not engaged. +- Content-channel mismatch: format does not fit the channel's conventions. +- Content-audience mismatch: the piece is not actually for the channel's audience even if both fit individually. + +The triangle is what produces channel-fit distribution. All three matchings need to hold for distribution to produce engagement. + +--- + +## Methodology-level choices that stay in the public skill + +The presence-vs-engagement distinction, the common audience-channel maps, the audience-channel audit, audience-research methods, the mismatch failure mode, the map-shift recognition, the audience-channel-content-type triangle. + +## Implementation choices that stay internal + +Specific audience-research surveys and interview templates. Specific UTM tracking and attribution conventions. Specific competitive analysis tooling. Specific channel-engagement scoring rubrics. The team's own audience-segment definitions. These vary by team, audience, and tooling. diff --git a/skills/content-distribution/references/channel-taxonomy.md b/skills/content-distribution/references/channel-taxonomy.md new file mode 100644 index 0000000..c826a25 --- /dev/null +++ b/skills/content-distribution/references/channel-taxonomy.md @@ -0,0 +1,215 @@ +# Channel taxonomy + +Owned, earned, paid with sub-types. The full taxonomy that grounds channel-fit decisions. + +Programs that distribute well think in terms of the taxonomy. Programs that distribute poorly think in terms of "social media" or "content marketing" without distinguishing the categories. The distinction matters because owned, earned, and paid channels have different cost structures, different reach characteristics, and different roles in a program's distribution mix. + +--- + +## Owned channels + +Channels the program owns and controls. + +### Newsletter and email + +The most direct owned distribution. + +Characteristics. Direct relationship with subscribers. The program controls what sends, when, and to whom. Near-100% delivery to inboxes (modulo spam filtering and engagement-based deliverability adjustments). + +Strengths. No platform algorithm between the program and the audience. Engagement is cleanly measured. Audience commitment signal is strong (people who subscribe and stay subscribed are valuable signal). + +Weaknesses. Slow to grow vs broad-reach social channels. Each subscriber is real work to acquire and retain. + +The newsletter discipline. Cadence consistency, content quality matching subscriber expectations, single-CTA-per-send, deliverability hygiene. See `email-sequences` for the email-specific discipline. + +### Blog and content site + +The program's content home. + +Characteristics. Owned property where pieces live as canonical versions. Search traffic compounds over years. Internal linking earns authority. Direct traffic from audiences who know the property. + +Strengths. Compounding asset. Content that earns search position keeps producing traffic indefinitely. Full design and presentation control. + +Weaknesses. Slow to start producing meaningful traffic. SEO investment is multi-year. Without distribution to the blog, pieces sit unread. + +The blog discipline. Architecture and technical SEO foundations (see `seo-technical`); pillar and cluster organization (see `pillar-content-architecture`); refresh discipline (see `content-refresh-system`); on-page optimization (see `seo-onpage`). + +### Social channels owned by the program + +LinkedIn company page, X account, YouTube channel, podcast feed, Instagram account, etc. + +Characteristics. The program runs the account; the platform controls reach via algorithms. Reach varies by platform algorithm changes, audience size, content engagement signals. + +Strengths. Larger potential audience than newsletter. Algorithmic favor can produce reach beyond follower base when content earns engagement signals. + +Weaknesses. Platform-controlled reach. Algorithm shifts can dramatically reduce reach without warning. Audiences are renting the platform; the program does not own the relationship the way newsletter signals ownership. + +The owned-social discipline. Per-platform conventions; cadence calibrated to platform attention rhythm; content adapted for platform; engagement-signal optimization; account-health hygiene. + +### Podcast + +Owned audio distribution. + +Characteristics. The show feed is owned; subscribers receive new episodes through their podcast app. Episodes also live on the blog with show notes; cross-platform distribution (Spotify, Apple Podcasts, YouTube) extends reach. + +Strengths. Intimate audience relationship. High engagement when audience is loyal. Long-form context for substantive content. Show notes are SEO assets. + +Weaknesses. Production cost is real (audio quality, editing, hosting). Discoverability depends on platform algorithms and word-of-mouth. + +The podcast discipline. See podcast-specific format conventions; show notes as derivative format; consistent episode cadence; cross-platform distribution for reach. + +### Communities + +Slack communities, Discord servers, dedicated discussion forums. + +Characteristics. Direct relationship with members. The program facilitates discussion; members engage with each other and with program content. + +Strengths. Highest-engagement audience the program has. Community feedback informs content and product. Members become advocates. + +Weaknesses. Community management is meaningful work. Communities require continuous facilitation; abandoned communities decay and signal decline. + +The community discipline. Active moderation; sustained value-delivery to members; integration with the broader content program (members get access; program content is shared in community). + +--- + +## Earned channels + +Channels where content reaches audiences via third-party amplification, not paid placement. + +### PR and press coverage + +Journalists, podcasters, newsletter operators who cover the program's content. + +Characteristics. Third parties cover the program's content because it is newsworthy, insightful, or fits their editorial agenda. The program does not pay for coverage; the value exchange is editorial fit. + +Strengths. External authority signal. Reach into audiences the program does not have direct relationships with. Often higher trust signal than program's own distribution. + +Weaknesses. Hard to predict; relationship-dependent; pitches that miss editorial fit produce nothing. + +The PR discipline. Genuine relationship-building with relevant journalists. Pitches specific to recipient and to actual newsworthy content. Quality over quantity; mass-blast pitches earn no coverage and damage future relationship potential. + +### Syndication + +Other publications republishing or excerpting the program's content. + +Characteristics. Programs negotiate with other publications to republish or excerpt their content. Canonical link signaling preserves SEO value. Attribution is mandatory. + +Strengths. Reach into the syndication partner's audience. Some pieces reach more readers via syndication than via owned distribution. + +Weaknesses. Negotiation overhead. Risk of authority dilution if canonical signaling is wrong. Partners may discontinue syndication; the program cannot rely on syndication as primary distribution. + +The syndication discipline. Canonical link tags; clear attribution; partner relationship management; selective syndication (not every piece warrants syndication). + +### Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +Characteristics. External programs reference the program's content as a source. The program's authority signal compounds with each citation. + +Strengths. Compounding authority. Long-term backlink and citation profile that informs SEO and AI-search positioning. + +Weaknesses. Largely outside the program's direct control. The program can produce citation-worthy content (specific data, framework introductions, primary research) but cannot force citation. + +The citation-earning discipline. Produce content with citation hooks: original data, named frameworks, primary research, contrarian-but-defensible positions. Pieces that are generic rarely get cited; pieces that are specifically valuable do. + +### Word of mouth and shares + +Audiences sharing pieces with their networks. + +Characteristics. The program's content becomes part of conversations beyond the program's distribution. Most valuable when sharing happens in private channels (DMs, Slack channels, internal corporate emails) where the program cannot directly track. + +Strengths. Highest-trust distribution. A piece shared by a colleague carries more weight than the same piece in a feed. + +Weaknesses. Hard to measure; hard to engineer deliberately. Pieces that earn word-of-mouth are pieces that are genuinely valuable to the audience. + +The word-of-mouth discipline. Produce content that audiences want to share. Specific, useful, citation-worthy. Avoid generic content that nobody bothers to share even if they read it. + +--- + +## Paid channels + +Channels where paid spending amplifies content. + +### Boosted social posts + +Paying to extend reach of an organic post on LinkedIn, X, Facebook, Instagram. + +Characteristics. The program pays the platform to show the post to additional audiences (often defined by audience targeting parameters). The post still appears as an owned post; the paid spend extends its reach. + +Strengths. Quick to deploy; extends reach of pieces that have demonstrated organic engagement; measurable. + +Weaknesses. Costs accumulate; auction dynamics drive prices up over time; pieces that performed organically may not maintain engagement at scaled paid reach. + +The boost discipline. Boost pieces with strong organic engagement signals; do not boost pieces that did not earn engagement organically; treat boost spend as amplification of validation, not as substitute for organic. + +### Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +Characteristics. The program pays a third-party newsletter to feature its content. The newsletter audience sees the program's content alongside the newsletter's editorial content. + +Strengths. Reach into newsletter audiences with strong attention rhythms. Often higher engagement than broad social paid amplification. + +Weaknesses. Requires negotiation; sponsorship feels different from editorial; price-per-send varies. + +The sponsored-newsletter discipline. Match the newsletter's audience and tone; sponsored content that fits the newsletter feels like value; sponsored content that clashes feels like an ad. + +### Syndication networks + +Outbrain, Taboola, native-content networks that distribute content via paid placement on third-party sites. + +Characteristics. Programs pay per click; content appears on third-party sites in "you may also like" or "recommended for you" placements. + +Strengths. Volume reach at variable cost; geographic and audience targeting. + +Weaknesses. Quality of audience varies; engagement often low; reputation challenges (some networks have brand-safety concerns). + +The syndication-network discipline. Test cautiously; measure beyond clicks (engagement, time-on-page); some networks fit some programs and not others. + +### Search advertising for content + +Paying for clicks on content pieces. + +Characteristics. Less common; usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +Strengths. High-intent audiences; quick reach for high-value content. + +Weaknesses. Cost-per-click on competitive queries; content that converts via paid clicks usually has clear conversion signals. + +The content-search-ads discipline. Reserve for content with clear conversion or lead-capture goals; measure paid traffic against owned-traffic comparison; high-value content only. + +### Sponsored podcast or content placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts or newsletters. + +Characteristics. The program pays to be featured in a third-party podcast or newsletter, often via host-read endorsement. + +Strengths. Host-read endorsements carry strong trust signal. Audiences of niche podcasts and newsletters are highly engaged. + +Weaknesses. Cost varies; production quality matters; mismatched host-program fit damages both. + +The sponsored-placement discipline. Match host audience to program audience; provide hosts with substantive talking points; measure on engagement signals beyond impressions. + +--- + +## Channel mix evolution over program maturity + +Programs at different stages have different channel mixes. + +Early-stage programs. Heavy owned-channel investment (newsletter, blog). Limited earned (relationships not yet built). Limited paid (budget often constrained). The early program is building the foundation. + +Mid-stage programs. Owned channels producing reliable distribution. Earned channels developing (PR relationships, syndication, mentions accumulating). Paid amplification of best organic pieces. + +Mature programs. Owned channels are reliable foundations. Earned channels are significant traffic and authority sources. Paid amplification is strategic, not load-bearing. + +The maturity audit. Programs heavily dependent on paid distribution often have under-invested in owned and earned. The dependency is visible: when paid budgets cut, reach collapses; when paid costs rise (as they do over time on auction-based platforms), program effectiveness degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The owned/earned/paid taxonomy with sub-types, the characteristics and disciplines per sub-type, the channel mix evolution by program maturity, the maturity audit. + +## Implementation choices that stay internal + +Specific platform tooling per channel. Specific community management software. Specific PR-relationship CRMs. Specific paid-platform configurations and bidding strategies. Specific syndication-network vendor selections. The team's own conventions for channel-mix targets at different program stages. These vary by team, budget, and program shape. diff --git a/skills/content-distribution/references/common-distribution-failures.md b/skills/content-distribution/references/common-distribution-failures.md new file mode 100644 index 0000000..92119ff --- /dev/null +++ b/skills/content-distribution/references/common-distribution-failures.md @@ -0,0 +1,193 @@ +# Common distribution failures + +Twelve-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most distribution failures share a single root, which is treating distribution as posting-after-publishing rather than as the equal half of the work. + +--- + +## Failure 1: Hope-and-pray (publish and wait) + +Symptom. The program publishes consistently. Reach is low. The team is unclear why; the content seems strong. + +Diagnosis. No deliberate distribution work. Publishing is treated as the end of the work; audiences are expected to find the content via search, social, and word of mouth without proactive distribution. + +Cure. Apply the channel-fit discipline. Identify which channels the audience engages on; distribute deliberately on those channels with appropriate format adaptation. Treat distribution as half the work. + +Capacity recovery. Programs that shift from hope-and-pray to deliberate distribution typically see 2-5x reach improvements within 8-12 weeks. + +--- + +## Failure 2: Spam-everywhere + +Symptom. The program posts on every channel: LinkedIn, X, Facebook, Threads, Bluesky, Instagram, TikTok, plus 5 emails per week, plus paid promotion on every platform. Engagement is flat across all channels. + +Diagnosis. Distribution capacity diluted across channels where the audience is not engaged. Each channel gets cursory attention; none gets enough to produce real engagement. + +Cure. Apply the audience-channel matching discipline. Cut channels where the audience is present but not engaged. Concentrate capacity on channels that produce engagement. + +Recovery time. Cutting underperforming channels and concentrating capacity typically produces visible engagement improvements within 4-8 weeks. + +--- + +## Failure 3: Newsletter open rates declining + +Symptom. The newsletter open rate has declined from 35% to 22% over 6 months. Subscribers are not opening sends. + +Diagnosis. Multiple possible causes. Cadence may be wrong (too aggressive or too sparse). List quality may be declining (lapsed subscribers depressing engagement signal). Subject lines may not be earning the open. Content may not be matching subscriber expectations. + +Cure. Diagnose first. Pull cohort data: are recent subscribers opening at higher rates than long-term subscribers (suggests content fit decline)? Are sends with specific subject-line patterns performing better (suggests subject line issue)? Is open rate consistent across send-times (rules out timing)? + +Apply the relevant fix: list pruning for lapsed subscribers; subject-line improvement; cadence adjustment; content recalibration. + +--- + +## Failure 4: LinkedIn engagement falling + +Symptom. LinkedIn engagement on the program's posts has declined. Comments, shares, and reach signals all lower than 6 months ago. + +Diagnosis. Multiple possible causes. Algorithm shift; content-channel mismatch; cadence issue; account-health degradation. LinkedIn algorithm changes have affected many programs over the past several years. + +Cure. Audit content quality (does it match what worked previously?). Audit cadence (within platform-rewarded range?). Check account-health signals (engagement on others' content, not just own posts; profile completeness; consistent branding). If algorithm shifts are the cause, content patterns may need recalibration to fit current algorithmic preferences. + +--- + +## Failure 5: PR pitches ignored + +Symptom. The program pitches journalists for coverage. Most pitches get ignored. Coverage is rare. + +Diagnosis. Mass-blast pitching, or relationships not built before pitching, or pitches not specific to recipient. + +Cure. Apply the relationship-first PR principle (see `earned-channel-work.md`). Build relationships with relevant journalists over months before pitching. Pitch specific to recipient with reference to their recent work. Reduce pitch volume; increase pitch quality. + +Timeline. PR relationships build over 1-3 years. Programs in mass-blast mode cannot fix this in a quarter; the cure is multi-year. + +--- + +## Failure 6: Heavy paid investment, low engagement + +Symptom. The program spends significantly on paid amplification. Engagement metrics are low. Cost-per-engagement keeps rising. + +Diagnosis. Paid amplification is amplifying low-organic-engagement content. Or paid is substituting for owned-channel investment. Or both. + +Cure. Apply the boost-organic pattern. Only boost pieces that have demonstrated organic engagement. Reduce paid spend on pieces without organic validation. Reallocate capacity toward owned-channel investment for long-term durability. + +--- + +## Failure 7: No measurement + +Symptom. The team operates on intuition about which channels are working. Different team members have different intuitions. Decisions about cadence, channel mix, and capacity are not informed by data. + +Diagnosis. No measurement infrastructure or no measurement-to-decision discipline. + +Cure. Establish per-channel metrics; channel-level analysis; cross-channel attribution. Quarterly measurement reviews that produce specific decision changes. See `distribution-measurement.md` for the discipline. + +--- + +## Failure 8: Posting without distribution + +Symptom. Content publishes. The piece appears on the blog and is shared once on social. The team considers distribution complete. + +Diagnosis. Distribution is treated as the act of posting. The work of getting content TO audiences is not happening. + +Cure. Plan distribution at production time. Each piece has a distribution plan: which channels, what cadence, what cross-channel co-promotion. Distribution is part of the production work, not an afterthought. + +--- + +## Failure 9: Campaign launches landing quietly + +Symptom. The team prepared a flagship launch with significant cross-format coordination. Launch day arrives. Engagement is muted. + +Diagnosis. Sustaining cadence was insufficient before the launch. Audiences were not warm; the campaign moment did not feel like a campaign moment because no audience habit primed it. + +Cure. Build sustaining cadence first. Campaign rhythm is earned by sustaining cadence. Programs that try to spike attention without sustaining baseline produce limited campaign engagement. + +--- + +## Failure 10: Owned audience small after years + +Symptom. After 2-3 years of program operation, the newsletter has 800 subscribers; the blog gets 5,000 monthly visits; the community is small. + +Diagnosis. Long-term investment in owned channels was skipped. Program reach (if there is reach) is rented from third parties. + +Cure. Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +--- + +## Failure 11: Earned channels not producing + +Symptom. The program has occasional coverage from third parties but no reliable earned-channel reach. Mentions are rare; syndication is informal; AI-search citation rates are low. + +Diagnosis. Earned channels are being treated as automatic. Relationship investment, pitching discipline, and citation-hook content design are not in place. + +Cure. Apply the earned-channel investment discipline. Specific capacity to relationship-building, pitching, syndication, citation tracking. Investment compounds over years. + +--- + +## Failure 12: Paid distribution costs rising + +Symptom. Paid amplification was producing acceptable cost-per-engagement 12-18 months ago. Costs have risen 50-100% since then. Engagement is similar; costs are higher. + +Diagnosis. Auction dynamics on paid platforms. Programs heavily dependent on paid see costs rise without offsetting owned/earned investment that would reduce paid dependence. + +Cure. Build owned and earned channels to reduce paid dependence. Within paid, focus on the highest-ROI placements; cut lower-performing paid spend. Recognize that paid costs typically rise over time on auction-based platforms; budget assumptions should account for this. + +--- + +## Failure 13: Channels mismatched to audience + +Symptom. The program is present on multiple channels. Engagement is low across most of them. The team is confused because the channels seemed obvious choices. + +Diagnosis. Channels were chosen by industry default ("everyone is on LinkedIn") or by capacity availability ("we can post on TikTok") rather than by audience-engagement match. + +Cure. Run the audience-channel audit (see `audience-channel-matching.md`). Cut channels where the audience is present but not engaged. Increase investment in channels where the audience is genuinely engaged. + +--- + +## Failure 14: Cadence too aggressive + +Symptom. Email subscribers are unsubscribing at higher rates. Social engagement is declining despite increased posting volume. The team is producing more content per week than ever; reception is worse. + +Diagnosis. Cadence has exceeded audience attention norms. The team is over-publishing. + +Cure. Reduce cadence to channel norms. Test reduced frequency for 6-8 weeks; observe whether engagement improves and unsubscribes slow. Most programs benefit from disciplined cadence rather than maximal cadence. + +--- + +## Failure 15: Cadence inconsistent + +Symptom. The program publishes 3 times in a week, then nothing for 3 weeks, then 5 times in 4 days. Audiences cannot develop habit. + +Diagnosis. No cadence discipline. Production happens when capacity allows; distribution follows production rather than following audience-attention rhythm. + +Cure. Establish cadence targets per channel. Build content calendars that smooth publication across the period. Capacity that produces content unevenly should distribute the publication evenly even if production was uneven (held pieces release on schedule). + +--- + +## Failure 16: No campaign rhythm + +Symptom. The program runs sustained cadence consistently. Flagship launches happen. The launches receive routine treatment; no campaign coordination produces outsized attention. + +Diagnosis. Campaign rhythm has not been built. The program has sustained cadence but no concentrated moments. + +Cure. Plan 4-12 campaign moments per year. Each campaign concentrates cross-format distribution for 4-6 weeks. The campaigns are earned by the sustaining cadence; together they produce the rhythm strong programs use. + +--- + +## The cross-cutting pattern + +Most distribution failures share a single root: treating distribution as posting-after-publishing rather than as the equal half of the work. + +Posting-after-publishing thinking treats publication as the end of the work. The piece goes live; minimal distribution work follows; reach is whatever happens organically. Output: most pieces reach a fraction of their potential audience. + +Distribution-as-half-the-work thinking treats distribution as a discipline equal to production. Channel choices are deliberate; cadence is calibrated; owned-earned-paid mix is strategic; measurement informs decisions. Output: pieces reach engaged audiences because the distribution work earned the reach. + +The fix for almost any distribution failure is the same: treat distribution as a real discipline, not as posting. Allocate capacity proportionate to its importance. The capacity required is significant; the value extracted is also significant. + +--- + +## Methodology-level choices that stay in the public skill + +The sixteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the distribution-as-half-the-work framing. + +## Implementation choices that stay internal + +Specific tooling for distribution tracking. Specific reporting templates for distribution outcomes. Specific reviewer training on per-channel conventions. Specific automation that flags distribution gaps. The team's own conventions for failure-pattern detection in their distribution program. These vary by team and tooling. diff --git a/skills/content-distribution/references/content-channel-matching.md b/skills/content-distribution/references/content-channel-matching.md new file mode 100644 index 0000000..6fcbf13 --- /dev/null +++ b/skills/content-distribution/references/content-channel-matching.md @@ -0,0 +1,181 @@ +# Content-channel matching + +Format-channel fit decisions. The compose-with-repurposing pattern. The format-mismatch failure mode that produces low engagement even when audience and channel match. + +Audience-channel matching answers "where is the audience?" Content-channel matching answers "does this format fit this channel?" Both must hold for distribution to produce engagement. + +--- + +## Format-channel fit examples + +How specific formats land on specific channels. + +### Long-form analytical text + +Strong fit. Newsletter (long-form-tolerant subscribers expect depth). Owned blog (long-form is the blog's native register). LinkedIn long posts (the platform rewards substantive long content). X threads (when the community fits and the thread is well-paced). + +Weak fit. Instagram (the format does not support text-driven content as primary). TikTok (audiences come for short-form video, not long text). Most podcast platforms (audio is the format; long-form text is not what audiences came for). + +### Short-form video + +Strong fit. TikTok, Reels, YouTube Shorts (the platforms' native formats). Increasingly LinkedIn video (the platform has invested in video). Twitter/X video for some communities. + +Weak fit. Newsletter (where text leads and video is a supplement). Owned blog (where written long-form leads). Most podcast platforms (audio-only consumption). + +### Statistic-driven content + +Strong fit. Social with quote-graphic visual treatment (LinkedIn, X, Instagram with the right design). AI search snippets (search engines weight statistics with named sources). Podcast mentions (host-read statistic + source citation works well). + +Weak fit. As primary format on owned blog (where context develops the stat; the stat alone is thin). Newsletter as the entire content (the stat without development underdelivers). + +### Conversational expert content + +Strong fit. Podcasts (the format is conversational by design). Video interviews (long-form video supports the conversational depth). Long social threads on platforms where substantive content is rewarded. + +Weak fit. Short-form video (the conversational depth does not fit 60-second windows). Newsletter (where edited prose fits better than conversational transcript). + +### Reference content (definitions, glossaries, FAQs) + +Strong fit. Owned blog and FAQ pages (canonical home). AI search snippets (citation-ready). Documentation sites (where reference is the format). + +Weak fit. Most social channels (reference content does not earn engagement on attention-driven feeds). Podcasts (reference content does not work in audio). + +### Visual narrative content (case studies with custom visuals, illustrated guides) + +Strong fit. Instagram (visual-first). Pinterest (visual reference). Owned blog with strong design treatment. + +Weak fit. Podcast (audio cannot carry visual content). Newsletter (most newsletters do not support rich visual treatment). + +--- + +## The compose-with-repurposing pattern + +When the audience is on a channel but the source format does not fit, the right answer is often to repurpose into a format that does fit. + +The pattern. + +- Source piece: 5,000-word whitepaper. +- Audience: present and engaged on TikTok (consumer-oriented program; younger demographic). +- Direct distribution: 5,000-word whitepaper does not fit TikTok. +- Compose-with-repurposing: produce 60-second video derivatives from the whitepaper's key claims, framed for TikTok conventions. Distribute the derivatives on TikTok; keep the whitepaper as the source for audiences who want depth. + +The discipline. Distribution is downstream of repurposing. A program with strong audience-channel matching but weak content-channel matching solves it through repurposing, not through distributing inappropriate formats. + +See `content-repurposing` for the cross-format adaptation discipline. The two skills compose: repurpose first to fit the channel; then distribute on the channel. + +--- + +## The format-mismatch failure mode + +The pattern when content-channel matching is skipped. + +The symptom. The program is present on the right channels (audience-channel matching held). Engagement is still low. The team is confused because the channels seem right but the content is not landing. + +The diagnosis. The format does not fit the channel even though the audience is there. The audience is on the channel for a different kind of content; the program's content does not match the channel's content expectations. + +The cure. Identify the format-channel mismatches. For channels with strong audience-channel match but weak content-channel match, repurpose to fit. For channels where neither matching holds, cut the channel. + +Recovery time. Format-mismatch fixes through repurposing typically produce visible engagement improvements within 4-12 weeks as the new format derivatives accumulate. + +--- + +## Format conventions per channel + +Beyond the strong/weak fit, each channel has specific conventions that distinguish good fit from forced fit. + +### LinkedIn long-form posts + +- 800-2,500 character body. +- First 1-3 lines must hook (truncation point). +- Short paragraphs, white space, occasional emphasis. +- Specific argument or position; vague observations underperform. +- Engagement-earning closes (questions, polarizing claims, specific examples). + +### X/Twitter threads + +- 5-15 posts typical for substantive threads. +- First post must hook; the thread is read sequentially. +- Each post is a complete thought, not a 280-character split of a longer thought. +- Conclusion specific. + +### Newsletter (substantive content) + +- 200-800 words for typical sends; 1,500-3,000 for engaged-audience long-form newsletters. +- Subject line and preheader bear most engagement load. +- Plain prose paragraphs render reliably. +- Single clear CTA per send. + +### Podcast + +- Spoken-language sentence structure. +- Conversational pacing with examples and asides. +- Show notes with links and structured summary. +- Consistent episode length; audiences develop expectations. + +### Owned blog + +- Format depends on the source-piece type; long-form articles, listicles, definitive guides, case studies, etc. +- SEO conventions: target keyword in title and headings, internal linking, schema markup. +- Visual rhythm appropriate to length. + +### TikTok / Reels / Shorts + +- 60-90 seconds typical. +- Hook in first 1-2 seconds. +- Captions essential. +- Single specific point. +- Visual variation, motion, or text-on-screen design. + +### Instagram (feed posts) + +- Visual-first; images carry the post's immediate impact. +- Caption supplements; not all viewers expand caption. +- Conventions vary by subgenre (educational carousels, product photography, lifestyle imagery). + +### YouTube (long-form) + +- 8-30 minutes typical for substantive content. +- Pacing for spoken delivery. +- Visual variation. +- Audio quality matters more than video quality. +- Thumbnail and title bear most click-through load. + +### AI-search snippets + +- 40-80 words for FAQ-style; 100-200 words for paragraph-style. +- Standalone meaning. +- Named-source citations. +- Specific framings. +- Schema markup where applicable. + +--- + +## Format adaptation per channel within a single source + +A worked example: a research report that distributes across multiple channels. + +Source. 8,000-word research report on B2B paid media benchmarks. + +Distribution by channel with content adaptation. + +- Owned blog. Full report as the canonical version. Schema-marked. Internal-linked from related pieces. Sections support deep linking. +- Newsletter (substantive subscribers). A 1,200-word digest sending the report's key findings, with a clear CTA to read the full report. +- LinkedIn long posts. 4-6 long-form posts, each developing one finding from the report. Each post includes the report's most relevant statistic with named-source attribution. +- X threads. 2-3 threads from the report, each focused on a specific finding. Threads link to the report. +- Podcast. One episode interviewing a practitioner who has applied the report's findings, with the report as the show's spine. +- TikTok / Reels. Statistic-driven 60-second videos, one per key statistic. Custom graphic treatment for each. +- AI-search snippets. 15-20 FAQ extractions from the report. Schema-marked FAQ page on the owned property. +- Promoted newsletter. Sponsored placement in 1-2 industry newsletters whose audience overlaps with the report's target. +- Boosted social. Boost the LinkedIn posts that earn the highest organic engagement. + +The example shows the compose-with-repurposing pattern in practice. The source is one piece; the distribution adapts per channel. The cross-format set composes with the channel choices to produce engagement appropriate to each channel's conventions. + +--- + +## Methodology-level choices that stay in the public skill + +The format-channel fit examples, the compose-with-repurposing pattern, the format-mismatch failure mode, the format conventions per channel, the worked example of multi-channel distribution from one source. + +## Implementation choices that stay internal + +Specific platform tooling for format-specific publishing. Specific design templates per channel-format combination. Specific automation for cross-channel scheduling. The team's own conventions for format-fit decisions when ambiguous. These vary by team, tooling, and brand voice. diff --git a/skills/content-distribution/references/distribution-cadence-patterns.md b/skills/content-distribution/references/distribution-cadence-patterns.md new file mode 100644 index 0000000..cc20c8b --- /dev/null +++ b/skills/content-distribution/references/distribution-cadence-patterns.md @@ -0,0 +1,183 @@ +# Distribution cadence patterns + +Frequency, mix, rhythm. Sustaining vs campaign rhythm. Common cadence patterns by program type. The audit that catches cadence mismatches. + +Cadence is the rhythm of a program's distribution: how often each channel publishes, what mix of owned-earned-paid, and how steady-state baseline relates to campaign spikes. The wrong cadence produces predictable engagement decline: too aggressive exhausts audiences; too sparse loses connection; mismatched to channel attention rhythm produces underperformance at any frequency. + +--- + +## Cadence axes + +Three axes that together define a program's distribution cadence. + +Frequency per channel. How often the program publishes to each channel. Newsletter weekly vs bi-weekly. LinkedIn 3 posts per week vs 1 per week. X 5-10 posts per week vs occasional. The frequency per channel is calibrated to the channel's audience attention rhythm. + +Mix. What proportion of distribution is owned vs earned vs paid. What proportion of pieces are original vs derivative. The mix reflects program strategy: owned-heavy programs invest in long-term audience-building; paid-heavy programs prioritize immediate reach. + +Rhythm. Sustaining baseline cadence vs campaign spikes. Most programs have a steady-state rhythm punctuated by occasional campaign moments around flagship launches. The rhythm shape determines how audiences experience the program. + +--- + +## Common cadence patterns by program type + +Cadences that show up repeatedly across program shapes. + +### B2B program with content-led demand generation + +Newsletter. Weekly. Substantive sends; subscribers expect depth. + +Blog. 2-4 posts per week. Mix of new pieces, refresh updates, and cross-format derivatives. + +LinkedIn. 3-5 posts per week. Mix of long-form posts, link drops to blog content, occasional video. + +X/Twitter. 5-10 posts per week. Higher cadence than LinkedIn; mix of original observations, links, and replies. + +Podcast. Bi-weekly or weekly episodes. + +Earned channels. Pitches and PR work continuous; coverage when earned. + +Paid amplification. Boost of best-performing organic pieces; occasional sponsored newsletter sends. + +Campaign rhythm. Quarterly spikes around flagship launches: cross-format wave for 4-6 weeks per launch. + +### Consumer brand with broad-audience reach goals + +Newsletter. Weekly or 2x weekly depending on subscriber engagement. + +Blog or content site. 1-2 posts per week. + +Instagram. Daily content (often a mix of feed posts, stories, and reels). + +TikTok. 2-4 posts per week. + +YouTube. Weekly long-form video plus shorts. + +Earned channels. PR for major moments; influencer relationships continuous. + +Paid amplification. Continuous; brands often run paid amplification on most major content as part of standard practice. + +Campaign rhythm. Heavier campaign spikes around product launches, seasonal moments, and brand events. + +### Niche specialist program with concentrated audience + +Newsletter. Weekly or bi-weekly. Substantive sends; the audience is concentrated and engaged. + +Blog. 1-2 posts per month. Quality-focused; depth over volume. + +Specific platforms (one or two). 2-3 posts per week on the platforms where the niche audience engages. + +Podcast (if applicable). Bi-weekly or monthly episodes. + +Earned channels. High prioritization; relationships with niche publications and influencers compound. + +Paid amplification. Selective; most niche programs benefit more from earned-channel investment than from paid amplification. + +Campaign rhythm. Less pronounced than broader programs; sustaining cadence is the dominant rhythm. + +### Founder-led brand with personal-brand element + +Newsletter. Weekly; founder-voice register; personal insight alongside program content. + +LinkedIn. Daily posts (or near-daily). Founder voice; personal observations alongside program content. + +X/Twitter. Daily posts with conversation engagement. + +Podcast. Often the founder hosts; weekly episodes. + +Earned channels. Founder builds relationships personally; PR coverage often person-driven. + +Paid amplification. Selective; the program builds on organic reach earned by founder authority. + +Campaign rhythm. Less formal campaigns; the program reads more as continuous founder voice than as discrete campaign moments. + +--- + +## Sustaining vs campaign rhythm + +The relationship between baseline cadence and campaign spikes. + +Sustaining cadence. The baseline rhythm. Audiences expect this cadence; deviations affect engagement. Sustaining cadence builds audience habit (subscribers who expect a Tuesday send keep paying attention; subscribers who get inconsistent sends start ignoring even the good ones). + +Campaign rhythm. Spikes around flagship launches, major announcements, or significant events. Concentrated cross-format distribution that briefly exceeds the sustaining cadence. + +The relationship. Campaign rhythm is earned by sustaining cadence. Programs without sustaining cadence cannot run effective campaigns; the audiences are not warm. Campaigns that spike out of nowhere produce limited engagement because no audience habit primes the moment. + +The balance. Strong programs run mostly sustaining cadence with occasional campaign spikes. The campaign spikes are 4-6 weeks total, 4-12 times per year. Programs running continuous "campaign" rhythm exhaust audiences; programs running only sustaining without campaigns miss the moments where flagship work could earn outsized attention. + +--- + +## Per-channel cadence tuning + +Each channel rewards different cadences. Cadence tuning matches channel-specific norms. + +Newsletter. Weekly is the most common B2B cadence. Bi-weekly works for higher-investment formats. Daily works for highly-engaged subscriber bases. The cadence should be predictable: subscribers should know roughly when to expect sends. + +LinkedIn. Algorithmic favor rewards 1-2 posts per day for individual accounts; company pages typically post less frequently (2-5 posts per week). Lower cadences (1-2 per week) work but limit reach. + +X/Twitter. The platform rewards higher cadence than other platforms. 5-15 posts per day is normal for engaged accounts; less can work but limits reach. + +Instagram. 1 post per day is common for engaged consumer accounts; 3-5 per week works for B2B and niche programs. Stories and reels often have higher cadence than feed posts. + +TikTok. Algorithmic recommendation rewards higher cadence; 1+ posts per day typical for accounts trying to grow. + +YouTube. Weekly long-form video is the upper-frequency norm; many channels publish less frequently. Shorts can publish more often (multiple per week). + +Podcast. Weekly is the most common cadence; bi-weekly works for higher-investment shows; daily works for high-volume formats (news-style podcasts). + +Owned blog. SEO programs benefit from regular publishing (2-4 posts per week typical for active programs); less frequent publishing limits the program's compounding traffic potential. + +--- + +## The cadence audit + +A short framework for auditing a program's cadence. + +1. Pull current cadence per channel over the last 90 days. What is the program actually doing? Often differs from the program's stated cadence target. +2. Compare to channel-specific norms. Are channel cadences within the engagement-rewarding range, or are they too sparse or too aggressive? +3. Identify cadence inconsistencies. Are there gaps where the program goes silent for weeks, then spikes? Inconsistency damages audience habit even when total volume is similar. +4. Match cadence to capacity. Is the program able to sustain the current cadences, or is it running unsustainably? +5. Identify the campaign rhythm. When were the last 3 flagship launches? Did sustaining cadence support them? Did campaigns earn outsized attention? + +The audit produces a calibration plan: which cadences to maintain, which to adjust, where the program is over-investing or under-investing. + +--- + +## Cadence anti-patterns + +Inconsistent cadence. 3 posts in one week, then nothing for 3 weeks. Audiences cannot develop habit; the program disappears between bursts. + +Volume-driven cadence. "We need to post X times per week" without reference to channel norms or audience attention. Volume without engagement is presence; presence without engagement is wasted capacity. + +Identical cadence across channels. Treating LinkedIn, X, TikTok, and newsletter all on the same cadence ignores channel-specific norms. Each channel has a different attention rhythm. + +No campaign rhythm. Pure sustaining cadence with no spikes. Flagship launches receive routine treatment; the moments where the program could earn outsized attention pass without the campaign coordination they warrant. + +Continuous campaign rhythm. Pure campaign rhythm with no sustaining baseline. Audiences never develop habit; every "launch" feels like another launch in a continuous stream of launches. + +Cadence beyond capacity. The team commits to LinkedIn daily, X 10x per day, newsletter twice weekly. Capacity cannot sustain; cadence drifts; audiences notice the drift. + +--- + +## When to adjust cadence + +Signals that cadence needs change. + +Engagement declining steadily on a channel. May indicate cadence too aggressive (audience fatigue) or too sparse (audience disengagement) or content-fit issues (different problem). Investigate. + +Subscriber unsubscribes spiking on newsletter. Cadence too aggressive, or content quality declining, or both. Cure depends on diagnosis. + +Algorithm changes on a platform. Some platform algorithm shifts reward different cadences. Adjust based on observed engagement signals. + +Capacity changes. Team grows or shrinks; cadence should match sustainable capacity. Programs with shrinking teams that maintain prior cadence often produce drift in quality. + +Audience-research findings. New data about audience attention rhythms. Adjust cadence to fit revealed audience patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The cadence axes, common cadence patterns by program type, sustaining-vs-campaign rhythm, per-channel cadence tuning, the cadence audit, the cadence anti-patterns, the signals for cadence adjustment. + +## Implementation choices that stay internal + +Specific scheduling tools the team uses. Specific cadence-tracking dashboards. Specific cadence-by-channel calendars. The team's own conventions for cadence-vs-quality tradeoffs when capacity is constrained. These vary by team, tooling, and program shape. diff --git a/skills/content-distribution/references/distribution-measurement.md b/skills/content-distribution/references/distribution-measurement.md new file mode 100644 index 0000000..c1d73f9 --- /dev/null +++ b/skills/content-distribution/references/distribution-measurement.md @@ -0,0 +1,203 @@ +# Distribution measurement + +Per-channel metrics, channel-level analysis, cross-channel attribution, the measurement-honest program. The discipline that prevents distribution-theater and turns distribution into a learning system. + +Distribution without measurement runs on assumption. Channels stay in the mix because they have always been in the mix; cadence stays at current levels because nobody has asked whether it is right; paid spend continues because budget exists. Measurement is the discipline that surfaces what is actually working and what is not. + +--- + +## Per-channel metrics + +Metrics organized by what they reveal about a channel's effectiveness. + +Reach metrics. + +- Impressions: how many times the content was shown. +- Unique reach: how many unique people saw the content. +- Audience growth: how the channel's owned audience size is changing. + +Engagement metrics. + +- Click-through rate (CTR): clicks divided by impressions. +- Time-on-page: how long visitors stay on the linked content. +- Scroll depth: how far down the content visitors scroll. +- Completion rate: for video and audio, what percentage finishes. +- Comment, share, and reaction signals on social. +- Reply rate on email. + +Conversion metrics. + +- Newsletter signups attributed to the channel. +- Content downloads attributed to the channel. +- Qualified-lead actions (form submissions, demo requests, free-trial starts). +- Sales-cycle progression for B2B programs. +- Attributed revenue for revenue-tracked programs. + +Channel-health metrics. + +- Audience retention rate (subscribers staying vs unsubscribing). +- Engagement-rate trend over time (rising, stable, falling). +- Algorithm-favor signals (for platform-controlled channels). +- Deliverability rate (for email). + +--- + +## Channel-level analysis + +Aggregating metrics into channel effectiveness assessments. + +Engagement-per-distribution-effort. + +- Some channels look impressive (high reach numbers) but produce low engagement. +- Some channels produce moderate reach but very high engagement. +- The channels that compound value are usually the engagement-heavy ones, not the reach-heavy ones. + +Conversion-per-channel. + +- Reach without conversion is vanity. Conversion is value. +- Channels driving conversion at favorable cost (whether owned-channel investment cost or paid-channel spend) earn their place in the mix. +- Channels driving impressive reach but no conversion may be building brand awareness (which is real value) or producing nothing of value (which is wasted capacity). + +Trend over time. + +- Channels' performance changes. Algorithm shifts, audience migrations, competitive landscape changes affect channel effectiveness. +- A channel that was effective 18 months ago may be underperforming now. +- A channel that was marginal 18 months ago may be the program's strongest now. +- Quarterly review of channel-level trends catches these shifts. + +The relative-effectiveness audit. + +Rank channels by engagement-per-effort and by conversion-per-effort. Channels at the top of both rankings are the program's strongest; channels at the bottom of both are candidates for cutting or restructuring. + +--- + +## Cross-channel attribution + +The audience member encounters the program on multiple channels before converting. Attribution should reflect this reality. + +Single-touch attribution failures. + +- Last-touch attribution. Credits the last channel before conversion. Misrepresents which channels actually drove the audience relationship; usually overweights the conversion channel (often newsletter or direct site visit) and underweights the discovery channels. +- First-touch attribution. Credits the first channel of contact. Misrepresents the role of nurturing channels; usually overweights discovery channels and underweights nurturing channels. + +Multi-touch attribution patterns. + +- Linear attribution. Equal weight to all touchpoints. Simple; usually a step up from single-touch. +- Time-decay attribution. More weight to touchpoints closer to conversion. Reflects the commonsense intuition that recent touches matter more than distant ones. +- Position-based attribution. Significant weight to first and last touch; remaining weight distributed across middle touches. Reflects the importance of discovery and conversion moments. +- Data-driven attribution. Algorithmic weighting based on observed conversion patterns. Most accurate; requires sufficient data and tooling. + +The attribution honesty discipline. + +- Attribution models are simplifications. None is "correct"; all are useful approximations. +- Programs should pick an attribution model and stay consistent. Switching attribution models produces apparent performance changes that are not real. +- Cross-reference attribution data with other signals (subscriber surveys, sales conversation reports). Triangulation is more honest than relying on attribution data alone. + +--- + +## The measurement-honest program + +Discipline that turns measurement into a decision-making input rather than into reporting theater. + +Cuts channels that consistently underperform. + +- A channel underperforming for 2-3 quarters is a real signal, not noise. +- Cutting underperforming channels reallocates capacity to channels that produce. +- The decision is hard because cutting feels like admitting failure; programs that cut decisively outperform programs that maintain everything indefinitely. + +Increases investment in channels that consistently produce. + +- Strong channels deserve disproportionate investment. +- Programs often spread investment evenly across channels regardless of performance; the measurement-honest discipline allocates investment to where return is highest. + +Adjusts cadence based on engagement patterns. + +- Cadence that is too aggressive shows up in declining engagement and rising unsubscribes. +- Cadence that is too sparse shows up in audience-habit decay. +- Engagement patterns inform cadence adjustments. + +Calibrates paid spend based on organic validation. + +- Boost what organic validates. +- Reduce or eliminate paid spend on content that does not earn organic engagement. +- Paid spend should be a function of organic signal, not a function of available budget. + +--- + +## The measurement-theater anti-pattern + +When measurement is performed without informing decisions. + +The pattern. The team produces quarterly reports with channel-level metrics. Reports are presented to leadership. Decisions are not changed based on the reports. Underperforming channels stay in the mix; over-performing channels do not get additional investment. The program continues as it would have continued without the measurement. + +Why it happens. + +- Measurement is treated as performance theater rather than as decision input. +- Leadership signals that all channels should continue (political pressure, sunk cost, brand reasons). +- The team has measurement capacity but lacks decision-authority over distribution. + +The cure. Tie measurement to specific decisions. Each quarter, the measurement review produces a list of changes: cuts, additions, cadence adjustments, capacity reallocations. Reviews without decisions are theater. + +--- + +## Common measurement failures + +No measurement. Distribution runs on assumption. Channels stay in the mix because they always have. Cadence and capacity allocation persist regardless of effectiveness. + +Measurement without action. Measurement is performed; decisions are not changed. The program runs as if no measurement happened. + +Vanity metrics. Reach and impressions reported as primary success metrics. Engagement and conversion underreported. The program looks like it is working when it may not be. + +Single-touch attribution dominance. All attribution analysis runs on last-touch or first-touch. The realities of multi-touch journeys are missed. + +No trend analysis. Channel performance reported in quarterly snapshots; trends across quarters are not surfaced. Channel decay is detected late. + +Cross-program comparison failures. The program compares itself to industry benchmarks without context. Benchmark numbers from other industries or audience segments may not apply; comparison produces false signals. + +--- + +## Measurement infrastructure + +The tooling and processes that support measurement. + +Analytics platform. Web analytics that tracks per-channel traffic, engagement, and conversion. Standard requirement for any program with a content site. + +Email analytics. Open rates, click-through rates, unsubscribe rates, deliverability rates. Standard for any program with a newsletter. + +Social analytics. Per-platform analytics from each social platform; supplemented by social-listening tools where the program tracks mentions and shares beyond direct posts. + +Attribution tooling. From simple UTM tracking and Google Analytics multi-touch reports to sophisticated attribution platforms (depending on program scale and complexity). + +Channel-specific dashboards. Programs often build per-channel dashboards that surface the metrics most relevant to that channel's optimization. + +Cross-channel rollup. A program-level dashboard that aggregates channel-level data into a coherent view of distribution effectiveness. + +The infrastructure cost is real; the alternative (running distribution without measurement) is more expensive over time because capacity gets allocated to wrong places. + +--- + +## Measurement cadence + +When to measure what. + +Continuous. Some metrics update daily or weekly: website traffic, social engagement, email opens. The team monitors these continuously. + +Weekly. Per-channel summaries of recent performance. Catches sharp decay or sharp improvements early. + +Monthly. Channel-level rollup. Detects trends developing across multiple weeks. + +Quarterly. Strategic measurement review. Decisions about channel cuts, additions, cadence adjustments, capacity reallocations. + +Annual. Program-level measurement review. Strategic shifts in channel mix, attribution-model adjustments, capacity reallocations across the program. + +The cadence should match the decision cadence. Programs with monthly capacity-allocation decisions need monthly measurement; programs with quarterly decisions need quarterly measurement. + +--- + +## Methodology-level choices that stay in the public skill + +The per-channel metric categories, channel-level analysis approaches, cross-channel attribution patterns, the measurement-honest discipline, the measurement-theater anti-pattern, common measurement failures, infrastructure requirements, measurement cadence. + +## Implementation choices that stay internal + +Specific analytics platforms (the team's chosen GA configuration, alternative platforms, attribution tools). Specific dashboard designs and reporting templates. Specific UTM tagging conventions. Specific attribution-model parameters tuned for the program. The team's own conventions for benchmark comparisons. These vary by team, tooling, and program scale. diff --git a/skills/content-distribution/references/earned-channel-work.md b/skills/content-distribution/references/earned-channel-work.md new file mode 100644 index 0000000..690d86b --- /dev/null +++ b/skills/content-distribution/references/earned-channel-work.md @@ -0,0 +1,172 @@ +# Earned-channel work + +PR, syndication, mentions, AI-search citation, word of mouth. The relationship investment that compounds over years. The pitching discipline that earns coverage rather than burning relationships. + +Earned channels reach audiences the program cannot reach directly. The work to earn the channel is real: relationships built over years, pitches that demonstrate the program's value, content that earns citation. Programs treating earned channels as automatic produce nothing; programs investing in the relationships earn ongoing channel access. + +--- + +## PR and press + +Journalists, podcasters, newsletter operators who cover the program's content. + +The relationship-first principle. Coverage follows relationships. Cold pitches from unknown senders get ignored at high rates; warm pitches from known senders get read. Programs that build relationships before they need coverage are the programs that earn coverage when they have flagship work to share. + +Building relationships. + +- Read the journalists, podcasters, and operators in the program's space. Know what they cover, what their angles are, what they have written or aired recently. +- Engage substantively before pitching. Comment thoughtfully on their work; share their pieces with attribution; respond if they ask for input. +- Build the relationship to a level of mutual recognition before the first pitch. + +Pitching when the relationship exists. + +- Pitch specific to the recipient. Reference their recent work; explain why the program's content fits their angle. +- Lead with the angle, not with the company. Recipients care about the story, not about the program's brand. +- Provide everything the recipient needs: the source piece, key statistics, possible quotes, a clear point of contact. +- Make it easy to say yes; make it easy to say no. + +The mass-blast pitching anti-pattern. + +- Identical pitches sent to dozens of recipients. Recipients detect mass-blast quickly; relationships are damaged not built. +- Pitches focused on the program rather than on the story. Recipients filter these as ads. +- Follow-up pressure. Excessive follow-ups damage future relationship potential. + +The PR investment timeline. Real PR relationships build over 1-3 years. Programs without prior PR investment cannot generate coverage on a deadline; programs with sustained investment have relationships that produce ongoing coverage. + +--- + +## Syndication + +Other publications republishing or excerpting the program's content with appropriate attribution. + +The syndication exchange. The program provides quality content; the partner provides reach into their audience. Both parties win when the exchange is fair. + +Negotiation patterns. + +- Republishing with canonical link. The partner runs the full piece; canonical link tag points to the program's version for SEO. Reach extends; SEO authority preserves. +- Excerpt with link. The partner runs an excerpt with a link to the full piece on the program's site. Less full reach but stronger funnel back to the program. +- Republishing without canonical. Less common; risks SEO duplication issues; should be avoided unless specifically negotiated with the partner about which version is canonical. + +Common syndication failures. + +- Canonical link mishandling. The piece appears on the partner's site as the canonical version; the program's version drops in rankings. +- Partner relationships not maintained. Syndication partners that stop running the program's content; the channel goes silent. +- Indiscriminate syndication. Every piece syndicated regardless of fit; partner audiences see content that does not match their interests; partner removes the program from rotation. + +The selective-syndication discipline. Not every piece warrants syndication. Match piece-to-partner: which pieces fit which partners; which partners' audiences will engage with which pieces. Selective syndication produces stronger partner relationships than blanket syndication. + +--- + +## Mentions and citations + +Other content marketing programs, industry analysts, AI search engines citing the program's content. + +Citation as compounding authority. Each citation increases the program's authority signal. Citations from authoritative sources weight more than citations from less authoritative ones. Citation accumulation over years is one of the most durable signals of program quality. + +Earning citations. + +- Produce content with citation hooks. Original data; named frameworks; primary research; contrarian-but-defensible positions. +- Build identifiable phrasings or term coinages. If the program names a concept, others citing the concept cite the program. +- Make content discoverable when others are researching the topic. SEO and AI-search visibility matter for citation discoverability. + +The generic-content-no-citation problem. Pieces that do not have specific citation hooks rarely get cited even if they are well-written. The hook is what other writers reach for. + +AI-search citation specifically. AI engines cite content that matches their retrieval criteria. See `content-repurposing`'s AEO extraction patterns for the discipline of producing AI-citation-friendly content. Programs that design for AI citation earn more citations than programs that publish without that consideration. + +--- + +## Word of mouth and shares + +Audiences sharing pieces with their networks. + +The hardest channel to engineer. Word of mouth follows from genuine usefulness. Pieces that audiences want to share are pieces that are genuinely valuable; pieces that are generic do not get shared even if they are read. + +Patterns that earn shares. + +- Specific, useful content. Audiences share pieces that help them or that they think will help others. +- Citation-worthy content. Audiences share pieces they want to point to as references. +- Provocative-but-defensible content. Audiences share pieces that take a position they want to amplify. +- Memorable framings. Audiences share pieces that introduce concepts or framings they find useful. + +Patterns that do not earn shares. + +- Generic content. Pieces that say what every other piece on the topic says do not earn the share. +- Surface-level coverage. Pieces that scratch the surface without substantive depth do not feel worth sharing. +- Defensive content. Pieces that hedge every position do not earn the share because they do not say anything specific. + +The measurement challenge. Word-of-mouth sharing often happens in private channels (DMs, internal Slack, work emails) where the program cannot directly measure. Indirect signals: referral traffic from unknown sources, audience members reporting "a colleague sent me this," conversion-without-tracked-attribution. + +--- + +## Earned-channel investment + +The capacity allocation question. + +Programs without earned-channel investment. Treat earned channels as automatic. Coverage that happens, happens; coverage that does not happen, does not. Output: limited earned reach; the program is dependent on owned and paid distribution. + +Programs with strategic earned-channel investment. Allocate specific capacity to relationship-building, pitching, syndication negotiation, citation tracking. Output: earned channels become reliable distribution over years. + +The investment shape. + +- PR work. A specific person owns relationships and pitching. Investment level varies by program: from 5% of one person's time at smaller programs to dedicated PR roles at larger programs. +- Syndication negotiation. Periodic outreach to potential partners; relationship maintenance; canonical-link verification. +- Citation tracking. Monitoring where the program is being cited; engaging with those citations (thanking citers; building relationships with frequent citers). +- AI-search citation. Tracking AI engine citation rates; iterating on AEO extraction patterns based on what gets cited. + +The investment payoff timeline. Earned-channel investment compounds over 2-5 years. Year 1 produces limited returns; years 3-5 produce significant returns if the investment was sustained. + +--- + +## Common earned-channel failures + +Mass-blast pitching. Pitches sent to dozens of recipients identical or near-identical. Recipients detect; relationships damaged; future coverage potential reduced. + +No relationship investment. The program tries to "do PR" only when it has flagship work to share. Without prior relationship investment, pitches go cold even when the content is genuinely strong. + +Syndication mishandled. Canonical-link issues; partner relationships not maintained; SEO authority drained to partner sites. + +No citation hooks. Pieces produced without elements that earn citation. Mentions and AI-search citation rates stay low because nothing in the content prompts citation. + +Earned channel as automatic. Treating earned channels as if they happen on their own. Without investment, they do not. + +Limited PR scope. Pitching only the same 3-5 trade publications repeatedly. The relationship gets over-extended; coverage drops; broader earned-channel work is not happening. + +--- + +## Earned-channel measurement + +Earned channels are harder to measure than owned or paid, but measurement is still possible. + +PR coverage. + +- Volume: how many pieces of coverage per quarter. +- Quality: which publications, which authors, what reach those publications have. +- Sentiment: positive coverage, neutral, critical. +- Attribution: traffic and conversions sourced from coverage moments. + +Syndication. + +- Reach via partner: traffic and engagement on partner-published versions. +- Funnel back: traffic from partner content to program's own site. +- Authority preservation: SEO position holding given canonical link signaling. + +Mentions and citations. + +- Citation count over time. Tools that track mentions across the web help here. +- Citing-source quality. Citations from high-authority sources weight more. +- AI-search citation rates. Tools that track AI engine citations are emerging; the measurement infrastructure is improving. + +Word of mouth. + +- Indirect signals: referral traffic from unknown sources, audience reports, sustained organic growth without proportional paid amplification. +- Survey data: when audience members are asked how they discovered the program, word-of-mouth signals appear. + +--- + +## Methodology-level choices that stay in the public skill + +The relationship-first PR principle, the syndication exchange and selective-syndication discipline, the citation-earning patterns, the word-of-mouth observations, the earned-channel investment shape and timeline, the common failures, the measurement approaches. + +## Implementation choices that stay internal + +Specific PR-relationship CRM tooling. Specific pitching templates and tracking. Specific syndication negotiation conventions. Specific citation tracking software. Specific AI-search citation tracking infrastructure. The team's own conventions for relationship-investment cadence. These vary by team, budget, and program scope. diff --git a/skills/content-distribution/references/owned-channel-discipline.md b/skills/content-distribution/references/owned-channel-discipline.md new file mode 100644 index 0000000..3b3adbb --- /dev/null +++ b/skills/content-distribution/references/owned-channel-discipline.md @@ -0,0 +1,156 @@ +# Owned-channel discipline + +Newsletter, blog, social, podcast, community discipline. The starvation anti-pattern. The patterns that turn owned channels from posting infrastructure into durable distribution foundations. + +Owned channels are the most reliable distribution a program has. The newsletter delivers to every subscriber's inbox; the blog persists indefinitely; the owned social accounts run on the program's terms (within platform constraints). Programs that under-invest in owned channels become dependent on third-party distribution; when platforms change, when paid costs rise, when earned channels go quiet, the dependent program's reach collapses. + +--- + +## Newsletter discipline + +The most direct owned distribution. + +The discipline shape. + +- Cadence consistency. Subscribers develop expectations. Weekly send on Tuesdays gets opened more reliably than weekly send that drifts to Thursday or Wednesday or Friday. +- Content quality matching subscriber expectations. What subscribers signed up for; the program delivers it. Drift in quality (or in topic) produces unsubscribes. +- Single CTA per send. Multi-CTA emails dilute. Subscribers process one action; competing actions reduce all of them. +- Deliverability hygiene. Spam-trigger words, unbalanced text-to-image ratios, technical configuration (SPF, DKIM, DMARC) all affect deliverability. Programs that ignore deliverability watch open rates decline. +- List health. Engaged subscribers vs lapsed subscribers; pruning lapsed segments improves overall deliverability and engagement metrics. + +Common newsletter failures. + +- Cadence drift. The "weekly" newsletter that becomes bi-weekly, then monthly, then sporadic. Subscribers stop expecting; engagement decays. +- Subject lines that announce instead of earning the open. "Newsletter for week of November 14" performs worse than specific subject lines tied to the email's content. +- Multi-topic emails that try to cover everything the program produced this week. Single-topic focus produces stronger engagement. +- No segmentation. The same email goes to every subscriber regardless of interest patterns. Programs with multiple distinct content streams benefit from segmented sends. + +See `email-sequences` for the email-specific discipline including subject-line patterns, sequence design, and lifecycle campaigns. + +--- + +## Blog discipline + +The owned content home. + +The discipline shape. + +- Architecture and technical SEO foundations. Crawlability, indexability, page speed, schema markup. Without these, the blog cannot earn search traffic regardless of content quality. +- Pillar and cluster organization. Topical hubs that compound authority over years. See `pillar-content-architecture`. +- Refresh discipline. Library does not decay into staleness. See `content-refresh-system`. +- Internal linking. Strong internal-link graph that distributes authority and earns rankings. +- On-page optimization. Per-page SEO discipline. See `seo-onpage`. + +Common blog failures. + +- Publishing without distribution to the blog. The blog is the destination; if no traffic flows to it from owned and earned distribution, only the slowly-compounding search traffic builds. +- Architectural neglect. The blog's information architecture rots; URL structures change without redirects; old content drags down newer pages' authority. +- Refresh starvation. The library accumulates stale pieces; new pieces have to compete with the team's own decaying content for rankings. +- No design investment. The blog reads as a content dump rather than as a property; visitors do not return. + +The blog as compounding asset. A well-disciplined blog produces traffic for years. Programs that invest in blog foundations early earn compounding returns; programs that under-invest never earn the compounding effect. + +--- + +## Owned social discipline + +LinkedIn company page, X account, YouTube channel, Instagram account, etc. + +The discipline shape. + +- Per-platform conventions. Each platform rewards different content shapes. LinkedIn rewards substantive long-form posts; X rewards conversation; YouTube rewards specific topic and audio quality; Instagram rewards visuals. +- Cadence calibrated to platform attention rhythm. Daily on platforms that reward daily; weekly on platforms that work weekly. Mismatch reduces reach regardless of content quality. +- Engagement-signal optimization. Algorithmic recommendation rewards content that earns engagement signals (comments, shares, time-watched, click-through). Content designed for these signals reaches more. +- Account-health hygiene. Posting consistency; authentic engagement (not spam-replies); profile completeness; consistent branding. + +Common owned-social failures. + +- Cross-posting identical content across platforms. Each platform has different conventions; identical posts perform poorly on all platforms. +- Generic posting templates. Audiences detect template-driven posting; engagement decays. +- No engagement with the audience. Posting without responding to comments or engaging with industry conversations reduces algorithmic favor over time. +- Reliance on a single platform. Platform algorithms shift; programs dependent on one platform's reach are exposed to algorithm risk. + +Owned vs platform-controlled. Owned-social channels are owned in the sense that the program runs the account; not owned in the sense that the platform controls reach. The distinction matters for risk: programs treating owned-social as fully owned underestimate platform-algorithm risk. + +--- + +## Podcast discipline + +Owned audio distribution. + +The discipline shape. + +- Audio quality. Listeners tolerate uneven video far more than uneven audio. Audio investment returns more than video investment up to a point. +- Consistent episode cadence. Weekly is most common; bi-weekly works for higher-investment shows. Drift undermines listener habit. +- Show notes as derivative format. Show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as their own derivative format with quality discipline. +- Cross-platform distribution. Apple Podcasts, Spotify, YouTube, Google Podcasts. Each is a discoverability surface. +- Format consistency within the show. Listeners develop expectations; format changes can lose listeners. + +Common podcast failures. + +- Production quality drift. The first 10 episodes are well-produced; episodes 30+ show production decay. +- No cross-platform distribution. The show lives on one platform; potential listeners on other platforms cannot find it. +- Show notes treated as afterthought. Thin show notes reduce SEO value and listener navigation. +- Cadence inconsistency. Drift between episodes undermines listener habit. + +The podcast as relationship channel. Engaged listeners feel connected to the host(s); the audience relationship is intimate. Podcasts produce trust signal that other channels often cannot match. + +--- + +## Community discipline + +Slack communities, Discord servers, dedicated discussion forums. + +The discipline shape. + +- Active moderation. Communities require continuous facilitation. Spam, off-topic content, and unaddressed conflict damage community health. +- Sustained value-delivery. Members come and stay because the community delivers value. Value can be peer connection, expert access, content access, or product feedback. +- Integration with the broader content program. Members get early access; program content is shared in the community; community feedback informs program decisions. +- Member-driven content. Strong communities have member-to-member interaction beyond program-to-member broadcasting. + +Common community failures. + +- Abandonment. Communities launched with fanfare and then under-staffed. Members leave; the community decays into a ghost town signaling the program's decline. +- Broadcast-only. The program posts to the community as if it were another social channel; no facilitation of member interaction. +- Membership-quality drift. Open communities accumulate members who do not contribute; the signal-to-noise ratio degrades. +- No moderation policy. Conflict, spam, or off-brand content erodes the community's character. + +Community as audience-relationship multiplier. The community is often the program's most engaged audience segment. Investment in the community returns at multiple points: feedback, advocacy, product input, content participation. + +--- + +## The starvation anti-pattern + +Programs that under-invest in owned channels become dependent on third-party distribution. + +The pattern. The program invests heavily in paid acquisition or in social platforms it does not own. Reach grows on those channels. The program does not build newsletter, blog, or community in proportion. When platforms change algorithms or paid costs rise, reach collapses; the program has no owned channels to fall back on. + +The visibility. Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscribes, account creations, community memberships). The reach is rented, not owned. + +The cure. Reallocate capacity. Reduce paid spend; reduce broad-platform investment. Increase newsletter, blog, and community investment. Recovery is multi-year; programs in starvation cannot rebuild quickly. + +Prevention. Programs in early stages should over-invest in owned channels relative to the reach those channels initially produce. The investment compounds over years; the alternative is decade-long dependency on third-party distribution. + +--- + +## The owned-channel investment timeline + +Owned channels reward long investment. + +Year 1. Newsletter and blog established; cadence consistent; subscriber count and traffic both small. The investment feels like it is producing little; the cadence is the foundation. + +Year 2-3. Newsletter list grows; blog accumulates SEO traffic; community starts to form (if part of the strategy). The investment starts to compound; engagement signals improve. + +Year 4+. Owned channels are reliable distribution. Newsletter sends produce predictable engagement; blog earns substantial organic traffic; community is a meaningful audience asset. The early investment compounds. + +The patience cost. Owned-channel investment is multi-year; the visible returns lag the investment. Programs that abandon owned-channel investment in years 1-2 because returns feel small often regret it in years 3-5 when peers who sustained the investment are reaping the compounding effect. + +--- + +## Methodology-level choices that stay in the public skill + +The owned-channel disciplines (newsletter, blog, social, podcast, community), the common failures per channel type, the starvation anti-pattern, the investment timeline. + +## Implementation choices that stay internal + +Specific newsletter platforms and templates. Specific blog CMS and design systems. Specific social-publishing tools. Specific podcast hosting and editing tools. Specific community-management software (Slack, Discord, custom forums). The team's own conventions for cadence and quality thresholds. These vary by team, budget, and program scope. diff --git a/skills/content-distribution/references/paid-promotion-patterns.md b/skills/content-distribution/references/paid-promotion-patterns.md new file mode 100644 index 0000000..43dbd94 --- /dev/null +++ b/skills/content-distribution/references/paid-promotion-patterns.md @@ -0,0 +1,181 @@ +# Paid promotion patterns + +When boosting organic content earns its keep. The paid-as-substitute anti-pattern. The disciplines that distinguish strategic paid amplification from spending budget on content that did not validate organically. + +Paid promotion of organic content is an amplification layer. The pattern works when paid spend extends the reach of content that organic engagement has already validated; the pattern fails when paid spend substitutes for organic validation or for owned-channel investment. + +--- + +## The boost-organic pattern + +The most common and effective form of paid content amplification. + +The shape. A piece publishes organically. Some pieces show strong engagement signals: high CTR, high time-on-page, organic shares, comment engagement. The program boosts those validated pieces with paid spend to extend reach. + +Why it works. The content has audience validation. Audiences engage with the boosted content because it is genuinely engaging. The paid spend amplifies what already worked rather than gambling on what might work. + +Implementation patterns. + +- Engagement-threshold boosting. Pieces that exceed defined engagement thresholds in the first 24-48 hours get boosted. The thresholds (CTR, share rate, comment volume) vary by program. +- Editorial-judgment boosting. Editorial reviews recent organic pieces and selects which ones merit boost spend based on broader strategic fit, not just engagement metrics. +- Hybrid. Engagement-threshold boost for tactical amplification; editorial-judgment boost for strategic amplification of pieces that align with program goals beyond engagement metrics. + +Capacity allocation. Most strong programs allocate 5-20% of distribution capacity to paid amplification of organic content. Higher allocations often signal under-investment in owned channels. + +--- + +## Promoted newsletter sends + +Sponsored placements in third-party newsletters. + +The shape. The program pays a third-party newsletter to feature its content. The newsletter's audience sees the program's content alongside the newsletter's editorial content. + +Why it works. Newsletter audiences have strong attention rhythms; sponsored content placed in a newsletter the audience reads gets meaningful attention. + +Implementation patterns. + +- Single-send sponsorship. The program pays for one prominent placement in a single send. Strongest engagement; highest cost per send. +- Multi-send package. The program pays for placements across multiple sends. Weaker per-send engagement; lower cost per send. +- Co-marketing. The program partners with the newsletter on a co-produced piece; both parties benefit. Often the most effective format when it fits both audiences. + +Selection criteria. + +- Audience overlap with target audience. +- Newsletter editorial fit (content tone matches the program's voice). +- Engagement metrics (open rates, click-through rates, sponsor performance history). +- Cost relative to alternative paid options. + +Common newsletter-sponsorship failures. + +- Mismatched audience. The newsletter has reach but does not match the program's target audience. +- Mismatched tone. Sponsored content clashes with the newsletter's voice; readers tune out. +- Generic sponsored content. Sponsored placements that read as ads underperform sponsorships that read as editorial fit. + +--- + +## Syndication networks (Outbrain, Taboola, native networks) + +Paid placement on third-party sites via "you may also like" or "recommended for you" units. + +The shape. Programs pay per click; content appears on third-party sites in recommendation units. + +Implementation patterns. + +- Bid management. Per-piece bidding; cost-per-click optimization. +- Geographic and audience targeting. Some networks support targeting; others are broader. +- Brand-safety controls. Choose where the content appears; some networks have brand-safety concerns about co-placement. + +Effectiveness. Variable. Some programs see meaningful traffic with reasonable cost-per-engagement; others see high traffic numbers but low engagement once visitors land on the program's content. The audience quality varies significantly across networks. + +Common syndication-network failures. + +- Click optimization without engagement measurement. The program optimizes for cost-per-click; clicks arrive; engagement is low; the audience is the wrong audience. +- Brand-safety incidents. Content appears in unwanted contexts; brand association damaged. +- Treating syndication networks as primary distribution. The networks supplement; they do not substitute for owned and earned channels. + +The cautious-test discipline. Test syndication networks at small budget; measure beyond clicks (engagement, time-on-page, conversion); expand only if the audience quality matches expectations. + +--- + +## Search advertising for content + +Paying for clicks on content pieces via search ads. + +The shape. Less common than other paid content amplification. Usually search ads target conversion-intent queries while content takes the organic side. Some programs use search ads to drive traffic to specific high-value content. + +When it fits. + +- High-value content with clear conversion or lead-capture goals. +- Pieces targeting queries where organic ranking is hard to achieve. +- Time-sensitive content where waiting for organic ranking is not an option. + +When it fails. + +- Routine blog posts boosted via search ads. Cost-per-click usually exceeds the value of the click. +- Content that does not have clear conversion paths. Paid traffic without conversion produces sunk cost. +- Competitive queries where ad costs are high. Programs may be unable to justify cost-per-click in highly contested categories. + +The selective-discipline. Reserve search ads for content with clear conversion goals; measure paid traffic against owned-traffic comparison; high-value content only. + +--- + +## Sponsored podcast placements + +Pre-rolls, mid-rolls, sponsored segments in industry podcasts. + +The shape. Programs pay to be featured in third-party podcasts. Often via host-read endorsement; sometimes via produced ads. + +Why host-read works. The podcast host's voice carries trust signal; audiences hearing the host endorse content engage at higher rates than they engage with produced ads. Host-read endorsements are often the highest-engagement paid content amplification available. + +Selection criteria. + +- Host audience alignment with the program's target. +- Host content alignment with the program's voice. +- Per-episode reach and download numbers (with verification; some self-reported numbers are inflated). +- Cost relative to expected engagement. + +Common podcast-sponsorship failures. + +- Mismatched host. The host's audience does not match the program's audience. +- Mismatched content. The host reads the program's pitch awkwardly because the content does not fit the host's editorial voice. +- Production quality issues. Poorly produced sponsored segments damage the host's show; future sponsorship opportunities reduce. + +The host-collaboration discipline. Provide the host with substantive talking points, not scripted ad copy. Hosts read better when they have material they can adapt to their voice. The collaboration produces stronger sponsorships than rigid scripts. + +--- + +## The paid-as-substitute anti-pattern + +When paid promotion substitutes for organic validation or for owned-channel investment. + +The pattern. The program does not invest in newsletter, blog, community, or earned channels. Paid amplification produces visible reach; the program looks like it is working. Underlying owned-channel growth is minimal; the program is rented reach without owned-audience growth. + +Why it fails over time. + +- Paid costs rise. Auction dynamics on paid platforms drive prices up; the program's cost-per-engagement increases. +- Algorithm shifts. Paid platforms change targeting; previously-effective audiences become harder to reach or more expensive. +- Audience saturation. Audiences encountering the program's paid content develop ad-blindness; engagement decays. +- No compounding effect. Each paid impression is paid for separately; nothing compounds the way newsletter or blog growth compounds. + +The visibility. Programs in this state often have impressive total reach numbers but low conversion to owned-audience signals (newsletter subscriptions, account creations, community memberships). The reach is rented, not owned. + +The cure. Reallocate capacity. Reduce paid spend; increase newsletter, blog, and community investment. Recovery is multi-year; programs in paid-substitute state cannot rebuild quickly. + +--- + +## Paid amplification of low-organic-engagement content + +Boosting pieces that did not earn engagement organically. + +The pattern. A piece publishes organically. Engagement is low. The team boosts the piece anyway, reasoning that more reach will produce more engagement. + +Why it fails. Audiences who did not engage organically rarely engage when shown the same content via paid amplification. The piece's value proposition is not landing; paid amplification compounds the problem. + +The cure. Boost organically-validated content; do not substitute paid for organic validation. Pieces that did not engage organically should be evaluated for whether they should be refreshed (see `content-refresh-system`) or whether they were the wrong piece for the audience. + +Exception cases. Some content may be specifically targeted at audiences who do not see the organic version (different geographic markets, different audience segments). In those cases, paid amplification to specific audiences may be appropriate even without organic validation in the original audience. The rule is "validate within the addressable audience"; not necessarily "validate organically before any paid spend." + +--- + +## Capacity allocation for paid promotion + +Most programs benefit from a clear capacity allocation. + +Capacity guidelines. + +- 0-5% of distribution capacity to paid. Programs with strong owned and earned channels; paid is selective amplification of best organic pieces. +- 5-20% of distribution capacity to paid. Programs balancing organic-first with strategic paid amplification. +- 20-50% of distribution capacity to paid. Programs with explicit paid-amplification strategy; usually B2C brands or programs with strong conversion-funnel logic. +- 50%+ of distribution capacity to paid. Often signals under-investment in owned and earned; should be reviewed against the paid-as-substitute anti-pattern. + +The allocation review. Quarterly, review actual spend allocation. Programs drifting toward paid-heavy allocation should consider whether the drift reflects strategy or under-investment in alternatives. + +--- + +## Methodology-level choices that stay in the public skill + +The boost-organic pattern, sponsored newsletter discipline, syndication network cautious-test discipline, search advertising selective discipline, sponsored podcast host-collaboration discipline, paid-as-substitute anti-pattern, paid amplification of low-organic-engagement failure, capacity allocation guidelines. + +## Implementation choices that stay internal + +Specific paid platform configurations and bidding strategies. Specific engagement-threshold values for boost decisions. Specific newsletter sponsorship vendor selections. Specific syndication network testing protocols. Specific podcast sponsorship measurement infrastructure. The team's own conventions for paid-vs-organic capacity tradeoffs. These vary by team, budget, and platform mix. diff --git a/skills/content-migration/SKILL.md b/skills/content-migration/SKILL.md new file mode 100644 index 0000000..6f19225 --- /dev/null +++ b/skills/content-migration/SKILL.md @@ -0,0 +1,259 @@ +--- +name: content-migration +description: "Move content between platforms, domains, or URL structures while preserving SEO equity, user bookmarks, and integrations. Use this skill when planning a CMS migration, replatforming, consolidating sites, changing URL structures, or merging content from multiple sources. Triggers on content migration, replatform, CMS migration, domain migration, URL restructure, redirect map, site merge, content consolidation, migration plan, post-migration drop. Also triggers when planning a launch that involves moving existing content." +category: cross-cutting +catalog_summary: "Platform migrations with SEO equity preservation" +display_order: 2 +--- + +# Content Migration + +Move content from one platform, domain, or URL structure to another without breaking SEO, user bookmarks, or downstream integrations. Stack-agnostic. + +--- + +## When to use + +- Migrating from one CMS to another (e.g., WordPress to a headless setup) +- Consolidating multiple sites into one +- Splitting one site into multiple +- Changing URL structures +- Domain migration (one brand to another, mergers, rebrands) +- Migrating from a custom build to a platform (or vice versa) +- Content audit-driven cleanup as part of a larger move + +## When NOT to use + +- A net-new site with no existing content (no migration needed) +- Single-page edits or content updates within an existing site (use `content-and-copy`) +- Performance or technical SEO improvements without URL changes (use `seo-technical`) +- Routine content audits (use `seo-content-audit`) + +--- + +## Required inputs + +- The source: current platform, current URL structure, current content inventory +- The destination: target platform, target URL structure, target capabilities +- The reason for migration (drives priority of what to preserve) +- Constraints (timeline, budget, downtime tolerance) +- Stakeholders (SEO, content, dev, comms, support) + +--- + +## The framework: 6 phases + +Every content migration follows the same arc. Skipping a phase is how migrations go badly. + +### Phase 1: Inventory + +You can't migrate what you don't know. Build a complete map of what exists. + +For each piece of content: +- URL +- Title +- Content type (article, landing page, product, doc, etc.) +- Status (live, draft, archived, scheduled) +- Last modified +- Author or owner +- Traffic (last 12 months) +- Backlinks (top external referrers) +- Internal links pointing to it +- Embedded assets (images, video, downloads) + +Pull from: CMS export, XML sitemap, server logs, analytics, search console, backlink tool. + +The inventory is a spreadsheet. It's the source of truth for the rest of the migration. + +### Phase 2: Audit and decide + +For each piece of content, decide: + +- Keep: migrate as-is +- Update: migrate with edits (refresh, expand, fix) +- Merge: combine with another piece, redirect both old URLs to the new +- Redirect: don't migrate; redirect to a related page +- Delete: don't migrate, no redirect (use sparingly; only for clearly low-value pages) + +This is `seo-content-audit` work. The migration is the time to do it; not the time to skip it. + +For each "Update" or "Merge," document the specific changes. + +### Phase 3: Map URLs + +The URL map is the most important migration artifact. + +\| Old URL \| New URL \| Status code \| Reason \| +\|---\|---\|---\|---\| +\| /old/path \| /new/path \| 301 \| Direct equivalent \| +\| /old/page-1, /old/page-2 \| /new/merged \| 301 \| Merged content \| +\| /old/deprecated \| /related/replacement \| 301 \| Closest replacement \| +\| /old/junk \| (none) \| 410 \| Intentionally gone \| + +Rules: +- 301 (permanent redirect) for content that has a new home +- 410 (gone) for intentionally deleted content +- Avoid 404 (not found) where 410 is more accurate +- Never redirect everything to the homepage; specific is always better +- Map every URL with traffic or backlinks; lower-priority URLs can be patterned + +For domain migrations, use a 1:1 path mapping by default (`old.com/page` → `new.com/page`) with specific overrides where structure changes. + +### Phase 4: Build and stage + +Build the destination. Don't skip a staging environment. + +- Set up the new platform with the new content +- Implement the URL map (most platforms support a redirect file or rule) +- Verify a representative sample of redirects work +- Test critical user flows (signup, purchase, contact) +- Validate analytics, monitoring, and integrations +- Test from search engine perspective: robots.txt, sitemap, canonicals + +If possible, get the destination crawled by Google before the cutover, so it's already indexed when redirects flip. + +### Phase 5: Cut over + +The actual switch. Plan it like a launch (and use `launch-runbook` alongside this skill). + +Pre-cutover: +- Comms to stakeholders (date, expected impact) +- Comms to users if downtime expected +- Support team prepped for likely questions +- Lower DNS TTL the day before (1-3 days for safety) +- Backup of source platform (in case rollback is needed) + +Cutover: +- Redirect rules go live +- DNS changes go live +- New sitemap submitted to search engines +- Old sitemap removed or updated +- Internal links audited and updated to point to new URLs (where possible) +- Status page or banner if user-visible disruption + +Immediately post-cutover: +- Smoke test top 50 pages from the inventory +- Verify redirects are 301 (not 302) +- Verify search console for errors +- Watch real-time traffic for unexpected drops +- Watch error logs for missing assets, broken integrations + +### Phase 6: Monitor and recover + +The migration isn't done at cutover. The next 30-90 days reveal problems. + +Watch: +- Traffic: expect a temporary drop (10-30% is common); should recover in 4-8 weeks. A persistent drop beyond that is a problem. +- Indexing: new URLs should be crawled and indexed. Check coverage in search console. +- Rankings: track top keywords. A position drop is normal; a position cliff is a sign of a redirect or canonical problem. +- Backlinks: check that linked-from-elsewhere pages still resolve to the right destination. +- 404s: any URL getting 404s that should have been redirected? Add to the map. +- User reports: support tickets, social media. Are users finding their old links? + +Common 30-day fixes: +- Add missed redirects from 404 patterns +- Update internal links you missed +- Re-submit sitemap if indexing stalls +- Investigate and fix any crawl errors + +--- + +## Workflow + +### Step 1: Set the scope + +What's in scope? What's out? Write it down. Migrations expand if not bounded. + +### Step 2: Build the inventory + +Pull every URL, traffic, backlinks, internal links. The spreadsheet is the artifact. + +### Step 3: Decide per piece + +Keep, update, merge, redirect, delete. Document decisions. + +### Step 4: Map URLs + +The complete redirect map. Reviewed by SEO and content stakeholders. + +### Step 5: Build the destination + +In a staging environment. Real content (or representative content). Real redirects. + +### Step 6: Test + +- Sample of redirects (top 20 by traffic, top 20 by backlinks, edge cases) +- Critical flows (signup, checkout, contact) +- Analytics and monitoring +- Search-engine perspective (robots.txt, sitemap, canonicals) + +### Step 7: Cut over + +Following the cutover checklist. Have rollback ready. + +### Step 8: Monitor + +Daily for the first week. Weekly for the first month. Monthly through 90 days. + +### Step 9: Document the result + +What worked. What didn't. Lessons. (See `after-action-report`.) + +--- + +## Failure patterns + +No URL inventory. Migration team thinks they have everything. They don't. Old PDFs, archived posts, marketing landing pages with backlinks. Build the inventory. + +302 redirects instead of 301. 302 is temporary. SEO equity doesn't reliably pass. Use 301 unless you have a specific reason. + +Redirecting everything to the homepage. "We'll let users find their way." They won't. They'll bounce. Map specifically. + +Long redirect chains. /a → /b → /c → /d. Each hop loses a little equity and adds latency. Collapse to /a → /d. + +Forgetting non-HTML URLs. PDFs, images, downloads. They have URLs too. They have backlinks too. Include in the map. + +Forgetting query strings. `/page?id=123` is a different URL than `/page`. Patterns or specific maps for query string variants. + +Ignoring trailing slashes. `/page` and `/page/` are different to most servers. Pick one canonical form. Redirect the other. + +No staging. The first time the migration runs is in production. Things break. Stage and test. + +Stage that's too different from production. Different DNS, different CDN, different platform. Tests pass on staging, fail on production. Stage as close to prod as feasible. + +Leaving the source live. Two sites serving the same content. Duplicate content, split equity, user confusion. Take down the source after confirming the destination is solid. + +Leaving the source domain unrenewed. Domain expires, redirects break, traffic dies. Renew the source domain for a long time, even if you're not using it. + +Big-bang migration with no rollback plan. Something goes wrong. Now what? Plan rollback before cutover. + +Cutover during a busy period. End of quarter, holiday season, big campaign. Bad timing. Pick a quiet period. + +No comms. Users find their bookmarks broken with no warning. Some won't come back. Communicate. + +Migration as a one-time event. It's not done at cutover. Monitor for 30-90 days. Fix what surfaces. + +Treating migration as just a dev project. SEO, content, support, comms all need to be involved. Cross-functional from day one. + +--- + +## Output format + +A migration plan document includes: + +- Scope: what's in, what's out +- Inventory: the URL spreadsheet +- Audit decisions: keep, update, merge, redirect, delete +- URL map: old to new, with status codes +- Architecture: new platform setup, redirect implementation +- Cutover plan: the runbook for switch day +- Rollback plan: if it goes wrong +- Monitoring plan: what's watched, for how long +- Comms plan: internal and external +- Owners and timeline: who does what when + +--- + +## Reference files + +- [`references/migration-runbook.md`](references/migration-runbook.md): Step-by-step runbook for cutover day, including pre-flight checks, the actual switch, immediate verification, and the first 24 hours of monitoring. diff --git a/skills/content-migration/references/migration-runbook.md b/skills/content-migration/references/migration-runbook.md new file mode 100644 index 0000000..c63c24e --- /dev/null +++ b/skills/content-migration/references/migration-runbook.md @@ -0,0 +1,351 @@ +# Migration Cutover Runbook + +A step-by-step runbook for the day of a content migration cutover. Pair this with `launch-runbook` for general launch protocol. + +The runbook is read by tense people watching the clock. Optimize for clarity. + +--- + +## Roles + +Assign these before the day: + +\| Role \| Responsibility \| Person \| +\|---\|---\|---\| +\| Migration lead \| Calls the cutover, makes go/no-go decisions \| \| +\| Tech lead \| Executes DNS and redirect changes \| \| +\| QA lead \| Runs verification scripts and manual checks \| \| +\| SEO lead \| Monitors search and indexing \| \| +\| Comms lead \| Sends notifications, updates status page \| \| +\| Support lead \| Watches tickets, escalates user reports \| \| +\| Backup decision maker \| Authorizes rollback if needed \| \| + +--- + +## T-7 days: prep + +- [ ] Inventory verified complete +- [ ] URL map signed off by SEO and content +- [ ] Destination tested in staging +- [ ] Sample of 50 redirects verified +- [ ] Rollback plan documented and rehearsed +- [ ] Cutover date and window communicated to all stakeholders +- [ ] Support team briefed on common questions +- [ ] DNS TTL lowered to 300 seconds (5 minutes) +- [ ] Monitoring dashboards built and tested +- [ ] Search console verified for both old and new domains (if domain change) + +--- + +## T-1 day + +- [ ] Final inventory pull (any new content added since the freeze?) +- [ ] Final URL map review +- [ ] Backup of source platform (full, restorable) +- [ ] Test rollback procedure in staging +- [ ] Confirm everyone on the team is available during the window +- [ ] Status page draft prepared +- [ ] Internal comms draft prepared +- [ ] Customer comms draft prepared (if applicable) + +--- + +## T-2 hours + +- [ ] All stakeholders in the cutover channel (chat or call) +- [ ] Status: source platform writeable lock (no new content during cutover) +- [ ] Final smoke test on staging +- [ ] Final confirmation: GO or NO-GO + +NO-GO triggers: +- Critical bug found in destination +- Key person unavailable +- Source data integrity issue +- External factors (e.g., source platform outage) + +If NO-GO, reschedule. Don't push through. + +--- + +## T-0: cutover + +Time-box each step. If a step takes 2x its expected duration, pause and assess. + +### Step 1: Final source backup + +Time: 5-15 minutes depending on volume. + +``` +[Specific backup commands or steps] +``` + +Verify backup integrity. Continue only on success. + +### Step 2: Deploy destination to production + +If the destination has been on staging only: + +``` +[Deploy commands] +``` + +Verify the destination is responding correctly on its production address (which may not yet have DNS pointed at it). + +### Step 3: Deploy redirect rules + +The redirect rules go on whatever the source platform uses to redirect (htaccess, edge worker, CDN rule, server config). + +``` +[Deploy redirect rules] +``` + +Test 5 redirects manually: + +```bash +curl -I https://oldhost.com/path1 +curl -I https://oldhost.com/path2 +# Expected: 301 to https://newhost.com/path1 +``` + +### Step 4: DNS cutover (if domain change) + +Update DNS to point the new domain to the destination. + +``` +[DNS update steps] +``` + +Verify resolution from multiple regions: + +```bash +dig +short newhost.com @8.8.8.8 +dig +short newhost.com @1.1.1.1 +``` + +DNS propagation usually completes within minutes (with the TTL lowered earlier). Some resolvers may lag. + +### Step 5: Submit new sitemap + +``` +[Submit to search engines] +``` + +For Google: search console → sitemaps → submit. +For Bing: webmaster tools → sitemaps → submit. + +### Step 6: Update internal references + +If the source has links to itself (or hardcoded references), update the source to point at the new URLs (helps tools that haven't picked up the redirects yet). + +If the source is being decommissioned entirely, this step is moot. + +### Step 7: Update integrations + +External integrations that reference URLs: +- Email templates with absolute URLs +- Social profiles with bio links +- Partner sites with deep links +- Marketing automation +- Analytics goals (URL-based goals may break) +- Saved CRM links + +Update each. Document in the comms plan. + +--- + +## T+15 minutes: smoke test + +- [ ] Top 50 URLs from inventory each return correct status +- [ ] Redirects return 301 (not 302) +- [ ] Critical user flows work (signup, contact form, checkout if applicable) +- [ ] Search engines can crawl (robots.txt, sitemap) +- [ ] Analytics is firing on new pages +- [ ] Monitoring is showing the new endpoints + +If any check fails: triage. Fix forward if simple; rollback if complex. + +--- + +## T+1 hour: stakeholder check-in + +- [ ] Status page updated +- [ ] Internal comms sent +- [ ] Customer comms sent (if applicable) +- [ ] Support has not seen unusual ticket volume +- [ ] Real-time analytics shows expected traffic patterns + +--- + +## T+24 hours + +- [ ] Search console shows crawls of new URLs +- [ ] Search console "Indexing" tab not showing major issues +- [ ] No spike in 404s or 5xx errors in logs +- [ ] Backlink-bearing pages confirmed to redirect correctly +- [ ] Monitoring dashboards normal +- [ ] No major customer reports + +--- + +## Rollback decision criteria + +Rollback if: +- Critical functionality broken on the destination +- Significant data corruption discovered +- Security issue introduced by the migration +- Search indexing catastrophically failing (rare; usually fixable forward) + +Do NOT rollback for: +- Normal traffic dip (expected, recovers) +- Individual broken redirects (fix forward) +- Minor visual issues (fix forward) +- Slow pages (fix forward) + +Rollback procedure: + +### Step R1: Reverse DNS (if domain change) + +``` +[Revert DNS] +``` + +### Step R2: Disable redirect rules + +Take redirects offline so source URLs serve source content again. + +``` +[Disable redirects] +``` + +### Step R3: Unlock source platform + +Remove the writeable lock on the source. + +### Step R4: Restore from backup if needed + +If data corruption: restore. See `backup-and-disaster-recovery`. + +### Step R5: Comms + +- [ ] Status page updated (rolled back) +- [ ] Internal comms (rolled back, next steps) +- [ ] Customer comms if applicable (apology, next steps) + +### Step R6: Schedule retrospective + +Within 5 business days. See `after-action-report`. + +--- + +## First-week monitoring + +Daily checks: + +\| Metric \| Target \| Action if off \| +\|---\|---\|---\| +\| Top-10 page traffic \| Within 80% of baseline \| Investigate redirects, check indexing \| +\| Conversion rate \| Within 90% of baseline \| Investigate UX changes, check analytics implementation \| +\| 404 rate \| Below 1% of requests \| Add missing redirects \| +\| Crawl errors \| Decreasing \| Check robots.txt, sitemap, canonicals \| +\| Indexing rate \| Increasing toward old volume \| Submit URLs manually if stalled \| +\| Search rankings (top 20 keywords) \| No cliff drops \| Investigate canonicals, redirects, content parity \| + +--- + +## First-month monitoring + +Weekly checks: + +\| Metric \| Target \| +\|---\|---\| +\| Total organic traffic \| Recovering toward baseline (typically 4-8 weeks) \| +\| Indexed pages \| At or above pre-migration count \| +\| Backlink-pointed-to pages \| All resolving correctly \| +\| 410 vs 404 ratio \| Pages that should be gone return 410, not 404 \| + +--- + +## After 90 days + +- [ ] Full performance review vs pre-migration baselines +- [ ] Document what worked, what didn't (after-action report) +- [ ] Decommission source platform if not already done +- [ ] Renew source domain (long-term, even if not in use, to preserve redirects) +- [ ] Archive the migration documentation for future reference + +--- + +## Common surprises + +Backlinks pointing to URLs not in inventory. Old marketing pages, archived posts, removed-but-still-linked content. Add to the map after cutover. + +Trailing slash inconsistencies. Server treats `/page` and `/page/` differently. One redirects, the other 404s. Fix with a normalizing redirect. + +Search engines slow to update. Old URLs still appear in search for weeks. Normal. Don't redirect to homepage to "speed it up." + +Analytics goals broken. URL-based goals don't match new URLs. Update the goals; backfill if possible. + +Hardcoded absolute URLs in email templates. Old links in transactional emails. Update templates. + +Schema.org or canonical tags pointing wrong. Crawlers follow canonical even after redirects. Verify canonical tags on the destination point to the destination. + +Sitemap caching. Some platforms cache sitemaps aggressively. Force a refresh. + +robots.txt forgot the new sitemap. Add the new sitemap to robots.txt. + +--- + +## Post-cutover comms template + +### Internal (to team) + +Subject: Migration cutover complete + +``` +The migration to [new platform/URL/etc.] is complete as of [time]. + +Status: +- [N] redirects in place +- All critical flows verified +- Monitoring shows expected traffic patterns + +We'll watch closely over the next 24 hours and the first week. Report any issues in [channel]. + +Next steps: +- [Specific monitoring action] +- [Specific follow-up] + +Thanks to everyone who made this happen. +``` + +### External (to users, if applicable) + +Subject: We've moved [or rebranded, or restructured] + +``` +Hi [name], + +[Brief reason for the change.] + +What this means for you: +- [Specific user-facing change 1] +- [Specific user-facing change 2] + +Old links should redirect automatically. If you find a broken link, please let us know at [contact]. + +Thanks for your patience as we make this transition. +``` + +--- + +## Document the result + +Within a week of cutover, write up: + +- What was migrated +- What worked +- What broke and how it was fixed +- What we'd do differently +- Lessons for the next migration + +This becomes input to `after-action-report` and to future migration playbooks. diff --git a/skills/content-refresh-system/SKILL.md b/skills/content-refresh-system/SKILL.md new file mode 100644 index 0000000..a7f8fa1 --- /dev/null +++ b/skills/content-refresh-system/SKILL.md @@ -0,0 +1,255 @@ +--- +name: content-refresh-system +description: "Systematic content refresh discipline. Quarterly audits, refresh prioritization (which pieces, when, how deep), refresh-vs-merge-vs-delete decisions, the lifecycle that distinguishes intentional refresh from set-and-forget decay. Builds on the refresh sections of pillar-content-architecture and editorial-qa with a program-level discipline. Triggers on content refresh, content decay, content audit, refresh prioritization, content lifecycle, refresh strategy, traffic decay, ranking drop, content freshness, evergreen content, content maintenance. Also triggers when traffic is eroding silently across an aging content library, when teams cannot decide which pieces to refresh, or when refresh work is happening but the impact is unclear." +category: content +catalog_summary: "Systematic content refresh: quarterly audits, refresh prioritization, refresh-vs-merge-vs-delete decisions, the lifecycle discipline that distinguishes intentional programs from set-and-forget decay" +display_order: 10 +--- + +# Content Refresh System + +A senior editorial leader's playbook for systematic content refresh. The discipline that distinguishes intentional refresh programs from set-and-forget decay, and the prioritization framework that prevents both over-refresh (refresh-everything-on-calendar) and under-refresh (refresh-nothing-until-traffic-collapses). + +Content decays. Search behavior shifts; SERP intent reshapes; facts go stale; competitors publish stronger pieces; the brand's own positioning evolves past what older pieces represent. Programs that ignore this reality watch traffic erode silently across the library. Programs that overreact (rewriting everything on calendar) burn editorial capacity that should be producing new flagship work. The discipline is in the middle: refresh what matters when signals say so, and document the decisions so the program is auditable. + +This skill is the program-level refresh discipline across the whole content library. It builds on `pillar-content-architecture`'s hub-level refresh consideration (refresh as ONE consideration in hub design) and `editorial-qa`'s pre-publish quality gate (this skill is post-publish lifecycle, not pre-publish QA). Together those skills cover content quality at the moments quality decisions get made; this skill covers the moments between, when content is in the field and decaying or holding. + +The voice is the senior editorial leader who has watched refresh programs fail in both directions and who has shipped the systems that produced durable refresh discipline. + +When to use this skill: building a refresh program from scratch, auditing why refresh work is happening but traffic is not responding, designing the prioritization that keeps refresh tractable across a 200-piece or 2,000-piece library, or fixing a refresh program that is eating editorial capacity without clear results. + +--- + +## What this skill covers + +This skill spans the post-publish lifecycle of content. The content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is HUB scope; refresh appears as ONE consideration in hub design. +- `content-brief-authoring` is per-piece scope at production time. +- `content-and-copy` is execution scope at production time. +- `editorial-qa` is gate scope: pre-publish verification. +- `content-refresh-system` (this skill) is lifecycle scope: program-level refresh discipline across the whole content library, after pieces are in the field. + +The audience: editorial leads, content directors, content ops managers, in-house teams running content libraries of 50-5,000+ pieces, agencies maintaining client content programs across years. + +What is not in scope: writing the refreshed pieces themselves (that is `content-and-copy`), the brief that drives the refresh (that is `content-brief-authoring`), the pre-publish gate on the refreshed piece (that is `editorial-qa`). This skill is the prioritization and lifecycle discipline; the actual content work plugs into the existing skills. + +--- + +## Refresh-everything vs refresh-nothing vs triaged-refresh + +The keystone framing. Two failure modes plus the discipline. + +Refresh-everything. Full rewrites on calendar. Every piece gets a refresh on a 12-month or 18-month rotation regardless of signals. Output: editorial capacity consumed by maintenance work that often was not needed, while strong pieces are touched into worse versions and weak pieces consume the same effort as flagship pieces. Cost: opportunity cost on new flagship production; maintenance fatigue in the editorial team; some pieces that were performing well get diluted by unnecessary edits. + +Refresh-nothing. Set-and-forget. Pieces ship and never get touched again. Output: traffic decays silently across the library as facts go stale, competitors publish stronger pieces, and SERP intent shifts away from the piece's framing. The library's compounding value erodes invisibly until an algorithm update or a competitor's flagship piece exposes the rot. Cost: cumulative traffic loss that nobody attributes to refresh failure because the loss is gradual; trust loss when readers find stale facts in pieces they expected to be current. + +Triaged-refresh. Refresh what matters when signals say so. Audit cadence catches decay early; prioritization concentrates effort on high-value-decaying pieces; weak pieces get refresh-vs-merge-vs-delete dispositions instead of automatic refresh; the program is auditable because every refresh decision was a deliberate response to specific signals. Output: editorial capacity preserved for new production; the library's compounding value protected; refresh work is seen, understood, and measured. + +The litmus test. Ask of any refresh decision: what signal triggered this refresh, what depth of refresh did the signal warrant, what outcome do we expect, and how will we measure whether the refresh worked? If the answer is "it was scheduled" or "we always refresh after 12 months," the program is on calendar rather than on signal. + +--- + +## Refresh signals + +Five categories of signal that trigger refresh consideration. Pieces that show no signals do not need refresh; pieces that show multiple signals are higher priority. + +Traffic decay. Organic traffic to the piece is trending down over a 90+ day window beyond the seasonal baseline. The decay can be slow (5-10% over a year) or sharp (40%+ in a month after an algorithm update). Slow decay typically indicates content drift; sharp decay typically indicates external change. + +Ranking drops. The piece is losing position on its target keywords. Drops from page 1 to page 2-3 are particularly consequential; drops within page 1 (position 3 to position 7) are less so but still tracked. Persistent ranking drops over 30+ days indicate a real shift, not search-result volatility. + +Factual staleness. The piece contains statistics, references, examples, or claims that are dated. A 2018 stat in a 2026 piece on a fast-moving topic is staleness; a piece that references defunct products or platforms is staleness; a piece that uses pre-shift framings ("AI is starting to influence search" in 2026) is staleness. + +SERP intent shift. The dominant SERP format for the target keyword has changed. The piece was written when articles ranked for the keyword; now the SERP wants product comparisons, video, or AI-overview-style answers. The piece may still rank but increasingly for the wrong reason. + +Content drift. The piece's positioning no longer matches the brand's current positioning. Voice has evolved; the brand's POV on the topic has sharpened or shifted; the piece reads as the brand-of-three-years-ago. Internal signal more than external; readers may not notice but the team will. + +The audit. Every piece in the library can be characterized by which signals it shows. Pieces with zero signals are stable; pieces with one or two signals warrant attention; pieces with three or more signals are typically in active decay. + +Detail in [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md). + +--- + +## The audit cadence + +How often to look. Two cadences with different tradeoffs. + +Quarterly audit. A formal review of the content library every 90 days. The team pulls traffic, ranking, and recency data; reviews each piece against the signals; assigns dispositions (refresh, merge, delete, or leave alone). Output: a refresh queue with priorities and a backlog of merge/delete decisions. + +- Strength: predictable, auditable, fits naturally into editorial calendar planning. +- Weakness: 90-day delay in detecting sharp decay; piece that lost 40% traffic in week 2 of a quarter is in decay for 75 days before the audit catches it. + +Continuous monitoring. Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. Pieces that lose more than X% traffic in Y days trigger a review. + +- Strength: catches sharp decay early; allows fast response to algorithm updates. +- Weakness: requires monitoring infrastructure; can produce alert fatigue if thresholds are too tight; misses slow decay that does not cross thresholds. + +The hybrid pattern. Most strong refresh programs run both. Quarterly audits catch slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. The two cadences cover different failure modes. + +Detail in [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md). + +--- + +## Refresh prioritization + +Prioritization is the discipline. Most libraries have more pieces showing signals than the team has capacity to refresh. Prioritization concentrates effort on the pieces where refresh produces the most value. + +The 2x2 matrix: piece value (high vs low) crossed with traffic state (decaying vs stable). + +High-value, decaying. Top priority. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. Refresh these first; the traffic loss compounds and the lost equity is hard to recover. + +High-value, stable. Monitor; do not refresh proactively. Pieces that are performing should not be touched without clear signal; refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. + +Low-value, decaying. Audit for merge or delete. Pieces with low traffic that are decaying further are usually candidates for merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling). Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. + +Low-value, stable. Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. Detail in [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md). + +--- + +## Refresh depth options + +Not every refresh is the same kind of work. Four depth levels. + +Light edit. Update statistics, replace dead links, fix factual errors, swap dated examples. Keeps the piece's structure and argument intact. Time investment: 30-90 minutes per piece. Use when the piece is structurally sound and only the surface details have aged. + +Substantial revision. Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that emerged after the piece was written. Time investment: 2-4 hours per piece. Use when the piece's structure is sound but specific sections have become weak. + +Full rewrite. Keep the URL and topic; rewrite the piece end-to-end. Time investment: similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. Use when the piece's structure no longer fits the current SERP intent or the brand's positioning has shifted enough that the piece needs to be re-conceived. + +Structural redesign. Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Time investment: a multi-piece project. Use when refresh is part of a larger structural change in the content library (a hub being rebuilt, a category being consolidated). + +The depth-decision discipline. Match depth to signal strength. Sharp decay or major SERP intent shift may warrant full rewrite; slow decay with stale stats may warrant only a light edit. Treating every refresh as a full rewrite is refresh-everything energy in a different shape. + +Detail in [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md). + +--- + +## Refresh vs merge vs delete decisions + +Not every piece in decay should be refreshed. Three dispositions. + +Refresh. The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +Merge. Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +Delete. The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. Delete and redirect to the closest sibling or, if no sibling exists, to the relevant hub or category page. + +The decision criteria. Refresh when the piece has demand and a path back. Merge when authority is being split. Delete when there is no path forward and the piece is not worth maintaining. + +The under-recognized failure mode: refreshing pieces that should have been merged or deleted. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. + +Detail in [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md). + +--- + +## Refresh execution patterns + +Who does the work, how it ships. + +Ownership. A single owner per refresh, not a committee. The owner is accountable for the outcome and runs the work through to ship. Refreshes that pass through multiple hands without an accountable owner often get partially done and then stall. + +Editorial integration. Refreshes typically run through the same editorial workflow as new pieces (brief, draft, edit, QA gate, publish), scaled to the depth chosen. A light edit may skip the brief and go straight to edit; a full rewrite goes through every step. + +Capacity allocation. Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff: a team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. The split varies by program maturity (older libraries often need 30-40% refresh allocation; newer libraries may need 5-10%). + +Refresh batching. Some teams batch refresh work into dedicated weeks or sprints; others integrate one refresh per week into the steady-state production cadence. Batching produces focus but interrupts new production; integration sustains new production but slows refresh velocity. Either works; the failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence. + +Detail in [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md). + +--- + +## Re-promotion after refresh + +Refreshed pieces need to signal to search engines and audiences that they have been updated. + +To search engines. Update the modified date in schema markup. Update the published-or-modified-date in the visible metadata. Submit the URL for re-crawl through Search Console. Some teams update the URL minimally (e.g., adding a year to the slug for evergreen pieces), but URL changes carry redirect risk and should be reserved for substantial-revision or full-rewrite refreshes. + +To audiences. Re-share the refreshed piece on the channels where the original landed: newsletter, social, syndication partners. Treat the refresh as a publication event, not as silent maintenance. The re-promotion is part of the refresh's value proposition: the piece earns new attention as well as preserved search position. + +Internal linking refresh. Pieces that link to the refreshed piece may benefit from anchor-text updates if the refreshed piece's positioning shifted. Sister pieces that should now link to the refreshed piece can be updated to do so. + +The refresh that nobody tells anyone about. A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement. + +Detail in [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md). + +--- + +## Refresh tracking and effectiveness measurement + +The discipline that prevents refresh-theater: tracking which refreshes worked, which did not, and what the patterns reveal. + +Per-refresh tracking. Each refresh is logged with: the signals that triggered it, the depth chosen, the date shipped, the predicted outcome, the actual outcome at 30 days and 90 days post-refresh. The log is the refresh program's evidence base. + +Effectiveness metrics. The primary metrics depend on the refresh's purpose. Traffic-decay refreshes track post-refresh traffic recovery; ranking-drop refreshes track post-refresh ranking position; content-drift refreshes track post-refresh engagement metrics (time on page, return visits) more than search metrics. + +Pattern detection. The log reveals patterns over time. Some signal types produce reliable recovery; others rarely produce recovery and indicate a deeper problem (the topic itself is dying; the brand's positioning on the topic is wrong; competitors are too strong to displace). The patterns inform program-level decisions. + +The refresh-that-did-not-work review. Refreshes that did not produce the expected recovery should get a structured review. Was the depth wrong? Was the merge or delete decision the right disposition that we did not take? Did the underlying problem turn out to be something refresh cannot fix? + +Detail in [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-refresh-failures.md`](references/common-refresh-failures.md). + +- "We refresh every piece annually and traffic is still declining." Refresh-everything pattern; the calendar-based work is not catching the actual decay signals. +- "We have not touched the library in 18 months and traffic has eroded 30%." Refresh-nothing pattern; the decay went uncaught. +- "We refresh pieces but the traffic does not come back." Wrong disposition; the pieces were merge or delete candidates, not refresh candidates. +- "Our refresh queue is 200 pieces deep and growing." No prioritization; everything that shows any signal goes in the queue regardless of value. +- "We refreshed a flagship piece and traffic dropped." Refresh damaged a piece that was performing; the refresh was triggered by calendar rather than signal. +- "The team is exhausted from refresh work." Capacity allocation is wrong; either refresh ratio is too high, or new production is suffering, or the depth choices are over-investing. +- "We do not know if our refreshes are working." No tracking; refresh work happens but its effectiveness is invisible. +- "Some pieces always get refreshed; others never do." The signal triage is informal and inconsistent; some pieces are getting attention because they are visible, not because they are most decayed. +- "We refreshed a piece and forgot to re-promote it." Refresh-without-re-promotion; the piece's modified date updated but no audience or channel re-engagement happened. +- "Our quarterly audit catches things 75 days late." Quarterly cadence alone is missing sharp decay; add continuous monitoring for traffic-loss thresholds. +- "We refresh sister pieces but the hub orchestration is unchanged." Pieces refreshed in isolation when the hub-level architecture also needed updating; coordinate with `pillar-content-architecture` discipline. + +--- + +## The framework: 12 considerations for content refresh + +When designing or auditing a refresh program, walk these 12 considerations. + +1. Triaged-refresh, not refresh-everything or refresh-nothing. Refresh on signal, not on calendar. +2. Signal categories named. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. +3. Audit cadence committed. Quarterly audit plus continuous monitoring; both running. +4. Prioritization matrix applied. High-value-decaying first; low-value-decaying audited for merge or delete. +5. Depth matched to signal. Light edit, substantial revision, full rewrite, structural redesign. +6. Disposition decided per piece. Refresh, merge, or delete; not all decay warrants refresh. +7. Single ownership per refresh. Accountable owner runs the work to ship. +8. Capacity allocation explicit. Refresh ratio of editorial capacity is a real number, planned. +9. Re-promotion built into the workflow. Schema, visible date, search-engine resubmit, audience re-share. +10. Per-refresh tracking. Signals, depth, outcomes logged for pattern detection. +11. Effectiveness measurement. Recovery tracked at 30 and 90 days; patterns inform program decisions. +12. The-refresh-that-did-not-work review. Failed refreshes get structured review; lessons compound. + +The output of the framework is a refresh program that is auditable, capacity-respecting, and producing visible value for the library's compounding equity. + +--- + +## Reference files + +- [`references/refresh-signals-checklist.md`](references/refresh-signals-checklist.md) - Five signal categories with detection patterns. Traffic decay, ranking drops, factual staleness, SERP intent shift, content drift. The audit pattern that surfaces signals across the library. +- [`references/audit-cadence-patterns.md`](references/audit-cadence-patterns.md) - Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, alert-threshold design. +- [`references/refresh-prioritization-matrix.md`](references/refresh-prioritization-matrix.md) - 2x2 matrix with quadrant strategies. High-value-decaying as top priority; low-value-decaying audited for merge or delete; the discipline of NOT refreshing the high-value-stable quadrant. +- [`references/refresh-depth-decision.md`](references/refresh-depth-decision.md) - Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, depth-creep anti-pattern. +- [`references/refresh-vs-merge-vs-delete.md`](references/refresh-vs-merge-vs-delete.md) - Disposition criteria. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged. +- [`references/refresh-execution-patterns.md`](references/refresh-execution-patterns.md) - Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. +- [`references/re-promotion-after-refresh.md`](references/re-promotion-after-refresh.md) - Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. +- [`references/effectiveness-measurement.md`](references/effectiveness-measurement.md) - Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. +- [`references/common-refresh-failures.md`](references/common-refresh-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: refresh is content's immune system + +A content library is a long-running system. The pieces in it interact with search algorithms that change, audiences that shift, brands that evolve, and competitors that publish. Set-and-forget treats the library as a static asset and watches it decay. Refresh-everything treats it as a maintenance project and burns capacity that should be producing new flagship work. + +The discipline is the immune system: signals are detected early, prioritization concentrates effort where the value is highest, depth matches signal strength, dispositions include merge and delete (not just refresh), and the work is tracked so the program learns. Programs that run this discipline preserve the library's compounding value. Programs that do not watch the library erode and discover the loss only when an algorithm update or a competitor's flagship piece exposes how far the rot has spread. + +When in doubt about whether a refresh program is ready, ask: does the program detect signals, prioritize on value, match depth to signal, decide between refresh and merge and delete, allocate capacity explicitly, re-promote the refreshed pieces, and track effectiveness? If yes to all of those, the program is real. If no to any, the gap is where decay will compound. diff --git a/skills/content-refresh-system/references/audit-cadence-patterns.md b/skills/content-refresh-system/references/audit-cadence-patterns.md new file mode 100644 index 0000000..4667597 --- /dev/null +++ b/skills/content-refresh-system/references/audit-cadence-patterns.md @@ -0,0 +1,162 @@ +# Audit cadence patterns + +Quarterly audit vs continuous monitoring vs hybrid. Tradeoffs, integration patterns, and alert-threshold design. + +The audit cadence determines how quickly decay signals turn into refresh decisions. Programs that audit annually catch decay 9-12 months late; programs that monitor continuously without an audit layer catch sharp decay early but miss the slow-drift and content-drift signals that need human review. The hybrid pattern is the standard for mature programs. + +--- + +## The quarterly audit + +A formal review of the content library every 90 days. + +The mechanics. + +- The team blocks 1-3 days per quarter for the audit. +- Pull data: traffic per URL over the last 90 and 180 days, rankings on target keywords, last-modified dates, target-keyword SERP samples. +- Run each piece through the five-signal checklist (see `refresh-signals-checklist.md`). +- Assign each piece a disposition: refresh (with depth), merge, delete, monitor, no action. +- Output a refresh queue prioritized by the prioritization matrix. + +Strengths. + +- Predictable. The team knows when audit work happens and can plan around it. +- Auditable. Each quarter's decisions are documented; patterns over multiple quarters become visible. +- Comprehensive. The signal types that need human judgment (content drift, SERP intent shift) get reviewed; continuous monitoring cannot detect these without human eyes. +- Capacity-aware. Audit work happens at known times; new production schedules can flex around it. + +Weaknesses. + +- 90-day delay in detecting sharp decay. A piece that lost 40% traffic in week 2 of the quarter is in decay for 75 days before the audit catches it. +- Heavy lift. Auditing 200-2,000 pieces in 1-3 days requires structured tooling; teams without tooling burn out. +- Focus on the audit moment can crowd out continuous attention. "We will catch it next quarter" becomes the answer to issues that warrant immediate response. + +--- + +## Continuous monitoring + +Automated detection of traffic and ranking shifts with alerts when thresholds are crossed. + +The mechanics. + +- Define thresholds for sharp decay: e.g., traffic drop of 25%+ in 14 days, ranking drop of 5+ positions in 14 days. +- Automated monitoring runs daily or weekly, comparing current data to baseline. +- Alerts route to the editorial owner of the affected piece (or to a refresh queue triage owner if pieces do not have individual owners). +- Triage decides whether the alert warrants immediate refresh, addition to the next quarterly audit's queue, or dismissal as noise. + +Strengths. + +- Catches sharp decay early. Algorithm-update fallout, technical regressions, and dramatic SERP intent shifts get attention within days, not 75-90 days. +- Allows fast response. A piece that lost 50% traffic on a specific date can be investigated while the cause is fresh. +- Reduces audit-day exhaustion. Sharp signals are handled in real time; the quarterly audit focuses on the slower signals. + +Weaknesses. + +- Requires monitoring infrastructure. Teams need rank tracking, traffic monitoring, and alerting that can route to specific URL owners. +- Alert fatigue if thresholds are too tight. Daily alerts on minor fluctuations train the team to ignore the alerts; thresholds need calibration. +- Misses slow decay. Pieces declining 5-8% per quarter never cross thresholds; they accumulate decay invisibly. The quarterly audit is what catches these. +- Misses non-traffic signals. Continuous monitoring on traffic and rankings cannot detect content drift or factual staleness. + +--- + +## The hybrid pattern + +Most strong refresh programs run both. The quarterly audit catches slow decay, content drift, and pieces that are stable but no longer match the brand's current positioning. Continuous monitoring catches sharp decay and algorithm-update fallout. + +Integration shape. + +- Continuous monitoring runs daily or weekly with a small set of well-calibrated thresholds. +- Quarterly audit runs the full signal checklist on the whole library. +- Pieces that triggered continuous-monitoring alerts during the quarter get fast-track disposition; the quarterly audit reviews the rest. +- The continuous-monitoring log feeds into the quarterly audit so the team can see whether thresholds are calibrated correctly (too many false alerts, too few real ones). + +Capacity split. A typical hybrid pattern might allocate 5-10% of editorial capacity to continuous-monitoring response (a few hours per week) and a concentrated 1-3 days per quarter to the audit. The split scales with library size and decay rates. + +--- + +## Alert-threshold design + +Calibrating continuous-monitoring thresholds is its own discipline. + +Threshold goals. + +- High precision: when the threshold is crossed, the alert is usually a real signal, not noise. +- Reasonable recall: catches the sharp-decay events that matter; does not need to catch every minor fluctuation (the audit catches those). +- Sustainable cadence: alerts arrive at a frequency the team can triage without fatigue. + +Threshold patterns that work. + +- Traffic: 25%+ drop in 14 days, sustained over 21 days. The sustainment requirement filters volatility. +- Ranking: 5+ position drop on a tracked keyword, sustained over 14 days. Single-day drops are noise; sustained drops are signal. +- Indexing: any unexpected change in indexed status (200 to non-200 status, sudden noindex tag, sudden disappearance from index). These are usually technical regressions and warrant immediate attention. +- Schema validation: schema breaking or warnings appearing on a piece that previously validated cleanly. Often indicates a CMS update or template change. + +Threshold patterns that fail. + +- 10% traffic drop alerts produce far too many false positives; teams stop reading the alerts. +- Single-day rank drop alerts produce noise; SERP volatility within a few positions is normal. +- Aggregate-traffic alerts on whole categories rather than per-URL alerts hide which specific pieces are decaying. + +Threshold tuning. Run alerts in shadow mode for 4-6 weeks before committing. Track whether alerts correspond to real signals on review. Adjust thresholds based on the precision-recall observed. + +--- + +## When to audit more frequently + +Some programs warrant more than quarterly audits. + +Programs in active rebuild. Content libraries undergoing structural redesign or hub reorganization benefit from monthly audits during the rebuild phase. The signal volume is higher and the decisions need faster cycle time. + +Post-algorithm-update period. In the 30-90 days after a major algorithm update, signal volume spikes. Some teams run a special audit at the 30-day post-update mark in addition to the regular quarterly cadence. + +Programs with rapid topic evolution. Topics that move quickly (AI tools, evolving regulatory environments, tactical playbooks in fast-moving fields) may benefit from monthly factual-staleness checks even when traffic and ranking signals are stable. + +--- + +## When to audit less frequently + +Some programs can run on lighter cadence. + +Small libraries (under 50 pieces) with stable performance. Bi-annual audits may be sufficient if continuous monitoring is in place and the library has shown stable decay rates over multiple cycles. + +Libraries dominated by evergreen pieces. When the topical mix is heavily evergreen (foundational concepts that move slowly), quarterly audits may produce limited signal volume. Combine with continuous monitoring; reduce audit frequency. + +The discipline. Cadence should match decay rate, not be fixed by convention. Programs that decay quickly need faster cadence; programs that decay slowly can run longer audit cycles. + +--- + +## Audit anti-patterns + +Annual audit as the only cadence. Catches decay 9-12 months late; the library is in significant erosion before the audit runs. + +Continuous monitoring without quarterly audit. Catches sharp decay; misses slow decay, content drift, and SERP intent shifts that need human review. + +Audit happening but no follow-through. The team runs the audit, produces a queue, then loses momentum on actually executing the refreshes. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +Audit without prioritization. The output is a list of every piece showing any signal, with no value-weighted prioritization. The team does the cheapest refreshes first regardless of value, leaving high-value-decaying pieces in the backlog. + +Audit without depth assignment. Pieces are tagged "refresh" without specifying depth. Refresh execution defaults to whatever depth the team has time for, which is often light edit even when substantial revision is needed. + +--- + +## Audit governance + +Who runs the audit, who approves dispositions, how the queue routes to execution. + +Single audit owner. A specific person runs the audit each quarter, accountable for signal quality and disposition recommendations. + +Disposition review. Refresh, merge, and delete dispositions are reviewed by a content lead or director. Delete dispositions in particular need approval because they are irreversible (pieces deleted and not redirected can lose authority that did not need to be lost). + +Queue routing. The refresh queue routes to specific editorial owners based on capacity, expertise, and the depth of work required. Light edits route to anyone with capacity; full rewrites route to the writer or editor best matched to the topic. + +Audit log. Each quarter's audit, dispositions, and outcomes are logged. The log feeds the next quarter's review (which dispositions actually shipped, which produced recovery, which patterns are emerging). + +--- + +## Methodology-level choices that stay in the public skill + +The quarterly audit mechanics, continuous monitoring mechanics, hybrid pattern, alert-threshold design principles, audit-cadence variations, audit governance shape, and the anti-patterns. + +## Implementation choices that stay internal + +Specific monitoring tools the team uses (rank trackers, analytics platforms, alerting systems). Specific threshold values calibrated to the team's data. Specific dashboards and reporting templates. Specific ticketing or queue systems for refresh routing. Specific automation scripts that pull data into audit-ready formats. The team's own audit-day rituals and tooling. These vary by team, tooling, and library size. diff --git a/skills/content-refresh-system/references/common-refresh-failures.md b/skills/content-refresh-system/references/common-refresh-failures.md new file mode 100644 index 0000000..df86203 --- /dev/null +++ b/skills/content-refresh-system/references/common-refresh-failures.md @@ -0,0 +1,169 @@ +# Common refresh failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear across programs of different sizes, library ages, and editorial team compositions; the underlying causes are rarely about people and almost always about discipline, prioritization, or measurement gaps. + +--- + +## Failure 1: Refresh-everything-on-calendar + +Symptom. Every piece gets refreshed on a 12-month or 18-month rotation regardless of signals. Editorial capacity is consumed by maintenance work that often was not needed. + +Diagnosis. The program treats refresh as a calendar event rather than as a signal-driven decision. Pieces that were performing get touched into worse versions; pieces that were decaying are scheduled for refresh whenever their rotation comes up rather than when the decay signals warrant. + +Cure. Replace calendar-driven refresh with the prioritization matrix and the signal-driven audit cadence. Refresh on signals; leave stable pieces alone. + +Capacity recovery. Programs that abandon refresh-everything typically recover 30-50% of their refresh capacity for higher-value work or for new production. + +--- + +## Failure 2: Set-and-forget + +Symptom. The team has not touched the library in 18+ months. Traffic has eroded across the library; the team is uncertain how much loss is from refresh failure vs other causes. + +Diagnosis. The program lacks both audit cadence and continuous monitoring. Decay accumulates silently because no system is detecting it. + +Cure. Establish the hybrid audit pattern: quarterly audit plus continuous monitoring. The first audit will surface a large queue (typical when starting from set-and-forget); the queue should be triaged by the prioritization matrix and worked through over multiple quarters rather than tackled all at once. + +--- + +## Failure 3: Refresh that should have been merge or delete + +Symptom. The team spends hours refreshing pieces that even at their best will not produce meaningful recovery. The same pieces appear in queue across multiple audits. + +Diagnosis. The disposition decision was wrong. Refresh was the default disposition because it felt less destructive than merge or delete; the actual right disposition was merge into a stronger sibling or delete with redirect. + +Cure. Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. Train the audit owner on the disposition decision flow (see `refresh-vs-merge-vs-delete.md`). + +--- + +## Failure 4: Unprioritized refresh queue + +Symptom. The refresh queue is 200 pieces deep and growing. The team works through the queue in order of arrival or in order of "easiest first" rather than by value. + +Diagnosis. No prioritization matrix is being applied. Every piece showing any signal goes in the queue regardless of value. + +Cure. Apply the 2x2 matrix (value × traffic state). Queue entries get tagged by quadrant. Work focuses on high-value-decaying first; low-value-decaying gets disposition decisions (often merge or delete) rather than refresh; stable quadrants get monitor or no action. + +--- + +## Failure 5: Refresh-on-stable-piece regression + +Symptom. A flagship piece was performing well. The team refreshed it because it was the next piece in the rotation. After the refresh, traffic dropped 30% and rankings dropped 5 positions. + +Diagnosis. Refresh-everything-on-calendar damaged a stable piece. The refresh introduced changes that shifted the SERP signals or the piece's structural fit; the new version performs worse than the original. + +Cure. Stop refreshing high-value-stable pieces by default. Pieces in this quadrant get monitor disposition unless content drift is severe enough to warrant the regression risk. When refreshing a stable piece is genuinely warranted, plan for fast revert if regression occurs. + +Recovery. Some refresh regressions can be partially reversed by going back to a closer-to-original version of the piece. Some cannot. The lesson informs future stable-piece refresh decisions. + +--- + +## Failure 6: Capacity overcommitment + +Symptom. The team is exhausted from refresh work. New-piece production is suffering. The team complains of refresh fatigue. + +Diagnosis. Capacity allocation to refresh is too high (or new-production commitments are too high; the result is the same). The team is being asked to do more total work than capacity allows. + +Cure. Right-size the allocation. Reduce refresh queue intake by tightening prioritization (only highest-value items enter the queue); or reduce new-production commitments; or temporarily increase capacity. The status quo is unsustainable. + +Sustainability check. Capacity is real. Programs that pretend capacity is infinite produce burnout, quality drift, and team turnover. The capacity audit (see `refresh-execution-patterns.md`) is what catches this before burnout. + +--- + +## Failure 7: Effectiveness invisible + +Symptom. "We do not know if our refreshes are working." Refresh work happens but its effectiveness is not tracked or reviewed. + +Diagnosis. No per-refresh tracking is in place. The program runs without learning data. + +Cure. Establish the minimum log (see `effectiveness-measurement.md`). Backfill the log for recent refreshes if possible. Establish 30-day and 90-day measurement windows. Run quarterly pattern-detection reviews. + +Adoption. Logging adds overhead. Programs that resist logging often discover later that the program's effectiveness has been declining for quarters and they cannot tell why because the data was not captured. The overhead of logging is small compared to the cost of running the program blind. + +--- + +## Failure 8: Inconsistent refresh attention + +Symptom. Some pieces always get refreshed; others never do. The pattern correlates with which writers prefer which topics, not with which pieces need refresh most. + +Diagnosis. The signal triage is informal and inconsistent. Pieces are getting attention because they are visible to certain people, not because they are most decayed. + +Cure. Formalize the audit so signal detection is data-driven rather than memory-driven. The matrix and the audit log force visibility on the whole library, not just on the pieces individual team members happen to think of. + +--- + +## Failure 9: Refresh-without-re-promotion + +Symptom. Refreshes ship. Modified dates update. The team waits for traffic recovery. Recovery is marginal at best. The team concludes refresh does not work. + +Diagnosis. Re-promotion was skipped. Search engines saw the modified date but audiences did not engage; the recovery curve that re-promotion typically produces did not happen. + +Cure. Build re-promotion into the workflow as a non-skippable step. Match re-promotion intensity to refresh depth (see `re-promotion-after-refresh.md`). The refresh is not "done" when published; the refresh is "done" when re-promotion has executed. + +--- + +## Failure 10: Audit without follow-through + +Symptom. The team runs the quarterly audit; produces a queue; the queue largely sits unworked; the next quarter's audit shows the same pieces in queue. + +Diagnosis. No owner-of-owners is keeping the queue moving. The audit becomes a documentation exercise rather than a refresh-driving exercise. + +Cure. Assign an owner-of-owners role for the refresh program as a whole. Their job is queue movement, escalation of stalled refreshes, and program-level reporting. Without this role, even good audits do not produce execution. + +--- + +## Failure 11: Quarterly cadence too slow for sharp decay + +Symptom. The quarterly audit catches a piece in significant decay. The traffic loss has been accumulating for 75 days before the audit caught it. The recovery is harder because the decay has compounded. + +Diagnosis. Quarterly cadence alone is missing sharp decay. The lag between decay and detection is too long. + +Cure. Add continuous monitoring for traffic-decay and ranking-drop thresholds. Sharp decay alerts route to fast-track triage; the quarterly audit focuses on slower signals that continuous monitoring cannot detect (content drift, factual staleness, SERP intent shift). + +--- + +## Failure 12: Refresh in isolation when hub orchestration changed + +Symptom. Pieces are refreshed individually but the hub-level architecture also needed updating. The refreshes ship; the hub-level decay continues because the architecture problem was unaddressed. + +Diagnosis. Piece-level refresh is being done without coordination with hub-level architecture. Some refresh queues need to escalate to structural-redesign disposition rather than be addressed at piece level. + +Cure. Coordinate with `pillar-content-architecture` discipline. When piece-level refresh is bumping against architecture-level issues, escalate to a structural-redesign project. Some refresh attempts cannot succeed without the hub-level work. + +--- + +## Failure 13: Stalled refreshes accumulating + +Symptom. The refresh queue contains zombie items: pieces assigned months ago that have not shipped and are not progressing. Everyone knows they are stalled; nobody is removing them. + +Diagnosis. No stalled-refresh recovery process. Refreshes that get stuck stay stuck because there is no review mechanism to escalate or reassign. + +Cure. Build stalled-refresh review into each quarterly audit. Refreshes that have been in queue more than two cycles get reviewed: reassign owners, re-scope depth, or remove from queue if the disposition was wrong. The review prevents zombie accumulation. + +--- + +## Failure 14: Light-edit-as-default + +Symptom. Most refreshes are light edits regardless of signal strength. The light edits do not move the needle on pieces that needed substantial revision; the team concludes "refresh does not work" when the actual issue is depth mismatch. + +Diagnosis. Depth assignment is defaulting to light edit because light edits are the easiest to schedule. Substantial revision and full rewrite are being skipped because they are harder to fit into capacity. + +Cure. Match depth to signal strength explicitly. Depth-light when signals support light edit; depth-deeper when signals warrant. Capacity allocation should account for depth distribution; if the team consistently has capacity only for light edits, the allocation needs adjustment, not the depth assignment. + +--- + +## The cross-cutting pattern + +Most refresh failures share a single root: shortcuts in discipline. Calendar-refresh shortcuts the signal analysis. No-measurement shortcuts the learning. Refresh-as-default shortcuts the disposition decision. Light-edit-as-default shortcuts the depth decision. No-re-promotion shortcuts the audience-engagement work. Each shortcut feels like it is saving capacity; each shortcut is actually shifting capacity to lower-value work. + +The fix for almost any refresh failure is the same: surface the discipline that was being shortcutted, and pay the cost of running the discipline. The capacity recovered from eliminating low-value refreshes typically more than pays for the discipline overhead. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the discipline-as-cure observation. + +## Implementation choices that stay internal + +Specific tooling for stalled-refresh detection. Specific reporting templates for owner-of-owners updates. Specific reviewer training on disposition decisions. Specific automation that catches refresh-without-re-promotion. The team's own conventions for capacity recalibration when overcommitment is detected. These vary by team, tooling, and program structure. diff --git a/skills/content-refresh-system/references/effectiveness-measurement.md b/skills/content-refresh-system/references/effectiveness-measurement.md new file mode 100644 index 0000000..7e6d0d3 --- /dev/null +++ b/skills/content-refresh-system/references/effectiveness-measurement.md @@ -0,0 +1,150 @@ +# Effectiveness measurement + +Per-refresh tracking, 30/90-day recovery measurement, pattern detection, the refresh-that-did-not-work review. The discipline that prevents refresh-theater and turns the refresh program into a learning system. + +Refresh effectiveness measurement is the difference between a program that learns and a program that runs. Programs without measurement run the same patterns indefinitely, including the patterns that do not work; programs with measurement see which refreshes produce recovery, which do not, and what the patterns reveal about depth, signal interpretation, and disposition decisions. + +--- + +## Per-refresh tracking + +Each refresh is logged with the data needed to evaluate it. + +The minimum log. + +- URL. The refreshed piece. +- Date shipped. When the refresh published. +- Signals that triggered the refresh. Which of the five signal categories were active; signal severity. +- Disposition. Refresh, merge, delete (with target URLs for merge). +- Depth. Light edit, substantial revision, full rewrite, structural redesign. +- Owner. Who shipped the refresh. +- Capacity spent. Hours of editorial time invested. +- Predicted outcome. What the team expected the refresh to produce (recovery within X% in Y days, or qualitative expectation). +- Actual outcome at 30 days. Traffic, ranking, engagement metrics post-refresh vs pre-refresh. +- Actual outcome at 90 days. Same metrics extended to 90 days. +- Notes. Qualitative observations on what happened, surprising patterns, questions raised. + +Why the minimum log. Each field is load-bearing for pattern detection. Without signals, you cannot tell whether decay-driven refreshes recover differently from drift-driven refreshes. Without depth, you cannot tell whether full rewrites outperform substantial revisions. Without capacity, you cannot evaluate ROI. + +The log as program memory. Across years, the log becomes the program's accumulated learning. A team that has logged 200 refreshes can answer questions like "what is the typical recovery curve for substantial-revision refreshes on traffic-decayed pieces?" with data; a team without the log answers the same question with anecdote. + +--- + +## 30-day recovery measurement + +The first measurement window post-refresh. + +What the 30-day window shows. + +- Schema and indexing recognition. Search engines have crawled the updated piece and registered the modified date. +- Initial ranking response. Some ranking shifts happen within days as the search engine re-evaluates; others take longer. +- Audience engagement spike. Re-promotion produces traffic from newsletter, social, and syndication. The 30-day window captures the immediate engagement. +- Quick wins or regressions. If the refresh broke something (regressions in indexing, schema, or ranking), the 30-day window catches it. + +What the 30-day window does not show. + +- Sustained recovery. Initial spikes from re-promotion fade; the 30-day window cannot distinguish sustained recovery from re-promotion afterglow. +- Algorithm-update response. If an algorithm update happens after the refresh, the 30-day measurement may be confounded. +- Long-tail keyword recovery. Some long-tail rankings move slowly; the 30-day window may show only head-term response. + +The 30-day pattern. Most refreshes that will produce sustained recovery show some signal at 30 days: ranking improvement, traffic uptick, engagement spike. Refreshes that show no signal at 30 days are not necessarily failures, but they warrant attention; the 90-day measurement will resolve the question. + +--- + +## 90-day recovery measurement + +The longer-window measurement that confirms or refutes the 30-day signal. + +What the 90-day window shows. + +- Sustained recovery. Initial spikes have faded; what remains is the refresh's durable contribution. +- Algorithm-update integration. Most algorithm updates have been digested; the 90-day data reflects the new state. +- Long-tail keyword response. Slower-moving rankings have settled. +- Engagement-based metrics. Time on page, return visits, scroll depth post-refresh vs pre-refresh. + +The 90-day pattern. + +- Strong recovery. Traffic and rankings are above pre-refresh baseline by 20%+. The refresh worked. +- Modest recovery. Traffic and rankings are 5-20% above pre-refresh baseline. The refresh helped but did not produce dramatic improvement. +- No recovery. Traffic and rankings are within 5% of pre-refresh baseline. The refresh was not effective. +- Regression. Traffic or rankings are below pre-refresh baseline. The refresh damaged the piece. + +The 90-day measurement is the primary effectiveness measurement. The 30-day is the early-warning; the 90-day is the verdict. + +--- + +## Pattern detection across refreshes + +Individual refresh measurements are noisy. Patterns across refreshes are signal. + +Patterns the log reveals. + +- Depth-effectiveness. Are full rewrites producing better recovery than substantial revisions on similar signals? If yes, the team should consider deeper depth on similar future cases. +- Signal-effectiveness. Are traffic-decay refreshes recovering more reliably than content-drift refreshes? If yes, the program may benefit from prioritizing traffic-decay queue and being more selective about content-drift refresh. +- Disposition-effectiveness. Are pieces in the high-value-decaying quadrant recovering when refreshed, or are they continuing to decay? If continuing decay, the disposition may be wrong (merge or delete may have been better) or the underlying cause is structural (the topic is dying; competitors too strong). +- Owner-effectiveness. Are some owners producing better recovery than others on similar refreshes? Possibly skill differential, possibly capacity issues, possibly random variation that needs more data. +- Topic-effectiveness. Are refreshes on some topics recovering reliably while others do not? Some topics may be in structural decline; the program may need to reduce investment in those topics rather than increase refresh effort. + +Pattern detection cadence. Quarterly review of accumulated refresh data. Year-over-year reviews on multi-year programs. The patterns inform program-level decisions about allocation, prioritization, and disposition defaults. + +--- + +## The refresh-that-did-not-work review + +Refreshes that did not produce recovery are the program's most valuable learning data. + +The review questions. + +- Was the depth wrong? Did the refresh need more depth than was applied? Light edit when substantial revision was needed produces no recovery on substantial-decay signals. +- Was the disposition wrong? Should the piece have been merged or deleted instead of refreshed? Refreshing a piece that should have been merged produces ongoing decay because the underlying authority-splitting was not addressed. +- Was the signal interpretation wrong? Did the team read decay as content-drift when it was actually competitor-displacement? Refresh on the wrong cause does not produce recovery. +- Is the topic in structural decline? Some topics decline structurally; refresh cannot recover what the topic itself has lost. The right disposition may be to reduce investment in the topic and reallocate capacity. +- Did re-promotion happen? Refresh-without-re-promotion underperforms; some "did not work" cases are actually "did not get re-promoted." + +The review output. Each non-recovery refresh produces either: a re-disposition (try merge or delete), a depth re-attempt (next quarter try the deeper depth), or an acknowledgment that the topic is in decline and the program should reduce investment. + +The review's program impact. Without the review, non-recovery refreshes accumulate as silent program failures. With the review, the patterns surface and the program adjusts. + +--- + +## Effectiveness metrics by refresh purpose + +Different refresh purposes warrant different primary metrics. + +Traffic-decay refreshes. Primary metric: post-refresh traffic recovery vs pre-refresh baseline at 90 days. Secondary: ranking position recovery on target keywords. + +Ranking-drop refreshes. Primary metric: ranking position recovery on target keywords at 90 days. Secondary: traffic recovery (rankings without traffic recovery suggest CTR issues that ranking alone does not capture). + +Factual-staleness refreshes. Primary metric: less straightforward; the refresh's purpose is correctness, not recovery. Track that the staleness was caught before reader-detected errors compound. Secondary: any traffic recovery is bonus. + +SERP-intent-shift refreshes. Primary metric: ranking on target keywords (rankings reflect format-fit). Secondary: engagement metrics (the refresh changed format; does the new format engage better?). + +Content-drift refreshes. Primary metric: engagement metrics (time on page, return visits, conversions). Secondary: voice consistency review (qualitative; the refresh purpose was alignment with current brand positioning). + +The metric should match the purpose. Programs that measure every refresh by traffic recovery miss the value of refreshes whose purpose was correctness or alignment rather than recovery. + +--- + +## Common measurement failures + +No measurement at all. Refreshes ship; outcomes are not tracked; the program runs without learning. Each refresh is a fresh prediction with no accumulated evidence. + +Measurement at the wrong window. Measuring at 7 days captures only re-promotion afterglow; measuring at 6 months conflates many other variables. 30 and 90 days are the workable windows. + +Single-metric measurement. Measuring only traffic ignores ranking, engagement, and conversion metrics. Different refresh purposes warrant different metrics. + +Measurement without context. Comparing post-refresh metrics to pre-refresh metrics without accounting for seasonality, algorithm updates, or competitor activity produces noisy attribution. + +No pattern detection. Per-refresh measurement happens but never gets aggregated into pattern review; the program does not learn across refreshes. + +No non-recovery review. Successful refreshes get celebrated; failed refreshes get forgotten. The asymmetry hides the program's most valuable learning. + +--- + +## Methodology-level choices that stay in the public skill + +The minimum per-refresh log fields, the 30-day and 90-day measurement windows, the pattern-detection cadence, the refresh-that-did-not-work review, the metric-by-purpose mapping, the common measurement failures. + +## Implementation choices that stay internal + +Specific analytics dashboards that pull refresh metrics. Specific log structure in the team's project-management or content system. Specific seasonality models the team uses to baseline. Specific competitor-activity tracking that contextualizes attribution. Specific reviewer workflow for non-recovery refreshes. The team's own pattern-detection rituals. These vary by team, tooling, and analytics setup. diff --git a/skills/content-refresh-system/references/re-promotion-after-refresh.md b/skills/content-refresh-system/references/re-promotion-after-refresh.md new file mode 100644 index 0000000..1f20605 --- /dev/null +++ b/skills/content-refresh-system/references/re-promotion-after-refresh.md @@ -0,0 +1,159 @@ +# Re-promotion after refresh + +Schema markup, visible-date update, search-engine resubmission, audience re-share, internal linking refresh. The patterns that signal a refresh to search engines and audiences. + +A refreshed piece that is not re-promoted often performs only marginally better than the original. The refresh's signal to search engines is the modified date; the refresh's value to the program is partly the audience re-engagement that re-promotion produces. Programs that ship refreshes silently leave value on the table. + +--- + +## Signal to search engines + +What the search engine needs to see to recognize the refresh. + +Modified-date in schema markup. Schema.org Article (and related types) include a `dateModified` field. Update this when the refresh ships. Many CMS platforms update this automatically on save; verify the automation is working. Schemas with stale modified dates signal that the refresh is technical rather than substantive. + +Visible modified-date on the page. The page should display "Updated [date]" or similar visible signal. Some templates show "Published [date]" without an updated date; these should be updated to surface the refresh date. + +Sitemap update. The XML sitemap's `lastmod` field for the URL should reflect the refresh date. Most sitemap generators handle this automatically; verify after the refresh ships. + +Search Console URL inspection and resubmission. For high-priority refreshes, use Search Console's URL inspection tool and request indexing. This signals the refresh to the index without waiting for the next crawl. Use sparingly; bulk resubmission of every refresh can throttle. + +Internal-link-graph signals. When sister pieces add or update links to the refreshed piece, the additional internal-link signals reinforce that the URL is current and load-bearing. Refresh that updates internal linking from sister pieces sends stronger signals than refresh that does not. + +--- + +## Substantive vs cosmetic modifications + +Search engines distinguish between substantive content changes and cosmetic touch-ups. + +Substantive changes. Body content edits, section additions or removals, lede or closing rewrites, factual updates, restructuring. The refresh has changed what the piece says. + +Cosmetic changes. Date stamp updates without content changes. CSS or template changes. Whitespace edits. These do not constitute refresh; updating the modified date without substantive change is signaling a refresh that did not happen. + +Why the distinction matters. Search engines that detect the modified-date signal as cosmetic rather than substantive can devalue the signal. Programs that bump modified dates without substantive change to chase the refresh signal are running a tactic that has been increasingly detected and discounted. The honest signal is a real refresh; the tactic of date-bumping without change is short-lived value at best. + +The audit. Refreshes should produce diff'able content changes. If the refresh ships without diff'able changes, it is not a refresh. + +--- + +## Signal to audiences + +The other half of re-promotion: re-engaging the audiences who saw the original. + +Newsletter re-share. For pieces that originally went to the newsletter, a refreshed piece deserves a re-share. The framing is "we updated this with [specific updates]," not "here is a piece you may have seen before." Specificity earns re-engagement; vague re-shares feel like filler. + +Social re-share. For pieces that originally landed on social channels, the refresh is a social moment. New angle, new pull-quote, new visual, framing the refresh as the news the piece now carries. + +Syndication partner update. For pieces syndicated to partner platforms, the refresh may warrant communication with syndication partners about the updated version. Some partners pull the latest content automatically; some do not. The refresh communication closes the loop. + +Email-list segmentation. For programs with sophisticated email-list segmentation, refreshed pieces can be sent to segments that did not see the original or that engaged with the original and may benefit from the updated version. + +Re-share cadence discipline. Not every refresh deserves the same re-share intensity. Light edits typically do not warrant social re-share; substantial revisions or full rewrites do. Calibrate re-share to depth. + +--- + +## Internal linking refresh + +Pieces that link to the refreshed piece may benefit from anchor-text updates. + +When anchor-text update fits. The refreshed piece's positioning shifted, and the anchor text on sister pieces should now describe the piece differently. A piece that linked to the refreshed piece as "our guide to programmatic SEO" may now want to link as "our guide to programmatic SEO durability" if the refreshed piece's framing is now durability-focused. + +When sister pieces should now link to the refreshed piece. Some refreshes add coverage of topics that sister pieces discuss. Pieces discussing those topics that did not previously link to the refreshed piece may now warrant new internal links. + +The internal-link-refresh pass. Some programs run a quick pass after each substantial refresh: search the library for pieces mentioning the refreshed piece's topic, audit whether the existing anchor text and link presence are correct, update where warranted. + +The over-linking failure. Refreshes that trigger 30 internal-link updates across the library can create maintenance overhead disproportionate to value. The internal-link refresh should be targeted, not exhaustive. + +--- + +## URL preservation vs URL change + +Most refreshes preserve the URL. Some warrant URL change. + +Preserve the URL when: + +- The refresh is light edit, substantial revision, or most full rewrites. +- The existing URL has authority worth preserving (rankings, backlinks, internal-link references). +- The URL slug fits the refreshed piece's framing reasonably well even if not perfectly. + +Change the URL when: + +- The refresh is a structural redesign and the URL slug no longer fits. +- The piece is being merged with a sibling and the consolidated piece needs a new URL. +- The original URL was a structural mistake (wrong category, awkward slug) that the refresh is correcting. + +The URL-change cost. Even with 301 redirects, URL changes incur authority transfer cost; some authority does not survive the redirect. URL changes should be earned by structural rationale, not chosen for cosmetic reasons. + +The URL-preservation discipline. Most refreshes should preserve URLs. The default disposition is preserve; URL change is the exception requiring rationale. + +--- + +## The refresh that nobody told anyone about + +The pattern when re-promotion is skipped. + +The symptom. A refresh ships. Modified date updates. Schema validates. The piece sits in the library with the refresh complete on paper. Traffic recovers marginally if at all. The team concludes refresh does not work. + +The actual cause. Re-promotion was skipped. The refresh signaled to the search engine but did not signal to audiences. New-piece-style audience engagement (newsletter, social, syndication) did not happen. The refresh produced search-engine recognition without the audience-engagement spike that often drives broader recovery. + +The cure. Build re-promotion into the refresh workflow as a non-skippable step. The refresh is not "done" when the piece is published; the refresh is "done" when the re-promotion has been executed. Define re-promotion intensity per depth (light edit may need only modified-date and schema; substantial revision needs newsletter and social re-share; full rewrite needs full re-promotion treatment). + +--- + +## Re-promotion checklist by depth + +A short framework matching re-promotion to refresh depth. + +Light edit re-promotion. + +- Modified date in schema and visible. +- Sitemap lastmod. +- No audience re-share required for routine light edits. +- Internal-link audit only if specific anchor text changes warranted. + +Substantial revision re-promotion. + +- Modified date and visible date. +- Sitemap lastmod. +- Newsletter re-share with framing on what was updated. +- Social re-share to channels that originally promoted the piece. +- Internal-link audit on sister pieces with relevant topics. + +Full rewrite re-promotion. + +- All of the above. +- Search Console URL inspection and resubmission. +- Syndication partner update where applicable. +- Email-list segment send to engaged segments. +- Visual asset refresh for social and newsletter (new pull-quote graphics, new hero image if applicable). + +Structural redesign re-promotion. + +- All of the above. +- Coordination with the broader hub or category being redesigned (see `pillar-content-architecture`). +- Cross-piece internal-link audit across the affected hub or category. +- Possible launch communication if the redesign represents a major program milestone. + +--- + +## Re-promotion failure modes + +Skipping re-promotion entirely. The refresh produces marginal recovery; the team concludes refresh does not work; the program loses momentum. + +Bulk-resubmitting every refresh URL to Search Console. Search Console's URL submission has implicit rate limits; bulk submission of low-value refreshes throttles the team's submission capacity for the cases that warrant it. + +Re-share without specificity. "We refreshed this piece; here it is" lacks the specific framing that earns re-engagement. Specific framing ("we added the 2026 data and a new section on X") earns clicks; vague re-shares get ignored. + +Anchor-text updates that proliferate. Internal-link refresh that touches every mention of the topic across the library is over-investment. Target specifically; touch sparingly. + +Modified-date bumping without content change. The signal that gets discounted by search engines and signals to careful auditors that the team is gaming the metric rather than producing substantive refresh. + +--- + +## Methodology-level choices that stay in the public skill + +The signal-to-search-engine patterns, the substantive-vs-cosmetic distinction, the audience re-promotion patterns, the internal-link refresh discipline, the URL-preservation default, the re-promotion checklist by depth, the re-promotion failure modes. + +## Implementation choices that stay internal + +Specific schema markup automation in the team's CMS. Specific newsletter and social-publishing tooling and templates. Specific Search Console workflow conventions. Specific internal-link-audit automation. Specific syndication-partner communication channels. The team's own depth-to-re-promotion-intensity mappings. These vary by team, stack, and channel mix. diff --git a/skills/content-refresh-system/references/refresh-depth-decision.md b/skills/content-refresh-system/references/refresh-depth-decision.md new file mode 100644 index 0000000..4e55045 --- /dev/null +++ b/skills/content-refresh-system/references/refresh-depth-decision.md @@ -0,0 +1,174 @@ +# Refresh depth decision + +Light edit, substantial revision, full rewrite, structural redesign. Time investment per depth, signal-to-depth matching, the depth-creep anti-pattern. + +Refresh depth is one of the most consequential decisions in the program. The wrong depth produces predictable failure: light edits on pieces that needed substantial revision produce no recovery; full rewrites on pieces that only needed factual updates burn capacity. The discipline is matching depth to signal strength. + +--- + +## Depth 1: Light edit + +The work. Update statistics. Replace dead links. Fix factual errors. Swap dated examples. Update product or platform references. Verify external links still resolve and still go where they should. + +Time investment. 30-90 minutes per piece for typical pieces. Longer for research-heavy pieces with many external citations. + +The piece's structure stays intact. Section weights, lede, closing, archetype, voice, claims-and-arguments are all preserved. The light edit is surface maintenance. + +Use when. + +- Factual staleness is the only or dominant signal. +- Traffic is stable or only slightly decayed. +- The piece's structural framing still fits current SERP intent and brand positioning. +- The piece is performing well enough that significant changes would risk performance. + +Common failures. + +- Light-editing when substantial revision is warranted. Surface fixes do not address the structural reasons for decay; the piece continues to decay after the light edit ships. +- Light edits that touch more than they should. A "light edit" that becomes 4 hours of work because the editor kept finding things has lost the depth discipline; either commit to substantial revision or stop at the originally scoped scope. + +--- + +## Depth 2: Substantial revision + +The work. Light edit plus rewrite of 1-3 sections that have aged badly. Update the introduction or closing. Add coverage of topics that have emerged since the piece was written. Restructure 1-3 H2 sections without redesigning the piece's overall shape. + +Time investment. 2-4 hours per piece for typical pieces. Longer for pieces with extensive new sections to add. + +The piece's spine stays intact. The archetype, the central thesis, and most sections survive. Specific sections are rewritten or added. + +Use when. + +- Traffic has decayed moderately but not catastrophically. +- Specific sections of the piece have aged badly (often the introduction, closing, or a section on a topic that has shifted). +- New topics have emerged that the piece needs to cover to stay current. +- The piece's structural framing is mostly fine but needs targeted updates. + +Common failures. + +- Substantial revision drifting into full rewrite. The "substantial revision" that becomes 8 hours of work has crossed into full-rewrite territory; either commit to full rewrite or scope back to the original substantial-revision plan. +- Substantial revision that rewrites the introduction without rewriting the closing, leaving the piece structurally inconsistent (the introduction promises one shape; the closing delivers a different one). +- Rewriting sections without auditing whether the rewrites match each other in voice and density. + +--- + +## Depth 3: Full rewrite + +The work. Keep the URL and topic; rewrite the piece end-to-end. New lede, new structure (possibly new archetype), new closing. The new piece occupies the old piece's URL and connects to the existing internal-link graph. + +Time investment. Similar to writing a new piece, sometimes more because of the constraint of preserving the URL and the existing internal links. 8-16 hours for typical long-form rewrites. + +The piece's spine changes. New archetype possible. New positioning possible. The connection to the URL and the existing topical authority is what is being preserved; everything else can change. + +Use when. + +- Traffic has decayed sharply or persistently. +- The piece's structural framing no longer fits current SERP intent. +- The brand's positioning has shifted enough that the piece needs to be re-conceived. +- Light edit and substantial revision have already been tried and did not produce recovery. + +Common failures. + +- Full rewrite that loses what worked. The original piece had specific strengths (a memorable lede, a particular section that drew links). The rewrite that does not preserve those strengths can perform worse than the original even if the rewrite is technically stronger. +- Full rewrite that breaks internal linking. Section IDs change, anchor links from sister pieces break, the internal-link graph that supported the piece's authority is disrupted. +- Full rewrite that ignores the URL constraint. The team rewrites as if writing a new piece, then realizes the URL is locked and the new framing does not fit the existing slug. Either accept the slug mismatch (suboptimal) or change the URL (incurring redirect cost). + +--- + +## Depth 4: Structural redesign + +The work. Full rewrite plus consolidation with sibling pieces, restructuring of internal linking, possible URL change with redirects. Often part of a larger structural change in the content library: a hub being rebuilt, a category being consolidated, a topic cluster being reorganized. + +Time investment. A multi-piece project. 1-3 weeks for a hub-level restructure involving multiple pieces. + +Multiple URLs and pieces are affected. The piece being refreshed is one node in a graph that is being reshaped. + +Use when. + +- Refresh of an individual piece is bumping against architecture-level issues that cannot be addressed at the piece level. +- A hub is being redesigned and pieces within the hub need to be reconceived as part of the redesign. +- Multiple pieces are competing for the same query and a consolidated piece would produce stronger authority than any of the individual pieces. + +Common failures. + +- Treating structural redesign as a refresh exercise rather than as a project. The work scope is project-scope; treating it as a refresh queue item leads to under-resourcing. +- Structural redesign without coordination with `pillar-content-architecture` discipline. The hub-level work and the piece-level work need to compose; doing them separately produces friction. +- Redirect plans that do not account for all the URLs being consolidated. Some authority is lost in transit because some redirects were missed. + +--- + +## Signal-to-depth matching + +A short framework for choosing depth from the signals. + +Light edit when: + +- Factual staleness is the dominant signal. +- Traffic stable or only slightly decayed (under 10%). +- Rankings stable or only slightly drifted. +- No SERP intent shift detected. +- No content drift detected. + +Substantial revision when: + +- Multiple signal types present (factual + content drift, or traffic decay + ranking drops). +- Traffic decayed moderately (10-25%). +- Rankings drifted but still on page 1. +- Specific sections have aged badly while others are sound. +- SERP intent has not shifted dramatically. + +Full rewrite when: + +- Traffic decayed sharply (25%+). +- Rankings dropped from page 1 to page 2 or beyond. +- SERP intent has shifted substantially (the dominant SERP format has changed). +- Brand positioning has shifted enough that the piece reads as the brand-of-multiple-years-ago. +- Light edit or substantial revision already attempted without recovery. + +Structural redesign when: + +- The piece's issues are architecture-level rather than piece-level. +- A hub or category is being reorganized. +- Multiple sibling pieces are competing for the same query and consolidation would produce stronger authority. + +--- + +## The depth-creep anti-pattern + +Refreshes that grow during execution from their planned depth into a deeper depth that was not budgeted. + +The pattern. A refresh planned as a light edit becomes substantial revision because the editor "kept finding things." The substantial revision becomes a full rewrite because once you are restructuring two sections you might as well restructure the rest. The piece ships 6 weeks after planned, having consumed 4x the planned capacity. + +Why it happens. Editors and writers are pattern-matchers; once they start working on a piece, they see all its problems and want to fix all of them. The discipline of staying at the planned depth is not natural to editorial work. + +The cure. Two options. + +1. Stop at scope. When the editor finds work beyond the planned depth, log it but do not do it. The next quarter's audit can decide whether the piece needs deeper work; this refresh ships at the planned depth. +2. Re-scope explicitly. When the editor discovers the planned depth is wrong, halt the refresh and re-scope formally. The capacity allocation gets adjusted; the timing gets adjusted; the team is aware the refresh became a bigger project. + +The failure mode is the third option: keep going at deeper depth without explicit re-scoping. That produces capacity overruns and missed timelines that affect other work. + +--- + +## Multi-depth refresh sequences + +Some pieces benefit from a sequence of refreshes at different depths over time. + +The pattern. + +- Light edit ships first to address factual staleness while broader investigation continues. +- Substantial revision follows in the next quarter once SERP intent shift has been analyzed and the right structural changes are clear. +- Full rewrite follows in 2-3 quarters if the substantial revision did not produce recovery. + +When this pattern fits. High-value-decaying pieces where the right disposition is unclear and the team wants to avoid premature commitment to a full rewrite. Light-edit-first preserves what works while buying time for analysis. + +When this pattern fails. Programs that always start with light edit on high-value-decaying pieces, regardless of signal strength, because light edit is the easiest depth to schedule. The light edit does not move the needle, and the next quarter's audit shows the same piece in the same queue. + +--- + +## Methodology-level choices that stay in the public skill + +The four depth levels with their work, time investment, and use cases. The signal-to-depth matching framework. The depth-creep anti-pattern with its cure. The multi-depth refresh sequence pattern. + +## Implementation choices that stay internal + +Specific time-tracking that captures actual depth per refresh. Specific scope-confirmation tooling that flags depth-creep. Specific writer or editor assignment patterns by depth (some writers are stronger at light edits; some at full rewrites). Specific brief templates per depth in the team's writing system. These vary by team and tooling. diff --git a/skills/content-refresh-system/references/refresh-execution-patterns.md b/skills/content-refresh-system/references/refresh-execution-patterns.md new file mode 100644 index 0000000..9cee5bb --- /dev/null +++ b/skills/content-refresh-system/references/refresh-execution-patterns.md @@ -0,0 +1,154 @@ +# Refresh execution patterns + +Single owner per refresh, editorial-workflow integration, capacity allocation, batching vs integration tradeoffs. The execution patterns that turn audit queues into shipped refreshes. + +The audit produces a queue. The execution patterns turn the queue into shipped work. Programs that produce strong audits but weak execution end up with documentation of what should have been refreshed rather than refreshed pieces. + +--- + +## Single owner per refresh + +Each refresh has one owner accountable for shipping it. + +The pattern. When a refresh is assigned, one person is named as the owner. The owner runs the work end-to-end: confirming the depth, doing or coordinating the actual editorial work, running the QA gate, shipping, re-promoting, logging the outcome. + +Why single ownership matters. Refreshes that pass through multiple hands without a clear owner often get partially done and then stall. One person believes another is finishing the work; the work sits between them; the audit's next pass shows the piece still in queue. The accountability gap is the failure mode. + +Owner selection. Typically the writer or editor best matched to the topic. For light edits, the owner can be anyone with capacity; for substantial revision and full rewrite, ownership matches expertise. For structural redesign, ownership often sits with a content lead because the work spans multiple pieces. + +Owner-of-owners. A single person owns the refresh program as a whole. Their job is keeping the queue moving, escalating stalled refreshes, ensuring effectiveness measurement is happening, and reporting on the program's health to leadership. Without this role, the program drifts even if individual refreshes have owners. + +--- + +## Editorial-workflow integration + +Refreshes typically run through the same editorial workflow as new pieces, scaled to the chosen depth. + +Light edit workflow. May skip the brief and go straight to edit. The editor pulls the piece, identifies the specific updates, makes them, runs a QA pass, and ships. 30-90 minutes of editorial time; minimal coordination. + +Substantial revision workflow. Brief, draft, edit, QA gate, publish. The brief covers the targeted sections being rewritten; the draft is partial-rewrite; the edit and QA gate match new-piece discipline. 2-4 hours of editorial time; coordination similar to a short blog post. + +Full rewrite workflow. Brief, draft, edit, QA gate, publish. Full new-piece workflow with the additional constraint of preserving the URL and existing internal-link integration. 8-16 hours of editorial time; coordination at long-form-piece scale. + +Structural redesign workflow. Project-scope coordination. Multiple briefs, multiple drafts, redirect plans, internal-link audits. Multi-week timeline; coordination at flagship-project scale. + +The integration discipline. Refreshes are not a separate workflow; they plug into the existing editorial workflow at the appropriate depth. Teams that build a parallel refresh workflow create coordination overhead and quality drift; teams that integrate refresh into the standard workflow benefit from the workflow's existing discipline. + +--- + +## Capacity allocation + +Refresh work consumes editorial capacity that would otherwise produce new pieces. The capacity decision is a real tradeoff. + +Allocation patterns. + +- Newer libraries (under 100 pieces, under 2 years old): 5-15% of capacity to refresh. Most pieces are still relatively current; signals are limited. +- Mid-stage libraries (100-500 pieces, 2-5 years old): 15-30% of capacity to refresh. Decay rates have built up; high-value-decaying queue is meaningful. +- Mature libraries (500+ pieces, 5+ years old): 25-40% of capacity to refresh. Cumulative decay is significant; without sustained refresh capacity, the library erodes. + +The capacity-vs-new-production tradeoff. + +A team producing 20 pieces per quarter might allocate 5 of those slots to refresh work, leaving 15 for new production. Or 8 to refresh, 12 to new. The split affects program shape: heavy-refresh programs preserve existing equity; heavy-new-production programs build new topical authority. + +Right-sizing the allocation. + +- If refresh queues are growing quarter-over-quarter, allocation is too low. +- If new-production output is dropping or the team complains of refresh fatigue, allocation may be too high. +- If high-value-decaying pieces stay in queue across multiple audits, allocation is misallocated (volume of work, not allocation share, may be the issue, but allocation review is the first step). + +The capacity audit. Quarterly, review the actual refresh time spent vs the planned allocation. Programs that consistently exceed their allocation are signaling that the queue's growth rate exceeds the allocation; either grow allocation, narrow the prioritization, or accept slower queue cycle times. + +--- + +## Batching vs integration + +Two patterns for how refresh work fits into the cadence. + +Batching. Dedicated weeks or sprints for refresh work. The team blocks 1-2 weeks per quarter for concentrated refresh execution. + +- Strength. Focus. The team is in refresh mode; context-switching costs are low; throughput on refresh work is high. +- Weakness. Interrupts new production. New-piece workflows pause during refresh sprints; pieces in the new-production pipeline stall. +- Fits. Mid-stage libraries with manageable refresh queues; teams that prefer focused work blocks; programs with predictable seasonality where new production has natural pauses. + +Integration. One refresh per week (or similar steady cadence) integrated into the regular production cadence. + +- Strength. Sustains new production. New-piece work continues without pauses. +- Weakness. Slower refresh velocity per piece; context-switching costs are higher; refresh work can get deprioritized in favor of "more urgent" new-piece work. +- Fits. Mature libraries with continuous refresh queues; teams that prefer sustained pacing; programs where new production has tight commitments. + +Hybrid. A baseline integration cadence plus periodic batching for the high-priority queue. + +- Strength. Sustained refresh on lower-priority work; periodic concentration on high-value-decaying queues. +- Weakness. Coordination overhead; the team manages both modes. +- Fits. Mature programs with sophisticated capacity planning. + +The discipline. Pick a pattern. The failure mode is no allocation discipline at all, which produces refresh work happening in the cracks at unpredictable cadence and a queue that never clears. + +--- + +## The refresh that needs to happen now + +Some refreshes cannot wait for the next allocation slot. + +Trigger conditions. + +- Sharp decay (40%+ traffic loss in 30 days) on a high-value piece. +- Algorithm-update fallout affecting a high-value piece. +- Factual error producing reputational risk. +- Broken page state (indexing failure, schema regression, redirect loop). + +The fast-track pattern. + +- Continuous monitoring detects the issue. +- The owner-of-owners decides whether the issue warrants fast-track. +- Fast-track refreshes get pulled out of the queue and shipped within days. +- The refresh skips some workflow steps if necessary (briefer brief, faster QA) but does not skip the QA gate; pieces that ship without QA produce regressions that compound. + +Fast-track capacity. Teams need a small reserve for fast-track work. The reserve is typically 5-10% of total capacity. Without reserve, fast-track work pushes other work out and produces cascade delays. + +--- + +## Stalled refresh recovery + +Refreshes that have been in queue for more than two audit cycles need intervention. + +Common causes. + +- Owner is over-committed; the refresh is not the highest priority on their plate. +- The refresh's depth was wrong (planned as light edit, actually needed substantial revision); the owner stalled rather than escalate. +- The refresh's disposition was wrong (planned as refresh, should have been merge); the owner is uncertain how to proceed. + +The recovery pattern. + +- Owner-of-owners reviews stalled refreshes at each audit. +- Reassign owners where capacity is the issue. +- Re-scope where depth was wrong; re-disposition where the disposition was wrong. +- For refreshes stalled because the analysis revealed a deeper issue, escalate to a content lead for decision. + +The stalled-refresh review prevents the queue from accumulating zombie items that everyone knows are not getting done but nobody is removing. + +--- + +## Common execution failures + +No single owner. Refreshes are assigned to "the team"; nobody is accountable; the refresh stalls. + +Workflow shortcuts. The refresh skips the QA gate or the brief. Quality drifts; regressions compound. + +Capacity overcommitment. The team plans 20% capacity for refresh; actual refresh work consumes 35%; new production suffers; team burns out. + +Refresh queue without owner-of-owners. The queue grows; nobody is reporting on its health; the program drifts toward set-and-forget within the formal-program shape. + +Fast-track without reserve. Urgent refreshes push planned work out; cascade delays affect downstream pieces. + +Stalled refreshes accumulating. The queue has zombie items in it; the queue's reported health does not match the queue's actual state. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner discipline, editorial-workflow integration shapes by depth, capacity allocation patterns by library stage, batching vs integration vs hybrid tradeoffs, the refresh-that-needs-to-happen-now pattern, the stalled-refresh recovery pattern. + +## Implementation choices that stay internal + +Specific project-management tooling for the refresh queue. Specific notification systems for refresh assignments. Specific time-tracking for capacity audits. Specific reserves and fast-track triage workflows. The team's own conventions for owner reassignment. These vary by team, tooling, and program shape. diff --git a/skills/content-refresh-system/references/refresh-prioritization-matrix.md b/skills/content-refresh-system/references/refresh-prioritization-matrix.md new file mode 100644 index 0000000..8b4649b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-prioritization-matrix.md @@ -0,0 +1,148 @@ +# Refresh prioritization matrix + +The 2x2 prioritization matrix with quadrant strategies. The discipline of NOT refreshing the high-value-stable quadrant. The under-recognized failure of treating low-value-decaying as automatic refresh candidates. + +Most libraries have more pieces showing signals than the team has capacity to refresh. Without prioritization, refresh work happens on the cheapest pieces or the most visible pieces, leaving high-value-decaying pieces in the backlog while editorial capacity goes to pieces that would not have produced recovery worth the effort. + +The matrix shifts the program from refresh-everything to refresh-the-quadrant-that-warrants-it. + +--- + +## The two axes + +Piece value. A composite of business value, traffic value, and strategic role. + +- Business value. Pieces that drive conversions, qualified leads, or specific business outcomes. Sometimes measurable directly (pieces that close a defined funnel step), sometimes attributed (pieces that influence subsequent conversions). +- Traffic value. Pieces that drive meaningful organic traffic, especially on commercial-intent keywords or topical-authority-building queries. +- Strategic role. Pieces that anchor a hub, that establish the brand's POV on a flagship topic, or that earn external citations and links. Strategic role can outweigh raw traffic; a 500-traffic flagship piece is high-value if it is the canonical statement of the brand's position. + +Pieces are classified as high-value (HV) or low-value (LV). The line between HV and LV is judgment-driven; teams typically settle the criteria by establishing tiers (top 10% by value, next 30%, bottom 60%, or similar). + +Traffic state. A composite of recent and trending traffic. + +- Stable. Traffic over the last 90 days is within 10-15% of the prior 90-day baseline, accounting for seasonality. +- Decaying. Traffic over the last 90 days is down meaningfully (15%+ beyond seasonal baseline), or trending consistently down over multiple quarters. + +Pieces are classified as stable or decaying. The classification is the easier of the two axes because traffic data is cleanly measurable. + +--- + +## Quadrant 1: High-value, decaying + +Top priority. + +The pieces. Pieces that drive meaningful traffic, conversions, or topical authority and are losing position. + +The strategy. Refresh first; the traffic loss compounds and the lost equity is hard to recover. These pieces are usually worth substantial-revision or full-rewrite refresh depth because the value at stake justifies the work. + +The disposition decision. Almost always refresh. Merge candidates in this quadrant exist (a high-value piece that is decaying because a sister piece is competing for the same query) but are uncommon. Delete is essentially never the right disposition for a high-value piece. + +Capacity allocation. This quadrant gets the largest share of refresh capacity. Many programs allocate 60-70% of total refresh capacity to high-value-decaying pieces. + +Expected outcomes. Recovery measured at 30 and 90 days. Strong refreshes on this quadrant typically produce 20-50% traffic recovery within 90 days; full rewrites can produce more. + +Common failures. + +- Treating this quadrant as "save for later" because the work is heavy. The traffic loss continues during the delay. +- Light-editing high-value-decaying pieces when substantial revision is warranted. The light edit does not move the needle and the team concludes refresh does not work. +- Not investigating the cause. A piece that is decaying because a competitor published a better resource needs different work than a piece decaying because of SERP intent shift. + +--- + +## Quadrant 2: High-value, stable + +Monitor; do not refresh proactively. + +The pieces. Pieces that are performing strongly and showing no decay signals. + +The strategy. Leave alone. Refresh-everything-on-calendar treats this quadrant the same as the high-value-decaying quadrant and damages performance. Pieces that are working should not be touched without clear signal. + +The disposition decision. No action; monitor through continuous monitoring for emerging decay; review at quarterly audits for content drift signals. + +The discipline. This is the quadrant that calendar-refresh programs damage most. A piece ranking position 2 with stable traffic gets refreshed because it is the next piece in the rotation; the refresh introduces minor changes that shift the SERP signals; ranking drops to position 5; traffic drops 30%. The refresh that was meant as maintenance was actually destruction. + +When to revisit. Monitor for emerging signals. If traffic starts decaying or rankings drop, the piece moves to high-value-decaying. If content drift becomes pronounced (the piece is performing but the team sees positioning misalignment), substantial revision may be warranted but only if the team is willing to risk the performance. + +Common failures. + +- Refresh-on-calendar damaging stable pieces. +- Treating stable rankings as a refresh target because the team wants to "improve" the piece. Improvement on stable pieces is a high-risk operation. +- Touching the URL, schema, or core copy of a stable piece without strong rationale. + +--- + +## Quadrant 3: Low-value, decaying + +Audit for merge or delete. + +The pieces. Pieces with low traffic that are decaying further. Pieces that never had strong demand and are now losing what little they had. + +The strategy. The default disposition is NOT refresh. Refresh on these pieces rarely justifies the effort; the underlying issue is usually that the piece never had strong demand. The actual disposition is usually merge (consolidate into a stronger sibling piece) or delete (and 301 to the closest sibling or relevant hub). + +The disposition decision. + +- Merge when a sibling piece on a related topic is performing better and could absorb the failing piece's content. Merging consolidates authority and produces a stronger consolidated piece. The merged URLs redirect to the survivor. +- Delete when no merge candidate exists, the topic is not load-bearing for the program, and the piece's residual value (small as it is) does not justify maintenance. Delete and redirect to the closest sibling piece or hub. +- Refresh is occasionally warranted: when the piece has clear strategic role (anchors a small but important sub-topic) and the decay is recoverable. Rare in this quadrant. + +Capacity allocation. This quadrant gets the smallest share of refresh capacity but a meaningful share of disposition work (merges and deletes are real work, less than full rewrites but more than light edits). + +Common failures. + +- Refreshing pieces in this quadrant by default. The team spends hours improving a low-value piece that even at its best will not recover meaningful traffic, while a merge candidate that would have produced a stronger consolidated piece sits unaddressed. +- Skipping the merge analysis. Pieces that should have been merged get refreshed in isolation, leaving the authority-splitting problem intact. +- Avoiding deletes because deleting feels destructive. Maintaining a library of low-value pieces forever costs ongoing audit attention and dilutes overall library quality. + +--- + +## Quadrant 4: Low-value, stable + +Leave alone. + +The pieces. Pieces with low traffic that are not actively decaying. They are at the floor. + +The strategy. Leave alone. Low traffic is the floor; the piece is not costing anything to keep. Touching these pieces in a refresh program burns capacity for no return. + +The disposition decision. No action. Pieces that have been low-traffic-stable for multiple audits are candidates for batch consideration: do they collectively represent a topic that is no longer load-bearing for the program? If yes, a structural decision (delete the topic cluster, merge into a hub, archive) may be warranted at program level. If no, leave alone. + +When the strategy fails. If a low-value-stable piece starts decaying further (moves to low-value-decaying), the disposition is reconsidered. Usually merge or delete. + +Common failures. + +- Refresh-on-calendar touching this quadrant. Pure capacity waste. +- Treating low-traffic as a problem to be solved. Low traffic on a low-value piece is the right outcome; not every piece needs to drive significant traffic. Some pieces serve narrow but real strategic roles at low volume. + +--- + +## Capacity allocation by quadrant + +A typical refresh program's capacity might split as: + +- High-value, decaying: 60-70% of refresh capacity. The largest share, on the highest-value work. +- Low-value, decaying: 15-20% of capacity, mostly on merge and delete dispositions, occasional refresh on strategically important pieces. +- High-value, stable: 5-10% of capacity, on the rare cases where content drift warrants substantial revision despite stable performance. +- Low-value, stable: 0-5% of capacity. Mostly batch reviews to identify topic-level decisions. + +The allocation varies by library age and decay rates. Newer libraries with limited decay have less work in the decaying quadrants and may invest more in continuous-monitoring infrastructure. Older libraries with significant decay have more work to do across quadrants. + +--- + +## Common matrix failures + +The "every piece is high-value" trap. Teams that classify too many pieces as high-value lose the prioritization signal. A library where 60% of pieces are "high-value" is essentially unprioritized; the matrix fails to discriminate. + +The traffic-only value classification. Classifying value purely by traffic misses strategic-role pieces that have lower traffic but high importance. A flagship manifesto that earns 800 visits a month but drives external citations and brand recognition is high-value despite lower traffic. + +The "refresh = recovery" assumption. Some pieces in the high-value-decaying quadrant cannot be recovered through refresh. The topic is genuinely declining; competitors are too strong; SERP intent has shifted away from any format the brand can produce. The matrix prioritizes refresh; it does not promise refresh will work. The effectiveness measurement (see `effectiveness-measurement.md`) catches the cases where refresh is not producing recovery. + +Static classification. Value and traffic state both shift over time. A piece in low-value-stable that suddenly draws traffic from an emerging keyword moves to high-value-stable; a piece in high-value-decaying that fully recovers moves to high-value-stable. The matrix is not a one-time classification; it is the framework run at each audit. + +--- + +## Methodology-level choices that stay in the public skill + +The two axes (value, traffic state), the four quadrants with strategies, the capacity allocation guidance, the common matrix failures, the dynamic-classification discipline. + +## Implementation choices that stay internal + +Specific value-classification rubrics the team uses (revenue attribution models, strategic-role tagging, traffic-tier definitions). Specific scripts that classify pieces into quadrants from data pulls. Specific dashboards that visualize the matrix at audit time. The team's own conventions for high-value-stable refresh decisions when content drift is pronounced. These vary by team, business model, and analytics setup. diff --git a/skills/content-refresh-system/references/refresh-signals-checklist.md b/skills/content-refresh-system/references/refresh-signals-checklist.md new file mode 100644 index 0000000..bddf11b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-signals-checklist.md @@ -0,0 +1,164 @@ +# Refresh signals checklist + +Five signal categories that trigger refresh consideration, with detection patterns and the audit shape that surfaces signals across the library. + +Pieces that show no signals do not need refresh. Pieces that show one or two signals warrant attention. Pieces that show three or more signals are typically in active decay and should be high in the prioritization queue. The signal taxonomy below is what distinguishes triaged refresh from calendar refresh. + +--- + +## Signal 1: Traffic decay + +Organic traffic to the piece is trending down over a 90+ day window beyond seasonal baseline. + +Detection patterns. + +- Pull traffic data per URL over rolling 90-day windows. +- Compare current 90 days to prior 90 days, accounting for known seasonality. +- A drop of more than 15-20% beyond seasonality on a piece that previously had stable traffic is a real signal. +- A drop of more than 40% in a 30-day window is a sharp signal warranting urgent review. + +What the signal usually means. + +- Slow decay (5-10% over a year): content drift. The piece is gradually losing relevance as the topic evolves or the brand's voice shifts. +- Moderate decay (15-30% in a quarter): ranking position drift, or SERP intent shifting, or competitor publication. +- Sharp decay (40%+ in a month): algorithm update, indexing issue, dramatic SERP intent shift, or technical regression on the URL. + +Diagnostic next steps. When traffic decay is detected, check ranking positions for the piece's target keywords (signal 2 may also be active), check for technical issues (indexability, page speed, broken redirects), and check the SERP for intent shift (signal 4). + +Anti-patterns in detection. + +- Comparing month-over-month rather than 90-day windows over-attributes seasonal noise to decay. +- Ignoring known seasonality (holiday traffic, B2B dropping in late December) produces false positives. +- Looking only at total traffic instead of organic specifically blurs the signal with referral or paid changes. + +--- + +## Signal 2: Ranking drops + +The piece is losing position on its target keywords. + +Detection patterns. + +- Track each piece's primary 3-10 target keywords with rank tracking. +- Drops from page 1 to page 2-3 are particularly consequential because click-through rates fall sharply at the page-1-to-page-2 boundary. +- Drops within page 1 (position 3 to position 7) reduce clicks but are less existential. +- Persistent drops over 30+ days are real shifts; week-over-week volatility within a few positions is normal. + +What the signal usually means. + +- A piece that was at position 3 and is now at position 8 has been displaced by stronger competing pieces. The displacement is informative; review what is now ranking and what those pieces have that this piece does not. +- A piece that was at position 5 and is now at position 35 has likely been algorithm-affected, indexing-affected, or technically regressed. Investigate before refresh; refreshing a piece with an indexing issue does not solve the indexing issue. +- Drops on long-tail keywords with simultaneous gains on broader head terms can indicate the piece's focus has broadened beneficially. Not always a refresh signal. + +Diagnostic next steps. Pull the SERP for each target keyword. Examine what is ranking. Identify whether the new rankings are stronger pieces (refresh signal: improve the piece) or different SERP intent (signal 4: SERP intent shift, possibly different format needed). + +Anti-patterns in detection. + +- Treating any rank movement as a refresh signal produces refresh-on-noise; require persistence over 30+ days. +- Tracking only branded keywords misses the meaningful organic ranking signal. +- Ignoring keyword cannibalization (multiple pieces competing for same keyword) treats split rankings as a refresh signal when the actual disposition is merge. + +--- + +## Signal 3: Factual staleness + +The piece contains statistics, references, examples, or claims that are dated. + +Detection patterns. + +- Annual review of statistics in the piece. Any stat older than 3 years on a fast-moving topic is a candidate for staleness flagging. +- Reference checks for defunct products, platforms, services, or companies named in the piece. +- Example checks for examples that have aged poorly (a 2019 case study of a company that has since gone bankrupt or changed direction). +- Framing checks for claims that no longer match current reality ("AI is starting to influence search" in 2026 is anachronistic). + +What the signal usually means. + +- Factual staleness alone is often a light-edit signal: update the stats, replace dead links, swap dated examples. The piece's structure may be sound. +- Factual staleness combined with traffic decay or ranking drops is a stronger signal that the piece's broader framing has aged, not just the surface details. +- Factual staleness on a flagship piece is more urgent than on a low-traffic piece because flagship pieces are read by more people who notice the staleness. + +Diagnostic next steps. List the specific stale facts, references, and examples. Estimate the light-edit time required to refresh them. If the structural framing is also stale, the depth required is substantial revision rather than light edit. + +Anti-patterns in detection. + +- Treating every old stat as stale when the stat may still be current (some stats genuinely have not changed in 3 years) produces unnecessary refresh. +- Ignoring framing-level staleness while updating individual stats produces pieces that are technically current in stats but feel old in voice. + +--- + +## Signal 4: SERP intent shift + +The dominant SERP format for the target keyword has changed. + +Detection patterns. + +- Pull the current SERP for each target keyword. What format is dominating? Articles? Listicles? Videos? Product comparisons? AI overviews? +- Compare to the piece's format. If the piece is an article and the SERP wants product comparisons, intent has shifted. +- Watch for new SERP features that did not exist when the piece was written: AI overviews, generative answers, knowledge panels, featured-snippet shifts. + +What the signal usually means. + +- The piece may still rank but increasingly for the wrong reasons. Click-through rates fall as the SERP signals the piece is not the dominant intent match. +- The piece may need format restructuring (full rewrite or substantial revision rather than light edit) to fit the new dominant intent. +- Sometimes the right disposition is to write a NEW piece in the new dominant format and either consolidate the old piece into it or keep the old piece for the residual intent it still serves. + +Diagnostic next steps. Read the top-ranking pieces for the target keyword. What format are they? What questions do they answer that the piece does not? Decide whether refresh in the new format will recover the position, or whether a new piece in the new format is the better disposition. + +Anti-patterns in detection. + +- Ignoring AI-overview presence on the SERP. AI overviews change click-through rates substantially and may indicate the piece needs restructuring for AI search citation. +- Assuming SERP intent is stable. Some keywords have stable intent for years; others shift quarterly. The audit should be active. + +--- + +## Signal 5: Content drift + +The piece's positioning no longer matches the brand's current positioning. + +Detection patterns. + +- The piece's voice reads as the brand-of-three-years-ago. Vocabulary, tone, level of conviction. +- The piece's POV on the topic has not kept up with how the brand now thinks. The brand has sharpened a position the piece treats with old hedging. +- The piece's framing fits the audience the brand had then, not the audience the brand has now. +- The piece's calls-to-action, internal linking, and product references reflect older brand offerings that have since changed. + +What the signal usually means. + +- Content drift is internal signal. Readers may not consciously notice, but the team will, and over time the library's voice incoherence weakens the brand. +- Content drift is often paired with the team's discomfort about which pieces in the library represent the brand best when sharing externally. +- Content drift is rarely the sole driver of a refresh decision (because traffic and rankings may be fine), but it determines depth: a content-drift refresh is usually substantial revision or full rewrite, not light edit. + +Diagnostic next steps. Identify which sections drift hardest from current positioning. If drift is concentrated in introduction, closing, and CTAs, substantial revision can address it. If drift is throughout, full rewrite is the cleaner disposition. + +Anti-patterns in detection. + +- Treating every voice evolution as drift triggers calendar refresh of pieces that are still serving readers. +- Ignoring drift because the piece is performing in search produces a library that performs but no longer represents the brand. + +--- + +## The library audit + +Running the signal taxonomy across the whole library. + +Audit shape. + +- Pull a per-URL data set: traffic over time, rankings, last-modified date, target keywords, business-value tag (high/medium/low). +- For each URL, run the five signal checks. Mark each signal as present or absent. +- Pieces with zero signals: stable; no action. +- Pieces with one or two signals: candidate queue; review individually for disposition. +- Pieces with three or more signals: active-decay queue; high priority for disposition decision. + +Output. A spreadsheet or database of pieces with their signals and the resulting disposition (refresh, merge, delete, monitor). The output feeds the prioritization matrix and the refresh queue. + +Cadence. Full audit quarterly. Continuous monitoring for traffic-decay and ranking-drop signals; manual signal checks (factual staleness, SERP intent shift, content drift) at quarterly cadence. + +--- + +## Methodology-level choices that stay in the public skill + +The five signal categories with detection patterns and what each signal means; the audit shape across the library; the cadence; the anti-patterns in detection. The signal-to-disposition mapping that informs prioritization. + +## Implementation choices that stay internal + +Specific data pulls from the team's analytics platform. Specific rank-tracking thresholds. Specific automation that runs continuous monitoring. Specific reviewer dashboards that surface signals. Specific seasonality models the team uses to baseline traffic. The team's own tags for business-value classification. These vary by team, tooling, and analytics setup. diff --git a/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md b/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md new file mode 100644 index 0000000..e1b242b --- /dev/null +++ b/skills/content-refresh-system/references/refresh-vs-merge-vs-delete.md @@ -0,0 +1,137 @@ +# Refresh vs merge vs delete + +The disposition decision. When to refresh, when to merge, when to delete and redirect. The under-recognized failure of refreshing pieces that should have been merged or deleted. + +Most refresh programs default to refresh as the disposition. The default is wrong. Some pieces should be merged into stronger siblings; some should be deleted and redirected. The disposition decision is upstream of the depth decision: a piece getting deleted does not need depth, and a piece being merged is doing a different kind of work than refresh. + +--- + +## Refresh + +The piece has a clear topic, real demand, and either a strong-enough current position to recover or a strong-enough strategic role in the library to justify the work. + +Criteria for refresh disposition. + +- The piece has demonstrated demand: it draws meaningful traffic now or did historically. +- The topic is one the brand wants to own; the piece's existence is strategically warranted. +- A path to recovery exists: refresh of the right depth has a reasonable chance of producing improvement. +- No sister piece is competing for the same query in a way that splits authority. +- The piece's URL has accumulated authority worth preserving. + +When refresh fits but might not. + +- Sometimes a refresh-eligible piece is also a merge candidate. A high-value-decaying piece that is decaying because a sister piece is stronger may produce more value through merge than through refresh of either piece alone. +- Sometimes refresh has been tried and did not produce recovery. The first failed refresh shifts disposition consideration toward merge or full-rewrite-with-new-positioning rather than another refresh attempt. + +Refresh failure modes. + +- Refreshing pieces that are not recoverable. The topic is dying; the brand cannot win against the competition; the SERP intent has shifted to a format the brand does not produce. Refresh in these cases is theater. +- Refreshing without resolving the underlying issue. If a piece is decaying because a sister piece is competing for the same query, refresh of the original piece does not solve the cannibalization. Both pieces continue to underperform. + +--- + +## Merge + +Two or more pieces are competing for the same query, splitting authority and confusing the reader. Combine into one stronger piece; redirect the merged URLs. + +Criteria for merge disposition. + +- Two or more pieces target the same primary query or a closely overlapping query cluster. +- Combined authority across the pieces is meaningful; merging would produce a piece with stronger authority than any individual piece has. +- The pieces' coverage overlaps enough that consolidation produces a coherent piece, not a Frankenstein of mismatched sections. +- The team can identify which URL the survivor occupies (typically the one with strongest existing authority) and which URLs redirect to the survivor. + +The merge decision in detail. + +- Identify the survivor URL. Usually the URL with strongest existing rankings, traffic, and backlinks. The survivor inherits the consolidated content; other URLs redirect to it. +- Plan the consolidated content. Outline the merged piece. Decide which sections come from which source piece. Plan the gaps where new content will fill what neither piece had. +- Author the consolidated piece. Write or rewrite as needed. The consolidated piece is usually stronger than any of the source pieces because it is built from the strongest components plus targeted new content. +- Implement redirects. 301 redirects from the merged URLs to the survivor. Redirects need to be implemented at publish time, not after; the merged URLs going to 404 or 410 produces traffic loss that did not need to happen. +- Update internal links. Pieces that linked to the merged URLs should be updated to link to the survivor. + +Merge failure modes. + +- Merging without redirects. The merged URLs go to 404; the consolidated authority does not transfer; traffic is lost. +- Merging pieces that did not actually compete. If two pieces target different intents, merging them produces a piece that does neither well. +- Frankenstein merges. The consolidated piece reads as multiple pieces stitched together rather than as a unified piece. Cure: rewrite the consolidated piece as a piece in its own right, using the source pieces as input rather than as components. + +--- + +## Delete + +The piece has no real demand, the topic is no longer relevant to the brand's positioning, or the piece is a low-quality artifact from an earlier era of the program. + +Criteria for delete disposition. + +- The piece draws minimal traffic and has minimal residual authority. +- The topic is not load-bearing for the program; the brand does not need to own it. +- No merge candidate exists; the piece's content does not consolidate cleanly into any stronger piece. +- Maintaining the piece costs ongoing audit attention without proportional return. + +The delete decision in detail. + +- Identify the redirect target. The deleted URL should redirect to the closest sibling piece, or to the relevant hub or category page, or to the homepage if no other target fits. Deleting without redirect (returning 404 or 410) is correct only when the piece's residual authority is genuinely zero, which is rare. +- Implement the redirect. 301 redirect to the chosen target. +- Update internal links. Pieces that linked to the deleted URL should be updated to link to the redirect target directly. The redirect chain still works but direct links are cleaner. +- Document the deletion. The audit log should capture the delete decision, the rationale, and the redirect target. Future audits can reference the log if a question arises about the URL. + +Delete failure modes. + +- Avoiding delete because deleting feels destructive. The library accumulates low-value pieces forever, costing ongoing audit attention and diluting overall library quality. +- Delete without redirect. The URL returns 404; whatever residual authority existed is lost; users who linked to the URL or bookmarked it find a dead link. +- Delete of pieces that should have been merged. The piece's content had value the team did not recognize; merging would have preserved it. Delete is appropriate when no merge candidate exists, not as the easy path to avoid the merge analysis. + +--- + +## The disposition decision flow + +A short framework for choosing. + +1. Does the piece have demonstrated demand? Traffic, rankings, conversions, or strategic role. If yes, continue. If no, the disposition is likely delete (or merge if there is a candidate). +2. Is there a sibling piece competing for the same query? If yes, evaluate merge. The merged piece has a strong chance of outperforming both original pieces. +3. Is the topic load-bearing for the brand? If no, refresh disposition is unlikely to be the right answer; consider merge into a stronger sibling or delete. +4. Has refresh been tried recently without recovery? If yes, the next disposition should be merge or full-rewrite-with-new-positioning, not another refresh attempt. +5. What is the cheapest disposition that addresses the actual problem? Refresh is often defaulted to because it feels less destructive; merge and delete are sometimes the cheaper paths to the actual outcome. + +--- + +## The under-recognized failure: refreshing what should have been merged or deleted + +The pattern that costs refresh programs the most capacity. + +How it shows up. The team spends 4 hours refreshing a low-value-decaying piece that even at its best will not draw meaningful traffic. The refresh ships. The piece ranks slightly better for two weeks, then drifts back down. Three months later the piece is in the same audit queue. + +Why it happens. + +- Refresh feels less destructive than merge or delete. +- The merge analysis takes time; refresh feels like the immediate action. +- Delete requires team agreement; refresh can be done by a single owner. +- The team has not internalized that some pieces should not be refreshed. + +The cure. Make merge and delete first-class dispositions in the audit. Every piece in the audit gets one of: refresh, merge, delete, monitor, no action. The audit is not "which pieces to refresh"; it is "what disposition each piece should get." Refresh becomes one option among several rather than the default. + +The capacity recovery. Programs that adopt the merge-and-delete-as-first-class-dispositions discipline typically recover 20-40% of refresh capacity for higher-value work. The pieces that were getting refreshed but should have been merged or deleted stop consuming capacity; the freed capacity goes to high-value-decaying pieces that produce real recovery. + +--- + +## Disposition decisions that need approval + +Some dispositions are higher-risk than others and warrant approval beyond the audit owner. + +Delete dispositions. Always need approval. Deletes are essentially irreversible without significant work to undelete; the redirect strategy is consequential; the team should be aligned on the decision. + +Merge dispositions involving high-value pieces. Need approval. Merging into a survivor URL means the non-survivor URLs lose their identity. If the non-survivor pieces had high-value characteristics, the merge needs review. + +Refresh dispositions on stable high-value pieces. Need approval. Touching a stable high-value piece is a high-risk operation; the audit owner should not unilaterally decide to refresh. + +Light edit and substantial revision on decaying pieces. Usually do not need approval beyond the audit owner. The risk-reward is straightforward. + +--- + +## Methodology-level choices that stay in the public skill + +The three dispositions and their criteria, the disposition decision flow, the under-recognized failure of refreshing what should have been merged or deleted, the merge and delete mechanics, the dispositions that need approval. + +## Implementation choices that stay internal + +Specific redirect implementation in the team's CMS or hosting layer. Specific internal-link update automation that catches links to merged or deleted URLs. Specific approval workflows for high-risk dispositions. Specific audit-log templates that capture disposition rationale. These vary by team, tooling, and CMS. diff --git a/skills/content-repurposing/SKILL.md b/skills/content-repurposing/SKILL.md new file mode 100644 index 0000000..be7ced8 --- /dev/null +++ b/skills/content-repurposing/SKILL.md @@ -0,0 +1,298 @@ +--- +name: content-repurposing +description: "Cross-format content adaptation. Turning one substantial piece into many derivative formats (blog series, email sequences, social posts, webinars, podcasts, video shorts) without losing the original's value or producing AI-slop variants. The discipline of adaptation per medium rather than mass-blast distribution. Triggers on content repurposing, content adaptation, cross-format content, content atomization, content multiplication, content distribution across formats, source-piece-to-derivative, video shorts from blog, email from whitepaper, podcast from article, blog series from research. Also triggers when a flagship piece is shipping but the team has not planned how to extend it across formats, when repurposing is happening but the derivatives feel mass-produced, or when AI-assisted repurposing is producing slop variants of strong source pieces." +category: content +catalog_summary: "Cross-format content adaptation: one piece becomes many (blog series, email, social, webinar, podcast, video) with per-format adaptation rather than mass-blast that ignores medium constraints" +display_order: 11 +--- + +# Content Repurposing + +A senior editorial leader's playbook for cross-format content adaptation. The discipline of turning one substantial piece into many derivative formats without losing the original's value or producing slop variants. + +Most content programs underspend on repurposing. A flagship piece costs 40-80 hours to produce; the program publishes it once, shares it on three channels, and moves on. The same piece could have produced a blog series, an email sequence, a webinar, a podcast episode, a dozen social posts, video shorts, and FAQ extractions for AI search visibility. The work to extend the source piece across formats is small relative to the value extracted; programs that skip repurposing leave most of the value unrealized. + +The failure mode in the other direction is mass-blast: the same content reposted across channels without adaptation. A blog post pasted into LinkedIn as a long-text post; the email newsletter is the blog's first three paragraphs with "read more" tacked on; the YouTube video is a slideshow of the article text read aloud. Mass-blast respects neither the medium nor the audience. AI-assisted repurposing has made mass-blast cheap; the result is a wave of derivative content that performs poorly across every channel because it was adapted to none of them. + +This skill is the discipline of adaptation per medium. Each format has constraints, conventions, and reader expectations the source piece does not have. Repurposing that respects those constraints produces work that earns engagement on the new format; repurposing that ignores them produces filler. + +When to use this skill: planning the extension of a flagship piece across formats, auditing a repurposing pipeline that is producing low-engagement derivatives, calibrating an AI-assisted repurposing workflow that is producing slop, or designing the cross-format adaptation conventions for a content program. + +--- + +## What this skill is for + +This skill spans cross-format adaptation work after a source piece has been produced. The content suite distinction: + +- `content-strategy` decides what to produce. +- `pillar-content-architecture` designs the topical hub. +- `content-brief-authoring` briefs each piece. +- `content-and-copy` writes the original piece in any single format. +- `content-repurposing` (this skill) turns one piece INTO many formats. +- `content-distribution` gets content TO audiences via channels. +- `editorial-qa` verifies pre-publish, including derivatives. +- `ai-content-collaboration` is the workflow layer; AI participation rules apply within repurposing. + +The distinction from `content-distribution` is load-bearing. Distribution is channel work: getting content to audiences via the right channels. Repurposing is transformation work: turning one piece INTO many formats, each adapted for its medium. They compose: repurpose first, then distribute the right format on the right channel. + +The audience: editorial leads, content directors, content ops managers, in-house teams running multi-format programs, agencies producing derivative content for clients, anyone planning to extend a flagship piece across formats. + +What is not in scope: the original piece's production (covered by `content-and-copy` and the long-form skills), the channels themselves (covered by `content-distribution`), the editorial QA on derivatives (covered by `editorial-qa`). + +--- + +## One-and-done vs mass-blast vs adapt-by-format + +The keystone framing. + +One-and-done. Publish once on the source format; never reuse. The piece took 60 hours to produce; it generates traffic for 90 days; it gets shared three times; it goes silent. The team treats publication as the end of the piece's life. Output: most of the source piece's value goes unrealized; the team is always producing new flagship work because old flagship work is not being extended. + +Mass-blast. Same content reposted across channels without adaptation. Blog post text pasted into LinkedIn as a long post. Email newsletter is the blog's first three paragraphs. The YouTube version is a slideshow of the text read by AI voice. Output: low engagement on every channel because nothing was adapted to any channel's conventions. Audiences perceive the cross-channel sameness as low-effort filler. AI-assisted repurposing has made this pattern cheap and common. + +Adapt-by-format. Per-medium adaptation that respects each format's constraints and conventions. The blog series breaks the source piece into chapters with new ledes and closings per chapter. The email sequence builds on the source's framework with sender-voice adjustments. Social posts use platform-native conventions. The webinar adds Q&A and live elements. Output: each derivative earns engagement on its medium because it was made for that medium; the source piece's value compounds across formats. + +The litmus test. Read each derivative as if you had not seen the source piece. Does it stand on its own? Does it use the medium's conventions? Would it earn engagement if it were the only thing the audience saw of this work? If yes to all three, the adaptation succeeded. If the derivative reads as "I should have read the original instead," the adaptation failed. + +--- + +## Source-piece selection + +Not every piece is worth repurposing. Selection is the first discipline. + +Strong source-piece characteristics. + +- The source has a clear central argument or framework that travels across formats. +- The source has standalone sections, examples, or sub-arguments that work as derivative pieces. +- The source's audience overlaps with the audiences on the target formats. +- The source's voice is distinctive enough that derivative voice can stay coherent. +- The source has accumulated demand: traffic, links, mentions, social shares. + +Weak source-piece characteristics. + +- The source is a tightly-integrated argument where every section depends on context. +- The source is a list-style piece where the items do not have standalone weight. +- The source's value depended on being read end-to-end (a narrative arc, a layered argument with payoff). +- The source's audience does not exist on most target formats. +- The source's voice is generic; derivative voice has nothing to anchor. + +The selection audit. Run candidate pieces through these questions before committing to repurposing. Pieces that fail the audit may still be valuable but as one-and-done; programs that try to repurpose unsuitable pieces produce derivatives that feel forced. + +Detail in [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md). + +--- + +## Format adaptation patterns + +Eight common source-to-derivative adaptations with worked examples. + +Long-form to blog series. A 6,000-word whitepaper becomes 4-6 standalone blog posts, each developing one of the whitepaper's sub-arguments with new ledes and closings. + +Blog post to email sequence. A 1,500-word blog post on a multi-step framework becomes a 5-email sequence, one email per step, with sender-voice adaptation and per-email engagement hooks. + +Whitepaper to webinar. Substantive whitepaper becomes a 30-45 minute webinar with the whitepaper's framework as the spine, plus live Q&A, plus interactive elements that print do not support. + +Long-form to social posts. Pull-quote-style posts, framework summaries, key-question posts, contrarian-claim posts. Each social post is one moment from the source, framed for the platform's conventions. + +Article to podcast episode. Article becomes the episode's spine; the host adds context, examples, and conversational elaboration; sometimes a guest interview drives the episode while the article is the show notes. + +Long-form to video shorts. 60-90 second video clips on individual claims, examples, or framework elements from the source. Each short is a standalone unit; series-of-shorts can extend the source over weeks of social posting. + +Research report to FAQ extractions. Specific Q&A extractions from the source piece, formatted for AI search citation and snippet capture. + +Multi-piece source to ebook. Several related pieces (blog posts, articles, even social threads) consolidated into an ebook, with new connective tissue, an introduction that frames the body, and a conclusion that synthesizes. + +Detail in [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md). + +--- + +## Per-format constraints + +Each medium demands and forbids specific things. Repurposing that ignores the constraints produces derivatives that fail the medium. + +Email. + +- Subject line and preheader bear most of the engagement load. +- Plain prose paragraphs work; complex formatting often breaks across email clients. +- Length tolerance varies by audience; 200-800 words common. +- Single clear CTA per email; multiple competing CTAs underperform. + +Social posts (text-driven platforms). + +- Hook in the first 1-2 lines; readers decide to expand or scroll. +- Platform-specific conventions (LinkedIn long-post structure differs from X/Twitter thread structure). +- Visual or quote-graphic options to break up text. +- One specific point per post; multi-point posts dilute. + +Video (long-form). + +- Pacing differs from print; spoken delivery requires different sentence structure. +- Visuals carry information print does not need; talking-head video alone for 30+ minutes underperforms. +- Audio quality matters more than video quality up to a point; bad audio kills retention. + +Video (short-form). + +- 60-90 second window for most platforms; 15-30 seconds for some. +- Captions essential; many viewers watch without sound. +- Hook in the first 1-2 seconds; algorithmic recommendation rewards retention from second 1. +- One specific point or moment per short. + +Podcast. + +- Spoken-language sentence structure; print-style sentences read aloud sound stilted. +- Conversational pacing rewards examples and asides; tightly-argued print sections feel stiff. +- Show notes do the print work the audio cannot; treat show notes as a derivative format too. + +Webinar. + +- Live element: Q&A, polls, interactive moments. Static webinar is a video; interactive webinar earns the format. +- Slide design matters; text-heavy slides fail. +- Length: 30-60 minutes typical; longer requires high engagement design. + +Detail in [`references/per-format-constraints.md`](references/per-format-constraints.md). + +--- + +## Voice consistency across formats + +The source piece's voice anchors the derivatives. The discipline is staying recognizable through the format shifts. + +What stays constant. + +- The brand's POV on the topic. +- Distinctive vocabulary, specific framings, recognizable phrasings. +- The level of conviction or hedging the brand uses. +- The audience-respect register (talking up to, down to, alongside the audience). + +What adapts per format. + +- Sentence length and structure (spoken voice differs from written). +- Density (visual formats can carry less per minute than text). +- Conversational vs declarative register (podcasts are conversational; whitepapers declarative). +- Direct-address frequency ("you" usage varies by format). + +The voice audit per derivative. Read or watch the derivative. Does it sound like the brand? Could a reader who knows the source piece tell the derivative is from the same source? If voice has drifted to AI-default or to the platform's default register, the adaptation lost the voice. + +The AI-repurposing voice problem. AI-assisted repurposing is particularly prone to voice drift. The source piece may have specific voice characteristics; AI generation of derivatives without strong voice prompts produces derivatives that sound more generic than the source. See `ai-content-collaboration` for the voice-preservation discipline that applies to repurposing workflows. + +Detail in [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md). + +--- + +## Sequencing and cadence + +When to release derivatives relative to the source, and at what pace. + +Sequencing patterns. + +- Source-first, derivatives following. Source publishes; derivatives roll out over the following 2-12 weeks. The source carries authority; derivatives extend reach. +- Derivatives-first, source as anchor. Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship. Less common; works for built-up audiences who follow the program. +- Simultaneous launch. Source and a wave of derivatives publish on the same day. Maximum splash; risks audience fatigue if every channel is firing the same day. + +Cadence within the rollout. + +- Concentrated. Most derivatives ship within 4-6 weeks of source. Maximum momentum from the source's authority; minimum time for individual derivatives to land. +- Distributed. Derivatives ship over 3-6 months. Each derivative has space to land; the program is extracting value over a longer window; risks losing connection to source if the gap grows too long. +- Indefinite. Derivatives keep being created from the source as long as the source remains relevant. Common for evergreen flagship pieces; rare otherwise. + +The pacing audit. Match cadence to the source's traffic curve. Pieces with sharp early traffic (trending topics) benefit from concentrated rollout; pieces with sustained evergreen traffic can support distributed rollout over many months. + +Detail in [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md). + +--- + +## Cross-promotion across derivatives + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. + +Linking patterns. + +- Derivative back to source. Each derivative includes a link or reference to the source piece for readers who want depth. The source's traffic compounds. +- Source forward to derivatives. The source piece is updated to include links to derivatives as they ship. The source becomes the hub for the cross-format extension. +- Derivatives across. Where appropriate, derivatives link to other derivatives in the cross-format set. The series feeling helps audiences engage with multiple pieces. + +Attribution within derivatives. When a derivative is clearly drawn from a source piece, acknowledge: "This is adapted from our recent piece on X." Attribution earns reader trust; uncredited derivatives can feel like the same work being recycled without acknowledgment. + +Co-promotion across channels. A blog post derivative can be re-shared on social where the original blog post was; a social post derivative can be promoted in the email newsletter. Cross-channel flow extends each derivative's reach. + +Detail in [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md). + +--- + +## Repurposing for AI search visibility + +A specific repurposing pattern worth its own treatment. + +FAQ extraction. Pull specific question-answer pairs from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries that can be cited by AI search engines. + +Snippet design. Identify standalone paragraphs in the source that answer specific queries cleanly. These paragraphs can be quoted, schema-marked, and presented in derivative pieces or in dedicated FAQ pages. + +Statistic extractions. AI engines weight statistics with named sources. Extract specific stats from the source (with citations to the underlying primary research) into format that AI can cite cleanly. + +Definition and entity extractions. Source pieces often define specific terms or describe specific entities authoritatively. Extract these as standalone definitions in glossaries, FAQ pages, or knowledge-base entries. + +The AI-search-derivative discipline. Treat AI-search optimization as a derivative format with its own conventions: specific question framings, named-source citations, standalone-paragraph design. Pieces that do this well earn AI citations; pieces that do not still get cited but at lower rates and with less control over framing. + +Detail in [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md). + +- "Our derivatives feel like AI slop." Mass-blast pattern; AI-assisted repurposing without per-format adaptation. Cure: add adaptation discipline, voice prompts, per-format review. +- "We repurposed but engagement is low." Format constraints ignored. Cure: audit each derivative against per-format conventions. +- "The blog post derivative outperforms the source." Either the source was the wrong format for the topic (the derivative format fits better), or the derivative cannibalizes the source. Investigate. +- "We never reuse pieces." One-and-done pattern; the program is leaving 70-90% of source-piece value unrealized. +- "Our LinkedIn posts are blog-post text dumps." Mass-blast on a platform with specific conventions. Cure: rewrite for platform-native structure. +- "The email newsletter is the blog's first paragraphs with 'read more' tacked on." Mass-blast email pattern. Cure: rewrite as a standalone email with engagement hooks. +- "Our podcast episodes are articles read aloud." Print-to-audio without spoken-language adaptation. Cure: rewrite for spoken delivery; add conversational pacing. +- "We extracted FAQ pages but they are not getting cited by AI search." Format may be wrong (snippets not standalone) or content may not be authoritative enough; audit against AI-search norms. +- "Our voice drifts across derivatives." AI-repurposing voice failure. Cure: stronger voice prompts; per-derivative voice audit. +- "We launched 12 derivatives in a week and audiences were exhausted." Concentrated cadence too aggressive. Cure: distributed cadence with engagement-driven sequencing. +- "Our derivatives compete with the source for the same query." Cannibalization. Cure: clear primary-keyword assignment per piece; consolidate or restructure. + +--- + +## The framework: 12 considerations for content repurposing + +When designing or auditing a repurposing program, walk these 12 considerations. + +1. Adapt-by-format, not mass-blast or one-and-done. Each derivative respects its medium. +2. Source-piece selection. Strong sources have travelable arguments and standalone sections. +3. Format adaptation patterns chosen. Match source-piece characteristics to derivative formats. +4. Per-format constraints respected. Each medium's conventions, length norms, and reader expectations. +5. Voice consistency across formats. Brand POV stays; sentence structure adapts. +6. Sequencing and cadence planned. Source-first vs simultaneous; concentrated vs distributed. +7. Cross-promotion across derivatives. Linking, attribution, co-promotion. +8. AI-search extraction. FAQ, snippet, statistic, entity extractions designed deliberately. +9. Cannibalization avoided. Derivatives complement the source; do not compete for the same query. +10. Engagement-per-format measured. Derivatives evaluated on each medium's metrics. +11. AI-assisted repurposing with voice discipline. Voice prompts, per-derivative review, slop prevention. +12. Capacity allocation explicit. Repurposing is real work; budgeted, not done in the cracks. + +The output of the framework is a repurposing program that turns each strong source piece into a coherent multi-format extension, with each derivative earning engagement on its medium. + +--- + +## Reference files + +- [`references/source-piece-selection-criteria.md`](references/source-piece-selection-criteria.md) - Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. +- [`references/format-adaptation-patterns.md`](references/format-adaptation-patterns.md) - Eight source-to-derivative adaptations with worked examples. Long-form to blog series, blog to email, whitepaper to webinar, etc. +- [`references/per-format-constraints.md`](references/per-format-constraints.md) - What each medium demands and forbids. Email, social, video, podcast, webinar, AI search. Length norms, conventions, hooks. +- [`references/voice-consistency-across-formats.md`](references/voice-consistency-across-formats.md) - What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem. +- [`references/sequencing-and-cadence-patterns.md`](references/sequencing-and-cadence-patterns.md) - Source-first vs simultaneous vs derivative-first. Concentrated vs distributed cadence. Pacing audits. +- [`references/cross-promotion-patterns.md`](references/cross-promotion-patterns.md) - Linking patterns, attribution, co-promotion across channels. +- [`references/aeo-extraction-patterns.md`](references/aeo-extraction-patterns.md) - FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. +- [`references/repurposing-pipeline-templates.md`](references/repurposing-pipeline-templates.md) - Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. +- [`references/common-repurposing-failures.md`](references/common-repurposing-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: adaptation is craft, not duplication + +Repurposing is widely treated as a content multiplication problem to be solved with AI: feed the source into a tool, get derivatives out. The output of that approach is mass-blast, slop, and audiences that learn to ignore the program. The teams producing repurposing that earns engagement are the ones treating each derivative as a piece in its own right, adapted for its medium, written with the source's voice but the format's craft. + +Adaptation is craft, not duplication. The source piece is the starting material; the derivative is its own work. Programs that hold this discipline get value compounding across formats; programs that skip it produce a wall of derivative content that performs worse, not better, than publishing only the source. + +When in doubt about whether a repurposing program is ready, ask: does each derivative respect its medium's conventions, does voice stay consistent across the set, are derivatives cross-promoting and linking back to the source, is AI-search extraction part of the plan, is cannibalization being managed, is the cadence pacing earning engagement? If yes to all of those, the program is real. If no to any, the gap is where the derivatives will read as filler and audiences will tune out. diff --git a/skills/content-repurposing/references/aeo-extraction-patterns.md b/skills/content-repurposing/references/aeo-extraction-patterns.md new file mode 100644 index 0000000..3ec2330 --- /dev/null +++ b/skills/content-repurposing/references/aeo-extraction-patterns.md @@ -0,0 +1,205 @@ +# AEO extraction patterns + +FAQ extraction, snippet design, statistic extractions, entity extractions for AI search citation. The repurposing pattern that turns long-form content into AI-search-ready derivatives. + +AI search engines (the citation-driven generative answer engines) cite content in specific shapes. Pieces that are designed for citation get cited at higher rates and with better framing control; pieces that are not designed for citation still get cited but at lower rates and with less control over how the citation appears. + +The AEO (answer engine optimization) extraction is its own derivative format with its own conventions. Treating it as a derivative is the discipline. + +--- + +## The AEO extraction frame + +AI engines retrieve and cite content paragraph-by-paragraph or snippet-by-snippet. They favor content that: + +- Has standalone meaning (the snippet works without surrounding context). +- Cites named sources within the snippet (specific authority). +- Uses specific phrasings (queryable framings). +- Has structural signals (FAQ schema, headings, lists where appropriate). + +Source pieces written without these properties may have the same content but in shapes the engines do not cite cleanly. AEO extraction restructures the content into citation-ready shape. + +--- + +## Pattern 1: FAQ extraction + +The most common AEO extraction pattern. + +The shape. Specific question-answer pairs derived from the source piece. Each Q&A is 40-80 words. Format as standalone FAQ entries. + +Question framing. + +- Use phrasings users actually search. "What is X?" "How does X work?" "Why does X matter?" "When should I use X?" +- Avoid phrasings users do not search. "What are the considerations around X?" rarely matches search intent. +- Specific is better than generic. "How long should a B2B sales email be?" performs better than "What length should sales emails be?" + +Answer framing. + +- Standalone meaning. The answer works as a paragraph; no pronoun references that depend on outside context. +- Named source within the answer where applicable. "According to a 2025 Forrester study, B2B sales emails between 75 and 150 words have the highest reply rates" performs better than "Studies show shorter emails work better." +- Specific framings, not hedged. "The strongest length is 75-150 words" performs better than "Generally, shorter tends to be better." +- Length: 40-80 words typical. Longer answers get truncated or cited partially; shorter answers may not have enough substance to cite. + +Where the FAQ lives. + +- A dedicated FAQ section at the bottom of the source piece, schema-marked with FAQPage. +- A standalone FAQ page that aggregates multiple FAQs across topics, deeply linked to source pieces. +- Inline within the source piece as a callout box, surfacing the Q&A while the surrounding prose develops the topic. + +--- + +## Pattern 2: Snippet design + +Standalone paragraphs in the source piece designed to be citation-ready. + +The shape. A paragraph (100-200 words typical) that answers a specific query cleanly and can be cited as a unit. + +Snippet framing. + +- Opens with a specific claim or definition. Snippets that open with throat-clearing rarely get cited cleanly. +- Includes named source citations where the claims need authority. +- Uses specific framings. "B2B sales emails between 75 and 150 words have a 32% reply rate, compared to 18% for emails over 250 words" is citation-ready; "shorter emails tend to do better" is not. +- Stands alone. The paragraph's meaning does not depend on the prior or following paragraphs. + +Where snippets live. + +- Throughout the source piece as load-bearing paragraphs that incidentally meet snippet criteria. +- As deliberately-designed snippets in specific positions (often after each H2 question for AEO-optimized pieces; see `editorial-qa`'s SEO/AEO compliance for the answer-paragraph discipline). +- As standalone snippets in derivative pieces (FAQ pages, glossaries, knowledge-base entries). + +--- + +## Pattern 3: Statistic extractions + +AI engines weight statistics with named sources at high citation rates. + +The shape. Specific statistic with named source, framed for citation. + +Statistic framing. + +- The number is specific. "32% of B2B buyers" performs better than "around a third of buyers." +- The source is named. "According to the 2025 Salesforce State of Marketing report" performs better than "according to a recent study." +- The context is clear. "Among B2B SaaS buyers in the $50M-500M revenue band" rather than just "among buyers." +- The currency is specified. The stat's date matters for AI engines deciding which sources to cite as current. + +Where statistic extractions live. + +- Throughout the source piece where data supports claims. +- In dedicated "key statistics" callouts that schema-mark the stats. +- As standalone tweet-graphic-style social derivatives (the stat on its own with the source citation). +- In FAQ-style answers that frame "what does the data say about X?" + +The citation-laundering avoidance. Statistic extractions that cite secondary sources (other content marketing pieces) rather than primary sources reduce citation rates. AI engines increasingly detect citation laundering and discount it. + +--- + +## Pattern 4: Definition and entity extractions + +Source pieces often define specific terms or describe specific entities authoritatively. + +The shape. Standalone definitions or entity descriptions that can serve as canonical references. + +Definition framing. + +- "X is [definition], typically [characterization], distinguished from [related concept] by [distinction]." +- 50-150 words for substantive definitions. +- Specific authority signals: who developed the concept, when, in what context. + +Entity framing. + +- For products, companies, frameworks: who, what, when, why, where used. +- Specific dates, named people, named organizations. +- Source attribution where the entity claim depends on authority. + +Where definition and entity extractions live. + +- Glossary pages. Many programs underuse glossaries; they are AI-search valuable real estate. +- Knowledge-base entries. +- Schema-marked definitions within source pieces (Article schema with appropriate sub-types). +- Wikipedia and similar entity authorities where the entity is significant enough to warrant external listings (different from on-property AEO but related; AI engines weight cross-source consistency). + +--- + +## Pattern 5: Comparison extractions + +Source pieces that compare options, frameworks, or approaches produce comparison-extraction derivatives. + +The shape. Side-by-side or table comparisons with specific axes, citation-ready. + +Comparison framing. + +- Defined axes (price, feature set, fit, scale). +- Specific values per axis per option. +- Tradeoff summary that AI can quote. +- Recommendation framing where the source piece commits a position. + +Where comparison extractions live. + +- Tables within the source piece, schema-marked where appropriate. +- Standalone comparison pages. +- FAQ-style answers framing "How does X compare to Y?" +- Decision-guide derivatives that walk readers through the comparison. + +--- + +## Pattern 6: How-to extractions + +Source pieces with sequential instructions produce how-to extractions. + +The shape. Step-by-step instructions that AI can cite as a procedure. + +How-to framing. + +- Numbered steps in a clear sequence. +- Each step is a complete instruction (not "do this, then that" run together). +- Schema-marked with HowTo where the source is an instructional piece. + +Where how-to extractions live. + +- Within source pieces as schema-marked procedures. +- Standalone how-to pages on specific tasks. +- Tutorial derivatives in video format. + +--- + +## AEO extraction failures + +Generic FAQs. Questions that do not match user search phrasings get little citation. Cure: query research; phrase questions in user voice. + +Context-dependent answers. Answers that reference "this approach" or "the method described above" do not cite cleanly. Cure: each answer is rewritten to stand alone with full context. + +Hedged answers. "Generally, in some cases, depending on context, X might work" rarely gets cited. AI engines prefer specific framings. Cure: where the source piece is genuinely uncertain, scope the answer to the specific case where the answer is specific. + +Missing schema. FAQs and snippets without schema markup do not signal cleanly to engines. Cure: add appropriate schema (FAQPage, HowTo, Article) where formats fit. + +No source citations within answers. Statistics and specific claims without named sources within the answer paragraph get cited at lower rates. Cure: include source citations within the answer body, not just in surrounding context. + +Citation laundering. FAQs citing other content marketing pieces rather than primary sources. Cure: trace claims to primary sources; cite the primary. + +Over-extraction. Producing 50 FAQs from a 5,000-word source piece dilutes; not every question deserves a standalone FAQ. Cure: extract the 10-15 highest-value questions; let the rest live within the source's prose. + +--- + +## AEO extraction integration with the cross-format set + +AEO extractions integrate with other derivatives. + +FAQ pages link to the source. The FAQ page is a derivative; the source piece is the canonical version. Cross-promotion follows the standard pattern. + +Statistic extractions appear in social posts. Each stat with its source citation can become a social post (often with quote-graphic visual treatment). + +Definition extractions appear in glossaries that the source piece links to. The glossary entry serves as the canonical definition for the term across the program. + +Comparison extractions appear in decision-guide derivatives. The comparison from the source becomes the spine of a separate decision-guide piece. + +The integration discipline. AEO extraction is one derivative type among several; the cross-format set's coordination includes the AEO extractions, not as a separate workflow but as part of the rollout plan. + +--- + +## Methodology-level choices that stay in the public skill + +The six AEO extraction patterns, the question/answer/snippet framing principles, the schema markup integration, the AEO extraction failures, the integration with the broader cross-format set. + +## Implementation choices that stay internal + +Specific schema markup automation. Specific FAQ-page templates in the team's CMS. Specific glossary-page architecture. Specific statistic-extraction tooling. Specific monitoring of AI citation rates per piece. The team's own conventions for FAQ length within the bands. These vary by team, CMS, and AI-citation tracking infrastructure. diff --git a/skills/content-repurposing/references/common-repurposing-failures.md b/skills/content-repurposing/references/common-repurposing-failures.md new file mode 100644 index 0000000..63412eb --- /dev/null +++ b/skills/content-repurposing/references/common-repurposing-failures.md @@ -0,0 +1,175 @@ +# Common repurposing failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most repurposing failures share a single root, which is treating repurposing as content multiplication rather than as cross-format craft. + +--- + +## Failure 1: Mass-blast (same content reposted across channels) + +Symptom. Blog post text pasted into LinkedIn as a long post. Email is the blog's first three paragraphs with "read more." YouTube version is a slideshow of the article text read aloud. + +Diagnosis. Repurposing without per-format adaptation. The team is treating "more channels" as the goal rather than treating each derivative as a piece adapted for its medium. + +Cure. Apply the per-format constraints discipline (see `per-format-constraints.md`). Each derivative gets rewritten for the target format. AI-assisted repurposing without strong format prompts produces this failure; the cure includes voice prompts and per-format instructions. + +--- + +## Failure 2: AI-slop derivatives + +Symptom. Derivatives feel like AI slop. Generic, derivative, signal-less. Voice has drifted from the source. + +Diagnosis. AI-assisted repurposing without voice discipline. AI generation regresses to model defaults; multiple derivatives generated without voice anchor compound the drift. + +Cure. Apply the voice-consistency-across-formats discipline (see `voice-consistency-across-formats.md`). Voice prompts including sample text from the source. Per-derivative voice review. Reject the bland; rewrite generic sentences in voice. See also `ai-content-collaboration` for the broader voice-preservation discipline. + +--- + +## Failure 3: One-and-done + +Symptom. Source pieces publish; never get repurposed. The team produces new flagship work continuously while older flagship work sits unused. + +Diagnosis. No repurposing discipline; the team treats publication as the end of the piece's life. Most of the source-piece value goes unrealized. + +Cure. Establish source-piece tiering (see `source-piece-selection-criteria.md`). Tier 1 and Tier 2 pieces get cross-format extension plans at production time. Capacity allocation for repurposing becomes a real budget line. + +--- + +## Failure 4: Repurposing the wrong pieces + +Symptom. Repurposing capacity goes to pieces that resist extension. The derivatives feel forced; engagement is low. + +Diagnosis. Source-piece selection is choosing pieces by availability rather than by suitability. Pieces with tightly-integrated arguments, list-style structure, or no demand signal are being repurposed when they should stay one-and-done. + +Cure. Apply the selection audit. Run candidates through the strong vs weak source-piece characteristics. Some pieces stay one-and-done; that is the right disposition for them. + +--- + +## Failure 5: Format constraints ignored + +Symptom. Derivatives feel awkward on their target formats. Engagement is low. Audiences scroll past or unsubscribe. + +Diagnosis. Each medium has constraints; the derivatives violate them. LinkedIn long posts as walls of text; emails as image-only layouts; podcasts as articles read aloud. + +Cure. Apply the per-format constraints discipline. Each format has demand-and-forbid lists. Derivatives must respect them, even at cost of departing from the source's surface. + +--- + +## Failure 6: Derivative outperforms source (cannibalization) + +Symptom. A blog-post derivative outperforms the source whitepaper for the source's target keyword. Authority is splitting between the two pieces. + +Diagnosis. Either the source was the wrong format for the topic (the derivative format fits SERP intent better), or the derivative is targeting the same keyword as the source and cannibalizing. + +Cure. Two options. If the source was the wrong format, consider whether the derivative should become the canonical piece (with the source decommissioned or repositioned). If the derivative is cannibalizing, reassign primary keywords: the source keeps the high-value head term; the derivative gets a long-tail variant. + +--- + +## Failure 7: Voice drift across the cross-format set + +Symptom. Each derivative is fine alone but the cross-format set reads as voice variants. Audiences who follow the program notice the inconsistency. + +Diagnosis. Multiple writers or AI generators produced derivatives without voice coordination. Voice drifted across producers. + +Cure. Single voice owner across the cross-format set. Voice library with examples. Calibration sessions where multiple writers reconcile voice expectations. AI tools include the same voice prompts across all derivative generations. + +--- + +## Failure 8: Cadence too aggressive + +Symptom. Cross-format set ships a wave of 12 derivatives in one week. Audiences disengage by day 3. Most derivatives produce minimal engagement. + +Diagnosis. Concentrated cadence too tight for the audience attention rhythm. The cross-format presence on a single week exhausts rather than reinforces. + +Cure. Apply the sequencing-and-cadence discipline. Match cadence to source's traffic curve and audience attention norms. Most cross-format sets benefit from concentrated-but-not-collapsed pacing (4-6 weeks rather than 1 week). + +--- + +## Failure 9: No cross-promotion + +Symptom. Derivatives ship in isolation. No links to source. No links between derivatives. No mention of the cross-format set on the channels where audiences could discover it. + +Diagnosis. Cross-promotion was treated as optional or as an afterthought. The compounding effects of cross-linking and co-promotion are missing. + +Cure. Apply the cross-promotion discipline (see `cross-promotion-patterns.md`). Every derivative includes a derivative-to-source link. The source piece is updated to reference derivatives. Co-promotion across channels is planned at rollout time. + +--- + +## Failure 10: AEO extraction skipped or generic + +Symptom. The cross-format set ships without FAQ extractions or with generic FAQ extractions. AI-search citation rates are low. + +Diagnosis. AEO extraction was not part of the plan, or the FAQ questions do not match user search phrasings, or the answers are context-dependent rather than standalone. + +Cure. Apply the AEO extraction patterns. Treat FAQ extraction, snippet design, and statistic extractions as derivative formats with their own conventions. Schema-mark where appropriate. + +--- + +## Failure 11: No source-piece updating after rollout + +Symptom. The source piece publishes; derivatives ship; the source piece is never updated to reference the derivatives. The source remains static. + +Diagnosis. The forward-promotion from source to derivatives was skipped. The source's role as cross-format hub is wasted. + +Cure. Plan source-piece updates as part of the rollout. As each derivative ships, the source's "related" or "see also" section gets updated. The source becomes a navigation hub for the cross-format set. + +--- + +## Failure 12: Capacity underestimation + +Symptom. The team planned 30 hours for a whitepaper repurposing pipeline; actual cost is 70 hours. New production suffers; team burns out. + +Diagnosis. Capacity estimates were based on optimistic assumptions or on prior pipelines that were not as substantial. + +Cure. Track actual capacity per pipeline (see `repurposing-pipeline-templates.md`). Calibrate estimates over time. Some pipelines genuinely cost more than the team has budget for; the right answer may be to reduce scope rather than to overrun. + +--- + +## Failure 13: No measurement + +Symptom. Cross-format sets ship; the team has a vague sense some perform better than others; the program does not learn. + +Diagnosis. No per-pipeline or per-derivative tracking. Outcomes are anecdotal rather than data-driven. + +Cure. Establish a minimum log per pipeline run: source piece, derivatives planned vs delivered, capacity spent, outcomes per derivative, lessons learned. Pattern-detect across pipelines to inform future ones. + +--- + +## Failure 14: Pipeline dogmatism + +Symptom. The team applies the same pipeline template to every source piece regardless of the source's characteristics or the audience overlap. Some derivatives consistently underperform; the team keeps producing them anyway. + +Diagnosis. Treating templates as fixed shapes rather than as starting points to customize. + +Cure. Customize pipelines per source piece. Audience characteristics, source characteristics, and capacity should adjust the cross-format set. Drop derivatives that consistently underperform for the program's audience mix. + +--- + +## Failure 15: AI repurposing as the strategy + +Symptom. "We use AI to repurpose, so we can scale." The output is a wave of low-engagement derivatives across many channels. The team is producing more derivative content than ever; engagement is flat or declining. + +Diagnosis. AI is being treated as a substitute for the craft of cross-format adaptation. Volume is being prioritized over quality. + +Cure. AI is a tool within the workflow, not the workflow itself. The discipline of adaptation per medium is still the work; AI accelerates parts of it. See `ai-content-collaboration` for the workflow discipline that prevents AI-assisted repurposing from drifting into mass-blast and slop. + +--- + +## The cross-cutting pattern + +Most repurposing failures share a single root: treating repurposing as content multiplication rather than as cross-format craft. + +Multiplication thinking treats each derivative as another item in a quota: more channels, more pieces, more reach. The output is mass-blast and slop because adaptation is skipped. + +Craft thinking treats each derivative as a piece in its own right, adapted for its medium, holding the source's voice while respecting the format's conventions. The output is a coherent cross-format set where each derivative earns engagement on its medium. + +The fix for almost any repurposing failure is the same: stop multiplying, start adapting. The capacity required for craft-driven repurposing is higher than multiplication-driven repurposing; the value extracted is also higher, often by an order of magnitude. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the multiplication-vs-craft framing. + +## Implementation choices that stay internal + +Specific tooling for derivative tracking. Specific reporting templates for cross-format outcomes. Specific reviewer training on per-format conventions. Specific automation that flags voice drift across derivatives. The team's own conventions for failure-pattern detection in their pipelines. These vary by team and tooling. diff --git a/skills/content-repurposing/references/cross-promotion-patterns.md b/skills/content-repurposing/references/cross-promotion-patterns.md new file mode 100644 index 0000000..e775ee6 --- /dev/null +++ b/skills/content-repurposing/references/cross-promotion-patterns.md @@ -0,0 +1,170 @@ +# Cross-promotion patterns + +Linking patterns, attribution, and co-promotion across channels. The mechanics that turn a cross-format set into a coordinated extension rather than scattered derivatives. + +Derivatives that link to each other and to the source compound. Derivatives that ship in isolation underperform. The cross-promotion discipline is small per-derivative but compounds significantly across the set. + +--- + +## Derivative back to source + +Each derivative includes a link or reference to the source piece for readers who want depth. + +The pattern. + +- Blog-post derivative includes "This is one of six pieces drawing from our recent whitepaper on X. Read the full whitepaper here." +- Email derivative ends with "Want the full framework? Read the original piece here." +- Social-post derivative includes a link to the source in profile, in comments, or as part of a multi-post thread. +- Podcast episode show notes link to the source article. +- Video description links to the source. + +Why it works. The source's traffic compounds. Audiences who engage with a derivative and want depth click through; the source piece earns continued traffic from the cross-format set. The source's authority benefits from the inbound links from derivative pieces. + +The discipline. Every derivative includes a derivative-to-source link as a non-negotiable element of the format adaptation. The link is not buried; it is positioned where readers who want more naturally find it. + +--- + +## Source forward to derivatives + +The source piece is updated to include links to derivatives as they ship. + +The pattern. + +- A "related" or "see also" section at the end of the source piece, updated as derivatives ship. +- Inline links from specific source sections to corresponding derivatives that develop those sections. +- A dedicated "this piece's extensions" callout linking to the cross-format set. + +Why it works. The source becomes the hub for the cross-format extension. Audiences who land on the source can navigate to derivatives that match their preferred format. The source's role as canonical anchor strengthens. + +The discipline. Update the source piece as the cross-format set rolls out. Stale source pieces that do not reference their derivatives miss the cross-promotion opportunity. + +--- + +## Derivatives across + +Where appropriate, derivatives link to other derivatives in the cross-format set. + +The pattern. + +- Blog post 3 in a series links to blog posts 1, 2, 4, 5, 6 either inline or in a "more in this series" footer. +- Email 5 in a sequence references email 4's framework or previews email 6. +- Podcast episode show notes link to a related video, blog series, or webinar. +- Webinar registration page links to the relevant blog series and the underlying source piece. + +Why it works. The series feeling helps audiences engage with multiple pieces. Internal linking compounds across the set. SEO benefits accrue when derivatives strengthen each other's authority. + +The discipline. Plan the cross-derivative link graph at production time. Each derivative's link plan is part of the production work, not an afterthought. + +--- + +## Attribution within derivatives + +When a derivative is clearly drawn from a source piece, acknowledge. + +The pattern. + +- "This is adapted from our recent piece on X." +- "Drawing from our research on [topic]." +- "Originally published as [source piece title]." +- For social posts: "From our recent whitepaper on X, [insight]." + +Why it works. Attribution earns reader trust. Uncredited derivatives can feel like the same work being recycled without acknowledgment; audiences notice and discount the program's perceived effort. + +The discipline. Attribution is honest about the derivative status. The format adaptation is the value-add; pretending the derivative is independent work overstates the production effort and reads as low-trust positioning. + +Anti-pattern: hiding derivatives. Some teams treat derivatives as if they were independent pieces, with no acknowledgment that they draw from a source. Audiences who follow the program detect the recycling and the cross-format coherence is lost. + +--- + +## Co-promotion across channels + +Derivatives can be promoted on channels other than the channel where they natively live. + +The pattern. + +- A blog post derivative gets re-shared on social where the original blog post might not have been re-shared without the derivative pretext. +- A social post derivative gets mentioned in the email newsletter as "our latest LinkedIn post on X." +- A podcast episode gets promoted on social, in the email, and on the blog. +- A video derivative gets embedded in a blog post or shared via email. + +Why it works. Each derivative's reach extends beyond its native channel. Audiences encountering a derivative through cross-channel promotion discover both the derivative and the channel where it lives. + +The discipline. Plan cross-channel promotion as part of the rollout. Each derivative has a primary channel (where it lives natively) and a secondary channel set (where it gets promoted from). The plan is explicit, not improvised. + +--- + +## Internal linking refresh on related pieces + +Pieces in the library that are related to the source's topic may benefit from updated internal linking when the source's cross-format set rolls out. + +The pattern. + +- Sister pieces that mention the source's topic get updated to link to the source piece (if they did not already) and possibly to the most relevant derivative. +- Pieces in the same hub or category get updated where the cross-format set makes new linking opportunities sensible. +- Anchor text on existing internal links may benefit from refresh if the source's positioning shifted. + +Why it works. The source's authority benefits from internal links across the library. Derivatives benefit from being part of the link graph rather than orphaned. + +The discipline. Run a brief internal-linking audit when the cross-format set rolls out. The audit catches obvious linking opportunities; over-investing in this pass is the failure mode (touching too many pieces, producing diminishing returns). + +--- + +## The cross-promotion graph + +Visualizing the cross-promotion structure as a graph helps catch gaps. + +Nodes. The source piece and each derivative. + +Edges. + +- Source-to-derivative links. +- Derivative-to-source links. +- Derivative-to-derivative links. +- Cross-channel co-promotion (each channel promoting each piece). + +Audit. Each derivative should connect to the source. Each derivative should connect to at least one other derivative where format-appropriate. Each derivative should be co-promoted on at least one secondary channel where audience overlap exists. + +Output of the audit. A planned link and promotion graph for the cross-format set, with the gaps identified before the rollout begins. + +--- + +## Common cross-promotion failures + +Derivatives shipping in isolation. Each derivative ships without links to source or to other derivatives. The cross-format set reads as scattered pieces; the compounding effect of cross-linking is lost. + +Source piece not updated. Source publishes; derivatives ship; the source piece is never updated to reference the derivatives. The hub function of the source is wasted. + +Attribution skipped. Derivatives ship without acknowledging the source. Audiences detect the recycling; trust degrades. + +Cross-channel co-promotion skipped. Each derivative stays on its native channel. Reach is limited to the audiences who happen to be on each channel. + +Internal-linking refresh skipped. Existing pieces in the library do not get linked to the new source piece. The library's internal-link graph stays static; the source piece's authority does not benefit. + +Over-investment in cross-promotion. Internal-link refresh that touches 50+ pieces in the library produces diminishing returns and maintenance overhead. Cure: target the highest-value linking opportunities; skip the marginal ones. + +--- + +## Cross-promotion in mature programs + +Programs with established cross-promotion discipline accumulate compounding effects over time. + +The pattern in mature programs. + +- Every flagship piece has an established cross-format extension plan. +- Every derivative has documented linking and promotion structure. +- The library's internal-link graph reflects accumulated cross-promotion across multiple cross-format sets over years. +- Audiences trust that pieces from the program connect; navigation between pieces feels intuitive. + +The compounding effect. Older flagship pieces continue to draw traffic because their cross-format sets extended their reach; their derivatives continue to draw traffic because their cross-promotion brought audiences in. The library's traffic profile reflects accumulated cross-format work, not just individual-piece performance. + +The maturity audit. Do new flagship pieces' cross-format sets connect to older flagship pieces' cross-format sets where topics overlap? Mature programs cross-promote across time; immature programs treat each cross-format set as isolated. + +--- + +## Methodology-level choices that stay in the public skill + +The cross-promotion link patterns, attribution discipline, co-promotion across channels, internal linking refresh, the cross-promotion graph, the common failures, the maturity-audit pattern. + +## Implementation choices that stay internal + +Specific link-graph tooling. Specific automation that surfaces missing cross-format links. Specific channel-promotion calendars. Specific internal-link audit tools. The team's own conventions for attribution language. These vary by team, CMS, and tooling. diff --git a/skills/content-repurposing/references/format-adaptation-patterns.md b/skills/content-repurposing/references/format-adaptation-patterns.md new file mode 100644 index 0000000..18b376f --- /dev/null +++ b/skills/content-repurposing/references/format-adaptation-patterns.md @@ -0,0 +1,202 @@ +# Format adaptation patterns + +Eight source-to-derivative adaptations with worked examples. The patterns that distinguish thoughtful adaptation from mass-blast. + +Each pattern below is a recurring shape: a particular source-piece type adapting into a particular derivative format. The patterns are not the only adaptations; they are the most common, with the most predictable success and failure modes. + +--- + +## Pattern 1: Long-form to blog series + +Source. A 4,000-8,000 word whitepaper, definitive guide, or research report. + +Derivatives. 4-6 standalone blog posts. Each post takes one of the source's H2 sections (or one of its sub-arguments) and develops it as a piece in its own right. + +Adaptation work. + +- New lede per post. The source's lede establishes the whole piece's thesis; each derivative needs its own lede that establishes its standalone scope. +- New closing per post. Source closing addresses the whole piece's argument; derivative closings address the post's specific argument. +- Connective tissue. Each derivative briefly references the source piece ("This is one of six pieces drawing from our recent whitepaper on X") and links forward to other derivatives in the series and back to the source. +- SEO targeting per derivative. The source piece may target one primary keyword cluster; each derivative can target a more specific long-tail keyword. + +Example. A whitepaper "The complete framework for content distribution" with H2 sections on owned, earned, paid channels, audience-channel matching, content-channel matching, and distribution measurement. Derivatives: 6 blog posts, one per section, each developing the section into a standalone piece (typically 1,200-1,800 words each). + +Common failures. + +- Derivative posts that are paste-ins of source sections without rewriting. Reads as duplicate content; SEO penalty risk; voice flatness. +- Derivative posts that compete with the source for the same keyword (cannibalization). Cure: explicit primary-keyword assignment per piece, with derivatives on long-tail variants. +- Derivative posts that drop the source's voice. Cure: voice prompts and review per derivative. + +--- + +## Pattern 2: Blog post to email sequence + +Source. A 1,200-2,500 word blog post on a multi-step framework, methodology, or process. + +Derivatives. 3-7 emails delivered over 1-3 weeks. Each email develops one step or section of the source's framework with sender-voice adaptation. + +Adaptation work. + +- Sender voice. Email voice is more direct and conversational than blog voice. Sentences shorter; "you" usage higher; more direct address. +- Engagement hooks per email. Subject line and preheader carry most of the email's open-rate burden. Hooks need to be earned per email. +- One CTA per email. Email format rewards single clear CTAs; multi-CTA emails underperform. +- Sequential building. Each email assumes the prior emails have been read; the sequence builds; the final email synthesizes. + +Example. A blog post on "the 5-step framework for product launches" becomes a 6-email sequence: introduction email, one email per step, synthesis email. Each email is 200-500 words with a single CTA. + +Common failures. + +- Emails that are blog paragraphs with "read more" links. Mass-blast pattern. +- Emails that lose voice consistency. Cure: voice anchored to source's distinctive register; per-email review. +- Sequences that are too long. 12-email sequences from a 1,500-word source are over-extension; audiences disengage. Cure: match sequence length to source's actual content depth. + +--- + +## Pattern 3: Whitepaper to webinar + +Source. A substantive whitepaper or research report. + +Derivatives. A 30-45 minute webinar with the whitepaper's framework as the spine, plus live elements that print does not support: Q&A, polls, interactive moments, possibly guest appearances. + +Adaptation work. + +- Spine selection. The webinar typically takes the whitepaper's 3-5 most load-bearing sections as its spine. Lower-priority sections from the source become spoken asides or get cut. +- Spoken-language adaptation. Print-style sentences read aloud sound stilted. The webinar script (or speaker notes) is rewritten in spoken voice. +- Interactive design. Polls, Q&A, audience prompts. Webinar without interactivity is a video; webinar with interactivity earns the format. +- Slide design. Text-heavy slides fail; the visual layer carries the audience's attention while the speaker delivers the content. +- Recording and follow-up. Most webinars become video derivatives after the live session; the recording extends value indefinitely. + +Example. A 6,000-word research report on B2B paid media benchmarks becomes a 40-minute webinar: 25-minute walkthrough of the report's framework with the speaker's commentary, 10-minute Q&A, 5-minute conclusion with specific recommendations. The recording is later cut into derivative video clips. + +Common failures. + +- Webinars that read the whitepaper aloud. The whitepaper is published; the webinar adds nothing. +- No interactivity. Live audiences disengage when the format is one-way. +- Text-heavy slides that compete with the speaker. Cure: visuals carry the design; speaker carries the content. + +--- + +## Pattern 4: Long-form to social posts + +Source. A long-form piece (whitepaper, definitive guide, research report). + +Derivatives. 8-30 social posts across the platforms where the audience exists. Each post is one specific moment from the source: a pull quote, a framework summary, a key statistic, a contrarian claim. + +Adaptation work. + +- Platform-specific structure. LinkedIn long-post structure differs from X/Twitter thread structure differs from Threads structure. Adaptation is per platform. +- Hook in the first 1-2 lines. Social readers decide to expand or scroll within seconds; the hook earns expansion. +- Visual or quote-graphic options. Many social posts benefit from accompanying visuals (quote graphics, statistic graphics, framework diagrams). +- One specific point per post. Multi-point social posts dilute; one clear point earns engagement. +- Series cadence. Posts shipped over weeks rather than dumped in one day; audiences engage with each post if they are spaced. + +Example. A whitepaper on AI search optimization becomes 18 social posts: 6 framework-summary posts, 4 statistic posts (with custom graphics), 4 contrarian-claim posts, 4 question-prompt posts. Distributed over 6 weeks across LinkedIn and X. + +Common failures. + +- Posts that are quote graphics with no context. The graphic is decoration; the post needs text that earns engagement. +- Posts that read as blog-text paste-ins. Mass-blast on social. +- Cadence too aggressive. 18 posts in one week exhausts audiences; distributed cadence performs better. + +--- + +## Pattern 5: Article to podcast episode + +Source. A substantive article (1,500-3,500 words). + +Derivatives. A podcast episode with the article as spine, plus host commentary, examples, and possibly guest interviews. + +Adaptation work. + +- Spoken-language adaptation. Article sentences read aloud sound stiff. The episode script (or talking-points outline) is in spoken voice. +- Conversational pacing. Examples and asides that print would cut earn their place in audio because the conversation needs space to breathe. +- Show notes as derivative format. The show notes do the print work the audio cannot: links, citations, structured summary. Treat show notes as a derivative in their own right. +- Guest dynamics where applicable. Some podcast episodes pair the article's framework with guest perspective; the article is the show's structured input, the guest adds expert commentary. + +Example. An article on programmatic SEO durability becomes a podcast episode: 5-minute introduction by the host, 30-minute interview with a practitioner who has run programmatic operations, 10-minute synthesis by the host. Show notes link to the source article and to several mentioned references. + +Common failures. + +- Episodes that read the article aloud. The article is published; the episode adds nothing. +- Episodes without spoken-language adaptation. Stilted delivery; low completion rates. +- Show notes that are afterthoughts. Show notes that fail their own format reduce the episode's discoverability and value. + +--- + +## Pattern 6: Long-form to video shorts + +Source. A long-form piece with travelable elements (specific examples, framework moments, contrarian claims). + +Derivatives. 6-20 short-form video clips, 30-90 seconds each. Each short is one standalone moment. + +Adaptation work. + +- Hook in seconds 1-2. Algorithmic recommendation rewards retention from second 1; openings must earn continued viewing. +- Captions essential. Many viewers watch without sound; captions carry the message. +- Visual presence. Talking-head shorts work for some audiences; many short-form platforms reward visual variation, motion, or text-on-screen design. +- Single specific point per short. Short-form does not support multi-point delivery; one moment per clip. +- Platform-specific aspect ratios and conventions. TikTok shorts, Instagram Reels, YouTube Shorts each have specific norms. + +Example. A research report becomes 12 video shorts: 4 statistic shorts (text-on-screen with audio narration), 4 framework moment shorts (whiteboard-style explanation), 4 contrarian-claim shorts (talking head). Distributed across LinkedIn video, YouTube Shorts, Instagram Reels. + +Common failures. + +- Shorts without strong opening hooks. Algorithmic feed deprioritizes; reach is minimal. +- Shorts without captions. 50%+ of audience cannot consume the content. +- Shorts that try to cover too much in 60 seconds. Cure: one moment, one point, one short. + +--- + +## Pattern 7: Research report to FAQ extractions + +Source. A research report or definitive guide with specific Q&A-able material. + +Derivatives. Standalone FAQ entries (40-80 words each), formatted for AI search citation, possibly aggregated into FAQ pages or schema-marked snippets within the source piece. + +Adaptation work. + +- Question framing. AI search engines cite content that matches likely user-query phrasings. FAQ questions need to use the phrasings users actually search. +- Standalone answer paragraphs. Each FAQ answer must work as a standalone paragraph; AI engines cite paragraphs, not contextual passages. +- Source attribution within the answer. Statistics and specific claims need named sources within the answer paragraph; AI engines weight named-source claims at higher rates. +- Schema markup. FAQPage schema where the FAQ aggregates as a dedicated page; structured data signals the format to search engines. + +Example. A research report on content distribution effectiveness becomes 15 FAQ extractions: "What channels produce highest engagement for B2B content?" "How does audience size affect channel selection?" "What is the typical engagement rate decay across channel types?" Each Q&A is 40-80 words with named-source citations. + +Common failures. + +- Questions that do not match how users phrase queries. Cure: query research; phrase questions in user voice. +- Answers that depend on context outside the answer paragraph. AI engines may not cite cleanly; paragraphs need to stand alone. +- Missing schema markup. The FAQ format does not signal cleanly to search engines without schema. + +--- + +## Pattern 8: Multi-piece source to ebook + +Source. Several related pieces (blog posts, articles, social threads) that together cover a topic. + +Derivatives. An ebook with the multi-piece content as the bulk, plus new connective tissue: introduction, chapter framings, conclusions, and possibly new chapters that fill gaps the source pieces did not cover. + +Adaptation work. + +- Topic synthesis. The multi-piece source covers the topic in scattered ways; the ebook needs to organize the content into a coherent sequence. +- New connective tissue. Introductions, chapter prefaces, transitions, conclusion. Often 20-30% of the ebook is new content not present in the source pieces. +- Voice consolidation. Pieces written over months may have voice variation; the ebook needs to read as one unified work, which often means rewriting passages to match a target voice. +- Design and production. Ebook format expectations: chapter design, table of contents, possibly downloadable PDF. Higher production cost than other repurposing patterns. + +Example. Twelve blog posts on a topical theme, written over 18 months, are consolidated into a 22,000-word ebook. New material includes a 1,500-word introduction, chapter framings totaling 3,000 words, a 1,500-word conclusion, and a 2,500-word new chapter that fills a gap the original posts did not address. + +Common failures. + +- Ebook that reads as posts stitched together. Cure: rewrite for unity; the ebook is a piece in its own right. +- No new connective tissue. The ebook adds no value over reading the source pieces. +- Voice inconsistency. Voice drift across pieces becomes visible when consolidated; cure: unified voice editing pass. + +--- + +## Methodology-level choices that stay in the public skill + +The eight adaptation patterns with their work, examples, and common failures. The recurring lesson: adaptation is per-format craft, not source-text recycling. + +## Implementation choices that stay internal + +Specific platform automation tooling. Specific design templates per derivative format. Specific tooling for video clip extraction from longer videos. Specific show-notes templates. Specific schema markup patterns the team uses for FAQ extractions. The team's own conventions for connective-tissue length in ebook consolidation. These vary by team, stack, and platform mix. diff --git a/skills/content-repurposing/references/per-format-constraints.md b/skills/content-repurposing/references/per-format-constraints.md new file mode 100644 index 0000000..df75a32 --- /dev/null +++ b/skills/content-repurposing/references/per-format-constraints.md @@ -0,0 +1,192 @@ +# Per-format constraints + +What each medium demands and forbids. Length norms, conventions, hooks, and the underlying observation: derivatives that ignore the medium's constraints fail the medium even when the source content was strong. + +Each format below has specific reader expectations. Pieces that meet expectations earn engagement; pieces that violate expectations get scrolled past or ignored regardless of content quality. Repurposing capacity goes to waste when derivatives fail the format-specific tax. + +--- + +## Email + +Length norms. 200-800 words per email for most B2B and consumer audiences. Newsletter-style emails can run longer (1,500-3,000 words) for engaged audiences but shorter is generally safer. + +What email demands. + +- A subject line that earns the open. Most engagement happens or fails at the subject-line level. +- A preheader that supports the subject line. The preheader is the second-most-read element of the email and most templates underuse it. +- Plain prose paragraphs that render reliably. Many email clients break complex formatting; tables, columns, and rich layouts can fail. +- A single clear CTA. Multi-CTA emails dilute; readers process one action at a time. +- Mobile-first design. 60-70% of email opens are on mobile; readability on small screens is essential. + +What email forbids. + +- Image-only emails. Many clients block images by default; image-only emails arrive blank. +- Link-laden text dumps. More than 3-4 links in body text dilutes attention. +- Multi-CTA layouts that compete for the click. +- Subject lines that announce the topic without earning the open ("Newsletter for week of X"). + +Adaptation discipline. Email derivatives need new ledes (the source's lede does not transfer); spoken-direct voice (more "you" usage; shorter sentences than blog voice); a single CTA per email even when the source piece had multiple potential actions. + +--- + +## LinkedIn (long-form text post) + +Length norms. 800-2,500 characters typical; long-form posts up to ~3,000 characters. The character count matters because the platform truncates with "see more"; the truncation point is the hook. + +What LinkedIn demands. + +- A first line that earns the "see more" click. The first 1-3 lines determine whether readers expand the post. +- Clear structure: short paragraphs, white space, occasional emphasis. Walls of text get scrolled past. +- A specific point or argument. Narrative-style posts that take time to land work; vague observations do not. +- Engagement hooks: questions, polarizing claims, specific examples that invite comment. +- Original perspective. Repurposed content marked clearly as such; uncredited recycling reads as low effort. + +What LinkedIn forbids. + +- Walls of text without paragraph breaks. +- Generic motivational content; the platform has decreasing tolerance for this. +- Posts that read as ads with no substantive content. +- Heavy use of emoji decoration without purpose. + +Adaptation discipline. Source content needs to be restructured for LinkedIn rhythm: short opening hook, body with paragraph breaks every 2-3 sentences, specific examples or stakes, possibly a question at the close that invites comment. + +--- + +## X/Twitter (single post and threads) + +Length norms. Single post: 280 characters (or up to 4,000 for premium accounts; conventions vary). Thread: 5-15 posts typical for substantive threads. + +What X demands (single post). + +- Tight phrasing. Each character matters; specific framings that fit the format earn engagement. +- Stand-alone meaning. Tweets that depend on context outside the tweet often fail. +- Specific points or claims. Vague observations underperform. + +What X demands (threads). + +- A first post that earns the next click. Threads are read sequentially; the first post must hook. +- One coherent argument across the thread. Threads that wander get abandoned mid-way. +- Reasonable length. Threads longer than 15-20 posts often lose readers; very long threads may be better as a blog post linked from a shorter thread. + +What X forbids. + +- Threads that read as a blog post split into 280-character chunks. The platform's conversational rhythm is different. +- Hashtags-as-content. Heavy hashtag usage signals SEO chasing rather than communication. + +Adaptation discipline. Source content for threads needs to be re-paced: each post a complete thought, the thread building, the conclusion specific. + +--- + +## Long-form video (YouTube, in-depth content) + +Length norms. 8-30 minutes typical for substantive content. Some categories support longer (45-90 minutes for deep technical content); the algorithm rewards retention over duration. + +What long-form video demands. + +- Pacing for spoken delivery. Print-style sentences read aloud sound stilted; video scripts need spoken voice. +- Visual variation. Talking-head video alone for 30+ minutes underperforms; cuts, b-roll, on-screen text, illustrations carry attention. +- Audio quality. Bad audio kills retention faster than bad video; audio investment usually returns more than video investment. +- A specific topic. The video's title and thumbnail need to communicate scope; vague titles underperform in algorithmic recommendation. + +What long-form video forbids. + +- Slideshows of text read aloud. Mass-blast pattern in video form. +- No editing. Filler words, long pauses, and unedited rambling reduce retention. +- Talking head only with no visual variation across long durations. + +Adaptation discipline. Source content for video needs scripting in spoken voice (or talking-points for unscripted delivery), visual planning per segment, and an opening that earns the next 30 seconds of viewing. + +--- + +## Short-form video (TikTok, Reels, Shorts) + +Length norms. 60-90 seconds typical; 15-30 seconds for some platforms. Algorithmic recommendation typically rewards retention from second 1. + +What short-form demands. + +- Hook in seconds 1-2. Viewers scroll past the opening if it does not earn the next 5 seconds. +- Captions. Many viewers watch without sound; captions carry the message. +- A single specific point. Short-form does not support multi-point delivery. +- Visual presence. Motion, text-on-screen, or visual variation within the short. Static talking heads underperform. + +What short-form forbids. + +- Content that takes 10+ seconds to land. Viewers leave before the point. +- Long-form video clipped without re-pacing. The pacing assumed in the source piece does not match short-form expectations. +- Captions that lag the audio. Mistimed captions distract. + +Adaptation discipline. Source content for shorts needs extreme compression: one moment, one point, one short. Each short is a standalone unit. + +--- + +## Podcast + +Length norms. 20-90 minutes typical for substantive content. Daily-news-style podcasts can be shorter (8-15 minutes); deep-interview podcasts can run 90-180 minutes. + +What podcast demands. + +- Spoken-language sentence structure. Print-style sentences read aloud sound stiff. +- Conversational pacing. Examples, asides, and natural speech earn engagement; tightly-argued print sections feel cold. +- Audio quality. Listening is intimate; bad audio breaks the connection. Better audio than video matters here. +- Show notes that do the print work the audio cannot. Links, structured summary, citations, references. + +What podcast forbids. + +- Reading articles aloud without adaptation. +- Scripts that sound scripted (over-rehearsed delivery, no conversational rhythm). +- Episodes without show notes or with thin show notes. +- Inconsistent episode length within a series; audiences develop expectations. + +Adaptation discipline. Source content for podcasts becomes the show's spine; the host adds context, examples, and conversational elaboration. Show notes are a distinct derivative format with their own constraints. + +--- + +## Webinar + +Length norms. 30-60 minutes typical. Longer webinars (90+ minutes) require very high engagement design or strong specific draws (like premiere announcements). + +What webinars demand. + +- A live element. Q&A, polls, interactive moments. Static webinars are videos; interactive webinars earn the format. +- Slide design that supports rather than competes with delivery. Text-heavy slides distract; visual slides with the speaker carrying the content work. +- Pacing for live audience attention. Audience attention dips in the middle; engagement design needs to address the dip. +- Recording strategy. Most webinars become video assets after the live session; the recording extends value indefinitely. + +What webinars forbid. + +- Reading slides aloud. The audience can read; the speaker should add the value the slides cannot carry. +- No engagement design. Audiences disengage in pure one-way webinars. +- Webinars that try to cover too much in 30 minutes. Cure: narrow the topic to what 30 minutes can deliver. + +Adaptation discipline. Source content for webinars typically takes the source's 3-5 most load-bearing sections as the spine, plus interactive moments, plus Q&A. + +--- + +## AI-search snippet (for citation by AI engines) + +Length norms. 40-80 words per snippet for FAQ-style extractions; 100-200 words for paragraph-style extractions. + +What AI-search snippets demand. + +- Standalone meaning. The snippet works without the surrounding context; AI engines extract paragraphs, not full pieces. +- Named-source citations within the snippet. AI engines weight named-source claims; "according to a 2025 Forrester study" performs better than "studies show." +- Specific framings. Vague phrasings rarely get cited; specific phrasings do. +- Schema markup where applicable. FAQPage and similar schemas signal the format. + +What AI-search snippets forbid. + +- Floating claims without sources. +- Pronoun references that depend on outside context ("This is why..." with no clear referent within the snippet). +- Hedged language on claims that can be specific. + +Adaptation discipline. Source content for AI snippets needs to be extractable as standalone paragraphs with internal citations and specific framings. Often the source piece needs additions specifically designed for snippet citation. + +--- + +## Methodology-level choices that stay in the public skill + +The format constraints by medium, the length norms, the demand-and-forbid lists, the adaptation discipline per format. The underlying observation: medium constraints are non-negotiable. + +## Implementation choices that stay internal + +Specific platform automation. Specific design templates per format. Specific captioning workflows. Specific schema markup patterns. Specific A/B testing of format-specific elements (subject lines, hooks, opening lines). The team's own conventions on length within the bands. These vary by team and platform mix. diff --git a/skills/content-repurposing/references/repurposing-pipeline-templates.md b/skills/content-repurposing/references/repurposing-pipeline-templates.md new file mode 100644 index 0000000..9325d2f --- /dev/null +++ b/skills/content-repurposing/references/repurposing-pipeline-templates.md @@ -0,0 +1,237 @@ +# Repurposing pipeline templates + +Workflow templates by source-piece type. Whitepaper pipeline, blog post pipeline, research report pipeline, multi-piece consolidation pipeline. The repeatable shapes that turn ad-hoc repurposing into a predictable program. + +Repurposing without templates produces ad-hoc workflows: each cross-format extension is invented from scratch, capacity estimates are unreliable, quality varies. Templates make repurposing a known production shape, with predictable capacity and predictable quality. + +The templates below are recurring shapes; teams adapt them to specific source pieces and program contexts. + +--- + +## Pipeline 1: Whitepaper + +Source. A 4,000-8,000 word whitepaper or definitive guide. + +Cross-format set (typical). + +- 4-6 blog posts (one per major section). +- 5-7 email sequence. +- 1 webinar. +- 12-18 social posts across LinkedIn, X, possibly Instagram or Threads. +- 6-12 video shorts. +- 10-15 FAQ extractions for AI search. +- Possibly 1 podcast episode. + +Production sequence. + +- Week 0: Source piece publishes. +- Week 1: First social posts ship; email teaser sends. FAQ extractions ship as part of the source piece (or as an immediately-following FAQ page). +- Weeks 2-6: Blog posts ship at 1-per-week cadence. Email sequence sends in parallel. More social posts ship from each blog post's release. +- Weeks 4-8: Webinar runs. Webinar recording becomes additional video derivatives. +- Weeks 6-10: Video shorts ship. Podcast episode (if applicable) records and releases. + +Capacity. Typical whitepaper pipeline costs 30-60 hours of editorial and production work across 8-10 weeks, on top of the source piece's production cost. + +Owner structure. Single owner-of-extensions for the whitepaper. Specific derivative owners by format (blog series owner, email sequence owner, social owner, video owner). The owner-of-extensions coordinates timing and ensures cross-promotion happens. + +--- + +## Pipeline 2: Blog post (substantive) + +Source. A 1,500-2,500 word substantive blog post on a multi-step framework or substantive topic. + +Cross-format set (typical). + +- 5-7 email sequence (if the source has a multi-step framework). +- 4-8 social posts. +- 2-4 video shorts. +- 3-5 FAQ extractions. +- Possibly 1 podcast episode segment (not full episode). + +Production sequence. + +- Week 0: Blog post publishes. +- Week 1: First social posts ship; email teaser if part of a sequence; FAQ extractions added to the post. +- Weeks 2-4: Email sequence sends. Additional social posts. Video shorts ship. +- Weeks 4-6: Long-tail social and AI-search-snippet refinement. + +Capacity. Typical substantive blog post pipeline costs 8-15 hours of additional work across 4-6 weeks. + +Owner structure. Often one owner runs the full extension for blog-post-tier sources because the work is small enough to coordinate in one head. + +--- + +## Pipeline 3: Research report + +Source. A 4,000-12,000 word research report with primary data. + +Cross-format set (typical). + +- 5-8 blog posts (one per major finding or section). +- 7-10 email sequence. +- 1-2 webinars (often a launch webinar plus a deeper-dive webinar). +- 20-30 social posts (research reports produce many statistic-driven social derivatives). +- 8-15 video shorts (statistic-focused). +- 15-25 FAQ extractions. +- 1-2 podcast episodes. +- Possibly an interactive data visualization or microsite. + +Production sequence. + +- Week -2 to Week 0: Pre-launch promotion teasers (research findings preview). +- Week 0: Source report publishes; launch webinar announces; first wave of statistic-focused social ships. +- Weeks 1-4: Heavy email sequence; blog posts ship; webinars run; social posts continue. +- Weeks 4-12: Video shorts roll out; podcast episodes record and release; FAQ extractions get refined as AI-search citations are tracked; second webinar runs for deeper-dive audience. +- Indefinitely: Statistics from the report continue to be cited in subsequent program pieces; the report becomes a reference asset. + +Capacity. Research report pipelines are the highest-investment repurposing efforts. Typical cost: 60-150 hours of additional work across 8-16 weeks, on top of the report's production cost. + +Owner structure. Owner-of-extensions plus dedicated derivative owners. Often a research report's cross-format extension is treated as a project with its own project manager rather than as a routine repurposing pipeline. + +--- + +## Pipeline 4: Multi-piece consolidation (ebook) + +Source. Multiple existing pieces (blog posts, articles, social threads) on a related topic. + +Cross-format set (typical). + +- 1 ebook (the primary consolidation). +- New introduction, chapter framings, conclusion within the ebook (often 20-30% new content). +- 4-7 promotional blog posts (potentially excerpting chapters or introducing the ebook). +- 5-8 email sequence promoting the ebook. +- 1 webinar based on the ebook's framework. +- 8-15 social posts promoting the ebook and its chapters. +- 3-6 video shorts. + +Production sequence. + +- Months 1-3: Source-piece selection and consolidation. Identify which existing pieces fit; outline the ebook; write new connective tissue; consolidate and edit for unified voice. +- Month 3-4: Production: design, layout, possibly PDF generation, gating setup if applicable. +- Month 4: Ebook launches. First promotional blog posts and emails ship. Webinar runs. +- Months 5-8: Promotional cadence continues. Video shorts and social posts roll out. + +Capacity. Multi-piece consolidation pipelines often cost 60-120 hours of consolidation and production work, plus the standard derivative production. Total: 80-180 hours across 4-8 months. + +Owner structure. A consolidation lead drives the editorial work; standard derivative owners run the promotional set. The consolidation lead often is a senior editor because the unified-voice editing is substantial. + +--- + +## Pipeline 5: Trending topic editorial + +Source. A 1,000-2,500 word editorial piece on a trending or news-driven topic. + +Cross-format set (typical, lighter than evergreen). + +- 4-7 social posts (concentrated in the first week to ride the trend). +- 1-2 video shorts. +- 1-2 FAQ extractions if the topic supports it. +- Often no email sequence (trending topics may not justify a multi-email investment). +- Often no webinar (production cycle is too long for trending topics). + +Production sequence. + +- Day 0: Source piece publishes. +- Days 1-7: Social posts ship rapidly to ride the trend. Video shorts ship if production cycle allows. +- Weeks 2-4: Long-tail social and AI-search-snippet refinement if the topic has staying power. +- After 4 weeks: Pipeline typically winds down as the trend fades. + +Capacity. Trending topic pipelines are deliberately light: 4-10 hours of additional work across 1-2 weeks. + +Owner structure. Often one owner runs the full extension because timeliness matters more than coordinated multi-format depth. + +--- + +## Pipeline 6: Case study + +Source. A 2,000-4,000 word case study with real specifics. + +Cross-format set (typical). + +- 3-5 blog posts pulling specific lessons or framework moments from the case. +- 3-5 email sequence (if the case study has clear teachable steps). +- 6-10 social posts (often statistic-driven from the case's outcomes). +- 1-3 video shorts (often featuring the case's customer if available, with their consent). +- 3-5 FAQ extractions. +- Possibly 1 webinar featuring the customer. + +Production sequence. + +- Week 0: Case study publishes. +- Week 1: First social posts ship; FAQ extractions added. +- Weeks 2-6: Blog posts and emails ship. Webinar runs (if part of the plan, often with customer participation). +- Weeks 4-10: Video shorts and additional social. + +Capacity. Typical case study pipeline costs 15-30 hours of additional work, plus customer coordination time for any derivatives featuring the customer. + +Owner structure. Customer-coordination owner plus standard derivative owners. The customer-coordination owner manages the relationship; derivative owners produce the work; the customer reviews customer-facing derivatives before they ship. + +--- + +## Pipeline customization + +Templates are starting points; programs adapt them. + +Customization based on audience. + +- B2B technical audiences: more LinkedIn, more whitepaper-driven; less TikTok and Instagram. +- Consumer audiences: more video and visual social; less long-form. +- Vertical-specific audiences: platform mix may differ (YouTube heavy in some industries; Twitter/X heavy in others). + +Customization based on capacity. + +- Smaller teams may execute Pipeline 1 with reduced scope (3 blog posts instead of 6, 6 social posts instead of 18). +- Larger teams may extend pipelines with additional derivatives the templates do not include (interactive tools, microsites, dedicated landing pages). + +Customization based on source characteristics. + +- Highly visual source pieces benefit from heavier video and visual-social investment. +- Voice-distinctive source pieces benefit from heavier email and podcast investment (where voice carries). +- Citation-rich source pieces benefit from heavier AEO-extraction investment. + +--- + +## Pipeline tracking + +Each pipeline run produces data that informs future pipelines. + +The minimum log per pipeline. + +- Source piece title, type, length, traffic at launch. +- Cross-format set planned vs delivered. +- Capacity spent (hours per derivative type). +- Outcomes per derivative (engagement, traffic, conversion, citation rates). +- Lessons learned (what worked, what failed, what to change next time). + +Pattern detection across pipelines. + +- Are some pipeline templates outperforming others on similar source types? +- Are some derivative types consistently outperforming others? +- Are capacity estimates accurate, or do certain pipelines consistently overrun? +- Are some channels consistently underperforming for the program's audience mix? + +The log informs program-level decisions: which pipelines to invest in more deeply, which to drop, which to redesign. + +--- + +## Common pipeline failures + +Pipeline-as-checklist. The team treats the pipeline as a checklist to complete rather than as a coordinated plan. Each derivative gets produced; nothing connects to the others; cross-promotion is missing. + +Capacity underestimation. Teams plan a Pipeline 1 expecting 30 hours; actual cost is 70 hours; new production suffers. Cure: track actual capacity per pipeline; calibrate estimates. + +Pipeline dogmatism. Treating the template as a fixed shape regardless of source-piece characteristics. Some source pieces fit the template; some need customization. Cure: customize pipelines per source. + +No tracking. Pipelines run; outcomes are not measured; the program does not learn. Cure: minimum log per pipeline. + +No owner-of-extensions. Pipelines run with derivative owners but no overall coordination. Cross-promotion gaps; cadence drift; no single accountable person. Cure: assign an owner-of-extensions per pipeline. + +--- + +## Methodology-level choices that stay in the public skill + +The six pipeline templates with cross-format set, sequencing, capacity, and ownership structures. The pipeline customization framework. The pipeline tracking log. The common pipeline failures. + +## Implementation choices that stay internal + +Specific project-management templates per pipeline. Specific calendar tooling for cross-format scheduling. Specific time-tracking that captures pipeline capacity. Specific reporting templates for pipeline outcomes. The team's own conventions for which pipelines apply to which source-piece tiers. These vary by team, tooling, and program scale. diff --git a/skills/content-repurposing/references/sequencing-and-cadence-patterns.md b/skills/content-repurposing/references/sequencing-and-cadence-patterns.md new file mode 100644 index 0000000..0678d1e --- /dev/null +++ b/skills/content-repurposing/references/sequencing-and-cadence-patterns.md @@ -0,0 +1,198 @@ +# Sequencing and cadence patterns + +When to release derivatives relative to the source. Concentrated vs distributed cadence. Pacing audits. The patterns that match cadence to the source's traffic curve and audience attention. + +The release sequence and cadence determine how the cross-format set lands. The wrong sequencing can produce a wave of derivatives that exhausts audiences, or a trickle that loses connection to the source's authority. The right sequencing matches the source's traffic curve and the audiences' attention rhythm. + +--- + +## Sequencing patterns + +Three patterns for how derivatives sequence relative to the source. + +### Source-first, derivatives following + +The pattern. The source piece publishes; derivatives roll out over the following 2-12 weeks. The source carries the initial authority and traffic spike; derivatives extend reach and re-engage audiences over time. + +Strengths. + +- The source piece's launch is concentrated, earning the full attention of the program's audiences. The launch is a moment. +- Derivatives reference the source's authority. Each derivative can link back to the source as the canonical version; the source's ranking and authority compounds. +- Audiences who engaged with the source are primed for derivatives; the first derivative often performs well because the audience is warm. + +Weaknesses. + +- The source needs to support the launch with strong promotion. If the source publishes quietly, the launch moment is muted. +- Audiences who missed the source see derivatives without context; the derivatives need to stand alone. + +Fits. Most programs. The default sequencing pattern. + +### Simultaneous launch + +The pattern. Source and a wave of derivatives publish on the same day. Multiple channels fire at once. + +Strengths. + +- Maximum splash. The cross-format presence on a single day signals significance to audiences. +- Cross-channel reinforcement. Audiences encountering the program on multiple channels in one day register the significance more strongly than serial encounters. + +Weaknesses. + +- Risks audience fatigue. If every channel is firing the same day, audiences may tune out before they engage with any individual piece. +- Heavy production load on launch day. All derivatives must be ready simultaneously, which can compress quality. +- Less time for individual derivatives to land. Each derivative competes for attention with every other derivative on the same day. + +Fits. Major flagship launches where the moment itself is part of the value (annual research reports, ebook releases, manifesto-style pieces). Tier 1 source pieces. + +### Derivatives-first, source as anchor + +The pattern. Social posts and short-form video tease ideas; the source piece publishes as the synthesizing flagship after the buildup. + +Strengths. + +- Builds anticipation. Audiences who engage with the early derivatives expect the source piece. +- The source piece publishes into a primed audience. + +Weaknesses. + +- Less common; works only for built-up audiences who follow the program closely. +- Risks giving away too much before the source. If the early derivatives expose the source's argument, the source publishes into an audience that feels they have already read it. +- Coordination overhead. The cross-format buildup needs to land at the right cadence to support the source's launch. + +Fits. Programs with engaged audiences and strong social presence. Less common than source-first; specific to programs that have earned anticipation. + +--- + +## Cadence within the rollout + +Three pacing patterns within the chosen sequencing. + +### Concentrated cadence + +The pattern. Most derivatives ship within 4-6 weeks of source. + +Strengths. + +- Maximum momentum from the source's authority. The source's traffic curve is highest in the first 2-4 weeks; derivatives launching during that window benefit from the source's freshness. +- The cross-format set feels coherent. Audiences see the program everywhere within a short window; the campaign feeling earns engagement. +- Easier to coordinate. Production and scheduling concentrate; the team is in launch mode for a defined period. + +Weaknesses. + +- Limited time for individual derivatives to land. A derivative in week 5 has less attention available than the source did in week 1. +- Audience fatigue risk. Audiences may disengage before week 4-6 if the cadence feels relentless. +- Less long-tail value. After week 6, the cross-format set largely stops producing new touchpoints. + +Fits. Tier 1 and Tier 2 source pieces. Programs running flagship launches where the campaign nature is part of the strategy. + +### Distributed cadence + +The pattern. Derivatives ship over 3-6 months. + +Strengths. + +- Each derivative has space to land. No internal competition for audience attention. +- Long-tail value. The program continues to produce touchpoints over a longer window. +- Sustainable. The team is not in launch mode for months; production fits steady-state cadence. + +Weaknesses. + +- Risk of losing connection to source. By month 3, the source piece may be background context rather than the active reference. +- Less momentum. The campaign feeling fades; each derivative is a standalone moment rather than part of a coherent push. +- Coordination overhead extended. Owners and producers need to maintain focus across months. + +Fits. Evergreen flagship pieces with sustained traffic curves. Programs with smaller production capacity that cannot sustain concentrated cadence. + +### Indefinite cadence + +The pattern. Derivatives keep being created from the source as long as the source remains relevant. + +Strengths. + +- Maximum long-term value extraction. +- Adapts to audience response. Derivatives that perform well inform what to produce next; the program learns from the cross-format set's reception. + +Weaknesses. + +- Most programs cannot sustain indefinite attention to a single source. Discipline tends to decay. +- Risk of voice drift. Derivatives produced 12 months apart may have voice variation that the original launch cadence avoided. +- Less coherent campaign feel. Audiences see scattered derivatives over a long window without a clear narrative. + +Fits. Truly evergreen sources whose value compounds for years. Rare; usually reserved for major flagship pieces (defining manifestos, definitive research reports). + +--- + +## Pacing audits + +Match cadence to the source's traffic curve and the audience's attention rhythm. + +The source's traffic curve. + +- Sharp early traffic, fast decay. Trending-topic pieces, news-driven analysis. Concentrated cadence; the audience is paying attention for a short window. +- Sustained high traffic for weeks. Flagship reports on hot topics. Concentrated to mid-distributed cadence; the audience attention extends but eventually fades. +- Slow build, sustained traffic for months. Evergreen flagship pieces, definitive guides. Distributed cadence; the audience encounter is continuous over time. +- Sustained low traffic with occasional spikes. Reference pieces that get rediscovered. Indefinite cadence works if the production capacity supports it. + +The audience's attention rhythm. + +- Email subscribers. Engagement varies; sequences spaced 5-7 days work for most B2B; daily for high-engagement consumer audiences. +- Social audiences. Platform-specific. LinkedIn rewards 1-2 posts per week from program accounts; X rewards higher frequency; Instagram somewhere in between. +- Podcast audiences. Episodic; weekly cadence common; bi-weekly works for higher-production-effort shows. +- YouTube audiences. 1-2 videos per week typical for active channels; long-form video can be less frequent. + +The pacing decision. Match the source's traffic curve and the audiences' attention rhythm. If they conflict, the source's curve usually wins; the cross-format set's coherence depends on the source's authority window. + +--- + +## Sequencing and cadence per derivative type + +Some derivatives have natural sequencing within the rollout. + +Derivatives that should ship early. + +- Email teaser or preview email. Sets up the source's launch with the email audience. +- Social posts that announce the source. Visibility on launch day. +- Short-form video that introduces the topic. Algorithmic recommendation responds best when the content is fresh. + +Derivatives that should ship 1-3 weeks in. + +- First blog post in a series. The source piece is still drawing traffic; the blog post benefits from internal linking and the audience's continued interest. +- Webinar based on the source. Allows time for audience registration and promotion. +- First batch of social pull-quote posts. The source's themes are familiar; the pull quotes resonate. + +Derivatives that should ship 1-3 months in. + +- Podcast episode. Production cycle is longer; podcast audience overlap with source audience may be partial. +- Subsequent blog posts in a series. Distributed cadence; each post earns its own attention. +- Email sequence (if not the immediate teaser). The sequence develops the source's framework over time. + +Derivatives with flexible timing. + +- FAQ extractions and AI-search snippets. These can ship at source-launch or any time after; AI search citation accumulates over months. +- Ebook consolidation. Often ships 6-12 months after source pieces accumulate; the consolidation work itself takes time. + +--- + +## Common sequencing and cadence failures + +All-at-once dumping. A wave of 12 derivatives in 5 days. Audiences disengage by day 3; most derivatives produce little engagement. Cure: distributed cadence with audience-attention spacing. + +Source quietly publishing while derivatives ship loudly. The derivatives carry the launch but the source piece itself launches without the attention it deserves. Cure: source-first launch with promotion focused on the source; derivatives follow. + +Source publishing months after promised derivatives. Derivatives that previewed a coming source piece ship; the source publishes 4 months later. Audiences have lost connection. Cure: tighten production schedule or flip the sequencing to source-first. + +Cadence too aggressive for the audience. Email subscribers receiving daily emails for 2 weeks unsubscribe. Cure: match cadence to audience attention norms; email audiences typically tolerate 1-2 sends per week from a program. + +Cadence too slow. Distributed cadence stretched too long; by month 4, audiences have forgotten the source. Cure: bring cadence closer to source's traffic curve; consider indefinite cadence only when the source genuinely supports it. + +No sequencing plan. Derivatives ship as they happen to be ready, with no coordination. Cross-format set feels random; audiences see scattered touchpoints with no coherent narrative. Cure: even rough sequencing planning at production time produces better outcomes than no plan. + +--- + +## Methodology-level choices that stay in the public skill + +The three sequencing patterns, the three cadence patterns, the pacing audit, the per-derivative-type sequencing, the common failures. + +## Implementation choices that stay internal + +Specific calendar tooling. Specific automation that schedules derivatives across channels. Specific coordination workflows between producers and channel owners. Specific A/B testing of cadence variants. The team's own conventions for fast-track vs queued derivatives. These vary by team and tooling. diff --git a/skills/content-repurposing/references/source-piece-selection-criteria.md b/skills/content-repurposing/references/source-piece-selection-criteria.md new file mode 100644 index 0000000..70e61ac --- /dev/null +++ b/skills/content-repurposing/references/source-piece-selection-criteria.md @@ -0,0 +1,125 @@ +# Source-piece selection criteria + +Strong vs weak source-piece characteristics. The selection audit. Pieces that should stay one-and-done. The discipline that prevents repurposing capacity from being spent on pieces that will not extend cleanly across formats. + +Not every piece is worth repurposing. Selection is the first decision, and getting it wrong produces derivative work that feels forced, fails to engage on the new formats, and consumes capacity that would have produced better return on stronger source pieces. + +--- + +## Strong source-piece characteristics + +A piece that extends cleanly across formats usually has several of the following. + +Clear central argument or framework. The piece has a thesis, a framework, or a structured set of positions that survives translation. The reader of any derivative can extract the argument; the reader of the source can recognize it. + +Standalone sections. The piece's H2 sections work as standalone units. A reader who only sees one section can still get value; the section does not depend on the cumulative context of preceding sections to make sense. Pieces with this property produce blog-series and social-post derivatives easily. + +Travelable examples and case studies. The piece contains specific examples, case studies, or worked illustrations that can stand alone. These travel into video shorts, social posts, and podcast episodes as natural anchors. + +Audience overlap with target formats. The source's audience exists on the platforms where derivatives will live. A B2B technical whitepaper extends well into LinkedIn long-form posts and into podcast episodes; less well into TikTok shorts. + +Distinctive voice. The piece has voice characteristics specific enough that derivative voice can stay coherent. Pieces in generic voice produce derivatives that sound like AI-default; pieces in distinctive voice anchor derivatives to recognizable register. + +Accumulated demand. The source has demonstrated reader interest: traffic, links, mentions, shares, citations. Pieces with traction support derivatives because the demand is real; pieces without traction produce derivatives that draw on no underlying interest. + +Multi-angle topic. The topic has multiple angles, sub-questions, or applications. Pieces on narrow single-angle topics produce few derivatives; pieces on broader topics with sub-questions produce more. + +--- + +## Weak source-piece characteristics + +Pieces that resist repurposing usually have several of the following. + +Tightly-integrated argument. The piece is a layered argument where every section depends on the cumulative context. Extract any section and it loses meaning. Whitepapers with this structure (high-rigor analytical pieces) often resist clean derivative extraction; the value is in reading end-to-end. + +List-style without standalone weight. The piece is a list of items where individual items are not substantial enough to support derivatives. "Top 10 marketing tips" with one-paragraph items per tip cannot produce strong derivatives because no single item justifies a derivative piece. + +Narrative-arc dependence. The piece's value comes from the unfolding narrative; reading any segment alone misses the arc. Some narrative case studies and feature-style longform have this property. Derivatives can summarize but cannot replace. + +Audience-format mismatch. The source's audience does not exist (or exists thinly) on most target formats. A regulatory-technical whitepaper for compliance officers extends poorly to TikTok; the audience is not there. + +Generic voice. The source piece reads in default-AI or generic-content-marketing voice. Derivatives generated from a generic source compound the genericness. Without a distinctive source voice, derivatives drift further from any recognizable register. + +No demand signal. The source piece has not earned traffic, links, or shares. Repurposing rarely creates demand that did not exist; pieces without demand should be evaluated for whether they should have been published in the first place. + +Highly time-bound. The source piece is about a specific event, news cycle, or moment that will not be relevant in the cadence's timeframe. Derivatives that ship 4-6 weeks after the source may already be out of date. + +--- + +## The selection audit + +A short framework for evaluating a candidate source piece. + +1. Read the piece's central argument or framework. Can you state it in one sentence? If not, the piece may not extend cleanly. If yes, the argument is the spine that derivatives will extend. +2. Identify standalone sections. Which H2 sections work alone? If most sections work alone, blog-series and social derivatives are natural. If only one section works alone, fewer derivative formats fit. +3. List travelable elements. Specific examples, case studies, statistics, or claims that could anchor derivatives. Pieces with 5-10 travelable elements support multi-format extension; pieces with 0-2 do not. +4. Check audience-format overlap. For each candidate derivative format, is the source's audience present on the format? If most candidate formats fail this check, the source may not be a multi-format candidate. +5. Audit voice distinctiveness. Read three paragraphs from different sections. Could a reader who knows the brand identify this as the brand's work? If yes, derivatives have voice anchor. If no, derivatives will drift. +6. Check demand signal. Has the source earned traffic, links, mentions, or shares? Pieces without demand signal do not transmit demand to derivatives. +7. Estimate extraction yield. Given the above, how many derivative pieces could the source plausibly support? Pieces yielding 1-2 derivatives may not be worth a formal repurposing plan; pieces yielding 6-12 are clear repurposing candidates. + +--- + +## Pieces that should stay one-and-done + +Some pieces are valuable but resist repurposing. Recognizing them prevents wasted effort. + +Tightly-argued analytical whitepapers. Pieces whose value is in the cumulative argument. Often valuable as flagship content but produce few clean derivatives. The right disposition: ship the source piece; create one or two derivative pieces (a summary blog post, an email teaser); accept that most of the value is in the source itself. + +Highly specific case studies. Pieces about a single specific situation that does not generalize cleanly. The case is valuable; abstraction loses the specifics that gave the case its weight. The right disposition: ship the case study; create derivative pieces only where the case has clear teachable moments that travel. + +Time-bound editorial. Pieces about a specific event, news cycle, or moment. The piece may be valuable in the moment but the moment passes. The right disposition: ship; minimal repurposing during the moment; archive after. + +Highly visual source pieces. Pieces whose value is primarily in custom visuals (data dashboards, illustrated guides, complex diagrams). Text derivatives often cannot carry the visual value. The right disposition: derivative video and visual-format extensions only; text derivatives often underperform. + +Niche-audience pieces. Pieces for a small specific audience that does not exist on most other formats. The right disposition: minimal repurposing; the audience is concentrated where the source already published. + +--- + +## Tier-based selection + +Programs with regular flagship production benefit from explicit tiering of source pieces by repurposing intensity. + +Tier 1: Major flagship (1-3 per year). The source piece is treated as the spine of a multi-month repurposing campaign. 8-15 derivative pieces planned. Cross-format extension covers blog series, email sequence, webinar, podcast, social waves, video shorts, AI-search extractions. Capacity allocation is significant; the source's value is being maximally extracted. + +Tier 2: Standard flagship (4-12 per year). Source piece supports 4-8 derivative pieces. Cross-format extension covers a subset of formats: blog series or email sequence (not both), social posts, FAQ extractions for AI search. Capacity allocation is moderate. + +Tier 3: Routine substantive piece (12-50 per year). Source piece supports 1-3 derivative pieces. Often a social-post wave, an email mention, an internal-link refresh on related pieces. Minimal additional capacity. + +Tier 4: One-and-done (the majority of pieces). Source piece publishes; appears in newsletter once; shares on social once; no derivative pieces planned. Capacity allocation only on the source. + +The tiering discipline. Most programs have too few Tier 1 and Tier 2 pieces and too many Tier 3 and Tier 4 pieces masquerading as flagship work. The audit shifts capacity allocation toward the few pieces that genuinely warrant multi-format extension. + +--- + +## When a piece grows into stronger source-piece status + +Some pieces start as Tier 4 and earn promotion based on performance. + +The signal. A piece that was published as routine starts drawing significant traffic, earning links, getting mentioned externally, or producing reader engagement disproportionate to its production tier. + +The response. Promote the piece into a higher tier. Plan derivatives. Some of the strongest source pieces in mature programs are pieces that performed unexpectedly well after publication; recognizing them quickly extracts the additional value. + +The audit. Quarterly review of pieces' performance. Pieces showing strong demand that have not been repurposed are candidates for retroactive extraction; pieces showing weak demand that were originally tiered as flagship may need their derivative plans reduced or canceled. + +--- + +## Common selection failures + +Repurposing every piece. Treating all pieces as repurposing candidates spreads capacity thin. Most programs benefit from concentrating capacity on 10-20% of pieces and accepting one-and-done for the rest. + +Repurposing the wrong pieces. Selecting source pieces because they are easy (recent, fresh in mind) rather than because they are strong source-piece candidates. The selection audit catches this. + +Ignoring weak-source-piece signals. Pushing through repurposing on pieces with tightly-integrated argument, list-style structure, or no demand signal produces derivatives that fail. + +Static tiering. Pieces tiered at production never get re-tiered based on performance. Strong sleeper pieces never get repurposed; weak flagship pieces consume planned derivative capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The strong vs weak source-piece characteristics, the selection audit, the one-and-done dispositions, the tiering framework, the dynamic-tiering discipline, the common selection failures. + +## Implementation choices that stay internal + +Specific scoring rubrics the team uses to score source pieces. Specific dashboards that surface high-performing pieces for retroactive promotion. Specific calendar templates that allocate repurposing capacity by tier. The team's own thresholds for when a routine piece warrants Tier 2 promotion. These vary by team and program shape. diff --git a/skills/content-repurposing/references/voice-consistency-across-formats.md b/skills/content-repurposing/references/voice-consistency-across-formats.md new file mode 100644 index 0000000..8435836 --- /dev/null +++ b/skills/content-repurposing/references/voice-consistency-across-formats.md @@ -0,0 +1,146 @@ +# Voice consistency across formats + +What stays constant and what adapts. The voice audit per derivative. The AI-repurposing voice problem and the discipline that prevents it. + +Voice is the most visible casualty of careless repurposing. The source piece may have specific voice characteristics; derivatives generated without strong voice discipline drift toward AI-default or platform-default register. Audiences detect the drift even when they cannot articulate it; the cross-format set reads as work from different brands rather than as a coherent program. + +--- + +## What stays constant + +The brand-voice elements that should survive every format adaptation. + +The brand's POV on the topic. If the source piece argues a specific position, the derivatives carry the same position. A derivative that hedges where the source committed, or that takes a different angle than the source, breaks the cross-format coherence. + +Distinctive vocabulary. Brand-specific terms, framings, and phrasings that signal "this is from this brand." If the source uses a particular word for a concept, derivatives use the same word. If the source has a recognizable phrase, derivatives carry the phrase. + +Level of conviction or hedging. Brands have characteristic stance positions. Some brands commit; some hedge thoughtfully; some are confrontational. The derivatives carry the brand's stance pattern even when format conventions might pull toward different stance defaults. + +Audience-respect register. Brands address audiences in specific ways: peer-to-peer, expert-to-novice, alongside-the-reader. The register stays consistent across formats; derivatives that suddenly talk down to the audience break voice coherence. + +Anti-patterns the brand avoids. If the brand does not use particular framings (motivational filler, generic-content-marketing voice, hype-driven language), derivatives also avoid them. Anti-pattern adherence is part of voice. + +--- + +## What adapts per format + +Voice elements that should adjust to the medium. + +Sentence length and structure. Spoken voice differs from written. Email voice differs from blog voice. Social-post voice differs from email voice. The brand's voice characteristics survive through these adaptations, but the surface-level sentence patterns change. + +- Print: medium sentences with occasional layered constructions. +- Email: shorter sentences, more direct address. +- Spoken (podcast, video): conversational rhythm with natural pauses and asides. +- Social: tight phrasing in first lines, paragraph breaks frequent. + +Density. Visual formats can carry less per minute than text formats. A short video cannot fit the density of a paragraph; the same point in video form has more breathing room. + +Conversational vs declarative register. Podcasts are conversational; whitepapers are declarative. The brand's POV stays the same in both; the framing register adapts. + +Direct-address frequency. "You" usage varies by format. Emails often use "you" frequently; whitepapers may use "the reader" or "marketers" more often. The shift is appropriate; pulling email voice into a whitepaper or vice versa would feel off. + +Visual element usage. Some formats use visuals heavily (social, video); others rely on text (email, long-form). Voice adapts to whether visuals are doing some of the work. + +--- + +## The voice audit per derivative + +A short framework for verifying voice consistency. + +1. Read or watch the derivative as if encountering it cold. Could a reader who knows the brand identify this as the brand's work? If yes, voice is working. +2. Compare to the source piece. Does the derivative carry the source's POV, vocabulary, and stance? Where it differs, is the difference appropriate format adaptation or unwanted drift? +3. Check against the brand's voice anti-patterns. Is the derivative slipping into framings the brand normally avoids? AI-default voice often slips in through derivatives. +4. Check sentence-level patterns. Sentence length, paragraph length, direct-address frequency, vocabulary. Are they format-appropriate but brand-recognizable? +5. Read aloud (for written derivatives) or read the script (for spoken derivatives). Does it sound like the brand's voice as the brand would speak it? + +The voice audit is one of the easiest to skip and one of the most consequential. Pieces that pass everything else but fail voice audit damage the cross-format coherence. + +--- + +## The AI-repurposing voice problem + +AI-assisted repurposing is particularly prone to voice drift. + +The pattern. The source piece has specific voice characteristics. AI generation of derivatives is asked to "summarize this for LinkedIn" or "turn this into emails." The AI produces derivatives that are technically related to the source but written in AI-default voice rather than the source's distinctive voice. + +Why it happens. AI generation regresses to model defaults unless the writer actively pulls it back. Without strong voice prompts, the derivatives sound like the AI's voice using the source's content. Multiple derivatives generated without voice anchor compound the drift; by the tenth derivative the cross-format set has lost the source's voice entirely. + +The cure. + +- Voice guidelines as prompt input. Every AI generation includes the brand voice guidelines as context. Generic prompts produce generic outputs. +- Sample text as voice anchor. Feed the AI 2-3 paragraphs of the source piece in their original voice. AI mimics what it sees more than what it is told. +- Per-derivative voice review. Each derivative gets a voice audit. Drift detected gets revision. The audit is non-negotiable. +- Rewrite the bland. Any sentence that could appear in any other piece on the topic gets rewritten in voice. Voice lives in the specific. + +See `ai-content-collaboration` for the broader voice-preservation discipline that applies across AI-assisted content workflows. The repurposing-specific application is that voice drift compounds across multiple derivatives in ways that single-piece AI generation does not. + +--- + +## When format conventions pull against brand voice + +Sometimes a format's conventions push toward voice that does not match the brand. + +LinkedIn motivational tone. LinkedIn rewards a particular kind of motivational and personal-narrative content. Brands with crisp analytical voice may resist the convention; the right answer is usually to maintain voice rather than to drift into LinkedIn-default motivational tone, even at cost of platform-specific engagement. + +TikTok's high-energy delivery. TikTok rewards high-energy short-form delivery. Brands with measured analytical voice may not fit naturally; the right answer may be to skip TikTok rather than to produce content that sounds wrong for the brand. + +Podcast-host conversational warmth. Some podcast styles reward warm conversational delivery; a brand with confrontational analytical voice may struggle to produce derivatives that fit. The right answer may be to format-fit (use a different format) or to produce derivatives that hold the brand's voice even at engagement cost. + +The discipline. Format-fit decisions are upstream of voice-adaptation decisions. If a format genuinely cannot accommodate the brand's voice, skipping the format is sometimes the right answer; voice integrity matters more than universal cross-format presence. + +--- + +## Voice prompts for AI-assisted repurposing + +When AI generates derivatives, the prompts should carry voice instructions. + +Components of a voice prompt. + +- 2-3 paragraphs of the source piece in original voice as anchor. +- A short voice description (3-5 specific characteristics). +- A short anti-pattern list (3-5 framings the brand avoids). +- Per-format adjustments (sentence length, register, direct-address frequency). + +A worked prompt example pattern. "The source piece below is in the brand's voice. Convert it into [target format]. The voice characteristics to preserve: [specific characteristics]. The anti-patterns to avoid: [specific anti-patterns]. The format adaptations: [format-specific]. Source piece: [text]." + +The discipline is including the voice instructions in every derivative generation, not assuming the AI will infer voice from the source alone. AI tools differ in how well they infer voice from samples; the safest discipline is explicit voice instruction. + +--- + +## Voice consistency across multiple writers or AI generators + +Programs with multiple writers or AI generators producing derivatives have a multi-source voice drift problem. + +The risk. Writer A produces three derivatives in slightly different voice from writer B's four derivatives, plus AI generates two more in default voice. The cross-format set has three voice variants, none of them quite the source's voice. + +The discipline. + +- Single voice owner. One person reviews all derivatives in the cross-format set for voice consistency. Catches drift across writers. +- Voice library. Documented brand voice with examples; all writers and AI generators reference the same library. +- Calibration sessions. Periodically, multiple writers (or writers plus the editorial lead) review derivatives together and reconcile voice expectations. + +Programs with sophisticated voice discipline can run multi-writer derivative production without losing voice; programs without discipline produce voice variants that audiences notice. + +--- + +## Common voice failures in repurposing + +AI-default drift. Derivatives sound like the AI's voice rather than the brand's voice. Cure: stronger voice prompts; per-derivative review. + +Platform-default drift. Derivatives sound like the platform's default register rather than the brand's voice. Cure: voice-over-platform-fit discipline; sometimes skip the platform. + +Cross-derivative drift. Each derivative is fine alone but the cross-format set reads as voice variants. Cure: single voice owner across the set. + +Source-voice loss. Derivatives carry the source's content but not the source's voice characteristics. Cure: voice anchor with sample text from the source. + +Voice-only-on-source. The source piece has voice; the derivatives default to generic. Cure: voice discipline applies to derivatives, not just to the source. + +--- + +## Methodology-level choices that stay in the public skill + +The constant-vs-adapting voice elements, the voice audit, the AI-repurposing voice problem and its cure, the format-vs-voice tension, the multi-writer voice discipline, the common voice failures. + +## Implementation choices that stay internal + +Specific voice-prompt templates per AI tool. Specific voice-library documentation in the team's writing system. Specific calibration session formats. Specific reviewer dashboards that surface cross-derivative voice variation. The team's own conventions for voice-vs-format tradeoffs. These vary by team, AI tooling, and brand voice maturity. diff --git a/skills/content-strategy/SKILL.md b/skills/content-strategy/SKILL.md new file mode 100644 index 0000000..dce5d9e --- /dev/null +++ b/skills/content-strategy/SKILL.md @@ -0,0 +1,211 @@ +--- +name: content-strategy +description: "Develop a content strategy covering editorial positioning, content pillars, formats, calendar, governance, and topical authority planning. Use this skill whenever the user wants to plan a content program, define content pillars, build an editorial calendar, structure topic clusters, set up content governance, or align content production with broader brand and SEO goals. Triggers on content strategy, content plan, editorial strategy, content pillars, content calendar, editorial calendar, topical authority, topic clusters, content governance, content roadmap, content production. Also triggers when the user is about to start producing content without a strategic plan." +category: strategy-and-discovery +catalog_summary: "Editorial strategy, content calendar, topical authority planning" +display_order: 5 +--- + +# Content Strategy + +Plan what content to produce, why, when, and how. Stack-agnostic. Works for blogs, knowledge bases, marketing sites, newsletters, and product content surfaces. + +This skill is the strategic layer. Tactical execution sits in `content-and-copy`, `landing-page-copy`, and `email-sequences`. SEO-driven content planning sits in `seo-keyword`. This skill stitches those together into a coherent program. + +--- + +## When to use + +- Planning a new content program or relaunching an existing one +- Defining editorial positioning and content pillars +- Building an editorial calendar +- Structuring topic clusters and content hubs +- Establishing content governance (review, approval, lifecycle) +- Aligning content with broader brand and revenue goals + +## When NOT to use + +- Writing specific content pieces (use `content-and-copy`) +- Writing landing pages or sales copy (use `landing-page-copy`) +- Writing email sequences (use `email-sequences`) +- Pure keyword research (use `seo-keyword`, then return here for strategic planning) +- Auditing existing content for keep/update/delete decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- Brand positioning and audience (from `brand-discovery` or `creative-brief`) +- Business goals the content needs to serve (traffic, leads, brand authority, retention) +- Existing content inventory (if any) +- Keyword research output (from `seo-keyword`) if SEO-driven +- Production capacity (writers, budget, cadence) + +If brand positioning is unclear, run `brand-discovery` first. If audience is undefined, do that work before strategy. + +--- + +## The framework: 5 layers + +A content strategy has five layers. Skip layers and the program drifts. + +### 1. Editorial positioning + +What this content program stands for. The "why we write" statement. + +Components: +- Mission. Why this content exists. One sentence. +- Audience. Who it serves. Specific. +- Promise. What readers get from us they cannot get elsewhere. +- Distinction. What makes this content different from the 50 other publications in the same space. + +Example structure: + +> We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +A strong editorial positioning forces choices. If you cannot complete the sentence, the positioning is too vague. + +### 2. Content pillars + +The 3 to 5 themes the program owns. Every piece of content belongs to a pillar. + +Per pillar, define: +- Theme. One sentence describing the topic territory. +- Why we own it. Audience need + brand authority + competitive opportunity. +- Sub-topics. 5 to 15 sub-topics that fit under the pillar. +- Cornerstone content. The 1 to 2 pieces that anchor the pillar (long-form, comprehensive, link-worthy). +- Supporting content. Articles, videos, tools, comparisons that reinforce and link to the cornerstone. + +Pillar selection criteria: +- Audience cares about it (research-backed, not assumed) +- Brand has credibility or can earn it +- Topical authority is achievable (you can plausibly become a top-3 source) +- Connects to revenue (directly or indirectly) +- Distinguishes you from competitors + +3 to 5 pillars is the sweet spot. Fewer than 3 risks brittleness. More than 5 dilutes focus. + +### 3. Content formats and types + +The shapes the content takes. + +Format dimensions: + +- Length. Short (under 500 words), medium (500 to 1500), long (1500 to 3000), epic (3000+) +- Depth. Surface (overview) vs. deep (comprehensive) +- Type. Article, guide, comparison, listicle, case study, interview, data study, tool, video, podcast, newsletter, social +- Originality. Aggregation (summarizing existing knowledge) vs. original research (new data or insight) +- Evergreen vs. timely. Lasting value vs. moment-driven + +Format selection criteria: + +- Match the audience's preferred consumption (do they read, watch, listen?) +- Match the topic (some topics demand depth; others demand brevity) +- Match production capacity +- Match distribution channels (LinkedIn favors short; YouTube favors video; SEO favors long evergreen) + +A content program typically has 3 to 5 formats it returns to consistently. More than that fragments production and brand recognition. + +### 4. Editorial calendar + +When content publishes. + +Cadence options: + +- High frequency (3+ pieces per week): builds momentum, requires significant production capacity +- Medium frequency (1 to 2 per week): sustainable for most teams, builds steady audience +- Low frequency (1 to 4 per month): each piece must be high-impact; longer production cycles +- Burst-then-pause (10 pieces in a month, then 3 months off): launches and campaigns + +Calendar structure: + +- Pillar rotation. If you have 4 pillars and publish weekly, each pillar gets one piece per month. +- Content type mix. Within a month, blend types (e.g., 2 articles + 1 case study + 1 video). +- Timely opportunities. Reserve flex slots for newsjacking, seasonal content, launches. +- Updates and refreshes. Plan time for updating existing high-performing content. + +Common failure: publishing whatever happens to get written. Without a calendar, the program drifts toward the topics easiest to write, not the ones the audience needs most. + +### 5. Governance and lifecycle + +How content gets made, reviewed, published, measured, and retired. + +Production workflow: + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +Per stage, define: + +- Who owns it +- What inputs they need +- What outputs they produce +- What the quality bar is +- How long it should take + +Roles: + +- Editorial lead. Owns positioning, calendar, quality bar. +- Writers. Produce drafts. May be in-house, freelance, or AI-assisted. +- Subject matter experts. Provide expertise, review for accuracy. +- Editors. Polish, ensure voice consistency, fact-check. +- SEO lead. Keyword optimization, internal linking, schema. +- Publishers. Ship the content (CMS, scheduling, distribution). + +Lifecycle decisions: + +- Update cadence. Top-performing evergreen content reviewed every 6 to 12 months. +- Retire criteria. Content that no longer serves the audience or hurts the site (use `seo-content-audit`). +- Republishing. Updated content republished as fresh, not buried as an update. + +--- + +## Workflow + +1. Confirm inputs. Brand positioning, audience, business goals, capacity. If any are missing, surface that first. +2. Draft editorial positioning. Mission, audience, promise, distinction. Stress-test the positioning by trying to complete the "We help X" sentence. +3. Define content pillars. 3 to 5. Each with a theme, justification, sub-topics, and planned cornerstone content. +4. Choose formats. 3 to 5 formats the program returns to consistently. +5. Build the calendar. Cadence, pillar rotation, format mix, flex slots. +6. Set up governance. Roles, workflow, quality bar, lifecycle rules. +7. Document. Use the template in [`references/content-strategy-template.md`](references/content-strategy-template.md). +8. Operationalize. Set up the editorial calendar in whatever tool the team uses (CMS, Notion, Airtable, etc.). + +--- + +## Failure patterns + +- Strategy without capacity. A 3-piece-per-week plan with one part-time writer fails. Match strategy to actual production capacity. +- Pillars chosen for SEO alone. Pillars must serve the audience and the brand, not just keyword opportunity. SEO is a downstream filter, not the strategy itself. +- Too many pillars. 7 pillars dilute the brand. The audience cannot remember what you stand for. +- Calendar without governance. Content gets produced but quality drifts. Without a quality bar, the program loses authority. +- No update plan. Top-performing content goes stale. Competitors with fresher versions overtake. +- Vanity metrics. Pageviews and follower counts without conversion tracking. Define what success looks like in business terms. +- Strategy that lives in a doc. A strategy document that doesn't translate to the editorial calendar and the production workflow is decoration. Operationalize or it doesn't exist. + +--- + +## Output format + +Default output is a strategy document at `content-strategy.md` plus an editorial calendar in whatever tool the team uses. + +Strategy document structure: +1. Editorial positioning +2. Content pillars (3 to 5, each detailed) +3. Formats +4. Calendar (cadence and structure, not the specific items) +5. Governance (roles, workflow, lifecycle) +6. Measurement plan (metrics, review cadence) +7. Production capacity and budget + +Editorial calendar (separate, ongoing): +- One row per planned content piece +- Columns for: title, pillar, format, target keyword (if SEO-driven), publish date, owner, status + +--- + +## Reference files + +- [`references/content-strategy-template.md`](references/content-strategy-template.md) - Strategy document template. +- [`references/editorial-calendar-template.md`](references/editorial-calendar-template.md) - Spreadsheet column definitions and calendar structure. diff --git a/skills/content-strategy/references/content-strategy-template.md b/skills/content-strategy/references/content-strategy-template.md new file mode 100644 index 0000000..2cee093 --- /dev/null +++ b/skills/content-strategy/references/content-strategy-template.md @@ -0,0 +1,259 @@ +# Content Strategy: [Brand or Site Name] + +Version: [X.Y] +Last updated: [YYYY-MM-DD] +Owner: [Editorial lead] +Review cadence: [Quarterly / Annually] + +--- + +## Editorial positioning + +### Mission + +[One sentence. Why this content program exists.] + +### Audience + +Primary: +[Specific audience segment with the depth of detail your discovery work earned.] + +Secondary: +[Additional segments, if any.] + +Anti-personas: +[Who this content is NOT for.] + +### Promise + +[What readers get from us that they cannot get elsewhere. One paragraph.] + +### Distinction + +We help [audience] [achieve outcome] by publishing [content type] that [unique angle], unlike [common alternatives] that [common shortcoming]. + +--- + +## Content pillars + +### Pillar 1: [Pillar name] + +- Theme: [One sentence] +- Why we own it: + - Audience need: [Specific need] + - Brand authority: [Why we're credible] + - Competitive opportunity: [Why this is winnable] +- Sub-topics (5 to 15): + - [Sub-topic] + - [Sub-topic] + - [Sub-topic] +- Cornerstone content (the 1 to 2 pieces that anchor this pillar): + - [Title or working title] + - [Title or working title] +- Supporting content (article types that link back to cornerstone): + - [Type and quantity, e.g., "5 deep-dive articles per quarter"] + +### Pillar 2: [Pillar name] +[Same structure] + +### Pillar 3: [Pillar name] +[Same structure] + +[Continue for all pillars; aim for 3 to 5] + +--- + +## Formats + +The program returns to these formats consistently. + +### Format 1: [Name, e.g., "In-depth guides"] +- Description: [What it is] +- Length: [Word count or duration range] +- Cadence: [How often we produce one] +- Use case: [When this format wins] + +### Format 2: [Name] +[Same structure] + +### Format 3: [Name] +[Same structure] + +[Continue for all formats; aim for 3 to 5] + +--- + +## Editorial calendar structure + +### Cadence + +Frequency: [N pieces per week/month] + +Reasoning: [Why this cadence; what it can sustainably support] + +### Pillar rotation + +[How pillars rotate through the calendar. Example: 4 pillars, weekly publishing, each pillar gets one piece per month.] + +### Format mix + +[Within a typical month, what's the format breakdown?] + +Example: +- 2 articles +- 1 case study or interview +- 1 longer guide or data study +- Plus: 1 newsletter (ongoing, separate cadence) + +### Flex slots + +[How much of the calendar is reserved for timely content, news jacking, or campaign launches?] + +Typical: 70% planned, 20% flex, 10% updates to existing content. + +### Updates and refreshes + +[Plan for refreshing top-performing content. Typically every 6 to 12 months for evergreen pillars.] + +--- + +## Governance + +### Roles + +\| Role \| Owner \| Responsibility \| +\|---\|---\|---\| +\| Editorial lead \| [Name] \| Strategy, calendar, quality bar \| +\| Writer (in-house or freelance) \| [Name(s) or agency] \| Drafts \| +\| Subject matter expert \| [Name(s)] \| Expertise, accuracy review \| +\| Editor \| [Name] \| Polish, voice consistency, fact-check \| +\| SEO lead \| [Name] \| Keyword optimization, internal linking, schema \| +\| Publisher \| [Name] \| CMS publication, scheduling, distribution \| + +### Production workflow + +``` +Idea → Brief → Outline → Draft → Edit → Review → Publish → Measure → Update or Retire +``` + +\| Stage \| Owner \| Inputs \| Outputs \| Quality bar \| Time estimate \| +\|---\|---\|---\|---\|---\|---\| +\| Idea \| \| \| \| \| \| +\| Brief \| \| \| \| \| \| +\| Outline \| \| \| \| \| \| +\| Draft \| \| \| \| \| \| +\| Edit \| \| \| \| \| \| +\| Review \| \| \| \| \| \| +\| Publish \| \| \| \| \| \| +\| Measure \| \| \| \| \| \| +\| Update or retire \| \| \| \| \| \| + +### Quality bar + +Every piece of published content meets these standards: +- [ ] Aligned with a defined content pillar +- [ ] Targets a specific audience need +- [ ] Voice and tone consistent with brand standards +- [ ] Factually accurate (sources cited where appropriate) +- [ ] SEO basics handled (title, meta, headers, internal links) +- [ ] Schema applied for the content type +- [ ] Edited by someone other than the writer +- [ ] Reviewed by the editorial lead + +### Lifecycle rules + +- Update trigger: A top-performing evergreen piece reviewed when [trigger, e.g., "stats are 12 months old" or "competitive landscape shifts"] +- Retire trigger: A piece is retired (deleted, redirected, or merged) when [trigger, e.g., "no traffic for 12 months and no backlinks"] +- See also: `seo-content-audit` for the keep/update/merge/redirect/delete framework + +--- + +## Measurement plan + +### Primary metrics + +\| Metric \| Target \| Reporting cadence \| +\|---\|---\|---\| +\| Organic traffic \| \| Monthly \| +\| Email subscribers \| \| Monthly \| +\| Conversions from content \| \| Monthly \| +\| [Custom metric] \| \| \| + +### Secondary metrics (signals) + +- Engaged sessions (sessions over 60 seconds) +- Scroll depth on long-form content +- Internal click-through from articles to commercial pages +- Backlinks earned per piece +- Time on page distribution +- Returning reader rate + +### Review cadence + +- Weekly: Calendar status check +- Monthly: Performance metrics review, calendar adjustments +- Quarterly: Strategy review, pillar performance, capacity check +- Annually: Full strategy refresh, audience research re-validation + +--- + +## Production capacity and budget + +### Capacity + +- Writers: [number, FTE or freelance, hours per week] +- Editors: [number, hours per week] +- Subject matter experts: [availability] +- Designers/illustrators (if needed): [availability] + +### Budget + +- Internal labor: [budget] +- Freelance writers: [per piece or per month] +- Subject matter expert honoraria (if external): [per piece] +- Imagery, illustration, video: [per piece or monthly] +- Tools and platforms: [monthly] + +### Output capacity at this budget + +[Realistic monthly output given the budget. Better to plan conservatively and exceed it than over-promise and under-deliver.] + +--- + +## Distribution + +Content does not earn its audience by being published. List the distribution channels and the standard process for promoting each piece. + +### Channels + +- Owned: site, email, social profiles +- Earned: PR, partnerships, expert mentions +- Paid (if budget): boosted social, sponsored newsletter slots + +### Per-piece distribution checklist + +When a new piece publishes: + +- [ ] Posted to social channels with [N] variations +- [ ] Included in next newsletter +- [ ] Sent to relevant internal stakeholders for sharing +- [ ] Outreach to [N] external mentions or backlink targets +- [ ] Submitted to relevant communities (forums, niche aggregators) +- [ ] Internal link added from [related cornerstone content] + +--- + +## Open questions + +[Things that still need to be decided before this strategy is fully operational.] + +- [ ] [Question] +- [ ] [Question] + +--- + +## Version history + +\| Version \| Date \| Changes \| +\|---\|---\|---\| +\| 1.0 \| YYYY-MM-DD \| Initial strategy \| diff --git a/skills/content-strategy/references/editorial-calendar-template.md b/skills/content-strategy/references/editorial-calendar-template.md new file mode 100644 index 0000000..15509c3 --- /dev/null +++ b/skills/content-strategy/references/editorial-calendar-template.md @@ -0,0 +1,214 @@ +# Editorial Calendar Template + +A spreadsheet column definition and calendar structure for content planning. Use as a setup spec for a new editorial calendar in any tool (Sheets, Airtable, Notion, Linear, Asana). + +The calendar is not the strategy. The calendar is the strategy made operational. If a strategy decision is missing, the calendar will reveal it. + +--- + +## Calendar structure + +### Single source of truth + +The editorial calendar is one document. Not five. If the team uses multiple tools (writing in Notion, scheduling in Buffer, etc.), one tool is the source of truth and the others mirror it. + +The source of truth answers, at a glance: + +- What is being published this week? +- What is in production right now? +- What is committed for the next quarter? +- What is the backlog? +- Who owns each piece? + +--- + +## Required columns + +Every row is one piece of content. Every column below is required. + +\| Column \| Type \| Description \| +\|---\|---\|---\| +\| ID \| Text or auto-number \| Unique identifier per piece. Used in cross-references. \| +\| Title (working) \| Text \| Working title. Final title can change at publish. \| +\| Type \| Pick list \| Article / guide / case study / video / podcast / email / social series / landing page / etc. \| +\| Topic cluster \| Pick list \| Which content cluster this piece belongs to (from the strategy doc). \| +\| Stage of funnel \| Pick list \| Awareness / Consideration / Decision / Retention / Advocacy. \| +\| Primary audience \| Pick list \| Maps to defined segments. \| +\| Primary keyword \| Text \| The query target if SEO-relevant. \| +\| Search intent \| Pick list \| Informational / commercial / navigational / transactional. (See `seo-keyword/references/intent-classification-guide.md`.) \| +\| Primary CTA \| Text \| What action should the reader take? \| +\| Channels \| Multi-select \| Web, email, organic social, paid, partnerships. \| +\| Owner (writer) \| Person \| Who drafts. \| +\| Editor \| Person \| Who reviews. \| +\| Reviewer (SME) \| Person \| Subject matter expert if needed. \| +\| Approver \| Person \| Who signs off before publish. \| +\| Status \| Pick list \| See status workflow below. \| +\| Brief due date \| Date \| When the brief should be ready. \| +\| Draft due date \| Date \| When the draft should be ready. \| +\| Edit due date \| Date \| When edits should be done. \| +\| Publish date (target) \| Date \| The intended publish date. \| +\| Publish date (actual) \| Date \| When it actually went live. \| +\| Brief link \| URL \| Link to the content brief document. \| +\| Draft link \| URL \| Link to the working draft. \| +\| Final link \| URL \| Live URL after publish. \| +\| Performance notes \| Text \| Updated 30 / 60 / 90 days post-publish. \| + +--- + +## Optional but recommended columns + +\| Column \| Description \| +\|---\|---\| +\| Estimated effort (hours) \| For capacity planning. \| +\| Tag(s) \| Cross-cutting tags beyond cluster (e.g., "originals research," "thought leadership," "evergreen"). \| +\| Related pieces \| IDs of companion pieces (series, follow-ups, redirects). \| +\| Distribution plan link \| Specific plan for how this piece is amplified post-publish. \| +\| Repurpose plan \| What this becomes downstream (newsletter, social cuts, video). \| +\| Source / inspiration \| Where the idea came from (data, customer ask, competitor gap, etc.). \| +\| Cost \| If freelance or paid placement. \| + +--- + +## Status workflow + +Every piece moves through these statuses, in this order. + +\| # \| Status \| Meaning \| Exit criteria \| +\|---\|---\|---\|---\| +\| 1 \| Idea \| Captured but not committed. \| Idea passes the prioritization screen. \| +\| 2 \| Backlog \| Committed for some future quarter. \| Scheduled for a specific quarter. \| +\| 3 \| Scheduled \| Targeted for a publish week. \| Brief assigned. \| +\| 4 \| In brief \| Brief being written. \| Brief approved. \| +\| 5 \| In draft \| Writer is drafting. \| Draft submitted to editor. \| +\| 6 \| In edit \| Editor reviewing. \| Edits accepted by writer. \| +\| 7 \| In review \| SME and approver reviewing. \| All approvals received. \| +\| 8 \| Ready to publish \| Final, scheduled in CMS. \| Publish date arrives. \| +\| 9 \| Published \| Live. \| (Terminal) \| +\| 10 \| Killed \| Decided not to ship. \| (Terminal, with reason recorded) \| + +### Why this matters + +If 30 pieces are sitting in "In draft" for 6 weeks, the bottleneck is writers. If 20 are in "In review," the bottleneck is approvers. The calendar exposes pipeline health, not just publish dates. + +--- + +## Calendar views + +The same data, sliced different ways. Each view answers a different question. + +### Calendar view (by week) + +Columns: weeks. Rows: channels (web, email, social). + +Used for: planning rhythm, spotting overlap and gaps. + +### Pipeline view (by status) + +Columns: status. Rows: pieces. + +Used for: identifying bottlenecks. + +### Owner view (by writer / editor) + +Columns: people. Rows: pieces. + +Used for: workload balancing. + +### Cluster view (by topic cluster) + +Columns: clusters. Rows: pieces in pipeline + already published. + +Used for: ensuring topical authority is being built coherently. + +### Funnel view (by funnel stage) + +Columns: stage. Rows: pieces. + +Used for: ensuring balance across funnel. + +### Performance view (post-publish) + +Columns: traffic, conversions, time on page, social shares. Rows: published pieces. + +Used for: retrospective and topic prioritization for next cycle. + +--- + +## Cadence rituals + +The calendar is reviewed on a rhythm. + +\| Ritual \| Cadence \| Attendees \| Purpose \| +\|---\|---\|---\|---\| +\| Daily standup \| Daily, 15 min \| Editorial team \| What is shipping today, blockers. \| +\| Weekly editorial planning \| Weekly \| Content lead + writers \| Confirm next 2 weeks, surface blockers, accept new ideas. \| +\| Monthly review \| Monthly \| Content team + marketing lead \| Look at last month's pipeline, performance, and adjust the next month. \| +\| Quarterly planning \| Quarterly \| Content team + cross-functional \| Plan the next quarter's content based on strategy and last quarter's data. \| +\| Annual review \| Annually \| All stakeholders \| Review the year's themes, performance, and rebuild the strategy. \| + +--- + +## Capacity planning + +Use the calendar to plan capacity, not just track output. + +### Throughput math + +- Available writer time per week: writers × hours allocated to writing +- Average effort per piece: hours from "Idea" to "Ready to publish" +- Throughput: available time ÷ effort + +If planned output exceeds throughput, the calendar will reveal it as drift (slipped dates, deferred backlog). + +### Buffer + +Real teams hit 70-80% of planned throughput. Plan to 70%. Treat the remaining 30% as buffer for inevitable surprises (priority shifts, sick days, longer-than-expected reviews). + +--- + +## Backlog management + +The backlog is not a wishlist. It is a curated set of committed-but-not-scheduled ideas. + +- Cap the backlog at 3-6 months of throughput. Beyond that, ideas go stale. +- Re-rank quarterly using the strategy doc's prioritization criteria. +- Kill backlog items that no longer match the strategy. Killing is a feature, not a failure. + +--- + +## Killed pieces + +When a piece is killed, record: + +- Date +- Reason (strategy shifted, owner left, evidence the piece would not perform, redundant with another piece) +- What happens to the brief or partial draft (archive, salvage for another piece, delete) + +Killed pieces inform future filtering. + +--- + +## Performance review + +For every published piece, update the calendar with performance at 30 / 60 / 90 days. Capture: + +- Sessions / pageviews +- Conversion events (CTAs clicked, signups, purchases) +- Time on page or read depth +- Social shares +- Backlinks earned +- Notes on what worked or did not + +Aggregate quarterly to inform the next quarter's plan. + +--- + +## Sign-off + +Calendar setup approved by: + +- Content lead: [Name, date] +- Marketing lead: [Name, date] +- Tooling owner: [Name, date] + +Calendar lives at: [URL] diff --git a/skills/cost-optimization/SKILL.md b/skills/cost-optimization/SKILL.md new file mode 100644 index 0000000..2f44efb --- /dev/null +++ b/skills/cost-optimization/SKILL.md @@ -0,0 +1,339 @@ +--- +name: cost-optimization +description: "Audit and reduce infrastructure and tooling costs without sacrificing reliability or velocity. Use this skill when reviewing monthly cloud or SaaS spend, finding unused resources, rightsizing infrastructure, negotiating vendor contracts, deciding what to consolidate, or planning for budget cuts. Triggers on cost optimization, cloud spend, SaaS spend, rightsizing, unused resources, FinOps, infrastructure audit, vendor consolidation, budget cut, cost review. Also triggers when finance flags rising costs or when a contract renewal is up." +category: cross-cutting +catalog_summary: "Infrastructure spend audits, rightsizing, contract negotiation" +display_order: 5 +--- + +# Cost Optimization + +Audit cloud, SaaS, and infrastructure spend. Cut what's not earning its keep. Rightsize what's oversized. Negotiate what's negotiable. Without breaking what works. + +--- + +## When to use + +- Quarterly or annual cost review +- Finance flags rising spend +- Vendor contract renewal coming up +- Budget cut required +- New leadership wants the numbers +- Migrating between providers (cost is part of the case) +- Audit before scaling significantly (catch waste before it scales) + +## When NOT to use + +- Active incident response (use `incident-response`) +- Performance issues that happen to involve infrastructure (use `performance-optimization`) +- Vendor evaluation for a new purchase (use `vendor-evaluation`) +- Personnel or org costs (out of scope for this skill) + +--- + +## Required inputs + +- Current cost (monthly, ideally for the last 12 months) +- Cost broken down by service or vendor +- Inventory of cloud resources (instances, databases, storage, etc.) +- Inventory of SaaS subscriptions +- Owners per cost line (who decided to spend this, who uses it) +- Constraints (compliance, performance, contract terms) + +--- + +## The framework: 5 levers + +Every cost optimization opportunity falls into one of these levers. + +### Lever 1: Eliminate + +Stop paying for things that aren't used. + +- Idle resources (instances, databases, environments running but unused) +- Subscriptions where no one logs in +- Duplicate tools (multiple tools doing the same job) +- Old projects still incurring cost +- Test environments that should have been torn down +- Forgotten domains, backups, snapshots, logs + +This is usually the largest opportunity in the first audit. Often 10-30% of spend. + +### Lever 2: Rightsize + +Pay for what you actually use, not what you provisioned for the worst case three years ago. + +- Oversized instances (CPU and memory utilization low) +- Over-provisioned databases (storage and throughput far above usage) +- Over-purchased SaaS seats +- Premium plans where standard would suffice +- High-availability setups for non-critical systems + +Rightsizing requires real usage data, not theoretical needs. + +### Lever 3: Restructure + +Use cheaper structures for the same workload. + +- Reserved or committed-use pricing (1-3 year commitments at 30-70% discount) +- Spot or preemptible instances for fault-tolerant work +- Cold storage for data accessed rarely +- Tiered storage (hot/warm/cold) by access pattern +- CDN caching to reduce origin load +- Compression and deduplication +- Serverless for spiky workloads +- Reserved instances for steady workloads + +The right structure depends on the access pattern. Mismatch costs money. + +### Lever 4: Negotiate + +Pay less for the same thing. + +- Annual contracts at lower rates than monthly +- Volume discounts at higher tiers +- Multi-year commitments for predictable workloads +- Bundle deals (consolidating services with one vendor) +- Renewal negotiation (vendors expect you to ask) +- RFP / competitive bid (using alternatives as leverage) + +Most enterprise vendors negotiate. Most SaaS vendors don't, except at higher tiers. Consumer-tier services usually don't. + +### Lever 5: Reframe + +Change the question. + +- Build vs buy: maybe in-house is cheaper at scale +- Buy vs build: maybe outsourcing is cheaper at small scale +- Different architecture (e.g., monolith vs microservices) has different cost profiles +- Different audience (do all customers need the same tier?) +- Different stack (open source vs commercial) + +Reframe is the longest-lead lever. Worth thinking about even if not actionable now. + +--- + +## Workflow + +### Step 1: Pull the spend data + +Get monthly costs by service, vendor, and (where possible) team or project. + +For cloud (AWS, GCP, Azure): the billing console and cost-explorer tools. +For SaaS: each vendor's billing portal, plus an SaaS-management tool if available. +For everything else: bank statements and accounting export. + +12 months minimum. Trends matter as much as absolute numbers. + +### Step 2: Categorize + +Organize spend into categories: + +- Hosting / compute +- Storage +- Database +- Networking / CDN +- Monitoring / observability +- Email +- CMS / hosting platforms +- Analytics / marketing +- Productivity / collaboration +- Development tools +- Security / compliance +- Other + +The categories vary by business. The point is: similar costs grouped, easy to compare. + +### Step 3: Identify the biggest line items + +80/20 rule. Usually 20% of vendors account for 80% of spend. + +Focus the audit on the top 80%. The long tail can be cleaned up but rarely yields big savings per item. + +### Step 4: Apply the 5 levers + +For each major line item, walk the levers: + +\| Lever \| Question \| +\|---\|---\| +\| Eliminate \| Is it used? Could we stop using it? \| +\| Rightsize \| Are we paying for capacity we don't use? \| +\| Restructure \| Is there a cheaper pricing model or service tier? \| +\| Negotiate \| When was the last renewal? Did we negotiate? \| +\| Reframe \| Is this even the right approach? \| + +Document the opportunity, the effort, the risk, and the savings estimate. + +### Step 5: Prioritize + +Plot opportunities on a 2x2: +- Y axis: savings +- X axis: effort + +Quadrants: +- High savings, low effort: do first +- High savings, high effort: plan +- Low savings, low effort: do as time allows +- Low savings, high effort: skip + +Also consider risk: +- Eliminate something used by no one: low risk +- Rightsize a database: medium risk (test in staging first) +- Replace a critical dependency: high risk (plan carefully) + +### Step 6: Execute the easy wins + +For each easy-win opportunity: +- Document the change +- Get owner approval +- Make the change +- Monitor for unexpected impact +- Confirm cost reduction in next billing cycle + +Easy wins typically include: +- Canceling unused subscriptions +- Tearing down idle resources +- Switching off dev environments outside business hours +- Moving cold data to cheaper storage tiers + +### Step 7: Plan the larger work + +For higher-effort opportunities: +- Spec the change (use `pm-spec-writing` for the plan) +- Test in staging +- Roll out incrementally +- Validate cost impact + +Examples: +- Migrating to reserved instances +- Consolidating monitoring vendors +- Migrating from one CMS to another with cost benefit + +### Step 8: Set up ongoing visibility + +Optimization isn't one-time. Costs creep back up. + +- Monthly cost review (at least) +- Cost dashboard (current, trend, by category) +- Alerts on cost spikes (e.g., daily spend exceeds threshold) +- Tagging or labeling on cloud resources (cost by team or project) +- Quarterly deeper review + +### Step 9: Negotiate at renewal + +For vendor contracts up for renewal: +- Start the conversation 60-90 days before renewal +- Have alternatives identified (even if you don't switch) +- Ask for a multi-year discount +- Ask about volume tiers +- Ask if usage rightsizing is possible +- Be willing to walk (most vendors find a way to keep you) + +Pre-pandemic, many vendors auto-renewed at increases. Post-pandemic, many are hungry for retention. Ask. + +### Step 10: Document the policy + +Going forward: +- New vendor evaluation requires cost justification +- Resource provisioning has approval thresholds +- Tagging and labeling are required for cloud resources +- Quarterly review is calendared +- Cost attribution is clear + +Without policy, costs creep. + +--- + +## Common opportunities by category + +### Hosting and compute + +- Reserved or committed-use pricing for predictable workloads (30-70% off) +- Spot or preemptible for fault-tolerant batch +- Auto-scaling for variable loads +- Right instance family (compute-optimized, memory-optimized, etc.) +- Dev/staging instances stopped outside business hours + +### Storage + +- Lifecycle policies to move old data to cheaper tiers +- Delete old logs, backups, snapshots +- Compression for archival +- Object versioning costs (every version is a stored object) + +### Database + +- Right size based on actual CPU/memory usage +- Reserved capacity for predictable workloads +- Read replicas for read-heavy workloads (cheaper than scaling primary) +- Drop unused indexes (indexes cost storage and write performance) +- Old data archived or deleted + +### Networking and CDN + +- CDN reduces origin egress costs (often the biggest cost category) +- Compression on the wire +- Image and video optimization +- Region-aware routing + +### Monitoring and observability + +- Sample logs (don't ingest 100% of high-volume sources) +- Retention policies (do you need 90 days or 30?) +- Consolidate tools where possible +- Free or open-source tooling for non-critical needs + +### SaaS + +- Audit logins per seat (inactive users on $X/seat = $X waste) +- Renegotiate at renewal +- Move to annual billing for the discount +- Consolidate overlapping tools + +--- + +## Failure patterns + +Cost-cutting that breaks something. Aggressive rightsizing without testing causes outages. The cost of an outage is usually larger than the savings. + +Optimization that takes more time than it saves. A team spends a quarter saving $5K/year. Math doesn't work. Focus on opportunities where savings exceed effort. + +Renewal autopilot. Annual renewals go through without review. Calendar them. + +No tagging. Cloud spend grows; no one knows whose. Tag everything from day one. + +Free tier overruns. "It's on the free tier." Then it's not, and bills surprise. Set alerts on free-tier services. + +No environment differentiation. Production-grade staging "to match prod." Costs as much as prod. Often unnecessary. + +Untouched legacy. "The old project still runs." Why? Often: nothing actually uses it. Audit and shut down. + +Premium tiers for non-premium needs. Enterprise plan because someone wanted a feature that's been since added to lower tiers. Recheck. + +Vendor lock-in justifying cost. "We can't switch." That's not a reason to overpay; it's a strategic problem to plan around. + +Optimizing the small stuff while ignoring the big stuff. Saving $50/month on tools while $5K/month sits in oversized infrastructure. Top-down first. + +Penny-wise, pound-foolish. Cutting a useful tool to save $20/month, then losing hours to manual work. Tools that pay for themselves shouldn't be cut. + +No reinvestment. Every dollar saved goes to bottom line; nothing reinvested in upgrades or capacity. Saved costs and improved capability aren't either/or. + +--- + +## Output format + +A cost optimization document includes: + +- Current state: total spend, by category, trended +- Top line items: the biggest costs +- Opportunities: by lever (eliminate / rightsize / restructure / negotiate / reframe) +- Prioritized list: with savings, effort, risk +- Action plan: owners, dates +- Easy wins executed: what's already done, results +- Ongoing governance: dashboard, review cadence, tagging, approval thresholds + +--- + +## Reference files + +- [`references/cloud-audit-checklist.md`](references/cloud-audit-checklist.md): A practical walkthrough for auditing a cloud account (compute, storage, database, network, monitoring) for waste and rightsizing opportunities. diff --git a/skills/cost-optimization/references/cloud-audit-checklist.md b/skills/cost-optimization/references/cloud-audit-checklist.md new file mode 100644 index 0000000..1265c60 --- /dev/null +++ b/skills/cost-optimization/references/cloud-audit-checklist.md @@ -0,0 +1,292 @@ +# Cloud Audit Checklist + +A practical walkthrough for auditing a cloud account for waste and rightsizing opportunities. Stack-agnostic in principle; the categories apply across AWS, GCP, Azure, and others. + +Allow about a half-day for a first audit. Subsequent audits go faster. + +--- + +## Setup + +- [ ] Pull the last 12 months of billing data +- [ ] Pull current resource inventory (compute, storage, database, networking) +- [ ] Identify owners per service or project +- [ ] Note any compliance or contractual constraints + +--- + +## Compute + +### Identify idle and underused + +- [ ] Instances with CPU utilization below 10% over 30 days +- [ ] Instances stopped but still incurring some charges (storage, IPs, etc.) +- [ ] Instances running 24/7 that only need business hours +- [ ] Instances forgotten from old projects +- [ ] Instances spun up for a one-time task and never deleted + +For each: identify owner. Confirm it's not needed. Stop or delete. + +### Rightsize active instances + +- [ ] Instances with CPU peaks under 40% (probably oversized) +- [ ] Instances with memory underused +- [ ] Instances of older generation (newer generations often cheaper for same performance) +- [ ] Instances of wrong family (compute-optimized when memory-optimized would be cheaper) + +For each: test smaller size in staging. Roll out gradually. + +### Pricing structure + +- [ ] On-demand instances with stable load (candidates for reserved or savings plans) +- [ ] Workloads that could tolerate interruption (candidates for spot/preemptible) +- [ ] Long-running workloads with no commitment (candidate for committed-use discounts) + +Reserved/committed: 30-70% discount for 1-3 year commitment. +Spot/preemptible: 60-90% discount, can be terminated by provider. + +### Auto-scaling + +- [ ] Auto-scaling configured for variable workloads (vs always-on at peak size) +- [ ] Scaling policies actually scale down (some only scale up) +- [ ] Min size set appropriately (not over-provisioned) + +--- + +## Storage + +### Identify unused + +- [ ] Snapshots not used in 6+ months +- [ ] Disks unattached to any instance +- [ ] Buckets accessed never or rarely (per access logs) +- [ ] Old log archives no one queries +- [ ] Old backups beyond retention requirements + +For each: confirm it's not needed. Delete or archive. + +### Lifecycle policies + +- [ ] Hot data only for recent access +- [ ] Move data to warm tier after [N] days +- [ ] Move to cold/archive tier after [M] days +- [ ] Delete after [P] days (if compliant) + +Lifecycle policies are set-once, save-forever. High ROI for the time invested. + +### Storage class + +- [ ] Verify storage class matches access pattern + - Frequently accessed: standard + - Infrequent: IA / nearline + - Rarely: cold / archive + - Compliance-only: deep archive + +Mismatched storage class is a common waste category. + +### Versioning + +- [ ] Object versioning is on intentionally (not accidentally) +- [ ] Old versions cleaned up via lifecycle policy +- [ ] Soft-delete retention is finite (not indefinite) + +Versioned buckets can accumulate massive cost from old versions. + +--- + +## Database + +### Identify underused + +- [ ] Databases with low CPU/memory usage over 30 days +- [ ] Databases with low connection counts +- [ ] Databases that could be smaller instance class +- [ ] Read replicas no longer needed +- [ ] Databases for old projects + +### Rightsize storage + +- [ ] Storage allocated far above used +- [ ] Auto-scaling on for storage (avoid manual oversizing) +- [ ] Old logs and audit data cleaned up + +### Backup retention + +- [ ] Backup retention matches RPO (not aspirational, not excessive) +- [ ] Manual snapshots cleaned up (often outlive their purpose) + +### Pricing structure + +- [ ] Reserved capacity for steady workloads +- [ ] Spot/preemptible for non-critical analytics + +### Indexes + +- [ ] Unused indexes dropped (each index costs storage and write performance) +- [ ] Indexes match query patterns (use database tooling to identify) + +--- + +## Networking + +### Egress + +Egress (data leaving the cloud or moving across regions) is often the most surprising cost. + +- [ ] Egress to internet (largely user traffic; CDN can reduce) +- [ ] Egress between regions (often unintended; check architecture) +- [ ] Egress between availability zones (matters at scale) +- [ ] NAT gateway charges (per-GB; can be huge for high-traffic egress) + +Reduce egress with: +- CDN caching (origin egress drops dramatically) +- Compression +- Multi-region only when needed (single-region egress is often cheaper) +- VPC endpoints for cloud-internal traffic (avoid going out and back in) + +### Load balancers + +- [ ] Idle or unused load balancers +- [ ] Load balancer count appropriate (don't run 5 when 1 works) +- [ ] Load balancer type matches use (application LB vs network LB; pricing differs) + +### Public IPs + +- [ ] Idle elastic IPs (charged when not attached) +- [ ] Public IPs that should be private + +### CDN + +- [ ] CDN in front of high-traffic origin +- [ ] Cache hit rate measured (low cache hit = wasted CDN, untrained origin) +- [ ] Compression and image optimization on at the CDN + +--- + +## Monitoring and logs + +### Log volume + +- [ ] Logs ingested but never queried +- [ ] Verbose logging in production (debug level by accident) +- [ ] Logs from low-importance services at full volume + +Sample or filter where possible. High-volume logs can dominate observability bills. + +### Retention + +- [ ] Retention matches need (do you query 90-day-old logs?) +- [ ] Compliance retention separate from operational retention (compliance can use cheaper storage) +- [ ] Aggregated metrics retained longer than raw logs (cheaper, often sufficient) + +### Tooling + +- [ ] Multiple monitoring tools doing the same job +- [ ] Premium tier when standard would suffice +- [ ] Per-host pricing on tools where utilization is low + +--- + +## Specialty services + +### Search (Elasticsearch, Algolia, etc.) + +- [ ] Indexes for old data still queried? +- [ ] Replicas appropriate for traffic +- [ ] Tier matches need + +### Cache (Redis, Memcached) + +- [ ] Cache hit rate measured (low hit = expensive cache delivering little value) +- [ ] Cache size appropriate +- [ ] TTLs reasonable + +### Queue / streaming (Kafka, Kinesis, SQS) + +- [ ] Throughput matches actual load +- [ ] Retention matches need +- [ ] Idle streams or topics cleaned up + +### Email / SMS / push + +- [ ] Volume matches projection +- [ ] Per-message pricing tier appropriate +- [ ] Old or low-engagement contacts removed (don't pay to send to non-recipients) + +--- + +## Account-level + +### Multiple accounts + +- [ ] Account count matches need (separation of concerns is good; sprawl is wasteful) +- [ ] Consolidated billing enabled (volume discounts across accounts) +- [ ] Inactive accounts decommissioned + +### Tagging + +- [ ] Tags applied to all resources +- [ ] Tags consistent (team, project, environment, cost center) +- [ ] Untagged resources have owners identified + +### Budgets and alerts + +- [ ] Budget alerts configured (e.g., alert at 80% of monthly target) +- [ ] Anomaly detection enabled (alert on unusual cost spikes) +- [ ] Per-team or per-project budgets where possible + +--- + +## Findings document + +For each finding, capture: + +\| Field \| Example \| +\|---\|---\| +\| Description \| "Production database is 8xlarge; CPU peaks at 25%" \| +\| Category \| Compute / storage / database / network / etc. \| +\| Lever \| Eliminate / rightsize / restructure / negotiate / reframe \| +\| Estimated savings \| $/month \| +\| Effort \| Hours/days \| +\| Risk \| Low / medium / high \| +\| Owner \| Person or team \| +\| Action \| Specific next step \| + +--- + +## Prioritization + +After all findings: + +\| Priority \| Description \| +\|---\|---\| +\| P0 \| Easy, high savings, low risk: do this week \| +\| P1 \| Medium effort, high savings: plan this quarter \| +\| P2 \| Easy, low savings: do as time allows \| +\| P3 \| High effort, low savings: deprioritize \| + +Reserved instances and committed-use discounts often appear as P0/P1: high savings, structured effort. + +--- + +## Tracking + +After acting, track: +- Savings achieved (compare next billing cycle to baseline) +- Issues caused (any rollbacks needed?) +- Time spent +- Lessons for next audit + +Cost reductions sometimes appear gradually (e.g., reserved purchase smooths in). Track over 2-3 billing cycles. + +--- + +## Maintenance + +- [ ] Set monthly cost review (15-30 min, look at trends) +- [ ] Set quarterly deeper audit (this checklist, abbreviated) +- [ ] Set annual full audit (this checklist, full) +- [ ] Set renewal calendar (each major contract, with reminder 90 days out) +- [ ] Tag governance (new resources require tags, untagged flagged) + +Cost optimization is ongoing, not one-time. Without maintenance, savings reverse. diff --git a/skills/creative-brief-selector/SKILL.md b/skills/creative-brief-selector/SKILL.md new file mode 100644 index 0000000..64d4a99 --- /dev/null +++ b/skills/creative-brief-selector/SKILL.md @@ -0,0 +1,112 @@ +--- +name: creative-brief-selector +description: "Produce a creative brief grounded in live reference sites and deliberately distinct from existing demos, for any new brand build. Composes with brand-archetype-system and creative-direction. Use this skill at the start of any brand or microsite build when the result needs to land in a specific aesthetic position and not drift into a default house style. Triggers on creative brief, design brief, build brief, brand direction, where should this brand sit, what should this site look like, reference sites for, archetype for, distinct from our other brands, divergence from prior, not the same as. Also triggers when prior builds have come out as siblings and a systematic divergence approach is needed." +category: brand +catalog_summary: "Live-reference-grounded creative briefs with divergence check against prior builds" +display_order: 6 +--- + +# Creative Brief Selector + +A starting-point selector for brand and microsite builds. Given a business spec (name, vertical, shape, one-line vibe, optional list of shipped demos), produces a creative brief grounded in three things: + +1. An archetype position from `brand-archetype-system`, picked or composed to be deliberately distinct from the shipped demos. +2. A small set of live reference sites for that archetype-and-vertical combination, drawn from a curated bank plus optional per-build discovery. +3. A divergence check against the shipped demos that flags palette, voice, structural pattern, and section-shape overlap before the brief is handed off. + +The brief output is concrete tokens, not abstract families, including explicit section-shape choices (hero shape and footer shape) as first-class outputs alongside palette and voice. It is meant to be loaded by downstream build skills as the single creative artifact for the build. + +--- + +## When to use + +- Starting any new brand or microsite build that should land in a specific aesthetic position. +- The first build in a portfolio (no prior builds to diverge from yet, but the divergence schema can be seeded for the next one). +- The second through nth build in a portfolio, where the risk of sibling output is real. +- After a portfolio audit that surfaced sibling builds: this skill is the systemic fix for the pattern. +- When a build's creative direction is being chosen between two adjacent archetypes and the call needs a reference-grounded reason. + +## When NOT to use + +- The user wants pure aesthetic methodology guidance (use `creative-direction`). +- The user has a finished archetype and a finished brief and is asking for execution (skip to the downstream build skills). +- The user wants a logo or a finished identity (use `logo-design`, `brand-identity`). +- The user wants to define voice for an existing brand (use `brand-voice`). +- Defining brand strategy from zero positioning (use `brand-ideation` first, then return to this skill). + +--- + +## How this composes with other skills + +This skill works upstream of build-time skills and parallel to the aesthetic methodology layer: + +- `brand-archetype-system` (upstream input). The archetype catalog this skill picks from. The skill names the archetype in the rendered brief; it does not redefine the archetype's defaults. +- `creative-direction` (parallel input). The four-axis vocabulary the archetypes reference. If the consumer needs the full axis brief, run `creative-direction` first; this skill's brief consumes its outputs. +- `brand-identity` (downstream). Once the brief is approved, brand-identity turns it into a finished identity system. +- `landing-page-copy`, `content-and-copy`, `art-direction` (downstream). Every downstream skill that produces aesthetic output references this skill's brief. + +Direct verbatim copying of an archetype's default palette into a new brand is the failure mode this skill exists to prevent. The brief shifts the archetype's defaults toward the business spec's specifics. + +--- + +## The framework: five steps, three rules, one hybrid bank + +1. Locate the design space. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. +2. Run input-side divergence. Read the shipped-demos signatures. Discard candidates that would land sibling to anything shipped. Record what was rejected and why. +3. Pull references. From the curated reference bank under `references/reference-bank/`, load the file(s) matching the chosen archetype-and-vertical. Augment with one to two discovered live references if the bank is sparse. Add discovered references back to the bank in the build PR. +4. Adapt. Shift the chosen archetype's defaults (palette, type, voice, layout, imagery direction) toward the business spec. The brief lands as concrete tokens, not abstract families. +5. Render and verify. Render the brief using the template in [`references/02-brief-template.md`](references/02-brief-template.md). Run output-side divergence. Output the brief plus the references list plus the divergence-check result. + +Full step-by-step in [`references/01-process.md`](references/01-process.md). The divergence schema and its three overlap rules are in [`references/03-divergence-check.md`](references/03-divergence-check.md). + +--- + +## The hybrid references model + +A curated bank that grows with each build. Each file under `references/reference-bank/` covers one archetype-and-vertical combination and holds three to six live reference URLs, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations covering western-boot maker, heritage barbershop, and balloon-ride experience. + +When a build draws from a sparse combination, the build is expected to commit the live references it discovered back to the bank as part of its build PR. The bank gets denser with use. + +--- + +## The divergence schema + +Each shipped demo carries a signature with seven fields: + +- `slug` +- `archetype` (the canonical archetype name from `brand-archetype-system`) +- `dominant_hue_family` (the recognizable colour family, e.g. leather-bone-saddle, dawn-navy-coral, dark-linen-amber) +- `voice_register` (e.g. story-forward third-person, atmospheric second-person, fitment-first technical) +- `primary_structural_pattern` (e.g. shoppable-grid-product-forward, arc-timeline-hero, fitment-selector-then-rails) +- `hero_shape` (e.g. dual-column-image-and-text, wide-photograph-with-band-below, full-bleed-image-with-overlay; canonical vocabulary in `references/05-section-shapes-vocabulary.md`) +- `footer_shape` (e.g. single-line-strip, multi-column-sitemap, type-only-no-links; same vocabulary file) + +Overlap rules (full set in [`references/03-divergence-check.md`](references/03-divergence-check.md)): + +- Two demos share archetype AND share dominant_hue_family => SIBLING (block). +- Two demos share archetype AND share voice_register AND share primary_structural_pattern => SIBLING (block). +- Two demos share only dominant_hue_family across different archetypes => WARN. +- The candidate's hero_shape matches the hero_shape of two or more shipped demos => WARN. +- The candidate's hero_shape matches three or more shipped demos AND any share an archetype family => BLOCK. +- The candidate's footer_shape matches three or more shipped demos => WARN. + +A worked example file of seven signatures lives at [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) for illustration; the live signatures file for any consuming project lives in that project, not in this skill. + +--- + +## Trademark and attribution + +Archetypes are NAMED for aesthetic families, NOT for brands, following the convention of `brand-archetype-system`. Live reference sites are cited as exemplars using nominative attribution language: "exemplified by [URL]", "characteristic of", "in the register of". This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified. + +--- + +## Reference files + +- [`references/00-overview.md`](references/00-overview.md) - The case for the skill, the hybrid references model, the two-direction divergence, the trademark posture. +- [`references/01-process.md`](references/01-process.md) - The five-step process, each step concrete enough to execute. +- [`references/02-brief-template.md`](references/02-brief-template.md) - The fillable brief template with section-by-section guidance. +- [`references/03-divergence-check.md`](references/03-divergence-check.md) - The signature schema and the overlap rules. +- [`references/04-shipped-demos-signatures-example.md`](references/04-shipped-demos-signatures-example.md) - Worked example signatures file with seven demos. +- [`references/05-section-shapes-vocabulary.md`](references/05-section-shapes-vocabulary.md) - Canonical open vocabulary of hero and footer section shapes plus archetype affinities. + +The curated reference bank lives in a `reference-bank/` subdirectory under `references/`. The bank ships with a README plus three seed archetype-and-vertical files: `premium-dtc-maker-western-boots.md`, `heritage-local-service-barbershop.md`, and `hospitality-experience-balloon-ride.md`. The bank's purpose and extension procedure are documented in its README; the seed files each carry three to four positive live references and one to two negative references for the chosen position. Load the bank file matching the build's archetype-and-vertical at step 3 of the process. diff --git a/skills/creative-brief-selector/references/00-overview.md b/skills/creative-brief-selector/references/00-overview.md new file mode 100644 index 0000000..337ea91 --- /dev/null +++ b/skills/creative-brief-selector/references/00-overview.md @@ -0,0 +1,79 @@ +# Overview + +The case for the skill, the references model, and the trademark posture. + +--- + +## The problem this skill exists for + +Portfolios of brand work drift toward house style. The first demo establishes a default; the second demo borrows it; the third has the same skeleton with a different name. Without a deliberate intervention at brief time, every new build leans on the same palette, the same micro-label tracking, the same hero gradient, the same voice register. The output is competent and sibling. + +This pattern is observable in any portfolio that has shipped more than two builds. The symptoms show up at the imagery stage, when a stone-and-amber palette that worked for one shape suddenly reads as the brand's signature across three shapes that should not share a signature. The fix is upstream: pick the position before the build starts, and verify it stays distinct as the build renders. + +This skill is the deliberate creative direction at brief time. + +--- + +## The hybrid references model + +Two parts: + +### The curated bank + +Files under `reference-bank/`, one per archetype-and-vertical combination. Each file holds three to six live reference URLs that exemplify the position, each with a one-line why and optional palette or type observations. The bank ships with three seed combinations and grows as new combinations are built against. + +The bank is the institutional memory of the portfolio. A new build for an archetype-and-vertical combination that has been done before loads the existing references and adapts. A new build for a sparse combination supplies new references during discovery and commits them back as part of its build PR. + +### Per-build discovery + +When the bank is sparse for a chosen combination, the build's first pass searches the live web for three to six exemplars. Curation rules are in [`reference-bank/README.md`](reference-bank/README.md). The discovered references serve the current build and seed the bank for future builds in the same combination. + +This is not a static reference list. The bank is supposed to drift over time as the portfolio grows; the discipline is that the bank reflects what was actually used in real builds. + +--- + +## The two-direction divergence check + +The skill runs divergence twice: once on input, once on output. + +### Input-side divergence + +Before any references are pulled, the skill loads the shipped-demos signatures file (a project artifact, not part of this skill; see [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md) for the illustrative format). Candidate archetypes are checked against the signatures. If a candidate would land sibling to a shipped demo, it is discarded and the rejection is recorded. + +The rejection record is itself useful output: it documents what the build was deliberately NOT. + +### Output-side divergence + +After the brief is rendered, the skill computes the brief's own signature (archetype, dominant hue family, voice register, primary structural pattern) and compares against the shipped signatures one more time. This catches adaptations that drifted back toward sibling territory during step 4 (the adapt step). + +The check produces one of three outcomes: `passed`, `warn-with-reasons`, or `block-with-reasons`. A `block` result means the brief cannot ship in its current form and needs adaptation before the next attempt. + +--- + +## Why two directions + +Input-side alone catches the obvious overlaps: picking an archetype that another demo already uses with the same palette family. Output-side catches the subtle drift: an archetype was picked clean of any sibling demo, but during adaptation the palette quietly converged on the recurring house family. + +The recurring stone-and-amber family is the worked example of this drift. The first build picked it intentionally; the second build adopted it because it was in the air; the third build adopted it because it felt like the brand. Without an output-side check, the brief itself becomes the carrier of the drift. + +--- + +## Trademark and attribution + +This skill follows the `brand-archetype-system` convention. Archetypes are named for aesthetic families ("Premium DTC Maker," "Heritage Local Service") not for brands. Live reference sites are cited as exemplars using nominative attribution language: + +- "exemplified by [URL]" +- "characteristic of [URLs]" +- "in the register of [URL]" + +This is descriptive and nominative fair use. A reference that pivots its identity does not invalidate the archetype it once exemplified, but it should be removed from the bank when the URL no longer shows what it was cited for. + +--- + +## What this skill is not + +- Not a logo designer. The brief includes a logo direction note ("type-led wordmark with a saddle-tan rule," "graphic mark in the dawn palette") but does not produce the mark itself. +- Not an identity system. The brief is the input to `brand-identity`, which produces the system. +- Not a finished design. The brief describes tokens; it does not lay them out into a finished page. +- Not a positioning exercise. The business spec is assumed to have positioning already. If positioning is open, run `brand-ideation` first. +- Not a taste machine. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. Taste is upstream of this skill. diff --git a/skills/creative-brief-selector/references/01-process.md b/skills/creative-brief-selector/references/01-process.md new file mode 100644 index 0000000..95c441e --- /dev/null +++ b/skills/creative-brief-selector/references/01-process.md @@ -0,0 +1,143 @@ +# The five-step process + +Each step concrete enough to execute. Run in order. Do not skip the divergence steps. + +--- + +## Inputs + +The skill takes a business spec: + +- Name (the brand name to be used in the brief) +- Vertical (e.g. western-boot maker, neighborhood barbershop, balloon-ride operator) +- Shape (the site shape: ecommerce-catalog, ecommerce-standout, local-service-booking, hospitality-experience, hospitality-food, institution-mission, inventory-listing, subscription-app, b2b-manufacturer, directory-marketplace) +- One-line vibe (a sentence describing what the brand wants to feel like) +- Shipped-demos signatures file (optional; the project artifact listing prior builds' signatures) + +If the shipped-demos file is absent, the build is the first in the portfolio. Run the divergence steps anyway and seed the signatures file with the rendered brief's signature. + +--- + +## Step 1. Locate the design space + +Read the business spec. Pick one to two candidate archetypes from `brand-archetype-system` that fit the vertical and shape. + +How to pick: + +- Read the vertical and shape against the 12 core archetypes. Most verticals have two or three plausible candidates; the shape narrows it. +- A western-boot maker maps plausibly to Luxe Considered (heritage premium), Rugged Utilitarian (workwear and craft), or Editorial Restrained (boutique editorial). The shape (ecommerce-standout, with a small editorial collection) narrows toward Luxe Considered with a Rugged Utilitarian secondary. +- A neighborhood barbershop maps plausibly to Warm Conversational (everyday-craft), Retro Nostalgic (period-specific), or Documentary Honest (real-people-real-work). The shape (local-service-booking, with a booking action) narrows toward Warm Conversational with a Retro Nostalgic secondary. +- A balloon-ride operator maps plausibly to Documentary Honest (landscape-and-light), Luxe Considered (aspirational-experience), or Warm Conversational (small-operator-warm). The shape (hospitality-experience, with a named arc and a booking flow) narrows toward Documentary Honest with a Luxe Considered secondary. + +Output of this step: + +- Primary candidate archetype (name) +- Optional secondary candidate archetype (name) with a note on which leads +- Two-sentence rationale tying each candidate to the vertical and shape + +--- + +## Step 2. Run input-side divergence + +Read the shipped-demos signatures file. Compare each candidate against every shipped demo using the rules in [`03-divergence-check.md`](03-divergence-check.md). + +Procedure: + +- For each candidate (primary, then secondary if present): + - For each shipped demo: + - If archetype matches AND dominant_hue_family matches => discard the candidate as SIBLING. + - If archetype matches AND voice_register matches AND primary_structural_pattern matches => discard the candidate as SIBLING. +- If all candidates are discarded, return to step 1 and pick fresh candidates from a different position on the four creative-direction axes. + +Output of this step: + +- The surviving candidate (the chosen archetype) +- A rejection log listing any discarded candidates with the reason (which shipped demo collided and on which fields) + +The rejection log is part of the brief output. It documents what the build was deliberately NOT. + +--- + +## Step 3. Pull references + +From `reference-bank/`, load the file matching the chosen archetype-and-vertical. Read the positive references and the negative references. + +If the bank has the combination: + +- Pull three to four positive references from the bank's list. Prefer the ones marked as canonical or most-recent. +- Read the negative references; they tell the build what register to avoid. + +If the bank is sparse for the combination: + +- Pull whatever positive references are available (one or two if that is all the bank has). +- Augment with one to two discovered live references that exemplify the position. Search the web for the vertical with the archetype's signal terms (e.g. for Luxe Considered DTC western boots: "premium western boot maker editorial photography prices visible"). +- Note the discovered references with the same format as the bank (URL plus one-line why). Add them back to the bank as part of the build PR. + +Output of this step: + +- A list of three to four live reference URLs, each with a one-line why +- A note on which references came from the bank versus which were discovered +- A list of negative references (registers to avoid) + +--- + +## Step 4. Adapt + +Take the chosen archetype's defaults from `brand-archetype-system` (palette, type, voice, layout, imagery direction). Shift them toward the business spec's specifics. + +Adaptations to document: + +- Palette. Pick 6 to 8 specific hex values that fit the brand. Name each with a token name (e.g. `Bone cream #f5ecd7`, `Saddle tan #a8753a`, `Pre-dawn navy #1a1f3a`). Each token gets a role (page background, primary text, primary CTA, accent, etc.). +- Type system. Pick the display family (often a serif from the archetype), the body family (often Inter or similar), and the micro-label treatment (tracking, casing, weight). Document the explicit differentiators from shipped demos (e.g. "tight uppercase tracking 0.04em on micro-labels, distinct from the loose 0.18em tracking the hospitality-experience build uses"). +- Voice. Pick the voice register (e.g. story-forward third-person; atmospheric second-person; fitment-first technical). Write five to ten voice samples in this voice using the brand name. +- Layout. Pick the structural pattern (e.g. shoppable-grid-product-forward; arc-timeline-hero; fitment-selector-then-rails). Describe the spine moves the homepage will run (four to six numbered moves). +- Section shapes. Pick a `hero_shape` and a `footer_shape` from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). The hero shape carries the most visual weight on the page; pick it deliberately based on archetype, audience, and the shapes already shipped in the portfolio. Document the rejected shapes in the brief with one-line reasons. Skipping this step means the engine inherits the most recently built hero shape regardless of brief specification, which is the drift signal this skill exists to catch. +- CTA grammar. Pick the verb register (e.g. "Shop the collection," "Book a dawn," "See the morning"). Verb-first, shape-appropriate. +- Imagery direction. Describe the shoot's register (e.g. "warm-bone studio seamless, three-quarter angle, soft overhead, products fill 70 percent of frame"). Specify aspect ratios per page slot. + +Each adaptation choice gets a sentence of why. The brief is a referenceable artifact; it should explain itself. + +Output of this step: + +- The full adaptation set, ready to render into the brief template. + +--- + +## Step 5. Render and verify + +Render the brief using the template in [`02-brief-template.md`](02-brief-template.md). + +After rendering, compute the brief's own signature and run output-side divergence: + +- `archetype`: the chosen archetype (from step 1) +- `dominant_hue_family`: derived from the palette tokens +- `voice_register`: from the voice section +- `primary_structural_pattern`: from the spine moves +- `hero_shape`: from the section-shapes choice in step 4 +- `footer_shape`: from the section-shapes choice in step 4 + +Compare this signature against every shipped demo using the full rule set in [`03-divergence-check.md`](03-divergence-check.md). The check now runs seven rules: the original three pairwise rules (archetype/hue, archetype/voice/pattern, recurring hue across archetypes) plus the three aggregate shape rules (hero shape collision warn at two matches, hero shape archetype-collision block at three matches with shared family, footer shape warn at three matches). + +Possible outcomes: + +- passed. No overlaps. The brief is ready to hand off. +- warn-with-reasons. The brief shares a single field (most commonly dominant_hue_family) with a shipped demo, but not enough to be sibling. Surface the warn with the matched fields so the consumer can make a deliberate call. +- block-with-reasons. The brief is sibling to a shipped demo. Return to step 4 and adapt further before re-rendering. Common fixes: swap the dominant accent colour, restructure one of the spine moves, shift the voice register. + +Output of this step: + +- The rendered brief +- The references list (from step 3) +- The divergence-check result with all matched fields if any +- A one-line summary suitable for the build PR's description + +--- + +## Failure modes + +- Skipping step 2. Picking the archetype that "feels right" without checking against shipped demos is how the portfolio drifts toward house style. +- Skipping step 5. Adapting in step 4 without re-checking on output is how the brief itself becomes the carrier of drift. +- Verbatim copying from the archetype's default palette. The archetypes provide anchor points, not endpoints. If the brief's palette is the archetype's palette unchanged, the brief is the archetype, not a build. +- Citing references without why-lines. A reference URL without a one-line why is decoration. The why is what makes the reference usable in step 4. +- Hand-waving the divergence check. The check is not a vibe call. It is a mechanical comparison against the schema. If it produces a block, the adaptation is incomplete. +- Treating the rejection log as overhead. The rejection log is part of the deliverable. It tells the next build what is already taken. diff --git a/skills/creative-brief-selector/references/02-brief-template.md b/skills/creative-brief-selector/references/02-brief-template.md new file mode 100644 index 0000000..96ac397 --- /dev/null +++ b/skills/creative-brief-selector/references/02-brief-template.md @@ -0,0 +1,190 @@ +# The brief template + +A fillable markdown skeleton. Fill every section. A section left blank is a section the build will fill with the house default, which is exactly the drift this skill exists to prevent. + +The template is modeled on the structure proven by real shipped builds. The worked example link at the bottom of this file shows the structure rendered against a real build. + +--- + +## Template + +```markdown +# Creative direction: <Brand Name> as <archetype position> + +A reusable brief for the <Brand Name> build. <One-sentence purpose: what shape is this, what position is this, why this brief>. + +Use this brief for: + +- <Specific use case 1> +- <Specific use case 2> + +Do NOT use this brief for: + +- <Adjacent shape that should NOT use this brief> +- <Adjacent position that should NOT use this brief> + +## The <N> spine moves + +1. <Move 1 name>. <One paragraph describing the move, specific to the shape>. +2. <Move 2 name>. <One paragraph>. +3. <Move 3 name>. <One paragraph>. +4. <Move 4 name>. <One paragraph>. +<continue 5, 6 if the shape calls for them> + +## Register + +- Positive reference frame: <one sentence describing what the brand IS, with named exemplars in nominative attribution> +- Negative reference frame: <one sentence describing what the brand is NOT, with named non-exemplars> + +## Live reference sites + +The references this brief draws from. Each is a real site exemplifying the chosen position. + +- [<URL 1>] - <one-line why; what specifically this site does that the brief inherits> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional> + +Negative references (do NOT pull from): + +- [<URL>] - <one-line why this register is the wrong one> + +## Section shapes (hero and footer; first-class brief outputs) + +Pick a `hero_shape` and a `footer_shape` from [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Document the choice with rationale; the choice is not optional and a brief without these fields does not pass the divergence check. + +### `hero_shape`: <chosen shape label, e.g. `wide-photograph-with-band-below`> + +<One paragraph: why this shape, what the chosen shape signals to the visitor that the alternatives do not, what shapes were rejected and why. Reference the section-shapes vocabulary by label.> + +Rejected shapes: + +- `<rejected shape 1>` - <one-line why this shape was wrong for this brief> +- `<rejected shape 2>` - <one-line why this shape was wrong for this brief> + +### `footer_shape`: <chosen shape label, e.g. `single-line-strip`> + +<One paragraph: why this footer shape, what it does for the page that alternatives do not.> + +Rejected shapes: + +- `<rejected shape>` - <one-line why> + +## Palette token shape (specific to this brand; do not reuse across brands) + +\| Token \| Hex \| Role \| +\|---\|---\|---\| +\| <Token 1 name> \| `#hex` \| <Role> \| +\| <Token 2 name> \| `#hex` \| <Role> \| +\| <Token 3 name> \| `#hex` \| <Role> \| +\| <Token 4 name> \| `#hex` \| <Role> \| +\| <Token 5 name> \| `#hex` \| <Role> \| +\| <Token 6 name> \| `#hex` \| <Role> \| +\| <Token 7 name> \| `#hex` \| <Role, optional> \| +\| <Token 8 name> \| `#hex` \| <Role, optional> \| + +Do NOT re-use <named hue family from a shipped demo, e.g. "stone-50 + amber-300 (the hospitality-experience default from the X build)">. + +## Type system + +- Display. <Family choice with stack notation>, <weight>, <tracking>. +- Body. <Family choice>, <weight>. +- Brand wordmark. <Family, case, tracking>. Distinct from <named shipped demo's wordmark treatment, e.g. "the loose 0.22em tracking used on the hospitality build">. +- Micro-labels. <Family, case, tracking>. <One-line on the explicit differentiator from shipped demos>. +- Numerics. <Family, tabular-nums or proportional, treatment for prices>. + +## CTA grammar + +- Primary on home. "<Verb-first label>". <One-line on why this verb>. +- Secondary on home. "<Verb-first label>". <One-line on why this verb>. +- On product or detail page. "<Label>". Verb-shape-appropriate. +- On craft or about page. "<Label>". Should close back to the primary action. + +## Image-ready spine + +The structure must be image-ready before any imagery pass runs. Per page slot: + +\| Page \| Aspect \| Count \| Source \| +\|---\|---\|---\|---\| +\| <Page slot 1> \| <e.g. 5:6 portrait> \| 1 \| <e.g. the signature product> \| +\| <Page slot 2> \| <e.g. 4:5 portrait> \| <e.g. one per product> \| <e.g. each product, on its own card> \| +\| <Page slot 3> \| <e.g. 16:9 wide> \| 1 \| <e.g. one lifestyle scene supporting the craft band> \| +\| <continue for every page> \| \| \| \| + +Each slot uses a placeholder during Phase A and is filled by the imagery pass in Phase B. Placeholders carry the alt text the final image will carry, so the swap is structurally drop-in. + +## Voice samples + +Five to ten lines in the brand's voice, used downstream by content-and-copy and landing-page-copy. + +- <Sample 1> +- <Sample 2> +- <Sample 3> +- <Sample 4> +- <Sample 5> +- <Sample 6, optional> +- <Sample 7, optional> + +## Honesty contract (unchanging across the portfolio) + +- <Functional element, e.g. cart, booking form> is real client-side, <demo surface, e.g. checkout, payment> is a clearly labelled demo that processes nothing. +- Fictitious brand disclosure in the footer and in any JSON-LD `description` field. +- Demo-only labelling on any demo surface in the brand's primary accent colour. +- All prices and figures fictitious. No promotional cadence, no fabricated reviews, no fabricated press quotes. +- No real brand mark. The logo pass, if any, is a separate later run. + +## Acceptance checklist (Phase A criteria) + +A build matches this brief if: + +- [ ] <Move 1 acceptance criterion> +- [ ] <Move 2 acceptance criterion> +- [ ] <Move 3 acceptance criterion> +- [ ] <Move 4 acceptance criterion> +- [ ] Palette is documentable as <N> tokens, distinct from any shipped demo's tokens. +- [ ] Type micro-labels have a distinct treatment from <named shipped demo's treatment>. +- [ ] Per-page image slots are wired with descriptive alt text, ready for a Phase B drop-in. +- [ ] Honesty contract intact. + +## Divergence-check result + +- Archetype: <chosen archetype name from brand-archetype-system> +- Dominant hue family: <derived from palette, e.g. "leather-bone-saddle"> +- Voice register: <e.g. "story-forward third-person"> +- Primary structural pattern: <e.g. "shoppable-grid-product-forward"> +- Hero shape: <chosen label from 05-section-shapes-vocabulary.md> +- Footer shape: <chosen label from 05-section-shapes-vocabulary.md> + +Input-side divergence: <passed \| warn-with-reasons \| block-with-reasons>. <If anything was rejected at step 2, list it here: rejected <archetype> because it collided with <shipped demo slug> on <field>>. + +Output-side divergence: <passed \| warn-with-reasons \| block-with-reasons>. <If warn or block, list the matched fields and the colliding demo. Rules 4 and 6 surface as warns; Rule 5 surfaces as a block; Rules 1, 2, 3 surface per their definitions in 03-divergence-check.md.> + +--- +``` + +--- + +## Worked example + +The Pinto Mesa Boots store-spine brief at `rampstackco-app/progress/ecommerce-standout-store-spine-brief.md` is a faithful render of this template against a real shipped build (ecommerce-standout shape; Luxe Considered with Rugged Utilitarian influence). It demonstrates: + +- The five spine moves (product-forward hero, shoppable grid, honest wayfinding, craft as supporting band, premium trust signals). +- The leather-forward palette with explicit do-not-reuse against the prior hospitality build's stone-and-amber. +- The type differentiation (tight uppercase microlabel tracking, distinct from the prior hospitality build's loose tracking). +- The image-ready spine with per-page aspect / count / source. +- The acceptance checklist as Phase-A criteria. + +Use the worked example as a structural reference when rendering new briefs. + +--- + +## Common section failures + +- Skipping the "Do NOT use this brief for" section. The negative-use section is what keeps the brief from being mis-applied to an adjacent shape. +- Spine moves that are abstract. "Lead with the product" is not a spine move. "Lead with the signature product shown large at 5:6 with one primary CTA and price-forward entry" is. +- Palette without explicit do-not-reuse lines. The do-not-reuse line is what makes the divergence check checkable. +- Type system without the explicit differentiator from shipped demos. This is the single field most likely to drift if not pinned. +- CTA grammar in mood words. "Welcoming" is not CTA grammar. "Shop the collection" is. +- Image-ready spine without aspect ratios. Without the aspect ratios the imagery pass cannot generate to the right shape. +- Honesty contract treated as boilerplate. The contract is part of what makes the brand demo-honest; cut and paste it but verify each line still applies to the specific build. +- Acceptance checklist as motivational language. The checklist is the build's pass/fail criteria, not a vibe statement. diff --git a/skills/creative-brief-selector/references/03-divergence-check.md b/skills/creative-brief-selector/references/03-divergence-check.md new file mode 100644 index 0000000..8374b0f --- /dev/null +++ b/skills/creative-brief-selector/references/03-divergence-check.md @@ -0,0 +1,229 @@ +# The divergence check + +The signature schema, the overlap rules, and the comparison procedure. + +--- + +## Signature schema + +Each shipped demo carries a signature with seven fields. The schema is small on purpose: any field that takes judgment to populate gets argued about; a small mechanical schema gets used. + +```yaml +- slug: <kebab-case slug, e.g. pinto-mesa-boots> + archetype: <canonical archetype name from brand-archetype-system, e.g. luxe-considered> + dominant_hue_family: <named hue family, e.g. leather-bone-saddle> + voice_register: <named register, e.g. story-forward-third-person> + primary_structural_pattern: <named pattern, e.g. shoppable-grid-product-forward> + hero_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. dual-column-image-and-text> + footer_shape: <named shape from 05-section-shapes-vocabulary.md, e.g. single-line-strip> +``` + +The last two fields (`hero_shape` and `footer_shape`) are the latest schema additions. The canonical vocabulary for both lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +### slug + +The kebab-case slug for the shipped build. Used to identify the demo in rejection logs and warn or block reasons. + +### archetype + +The canonical archetype name from `brand-archetype-system`. Use the file slug from `references/core-archetypes/` (e.g. `luxe-considered`, `documentary-honest`, `warm-conversational`). If the demo composes two archetypes, record both as a hyphenated pair with the lead first (e.g. `luxe-considered-rugged-utilitarian`). + +### dominant_hue_family + +The recognizable colour family the demo reads as, in three to four words. Examples: + +- `leather-bone-saddle` (Pinto Mesa Boots v2) +- `dawn-navy-coral` (Drift & Dawn after the dawn retune) +- `dark-linen-amber` (Pho Heights) +- `warm-walnut-brass` (Iron & Rye) +- `forest-green-cream` (Clearflow Initiative) +- `slate-and-amber` (the original Drift & Dawn pre-retune, kept for historical reference) +- `stone-and-amber` (the recurring family the imagery passes surfaced as the drift signal) + +The naming convention: two to four colour terms separated by hyphens, lowercase. The terms should be specific enough that two demos with materially different palettes get different families even if they share an undertone. + +### voice_register + +The brand's voice in three to four words. Examples: + +- `story-forward-third-person` +- `atmospheric-second-person` +- `fitment-first-technical` +- `evidence-and-mission-first` +- `restrained-citation-bearing` +- `warm-everyday-craft` + +The naming convention: hyphenated phrase that names the register the voice samples in the brief operate in. + +### primary_structural_pattern + +The structural pattern the homepage runs, in three to five words. Examples: + +- `shoppable-grid-product-forward` +- `arc-timeline-hero-with-packages-strip` +- `fitment-selector-then-rails` +- `editorial-hero-then-courses-grid` +- `barber-roster-then-services-menu` +- `theory-of-change-hero-then-evidence-band` + +The naming convention: name the homepage's primary spine in a way another build can recognize from the rendered page. + +### hero_shape + +The shape of the hero section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `dual-column-image-and-text` +- `wide-photograph-with-band-below` +- `full-bleed-image-with-overlay` +- `type-led-prose` +- `centered-single-column` +- `asymmetric-large-image-small-text` +- `grid-of-elements` +- `data-table-or-spec-led` + +A build that needs a shape not in the vocabulary documents and proposes a new label per the extension procedure in `05-section-shapes-vocabulary.md`. + +### footer_shape + +The shape of the footer section, drawn from the vocabulary in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). Examples: + +- `single-line-strip` +- `multi-column-sitemap` +- `type-only-no-links` +- `editorial-colophon-with-masthead` +- `newsletter-band-with-credits` +- `dark-cta-then-credits` + +--- + +## Overlap rules + +The comparison is mechanical. The skill applies these rules in order; the first rule that fires determines the outcome for that pair. + +### Rule 1: Same archetype + same dominant_hue_family + +If two demos share `archetype` AND share `dominant_hue_family`, they are SIBLING (block). + +Two demos in the same archetype with the same hue family will read as the same brand at a glance. The block forces an adaptation in either archetype or palette before the brief can ship. + +### Rule 2: Same archetype + same voice_register + same primary_structural_pattern + +If two demos share `archetype` AND share `voice_register` AND share `primary_structural_pattern`, they are SIBLING (block). + +This catches the case where the palettes diverge but the underlying skeleton is identical. The build will look different on first glance and identical on the second. + +### Rule 3: Same dominant_hue_family across different archetypes + +If two demos share `dominant_hue_family` but their `archetype` differs, the outcome is WARN. + +A recurring hue family across different archetypes is the most common drift signal in a portfolio. The warn surfaces the recurrence so the consumer can choose to break the pattern or accept it as the portfolio's signature. + +### Rule 4: Hero shape collision (warn) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of two or more shipped demos, the outcome is WARN. + +The warn surfaces a deliberation note listing every shipped demo using the same shape. The brief author either justifies the repeat (and records that justification in the brief's section-shapes rationale) or picks a different shape from the vocabulary. Two demos sharing a hero shape is acceptable for a portfolio of nine to twelve demos; three or more is the point where the shape starts reading as the engine's house default. + +### Rule 5: Hero shape archetype-collision (block) + +If the candidate's proposed `hero_shape` matches the `hero_shape` of three or more shipped demos AND any of those matching demos share an archetype family with the proposed brief, the outcome is BLOCK. + +This catches the case where the brief is heading toward the strongest sibling result possible: the same hero shape AND a related archetype. The block forces the brief to choose differently on at least one dimension (a different hero shape, or a different archetype lead, or a documented justification that escalates to the deliberation notes with explicit reasoning). + +Archetype-family overlap is computed by comparing the lead archetype tokens. Composed archetypes share a family if either of their tokens matches. For example, `editorial-restrained` and `editorial-restrained-documentary-honest` share the `editorial-restrained` family; `documentary-honest-luxe-considered` and `rugged-utilitarian-documentary-honest` share the `documentary-honest` family. + +### Rule 6: Footer shape collision (warn) + +If the candidate's proposed `footer_shape` matches the `footer_shape` of three or more shipped demos, the outcome is WARN. + +Footers tolerate more repetition than heroes since they carry less visual weight and are more functional than expressive. The threshold (three matching demos for a warn, not two) is correspondingly higher. There is no block-level rule for footer shapes at this scope; if a portfolio-wide footer shape emerges as the house default, it becomes part of the portfolio's signature rather than a per-build distinctness failure. + +### Rule 7: Anything else + +If no rule above fires, the outcome is PASSED. + +--- + +## Why shapes carry weight + +Heroes carry the most visual weight on a page and the most signal to the visitor. Hero-shape repetition across a portfolio compresses the perceived distance between builds even when palette, voice, and structural pattern diverge. The early showcase portfolio surfaced this drift signal: most builds shipped a `dual-column-image-and-text` or `full-bleed-image-with-overlay` hero regardless of brief specification, because the engine pattern-matched the most recently built shape. + +Footers carry less weight and are typically more functional than expressive. They tolerate more repetition before the repetition becomes a distinctness cost. + +Rules 4, 5, and 6 exist to make hero-shape and footer-shape choice an explicit selection at brief time rather than an implicit inheritance from the most recently built demo. + +--- + +## Comparison procedure + +``` +# Pairwise rules (run on every candidate-shipped pair): +for candidate in candidates: + for shipped in shipped_demos: + if rule_1(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'dominant_hue_family']) + continue + if rule_2(candidate, shipped): + record_block(candidate, shipped, fields=['archetype', 'voice_register', 'primary_structural_pattern']) + continue + if rule_3(candidate, shipped): + record_warn(candidate, shipped, fields=['dominant_hue_family']) + continue + +# Aggregate rules (run once per candidate against the full set): +for candidate in candidates: + hero_matches = [s for s in shipped_demos if s.hero_shape == candidate.hero_shape] + if len(hero_matches) >= 3 and any(shares_archetype_family(candidate, s) for s in hero_matches): + record_block(candidate, hero_matches, fields=['hero_shape', 'archetype']) # rule 5 + elif len(hero_matches) >= 2: + record_warn(candidate, hero_matches, fields=['hero_shape']) # rule 4 + + footer_matches = [s for s in shipped_demos if s.footer_shape == candidate.footer_shape] + if len(footer_matches) >= 3: + record_warn(candidate, footer_matches, fields=['footer_shape']) # rule 6 +``` + +The check produces three lists: blocks, warns, and a passed flag (true iff blocks and warns are both empty). + +### Input-side outcome + +- If any block was recorded against the primary candidate, discard it. If the secondary candidate also blocks, return to step 1 and pick fresh candidates. +- Warns at input-side are surfaced in the rejection log but do not discard the candidate. + +### Output-side outcome + +After the brief is rendered, the brief's own signature is checked against every shipped demo using the same rules. The outcome is one of: + +- passed: no blocks, no warns. The brief is ready to hand off. +- warn-with-reasons: warns only. The brief shares a single field (most commonly `dominant_hue_family`) with a shipped demo. Surface the warn with the matched fields so the consumer can make a deliberate call. +- block-with-reasons: at least one block. The brief is sibling to a shipped demo. Return to step 4 of the process and adapt further before re-rendering. + +--- + +## What changes a block to a warn or a pass + +Concretely: + +- Shift the dominant_hue_family. Swap the dominant accent colour, change the page background's temperature, or change the accent colour family (saddle to oxblood to navy). Recompute the family. +- Shift the primary_structural_pattern. Change which move leads the page. A "product-forward" pattern becomes "story-forward" by reordering the spine moves. Recompute the pattern. +- Shift the voice_register. Change the voice from third-person to second-person, or from atmospheric to technical. Recompute the register. +- Compose a different archetype pair. If the chosen archetype is locked, change the secondary archetype to shift the brief's centre of mass. + +Each adaptation should be a deliberate choice, recorded in the brief's adaptation notes (step 4 of the process). + +--- + +## The signatures file + +The signatures file is a project artifact, not part of this skill. The consuming project maintains it (typically as `progress/shipped-demos-signatures.yml` or similar). The illustrative format is in [`04-shipped-demos-signatures-example.md`](04-shipped-demos-signatures-example.md). + +Whenever a new build ships, append its signature to the file. The signatures grow with the portfolio; the divergence check stays current. + +--- + +## Failure modes + +- Filling fields with vibe words. "vibrant-modern" is not a hue family; "saddle-bone-walnut" is. The schema works because the field values are specific. Vague values produce vague checks. +- Re-using the same family across builds without recomputing. When a build's palette shifts during step 4, the dominant_hue_family must shift with it. A stale signature is worse than a missing signature. +- Treating warns as ignorable. A warn is the portfolio's drift early-warning. Three consecutive warns on the same hue family is the portfolio adopting a house signature, which is the failure mode this skill exists to prevent. +- Hand-waving the rules. The rules are mechanical. If a candidate blocks under rule 1, it blocks; the answer is to adapt, not to argue with the rule. diff --git a/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md b/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md new file mode 100644 index 0000000..b770582 --- /dev/null +++ b/skills/creative-brief-selector/references/04-shipped-demos-signatures-example.md @@ -0,0 +1,141 @@ +# Shipped-demos signatures: worked example + +An illustrative signatures file with seven worked entries. This file is example-only; the live signatures file for any consuming project lives in that project (typically at `progress/shipped-demos-signatures.yml`), not in this skill. + +The schema is defined in [`03-divergence-check.md`](03-divergence-check.md). Each entry has seven fields: `slug`, `archetype`, `dominant_hue_family`, `voice_register`, `primary_structural_pattern`, `hero_shape`, `footer_shape`. The last two (`hero_shape`, `footer_shape`) are the latest additions; their canonical vocabulary lives in [`05-section-shapes-vocabulary.md`](05-section-shapes-vocabulary.md). + +The seven entries below are illustrative records of seven sibling-shape demos a portfolio might ship. They are written here as a worked example of what the file looks like in practice. The archetype values reference the canonical names from `brand-archetype-system`. + +--- + +## Example signatures + +```yaml +demos: + - slug: fitfirst-parts + archetype: technical-precise + dominant_hue_family: slate-and-amber + voice_register: fitment-first-technical + primary_structural_pattern: fitment-selector-then-rails + hero_shape: dual-column-image-and-text + footer_shape: multi-column-sitemap + + - slug: iron-and-rye-barbershop + archetype: warm-conversational-retro-nostalgic + dominant_hue_family: warm-walnut-brass + voice_register: warm-everyday-craft + primary_structural_pattern: barber-roster-then-services-menu + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: pho-heights + archetype: documentary-honest-luxe-considered + dominant_hue_family: dark-linen-amber + voice_register: chef-essay-first-person + primary_structural_pattern: editorial-hero-then-signatures-menu + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: volta-robotics + archetype: technical-precise + dominant_hue_family: graphite-and-signal-orange + voice_register: spec-forward-technical + primary_structural_pattern: product-strip-then-spec-table + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: clearflow-initiative + archetype: editorial-restrained + dominant_hue_family: forest-green-cream + voice_register: restrained-citation-bearing + primary_structural_pattern: theory-of-change-hero-then-evidence-band + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip + + - slug: pinto-mesa-boots + archetype: luxe-considered-rugged-utilitarian + dominant_hue_family: leather-bone-saddle + voice_register: story-forward-third-person + primary_structural_pattern: shoppable-grid-product-forward + hero_shape: dual-column-image-and-text + footer_shape: single-line-strip + + - slug: drift-and-dawn + archetype: documentary-honest-luxe-considered + dominant_hue_family: dawn-navy-coral + voice_register: atmospheric-second-person + primary_structural_pattern: arc-timeline-hero-with-packages-strip + hero_shape: full-bleed-image-with-overlay + footer_shape: single-line-strip +``` + +--- + +## Why each field is what it is + +### fitfirst-parts (ecommerce-catalog) + +- archetype: `technical-precise`. The build leads with a YMM (year-make-model) fitment selector. Grids, monospace numerics, system-feeling. +- dominant_hue_family: `slate-and-amber`. Cool slate ground with warm amber accents on safety and action surfaces. +- voice_register: `fitment-first-technical`. The voice asks "does it fit your vehicle" before anything else. +- primary_structural_pattern: `fitment-selector-then-rails`. The home leads with the selector, then rails of parts filtered by the confirmed vehicle. + +### iron-and-rye-barbershop (local-service-booking) + +- archetype: `warm-conversational-retro-nostalgic`. Heritage barbershop register; walnut and brass; period-specific cues. +- dominant_hue_family: `warm-walnut-brass`. Walnut wood and brass hardware are the recognizable palette. +- voice_register: `warm-everyday-craft`. The voice is the shop talking about its work in plain terms. +- primary_structural_pattern: `barber-roster-then-services-menu`. Roster (initials) leads, services menu follows, atmosphere gallery threads the page. + +### pho-heights (hospitality-food) + +- archetype: `documentary-honest-luxe-considered`. Dark linen photography, real-food register, premium restraint. +- dominant_hue_family: `dark-linen-amber`. Dark linen background dominates; amber surfaces as the accent. +- voice_register: `chef-essay-first-person`. The chef-partner essay is the page's voice. +- primary_structural_pattern: `editorial-hero-then-signatures-menu`. Edge-to-edge hero, chef essay, signatures section with image-led cards. + +### volta-robotics (b2b-manufacturer) + +- archetype: `technical-precise`. Industrial spec-table register. Same archetype as fitfirst-parts but a different hue family and a different structural pattern (so rule 1 does not fire on this pair). +- dominant_hue_family: `graphite-and-signal-orange`. Industrial graphite with hazard-orange accents on action surfaces. +- voice_register: `spec-forward-technical`. Specs lead, narrative supports. +- primary_structural_pattern: `product-strip-then-spec-table`. Product strip up top, deep spec tables follow. + +### clearflow-initiative (institution-mission) + +- archetype: `editorial-restrained`. Counsel-restrained register; numbers before adjectives; citation-bearing voice. +- dominant_hue_family: `forest-green-cream`. Deep forest green sections with warm cream surfaces. +- voice_register: `restrained-citation-bearing`. Third-person about the org, low-register confidence, numbers leading. +- primary_structural_pattern: `theory-of-change-hero-then-evidence-band`. Theory of change in the hero, evidence band (lives reached, water systems built) follows. + +### pinto-mesa-boots (ecommerce-standout) + +- archetype: `luxe-considered-rugged-utilitarian`. Premium DTC maker register with workwear and craft secondary. +- dominant_hue_family: `leather-bone-saddle`. Bone cream ground with saddle tan and walnut accents; oxblood as the demo-only chip. +- voice_register: `story-forward-third-person`. The brand talks about itself in the third person, with material before adjectives. +- primary_structural_pattern: `shoppable-grid-product-forward`. Product-forward hero, six-boot shoppable grid on the home, by-last wayfinding. + +### drift-and-dawn (hospitality-experience) + +- archetype: `documentary-honest-luxe-considered`. Photography-led, atmospheric, aspirational. Same composed archetype as pho-heights but a different vertical and a different hue family (so rule 1 does not fire on this pair). +- dominant_hue_family: `dawn-navy-coral`. Pre-dawn navy with coral and pale-gold accents, deliberately distinct from the hospitality-experience stone-and-amber default the original build used. +- voice_register: `atmospheric-second-person`. The brand walks the visitor through the morning in second person. +- primary_structural_pattern: `arc-timeline-hero-with-packages-strip`. Hero with arc preview, packages strip with named prices, six-moment timeline on the experience page. + +--- + +## What this example exercises + +The seven entries are constructed to exercise the divergence rules: + +- Rule 1 not firing: `fitfirst-parts` and `volta-robotics` share `archetype: technical-precise` but differ on `dominant_hue_family` (`slate-and-amber` vs `graphite-and-signal-orange`). No block. +- Rule 1 not firing: `pho-heights` and `drift-and-dawn` share `archetype: documentary-honest-luxe-considered` but differ on `dominant_hue_family` (`dark-linen-amber` vs `dawn-navy-coral`). No block. The deliberate retune from the original `slate-and-amber` to `dawn-navy-coral` is what kept this pair from blocking. +- Rule 3 historical case: the original `drift-and-dawn` (pre-retune, hue family `slate-and-amber`) would have triggered rule 3 against `fitfirst-parts` (also `slate-and-amber`) across different archetypes. The retune resolved the recurring family. + +--- + +## How to use this example + +Copy the YAML block to a `progress/shipped-demos-signatures.yml` file in the consuming project. Edit the entries to match the actual shipped builds. Append new entries as builds ship. The divergence check in [`03-divergence-check.md`](03-divergence-check.md) reads from this file. + +This file is example-only. The skill does not parse this example file at runtime; it parses the consuming project's signatures file. The example exists to show what the file should look like. diff --git a/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md b/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md new file mode 100644 index 0000000..0195584 --- /dev/null +++ b/skills/creative-brief-selector/references/05-section-shapes-vocabulary.md @@ -0,0 +1,151 @@ +# Section shapes vocabulary + +A canonical, open vocabulary of section shapes the brief picks from for the hero and footer sections (with optional later extension to trust-strip, CTA-close, and how-it-works sections). The vocabulary is a starting point, not a closed enum. Builds can document and propose a new shape if none of the listed labels fits. + +Section shapes are first-class brief outputs. The brief picks a shape per section explicitly and records the rationale next to palette and voice rationale. Two new fields per signature record (`hero_shape` and `footer_shape`) let the divergence check fire against shape collision across shipped demos. + +The divergence rules for shapes are in [`03-divergence-check.md`](03-divergence-check.md) (Rules 4, 5, 6). + +--- + +## Hero shapes (open list, starting set) + +### `dual-column-image-and-text` + +Image on one side of the hero, heading and lede and CTAs on the other. CSS grid with two columns (often around 1.1fr / 1fr). The engine's house default and the shape most prone to overuse in a portfolio that grows without explicit shape selection. + +- When it fits: brands where the photograph and the type carry roughly equal weight and the eye is meant to ricochet between them. Premium DTC product hero is the canonical fit; a single product on the image side and a price-and-CTA on the type side. +- References: [allbirds.com](https://allbirds.com), [tecovas.com](https://tecovas.com). +- Archetype affinities: Luxe Considered, Warm Conversational, Editorial Restrained (mild). + +### `wide-photograph-with-band-below` + +Single full-width hero photograph (aspect 16:9 or wider) spanning the content width, with structured content (search rail, CTA pair, lede, filter chips) stacked vertically below the photograph. The photograph carries the page; the band below carries the affordances. + +- When it fits: inventory marketplaces, regional specialists, sites where the photograph signals what the marketplace is for and the band carries the controls. Also fits magazine-style editorial registers where one strong image opens an article. +- References: [bringatrailer.com](https://bringatrailer.com), [icon4x4.com](https://icon4x4.com). +- Archetype affinities: Rugged Utilitarian, Documentary Honest, Editorial Restrained. + +### `full-bleed-image-with-overlay` + +Image fills the section (or near-fills, often at `object-cover` with `absolute inset-0`), with type overlaid via a gradient. Dramatic, cinema-poster register. Strongest visual signal of all hero shapes; correspondingly the easiest to over-saturate. + +- When it fits: hospitality experiences where the place is the product (balloon ride, restaurant, hotel), mission-driven nonprofits where the documentary photograph is the evidence, premium B2B where the product is photographed at scale. Atmospheric and cinematic. +- References: [bombasses.com](https://bombasses.com) (hospitality), [charitywater.org](https://charitywater.org) (institution-mission). +- Archetype affinities: Documentary Honest, Luxe Considered (composed with Documentary Honest), Editorial Restrained. + +### `type-led-prose` + +No image in the hero. The H1 and lede do the work; image (if any) appears below the hero as a supporting element. Editorial publication register. The whitespace and the type carry the page. + +- When it fits: editorial publications, ideas-led brands, B2B SaaS where the proposition is conceptual, premium consultancies, law and finance where understated credibility is the play. +- References: [nytimes.com](https://nytimes.com), [stripe.com](https://stripe.com) (mild type-led, with type leading and a subtle product render below). +- Archetype affinities: Editorial Restrained, Technical Precise (mild). + +### `centered-single-column` + +Narrow content column centered on the page, H1 and lede only, minimal. Often paired with atmospheric brand registers where the centered alignment signals "considered, not loud." + +- When it fits: portfolio brands, atmospheric or contemplative registers, single-product brands where the page is essentially a long-scroll story and the hero is just the opening line. +- References: [linear.app](https://linear.app), [framer.com](https://framer.com) (both run centered single-column heroes at times). +- Archetype affinities: Editorial Restrained, Luxe Considered. + +### `asymmetric-large-image-small-text` + +One element dominates the hero (usually an image at 70 to 80 percent of width), the other is caption-scale beside or below it. Distinct from `dual-column-image-and-text` by the imbalance: the dual-column is roughly balanced, the asymmetric leans heavily. + +- When it fits: magazine cover style, photography portfolios, single-product hero where the product carries everything and the type is a caption-scale credit line. +- References: [magnum.com](https://magnum.com), [aesop.com](https://aesop.com) (varies; some pages use asymmetric layouts). +- Archetype affinities: Luxe Considered, Documentary Honest, Editorial Restrained. + +### `grid-of-elements` + +The hero IS a grid: product tiles, listing cards, directory entries, no single anchor image. The inventory or directory itself is the hero. Distinct from `wide-photograph-with-band-below` by having no single dominant image; the grid carries the meaning. + +- When it fits: directory and marketplace shapes where the breadth of the catalog is the value, ecommerce catalog shapes where shoppability above the fold is the conversion lever. +- References: [airbnb.com](https://airbnb.com) (search results hero is the grid), [unsplash.com](https://unsplash.com). +- Archetype affinities: Technical Precise, Editorial Restrained (with restraint), Rugged Utilitarian (if the directory is the working catalog). + +### `data-table-or-spec-led` + +A data table or spec block is the hero element. The numbers and the comparison carry the page. Technical Precise register, B2B engineering context, comparison-led purchase decisions. + +- When it fits: B2B engineering procurement, hardware comparison sites, financial product comparison, anywhere the buyer is data-anchored before they care about photography. +- References: [parametric-portfolios.com](https://parametric-portfolios.com), [substack.com/pricing](https://substack.com/pricing) (pricing-table-as-hero variants). +- Archetype affinities: Technical Precise, Editorial Restrained. + +--- + +## Footer shapes (open list, starting set) + +### `single-line-strip` + +One row carrying the brand disclosure paragraph and the footer nav, no multi-column structure. Mobile and desktop render the same content reflowed. The default across most demos in the showcase portfolio. + +- When it fits: small-collection brands, single-purpose microsites, demo and showcase contexts, brands where the footer is meant to be functional chrome rather than navigation in its own right. +- References: most editorial brand sites with a small surface area. +- Archetype affinities: any; this is the chrome default. + +### `multi-column-sitemap` + +Three to six columns of links plus brand info. Common on larger commerce sites where the footer carries category navigation, popular searches, account shortcuts, customer service, about-the-company, and resources. + +- When it fits: ecommerce catalog with deep category trees, multi-tenant marketplaces with seller-side and buyer-side links, B2B sites with documentation libraries. +- References: [amazon.com](https://amazon.com), [shopify.com](https://shopify.com), most large retailers. +- Archetype affinities: Technical Precise, Rugged Utilitarian (if functional), any commerce-heavy archetype. + +### `type-only-no-links` + +Minimal editorial footer, copyright and disclosure only, no nav. The footer is essentially a colophon. + +- When it fits: ideas-led brands, single-page narratives, publications where the nav lives in the top chrome and the bottom is just the credit line. +- References: [pitchfork.com](https://pitchfork.com) (varies; minimal footer), portfolio sites. +- Archetype affinities: Editorial Restrained, Luxe Considered. + +### `editorial-colophon-with-masthead` + +Masthead-style footer naming the editorial team or contributors. Fits publication register where the footer credits the people behind the work. + +- When it fits: publications, magazine sites, editorial collectives, organizations where the people are the brand. +- References: [theatlantic.com](https://theatlantic.com), [theverge.com](https://theverge.com). +- Archetype affinities: Editorial Restrained, Documentary Honest. + +### `newsletter-band-with-credits` + +Newsletter signup as the dominant footer element, with credits below. The newsletter is the conversion goal; the footer is the conversion surface. + +- When it fits: content sites, newsletter-first publications, brands where the newsletter is the customer-relationship channel. +- References: [substack.com](https://substack.com), most content sites operating newsletter-led growth. +- Archetype affinities: Editorial Restrained, Warm Conversational. + +### `dark-cta-then-credits` + +Two-row footer with a dark CTA band on top and a credits strip below. The CTA band acts as the page-bottom conversion surface; the credits strip is the actual footer. + +- When it fits: conversion-led sites where the bottom of the page is the second-most-attended surface (after the hero), marketing sites, B2B with a sign-up funnel. +- References: [vercel.com](https://vercel.com), [linear.app](https://linear.app). +- Archetype affinities: Technical Precise, any conversion-led register. + +--- + +## Optional extensions (not formally checked at this dispatch's scope) + +The framework can grow to cover additional section shapes as the portfolio surfaces them. Currently documented loosely; not part of the divergence check fields. + +- Trust-strip shapes: four-signal block, two-paragraph narrative band, logo wall, citation row. +- CTA-close shapes: dark band with single CTA, gradient band with pair of CTAs, image-backed close, newsletter close. +- How-it-works shapes: three-card strip, numbered list with images, flow diagram, timeline. + +When a brief's shape choice for one of these sections proves load-bearing for the build's distinctness, a future framework dispatch can promote the section to a checked field. + +--- + +## How to extend the vocabulary + +A build that discovers a section shape not present in the vocabulary: + +1. Documents the shape in the brief with a name (kebab-case), a one-paragraph description, and one or two real-world references. +2. Adds the shape to this file under the appropriate section (hero or footer) with the same format the existing shapes use. +3. Commits the vocabulary addition in the build PR. + +The vocabulary grows with the portfolio. Stale shapes (no demo uses them, no live references remain) can be retired in subsequent dispatches. diff --git a/skills/creative-brief-selector/references/reference-bank/README.md b/skills/creative-brief-selector/references/reference-bank/README.md new file mode 100644 index 0000000..dbaf928 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/README.md @@ -0,0 +1,114 @@ +# Reference bank + +The bank holds curated live reference sites for archetype-and-vertical combinations the portfolio has built against. Each file covers one combination, with positive references (sites that exemplify the position) and negative references (sites in the same vertical but in the WRONG register). + +The bank is the institutional memory of the portfolio. A new build for a combination that has been done before loads the existing file and adapts. A new build for a sparse combination supplies discovered references and commits them back to the bank as part of its build PR. + +--- + +## File naming convention + +`<archetype>-<vertical-specific-tag>.md` + +Examples: + +- `premium-dtc-maker-western-boots.md` +- `heritage-local-service-barbershop.md` +- `hospitality-experience-balloon-ride.md` + +The archetype prefix is the canonical name from `brand-archetype-system` (composed archetypes are hyphenated with the lead first). The vertical-specific tag is the narrowest description of the vertical the file covers (not the broad shape; the specific category within it). + +--- + +## File structure + +Each file has the same structure: + +```markdown +# <Archetype>, <Vertical> + +- Archetype: <Canonical archetype name, with composition note if any>. +- Vertical: <Broad shape> (specifically <narrow category>). +- Position summary: <One-line position the references collectively exemplify>. + +## Positive references + +- [<URL 1>] - <one-line why; what specifically this site does that a build in this position should inherit> +- [<URL 2>] - <one-line why> +- [<URL 3>] - <one-line why> +- [<URL 4>] - <one-line why, optional but encouraged> + +## Negative references + +- [<URL or named category>] - <one-line why this register is the wrong one for this position> + +## Extension note + +- <When was this file last updated and against which build> +``` + +--- + +## Adding references + +A build that uses this skill on a combination that has a file already: + +1. Loads three to four references from the existing file in step 3 of the process. +2. If the build discovered any new live references in addition (because the bank's references were stale or the build needed more breadth), append them to the positive references list in the same file with a one-line why. +3. Commit the file edit as part of the build PR. + +A build that uses this skill on a combination with no existing file: + +1. Creates a new file under `reference-bank/` named per the convention above. +2. Fills the file with three to six positive references discovered during the build's step 3. +3. Fills negative references with one to two categories or named sites that the build should not pull from. +4. Commits the file as part of the build PR. + +--- + +## Reference quality bar + +Each positive reference should be a real live site that: + +- Exemplifies the chosen position observably (palette, layout, voice, imagery, or all four). +- Is operating at a quality level the build can credibly aspire to. +- Has been live recently (within the past year if possible; older references are acceptable if they remain the canonical example). + +Each negative reference should be a real live site or a named category that: + +- Sits in the same vertical but in a different register. +- Helps the build understand what to NOT pull from. + +The one-line why for each reference is what makes the reference usable in step 4 of the process. A URL without a why is decoration; the why is what tells the next build what specifically to inherit or avoid. + +--- + +## When to retire a reference + +A reference should be removed from the bank when: + +- The URL stops showing what it was cited for (brand redesign, site shutdown, paywall changed the visible register). +- A more canonical example for the same position emerges. +- The build that originally cited the reference has been superseded and the new build uses different references. + +Retirement is a normal part of bank maintenance. The bank reflects what is currently usable, not what was once usable. + +--- + +## Seeded combinations + +Eleven combinations live in the bank: + +- [`premium-dtc-maker-western-boots.md`](premium-dtc-maker-western-boots.md) - Premium DTC maker register applied to a small-collection western-boot maker. +- [`heritage-local-service-barbershop.md`](heritage-local-service-barbershop.md) - Heritage local-service register applied to a neighborhood barbershop. +- [`hospitality-experience-balloon-ride.md`](hospitality-experience-balloon-ride.md) - Documentary-honest hospitality-experience register applied to a scenic-flight operator. +- [`editorial-restrained-documentary-honest-specialty-coffee-subscription.md`](editorial-restrained-documentary-honest-specialty-coffee-subscription.md) - Editorial-restrained subscription-app register applied to a single-origin specialty coffee subscription. +- [`rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md`](rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md) - Rugged-utilitarian inventory-listing register applied to a regional used-truck-and-SUV marketplace. +- [`editorial-restrained-literary-quarterly.md`](editorial-restrained-literary-quarterly.md) - Editorial-restrained editorial-publication register applied to a themed literary and ideas quarterly. +- [`luxe-considered-editorial-restrained-residential-architectural-brokerage.md`](luxe-considered-editorial-restrained-residential-architectural-brokerage.md) - Luxe-considered-editorial-restrained inventory-listing register applied to a residential brokerage of architecturally significant homes (the first same-shape divergence test against the rugged-utilitarian regional-used-vehicle-marketplace entry). +- [`bold-confident-editorial-restrained-aaa-game-studio.md`](bold-confident-editorial-restrained-aaa-game-studio.md) - Bold-confident-editorial-restrained corporate-portfolio register applied to a AAA-adjacent action game studio (the first portfolio entry in Bold Confident; the gentler entry into the bold register before a game-title demo). +- [`bold-confident-vibrant-saturated-single-ip-game-title.md`](bold-confident-vibrant-saturated-single-ip-game-title.md) - Bold-confident-vibrant-saturated single-IP marketing register applied to a post-launch AAA action game title (the first single-IP marketing entry; the title side of the game-studio pair, claiming the saturated leap the studio brief reserved). +- [`minimal-essentialist-documentary-honest-trades-directory.md`](minimal-essentialist-documentary-honest-trades-directory.md) - Minimal-essentialist-documentary-honest directory-marketplace register applied to a homeowner-facing local-trades directory (the first directory-marketplace shape and the first multi-provider entry; encodes the multi-provider conventions and the no-fabricated-reviews resolution). +- [`luxe-considered-curated-stays-directory.md`](luxe-considered-curated-stays-directory.md) - Pure-luxe-considered directory-marketplace register applied to an aspirational curated short-term-stays marketplace (the second directory-marketplace entry; the same-shape divergence partner to the trades directory, showing the shape across two opposite registers; reframes the multi-provider conventions for hosts and stays). + +Each seed file was built against a real shipped demo or shipped brief and reflects the references that build drew from. As the portfolio grows, the bank grows with it. diff --git a/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md b/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md new file mode 100644 index 0000000..3717ecd --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md @@ -0,0 +1,23 @@ +# Bold-confident-editorial-restrained, AAA-adjacent action game studio + +- Archetype: `bold-confident` with `editorial-restrained` as the composition secondary. The lead is the cinematic-confident register of AAA-adjacent action studios; the secondary is chrome restraint (the platform-versus-content distinction from the gaming and entertainment vertical file: a studio is the chrome around its games, so the chrome composes while the game key art carries the saturation). The composition is the explicit chrome-restraint dial: pure Bold Confident or composed-with-Vibrant-Saturated is reserved for single-game-title demos. +- Vertical: Corporate-portfolio (specifically AAA-adjacent action game studio: a content-creator studio that builds large-scale action games and presents itself as a serious craft-and-scale shop). +- Position summary: A studio whose chrome is composed and dark-mode-first, where each fictitious title's key art carries the saturation and energy. Cinematic full-bleed hero, titles portfolio strip, type-led studio band, careers band as the load-bearing conversion surface, dark CTA close. + +## Positive references + +- [bungie.net](https://bungie.net) - The canonical AAA-action studio chrome register: cinematic full-bleed key-art hero, dark-mode-first ground, restrained type chrome that lets the game art carry. Inherit the cinematic hero treatment, the dark ground, and the chrome restraint. +- [insomniac.com](https://insomniac.com) - Insomniac Games. The studio chrome at composed-cinematic; the titles portfolio surfaced with care. Inherit the titles-portfolio anatomy and the craft-proud-without-arrogance voice. +- [naughtydog.com](https://naughtydog.com) - Naughty Dog. The restrained-cinematic studio register; type-led studio band with the team presented at masthead density. Inherit the studio-band convention and the restrained-cinematic chrome. +- [remedygames.com](https://remedygames.com) - Remedy Entertainment. The composed-cinematic register at the studio level, with a smaller portfolio presented with editorial discipline. Inherit the title-detail-page-as-small-monograph anatomy. + +## Negative references + +- [steampowered.com](https://steampowered.com) - Steam. Platform chrome that hosts third-party content. Wrong vertical (platform, not studio); the platform chrome reads totally different from a studio's content-creator brand. +- [itch.io](https://itch.io) - Itch.io. Indie game platform; minimal chrome; wrong register and wrong vertical. +- Mobile and casual free-to-play studio sites (the bright-saturated multi-hue cartoon register of casual-mobile studio brands). Wrong register; a AAA-adjacent action studio is not casual-mobile. +- Streaming-service sites (netflix.com, hbomax.com). Adjacent Bold-Confident-leaning register but wrong vertical (streaming distribution vs studio creation). Netflix's content-as-hero treatment is a useful inheritance for the cinematic hero; the rest of Netflix's chrome is platform-distributor, not studio. + +## Extension note + +- Seeded from the Ironhold AAA-adjacent action studio brief (first portfolio entry in Bold Confident; first portfolio entry in the corporate-portfolio shape applied to a game studio). The brief is the gentler entry into Bold Confident in the showcase portfolio; the upcoming game-title demo is the leap into the saturated single-IP register. The studio composes with Editorial Restrained as the chrome-restraint dial so the title-demo can pull saturation further without colliding. The brief documents a Rule 4 WARN override on the full-bleed-image-with-overlay hero (the canonical AAA-studio cinematic treatment, four shipped matches but no archetype-family share so Rule 5 does not block; the override is justified by the new archetype carrying the shape into a completely different visual reading). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md b/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md new file mode 100644 index 0000000..a3e23c8 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md @@ -0,0 +1,24 @@ +# Bold-confident-vibrant-saturated, single-IP game-title marketing site + +- Archetype: `bold-confident` with `vibrant-saturated` as the composition secondary. The lead is the cinematic-confident register of AAA action titles; the secondary is the saturated leap (palette depth, type at title-card scale, key art as the load-bearing surface). This is the expressive content-brand end of the gaming and entertainment vertical, distinct from the studio-portfolio chrome that publishes the title. The pair to `bold-confident-editorial-restrained-aaa-game-studio`: the studio composes with Editorial Restrained chrome restraint, the single title composes with Vibrant Saturated to claim the saturation the studio reserved. +- Vertical: Single-IP marketing (specifically a post-launch AAA action game title: the marketing site where one shipped game lives, distinct from the studio portfolio that publishes it). The shape generalizes to any single published work (a single film, album, book, or show); the references here are the game-title instance. +- Position summary: A single published title's own brand, dark-mode-first, world-forward, where the world's own palette and the key art carry the saturation. Cinematic launch-poster hero, a trailer or curated key-art sequence, a world-immersion surface, a systems surface, a media gallery, and a follow-or-storefront conversion close. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (dark-mode-first, world-forward, saturated, cinematic) and pulls NO trade dress, layout, scroll behavior, font choice, or animation language from any specific real-game marketing site. Marketing-site mimicry is as off-limits as in-game resemblance. + +- [marathonthegame.com](https://marathonthegame.com) - The saturated single-IP marketing register at its most committed: a published title's own brand, dark-mode-first, with the title's palette and art carrying the saturation rather than the publisher's chrome. Inherit the world-forward saturated register; do NOT pull the flat-graphic identity or layout. +- [deathstranding.com](https://deathstranding.com) - Single-IP world-immersion marketing: the site immerses the visitor in one world (the setting, the lore) in the game's own voice rather than the studio's. Inherit the world-as-protagonist surface; do NOT pull the atmospheric scroll, type, or identity. +- [cyberpunk.net](https://cyberpunk.net) - Saturated single-IP launch register: type at title-card scale, palette depth carrying the world's own tones. Inherit the type-at-scale and palette-depth treatment; do NOT pull the neon-magenta identity. +- [eldenring.bandainamcoent.com](https://eldenring.bandainamcoent.com) - Single-IP lore-immersion marketing: a world page that treats the world as the protagonist with deep lore in the title's voice. Inherit the lore-immersion surface; do NOT pull the dark-fantasy identity. + +## Negative references + +- Studio and publisher portfolio sites ([bungie.net](https://bungie.net), [naughtydog.com](https://naughtydog.com), and the paired `bold-confident-editorial-restrained-aaa-game-studio` register) - The studio chrome composes and recedes to let many titles share a body of work. The single-IP title's register is the saturated content brand, distinct from the publisher's chrome; a single title is not a portfolio. +- Platform-chrome sites ([steampowered.com](https://steampowered.com), [store.epicgames.com](https://store.epicgames.com), [itch.io](https://itch.io)) - Platforms host third-party content and lean restrained to let the content carry. A single-IP marketing site is the content's own brand, not the platform that distributes it. +- Casual and mobile single-game marketing sites (the bright multi-hue cartoon register of casual-mobile single-game brands) - Wrong register; an AAA cinematic title is dark-mode-first and world-forward, not bright-cartoon. + +## Extension note + +- Seeded from the Mariner's Gauntlet single-IP marketing brief (first portfolio entry in the single-IP marketing shape; the title side of the Ironhold pair; the first portfolio entry composing with Vibrant Saturated). The title claims the saturated single-IP register that the paired studio brief (`bold-confident-editorial-restrained-aaa-game-studio`) deliberately reserved as forward-divergence headroom. The brief documents the framework's first Rule 5 BLOCK against a same-pair shipped demo: `full-bleed-image-with-overlay` is blocked (five shipped matches plus a shared Bold Confident family with the publisher Ironhold), so the title selects `centered-single-column` as a cinematic launch-poster hero, the intended divergence-within-the-pair. Footer is `newsletter-band-with-credits` (the follow-the-title conversion). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md new file mode 100644 index 0000000..6e98079 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md @@ -0,0 +1,22 @@ +# Editorial-restrained, documentary-honest, specialty coffee subscription + +- Archetype: `editorial-restrained` with `documentary-honest` as the composition secondary. The lead is editorial type-led restraint (low-saturation, generous whitespace, considered typography); the secondary is documentary farm and bean photography that grounds the single-origin claim. Premium but approachable; not luxury, not mass-market. +- Vertical: DTC food and beverage (specifically specialty coffee subscriptions; the references generalise to tea and other consumable single-origin subscriptions in adjacent registers). +- Position summary: A specialty single-origin coffee subscription in the editorial-restrained register. Subscriber-first commerce (cadence picker, pause and swap surfaced as features, not buried in account settings). Named farms, named processes, named roast dates. Documentary farm photography supports the type rather than leads. + +## Positive references + +- [drinktrade.com](https://drinktrade.com) - Subscriber-first commerce explicit: cadence picker on the home, match-quiz to find your roast, pause and swap surfaced as features rather than buried in account settings. Editorial-restrained type-led layout with documentary product photography. +- [counterculturecoffee.com](https://counterculturecoffee.com) - Specialty roaster with subscription surfaced; documentary photography of farms and farmers carries the page; editorial type. The canonical reference for "farm-direct specialty roaster with a subscription option." +- [onyxcoffeelab.com](https://onyxcoffeelab.com) - Editorial-restrained register at its most refined: type-led, considered photography, premium-but-approachable. Useful as the type-system reference (small-caps, restrained tracking, editorial serifs). +- [atlascoffeeclub.com](https://atlascoffeeclub.com) - Subscriber-first explicitly with a world-coffee-journey narrative. The closest match to the "one origin a month, named farm, named process" positioning. Useful for how to surface the rotation as the value prop. + +## Negative references + +- [starbucks.com](https://starbucks.com) - Mass-market grocery register; frappuccino lifestyle photography; promotional cadence dominates the homepage. The register a specialty roaster must not pull from. +- [folgers.com](https://folgers.com) - Commodity grocery brand; blue-can heritage but no specialty register. The bottom of the grocery shelf, conceptually. +- Generic lifestyle-influencer subscription boxes (BarkBox, FabFitFun, Allure Beauty Box and similar) - Lifestyle-spectacle subscription register where the unboxing is the product; the box itself is supposed to be a surprise. Wrong register entirely for a specialty-coffee subscription where the named farm and the roast date are the value, not the unboxing reveal. + +## Extension note + +- Seeded by the Northbound Coffee Co. brief (Phase 2 live pressure-test of the creative-brief-selector skill, rampstack/rampstackco-app PR #131). The brief was the first live invocation of the selector and discovered these references during step 3 because the bank had no seed for the specialty-coffee-subscription combination. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md new file mode 100644 index 0000000..a6c7c02 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/editorial-restrained-literary-quarterly.md @@ -0,0 +1,25 @@ +# Editorial-restrained, literary quarterly + +- Archetype: `editorial-restrained` (pure, no composition secondary). The lead is the literary quarterly tradition: typography carries the page, the considered editorial register, the restrained accent, and the absence of marketing inflation. +- Vertical: Editorial publication (specifically themed literary and ideas quarterly with multi-author masthead, each issue organized around a single question or theme). +- Position summary: A themed literary quarterly where each issue is a single question, the table of contents reads as variations on the question across disciplines, the design is restrained-considered with one literary accent colour. Not politically situated, not generationally branded, not topical, not single-author. The audience is literary readers across disciplines. + +## Positive references + +- [aeon.co](https://aeon.co) - Multidisciplinary ideas register. Considered design, restrained palette (warm-grey ground with deep type and a single accent), essays at substantial length, multiple disciplines per surface. Inherit the ideas-led register, the considered-but-not-luxe typography, the absence of marketing inflation. +- [thepointmag.com](https://thepointmag.com) - Themed multi-author essay structure at length. The closest peer on the audience axis (broadly literary readers across disciplines). Inherit the multi-author themed-issue treatment and the essay-length expectation. +- [cabinetmagazine.org](https://cabinetmagazine.org) - The closest structural anchor in the field: each issue is organized around a single thematic question rendered with editorial restraint. Inherit the single-theme-per-issue structure and the question-as-masthead treatment. +- [canopycanopycanopy.com](https://canopycanopycanopy.com) - Triple Canopy. Themed digital-first sequenced issues with editorial restraint. Inherit the digital-first design discipline and the sequenced-issue numbering. + +## Negative references + +- [thedriftmag.com](https://thedriftmag.com) - Politically situated, generationally branded, identity-forward. A considered quarterly must avoid the political-statement register on conversion architecture, palette, and voice. +- [nplusonemag.com](https://nplusonemag.com) - Institutional NY cultural authority register. A considered quarterly should not borrow the geographic or generational positioning. +- [laphamsquarterly.org](https://laphamsquarterly.org) - Historical-source-driven format (passages from historical writing assembled around a theme). A different format entirely; canonical to that publication and not transferable. +- [believermag.com](https://believermag.com) - McSweeney's-adjacent geometric illustration identity. A type-led quarterly should not borrow the illustration-led visual treatment. +- [atavist.com](https://atavist.com) - Single-essay-per-issue reportage register. A multi-essay themed quarterly is a different shape. +- [themarginalian.org](https://themarginalian.org) - Single-author blog register. A multi-author themed quarterly is a different shape. + +## Extension note + +- Seeded from the Caesura editorial-publication brief (the first portfolio entry in the editorial-publication shape, using the extended creative-brief-selector framework with hero_shape and footer_shape as first-class outputs). The pure `editorial-restrained` archetype combined with the type-led-prose hero and editorial-colophon-with-masthead footer renders as the natural literary-publication fit; the framework's extended rules align with the register's tradition rather than fighting it. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md b/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md new file mode 100644 index 0000000..ec9fae5 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/heritage-local-service-barbershop.md @@ -0,0 +1,20 @@ +# Heritage local service, barbershop + +- Archetype: `warm-conversational` with `retro-nostalgic` as the composition secondary. The lead is warm-everyday-craft (real-room atmosphere, social proof from genuine reviews, real-team page); the secondary is period-specific cues (walnut wood, brass fittings, marble counters, restrained palette). +- Vertical: Hospitality and local service (specifically neighborhood barbershops). +- Position summary: A heritage neighborhood shop with craft-and-space-led atmosphere, real-people-real-work proof, social proof drawn from review aggregates rather than fabricated testimonials. Initials over fabricated portraits when fictitious-brand demos cannot ethically render faces. + +## Positive references + +- [therosemontbarbers.com](https://therosemontbarbers.com) - Cuts gallery, interior atmosphere, social-proof badge, real team page in the heritage register. +- [speakeasybarberlounge.com](https://speakeasybarberlounge.com) - Atmosphere-led, period-specific cues (lounge fittings, warm interior), interior photography carries the page. +- [franksdenver.com](https://franksdenver.com) - Heritage register at a higher-end price point; restrained palette, considered editorial layout. +- [alfanisbarbershop.com](https://alfanisbarbershop.com) - Small-operator heritage, atmosphere-forward, real-team page. + +## Negative references + +- The chain barbershop register (Great Clips, Supercuts, Sport Clips and the like) - High-volume operational chains in the same vertical but in a fundamentally different register: utility-led, promotion-driven, no atmosphere. A heritage maker pulling from this register loses the position. + +## Extension note + +- Seeded from the Iron and Rye Barbershop atmosphere imagery pass. The seed positive references were used as register cross-checks during the build's still-life and interior shots. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md b/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md new file mode 100644 index 0000000..3b4fced --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/hospitality-experience-balloon-ride.md @@ -0,0 +1,20 @@ +# Hospitality experience, balloon ride + +- Archetype: `documentary-honest` with `luxe-considered` as the composition secondary. The lead is photography-led documentary realism (real landscape, real light, the morning as it actually looks); the secondary is aspirational-experience polish (named arc, named prices, named safety signals). +- Vertical: Hospitality experience (specifically scenic flight or ride experiences, with the balloon ride as the worked example). +- Position summary: A photography-led experience operator with the morning arc surfaced explicitly, named packages with named prices above the fold, four trust signals (FAA certification, lead pilot hours, weather posture, cancellation) surfaced as the booking-confidence layer. No fabricated identifiable faces; environmental imagery only. + +## Positive references + +- [napavalleyaloft.com](https://napavalleyaloft.com) - Regional operator, atmosphere-forward, dawn-palette imagery. +- [aerogelichotairballooning.com](https://aerogelichotairballooning.com) - Atmosphere-led, ride arc surfaced, photography drives the page. +- [rainbowryders.com](https://rainbowryders.com) - Multi-region operator, photography-led, named packages with prices. +- [sundanceballoons.com](https://sundanceballoons.com) - Multi-region operator, considered-warm register, ride-arc framing. + +## Negative references + +- Generic adventure-tour aggregators (Viator, GetYourGuide, and similar) - Stock photography pile, undifferentiated palette, transactional layout. A photography-led operator pulling from this register loses the atmosphere that justifies the price. + +## Extension note + +- Seeded from the Drift and Dawn imagery pass and the audited-field competitor set used during that build's Stage 1. The dawn-palette retune was driven by the gap between the original stone-and-amber default and the actual dawn light these references carry. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md b/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md new file mode 100644 index 0000000..52aff00 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/luxe-considered-curated-stays-directory.md @@ -0,0 +1,33 @@ +# Luxe-considered, curated short-term-stays directory-marketplace + +- Archetype: `luxe-considered` (pure; no composition secondary). The aspirational curated-stays register the hospitality vertical file names as Aman and Four Seasons: serif-led, understated authority, image-forward, the stay as a designed object. The escapist warmth is carried by a warm palette and a host-voice convention, not by a second archetype. Documentary Honest (the mass-market Airbnb register and a recurring portfolio secondary), Editorial Restrained (another build's exact luxe composition string), and Warm Conversational (the review-platform register) were each considered and rejected as secondaries; pure Luxe is the fit. +- Vertical: Directory-marketplace (specifically an aspirational curated short-term-rental marketplace of many independent hosts' standout stays). The second directory-marketplace entry in the bank; with the trades-directory entry it shows the shape across two opposite registers (functional-tool versus escapist-aspirational). +- Position summary: A small, curated marketplace a traveler dreams through, where the property photography carries the page and the stay is the product. Image-forward, escapist, design-forward; inventory grouped into curated collections; trust built on a stated verification claim rather than a fabricated-metric arms race. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (curated collections, image-forward discovery, the property-as-monograph, restrained booking affordances) and pulls NO palette, type, trade dress, photography style, or grid treatment from any specific real platform. + +- [plumguide.com](https://plumguide.com) - The curated-design short-term-stay register: a small vetted collection rather than the long tail, each stay presented with editorial care. Inherit the curated-collection posture and the property-as-monograph anatomy; do NOT pull the palette, type, or the specific listing-grid treatment. +- [boutique-homes.com](https://boutique-homes.com) - The design-led curated-stays register: architecturally distinctive properties grouped by design feeling. Inherit the design-forward collection grouping and the generous property gallery; do NOT pull the trade dress. +- [onefinestay.com](https://onefinestay.com) - The upper-curated hospitality register: a small set of standout homes with a hotel-grade presentation. Inherit the restrained-confident chrome and the aspirational photo direction; do NOT pull the palette or the brand identity. + +## Negative references + +- Functional-tool consumer directories (the trustworthy-direct-functional trades-directory neighbourhood; the same directory-marketplace shape in the opposite register). The functional tool a user controls is the deliberate opposite of the escapist marketplace a traveler dreams through; the shape and the multi-provider conventions are shared, the register is inverted. +- Single-operator hospitality-experience brands (one operator selling its own arc). The count axis differs: a curated-stays marketplace lists many independent hosts, not one operator's owned experience. +- Mass-market transactional rental platforms (the high-volume long-tail booking engines with urgency banners, opaque ranking, and dense result grids). Wrong register: a curated marketplace presents a small standout set as a publication, not the whole inventory as a funnel. + +## Multi-provider conventions (reframed for hosts and stays) + +The directory-marketplace shape's multi-provider conventions (first encoded by the trades-directory entry) carry forward, reframed from providers to hosts and stays: + +- Brand versus host voice. The marketplace brand's voice is the site voice throughout; each property carries a short host voice (a one-line note on why the place is worth the trip) only inside its card and detail, set with a typographic voice-shift. The brand never speaks as a host; hosts never speak as the brand. +- Discoverability is the spine, image-forward. The home is a search-and-browse surface where the property photography carries the page (the aspirational counterpart to the functional-categorical discovery of a trades directory). The hero is image-forward, not a functional tile grid. +- Listing density, organized as collections. Curated themed collections (coastal escapes, design landmarks, mountain retreats) rather than flat categories; roughly 4 to 6 collections with 4 to 8 properties each (24 to 40 properties). The collection is itself an editorial act. +- Comparison surface. Properties comparable within a collection on a small honest set (location, sleeps, stay-type, a demo-only rate band), with a within-collection compare view. +- Reviews-and-ratings honesty resolution. A demo-only Verified Host badge with its meaning stated plainly, plus an explicit "Demo: no reviews shown" placeholder slot and an aggregate-rating placeholder. The full trust UX is visible without fabricating a single review, rating, or superhost-style metric. Hosts are represented by their properties and a one-line voice, NOT by fabricated headshots; properties are set in fictitious locations; no real platform is named, even in negation. + +## Extension note + +- Seeded from the Lodestar curated-stays marketplace brief (the fifteenth and final showcase demo; the second directory-marketplace shape and the same-shape divergence partner to the trades-directory entry, running maximal-distance mode within the shape). Anchored to the hospitality and travel vertical file (`12-hospitality-travel.md`), which names pure Luxe Considered as the aspirational-hospitality register and Documentary Honest as the mass-market Airbnb register. The styled-aspirational property photography carries a real drift profile for the imagery pass: real-listing-platform aesthetic mimicry and fabricated-location-resemblance, both flagged for the build's NEGATIVE_GUARDRAILS, plus no real brand marks in any property image. The palette must read warm-aspirational (a design-hotel sandstone-clay-brass family) and must not reuse the trades-directory's cool functional family or any shipped warm-hospitality family. Last updated: 2026-05-29. diff --git a/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md b/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md new file mode 100644 index 0000000..aaf9c53 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md @@ -0,0 +1,23 @@ +# Luxe-considered-editorial-restrained, residential architectural brokerage + +- Archetype: `luxe-considered` with `editorial-restrained` as the composition secondary. The lead is the gallery-monograph register: premium, considered, type-and-photography-led, design-literate. The secondary is design-publication restraint: listings rendered as small monographs, the architect-and-year credit at byline weight, the brokerage represented as a practice rather than as a roster of agents. +- Vertical: Inventory-listing (specifically residential brokerage of architecturally significant homes: modernist, mid-century, architect-designed new builds, design-forward renovations). +- Position summary: A luxe residential brokerage that treats each architecturally significant home as a small monograph. The architect, the design year, the materials, the siting, and the light are first-class fields on every listing. The brokerage speaks as a design-literate practice rather than as a roster of individual agents. + +## Positive references + +- [themodernhouse.com](https://themodernhouse.com) - The canonical reference for the design-led residential brokerage register at editorial-restrained tier. Each listing reads as a small monograph; the architect is named in the listing card; the photography is disciplined. Inherit the listing-as-monograph anatomy and the considered-restraint voice. (Cited as a register anchor, not for trade dress copy; the negative-reference frame governs which brokerages a build must not pull trade dress from.) +- [phillips.com](https://phillips.com/design) - Phillips's design auction catalog register. The monograph treatment per lot (designer, year, materials, provenance) transfers cleanly to a residential listing. Inherit the per-lot monograph anatomy. +- [dezeen.com](https://dezeen.com) - The architectural press register. Listing-style architecture coverage with architect credits, year, materials, photography. Inherit the architecture-press literacy and the credit-line convention. +- [architecturaldigest.com](https://architecturaldigest.com) - The design-publication register with residential homes covered as design objects. Inherit the photography sensibility and the design-publication restraint. + +## Negative references + +- [zillow.com](https://zillow.com) - Mass-market portal; algorithmic listing presentation, estimated-value overlays, financing-first conversion. The register a luxe-considered brokerage must avoid on conversion architecture, palette, and voice. +- [realtor.com](https://realtor.com) - Same mass-market portal register; broker-listing-syndication shape, generic photography presentation. +- [redfin.com](https://redfin.com) - Mass-market portal with light brokerage layer; price-anxiety scoring, financing partnerships surfaced as primary CTAs. +- High-volume luxury brokerages whose primary surface is personality-led agent funnels. The architectural-monograph register is a practice, not a personal brand; the no-fabricated-agent-headshots line in the honesty contract is the structural rationale. + +## Extension note + +- Seeded from the Datum residential-brokerage brief (the first portfolio entry in luxe-residential-architectural-brokerage and the first same-shape divergence test in the portfolio; second inventory-listing build, the first being the rugged-utilitarian Treeline Motors marketplace). The brief documents the Section Shapes Rule 5 block on the two obvious luxe-architectural defaults (full-bleed-image-with-overlay and dual-column-image-and-text) and the resulting selection of asymmetric-large-image-small-text as the hero shape. Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md b/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md new file mode 100644 index 0000000..5083d66 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md @@ -0,0 +1,34 @@ +# Minimal-essentialist-documentary-honest, local-trades directory + +- Archetype: `minimal-essentialist` with `documentary-honest` as the composition secondary. The lead is the functional-tool register (clean, organized, content-forward, reduced chrome; the page is the directory and the chrome recedes to let the listings carry). The secondary is honest-transparency trust (a stated verification claim, honest placeholders where reviews would render, real-context provider photography). The marketplace platform-versus-provider principle is the structural rationale: the directory brand must not compete with the provider identities, so restraint wins. +- Vertical: Directory-marketplace (specifically a homeowner-facing local-trades directory of many independent providers across real trade categories: plumbing, electrical, HVAC, carpentry, painting, roofing). The first multi-provider entry in the bank. +- Position summary: A clean, trustworthy directory tool the homeowner controls, light-mode-first, where the categories and the providers are the page. Discoverability is the spine, comparison is core, and the trust is built on honest transparency rather than on warmth or on clinical authority. + +## Positive references + +The references are cited NOMINATIVELY as register exemplars only. A build in this position inherits the register (search-first discovery, category browse, provider listings, a comparison surface, a verification claim) and pulls NO palette, trade dress, logo language, or conversion-funnel pattern from any specific real directory. + +- [angi.com](https://angi.com) - The modern consolidated home-services directory register: category-and-location search, provider listings, the lead-handoff conversion. Inherit the search-first discovery spine and the category structure; do NOT pull the orange-and-green palette, the match-now funnel, or any trade dress. +- [thumbtack.com](https://thumbtack.com) - The matched-services register: structured by trade and location, provider profiles with comparable fields. Inherit the comparable-provider-profile anatomy; do NOT pull the blue palette or the get-matched interstitial funnel. +- [houzz.com](https://houzz.com) - The visual-services-directory register: real work photography carrying the provider listings. Inherit the documentary work-in-context photography direction (a trade in progress, a finished job), not glamour shots; do NOT pull the green-and-orange palette or the social-feed product framing. + +## Negative references + +- Warm-conversational single-provider service brands (a neighbourhood barbershop, a single local shop's site; the heritage-local-service register). Wrong register and wrong count: that is a single provider speaking warmly about itself, not a directory of many providers in a functional-trust tool. A trades directory must not read as one warm shop with extras. +- Magazine-editorial services-content sites (a home-improvement publication, a services-advice editorial). Wrong register: a directory is a functional tool, not a magazine pretending to be a directory; the editorial-publication register buries the listing density behind a narrative. +- Bold-cinematic or saturated AAA visual registers (a cinematic full-bleed experiential hero). Wrong register entirely: a directory reads functional, not experiential; an image-and-overlay cinema-poster hero is the opposite of the page-is-the-directory discovery spine. + +## Multi-provider conventions (new ground; inherited by future directory-marketplace briefs) + +The directory-marketplace shape is the first multi-provider register in the portfolio. These conventions are first-class and carry forward: + +- Brand versus provider voice. The directory brand's voice is the site voice throughout; each provider has its own short voice only inside its listing card (a one-line how-we-work statement). The directory speaks as the trustworthy tool; the providers speak as themselves inside their cards. (Single-provider builds never had to navigate this distinction.) +- Discoverability is the spine. The home page is a search-and-browse surface (category-and-location search, category tiles, provider cards), not a hero-and-essay narrative. A `grid-of-elements` hero fits naturally; a type-led or image-and-overlay hero does not. +- Listing density. A meaningful directory reads as real only at sufficient density: roughly 4 to 6 categories with 4 to 8 providers each (16 to 48 total). Fewer reads as a single-provider demo with extras; more risks bloat. +- Comparison surface. Providers within a category are comparable on a small honest set of dimensions (service area, specialties, years in business), not on an opaque ranking score. Comparison is core to the pattern. +- Reviews and ratings are the canonical fabrication risk, and the resolution is honest UX without fabricated content. A directory conventionally shows aggregate ratings, review counts, and written reviews; a demo cannot fabricate any of them. The resolution: an explicit "Demo: no reviews shown" placeholder slot where review content and an aggregate rating would render, plus a demo-only "Verified Pro" badge (the directory's own badge, meaning stated, not a real accreditation) where earned. The directory's full trust UX is visible without a single fabricated review, rating, license number, or certification. +- Real categories, fictitious providers. The trade categories are real; the providers within them are demo-fictitious, with names vetted against recognizable businesses (a proprietor-surname-plus-trade format), set in a fictitious city, with schematic service-area maps and no fabricated license numbers, certifications, or accreditation marks. + +## Extension note + +- Seeded from the Tradepost local-trades directory brief (the first directory-marketplace shape and the first multi-provider demo in the portfolio; the seventh selector-led build). The brand-archetype-system has no dedicated home-services, local-services, or trades vertical file; this build used `16-marketplace.md` (the two-sided-platform register) as the closest anchor, and the gap is flagged for a future skill-extension dispatch to add a dedicated local-services-and-trades vertical file. Tradepost runs maximal-distance mode; it is the same-shape divergence partner to a forthcoming vacation rental marketplace (the Browse-AI attended capstone), and the two diverge naturally because the verticals differ. The palette deliberately avoids the recognizable real-brand directory colours (Angi orange-and-green, Thumbtack blue, HomeAdvisor orange, Yelp red, Houzz green-and-orange, Yellow Pages yellow-and-black). Last updated: 2026-05-28. diff --git a/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md b/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md new file mode 100644 index 0000000..8a7d341 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/premium-dtc-maker-western-boots.md @@ -0,0 +1,22 @@ +# Premium DTC maker, western boots + +- Archetype: `luxe-considered` with `rugged-utilitarian` as the composition secondary. The lead is premium-considered (editorial layout, prices visible, restrained merchandising); the secondary is workwear-and-craft (heritage materials, hand-welt construction, made-to-last positioning). +- Vertical: DTC fashion (specifically western boots). +- Position summary: A premium small-collection western-boot maker, leather-forward, product-photographed, prices visible, no discount cadence, no SKU-strip-above-the-fold. Confident, not promotional. + +## Positive references + +- [tecovas.com](https://tecovas.com) - The elevated-DTC reference: product-forward hero, named prices visible, restrained merchandising. No discount banners above the fold. +- [lucchese.com](https://lucchese.com) - Heritage register; serif-led, craft narrative as a supporting band rather than the lead. +- [oldgringoboots.com](https://oldgringoboots.com) - Smaller-maker, leather-forward photography, restrained editorial set instead of catalog density. +- [ranchroadboots.com](https://ranchroadboots.com) - Small-operator boutique competing in the same position; useful for cross-checking how a peer maker handles wayfinding on a small collection. + +## Negative references + +- [durangoboots.com](https://durangoboots.com) - Catalog-dense big-box texture; discount cadence, SKU-strip-above-the-fold, sale-badge pile. Not the register a premium small maker should pull from. +- [justinboots.com](https://justinboots.com) - Same big-box texture in a different brand; promotional banners and grid density dominate. +- [bootbarn.com](https://bootbarn.com) - Multi-brand retailer rather than a maker; merchandising-led rather than craft-led. + +## Extension note + +- Seeded from the Pinto Mesa Boots store-spine brief (the worked example of the brief template). Last updated: 2026-05-27. diff --git a/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md b/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md new file mode 100644 index 0000000..b260e05 --- /dev/null +++ b/skills/creative-brief-selector/references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md @@ -0,0 +1,24 @@ +# Rugged-utilitarian-documentary-honest, regional used-vehicle marketplace + +- Archetype: `rugged-utilitarian` with `documentary-honest` as the composition secondary. The lead is workwear-and-craft (Mountain West heritage utility register); the secondary is data-forward documentary (transparency-first listings, real photography, real source attribution). +- Vertical: Inventory-listing (specifically regional used-truck-and-SUV marketplace serving working-vehicle buyers, not full passenger-car market). +- Position summary: A regional working-vehicle specialist marketplace, transparency-first on every listing, documentary photography of vehicles in working context, plain-direct voice that speaks with familiarity of the terrain its audience drives. Specialist, not generalist; transparent, not promotional; regional, not national. + +## Positive references + +- [bringatrailer.com](https://bringatrailer.com) - The canonical listing-detail transparency reference: full ownership history, mileage timeline, photograph density (forty to one hundred photographs per lot is typical), a comments thread that adds provenance. Inherit the listing-detail anatomy and the source-attributed transparency posture. Diverge from the auction format; a fixed-price marketplace borrows the transparency without the closing-clock. +- [icon4x4.com](https://icon4x4.com) - Editorial documentary register applied to working vehicles. Inherit the photography direction (vehicles photographed in landscape and at work, not glamour shots on a studio seamless), the considered editorial type, and the absence of promotional banners. +- [filson.com](https://filson.com) - Mountain West heritage workwear register. Inherit the palette tendency (granite, evergreen, oxblood, aspen gold; cool ground with restrained accents), the documentary photography that supports the type rather than fighting it, and the plain-direct voice. +- [patagonia.com](https://patagonia.com) - The adjacent outdoor-utility register, useful as the second positive on voice (plain-direct, no marketing inflation, the audience treated as competent). + +## Negative references + +- [cargurus.com](https://cargurus.com) - Mass-market national passenger-car register; price-anxiety scoring as the hero, financing-first conversion architecture. The register a specialist regional marketplace must avoid on conversion architecture, palette, and voice. +- [cars.com](https://cars.com) - Same mass-market national register; promotional banner cadence, broad-inventory generalist posture. +- [carvana.com](https://carvana.com) - DTC mass-market with vending-machine theatrics, financing-first. The register to avoid on theatrics and on conversion-flow priority. +- [autotempest.com](https://autotempest.com) - Meta-aggregator with no editorial voice; utility-only search-across-the-others. A specialist marketplace must not read as utility-only. +- [edmunds.com](https://edmunds.com) - Research-led advisory; content-heavy editorial sitting adjacent to a marketplace. A specialist marketplace must not read as a magazine pretending to be a marketplace. + +## Extension note + +- Seeded from the Treeline Motors inventory-listing brief (the second batch-two build using the creative-brief-selector skill end to end). The Bring a Trailer reference is dual-positioned: positive on listing-detail transparency, negative on format (auction vs fixed-price marketplace). Last updated: 2026-05-27. diff --git a/skills/creative-brief/SKILL.md b/skills/creative-brief/SKILL.md new file mode 100644 index 0000000..8e18b1c --- /dev/null +++ b/skills/creative-brief/SKILL.md @@ -0,0 +1,158 @@ +--- +name: creative-brief +description: "Create or refine a creative brief that bridges discovery and execution. Use this skill whenever the user is starting a new project, kicking off a website, beginning a brand build or redesign, briefing a designer or developer or AI agent, or trying to align a team before building. Triggers on creative brief, design brief, brand brief, project kickoff, kicking off, briefing the team, project intake, design direction, brief the designer, brief the dev, where do we start, how do we start, write a brief, project overview, scope this project, align on direction. Also triggers when the user has a vague idea and needs to make it concrete enough to hand off, even if they do not say 'brief' explicitly." +category: strategy-and-discovery +catalog_summary: "Project briefs that align stakeholders before work starts" +display_order: 2 +--- + +# Creative Brief + +Bridges discovery and execution. Translates "we want a website" into a brief a designer, developer, or AI agent can actually run with. + +--- + +## When to use + +- Starting a new project (website, app, brand, campaign) +- Kicking off a redesign or rebrand +- Handing work to a designer, developer, or AI agent +- Aligning a team that has drifted off course +- Turning a vague idea into something buildable + +## When NOT to use + +- The user is asking a one-off design question (use `design-standards`) +- The user wants a PRD or dev ticket (use `pm-spec-writing`) +- The user is doing initial research and has not decided what they are building (use `brand-discovery` first) +- The user just wants you to write copy (use `content-and-copy`) +- The user already has scope and constraints settled and needs deeper aesthetic direction specifically (use `creative-direction` for the structured aesthetic axes) + +--- + +## Required inputs + +A brief needs answers to ten questions. Before writing, confirm you have answers (or can elicit them) for: + +1. What is the project? +2. Why does it exist? What problem does it solve? +3. Who is the audience? +4. What do you want them to do, feel, or know? +5. What is the personality? How does it sound? +6. What is the visual direction? How does it look? +7. What is in scope? What is out? +8. What are the constraints (time, budget, technical, brand)? +9. What does success look like? +10. Who approves? + +If you have fewer than five of these, run a quick intake first. See "Eliciting missing info" below. + +--- + +## The framework: brief structure + +Output a markdown brief with these ten sections. Keep each section tight. A good brief is two pages, not ten. + +### 1. Snapshot +One paragraph answering: what, who, why, when. The kind of thing you would say at a kickoff in thirty seconds. + +### 2. Audience +Primary audience first. Include who they are, what they are trying to do, what is blocking them today, and where you reach them. Add secondary audiences only if they materially change the work. + +### 3. Objectives +What success looks like. Pair every objective with a measurable signal. + +> Objective: drive trial signups. +> Signal: 3 percent conversion from homepage to signup within 30 days of launch. + +### 4. Key message +The one thing you want a visitor to walk away knowing. If they see only the homepage hero and bounce, what should they remember? One sentence. + +### 5. Voice and tone +Pick three to five adjectives. Pair each with what you are NOT (e.g. "confident, not arrogant"). See [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) for frameworks and worked examples. + +### 6. Visual direction +Mood, palette, type, and imagery direction. Three to five reference URLs are worth more than 500 words. Note what you like AND what you would reject. + +### 7. Scope and deliverables +A bulleted list of what is being made. Be specific. "Homepage" is not a deliverable. "Homepage with hero, three feature blocks, testimonial carousel, and contact CTA" is. + +### 8. Constraints +Time. Budget. Technical (existing stack, required integrations, hosting). Brand (logo, colors, fonts that must be used). Legal (compliance, accessibility level required). + +### 9. Inspiration and competitors +Three to five sites or brands you want to feel like, three to five you want to feel different from. Note WHY for each. + +### 10. Approval +Who signs off. What artifact triggers sign-off (a Figma file, a staging URL, a PDF). What happens if there is no sign-off by a deadline. + +--- + +## Eliciting missing info + +If the user comes with a partial answer (e.g., "I want a website for my coffee shop"), do not just write a generic brief. Ask. Use these prompts. + +For audience +- Who is the single most likely person to land on this site? Walk me through their day. +- If you could pick one type of customer to fill your inbox, who? +- Who do you NOT want to attract? + +For objectives +- Pretend it is six months after launch. What number tells you it worked? +- What is the one action you most want a visitor to take? + +For voice +- Pick three brands or people whose tone you would want to borrow. +- If your site were a person at a dinner party, what would they sound like? + +For visuals +- Show me three sites you love. What do you love about them? +- Show me one site you hate. Why? + +For scope +- If you only got one page, which one? +- What would you cut if the budget were halved? + +Do not ask all of these. Pick the ones that fill the actual gaps. + +--- + +## Workflow + +1. Read the conversation. Pull every fact already given. Do not ask questions you can answer from context. +2. Identify gaps. Which of the ten required inputs are missing or thin? +3. Run intake. Ask three to five targeted questions to fill the gaps. Group related questions to keep the conversation tight. +4. Draft the brief. Use [`references/creative-brief-template.md`](references/creative-brief-template.md) as the structure. Keep it under 1500 words. +5. Stress-test. Before delivering, check the brief against the failure patterns below. If any apply, revise before showing the user. +6. Deliver. Save as `creative-brief.md` in the project root. Offer to make it a Word doc or PDF if the user wants something to share with stakeholders. +7. Hand off for aesthetic depth (optional). For projects where sections 5 (voice and tone) and 6 (visual direction) need more rigor than this brief surfaces, run `creative-direction` next. It produces a structured aesthetic brief using four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) that content, copy, and art-direction skills consume directly. + +--- + +## Failure patterns + +When the user's input matches one of these patterns, push back before writing. + +- "We want to be the [giant brand] of [our niche]." Ask what specifically about that brand they want to borrow. Probably one or two things, not the whole thing. +- Audience as "men and women 18-65." This is not an audience. Ask for the single most valuable customer type and start there. +- "Increase awareness" with no metric. Awareness of what, by whom, measured how? Push for a number. +- "Modern, clean, minimalist." These words are meaningless. Ask for three specific URLs they think look right. +- Twenty pages of context, no clear ask. Ask: "If a designer reads only one paragraph, what should it be?" Then make that the snapshot. + +--- + +## Output format + +Default output is a markdown file at `creative-brief.md` in the project root. Structure follows the template exactly. + +If the project is large, split: keep the main brief under 1500 words and put detail in linked appendices (`audience-research.md`, `brand-guidelines.md`, etc.). Briefs that try to be everything end up read by no one. + +--- + +## Reference files + +- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Fillable template. Copy and use as the starting point. +- [`references/voice-and-tone-guide.md`](references/voice-and-tone-guide.md) - Voice frameworks, brand archetypes, and worked patterns. +- [`references/example-brief.md`](references/example-brief.md) - A worked example for a fictional B2B SaaS, showing what a "good" filled brief looks like. + +Read the template before drafting. Read the voice guide if the user has not already specified a voice. Read the example if you are unsure how filled-out a section should be. diff --git a/skills/creative-brief/references/creative-brief-template.md b/skills/creative-brief/references/creative-brief-template.md new file mode 100644 index 0000000..7d57fc3 --- /dev/null +++ b/skills/creative-brief/references/creative-brief-template.md @@ -0,0 +1,185 @@ +# Creative Brief: [Project Name] + +Date: [YYYY-MM-DD] +Author: [Who wrote this brief] +Stakeholders: [Who needs to sign off] +Status: Draft / In review / Approved + +--- + +## 1. Snapshot + +[One paragraph. What is this project, who is it for, why does it exist, and when does it need to be done? Aim for 3 to 5 sentences.] + +Quick facts +- Project type: [Website / app / brand / campaign / other] +- Launch target: [Date or quarter] +- Budget tier: [Range or "to be confirmed"] +- Stack constraints: [Required tech or "open"] + +--- + +## 2. Audience + +Primary audience + +Who: [One specific persona, not a demographic range] + +What they are trying to do: [The job they are hiring this product to do] + +What is blocking them today: [The friction they are experiencing now] + +Where you reach them: [Channels: search, social, referral, paid, etc.] + +Secondary audience (only if it changes the work) + +[Same structure, briefer.] + +Anti-personas + +- [Type of customer you do NOT want to attract, and why] + +--- + +## 3. Objectives + +\| Objective \| Measurable signal \| Timeframe \| +\|---\|---\|---\| +\| [What you want to achieve] \| [How you know it worked, with a number] \| [When you measure] \| +\| \| \| \| +\| \| \| \| + +--- + +## 4. Key message + +[One sentence. If a visitor saw only the hero and bounced, what should they remember?] + +--- + +## 5. Voice and tone + +We sound: [3 to 5 adjectives] + +We do not sound: [The mirror image of each adjective] + +\| We are \| We are NOT \| +\|---\|---\| +\| [Adjective] \| [What it could tip into if overdone] \| +\| \| \| +\| \| \| + +Examples of our voice in the wild + +- [Brand or writer 1, and what specifically about them] +- [Brand or writer 2, and what specifically about them] + +--- + +## 6. Visual direction + +Mood: [3 to 5 words] + +Palette direction: [Light/dark, warm/cool, saturated/muted, plus any required brand colors] + +Type direction: [Serif/sans, display vs body, formal vs casual] + +Imagery direction: [Photography style, illustration style, iconography] + +Reference sites we want to feel like + +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] +- [URL]: [What specifically about it] + +Reference sites we want to feel different from + +- [URL]: [What we are rejecting] +- [URL]: [What we are rejecting] + +--- + +## 7. Scope and deliverables + +In scope + +- [Specific deliverable 1, with detail] +- [Specific deliverable 2, with detail] +- [Specific deliverable 3, with detail] + +Out of scope + +- [Things explicitly not being built in this project] + +--- + +## 8. Constraints + +Timeline + +- [Milestone 1]: [Date] +- [Milestone 2]: [Date] +- [Launch]: [Date] + +Budget + +- [Range or specific number, plus what it covers] + +Technical + +- Existing stack: [What is already in place] +- Required integrations: [Analytics, CRM, payment, etc.] +- Hosting: [If specified] + +Brand + +- Required: [Logo, colors, fonts, marks that must be used] +- Available: [Brand assets the team can pull from] + +Legal and compliance + +- Accessibility level: [WCAG AA / AA+ / AAA] +- Privacy: [GDPR / CCPA / other] +- Industry: [Any sector-specific requirements] + +--- + +## 9. Inspiration and competitors + +Inspiration (the feel we want) + +\| Site / brand \| What we love \| +\|---\|---\| +\| [URL] \| [Specific element] \| +\| [URL] \| [Specific element] \| +\| [URL] \| [Specific element] \| + +Competitors (in our category) + +\| Site / brand \| How we differ \| +\|---\|---\| +\| [URL] \| [Where we want to position differently] \| +\| [URL] \| [Where we want to position differently] \| + +--- + +## 10. Approval + +Sign-off owner: [Name, role] + +Sign-off artifact: [What needs to be approved: brief, comps, staging URL, etc.] + +Sign-off deadline: [Date] + +If no sign-off by deadline: [Default action: ship anyway, escalate, pause, etc.] + +--- + +## Appendix (optional) + +Link out to anything that would otherwise bloat the brief. + +- [Audience research] [link] +- [Competitive analysis] [link] +- [Brand guidelines] [link] +- [Technical requirements] [link] diff --git a/skills/creative-brief/references/example-brief.md b/skills/creative-brief/references/example-brief.md new file mode 100644 index 0000000..cef9a7f --- /dev/null +++ b/skills/creative-brief/references/example-brief.md @@ -0,0 +1,206 @@ +# Creative Brief: Plumb + +Date: 2026-04-15 +Author: Maria Chen, Founder +Stakeholders: Maria Chen (sign-off), Devon Park (engineering), Sasha Williams (design lead) +Status: Approved + +--- + +## 1. Snapshot + +Plumb is infrastructure observability built for small DevOps teams. We are launching a marketing site and product trial flow to support our public beta in Q3 2026. The site needs to convert technical buyers from a homepage visit to a trial signup, and clearly position us as the "right-sized" option against the heavy enterprise incumbents. Target launch: July 15, 2026. + +Quick facts +- Project type: Marketing website + trial signup flow +- Launch target: July 15, 2026 +- Budget tier: $25K design + dev, plus internal team time +- Stack constraints: Next.js + Vercel, with Supabase for the trial flow + +--- + +## 2. Audience + +Primary audience + +Who: A staff or principal engineer at a 20 to 200 person startup, currently the unofficial owner of the team's monitoring stack. They got handed Datadog two years ago, the bill is now embarrassing, and they want a defensible alternative they can sell internally. + +What they are trying to do: Cut the monitoring bill by at least 40 percent without taking on a tool that requires a dedicated SRE to operate. + +What is blocking them today: Datadog is too expensive and too sprawling. Grafana is technically free but burns engineering time on maintenance. Both feel built for someone three sizes bigger. + +Where you reach them: Hacker News, the changelog blog, lobste.rs, technical Twitter, dev-focused podcasts (Changelog, Software Engineering Daily), and search ("alternative to datadog", "self-hosted monitoring small team"). + +Secondary audience + +Engineering managers and CTOs at the same companies, who sign the invoice. They land later in the journey but need the pricing page and the ROI math to be airtight. + +Anti-personas + +- Enterprise procurement teams. We do not want to attract Fortune 500 inbound. The product is not built for that scale and we do not want to spend cycles on RFPs. +- Hobbyists who want a free forever tier. We have a generous trial but no free tier. Bargain hunters churn. + +--- + +## 3. Objectives + +\| Objective \| Measurable signal \| Timeframe \| +\|---\|---\|---\| +\| Drive trial signups from organic and content channels \| 200 trial signups per month within 90 days of launch \| By Oct 15, 2026 \| +\| Convert trials to paid \| 12 percent trial-to-paid conversion \| By end of Q4 2026 \| +\| Establish technical credibility \| 50+ inbound mentions on HN, lobste.rs, or dev Twitter referencing the site or docs \| By end of Q3 2026 \| +\| Reduce sales cycle for inbound \| Pricing page transparent enough that 80 percent of inbound deals close without a sales call \| Ongoing \| + +--- + +## 4. Key message + +Plumb is observability that fits a 50-person engineering team, priced for a 50-person engineering team. + +--- + +## 5. Voice and tone + +We sound: Direct, technical, confident, dry-witted, practical. + +We do not sound: Cute, hand-wavy, salesy, corporate, or condescending. + +\| We are \| We are NOT \| +\|---\|---\| +\| Direct \| Blunt or rude \| +\| Technical \| Inaccessible to a non-expert reader \| +\| Confident \| Boastful \| +\| Dry-witted \| Trying to be funny \| +\| Practical \| Boring \| + +Examples of our voice in the wild + +- Stripe docs, for the rhythm and the way they assume reader competence without showing off. +- Tailscale's blog, for the dry technical wit and willingness to admit tradeoffs. +- 37signals' product copy, for short sentences that earn their place. + +--- + +## 6. Visual direction + +Mood: Calm, confident, technical, slightly opinionated. A senior engineer's notebook, not a stadium. + +Palette direction: Predominantly light with strong dark-mode parity. Single accent color (deep teal). Charts and diagrams in muted, accessible color ramps. No gradients, no glow effects. + +Type direction: Geometric sans for display (Inter or similar), monospace for code and metrics (JetBrains Mono or similar). Generous line height. Comfortable for long-form reading. + +Imagery direction: Real screenshots of the product, annotated. Architecture diagrams drawn in a consistent simple style. No stock photos. No abstract 3D illustrations. No people in headsets pointing at laptops. + +Reference sites we want to feel like + +- linear.app: For the calm density and how every pixel feels intentional. +- planetscale.com: For technical credibility without enterprise stuffiness. +- fly.io: For the dry voice and the unapologetic technical depth on the homepage. + +Reference sites we want to feel different from + +- datadoghq.com: Too dense, too many product lines, screams "we will sell you everything." +- newrelic.com: Too corporate, too gradient-heavy, feels like 2018. + +--- + +## 7. Scope and deliverables + +In scope + +- Homepage with hero, three feature blocks, social proof, pricing teaser, footer CTA +- Pricing page with transparent tiers, calculator, and FAQ +- Product page with annotated screenshots and one short demo video +- About page (founder story, team, hiring CTA) +- Trial signup flow (3 steps: email + workspace name + first project setup) +- Docs index page that links into the existing docs site (separate property) +- Blog index and post template (engineering writing, changelog posts) +- 404 and other error pages + +Out of scope + +- Customer logos page (we do not have permissioned logos yet) +- Comparison pages (Datadog vs Plumb, etc.) - saved for Q4 once we have data +- Localization (English only at launch) +- Marketing automation integrations beyond a single newsletter capture + +--- + +## 8. Constraints + +Timeline + +- Brief approved: April 15, 2026 +- Wireframes: April 30 +- High-fi design: May 20 +- Dev complete: June 30 +- QA and content load: July 1 to July 12 +- Launch: July 15 + +Budget + +- $25K total: $15K design, $10K dev contractor for trial flow integration. Internal team handles content, brand assets, deploy. + +Technical + +- Next.js App Router on Vercel +- Trial flow writes to Supabase (existing project) +- Plausible for analytics (no Google Analytics) +- All pages must score 95+ on Lighthouse performance and accessibility +- Mobile baseline: 375px + +Brand + +- Logo: existing wordmark + glyph (provided) +- Colors: deep teal (#0F4C5C), slate gray scale, white. Single accent only. +- Type: Inter for display, JetBrains Mono for code + +Legal and compliance + +- Accessibility: WCAG 2.1 AA +- Privacy: GDPR compliant. EU users get a banner. Data residency in US-East. +- No customer testimonials with full names without written consent + +--- + +## 9. Inspiration and competitors + +Inspiration + +\| Site / brand \| What we love \| +\|---\|---\| +\| linear.app \| Density without clutter; type system; restraint \| +\| planetscale.com \| How they explain technical concepts in the hero \| +\| fly.io \| Voice, blog rhythm, code samples on the homepage \| +\| stripe.com/docs \| The annotated examples pattern (we want to borrow this for the product page) \| + +Competitors + +\| Site / brand \| How we differ \| +\|---\|---\| +\| datadoghq.com \| We are smaller, opinionated, and priced for teams under 200 \| +\| newrelic.com \| We avoid enterprise sprawl. Single product, clear pricing \| +\| grafana.com \| We are managed and easier to operate. We charge for the time savings \| + +--- + +## 10. Approval + +Sign-off owner: Maria Chen + +Sign-off artifacts: +- Wireframes: review by April 30, async approval in Figma +- High-fi design: review by May 20, in-person review meeting + 48-hour async window +- Pre-launch site (staging URL): review by July 10, all stakeholders sign off in writing + +Sign-off deadline: Each stage above has a 48-hour async window after the review meeting. After 48 hours of no objection, the stage is approved and we proceed. + +If no sign-off by deadline: Default to ship. Maria has final say on any post-launch revision. + +--- + +## Appendix + +- [Audience research notes](./audience-research.md) +- [Competitive teardown](./competitive-analysis.md) +- [Brand guidelines](./brand-guidelines.md) diff --git a/skills/creative-brief/references/voice-and-tone-guide.md b/skills/creative-brief/references/voice-and-tone-guide.md new file mode 100644 index 0000000..a8fb49d --- /dev/null +++ b/skills/creative-brief/references/voice-and-tone-guide.md @@ -0,0 +1,200 @@ +# Voice and Tone Guide + +Voice is who you are. Tone is how you sound right now. Voice stays constant. Tone shifts with context (a 404 page sounds different from an onboarding email, even if the voice is the same). + +This guide gives you frameworks for picking a voice and adapting tone, plus worked examples. + +--- + +## Framework 1: Four dimensions (Nielsen Norman) + +Pick a position on each axis. Together they describe the voice. + +\| Dimension \| One end \| Other end \| +\|---\|---\|---\| +\| Formality \| Formal \| Casual \| +\| Seriousness \| Serious \| Funny \| +\| Respectfulness \| Respectful \| Irreverent \| +\| Enthusiasm \| Matter-of-fact \| Enthusiastic \| + +A bank: formal, serious, respectful, matter-of-fact. +A craft soda brand: casual, funny, irreverent, enthusiastic. +A premium watch brand: formal, serious, respectful, matter-of-fact. +A coding bootcamp: casual, serious, respectful, enthusiastic. + +If you cannot pick a position on each axis, the voice is not defined yet. + +--- + +## Framework 2: Brand archetypes + +Twelve archetypes from Jung-derived brand theory. Pick one primary and one secondary. + +\| Archetype \| Promise \| Voice notes \| Example brands \| +\|---\|---\|---\|---\| +\| Innocent \| Safety, simplicity \| Warm, plain, reassuring \| Dove, Coca-Cola \| +\| Sage \| Truth, wisdom \| Authoritative, considered, measured \| Google, BBC, The Economist \| +\| Explorer \| Freedom, discovery \| Adventurous, restless, vivid \| Patagonia, Jeep, Subaru \| +\| Outlaw \| Disruption \| Rebellious, blunt, anti-establishment \| Harley-Davidson, Liquid Death \| +\| Magician \| Transformation \| Visionary, mysterious, evocative \| Apple, Tesla \| +\| Hero \| Mastery, courage \| Bold, confident, action-driving \| Nike, FedEx \| +\| Lover \| Intimacy, beauty \| Sensual, warm, indulgent \| Chanel, Godiva \| +\| Jester \| Joy, fun \| Playful, irreverent, witty \| Old Spice, Mailchimp, Slack \| +\| Everyman \| Belonging \| Friendly, plain, relatable \| IKEA, Target \| +\| Caregiver \| Service, compassion \| Nurturing, warm, supportive \| Johnson & Johnson, Volvo \| +\| Ruler \| Control, prestige \| Commanding, polished, exclusive \| Rolex, Mercedes \| +\| Creator \| Self-expression \| Imaginative, articulate, craft-focused \| Lego, Adobe \| + +Two archetypes give you range. A primary "Sage" with secondary "Hero" is authoritative AND action-driving. A primary "Caregiver" with secondary "Sage" is supportive AND wise. + +--- + +## Framework 3: We are X, not Y + +The fastest voice exercise. Pick three to five adjectives. For each, name what it could tip into if overdone. + +> Confident, not arrogant. +> Direct, not blunt. +> Warm, not saccharine. +> Witty, not sarcastic. +> Smart, not condescending. + +The "not" half is what saves you. "Confident" alone leads writers to swagger. "Confident, not arrogant" tells them where the line is. + +--- + +## Tone shifts by context + +Voice stays. Tone shifts. Map the high-frequency moments and decide how each one sounds. + +\| Moment \| Tone shift \| +\|---\|---\| +\| Onboarding \| Warmer, more enthusiastic \| +\| Error message \| Calmer, more matter-of-fact \| +\| Success state \| Brief celebration, quickly redirect to next action \| +\| Empty state \| Helpful, slightly playful, suggests action \| +\| 404 / not found \| Self-aware, light, points the way home \| +\| Account deletion \| Quiet, respectful, no jokes \| +\| Pricing page \| Direct, clear, confidence-inspiring \| +\| Legal copy \| Plain language version of the legal copy, sitting next to the legal copy \| + +--- + +## Practical patterns + +Voice shows up in concrete choices. These are the dials. + +Sentence length + +- Short sentences = punchy, confident. (Apple, Stripe, Liquid Death.) +- Medium sentences = considered, professional. (Most B2B SaaS.) +- Long sentences = literary, premium, slow. (The New Yorker, premium watch brands.) + +Vocabulary + +- Plain (most words 1-2 syllables) = approachable, mass-market. +- Domain-specific = signals expertise to insiders, alienates outsiders. +- Coined or invented = builds a worldview but high risk if not earned (Apple's "Retina", Slack's "huddle"). + +Pronouns + +- "We" = the company speaking. +- "You" = the customer being addressed. +- "I" = a person speaking, not a company. Strong on personal brands and creator products. Weird on enterprise. + +Contractions + +- Use them = casual. +- Avoid them = formal. + +Punctuation + +- Em dashes = literary, breath-taking pauses. +- Semicolons = considered, formal, slightly old-school. +- Periods only = punchy, confident. +- Exclamation points = exuberant; lose credibility past one or two. +- Em dashes are popular but polarizing. Many writers and brands ban them outright; some lean on them. Pick a side. + +Rhythm + +Read your copy out loud. If you stumble, the rhythm is off. Vary sentence length. A page of all-short sentences feels staccato. A page of all-long sentences feels lecture-y. + +--- + +## Worked example: B2B SaaS + +Voice + +> Direct, not blunt. +> Confident, not cocky. +> Practical, not boring. +> Smart, not academic. + +Archetype + +Primary: Sage. Secondary: Hero. + +Patterns + +- Sentence length: short to medium. Lead with the headline, deliver the proof, exit. +- Vocabulary: plain, with domain terms when precision earns its keep. +- Pronouns: "we" for the company, "you" for the reader. Avoid "users." +- Contractions: yes. +- Em dashes: no. + +Tone shifts + +- Onboarding: warmer. Lean into "you can do this." +- Error: matter-of-fact. State what happened, what to do, no apology theater. +- Pricing: direct. List the number, list what's included, stop. + +Sample + +Bad (vague, hedged, overwrought): +> Our innovative platform leverages cutting-edge technology to revolutionize how teams collaborate on data-driven workflows. + +Good (direct, plain, confident): +> Move data between tools without writing code. Connect your stack in minutes. Built for teams that have outgrown spreadsheets. + +--- + +## Worked example: D2C food brand + +Voice + +> Playful, not goofy. +> Honest, not blunt. +> Crave-worthy, not gluttonous. +> Curious, not academic. + +Archetype + +Primary: Jester. Secondary: Everyman. + +Patterns + +- Sentence length: short. Hit the joke, get out. +- Vocabulary: plain. Sensory words land. +- Pronouns: "we" and "you," very conversational. +- Contractions: always. +- Punctuation: light. Periods do the work. + +Sample + +Bad (corporate, distant): +> We are committed to providing high-quality artisanal granola made with the finest organic ingredients sourced from trusted partners. + +Good (playful, sensory, confident): +> Crunchy. Honey-roasted. Made with oats from one farm in Wisconsin. We tried adding more stuff. It got worse. So we stopped. + +--- + +## When voice is locked + +A voice is locked when you can: + +1. State it in one sentence ("We sound like a senior engineer explaining something to a junior, with patience.") +2. Cite three brands or writers it borrows from, and what specifically. +3. Show a piece of copy and a critic could say "that does/does not sound like us" without arguing. + +If you cannot do all three, keep working on the voice. diff --git a/skills/creative-direction/SKILL.md b/skills/creative-direction/SKILL.md new file mode 100644 index 0000000..0545b60 --- /dev/null +++ b/skills/creative-direction/SKILL.md @@ -0,0 +1,153 @@ +--- +name: creative-direction +description: "Walk the user through four directional axes (tone register, aesthetic philosophy, audience relationship, sensory ambition) and produce a structured aesthetic brief that downstream content, copy, design, and art-direction skills consume as required input. The aesthetic depth layer, distinct from `creative-brief` (operational kickoff: scope, audience, deliverables, constraints). Use when a project needs aesthetic coherence across many small decisions and the user has only a vague feeling, or when multiple downstream aesthetic-producing skills need a shared brief. Triggers on creative direction, aesthetic direction, set the aesthetic, define the visual direction, what's the vibe, what's the tone, the four axes. Does NOT fire for a general kickoff brief (use `creative-brief`), tactical single-piece work, already-documented direction, purely functional output, or locked production-stage work." +category: strategy-and-discovery +catalog_summary: "Four-axis aesthetic brief (tone, aesthetic, audience, sensory ambition) for cross-skill coherence" +display_order: 3 +--- + +# Creative Direction + +Frameworks produce competent output. Coherent output requires a brief. + +This skill turns vague creative intent into a structured brief that downstream skills can reference. It does not generate taste. It captures direction, so the dozens of small decisions a project requires (word choice, image selection, white space, sequencing, what to leave out) all answer to the same question. + +--- + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## When to use + +- The start of a multi-touchpoint project (website, brand, campaign, product launch) where aesthetic coherence matters +- Before running multiple downstream skills that need to share a unified voice and look +- When inheriting a project that has competent execution but feels generic or incoherent +- Recalibrating an existing project that has drifted aesthetically over time +- When the user is a non-curator who knows what feeling they want but cannot articulate the decisions that produce it + +## When NOT to use + +- Use `creative-brief` instead when the user needs a general kickoff brief covering scope, audience, deliverables, and constraints. This skill goes deeper on aesthetic axes specifically, not on the operational layer. +- Use `art-direction` instead when briefing a specific creative deliverable (photo shoot, illustration set, video, campaign). This skill produces project-wide aesthetic direction; `art-direction` extends that direction into specific creative work. +- Tactical single-piece work (one tweet, one error message, one button label) +- Projects where the user has complete aesthetic direction documented already (skip to downstream skills) +- Purely functional output (data tables, form labels, system status text) +- Production-stage execution where direction is already locked +- When the goal is to develop taste; this skill codifies intent, it does not develop judgment + +--- + +## Required inputs + +- Project name and one-paragraph description +- Target audience (rough is fine; full audience profiles come from `brand-discovery`) +- Business goal (what changes if this project works) +- Optional but high-value: 2 to 4 reference URLs (sites, brands, or pieces) the user admires, with a sentence on what specifically resonates +- Optional: existing brand assets if the project is a refresh, not greenfield +- Constraints worth declaring (parent brand voice, regulatory tone requirements, accessibility floors) + +--- + +## The framework: 4 directional axes + +A creative brief sits at the intersection of four axes. Each axis is a spectrum, not a binary. The user picks a position on each, knowing that the choice excludes adjacent positions for this project. + +### 1. Tone Register + +How formal is the work? How much heat does the language carry? + +Positions: + +- Professional. Measured, precise, low-register. Trusts the reader to do work. Restraint is the signal. +- Conversational. Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking. +- Playful. Wit, surprise, willingness to break form for effect. Risks the reader missing the point if not earned. +- Provocative. Pointed, opinionated, willing to take a position other brands will not. Risks alienating people who do not share the position. + +How to choose: What does the audience already get too much of, and what too little? If the category is dry, conversational or playful is differentiation. If the category is loud, professional restraint is differentiation. + +### 2. Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +Positions: + +- Editorial Restrained. Generous white space, single definitive image instead of grids, considered typography, low color count. Signals confidence and patience. +- Polished Standard. Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions. Signals competence and professionalism. +- Controlled Maximalist. High visual density where every element is intentional. Loud but engineered. Signals craft and conviction. +- Expressive Maximalist. Visual abundance, willingness to be loud, willing to clash. Signals energy and ambition. Hardest to execute well. + +How to choose: What is the project saying about the brand's relationship to attention? Restrained earns attention by deserving it. Maximalist captures attention by not letting it leave. + +### 3. Audience Relationship + +How does the brand position itself relative to the reader? + +Positions: + +- Authority. We tell you what is true. Implicit hierarchy, expertise on display, reader is the learner. +- Peer. We are figuring this out together. Equal footing, shared vocabulary, reader is the co-thinker. +- Companion. We walk with you. Lower hierarchy than authority, more presence than peer, reader is the protagonist of their own work. +- Coach. We challenge you. The brand pushes the reader toward something they would not push themselves toward alone, reader is the trainee. + +How to choose: What does the audience need most? Audiences who feel lost want authority or coach. Audiences who feel patronized want peer or companion. The wrong choice patronizes or abandons the reader. + +### 4. Sensory Ambition + +How much is the work asking of the reader emotionally? + +Positions: + +- Functional. Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity. Most utility tools live here. +- Considered. Reader notices the craft. Aesthetic choices are visible without being the point. Most premium brands live here. +- Resonant. Reader feels something specific the brand architected. Aesthetics carry meaning. Hardest to produce. Most editorial and narrative brands aspire here. + +How to choose: What does the audience deserve from this experience? Functional respects time. Resonant respects feeling. The wrong choice either wastes attention or fails to deliver utility. + +--- + +## Workflow + +1. Gather inputs. Project name, description, audience, goal, references. +2. Walk through each axis as a question. One axis at a time. For each, present the positions, surface tradeoffs, and capture the user's selection plus reasoning. +3. Capture inspiration references. For each provided reference URL, ask what specifically resonates. The answer often clarifies which axis position fits better than abstract description does. +4. Surface tensions. Some combinations are difficult to execute well. Functional + Provocative is rare since provocation usually requires emotional engagement that pure functional work resists. Authority + Functional often slides into preachy without warming up at least slightly. Flag tensions and ask the user to confirm or reconsider. +5. Synthesize. Write a one-paragraph synthesis describing what this combination produces in practice. +6. Output the brief. Markdown format using the structure in [`references/brief-template.md`](references/brief-template.md). The brief becomes a project artifact (typically saved as `BRIEF.md` at the project root). +7. Hand off. Reference the brief in any downstream skill that produces aesthetic output. Required reading before `landing-page-copy`, `art-direction`, `content-and-copy`, `brand-style-guide`, or any other skill where coherence matters. + +--- + +## Failure patterns + +- Using this to develop taste. This skill codifies intent. It does not produce judgment. A user with no taste who runs this still produces incoherent work; the brief just makes the incoherence consistent. +- Skipping inspiration references. The references calibrate what the axis positions mean in practice. A user picking "Editorial Restrained" without examples often means something different than what an art director means by it. +- Treating positions as absolute. A project at "Conversational" still has moments of authority and play. Position is the gravitational center, not a fence. +- Brief drift mid-project. The most common failure. The brief gets written, then ignored. Discipline: every downstream skill checks the brief before producing output. If a skill wants to violate the brief, the violation is a decision the user makes consciously, not an accident. +- Picking incompatible combinations without flagging. Functional + Provocative is technically valid but very hard. The skill should surface that the combination is rare and ask the user to confirm. +- Producing a brief no one references. A brief that does not change downstream output is decoration. The test of a good brief is whether the output would be different if a different brief were used. + +--- + +## Output format + +Default output is a markdown brief, typically saved as `BRIEF.md` at the project root. + +Structure: + +1. Project header. Name, one-paragraph description, target audience, business goal. +2. The four axis selections. Each axis with the position selected and a one-sentence rationale. +3. Synthesis paragraph. What this combination produces in practice. Written in present tense, not aspirational ("This brief produces work that..." not "This brief will help us..."). +4. Inspiration references. The provided URLs with notes on what specifically each one demonstrates. +5. Rejection list. What this brief explicitly says no to. Often the most useful section. Examples: "No testimonial walls. No stock photography. No exclamation marks." +6. Open questions. Anything still unresolved that downstream skills will need to know. + +The brief is reference material for the project's life, not a one-time deliverable. Update it when the project's direction genuinely changes. Resist the urge to update it when execution is hard; usually that means execute harder, not loosen the brief. + +--- + +## Reference files + +- [`references/axes-explained.md`](references/axes-explained.md) - The four axes in depth, with positions, signals, and short brand examples per position to calibrate the user's eye. +- [`references/brief-template.md`](references/brief-template.md) - Blank template for the brief output. +- [`references/example-aesthetic-brief.md`](references/example-aesthetic-brief.md) - A fully completed brief from a representative project, showing how the abstract axes translate into concrete creative direction. diff --git a/skills/creative-direction/references/axes-explained.md b/skills/creative-direction/references/axes-explained.md new file mode 100644 index 0000000..b49c833 --- /dev/null +++ b/skills/creative-direction/references/axes-explained.md @@ -0,0 +1,235 @@ +# The Four Axes Explained + +Each axis is a spectrum. Pick a position knowing it excludes adjacent positions for this project. Reference brands are illustrative, not prescriptive. + +> Worked examples for each axis position can be assembled from any reference brand library that documents tone, aesthetic, audience relationship, and sensory ambition consistently. The framework below describes the four axes; the user's own reference set positions each example along the axes during the brief workflow. + +--- + +## Axis 1: Tone Register + +How formal is the language? How much heat does it carry? + +### Professional + +Measured, precise, low-register. Trusts the reader to do the work of meaning. Restraint is the signal. + +What this signals: Seriousness, expertise, established status. The brand does not need to perform to be taken seriously. + +Reference examples: Stripe's documentation. The Economist. McKinsey's published thinking. Bloomberg's editorial style. + +When to pick this: The audience is making high-stakes decisions and needs to feel they are dealing with peers, not pitchpeople. Or, the category is loud and your differentiation is calm. + +Common failure: Sliding into stiffness. Professional is not robotic. It is restrained and warm, not cold. + +### Conversational + +Warmer, more personal, comfortable with first-person and contractions. Reads like a thoughtful person talking, not an institution speaking. + +What this signals: Approachability without sacrificing competence. A brand that respects the reader as a person, not a target. + +Reference examples: Linear's product copy. Vercel's marketing voice. Notion's onboarding. MailChimp's voice in their early years. + +When to pick this: Default for most modern B2B and prosumer brands. The audience appreciates human voice but still needs to trust the brand's competence. + +Common failure: Sliding into casual. Conversational is still considered. "Hey friend!" is not conversational, it is performed informality. + +### Playful + +Wit, surprise, willingness to break form for effect. Visible craft in the language itself. + +What this signals: Confidence, creative ambition, willingness to risk being misread. The brand is having fun and inviting the reader to as well. + +Reference examples: Slack's early voice. Old Spice campaigns. Bumble. Mailchimp at its peak. + +When to pick this: The audience expects beige and wants color. The category is mature and differentiation through craft is available. The brand has the cultural permission to be funny without it reading as forced. + +Common failure: Forcing humor that does not earn its place. Playful only works when it is actually funny. Otherwise it reads as desperate. + +### Provocative + +Pointed, opinionated, willing to take a position other brands will not. Says what others soften. + +What this signals: Conviction. The brand stands for something specific and is willing to lose the audience that disagrees in order to bond more deeply with the audience that agrees. + +Reference examples: Patagonia's political voice. Liquid Death's entire premise. Oatly's category-baiting copy. The early Apple "Think Different" era. + +When to pick this: Strong opinion exists and hiding it is more expensive than expressing it. The brand can defend the position over the long term, not just at launch. + +Common failure: Performing provocation without conviction. Audiences detect this in seconds. Either the position is real or the voice fails. + +--- + +## Axis 2: Aesthetic Philosophy + +How much visual density does the work carry? How much does each element earn its place? + +### Editorial Restrained + +Generous white space, single definitive image instead of grids, considered typography, low color count, deliberate slowness. + +What this signals: Confidence and patience. The brand is willing to under-fill space because it trusts the reader to fill it with attention. + +Reference examples: Aesop's website. Apple's product pages in their classic era. Jacquemus. Phaidon's editorial work. Most luxury fashion houses. + +When to pick this: The audience is fatigued by visual noise. The brand is premium or aspirational. The product or work itself benefits from being viewed slowly. + +Common failure: Restraint that reads as absence. Restraint earns its place when every remaining element is exquisite. Strip too much and the page reads as unfinished. + +### Polished Standard + +Modern SaaS aesthetic. Clean grids, balanced contrast, expected proportions, conventional component patterns. + +What this signals: Competence, professionalism, current. The brand belongs in its category without standing out. + +Reference examples: Most modern B2B SaaS sites. Stripe's marketing pages. Linear. Notion's marketing. Vercel. + +When to pick this: The audience expects the category's visual conventions and the brand's differentiation is in the product, not the wrapper. Default for most B2B work. + +Common failure: Producing work indistinguishable from competitors. Polished Standard is safe. Safe is forgettable. + +### Controlled Maximalist + +High visual density where every element is intentional. Loud, but engineered. The page is full because each thing earns its place. + +What this signals: Craft and conviction. The brand has thought about every pixel and chose density on purpose. + +Reference examples: BUCK's portfolio site. Ueno's work. Pentagram's case study pages. Many top-tier creative agency sites. Some Nike campaign work. + +When to pick this: The audience expects boring and the brand wants to demonstrate creative ambition. Differentiation through visible craft is available. The team has the design capacity to execute it. + +Common failure: Density without intent. Controlled Maximalist requires every element to defend its existence. Lazy density reads as cluttered, not crafted. + +### Expressive Maximalist + +Visual abundance, willingness to be loud, willing to clash. Energy over restraint. + +What this signals: Energy, ambition, irreverence. The brand is having a moment and the work is the moment. + +Reference examples: Adult Swim. Cards Against Humanity. Some Heinz creative work. Liquid Death's loudest moments. Music festival branding. + +When to pick this: The audience is energetic and seeks brands that match. Cultural permission for loudness is high in the category. The brand can sustain the energy over time. + +Common failure: This is the hardest position to execute well. Expressive Maximalism that lacks craft reads as chaotic, not exciting. Most attempts fail. + +--- + +## Axis 3: Audience Relationship + +How does the brand position itself relative to the reader? + +### Authority + +We tell you what is true. Expertise on display. Hierarchy implicit and accepted. + +What this signals: Earned expertise. The reader came here to learn from someone who knows more than they do. + +Reference examples: Bloomberg. McKinsey's published frameworks. Bain's reports. The Economist. Some of Apple's product copy. + +When to pick this: The audience explicitly came for expertise. The brand has the credibility to back the position. The category rewards authoritative voice. + +Common failure: Authority without earned credibility reads as arrogance. The brand needs to actually know more than the reader. + +### Peer + +We are figuring this out together. Equal footing, shared vocabulary. + +What this signals: Mutual respect. The reader is treated as a co-thinker, not a learner. + +Reference examples: Linear. Most developer-focused brands. GitHub. Some of Notion's voice. Most modern B2B SaaS. + +When to pick this: The audience is sophisticated and reacts badly to being talked down to. The work is genuinely collaborative and acknowledging the reader's expertise serves the relationship. + +Common failure: False peering. If the brand actually does know more, hiding that to seem peer-like reads as condescending. + +### Companion + +We walk with you. Lower hierarchy than authority, more presence than peer. + +What this signals: Sustained accompaniment. The brand is here for the long arc, not just the transaction. + +Reference examples: Headspace. Calm. Stitch Fix. Some healthcare brands. Anthropic's voice in some moments. + +When to pick this: The audience is going through something difficult, ongoing, or uncertain. They need presence more than expertise. The relationship is about being with them, not directing them. + +Common failure: Companion without substance reads as performative warmth. The brand needs to actually do something useful to earn the relationship. + +### Coach + +We challenge you. The brand pushes the reader toward something they would not push themselves toward alone. + +What this signals: Productive friction. The brand assumes the reader wants growth and is willing to be pushed. + +Reference examples: Strava. Whoop. Crossfit's brand voice. Apple Fitness+. Some founder-focused programs. + +When to pick this: The audience explicitly wants to be challenged. The brand has the credibility to push without being dismissed. The product or service requires effort that the brand is asking of the reader. + +Common failure: Coaching without permission. The brand needs to be invited into that role. Pushing readers who did not ask to be pushed reads as preachy. + +--- + +## Axis 4: Sensory Ambition + +How much is the work asking of the reader emotionally? + +### Functional + +Get a job done. Reader gets in, gets the answer, gets out. Aesthetics serve clarity, not feeling. + +What this signals: Respect for time. The brand assumes the reader has somewhere else to be. + +Reference examples: Wikipedia. Craigslist. Most documentation sites. Government services that work well. IRS forms when they are well-designed. + +When to pick this: The reader is in transactional mode. The work's value is utility, not feeling. Asking for emotional engagement would be presumptuous. + +Common failure: Confusing functional with bare. Functional work is still well-designed. It is just designed for clarity over resonance. + +### Considered + +Reader notices the craft. Aesthetic choices are visible without being the point. + +What this signals: Attention to detail without flexing it. The brand cares, and the reader can tell. + +Reference examples: Apple's product pages. Notion's marketing. Linear's interface. Aesop's product photography. Most premium SaaS. + +When to pick this: The audience appreciates craft when they encounter it but does not require an emotional payoff. The work needs to feel premium without demanding emotion. + +Common failure: Considered work that drifts toward decorative. If the craft is visible without earning its place, it reads as fussy. + +### Resonant + +Reader feels something specific the brand architected. Aesthetics carry meaning. The work is asking the reader to feel. + +What this signals: Ambition. The brand is trying to do more than communicate. It is trying to move. + +Reference examples: Hermes. Patagonia at their narrative best. Some Apple campaigns ("Think Different," "Shot on iPhone"). Aesop's editorial work. Most editorial publications. + +When to pick this: The audience came for feeling, not utility. The brand has the craft to deliver it. The work is significant enough to warrant the emotional ask. + +Common failure: This is the hardest position. Resonance that is forced reads as manipulation. Resonance that is mistargeted reads as melodrama. Resonance that is vague reads as pretentious. Most attempts fail. + +--- + +## Combinations to flag + +Some combinations are common, some are rare-but-doable, some are contradictory. + +Common combinations: + +- Conversational / Polished Standard / Peer / Considered = the modern B2B SaaS default +- Professional / Editorial Restrained / Authority / Considered = premium consultancy default +- Conversational / Polished Standard / Companion / Considered = wellness or healthcare default + +Rare but powerful: + +- Provocative / Editorial Restrained / Coach / Resonant = the "Patagonia at full conviction" register +- Conversational / Controlled Maximalist / Peer / Resonant = the "top creative agency" register +- Provocative / Controlled Maximalist / Coach / Resonant = the "high-stakes brand revival" register + +Difficult combinations to flag: + +- Functional + Provocative = rare. Provocation usually requires emotional engagement that pure functional work resists. +- Editorial Restrained + Expressive Maximalist = unreachable by selection. These are both positions on Axis 2 (Aesthetic Philosophy), so the user picks one or the other, not both. +- Authority + Functional = possible but flat. Often slides into "we are right and you should know that," which is hard to hold without warming up at least slightly. + +When the user picks a difficult combination, surface the difficulty. Ask them to confirm or reconsider. Sometimes the difficulty is the point. diff --git a/skills/creative-direction/references/brief-template.md b/skills/creative-direction/references/brief-template.md new file mode 100644 index 0000000..ffdd108 --- /dev/null +++ b/skills/creative-direction/references/brief-template.md @@ -0,0 +1,74 @@ +# Brief Template + +Save this as `BRIEF.md` at the project root. Update when direction genuinely changes; otherwise hold the line. + +--- + +# [Project Name] Brief + +## Project + +Name: [Project name] + +Description: [One paragraph describing what the project is, what it produces, who it serves.] + +Target audience: [Rough description. A full audience profile from `brand-discovery` is a separate document.] + +Business goal: [What changes if this project works. The actual outcome that defines success.] + +--- + +## The four axes + +### Tone Register: [Position] + +[One sentence rationale for why this position fits this audience and goal.] + +### Aesthetic Philosophy: [Position] + +[One sentence rationale.] + +### Audience Relationship: [Position] + +[One sentence rationale.] + +### Sensory Ambition: [Position] + +[One sentence rationale.] + +--- + +## Synthesis + +[One to two paragraphs describing what this combination produces in practice. Written in present tense. "This brief produces work that..." not "This brief will help us...". Concrete enough that downstream skills can check their output against it.] + +--- + +## Inspiration references + +[For each reference URL or brand the user provided, document what specifically resonates and which axis it informs.] + +- [Reference 1] - [What this demonstrates and which axis it calibrates.] +- [Reference 2] - [What this demonstrates and which axis it calibrates.] +- [Reference 3] - [What this demonstrates and which axis it calibrates.] + +--- + +## Rejection list + +This brief explicitly says no to: + +- [Specific decision the brief rejects, e.g. "No testimonial walls."] +- [Another specific decision, e.g. "No stock photography of people."] +- [Another, e.g. "No exclamation marks in body copy."] + +The rejection list is often the most useful section. The choices a brief excludes are as important as the choices it commits to. + +--- + +## Open questions + +[Anything still unresolved that downstream skills will need to know. Better to surface uncertainty than to leave it implicit.] + +- [Question 1] +- [Question 2] diff --git a/skills/creative-direction/references/example-aesthetic-brief.md b/skills/creative-direction/references/example-aesthetic-brief.md new file mode 100644 index 0000000..6e52131 --- /dev/null +++ b/skills/creative-direction/references/example-aesthetic-brief.md @@ -0,0 +1,83 @@ +# Example Aesthetic Brief + +A representative completed brief, modeled on a realistic project. Showing how the abstract axes translate into concrete creative direction. + +> The brief below is a worked example for "Conversational + Editorial Restrained + Peer + Considered" applied to a developer-tool marketing site. Compare it against any rendered marketing site that hits these axis positions to see how the abstract axes translate into concrete decisions: copy register, typographic restraint, image treatment, page density, and rejection list. + +--- + +# Observatory Marketing Site Brief + +## Project + +Name: Observatory marketing site redesign + +Description: Rebuild the marketing site for an open-source observability tool aimed at senior infrastructure engineers. The current site reads like every other developer SaaS site (gradient hero, "trusted by" logo wall, three-column feature grid, code snippet, testimonials, signup CTA). The new site needs to feel like the team behind it actually understands the problem space, not like a marketing team built a site about a tool they have not used. + +Target audience: Senior platform engineers, infrastructure leads, and SRE managers at companies with 50 to 500 engineers. They evaluate observability tools for their team. They are skeptical of marketing claims and value technical depth. They will read documentation before they evaluate the product. + +Business goal: Increase qualified evaluation requests from engineering decision-makers, where "qualified" means the requester has authority to influence vendor selection and is in active evaluation. Volume of low-intent signups is not the goal. Quality and intent are. + +--- + +## The four axes + +### Tone Register: Conversational + +The audience is fatigued by both stiff vendor copy ("enterprise-grade reliability") and aggressive performance copy ("10x your observability"). Conversational treats the reader as a peer engineer who can read between the lines. + +### Aesthetic Philosophy: Editorial Restrained + +The category is visually loud. Dashboards, gradient heroes, neon accents, animated charts. The differentiation is opposite: low color count, generous white space, considered typography, single definitive image instead of dashboard screenshots above the fold. The site reads like documentation that decided to be a marketing site, not the other way around. + +### Audience Relationship: Peer + +These engineers do not need to be educated on observability. They need to be respected as practitioners. Authority voice would be condescending. Companion voice would be saccharine. Peer voice acknowledges that we and they are figuring out the same hard problems. + +### Sensory Ambition: Considered + +Functional would underdeliver; the audience expects a marketing site to be more than a feature list. Resonant is too much; this is not a brand campaign, it is a tool evaluation. Considered means the craft is visible (typography, restraint, the right photograph in the right place) without the site asking for an emotional response. + +--- + +## Synthesis + +This brief produces a marketing site that reads like a thoughtful engineering blog post the team happened to design well. Body copy is in first-person plural, contractions are fine, and technical terms appear without quotation marks (the audience uses them naturally, the site should too). Visual density is intentionally low, with a single hero image instead of a product screenshot grid, and pages that breathe rather than fill. There is no logo wall above the fold. There are no testimonials styled as ad copy. The product makes its case through clear documentation links, an honest comparison page, and a "how this differs from what you are already using" section that is willing to say what the tool is not for. + +The site refuses several conventions of the category. No animated dashboard hero. No "trusted by" logos as the second module. No three-column feature grid with checkmarks. No popup. No newsletter modal. The site assumes the reader will find the product if it is genuinely useful, and that the marketing's job is to be clear, not to be loud. + +--- + +## Inspiration references + +- Linear's marketing site (linear.app) - Demonstrates Conversational + Polished Standard + Peer well. The Observatory site borrows the calm density and the willingness to write in first person, but pushes further toward Editorial Restrained on the aesthetic axis. +- Vercel's marketing pages - Useful for how they handle technical depth without overwhelming. The product surfaces in code, not in dashboard mockups. +- Stripe's documentation - The reference for how documentation can be a marketing asset. Observatory's marketing site borrows the sense that good docs are a brand decision, not just a product decision. +- The Economist's editorial design - Aesthetic reference for restraint, considered typography, and the use of a single editorial photograph as a hero treatment instead of a dashboard screenshot. + +--- + +## Rejection list + +This brief explicitly says no to: + +- No "trusted by" logo wall, especially above the fold +- No gradient hero. Solid color or a single restrained photograph instead +- No three-column feature grid with checkmark icons +- No product dashboard mockup as the hero image +- No animated chart components scattered through the page +- No exit-intent modal, newsletter popup, or any popup of any kind +- No testimonials with headshots arranged in a grid +- No marketing-speak: "enterprise-grade," "blazing fast," "world-class," "industry-leading" +- No "AI-powered" framing. The product uses ML; that is not the lead +- No corporate stock photography of people in offices +- No vague "join the future" CTAs. Specific verbs only + +--- + +## Open questions + +- The comparison page is committed to but the comparators are not yet selected. Decision needed before `landing-page-copy` runs on that page. +- The hero image needs custom photography or commissioned illustration. Considered Restrained does not support stock. Budget question for the team. +- The pricing page is not yet scoped. Brief should be confirmed before that page is built; pricing pages have their own conventions. +- Author bylines are part of the documentation but not the marketing site yet. Worth deciding whether marketing pieces carry author attribution. diff --git a/skills/cro-optimization/SKILL.md b/skills/cro-optimization/SKILL.md new file mode 100644 index 0000000..d1ea82f --- /dev/null +++ b/skills/cro-optimization/SKILL.md @@ -0,0 +1,271 @@ +--- +name: cro-optimization +description: "Run conversion rate optimization through hypothesis-driven testing including audit, hypothesis generation, test design, statistical analysis, and rollout decisions. Use this skill whenever the user wants to optimize conversion, run A/B tests, audit a funnel, generate test hypotheses, design experiments, or analyze test results. Triggers on conversion optimization, CRO, A/B test, split test, multivariate test, hypothesis, conversion funnel, funnel audit, experiment design, statistical significance, lift, optimization. Also triggers when the user has a conversion problem and isn't sure where to start, or when test results are ambiguous and need interpretation." +category: growth +catalog_summary: "Hypothesis-driven testing, conversion optimization" +display_order: 2 +--- + +# CRO Optimization + +Run conversion rate optimization as a structured discipline: audit → hypothesize → test → decide. Stack-agnostic. Tool-agnostic. + +This skill is for running tests against existing pages and flows. For writing landing page copy from scratch, use `landing-page-copy`. For setting up the analytics that make CRO possible, use `analytics-strategy`. + +--- + +## When to use + +- Converting traffic at lower rate than expected +- Specific funnel step has high drop-off +- Pages with high traffic that could move the needle if optimized +- A/B testing infrastructure exists (or can be set up) +- Statistical significance and sample size questions + +## When NOT to use + +- Without sufficient traffic to test (under ~5,000 monthly conversions per variant) +- Pre-launch (no users to test on yet) +- Strategy or messaging-level questions that need qualitative research first +- Brand-defining choices (CRO can't optimize a fundamentally wrong brand) + +--- + +## Required inputs + +- The page or flow under optimization +- Current conversion rate and traffic volume +- Access to analytics (event tracking, funnel data) +- An A/B testing tool (or willingness to set one up) +- Time and budget for testing (typically 2 to 8 weeks per test) + +--- + +## The framework: 4 phases + +### 1. Audit + +Diagnose before treating. + +Quantitative audit: + +- Funnel data. Where are users dropping off? The biggest drop is the biggest opportunity. +- Segmentation. Does the funnel perform differently by source, device, geography, audience type? +- Performance data. Are slow pages dragging conversions? +- Search Console / on-site search. What are users looking for that they can't find? + +Qualitative audit: + +- Session replay. Watch 20+ sessions of users on the target flow. Note friction, confusion, hesitation. +- Heatmaps. Where do users click? Where do they scroll? Where do they not? +- User interviews / surveys. Why did users not convert? Survey people who started but abandoned. +- Form analytics. Which fields cause abandonment? Which cause errors? +- Customer support tickets. What conversion-related questions come in? + +Heuristic audit: + +- Apply CRO heuristics to the flow: + - Is the value proposition clear in 5 seconds? + - Is there a single primary CTA per page? + - Is the form length appropriate to the offer? + - Is the trust/social proof present? + - Are objections handled? + - Is the page accessible? (Accessibility issues hurt conversion silently.) + +The audit produces a list of suspected friction points. Each becomes a hypothesis candidate. + +### 2. Hypothesis + +A testable statement. + +Hypothesis structure: + +> Because [observation from audit], we believe that [change] will produce [predicted outcome] for [user segment], because [reason]. + +Example: + +> Because session replays show users abandoning at the shipping step (audit), we believe that adding visible shipping cost to the product page (change) will increase add-to-cart conversion by 5 percent (outcome) for desktop users (segment), because users are surprised by shipping cost and abandon (reason). + +Hypothesis quality criteria: + +- Specific change (not "improve the design") +- Measurable outcome (with a target) +- Grounded in evidence (audit, research, prior tests) +- Tied to a known mechanism (why would this work?) + +Hypothesis prioritization (ICE or PIE): + +- Impact: How much could this move the metric? +- Confidence: How likely is the hypothesis to be right? +- Ease: How easy to test? (Time, complexity, risk) + +Score each 1 to 10. Highest combined scores test first. + +### 3. Test design + +A test that produces an unambiguous answer. + +Sample size and duration: + +Use a sample size calculator (most A/B tools have one) before launching. Inputs: + +- Baseline conversion rate +- Minimum detectable effect (the smallest lift you'd care about) +- Statistical power (typically 80%) +- Significance level (typically 95%) + +This produces required sample size per variant. Run the test until that sample is reached, OR for a minimum duration that captures full business cycle (typically 2 weeks minimum, to cover weekends and weekly patterns). + +Common test setup mistakes: + +- Stopping the test the moment significance is hit (peeking) +- Running tests for too short to capture a full business cycle +- Running multiple overlapping tests on the same flow +- Testing during atypical periods (Black Friday, holidays, major campaigns) +- Excluding mobile when 50%+ of traffic is mobile (or vice versa) +- Testing on too small a slice of traffic (low statistical power) +- Not segmenting analysis (overall lift can hide negative impact on a segment) + +Test parameters to define before launch: + +- Primary metric (one) +- Guardrail metrics (do not go down) +- Sample size +- Duration (minimum and maximum) +- Decision criteria (when to ship, when to kill, when to extend) +- Segments to analyze in addition to overall + +### 4. Decide + +After the test concludes. + +Decision framework: + +\| Outcome \| Decision \| +\|---\|---\| +\| Variant clearly wins (>95% significance, exceeds minimum effect) \| Ship variant. Document. Continue testing. \| +\| Variant clearly loses \| Kill. Capture the lesson. Iterate hypothesis. \| +\| Inconclusive (neither significant) \| Larger test, different angle, or move on. Don't ship "tied" variants. \| +\| Small lift, lots of variance \| Probably not worth shipping. Even if "winner," may not replicate. \| +\| Wins overall, loses for important segment \| Investigate segment. Consider segment-specific solution. \| + +Anti-patterns: + +- "It looks like it's winning, ship it" before reaching significance +- Shipping a variant because the team wants to (HiPPO - highest paid person's opinion) +- Killing tests too early because they look bad +- Re-running tests until they "win" (false positive risk) +- Not capturing the learning when a test loses + +--- + +## Statistical foundations + +### Significance and confidence + +A 95% significance level means: if there were truly no difference between variants, there's only a 5% chance you'd see results this extreme by chance. + +That's not the same as "95% chance the variant wins." + +Most CRO tools report Bayesian probabilities ("95% chance of being best"). Read the methodology your tool uses. + +### Sample size + +Conversion testing needs more sample than people intuit. Quick reference: + +\| Baseline rate \| Minimum detectable effect \| Sample per variant \| +\|---\|---\|---\| +\| 2% \| 10% relative lift \| ~75,000 \| +\| 2% \| 20% relative lift \| ~19,000 \| +\| 5% \| 10% relative lift \| ~30,000 \| +\| 5% \| 20% relative lift \| ~7,500 \| +\| 10% \| 10% relative lift \| ~14,000 \| +\| 10% \| 20% relative lift \| ~3,500 \| + +(Approximate. Use a calculator.) + +If your monthly conversions per variant don't reach these numbers, A/B testing won't produce reliable results. Iterate via design and qualitative research instead. + +### Multiple testing + +The more variants and metrics tested simultaneously, the more false positives. Adjust significance thresholds for multiple comparisons (Bonferroni or similar). + +--- + +## Workflow + +1. Audit. Quantitative + qualitative + heuristic. +2. Generate hypotheses. From audit findings. Apply hypothesis structure. +3. Prioritize. ICE or PIE. Top 3 to 5 to test next. +4. Design the test. Sample size, duration, primary and guardrail metrics, decision criteria. +5. Implement. Build variants. QA carefully (broken variants invalidate tests). +6. Run. Don't peek. Don't stop early. +7. Analyze. Overall and by segment. Note interesting patterns regardless of significance. +8. Decide. Ship, kill, or extend. +9. Document. Hypothesis, design, results, decision, lesson. +10. Compound. Apply lessons to next round of hypotheses. + +--- + +## Failure patterns + +- Testing without audit. Random changes, random results. +- Vague hypotheses. "Make it better" is not a hypothesis. +- Peeking and early stopping. Bias toward false positives. +- Underpowered tests. Not enough sample for a real conclusion. +- HiPPO override. Highest paid person's opinion overrides the data. +- Testing during atypical periods. Holidays distort results. +- Single metric obsession. Conversion ups but average order value craters. Net loss. +- No guardrail metrics. Testing for one outcome, missing damage to others. +- Documentation gap. Wins captured, losses forgotten. Same hypothesis re-tested 3 times. +- Treating each test in isolation. Compounding learning across tests is where CRO programs really win. + +--- + +## Output format + +Default output: a markdown test plan at `cro-test-[hypothesis-slug].md` per test. After the test runs, append the results section. + +Structure: + +```markdown +# Test: [Hypothesis short name] + +## Hypothesis +Because [observation], we believe that [change] will produce [outcome] for [segment], because [reason]. + +## Audit evidence +[What evidence supports this hypothesis] + +## Test design +- Primary metric: +- Guardrail metrics: +- Sample size required: +- Duration: minimum X, maximum Y +- Variant traffic split: +- Segments to analyze: + +## Decision criteria +- Ship if: [conditions] +- Kill if: [conditions] +- Extend if: [conditions] + +## Results (filled after test) +- Sample reached: +- Duration actual: +- Primary metric: [variant vs control + significance] +- Guardrail metrics: [results] +- Segment analysis: [findings] + +## Decision +[Ship / Kill / Extend / Iterate] - [Why] + +## Lesson +[What this teaches us, regardless of outcome] +``` + +--- + +## Reference files + +- [`references/hypothesis-library.md`](references/hypothesis-library.md) - Common high-impact hypothesis patterns by funnel stage. diff --git a/skills/cro-optimization/references/hypothesis-library.md b/skills/cro-optimization/references/hypothesis-library.md new file mode 100644 index 0000000..89fbae6 --- /dev/null +++ b/skills/cro-optimization/references/hypothesis-library.md @@ -0,0 +1,313 @@ +# Hypothesis Library + +Common high-impact CRO hypothesis patterns by funnel stage. Use as starting points; adapt to the specific product and audience. Each pattern includes the typical evidence that supports it and the typical mechanism behind why it works. + +--- + +## Top of funnel: hero and value proposition + +### H1: Outcome-led headline beats feature-led + +Hypothesis: Replacing a feature-led headline ("Advanced workflow automation") with an outcome-led headline ("Ship 30% faster") will increase scroll-past-hero rate and CTA clicks. + +Evidence to look for: +- Session replays show users bouncing within 3 seconds +- Heatmaps show low engagement below the hero +- The current headline names a feature, not a benefit + +Mechanism: Users grant 3 to 5 seconds to decide whether to continue. Outcome language is processed faster than feature language. + +Test design: Hero-only swap. Control vs variant. Primary metric: scroll past hero + CTA click. + +--- + +### H2: Specific number beats vague claim + +Hypothesis: Replacing "Save time on month-end close" with "Close in 3 days, not 2 weeks" will increase signup rate. + +Mechanism: Specific numbers are more credible and more memorable than vague claims. + +--- + +### H3: Customer-facing ID over jargon + +Hypothesis: Replacing internal/industry jargon ("ETL pipeline orchestration") with customer language ("Move data between your tools without engineering") will improve hero engagement. + +Mechanism: Industry insiders use jargon. Most prospects are not industry insiders. + +--- + +### H4: Real customer photo beats stock + +Hypothesis: Replacing stock-photo hero imagery with photos of actual customers using the product will increase signup rate. + +Mechanism: Stock photos are pattern-recognized as marketing fluff. Real customer photos signal authenticity. + +--- + +## Mid-funnel: feature blocks and social proof + +### H5: Specific named customer logos beat unnamed + +Hypothesis: Replacing "Trusted by 1,000+ companies" with named logos will improve trust and conversion. + +Evidence: Heatmaps show users hovering near social proof but not converting. + +Mechanism: Named logos provide verifiable trust. Numbers without names are easily fabricated and users know it. + +--- + +### H6: Specific outcome quote beats generic praise + +Hypothesis: Replacing "We love this product!" with "Reduced our onboarding time by 40 percent in three months" will increase trust score and conversion. + +Mechanism: Specific outcomes are credible because they're quantifiable. Generic praise is dismissed as cherry-picked. + +--- + +### H7: Founder quote at scale stage + +Hypothesis: Adding a founder quote and photo on the homepage will increase early-stage trust signals. + +Evidence: Brand is unknown. No major customer logos to display yet. + +Mechanism: Personal accountability from a named person beats anonymous brand voice when trust signals are scarce. + +--- + +### H8: Comparison table for competitive categories + +Hypothesis: Adding a comparison table against named competitors will increase conversion for prospects in active evaluation. + +Mechanism: Users in evaluation mode are comparing anyway. Honest comparison reduces objection-handling work. + +Risks: Can backfire if comparison feels biased or if competitors are smaller than you (gives them oxygen). + +--- + +## Form and signup + +### H9: Fewer form fields wins + +Hypothesis: Reducing signup fields from 7 to 3 will increase signup conversion. + +Evidence: Form analytics show high abandonment, especially on optional fields. + +Mechanism: Each form field is friction. Optional fields without value to the user feel like data collection for company benefit. + +--- + +### H10: Progressive profiling beats upfront fields + +Hypothesis: Moving non-essential signup fields to a post-signup onboarding flow will increase initial signup conversion without hurting profile completion. + +Mechanism: Users commit incrementally. The hardest "yes" is the first one. + +--- + +### H11: Social signup options reduce friction + +Hypothesis: Adding "Sign up with Google" alongside email signup will increase signup rate. + +Risks: OAuth providers can also reduce signups for users uncomfortable with social login. Test, don't assume. + +--- + +### H12: Visible password requirements reduce errors + +Hypothesis: Showing password requirements (8 chars, etc.) above the field instead of as error messages will reduce form errors and abandonment. + +Mechanism: Errors after submission feel like punishment. Pre-emptive guidance feels like assistance. + +--- + +### H13: Trust signals near form + +Hypothesis: Adding "Free for 14 days. No credit card." adjacent to the CTA will increase form completion. + +Mechanism: Reduces perceived risk at the point of commitment. + +--- + +## Pricing page + +### H14: Annotated tiers beat unannotated + +Hypothesis: Adding "Best for" labels on each pricing tier ("Best for solo founders," "Best for teams of 10+") will increase plan selection clarity. + +Mechanism: Users self-select faster when given decision shortcuts. + +--- + +### H15: Annual emphasis beats monthly default + +Hypothesis: Defaulting the pricing toggle to annual (with savings highlighted) will increase annual plan adoption. + +Mechanism: Defaults stick. Loss-framed savings ("Save $X") are more compelling than gain-framed. + +--- + +### H16: Clear "what's included" reduces confusion + +Hypothesis: Adding a checkmark feature comparison below the pricing tiers will reduce sales-assist requests and improve self-service conversion. + +Mechanism: Many prospects abandon when they can't quickly verify a needed feature is in their tier. + +--- + +### H17: Social proof on pricing page + +Hypothesis: Adding tier-specific customer testimonials ("Why we picked Team plan") will increase plan upgrade rate. + +Mechanism: Tier-specific proof reduces fear of overpaying or under-buying. + +--- + +## Checkout / cart + +### H18: Free shipping threshold visible + +Hypothesis: Adding a "$X away from free shipping" message in the cart will increase average order value. + +Evidence: Cart abandonment correlated with sub-threshold orders. + +Mechanism: Goal gradient. Users near a goal accelerate toward it. + +--- + +### H19: Guest checkout option + +Hypothesis: Adding a guest checkout option will increase conversion of first-time buyers. + +Mechanism: Account creation is friction at the worst possible moment (when the user has just decided to buy). + +--- + +### H20: Multiple payment methods + +Hypothesis: Adding [PayPal / Apple Pay / Google Pay / etc.] at checkout will increase mobile conversion. + +Mechanism: Saved payment methods reduce friction. Mobile typing is painful. + +--- + +### H21: Visible total throughout checkout + +Hypothesis: Showing the running total persistently in the checkout flow will reduce abandonment. + +Evidence: Step-by-step abandonment shows users dropping after seeing fees. + +Mechanism: Surprise cost is the #1 cause of cart abandonment. + +--- + +### H22: Trust badges at checkout + +Hypothesis: Adding security badges (SSL, PCI, money-back guarantee) at the payment step will increase completion. + +Mechanism: Security concerns peak at payment entry. + +--- + +## Onboarding (post-signup) + +### H23: Single first action vs feature tour + +Hypothesis: Replacing a feature tour with a single guided first action will increase activation. + +Mechanism: Feature tours teach. First actions deliver value. Users who experience value retain better than users who learn features. + +--- + +### H24: Sample data on first login + +Hypothesis: Pre-loading the new user's account with sample data will increase first-week retention. + +Mechanism: Empty states are demotivating. Pre-populated data shows "what good looks like." + +--- + +### H25: Time-to-value reduction + +Hypothesis: Reducing the steps from signup to first valuable action from 12 to 4 will increase activation rate. + +Evidence: Funnel analysis shows huge drops in the middle of the onboarding flow. + +Mechanism: Each step is a chance to bounce. Fewer steps = more activations. + +--- + +## Email and notifications + +### H26: Subject line specificity + +Hypothesis: Replacing "Update from [Brand]" with a specific benefit-led subject ("Your invoice is ready" or "Save 20% this week") will increase open rate. + +Mechanism: Inbox is competitive. Specificity earns the open. + +--- + +### H27: Single CTA per email + +Hypothesis: Reducing email CTAs from 3 to 1 will increase click-through to primary action. + +Mechanism: Choice paralysis. Multiple CTAs dilute the primary action. + +--- + +### H28: Personalization beyond name + +Hypothesis: Personalizing email body content based on user behavior (last action, product viewed) will increase reactivation rate. + +Mechanism: Generic emails feel like spam. Behaviorally relevant emails feel like service. + +--- + +## Mobile-specific + +### H29: Tap target sizing + +Hypothesis: Increasing tap targets to meet 44x44 minimum will reduce mobile bounce rate. + +Evidence: Mobile heatmaps show mis-taps and rage clicks. + +Mechanism: Small targets fail more often than large ones. + +--- + +### H30: Sticky CTA on mobile + +Hypothesis: Adding a sticky bottom CTA on mobile pages will increase conversion. + +Mechanism: Long mobile pages bury CTAs. Sticky keeps the action available. + +Risks: Can cover content. Test for accessibility issues. + +--- + +### H31: Mobile-specific headlines + +Hypothesis: Shortening headlines for mobile viewports (vs desktop) will reduce bounce rate. + +Mechanism: Long headlines on mobile become walls of text. Short headlines preserve hierarchy. + +--- + +## Compounding tests + +The biggest CRO wins come from compounding learnings. After running 5 to 10 tests, you should know: + +- What kind of headlines win in your category +- How long your forms should be +- Which trust signals move your audience +- Which features matter to your buyer +- What price framing converts + +These insights compound across tests. Document each test's lesson, even when the test loses. + +A pattern to watch: +- Test #1: Outcome-led headline wins +- Test #5: Outcome-led email subject wins +- Test #10: Outcome-led ad copy wins + +You haven't just run 10 tests. You've discovered that "outcome-led messaging" is your audience's preference, broadly. That insight is worth more than any single test. diff --git a/skills/data-warehouse-experimentation/SKILL.md b/skills/data-warehouse-experimentation/SKILL.md new file mode 100644 index 0000000..f4a424f --- /dev/null +++ b/skills/data-warehouse-experimentation/SKILL.md @@ -0,0 +1,389 @@ +--- +name: data-warehouse-experimentation +description: "Running experiments out of the data warehouse instead of via dedicated experiment platforms. SQL-based assignment, exposure logging discipline, metric definitions in dbt models, statistical analysis in SQL or Python, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms like Statsig and Optimizely. Triggers on warehouse-native experimentation, run experiments in BigQuery, run experiments in Snowflake, dbt experiments, SQL t-test, CUPED variance reduction, exposure log, sample ratio mismatch, sequential testing, mSPRT, doubly robust estimation, build vs buy experimentation. Also triggers when the team is choosing between platform and warehouse, building warehouse-native experiment infrastructure, auditing one, or running an experiment with a custom metric the platform cannot handle." +category: product +catalog_summary: "Run experiments out of the warehouse: SQL assignment, exposure logs, dbt metric definitions, statistical analysis, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms" +display_order: 9 +--- + +# Data Warehouse Experimentation + +A senior data scientist's playbook for running experiments natively out of BigQuery, Snowflake, or any modern data warehouse, with metric definitions in dbt and statistical analysis in SQL or Python. + +Most companies that run experiments at scale use a dedicated platform. Statsig, Optimizely, LaunchDarkly with experimentation, PostHog, Amplitude Experiment. The platforms are good. They handle assignment, instrumentation, and analysis in one product, and the SQL-savvy data team does not have to reinvent the variance reduction wheel. + +There is a different operational model that mature data teams increasingly choose: warehouse-native experimentation. Assignment happens in code or via feature flags. Exposure events fire to the warehouse like any other event. Metrics are defined as dbt models. Statistical analysis runs as SQL or in a Python notebook against warehouse data. The "experiment platform" is just your existing data stack. + +This skill covers when warehouse-native is the right call, the architecture, and the specific techniques that make it work: assignment patterns, exposure logging discipline, metric definitions in dbt, t-tests and CUPED in SQL, sequential testing, and the pitfalls that take down homegrown setups. + +When to use this skill: deciding between platform vs warehouse-native, building a warehouse-native experiment infrastructure, auditing an existing one, or running a specific experiment when the platform of record cannot handle a custom metric or segmentation. + +--- + +## What this skill is for + +This skill spans the operational execution model for warehouse-native experimentation. It does not replace the methodology and interpretation skills; it composes with them. + +- `experiment-design` covers methodology: hypotheses, sample size, randomization unit, primary metric. Tool-agnostic. Read it first to design the experiment correctly regardless of where it runs. +- `experimentation-analytics` covers interpretation: confidence intervals, p-values, effect size, decision frameworks. Tool-agnostic. Read it when results land. +- `experimentation-platform-orchestrator` covers the platform-vs-warehouse decision in detail. Read it to decide whether to use a platform or this skill. +- `feature-flagging` covers assignment infrastructure when not running through a platform. Read it for the flag-management discipline that this skill assumes. +- This skill (`data-warehouse-experimentation`) covers the operational execution: SQL-based assignment, exposure logging, metric definitions in dbt, statistical analysis in SQL or Python, variance reduction, sequential testing. + +The distinction is between "what to do" (the methodology and interpretation skills) and "how to do it without a vendor platform" (this skill). Read this skill after you have decided warehouse-native is the right call. If you are still deciding, start with `experimentation-platform-orchestrator`. + +--- + +## When warehouse-native is the right call + +Six factors push the decision toward warehouse-native. + +1. Cost at volume. Platforms charge per MAU or per event. At 10K MAU the platform is cheap; at 1M MAU the bill becomes a real budget item. Warehouse-native runs on infrastructure you already pay for. +2. Custom metrics. If your primary metric is a complex business metric (revenue with refund-aware logic, cohort LTV, retention bracket, multi-event composites), platforms can struggle. Warehouse-native expresses any metric you can write in SQL. +3. Custom segmentation. Enterprise customers, account-tier crosscuts, complex behavioral segments. Platforms have segmentation features; the depth varies. dbt models compose without limit. +4. Trust requirements. Regulated industries (healthcare, finance, government) need full transparency into the math. Warehouse-native gives you every step of the calculation auditable in SQL. +5. Existing data team strength. If you have data engineers and data scientists, you have most of the infrastructure. Adding experimentation discipline on top costs less than adopting a new platform. +6. Iteration on metric definitions. Platforms ship metric updates on their own cadence. Warehouse-native iterates as fast as your dbt deployments. + +Five factors push toward platform. + +1. Frontend visual experiments. Optimizely's bread and butter. Variant code injected via a script tag, with WYSIWYG editing. +2. Sub-week iteration speed. Some platforms set up an experiment in 30 minutes; warehouse-native often takes a day or more for the first run of a new metric pattern. +3. Teams without strong data infrastructure. If you do not have a warehouse, dbt, and analysts, do not start with warehouse-native. The platform is the right call. +4. Mobile experimentation. SDK-based assignment with offline support is the platform's job, not the warehouse's. +5. Out-of-the-box sequential testing with strict guarantees. Statsig and Eppo ship mSPRT with calibrated alpha-spending. Building this in-house is real work. + +Detail and a decision tree in [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md). Many mature teams use both; warehouse-native for the hard cases, platform for fast iteration on standard experiments. + +--- + +## The architecture + +Four components, in order of data flow. + +1. Assignment. How users get bucketed into variants. Hash function, feature flag, or randomized assignment table. +2. Exposure logging. A discrete event fired the first time a user is exposed to the experiment, written to the warehouse like any other event. +3. Metric definitions. SQL queries (or dbt models) that compute the primary and secondary metrics from warehouse events. +4. Analysis. Statistical computation in SQL or Python that joins exposure to metrics and produces effect estimates with confidence intervals. + +The flow. User visits the product. Assignment determines the bucket (control or treatment). If the user is exposed to the variant (sees the treatment-specific behavior), an exposure event fires to the warehouse. The user takes actions, generating metric events to the same warehouse. At analysis time, exposure joins to metrics on the assignment unit (typically `user_id`); the analysis computes lift and produces a decision. + +The exposure-event pattern is critical. Without it you can compute only an "intent-to-treat" analysis (everyone assigned, regardless of whether they saw the variant). With it you compute the "exposed" analysis on the population that actually experienced the variant. The latter is usually what you want, especially when the variant only affects a subset of the assigned users (e.g., users who reached a specific page). + +--- + +## Assignment patterns + +Three approaches. + +Deterministic hash assignment. The default for warehouse-native. + +```sql +MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 +``` + +The salt (`'exp_button_color_v1'`) ensures different experiments produce uncorrelated assignments for the same user. Reproducible (same input always produces the same bucket), no service dependency, salt isolation across experiments. The assignment can be computed inline in any SQL query. + +Feature flag assignment. Rely on a feature flag service (LaunchDarkly, Statsig flags, Unleash, internal) to do bucketing; the warehouse just records the assignment that the flag service chose. + +```sql +-- Read assignment from the flag service's logs +SELECT user_id, variant_id, assigned_at +FROM flag_service.assignments +WHERE flag_key = 'exp_button_color_v1' +``` + +This works when the flag service is the source of truth for assignment and the warehouse mirrors the assignment table. Useful when assignment must respect flag-service rules (e.g., percentage rollouts, targeting rules) that are inconvenient to replicate in SQL. + +Randomized assignment table. Pre-randomize users into a table at experiment start. + +```sql +CREATE TABLE exp_button_color_v1_assignments AS +SELECT + user_id, + CASE WHEN RAND() < 0.5 THEN 'control' ELSE 'treatment' END AS variant_id +FROM dim_users +WHERE eligible = true; +``` + +Less common; useful when the eligibility set is fixed at experiment start and you want assignment to be deterministic and explicit (e.g., for compliance audit). The downside: new users joining mid-experiment are not in the table; either skip them or fall back to hash assignment. + +The deterministic hash approach is the default for warehouse-native because it requires no service dependency and produces stable, auditable assignments. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## The exposure log + +The single most important discipline in warehouse-native experimentation. + +Required exposure event schema: + +\| Field \| Type \| Notes \| +\|---\|---\|---\| +\| `experiment_id` \| string \| Unique identifier per experiment. \| +\| `variant_id` \| string \| The variant the user was bucketed into. \| +\| `user_id` \| string \| The assignment unit. \| +\| `exposed_at` \| timestamp \| ISO 8601 UTC. The moment exposure fired. \| +\| `context_` \| various \| Optional context properties: device, page, account_id. \| + +Fire exposure exactly when the user has seen the variant-specific behavior. Not at page load. Not at session start. Not at app open. + +The "delayed exposure" trap. If the variant only matters at button click and you fire exposure at page load, every page-load user enters the analysis whether or not they ever saw the variant. The control group includes users who never reached the button; the treatment group does too. The analysis dilutes the real effect. + +Worked example. The treatment shows a new pricing page; the control shows the old one. Fire exposure when the pricing page loads, not when the user lands on the homepage. Users who never reach the pricing page are not exposed to either variant; they should not be in the analysis. + +The "always-fire" trap. Some implementations fire exposure on every variant-specific interaction. The user clicks the button five times; exposure fires five times. The exposure log is now five times larger than it should be, and analysis tools that count distinct user_ids in exposure handle this correctly while tools that count rows do not. + +The discipline. Fire exactly one exposure event per user per experiment, at the moment of first variant-specific exposure. Use a deterministic flag in the client (or a server-side cache) to enforce single-fire. Detail in [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md). + +--- + +## Metric definitions in dbt models + +Defining metrics as dbt models gives you four things. + +1. Version control on metric definitions.* Every change to a metric is a git commit. The history is queryable. +2. Testability. dbt tests on the metric output catch regressions. +3. Composability. The same `fct_orders` model feeds the board dashboard, the experiment analysis, and the executive report. Aligned definitions, no drift. +4. Single source of truth. When the experiment says X and the board says Y, the answer is in the dbt model, not in two unrelated SQL files. + +Pattern. + +```sql +-- models/experiments/exp_metrics_revenue.sql +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + MIN(occurred_at) AS first_purchase_at +FROM {{ ref('fct_orders') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' +GROUP BY user_id +``` + +The experiment analysis joins this to the exposure log on `user_id` and computes group means. + +The variance discipline. The same metric definition is used in board dashboards AND in experiment analysis. No "experiment-specific revenue calculation" that is slightly different. Otherwise you get the "the experiment said the revenue lifted but the board did not move" problem, which is almost always a metric-definition mismatch. + +The namespace pattern. Use `exp_metrics_` for experiment-shaped models that group by `user_id` and produce one row per user. Use `fct_` for the underlying fact tables that feed both metric models and dashboards. Detail in [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md). + +--- + +## Statistical analysis in SQL + +The basic two-sample Welch's t-test in SQL. + +```sql +WITH metric_by_variant AS ( + SELECT + e.variant_id, + COUNT() AS n, + AVG(m.net_revenue_cents) AS mean, + VAR_SAMP(m.net_revenue_cents) AS variance + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' + GROUP BY e.variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic +FROM + (SELECT FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment +``` + +Convert the t-statistic to a p-value or confidence interval using a SQL function (BigQuery: a UDF; Snowflake: native or a stored procedure) or compute in Python on the result of the SQL query. + +The SQL pattern is fine for simple t-tests on continuous metrics. For proportions tests, swap variance for `p * (1 - p)`. For non-parametric tests (Mann-Whitney), the SQL gets ugly fast; switch to Python. + +Anything more complex than a simple t-test (CUPED, bootstrap, doubly robust estimation, sequential testing) is easier in Python. Use SQL for the SUM-and-AVG aggregations; ship the result to Python for the statistical math. Detail in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Statistical analysis in Python + +The Python pattern, typically in a Jupyter or Hex notebook. + +```python +import pandas as pd +import numpy as np +from scipy import stats + +# Pull aggregated data from the warehouse +df = warehouse.query(""" + SELECT user_id, variant_id, net_revenue_cents + FROM exp_results + WHERE experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].net_revenue_cents +treatment = df[df.variant_id == 'treatment'].net_revenue_cents + +# Welch's t-test +t, p = stats.ttest_ind(treatment, control, equal_var=False) + +# Confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} cents (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"p-value: {p:.4f}") +``` + +Python gives you access to the full statistical ecosystem (`scipy`, `statsmodels`, `numpy`) for techniques SQL cannot easily express. + +The notebook pattern. One notebook per experiment, parameterized by `experiment_id`. Version-controlled in git or as Hex projects. Each notebook produces a written-up decision document at the end, archived in a queryable repository (Notion, GitHub markdown, or a dedicated experiment-results table in the warehouse). + +Detail and bootstrap templates in [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md). + +--- + +## Variance reduction: CUPED and beyond + +The most powerful variance reduction technique for warehouse-native experimentation: CUPED (Controlled-experiment Using Pre-Experiment Data). Originally from Microsoft. + +The intuition. If you can predict a user's metric behavior from pre-experiment data, you can subtract out that predicted variance, leaving a smaller residual to test on. + +```python +# Pre-experiment metric for each user (e.g., last 28 days revenue) +pre = pre_period_revenue(user_id) + +# Theta is the regression coefficient of the metric on the pre-period +theta = np.cov(metric, pre)[0, 1] / np.var(pre) + +# Adjusted metric +adjusted_metric = metric - theta * (pre - pre.mean()) +``` + +Run the t-test on the adjusted metric instead of the raw metric. The mean is preserved (CUPED does not change the point estimate) but the variance is smaller, so the confidence interval is narrower. + +CUPED typically reduces variance by 30 to 50 percent on engagement metrics. That is equivalent to running an experiment 1.5x to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +Other variance reduction techniques. + +- Stratification. Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. +- Regression adjustment. Fit an OLS regression with covariates; the residual analysis has lower variance. Generalizes CUPED to multiple covariates. +- Doubly robust estimation. Combines outcome modeling and propensity-score weighting. Useful in observational and quasi-experimental settings where randomization was imperfect. Outside the scope of typical A/B tests; pointer to academic references in the variance-reduction reference file. + +Detail with worked examples in [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md). + +--- + +## Pre-experiment power analysis + +Before running, compute required sample size. + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Solve for sample size given desired MDE +n_per_arm = tt_ind_solve_power( + effect_size=0.05, # Cohen's d + nobs1=None, + alpha=0.05, + power=0.8 +) + +# Or solve for MDE given sample size +mde = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8 +) +``` + +The "we need 10x more users than we thought" lesson. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10% lift; the actual effect is 1%, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. + +The fix. Use the historical distribution of past experiments' observed effects to set realistic MDE expectations. If the median observed effect across the last 30 experiments is 0.5%, plan for a 0.5% MDE on new experiments. The optimism asymmetry is real; correcting it requires looking at the actual distribution of effects, not the wished-for distribution. + +Detail in [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md). + +--- + +## Sequential testing patterns + +The "peeking" problem. Looking at experiment results before completion inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. + +Three approaches. + +- mSPRT (mixture Sequential Probability Ratio Test). Used by Optimizely and Statsig. Provides an always-valid p-value that survives peeking. Implementation in Python via `statsmodels` or custom code; not natively in SQL. +- Always-Valid Inference with confidence sequences. Howard et al. Confidence intervals that are valid at any sample size. Implementation requires careful Python; not for the data team that has not read the paper. +- Group sequential designs (O'Brien-Fleming boundaries). Pre-specified interim analysis points with calibrated alpha-spending. The classic frequentist approach. + +For warehouse-native, the practical recommendation is mSPRT in Python. Document the alpha-spending function used. Train one team member on the math; do not rely on a black-box implementation. + +The honest version. If you do not have someone on the team who understands sequential testing math, just do not peek. Pre-register sample size, run to completion, analyze once. Sequential testing is statistically correct only when implemented correctly; an incorrect implementation is worse than no peeking discipline at all. + +Detail in [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md). + +--- + +## Common pitfalls + +Eleven patterns recur in warehouse-native experimentation. Detail in [`references/common-pitfalls.md`](references/common-pitfalls.md). + +- "Our exposure log fires at page load." Should fire when the variant-specific behavior is shown, not at page load. The "delayed exposure" trap dilutes the effect. +- "We see lift in control, not treatment." Assignment-hash collision or salt reuse. Audit the salt; check that different experiments produce different bucket assignments for the same user. +- "P-value is 0.04, we are shipping." Probably underpowered plus multiple comparisons plus peeking. Compute the test at the planned sample size only; correct for multiple secondary metrics. +- "Experiment shows 30% lift." Almost certainly a bug. Effects that big rarely exist; first action is to audit the exposure log and metric definitions before celebrating. +- "Treatment users are different." Sample ratio mismatch (SRM). The assignment hash is broken or the exposure log is biased. Check the SRM before computing any metric. +- "We cannot reproduce yesterday's number." Non-deterministic queries (window functions without explicit ORDER BY, sampling without a seed) or floating-point issues in aggregations. Make queries deterministic; document the random seed if any. +- "Custom metric definition disagrees with the board metric." Bad. Align them by using the same dbt model. Otherwise nobody trusts either number. +- "We never finished the experiment." Pre-register stop criteria; honor them. Experiments that drift indefinitely waste team time and produce ambiguous decisions. +- "iOS users converted 3x in treatment." Segment effect or instrumentation bug. Check if iOS instrumentation differs from the rest. Beware over-claiming on small segments. +- "It worked on phase 1, broke on phase 2." Simpson's paradox from cohort mix shift. The aggregate trend reverses when the underlying segments are weighted differently across phases. +- "Statistical significance but tiny effect." Large sample inflated power. The p-value is below 0.05 but the effect is 0.3%. Consider practical significance: is 0.3% worth shipping? + +--- + +## The framework: 12 considerations for warehouse-native experimentation + +When designing or running a warehouse-native experiment, walk these 12 considerations. + +1. Platform vs warehouse decision. Cost, custom metrics, segmentation, trust, team strength. Read `experimentation-platform-orchestrator` if undecided. +2. Assignment unit. User, account, session, device. Pick once at experiment start and stick to it. +3. Assignment salt. Unique per experiment to prevent correlation with prior experiments. Document the salt convention. +4. Exposure logging discipline. Fire when the variant matters, not at page load. One exposure event per user per experiment. +5. SRM check. Sample ratio mismatch indicates assignment bugs. Check before computing any metric. +6. Metric definition reuse. Same dbt model for board and experiment. No experiment-specific calculations that drift from canonical metrics. +7. Pre-experiment power analysis. Realistic MDE based on the historical distribution of past observed effects. +8. Variance reduction. CUPED for engagement metrics. 30 to 50 percent variance reduction is worth the engineering for any team running 5+ experiments per quarter. +9. Statistical method. Welch's t-test as default. Bootstrap for skewed distributions. Doubly robust estimation for quasi-experiments. +10. Sequential testing. mSPRT or stop-at-N. Document alpha-spending. If you cannot implement correctly, do not peek. +11. Multiple comparisons. Bonferroni or Benjamini-Hochberg correction across secondary metrics. +12. Decision documentation. Write the result up. Archive in a queryable repository. The next experiment will benefit from the institutional memory. + +The output of the framework is an experiment record. Pre-registered sample size and stop criteria, the assignment salt, the exposure log specification, the dbt metric model, the analysis notebook, and a written-up decision. The record lives in version control or in a dedicated experiment-tracking system; the analysis is reproducible from the record. + +--- + +## Reference files + +- [`references/warehouse-vs-platform-decision.md`](references/warehouse-vs-platform-decision.md) - When each operational model is the right call. Cost considerations at different scales. Hybrid patterns. Migration patterns. +- [`references/assignment-and-exposure-patterns.md`](references/assignment-and-exposure-patterns.md) - Hash assignment SQL templates for BigQuery and Snowflake. Salt naming conventions. Exposure event schema. SRM check SQL. +- [`references/metric-definitions-in-dbt.md`](references/metric-definitions-in-dbt.md) - dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. +- [`references/statistical-analysis-templates.md`](references/statistical-analysis-templates.md) - SQL and Python templates for Welch's t-test, proportions test, Mann-Whitney, bootstrap. Notebook structure. +- [`references/variance-reduction-techniques.md`](references/variance-reduction-techniques.md) - CUPED math and Python implementation with worked example. Stratification. Regression adjustment. Doubly robust estimation primer. +- [`references/power-analysis-calculations.md`](references/power-analysis-calculations.md) - MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. +- [`references/sequential-testing-patterns.md`](references/sequential-testing-patterns.md) - mSPRT, confidence sequences, group sequential designs. Honest framing on when to peek. +- [`references/common-pitfalls.md`](references/common-pitfalls.md) - Eleven failure patterns with diagnoses and fixes. + +--- + +## Closing: the build-vs-buy decision is real + +Warehouse-native experimentation is powerful but expensive in engineering time. A first-year experimentation team should almost always start with a platform; the platform handles 90 percent of cases and lets you focus on hypotheses, not infrastructure. The team that graduates to warehouse-native does so because their volume, custom metric needs, or trust requirements outgrew what platforms offer. + +If you are building warehouse-native because "platforms cost too much" without first running the math: you are underestimating the cost of your team's engineering time. The platform fee that looks expensive on a procurement form is often cheaper than three months of a data engineer's time spent reinventing CUPED. + +If you are building it because the platform cannot handle your specific needs: you are probably right and the investment will pay back. Platforms are general; your business is specific. The custom metric the platform cannot express is often the metric that matters most for your decisions. + +Honest middle ground: many mature teams use both. The platform for fast iteration on standard experiments where time-to-result matters more than custom depth. Warehouse-native for the hard cases where the platform's metric library or segmentation cannot reach. The hybrid is operationally complex; document the rule for which experiments go where, and revisit annually. diff --git a/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md b/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md new file mode 100644 index 0000000..a043446 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/assignment-and-exposure-patterns.md @@ -0,0 +1,230 @@ +# Assignment and exposure patterns + +Hash assignment SQL templates. Salt naming conventions. Exposure event schema. The delayed-exposure trap. Sample ratio mismatch (SRM) check. + +--- + +## Hash assignment SQL templates + +### BigQuery + +```sql +-- 50/50 split for experiment exp_button_color_v1 +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Snowflake + +```sql +-- 50/50 split using SHA1 hash and modulo +SELECT + user_id, + CASE + WHEN MOD(ABS(HASH(CONCAT(user_id, 'exp_button_color_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Postgres + +```sql +-- 50/50 split using md5 hash; convert hex to integer +SELECT + user_id, + CASE + WHEN ('x' \|\| SUBSTRING(MD5(user_id \|\| 'exp_button_color_v1'), 1, 8))::bit(32)::int % 100 < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +### Three-arm split + +```sql +-- 33/33/34 split (control / variant_a / variant_b) +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 33 + THEN 'control' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_three_way_v1'))), 100) < 66 + THEN 'variant_a' + ELSE 'variant_b' + END AS variant_id +FROM dim_users; +``` + +### Sub-sampling for opt-in experiments + +```sql +-- 10% of users in the experiment, 50/50 split among them +SELECT + user_id, + CASE + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_eligibility'))), 100) >= 10 + THEN 'not_in_experiment' + WHEN MOD(ABS(FARM_FINGERPRINT(CONCAT(user_id, 'exp_pricing_test_v1'))), 100) < 50 + THEN 'control' + ELSE 'treatment' + END AS variant_id +FROM dim_users; +``` + +Note the two different salts: one for eligibility, one for assignment. This ensures the eligibility decision is independent of the variant decision. + +--- + +## Salt naming conventions + +Three rules. + +1. Unique per experiment. Reuse the same salt across experiments and you correlate assignments. A user in control of experiment A is more likely to be in control of experiment B; the experiments interfere. +2. Stable across the experiment lifecycle. Do not change the salt mid-experiment. Changing the salt re-randomizes existing users; the analysis becomes uninterpretable. +3. Versioned. When semantics change, append `_v2`. The old experiment data remains queryable; the new salt produces independent assignments. + +Convention. + +``` +{prefix}_{descriptor}_{version} +``` + +Examples. + +- `exp_button_color_v1` +- `exp_pricing_test_v1` (eligibility salt) +- `exp_pricing_test_assign_v1` (assignment salt within eligible) +- `exp_recommendation_model_v2` (version 2 of an existing experiment) + +Document the salt convention. Add it to the experiment record. + +--- + +## Exposure event schema + +The required fields. + +\| Field \| Type \| Required \| Notes \| +\|---\|---\|---\|---\| +\| `experiment_id` \| string \| Required \| Unique identifier per experiment. \| +\| `variant_id` \| string \| Required \| The variant the user was bucketed into. \| +\| `user_id` \| string \| Required \| The assignment unit. \| +\| `exposed_at` \| timestamp \| Required \| ISO 8601 UTC. Server-stamped. \| +\| `assigned_at` \| timestamp \| Optional \| When the user was first assigned (may differ from exposed). \| +\| `device_type` \| string \| Optional \| mobile, web, desktop. \| +\| `app_version` \| string \| Optional \| For change-tracking when version-specific bugs surface. \| +\| `account_id` \| string \| Optional \| For B2B; the account context. \| +\| `session_id` \| string \| Optional \| For session-level path analysis. \| + +The minimum schema is the four required fields. Optional fields support segmentation and debugging. + +### Storage pattern + +Either as a dedicated `experiment_exposures` table or as an event in the main events table with `event_name = 'experiment_exposed'`. + +Dedicated table is cleaner for analysis. Main events table is simpler for instrumentation. Pick one and stick to it. + +--- + +## The delayed-exposure trap + +The single most common warehouse-native experimentation bug. + +The setup. The treatment shows a new pricing page; the control shows the old one. The team fires exposure at homepage load. + +The problem. Many users land on the homepage but never click through to the pricing page. They are counted as "exposed" to the experiment but never saw the variant. The control group includes users who never reached the pricing page; the treatment group does too. + +The result. The analysis dilutes the real effect. The treatment may have produced a 20 percent lift among users who actually saw the pricing page, but the analysis shows a 2 percent lift because 90 percent of "exposed" users never reached the variant. + +The fix. Fire exposure exactly when the user has seen the variant-specific behavior. + +```javascript +// Wrong: fires at every page load +function onHomepageLoad(user) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: getVariant(user), + user_id: user.id, + }); +} + +// Right: fires when the pricing page renders the variant-specific UI +function onPricingPageLoad(user) { + const variant = getVariant(user); + if (variant === 'treatment') { + renderNewPricingPage(); + } else { + renderOldPricingPage(); + } + // Fire once per user per experiment + if (!hasExposureFired(user, 'exp_pricing_v1')) { + fireExposure({ + experiment_id: 'exp_pricing_v1', + variant_id: variant, + user_id: user.id, + }); + markExposureFired(user, 'exp_pricing_v1'); + } +} +``` + +The discipline. Fire exposure when the variant-specific UI renders or the variant-specific code path executes. Use a single-fire flag (client-side cache or server-side state) to ensure exposure fires exactly once per user per experiment. + +--- + +## Sample ratio mismatch (SRM) check + +Before computing any metric, check that the assignment is balanced. + +```sql +-- For a 50/50 split, expect roughly equal counts in control and treatment +SELECT + variant_id, + COUNT() AS n, + COUNT() * 1.0 / SUM(COUNT()) OVER () AS share +FROM exposures +WHERE experiment_id = 'exp_button_color_v1' +GROUP BY variant_id; +``` + +Expected output. + +\| variant_id \| n \| share \| +\|------------\|--------\|-------\| +\| control \| 50,123 \| 0.501 \| +\| treatment \| 49,877 \| 0.499 \| + +If the share deviates from the expected 50 percent by more than 1 percentage point at large samples, you have an SRM. The chi-squared test detects this formally. + +```python +from scipy.stats import chi2_contingency + +observed = [50123, 49877] # control, treatment +expected_ratio = [0.5, 0.5] +chi2, p, dof, _ = chi2_contingency([observed, [sum(observed) r for r in expected_ratio]]) +print(f"SRM chi-squared p-value: {p:.4f}") +# p < 0.001 indicates SRM +``` + +If you have an SRM. Do not analyze the experiment. The assignment is broken (hash collision, biased exposure logging, instrumentation that fires for one variant but not the other). Fix the bug; restart the experiment. + +The honest pattern. Run an SRM check at the top of every experiment analysis notebook. If SRM is detected, abort with a clear error message; do not let the analysis proceed. + +--- + +## Common assignment and exposure mistakes + +- Salt reuse across experiments. A user in control of experiment A is correlated with control of experiment B. Use unique salts per experiment. +- Changing the salt mid-experiment. Re-randomizes existing users. The analysis becomes a mix of two different assignment functions. Pre-register the salt; freeze it at experiment start. +- Firing exposure on every event. Inflates the exposure log by 10 to 100x. Use single-fire enforcement. +- Server-side fire when only client renders the variant. Server-side fires for every API call; client-side fires only when the user reaches the variant-specific UI. Match exposure to where the variant matters. +- Eligibility check in the wrong place. Eligibility (e.g., paid users only) checked client-side after assignment produces biased exposure (only paid users in the log). Check eligibility before assignment, server-side. diff --git a/skills/data-warehouse-experimentation/references/common-pitfalls.md b/skills/data-warehouse-experimentation/references/common-pitfalls.md new file mode 100644 index 0000000..5e96609 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/common-pitfalls.md @@ -0,0 +1,143 @@ +# Common pitfalls + +Eleven failure patterns that recur in warehouse-native experimentation. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Exposure log fires at page load + +Symptom. The experiment shows a 1 percent lift; the team expected 10 percent. The lift is real but diluted because most exposed users never saw the variant. + +Root cause. Exposure fires at page load (or session start) regardless of whether the user reaches the variant-specific code path. The control group includes users who never saw the variant; the treatment group does too. + +Fix. Move exposure firing to the moment the variant-specific UI renders or the variant-specific code path executes. Re-run the experiment with corrected logging. + +Prevention. Document the exposure-firing rule in the experiment record. Code review the implementation. Check the exposure-to-metric ratio (if exposure count is much higher than expected metric count, exposure is firing too broadly). + +--- + +## 2. Lift in control, not treatment + +Symptom. The control group has a higher mean than the treatment group. The team is confused because the variant-specific changes should have increased the metric. + +Root cause. Assignment hash collision or salt reuse with a prior experiment. Users in control of the new experiment are correlated with users in treatment of an old experiment that also affected the metric. + +Fix. Audit the salt. Use a unique salt per experiment. Re-run with corrected assignment. + +Prevention. Salt naming convention with version suffix. Code review for new experiments. Run a chi-squared test of independence between the new experiment's assignment and recent prior experiments' assignments before launching. + +--- + +## 3. P-value is 0.04, we are shipping + +Symptom. The primary metric p-value is 0.04. The team declares victory and ships. Three months later the metric in production has not moved. + +Root cause. Some combination of underpowered experiment, multiple comparisons without correction, and peeking. Each of these inflates the false-positive rate; together they make a 0.04 p-value uninformative. + +Fix. Re-run with a pre-registered sample size, single primary metric, no peeking. If the lift is real, the second experiment will confirm it. If not, the first result was a false positive. + +Prevention. Pre-register the sample size, the primary metric, and the analysis method. Do not peek. Apply Bonferroni or BH correction across secondary metrics. Treat 0.04 with much more skepticism than 0.001. + +--- + +## 4. Experiment shows 30 percent lift + +Symptom. The treatment shows a 30 percent lift on the primary metric. The team is excited. + +Root cause. Almost certainly a bug. Effects that big rarely exist outside truly novel features. Common bugs: exposure log fires only for treatment users (control is missing); metric model has a join error that double-counts treatment events; assignment is non-random and treatment is over-represented in heavy users. + +Fix. Audit the exposure log balance, the assignment ratio, and the metric model. Compare metric values to the historical baseline; if the treatment metric is higher than the all-users historical metric, something is wrong. + +Prevention. Skepticism about large effects. Run an SRM check before any analysis. Compare exposed-treatment metric to the historical baseline as a sanity check. + +--- + +## 5. Treatment users are different (sample ratio mismatch) + +Symptom. The exposure log shows 52,000 control users and 48,000 treatment users for a planned 50/50 split. The chi-squared test rejects the null at p < 0.001. + +Root cause. Assignment is not balanced. Possible causes: hash function bug, biased exposure logging, instrumentation that fires for one variant but not the other, eligibility check that runs differently across variants. + +Fix. Do not analyze the experiment. Find and fix the assignment bug. Restart. + +Prevention. Run the SRM check at the top of every analysis notebook. Abort with a clear error message if SRM is detected. Code review the exposure logging for both variants. + +--- + +## 6. Cannot reproduce yesterday's number + +Symptom. Yesterday's analysis showed 5.2 percent lift; today's shows 4.8 percent. Same query, same data, same notebook. The team cannot tell which is "the" answer. + +Root cause. Non-deterministic queries. Window functions without explicit `ORDER BY` produce different results on different runs. Sampling without a seed produces different samples. Floating-point aggregations on large datasets produce slight numeric differences depending on the order of summation. + +Fix. Make queries deterministic. Add explicit `ORDER BY` to window functions. Set a seed for any sampling. For floating-point precision, sum integers (cents) instead of floats; convert to dollars only at display time. + +Prevention. Code review for non-determinism. Save the query plan or the result set; compare across runs to detect drift early. + +--- + +## 7. Custom metric definition disagrees with board metric + +Symptom. The experiment says revenue lifted 5 percent; the board's revenue dashboard shows revenue flat. The team cannot tell which is right. + +Root cause. Two different SQL queries computing "revenue" with subtly different rules. The experiment query may include or exclude refunds, internal users, test orders, or specific time windows in different ways than the board. + +Fix. Align via shared dbt models. The board's revenue dashboard and the experiment's revenue metric reference the same `fct_orders` model with the same filters. + +Prevention. Schema discipline. Every metric used in an experiment is also used somewhere in the board or weekly review. Drift between the two is a code smell that should be caught at code review. + +--- + +## 8. We never finished the experiment + +Symptom. The experiment has been running for 8 weeks. The team has looked at the dashboard three times. Each time the result was inconclusive. The team keeps running it hoping for a clear answer. + +Root cause. No pre-registered stop criteria. The experiment was launched without a clear "we will stop when X" rule. The team is implicitly peeking and refusing to call it. + +Fix. Set a stop date and honor it. Analyze once on the stop date; report the result (which may be inconclusive). Document the inconclusive result and the design improvements needed for the next attempt. + +Prevention. Pre-register the sample size, the stop date, and the decision rule. Honor them. + +--- + +## 9. iOS users converted 3x in treatment + +Symptom. The aggregate treatment lift is small (1 percent), but the iOS segment shows a 3x lift. The team wants to ship the variant for iOS specifically. + +Root cause. Three possibilities. (a) Real segment effect: iOS users genuinely prefer the variant. (b) Instrumentation bug: iOS metric tracking differs from the rest. (c) Multiple comparisons: among many segments, one shows a large effect by chance. + +Fix. Investigate. Compare iOS metric tracking to other platforms (is the same event firing the same way?). Check the iOS sample size (if small, the 3x is high variance). Re-run the experiment with iOS as the primary segment if the team genuinely wants iOS-specific results. + +Prevention. Pre-register segments of interest. Apply multiple-comparisons correction across segments. Treat unexpected segment effects as hypotheses to confirm in a follow-up experiment, not as ship signals. + +--- + +## 10. Worked on phase 1, broke on phase 2 + +Symptom. Phase 1 of a staged rollout showed a clear positive lift. Phase 2 (broader audience) shows a much smaller or negative lift. The team is confused. + +Root cause. Simpson's paradox from cohort mix shift. Phase 1's audience is enriched in a segment where the treatment works well; phase 2 includes more of a segment where the treatment works poorly. The aggregate result reverses. + +Fix. Decompose by segment. The phase 2 result is the truer estimate (broader audience), but the phase 1 result tells you which segments respond. Consider a segment-specific rollout if the segment-level economics support it. + +Prevention. Run the experiment on the full target audience from the start, not on a phase-1 sub-audience. If staged rollout is operationally required, plan for the cohort mix shift in the analysis. + +--- + +## 11. Statistical significance but tiny effect + +Symptom. The p-value is 0.001. The lift is 0.3 percent. The experiment is statistically significant but the team is unsure whether to ship. + +Root cause. Large sample inflated the test's power. The test detects effects much smaller than the team's practical significance threshold. + +Fix. Apply the practical-significance check. If the team's threshold is "ship at 1 percent or larger," 0.3 percent does not meet the bar regardless of the p-value. Document the result; do not ship. + +Prevention. Pre-register the practical-significance threshold (the MDE) at experiment design time. Treat statistical significance below the MDE as inconclusive, not as a ship signal. + +--- + +## The pattern across all eleven + +Most warehouse-native experimentation failures share one root cause: the team did not pre-register enough discipline before the experiment started. Pre-registered sample size prevents underpowered analysis. Pre-registered exposure rule prevents the delayed-exposure trap. Pre-registered primary metric prevents multiple-comparisons fishing. Pre-registered stop criteria prevent the experiment-runs-forever pattern. + +The fix at the meta level. Treat each experiment as a contract. Before launching, write down the assignment unit, the salt, the exposure rule, the primary metric, the secondary metrics with multiple-comparisons correction, the sample size, the stop criteria, the practical-significance threshold. The contract is reviewed at launch. Deviations from the contract during the experiment require explicit re-registration. The discipline is the only thing that scales as the team runs more experiments. diff --git a/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md b/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md new file mode 100644 index 0000000..7ecfb76 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/metric-definitions-in-dbt.md @@ -0,0 +1,229 @@ +# Metric definitions in dbt + +dbt model patterns for experiment metrics. Reusing fct models. The exp_metrics namespace. Versioning. Aligning with board metrics. + +The principle. Define experiment metrics as dbt models so they are version-controlled, testable, and aligned with board metrics. The same source of truth for both surfaces eliminates the "experiment said X but the board says Y" problem. + +--- + +## The namespace pattern + +Three layers in a typical dbt project. + +- `stg_`: staging models. Light cleanup of source data. One per source table. +- `fct_` and `dim_`: marts models. Business-logic transformations. Joined and enriched data ready for consumption. +- `exp_metrics_`: experiment-shaped models. One row per assignment unit (typically `user_id`) with the metrics needed for analysis. + +Example structure. + +``` +models/ + staging/ + stg_orders.sql + stg_users.sql + stg_events.sql + marts/ + fct_orders.sql + fct_sessions.sql + dim_users.sql + experiments/ + exp_metrics_revenue.sql + exp_metrics_engagement.sql + exp_metrics_retention.sql +``` + +The `fct_` models feed both the board dashboard and the experiment metrics. The `exp_metrics_` models pivot to one row per user with the metrics joined or aggregated. + +--- + +## Pattern 1: revenue metric + +```sql +-- models/experiments/exp_metrics_revenue.sql +{{ config(materialized='table') }} + +WITH order_data AS ( + SELECT + user_id, + occurred_at, + amount_cents, + refunded + FROM {{ ref('fct_orders') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +) +SELECT + user_id, + SUM(CASE WHEN refunded THEN 0 ELSE amount_cents END) AS net_revenue_cents, + SUM(amount_cents) AS gross_revenue_cents, + COUNT() AS order_count, + MIN(occurred_at) AS first_order_at +FROM order_data +GROUP BY user_id; +``` + +Note the `var()` references for experiment start and end dates. The variables come from the dbt project's variables file or are passed at run time. + +The same `fct_orders` model feeds the board's revenue dashboard. Aligned definitions. + +--- + +## Pattern 2: engagement metric + +```sql +-- models/experiments/exp_metrics_engagement.sql +{{ config(materialized='table') }} + +WITH event_data AS ( + SELECT + user_id, + occurred_at, + event_name + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' + AND event_name IN ('content_created', 'content_edited', 'content_shared') +) +SELECT + user_id, + COUNT() AS engagement_event_count, + COUNT(DISTINCT DATE(occurred_at)) AS active_day_count, + SUM(CASE WHEN event_name = 'content_shared' THEN 1 ELSE 0 END) AS shares_count +FROM event_data +GROUP BY user_id; +``` + +The metric definition specifies exactly which events count as engagement. The board's "weekly active users" dashboard uses the same event filter via the same `fct_events` model. + +--- + +## Pattern 3: retention metric (bracket retention) + +```sql +-- models/experiments/exp_metrics_retention_w2.sql +{{ config(materialized='table') }} + +WITH user_first_activity AS ( + SELECT user_id, MIN(occurred_at) AS first_active_at + FROM {{ ref('fct_events') }} + WHERE occurred_at >= '{{ var("experiment_start") }}' + GROUP BY user_id +), +week2_activity AS ( + SELECT DISTINCT u.user_id + FROM user_first_activity u + JOIN {{ ref('fct_events') }} e ON e.user_id = u.user_id + WHERE e.occurred_at >= u.first_active_at + INTERVAL '7 days' + AND e.occurred_at < u.first_active_at + INTERVAL '14 days' +) +SELECT + u.user_id, + CASE WHEN w2.user_id IS NOT NULL THEN 1 ELSE 0 END AS retained_w2 +FROM user_first_activity u +LEFT JOIN week2_activity w2 USING (user_id); +``` + +Bracket retention (week 2 = days 7 to 13 from first activity) is more stable than N-day retention. The metric is binary: 1 if retained, 0 if not. + +--- + +## Pattern 4: ratio metric (delta method required) + +Some metrics are ratios (conversion rate, click-through rate). They require the delta method for correct variance estimation. + +```sql +-- models/experiments/exp_metrics_conversion.sql +{{ config(materialized='table') }} + +SELECT + user_id, + COUNT() AS impressions, + SUM(CASE WHEN converted THEN 1 ELSE 0 END) AS conversions +FROM {{ ref('fct_funnel_events') }} +WHERE occurred_at >= '{{ var("experiment_start") }}' + AND occurred_at < '{{ var("experiment_end") }}' +GROUP BY user_id; +``` + +The model produces numerator and denominator per user. The analysis layer (Python) computes the ratio and applies the delta method for variance. + +```python +# Per-user numerator and denominator +df = warehouse.query("SELECT FROM exp_metrics_conversion") + +# Group means +control = df[df.variant_id == 'control'] +treatment = df[df.variant_id == 'treatment'] + +# Conversion rate per group +control_rate = control.conversions.sum() / control.impressions.sum() +treatment_rate = treatment.conversions.sum() / treatment.impressions.sum() + +# Delta method variance (skipping the math here; see statistical-analysis-templates.md) +# ... +``` + +Do not compute the ratio per user and average it. That undercounts heavy users; the delta method is the correct treatment. + +--- + +## Versioning metric definitions + +Same versioning pattern as elsewhere. When the metric definition changes meaningfully, append `_v2`. + +``` +exp_metrics_revenue.sql <- v1, fires alongside v2 during transition +exp_metrics_revenue_v2.sql <- new semantics +``` + +The transition is the same: ship v2 alongside v1, migrate experiments to v2 over 90 days, deprecate v1. + +dbt's built-in versioning (the `models:` config with `versions:`) is also useful here; lets you serve both versions from the same model name with explicit version selection. + +--- + +## Aligning experiment metrics with board metrics + +The variance discipline. The same dbt model feeds both surfaces. + +If the board reports "monthly revenue" by summing `amount_cents` from `fct_orders` and excluding refunded orders, the experiment's revenue metric does the same. No special "experiment revenue" calculation that subtly differs. + +The mechanism. Both the board dashboard's SQL and the `exp_metrics_revenue` model reference the same `fct_orders` table with the same filters. dbt tests verify the table contains the expected rows. + +The check. When an experiment lands and the team reports "revenue lifted 5 percent in treatment," the team can pull the same numbers from the board and compare. If the board's revenue is flat or the experiment's lift is much larger than the board's revenue trend, the metric definitions disagree somewhere. Investigate. + +--- + +## Testing experiment metrics + +dbt tests on the metric models catch regressions. + +```yaml +# models/experiments/_experiments.yml +version: 2 + +models: + - name: exp_metrics_revenue + columns: + - name: user_id + tests: + - not_null + - unique + - name: net_revenue_cents + tests: + - not_null + - dbt_utils.expression_is_true: + expression: ">= 0" +``` + +The `unique` test on `user_id` confirms the model produces one row per user (no accidental duplicates from a bad join). The `>= 0` test confirms revenue is non-negative (refunds are subtracted, never additive). + +--- + +## Common metric-definition mistakes + +- Drift between board and experiment. "Experiment revenue" is computed differently from "board revenue." Align via shared dbt models. +- Wrong time window. The experiment runs for 14 days but the metric model includes 30 days of data. The control and treatment numbers are similar because the variant signal is diluted. +- One row per event instead of one row per user. Joining the metric to exposure on `user_id` produces a row explosion. Always aggregate to one row per user before joining. +- Forgetting to handle nulls. Users with no activity should appear with metric = 0, not be missing from the model. Use `LEFT JOIN` from exposure or include all eligible users in the metric model. +- Non-deterministic queries. Window functions without explicit `ORDER BY`, sampling without a random seed. The same query produces different numbers on different days. diff --git a/skills/data-warehouse-experimentation/references/power-analysis-calculations.md b/skills/data-warehouse-experimentation/references/power-analysis-calculations.md new file mode 100644 index 0000000..c7008f5 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/power-analysis-calculations.md @@ -0,0 +1,169 @@ +# Power analysis calculations + +Pre-experiment power analysis. MDE math. Sample size calculations. Calibrating effect-size assumptions from historical experiments. + +The principle. Most underpowered experiments come from optimistic effect-size assumptions. The team designs the experiment expecting a 10 percent lift; the actual effect is 1 percent, undetectable at the planned sample size; the experiment runs forever or stops with an inconclusive result. Power analysis prevents this by forcing a concrete decision about how big the lift needs to be before the experiment starts. + +--- + +## The four parameters + +Power analysis ties together four numbers. Fix any three; the fourth is determined. + +1. Effect size (or MDE, minimum detectable effect). The smallest lift the experiment can reliably detect. Expressed as a relative percentage, an absolute difference, or Cohen's d (effect size in standard deviations). +2. Sample size per arm. Number of users in each variant. +3. Alpha (significance level). Default 0.05. The false-positive rate. +4. Power. Default 0.8. One minus the false-negative rate. The probability of detecting a real effect. + +The standard practice. Fix alpha at 0.05, power at 0.8, decide on either the MDE (and solve for sample size) or the sample size (and solve for MDE). + +--- + +## Solving for sample size given MDE + +```python +from statsmodels.stats.power import tt_ind_solve_power + +# Continuous metric, two-sample t-test +# Cohen's d = (mean_treatment - mean_control) / pooled_std + +cohens_d = 0.05 # 5 percent of one standard deviation + +n_per_arm = tt_ind_solve_power( + effect_size=cohens_d, + nobs1=None, + alpha=0.05, + power=0.8, + ratio=1.0 # equal sample sizes per arm +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a Cohen's d of 0.05 (small effect), expect roughly 6,300 users per arm. For 0.1 (still small), roughly 1,600 per arm. For 0.2 (medium), roughly 400 per arm. + +### Solving for proportions + +```python +from statsmodels.stats.power import zt_ind_solve_power + +# Binary metric, proportions test +# baseline conversion rate = 5 percent; target lift = 5 percent relative +baseline_p = 0.05 +relative_lift = 0.05 +treatment_p = baseline_p * (1 + relative_lift) + +# Cohen's h for proportions +import numpy as np +def cohens_h(p1, p2): + return 2 * np.arcsin(np.sqrt(p1)) - 2 * np.arcsin(np.sqrt(p2)) + +h = cohens_h(treatment_p, baseline_p) + +n_per_arm = zt_ind_solve_power( + effect_size=h, + nobs1=None, + alpha=0.05, + power=0.8 +) +print(f"Required sample size per arm: {n_per_arm:.0f}") +``` + +For a 5 percent relative lift on a 5 percent baseline conversion rate, expect roughly 60,000 users per arm. Small relative lifts on small baselines need very large samples. + +--- + +## Solving for MDE given sample size + +The reverse calculation. Given the available sample (e.g., 8,000 users per arm), what is the smallest effect the experiment can detect? + +```python +from statsmodels.stats.power import tt_ind_solve_power + +mde_cohens_d = tt_ind_solve_power( + effect_size=None, + nobs1=8000, + alpha=0.05, + power=0.8, + ratio=1.0 +) +print(f"MDE in Cohen's d: {mde_cohens_d:.4f}") + +# Convert to relative MDE assuming the metric's standard deviation +metric_std = 50.0 # in cents, for example +metric_mean = 200.0 +mde_absolute = mde_cohens_d * metric_std +mde_relative = mde_absolute / metric_mean +print(f"MDE absolute: {mde_absolute:.2f}") +print(f"MDE relative: {mde_relative:.2%}") +``` + +If the available sample yields an MDE of 8 percent and the team expects only a 2 percent lift, the experiment is underpowered. Either secure more sample (run longer or expand the audience) or accept that the experiment will produce an inconclusive result. + +--- + +## Calibrating effect-size assumptions from historical experiments + +The most common power-analysis mistake is over-optimistic effect-size estimates. Three patterns help calibrate. + +### Pattern 1: pull the historical distribution + +For the last 30 (or however many) experiments, pull the observed lifts. Compute the median, 25th percentile, and 75th percentile. + +```python +df = warehouse.query(""" + SELECT experiment_id, observed_relative_lift + FROM experiment_results + WHERE shipped = true + ORDER BY ended_at DESC + LIMIT 30 +""") + +print(f"Median observed lift: {df.observed_relative_lift.median():.2%}") +print(f"P25: {df.observed_relative_lift.quantile(0.25):.2%}") +print(f"P75: {df.observed_relative_lift.quantile(0.75):.2%}") +``` + +The median observed lift is the realistic expectation for the next experiment. If past experiments show a median lift of 1 percent, planning for a 5 percent lift on the next experiment is optimistic. + +### Pattern 2: stratify by experiment type + +Pricing experiments often produce larger lifts than UI experiments. Onboarding experiments often produce larger lifts than feature-discovery experiments. Pull the distribution by experiment type to set type-specific expectations. + +### Pattern 3: ask the team about prior experiments they remember + +The "we usually see X" estimate from team members is anchored on memorable experiments (the wins, the disasters). Compare against the actual distribution; the memorable estimate is usually too high. + +The honest conversation. "Our last 30 experiments had a median observed lift of 0.5 percent. We are planning this experiment for a 5 percent MDE. Either the experiment is going to produce an inconclusive result, or we are expecting an unusually large effect. Which is it?" + +--- + +## When the math says "we cannot run this" + +Three escalation paths when the available sample is insufficient. + +1. Run longer. The default. If the experiment needs 60,000 users per arm and you have 10,000 per week, plan for a 6-week run. Document the duration before starting. +2. Expand the audience. If the experiment is targeting only paid users (10 percent of the user base), consider running on all users. The result is generalizable to a broader population, but the intervention may need to work for the broader population too. +3. Accept inconclusive. Some experiments cannot be powered with the available sample. Document the MDE; design the experiment to detect a larger effect or accept that it will be inconclusive. The discipline of saying "we cannot reliably answer this with our sample" is hard but honest. + +--- + +## The underpowered-experiment cost + +A team running 12 experiments per quarter, 4 of which are underpowered. The cost. + +- Underpowered experiments produce inconclusive results. The team learns nothing. +- Engineering and design effort spent on the experiment is wasted. +- Stakeholders treat inconclusive as "no effect"; later experiments that would have shown the same effect at a larger sample also produce inconclusive, reinforcing the false belief that no effect exists. +- The team's experimentation discipline degrades because the visible track record looks bad. + +Power analysis at the design stage prevents most of this. The cost is 30 minutes of work; the benefit is avoiding multi-week runs of experiments that cannot answer the question. + +--- + +## Common power-analysis mistakes + +- Optimistic effect-size assumption. Plan for a 10 percent lift; observe a 1 percent lift. The experiment is 100x underpowered. +- Forgetting variance from the historical metric. Power calculations use Cohen's d, which depends on the metric's standard deviation. A high-variance metric requires a larger sample for the same MDE than a low-variance metric. +- Computing power on aggregate when the assignment unit is something else. If the assignment unit is user but the metric is per-event, the per-event variance includes within-user correlation. Use the user-level variance for the calculation. +- Skipping the calculation for "small" experiments. "We will just see what happens" is the path to a quarter of inconclusive experiments. +- Confusing statistical significance with practical significance. A p-value below 0.05 with a 0.3 percent effect on a 100,000-user experiment is statistically significant but may not be worth shipping. Use the MDE as the practical-significance threshold; a 0.3 percent effect is below most teams' MDE. diff --git a/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md b/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md new file mode 100644 index 0000000..401eb49 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/sequential-testing-patterns.md @@ -0,0 +1,148 @@ +# Sequential testing patterns + +mSPRT, confidence sequences, group sequential designs. Plus an honest framing on when to peek. + +The principle. Looking at experiment results before completion (peeking) inflates the false-positive rate. The naive solution is "do not peek." The practical solution is sequential testing methods that allow valid early stopping. The honest middle ground: if you do not understand the math, do not peek. + +--- + +## The peeking problem + +The standard t-test assumes a fixed sample size pre-registered before the experiment runs. When the team peeks early, the test is implicitly running multiple times; some of those peeks will hit p < 0.05 by chance even when no effect exists. + +A team that peeks daily on a 4-week experiment runs the test roughly 28 times. The implicit false-positive rate becomes much higher than the nominal 5 percent. Estimates suggest 30 percent or more in this case; the experiment is more likely to show a fake significant result than a real one. + +The four solutions. + +1. Do not peek. Pre-register the sample size; analyze once. +2. mSPRT. Always-valid p-values that survive peeking. +3. Confidence sequences. Always-valid confidence intervals via the Howard et al construction. +4. Group sequential designs. Pre-specified interim analyses with calibrated alpha-spending. + +Each solution requires implementation discipline. Incorrect implementation is worse than no peeking solution at all (the team thinks the math is correct and ships based on inflated false-positives). + +--- + +## mSPRT (mixture Sequential Probability Ratio Test) + +The most commonly deployed sequential testing method. Used by Optimizely, Statsig. + +The intuition. Compute a Bayes-factor-like statistic that updates as data arrives. The statistic crosses a fixed threshold when the evidence is strong enough to reject the null; it never crosses by chance under the null (with the correct calibration). + +### Python implementation sketch + +```python +import numpy as np + +def mSPRT(treatment, control, prior_var=1.0, alpha=0.05): + """ + Mixture SPRT for two-sample mean difference. + Returns the always-valid p-value at the current sample. + """ + n_t = len(treatment) + n_c = len(control) + diff = treatment.mean() - control.mean() + pooled_var = (treatment.var() / n_t + control.var() / n_c) + se = np.sqrt(pooled_var) + + # Test statistic + z = diff / se + + # Mixture prior with variance prior_var + # Always-valid p-value via the mixture-likelihood ratio + n_eff = (n_t * n_c) / (n_t + n_c) + weight = np.sqrt(prior_var / (prior_var + 1.0 / n_eff)) + log_lr = 0.5 * z*2 (1 - weight*2) - 0.5 np.log(1.0 / weight2) + p_always_valid = min(1.0, np.exp(-log_lr)) + + return p_always_valid +``` + +Note: the implementation above is a sketch for illustration. Production implementations should use a peer-reviewed library or expert review. Do not deploy this verbatim. + +The honest version. Use a maintained library (`sequential` in R, custom Python adapted from peer-reviewed papers like Johari et al 2017). Have a statistician on the team review the implementation. + +--- + +## Confidence sequences (Always-Valid Inference) + +The Howard et al construction. Confidence intervals that are valid at any sample size; the team can peek arbitrarily often without inflating the false-positive rate. + +The math is more involved than mSPRT. Useful when the team needs not just always-valid p-values but always-valid confidence intervals (effect size with uncertainty). + +References. + +- Howard, Ramdas, McAuliffe, Sekhon (2021), "Time-uniform, nonparametric, nonasymptotic confidence sequences." +- Code: `sequential` package in R, or custom Python. + +For most warehouse-native teams, mSPRT is enough. Confidence sequences are for teams with a statistician who has read the paper and validated the implementation. + +--- + +## Group sequential designs + +The classical frequentist approach. Pre-specified interim analysis points (e.g., at 25 percent, 50 percent, 75 percent of the planned sample) with calibrated alpha-spending boundaries. + +The most common boundary is O'Brien-Fleming. Conservative early (high effect size required to stop early); lenient late (lower effect size required to stop at the final analysis). + +```python +# Hypothetical O'Brien-Fleming boundaries for 4 interim analyses +# Z-values; if observed Z exceeds, reject the null and stop +boundaries = { + 0.25: 4.05, + 0.50: 2.86, + 0.75: 2.34, + 1.00: 2.02, +} +``` + +The discipline. + +1. Pre-register the interim analysis points and the boundary values. +2. At each interim point, compute the test statistic. +3. If the statistic exceeds the boundary, stop the experiment and reject the null. +4. If the statistic does not exceed any boundary by the final analysis, fail to reject (treat as inconclusive or as "no effect detected"). + +Group sequential designs require commitment up front. Adding interim analyses after the experiment starts is post-hoc peeking and inflates the false-positive rate. + +--- + +## When to peek and when not to + +Three scenarios. + +### Scenario 1: small team, no statistician, simple experiments + +Do not peek. Pre-register the sample size; analyze once at completion. The discipline is simpler than implementing sequential testing correctly, and the cost (running for the full pre-registered duration) is usually small. + +### Scenario 2: high-volume team running many experiments, has a statistician + +Implement mSPRT. The peeking is operationally useful (early stops free up the testing infrastructure for the next experiment) and the math is well-understood. Train the team on the implementation; review periodically. + +### Scenario 3: regulated industry, strong audit requirements + +Group sequential design. Pre-registered interim analyses with calibrated boundaries. The audit trail is clean: every interim analysis was specified before the experiment started; the boundaries are reproducible from the design document. + +--- + +## Common sequential testing mistakes + +- Implementing mSPRT without understanding the math. A wrong implementation produces inflated false-positives that the team trusts. Worse than no peeking. +- Adding interim analyses after the experiment starts. Group sequential designs require pre-registration. Post-hoc interim analyses are just peeking. +- Mixing methods. Compute mSPRT for some peeks and a standard t-test for others. The latter inflates false-positives; the former does not. Pick one method per experiment and stick to it. +- Using mSPRT but reporting the standard p-value. The mSPRT p-value is always-valid; the standard p-value is not. Reporting the standard p-value while peeking is the same as not using mSPRT at all. +- Stopping early on a tiny effect.** mSPRT may show "significant" before the team has enough evidence on practical significance. The effect is real but small; shipping it may not be worth the engineering complexity. + +--- + +## The honest recommendation + +For most warehouse-native experimentation teams, the right answer is "do not peek." + +- Pre-register the sample size based on power analysis. +- Run to the pre-registered sample. +- Analyze once at completion. + +The cost is some early stops the team would have liked. The benefit is no implementation risk in sequential testing math, no false-positives from mis-implemented peeking, and a clean audit trail. + +Move to sequential testing when the team has the statistical expertise to implement correctly and the operational pressure to peek (high-volume infrastructure where early stops materially affect the next experiment's timeline). diff --git a/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md b/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md new file mode 100644 index 0000000..c1b1137 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/statistical-analysis-templates.md @@ -0,0 +1,241 @@ +# Statistical analysis templates + +SQL and Python templates for the most common warehouse-native analyses. t-test, proportions test, Mann-Whitney, bootstrap. Plus the recommended notebook structure. + +--- + +## Welch's t-test (continuous metrics) + +The default for continuous metrics where group variances may differ. + +### SQL + +```sql +WITH joined AS ( + SELECT e.variant_id, m.net_revenue_cents + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +), +metric_by_variant AS ( + SELECT + variant_id, + COUNT() AS n, + AVG(COALESCE(net_revenue_cents, 0)) AS mean, + VAR_SAMP(COALESCE(net_revenue_cents, 0)) AS variance + FROM joined + GROUP BY variant_id +) +SELECT + control.mean AS control_mean, + treatment.mean AS treatment_mean, + treatment.mean - control.mean AS absolute_lift, + (treatment.mean - control.mean) / NULLIF(control.mean, 0) AS relative_lift, + -- Welch's t-statistic + (treatment.mean - control.mean) / + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS t_statistic, + -- Standard error of the mean difference + SQRT(treatment.variance / treatment.n + control.variance / control.n) + AS se, + control.n AS control_n, + treatment.n AS treatment_n +FROM + (SELECT FROM metric_by_variant WHERE variant_id = 'control') control, + (SELECT * FROM metric_by_variant WHERE variant_id = 'treatment') treatment; +``` + +The query returns the t-statistic and standard error. Convert to p-value and confidence interval via a UDF or in Python. + +### Python + +```python +import pandas as pd +from scipy import stats +import numpy as np + +df = warehouse.query(""" + SELECT e.variant_id, COALESCE(m.net_revenue_cents, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +t_stat, p_value = stats.ttest_ind(treatment, control, equal_var=False) + +# 95 percent confidence interval on the mean difference +diff = treatment.mean() - control.mean() +se = np.sqrt(treatment.var() / len(treatment) + control.var() / len(control)) +ci_low, ci_high = diff - 1.96 * se, diff + 1.96 * se + +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +print(f"t = {t_stat:.3f}, p = {p_value:.4f}") +``` + +--- + +## Proportions test (binary metrics) + +For binary outcomes (converted vs not, retained vs not). + +### Python + +```python +from statsmodels.stats.proportion import proportions_ztest, proportion_confint + +# Counts and totals per variant +control_conv = 1240 +control_n = 25000 +treatment_conv = 1390 +treatment_n = 25000 + +# Z-test +z_stat, p_value = proportions_ztest( + [control_conv, treatment_conv], + [control_n, treatment_n] +) + +# Confidence intervals on each proportion +control_ci = proportion_confint(control_conv, control_n, method='wilson') +treatment_ci = proportion_confint(treatment_conv, treatment_n, method='wilson') + +# Lift +control_rate = control_conv / control_n +treatment_rate = treatment_conv / treatment_n +relative_lift = (treatment_rate - control_rate) / control_rate + +print(f"Control: {control_rate:.4f}, CI: {control_ci}") +print(f"Treatment: {treatment_rate:.4f}, CI: {treatment_ci}") +print(f"Relative lift: {relative_lift:.2%}") +print(f"z = {z_stat:.3f}, p = {p_value:.4f}") +``` + +The Wilson score interval is more accurate than the normal approximation for small samples or extreme proportions. + +--- + +## Mann-Whitney U test (non-parametric) + +For metrics with skewed distributions (revenue, time-on-site) where the t-test's normal-distribution assumption is violated. + +```python +from scipy.stats import mannwhitneyu + +control = df[df.variant_id == 'control'].metric +treatment = df[df.variant_id == 'treatment'].metric + +u_stat, p_value = mannwhitneyu(treatment, control, alternative='two-sided') + +# Mann-Whitney tests stochastic dominance, not the mean. +# Report median lift alongside. +median_lift = treatment.median() - control.median() +print(f"Median lift: {median_lift:.2f}") +print(f"U = {u_stat:.0f}, p = {p_value:.4f}") +``` + +The Mann-Whitney U test is the standard non-parametric alternative. Use when the metric distribution is skewed and the t-test's assumption fails. + +--- + +## Bootstrap confidence interval + +For metrics where the analytic distribution is unclear or unusual (e.g., retention bracket, complex composite metrics). + +```python +import numpy as np + +def bootstrap_ci(treatment, control, n_iterations=10000, alpha=0.05): + diffs = [] + for _ in range(n_iterations): + t_sample = treatment.sample(n=len(treatment), replace=True) + c_sample = control.sample(n=len(control), replace=True) + diffs.append(t_sample.mean() - c_sample.mean()) + diffs = np.array(diffs) + return np.quantile(diffs, [alpha / 2, 1 - alpha / 2]) + +ci_low, ci_high = bootstrap_ci(treatment, control) +diff = treatment.mean() - control.mean() +print(f"Lift: {diff:.2f} (95% CI: [{ci_low:.2f}, {ci_high:.2f}])") +``` + +10,000 bootstrap iterations is the standard. More iterations produce tighter intervals at the cost of compute time. + +--- + +## Notebook structure + +The recommended structure for an experiment analysis notebook. + +### Cell 1: parameters + +```python +EXPERIMENT_ID = 'exp_button_color_v1' +EXPERIMENT_START = '2026-04-01' +EXPERIMENT_END = '2026-04-15' +PRIMARY_METRIC = 'net_revenue_cents' +SECONDARY_METRICS = ['order_count', 'session_count'] +ALPHA = 0.05 +``` + +Parameters at the top. Parametrize the notebook so the same template runs for any experiment. + +### Cell 2: SRM check + +```python +df_exposures = warehouse.query(f""" + SELECT variant_id, COUNT() AS n + FROM exposures + WHERE experiment_id = '{EXPERIMENT_ID}' + GROUP BY variant_id +""") + +# Chi-squared test against expected ratio +from scipy.stats import chi2_contingency +observed = df_exposures.n.values +expected = [observed.sum() / len(observed)] len(observed) +chi2, p, _, _ = chi2_contingency([observed, expected]) +assert p > 0.01, f"SRM detected (p = {p:.4f}). Aborting analysis." +print(f"SRM check passed (p = {p:.4f})") +``` + +Abort the notebook if SRM is detected. Do not proceed to metric analysis with broken assignment. + +### Cell 3: pull data + +```python +df = warehouse.query(f""" + SELECT + e.variant_id, + e.user_id, + COALESCE(m.{PRIMARY_METRIC}, 0) AS metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + WHERE e.experiment_id = '{EXPERIMENT_ID}' +""") +``` + +### Cell 4: primary analysis + +t-test, proportions test, or bootstrap depending on the metric. + +### Cell 5: secondary metrics + +Loop over secondary metrics; apply Bonferroni correction for multiple comparisons. + +### Cell 6: written-up decision + +A markdown cell with the conclusion. Ship, kill, or inconclusive. Include the lift, the CI, the p-value, the SRM result, and any caveats. This cell is the deliverable. + +--- + +## Common analysis mistakes + +- No SRM check. Analyzing an experiment with broken assignment produces meaningless numbers. +- Equal-variance t-test on unequal-variance data. Use Welch's (`equal_var=False`) by default. +- t-test on heavily skewed metrics. Use bootstrap or Mann-Whitney instead. +- Per-user ratios for ratio metrics. Heavy users get under-weighted. Use the delta method. +- Multiple secondary metrics without correction. With 5 secondary metrics at alpha 0.05, expect a 25 percent chance of a false positive somewhere. Bonferroni or BH correction. +- Stop-on-significance peeking. Inflates the false-positive rate. Either pre-register the sample size or use a sequential testing method correctly. diff --git a/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md b/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md new file mode 100644 index 0000000..daa2693 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/variance-reduction-techniques.md @@ -0,0 +1,179 @@ +# Variance reduction techniques + +CUPED is the most powerful variance reduction technique for warehouse-native experimentation. Stratification, regression adjustment, and doubly robust estimation cover specific cases. + +The principle. Variance reduction makes confidence intervals narrower at the same sample size. A 30 to 50 percent variance reduction (typical with CUPED on engagement metrics) is equivalent to running the experiment 1.5 to 2x longer for the same statistical power. Worth the engineering investment for any team running 5+ experiments per quarter. + +--- + +## CUPED: the workhorse + +CUPED stands for Controlled-experiment Using Pre-Experiment Data. Originally from Microsoft (Deng et al, 2013). + +The intuition. If you can predict a user's metric behavior from pre-experiment data (their behavior before the experiment started), you can subtract that prediction from the metric, leaving a smaller residual to test on. The mean is preserved (CUPED does not change the point estimate of the lift), but the variance shrinks because predictable variance has been removed. + +### The math + +For each user, compute a pre-experiment covariate (e.g., revenue in the 28 days before the experiment started). Call this `pre_metric`. The CUPED-adjusted metric is: + +``` +adjusted_metric = metric - theta * (pre_metric - mean(pre_metric)) +``` + +where `theta` is the regression coefficient of `metric` on `pre_metric`: + +``` +theta = cov(metric, pre_metric) / var(pre_metric) +``` + +Run the t-test on `adjusted_metric` instead of `metric`. The mean difference between treatment and control is preserved; the variance is reduced. + +### Python implementation + +```python +import pandas as pd +import numpy as np + +# df has columns: user_id, variant_id, metric, pre_metric +df = warehouse.query(""" + SELECT + e.user_id, + e.variant_id, + COALESCE(m.net_revenue_cents, 0) AS metric, + COALESCE(p.pre_net_revenue_cents, 0) AS pre_metric + FROM exposures e + LEFT JOIN exp_metrics_revenue m USING (user_id) + LEFT JOIN pre_experiment_revenue p USING (user_id) + WHERE e.experiment_id = 'exp_button_color_v1' +""") + +# Compute theta from the entire dataset (control and treatment combined) +theta = np.cov(df.metric, df.pre_metric)[0, 1] / np.var(df.pre_metric) + +# CUPED-adjusted metric +df['adjusted_metric'] = df.metric - theta * (df.pre_metric - df.pre_metric.mean()) + +# Run t-test on the adjusted metric +from scipy import stats +control_adj = df[df.variant_id == 'control'].adjusted_metric +treatment_adj = df[df.variant_id == 'treatment'].adjusted_metric +t_stat, p_value = stats.ttest_ind(treatment_adj, control_adj, equal_var=False) + +# Compare to unadjusted variance +unadjusted_var = df.metric.var() +adjusted_var = df.adjusted_metric.var() +variance_reduction = 1 - adjusted_var / unadjusted_var +print(f"Variance reduction: {variance_reduction:.1%}") +``` + +### When CUPED works well + +- Engagement metrics with strong autocorrelation. Pre-experiment activity strongly predicts in-experiment activity. +- Revenue metrics on consumer products with repeat customers. +- Retention metrics where past retention predicts future retention. + +### When CUPED works poorly + +- New users (no pre-experiment data). They drop out of the analysis or are imputed. +- Metrics with weak temporal autocorrelation. The pre-period does not predict the in-period. +- Metrics that are zero for most users (highly skewed binary outcomes). The t-test's normal-distribution assumption fails; CUPED on top inherits the failure. + +### Pre-experiment window length + +A 28-day pre-experiment window is the typical default. Longer windows (60 to 90 days) capture more of the user's behavior pattern and may reduce variance more, but also reduce eligibility (users who joined within the window have no pre-period). + +The discipline. Pre-register the pre-period length when designing the experiment. Do not change it after looking at results. + +--- + +## Stratification + +Slice the analysis by a pre-experiment covariate (segment, region, device) and pool the per-stratum estimates. Useful when the covariate is strongly predictive of the metric. + +```python +# Stratify by device +strata = df.device_type.unique() +stratum_estimates = [] +for s in strata: + sub = df[df.device_type == s] + diff = sub[sub.variant_id == 'treatment'].metric.mean() - sub[sub.variant_id == 'control'].metric.mean() + stratum_estimates.append({ + 'stratum': s, + 'n': len(sub), + 'diff': diff, + }) + +# Pool: weighted average by stratum size +total_n = sum(s['n'] for s in stratum_estimates) +pooled_diff = sum(s['diff'] * s['n'] / total_n for s in stratum_estimates) +``` + +The variance of the pooled estimate is lower than the unpooled t-test when the strata have different baseline metrics (the across-stratum variance is removed). + +The downside. Stratification by too many covariates produces small per-stratum samples, which inflates per-stratum variance. Use stratification on one or two strong predictors, not on every covariate available. + +--- + +## Regression adjustment (covariate adjustment via OLS) + +A generalization of CUPED to multiple covariates. + +```python +import statsmodels.api as sm + +# X: covariates (pre_metric, device_type encoded, region encoded) +X = pd.get_dummies(df[['pre_metric', 'device_type', 'region']], drop_first=True) +X['variant_treatment'] = (df.variant_id == 'treatment').astype(int) +X = sm.add_constant(X) +y = df.metric + +# OLS regression +model = sm.OLS(y, X).fit() +print(model.summary()) + +# The coefficient on 'variant_treatment' is the adjusted effect estimate. +# Its standard error is typically smaller than the unadjusted t-test SE. +``` + +Regression adjustment is more flexible than CUPED but requires more care: collinearity among covariates, model misspecification, and overfitting on small samples are all possible failure modes. + +For most warehouse-native experiments, CUPED with a single pre-period covariate is enough. Regression adjustment with multiple covariates is for edge cases. + +--- + +## Doubly robust estimation + +Useful in observational and quasi-experimental settings where randomization was imperfect (geo experiments, switchback designs, natural experiments). + +The intuition. Combine an outcome model (predict the metric from covariates) with a propensity-score model (predict the probability of treatment from covariates). The combined estimator is unbiased if either of the two models is correct (hence "doubly robust estimation"). + +For the standard A/B test where assignment is random, doubly robust estimation does not help. The benefit is in observational settings where the assignment mechanism may be confounded. + +The implementation requires `causalml`, `dowhy`, or a custom implementation. Outside the scope of the typical experiment notebook; pointer to the academic literature for full treatment. + +References. + +- Bang and Robins (2005), "Doubly Robust Estimation in Missing Data and Causal Inference Models." +- Funk et al. (2011), "Doubly Robust Estimation of Causal Effects." + +--- + +## When to invest in variance reduction + +Three signals. + +1. Running 5+ experiments per quarter. The amortized engineering investment in CUPED pays back across many experiments. +2. The team is power-constrained. Experiments routinely run too long or hit inconclusive results because of insufficient sample size. CUPED extends the effective sample size by 30 to 50 percent. +3. The team has data scientists who understand the math. CUPED is straightforward but easy to implement incorrectly (theta computed on the wrong subset, pre-period window misaligned, regression diagnostics ignored). Without someone on the team who can audit the implementation, the variance reduction may not be real. + +The order of investment. CUPED first; it is the highest ROI. Stratification second; useful for one or two strong predictors. Regression adjustment third; for edge cases where multiple covariates matter. Doubly robust estimation last; for genuine quasi-experiments. + +--- + +## Common variance reduction mistakes + +- Computing theta on treatment data only. Theta should be computed on the combined dataset (control plus treatment) for unbiased estimation. Computing on treatment alone re-introduces the bias CUPED is trying to remove. +- Pre-period contamination. The pre-period overlaps with the experiment period. Users in the experiment have already been exposed when their "pre-period" metric is measured. The pre-metric is not actually pre. +- CUPED on heavily skewed binary metrics. CUPED reduces variance but does not change the metric's distribution. A binary metric where 99 percent of users are 0 is still skewed after CUPED; the t-test is still misspecified. +- Stratification on a post-experiment covariate. The covariate must be measured before the experiment, otherwise the stratification creates selection bias. Use only pre-experiment covariates for stratification. +- Forgetting to validate that variance actually decreased. Run both adjusted and unadjusted analyses; verify the adjusted variance is smaller. If it is not, CUPED is not helping for this metric and pre-period. diff --git a/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md b/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md new file mode 100644 index 0000000..21e0222 --- /dev/null +++ b/skills/data-warehouse-experimentation/references/warehouse-vs-platform-decision.md @@ -0,0 +1,145 @@ +# Warehouse vs platform decision + +Side-by-side comparison. Cost considerations at scale. Hybrid patterns. Migration patterns. Decision tree. + +The principle. Both operational models are valid. The right choice depends on team strength, volume, custom-metric needs, and how much engineering time you are willing to invest in experimentation infrastructure. + +--- + +## Side-by-side comparison + +\| Dimension \| Platform (Statsig, Optimizely, etc.) \| Warehouse-native \| +\|---\|---\|---\| +\| Time to first experiment \| Hours to days \| Days to weeks \| +\| Custom metric depth \| Limited to platform's metric library \| Anything you can write in SQL \| +\| Custom segmentation \| Platform-specific filters \| dbt models compose without limit \| +\| Cost shape \| Per-MAU or per-event subscription \| Existing warehouse compute \| +\| Engineering investment \| Low \| Medium to high \| +\| Sequential testing \| Out of the box \| Build it yourself or skip \| +\| Frontend visual editing \| Optimizely, VWO ship this \| Not applicable \| +\| Mobile SDK assignment \| Out of the box \| Build it yourself \| +\| Trust and audit \| Platform's math is a black box \| Every step is auditable SQL \| +\| Iteration speed on metric definitions \| Platform release cadence \| dbt deploy cadence \| +\| Ecosystem integration \| Platform's connectors \| Warehouse already has the data \| + +--- + +## Cost considerations at scale + +Approximate costs as of 2025-2026. Verify with vendor pricing. + +### 10K MAU + +- Platform (mid-tier): $0 to $500 per month. Free tiers from PostHog, Statsig, Amplitude cover this. +- Warehouse-native: warehouse compute already paid for. Engineering time cost: 1 to 2 weeks of a data engineer's time to set up infrastructure. + +Recommendation. Platform. The engineering time on warehouse-native at this scale does not pay back. + +### 100K MAU + +- Platform (mid-tier): $1K to $10K per month. Statsig, PostHog paid tiers; Optimizely contract. +- Warehouse-native: same warehouse compute; engineering time amortized over more experiments. + +Recommendation. Either. Depends on team strength and custom-metric needs. Many teams stay on a platform; some graduate to warehouse-native. + +### 1M MAU + +- Platform: $10K to $80K per month, often more for enterprise contracts. Optimizely Enterprise can hit $200K+ per year. +- Warehouse-native: same warehouse compute. The engineering investment pays back at this scale. + +Recommendation. Warehouse-native is increasingly attractive. Many enterprise data teams run warehouse-native primary, with a platform for specific use cases (frontend visual experiments). + +### 10M+ MAU + +- Platform: enterprise contracts at $200K to $1M+ per year. +- Warehouse-native: dominant pattern at this scale. Custom infrastructure plus dbt plus Python notebooks. + +Recommendation. Warehouse-native, often with a thin platform for fast frontend iteration. + +--- + +## Hybrid patterns + +Three common hybrid patterns. + +### Pattern 1: platform for product, warehouse-native for analytics + +The platform handles assignment and exposure for product experiments. The warehouse handles analysis for the same experiments by reading the platform's exposure data. + +Why. The platform's analysis is fine for standard cases; warehouse-native analysis allows custom metrics and segmentation the platform cannot express. + +Operational shape. The platform's exposure events flow to the warehouse (typically via webhook or scheduled export). dbt models compute custom metrics; the analyst runs the t-test in Python against the joined data. + +### Pattern 2: warehouse-native for backend, platform for frontend + +Warehouse-native handles backend experiments where assignment is server-side (pricing, recommendations, ML model variants). The platform handles frontend visual experiments (button colors, copy, layout). + +Why. Frontend visual experiments benefit from the platform's WYSIWYG editor and script-tag injection. Backend experiments benefit from warehouse-native's metric flexibility. + +Operational shape. Two separate experiment registries. Each team picks the right tool for the experiment type. + +### Pattern 3: platform for fast iteration, warehouse-native for hard cases + +The platform handles experiments where time-to-result matters more than custom depth. Warehouse-native handles experiments where the platform cannot express the metric. + +Why. Most experiments are standard; the platform is faster. The 10 percent that are not standard need the warehouse. + +Operational shape. Default to platform; escalate to warehouse-native when the platform fails to support the experiment design. + +--- + +## Migration patterns + +### Platform to warehouse-native + +Triggered by cost (the platform bill became a budget item) or capability (the platform cannot handle a specific experiment design that matters). Typical effort: 6 to 12 engineer-weeks for the first warehouse-native experiment with full infrastructure; later experiments amortize the investment. + +Steps. Build the assignment hash function. Build the exposure logging discipline. Define the first metric in dbt. Run a parallel experiment on the platform and warehouse-native; verify results match within statistical noise. Migrate experiments one at a time; retire the platform when the last in-flight experiment completes. + +### Warehouse-native to platform + +Triggered by team contraction (the data engineer who built the infrastructure left) or by velocity needs (experiments are taking too long to set up). Typical effort: 2 to 4 engineer-weeks; the platform handles the heavy lifting. + +Steps. Pick the platform. Wire up assignment and exposure. Migrate the metric library to the platform's format. Run the first experiment on the platform; verify results align with what warehouse-native would have produced. + +The frequent reverse migration. Companies that move to warehouse-native and discover the engineering investment is too much. The migration back is usually faster than the migration out. + +--- + +## Decision tree + +``` +Is your team running 5+ experiments per quarter? +├── No → Platform. Warehouse-native does not pay back at low volume. +└── Yes → Continue. + │ + Do you have a data engineer and a data scientist? + ├── No → Platform. Warehouse-native requires both roles. + └── Yes → Continue. + │ + Are your experiments primarily frontend visual? + ├── Yes → Platform (Optimizely, VWO). Warehouse-native cannot match. + └── No → Continue. + │ + Do you need custom metrics the platform cannot express? + ├── Yes → Warehouse-native. The custom metric is the use case. + └── No → Continue. + │ + Is the platform bill exceeding 10x the cost of the engineering time? + ├── Yes → Warehouse-native. The math justifies it. + └── No → Platform. The simplicity is worth the cost. +``` + +The defaults. New teams: platform. Mature teams with strong data infrastructure and high volume: hybrid or warehouse-native primary. The decision is never permanent; revisit annually. + +--- + +## When the math is wrong + +Two situations where teams misjudge the build-vs-buy. + +Underestimating engineering cost. "We can build this in a week" rarely holds. The first experiment takes weeks; the second takes days; the long tail of pitfalls (CUPED, sequential testing, SRM checks, dashboard reconciliation) adds up to months of engineering investment. Budget realistically. + +Overestimating platform limitations. "The platform cannot handle our metric" is sometimes true and sometimes a workflow problem. Verify with the vendor; many platforms have advanced features (Cortex Analyst on Snowflake, custom SQL metrics on Statsig) that solve the apparent limitation. + +The honest test. Run a 30-day proof of concept on the platform with the actual experiment you say it cannot handle. If the platform truly fails, warehouse-native is justified. If the platform works (even if imperfectly), the cost-benefit shifts back toward the platform. diff --git a/skills/dependency-management/SKILL.md b/skills/dependency-management/SKILL.md new file mode 100644 index 0000000..4ea6220 --- /dev/null +++ b/skills/dependency-management/SKILL.md @@ -0,0 +1,326 @@ +--- +name: dependency-management +description: "Manage third-party libraries, runtimes, and SaaS dependencies. Use this skill when setting an update cadence, responding to security advisories, dealing with deprecated dependencies, evaluating new dependencies, auditing what's installed, or unblocking a dependency upgrade. Triggers on dependency, package update, security patch, lockfile, deprecated, breaking change, supply chain, dependency audit, npm audit, dependabot, renovate. Also triggers when a build breaks after an update or when an advisory is published for a used package." +category: cross-cutting +catalog_summary: "Package updates, security patches, lockfile hygiene" +display_order: 4 +--- + +# Dependency Management + +Decide what to depend on, keep dependencies current, respond to advisories, and reduce supply chain risk. Stack-agnostic principles; specifics vary by package manager. + +--- + +## When to use + +- Setting up dependency hygiene for a new or existing project +- Responding to a security advisory +- Major version upgrade of a key dependency +- Adding a new dependency (evaluation, decision) +- Removing a dependency (cleanup) +- Audit of what's installed and what's actually used +- Setting an update cadence and policy +- Diagnosing a broken build after an update + +## When NOT to use + +- General code review (use `code-review-web`) +- Vulnerability scanning of infrastructure (use `security-baseline`) +- Pinning vendor or service contracts (use `vendor-evaluation`) +- Performance impact of dependencies (use `performance-optimization`) + +--- + +## Required inputs + +- Package manager and lockfile in use (npm, yarn, pnpm, pip, gem, composer, etc.) +- Current dependency list (production and dev) +- Current advisories (run audit; check service like Snyk, Dependabot) +- Update history (when were major dependencies last updated) +- Risk profile (production criticality, change tolerance) + +--- + +## The framework: 4 categories of dependency + +Every dependency falls into one of these. The category drives the policy. + +### Category 1: Critical runtime + +Code that runs in production and would break the system if it failed. + +Examples: framework, database driver, payment SDK, authentication library. + +Policy: +- Update cadence: monthly minor, quarterly major (with planning) +- Security: patch within 24-72 hours of advisory, 24h for critical +- Pinning: exact version pins or narrow ranges +- Vetting: thoroughly evaluated before adoption + +### Category 2: Supporting runtime + +Code that runs in production but is replaceable or non-critical. + +Examples: utility libraries, formatting, non-core integrations. + +Policy: +- Update cadence: monthly together with critical +- Security: patch within a week of advisory +- Pinning: narrow ranges acceptable (e.g., `^1.2.3`) +- Vetting: moderate evaluation; alternatives considered + +### Category 3: Dev/build + +Code that runs only during development or build, not in production. + +Examples: bundlers, linters, test frameworks, type checkers. + +Policy: +- Update cadence: quarterly +- Security: patch within a week (still matters; supply chain attacks target build tools) +- Pinning: ranges acceptable +- Vetting: lighter; broken dev tools surface fast + +### Category 4: Optional/dev-only-personal + +Tools individual developers use that aren't part of shared dev environment. + +Not really managed at the project level. Mentioned for completeness. + +--- + +## The framework: 5 risk dimensions + +When evaluating a dependency, consider: + +### Dimension 1: Maintenance health + +- Last commit date (months ago is concerning) +- Open issue count and age +- Number of maintainers +- Sponsorship or commercial backing +- Roadmap visibility + +A dependency abandoned a year ago is a liability waiting to surface. + +### Dimension 2: Surface area + +- Size of the package +- Number of transitive dependencies +- Footprint in the bundle (for client-side) +- Privileges required (file system, network, etc.) + +A small dependency that pulls in 50 transitive packages has the surface area of all 50. + +### Dimension 3: Replaceability + +- How hard would it be to remove? +- Are there alternatives? +- Could the functionality be implemented in-house? +- Is the API standard or idiomatic? + +A dependency you can't replace is leverage you've granted to its maintainer. + +### Dimension 4: Trust + +- Reputation of the maintainer or organization +- Code quality (skim the source) +- License (GPL, MIT, BSD, proprietary, none) +- History of security issues +- Supply chain practices (signed releases, 2FA on publishes) + +### Dimension 5: Cost + +- Time to evaluate, integrate, maintain +- Risk of breaking changes +- Lockfile entropy +- Potential security exposure +- Bundle size impact (for client-side) + +Every dependency has a cost. Free packages aren't free. + +--- + +## Workflow + +### Step 1: Inventory + +Run a dependency listing: + +```bash +# npm/yarn/pnpm +npm ls --all --json + +# pip +pip list + +# gem +bundle list +``` + +For each top-level dependency, categorize (critical / supporting / dev). For transitives, you generally don't manage individually unless one becomes a problem. + +### Step 2: Audit + +Run the security audit: + +```bash +npm audit +yarn audit +pip-audit +bundle audit +``` + +For each finding: +- Severity (critical, high, medium, low) +- Package and version +- Fix available? +- Used directly or transitively? + +### Step 3: Categorize and prioritize + +\| Severity \| Direct dep \| Indirect dep \| +\|---\|---\|---\| +\| Critical \| Patch today \| Patch this week (if a fix exists; track if not) \| +\| High \| Patch this week \| Patch this month \| +\| Medium \| Patch this month \| Track; patch with next round \| +\| Low \| Track \| Track \| + +Critical and high in production code are emergencies. Low and medium are scheduled work. + +### Step 4: Test before merging fixes + +Even patch-level updates can break things. For critical dependencies: +- Run the full test suite +- Smoke-test in staging +- Watch the monitoring after rollout + +For supporting and dev: +- Run the test suite +- A failed test is OK to investigate; don't merge a known-broken update + +### Step 5: Plan major version upgrades + +Major versions break things. Plan rather than rush. + +For each major upgrade: +- Read the changelog and migration guide +- Estimate the migration effort +- Schedule the work (don't do it under deadline pressure) +- Branch and test thoroughly +- Plan a staged rollout if it's a critical dependency + +Don't sit on major versions indefinitely. The longer you wait, the more painful the upgrade. + +### Step 6: Set the policy + +Document: +- Update cadence (e.g., monthly review, quarterly upgrades) +- Security response SLA (e.g., critical within 24h) +- Approval for new dependencies (who signs off) +- Removal criteria (when do we drop a dependency) +- Pinning strategy (exact, narrow range, broad range) + +The policy is what survives team turnover. Without it, dependency management becomes chaotic ad hoc work. + +### Step 7: Automate + +- Renovate or Dependabot for automatic update PRs +- CI runs audit on every PR +- Block merges on critical advisories (with override path for false positives) +- Notify on advisories for installed packages +- Lockfile diff in PR review + +Automation reduces toil. Manual checking doesn't scale. + +### Step 8: Audit usage periodically + +Quarterly: +- Dependencies installed but not imported anywhere (run a tool like `depcheck`) +- Major versions behind (more than 1-2 majors behind = upgrade plan needed) +- Unmaintained packages (last commit over a year ago = consider replacing) +- License audit (anything that's changed terms?) + +Remove what's not used. Replace what's unmaintained. + +--- + +## New dependency evaluation + +Before adding a new dependency, answer: + +- [ ] What problem does this solve? +- [ ] Could we solve it without a dependency? (Often yes for small problems.) +- [ ] What alternatives exist? +- [ ] Is the package actively maintained? +- [ ] What's the install size and bundle impact? +- [ ] What are the transitive dependencies? (Worth a quick scan.) +- [ ] What's the license? +- [ ] What's the security history? +- [ ] How replaceable is it? + +Default: don't add. Add only when the value clearly exceeds the cost. The cost includes ongoing maintenance, not just installation. + +--- + +## Dependency removal + +When removing a dependency: + +- [ ] Identify all usages (search the codebase) +- [ ] Replace each usage (with native code, another dependency, or a no-op) +- [ ] Remove from package.json or equivalent +- [ ] Update lockfile (run install) +- [ ] Verify tests pass +- [ ] Verify build size went down (or stayed the same) +- [ ] Document the removal in the changelog + +Removed dependencies sometimes leave config files, CI hooks, or imports behind. Search broadly. + +--- + +## Failure patterns + +No update cadence. Dependencies drift. When you finally upgrade, it's painful. Set a cadence. + +Audit disabled in CI. "Too noisy." Tune the audit, don't disable it. Whitelist known false positives explicitly. + +Pinning everything to exact versions. Stops automatic patches. Misses security fixes. Use narrow ranges with a lockfile. + +Unpinned floating versions. `latest` in production. Builds aren't reproducible. Lockfile required. + +Adding dependencies without review. "I just needed a quick utility." Now there are 50 unused dependencies. Require review for new dependencies. + +Ignoring transitive dependencies. A direct dependency pulls in 50 indirect ones. Each is supply chain surface. Audit the tree, not just the top level. + +Patching with major version bumps. "Updating to fix a bug" but the update is a major version. Now you have unrelated breaking changes too. Be deliberate about the version of the fix. + +Vendor-bundled libraries. Some dependencies vendor copies of other dependencies. They're not visible to the audit. Periodically check. + +Build-time dependencies treated as zero-risk. Build tools have access to your code and credentials. Supply chain attacks target them. Treat with appropriate care. + +Fork without rebase plan. Forking a dependency to fix something. Then you own it. Plan how to rebase or merge upstream changes, or commit to maintaining the fork. + +No license audit. Project ships with a GPL dependency in a commercial product. Compliance issue. Audit licenses on add and quarterly. + +Update PRs piling up. Dependabot PRs go unmerged for months. Either tune to fewer PRs or commit time to merging them. + +--- + +## Output format + +A dependency policy document includes: + +- Inventory: current dependencies by category +- Audit status: open advisories, severity, plan +- Policies: cadence, SLA, pinning, approval +- Tooling: what's automated (Renovate, Dependabot, audit in CI) +- License audit: any concerns +- Quarterly review schedule: when this gets revisited + +--- + +## Reference files + +- [`references/upgrade-checklist.md`](references/upgrade-checklist.md): Step-by-step checklist for performing a major version upgrade of a critical dependency, from changelog reading to staged rollout. diff --git a/skills/dependency-management/references/upgrade-checklist.md b/skills/dependency-management/references/upgrade-checklist.md new file mode 100644 index 0000000..f9e6929 --- /dev/null +++ b/skills/dependency-management/references/upgrade-checklist.md @@ -0,0 +1,290 @@ +# Major Version Upgrade Checklist + +Step-by-step checklist for upgrading a critical dependency to a new major version. The work is in the prep, not the install. + +--- + +## Phase 1: Decide whether to upgrade + +- [ ] Read the changelog from current version to target version +- [ ] Read the migration guide (most major libraries publish one) +- [ ] Skim issues filed against the new version (early adopters surface problems) +- [ ] Note any other dependencies that may need to upgrade in tandem +- [ ] Estimate effort (hours, days, weeks?) +- [ ] Estimate risk (low/medium/high) +- [ ] Estimate value (security fix, new features, ecosystem support, etc.) + +Decision: GO, DEFER, or SKIP. + +GO triggers: +- Security fix only available in new major +- Current version losing support +- New version unblocks a needed feature +- Effort and risk are manageable + +DEFER triggers: +- New version released within last 30 days (let early adopters surface bugs) +- Conflicts with active development +- No urgent driver + +SKIP triggers: +- Maintenance discontinued; replace the dependency instead +- Migration effort exceeds the value +- A different replacement is the better path + +--- + +## Phase 2: Prepare + +### Branch + +- [ ] Create a feature branch named for the upgrade (e.g., `upgrade/library-v3`) +- [ ] Don't mix the upgrade with other work; isolate it + +### Read the changelog carefully + +- [ ] List every breaking change between current and target version +- [ ] Note deprecations that affect your code +- [ ] Note new patterns or APIs you'll use after the upgrade + +For each breaking change: +- Where does this affect our code? +- What's the migration path? +- Is there a codemod available? + +### Search for usages + +- [ ] Grep for every API surface used (function names, import paths) +- [ ] Identify call sites that need attention +- [ ] Identify tests that may break + +For complex libraries, this can be the longest step. Be thorough. + +### Check the ecosystem + +- [ ] Plugins or related packages that depend on the library: do they support the new version? +- [ ] TypeScript types: are they updated? +- [ ] Documentation and examples in the wild: have they caught up? + +--- + +## Phase 3: Upgrade + +### Install + +- [ ] Update the version in package.json (or equivalent) +- [ ] Update related packages (plugins, types, etc.) to compatible versions +- [ ] Run install, generate fresh lockfile +- [ ] Verify the install completes without errors + +```bash +# Example +npm install library@^3.0.0 +``` + +### Initial build + +- [ ] Run the build +- [ ] Note every error and warning +- [ ] Don't fix anything yet; just inventory + +### Inventory the breakage + +Categorize each error: +- Type errors: API signatures changed +- Import errors: module structure changed +- Runtime errors: behavior changed +- Test failures: assumed behavior changed +- Lint warnings: patterns deprecated + +This list is your work plan. + +--- + +## Phase 4: Migrate + +### Apply codemods first + +If the library publishes codemods: + +```bash +npx codemod-name path/to/code +``` + +Codemods handle the mechanical parts (renamed APIs, restructured imports). They're not perfect, but they reduce toil. + +- [ ] Run codemods +- [ ] Review the diff (codemods can over-apply or under-apply) +- [ ] Commit the codemod changes separately + +### Fix manual issues + +For each remaining issue: +- [ ] Identify the root cause (what changed in the new version?) +- [ ] Apply the fix per the migration guide +- [ ] Verify tests pass for that area +- [ ] Commit incrementally (small commits, easy to revert) + +### Update tests + +- [ ] Tests using deprecated patterns: update to new patterns +- [ ] Tests that fail because behavior is different: investigate. Is the new behavior correct? +- [ ] Add tests for any new behavior you depend on + +### Update documentation + +- [ ] README references to the old version +- [ ] Internal docs and runbooks +- [ ] Comments referencing the old behavior + +--- + +## Phase 5: Verify + +### Local + +- [ ] All tests pass (unit, integration, E2E) +- [ ] Build succeeds without warnings (or with only acceptable warnings) +- [ ] Lint passes +- [ ] Type check passes (if typed) +- [ ] No console warnings in dev mode that weren't there before + +### Visual + +For UI-affecting libraries: +- [ ] Visual regression tests (Chromatic, Percy, or similar) clean +- [ ] Manual smoke test of key user flows +- [ ] Check on multiple browsers/devices + +### Performance + +- [ ] Bundle size: comparable or better +- [ ] Build time: comparable +- [ ] Runtime performance: comparable on key paths + +If bundle size or performance regresses meaningfully, investigate before merging. + +### Compatibility + +- [ ] Browser compatibility (if relevant) maintained +- [ ] Node version compatibility (if relevant) maintained +- [ ] Other dependencies still work with the new version + +--- + +## Phase 6: Stage + +For critical dependencies, don't go straight to production. + +- [ ] Deploy to a staging environment +- [ ] Run automated tests against staging +- [ ] Smoke-test critical flows manually +- [ ] Watch monitoring for new errors +- [ ] Watch performance metrics for regressions +- [ ] Let it bake for at least 24 hours (longer for critical systems) + +--- + +## Phase 7: Roll out + +Strategy depends on the dependency and the risk: + +### Low risk: standard deploy + +- [ ] Merge the PR +- [ ] Deploy to production +- [ ] Watch monitoring for the next few hours +- [ ] Be ready to rollback + +### Medium risk: feature flag or canary + +- [ ] Behind a feature flag if applicable +- [ ] Deploy with traffic splitting (1% to new, 99% to old, if infrastructure supports) +- [ ] Gradually increase traffic +- [ ] Watch metrics at each step + +### High risk: parallel run + +- [ ] Run old and new side by side +- [ ] Compare outputs +- [ ] Switch over only when confident + +--- + +## Phase 8: Monitor + +For at least one week post-rollout: + +- [ ] Error rates (compare to pre-upgrade baseline) +- [ ] Performance metrics +- [ ] User-reported issues +- [ ] Any unexpected behavior + +If issues appear: +- [ ] Triage by severity +- [ ] Fix forward (most common) +- [ ] Or rollback (if severe) +- [ ] Document the issues for the next upgrade + +--- + +## Phase 9: Document + +After the upgrade is stable: + +- [ ] Note the upgrade in the changelog +- [ ] Document any non-obvious migrations for future reference +- [ ] Update internal docs that referenced the old version +- [ ] If the upgrade was painful, write a note for next time +- [ ] Thank anyone who helped (especially open-source maintainers if they helped) + +--- + +## Common gotchas + +Bundle size grows unexpectedly. New version pulls in additional code or dependencies. Check the bundle analysis. + +Tests that "passed but didn't actually run." Test infrastructure breaks silently in some upgrades. Verify tests are running, not just exiting clean. + +TypeScript types don't match runtime. Sometimes types are updated but runtime isn't (or vice versa). Test runtime behavior, not just types. + +Server-side rendering breaks. New version uses browser-only APIs. Check SSR if applicable. + +Tree-shaking changes. Bundle includes more or different code. Verify what's actually shipped. + +Peer dependency conflicts. Library A wants version X, library B wants version Y. Resolve carefully; sometimes requires upgrading multiple in tandem. + +Breaking changes in transitive dependencies. The upgrade pulls in a new major of a transitive. The transitive's breaking changes affect you indirectly. + +API changes that compile but behave differently. Same function name, different default behavior. Read the changelog. + +Migration guide assumes specific framework or stack. If you use the library in a non-standard way, the guide may not cover your case. Adapt. + +--- + +## When to abort + +It's OK to abort an upgrade. Better to abort than ship a broken version. + +Abort triggers: +- Migration effort blowing past estimate by 5x+ +- Discovering critical incompatibilities mid-migration +- Finding that the new version has bugs blocking your use case +- Realizing the dependency itself is the problem (consider replacement) + +After aborting: +- Keep the branch around for reference +- Document what you learned +- Schedule a retry when conditions are better, or pivot to replacement + +--- + +## Reference for next time + +After every major upgrade, capture: +- Total effort (hours) +- Surprises encountered +- Things that worked well +- Things to do differently + +This becomes input to estimating the next major upgrade. Major upgrades happen periodically; the team gets better at them with practice and notes. diff --git a/skills/design-standards/SKILL.md b/skills/design-standards/SKILL.md new file mode 100644 index 0000000..ee3d5dd --- /dev/null +++ b/skills/design-standards/SKILL.md @@ -0,0 +1,213 @@ +--- +name: design-standards +description: "Apply production-grade design standards when building or reviewing pages, components, or UI. Use this skill whenever the user asks to build a page, design a component, lay out a section, review the UI, fix the layout, or check design quality. Triggers on build a page, create a component, design a section, hero, card, CTA, layout, review the UI, fix the design, design system, design tokens, spacing, typography scale, button standards, mobile design. Also triggers for any production design decision where contrast, accessibility, spacing, or visual hierarchy matters." +category: design +catalog_summary: "Production-grade page and component design standards" +display_order: 2 +--- + +# Design Standards + +Production design standards for any web project. Stack-agnostic. Tool-agnostic. Covers tokens, contrast, hierarchy, spacing, mobile rules, and the pre-ship checklist. + +This skill complements `brand-identity` (which defines the visual system) and `brand-style-guide` (which documents it). This skill is for the day-to-day work of applying those standards in real components and pages. + +--- + +## When to use + +- Building a new page, section, or component +- Reviewing UI for quality, accessibility, or consistency +- Setting up design tokens for a new project +- Fixing layout, contrast, or hierarchy issues +- Establishing a button or form standard +- Pre-ship design review + +## When NOT to use + +- Defining a brand identity from scratch (use `brand-identity`) +- Documenting a finished brand system (use `brand-style-guide`) +- Building a formal component library (use `design-system`) +- Frontend code architecture (use `frontend-component-build`) +- Accessibility-only audits with WCAG remediation (use `accessibility-audit`) + +--- + +## Required inputs + +- The page or component being built or reviewed +- The brand's design tokens (colors, type, spacing) - or willingness to define them +- The target devices and viewports + +If brand tokens are undefined, define a working set first using the template in [`references/design-tokens-template.md`](references/design-tokens-template.md). + +--- + +## The framework: 6 standards + +Six standards apply to every piece of UI. Hold the line on these and most design problems disappear. + +### 1. Design tokens + +Every project needs tokens defined before any UI gets built. Tokens are the source of truth. + +Color tokens (minimum): +- Primary brand color +- Primary hover (typically 15 to 25 percent darker) +- Background variants (surface, alt-section, hero/dark, footer) +- Text scale (heading, body, muted, on-dark) +- Semantic (success, warning, error, info) + +Spacing tokens: +- A consistent scale (e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96) +- Page max-width +- Section vertical padding (large, medium, small) +- Card padding +- Grid gaps + +Type tokens: +- Display, H1 through H4, body large, body, small, caption +- Each with size, weight, line height, letter spacing +- Font fallback stacks + +Radius tokens: +- Tight (cards, badges) +- Standard (buttons, inputs) +- Round (avatars, pill buttons) + +Document the tokens once. Reference them everywhere. Hardcoded values are technical debt. + +### 2. WCAG AA contrast (non-negotiable) + +Contrast is not a preference. It is a baseline. A design that fails AA is broken, regardless of how it looks to designers with full vision. + +\| Element \| Required ratio \| +\|---\|---\| +\| Normal body text \| 4.5:1 \| +\| Large text (18pt regular or 14pt bold) \| 3:1 \| +\| UI components and graphical elements \| 3:1 \| + +Common failures to avoid: +- Light gray body text on white that calculates to 2 to 4:1 +- Brand color used for body text without a darker variant +- Light borders on form fields that compute under 3:1 +- Bright orange or yellow on white at small sizes + +For the math, the contrast checker, and brand-color strategies, see `brand-identity/references/contrast-and-accessibility.md`. + +### 3. Visual hierarchy + +A well-designed page has a clear scan order. Hierarchy comes from: + +- Size. The largest element gets noticed first. +- Weight. Bold beats regular at the same size. +- Color. Saturated beats neutral. High-contrast beats low. +- Spacing. What sits alone gets emphasis. What gets crowded recedes. +- Position. Top-left and center get weight. Edges and corners recede. + +Apply hierarchy intentionally. Every visual element should be reachable through the hierarchy. If three things compete for primary attention, none of them wins. + +Common failures: +- Multiple elements styled as the "primary" CTA (creates ambiguity) +- Body text and headlines too close in size +- Hero image fighting the hero text for attention +- Icon, headline, and image at similar visual weight + +### 4. Spacing and rhythm + +Spacing is what separates a polished layout from a cluttered one. + +Rules: +- Use the spacing scale, not arbitrary values +- Related elements sit closer together than unrelated ones (proximity principle) +- Section breathing room: minimum 64px desktop, 48px mobile +- Card padding: minimum 24px desktop, 16px mobile +- Form field spacing: minimum 16px between fields +- Touch targets: minimum 44 by 44 pixels + +Common failures: +- Inconsistent spacing within similar contexts (one card has 24px padding, the next has 32px) +- Cramped sections that bleed into each other +- Touch targets under 44 pixels on mobile +- Headline butted directly against subheadline with no rhythm + +### 5. Mobile rules + +Most users are on mobile. Designing for desktop first guarantees mobile failures. + +Standards: +- Test on a 375 to 390 pixel viewport before declaring complete +- All interactive elements minimum 44 by 44 pixels +- Sticky bottom bars: page wrapper needs bottom padding equal to bar height +- No fixed pixel widths without max-width constraint +- Text never smaller than 14 pixels for body content +- Tap targets get 8 pixels of spacing minimum on all sides +- Modal and popover content scrolls; body locks +- Form inputs: at least 16px text size to prevent iOS auto-zoom + +Common failures: +- Designs that work in browser dev tools but break on real devices +- Sticky navigation eating 80px of viewport without compensation +- Horizontal scroll appearing because of one over-wide element +- Tap targets that are visually fine but impossibly close to other tap targets + +### 6. Component consistency + +The same thing should look the same everywhere. Variations should be intentional. + +Common consistency principles: +- Buttons: one primary style, one secondary style, one ghost style. Not five. +- Cards: one base card pattern with variants. Not bespoke cards per page. +- Icons: one stroke weight, one corner style across the icon set +- Avatars and brand marks: one shape rule (rounded-lg or fully round, pick one and stick to it) +- Form inputs: one set of input states (default, focus, error, disabled) used everywhere + +Common failures: +- Three different "primary buttons" used inconsistently across pages +- Some cards with rounded-2xl corners, others with rounded-xl +- Iconography style drifting between sections +- Brand avatar that switches between square and round depending on the page + +--- + +## Workflow + +1. Confirm tokens. If tokens are not yet defined, define a working set first. Document them. +2. Sketch hierarchy. Before writing markup, identify the primary action, secondary actions, and supporting content. Confirm the scan order makes sense. +3. Build mobile-first. Lay out for the smallest target viewport before scaling up. +4. Apply tokens. All values come from the token set. No hardcoded colors, sizes, or spacing. +5. Run contrast checks. Every text-on-background combination passes AA. Every UI element passes 3:1. +6. Test at viewport breakpoints. 375, 768, 1024, 1440 minimum. Confirm nothing breaks. +7. Run the pre-ship checklist in [`references/preship-checklist.md`](references/preship-checklist.md). + +--- + +## Failure patterns + +- Designing without tokens. Hardcoded colors and spacing. Hard to maintain. Inconsistent at scale. +- Skipping contrast checks. Especially on brand colors used for text. Most brand colors fail AA. +- Designing only for desktop. Mobile reveals every layout sin. Test mobile first or last, but always. +- Rounded-everything. Treating "modern" as "rounded all the things." Rounded corners are a tool, not a default. +- Visual hierarchy mush. Three things competing as primary. Reader does not know where to look. +- Touch target violations. Visually nice 32px buttons that fail finger ergonomics on real devices. +- Component drift. Each page rebuilds the card or button from scratch. Design system erodes. + +--- + +## Output format + +This skill produces design decisions and review notes more than artifacts. Outputs include: + +- Design tokens file (when starting a project): `design-tokens.md` or equivalent +- Component or page review: markdown notes scored against the 6 standards, with specific fixes +- Pre-ship checklist results: pass/fail across the checklist with notes + +When generating component code (HTML, CSS, framework-specific markup), the SKILL.md remains stack-agnostic. Stack-specific patterns live in reference files. + +--- + +## Reference files + +- [`references/design-tokens-template.md`](references/design-tokens-template.md) - Template for setting up tokens for any project. +- [`references/preship-checklist.md`](references/preship-checklist.md) - Final design review checklist before shipping. +- [`references/tailwind-patterns.md`](references/tailwind-patterns.md) - Optional. Tailwind-specific component patterns (hero, cards, buttons, data rows) for projects on that stack. diff --git a/skills/design-standards/references/design-tokens-template.md b/skills/design-standards/references/design-tokens-template.md new file mode 100644 index 0000000..7e96765 --- /dev/null +++ b/skills/design-standards/references/design-tokens-template.md @@ -0,0 +1,248 @@ +# Design Tokens Template + +Tokens are the source of truth for color, spacing, typography, and other design decisions. Define them once at the start of the project. Reference them everywhere. + +This template is stack-agnostic. Adapt the syntax to your project: CSS custom properties, Tailwind config, design system JSON, Style Dictionary, Figma variables - the values stay the same. + +--- + +## Color tokens + +### Primary (brand) + +``` +brand/primary #XXXXXX /* signature brand color / +brand/primary-hover #XXXXXX / 15-25% darker, for hover states / +brand/primary-text #XXXXXX / darker variant if primary fails AA on white / +``` + +### Background + +``` +bg/surface #FFFFFF / default page background / +bg/surface-alt #F9FAFB / alternating section background / +bg/hero #1A1D23 / dark section for heroes, footers / +bg/footer #111827 / footer specifically / +``` + +### Text scale + +Document each with the contrast ratio against the background it sits on. + +``` +text/heading #111827 / heading on white = 16.9:1 / +text/body #374151 / body on white = 10.3:1 / +text/muted #4B5563 / muted on white = 7.6:1 PASS AA / +text/subtle #6B7280 / subtle on white = 5.1:1 PASS AA / +text/on-dark #FFFFFF / white on hero bg = 15.8:1 / +text/on-dark-muted #D1D5DB / on hero bg = 11.4:1 / +``` + +Avoid going lighter than the muted/subtle colors above on white. Lighter grays fail AA. + +### Semantic + +``` +semantic/success #059669 / on white = 4.5:1 PASS AA / +semantic/warning #D97706 / on white = 4.5:1 PASS AA / +semantic/error #DC2626 / on white = 4.7:1 PASS AA / +semantic/info #2563EB / on white = 5.6:1 PASS AA / +``` + +For each semantic color, also define a tinted background and a darker text variant for badges and alert blocks. + +### Border and divider + +``` +border/default #E5E7EB / default borders, subtle dividers / +border/strong #D1D5DB / form fields, interactive borders / +border/focus #2563EB / focus rings / +``` + +--- + +## Spacing tokens + +A consistent scale prevents arbitrary values. + +``` +space/0 0 +space/1 4px +space/2 8px +space/3 12px +space/4 16px +space/5 20px +space/6 24px +space/8 32px +space/10 40px +space/12 48px +space/16 64px +space/20 80px +space/24 96px +space/32 128px +``` + +### Layout-specific spacing + +``` +layout/page-max-width 1280px (or 1440px for spacious designs) +layout/page-padding-x 16px mobile / 24px tablet / 32px desktop +layout/section-py-large 80px desktop / 64px mobile +layout/section-py-medium 48px desktop / 32px mobile +layout/section-py-small 32px desktop / 24px mobile +layout/card-padding 24px to 32px +layout/grid-gap 24px to 32px +``` + +--- + +## Typography tokens + +### Font families + +``` +font/display "[Display typeface]", system-ui, sans-serif +font/body "[Body typeface]", system-ui, sans-serif +font/mono "[Mono typeface]", ui-monospace, monospace +``` + +### Type scale + +\| Token \| Size \| Weight \| Line height \| Letter spacing \| Use \| +\|---\|---\|---\|---\|---\|---\| +\| type/display-1 \| 64px \| 700 \| 1.0 \| -0.02em \| Hero headlines \| +\| type/display-2 \| 48px \| 700 \| 1.05 \| -0.01em \| Section heroes \| +\| type/h1 \| 36px \| 700 \| 1.1 \| 0 \| Page titles \| +\| type/h2 \| 28px \| 600 \| 1.2 \| 0 \| Section titles \| +\| type/h3 \| 22px \| 600 \| 1.3 \| 0 \| Sub-sections \| +\| type/h4 \| 18px \| 600 \| 1.4 \| 0 \| Component titles \| +\| type/body-large \| 18px \| 400 \| 1.5 \| 0 \| Lead paragraphs \| +\| type/body \| 16px \| 400 \| 1.6 \| 0 \| Default body \| +\| type/body-small \| 14px \| 400 \| 1.5 \| 0 \| Captions, metadata \| +\| type/caption \| 12px \| 400 \| 1.4 \| 0.01em \| Footnotes, labels \| +\| type/eyebrow \| 12px \| 600 \| 1.4 \| 0.08em \| Uppercase eyebrows \| + +### Mobile adjustments + +Mobile typography is typically 1 to 2 steps smaller for display sizes: + +``` +display-1: 64px desktop → 40px mobile +display-2: 48px desktop → 32px mobile +h1: 36px desktop → 28px mobile +``` + +Body sizes stay the same on mobile; never go below 14px. + +--- + +## Radius tokens + +``` +radius/none 0 +radius/sm 4px / small badges, tags / +radius/md 8px / default for inputs / +radius/lg 12px / buttons, alerts / +radius/xl 16px / cards (small) / +radius/2xl 20px / cards (default) / +radius/3xl 24px / cards (prominent), modals / +radius/full 9999px / pill buttons, fully rounded / +``` + +### Conventions for shapes + +``` +buttons (default): radius/full (pill) OR radius/lg (rounded rect) +buttons (form/utility): radius/md +inputs: radius/md or radius/lg +cards: radius/2xl +icon containers: radius/xl (NOT radius/full unless avatar) +avatars (people): radius/full +brand avatars/logos: radius/lg (matches favicon convention) +modals: radius/3xl (top corners on mobile sheets) +``` + +Pick the conventions, document them, and stick to them. Inconsistent radius is one of the most common visual drift patterns. + +--- + +## Shadow tokens + +``` +shadow/none none +shadow/sm 0 1px 2px rgba(0,0,0,0.05) +shadow/md 0 4px 6px rgba(0,0,0,0.08) +shadow/lg 0 10px 15px rgba(0,0,0,0.10) +shadow/xl 0 20px 25px rgba(0,0,0,0.10) +shadow/2xl 0 25px 50px rgba(0,0,0,0.15) +``` + +### Shadow conventions + +``` +default cards: shadow/sm +hover state cards: shadow/md +elevated content: shadow/lg +modals/dropdowns: shadow/xl +``` + +--- + +## Z-index tokens + +A documented z-index scale prevents the "9999 wars." + +``` +z/below -1 +z/base 0 +z/raised 10 / sticky elements, fixed nav / +z/dropdown 20 / popovers, dropdowns / +z/overlay 30 / page-level overlays, scrims / +z/modal 40 / modals, dialogs / +z/toast 50 / toasts, top-of-everything notifications / +``` + +--- + +## Motion tokens + +``` +motion/duration-fast 100ms / hover state, simple feedback / +motion/duration-base 200ms / most UI transitions / +motion/duration-slow 300ms / enter/exit animations / +motion/duration-slower 500ms+ / dramatic brand moments / + +motion/ease-default cubic-bezier(0.4, 0, 0.2, 1) +motion/ease-in cubic-bezier(0.4, 0, 1, 1) +motion/ease-out cubic-bezier(0, 0, 0.2, 1) +motion/ease-bounce cubic-bezier(0.68, -0.55, 0.27, 1.55) +``` + +Always provide `prefers-reduced-motion` alternatives that disable or shorten animations for users who request it. + +--- + +## Breakpoints + +``` +breakpoint/sm 640px +breakpoint/md 768px +breakpoint/lg 1024px +breakpoint/xl 1280px +breakpoint/2xl 1536px +``` + +Test the design at viewport widths matching each breakpoint, and at 375px (smaller phone), 390px (default iPhone), and 1440px (default laptop). + +--- + +## How to use this template + +1. Copy* the structure into your project. +2. Fill in values per the brand identity. +3. Verify contrast for every text/background combination using a contrast checker. +4. Document edge cases (e.g., the darker brand variant for text contexts). +5. Reference everywhere. No hardcoded values in components. +6. Update once. When tokens change, the whole product reflects the change. + +The token file is canonical. Anything in the codebase using a hardcoded value instead of a token is technical debt waiting to surface. diff --git a/skills/design-standards/references/preship-checklist.md b/skills/design-standards/references/preship-checklist.md new file mode 100644 index 0000000..14cd7fd --- /dev/null +++ b/skills/design-standards/references/preship-checklist.md @@ -0,0 +1,180 @@ +# Pre-Ship Design Checklist + +Run before declaring any page or component complete. Most production design defects come from skipping these. + +--- + +## Tokens and consistency + +- [ ] All colors come from the token set (no hardcoded hex values) +- [ ] All spacing comes from the spacing scale (no arbitrary px values) +- [ ] All typography uses defined type tokens +- [ ] All radii use the defined radius tokens +- [ ] Shadows use defined shadow tokens +- [ ] No more than one variant per component type (e.g., one primary button style across the page) + +--- + +## Contrast (WCAG AA) + +- [ ] All body text passes 4.5:1 against its background +- [ ] All large text passes 3:1 +- [ ] All UI elements (icons, borders, focus rings) pass 3:1 +- [ ] Brand colors used for text use the darker text variant if the signature color fails +- [ ] No light gray text under #6B7280 on white backgrounds +- [ ] Dark mode (if implemented) tested against dark surfaces, not just light + +Use a contrast checker for every pairing. Visual judgment is unreliable. + +--- + +## Visual hierarchy + +- [ ] One clear primary action per page (one primary CTA) +- [ ] Secondary actions visually subordinate to primary +- [ ] Headline larger and heavier than body text by enough to be unambiguous +- [ ] Section breaks visible without effort (spacing or background change) +- [ ] Images do not visually compete with primary content + +--- + +## Typography + +- [ ] Exactly one H1 per page +- [ ] No skipped header levels (H2 followed by H4) +- [ ] Body text minimum 14px (16px preferred) +- [ ] Line length controlled (45 to 75 characters per line for body text) +- [ ] Line height appropriate (1.4 to 1.6 for body, 1.0 to 1.2 for display) +- [ ] No fake italics or fake bold (use real font weights) + +--- + +## Spacing and rhythm + +- [ ] Consistent padding inside same-type containers (all cards, all sections) +- [ ] Section breathing room: 64px+ desktop, 48px+ mobile +- [ ] Form fields spaced minimum 16px apart vertically +- [ ] Related elements visually grouped (proximity principle) +- [ ] No cramped sections that bleed into each other + +--- + +## Buttons and CTAs + +- [ ] Primary button uses brand primary color +- [ ] Hover state visible and distinct +- [ ] Focus state visible (focus ring or equivalent) +- [ ] Disabled state visible and accessible +- [ ] Touch target minimum 44 by 44 pixels +- [ ] Button text descriptive (not "click here" or "submit") + +--- + +## Forms + +- [ ] Every input has a visible label (placeholder is not a label) +- [ ] Required fields marked clearly +- [ ] Error states have text descriptions, not just color +- [ ] Help text positioned below or beside the field, not as placeholder +- [ ] Input height accommodates touch (minimum 44px) +- [ ] Form inputs use 16px+ text on iOS to prevent zoom + +--- + +## Images and media + +- [ ] All meaningful images have descriptive alt text +- [ ] Decorative images have empty alt (`alt=""`) +- [ ] Images have explicit width and height to prevent layout shift +- [ ] Modern formats used where supported (WebP, AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] No images stretched or pixelated due to wrong sizing + +--- + +## Interactive elements + +- [ ] All interactive elements have hover states (where pointer is supported) +- [ ] Focus rings visible (do not use `outline: none` without a replacement) +- [ ] Tap targets minimum 44 by 44 pixels +- [ ] Tap targets at least 8 pixels of spacing on all sides from other tap targets +- [ ] Cursor styles correct (`pointer` for clickable, `text` for inputs, etc.) + +--- + +## Mobile (375 to 390 pixel viewport) + +- [ ] Tested on real device or device-mode in browser +- [ ] No horizontal scroll +- [ ] No fixed-width elements breaking layout +- [ ] Sticky bottom bars do not overlap content (page wrapper has bottom padding) +- [ ] Sticky top bars do not eat critical content +- [ ] Mobile menu works on touch +- [ ] All text remains readable (no truncated headlines) +- [ ] Tap targets remain 44px minimum + +--- + +## Tablet (768 to 1024 pixel viewport) + +- [ ] Layout transitions cleanly between mobile and desktop breakpoints +- [ ] No awkward in-between sizing +- [ ] Multi-column layouts adapt sensibly + +--- + +## Desktop (1280+ pixel viewport) + +- [ ] Page max-width prevents content from stretching too wide +- [ ] Typography does not break (line lengths still controlled) +- [ ] Whitespace remains balanced + +--- + +## Performance signals (visual) + +- [ ] No visible layout shift after initial render +- [ ] Images load progressively (no blank-then-pop) +- [ ] No flash of unstyled text (FOUT) for primary fonts +- [ ] No render-blocking elements above the fold + +(For deep performance audits, use `performance-optimization`.) + +--- + +## Brand and consistency + +- [ ] Logo placed correctly (per brand-style-guide rules) +- [ ] Brand colors used per brand-style-guide rules +- [ ] Imagery direction matches brand-style-guide +- [ ] Voice (in any UI text) matches brand-voice +- [ ] No off-brand stock photography or generic illustrations + +--- + +## Accessibility (basic checks; for deeper audits use `accessibility-audit`) + +- [ ] Page operable by keyboard alone +- [ ] Logical tab order +- [ ] Form fields have associated labels (`for`/`id` or `aria-labelledby`) +- [ ] Buttons and links use semantic elements (not `<div onClick>`) +- [ ] Skip links present for long pages +- [ ] Page language declared (`<html lang="...">`) + +--- + +## Pre-launch sanity + +- [ ] No placeholder text remaining ("Lorem ipsum," "TODO," "[Replace this]") +- [ ] No broken images +- [ ] No broken links (test 5 random links) +- [ ] No console errors in browser dev tools +- [ ] No accessibility errors in browser audit tools + +--- + +## Sign-off + +When all boxes check, the design is ready to ship. If any box fails, document the failure, decide whether it is a launch blocker, and either fix or file a known-issue ticket before shipping. + +The checklist is the floor, not the ceiling. Great design exceeds it. diff --git a/skills/design-standards/references/tailwind-patterns.md b/skills/design-standards/references/tailwind-patterns.md new file mode 100644 index 0000000..7b8b004 --- /dev/null +++ b/skills/design-standards/references/tailwind-patterns.md @@ -0,0 +1,287 @@ +# Tailwind Component Patterns + +Optional reference. Tailwind-specific component patterns for projects on that stack. The principles in [`SKILL.md`](../SKILL.md) are stack-agnostic; this file translates them into Tailwind utilities. + +If you are not using Tailwind, skip this file. The patterns translate to any utility framework or CSS approach with minor changes. + +--- + +## Page wrapper + +The standard container pattern: + +```jsx +<main className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"> + {/* page content /} +</main> +``` + +Token equivalents: +- `max-w-7xl` = page max width (1280px) +- `mx-auto` = horizontal centering +- `px-4 sm:px-6 lg:px-8` = responsive horizontal padding + +For wider designs, swap `max-w-7xl` for `max-w-[1440px]`. + +--- + +## Section spacing + +```jsx +{/ Large section (heroes, major content) /} +<section className="py-20 md:py-28"> + +{/ Medium section (most content) /} +<section className="py-12 md:py-16"> + +{/ Small section (compact content) /} +<section className="py-8 md:py-12"> +``` + +Always include the mobile-first variant. Mobile sections use shorter padding to preserve viewport efficiency. + +--- + +## Dark hero + +```jsx +<section className="bg-gray-900 py-20 md:py-28"> + <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 text-center"> + {/ Breadcrumb - text-gray-300 minimum on dark for AA /} + <nav className="text-sm text-gray-300 mb-6" aria-label="Breadcrumb"> + <a href="/" className="hover:text-white transition-colors">Home</a> + <span className="mx-2" aria-hidden="true">/</span> + <span className="text-white">Current Page</span> + </nav> + + {/ Eyebrow /} + <p className="text-xs font-semibold uppercase tracking-wider text-blue-400 mb-3"> + Section Label + </p> + + {/ H1 - exactly one per page /} + <h1 className="text-4xl md:text-6xl font-extrabold tracking-tight text-white mb-4"> + Main <span className="text-blue-400">Headline</span> + </h1> + + {/ Supporting /} + <p className="text-lg text-gray-300 max-w-2xl mx-auto"> + Supporting description that gives context. + </p> + </div> +</section> +``` + +Contrast notes: +- White on `bg-gray-900` = 17.4:1 PASS +- `text-gray-300` on `bg-gray-900` = 11.2:1 PASS AA +- `text-gray-400` on `bg-gray-900` = 7.6:1 PASS AA (still readable) +- `text-gray-500` on `bg-gray-900` = 5.5:1 PASS AA borderline; prefer 300 or 400 for body on dark + +--- + +## Feature card grid + +```jsx +<div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6"> + <div className="rounded-2xl border border-gray-200 bg-white p-6 shadow-sm hover:shadow-md transition-shadow"> + {/ Icon container - rounded-xl, NOT rounded-full unless avatar /} + <div className="w-10 h-10 rounded-xl bg-blue-50 text-blue-600 flex items-center justify-center mb-4"> + <Icon className="w-5 h-5" /> + </div> + <h3 className="font-semibold text-gray-900 mb-2">Card Title</h3> + <p className="text-sm text-gray-600">Card description that explains the feature.</p> + </div> + {/ repeat /} +</div> +``` + +Conventions: +- `rounded-2xl` for cards (consistent radius across all cards on the site) +- `rounded-xl` for icon containers (not `rounded-full` unless it's an avatar) +- `text-gray-600` is the muted-text floor on white (passes AA at 7.6:1) + +--- + +## Data row (key-value display) + +```jsx +<div className="flex justify-between items-center rounded-xl bg-gray-50 px-4 py-3 text-sm"> + <span className="text-gray-600 font-medium">Label</span> + <span className="font-semibold text-gray-900">Value</span> +</div> +``` + +Stack rows in a `space-y-2` container for vertically grouped data. + +--- + +## Inline CTA banner + +```jsx +<div className="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 rounded-xl border border-blue-100 bg-blue-50 px-5 py-4"> + <div> + <p className="font-semibold text-gray-900">CTA Headline</p> + <p className="text-sm text-gray-600 mt-0.5">Supporting context</p> + </div> + <a + href="#" + className="shrink-0 bg-blue-600 hover:bg-blue-700 text-white text-sm font-semibold px-4 py-2.5 rounded-full transition-colors whitespace-nowrap" + > + Action Text + </a> +</div> +``` + +The `flex-col sm:flex-row` pattern stacks on mobile, sits side-by-side on tablet+. Standard across all banner-style CTAs. + +--- + +## Author byline + +```jsx +<div className="flex items-center gap-3"> + {/ Brand/author avatar - rounded-lg matches favicon shape /} + <div className="w-9 h-9 rounded-lg bg-blue-600 flex items-center justify-center text-white text-sm font-bold flex-shrink-0"> + {authorInitial} + </div> + <div className="min-w-0"> + <a + href={`/author/${slug}`} + className="text-sm font-medium text-gray-900 hover:text-blue-700 transition-colors block truncate" + > + {authorName} + </a> + <p className="text-xs text-gray-600 truncate">{authorRole}</p> + </div> +</div> +``` + +Convention: brand and author identifiers use `rounded-lg`, not `rounded-full`. Reserve `rounded-full` for actual person photographs (people-photo avatars). + +--- + +## Buttons + +```jsx +{/ Primary - pill shape, brand color /} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold transition-colors"> + Primary Action +</a> + +{/ Secondary - outline /} +<a className="inline-flex items-center gap-2 px-6 py-3 rounded-full border border-blue-600 text-blue-600 hover:bg-blue-50 font-semibold transition-colors"> + Secondary Action +</a> + +{/ Ghost - text only /} +<a className="inline-flex items-center gap-2 px-4 py-2 text-blue-600 hover:text-blue-700 font-semibold transition-colors"> + Ghost Action +</a> + +{/ Disabled state /} +<button + disabled + className="px-6 py-3 rounded-full bg-gray-200 text-gray-500 font-semibold cursor-not-allowed" +> + Disabled +</button> +``` + +Pick pill (`rounded-full`) or rounded-rect (`rounded-lg`) for buttons. Use one consistently across the entire site. + +--- + +## Form inputs + +```jsx +{/ Input with label /} +<div className="space-y-1.5"> + <label htmlFor="email" className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + id="email" + type="email" + className="w-full rounded-lg border border-gray-300 px-3.5 py-2.5 text-base shadow-sm focus:border-blue-600 focus:ring-2 focus:ring-blue-600/20 focus:outline-none" + placeholder="you@example.com" + /> + <p className="text-xs text-gray-600">We'll never share your email.</p> +</div> + +{/ Error state /} +<div className="space-y-1.5"> + <label className="block text-sm font-medium text-gray-900"> + Email address + </label> + <input + type="email" + aria-invalid="true" + aria-describedby="email-error" + className="w-full rounded-lg border border-red-500 px-3.5 py-2.5 text-base shadow-sm focus:border-red-600 focus:ring-2 focus:ring-red-600/20 focus:outline-none" + /> + <p id="email-error" className="text-xs text-red-600"> + Please enter a valid email address. + </p> +</div> +``` + +Notes: +- Always use `text-base` (16px) on inputs to prevent iOS zoom on focus +- `py-2.5` gives ~44px height with text, hitting the touch target minimum +- Error states need text, not just color (color blindness consideration) + +--- + +## Mobile sticky bar + +```jsx +<> + {/ Page wrapper needs bottom padding to compensate for the bar /} + <main className="pb-20 md:pb-0"> + {/ page content /} + </main> + + {/ Sticky bar - mobile only /} + <div className="fixed bottom-0 left-0 right-0 bg-white border-t border-gray-200 px-4 py-3 md:hidden z-30"> + <a + href="#" + className="block w-full text-center px-6 py-3 rounded-full bg-blue-600 hover:bg-blue-700 text-white font-semibold" + > + Mobile CTA + </a> + </div> +</> +``` + +The `pb-20 md:pb-0` on the wrapper is critical. Without it, the sticky bar covers the bottom of the page content. + +--- + +## Common Tailwind contrast values + +Quick reference for which gray text colors pass AA on white: + +\| Class \| Hex \| Contrast on white \| AA pass \| +\|---\|---\|---\|---\| +\| `text-gray-300` \| #D1D5DB \| 1.6:1 \| FAIL (decorative only) \| +\| `text-gray-400` \| #9CA3AF \| 2.85:1 \| FAIL \| +\| `text-gray-500` \| #6B7280 \| 4.6:1 \| PASS (borderline; prefer 600) \| +\| `text-gray-600` \| #4B5563 \| 7.6:1 \| PASS \| +\| `text-gray-700` \| #374151 \| 10.3:1 \| PASS \| +\| `text-gray-800` \| #1F2937 \| 14.6:1 \| PASS \| +\| `text-gray-900` \| #111827 \| 16.9:1 \| PASS \| + +Use `text-gray-600` as the floor for body text on white. Anything lighter requires verification against the specific background. + +For dark backgrounds: + +\| Class \| Hex \| Contrast on `bg-gray-900` \| AA pass \| +\|---\|---\|---\|---\| +\| `text-white` \| #FFFFFF \| 17.4:1 \| PASS \| +\| `text-gray-300` \| #D1D5DB \| 11.2:1 \| PASS \| +\| `text-gray-400` \| #9CA3AF \| 7.6:1 \| PASS \| +\| `text-gray-500` \| #6B7280 \| 5.5:1 \| PASS borderline \| +\| `text-gray-600` \| #4B5563 \| 3.8:1 \| FAIL for body \| + +Use `text-gray-300` as the floor for body text on `bg-gray-900`. Reserve lighter grays for headlines and primary content. diff --git a/skills/design-system/SKILL.md b/skills/design-system/SKILL.md new file mode 100644 index 0000000..9ae0401 --- /dev/null +++ b/skills/design-system/SKILL.md @@ -0,0 +1,202 @@ +--- +name: design-system +description: "Build or audit a design system including component library, design tokens, naming conventions, contribution model, and documentation. Use this skill whenever the user wants to build a design system, audit an existing system, define design tokens at the system level, structure a component library, or set up design system governance. Triggers on design system, component library, design tokens, atomic design, atoms, molecules, organisms, design system documentation, Storybook, Figma library, system governance, design contribution model. Also triggers when teams are inconsistent across products and a system is the answer." +category: design +catalog_summary: "Component library, design tokens, design system documentation" +display_order: 1 +--- + +# Design System + +Build, evolve, or audit a design system. Stack-agnostic in principle. Implementation is stack-specific (Figma, Storybook, code library, etc.) but the structure and governance principles transfer. + +This skill is for building the system. For applying a system to specific pages or components, use `design-standards`. For brand visual identity, use `brand-identity`. + +--- + +## When to use + +- Building a design system from scratch +- Auditing an existing system for gaps or fragmentation +- Defining design tokens at the system level +- Structuring a component library +- Establishing contribution and governance models +- Migrating from ad-hoc components to a documented system + +## When NOT to use + +- Designing a single page or component (use `design-standards`) +- Brand identity work (use `brand-identity`) +- Component-level frontend implementation (use `frontend-component-build`) +- Pure design documentation for marketing (use `brand-style-guide`) + +--- + +## Required inputs + +- The brand identity (tokens, voice, imagery direction) +- The product surfaces the system needs to support (web, mobile, marketing, app, internal tools) +- The team and its working tools (Figma, code framework, doc platform) +- Existing components, even if undocumented +- Constraints (accessibility requirements, performance targets, browser support) + +If brand identity is undefined, run `brand-identity` first. + +--- + +## The framework: 5 layers + +A complete design system has five layers, stacked. Each layer feeds the layer above. + +### 1. Foundations (tokens) + +The atomic decisions. Color, type, spacing, radius, shadow, motion, breakpoints. + +Why this layer matters:* +- Tokens are the source of truth for everything above +- Token changes propagate everywhere automatically +- Without tokens, the system has no foundation + +Output: +- A documented token set (see `design-standards/references/design-tokens-template.md`) +- Token implementation in code (CSS variables, JS objects, Style Dictionary, etc.) +- Token implementation in Figma (variables and styles) +- A primer doc explaining what tokens to use when + +Common patterns: +- Two-tier tokens: base tokens (raw values) + semantic tokens (named uses). Example: `color-blue-600` (base) + `color-text-link` (semantic). Components reference semantic tokens. Theme changes update semantic tokens, not base. + +### 2. Elements (atoms) + +The smallest functional building blocks. Buttons, inputs, labels, badges, icons, links, dividers. + +Per element, document: +- Visual variants (primary, secondary, ghost, etc.) +- Size variants (small, medium, large) +- States (default, hover, focus, active, disabled, error, loading) +- Anatomy (the parts that make up the element) +- Spacing and proportions +- Accessibility (keyboard support, screen reader behavior, ARIA) +- Code usage (props, examples) + +Output: +- Element library in Figma +- Element components in code +- Per-element documentation + +### 3. Components (molecules + organisms) + +Combinations of elements that form recognizable UI patterns. Cards, alerts, modals, navigation, forms, data tables, headers, footers. + +Per component: +- Composition (which elements it uses) +- Variants and configurations +- Use cases (when to reach for this vs. an alternative) +- Layout behavior (responsive, contained, full-bleed) +- Anti-patterns (when NOT to use it) + +Output: +- Component library +- Per-component documentation with usage guidance + +### 4. Patterns (templates) + +Larger structures that combine components. Sign-in flow, settings page, dashboard layout, marketing page sections. + +Per pattern: +- The structure and components used +- The user journey it supports +- Layout grid and spacing +- Responsive behavior +- Variants (e.g., "with sidebar," "fullscreen," "modal") + +Output: +- Pattern library or page templates +- Documentation showing complete examples + +### 5. Documentation and governance + +How the system gets used, contributed to, and maintained. + +Documentation includes: +- Getting started guide for new team members +- How to use vs. how to extend +- Contribution model +- Versioning policy +- Migration paths when breaking changes happen +- Decision log for major system choices + +Governance includes: +- Who owns the system (a team or rotation) +- How new components get proposed and approved +- How conflicts get resolved +- How the system evolves vs. stays stable +- Cadence of review and updates + +--- + +## Workflow + +### For a new design system + +1. Inventory the existing UI. Screenshot every component, button, form, modal across the product. The list of distinct UI patterns is your starting scope. +2. Identify the duplicates. Same component built 5 different ways across the product. These are your high-value consolidation targets. +3. Define foundations. Token set, with both base and semantic layers. Document each. +4. Audit elements. From the inventory, identify the actual elements (buttons, inputs, etc.) and reduce variants to a managed set. +5. Build the element library. Figma + code. Document each element. +6. Identify priority components. The 10 to 15 components that appear most often. Build those first. +7. Document patterns. Page-level templates that show the system in use. +8. Establish governance. Owner, contribution model, review cadence. +9. Roll out. Migrate existing surfaces to the system progressively. + +### For an existing design system audit + +1. Inventory what exists. What's documented, what's in Figma, what's in code, what's actually used in production. +2. Map gaps. Where the system is incomplete. Where teams build outside the system because the system can't serve their need. +3. Map fragmentation. Where the system has divergent implementations (Figma vs. code, web vs. mobile, multiple teams). +4. Identify decay. Components that have drifted from the documented standard. +5. Prioritize fixes. Foundation gaps first. High-use component drift second. Rarely-used component cleanup last. +6. Plan rollout. Major changes need migration paths. + +--- + +## Failure patterns + +- Building the system before the brand is set. Tokens depend on brand. Set brand first. +- Atoms-up extreme. Spending 6 months on tokens and elements before producing components anyone uses. Ship components people need; refine tokens iteratively. +- One-person system. A system without governance fails as soon as the original designer leaves. Establish ownership early. +- Stale documentation. A system with code that's diverged from the docs is worse than no system. Synchronize or kill the docs. +- Versioning everything. Treating every component as needing a major version. Most components evolve in place. Reserve versioning for breaking changes. +- Adopting "atomic design" dogmatically. Atoms / molecules / organisms is a useful mental model, not a rigid taxonomy. Don't argue about whether something is a molecule or an organism. +- Building in a vacuum. A system designed without input from the teams using it gets ignored. Co-design with consumers. +- No deprecation path. Old components linger in code forever because no one knows it's safe to remove them. Document deprecation explicitly. +- Token explosion. Defining 200 color tokens for a brand with 10 colors. Discipline. Most products need fewer tokens than they have. + +--- + +## Output format + +A design system has multiple deliverables. Typically: + +- Documentation site (Notion, dedicated site, GitHub Pages, Storybook addon, etc.) +- Figma library (or equivalent design tool) +- Code library (npm package, monorepo workspace, copy-paste components) +- Decision log (system-level decisions and the reasoning) +- Roadmap and changelog + +For a design system audit, output is a markdown report at `design-system-audit.md`: + +1. Inventory of what exists (foundations, elements, components, patterns) +2. Gap analysis +3. Fragmentation analysis +4. Drift analysis +5. Prioritized remediation plan +6. Governance recommendations + +--- + +## Reference files + +- [`references/system-architecture.md`](references/system-architecture.md) - The four-layer model (tokens, primitives, patterns, templates) and how to decide where new work belongs. +- [`references/system-audit-template.md`](references/system-audit-template.md) - Template for auditing an existing design system. +- [`references/governance-playbook.md`](references/governance-playbook.md) - Contribution model, ownership, and decision process for an active system. diff --git a/skills/design-system/references/governance-playbook.md b/skills/design-system/references/governance-playbook.md new file mode 100644 index 0000000..8d72e3b --- /dev/null +++ b/skills/design-system/references/governance-playbook.md @@ -0,0 +1,303 @@ +# Design System Governance Playbook + +A design system without governance decays. This playbook covers the operating model: who owns it, how changes happen, and how the system stays alive. + +--- + +## Ownership models + +Three common models. Pick based on team size and maturity. + +### Model 1: Dedicated team + +A standing team owns the system full-time. 2 to 5 people typically: a lead designer, a lead engineer, and supporting roles. + +Strengths: +- Highest velocity for system improvements +- Clear ownership, fast decisions +- Can take on big system-level initiatives + +Weaknesses: +- Expensive +- Risk of disconnection from product teams +- Risk of building what the team finds interesting vs. what consumers need + +When to use: Organizations with 10+ designers and 50+ engineers, where system inconsistency is a real cost. + +### Model 2: Federated / contribution model + +System is maintained by multiple teams contributing changes. A small core team (or one lead) reviews contributions and maintains the foundation. + +Strengths: +- Distributed effort +- Component owners are the people closest to the use case +- Prevents the "system team builds for itself" problem + +Weaknesses: +- Coordination overhead +- Inconsistent velocity +- Requires strong contribution norms or quality drifts + +When to use: Mid-sized teams (5 to 15 designers, 20 to 100 engineers), where multiple teams need a shared system but no single team can dedicate full-time effort. + +### Model 3: Single owner / part-time + +One person owns the system as part of their broader role. Common in startups and small teams. + +Strengths: +- No coordination cost +- Decisions happen instantly +- Cheap + +Weaknesses: +- System decays when owner is busy +- Bus factor of one +- Hard to scale + +When to use: Early-stage teams. Plan to migrate to Model 1 or 2 as the team grows. + +--- + +## Contribution model + +How new components, variants, or changes get added to the system. + +### Stages + +1. Proposal. A team that needs a new component or variant proposes it. Proposal includes: the use case, examples in the wild, why existing components don't suffice. + +2. Triage. System owner(s) decide: + - Accept: add to the system. Assign owner. + - Adapt existing: existing component should grow to cover this use case. + - Defer: valid request but not prioritized now. + - Reject: doesn't fit the system. Solve in a one-off way. + +3. Design. Component is designed in the system's style. Includes all states, variants, and accessibility requirements. + +4. Review. System owner reviews against system standards. Iterate. + +5. Build. Component is built in code (and Figma if not built there first). + +6. Document. Usage doc, API doc, examples, anti-patterns. + +7. Release. Versioned release. Changelog entry. Announcement to consumers. + +### Proposal template + +```markdown +# Component Proposal: [Name] + +## Use case +[What we're building. The user problem this UI element solves.] + +## Examples in the wild +[3 to 5 places where teams have built ad-hoc versions of this. Screenshots.] + +## Why existing components don't fit +[Specific reasons existing components are insufficient.] + +## Proposed component +[Sketch or description of the proposed component, variants, states.] + +## Owner +[Who will design, build, and maintain this component.] + +## Timeline +[When this is needed. Hard deadlines vs. nice-to-have.] +``` + +--- + +## Decision-making + +### Type 1: Reversible decisions + +Most component-level decisions. Made by the component owner with light input from the system team. + +Examples: a new variant, a tweak to a state, an additional prop on an existing component. + +Process: lightweight. Propose in the team channel, get one or two reactions, ship. + +### Type 2: One-way doors + +Decisions that affect the foundation or ripple across many components. + +Examples: changing a base token, deprecating a component, changing the naming convention. + +Process: written proposal, formal review, broader stakeholder input, documented decision in the decision log. + +### Decision log + +Every Type 2 decision gets logged: + +```markdown +# DSDR-001: [Decision title] + +Date: YYYY-MM-DD +Status: [Proposed / Approved / Rejected / Implemented] +Author: [Name] + +## Context +[What situation led to this decision.] + +## Options considered +1. [Option] - pros, cons +2. [Option] - pros, cons +3. [Option] - pros, cons + +## Decision +[What was decided.] + +## Reasoning +[Why this option won.] + +## Consequences +[What changes as a result. What new constraints exist.] + +## Revisit when +[Trigger condition that would warrant reopening this decision.] +``` + +This log becomes the institutional memory. Future system owners can understand why things are the way they are. + +--- + +## Versioning + +### Semantic versioning + +For systems shipped as code packages, semver works well: + +- Major (1.0.0 → 2.0.0): breaking changes. API changes. Visual changes that consumers must adapt to. +- Minor (1.0.0 → 1.1.0): new components or variants. Backward-compatible. +- Patch (1.0.0 → 1.0.1): bug fixes. Backward-compatible. + +### Release cadence + +Three patterns: + +- Continuous: ship as ready. Best for teams that can absorb frequent updates. +- Periodic: weekly or biweekly batched releases. Best for systems with many consumers. +- Major releases: quarterly major versions, with weekly patches between. Best for systems with breaking changes that need migration time. + +### Communication + +For each release: +- Changelog entry (what changed, why) +- Migration guide for breaking changes +- Internal announcement (Slack, email, internal newsletter) +- Demo or office hours for major changes + +--- + +## Deprecation + +Components get retired. Manage retirement explicitly. + +### Deprecation stages + +1. Warning. Component is marked deprecated. Documentation gains a deprecation notice. Build emits a console warning. + +2. Migration period. Defined window (typically 1 to 2 quarters) for consumers to migrate. Migration guide published. + +3. Removal. Component removed. Code deleted. Documentation archived (not deleted, for historical reference). + +### Deprecation notice template + +```markdown +> ⚠️ Deprecated: [Component] is deprecated as of [version]. +> Replacement: [link to replacement component] +> Removal: scheduled for [version / date] +> Migration guide: [link] +``` + +--- + +## Quality bar + +Every component or change must meet the bar before merging. + +### Functional +- [ ] Works at the documented breakpoints +- [ ] All variants and states implemented +- [ ] Keyboard navigation works +- [ ] Screen reader announces correctly +- [ ] Focus indicators visible +- [ ] Touch targets at least 44px +- [ ] Color contrast passes AA + +### Documentation +- [ ] Usage doc (when to use, when not to) +- [ ] API doc (props, types, defaults) +- [ ] Examples (basic, advanced, edge cases) +- [ ] Anti-patterns (what to avoid) + +### Consistency +- [ ] Uses tokens (no hardcoded values) +- [ ] Follows naming conventions +- [ ] Visual style matches the system +- [ ] Behavior matches similar components + +### Test +- [ ] Unit tests for component logic +- [ ] Visual regression test +- [ ] Accessibility test + +--- + +## Metrics + +Track the health of the system. + +### Adoption + +- Percentage of product UI built from system components vs. one-offs +- Per-team adoption rate +- Component usage frequency + +### Velocity + +- Time from proposal to release +- Number of accepted contributions per month +- Open proposals in queue + +### Quality + +- Open bugs against system components +- Accessibility issues count +- Drift incidents (components used in unsupported ways) + +### Consumer satisfaction + +- Internal survey: how useful is the system? +- What's missing? What blocks adoption? + +Run satisfaction survey at least annually. Use results to guide system priorities. + +--- + +## Sustaining the system + +A design system is a living thing. Without maintenance, it dies. + +### Weekly +- Triage incoming proposals +- Review consumer questions and feedback +- Address bugs + +### Monthly +- Release notes for any changes +- Office hours for consumer teams +- Component audit (one or two components reviewed in depth) + +### Quarterly +- Roadmap review +- Foundation review (token health, naming consistency) +- Adoption metrics review + +### Annually +- Strategic review (is the system serving its purpose?) +- Consumer satisfaction survey +- Major version planning + +The system is never finished. It evolves with the product, the team, and the brand. diff --git a/skills/design-system/references/system-architecture.md b/skills/design-system/references/system-architecture.md new file mode 100644 index 0000000..113081c --- /dev/null +++ b/skills/design-system/references/system-architecture.md @@ -0,0 +1,275 @@ +# System Architecture + +How the four layers of a design system relate, and how to decide where new things belong. + +--- + +## The four layers, top to bottom + +``` +┌──────────────────────────────────────────────────────────────┐ +│ TEMPLATES (full screens, complete flows) │ +│ Optional layer. Use when the same screen pattern recurs. │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PATTERNS (composed components solving a UI problem) │ +│ Examples: form layouts, modal dialogs, navigation, tables │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ PRIMITIVES (smallest reusable elements) │ +│ Examples: button, input, checkbox, badge, icon, link │ +└──────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────┐ +│ TOKENS (atomic named values) │ +│ Examples: color-text-primary, space-md, radius-card │ +└──────────────────────────────────────────────────────────────┘ +``` + +Higher layers consume lower layers. A primitive uses tokens. A pattern composes primitives (and tokens). A template assembles patterns. + +A token never references a primitive. A primitive never references a pattern. The dependency direction is one-way. + +--- + +## When to add at each layer + +### Add a token when: +- A value appears in 3+ places +- The value has a clear semantic purpose +- Changing the value should propagate everywhere it appears + +Example: "Card border radius" - if 12 components use 12px corner radius, that's a token. + +Counter-example: A one-off radius for a single decorative element. Hard-code it. + +### Add a primitive when: +- The same combination of HTML/JSX/View elements recurs in 3+ places +- The element has an internal state machine (open/closed, default/hover/disabled) +- Centralized accessibility logic helps consumers + +Example: Button. Recurs everywhere. Has states. Accessibility (focus, keyboard, ARIA) is non-trivial. + +Counter-example: A specific marketing hero block that only appears on the homepage. Not a primitive. Build it inline. + +### Add a pattern when: +- Multiple teams keep building the same composition +- The composition involves non-obvious decisions (z-index, focus management, scroll behavior, animation) +- A central pattern reduces accessibility risk + +Example: Modal dialog. Hard to get right (focus trap, escape, scroll lock). Pattern centralizes the hard parts. + +Counter-example: A specific dashboard layout used only on the analytics page. Not a pattern. Build it inline as a screen. + +### Add a template when: +- A full screen recurs across products or sections +- New product features want a starting point that already follows system rules + +Example: Settings page layout (left nav, content area, save bar). If the team builds 5 settings sections, the template saves time. + +Counter-example: A unique landing page. Not a template. + +--- + +## Decision tree: where does this belong? + +``` +Is it a value? ────── Yes ────── Token + │ + └── No + +Is it a single element? ── Yes ── Primitive + │ + └── No + +Is it composed of primitives? ─ Yes ─ Pattern + │ + └── No + +Is it a full screen? ──────── Yes ── Template +``` + +--- + +## Token tiering + +Most systems benefit from at least two tiers. Three is the maximum without diminishing returns. + +### Tier 1: Primitives + +Raw values, no semantic meaning attached. + +``` +color-blue-50 = #EFF6FF +color-blue-100 = #DBEAFE +color-blue-500 = #3B82F6 +color-blue-900 = #1E3A8A + +space-1 = 4px +space-2 = 8px +space-4 = 16px +space-8 = 32px + +radius-sm = 4px +radius-md = 8px +radius-lg = 12px +``` + +### Tier 2: Semantic + +Purpose-named, mapped to primitives. + +``` +color-text-primary = color-gray-900 +color-text-secondary = color-gray-600 +color-text-link = color-blue-700 +color-bg-surface = color-white +color-bg-elevated = color-white +color-border-default = color-gray-200 + +space-stack-tight = space-2 +space-stack-default = space-4 +space-stack-loose = space-6 +``` + +### Tier 3 (optional): Component-specific + +Component-tied, mapped to semantic tokens. + +``` +button-padding-x = space-stack-default +button-padding-y = space-stack-tight +button-radius = radius-md +button-bg-primary = color-bg-action-primary +``` + +Rule of thumb: Stop at Tier 2 unless the system is large enough to justify Tier 3 maintenance. Tier 3 adds clarity but multiplies token count. + +--- + +## Naming conventions + +Pick one and stay. The most common patterns: + +### Pattern A: Hierarchical with hyphens +``` +color-text-primary +color-text-secondary +color-bg-surface +space-stack-md +``` + +### Pattern B: Object/dot notation (often in JSON or JS) +``` +color.text.primary +color.bg.surface +space.stack.md +``` + +### Pattern C: Flat with prefix +``` +text-color-primary +bg-color-surface +stack-space-md +``` + +Hierarchical-with-hyphens (Pattern A) is the most common for CSS variable contexts. Pick once, document, never deviate. + +--- + +## Naming for the semantic layer + +Names should describe purpose, not appearance. "Color is what it is, name is what it does." + +Good: +- `color-text-primary` (what role does it play?) +- `color-bg-action-destructive` (what action is this for?) +- `space-stack-section` (where does it apply?) + +Bad: +- `color-blue-medium` (semantic name should not encode the value; that's the primitive layer's job) +- `color-pretty-blue` (subjective, not purpose) +- `color-button-text` (OK at component layer; too specific for semantic layer) + +--- + +## Versioning + +Use semantic versioning: `major.minor.patch`. + +- Patch: Bug fixes, no API changes. Bump for any defect fix. +- Minor: Additive changes. New tokens, new components, non-breaking API additions. +- Major: Breaking changes. Removed tokens, renamed APIs, behavioral changes consumers must adapt to. + +For breaking changes, provide: + +1. Deprecation warning in the previous minor version +2. Migration guide +3. Codemod or scripted migration path where possible +4. A timeline for sunset (typically 1 to 2 quarters) + +--- + +## Anti-patterns + +### Color sprawl +- 200 named colors instead of a tight palette of 30 to 50. +- Symptom: every designer adds the color they need. +- Fix: enforce primitive layer review before new colors land. + +### Spacing chaos +- 17 different spacing values, half of them within 2px of each other. +- Symptom: each design uses unconstrained spacing. +- Fix: a defined scale. New spacing values require a real reason. + +### Naming inconsistency +- `colorPrimary`, `color-primary`, `primary-color`, `primaryColor` all in the same system. +- Symptom: tokens added by different people without convention. +- Fix: pick one convention, document, automate validation. + +### Tokens without consumers +- 200 tokens defined, 50 actually used. +- Symptom: aspirational tokens added "for the future." +- Fix: only add tokens with current or near-future consumers. + +### Components without docs +- 30 components in the library, 5 have docs. +- Symptom: docs treated as separate work, deprioritized. +- Fix: docs blocking the merge of new components. + +### Patterns over-built +- A "DataTable" pattern with 47 props supporting every imaginable variation. +- Symptom: Trying to anticipate every use. +- Fix: ship narrow first. Expand based on real demand. Hard to remove options once shipped; easy to add. + +--- + +## Dependency directions + +A healthy system has these dependency rules: + +- Tokens depend on nothing. +- Primitives depend on tokens. +- Patterns depend on primitives and tokens. +- Templates depend on patterns, primitives, and tokens. +- Application code depends on any layer. + +Violations to flag: + +- A token referencing another token at a different tier (sometimes OK, often a smell). +- A primitive referencing a pattern. Wrong direction. +- A pattern not using primitives, building from raw HTML. Bypasses the system. +- Application code defining its own colors instead of using tokens. Bypasses the system. + +--- + +## How to introduce a system to an existing codebase + +If the codebase has no system today: + +1. Audit. Inventory existing UI. Find duplicates and inconsistencies. +2. Tokens first. Establish the token foundation. Migrate hard-coded values gradually. +3. Primitives second. Replace ad-hoc components with system primitives. Highest-impact ones first (button, input, modal). +4. Patterns third. Once primitives are established, codify patterns. +5. Migrate over multiple quarters. Rip-and-replace fails. Coexistence with gradual migration succeeds. + +Plan for the system to take 2 to 4 quarters to fully replace ad-hoc UI in a medium-sized product. Plan for it to never be "done" - it evolves with the product. diff --git a/skills/design-system/references/system-audit-template.md b/skills/design-system/references/system-audit-template.md new file mode 100644 index 0000000..625f9f5 --- /dev/null +++ b/skills/design-system/references/system-audit-template.md @@ -0,0 +1,258 @@ +# Design System Audit Template + +A template for auditing an existing design system. Use this to take stock of what exists, what is missing, what is duplicated, and what is silently broken. + +The output is an honest report, not a grade. The goal is a backlog the team can act on. + +--- + +## When to use this template + +- Before a major redesign or rebrand (knowing the starting state shapes the plan). +- When the system feels heavy or inconsistent and no one can articulate why. +- When a new owner takes over and needs ground truth. +- Quarterly, as a regular health check. + +--- + +## Audit scope + +Decide upfront what is in and out of scope. A full audit covers all four layers (tokens, primitives, patterns, templates) plus governance and adoption. A focused audit covers one or two. + +\| Layer / area \| In scope \| Out of scope \| +\|---\|---\|---\| +\| Tokens \| \| \| +\| Primitives \| \| \| +\| Patterns \| \| \| +\| Templates \| \| \| +\| Documentation \| \| \| +\| Governance \| \| \| +\| Adoption \| \| \| + +--- + +## Layer 1: Tokens + +### Inventory + +List every token category in the system. For each, count, source of truth, and platforms supported. + +\| Category \| Count \| Source of truth \| Platforms supported \| +\|---\|---\|---\|---\| +\| Color \| \| \| \| +\| Typography (font, size, weight, line-height) \| \| \| \| +\| Spacing \| \| \| \| +\| Radius \| \| \| \| +\| Shadow \| \| \| \| +\| Motion (duration, easing) \| \| \| \| +\| Z-index \| \| \| \| +\| Breakpoints \| \| \| \| +\| Other \| \| \| \| + +### Findings + +- [ ] Are tokens named by role (`color-text-primary`) or by value (`gray-900`)? Role-based scales better. +- [ ] Is there a single source of truth (one file, one tool) or multiple sources that drift? +- [ ] Are tokens versioned? How are breaking token changes communicated? +- [ ] Are there duplicate tokens (`color-blue-primary` and `color-action`)? List them. +- [ ] Are there orphan tokens (defined but unused)? List them. +- [ ] Are dark mode / theme variants modeled at the token layer or elsewhere? + +### Token risks + +- Hardcoded values in code: grep the codebase for raw hex, raw px values, raw font sizes. Note where tokens were skipped. +- Token sprawl: more than 20 named colors, more than 8 spacing values, or more than 6 font sizes is usually a smell. +- Naming inconsistency: `color-text` vs `text-color` vs `textColor` across categories. + +--- + +## Layer 2: Primitives + +### Inventory + +List every primitive component the system ships. For each, status and consumer count. + +\| Primitive \| Status (Production / Beta / Deprecated) \| Consumers (rough count) \| Notes \| +\|---\|---\|---\|---\| +\| Button \| \| \| \| +\| Input \| \| \| \| +\| Checkbox \| \| \| \| +\| Radio \| \| \| \| +\| Select \| \| \| \| +\| Textarea \| \| \| \| +\| Badge \| \| \| \| +\| Avatar \| \| \| \| +\| Icon \| \| \| \| +\| Link \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Are primitives accessible (keyboard, screen reader, focus management)? List failures. +- [ ] Are all primitives token-driven, or do some hardcode values? +- [ ] Are there duplicate primitives that do almost the same thing (`Button` and `IconButton` and `LinkButton`)? Could they consolidate? +- [ ] Are primitives documented (props, states, variants, accessibility)? +- [ ] Are there one-off primitives in product code that should be promoted to the system? + +--- + +## Layer 3: Patterns + +Patterns are composed components solving a specific UI problem. + +### Inventory + +\| Pattern \| Status \| Used by (rough page or feature count) \| Notes \| +\|---\|---\|---\|---\| +\| Form layout \| \| \| \| +\| Modal dialog \| \| \| \| +\| Toast / notification \| \| \| \| +\| Navigation (top, side) \| \| \| \| +\| Empty state \| \| \| \| +\| Pagination \| \| \| \| +\| Data table \| \| \| \| +\| Card \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Are patterns built from primitives, or do they reach around the primitives layer? +- [ ] Do multiple patterns solve the same problem with different APIs? +- [ ] Are patterns flexible enough for real product needs, or are teams forking them? + +--- + +## Layer 4: Templates + +Templates are full screens or flows. Optional layer. + +### Inventory + +\| Template \| Status \| Used by \| Notes \| +\|---\|---\|---\|---\| +\| Marketing landing \| \| \| \| +\| App shell \| \| \| \| +\| Settings page \| \| \| \| +\| Onboarding flow \| \| \| \| +\| Empty product state \| \| \| \| +\| (etc.) \| \| \| \| + +### Findings + +- [ ] Do templates exist at all? Many systems skip this layer. +- [ ] Are templates a starting scaffold or a rigid spec? +- [ ] Are template layouts responsive, or do teams reimplement responsive behavior each time? + +--- + +## Documentation + +### Inventory + +- Documentation site: [URL or "none"] +- Last meaningful update: [Date] +- Component coverage: [What % of shipped components are documented?] +- Code examples for every component: [Yes / partial / no] +- Accessibility notes for every interactive component: [Yes / partial / no] +- Migration / changelog: [Yes / no] + +### Findings + +- [ ] Is the documentation in sync with the shipped code, or has it drifted? +- [ ] Can a new engineer onboard from the docs alone, or do they need tribal knowledge? +- [ ] Is there a "do / do not" pattern with examples for each component? +- [ ] Are deprecated components clearly marked, with a migration path? + +--- + +## Governance + +- Ownership model: [Dedicated team / federated / single owner / unowned] +- Contribution process: [Documented / informal / nonexistent] +- Review cadence: [How often do owners look at incoming requests, bugs, drift?] +- Decision log: [Where are major design system decisions recorded? Or are they not?] +- Communication channel: [Slack channel / mailing list / standing meeting / none] + +### Findings + +- [ ] Who decides when a new component enters the system? +- [ ] Who decides when a component is deprecated? +- [ ] Who handles requests from product teams? What is the SLA? +- [ ] What happens when a product team needs something the system does not provide? + +--- + +## Adoption + +### Measurement + +\| Measure \| Today \| Target \| +\|---\|---\|---\| +\| % of UI built with system components \| \| \| +\| % of new features using system \| \| \| +\| Number of one-off components in product code \| \| \| +\| Number of token overrides in product code \| \| \| +\| Number of open issues against the system \| \| \| + +### Findings + +- [ ] Where is adoption strongest? Why? +- [ ] Where is adoption weakest? Why? (Often: missing components, too rigid, undocumented, or onboarding gap.) +- [ ] Are there teams actively forking or working around the system? + +--- + +## Risk register + +List the top 5 risks the audit surfaced. For each: severity (high / medium / low), affected area, and a one-line recommendation. + +\| # \| Risk \| Severity \| Affected area \| Recommendation \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| +\| 3 \| \| \| \| \| +\| 4 \| \| \| \| \| +\| 5 \| \| \| \| \| + +--- + +## Backlog + +Translate findings into a prioritized backlog. Keep items concrete and assignable. + +### Critical (block adoption or accessibility) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### High (consistent friction or duplication) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Medium (improvement, not blocking) + +- [ ] [Item, owner, target date] +- [ ] [Item, owner, target date] + +### Low (polish) + +- [ ] [Item, owner, target date] + +--- + +## Audit summary + +Three sentences. What is the overall state, what is the single most important thing to fix, and what should the team start now. + +> [State summary] +> [Most important fix] +> [Start now] + +--- + +## Sign-off + +Audit conducted by: [Name(s), date] +Reviewed with: [Stakeholders] +Next audit scheduled: [Date] diff --git a/skills/discovery-research-synthesis/SKILL.md b/skills/discovery-research-synthesis/SKILL.md new file mode 100644 index 0000000..be007e8 --- /dev/null +++ b/skills/discovery-research-synthesis/SKILL.md @@ -0,0 +1,265 @@ +--- +name: discovery-research-synthesis +description: "Turning research artifacts into actionable PM insight. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the decisions they are meant to inform. The discipline of moving from raw discovery data to clear product direction without losing signal in the synthesis or fabricating insight that was not actually there. Triggers on research synthesis, customer interview synthesis, user research analysis, discovery readout, research insights, sales call analysis, support ticket analysis, qualitative data analysis. Also triggers when a team has done research but cannot turn it into decisions, when synthesis is producing pretty decks but no roadmap movement, or when an upcoming PM decision needs to be grounded in research already conducted." +category: research +catalog_summary: "Synthesizing customer interviews, research notes, and support tickets into actionable PM decisions. Distinguishes data-dump (no synthesis) from insight-theater (overpolished narrative) from actionable synthesis (decision-grade clarity)" +display_order: 4 +--- + +# Discovery Research Synthesis + +A senior PM's playbook for turning research artifacts into decisions. Customer interviews, user research notes, support ticket reviews, sales call transcripts, survey data, in-app feedback, all synthesized into the product direction they are meant to inform. + +Most discovery research never produces decisions. The team conducts interviews; the transcripts pile up; a researcher hands product the raw artifacts (data-dump) or builds a polished readout deck (insight-theater); the deck gets a 30-minute review meeting and is never referenced again. Two months later the team is making the same product decisions that the research was supposed to inform, with the same gut-feel inputs the research was supposed to displace. + +The discipline is in the synthesis. Synthesis is where research earns its keep: where transcripts become tagged observations, observations cluster into patterns, patterns get named, named patterns surface product implications, and implications drive specific decisions. Without that sequence, research is performance art. + +This skill covers one-off discovery research projects: a 12-week customer development sprint, a sales-call review for an onboarding redesign, a support-ticket audit informing a roadmap quarter. Different from `user-feedback-aggregation`, which covers ongoing feedback streams; different from `jtbd-framing`, which is a specific framing technique often applied within synthesis but narrower in scope. + +The voice is the senior PM or staff product researcher who has run synthesis well and seen plenty of teams fail at it. Honest about where polish becomes performance and where pattern-naming slides into pattern-fabrication. + +When to use this skill: synthesizing a recent batch of customer interviews, auditing why prior research has not produced product decisions, designing the synthesis output for a multi-week discovery sprint, or establishing the synthesis discipline a team currently lacks. + +--- + +## What this skill is for + +This skill spans research-to-decision synthesis. The PM-skill distinction: + +- `discovery-research-synthesis` (this skill) is one-off research synthesis: turning a discrete batch of artifacts into a discrete set of decisions. +- `user-feedback-aggregation` is ongoing feedback streams: continuous synthesis across always-on channels (support, NPS, in-app, sales). +- `jtbd-framing` is a framing technique often applied during synthesis; this skill is broader. +- `pm-spec-writing` is downstream: specs use synthesized insights as input. +- `roadmap-planning` is downstream: roadmap uses synthesized priorities as input. +- `experiment-design` is the quantitative-validation discipline that often follows qualitative synthesis. + +The audience: senior PMs, product directors, in-house product teams, agencies running discovery work for clients, researchers handing off to product teams. + +What is not in scope: conducting the research itself (interview design, recruiting, moderation), the broader discovery strategy that decides which research to commission, or the long-running feedback channels that user-feedback-aggregation covers. + +--- + +## Data-dump vs insight-theater vs actionable-synthesis + +The keystone framing. Two failure modes plus the discipline. + +Data-dump. Research artifacts handed to the product team raw. "Here are 47 transcripts and a spreadsheet of tags; figure it out." No synthesis, no signal-finding, no implications drawn. The product team either does the synthesis itself (often badly, often months later) or skips it (the most common outcome). Output: a research investment that produced artifacts but not insight. + +Insight-theater. Overpolished synthesis dressed as insight. Pretty quote walls, designed personas, branded readout decks, no decision-driving conclusions. The research deck that gets a 30-minute review and never gets referenced. Synthesis that performed for the executive audience but did not inform the product audience. Cost: real research budget converted into a slide deck; the organization "did the research" without doing the research. + +Actionable-synthesis. Synthesis that drives decisions. Each pattern has a "so what" attached; each finding leads to a product implication; the document gets referenced in roadmap discussions, spec drafts, prioritization debates. The synthesis is short, opinionated, and load-bearing. Six months later, team members can quote the patterns that shaped what shipped and what got cut. + +The litmus test. Three months after a synthesis ships, can team members name the decisions the synthesis informed? If yes, the synthesis was actionable. If team members remember the deck but cannot name the decisions, it was insight-theater. If nobody remembers anything because the synthesis never happened, it was data-dump. + +--- + +## Discovery research types + +Five common research types, each with different artifacts and synthesis needs. + +Customer interviews. 30-90 minute structured or semi-structured conversations. Transcripts plus moderator notes plus recordings. Highest-quality qualitative data; most expensive to collect; most rewarding to synthesize when done well. Typical batch: 8-15 interviews per discovery cycle. + +Support ticket reviews. Auditing recent support tickets for patterns. Lower per-artifact richness than interviews; higher volume; surfaces the friction users actually hit (not just what they say in interviews). Typical batch: 100-500 tickets per audit. + +Sales call analysis. Recording or transcript review of recent sales calls. Surfaces objections, pricing-conversation patterns, competitive mentions, and the gap between marketing positioning and what sales actually leads with. Typical batch: 15-30 calls per audit. + +Survey data. Quantitative responses with optional qualitative comments. Best for validating qualitative patterns at scale; weak as primary discovery (surveys reveal what users say, not what they do). Typical batch: 100-2,000 responses. + +In-app feedback. Users submitting feedback through in-product channels. Volume is high; quality varies; signal lives in patterns across many low-effort submissions. Typical batch: ongoing; synthesized in periodic audits. + +Different research types compose. A discovery cycle often pairs interviews (depth) with support ticket review (volume) with survey data (validation at scale). The synthesis combines them. + +Detail in [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md). + +--- + +## The synthesis sequence + +Six stages from raw artifacts to decisions. Skipping stages is where synthesis fails. + +1. Transcribe and prepare. Convert artifacts into a synthesizable format. Interview recordings to transcripts; sales calls to summaries; support tickets to a tagged dataset. The prep work is unglamorous; teams that skip it never reach the later stages. + +2. Tag at the artifact level. Read each transcript or ticket and tag it with the topics, problems, and quotes that surface. First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. Tags are messy; that is fine. + +3. Cluster across artifacts. Group tags into themes. Multiple users mentioned the same friction; multiple tickets reference the same workflow; multiple interviews returned to the same struggling moment. The clusters surface the patterns. + +4. Name patterns. Each cluster becomes a named pattern. The naming is the work: a pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references. "Onboarding configuration friction" is a pattern name; "users had trouble" is not. + +5. Infer product implications. For each pattern, what does this imply for the product? Implications are the bridge from observation to decision. A pattern without an implication is a finding; a pattern with an implication is actionable input. + +6. Name the so-what. For each implication, the specific decision it informs. "Should we prioritize the onboarding redesign in Q2?" The so-what is what makes the synthesis decision-grade. + +The sequence is non-negotiable. Teams that skip tagging and jump to pattern naming hallucinate patterns; teams that skip implications produce findings without product direction; teams that skip so-what produce documentation, not synthesis. + +Detail in [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md). + +--- + +## Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. + +Tag at the artifact level first; do not pre-design the taxonomy. Tags emerge from the artifacts. Teams that arrive with a pre-built tag taxonomy ("we will tag for usability, performance, pricing, support") force artifacts into categories that may not fit the data, and miss patterns the taxonomy did not anticipate. + +Allow tag proliferation; collapse later. Early tagging may produce 80-150 tags across a batch. That is correct. The clustering stage collapses them. Premature consolidation ("we had 4 onboarding tags; let me merge them") loses distinctions that turn out to matter. + +Cluster on patterns, not on tag overlap. Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation: are these the same struggling moment, or do they share a tag because the tag was loose? + +Name the cluster after clustering, not before. The cluster name comes from the data, not from a hypothesis. Teams that arrive with named clusters and slot data into them produce confirmation; teams that name clusters from the data produce discovery. + +Tag dissent and contradictions explicitly. Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. Tag the dissent so the synthesis can address it. + +Detail in [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md). + +--- + +## Pattern naming + +The work that distinguishes synthesis from documentation. + +A pattern name is not a category label. "Onboarding" is a category. "Users abandon configuration before reaching the success state because the third configuration step requires data they do not have on hand" is a pattern. The pattern names the specific behavior the data reveals. + +The name should make the implication legible. A reader who sees only the pattern name should be able to guess the product implication. If the name is too abstract, the reader cannot reach the implication; if the name is too concrete, the synthesis becomes a list of micro-observations. + +Avoid category bloat. Synthesis with 30 named patterns is usually under-clustered: many of those patterns are variations on a smaller number of underlying patterns. Synthesis with 4 named patterns is often the right number; 6-8 is common; more than 12 is usually category bloat. + +Avoid naming the obvious. "Users want fast performance" is not a pattern; it is a truism. A pattern is a specific observation that the product team did not already know. If the pattern name reads as something everyone could have said before the research, the pattern is not a pattern. + +Name with conviction. Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly; they invite challenge and produce decisions. + +Detail in [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md). + +--- + +## From pattern to product implication + +The bridge from observation to decision. + +Pattern-to-implication is the writer's analytical work, not what the user said. Users do not state product implications; they describe their experience. The PM doing synthesis interprets the pattern and proposes the implication. The interpretation is where synthesis adds value beyond transcription. + +Each pattern can have multiple implications. A pattern about onboarding friction might imply a redesign of the configuration flow, or default-data pre-population, or staged onboarding. The synthesis surfaces the options; the prioritization decision picks one. + +Implications should be falsifiable. A vague implication ("we should improve onboarding") is not actionable. A specific implication ("staged onboarding that defers the third configuration step until after the user reaches the first success state") is. Specific implications can be debated, scoped, prioritized. + +Implications should acknowledge cost. Patterns suggest solutions; solutions cost product capacity. Synthesis that implies 30 product changes without acknowledging that delivering them all is impossible is not synthesis; it is a wishlist. + +Some patterns imply not-acting. Sometimes the pattern reveals friction the team should not address: it affects too few users, it represents segment misfit, addressing it would compromise other priorities. Naming the not-act implication is honest synthesis. + +Detail in [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md). + +--- + +## Writing for decisions, not deck performance + +Synthesis output should be optimized for decision use, not for presentation. + +Document, not deck. Deck format is poor for synthesis: slides cannot carry argument density; readers cannot reference slides later; decks decay into icons and bullet points. A short document (4-12 pages) carries more usable synthesis than a 60-slide deck. + +Lead with patterns and implications; relegate evidence to appendix. A reader scanning for decision input wants the patterns and implications first. Evidence (quotes, ticket excerpts, data tables) supports the patterns but does not lead. Decks that lead with quote walls have inverted the reader's needs. + +One section per pattern. Each pattern gets a short section: pattern name, evidence summary (2-3 sentences with link to full evidence in appendix), implication, so-what decision input. + +Be opinionated. Synthesis that hedges every pattern reads as a researcher avoiding accountability. Synthesis that commits positions invites challenge and produces decisions. The PM doing synthesis is making a recommendation; readers can disagree, but disagreement is the point. + +Include a decision-input section. What does this synthesis recommend the team do? Where should priorities shift? Which roadmap items does this validate, which does it challenge? The decision-input section is the synthesis's reason for existing. + +Detail in [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md). + +--- + +## The synthesis review and validation loop + +How the synthesis gets pressure-tested before it drives decisions. + +Internal review with the research participants where possible. Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? Misrecognition signals the synthesis fabricated patterns or projected interpretations the data did not support. + +Adjacent-team review. Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? Adjacent teams catch synthesis errors that the research team missed. + +Quantitative validation where possible. Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. The pattern says X; does the data confirm X happens at the frequency and severity the pattern implies? See `experiment-design` and `product-analytics-setup` for the quantitative methodology. + +The "challenge the synthesis" session. A specific session where adjacent teams try to find the patterns the synthesis missed, the implications the synthesis overstated, the decisions the synthesis is railroading. Productive disagreement strengthens the synthesis. + +Iterate before publishing. Synthesis goes through revision based on the review loop. Synthesis that ships in the first draft state usually carries unacknowledged blind spots. + +Detail in [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md). + +--- + +## When to halt and gather more data + +Synthesis sometimes reveals that the research did not collect enough. + +Pattern thinness. A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. Either name the pattern as tentative pending more data, or pause synthesis and gather more research. + +Segment under-representation. The research overrepresents one user segment and underrepresents another that matters for the decision. Patterns from the represented segment may not apply to the underrepresented one. + +Contradictory clusters. Two clusters point in opposite directions and the data does not resolve the contradiction. Often signals a sub-segment difference that the research did not investigate enough. + +Decision time pressure. Synthesis revealing data gaps but the decision has to ship before more research can happen. Honest path: name the data gap explicitly in the synthesis, make the recommendation with the gap acknowledged, plan the follow-up research that would validate or revise. + +The "we have enough" trap. Teams that have invested in research often want to declare the data sufficient even when the synthesis reveals gaps. The discipline is naming gaps even when uncomfortable. + +Detail in [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md). + +- "We did the research but never made decisions from it." Data-dump or insight-theater; synthesis sequence skipped or stopped at findings. +- "Our synthesis deck got a polite review and was never referenced again." Insight-theater; output was performative rather than load-bearing. +- "We have 30 named patterns and no clear priorities." Category bloat; under-clustering; cure: re-cluster to 4-8 underlying patterns. +- "Every pattern reads as something we already knew." The synthesis named truisms, not patterns. Re-examine the data for what was actually surprising. +- "The patterns contradict each other and we cannot reconcile them." Often segment misfit; consider whether the contradictions reveal sub-segments with different needs. +- "Research participants did not recognize themselves in our synthesis." Synthesis fabricated patterns or projected interpretations not in the data. Restart with closer evidence-tracking. +- "The synthesis is detailed but the team cannot tell what to do." Implications missing or vague; cure: each pattern gets a specific falsifiable implication. +- "We hedged every pattern and the synthesis reads as wishy-washy." Hedge stacking; the synthesis avoided commitment. Rewrite with conviction. +- "Our quote walls were impressive but the deck was 60 slides." Insight-theater; cure: 8-page document with quotes in appendix. +- "The synthesis recommended 20 product changes; we shipped one." Wishlist synthesis; did not acknowledge cost; cure: prioritize within the synthesis. +- "Adjacent teams disagreed with our patterns and we did not engage." Review loop skipped; cure: make adjacent-team review non-negotiable before shipping. + +--- + +## The framework: 12 considerations for discovery synthesis + +When designing or auditing a synthesis output, walk these 12 considerations. + +1. Actionable-synthesis, not data-dump or insight-theater. Synthesis that drives decisions. +2. Research types matched to questions. Interviews, support, sales calls, surveys, in-app combined deliberately. +3. The synthesis sequence: transcribe, tag, cluster, name, imply, so-what. No stage skipped. +4. Tags emerge from artifacts; taxonomy not pre-designed. +5. Tag proliferation allowed; clustering collapses. +6. Patterns named with conviction; not categories or truisms. +7. Each pattern produces a specific falsifiable product implication. +8. Each implication has a so-what tied to a real decision. +9. Output is a document, not a deck. Patterns lead; evidence in appendix. +10. Synthesis is opinionated. Hedges flagged; conviction shown. +11. Review loop before publish. Participants, adjacent teams, quantitative validation where available. +12. Data gaps named, not buried. Where research did not support a position, the synthesis says so. + +The output of the framework is a synthesis the team can act on: short, opinionated, evidence-grounded, decision-driving, accountable to challenge. + +--- + +## Reference files + +- [`references/research-types-and-when-each-fits.md`](references/research-types-and-when-each-fits.md) - Five research types with synthesis implications. Composition patterns across types within a discovery cycle. +- [`references/synthesis-sequence-walkthrough.md`](references/synthesis-sequence-walkthrough.md) - The six-stage sequence with worked example. Stage outputs, common skip-failures, time investment per stage. +- [`references/tagging-and-clustering-discipline.md`](references/tagging-and-clustering-discipline.md) - Tag-at-artifact-level discipline, allow tag proliferation, cluster on patterns not overlap, name after clustering, tag dissent. +- [`references/pattern-naming-patterns.md`](references/pattern-naming-patterns.md) - Pattern names that work and fail. Avoiding category bloat, naming-with-conviction, the implication-legibility test. +- [`references/from-pattern-to-product-implication.md`](references/from-pattern-to-product-implication.md) - The bridge from pattern to implication. Falsifiability, multi-implication patterns, cost acknowledgment, the not-act implication. +- [`references/writing-for-decisions-not-decks.md`](references/writing-for-decisions-not-decks.md) - Document over deck, patterns lead, evidence appendix, opinionated voice, decision-input section. +- [`references/synthesis-review-and-validation.md`](references/synthesis-review-and-validation.md) - Participant review, adjacent-team review, quantitative validation, the challenge-the-synthesis session, iteration before publish. +- [`references/when-to-gather-more-data.md`](references/when-to-gather-more-data.md) - Pattern thinness, segment under-representation, contradictory clusters, decision time pressure, the we-have-enough trap. +- [`references/common-discovery-synthesis-failures.md`](references/common-discovery-synthesis-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: synthesis is where research earns its keep + +Discovery research is one of the most expensive activities a product team commissions. The expense is mostly hidden: customer time, researcher time, the opportunity cost of the discovery cycle itself, the management overhead of recruiting and scheduling. Most of that expense gets spent before synthesis even begins. + +The teams that earn returns on the research investment are the teams that take synthesis seriously: the sequence is run end-to-end, the patterns are named with conviction, the implications are falsifiable, the so-what ties to specific decisions, the output is a load-bearing document the team references for months. The teams that do not earn returns produce data-dumps or insight-theater; their research becomes documentation of work done rather than the input to work to come. + +When in doubt about whether a synthesis is ready, ask: are the patterns named with conviction, do they reach product implications, do the implications tie to specific decisions, has the synthesis been reviewed by participants and adjacent teams, are the data gaps named honestly? If yes to all of those, the synthesis is real. If no to any, the gap is where the research investment will fail to convert into decisions. diff --git a/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md b/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md new file mode 100644 index 0000000..a7b35c6 --- /dev/null +++ b/skills/discovery-research-synthesis/references/common-discovery-synthesis-failures.md @@ -0,0 +1,193 @@ +# Common discovery synthesis failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most synthesis failures share a single root, which is treating synthesis as documentation work rather than as decision work. + +--- + +## Failure 1: We did the research but never made decisions from it + +Symptom. Discovery cycle completed; transcripts and notes filed; the team's roadmap discussions in the following months never reference the research. + +Diagnosis. Data-dump or insight-theater pattern. Synthesis sequence either skipped entirely (data-dump) or stopped at findings without reaching decisions (insight-theater). + +Cure. Run the synthesis sequence end-to-end on the existing artifacts. Even months after the original research, retroactive synthesis can produce decisions the original research was meant to inform. + +Prevention. Before commissioning the next research cycle, name the decisions the research is intended to inform. Build the synthesis sequence into the discovery plan, not as an afterthought. + +--- + +## Failure 2: Our synthesis deck got a polite review and was never referenced again + +Symptom. A polished readout deck. A 30-minute presentation. Positive feedback in the meeting. Six months later nobody references the synthesis in product decisions. + +Diagnosis. Insight-theater. Output was performative rather than load-bearing. Optimized for the presentation moment, not for reference use. + +Cure. Convert the deck content into a document with patterns leading, evidence in appendix, decision-input section. Recirculate as a reference document. + +Prevention. Future synthesis ships as documents, not decks. The presentation is a deck if needed; the synthesis is the document. + +--- + +## Failure 3: We have 30 named patterns and no clear priorities + +Symptom. The synthesis lists many patterns. The team agrees they are interesting but cannot prioritize. The synthesis fails to drive a roadmap shift. + +Diagnosis. Category bloat. Under-clustering produced inflation. Many of the 30 patterns are variations on a smaller number of underlying patterns. + +Cure. Re-cluster. Take the pattern list back to the clustering stage and look for the 4-8 underlying patterns the data actually supports. Synthesize from the consolidated list. + +Prevention. Cap pattern count at 4-8 for typical synthesis. When more than 8 patterns emerge, that is a signal to recluster, not to ship with bloat. + +--- + +## Failure 4: Every pattern reads as something we already knew + +Symptom. The synthesis names patterns that read as truisms. Team members who attended the readout could have produced the patterns without the research. + +Diagnosis. Pattern names captured truisms rather than the specific observations the research surfaced. The analytical work of pattern naming was skipped. + +Cure. Re-examine the data for what was actually surprising. Often the strongest patterns surface in the contradictions, the unexpected sub-segments, the workarounds users built. Pattern names should commit positions the team would not have committed before the research. + +Prevention. During pattern naming, apply the "what the team did not know" test. Patterns that read as common-knowledge are probably under-named. + +--- + +## Failure 5: The patterns contradict each other and we cannot reconcile them + +Symptom. Two patterns point in opposite directions. The synthesis is silent on the contradiction or hand-waves it. + +Diagnosis. Often segment misfit: different segments have different needs, and the synthesis did not surface the segment distinction. Sometimes context misfit: different use contexts produce different patterns. + +Cure. Re-examine the data for the segment or context dimension that explains the contradiction. The contradiction often becomes the most valuable finding once explained. + +Prevention. Tag dissent and contradictions explicitly during the tagging stage. Surface them through clustering. Address them in synthesis rather than burying them. + +--- + +## Failure 6: Research participants did not recognize themselves in our synthesis + +Symptom. When shown the synthesis, participants say "I did not say that" or "this does not match my experience." + +Diagnosis. Synthesis fabricated patterns or projected interpretations not in the data. The pattern naming reached for what the team wanted to find rather than what the participants actually said. + +Cure. Restart with closer evidence-tracking. Each pattern should be traceable to specific moments in specific artifacts. Patterns that cannot be traced are projections, not observations. + +Prevention. Build participant review into the synthesis process. Synthesis that participants do not recognize fails the validation; revise before publishing. + +--- + +## Failure 7: The synthesis is detailed but the team cannot tell what to do + +Symptom. Patterns are clear and well-supported. The team agrees on the patterns. The team cannot derive the product implications. + +Diagnosis. Implications missing or vague. The synthesis stopped at observations without bridging to product responses. + +Cure. Add implications to each pattern. Each implication should be specific, falsifiable, cost-acknowledged, and tied to a specific decision. + +Prevention. The synthesis sequence's implication stage is non-negotiable. Synthesis that ships without implications is incomplete. + +--- + +## Failure 8: We hedged every pattern and the synthesis reads as wishy-washy + +Symptom. "Users may sometimes occasionally seem to indicate." Every claim caveated. The synthesis avoids commitment. + +Diagnosis. Hedge stacking. The researcher did not commit to what the data showed. + +Cure. Rewrite with conviction. Name patterns as if the data supports them. If the data does not support the position, name a smaller position the data does support; do not hedge an oversized claim. + +Prevention. During pattern naming, apply the conviction test. Hedge stacking signals a pattern that should either be sharpened or dropped. + +--- + +## Failure 9: Our quote walls were impressive but the deck was 60 slides + +Symptom. Beautiful quote pulls; designed personas; 60 slides. Readers admired the deck. Few remember the patterns. + +Diagnosis. Insight-theater. Evidence dominated; analysis receded. Quote walls without analytical bridge. + +Cure. Restructure as a document. Patterns lead; evidence in appendix. Quote walls converted into evidence-summary paragraphs supporting each pattern. + +Prevention. The format choice is upstream. Default to documents; reserve decks for short executive summaries paired with substantive documents. + +--- + +## Failure 10: The synthesis recommended 20 product changes; we shipped one + +Symptom. Synthesis presents many implications. Team picks the easiest or most-vocal one to ship. The rest sit in the synthesis document unaddressed. + +Diagnosis. Wishlist synthesis. Implications did not acknowledge cost or prioritize within themselves. The synthesis offloaded prioritization to the team without giving them a starting point. + +Cure. Re-prioritize within the synthesis. Each implication gets a cost note. The synthesis recommends a sequence: which implications to address now, which to defer, which to drop. The team has a starting point for prioritization. + +Prevention. During implication writing, surface cost. The synthesis owner uses available context to estimate cost; pairs with engineering for harder estimates. Cost-blind synthesis is incomplete. + +--- + +## Failure 11: Adjacent teams disagreed with our patterns and we did not engage + +Symptom. Synthesis ships. Support team says "this does not match what we see in tickets." Sales team says "our prospects say something different." The synthesis fails to align with the teams closest to the customer. + +Diagnosis. Adjacent-team review skipped or compressed. The synthesis reached publication without surfacing perspectives the research team did not have. + +Cure. Pause publication. Run the adjacent-team review even after the fact. Revise based on inputs. + +Prevention. Build adjacent-team review into the synthesis workflow. Make it non-negotiable. The teams closest to the customer have ground-truth observations the research team needs. + +--- + +## Failure 12: Data gaps buried in the synthesis + +Symptom. Synthesis presents conclusions where the data did not support them. The recommendations sound confident; the data is thin in places the synthesis did not name. + +Diagnosis. The we-have-enough trap. Sunk-cost reasoning suppressed honest gap-naming. + +Cure. Audit each pattern for data sufficiency. Where gaps exist, name them explicitly. Where recommendations rest on under-supported patterns, downgrade or hedge them honestly. + +Prevention. The synthesis owner's job is to be honest about what the data can and cannot support. The team relies on the synthesis owner for this honesty. + +--- + +## Failure 13: Synthesis sequence stages skipped + +Symptom. Synthesis arrives at "patterns" without going through the tagging and clustering stages. Patterns feel imposed on the data rather than emerging from it. + +Diagnosis. Stages skipped. Researcher jumped to pattern-naming based on impressions from reading transcripts. + +Cure. Restart the sequence from tagging. Patterns from skipped sequences are usually projections; tagging-grounded patterns are observations. + +Prevention. The sequence is non-negotiable. Every synthesis runs through transcribe, tag, cluster, name, imply, so-what. + +--- + +## Failure 14: Synthesis owner became defensive in the review + +Symptom. Adjacent teams raise concerns; synthesis owner argues against each one; the review session produces no revisions; synthesis ships unchanged. + +Diagnosis. Defensive review posture. The owner treated review as defense of the synthesis rather than as input to it. + +Cure. Owner takes notes; does not defend in the moment; revises based on inputs over the following days. Reviewer concerns surface in the revision; the synthesis improves. + +Prevention. Establish the review session's purpose explicitly: input, not approval. The synthesis owner's job in the session is to listen. + +--- + +## The cross-cutting pattern + +Most synthesis failures share a single root: treating synthesis as documentation work rather than as decision work. + +Documentation work prioritizes capturing the research; producing a deliverable; performing for an audience. Output: artifacts that look like synthesis but do not drive decisions. + +Decision work prioritizes producing direction; committing positions; informing prioritization. Output: synthesis that team members reference for months, that drives roadmap shifts, that earns the research investment. + +The fix for almost any synthesis failure starts with the same question: what decision is this synthesis supposed to inform? When the answer is clear, the synthesis becomes load-bearing. When the answer is "we should document the research," the synthesis fails as decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting documentation-vs-decision pattern. + +## Implementation choices that stay internal + +Specific reviewer training on synthesis-failure detection. Specific automation that flags synthesis structures (e.g., document length checks, hedge-frequency analysis). Specific reviewer dashboards. The team's own conventions for catching synthesis failures pre-publish. These vary by team. diff --git a/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md b/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md new file mode 100644 index 0000000..1ed2d6b --- /dev/null +++ b/skills/discovery-research-synthesis/references/from-pattern-to-product-implication.md @@ -0,0 +1,192 @@ +# From pattern to product implication + +The bridge from observation to decision. Implications are where synthesis adds value beyond transcription. + +A pattern without an implication is a finding. A finding describes the world; an implication proposes action. Synthesis stops at findings; actionable synthesis reaches implications. + +--- + +## Implications are the writer's analytical work, not what the user said + +The principle. Users describe their experience; PMs interpret what experience implies for the product. + +Why this matters. A common synthesis failure is presenting implications as if they came from users. "Users want X" treated as an implication. But users do not always know what would actually solve their problem; they describe symptoms, not solutions. + +Worked example. A pattern: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +- What users said: "I had to stop and find my credit card." +- What users want (per their own description): "Make signup not require credit card details." +- What the implication actually is (PM analytical work): defer the credit-card-requiring step to after first success state, OR remove the credit card requirement at signup, OR allow signup without credit card and request it before paid features. + +The implication options surface from analytical interpretation, not from user prescription. Users said the symptom; the PM proposes the system response. + +The discipline. Frame implications as the team's analytical position grounded in the pattern, not as user requests. "The pattern implies X" rather than "Users want X." + +--- + +## Each pattern can have multiple implications + +The principle. Synthesis surfaces options; the prioritization decision picks one. + +Worked example. A pattern: "Free users hit the upgrade prompt before experiencing paid value." + +Possible implications: + +- Delay the upgrade prompt until after the user has experienced the value-realization moment. +- Show the upgrade prompt earlier but reframe it as exploratory rather than transactional. +- Add a value-realization moment earlier in the free experience to align with the existing prompt timing. +- Remove the upgrade prompt entirely; let users discover paid features through usage. + +Each implication is a different product response. The synthesis presents the options; the team's prioritization debate picks one (or sequences several). + +Why multi-implication matters. Single-implication synthesis presents the synthesizer's preferred solution as if it were the only solution. Multi-implication synthesis surfaces options the team can debate. + +The presentation. Per pattern, surface 2-4 candidate implications. Acknowledge tradeoffs between them. Recommend if the data supports a recommendation; otherwise present the options for prioritization. + +--- + +## Implications should be falsifiable + +The principle. A vague implication cannot be acted on or debated. A specific implication can. + +Vague implications. + +- "We should improve onboarding." +- "Pricing should be reconsidered." +- "Mobile experience needs attention." + +These are too vague to drive decisions. The team agrees to "improve onboarding" without committing to any specific change. + +Falsifiable implications. + +- "Defer configuration step 3 to after first success state." +- "Add a value-realization moment within the first 90 seconds of signup." +- "Make the homepage hero copy lead with B2B use cases." + +These commit specific positions. The team can debate them, scope them, kill them, prioritize them. + +The test. For each implication, ask: could the team disagree with this and explain why? If the implication is vague enough that disagreement is impossible, the implication is too vague to be useful. + +--- + +## Implications should acknowledge cost + +The principle. Patterns suggest solutions; solutions cost product capacity. Synthesis that ignores cost produces wishlists. + +The pattern that fails. Synthesis recommends 30 product changes without acknowledging that delivering them all is impossible. The team takes one or two; the rest sit. The synthesis produced no actionable input because the team had no help prioritizing. + +The pattern that works. Each implication includes an estimated cost dimension and a recommendation about whether the cost is justified. + +- "Defer configuration step 3 (medium engineering cost; high expected impact on signup conversion)." +- "Pre-populate step 3 with sensible defaults (low engineering cost; medium expected impact)." +- "Remove credit card requirement entirely (high cost across systems; uncertain impact)." + +The cost annotations help the team prioritize without re-doing the synthesis work. + +The discipline. PMs doing synthesis usually have enough context to estimate cost roughly. If they do not, they can pair with engineering to estimate. Cost-blind synthesis is incomplete. + +--- + +## Some patterns imply not-acting + +The principle. Sometimes the pattern reveals friction the team should not address. + +When not-acting is honest. + +- The friction affects too few users to justify the engineering cost. +- The friction reveals segment misfit; the affected users are not the team's target. +- Addressing the friction would compromise other priorities or product positioning. +- The friction is real but the proposed solutions are worse than the problem. + +Worked example. A pattern: "Enterprise users want admin controls that small-team users do not need." + +Implications: + +- Build the admin controls (high cost, expands target market). +- Build the admin controls only for the enterprise tier (medium cost, segment-specific). +- Do not build (acknowledges enterprise as not the target segment). + +If the team is committed to small-team users as the target market, the not-act implication is honest; building enterprise admin controls would dilute focus. + +The naming discipline. When the synthesis recommends not-acting, name it explicitly. "The pattern is real but the recommended response is to not address it because [reason]." Buried not-act implications get overlooked; the team adds the unaddressed friction to the next quarter's roadmap because nobody surfaced the not-act case. + +--- + +## Implications that bridge to specific decisions + +The principle. The strongest implications point to a specific decision the team is making. + +Implication-to-decision mapping. + +- Implication: "Defer configuration step 3." + - Decision input: should the Q2 roadmap include the onboarding redesign? (Yes, with this approach.) +- Implication: "Add B2B-leading homepage hero." + - Decision input: should the homepage redesign be prioritized this quarter? (Yes, with positioning shift.) +- Implication: "Do not address enterprise admin controls." + - Decision input: should enterprise tier be in this year's roadmap? (No; small-team focus continues.) + +Why decision-mapping matters. Implications floating free of decisions produce a list the team must connect to its prioritization work themselves. Implications mapped to decisions produce direct input. + +--- + +## Implication strength and confidence + +The principle. Not all implications are equally well-supported. + +Strong implications. + +- Pattern is supported by multiple research types (interviews + tickets + survey). +- Implication has a clear analytical bridge from the pattern. +- Cost is reasonable relative to expected impact. +- Decision input is clear. + +Weaker implications. + +- Pattern is supported by limited evidence (3 interviews; thin volume). +- Implication is one of several plausible options without clear analytical bridge. +- Cost is uncertain. +- Decision input is hedged. + +The discipline. Synthesis labels implications by strength. Strong ones get presented as recommendations; weaker ones as options for further investigation. The team can prioritize confidently when it knows which implications carry weight. + +--- + +## Common pattern-to-implication failures + +Implications that restate the pattern. "The pattern shows X. The implication is X." No analytical bridge; no value added. + +Wishlist implications. Synthesis recommends 30 changes; the team cannot prioritize; one or two ship; the rest sit. + +Implications buried in narrative. The synthesis discusses the pattern at length; the implication is one sentence at the end. Readers miss it. + +No cost acknowledgment. Implications presented as if all are equal cost; team has to do the cost analysis itself. + +Skipping the not-act implication. Synthesis recommends action on every pattern; some patterns warrant not-acting; the synthesis fails to surface this honestly. + +Implications that prescribe specific designs. Implications should propose product responses, not detailed designs. Detailed designs are for spec writing; implications are the upstream input. + +--- + +## The implication-quality audit + +A short framework for auditing implications. + +1. Is each implication an analytical proposition, not a user request? +2. Are multiple candidate implications surfaced where appropriate? +3. Is each implication specific enough to be falsifiable? +4. Does each implication acknowledge cost? +5. Where the data supports not-acting, is that surfaced honestly? +6. Does each implication map to a specific decision? +7. Is implication strength labeled? + +Synthesis that passes this audit converts research into decisions. Synthesis that fails it produces findings that look like decisions but do not drive them. + +--- + +## Methodology-level choices that stay in the public skill + +The implication-as-analytical-work principle. Multi-implication patterns. Falsifiability. Cost acknowledgment. The not-act implication. Decision mapping. Implication strength. Common failures. The audit. + +## Implementation choices that stay internal + +Specific document templates that surface implications. Specific cost-estimation conventions. Specific cross-functional review patterns for cost validation. The team's own conventions for implication-strength labeling. These vary by team. diff --git a/skills/discovery-research-synthesis/references/pattern-naming-patterns.md b/skills/discovery-research-synthesis/references/pattern-naming-patterns.md new file mode 100644 index 0000000..26d6aac --- /dev/null +++ b/skills/discovery-research-synthesis/references/pattern-naming-patterns.md @@ -0,0 +1,178 @@ +# Pattern naming patterns + +Pattern naming is the work that distinguishes synthesis from documentation. A pattern named badly disappears into the synthesis; a pattern named well becomes the framing the team references for months. + +The naming is not formatting. It is analytical work that surfaces what the data actually shows. Most synthesis underperforms because the pattern names did not do this work. + +--- + +## A pattern name is not a category label + +The principle. Categories describe topics; patterns describe specific observations the data reveals. + +Examples. + +- Category: "Onboarding." +- Pattern: "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." + +- Category: "Pricing." +- Pattern: "Free users hit the upgrade prompt before they have experienced the paid value, producing churn instead of conversion." + +- Category: "Mobile." +- Pattern: "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +Why categories fail as pattern names. Categories are containers. The synthesis with category-named patterns is a list of containers, not a list of observations. Readers cannot tell what the data showed; only what topic it concerned. + +The test. Does the pattern name commit a position about what the data reveals, or does it merely name a topic the data covered? Position-committing names are patterns; topic-naming labels are categories. + +--- + +## The name should make the implication legible + +The principle. A reader who sees only the pattern name should be able to guess the product implication. + +Examples that pass the test. + +- "Users abandon configuration step 3 because credit card details are not accessible during signup." + - Implication a reader can guess: defer configuration step 3 to after first success state, or remove credit card requirement at signup. +- "Sales prospects assume the product is for B2C because the homepage hero shows consumer use cases." + - Implication a reader can guess: revise homepage positioning to lead with B2B use cases. + +Examples that fail the test. + +- "Onboarding has issues." +- "Users have feedback about pricing." +- "There is mobile-related friction." + +Why implication-legibility matters. Synthesis exists to drive decisions. Pattern names that obscure implications force readers to do the analytical work themselves; many readers will not, and the synthesis fails to inform decisions. + +--- + +## Avoid category bloat + +The principle. Strong synthesis has 4-8 named patterns. Synthesis with 30 patterns is usually under-clustered: many of those are variations on a smaller number of underlying patterns. + +Diagnosis of bloat. + +- Look at the pattern list. Are some patterns sub-cases of others? If yes, the under-cluster is producing inflation. +- Are there patterns that always co-occur with other patterns? If yes, they may be the same pattern viewed from different angles. +- Are there patterns supported by 1-2 artifacts only? If yes, they may be noise being elevated to pattern status. + +The cure. Re-cluster. Take the 30-pattern list back to clustering and look for the 4-8 underlying patterns the data actually supports. + +Why bloat fails. Synthesis with 30 patterns produces no decision direction: the team cannot prioritize 30 things. Synthesis with 4-8 patterns surfaces what to focus on. + +--- + +## Avoid naming the obvious + +The principle. A pattern is a specific observation that the product team did not already know. Pattern names that read as truisms ("users want fast performance") are not patterns. + +The truism trap. + +- "Users want better performance." +- "Users find some aspects confusing." +- "Pricing is a consideration in the decision." +- "Mobile usage is increasing." + +These are descriptive of the universe; they do not describe what the research revealed. + +The cure. For each pattern name, ask: would this name have been just as accurate without the research? If yes, the pattern is a truism. The research must have surfaced something more specific; rewrite the name to capture it. + +The "what the team did not know" test. Strong pattern names commit a position the team would not have made before the research. Weak pattern names commit positions the team already held. + +--- + +## Name with conviction + +The principle. Hedged pattern names ("users sometimes seem to maybe struggle with...") signal a researcher who did not commit to what the data showed. Patterns named with conviction are more useful even if they overstate slightly. + +Hedging vs precision. + +- Hedged: "Some users may experience occasional difficulty in some configuration steps." +- Precise: "Users abandon configuration step 3 in 40% of signup attempts." + +The precise name is also commitment-bearing: it claims a specific behavior at a specific frequency. If the data does not support 40%, the name is wrong; the researcher should restate. The hedged name avoids being wrong by avoiding being specific. + +Why conviction matters. Synthesis that hedges every pattern reads as a researcher avoiding accountability. Readers cannot debate hedged patterns; they cannot prioritize them; they cannot act on them. Conviction-named patterns invite challenge, which strengthens synthesis. + +The discipline. Name as if the data fully supports the position. If it does not, name a smaller position the data does support. Do not pad an under-supported position with hedging. + +--- + +## Pattern naming structures that work + +Several structures recur across strong synthesis. + +The behavioral observation: "Users [do specific action] because [specific cause]." + +Example: "Users abandon configuration step 3 because credit card details are not accessible during signup." + +This structure forces specificity in both behavior and cause. + +The contradiction: "Users [say X] but [do Y]." + +Example: "Users in interviews report wanting more configuration options, but in support tickets request defaults that match their actual usage." + +This structure surfaces the gap between stated preference and revealed preference. + +The segment difference: "[Segment A] [does X], while [Segment B] [does Y]." + +Example: "Free users hit the upgrade prompt before experiencing paid value, while paid users encounter it after the value-realization moment." + +This structure surfaces sub-segment patterns the research revealed. + +The mismatch: "[Team's framing] does not match [user's framing]." + +Example: "Marketing positions the product as B2C-friendly; sales prospects evaluating for B2B use assume the product is consumer-only based on the homepage." + +This structure surfaces positioning gaps. + +The frequency-specific: "[Specific behavior happens at frequency X across segment Y]." + +Example: "30% of new users hit the configuration friction within 5 minutes of signup; the friction correlates with day-7 churn." + +This structure pairs qualitative observation with quantitative validation. + +--- + +## The pattern-name editing pass + +Strong synthesis runs a final editing pass focused only on pattern names. + +For each pattern name, the editing questions. + +1. Is this a category or a pattern? +2. Can a reader guess the implication from the name alone? +3. Is this a truism or a specific observation? +4. Does the name commit a position with conviction? +5. Does the name match what the data actually shows (no overstatement)? +6. Could this be split into multiple patterns or merged with another? + +The editing investment. 1-2 hours of focused name-editing on a 4-8 pattern set. The investment pays off in synthesis usability. + +--- + +## Common pattern-naming failures + +Categories disguised as patterns. "Onboarding patterns" as a section heading; nothing in the section actually names a pattern. + +Patterns that hedge into nothing. "Users may sometimes experience difficulty"; the name commits no position. + +Truism patterns. "Users want fast performance"; the name describes the universe, not the data. + +Vague specificity. "Configuration step 3 is problematic"; specific enough to seem like a pattern, vague enough to not be one. + +Pattern bloat. 30 named patterns; the synthesis loses focus and produces no priorities. + +Patterns named without evidence ties. Synthesis where readers cannot trace each pattern to specific artifacts and quotes. Patterns become assertions rather than observations. + +--- + +## Methodology-level choices that stay in the public skill + +The category-vs-pattern distinction. The implication-legibility test. The avoid-bloat principle. The avoid-truism principle. The conviction principle. The pattern-name structures that work. The editing pass. Common naming failures. + +## Implementation choices that stay internal + +Specific document templates that surface pattern names prominently. Specific reviewer rubrics for editing pattern names. Specific A/B testing of pattern name variants for clarity. The team's own conventions for pattern count within the bands. These vary by team. diff --git a/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md b/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md new file mode 100644 index 0000000..341f05f --- /dev/null +++ b/skills/discovery-research-synthesis/references/research-types-and-when-each-fits.md @@ -0,0 +1,221 @@ +# Research types and when each fits + +Five common discovery research types, what each surfaces, what synthesis they support, and how to compose them within a single discovery cycle. + +Research-type selection is upstream of synthesis. The wrong types collected for the question produce data that synthesis cannot rescue. The right types collected, even at modest scale, produce synthesis that drives decisions. + +--- + +## Customer interviews + +Format. 30-90 minute conversations, structured or semi-structured. Often one-on-one, sometimes in pairs or small groups for specific contexts. + +Artifacts. Recordings, transcripts, moderator notes, sometimes follow-up email exchanges. + +What this surfaces. + +- Why users do what they do (motivation, context, constraints). +- The struggling moments and workarounds users have built. +- The mental model behind user behavior. +- The trade-offs users are weighing that the team did not anticipate. +- The vocabulary users actually use (often different from internal product language). + +What this does not surface. + +- What users actually do in practice (interview self-report differs from behavioral data). +- Patterns that emerge only at scale (a single interview is one data point). +- Pricing willingness to pay (interview answers about price are notoriously unreliable). + +Synthesis implications. + +- Highest per-artifact richness; warrants careful per-transcript tagging. +- Best paired with other research types that quantify the qualitative patterns. +- Pattern thinness risk: 8-15 interviews surfaces patterns; 3-5 surfaces hypotheses that need more validation. + +Typical batch size. 8-15 interviews per discovery cycle. Larger batches saturate (most patterns emerge by interview 8-10 in a focused topic). + +--- + +## Support ticket reviews + +Format. Audit of recent support tickets, often spanning a defined time window or a defined product area. + +Artifacts. Tagged ticket dataset, agent-conversation transcripts, sometimes recorded support calls. + +What this surfaces. + +- The friction users actually hit (revealed by ticket volume). +- The vocabulary users use to describe broken experiences. +- The disconnect between intended user flow and actual user behavior. +- Repeated workflows that produce confusion or errors. +- Documentation and onboarding gaps. + +What this does not surface. + +- Why users got there (the ticket starts at the problem; the path before is not visible). +- The experience of users who did not contact support (silent struggling). +- Users who succeed without friction. + +Synthesis implications. + +- Lower per-artifact richness; higher volume; signal lives in patterns across many tickets. +- Best for surfacing concrete friction points; weak for understanding motivation. +- Often pairs with interviews (interviews explain why; tickets document where). + +Typical batch size. 100-500 tickets per audit, often filtered by topic or product area. + +--- + +## Sales call analysis + +Format. Recording or transcript review of recent sales calls. Often pairs with sales team feedback on patterns they hear repeatedly. + +Artifacts. Call recordings, sales notes, CRM-tagged objections, deal-stage data. + +What this surfaces. + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Use cases prospects describe (sometimes different from how marketing describes the product). +- Words prospects use to describe their situation (vocabulary signal). + +What this does not surface. + +- Existing-customer experience (sales calls are pre-purchase). +- Why prospects who did not buy did not buy (lost-deal analysis is a separate research mode). + +Synthesis implications. + +- Pairs well with positioning and pricing decisions. +- Useful for marketing-product alignment work. +- Sales teams often have synthesis hypotheses already; the research either confirms or challenges those. + +Typical batch size. 15-30 calls per audit. + +--- + +## Survey data + +Format. Quantitative responses to structured questions, often with optional qualitative comments. + +Artifacts. Response dataset, segmented by audience attributes. + +What this surfaces. + +- The frequency and severity of patterns identified through other research. +- Segment differences (do Pro users and Free users have different needs). +- Quantitative validation of qualitative hypotheses. +- Aggregate satisfaction or NPS-style sentiment. + +What this does not surface. + +- Why users responded the way they did (closed-ended responses do not explain). +- Patterns that the survey questions did not anticipate (surveys cannot find what they did not ask about). +- Behavior (surveys reveal what users say, not what they do). + +Synthesis implications. + +- Best as validation of qualitative patterns at scale, not as primary discovery. +- Survey design biases (leading questions, response order effects, satisficing) compromise data; treat with skepticism. +- Open-ended comments are often the highest-value section of a survey. + +Typical batch size. 100-2,000 responses, depending on segment specificity. + +--- + +## In-app feedback + +Format. Users submitting feedback through in-product channels (feedback widgets, NPS prompts, post-task surveys, error-state feedback forms). + +Artifacts. Submitted feedback corpus, often timestamped and contextualized by where in the product the feedback was triggered. + +What this surfaces. + +- Friction at the moment users encounter it (high context fidelity). +- Patterns across many low-effort submissions. +- Feature requests grounded in specific usage moments. +- Bugs and broken experiences not captured by support. + +What this does not surface. + +- Users who did not bother to submit feedback (silent majority). +- Why users hit the friction (the feedback names the problem; not always the cause). +- Patterns from users who do not actively use the feedback channels. + +Synthesis implications. + +- Volume varies widely; some products see high in-app feedback volume, others minimal. +- Often pairs with support tickets (similar surface area; different submission channels). +- Useful as ongoing signal; this skill is more about the periodic-audit case (`user-feedback-aggregation` covers continuous synthesis). + +Typical batch size. Ongoing; synthesized in periodic audits over defined windows. + +--- + +## Composition across types + +Strong discovery cycles combine research types deliberately. + +The pair-and-validate pattern. + +- Interviews (depth, ~12 conversations) provide qualitative patterns. +- Support tickets (volume, ~300 tickets) document where friction surfaces in practice. +- Survey (validation, ~500 responses) quantifies the patterns at scale. +- Synthesis weaves all three: interview patterns ground the why, tickets ground the where, survey grounds the how-many. + +The triangulate-the-decision pattern. + +- A specific decision (should we redesign onboarding) gets evidence from three sources. +- Interviews surface the experience of recent signups. +- Sales calls surface what prospects say onboarding will look like. +- Support tickets surface what new users actually hit. +- Synthesis converges three perspectives on the same decision. + +The single-type sufficiency pattern. + +- Some discovery questions only need one type. A pricing review might need only sales call analysis. A support-volume reduction effort might need only ticket analysis. +- Discipline: do not commission research types that will not contribute to the decision. + +The wrong-pairs to avoid. + +- Interviews + survey only, with no behavioral data: both are self-report; both can be wrong in the same direction. +- Survey only, no qualitative: the survey assumes the questions are right. +- Sales calls only, no customer voice: the prospect view is one segment; existing-customer voice may differ. + +--- + +## Research-type pitfalls per type + +Interview pitfalls. Recruiting bias (the easiest-to-recruit users are not always representative). Leading questions. Confirming the team's prior hypothesis rather than challenging it. Small-batch over-generalization. + +Support ticket pitfalls. Survivorship bias (only users who contacted support are visible; users who silently churned are not). Tag quality (poor tagging compounds in synthesis). Time-window choice (a window that misses recent product changes can mislead). + +Sales call pitfalls. Stage selection (early-stage discovery calls and late-stage closing calls reveal different things). Sales-team interpretation (sales reps' framings can color how calls are tagged). Anonymization vs detail (privacy needs can erase the specifics that matter). + +Survey pitfalls. Response bias (who responds is not representative of who is asked). Question wording. Ordering effects. Satisficing (respondents click through without engaging). Falsely-precise quantitative output from low-quality data. + +In-app feedback pitfalls. Channel bias (the kinds of users who submit in-app feedback differ from those who do not). Volume-driven prioritization (loudest categories get attention; quieter ones get missed). + +--- + +## When to commission what + +A short framework. + +1. Decision driving the research. What product decision is this research meant to inform? +2. Best research type for that decision. Discovery (interviews lead), validation (survey or quantitative leads), friction-mapping (support and in-app feedback lead), positioning (sales call analysis leads). +3. Composition. Which secondary types triangulate the primary? +4. Capacity. What can be collected within the time and budget the decision allows? +5. Existing data check. Has the team already collected research that would answer the question? Mining existing artifacts often produces value before commissioning new research. + +--- + +## Methodology-level choices that stay in the public skill + +The five research types and what each surfaces. The composition patterns. The wrong-pairs to avoid. The pitfalls per type. The when-to-commission framework. The principle that research-type selection is upstream of synthesis quality. + +## Implementation choices that stay internal + +Specific recruiting platforms and incentive structures. Specific transcription tooling. Specific support-ticket platforms and their tagging schemas. Specific survey tools and statistical-significance configurations. Specific in-app feedback widgets and integration patterns. The team's own conventions for sample sizes within the bands. These vary by team, budget, and tooling. diff --git a/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md b/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md new file mode 100644 index 0000000..4043285 --- /dev/null +++ b/skills/discovery-research-synthesis/references/synthesis-review-and-validation.md @@ -0,0 +1,177 @@ +# Synthesis review and validation + +How synthesis gets pressure-tested before it drives decisions. Review and validation surface synthesis errors that the research team missed: fabricated patterns, projected interpretations, missing dissent, segment misreads. + +The discipline is making review non-negotiable. Synthesis that ships without review carries unacknowledged blind spots; review compresses those blind spots before the synthesis becomes the team's working document. + +--- + +## Internal review with research participants where possible + +The principle. Show the synthesis to a subset of the research participants. Do they recognize themselves and their experiences in the patterns? + +Why participant review matters. + +- Participants are the only authoritative source on whether the synthesis represents their experience. +- Misrecognition signals fabrication: the synthesis projected interpretations the data did not support, or named patterns that did not match what participants actually said. +- Recognition validates the synthesis: participants endorse the patterns as accurate representations. + +The mechanics. + +- Send the synthesis (or relevant excerpts) to 3-5 research participants for review. +- Ask: "Do these patterns reflect your experience? Anything missing? Anything the synthesis got wrong?" +- Build participant recognition into the research design from the start (with consent for follow-up review). + +The exception. Some research types (large-scale survey, anonymous in-app feedback) do not support participant review at the individual level. For those, validation depends on aggregate quantitative checks (the next section). + +The honest disclosure. When participant review surfaces misrecognition, the synthesis revises rather than dismissing the feedback. Synthesis that dismisses participant pushback is reverting to confirmation bias. + +--- + +## Adjacent-team review + +The principle. Show the synthesis to product, engineering, support, sales. Do the patterns match what they observe in their domains? + +Why adjacent-team review matters. + +- Adjacent teams have ground-truth observations the research did not access. Support sees the friction users hit every day; sales hears prospect objections; engineering knows which problems are technically tractable. +- Adjacent teams catch synthesis errors that the research team missed: patterns that contradict what support handles daily, implications that ignore engineering constraints. +- Adjacent teams' alignment with synthesis affects whether the synthesis drives decisions: if support disagrees with the support-related patterns, the synthesis loses authority. + +The mechanics. + +- Share the synthesis with relevant adjacent-team leads for review. +- Hold a structured review session where adjacent teams can challenge, validate, or extend the patterns. +- Capture adjacent-team observations as inputs to synthesis revision. + +Common adjacent-team feedback patterns. + +- Support: "Your synthesis names X as a pattern, but support tickets show Y is also load-bearing and not in the synthesis." +- Sales: "Prospects do say what your synthesis claims, but the patterns you missed are the pricing-conversation friction." +- Engineering: "The implication you propose has a constraint the synthesis did not account for." + +The synthesis revises in light of these inputs. + +--- + +## Quantitative validation where possible + +The principle. Patterns from qualitative synthesis can often be validated at scale through analytics, survey, or in-app data. + +The validation pattern. + +- Synthesis says: "Users abandon configuration step 3 because credit card details are not accessible at signup." +- Quantitative validation: pull analytics on configuration step 3 abandonment rate. Does the data confirm 40% abandonment that the pattern implies? Does abandonment correlate with the credit card requirement (versus other possible causes)? +- If the data confirms: the pattern is strongly supported. +- If the data does not confirm: the pattern needs revision; the qualitative signal may not generalize. + +Why validation matters. + +- Qualitative patterns can overstate frequency; small-sample interview signal does not always match large-sample reality. +- Quantitative validation grounds synthesis in scaled data without requiring the synthesis to be quantitative-only. +- Validation reveals which patterns are strong enough to act on and which need more investigation. + +See `experiment-design` for rigorous A/B testing as quantitative validation. See `product-analytics-setup` for the instrumentation that makes validation possible. + +The honest disclosure. When quantitative validation contradicts qualitative patterns, the synthesis adjusts. Patterns the analytics does not support get downgraded or removed. Synthesis that ignores quantitative pushback in favor of qualitative claims is unrigorous. + +--- + +## The "challenge the synthesis" session + +The principle. A specific session where adjacent teams try to find what the synthesis missed, overstated, or railroaded. + +The session structure. + +- Synthesis owner presents the patterns and implications (15-30 minutes). +- Adjacent-team participants challenge: "What patterns did the research miss? What implications overstate the data? What decisions is the synthesis trying to railroad?" +- Synthesis owner takes notes; does not defend; the session is for surfacing concerns, not for resolution in the moment. +- Synthesis owner revises based on the inputs over the following days; revised synthesis circulates back. + +Why this works. + +- Productive disagreement strengthens synthesis. The team that surfaces concerns is contributing to better synthesis, not undermining the research investment. +- The session creates space for honest pushback that quieter review formats sometimes suppress. +- The session signals that synthesis is open to challenge, which strengthens the team's trust in the synthesis once it ships. + +The anti-pattern. Synthesis owners who treat the session as defense of the synthesis rather than as input to the synthesis. The owner pushes back on every challenge; adjacent teams disengage; synthesis ships unrevised. + +The discipline. The synthesis owner's job in the session is to listen and capture, not to defend. Defense happens in the revision; pushback happens later, after considering the input. + +--- + +## Iterate before publishing + +The principle. Synthesis goes through revision based on the review loop. Synthesis that ships in first-draft state usually carries unacknowledged blind spots. + +The iteration cycle. + +- First draft from the synthesis owner. +- Participant review (where possible). +- Adjacent-team review (always). +- Challenge-the-synthesis session. +- Revision based on inputs. +- Final review by senior product leader for clarity and quality. +- Publication. + +Time investment. The review-and-iteration loop adds 1-2 weeks to the synthesis timeline. That investment is small relative to the cost of publishing synthesis with blind spots that produce wrong decisions. + +Common iteration outputs. + +- Patterns split (the original pattern was actually two patterns adjacent teams distinguished). +- Patterns merged (the original separation was not load-bearing). +- Patterns revised (the framing did not match the data on closer review). +- Implications expanded (additional implications surfaced during review). +- Implications narrowed (some implications overstepped what the data supports). +- Decision input refined (the original was too vague to drive decisions). + +--- + +## When the review loop reveals the synthesis cannot be saved + +The honest case. Sometimes review surfaces synthesis problems too deep to fix in revision: patterns built on insufficient data, projections the data did not support, framing that adjacent teams flatly contradict. + +The response. + +- Stop. Do not publish synthesis with known significant problems. +- Re-examine: was the underlying research adequate? Was the synthesis sequence run completely? Were the patterns named with conviction or projected? +- Restart from where the breakdown happened. Often returns to clustering or pattern-naming. +- Sometimes returns to gathering more research. The honest case is acknowledging that the discovery cycle did not produce sufficient input for reliable synthesis. + +The cost calibration. Restarting synthesis costs PM time. Publishing flawed synthesis costs the team's trust in research output, plus the wrong decisions the flawed synthesis drives. The latter is usually more expensive. + +--- + +## What review does not do + +Review does not validate every synthesis. Some synthesis fails review and should not ship; some passes with revision; some passes with minor adjustment. Review is the discipline that distinguishes the cases. + +Review does not eliminate disagreement. Adjacent teams may continue to disagree even after review. The synthesis owner makes the final call after considering inputs. Disagreement preserved in the published synthesis is fine and honest; pretended consensus is not. + +Review does not slow shipping artificially. A 1-2 week review loop on substantive synthesis is appropriate. Quick-turn synthesis (short audits, focused interview batches) can run a lighter review (asynchronous comments from 2-3 reviewers; adjacent-team check; ship). + +--- + +## Common review-and-validation failures + +Skipping participant review. Synthesis ships without participants ever seeing the patterns; participants would have caught misrecognitions; the synthesis carries projection. + +Skipping adjacent-team review. The team most likely to know the data is wrong did not see the synthesis before publication. + +Defensive review sessions. The synthesis owner argues against challenges instead of capturing them; the session produces defense rather than input. + +Quantitative validation skipped. The qualitative patterns went unchallenged by available analytics data; the synthesis overstates patterns the data does not support. + +Iteration compressed to one round. First draft + one review + ship. Most synthesis benefits from two rounds of revision: first round on substance, second round on presentation. + +Review feedback dismissed. Adjacent teams raise concerns; synthesis owner notes them but does not revise. Synthesis ships as if the feedback did not happen. + +--- + +## Methodology-level choices that stay in the public skill + +The participant review pattern. The adjacent-team review pattern. Quantitative validation. The challenge-the-synthesis session. Iteration discipline. The cannot-be-saved escalation. What review does and does not do. Common review failures. + +## Implementation choices that stay internal + +Specific reviewer pairings and roles. Specific session formats and facilitation. Specific revision tracking. Specific publication conventions. Specific quantitative validation pipelines. The team's own conventions for review-loop length. These vary by team. diff --git a/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md b/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md new file mode 100644 index 0000000..5a9b6f3 --- /dev/null +++ b/skills/discovery-research-synthesis/references/synthesis-sequence-walkthrough.md @@ -0,0 +1,229 @@ +# Synthesis sequence walkthrough + +The six-stage synthesis sequence with worked example. Stage outputs, common skip-failures, time investment per stage. + +The sequence is non-negotiable. Teams that skip stages produce findings that look like synthesis but are not: untagged transcripts, unclustered tags, unnamed patterns, patterns without implications, implications without decisions. Each stage builds on the previous; skipping any stage breaks the chain. + +--- + +## The six stages + +1. Transcribe and prepare. Convert artifacts into a synthesizable format. +2. Tag at the artifact level. First-pass descriptive tagging. +3. Cluster across artifacts. Group tags into themes. +4. Name patterns. Each cluster becomes a named pattern. +5. Infer product implications. What does each pattern imply. +6. Name the so-what. The decision input. + +--- + +## Stage 1: Transcribe and prepare + +The work. Convert artifacts into a format you can read, mark up, and search. + +Outputs. + +- Interview transcripts, time-stamped, speaker-labeled. +- Support ticket dataset, exported to a workable format with relevant fields (subject, body, resolution, tags, dates). +- Sales call summaries or transcripts. +- Survey data with open-ended responses extracted into a reviewable format. + +Time investment. Often underestimated. A 60-minute interview takes 60-90 minutes to transcribe (with AI tools) plus 30-60 minutes to clean. Eight interviews: 12-20 hours of prep before tagging starts. + +Common skip-failures. + +- Skipping transcription on the assumption that the recordings are sufficient. Reality: tagging from audio is impractical at any meaningful batch size. +- Cleaning to the point of distortion (removing the messy parts that contain signal). +- Skipping speaker labels (collapsed dialog loses critical context). + +The unglamorous-but-essential principle. Teams that skip prep work never reach the later stages because the artifacts are not workable. The investment in prep pays back across every later stage. + +--- + +## Stage 2: Tag at the artifact level + +The work. Read each transcript or ticket and tag it with topics, problems, quotes, and observations. + +Outputs. + +- Tagged artifacts (transcripts, tickets, etc.) with descriptive tags inline. +- A tag list (often 80-150 tags per batch by the end of this stage). +- Quote pulls (specific sentences worth referencing later). + +Approach. + +- First-pass tagging is descriptive: what did this person say, what problem did they hit, what were they trying to do. +- Allow tag proliferation. Do not force consolidation in this stage; that is for clustering. +- Tag dissent and contradictions explicitly. "User reports liking the onboarding" alongside other users reporting friction is signal; tag it. +- Mark quotes worth pulling. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. + +Time investment. Per artifact: 30-90 minutes for an interview transcript, 1-3 minutes per support ticket, 15-30 minutes per sales call. A typical batch (12 interviews + 200 tickets + 20 sales calls) might run 25-40 hours of focused tagging work. + +Common skip-failures. + +- Pre-designing the tag taxonomy and forcing artifacts into it. +- Tagging from memory after reading the transcript rather than during reading. +- Premature consolidation (collapsing tags during this stage instead of later). +- Skipping the contradictions (only tagging the dominant pattern). + +The artifact-level discipline. Each tag is grounded in a specific moment in a specific artifact. Tags floating free of evidence are a stage-2 failure that compounds in later stages. + +--- + +## Stage 3: Cluster across artifacts + +The work. Group tags into themes that surface the patterns the data reveals. + +Outputs. + +- A cluster list (often 6-15 clusters from the 80-150 tags). +- Per-cluster tag membership. +- Per-cluster artifact source list (which artifacts contributed to this cluster). + +Approach. + +- Cluster on the underlying observation, not on tag overlap. Two tags that co-occur may not be the same pattern. +- Iterate: first-pass clustering will reveal that some tags belong in multiple clusters; some clusters are too broad; some need to split. +- Use the artifact-source list to test cluster strength. A cluster with 8 supporting artifacts is stronger than one with 2. +- Track the dissent: which clusters have countervailing evidence the synthesis must address. + +Time investment. 4-8 hours of clustering work for a batch this size. Often done collaboratively with another reviewer to surface alternative groupings. + +Common skip-failures. + +- Clustering on assumed categories rather than emergent themes. +- Stopping at first-pass clustering without iterating. +- Ignoring artifact-source counts (clusters with thin support get weighted equally with strong ones). +- Forcing every tag into a cluster (some tags are noise; that is fine). + +--- + +## Stage 4: Name patterns + +The work. Each cluster becomes a named pattern that captures what the underlying observation actually is. + +Outputs. + +- A pattern list (typically 4-8 patterns from a strong synthesis). +- Per-pattern name, evidence summary, and source-artifact list. + +Approach. + +- Pattern name is specific enough that a reader can guess the implication. +- Pattern names commit a position: name what the data shows, not a category the data sits in. +- Avoid truisms: pattern names that read as something everyone could have said before the research are not patterns. +- Limit pattern count: 4-8 strong patterns serve synthesis better than 15 weak ones. + +Time investment. 2-4 hours of pattern-naming work. Often the highest-impact stage; investment in good pattern names pays off in implications and decisions. + +Common skip-failures. + +- Pattern names that are category labels (Onboarding, Pricing, Support). +- Pattern names that are truisms (Users want fast performance). +- Hedge-stacked pattern names (Users sometimes seem to occasionally maybe). +- Too many patterns (under-clustering manifests as pattern bloat). + +See `pattern-naming-patterns.md` for detail. + +--- + +## Stage 5: Infer product implications + +The work. For each pattern, name what this implies for the product. + +Outputs. + +- Per-pattern implication list (often 1-3 implications per pattern). +- Per-implication: specific, falsifiable, cost-acknowledged. + +Approach. + +- Each pattern can have multiple implications. Surface the options; do not pre-prioritize. +- Implications are the writer's analytical work, not what users said. Users describe experience; PMs interpret what experience implies. +- Make implications falsifiable. "We should improve onboarding" is not an implication; "Move the third configuration step to after first success state" is. +- Acknowledge cost. Implications that ignore implementation cost produce wishlists. +- Some patterns imply not-acting. Naming the not-act implication is honest synthesis. + +Time investment. 3-6 hours of implication work. + +Common skip-failures. + +- Vague implications that cannot be acted on or debated. +- Wishlist implications that do not acknowledge cost. +- Skipping the not-act implication when it would be honest. +- Implications that are restatements of the pattern (no analytical bridge). + +See `from-pattern-to-product-implication.md` for detail. + +--- + +## Stage 6: Name the so-what + +The work. For each implication, the specific decision it informs. + +Outputs. + +- Per-implication so-what statement tied to a real decision. +- An overall recommendation section: what should change as a result of this synthesis. + +Approach. + +- Map each implication to a decision the team is making (or should make). +- Be specific: "Should the Q2 roadmap include the onboarding redesign?" rather than "Onboarding should be considered." +- Surface the synthesis's overall recommendation: where to invest, where to deprioritize, where to gather more data before deciding. +- Acknowledge the decisions the synthesis cannot resolve: data gaps, contested patterns, decisions outside the synthesis's scope. + +Time investment. 2-4 hours of so-what work. + +Common skip-failures. + +- So-whats that are too abstract to drive decisions. +- Skipping the overall recommendation section (each pattern stands alone; the synthesis does not aggregate). +- Buried data gaps (the synthesis presents conclusions where the data did not support them). + +--- + +## Worked example + +A discovery cycle with 12 customer interviews + 250 support tickets + a sales call audit, focused on a possible onboarding redesign. + +Stage 1 (prep). 18 hours. Interview transcripts cleaned; ticket dataset extracted; sales call transcripts pulled. + +Stage 2 (tagging). 32 hours. 110 tags emerged across the artifacts. Quote pulls captured. + +Stage 3 (clustering). 6 hours. Clusters emerged: configuration-step friction, value-state delay, onboarding length, mobile-context onboarding, role-based mismatch, support-deflectable confusion. Six clusters with varying artifact support. + +Stage 4 (pattern naming). 3 hours. Six patterns named, including: + +- "Users abandon configuration step 3 because it requires data they do not have on hand at signup time." +- "Free users reach the success state at half the rate of paid users because the configuration burden is the same but the value reveal is gated." +- "New users on mobile cannot complete onboarding without switching to desktop because two configuration screens are not mobile-functional." + +Stage 5 (implications). 4 hours. Per-pattern implications. Example for the configuration-step pattern: + +- Implication: defer configuration step 3 to after first success state, with a "complete your setup" prompt later. +- Cost: medium engineering investment; affects existing flows for users who completed step 3 historically. +- Alternative implication: pre-populate step 3 with sensible defaults from step 2 data where possible. +- Not-act implication: keep the current flow but improve docs (probably insufficient given the friction severity). + +Stage 6 (so-what). 3 hours. Decision input: yes, prioritize onboarding redesign in Q2; staged-onboarding approach; mobile parity is a sub-track within the redesign; configuration-step deferral is the headline change. + +Total synthesis time. 66 hours over the six stages. Roughly 1.5-2 weeks of focused synthesis work for one PM. + +--- + +## Time-investment patterns + +Synthesis sequences that go shorter than this are usually skipping stages. Sequences that go longer are usually over-investing in tagging or under-deciding in implications. The 60-80 hour range for a substantial discovery synthesis is typical. + +Programs that have not budgeted synthesis time often discover it after research ships and the synthesis stalls. The discipline is budgeting synthesis at the start of the discovery cycle, not as an afterthought. + +--- + +## Methodology-level choices that stay in the public skill + +The six-stage sequence with stage outputs and time investments. The worked example. The non-negotiability of the sequence. Common skip-failures per stage. + +## Implementation choices that stay internal + +Specific transcription tools. Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific document templates per output. Specific time-tracking conventions for synthesis budgeting. These vary by team and tooling. diff --git a/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md b/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md new file mode 100644 index 0000000..b09da20 --- /dev/null +++ b/skills/discovery-research-synthesis/references/tagging-and-clustering-discipline.md @@ -0,0 +1,140 @@ +# Tagging and clustering discipline + +The middle stages of the synthesis sequence have specific failure modes. Tagging and clustering done badly produces bad patterns; tagging and clustering done well produces patterns that drive decisions. + +The discipline is in five principles that apply across both stages. + +--- + +## Principle 1: Tag at the artifact level first; do not pre-design the taxonomy + +The pattern. Tags emerge from the artifacts. The researcher reads each transcript and tags what is actually there. + +The anti-pattern. Researchers arrive at tagging with a pre-built taxonomy: "we will tag for usability, performance, pricing, support." Artifacts get forced into the categories. Patterns the taxonomy did not anticipate get missed. + +Why pre-built taxonomies fail. + +- The taxonomy reflects what the team already thinks; tagging confirms what the team already thinks; synthesis does not reveal anything new. +- Artifacts that do not fit the taxonomy categories get skipped or shoehorned in. +- Tags that emerge in the data but were not in the taxonomy do not get captured. + +The exception. Some categorical metadata is fine to apply consistently (user segment, source channel, recency). The semantic tagging that drives synthesis should still emerge from the data. + +The recovery. Mid-tagging, if the team realizes the pre-built taxonomy is constraining, it can be discarded and tagging restarted with descriptive tags emerging from artifacts. Better to restart than to publish synthesis grounded in a constraining taxonomy. + +--- + +## Principle 2: Allow tag proliferation; collapse later + +The pattern. First-pass tagging produces 80-150 tags across a batch. That is correct. Premature consolidation loses distinctions that turn out to matter. + +The anti-pattern. Researchers consolidating tags during the tagging stage. "We had four onboarding tags; let me merge them into one." The merge happens before the researcher has seen whether the four tags actually represent different patterns. + +Why proliferation matters. + +- Some distinctions only become visible after seeing many artifacts. Two tags that seem similar at artifact 3 may turn out to be different patterns by artifact 12. +- Granular tags can always be collapsed in the clustering stage; collapsed tags cannot be unmerged once the tagging is done. +- Proliferation supports the discovery posture; consolidation supports the confirmation posture. + +The volume calibration. A batch of 12 interviews + 250 tickets + 20 sales calls might end with 80-150 tags. Fewer than that often signals premature consolidation; more than that may signal undisciplined tagging. + +--- + +## Principle 3: Cluster on patterns, not on tag overlap + +The pattern. Two tags that co-occur in many artifacts may or may not be the same pattern. Cluster on the underlying observation, not on statistical co-occurrence. + +The anti-pattern. Tools that auto-cluster by co-occurrence. They produce statistical groupings that do not always match the patterns the researcher needs. + +Why pattern-clustering matters. + +- "Slow onboarding" and "configuration friction" might co-occur because both are common; that does not mean they are the same pattern. They might be the same (configuration is what makes onboarding feel slow) or different (there is friction in configuration AND there is a perception of length independent of configuration). +- The researcher's interpretation of the artifact-level tags is what surfaces the pattern; tools can suggest groupings but cannot determine them. + +The work. For each candidate cluster, ask: are the underlying observations the same, or do they share a tag because the tag was loose? If the latter, split the cluster. + +--- + +## Principle 4: Name the cluster after clustering, not before + +The pattern. The cluster name comes from the data after the clustering work is done. + +The anti-pattern. Researchers arriving with named clusters and slotting data into them. The clusters become hypothesis-confirmation rather than discovery. + +Why post-cluster naming matters. + +- Pre-named clusters bias the clustering: tags get assigned to clusters they fit linguistically rather than substantively. +- Post-cluster naming reveals patterns the team did not anticipate (the highest-value patterns). +- The naming itself is part of the synthesis work; rushing the naming compresses the analytical work into a label without thought. + +The discipline. First-pass clustering produces unnamed clusters. The researcher then names each cluster based on what the underlying observations actually show. Names emerge after the clustering, not before. + +--- + +## Principle 5: Tag dissent and contradictions explicitly + +The pattern. Some users will contradict the dominant pattern. Those contradictions are signal: either there is a sub-segment with different needs, or the pattern is weaker than the volume suggests. + +The anti-pattern. Tagging only the dominant pattern; ignoring the contradictions; or tagging contradictions but not following them through to clustering and synthesis. + +Why dissent matters. + +- Contradictions reveal sub-segments. "Most users find configuration confusing; experienced users find it efficient" might mean the pattern is segment-specific, not universal. +- Contradictions reveal pattern strength. A pattern with no countervailing evidence is suspicious; a pattern with some dissent that the synthesis can explain is stronger. +- Synthesis that ignores dissent reads as researcher confirmation bias. + +The discipline. Each major pattern in synthesis has a "but consider" section: contradictions in the data, segment differences, edge cases. The synthesis is more honest with these sections; readers trust patterns that engage their counterevidence. + +--- + +## Tagging tactics that work + +A short list of tactics that improve tagging quality. + +Read the artifact end-to-end before tagging. Tagging while reading on first pass produces fragmentary tags. Reading first, then tagging on a second pass, produces tags grounded in the artifact's full context. + +Tag specific moments, not summaries. "User struggles" is a summary. "User abandons configuration step 3 because credit card details are not accessible during signup" is a specific moment. Specific moments support stronger pattern naming later. + +Pull quotes during tagging. Synthesis output includes evidence; the evidence comes from quotes selected during tagging. Marking quote-worthy moments during tagging prevents re-reading later. + +Tag motivation alongside behavior. "User clicked X" is behavior; "User clicked X because they thought it would Y" is motivation. Motivation tags surface what users were trying to accomplish, which informs implications more than behavior alone. + +Tag emotional valence sparingly. "User was frustrated" is fine; tagging every artifact for emotional state produces noise. + +--- + +## Clustering tactics that work + +Iterate clustering at least twice. First-pass clustering is rough; second-pass clustering refines; third-pass clustering catches what the first two missed. + +Use artifact-source counts. A cluster supported by 8 artifacts is stronger than one supported by 2. The source count does not determine pattern importance, but it informs synthesis weighting. + +Test cluster boundaries. Take a tag from one cluster and ask: could this fit in another cluster instead? If yes, the cluster boundaries are unclear; refine. + +Surface the leftovers. Tags that do not fit any cluster are signal. They might be noise (one-off observations not generalizing). They might be edge-case patterns worth naming separately. They might point to a cluster the researcher missed. + +Cluster collaboratively where possible. A second reviewer surfaces alternative groupings the first reviewer did not see. Two reviewers usually produces better clustering than one. + +--- + +## Common tagging-and-clustering failures + +Tagging by memory, not by reading. Researchers reading transcripts and then tagging from recall. Loses specifics; produces general tags that cluster poorly. + +Tag exhaustion. Researchers running through too many artifacts in one session, tag quality decaying as fatigue sets in. Reduce session length; pace the tagging across days. + +Confirming the team's prior hypothesis. Researchers entering tagging with a hypothesis the research is meant to confirm. Tags get assigned to support the hypothesis; counterevidence gets minimized. + +Cluster collapsing to fit a target count. Researchers feeling they should have N clusters and forcing the data to that count. Either over-collapsing (losing distinctions) or under-collapsing (preserving noise as signal). + +Skipping the dissent. Tagging only the dominant pattern; clustering only the supporting tags. Synthesis publishes patterns without their counterevidence; reviewers later catch the gap. + +--- + +## Methodology-level choices that stay in the public skill + +The five principles (tag at artifact level, allow proliferation, cluster on patterns, name after clustering, tag dissent). The tagging tactics. The clustering tactics. The common failures. + +## Implementation choices that stay internal + +Specific tagging tools (spreadsheet, dedicated qualitative analysis software, AI-assisted tagging). Specific clustering visualization. Specific session-length conventions for tagging. Specific reviewer pairings. The team's own conventions for tag-count thresholds. These vary by team and tooling. diff --git a/skills/discovery-research-synthesis/references/when-to-gather-more-data.md b/skills/discovery-research-synthesis/references/when-to-gather-more-data.md new file mode 100644 index 0000000..5ba1b81 --- /dev/null +++ b/skills/discovery-research-synthesis/references/when-to-gather-more-data.md @@ -0,0 +1,212 @@ +# When to gather more data + +Synthesis sometimes reveals that the research did not collect enough. The discipline is naming gaps explicitly and deciding whether to halt synthesis, ship with named gaps, or restart with more research. + +The discomfort of acknowledging gaps is the source of bad synthesis. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals it was not. The discipline is honesty about what the research can and cannot support. + +--- + +## Pattern thinness + +The signal. A pattern surfaces in 2-3 artifacts but the synthesis would need 5-8 to commit a position. + +Why it happens. + +- The discovery cycle had a defined batch size; some patterns emerged with limited support. +- The pattern is real but rare; the research did not encounter enough cases to characterize it. +- The pattern is segment-specific; the research overrepresented other segments. + +The honest options. + +- Name the pattern as tentative pending more data. Synthesis ships with this pattern flagged as preliminary; the team treats it as a hypothesis rather than a finding. +- Pause synthesis to gather more research. If the pattern is decision-load-bearing, the additional research investment may be worthwhile. +- Drop the pattern. If the pattern is not decision-relevant or the data is too thin to be useful, do not include it. Inflating thin patterns to fill space is a synthesis failure. + +The dishonest option to avoid. Naming the thin pattern as if it had full support. Readers cannot distinguish well-supported from thinly-supported patterns; decisions get made as if all patterns are equal weight; the team gets surprised when the thin-pattern decisions do not pan out. + +--- + +## Segment under-representation + +The signal. The research overrepresents one user segment and underrepresents another that matters for the decision. + +Why it happens. + +- Recruiting bias produces segment skew (the easiest-to-recruit users are usually a specific segment). +- The research was scoped before the team realized which segments mattered most for the decision. +- Available research artifacts (existing tickets, prior interviews) skew toward certain segments. + +The honest options. + +- Synthesize for the represented segment; flag explicitly that the patterns may not apply to underrepresented segments. +- Pause to recruit and conduct research with the underrepresented segment. +- Use existing data sources (analytics, support data) to validate patterns in the underrepresented segment indirectly. + +Worked example. A discovery cycle on B2B onboarding interviews 12 users, all from companies of 50-500 employees. The synthesis surfaces strong patterns for that segment. The product team is also considering enterprise (1000+ employees) and small business (1-50). The synthesis should: + +- Name patterns for the 50-500 segment with confidence. +- Acknowledge that enterprise and small business patterns are not represented. +- Recommend either separate research for the missing segments or scoping the decision to the segment the data covered. + +--- + +## Contradictory clusters + +The signal. Two clusters point in opposite directions and the data does not resolve the contradiction. + +Why it happens. + +- Sub-segment differences the research did not investigate explicitly. +- Different use contexts producing different needs (mobile vs desktop, new vs returning users). +- One cluster reflects what users say; the other reflects what users do; the contradiction is real and revealing. + +The honest options. + +- Investigate the contradiction. Often the contradiction itself becomes the most valuable finding: it surfaces a sub-segment or context distinction the team did not anticipate. +- Pause synthesis to gather targeted research that resolves the contradiction. +- Ship synthesis with the contradiction named and the recommendation to gather more data before committing decisions in this area. + +Worked example. Interviews with new users surface that they want simpler onboarding. Support tickets from new users in the same week surface frequent requests for more configuration options during onboarding. The contradiction may reveal: + +- New users say "simpler" but mean "fewer required steps before value"; configuration options are fine if not blocking. +- The interview sample skewed casual users; the support tickets came from power users. +- The contradiction needs more investigation before driving onboarding redesign. + +--- + +## Decision time pressure + +The signal. Synthesis revealing data gaps but the decision has to ship before more research can happen. + +Why it happens. + +- Roadmap commitments do not flex for data gaps. +- The decision is upstream of work that has already been committed. +- The cost of waiting exceeds the value of additional data. + +The honest path. + +- Name the data gap explicitly in the synthesis. Do not pretend the gap does not exist. +- Make the recommendation with the gap acknowledged. "Given current data, we recommend X. The gap that may revise this recommendation is Y." +- Plan the follow-up research that would validate or revise the recommendation. +- Build instrumentation that will validate the recommendation post-launch (so the team can detect if the recommendation was wrong). + +The path to avoid. Pretending the data is sufficient when it is not. Synthesis under time pressure that treats partial data as complete data produces decisions the team will not be able to recover from cleanly when the gap surfaces later. + +--- + +## The "we have enough" trap + +The pattern. Teams that have invested in research want to declare the data sufficient even when the synthesis reveals gaps. + +Why it happens. + +- Sunk-cost reasoning: the team has spent the research budget; restarting feels like waste. +- Timeline pressure: the research was scheduled before synthesis; more research means schedule slip. +- Status concerns: declaring the research insufficient feels like admitting the discovery work was inadequate. + +Why it produces bad synthesis. + +- The data gaps still exist whether or not the team acknowledges them. Decisions made on incomplete data still suffer from the incompleteness. +- Synthesis that papers over gaps trains the team to treat synthesis as performative rather than load-bearing. +- The next discovery cycle will repeat the same scoping mistakes because the team did not name them honestly. + +The discipline. + +- Naming gaps is the synthesis owner's job. The team relies on the synthesis owner to be honest about what the research can and cannot support. +- The cost of naming gaps is short-term discomfort; the cost of pretending they do not exist is bad decisions. +- "We have enough" should be the conclusion of synthesis review, not the assumption. + +--- + +## When more research is the right call + +The criteria. + +- The decision is load-bearing for product direction. +- The gap is large enough that synthesis would be misleading without addressing it. +- The cost of additional research is bounded and feasible. +- The cost of deciding now and being wrong is high. + +Examples that warrant more research. + +- A pricing decision where current research underrepresents the segment that drives revenue. +- An onboarding redesign where the synthesis cannot distinguish what new users want from what they need. +- A positioning shift where existing-customer voice is in the data but prospect voice is missing. + +Examples that do not warrant more research. + +- Minor decisions where the gap's resolution would not change the recommendation materially. +- Decisions where the cost of waiting exceeds the value of additional data. +- Decisions that can be reversed easily based on post-launch data. + +--- + +## When to ship synthesis with named gaps + +The criteria. + +- Decision time pressure makes more research infeasible. +- The gap is named honestly so the team can weigh the recommendation accordingly. +- Post-launch instrumentation will detect if the recommendation was wrong. + +The discipline. + +- The named gap is in the synthesis prominently, not buried. +- The recommendation acknowledges what the gap might change. +- The follow-up research plan is specific and committed. + +Worked example. "Recommendation: prioritize the onboarding redesign in Q2. Caveat: our research underrepresents enterprise users; if enterprise represents a significant share of new signups, the redesign should include enterprise-specific paths we have not validated. Follow-up: enterprise-specific user research in Q1 to validate the redesign approach for that segment before Q2 ships." + +--- + +## When to drop the pattern entirely + +The criteria. + +- The supporting data is too thin to commit a position even tentatively. +- The pattern, if false, would mislead the team in directions hard to recover from. +- The pattern is not load-bearing for the synthesis's primary recommendations. + +The discipline. + +- Some thin patterns warrant dropping rather than flagging. Not every observation needs to make it into the synthesis. +- Dropping is honest synthesis; inflating is not. + +--- + +## Common gather-more-data failures + +Inflating thin patterns. Patterns supported by 2 artifacts presented as if supported by 12. Readers cannot distinguish strength. + +Hiding segment gaps. Synthesis presents recommendations as universal when they apply only to the segment researched. + +Pretending contradictions resolved. Synthesis writes around the contradiction rather than naming it; readers later discover it on their own. + +Decision-pressure denial. Synthesis treats time pressure as if it makes data complete. The decision is made; the wrong-decision cost is paid later. + +The "we have enough" trap. Sunk cost and status protect the synthesis from honest gap-naming. + +Endless research. The opposite failure: every gap triggers more research; synthesis never ships; the team paralyzes on data-gathering. + +--- + +## The data-sufficiency calibration + +A short framework. + +1. Is the gap load-bearing for the recommendations? If yes, address it. If no, name and proceed. +2. Is more research feasible within the decision timeline? If yes, gather. If no, ship with named gaps. +3. Can post-launch instrumentation catch wrong decisions? If yes, ship-with-instrumentation is reasonable. If no, more caution warranted. +4. What is the cost of being wrong vs cost of waiting? Compare; choose the lower-cost path. +5. Is the team's commitment to follow-up research credible? If named gaps will trigger real follow-up, ship-with-gaps works. If named gaps will be ignored, gather now. + +--- + +## Methodology-level choices that stay in the public skill + +The pattern thinness signal. Segment under-representation. Contradictory clusters. Decision time pressure. The we-have-enough trap. When more research is and is not the right call. When to ship with named gaps. When to drop patterns. Common gather-more-data failures. The data-sufficiency calibration. + +## Implementation choices that stay internal + +Specific recruiting pipelines for follow-up research. Specific instrumentation for post-launch validation. Specific synthesis-revision workflows when gaps are named. The team's own conventions for "thin pattern" thresholds. These vary by team. diff --git a/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md b/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md new file mode 100644 index 0000000..6291907 --- /dev/null +++ b/skills/discovery-research-synthesis/references/writing-for-decisions-not-decks.md @@ -0,0 +1,207 @@ +# Writing for decisions, not decks + +Synthesis output should be optimized for decision use, not for presentation. The format choice (document vs deck), the structure (patterns lead, evidence appendix), the voice (opinionated), and the closing (decision input section) compose to produce synthesis the team actually references. + +--- + +## Document, not deck + +The principle. Deck format is poor for synthesis. + +Why decks fail. + +- Slides cannot carry argument density. A pattern, its evidence summary, its implications, and its decision input do not fit on one slide; spreading them across slides loses coherence. +- Readers cannot reference slides later. A pattern needs to be findable; decks decay into icons and bullet points that are hard to search and cite. +- Decks are presentation artifacts; synthesis needs to be a reference artifact that the team uses for months. +- The deck format encourages summarization that loses precision. + +Why documents work. + +- A 4-12 page document can carry the pattern, evidence, implications, and decision input in connected prose. +- Documents are searchable, linkable, and citable. +- Documents accommodate density without overwhelming; readers can scan headings and dive into sections. +- Documents read as load-bearing analytical work; decks read as presentation. + +The exception. A short executive summary deck (5-8 slides) can pair with a substantive document. The deck summarizes; the document carries the work. + +The discipline. If the synthesis is being optimized for a single 30-minute readout meeting, the format will fail when the team needs to reference the synthesis in week 6 of execution. Optimize for the reference use, not the presentation moment. + +--- + +## Lead with patterns and implications; relegate evidence to appendix + +The principle. Readers scanning for decision input want patterns and implications first. + +The reader's question. "What does this synthesis tell me to do?" Patterns and implications answer it. Evidence supports the answer but is not the answer. + +The structure that works. + +- Executive summary (1 page): the patterns, the recommendations, the decision input. +- Pattern sections (1-3 pages per pattern): pattern name, evidence summary in 2-3 sentences, implications, decision input. +- Recommendations section (1 page): overall synthesis recommendation; what should change. +- Appendix: detailed evidence, quote pulls, methodology notes, full transcripts or links to them. + +The structure that fails. + +- Decks that lead with quote walls. Readers admire the quotes; they do not extract decisions. +- Documents that bury the patterns under methodology and background. Readers stop reading before reaching the patterns. +- Synthesis that mixes evidence and analysis throughout. Readers cannot tell where observation ends and recommendation begins. + +The discipline. Each pattern section is short (2-4 paragraphs of synthesis text); evidence linked or summarized briefly; the appendix is where evidence depth lives. Readers who want depth follow the link; readers who want decisions stay in the body. + +--- + +## One section per pattern, parallel structure + +The principle. Synthesis with 4-8 patterns has 4-8 parallel sections, each with the same structure. + +Per-section structure. + +- Pattern name (the heading). +- Evidence summary (2-3 sentences naming the artifacts and the dominant signals). +- Implication (1-3 implications with cost notes). +- Decision input (specific decision the implication informs). + +Why parallel structure works. + +- Readers learn the structure from the first section and can scan subsequent ones. +- Comparison across patterns is easier when each is presented the same way. +- Editing for completeness is easier (each section either has the elements or it does not). + +The variation. Some patterns warrant longer treatment (richer evidence, more complex implications); some are shorter. Length variation is fine; structural variation is not. + +--- + +## Be opinionated + +The principle. Synthesis that hedges every pattern reads as a researcher avoiding accountability. + +Hedged synthesis. + +- "Users may sometimes occasionally seem to indicate possible difficulty." +- "It might be considered to potentially explore some adjustments." +- "There could be benefits to investigating opportunities." + +These commit nothing. Readers cannot debate or decide on hedged synthesis. + +Opinionated synthesis. + +- "Users abandon configuration step 3 in 40% of signup attempts because credit card details are not accessible at signup." +- "The Q2 roadmap should prioritize the onboarding redesign over the dashboard expansion." +- "The not-act recommendation is to defer enterprise admin controls until small-team segment growth stabilizes." + +These commit positions. Readers can disagree; disagreement produces decisions. + +The discipline. Write synthesis as a recommendation. The PM doing synthesis is making analytical claims; readers may push back, but pushback is the point. Hedging avoids pushback by avoiding claim. + +The exception for honest uncertainty. When the data genuinely does not support a position, name the uncertainty explicitly: "The evidence supports two possible interpretations; we recommend gathering more data before deciding." This is honest uncertainty, not hedging. Hedging is dressing up uncertainty as if it were synthesis. + +--- + +## Include a decision-input section + +The principle. What does this synthesis recommend the team do? + +The section's role. The decision-input section connects the synthesis to the team's prioritization work. Without it, the synthesis presents patterns and implications but does not aggregate them into recommendations. + +What the section addresses. + +- Where should priorities shift based on this synthesis? +- Which roadmap items does the synthesis validate? Which does it challenge? +- Which decisions can the team make now with this synthesis as input? +- Which decisions need more research before making? +- What is the synthesis's overall view of where the product should focus? + +The section's voice. Direct, specific, opinionated. The team can disagree, but the section should commit a recommendation. + +The discipline. Without this section, synthesis is a collection of patterns; with this section, synthesis is decision input. The section is what makes the synthesis load-bearing for the team's strategic work. + +--- + +## Length calibration + +The principle. Synthesis should be as short as possible without losing the load-bearing content. + +Typical lengths. + +- Discovery cycle synthesis from a meaningful research batch: 6-12 pages. +- Smaller-scale synthesis from a single research type (e.g., support audit alone): 3-6 pages. +- Quick-turn synthesis from a focused interview batch: 2-4 pages. + +Length anti-patterns. + +- Synthesis padded to 30+ pages. Readers stop reading; the load-bearing content gets lost. +- Synthesis compressed to 1 page. Density too high; specifics get lost. +- Synthesis stretched across multiple documents without clear primacy. Readers do not know which document is the synthesis. + +The discipline. Edit for length. Each pattern section should be tight; each implication should be specific; the recommendation should be concise. Readers will engage with a 6-page synthesis they can finish in 20 minutes; readers will skim a 30-page synthesis and miss the recommendations. + +--- + +## The reference-after-shipping test + +The principle. Synthesis that gets referenced months after publication has earned its keep. + +The test. Six months after a synthesis ships, can the team: + +- Name the patterns the synthesis surfaced? +- Cite the synthesis in roadmap discussions? +- Use the synthesis as input for related decisions that came up after publication? + +Failures the test reveals. + +- Synthesis nobody can name suggests insight-theater (presented but not absorbed). +- Synthesis nobody references suggests document-shelf-syndrome (filed away after readout). +- Synthesis the team contradicts in later decisions suggests the synthesis was not load-bearing in their actual prioritization work. + +Recovery. When prior synthesis fails the test, the next synthesis should adjust: shorter, more opinionated, more directly tied to specific decisions. Each round of synthesis should be more usable than the prior. + +--- + +## Visual elements in synthesis documents + +The discipline. Visuals should carry argumentative load the prose alone cannot. + +Visuals that work. + +- A pattern-to-implication-to-decision diagram showing how the synthesis connects to product work. +- A frequency chart for patterns supported by quantitative data. +- A segment comparison table where patterns differ across segments. +- An evidence map showing artifact-source distribution per pattern. + +Visuals that fail. + +- Stock images decorating section breaks. +- Quote walls without context. +- Word clouds (rarely informative). +- Persona illustrations (decorative; not synthesis output). + +The frequency. Visual elements every 2-3 pages of synthesis is typical. More than that risks decoration; fewer is fine if the prose carries the work. + +--- + +## Common synthesis-writing failures + +Format choice. Deck instead of document; the synthesis decays into bullets that lose precision. + +Buried recommendations. Patterns are clear; the recommendation is one sentence on page 11. Readers miss it. + +Hedge-stacking. Every claim caveated; readers cannot extract a position. + +No decision-input section. Synthesis presents patterns; team has to aggregate them into decisions on their own; usually does not. + +Length excess. 30 pages of synthesis where 8 would have served. Readers skim; load-bearing content gets lost. + +Length compression. 1 page of synthesis where 6 were needed. Density too high; specifics lost. + +Quote-wall presentation. Evidence dominates; analysis recedes; readers admire the quotes and miss the synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The document-not-deck principle. The patterns-lead-evidence-appendix structure. The parallel-section discipline. The opinionated voice. The decision-input section. Length calibration. The reference-after-shipping test. Visual element discipline. Common failures. + +## Implementation choices that stay internal + +Specific document templates and styles. Specific document hosting (Notion, Coda, Google Docs, Confluence). Specific link conventions for evidence. Specific reviewer workflows. Specific archive practices. The team's own conventions for synthesis length within the bands. These vary by team and tooling. diff --git a/skills/documentation-strategy/SKILL.md b/skills/documentation-strategy/SKILL.md new file mode 100644 index 0000000..1b65361 --- /dev/null +++ b/skills/documentation-strategy/SKILL.md @@ -0,0 +1,428 @@ +--- +name: documentation-strategy +description: "Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long." +category: process-and-team +catalog_summary: "Documentation systems, what to document, maintenance cadence" +display_order: 2 +--- + +# Documentation Strategy + +Decide what gets documented, where, by whom, and how it stays fresh. Stack-agnostic. Applies to internal team docs, product docs, runbooks, READMEs, and knowledge bases. + +--- + +## When to use + +- Setting up documentation for a new team or product +- Auditing existing documentation +- Fixing stale or scattered docs +- Choosing a documentation tool or platform +- Defining what gets documented and what doesn't +- Establishing maintenance cadence +- Scoping technical writing work +- Designing onboarding documentation (use alongside `team-onboarding-playbook`) + +## When NOT to use + +- Writing the actual content of a single document (use `content-and-copy`) +- Customer-facing knowledge base copy (use `content-strategy`) +- Code comments and inline documentation (covered by `code-review-web`) +- One-off blog posts or articles (use `content-and-copy`) + +--- + +## Required inputs + +- The audience (internal, external, customer, dev, exec) +- Existing docs and their state (where, what shape, last updated) +- Team size and growth trajectory +- The kinds of work that produce documentation (engineering, product, ops, support) +- Tools currently in use + +--- + +## The framework: 4 categories of documentation + +Different categories of doc serve different purposes. Conflating them is how docs get bad. + +### Category 1: Reference + +What things are. Looked up when needed. + +Examples: API reference, configuration options, glossary, architecture diagrams, contact lists, decision log entries. + +Properties: +- Comprehensive +- Fact-checked, kept accurate +- Searchable +- Stable structure (links don't break) +- Version-aware where relevant + +### Category 2: How-to + +How to do specific tasks. Procedural. + +Examples: "Deploy to staging," "Reset a password," "Onboard a new contractor," "Run the backup restore drill." + +Properties: +- Step-by-step +- Tested by someone who didn't write it +- Includes the prerequisites +- Includes troubleshooting +- Versioned to the system it documents + +### Category 3: Explanation + +Why things are the way they are. Conceptual. + +Examples: architecture rationale, design decision records (ADRs), strategy docs, vision documents. + +Properties: +- Narrative +- Captures context (the why) +- Often historical (why we built it this way) +- Links to evidence + +### Category 4: Tutorial + +Learning-oriented. Walks someone from zero to capable. + +Examples: "Getting started with our codebase," "Your first deploy," onboarding pathways. + +Properties: +- Sequenced from simple to complex +- Hands-on +- Doesn't assume prior knowledge in scope +- Has clear completion criteria + +(This four-way split is the Diátaxis framework, well-known in tech writing. Memorize it.) + +--- + +## The framework: 5 tiers of doc + +Different docs serve different audiences with different stakes. + +### Tier 1: Customer-facing + +Public docs, customer KBs, API references. High visibility, slow change. + +Standards: +- Editorial review +- Version control +- Clear ownership +- High freshness bar +- Tied to release + +### Tier 2: Cross-team / shared + +Docs used across teams: shared APIs, common services, company-wide processes. + +Standards: +- Cross-team ownership clear +- Update obligations on changes +- Mid-to-high freshness bar + +### Tier 3: Team-internal + +Docs for the team that owns them: how the team works, runbooks, decisions. + +Standards: +- Team-owned, team-maintained +- Mid freshness bar +- Useful for the next person joining + +### Tier 4: Personal scratchpad + +Notes, drafts, work-in-progress. Not for others. + +Standards: +- Low maintenance +- Don't link from official docs +- Promote to higher tier when valuable + +### Tier 5: Auto-generated + +Docs derived from code: API references generated from comments, schemas, etc. + +Standards: +- Generation is automated, runs in CI +- Single source of truth (the code) +- Reviewed for usability, not freshness (that's automatic) + +The tiering matters because the maintenance bar differs. Asking team-internal docs to meet customer-facing standards is wasteful and unsustainable. + +--- + +## Workflow + +### Step 1: Audit current state + +- What docs exist? +- Where do they live? (often: scattered) +- Who owns each? +- How fresh are they? +- Are they actually used? (check page views or referrals if measurable) + +The audit is often eye-opening. Most teams have more docs than they realize, in more places than they realize. + +### Step 2: Categorize and tier + +For each doc: +- Category (reference / how-to / explanation / tutorial) +- Tier (customer / shared / team / scratchpad / generated) + +Some docs are mixed. Note the dominant category. + +### Step 3: Identify gaps + +What documentation does the team need that doesn't exist? + +Common gaps: +- "How does X actually work?" no answer +- Onboarding for the role no one's onboarded recently +- Runbook for a system that's never broken (yet) +- Decision rationale for "why are we doing it this way" + +Ask people what they wish were documented. They know. + +### Step 4: Identify dead weight + +Docs that are: +- Out of date and not getting updated +- Duplicated across places (one is canonical, others should redirect or be deleted) +- About things that no longer exist +- Drafts abandoned long ago + +Delete or archive. Stale docs are worse than missing docs (people might trust them). + +### Step 5: Pick the home(s) + +Where docs live affects whether they're maintained. + +Common locations: +- Code repo (markdown): for docs tightly coupled to code (READMEs, ADRs, runbooks for the service) +- Wiki / Notion / Confluence: for cross-team and team-internal +- Docs site (Docusaurus, Mintlify, custom): for customer-facing +- Tickets / decision logs: for ephemeral records + +Don't aim for one home. Aim for a clear answer to "where does this kind of doc live?" + +### Step 6: Establish ownership + +Every doc has an owner. Without an owner, it goes stale. + +Owner can be: +- A team +- A role (the on-call rotation, the PM, the EM) +- A person, with a backup + +If an owner isn't obvious, the doc may not deserve to exist. + +### Step 7: Establish maintenance cadence + +Per tier: + +\| Tier \| Review cadence \| +\|---\|---\| +\| Customer-facing \| Per release, plus quarterly \| +\| Cross-team \| Quarterly \| +\| Team-internal \| Quarterly \| +\| Personal scratchpad \| None \| +\| Auto-generated \| On every change \| + +Maintenance includes: +- Verify accuracy +- Update for changed systems +- Archive what's no longer relevant +- Address user feedback + +### Step 8: Make doc updates part of work + +Documentation isn't a separate project. It's part of the work that produces it. + +- New feature: docs are part of the feature +- New process: doc is part of the rollout +- Decision made: ADR or decision-log entry filed +- Bug postmortem: runbook updated +- New hire: onboarding doc updated based on their experience + +The team that ships features without docs has less than they think they have. + +### Step 9: Make docs discoverable + +Even great docs are useless if no one finds them. + +- Search that actually works (most platforms; some better than others) +- Index pages for major topics +- Cross-links between related docs +- Search aliases for common alternative phrasings +- Pinning the most-used docs + +### Step 10: Measure + +What's measurable depends on the platform: +- Page views +- Search queries (and zero-result queries) +- "Was this helpful?" feedback +- Time on page +- Referral patterns + +For internal docs, the qualitative measure is often more useful: are the same questions getting asked over and over? If yes, the docs aren't doing their job (either they don't exist, aren't found, or aren't clear). + +--- + +## Specific patterns + +### README per project + +Every code repo has a README that answers: +- What is this? +- How do I run it? +- How do I contribute? +- Where do I find more info? + +Five sentences each, often. Length isn't the goal. The READ-it-ME promise is. + +### ADR (Architecture Decision Record) + +Per significant decision: + +``` +# ADR-NNN: [Title] + +Status: [Proposed / Accepted / Deprecated / Superseded] +Date: [Date] + +## Context +[What's the situation? What forces are at play?] + +## Decision +[What was decided?] + +## Consequences +[What happens because of this decision? Both good and bad.] +``` + +ADRs accumulate. They become the explanation layer for "why are we doing it this way." + +### Runbook + +Per system: +- What it is +- How to access it +- Common operations (with commands) +- Common failure modes +- Restore from backup procedure +- Escalation contacts + +See `incident-response` and `backup-and-disaster-recovery` for runbook standards. + +### Onboarding pathway + +Per role: +- Day 1 +- Week 1 +- Month 1 +- 90 days + +See `team-onboarding-playbook`. + +### Decision log + +Lightweight version of ADRs. Date, decision, decider, why. Keeps a record without ceremony. + +### Glossary + +Terms that have specific meaning in the team or product. Reduces confusion. Trains AI tools too (more on that later). + +--- + +## Tooling + +The tool is less important than the discipline. That said: + +\| Tool category \| Examples \| Best for \| +\|---\|---\|---\| +\| Wiki \| Notion, Confluence, GitBook \| Cross-team, internal \| +\| Markdown in code \| GitHub, GitLab, Bitbucket \| READMEs, ADRs, technical \| +\| Docs sites \| Docusaurus, Mintlify, ReadMe \| Customer-facing, public docs \| +\| Internal sites \| MkDocs, custom \| Team-specific patterns \| + +Considerations: +- Search quality (a poor search makes everything worse) +- Editor quality (people won't write in painful editors) +- Version control (can you see history?) +- Permissions (right people can read and write) +- API and integration (for automation) +- Cost at your scale + +For small teams: a single wiki tool is plenty. For larger: tiered tools. + +--- + +## AI-related notes + +LLMs and AI assistants increasingly read documentation. Some considerations: + +- Clear, consistent structure helps both humans and AI +- A glossary of terms helps both +- File-level metadata (front matter) helps tools +- Public docs may be read by AI crawlers; consider an `llms.txt` if relevant +- AI-generated drafts are a starting point, not a final answer; humans review + +--- + +## Failure patterns + +Documentation as a "later" task. Always written later. Later means never. Make docs part of the work. + +One mega-doc for everything. Wiki page that's 8,000 words. No one reads it. Break by category and topic. + +Stale docs that nobody trusts. "Probably out of date" is the thought that kills documentation. Either keep current or archive. + +Docs everyone agrees should exist but no one writes. The team agrees onboarding docs would be valuable. Months pass. No one writes them. Make ownership specific. + +Wikis that are graveyards. Lots of pages, no one trusts any of them. Audit, archive, restart with a slimmer set. + +Docs separated from code. API docs in a wiki, code in a repo. They drift. Co-locate. + +Docs without examples. Reference without examples is hard to use. Examples make it concrete. + +Examples that don't run. Code examples that worked once, drifted. Test examples in CI where possible. + +Long-form when reference would do. A 2,000-word doc explaining what a 30-row table would. Use the right form. + +Multiple sources of truth. Same info in three places, all slightly different. Pick canonical, redirect others. + +Doc tools no one uses. Adopted because of a feature; team doesn't actually use it. Pick tools the team will use. + +Doc style guide that's longer than the docs. Process beats product. Guide should be short. + +No way to mark docs as deprecated. Old docs sit alongside current ones with no indication. Add a "deprecated" or "archived" status. + +No analytics. No idea what's being used or what's missing. Even basic page views inform priorities. + +Docs that read like specifications. Dense, formal, hard to scan. Write for the reader. + +--- + +## Output format + +A documentation strategy document includes: + +- Audit: what exists, where, in what state +- Tiering and categorization: the framework applied to existing docs +- Gap list: what should exist but doesn't +- Tool decisions: where each kind of doc lives +- Ownership map: who owns what +- Maintenance cadence: what's reviewed when +- Style guide (brief): consistency standards +- Roadmap: prioritized work to fill gaps and close out dead weight + +--- + +## Reference files + +- [`references/doc-types-guide.md`](references/doc-types-guide.md): Detailed guide to the four doc types (reference, how-to, explanation, tutorial) with examples and templates for each. diff --git a/skills/documentation-strategy/references/doc-types-guide.md b/skills/documentation-strategy/references/doc-types-guide.md new file mode 100644 index 0000000..badadbf --- /dev/null +++ b/skills/documentation-strategy/references/doc-types-guide.md @@ -0,0 +1,451 @@ +# Doc Types Guide + +The four categories of documentation, what each is for, and a template for each. Based on the Diátaxis framework (well-known in technical writing). + +The categories aren't interchangeable. Mixing them is the most common failure in documentation: a "tutorial" that's actually reference, a "how-to" that's secretly explanation, a "reference" that meanders into tutorial territory. + +--- + +## The four types + +\| Type \| Purpose \| Reader needs \| Style \| +\|---\|---\|---\|---\| +\| Reference \| Look up facts \| "What is the value of X?" \| Comprehensive, terse \| +\| How-to \| Solve a specific problem \| "How do I do Y?" \| Step-by-step, focused \| +\| Explanation \| Understand the why \| "Why does Z work this way?" \| Discursive, narrative \| +\| Tutorial \| Learn from zero \| "How do I get started?" \| Hands-on, sequenced \| + +A useful diagram of how they relate: + +``` + Practical (action) + \| + HOW-TO ───────────\|─────────── REFERENCE + \| + \| + Theoretical (understanding) + \| + TUTORIAL ───────────\|─────────── EXPLANATION + \| + Study (acquiring skill) Work (applying skill) +``` + +- Tutorial and how-to are practical (the reader is doing something) +- Reference and explanation are theoretical (the reader is understanding something) +- Tutorial and explanation are study-oriented (acquiring skill or understanding) +- How-to and reference are work-oriented (applying skill) + +--- + +## Reference + +### What it is + +The complete catalog of facts about something. Looked up when needed. + +### Examples + +- API reference (every endpoint, every parameter, every response) +- Configuration options (every flag, every default, every effect) +- Glossary (every term, definition) +- Error code catalog +- Component library docs + +### What makes it good + +- Comprehensive (covers everything) +- Accurate (verified against the actual system) +- Consistently structured (each entry follows the same pattern) +- Searchable (people find what they need quickly) +- Stable links (entries don't move or disappear without redirects) + +### What makes it bad + +- Editorializing ("This is the best way...") +- Tutorials interleaved (reader looking up a fact gets a wall of explanation) +- Inconsistent depth (some entries thorough, others sparse) +- Out of date (single most common reference failure) + +### Template + +``` +# [Function / Endpoint / Setting / Term] + +Type: [function / endpoint / configuration / etc.] +Since: [version introduced] +Status: [stable / beta / deprecated] + +## Description + +[1-2 sentences. What this is.] + +## [Parameters / Inputs / Properties] + +\| Name \| Type \| Default \| Description \| +\|---\|---\|---\|---\| +\| [name] \| [type] \| [default] \| [description] \| + +## [Returns / Output] + +[Description of return value or output.] + +## Examples + +[Minimum useful example.] + +## Notes + +- [Edge case] +- [Gotcha] +- [Related: link to related reference] +``` + +--- + +## How-to + +### What it is + +A guide to accomplishing a specific task. The reader has a problem; the how-to gives the solution. + +### Examples + +- "How to deploy to production" +- "How to reset a forgotten password" +- "How to add a new locale" +- "How to migrate data from system A to system B" + +### What makes it good + +- Goal-oriented (solves a specific problem) +- Sequential (steps in order) +- Tested (someone other than the author followed it) +- Includes prerequisites +- Includes troubleshooting for known issues +- Realistic (uses real values, not placeholders that confuse) + +### What makes it bad + +- Mixed with explanation (the reader wants to act, not understand the design) +- Too generic (steps don't apply cleanly to the actual situation) +- Out of date (commands no longer work) +- Missing prerequisites (reader gets stuck on step 2 because of an unstated dependency) +- Too many branches ("If X then..., else if Y then..."; usually means it should be split into multiple how-tos) + +### Template + +``` +# How to [Specific Task] + +## Goal + +[1 sentence: what the reader will accomplish.] + +## Before you start + +- [Prerequisite 1] +- [Prerequisite 2] +- [Prerequisite 3] + +## Steps + +### 1. [First step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 2. [Second step] + +[Action description] + +``` +[Command or example] +``` + +[Expected outcome of this step] + +### 3. [Third step] + +[...] + +## Verify + +[How to confirm the task succeeded.] + +## Troubleshooting + +Problem: [Common issue] + +[Cause and resolution.] + +Problem: [Common issue] + +[Cause and resolution.] + +## See also + +- [Related how-to] +- [Related reference] +``` + +--- + +## Explanation + +### What it is + +The why. Discursive. Helps the reader understand the design, the rationale, the tradeoffs. + +### Examples + +- Architecture documents +- Design rationale +- Decision records (ADRs) +- "Why we don't support feature X" +- Strategy documents +- Conceptual overviews + +### What makes it good + +- Captures the why (not just the what) +- Honest about tradeoffs (every design choice has a cost) +- Includes alternatives considered +- Time-stamped (so readers know when this was true) +- Connects to other concepts + +### What makes it bad + +- Lecture-y (reader feels talked down to) +- Ahistorical (no context of why decisions were made) +- Marketing voice (everything is "great" and "exciting") +- Buried in how-to (reader is trying to do something; explanation slows them down) + +### Template (ADR specifically) + +``` +# ADR-NNN: [Title of decision] + +Status: [Proposed / Accepted / Deprecated / Superseded by ADR-MMM] +Date: [YYYY-MM-DD] +Deciders: [Who was involved] + +## Context + +[What's the situation? What's the problem? What forces are at play?] + +[Include enough context that a reader new to this can understand. Don't assume the present-day context will be obvious in the future.] + +## Decision + +[What was decided. State it clearly.] + +## Alternatives considered + +### Alternative A: [Name] + +[Description, why not chosen.] + +### Alternative B: [Name] + +[Description, why not chosen.] + +## Consequences + +### Positive + +- [What's better as a result] +- [What's better as a result] + +### Negative + +- [What's worse or constrained as a result] +- [What's worse or constrained as a result] + +### Neutral / mixed + +- [Tradeoffs that aren't clearly good or bad] + +## Notes + +[Anything else relevant. Links to discussion threads, prototypes, related decisions.] +``` + +### Template (general explanation doc) + +``` +# [Topic] + +## What this is + +[2-3 sentences orienting the reader.] + +## Background + +[The context. What was true before. Why this came up.] + +## How it works + +[The substance. Walk through the design, the model, the structure. Use diagrams.] + +## Why this approach + +[The rationale. What we considered. What we chose and why.] + +## Tradeoffs + +[Honest accounting of what's good and bad about this approach.] + +## See also + +[Related explanation, related decisions, related reference.] +``` + +--- + +## Tutorial + +### What it is + +Learning by doing. The reader starts with no knowledge of the topic and finishes capable of using it. + +### Examples + +- "Getting started with our SDK" +- "Your first deployment" +- Onboarding pathways for new team members +- "Building your first integration" + +### What makes it good + +- Sequenced from simple to complex +- Hands-on (the reader does things, not just reads) +- Concrete (real values, real commands, real outcomes) +- Has clear completion criteria +- Builds on a single thread (one project, one example) +- Acknowledges where the reader is (beginner) + +### What makes it bad + +- Reference dressed up as tutorial (no thread, no completion) +- Skips steps "for brevity" (reader gets stuck) +- Uses placeholders like `<your-value-here>` without making them concrete +- Assumes prior knowledge that wasn't stated as prerequisite +- Branches early ("if you want X, do this; if Y, do this") instead of staying focused + +### Template + +``` +# Getting started with [Thing] + +## What you'll build + +[1-2 sentences describing the end state. Maybe a screenshot or example output.] + +## Time required + +[Realistic estimate, e.g. "30-45 minutes"] + +## Before you start + +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] +- [Prerequisite, with how to check] + +## Step 1: [First milestone] + +[Plain-English description of what we're doing in this step.] + +[Concrete instructions:] + +``` +[Specific command] +``` + +[What you should see:] + +``` +[Expected output] +``` + +If something different happens, see [Troubleshooting section]. + +## Step 2: [Second milestone] + +[Same pattern.] + +## Step 3: [Third milestone] + +[Same pattern.] + +[...] + +## What you've built + +[Recap. The reader should feel: I get it now.] + +## Where to go next + +- [Next tutorial] +- [Reference for what you just used] +- [How-to for related task] + +## Troubleshooting + +[Specific problem someone might hit] + +[Cause and resolution.] +``` + +--- + +## How to use this in practice + +### When writing new docs + +Identify which type before starting. Don't mix. + +If a doc has tutorial sections AND reference sections AND explanation sections, it's three docs. Split. + +### When auditing existing docs + +For each existing doc, ask: which type is this trying to be? + +If it's mixed, split. The split is usually: keep the dominant type in the original, link to the other types. + +### When linking between types + +The four types reinforce each other: +- Tutorials link to reference for the things they introduce +- How-tos link to reference for the commands they use +- Reference links to explanation for the why +- Explanation links to how-to for "to do this, see..." + +A connected web of all four serves the reader well. + +### When choosing the type for a need + +\| Reader is asking \| Type \| +\|---\|---\| +\| "What does X mean?" \| Reference \| +\| "What's the syntax for X?" \| Reference \| +\| "How do I do Y?" \| How-to \| +\| "How do I solve [specific problem]?" \| How-to \| +\| "Why does Z work this way?" \| Explanation \| +\| "What did we decide about W?" \| Explanation (ADR) \| +\| "I'm new; where do I start?" \| Tutorial \| + +If the answer is "all of the above," the reader actually needs multiple docs, not one mega-doc. + +--- + +## Anti-patterns to recognize + +- The "everything" doc: tries to be all four types. Reads like all four poorly. +- The "guide" doc: vague title, vague purpose. Often a how-to that lost focus. +- The "manual" doc: monolithic. Unmaintainable. Split. +- The "wiki page that became sacred: historical accumulation. Past usefulness. Audit and split or archive. diff --git a/skills/domain-strategy/SKILL.md b/skills/domain-strategy/SKILL.md new file mode 100644 index 0000000..568e44d --- /dev/null +++ b/skills/domain-strategy/SKILL.md @@ -0,0 +1,218 @@ +--- +name: domain-strategy +description: "Plan, manage, and optimize a domain portfolio. Use this skill for DNS architecture decisions, redirect strategies, registrar choice, parking unused domains, multi-site setups, and domain consolidation or split planning. Triggers on DNS, domain, registrar, redirect, parking, subdomain, apex, www vs non-www, multi-site, portfolio, hreflang setup, domain migration. Also triggers when planning a new site that needs domain decisions made before launch." +category: operations +catalog_summary: "DNS architecture, redirects, registrars, multi-domain portfolios" +display_order: 4 +--- + +# Domain Strategy + +Decide how domains, subdomains, and DNS work across a portfolio. Stack-agnostic. Works for one site or one hundred. + +--- + +## When to use + +- Setting up DNS for a new site (apex vs www, primary vs aliases) +- Choosing or switching registrars +- Planning redirects across multiple domains (parked, retired, consolidated) +- Deciding subdomain vs subfolder vs separate domain for a new product line +- Consolidating multiple sites into one +- Splitting one site into multiple +- Setting up DNS for email, security records, third-party services + +## When NOT to use + +- Migrating content between platforms with URL changes (use `content-migration`) +- Email authentication setup specifically (use `email-deliverability`) +- Security headers or HTTPS config (use `security-baseline`) +- Internationalization domain choices (use `internationalization`) + +--- + +## Required inputs + +- Current domain inventory (every domain you own or operate) +- Status of each (live, parked, redirected, retired) +- Strategic role of each (primary brand, sub-brand, defensive registration, campaign) +- Current DNS provider and registrar for each +- Email and third-party service dependencies + +--- + +## The framework: 5 decisions + +Every domain decision falls into one of these buckets. Address them in order. + +### Decision 1: Apex vs www as canonical + +Pick one. Redirect the other to it. Pick before launch. Changing later is painful. + +- Apex (example.com): cleaner, more memorable, the modern default. +- www (www.example.com): historically standard, easier to add CDN-level CNAME records (apex CNAME is technically forbidden but most providers offer ALIAS or ANAME). + +Whichever you pick, the other must 301 to it. Both serving content is duplicate content and a soft signal of poor setup. + +### Decision 2: Subdomain vs subfolder vs separate domain + +For a new product, blog, or content section: + +\| Pattern \| Use when \| +\|---\|---\| +\| Subfolder (`example.com/blog`) \| Same brand, want SEO equity to flow, default choice \| +\| Subdomain (`blog.example.com`) \| Different stack or platform, organizationally separate but related \| +\| Separate domain (`exampleblog.com`) \| Different brand, different audience, intentional separation \| + +Default to subfolder. The case for subdomain or separate domain has to be made. + +### Decision 3: Registrar strategy + +The registrar is where the domain is registered. The DNS provider is where DNS records live. They can be the same or different. + +Decisions: +- Single registrar vs multiple: single is simpler. Multiple makes sense for redundancy at scale. +- Lock and 2FA: non-negotiable. Domain hijacking is real and costly. +- Auto-renew: on for everything you care about. Off only for intentional drops. +- WHOIS privacy: on by default. Free at most modern registrars. +- Transfer lock: on except during planned transfers. + +### Decision 4: DNS provider + +The DNS provider controls how domains resolve. Critical for performance, reliability, and security. + +Pick a provider that gives you: +- Fast global resolution (anycast network) +- DNSSEC support +- API access for automation +- Reasonable record limits +- Good audit logs + +Default DNS records every domain needs: +- A or AAAA records (or CNAME) for the apex and www +- MX records (even just nullified if no email) +- TXT for domain verification, SPF +- CAA records (locks down which certificate authorities can issue certs for the domain) + +### Decision 5: Parked domain strategy + +Domains you own but aren't actively using. Three valid strategies: + +1. Redirect to a primary site. Best for defensively registered domains close to your main brand. 301 every path to the primary's homepage or matching path. +2. Hold blank. A simple page or DNS NXDOMAIN. Acceptable for domains you may use later. +3. Park with a landing page. Generic "coming soon" page. Lowest value. Avoid registrar default parking pages (often serve ads against your brand). + +Anti-pattern: letting parked domains serve duplicate or near-duplicate content from your main site. This is an SEO liability. + +--- + +## Workflow + +### Step 1: Inventory + +Pull every domain you own from every registrar. Build a single sheet: + +\| Domain \| Registrar \| DNS provider \| Status \| Role \| Renewal date \| Notes \| +\|---\|---\|---\|---\|---\|---\|---\| + +If you can't account for every domain, the strategy can't be accurate. + +### Step 2: Classify by role + +Each domain gets one role: +- Primary (the main site for a brand) +- Alias (redirects to a primary) +- Defensive (registered to prevent others from getting it; usually parked) +- Campaign (short-term, specific use) +- Retired (no longer active; either drop at expiry or redirect permanently) + +The classification drives the configuration. + +### Step 3: Audit current configuration + +For each domain check: +- Is the canonical (apex vs www) consistent with the strategy? +- Are redirects 301 (permanent) where intended? +- Is HTTPS enforced on every variant? +- Are DNS records minimal and intentional? +- Is the registrar locked? +- Is auto-renew on? +- Is 2FA on the registrar account? + +Document gaps. Each gap is a ticket. + +### Step 4: Set the canonical pattern + +For new domains and any that need fixing: + +- Pick apex or www as canonical +- Configure 301 redirect for the non-canonical +- Force HTTPS for both +- Verify with curl: `curl -I http://example.com`, `curl -I http://www.example.com`, `curl -I https://www.example.com`. All should chain to a single 200 on the canonical. + +### Step 5: Document the redirect map + +Across the portfolio, document every redirect: + +\| Source \| Destination \| Type \| Reason \| Date set \| +\|---\|---\|---\|---\|---\| + +This is invaluable when something breaks or when planning consolidations. + +### Step 6: Set up monitoring + +Monitor: +- DNS resolution (alert on NXDOMAIN or wrong IP) +- HTTPS certificate expiration (alert at 30, 14, 7 days out) +- Redirect chains (alert if a 301 starts returning 200 or 404) +- Renewal dates (alert at 90, 30, 7 days out) + +This is the bridge between domain strategy and `monitoring-and-alerting`. + +### Step 7: Document and revisit + +Domain strategy is a quarterly review topic. Renewals, consolidations, and new launches change the picture. Without scheduled review, the portfolio drifts. + +--- + +## Failure patterns + +Both apex and www serve content. Duplicate content. Pick one, redirect the other. + +302 redirects where 301 was intended. 302 is temporary. 301 is permanent. SEO equity passes through 301, not (reliably) through 302. + +HTTPS not enforced. HTTP variant serving content alongside HTTPS. Force HTTPS at the edge or the load balancer. + +Registrar default parking pages. Parked domains serving registrar ads. Free for the registrar, bad for you. Replace with a redirect or your own page. + +Domains in multiple registrars by accident. Migrations that didn't fully complete. Consolidate. + +No CAA records. Anyone with a misconfigured ACME client can issue a cert for your domain. CAA limits which CAs can issue. Add it. + +Auto-renew off "to save money." Domain accidentally drops, gets snapped up, costs ten times more (or is unrecoverable). Auto-renew is cheap insurance. + +Subdomains used where subfolders would have been better. SEO equity gets fragmented across hostnames. The case for a subdomain has to be made; the default is subfolder. + +Parked domains with thin content "for SEO." Search engines don't reward this. They penalize doorway pages. Either redirect or leave blank. + +--- + +## Output format + +A domain strategy document includes: + +- Inventory: the spreadsheet of every domain +- Classification: the role of each +- Canonical decisions: apex vs www, locked +- Redirect map: every redirect in the portfolio +- DNS standards: the default record set +- Registrar standards: locked, 2FA, auto-renew +- Monitoring: what's watched, where alerts go +- Renewal calendar: the next 12 months +- Review cadence: when this gets revisited + +--- + +## Reference files + +- [`references/dns-record-reference.md`](references/dns-record-reference.md): Common DNS records explained, with the syntax for the most useful ones (A, AAAA, CNAME, MX, TXT, CAA, SRV, etc.) and when each is needed. diff --git a/skills/domain-strategy/references/dns-record-reference.md b/skills/domain-strategy/references/dns-record-reference.md new file mode 100644 index 0000000..62edfff --- /dev/null +++ b/skills/domain-strategy/references/dns-record-reference.md @@ -0,0 +1,252 @@ +# DNS Record Reference + +A quick reference to the DNS records every domain operator should understand. Stack-agnostic. The syntax is the same across DNS providers. + +--- + +## Address records + +### A record + +Maps a name to an IPv4 address. + +``` +example.com. 300 IN A 192.0.2.1 +www.example.com. 300 IN A 192.0.2.1 +``` + +Use for the apex and any subdomain that resolves to a specific IPv4. + +### AAAA record + +Maps a name to an IPv6 address. + +``` +example.com. 300 IN AAAA 2001:db8::1 +``` + +If your infrastructure supports IPv6, set AAAA records alongside A records. Many ISPs prefer IPv6. + +### CNAME record + +Maps a name to another name (which must resolve to A or AAAA). + +``` +www.example.com. 300 IN CNAME example.com. +shop.example.com. 300 IN CNAME shopify-store.myshopify.com. +``` + +CNAME cannot be used at the apex (e.g., `example.com.` cannot be a CNAME). Most providers offer ALIAS or ANAME records as a workaround for apex. + +CNAME at a name conflicts with any other record at the same name. You can't have both a CNAME and an MX at the same name, for example. + +--- + +## Mail records + +### MX record + +Specifies mail servers for the domain. Priority is the first number; lower wins. + +``` +example.com. 300 IN MX 10 mx1.mailprovider.com. +example.com. 300 IN MX 20 mx2.mailprovider.com. +``` + +Even if the domain doesn't send or receive email, set a "null MX" to prevent spoofing: + +``` +example.com. 300 IN MX 0 . +``` + +This is the "this domain doesn't accept mail" signal, defined in RFC 7505. + +### TXT record (for SPF, DKIM, DMARC) + +TXT records hold arbitrary text. The most common use is email authentication. + +SPF (Sender Policy Framework): declares which servers can send mail for the domain. + +``` +example.com. 300 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +``` + +Only one SPF record per domain. Multiple SPF records break SPF entirely. + +DKIM (DomainKeys Identified Mail): publishes the public key for signing outgoing email. + +``` +selector1._domainkey.example.com. 300 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +The selector is set by your mail provider. Different providers use different selectors. + +DMARC (Domain-based Message Authentication): tells receivers what to do with mail that fails SPF or DKIM. + +``` +_dmarc.example.com. 300 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +``` + +Start with `p=none` for monitoring, then move to `p=quarantine` and finally `p=reject` once aligned. See `email-deliverability` skill for the full progression. + +--- + +## Security records + +### CAA record + +Certificate Authority Authorization. Restricts which CAs can issue certificates for the domain. + +``` +example.com. 300 IN CAA 0 issue "letsencrypt.org" +example.com. 300 IN CAA 0 issuewild "letsencrypt.org" +example.com. 300 IN CAA 0 iodef "mailto:security@example.com" +``` + +Without CAA, any public CA can issue a cert for your domain. With CAA, only the listed CAs can. Add CAA for any domain you care about. + +The `iodef` directive specifies where to email reports of unauthorized issuance attempts. + +### TLSA record + +Used with DNSSEC for DANE (DNS-based Authentication of Named Entities). Pins the TLS certificate or public key in DNS. + +``` +_443._tcp.example.com. 300 IN TLSA 3 1 1 abc123def456... +``` + +Niche. Most operators won't need TLSA. Useful for high-security applications. + +### DNSKEY, DS, RRSIG (DNSSEC) + +DNSSEC signs DNS responses cryptographically, preventing spoofing. Setup is provider-specific. Most modern DNS providers offer one-click DNSSEC. Enable it if available. + +--- + +## Service discovery + +### SRV record + +Specifies the location of services (priority, weight, port, target). + +``` +_sip._tcp.example.com. 300 IN SRV 10 60 5060 sip-server.example.com. +``` + +Used for SIP, XMPP, and similar. Most websites don't need SRV records. + +### NS record + +Specifies authoritative name servers for the domain (or a delegated subdomain). + +``` +example.com. 300 IN NS ns1.dns-provider.com. +example.com. 300 IN NS ns2.dns-provider.com. +``` + +NS records are usually managed by the registrar (for the apex) or by you (for delegated subdomains). + +### SOA record + +Start of Authority. Contains administrative info about the zone. + +``` +example.com. 300 IN SOA ns1.dns-provider.com. admin.example.com. 2024010101 7200 3600 1209600 300 +``` + +Auto-managed by most DNS providers. The serial number (2024010101) increments on every zone change. + +--- + +## TTL guidance + +TTL is how long a record can be cached by resolvers, in seconds. + +\| Record type \| Recommended TTL \| Reason \| +\|---\|---\|---\| +\| A, AAAA on stable infrastructure \| 3600 (1 hour) to 86400 (1 day) \| Reduces lookup load \| +\| A, AAAA during a migration \| 300 (5 min) \| Fast cutover \| +\| CNAME \| 3600 to 86400 \| Stable mappings \| +\| MX \| 86400 (1 day) \| Mail rarely changes \| +\| TXT (SPF, DMARC) \| 3600 \| Quick to update if needed \| +\| CAA \| 86400 \| Rarely changes \| + +Lower TTL during migrations. Raise it back after. + +--- + +## Common record patterns + +### A new website, single domain + +``` +example.com. 3600 IN A 192.0.2.1 +example.com. 3600 IN AAAA 2001:db8::1 +www.example.com. 3600 IN CNAME example.com. +example.com. 3600 IN MX 10 mx.mailprovider.com. +example.com. 3600 IN TXT "v=spf1 include:_spf.mailprovider.com -all" +_dmarc.example.com. 3600 IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com" +example.com. 86400 IN CAA 0 issue "letsencrypt.org" +example.com. 86400 IN CAA 0 iodef "mailto:security@example.com" +``` + +### A domain that doesn't send mail + +Same as above but replace MX records with the null MX: + +``` +example.com. 86400 IN MX 0 . +``` + +And the SPF can be: + +``` +example.com. 3600 IN TXT "v=spf1 -all" +``` + +### A redirect-only domain + +For a parked or alias domain that only redirects to a primary: + +``` +parked-example.com. 3600 IN A 192.0.2.10 +parked-example.com. 86400 IN MX 0 . +parked-example.com. 3600 IN TXT "v=spf1 -all" +parked-example.com. 86400 IN CAA 0 issue "letsencrypt.org" +``` + +The A record points to whatever serves the redirect. The null MX and SPF prevent the domain from being used for email spoofing. + +--- + +## Common mistakes + +Multiple SPF records. Only one SPF record per domain is allowed. Two or more break SPF entirely. To "include" multiple senders, combine them in a single `v=spf1` record. + +CNAME at the apex. Forbidden by the DNS spec. Use ALIAS or ANAME (provider-specific) or just use an A record. + +TTL too low long-term. Sub-300 TTLs cause unnecessary DNS query load. Use low TTLs only during migrations. + +Forgotten CAA record after switching CAs. If you switch from Let's Encrypt to another CA but the CAA record only lists Let's Encrypt, the new CA can't issue. Update CAA before issuing. + +No null MX on non-mail domains. Domain becomes a target for spoofing. Cheap to add the null MX. + +Manual records that should be provider-managed. Many providers manage records for their services automatically (e.g., Vercel, Cloudflare). Manual records can drift and conflict. + +--- + +## Tooling + +For testing DNS: +- `dig` (command line, the standard) +- `nslookup` (older but widespread) +- Online tools: dnschecker.org, mxtoolbox.com, intodns.com (good for sanity-checking a fresh setup) + +For testing email auth specifically: +- mail-tester.com +- dmarcian.com +- mxtoolbox.com (deliverability tab) + +For monitoring DNS in production: +- Most monitoring services include DNS checks (uptime providers, observability platforms) +- See `monitoring-and-alerting` skill for setting these up. diff --git a/skills/editorial-qa/SKILL.md b/skills/editorial-qa/SKILL.md new file mode 100644 index 0000000..0f99207 --- /dev/null +++ b/skills/editorial-qa/SKILL.md @@ -0,0 +1,334 @@ +--- +name: editorial-qa +description: "Pre-publish QA framework for content. Brief adherence, voice consistency, fact accuracy, structure and clarity, AI-content audit, SEO and AEO compliance, internal linking and schema validation, QA at scale via sampling, the QA workflow, and the discipline that distinguishes catch-problems QA from checkbox QA. Triggers on editorial QA, content review, pre-publish review, content audit, content QA process, AI-content audit, hallucination check, content sampling, programmatic QA, voice consistency check, brief adherence check. Also triggers when a content team is shipping sloppy work, when AI-co-authored content is reaching publish unaudited, when a QA process burns reviewers out, or when a programmatic SEO set needs sampling discipline." +category: content +catalog_summary: "Pre-publish QA framework: brief adherence, voice consistency, fact accuracy, AI-content audit, AEO/SEO compliance, sampling at scale, and the workflow that distinguishes catch-problems QA from process theater" +display_order: 7 +--- + +# Editorial QA + +A senior editor's playbook for pre-publish content QA. The discipline that catches problems BEFORE content ships, not after. + +Most content QA is broken in one of two directions. The thin version is "did I read it once and is the spelling OK," which catches typos but misses brief drift, voice inconsistency, hallucinated facts, AI tells, and structural problems that reach readers as "this is fine but not memorable." The thick version is a 47-item checklist that nobody completes honestly because it is process theater: checkboxes nobody actually believes catch problems. + +This skill is the discipline of catch-problems QA. Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Checks the production volume cannot sustain get redesigned (sampling instead of full audit, automated instead of manual). The QA framework is what is left when you remove the theater. + +The skill covers three production shapes: single editorial pieces (one at a time, full QA), AI-generated drafts (with the AI-content audit that did not exist as prominently 2 years ago), and programmatic SEO sets at scale (sampling discipline, threshold gating). Each needs its own QA shape; the underlying methodology composes across all three. + +When to use this skill: building a content QA process from scratch, auditing an existing QA process that ships sloppy work or burns out the team, designing QA gates for an AI-assisted workflow, or building sampling discipline for programmatic SEO sets. + +--- + +## What this skill is for + +This skill spans pre-publish quality control. It plugs in at the END of every other content skill's output. The six-skill content suite distinction: + +- `content-strategy` is program scope: what to produce. +- `pillar-content-architecture` is hub scope: how the topical hub fits together. +- `content-brief-authoring` is per-piece scope: briefs each piece. +- `content-and-copy` is execution scope: writes each piece. +- `programmatic-seo` is scaled scope: generates many pages from data. +- This skill is gate scope: verifies before publish. + +Every skill above produces a draft. This skill is what gets drafts to publishable. It is the gate where quality is actually enforced. + +The audience: editorial leads, content directors, in-house content QA, agencies with production lines, content ops managers, anyone running a writer (human or AI) and accountable for what ships. The voice is senior editor to junior editor or content marketer. Specific, opinionated, honest about where QA earns its keep versus where it becomes process theater. + +--- + +## Catch-problems QA vs checkbox QA + +The keystone distinction. Two failure modes plus the discipline. + +Thin QA (typo-checking dressed as quality control). "I read it once, it is fine." Catches obvious mistakes; misses brief drift, voice inconsistency, hallucinated facts, structural problems, AI tells. Output: shipped content that is "fine but not memorable." Cost: invisible until a brand misstep, a hallucinated statistic, or a competitor's content compounds and the thin set falls behind. + +Thick QA (47-item checklist nobody completes honestly). Every conceivable check listed; no triage. Reviewers either skim and check boxes (theater) or burn out under the cognitive load. Output: shipped content slightly more polished than thin QA produces, but the team's review velocity collapses. Cost: throughput drops; reviewers leave; the checklist atrophies into a few checks that actually run. + +Catch-problems QA (the discipline). Each check earns its keep by catching a specific class of failure that would reach readers if missed. Checks that do not catch anything get cut. Production volume drives sampling versus full-audit decisions. Reviewers are accountable for what they caught, not for box-completion. + +The litmus test. If the team can name the last 3 problems each QA check caught, the check earns its keep. If a check has not caught anything in 6 months, it is theater. Cut it; reallocate the attention to checks that catch real problems. + +--- + +## Brief adherence check + +Did the writer execute the brief? The check is straightforward when the brief is well-authored (see `content-brief-authoring`). + +The brief-adherence checks: + +- Target keyword and cluster. Present in title, first paragraph, headings. +- Search intent and SERP format. Piece matches the dominant SERP format (article when SERP wants article, listicle when SERP wants listicle). +- Target audience. Piece reads as written FOR the named audience, not for a generic reader. +- Heading structure. Piece follows the H2 / H3 outline in the brief, or has a documented reason for deviation. +- Required entities. Every entity flagged in the brief appears in the piece. +- Internal links. Outbound links specified in the brief are present with the right anchor text. +- Anti-patterns. Piece avoids the off-limits language and structures named in the brief. +- Success criteria acknowledged. Piece is shaped to MEASURE against the success criteria. + +The brief-adherence check is the cheapest, fastest, highest-value QA gate. It runs first in the QA sequence because catching a brief-adherence failure early saves the editor from spending time on voice and structure on a piece that will need to restart. + +If briefs are vague, this check is impossible. Fix briefs first; the QA process cannot enforce a contract that does not exist. + +Detail in [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md). + +--- + +## Voice consistency check + +Does the piece sound like the brand? + +- Vocabulary. Brand-specific terms used correctly; off-brand terms absent. +- Sentence rhythm. Matches brand voice (short and punchy versus measured and layered versus colloquial). +- Stance. The piece takes positions consistent with brand POV. +- Register. Formal or casual matches the surface (blog versus whitepaper versus help doc). +- Voice drift in long pieces. 3,000-word pieces often start in brand voice and drift to generic by section 4. Sample paragraphs from start, middle, end. + +For AI-co-authored pieces, voice drift is the dominant failure mode. AI assistants regress to a model-default voice unless the writer actively pulls them back. The QA check needs to read for the brand voice as much as for the words. + +Detail in [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md). + +--- + +## Fact accuracy and citation discipline + +Every claim in the piece needs to be true. The check: + +- Statistics. Every number sourced or removed if no source. +- Quotes. Every quote attributed to a real person who actually said it. +- Case studies. Every example refers to a real company or scenario, or labeled clearly as hypothetical. +- Dates and timelines. Verified, not approximate. +- Named experts. Real people who consented to attribution. +- Product claims. Matches actual product behavior, not future-tense roadmap or marketing aspiration. + +Hallucination is the dominant failure mode in AI-assisted writing. AI assistants generate plausible statistics, plausible quotes, plausible case studies, none of which are real. The fact-accuracy check is the gate that catches them. If you skip this gate on AI-generated content, you ship hallucinations. + +Citation discipline: + +- Inline citations link to authoritative sources (academic papers, industry reports, primary sources). +- Avoid citing other content marketing pages (citation laundering). +- Date the source; sources older than 3 years for fast-moving topics need refresh. + +Detail in [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md). + +--- + +## Structure and clarity check + +Does the piece work as a piece? + +- Lede. First 200 words answer the user's likely query (for SEO/AEO pieces) OR establish the thesis (for thought leadership). +- Sectioning. H2s map to user mental model, not writer enthusiasm. +- Section length. Even-ish across H2s. One massive section plus four 80-word sections signals broken structure. +- Reading flow. Paragraphs connect, sentences vary in length. +- Specificity vs abstraction. Claims are concrete, not vague. +- Endings. Piece concludes with something specific (action, question, idea), not throat-clearing filler. + +Detail in [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md). + +--- + +## AI-content audit + +The QA check that did not exist as prominently 2 years ago. AI-co-authored content has detectable patterns even when written by a competent human editor. + +AI tells (pattern recognition). + +- Excessive em-dashes (model-default punctuation) +- Predictable opening phrasings (throat-clearing openers that announce what the piece is about to do; the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener) +- Predictable concluding paragraphs (throat-clearing wrap-ups, "By following these steps") +- Bullet-list overuse where prose would serve +- "On the other hand" / "However" overuse +- Forced bilateral framing (always "two sides" even when one side is right) +- Sentence-end filler ("...and more.", "...among other things.", "...for example.") +- Repetitive sentence-rhythm (every paragraph 2-3 sentences, similar lengths) +- Generic openings (descriptive paragraphs that could open any article on the topic) +- Bridging fluff ("That said", "With that in mind", "Moving on") +- Hedge stacking ("typically", "generally", "often") on claims that should be specific + +Hallucination patterns (factual errors). + +- Statistics that look authoritative (specific decimal places, named source) but the source does not exist or does not say that +- Quotes attributed to real people who did not say it +- Case studies about companies that do not exist +- Citations to URLs that 404 or never existed +- "Studies show" claims with no actual study behind them +- Made-up product features + +Voice drift. + +- Piece starts in brand voice, drifts to generic by section 4 +- Vocabulary regresses to model defaults +- Stance becomes diplomatic ("there are good arguments on all sides") when brand stance was clear + +The audit shape. Read with these patterns top-of-mind. Flag any match. The bar is not "AI was used" (it almost always is now); the bar is "would a careful human editor have shipped this." If the patterns above are present, the piece needs another revision pass with the patterns called out. + +Detail in [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md). + +--- + +## SEO and AEO compliance check + +Does the piece serve search engines AND answer engines? + +SEO checks. + +- Target keyword in title, H1, first paragraph, slug +- Heading hierarchy clean (no orphan H3s, no H4 without H3) +- Image alt text descriptive +- Meta description compelling and keyword-aware +- Internal links specified in brief are present +- External links open in new tab (typically) and have rel attributes appropriate +- URL slug short and descriptive + +AEO checks. + +- 40 to 60 word answer paragraph immediately following each H2 question +- TL;DR section present (for pillar pieces) +- FAQ section with FAQPage schema (for pieces where Q and A format applies) +- Specific statistics with cited sources (AI engines weight statistics with sources) +- Named entities (experts, methods, tools) consistently mentioned (entity coverage signals) +- Distinctive POV that is attributable to the brand + +Detail in [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md). + +--- + +## Internal linking and schema validation + +Internal linking. + +- Outbound links specified in brief are present with correct anchor text +- Anchor text varies (avoid every link being "click here" or every link being the exact-match target keyword) +- Link targets are live (no 404s, no links to deprecated pages) +- Internal link count appropriate to length (3 to 7 for typical 1,500-word piece, 8 to 15 for pillars) +- Self-cannibalization check: piece does not compete with existing pieces for same target keyword + +Schema validation. + +- Article schema present on most pieces; HowTo schema on instructional pieces; FAQPage schema where Q and A applies +- Schema validates against schema.org definitions (no missing required fields, no malformed JSON-LD) +- Schema is consistent with on-page content (do not claim 5-star rating in schema if no rating on page) + +Detail in [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md). + +--- + +## QA at scale + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. Sampling discipline replaces it. + +Sampling strategy. + +- Random sample 50 to 200 pages per audit cycle +- Balance the sample across data shape (sparse versus dense records, recent versus old generation, popular versus niche categories) +- Fixed sample percentage as set grows; absolute count plateaus around 200 once the set is large + +Automated checks at scale. + +- Heading structure validation +- Schema markup validation +- Word count (flag pages below the floor, e.g. 600 words) +- Duplicate content check (compare each page against the rest of the set) +- Broken-link check +- Image-presence check (where templates expect images) + +Manual checks on sampled pages. + +- Brief-adherence equivalent (template-adherence check: does the page execute the template?) +- Top-200-word answer quality +- Whether the page would satisfy a human user's likely query +- Whether the page reads as distinctive versus templated +- Spot-check for AI hallucination if AI was in the loop + +Threshold gating. + +- If more than 5% of sampled pages fail the manual review, halt new generation +- Fix the template OR data quality issue before resuming +- Document the threshold breach in the QA log so patterns become visible + +Detail in [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md). + +--- + +## The QA workflow + +Ownership and sequencing. + +Single QA owner per piece, not a committee. The owner is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +Sequencing. Brief-adherence, then fact-accuracy, then structure, then AI-content audit, then voice, then SEO/AEO, then internal linking, then schema. Brief-adherence first because it is the cheapest gate; SEO/AEO checks last because they are easiest to fix and rarely halt-conditions. + +Halt vs flag vs auto-fix. + +- Brief-adherence and fact-accuracy can HALT (return to writer). +- Voice and structure FLAG with suggestions; editor judgment decides whether to halt or revise inline. +- SEO/AEO and schema typically auto-fix (slug, meta description, schema markup are mechanical edits the editor or a script can ship without writer involvement). + +Escalation. When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +Detail in [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-qa-failures.md`](references/common-qa-failures.md). + +- "Our QA process is a 47-item checklist nobody completes." Checkbox theater; cut to the checks that earned their keep. +- "We caught zero problems in QA last quarter." Either the process is broken or the writers are extraordinary; investigate. +- "Editor and writer disagree on voice." Voice guidelines are vague; document brand voice with concrete examples. +- "AI hallucinations made it to publish." Fact-accuracy gate skipped or rushed; reinstate as halt-condition. +- "Our pSEO set is shipping thin pages." Sampling discipline missing or thresholds not honored. +- "QA takes longer than the writing." Wrong sequencing; brief-adherence early catches problems before voice/structure investment. +- "Reviewers burn out." Checks that do not catch problems are taxing reviewer attention; cut them. +- "Voice drifts halfway through long pieces." Sample mid-piece paragraphs, not just open and close. +- "We never go back to evaluate." QA log archives feed pattern detection; quarterly review. +- "Different editors apply different standards." Calibration sessions where editors review the same piece independently and reconcile. +- "We ship and discover problems on social." QA was not catching the problem class that is reaching readers; add a check for that class. + +--- + +## The framework: 12 considerations for editorial QA + +When designing or auditing a QA process, walk these 12 considerations. + +1. Catch-problems vs checkbox. Every check earns its keep by catching a class of failure. +2. Brief-adherence first. Cheapest, fastest, highest-value gate. +3. Fact-accuracy as halt-condition. AI hallucinations do not ship to readers. +4. Voice consistency including mid-piece sampling. Long pieces drift; sample throughout. +5. AI-content audit. Pattern recognition for AI tells, hallucinations, voice drift. +6. Structure and clarity. Lede, sectioning, even-ish length, specific endings. +7. SEO and AEO compliance. Answer paragraphs, schema, entity coverage. +8. Internal linking and schema validation. Outbound links live, anchor text varies, schema validates. +9. Sampling at scale. Programmatic and high-volume sets need sampling, not full-audit. +10. Threshold gating. Failure rate above threshold halts generation; document breaches. +11. Single QA owner per piece. Accountability not diffused across committee. +12. Sequencing. Brief-adherence to fact-accuracy to structure to AI-audit to voice to SEO/AEO to linking to schema. + +The output of the framework is a QA process the team can run repeatably: each check named, each owner named, each halt-condition documented, each sampling rule specified for programmatic surfaces. + +--- + +## Reference files + +- [`references/brief-adherence-checklist.md`](references/brief-adherence-checklist.md) - Every brief field as a QA check, with how to verify and what failure looks like. +- [`references/voice-consistency-patterns.md`](references/voice-consistency-patterns.md) - Vocabulary, rhythm, stance, register, mid-piece sampling discipline for long pieces. +- [`references/fact-accuracy-and-citation-discipline.md`](references/fact-accuracy-and-citation-discipline.md) - Verification methodology, hallucination detection, citation rules, source-age guidelines. +- [`references/structure-and-clarity-review.md`](references/structure-and-clarity-review.md) - Lede patterns, sectioning principles, endings, structural anti-patterns. +- [`references/ai-content-audit-patterns.md`](references/ai-content-audit-patterns.md) - 11 AI tells, 6 hallucination patterns, voice drift detection, worked example with revision. +- [`references/seo-aeo-compliance-checklist.md`](references/seo-aeo-compliance-checklist.md) - SEO and AEO checks combined into one workflow. +- [`references/internal-linking-and-schema-validation.md`](references/internal-linking-and-schema-validation.md) - Link discipline, anchor text variation, schema patterns and validation. +- [`references/qa-at-scale-patterns.md`](references/qa-at-scale-patterns.md) - Sampling strategy, automated checks, manual review at scale, threshold gating. +- [`references/qa-workflow-templates.md`](references/qa-workflow-templates.md) - Ownership, sequencing, halt versus flag versus auto-fix, escalation patterns. +- [`references/common-qa-failures.md`](references/common-qa-failures.md) - 11+ failure patterns with diagnoses and fixes. + +--- + +## Closing: QA is where quality gets enforced + +Every other skill in the content suite produces drafts. QA is the discipline that turns drafts into publishable work. It is also where every previous decision (brief shape, voice guidelines, hub architecture, programmatic template) gets tested against actual output. Skipping QA is not "moving fast"; it is shipping the failure modes of every upstream decision unfiltered. + +The QA process is the immune system of the content program: invisible when it is working, catastrophic in its absence. + +When in doubt about whether a QA process is ready, ask: does each check name a class of failure it catches, has each check actually caught something in the last 6 months, is brief-adherence first in the sequence, is fact-accuracy a halt-condition, is the AI-content audit included, does sampling discipline apply to scaled surfaces? If yes to all of those, the process is real. If no to any, the gap is where readers will encounter the failure that QA did not catch. diff --git a/skills/editorial-qa/references/ai-content-audit-patterns.md b/skills/editorial-qa/references/ai-content-audit-patterns.md new file mode 100644 index 0000000..57337e9 --- /dev/null +++ b/skills/editorial-qa/references/ai-content-audit-patterns.md @@ -0,0 +1,119 @@ +# AI-content audit patterns + +The 11 AI tells, the 6 hallucination patterns, voice drift detection, a worked example. The QA check that did not exist as prominently 2 years ago and is now load-bearing for any program with AI in the loop. + +--- + +## The 11 AI tells + +Pattern recognition. Read with these top-of-mind; flag any match. + +1. Excessive em-dashes. Model-default punctuation. A piece with 8 em-dashes per 1,000 words is almost certainly AI-drafted. The fix: replace with periods, semicolons, or rephrase the sentence. + +2. Predictable opening phrasings. Throat-clearing openers that announce what the piece is about to do (the fast-paced-world opener, the importance-noting opener, the whether-you-are-X-or-Y opener). These openings appear in AI output across topics; pattern-match against the team's curated do-not-use list and cut. + +3. Predictable concluding paragraphs. Throat-clearing wrap-ups. "By following these steps." "By implementing these strategies." "Now you have a comprehensive understanding of." All cut. + +4. Bullet-list overuse. AI defaults to bullets when prose would serve. Bullets fragment reading flow and signal AI drafting. Convert to prose where prose makes the connection between items clearer. + +5. "On the other hand" / "However" overuse. Forced bilateral framing pattern. Used 4+ times in 1,500 words is the AI tell. + +6. Forced bilateral framing. "While X has its advantages, Y also has merits." Always two sides given equal weight even when one side is right. The fix: pick a position; defend it; let the contrary view get one short acknowledgment. + +7. Sentence-end filler. "...and more." "...among other things." "...for example." All padding. Cut. + +8. Repetitive sentence-rhythm. Every paragraph 2 or 3 sentences of similar length. Read aloud: monotonous. The fix: deliberate variation in sentence length and paragraph shape. + +9. Generic openings. Descriptive paragraphs that could open any article on the topic. "Customer experience is more important than ever in today's competitive landscape." Cut; replace with a specific opening tied to the piece's thesis or the reader's specific query. + +10. Bridging fluff. "That said." "With that in mind." "Moving on." Throat-clearing transitions; cut. + +11. Hedge stacking. "Typically," "generally," "often" stacked on claims that should be specific. AI hedges to avoid being wrong; the result is content that says nothing definite. Replace hedges with specifics or cut the hedge. + +--- + +## The 6 hallucination patterns + +Factual errors that AI assistants generate and how to detect each. + +1. Specific decimal places, named source, source does not exist. "According to a 2024 Forrester report, 67.3% of B2B buyers..." The decimal place plus named source is the AI tell. Detection: search the source. If it does not exist or does not say that, cut the claim. + +2. Quotes attributed to real people the person did not say. "As Marc Benioff said in his 2024 keynote..." Plausible because Benioff gives keynotes. Detection: search for the quote in actual transcripts; verify against original source. If the quote does not match a real source, cut. + +3. Case studies about companies that do not exist. "Acme Innovations reduced their cycle time 40% using..." Detection: search the company name. If it does not appear in business directories, news coverage, or LinkedIn, the case study is fake. + +4. Citations to URLs that 404 or never existed. Detection: click every external link. 404s and dead links are signals; multiple dead links signal multiple unverified claims. + +5. "Studies show" claims with no actual study. "Studies show that 45% of marketers..." with no link, no journal, no year. Detection: ask for the study. If the writer cannot produce it, cut the claim. + +6. Made-up product features. "Product X now supports automatic Y" when the product does not. Detection: verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Voice drift detection + +The mid-piece drift pattern in AI-co-authored content. + +The pattern. Piece starts in brand voice (because the writer set up the opening prompt with brand voice cues). By section 4, the voice has drifted to model-default. The drift is gradual; the start and end pass voice review while the middle fails. + +Detection methodology. + +1. Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. +2. Compare each sample to the brand voice doc's vocabulary, rhythm, stance, register. +3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. + +The fix. Send back with the drifted sections highlighted. Specific note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes from the voice doc]." + +--- + +## Worked example: AI tells in a 4-paragraph excerpt + +Original AI-drafted excerpt (with AI tells in bold for the audit): + +> In today's fast-paced digital landscape, content marketing has become more important than ever. Whether you're a small business owner or a Fortune 500 executive, understanding the nuances of effective content strategy is crucial for success. +> +> There are many factors to consider when developing a content strategy. On one hand, you need to focus on creating high-quality content that resonates with your audience. On the other hand, you also need to ensure that your content is optimized for search engines, social media platforms, and more. +> +> It's important to note that successful content marketing requires a balance between creativity and analytics. Studies show that companies that prioritize data-driven decision-making see significant improvements in their content performance metrics. +> +> By following these steps, you'll be well on your way to creating a content strategy that drives results. Remember that consistency is key, and that great content takes time to produce. + +The audit tags 9 AI tells in 4 paragraphs (more than 2 per paragraph). + +Revised excerpt (AI tells removed, voice tightened, specifics added): + +> Content marketing produces results when the strategy answers two questions: who are we writing for, and what do they need to do after reading. The B2B SaaS team writing for senior data engineers asks different questions than the consumer brand writing for first-time buyers. Both work; conflating them does not. +> +> The trade-off most teams get wrong is craft against measurement. Pieces optimized for search rankings often read as templated; pieces optimized for craft often miss the structural patterns that earn rankings. The fix is not balance; it is sequencing. Brief the structural patterns first; write to craft within them. +> +> Companies that ship measurable content programs share three patterns: a brief discipline that survives writer changes, a voice doc specific enough to enforce, and a fact-check gate that does not compromise under deadline pressure. Companies that miss any of the three produce inconsistent output regardless of writer talent. +> +> The next step is auditing your current process against those three patterns. If the brief is vague, fix the brief. If the voice doc is aspirational, tighten it with concrete examples. If the fact-check gate is optional, make it a halt-condition. + +The revision removed AI tells, added specifics (the two audience examples, the three patterns), and replaced the closing throat-clearing with a concrete next-step. + +--- + +## The audit checklist + +For each AI-co-authored draft, walk this checklist. + +1. Read the first 200 words. Does the opening match any of the 11 AI tells? Flag. +2. Sample 2 paragraphs from the middle. Does either match AI tells? Does the voice match the brand voice doc? Flag. +3. Read the last 200 words. Does the closing match any of the 11 AI tells? Flag. +4. Search the piece for em-dashes; count. More than 5 in a 1,500-word piece is suspicious. +5. Search for forced bilateral framing patterns. Count. +6. Verify every statistic, quote, case study, citation, and product claim per the fact-accuracy methodology. +7. Sample 3 to 5 internal links; verify they go where the brief specified and the targets exist. + +If 3+ items flag, halt the piece and return for revision with the specific items called out. + +--- + +## Methodology-level choices that stay in the public skill + +The 11 AI tells, the 6 hallucination patterns, voice drift detection methodology, the worked example revision pattern, the 7-step audit checklist. + +## Implementation choices that stay internal + +The specific tooling for automated AI-tell detection (regex patterns, classifier models, prompt-based audits). The specific brand voice doc that drives voice-drift comparison. The specific archive of past AI-tell catches that informs ongoing pattern recognition. The specific revision workflow when AI tells are detected (writer's editing tool, AI assistant configured for revision-not-drafting, human-only revision). These vary by team and tooling preferences. diff --git a/skills/editorial-qa/references/brief-adherence-checklist.md b/skills/editorial-qa/references/brief-adherence-checklist.md new file mode 100644 index 0000000..3f711e9 --- /dev/null +++ b/skills/editorial-qa/references/brief-adherence-checklist.md @@ -0,0 +1,137 @@ +# Brief adherence checklist + +Every brief field as a QA check, with how to verify and what failure looks like. + +The brief-adherence check is the first QA gate in sequence. It is the cheapest gate to run and the highest-value gate to pass: catching a brief-adherence failure early saves the editor from spending review time on voice, structure, and fact-accuracy on a piece that will need to restart. + +This check assumes the brief was authored under the discipline of `content-brief-authoring`. If briefs are vague or thin, fix briefs first; the brief-adherence check enforces a contract that has to exist. + +--- + +## The checklist + +For each piece, walk these 8 fields. + +### 1. Target keyword and cluster + +Verify. Pull the brief's primary keyword and 3 to 5 supporting cluster keywords. Search the piece for each. + +Pass. Primary keyword appears in title, H1 (if separate), first paragraph, and at least one H2. Supporting keywords appear naturally across the piece without stuffing. + +Fail patterns. + +- Primary keyword missing from title or first paragraph +- Cluster keywords absent (piece read like a generic article on the topic) +- Keyword stuffing: same exact-match phrase repeated 8+ times in 1,500 words + +### 2. Search intent and SERP format + +Verify. Pull the brief's intent classification and dominant SERP format. Compare to the piece's shape. + +Pass. Piece shape matches the format the brief specified: long-form article when SERP wants long-form, listicle when SERP wants listicle, comparison when SERP wants comparison. + +Fail patterns. + +- Brief specified listicle; piece is long-form prose +- Brief specified commercial-investigation intent; piece reads as informational with no purchase decision support +- Brief flagged the SERP intent override; piece ignored the override + +### 3. Target audience + +Verify. Read the first 200 words and the closing 200 words with the brief's audience description in mind. + +Pass. Piece reads as written FOR the named audience: vocabulary, examples, and assumed knowledge match the audience's level. + +Fail patterns. + +- Brief specified senior data engineers; piece explains "what is a database" in the introduction +- Brief specified non-technical CMOs; piece uses unexplained jargon +- Piece reads as written for a generic reader rather than the named audience + +### 4. Heading structure + +Verify. Compare the piece's H2 / H3 outline to the brief's specified outline. + +Pass. Piece follows the brief's outline. Where the writer deviated, the brief's deviation note explains why or the writer's first-draft note flags the deviation for editor review. + +Fail patterns. + +- Brief specified 6 H2s; piece has 4 or 9 with no documented reason +- H2 order changed without explanation +- Sections from the outline missing entirely + +### 5. Required entities + +Verify. Pull the brief's required-entity list. Search the piece for each. + +Pass. Every required entity appears in the piece, ideally in the section the brief specified. Standard entities are covered. Gap entities (the differentiation opportunity) are present where the brief committed to them. + +Fail patterns. + +- Brief required mentioning CUPED in the methodology section; CUPED is not in the piece +- Required entities mentioned in passing once each; depth-of-coverage requirements not met +- Gap entities skipped because they were "optional" (they were not; the brief committed to them) + +### 6. Internal links + +Verify. Pull the brief's outbound internal-link list with anchor text. Check the piece for each link. + +Pass. Every required outbound link is present with the specified anchor text. Optional outbound links are either present or noted as skipped with reason. + +Fail patterns. + +- Brief specified 4 required outbound links; piece has 2 +- Anchor text differs from the specified anchor text without reason +- Links to deprecated pages (the writer copied old anchor links from a stale draft) + +### 7. Anti-patterns + +Verify. Pull the brief's anti-pattern list. Read the piece looking for each pattern. + +Pass. Piece avoids every named anti-pattern. The do-not-use word list, off-brand voice, off-topic tangents, AI clichés, and structural patterns the brief explicitly forbade are absent. + +Fail patterns. + +- Anti-pattern words from the do-not-use list present (e.g., the writer slipped into corporate-speak adjectives) +- Off-topic tangents the brief warned against (the writer wandered into adjacent facets the cluster covers separately) +- Voice drifted toward a register the brief excluded + +### 8. Success criteria acknowledged + +Verify. Read the piece with the brief's success criteria in mind. Does the piece's shape support the criteria? + +Pass. Piece is shaped to MEASURE against the success criteria: ranking-targeted pieces have keyword-aware structure, citation-targeted pieces have answer paragraphs and statistics, conversion-targeted pieces have CTAs and decision-support content. + +Fail patterns. + +- Brief said "rank top 10 for [keyword]"; piece misses the structural patterns that earn ranking (no answer paragraphs, no entity coverage, no internal-link plan) +- Brief said "drive 50 trial signups in 30 days"; piece has no clear CTA path to signup +- Success criteria treated as an afterthought rather than a design parameter + +--- + +## What halt-condition looks like + +Brief-adherence failures are halt-conditions: return the piece to the writer with the specific failures named. + +The return note is short. "This piece misses the brief in 3 places: [field 1], [field 2], [field 3]. The brief specified [X]; the piece does [Y]. Please revise and return for round 2." + +Editors who try to fix brief-adherence failures themselves end up rewriting the piece. Better to halt cleanly, return to the writer, and let the writer execute the contract that already existed in the brief. + +--- + +## When briefs are too vague to enforce + +Sometimes the brief itself is the problem. The brief specified "engineers" without naming the seniority level. The brief specified "informational intent" without checking the SERP. The brief specified entities without depth-of-coverage requirements. + +When the brief is too vague, brief-adherence cannot enforce anything. The fix is upstream: tighten brief authoring discipline (see `content-brief-authoring`). The brief is the contract; vague contracts produce vague output regardless of writer skill. + +--- + +## Methodology-level choices that stay in the public skill + +The 8-field checklist, the halt-condition discipline, the upstream-fix observation when briefs are vague. + +## Implementation choices that stay internal + +The specific format the team uses for return notes (Slack message template, Notion row, ticketing system field structure). The specific tooling that stores brief metadata for diff-checking against pieces. The specific automation (if any) that surfaces brief-adherence failures before manual review. These vary by team and stack. diff --git a/skills/editorial-qa/references/common-qa-failures.md b/skills/editorial-qa/references/common-qa-failures.md new file mode 100644 index 0000000..9f97eac --- /dev/null +++ b/skills/editorial-qa/references/common-qa-failures.md @@ -0,0 +1,168 @@ +# Common QA failures + +11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: QA either drifted into theater (checks that do not catch problems but cost reviewer attention) or skipped the gates that catch the problems readers actually encounter. The fix is upstream: cut theater checks, reinstate gates that actually catch problems. + +--- + +## "Our QA process is a 47-item checklist nobody completes" + +Symptom. The checklist exists. Nobody completes it honestly. Reviewers either skim and check boxes or burn out under the cognitive load. + +Diagnosis. Checkbox theater. The checklist accumulated over time as new failures appeared and got added; nothing was ever removed. The list grew past what reviewer attention can sustain. + +Fix. Audit the checklist. For each item, ask: when did this last catch a problem? If the answer is "never" or "more than 6 months ago," cut it. The remaining items are the catch-problems checks; the cut items were theater. + +Prevention. Quarterly review of the checklist. Each new check earns its keep by catching at least one problem within 90 days; checks that do not catch problems get cut. + +--- + +## "We caught zero problems in QA last quarter" + +Symptom. No QA returns. No halt-conditions. No revision rounds. Pieces ship clean every time. + +Diagnosis. Either the writers are extraordinary or the process is broken. Almost always the latter. + +Fix. Audit recently-shipped pieces independently of the original QA. Find the problems QA missed: hallucinated statistics, voice drift in long pieces, broken links, schema validation failures. Document each. Reinstate the QA gate that should have caught the failure. + +The pattern. When QA catches nothing for a quarter, reviewers have stopped reading carefully. The fix is not "trust the writers"; it is reinstating the discipline that was nominally still running. + +--- + +## "Editor and writer disagree on voice" + +Symptom. Editor returns the piece with voice notes; writer pushes back; edits go back and forth without convergence. + +Diagnosis. Voice guidelines are vague. Both editor and writer are interpreting the brand voice doc differently because the doc does not specify enough. + +Fix. Update the voice doc with concrete examples of the disputed dimension. If the dispute was about sentence rhythm, add 5 paired examples (the rhythm we want, the rhythm we do not want). The voice doc gets sharper; future disputes resolve by reference to the examples. + +Prevention. Quarterly voice calibration sessions (see `voice-consistency-patterns.md`) where editors review the same piece independently and reconcile. + +--- + +## "AI hallucinations made it to publish" + +Symptom. A statistic, quote, citation, or product claim in a published piece turns out to be invented. Reader (or competitor) flags it. + +Diagnosis. The fact-accuracy gate was skipped or rushed. + +Fix. Two parts. + +- Immediate: correct the published piece, document the failure in the QA log. +- Process: reinstate fact-accuracy as a halt-condition. AI hallucinations do not progress past this gate. If the gate is too slow, automate the easy parts (named-entity extraction, statistic detection) so manual verification focuses on the hard parts. + +Prevention. Fact-accuracy gate runs second in the QA sequence (after brief-adherence). Detail in `fact-accuracy-and-citation-discipline.md`. + +--- + +## "Our pSEO set is shipping thin pages" + +Symptom. Programmatic pSEO set is producing pages with insufficient data; pages render at 200 to 400 words of templated boilerplate; algorithm risk compounds. + +Diagnosis. Sampling discipline missing or thresholds not honored. The set was generating pages without QC checking the quality at the data-shape level. + +Fix. Implement the sampling discipline (see `qa-at-scale-patterns.md`). Set the 5% failure threshold; halt new generation when breached. Audit the existing set; noindex or remove pages below the data depth threshold. + +Prevention. Sampling and threshold gating built into the program at design time, not retrofitted. + +--- + +## "QA takes longer than the writing" + +Symptom. The team's writers ship drafts in 4 hours; QA cycle takes 6 hours. The bottleneck is review. + +Diagnosis. Wrong sequencing. The team is running expensive checks (voice, structure) before cheap checks (brief-adherence, fact-accuracy). When a piece fails at gate 1, the time spent on gates 5 to 8 is wasted. + +Fix. Reorder the sequence. Brief-adherence first; fact-accuracy second; halt-conditions short-circuit the rest of the gates. Voice and SEO checks last because they are easiest to fix and rarely halt-conditions. + +Prevention. The sequencing discipline is documented in `qa-workflow-templates.md`; new editors get the sequence in their onboarding. + +--- + +## "Reviewers burn out" + +Symptom. Editors who used to review carefully now skim. The catch rate drops. Editors leave the team. + +Diagnosis. The QA load exceeds reviewer capacity. Often because checks that do not catch problems are taxing reviewer attention. + +Fix. Cut theater checks (the same fix as the 47-item checklist failure). Burn-out reduces with the cognitive load. + +Also. Verify that production volume matches reviewer capacity. If the team is shipping 30 pieces a week with 1 editor, the volume is wrong. Either reduce volume, add reviewers, or accept lower quality with eyes open. + +--- + +## "Voice drifts halfway through long pieces" + +Symptom. 3,000-word pillar pieces start in brand voice; by section 4 they read generic. + +Diagnosis. Voice review only sampled the start and end. Mid-piece drift went undetected. + +Fix. Mid-piece sampling discipline (see `voice-consistency-patterns.md`). Sample paragraphs from start, middle (2 paragraphs from middle 60%), and end. AI-co-authored pieces especially need this. + +Prevention. Voice review template explicitly requires mid-piece sampling. + +--- + +## "We never go back to evaluate" + +Symptom. QA process exists. QA log accumulates. Nobody reviews the log. + +Diagnosis. The log is an artifact, not a feedback mechanism. Patterns the log surfaces never reach the editorial process owner. + +Fix. Quarterly QA log review. The owner reads the log; pattern observations get translated into process changes (brief tweaks, writer feedback, workflow adjustments, automation additions). + +Prevention. The quarterly review is calendar-anchored. Skipping it is the failure mode. + +--- + +## "Different editors apply different standards" + +Symptom. A piece shipped under editor A would be returned under editor B (or vice versa). Writers receive inconsistent feedback. Quality varies by which editor caught the piece. + +Diagnosis. Voice and structural standards have drifted between editors. Without calibration, individual editors apply individual taste. + +Fix. Calibration sessions. Three editors review the same piece independently; the team reads the three assessments together and reconciles. The consensus updates the voice doc and the QA process; future reviews stay consistent. + +Prevention. Calibration sessions quarterly minimum. Onboarding new editors includes a calibration round before they review live pieces solo. + +--- + +## "We ship and discover problems on social" + +Symptom. Readers (or competitors, or critics on social) flag problems that QA did not catch. + +Diagnosis. QA was not catching the problem class that is reaching readers. The class might be hallucinations, voice drift, structural problems, factual errors, or off-brand tone. + +Fix. Identify the class of failure that reached readers. Add a QA check that catches that class. Document the addition in the QA log so the pattern becomes visible. + +Prevention. The QA process evolves with feedback from shipped pieces. New failure classes that reach readers feed new QA checks. + +--- + +## "AI tells slipped through" + +Symptom. Published piece reads as AI-generated despite a human editor reviewing it. Readers or AI-detection tools flag it. + +Diagnosis. The AI-content audit either was not run or ran without the pattern recognition the editor needed. + +Fix. Add the AI-content audit as a named gate in the QA sequence (see `ai-content-audit-patterns.md`). Train the editor on the 11 AI tells; provide the worked example as reference. The audit becomes a 5-minute discipline rather than an unstructured "does this read OK" check. + +Prevention. Every AI-co-authored piece runs through the audit. The audit is a named gate, not an implicit step. + +--- + +## The pattern across most failures + +Most QA failures are designed-in. The process either drifted into theater (cuts needed) or skipped gates that should have been there (gates needed). The discipline is upstream: design the QA process around catch-problems, not around process appearance, and the operational discipline at scale becomes manageable. + +--- + +## Methodology-level choices that stay in the public skill + +The 12 failure patterns above, the diagnosis-and-fix structure, the prevention guidance, the upstream-discipline observation. + +## Implementation choices that stay internal + +The specific QA log format and tooling. The specific calibration session cadence and team composition. The specific automation that supports each gate (statistic detection, hallucination flagging, schema validation, link audit). The specific escalation pathways within the team's structure. These vary by team and tooling. diff --git a/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md b/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md new file mode 100644 index 0000000..17d8d83 --- /dev/null +++ b/skills/editorial-qa/references/fact-accuracy-and-citation-discipline.md @@ -0,0 +1,113 @@ +# Fact accuracy and citation discipline + +Verification methodology, hallucination detection, citation rules, source-age guidelines. + +Fact accuracy is a halt-condition QA gate. Hallucinations from AI-assisted writing reach readers if the gate is skipped or rushed. The discipline below is what makes the gate work at production speed without becoming the bottleneck. + +--- + +## What gets fact-checked + +Every claim that could be wrong. The categories. + +Statistics. Every number in the piece needs a source. "23% of feature flag rollouts include a kill switch" needs a source link to the survey, report, or dataset that produced the 23%. Without a source, the number is either removed or replaced with sourced equivalent. + +Quotes. Every quote attributed to a real person needs verification: the person said it, the quote is verbatim or correctly paraphrased, the attribution is accurate, the person consents to attribution. + +Case studies. Every example refers to a real company or scenario, OR is labeled clearly as hypothetical. "Acme Corp reduced churn by 40% using this method" needs verification that Acme exists, the method was used, the 40% is real. If the example is hypothetical, the piece labels it: "Imagine a SaaS company..." + +Dates and timelines. Verified, not approximate. "Google launched feature X in March 2025" needs verification of the exact month and year. + +Named experts. Real people who consented to being attributed. The piece should not attribute claims to "Ronny Kohavi" without verifying the attribution traces to actual published work or direct consent. + +Product claims. Match actual product behavior. The product does what the piece says it does, in the way the piece says it does, today, in production. Future-tense roadmap items get clearly labeled as roadmap; marketing aspirations get cut. + +--- + +## The verification methodology + +For each claim in the piece, the editor follows one of three paths. + +Path 1: in-line citation present. Click through the citation. Does the source exist? Does the source actually say the claimed thing? Is the source the original (not a citation-of-citation)? + +Path 2: claim has no citation but is a known fact. Editor verifies via authoritative source (academic paper, primary government data, official company announcement). Add the citation; do not let the piece ship with uncited claims. + +Path 3: claim has no citation and is not a known fact. Halt. Return to writer with the claim flagged. Either the writer adds verification, or the claim gets removed. + +The discipline. No claim ships without verification. "I'm pretty sure I read this somewhere" is not verification. + +--- + +## Hallucination detection + +AI-assisted writing produces plausible-but-fake claims at scale. The patterns to recognize. + +Pattern 1: specific decimal places, named source, source does not exist. "According to a 2024 Forrester report, 67.3% of B2B buyers prefer..." Sounds authoritative. The Forrester report does not exist, or exists but does not say that. The decimal place is the AI tell; AI assistants generate false precision to sound credible. + +Pattern 2: quotes attributed to real people the person did not say. "As Marc Benioff said in his keynote..." Plausible because Benioff gives keynotes. The specific quote is fabricated. Verify quotes against the actual recording, transcript, or primary source. + +Pattern 3: case studies about companies that do not exist. "Acme Innovations reduced their cycle time 40% using..." The company does not appear in any business directory; the case study is invented. Search the company name; if it does not surface in legitimate sources, the case study is fake. + +Pattern 4: citations to URLs that 404 or never existed. Click every external link. 404s and dead links are signals; a piece with multiple dead links has multiple unverified claims. + +Pattern 5: "Studies show" claims with no actual study. "Studies show that..." with no link, no journal, no year. Either the writer provides the study or the claim gets cut. + +Pattern 6: made-up product features. "[Product] now supports automatic X" when the product does not. Verify against the product's current documentation, not against marketing copy that might be aspirational. + +--- + +## Citation discipline + +When citations are present, they need to be the right kind. + +Authoritative sources. + +- Academic papers (peer-reviewed journals) +- Industry reports from established research firms (Forrester, Gartner, McKinsey, IDC) when verified +- Primary government data (BLS, Census, SEC filings) +- Original company announcements (the company's own blog, press release, official documentation) +- First-party data the brand owns and has published + +Avoid citation laundering. + +Citing another content marketing page that itself cites a primary source is laundering. The chain of attribution gets murky; the claim's accuracy degrades through each hop. Cite the primary source directly. + +Date the source. + +Sources older than 3 years for fast-moving topics need refresh. "According to a 2018 Gartner report" is a yellow flag for content about a 2026 topic; the data might still be true but probably is not. Either find a more recent source or note the date and explain why the older source still applies. + +--- + +## When the writer disputes the fact-check + +Sometimes the editor flags a claim and the writer pushes back. "I read it in the original source; here's the link." Two outcomes. + +Outcome 1: writer's source verifies the claim. Add the citation; ship the piece. The QA process worked. + +Outcome 2: writer's source does not verify the claim. This is where the conversation gets uncomfortable. The writer thought they had a source; the source does not say what they thought. The fix is the same: cut the claim or find a verifying source. Do not ship the unverified claim because the writer is sure it is true. + +--- + +## Fact-check log + +Maintain a log of fact-check failures across pieces. Patterns surface over time. + +Log fields. Piece, claim, failure type (hallucination / wrong citation / outdated source / unverifiable), writer (if naming patterns), resolution (cut / re-sourced / verified). + +Patterns the log surfaces. + +- One writer repeatedly produces hallucinations: writer needs feedback or different work +- One topic area produces frequent hallucinations: that topic needs more verification time built in +- AI-co-authored pieces fail at higher rates than human-authored: AI workflow needs additional guardrails + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The verification methodology, the 6 hallucination patterns, the citation discipline rules, the fact-check log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing the fact-check log (spreadsheet, database, Notion). The specific automation (if any) for surfacing claims that need verification (named-entity extractors, statistic detectors). The specific verification workflow when the editor does not have the bandwidth to fact-check personally (assistant-powered verification, fact-checking service integration). These vary by team scale and tooling preferences. diff --git a/skills/editorial-qa/references/internal-linking-and-schema-validation.md b/skills/editorial-qa/references/internal-linking-and-schema-validation.md new file mode 100644 index 0000000..bce4dd4 --- /dev/null +++ b/skills/editorial-qa/references/internal-linking-and-schema-validation.md @@ -0,0 +1,125 @@ +# Internal linking and schema validation + +Link discipline, anchor text variation, schema patterns and validation. + +The internal-linking and schema layer is where SEO compounds. Each piece's link contribution and schema contribution feeds the program's overall ranking and citation signal. QA enforces the discipline so individual pieces do not drift from the program's link graph and schema standards. + +--- + +## Internal linking + +### Outbound links specified in brief + +- The brief named X outbound links. Verify each is present in the piece. +- Anchor text matches the brief's specification. "Click here" is dead anchor text; the brief should specify keyword-aware anchor text per link. +- Links go where the brief said. The link target is the page the brief specified, not a deprecated alternate or a different page that happens to share the topic. + +### Anchor text variation + +The "every link has the same anchor text" anti-pattern. + +Pattern. A piece links to the pillar 3 times. All 3 links use the exact-match keyword as anchor. This signals manipulation to ranking systems and dilutes the anchor's signal. + +Fix. Vary the anchor across the 3 links. One uses the exact-match keyword; one uses a descriptive natural-language phrase; one uses a brand-mention anchor or a context-driven phrase. + +The audit. For each piece, count the outbound links to the same target. If multiple links to the same target use identical anchor text, vary at least one. + +### Link-target liveness + +- Every internal link target exists. No 404s. The link goes to a live page on the site. +- No links to deprecated pages. If a target page was retired, the link should redirect (via 301) or the link itself should be replaced. +- External links work. Click them; verify they resolve and lead to the intended source. + +The external-link audit catches hallucinated citations (see `fact-accuracy-and-citation-discipline.md`) and link rot. + +### Internal link count + +- 3 to 7 internal links for a typical 1,500-word piece. Below 3 signals under-linked (orphan-shaped). Above 10 signals link-stuffing. +- 8 to 15 for a pillar piece. Pillars carry more outbound links to their cluster. +- The link count should be by design, not by accident. The brief specifies the link count; the writer should hit it; QA verifies. + +### Self-cannibalization check + +- The piece does not compete with an existing piece for the same target keyword. Search the site for the primary keyword. If an existing piece is in the top 5 internal results, flag the new piece. + +The flag triggers a decision: consolidate, differentiate, or kill one. Detail in `pillar-content-architecture/references/internal-linking-architecture.md` for the broader internal linking discipline. + +--- + +## Schema validation + +### Schema type matches content + +- Article schema for editorial pieces. Default for blog posts, long-form articles, thought leadership. +- HowTo schema for instructional pieces. Step-by-step guides with explicit steps that the schema can structure. +- Product schema for product pages. Programmatic pSEO pages rendering products usually use Product schema. +- LocalBusiness schema for location-based pages. Programmatic pSEO for geographic categories. +- FAQPage schema for genuine FAQ sections. As an embedded schema within the page, not as the page's primary schema (unless the page is FAQ-shaped throughout). +- BreadcrumbList schema for navigation context. Most pages benefit; pillar pages especially. + +### Schema validates + +- Schema validates against schema.org definitions. No missing required fields. No malformed JSON-LD. No invalid field types. +- Validation method. Run the schema through a validator (Google's Structured Data Testing Tool, schema.org's validator, or equivalent). Failures appear as errors with field-specific messages. + +### Schema is consistent with on-page content + +- Schema reflects what the page actually shows. Do not claim 5-star rating in schema if there is no rating on the page. Do not claim a HowTo with 7 steps if the page only walks through 4. Mismatch between schema and content can trigger manual penalties. + +### Optional schema fields earn their keep + +- Populated optional schema fields signal depth. Programmatic pages with comprehensive schema (`aggregateRating`, `additionalProperty`, `areaServed`, etc.) score higher with AI engines than pages with bare-minimum schema. +- The trade-off. Filling optional fields requires data. If the data does not exist, do not fabricate it; either populate genuinely or leave the field absent. + +--- + +## The link audit pattern + +For each piece in QA: + +1. Outbound links present. Match against brief. +2. Anchor text variation. Same-target links use varied anchor text. +3. Targets live. No 404s, no deprecated pages. +4. Link count in band. 3 to 7 for typical, 8 to 15 for pillar. +5. Self-cannibalization. No competition with existing pieces. +6. Inbound links queued for post-publish update. The brief queued 1 to 3 existing pages that should add links to this piece after publish; the QA log queues those updates. + +The 6-step audit takes 5 minutes per piece. Worth the time; under-linked or stuffed pieces fail to compound. + +--- + +## The schema audit pattern + +For each piece in QA: + +1. Schema type appropriate. Article, HowTo, Product, LocalBusiness, FAQPage, or BreadcrumbList per content shape. +2. Schema validates. Run through a validator; resolve errors before publish. +3. Schema matches content. No false claims (false ratings, false step counts). +4. Optional fields populated. Where data exists, fields populate; the page signals depth. +5. Multiple schema types when appropriate. Article + FAQPage + BreadcrumbList is common for pillar pieces with FAQ sections. + +The schema audit takes 3 to 5 minutes per piece (less with automation; more on first-pass for new content types). + +--- + +## Common failures + +Brief specified link, writer skipped it. Halt and return; brief-adherence catches this earlier in the QA sequence. + +Anchor text identical across links. Auto-fix in the editor pass; vary the anchor on at least 2 of every 3 same-target links. + +Schema fails validation. Auto-fix; the editor or a script ships the corrected schema. + +Schema claims rating that is not on the page. Halt and return; this is the manual-penalty risk. + +Internal link count below brief. Flag and return for the writer to add the missing links per the brief's specification. + +--- + +## Methodology-level choices that stay in the public skill + +The 6-step link audit, the 5-step schema audit, the anchor variation rule, the schema-content consistency rule, the optional-field discipline. + +## Implementation choices that stay internal + +The specific schema validation tooling (Google's tool, schema.org's tool, custom CI integration). The specific link checker (Screaming Frog, custom Puppeteer script, headless browser audit). The specific CMS integration that auto-populates schema from page metadata. The specific deployment pipeline that runs schema validation on every publish. These vary by stack and team. diff --git a/skills/editorial-qa/references/qa-at-scale-patterns.md b/skills/editorial-qa/references/qa-at-scale-patterns.md new file mode 100644 index 0000000..cd443d8 --- /dev/null +++ b/skills/editorial-qa/references/qa-at-scale-patterns.md @@ -0,0 +1,184 @@ +# QA at scale patterns + +Sampling strategy, automated checks, manual review at scale, threshold gating. + +For pieces shipping at programmatic-SEO scale (100s to 100,000s of pages), full-audit QA is infeasible. The discipline below is sampling plus automated checks plus threshold gating. It is the same shape as the QA section in `programmatic-seo` but applied to the editorial QA gate specifically. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle. The sample is stratified. + +Stratification dimensions. + +- Sparse vs dense data. Sample some records with minimum-required fields; sample some with most-fields-populated. Sparse pages fail differently from dense pages; the sample needs both. +- Recent vs old. Sample some pages generated in the last 30 days; sample some generated 12+ months ago. Recent pages catch template drift; old pages catch data drift. +- Popular vs niche categories. Sample some pages from high-traffic parent categories; sample some from low-traffic ones. The popular categories carry the program's traffic; the niche ones surface long-tail-specific failures. +- Different cohort versions. If the template has shipped revisions, sample some pages from each cohort. Cohort-specific failures only surface if the sample includes the cohort. + +Sample size by set size. + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +Cycle frequency. Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks at scale + +Run on every page on a cadence; surface failures as a queue. + +### Heading-structure validation + +- One H1 per page, in the right place +- H2 sequence reasonable (not orphan H3s, not H4 without H3) +- Heading text length within bounds (no 200-character H2s) + +### Schema markup validation + +- Schema type present and matches the page's content type +- Required fields populated +- JSON-LD parses without errors +- Schema does not claim things absent from the page + +### Word count + +- Pages below the floor (typically 600 words for editorial; varies for programmatic templates) get flagged +- Pages above an upper bound (typically 8,000+ words on programmatic templates) get flagged for review + +### Duplicate content + +- Hash-similarity comparison across the set +- Pages with >80% content overlap with another page in the set get flagged +- Common cause: comparison-pivot pages (X vs Y inverse) without canonicalization + +### Broken links + +- Crawl outbound and internal links +- 404s and 5xx responses get flagged +- Both internal links to deleted pages and external links to dead URLs surface + +### Image presence + +- Pages where the template expects images but the image slot is empty +- Programmatic pages with missing image fields render visibly broken + +--- + +## Manual checks on sampled pages + +For sampled pages, the human review covers what automation misses. + +### Brief or template adherence + +- For editorial pages: did the writer execute the brief? +- For programmatic pages: did the page execute the template? + +### Top-200-word answer quality + +- Read the first 200 words. Does the page answer the user's likely query? +- Is the answer self-contained (could be cited as the canonical answer to the query)? + +### Distinctive vs templated + +- Compare the sampled page to two siblings in the same template cohort. Could you tell them apart on substance, not just on identifiers? +- Templated pages that look identical signal weak data depth or weak template variable density. + +### User-intent satisfaction + +- If a real user landed on this page from the target SERP, would they stay or bounce? +- The bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +### AI hallucination spot-check + +- For pages that involved AI in drafting or generation, spot-check 3 to 5 statistics, citations, or factual claims per sampled page. +- Hallucination patterns surface in patterns; one bad page often signals a template-level or pipeline-level issue. + +### AI-tell pattern check + +- Sample a paragraph from the middle of the sampled page. +- Does it match the AI tells from `ai-content-audit-patterns.md`? +- Mid-page drift in programmatic pages signals the generation pipeline's output drifted; investigate. + +--- + +## Threshold gating + +If more than 5% of sampled pages fail the manual review, halt new generation. Fix the template OR data quality issue before resuming. + +The 5% threshold is empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +What "halt" means. + +- New page generation stops. +- The template or data fix is shipped. +- The next sample audit confirms the fix improved the failure rate before generation resumes. + +Why halt instead of "fix as you go." Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +The threshold is not negotiable. "Just ship the next batch and we will fix later" is the failure mode. The pattern produces sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another. That signals a template change or data quality drift; investigate. + +Cohort cuts. + +- Pages from a given month +- Pages from a given template version +- Pages from a given data-source version + +Drift signals. + +- Cohort A pages rank top 10; cohort B pages rank position 30. Template or data changed between cohorts; identify the change. +- Cohort A pages get cited; cohort B pages do not. Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- Cohort A pages have stable engagement; cohort B pages have decaying engagement. Cohort B may have a data freshness problem. + +Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically. + +--- + +## QA log + +Document each cycle's audit. The log compounds into pattern detection. + +Log fields. Cycle date, sample size, failure count, failure types, cohort distribution, threshold breach if any, halt action if triggered, fix shipped if applicable. + +The patterns the log surfaces over time. + +- Recurrent failure types (always the answer paragraph; always the schema; always the data freshness) +- Cohort-specific patterns (cohort B always fails harder than cohort A) +- Template versions that solved one problem and introduced another +- Data sources that drift faster than expected + +The log is process improvement input. Quarterly review; act on patterns. + +--- + +## When the sample reveals the program is broken + +Sometimes QC at scale reveals the underlying program is wrong, not just that individual pages need fixes. + +Signals. + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole there; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. + +--- + +## Methodology-level choices that stay in the public skill + +The stratified sampling strategy, the 5% threshold, the automated check categories, the manual review checklist, the cohort tracking discipline, the QA log methodology. + +## Implementation choices that stay internal + +The specific tooling for storing and querying the QA log (database table, Notion, dbt model, BI tool). The specific automated check pipeline (CI integration, scheduled crawls, data warehouse queries). The specific sampling implementation (random ID selection script, weighted sampling logic). The specific dashboard or visualization for surfacing cohort patterns. These vary per team scale and tooling. diff --git a/skills/editorial-qa/references/qa-workflow-templates.md b/skills/editorial-qa/references/qa-workflow-templates.md new file mode 100644 index 0000000..ad175af --- /dev/null +++ b/skills/editorial-qa/references/qa-workflow-templates.md @@ -0,0 +1,153 @@ +# QA workflow templates + +Ownership, sequencing, halt vs flag vs auto-fix, escalation patterns. + +The QA workflow is the operational shape of how QA actually runs. Templates below name the patterns; teams adapt the implementation to their own tooling. + +--- + +## Ownership: single QA owner per piece + +The principle. One person is accountable for what shipped. Committees diffuse accountability; nobody owns a problem that reaches readers. + +Common ownership models. + +- Editor-owns-piece. The editor who reviews the piece is also accountable for what shipped. The same person sees the brief, reads the draft, runs QA checks, ships. +- Editor + dedicated QA. Editor reviews voice and structure; dedicated QA runs fact-checks, link audits, schema validation. The editor is still the single point of accountability for ship-decision. +- Rotating editor pool. Larger teams have multiple editors; each piece gets one named owner from the pool. The pool is calibrated quarterly so individual editors apply consistent standards. + +Anti-pattern. Committee review where 4 reviewers comment, nobody decides, the writer revises against contradictory feedback. The fix: name the decision-maker; treat other input as advisory. + +--- + +## The sequencing template + +Run QA gates in this order. Each gate is cheaper than the next; running them in order saves the editor's time on pieces that should restart. + +1. Brief-adherence. First. Cheapest to run. Catches the largest class of failures. +2. Fact-accuracy. Second. Halt-condition; AI hallucinations do not progress past this gate. +3. Structure and clarity. Third. Identifies pieces that need structural revision before voice and SEO checks make sense. +4. AI-content audit. Fourth. Catches AI tells, hallucinations not caught at gate 2, voice drift. +5. Voice consistency. Fifth. Mid-piece sampling for long pieces. +6. SEO and AEO compliance. Sixth. Most failures here are auto-fixable; rarely halt-conditions. +7. Internal linking and schema validation. Seventh. Mostly auto-fix or flag. +8. Final read. The last full read before publish. Catches anything the gate-by-gate review missed. + +The early gates (brief, fact, structure) save the most time; running them first means a piece that fails brief-adherence does not consume voice/SEO review time. + +--- + +## Halt vs flag vs auto-fix taxonomy + +Each QA gate has a default action when failures appear. + +Halt-conditions (return to writer). + +- Brief-adherence failures. The contract was not executed. +- Fact-accuracy failures (hallucinations, unverifiable claims). Cannot ship false claims. +- Structural failures that require rewriting (buried lede, mismatched intent, missing facets). Cannot fix in editor pass. +- Voice drift that requires rewriting sections. Cannot fix inline. + +Flag-and-revise (editor flags; writer or editor revises). + +- Voice consistency issues that are correctable inline. +- Structural issues that need paragraph-level revision (sentence variety, transition smoothing). +- AI tells that need targeted rewriting. +- Specificity gaps where the writer needs to add the missing concrete claim. + +Auto-fix (editor or script ships the correction without writer involvement). + +- Slug, meta description, image alt text. +- Schema markup formatting issues. +- Anchor text variation when same-target links share identical anchors. +- Heading structure mechanical fixes (closing orphan H3s). +- Typos and minor grammar. + +The discipline. Most pieces have a mix: some auto-fix items, some flag-and-revise items, sometimes a halt-condition. The editor processes them in the right order: handle auto-fixes inline, batch flag-and-revise items into one return note, halt early if a halt-condition appears. + +--- + +## Escalation patterns + +When QA finds a pattern (multiple pieces failing the same check), escalate to the brief author, the writer, or the editorial process owner. Pattern signals process problem, not just per-piece problem. + +### Brief-level patterns + +- Multiple writers fail brief-adherence on the same brief field. The brief is unclear about that field; tighten the brief template. +- Multiple briefs surface the same gap (always missing the audience specification, always missing the success criteria). The brief authoring process needs feedback. + +### Writer-level patterns + +- One writer repeatedly produces pieces that fail at the same gate. The writer needs targeted feedback or different work. +- One writer's pieces consistently need substantial revision. Either the briefs the writer receives need to be tighter, or the writer-fit is wrong for the work. + +### Process-level patterns + +- AI-content audit catches similar tells across pieces. The AI workflow needs additional guardrails. +- Fact-accuracy gates catch repeated hallucinations on the same topic. The verification step for that topic needs more time. +- Schema validation fails consistently on the same content type. The CMS template for that type needs updating. + +The escalation. Pattern goes to the editorial process owner with a short summary: "Across the last 12 pieces, 5 failed at [gate] for [reason]. Recommend [action]." The owner decides whether to update the brief template, retrain a writer, change the workflow, or document the pattern as known and accepted. + +--- + +## QA review templates + +Common formats for capturing QA findings. + +### Halt-condition return note + +Short. The note specifies what failed and what needs to change. + +> "This piece needs revision before round 2. Three failures: [field 1] missing the brief specification of [X], [field 2] contains an unverified statistic on line [N], [field 3] reads as model-default voice in section 4. Revise per the brief and the voice doc." + +### Flag-and-revise inline review + +Inline comments in the editing tool. Each comment is short and actionable. + +- "[Brief required] Add internal link to [X] with anchor '[Y]' here." +- "[Voice drift] This paragraph reads generic; pull back to brand voice." +- "[Specificity] 'Many companies' is vague; add the source or remove the claim." + +### Auto-fix log entry + +The editor logs what was auto-fixed for the writer's awareness without requiring writer action. + +> "Auto-fixed during review: meta description tightened, schema markup field [X] added, anchor text varied on 2 links to [target]. No writer action required." + +### Escalation note + +Short summary to the editorial process owner. + +> "Pattern: 5 of 12 recent pieces have failed AI-content audit on em-dash count. The writer using AI assistance is shipping mid-stage drafts without final em-dash cleanup. Recommend a final-pass revision guideline added to the AI-co-author workflow doc." + +--- + +## QA cycle time + +The discipline keeps QA cycle time tractable. + +Typical times for a 1,500-word piece. + +- Brief-adherence: 5 minutes +- Fact-accuracy: 10 to 30 minutes (depending on claim density) +- Structure and clarity: 10 minutes +- AI-content audit: 5 minutes +- Voice consistency: 5 minutes +- SEO and AEO compliance: 10 minutes +- Internal linking and schema: 5 minutes +- Final read: 5 minutes + +Total. 55 to 75 minutes for a healthy piece. Pieces that halt at gate 1 or gate 2 take less editor time because the early gates short-circuit the rest. + +The "QA takes longer than the writing" failure. Usually means the wrong sequencing (running expensive checks before cheap ones). Fix the sequence; the cycle time drops. + +--- + +## Methodology-level choices that stay in the public skill + +The single-owner principle, the gate sequencing, the halt/flag/auto-fix taxonomy, the escalation patterns, the review templates, the cycle-time targets. + +## Implementation choices that stay internal + +The specific editing tool the team uses (Google Docs, Notion, Markdown PRs, headless CMS draft mode). The specific commenting and review workflow within that tool. The specific tracking system for QA logs and escalations (Notion, Linear, Jira, custom database). The specific reporting cadence and format for editorial process owners. These vary per team and tooling. diff --git a/skills/editorial-qa/references/seo-aeo-compliance-checklist.md b/skills/editorial-qa/references/seo-aeo-compliance-checklist.md new file mode 100644 index 0000000..e3e31e6 --- /dev/null +++ b/skills/editorial-qa/references/seo-aeo-compliance-checklist.md @@ -0,0 +1,113 @@ +# SEO and AEO compliance checklist + +SEO and AEO checks combined into one workflow. The two-engine optimization principle holds: pieces that earn search rankings are largely the same pieces that earn AI citations. + +This checklist runs late in the QA sequence (after brief-adherence, fact-accuracy, structure, AI-content audit, voice). SEO and AEO failures are mostly auto-fixable; halting on them is rarely the right call. + +--- + +## SEO checks + +### Title and headings + +- Target keyword in title. The brief's primary keyword appears in the page title; the title is 50 to 65 characters; the title reads naturally rather than keyword-stuffed. +- H1 present and matches title intent. Some CMSs use the title as H1; some have separate H1. Either way, one H1 per page that establishes the topic. +- Heading hierarchy clean. No orphan H3s (every H3 sits under an H2). No H4 without H3. The hierarchy is tree-shaped, not arbitrary. +- H2 keyword variation. Supporting cluster keywords appear naturally across H2s without forcing. + +### Meta and URL + +- Meta description compelling and keyword-aware. 140 to 160 characters; includes the primary keyword without stuffing; reads as a benefit-statement that earns the click from SERP. +- URL slug short and descriptive. Hyphens, lowercase, keyword-aware, date-free, under 60 characters. Generic example: `/feature-flag-rollout/kill-switches/`. +- Canonical URL set. The piece has a canonical URL pointing to itself (or to the canonical version if this piece is a duplicate-by-design like an X vs Y comparison page). + +### On-page + +- Image alt text descriptive. Every image has alt text that describes the image's content, not "image of [thing]" or generic placeholders. +- External links open appropriately. Most external links open in a new tab; rel attributes (`noopener`, `noreferrer`, `sponsored`, `nofollow`) match the link's purpose. +- Internal link count appropriate. 3 to 7 internal links for a 1,500-word piece; 8 to 15 for a pillar piece. Below the floor signals under-linked; well above signals link-stuffing. + +--- + +## AEO checks + +The AEO surface complements the SEO surface. AI engines weight different patterns; the checks below catch what AI engines specifically reward. + +### Answer paragraphs at H2 level + +- 40 to 60 word answer paragraph immediately following each H2 question. AI engines extract these as citation candidates. The paragraph is self-contained: read alone, it answers the H2's specific question completely. +- Snippet-bait pattern repeats throughout. Not just the top of the piece. Every H2 gets one. + +### TL;DR section + +- Pillar pieces include a TL;DR section near the top. 150 to 250 words. Self-contained. The most-cited section by AI engines for pillar-shaped content. +- TL;DR placement. After the hero, before the table of contents. The reader sees TL;DR within the first scroll. + +### FAQ schema + +- FAQ section with FAQPage schema. Pieces that contain FAQ-shaped content (genuine reader questions with answers) mark the FAQ section with FAQPage structured data. Perplexity especially cites FAQPage content heavily. +- Genuine FAQs only. Do not mark fake FAQs (questions nobody actually asks) with FAQPage schema. Search engines and AI engines detect fabricated FAQs and deprioritize. + +### Statistics with sources + +- Specific statistics with cited sources. AI engines weight statistics with sources higher than vague qualifiers. "23% of B2B buyers cite [specific source]" beats "many B2B buyers." +- The numbers are real. Verify in the fact-accuracy gate; do not let hallucinated statistics ship just because they would help SEO/AEO. + +### Named entities + +- Entity coverage matches brief. The required entities from the brief are present; the standard entities are present where relevant; the gap entities are present where the brief committed to them. +- Entities mentioned with weight. Pass the brief's depth-of-coverage requirement: not just "CUPED is mentioned in passing" but "CUPED is developed in the methodology H2 with the formula and an example." + +### Distinctive POV + +- The piece takes a position. AI engines preferentially cite content with attributable claims. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. +- The POV is consistent with brand stance. Voice doc specified the brand stance; the piece's POV aligns. + +--- + +## Auto-fix vs flag vs halt + +Most SEO/AEO failures are auto-fixable: the editor or a script can fix slug, meta description, image alt text, schema markup without writer involvement. + +Some require flag-and-revise: heading structure, internal link count, answer paragraph patterns. The editor flags; the writer revises. + +Halt-conditions are rare for SEO/AEO. The typical case where halt makes sense: the piece is structurally wrong for the target SERP (brief specified listicle; piece is long-form prose). That is a brief-adherence failure that surfaced late; route back to the brief-adherence gate. + +--- + +## The combined SEO/AEO audit + +Run as one pass. The checks overlap (both reward heading structure, both reward depth, both reward freshness). Treating SEO and AEO as separate workflows doubles the audit time without doubling the catch rate. + +The discipline. One audit, one checklist, two-engine optimization mindset. The piece serves both surfaces or it serves neither well. + +--- + +## Pillar-specific extensions + +Pillar pieces have additional SEO/AEO requirements. + +- TL;DR section (covered above) +- Comprehensive entity coverage. Pillar pieces should mention 15 to 25 entities across the topic; cluster pieces have lower bars. +- Internal links to cluster pieces. Pillar links out to each cluster piece via contextual anchors, not via a footer dump. +- Schema includes BreadcrumbList. Tells crawlers and AI engines that this is the hub of a topical cluster. + +--- + +## Programmatic-page-specific extensions + +For programmatic SEO pages, SEO/AEO checks adapt. + +- Top-200-word answer. First 200 words answer the user's specific query directly. AI engines cite programmatic data pages for factual queries primarily. +- Schema population at scale. Every page has Article, Product, LocalBusiness, or other type-appropriate schema; schema fields populate from the same data that renders the visible page. +- Sampling discipline. Full-audit SEO/AEO checks are infeasible at scale; sample 50 to 200 pages per cycle (see `qa-at-scale-patterns.md`). + +--- + +## Methodology-level choices that stay in the public skill + +The combined SEO/AEO check sequence, the auto-fix/flag/halt taxonomy, the pillar-specific extensions, the programmatic-specific extensions. + +## Implementation choices that stay internal + +The specific tooling for automated SEO/AEO checks (Lighthouse audits, schema validators, headless-CMS-specific plugins). The specific schema-validation library or service. The specific staging environment where pre-publish checks run. The specific deployment pipeline that gates publish on SEO/AEO compliance. These vary by stack and team. diff --git a/skills/editorial-qa/references/structure-and-clarity-review.md b/skills/editorial-qa/references/structure-and-clarity-review.md new file mode 100644 index 0000000..aebad76 --- /dev/null +++ b/skills/editorial-qa/references/structure-and-clarity-review.md @@ -0,0 +1,128 @@ +# Structure and clarity review + +Lede patterns, sectioning principles, endings, structural anti-patterns. + +Structure determines whether the piece works as a piece. The discipline below is about making structure visible enough to QA repeatably without becoming process theater. + +--- + +## The lede + +The first 200 words. Two valid patterns depending on intent. + +For SEO/AEO pieces. The lede answers the user's likely query directly. The reader landed from a SERP looking for a specific answer; the lede provides it within the first 200 words. The rest of the piece develops the answer with depth. + +For thought leadership. The lede establishes the thesis. The reader is investing attention; the lede tells them the argument the piece will defend. The rest of the piece builds the case. + +Lede failure patterns. + +- Welcome-to-our-blog throat-clearing. The lede announces what the piece is about to do instead of doing it. +- Buried lede. The actual answer or thesis appears in section 4. The reader bounced at section 2. +- Vague opening. Generic descriptive paragraph that could open any article on the topic. +- History dump. "Since the dawn of [topic]..." Cuts the throat-clearing; ledes do not need a history. + +--- + +## Sectioning + +The check. H2s map to user mental model, not writer enthusiasm. + +User mental model. What questions does the reader bring? What questions follow naturally from the first answer? What does the reader want to know next? The H2 sequence answers these in order. + +Writer enthusiasm. What does the writer find interesting? Where does the writer want to dig deep? Writer enthusiasm produces sections that are well-written but mistargeted; the reader did not come for that section and skips it. + +The audit. Read the H2 list as a sequence of questions or topics. Does the sequence match what the reader's mind would ask in order? If H2 #4 has the answer the reader landed for, the structure has buried lede; promote H2 #4 to H2 #1. + +--- + +## Section length + +The check. Even-ish across H2s. + +Why even-ish matters. One massive section followed by four 80-word sections signals broken structure. The massive section is doing real work; the 80-word sections are placeholders or filler. + +The fix. + +- If the 80-word sections are placeholders: cut them or expand them to the section's natural depth. +- If the massive section is two facets bundled: split it into two H2s. +- If the structure is genuinely uneven (one section needs to be twice as long for substantive reasons): document the rationale; ship with the imbalance acknowledged rather than hidden. + +--- + +## Reading flow + +The check. Paragraphs connect; sentences vary in length. + +Paragraph flow. Each paragraph extends the previous one or pivots intentionally. Disconnected paragraphs read as bullet-points-pretending-to-be-prose. The fix: explicit connective tissue between paragraphs (the connection is implicit in the sequence, or the writer adds a one-sentence transition that does the work). + +Sentence variety. Reading aloud is the audit. Do all the sentences run the same length? That is a tell of AI-assisted writing or rushed drafting. Vary sentence length across the paragraph; mix short declarative sentences with longer ones that build through clauses. + +--- + +## Specificity vs abstraction + +The check. Claims are concrete, not vague. + +Concrete. Named tools, named methods, named statistics with sources, named experts, named scenarios. Concrete claims earn citations from AI engines and trust from readers. + +Abstract. "Many companies struggle with X." "Studies show Y." "Industry leaders agree Z." Vague claims read as content marketing filler; AI engines and readers both deprioritize. + +The fix. Replace each abstract claim with a specific one. "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research the writer did not do, halt and request the research before shipping. + +--- + +## Endings + +The check. Piece concludes with something specific. + +Specific endings. + +- An action the reader can take now +- A specific question that frames the next step +- A concrete idea that lands as the takeaway +- A direct call to action with a specific destination + +Filler endings to cut. + +- Wrap-up paragraphs that summarize what the piece just said +- Wrap-up frames that announce the ending instead of arriving at it (the conclusion should land as a conclusion, not declare itself) +- Vague "join us as we explore" closings +- Marketing-tone CTAs that do not match the piece's voice + +The ending is the last thing the reader reads; it is the moment of conversion or memory. Filler endings waste the moment. + +--- + +## Structural anti-patterns + +The patterns that surface in QA, with the fix for each. + +Bullet-list overuse. When prose would serve, the writer used bullets. Bullets fragment the reading flow and signal AI-assisted drafting. Convert bullets to prose where prose makes the connection between items clearer. + +Subheading-fest. Every paragraph has its own H3 subheading. Reads as outline-converted-to-content rather than written content. Cut subheadings to the structural ones; let prose carry between subheadings. + +Repetitive paragraph structure. Every paragraph is 2 or 3 sentences of similar length. Vary the structure: some paragraphs are one long sentence; some are 4 short sentences; some are a sentence and a fragment. + +Forced bilateral framing. "On one hand X, on the other hand Y" pattern repeated throughout. AI-tell. Pick a position; defend it; let the contrary position get one sentence rather than equal weight when the position is genuinely strong. + +Throat-clearing transitions. "That said," "With that in mind," "Moving on," "Now let us look at..." All filler. Cut them; the section heading does the transition work. + +--- + +## The read-aloud audit + +The fastest structure check. Read the piece aloud (or silently with attention to rhythm). + +Signals. Where does the rhythm break? Where do you stumble? Where does the reading energy drop? Each break is a structural signal. Sometimes the fix is sentence-level; sometimes it is structural. + +The discipline. The read-aloud audit takes 10 minutes for a 1,500-word piece. It catches problems that line-by-line review misses. Build it into the QA workflow. + +--- + +## Methodology-level choices that stay in the public skill + +The lede patterns, the sectioning principles, the section-length discipline, the reading-flow audit, the specificity rule, the endings discipline, the structural anti-patterns, the read-aloud audit. + +## Implementation choices that stay internal + +The specific format the team uses for structural feedback (inline comments versus written summary versus structural diff). The specific tooling for documenting structural decisions on a piece (CMS metadata, brief addendum, separate review doc). The specific surface conventions per content type (the team's own blog vs help doc vs landing page structural patterns). These vary by team and stack. diff --git a/skills/editorial-qa/references/voice-consistency-patterns.md b/skills/editorial-qa/references/voice-consistency-patterns.md new file mode 100644 index 0000000..3a0ba06 --- /dev/null +++ b/skills/editorial-qa/references/voice-consistency-patterns.md @@ -0,0 +1,108 @@ +# Voice consistency patterns + +Vocabulary, rhythm, stance, register. Mid-piece sampling discipline for long pieces. The voice-drift failure mode in AI-co-authored content. + +Voice is the most subjective QA dimension and often the easiest one to skip. The discipline below makes voice-consistency checking concrete enough to run repeatably. + +--- + +## Vocabulary + +The check. Brand-specific vocabulary used correctly; off-brand vocabulary absent. + +Brand vocabulary. Each brand has a set of terms it uses (or refuses) consistently. Apple says "Mac," not "PC." Stripe says "developers," not "engineers." A B2B SaaS company might say "customers," not "users." A consumer brand might say "members," not "subscribers." + +The audit. Pull the brand voice doc's vocabulary section. Check the piece for each preferred term and each forbidden term. Failures: off-brand terms slipped in (the writer or AI assistant defaulted to industry-standard vocabulary instead of brand-specific). + +Forbidden terms list. Every brand has a list. Common patterns: corporate-speak adjectives, throat-clearing phrases, generic descriptors that flatten distinctive voice. The list is short (10 to 30 terms typically); reviewers should know it cold. + +--- + +## Sentence rhythm + +The check. Sentence rhythm matches brand voice. + +Three common rhythms. + +- Short and punchy. Short sentences. Frequent paragraph breaks. Dramatic emphasis through structural choices. +- Measured and layered. Longer sentences with subordinate clauses. Paragraphs build through accumulation. Conversational but considered. +- Colloquial. Conversational rhythm with mid-sentence asides, contractions, and direct reader address. Reads like a smart person talking. + +The audit. Read 3 paragraphs aloud. Does the rhythm match the brand's voice doc? Common drift: AI-assisted pieces regress to a uniform medium-length sentence rhythm regardless of the brand's specified rhythm. + +--- + +## Stance + +The check. The piece takes positions consistent with brand POV. + +Brand stance varies. Some brands are diplomatic and surface multiple sides without endorsing one. Others are opinionated and take clear positions. Others are coach-style and challenge the reader directly. + +The audit. Pick 3 to 5 places in the piece where the writer made a stance choice (a recommendation, a warning, an evaluation). Does each match the brand's stance pattern? + +Voice drift signal. AI-assisted pieces regress toward "diplomatic" stance even when the brand stance is opinionated. "There are good arguments on all sides" is the AI default; opinionated brands need to push the AI back toward conviction explicitly. + +--- + +## Register + +The check. Formal versus casual matches the surface. + +Surface determines register. A whitepaper takes one register; a blog post takes another; a help doc takes a third. The brand voice doc usually specifies registers per surface type. + +The audit. Identify the surface this piece will publish on (blog, knowledge base, whitepaper, marketing page, product help). Check the piece's register against the surface-appropriate register. + +Common drift. Blog pieces drift formal (they read like watered-down whitepapers). Whitepapers drift casual (they read like long blog posts). Help docs drift either direction. The brand voice doc establishes register expectations; the QA check enforces them. + +--- + +## Mid-piece sampling + +The discipline. Long pieces drift; sample throughout, not just at start and end. + +Why drift happens. Writers (human or AI) start in brand voice because that is what the brief, the opening prompt, and the recent context established. By section 4 of a 3,000-word piece, the writer's working memory has shifted to the topic at hand and the voice has drifted toward a generic baseline. AI-assisted pieces drift faster because the model's defaults reassert without continuous reinforcement. + +The sampling pattern. + +- Start sample. First 200 words. Voice should be strongest here. +- Middle samples. Two paragraphs from the middle 60% of the piece. Voice should hold. +- End sample. Last 200 words. Voice should match the start. + +If the start and end samples show brand voice and the middle samples show generic voice, the piece has voice drift. Send it back with the drifted sections highlighted. + +--- + +## The voice-drift signal in AI-co-authored content + +Voice drift is the dominant voice failure in 2025-2026 content. AI assistants produce drafts that pass the start-and-end check (because the writer set up the opening prompt with brand voice cues) but fail the mid-piece check (because the model defaults reasserted in the middle). + +The detection pattern. + +- Mid-piece paragraphs use vocabulary not in the brand voice doc +- Mid-piece sentence rhythm regresses to medium-length uniformity +- Mid-piece stance becomes diplomatic where brand stance was opinionated +- Mid-piece register drifts toward "professional neutral" regardless of the surface's intended register + +The fix. When mid-piece drift is detected, the revision pass needs to explicitly pull the voice back. The editor's note: "Sections 3 and 4 read as model-default. Revise with the voice doc's vocabulary, rhythm, and stance. Specifically: [3 specific fixes]." + +--- + +## Voice calibration sessions + +Different editors apply voice judgment differently. Quarterly calibration sessions reduce the drift between editors. + +The session. Three editors review the same piece independently. Each writes a one-paragraph voice assessment. The team reads the three assessments together; differences in interpretation surface; the team reconciles to a shared standard. + +The output. A short addendum to the brand voice doc capturing the calibration consensus on whatever was contested. Over time the addenda accumulate into a sharper, more specific voice doc. + +Why calibration matters. Without it, voice judgment varies by editor; writers receive inconsistent feedback; voice drift compounds across the program. The calibration session is preventative; once the team is calibrated, individual reviews stay consistent. + +--- + +## Methodology-level choices that stay in the public skill + +The 4-dimension voice check (vocabulary, rhythm, stance, register), the mid-piece sampling discipline, the AI voice-drift detection pattern, the calibration session methodology. + +## Implementation choices that stay internal + +The specific brand voice doc format (Notion page, Markdown file, internal wiki page). The specific vocabulary list and the specific forbidden-term list (these are brand-specific and live in the brand's own documentation). The specific calibration session cadence and team composition. The specific tooling for archiving voice assessments. These vary per brand and team. diff --git a/skills/email-deliverability/SKILL.md b/skills/email-deliverability/SKILL.md new file mode 100644 index 0000000..aca68b1 --- /dev/null +++ b/skills/email-deliverability/SKILL.md @@ -0,0 +1,283 @@ +--- +name: email-deliverability +description: "Make sure email actually reaches inboxes. Use this skill when setting up email authentication (SPF, DKIM, DMARC), diagnosing emails landing in spam, planning a domain reputation strategy, monitoring sender reputation, or hardening against email spoofing. Triggers on email deliverability, SPF, DKIM, DMARC, spam folder, sender reputation, mailbox provider, soft bounces, bounce rate, BIMI, MTA-STS, deliverability audit. Also triggers when a marketing or transactional email isn't reaching users." +category: operations +catalog_summary: "DMARC, SPF, DKIM, sender reputation, deliverability monitoring" +display_order: 8 +--- + +# Email Deliverability + +Get email into inboxes, not spam folders. Set up authentication. Monitor reputation. Diagnose problems before they hurt the business. + +--- + +## When to use + +- Setting up email for a new domain +- A meaningful percentage of email is going to spam +- Customers report they're not receiving emails +- Setting up DMARC, SPF, or DKIM +- Hardening against domain spoofing +- Migrating email service providers +- Sender reputation has dropped +- Pre-launch audit before sending volume increases + +## When NOT to use + +- Writing the email content itself (use `email-sequences`) +- Designing the email program strategy (use `email-sequences`) +- DNS records in general (use `domain-strategy`) +- Outbound spam coming FROM your account (different problem; investigate compromised credentials) + +--- + +## Required inputs + +- The sending domain(s) +- The email service provider (ESP, transactional service, mail server) +- Current DNS records (or access to them) +- Email volume (transactional vs marketing, daily volume) +- Current deliverability state (if known: bounce rate, spam complaints) + +--- + +## The framework: 3 pillars + +Email deliverability rests on three pillars. Weakness in any one limits the others. + +### Pillar 1: Authentication + +Mailbox providers verify email is actually from who it claims to be from. Three records. + +SPF (Sender Policy Framework) + +Lists which servers are authorized to send mail for the domain. Published as a TXT record at the apex. + +``` +v=spf1 include:_spf.mailprovider.com -all +``` + +- `include:` adds another sender's authorized list +- `-all` (hard fail): mail from unlisted senders fails authentication +- `~all` (soft fail): unlisted senders are suspicious but pass; useful during rollout +- `+all`: never use; allows anyone to send + +Only one SPF record per domain. Multiple SPF records break SPF entirely. Combine senders into a single record. + +SPF has a 10-DNS-lookup limit. Each `include:` may use multiple lookups. Hit the limit and SPF stops working. Watch this carefully. + +DKIM (DomainKeys Identified Mail) + +A cryptographic signature on each outgoing email. The mail server signs with a private key; the public key is published in DNS. + +``` +selector1._domainkey.example.com TXT "v=DKIM1; k=rsa; p=MIGfMA0G..." +``` + +Selectors differ by ESP. Some use `default._domainkey`, some use unique selectors per service. Most ESPs walk you through publishing the records. + +DKIM proves the message wasn't modified in transit and that the sender controls the domain. + +DMARC (Domain-based Message Authentication, Reporting, and Conformance) + +The policy layer. Tells receivers what to do when SPF or DKIM fails, and where to send reports. + +``` +_dmarc.example.com TXT "v=DMARC1; p=reject; rua=mailto:dmarc-aggregate@example.com; ruf=mailto:dmarc-forensic@example.com; pct=100; adkim=s; aspf=s" +``` + +Components: +- `p=`: policy. `none`, `quarantine`, or `reject`. +- `rua=`: aggregate reports (daily, summary). Always set this. +- `ruf=`: forensic reports (per-message). Optional, can be high volume. +- `pct=`: percentage of failing mail subject to the policy. Useful for gradual rollout. +- `adkim=`, `aspf=`: alignment mode. `s` (strict), `r` (relaxed). Strict means From: domain must match exactly. + +DMARC is the most important record. It's what makes spoofing your domain hard. + +### Pillar 2: Reputation + +Mailbox providers (Gmail, Outlook, Yahoo) score every sender. Reputation drives delivery. + +Reputation factors: +- Authentication pass rates (SPF, DKIM, DMARC) +- Engagement signals (opens, replies, marking as not-spam) +- Negative signals (spam complaints, deletions without opens, blocking) +- List hygiene (low bounce rates, no spam traps) +- Volume consistency (sudden spikes look like spam) +- Content patterns (link reputation, attachment patterns) +- IP and domain history + +Reputation is per (sending domain × mailbox provider). Gmail's view of you is independent of Outlook's. + +### Pillar 3: List quality and engagement + +Authentication and reputation rest on list quality. Bad list = bad reputation eventually. + +- Only send to people who explicitly opted in +- Confirmed (double) opt-in for marketing wherever feasible +- Honor unsubscribes immediately and reliably +- Remove hard bounces immediately +- Sunset disengaged contacts (no opens in 6 months: reduce frequency or remove) +- Avoid third-party lists, scraped emails, or "purchased opt-ins" + +The single biggest deliverability lever for most senders is list hygiene. + +--- + +## Workflow + +### Step 1: Audit current state + +Check the current DNS records: + +```bash +dig +short txt example.com +dig +short txt selector1._domainkey.example.com +dig +short txt _dmarc.example.com +``` + +Also check: +- Current bounce rate (target: under 2%) +- Current spam complaint rate (target: under 0.1%) +- Current open rate (varies by industry; falling trend is a warning) +- Current sending volume + +Tools: mxtoolbox.com, dmarcian.com, mail-tester.com (for individual messages). + +### Step 2: Fix authentication + +If any of SPF, DKIM, DMARC is missing or misconfigured, fix first. + +SPF fix order: +1. Identify all legitimate senders (transactional ESP, marketing ESP, support tools, etc.) +2. Get the `include:` value or IP for each +3. Combine into a single SPF record +4. Verify lookup count is under 10 +5. Use `-all` for hard fail (or `~all` if rolling out gradually) + +DKIM fix order: +1. Generate a new selector per sending service +2. Publish the public key in DNS +3. Configure the ESP to sign with the private key +4. Verify with a test send (check headers for `dkim=pass`) + +DMARC fix order: +1. Publish DMARC with `p=none` initially (monitoring mode) +2. Set up an aggregate report endpoint (use a DMARC analytics service or your own) +3. Watch reports for at least 2-4 weeks +4. Identify any legitimate senders failing alignment; fix them +5. Move to `p=quarantine` with `pct=10`, gradually increase +6. Move to `p=reject` once confidence is high + +The full progression typically takes 2-3 months. Rushing causes legitimate mail to bounce. + +### Step 3: Set up monitoring + +Ongoing visibility: + +- DMARC aggregate reports: parsed daily. Watch for new sources, alignment failures, volume changes. +- Bounce rate: per ESP dashboard. Target under 2% for transactional, under 5% for marketing. +- Spam complaint rate: target under 0.1%. +- Reputation tools: Google Postmaster Tools (free), Microsoft SNDS, Talos, Sender Score. +- Blacklist monitoring: most ESPs include this; otherwise mxtoolbox.com or hetrixtools.com. + +### Step 4: Address list hygiene + +- Remove hard bounces from your sending lists immediately (most ESPs do this; verify) +- Set up suppression lists (unsubscribes, manual blocks, deliverability sinkholes) +- Sunset disengaged contacts (re-engagement campaigns or just remove) +- Review opt-in flows: do people know what they're signing up for? + +### Step 5: Content and pattern audit + +If reputation is good and authentication passes, check content: + +- HTML-only emails (no plain-text alternative) raise flags +- Heavy image-to-text ratios raise flags +- Suspicious link patterns (bare IPs, URL shorteners, hijacked domains) +- Specific spam-trigger words in subject lines (less important than it used to be, still real) +- Lots of mismatched domains in URLs +- Generic from-name like "info@" rather than a real-sounding sender + +### Step 6: Plan for growth + +Email volume affects reputation. Sudden spikes look like spam. + +- Warm up new sending IPs gradually (start at 50/day, 2x daily) +- Warm up new domains gradually (similar pattern) +- Spread sends throughout the day +- Don't switch ESPs the week before a big launch + +### Step 7: Set up BIMI (optional but valuable) + +BIMI (Brand Indicators for Message Identification) shows your logo next to authenticated emails in supporting clients (Gmail, Apple Mail, Yahoo, others). + +Requires: +- DMARC at `p=quarantine` or `p=reject` (so this comes after the DMARC progression) +- A trademarked logo as an SVG (specific format requirements) +- A Verified Mark Certificate (VMC) from a CA, for Gmail and others +- A `_bimi` DNS record pointing to the SVG and VMC + +BIMI improves trust signals and engagement. Worth doing once DMARC enforcement is in place. + +### Step 8: Document and revisit + +Document the email architecture: +- Sending domains and subdomains +- Each ESP and what it sends +- DNS records for each +- Monitoring setup +- Escalation if deliverability degrades + +Revisit quarterly or when a new ESP is added. + +--- + +## Failure patterns + +Multiple SPF records. Two or more SPF records on the same domain breaks SPF. Combine into one. + +SPF DNS lookup limit exceeded. Too many `include:` directives or chained includes. Flatten or simplify. + +DMARC at `p=none` forever. Monitoring without enforcement. Spoofing remains easy. Move to enforcement. + +DMARC at `p=reject` too quickly. Legitimate mail bounces because alignment wasn't verified. Use the gradual rollout. + +Sending from a different domain than the From: address. Causes alignment failures. Fix the From: domain or ensure proper alignment. + +Using a shared ESP IP without ESP-specific configuration. Some ESPs don't sign with your DKIM by default; the signature is the ESP's, not yours. Configure custom DKIM. + +Sending from a domain that also sends marketing. A spam complaint on a marketing email hurts transactional deliverability. Use a subdomain for transactional (`transactional.example.com`) or marketing (`mail.example.com`). + +No bounce monitoring. Hard bounces accumulate, reputation tanks, deliverability cliff-falls. Monitor. + +Bought lists or scraped contacts. Spam traps in those lists destroy reputation. Don't. + +No double opt-in for marketing. Single opt-in lets bots and typos onto the list. Bots generate spam complaints, destroy reputation. + +Ignoring DMARC reports. Reports show problems early. Set up a parser. Look weekly. + +Treating "marked as not-spam" as the goal. The goal is to never land in spam in the first place. Once reputation is bad, recovery takes months. + +--- + +## Output format + +A deliverability audit document includes: + +- Domain inventory: every sending domain +- Authentication status: SPF, DKIM, DMARC per domain +- Sender inventory: every ESP or service that sends mail, what's configured +- Reputation status: per major mailbox provider where measurable +- List hygiene: bounce rate, complaint rate, opt-in process +- Findings: prioritized issues +- Roadmap: SPF/DKIM/DMARC fixes, BIMI plan, monitoring plan +- Monitoring setup: what's watched, where alerts go + +--- + +## Reference files + +- [`references/dmarc-rollout-playbook.md`](references/dmarc-rollout-playbook.md): Step-by-step for moving from no DMARC to `p=reject`, with timing, monitoring, and how to handle problems found along the way. diff --git a/skills/email-deliverability/references/dmarc-rollout-playbook.md b/skills/email-deliverability/references/dmarc-rollout-playbook.md new file mode 100644 index 0000000..bc3d319 --- /dev/null +++ b/skills/email-deliverability/references/dmarc-rollout-playbook.md @@ -0,0 +1,294 @@ +# DMARC Rollout Playbook + +A staged, low-risk path from no DMARC to full `p=reject` enforcement. Typical duration: 2-3 months. Rushing breaks things. + +--- + +## Why DMARC matters + +Without DMARC at enforcement, anyone can send email claiming to be from your domain. Phishing campaigns can spoof your brand to your customers, your investors, your own employees. + +DMARC at `p=reject` means mailbox providers will reject mail that fails authentication. The spoofing attacks fail. + +The goal of this playbook: get to `p=reject` without losing legitimate mail. + +--- + +## Prerequisites + +Before starting: + +- [ ] SPF is published, single record, under 10 lookups +- [ ] DKIM is published, every legitimate sender signs with your domain's key +- [ ] You have a DMARC report destination (a parsing service or your own endpoint) +- [ ] You have access to make DNS changes +- [ ] You know who is responsible for fixing email-related issues + +If any of these are missing, fix them first. DMARC enforcement on top of broken SPF or DKIM means losing legitimate mail. + +--- + +## Stage 1: Monitor (Week 1-2) + +### Goal +Discover every legitimate sender of mail from your domain. Many will be unexpected. + +### Action + +Publish DMARC at `p=none`: + +``` +v=DMARC1; p=none; rua=mailto:dmarc-aggregate@example.com; pct=100; adkim=r; aspf=r +``` + +Notes: +- `p=none`: no enforcement; mailbox providers report but take no action +- `rua=`: where aggregate reports go. Use a DMARC analytics service or your own endpoint +- `adkim=r`, `aspf=r`: relaxed alignment (less strict; eases initial rollout) + +### What to watch + +Aggregate reports start arriving from major mailbox providers within 24-48 hours. Reports are XML, daily, summarized. + +Look for: +- Every IP and sender sending mail "From: yourdomain" +- Pass/fail rates for SPF and DKIM +- Volume per sender +- Unexpected senders (often: a marketing tool, a customer support tool, a forgotten old service) + +### Common discoveries + +- Marketing ESP signing with their domain, not yours +- Internal tools sending email through unauthorized servers +- Help desk forwarding mail in a way that breaks alignment +- A SaaS notification service no one remembered +- Compromised accounts (rare but real) +- Spoofers trying to phish + +### Exit criteria + +- All legitimate senders identified +- All legitimate senders pass SPF or DKIM (ideally both) +- The volume of failing legitimate mail is well understood + +--- + +## Stage 2: Quarantine 10% (Week 3-4) + +### Goal +Begin enforcement on a small percentage. Watch for legitimate mail being affected. + +### Action + +Update DMARC to: + +``` +v=DMARC1; p=quarantine; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +Now 10% of failing mail goes to spam at supporting providers. 90% still passes through. + +### What to watch + +- Aggregate reports continuing to flow +- Customer reports of legitimate mail in spam +- Internal complaints (your own team is often the canary) + +### What to do if problems + +If a known-legitimate sender starts having mail quarantined: + +1. Identify the sender and the failure (SPF? DKIM? Alignment?) +2. Fix the sender (add to SPF, configure DKIM, fix alignment) +3. Verify the fix in subsequent reports +4. Continue + +If an unknown legitimate sender starts having mail quarantined: + +1. Investigate. Is this real legitimate use? (Internal tool? New SaaS?) +2. If yes, fix the authentication for it +3. If no, this is the spoofing DMARC is meant to stop + +### Exit criteria + +- Reports show no legitimate mail being quarantined +- Sustained for at least one week with no surprises + +--- + +## Stage 3: Quarantine 100% (Week 5-6) + +### Goal +Enforce quarantine for all failing mail. Build confidence before reject. + +### Action + +``` +v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 2 but expect higher volume of spam-foldered mail. Most should be illegitimate. + +### Exit criteria + +- No legitimate mail quarantined for at least one week +- Spoofing volume in reports is clearly visible (this is what DMARC is catching) + +--- + +## Stage 4: Reject 10% (Week 7-8) + +### Goal +Start rejecting failing mail. Fail-mode is harder than quarantine; legitimate mail that fails is bounced, not delivered to spam. + +### Action + +``` +v=DMARC1; p=reject; pct=10; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +10% of failing mail is rejected. The other 90% goes to quarantine (the previous policy applies). + +### What to watch + +- Bounce rates from your sending tools (transactional and marketing) +- Customer reports of "I never got the email" +- Reports of legitimate mail being rejected + +If bounces spike, something legitimate is failing. Investigate immediately and consider rolling back. + +### Exit criteria + +- No spike in bounces or "didn't receive email" reports +- Sustained for at least one week + +--- + +## Stage 5: Reject 50% (Week 9-10) + +### Action + +``` +v=DMARC1; p=reject; pct=50; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Same as Stage 4. Legitimate failures will be more visible at higher percentage. + +### Exit criteria + +Same as Stage 4. No spike in legitimate mail rejection. + +--- + +## Stage 6: Reject 100% (Week 11+) + +### Goal +Full enforcement. Spoofing is now blocked. + +### Action + +``` +v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-aggregate@example.com; adkim=r; aspf=r +``` + +### What to watch + +Continue monitoring reports. New senders, configuration drift, and changes in the email infrastructure can introduce new failures over time. + +### Maintenance + +- Review reports at least weekly +- Audit sender list quarterly +- Re-verify SPF and DKIM after any infrastructure change + +--- + +## Optional: Strict alignment + +After `p=reject` is stable, consider tightening alignment: + +``` +v=DMARC1; p=reject; pct=100; rua=...; adkim=s; aspf=s +``` + +Strict alignment requires the From: domain to match exactly (not just a parent domain). This catches subdomain spoofing too. + +Verify in monitoring mode (back to `p=none` with `adkim=s; aspf=s`) before enforcing. + +--- + +## Subdomain policy + +DMARC includes `sp=` for subdomain policy. Without it, subdomains inherit the main policy. + +For high-security applications: + +``` +v=DMARC1; p=reject; sp=reject; ... +``` + +This rejects spoofs on subdomains too. Important for parked or unused subdomains; an attacker can pick any subdomain by default. + +--- + +## Edge cases + +### Forwarders and mailing lists + +When mail is forwarded (e.g., user@oldcompany.com forwards to user@newcompany.com), SPF often fails (the forwarder is now the sender from SPF's view). + +DKIM survives forwarding if the message body isn't modified. Mailing lists that modify headers or add footers can break DKIM. + +Solutions: +- ARC (Authenticated Received Chain): restores authentication across forwards. Major providers support it. +- DKIM only (don't rely on SPF for DMARC alignment): if DKIM passes, DMARC passes regardless of SPF +- Mailing list software that's DMARC-aware + +### Bulk transactional providers + +Some providers (notification services, password reset emails) have hundreds of customers sharing IP space. Authentication usually requires custom domain setup; the default shared sending often fails alignment. + +Solution: configure the provider to use your domain for DKIM and From: address. Most providers offer "custom domain" or "sender authentication" features. + +### Email-on-acid testing services + +If you use email testing services that "send on your behalf" but don't authenticate, those will fail. Either configure them or accept the failure (they're not user-facing). + +--- + +## What can go wrong + +Legitimate mail starts bouncing. Roll back to the previous stage immediately. Investigate the failure. Fix. Try again. + +Spoofing complaints rise. Counterintuitively, after DMARC enforcement, you may see a temporary rise in complaints because spoofing that was previously delivered (silently spoofed your customers) now bounces (and the spoofer gets a bounce notification, then sometimes complains to the wrong place). This usually settles within a week. + +Volume of reports overwhelms. Reports are voluminous from large mailbox providers. Use a DMARC analytics service rather than parsing manually. + +Forensic reports (`ruf=`) flooding. Forensic reports include full message content of failures and can be high volume. Many use `rua=` (aggregate) only, especially after Stage 1. + +--- + +## Tools + +- Reporting/Analytics: Postmark, dmarcian, EasyDMARC, Valimail, Cloudflare Email Routing (free for some scenarios), or roll your own with a DMARC parser library. +- Testing: mxtoolbox.com, mail-tester.com, dmarcian.com. +- Lookups: `dig +short txt _dmarc.example.com`. + +--- + +## Timing summary + +\| Stage \| Policy \| Duration \| What you're doing \| +\|---\|---\|---\|---\| +\| 1 \| `p=none` \| 1-2 weeks \| Discovery \| +\| 2 \| `p=quarantine; pct=10` \| 1-2 weeks \| Initial enforcement \| +\| 3 \| `p=quarantine; pct=100` \| 1-2 weeks \| Full quarantine \| +\| 4 \| `p=reject; pct=10` \| 1-2 weeks \| Initial rejection \| +\| 5 \| `p=reject; pct=50` \| 1-2 weeks \| Half rejection \| +\| 6 \| `p=reject; pct=100` \| Ongoing \| Full enforcement \| + +Total: 6-12 weeks. Don't shortcut. The cost of moving slowly is low; the cost of breaking legitimate mail is high. diff --git a/skills/email-sequences/SKILL.md b/skills/email-sequences/SKILL.md new file mode 100644 index 0000000..e735886 --- /dev/null +++ b/skills/email-sequences/SKILL.md @@ -0,0 +1,282 @@ +--- +name: email-sequences +description: "Design and write email campaigns and sequences including onboarding flows, lifecycle campaigns, transactional emails, newsletters, broadcast sends, and launch and announcement emails. Use this skill whenever the user wants to write email copy, plan an email sequence, design an onboarding drip, or set up lifecycle email campaigns. Triggers on email sequence, drip campaign, onboarding email, lifecycle email, welcome email, transactional email, newsletter, email broadcast, launch email, announcement email, nurture sequence, abandoned cart, re-engagement, win-back. Also triggers when planning email automation flows or writing email subject lines for campaigns." +category: content +catalog_summary: "Onboarding flows, lifecycle campaigns, transactional copy" +display_order: 5 +--- + +# Email Sequences + +Plan and write email campaigns. Sequences (multi-message flows triggered by events) and broadcasts (one-off sends). Stack-agnostic. Works with any email service provider. + +--- + +## When to use + +- Writing welcome and onboarding email sequences +- Planning lifecycle campaigns (activation, retention, win-back) +- Writing transactional emails (receipts, password resets, notifications) +- Newsletter design and writing +- Abandoned-cart or re-engagement flows +- Writing a one-off broadcast, launch announcement, or news email +- Drafting email subject lines and preview text for any send + +## When NOT to use + +- Landing pages and conversion pages (use `landing-page-copy`) +- Long-form articles (use `content-and-copy`) +- Brand voice work (use `brand-voice`) +- Analytics setup for email (use `analytics-strategy`) + +--- + +## Required inputs + +- The audience (segment or list) +- The trigger or context (signup, purchase, abandonment, time-based, manual) +- The goal of the email or sequence +- Brand voice +- Any technical constraints (provider, deliverability requirements) + +If the audience is undefined, define it before writing. Generic emails to "everyone" perform worse than targeted ones. + +--- + +## The framework: 6 sequence types + +Most email programs run a handful of standard sequence patterns. Each has its own goals, structure, and pitfalls. + +### 1. Welcome / onboarding + +Triggered by signup. Goal: get the user to first value. + +Typical structure (5 emails over 14 days): + +- Email 1 (immediate): Welcome. Confirm they're in. State what happens next. Single CTA: the next obvious action. +- Email 2 (day 1 or 2): First-value step. Help them get to a quick win or core action. +- Email 3 (day 4 or 5): Education. Show them something they probably haven't discovered yet. +- Email 4 (day 8): Social proof. Customer story or use case relevant to their segment. +- Email 5 (day 14): Outcome reminder. Where they could be in 30/60/90 days. Soft commercial cue. + +Common failure: Front-loading product features. Users don't care about features yet; they care about getting to value. + +### 2. Lifecycle / activation + +Time- or behavior-triggered. Goal: move users from signup to engaged user. + +Patterns: +- Sent when a user completes a milestone (first project, first invite, first export) +- Or sent when a user has NOT completed a milestone after N days +- Each email targets a specific next step + +Best practice: Trigger on behavior, not just time. A user who has done 3 onboarding steps doesn't need an email telling them to get started. + +### 3. Retention / engagement + +Ongoing. Goal: keep active users engaged. + +Patterns: +- Newsletter (weekly or monthly) +- Product updates +- Tips and tutorials +- Customer-only content (community, behind-the-scenes) + +Cadence rule: Frequency that earns the read, not frequency that fills the calendar. Weekly newsletter that is genuinely useful beats daily newsletter that gets archived. + +### 4. Re-engagement / win-back + +Triggered by inactivity. Goal: pull a lapsed user back. + +Typical structure (3 emails): + +- Email 1: "We miss you" framing or value reminder. What's new since they were last active. +- Email 2: Specific incentive (discount, feature unlock, content offer). +- Email 3: "Last call" or list-cleaning email. "We'll stop emailing you unless you click this." + +Best practice: Honor the unsubscribe. Aggressive win-back damages deliverability. A clean list of engaged subscribers beats a large list of inactive ones. + +### 5. Transactional + +Triggered by actions: receipts, password resets, notifications, order confirmations, shipping updates. + +Best practices: +- Confirm the action that triggered the email at the top +- Include all relevant detail without padding +- Use plain language ("Your order shipped" not "Your shipment notification") +- One primary CTA (track package, view receipt, view account) +- Subject line states the action ("Your receipt for order #12345") + +Highest open rates of any email type. Use sparingly for marketing nudges; over-marketing transactional emails damages trust. + +### 6. Broadcast + +One-off sends. Announcements, launches, news, time-sensitive campaigns. + +Best practices: +- Subject line earns the open +- Single clear message per send +- Specific audience targeting (do not blast the entire list for narrow announcements) +- Clear CTA in the first screen-height +- Mobile-optimized (most opens are mobile) + +--- + +## The 5 components of every email + +Regardless of sequence type, every email has the same components. + +### 1. Subject line + +The deciding factor for whether the email gets opened. + +Patterns: +- Specific ("Your week 1 progress: 3 of 5 steps done") +- Curiosity ("The mistake most teams make in week 2") +- Direct ("Your invoice #12345") +- Personal ("Quick question, [name]") +- Urgency ("Last day for the team plan discount") - use sparingly + +Avoid: +- ALL CAPS +- Excessive punctuation (!!!) +- Click-bait that doesn't deliver +- Generic ("Newsletter #23") + +Length: 30 to 50 characters. Mobile clients truncate longer. + +### 2. Preview text (preheader) + +The line that appears below or beside the subject in most email clients. + +Best practice: +- Treat as the subject's wingman +- Add what the subject line couldn't fit +- Avoid wasting it on "View this email in browser" +- 50 to 90 characters + +### 3. Opening + +The first line of the email body. The reader is deciding whether to keep reading. + +Strong openings: +- Reference the trigger ("You signed up yesterday for...") +- Get to the point ("Here's what changed this week...") +- Personal ("Saw your team just hit milestone X. Nice work.") + +Weak openings: +- "I hope this email finds you well." +- "Welcome to our amazing platform." +- Long throat-clearing before the actual content + +### 4. Body + +The substance. + +Length guide: +- Welcome and transactional: under 100 words +- Lifecycle and activation: 100 to 250 words +- Newsletter: 200 to 800 words depending on format +- Sales sequences: 250 to 500 words + +Structure: +- One core message per email (avoid "while we have you...") +- Short paragraphs (2 to 3 lines) +- Bullets or lists when content is enumerable +- Mobile-first formatting + +### 5. CTA + +The action the email is asking for. + +Best practices: +- One primary CTA per email (multiple CTAs split attention) +- Button or clearly-styled link, not buried in prose +- Action verb + specific outcome ("See your dashboard" not "Click here") +- Above the fold AND repeated at the end of longer emails +- Plain text link as a fallback for users who block buttons + +--- + +## Workflow + +### For a new sequence + +1. Define the trigger. What event starts this sequence? (Signup, purchase, abandonment, manual.) +2. Define the goal. What does success look like at the end of the sequence? +3. Map the journey. What does the recipient need to know, do, or feel between trigger and goal? +4. Outline emails. One purpose per email. Sequence them across appropriate timing. +5. Draft email 1. Subject, preview, opening, body, CTA. +6. Draft remaining emails. Each builds on the previous. +7. Test the sequence. Send to yourself. Read on mobile. Time the gaps. +8. Set up triggers. Configure in the email service provider. +9. Measure. Open rate, click rate, completion rate per email. Sequence completion rate. + +### For a single broadcast + +1. Define the audience. Specific segment, not the whole list. +2. Define the goal. One thing this email accomplishes. +3. Draft subject + preview. Generate 5 to 10 variations. +4. Draft body. Single message, clear CTA. +5. Test on mobile. Most opens are mobile. +6. Schedule. Day and time matched to audience behavior. +7. Measure. Open rate, click rate, downstream conversions. + +--- + +## Failure patterns + +- Sending to "everyone." Generic broadcasts to the full list have lower engagement than targeted segments. +- Too many CTAs in one email. Splits attention. Pick one. +- Subject line clickbait that doesn't deliver. Crashes the trust the email program is trying to build. +- Sequences that ignore behavior. Sending day-3 onboarding email to a user who already activated wastes the touch. +- Mobile-broken layouts. 60 to 70 percent of opens are on mobile. Test there first. +- Long pre-text. Burying the message under "I hope this email finds you well" wastes the read. +- Aggressive win-back. Emailing dormant users 5 times damages deliverability and brand trust. +- No measurement. Without tracking opens, clicks, and downstream conversion, you can't iterate. +- Ignoring deliverability. Sender reputation, authentication (SPF, DKIM, DMARC), list hygiene. Skip these and emails go to spam regardless of how good the content is. + +--- + +## Output format + +Default output is a markdown document per email or sequence: + +```markdown +# Sequence: [Name] + +Trigger: [What starts this sequence] +Goal: [Outcome at completion] +Audience: [Specific segment] +Length: [N emails over X days] + +## Email 1 - [Subject working title] + +Send: [Trigger / Day N] +Subject: [text] +Preview: [text] + +[Body] + +Primary CTA: [text] +CTA URL: [destination] + +--- + +## Email 2 - [Subject working title] + +[Same structure] + +--- + +[etc.] +``` + +For a single broadcast, just one email block. + +--- + +## Reference files + +- [`references/subject-line-patterns.md`](references/subject-line-patterns.md) - Subject line patterns with examples for each sequence type. +- [`references/sequence-templates.md`](references/sequence-templates.md) - Skeleton templates for the 6 sequence types. diff --git a/skills/email-sequences/references/sequence-templates.md b/skills/email-sequences/references/sequence-templates.md new file mode 100644 index 0000000..ac0ca87 --- /dev/null +++ b/skills/email-sequences/references/sequence-templates.md @@ -0,0 +1,252 @@ +# Sequence Templates + +Starter outlines for the 5 standard sequence types. These are scaffolds. Adapt the cadence, voice, and content to the specific brand and audience. + +--- + +## Onboarding sequence (SaaS, 7 emails over 14 days) + +### Email 1 - Welcome +Send: Immediately on signup +Subject: Welcome to [Product]. Here's your first step. +Body skeleton: +- One-line welcome +- Restate the outcome they signed up for +- ONE clear next step +- Optional: founder note for early-stage products + +### Email 2 - First action tutorial +Send: T+1 day +Subject: [Specific first task] in 5 minutes +Body skeleton: +- Hook: Why this first task matters +- 3 to 5 numbered steps +- Visual or screenshot +- CTA back to the product + +### Email 3 - Build on first +Send: T+3 days +Subject: Now that [first task done], try [second task] +Body skeleton: +- Acknowledge progress (works even if user hasn't done first task; it primes them) +- Introduce next capability +- Show what it unlocks +- CTA + +### Email 4 - Use case spotlight +Send: T+5 days +Subject: How [persona] uses [Product] to [outcome] +Body skeleton: +- Specific persona description +- Their workflow with the product +- Specific result +- "Try this approach" CTA + +### Email 5 - Common questions +Send: T+7 days +Subject: Quick answers to questions new users ask +Body skeleton: +- 3 to 5 FAQs with brief answers +- Links to fuller help docs +- CTA: open help center or chat with support + +### Email 6 - Re-engagement check +Send: T+10 days (only if user is dormant) +Subject: Need a hand getting started? +Body skeleton: +- Acknowledge they may be busy +- Offer a 10-minute call or specific resource +- One simple action they can take in <2 minutes + +### Email 7 - Hand-off to ongoing comms +Send: T+14 days +Subject: You're set up. Here's what to expect from us. +Body skeleton: +- Confirm onboarding complete +- Set expectations for future emails (frequency, content type) +- Offer preferences center +- Light next-step CTA + +--- + +## Lifecycle (triggered, individual emails) + +### Anniversary (annual) +Subject: Hard to believe - it's been a year +Body: Celebrate the milestone, surface specific achievements ("You shipped X projects this year"), suggest next-level use case. + +### Plan upgrade nudge +Subject: You're hitting your [Plan] limits +Body: Specific data showing usage approaching limits, value of next tier, painless upgrade path. + +### Inactivity check (30 days dormant) +Subject: We haven't seen you for a bit +Body: Light touch, restate value, surface a recent improvement, easy way to come back. + +### Power user celebration (Y key actions) +Subject: You've crossed [Y] [actions]. Nice. +Body: Acknowledge the milestone, share advanced tips, invite to community or beta. + +### Feature announcement (when relevant feature ships) +Subject: New: [feature] +Body: What it does, why we built it, how to start using it. Brief. + +--- + +## Sales nurture (B2B, 9 emails over 28 days) + +### Email 1 - Deliver the asset +Send: Immediately on opt-in +Subject: Your [asset name] +Body: Direct download link, brief intro to what's inside. + +### Email 2 - Educational angle +Send: T+2 days +Subject: [Specific question the audience asks] +Body: Useful content piece tied to their problem. No pitch. + +### Email 3 - Educational angle (different facet) +Send: T+4 days +Subject: [Adjacent question] +Body: Different angle on the same problem space. + +### Email 4 - Customer story +Send: T+7 days +Subject: How [Customer] [achieved specific outcome] +Body: Specific company, specific outcome, specific approach. Their story, with brand as supporting role. + +### Email 5 - Objection handling +Send: T+10 days +Subject: "I'm not sure [common objection]" +Body: Address the most common reason this audience hesitates. Honest, non-defensive. + +### Email 6 - Demo invitation +Send: T+14 days +Subject: Want to see [Product] in action? +Body: 20-minute personalized demo offer. Specific outcome the demo will show. + +### Email 7 - Strong proof + soft pitch +Send: T+18 days +Subject: [Specific result] in [specific time] +Body: Strongest case study, direct invitation to start a trial or call. + +### Email 8 - Urgency +Send: T+21 days +Subject: [Deadline or limited offer] +Body: Clear offer with deadline. Real urgency only - manufactured urgency damages trust. + +### Email 9 - Goodbye +Send: T+28 days +Subject: Last note from us +Body: Acknowledge the silence. Offer one last resource or chance to opt back in. Then suppress or move to long-term nurture list. + +--- + +## Transactional templates + +### Order confirmation +Subject: Your order #[number] is confirmed +Body: +- Order summary (items, totals, shipping address) +- Estimated delivery +- Order tracking link +- Support contact + +Keep marketing minimal. People are looking for specific info. + +### Password reset +Subject: Reset your password +Body: +- Brief acknowledgment of the request +- Reset link (with expiration time stated) +- "Did not request this?" instruction +- Support contact + +No marketing in transactional. Keep it clean. + +### Email verification +Subject: Verify your email +Body: +- One-line ask +- Big verify button +- "If you did not sign up..." opt-out +- Expiration time + +### Abandoned cart +Subject: You left these in your cart +Body: +- Items left in cart with images +- Quick-resume link +- Optional: incentive (free shipping, small discount) +- Support contact + +Send 1 email at T+1 hour, optional second at T+24 hours, NO third email (annoyance penalty exceeds recovery). + +--- + +## Win-back (5 emails over 20 days) + +### Email 1 - We miss you +Subject: Hey, it's been a while +Body: Acknowledge the lapse, brief reminder of what's possible, soft re-engage CTA. + +### Email 2 - What's new +Subject: A few things have changed since you were last here +Body: Updates, new features, recent improvements. Specific. + +### Email 3 - Specific incentive +Subject: Come back: [specific offer] +Body: Concrete incentive (discount, bonus, free month). Deadline. + +### Email 4 - Last chance +Subject: Last call: [offer ends X] +Body: Final reminder of the offer. Clear deadline. + +### Email 5 - Sunset +Subject: We'll miss you +Body: Acknowledge they're not coming back, confirm we're stepping down sends, leave the door open. + +After this email: suppress from active sends. Optional: move to a quarterly "big news only" list. + +--- + +## Cadence rules across all sequence types + +- Default time of day: 8 to 10 AM in the recipient's timezone for non-time-sensitive sends. +- Avoid send fatigue: Cap at 2 emails per week from the same brand to the same person across all programs. +- Respect engagement: If a user has opened zero of the last 5 emails, throttle frequency or sunset. +- Honor unsubscribes immediately: Same-day, all programs, no exceptions. +- Test sending: Send tests to 5+ devices before any sequence goes live. + +--- + +## Subject line patterns that work + +- Specific question: "Why your churn rate isn't moving" +- Specific number: "47% of B2B buyers do this before purchasing" +- Personal/conversational: "Quick question about [topic]" +- Curiosity gap: "The mistake we see in 80% of pricing pages" +- Negative framing (sparingly): "Don't make this mistake on your next launch" +- Direct value: "Free template: 90-day onboarding checklist" + +Avoid: + +- Subject lines that look like spam (all caps, multiple exclamations) +- Misleading subject lines (mentions in subject that aren't in body) +- Tricks ("Re:" or "Fwd:" on cold sends) +- Subject lines longer than 50 characters where avoidable + +--- + +## Metrics to track per sequence + +\| Metric \| Target benchmark (rough) \| +\|---\|---\| +\| Open rate \| 20 to 35% (varies wildly by industry) \| +\| Click-through rate \| 2 to 5% \| +\| Conversion to goal \| Sequence-specific \| +\| Unsubscribe rate per email \| <0.5% \| +\| Spam complaint rate \| <0.1% \| +\| Reply rate (for cold/B2B) \| 1 to 3% \| + +Below benchmark: investigate the weakest emails in the sequence first. Above: capture what worked and apply to other sequences. diff --git a/skills/email-sequences/references/subject-line-patterns.md b/skills/email-sequences/references/subject-line-patterns.md new file mode 100644 index 0000000..2df7648 --- /dev/null +++ b/skills/email-sequences/references/subject-line-patterns.md @@ -0,0 +1,298 @@ +# Subject Line Patterns + +Subject lines are the deciding factor for opens. A great email with a weak subject gets archived unread. + +These patterns are tools, not formulas. Apply them, then make them sound like the brand. + +--- + +## Universal rules + +- Length: 30 to 50 characters. Mobile clients truncate longer. +- No ALL CAPS. Reads as shouting and triggers spam filters. +- No excessive punctuation. "!!!" reads as desperate. +- Match the body. A subject that doesn't deliver in the body kills trust. +- Sentence case is more readable than Title Case in inboxes. +- Skip the prefix conventions ("Newsletter #23"). Subscribers ignore them. + +--- + +## Pattern 1: Specific outcome + +Names what the reader gets. + +Examples: +- "The 5 questions to ask before hiring a designer" +- "Your team's productivity numbers for September" +- "How to cut your invoicing time in half" +- "What changed in your competitor's pricing this month" + +Strengths: Clear value. Easy to evaluate whether to open. + +When to use: Newsletters, content emails, value-driven sends. + +--- + +## Pattern 2: Curiosity gap + +Opens a loop the email body closes. + +Examples: +- "The mistake most teams make in week 2" +- "Why your best customers are leaving" +- "The one habit your top performers share" +- "What I wish I'd known before scaling to 50 people" + +Strengths: High open rates when the gap is genuine. + +Risks: Becomes click-bait if the body doesn't deliver. Erodes trust over time. + +When to use: Sparingly. The body must deliver real insight. + +--- + +## Pattern 3: Personal / direct + +Speaks as if to a friend. + +Examples: +- "Quick question, [name]" +- "Saw this and thought of you" +- "Got 5 minutes?" +- "Are you still using [tool]?" + +Strengths: Feels human. Cuts through marketing-speak. + +Risks: Used by every spam email. Authentic context required for it to work. + +When to use: 1:1 sends, personalized cold outreach, founder-to-customer emails. + +--- + +## Pattern 4: Direct / no-mystery + +States exactly what the email is about. + +Examples: +- "Your receipt for order #12345" +- "Password reset link" +- "Invoice for September" +- "Meeting confirmation: Tuesday 2pm" + +Strengths: High trust. High open rates for transactional content. + +When to use: Transactional emails. Always be direct. + +--- + +## Pattern 5: Question + +Poses the question the reader is asking. + +Examples: +- "Should you hire a generalist or specialist first?" +- "Is your pricing too cheap?" +- "What's the ROI of customer service?" +- "Are you measuring the wrong KPIs?" + +Strengths: Aligns with the reader's mental state. Strong for educational content. + +When to use: Newsletters and educational sequences. + +--- + +## Pattern 6: Number / list + +Promises a specific quantity of items. + +Examples: +- "3 things to do this week to retain customers" +- "7 signs your team is about to burn out" +- "The 4-step checklist for a clean handoff" + +Strengths: Sets clear expectations. Easy to scan. + +Risks: Overused. Can read as listicle filler. + +When to use: When the content genuinely is a list and the count matters. + +--- + +## Pattern 7: Time-bound / urgency + +Signals the email is time-sensitive. + +Examples: +- "Last day: free shipping on your order" +- "Webinar starts in 2 hours" +- "Pricing changes Thursday" + +Strengths: Drives immediate action. + +Risks: Overuse trains subscribers to ignore urgency cues. Reserve for genuine deadlines. + +When to use: Real time-sensitive sends only. Never fake urgency. + +--- + +## Pattern 8: News / update + +States what's new. + +Examples: +- "New: instant export to spreadsheets" +- "Just launched: team mode" +- "Update on the integration you asked for" + +Strengths: Useful for product update emails. + +When to use: Real product announcements that the recipient signed up to hear about. + +--- + +## Pattern 9: Personal anecdote / story + +Hints at a story. + +Examples: +- "I almost didn't ship this" +- "What happened when we tried [thing]" +- "The phone call that changed our hiring process" + +Strengths: Strong for narrative-driven brand newsletters. + +When to use: When the brand voice supports storytelling. + +--- + +## Pattern 10: Reference to recipient's behavior + +Acknowledges what they did. + +Examples: +- "Saw you tried [feature] - here's what's next" +- "Welcome back. Here's what you missed." +- "You completed week 1. Here's week 2." + +Strengths: Personalization that actually feels personal. + +When to use: Behavior-triggered emails. Lifecycle and onboarding sequences. + +--- + +## Subject lines by sequence type + +### Welcome / onboarding + +``` +Email 1: Welcome to [Brand], [name] +Email 2: The first thing to do in [Brand] +Email 3: How [audience] use [Brand] (3 examples) +Email 4: Did this happen for you? +Email 5: 30 days in: where you could be +``` + +### Lifecycle / activation + +``` +Trigger: completed milestone +"Nice work hitting [milestone]. Here's what's next." + +Trigger: stalled on a step +"Quick question about your setup" +``` + +### Re-engagement / win-back + +``` +Email 1: Hey [name], we miss you +Email 2: Here's [specific incentive] +Email 3: Last email - should we say goodbye? +``` + +### Newsletter + +``` +Curiosity: "The metric most teams ignore" +Specific: "September wrap: what we shipped, what we learned" +Question: "Should you raise your prices?" +Number: "3 reads from this week" +``` + +### Transactional + +``` +"Your order is on the way (#12345)" +"Receipt for your subscription" +"Your password was changed" +"Action required: confirm your email" +``` + +### Broadcast + +``` +Launch: "Just shipped: [feature]" +Event: "Live this Thursday: [topic]" +Update: "Our pricing changed today. Here's what it means for you." +``` + +--- + +## A/B test ideas + +Subject lines are the easiest thing to test. For any meaningful send, generate 2 to 4 variations along these axes: + +- Specific vs. curiosity: Does the audience prefer to know what they're getting, or to be intrigued? +- Personal vs. direct: Does first-person ("I just shipped this") work better than third-person ("Just launched")? +- Length: Short (under 30 chars) vs. medium (30 to 50 chars). +- Punctuation: Question vs. statement. +- Personalization: With name vs. without. + +Track open rates and click-through rates. Open alone is incomplete; some subject patterns get opened but discarded. + +--- + +## What to avoid + +### "Just checking in" +Empty. Adds no value. Reads as nag. + +### "Following up" +Same problem. The reader knows you're following up. Tell them why. + +### "Thoughts?" +A request without context. Comes across as lazy. + +### "Hi" +Just don't. Even from someone you know. + +### Excessive emojis +🎉🚀✨ does not signal value. Often signals spam to filters. + +### Re: when it's not actually a reply +Deceptive. Damages trust. + +### Personalization gone wrong +"{first_name} wanted to chat" with the variable un-rendered. Test send before broadcast. + +--- + +## Preview text (preheader) + +The line that appears next to or below the subject. Often more important than the subject for engagement. + +Best practice: +- Use it as the subject's continuation +- 50 to 90 characters +- Don't waste it on "View in browser" or boilerplate +- Add the detail the subject didn't fit + +Examples of subject + preview pairs: + +\| Subject \| Preview \| +\|---\|---\| +\| "Your week 1 progress" \| "3 of 5 steps complete. Here's what's next." \| +\| "The mistake most teams make" \| "(It's not the obvious one)" \| +\| "Just shipped: team mode" \| "Invite up to 50 teammates and assign roles." \| + +A weak preview wastes prime real estate. A strong preview can save a mediocre subject. diff --git a/skills/evidence-based-reviews/SKILL.md b/skills/evidence-based-reviews/SKILL.md new file mode 100644 index 0000000..5f0a4f2 --- /dev/null +++ b/skills/evidence-based-reviews/SKILL.md @@ -0,0 +1,161 @@ +--- +name: evidence-based-reviews +description: "Produce honest product reviews and buying guides without fabricated first-hand experience, using disclosed evidence tiers: verified specs, owner-experience synthesis at scale, expert triangulation, and hands-on only when true. Use this skill whenever the user wants to write product reviews or buying guides without hands-on access, set up a review methodology, add evidence disclosure to review content, align reviews with Google's reviews system or FTC affiliate disclosure expectations, or decide when Review and Product schema are honest to use. Triggers on product review, buying guide, best-of list, review methodology, evidence basis, hands-on testing, we tested, affiliate review site, review disclosure, methodology block, original research, reviews system. Also triggers when review content claims testing that did not happen, or when an affiliate site needs a trust mechanism that survives scrutiny." +category: content +catalog_summary: "Evidence tiers, methodology disclosure, honest review claims" +display_order: 13 +--- + +# Evidence-Based Reviews + +Produce product reviews and buying guides whose claims match their evidence. The method is evidence synthesis with a disclosed basis, and one rule anchors everything: never claim hands-on time that did not happen. + +Most review sites fail this rule quietly. "We tested" appears above content assembled from spec sheets, and readers have learned to smell it. The honest alternative is stronger, not weaker: synthesis of owner experience at scale, verified specifications, and triangulated expert sources is demonstrable original analysis, and disclosing it builds the trust that fabricated testing destroys. + +--- + +## When to use + +- Writing product reviews or buying guides when hands-on access is partial or absent +- Setting up the review methodology for a new review or affiliate site +- Adding evidence disclosure to existing review content +- Auditing review content for claims its evidence cannot support +- Deciding whether Review or Product schema is honest for a given piece +- Aligning review content with Google's reviews system and FTC disclosure expectations + +## When NOT to use + +- General content writing and editing (use `content-and-copy`; this skill governs the evidence and claims layer of review content specifically) +- Defining how the brand sounds (use `brand-voice`) +- Optimizing the review page itself for search (use `seo-onpage`) +- Per-piece editorial briefs (use `content-brief-authoring`) +- Instructional how-to content that teaches a procedure or concept to a first-time reader, such as a tutorial or an explainer: a teaching piece of this kind is owned by its writing, its structure, and its search craft, with the evidence discipline riding alongside as a constraint on its claims, so this skill is one input among several rather than the single choice for it + +If genuine hands-on testing at scale exists, with instrumentation and protocols, this skill still applies: the tiers do not change, the methodology block simply states tier 4 and the testing protocol becomes the disclosed basis. + +--- + +## Required inputs + +- The product category and the pieces planned (reviews, buying guides, or both) +- Access to evidence sources: manufacturer pages, retailer review corpora, forums or owner communities, expert publications +- The brand's disclosure language, if one exists (this skill supplies a template if not) +- An honest inventory of what hands-on experience genuinely exists, if any + +--- + +## The framework: one rule, four evidence tiers + +The anchor rule: never claim hands-on time that did not happen. Every other part of the method exists to make honest content strong enough that the lie is unnecessary. + +### Tier 1: verified manufacturer specs + +Specifications cited to the maker's own page, not to aggregator copies that drift. The verification step is the work: cross-check the spec against the manufacturer's current listing, note the date, and flag discrepancies between sources instead of picking one silently. A spec table built this way is a fact layer; a spec table pasted from another review site is a rumor layer. + +When it suffices: factual comparisons, fit and compatibility answers, price-tier groupings. It never supports a quality verdict on its own. + +### Tier 2: owner-experience synthesis at scale + +Retailer review corpora, forum threads, warranty and return patterns, read across sources and summarized honestly. Honest synthesis means: + +- Recurring complaints and recurring praise, not the loudest single anecdote +- Sample-size candor: "across roughly 1,400 owner reviews" reads differently from "owners say," and the reader deserves the number +- No cherry-picking: if owners split, the split is the finding +- Source naming: which corpora, which communities, over what period + +When it suffices: durability and reliability verdicts, real-world quirks specs never show, satisfaction patterns by use case. This tier is the workhorse of honest no-hands-on reviewing, and it is genuine original analysis when done at scale. + +### Tier 3: expert-source triangulation + +Named expert sources compared against each other. Triangulation means surfacing agreement and disagreement, not averaging verdicts into mush. When two credible testers reach opposite conclusions, the honest move is to say so and explain the conditions that might account for it. Anonymous "experts agree" is not a tier; it is decoration. + +When it suffices: performance claims that require instrumentation the site lacks, technique-dependent judgments, category context. + +### Tier 4: hands-on, only when true + +Stated only when it happened, flagged as such, with the extent quantified: what was done, how much, under what conditions. When hands-on experience arrives later for a piece published on tiers 1 to 3, the piece is upgraded and the update is marked with what changed. Never backfilled to look like it was always hands-on; the upgrade trail is itself a trust signal. + +--- + +## The methodology block + +Every review and buying guide carries a short disclosure block naming its evidence basis, placed with the criteria, written for readers rather than lawyers. The fillable template and a worked example live in [`references/methodology-block-template.md`](references/methodology-block-template.md). + +The block names: the criteria in the order they were weighted, the tiers actually used (specifically, with sources), what was done hands-on or the words "none claimed," and the update line. A block that claims a tier the piece did not use is the same lie the anchor rule bans, in smaller type. + +--- + +## Structure discipline the method implies + +- Criteria stated and ordered before picks. A verdict the reader cannot trace to a stated criterion is an opinion wearing a methodology costume. +- A named drawback per recommended pick. Every product has one; a review that finds none has not looked. Consistent placement makes the honesty visible. +- Update transparency. Dated updates with what changed. Stale best-of content silently rotting is one of the most common failures in the category, and a dated what-changed line beats the field. + +--- + +## Google reviews-system alignment + +The guidance asks for demonstrated first-hand experience OR demonstrable original research and analysis. The second branch is this skill's lane, and "original analysis" means concrete work product: + +- The synthesis itself: owner-experience patterns no single source contains +- Comparative tables built from verified data, structured around the stated criteria +- Decision frameworks: who each pick fits and who it does not +- What paraphrased spec sheets are not: rearranging a manufacturer's bullet points is neither experience nor analysis, and ranks accordingly + +A site that does tier 2 and 3 work honestly is doing original analysis by the guidance's own definition. The methodology block is how the work shows. + +--- + +## FTC alignment + +Affiliate relationships are disclosed in plain language, placed where the recommendation is, not in a footer. The disclosure travels with the monetized content: near the picks, in body-size text, before or beside the first affiliate link a reader can act on. "Plain language" means a reader who has never heard the word affiliate understands that the site earns a commission and that the price they pay does not change. Euphemisms ("partner links," "support the site") fail the plain-language test. + +--- + +## Schema judgment + +Markup is a claim. Apply the same honesty to structured data as to prose: + +- Review and Product markup only when the piece's claims support what the markup asserts. Review markup asserts an evaluative review of an item the reviewer assessed; a tier 1-to-3 buying guide asserting hands-on style review markup is making a machine-readable version of the banned claim. +- Buying guides without hands-on use guide-shaped markup: ItemList for the picks, Article for the piece. +- When tier 4 is real and stated, Review markup becomes honest; add it then, per piece, not as a template default. + +--- + +## Workflow + +1. Inventory the evidence honestly. What tiers are actually available for this category? What hands-on exists, if any? +2. Set the criteria first. Ordered, before any product is examined, so the criteria cannot quietly bend toward a favored pick. +3. Gather per tier. Verify specs at the source. Pull owner corpora at scale and note sample sizes. Collect named expert sources, including the disagreements. +4. Synthesize. Findings per criterion, drawbacks per pick, splits surfaced. +5. Write the methodology block from what was actually done, not from what sounds good. +6. Match the markup to the claims. ItemList and Article by default; Review only where tier 4 is true. +7. Maintain. Date updates, state what changed, upgrade pieces when hands-on arrives, and mark the upgrade. + +--- + +## Failure patterns + +- "We tested" inflation. The anchor-rule violation. It is also unnecessary: honest synthesis outperforms fake testing once readers compare the work. +- Aggregator specs. Spec tables copied from other reviews, drift included. Verify at the maker's page or do not publish the number. +- Anecdote dressed as synthesis. Three forum posts is not owner experience at scale. State the sample or downgrade the claim. +- Averaged experts. Splitting the difference between conflicting expert verdicts erases the most useful information: that credible testers disagree, and why. +- The drawback-free pick. A recommendation with no named drawback reads as advertising because it is structured like advertising. +- Backfilled hands-on. Quietly rewriting an old synthesis piece as if it had been tested all along. The upgrade-and-mark pattern exists so this never has to happen. +- Footer disclosure. An affiliate disclosure the reader has to hunt for fails both the FTC's placement expectations and the trust purpose it exists to serve. +- Schema overreach. Review markup on synthesis content. The piece's prose is honest and its markup lies. + +--- + +## Output format + +For a methodology setup: a short methodology standard the site adopts (the tiers, the block template filled with the site's sources, the schema policy), suitable for docs or an editorial guide. + +For a piece-level engagement: the methodology block for that piece, the criteria list, the evidence file (sources gathered per tier with sample sizes), and the claims audit if the piece existed before this skill did. + +--- + +## Reference files + +- [`references/evidence-tiers.md`](references/evidence-tiers.md) - The four tiers in depth: verification steps, synthesis honesty, triangulation practice, and the upgrade-and-mark pattern. +- [`references/methodology-block-template.md`](references/methodology-block-template.md) - The fillable per-piece disclosure block, a worked example, and placement rules. diff --git a/skills/evidence-based-reviews/references/evidence-tiers.md b/skills/evidence-based-reviews/references/evidence-tiers.md new file mode 100644 index 0000000..b348f67 --- /dev/null +++ b/skills/evidence-based-reviews/references/evidence-tiers.md @@ -0,0 +1,46 @@ +# The four evidence tiers, in depth + +The tiers are not a ladder of prestige; they are different kinds of knowledge with different verification work and different claims they can support. A strong piece usually combines two or three, and says which. + +## Tier 1: verified manufacturer specs + +The verification step. Cite the specification to the manufacturer's own current product page. Aggregators, retailer listings, and other reviews drift: units get converted wrong, superseded model years linger, and one site's typo becomes the category's consensus number. When the manufacturer's page and a retailer listing disagree, note the discrepancy in the piece; the disagreement is information. + +Date the pull. Specs change across model years. A spec table that says when its numbers were verified survives the next revision; one that does not becomes silently wrong. + +What tier 1 supports: factual comparison (weights, dimensions, capacities, materials), compatibility and fit answers, price-tier groupings. What it cannot support: any quality verdict. A spec sheet cannot tell you the thing rattles. + +## Tier 2: owner-experience synthesis at scale + +The workhorse tier for review work without hands-on access, and the one most often done dishonestly. The honest version: + +Scale and candor. Read across sources: retailer review corpora, owner forums, warranty and return discussions. State the scale in the piece ("across roughly 1,400 retailer reviews and two seasons of forum threads"). If the sample is small, say so and weaken the claim to match. + +Recurrence over volume. The finding is the pattern that recurs across independent sources, not the most dramatic single report. One catastrophic failure post is an anecdote; the same failure described by unrelated owners across two sites is a finding. + +Splits are findings. When owners divide (half love the trigger, half send it back), the split is the most useful thing the piece can report, usually with the variable that explains it (hand size, draw weight, use case). + +No cherry-picking. Deciding the verdict first and quoting only supporting owners is fabrication with extra steps. The synthesis is written from the pattern, not toward a pick. + +Name the corpora. Which retailers, which communities, what period. This is what makes the synthesis auditable and what makes it original analysis rather than vibes. + +## Tier 3: expert-source triangulation + +Named sources only. "Experts agree" without names is decoration. Name the publication or tester, and link where possible. + +Triangulate, never average. Three credible sources agreeing is strong signal; two credible sources disagreeing is stronger content. Surface the disagreement and look for the condition that explains it: different test protocols, different units, different use assumptions. Averaging opposite verdicts into "mixed reviews" throws away exactly what the reader came for. + +Independence check. Three reviews that all trace to the same press kit are one source wearing three hats. + +## Tier 4: hands-on, only when true + +Quantify the experience. "We shot it" hides more than it tells. The honest form states extent and conditions: how many arrows or hours or miles, over what period, in what setting, with what comparison points. The quantification is what separates a real claim from a vibe. + +Flag it. On a site where synthesis is the norm, hands-on time is the exception worth marking. Flagging it does double duty: it strengthens the piece that has it and keeps every other piece honest by contrast. + +The upgrade-and-mark pattern. When hands-on experience arrives for a piece originally published on tiers 1 to 3: + +1. Update the piece with the hands-on findings. +2. Update the methodology block: the hands-on line changes from "none claimed" to the quantified statement. +3. Mark the update with the date and what changed ("Updated [date]: added hands-on findings after six weeks with the production unit; the durability verdict held, the comfort note changed"). +4. Never rewrite history. The piece does not pretend it was always hands-on; the visible upgrade is itself evidence the site's claims mean something. diff --git a/skills/evidence-based-reviews/references/methodology-block-template.md b/skills/evidence-based-reviews/references/methodology-block-template.md new file mode 100644 index 0000000..7ac4b6b --- /dev/null +++ b/skills/evidence-based-reviews/references/methodology-block-template.md @@ -0,0 +1,33 @@ +# The methodology block: template, example, placement + +The per-piece disclosure block. Short, placed with the criteria, written for readers. It names what the piece's verdicts rest on, and it never claims a tier the piece did not use. + +## The template + +> How we reviewed this +> Criteria: [the 3 to 5 criteria, in the order they were weighted, stated before the picks]. +> Evidence: [the tiers actually used, specifically: verified manufacturer specs (noting where and when); owner-experience synthesis at scale (name the corpora and the rough sample size); expert-source triangulation (name the sources)]. +> Hands-on: [what was physically done, quantified, or the words "none claimed for this piece"]. +> Updated: [date]: [what changed and why]. + +## A worked example (generic category) + +> How we reviewed this +> Criteria: noise under load, durability across a season, build quality, price against the field, in that order. +> Evidence: manufacturer specs verified against each maker's current product page (May 2026); owner-experience synthesis across roughly 1,400 retailer reviews and two seasons of forum threads from three owner communities; expert triangulation across two named publications, whose durability verdicts disagreed (the disagreement and the likely cause are discussed under pick 2). +> Hands-on: none claimed for this piece. +> Updated: June 2026: replaced the budget pick after recurring owner reports of a failed adjustment mechanism; previous pick moved to the skip-it section with the evidence. + +## Placement rules + +- The block sits with the criteria, before or immediately after the picks summary, never below the fold of a long piece and never in a footer. +- Body-size text. A disclosure styled to be skipped is a disclosure in name only. +- The hands-on line is mandatory even when the answer is "none claimed." The absence stated plainly is the trust mechanism; the absence omitted is the lie of implication. +- The affiliate disclosure is a sibling, not a substitute: it travels with the recommendation per FTC expectations and says in plain language that the site earns a commission and that the reader's price does not change. The methodology block discloses the evidence; the affiliate block discloses the money. A piece with affiliate links carries both. + +## Anti-patterns + +- A block that lists every tier the site has ever used instead of the tiers this piece used. +- "Extensive research" as the evidence line. Name the corpora or do not claim the scale. +- A block written in legal register. The reader should finish it trusting the piece more, not feeling warned. +- The block as template default with fields unfilled. An unfilled block is a claim generator; every line must be true per piece. diff --git a/skills/experiment-design/SKILL.md b/skills/experiment-design/SKILL.md new file mode 100644 index 0000000..c858add --- /dev/null +++ b/skills/experiment-design/SKILL.md @@ -0,0 +1,255 @@ +--- +name: experiment-design +description: A discipline for designing experiments (A/B tests, multivariate, holdouts) so the results actually answer the question you asked. Hypothesis writing, sample size, duration, segment analysis, interpretation, decision-making, and the common failure modes that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Hypothesis to decision: sample size, duration, segment analysis, interpretation, and the failure modes that produce wrong shipping calls" +display_order: 4 +--- + +# Experiment Design + +A senior product manager's playbook for running experiments that produce trustworthy decisions. + +The default state of experimentation in most companies is sloppy. PMs run tests against vague hypotheses, look at results too early, ignore guardrails, stratify into noise, and ship features whose lift is mostly measurement error. The cost is real: ship the wrong thing, kill the right thing, learn the wrong lesson, repeat. + +This skill is the discipline that prevents most of those mistakes. It assumes you have a working experimentation platform (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon; the platform does not matter for the principles). It assumes you have product-design and engineering pipelines that can deliver real treatment changes. The hard part is the thinking, and that is what is here. + +When to use this skill: any time you are about to design or interpret an experiment. Read the relevant section before you start, not after the test is running. + +--- + +## What this skill covers + +The skill spans the full experiment lifecycle. Pre-experiment readiness (is this thing even worth testing). Hypothesis design (cause, effect, magnitude, mechanism). Sample size and minimum detectable effect (do you have enough traffic to learn anything). Duration (how long is long enough, when does the cycle bias the result). Running discipline (no peeking, guardrails, sequential testing). Interpretation (the three buckets and the inconclusive case). Decision-making (matching the result to a pre-committed rule). + +The skill does not cover feature flag operational mechanics; those live in the `feature-flagging` skill, which handles flag taxonomy, environment management, and stale-flag cleanup as a separate discipline. The skill does not cover statistical analysis depth; for delta methods, variance reduction techniques like CUPED, and Bayesian alternatives, see the `experimentation-analytics` skill. The skill does not cover platform-specific tooling; for MCP commands, auth models, and platform-specific configuration, consult the chosen platform's official documentation. This skill produces the experiment design; the platform implements it. + +For the orchestration layer above (which experiments to run, in what order, with what cadence), see the forthcoming `experimentation-platform-orchestrator` skill. That skill schedules; this skill designs. + +--- + +## The framework: 12 considerations for trustworthy experiment results + +A defensible experiment design sits at the intersection of twelve considerations. Each is covered in detail in its own section below. + +1. Hypothesis discipline. Cause, effect, magnitude, and mechanism. The hypothesis names what is being tested, what should move, by how much, and why. +2. Sample size and minimum detectable effect (MDE). Whether the test has enough traffic to detect the effect at the chosen power. Refuse to run underpowered tests. +3. Test duration. Longer of the sample-size-hit duration and a full weekly cycle. UI/UX changes need at least 14 days regardless. +4. What NOT to A/B test. UX bugs, legal-required changes, brand-philosophy questions, decisions already made, designs whose randomization cannot be clean. +5. Segment analysis. Pre-registered segments are evidence; post-hoc segments are noise mining. The multiple comparisons problem is real. +6. Interaction effects. Concurrent tests on the same surface can interfere. Mutex enforcement or coordination required. +7. Ratio metrics and variance estimation. Naive variance estimators on ratios understate uncertainty. Confirm the platform uses a ratio-aware estimator. +8. Network effects and two-sided markets. Treatment can leak into control via interference. Cluster randomization, switchback, or geographic isolation when needed. +9. Sequential testing and the peeking problem. Daily peeking inflates false positive rates. Use sequential testing methods when available; pre-commit otherwise. +10. Pre-commitment vs p-hacking. Write down the primary metric, MDE, duration, segments, and decision rule before launch. Apply mechanically when results come in. +11. Reading results and making the call. Three buckets: clear win, clear loss, inconclusive. The inconclusive bucket exists for a reason; resist the pull to ship anyway. +12. Common failures and fixes. A short rapid-fire pattern catalog, expanded in [`references/common-failures.md`](references/common-failures.md). + +The sections below cover each consideration in turn. Read the relevant section before running the experiment, not after. + +--- + +## Hypothesis discipline + +The most important section in the skill. Most experiment failures trace back to a vague hypothesis. + +A real hypothesis has four parts: cause, effect, magnitude, mechanism. Cause is the change you are making. Effect is the metric you expect to move. Magnitude is how much you expect it to move and from what baseline. Mechanism is why you expect this change to produce this effect. + +Bad hypothesis, common shape: "We think the new pricing page will increase conversions." What is wrong with it: no magnitude (how much), no mechanism (why), and the metric is "conversions" rather than a specific event with a clear definition. The team will run this test, look at the result, and argue about what counts as a win. Pre-commitment is impossible because nothing was committed. + +Good hypothesis, same domain: "Replacing the three-tier pricing comparison with a single recommended tier will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe." Cause is the tier replacement. Effect is signup-to-paid conversion, defined as the user reaches the paywall and completes payment within seven days. Magnitude is 8 percent relative lift, taking the rate from 12 to 13 percent absolute. Mechanism is decision friction reduction. Now the team has something to test, a number to hit, and a story to falsify. + +Primary metric vs guardrails. The primary metric is the thing you are trying to move. Guardrails are the things that must not break: revenue, retention, support ticket volume, page load time, error rates. Pick exactly one primary metric. Pick three to five guardrails. Multiple primary metrics destroy the discipline because they let you cherry-pick the favorable one when results come in. + +Falsifiability test. Before launching the experiment, write down what would make you NOT ship this. If the answer is "nothing, we are committed to the change regardless," the hypothesis is not real and the experiment is theater. Skip the test, save the engineering time, and just ship the change. + +Directional vs magnitude distinction. Knowing the change moves the needle is different from knowing it moves the needle enough to matter. A 0.3 percent absolute lift on signup conversion may be statistically significant with enough traffic and still not justify the engineering cost of maintaining the change. Magnitude matters as much as direction; the hypothesis names the magnitude that would justify shipping. + +For templates and worked examples across common metric types, see [`references/hypothesis-templates.md`](references/hypothesis-templates.md). + +--- + +## Sample size and minimum detectable effect + +Sample size grows with the inverse square of the effect you want to detect. Detecting a 1 percent lift requires roughly one hundred times the sample needed to detect a 10 percent lift. Most PMs underestimate this. + +The basic decision rule: if your minimum detectable effect (MDE) at current traffic and a reasonable test duration is greater than 5 percent absolute lift, you probably need a bigger MDE. Tiny changes that need huge samples to detect are usually not worth shipping anyway. The change is small either because the underlying mechanism is weak or because the implementation is timid. A weak mechanism is not worth a launch. A timid implementation should be made bolder before testing. + +The "we do not have enough traffic" trap. Real for very small products. Lazy for everyone else. If you have ten thousand users a week and you are trying to detect a half-percent absolute lift, you are not running an experiment, you are sampling noise. Pick changes whose expected effect is large enough to detect at your traffic level. If the change is genuinely small, ship it without a test (small upside, small downside, low cost) or do not ship it at all. + +Power. The test's ability to detect an effect that is actually present. The conventional floor is 80 percent. Below that, you are rolling dice; the test will frequently miss real effects. Higher power costs more sample. Most platforms default to 80; if you change it, document why. + +One-sided vs two-sided. Most PM tests are two-sided despite the temptation to claim otherwise. A one-sided test says "I only care about the positive direction; if the change makes things worse, I do not need to detect it." That is rarely true. If the new pricing page tanks conversion, you want to know. Default to two-sided. If you genuinely want one-sided, document the asymmetry before running. + +For pre-calculated sample size tables across common conversion rate baselines and MDEs, see [`references/sample-size-tables.md`](references/sample-size-tables.md). The tables are starting points, not substitutes for running the math against your specific traffic and metric. + +--- + +## Test duration + +Minimum duration is the longer of two constraints. Constraint one: the sample size hits the calculated requirement. Constraint two: the test runs at least one full weekly cycle. Testing only Monday through Wednesday misses weekend behavior, which on most consumer products differs meaningfully from weekday behavior. + +Novelty effects. New things attract attention. The first few days of a winning test often overstate the lift. Users notice the change, click it, and produce a temporary effect that fades as the novelty wears off. Run long enough to see if the lift survives the novelty period. Two weeks is the conventional minimum for any UI/UX experiment, even if the sample size hits faster. + +Primacy effects. The opposite problem. Existing users may resist the change in week one and adapt by week three. Common in UI rearrangement tests. Killing the test in week one because the result looks negative misses the point that primacy is bigger than the underlying effect at that timescale. + +Holdout periods. If the experiment changes a permanent feature (notification frequency, default settings, search ranking), keep a holdout group OFF the new behavior for at least a month after launch. The holdout measures long-term effect, not just the day-1 lift. Long-term effects are often different from short-term effects: a notification change that increases day-1 engagement may decrease month-three retention. + +Maximum duration. Usually four to six weeks. Beyond that, the world changes around the test. Seasonality shifts. Marketing campaigns launch. The product evolves. The comparison between treatment and control stops being clean because the underlying user population is no longer comparable across the test window. If the test needs to run longer than six weeks to hit power, the MDE is probably wrong; the change is too small to detect cleanly. + +--- + +## What NOT to A/B test + +This is a section many discussions of experimentation skip. Worth being direct about. + +UX bug fixes. If the current behavior is objectively broken (button does not work, copy says the wrong thing, accessibility fails), fix it. A/B testing it is theater. The right answer is not "let's see if our users prefer a working button"; the right answer is to ship the working button. + +Legal-required changes. GDPR consent flows, accessibility compliance, regulatory disclaimers. Ship them. The lift is irrelevant; the compliance is the point. A/B testing whether to comply with the law is not a serious question. + +Strategic or philosophical brand questions. "Should our voice be playful or serious?" is not an A/B test question; it is a brand strategy question that needs to be made by humans with context, weighed against brand equity, audience expectation, and long-term positioning. Picking the variant with the higher click-through rate does not answer it because click-through rate was not the brand decision. Use the experiment data as one input to the brand decision, not as the decision itself. + +Things you have already decided. If leadership has committed to a direction regardless of test result, do not run an experiment. A/B testing as theater (running tests where the outcome does not change the decision) corrodes trust in the experimentation discipline overall. Other PMs see the test, see the result ignored, and conclude that experiment results do not matter at this company. Then they stop pre-committing. Then the discipline collapses. + +Things where the test design is impossible. Cross-device experiences, network effects, internal tooling for a ten-person ops team, anything where the sample size is fundamentally too small or the randomization is fundamentally contaminated. Sometimes the right answer is qualitative research, longitudinal cohort analysis, or just shipping and watching. An experiment that cannot be designed cleanly will not produce a clean answer. + +--- + +## Segment analysis + +Pre-registered segments versus post-hoc segments. Declaring before the test runs that "we will look at the result for new users versus returning users" is fine. Discovering after the test that "users from California who signed up on Tuesdays via mobile" had a huge lift is almost always noise mining. + +The multiple comparisons problem. Every additional segment you analyze increases the probability of finding a "significant" result by chance. With twenty independent segments at p equals 0.05, you expect one false positive purely by chance. With fifty segments, two or three. Do not analyze fifty segments and report the one that hit significance. + +When stratification helps versus misleads. Stratification is useful when three things are true. The segment was pre-registered. There is a real prior reason to expect different behavior in this segment. There is enough sample within the segment to detect the effect at the chosen power. If any of the three is missing, stratification is noise mining. The default posture should be: report the overall result. Report pre-registered segments as additional context. Do not report unplanned segments. + +The "weighted average" reframe. If a treatment is positive for one segment and negative for another, the right question is "what is the weighted average effect across the population we will actually ship to" not "let's just ship to the segment where it works." Shipping to a segment usually requires UI complexity, audience targeting infrastructure, and ongoing maintenance that the segment-specific lift does not justify. The bias against segment-specific shipping is healthy. + +--- + +## Interaction effects + +The classic problem: you are running five concurrent A/B tests on the checkout flow. Each test individually shows a small lift. Together, the combinations may not multiply cleanly. They may not even sum cleanly. They may interfere in ways the individual tests cannot reveal. + +Pre-experiment hygiene. Before launching a new experiment, check what other experiments are running on the same surface. Ask the other PM owners. Coordinate on which tests are mutually exclusive and which can overlap. + +Mutex (mutually exclusive) experiment groups. Most platforms support exclusion rules so users in test A are not also in test B. Use them when interactions are likely. The cost is sample size; the benefit is interpretable results. For a small set of high-stakes tests, mutex is the right call. For dozens of lower-stakes tests, full mutex is impractical; coordinate and document overlap instead. + +The "we will analyze it later" fallacy. Post-hoc detangling of overlapping experiments is hard, expensive, and usually inconclusive. The factorial design that would isolate interaction effects requires sample sizes most products do not have. Coordinate up front rather than untangle afterwards. + +--- + +## Ratio metrics and the delta method + +The trap. Conversion rate is a ratio: conversions divided by users. Standard deviation calculations for raw counts do not apply directly to ratios. A naive variance estimate on a ratio metric tends to be too narrow, leading to overstated confidence and false-positive ship decisions. + +Why it matters. Many experimentation platforms quietly use the delta method (or bootstrap, or some other ratio-aware estimator) for ratio metrics. If yours does not, your confidence intervals are wrong. Wrong in the direction that matters: you ship things that look significant but are not. + +How to check. Ask your platform vendor: "What is your variance estimator for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (converted yes or no, with one row per user). If the answer is "delta method" or "bootstrap with re-sampling at the user level" or "linearization with Taylor expansion," that is correct. Other reasonable answers exist; the test is whether the platform team can articulate a ratio-aware estimator at all. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. RPU lift estimates that do not use a ratio-aware estimator tend to overstate confidence. A 5 percent reported lift with p equals 0.04 might actually be a 5 percent point estimate with no statistical significance once the variance is computed correctly. Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production. + +For deeper coverage of variance reduction (CUPED, stratified sampling, control variates), see the `experimentation-analytics` skill when it ships. + +--- + +## Network effects and two-sided markets + +The interference problem. In a two-sided marketplace (Uber, Airbnb, eBay, DoorDash, any platform with buyers and sellers), a treatment for buyers may affect sellers regardless of which group is in the test. A treatment that increases buyer demand changes seller behavior. The "control" buyers, who are competing for the same sellers, see different supply because of treatment buyers' actions. The test no longer measures the treatment effect cleanly; it measures treatment effect plus interference. + +Common pattern. Marketplace experiments where the control group is contaminated. The test reports a small effect because half the effect leaked into the control. The team underestimates the true effect, kills a winning idea, and learns the wrong lesson. + +Mitigations, none perfect. Cluster randomization assigns whole markets (cities, regions, market segments) to treatment or control rather than individual users. Eliminates within-cluster interference but reduces effective sample size by orders of magnitude. Switchback experiments alternate the entire population between treatment and control across time windows (week 1 treatment, week 2 control, week 3 treatment, etc.). Eliminates cross-user interference but requires careful temporal modeling. Geographic isolation runs the experiment in one city while keeping the rest of the network on the original behavior. Eliminates interference but is expensive and slow. + +When to call qualitative. If interference is severe and randomization cannot isolate it, the test will not tell you what you want to know. Switch to user research, longitudinal cohort analysis, or a phased rollout with careful instrumentation. The decision is "do we believe this works enough to invest in the rollout monitoring" rather than "did the lift hit significance." + +--- + +## Sequential testing and the peeking problem + +The peeking problem. If you check results every day and stop the test as soon as you see significance, your false positive rate is much higher than the nominal 5 percent. Standard statistical tests assume one analysis at the end of the test. Multiple analyses inflate alpha. + +The math. With one analysis, false positive rate is 5 percent (at alpha equals 0.05). With three analyses spread across the test, false positive rate climbs toward 14 percent. With daily peeking on a 28-day test, false positive rate can exceed 30 percent. You will see "significant" results that are not real, ship them, and watch them fail to replicate in production. + +Sequential testing methods. Most modern platforms (Statsig, Eppo, parts of PostHog, GrowthBook with mSPRT) support sequential testing that adjusts the math to allow daily peeking without inflating alpha. The methods include sequential probability ratio tests, group sequential designs, and always-valid p-values via mixture sequential probability ratio tests (mSPRT). Use them when the platform offers them. They cost some statistical power in exchange for valid mid-test inference. + +Pre-registered stopping rules. If the platform does not support sequential testing, declare the planned analysis date before the test runs. Save the pre-commitment. Do not look at results until that date. If you must look (some platforms make it hard not to), do not make decisions based on what you see. The decision happens at the pre-committed analysis date, not when the early peek looks favorable. + +The "ship early because results look great" trap. Results almost always look more dramatic on day 3 than they do at day 14. Regression to the mean kicks in. Novelty fades. The metric stabilizes. The tests that survive the full window and still look great are the ones worth shipping. The ones that "looked great early" and were shipped early are disproportionately the ones that disappointed in production. + +--- + +## Pre-commitment vs p-hacking + +The p-hacking inventory. Things people do, often unconsciously, when results do not come out the way they hoped: + +- Run additional segments until something hits significance +- Drop "outliers" until the headline result moves +- Switch the primary metric mid-flight +- Extend the test duration "just a bit longer" +- Reframe the hypothesis to match what the data showed +- Combine multiple inconclusive tests into a "directional pattern" that justifies shipping + +Each individually feels like a small judgment call. Cumulatively they destroy the discipline. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +The pre-commitment fix. Before the test runs, write down: the primary metric and how it is computed; the MDE you are powered to detect; the duration in calendar days; the segments you will analyze (if any); the decision rule that maps each possible result to a ship or kill. Save the pre-commitment somewhere with a timestamp. The PR description that ships the experiment configuration. A signed Slack message. A pinned ticket. Anywhere that makes it immutable. + +When the results come in, follow the pre-commitment. If the result was clean and you want to ship, file the launch. If the result was bad and you want to kill, kill. If the result was inconclusive, follow the inconclusive resolution path described below; do not invent new analyses. + +The "we learned so much" trap. If the test ran and produced an inconclusive result, the answer is "inconclusive." Not "we learned that the underlying mechanism is more nuanced than expected" or "we discovered a fascinating segment dynamic." Inconclusive is inconclusive. The lesson, if there is one, is for the next hypothesis, not retrofitted onto this one. + +--- + +## Reading results and making the call + +Three buckets. Clear win: ship. Clear loss: kill. Inconclusive: the hardest case. + +Inconclusive resolution paths, ranked from most acceptable to least: + +1. Ship anyway because the change is cheap and reversible (defensible only if guardrails are clean and you genuinely have no information that the change is harmful). The bar here is high; "the directional movement was favorable" is not enough. +2. Run a bigger version: more traffic, longer duration, larger MDE if the change can be made bolder. Use the inconclusive result as evidence that the original was underpowered or the effect is smaller than expected. +3. Kill the idea. The most common right answer; the hardest to do because PMs have invested in the hypothesis. +4. Iterate the hypothesis and re-test. Use the inconclusive result to refine the mechanism. The new test is a new test, not a continuation; pre-commit again. + +Bayesian thinking layer. If your prior was strong (this should obviously work, given everything we know about user behavior), an inconclusive result should still update your belief somewhat. The prior was wrong, or the effect is smaller than expected, or the implementation was too timid to capture it. If your prior was weak (we genuinely had no idea what would happen), an inconclusive result means inconclusive; the prior was already uncertain and the result did not narrow it. + +The hardest version. Positive primary metric, ambiguous guardrail. Revenue went up but support tickets ticked up. Conversion went up but session length went down. Use the pre-committed decision rule. If you did not pre-commit on the guardrail trade-off, default to "do not ship." The guardrails exist because you cared about them before you saw the result. Do not lower the bar after the fact. + +For a step-by-step results-reading checklist, see [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). + +--- + +## Common failures and fixes + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-failures.md`](references/common-failures.md). + +- "We did not have enough traffic" means the MDE was too small. Pick bigger changes worth detecting. +- "The lift disappeared after launch" means the test ran for 5 days and caught a novelty effect. Run longer next time; minimum two weeks for UI changes. +- "It worked for new users but not returning users" means the segment was post-hoc, probably noise. Ship to all or kill, do not ship to the segment. +- "The p-value crept up to 0.04 after 12 days of peeking" means the false-positive rate is much higher than nominal. Pre-commit and use sequential testing. +- "Revenue went up but retention went down" means a guardrail was violated. Do not ship. +- "We cannot replicate the result" means the original was probably noise or platform-bug. Investigate before re-running. +- "Conversion went up but only because of the bot traffic from the new ad campaign" means the result was confounded by an external event. Pause campaigns during sensitive tests, or stratify by acquisition source. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped" means you ignored your own discipline. The inconclusive bucket exists for a reason; do not let directional patterns substitute for evidence. + +--- + +## Reference files + +- [`references/hypothesis-templates.md`](references/hypothesis-templates.md). Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test, with worked examples across conversion, engagement, revenue, retention, and funnel-step metric types. +- [`references/sample-size-tables.md`](references/sample-size-tables.md). Pre-calculated sample size tables for the most common conversion-rate experiments, with how-to-use guidance and the common pitfalls in sample-size planning. +- [`references/common-failures.md`](references/common-failures.md). Fifteen anti-patterns that produce wrong shipping decisions, each with symptom, root cause, fix, and prevention. +- [`references/results-interpretation-checklist.md`](references/results-interpretation-checklist.md). Step-by-step checklist for reading results, the three-bucket decision matrix (win, loss, inconclusive), and the post-launch monitoring discipline. +- [`references/platform-comparison.md`](references/platform-comparison.md). Profiles of the major experimentation platforms (Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon) with strengths, gotchas, and a decision matrix for choosing. +- [`references/pre-experiment-readiness-checklist.md`](references/pre-experiment-readiness-checklist.md). Ten-item go/no-go checklist run through before launch. +- [`references/post-experiment-decision-framework.md`](references/post-experiment-decision-framework.md). The moment-of-decision framework: confirm pre-commitment, apply rule mechanically, route to ship/kill/inconclusive paths, write the post-mortem within a week. + +--- + +## Closing: when in doubt + +Default conservative posture. When results are unclear, do not ship. The cost of a false negative (you did not ship a real win) is usually smaller than the cost of a false positive (you shipped something that does not actually work and now you have to maintain it forever). The maintenance cost compounds; the missed-opportunity cost does not, because you can always test again. + +The discipline of experiment design is the discipline of saying "I do not know" out loud when you do not know. Saying it is often the most consequential thing a PM does in a given week. The instinct is to pretend the result is more conclusive than it is, ship to look decisive, and absorb the failure quietly when the change does not work in production. The discipline is to say "the test was inconclusive, here is what I would change to get a real answer, here is the new test plan." Saying that is professional. Pretending otherwise is theater. + +For platform-specific patterns (which platform handles which experiment type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the operational layer below this skill (managing flags, retiring stale ones, coordinating environments), see the `feature-flagging` skill. For the analytical layer above this skill (variance reduction, Bayesian alternatives, sequential testing math), see the `experimentation-analytics` skill. diff --git a/skills/experiment-design/references/common-failures.md b/skills/experiment-design/references/common-failures.md new file mode 100644 index 0000000..ba75be0 --- /dev/null +++ b/skills/experiment-design/references/common-failures.md @@ -0,0 +1,183 @@ +# Common failures and fixes + +Anti-patterns that produce confidently wrong shipping decisions, with the symptom you observe, the root cause, the fix that resolves it, and the prevention that stops it from recurring. + +--- + +## 1. The vague hypothesis + +Symptom. "We think the new pricing page will increase conversions." The team runs the test, the result is ambiguous, and a heated meeting follows about whether to ship. + +Root cause. The hypothesis lacks magnitude and mechanism. When the result comes in, there is no pre-committed bar to compare against, so the decision becomes political. + +Fix. Rewrite the hypothesis with the cause-effect-magnitude-mechanism format from [SKILL.md](../SKILL.md). Save it before launching. + +Prevention. Make hypothesis review part of the experiment kickoff. A peer reads the hypothesis and confirms all four parts are present before the test launches. + +--- + +## 2. The novelty effect ship + +Symptom. Test ran for 5 days, lift looked great, the team shipped, and the lift disappeared in production within two weeks. + +Root cause. Users notice new things and click them disproportionately during the novelty window. The early lift was novelty, not durable preference. + +Fix. Re-test the change with at least a two-week test window. Most novelty effects fade in 7-10 days. If the lift survives 14 days, it is likely durable. + +Prevention. Set minimum test duration of 14 days for any UI/UX change, regardless of how fast sample size hits. Document the rule and enforce it. + +--- + +## 3. The post-hoc segment win + +Symptom. Test was inconclusive overall, but "users from California who signed up via mobile on Tuesdays" had a huge lift. The team wants to ship to that segment. + +Root cause. Multiple comparisons. With enough segments analyzed, one will hit "significance" by chance. The California-mobile-Tuesday segment is almost certainly noise. + +Fix. Do not ship to the segment. Either ship to all (if guardrails hold), or kill, or re-test with the segment pre-registered as a hypothesis. + +Prevention. Pre-register the segments to be analyzed. Limit to three to five segments per test, each with a real prior reason to differ from the population. + +--- + +## 4. The peeking creep + +Symptom. P-value drifted around 0.06 for the first week, then crept to 0.04 on day 12, the team called it significant and shipped. + +Root cause. The platform did not use sequential testing. Daily peeking inflated the false positive rate. The "significance" on day 12 was a peeking artifact. + +Fix. Either use a platform with sequential testing, or pre-commit to a single end-of-test analysis. If you peeked and the test is over, treat the result as inconclusive and consider rerunning. + +Prevention. If your platform supports sequential testing (mSPRT, group sequential), enable it. If not, set up the test with calendar reminders for the analysis date, not before. + +--- + +## 5. The guardrail violation overlook + +Symptom. Primary metric (revenue) went up. Retention dropped. The team shipped because revenue was the headline metric. + +Root cause. Guardrails were defined but not treated as binding. When the primary metric looked favorable, the team rationalized the guardrail violation as acceptable. + +Fix. Do not ship. Investigate the retention drop. The change may be capturing short-term revenue at the cost of long-term value, which is a worse trade than no change at all. + +Prevention. Pre-commit on the guardrail trade-off. Write down explicitly: "We will not ship if retention drops by more than X." If you cannot specify the bar in advance, you do not understand the trade-off well enough to test it. + +--- + +## 6. The non-replicable result + +Symptom. Test reported a 5 percent lift. The team shipped. A month later the same change tested with a holdout group shows no effect. + +Root cause. Could be many things: original test was a false positive, platform bug, external event during the test window, contamination. Without investigation, you do not know which. + +Fix. Stop, investigate, find the cause. Possible findings: the metric was computed differently in the test versus production; the test exposure was lower than reported; an unrelated change confounded the result. Do not "just rerun and hope." + +Prevention. Schedule a post-launch holdout test for any change with a reported lift greater than 3 percent. Confirm the production behavior matches the test before declaring the win. + +--- + +## 7. The campaign confound + +Symptom. Test launched the same week as a major marketing campaign. Test reported a huge lift. The team shipped. The lift was the campaign's traffic mix, not the treatment. + +Root cause. The campaign brought a different user mix into the test population: higher-intent visitors, different geographies, different device types. Treatment and control both saw the campaign traffic, but the campaign-driven users may have responded differently to the variants than the baseline population would. + +Fix. Pause campaigns during sensitive tests, or stratify the analysis by acquisition source so campaign traffic is analyzed separately from baseline traffic. + +Prevention. Coordinate with the marketing team before launching tests. Maintain a calendar of upcoming campaigns and avoid launching experiments on the same surfaces during major pushes. + +--- + +## 8. The directional ship + +Symptom. Test was inconclusive. Primary metric trended up but did not hit significance. The team shipped because "the trend was directional." + +Root cause. Directional trend without significance is noise that happens to point in a flattering direction. Treating it as evidence is exactly the discipline failure that erodes experimentation rigor. + +Fix. Do not ship based on directional trends. Either run a bigger test (more traffic, longer duration), kill, or accept inconclusive as the answer. + +Prevention. Pre-commit to the decision rule. "Inconclusive" as a category requires acceptance, not creative reframing. + +--- + +## 9. The interaction effect blind spot + +Symptom. Five concurrent tests on the checkout flow. Each individually reported a small lift. Combined, total checkout conversion did not move. + +Root cause. Interactions between concurrent tests. The lifts did not multiply or even sum. Some may have canceled out, some may have interfered with each other. + +Fix. Roll back, run tests with mutex enforcement, or run them sequentially. Re-test the combination as a multivariate. + +Prevention. Maintain an experiment registry per surface. Before launching a new test, check which others are running on the same surface and coordinate. Use mutex when interactions are likely. + +--- + +## 10. The selection bias ship + +Symptom. ARPU went up. The team shipped. After launch, MAU dropped because the lowest-revenue users churned. + +Root cause. The treatment caused selection: lower-value users left, higher-value users stayed. ARPU went up arithmetically because the denominator shrank, not because anyone made more money. + +Fix. Pair ARPU primary metrics with retention or MAU guardrails. Investigate the source of the lift before shipping. + +Prevention. When the primary metric is a ratio, always pair with absolute count guardrails. ARPU plus revenue. Conversion rate plus conversion count. Engagement rate plus DAU. + +--- + +## 11. The internal traffic contamination + +Symptom. Test reported strong lift in the first week. Investigation showed half the test users were internal employees clicking around the new feature. + +Root cause. Internal traffic was not excluded from the test population. Employees behave differently from real users. + +Fix. Re-bucket the test excluding internal IPs and employee accounts. Re-analyze. + +Prevention. Maintain an internal-traffic exclusion list at the platform level. Apply it to all experiments by default. Audit the user counts on test launch to confirm internal traffic is excluded. + +--- + +## 12. The metric definition mismatch + +Symptom. Test reported a 5 percent lift in "conversion." Production analytics reported a 0.5 percent lift. The team blamed the platform. + +Root cause. The conversion event was defined differently in the test platform versus production analytics. Different conversion windows, different deduplication rules, different user-identity logic. + +Fix. Reconcile the metric definitions before re-running. Document the canonical definition and confirm both systems produce matching numbers on a known historical period. + +Prevention. Maintain a metric dictionary. Before adding a metric to an experimentation platform, document the canonical definition and validate against production analytics. Treat the metric definition as a versioned artifact. + +--- + +## 13. The ratio metric variance error + +Symptom. Test reported a "significant" lift in revenue per user with p equals 0.04. Production rollout produced no measurable change. + +Root cause. The platform used a naive variance estimator on a ratio metric. Confidence interval was too narrow; the "significance" was an artifact of bad math. + +Fix. Switch to a platform that uses a ratio-aware estimator (delta method, bootstrap). Re-run the test or confirm via holdout. + +Prevention. Audit your platform's variance estimator. Ask the vendor what they use for ratio metrics. If the answer is "standard t-test on proportions" for anything other than simple binary conversion, plan a workaround. + +--- + +## 14. The "we will fix it later" rollout + +Symptom. Test was inconclusive but engineering had already deployed the change. Rolling back was hard. The team shipped because the cost of rollback was higher than the expected cost of shipping. + +Root cause. The rollout was not gated on the experiment result. Engineering shipped to production before the test had concluded. + +Fix. Roll back if possible. If not, accept the change is shipped and instrument production carefully to confirm whether it actually works. + +Prevention. Gate rollouts behind experiment conclusions. Use feature flags so the change can be toggled off without a code revert. Coordinate engineering schedules with experiment timelines. + +--- + +## 15. The retroactive hypothesis + +Symptom. Test was set up to validate "the new homepage increases signups." Result showed signups flat but engagement up. The team rewrote the hypothesis as "the new homepage drives engagement" and shipped. + +Root cause. Hypothesis was changed after the result was visible. This is p-hacking even if no statistical math was changed. + +Fix. The original hypothesis was inconclusive on signups. Either kill, or run a new test with the engagement hypothesis pre-registered. + +Prevention. Pre-commit the primary metric and stick with it. If the data suggests a different metric is more interesting, treat that as the hypothesis for the next test, not a rewrite of the current one. diff --git a/skills/experiment-design/references/hypothesis-templates.md b/skills/experiment-design/references/hypothesis-templates.md new file mode 100644 index 0000000..18e3584 --- /dev/null +++ b/skills/experiment-design/references/hypothesis-templates.md @@ -0,0 +1,95 @@ +# Hypothesis templates + +Concrete formats for writing hypotheses that pass the cause-effect-magnitude-mechanism test from [SKILL.md](../SKILL.md). Each template names the right shape, shows two or three worked examples in different domains, and calls out the most common mistakes specific to that template type. + +The unifying format across all templates: replace [bracketed slots] with concrete project-specific values. If a slot reads as a vague phrase after replacement, the hypothesis is not specific enough. + +--- + +## Template 1: Conversion rate change + +Format. Replacing [current treatment] with [new treatment] will increase [conversion event] by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +Worked example, e-commerce. Replacing the multi-step shipping selector with an inline shipping summary on the cart page will increase cart-to-purchase conversion by 6 percent (currently 14.2 percent, target 15.1 percent) by reducing the cognitive load at the moment users are deciding whether to complete checkout. + +Worked example, SaaS. Replacing the three-tier pricing comparison with a single recommended tier on the pricing page will increase signup-to-paid conversion by 8 percent (currently 12 percent, target 13 percent) by reducing decision friction for users who already know they want to subscribe. + +Worked example, marketplace. Replacing the "browse all categories" landing page with a personalized recommendation grid will increase landing-to-listing-click conversion by 12 percent (currently 18 percent, target 20.2 percent) by surfacing relevant inventory before users have to specify intent. + +Common mistakes specific to this template. +- Naming the metric as "conversions" without specifying the conversion event. "Conversion" alone is ambiguous; cart-to-purchase, signup-to-paid, and landing-to-listing-click are different metrics with different baselines and different relevant timescales. +- Stating relative lift without absolute. "10 percent lift" sounds bigger than "1 percent absolute lift on a 10 percent baseline" but is the same thing; state both so the reader knows what is being claimed. +- Skipping the mechanism. "Will increase conversion by 8 percent" is a target, not a hypothesis. The why is what makes it falsifiable. + +--- + +## Template 2: Engagement metric change (DAU, sessions, time-on-task) + +Format. Adding [new feature or affordance] will increase [engagement metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, content product. Adding a "save for later" button to article cards will increase weekly active users by 5 percent (currently 1.2 million, target 1.26 million) by giving users a reason to return to articles they have started reading. + +Worked example, productivity tool. Adding inline comments on document blocks will increase sessions per week per active team by 15 percent (currently 4.2, target 4.8) by enabling asynchronous collaboration that previously required separate communication channels. + +Common mistakes specific to this template. +- Engagement metrics are not always good. A feature that increases sessions but decreases task completion is making the product worse, not better. Pair engagement primary metrics with task-completion guardrails. +- "Time on task" is ambiguous. More time can mean engagement or confusion. Specify whether longer or shorter is the desired direction and why. +- Treating engagement lift as a leading indicator without evidence that it is. Increased DAU does not always lead to increased revenue; sometimes it lags it, sometimes it has no relationship. + +--- + +## Template 3: Revenue metric change (ARPU, AOV, RPU) + +Format. Implementing [new pricing or merchandising change] will increase [revenue metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, subscription product. Adding an annual prepay option at 10 percent discount will increase average revenue per user by 4 percent (currently $87, target $90.50) by shifting price-sensitive users from monthly to annual billing, which has lower churn. + +Worked example, e-commerce. Adding a "frequently bought together" bundle on product detail pages will increase average order value by 8 percent (currently $42, target $45.40) by surfacing relevant add-on items at the moment of purchase decision. + +Common mistakes specific to this template. +- Revenue is a ratio metric (revenue divided by users or orders). Naive variance estimators understate the variance and overstate confidence. Confirm your platform uses the delta method or an equivalent ratio-aware estimator. +- ARPU lifts can come from selection effects: if the treatment moves the lowest-revenue users away (they churn), ARPU goes up without anyone making more money. Pair ARPU primary metrics with retention guardrails. +- Revenue lifts can be driven by a small number of high-value users. Confidence intervals are wide. Run longer than you think you need to. + +--- + +## Template 4: Retention metric change + +Format. Changing [interaction or feature] will increase [retention metric] by [magnitude] (current [baseline], target [target]) by [mechanism]. + +Worked example, mobile app. Changing the day-3 push notification copy from generic to personalized recommendations will increase day-7 retention by 3 percent (currently 38 percent, target 39.1 percent) by reminding users of specific value they can return to. + +Worked example, SaaS onboarding. Replacing the static onboarding checklist with a guided in-product tour will increase day-30 active retention by 5 percent (currently 22 percent, target 23.1 percent) by getting more users to the activation event during their first session. + +Common mistakes specific to this template. +- Retention takes time to measure. A test of day-30 retention requires at least 30 days of treatment exposure plus the test duration. Plan accordingly. +- Day-N retention is a moving definition. Day-7 active means different things in different products; specify the activity that defines "active" before running. +- Retention lifts often shrink over time. A treatment that improves day-7 retention may have no effect on day-90 retention. Decide which timescale matters for the business and measure that, not just the convenient short one. + +--- + +## Template 5: Funnel-step abandonment reduction + +Format. Modifying [specific funnel step] will reduce abandonment at that step by [magnitude] (current [baseline rate], target [target rate]) by [mechanism]. + +Worked example, signup funnel. Removing the phone number field from the signup form will reduce signup-form abandonment by 20 percent (currently 35 percent, target 28 percent) by removing a high-friction field that is not required for account creation. + +Worked example, checkout funnel. Adding guest checkout above the account creation prompt will reduce account-creation-step abandonment by 25 percent (currently 18 percent, target 13.5 percent) by giving purchase-intent users a path that does not require account creation. + +Common mistakes specific to this template. +- Reducing abandonment at one step often shifts abandonment to the next step. The right metric is downstream conversion, not just step-level abandonment. Pair step-level primary metrics with full-funnel guardrails. +- Signup abandonment can be measured noisily; users who abandon the form may return later. Define the conversion window (5 minutes, 24 hours, 7 days) before testing. +- Reducing friction is not always good. A signup form that is too short produces low-quality signups: trial users who never return, fake accounts, support load. Pair friction-reduction tests with downstream-quality guardrails. + +--- + +## Anti-templates: hypotheses that should be rejected + +Examples of hypotheses that fail the format and should be rewritten before launching: + +- "We think the new pricing page will increase conversions." Missing magnitude, mechanism, and a specific conversion event. Rewrite using Template 1. +- "Users will love the redesign." Missing everything. Not testable. Pick a metric. +- "The new flow is faster, so more people will complete it." Missing baseline, target, and a defined "complete" event. The mechanism (faster) is plausible but not specific. +- "We want to see if dark mode improves engagement." Vague metric (engagement), no magnitude, and dark mode is binary not a multivariate. Pick a specific engagement metric and pre-register the segments where dark mode users are likely to differ from light-mode users (mobile evening sessions, for example). + +If your draft hypothesis sounds like one of the anti-templates, rewrite it using one of the five templates above before running the test. diff --git a/skills/experiment-design/references/platform-comparison.md b/skills/experiment-design/references/platform-comparison.md new file mode 100644 index 0000000..f435e29 --- /dev/null +++ b/skills/experiment-design/references/platform-comparison.md @@ -0,0 +1,133 @@ +# Platform comparison + +A practical guide to choosing an experimentation platform. Each platform has a distinct profile (statistical defaults, primary audience, integration model, pricing shape). Picking well saves quarters of friction; picking badly creates ongoing pain. + +This reference assumes the team is in the position of choosing or reconsidering. For platform-specific MCP commands, auth models, and example prompts, consult the chosen platform's official documentation. + +--- + +## Statsig + +Profile. Modern feature management plus experimentation platform. Built CUPED-first, holdouts as a first-class concept, warehouse-native with optional event ingestion. Fast-growing customer base including OpenAI, Notion, Brex, Whatnot. + +Strengths. CUPED variance reduction is the default, not an opt-in. Strong holdout analysis with built-in long-term measurement. Mature MCP exposing full CRUD across experiments, gates, dynamic configs, layers, and segments. Setup guides for ChatGPT, Cursor, Claude Code, Codex. + +Best for. Fast-growing companies that want one platform for both feature flags and experiments. Engineering-led teams comfortable with code-first configuration. Teams that need to run many concurrent experiments and care about variance reduction. + +Gotchas. Pricing scales with events, which can compound for high-traffic products. The breadth of the MCP can crowd context windows on smaller models; scoping helps. Best-in-class statistical defaults are nice but require the team to actually understand them. + +MCP setup. Statsig publishes setup guides for ChatGPT, Cursor, Claude Code, and Codex; consult the Statsig docs for the current MCP server URL and auth model. + +--- + +## PostHog + +Profile. Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics in one platform. Self-host or cloud. Customer base skews toward PLG products and developer tools. + +Strengths. Combines analytics and experimentation in one platform, eliminating the metric-definition mismatch between systems. Full event-level data in the warehouse. 200+ MCP tools across the entire product, the largest surface of any vendor in this list. + +Best for. Product-led growth products that benefit from full-funnel context across analytics, experiments, and session replays. Teams that want one platform for everything rather than a stack of specialized tools. + +Gotchas. The breadth of the MCP requires scoping with `?features=` query parameters; without scoping, the agent gets 200+ tools and tool selection accuracy degrades on smaller models. Self-host adds operational complexity. Some experiment features lag behind specialized platforms. + +MCP setup. PostHog's MCP scopes via `?features=` query parameters; without scoping, the agent gets 200+ tools and tool-selection accuracy degrades on smaller models. Consult the PostHog docs for current scoping syntax. + +--- + +## GrowthBook + +Profile. Open-source warehouse-native experimentation. Runs SQL on the team's existing data warehouse. Customer base skews data-mature: Dropbox, Khan Academy, Mistral. Claims the first open-source production MCP for experimentation. + +Strengths. Data stays in the team's warehouse; no event ingestion to a vendor. Strong cost control because the math runs on infrastructure the team already pays for. 100 percent open source under MIT, with self-host or cloud options. + +Best for. Data-mature teams that already own a warehouse (Snowflake, BigQuery, Redshift, ClickHouse, Postgres). Regulated industries where data residency matters. Teams that want full control over the statistical math. + +Gotchas. More setup overhead than hosted platforms. Requires SQL fluency for advanced analyses. Smaller community than the bigger commercial vendors. + +MCP setup. GrowthBook ships an open-source MCP for self-host or cloud; consult the GrowthBook docs for the current binary and auth model. + +--- + +## Optimizely + +Profile. Long-time enterprise leader in personalization and experimentation. Web Experimentation and Feature Experimentation as separate but linked products. Customer base skews enterprise marketing and e-commerce. + +Strengths. Deep targeting, audience management, multivariate testing. Visual editor accessible to non-technical users (marketers can build variants without engineering). Mature personalization and recommendation engine. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth. + +Best for. Marketing-led organizations where non-technical teams need to author variants. Enterprises with deep personalization needs. E-commerce sites with established A/B testing programs. + +Gotchas. Expensive at the enterprise tier. Visual editor produces JS that ships at runtime, which can affect page performance. Less ergonomic for engineering-led teams that prefer code-first configuration. + +MCP setup. Optimizely's hosted Remote MCP works in browser-based ChatGPT and Claude.ai with OAuth; consult Optimizely docs for the current server URL. + +--- + +## Amplitude + +Profile. Behavioral analytics platform with experiments and feature flags layered on top. Customer base skews product analytics teams that adopted Amplitude before adding experimentation. + +Strengths. Deep cohort analysis and behavioral segmentation. Native ChatGPT connector. Hosted MCP available to all customers including the free tier. Integrates tightly with the analytics layer that PMs already use. + +Best for. Teams that already use Amplitude for analytics and want to add experiments without introducing a new platform. Product analytics teams that need behavioral cohort segmentation as part of the experiment workflow. + +Gotchas. Experiments are a secondary feature, not the platform's center of gravity. Variance reduction options are more limited than dedicated experimentation platforms. Beta status of the MCP means the API surface may evolve. + +MCP setup. Amplitude's hosted MCP is available to all customers including the free tier and ships a native ChatGPT connector; consult the Amplitude docs for the current setup steps. + +--- + +## Eppo + +Profile. Warehouse-native experimentation platform with strong statistical defaults. Customer base skews data-team-led organizations: Twitch, DraftKings, Perplexity. Best-in-class statistical rigor. + +Strengths. Best-in-class statistical defaults: variance reduction, sequential testing, contextual bandits, lifecycle experimentation. Warehouse-native means data stays in the team's stack. Strong explainability features for tracing reported lifts back to underlying SQL. + +Best for. Data-team-led organizations where data scientists own the experimentation discipline. Companies with mature warehouses and strict statistical rigor requirements. Teams running contextual bandits or other advanced experiment designs. + +Gotchas. No first-party MCP server as of May 2026. Programmatic access is REST API only; teams that want agentic workflows today need to build a custom MCP adapter or wait. Pricing reflects the data-science-focused product positioning. + +MCP setup. No first-party MCP server as of mid-2026; teams that want agentic workflows today either build a custom MCP adapter on top of Eppo's REST API or wait for the official server. Consult Eppo's docs and roadmap for current status. + +--- + +## Kameleoon + +Profile. AI-driven personalization platform with a specialized MCP focused on the convert-and-promote workflow. The MCP pulls raw variation code from winning experiments and helps refactor it into production-ready React components. + +Strengths. Sharp, narrow MCP (seven specialized tools) focused on a specific job: take a winning marketing-site variation and ship it as permanent product code. Hosted MCP via OAuth. Avoids the broad-CRUD complexity that crowds context windows on other platforms. + +Best for. Teams that test on the marketing site and need to convert wins into permanent React components. Hybrid marketing-and-product setups where the experiment lives in JS/CSS and the win needs to ship as a product feature. + +Gotchas. The narrow MCP scope is intentional but limits broader CRUD work. For everyday flag management, teams use the Kameleoon dashboard or REST API rather than the MCP. + +MCP setup. Kameleoon's hosted MCP via OAuth ships a narrow seven-tool surface focused on the convert-and-promote workflow; consult Kameleoon's docs for the current server URL. + +--- + +## Decision matrix + +A short matrix for the first-pass platform decision. Tradeoffs are oversimplified; verify against the team's specific constraints. + +\| Situation \| Pick \| +\|---\|---\| +\| Pure SaaS, fast-growing, want one platform for flags + experiments \| Statsig or PostHog \| +\| Open-source preference, warehouse-native \| GrowthBook or Eppo \| +\| Enterprise, marketing-led, non-technical variant authoring \| Optimizely \| +\| Already using Amplitude for analytics, want experiments without new platform \| Amplitude \| +\| Convert marketing-site experiment wins into permanent product code \| Kameleoon \| +\| Data-team-led, statistical rigor is non-negotiable, can wait for MCP \| Eppo \| +\| Open-source AND warehouse-native AND need MCP today \| GrowthBook \| + +Beyond these defaults, the right choice depends on the team's existing stack, the experimentation maturity, and the budget. The "best" platform for one team is wrong for another; pick based on the team's actual constraints, not the platform's marketing. + +--- + +## Switching costs + +Once a team has adopted a platform, switching is expensive. Existing experiments need to be re-run on the new platform. The metric definitions need to be reconciled. The team needs to retrain on a new tool. Plan accordingly: + +- Easy switches. Visual A/B testing tools that ship JS at runtime (Optimizely Web, AB Tasty, VWO classic). Switching is mostly tag-replacement. +- Medium switches. Warehouse-native to warehouse-native (GrowthBook to Eppo, or vice versa). The data layer is shared; the configuration migrates. +- Hard switches. Anything to or from event-ingestion platforms (Statsig, Amplitude). The historical event data does not transfer cleanly; the team starts fresh on metric history. + +If the team is choosing now and might need to switch later, lean toward warehouse-native options. Data ownership is the most expensive thing to switch. diff --git a/skills/experiment-design/references/post-experiment-decision-framework.md b/skills/experiment-design/references/post-experiment-decision-framework.md new file mode 100644 index 0000000..6354a66 --- /dev/null +++ b/skills/experiment-design/references/post-experiment-decision-framework.md @@ -0,0 +1,91 @@ +# Post-experiment decision framework + +The moment-of-decision framework for what to do when a test ends. Each step builds on the prior; do not skip ahead. The discipline at this stage is what separates teams that learn from experiments from teams that confirm their priors. + +--- + +## Step 1: Confirm pre-commitment was followed + +Before reading the results, pull up the pre-commitment document. Verify: +- The test ran for the pre-committed duration (not stopped early, not extended). +- The primary metric was the one pre-committed (not silently swapped). +- The segments analyzed were the ones pre-committed (not new ones discovered post-hoc). +- The guardrails are the ones pre-committed (not narrowed or widened after the fact). + +If any item failed the check, the result is compromised. Treat as inconclusive at minimum; consider re-running. + +--- + +## Step 2: Apply the pre-committed decision rule mechanically + +The pre-commitment mapped each possible result to a ship-or-kill decision. Find the bucket the result falls into. Apply the rule. + +Resist the temptation to add new analysis "just to be sure." If new analysis is required to make a decision, the pre-commitment was inadequate; the lesson is for next time, not a license to dig until the answer feels right. + +The mechanical-application discipline is the most important habit at this step. Teams that deliberate about whether to follow their own pre-commitment have already lost the discipline. Apply the rule. Document any second-guessing as feedback for the next pre-commitment. + +--- + +## Step 3a: If decision is "ship" + +1. File the launch ticket. Include: the test ID, the primary metric lift, confidence interval, guardrails status, segments status, and a link to the pre-commitment. +2. Schedule post-launch monitoring at +7 days, +30 days, +60 days. Calendar reminders, not "I'll check it later." +3. Confirm the launch removes the experiment infrastructure (the flag, the variant code paths) on the schedule the team has for stale-flag cleanup. See the `feature-flagging` skill for the cleanup discipline. +4. Post a brief launch summary to the team's experiment log. + +--- + +## Step 3b: If decision is "kill" + +1. Document the learning. What did the team predict? What happened? What is the most likely reason for the gap? +2. Propose a follow-up hypothesis if applicable. The hypothesis can be "we should not test this idea again" if the test was definitive in the negative direction. It can be "let's iterate the mechanism" if the test was inconclusive and the team has a clearer story now. +3. Archive the experiment infrastructure: remove the flag, clean up the variant code, remove instrumentation that was specific to this test. +4. Post the kill summary to the team's experiment log. Killed experiments are as valuable as winning experiments; they prevent the team from repeating the mistake. + +--- + +## Step 3c: If decision is "inconclusive" + +The inconclusive path is the hardest. The temptation is to ship anyway because the team has invested in the hypothesis. Resist it. + +Run through the resolution paths in order: + +1. Was the MDE realistic? If the test was underpowered (you needed a 5 percent lift to be detectable, and you got a 2 percent point estimate with a confidence interval crossing zero), the right answer may be to redesign the test with a bolder change and rerun. Do not extend the existing test; that produces a peeking artifact. Plan a new test, pre-commit, run. +2. Was the test contaminated? If a confounder (campaign, outage, instrumentation bug) is identifiable, fix and rerun. Do not handwave the confounder. +3. Is the change cheap and reversible? If the change is small, easy to maintain, and easy to roll back, shipping despite an inconclusive result is defensible. The bar is high; the change has to be genuinely cheap, and the guardrails have to be clean. If the change is expensive to maintain (additional UI complexity, additional code paths, additional analytics surface), ship is the wrong call. +4. Otherwise: kill, document, move on. The discipline of accepting inconclusive results as inconclusive is what makes experimentation a learning system. Treating every inconclusive result as a "we just need more data" justification destroys the discipline. + +--- + +## Step 4: Write the post-mortem within one week + +Regardless of the decision, write a short post-mortem within one week. The post-mortem covers: + +- The hypothesis (cause, effect, magnitude, mechanism) +- The pre-commitment (primary metric, MDE, duration, decision rule) +- The result (lift, CI, guardrails, segments) +- The decision (ship / kill / inconclusive) +- The action taken (launch, archive, redesign) +- The learning (what would the team do differently next time) + +Keep post-mortems short: half a page is plenty. Long post-mortems do not get written; short ones do. The compounding value of a written experiment log over years is enormous; the compounding value of a vague memory of past tests is zero. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. + +Schedule a review at: + +- Day 7. Production metric matches the experiment lift within reasonable tolerance. If it does not, investigate before declaring the launch successful. +- Day 14. Lift has not decayed (which would suggest novelty effect that the test underweighted) or amplified (which would suggest the change interacts with something the test could not capture). +- Day 30. Long-term metrics (retention, downstream conversion, support load) are not eroding. The change continues to deliver value, not just an initial bump. + +If the production behavior diverges materially from the test behavior at any review: + +1. Quantify the divergence. Is it within statistical noise, or is it a real effect? +2. Investigate the cause. Common ones: novelty wore off, segment distribution shifted, instrumentation bug, interaction with another concurrent change. +3. Decide: roll back, hot-fix, or accept and document. Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. + +The 30-day rule prevents the "we shipped, it worked, then it stopped working but nobody noticed" failure mode. Most teams skip post-launch monitoring; the ones that do it consistently learn faster. diff --git a/skills/experiment-design/references/pre-experiment-readiness-checklist.md b/skills/experiment-design/references/pre-experiment-readiness-checklist.md new file mode 100644 index 0000000..5a0e44a --- /dev/null +++ b/skills/experiment-design/references/pre-experiment-readiness-checklist.md @@ -0,0 +1,108 @@ +# Pre-experiment readiness checklist + +A go/no-go decision checklist to run through before launching any experiment. If any item is "no," delay the launch until it is "yes." Running an experiment without these in place produces results that cannot be defended, decisions that get second-guessed, and a long-term erosion of trust in the experimentation discipline. + +The checklist takes ten to fifteen minutes per experiment. The cost of skipping it is much higher. + +--- + +## 1. Hypothesis written in cause-effect-magnitude-mechanism format + +The hypothesis names: what change is being made (cause), what metric will move (effect), how much you expect it to move with what baseline and target (magnitude), and why you expect this change to produce this effect (mechanism). + +If the draft hypothesis is missing any of the four parts, rewrite using one of the templates from `hypothesis-templates.md` before launch. + +--- + +## 2. Primary metric defined with success threshold + +Exactly one primary metric. Specified with the same precision the platform's metric configuration requires (event name, deduplication window, user identity logic). Success threshold pre-committed: the lift you would consider sufficient to ship. + +If multiple metrics feel "primary," collapse to one and demote the others to guardrails. + +--- + +## 3. Guardrails defined (3 to 5) + +Three to five guardrail metrics that must not break: revenue, retention, support tickets, page load time, error rate, satisfaction scores. Each with a tolerance threshold pre-committed. + +Avoid: more than five guardrails (creates analysis paralysis), or zero guardrails (the test cannot detect collateral damage), or vague guardrails like "user happiness" (not measurable). + +--- + +## 4. Sample size calculated for chosen MDE + +The required sample size for the chosen minimum detectable effect, at standard alpha (0.05) and power (0.80), through your platform's calculator or via a stats library. Documented in the pre-commitment. + +If the math says "you need 200,000 users to detect this lift and you have 5,000 a week," accept a larger MDE or do not run the test. Do not run an underpowered test and hope for the best. + +--- + +## 5. Duration committed (longer of sample-size-hit and full weekly cycle) + +Calendar duration committed in advance. The longer of: time to hit the calculated sample size at expected daily traffic, or one full weekly cycle (typically 7 days). UI/UX changes get a 14-day minimum regardless. + +If the duration is "we will see how long it takes," that is not a duration. Pick a date. + +--- + +## 6. Segments pre-registered (if any) + +If you plan to analyze segment-level results, name the segments before launch. Three to five maximum, each with a real prior reason to expect different behavior in that segment. + +If you do not plan to analyze segments, write that down too. The pre-commitment to "no segment analysis" is itself a defense against post-hoc segment mining. + +--- + +## 7. Decision rule pre-committed (saved with timestamp) + +Map each possible result to a decision: +- Result above target threshold + guardrails clean: ship +- Result below MDE: kill +- Result inconclusive (point above zero, CI crosses zero): default to do not ship; document next-step options +- Guardrail violation: do not ship regardless of primary + +Save the decision rule somewhere immutable: the PR description, a pinned ticket, a signed Slack message, anywhere with a timestamp. + +--- + +## 8. No conflicting concurrent experiments on the same surface + +Check the experiment registry for what else is running on the same surface (checkout flow, signup form, pricing page). If there are interactions, set up mutex enforcement so users in this test are not also in the others. + +If you cannot enforce mutex (sample size constraints), document the overlap and accept the interpretability cost. Do not pretend there is no overlap. + +--- + +## 9. Instrumentation tested with a small canary + +Before launching to the full population, expose a small canary group (5 to 10 percent) and confirm: +- Treatment users actually see the treatment +- Events fire correctly for both groups +- The platform reports the right exposure counts +- Internal traffic is excluded +- The metric definitions match between the platform and production analytics + +Catching instrumentation bugs in canary saves a wasted full test run. + +--- + +## 10. Stakeholders aligned on what each outcome means + +The PM, the engineering lead, the design lead, and any other decision-maker have all agreed: if the test wins, we ship; if it loses, we kill; if it is inconclusive, we follow the inconclusive path documented in the decision rule. + +If a stakeholder is going to dispute the result regardless of what it shows, the experiment is theater. Resolve the strategic question first; run the experiment only if the result genuinely changes the decision. + +--- + +## Decision + +If all ten items are "yes," launch. + +If any item is "no": +- Items 1, 2, 3 (hypothesis, metric, guardrails): blocking. Fix before launch. +- Items 4, 5, 7 (math, duration, decision rule): blocking. Fix before launch. +- Items 6, 8, 9 (segments, mutex, canary): worth fixing but launch can proceed if the fix is impractical and the team accepts the risk. +- Item 10 (stakeholder alignment): blocking. An experiment that cannot change the decision is theater. + +The cost of delaying a launch by a day to fix a checklist item is small. The cost of running a test that produces an indefensible result is much higher. diff --git a/skills/experiment-design/references/results-interpretation-checklist.md b/skills/experiment-design/references/results-interpretation-checklist.md new file mode 100644 index 0000000..32d3006 --- /dev/null +++ b/skills/experiment-design/references/results-interpretation-checklist.md @@ -0,0 +1,112 @@ +# Results interpretation checklist + +A step-by-step checklist for reading experiment results and arriving at a defensible decision. Run through it in order. Do not skip steps because the result "looks obvious"; the obvious-looking results are often the ones that fail in production. + +--- + +## Step 1: Did the test run for the pre-committed duration? + +What to look for. The test ended on the date pre-committed at launch, with the planned analysis happening on that date. + +Red flags. The test was stopped early because results "looked great." The test was extended past the pre-commitment because results "had not stabilized." The test ran for an arbitrary duration not tied to the pre-commitment. + +When to escalate. If the duration was changed after launch without documented rationale, the result is compromised. Treat as inconclusive and consider re-running. + +--- + +## Step 2: Did all guardrails stay within tolerance? + +What to look for. Each pre-defined guardrail (revenue, retention, support tickets, page load time, error rate) within its acceptable range. Confidence intervals around guardrail metrics that exclude the threshold of concern. + +Red flags. A guardrail moved in the wrong direction even if the change was not "significant." Wide confidence intervals on guardrails (the test was underpowered for the guardrail). A guardrail you did not pre-define being raised post-hoc. + +When to escalate. A guardrail violation should be treated as binding. The fix is "do not ship," not "the primary metric was good enough to outweigh the guardrail." If the guardrail was poorly chosen, that is a lesson for next time, not a license to ignore it on this test. + +--- + +## Step 3: Did the primary metric move beyond the MDE? + +What to look for. The point estimate of the primary metric exceeds the pre-committed minimum detectable effect, and the confidence interval excludes zero (or excludes the no-effect threshold for one-sided tests). + +Red flags. Point estimate is above MDE but the confidence interval crosses zero. The "significance" comes from a peeking artifact (interim analysis that became the headline). The lift comes from a small number of outlier users. + +When to escalate. If the primary metric is significant but the lift is below MDE, the test was overpowered for the question; the result is technically real but practically too small to matter. Do not ship a 0.3 percent lift just because p equals 0.001. + +--- + +## Step 4: Was the confidence interval clean? + +What to look for. A confidence interval around the lift estimate that is well-bounded and not crossing zero. Symmetric (or appropriately skewed for the metric type). + +Red flags. Very wide CI (test was underpowered). Skewed CI hinting at distributional weirdness (a few outliers drove the result). CI computed without ratio-aware variance for ratio metrics. + +When to escalate. If the CI is wide enough that the practical lift could be anywhere from "not worth shipping" to "amazing," the test does not support a confident ship decision. Run longer or accept inconclusive. + +--- + +## Step 5: Are the results consistent across pre-registered segments? + +What to look for. The pre-registered segments show effects in the same direction as the overall result. Magnitude can vary; direction should not flip. + +Red flags. Some segments show effects opposite to the overall result. The overall lift comes from one segment and the rest are flat or negative. + +When to escalate. If one segment is driving the entire effect and others are negative, the right ship decision is "ship to the segment where it works" only if the targeting infrastructure exists and is worth the maintenance cost. More often the right answer is to redesign the change so it works for the whole population. + +Reminder: this step covers PRE-REGISTERED segments only. Post-hoc segments are noise mining; do not re-analyze the data through new segments looking for an interpretation. + +--- + +## Step 6: Did any external events potentially confound the results? + +What to look for. A timeline of events during the test window: marketing campaigns, product launches, outages, news cycles, holidays, seasonality shifts. + +Red flags. A campaign launched mid-test that brought a different user mix. A product release mid-test that changed user behavior. An outage during the test that affected one variant differently from the other. + +When to escalate. If a confounder is identified, isolate it. Stratify the analysis by acquisition source (excludes campaign-driven users), or by date (excludes the outage day), or rerun. Do not handwave the confounder; either fix it or accept that the result is tainted. + +--- + +## Step 7: Is the magnitude practically significant, not just statistically significant? + +What to look for. The lift is large enough to matter for the business. A 0.3 percent absolute lift on a 30 percent baseline is statistically significant with enough sample but may not justify the engineering cost of maintaining the change. + +Red flags. "Statistically significant" being used as the only justification. No conversation about whether the lift is large enough to be worth the implementation, maintenance, and complexity cost. + +When to escalate. If the magnitude is small, ask: "Is this worth the code surface area, the testing surface area, and the cognitive load on the team?" Often the answer is no. Do not ship marginal lifts unless the change is also cheap to maintain. + +--- + +## Step 8: Does the decision match the pre-committed rule? + +What to look for. The pre-commitment document mapped each possible result to a ship-or-kill decision. The result fits clearly into one of those buckets. + +Red flags. The result does not fit cleanly. The team is debating which bucket applies. Someone is proposing a new analytical knob to clarify the bucket. + +When to escalate. If the result is genuinely ambiguous, default to "do not ship" and document why. Inconclusive is a valid outcome; treating it as one is the discipline. + +--- + +## Decision matrix + +After running through the checklist, the result fits one of three buckets: + +\| Bucket \| Conditions \| Action \| +\|---\|---\|---\| +\| Clear win \| Primary moved past MDE, CI excludes zero, guardrails clean, segments consistent, no confounders \| Ship. File launch. Schedule post-launch monitoring at +30 and +60 days. \| +\| Clear loss \| Primary moved against expected direction with significance, OR guardrail violated \| Kill. Document the learning. Propose follow-up hypothesis if applicable. \| +\| Inconclusive \| Anything else \| Default to do not ship. Run a bigger version, kill, or iterate the hypothesis. \| + +The inconclusive bucket is the most common and the hardest. The discipline is to recognize it and resist the pull to ship anyway. + +--- + +## Post-launch monitoring (the 30-day rule) + +Even shipped experiments need monitoring. The first 30 days after launch are when the production behavior diverges from the test behavior, if it is going to. Schedule a review at day 7, day 14, and day 30. + +What to check at each review: +- Day 7: Production metric matches the experiment lift within reasonable tolerance. +- Day 14: Lift has not decayed (novelty effect) or amplified (the change interacts with something the test could not capture). +- Day 30: Long-term metrics (retention, downstream conversion) are not eroding. + +If the production behavior diverges materially from the test behavior, the right call is to roll back and investigate, not to "wait and see." Most successful tests behave the same way in production as in the test; the ones that diverge are usually telling you something is wrong. diff --git a/skills/experiment-design/references/sample-size-tables.md b/skills/experiment-design/references/sample-size-tables.md new file mode 100644 index 0000000..5a74eea --- /dev/null +++ b/skills/experiment-design/references/sample-size-tables.md @@ -0,0 +1,88 @@ +# Sample size tables + +Pre-calculated sample size tables for the most common experimentation scenarios. These tables are starting points, not substitutes for running the math against your specific traffic and metric. The math depends on the variance of the metric, the desired power, the alpha threshold, and the test design (one-sided, two-sided, sequential). + +Use these tables to: +- Sanity-check a sample size estimate from your platform's calculator +- Decide whether the planned test is feasible given your traffic +- Choose an MDE that is realistic for your traffic level + +For exact figures, run the math through your platform's calculator (most experimentation platforms expose one) or use a stats library (`scipy.stats`, R's `pwr` package, or an online calculator). + +--- + +## How to use these tables + +Each table assumes: +- Two-sided test (the standard default for PM experiments) +- Alpha equals 0.05 (5 percent false positive rate) +- Power equals 0.80 (80 percent chance of detecting an effect that is really there) +- Equal group sizes (50/50 split) + +Total sample size is the sum across both groups. Per-group sample is half the total. + +If you change any of those assumptions, multiply by the indicated factor: +- Power 0.90 instead of 0.80: multiply sample size by ~1.34 +- Alpha 0.01 instead of 0.05: multiply sample size by ~1.49 +- One-sided test: multiply by ~0.79 + +Worked example for using Table 1: a product has a baseline conversion rate of 10 percent and wants to detect a 1 percent absolute lift (target 11 percent). Total sample size required is roughly 31,400 users. With 1,000 daily new users in the test population, the test needs about 31 days plus one full weekly cycle. If you can only run it for 14 days, the MDE you can detect at this traffic is closer to 1.5 percent absolute. Pick the change you can detect; do not run an underpowered test. + +--- + +## Table 1: Conversion rate experiments + +Total sample size required (across both groups) for a two-sided test, alpha 0.05, power 0.80. + +\| Baseline rate \| MDE 1% abs \| MDE 2% abs \| MDE 5% abs \| MDE 10% abs \| +\|---\|---\|---\|---\|---\| +\| 5% \| 14,800 \| 4,400 \| 1,000 \| 360 \| +\| 10% \| 31,400 \| 8,400 \| 1,700 \| 540 \| +\| 20% \| 51,800 \| 13,400 \| 2,500 \| 720 \| +\| 30% \| 65,600 \| 16,600 \| 3,000 \| 800 \| +\| 50% \| 78,400 \| 19,600 \| 3,200 \| 800 \| + +Reading the table. A product with 30 percent baseline conversion that wants to detect a 2 percent absolute lift (target 32 percent) needs ~16,600 users total, ~8,300 per group. Numbers are approximate and rounded. + +Choosing an MDE that matches traffic. If you have 5,000 weekly users in the test population: +- One week of traffic supports detection of ~5 percent absolute lift on a 30 percent baseline (3,000 users, MDE 5 percent matches) +- Two weeks supports ~3 percent absolute lift +- Four weeks supports ~2 percent absolute lift +- Six weeks supports ~1.5 percent absolute lift + +Beyond six weeks the test runs into seasonality and product-evolution problems described in [SKILL.md](../SKILL.md). If the change you want to test would only produce a 1 percent absolute lift and your traffic supports 5 percent MDE in a reasonable window, the test is not worth running. Pick a bigger change. + +--- + +## Table 2: Mean comparison experiments (continuous metrics) + +For continuous metrics like time-on-task, session length, page views per session, the math depends on the metric's standard deviation, which varies by product. The table below shows sample sizes assuming a coefficient of variation (standard deviation divided by mean) of 1.0, which is typical for engagement metrics. + +\| Baseline mean \| MDE 5% rel \| MDE 10% rel \| MDE 20% rel \| +\|---\|---\|---\|---\| +\| Any (CoV ~1.0) \| 12,600 \| 3,200 \| 800 \| +\| Any (CoV ~2.0) \| 50,400 \| 12,600 \| 3,200 \| + +For revenue metrics the CoV is often higher (2.0 to 3.0) because revenue is concentrated in a small fraction of users. Run your variance through the platform calculator before committing to a sample size; the table is illustrative, not authoritative. + +--- + +## Common pitfalls in sample size planning + +- Forgetting to count exposure, not allocation. If 1,000 users see the experiment per day but only 200 reach the surface where the variant is rendered, your effective sample is 200 per day. Use exposure counts, not bucketing counts. +- Treating session-level and user-level differently. Some metrics are evaluated per session (page views per session), others per user (day-7 retention). Sample size requirements differ. Specify which level the metric is evaluated at and use the matching count. +- Forgetting variance reduction. Methods like CUPED, stratified sampling, and control variates can reduce required sample size by 30 to 50 percent for the same power. If your platform supports them, use them. Sample size tables ignoring variance reduction overstate what you actually need. +- Underestimating the weekly cycle requirement. A test that hits sample size in three days still needs to run a full week to capture cycle effects. Sample size hit is necessary but not sufficient. +- Assuming traffic is stable. If a marketing campaign launches mid-test, the user mix changes and the test may no longer be a clean comparison. Coordinate with marketing before launching tests on user-acquisition-sensitive surfaces. + +--- + +## When the math says "you cannot detect this" + +Sometimes the table reads "you need 200,000 users to detect this lift and you have 5,000 a week." Three options: + +1. Accept a larger MDE. Pick a bigger change worth detecting. A 3 percent absolute lift may be detectable in two weeks; a 0.3 percent lift may take a year. Test the bigger change. +2. Find a more sensitive metric. Sometimes the metric is the constraint, not the change. Switching from "purchases" to "add-to-cart" gives you a higher-frequency event with more sample. The trade-off is that ATC is less directly tied to revenue; pair the more-sensitive primary with a revenue guardrail. +3. Skip the test. If the change is small but cheap and reversible, ship without testing. If it is small and expensive to maintain, do not ship. Running an underpowered test produces noise dressed up as evidence; that is worse than no test. + +The discipline is to refuse to run tests that cannot answer the question. An underpowered test is not "better than nothing"; it is worse than nothing because it produces a result that feels meaningful but is not. diff --git a/skills/experimentation-analytics/SKILL.md b/skills/experimentation-analytics/SKILL.md new file mode 100644 index 0000000..eb34627 --- /dev/null +++ b/skills/experimentation-analytics/SKILL.md @@ -0,0 +1,333 @@ +--- +name: experimentation-analytics +description: How to read experiment results without fooling yourself. Confidence intervals, p-values, multiple testing, sequential testing, CUPED, heterogeneous treatment effects, ratio metrics, network effects, dashboard reconciliation, and the interpretation failures that produce confidently wrong shipping decisions. +category: product +catalog_summary: "Read result panels without fooling yourself: confidence intervals, p-values, multiple testing, sequential testing, CUPED, ratio metrics, network effects, dashboard reconciliation" +display_order: 6 +--- + +# Experimentation Analytics + +A data-team-mentor's playbook for interpreting experiment results without fooling yourself. + +The result panel is the moment-of-truth for an experiment. The numbers on it determine whether you ship, kill, or iterate. They also expose every shortcut taken in the design phase: an underpowered test produces wide confidence intervals; a peeked test produces a too-narrow p-value; a ratio metric without delta-method correction produces overconfident lift estimates. Most ship-the-wrong-thing decisions trace back to misreading the result panel. + +This skill is the discipline that prevents misreading. It assumes the experiment was designed well (see the `experiment-design` skill). It assumes the platform's results panel is technically correct (most modern platforms are; some older ones are not). It assumes you can read a number off a screen. The hard part is knowing what each number actually means and what it does not, and that is what is here. + +When to use this skill: any time you are reading an experiment result panel and about to make a ship, kill, or iterate decision. + +--- + +## What this skill is for + +This skill covers result interpretation, the statistical concepts that make the numbers trustworthy, and the dashboard reconciliation work that prevents executive-level confusion when the experiment number does not match the BI number. The audience is product managers and data analysts who read experiment results together and need a shared vocabulary that does not paper over the dangerous parts of statistics. + +Companion skills cover the adjacent territory. The `experiment-design` skill covers pre-experiment thinking: hypothesis, sample size, MDE, segments, what NOT to test. Read it before designing the test; read this skill when reading the result. The `feature-flagging` skill covers the operational mechanics of flag management, environment promotion, and stale-flag cleanup. Together the three skills span the experimentation lifecycle from intent through interpretation. For platform-specific MCP commands, consult the chosen platform's docs; Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, and Kameleoon all expose rich analytics surfaces that this skill informs how to read. + +--- + +## The result panel: what every modern platform should expose + +A result panel that omits any of the following is a black box. Treat results from black-box platforms with extra skepticism, and consider exporting raw assignment and event data into a notebook where you can compute the missing pieces yourself. + +What a competent platform exposes: + +- Variants and traffic allocation (e.g., 50/50, 33/33/33). Allocation drift across the test window indicates assignment bugs. +- Per-variant primary metric: point estimate, confidence interval (or credible interval for Bayesian), sample size at the variant level. +- Lift: variant minus control, expressed as both absolute change and relative percent. Both numbers matter; relative is intuitive, absolute is what shows up in revenue calculations. +- Statistical significance: p-value (frequentist) or probability of being best (Bayesian). The methodology should be labeled clearly so you know which interpretation rules apply. +- Variance reduction technique applied: CUPED, post-stratification, regression adjustment. If the platform applies these silently, ask which. +- Guardrail metric statuses: each guardrail labeled green, amber, or red against its tolerance. The tolerance was set at design time; the panel just enforces it. +- Per-segment results for pre-registered segments only. Post-hoc segment slicers are tempting and dangerous. +- Test status: running, ended, decision filed. +- A time series of the lift across the test window. This is where novelty effects, primacy effects, and assignment bugs become visible. + +If you are looking at a result panel that hides any of these, the first move is to surface them, not to ship. + +--- + +## Confidence intervals: the most important number + +The single most important number on the result panel is the confidence interval (CI) on the lift. More important than the point estimate. More important than the p-value. The CI tells you what you actually know. + +What a 95% CI of [+2%, +6%] means: under repeated sampling, the true effect would fall in this range 95% of the time. The true effect is most likely somewhere near the middle, but the extremes are entirely consistent with the data. + +What it does not mean: it does not literally mean "there is a 95% chance the true effect is between +2% and +6%." That is the Bayesian credible interval, which often gives similar numerical answers but is conceptually different. PMs can usually live with the loose intuition; analysts should know the precise version when defending a number to a skeptic. + +The width of the CI matters more than the center for most ship decisions. A wide CI means you do not know much yet. A narrow CI means you know with precision. The point estimate is your best guess; the width is your humility. + +Practical decision rules, in order of importance: + +1. If the CI includes zero AND a meaningful positive number (say [-1%, +5%]), you do not have enough data to ship. Period. The point estimate may look favorable, but the data is consistent with no effect and consistent with a meaningful win. You cannot tell which. +2. If the CI is all-positive (lower bound greater than zero, e.g., [+1%, +4%]), there is a real effect. Now evaluate magnitude: is the lower bound large enough to be worth the implementation cost? +3. If the CI is all-negative (upper bound less than zero, e.g., [-5%, -1%]), there is real harm. Kill the test. +4. If the CI straddles zero but is narrow (e.g., [-0.5%, +0.5%]), this is a real null result. The effect is small enough to call essentially zero. Useful information; do not ship the change for "lift" reasons (you found none) but do not panic about harm either. +5. If the CI straddles zero and is wide (e.g., [-5%, +8%]), the test is inconclusive. The data is consistent with a moderate win, no effect, or a moderate loss. Run longer, run bigger, or accept that the question cannot be answered at the available traffic. + +For a worked-example cheatsheet, see [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). + +--- + +## P-values: what they mean and what they do not + +The p-value is the probability of observing the lift you saw (or a larger one) IF the true effect were zero. A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. + +What the p-value does not mean, despite frequent abuse: + +- It does not mean "there is a 96% chance the treatment works." That sentence has no defensible interpretation; the p-value is computed under the assumption that the treatment does NOT work, so it cannot tell you the probability that it does. +- It does not mean "the effect is large." A tiny effect tested against a huge sample can produce a vanishingly small p-value. The p-value is about the strength of evidence against the null, not the size of the effect. +- It does not mean "the result will replicate." A p-value of 0.04 is associated with replication rates well below 50% in most published research; statistical significance is not reproducibility. + +The 0.05 cutoff is convention, not law. If you pre-committed to alpha equals 0.05, follow it; the discipline of pre-commitment is more valuable than the specific threshold. If you did not pre-commit, p equals 0.06 is not categorically different from p equals 0.04, and treating it as such is theater. + +Always read the CI alongside the p-value. The p-value tells you about the null hypothesis; the CI tells you about the magnitude. Both matter; neither is sufficient alone. A p-value of 0.001 with a CI of [+0.1%, +0.3%] is a real but practically tiny effect; a p-value of 0.08 with a CI of [-1%, +12%] is a noisy estimate that could be huge or zero. The former is technically significant and not worth shipping; the latter is technically not significant and you might still want to dig deeper. + +The peeking problem applies to p-values directly. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Modern platforms with sequential testing report "always-valid" or "anytime-valid" p-values that survive peeking; older platforms do not. Know which you are looking at. See [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md) for deeper coverage. + +--- + +## Multiple testing corrections + +The problem in one sentence: with twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty comparisons, two or three. With a hundred, five. + +Where multiple testing creeps in unintentionally: + +- Multiple variants: A vs B vs C vs D is three pairwise comparisons against control, not one. +- Multiple metrics: tracking primary plus six guardrails plus three secondary metrics is ten chances to find significance somewhere. +- Multiple segments: ten segments times three metrics is thirty chances. +- Multiple time windows: looking at week 1, week 2, week 3, and the full test is four chances per metric per segment. + +Two correction methods you should know: + +- Bonferroni correction. Divide alpha by the number of comparisons. Conservative; controls the family-wise error rate (the probability of even one false positive across the family of tests). Use when false positives are catastrophic. +- Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (the expected proportion of false positives among the things called significant). Better for exploratory analysis. + +Most modern platforms support these natively as a configuration option. Configure them, or know which the platform applies by default. Some platforms apply corrections silently to the displayed p-values; others report uncorrected numbers and expect you to do the math. + +The PM-friendly heuristic: pre-register your primary metric and primary segment. Treat everything else as exploratory. Findings in non-primary metrics or non-primary segments require larger effects, replication in a follow-up test, or both before they justify shipping. The discipline of designating primary up front protects you from the multiple-testing trap better than any correction formula. + +--- + +## Sequential testing math + +The peeking problem revisited from the analytics side. Classical t-tests, z-tests, and proportion tests assume one analysis at the end of a test. If you analyze the data five times during the test and stop the moment you see significance, your false positive rate is much higher than the nominal 5%. With daily peeking on a four-week test, false positive rate can climb above 30%. + +Sequential testing methods adjust the math to allow continuous monitoring without inflating false positives. The names you will encounter: + +- mSPRT (mixture sequential probability ratio test). Produces "always-valid" p-values: you can look any time, and the false positive rate stays at the nominal alpha. Common in modern platforms. +- Group sequential designs. Plan a fixed set of interim analyses (say, three) with adjusted significance thresholds at each. Less flexible than mSPRT but well-understood. +- Anytime-valid confidence intervals. The CI version of always-valid p-values. Wider than fixed-horizon CIs by design; the cost of peek-safety is some statistical efficiency. + +Modern platforms with sequential testing built in: Statsig (always-valid by default), Eppo (sequential CIs as a configuration), parts of PostHog (depending on the experiment type), GrowthBook (mSPRT supported). If your panel says "always-valid p-value" or "anytime-valid CI," that is sequential. If it says "p-value" with no qualifier, it is probably fixed-horizon and peeking inflates false positives. + +If your platform does not support sequential testing, the discipline is: pre-commit to a single analysis date at launch, do not peek, and if you must peek, do not make decisions based on the peek. Save the decision-making for the pre-committed date. This is hard. Sequential testing makes it easier. + +The trade-off: sequential tests have wider CIs and less aggressive p-values than fixed-horizon tests at the same sample size. The cost is real but usually worth it for PM contexts where the discipline of not peeking is impractical. + +--- + +## CUPED variance reduction + +CUPED (Controlled-experiment Using Pre-Experiment Data) uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. The result is the same point estimate with a much narrower confidence interval, often 30% to 50% narrower, which is equivalent to roughly doubling your effective sample size for free. + +When CUPED helps: + +- Metrics with high pre-experiment baseline variance: revenue per user, sessions per user, engagement minutes, content consumption. +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When CUPED does not help: + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline (a user either signs up or does not; there is nothing to subtract). +- Tests where pre-experiment behavior is essentially uncorrelated with the metric being moved. + +How to read CUPED-adjusted results: the point estimate is roughly the same as the unadjusted estimate; the CI is narrower. If a result switched from "significant with CUPED" to "not significant without CUPED," that is normal and the CUPED-adjusted version is the more powerful test. If a result went the other way (significant without CUPED, not significant with), the unadjusted result was probably noise that CUPED correctly removed. + +A common confusion: "CUPED made our lift smaller, so we should ship the unadjusted version." This is wrong. CUPED reduces variance, not point estimates. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. Trust the adjusted version. + +Platform support: Statsig, Eppo, GrowthBook, parts of PostHog, Amplitude (Experiment product). Optimizely has equivalent variance reduction. If your platform offers CUPED, turn it on for any metric where pre-experiment data exists. + +For deeper coverage of CUPED, the delta method, and other statistical methods, see [`references/statistical-method-reference.md`](references/statistical-method-reference.md). + +--- + +## Heterogeneous treatment effects (HTE) and segments + +A heterogeneous treatment effect is when the treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. This is common, often interesting, and easy to over-read. + +Why HTE is tempting: "let us just ship to new users." Why it is dangerous: post-hoc segment discovery is often noise; targeting infrastructure costs are real; UI complexity from per-segment behavior compounds over time. + +The right way to handle HTE: + +- Pre-register the segments you care about before launching. Two or three is plenty; ten is overfitting waiting to happen. +- If a pre-registered segment shows a meaningfully different effect, treat it as evidence worth following up. Not as a green light to ship to that segment alone. +- Before shipping segment-only behavior, ask: is the segment large enough to matter, is the effect large enough to justify the targeting work, and can we build the targeting cleanly in production? +- If the segment was discovered post-hoc by slicing the data many ways, treat the finding as a hypothesis for a follow-up test. Do not ship based on one observation. + +HTE versus simple averaging: when segments have meaningfully different effects, the average underrepresents both. A treatment that is +10% for half the population and -5% for the other half averages to +2.5%, which understates the win for half and ignores the loss for the other. The average is still the right number for "ship to everyone" decisions; per-segment numbers are the right inputs for "should we invest in segment-specific targeting" decisions. + +Practical heuristic: if pre-registered segments show meaningfully different effects, write a follow-up hypothesis. Run a follow-up test that confirms the segment behavior with appropriate power. Then decide on segment-specific shipping. The cost of the follow-up test is much smaller than the cost of shipping segment-targeted behavior that does not actually work. + +--- + +## Ratio metrics and the delta method + +Most "rate" metrics are ratios. Conversion rate equals conversions divided by users. Click-through rate equals clicks divided by impressions. Revenue per user equals revenue divided by users. Average order value equals revenue divided by orders. + +Why this matters for analytics: standard variance estimation for sums does not apply directly to ratios. Naive variance estimation on ratios produces incorrectly narrow confidence intervals and inflated false positive rates. You ship things that look significant but are not, because the math under the hood was wrong. + +Two correct approaches: + +- Delta method. A calculus-based correction (Taylor expansion linearization) that produces correct CIs and p-values for ratio metrics. Fast, well-understood, what most modern platforms use. +- Bootstrap. A simulation-based alternative: resample users with replacement many times, compute the ratio each time, and read off the empirical distribution. Distribution-free and intuitive; slower than delta method. + +How to verify your platform: ask "what variance estimator do you use for ratio metrics?" If the answer is "standard t-test on proportions," that is wrong for any ratio that is not a simple binary conversion (one row per user, converted yes or no). If the answer is "delta method," "linearization," or "bootstrap," correct. + +Most modern platforms (Statsig, Eppo, PostHog, Optimizely, GrowthBook) handle this correctly. Older or homegrown platforms often do not. The risk is silent: the panel shows confidence intervals that look reasonable but are too narrow, and you ship changes that do not produce the claimed effect. + +Worked example. Revenue per user is a ratio: total revenue divided by total users. Suppose treatment shows a 5% lift with a CI that excludes zero under the wrong (naive) variance estimator. Under the correct delta-method estimator, the same point estimate has a CI that includes zero. The wrong math says "significant, ship." The correct math says "inconclusive, run longer or accept noise." Shipping based on the wrong math means shipping changes that do not produce the claimed effect in production, then puzzling over why the launch did not move the dashboard. + +--- + +## Bayesian vs frequentist results panels + +Frequentist panels (most older platforms, parts of most modern ones) show p-values, confidence intervals, and "statistically significant" labels. Bayesian panels (Eppo by default, Statsig as an option, parts of PostHog) show probability of being best, credible intervals, and posterior distributions. + +For most PM contexts, both approaches produce similar ship-or-kill decisions when the experiment was designed correctly. The vocabulary differs; the underlying judgment is similar. + +Bayesian advantages: + +- Natural multi-variant comparison: "variant B has 87% probability of being best" reads more naturally than the equivalent Bonferroni-corrected p-value soup. +- Peek-safe by construction: posterior probabilities are valid at any time without sequential corrections. +- More intuitive for stakeholders unfamiliar with hypothesis testing. +- Allows informative priors when you have prior knowledge (rare in practice for shipping decisions). + +Frequentist advantages: + +- Better-understood: most analytics teams have stronger frequentist training. +- Clearer pre-registration semantics: "alpha equals 0.05, MDE equals 5%, decision rule X" is unambiguous. +- Longer track record in regulated contexts. + +Mixing them within a single experiment is fine. Most platforms (Eppo, Statsig) let you toggle. Pick one per experiment and stick with it; do not switch mid-flight to chase a more favorable interpretation. That is the Bayesian-frequentist version of p-hacking and corrodes the discipline. + +--- + +## Network effects and SUTVA violation + +SUTVA (Stable Unit Treatment Value Assumption) is the technical name for "one user's treatment does not affect another user's outcome." When SUTVA holds, standard A/B test math works. When it is violated, the math systematically understates or overstates the true effect. + +When SUTVA is violated: + +- Two-sided marketplaces. Changes to buyers shift seller behavior, which affects control buyers competing for the same supply. Treatment buyers' actions leak into the control group's experience. +- Social products. A treatment user's changed behavior affects the experience of users they interact with, regardless of which group those friends are in. +- Supply-constrained features. When supply is limited, treatment users compete with control users for the same scarce resource, and the test cannot cleanly separate treatment effect from substitution. +- Notification systems. A treatment that increases notification volume changes user behavior across the whole platform, not just in the treatment cell. + +The "interference dampens lift" pattern is the most common version. In marketplace experiments, if your treatment looks small, the true effect (in the absence of interference) may be 2x to 3x larger than what the standard A/B test reports. Killing a winning test because the leaked-into-control lift looked small is a common mistake. + +Detection methods: + +- Switchback experiments. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control, etc.). Eliminates cross-user interference within each window; requires careful temporal modeling. +- Cluster randomization. Assign whole units (cities, markets, friend groups) rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. +- Geographic experiments. Launch in some regions, hold others. Slow and expensive but interference-clean. + +When in doubt about whether interference is present, run a small cluster-randomized version as a check. If the cluster-randomized lift is much larger than the user-randomized lift, you have evidence of interference and should rerun the main test as cluster-randomized. + +--- + +## Dashboard metric vs experiment metric reconciliation + +The scenario: your business intelligence dashboard shows revenue grew 8% last week. Your experiment platform shows the treatment lifted revenue 2%. How can both be true? + +Likely answers, ranked by frequency: + +- Different denominators. The dashboard shows all users; the experiment shows just enrolled users. Most experiments enroll a subset; the lift only applies to that subset. +- Different time windows. The dashboard is rolling 7 days; the experiment is fixed start to end. The two windows can move independently. +- External effects. Marketing campaigns, seasonality, competitor activity, news cycles. The experiment correctly excludes these by random assignment; the dashboard reflects them. +- Selection effects. Who gets enrolled in the experiment matters. New users only? Logged-in users only? Users who passed a feature flag check? Each filter changes the population the lift applies to. +- Different metric definitions. "Revenue" might be gross in one place and net of refunds in another. "Conversions" might count differently across systems. + +Reconciliation discipline: never report experiment results as "the feature drove $X in revenue this week." Always report as "the feature lifted enrolled-user revenue Y% during the test period." The first phrasing implies a company-wide impact that the experiment cannot measure; the second phrasing is precise about what the experiment actually showed. + +The "blended attribution" trap is the most common reconciliation failure. PM takes the experiment lift (say +2% revenue per user) and multiplies by the total user base for a company-wide impact estimate ("$10M in incremental revenue"). This is wrong twice over. The lift only applies to enrolled users (typically 10% to 50% of the base). Even within the enrolled group, the lift was measured during the test conditions; long-term and at full scale, the effect can be different. The right phrasing is "during the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control." Then leadership can do the careful arithmetic of how that translates at full launch. + +For deeper reconciliation patterns and stakeholder-facing language, see [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). + +--- + +## Long-term effect estimation + +Most A/B tests run for two to four weeks. Many feature decisions need a thirty- to ninety-day understanding because behavior changes over longer windows: novelty fades, primacy fades, retention impacts emerge, network effects compound. + +Three patterns for long-term measurement: + +- Holdout groups. Keep a percentage of users (often 5% to 10%) on the control treatment for thirty or more days post-launch. Compare their long-term behavior to the launched-to users. The comparison measures the long-term effect cleanly because the holdout was randomized at the same time as the original test. +- Geo experiments. Launch the change in some markets and hold others. Measure long-term differences across market pairs. Slow, expensive, and the markets need to be comparable, but interference-clean and capable of measuring effects that user-randomization cannot. +- Difference-in-differences (diff-in-diff). Pre-launch versus post-launch measurement in a treated market versus a control market. Useful when you cannot randomize at all (regulatory rollouts, partner-specific changes). Weaker than randomized methods but defensible when randomization is impossible. + +Practical heuristic: any feature with novelty risk (new UI, new mechanic, new pricing, new notification cadence) deserves a thirty-day holdout. Set it up at launch, not later; setting it up later requires unwinding the launch and is rarely done in practice. The cost of the holdout is small (a small percentage of users on the old experience for a month); the value is the ability to detect long-term degradation before it compounds. + +--- + +## Common interpretation failures + +Rapid-fire reference. Each pattern is described in more detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). + +- "P equals 0.04, ship it." No consideration of CI width, magnitude, or guardrails. Significance is a necessary condition, not a sufficient one. +- "We saw +5% on day 3, ending early." Peeking, novelty effect, or both. Day-3 lifts are routinely larger than day-14 lifts; ending early ships noise. +- "The new flow worked for power users (post-hoc segment)." Noise mining. The segment was found by slicing the data multiple ways; the apparent lift will not replicate. +- "Our experiment said +2%, but launch only delivered +0.5%." Often the experiment was correct: the lift applied to enrolled users in test conditions, and at full launch the effect is diluted by non-enrolled users, novelty fade, or interference effects the test could not capture. +- "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail violation that was reframed as "no signal." If retention is a guardrail, the guardrail is binding; "we did not see a clear signal" is not the same as "we have evidence of safety." +- "We CUPED-adjusted away a real treatment effect." CUPED reduces variance, not the point estimate. If the lift looked smaller after CUPED, the unadjusted lift was probably noise that CUPED correctly removed. Trust the adjusted version. +- "Two segments showed opposite effects; we shipped to the better segment." Likely overfitting unless both segments were pre-registered and the targeting infrastructure exists. Re-test before shipping. +- "We ran the test, it was inconclusive, but the trend was directional so we shipped." Inconclusive is inconclusive. Directional patterns are not evidence; they are wishful reading of noise. + +--- + +## The framework: 14 considerations for trustworthy experiment interpretation + +Trustworthy interpretation sits at the intersection of fourteen considerations. Each is covered in detail in its own section above. + +1. Result panel completeness. The panel exposes variants, allocation, per-variant metrics, lifts, significance, variance reduction, guardrails, segments, time series, and status. Missing pieces are red flags. +2. Confidence interval reading. Width matters more than center. Five practical decision rules cover the cases where CI excludes zero, includes zero narrowly, and includes zero widely. +3. P-value semantics. The probability of seeing the lift if the null is true. Not the probability that the treatment works. Always read alongside the CI. +4. Multiple testing corrections. Bonferroni for family-wise control, BH for false discovery rate. Pre-register primary metrics and segments; treat the rest as exploratory. +5. Sequential testing math. Always-valid p-values and anytime-valid CIs survive peeking. Fixed-horizon p-values inflate false positives under daily monitoring. +6. CUPED variance reduction. Same point estimate, narrower CI. Use whenever pre-experiment data is available and informative. +7. Heterogeneous treatment effects. Pre-register segments. Treat post-hoc segment effects as hypotheses for follow-up tests, not as ship signals. +8. Ratio metrics. Use delta method or bootstrap. Naive proportion estimators understate variance and inflate false positives. +9. Bayesian vs frequentist. Pick one per experiment and stick with it. Both produce similar ship decisions when the experiment was designed correctly. +10. Network effects and SUTVA. Marketplace and social products often violate SUTVA. Cluster randomization, switchback, or geographic experiments when interference is suspected. +11. Dashboard reconciliation. Different denominators, time windows, external effects, and metric definitions explain most disagreements between BI dashboards and experiment panels. +12. Long-term effect estimation. Holdouts, geo experiments, and diff-in-diff for effects that emerge over thirty to ninety days. +13. Common interpretation failures. A pattern catalog of the most frequent ways smart teams ship wrong things. +14. The discipline of inconclusive. The hardest call is "we do not have enough signal to ship." It is often the right call. + +The sections above expand each consideration in turn. Read the relevant section before making the decision, not after. + +--- + +## Reference files + +- [`references/confidence-interval-cheatsheet.md`](references/confidence-interval-cheatsheet.md). How to read a CI, what to ignore, the five decision rules with worked examples for each. +- [`references/p-value-interpretation-guide.md`](references/p-value-interpretation-guide.md). What it means, what people pretend it means, the 0.05 convention, the peeking problem, and the multiple-testing context. +- [`references/statistical-method-reference.md`](references/statistical-method-reference.md). CUPED, the delta method, sequential testing methods (mSPRT, group sequential, anytime-valid), HTE handling, multiple testing corrections, cluster randomization. The technical reference for analysts. +- [`references/dashboard-vs-experiment-reconciliation.md`](references/dashboard-vs-experiment-reconciliation.md). Why the BI number does not match the experiment number, the blended-attribution trap, and how to communicate the difference to non-statistical stakeholders. +- [`references/result-presentation-templates.md`](references/result-presentation-templates.md). Five templates for stakeholder communication: clear win, clear loss, inconclusive (the most common, hardest), mixed (positive primary with ambiguous guardrail), and long-term holdout report. +- [`references/analytics-platform-comparison.md`](references/analytics-platform-comparison.md). Profiles of seven major platforms (Statsig, PostHog, Optimizely, GrowthBook, Eppo, Amplitude, Kameleoon) covering what each exposes, what each hides, and the gotchas in each. +- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md). Fifteen-plus failure patterns: name, symptom, root cause, fix, prevention. + +--- + +## Closing: the courage to call it inconclusive + +Most experiment results are not clear ship-or-kill. They are inconclusive: lift exists but the CI straddles zero; lift is real but does not justify the implementation cost; lift is significant but a guardrail is concerning; lift looks great in one segment but the segment is small or the targeting infrastructure does not exist. + +The hardest decision a PM makes in a given week is often "we do not have enough signal to ship." The temptation to lower the bar after seeing the result is enormous. The discipline of saying "inconclusive" is the discipline of caring about being right more than being decisive. + +The same discipline applies to analysts. The temptation to slice the data one more way until something looks significant, to apply one more variance reduction technique, to switch from frequentist to Bayesian mid-test, is constant. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. The result is not "we found a real effect"; the result is "we ran enough analytical knobs that something looked significant." + +Inconclusive is a valid outcome. The lesson, if there is one, is for the next hypothesis: the effect is smaller than expected, the segment matters, the test was underpowered, the metric was the wrong one. Use the inconclusive result to design a better next test. Do not retrofit a story onto the current one. + +For pre-experiment design discipline, see the `experiment-design` skill. For the operational mechanics of feature flags that deliver the variants, see the `feature-flagging` skill. For platform-specific MCP commands and example prompts, consult the chosen platform's documentation. diff --git a/skills/experimentation-analytics/references/analytics-platform-comparison.md b/skills/experimentation-analytics/references/analytics-platform-comparison.md new file mode 100644 index 0000000..a8c3504 --- /dev/null +++ b/skills/experimentation-analytics/references/analytics-platform-comparison.md @@ -0,0 +1,147 @@ +# Analytics platform comparison + +Profiles of seven major experimentation platforms covering what each exposes, what each hides, and the gotchas in each. For MCP setup, auth, and example prompts, consult each platform's official documentation. + +The categorization below is for analytics surface area specifically. All seven platforms are competent at running experiments; the difference is what they expose on the result panel and how the math under the hood handles edge cases. + +--- + +## Statsig + +Statistical defaults. Among the most rigorous in the category. Always-valid p-values (sequential testing) by default. CUPED variance reduction available and easy to enable. Delta method for ratio metrics. Comprehensive HTE analysis with pre-registered and exploratory modes. + +What is exposed. Per-variant metrics with CIs, lift point estimate, always-valid p-value, sample size, variance reduction technique applied, guardrail status, segment results for pre-registered segments, time series of the lift across the test window. + +What can be hidden by default. Some advanced configuration is buried in the UI; defaults are sensible but worth confirming. The "topline metrics" view simplifies away the CI in some contexts. + +Gotchas. + +- Always-valid p-values are wider than fixed-horizon by design. Teams new to sequential testing sometimes interpret "less significant" as "weaker effect" rather than "peek-safe math." +- The auto-generated guardrail metrics catch some categories well (latency, error rate) and miss others (business-critical metrics specific to your product). Augment with custom guardrails. +- The "experiment hub" view groups results across multiple experiments and can mask single-experiment subtlety. + +Where it shines. Mid-stage to late-stage product teams running many concurrent experiments where peek-safety and variance reduction matter. The default rigor saves teams from common mistakes without requiring statistical expertise. + +--- + +## PostHog + +Statistical defaults. Solid for the open-source experimentation category. Frequentist by default; Bayesian available. Variance reduction via "stats engine" configuration. Sequential testing in some experiment types. + +What is exposed. Per-variant metrics, CIs, p-values, sample size, time series, segment results. + +What can be hidden. The newer "stats engine" updates change defaults across versions; what you see depends on the deployment version. Older deployments may use less-rigorous defaults. + +Gotchas. + +- Self-hosted vs cloud can differ in stats engine version. Confirm the version when interpreting numbers. +- The "winner" badge can appear on results that are technically significant but practically tiny. Always read the CI. +- Bayesian and frequentist views can coexist for the same experiment; use one consistently per experiment. + +Where it shines. Teams that want experimentation embedded in their analytics platform rather than separate. PostHog's strength is the integration of feature flags, experiments, session recording, and product analytics in one place. + +--- + +## Optimizely + +Statistical defaults. Enterprise-grade rigor. Stats Engine includes sequential testing, ratio-aware variance estimation, and configurable significance thresholds. Long track record in the category. + +What is exposed. Comprehensive per-variant statistics, configurable significance thresholds, sequential testing labels, sample size, segment analysis with pre-registration. + +What can be hidden. Configuration depth means defaults vary by account setup. Confirm with the platform admin which defaults are in play for your project. + +Gotchas. + +- The classic Optimizely product (Web Experimentation) and the newer products (Feature Experimentation, Personalization) have different stats engines. Know which product your team is on. +- Enterprise pricing can mean limited license seats; non-statistician PMs sometimes work from screenshots taken by analysts, which loses interactive panel context. +- The "lift" display can default to relative percent without the absolute number; both matter. + +Where it shines. Larger organizations with established experimentation practices, regulated contexts where the rigorous track record matters, and teams that need extensive personalization alongside experimentation. + +--- + +## GrowthBook + +Statistical defaults. Open-source-first, warehouse-native. Explicit choice between Bayesian and frequentist. Sequential testing via mSPRT. CUPED supported. + +What is exposed. Per-variant metrics with CIs, lift, significance, variance reduction, guardrails, segment results. + +What can be hidden. Because GrowthBook runs on top of your data warehouse, the metric definitions live in your SQL; verify them when reading results. A subtle metric query change can shift results without anyone noticing. + +Gotchas. + +- Warehouse latency affects how fresh the result panel is. A daily batch is common; treat panel data as up to one day stale. +- Custom metrics defined in SQL can drift from dashboard definitions of the same metric. Reconcile carefully. +- The "experiment health checks" surface assignment imbalance and other quality issues; pay attention when they fire. + +Where it shines. Engineering-led teams that want experimentation tied directly to the warehouse and version-controlled metric definitions. The open-source core means full transparency on the math. + +--- + +## Eppo + +Statistical defaults. Best-in-class statistical defaults among the platforms. Bayesian and frequentist supported, with Bayesian as the default for most use cases. Sequential CIs available. CUPED supported. Delta method for ratio metrics. Strong HTE analysis. + +What is exposed. Per-variant metrics with credible intervals (Bayesian) or CIs (frequentist), probability of being best, posterior distributions, lift, guardrails, segments. + +What can be hidden. The Bayesian default produces "probability variant B is best" rather than a p-value, which can confuse stakeholders trained on frequentist conventions. Switch to frequentist if your team's vocabulary is p-value-based; do not switch mid-experiment. + +Gotchas. + +- Bayesian probabilities and frequentist p-values answer different questions; do not translate one into the other naively. +- Eppo's "decision support" feature recommends actions based on the result; treat the recommendation as input, not as the decision. +- Warehouse-native like GrowthBook; same caveats about metric definition drift. + +Where it shines. Data-team-led organizations that want statistical rigor as a default. Eppo's design philosophy is "make it hard to do the wrong thing"; the defaults reflect that. + +--- + +## Amplitude (Experiment) + +Statistical defaults. Behavioral analytics first, experimentation second. Frequentist defaults; sequential testing available. Variance reduction supported. + +What is exposed. Per-variant metrics with CIs, p-values, sample size, segment analysis, guardrails. Tightly integrated with Amplitude's behavioral analytics surface. + +What can be hidden. Some statistical configuration options are less prominent than in Statsig or Eppo; defaults are reasonable but worth confirming. + +Gotchas. + +- Strength is the integration with behavioral analytics, not the rigor of the experimentation engine. For teams that prioritize statistical sophistication, the engine is competent but not the strongest. +- Amplitude's "insights" auto-generate from event data; the same flexibility that makes them useful makes it easy to slice into noise. +- Experiment results can be viewed alongside cohort and funnel analyses; this is powerful and risky (post-hoc cohort definitions are noise mining). + +Where it shines. Product teams already invested in Amplitude for behavioral analytics. The integration of experiment results with the broader product analytics is the differentiator. + +--- + +## Kameleoon + +Statistical defaults. Frequentist with Bayesian options. CUPED and sequential testing supported. Strong personalization and AI-driven optimization features. + +What is exposed. Per-variant metrics with CIs, p-values, lift, segments, guardrails. + +What can be hidden. The personalization and AI optimization features can take experiment results and apply them automatically; verify which of your "experiments" are actually fully randomized A/B tests vs personalization rollouts. + +Gotchas. + +- The boundary between experiment and personalization can blur. Personalization decisions made by an AI engine are not the same as ship decisions made from a randomized A/B test. +- Less common in the US than the European market; documentation and community resources are more limited than for Statsig, PostHog, or Optimizely. +- Some advanced statistical features require specific subscription tiers. + +Where it shines. Teams running heavy personalization alongside experimentation, particularly in the European market. The personalization features are differentiated; the experimentation engine is competent. + +--- + +## Quick comparison + +\| Platform \| Sequential testing \| CUPED \| Delta method \| Bayesian option \| Strongest for \| +\|---\|---\|---\|---\|---\|---\| +\| Statsig \| Default \| Yes \| Yes \| Yes \| Multi-team experimentation rigor \| +\| PostHog \| Some types \| Configurable \| Yes \| Yes \| Embedded analytics + experiments \| +\| Optimizely \| Yes \| Yes \| Yes \| No (frequentist Stats Engine) \| Enterprise + personalization \| +\| GrowthBook \| Yes (mSPRT) \| Yes \| Yes \| Yes \| Warehouse-native, open source \| +\| Eppo \| Yes \| Yes \| Yes \| Default \| Statistical rigor by default \| +\| Amplitude \| Yes \| Yes \| Yes \| Yes \| Behavioral analytics integration \| +\| Kameleoon \| Yes \| Yes \| Yes \| Yes \| Personalization-heavy contexts \| + +The platform choice is rarely the bottleneck on getting experimentation right. All seven are competent. The bottleneck is the design discipline (covered in the `experiment-design` skill), the interpretation discipline (covered in this skill), and the operational discipline of the flag layer (covered in the `feature-flagging` skill). Pick the platform that fits the team's existing stack and skill mix; spend the effort on the disciplines. diff --git a/skills/experimentation-analytics/references/common-interpretation-failures.md b/skills/experimentation-analytics/references/common-interpretation-failures.md new file mode 100644 index 0000000..86c27fb --- /dev/null +++ b/skills/experimentation-analytics/references/common-interpretation-failures.md @@ -0,0 +1,203 @@ +# Common interpretation failures + +Fifteen-plus failure patterns that produce confidently wrong shipping decisions. Each pattern is described as: name, symptom (what it looks like in the panel or the discussion), root cause (why it happens), fix (what to do this time), prevention (how to avoid it next time). + +--- + +## Pattern 1: P-value worship + +Symptom. "P equals 0.04, ship it." No discussion of CI width, magnitude, or guardrails. + +Root cause. Treating statistical significance as a binary truth. The p-value answers one specific question (how surprising is this data under the null) and people use it to answer all questions. + +Fix. Always pair the p-value with the CI on the lift and the guardrail status. A significant p-value with a wide CI that includes practically tiny effects is not a ship signal. + +Prevention. Pre-commitment includes the MDE, not just the alpha. The decision rule should reference the lift magnitude relative to the MDE, not just the p-value. + +--- + +## Pattern 2: Early stop on a peek + +Symptom. Test ended on day 3 or day 5 because the result "looked great." Headline lift is 5% to 10%; later analysis shows the effect was much smaller. + +Root cause. Standard p-values inflate under peeking. Early-test lifts are systematically larger than late-test lifts due to regression to the mean and novelty effects. + +Fix. Re-run the test to the pre-committed end date. Treat the early result as suggestive only. If the platform supports always-valid p-values, those are peek-safe; otherwise, do not stop early. + +Prevention. Pre-commit the analysis date at launch. If the platform offers sequential testing, enable it. If not, do not look at intermediate results. + +--- + +## Pattern 3: Post-hoc segment mining + +Symptom. "The new flow worked for power users on Android in the EU on weekends." The segment was discovered by slicing the data many ways looking for an effect. + +Root cause. Multiple comparisons. With enough segments, some will show a "significant" effect purely by chance. The pattern is real for the test data; it does not replicate. + +Fix. Treat the post-hoc segment finding as a hypothesis for a follow-up test, not as a ship signal. Pre-register the segment in the new test and run it cleanly. + +Prevention. Pre-register segments at design time. Two or three is plenty; ten is overfitting waiting to happen. Treat any segment not in the pre-registration list as exploratory. + +--- + +## Pattern 4: Launch dilution misread + +Symptom. "Our experiment said +2%, but launch only delivered +0.5%. The experiment was wrong." + +Root cause. The experiment lift applied to enrolled users in test conditions. Launch dilution from non-enrolled users, novelty fade, and interference effects routinely produce smaller production effects than test effects. The experiment was usually correct; the production measurement is correctly capturing the diluted effect. + +Fix. Compare apples to apples: the launch effect on the same enrolled-user population, in the same conditions. If the launch effect on enrolled users matches the test, the experiment was right; the dashboard sees a smaller number because the dashboard includes everyone. + +Prevention. Communicate experiment results in enrolled-user terms, not extrapolated to the full base. The blended-attribution trap is the source of most "experiment wrong" complaints. + +--- + +## Pattern 5: Guardrail reframing + +Symptom. "Revenue went up but the CI for retention straddled zero so we ignored it." A guardrail movement that was reframed as "no signal" rather than treated as binding. + +Root cause. The guardrail was pre-committed but the team did not pre-commit a clear rule for "what counts as a guardrail violation." A wide CI on the guardrail leaves room for interpretation; the interpretation usually favors shipping. + +Fix. If retention is a guardrail, the guardrail binds. "We did not see a clear signal" is not the same as "we have evidence of safety." A wide guardrail CI means the test was underpowered for the guardrail; the right answer is more sample, not "ship anyway." + +Prevention. At pre-commitment, define guardrail rules as: "ship only if the CI on the guardrail clearly excludes a [X percent] degradation." Then apply the rule mechanically when results come in. + +--- + +## Pattern 6: CUPED misinterpretation + +Symptom. "We CUPED-adjusted away a real treatment effect. Let us report the unadjusted version." OR "The unadjusted lift is bigger; CUPED is hiding our win." + +Root cause. Misunderstanding what CUPED does. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior. + +Fix. Trust the CUPED-adjusted estimate. If the estimate is smaller and the CI is narrower, the CUPED estimate is closer to the true effect. + +Prevention. Educate the team on what CUPED does before enabling it. The first time the unadjusted and adjusted numbers diverge, walk through why. + +--- + +## Pattern 7: Opposite-segment shipping + +Symptom. "Two segments showed opposite effects; we shipped to the better segment." Often without re-testing or without infrastructure to support segment-specific behavior. + +Root cause. Post-hoc segment discovery (most common) or pre-registered segments where the targeting infrastructure does not exist. Either way, segment-only shipping is a significant commitment that requires more evidence than a single observation. + +Fix. Treat the segment finding as a hypothesis for a follow-up test. Confirm the effect with an appropriately powered re-test. Build the targeting infrastructure with eyes open about ongoing maintenance cost. + +Prevention. Pre-register segments. Build the targeting infrastructure separately, before any segment-specific shipping decision; do not let the decision force the infrastructure into existence under deadline pressure. + +--- + +## Pattern 8: Directional ship + +Symptom. "The result was technically inconclusive, but the trend was directional so we shipped." + +Root cause. Inconclusive is hard to communicate; directional language sounds more decisive. The team substitutes the appearance of evidence for actual evidence. + +Fix. Inconclusive is inconclusive. The directional pattern is wishful reading of noise. Do not ship; either run a bigger test or kill the hypothesis. + +Prevention. Pre-commit decision rules that map each possible result to a ship-or-kill decision. The inconclusive case should map to "do not ship" by default. Discussions of "directional" outcomes are a sign that pre-commitment was incomplete or is being ignored. + +--- + +## Pattern 9: Mid-test methodology switch + +Symptom. Test was running with frequentist analysis; results were ambiguous; team switched to Bayesian (or vice versa) and the new view "shows we should ship." + +Root cause. Different methodologies can produce different ship recommendations on the same data, particularly near the significance threshold. Switching mid-flight to find the more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +Fix. Stick with the methodology pre-committed at launch. If the result is ambiguous under the pre-committed method, that is the result. + +Prevention. Pre-commit the methodology along with the metric and the alpha. Document the choice in the experiment configuration so the change is visible if anyone tries. + +--- + +## Pattern 10: Ratio metric without delta method + +Symptom. Conversion rate or revenue per user with a CI that looks suspiciously narrow. The result panel shows significance that does not replicate at launch. + +Root cause. Naive variance estimation on ratio metrics produces incorrectly narrow CIs and inflated false positive rates. The platform did not use delta method, bootstrap, or another ratio-aware estimator. + +Fix. Re-analyze with a ratio-aware estimator. If the platform does not support one, export raw data and compute correctly in a notebook. + +Prevention. Verify your platform's variance estimator for ratio metrics during onboarding. If the answer is "standard t-test on proportions," consider migrating or implementing the correction yourself. + +--- + +## Pattern 11: Marketplace interference undercount + +Symptom. Marketplace experiment shows a small lift; team kills the test as not worth the effort. Later, a feature implemented for other reasons shows a much larger effect on the same metric. + +Root cause. SUTVA violation. In two-sided marketplaces, treatment users compete with control users for the same supply; the lift "leaks" into control. The standard A/B test undercounts the true effect, often by a factor of 2x to 3x. + +Fix. Re-run as cluster randomized (whole markets to treatment or control) or switchback. Compare the results to the user-randomized version to estimate the interference factor. + +Prevention. Identify SUTVA violation risk at design time. For marketplace, social, and supply-constrained features, default to cluster randomization or switchback unless interference is demonstrably negligible. + +--- + +## Pattern 12: Definition drift between systems + +Symptom. Experiment result shows +X% on conversion. Dashboard shows the launch having no effect on conversion. Investigation reveals the two systems define "conversion" differently. + +Root cause. Metric definitions live in different places (experiment platform, BI dashboard, data warehouse) and drift over time. Each definition individually makes sense; the comparison is meaningless. + +Fix. Reconcile the definitions before the next post-launch report. Pick one canonical definition and align both systems. + +Prevention. Centralize metric definitions (semantic layer, dbt model, shared SQL library). Audit all "the same metric" usages quarterly. + +--- + +## Pattern 13: Confounded test window + +Symptom. Test ran during a marketing campaign, a product launch, an outage, or a holiday. The result is reported without acknowledging the external event. + +Root cause. Random assignment usually handles external events (treatment and control are equally affected). But if the external event affects the metric definition (campaign brings different user mix), the populations stop being comparable. + +Fix. Stratify the analysis by the relevant covariate (acquisition source for campaigns, date for outages). If the stratified analysis differs meaningfully from the pooled analysis, report the stratified version and explain. + +Prevention. Maintain a calendar of marketing campaigns, product launches, and known external events. Avoid scheduling sensitive tests during these windows. If unavoidable, plan the stratification at design time. + +--- + +## Pattern 14: Long-tail metric overweighted by outliers + +Symptom. Revenue per user shows a large lift driven by a few high-value users. The lift is "significant" but unstable across re-samples. + +Root cause. Long-tailed distributions (revenue, session length, content engagement) have a few users contributing disproportionately. Random assignment of those users to treatment or control can drive large apparent effects that do not represent the underlying treatment effect. + +Fix. Winsorize the metric (cap extreme values at the 99th percentile, for example) and re-analyze. If the winsorized result is materially different from the raw result, the outliers were driving the effect. + +Prevention. Pre-commit to a winsorization threshold for long-tailed metrics. Apply the same threshold across treatment and control. Document the choice. + +--- + +## Pattern 15: Significance from sample size, not effect + +Symptom. "P equals 0.001, very significant." CI on the lift is [+0.1%, +0.3%]. Magnitude is tiny. + +Root cause. With enough sample, even tiny effects produce small p-values. Significance is not the same as magnitude. Shipping a 0.2% lift because "p was tiny" is a misuse of the framework. + +Fix. Read the CI alongside the p-value. If the practical lift is too small to matter, do not ship regardless of significance. + +Prevention. Pre-commit to an MDE (minimum detectable effect) as part of the design. If the observed lift is below the MDE, the test was overpowered and the result, while real, is not actionable. + +--- + +## Pattern 16: Overcorrection panic + +Symptom. Result shows a clean lift on the primary metric. Team adds five new metrics post-hoc and applies Bonferroni correction across all of them. Now the primary metric is "not significant." + +Root cause. Multiple testing corrections apply to pre-registered comparisons, not to post-hoc analyses meant to "stress-test" the result. Adding metrics after seeing the result and then correcting is statistically incoherent. + +Fix. Apply corrections only to the pre-registered comparison set. Post-hoc metrics are exploratory and should be reported as such, without claiming to update the primary inference. + +Prevention. Pre-register the metric set at design time. Treat any metric not on the list as exploratory. + +--- + +## The pattern behind the patterns + +Most of these failures share a common shape: the team had a hypothesis they wanted to confirm, the result was less clean than hoped, and the team applied an analytical knob (slice, switch methodology, drop outliers, reframe the guardrail, peek early) to make the result look cleaner. Each individual move feels like a small judgment call. Cumulatively they destroy the integrity of the analysis. + +The defense against this pattern is pre-commitment. The defense against pre-commitment being weakened over time is documenting the pre-commitment somewhere immutable (PR description, signed Slack message, pinned ticket) and applying it mechanically when results come in. The pre-commitment is not the team's enemy; it is the team's protection from its own future motivated reasoning. diff --git a/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md b/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md new file mode 100644 index 0000000..1f3e1ec --- /dev/null +++ b/skills/experimentation-analytics/references/confidence-interval-cheatsheet.md @@ -0,0 +1,107 @@ +# Confidence interval cheatsheet + +The CI on the lift is the single most important number on the result panel. This cheatsheet covers what it means, what to ignore, and the five decision rules that map a CI to a ship, kill, or wait decision. + +--- + +## What the CI is + +A 95% confidence interval (CI) on a lift estimate is a range of values that, under repeated sampling of the experiment, would contain the true effect 95% of the time. The point estimate (the center) is your best single guess at the true effect. The width is your humility about how much you actually know. + +Three common CI shapes you will see on result panels: + +- Symmetric. Lift estimate +3% with CI [+1%, +5%]. The middle is the best guess; the bounds are equidistant. +- Skewed. Lift estimate +3% with CI [-0.5%, +8%]. Common with small samples or distributions with long tails. The point estimate is still the best guess; the asymmetry tells you the data is consistent with a wider range on the upside than the downside. +- Always-valid (sequential). Same shape as a normal CI but wider by design. Survives daily peeking. If your panel says "anytime-valid CI," that is what you are looking at. + +--- + +## What to read first + +Width before center. A narrow CI tells you a lot about the true effect; a wide CI tells you very little, regardless of where it is centered. A point estimate of +5% with CI [+4.5%, +5.5%] is a precise estimate of a real lift. A point estimate of +5% with CI [-3%, +13%] is essentially "we have no idea, somewhere between a meaningful loss and a huge win." + +The position of zero relative to the CI. If zero is well outside the CI on the positive side, you have a real positive effect. If zero is well outside on the negative side, you have a real harm. If zero is inside the CI, you cannot rule out "no effect." + +--- + +## What to ignore + +The point estimate alone. Without the CI, the point estimate is a single number with no honesty about how much it could move under different sampling. Reading "lift was +3%" without the CI is reading half the result. + +The p-value alone. P-values tell you about the strength of evidence against the null; CIs tell you about the magnitude of the effect. Both matter. A tiny lift with p equals 0.001 is technically significant and not worth shipping. A big lift with p equals 0.10 is technically inconclusive and worth a follow-up test. + +The "statistically significant" label as a binary. Most platforms color-code significance as a green check or a red X. The label is fine as a heuristic; the underlying CI is what you should defend the decision on. + +--- + +## The five decision rules + +### Rule 1: CI all-positive, lift above MDE. Ship. + +Example. MDE was 2%; CI is [+3%, +6%]. + +The lower bound of the CI exceeds the MDE you committed to detect. The data is inconsistent with no effect AND inconsistent with a trivial effect. Confidence is high, magnitude is meaningful. Ship. + +Confirm guardrails are clean before filing the launch. + +### Rule 2: CI all-positive, lift below MDE. Probably do not ship. + +Example. MDE was 5%; CI is [+0.5%, +1.2%]. + +The lift is real (CI excludes zero) but small (entire CI is below the MDE). The test was overpowered for the question, or the effect is smaller than expected. Real but tiny lifts are rarely worth shipping; the engineering, testing, and cognitive surface area exceeds the gain. + +The exception: changes that are essentially free to ship and maintain. A copy tweak with a +0.5% lift might be worth shipping; a feature requiring ongoing infrastructure with the same lift is not. + +### Rule 3: CI all-negative. Kill. + +Example. CI is [-4%, -1%]. + +The data is inconsistent with no effect and inconsistent with a positive effect. The change made things worse with high confidence. Kill the test. Document the lesson if the result is surprising; sometimes the lesson is "users wanted what we already had." + +### Rule 4: CI straddles zero, narrow. Real null result. + +Example. CI is [-0.5%, +0.8%]. + +Zero is inside the CI, but so is everything else within a small range. The data is consistent with no effect and inconsistent with any meaningful positive or negative effect. This is a real "we tested and it does not move the metric" result. Useful information; do not ship for "lift" reasons (you found none) but do not panic about harm either. + +The product question becomes: does the change have value beyond the metric we measured (brand consistency, code maintainability, accessibility)? If yes, ship for those reasons. If no, do not ship. + +### Rule 5: CI straddles zero, wide. Inconclusive. + +Example. CI is [-5%, +8%]. + +Zero is inside the CI and so is a wide range of meaningful effects in both directions. The data does not distinguish "moderate win" from "no effect" from "moderate loss." The test was underpowered for the question. + +Three follow-up paths: + +- Run longer or run bigger to narrow the CI. +- Make the treatment bolder so the expected effect is larger and detectable at the available traffic. +- Accept that the question cannot be answered cleanly and move on. + +The temptation is to ship anyway because "the point estimate was favorable." The point estimate is not evidence when the CI is this wide. Resist. + +--- + +## Pairing the CI with guardrails + +The CI on the primary metric is where the ship decision lives. The CI on each guardrail is where the safety check lives. Read both. + +A guardrail CI that excludes the threshold of concern is clean. For example, if retention is a guardrail and you require it to not drop more than 1%, a guardrail CI of [-0.3%, +0.4%] is clean. A CI of [-2%, +0.5%] is not clean even though it includes zero, because the lower bound exceeds the threshold. + +Wide guardrail CIs mean the test was underpowered for the guardrail. That is a real problem: you cannot claim safety on a metric you did not measure precisely. The fix is more sample, not "the point estimate looked fine." + +--- + +## Worked example: the "looks great" trap + +Setup. PM running a checkout redesign. Pre-committed primary: revenue per visitor. MDE: 3%. Guardrail: refund rate not increasing by more than 0.5%. + +Day 5. Result panel shows revenue per visitor +6%, p equals 0.03, CI [+0.5%, +11.5%]. Refund rate +0.3%, CI [-0.4%, +1.0%]. + +The temptation. Both metrics moved favorably; the headline is significant. PM proposes ending the test early. + +The CI read. Revenue CI [+0.5%, +11.5%] has a lower bound (+0.5%) below the MDE (+3%). The data is consistent with a real but tiny lift, not just the headline +6%. The guardrail CI [-0.4%, +1.0%] has an upper bound (+1.0%) that exceeds the threshold (+0.5%); the test cannot rule out a guardrail violation. + +The right call. Do not ship yet. Run to the pre-committed end date. Both CIs need to narrow before the ship case is defensible. The day-5 read is suggestive but not decisive; it is exactly the case the pre-commitment discipline was designed to handle. + +Common variant. PM ships anyway because "the trend is positive." Three weeks later the launch shows a refund rate increase that wipes out the revenue gain. The day-5 CI was warning of this exact possibility; the team did not read the width. diff --git a/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md b/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md new file mode 100644 index 0000000..072b959 --- /dev/null +++ b/skills/experimentation-analytics/references/dashboard-vs-experiment-reconciliation.md @@ -0,0 +1,87 @@ +# Dashboard vs experiment reconciliation + +The scenario: the BI dashboard shows revenue grew 8% last week, the experiment platform shows the treatment lifted revenue 2%, and an executive asks how both can be true. This reference covers the common reasons numbers disagree, the blended-attribution trap, and how to communicate the difference. + +--- + +## Why numbers disagree (in order of frequency) + +Different denominators. The dashboard is computed across all users (or all sessions, or all transactions). The experiment is computed across enrolled users only. If 30% of users are enrolled in the experiment, the experiment lift applies to roughly 30% of the metric base; the dashboard sees the entire base. A 2% lift on the enrolled 30% looks like roughly 0.6% on the dashboard, even if everything is working perfectly. + +Different time windows. The dashboard shows rolling seven days; the experiment shows fixed start to end. Comparing a moving window to a fixed window is comparing two different summaries of overlapping but distinct data. + +External effects. Marketing campaigns, seasonality, news cycles, competitor moves, weather. The experiment correctly excludes these by random assignment (treatment and control see the same external effects, so they cancel in the lift estimate). The dashboard reflects them in full. The dashboard moving up has nothing to do with the experiment moving up. + +Selection effects in enrollment. Who is enrolled matters. New users only? Logged-in only? Users who passed a feature flag check? Each filter changes the population the experiment lift applies to, and changes how that population's behavior compares to the dashboard total. + +Different metric definitions. "Revenue" might be gross in the dashboard and net of refunds in the experiment. "Conversions" might count differently across systems (does a re-purchase count? a subscription renewal? a free trial activation?). Definitional drift between systems is common and almost always under-investigated. + +Pipeline lag. The dashboard is real-time or near-real-time. The experiment is computed on a daily batch with attribution windows that delay the metric by hours or days. Comparing a real-time number to a batched-and-attributed number is comparing two different versions of the truth. + +Different attribution models. First-touch vs last-touch vs multi-touch attribution can produce wildly different "revenue" numbers from the same underlying events. The dashboard and the experiment might use different models without anyone realizing. + +--- + +## The blended attribution trap + +The most common reconciliation failure: take the experiment lift and multiply by the total user base for company-wide impact. + +The wrong calculation. Experiment shows +2% revenue per user. Total active users: 5 million. "The feature drove $X million in incremental revenue." + +Why it is wrong, twice over. + +- The lift only applies to enrolled users, not the total base. If 30% of users are enrolled, the in-test impact is roughly 30% of what the multiplication suggests. +- Even within enrolled users, the lift was measured during the test conditions. Long-term and at full scale, the effect can be smaller (novelty fade, interference effects, market saturation) or sometimes larger (network effects that compound, learning effects). + +The right framing. "During the four-week test, enrolled users (about 30% of the active base) showed a 2% revenue-per-user lift relative to control. Extrapolating to a full launch requires assumptions about how the effect translates at scale; the simple multiplication ignores those assumptions." + +The right framing is longer. Stakeholders sometimes push back on the precision. The precision is the point: the simple version is wrong, and shipping based on the simple version produces forecasts that do not materialize. + +--- + +## How to communicate to non-statistical stakeholders + +The temptation is to translate the experiment result into a single number that sounds like the dashboard. The translation is usually wrong because the two numbers are answering different questions. + +Better framings: + +- "The experiment is asking 'does this change move the metric for users who see it?' The dashboard is asking 'how is the metric trending overall?' Both can move independently and both can be true at the same time." +- "The experiment lift applies to enrolled users, in test conditions, during the test window. Translating to a launch forecast requires assumptions about scale, novelty, and interference." +- "If we ship to everyone, we expect the dashboard to move by roughly [X percent of the lift], plus or minus [a wide range], because of [specific assumptions]." + +Worse framings to avoid: + +- "The feature drove $X million in revenue this week." (Conflates the experiment lift with the dashboard movement.) +- "We hit our target." (When the target was set against the dashboard but the result is from the experiment.) +- "The lift was bigger in production than in the test." (Usually a sign of confounding, not vindication.) + +--- + +## When to dig into discrepancies vs accept them + +Dig in when: + +- The experiment shows a big effect and the dashboard shows nothing. The experiment is making a claim that the launch did not deliver. Either the experiment was wrong (selection effect, pipeline bug, confounder) or the launch is being measured wrong. +- The experiment shows nothing and the dashboard shows a big effect. The experiment is missing a real movement. Either the test was underpowered, the wrong population was enrolled, or the dashboard movement is from external factors. +- The directions disagree (experiment positive, dashboard negative). Almost always indicates a definitional drift or pipeline issue that needs investigation. + +Accept the discrepancy when: + +- The magnitudes are different but the directions agree. Usually a denominator or selection issue; document the explanation and move on. +- The dashboard is volatile and the experiment is stable. The dashboard reflects external noise the experiment correctly excludes. +- The dashboard is stable and the experiment showed a small effect. The launch effect is too small to detect in the dashboard's noise. + +--- + +## A reconciliation checklist for the moment of confusion + +When a stakeholder asks "why do these numbers not match?", run through this: + +1. Same metric definition? Confirm the experiment and dashboard are computing the metric the same way. Check the definitional doc for both. Ask the data team if there is no doc. +2. Same denominator? Confirm the experiment population and the dashboard population. Often they differ. +3. Same time window? Confirm the experiment window and the dashboard window are aligned (or explain why they are not). +4. Any external events? List campaigns, launches, outages, holidays during the test window. The dashboard reflects them; the experiment cancels them. +5. Any pipeline lag? Confirm both numbers are using the same attribution and the same data freshness. +6. Any selection effects? Who got enrolled and how? If enrollment was non-random (by feature flag check, by cohort), the experiment population is not representative of the dashboard population. + +If all six check out and the numbers still disagree by a meaningful amount, escalate to data engineering. There is probably a pipeline bug in one of the two systems. diff --git a/skills/experimentation-analytics/references/p-value-interpretation-guide.md b/skills/experimentation-analytics/references/p-value-interpretation-guide.md new file mode 100644 index 0000000..55e87f5 --- /dev/null +++ b/skills/experimentation-analytics/references/p-value-interpretation-guide.md @@ -0,0 +1,118 @@ +# P-value interpretation guide + +The p-value is the most-mentioned and most-misunderstood number on the result panel. This guide covers what it actually means, what people pretend it means, when the 0.05 cutoff binds and when it does not, and how to read p-values alongside the CI. + +--- + +## What the p-value is + +The p-value is the probability of observing the lift you saw (or one larger in magnitude), IF the true effect were zero. It is computed under the assumption that the treatment had no effect; the value tells you how surprised you should be by the observed data under that assumption. + +A p-value of 0.04 means: under the null hypothesis of no effect, you would see this much lift purely by chance about 4% of the time. A p-value of 0.001 means it would happen 0.1% of the time. Smaller p-values are stronger evidence against the null; larger p-values are weaker evidence. + +That is the whole technical definition. Everything else is interpretation, and most of it is wrong. + +--- + +## What the p-value is not + +These are the most common misinterpretations. Each one is wrong for a specific reason. + +"P equals 0.04 means 96% chance the treatment works." No. The p-value is computed under the assumption that the treatment does NOT work; it cannot tell you the probability that it does. The Bayesian probability of the alternative depends on the prior, which the p-value does not contain. + +"P equals 0.001 means the effect is huge." No. P-values are about the strength of evidence against the null, not the size of the effect. A tiny effect tested against a very large sample produces a tiny p-value. The CI tells you the size; the p-value tells you the certainty. + +"A significant result will replicate." Not necessarily. A p-value of 0.05 is associated with replication rates well below 50% in most published research. Statistical significance is one piece of evidence; reproducibility requires confirmation. + +"P greater than 0.05 means there is no effect." No. P-values cannot prove the null. A non-significant result means "we do not have enough evidence to reject no-effect," which is weaker than "no-effect is true." The CI tells you the practical conclusion: a wide CI straddling zero is "we do not know," while a narrow CI around zero is "the effect is small enough to call zero." + +"P equals 0.06 is much worse than p equals 0.04." No. The 0.05 cutoff is convention; the underlying evidence is roughly the same. Treating 0.06 as categorically different from 0.04 is theater unless you pre-committed to the cutoff. + +--- + +## The 0.05 convention + +Alpha equals 0.05 is the standard significance threshold by historical convention, not because the math says 0.05 is special. The convention is useful because it provides a shared reference point, and pre-committing to a threshold prevents post-hoc rationalization. + +Two valid uses of the threshold: + +- Pre-committed alpha. You declared at design time that you would ship if p was less than 0.05 and the CI excluded zero. Now apply the rule mechanically. If the result hit 0.04, follow the pre-commitment. +- Convention reference point. When communicating with stakeholders, "significant at the conventional 5% threshold" is a familiar phrasing. Use it as long as the underlying CI is also reported. + +Two invalid uses: + +- Post-hoc threshold games. Result is p equals 0.06; you decide that 0.10 is "good enough this time." This is p-hacking. +- Treating the threshold as a binary truth. Result is p equals 0.04; you ship without reading the CI. The threshold is necessary but not sufficient evidence to ship. + +--- + +## Always read the CI alongside the p-value + +The p-value tells you about the null hypothesis. The CI tells you about the magnitude. They answer different questions, and decisions need both answers. + +\| Scenario \| P-value \| CI on lift \| Decision \| +\|---\|---\|---\|---\| +\| Real, meaningful effect \| 0.001 \| [+3%, +6%] \| Ship if guardrails clean \| +\| Real but tiny effect \| 0.001 \| [+0.2%, +0.4%] \| Probably do not ship; magnitude too small \| +\| Suggestive but uncertain \| 0.08 \| [-0.5%, +12%] \| Inconclusive; run longer or kill \| +\| Inconclusive null \| 0.30 \| [-1%, +1%] \| Real null result; do not ship for lift reasons \| +\| Inconclusive wide \| 0.30 \| [-7%, +9%] \| Underpowered; not enough information \| + +Reading just the p-value loses the magnitude. Reading just the CI loses the certainty calibration. Both are routine on every result panel; both deserve attention. + +--- + +## The peeking problem + +Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. + +The math: at one analysis, alpha equals 5% means 5% false positive rate. At three analyses, it climbs toward 14%. At daily peeking on a four-week test, it can exceed 30%. The "significant" results you find by peeking are disproportionately false positives that will not replicate. + +Two fixes: + +- Sequential testing methods. Modern platforms (Statsig, Eppo, GrowthBook with mSPRT, parts of PostHog) report "always-valid" or "anytime-valid" p-values that survive peeking. The math is wider by design; the cost of peek-safety is some statistical efficiency. +- Pre-commitment. If your platform does not support sequential testing, declare the analysis date at launch and do not peek. If you must peek (some platforms make it hard not to), do not make decisions on intermediate peeks. + +If your panel says "p-value" without a qualifier, assume fixed-horizon. Treat early-peek results as suggestive only. + +--- + +## Multiple testing context + +A p-value of 0.05 means a 5% false positive rate per comparison. With twenty comparisons, you expect one false positive purely by chance. + +Where this matters: + +- Multiple variants (A vs B vs C vs D is three pairwise tests). +- Multiple metrics (primary plus six guardrails plus three secondary is ten chances). +- Multiple segments (ten segments times three metrics is thirty chances). + +Pre-register the primary metric and primary segment. Treat the rest as exploratory. A "significant" finding in a non-primary metric or non-primary segment requires either a larger effect, a follow-up test, or both before it justifies shipping. The discipline of pre-registration protects you from the multiple-testing trap better than any correction formula. + +When the platform applies a correction (Bonferroni, Benjamini-Hochberg) silently, the p-values you see have already been adjusted. Know which the platform applies by default; otherwise you may double-correct in your interpretation. + +--- + +## Bayesian alternatives + +Some platforms (Eppo by default, Statsig as a configuration option) report Bayesian probabilities rather than frequentist p-values. The vocabulary differs: + +- "Probability variant B is best": the Bayesian equivalent of multi-variant frequentist comparison. +- "Probability of beating control by at least X%": directly answers the magnitude question that frequentist p-values dance around. +- "Posterior credible interval": the Bayesian analogue of the confidence interval, with an interpretation closer to lay intuition ("there is a 95% chance the true effect is in this range"). + +For most PM contexts, both approaches produce similar ship decisions when the experiment was designed correctly. Pick one per experiment and stick with it. Switching mid-flight to chase a more favorable interpretation is the Bayesian-frequentist version of p-hacking. + +--- + +## Communicating p-values to non-technical stakeholders + +Stakeholders often want a one-sentence summary. The temptation is "p equals 0.04, so we should ship." The temptation is wrong because it loses the magnitude. + +Better one-liners: + +- "We saw a 4% lift in revenue per visitor; the data rules out no-effect and is consistent with a 2% to 6% true lift." +- "The test was inconclusive: the lift could be anywhere from a small loss to a moderate win." +- "We measured a small but real effect: about 0.5% lift, which is statistically detectable but probably not worth shipping." + +Each names the magnitude, the uncertainty, and the decision implication. None reduces the question to a p-value threshold check. diff --git a/skills/experimentation-analytics/references/result-presentation-templates.md b/skills/experimentation-analytics/references/result-presentation-templates.md new file mode 100644 index 0000000..a89bd8e --- /dev/null +++ b/skills/experimentation-analytics/references/result-presentation-templates.md @@ -0,0 +1,123 @@ +# Result presentation templates + +Five templates for stakeholder communication on experiment results. Each names the structure, the vocabulary, what to emphasize, and what to omit. Use the right template for the result you have, not the one that flatters the team. + +--- + +## Template 1: Clear win + +When to use. Primary metric moved past MDE, CI on lift excludes zero, all guardrails clean, pre-registered segments consistent. + +Structure. + +1. Headline. "We are shipping [feature]. The test showed a [X percent] lift in [primary metric] with [Y percent] confidence. Guardrails are clean." +2. The number. Point estimate of the lift, with the CI in parentheses. "Revenue per visitor lifted 4.2% (CI [+2.8%, +5.6%])." +3. Magnitude in business terms. "At our enrolled traffic, that is roughly [$Z] in incremental [period] revenue from this cohort. Full-launch impact depends on rollout assumptions." +4. Guardrails. One line per guardrail confirming it stayed within tolerance. +5. Decision and timing. "Filing the launch this week. Post-launch monitoring at days 7, 14, and 30." + +Vocabulary to use. "Real lift," "high confidence," "exceeds the threshold we committed to," "shipping." + +Vocabulary to avoid. Superlatives ("dramatic," "unprecedented," "transformative"). The number speaks; superlatives do not add to it. + +What to omit. Long discussion of why the test worked, deep statistical detail, exhaustive caveats. The headline result is clean; the writeup should be too. + +--- + +## Template 2: Clear loss + +When to use. Primary metric moved against expected direction with significance, OR a guardrail was violated. + +Structure. + +1. Headline. "We are not shipping [feature]. The test showed [a negative effect / a guardrail violation]." +2. The number. Point estimate and CI. Be precise about which metric showed the issue. +3. Likely cause, if known. Brief diagnosis: "Conversion dropped because users did not understand the new flow. Session recordings confirm confusion at step three." +4. What we learned. One or two sentences naming the lesson for the next hypothesis. +5. Decision and follow-up. "Killing the test. Filing the learning in the team retrospective. Considering [follow-up direction] as a next test." + +Vocabulary to use. "The test showed," "killing," "the change made things worse on [metric]," "we learned." + +Vocabulary to avoid. "Failed" applied to the team. "Setback." Defensive language. The test produced a clear answer; the team did its job. + +What to omit. Speculation about what would have happened with a different design. Excessive postmortem detail. The kill is the right decision; do not over-justify it. + +--- + +## Template 3: Inconclusive (the most common, hardest) + +When to use. Primary metric did not clearly move past MDE, CI is wide, OR guardrails are clean but signal is weak. The most frequent real outcome and the hardest to communicate without slipping into "we should ship anyway." + +Structure. + +1. Headline. "The test was inconclusive. We do not have enough signal to ship and we do not have enough signal to kill." +2. The number. Point estimate and the wide CI. Name the width: "Lift was +1.8%, but the CI is [-2.1%, +5.7%]; the data is consistent with a moderate win, no effect, or a moderate loss." +3. What we know vs what we do not. "We can rule out a large negative effect. We cannot distinguish a small positive effect from no effect. We cannot say whether shipping would help or hurt." +4. The three resolution paths. + + - Run bigger or longer: extend the test to narrow the CI. Cost: [time and traffic]. Benefit: a clearer answer. + - Make the treatment bolder: redesign with a larger expected effect, then re-test. Cost: design and engineering effort. Benefit: addresses the underlying mechanism rather than the measurement. + - Kill the idea: accept that the change does not produce a meaningfully detectable effect at our traffic. Cost: closing the hypothesis. Benefit: team time freed for higher-signal work. +5. Recommendation. Pick one path and explain why. +6. Decision. "Going with [path]. Re-evaluating in [timeframe]." + +Vocabulary to use. "Inconclusive," "the data does not distinguish," "we cannot confidently say," "the right call is to [chosen path]." + +Vocabulary to avoid. "Trending positive," "directional improvement," "looks promising." These are the phrases that get teams to ship inconclusive tests; they are wishful reading of noise. + +What to omit. Pleas to ship "since we are already here." Optimistic projections of what the lift "would be" with more sample. Alternative analyses that conveniently show significance. + +The hardest version of this template is the case where the team has invested in the hypothesis and the result is inconclusive. The temptation is to find a way to justify shipping. The discipline is to use the structure above and let the inconclusive result be inconclusive. + +--- + +## Template 4: Mixed result (positive primary, ambiguous guardrail) + +When to use. Primary metric moved past MDE with clean significance, but a guardrail metric showed concerning movement that did not clearly violate tolerance. + +Structure. + +1. Headline. "The primary metric moved as expected. A guardrail showed concerning movement; we are [shipping with monitoring / holding for further investigation]." +2. Primary metric result. Point estimate and CI. "Conversion lifted 5.1% (CI [+3.4%, +6.8%])." +3. Guardrail concern. Specific. "Refund rate point estimate moved +0.4%, with CI [-0.1%, +0.9%]. Pre-committed tolerance was no more than +0.5%. The CI does not clearly violate tolerance, but the upper bound is right at the threshold." +4. The interpretation question. "Pre-committed decision rule was 'do not ship if the guardrail CI excludes safe behavior.' The CI does not exclude safe behavior, but it does not exclude a violation either." +5. Recommendation with reasoning. Two valid paths: + + - Ship with extra monitoring: production behavior at +1, +2, +4 weeks specifically watching the guardrail. Roll back if it crosses tolerance in production. Acceptable when the primary lift is large and the guardrail risk is reversible. + - Hold and re-test: extend the test to narrow the guardrail CI. Acceptable when the primary lift is marginal or the guardrail is hard to monitor in production. +6. Decision. Pick the path. Document the guardrail-specific monitoring or the re-test plan. + +Vocabulary to use. "The guardrail CI does not clearly exclude tolerance," "shipping with intensified monitoring," "the pre-committed rule was." + +Vocabulary to avoid. "The guardrail did not move significantly" (when the CI does not exclude movement, do not pretend it did). "The primary lift outweighs the guardrail concern" (the guardrail was set as binding for a reason). + +What to omit. Reframing the guardrail as a "secondary metric" that does not need to bind. The guardrail was set during pre-commitment; it binds. + +--- + +## Template 5: Long-term holdout report (30 / 60 / 90 days post-launch) + +When to use. Reporting back on a feature that shipped with a holdout group, after the holdout period has elapsed. + +Structure. + +1. Headline. "[Feature] post-launch holdout report at [day count]. Long-term effect [confirms / diverges from / disconfirms] the test result." +2. Test result reminder. What the test showed at launch. "At launch, the test measured a +4% lift in [metric]." +3. Long-term result. What the holdout shows now. "At day 30, the launched cohort shows a +3.2% lift over the holdout (CI [+1.8%, +4.6%])." +4. Comparison. Direct: "The long-term effect is [in line with / smaller than / larger than] the test estimate. [If smaller: the difference is consistent with novelty fade / interference / dilution. If larger: the difference is consistent with network effects / learning effects.]" +5. Decision implications. "[Continue the launch as is / revisit the design / consider rollback]." +6. Holdout disposition. "[Releasing the holdout into the launched cohort / extending the holdout for another 30 days]." + +Vocabulary to use. "Long-term effect," "confirms / diverges from," "novelty fade," "we observe." + +Vocabulary to avoid. "Vindication" or "we were right." Long-term reports are about updating the prior, not declaring victory. + +What to omit. Excessive celebration of a confirmed lift. Excessive panic about a divergent lift. The report is information for the next decision; let the information drive it. + +--- + +## A note on the "we should report this differently" temptation + +When a result is inconclusive or mixed, there is always a way to slice the data, frame the writeup, or pick the chart that makes the result look more decisive. Resist. + +The cost of overstating an inconclusive result is shipping changes that do not work, eroding trust in the experimentation discipline, and accumulating production complexity for no gain. The cost of accurately reporting an inconclusive result is one round of disappointment from stakeholders who wanted a cleaner answer. The first cost compounds; the second does not. Use the right template for the actual result. diff --git a/skills/experimentation-analytics/references/statistical-method-reference.md b/skills/experimentation-analytics/references/statistical-method-reference.md new file mode 100644 index 0000000..bb11a4f --- /dev/null +++ b/skills/experimentation-analytics/references/statistical-method-reference.md @@ -0,0 +1,150 @@ +# Statistical method reference + +The technical reference for analysts. Covers the methods named in the [SKILL.md](../SKILL.md) with enough depth to verify a platform's implementation, recognize when a method is needed, and explain the choice to a skeptical reviewer. + +--- + +## CUPED (Controlled-experiment Using Pre-Experiment Data) + +What it does. Uses pre-experiment behavior of the same users to subtract out their baseline, leaving a cleaner signal of the treatment effect. Same point estimate as the unadjusted analysis; narrower CI. + +The math, in one paragraph. For each user, take their in-experiment metric value Y and their pre-experiment metric value X. Compute the regression coefficient theta that relates X to Y in the control group. Replace Y with Y minus theta times (X minus X-bar) for every user. Run the analysis on the adjusted Y. The variance of the adjusted Y is lower than the variance of Y by a factor proportional to the squared correlation between X and Y, which directly narrows the CI. + +Variance reduction in practice. Typical reduction is 30% to 50% for engagement metrics, 20% to 40% for revenue metrics, near zero for one-time conversions. Effective sample size roughly doubles when variance halves. + +When to use. + +- Metrics with high pre-experiment baseline variance (revenue per user, sessions per user, engagement minutes). +- Tests where users have meaningful history (logged-in users, users from before a certain date). +- Long-running products where pre-experiment behavior strongly predicts in-experiment behavior. + +When NOT to use. + +- Brand-new users with no pre-experiment data. +- One-time conversion metrics with no pre-experiment baseline. +- Tests where pre-experiment behavior is uncorrelated with the metric being moved (a notification redesign rarely correlates with prior revenue, for example). + +How to verify your platform implements it correctly. Ask: "Do you compute theta on control only, or on the pooled population?" Pooled is technically wrong (induces bias). Control-only is correct. "What pre-experiment window do you use?" Common defaults are 14 to 28 days; the choice should be documented. + +Common confusion. "CUPED made our lift smaller, so we should report the unadjusted version." Wrong. CUPED reduces variance, not the point estimate. If the lift looks smaller after CUPED, the unadjusted lift was probably inflated by chance correlation with pre-experiment behavior; the CUPED estimate is closer to the true effect. + +--- + +## The delta method + +What it does. Provides correct variance estimation for ratio metrics. Naive variance estimation on ratios produces incorrectly narrow CIs and inflated false positive rates. + +Why ratios are special. Standard variance formulas assume sums of independent observations. Ratios are functions of two correlated sums (numerator and denominator). The variance of a ratio depends on the variance of the numerator, the variance of the denominator, AND the covariance between them. Naive estimators ignore the denominator variance and the covariance. + +The math, in one paragraph. For a ratio R equals N divided by D, the delta method approximates the variance of R using a first-order Taylor expansion around the means of N and D. The result expresses Var(R) as a function of Var(N), Var(D), Cov(N, D), and the means. The approximation is excellent when the sample size is moderate to large, which it is for almost any A/B test. + +When to use. + +- Conversion rate (conversions per user, when users can have multiple events). +- Click-through rate (clicks per impression). +- Revenue per user. +- Average order value. +- Any metric expressible as numerator divided by denominator where users can contribute multiple values. + +When the simple formula is fine. + +- Per-user binary conversion (one row per user, converted yes or no). The standard proportion variance formula is correct here. + +Bootstrap as an alternative. Resample users with replacement many times, compute the ratio each time, read off the empirical CI. Distribution-free; slower than delta method. Both produce similar CIs for typical A/B test sizes. + +How to verify your platform. Ask "what variance estimator do you use for ratio metrics?" Acceptable answers: delta method, linearization, bootstrap with user-level resampling. Unacceptable: standard t-test on proportions (wrong for non-binary ratios), bootstrap with row-level resampling (ignores within-user correlation). + +--- + +## Sequential testing methods + +The peeking problem. Standard p-values assume one analysis at the end of the test. Multiple analyses inflate the false positive rate. Daily peeking on a four-week test can push false positive rate above 30%. + +Group sequential designs (GSD). Plan a fixed set of interim analyses (often three) with adjusted significance thresholds at each. The thresholds are computed so the overall false positive rate stays at the nominal alpha. Well-understood; less flexible than always-valid methods. + +Mixture sequential probability ratio test (mSPRT). Produces "always-valid" p-values: the false positive rate stays at nominal alpha regardless of how many times you analyze. Common in modern platforms. The math: define a likelihood ratio between the alternative and null hypotheses, integrated over a prior on the effect size. The test rejects when the ratio exceeds 1/alpha. + +Anytime-valid confidence intervals. The CI version of always-valid p-values. Produced by taking the inverse of the always-valid test family. Wider than fixed-horizon CIs; the cost of peek-safety is some statistical efficiency, typically 10% to 30% wider. + +Implementation across platforms. + +- Statsig: always-valid by default for sequential metrics. +- Eppo: sequential CIs available as a configuration. +- GrowthBook: mSPRT supported. +- PostHog: depends on the experiment type and configuration. +- Optimizely: supports sequential via Stats Engine. +- Amplitude (Experiment): supports sequential testing. + +How to read the panel. "Always-valid p-value" or "anytime-valid CI" labels indicate sequential. "P-value" with no qualifier is fixed-horizon; treat early peeks as suggestive only. + +--- + +## Heterogeneous treatment effects (HTE) + +What HTE is. The treatment works differently for different segments. New users see +5%, power users see -2%, average is +1%. + +Pre-registered vs post-hoc. Pre-registered HTE analysis is one of the segment definitions you committed to at design time, with sample size budgeted for the segment. Post-hoc HTE discovery is finding a segment whose effect is large by mining the data; this is noise mining and the apparent lift will not replicate. + +When to ship segment-only. Three conditions must all hold: + +- The segment was pre-registered. +- The effect within the segment is large enough to justify shipping. +- The targeting infrastructure exists (or is cheap to build) and the maintenance cost is acceptable. + +If any condition fails, do not ship segment-only. Either ship to everyone (taking the average effect) or do not ship. + +Methods for principled HTE detection. + +- Causal forests: machine learning method for estimating heterogeneous treatment effects across many features. +- Conditional average treatment effects (CATE) with regression: model the effect as a function of covariates. +- Pre-registered segment analysis: simpler, more defensible, and sufficient for most PM contexts. + +For most A/B tests, pre-registered segment analysis is the right level of sophistication. Causal forests are useful for marketplace and personalization research where the effect is genuinely expected to vary across many dimensions. + +--- + +## Multiple testing corrections + +The problem. With twenty independent comparisons at alpha equals 0.05, you expect one false positive purely by chance. With fifty, two or three. + +Bonferroni correction. Divide alpha by the number of comparisons. With 20 comparisons, use alpha equals 0.0025 per comparison. Conservative; controls the family-wise error rate (probability of any false positive across the family). + +Benjamini-Hochberg (BH) correction. Less conservative; controls the false discovery rate (expected proportion of false positives among the things called significant). Better for exploratory analysis where some false positives are tolerable. + +When to use which. + +- Small number of pre-registered comparisons with high stakes: Bonferroni. +- Larger exploratory analysis where some false positives are acceptable: BH. +- Single pre-registered primary metric: no correction needed (one comparison). + +How platforms apply corrections. Some platforms apply corrections silently to displayed p-values; others report uncorrected numbers. Know which your platform does. The "5 of 12 metrics significant" headline means very different things depending on whether the p-values were corrected. + +--- + +## Cluster randomization + +When SUTVA is violated. SUTVA (Stable Unit Treatment Value Assumption) says one user's treatment does not affect another user's outcome. Violated in two-sided marketplaces, social products, supply-constrained features, and notification systems. + +Cluster randomization as a fix. Assign whole units (cities, markets, friend groups, sessions) to treatment or control rather than individual users. Eliminates within-cluster interference at the cost of effective sample size. + +Trade-off. A cluster of 1000 users behaves more like one observation than 1000 independent observations. Effective sample size is roughly the number of clusters times the within-cluster correlation factor. Cluster randomization with 50 clusters has roughly the power of a user-randomized test with 200 to 500 users, even if the clusters contain millions of users total. + +Designing for cluster randomization. Choose the cluster boundary so that interference happens within clusters but not across them. Cities work for marketplace experiments. Friend groups work for social products. Sessions work for some notification studies. + +Switchback experiments as an alternative. Toggle the entire population between treatment and control across time windows (week 1 treatment, week 2 control). Eliminates cross-user interference within each window. Requires careful temporal modeling because the windows are not independent (carryover effects, day-of-week effects). + +Detection of SUTVA violation without redesign. Compare a small cluster-randomized version to the user-randomized version. If the cluster-randomized lift is much larger than the user-randomized lift, the user-randomized test is leaking treatment into control via interference. The user-randomized test is undercounting the effect. + +--- + +## Variance reduction beyond CUPED + +Stratified sampling. Pre-stratify users by a known covariate (geography, segment, signup cohort) and randomize within strata. Reduces variance from imbalanced randomization at the cost of slightly more complex analysis. + +Post-stratification. Run normal randomization, then adjust the analysis for known covariates after the fact. Similar variance reduction to CUPED for the right covariates. + +Regression adjustment. Include covariates as controls in the regression that estimates the treatment effect. Equivalent to post-stratification for one covariate; generalizes to multiple. + +Doubly robust estimation. Combines regression adjustment with inverse-probability weighting. Robust to misspecification of either the outcome model or the propensity model. Overkill for most A/B tests; useful for observational analysis and some quasi-experiments. + +For most PM contexts, CUPED plus pre-registered segment analysis covers the variance reduction needs. The methods above are the next step up when the standard tools are insufficient. diff --git a/skills/experimentation-platform-orchestrator/SKILL.md b/skills/experimentation-platform-orchestrator/SKILL.md new file mode 100644 index 0000000..ea765c9 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/SKILL.md @@ -0,0 +1,286 @@ +--- +name: experimentation-platform-orchestrator +description: "A platform decision framework for experimentation. When to use Statsig vs PostHog vs GrowthBook vs Optimizely vs Amplitude vs Eppo vs Kameleoon. How to migrate between them. How to coordinate when multi-platform is genuinely warranted. The decisions that compound for years and the ones you can defer. Triggers on which experimentation platform, choose Statsig vs PostHog, evaluate experimentation tools, switch experimentation platform, migrate from Optimizely, consolidate experimentation tools, multi-platform experimentation, experimentation platform decision, ab test platform selection, feature flag platform vs experiment platform, warehouse-native experiments, vendor lock-in experimentation. Also triggers when a team is asking about cost, governance, or migration cost across experimentation tools, or when an evaluation is starting." +category: product +catalog_summary: "Pick the right experimentation platform, migrate when wrong, coordinate when multi-platform: a decision framework for Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon" +display_order: 7 +--- + +# Experimentation Platform Orchestrator + +A senior product and engineering leader's playbook for making the experimentation platform decision and recovering from making it wrong. + +Picking an experimentation platform is one of those decisions that looks easy at the start and compounds for years afterward. The wrong choice costs you in lost experiments (because the team avoids the painful workflow), in cost (because the wrong pricing model penalizes your usage shape), in vendor lock-in (because migration is real engineering work, not a config change), and in cultural drift (because the platform's defaults shape what your team thinks experimentation is). + +This skill is the discipline that makes the decision well the first time and the migration plan when you didn't. + +When to use this skill: choosing a platform from scratch, evaluating whether to switch, deciding whether to consolidate from multi-platform to single, or planning a migration that has already been approved. + +--- + +## What this skill is for + +This skill spans platform selection, multi-platform decisions, migration planning, and governance setup. It does not cover experiment design (use `experiment-design`), result interpretation (use `experimentation-analytics`), or feature flag operations (use `feature-flagging`). Pair this skill with the relevant integrations microsite when you need platform-specific MCP details. + +The audience is a PM, engineering leader, or data lead who is making the decision or recovering from a previous one. The voice is decisive. There is no "it depends, evaluate them all yourself." The decision space has real shape, and a senior advisor can map your situation to a defensible answer in an afternoon. + +--- + +## The 7 considerations for the platform decision + +Every platform evaluation walks the same seven questions. Answer them honestly first, then read the per-platform profiles, then consult the decision matrix. The order matters: data architecture and statistical rigor are foundational; the rest are layered on top. + +1. Data architecture. Where does experiment data live? Three patterns. Vendor-native (Statsig, Optimizely) keeps the data in the vendor's storage. Product-suite (PostHog, Amplitude) combines analytics and experiments behind one event pipeline. Warehouse-native (GrowthBook, Eppo) runs SQL on your existing data warehouse. The pattern dictates security review depth, residency, statistical depth, and cost shape. + +2. Statistical rigor. Does the platform implement CUPED, sequential testing, the delta method for ratio metrics, and multiple testing corrections? Cheap to verify in a sales call: ask "what variance estimator do you use for ratio metrics?" and "do you support always-valid p-values?" Modern platforms (Statsig, Eppo, parts of PostHog) have these. Older or homegrown platforms often do not. + +3. MCP availability. All seven platforms covered here have a first-party or hosted MCP except Eppo (as of May 2026). MCP availability matters more for agentic workflows where AI agents create and read experiments end to end. It matters less for traditional human-driven experimentation. Worth weighting if your team is AI-forward. + +4. Feature flag integration. Do experiments and feature flags live in the same platform? Statsig, Optimizely, GrowthBook, and PostHog all unify them. Eppo is experiment-only. Kameleoon is creative-personalization-focused. If you also need feature flag operations as production infrastructure, check `feature-flagging` for the operational discipline; the platform choice has to support both surfaces or you accept a second tool. + +5. Analytics depth. Can you see funnels, retention, and cohorts in the same surface as experiment results? PostHog and Amplitude are strongest here (analytics-first products). Statsig has a strong analytics overlay. Optimizely and GrowthBook are experiment-first, with analytics as a supplementary feature. + +6. Governance and audit. Who can change targeting in production, who can ship experiments, who can read sensitive metrics? Enterprise tiers (Optimizely, LaunchDarkly Federal) handle this with maturity. Open-source platforms (GrowthBook, PostHog self-hosted) require self-built governance. For regulated industries (healthcare, finance, public sector), this question is the deciding factor. + +7. Cost shape. Vendor-native scales with events. Warehouse-native scales with seats and warehouse compute. Product-suite scales with combined event volume across all features. Match the pricing shape to your actual usage shape. A high-traffic startup pays vendor-native pricing differently from a lower-traffic enterprise; pick the shape that is friendly to your trajectory, not just your current month. + +--- + +## Statsig + +Modern experimentation and feature management combined in one platform. CUPED and sequential testing built in. Strong PM-led ergonomics. Used by OpenAI, Notion, Brex, Figma. + +Strengths. Fast time to first experiment. Combined experiments and feature flags eliminate the second-tool tax. Statistical rigor is current with the literature. The MCP exposes full CRUD across experiments, gates, dynamic configs, and metrics. + +Gotchas. Pricing scales with events, which can become expensive at high scale. The platform has strong opinions about how experiments should run; teams that want a custom statistical workflow will fight the defaults. Self-host is not a first-class option. + +Ideal customer. Fast-growing SaaS that wants one platform for flags and experiments, values out-of-the-box statistical depth, and is comfortable with vendor-native data architecture. + +--- + +## PostHog + +Open-source product OS combining product analytics, experiments, feature flags, surveys, session replays, error tracking, and LLM analytics. Free tier available. + +Strengths. Full-funnel context. Experiments live next to the analytics that contextualize them. The MCP exposes 200+ tools (use scoping like `?features=` to keep the agent context tight). Self-host option is mature. Open-source license keeps you outside the vendor lock-in trap. + +Gotchas. Combined event volume across all features can make pricing surprising at scale. The breadth of features can make onboarding feel busy. Statistical depth in experiments is good but a step behind dedicated experiment platforms (Statsig, Eppo) on advanced features like CUPED defaults. + +Ideal customer. Product-led-growth SaaS that wants analytics, experiments, and feature flags in one surface, values open-source flexibility, and is comfortable with the breadth. + +--- + +## GrowthBook + +Open-source warehouse-native experimentation. Data stays in your warehouse (Snowflake, BigQuery, Redshift, Postgres). Self-host or cloud. + +Strengths. Data sovereignty. Cost control at scale because the warehouse is already paid for. First open-source production MCP for experimentation per their announcement. Mature statistical defaults including Bayesian and frequentist toggles. Bring-your-own metrics from the warehouse means experiment metrics match analytics metrics by definition. + +Gotchas. Setup overhead is higher than vendor-native. You own the warehouse compute cost (this is usually a feature, not a bug, but it shows up in different finance line items). Smaller community than Statsig or PostHog. UI polish lags vendor platforms by half a step. + +Ideal customer. Data-mature teams that already run a warehouse, regulated industries that need data residency, and teams that prefer open-source for the exit option. + +--- + +## Optimizely + +Long-time enterprise leader. Web Experimentation plus Feature Experimentation. Strong personalization and visual editing for non-technical users. + +Strengths. Enterprise governance is mature. Visual editing lets marketers ship experiments without engineer help. Strong customer success organization. Hosted Remote MCP works in browser-based ChatGPT and Claude.ai. + +Gotchas. Expensive. Pricing targets marketing budgets, not engineering budgets. The product has decades of accumulated features; navigating it takes time. Statistical defaults are conservative but the platform is not the place to look for the latest variance reduction techniques. + +Ideal customer. Marketing-led organizations, enterprises with mature experimentation programs, and teams where non-technical experiment creation is a hard requirement. + +--- + +## Amplitude + +Behavioral analytics platform with experiments and feature flags as additional features. Hosted MCP available to all customers including the free tier. + +Strengths. If your team already lives in Amplitude for analytics, adding experiments is the path of least resistance. Cohort and behavioral segmentation are excellent. Free tier (10M events/month) is generous. + +Gotchas. Experiments are a secondary feature, not the headline. Statistical depth is moderate. If experimentation is your team's primary discipline, Amplitude is rarely the right choice; if experimentation is a supporting capability and analytics is the headline, it works. + +Ideal customer. Analytics-first teams that need experiments as a supplementary capability, not the centerpiece. Pre-PMF teams that want a free tier with analytics and experiments together. + +--- + +## Eppo + +Warehouse-native, statistically rigorous, used by Twitch, DraftKings, Perplexity. Strong statistical defaults including Bayesian and frequentist toggles, sequential testing, and CUPED. + +Strengths. Statistical correctness is the headline. The team is heavy on data scientists and statisticians, and it shows in the defaults. Warehouse-native architecture matches the pattern data-mature teams already run. Reporting is clear and oriented to decisions. + +Gotchas. No first-party MCP as of May 2026. REST API only. If your workflow depends on AI agents reading and writing experiments, Eppo is currently a gap. Track for a future MCP release. Pricing is enterprise; no meaningful free tier. + +Ideal customer. Data-team-led organizations where statistical correctness is paramount, the warehouse is already the system of record, and AI agent workflows are a future concern rather than a current requirement. + +--- + +## Kameleoon + +Specialty platform focused on the winning-experiment-to-production-code workflow. AI-driven personalization. Hosted MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. + +Strengths. Converts marketing-site experiment wins into permanent React components, which is a real workflow that other platforms force teams to handle manually. AI-driven personalization for content sites. The MCP is purpose-built for the win-to-code path. + +Gotchas. Narrower than the others. Not a replacement for Statsig or Optimizely on product experiments. Often shows up alongside another platform rather than as the primary. + +Ideal customer. Teams running experiments on marketing or content sites that need the winning variant to become permanent code. Almost always layered with a primary product-experiment platform. + +--- + +## Decision matrix: which platform for which context + +The matrix lives in [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) with worked examples. The summary: + +- Pure SaaS, fast-growing, want one platform for flags and experiments. Choose Statsig. Choose PostHog if you also want analytics. +- Open-source preference, want data sovereignty, warehouse-native. Choose GrowthBook or Eppo. +- Enterprise, marketing-led, deep personalization. Choose Optimizely. +- Already deeply on Amplitude for analytics. Stay on Amplitude unless statistical depth becomes the bottleneck. +- Data-team-led, statistical correctness paramount, MCP not yet required. Choose Eppo. +- Need to convert marketing-site wins into production code. Add Kameleoon alongside your primary platform. +- Regulated industry (HIPAA, FedRAMP), self-hosting required. Choose GrowthBook self-hosted. PostHog self-hosted is also viable. +- Pre-PMF startup, low traffic, need a free tier. Use PostHog free tier or Statsig free tier; defer the real decision until traffic justifies the cost calculation. +- 100M+ events per month, cost control is the headline constraint. Choose GrowthBook or Eppo. Warehouse-native pricing scales better at this volume. +- AI-forward team, MCP-first workflow. Choose Statsig, PostHog, or Optimizely. Defer Eppo until its MCP ships. + +--- + +## Multi-platform: when warranted, when a mess + +Multi-platform is warranted when the surfaces are genuinely different and the platforms overlap zero. Marketing site personalization on Kameleoon plus product experiments on Statsig is a clean split: different surface, different audience, different metric set, no overlap. The cost of the second tool is justified because the workflows do not collide. + +Multi-platform is a mess when the surfaces overlap. Running both Statsig and Optimizely for product experiments creates duplicate cost, split data, and a "which one is the source of truth" problem that surfaces in the worst possible moment, which is when a leadership disagreement needs an answer. + +The 80/20 rule. Eighty percent of teams should pick one platform and consolidate. The 20% with genuine multi-surface needs (marketing site plus product app plus content site) can justify multi-platform with clear ownership boundaries. + +When multi-platform is genuine, three coordination patterns are non-negotiable. An ownership matrix names which platform owns which surface. Shared metric definitions ensure that "activation rate" computes the same way in both platforms (this is hard, and it is the reason most multi-platform setups quietly drift). Reconcilable dashboards let you see the same metric across both platforms with the same definitions. Detail in [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md). + +--- + +## Migration patterns + +Migration is the unglamorous engineering work that makes the platform decision recoverable. Five common paths. + +Statsig to PostHog. Typical when a company outgrows pure experimentation and wants analytics plus experiments combined. Effort: 3 to 5 engineer-weeks. Parallel-run for 4 to 8 weeks, validate experiments produce the same results on both, cut over once trust is established. + +Optimizely to Statsig. Typical under budget pressure or modernization. Effort: 4 to 8 engineer-weeks. Audit for feature parity first (Optimizely has personalization features Statsig does not). Migrate experiments before flags. Retire Optimizely only after all in-flight experiments complete on the old platform. + +PostHog to Eppo. Typical when statistical rigor becomes the binding constraint and the warehouse is already the system of record. Effort: 6 to 10 engineer-weeks. Often results in PostHog staying for analytics and Eppo running experiments. Plan for the dual-platform end state, not a clean replacement. + +GrowthBook to Eppo. Typical when commercial support and deeper statistical features become worth the price. Effort: 2 to 4 engineer-weeks because both are warehouse-native; the data already lives in your stack. + +Any to Statsig. Typical consolidation move from multi-platform mess. Effort scales with the number of platforms and in-flight experiments; a clean consolidation can run 6 to 12 engineer-weeks. + +The migration discipline is in [`references/migration-playbook.md`](references/migration-playbook.md). Three rules apply to every migration: do not parallel-run forever, do not big-bang switch, and do not retire the old platform before all in-flight experiments complete. + +--- + +## The cost reality + +Plain talk. Vendor-native (Statsig, Optimizely) bills on events, typically $0.10 to $0.50 per million events. Easy to predict at small scale, painful at very high scale. Warehouse-native (Eppo, GrowthBook paid) bills on seats and warehouse compute; $5K to $50K per year is the typical range for paid tiers, with warehouse compute showing up on a different finance line. Product-suite (PostHog, Amplitude) bills on combined event volume across all features; often the most cost-effective when used heavily and the most expensive when only experiments are needed. + +Free tiers. PostHog gives 1M events per month free. Statsig gives 1M events free. Amplitude gives 10M events per month free with basic features. GrowthBook is free open-source. Optimizely and Eppo do not have meaningful free tiers. + +The trap. Optimizing for sticker price ignores total cost. Total cost includes engineer time, statistical correctness (a wrong-result experiment can cost more than a year of platform fees), governance overhead, and migration risk. Sticker price matters for finance; total cost matters for product velocity. Detail and finance conversation patterns in [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md). + +--- + +## Governance and team fit + +Permission tiers, approval workflows, audit trails, and environment promotion are the four pillars of governance. Who creates experiments, who modifies targeting in production, who reads sensitive metrics, who approves a rollout. Enterprise tiers handle these out of the box. Open-source self-hosted requires you to build them, which is fine if you have the engineering capacity and a dealbreaker if you do not. + +Team fit shapes the decision more than most evaluations admit. PostHog and GrowthBook suit engineer-led and PLG teams. Optimizely suits marketing-led teams. Eppo and GrowthBook suit data-team-led teams. Statsig suits PM-led teams. The platform's defaults will pull your team's experimentation culture in the direction of its primary user; pick the alignment that matches who you actually want running experiments. + +Onboarding cost. How long until a new PM can ship their first experiment? Statsig and PostHog: hours to days. Optimizely: days to weeks. Eppo and GrowthBook: depends on whether the warehouse and metrics are already wired in (days if yes, weeks if no). Detail in [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md). + +--- + +## The MCP capability layer + +For AI-forward teams, the MCP capability layer is becoming the deciding factor. The current state as of May 2026: + +- All seven covered platforms have first-party or hosted MCPs, with the exception of Eppo. Eppo offers REST API only. +- Capability differs by an order of magnitude. PostHog exposes 200+ tools; Kameleoon exposes 7. More is not better; the right size depends on your workflow. +- For agentic workflows where AI agents run experiments end to end, prefer platforms with full CRUD via MCP: Statsig, PostHog, GrowthBook, Optimizely. +- For human-driven workflows where MCP supplements human action, any of the seven works (Eppo via the REST path). + +MCP availability is evolving fast. Check the current state of any platform before committing. Eppo is worth tracking for a future MCP release that would close its current gap. Side-by-side capability matrix in [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md). + +--- + +## When to defer the decision + +Sometimes the right answer is "not now." Four cases. + +Pre-PMF. Experimentation infrastructure is premature. Use a free tier (PostHog or Statsig) to remove blockers, defer the real decision until you have enough traffic to make any platform meaningful. + +Single-experiment validation. Do not pick a platform for one experiment. Use whatever is free and easy. The platform decision is for the team that runs experiments as a discipline, not the team running its first. + +No experimentation culture yet. Tooling does not fix culture. If your team is not running experiments, picking a fancy platform will not change that. Build the culture first; the platform decision becomes obvious once experiments are flowing. + +Pending acquisition or major pivot. Defer until the dust settles. The acquirer will likely have a preferred platform anyway. + +--- + +## Common mistakes + +Twelve patterns recur across platform decisions. The short version: + +- Picked the cheapest. Total cost dominates sticker price. +- Picked the most-featured. Features you do not use are technical debt. +- Tried multi-platform first. Almost always becomes a consolidation project later. +- Outgrew the platform but stayed for migration cost. The platform tax compounds; migration cost is fixed. +- Picked based on a demo. Demos optimize for the show; real usage reveals real tradeoffs. +- Did not check governance. Discovered after rollout that anyone can modify production targeting. +- Picked a platform that does not fit team type. PM-led team on a marketing-led platform is constant friction. +- Underestimated the warehouse setup. Warehouse-native platforms expect the warehouse to already be there. +- Skipped statistical depth review. Then a critical experiment surfaced a wrong-result decision. +- Ignored MCP trajectory. Picked a platform without MCP for an AI-forward team. +- Locked the brief on the demo, not the trial. Brief assumptions did not survive contact with real usage. +- Renewed without re-evaluating. The market changed; the brief did not. + +Detail in [`references/common-mistakes.md`](references/common-mistakes.md) with symptoms, root causes, fixes, and prevention. + +--- + +## The framework: 11 considerations for sustainable platform choice + +When choosing or evaluating an experimentation platform, walk these 11 considerations. Answer each one before reaching a recommendation. Skipping any of them is how teams end up in a migration project a year later. + +1. Data architecture. Vendor-native, product-suite, or warehouse-native. The pattern is downstream of every other decision. +2. Statistical rigor. CUPED, sequential testing, delta method for ratio metrics, multiple testing corrections. Verify at the sales-call level; do not assume. +3. MCP availability. Current capability and trajectory. Weight higher if your team is AI-forward. +4. Feature flag integration. Same platform or separate. Decide once and live with the implications. +5. Analytics depth. Funnels, retention, cohorts in the same surface. Decides whether you need a second tool for the analytics layer. +6. Governance. Permissions, audit, approval workflows, environment promotion. Non-negotiable for regulated industries. +7. Cost shape. Events vs seats vs warehouse compute. Match the shape to your usage trajectory. +8. Team fit. PM-led, engineer-led, data-led, marketing-led. The platform's defaults will pull your culture in the direction of its primary user. +9. Onboarding cost. Time to first experiment for a new team member. Faster is better; varies wildly across platforms. +10. Migration cost. What is the exit plan if you choose wrong. Higher migration cost means higher confidence required at decision time. +11. Multi-platform fit. Does this layer cleanly with platforms you already have, or does it create overlap. + +The output of this framework is one of three answers. A primary recommendation with reasoning. A short list of two if the situation is genuinely ambiguous. A "defer" if a precondition is not met (no traffic, no culture, pending pivot). + +--- + +## Reference files + +- [`references/platform-decision-matrix.md`](references/platform-decision-matrix.md) - Context-to-platform matrix with worked examples for the most common decision contexts. +- [`references/migration-playbook.md`](references/migration-playbook.md) - Step-by-step migration patterns for the five common migrations including effort estimates and validation approaches. +- [`references/mcp-capability-comparison.md`](references/mcp-capability-comparison.md) - Side-by-side MCP capability matrix across the seven platforms. +- [`references/multi-platform-orchestration.md`](references/multi-platform-orchestration.md) - Ownership boundaries, shared metric definitions, and reconciliation dashboards for genuine multi-platform setups. +- [`references/cost-and-pricing-models.md`](references/cost-and-pricing-models.md) - Pricing shapes, real-world cost ranges at different traffic tiers, and finance conversation patterns. +- [`references/governance-and-team-setup.md`](references/governance-and-team-setup.md) - Permission tiers, audit trail requirements, environment promotion rules, and team fit assessment. +- [`references/common-mistakes.md`](references/common-mistakes.md) - Twelve failure patterns with symptom, root cause, fix, and prevention for each. + +--- + +## Closing: when in doubt, pick boring + +When the analysis is genuinely ambiguous, pick the boring choice. Boring means mature, well-documented, large user base, and a recoverable migration if you turn out to be wrong. Statsig is boring for SaaS. PostHog is boring for product-led growth. Optimizely is boring for enterprise. GrowthBook is boring for warehouse-native. + +Boring is not the optimum, but it is almost never wrong. The optimum can come later, when the situation has clarified and the team has the experience to know what it actually needs. The cost of picking boring is a small efficiency tax. The cost of picking exotic and being wrong is a migration project that interrupts a year of product work. + +If the team disagrees on which boring choice is the right one, that is a data signal: the situation is not yet clear enough for any answer to be obviously correct. Run a 30-day trial on the top two, evaluate against the 11-consideration framework with real usage data, and pick. Do not skip the trial; demos lie about real usage in ways that only the trial reveals. diff --git a/skills/experimentation-platform-orchestrator/references/common-mistakes.md b/skills/experimentation-platform-orchestrator/references/common-mistakes.md new file mode 100644 index 0000000..bbf1200 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/common-mistakes.md @@ -0,0 +1,155 @@ +# Common mistakes + +Twelve failure patterns that recur in platform decisions. For each: name, symptom, root cause, fix, and prevention. + +--- + +## 1. Picked the cheapest + +Symptom. Six months in, the team is paying more in engineer time than they saved on the platform fee. Velocity is below the pre-decision projection. + +Root cause. Sticker-price optimization without a total-cost frame. Engineer time, statistical correctness, and migration risk were not priced in. + +Fix. Run a total-cost-of-ownership review. If TCO is materially worse, plan a migration to a better-fit platform. Counter-intuitively, paying more in platform fees can save more in engineer time. + +Prevention. Use the total cost frame at decision time. The cheapest sticker price is rarely the cheapest TCO. See `cost-and-pricing-models.md` for the framing. + +--- + +## 2. Picked the most-featured + +Symptom. The team uses 20% of the platform's features. The other 80% are noise that complicates onboarding and inflates the bill. + +Root cause. Demo-driven feature comparison. The platform's depth was impressive in the demo and translated into a "more features means more value" assumption. + +Fix. Audit feature usage. If 80% of the platform is unused, evaluate whether a simpler platform serves the team better. Migrating to a smaller-surface platform reduces operational complexity. + +Prevention. Build a "features needed" list before evaluating platforms. Use the list to filter out features you do not need; do not let demo-time enthusiasm expand it. + +--- + +## 3. Tried multi-platform first + +Symptom. Two platforms running, both partially used, neither fully embraced. Stakeholders cannot tell which one is the source of truth. + +Root cause. "Best of both worlds" thinking. The team picked two platforms hoping to combine their strengths, but the integration cost exceeded the combined benefit. + +Fix. Plan a consolidation. See `multi-platform-orchestration.md` for when consolidation is the right answer (almost always for teams in this state). + +Prevention. Default to single-platform unless the surfaces genuinely do not overlap. Multi-platform is a 20% case, not the default. + +--- + +## 4. Outgrew the platform but stayed for migration cost + +Symptom. The team is hitting limits the platform cannot serve (statistical depth, governance, scale). They know it. They have not migrated because the migration project feels expensive. + +Root cause. Migration cost is overweighted relative to the ongoing platform tax. The platform tax compounds; migration cost is fixed. + +Fix. Run the migration. Set a 90-day window. Use the migration playbook. + +Prevention. Do an annual platform fit review. If the platform is not the right fit, the answer is to migrate, not to defer. Deferral makes the migration harder, not easier. + +--- + +## 5. Picked based on a demo + +Symptom. Real usage reveals workflows that did not show up in the demo. Team velocity is below expectations. Frustration is mounting. + +Root cause. Demos optimize for the show. Real usage reveals real tradeoffs. The decision was made before the team had data on actual workflows. + +Fix. Run a 30-day trial on the next-best alternative. Compare real-usage friction. If the alternative is materially better, plan the migration. + +Prevention. Always run a real trial, never just a demo. The trial should ship at least one experiment end to end on each platform under evaluation. + +--- + +## 6. Did not check governance + +Symptom. Discovered after rollout that anyone with platform access can modify production targeting. A bad change shipped because no review was required. + +Root cause. Governance was not part of the evaluation. The team assumed defaults would be acceptable; they were not. + +Fix. Build the governance layer immediately. Permission tiers, approval workflows, audit trails, environment promotion. See `governance-and-team-setup.md`. + +Prevention. Make governance a non-negotiable evaluation criterion. For any platform under consideration, document the permission model, audit capabilities, and approval workflow before signing. + +--- + +## 7. Picked a platform that does not fit team type + +Symptom. Constant friction in experiment authoring. The team that should be shipping experiments is instead filing tickets. Experiment volume is below target. + +Root cause. Team-fit mismatch. A PM-led team on a marketing-led platform, or vice versa. The platform's defaults pull the workflow in a direction the team cannot follow. + +Fix. Either change the team's workflow to match the platform, or migrate to a platform that matches the team. The migration is usually the right answer because team workflow is hard to change quickly. + +Prevention. Assess team fit explicitly. See the team-fit framework in `governance-and-team-setup.md`. + +--- + +## 8. Underestimated the warehouse setup + +Symptom. Picked a warehouse-native platform. Three months in, still not running experiments because the warehouse layer is not ready. + +Root cause. Warehouse-native platforms expect the warehouse to already be the system of record with metrics defined and refresh cadences in place. The team did not have that foundation. + +Fix. Either complete the warehouse setup (real engineering project) or migrate to a vendor-native platform that does not require it. + +Prevention. Verify warehouse readiness before committing to warehouse-native. The platform decision should follow the warehouse decision, not lead it. + +--- + +## 9. Skipped statistical depth review + +Symptom. A critical experiment surfaced a wrong-result decision. The platform's defaults did not catch the issue (peeking, ratio metric, multiple testing, network effects). + +Root cause. Statistical depth was not part of the evaluation. The team assumed all platforms compute the same numbers correctly; they do not. + +Fix. Add the missing rigor. Either configure the current platform's advanced features (sequential testing, CUPED, delta method) or migrate to a platform with stronger defaults. Pair with the `experimentation-analytics` skill to interpret results going forward. + +Prevention. Verify statistical depth at evaluation time. Ask specifically about CUPED, sequential testing, delta method for ratio metrics, and multiple testing corrections. Do not accept "we have statistical features" without specifics. + +--- + +## 10. Ignored MCP trajectory + +Symptom. AI-forward team picked a platform without MCP. Six months later, the team is hitting the limit of agent-driven workflows and the platform is the bottleneck. + +Root cause. MCP trajectory was not weighted in the decision. The platform's strengths in other areas were assumed to make up for the gap. + +Fix. Either wait for the platform to ship an MCP (uncertain timeline) or migrate to a platform with mature MCP. Eppo specifically is worth tracking for a future MCP release. + +Prevention. For AI-forward teams, MCP availability is a primary criterion, not a tiebreaker. See `mcp-capability-comparison.md` for current state. + +--- + +## 11. Locked the brief on the demo, not the trial + +Symptom. Brief-time assumptions did not survive contact with real usage. The platform is technically capable but operationally uncomfortable in ways the demo did not reveal. + +Root cause. The decision was made on the strength of the demo, with the trial running as a formality afterward. Real-usage signals were not weighted. + +Fix. Do another trial of the next-best alternative. If the alternative removes the operational discomfort, migrate. + +Prevention. Run the trial first. Use trial outcomes to update the brief, not the other way around. Demos are useful for screening; trials are required for committing. + +--- + +## 12. Renewed without re-evaluating + +Symptom. Renewal cycle came up. The team renewed because the platform was working "well enough." Six months later, an alternative shipped a feature that would have changed the decision. + +Root cause. Renewal treated as a status-quo extension. The platform market changes faster than annual contracts, and a yearly renewal without re-evaluation drifts away from the optimal choice. + +Fix. Run the platform decision framework at every renewal. If the answer is the same platform, renew with confidence. If the answer is different, plan a migration. + +Prevention. Build the annual platform review into the team's calendar. Tie it to the renewal date so the review informs the renewal decision rather than competing with it. + +--- + +## The pattern across all twelve + +Most platform mistakes share one root cause: under-investment in the decision itself. A two-week evaluation that catches all twelve patterns is cheaper than a year on the wrong platform. + +The fix at the meta level. Treat the platform decision as a real engineering project. Allocate time. Run trials. Audit governance. Verify statistical depth. Check MCP trajectory. Document the decision and the reasoning. Review annually. diff --git a/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md b/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md new file mode 100644 index 0000000..146f835 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/cost-and-pricing-models.md @@ -0,0 +1,125 @@ +# Cost and pricing models + +Pricing shapes per platform, real-world cost ranges at different traffic tiers, the total cost frame, and finance conversation patterns. + +Pricing on experimentation platforms is rarely transparent on the public site for paid tiers. The numbers below are typical ranges from real customer conversations as of May 2026. Verify with each vendor before committing. + +--- + +## The three pricing shapes + +Vendor-native (event-based). Statsig, Optimizely. Billing scales with the number of events sent to the platform. Easy to predict at small scale: events per month times rate per million. Painful at very high scale because the rate per million does not always decrease quickly. + +Warehouse-native (seat plus warehouse compute). GrowthBook (paid), Eppo. Billing scales with the number of seats and the warehouse compute the platform consumes. Warehouse compute is your existing line item, so the marginal cost of more experiments is small once the platform is paid for. Less elastic on team size, more elastic on experiment volume. + +Product-suite (combined event volume). PostHog, Amplitude. Billing scales with combined event volume across all features (analytics, experiments, replays, error tracking, surveys). Often the most cost-effective when used heavily; can be the most expensive when only one feature is needed. + +--- + +## Free tiers + +Free tiers exist for the early-stage and pre-PMF cases. The numbers below are current as of May 2026. + +\| Platform \| Free tier shape \| +\|---\|---\| +\| PostHog \| 1M events per month free across all features \| +\| Statsig \| 1M events per month free; full feature access \| +\| Amplitude \| 10M events per month free with basic features (some advanced features paid) \| +\| GrowthBook \| Free open-source self-hosted; cloud has a free tier with 3 users and 5 active experiments \| +\| Optimizely \| No meaningful free tier \| +\| Eppo \| No meaningful free tier \| +\| Kameleoon \| No meaningful free tier; free trial only \| + +For pre-PMF and early-stage teams, the free-tier choice is between PostHog and Statsig. Both work. Pick the one whose product surface matches your needs (PostHog if you also want analytics; Statsig if you want experiments and flags primarily). The decision is reversible at low cost while you are still on the free tier. + +--- + +## Real-world cost ranges + +Approximate ranges for paid tiers. Bands are wide because pricing varies by contract size, sales discount, and feature mix. + +### Vendor-native (events per month) + +\| Volume \| Statsig (typical) \| Optimizely (typical) \| +\|---\|---\|---\| +\| 1M to 10M \| $0 (free) to $1K/month \| Custom contract; rarely under $30K/year \| +\| 10M to 100M \| $1K to $8K/month \| $30K to $100K/year \| +\| 100M to 1B \| $8K to $40K/month \| $100K to $400K/year \| +\| 1B+ \| $40K+/month with custom negotiation \| $400K+/year with custom negotiation \| + +Optimizely consistently sits at a higher absolute price point than Statsig for the same volume. The premium pays for the marketing-led ergonomics, the visual editor, and the personalization features. Whether the premium is justified is a per-team judgment. + +### Warehouse-native (seats and compute) + +\| Team size \| Eppo (typical) \| GrowthBook paid (typical) \| +\|---\|---\|---\| +\| 5 to 10 seats \| $20K to $40K/year \| $5K to $15K/year \| +\| 10 to 30 seats \| $40K to $120K/year \| $15K to $50K/year \| +\| 30+ seats \| Custom contract \| Custom contract \| + +Plus warehouse compute. For a Snowflake-based setup running 100 to 300 active experiments per year, expect $2K to $20K/year of additional warehouse compute attributable to experimentation queries. The exact number depends on metric complexity and refresh cadence. + +### Product-suite (combined events) + +\| Volume \| PostHog (typical) \| Amplitude (typical) \| +\|---\|---\|---\| +\| 1M to 10M \| $0 (free) to $500/month \| $0 (free) to $2K/month \| +\| 10M to 100M \| $500 to $5K/month \| $2K to $20K/month \| +\| 100M to 1B \| $5K to $30K/month \| $20K to $100K/month \| +\| 1B+ \| Custom negotiation \| Custom negotiation \| + +PostHog is consistently more cost-effective for combined product analytics plus experiments. Amplitude charges a premium for the depth of its behavioral analytics; if experiments are the primary use, PostHog is hard to justify against. + +--- + +## The total cost frame + +Sticker price is one input to the cost decision. Total cost is the right frame. + +Engineer time. Wiring, maintenance, dashboard upkeep, debugging integration issues. Ranges from 5% to 30% of an engineer's time depending on platform and team size. Vendor-native is usually lower; warehouse-native is usually higher (more setup); multi-platform is usually highest. + +Statistical correctness. A single wrong-result experiment can cost more than a year of platform fees. If a platform's defaults produce confidently-wrong recommendations, the cost is the experiment that shipped wrong, not the platform fee. Worth a real review at platform decision time. + +Governance overhead. Self-hosted open-source platforms require self-built governance (audit, permissions, approval workflows). For regulated industries, this is hours of compliance review per quarter. Enterprise tiers absorb this overhead in their pricing. + +Migration risk. What is the cost if you choose wrong and need to migrate? See `migration-playbook.md` for engineer-week ranges. Multiply by the probability you will need to migrate, and that is the migration risk component of total cost. + +Cultural drift. The platform's defaults shape what the team thinks experimentation is. PM-led platforms produce PM-led cultures. Marketing-led platforms produce marketing-led cultures. The drift is hard to price but real. + +--- + +## Finance conversation patterns + +Three patterns that work when justifying a platform decision to finance. + +### Pattern 1: cost per experiment + +Compute the all-in cost per experiment shipped: platform fees plus engineer time amortized across experiments per year. This converts platform cost into a unit that finance understands. A team running 50 experiments per year on a $40K platform fee is paying $800 per experiment in platform alone, plus engineer time. A team running 200 experiments on the same fee is paying $200 per experiment. + +The frame: more experiments per year reduces unit cost. Justify investment by showing a path to higher experiment throughput. + +### Pattern 2: avoided wrong-result experiments + +Estimate the cost of a wrong-result decision. For revenue experiments, this is often $50K to $500K (the value of the experiment shipped wrong). Multiply by the rate of wrong-result decisions before and after a platform change. + +The frame: a more rigorous platform avoids wrong-result decisions. A few avoided wrong-results per year easily justify the platform premium. + +### Pattern 3: total cost of ownership across alternatives + +Build a 3-year TCO model for the top two or three candidates. Include platform fees, engineer time, migration costs, and governance overhead. Show the comparison. + +The frame: the cheapest sticker price is rarely the cheapest TCO. The platform that minimizes engineer time often wins on TCO even if it costs more per month. + +Use whichever pattern matches finance's mental model. Pattern 1 works for ROI-focused finance leaders. Pattern 2 works for risk-focused leaders. Pattern 3 works for procurement-focused leaders. + +--- + +## Negotiation tips + +Three patterns work in vendor negotiations. + +1. Multi-year commits unlock 15 to 30% discounts. If the team is confident in the platform, lock in the discount. +2. Event volume tiers are negotiable. The published pricing is the starting position. Custom contracts at scale always run below it. +3. Bundle features for unit-cost reduction. Combining experiments and feature flags in one contract often costs less than the same features separately. + +Do not negotiate from desperation. If the team is in a "we have to migrate this quarter" position, the vendor knows and the discount evaporates. Negotiate from a position of optionality: keep the trial of the alternative platform live until the contract closes. diff --git a/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md b/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md new file mode 100644 index 0000000..f7db5ca --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/governance-and-team-setup.md @@ -0,0 +1,133 @@ +# Governance and team setup + +Permission tiers, approval workflows, audit trail requirements, environment promotion, team fit assessment, and onboarding playbooks. + +Governance is the unglamorous discipline that prevents the worst outcomes. A team that ships fast without governance will eventually have an "anyone can modify production targeting" incident. This reference is the structure that prevents it. + +--- + +## The four governance pillars + +### Permission tiers + +A typical permission model has four tiers. + +1. Read. See experiments, flags, and results. Default for analysts, partners, and read-only stakeholders. +2. Author. Create and modify experiments and flags in non-production environments. Default for PMs and engineers shipping experiments. +3. Production. Modify production targeting. Reserved for senior engineers, leads, or designated experiment owners. +4. Admin. Manage users, billing, integrations. Reserved for engineering leadership and platform owners. + +Map roles to tiers. Document who has which tier. Review quarterly. Remove access proactively when someone changes roles. + +For platforms that do not natively support fine-grained permissions (some open-source self-hosted setups), build the permission model in the deployment process. For example, only certain CI/CD pipelines can push to production targeting. + +### Approval workflows + +Production-impacting changes go through review. The minimum approval workflow has three steps. + +1. The author proposes the change (new experiment, modified targeting, rollout to higher percentage). +2. A second person reviews. The reviewer is not the author. +3. The change is logged with actor, timestamp, before-and-after, and reason. + +Lighter approval is acceptable for low-risk experiments (5% rollout to internal users). Stricter approval applies to high-risk experiments (revenue, billing, security-adjacent). + +Some platforms (Optimizely Enterprise, Statsig Enterprise) build the approval workflow into the platform. Others require self-built workflows in your deployment process or change management tool. + +### Audit trails + +Every change logged. The log includes actor, timestamp, before state, after state, and reason. The log is immutable and queryable. + +Audit trails matter for two reasons. The first is compliance: regulated industries require them. The second is post-incident analysis: when a wrong-result decision ships, the audit trail tells you exactly when and why the experiment was modified. + +For platforms that do not natively log every change (smaller open-source setups), build the audit at the deployment-pipeline level. Every push to the experimentation platform's API runs through a logging proxy. + +### Environment promotion + +Experiments and flags promoted through environments: dev, staging, production. The promotion is not automatic. Each promotion is a deliberate decision. + +The minimum environment model is dev plus production. The fuller model is dev, staging, production. Larger organizations add a pre-production environment that mirrors production traffic for risk-free smoke testing. + +Promotion rules. Experiments are tested in dev first. The experiment definition (targeting, variants, metrics) is identical across environments. Only the user population differs. Promotion to production requires approval. + +--- + +## Team fit assessment + +The platform's defaults shape the team's experimentation culture. Pick the alignment that matches who you actually want running experiments. + +PM-led culture. PMs author and own experiments. Engineers wire metrics and SDK changes. The platform should have a low-overhead experiment authoring surface, clear analytics, and good metric documentation. + +Best fit: Statsig, PostHog. Both have PM-friendly authoring surfaces. + +Engineer-led culture. Engineers author and own experiments. PMs review and prioritize. The platform should have a code-first authoring surface and good SDK ergonomics. + +Best fit: PostHog, GrowthBook. Both have strong code-first paths. + +Data-team-led culture. Analysts and data scientists author experiments. The platform should have warehouse-native architecture, deep statistical defaults, and SQL-first metric definitions. + +Best fit: Eppo, GrowthBook. Both are warehouse-native. + +Marketing-led culture. Marketing teams author experiments without engineer involvement. The platform should have a visual editor and non-technical experiment authoring. + +Best fit: Optimizely, Kameleoon. Both have mature visual editors. + +The wrong fit is constant friction. A PM-led team on a marketing-led platform will struggle with the visual-editor-first authoring surface. A marketing-led team on an engineer-led platform will not be able to ship without filing engineering tickets. + +--- + +## Onboarding cost + +Time to first experiment for a new team member is a real metric. Track it after platform decisions. + +Statsig and PostHog. Hours to days. The authoring surfaces are PM-friendly; new team members can ship a low-risk experiment in a single afternoon with documentation. + +Optimizely. Days to weeks. The visual editor is approachable for non-engineers, but the platform's depth means navigation takes time. New marketing team members can ship faster than new engineering team members. + +Eppo and GrowthBook. Days if the warehouse and metrics are already wired in. Weeks if not. The setup overhead is in the warehouse layer, not the platform itself. + +Amplitude. Hours if the team is already using Amplitude for analytics. The experiments surface is a small extension of the analytics surface. New team members already familiar with Amplitude pick it up quickly. + +Kameleoon. Hours for the visual editor. Days for the win-to-code workflow. The specialty workflow has its own learning curve. + +--- + +## Onboarding playbook + +A repeatable onboarding playbook for a new PM or engineer joining an experimentation discipline. + +### Day 1: orientation + +- Read the platform documentation overview (1 hour). +- Walk through one completed experiment in the platform with the team owner (30 minutes). +- Review the team's metric definitions and ownership matrix (30 minutes). +- Get permissions provisioned at the Author tier (varies; aim for same day). + +### Day 2 to 5: shadow + +- Sit in on one experiment review meeting. +- Read the last 3 to 5 experiment writeups. +- Pair with a senior team member on a low-risk experiment. + +### Week 2: ship + +- Author and ship a low-risk internal experiment (5% rollout to internal users). +- Write up results. +- Get feedback from a senior team member. + +### Week 3 to 4: own + +- Take ownership of a backlogged experiment. +- Ship it end to end. +- Present results to stakeholders. + +After week 4, the new team member is fully onboarded. Track the time to first experiment as a metric. Investigate when it exceeds two weeks; that is a signal of either platform friction or onboarding-process drift. + +--- + +## Common governance failures + +Three patterns recur. + +1. Permission creep. Everyone gets Production tier "for convenience." Six months later, no one knows who can modify production targeting. The fix is quarterly access reviews and a strict default to Read or Author tier. +2. Approval theater. Changes go through an approval workflow but reviewers do not actually review. The fix is to require a substantive comment on every approval, not just a click. +3. Audit log drift. The audit log exists but no one reads it. The fix is to surface audit log highlights (high-risk changes, unusual targeting modifications) in a weekly digest. diff --git a/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md b/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md new file mode 100644 index 0000000..2c25bfc --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/mcp-capability-comparison.md @@ -0,0 +1,97 @@ +# MCP capability comparison + +Side-by-side capability matrix across the seven covered platforms. Current as of May 2026. MCP capability evolves quickly; verify before committing. + +The matrix is organized by capability category. Read it as "if my workflow needs X, which platforms support it." If your workflow needs every capability across the board, the answer is Statsig, PostHog, or Optimizely (the most mature MCPs). If your workflow needs a specific subset, smaller MCPs may be a better fit. + +--- + +## Capability matrix + +\| Capability \| Statsig \| PostHog \| GrowthBook \| Optimizely \| Amplitude \| Eppo \| Kameleoon \| +\|---\|---\|---\|---\|---\|---\|---\|---\| +\| Read feature flags \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Create or update feature flags \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Read experiments \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Create or update experiments \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Read experiment results \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Query analytics or events \| Yes \| Yes (200+ tools) \| Limited \| Limited \| Yes \| No (REST) \| No \| +\| Manage segments and audiences \| Yes \| Yes \| Yes \| Yes \| Yes \| No (REST) \| Yes \| +\| Governance actions (permissions, audit) \| Partial \| Partial \| No \| Yes \| Partial \| No \| No \| +\| Code generation (variant to component) \| No \| No \| No \| No \| No \| No \| Yes \| +\| Hosting model \| First-party (managed) \| First-party + self-host \| First-party + OSS self-host \| Hosted Remote \| Hosted \| n/a (REST) \| Hosted Remote \| +\| Auth method \| API key \| API key \| API key \| OAuth \| API key \| n/a \| OAuth \| +\| Approximate tool count \| ~30 \| 200+ \| ~25 \| ~20 \| ~15 \| n/a \| 7 \| +\| Recommended scoping \| Default \| `?features=` to scope \| Default \| Default \| Default \| n/a \| Default \| + +--- + +## Notes per platform + +### Statsig + +The MCP is mature and covers the full Statsig surface (gates, dynamic configs, experiments, holdouts, layers). The tool count is moderate, which keeps the agent context window tight without sacrificing capability. Authentication is API-key based; provision a service account for agent workflows so the audit trail is clean. + +Recommended for AI-forward teams that want full CRUD without context window concerns. + +### PostHog + +The MCP is the most expansive of any platform here. 200+ tools cover analytics, experiments, flags, surveys, replays, and more. The breadth comes with a cost: without scoping, the agent's context window fills with tool definitions before it can do useful work. + +Use the `?features=` scoping parameter to load only the surfaces you need. For an experimentation-focused workflow, scope to flags, experiments, and analytics; skip replays, surveys, and error tracking unless they are part of the workflow. + +Recommended for AI-forward teams that need broad coverage and are willing to invest in scoping discipline. + +### GrowthBook + +The MCP is the first open-source production MCP for experimentation. It covers the GrowthBook surface (experiments, flags, metrics, segments). Tool count is moderate. Self-host means you can run the MCP inside your network for data sovereignty. + +Recommended for OSS-preferring teams and regulated industries that need the MCP inside their VPC. + +### Optimizely + +The hosted Remote MCP works in browser-based ChatGPT and Claude.ai. Authentication is OAuth, which integrates cleanly with enterprise SSO. Tool count is moderate. Coverage is solid on Web Experimentation and Feature Experimentation; Personalization features are accessed via the same surface. + +Recommended for enterprise teams that need OAuth and SSO compatibility for compliance. + +### Amplitude + +The hosted MCP is available to all customers including the free tier. Tool count is smaller than Statsig or PostHog. Coverage is strongest on analytics queries (cohorts, funnels, retention) and adequate on experiments and flags. + +Recommended for teams that primarily need analytics queries and use experiments as a supplementary capability. + +### Eppo + +No first-party MCP as of May 2026. REST API is the integration path. Workflows that depend on agent-driven experiment creation need a custom adapter or a wait until Eppo ships an MCP. + +Track for a future MCP release. The platform has the underlying API; an MCP wrapper is a likely future development. + +### Kameleoon + +Hosted Remote MCP at `mcp.kameleoon.com/mcp` with OAuth and 7 specialized tools. The tool surface is purpose-built for the win-to-code workflow. The smallest MCP in this matrix and the most opinionated. + +Recommended for teams running the marketing-site-to-product-code workflow. Layer with another MCP if your needs go beyond that scope. + +--- + +## Choosing by workflow + +Agent-driven full experiment lifecycle (create, run, monitor, conclude). Statsig, PostHog, GrowthBook, or Optimizely. All four support full CRUD via MCP. + +Agent-driven analytics queries plus light experiment work. PostHog (with scoping) or Amplitude. Both have strong analytics MCP coverage. + +Agent-driven win-to-code conversion. Kameleoon. The only platform with this workflow as a primary feature. + +Human-driven workflow where MCP is supplementary. Any of the seven. Eppo via REST works for the supplementary case. + +Compliance-sensitive workflow (SSO, audit, data residency). Optimizely (OAuth, hosted) or GrowthBook self-hosted (data residency, OSS auditable). + +--- + +## Things to check before committing + +1. Tool count and scoping. Verify the agent context window is comfortable with the platform's tool surface. PostHog without scoping fills the window fast. +2. Auth model. API key is faster to provision; OAuth is required for compliance-sensitive deployments. +3. CRUD coverage. Read-only MCPs limit your workflow. Verify create and update are supported for your target objects. +4. Hosting model. Hosted is faster to start; self-host is required for data sovereignty. +5. Trajectory. MCP capability evolves monthly. Check the platform's changelog before committing for a future-sensitive workflow. diff --git a/skills/experimentation-platform-orchestrator/references/migration-playbook.md b/skills/experimentation-platform-orchestrator/references/migration-playbook.md new file mode 100644 index 0000000..94c8ec8 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/migration-playbook.md @@ -0,0 +1,139 @@ +# Migration playbook + +Five common migration paths with effort estimates, the first 30 days plan, the 30-90 day cutover plan, and what NOT to do. + +The discipline applies to every migration. Three rules are non-negotiable: + +1. Do not parallel-run forever. Set a cutover date and hold to it. +2. Do not big-bang switch. The risk of a silent miscount is too high; you cannot tell whether the new platform is computing correctly without overlap. +3. Do not retire the old platform before all in-flight experiments complete. + +--- + +## Statsig to PostHog + +Trigger. Company has outgrown a pure experimentation platform and wants analytics, experiments, and feature flags in one surface. Often coincides with consolidating away from a separate analytics tool. + +Effort. 3 to 5 engineer-weeks. Add 2 to 4 weeks if you are also consolidating analytics. + +First 30 days plan. +- Week 1: Provision PostHog. Wire the SDK alongside Statsig. Verify event volume matches. +- Week 2: Recreate the top 5 metrics in PostHog. Compare totals against Statsig over a 7-day window. Investigate any variance over 1%. +- Week 3: Recreate 1 active experiment in PostHog as a parallel experiment. Run both for 7 to 14 days. Confirm results agree within statistical noise. +- Week 4: Decision review. Either commit to migration or roll back to Statsig only. Document the decision. + +30-90 day cutover plan. +- Migrate experiments one at a time. New experiments start in PostHog. Existing experiments complete in Statsig. +- Migrate feature flags by service. Highest-risk services move last. +- Build dashboards in PostHog before retiring Statsig dashboards. +- Final week: retire Statsig SDK from the codebase. Remove credentials. + +What NOT to do. +- Parallel-run the SDKs for more than 90 days. The dual cost compounds; the integration tax distracts. +- Migrate flags before experiments. Flags are operational; experiments are time-bound. Flag migration creates production risk that overshadows the migration value. +- Skip the metric reconciliation. Discovering a metric definition mismatch a month into the migration is the worst possible time. + +--- + +## Optimizely to Statsig + +Trigger. Budget pressure or modernization push. Often coincides with a CFO-led cost review. + +Effort. 4 to 8 engineer-weeks. Add weeks proportional to how heavily personalization features are used (Optimizely has personalization that Statsig does not match). + +First 30 days plan. +- Week 1: Feature parity audit. List every Optimizely feature in active use. Mark which ones Statsig covers, which it does not, and which need a workaround. +- Week 2: Migrate the simplest 3 experiments. Validate results match. +- Week 3: Address the personalization gap. If personalization is heavy, plan a hybrid (Statsig for product experiments, Optimizely retained for personalization, with a retirement date in 6 to 12 months). +- Week 4: Decision review. Commit to full migration or hybrid. + +30-90 day cutover plan. +- Migrate experiments first, flags second. Personalization last (or retain in Optimizely). +- Communicate clearly with non-engineering experiment authors. The visual editor change is the friction point. +- Train non-engineering authors on Statsig's experiment definition format. +- Final phase: cancel Optimizely contract on its renewal date. Do not cancel mid-term; the savings rarely justify the early-termination friction. + +What NOT to do. +- Underestimate the non-engineering author retraining. Marketing-led teams will resist the platform change harder than engineering-led teams. +- Force personalization into Statsig if the use case does not fit. A hybrid setup is cheaper than a forced consolidation that the team cannot use. +- Cancel the Optimizely contract before all in-flight experiments complete on the old platform. + +--- + +## PostHog to Eppo + +Trigger. Statistical rigor becomes the binding constraint. A data team has joined or grown, and a critical experiment surfaced a wrong-result decision that PostHog's defaults did not catch. + +Effort. 6 to 10 engineer-weeks. The migration is harder because PostHog includes session replay, error tracking, and analytics that Eppo does not replace. Plan for a dual-platform end state. + +First 30 days plan. +- Week 1: Define the scope. Eppo replaces experiments. PostHog stays for analytics, replay, and tracking. Document which surface owns what. +- Week 2: Wire Eppo SDK alongside PostHog. Configure metric definitions in the warehouse. +- Week 3: Run one parallel experiment. Compare statistical conclusions. Investigate any disagreement; this is where the rigor difference shows up. +- Week 4: Decision review. Commit to the dual-platform end state or rethink scope. + +30-90 day cutover plan. +- New experiments start in Eppo. Existing experiments complete in PostHog. +- Build the metric definition layer in the warehouse so both platforms can agree on what "activation" means. +- Set up reconciliation dashboards. The two platforms will disagree on edge metrics; surface those proactively rather than letting stakeholders find them. + +What NOT to do. +- Try to retire PostHog. The non-experiment features (replay, tracking, analytics) do not have a clean Eppo replacement. +- Skip the warehouse metric layer. Without it, the two platforms compute metrics differently and stakeholders lose trust in both. +- Use Eppo for the small experiments where statistical depth is overkill. The analyst overhead per experiment is higher in Eppo than in PostHog. + +--- + +## GrowthBook to Eppo + +Trigger. Team growth and a desire for commercial support, deeper Bayesian and sequential testing features, and decision-oriented reporting. + +Effort. 2 to 4 engineer-weeks. This is the easiest migration in the playbook because both platforms are warehouse-native; the data already lives in your stack. + +First 30 days plan. +- Week 1: Provision Eppo. Reuse the warehouse connection. +- Week 2: Recreate metric definitions. Most translate cleanly. +- Week 3: Run 1 to 2 parallel experiments to validate. +- Week 4: Cutover. New experiments in Eppo. In-flight in GrowthBook complete on GrowthBook. + +30-90 day cutover plan. +- Migrate active flag rollouts to Eppo if Eppo's flag features are sufficient. +- Retire GrowthBook 30 to 60 days after the last in-flight experiment completes. + +What NOT to do. +- Migrate flags if Eppo's flag features do not match. Run a separate flag platform if needed. +- Cancel GrowthBook before all dashboards are recreated. + +--- + +## Any to Statsig (consolidation) + +Trigger. Multi-platform mess. Common when a company has accumulated 2 to 3 platforms over time and wants to consolidate. + +Effort. 6 to 12 engineer-weeks, scaling with the number of platforms and in-flight experiments. + +First 30 days plan. +- Week 1: Inventory. List every experiment, flag, and dashboard across all platforms. Identify the canonical source of truth where they disagree. +- Week 2: Statsig provisioning. Configure metrics. Validate event volume matches. +- Week 3: Migrate the simplest 5 experiments. Validate results. +- Week 4: Migration plan with explicit retirement dates per old platform. + +30-90 day cutover plan. +- Per-platform retirement. Pick one of the old platforms to retire first (usually the smallest user base). +- Communicate retirement dates clearly. Stakeholders need 30 days of warning per platform. +- Build dashboards before retiring; never after. + +What NOT to do. +- Try to retire all old platforms at once. Sequential retirement is slower but lower risk. +- Skip the inventory step. Discovering a forgotten experiment in production after retirement is the failure mode. +- Underestimate the team training cost. Multi-platform teams have built workflow muscle memory across all of them; consolidation requires retraining. + +--- + +## Validation: how to know the migration succeeded + +Three signals that the migration is complete and successful. + +1. All in-flight experiments completed on the original platform. No experiment was stranded mid-test. +2. Metric values match within statistical noise on the new platform for at least 30 days post-cutover. Variance over 1 to 2% needs investigation. +3. The team is shipping experiments at the pre-migration rate or faster within 60 days of cutover. If velocity has not recovered, retraining or workflow changes are still needed. diff --git a/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md b/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md new file mode 100644 index 0000000..9553bc5 --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/multi-platform-orchestration.md @@ -0,0 +1,99 @@ +# Multi-platform orchestration + +When multi-platform is genuine, three coordination patterns are non-negotiable: an ownership matrix, shared metric definitions, and reconciliable dashboards. + +This reference is for the 20% of teams whose surfaces genuinely warrant more than one platform. The 80% should consolidate. If you are not sure which group you are in, the test is whether the platforms overlap. Zero overlap is a candidate for multi-platform; any overlap is a candidate for consolidation. + +--- + +## When multi-platform is warranted + +The pattern is: different surface, different audience, different metric set, no overlap. + +Marketing site plus product app. Kameleoon for personalization on the marketing site. Statsig for product experiments. The marketing site's metrics (conversion to signup, page-level engagement) do not collide with the product app's metrics (activation, retention, revenue). The two surfaces are run by different teams with different cadences. + +Content site plus product app. Optimizely or Kameleoon for content experiments. PostHog or Statsig for product. Same pattern: different surface, different audience. + +Pre-acquisition multi-tool reality. Two products from two acquired companies on different platforms. Multi-platform is the temporary reality; consolidation is the eventual answer. Plan a retirement date during the integration project. + +Specialized statistical needs. A core product on Statsig plus a specialized statistical workload (causal inference, network effects analysis) running on a separate tool. Rare but legitimate when the specialty platform has capabilities the primary platform lacks. + +--- + +## When multi-platform is a mess + +Three signals that the multi-platform setup has drifted into a consolidation candidate: + +1. The same experiment can be defined on more than one platform. Stakeholders ask "which one are we using?" and the answer is unclear. +2. Metrics differ between platforms. "Activation rate" computes one way in Statsig and another way in PostHog. Stakeholders see two numbers and trust neither. +3. Operational overhead exceeds the value of platform diversity. Engineers spend more time keeping platforms in sync than they save by using each platform's strengths. + +If two of three apply, plan a consolidation. + +--- + +## The ownership matrix + +The first artifact of a multi-platform setup is an explicit ownership matrix. It names which platform owns which surface, which metrics, and which experiments. Disagreements between platforms are resolved against the matrix. + +\| Surface \| Primary platform \| Secondary platform (if any) \| Owner \| +\|---\|---\|---\|---\| +\| Marketing site \| Kameleoon \| None \| Marketing team \| +\| Product app \| Statsig \| None \| Product team \| +\| Mobile app \| Statsig \| None \| Mobile team \| +\| Email \| None \| None \| n/a \| +\| Pricing page \| Kameleoon \| Statsig (revenue metrics) \| Marketing team primary, product team consulted \| + +Where two platforms touch the same surface (the pricing page row), name a primary and clarify what the secondary is responsible for. Ambiguity here is the source of every multi-platform drift. + +The ownership matrix lives in a single document, version-controlled, reviewed quarterly. Stakeholders refer to it instead of arguing. + +--- + +## Shared metric definitions + +The second artifact is a shared metric definitions document. The same metric should compute the same way across platforms. + +Example. "Activation rate" might be defined as: percentage of users who completed onboarding within 7 days of signup. The definition includes the event name, the time window, the denominator population, and any exclusions. Both platforms reference the same definition. + +In practice, sharing definitions across platforms is hard. Three approaches. + +Single source warehouse layer. Define metrics in your warehouse using a metrics layer (dbt, Cube, Metricflow). Both platforms query the warehouse. This is the strongest pattern. It works if both platforms support warehouse-native metrics (GrowthBook, Eppo) or have warehouse integration paths. + +Documented definitions with periodic reconciliation. Each platform has its own metric. The definitions document records what each is supposed to compute. A weekly or monthly reconciliation job compares the two and surfaces variance. This works for vendor-native platforms that do not share a warehouse. + +Tolerance for variance. Accept that the two platforms compute slightly differently and document the expected variance range. Over 1 to 2% triggers an investigation. Under 1% is treated as noise. This works when the platforms are used for different surfaces and the metrics are not directly compared across them. + +The wrong approach is no approach. Without one of these three patterns, the platforms drift, and a leadership disagreement surfaces in the worst possible moment. + +--- + +## Reconciliable dashboards + +The third artifact is dashboards that surface the same metrics from both platforms side by side. The point is not that the numbers always agree (they will not). The point is that disagreements are visible and explainable. + +A reconciliation dashboard has three columns per metric: the value from platform A, the value from platform B, and the variance with a threshold. Variance over the threshold triggers a notification. Owners investigate and either explain the variance or fix the underlying definition mismatch. + +Reconciliation runs daily for high-stakes metrics, weekly for everything else. Outputs go to a shared channel where the team sees them; do not let reconciliation reports live in a folder no one reads. + +--- + +## The "primary platform" rule + +In every multi-platform setup, one platform is canonical. If the platforms disagree, the canonical answer wins. Pick the canonical platform once, document it, and stop arguing. + +The canonical platform is usually the one that owns the surface where the metric originates. Revenue metrics: the warehouse is canonical. Product engagement: the product analytics platform is canonical. Marketing-site conversion: the marketing experiment platform is canonical. + +Without a canonical, every disagreement becomes a debate. With a canonical, disagreements become investigations into why the non-canonical platform diverged. + +--- + +## When to consolidate + +Three signals that consolidation is overdue: + +1. The reconciliation dashboard reports variance more often than not. The platforms drift faster than the team can reconcile. The cost of staying multi-platform exceeds the cost of consolidating. +2. A leadership disagreement surfaces a "which one is the source of truth" debate. Multi-platform is meant to support different surfaces, not different versions of the same answer. If the same answer has two values, consolidation is the fix. +3. The team is spending more than 10% of its experimentation operational time on platform coordination. That time should be on experiments, not platform plumbing. + +When consolidation is the right answer, see `migration-playbook.md` for the patterns. The consolidation move is almost always to whichever platform is closest to the canonical for the highest-stakes surface. diff --git a/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md b/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md new file mode 100644 index 0000000..1025a1f --- /dev/null +++ b/skills/experimentation-platform-orchestrator/references/platform-decision-matrix.md @@ -0,0 +1,61 @@ +# Platform decision matrix + +A context-to-platform map. The left column is the situation. The center column is the recommendation. The right column is the reasoning and the common alternative. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. The remaining rows are useful as cross-checks rather than primary picks. + +--- + +## The matrix + +\| Situation \| Primary recommendation \| Reasoning and common alternative \| +\|---\|---\|---\| +\| Pure SaaS, fast-growing, want one platform for flags and experiments \| Statsig \| Combined feature flags and experiments, modern statistical defaults, fast time to first experiment. Alternative: PostHog if you also want analytics. \| +\| Product-led growth, want analytics and experiments together \| PostHog \| Full-funnel context, free tier covers early growth, mature MCP for AI workflows. Alternative: Amplitude if analytics depth matters more than experiment depth. \| +\| Open-source preference, data sovereignty, warehouse-native \| GrowthBook \| Data stays in your warehouse, OSS license avoids vendor lock-in, mature statistical defaults. Alternative: PostHog self-hosted if you also need analytics. \| +\| Enterprise, marketing-led, deep personalization \| Optimizely \| Visual editing for non-engineers, mature governance, decades of features. Alternative: Adobe Target if you are already on the Adobe stack. \| +\| Already deep on Amplitude for analytics \| Amplitude \| Adding experiments is the path of least resistance. Alternative: layer Statsig or Eppo only if statistical depth becomes the binding constraint. \| +\| Data-team-led, statistical correctness paramount, MCP not yet required \| Eppo \| Strongest statistical defaults among warehouse-native platforms, decision-oriented reporting. Alternative: GrowthBook if open-source is non-negotiable. \| +\| Convert marketing-site wins into permanent code \| Kameleoon \| Purpose-built for the win-to-code path; the only platform with this workflow as a primary feature. Use alongside a primary product-experiment platform. \| +\| Regulated industry (HIPAA, FedRAMP, healthcare), self-hosting required \| GrowthBook self-hosted \| Full data residency, audit-friendly, OSS auditable. Alternative: PostHog self-hosted if you also need analytics. \| +\| Pre-PMF, low traffic, need free tier \| PostHog free or Statsig free \| Both free tiers cover the early phase. Defer the real platform decision until you have the traffic to make any platform meaningful. \| +\| 100M+ events per month, cost control is the binding constraint \| GrowthBook or Eppo \| Warehouse-native pricing scales better than vendor-native at this volume. Alternative: negotiate a custom contract with Statsig or PostHog; only worth it if vendor-native features justify the premium. \| +\| AI-forward team, MCP-first workflow important \| Statsig, PostHog, GrowthBook, or Optimizely \| All four have mature MCPs with full CRUD coverage. Avoid Eppo for now (REST only). \| +\| Mid-market SaaS, governance important, single tool preference \| Statsig \| Enterprise governance is mature, combined flags and experiments simplify the operational surface. Alternative: Optimizely if marketing-led, GrowthBook if open-source preferred. \| +\| Web-only personalization, content site, no product app \| Kameleoon or Optimizely \| Both are strong on visual editing and personalization. Kameleoon for the win-to-code workflow; Optimizely for enterprise governance. \| +\| Data warehouse already in place (Snowflake, BigQuery), small data team \| Eppo \| Statistical defaults are decision-grade, warehouse compute is already a line item, low operational burden. Alternative: GrowthBook if commercial support is not required. \| +\| Solo founder or pre-seed startup \| PostHog free or Statsig free \| Both work, both are free at this stage. Pick whichever you are more familiar with; the decision is reversible. \| + +--- + +## Worked examples + +### Example 1: Series B SaaS, 5M events/month, PM-led, considering Statsig vs PostHog + +The team has feature flags in LaunchDarkly already, has analytics in Amplitude, and is considering experiments. The PM-led culture wants experiments shipped weekly with low engineer overhead. + +Recommendation. Statsig. The PM-led culture matches Statsig's defaults. The 5M event volume is comfortably in the free tier or a small paid contract. Combined flags and experiments will likely cause a LaunchDarkly migration in 12 to 18 months, but that is a future decision, not a current one. PostHog is the alternative if the team also wants to consolidate analytics, but Amplitude is already paid for and migrating analytics is a bigger project than starting experiments. + +### Example 2: 50-person fintech, regulated industry, need data residency + +The team needs HIPAA-equivalent controls (financial regulations), data must stay in their VPC, and the engineering team is comfortable with a more hands-on platform. + +Recommendation. GrowthBook self-hosted. Data residency is a hard requirement and rules out all vendor-native options. The engineering team has the capacity to operate self-hosted. PostHog self-hosted is the alternative if analytics is also needed. + +### Example 3: Marketing-led brand, want non-engineer-shipped experiments + +The team is a marketing organization with a small engineering function. The marketing leads want to ship experiments without filing engineering tickets. + +Recommendation. Optimizely. Visual editing for non-engineers is a hard requirement. Statsig and PostHog can be used by non-engineers but require more comfort with structured experiment definitions. Kameleoon is the alternative if the win-to-code workflow is important. + +### Example 4: Data-team-led, 100M events/month, statistical depth required + +The data science team owns experimentation, runs the warehouse, and has been burned by misleading results from a less rigorous platform. + +Recommendation. Eppo. Statistical correctness is the headline. The 100M event volume makes warehouse-native pricing more attractive. The lack of MCP is acceptable because the team's workflow is data-scientist-driven, not agent-driven. GrowthBook is the alternative if open-source is required. + +### Example 5: Pre-PMF startup, 200K events/month + +The team has a product but no product-market fit. They want to start experimenting to find the wedge. + +Recommendation. PostHog free tier. Free covers the volume. Analytics plus experiments in one place lets the team learn. Defer the real platform decision until traffic is 10x higher and the platform tax becomes a real number. diff --git a/skills/feature-flagging/SKILL.md b/skills/feature-flagging/SKILL.md new file mode 100644 index 0000000..c0fa267 --- /dev/null +++ b/skills/feature-flagging/SKILL.md @@ -0,0 +1,281 @@ +--- +name: feature-flagging +description: Operational discipline for feature flags as production infrastructure. Flag types, naming, targeting rules, rollout strategy, lifecycle, governance, stale flag management, and the technical debt patterns that bite teams who weren't deliberate about it. +category: product +catalog_summary: "Flags as production infrastructure: types, naming, lifecycle, targeting, rollout, stale flag cleanup, governance" +display_order: 5 +--- + +# Feature Flagging + +A senior engineer's playbook for using feature flags well, not just frequently. + +Feature flags are infrastructure. Treated as such, they enable kill switches, gradual rollouts, A/B experiments, permission gates, and operational toggles without redeploys. Treated casually, they become the largest accumulating technical debt in your codebase: thousands of dead flags, conflicting evaluation logic, brittle targeting, and a permission surface no one fully understands. + +This skill is the discipline that prevents the second outcome. It assumes you have a feature flag platform (LaunchDarkly, Flagsmith, Split.io, VWO FME, GrowthBook, Statsig, PostHog, Optimizely; the platform does not matter for the principles). It assumes your engineering team can implement targeting rules and SDK integration. The hard part is the operational discipline, and that is what is here. + +When to use this skill: any time you are about to introduce a flag, modify a flag, audit existing flags, or design a flag-related governance policy. + +--- + +## What this skill is for + +The skill spans the operational lifecycle of a flag from creation through retirement. Flag types and the discipline of not mixing them. Naming conventions that survive code review. Lifecycle expectations baked in at creation, not bolted on later. Targeting rules that compose without fragility. Rollout strategies that match the risk profile of the launch. Stale flag management on a quarterly cadence. Governance and permissions that balance access with audit. Performance considerations so flags do not become a latency tax. Testing patterns that cover both branches. Rollback discipline. Observability across rollouts. + +The skill does not cover experiment design; for hypothesis writing, sample size, MDE, and the discipline of arriving at a defensible decision, see the `experiment-design` skill. It does not cover statistical analysis or variance reduction; those live in the `experimentation-analytics` skill. It does not cover platform-specific tooling; for MCP commands, auth, and platform-specific configuration, consult the chosen platform's documentation. This skill produces the operational shape; the platform implements it. + +--- + +## The five flag types + +Mixing flag types is the root cause of most flag mess. A flag is one of five things; commit at creation and do not let it drift. + +Release flag. Code is in production but disabled. The new feature ships dark, gets toggled on for a percentage, then ramps to 100. Lifetime: short, days to weeks. Lifecycle: clean removal after launch. Common name prefix: `release_`. + +Experiment flag. Users are randomly assigned to variants; conversion is measured. The flag controls which variant a user sees. Lifetime: medium, one to six weeks. Lifecycle: variant chosen, code paths consolidated, flag removed. Common name prefix: `exp_`. + +Operational flag. A kill switch or circuit breaker that lets ops disable a misbehaving feature without a redeploy. Lifetime: long-lived, often years. Lifecycle: usually never removed; remains as standby. Common name prefix: `ops_`. + +Permission flag. Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. Lifetime: long-lived. Lifecycle: managed alongside billing and access infrastructure. Common name prefix: `perm_`. + +Configuration flag. Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account. Lifetime: long-lived. Lifecycle: governed by sales and product agreements. Common name prefix: `cfg_`. + +Each type has different lifecycle, governance, and removal expectations. Mixing them in one flag (the flag is both a kill switch AND a permission gate AND now we are using it for an experiment) is the most common source of flag mess. When the flag's purpose changes, create a new flag and migrate. Do not overload an existing one. + +--- + +## Flag naming conventions + +A flag name encodes type, owner, and purpose. Without that encoding, a flag list at month nine is unreadable and the cleanup playbook from [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md) cannot tell what is safe to remove. + +The convention this skill recommends is `<type>_<owner>_<semantic_name>_<version_or_date>`: + +- `release_checkout_redesign_2026q2` +- `exp_billing_pricing_v2` +- `ops_search_circuit_breaker` +- `perm_enterprise_audit_log` +- `cfg_tenant_acme_custom_dashboard` + +Pick snake_case or kebab-case once, organization-wide, and stick with it. Mixing both in the same platform produces typo-driven bugs that bite at 3 AM. Vague names die a slow death: `new_feature`, `temp_toggle`, `test_flag`, `pricing_update_v3`. Within months, no one knows which `pricing_update` shipped and which is dead. + +For deeper coverage including the table of typed prefixes, owner conventions, and the migration plan for existing badly-named flags, see [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md). + +--- + +## The flag lifecycle + +Every flag has five life phases. Each phase has explicit entry and exit criteria. Skipping phases is how flag mess accumulates. + +Birth. Flag created with explicit metadata: owner, type, target removal date (for release and experiment flags), rollout plan, monitoring approach. The metadata is not optional; without it the flag has no end-of-life. + +Adolescence. The feature behind the flag is being built. Code paths exist for both the disabled (current production) branch and the enabled (new) branch. Both are tested. The flag remains off in production. + +Launch. Production rollout begins. Percentage starts low (1 or 5 percent), monitored at each step, ramps if metrics hold. Ramp gates documented in [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +Maturity. The flag is at 100 percent rollout. The new code path is the production path. Monitoring continues for at least 30 days to catch issues that did not show up during the ramp. + +Death. The flag is removed from code (PR that deletes the gating logic) and removed from the platform. The audit trail records the removal. + +The asymmetry: birth is fast (one PR creates the flag and gates the new code), death requires intentional cleanup. Most flag mess is unfinished death. Birth-and-death have to be planned together; the death plan is part of the birth metadata. + +For the per-phase checklist, see [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md). + +--- + +## Targeting rules and segmentation + +A targeting rule is the boolean expression that determines whether a user, account, or request gets the treatment branch. There are four useful target dimensions: + +- User attributes. `user.email_domain == "acme.com"`, `user.signup_date > "2026-01-01"`, `user.plan == "enterprise"`. +- Account attributes. `account.tier == "enterprise"`, `account.region == "EU"`, `account.feature_x_enabled == true`. +- Request attributes. `request.country == "US"`, `request.device_type == "mobile"`, `request.api_version >= 3`. +- Time-based. `time > "2026-06-01T00:00:00Z"`, `time < "2026-12-31T23:59:59Z"`. + +Compose with AND, OR, and NOT. Keep the expressions simple. If your rule needs three nested clauses, your taxonomy is wrong. Either define a segment (a named group of users with shared attributes) and target the segment, or split into multiple flags. + +The most common pitfall: targeting on attributes that change frequently. If the rule is `user.last_login_date > "2026-04-01"`, a user who logs in on May 1 sees the treatment, then their value changes the next day, and they see the control again. The user experience whiplashes. Volatile attributes belong in segments computed off snapshots, not in live targeting rules. + +For pattern catalog and anti-patterns, see [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md). + +--- + +## Rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile. + +Percentage rollout. The default for release flags. Start at 1 or 5 percent. Watch error rates, latency, and the primary success metric for at least one peak hour. If clean, ramp to 10. Watch. Ramp to 25, then 50, then 100. Total elapsed time depends on traffic, but a typical pattern is 1 percent for one day, then 10 percent for two days, then 50 for two days, then 100. Production rollouts that complete in under four hours are usually rolling too fast. + +Cohort rollout. Internal employees first, then beta customers, then free tier, then paid. Each cohort is a named segment; the flag advances through them in sequence. Use this for risky launches where the blast radius matters more than rollout speed. + +Geo-staged rollout. One region at a time. The default for compliance-sensitive features (data residency, regulatory disclosures, region-specific UX). Pair with the platform's region targeting capability so the rule does not have to be hand-written. + +Time-based rollout. Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment. Watch the timezone; midnight Eastern is not midnight UTC. Avoid time-based rollouts on holidays unless you have weekend on-call coverage. + +The "ramp and watch" rule: at each percentage step, monitor the system for at least one peak hour before advancing. The peak hour is when the rate of any new failure mode is highest; if the system holds at peak for an hour, the next step is safe. If you ramp during off-peak and immediately advance, you have not actually tested the change. + +For full strategy detail and a worked example for a checkout redesign, see [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md). + +--- + +## Stale flag management + +Every live flag adds runtime cost: evaluation overhead, two code paths to maintain, mental overhead for engineers who read the code. One flag is fine. Two hundred dead flags is a productivity tax that compounds. + +Most platforms support stale flag reporting: flags that have not been evaluated in N days. Threshold defaults: 30 days for release flags and experiment flags, 90 days for operational and permission flags. A flag that has not been evaluated in 30 days is either retired in production (no users in the targeting rule) or completely dead in code (the gating call has been removed but the flag itself was never deleted). + +The cleanup playbook is mechanical: + +1. Generate the stale flag report from the platform. +2. For each flag: identify owner, last evaluation, type, recommended action. +3. Triage in a quarterly meeting: keep, remove, or investigate. +4. Open one PR per flag for code-side removal. One per PR is reviewable; bundling ten is not. +5. Delete from the platform after the PR merges. + +The reason cleanup does not happen by default: removing a flag is a code change PR with review, testing, and deploy overhead. PMs do not reward it (the feature already shipped). SREs eventually get fed up with the noise. The fix is to make removal part of the launch checklist, not a separate effort. When a flag is created, the removal date is in the metadata. The launch ticket has a follow-up sub-ticket scheduled 30 days out that says "remove flag X." If the launch goes well, the sub-ticket gets done. + +For the full quarterly cadence including ownership rotation for orphan flags, see [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md). + +--- + +## Governance and permissions + +Different roles need different access. Engineering can create flags broadly. Product can author targeting rules in dev and staging. Production targeting changes deserve a smaller set of approvers. + +Recommended permission tiers: + +- Viewer. Read-only across all environments. Includes most of engineering, product, support. +- Editor. Can create and modify flags in dev and staging. Includes the team that owns the flag. +- Approver. Can promote flag changes from staging to production. Smaller group; usually the team lead and the on-call engineer. +- Admin. Full control including deleting flags, modifying permissions, and accessing audit logs. Smallest group; platform team plus a backup. + +Production-impacting flag changes go through review like deploys, not chat. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review; the rule does not silently appear in production because someone clicked a button. + +Audit trail: every flag change logged with actor, timestamp, before/after rule, reason. Most platforms expose this; configure it to write to the central log aggregator alongside other infrastructure events. + +Environment promotion: rules tested in dev, promoted to staging, promoted to production. Authoring a production rule directly in production skips both staging tests and the review gate. Treat it as a deploy: dev → staging → production, with the same review and approval at each stage. + +Emergency override: who can flip the kill switch at 3 AM? Document, test in incident drills, and confirm the override path actually works. A kill switch nobody can find is not a kill switch. + +--- + +## Flag dependencies and conflicts + +Two failure modes that come from flags interacting: + +Dependency. Flag B's code path requires flag A to be on. Hard to model in most platforms; the SDK does not know about the inter-flag relationship. Avoid where possible; if you need to express it, document in the flag description and add a unit test that fails if A is off and B is on. + +Conflict. Two flags target the same surface, last-write-wins. The result depends on evaluation order, which depends on SDK implementation, which depends on platform internals. Detect via shared-key audit: any two flags whose targeting rules overlap on the same code path is a conflict candidate. The platform usually does not flag this; the team has to audit. + +Cross-team conflict is the dangerous version: team Alpha's release flag for the checkout redesign interacts with team Bravo's experiment on the pricing page. The interaction is invisible until production users see broken UI because both flags fired. The fix is up-front coordination via the experiment registry described in `experiment-design`. Discover before launch via planning, not via a 2 AM incident. + +For mutually exclusive experiment groups (where the platform enforces that a user is in either test A or test B but never both), see the experiment-design skill's coverage of mutex enforcement. + +--- + +## Performance considerations + +A flag evaluation is a function call (cheap) plus possibly a network call to the platform (expensive). The performance question is how much you spend in the latter. + +Cache aggressively. Most server-side SDKs cache flag values per request, per session, or per user; configure the cache so the network call happens once per relevant scope, not on every flag check. A request that evaluates fifty flags should hit the platform once at request start, not fifty times. + +Bulk evaluation: most platforms support evaluating all flags for a user or context in one call. Use it. The latency cost of "fifty individual flag checks" is fifty times the per-check overhead; the latency cost of "one bulk evaluation that returns all fifty" is one round trip plus a fast lookup per check. + +SDK selection: server-side SDKs are usually preferable to client-side for sensitive logic where latency, security, and freshness matter. Client-side SDKs are appropriate for UI-only behavior where the user can see the flag value in DevTools anyway. Mixing the two creates inconsistencies; if a user gets a different flag value on the server than the client, the UI breaks. + +Latency budget: evaluating fifty flags per request should add no more than 5 ms in the typical case. If it adds more, the SDK is misconfigured (no caching, no bulk evaluation, evaluating in a hot loop). Audit before scaling. + +--- + +## Testing flag-gated code + +Both branches need tests. The disabled branch is the existing production behavior; the enabled branch is the new code. Unit tests cover both with explicit flag overrides at test setup. + +Test the transition. What happens to a user mid-session when their flag value changes? In most well-behaved systems, the user finishes their current request with the value they had at request start, then sees the new value on the next request. Document the assumption explicitly. If your system mid-flips a user inside a session, that is usually a bug. + +Integration tests with flag overrides: most platforms support test-only flag overrides that do not affect production. Use them for end-to-end tests that exercise both branches. Without test overrides, integration tests have to share the production flag config, which means you cannot test new features that are still gated off in production. + +Common failure: shipping a "wins" experiment but only the test environment had the right targeting rules. The test environment let in 100 percent of test users via a permissive rule; production rules are stricter and let in only 20 percent. The lift you measured does not translate. Catch via staged rollout: the first 1 percent in production should match the test result before you ramp further. + +--- + +## Rollback discipline + +Flags are useful for instant rollback of the gated change. They are not a substitute for code rollback. If a bug ships in code that is not flag-gated (a fix to the existing path, an unrelated change in the same deploy), flipping the flag does nothing. Treat flag rollback as one tool among several, not as the only tool. + +If flipping the flag does work, document the rollback. If it does not work, the bug is in non-flag-gated code or in flag dependencies. Diagnose accordingly; do not assume the flag failed. + +Speed matters. How fast can you flip a flag in production? The target is under 60 seconds via UI or MCP, under 5 minutes via API plus auth. If your platform takes 15 minutes to propagate a flag change, that is a real incident-response constraint and the team should know. + +Practice. Include flag rollback in incident drills. The first time you flip a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. + +--- + +## Observability on flags + +Log flag evaluations alongside other request data. The flag value at evaluation time goes on the request log as a contextual field. When you investigate a slow request or an error, the log shows which flag values were active. + +Alert on flag evaluation rate changes. If a flag's evaluation rate suddenly drops, the rule is misconfigured (no users matching) or the SDK is broken. Either way, the team should know within minutes. + +Build dashboards for production rollouts. What percentage of users see treatment versus control, broken down by region, plan, device, etc. Without the dashboard, the rollout is a black box; with it, the team can answer "are we actually rolling out evenly across segments?" without writing a SQL query. + +Connect to error tracking. When errors spike during a rollout, the dashboard should show whether errors correlate with the flag value. Spike on treatment branch = roll back the flag. Spike on both branches = the issue is unrelated and the flag rollback will not help. + +--- + +## Common failures (rapid-fire) + +A short pattern catalog. Detail in `references/`. + +- "We launched but 90 percent of users still see the old version" means the rollout rule is wrong. Audit the rule against actual user attributes. +- "We disabled the flag but the bug is still happening" means the affected code path is not flag-gated, or there is a cached value, or a dependent flag is still on. +- "We have 400 dead flags and removing them is too risky" means cleanup never happened. Start the quarterly cadence now; one PR per flag. +- "Two flags target the same code path and we don't know which wins" means a conflict. Audit shared keys, decide one of them is canonical, retire the other. +- "Our flag evaluator is causing latency spikes" means bulk evaluation or caching is missing. Audit the SDK config. +- "We need to give finance access to feature toggles but they shouldn't change production rules" means permission tiering. Viewer for finance, editor for the owning team, approver for the team lead. + +--- + +## The framework: 14 considerations for sustainable feature flagging + +When designing or auditing feature flags, walk these 14 considerations: + +1. Type clarity. Release, experiment, operational, permission, or configuration. Pick one at creation; do not let it drift. +2. Naming. Typed prefix, owner prefix, semantic name. Avoid vague. +3. Lifecycle planning. Birth and death committed at creation. Removal date in metadata. +4. Targeting taxonomy. User, account, request, or time-based. Avoid volatile attributes. +5. Rule simplicity. AND, OR, NOT only. Three nested clauses means the taxonomy is wrong. +6. Rollout match. Strategy matches the risk profile. Percentage for low risk, cohort for medium, geo for compliance, time-based for coordinated launches. +7. Ramp discipline. One peak hour at each percentage step. No four-hour rollouts. +8. Stale flag cadence. Quarterly cleanup. One PR per removal. Make removal part of the launch checklist. +9. Permission tiering. Viewer / editor / approver / admin. Fewer admins than approvers, fewer approvers than editors. +10. Environment promotion. Dev to staging to production with review gates. Production rules are not authored in production. +11. Conflict audit. Two flags on the same surface = conflict. Detect via shared-key audit; coordinate cross-team via the experiment registry. +12. Performance budget. Bulk evaluation, caching, server-side SDKs for sensitive logic. 5 ms total budget for fifty flag checks. +13. Branch testing. Both code paths covered by tests. Transition behavior documented. +14. Observability. Every flag evaluation logged. Every rollout dashboarded. Errors correlated with flag value during incidents. + +--- + +## Reference files + +The following reference files extend this skill: + +- [`references/flag-naming-conventions.md`](references/flag-naming-conventions.md): typed prefixes, owner prefixes, semantic naming patterns, and the migration plan for existing badly-named flags. +- [`references/flag-lifecycle-checklist.md`](references/flag-lifecycle-checklist.md): birth-to-death checklist organized by lifecycle phase. +- [`references/flag-types-reference.md`](references/flag-types-reference.md): the five flag types in detail with worked examples and common pitfalls. +- [`references/stale-flag-cleanup-playbook.md`](references/stale-flag-cleanup-playbook.md): quarterly cleanup process and the orphan-ownership pattern. +- [`references/targeting-rule-patterns.md`](references/targeting-rule-patterns.md): common patterns and anti-patterns for targeting rules. +- [`references/flag-rollout-strategies.md`](references/flag-rollout-strategies.md): percentage, cohort, geo, time-based, and combination strategies with a worked example. +- [`references/governance-and-permissions.md`](references/governance-and-permissions.md): permission tiers, environment promotion, approval workflows, and emergency override. + +--- + +## Closing: when to remove a flag + +The default disposition for any flag should be removal. Flags that earn permanent residence in the codebase (operational kill switches, permission flags tied to billing, configuration flags tied to contracts) are exceptions, not norms. Most release and experiment flags should be removed within 30 days of the launch decision. + +The cost of leaving them is real: every dead flag is two code paths to maintain, two test suites to keep green, and one more line of mental overhead for the engineer who reads the file next quarter. The cost compounds across hundreds of flags. + +The discipline of removing them is the discipline of caring about the codebase you will work in next quarter. It is the same discipline behind cleaning up after a deploy, removing dead imports, and writing a post-mortem within a week of the incident. None of it ships features today. All of it makes shipping features tomorrow easier. + +For platform-specific patterns (which platform handles which flag type best, what the MCP commands look like, where the gotchas live), consult the chosen platform's documentation. For the experiment-design layer above this skill (hypothesis discipline, sample size, decision-making), see the `experiment-design` skill. For the analytical layer below this skill (variance reduction, sequential testing math, Bayesian alternatives), see the `experimentation-analytics` skill. diff --git a/skills/feature-flagging/references/flag-lifecycle-checklist.md b/skills/feature-flagging/references/flag-lifecycle-checklist.md new file mode 100644 index 0000000..619adb8 --- /dev/null +++ b/skills/feature-flagging/references/flag-lifecycle-checklist.md @@ -0,0 +1,119 @@ +# Flag lifecycle checklist + +A phase-by-phase checklist for the operational discipline of a flag from creation through removal. Run through the phase the flag is currently in; do not skip ahead. + +--- + +## Phase 1: Birth (creation) + +Before merging the PR that introduces a new flag: + +- [ ] Type committed. Release, experiment, operational, permission, or configuration. Pick one. +- [ ] Name follows the convention from `flag-naming-conventions.md`. +- [ ] Owner assigned. The team or person responsible for the flag's lifecycle. +- [ ] Target removal date set in metadata (release flags: 30-60 days; experiment flags: end of test plus 14 days; operational/permission/configuration flags: "long-lived, review annually"). +- [ ] Rollout plan attached. Percentage, cohort, geo, or time-based; abort criteria defined. +- [ ] Monitoring approach attached. What metric is being watched? What alert fires if the rollout breaks something? +- [ ] Both code branches tested. The disabled branch (existing production) and the enabled branch (new code). +- [ ] Default value confirmed off in production. +- [ ] Removal sub-ticket created and scheduled (release/experiment flags only). + +If any item is no, do not merge. + +--- + +## Phase 2: Adolescence (pre-launch) + +The feature behind the flag is being built in dev and staging. The flag remains off in production. + +- [ ] Feature complete in code, both branches tested. +- [ ] QA sign-off on enabled branch. +- [ ] Staging rule mirrors planned production rule (does not have to match exactly; should be representative). +- [ ] Telemetry confirmed. Logs include flag value as a contextual field. Dashboards exist for the metrics the rollout will watch. +- [ ] Rollout plan reviewed by approver. + +--- + +## Phase 3: Launch (rollout) + +Production rollout begins. Each percentage step has its own gate. + +For each step (typical: 1% → 10% → 50% → 100%): + +- [ ] Apply rule change via platform UI, MCP, or API. +- [ ] Confirm rule applied. Flag evaluation rate matches expected percentage. +- [ ] Watch primary success metric, error rate, latency p95 for at least one peak hour. +- [ ] If clean, advance to next step. +- [ ] If degraded, hold or roll back. Document what was observed. + +At 100%: + +- [ ] Hold for 7 days at 100% before declaring launch complete. +- [ ] Confirm metrics stable across the full holding period. +- [ ] Schedule the 30-day review (calendar reminder for the owner). + +--- + +## Phase 4: Maturity (post-launch) + +Flag is at 100% rollout. Both code paths still exist. The new path is production. + +- [ ] 30-day review: any regressions detected? Any rollbacks needed? +- [ ] Confirm the removal sub-ticket created at birth still exists and is scheduled. +- [ ] Confirm no unexpected dependencies on the flag from other code paths. + +If the flag is operational, permission, or configuration, the lifecycle ends here. The flag is permanent. + +If the flag is release or experiment, proceed to Phase 5. + +--- + +## Phase 5: Death (removal) + +The flag has reached its target removal date or its purpose is complete. + +Code-side: + +- [ ] Open a single PR that removes the flag's gating logic. One flag per PR. +- [ ] Delete the disabled branch (the old code path). Keep only the enabled branch. +- [ ] Delete tests that targeted the disabled branch. +- [ ] Update any documentation that referenced the flag. +- [ ] Confirm CI passes; tests still cover the new (now permanent) code path. +- [ ] Merge the PR. + +Platform-side (after PR merges): + +- [ ] Confirm the flag has zero evaluations in the platform's dashboard for at least 24 hours. +- [ ] Archive or delete the flag from the platform. +- [ ] Audit log entry confirms deletion with actor, timestamp, reason. + +Documentation: + +- [ ] Close the original removal sub-ticket created at birth. +- [ ] Update any team-level flag inventory the team maintains. + +--- + +## Phase 6: Audit (quarterly) + +Even with the discipline above, some flags will slip through. The quarterly audit catches them. + +- [ ] Generate stale flag report from the platform (>30 days unevaluated for release/experiment, >90 days for operational). +- [ ] Triage in a meeting: keep, remove, or investigate per flag. +- [ ] Open removal PRs (one per flag) for the "remove" pile. +- [ ] Investigate the "investigate" pile; usually the answer is remove or rename. + +For the full audit pattern, see `stale-flag-cleanup-playbook.md`. + +--- + +## Common slips + +The phases above describe the disciplined path. Common slips: + +- Birth without removal date. Fix: require the removal date as part of the flag-creation form or PR template. +- Launch without monitoring. Fix: the rollout plan review at end of Phase 2 catches this. +- Maturity skipped (rolled to 100%, never reviewed). Fix: the 30-day review reminder is in the launch ticket. +- Death skipped (flag forgotten). Fix: the quarterly audit catches it. + +The slips compound. A skipped death today is one more flag to clean up at quarter end. A hundred skipped deaths over a year is the productivity tax described in `stale-flag-cleanup-playbook.md`. diff --git a/skills/feature-flagging/references/flag-naming-conventions.md b/skills/feature-flagging/references/flag-naming-conventions.md new file mode 100644 index 0000000..c5daa6d --- /dev/null +++ b/skills/feature-flagging/references/flag-naming-conventions.md @@ -0,0 +1,128 @@ +# Flag naming conventions + +A flag name encodes type, owner, and purpose. Encoding makes flag lists readable at month nine and lets the cleanup playbook tell what is safe to remove. This reference documents the conventions, shows worked examples, and provides the migration plan for existing badly-named flags. + +--- + +## The format + +`<type>_<owner>_<semantic_name>_<version_or_date>` + +Each segment is mandatory for new flags except the version/date suffix, which is recommended but optional for short-lived release flags. + +--- + +## Typed prefixes + +\| Prefix \| Type \| Lifetime \| Example \| +\|---\|---\|---\|---\| +\| `release_` \| Release flag \| Days to weeks \| `release_checkout_redesign_2026q2` \| +\| `exp_` \| Experiment flag \| 1-6 weeks \| `exp_billing_pricing_v2` \| +\| `ops_` \| Operational flag \| Long-lived \| `ops_search_circuit_breaker` \| +\| `perm_` \| Permission flag \| Long-lived \| `perm_enterprise_audit_log` \| +\| `cfg_` \| Configuration flag \| Long-lived \| `cfg_tenant_acme_custom_dashboard` \| + +Pick one prefix style organization-wide. Mixing `release_` with `release-` produces typo bugs that bite during 3 AM rollbacks. + +--- + +## Owner prefix + +The owner segment is the team or component that owns the code behind the flag. It does not have to be the team that created the flag. + +Examples: +- `checkout` for the checkout team +- `billing` for the billing team +- `search` for the search team +- `growth` for the growth team +- `infra` for platform/SRE work + +Organizations with many small teams may use a two-segment owner like `growth_signup` or `infra_db_failover`. Organizations with a single product team may use a component-level owner like `pricing`, `dashboard`, `api`. + +--- + +## Semantic name + +The semantic name describes what the flag controls. It should read naturally to someone who has not seen the flag before. + +Good semantic names: +- `redesign` (the team is redesigning a surface) +- `ml_recommendations` (the feature is ML-driven recommendations) +- `circuit_breaker` (the flag is a circuit breaker, an operational kill switch) +- `audit_log` (the feature behind the flag is an audit log) +- `single_step_billing` (a specific UX pattern the flag controls) + +Bad semantic names: +- `new_feature` (which feature?) +- `temp_toggle` (temporary for what?) +- `test_flag` (for testing what?) +- `pricing_update_v3` (which version was v3? was there a v2?) + +--- + +## Version or date suffix + +For experiment flags and release flags that may iterate, include a version or date suffix so old and new variants are distinguishable. + +- `release_checkout_redesign_2026q2`: quarter-stamped release +- `exp_pricing_test_v2`: second iteration of a pricing test +- `release_signup_form_v3_2026_05`: third iteration, May 2026 + +Operational, permission, and configuration flags usually do not need a version suffix; they are stable infrastructure. + +--- + +## Worked examples (good) + +``` +release_checkout_redesign_2026q2 +release_signup_passwordless_2026_06 +exp_billing_pricing_v2 +exp_homepage_hero_copy_test_v1 +ops_search_circuit_breaker +ops_db_failover_manual_override +perm_enterprise_audit_log +perm_eu_data_residency +cfg_tenant_acme_custom_dashboard +cfg_white_label_partner_xyz +``` + +Each name says: what type of flag, who owns it, what it controls, and (where applicable) which iteration. + +--- + +## Worked examples (bad) + +``` +new_pricing // bad: no type, no owner, no version +temp_homepage_test // bad: "temp" promises removal that never happens +billing_flag_2 // bad: vague semantic, what does flag_2 do? +killswitch // bad: which feature does this kill? +enterprise_features // bad: ambiguous, is this permission or configuration? +beta_users_only // bad: targeting concept in the flag name; rule should target, not name +``` + +--- + +## Migration plan for badly-named flags + +If the existing platform has hundreds of badly-named flags, do not rename them all at once. The pattern is to rename on touch: + +1. Establish the convention. Document it; share with the team. +2. New flags follow the convention. No exceptions. +3. Existing flags get renamed when touched: when the rule changes, when the rollout advances, when ownership transfers, when removal is scheduled. +4. Quarterly cleanup includes a "rename batch" of the 5-10 worst-named flags, especially ones that are confusing during the cleanup itself. +5. After 6-12 months, the platform stabilizes on the convention. + +Bulk renames can be scripted via the platform's API, but renaming forces a code change in every place the flag key is referenced. Bundle renames with refactors, not as standalone PRs. + +--- + +## Anti-pattern: targeting in the name + +Do not put targeting concepts in the flag name. The flag name describes what the flag controls; the targeting rule describes who sees it. + +Bad: `enterprise_users_audit_log` (the "enterprise_users" is targeting) +Better: `perm_audit_log` (the flag is a permission flag for the audit log; the rule targets enterprise users) + +If the targeting rule changes (audit log opens up to all paid customers), the flag does not need to be renamed. The rule does the work. diff --git a/skills/feature-flagging/references/flag-rollout-strategies.md b/skills/feature-flagging/references/flag-rollout-strategies.md new file mode 100644 index 0000000..3b13fdc --- /dev/null +++ b/skills/feature-flagging/references/flag-rollout-strategies.md @@ -0,0 +1,150 @@ +# Flag rollout strategies + +Different launches deserve different rollout strategies. Match the strategy to the risk profile of the change. The five patterns below cover most cases; combine them when needed. + +--- + +## Percentage rollout + +The default for release flags. The flag advances through fixed percentage steps with a monitoring gate at each step. + +Typical sequence: + +\| Step \| Percentage \| Hold time \| +\|---\|---\|---\| +\| 1 \| 1% \| At least one peak hour \| +\| 2 \| 10% \| At least 24 hours \| +\| 3 \| 50% \| At least 48 hours \| +\| 4 \| 100% \| Hold for 7 days before declaring complete \| + +Hold times are minimums. If the metric being watched takes longer than 24 hours to stabilize (retention, downstream conversion), extend the holds accordingly. + +Abort criteria at each step: +- Error rate exceeds baseline by 10 percent. +- Latency p95 exceeds baseline by 20 percent. +- Primary success metric trends materially negative. +- Any P1 alert fires that traces back to the flag. + +If any abort criterion fires, hold or roll back. Do not advance. + +--- + +## Cohort rollout + +For risky launches where the blast radius matters. Each cohort is a named segment; the flag advances through cohorts in sequence. + +Typical sequence: + +1. Internal employees only. Bugs surface from the team that can fix them quickly. +2. Beta customers (opt-in). Engaged users who tolerate roughness in exchange for early access. +3. Free-tier customers. Larger population; risk to revenue is bounded because they are unpaid. +4. Paid customers, smaller plans first. Tier-by-tier escalation. +5. Paid customers, enterprise. Last; highest revenue impact, lowest tolerance for issues. + +Each cohort hold is at least one full business cycle (5-7 days). Compress only with strong upstream confidence (the change has already shipped through internal and beta with zero issues). + +Abort criteria same as percentage rollout, plus: support ticket volume from the cohort exceeds baseline. + +--- + +## Geo-staged rollout + +Default for compliance-sensitive features (data residency, region-specific regulations, locale-specific UX). One region at a time. + +Typical sequence: + +1. Single test region (often the team's home region; US-East or EU-West for most products). +2. English-speaking regions (US, CA, UK, AU, NZ). +3. Western Europe (DE, FR, ES, IT, NL, etc.). +4. APAC (JP, SG, AU, etc.). +5. LATAM and remaining regions. + +Hold per region depends on the product. For compliance features, hold long enough to detect any regulatory complaint or support escalation; for UX features, one full business cycle suffices. + +Abort criteria same as cohort, plus: any region-specific regulatory escalation. Compliance issues are non-negotiable rollback triggers. + +--- + +## Time-based rollout + +Scheduled flips at known times. Useful for marketing-coordinated launches where the toggle has to fire at a specific moment (a press release, a partner co-launch, a planned downtime window). + +Pattern: + +1. The flag has a `time > $LAUNCH_TIMESTAMP` condition. +2. Internal QA confirms the timestamp is correct in the platform UI. +3. The launch hour arrives; the flag flips automatically. +4. The team monitors the same metrics as a percentage rollout but at the full population from minute one. + +Watch the timezone. Coordinate the timestamp explicitly: midnight Eastern is not midnight UTC; "Friday at 9 AM" is ambiguous across timezones. Use UTC in the rule and let the platform UI display in the user's local time. + +Avoid time-based rollouts: +- On weekends, unless weekend on-call exists. +- On major holidays, unless the launch is the holiday itself (rare). +- Overlapping with other major launches or known marketing campaigns; the metrics get confounded. + +--- + +## Combination strategies + +The strategies above compose. Common combinations: + +Percentage within cohort. "Roll out to 50 percent of beta customers, then ramp to 100 percent of beta, then start the cohort rollout to free tier." Useful when the blast radius matters even within a single cohort. + +Geo within percentage. "Roll out to 1 percent of users in US-East only, then 10 percent of US-East, then expand to other regions." Useful when geo isolation is important for incident containment. + +Time-based gated by cohort. "At time T, the flag turns on, but only for the beta cohort. The rollout to other cohorts happens later." Useful when the public announcement matters but the broader rollout should still be cautious. + +--- + +## Worked example: checkout redesign launch + +A team is launching a redesigned checkout flow. The change is high-risk (revenue surface, complex code, third-party payment integrations). + +Rollout plan: + +\| Day \| Stage \| Rule \| Hold \| Watch \| +\|---\|---\|---\|---\|---\| +\| 1 \| Internal \| `user.email_domain == "yourcompany.com"` \| 24 hours \| Bug reports from team \| +\| 2-4 \| Internal extended \| Same \| 72 hours \| Conversion, error rate \| +\| 5 \| Beta \| `user.beta_opted_in == true` \| 24 hours \| Conversion, error rate, support \| +\| 6-8 \| Beta extended \| Same \| 72 hours \| Conversion, primary funnel metrics \| +\| 9 \| Production 1% \| `rollout 1% of all users` \| 24 hours (must include peak) \| Full alerting \| +\| 10 \| Production 10% \| `rollout 10%` \| 24 hours \| Full alerting \| +\| 11 \| Production 50% \| `rollout 50%` \| 48 hours \| Full alerting \| +\| 13 \| Production 100% \| `rollout 100%` \| 7 days \| Full alerting \| +\| 20 \| Launch declared complete \| Same rule \| n/a \| 30-day review scheduled \| +\| 50 \| 30-day review \| Same rule \| n/a \| Decide on flag removal \| +\| 60-80 \| Flag removal PR \| Code path consolidated \| n/a \| n/a \| + +Abort criteria at every stage: +- Checkout completion rate drops more than 1 percent absolute. +- Payment failure rate increases at all. +- Error rate (any 5xx) increases by more than 10 percent. +- Support ticket volume on checkout increases. + +Total time from launch to flag-removed: about 80 days. The work to remove the flag at day 60-80 is part of the launch plan, not an afterthought. + +--- + +## When to compress + +The cadences above are conservative defaults. Compress only with strong upstream confidence: + +- The change has already shipped behind a feature flag for an extended period (release-as-experiment-as-release). +- The blast radius is genuinely small (an internal admin tool, a low-traffic settings page). +- A previous similar launch went through the full cadence with zero issues, and the new launch is structurally analogous. + +Even with strong confidence, do not skip the production 1 percent stage. The first 1 percent in production is the only stage where production-specific issues (real user agents, real network conditions, real account distributions) surface. + +--- + +## When to extend + +Extend the cadence when: + +- The metric being watched is slow (retention measured at day-7 or day-30 cannot be observed at a 24-hour hold). +- The change involves a third party (payment processor, email provider, analytics vendor) whose behavior under load is unknown. +- The team is new to flag rollouts and benefits from the slower pace as a learning exercise. + +Extension is cheaper than incident response. Conservative defaults are correct defaults. diff --git a/skills/feature-flagging/references/flag-types-reference.md b/skills/feature-flagging/references/flag-types-reference.md new file mode 100644 index 0000000..f0a1325 --- /dev/null +++ b/skills/feature-flagging/references/flag-types-reference.md @@ -0,0 +1,83 @@ +# Flag types reference + +The five flag types in detail. Mixing them in one flag is the most common source of flag mess; commit at creation and do not let the type drift. + +--- + +## Release flag + +Definition. A flag that gates a new feature so the code can ship to production while disabled. The team toggles it on for a percentage, ramps to 100, then removes the flag. + +Lifetime. Days to weeks. Most release flags should be removed within 30 days of reaching 100 percent rollout. + +Lifecycle pattern. Birth (PR adds gated code), adolescence (testing in dev/staging), launch (gradual percentage ramp in production), maturity (100 percent, monitor for 30 days), death (removal PR consolidates code paths). + +Worked example. `release_checkout_redesign_2026q2` gates a new checkout flow. Created when the new flow PR merges. Toggled on for 1 percent of users on day 1; ramps to 10 percent on day 2, 50 percent on day 4, 100 percent on day 6. Removed on day 36 after the 30-day review confirms no regressions. + +Common pitfalls. Skipping the removal step (the most common). Conflating with an experiment flag (the team wants to A/B test the rollout instead of just ramping it; that is a different type). Leaving the flag at 50 percent forever because the team is "watching" it (either ramp to 100 or roll back; do not park). + +--- + +## Experiment flag + +Definition. A flag that randomly assigns users to variants for an A/B or multivariate test. The platform tracks conversion per variant; the team decides which variant wins, then ships the winner. + +Lifetime. One to six weeks. Tied to the duration of the test. + +Lifecycle pattern. Birth (PR adds the variants behind the flag), adolescence (canary in dev/staging), launch (test runs at the full target audience), maturity (test ends, decision made), death (winning variant code consolidated; flag removed). + +Worked example. `exp_billing_pricing_v2` tests two pricing page layouts. 50/50 split. Test runs for 21 days, hits the pre-committed sample size. Variant B wins. The PR removes the flag and the variant A code path; only variant B remains in production. + +Common pitfalls. Letting the experiment flag persist after the decision (the most common). Treating an inconclusive result as "let's keep the test running" instead of "kill or redesign." Mixing experiment with release: the team uses an experiment flag to gradually ramp a feature; if it is a ramp, it is a release flag. + +--- + +## Operational flag + +Definition. A kill switch or circuit breaker. Lets ops disable a misbehaving feature without a code redeploy. The flag is on by default in production; flipped off only during incidents. + +Lifetime. Long-lived. Often years. Removed only when the underlying feature is removed. + +Lifecycle pattern. Birth (PR adds the kill switch around a risk surface), maturity (the flag sits at "on" indefinitely), occasional use during incidents. + +Worked example. `ops_search_circuit_breaker` wraps the search service. If the search service starts returning errors at high rates during a 3 AM incident, on-call flips the flag off, and the search bar shows a graceful fallback message until the underlying issue is fixed. + +Common pitfalls. No incident drill (the first time the kill switch is used should not be at 3 AM). Wrapping logic that does not need a kill switch (every feature does not need one; pick the high-risk surfaces). Conflating with a release flag (the team uses the kill switch as a rollout control; if it is a ramp, the new code path needs its own release flag, and the kill switch wraps the larger feature). + +--- + +## Permission flag + +Definition. Controls feature access by plan tier, customer cohort, or region. The free tier sees one set of features; the enterprise tier sees another. The flag is the access control mechanism. + +Lifetime. Long-lived. Tied to the business model. + +Lifecycle pattern. Birth (PR adds the gate around a paid feature), maturity (the flag stays in production indefinitely), evolution (the rule changes as plans evolve, but the flag remains). + +Worked example. `perm_enterprise_audit_log` controls access to the audit log feature. Only accounts on the enterprise plan see it. When the plan structure changes (audit log opens up to the team plan too), the rule changes; the flag remains. + +Common pitfalls. Putting permission logic in code instead of in the flag (so the team has to deploy when plans change). Conflating with configuration: permission flags govern access by plan/role; configuration flags govern behavior per tenant contract. Permission flags use the same evaluation surface as release flags but the lifecycle is fundamentally different. + +--- + +## Configuration flag + +Definition. Lets some customers see different behavior based on contractual configuration. White-label tenants, regulated regions, custom rollout schedules per account, partner integrations. + +Lifetime. Long-lived. Tied to the contract or regulatory requirement. + +Lifecycle pattern. Birth (PR adds the configuration switch for a specific tenant or partner), maturity (the flag remains as long as the contract is active), evolution (the rule changes as new tenants come on or existing ones renegotiate). + +Worked example. `cfg_tenant_acme_custom_dashboard` enables a custom dashboard for Acme Corp because their contract specifies it. The flag's targeting rule is `account.tenant_id == "acme"`. The flag remains in production as long as Acme is a customer. + +Common pitfalls. Configuration sprawl: every tenant request becomes a new flag, the platform has hundreds, no one can audit. Mitigation: use segments and tenant-attribute targeting on a smaller set of feature flags rather than per-tenant flags. Conflating with permission: configuration governs custom behavior per tenant contract; permission governs access by plan tier. + +--- + +## Anti-pattern: type drift + +A flag created as a release flag gets repurposed as an experiment, then later as a permission gate. The name still says `release_`. The targeting rule is now multi-purpose. The lifecycle expectation is unclear. Removing the flag breaks something somewhere. + +The fix is to refuse type drift. When the purpose changes, create a new flag of the new type and migrate the rule. The original flag is removed once nothing depends on it. This is more work than just changing the rule on the existing flag, but it preserves the type-clarity discipline. + +The recovery for an existing type-drifted flag: rename to one of the five types, document the current actual purpose, and treat the flag as that type from now on. The original mixed history is grandfathered; the going-forward behavior is single-typed. diff --git a/skills/feature-flagging/references/governance-and-permissions.md b/skills/feature-flagging/references/governance-and-permissions.md new file mode 100644 index 0000000..a56582d --- /dev/null +++ b/skills/feature-flagging/references/governance-and-permissions.md @@ -0,0 +1,115 @@ +# Governance and permissions + +Different roles need different access to the flag system. Engineering needs broad ability to create flags. Product needs to author targeting rules in dev and staging. Production targeting changes deserve a smaller approver pool. The pattern below balances access with audit. + +--- + +## Permission tiers + +Four tiers cover most cases. Not every organization needs all four. + +\| Tier \| Scope \| Typical members \| +\|---\|---\|---\| +\| Viewer \| Read-only across all environments \| Most of engineering, product, support, finance, executive \| +\| Editor \| Create and modify flags in dev and staging \| The team that owns the flag's surface \| +\| Approver \| Promote flag changes from staging to production \| Team lead, on-call engineer, designated approvers \| +\| Admin \| Delete flags, modify permissions, access audit logs \| Platform team plus a backup \| + +Smaller organizations may collapse Editor and Approver into a single "Engineer" tier. Larger organizations may add a fifth tier ("Owner") for cross-cutting governance. + +--- + +## Environment-based permissions + +Permissions vary by environment. The same person can have Editor in dev/staging and Viewer in production. The environment-based scope is the second axis after role. + +\| Environment \| Default access \| Notes \| +\|---\|---\|---\| +\| Dev \| Editor for engineering, Viewer for everyone else \| Sandbox; mistakes are cheap \| +\| Staging \| Editor for the owning team, Viewer for everyone else \| Pre-production; mistakes are detectable \| +\| Production \| Approver for the owning team, Viewer for everyone else \| Live; mistakes are expensive \| + +Production changes go through review like deploys. The change request describes the rule diff, the rollout plan, and the abort criteria. An approver applies the change after review. The rule does not silently appear in production because someone clicked a button. + +--- + +## Approval workflow + +For production-impacting changes: + +1. Editor authors the change in staging. +2. Editor tests the change in staging (the rule applies, the metric moves as expected). +3. Editor opens a change request in the platform (most platforms have a built-in change-request workflow; if not, a Slack channel with a bot suffices). +4. The request includes: rule diff, rollout plan, abort criteria, link to relevant ticket/PR, link to staging test results. +5. An approver reviews. If clean, applies. If not, comments and the editor revises. +6. The change applies in production with the audit trail attached. + +For low-risk operational changes (a kill switch flip during an incident), the workflow can be compressed: the approver applies directly without a separate change request, and the audit trail captures the change with the incident reference. Document this exception explicitly so emergencies do not produce unexplained audit entries. + +--- + +## Audit trail + +Every flag change must be logged with: + +- Actor (who applied it, by user identity). +- Timestamp. +- Before-state and after-state (the rule diff). +- Reason (free-text or linked ticket). + +Most platforms do this automatically. Configure the audit log to also write to the central log aggregator (Datadog, Splunk, ELK, the team's choice). The platform's audit log is fine for routine inspection; the centralized log is where investigation happens during incidents. + +Audit retention: at least one year. Two years for organizations with regulatory obligations. + +--- + +## Emergency override + +An emergency override is the path that lets on-call flip a kill switch at 3 AM without going through the standard approval workflow. + +The pattern: + +1. A small group has Approver permission on the operational kill switches specifically. +2. The group includes the on-call rotation; on-call inherits Approver for the duration of their shift. +3. Emergency overrides apply with the standard audit trail; the reason field includes the incident reference. +4. After the incident, the override is reviewed in the post-mortem. + +Test the override in incident drills. The first time on-call flips a kill switch should not be at 3 AM with revenue dropping; it should be in a drill with everyone calm. If the drill reveals the override path is broken (the on-call's account does not have the right permission, the platform's UI is confusing, the mobile app does not let you change rules), fix it immediately. + +--- + +## Service accounts + +Automation needs flag access too. CI/CD pipelines may flip flags as part of deploys; monitoring systems may flip kill switches based on alerts; orchestration agents may modify flags via MCP. + +Service accounts: + +- Each automation has its own service account with a clearly named identity (`ci_pipeline`, `monitoring_alert_bot`, `agent_orchestrator`). +- Service accounts have the minimum permission needed for their scope. The CI account that flips release flags after deploy does not need permission to delete flags. +- Service account credentials rotate on a schedule (90 days for production access). +- Audit log entries from service accounts are clearly marked so they can be filtered separately from human changes. + +Mixing human and service-account credentials in the same identity is the most common audit-trail mistake. The investigation question "who changed this flag at 2 AM" should not have the answer "an automation, but we are not sure which one because it was authenticated as a human admin." + +--- + +## The "production console freeze" anti-pattern + +Some organizations respond to a production flag incident by tightening access so much that every flag change requires a ticket, a meeting, and a 24-hour delay. The result is over-correction: routine flag changes get queued, the team starts authoring rules in code instead of in the platform, and the platform stops being load-bearing. + +The fix is not to freeze access. The fix is to: + +- Tighten the approval workflow (require change requests for production). +- Tighten the audit log (capture every change with reason). +- Tighten the emergency override (drill it). +- Loosen the day-to-day workflow so editors can do their jobs without paperwork. + +Bureaucracy substitutes for trust. Trust is built via the audit log and the approval workflow. Once the audit log is solid, day-to-day editing can stay fast. + +--- + +## Cross-team coordination + +When a flag's surface overlaps with another team's work, coordinate before the change. The experiment registry pattern from the `experiment-design` skill applies here too: maintain a shared list (in the platform, in a wiki, in a shared doc) of flags currently being modified or rolled out per surface. Before launching a flag rollout, check the registry for conflicts. + +Cross-team coordination does not have to be heavy. A 5-minute Slack check ("we're rolling out flag X on the checkout flow tomorrow at 1 PM, anyone working on adjacent flags?") is enough for most cases. The cost of skipping the check is the cross-team conflict scenario from the [SKILL.md](../SKILL.md), where two flags interact and produce broken UI. diff --git a/skills/feature-flagging/references/stale-flag-cleanup-playbook.md b/skills/feature-flagging/references/stale-flag-cleanup-playbook.md new file mode 100644 index 0000000..a4e2670 --- /dev/null +++ b/skills/feature-flagging/references/stale-flag-cleanup-playbook.md @@ -0,0 +1,116 @@ +# Stale flag cleanup playbook + +A quarterly cadence for keeping the flag inventory healthy. Without it, dead flags compound: every quarter adds 20-50 release/experiment flags that never got removed, and after two years the platform has hundreds of dead entries that nobody can confidently delete. + +The playbook is mechanical. Run it every quarter, the same way. Resist the urge to skip a quarter because the platform "looks fine." + +--- + +## What counts as stale + +\| Flag type \| Stale threshold \| +\|---\|---\| +\| Release \| 30 days without evaluation \| +\| Experiment \| 30 days without evaluation \| +\| Operational \| 90 days without evaluation \| +\| Permission \| Annual review; not "stale" by evaluation count \| +\| Configuration \| Annual review; tied to contract status \| + +Most platforms expose a "stale flag" report or a "last evaluated" timestamp per flag. If yours does not, the SDK can be configured to emit evaluation events to an analytics destination, and the analytics database becomes the source of truth. + +--- + +## Quarterly process + +### Step 1: Generate the report + +Pull the stale flag list from the platform. Filter by type-specific threshold above. Output: a list of flags with last-evaluation timestamp, owner, type, current rule. + +### Step 2: Owner triage + +For each flag in the list, route to the owner. The owner has three options per flag: + +- Remove. The flag is dead. Open a code-side removal PR. +- Keep. The flag is still load-bearing for a real reason (operational kill switch that has not fired in 90 days but should remain; permission flag for a feature whose rule is being audited annually). Document the reason; remove from this quarter's list. +- Investigate. The owner does not know why the flag exists or what it controls. Spawn a sub-task to investigate; the flag stays in next quarter's list. + +If a flag has no owner (the original owner left, ownership was never assigned, the flag predates the convention), rotate to the platform/SRE team for a forced decision in step 3. + +### Step 3: Triage meeting + +A 30-minute meeting per quarter. Attendees: representative from each team that owns flags, the platform/SRE team, the engineering lead. + +Walk the list. For each flag: + +- Confirm the owner's recommendation. +- For "investigate" flags, decide a deadline: investigation completes by next month or the flag is force-removed. +- For orphan flags (no owner, force-routed to platform), the platform team makes the call: remove if there is no evidence of active use, keep with documentation if there is. + +The meeting produces three artifacts: a remove list, a keep list with reasons, an investigate list with deadlines. + +### Step 4: Removal PRs + +One PR per flag. Bundle is tempting; resist it. One-flag-per-PR has three advantages: + +1. The reviewer can confirm the flag is genuinely dead by inspecting only the removed code paths. +2. If a flag was not actually dead (a code path uses it that the search missed), the rollback is a single revert. +3. The PR title and description reference the specific flag, which produces a clean audit trail. + +Each PR: + +- Removes the flag's evaluation calls from code. +- Consolidates the gated branches: usually keeps the "on" branch as permanent code and deletes the "off" branch. +- Removes any tests that targeted only the removed branch. +- Updates documentation that referenced the flag. + +### Step 5: Platform deletion + +After the removal PR merges and ships: + +- Wait 24 hours for the new code to fully roll out. +- Confirm the platform shows zero evaluations of the flag for the full 24-hour window. +- Archive or delete the flag from the platform. +- Audit log entry confirms deletion with actor, timestamp, reason ("quarterly cleanup, removal PR #NNNN"). + +### Step 6: Verification + +A week after platform deletion: + +- Spot-check the codebase for any remaining references to the flag's key (string-grep). Should be zero. +- Spot-check the platform for the flag's reappearance (sometimes platforms restore archived flags via API automation; rare but worth checking). + +--- + +## Orphan flags + +Orphan flags (no owner) are the hardest case. The original owner left the company, the team that owned the area dissolved, the flag predates the ownership convention. + +The pattern: + +1. Default ownership routes to the platform/SRE team. +2. The platform team asks: "Is this flag's targeting rule consistent with documented product behavior? Would removing it change observable behavior for any user?" +3. If no observable change, remove. If yes, escalate to the team most plausibly impacted. +4. If no team can be identified and no observable change is detectable, the flag is a candidate for removal in the next quarterly meeting; document the orphan status and remove on a 60-day delay so any silent dependency can be discovered. + +The 60-day delay is a hedge against unknown dependencies. In most cases, no one notices and the flag is safely removed. In the rare cases where a forgotten cron job or a downstream service was depending on the flag, the issue surfaces during the delay window. + +--- + +## Tooling + +Most platforms provide some automation: + +- LaunchDarkly: Code References finds usages in the codebase, flags candidates for removal. +- Statsig: Stale Gates report. +- GrowthBook: stale flag dashboard. +- Flagsmith: change request workflow integrates removal with governance. + +The automation reduces manual work but does not replace the triage meeting. The meeting is where humans make the keep/remove decision, which is the part automation cannot do. + +--- + +## Make removal part of the launch checklist + +The most important pattern is upstream: make flag removal part of the launch checklist, not a separate quarterly effort. When a release flag is created, the launch ticket has a sub-ticket scheduled 30 days out: "Remove flag X." When the launch goes well and the flag reaches 100 percent, the sub-ticket gets done as part of post-launch hygiene. + +Quarterly cleanup is the safety net for everything that slips past the upstream discipline. The discipline reduces the safety-net workload from "300 dead flags" to "5 dead flags," which is the difference between a 30-minute triage meeting and a multi-day project. diff --git a/skills/feature-flagging/references/targeting-rule-patterns.md b/skills/feature-flagging/references/targeting-rule-patterns.md new file mode 100644 index 0000000..edabbe0 --- /dev/null +++ b/skills/feature-flagging/references/targeting-rule-patterns.md @@ -0,0 +1,183 @@ +# Targeting rule patterns + +Common patterns and anti-patterns for flag targeting rules. The patterns work; the anti-patterns produce flag mess that takes quarters to unwind. + +--- + +## Pattern: percentage rollout + +Default: flag off (0 percent). Override: flag on for a percentage of the user population. + +``` +Default rule: off +Override: rollout 10% of all users +``` + +The platform handles the bucketing (usually a stable hash on user ID, so the same user gets the same value across requests). Use this for release flags during ramps. + +Variation: percentage within a segment. `Default off; rollout 50% of users where account.tier == "enterprise"`. Useful when the rollout should reach only a subset of the population. + +--- + +## Pattern: internal-only + +Restrict the flag to internal employees first. The flag is on for `@yourcompany.com` emails; everyone else sees the disabled state. + +``` +Default rule: off +Override: on if user.email_domain == "yourcompany.com" +``` + +Use this for the first stage of a sensitive release. Internal users find bugs without external exposure. + +--- + +## Pattern: opt-in beta + +Users who have opted into beta features see the flag on. Implementation requires an opt-in mechanism somewhere in the product (settings page, signup flow, support request). + +``` +Default rule: off +Override: on if user.beta_opted_in == true +``` + +Use this for risky features that need engaged-user feedback. The opt-in is the consent mechanism; the flag is the access mechanism. + +--- + +## Pattern: cohort-based + +Target a named segment defined elsewhere in the platform. The segment captures the cohort logic so the flag rule stays simple. + +``` +Default rule: off +Override: on if user IN segment "early_access_2026q2" +``` + +Use this when the cohort is shared across multiple flags (the same set of "early access" users sees several features). The segment is the single source of truth; flags reference it. + +--- + +## Pattern: geo-staged + +Target users by region. The country or region attribute usually comes from the request (IP-based geolocation) or the account profile. + +``` +Default rule: off +Override: on if request.country IN ("US", "CA") +``` + +Use this for compliance launches (data residency regulations, region-specific UX). Stage the rollout: US first, then EU, then APAC. + +--- + +## Pattern: time-based scheduled flip + +The flag turns on at a specific time. Useful for marketing-coordinated launches. + +``` +Default rule: off +Override: on if time > "2026-06-01T12:00:00Z" +``` + +Watch the timezone. Avoid scheduling on weekends or holidays unless on-call coverage exists for the rollout window. + +--- + +## Pattern: composition (cohort within percentage) + +A percentage of a cohort. Useful when the rollout should be slow even within an opt-in group. + +``` +Default rule: off +Override: on if user.beta_opted_in == true AND rollout 25% of those users +``` + +Order matters: the percentage applies to the cohort, not the full population. The platform's rule editor usually makes this clear. + +--- + +## Anti-pattern: volatile-attribute targeting + +Targeting on attributes that change frequently produces user-experience whiplash. + +Bad: +``` +Override: on if user.last_login_date > "2026-04-01" +``` + +A user's last_login_date changes every time they log in. They see the treatment one day, the control the next. The experience flickers; conversion data is noise. + +Fix: target on stable attributes. Or, snapshot the attribute at a fixed point (`user.first_login_date_was_after_2026_04_01`) and use the snapshot. + +--- + +## Anti-pattern: deeply nested AND/OR + +If your rule has three levels of nesting, the taxonomy is wrong. + +Bad: +``` +Override: on if ( + (user.country == "US" AND user.signup_date > "2026-01-01") + OR + (account.tier == "enterprise" AND NOT user.churned) + OR + (user.beta_opted_in == true AND request.device == "mobile") +) +``` + +The intent is unclear, the rule is fragile, and reviewing it during incidents is slow. + +Fix: define a segment that captures the intent (e.g., "eligible_for_new_dashboard") and use the segment in the flag rule. Or split into multiple flags (one for the US/recent-signup case, one for the enterprise case, one for the mobile-beta case) and let the calling code combine them. + +--- + +## Anti-pattern: production rules drift from staging + +The team tests the flag in staging with rule X. The rule that ships in production is rule Y, written directly in the production console without re-testing in staging. + +Result: the staging tests do not predict production behavior. The first 1 percent rollout in production reveals the gap, and the team scrambles to align. + +Fix: rules go through environment promotion. Author in staging, test in staging, promote to production via the platform's promotion workflow. If the platform does not have promotion, copy the rule from staging to production via a documented process and confirm the rule is identical in both before flipping production on. + +--- + +## Anti-pattern: targeting in the flag name + +Bad: `flag_name = "enterprise_audit_log"` with rule `account.tier == "enterprise"`. + +When the rule changes (audit log opens up to team-tier accounts), the flag name lies. + +Fix: name the flag for what it controls (`perm_audit_log`), let the rule do the targeting work. The rule can change without renaming the flag. + +--- + +## Anti-pattern: kill switch with a complex rule + +A kill switch (operational flag) should have a simple rule: `on for everyone` or `off for everyone`. If your kill switch's rule is `on for everyone except a specific cohort with these conditions`, you are using an operational flag as a permission gate. + +Fix: use a permission flag for the per-cohort access; use a separate operational flag (`ops_feature_x_killswitch`) for the universal kill. The operational flag wraps the entire feature; the permission flag wraps the access to the feature. + +--- + +## Pattern: explicit ramp gate + +Some platforms let you tag a flag's rule with explicit "stages." The flag advances through stages on a button press, with each stage having its own rule. + +``` +Stage 1: rollout 1% +Stage 2: rollout 10% (advance from stage 1 manually) +Stage 3: rollout 50% (advance from stage 2 manually) +Stage 4: rollout 100% (advance from stage 3 manually) +``` + +Use this when the platform supports it. The explicit stages make rollout history readable: you can see when each stage advanced, by whom, with what observed metrics. + +--- + +## Composition rule of thumb + +If a flag's rule reads naturally to a non-engineer ("on for enterprise customers in the US"), the rule is simple enough. If the rule requires a five-minute explanation, it is too complex; refactor into segments or split into multiple flags. + +The rule is read more times than it is written. Optimize for readability. diff --git a/skills/feature-launch-playbook/SKILL.md b/skills/feature-launch-playbook/SKILL.md new file mode 100644 index 0000000..119e651 --- /dev/null +++ b/skills/feature-launch-playbook/SKILL.md @@ -0,0 +1,340 @@ +--- +name: feature-launch-playbook +description: "The operational playbook for launching a feature well. Positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring with pre-defined rollback triggers, post-launch measurement against spec hypotheses, and the discipline that distinguishes shipping from releasing from actually launching. Triggers on launch plan, feature launch, launch checklist, ship vs release, rollout strategy, gradual rollout, sales enablement, support readiness, launch announcement, post-launch measurement, launch failure, declared victory too early. Also triggers when planning a launch (any size, any segment), auditing an existing launch process, fixing the we shipped it but the metric did not move problem, or building a launch checklist for the team." +category: product +catalog_summary: "The operational discipline of launching a feature well: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement" +display_order: 10 +--- + +# Feature Launch Playbook + +A veteran PM-leader's playbook for launching features well, not just shipping them. + +Most teams conflate shipping, releasing, and launching. Shipping means engineering work is complete. Releasing means users can access it, even if it is behind a flag at 1 percent. Launching is the discipline of positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement that turns "feature exists" into "feature lands." + +A feature that ships without launching costs you the same engineering investment but captures a fraction of the value. Sales does not know how to sell it. Support does not know how to help with it. Customers do not notice it. The metric you said you would move does not move because nobody knows the feature is there. + +This skill is the operational playbook. It assumes you have already written the spec (`pm-spec-writing`), prioritized it onto the roadmap (`roadmap-planning`), instrumented it (`product-analytics-setup`), and possibly tested it (`experiment-design`). The launch is the next discipline: how to actually get the feature in front of the right users, with the right context, in a way that lets you measure whether it worked. + +When to use this skill: planning a launch (any size, any segment), auditing an existing launch process, fixing the "we shipped it but the metric did not move" problem, or building a launch checklist for the team. + +--- + +## What this skill is for + +This skill spans the operational launch discipline. It composes with the rest of the Product skill suite. + +- `pm-spec-writing` defines the launch hypotheses; this skill validates them. +- `roadmap-planning` provides the launch context (what came before, what comes next). +- `product-analytics-setup` is the instrumentation prerequisite; without it you cannot measure the launch. +- `experiment-design` and `data-warehouse-experimentation` provide the methodology for testing whether the launch worked. +- `feature-flagging` provides the rollout infrastructure this skill depends on. + +This skill does not cover pricing decisions, brand campaigns, or full GTM strategy. Those need a marketing team partner; this is the PM operational playbook for the engineering and product side. + +The audience is broad: every PM ships features, every PM has launched poorly at least once, every PM benefits from a checklist that stops the worst failure modes from recurring. The voice is veteran PM-leader to PM. Specific, opinionated, honest about what discipline matters at what stage. + +--- + +## Ship vs release vs launch + +The keystone distinction. Three definitions. + +Shipping means engineering completes the work. Code is on production. No users can access it yet, or only internal users via a flag. The PR is merged and deployed. + +Releasing means users can access it. Could be 1 percent rollout, could be 100 percent. The feature is "live" in some technical sense. The flag is on for at least one user. + +Launching means positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement are all in flight. The feature has been introduced to the people who would benefit from it, with the context they need to use it. + +The pathology. PMs report "we shipped feature X" when what happened is engineering completed the work. The feature might be released to 1 percent of users with no announcement, no documentation, no sales enablement, no measurement plan. From a value-capture perspective, that is an unlaunched feature. + +The discipline. Use precise vocabulary. "Engineering shipped on Tuesday. We are releasing to 25 percent on Thursday. We are launching publicly next month." The vocabulary forces honest accounting of what has and has not happened. + +Most "feature failed" diagnoses turn out to be "feature was unlaunched." This skill is structured around the launch dimension because that is where most teams under-invest. + +--- + +## Launch tiers + +Not every feature needs the full playbook. Match the work to the feature. + +Tier 1 (full launch). Net-new product, major feature reshaping the product narrative, pricing change, breaking change. Full playbook: positioning, all comms channels, sales enablement, customer success briefing, dedicated post-launch measurement, executive announcement. + +Tier 2 (focused launch). Meaningful improvement that materially affects user value or competitive positioning. Subset of the playbook: in-app comms, blog post or release note, support readiness, rollout strategy, post-launch measurement. + +Tier 3 (release note). Incremental improvement, bug fix made positive, polish. Minimal: changelog entry, release note, light monitoring. + +The trap on either side. + +- Treating every release as Tier 1 produces comms fatigue. Customers tune out the announcement firehose; your real Tier 1 launches lose signal in the noise. +- Treating every release as Tier 3 produces unlaunched features. The feature ships, the metric does not move, the team concludes "users do not want this" when the actual cause is "users were not told." + +Match the tier to the feature. This skill primarily covers Tier 1 and Tier 2. Tier 3 is mostly the changelog discipline; the launch playbook applies but compressed to the changelog entry plus light monitoring. + +Detail in [`references/launch-tier-decision.md`](references/launch-tier-decision.md). + +--- + +## Pre-launch: positioning + +Positioning answers: who is this for, what problem does it solve, why now, and what is the user-visible promise. + +The positioning canvas. One page, filled out before any comms drafting. + +- Target user. Segment, role, jobs-to-be-done. Specific enough that a sales rep could describe the customer profile in one sentence. +- Problem it solves. Specifically, in user words. Not "we improve productivity"; instead "the customer support manager who needs to triage 200 tickets a day cannot tell which are urgent without opening each one." +- Current alternative. What users do today without this. The status quo is the real competition. +- User-visible promise. One sentence. The promise the user will hear when they encounter the feature in the wild. +- Proof points. Three to five specific capabilities or outcomes. Concrete, not adjectives. +- Anti-positioning. What this is NOT, what it does not try to do. Prevents over-promising. + +The most common positioning failure is a vague target user. "It is for PMs" is not a target. "It is for B2B SaaS PMs at companies with 50 to 500 customers who need to coordinate roadmap discussions across engineering and customer success" is a target. The specificity is what lets sales, marketing, and support speak the same language about who this is for. + +Detail in [`references/positioning-canvas.md`](references/positioning-canvas.md). + +--- + +## Pre-launch: internal alignment + +Stakeholders who need to know before launch. + +- Engineering leadership. Capacity for follow-ups, support escalations, post-launch fixes. +- Sales leadership. Revenue forecast updates, deal coaching, pipeline impact. +- Customer success leadership. Proactive customer notifications, deal saves at risk, expansion conversations. +- Marketing leadership. Paid spend coordination, blog calendar, social timing. +- Support leadership. Training, FAQ, escalation paths. +- Executive sponsor. Visibility, public messaging, investor or board reporting. + +The discipline. A single internal launch brief, distributed two to four weeks before launch (Tier 1) or one week before (Tier 2). The brief contains a one-page summary, an FAQ, a decision log of choices already made, and the launch calendar. The brief should answer "what do I need to do differently because of this launch." + +The most common internal alignment failure: launching without sales knowing. Sales finds out from a customer asking about it. Trust erodes for the next launch. The fix is the launch brief plus a sales-specific briefing one to two weeks before customer-facing launch. + +Detail in [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md). + +--- + +## Pre-launch: customer comms plan + +Channels and decision factors. + +- In-app. Highest reach for active users; right for product-internal features. Tooltips, banners, modals. +- Email (transactional or campaign). High reach across active and inactive users; right for material changes that affect existing workflows. +- Blog post. SEO plus lead gen plus narrative; right for Tier 1 launches with external story. +- Release notes. Discoverable, archived, queryable; right for every Tier 2 and above. Often the canonical reference customers find later. +- Social (LinkedIn, X, Bluesky). Reach beyond existing customers; right when launch has external narrative or competitive angle. +- Webinar or customer call. Depth for enterprise customers; right for Tier 1 with material customer impact. +- Sales-led briefing. High-touch for top accounts; right when launch affects pricing, contracts, or strategic positioning. + +For each channel: who drafts, who approves, what is the timing, what is the call to action. + +The comms calendar pattern. A single document with all channels and dates, distributed in the internal launch brief. Prevents the "blog post went out before sales got the briefing" failure. Ordering typically goes: sales briefing first, support training second, customer success outreach to top accounts third, public comms fourth. + +Detail in [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md). + +--- + +## Pre-launch: sales enablement (B2B) + +For B2B products, sales enablement is not optional for Tier 1 and most Tier 2 launches. The deliverables. + +- One-page battlecard. Positioning, target customer, top objections, proof points. Sales can read it in two minutes and pitch the feature in five. +- Demo script and recorded demo. A repeatable demo the rep can run with a customer; the recorded version is the fallback for reps who join after the launch. +- Pricing change documentation if applicable. Sales reps cannot answer pricing questions accurately without explicit guidance. +- Deal coaching guide. Which deals does this unblock, which does it complicate. Specific named accounts where appropriate. +- Internal training session live or recorded, with Q&A archived. Sales reps need the chance to ask questions before they take the feature to a customer. + +The "shadow launch" failure. Feature ships, sales hears about it from product team Slack, no battlecard, sales reps either ignore it or misrepresent it to customers. Customers churn because the feature was promised in a way that did not match reality. + +For B2C and PLG products, this section is mostly skipped. The user is the buyer; there is no sales motion. Note this explicitly so PMs in those contexts do not feel they are missing the discipline. + +Detail in [`references/sales-enablement-template.md`](references/sales-enablement-template.md). + +--- + +## Pre-launch: support readiness + +Support is often the first to encounter the failure modes of a new feature. They need. + +- Training live or recorded, with Q&A. The same content as the sales training adapted to support workflows. +- FAQ document covering known questions, known limitations, and known bugs at launch. The FAQ updates daily during the first week as new questions surface. +- Escalation path for issues that need engineering or PM. Named owners and turnaround time commitments. +- Monitoring access or a way to ask for it. Support reps should be able to verify whether a customer's issue is feature-specific. + +The discipline. The support team's confusion is the test customer's confusion. If support does not understand the feature, neither will customers. Train support before customer-facing launch comms go out. + +Detail in [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md). + +--- + +## Launch day: rollout strategy + +Four common patterns matched to feature type. + +All-at-once (big bang). Zero to 100 percent in a single deploy. Right for marketing-coordinated launches where the announcement IS the rollout. Risky for anything where bugs would affect a meaningful customer base. Use sparingly. + +Gradual percentage rollout. 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days, monitored at each step. Right for most feature launches; the default unless there is a reason to deviate. + +Flag-gated cohort rollout. Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Right for features with cohort-specific risk profiles. + +Phased launch (multi-week). Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Right for Tier 1 launches with high uncertainty about user reception. + +The decision framework. Feature blast radius times confidence in correctness times external commitments. + +- High blast radius plus low confidence plus no external commitment: phased. +- Low blast radius plus high confidence plus external launch date: all-at-once. +- The middle (most launches): gradual percentage rollout. + +Detail in [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md). + +--- + +## Launch day: monitoring + +Pre-launch, define what you will monitor and what alerts you. Common dimensions. + +- Error rates. Overall plus feature-specific. +- Latency. Overall plus feature-specific. +- Feature usage rate. People who SHOULD use it actually do. +- Funnel completion. Users complete the new flow. +- Support ticket volume. Especially feature-specific tags. +- Customer satisfaction signals. NPS comments, feedback widget mentions. + +Define the rollback trigger explicitly before launch. Examples. + +- "Error rate above 1 percent sustained for 5 minutes triggers rollback." +- "Support tickets mentioning the feature exceed 50 in the first hour triggers escalation." +- "Funnel completion drops below 50 percent of pre-launch baseline for any cohort triggers paused rollout." + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate; the rule fires automatically and the team executes the rollback. + +Detail in [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md). + +--- + +## Launch day: comms execution + +The comms calendar from the customer comms section executes on launch day. Each channel has a clear owner, a clear time, and a clear sequence. + +- In-app banner activates when rollout reaches X percent. +- Email sends after a 4-hour stability check. +- Blog post publishes at the time announced internally. +- Sales briefing happens one day before public comms. +- Support training happens one week before launch. + +The "comms misfire" failure. Blog post auto-publishes at the scheduled time, but the rollout was paused two hours earlier due to an issue. Customers click through to a feature that is behind a flag for them. They lose trust; the launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +--- + +## Post-launch: measurement against spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses about what the feature would change. The launch measurement plan validates or invalidates each. + +Four measurement dimensions. + +1. Adoption. Did the right users actually use it? The reach question. Is the feature visible to the target segment, and are they trying it. +2. Engagement. Did users who tried it come back? The stickiness question. First use is necessary but not sufficient. +3. Outcome. Did the metric the spec said this would move actually move? The effect question. The hypothesis the spec made. +4. Side effects. Did any other metric move that was not supposed to? The safety question. Sometimes the feature works but breaks something else. + +Time horizons. Most launches need two to four weeks of post-launch data for engagement signals, four to eight weeks for outcome signals. Do not declare success or failure too early. + +The "no measurement plan" failure. Feature ships; the team moves on; six months later nobody knows if it worked. The feature becomes maintenance debt; the team cannot decide whether to invest in it further. + +Detail in [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md). + +--- + +## Post-launch: iteration and follow-ups + +Within the first four weeks post-launch, expect. + +- Bug discoveries that did not surface in QA or limited rollout. +- Usability issues that did not surface in user research. +- Adoption gaps in cohorts you did not expect to under-adopt. +- Feature requests for adjacent capabilities. + +The discipline. Document every issue, triage weekly, prioritize fixes against the original measurement plan. + +If adoption is below target, the question is. Is it a marketing problem (users do not know about the feature)? A usability problem (users try the feature and bounce)? A value problem (users try the feature and do not see value)? A wrong-segment problem (the target was not who we thought)? + +Each diagnosis maps to a different fix. + +- Marketing problem: more comms, repeat comms, sales reactivation. +- Usability problem: design or onboarding fix. +- Value problem: feature redesign or repositioning. +- Wrong-segment problem: re-target the comms to a different audience. + +The "we declared victory" failure. The launch metric hits target in week 1 (often due to the launch announcement spike); the team moves on; the metric falls back to baseline by week 4. The launch was reported as successful but the feature did not actually land. + +The fix. Declare success or failure based on a stable post-launch trend, not the launch-week spike. Most launches need at least a four-week stable trend before the success or failure call is reliable. + +--- + +## Common failure modes + +Twelve patterns recur across feature launches. Detail in [`references/common-launch-failures.md`](references/common-launch-failures.md). + +- "We shipped it but nothing happened." Unlaunched. No comms plan, no internal alignment, no measurement. +- "Sales is confused and selling it wrong." No enablement. Battlecard, demo, training were skipped or rushed. +- "Support is overwhelmed." No training, no FAQ. Support is encountering the feature for the first time when customers ask. +- "We rolled out and immediately rolled back." No rollout strategy, no health check. The big-bang deploy hit production and broke. +- "The blog post went out but the feature is broken." Comms misfire. The comms were not gated on rollout health. +- "Adoption was great in week 1, now it is flat." Declared victory on the launch spike. The metric reverted to baseline. +- "We do not know if it worked." No measurement plan tied to spec hypotheses. +- "Customers say we did not tell them." Comms did not reach the right segments. Email went to active users only; inactive users were not notified. +- "Enterprise customers found out from their account manager three days late." No high-touch tier in comms. Top accounts deserve sales-led briefing before public comms. +- "Our metric moved but it was actually because of a different launch that week." No isolation. Cannot attribute the metric movement to this launch versus other concurrent changes. +- "We launched the wrong feature." Positioning unclear. Customers expected something different from what shipped; the gap between expectation and reality reads as a failed launch even though the feature works. +- "It worked but nobody knew about it internally." No internal alignment. Sales did not capitalize on the feature in deals; customer success did not save accounts that were churning over the gap this feature now closes. + +--- + +## The framework: 12 considerations for a real launch + +When planning a launch, walk these 12 considerations. Skipping any of them produces one of the failure modes above. + +1. Tier the launch. Tier 1, Tier 2, or Tier 3. Match the effort to the feature. +2. Position it. Target user, problem, promise, proof points, anti-positioning. +3. Align internally. Single launch brief, distributed two to four weeks before launch. +4. Plan customer comms. Channel mix, calendar, owners, gates. +5. Enable sales. Battlecard, demo, training, deal coaching (B2B only). +6. Ready support. Training, FAQ, escalation paths, monitoring access. +7. Pick a rollout strategy. All-at-once, gradual, flag-gated, or phased. +8. Define monitoring. Metrics, alerts, rollback triggers. Pre-defined, not in-the-moment. +9. Sequence comms execution. Gated on health checks. Never auto-fire if the rollout is paused. +10. Tie measurement to spec hypotheses. Adoption, engagement, outcome, side effects. +11. Iterate post-launch. Weekly triage. Distinguish marketing, usability, value, and segment problems. +12. Declare success or failure on a stable trend. Not the launch-week spike. + +The output of the framework is a launch plan document. The positioning canvas, the internal launch brief, the comms calendar, the rollout strategy with health-check gates, the monitoring spec with rollback triggers, and the post-launch measurement plan tied to the spec hypotheses. The plan is reviewed two weeks before launch; gaps are filled before the launch date. + +--- + +## Reference files + +- [`references/launch-tier-decision.md`](references/launch-tier-decision.md) - Tier 1, 2, 3 decision framework with worked examples. +- [`references/positioning-canvas.md`](references/positioning-canvas.md) - One-page positioning template with B2B SaaS, B2C, and developer feature examples. +- [`references/internal-alignment-checklist.md`](references/internal-alignment-checklist.md) - Stakeholders, brief structure, distribution timing by tier. +- [`references/customer-comms-playbook.md`](references/customer-comms-playbook.md) - Channels, calendar, owners, gates. +- [`references/sales-enablement-template.md`](references/sales-enablement-template.md) - Battlecard, demo, deal coaching, training (B2B). Skip note for B2C and PLG. +- [`references/support-readiness-checklist.md`](references/support-readiness-checklist.md) - Training, FAQ, escalation, monitoring access. +- [`references/rollout-strategy-patterns.md`](references/rollout-strategy-patterns.md) - Four patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. +- [`references/monitoring-readiness-checklist.md`](references/monitoring-readiness-checklist.md) - Metrics dimensions, alert thresholds, pre-defined rollback triggers. +- [`references/post-launch-measurement-framework.md`](references/post-launch-measurement-framework.md) - Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. +- [`references/common-launch-failures.md`](references/common-launch-failures.md) - Twelve failure patterns with diagnoses and fixes. + +--- + +## Closing: most failed launches are unlaunched + +When a feature "fails," the most common diagnosis is not that the feature was wrong. It is that the launch was incomplete. Sales did not know. Customers were not told. Support could not help. The metric did not move because the launch did not reach the people who would have moved it. + +Before declaring a feature failed, audit the launch against this playbook. Half the time the feature was fine; the launch never happened. + +The discipline of separating shipping from releasing from launching is the single most useful PM vocabulary upgrade. Use it explicitly. Use it in stand-ups, in roadmap reviews, in launch retrospectives. The team that uses precise language about what has happened catches unlaunched features before declaring them failed and reallocates the engineering investment toward features that would actually capture value. + +When in doubt about whether a launch is ready, ask: is the launch brief written and distributed? Has sales seen the battlecard? Does support have the FAQ? Is the rollout strategy chosen and the rollback trigger defined? Are the comms gated on a health check? Is the measurement plan tied to the spec hypotheses? + +If any of those answers is no, the launch is not ready. Delaying the launch by a week to close the gaps is cheaper than launching incomplete and capturing a fraction of the value the feature could have delivered. diff --git a/skills/feature-launch-playbook/references/common-launch-failures.md b/skills/feature-launch-playbook/references/common-launch-failures.md new file mode 100644 index 0000000..987206f --- /dev/null +++ b/skills/feature-launch-playbook/references/common-launch-failures.md @@ -0,0 +1,181 @@ +# Common launch failures + +Twelve patterns that recur across feature launches. For each: name, symptom, root cause, fix, prevention. Cross-references to other reference files. + +--- + +## 1. We shipped it but nothing happened + +Symptom. The team reports "we shipped feature X." Three weeks later, nobody is using it. The metric the spec said this would move has not moved. Internal stakeholders ask if the feature is live; nobody is sure. + +Root cause. Unlaunched. Engineering completed the work; the team did not execute the launch. No comms plan, no internal alignment, no measurement plan tied to spec hypotheses. + +Fix. Treat it as a re-launch. Audit against the playbook: positioning, internal alignment, customer comms, sales enablement, support readiness, measurement plan. Distribute the launch brief. Sequence comms. Re-measure at the four-week checkpoint. + +Prevention. The launch brief is the artifact that prevents this. Without a brief, the launch defaults to engineering completion plus silence. With a brief, the launch has a calendar, owners, and measurement. + +See: `internal-alignment-checklist.md`, `customer-comms-playbook.md`, `post-launch-measurement-framework.md`. + +--- + +## 2. Sales is confused and selling it wrong + +Symptom. Customers ask sales questions sales cannot answer. Reps over-promise capabilities the feature does not have. Customers churn because the feature was sold wrong. + +Root cause. No sales enablement. Battlecard, demo, training were skipped or rushed. Reps are improvising in front of customers. + +Fix. Pause the launch (pause public comms; let in-app and release notes continue). Run the sales enablement playbook in compressed form: write the battlecard, record the demo, hold the training. Resume public comms after sales is enabled. + +Prevention. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. Battlecard plus 30-minute training plus recorded demo. The investment is small; skipping it is the largest avoidable launch cost. + +See: `sales-enablement-template.md`. + +--- + +## 3. Support is overwhelmed + +Symptom. Support ticket volume doubles or triples on launch day. Tickets pile up. Customer wait times balloon. Support reps escalate everything to the PM. + +Root cause. No training, no FAQ, or both. Support is encountering the feature for the first time when customers ask about it. They cannot answer questions; they escalate; the queue grows. + +Fix. Emergency FAQ. PM and support lead spend 4 hours documenting every question that has come in. FAQ updates push to support immediately. Re-train if needed (a short refresher). + +Prevention. Support training one week before launch. FAQ written before launch, not during. Estimate support volume realistically; staff for elevated volume. + +See: `support-readiness-checklist.md`. + +--- + +## 4. We rolled out and immediately rolled back + +Symptom. Big-bang deploy hit production. Within minutes, error rate was up. The team rolled back. Customers experienced a broken feature for 30 minutes; some saw error states. + +Root cause. Wrong rollout strategy. All-at-once was used when gradual was the right pattern. + +Fix. Audit the rollback. What was the bug; what would have caught it earlier in a gradual rollout. Pre-mortem the next launch. + +Prevention. Default to gradual percentage rollout for most launches. Use all-at-once only when the marketing-coordinated launch makes it unavoidable, AND the team has high confidence in correctness, AND the blast radius is low. + +See: `rollout-strategy-patterns.md`. + +--- + +## 5. The blog post went out but the feature is broken + +Symptom. Blog post auto-published at the announced time. Rollout had been paused two hours earlier due to an issue. Customers click through; 75 percent of them do not have the feature; they report "broken" feature that is actually a paused rollout. + +Root cause. Comms not gated on rollout health. Auto-fire schedule executed regardless of rollout state. + +Fix. Pull or update the blog post. Communicate transparently: "We hit an issue in our rollout; the feature is paused while we resolve. Your account will get access once we resume." + +Prevention. Make external comms manually triggered, gated on health check. Auto-fire is convenient but brittle. + +See: `customer-comms-playbook.md`. + +--- + +## 6. Adoption was great in week 1, now it is flat + +Symptom. The launch announcement drove a spike of users trying the feature. By week 4, adoption has dropped back to near-baseline. The team had declared victory in week 1. + +Root cause. Declared victory on the launch spike. The metric reverted because the launch announcement was the only driver of usage; users tried the feature once but did not come back. + +Fix. Re-evaluate as if the launch is unfinished. Diagnose: was it an awareness problem (users forgot the feature exists), a usability problem (users tried and bounced), a value problem (users tried and did not see value), a wrong-segment problem (the audience was wrong). Iterate based on the diagnosis. + +Prevention. Declare success or failure on the stable post-launch trend, not the launch-week spike. Minimum measurement window is four weeks. + +See: `post-launch-measurement-framework.md`. + +--- + +## 7. We do not know if it worked + +Symptom. Six months after launch, the team cannot answer "did feature X work?" Nobody measured. The feature is now maintenance debt. + +Root cause. No measurement plan tied to spec hypotheses. The launch did not commit to specific metrics with specific decision rules. + +Fix. Retroactive measurement. Pull the data; compare to a pre-launch baseline (if one exists); compute the lift. The retroactive measurement is less rigorous than a planned one but better than nothing. + +Prevention. Every launch has a measurement plan. The plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +See: `post-launch-measurement-framework.md`. + +--- + +## 8. Customers say we did not tell them + +Symptom. A customer reaches out asking why nobody told them about a feature that has been live for two months. The customer was on the email list; the email was sent; the customer missed it. + +Root cause. Comms did not reach the right segments. Email went to active users only; inactive users were not notified. Or the email subject line was generic and customers archived without reading. + +Fix. Re-send to the cohort that missed it. Use a different channel (in-app banner, account-manager outreach for top accounts). Improve the discoverability for new visitors (pricing page mention, feature-tour highlight). + +Prevention. Channel-mix analysis. For each launch, plan which channels will reach which cohorts. Inactive users need a different reach plan than active users. + +See: `customer-comms-playbook.md`. + +--- + +## 9. Enterprise customers found out from their account manager three days late + +Symptom. Enterprise customer hears about a launch from their account manager three days after public comms went out. The customer is annoyed; their AM is embarrassed; trust erodes. + +Root cause. No high-touch tier in comms. Public comms hit before account managers had been briefed. + +Fix. Apologize to the affected customer. Brief their AM immediately with the full context. Adjust process for the next launch. + +Prevention. Sales-led briefing for top accounts before public comms. Account managers should know about the feature one to three days before customers do, with talking points for the customer conversation. + +See: `customer-comms-playbook.md`, `sales-enablement-template.md`. + +--- + +## 10. Metric moved but it was actually because of a different launch that week + +Symptom. Outcome metric is up 8 percent in the four weeks post-launch. Team celebrates. Then someone notices a different launch happened the same week, and a price test concluded, and a marketing campaign ran. The 8 percent cannot be attributed to this specific feature launch. + +Root cause. No isolation. Multiple changes hit production in the same window; effects are confounded; the team cannot tell which change drove which metric. + +Fix. Run a follow-up isolated test. Roll back the feature for a cohort; measure the gap. If the gap is large, the feature was driving the metric. If the gap is small, other concurrent changes were the driver. + +Prevention. Stagger launches. Major launches should not coincide with each other; at minimum two weeks of separation for measurement isolation. For experiments, use the warehouse-native experimentation framework to isolate. + +See: `data-warehouse-experimentation` skill. + +--- + +## 11. We launched the wrong feature + +Symptom. The launch goes out. Customers respond with "this is great but it does not solve the problem we asked you to solve." The feature works; it just was not what customers expected. + +Root cause. Positioning unclear. The customer expected something different from what shipped because the spec, the comms, or both implied a different scope. + +Fix. Re-position. Re-write the comms to match what the feature actually does. Acknowledge the gap to customers who feel misled. Plan a follow-up that addresses the original ask. + +Prevention. The positioning canvas plus anti-positioning section forces explicit definition of what the feature is and is not. Review the canvas with sales and customer success before launch; their pushback often catches the positioning gap. + +See: `positioning-canvas.md`. + +--- + +## 12. It worked but nobody knew about it internally + +Symptom. The metric moved. Customer adoption was strong. The launch was a success. Six weeks later, sales is not pitching the feature, customer success is not using it as a save argument, and the executive team has forgotten about it. + +Root cause. No sustained internal awareness. The launch hit; the team moved to the next thing; internal momentum did not carry. + +Fix. Re-brief internal stakeholders at the four-week checkpoint. Share the metrics. Highlight customer use cases. Make the feature part of the next sales kickoff or company all-hands. + +Prevention. Internal launch is not a one-time event. After the four-week measurement, revisit. Share the win story. Update the sales playbook. The launch is not over until the feature is part of the team's vocabulary for at least a quarter. + +See: `internal-alignment-checklist.md`. + +--- + +## The pattern across all twelve + +Most launch failures share one root cause. The team treated the launch as a single event (the day the feature ships) rather than a multi-week discipline (the period when the feature lands). + +The shipping vs releasing vs launching distinction names this. Shipping is a moment; releasing is a moment; launching is a discipline that spans the four to eight weeks before and after. Teams that invest in the discipline catch most failure modes early; teams that treat the launch as a moment hit failure modes late or never. + +The fix at the meta level. Pre-launch checklist. Launch-day standup. Post-launch measurement at four-week and eight-week checkpoints. The discipline is the only thing that produces consistent launches across many features. diff --git a/skills/feature-launch-playbook/references/customer-comms-playbook.md b/skills/feature-launch-playbook/references/customer-comms-playbook.md new file mode 100644 index 0000000..739ade4 --- /dev/null +++ b/skills/feature-launch-playbook/references/customer-comms-playbook.md @@ -0,0 +1,148 @@ +# Customer comms playbook + +Channels, decision factors, calendar template, comms misfire failure mode. + +The principle. Every channel has a different reach, latency, and cost. Pick the channels that match the feature's audience and tier; sequence them so the highest-touch channels fire first and the highest-reach channels fire last. + +--- + +## Channel-by-channel + +### In-app + +Reach. Active users only. Highest engagement among the people who already use the product. + +Latency. Real-time once the rollout reaches them. + +Right for. Product-internal features. Tooltips, banners, modals. Discoverability prompts. + +Decision factors. Are users active enough to encounter the in-app surface within the launch window? If your DAU is 10 percent of MAU, in-app reaches one in ten users in the first week. + +Anti-pattern. Modal interrupting the user mid-task. Use banners, tooltips, or empty-state prompts that the user notices but does not have to dismiss. + +### Email (transactional or campaign) + +Reach. All users who opted in. Higher than in-app for inactive users. + +Latency. Hours from send to read. Delays for users who batch-read email. + +Right for. Material changes that affect existing workflows. Pricing changes. Breaking changes that need user awareness. + +Decision factors. Is the change material enough to justify an email? If the user can discover the feature on their next visit, email may be unnecessary. If the change affects their billing or their workflow, email is the right channel. + +Anti-pattern. Sending email for every release. Customers unsubscribe; the channel decays. + +### Blog post + +Reach. External traffic plus existing customers who read the blog. Best for SEO, lead gen, narrative. + +Latency. Hours to days from publish to traffic peak. + +Right for. Tier 1 launches with external story. Competitive positioning announcements. Major narrative shifts. + +Decision factors. Is there a story worth telling beyond "we shipped a feature"? Blog posts about feature ships read as marketing churn; blog posts about category narrative shifts read as substantive. + +### Release notes + +Reach. Customers who actively check release notes. Discoverable later via search. + +Latency. Real-time on publish; the long-tail value comes from search-engine and customer-search traffic over the following months. + +Right for. Every Tier 2 and above. The canonical reference customers find later when they encounter the feature in the wild. + +Decision factors. Always. Release notes are the cheapest comms channel; the cost of writing one is small; the long-tail value is real. + +### Social (LinkedIn, X, Bluesky) + +Reach. Beyond existing customers. Mostly other PMs, engineers, prospects. + +Latency. Hours to days from post to engagement. + +Right for. Launches with external narrative or competitive angle. Founder-led marketing. + +Decision factors. Does the launch have a story that a non-customer would care about? If no, social is filler. If yes, social can drive net-new pipeline. + +### Webinar or customer call + +Reach. Limited to attendees, but high engagement per attendee. + +Latency. Days to weeks from announcement to event. + +Right for. Tier 1 launches with material customer impact. Enterprise customers who need depth. + +Decision factors. Does the feature need explanation that a blog post or email cannot deliver? If yes, webinar. If the feature is self-evident, skip. + +### Sales-led briefing + +Reach. Top accounts only. Highest-touch channel. + +Latency. Days from scheduling to delivery. + +Right for. Launches affecting pricing, contracts, or strategic positioning. Top accounts hear about the feature from their account executive before they hear from any other channel. + +Decision factors. Does the launch affect the top 10 to 20 accounts in a way that requires a personal conversation? If yes, sales-led briefing is non-negotiable. + +--- + +## The comms calendar + +A single document with all channels and dates. Distributed in the internal launch brief. + +\| Date \| Channel \| Owner \| Status \| Notes \| +\|---\|---\|---\|---\|---\| +\| T minus 14 days \| Sales briefing scheduled \| Sales lead \| Pending \| 30-min training \| +\| T minus 7 days \| Support training delivered \| Support lead \| Pending \| Live + recorded \| +\| T minus 3 days \| CS outreach to top 20 accounts \| CS lead \| Pending \| Email plus call \| +\| T minus 1 day \| Sales briefing delivered \| Sales lead \| Pending \| Q&A captured \| +\| T minus 1 day \| Support FAQ published internally \| Support lead \| Pending \| \| +\| T plus 0 (launch day, AM) \| In-app banner activates \| Eng \| Auto on rollout \| Gated on health \| +\| T plus 0 (launch day, AM) \| Release notes publish \| PM \| Manual on health \| \| +\| T plus 0 (launch day, PM) \| Email send to all customers \| Marketing \| Manual on health \| After 4-hr stability \| +\| T plus 1 day \| Blog post publishes \| Marketing \| Manual on health \| \| +\| T plus 1 day \| Social posts \| Marketing + founder \| Manual on health \| \| +\| T plus 7 days \| Webinar (Tier 1 only) \| PM + Marketing \| Scheduled \| \| +\| T plus 14 days \| First post-launch checkpoint \| PM \| Recurring \| Adoption review \| + +The calendar names every channel, every date, every owner. Gaps in the calendar signal channels that are not covered (intentionally or accidentally). + +--- + +## Sequencing principles + +Highest-touch first. Sales-led briefing for top accounts before public comms. The top customer hearing about a feature from their account manager before they hear from a blog post is a trust win; the inverse is a trust loss. + +Internal before external. Sales training before sales is asked customer questions. Support training before customers ask support questions. Internal launch brief before any customer-facing channel fires. + +Health-check gates on auto-fire channels. In-app banners, scheduled emails, scheduled blog posts should be gated on a rollout health check. Manual triggers preferred for any channel that would be embarrassing if the rollout is paused. + +Lower-reach to higher-reach. Release notes and in-app first; email second; blog and social last. The lower-reach channels catch initial issues; the higher-reach channels amplify after stability. + +--- + +## The comms misfire failure + +The most common comms execution failure. + +The setup. The blog post is scheduled to auto-publish at the announced launch time. The rollout starts at 9 AM. At 11 AM, an issue is detected and the rollout is paused at 25 percent. The blog post auto-publishes at noon as scheduled. + +The result. Customers click through to the new feature page. 75 percent of them do not see the feature (the rollout has not reached them). They report bugs that are actually rollout-paused state. The launch story breaks. + +The fix. Make external comms manually triggered, gated on a rollout health check. The comms timing in the calendar is the planned timing; the actual fire is conditional on the rollout passing the health check. + +The pattern. Auto-fire is convenient but brittle. Manual triggers are slightly more work but catch issues that auto-fire cannot. + +--- + +## Channel-mix rules of thumb by feature type + +\| Feature type \| Recommended channel mix \| +\|---\|---\| +\| New feature for active users (Tier 2) \| In-app + release notes \| +\| Major feature launch (Tier 1, B2B) \| All channels: in-app, email, blog, release notes, social, sales-led briefing for top accounts \| +\| Pricing change \| Email + blog + sales-led briefing + executive comms; in-app for affected users \| +\| Breaking change \| Email + in-app prominent banner + release notes + (B2B) sales-led briefing \| +\| Performance improvement \| Release notes + (Tier 2) in-app + (Tier 1) blog post \| +\| New integration \| Release notes + email + blog + co-marketing with the integration partner \| +\| Enterprise-only feature \| Sales-led briefing + customer success outreach + release notes; skip blog and social \| + +The pattern. The channel mix is not "all channels" by default. It is the subset of channels that match the audience and the tier. Skipping the wrong channel hurts; firing on the wrong channel also hurts. diff --git a/skills/feature-launch-playbook/references/internal-alignment-checklist.md b/skills/feature-launch-playbook/references/internal-alignment-checklist.md new file mode 100644 index 0000000..13637c1 --- /dev/null +++ b/skills/feature-launch-playbook/references/internal-alignment-checklist.md @@ -0,0 +1,144 @@ +# Internal alignment checklist + +Stakeholders, brief structure, distribution timing. The launch brief is the single document that aligns everyone before customer comms go out. + +The principle. Internal alignment fails silently. The team does not know they are misaligned until a customer asks sales a question that sales cannot answer, or a customer escalates an issue support did not know existed. The launch brief catches misalignment before customers do. + +--- + +## Stakeholders by org type + +### Small startup (under 50 employees) + +- Engineering lead. Capacity for fixes, support escalation handling. +- Sales lead (if B2B). Pipeline impact, deal coaching. +- Customer success / support lead. Often the same person at this size. +- Marketing or content lead (if exists). Comms execution. +- Executive sponsor. Usually CEO at this size. + +The brief is shorter at this size; the meeting is faster; but the discipline still matters. The "small team did not need a launch brief" assumption is a frequent source of small-launch failures. + +### Mid-size (50 to 500 employees) + +- Engineering leadership. +- Sales leadership and at least one regional sales lead. +- Customer success leadership. +- Marketing leadership. +- Support leadership. +- Executive sponsor (VP-level for most launches; C-level for Tier 1). + +The brief is longer. The launch meeting includes a Q&A. Decision log captures the questions and answers; the log is part of the brief. + +### Enterprise (500+ employees) + +- Engineering leadership. +- Sales leadership across regions and segments. +- Customer success leadership. +- Marketing leadership including PMM (product marketing manager). +- Support leadership. +- Legal, security, and compliance (for features touching pricing, data, or regulated workflows). +- Executive sponsor (C-level for Tier 1). + +At this size, the launch brief is a formal document with sections owned by different functions. PMM often co-owns the brief with the PM. + +--- + +## The launch brief + +A single document distributed two to four weeks before Tier 1 launch, one week before Tier 2 launch. + +### Section 1: one-page summary + +Top of the brief. The PM writes it. The reader should be able to answer "what is launching, when, who is it for, why now" after one minute. + +### Section 2: positioning + +The positioning canvas (from the positioning-canvas reference) embedded directly. Target user, problem, current alternative, user-visible promise, proof points, anti-positioning. + +### Section 3: launch calendar + +Every channel and every date. In-app banner activation, email send, blog post publish, social post times, sales briefing, support training, customer success outreach windows. Owners named for each. + +### Section 4: what each function needs to do differently + +The most important section for the readers. Each function gets a paragraph. + +- Sales. Battlecard link. Demo recording link. Top objections and answers. Deals to revisit. Training session date. +- Customer success. Top accounts to brief. Talking points for the briefing. Escalation contact during launch week. +- Support. Training session date. FAQ link. Escalation path. Ticket tagging convention. +- Marketing. Channel list, dates, message variants by channel. +- Engineering. On-call coverage during launch. Rollback authority. Health-check dashboard link. + +If a function does not have a paragraph, the launch was not designed with that function in mind; revisit before distributing. + +### Section 5: FAQ + +The questions that have already come up internally, with answers. The FAQ updates daily during the first week of distribution as new questions surface. + +### Section 6: decision log + +Choices already made. Includes the rationale for non-obvious decisions. Future questions ("why did we pick that rollout strategy?") get answered by reading the log instead of re-litigating the decision. + +--- + +## Distribution timing + +\| Tier \| Timing \| Channel \| +\|---\|---\|---\| +\| Tier 1 \| 2 to 4 weeks before launch \| Email plus async meeting plus 1:1 follow-ups for sales and CS \| +\| Tier 2 \| 1 week before launch \| Email plus async meeting \| +\| Tier 3 \| Day of launch or as part of a weekly release digest \| Email or shared doc \| + +The pattern. Launch brief lands first. Sales briefing, support training, customer success outreach all happen after the brief lands and before the public comms fire. + +--- + +## The pre-launch meeting + +For Tier 1 launches, hold a 30-minute pre-launch meeting one week before launch. + +Agenda. + +1. PM walks through the positioning canvas and the calendar (10 minutes). +2. Each function lead confirms their readiness (10 minutes). +3. Open Q&A captured in the decision log (10 minutes). + +The meeting is not for re-litigating the launch. It is for confirming readiness and catching last-minute gaps. If functions are not ready, the launch is delayed. The PM has authority to delay; the executive sponsor confirms. + +--- + +## The launch-day standup + +For Tier 1 launches, hold a brief launch-day standup at the start of launch day. Five to ten minutes. + +Agenda. + +1. Confirm rollout health check is green. +2. Confirm comms are gated on the health check (the social post will not auto-fire if the rollout is paused). +3. Confirm support is staffed for the launch window. +4. Confirm escalation contacts are reachable. +5. Open the post-launch monitoring channel. + +The launch-day standup catches "the marketing person took the day off and the social post is set to auto-fire" the morning of launch instead of in the moment. + +--- + +## Common internal alignment failures + +- Launching without sales knowing. Sales finds out from a customer. Trust erodes for the next launch. Fix: launch brief plus sales-specific briefing one to two weeks before public comms. +- Sales briefing is the launch brief. Sales reads a 12-page document. Their actual takeaway is partial. Fix: separate one-pager for sales (the battlecard) plus the full brief for reference. +- Support is trained the day of launch. Support cannot internalize a new feature in one morning. Fix: train support one week before customer-facing launch. +- Customer success outreach happens after public comms. Top accounts hear about the feature from the email blast like everyone else. Fix: customer success briefs top accounts one to three days before public comms. +- Executive sponsor is surprised on launch day. The executive read the brief but did not internalize it; on launch day they see press coverage and ask the team questions that should have been answered in the brief. Fix: brief executives in person, not just via document. + +--- + +## When the brief reveals misalignment + +The brief is the artifact that surfaces misalignment. Common signals. + +- The positioning canvas does not match how sales describes the customer profile. Misalignment between PM and sales on who the customer is. +- The launch calendar does not give sales enough time. Misalignment on what enablement requires. +- The FAQ has questions nobody can answer. Misalignment on what the feature actually does. + +The pattern. Surface misalignment before launch; resolve before launch. The brief is the tool that forces the conversation. A team that drafts the brief carefully and finds it easy to write probably has no misalignment. A team that struggles to write the brief has misalignment that the brief is now revealing; resolve it before customer comms go out. diff --git a/skills/feature-launch-playbook/references/launch-tier-decision.md b/skills/feature-launch-playbook/references/launch-tier-decision.md new file mode 100644 index 0000000..dab6ffc --- /dev/null +++ b/skills/feature-launch-playbook/references/launch-tier-decision.md @@ -0,0 +1,137 @@ +# Launch tier decision + +Tier 1 / Tier 2 / Tier 3 decision framework. Worked examples. Anti-patterns on both sides. + +The principle. Match launch effort to feature scope. Treating every release as Tier 1 produces comms fatigue; treating every release as Tier 3 produces unlaunched features. + +--- + +## The tiers + +### Tier 1: full launch + +Scope. Net-new product, major feature reshaping the product narrative, pricing change, breaking change. + +Effort. Full playbook. Positioning, all comms channels, sales enablement (B2B), customer success briefing, dedicated post-launch measurement, executive announcement. Two to four weeks of pre-launch work; four to eight weeks of post-launch monitoring. + +Examples. + +- A new product surface (Slack adds Canvas; Figma adds FigJam; Notion adds Sites). +- A pricing model change (per-seat to consumption; introducing a new tier). +- A foundational replatforming with user-visible impact (a new UI architecture, a new permissions model). +- A flagship competitive feature (the thing the sales team has been asking for, the thing the analyst report compared you on). + +### Tier 2: focused launch + +Scope. Meaningful improvement that materially affects user value or competitive positioning. + +Effort. Subset of the playbook. In-app comms, blog post or detailed release note, support readiness, rollout strategy, post-launch measurement. One to two weeks of pre-launch work; two to four weeks of post-launch monitoring. + +Examples. + +- A new export format that customers have been requesting. +- A redesigned core flow (e.g., a new onboarding experience). +- An integration with a major third-party (Slack notifications, Salesforce sync). +- A meaningful performance improvement (page loads twice as fast on a flagship surface). + +### Tier 3: release note + +Scope. Incremental improvement, bug fix made positive, polish. + +Effort. Minimal. Changelog entry, release note, light monitoring. Hours of pre-launch work; passive monitoring post-launch. + +Examples. + +- A new keyboard shortcut. +- A small UI polish (better empty states, refined typography). +- A minor configuration option (toggle to disable a non-default behavior). +- A bug fix that improves reliability for a small cohort. + +--- + +## Decision framework + +When unsure between two tiers, ask three questions. + +1. Will sales need to talk about this? If yes, at least Tier 2. If sales is selling against this gap today, Tier 1. +2. Will customers be confused if we do not tell them? If yes, at least Tier 2. +3. Will the metric this is meant to move show up in board reporting? If yes, Tier 1. If yes but only at the team level, Tier 2. + +If all three answers are no, the feature is Tier 3. + +--- + +## Worked examples + +### Example 1: a new export-to-PDF capability + +A B2B SaaS product adds export-to-PDF to its reporting feature. + +- Will sales talk about this? Yes; this has been a top sales objection. +- Will customers be confused without comms? No; the feature is discoverable in the existing UI. +- Will the metric move at board level? Probably not directly; might unblock some deals. + +Tier 2. Sales enablement (battlecard plus a one-paragraph deal-coaching note). Blog post. Release note. In-app banner on the reporting page. Light monitoring. + +### Example 2: a new pricing tier with consumption-based billing + +A SaaS company adds a usage-based tier alongside its existing per-seat plans. + +- Will sales talk about this? Yes; pricing changes always involve sales. +- Will customers be confused without comms? Yes; existing customers will wonder if they should switch. +- Will the metric move at board level? Yes; revenue mix and ARR composition are board-level. + +Tier 1. Full positioning canvas. Internal launch brief 4 weeks ahead. Sales enablement including pricing change documentation. Email to existing customers explaining what is and is not changing for them. Blog post. Webinar for top accounts. Phased rollout starting with new customers, then existing customer opt-in. + +### Example 3: a keyboard shortcut for a power-user action + +A consumer app adds Cmd+K for quick navigation. + +- Will sales talk about this? No; consumer product, no sales motion. +- Will customers be confused without comms? No; the feature is purely additive and discoverable. +- Will the metric move at board level? No; small UX improvement. + +Tier 3. Changelog entry. Maybe a tweet from the product team. No further work. + +### Example 4: an enterprise SSO integration + +A B2B SaaS adds SAML SSO support. + +- Will sales talk about this? Yes; SSO is a hard requirement for many enterprise deals. +- Will customers be confused without comms? Existing self-service customers no; enterprise prospects yes. +- Will the metric move at board level? Indirectly; SSO unblocks enterprise deals worth real ARR. + +Tier 1 if SSO unlocks the enterprise segment for the first time, otherwise Tier 2. Sales enablement is the highest-impact piece (the deal-coaching note for previously SSO-blocked accounts). Customer success outreach to top enterprise prospects. Blog post focused on the security and IT audience. Quiet rollout for self-service customers (changelog only). + +--- + +## Anti-pattern: everything is Tier 1 + +Symptom. Every release gets a blog post, an email, a sales briefing. Customers tune out the announcement firehose. Real Tier 1 launches lose signal in the noise. Sales reps stop reading the briefings because they assume every one is minor. + +Fix. Be honest about which features are major. If you ship five "major" launches per quarter, three of them are Tier 2 or Tier 3 in disguise. The Tier 1 budget should be one to three per quarter for most companies. + +--- + +## Anti-pattern: everything is Tier 3 + +Symptom. Features ship without comms. Sales does not know what is new. Customers are surprised when they discover a feature six months after launch. Metrics do not move because users do not know the feature exists. + +Fix. Tier honestly. Most B2B SaaS releases are Tier 2; defaulting them to Tier 3 leaves value on the table. The minimum Tier 2 effort (release note plus in-app banner plus support FAQ) is small; the marginal value capture is large. + +--- + +## How tier affects the rest of the playbook + +\| Section \| Tier 1 \| Tier 2 \| Tier 3 \| +\|---\|---\|---\|---\| +\| Positioning canvas \| Required \| Required \| Skip \| +\| Internal launch brief \| 2 to 4 weeks ahead \| 1 week ahead \| Skip \| +\| Customer comms \| All channels \| In-app + blog + release note \| Release note \| +\| Sales enablement (B2B) \| Full battlecard + demo + training \| One-page note + Q&A \| Skip \| +\| Support readiness \| Full training \| Brief + FAQ \| FAQ if applicable \| +\| Rollout strategy \| Phased or gradual \| Gradual \| Either \| +\| Monitoring \| Full + rollback triggers \| Standard + alerts \| Passive \| +\| Post-launch measurement \| 4 to 8 weeks \| 2 to 4 weeks \| Light \| + +The pattern. Tier 1 is the full playbook. Tier 2 is the playbook compressed. Tier 3 is the changelog plus passive monitoring. Each section's depth scales with tier. diff --git a/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md b/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md new file mode 100644 index 0000000..6770c30 --- /dev/null +++ b/skills/feature-launch-playbook/references/monitoring-readiness-checklist.md @@ -0,0 +1,185 @@ +# Monitoring readiness checklist + +Metrics dimensions, alert thresholds, pre-defined rollback triggers. The "no rollback trigger" failure mode. + +The principle. Monitoring catches launch issues before they compound into customer pain. The discipline is defining what to watch and what to do BEFORE launch, so the team executes rather than debates during the launch window. + +--- + +## What to monitor + +Six dimensions for most launches. + +### 1. Error rates + +- Overall error rate. The baseline. Has the deploy increased errors across the application. +- Feature-specific error rate. Errors in code paths the new feature touches. Often the first signal of a feature-specific bug. +- Per-cohort error rate. Errors broken down by user segment, plan, region. Catches cohort-specific bugs. + +### 2. Latency + +- Overall P50, P95, P99. Has the deploy slowed the application. +- Feature-specific latency. New code paths often have unoptimized queries; latency tracking catches them. +- Database query latency. New features often add new queries; database load can spike. + +### 3. Feature usage rate + +- Reach. Of users in the rollout cohort, how many actually trigger the feature within their first session post-rollout. +- Frequency. Of users who used the feature once, how many used it again. +- The expected vs actual gap. Pre-launch projections vs actual numbers. Large gaps in either direction need investigation. + +### 4. Funnel completion + +- End-to-end completion of the workflow the feature is part of. Did users complete the flow at the same rate as pre-launch. +- Step-by-step drop-off. Where in the flow are users abandoning. Compare pre-launch to post-launch step-by-step. +- Per-cohort completion. Cohort-specific drop-off can hide in aggregate metrics. + +### 5. Support ticket volume + +- Overall ticket volume. Has the team's support load increased. +- Feature-tagged tickets. Tickets where the customer mentions the feature. +- Ticket sentiment. Frustrated tickets vs informational tickets vs positive tickets. + +### 6. Customer satisfaction signals + +- NPS comments. Mentions of the feature in NPS responses. +- Feedback widget. In-product feedback explicitly about the feature. +- Social mentions. Twitter or LinkedIn posts about the launch. + +--- + +## Alert thresholds + +For each dimension, pre-defined thresholds that fire alerts. + +### Error rates + +- Yellow. Overall error rate up by more than 25 percent vs pre-launch baseline. Investigate without escalation. +- Orange. Overall error rate up by more than 50 percent vs baseline. Escalate to PM and engineering on-call. +- Red. Overall error rate above 1 percent absolute. Trigger rollback. + +### Latency + +- Yellow. P95 up by 25 percent vs baseline. Investigate. +- Orange. P95 up by 50 percent. Escalate. +- Red. P95 doubled or worse. Trigger rollback if sustained for 10 minutes. + +### Feature usage rate + +- Yellow. Below 50 percent of pre-launch projection. Investigate (probably comms or discovery problem). +- Orange. Below 25 percent of projection. Escalate; the launch may not be reaching users. +- Red. Near zero usage. Likely an instrumentation bug; the feature is not firing or the metric is not capturing. + +### Funnel completion + +- Yellow. Down by 10 percent from pre-launch baseline. Investigate. +- Orange. Down by 25 percent. Escalate; the feature may be breaking the flow. +- Red. Down by 50 percent for any cohort. Trigger rollback for that cohort or pause the rollout. + +### Support volume + +- Yellow. Feature-tagged tickets exceed 10 in the first hour. Investigate. +- Orange. Feature-tagged tickets exceed 50 in the first hour. Escalate. +- Red. Feature-tagged tickets exceed 100 in the first hour. Trigger rollback or pause; the feature has a real problem. + +The numbers above are illustrative. Calibrate to the team's actual support volume and the feature's expected reach. + +--- + +## Pre-defined rollback triggers + +A rollback trigger is a rule that fires automatically. The team executes the rollback without re-litigating whether to. + +### Examples + +For a feature touching the checkout flow. + +- Error rate above 1 percent sustained for 5 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline. +- Stripe API errors increase by 100 percent. + +For a new internal tool. + +- Error rate above 5 percent sustained for 5 minutes (higher tolerance because internal users provide more context). +- Adoption near zero after 24 hours (instrumentation bug or feature not deployed). + +For a pricing change. + +- Subscription cancellation rate increase by 50 percent in the first 48 hours. +- Customer service contact rate about pricing increase by 200 percent. +- Revenue forecast adjustment indicates a 10 percent quarterly miss. + +The pattern. Each rollback trigger names a specific metric, a specific threshold, and a specific time window. The team rehearses what to do when the trigger fires. + +### What rollback means + +Rollback can be one of several things. + +- Full rollback. Flag off, code reverted, user-visible state returns to pre-launch. +- Pause at current rollout percentage. Flag stays on for users who already have it; no new users get the feature. +- Cohort-specific rollback. Flag off for the cohort showing issues; flag on for cohorts that look healthy. +- Fix-forward. A small fix is deployed; rollout continues at the previous percentage. Risky; only use when the fix is high-confidence. + +The team should know which rollback path applies to which trigger before launch. + +--- + +## The on-call rotation + +For Tier 1 launches, the on-call rotation should include. + +- Primary engineering on-call. Standard rotation. Receives alerts, executes rollbacks. +- Secondary engineering on-call. Backup if primary is unreachable. +- PM contact. The PM who owns the launch is reachable during the launch window. +- Support escalation contact. The support lead responsible for routing customer issues to the right team. +- Marketing contact. For comms decisions if the rollout pauses. + +Reachability hours for Tier 1 launches: 24/7 for the first 48 hours, business hours plus on-call after that. + +--- + +## The "no rollback trigger" failure + +The pattern. + +- Launch goes sideways. Error rate is up; support volume is high; engineering is investigating. +- The team debates whether to roll back. The debate takes an hour. +- During the debate hour, more users encounter the issue. Support tickets pile up. The press notices. Trust erodes. +- The team eventually rolls back, but the recovery is now harder than it would have been one hour earlier. + +The fix. Pre-define the rollback triggers. Write them down. Get team agreement before launch. When a trigger fires, execute the rollback. Debate the appropriateness of the trigger after the rollback, not during the incident. + +The discipline. The cost of a wrong rollback (the team rolls back when the feature was actually fine) is small (a paused launch and a re-rollout). The cost of a delayed rollback (the team debates while the issue compounds) is large (customer impact, reputation, recovery cost). Bias toward fast rollback. + +--- + +## Post-rollback retrospective + +After any rollback, hold a retrospective within 48 hours. + +Agenda. + +1. What was the trigger that fired. +2. What was the actual problem. +3. Was the rollback the right call (almost always yes; even false positives that catch nothing teach the team about the system). +4. What is the path to re-launch (fix the bug, test it, validate the test, schedule a new rollout). +5. What did we learn that updates the next launch's monitoring. + +The retrospective is not a blame session. It is an investment in the next launch's monitoring quality. + +--- + +## Health check before each rollout step + +For gradual percentage rollouts, define a health check that gates each step. + +The health check passes when. + +- All Yellow thresholds clear for the prior percentage step's full duration. +- No Orange or Red alerts in the prior step. +- Support volume stable. +- Customer feedback (NPS, social) neutral or positive. + +The health check fails when any of the above conditions does not hold. The rollout pauses at the current step until the health check passes. + +The pattern. The rollout proceeds when the system is healthy; it does not proceed on a schedule. Schedule-driven rollouts that ignore health checks are how launches go sideways. diff --git a/skills/feature-launch-playbook/references/positioning-canvas.md b/skills/feature-launch-playbook/references/positioning-canvas.md new file mode 100644 index 0000000..4ab4b54 --- /dev/null +++ b/skills/feature-launch-playbook/references/positioning-canvas.md @@ -0,0 +1,132 @@ +# Positioning canvas + +The one-page positioning template. Worked examples for B2B SaaS, B2C, and developer features. The vague-target-user failure mode. + +The principle. Positioning is the foundation of the launch. Without it, comms drift, sales improvise, and customers come away with a different understanding of the feature than the team intended. Filled out before any comms drafting; reviewed by sales, support, and an executive sponsor before launch. + +--- + +## The canvas + +One page. Six sections. Filled out by the PM with input from sales, customer success, and design. + +### 1. Target user + +Segment. What kind of company or individual. + +Role. What is their job title or function. + +Jobs-to-be-done. What is the user trying to accomplish in their work or life that this feature serves. + +Specificity test. Could a sales rep describe the customer profile in one sentence? Could marketing target ads at this segment? If no to either, the target user is too vague. + +### 2. Problem it solves + +The current pain. In the user's words. What is hard, slow, error-prone, or impossible today. + +The cost of the pain. Time, money, errors, missed opportunities. Quantified where possible. + +Specificity test. Is the problem stated in concrete terms or in abstract language? "Productivity is low" is abstract. "The customer support manager spends 3 hours per day triaging tickets that an automated system could route" is concrete. + +### 3. Current alternative + +What users do today without this. The status quo, the workaround, the competing product, the manual process, the spreadsheet. + +The status quo is the real competition. A feature that is better than nothing but worse than the user's existing workaround does not get adopted. + +### 4. User-visible promise + +One sentence. The promise the user will hear when they encounter the feature. + +Specificity test. Can sales repeat it without changing words? Can support repeat it without paraphrasing? If no, it is too long or too abstract. + +### 5. Proof points + +Three to five specific capabilities or outcomes. Concrete, not adjectives. + +Examples of bad proof points: "fast," "easy," "secure," "intelligent." These are claims, not proof. + +Examples of good proof points: "exports a 200-page report in under 5 seconds," "supports 14 languages including right-to-left," "SOC 2 Type II audited by Deloitte 2025." + +### 6. Anti-positioning + +What this is NOT. What it does not try to do. + +Anti-positioning prevents over-promising. If the feature does not handle enterprise scale, say so. If it does not work offline, say so. If it does not replace the customer's existing tool, say so. + +The anti-positioning protects the team from sales reps who hear about the feature and embellish. It protects support from customers who expected something the feature does not do. + +--- + +## Worked example 1: B2B SaaS feature + +A B2B project management tool ships a new automated routing feature. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Customer support managers at SaaS companies with 10 to 100 support reps. JTBD: triage incoming tickets and route them to the right team without reading every ticket. \| +\| Problem it solves \| Current manual triage takes 2 to 3 hours of a support manager's day. Tickets sit in the queue waiting for routing while customers grow impatient. The cost is 10+ hours per week of manager time plus 30 to 60 minute response delays on simple tickets. \| +\| Current alternative \| Manual triage by a senior support rep, or basic keyword routing rules in their existing helpdesk that produce 30 to 40% misroutes. \| +\| User-visible promise \| "Route incoming tickets to the right team in under 30 seconds with 95% accuracy." \| +\| Proof points \| (1) ML model trained on 90 days of historical ticket routing decisions. (2) Accuracy benchmarks: 95% routing accuracy at launch, retraining weekly. (3) Override and feedback flow lets support managers correct routes; corrections feed back into the model. (4) Audit log of every routing decision for compliance. (5) Configurable confidence threshold; below the threshold, the ticket falls back to manual routing. \| +\| Anti-positioning \| This is not a full ticket-resolution AI. It does not draft replies, identify duplicate tickets, or detect sentiment. It only routes. \| + +The anti-positioning protects the team from sales reps who would otherwise pitch this as "AI customer support." + +--- + +## Worked example 2: B2C feature + +A consumer note-taking app ships AI-generated summaries. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Students and knowledge workers who maintain long-form notes. Specifically users with 50+ notes longer than 500 words. JTBD: quickly recall the key points of a note without re-reading it. \| +\| Problem it solves \| Long notes get written then forgotten. The user cannot recall what is in them without scrolling and re-reading. Cost: hours per week of search-and-rediscover, plus the worse cost of acting on stale information. \| +\| Current alternative \| Manual TLDRs the user writes themselves (rare). Highlighted text within the note (common but unreliable). Re-reading the full note (default; expensive). \| +\| User-visible promise \| "See a summary of any note in two seconds." \| +\| Proof points \| (1) Summaries appear at the top of every note over 500 words. (2) Summary regenerates when the note is meaningfully edited. (3) Click any summary point to jump to its source paragraph in the note. (4) Generates in under 2 seconds for notes up to 5,000 words. \| +\| Anti-positioning \| This is not a research assistant; it does not pull in outside context or related notes. It summarizes the note in front of you, nothing more. \| + +--- + +## Worked example 3: developer feature + +A developer tools company ships a new CLI command. + +\| Section \| Content \| +\|---\|---\| +\| Target user \| Backend engineers using the platform's CLI for deploys. Specifically engineers who run more than 5 deploys per week. JTBD: deploy faster and roll back when something breaks. \| +\| Problem it solves \| Rollbacks today require digging through deploy history, finding the prior version, and running a deploy command with the version pinned. Takes 2 to 5 minutes; under incident pressure, the time matters. \| +\| Current alternative \| Manual deploy command with version pin. Some teams script this; most do it from memory under pressure. \| +\| User-visible promise \| "Roll back to the last known good deploy with one command." \| +\| Proof points \| (1) Single command: `acme deploy rollback`. (2) Defaults to the most recent successful deploy that is older than the current. (3) Confirmation prompt shows what will be rolled back; passes through to the existing deploy flow. (4) Logged as a rollback in deploy history (not as a fresh deploy) for clean audit trail. \| +\| Anti-positioning \| This does not auto-detect bad deploys. The engineer still decides when to roll back. \| + +--- + +## The vague-target-user failure mode + +The most common positioning failure. The PM writes "It is for PMs" or "It is for engineers" or "It is for marketers." + +Why it fails. Different PMs, engineers, and marketers have different jobs. A B2B PM at a 50-person startup has a different job from a B2C PM at a 5,000-person company. A backend engineer has a different job from a frontend engineer. The vague target prevents sales from filtering, prevents marketing from targeting ads, prevents support from anticipating questions. + +The fix. Specificity layers. + +- Industry or company type. (B2B SaaS at 50 to 500 customers.) +- Role and function. (Customer support manager, not just "support.") +- Jobs-to-be-done. (Triage incoming tickets, not "improve productivity.") + +Three layers of specificity move the target from useless to actionable. If you cannot fill in all three, the team has not yet decided who the feature is for. + +--- + +## Reviewing the canvas + +Before launch, review the positioning canvas with three audiences. + +1. Sales review. Can sales pitch this in 30 seconds? Does the language match how customers ask about the problem? +2. Support review. Can support answer the obvious questions (what does it cost, how do I turn it on, what are the limits) using only the canvas? +3. Executive review. Does the positioning fit the company narrative? Will it confuse customers who are mid-purchase on a different feature? + +If any of the three review groups push back, fix the canvas before launch comms drafting begins. Drafting comms on top of weak positioning produces comms that look fine in isolation but contradict each other across channels. diff --git a/skills/feature-launch-playbook/references/post-launch-measurement-framework.md b/skills/feature-launch-playbook/references/post-launch-measurement-framework.md new file mode 100644 index 0000000..3475f47 --- /dev/null +++ b/skills/feature-launch-playbook/references/post-launch-measurement-framework.md @@ -0,0 +1,181 @@ +# Post-launch measurement framework + +Adoption, engagement, outcome, side effects. Time horizons. Tying back to spec hypotheses. The "declared victory on launch spike" failure mode. + +The principle. The launch measurement plan answers "did this work." Without it, the team moves on without knowing. + +--- + +## Four measurement dimensions + +### 1. Adoption (the reach question) + +Did the right users actually use the feature. + +Metrics. + +- Reach: of users in the rollout cohort, what fraction has tried the feature. +- Time to first use: of users who tried the feature, how long after rollout. +- Distribution by cohort: are the right segments (per the positioning canvas) the ones using the feature. + +Signal interpretation. + +- High reach plus right cohorts: the launch reached the target audience. +- High reach plus wrong cohorts: the launch reached the wrong audience; positioning or comms missed the target. +- Low reach: comms problem or discovery problem. Investigate which channel users would have learned about the feature from. + +### 2. Engagement (the stickiness question) + +Did users who tried the feature come back. + +Metrics. + +- Retention: of users who tried the feature once, what fraction used it again within 7, 14, 30 days. +- Frequency: how many times per week did adopters use the feature. +- Depth: did adopters use the full feature or only the first step. + +Signal interpretation. + +- High first-time use plus high retention: the feature is delivering value. +- High first-time use plus low retention: the feature failed to deliver on the first-use experience. Usability or value-prop problem. +- Low first-time use plus high retention among the few who tried: the feature is valuable to a niche; reach the niche better, or accept that it serves a smaller audience. + +### 3. Outcome (the effect question) + +Did the metric the spec said this would move actually move. + +Metrics. + +- The primary metric from the spec. Usually a business metric (revenue, retention, support deflection, conversion rate). +- The lift relative to a pre-launch baseline. +- The statistical significance of the lift, if a controlled comparison is available. + +Signal interpretation. + +- Metric moved as predicted: the feature delivered the value the team committed to. +- Metric moved less than predicted: partial success; the feature works but did not have the size of impact the team expected. Investigate why (smaller cohort than expected, smaller per-user impact, or simply optimistic projection). +- Metric did not move: the launch did not deliver the promised value. Investigate before declaring failure (could be measurement timeline, isolation issues, or the feature genuinely failing). + +### 4. Side effects (the safety question) + +Did any other metric move that was not supposed to. + +Metrics. + +- Cohorts adjacent to the target: did the feature affect users it was not designed for. +- Adjacent metrics: did related metrics move (positively or negatively). +- Support volume on adjacent topics: did the feature confuse customers about other parts of the product. + +Signal interpretation. + +- No side effects: clean launch. +- Positive side effects: the feature delivered value beyond the target. Document for the next iteration. +- Negative side effects: the feature broke something else. Triage urgently; this is a launch quality issue regardless of whether the primary metric moved. + +--- + +## Time horizons + +Different signals stabilize at different times. + +\| Signal type \| Stable at \| +\|---\|---\| +\| Adoption (reach) \| 1 to 2 weeks post-launch \| +\| Engagement (retention) \| 4 weeks for week-2 retention; 8 weeks for week-4 retention \| +\| Outcome \| 4 to 8 weeks for most business metrics; longer for retention or LTV \| +\| Side effects \| 2 to 4 weeks \| + +The rule. Do not declare success or failure on the outcome metric before week 4. The launch-week spike is unrepresentative; the metric needs time to stabilize at its post-launch level. + +--- + +## Tying back to spec hypotheses + +The spec (per `pm-spec-writing`) should have stated explicit hypotheses. The launch measurement plan validates each. + +Example hypotheses from a hypothetical spec. + +- "We expect this feature to be used by 40 percent of paid users within 30 days of rollout." (Adoption hypothesis.) +- "Of users who try the feature, we expect 60 percent to use it again within 7 days." (Engagement hypothesis.) +- "We expect this feature to reduce support tickets in the X category by 25 percent." (Outcome hypothesis.) +- "We do not expect this feature to affect billing-related support volume." (Side-effect hypothesis.) + +The measurement plan validates each. + +\| Hypothesis \| Measurement \| Decision rule \| +\|---\|---\|---\| +\| 40% paid user adoption in 30 days \| Cohort: paid users in rollout. Metric: distinct user count using the feature divided by cohort size. \| Above 30% acceptable; below 20% requires intervention. \| +\| 60% week-1 retention \| Cohort: users who tried the feature in week 1. Metric: fraction of cohort using the feature again in week 2. \| Above 50% acceptable; below 40% indicates value or usability problem. \| +\| 25% reduction in X-category support tickets \| Pre-launch baseline 30 days; post-launch 30 days. Compare ticket volumes. \| Above 15% reduction acceptable; below 10% indicates the feature is not solving the right problem. \| +\| No effect on billing support \| Billing ticket volume pre vs post. \| Volume change above 20% requires investigation. \| + +The measurement plan is written before launch. The decision rules are pre-committed; the team does not move the goalposts after seeing the data. + +--- + +## The "declared victory on launch spike" failure + +The pattern. + +- Week 1: adoption is high. The team announced the feature; users tried it; the metric is up. +- Week 2: adoption flat. The launch announcement spike has passed; the new users have tried the feature. +- Week 3: adoption declining. Users who tried the feature once are not coming back. +- Week 4: adoption near pre-launch baseline. The metric has reverted. +- The team had already declared the launch a success in week 1 and moved on. + +The cost. The team's roadmap is now built on a launch that did not actually work. The next quarter's plan assumes the metric is at the elevated level; when it does not stay there, the plan does not deliver. + +The fix. Declare success or failure based on the stable post-launch trend, not the launch-week spike. The minimum measurement window is four weeks; for retention or LTV signals, eight to twelve weeks. + +The discipline. The four-week checkpoint is on the calendar before launch. The team holds itself accountable to revisit; the executive sponsor holds the team accountable to revisit. Launches that are reported as successful in week 1 and never revisited are silent failures. + +--- + +## The "no measurement plan" failure + +The pattern. + +- Feature ships. +- Team moves on to the next feature. +- Six months later, someone asks "did feature X work?" Nobody knows. +- The feature becomes maintenance debt; the team cannot decide whether to invest in iteration. + +The cost. The team accumulates features whose value is unknown. Roadmap decisions get harder because the historical track record is opaque. Engineering investment is wasted on features that did not work; the team does not learn from them because they did not measure. + +The fix. Every launch has a measurement plan. The plan is short (one page); it names the four dimensions, the metrics, the time horizons, and the decision rules. The plan is reviewed at week 4 and again at week 8 or 12 depending on the signal. + +The discipline. The measurement plan is part of the launch brief. A launch without a measurement plan does not get scheduled. + +--- + +## When the metric did not move + +If the outcome metric did not move at week 4, the next investigation. + +1. Is adoption strong? If adoption is below target, the launch may be a comms or discovery problem, not a feature problem. +2. Is engagement strong? If engagement is below target among adopters, the value is not landing for the right reasons. +3. Is the metric correctly attributed? Did another concurrent change interfere with the measurement. +4. Did the side-effects analysis catch a counterweight? A negative side effect could be cancelling the positive primary effect. + +Each diagnosis maps to a different fix. + +- Adoption problem: more comms, repeat comms, deeper sales reactivation, in-app discovery surface. +- Engagement problem: usability or value-prop iteration. The feature may need redesign. +- Attribution problem: re-run measurement after the concurrent change has been accounted for. +- Side-effect counterweight: fix the side effect, then re-measure the primary. + +--- + +## When the launch worked but quietly + +Sometimes the launch works at every level (adoption strong, engagement strong, outcome metric moved) but the team does not feel like it succeeded. Usually the gap is internal awareness. + +Signs. + +- Sales is not using the feature in pitches. +- Customer success is not mentioning it in customer calls. +- The product narrative has not updated to include the feature. + +The fix. Internal launch effectiveness is part of the launch playbook. Even successful feature launches need ongoing internal advocacy. + +The discipline. After the four-week checkpoint, briefly re-engage internal stakeholders. Share the metrics. Highlight customer use cases. The internal awareness is not a one-time event at launch; it is sustained for a quarter or more. diff --git a/skills/feature-launch-playbook/references/rollout-strategy-patterns.md b/skills/feature-launch-playbook/references/rollout-strategy-patterns.md new file mode 100644 index 0000000..a7e0c83 --- /dev/null +++ b/skills/feature-launch-playbook/references/rollout-strategy-patterns.md @@ -0,0 +1,185 @@ +# Rollout strategy patterns + +Four rollout patterns matched to feature types. Decision framework: blast radius times confidence times external commitments. + +The principle. The rollout is the mechanism by which users actually encounter the feature. The pattern depends on what would happen if the feature breaks, how confident the team is in correctness, and whether external comms are tied to a specific date. + +--- + +## Pattern 1: all-at-once (big bang) + +Mechanism. Zero to 100 percent of eligible users in a single deploy. No gradual rollout. + +Right for. + +- Marketing-coordinated launches where the announcement IS the rollout. The press is briefed for a specific date; the feature has to be live for everyone at that moment. +- Low-blast-radius features. The feature affects a small portion of the user experience; even if it breaks, the customer impact is limited. +- High-confidence releases. The feature has been tested thoroughly, used internally, validated with a beta cohort. + +Risky for. + +- High-traffic critical paths (checkout, login, primary navigation). Any bug affects a meaningful share of users immediately. +- Features without a clean rollback path. If the deploy breaks, recovery is hard. +- Features with cohort-specific risk (works for free users, breaks for enterprise). The cohort variance is not exposed before launch. + +Operational shape. One deploy. Health check after deploy. Rollback path ready but rarely used. Monitoring tightens for 24 hours post-deploy. + +--- + +## Pattern 2: gradual percentage rollout + +Mechanism. 1 percent, then 10 percent, then 25 percent, then 50 percent, then 100 percent over hours or days. Health checks at each step. + +Right for. + +- Most feature launches. The default unless there is a reason to deviate. +- Features touching critical paths. The 1 percent rollout catches errors before they affect a meaningful share of users. +- Features with uncertain interaction effects. Other systems may behave differently when the feature is on; gradual rollout surfaces interactions safely. + +Risky for. + +- Marketing-coordinated launches with a fixed announcement date. The press writes about a feature that 90 percent of users do not have yet. + +Operational shape. + +- 1 percent to 10 percent: 4 to 24 hours. Watch error rates, latency, feature usage rate. +- 10 percent to 25 percent: 24 to 48 hours. Watch the same metrics plus support volume. +- 25 percent to 50 percent: 48 to 72 hours. Watch all metrics plus customer feedback. +- 50 percent to 100 percent: 24 to 72 hours. + +The pace is configurable. Faster for low-risk features; slower for high-risk. + +The rollback at any step. If a metric breaches a threshold, the rollout pauses. If the issue is severe, rollback to 0 percent. If the issue is minor, fix forward at the current percentage. + +--- + +## Pattern 3: flag-gated cohort rollout + +Mechanism. Targeted to specific user segments. Free tier first, then paid. Small accounts first, then enterprise. Specific named accounts first, then broad rollout. + +Right for. + +- Features with cohort-specific risk profiles. A pricing change affects existing customers differently from new customers; roll out to new customers first. +- Features that need cohort-specific configuration. Enterprise customers may need a setup step; roll out to them after they are configured. +- Features where the cost of a bad rollout varies by cohort. Bug in front of a Fortune 500 prospect costs more than a bug in front of a free-tier user. + +Operational shape. + +- The flag service controls which cohorts have the feature enabled. +- Cohorts are defined explicitly: account tier, account ID list, region, signup date range. +- Each cohort gets its own monitoring slice. Issues affecting one cohort do not pause the rollout to other cohorts. + +Risky for. + +- Features that interact across cohorts. If enterprise customers can see what free-tier customers create, a partial cohort rollout exposes a feature inconsistency that breaks workflows. + +--- + +## Pattern 4: phased launch (multi-week) + +Mechanism. Launch to a subset of users, regions, or customers; gather feedback; iterate; expand. Multi-week timeline. + +Right for. + +- Tier 1 launches with high uncertainty about user reception. Pricing changes often launch this way. +- Major UX redesigns. The team needs to learn what users do with the new design before broader rollout. +- Features that depend on user behavior change. The team needs to see whether users adopt before declaring readiness. + +Operational shape. + +- Phase 1: limited rollout (5 to 10 percent of eligible users). 1 to 2 weeks. Heavy feedback collection. +- Phase 2: iteration based on phase 1 feedback. Could be days; could be weeks. +- Phase 3: expanded rollout (25 to 50 percent). 1 to 2 weeks. +- Phase 4: general availability. + +The total timeline is 4 to 8 weeks for a typical phased launch. Longer for major UX changes; shorter for feature additions. + +Risky for. + +- Features that need to be all-on for users to encounter them naturally. A change to the homepage hero needs to be either visible or not; phased rollout creates inconsistent experiences across users. + +--- + +## The decision framework + +Three factors. Pick the rollout that matches. + +### Factor 1: blast radius + +What happens if the feature breaks for a meaningful share of users? + +- Low. Optional new tool that users opt into. Bug affects only users who tried the new tool. +- Medium. New surface in an existing flow. Bug affects users mid-flow but not users on other paths. +- High. Critical path change. Bug affects most active users immediately. + +### Factor 2: confidence in correctness + +How confident is the team that the feature works. + +- Low. First time the team has built this kind of feature. Edge cases unknown. +- Medium. The team has built similar features before. Most edge cases anticipated. +- High. Iterative refinement of an existing feature. Behavior well-understood. + +### Factor 3: external commitments + +Is the launch date tied to external press, partner coordination, or a public commitment. + +- None. Internal team knows the rough timeline; no external coordination. +- Soft. Marketing has scheduled comms but the date can shift by a few days. +- Hard. Press is briefed for a specific day. Partner is coordinating launches. The date is fixed. + +### The decision matrix + +\| Blast radius \| Confidence \| External commitment \| Recommended pattern \| +\|---\|---\|---\|---\| +\| Low \| High \| Hard \| All-at-once \| +\| Low \| High \| Soft or none \| All-at-once or gradual \| +\| Low \| Medium \| Any \| Gradual \| +\| Low \| Low \| Any \| Gradual or phased \| +\| Medium \| High \| Hard \| Gradual fast \| +\| Medium \| High \| Soft or none \| Gradual \| +\| Medium \| Medium \| Any \| Gradual \| +\| Medium \| Low \| Any \| Phased \| +\| High \| High \| Any \| Gradual slow \| +\| High \| Medium \| Any \| Gradual or flag-gated \| +\| High \| Low \| Any \| Phased \| + +The defaults. Most launches use gradual percentage rollout. The other patterns are for specific situations. + +--- + +## Cohort-specific rollout sequencing + +When using flag-gated cohort rollout, the sequence matters. + +Internal users first. Eat your own dog food. Catch the obvious issues before any external user sees them. + +Free or trial users next. Lower-stakes; if the feature has issues, the cost of a bad experience is lower than for paying customers. + +Self-service paid users. Customers who use the product without a sales rep. They will encounter the feature naturally; their feedback is high-quality. + +Top accounts last (with sales-led briefing first). Top accounts hear about the feature from their account executive before encountering it. By the time they have access, the feature is stable. + +Reverse the sequence in specific cases. + +- A feature designed specifically for enterprise customers should roll out to those customers first; the feedback is the design feedback. +- A feature gated by configuration that only enterprise customers complete should roll out to them first; otherwise the feature is invisible to the cohort that can use it. + +--- + +## What "rollback trigger" means + +A pre-defined rule that determines when the team rolls back without further debate. + +Examples. + +- Error rate above 1 percent sustained for 5 minutes. +- Latency above the pre-launch P95 by 50 percent for 10 minutes. +- Funnel completion drops below 50 percent of pre-launch baseline for any cohort. +- Support tickets mentioning the feature exceed 50 in the first hour. + +The trigger fires automatically; the team executes the rollback without re-litigating whether to do it. + +The "no rollback trigger" failure. Launch goes sideways. The team debates whether to roll back for an hour while the issue compounds. Pre-defined triggers remove the debate. + +The discipline. Define the trigger before launch. Write it down. Rehearse the rollback. Make the trigger automatic where possible (alerting plus on-call paging); make the rollback execution one command, not a multi-step process. diff --git a/skills/feature-launch-playbook/references/sales-enablement-template.md b/skills/feature-launch-playbook/references/sales-enablement-template.md new file mode 100644 index 0000000..07b7cca --- /dev/null +++ b/skills/feature-launch-playbook/references/sales-enablement-template.md @@ -0,0 +1,173 @@ +# Sales enablement template + +Battlecard, demo script, deal coaching, training session structure. For B2B; skip for B2C and PLG. + +The principle. Sales reps cannot pitch a feature they were briefed on yesterday. Enablement is the structured way to give sales the language and the mechanics they need to talk about the feature accurately and quickly. + +--- + +## When to skip this section + +For B2C products and PLG products without a sales motion, this section does not apply. The user is the buyer; there is no rep in the middle. Skip ahead to the support readiness checklist. + +For B2B products, this section is non-negotiable for Tier 1 launches and most Tier 2 launches. + +--- + +## The battlecard + +One page. Sales can read it in two minutes and pitch the feature in five. + +### Section 1: positioning summary + +Two to three sentences. The user-visible promise plus the target customer profile plus the differentiator vs the status quo. Pulled directly from the positioning canvas. + +### Section 2: target customer profile + +The specifics sales needs to qualify. Industry, company size, role of the buyer, role of the user (often different), use case, current pain. + +### Section 3: top objections and answers + +Three to five expected objections with the answer for each. The answers are written, not improvised; reps should be able to quote them back. + +Example. + +\| Objection \| Answer \| +\|---\|---\| +\| "We already have a routing solution that works fine." \| "Most solutions are keyword-based. Ours uses ML trained on the customer's actual routing decisions, so it adapts to their specific team structure. Customers report 95 percent accuracy vs 60 to 70 percent on keyword-based systems." \| +\| "How is this different from what [Competitor] just shipped?" \| "Both products do automated routing. The difference: ours retrains weekly on the customer's data; theirs uses a fixed model. Customers with non-standard team structures see materially better routing on our system." \| +\| "What if the model gets it wrong?" \| "Below the configurable confidence threshold, the ticket falls back to manual routing. Manager corrections feed back into the model, so accuracy improves over time." \| + +### Section 4: proof points + +The same proof points from the positioning canvas. Three to five concrete capabilities or outcomes. + +### Section 5: deal coaching + +Specific guidance on how this affects deals. + +- Deals to revisit. Customers in the pipeline who were blocked by the gap this feature now closes. Names where appropriate. +- Deals it complicates. Customers on the existing pricing or feature set who may need migration support. Names where appropriate. +- Common pricing questions. What customers ask about cost; the answers reps should give. + +### Section 6: where to learn more + +Links to the demo recording, the full launch brief, the FAQ, the support documentation, and the PM contact for sales questions. + +--- + +## The demo script + +A repeatable demo the rep can run with a customer. + +### Structure + +Open (1 minute). State the customer's pain in their language. Reference what they told the rep in discovery (use a generic placeholder if the rep is in a first-call demo). + +Show the problem (2 minutes). Demonstrate the status quo workflow that the feature replaces. The rep walks through the manual process, naming the friction points. + +Show the feature (5 minutes). Walk through the feature solving the same workflow. Highlight the proof points. Pause at the moments where the customer would feel the difference. + +Show the safety net (2 minutes). Walk through the failure mode. What happens when the feature does not work perfectly. The customer needs to trust the safety net before they trust the feature. + +Close (1 minute). Summarize the value. Ask the customer what they think. Surface objections. + +Total. 11 minutes. Demos longer than 15 minutes lose attention; demos shorter than 7 minutes feel rushed. + +### The recorded demo + +For reps who join after the launch or who want a refresher, a recorded version of the demo. Same structure. Annotated with timestamps. Stored where reps can find it (sales enablement platform, shared drive, internal wiki). + +The recorded demo is not a substitute for the live demo with a customer. It is reference material for the rep. + +--- + +## Deal coaching guide + +Beyond the battlecard's deal-coaching section, a longer-form guide for the top sales scenarios. + +### Scenario 1: deal blocked by missing capability + +The rep has a customer in the pipeline who was blocked by a feature gap that this launch closes. Coaching. + +- Confirm the gap was the actual blocker via discovery questions before pitching the new feature. +- Reference the customer's specific pain in the demo. +- If the deal stalled with a competitor, address the competitor head-on with the differentiator section of the battlecard. +- Time the outreach. Reach out one to three days after public launch comms; the customer will already be aware of the announcement. + +### Scenario 2: existing customer expansion + +The rep has an existing customer using a smaller plan; this launch could justify expansion. Coaching. + +- The customer success team should brief the customer first if the customer is in a top-account tier. +- The rep follows up with an upgrade conversation tied to the specific value the customer gets from the new feature. +- Pricing change documentation if applicable; reps should not improvise pricing. + +### Scenario 3: defensive against churn + +The rep has a customer at risk of churning to a competitor whose product had the feature this launch adds. Coaching. + +- The customer success team should flag the at-risk customer; the rep delivers the briefing in coordination. +- Acknowledge the gap that existed; explain the timeline of the launch; show the feature. +- Offer migration support if the customer was already starting to evaluate the competitor. + +### Scenario 4: net-new pipeline + +The rep is targeting net-new prospects for whom the launch is a relevant capability. Coaching. + +- Lead with the launch as the recent product update; reference the blog post or release. +- Tie the feature to the buyer's expected pain. +- The launch announcement is the conversation starter; the demo is the conversion. + +--- + +## The training session + +Live, 30 minutes, with Q&A. Recorded for reps who cannot attend. + +### Structure + +0 to 5 minutes. PM walks through the positioning canvas. Target user, problem, promise, proof points, anti-positioning. + +5 to 15 minutes. PM (or sales-engineering partner) demos the feature using the demo script. Reps see what the rep version of the demo looks like. + +15 to 25 minutes. Q&A. Reps ask the questions they expect customers to ask. The answers feed back into the FAQ. + +25 to 30 minutes. Coaching on top deal scenarios. Brief discussion of which named accounts in the pipeline are affected. + +### After the session + +- Recording posted to the sales enablement platform. +- Q&A captured in the launch brief's FAQ section. +- Battlecard finalized with any new objections that surfaced. +- Demo script updated with any clarifications from the live demo. + +--- + +## What to skip + +Do not. + +- Hand sales a 12-page document and call it enablement. +- Train sales the morning of public launch. +- Skip the recorded demo because "we can do it live." +- Assume sales will read the launch brief before the customer call. + +The discipline. Sales enablement is short, opinionated, and rehearsed. Reps internalize it once and pitch the feature naturally for the rest of the launch period. + +--- + +## The "shadow launch" failure + +The pattern. + +- Feature ships. +- Sales hears about it from product team Slack. +- No battlecard. +- No demo recording. +- Sales reps either ignore the feature in customer conversations (because they cannot pitch it) or misrepresent it (because they are improvising). +- Customers churn or escalate when the feature does not match what they were told. + +The cost. Engineering investment is captured at zero or negative value. The next product team launch is met with sales skepticism. + +The fix. Sales enablement is mandatory for B2B Tier 1 and Tier 2 launches. The battlecard takes a half day to write. The training session takes 30 minutes. The recorded demo takes an hour. The investment is small relative to the engineering investment behind the feature. diff --git a/skills/feature-launch-playbook/references/support-readiness-checklist.md b/skills/feature-launch-playbook/references/support-readiness-checklist.md new file mode 100644 index 0000000..50f031c --- /dev/null +++ b/skills/feature-launch-playbook/references/support-readiness-checklist.md @@ -0,0 +1,137 @@ +# Support readiness checklist + +Training, FAQ, escalation paths, monitoring access. The pattern of training support before customer-facing launch comms. + +The principle. Support is the first to encounter the failure modes of a new feature. They need the same context as sales but oriented toward post-purchase questions and incident resolution. + +--- + +## The four deliverables + +### 1. Training + +Live or recorded, with Q&A. + +The same content as the sales training, adapted for support workflows. Differences. + +- Sales pitches the feature; support solves problems with it. The training emphasizes how to diagnose customer issues, not how to position the feature. +- Sales sees the happy path; support sees the failure modes. The training includes the FAQ of expected support tickets and the escalation paths for unexpected ones. +- Sales has a 30-minute training; support often has 60 minutes because the breadth of expected questions is larger. + +Schedule. Support training one week before customer-facing launch comms. Recorded for reps who cannot attend live. + +### 2. FAQ document + +The questions that support expects customers to ask, with the answers. + +Categories. + +- What does the feature do. The basic explanation. Same content as the user-visible promise plus a short "how it works" paragraph. +- How do I turn it on. Configuration steps. Permissions required. Plan tier required. +- What are the limits. Rate limits, size limits, supported regions, supported plans. +- What if it does not work. Troubleshooting steps. When to escalate. +- How do I turn it off. For users who tried it and want to revert. Often forgotten until the first customer asks. +- Pricing or billing questions. If the feature affects billing, support needs the answer. + +The FAQ updates daily during the first week of launch as new questions surface. Support reps add questions they encountered to the FAQ; the PM reviews and approves daily. + +### 3. Escalation path + +When support cannot answer a question or solve an issue, who do they escalate to and how fast. + +The escalation contract. + +- Tier 1 (in-product issue). Support resolves with the customer using the FAQ and product knowledge. Target response: under 1 hour during business hours. +- Tier 2 (product question support cannot answer). Escalate to the PM. Target response from PM: same day during business hours. +- Tier 3 (product is broken for the customer). Escalate to engineering on-call. Target response from engineering: under 2 hours regardless of hours during launch week. + +For Tier 1 launches, the on-call rotation should include a launch-week PM contact in addition to the regular engineering on-call. + +### 4. Monitoring access + +Support reps should be able to verify whether a customer's issue is feature-specific. + +The minimum. + +- A dashboard showing feature health (overall error rate, feature-specific error rate, rollout percentage). +- A way to look up whether a specific customer is in the rollout cohort. (For flag-gated rollouts; some customers will not have access to the feature on launch day, and support needs to be able to confirm that.) +- A way to look up the customer's recent feature usage (or the lack thereof). + +Without monitoring access, support reps escalate every feature-related ticket to engineering or the PM. The escalation queue gets noisy; real Tier 3 issues get drowned in Tier 2 questions. + +--- + +## The training-before-comms rule + +The discipline. Support training happens before customer-facing comms launch. + +The reason. Customers will start asking support about the feature within minutes of the public announcement. Support needs to be ready before customers ask, not while customers are asking. + +The pattern. + +- Day T minus 7: support training delivered. FAQ published internally. Escalation paths confirmed. +- Day T minus 1: support team huddle. Last-minute questions. FAQ refresh. +- Day T (launch day): support staffed for elevated volume. PM and engineering on-call paths confirmed open. + +The "training day-of" failure. Support is trained the morning of public launch. By the afternoon, they have already encountered three customer questions they cannot answer well. The support team's confidence with the feature degrades; customers feel the rep does not know the product. Trust loss. + +--- + +## The "support is overwhelmed" failure + +The setup. The launch generates more support volume than the team expected. The feature is novel; customers ask many basic questions; the FAQ does not anticipate the actual questions; support reps escalate everything to the PM. + +The signs. + +- Support ticket queue length doubles or triples on launch day vs the prior week. +- Tickets tagged with the feature exceed the support team's capacity for new conversations. +- The PM's Slack is full of support questions that should have FAQ answers. + +The fix. + +- Pre-launch: estimate support volume. Look at ticket volume from prior comparable launches; double the estimate. +- Pre-launch: staff support for the launch window. Pull in cross-functional help if needed. +- Pre-launch: write the FAQ deeper than feels necessary. Most launches have 20 to 30 expected questions; document them all in advance. +- Launch day: PM is available for FAQ updates throughout the day. New questions get answers within an hour and propagate to support. + +--- + +## What support needs that sales does not + +Two specific differences. + +Failure modes documentation. Support needs to know what happens when the feature breaks. The error messages users see, the recovery flows, the limitations. Sales does not need this depth; support requires it. + +Customer-facing language for limits. Sales pitches the feature and addresses the limits at the negotiation stage. Support encounters the limits the moment a customer hits them. Support reps need pre-written language for "the feature supports up to X; for higher volumes, contact your account manager." + +Without these two, support is improvising at the moment of customer pain. Improvisation produces inconsistent answers across reps; customers compare notes and lose trust. + +--- + +## The post-launch FAQ refresh cycle + +For two to four weeks post-launch, the FAQ refreshes daily. + +- Support reps log new questions they encountered, with the answers they gave. +- PM reviews daily, approves or corrects answers, adds them to the canonical FAQ. +- Support team gets a daily summary of new FAQ entries. + +After two to four weeks, the FAQ stabilizes. The refresh moves to weekly, then monthly. + +The cost of the daily refresh is small. The benefit is that support builds confidence with the feature in the first month, instead of struggling for the first quarter. + +--- + +## When support flags an issue larger than a question + +Sometimes the support volume on a feature reveals a real problem with the feature, not just a need for better FAQ. + +Signs. + +- Many customers ask the same question, and the answer is "the feature does not do that." The customers expected something the feature does not deliver. Positioning was misaligned. +- Many customers report the same bug. The bug is real and affects a meaningful share of users. +- Support tickets cluster on a specific cohort (e.g., users on a specific plan, in a specific region). The feature does not work correctly for that cohort. + +The pattern. Support is the early-warning system for launch quality. The PM should review the support ticket digest daily during the first week and at least weekly thereafter. If the support volume reveals a feature problem, the launch may need to pause for a fix before further rollout. + +The discipline of treating support as a quality signal is the cheapest way to catch launch problems before they show up in revenue or churn metrics. diff --git a/skills/form-strategy/SKILL.md b/skills/form-strategy/SKILL.md new file mode 100644 index 0000000..75b63cb --- /dev/null +++ b/skills/form-strategy/SKILL.md @@ -0,0 +1,257 @@ +--- +name: form-strategy +description: "Design forms that convert, validate well, resist spam, and integrate cleanly with downstream systems. Use this skill when designing or auditing any form (contact, signup, checkout, multi-step, embedded), planning validation logic, fighting spam, choosing form tooling, or improving form conversion. Triggers on form design, form validation, form conversion, multi-step form, form spam, captcha, honeypot, form abandonment, signup form, contact form. Also triggers when form completion rates are low or spam is overwhelming." +category: cross-cutting +catalog_summary: "Form design, validation patterns, spam prevention, conversion tuning" +display_order: 1 +--- + +# Form Strategy + +Forms are where intent becomes action. Design them well or lose conversions, frustrate users, and drown in spam. Stack-agnostic. + +--- + +## When to use + +- Designing or redesigning a form +- Conversion is dropping on a key form +- Spam volume is overwhelming the inbox or database +- Auditing forms across a site +- Planning validation logic +- Choosing form tooling (form service, custom build, no-code) +- Integrating forms with CRM, email, or other downstream systems +- Multi-step form decisions + +## When NOT to use + +- Generic conversion optimization (use `cro-optimization`) +- The copy on the form (use `landing-page-copy`) +- Backend handling beyond form-specific concerns (use `frontend-component-build`, `code-review-web`) +- General accessibility (use `accessibility-audit`) + +--- + +## Required inputs + +- The form's purpose (what action, what outcome) +- Current form (URL, screenshot, or fields) +- Current performance (completion rate, spam rate, conversion to next step) +- Downstream system (where submissions go: CRM, email, database, support tool) +- Business context (volume, urgency of leads, cost of false vs missed signups) + +--- + +## The framework: 5 dimensions + +Every form decision falls into one of these dimensions. + +### Dimension 1: Field strategy + +The biggest lever. Every additional field reduces conversion. + +Questions to ask for each field: +- Is this required to deliver value to the user? +- Is this required to deliver value to the business? +- Can it be inferred from another source (email domain, behavior, context)? +- Can it be asked later (after first contact, on second visit, on settings page)? + +Default rule: ask for the minimum to make the next step happen. Everything else later. + +For a B2B contact form: name and email get you started. Phone, company size, role are nice-to-haves that often hurt conversion more than they help qualification. + +For a checkout: country, postal code, address, name, payment. Anything else (referral source, marketing opt-in, account creation) is optional or moved to post-purchase. + +### Dimension 2: Field design + +How each field looks and behaves. + +- Labels above inputs beat placeholders. Placeholder labels disappear when typing. +- Inline labels (floating labels) work for very compact forms. +- Single column for almost every form. Eyes flow vertically. +- Logical grouping with visible spacing. Don't put unrelated fields next to each other. +- Right input type: `email` for emails, `tel` for phone, `number` for numbers, `date` for dates. Mobile keyboards adapt. +- Autocomplete attributes: `autocomplete="email"`, `autocomplete="given-name"`, etc. Browsers and password managers fill them in. +- Sensible defaults for fields where one applies (country pre-selected by IP, etc.). Don't default to anything that would mislead if wrong. + +### Dimension 3: Validation + +Tell users what's wrong, when, and how to fix it. + +- Validate on blur, not on every keystroke. Inline errors that appear as someone types are jarring. +- Re-validate on submit (catch fields the user skipped). +- Specific messages: "Email must include @" beats "Invalid email." +- Position errors next to the field they refer to. +- Don't submit a form when there are errors. Highlight the first errored field. Scroll to it. +- Validate server-side too. Client validation is UX. Server validation is correctness. + +For format-flexible fields (phone numbers, postal codes), validate liberally. Reject only what's clearly wrong, not what's "non-standard." Many phone formats exist. + +### Dimension 4: Spam defense + +Public forms attract spam. Plan for it from day one. + +Layered defense: + +1. Honeypot field. A hidden field that humans don't fill in but bots do. If it's filled, reject silently. Free, low-friction, surprisingly effective for low-effort spam. +2. Time-based detection. Reject submissions completed in under 2-3 seconds (bots) or after very long delays (suspicious sessions). +3. Rate limiting. Reject if the same IP submits too many times. +4. CAPTCHA as a last resort. Modern invisible CAPTCHAs (hCaptcha, reCAPTCHA v3, Turnstile) are low-friction. Old image CAPTCHAs are conversion-killers. +5. Behavioral signals. Did the cursor move? Was there scroll? Modern services track this. +6. Content filtering. Reject obvious spam content (links, foreign-language content if your audience is local, common spam words). +7. Server-side review. A queue rather than direct delivery to inboxes for high-spam-target forms. + +For most contact forms: honeypot + time check + Turnstile (or similar) is sufficient. + +### Dimension 5: Submission flow + +What happens after submit. + +- Inline success message for short forms. Don't redirect just to confirm. +- Confirmation page for high-value submissions (to provide next steps, set expectations). +- Email confirmation for signups, purchases, RSVPs. Always. +- Save data on errors so the user doesn't re-enter everything. +- Optimistic UI (show success before the server confirms) for low-stakes forms; risky for high-stakes. + +For multi-step forms: +- Show progress (3 of 5) +- Save state between steps (in case of refresh or navigation) +- Allow back navigation without losing data +- Validate per step, not just at the end + +--- + +## Workflow + +### Step 1: Audit current state + +For each form on the site: +- What's its purpose? +- Number of fields, required vs optional +- Current completion rate +- Current spam rate +- Validation rules +- What happens after submit +- Where the data goes downstream + +### Step 2: Define success per form + +Different forms have different success metrics: +- Lead form: qualified leads (defined by sales) +- Newsletter: confirmed subscriptions (after double opt-in) +- Contact: substantive replies (not just submissions) +- Checkout: successful payments + +Track the metric that matters, not just submissions. + +### Step 3: Cut fields ruthlessly + +Apply the field strategy filter. For each field, answer: +- Required to deliver value? Keep. +- Nice to have? Move to optional or later. +- Used for routing or qualification? Often can be inferred. + +A 7-field form becomes a 3-field form. Conversion rises. + +### Step 4: Set up spam defense + +Before launching a public form: +- Add a honeypot field +- Add time-based detection +- Add rate limiting +- Add a modern CAPTCHA if the form is high-traffic or high-spam + +After launch, monitor. Tune layers based on what's actually getting through. + +### Step 5: Improve validation + +Walk through each field: +- Is validation specific? +- Does it run at the right time (blur or submit, not on keystroke)? +- Are error messages actionable? +- Is server-side validation matching client-side? + +### Step 6: Verify accessibility + +Critical baseline: +- Every input has an associated label (visually visible or `aria-label`) +- Errors are associated with inputs (`aria-describedby`, `aria-invalid`) +- Focus order matches visual order +- Color isn't the only way to indicate errors +- Form is fully keyboard-navigable + +See `accessibility-audit` for the full WCAG audit. + +### Step 7: Test downstream + +Submit the form. Verify: +- Data lands where it should +- Required fields are populated correctly +- Spam defenses are working (test with a script) +- The user gets the confirmation they expect +- Internal notification is timely + +Forms break silently when downstream systems change. Test after any integration update. + +### Step 8: Monitor + +- Completion rate over time +- Spam rate over time +- Errors per submission (high errors = bad UX) +- Drop-off field (where do people abandon?) + +--- + +## Failure patterns + +Too many fields. Most B2B contact forms have 3x more fields than they need. Cut. + +Validation that fires while typing. Annoying. Causes errors before the user has finished. + +Generic error messages. "Invalid input." Where? Why? Be specific. + +Required fields not marked. Users discover they're required only after submission fails. Mark required (or, for short forms, mark optional). + +Autocomplete disabled. "For security." It's almost never a security improvement and always a UX cost. Leave autocomplete on. + +Tab order is broken. Tab key skips fields or jumps backward. Set `tabindex` only when necessary; use natural DOM order. + +Submit button below the fold. Especially on mobile. Users don't see it. + +No save on error. User submits, has one error, returns to the form, all fields empty. Nightmare. Save the state. + +Captcha as the only spam defense. Captchas are friction. Layered defense beats brute-force friction. + +Captcha visible by default. Modern CAPTCHAs (Turnstile, reCAPTCHA v3) are invisible most of the time and only escalate when needed. Use those. + +Newsletter signup that's actually a marketing list. Honor opt-in scope. If the user signed up for product updates, don't add them to the marketing newsletter. + +Confirmation page that's a dead end. "Thanks for submitting" with no next step. What now? Provide an action (read related content, return to homepage, follow on social). + +No double opt-in for marketing email. Bots and typos pollute the list. See `email-deliverability` for why this matters. + +Email field accepting `name@` as valid. Browser spec validation is loose. Validate against an actual format. + +Custom date pickers worse than native. The native `<input type="date">` is now good on most platforms. Don't reinvent unless you have a specific reason. + +Forms that lose state on refresh. For long forms, save to localStorage and restore on load. + +--- + +## Output format + +A form audit document includes: + +- Form inventory: every form on the site +- Per-form review: purpose, fields, performance +- Recommendations: field cuts, validation improvements, spam defense, design changes +- Spam defense plan: layers per form +- Accessibility status: WCAG compliance per form +- Downstream integration map: where each form's data goes +- Monitoring plan: what's tracked + +--- + +## Reference files + +- [`references/form-anatomy-checklist.md`](references/form-anatomy-checklist.md): A field-by-field, behavior-by-behavior checklist for auditing or designing a form, covering structure, accessibility, validation, and spam defense. diff --git a/skills/form-strategy/references/form-anatomy-checklist.md b/skills/form-strategy/references/form-anatomy-checklist.md new file mode 100644 index 0000000..14f651f --- /dev/null +++ b/skills/form-strategy/references/form-anatomy-checklist.md @@ -0,0 +1,243 @@ +# Form Anatomy Checklist + +A field-by-field, behavior-by-behavior checklist for auditing or designing a form. Walk through it for any form before shipping. + +--- + +## Overall structure + +- [ ] Purpose is clear from headline, subheadline, or surrounding context +- [ ] Single column layout (multi-column forms are slower to scan and complete) +- [ ] Form is reasonably short (cut fields you don't strictly need) +- [ ] Required vs optional is clear (mark one or the other based on which is shorter) +- [ ] Logical grouping of related fields with visible spacing +- [ ] Submit button is visible without scrolling on common viewports +- [ ] Submit button text is specific to the action ("Get the report" beats "Submit") + +--- + +## Per-field checklist + +For each field, verify: + +### Label + +- [ ] Has a visible label (or, for compact forms, a clearly associated visible cue) +- [ ] Label is above the input (preferred) or floats (acceptable for compact) +- [ ] Label is descriptive (not just the field name from the database) +- [ ] Label is associated with the input via `for=` and `id=` or a wrapping `<label>` + +### Input type + +- [ ] Uses semantic input type: + - `email` for emails + - `tel` for phone + - `number` for numeric (when not formatted, like a count or amount) + - `date` for dates + - `url` for URLs + - `text` for general +- [ ] Native input where possible (date, color, range) before custom widgets +- [ ] `inputmode` attribute set when it differs from type (e.g., `inputmode="decimal"` on a price) + +### Autocomplete + +- [ ] `autocomplete=` attribute set with the appropriate value + - `name`, `given-name`, `family-name` + - `email` + - `tel` + - `street-address`, `address-line1`, `postal-code`, `country` + - `cc-name`, `cc-number`, `cc-exp`, `cc-csc` + - `current-password`, `new-password` +- [ ] Doesn't disable autocomplete without good reason + +### Validation + +- [ ] Validates on blur, not on every keystroke +- [ ] Validates again on submit (in case fields were skipped) +- [ ] Error message is specific ("Email must include @" not "Invalid") +- [ ] Error message appears next to the field +- [ ] Error state is visually distinct (not just color; also icon or pattern) +- [ ] `aria-invalid="true"` on errored fields +- [ ] `aria-describedby` linking the field to its error message + +### Server-side validation + +- [ ] Server validates everything client validates (client validation is UX, server is correctness) +- [ ] Server validates fields the client can't (uniqueness, business rules, etc.) +- [ ] Server returns specific error messages +- [ ] Server is the source of truth for "save" + +### Hint text + +- [ ] If a field needs explanation, hint text is below the field (not in placeholder) +- [ ] Hint text uses `aria-describedby` to associate with the input +- [ ] Hint text doesn't contain critical info that would be missed if not read + +### Required vs optional + +- [ ] Marked clearly (consistently use either "required" markers or "optional" markers, not both) +- [ ] `required` attribute set on truly required fields +- [ ] Required fields announced to assistive tech (the `required` attribute does this) +- [ ] Field has a fallback if accidentally skipped (server validation catches it gracefully) + +### Width + +- [ ] Field width matches expected input length (don't make a postal code field as wide as a name field) +- [ ] Mobile field width is full-width minus reasonable margins + +### Specific field types + +Password: +- [ ] `autocomplete="current-password"` for login, `"new-password"` for signup +- [ ] Toggle to show password (not in lieu of, but in addition to, dots) +- [ ] Length and complexity hints visible before typing +- [ ] Allow long passphrases (no max length under 64+ chars) + +Email: +- [ ] `type="email"` and `autocomplete="email"` +- [ ] Server validates format more strictly than the browser default +- [ ] Confirms for high-stakes use (with a second email field) or relies on confirmation email + +Phone: +- [ ] `type="tel"` and `autocomplete="tel"` +- [ ] Liberal validation (accept various formats) +- [ ] Country code handling if international + +Date: +- [ ] `type="date"` for native picker, or a well-tested custom picker +- [ ] Timezone handling thought through (server side) + +Address: +- [ ] Multiple fields (line 1, line 2, city, region, postal code, country) +- [ ] `autocomplete` on each +- [ ] Validation by country (US ZIP differs from UK postcode) +- [ ] Optional autocomplete via address API for high-conversion forms + +File upload: +- [ ] Accepted types declared with `accept=` +- [ ] Size limit communicated and enforced (client and server) +- [ ] Drag-and-drop and click-to-browse both work +- [ ] Selected file feedback (name, size, preview if image) +- [ ] Progress indicator for slow uploads +- [ ] Server scans uploads if user-generated content goes public + +Select / dropdown: +- [ ] Native `<select>` for short lists (under ~15 options) +- [ ] Custom searchable component for long lists +- [ ] Default option that's not selectable (e.g., "Select a country") +- [ ] Sort by likelihood (popular options first), or alphabetical, not random + +Radio buttons: +- [ ] Use for 2-7 mutually exclusive options +- [ ] All options visible (no scrolling) +- [ ] One option pre-selected only if a sensible default exists + +Checkboxes: +- [ ] Use for boolean choices and multi-select +- [ ] Label is clickable (associated with checkbox) +- [ ] Marketing opt-ins are off by default (legal requirement in many regions) +- [ ] Terms-of-service is unchecked by default (active acceptance) + +Multi-step forms: +- [ ] Progress indicator (3 of 5) +- [ ] State saved between steps (refresh-resilient) +- [ ] Back navigation doesn't lose data +- [ ] Validation per step +- [ ] Final review step before submit (high-stakes only) + +--- + +## Spam defense + +- [ ] Honeypot field (hidden, must remain empty) +- [ ] Time-based detection (reject very fast or very slow submissions) +- [ ] Rate limiting per IP / per session +- [ ] Modern CAPTCHA (Turnstile, hCaptcha invisible, reCAPTCHA v3) if needed +- [ ] Server-side spam content filtering for high-volume forms +- [ ] Logging of rejected submissions for tuning + +--- + +## Accessibility + +- [ ] Form is fully keyboard-navigable (Tab, Shift+Tab, Enter to submit) +- [ ] Tab order matches visual order +- [ ] Focus is visible (don't remove the focus outline) +- [ ] Form errors are announced to screen readers +- [ ] Color contrast meets WCAG (4.5:1 for text, 3:1 for UI) +- [ ] Errors aren't communicated only by color +- [ ] Form works at 200% zoom +- [ ] Touch targets at least 44px on mobile +- [ ] No time limits without warning and the option to extend + +--- + +## Submission + +- [ ] Submit button is disabled while submission is in flight (prevent double-submit) +- [ ] Loading state on the button or near the form +- [ ] Success state is clear (inline message, redirect to confirmation page, or both) +- [ ] Failure state is clear (specific reason, what to do, support contact) +- [ ] State preserved on submission failure (user doesn't lose data) +- [ ] Email confirmation sent for signups, purchases, RSVPs +- [ ] Internal notification (if applicable) is timely + +--- + +## Privacy and compliance + +- [ ] Privacy notice or link visible near the form +- [ ] Terms of service link if relevant +- [ ] Marketing consent (where required by jurisdiction) is explicit and unchecked by default +- [ ] Data sent over HTTPS only +- [ ] Sensitive fields (passwords, payment) not autofilled by URL params (don't appear in browser history) + +--- + +## Performance + +- [ ] Form loads quickly (lazy-load any heavy assets like CAPTCHAs until needed) +- [ ] Submit handler doesn't block the UI +- [ ] No unnecessary fetches on field interaction +- [ ] CAPTCHA loads asynchronously + +--- + +## Monitoring + +- [ ] Completion rate tracked +- [ ] Field-level drop-off tracked (where do people abandon?) +- [ ] Errors tracked (which fields cause the most errors?) +- [ ] Spam rate tracked (compare layers of defense over time) +- [ ] Submission failures tracked (server errors, integration failures) + +--- + +## Pre-launch test + +Before publishing a form publicly: + +- [ ] Submit successfully with valid data +- [ ] Submit unsuccessfully with bad data (verify error UX) +- [ ] Submit with no data (verify required-field UX) +- [ ] Submit with the honeypot filled (verify silent rejection) +- [ ] Submit very fast (verify time-based rejection) +- [ ] Submit on mobile (verify mobile UX) +- [ ] Submit with keyboard only (verify accessibility) +- [ ] Submit with a screen reader (verify announcements) +- [ ] Submit with autocomplete enabled (verify it works) +- [ ] Verify data lands in the correct downstream system +- [ ] Verify confirmation email arrives (if applicable) +- [ ] Verify internal notification arrives (if applicable) +- [ ] Try to submit duplicate (verify deduplication if applicable) + +--- + +## Post-launch review (after first week) + +- [ ] Completion rate vs target +- [ ] Spam rate (tune defense if needed) +- [ ] Errors (most common errors? could be UX problems) +- [ ] Drop-off (which field loses people?) +- [ ] Downstream system happy? (CRM data clean, no broken integrations) +- [ ] Customer reports (anyone reporting a broken form?) diff --git a/skills/frontend-component-build/SKILL.md b/skills/frontend-component-build/SKILL.md new file mode 100644 index 0000000..fb5f5f7 --- /dev/null +++ b/skills/frontend-component-build/SKILL.md @@ -0,0 +1,184 @@ +--- +name: frontend-component-build +description: "Build production-ready frontend components with accessible markup, sensible props, defined states, and tested behavior. Use this skill whenever the user wants to build a component from scratch, refactor an existing one, design a component API, or implement a UI element with proper states and accessibility. Triggers on build a component, create a button, create a modal, create a form input, component API, props design, component states, refactor component, accessible component. Also triggers when implementing UI from a design that needs to be reusable." +category: development +catalog_summary: "Component architecture, props design, accessibility from the start" +display_order: 2 +--- + +# Frontend Component Build + +Build production-ready components. Stack-agnostic principles. Most patterns translate to React, Vue, Svelte, or vanilla web components. + +This skill is about implementing a component well. For broader system design see `design-system`. For day-to-day visual decisions see `design-standards`. + +--- + +## When to use + +- Building a new component from scratch +- Refactoring an existing component +- Designing a component API (props, slots, events) +- Adding accessibility to an existing component +- Implementing a component from a design + +## When NOT to use + +- Building a full design system (use `design-system`) +- Page-level design decisions (use `design-standards`) +- Backend or data work (use `code-review-web`) +- Performance-only optimization (use `performance-optimization`) + +--- + +## Required inputs + +- The component's purpose (what UI need it serves) +- The design (or willingness to design it) +- The framework or technical context +- The states the component must support +- Accessibility requirements + +--- + +## The framework: 6 dimensions + +A complete component handles six dimensions. Skip any one and the component is incomplete. + +### 1. Anatomy + +Identify the parts that make up the component before writing any markup. + +Common anatomies: +- Button: container + label + (optional) icon + (optional) loading indicator +- Modal: backdrop + container + header + body + footer + close affordance +- Form input: label + input + (optional) help text + (optional) error message +- Card: container + (optional) header + body + (optional) footer + (optional) media + +Naming the parts up front makes the API obvious. + +### 2. Variants + +What variations does the component support? + +- Visual variants (primary, secondary, ghost, danger) +- Size variants (small, medium, large) +- Functional variants (with icon, without icon, icon-only) + +Variants should be a managed set, not a free-for-all. Document the supported set; reject requests for new variants without a real use case. + +### 3. States + +What states must the component handle? + +- Default +- Hover (when pointer is supported) +- Focus (always - keyboard navigation requires it) +- Active / pressed +- Disabled +- Loading (where applicable) +- Error (for inputs, forms, validation-bound components) +- Empty (for components that display data) + +Every state needs visual treatment AND accessibility treatment. + +### 4. Props / API + +Design the component's contract. + +API design principles: + +- Required props minimal. What's truly needed every time? That's required. Everything else has a sensible default. +- Boolean props are red flags. Three booleans means seven combinations. Prefer enum strings: `variant: "primary" \| "secondary" \| "ghost"` over `primary={true} ghost={false}`. +- Children > props. Where content is content, accept children. Don't invent `headerText` and `bodyText` props when slots work. +- Composition > configuration. A component that does 5 things via 12 props often should be 5 smaller components. +- Type the props. TypeScript or PropTypes or JSDoc. The type is documentation that won't go out of date. + +### 5. Accessibility + +Build it accessible from the start. Adding accessibility later is 5x harder. + +Universal: +- Semantic HTML elements (`<button>`, `<a>`, `<nav>`, `<form>`, etc.) over generic `<div>` +- Keyboard navigable (Tab, Shift+Tab, Enter/Space for buttons) +- Focus visible +- Tap targets minimum 44 by 44 pixels +- ARIA only where semantic HTML is insufficient + +Component-specific: + +- Button: use `<button>`. Don't fake one with a `<div>`. +- Modal: focus trap, ESC to close, returns focus to trigger on close, `role="dialog"` and `aria-labelledby`. +- Form input: label associated via `for`/`id` or `aria-labelledby`. Error messages linked via `aria-describedby`. `aria-invalid` when in error state. +- Toggles: `<button>` with `aria-pressed` for two-state, or `role="switch"` for on/off. +- Tabs: `role="tablist"` / `role="tab"` / `role="tabpanel"` with `aria-selected` and arrow-key navigation. +- Tooltips and popovers: triggered by focus AND hover. Dismissible with ESC. +- Loading states: announce with `aria-live` so screen readers know something changed. + +### 6. Tests + +Verify the component works before declaring it done. + +Test types by priority: + +1. Visual regression. Renders correctly across variants and states. (Storybook + visual diff tools, or manual screenshots.) +2. Accessibility. Passes axe or equivalent automated checks. +3. Keyboard navigation. Tab, Enter, Escape, arrow keys all work as expected. +4. Component logic. Props produce expected output. Events fire correctly. (Unit tests.) +5. Integration. Component works inside its expected parent contexts. + +A component without at least automated accessibility testing is not done. + +--- + +## Workflow + +1. Understand the use case. What UI need does this component serve? Where will it appear? Adjacent components? +2. Sketch the anatomy. Name the parts. +3. List variants and states. Match the design system or define new ones if needed. +4. Design the API. Required props, optional props, children, events. Type it. +5. Build the markup with semantic HTML. Choose the right elements. Avoid generic `<div>` for interactive things. +6. Style with tokens. No hardcoded colors, spacing, or sizes. +7. Add interaction. Focus management, keyboard handlers, ARIA. +8. Add states. Hover, focus, active, disabled, loading, error. +9. Test. Automated accessibility, keyboard navigation, visual regression. +10. Document. Usage, API, examples, anti-patterns. + +--- + +## Failure patterns + +- Building with `<div onClick>`. Loses keyboard accessibility, screen reader semantics, and focus. Use `<button>` or `<a>`. +- Hardcoding colors and sizes. Tokens exist for a reason. Hardcoded values resist theming and consistency. +- Boolean prop explosion. `<Button primary large rounded fullWidth disabled icon />`. Too many booleans means you actually need fewer variants designed more thoughtfully. +- Forgetting focus states. Hover gets attention; focus gets neglected. Keyboard users see invisible buttons. +- Skipping disabled-state thought. A disabled button should look obviously disabled AND be `aria-disabled` AND not respond to clicks. +- Inventing ARIA. ARIA roles and properties have specific behaviors. Made-up ARIA is worse than no ARIA. Use semantic HTML first. +- Loading state that doesn't announce. Screen readers don't know the spinner appeared. Use `aria-live="polite"` or `role="status"`. +- Tooltip-only critical content. Hover-only content is invisible to keyboard and touch users. Critical content goes in the visible UI. +- Component without docs. Future-you, your teammate, or the next maintainer cannot use what they cannot understand. + +--- + +## Output format + +A complete component delivery includes: + +- Component code (in the appropriate framework) +- Storybook (or equivalent) entry showing all variants and states +- Documentation: + - Anatomy diagram or description + - Props/API table + - Usage examples (basic, advanced, edge cases) + - When to use vs. when to use an alternative + - Anti-patterns (what to avoid) + - Accessibility notes +- Tests (visual regression + accessibility + logic) + +--- + +## Reference files + +- [`references/component-spec-template.md`](references/component-spec-template.md) - Template for documenting a component (props, states, accessibility, edge cases) before building. +- [`references/component-api-patterns.md`](references/component-api-patterns.md) - Common patterns for designing flexible component APIs (compound components, controlled vs uncontrolled, polymorphic `as` prop, render props, slots). +- [`references/accessibility-patterns.md`](references/accessibility-patterns.md) - ARIA patterns for common interactive components. diff --git a/skills/frontend-component-build/references/accessibility-patterns.md b/skills/frontend-component-build/references/accessibility-patterns.md new file mode 100644 index 0000000..d32ab58 --- /dev/null +++ b/skills/frontend-component-build/references/accessibility-patterns.md @@ -0,0 +1,354 @@ +# Accessibility Patterns + +ARIA patterns for common interactive components. Each follows the WAI-ARIA Authoring Practices guidelines. + +When in doubt, use semantic HTML. Reach for ARIA only when semantic HTML cannot express what's needed. + +--- + +## Button + +```html +<button type="button"> + Click me +</button> +``` + +That's it. Don't reinvent it. + +For buttons that toggle a state: +```html +<button type="button" aria-pressed="false"> + Bookmark +</button> +``` +Toggle `aria-pressed` between `"true"` and `"false"` on click. + +For buttons that disclose content: +```html +<button type="button" aria-expanded="false" aria-controls="menu-1"> + Menu +</button> +<ul id="menu-1" hidden>...</ul> +``` +Toggle `aria-expanded` and `hidden` together. + +Anti-patterns: +- `<div onClick>` instead of `<button>` +- Buttons that look like buttons but use `<a href="#">` +- Missing `type="button"` (defaults to `type="submit"` inside forms, causing accidental submits) + +--- + +## Link + +```html +<a href="/destination"> + Link text +</a> +``` + +For external links opening in new tab: +```html +<a href="https://external.com" target="_blank" rel="noopener noreferrer"> + External site +</a> +``` + +Anti-patterns: +- `<a>` without `href` (breaks keyboard navigation; use `<button>` instead) +- `<a href="#">` for buttons (causes URL pollution and unexpected behavior) +- Generic link text ("click here," "read more") + +--- + +## Form input with label + +```html +<div> + <label for="email">Email address</label> + <input id="email" type="email" name="email" required /> + <p id="email-help">We'll never share your email.</p> +</div> +``` + +With help text linked: +```html +<input id="email" type="email" aria-describedby="email-help" /> +<p id="email-help">We'll never share your email.</p> +``` + +With error state: +```html +<input + id="email" + type="email" + aria-invalid="true" + aria-describedby="email-error" +/> +<p id="email-error" role="alert">Please enter a valid email.</p> +``` + +Anti-patterns: +- Placeholder as label (placeholder disappears on input, leaving field unlabeled) +- Label not associated (visual proximity isn't enough) +- Error indicated by color only (color-blind users miss it) + +--- + +## Modal / dialog + +```html +<div + role="dialog" + aria-modal="true" + aria-labelledby="dialog-title" + aria-describedby="dialog-description" +> + <h2 id="dialog-title">Confirm action</h2> + <p id="dialog-description">Are you sure you want to delete this?</p> + <button type="button" data-close>Cancel</button> + <button type="button" data-confirm>Delete</button> +</div> +``` + +Behavior requirements: +- Trap focus inside the modal while open +- Return focus to the trigger element on close +- Close on Escape key +- Close on backdrop click (optional, but expected) +- Background content should be inert (`inert` attribute or `aria-hidden`) +- Body scroll locked while modal is open + +Anti-patterns: +- Modal without focus trap (Tab escapes to background page) +- Modal without `aria-modal` and `role="dialog"` +- Modal that doesn't return focus on close +- Background content remains tabbable + +--- + +## Disclosure (accordion section) + +```html +<button + type="button" + aria-expanded="false" + aria-controls="section-1" +> + Section title +</button> +<div id="section-1" hidden> + Section content... +</div> +``` + +For full accordion (multiple disclosures, optionally limit one open at a time), repeat the pattern. + +--- + +## Tabs + +```html +<div role="tablist" aria-label="Settings sections"> + <button + role="tab" + aria-selected="true" + aria-controls="panel-1" + id="tab-1" + tabindex="0" + > + Profile + </button> + <button + role="tab" + aria-selected="false" + aria-controls="panel-2" + id="tab-2" + tabindex="-1" + > + Notifications + </button> +</div> + +<div role="tabpanel" id="panel-1" aria-labelledby="tab-1"> + Profile content... +</div> +<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden> + Notifications content... +</div> +``` + +Behavior requirements: +- Arrow keys navigate between tabs +- Active tab has `aria-selected="true"` and `tabindex="0"` +- Inactive tabs have `aria-selected="false"` and `tabindex="-1"` +- Selecting a tab shows the corresponding panel +- Home / End keys jump to first / last tab + +--- + +## Toggle switch + +```html +<button + type="button" + role="switch" + aria-checked="false" + id="darkmode-toggle" +> + <span class="visually-hidden">Dark mode</span> +</button> +<label for="darkmode-toggle">Dark mode</label> +``` + +Toggle `aria-checked` between `"true"` and `"false"` on click. + +Alternatively, use a real checkbox styled as a switch: +```html +<label> + <input type="checkbox" role="switch" /> + Dark mode +</label> +``` + +--- + +## Combobox / autocomplete + +```html +<label for="city">City</label> +<input + id="city" + type="text" + role="combobox" + aria-autocomplete="list" + aria-controls="city-listbox" + aria-expanded="false" + autocomplete="off" +/> +<ul id="city-listbox" role="listbox" hidden> + <li role="option" id="city-1" aria-selected="false">London</li> + <li role="option" id="city-2" aria-selected="false">Lagos</li> +</ul> +``` + +Behavior requirements: +- Down arrow opens listbox +- Arrow keys navigate options +- Enter selects highlighted option +- Escape closes listbox +- `aria-activedescendant` on the input points to highlighted option +- Type-ahead filtering + +This is one of the most complex patterns. Test thoroughly with screen readers. + +--- + +## Menu / menubar + +```html +<button + type="button" + aria-haspopup="menu" + aria-expanded="false" + aria-controls="user-menu" +> + Account +</button> +<ul role="menu" id="user-menu" hidden> + <li role="menuitem" tabindex="-1"><a href="/profile">Profile</a></li> + <li role="menuitem" tabindex="-1"><a href="/settings">Settings</a></li> + <li role="menuitem" tabindex="-1"><a href="/logout">Sign out</a></li> +</ul> +``` + +Behavior requirements: +- Down arrow / up arrow navigate menu items +- Escape closes menu +- Click outside closes menu +- Focus returns to trigger on close + +Important: `role="menu"` is for command-style menus (like a desktop application's File menu). For navigation, use `<nav>` with regular links instead. + +--- + +## Loading and live regions + +```html +<div role="status" aria-live="polite"> + Loading results... +</div> +``` + +Use `role="status"` (or `aria-live="polite"`) for non-urgent updates. +Use `role="alert"` (or `aria-live="assertive"`) for urgent errors. + +Anti-patterns: +- Spinners with no announcement (screen readers don't know anything changed) +- Live regions that announce too aggressively (`aria-live="assertive"` for non-critical updates) + +--- + +## Skip link + +```html +<a href="#main-content" class="skip-link">Skip to main content</a> +... +<main id="main-content">...</main> +``` + +CSS: +```css +.skip-link { + position: absolute; + top: -100px; + left: 0; +} +.skip-link:focus { + top: 0; +} +``` + +The skip link should be the first focusable element on the page. Visible only when focused. + +--- + +## Visually hidden but available to screen readers + +```css +.visually-hidden { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border: 0; +} +``` + +Use for content that screen readers need but sighted users don't (e.g., the label of an icon-only button). + +```html +<button type="button"> + <SearchIcon aria-hidden="true" /> + <span class="visually-hidden">Search</span> +</button> +``` + +Anti-pattern: `display: none` or `visibility: hidden` removes content from the accessibility tree too. Use `visually-hidden` for content meant for screen readers only. + +--- + +## Generic notes + +- Test with a real screen reader. VoiceOver (macOS, iOS) and NVDA (Windows) are free. +- Test with keyboard alone. Unplug the mouse. Can you accomplish the task? +- Run automated tests. axe DevTools, Lighthouse, WAVE catch the basics. +- Don't fake elements that exist. A `<div role="button">` is worse than a `<button>`. +- Less ARIA is more. Most components need little or no ARIA. Semantic HTML does the work. + +For deep accessibility audits, use `accessibility-audit`. diff --git a/skills/frontend-component-build/references/component-api-patterns.md b/skills/frontend-component-build/references/component-api-patterns.md new file mode 100644 index 0000000..96283bc --- /dev/null +++ b/skills/frontend-component-build/references/component-api-patterns.md @@ -0,0 +1,311 @@ +# Component API Patterns + +Common patterns for building flexible, predictable component APIs. Examples assume React idioms but the patterns translate to Vue, Svelte, and Web Components. + +--- + +## Pattern 1: Compound components + +Multi-part components where each part is a separate sub-component sharing state via context. + +Use when: +- The component has distinct, repeating sub-parts (header, body, footer) +- Consumers need flexibility in arrangement and content +- Internal state needs to coordinate across parts + +```jsx +<Card> + <Card.Header>Title</Card.Header> + <Card.Body> + <Text>Content</Text> + </Card.Body> + <Card.Footer> + <Button>Action</Button> + </Card.Footer> +</Card> +``` + +Pros: +- Highly composable +- Consumers control arrangement +- Internal state stays encapsulated + +Cons: +- More API surface to maintain +- Less guidance for the consumer (any arrangement is "valid") + +--- + +## Pattern 2: Slots / render children + +A single component that accepts content through specific slots. + +Use when: +- The component has one or two specific insertion points +- Compound components feel like overkill + +```jsx +<Modal + title="Confirm action" + footer={<Button>Confirm</Button>} +> + <p>Are you sure?</p> +</Modal> +``` + +In Web Components: `<slot name="title">`. In Vue: named slots. In React: prop-as-element. + +Pros: +- Smaller API surface than compound components +- Clear insertion points + +Cons: +- Less flexible if the consumer wants to vary arrangement + +--- + +## Pattern 3: Render props / function as children + +The component provides state, the consumer provides UI. + +Use when: +- The component has reusable behavior (e.g., dropdown logic) +- Multiple visual variations should share the behavior +- Headless component libraries (Radix, Headless UI) use this heavily + +```jsx +<Dropdown> + {({ isOpen, toggle, items }) => ( + <> + <button onClick={toggle}>Menu</button> + {isOpen && <ul>{items.map(item => <li>{item}</li>)}</ul>} + </> + )} +</Dropdown> +``` + +Pros: +- Maximum flexibility +- Behavior and presentation cleanly separated + +Cons: +- Steeper learning curve +- More boilerplate at the call site + +--- + +## Pattern 4: Headless components + +Components that ship behavior and accessibility without prescribing visual style. + +Use when: +- Multiple consumers want different looks +- Accessibility is hard and worth centralizing +- Building a primitive layer + +```jsx +// Headless: behavior + accessibility, no visual style +<Listbox value={selected} onChange={setSelected}> + <Listbox.Button>{selected}</Listbox.Button> + <Listbox.Options> + {options.map(option => ( + <Listbox.Option key={option} value={option}>{option}</Listbox.Option> + ))} + </Listbox.Options> +</Listbox> +``` + +The consumer styles each part however they want. + +Pros: +- Reusable across visual styles +- Accessibility hard work centralized + +Cons: +- Consumers must style every part +- Less batteries-included + +--- + +## Pattern 5: Controlled vs uncontrolled + +Two modes: + +Uncontrolled (component owns its state): +```jsx +<Input defaultValue="initial" onChange={handleChange} /> +``` + +Controlled (consumer owns the state): +```jsx +<Input value={value} onChange={setValue} /> +``` + +Pattern: Support both. Uncontrolled is convenient for simple cases. Controlled is required when state needs to live in the parent. + +```jsx +function Input({ value, defaultValue, onChange, ...props }) { + const isControlled = value !== undefined; + const [internalValue, setInternalValue] = useState(defaultValue); + const currentValue = isControlled ? value : internalValue; + + const handleChange = (e) => { + if (!isControlled) setInternalValue(e.target.value); + onChange?.(e); + }; + + return <input value={currentValue} onChange={handleChange} {...props} />; +} +``` + +Convention: `value` for controlled, `defaultValue` for uncontrolled. Documented behavior when both are provided (typically: warn, treat as controlled). + +--- + +## Pattern 6: Polymorphic components (the `as` prop) + +A component that can render as different HTML elements while preserving its API. + +Use when: +- Visual style should apply to multiple HTML elements (e.g., a Heading that could be h1, h2, etc.) +- Consumers occasionally need to override the rendered element + +```jsx +<Text as="h1">Page title</Text> +<Text as="span">Inline text</Text> +<Text as="a" href="/path">Link</Text> +``` + +Pros: +- Style and semantics decoupled when needed + +Cons: +- Type complexity (TypeScript polymorphic types are non-trivial) +- Easy to misuse (rendering an h1 styled as a span breaks structure) + +Use sparingly. The default rendered element should fit most cases. + +--- + +## Pattern 7: Context for cross-component state + +When sub-components in a tree need shared state, use context. Don't drill props. + +```jsx +const TabContext = createContext(); + +function Tabs({ children, defaultIndex = 0 }) { + const [activeIndex, setActiveIndex] = useState(defaultIndex); + return ( + <TabContext.Provider value={{ activeIndex, setActiveIndex }}> + {children} + </TabContext.Provider> + ); +} + +function Tab({ index, children }) { + const { activeIndex, setActiveIndex } = useContext(TabContext); + return ( + <button + role="tab" + aria-selected={activeIndex === index} + onClick={() => setActiveIndex(index)} + > + {children} + </button> + ); +} +``` + +Convention: Context tied to a specific component family. Don't overload one context across unrelated components. + +--- + +## Pattern 8: forwardRef and ref forwarding + +Components should pass refs through to their underlying DOM element when reasonable. + +```jsx +const Button = forwardRef(function Button({ children, ...props }, ref) { + return <button ref={ref} {...props}>{children}</button>; +}); +``` + +Why: +- Consumers need DOM access (focus, measure, scroll) +- Form libraries need refs to inputs +- Animation libraries need refs to elements + +Convention: Forward refs on any component that wraps a single primary DOM element. Document where the ref attaches. + +--- + +## Pattern 9: Variant / size enums via discriminated unions + +Use string enums for variant and size props. + +```typescript +type ButtonProps = { + variant?: 'primary' \| 'secondary' \| 'ghost' \| 'danger'; + size?: 'sm' \| 'md' \| 'lg'; + // ... +}; +``` + +Why: +- Self-documenting +- Type-safe +- Consumers see options via autocomplete + +Anti-pattern: Boolean variant props. + +```typescript +// Bad +type ButtonProps = { + primary?: boolean; + secondary?: boolean; + danger?: boolean; +}; +``` + +Boolean variants permit invalid combinations (`primary={true} danger={true}`). + +--- + +## Pattern 10: Event handler conventions + +\| Convention \| Example \| +\|---\|---\| +\| `onX` for events \| `onClick`, `onChange`, `onClose` \| +\| `onXChange` for state changes \| `onValueChange`, `onOpenChange` \| +\| Pass event object as first arg \| `onClick(event)` \| +\| For state changes, pass new state as first arg \| `onOpenChange(isOpen)` \| + +Anti-patterns: +- `handleClick` as a prop name (consumer confusion - this is the implementation, not the API) +- `change` instead of `onChange` +- Passing transformed event without the original + +--- + +## API audit checklist + +Before shipping a component: + +- [ ] Default behavior is reasonable with zero props +- [ ] Variant prop uses string enum, not booleans +- [ ] Size prop uses string enum, not numbers (when sizes are constrained) +- [ ] Event handlers use `onX` convention +- [ ] Required props are minimal (ideally zero, often one) +- [ ] Optional props document defaults +- [ ] Component is forwardable (refs work) +- [ ] Polymorphic only where genuinely useful +- [ ] No boolean explosion (more than 5 booleans is a smell) +- [ ] State is controllable when it makes sense (controlled/uncontrolled support) +- [ ] Accessibility props are first-class (`aria-label`, `aria-describedby`, etc.) +- [ ] className/style override pattern documented +- [ ] All variants have visual examples in docs +- [ ] All states have visual examples in docs +- [ ] Keyboard interactions documented + +If any item fails, the API needs another pass before ship. diff --git a/skills/frontend-component-build/references/component-spec-template.md b/skills/frontend-component-build/references/component-spec-template.md new file mode 100644 index 0000000..bae7d3f --- /dev/null +++ b/skills/frontend-component-build/references/component-spec-template.md @@ -0,0 +1,250 @@ +# Component Spec Template + +Fillable template for documenting a component before writing code. The cost of writing a spec is small. The cost of building, shipping, and rebuilding a component because the API was wrong is large. + +Fill every section. If a section is "N/A", say why. + +--- + +## Identity + +Component name: [PascalCase. e.g., `Button`, `DatePicker`, `DropdownMenu`] +Layer: [Primitive / Pattern / Template] +Status: [Proposal / Draft / In review / Production] +Owner: [Name] +Related components: [Sibling components, parent components, components this composes or replaces] + +--- + +## Purpose + +One paragraph. What this component does, who uses it, and why it exists at all. + +If you cannot articulate why this is a system component (vs a one-off in product code), it should not be in the system yet. + +> [Purpose statement] + +--- + +## Use cases + +List the real, concrete use cases this component must serve. If the list is empty or hypothetical, the component is premature. + +1. [Specific scenario, e.g., "Submit a form on the checkout page"] +2. [Specific scenario] +3. [Specific scenario] + +### Anti-use cases + +When NOT to use this component. Helps consumers pick the right primitive. + +- [Scenario, e.g., "Triggering navigation - use `Link` instead"] +- [Scenario] + +--- + +## API + +### Props + +\| Prop \| Type \| Default \| Required \| Description \| +\|---\|---\|---\|---\|---\| +\| `variant` \| `'primary' \\| 'secondary' \\| 'ghost'` \| `'primary'` \| No \| Visual treatment \| +\| `size` \| `'sm' \\| 'md' \\| 'lg'` \| `'md'` \| No \| \| +\| `disabled` \| `boolean` \| `false` \| No \| \| +\| `loading` \| `boolean` \| `false` \| No \| Shows spinner; auto-disables interaction \| +\| `leadingIcon` \| `ReactNode` \| - \| No \| \| +\| `trailingIcon` \| `ReactNode` \| - \| No \| \| +\| `as` \| `ElementType` \| `'button'` \| No \| Polymorphic root element \| +\| `onClick` \| `(e: MouseEvent) => void` \| - \| No \| \| +\| `children` \| `ReactNode` \| - \| Yes \| Visible label \| +\| (etc.) \| \| \| \| \| + +### Slots / composition + +If this is a compound component, describe each sub-component and its role. + +\| Slot / sub-component \| Purpose \| Required \| +\|---\|---\|---\| +\| `Card.Header` \| Title and optional icon \| No \| +\| `Card.Body` \| Main content \| Yes \| +\| `Card.Footer` \| Actions \| No \| + +### Events + +\| Event \| Payload \| When fires \| +\|---\|---\|---\| +\| `onChange` \| `{ value: string }` \| User changes value, on blur or on each keystroke depending on `mode` prop \| + +### Refs / imperative handles + +If the component exposes imperative methods, list them. + +\| Method \| Signature \| Purpose \| +\|---\|---\|---\| +\| `focus` \| `() => void` \| Move focus to the component's primary interactive element \| + +--- + +## States + +List every state the component can be in. Each state needs a visual treatment. + +\| State \| Visual \| Trigger \| +\|---\|---\|---\| +\| Default \| \| Initial render \| +\| Hover \| \| Pointer over (non-touch) \| +\| Focus \| \| Keyboard focus \| +\| Active / pressed \| \| Mouse down or `Enter`/`Space` \| +\| Disabled \| \| `disabled` prop true \| +\| Loading \| \| `loading` prop true \| +\| Error \| \| Error context (validation failure, API error) \| +\| Empty / no data \| \| (For data-bearing components) \| +\| Read-only \| \| (For form inputs) \| + +### State combinations + +Some states combine. Document the priority rules. + +- Loading + disabled: spinner shows, looks disabled. +- Error + focus: focus ring shows in error color. +- (etc.) + +--- + +## Accessibility + +This section is non-negotiable. Every interactive component has an accessibility section. If the component is decorative, say so explicitly. + +### Role and semantics + +- Native element: [What HTML element is the root, e.g., `<button>`, `<input type="text">`] +- ARIA role (if not native): [e.g., `role="dialog"`] +- Label requirement: [How is the accessible name set? `aria-label`, visible label, etc.] + +### Keyboard interaction + +\| Key \| Action \| +\|---\|---\| +\| `Tab` \| \| +\| `Shift + Tab` \| \| +\| `Enter` \| \| +\| `Space` \| \| +\| `Escape` \| \| +\| `Arrow keys` \| \| +\| `Home / End` \| \| + +### Screen reader behavior + +- What is announced on focus? +- What is announced on state change (loading, error)? +- Are there `aria-live` regions for status updates? + +### Focus management + +- Where does focus go on mount? On unmount? +- Is focus trapped (e.g., modals)? +- Is focus visible (focus ring)? + +### Color contrast + +Confirm WCAG AA at minimum (3:1 for non-text, 4.5:1 for body text, 3:1 for large text). Note any state where contrast is at risk (disabled state often fails AA on purpose; document the choice). + +### Touch target size + +- Minimum 44x44px on mobile (WCAG 2.5.5). +- Document if smaller and why. + +--- + +## Edge cases + +The cases that always come up after launch. Document them now. + +- [ ] Empty content: What if `children` is empty? +- [ ] Very long content: What if the label is 200 characters? Truncate, wrap, or expand? +- [ ] No data: For data-bearing components, what does the empty state look like? +- [ ] Loading: What does the loading state look like? Skeleton? Spinner? Disabled? +- [ ] Error: Inline error? Toast? Both? +- [ ] Disabled with tooltip: A disabled `<button>` cannot receive focus, so a tooltip explaining why it is disabled needs special handling. +- [ ] Right-to-left: Does the layout flip correctly? +- [ ] High zoom (200%): Does the layout hold? +- [ ] Dark mode: Are tokens used so dark mode works automatically? +- [ ] Reduced motion: Are animations disabled when `prefers-reduced-motion: reduce`? + +--- + +## Variants and customization + +### Built-in variants + +What variants ship out of the box (`size`, `variant`, etc.). Document each. + +### Customization API + +How can consumers customize without forking? `className` pass-through? Style props? Slots? CSS custom properties? + +### What is NOT customizable + +Be explicit about what consumers cannot override. This is the system's stance, not a bug. + +--- + +## Internationalization + +- [ ] Text is via prop or children (not hardcoded) +- [ ] Plural and count formatting uses `Intl.PluralRules` +- [ ] Date / time formatting uses `Intl.DateTimeFormat` +- [ ] Layout works in RTL (logical properties: `margin-inline-start`, `padding-inline-end`) +- [ ] Bidirectional text (mixed LTR / RTL strings) handled + +--- + +## Performance + +- Bundle weight target: [KB compressed] +- Render cost: [Should be cheap. If expensive, document why.] +- Re-render risk: [Memoize? Stable callbacks expected from consumers?] +- Lazy-loadable: [Yes / no] + +--- + +## Testing + +### Unit tests + +- [ ] Renders default state +- [ ] Renders all variants +- [ ] Fires events on interaction +- [ ] Respects disabled / loading state +- [ ] Forwards refs + +### Accessibility tests + +- [ ] Axe passes on default state +- [ ] Axe passes on each variant +- [ ] Keyboard navigation tested +- [ ] Screen reader pass (manual or automated) + +### Visual regression tests + +- [ ] Each variant snapshot +- [ ] Each state snapshot +- [ ] RTL snapshot +- [ ] Dark mode snapshot + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Sign-off + +- Design approved: [Name, date] +- Engineering approved: [Name, date] +- Accessibility reviewed: [Name, date] +- Ready for production: [Date] diff --git a/skills/funnel-flow-architecture/SKILL.md b/skills/funnel-flow-architecture/SKILL.md new file mode 100644 index 0000000..ffa49be --- /dev/null +++ b/skills/funnel-flow-architecture/SKILL.md @@ -0,0 +1,306 @@ +--- +name: funnel-flow-architecture +description: "Architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. Honest about silo-funnels (every tool standalone), kitchen-sink-funnels (every audience squeezed through one path), and matched-funnels (architecture matched to audience-and-stage) patterns. Triggers on funnel design, conversion architecture, marketing funnel, growth funnel, lifecycle architecture, nurture sequence design, multi-tool funnel orchestration. Also triggers when the team's growth tools are working individually but not together, when audience segments share one nurture path, or when a funnel is being architected from scratch." +category: growth-tooling +catalog_summary: "Architecting cross-tool conversion flows that match audience and stage. Distinguishes silo-funnels (every tool standalone) from kitchen-sink-funnels (every audience squeezed through one path) from matched-funnels (architecture matched to audience-and-stage)" +display_order: 6 +--- + +# Funnel Flow Architecture + +A senior growth practitioner's playbook for architecting cross-tool conversion flows that match audience and stage. Landing page to lead magnet to nurture sequence to offer to advanced funnels. The discipline of building a funnel architecture, not just collecting tools. + +Most growth programs accumulate tools without architecture. A chatbot, a calculator, a quiz, a lead magnet, a newsletter signup, a demo CTA. Each tool works individually; none of them work together. Visitors hit one tool, leave, and never enter the broader nurture sequence. The funnel is a collection of orphans. + +The growth programs that compound do something different. They architect the funnel deliberately. Different entry points lead to different nurture sequences. Different stages get different CTAs. Different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. + +This skill is the architecture skill that orchestrates the other 5 growth-tooling skills (lead-magnet-design, calculator-design, quiz-and-assessment-design, multi-step-form-design, chatbot-flow-design). Where those skills zoom into specific tool design, this skill zooms out to the cross-tool architecture that determines whether the tools compound. + +The voice is the senior growth practitioner who has watched funnels architecture compound and watched siloed funnel collections produce engagement metrics with no business impact. Practical, opinionated about the difference between collecting tools and architecting funnels, willing to call out when a team's growth program needs architecture rather than another tool. + +When to use this skill: architecting a funnel from scratch, auditing a growth program where tools work individually but conversion is flat, designing the cross-tool data flow that captures audience signal across touchpoints, or deciding which segments warrant which funnel paths. + +--- + +## What this skill covers + +This skill spans cross-tool funnel architecture. The growth-tooling distinctions: + +- `lead-magnet-design`, `calculator-design`, `quiz-and-assessment-design`, `multi-step-form-design`, `chatbot-flow-design` are tools that LIVE INSIDE the funnel architecture this skill designs. They zoom into specific tool design. +- `content-distribution` covers how content reaches audiences. This skill is what audiences DO once they reach content. +- `experiment-design` validates funnel changes. This skill designs the architecture; experiment-design tests it. +- `landing-page-copy` covers page-level copy. This skill is the cross-page architecture. +- `funnel-flow-architecture` (this skill) is audience-and-stage segmentation, entry-point architecture, tool-to-funnel mapping, nurture sequence architecture, cross-tool data flow. + +The audience: growth marketing leads, product marketing leads, marketing directors at SMB and mid-market companies, agencies running funnel architecture for clients, founders architecting growth programs from scratch. + +Out of scope: specific tool design (covered by the 5 sister growth-tooling skills); content distribution mechanics (covered by `content-distribution`); A/B testing methodology (covered by `experiment-design`); page-level copy (covered by `landing-page-copy`). + +--- + +## Silo-funnels vs kitchen-sink-funnels vs matched-funnels + +The keystone framing. + +Silo-funnels. Each tool (chatbot, calculator, lead magnet, quiz) lives independently. No coordinated flow; users hit one tool, leave, never enter the broader nurture sequence. Tools as orphans. Cost: each tool's investment does not compound; the audience that interacts with one tool is not connected to any next step; the team has tools but no architecture. + +Kitchen-sink-funnels. One funnel for everyone. Same nurture sequence regardless of audience or entry point. SMB and enterprise get the same emails. New visitors and bottom-of-funnel get the same CTAs. Conversion rates regress to mediocre on every segment. Cost: the funnel optimizes for the average; no segment is well-served; downstream conversion is uniformly low. + +Matched-funnels. Funnel architecture matches audience and stage. Different entry points lead to different nurture sequences; different stages get different CTAs; different tools serve different segments. Each tool is part of a larger architecture, not a standalone artifact. Cost: the design effort upfront is significant; the maintenance is real; downstream conversion is meaningfully higher per segment. + +The litmus test. Pick a recent visitor to the site. Can the team explain which segment the visitor falls into, which entry point they used, which nurture sequence they are in, and what the next-step CTA they will see is? If yes, the funnel is matched. If the answer is "they got the same flow as everyone else," the funnel is kitchen-sink. If the answer is "they used the calculator but I do not know what comes next," the funnel is silo. + +--- + +## Audience and stage segmentation + +The foundation. + +The principle. Funnel architecture starts with audience and stage segmentation. Without segmentation, every visitor goes through the same path; the funnel cannot match. + +Audience dimensions. + +- Company size or buyer type. Solo, SMB, mid-market, enterprise. +- Industry or vertical. Healthcare, finance, retail, technology. +- Use case. What the audience is trying to accomplish. +- Role. Founder, PM, marketer, executive, IC. +- Source. Paid traffic, organic, referral, partner. + +Stage dimensions. + +- Awareness. Just discovered the brand or the topic. +- Consideration. Evaluating options actively. +- Decision. Choosing between specific options. +- Customer. Already a customer; ongoing relationship. + +The intersection. Audience x stage produces the matrix the funnel architecture serves. An enterprise PM in consideration is a different segment from an SMB founder in awareness; each warrants a different path. + +Segmentation discipline. Start with 3-5 audiences and 3 stages. 9-15 cells in the matrix. Some cells may share paths; some may have unique paths. The discipline is naming the segments deliberately rather than treating "everyone" as the audience. + +Detail in [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md). + +--- + +## Entry-point architecture + +How visitors land vs how they're routed. + +The principle. The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). + +Common entry points. + +- Paid landing page. Visitor arrives via ad; high intent; specific to the ad's promise. +- Organic content page. Visitor arrives via search or content discovery; awareness or research stage. +- Direct. Visitor arrives by typing URL or via bookmark; often returning. +- Referral. Visitor arrives via partner or word-of-mouth; warmer than paid. +- Social. Visitor arrives via social post; awareness or interest. +- Tool entry. Visitor arrives via a calculator, quiz, or chatbot directly. + +Entry-point routing. + +- Each entry point has expected segments and stages. +- The first action available at the entry point should match likely segment and stage. +- Different entry points may route to different downstream tools and sequences. + +Worked example. A visitor arriving via a paid ad about "B2B SaaS pricing" is likely in consideration stage looking for pricing information. The landing page should serve that need (clear pricing, comparison, calculator); the next-step offer should match consideration (demo, talk to sales). Same visitor arriving via an organic blog post about "B2B SaaS pricing strategy" is likely in awareness stage; the landing page should serve education (depth on pricing strategy); the next-step offer should match awareness (subscribe to content, get the framework). + +Detail in [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md). + +--- + +## Tool-to-funnel mapping + +Which tools serve which entry points. + +The principle. Each tool in the growth toolkit has a place in the funnel architecture. The tool serves specific segments at specific stages from specific entry points. + +Mapping examples. + +- Lead magnet. Often serves awareness-to-consideration transition. Captured email leads to nurture sequence. +- Calculator. Often serves consideration stage. The audience evaluating options uses the calculator to defend a specific decision. +- Quiz. Can serve any stage depending on design. Awareness quizzes for content marketing; consideration quizzes for product matching; decision quizzes for plan selection. +- Multi-step form. Often serves decision or qualification stage. The form captures qualified intent. +- Chatbot. Cross-cutting. Can serve any stage with intent recognition routing. + +The tool-segment fit. Tools should serve segments that match their value proposition. A calculator for solo founders may need different inputs and outputs than a calculator for enterprise buyers; the same calculator cannot serve both well. + +The portfolio approach. A team often has multiple tools serving different segments. The architecture maps each tool to its specific segments and stages. + +Detail in [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md). + +--- + +## Nurture sequence architecture + +Per-segment, per-stage. + +The principle. Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. + +Sequence variation by stage. + +- Awareness sequence. Educational; broad value; brand-building. Soft offers if any. +- Consideration sequence. Comparative; specific value; product-fit signals. Demo or trial CTAs. +- Decision sequence. Confidence-building; risk-reversal; urgency cues. Direct purchase or commitment CTAs. + +Sequence variation by audience. + +- Enterprise audiences get different content (white papers, case studies, ROI analysis) than SMB audiences (templates, quick wins, peer testimonials). +- Different roles get different framing (founder content emphasizes business outcomes; IC content emphasizes practitioner depth). +- Different industries get different examples and language. + +The kitchen-sink sequence failure. One sequence for everyone. Generic enough to send to all; specific enough for none. Conversion uniformly mediocre. + +The matched sequence win. Sequence specific to segment-and-stage. The audience perceives the brand as understanding their situation; conversion compounds. + +Detail in [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md). + +--- + +## Cross-tool data flow + +Capturing context from tool to tool. + +The principle. When the audience moves from one tool to another in the funnel, the audience signal travels with them. The chatbot conversation context informs the calculator's defaults; the calculator inputs inform the lead-magnet sequence; the quiz result informs the demo-request prefill. + +Cross-tool data flow patterns. + +- Identity threading. When the audience is identified at any point (logged in, opted in, identified by email), their identity carries forward across tools. +- Context capture. Inputs from one tool (calculator values, quiz results, form submissions) feed into the next interaction. +- Segment tagging. Each interaction tags the audience with segment information that informs future routing. +- Sequence-tool integration. Email sequences include links to specific tools matched to the audience's segment. + +The siloed-tool failure. Each tool captures its own data; nothing flows between them. The chatbot conversation is forgotten when the user opens the calculator; the calculator inputs are forgotten when the user opens the lead magnet. + +The integrated-funnel win. Data flows. The audience experiences continuity; the brand can match content and offers to the audience's specific journey. + +Detail in [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md). + +--- + +## Funnel measurement + +What to measure, what is noise. + +The principle. Funnel measurement should reveal architecture quality, not just tool quality. + +Architecture-level metrics. + +- Cross-tool conversion. What percentage of audience that hits tool A then engages with tool B? +- Sequence-to-tool conversion. What percentage of nurture sequence subscribers engage with downstream tools? +- Segment-level downstream conversion. Per-segment conversion to the program's main goal (trial, demo, purchase). +- Funnel-stage progression. What percentage of audience moves from awareness to consideration to decision over time? + +Tool-level metrics. + +- Conversion rate per tool (covered by each tool's skill). + +Architecture-level vs tool-level. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. Both matter; architecture is often the missing measurement. + +Detail in [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md). + +--- + +## Funnel iteration discipline + +When to redesign, when to refine. + +The principle. Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +Refine when: + +- Specific tools are underperforming relative to baseline. +- Specific segments have lower conversion than peer segments. +- Specific transitions in the funnel are producing drop-off. +- Sequence engagement is declining for specific cohorts. + +Redesign when: + +- Audience composition has fundamentally shifted. +- Product or service strategy has changed. +- Competitive landscape has shifted significantly. +- Multiple refine cycles have not produced expected results, suggesting architectural issues. + +Continuous-redesign trap. Teams that constantly redesign never benefit from architectural compounding. Each redesign resets the learning; nothing accumulates. + +Frozen-architecture trap. Teams that never iterate watch their architecture decay as audiences and markets evolve. + +The middle ground. Refine continuously; redesign infrequently and deliberately. + +Detail in [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md). + +--- + +## Architecture anti-patterns + +Patterns that look like funnel architecture but degrade conversion. + +The silo-funnels pattern. Tools as orphans; no architecture. + +The kitchen-sink-funnels pattern. One funnel for everyone. + +The over-segmented funnel. So many segments that maintenance is impossible; segments are not actually distinguishable. + +The unmaintained-funnel. Architecture designed once, never reviewed; decay accumulates. + +The tool-driven-architecture. Architecture organized around tools rather than around audience-and-stage; each tool gets its own funnel regardless of whether that serves the audience. + +The metric-blind-architecture. Architecture without measurement; cannot diagnose where it works and where it does not. + +The single-tool-funnel. Architecture that depends on one tool (just the calculator, just the chatbot); no resilience if that tool underperforms. + +The hand-off-broken-funnel. Tools work individually but the transitions between them break. + +Detail in [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md). + +--- + +## The framework: 12 considerations for funnel flow architecture + +When designing or auditing a funnel architecture, walk these 12 considerations. + +1. Matched-funnels, not silo or kitchen-sink. Architecture matches audience-and-stage; each tool is part of the architecture, not a standalone artifact. +2. Audience and stage segmentation defined. 3-5 audiences x 3 stages; the matrix the architecture serves. +3. Entry-point architecture mapped. Each entry point routed to expected segments and stages. +4. Tool-to-funnel mapping documented. Each tool serves specific segments at specific stages. +5. Nurture sequence architecture per segment. Sequences vary by audience and stage; not one sequence for everyone. +6. Cross-tool data flow integrated. Context travels across tools; the audience experiences continuity. +7. Architecture-level metrics tracked. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion. +8. Funnel iteration discipline. Refine continuously; redesign deliberately; avoid both extremes. +9. Tool portfolio balanced. Multiple tools serving different segments; not over-reliant on any single tool. +10. Audience-fit honest. The architecture serves the segments the brand can actually serve; out-of-fit audiences are filtered or routed elsewhere. +11. Maintenance ownership clear. Someone owns the architecture; quarterly review is calendared. +12. Expansion plan defined. When adding new tools, the architecture says where they fit; new tools earn their place rather than being added decoratively. + +The output of the framework is a funnel architecture that compounds over time, matches audience-and-stage segments, integrates tool data flows, and produces measurable downstream conversion. + +--- + +## Reference files + +- [`references/audience-and-stage-segmentation.md`](references/audience-and-stage-segmentation.md) - The foundation. Audience dimensions, stage dimensions, the intersection matrix. +- [`references/entry-point-architecture-patterns.md`](references/entry-point-architecture-patterns.md) - How visitors land vs how they're routed. Common entry points and their routing. +- [`references/tool-to-funnel-mapping.md`](references/tool-to-funnel-mapping.md) - Which tools serve which entry points and segments. +- [`references/nurture-sequence-architecture.md`](references/nurture-sequence-architecture.md) - Per-segment, per-stage sequence variation. The matched sequence win. +- [`references/cross-tool-data-flow-patterns.md`](references/cross-tool-data-flow-patterns.md) - Identity threading, context capture, segment tagging, sequence-tool integration. +- [`references/funnel-measurement-patterns.md`](references/funnel-measurement-patterns.md) - Architecture-level vs tool-level metrics. What to measure, what is noise. +- [`references/funnel-iteration-discipline.md`](references/funnel-iteration-discipline.md) - When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. +- [`references/architecture-anti-patterns.md`](references/architecture-anti-patterns.md) - The patterns that look like funnel architecture but degrade conversion. +- [`references/common-funnel-architecture-failures.md`](references/common-funnel-architecture-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: funnels are architecture, not collections + +The growth programs that compound are the ones that architect their funnels deliberately. Not collect tools. Not optimize one-tool-at-a-time. Architect. + +The architecture is the difference between tools that produce engagement and a funnel that produces business outcomes. The chatbot, the calculator, the quiz, the lead magnet, the multi-step form: each one is a tool. None of them are a funnel. The funnel is the architecture that makes them work together. + +That is the bar. Below the bar are silo-funnels (tools as orphans) and kitchen-sink-funnels (one path for everyone). Above the bar are matched-funnels where audience-and-stage segmentation drives entry-point routing, tool-to-funnel mapping, nurture sequence design, cross-tool data flow, and architecture-level measurement. + +## Closing: funnels earn investment when they compose + +Each tool in the growth toolkit costs investment to build and maintain. The investment compounds when the tools compose; the investment dilutes when the tools sit in silos. Architecture is the discipline of composition. + +The compounding mechanism. A visitor arrives. The architecture routes them based on entry point and observable signals. The first tool they encounter serves their segment-and-stage. The data they generate informs the next tool they encounter. The sequence they enter matches their context. Each interaction deepens the brand's understanding of the audience; each tool's contribution compounds with the others. + +When in doubt, ask: does each tool in the program serve a defined segment-and-stage, do the tools share data and context, can the team explain the architecture in one diagram, and does the team measure architecture-level outcomes (not just tool-level metrics)? If yes to all of those, the funnel is real architecture. If no to any, the gap is where the program's tools are failing to compose. diff --git a/skills/funnel-flow-architecture/references/architecture-anti-patterns.md b/skills/funnel-flow-architecture/references/architecture-anti-patterns.md new file mode 100644 index 0000000..6595f7a --- /dev/null +++ b/skills/funnel-flow-architecture/references/architecture-anti-patterns.md @@ -0,0 +1,198 @@ +# Architecture anti-patterns + +The patterns that look like funnel architecture but degrade conversion. Anti-patterns are easy to ship; the cost shows up in downstream conversion, lead quality, and brand reputation over time. + +--- + +## The silo-funnels pattern + +The pattern. Tools as orphans. No coordinated flow. + +The signal. Each tool's metrics look fine individually; cross-tool metrics non-existent or near-zero. Downstream conversion does not match the sum of tool conversions. + +The cost. Each tool's investment does not compound. The audience that interacts with one tool is not connected to any next step. The team has tools but no architecture. + +The cure. Add cross-tool data flow and explicit funnel architecture. Detail in `references/cross-tool-data-flow-patterns.md` and the broader skill. + +--- + +## The kitchen-sink-funnels pattern + +The pattern. One funnel for everyone. Same nurture sequence regardless of audience or entry point. + +The signal. Conversion rates regress to mediocre on every segment. No segment is well-served. + +The cost. The funnel optimizes for the average; downstream conversion is uniformly low. + +The cure. Segment-and-stage architecture. Different paths for different cells in the matrix. Detail in `references/audience-and-stage-segmentation.md` and `references/nurture-sequence-architecture.md`. + +--- + +## The over-segmented funnel + +The pattern. So many segments that maintenance is impossible. 60 cells in the matrix; 60 distinct paths; nobody can keep up. + +The signal. Specific paths get little attention; maintenance backlog grows; specific cells are theoretical with no real visitors. + +The cost. The architecture exists on paper but not in execution. Tools and sequences for theoretical cells cost effort without producing value. + +The cure. Reduce to 9-15 cells. Start with the minimum viable matrix; expand only when data justifies. Detail in `references/audience-and-stage-segmentation.md`. + +--- + +## The unmaintained-funnel + +The pattern. Architecture designed once, never reviewed. Decay accumulates. + +The signal. Conversion declines slowly; tools age; sequences go stale; segments shift; the architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; the brand falls behind. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## The tool-driven-architecture + +The pattern. Architecture organized around tools rather than around audience-and-stage. Each tool gets its own funnel regardless of whether that serves the audience. + +The signal. The site has many tool-specific landing pages; users navigate to tools rather than tools serving users; the architecture is organized for the team, not the audience. + +The cost. Audiences cannot find what they need; tools cannibalize each other; the architecture cannot scale because each tool is its own funnel. + +The cure. Reorganize around audience-and-stage. The matrix drives the architecture; tools serve the matrix. + +--- + +## The metric-blind-architecture + +The pattern. Architecture without measurement. Cannot diagnose where it works and where it does not. + +The signal. Decisions made on intuition; no data to validate; iteration is guesswork. + +The cost. The architecture cannot improve through measurement; refinement is random; redesign happens reactively. + +The cure. Architecture-level metrics. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## The single-tool-funnel + +The pattern. Architecture that depends on one tool. Just the calculator. Just the chatbot. No resilience if that tool underperforms. + +The signal. The tool's quarterly performance dictates overall funnel performance. A bad month for the tool is a bad month for the funnel. + +The cost. The architecture is fragile. Tool failures cascade; redesigns of the central tool are high-risk. + +The cure. Portfolio approach. Multiple tools serving different segments. The architecture's resilience comes from diversification. + +--- + +## The hand-off-broken-funnel + +The pattern. Tools work individually but the transitions between them break. + +The signal. Each tool's metrics look fine; cross-tool conversion is low. The architecture's transitions are silently failing. + +The cost. The audience experiences the funnel as disconnected. Downstream conversion suffers because the bridges between tools are broken. + +The cure. Audit transitions. Cross-tool data flow. Sequence-tool integration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## The continuous-redesign funnel + +The pattern. Architecture redesigned every quarter. Each iteration starts over. + +The signal. Conversion does not improve over time. Each redesign resets the learning. Tools never reach maturity. + +The cost. Investment dilutes across redesigns. Compounding does not happen. + +The cure. Refine continuously; redesign infrequently and deliberately. Detail in `references/funnel-iteration-discipline.md` (continuous-redesign trap). + +--- + +## The frozen-architecture funnel + +The pattern. Architecture designed once; never iterated; treated as finished. + +The signal. Conversion declines slowly; tools and sequences feel dated; segments no longer match the audience. + +The cost. The architecture's value erodes; the brand becomes uncompetitive. + +The cure. Set refinement cadences. Quarterly audits. Detail in `references/funnel-iteration-discipline.md` (frozen-architecture trap). + +--- + +## The vanity-metric architecture + +The pattern. Architecture measured by surface metrics (tool engagement, total visitors, email signups) without measuring downstream outcomes. + +The signal. Metrics report looks healthy; business outcomes do not match. + +The cost. The team optimizes for the wrong metrics; the architecture appears successful while underperforming on what matters. + +The cure. Measure downstream conversion. Per-segment downstream conversion. Architecture-level metrics rather than tool-level activity. + +--- + +## The over-personalized funnel + +The pattern. Architecture designed for personalization the team cannot actually deliver. Many entry points; many sequences; many tools; team capacity exceeded. + +The signal. Personalization in design; generic in execution. Specific paths exist on paper; default to generic in practice. + +The cost. The team built complexity that does not get used. Maintenance burden without payoff. + +The cure. Match architecture complexity to team capacity. Start simple; add personalization where it produces meaningful lift; do not personalize for its own sake. + +--- + +## The under-personalized funnel + +The pattern. Architecture treats every visitor the same when meaningful personalization would lift conversion. + +The signal. Specific segments underperform; the audience's actual differences are not reflected in the funnel. + +The cost. Conversion stays at the average; no segment exceeds. + +The cure. Add personalization where data shows it would help. Start with segment-level differentiation; refine over time. + +--- + +## The orphan-tool architecture + +The pattern. Tools added to the funnel without explicit segment-and-stage assignment. Each new tool exists; no architecture says where it fits. + +The signal. The funnel's tool count grows; the architecture's clarity does not. + +The cost. Tools compete for the same audience; users see overlapping options; conversion fragments. + +The cure. Each tool earns its place. Architecture documents which segments and stages the tool serves. New tools are added with explicit mapping. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of the architecture, looking specifically for these anti-patterns. + +Audit questions. + +- Do the tools work together (anti-pattern check: silo, hand-off-broken)? +- Is there segment-and-stage architecture (anti-pattern check: kitchen-sink, tool-driven)? +- Is the matrix maintainable (anti-pattern check: over-segmented, over-personalized)? +- Are tools mapped to specific segments (anti-pattern check: orphan-tool, single-tool, under-personalized)? +- Are architecture-level metrics tracked (anti-pattern check: metric-blind, vanity-metric)? +- Is there iteration discipline (anti-pattern check: continuous-redesign, frozen-architecture, unmaintained)? + +The retire decision. Anti-pattern architectures often warrant redesign. Patching anti-patterns rarely produces a good architecture. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md b/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md new file mode 100644 index 0000000..f2ce571 --- /dev/null +++ b/skills/funnel-flow-architecture/references/audience-and-stage-segmentation.md @@ -0,0 +1,200 @@ +# Audience and stage segmentation + +The foundation. Audience dimensions, stage dimensions, the intersection matrix. + +Funnel architecture starts with audience and stage segmentation. Without it, every visitor goes through the same path; the funnel cannot match. With it, the architecture has a definable map of who the audience is and where they are in their journey. + +--- + +## The segmentation principle + +The funnel cannot be tailored without segments. Segments are the architecture's unit of design. + +The discipline. Define 3-5 audience segments and 3 stages. The intersection produces 9-15 cells; each cell is a potential funnel path. + +The trap. Over-segmenting. Defining 12 audiences x 5 stages produces 60 cells; the team cannot maintain that many distinct paths. Most cells end up sharing paths or being indistinguishable. + +The discipline boundary. Start with the minimum viable segmentation. 3-5 audiences and 3 stages is enough to start. Expand only if the data shows meaningful differentiation that justifies more cells. + +--- + +## Audience dimensions + +The dimensions that distinguish meaningful audience segments. + +Company size or buyer type. Solo founders, SMB (10-50), mid-market (50-500), enterprise (500+). Different sizes have different buying processes, different budgets, different needs. + +Industry or vertical. Healthcare, finance, retail, technology, education. Different industries have different language, regulations, examples, competitors. + +Use case. What the audience is trying to accomplish. "Customer support automation," "sales pipeline management," "content production at scale." + +Role. Founder, PM, marketer, sales lead, executive, IC. Different roles have different perspectives and different content preferences. + +Source or channel. Paid traffic, organic search, content referral, partner referral, direct. Different sources signal different intent and stage. + +Geography or language. Domestic vs international; English-first vs other-language audiences. May warrant different funnels for compliance, currency, or cultural reasons. + +The audience dimensions to use depend on the brand's strategy. Most B2B brands segment primarily by company size and use case; most consumer brands segment by demographic and behavioral attributes. + +--- + +## Stage dimensions + +The dimensions that distinguish where the audience is in their journey. + +Awareness. Just discovered the brand or the topic. Has not yet committed to research or evaluation. The audience is open but uncommitted. + +Content fit: educational, broad value, brand-building. +CTAs that fit: subscribe to content, get a framework, follow. +CTAs that do not fit: book a demo, start a trial, buy now. + +Consideration. Evaluating options actively. Has identified a need; comparing solutions. The audience is engaged but not yet decided. + +Content fit: comparative, specific value, product-fit signals. +CTAs that fit: see a calculator, take a quiz, download a comparison, book a demo. +CTAs that do not fit: just-published-content awareness asks; or hard sell. + +Decision. Choosing between specific options. The audience has narrowed the field; selecting is imminent. + +Content fit: confidence-building, risk-reversal, urgency cues. +CTAs that fit: start a trial, talk to sales, sign up. +CTAs that do not fit: top-of-funnel awareness; long-form education. + +Customer. Already a customer; ongoing relationship. Often left out of growth-funnel architecture even though it matters for retention and expansion. + +Content fit: success-deepening, capability-expanding, community. +CTAs that fit: upgrade, refer, join community, attend event. + +The four stages cover most audiences. Some programs combine awareness-and-consideration or consideration-and-decision into 2-stage models; the principle is the same. + +--- + +## The intersection matrix + +Audience x stage produces the matrix the funnel architecture serves. + +Example matrix for a B2B SaaS company. + +\| Audience \| Awareness \| Consideration \| Decision \| +\|----------\|-----------\|---------------\|----------\| +\| Solo founder \| Path A \| Path B \| Path C \| +\| SMB team \| Path D \| Path E \| Path F \| +\| Mid-market \| Path G \| Path H \| Path I \| +\| Enterprise \| Path J \| Path K \| Path L \| + +12 cells. Some may share paths (Path A and Path D might be similar awareness content for solo and SMB). The matrix is the architecture's map. + +Cell-sharing patterns. + +- Awareness paths often share more than decision paths (broad content can serve multiple audience segments). +- Consideration paths often diverge by audience (the comparison content for enterprise differs significantly from SMB). +- Decision paths almost always diverge (the offer for enterprise is different from SMB). + +The matrix shows where the funnel architecture invests in unique paths and where it shares. + +--- + +## Segmentation discipline + +The discipline boundaries. + +Discipline 1: Define segments before designing paths. Without segments, paths are arbitrary. Always start with the matrix. + +Discipline 2: Name segments specifically. "Solo founder pre-launch" beats "small business." Specific names reflect specific audiences. + +Discipline 3: Validate segments with data. A segment that does not appear in actual audience data is theoretical. Validate against site analytics, sales data, or audience research. + +Discipline 4: Maintain the matrix. Audiences shift; the matrix should be reviewed quarterly. Segments may merge or split over time. + +Discipline 5: Avoid over-segmentation. 60-cell matrices are not maintainable. Start with 9-15 cells; expand only with justification. + +--- + +## Segmentation worked example + +A B2B SaaS analytics platform. + +Audiences (4). + +- Data analysts at SMB companies (50-200 employees). +- Data leaders at mid-market companies (200-1000 employees). +- Engineering leaders at enterprise companies (1000+ employees). +- Solo data practitioners and consultants. + +Stages (3). + +- Awareness (researching the analytics topic). +- Consideration (evaluating analytics platforms). +- Decision (selecting and signing up). + +Matrix (12 cells). + +\| Audience \| Awareness \| Consideration \| Decision \| +\|----------\|-----------\|---------------\|----------\| +\| Data analyst SMB \| Educational content \| Calculator, quiz \| Trial, demo \| +\| Data leader mid-market \| Strategic content \| Comparison, ROI calc \| Demo, custom quote \| +\| Engineering enterprise \| Technical depth \| Technical demo, security \| Custom evaluation \| +\| Solo practitioner \| Practical content \| Self-serve resources \| Free tier signup \| + +Each cell has a defined path. The architecture invests where the cells need unique treatment; shares where the cells can use the same path. + +--- + +## Segmentation maintenance + +Segments decay. + +What decays. + +- Audience definitions that no longer match actual visitors. +- Stage definitions that have shifted as buying processes evolved. +- Cells that have become empty (no visitors fit the segment). +- Cells that have become bloated (too many visitors fit one segment; needs sub-segmentation). + +Maintenance cadence. Quarterly review of the matrix against actual audience data. + +The drift indicator. Sales reports that the funnel-sourced leads do not match expected segments; analytics show segments combining or splitting unexpectedly. + +--- + +## Segmentation and the rest of the architecture + +How segmentation drives the rest of the architecture. + +Entry-point architecture. Each entry point routes to expected segments. The matrix tells the architecture where each entry point's traffic likely lands. + +Tool-to-funnel mapping. Each tool serves specific cells in the matrix. The matrix tells the architecture which tools belong where. + +Nurture sequence architecture. Each cell may have its own sequence (or sequences may be shared across similar cells). The matrix is the sequence design map. + +Cross-tool data flow. As the audience moves through the matrix (awareness to consideration to decision), data flows with them. The matrix tracks the journey. + +Funnel measurement. Per-cell conversion is the architecture-level metric. The matrix is the measurement framework. + +--- + +## Common segmentation failures + +No segmentation. "Everyone" treated as the audience. Funnel cannot match. + +Theoretical segments. Segments defined that do not exist in actual audience data. + +Over-segmentation. 60-cell matrix that the team cannot maintain. + +Under-segmentation. 4-cell matrix when the audience genuinely splits into more meaningful segments. + +Stale segmentation. Matrix designed once; audience shifted; matrix not updated. + +Segments without paths. Matrix defined but no funnel paths designed for the cells; segmentation is decorative. + +Paths without segments. Funnel paths designed without clear segment mapping; treatments are arbitrary. + +--- + +## Methodology-level choices that stay in the public skill + +The segmentation principle and discipline boundaries. Audience dimensions. Stage dimensions. The intersection matrix. Segmentation discipline (5 disciplines). Worked example. Segmentation maintenance. Segmentation and the rest of the architecture. Common failures. + +## Implementation choices that stay internal + +Specific segments for the team's audience. Specific tooling for segment tagging and analysis. The team's matrix maintenance calendar. Specific path designs per cell. These vary by team. diff --git a/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md b/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md new file mode 100644 index 0000000..8f45320 --- /dev/null +++ b/skills/funnel-flow-architecture/references/common-funnel-architecture-failures.md @@ -0,0 +1,179 @@ +# Common funnel architecture failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the funnel is not converting" or "tools work individually but conversion is flat" or "we cannot tell where the funnel is broken." + +--- + +## "Tools work individually; conversion is flat." + +The diagnosis. Silo-funnels pattern. Tools as orphans; no architecture connects them. + +The cure. Add cross-tool data flow; map tools to specific segments; design transitions between tools. Detail in `references/cross-tool-data-flow-patterns.md` and `references/tool-to-funnel-mapping.md`. + +--- + +## "Every audience gets the same nurture sequence." + +The diagnosis. Kitchen-sink-funnels pattern. One sequence for everyone. + +The cure. Segment-and-stage sequences. Different cells in the matrix get different sequences. Detail in `references/nurture-sequence-architecture.md`. + +--- + +## "We have 12 tools and no clear architecture." + +The diagnosis. Tool-driven architecture. Tools accumulated without explicit segment mapping. + +The cure. Build the matrix; map each tool to specific cells; retire tools that do not have a mapping or that compete with better-mapped alternatives. + +--- + +## "Specific segments convert at half the rate of others." + +The diagnosis. Architecture for those segments may be broken. Or the segments may not be served by the current tools and sequences. + +The cure. Audit those segments' funnel paths. Are tools mapped to them? Are sequences designed for them? If not, build for those segments. If yes, refine the existing path. + +--- + +## "We cannot tell which tools or sequences are driving conversion." + +The diagnosis. Architecture-level metrics not tracked. Cannot attribute outcomes to architecture choices. + +The cure. Instrument cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. Detail in `references/funnel-measurement-patterns.md`. + +--- + +## "We redesign every quarter; nothing improves." + +The diagnosis. Continuous-redesign trap. Each redesign resets learning; nothing compounds. + +The cure. Establish "no major redesign for X months" discipline. Refine continuously; redesign deliberately and rarely. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "The funnel was great at launch; now conversion has dropped 40 percent." + +The diagnosis. Frozen-architecture trap. Designed once; never iterated; decay accumulated. + +The cure. Quarterly audit. Refinement cadence. Detail in `references/funnel-iteration-discipline.md`. + +--- + +## "Specific transitions in the funnel have high drop-off." + +The diagnosis. Hand-off-broken pattern. Tools work but the bridges between them break. + +The cure. Audit transitions. Add cross-tool data flow so context travels. Promote downstream tools at upstream tools' exits. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Our chatbot, calculator, and quiz all serve consideration-stage audiences." + +The diagnosis. Tool overlap without differentiation. Three tools competing for the same audience. + +The cure. Differentiate the tools' purposes. Calculator for ROI questions; quiz for product matching; chatbot for FAQ. Or consolidate to fewer tools with clearer roles. + +--- + +## "Sales says quiz-sourced leads, calculator-sourced leads, and lead-magnet-sourced leads are different qualities." + +The diagnosis. Tools may be attracting different segments; the architecture's segmentation is working but the tools are not all matched to high-quality segments. + +The cure. Investigate which tools attract which segments. Optimize tool placement and design for the segments the brand serves best; deprioritize tools that attract low-quality segments. + +--- + +## "We added a new tool last quarter; it does not seem to help conversion." + +The diagnosis. Orphan-tool pattern. Tool added without architecture mapping. + +The cure. Map the new tool to specific segments. Decide where it fits in the matrix. Promote it where it fits; remove it from places it does not. + +--- + +## "Our funnel has 8 stages; visitors only complete 2." + +The diagnosis. Funnel may be over-architected. Too many steps; audience cannot or will not progress through them all. + +The cure. Simplify the funnel. Combine stages; remove unnecessary tools; align the funnel length to the audience's likely journey. + +--- + +## "Cross-tool tracking is broken; we cannot tell who used what." + +The diagnosis. Identity threading or event tracking issue. Architecture's measurement infrastructure is broken. + +The cure. Audit identity threading. Verify event tracking. Fix the infrastructure before further iteration. Detail in `references/cross-tool-data-flow-patterns.md`. + +--- + +## "Audiences arriving from paid traffic and organic traffic perform completely differently." + +The diagnosis. Either entry-point routing is not differentiating, or the funnel paths are not serving paid and organic audiences differently. + +The cure. Different routing for different entry points. Specific landing pages and sequences for paid vs organic. Detail in `references/entry-point-architecture-patterns.md`. + +--- + +## "The team built personas; the funnel does not reflect them." + +The diagnosis. Segments defined but not implemented in the funnel architecture. Decorative segmentation. + +The cure. Map personas to funnel cells. Build paths for the cells. The personas should drive the architecture, not sit in a deck. + +--- + +## "Our sequence-to-trial conversion is high; trial-to-paid is low." + +The diagnosis. Architecture handles funnel up to trial well; the trial-to-paid stage may need its own architecture (or may be a product issue rather than funnel issue). + +The cure. Treat trial-to-paid as its own funnel-stage progression. Build paths for trial users; nurture toward paid conversion. + +--- + +## "We have 15 lead magnets; 3 produce most of the leads." + +The diagnosis. Magnet portfolio not maintained. Most magnets are dead but still on the site. + +The cure. Audit and retire dead magnets. Free capacity for the strong ones. Detail in `lead-magnet-design`. + +--- + +## "We built a fancy architecture; the team cannot maintain it." + +The diagnosis. Over-architecture. Architecture exceeds team capacity. + +The cure. Simplify. Match architecture complexity to team capacity. Expand only when capacity grows. + +--- + +## "Funnel-sourced leads are different from sales-sourced leads." + +The diagnosis. Likely fine. Funnel and direct sales serve different segments and stages. Both can be valuable. + +The action. Track them separately. Optimize each for its specific path. + +--- + +## The pattern across failures + +Most funnel architecture failures fall into one of three patterns. + +Pattern 1: Tools without architecture. Silo, kitchen-sink, tool-driven, orphan-tool. The fix is to add explicit architecture (matrix, mapping, data flow). + +Pattern 2: Architecture without measurement. Metric-blind, vanity-metric, broken tracking. The fix is to instrument architecture-level metrics. + +Pattern 3: Architecture without maintenance. Frozen, decayed, unmaintained. The fix is iteration discipline (refine continuously, redesign rarely). + +The metric pattern: funnel architecture failures often look fine on tool-level metrics. The signal is in cross-tool conversion, segment-level outcomes, and funnel-stage progression. Programs that track only tool metrics keep shipping the same architectural patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (tools-without-architecture, architecture-without-measurement, architecture-without-maintenance). The principle that tool-level metrics alone are insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific architecture-level dashboards. Specific cures the team applies. The team's audit and redesign processes. These vary by team. diff --git a/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md b/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md new file mode 100644 index 0000000..a74f62a --- /dev/null +++ b/skills/funnel-flow-architecture/references/cross-tool-data-flow-patterns.md @@ -0,0 +1,252 @@ +# Cross-tool data flow patterns + +Identity threading, context capture, segment tagging, sequence-tool integration. + +When the audience moves from one tool to another in the funnel, the audience signal travels with them. Done well, cross-tool data flow makes the audience experience continuous and lets the brand match content to the audience's specific journey. Done poorly, every tool starts from scratch and the audience signal is lost. + +--- + +## The continuity principle + +The audience experience should feel continuous across tools. Their interactions in one tool inform their experience in the next. + +The win. A visitor takes a quiz; the quiz tags them as "mid-market mid-funnel." When they later open the calculator, the defaults reflect mid-market context. When they download a lead magnet, the sequence delivered matches the segment. The visitor experiences a coordinated brand journey. + +The fail. The same visitor takes the quiz; the calculator does not know they took it; the lead magnet sequence is generic. Each tool is an island. The audience signal captured in one tool is wasted in the next. + +The discipline. Data flows. Each tool's interactions inform subsequent interactions. + +--- + +## Pattern A: Identity threading + +When the audience is identified, their identity carries forward across tools. + +How it works. + +- The audience opts in (email submission, account creation, login). +- Subsequent interactions are associated with that identity. +- Tools across the funnel access the identity record to personalize. + +Strengths. + +- Most powerful continuity mechanism. +- Lets all tools share context for the same person. + +Weaknesses. + +- Requires identity infrastructure (CRM, data warehouse, customer data platform). +- Privacy considerations (handling identity data carefully). + +When to use. When the program has identity infrastructure and the audience is willing to be identified (typically post lead-magnet download or account creation). + +--- + +## Pattern B: Context capture + +Inputs from one tool feed into the next interaction. + +How it works. + +- Tool A captures specific inputs (calculator values, quiz answers, form responses). +- Those inputs are stored with the identity (or with an anonymous session token). +- Tool B reads the inputs; uses them as defaults or context. + +Example. + +- Quiz captures "team size: 75." +- Calculator's defaults reflect team size 75. +- Lead magnet's recommended resource matches team size 75. + +Strengths. + +- Concrete continuity; the audience sees their inputs reflected. +- Reduces re-entry friction. + +Weaknesses. + +- Requires structured data capture (not just behavioral signals). +- Inputs from different tools must align (no conflict if quiz and calculator both capture team size). + +When to use. When tools capture overlapping or related context that benefits from shared use. + +--- + +## Pattern C: Segment tagging + +Each interaction tags the audience with segment information that informs future routing. + +How it works. + +- Tool A determines the audience's segment based on inputs (the quiz result; the calculator's input pattern). +- The segment tag attaches to the audience record. +- Subsequent tools and sequences route based on the tag. + +Example. + +- Quiz result: "Mid-market operator." +- Tag: segment = mid-market. +- Subsequent: lead magnet sequence is the mid-market sequence; calculator defaults are mid-market; chatbot routing is mid-market-aware. + +Strengths. + +- Lightweight. The tag is small; the routing logic uses it. +- Compatible with most marketing automation. + +Weaknesses. + +- Tag accuracy depends on the source tool's accuracy. +- Tags can conflict (different tools assign different segments). +- Tag staleness (the audience's segment may change over time). + +When to use. Default pattern for cross-tool routing. + +--- + +## Pattern D: Sequence-tool integration + +Email sequences include links to specific tools matched to the audience's segment. + +How it works. + +- Sequence email includes a CTA: "based on your situation, this calculator can help you compare." +- The CTA link includes parameters that pre-fill the calculator with the audience's known context. +- Audience clicks; calculator opens with their context already populated. + +Strengths. + +- Explicit cross-tool connection; the audience sees the journey. +- Reduces friction at the calculator (audience does not re-enter known information). + +Weaknesses. + +- Requires tooling for parameterized links and pre-fill. +- The pre-fill must respect what the audience consented to share. + +When to use. When the sequence is steering the audience toward specific tools and pre-fill would meaningfully reduce friction. + +--- + +## Conflict and source-of-truth + +When different tools capture different values for the same attribute. + +The pattern. The quiz says team size 75; the multi-step form says team size 60. Which is correct? + +Approaches. + +- Latest wins. The most recent capture overrides earlier captures. +- Source authority. Specific tools are designated as authoritative for specific attributes (form > quiz for verified data). +- User confirmation. Conflict surfaces a confirmation prompt: "We have you down as 75; is that still correct?" + +The discipline. Define source-of-truth for important attributes. Latest-wins is simple but can lose data; source authority is more disciplined but requires explicit definition. + +--- + +## Privacy and consent + +Cross-tool data flow involves handling user data. Consent matters. + +The principle. The audience should know what data flows where. Pre-filling a calculator with previously captured information is fine if the audience expects it; surprising them with knowledge they did not consent to share breaks trust. + +Consent patterns. + +- Explicit opt-in to identity tracking ("save my progress"). +- Disclosure of data flow ("we use your quiz answers to personalize subsequent recommendations"). +- Easy data deletion or account closure. + +Privacy regulations. GDPR, CCPA, and other regulations affect what data can flow and how. Compliance is essential; the architecture must respect the regulations applicable to the audience. + +--- + +## Anonymous-session continuity + +When the audience is not yet identified. + +The pattern. Browser-based continuity (cookies, local storage) lets tools share context within the same session even before identity capture. + +Strengths. + +- Continuity without requiring early opt-in. +- Smooth experience across same-session tool interactions. + +Weaknesses. + +- Lost when the audience switches devices or clears cookies. +- Limited persistence (typically days, not weeks). +- Privacy considerations (cookies-based tracking has its own complications). + +When to use. As a supplement to identity-based continuity; for early-funnel interactions before opt-in. + +--- + +## Cross-tool data flow architecture + +How to design the data flow at the architecture level. + +The data layer. A single data layer (CRM, customer data platform, data warehouse) holds the audience records. All tools read from and write to this layer. + +The integration layer. Tools integrate with the data layer either directly (API) or through a middleware (Zapier, Segment). + +The privacy layer. Consent and data-control mechanics live across the architecture; the data layer respects them. + +Architecture-level discipline. Cross-tool data flow is infrastructure work, not just tool work. Building the infrastructure is part of the funnel architecture investment. + +--- + +## Cross-tool measurement + +Track how data flows across tools. + +Metrics. + +- Cross-tool engagement. What percentage of subscribers who engaged with tool A also engaged with tool B? +- Identity capture rate. What percentage of visitors who interact with tools become identified? +- Pre-fill usage. When pre-fill is offered, what percentage of users engage with the pre-filled tool? +- Segment tag accuracy. Sample-based audit of whether segment tags match actual audience profiles. + +Diagnostic uses. Low cross-tool engagement signals tools are not connecting in the audience's journey; low pre-fill usage signals the pre-fill is not visible or not valued. + +--- + +## Cross-tool data flow audit + +Periodically audit the data flow. + +The audit. + +- Walk through critical journeys end-to-end. Does data actually flow? +- Verify identity threading works (logged-in user is recognized across tools). +- Verify context capture works (inputs in tool A appear in tool B as expected). +- Verify segment tagging works (quiz result tag triggers correct downstream sequences). +- Verify sequence-tool integration works (sequence links pre-fill correctly). + +The drift. Integrations break silently. Tool updates change data formats. Audit catches the drift. + +--- + +## Common data flow failures + +No data flow. Each tool isolated; identity and context lost between tools. + +Identity threading broken. Logged-in user not recognized across tools; same person treated as new visitor multiple times. + +Context capture incomplete. Tool A captures inputs but tool B does not access them. + +Segment tag conflicts. Different tools tag the same person differently; downstream routing inconsistent. + +Pre-fill broken. Sequence link includes parameters but the tool does not honor them; audience re-enters known information. + +Privacy violations. Cross-tool data flow happens without consent; audience surprised; trust damaged. + +Stale data. Audience's situation has changed but tools still use old captured data. + +--- + +## Methodology-level choices that stay in the public skill + +The continuity principle. Patterns A through D (identity, context, segment, sequence-tool integration). Conflict and source-of-truth. Privacy and consent. Anonymous-session continuity. Cross-tool data flow architecture. Cross-tool measurement. Audit cadence. Common failures. + +## Implementation choices that stay internal + +Specific data layer choices for the team's stack. Specific integration tooling. Specific consent flows and privacy disclosures. The team's audit calendars. These vary by team. diff --git a/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md b/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md new file mode 100644 index 0000000..d3cb1a1 --- /dev/null +++ b/skills/funnel-flow-architecture/references/entry-point-architecture-patterns.md @@ -0,0 +1,190 @@ +# Entry-point architecture patterns + +How visitors land vs how they're routed. Common entry points and their routing. + +The funnel architecture maps entry points (where visitors arrive) to segments and paths (what they do next). Without entry-point architecture, every visitor goes through the same first experience regardless of where they came from. + +--- + +## The entry-routing principle + +Each entry point has expected segments and stages. The first action available at the entry point should match those expectations. + +The win. A visitor arrives via an ad about "B2B SaaS pricing." The landing page serves consideration-stage pricing content. The first available action is a pricing calculator and a demo CTA. The entry point's routing matches the visitor's likely intent. + +The fail. Same visitor arrives via the same ad. The landing page is the homepage. The visitor lands in awareness-stage content with no clear next step. The mismatch costs the conversion. + +The discipline. Each entry point's first experience matches the visitor's likely segment and stage. + +--- + +## Common entry points + +The entry points most growth programs work with. + +Paid landing page. Visitor arrives via paid ad (search, social, display). High intent; specific to the ad's promise. + +Expected segment: usually narrow (the ad targeted specific audience). +Expected stage: usually consideration or decision (paid traffic is rarely awareness-stage). +Routing: landing page should serve the ad's specific promise; next-step action should match consideration or decision stage. + +Organic content page. Visitor arrives via search or content discovery; awareness or research stage. + +Expected segment: variable (organic search may surface multiple audience types). +Expected stage: usually awareness or early consideration (research-driven). +Routing: content should serve the search intent; secondary CTAs offer movement toward consideration. + +Direct or returning visitor. Visitor arrives by typing URL or via bookmark; often returning. + +Expected segment: variable (depends on prior interactions). +Expected stage: variable (could be any stage). +Routing: homepage should provide multiple entry paths to different segments and stages; navigation matters more than single CTA. + +Referral. Visitor arrives via partner or word-of-mouth; warmer than paid. + +Expected segment: variable (depends on referral source). +Expected stage: usually consideration or decision (referrals indicate active interest). +Routing: page should match the referral context; next-step action should reflect the warmth (free trial, demo, talk to sales often work). + +Social. Visitor arrives via social post; awareness or interest. + +Expected segment: variable (depends on social audience). +Expected stage: usually awareness (social discovery is rarely buying intent). +Routing: page should serve the social post's promise; soft CTAs (follow, subscribe, learn more) often work better than hard sells. + +Tool entry. Visitor arrives via a calculator, quiz, or chatbot directly (often via shared link or specific tool URL). + +Expected segment: matches the tool's audience. +Expected stage: usually consideration (the tool is a consideration-stage artifact). +Routing: tool should serve its specific value; next-step actions should connect tool output to broader funnel. + +--- + +## Entry-point routing patterns + +How to route each entry point. + +Pattern A: Direct match. Entry point routes directly to a specific landing page and CTA. Simple; works when the entry point's segment and stage are well-defined. + +Pattern B: Routing layer. Entry point routes to a routing page that asks 1-2 questions and then sends to the matched destination. Useful when the entry point's segment is variable. + +Pattern C: Personalized landing. Entry point routes to a landing page that adapts based on visitor attributes (source, behavior, profile). Sophisticated; requires personalization infrastructure. + +Pattern D: Quiz-as-router. Entry point routes to a quiz that segments and recommends. Detail in `quiz-and-assessment-design`. + +The choice depends on entry-point variability and infrastructure. Most programs start with Pattern A and add complexity as data shows the need. + +--- + +## Entry-point and segment matching + +Each entry point likely surfaces specific segments. + +The discipline. For each entry point, document the expected segments. The first experience should serve those segments. + +Worked example. + +- Entry point: paid ad targeting "data analytics for SaaS." +- Expected segments: data analysts and data leaders at SaaS companies. +- Expected stage: consideration. +- Routing: landing page on data analytics for SaaS; calculator showing ROI; CTA to demo. + +The match is deliberate. Visitors arriving via this entry point get a first experience that fits their segment and stage. + +--- + +## Entry-point and stage matching + +The first experience should match the visitor's likely stage. + +Common mismatches. + +- Awareness-stage visitor lands on a hard-sell decision-stage page; bounces because not ready. +- Decision-stage visitor lands on awareness-stage content; bounces because oversold on what they already know. +- Consideration-stage visitor lands on either; serves the wrong intent. + +The cure. Match the entry point's expected stage to the page's stage. Awareness pages serve awareness traffic; decision pages serve decision traffic. + +--- + +## Multi-entry funnels + +When the same visitor arrives via different entry points across visits. + +The pattern. A visitor sees an ad on Tuesday (paid entry); reads a blog post on Wednesday (organic entry); types the URL on Thursday (direct entry). Each entry point may surface a different first experience. + +Architecture implications. + +- Personalization across visits requires identity threading. +- Nurture sequences may need to acknowledge prior visits. +- Cross-channel attribution becomes important. + +The discipline. Architecture should accommodate multi-entry without confusion. The visitor's progression through the funnel respects their cumulative interactions, not just the latest entry. + +--- + +## Entry-point measurement + +Track per-entry-point performance. + +The metric. Per entry point: visitors, segment composition, stage composition, conversion to next action. + +Diagnostic uses. + +- Entry points with low conversion: routing may be mismatched. +- Entry points with high conversion: investigate what is working; replicate to other entries. +- Entry points whose segment composition does not match expectations: the source may have shifted; review. + +--- + +## Entry-point and audience-segment audit + +Periodically audit entry-point routing. + +The audit. + +- For each entry point: what segments and stages are arriving? +- Does the first experience match those segments and stages? +- Is conversion at this entry point above or below baseline? + +The drift. Entry points decay as ad targeting shifts, content rankings change, partners evolve. Quarterly audit catches the drift. + +--- + +## Entry-point anti-patterns + +The single-funnel-for-every-entry. All visitors go through the same first experience regardless of entry. Routing not matching segments or stages. + +The over-personalized-entry. Entry routing so specific that maintenance is impossible; many entries route to landing pages that exist only for one entry source. + +The mismatched-entry. Entry expects one segment; landing page serves a different one. Conversion suffers. + +The unmeasured-entry. Per-entry data not tracked; routing decisions are guesswork. + +The orphan-entry. Entry point exists; no landing page or routing defined; visitors land somewhere generic. + +--- + +## Common entry-point failures + +One landing page for everyone. Different entry points get the same first experience; routing not matching variability. + +Wrong stage routing. Awareness traffic gets decision-stage CTAs; decision traffic gets awareness content. + +Personalization without infrastructure. Architecture designed for personalization that the team cannot actually implement. + +Entry-point drift. Entry sources shifted; routing not updated. + +Single-tool entry. Only one tool serves an entry point; if the tool fails, the entry has no recovery. + +Entry-conversion attribution missing. Cannot tell which entry points produce which downstream conversion. + +--- + +## Methodology-level choices that stay in the public skill + +The entry-routing principle. Common entry points (6 patterns). Entry-point routing patterns (4 patterns). Entry-point and segment matching. Entry-point and stage matching. Multi-entry funnels. Entry-point measurement. Audit cadence. Anti-patterns. Common failures. + +## Implementation choices that stay internal + +Specific entry points for specific programs. Specific routing logic per entry. Specific landing pages per entry. The team's audit calendars. These vary by team and program. diff --git a/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md b/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md new file mode 100644 index 0000000..22a62e8 --- /dev/null +++ b/skills/funnel-flow-architecture/references/funnel-iteration-discipline.md @@ -0,0 +1,189 @@ +# Funnel iteration discipline + +When to refine, when to redesign. Avoiding the continuous-redesign and frozen-architecture traps. + +Funnel architecture compounds when refined; collapses when constantly redesigned. The discipline is knowing when each is appropriate. + +--- + +## The compound-vs-reset distinction + +Refinement compounds. Redesign resets. + +Refinement. Targeted changes to specific tools, sequences, or transitions within the existing architecture. The architecture's bones stay; the muscles get stronger. + +Redesign. Overhaul of the architecture. Segments redefined; tool-to-funnel mapping changed; sequences rebuilt. The architecture restarts. + +The discipline. Refine continuously; redesign deliberately and rarely. Constant redesign prevents compounding; never iterating allows decay. + +--- + +## When to refine + +Five conditions that signal refinement is appropriate. + +Specific tools are underperforming relative to baseline. A calculator with declining conversion benefits from input adjustment, default updates, or methodology refinement. The architecture is fine; the tool needs attention. + +Specific segments have lower conversion than peer segments. A segment that converts at 4 percent while peer segments convert at 10 percent has a fixable architecture issue. Refine the segment's path. + +Specific transitions in the funnel are producing drop-off. The transition from quiz to recommended product page has high drop-off. Audit the transition; fix. + +Sequence engagement is declining for specific cohorts. Newer subscribers to a sequence engage less than older subscribers. The sequence may have decayed; refresh content. + +Specific entry points are routing wrong segments. A paid ad source has shifted; visitors arriving from it no longer match the segment the landing page serves. Adjust the routing. + +These are refinements. The architecture is sound; specific elements need attention. + +--- + +## When to redesign + +Four conditions that signal redesign is appropriate. + +Audience composition has fundamentally shifted. The brand pivots; the target audience changes; the segments are no longer accurate. The matrix needs redesign. + +Product or service strategy has changed. The brand offers a fundamentally different product line; the funnel that served the old products no longer fits. Redesign. + +Competitive landscape has shifted significantly. A new competitor reshapes the buying process; the funnel needs to respond. Redesign may follow. + +Multiple refine cycles have not produced expected results. The team has refined repeatedly; conversion has not moved. The issue may be architectural rather than tactical. Redesign worth considering. + +These are redesigns. The architecture's fundamentals need to change. + +--- + +## The continuous-redesign trap + +Teams that constantly redesign never benefit from architectural compounding. + +The pattern. Every quarter, the team rethinks the funnel. New segments; new tools; new sequences. Each redesign is partially built before the next redesign starts. + +The signal. Conversion does not improve over time. Each iteration starts over. Learning does not accumulate because the structure keeps changing. + +The cost. The team's investment dilutes across redesigns. Tools never reach maturity. Sequences never stabilize. + +The cure. Redesign infrequently. Refine continuously between redesigns. Set a "no major redesign for X months" discipline if needed. + +--- + +## The frozen-architecture trap + +Teams that never iterate watch their architecture decay. + +The pattern. The funnel was designed once; the team treats it as finished. No refinement; no redesign; no audit. + +The signal. Conversion declines slowly over months and years. Tools age; sequences go stale; segments shift. The architecture does not respond. + +The cost. The architecture's value erodes. Audiences move on; competitors improve; the brand falls behind. + +The cure. Set refinement cadences. Quarterly audit; targeted refinements based on data. Acknowledge that no architecture stays optimal forever. + +--- + +## The middle ground + +Refine continuously; redesign infrequently and deliberately. + +Refinement cadence. Monthly or quarterly. Targeted; data-driven; small enough to test in isolation. + +Redesign cadence. Annually at most. Often longer. Major triggers (audience pivot, product change, competitive shift) drive redesign rather than calendar. + +The discipline. Both rhythms running in parallel. Refinement maintains; redesign responds to fundamental change. + +--- + +## Refinement workflow + +How to iterate productively. + +Step 1: Identify the gap. Data-driven; specific to a tool, segment, transition, or sequence. + +Step 2: Hypothesize the cause. What might explain the gap? + +Step 3: Design a treatment. What change would address the hypothesis? + +Step 4: Test if possible. A/B test or before-after measurement when feasible. + +Step 5: Validate. Did the metric move? Did downstream metrics also benefit? + +Step 6: Roll out or roll back. Successful refinements stick; unsuccessful ones revert. + +The discipline. Each refinement is hypothesis-driven and validated. Random changes do not compound. + +--- + +## Redesign workflow + +How to redesign without resetting everything. + +Step 1: Articulate why. What has fundamentally changed that warrants redesign? + +Step 2: Preserve what works. Identify elements of the current architecture that are still appropriate. Do not throw away learning. + +Step 3: Design the new architecture. Segment matrix; entry-point routing; tool-to-funnel mapping; sequence architecture. Document everything. + +Step 4: Plan migration. How to transition existing audience and tools to the new architecture without losing momentum. + +Step 5: Pilot before full rollout. Test the new architecture with a subset of audience or one segment before full deployment. + +Step 6: Migrate. Roll out the new architecture; retire the old one. + +Step 7: Monitor closely. Architecture-level metrics in the first months show whether the redesign delivered. + +The discipline. Redesign is a project, not a flip of a switch. Plan it; pilot it; migrate; monitor. + +--- + +## The decay-driven redesign signal + +How to know decay has accumulated to redesign level. + +Signals. + +- Multiple refine cycles have not moved the metric. +- Segments no longer describe the audience accurately. +- Tools designed for one segment are being used by others (mapping has drifted). +- The architecture diagram no longer matches the actual experience visitors have. +- Quarterly audits surface the same issues quarter after quarter without fix. + +When these signals accumulate, refinement is not enough. Redesign is needed. + +--- + +## Iteration measurement + +How to know iterations are working. + +The metric. Architecture-level metrics improving over time. Cross-tool conversion rising; segment-level conversion rising; funnel-stage progression accelerating. + +The trap. Improving one metric while others decline. A refinement that lifts cross-tool conversion but tanks lead quality is not net positive. + +The discipline. Watch the portfolio of metrics, not individual ones. Refinement should improve the architecture's overall outcomes, not just one measure. + +--- + +## Common iteration failures + +Continuous redesign. Architecture never stabilizes; learning does not compound. + +Frozen architecture. Architecture never iterates; decay accumulates. + +Random refinement. Changes without hypothesis or testing; results are noise. + +Refinement without measurement. Cannot tell if changes are working. + +Redesign without preserving learning. Throws away what was working alongside what was not. + +Redesign without migration plan. Audience and tools left in transition; experience suffers. + +Iteration without portfolio metrics. Improving one metric while damaging others. + +--- + +## Methodology-level choices that stay in the public skill + +The compound-vs-reset distinction. When to refine (5 conditions). When to redesign (4 conditions). The continuous-redesign trap. The frozen-architecture trap. The middle ground. Refinement workflow. Redesign workflow. The decay-driven redesign signal. Iteration measurement. Common failures. + +## Implementation choices that stay internal + +Specific iteration calendars for the team. Specific refinement and redesign processes. Specific tooling for testing iterations. The team's iteration history and lessons. These vary by team. diff --git a/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md b/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md new file mode 100644 index 0000000..d23c914 --- /dev/null +++ b/skills/funnel-flow-architecture/references/funnel-measurement-patterns.md @@ -0,0 +1,222 @@ +# Funnel measurement patterns + +Architecture-level vs tool-level metrics. What to measure, what is noise. + +Funnel measurement should reveal architecture quality, not just tool quality. Tool-level metrics tell you whether each tool is working; architecture-level metrics tell you whether the tools work together. + +--- + +## The architecture-vs-tool measurement distinction + +Two layers of measurement. + +Tool-level metrics. Each tool's individual performance (calculator conversion, quiz completion, lead-magnet downloads). Detail in each tool's skill. + +Architecture-level metrics. How the tools and sequences compose. Cross-tool conversion, sequence-to-tool conversion, segment-level downstream conversion, funnel-stage progression. + +The discipline. Measure both layers. Architecture-level metrics are often the missing measurement. + +--- + +## Architecture-level metric: Cross-tool conversion + +What percentage of audience that hits tool A then engages with tool B. + +The metric. Count the visitors who interact with tool A (calculator, quiz, lead magnet, etc.). Of those, how many subsequently interact with tool B? + +Why it matters. Cross-tool engagement signals whether the funnel is composing. High cross-tool conversion means the architecture is working; low cross-tool conversion means tools are silos. + +Measurement methods. + +- Identity-based tracking (same identified user across tools). +- Session-based tracking (same session sees multiple tools). +- Cohort analysis (cohorts entering through tool A and their downstream tool engagement). + +Diagnostic uses. + +- Low cross-tool conversion: tools may not be promoted to each other's audiences; transitions may be broken. +- Specific tool pairs underperforming: those transitions need design attention. + +--- + +## Architecture-level metric: Sequence-to-tool conversion + +What percentage of nurture sequence subscribers engage with downstream tools. + +The metric. Count subscribers in a sequence. Of those, how many click through to a tool the sequence promoted? + +Why it matters. Sequences should drive subscribers toward tools matched to their segment-and-stage. Low sequence-to-tool conversion signals that the sequences are not effectively bridging to tools. + +Diagnostic uses. + +- Specific sequence emails with low click-through: the email's tool promotion may not match the audience. +- Specific tools with low sequence-driven traffic: the sequences may not be promoting those tools enough. + +--- + +## Architecture-level metric: Segment-level downstream conversion + +Per-segment conversion to the program's main goal. + +The metric. For each segment in the matrix: what percentage convert to the main goal (trial, demo, purchase) within a defined timeframe? + +Why it matters. Different segments will convert at different rates; segments significantly underperforming relative to peers signal architecture issues. + +Diagnostic uses. + +- Segments with low downstream conversion: the funnel architecture for that segment may be broken or under-developed. +- Segments with high downstream conversion: investigate what is working; replicate to other segments. + +--- + +## Architecture-level metric: Funnel-stage progression + +What percentage of audience moves from awareness to consideration to decision over time. + +The metric. Track audience as they progress through stages. Awareness audience this month; what percentage are in consideration next month; what percentage in decision the following. + +Why it matters. The funnel's job is to progress audience through stages. Low progression signals the nurture sequences and tools are not advancing the relationship. + +Diagnostic uses. + +- Slow progression: sequences may be too educational without enough advancement; or the audience may be getting stuck. +- Fast progression but low conversion: progression without quality. + +--- + +## Tool-level metrics + +Each tool has its own metrics. Detail in each tool's skill. + +Calculator. Conversion rate per visitor; tier-2 (email gate) conversion; downstream conversion of calculator-sourced leads. + +Quiz. Completion rate; per-segment downstream conversion; recommendation click-through. + +Lead magnet. Download rate; sequence engagement; downstream conversion of magnet-sourced subscribers. + +Multi-step form. Completion rate; per-step drop-off; lead quality. + +Chatbot. Resolution rate per intent; escalation rate; downstream conversion. + +The tool-level metrics tell you whether each tool is doing its job. The architecture-level metrics tell you whether the tools are doing the funnel's job. + +--- + +## What is noise + +Metrics that look important but are not. + +Total tool engagements. Volume without context. A tool with 10000 engagements per month tells you nothing without conversion context. + +Email open rate alone. Open rate is a leading indicator at best; sequence-to-conversion is the metric that matters. + +Time on page or session length. Often correlates with confusion as much as engagement. + +Bounce rate alone. High bounce rate on awareness content may be normal; on decision content may signal a problem; aggregate bounce rate is noise. + +The discipline. Measure outcomes, not activity. Activity metrics are noise unless connected to outcome metrics. + +--- + +## Measurement granularity + +How granular to measure. + +Per-tool measurement. Standard. Each tool tracked. + +Per-segment-per-tool measurement. Measure each tool's performance per segment. Surfaces segment-specific tool issues. + +Per-segment-per-stage measurement. Measure progression and conversion per cell in the matrix. + +Per-cohort measurement. Track cohorts (groups arriving in the same period) over time. Surfaces evolution and decay. + +The discipline. Granularity matters when it informs decisions. Per-segment-per-stage is often where the diagnostic value lives; per-cohort surfaces decay. + +--- + +## Attribution + +Connecting outcomes to specific tools and sequences. + +The challenge. Audiences interact with multiple tools and sequences. Which one drove the conversion? + +Approaches. + +- First-touch attribution. Credit goes to the first interaction. +- Last-touch attribution. Credit goes to the most recent interaction. +- Multi-touch attribution. Credit distributed across interactions. +- Position-based attribution. Credit weighted by position (often U-shaped or W-shaped). + +The honest framing. Attribution is a model. No model is perfectly accurate. Choose a model deliberately; understand its biases; report consistently. + +--- + +## Measurement and architecture decisions + +How metrics inform architecture changes. + +The pattern. Metrics surface gaps; architecture decisions address them; subsequent metrics validate. + +Examples. + +- Cross-tool conversion low: redesign transitions; promote tool B in tool A's exit; measure improvement. +- Specific segment underperforming: review segment's funnel path; adjust tools or sequences; measure. +- Funnel-stage progression slow: review sequence design; add or refine; measure. + +The discipline. Metrics inform decisions; decisions are tested; results validated. Without measurement, architecture changes are guesswork. + +--- + +## Measurement instrumentation + +What needs to be in place. + +Identity tracking. Identified users tracked across tools. +Event tracking. Each tool interaction logged with event data. +Funnel definition. The funnel stages and segments defined in the analytics tool. +Cohort capability. Ability to define and track cohorts. +Reporting. Dashboards or reports that surface architecture-level metrics. + +The discipline. Instrumentation should be in place before launch, not added later. Retrofitting measurement is harder than building it in. + +--- + +## Measurement cadence + +How often to look at architecture-level metrics. + +Weekly review. For high-velocity programs or recently launched architectures. Catches regressions and informs rapid iteration. + +Monthly review. For stable programs. Tracks trends and surfaces gradual decay. + +Quarterly review. Comprehensive architecture audit. Per-cell analysis; segment-level deep dive; funnel-stage progression. + +Triggered review. When tools change, when segments shift, when external factors (market, competition) change. + +--- + +## Common measurement failures + +Tool-level only. Architecture-level metrics not tracked; cannot diagnose composition issues. + +Vanity metrics. Volume metrics without conversion context. + +No segment-level granularity. Aggregate metrics hide segment-specific issues. + +Attribution model not chosen. Reports inconsistent because attribution is ad-hoc. + +No cohort tracking. Cannot see decay or evolution. + +Metrics without action. Metrics reviewed but no decisions follow. + +Confounded data. Multiple changes deployed without isolation; cannot attribute outcomes to changes. + +--- + +## Methodology-level choices that stay in the public skill + +The architecture-vs-tool measurement distinction. Architecture-level metrics (cross-tool, sequence-to-tool, segment-level, funnel-stage). Tool-level metrics (cross-reference). What is noise. Measurement granularity. Attribution approaches. Measurement and architecture decisions. Instrumentation requirements. Measurement cadence. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific programs. Specific tooling for measurement. Specific attribution models. The team's reporting conventions. These vary by team. diff --git a/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md b/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md new file mode 100644 index 0000000..6469028 --- /dev/null +++ b/skills/funnel-flow-architecture/references/nurture-sequence-architecture.md @@ -0,0 +1,256 @@ +# Nurture sequence architecture + +Per-segment, per-stage sequence variation. The matched sequence win. + +Different segments at different stages get different nurture sequences. The sequences match the audience's situation and stage. Done well, sequences compound the brand's relationship with the audience; done poorly, sequences treat everyone the same and convert no one well. + +--- + +## The matched-sequence principle + +Each segment-and-stage cell warrants a sequence designed for that cell. Different cells get different sequences. + +The win. An SMB consideration-stage subscriber gets a 5-email sequence focused on SMB-relevant comparison content, ROI examples from similar SMB customers, and a soft demo invitation. The sequence reads as if written for them. + +The fail (kitchen-sink sequence). Every subscriber regardless of segment or stage gets the same 5-email sequence. The content is generic enough to send to all; specific enough for none. SMB subscribers see enterprise examples; enterprise subscribers see SMB examples; conversion uniformly low. + +The discipline. Sequences vary by segment and stage. The matrix from `audience-and-stage-segmentation` is the sequence design map. + +--- + +## Sequence variation by stage + +Stage-specific sequence patterns. + +Awareness sequence. + +- Goal: build relationship; deepen brand association with the topic. +- Content: educational, broad value, brand-building. +- Frequency: typically lower (weekly to bi-weekly); the audience is not in active research. +- Soft offers: subscribe to newsletter, follow on social, attend webinar. +- Hard offers: rare; awareness audiences are not buying yet. + +Consideration sequence. + +- Goal: move from "evaluating" to "selecting." +- Content: comparative, specific value, product-fit signals. +- Frequency: higher (every 3-7 days); audience is actively evaluating. +- Soft offers: see comparison guide, take quiz, calculator. +- Hard offers: demo, trial, talk to sales (toward end of sequence). + +Decision sequence. + +- Goal: commit; sign up; purchase. +- Content: confidence-building, risk-reversal, urgency cues, case studies of similar customers. +- Frequency: high (every 2-4 days); audience is close to deciding. +- Soft offers: rarely; mostly hard offers. +- Hard offers: trial, signup, talk to sales, custom quote. + +Customer sequence (often missed). + +- Goal: deepen success; expand and retain. +- Content: feature deep-dives, success stories from similar customers, community invitations. +- Frequency: ongoing; matches product cadence. +- Soft offers: attend events, refer others. +- Hard offers: upgrade, add-on, expansion. + +--- + +## Sequence variation by audience + +Audience-specific sequence patterns. + +SMB audience. + +- Tone: practical, fast-execution, peer-to-peer. +- Examples: SMB customers; focus on quick wins and resource constraints. +- Content depth: shorter, scannable, action-oriented. + +Mid-market audience. + +- Tone: strategic, considered, multi-stakeholder. +- Examples: mid-market customers; focus on team adoption and process change. +- Content depth: moderate; depth where it matters; summaries for executives. + +Enterprise audience. + +- Tone: rigorous, evidence-based, formal. +- Examples: enterprise customers; focus on security, scale, integration. +- Content depth: deep; white papers, technical documentation, case studies with metrics. + +Solo or creator audience. + +- Tone: personal, founder-to-founder. +- Examples: similar solo practitioners; focus on individual impact and time savings. +- Content depth: practical; templates and how-tos over strategy. + +--- + +## Sequence design discipline + +How to design each sequence. + +Step 1: Define the goal. What conversion does this sequence drive? Awareness to consideration; consideration to demo; demo to decision; decision to purchase. + +Step 2: Define the audience. Which segment-and-stage cell does this sequence serve? + +Step 3: Outline the arc. What is the email-by-email progression? Each email should have a purpose; cumulatively the arc moves the subscriber toward the goal. + +Step 4: Match content to arc. What specific content (template, case study, framework, demo invitation) fits each step? + +Step 5: Define triggers and cadence. What triggers the sequence (lead magnet download, demo request, behavior signal)? What is the spacing? + +Step 6: Define the soft and hard offers. Where do soft offers appear? Where do hard offers appear? At what point does the sequence make a direct ask? + +Step 7: Define the exit. When does the sequence end? Where do subscribers go after (newsletter, segment-specific stream, retired)? + +The output is a documented sequence ready to build and ship. + +--- + +## Sequence cadence + +How frequently to send. + +Awareness cadence. Weekly to bi-weekly typical. The audience is not in active research; over-sending feels intrusive. + +Consideration cadence. Every 3-7 days typical. The audience is actively evaluating; cadence matches their consideration pace. + +Decision cadence. Every 2-4 days typical. The audience is close to deciding; cadence reflects urgency. + +Customer cadence. Variable. Match product cadence and customer engagement patterns. + +The cadence-too-frequent risk. Daily sends can fatigue; unsubscribe rates climb. + +The cadence-too-infrequent risk. Weekly sends to consideration audiences can lose momentum; the audience moves on. + +--- + +## Sequence content sourcing + +Where the content for sequences comes from. + +Repurposed content. Existing blog posts, case studies, white papers can populate sequences. Cost-effective; benefits from existing content investments. + +Sequence-original content. Content written specifically for the sequence. More effort; can be highly tailored to the audience and arc. + +Hybrid. Most sequences mix repurposed and original. Original content for the key arc moments; repurposed content for supplementary value. + +The discipline. Sequence content should fit the sequence's audience and stage; off-fit content (even good content) weakens the sequence. + +--- + +## Sequence triggers + +What launches the sequence. + +Trigger types. + +- Lead magnet download. Most common trigger. +- Calculator completion. With segment data captured. +- Quiz completion. With segment matched to result. +- Multi-step form submission. Demo request, qualification. +- Behavior signal. Visited specific pages, viewed pricing, abandoned cart. +- Manual addition. Sales team adds a contact. + +The trigger discipline. The trigger informs which sequence the subscriber enters. A lead-magnet download for an awareness-stage resource enters the awareness sequence; a calculator completion with consideration-stage signals enters the consideration sequence. + +Trigger-segment routing. Multiple triggers can route to multiple sequences based on captured segment information. The trigger is one signal; segment is another. + +--- + +## Sequence intersection and routing + +When subscribers might enter multiple sequences. + +The challenge. A subscriber downloads two lead magnets in the same week. Each magnet has its own sequence. Should they enter both? + +Approaches. + +- Override. Latest trigger overrides; subscriber enters the latest sequence and exits prior ones. +- Concatenate. Subscriber completes the first sequence, then enters the next. +- Pause. Active sequence pauses other triggers; subscriber returns to queue after current sequence. +- Multi-path. Subscriber enters multiple sequences simultaneously (risk of frequency overload). + +The choice depends on subscriber experience and sequence design. Most programs benefit from override or pause patterns to avoid frequency overload. + +--- + +## Sequence and offer alignment + +The offers in the sequence must match the audience. + +The principle. A sequence for SMB consideration-stage subscribers should pitch SMB-appropriate offers. Pitching enterprise offers in this sequence wastes the audience signal. + +Offer alignment failures. + +- Magnet attracts SMB; sequence pitches enterprise. +- Awareness sequence pitches hard sales offers prematurely. +- Decision sequence pitches awareness content the subscriber outgrew. + +The cure. Sequence offers reflect the audience and stage the sequence serves. + +--- + +## Sequence measurement + +Per-sequence metrics. + +Open rate. Per email; per sequence overall. + +Click-through rate. Per email; per sequence. + +Conversion to next step. What percentage of subscribers in this sequence completed the desired conversion? + +Unsubscribe rate. Per email; per sequence. + +Sequence-to-customer conversion. What percentage of subscribers in this sequence eventually became customers? + +Diagnostic uses. Low open rates per email signal subject-line issues; low click-through signals content fit issues; high unsubscribe rates signal cadence or content problems. + +--- + +## Sequence maintenance + +Sequences decay. + +What decays. + +- Content references go stale (outdated case studies, retired products). +- Offers change (new products, new pricing, new programs). +- Audience composition shifts; sequence content no longer fits. +- Email deliverability changes; subject lines that worked stop working. + +Maintenance cadence. Quarterly review of every active sequence. Update content; refresh offers; verify links. + +The drift indicator. Sequence performance declining over time signals decay; specific cohorts (newer subscribers vs older) performing differently signals audience shift. + +--- + +## Common sequence failures + +One sequence for everyone. Kitchen-sink pattern; matches no segment specifically. + +Sequence-trigger mismatch. The trigger captured one segment; the sequence is designed for another. + +Offer misalignment. Sequence pitches offers that do not match the audience. + +Cadence wrong for stage. Awareness cadence on consideration audience; consideration cadence on awareness audience. + +No trigger logic. Subscribers enter the same default sequence regardless of how they were captured. + +Sequence-orphan magnets. Lead magnets without follow-up sequences; subscribers go cold. + +Stale sequence content. Sequence designed once; content no longer reflects the brand or product. + +No sequence measurement. Sequence performance unknown; maintenance is guesswork. + +--- + +## Methodology-level choices that stay in the public skill + +The matched-sequence principle. Sequence variation by stage (4 stages). Sequence variation by audience (4 audiences). Sequence design discipline (7 steps). Sequence cadence. Sequence content sourcing. Sequence triggers. Sequence intersection and routing (4 approaches). Sequence and offer alignment. Sequence measurement. Sequence maintenance. Common failures. + +## Implementation choices that stay internal + +Specific sequences for specific segments. Specific email content in brand voice. Specific tooling for sequence automation and measurement. The team's cadence baselines. These vary by team. diff --git a/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md b/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md new file mode 100644 index 0000000..61de4bf --- /dev/null +++ b/skills/funnel-flow-architecture/references/tool-to-funnel-mapping.md @@ -0,0 +1,225 @@ +# Tool-to-funnel mapping + +Which tools serve which entry points and segments. Each tool in the growth toolkit has a place in the funnel architecture; the mapping makes the place explicit. + +Without explicit mapping, tools end up serving everyone (and serving no one well) or getting deployed where they do not fit. With explicit mapping, each tool serves the segments where it adds the most value. + +--- + +## The mapping principle + +Each tool serves specific segments at specific stages from specific entry points. The mapping is documented, not implicit. + +The win. A team's calculator is mapped to consideration-stage SMB and mid-market visitors arriving via organic content. The calculator's design (inputs, defaults, methodology) reflects this segment. Other segments do not see the calculator featured prominently; they see tools matched to their segment. + +The fail. A team's calculator is featured on every page for every visitor. The calculator's design is generic to serve everyone. SMB visitors see enterprise inputs; enterprise visitors see SMB defaults. The calculator serves nobody well. + +The discipline. Each tool has a defined place. The architecture documents which segments and stages and entry points the tool serves. + +--- + +## Common tool-to-funnel mappings + +How each growth tool typically maps. + +Lead magnet. Often serves awareness-to-consideration transition. + +- Audience: awareness-stage visitors who would benefit from a focused resource. +- Entry points: blog posts, content discovery, paid ads on educational topics. +- Position in funnel: captures email; routes to nurture sequence that bridges to consideration. +- Detail in `lead-magnet-design`. + +Calculator. Often serves consideration stage. + +- Audience: visitors evaluating options who need to defend a specific decision. +- Entry points: pricing pages, comparison content, paid ads on solution-evaluation. +- Position in funnel: provides defensible numeric output; routes to demo or trial CTA. +- Detail in `calculator-design`. + +Quiz. Variable depending on design. + +- Awareness quizzes: content marketing, brand-building. Captures email; routes to broad nurture sequence. +- Consideration quizzes: product matching, fit assessment. Captures email; routes to product-specific sequence. +- Decision quizzes: plan selection, configuration. Captures email and routes to specific sales motion or signup. +- Detail in `quiz-and-assessment-design`. + +Multi-step form. Often serves decision or qualification stage. + +- Audience: visitors with high intent who need to provide structured information. +- Entry points: demo CTAs, talk-to-sales pages, application flows. +- Position in funnel: captures qualified intent; routes to sales or to next-stage automation. +- Detail in `multi-step-form-design`. + +Chatbot. Cross-cutting; can serve any stage with intent recognition routing. + +- Audience: any visitor who has questions the bot can handle. +- Entry points: any page where conversation might add value. +- Position in funnel: handles in-conversation routing; escalates to humans for complex cases. +- Detail in `chatbot-flow-design`. + +--- + +## Mapping examples by audience segment + +How tools map for specific segments. + +Solo founder, awareness stage. + +- Lead magnet: practical template they can use today. +- Quiz (optional): "what stage of growth are you in" with matched recommendations. +- Chatbot: yes, for FAQ; lightweight routing. +- Calculator, multi-step form: probably not at this stage. + +SMB team, consideration stage. + +- Calculator: ROI estimate matched to SMB context. +- Lead magnet: comparison guide or worked example. +- Multi-step form: demo request capture. +- Chatbot: yes, for product-specific questions. +- Quiz (optional): plan recommendation. + +Mid-market team, consideration-to-decision. + +- Calculator: ROI estimate with mid-market context. +- Multi-step form: demo request with qualification. +- Chatbot: yes, with escalation to sales for complex questions. +- Lead magnet (optional): white paper or case study. +- Quiz: probably not (mid-market buyers often skip quizzes). + +Enterprise, decision stage. + +- Multi-step form: enterprise demo request with detailed qualification. +- Chatbot: lightweight; escalation-heavy. +- Custom calculator: with enterprise-specific inputs and ROI factors. +- Lead magnet, quiz: usually not (enterprise buyers expect direct human attention). + +The mapping is segment-aware. Tools that fit one segment may not fit another. + +--- + +## Mapping examples by stage + +How tools map for specific stages. + +Awareness stage. + +- Lead magnets prominent. Quizzes can serve. Calculators less common (consideration is when calculators earn their value). Chatbots support. +- Goal: capture awareness-stage email; route to nurture sequence. + +Consideration stage. + +- Calculators central. Quizzes useful for product matching. Lead magnets can deepen value. Chatbots support specific questions. +- Goal: convert consideration into qualified intent; route to demo or trial. + +Decision stage. + +- Multi-step forms central (demo requests, qualified intent capture). Calculators support specific decisions. Chatbots route to sales. +- Goal: convert decision-stage intent into commitment. + +Customer stage. + +- Onboarding flows (which can use multi-step forms). Chatbots for support. Lead magnets and quizzes less central; replaced by in-product education. +- Goal: deepen customer success; expand and retain. + +--- + +## Mapping discipline + +How to make the mapping rigorous. + +Discipline 1: Document the mapping. Write down which tools serve which segments and stages. The document is the architecture's reference. + +Discipline 2: Match tool design to mapping. A tool serving SMB should have SMB-relevant inputs and defaults; a tool serving enterprise should reflect enterprise context. + +Discipline 3: Promote tools where they fit. Show calculators on consideration-stage pages; show lead magnets on awareness-stage pages. Generic tool placement on every page dilutes their value. + +Discipline 4: Retire tools that do not fit. A tool that does not have a mapping is decorative. Either find its place or retire it. + +Discipline 5: Audit the mapping quarterly. Mappings decay as audience composition shifts. Quarterly review catches drift. + +--- + +## Multi-tool segments + +Some segments use multiple tools across their journey. + +The pattern. A consideration-stage SMB visitor uses a lead magnet (awareness arrival), a calculator (consideration depth), then a multi-step demo form (decision intent). Three tools across the journey. + +Architecture implications. + +- Each tool serves a specific moment in the visitor's journey. +- Cross-tool data flow lets each tool benefit from earlier interactions. +- Tools should not duplicate each other's value. + +The discipline. Tools complement, not duplicate. Each tool earns its place in the segment's journey. + +--- + +## Tool overlap and choice + +When multiple tools could serve the same segment-and-stage cell. + +The pattern. A team has both a calculator and a quiz that could serve consideration-stage SMB. + +The decision. Choose the tool that serves the segment best, or use both with clear differentiation. + +- Calculator: when the consideration involves a specific calculation (ROI, savings, sizing). +- Quiz: when the consideration involves categorization or product matching. +- Both: when the segment benefits from both, with clear positioning of when each helps. + +The discipline. Avoid having multiple tools competing for the same segment without clear differentiation. Audiences pick the most prominent; the others underperform. + +--- + +## Tool gaps + +When the mapping reveals gaps. + +The pattern. The architecture documents which tools serve which segments. Some cells in the matrix have no tool; the audience there has no relevant tool to engage with. + +The decision. Either build a tool to fill the gap, or accept that some cells use generic content rather than tools. + +- Build when the segment is high-value and the tool would meaningfully improve conversion. +- Accept when the segment is small or the tool would not earn its build cost. + +The architecture surfaces gaps; the team decides what to do about them. + +--- + +## Tool-mapping audit + +Periodically audit which tools serve which segments and how well. + +The audit. + +- For each tool: which segments does it currently serve? Which segments does it actually attract? +- For each cell in the matrix: which tools are mapped to it? Are they performing? +- Are any tools serving segments outside their intended mapping (drift)? + +The drift indicators. Tool conversion drops; tool's audience composition changes; tool gets traffic from segments it was not designed for. + +--- + +## Common mapping failures + +No mapping. Tools deployed without explicit segment-and-stage assignment. + +Mismatched mapping. Tool serving segments it was not designed for; tool's design does not fit the audience. + +Decorative mapping. Mapping documented but not enforced; tool appears everywhere regardless of mapping. + +Stale mapping. Mapping designed once; not updated as tools or audiences evolved. + +Tool overlap without differentiation. Multiple tools competing for the same segment; audience splits; none performs well. + +Mapping gaps unaddressed. Cells in the matrix have no tool support; the architecture has holes. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle. Common tool-to-funnel mappings (5 tools). Mapping examples by audience segment (4 examples). Mapping examples by stage (4 examples). Mapping discipline (5 disciplines). Multi-tool segments. Tool overlap and choice. Tool gaps. Tool-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific tool-to-segment mappings for specific programs. Specific tool placement decisions on specific pages. The team's audit calendars. These vary by team and program. diff --git a/skills/incident-response/SKILL.md b/skills/incident-response/SKILL.md new file mode 100644 index 0000000..f484749 --- /dev/null +++ b/skills/incident-response/SKILL.md @@ -0,0 +1,260 @@ +--- +name: incident-response +description: "Manage active production incidents through detection, triage, mitigation, communication, and resolution with structured roles and decision-making. Use this skill whenever the user has an active incident, a production issue, a service outage, a security incident, or needs to plan incident response procedures. Triggers on incident response, production incident, outage, service down, site down, P0, P1, severity, downtime, on-call, incident commander, status page, postmortem prep. Also triggers when something is actively broken in production and the user is figuring out what to do." +category: operations +catalog_summary: "Incident triage, comms, mitigation, escalation" +display_order: 2 +--- + +# Incident Response + +Manage active production incidents from detection to resolution. Stack-agnostic. Tool-agnostic. + +This skill is for active incidents and incident process. For after-the-fact analysis, use `after-action-report`. For planned launches, use `launch-runbook`. + +--- + +## When to use + +- An active incident is happening +- Building incident response procedures +- Defining severity levels +- Setting up on-call rotations +- Training a team on incident response + +## When NOT to use + +- Post-incident retrospective (use `after-action-report`) +- Planned launches (use `launch-runbook`) +- Pre-launch issue triage (use `qa-testing`) + +--- + +## Required inputs + +- Awareness of the incident (alert, customer report, internal observation) +- Access to production systems and monitoring +- Roles and authorities clearly defined +- Communication channels operational + +--- + +## The framework: 5 phases + +### 1. Detection + +How the incident becomes known. + +Detection sources: + +- Automated alerts (monitoring, SLO violations, error rate spikes) +- Customer reports (support tickets, social media, status page subscribers) +- Internal observation (engineer notices something off) +- Third-party (security researchers, partners) + +On detection: + +- Acknowledge within target time (typically 5 to 15 minutes for critical) +- Assess severity (see severity rubric below) +- Page the on-call if not already paged +- Open the incident channel + +### 2. Triage + +Establish severity and impact. + +Severity rubric: + +\| Severity \| Definition \| Response \| +\|---\|---\|---\| +\| SEV-1 (Critical) \| Major customer-facing functionality broken. Data integrity at risk. Security breach. \| All-hands. Incident commander. Active war room. Public communication required. \| +\| SEV-2 (Major) \| Significant degradation. Some customers affected. Revenue impact. \| Incident commander assigned. Active response. Internal communication. May or may not need public communication. \| +\| SEV-3 (Minor) \| Limited impact. Workaround available. Affecting a small group of users. \| Standard on-call response. Single owner. \| +\| SEV-4 (Low) \| Cosmetic, edge-case, or low-frequency. No urgent action needed. \| Tracked as bug. Addressed in normal queue. \| + +Severity can change. Re-evaluate as more info emerges. + +### 3. Mitigation + +Stop the bleeding before fixing the cause. + +Mitigation patterns (faster than full fix): + +- Rollback (revert recent deploy) +- Feature flag off (disable the broken feature without deploy) +- Failover (route to healthy replica or region) +- Scale up (more capacity to absorb the load) +- Throttle (reject some traffic to protect the rest) +- Graceful degradation (turn off non-essential features to keep core functional) +- Maintenance mode (last resort, blocks all users) + +Mitigation principle: Stop user impact first. Cause analysis second. + +### 4. Communication + +Three audiences during an incident: + +Internal team: +- Real-time updates in incident channel +- Cadence: every 15 minutes minimum during active incident +- Format: timestamped status updates with what we know, what we're doing, ETA + +Internal stakeholders: +- Higher-level updates to broader org +- Cadence: every 30 to 60 minutes +- Format: business-impact framing, not technical detail + +External / customers: +- Status page updates +- Cadence: every 30 minutes minimum during active incident +- Format: plain language, no blame, what users are experiencing, what to expect + +Communication principles: +- Acknowledge before you have answers ("We're aware and investigating") +- Update on schedule even if no progress ("Still investigating, no new information") +- Never speculate publicly about cause +- Confirm resolution explicitly when restored + +### 5. Resolution + +Verified fix, customers restored, incident closed. + +Resolution criteria: + +- Mitigation in place and verified +- Root cause identified (or explicitly deferred to AAR) +- All affected systems back to normal +- Customers can resume normal use +- Final status update posted (internal and external) +- Incident channel can be closed (or archived for AAR) + +After closure: +- Schedule AAR within 1 to 2 weeks +- Capture initial timeline while memories are fresh +- Track follow-up action items + +--- + +## Roles during an incident + +\| Role \| Responsibility \| +\|---\|---\| +\| Incident commander (IC) \| Owns the response. Calls decisions. Assigns work. Not necessarily the most technical person; needs to coordinate. \| +\| Communications lead \| Owns internal and external messaging. Reduces IC's communication burden. \| +\| Operations lead \| Drives the technical investigation and mitigation. Often the most senior on-call engineer. \| +\| Scribe \| Captures the timeline as the incident unfolds. Critical for AAR. \| +\| Subject matter experts \| Pulled in as needed. Service owners, database experts, security experts. \| + +For small teams or low-severity incidents, one person can hold multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Decision-making during an incident + +The IC's authority: + +- Call rollback or other mitigations +- Pull additional people in +- Escalate severity +- Make the call when unclear options exist + +Non-decisions to avoid: + +- "Let's wait and see" when mitigations are available and impact is occurring +- Discussing root cause while users are actively impacted (mitigate first) +- Premature resolution announcements before verification +- Death-by-committee (pull in lots of people, no one decides) + +When in doubt: act. A wrong action that can be rolled back beats inaction while users suffer. + +--- + +## Status page communication patterns + +Initial: +> "We are investigating reports of [issue]. Updates to follow." + +Identified: +> "We have identified the issue affecting [scope]. Engineers are working on a fix. Next update by [time]." + +Monitoring: +> "A fix has been applied. We are monitoring to confirm resolution. Next update by [time]." + +Resolved: +> "This incident has been resolved. Service has been restored. A full incident report will be posted within [timeframe]." + +Patterns to avoid: + +- Vague language ("experiencing some issues" - what kind?) +- Missing affected scope ("login is down" - everywhere or just one region?) +- Missing time commitments +- "Should be resolved soon" without verification +- Using "back up" before verification + +--- + +## Workflow + +1. Acknowledge. First responder acknowledges within target time. +2. Assess severity. Use the rubric. Open the appropriate response channel. +3. Assign roles. IC, comms, ops at minimum. +4. Communicate. Initial status update. Internal channel active. +5. Investigate. Logs, metrics, recent changes. The four most common causes: a recent deploy, a configuration change, a third-party dependency change, a load spike. +6. Mitigate. Stop the bleeding. Don't wait for full root cause. +7. Verify mitigation. Don't trust dashboards alone; test the user flow. +8. Communicate resolution. Internal and external. +9. Close incident. Final timeline noted. Action items tracked. +10. Schedule AAR. Within 1 to 2 weeks. + +--- + +## Failure patterns + +- No clear IC. Multiple people debugging in parallel, no coordination. Slower to mitigate, easier to make conflicting changes. +- Skipping mitigation, going straight to root cause. Users keep suffering while engineers debug. +- Premature "all clear." Announcing resolution before verification. +- Communication silence. Users don't know if anyone is working on it. +- Status updates too vague. "We're working on it" with no detail. +- Speculating publicly about cause. Often wrong, always damaging trust. +- Pulling in too many people. Coordination overhead exceeds value. +- No scribe. The timeline gets lost. AAR has to reconstruct from chat logs. +- Skipping AAR for "minor" incidents. Patterns get missed. Lessons get re-learned. +- Blame culture. People hide mistakes, incidents take longer. + +--- + +## Output format + +During an active incident: incident channel updates and status page updates as per the framework above. + +After incident close: a brief incident summary feeding into the AAR. + +```markdown +# Incident: [Brief title] + +Date: [YYYY-MM-DD] +Severity: [SEV-1 / 2 / 3 / 4] +Duration: [Detection to resolution] +Customer impact: [Who, how many, how] + +## Summary +[1 to 2 paragraphs] + +## Timeline +[Timestamped events] + +## Mitigation +[What was done] + +## Action items +[Follow-ups, with owners] + +## AAR scheduled for +[Date] +``` + +--- + +## Reference files + +- [`references/incident-playbook.md`](references/incident-playbook.md) - Severity definitions, roles, status page templates, decision rubrics. diff --git a/skills/incident-response/references/incident-playbook.md b/skills/incident-response/references/incident-playbook.md new file mode 100644 index 0000000..b960f45 --- /dev/null +++ b/skills/incident-response/references/incident-playbook.md @@ -0,0 +1,280 @@ +# Incident Playbook + +The reference document during an incident. Severity definitions, role responsibilities, communication templates, and decision rubrics. + +--- + +## Severity rubric + +### SEV-1: Critical + +Definition: +- Major customer-facing functionality completely broken +- Data loss or data integrity at risk +- Active security breach or vulnerability being exploited +- Significant revenue impact ongoing + +Response: +- All-hands response activated +- Incident commander assigned (within 10 minutes of detection) +- War room (video call) opened +- Public status page updated immediately +- Executive notification within 15 minutes +- Customer-facing communication within 30 minutes + +Acknowledgment SLA: 5 minutes +Update cadence: Every 15 minutes +Resolution target: As fast as humanly possible + +### SEV-2: Major + +Definition: +- Significant degradation affecting many users +- Important feature unavailable +- Performance severely degraded +- Revenue impact, but limited + +Response: +- Incident commander assigned (within 30 minutes) +- Active investigation in incident channel +- Status page updated +- Internal communication to broader org +- Public communication if customer-facing + +Acknowledgment SLA: 15 minutes +Update cadence: Every 30 minutes +Resolution target: Within hours + +### SEV-3: Minor + +Definition: +- Limited impact (specific feature, specific user segment) +- Workaround available +- No revenue impact, or minor + +Response: +- Single owner assigned +- Standard on-call response +- No status page update unless customer-facing +- No public communication unless trending + +Acknowledgment SLA: 1 hour +Update cadence: As progress dictates +Resolution target: Within a day + +### SEV-4: Low + +Definition: +- Cosmetic issue +- Edge case affecting few users +- No customer impact + +Response: +- Track as bug, not incident +- Address in normal queue + +Acknowledgment SLA: Next business day +Resolution target: As prioritized + +--- + +## Roles + +### Incident Commander (IC) + +Responsibilities: +- Owns the response +- Makes decisions when options exist +- Assigns work to others +- Decides when to escalate severity +- Decides when to declare resolution +- Coordinates without doing technical work themselves + +NOT the IC's job: +- Doing the actual debugging +- Speculating about cause publicly +- Writing status page updates (delegates to comms lead) + +Selection criteria: Calm under pressure, good at coordination, clear communicator. Does not need to be the most senior or most technical. + +### Communications Lead + +Responsibilities: +- Posts internal updates on schedule +- Drafts status page updates +- Coordinates with customer support +- Drafts executive notifications +- Manages external messaging + +Removes: Communication burden from IC and ops lead. + +### Operations Lead + +Responsibilities: +- Drives the technical investigation +- Identifies the cause +- Identifies and applies mitigations +- Coordinates with subject matter experts +- Verifies fixes + +### Scribe + +Responsibilities: +- Captures the timeline as the incident unfolds +- Records decisions and rationale +- Records actions taken +- Provides material for the AAR + +Often filled by: A junior engineer (good learning experience), someone not in the active investigation, or anyone tasked specifically with note-taking. + +### Subject Matter Experts (SMEs) + +Pulled in as needed. Service owners, database experts, security experts, third-party vendors. Pulled by IC, not self-deploying. + +--- + +## Status page templates + +### SEV-1 / SEV-2 initial + +> "We are currently investigating reports of [user-facing description of impact]. Affected users may experience [specific symptoms]. We will update by [time, typically +30 minutes]." + +### Identified + +> "We have identified the cause of the issue affecting [scope]. Engineers are deploying a fix. Next update by [time]." + +### Monitoring + +> "A fix has been applied. We are monitoring to confirm full resolution. Next update by [time]." + +### Resolved + +> "This incident has been resolved. All services have returned to normal. A full incident report will be posted within [typically 1 week]. Thank you for your patience." + +### Patterns to avoid + +\| Avoid \| Why \| Use instead \| +\|---\|---\|---\| +\| "Some users may be experiencing issues" \| Vague \| "Users in [region] may experience [specific symptom]" \| +\| "We are working on it" \| Empty \| "Engineers are investigating [hypothesis or symptom]" \| +\| "Should be resolved shortly" \| Speculative \| "Next update by [specific time]" \| +\| "We apologize for the inconvenience" \| Hollow \| Acknowledge specifically, then state action \| +\| Technical jargon \| Excludes users \| Plain language describing user experience \| +\| Blame language \| "Our database vendor failed" \| Focus on user impact and our response \| + +--- + +## Decision rubrics + +### Should we roll back? + +Roll back if: +- A recent deploy correlates with the start of the incident +- Rollback can be completed safely +- The risk of leaving the broken state exceeds the risk of rollback + +Don't roll back if: +- The incident clearly predates the recent deploy +- Rollback would cause data loss or worse impact +- A targeted fix is available and faster + +When unsure: roll back. Recovery from rollback is usually cheaper than continued debugging in a broken state. + +### Should we declare SEV-1? + +Declare SEV-1 if any are true: +- Most users cannot use the core product +- Revenue is being lost at significant rate +- Data integrity is at risk +- A security breach is happening +- Senior leadership awareness is required + +When unsure between SEV-1 and SEV-2: start with SEV-1. Easier to de-escalate than to scale up. + +### Should we communicate publicly? + +Communicate publicly if any are true: +- Customers are experiencing impact and will notice +- Customer support is receiving inquiries +- The incident is visible externally (status page, social media chatter) +- Regulatory notification may be required (data breach, certain financial systems) + +Don't communicate publicly if: +- Impact is invisible to users +- Confidence is high that it will be resolved before users notice (but lean toward communication) + +When unsure: communicate. Silence on the status page is worse than a brief acknowledgment. + +### Should we escalate? + +Escalate to senior leadership if: +- Severity has reached SEV-1 +- Resolution is taking longer than expected at SEV-2 +- Decisions are needed that exceed the IC's authority +- Reputational risk is material + +--- + +## On-call rotation principles + +A healthy on-call: + +- Rotates regularly. Same person on call indefinitely is unsustainable. +- Has a clear primary and secondary. Backup if primary is unavailable. +- Has documented runbooks. On-call is not pop quiz. +- Has acknowledgment SLAs that match severity. A 1-hour SLA on SEV-1 is too slow. +- Is paid or compensated in some form. Time on-call has cost. +- Includes a hand-off ritual. Outgoing on-call briefs incoming on open issues, recent deploys, hot spots. + +Anti-patterns: + +- One person who is "always on" because they know the system best +- On-call without monitoring (you can only respond to what you know) +- On-call who lacks production access (cannot mitigate) +- No primary/backup, just one person + +--- + +## Common mitigation patterns + +\| Symptom \| Try first \| +\|---\|---\| +\| Errors after recent deploy \| Roll back the deploy \| +\| Errors with no recent deploy \| Check third-party dependencies, recent config changes \| +\| Database errors \| Check connection pool, recent query changes, capacity \| +\| Latency spike \| Check load, capacity, slow downstream \| +\| Specific feature broken \| Feature flag off if available \| +\| Security incident \| Isolate affected systems, rotate credentials, preserve logs \| +\| Data integrity issue \| Stop writes, snapshot, investigate before continuing \| + +When unsure of cause but mitigation is available: mitigate. Investigate cause separately. + +--- + +## After the incident + +Once resolved: + +1. Final status page update (resolved) +2. Final internal update +3. Capture initial timeline (the scribe's notes) +4. Identify obvious follow-up action items, file tickets +5. Schedule AAR within 1 to 2 weeks +6. Hand off any monitoring to normal operations + +In the next 24 to 48 hours, while memory is fresh: + +- Each participant writes their own brief account of what they observed and did +- These individual accounts become primary source material for the AAR +- This avoids reconstruction errors that come from trying to piece together what happened weeks later + +--- + +## Anti-patterns to call out + +- Hero culture. One person stays up all night to fix it; gets praised. Real lesson: the system is too brittle, and the team has too little redundancy. +- Blame in retrospectives. "Whose fault was this?" produces hidden mistakes next time. +- Skipping AARs for "minor" incidents. The minor incidents are often the patterns that predict major ones. +- Action items that never close. Action items get filed, never actioned. The same incident recurs. +- Status pages updated only at start and end. "Updating every 30 minutes" with the same content is still better than silence. +- Investigating root cause while users are impacted. Mitigate first. diff --git a/skills/information-architecture/SKILL.md b/skills/information-architecture/SKILL.md new file mode 100644 index 0000000..b77d8a7 --- /dev/null +++ b/skills/information-architecture/SKILL.md @@ -0,0 +1,254 @@ +--- +name: information-architecture +description: "Design the structure of a website or product including sitemap, navigation, URL structure, content types, taxonomy, and labeling. Use this skill whenever the user asks to plan a sitemap, design navigation, structure URLs, define content types, build taxonomies, design site search, or organize content at the system level. Triggers on sitemap, site structure, navigation, IA, information architecture, URL structure, content types, taxonomy, categorization, breadcrumbs, hub pages, faceted navigation, site search, labeling. Also triggers when content is being created without a structural plan, or when an existing site's structure is being audited or restructured." +category: strategy-and-discovery +catalog_summary: "Sitemap, navigation, URL structure, content types, taxonomy" +display_order: 4 +--- + +# Information Architecture + +Design the structure that holds the content. Stack-agnostic. Applies to marketing sites, product surfaces, knowledge bases, e-commerce, and editorial content. + +A well-designed IA makes the rest of the project easier. A poorly-designed IA forces every downstream decision to fight the structure. + +--- + +## When to use + +- Designing a new site or major section from scratch +- Restructuring an existing site +- Adding a new content type or category +- Designing site navigation or menu systems +- Defining URL structure and slug patterns +- Building taxonomies or tag systems +- Auditing an existing IA for problems + +## When NOT to use + +- Single-page design (use `design-standards`) +- Content production (use `content-and-copy`) +- SEO-driven content planning (use `seo-keyword`) +- Initial brand and audience discovery (use `brand-discovery`) + +--- + +## Required inputs + +- The site or product scope +- The audience and what they're trying to do +- The content that exists or is planned +- Any constraints (parent IA, regulatory, technical) + +If audience is unclear, run `brand-discovery` first. If content scope is unclear, run `content-strategy` first. + +--- + +## The framework: 6 layers + +Information architecture has six layers. Each builds on the one below. + +### 1. Mental models + +Before structure, understand how the audience thinks about the domain. + +- What concepts do they group together naturally? +- What words do they use? (Often different from what the company uses.) +- What is the dominant frame of reference? (By task? By role? By topic? By time?) +- What do they expect to find where, based on conventions in similar products? + +Methods: + +- Card sorting (open or closed): Give the audience the content items, ask them to group them. Open card sorts surface natural groupings. Closed card sorts validate proposed groupings. +- Tree testing: Give a proposed structure, ask users to find specific items. Surfaces where the structure breaks down. +- First-click testing: Given a goal, where do users click first? If first clicks are wrong, the labels and structure are wrong. + +### 2. Sitemap + +The map of all pages and how they relate. + +Sitemap deliverables: + +- A hierarchy diagram showing parent-child relationships +- Indication of page types (static, dynamic, listing, detail) +- Cross-references showing how pages relate beyond the hierarchy +- Sometimes a separate user-flow overlay for key journeys + +Sitemap types: + +- Hub-and-spoke (cornerstone content + supporting content): Common for content marketing +- Tree (strict hierarchy, every page has one parent): Common for product documentation +- Faceted (content lives in many overlapping categories): Common for e-commerce +- Flat (everything reachable from the home): Common for small sites + +Most sites blend types. Pick the dominant pattern and document the exceptions. + +### 3. URL structure + +URLs are part of the IA. They are user-facing, indexed by search engines, and shape how content is referenced. + +URL principles: + +- Reflect the content hierarchy +- Lowercase, hyphen-separated +- Predictable (same pattern across same content type) +- Stable (URLs don't change without redirects) +- Short (under 60 characters where possible) +- Descriptive (slug indicates the content) +- Free of dates unless time-bound +- Free of session IDs and tracking parameters in canonical form + +Common patterns: + +``` +/ home +/[section] section landing +/[section]/[subsection] subsection landing +/[section]/[subsection]/[item] detail page +/blog blog index +/blog/[slug] blog post +/blog/category/[category] category index +/blog/tag/[tag] tag index +/products product catalog +/products/[category] category page +/products/[category]/[product] product detail +``` + +Pick a pattern and stick to it. Inconsistent URL patterns confuse users, crawlers, and analytics. + +### 4. Navigation + +The chrome that gets users where they need to go. + +Primary navigation: + +- The top-level structure of the site +- Should reflect what the audience cares about, not what the org chart looks like +- 5 to 7 items maximum (more becomes cognitively heavy) +- Each label is recognizable in 2 to 3 words +- Order matters (left/first gets the most attention) + +Secondary navigation: + +- Within-section navigation +- Often shown as sidebars, sub-menus, or in-page tabs +- Supports the primary nav, doesn't duplicate it + +Utility navigation: + +- Account, search, login, support +- Visually subordinate to primary nav +- Often top-right (LTR languages) + +Breadcrumbs: + +- For nested hierarchies (3+ levels deep) +- Always linked except the current page +- Match the URL hierarchy or the conceptual hierarchy +- Marked up with BreadcrumbList schema + +Footer navigation: + +- Comprehensive; sometimes includes everything +- Organized by category for findability +- Includes secondary content (privacy, terms, contact) + +### 5. Taxonomy and metadata + +The classification system applied to content. + +Categories: + +- A small, controlled list (typically 5 to 15) +- Mutually exclusive ideal (one item, one category) +- Used for structural navigation + +Tags: + +- A larger, often growing list (50+) +- Multi-assignment (one item, many tags) +- Used for cross-cutting connections, related-content, and long-tail discovery + +Metadata fields: + +- Author, date, content type, audience segment +- Whatever is useful for filtering, sorting, and surfacing + +Common failures: + +- Categories that overlap (item could go in 3 different categories) +- Tags that are unmaintained (sprawl into thousands, become useless) +- Metadata fields that get filled inconsistently +- Different content types using different taxonomies for the same thing (chaos) + +### 6. Labeling + +What you call things. + +Label principles: + +- Audience language, not internal language +- Specific enough to be useful, short enough to scan +- Consistent across the site (call it "Product" or "Solutions" but not both) +- Tested with real users (closed card sort or tree test surfaces label problems) + +Common label problems: + +- "Solutions" (vague; usually means "products with marketing copy") +- "Resources" (catch-all; everything ends up there) +- Internal jargon ("PRD," "OKRs") that doesn't match user vocabulary +- Labels that change meaning across the site + +--- + +## Workflow + +1. Understand the audience and content. Use existing discovery and content strategy if available. +2. Card sort or interview to surface mental models. +3. Draft the sitemap. Hierarchy, page types, cross-references. +4. Define URL patterns. One pattern per content type. +5. Design navigation. Primary, secondary, utility, footer, breadcrumbs. +6. Build taxonomy. Categories (controlled, small) and tags (open, large). +7. Validate labels. Tree test or closed card sort with target users. +8. Document. Use the template in [`references/ia-document-template.md`](references/ia-document-template.md). +9. Hand off to design and development. IA decisions inform navigation components, URL routing, and taxonomy implementation. + +--- + +## Failure patterns + +- IA designed by org chart. "Engineering" and "Marketing" sections make sense to the company, not to the audience. +- Categories that proliferate. Every team adds a category for their thing. Becomes unscannable. Hold the line at 5 to 15. +- Tags that sprawl. No tag governance. Tags become a junk drawer. +- Inconsistent URL patterns. Some posts at /blog/[slug], some at /[slug], some at /articles/[slug]. Pick one. +- Navigation that hides primary content. The most important pages should be one click from home. +- Search as a substitute for IA. "Just use search" is not a structure. Search supports IA, doesn't replace it. +- No validation. Card sorts, tree tests, and first-click tests are cheap and surface huge problems early. +- Treating IA as a one-time deliverable. IA evolves with content. Plan for evolution. + +--- + +## Output format + +Default output is an IA document at `information-architecture.md` plus visual assets: + +1. Executive summary +2. Audience and mental models (synthesized) +3. Sitemap (hierarchical diagram) +4. URL structure (per content type) +5. Navigation specification (primary, secondary, utility, footer, breadcrumbs) +6. Taxonomy (categories and tag governance) +7. Labels (validated wording for navigation, categories, content types) +8. Implementation notes for design and development + +Visual deliverables: +- Sitemap diagram (Whimsical, Figma, OmniGraffle, etc.) +- Navigation wireframes for primary surfaces +- Optional: card sort and tree test results + +--- + +## Reference files + +- [`references/ia-document-template.md`](references/ia-document-template.md) - Template for the IA deliverable. +- [`references/url-pattern-library.md`](references/url-pattern-library.md) - URL pattern conventions for common content types. diff --git a/skills/information-architecture/references/ia-document-template.md b/skills/information-architecture/references/ia-document-template.md new file mode 100644 index 0000000..4f7ad12 --- /dev/null +++ b/skills/information-architecture/references/ia-document-template.md @@ -0,0 +1,298 @@ +# Information Architecture Document Template + +A fillable template for the IA deliverable. Captures the sitemap, navigation, content types, taxonomy, and URL conventions. + +The IA document is the single source of truth for "what is this site, structurally." Engineering, design, content, and SEO all reference it. + +--- + +## Project metadata + +Site / app: [Name] +Phase: [New build / restructure / refresh] +Date: [YYYY-MM-DD] +IA lead: [Name] +Status: [Draft / In review / Approved] + +--- + +## 1. Audience and intent + +The IA serves audience tasks. Start with the tasks. + +### Primary audiences + +\| Audience \| Top tasks on this site \| +\|---\|---\| +\| \| \| +\| \| \| +\| \| \| + +### Top tasks + +The 5-10 things people most commonly want to do or find. + +1. [Task] +2. [Task] +3. [Task] +4. [Task] +5. [Task] + +Each task should be discoverable in 3 clicks or fewer from the homepage. + +--- + +## 2. Sitemap + +The full set of pages the site contains, organized by hierarchy. + +### Top-level navigation + +The 4-7 sections that appear in the main nav. + +``` +Home +├── [Section 1] +├── [Section 2] +├── [Section 3] +├── [Section 4] +├── [Section 5] +└── [Utility nav: Login, Search, Cart, etc.] +``` + +### Full sitemap + +``` +Home (/) +├── Section 1 (/section-1/) +│ ├── Sub-page 1.1 (/section-1/sub-page-1-1/) +│ ├── Sub-page 1.2 (/section-1/sub-page-1-2/) +│ └── Sub-page 1.3 (/section-1/sub-page-1-3/) +├── Section 2 (/section-2/) +│ ├── Category 2.1 (/section-2/category-2-1/) +│ │ └── Detail pages (/section-2/category-2-1/[slug]/) +│ └── Category 2.2 (/section-2/category-2-2/) +├── Section 3 (/section-3/) +├── About (/about/) +├── Contact (/contact/) +├── Legal +│ ├── Privacy (/privacy/) +│ ├── Terms (/terms/) +│ └── Cookies (/cookies/) +└── 404 (/[unmatched]) +``` + +### Pages outside primary nav + +Pages that exist but are not in the top nav. Reachable from footers, contextual links, search, or direct entry. + +\| Page \| URL \| Reached from \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## 3. Navigation + +### Primary nav + +- Items: [List] +- Behavior on desktop: [Always visible / dropdown / mega menu] +- Behavior on mobile: [Hamburger / bottom nav / slide-in] +- Active state indicator: [Underline / color / weight] +- Sticky on scroll: [Yes / no] + +### Secondary nav + +If applicable. Examples: section nav within a section, sidebar nav for docs, breadcrumbs. + +- Used in: [Sections] +- Pattern: [Sidebar / breadcrumbs / tabs / pills] + +### Utility nav + +Login, search, cart, language switcher, account. Where they live on desktop and mobile. + +### Footer nav + +Comprehensive map of the site, plus legal and contact. + +- Sections: [Group names and what is in each] +- Treatment: [Links only / links + descriptions / multi-column / single column on mobile] + +--- + +## 4. Content types + +The reusable patterns that pages fall into. Each content type has a defined schema. + +### Content type: [Name, e.g., "Article"] + +- Purpose: [What this content type is for] +- Required fields: [Title, body, author, publish date, etc.] +- Optional fields: [Hero image, related articles, summary] +- URL pattern: [`/blog/[slug]/`] +- Template: [Which page template renders this] +- SEO defaults: [Default title pattern, meta description pattern, schema type] +- Open Graph defaults: [OG image source, OG type] + +(Repeat for each content type: page, article, product, case study, landing page, author, category, tag, etc.) + +--- + +## 5. Taxonomy + +How content is organized and tagged for filtering, related-content surfacing, and navigation. + +### Categories (hierarchical) + +The primary classification, often used in URLs. + +- Category 1 + - Subcategory 1.1 + - Subcategory 1.2 +- Category 2 + +Categories are typically mutually exclusive (a piece belongs to one). + +### Tags (flat, multi-select) + +Cross-cutting attributes a piece can have multiple of. + +- [Tag] +- [Tag] +- [Tag] + +### Custom taxonomies + +Domain-specific facets (e.g., for a recipe site: cuisine, dietary, cook time, meal type). + +\| Taxonomy \| Values \| Used by content types \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## 6. URL conventions + +See `url-pattern-library.md` for the full URL pattern reference. The IA document captures decisions specific to this site. + +\| Type \| Pattern \| Example \| +\|---\|---\|---\| +\| Home \| `/` \| `/` \| +\| Static page \| `/[slug]/` \| `/about/` \| +\| Section landing \| `/[section]/` \| `/products/` \| +\| Article detail \| `/blog/[slug]/` \| `/blog/how-to-x/` \| +\| Product detail \| `/products/[slug]/` \| `/products/widget/` \| +\| Category archive \| `/category/[slug]/` \| `/category/news/` \| +\| Tag archive \| `/tag/[slug]/` \| `/tag/announcements/` \| +\| Author page \| `/author/[slug]/` \| `/author/jane-doe/` \| +\| Search results \| `/search/?q=[query]` \| `/search/?q=widget` \| + +### Trailing slash policy + +[All URLs end with trailing slash / no trailing slash. Pick one and enforce via redirect.] + +### Casing + +[Lowercase only. Hyphens for word separation.] + +--- + +## 7. Search + +- In-site search included?: [Yes / no] +- Source of truth: [Internal index, Algolia, Elasticsearch, native CMS search] +- Surface in nav: [Always visible / icon-only / hidden behind utility nav] +- Result page URL: [`/search/?q=[query]`] +- Result types: [Pages, articles, products, etc.] +- Filters: [What filters appear on the result page] +- Empty-state message: [Text and suggested actions] + +--- + +## 8. Cross-linking strategy + +How pages link to other pages within the site. + +### Hub-and-spoke + +Pillar pages (hubs) link to related detailed pages (spokes). Spokes link back to the hub. + +\| Hub \| Spokes \| +\|---\|---\| +\| `/topic-area/` \| `/topic-area/[detail-1]`, `/topic-area/[detail-2]` \| + +### Related content blocks + +Where they appear, what populates them. + +- Article footer: [Same category / same tag / manually curated] +- Product detail page: [Same category, similar price, frequently bought with] +- Sidebar: [Trending, recent] + +### Contextual links in body copy + +The single highest-value cross-link mechanism. Editorial guidelines: + +- Link the first natural mention of a related topic +- 2-5 contextual links per article +- Anchor text describes the destination, not "click here" + +--- + +## 9. Pagination, infinite scroll, and load more + +For listing pages (archives, search, category, etc.). + +\| Listing type \| Pattern \| Page size \| URL behavior \| +\|---\|---\|---\|---\| +\| Article archive \| Pagination \| 10 per page \| `/blog/page/2/` \| +\| Search results \| Load more \| 20 per page \| URL stays at `/search/?q=...` \| +\| Product grid \| Pagination \| 24 per page \| `/products/?page=2` \| + +Pick deliberately. Each pattern affects SEO, accessibility, and analytics. + +--- + +## 10. Multilingual / multi-region + +If applicable. See `internationalization` skill for full guidance. + +- Languages supported: [List] +- Regions supported: [List] +- URL pattern for locale: [`/en/`, `/es/` subdir / `en.example.com` subdomain / no prefix on default locale] +- Hreflang strategy: [How locale alternates are declared] +- Default locale fallback: [What happens for unmatched locales] + +--- + +## 11. Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## 12. Change log + +\| Date \| Change \| Approved by \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +--- + +## Sign-off + +IA approved by: + +- IA lead: [Name, date] +- Engineering lead: [Name, date] +- Content lead: [Name, date] +- SEO lead: [Name, date] + +Implementation can begin: [Date] diff --git a/skills/information-architecture/references/url-pattern-library.md b/skills/information-architecture/references/url-pattern-library.md new file mode 100644 index 0000000..75bf052 --- /dev/null +++ b/skills/information-architecture/references/url-pattern-library.md @@ -0,0 +1,377 @@ +# URL Pattern Library + +Conventional URL patterns for common content types. Use as a starting point. Adapt for the specific site. + +URL patterns matter because: +- Users see them in the address bar +- Search engines use them as a relevance signal +- They appear in shared links and citations +- Inconsistent patterns are a structural smell that creates downstream problems + +--- + +## Universal principles + +Apply to every URL on every site: + +- Lowercase. `/about` not `/About`. +- Hyphens, not underscores. `/blog/getting-started` not `/blog/getting_started`. +- No trailing slash for non-folder URLs (or always with trailing slash; pick one and be consistent). +- No file extensions. `/about` not `/about.html` or `/about.php`. +- No query strings in canonical URLs. Filters and sorts can use query strings, but the canonical version is parameter-free. +- Stable. URLs do not change without a 301 redirect from the old URL. +- Predictable. Same content type uses the same URL pattern site-wide. + +--- + +## Marketing site patterns + +### Home + +``` +/ +``` + +### Top-level pages + +``` +/about +/contact +/pricing +/careers +/blog +/help +``` + +Avoid generic catch-alls like `/info` or `/page`. + +### Sub-pages within sections + +``` +/about/team +/about/values +/about/history +/careers/engineering +/careers/design +``` + +Two levels deep is the typical maximum for marketing site pages. Beyond that, structure usually breaks down. + +### Marketing landing pages + +``` +/[campaign-slug] short, memorable, often used in print/ads +/lp/[campaign-slug] namespaced under /lp for clarity +/[product]/[campaign] nested under product if relevant +``` + +For high-traffic ad campaigns, a short root-level URL is fine. For evergreen marketing pages, namespace them. + +--- + +## Blog and editorial patterns + +### Blog index + +``` +/blog +``` + +### Blog posts + +``` +/blog/[slug] +``` + +The dominant pattern. Simple, scannable, no dates in the URL (so updates don't change the URL). + +If dates are genuinely required (news sites, time-sensitive content): + +``` +/blog/[year]/[month]/[slug] +``` + +But avoid dates by default. They make URLs longer and stale-looking when content gets updated. + +### Categories and tags + +``` +/blog/category/[category-slug] +/blog/tag/[tag-slug] +``` + +Or, if you prefer cleaner URLs: + +``` +/blog/[category-slug]/[post-slug] embeds category in the post URL +``` + +The embedded version is cleaner but creates URL changes when posts move categories. Pick based on whether posts move categories. + +### Author pages + +``` +/author/[author-slug] +/blog/author/[author-slug] +``` + +The first if authors are site-wide. The second if authors are blog-specific. + +### Archive pages + +``` +/blog/archive/[year] +/blog/archive/[year]/[month] +``` + +Optional, mostly for SEO and historical browsing. Often noindexed if they don't add unique value. + +--- + +## Product / e-commerce patterns + +### Product catalog + +``` +/products +/shop +``` + +Pick one and use site-wide. Don't have both. + +### Categories + +``` +/products/[category] +``` + +### Sub-categories + +``` +/products/[category]/[subcategory] +``` + +Two levels of category is typical maximum. Deeper hierarchies hurt findability. + +### Product detail + +``` +/products/[category]/[product-slug] +/products/[product-slug] if categorization isn't critical +``` + +The first is more SEO-friendly (signals category relevance). The second is cleaner but loses the hierarchy signal. + +### Filters and search + +``` +/products/[category]?filter=value&sort=price-asc filters as query strings +``` + +Canonical URL ignores query strings. Use the bare category URL as the canonical. + +--- + +## Documentation patterns + +### Docs root + +``` +/docs +/help +/support +``` + +### Sections + +``` +/docs/getting-started +/docs/api +/docs/integrations +``` + +### Pages within sections + +``` +/docs/getting-started/installation +/docs/api/authentication +/docs/integrations/slack +``` + +Two to three levels is typical. Deeper hierarchies become hard to navigate. + +### API reference + +``` +/docs/api/[endpoint] +/docs/api/v[N]/[endpoint] versioned APIs +/api-reference/[endpoint] if API docs are separate +``` + +--- + +## Account and product surface patterns + +These are the URLs inside an authenticated product. Not visible to crawlers but still matter for usability and consistency. + +### Dashboard + +``` +/dashboard +/app +/home inside the product, not the marketing site +``` + +### Settings + +``` +/settings +/settings/[section] +/account +/account/[section] +``` + +### Resources within an account + +``` +/projects +/projects/[id] +/projects/[id]/[resource] +/projects/[id]/[resource]/[item-id] +``` + +For e-commerce or SaaS, IDs matter more than slugs since these are user-specific items. + +--- + +## Special URL patterns + +### Search results + +``` +/search?q=[query] +``` + +Or, for SEO-friendly search landing pages: + +``` +/search/[query] +/find/[query] +``` + +The second pattern creates indexable search pages, which can be useful or harmful depending on the site. + +### Filter/facet pages (e-commerce or directory) + +``` +/[category]/[filter-slug] e.g., /running-shoes/men +/[category]?[filter]=[value] filters via query string +``` + +Static filter pages are SEO-friendly. Dynamic query strings are cleaner but don't index. + +### Pagination + +``` +/blog/page/2 +/blog/page/3 +/blog?page=2 via query string +``` + +The path-based version is more SEO-friendly. Either works as long as you canonical correctly. + +### Profile pages + +``` +/u/[username] +/users/[username] +/profile/[username] +/[username] if usernames don't conflict with other paths +``` + +The last (root-level usernames) is the cleanest but requires careful conflict prevention. + +### Internationalization + +``` +/[locale]/[path] e.g., /en/about, /es/about +[subdomain].domain.com/[path] e.g., en.domain.com/about +domain.[ccTLD]/[path] e.g., domain.fr/about +``` + +Each has tradeoffs. Path-based is most flexible. Subdomain is good for cleanly separated content. ccTLD is best for genuine country targeting. + +Use hreflang tags to indicate language pairs regardless of the URL strategy. + +--- + +## URL anti-patterns + +### Anti-pattern: Tracking parameters in canonical URLs + +``` +Bad: /post?utm_source=newsletter +Good: /post (with utm parameters preserved at runtime but stripped from canonical) +``` + +UTM parameters are for analytics, not for canonical URLs. + +### Anti-pattern: Session IDs in URLs + +``` +Bad: /products?sid=ABC123 +Good: /products (session in cookies, not URL) +``` + +URLs should be safe to share. Session IDs in URLs leak sessions when shared. + +### Anti-pattern: Verb-heavy URLs + +``` +Bad: /show-product/[id] +Good: /products/[id] +``` + +URLs are nouns, not verbs. + +### Anti-pattern: Date in URLs for evergreen content + +``` +Bad: /blog/2024/05/how-to-write-headlines +Good: /blog/how-to-write-headlines +``` + +Dates make URLs feel stale. They also break when posts get updated. + +### Anti-pattern: Stop words in URLs + +``` +Acceptable: /the-best-running-shoes +Better: /best-running-shoes +``` + +Removing "the," "and," "of" makes URLs shorter without losing meaning. + +### Anti-pattern: Fragment-only navigation + +``` +Bad: /home#features (no /features page) +Good: /features (real URL) +``` + +Fragments don't index. Real pages do. + +--- + +## Migration considerations + +When changing URL patterns on an existing site: + +1. Map every old URL to a new URL. No exceptions. +2. 301 redirect old URLs to new. Permanent redirect preserves SEO equity. +3. Avoid redirect chains. Old URL should redirect directly to the new URL, not to an intermediate. +4. Update internal links. Every internal link should point at the new URL, not the old. +5. Update sitemap. New URLs only, no legacy URLs. +6. Wait 90+ days before removing redirects. Search engines and external sites take time to update. + +See `seo-technical/references/migration-checklist.md` for the full migration playbook. diff --git a/skills/integration-orchestrator/SKILL.md b/skills/integration-orchestrator/SKILL.md new file mode 100644 index 0000000..9a80690 --- /dev/null +++ b/skills/integration-orchestrator/SKILL.md @@ -0,0 +1,171 @@ +--- +name: integration-orchestrator +description: "Generate a phased delivery orchestration plan for creative-direction-driven work: which skills run when, what locks at which gate, how handoffs occur, and how the cadence implements in the team's tools (Jira, Linear, Notion, Figma, GitHub) with AI agents via MCP and CLI. A temporal map of phases, lock points, handoff specs, gate definitions, and QA verification gates. Distinct from `creative-brief` (static project brief) and `creative-direction` (aesthetic direction). Triggers on integration orchestrator, delivery cadence, project orchestration, when does the brief lock, how to phase creative direction, design-development handoff, QA gate, agent-driven QA, and when a creative-direction project is starting, mid-flight with broken cadence, or integrating AI agents into PM workflow. Does NOT fire for project scoping (use `creative-brief`), aesthetic direction (use `creative-direction`), or general project management without a creative-direction throughline." +category: product +catalog_summary: "Sequence creative-direction work across phases, gates, handoffs, and QA verification" +display_order: 3 +--- + +# Integration Orchestrator + +A brief tells a team what to make. Creative direction tells them what it should feel like. Neither tells them when each decision locks, who reviews what, or what stops the next phase from starting before the prior one is done. That is the gap this skill fills. + +The output is a phased orchestration plan the PM can paste into a calendar Monday morning and start running Tuesday. Phases, gates, lock points, handoffs, QA verification rules, and a platform-specific implementation guide for whatever stack the team actually uses (Jira, Linear, Notion, Figma, GitHub, agile sprints). + +--- + +## What this skill is + +A creative-direction project has three layers. The brief layer defines scope, audience, deliverables, constraints, success criteria. The direction layer defines tone, aesthetic, relationship, and sensory ambition. Both produce written artifacts. Neither answers the temporal question: when does the brief lock, when does identity lock, when does copy lock, who reviews each, what gets blocked while a gate is open, what happens when a downstream task discovers the brief is wrong, and what makes "Done" mean tested rather than self-reported. + +This skill produces that temporal layer. Most teams have briefs and creative direction but no orchestration plan. The result, by week 3, is everyone working in parallel with no shared sense of which decisions are still open and which are locked. Brief drift. Re-work. Identity tokens shifted after copy was already drafted against the old ones. Engineering shipping before design had a chance to review. "Done" tickets that were never actually verified. + +The orchestration plan answers all of that. It is not theory. It is a phased timeline with calendar weeks, ticket templates the PM can paste into Jira or Linear, MCP commands for setup, gate definitions with measurable pass criteria, handoff specs with artifact requirements, and QA verification gates with Playwright or Chrome MCP invocations. + +--- + +## When to use + +- Starting a new brand build, rebrand, or campaign and the team needs to sequence the work +- Mid-flight project where the brief is being revisited and downstream work is suffering from constant resets +- Setting up a new team's agent-driven workflow with MCPs and CLI integration +- Multi-team work where handoffs between brand, design, and engineering have broken down +- Establishing QA verification gates so "Done" is measurable, not self-reported +- Migrating from ad-hoc orchestration to a documented cadence +- Onboarding a new PM or design lead onto an existing project that has running tickets but no documented sequencing +- Adding new platforms or tools to an existing workflow and the cadence needs to be re-mapped + +--- + +## When NOT to use + +- Use `creative-brief` instead if the deliverable is the project brief itself: scope, audience, deliverables, constraints, success criteria. The orchestrator skill takes the brief as input. +- Use `creative-direction` if the deliverable is the aesthetic direction: tone, aesthetic, relationship, sensory. The orchestrator schedules the work that answers to the direction; it does not produce the direction. +- Generic project management software is the platform; this skill produces the plan that runs IN the platform. Do not run this skill if the team needs help picking a tool; it assumes the tool stack is already chosen. +- Sprint-planning tactics (story-pointing, retros, velocity charts) live downstream of orchestration. The skill produces the cadence; sprint planning fills it in. + +--- + +## Required inputs + +- Project type. New brand build, rebrand, single landing page, campaign, identity refresh, website refresh, microsite, product launch. The type implies a default phase decomposition that the skill adapts to the specific project. +- Team composition. Total size and role mix. Solo, small (2-3), medium (4-7), large (8+). Whether AI agents (Claude Code, Claude in Chrome, others) participate in production, QA, or both. +- Tool stack. Which of Jira, Linear, Notion, Figma, GitHub the team uses. Plus QA tooling (Playwright, Chrome MCP, Windows MCP, mobile testing harnesses) if known. Plus communication and paging channel (Slack, email, in-tool mention). The output adapts to the actual stack. +- Timeline target. Express (compressed timelines, fewer reviewers, accept higher rework risk), standard (typical cadence at the project type's default duration), or thorough (more reviewers, formal phase reviews, lower rework risk at the cost of slower delivery). +- Existing constraints. What is already locked? Brief approved, identity locked, platform fixed, brand voice already shipped, content management system non-negotiable. The orchestrator plan handles greenfield and mid-flight equally; the existing constraints input is how mid-flight projects are accommodated. +- AI agent participation. Which workflows include agents and at what fidelity. Examples: Claude Code does production tasks against a state file in the repo; Claude in Chrome runs human-readable QA flows on the staging deployment; the agent has access to the Linear MCP and the GitHub MCP but not Jira; the agent can move tickets between Todo, In Progress, Waiting, and Blocked but cannot move to Done (Done requires a human verification step). +- Risk profile. Optional input naming the failure modes the team is most worried about: brief drift, parallel-work conflicts, QA gaps, agent runaway. The orchestration plan front-loads mitigations for the named risks. + +--- + +## The framework: 7 considerations for orchestration + +A delivery orchestration plan sits at the intersection of seven considerations. Each filters the choices that follow. + +### 1. Phasing + +How the project decomposes into phases. The standard shape is discovery, direction, identity, production, QA, and launch. Not every project type uses every phase. A campaign skips identity (it inherits the locked brand identity). A landing page collapses discovery and direction into a single brief phase. A rebrand replaces discovery with audit (positioning is known; the audit assesses what to keep). + +The shape of the phases matters less than the explicit answer to two questions per project: which phases run sequentially because the downstream phase cannot start without the prior phase's output, and which phases overlap because their outputs do not depend on each other. Identity must complete before copy starts (copy depends on tone-axis position, which is part of identity). QA must complete before launch. Discovery and audit may overlap with brief drafting, because the brief consumes discovery findings as they emerge. + +### 2. Gates + +A gate is the approval moment that governs phase transition. The standard gates are brief approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, and launch readiness. Each gate has a trigger (the work that opens it), an approver (the person or test suite that passes it), required-to-pass criteria (the measurable thing that says yes or no), what's blocked until the gate passes, and what's already locked from prior gates. + +Gates work when the criteria are measurable. "Brief approved" is too vague; "client signed the brief artifact in writing or in a recorded review" is measurable. "QA passed" is too vague; "Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained" is measurable. Gates that are not measurable become political; gates that are measurable become structural. + +### 3. Lock points + +A lock point is the moment an artifact becomes immutable. The brief locks after direction is approved. Identity tokens lock after the identity gate. Voice rules lock after voice approval. Copy locks per page after copy approval. Once locked, the artifact cannot be changed by downstream work; it can only change via a formal change request that triggers re-review of dependent work. + +Without explicit lock points, every artifact is conceptually editable forever. That is the source of brief drift. The orchestrator plan names what locks at which gate, where the locked artifact lives, who can request a change, and what gets re-reviewed if a change is approved. Locked is not the same as final; locked means "any further change to this triggers downstream review work, so make changes deliberately." + +### 4. Handoffs + +A handoff is the moment work transfers between phases or skills. The standard handoffs are discovery to brief, brief to identity, brief to voice, identity plus voice to copy, identity plus copy to design, design to engineering, engineering to launch. Each transfers specific artifacts and decisions. Each leaves some things open and locks others. + +There is also a cross-cutting handoff: the adjacent observation handoff. While working on the homepage hero, an agent or person notices the footer copy is inconsistent with the new voice. That observation is not the current task. It is filed as an observation in the project triage queue. The PM or tech lead reviews observations on a regular cadence and triages them into proper tickets. This pattern keeps current work focused while not losing the contextually-relevant findings the team would otherwise either drop or derail current work to address. + +### 5. Team-size modulation + +A 2-person team and a 12-person team need different orchestration. Solo work is one person playing every role. Small (2-3) means a single reviewer per gate and async handoffs are fine. Medium (4-7) needs multiple reviewers and async sync points. Large (8+) needs formal phase reviews, a dedicated PM for orchestration, and explicit cross-track sync ceremonies because parallel tracks drift apart without them. + +The orchestration plan output modulates by scale. Solo gets self-review checklists per phase. Small gets per-gate "review by" assignments. Medium gets reviewer rotation and within-phase mini-gates. Large gets formal phase reviews, cross-track sync, and a brief-owner role. The framework is the same; the cadence's review density and ceremony level change. + +### 6. Tool-stack implementation + +Phases and gates exist in concept; they implement in tools. The orchestration plan specifies the implementation per platform: in Jira, phases become Epics with custom fields for "Phase", "Locked", "Approver", and "Gate Status"; in Linear, phases become Projects with cycles and label-driven views; in Notion, the brief becomes a database row with relation properties tying to direction docs, identity specs, voice guides, and copy decks; in Figma, phases become library folders with frame-level review status; in GitHub, phases interact with branch protection, PR templates, and CODEOWNERS-driven review routing. + +Where MCPs exist (Atlassian, Linear, Notion, GitHub), the plan specifies which orchestration setup operations the MCP can execute and which remain manual UI work. Where MCPs are limited (Figma's Dev Mode MCP is dev-mode-focused; the design library setup remains manual), the plan documents the recommendation without claiming end-to-end automation. + +### 7. Automation and QA verification + +The single most consequential discipline in the framework. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The standard status taxonomy is Todo, In Progress, Waiting, Blocked, Done. Blocked is a first-class status, distinct from Waiting. Waiting means the task is paused for normal handoff or scheduled review; Blocked means the task cannot proceed without human resolution of a specific issue. Agents move tasks to Blocked when they cannot autonomously resolve work; this prevents agents from spinning on un-resolvable problems and burning context. + +QA verification gates fire automatically. Playwright MCP runs critical-flow tests; Chrome MCP runs human-readable walkthroughs and captures evidence; Windows MCP handles desktop apps; mobile testing harnesses cover mobile applications. Failure routes to Blocked, files an adjacent observation if the failure surfaced something unrelated, pages the human via the configured channel, and stops. The agent does not retry autonomously. + +--- + +## Common project-type cadences + +Seven templates. Each is a skeletal phase map; the cadence-patterns reference file expands each. + +- New brand build. 6 to 8 weeks across 5 phases: Discovery (1 week), Direction (1 week), Identity (1 to 2 weeks), Production (2 to 3 weeks), Launch (1 week). Gates fire after each phase; identity locks before copy starts. +- Rebrand. 4 to 6 weeks across 4 phases: Audit (1 week, replaces Discovery), Direction (1 week), Identity (1 to 2 weeks), Production (1 to 2 weeks). Audit assumes positioning and audience are known; the work is assessing what to keep, drop, or refresh. +- Single landing page. 1 to 2 weeks across 3 phases: Brief (2 to 3 days), Production (5 to 7 days), QA-Launch (1 to 2 days). Identity is assumed locked. Voice is assumed locked. The work is page-specific copy, design, and engineering. +- Campaign. 2 to 4 weeks across 4 phases: Brief (3 to 5 days), Production (1 to 2 weeks), QA (3 to 5 days), Launch (1 to 2 days). Campaign assumes brand identity and voice exist and are locked. +- Identity refresh. 3 to 4 weeks across 3 phases: Audit (1 week), Identity (1 to 2 weeks), Production (1 week). Skips discovery and positioning. The output is a refreshed identity system that goes into production for application examples. +- Website refresh. 4 to 8 weeks across 4 phases: Audit (1 week), Direction (1 week), Production (2 to 4 weeks), QA-Launch (1 to 2 weeks). Direction may produce a refreshed brief if the audit surfaces positioning gaps. +- Microsite or product launch. 3 to 5 weeks across 4 phases: Brief (3 to 5 days), Production (2 to 3 weeks), QA (3 to 5 days), Launch (2 to 3 days). The microsite or product launch usually has a fixed launch date that drives backward planning. + +Each cadence reads as if the PM could paste it into a calendar and start running. Phase boundaries align with calendar weeks where possible, because that is how teams actually plan. + +--- + +## Failure patterns + +The orchestration plan exists to prevent these. Each is a real failure mode, observed in the wild on real projects. + +- Brief becomes a write-once doc. The brief is drafted, signed, then nobody references it again. Downstream work drifts. The fix: lock the brief at a gate and treat any reference to it as a reading, not an edit. +- Brief gets unfrozen mid-flight without re-reviewing dependent work. Someone tweaks the brief's audience or positioning; the change does not propagate to identity, voice, or copy that already depend on the old version. The fix: a formal change-request protocol that triggers re-review of dependent artifacts. +- Identity locks before voice. The typography is finalized before the voice is approved. Result: the type and the voice register conflict (a friendly voice in austere type, or a serious voice in casual type). The fix: voice approval gate fires before or alongside identity lock. +- Copy starts before voice locks. Writers draft against a moving target. Rework is invisible because the original draft never gets compared against the locked voice. The fix: voice approval before copy production. +- Multiple parallel design tracks lose brief alignment. Track A and Track B both interpret the brief slightly differently; by week 3 the two tracks read as different brands. The fix: cross-track sync ceremonies and a brief-owner role. +- Engineering starts before design freeze. Components get built against design that is still moving. Rework downstream when design lands somewhere else. The fix: design approval gate before engineering starts on the affected surface. +- Reviews stack at end of phase. Everyone defers their review to the final day; the gate becomes a 10-hour review marathon and approvers approve under fatigue. The fix: within-phase mini-gates that flatten review demand. +- Async handoffs without artifact specification. "Hand the design over to engineering" without specifying what artifacts (Figma file URL, exported tokens, asset library reference, PR draft template) means engineering opens half a dozen Slack threads to find what they need. The fix: explicit artifact specification per handoff. +- QA gate is self-reported. "Done" tickets get moved to Done without verification. Bugs land in production. The fix: automated verification that fires before status transitions to Done; failure routes to Blocked. +- Agents spin on un-resolvable work. A Claude Code task cannot resolve itself; the agent retries, burns context, runs out of tokens, leaves the work in a worse state than when it started. The fix: Blocked is a first-class status; agents move tasks to Blocked when they cannot autonomously resolve, document the blocker, and stop. + +--- + +## Output format + +Default output is a markdown document, typically saved as `ORCHESTRATION.md` at the project root or in a `docs/` subdirectory. The document contains the full plan and is the canonical reference for the team. + +Structure: + +1. Project orchestration plan. Phased timeline with calendar weeks, milestone dates, phase outputs. +2. Per-phase gate specs. What enters, what exits, who approves, the measurable pass criteria for each gate including the QA verification gate. +3. Lock-point register. What becomes immutable when, where the locked artifact lives, who can request a change, and what re-review work a change triggers. +4. Tool-stack implementation guide. Concrete setup for Jira, Linear, Notion, Figma, and GitHub as applicable, with MCP commands or CLI invocations for the parts that automate. +5. QA verification gate spec. Which automated tests must pass, which MCPs run them, where evidence attaches, what happens on failure. +6. Handoff specs. Artifacts transferred per handoff, locked items, change-request protocols, adjacent-observation routing. +7. Cross-skill dependency graph. Which skills run in which phase, what each skill consumes, what each produces. +8. Risk register. Cadence-specific risks with mitigations. + +The document is the orchestration plan. The next step after delivery is for the PM to set up the team's tools to match (Jira epics, Linear projects, Notion databases, Figma libraries, GitHub branch protection) and start running the plan. + +--- + +## Reference files + +- [`references/cadence-patterns.md`](references/cadence-patterns.md). The 7 project-type cadences in detail with phase decomposition, timelines, gate definitions, and tool-stack implementation skeletons. +- [`references/gate-definitions.md`](references/gate-definitions.md). Each standard gate with trigger, approver, pass criteria, what's blocked, what's already locked, and change-request protocols. +- [`references/handoff-protocols.md`](references/handoff-protocols.md). The standard handoffs between phases and skills, plus the adjacent observation handoff for filing things noticed while working nearby. +- [`references/platform-implementation.md`](references/platform-implementation.md). How the orchestration maps to Jira, Linear, Notion, Figma, and GitHub, including MCP integration notes per platform and CLI alternatives where MCP is the wrong tool. +- [`references/team-size-modulation.md`](references/team-size-modulation.md). How cadences scale across solo, small, medium, and large teams. +- [`references/automation-and-qa-tooling.md`](references/automation-and-qa-tooling.md). The QA verification gate pattern, MCP vs CLI tradeoffs, session memory and momentum patterns, code-to-ticket linkage, and evidence trails. +- [`references/example-orchestration.md`](references/example-orchestration.md). A complete worked example showing all sections populated for a representative scenario. diff --git a/skills/integration-orchestrator/references/automation-and-qa-tooling.md b/skills/integration-orchestrator/references/automation-and-qa-tooling.md new file mode 100644 index 0000000..d1649a5 --- /dev/null +++ b/skills/integration-orchestrator/references/automation-and-qa-tooling.md @@ -0,0 +1,167 @@ +# Automation and QA tooling + +The QA verification gate, MCP vs CLI tradeoffs at the strategic level, session memory and momentum patterns, code-to-ticket linkage, evidence trails, and failure routing. This file pairs with platform-implementation.md (which covers per-platform specifics) but stays at strategic-pattern level. + +--- + +## Section 1: The QA verification gate + +The single most important pattern in this reference file. Tasks only move from "QA" to "Done" after automated verification passes. This makes Done a measurable gate, not a self-reported one. + +The orchestration plan specifies, per project type: + +- Which automated tests must pass. Defined in writing as part of the orchestration plan output. Different project types have different test suites. + - Web project. Playwright critical-flow tests covering signup, checkout, contact form, navigation, and any other paths that move money or capture data. Visual regression on key pages (homepage, pricing, top-traffic landing pages). Console error count not exceeding baseline (specify baseline as 0 errors at hero load and during critical flows). Accessibility floor (WCAG AA contrast, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled). Performance budgets (Lighthouse mobile and desktop scores at or above project target, Core Web Vitals at or above project target). + - Microsite or landing page. Subset of the above scoped to the page; performance budgets often tighter. + - Campaign. Cross-deliverable consistency check (do all assets reference the same brand identity? do all touchpoints use the locked voice?) plus per-deliverable QA. + - Identity refresh. Visual regression on the design library plus an audit of downstream files using deprecated components. + +- Which MCPs run them. + - Playwright MCP for browser-driven user-flow tests. The agent invokes the test suite, captures pass/fail per test, and attaches results to the ticket. + - Claude in Chrome / Chrome MCP for human-readable QA flows with screenshot or GIF evidence trails. Useful when the test isn't a deterministic pass/fail (e.g., "does the checkout flow feel right?" requires a human-readable record). Chrome MCP captures the agent's walkthrough as a GIF or screenshot sequence. + - Windows MCP for desktop applications. Covers Windows-specific testing scenarios when the project is desktop-app-shaped. + - Mobile testing MCPs (Detox-based, Appium variants) for mobile apps when applicable. + +- What gets verified in a typical web QA pass. + - Critical user-flow tests (signup, checkout, contact form submission, search if applicable). + - Visual regression on key pages (typically 5-10 pages flagged as critical). + - Console error count not exceeding baseline. + - Accessibility floor (WCAG AA contrast, keyboard navigation, screen reader landmarks). + - Performance budgets (Lighthouse, Core Web Vitals). + +- Where the evidence attaches. + - Linked to the ticket as a comment with screenshot or GIF. + - Optionally stored in a `.evidence/` folder in the repo (engineering projects) or a designated cloud bucket (S3, GCS). + +- What happens on failure. + - Status moves to Blocked (not back to In Progress). + - The blocker reason is documented in the ticket comment. + - If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. + - The human is paged via the configured channel. + - The agent does NOT keep retrying autonomously; it documents the state and waits. + +--- + +## Section 2: MCP vs CLI tradeoffs at the strategic level + +The platform-implementation reference covers per-platform specifics. This section is the strategic frame for choosing between MCP and CLI as the orchestration's primary interface. + +### MCP excels at + +- Small reads and writes (single ticket update, single comment posting, single page edit). +- Real-time data (current status of a project, current PRs awaiting review). +- API-shaped operations that map cleanly to JSON-in / JSON-out. +- Agent-friendly contracts (structured tool calls with typed responses). +- Navigation queries ("show me all open tickets in this project", "find the PR that touches this file"). +- Status reads (what's the current gate state, what's locked). + +### CLI excels at + +- Bulk content updates (large Confluence pages, multi-page Notion exports, repo-wide search-and-replace). +- File-tree-aware operations (operating on multiple files in a repo, generating a directory of artifacts). +- Git-like workflows (the gh CLI's strengths around branches, PRs, releases). +- Lower token cost on heavy operations. MCP roundtrips become expensive at scale; CLI runs locally with no token cost per operation. +- Scripted automation (CI workflows, deploy pipelines, scheduled jobs). + +### Decision pattern + +- For setup and orchestration. Prefer MCP. PM-friendly, declarative, easy to inspect. The agent can explain what it did via tool-call traces. +- For bulk operations. Prefer CLI. More efficient, lower token cost, better formatting preservation. +- For QA verification. Playwright CLI when the same test runs repeatedly (CI integration, pre-commit hooks). Playwright MCP when verification is ad-hoc and needs to interact with surrounding context (the agent reading a Linear ticket, then running specific tests against the deployed staging site). + +### Hybrid pattern + +Most production setups use both. MCP for the orchestration plan's setup operations and ongoing navigation; CLI for ongoing bulk work, CI integration, and operations the MCP can't handle efficiently. The orchestration plan specifies which interface fires when. + +--- + +## Section 3: Session memory and momentum + +The agent-starts-from-zero problem. Each new Claude Code session re-reads files, re-discovers decisions, re-learns the same gotchas. MCP gives the task list; it doesn't give working momentum. + +Patterns to bridge the gap: + +### Project state file + +Committed alongside code. Typical paths: `CLAUDE.md`, `AGENTS.md`, `.agent/state.md`. Contents: + +- Last completed task with brief outcome notes ("RAMP-123: homepage hero rewrite. Shipped in PR #456. Worth noting: the existing copy was longer than the new copy, so the design has extra whitespace below the hero now. May need design follow-up."). +- Current task in progress with current status ("RAMP-124: pricing page CTA test. In Progress. Blocking on getting the test variant ID from Mira."). +- Open decisions awaiting human input ("Should we use the new monogram on the favicon, or keep the existing letterform-as-symbol? Pending design lead review."). +- Known gotchas the agent should avoid re-discovering ("The CMS export step takes 8 minutes. Don't kick it off until you're ready to wait. The export contains stale image references; replace with current image URLs from the asset library before publishing."). +- Convention reminders specific to the project ("Branch names use uppercase ticket prefix: feat/RAMP-123-slug. PR descriptions include 'Closes RAMP-123'. Squash merge only."). + +### Per-task observation trail + +After completing each task, the agent records observations: + +- What was unexpected ("The CMS API returned a 429 on the first attempt; had to wait 60 seconds before retry succeeded."). +- What broke before it worked ("Initial regex for the slug pattern matched too broadly; tightened to require dash separators."). +- What workaround was found ("The token export script doesn't handle nested groups in Figma; flattened the groups manually before export."). +- What pattern might generalize ("All API endpoints return null when the resource doesn't exist, not 404. Worth refactoring the error handling to assume null rather than 404."). + +### Trail-as-next-task generation + +When N observations accumulate (typically 5 to 10), hand them back as the brief for the next iteration: "here are 10 observations from this week, turn them into improvements." Keeps the agent's capability pointed at code quality and process refinement, not just task completion. + +The orchestrator skill's output bakes these mechanisms into the plan: specifies which state file to use, what content goes in it, when observations get reviewed by the human (typically weekly grooming), how the observation trail informs next-cycle planning. + +--- + +## Section 4: Code-to-ticket linkage + +Standard but worth specifying so the orchestration plan can call out exactly which conventions the team uses. + +- Branch naming. `{type}/{ticket-id}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform. +- PR descriptions. Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- Commit messages. Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. +- CODEOWNERS. When set up, PR review routing happens automatically and the orchestration plan's review-by assignments align with platform-native routing. + +The orchestration plan specifies the convention per platform combination (Jira+GitHub uses RAMP-123 prefix style; Linear+GitHub uses LIN-456 or the team's chosen prefix). Without that specification, branch names drift across team members and the auto-linking breaks. + +--- + +## Section 5: Evidence trails and recording + +Some pattern, some practical advice. + +### Recording tools + +- Claude in Chrome auto-records GIFs of QA flows. Useful for evidence attached to tickets. Limitations: GIF format is large and not video-quality; for longer flows, prefer MP4 or WebP if the recording tool supports it. +- Screenshot evidence is sufficient for most ticket-level QA artifacts. Tools like Playwright auto-capture on test failure; Chrome MCP can take ad-hoc screenshots during human-readable QA. +- Loom or similar for human-narrated walkthroughs when the audience needs context (client review of the staging site, stakeholder review of a complex flow). + +### Where evidence lives + +Three options, each with tradeoffs: + +- Attached directly to the ticket as a comment. Most discoverable but bloats the ticket. Best for evidence that pairs tightly with a specific ticket. +- In a designated cloud bucket (S3, GCS) with a link in the ticket. Ticket stays clean, evidence has a stable URL. Best for projects with high evidence volume. +- In a `.evidence/` folder in the repo. Works for engineering-heavy projects but cumbersome for design or copy work. Pairs well with the project state file pattern; evidence and state co-locate. + +### Retention + +Most projects don't need permanent evidence retention beyond the ticket. Specify a retention policy in the orchestration plan: + +- 30 days for QA evidence (passing tests don't need long retention). +- 90 days for bug-related evidence (bug reproduction often resurfaces within 90 days). +- Indefinite for design final approvals (the audit trail matters for years). + +--- + +## Section 6: Failure routing + +When automated verification fails OR an agent hits something it cannot autonomously resolve, the failure follows a defined routing. + +1. Status moves to Blocked. Not back to In Progress, not to Waiting. Blocked is a first-class status that means "human action required to unblock". +2. The blocker reason is documented in the ticket comment with specifics: which test failed, which file was the locus, which assertion didn't pass, what the agent already tried. +3. If the failure surfaced something unrelated to the current task, an adjacent observation gets filed in the project triage queue. +4. The human is paged via the configured channel. + - Slack (preferred for in-team work, fastest response). + - Email (for cross-team or external-stakeholder blockers). + - Linear or Jira mention (for in-tool routing when the team prefers a single channel). +5. The agent does NOT continue retrying. It documents the state and waits. Retrying is the path that turns a single failure into a context-burning loop. + +This routing is itself part of the orchestration plan output: the skill specifies which channels are configured, who's on the escalation tree, and what response time is expected per blocker severity (typically: P0 blockers paged immediately; P1 paged within a working hour; P2 surfaced at next standup; P3 added to the triage queue without a page). + +The discipline of Blocked-as-first-class-status is what makes agent participation safe at scale. Without it, agents either burn context retrying or silently abandon work; with it, the agent has a clear "I'm stuck" signal that keeps the work visible to the human team. diff --git a/skills/integration-orchestrator/references/cadence-patterns.md b/skills/integration-orchestrator/references/cadence-patterns.md new file mode 100644 index 0000000..e21adb9 --- /dev/null +++ b/skills/integration-orchestrator/references/cadence-patterns.md @@ -0,0 +1,245 @@ +# Cadence patterns + +The 7 project-type cadences in working detail. Each cadence covers phase decomposition, calendar timelines, gate definitions, lock-point map, and tool-stack implementation skeleton. + +## The 5-status taxonomy + +Every cadence in this file uses the same 5-status taxonomy: + +- Todo. Work scoped, not yet started. +- In Progress. Work being actively done. +- Waiting. Work paused for normal handoff or scheduled review. Examples: a ticket waiting for the next standup, a PR waiting for its assigned reviewer, a design awaiting client review at the next scheduled session. +- Blocked. Work cannot proceed without human resolution of a specific issue. Distinct from Waiting. An agent moves a task to Blocked when it cannot autonomously resolve and documents the blocker. The agent then stops; it does not retry. +- Done. Work complete AND verified. The QA verification gate must pass before transition to Done. Self-reported "I think this works" does not transition to Done; the automated test gate (or, in non-engineering contexts, the explicit reviewer signoff) does. + +Status transitions are restricted at the gate level. The QA gate prevents transition to Done. The approval gates prevent forward progress until the gate passes. Blocked tickets generate a paging signal to the configured channel. + +--- + +## 1. New brand build (6 to 8 weeks) + +The full lifecycle. Greenfield brand or a brand whose existing assets are being replaced wholesale. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Discovery \| 1 week \| Audience, positioning, competitive landscape, references \| +\| Direction \| 1 week \| Creative direction brief (axes locked) \| +\| Identity \| 1 to 2 weeks \| Logo system, color, typography, imagery direction, motion \| +\| Production \| 2 to 3 weeks \| Voice guide, copy, design system, page builds \| +\| Launch \| 1 week \| QA, soft launch, full launch \| + +### Gates + +- End of Discovery. Brief approval. Required: client signed brief artifact (in writing or recorded review). +- End of Direction. Direction approval. Required: axis positions locked, references curated. +- End of Identity. Identity approval. Required: logo system, color tokens, typography, imagery direction documented. +- Mid-Production. Voice approval. Required: voice guide signed. +- End of Production. Copy approval and design approval. Required: per-page copy and design signed. +- Pre-Launch. QA verification. Required: Playwright critical-flow suite green, console error count at or below baseline, accessibility floor maintained. +- Launch readiness. Final go/no-go. Required: deployment checklist complete, rollback plan documented. + +### Lock points + +Brief locks at end of Direction. Identity tokens lock at end of Identity. Voice locks mid-Production. Copy locks per page at end of Production. Design tokens lock with identity; design final lock at end of Production. + +### Tool-stack implementation + +- Jira: 1 Epic per phase, Stories per work item, custom fields for Phase / Locked / Approver / Gate Status. Workflow scheme with the 5-status taxonomy. +- Linear: 1 Project per phase, Cycles per week, Labels per skill (`brand-identity`, `brand-voice`, `landing-page-copy`, etc.). +- Notion: Brief database with one row, related databases for direction docs, identity specs, voice guides, copy decks. Phase dashboard views. +- Figma: Library structure: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status. +- GitHub: Branch protection on `main`. PRs from `phase/{phase-name}/` branches. + +### Example ticket titles + +- Discovery: "Audience: 5 archetypes interviewed", "Positioning: locate the brand against 3 competitors" +- Direction: "Direction: confirm tone-axis position", "Direction: rejection list signed off" +- Identity: "Identity: logo lockup variants for review", "Identity: color tokens locked" +- Production: "Voice guide: tone-shift table approved", "Copy: homepage hero v3 reviewed" +- Launch: "QA: Playwright critical flow regression green", "Launch: deploy to production" + +--- + +## 2. Rebrand (4 to 6 weeks) + +Existing brand. Audience and positioning known. Audit replaces discovery. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| What to keep, drop, refresh; positioning gaps \| +\| Direction \| 1 week \| Creative direction brief \| +\| Identity \| 1 to 2 weeks \| Refreshed logo, color, type, imagery \| +\| Production \| 1 to 2 weeks \| Updated voice guide, copy, design library, page builds \| + +### Gates + +Audit approval, direction approval, identity approval, voice approval, copy approval, design approval, QA verification, launch readiness. Same gates as new brand build minus the Launch phase (rebrand often launches with the production push rather than a separate phase). + +### Lock points + +Audit findings lock at end of Audit (decisions about what to keep stay in scope; revisiting requires change request). All other lock points match new brand build. + +### Tool-stack implementation + +Same as new brand build. The Audit phase typically uses a Notion database with rows for "Existing asset / Decision (keep/drop/refresh)/Owner / Status". + +--- + +## 3. Single landing page (1 to 2 weeks) + +The brand identity and voice are locked. The work is page-specific copy, design, and engineering. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 2 to 3 days \| Page brief, success criteria \| +\| Production \| 5 to 7 days \| Copy, design, build \| +\| QA-Launch \| 1 to 2 days \| QA, deploy \| + +### Gates + +- End of Brief.* Page brief approval. Required: success metric defined. +- Mid-Production. Copy approval. Required: signed against existing voice guide. +- End of Production. Design approval and engineering review. Required: design final, build complete. +- End of QA-Launch. QA verification and launch readiness combined. Required: Playwright run green, console errors at baseline, deploy executed. + +### Lock points + +Page brief locks at end of Brief. Copy locks mid-Production. Design tokens are inherited from the brand identity (already locked). Design final locks at end of Production. + +### Tool-stack implementation + +- Jira / Linear: Single Epic for the page, 5 to 8 Stories. +- Notion: Single brief row, one direction artifact (the page brief). +- Figma: Working file referencing the brand library; one set of frames. +- GitHub: Single feature branch, PR template, branch protection on `main`. + +--- + +## 4. Campaign (2 to 4 weeks) + +Brand identity and voice locked. Multiple deliverables under one campaign theme. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 3 to 5 days \| Campaign brief, deliverable list \| +\| Production \| 1 to 2 weeks \| Per-deliverable copy, design, build \| +\| QA \| 3 to 5 days \| Cross-deliverable QA \| +\| Launch \| 1 to 2 days \| Coordinated launch \| + +### Gates + +Campaign brief approval, per-deliverable copy approval, per-deliverable design approval, cross-deliverable QA verification, launch readiness. + +### Lock points + +Campaign brief locks at end of Brief. Per-deliverable copy locks at copy approval. Per-deliverable design locks at design approval. Cross-deliverable consistency checked at QA gate (a single change request on the campaign brief triggers re-review across all deliverables). + +### Tool-stack implementation + +- Jira / Linear: 1 Epic for campaign, 1 Story per deliverable plus per-deliverable subtasks. +- Notion: Campaign brief row plus deliverable rows in a related database. +- Figma: Library file plus one frame per deliverable. +- GitHub: Multiple feature branches off a campaign branch, single PR per deliverable. + +--- + +## 5. Identity refresh (3 to 4 weeks) + +Existing brand. Voice and positioning stay. Identity gets refreshed. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| What stays, what changes \| +\| Identity \| 1 to 2 weeks \| Refreshed logo, color, type, imagery \| +\| Production \| 1 week \| Application examples (web, signage, social) \| + +### Gates + +Audit approval, identity approval, production review. Voice and copy gates skipped (voice stays locked; copy gets light updates if any). + +### Lock points + +Audit findings lock at end of Audit. Identity tokens lock at end of Identity. Application examples lock at end of Production but tokens remain canonical. + +### Tool-stack implementation + +- Figma: Refresh of existing library; new component versions; old components deprecated rather than deleted (downstream files still reference them). +- Notion: Identity spec row with relations to before/after asset databases. +- Jira / Linear: Smaller scope than rebrand; 1 Epic, 8 to 15 Stories. +- GitHub: Library updates land via versioned PR; downstream consumers update on their own cadence. + +--- + +## 6. Website refresh (4 to 8 weeks) + +Existing site. Either a partial refresh (specific sections) or a full overhaul. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Audit \| 1 week \| Current site assessment, gaps, priorities \| +\| Direction \| 1 week \| Refreshed brief if positioning has shifted \| +\| Production \| 2 to 4 weeks \| Voice updates, copy, design, build \| +\| QA-Launch \| 1 to 2 weeks \| Cross-page QA, soft launch, full launch \| + +### Gates + +Audit approval, direction approval (if direction phase happens; some refreshes skip), per-section copy approval, per-section design approval, QA verification, launch readiness. + +### Lock points + +Audit findings lock at end of Audit. Direction (if produced) locks at end of Direction. Per-section copy locks at copy approval per section. Design tokens lock with the design library; design final per section locks at design approval. + +### Tool-stack implementation + +- Jira / Linear: 1 Epic per phase, sub-Epics per section if the site is large. +- Notion: Brief plus per-section page in a database. +- Figma: Library refresh plus per-section design files. +- GitHub: Per-section feature branches, branch protection, CI gates per section. + +--- + +## 7. Microsite or product launch (3 to 5 weeks) + +Fixed launch date. Plan backward from the launch. + +### Phase decomposition + +\| Phase \| Duration \| Output \| +\|---\|---\|---\| +\| Brief \| 3 to 5 days \| Launch brief, microsite scope \| +\| Production \| 2 to 3 weeks \| Copy, design, build, integrations \| +\| QA \| 3 to 5 days \| Cross-flow QA \| +\| Launch \| 2 to 3 days \| Coordinated launch sequence \| + +### Gates + +Launch brief approval, copy approval, design approval, QA verification, launch readiness. + +### Lock points + +Launch brief locks at end of Brief. Copy locks at copy approval. Design locks at design approval. The launch date is the hardest lock; if QA fails, the launch slips rather than launching with bugs. + +### Tool-stack implementation + +- Jira / Linear: 1 Epic, multiple Stories per surface (microsite, supporting pages, integrations). +- Notion: Launch brief plus dependency table (assets, integrations, third parties). +- Figma: Microsite design file referencing brand library. +- GitHub: Microsite feature branch plus per-surface sub-branches; branch protection plus pre-launch CI gate. + +--- + +## How to use this file + +Pick the cadence whose project type matches yours. Follow the phase decomposition for your team size (use the team-size-modulation reference for adjustments). Implement in your tool stack using the platform-implementation reference for per-platform setup. Configure the QA verification gate using the automation-and-qa-tooling reference. The pieces compose; this file is the cadence skeleton. diff --git a/skills/integration-orchestrator/references/example-orchestration.md b/skills/integration-orchestrator/references/example-orchestration.md new file mode 100644 index 0000000..c481fb5 --- /dev/null +++ b/skills/integration-orchestrator/references/example-orchestration.md @@ -0,0 +1,267 @@ +# Example orchestration + +A complete worked example showing all sections of the orchestration plan populated for a representative scenario. The PM should be able to read this Monday morning and start setting up tools Tuesday. + +## Scenario + +A 4-person team is doing a rebrand for a 15-year-old hospitality brand. The existing brand has a loyal customer base and recognizable identity assets, but the visual register has aged poorly and the digital surfaces haven't been updated since 2019. + +- Team. PM (Mira), design lead (Karim), copy lead (Jess), senior engineer (Dax). +- Timeline. 6 weeks. +- Tool stack. Jira (existing, the team's main work tracker) + Figma + GitHub. Notion is not used by this team. Slack for communication. Loom for client review walkthroughs. +- AI agent participation. Claude Code participates in production phase tasks (component library updates, page builds). Claude in Chrome runs QA gates on the staging deployment. Agents have access to the Atlassian MCP and GitHub MCP. Agents move tickets between Todo, In Progress, Waiting, and Blocked but do NOT move to Done; Done requires human verification. +- Client. Hospitality brand owner is non-technical. Reviews happen via Loom-recorded walkthroughs scheduled at end of each phase. + +--- + +## 1. Project orchestration plan + +### Phased timeline + +- Week 1 (Audit). Existing brand assessment. Audience already known; the audit assesses what to keep, drop, refresh. Output: audit findings document. +- Week 2 (Direction). Refreshed creative direction brief. Tone, aesthetic, relationship, sensory positions confirmed. Output: direction artifact. +- Weeks 3-4 (Identity). Refreshed logo lockup, color tokens, typography selections, imagery direction. Output: locked identity tokens published to Figma library, identity spec document. +- Weeks 5-6 (Production). Voice guide refresh, copy update for top 8 pages, design final per page, engineering implementation, QA verification, launch. + +### Calendar boundaries + +Week 1: Mon-Fri Audit, Friday phase review with brand owner via Loom walkthrough. +Week 2: Mon-Fri Direction, Friday phase review. +Weeks 3-4: Mon-Fri Identity, mid-Week 4 voice approval gate, Friday Week 4 identity approval gate plus Loom walkthrough. +Weeks 5-6: Mon-Tue Week 5 copy approval per page, Wed-Fri Week 5 design final per page (rolling), Mon-Wed Week 6 engineering implementation (rolling), Thu Week 6 QA verification, Fri Week 6 launch. + +--- + +## 2. Per-phase gate specs + +### Audit approval gate (end of Week 1) + +- Trigger. All Audit tasks transitioned to Done. Audit findings document complete. +- Approver. Brand owner (via Loom walkthrough plus email signoff). Mira reviews internally first. +- Required to pass. Audit findings document complete (existing assets categorized as keep / drop / refresh, gaps identified). Brand owner signed off in writing. +- Blocks until passed. Direction phase work. + +### Direction approval gate (end of Week 2) + +- Trigger. Tone, aesthetic, relationship, sensory positions selected. References curated. Rejection list documented. +- Approver. Brand owner plus Karim (design lead). +- Required to pass. All four axis positions confirmed in writing. Reference brand list documented. Rejection list signed off. +- Blocks until passed. Identity phase production work. + +### Voice approval gate (mid Week 4) + +- Trigger. Refreshed voice guide drafted by Jess against locked direction. +- Approver. Brand owner plus Jess (copy lead). +- Required to pass. Voice guide complete (attributes, tone shifts, vocabulary, paired examples). At least 3 paired examples per major content type. +- Blocks until passed. Copy production for shipping pages. + +### Identity approval gate (end of Week 4) + +- Trigger. Refreshed logo, color tokens, typography, imagery direction documented and rendered. +- Approver. Brand owner plus Karim. +- Required to pass. Logo lockup variants reviewed. Selected variants documented. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented. +- Blocks until passed. Design production at scale. + +### Copy approval gate (per page, Week 5) + +- Trigger. Per-page copy drafted against locked voice guide. +- Approver. Brand owner (via Loom walkthrough for top 3 pages; email approval for the other 5) plus Jess. +- Required to pass. Copy matches voice guide. Calls-to-action consistent with success criteria. +- Blocks until passed. Design final for that page. + +### Design approval gate (per page, Week 5-6) + +- Trigger. Design final rendered against locked copy and locked identity tokens. +- Approver. Karim plus Mira. +- Required to pass. Design references locked identity tokens. Copy reflected exactly as approved. Responsive states designed. Empty/loading/error states accounted for. +- Blocks until passed. Engineering of that page. + +### QA verification gate (Thu Week 6) + +- Trigger. Engineering signaled complete; ticket transitioned to QA status. +- Approver. Automated test suite (Playwright via MCP) plus Claude in Chrome walkthrough; human review on test failure. +- Required to pass. Playwright critical-flow suite green. Console error count at 0 for hero load and during critical flows. Accessibility floor maintained (WCAG AA contrast, keyboard navigation, screen reader landmarks). Lighthouse mobile score at or above 85, desktop at or above 95. Visual regression on top 8 pages within tolerance. +- Blocks until passed. Status transition to Done. Launch readiness for the affected page. + +### Launch readiness gate (Fri Week 6) + +- Trigger. All 8 affected pages have passed QA verification. +- Approver. Mira (project owner) plus Dax (launch coordinator). +- Required to pass. Deployment checklist complete. Rollback plan documented. On-call coverage assigned for the launch window. Brand owner notified. + +--- + +## 3. Lock-point map + +- Audit findings lock at end of Week 1. Existing-asset decisions cannot be revisited without change request triggering re-review of Direction work. +- Direction locks at end of Week 2. Axis positions cannot be revisited without change request triggering re-review of Identity, Voice, and Copy work. +- Identity tokens lock at end of Week 4. Color tokens, typography selections, logo lockup committed to Figma library v2.0. Downstream design and engineering work references the locked library version. +- Voice rules lock mid Week 4. Voice guide v2.0 committed to canonical Confluence page. Downstream copy production references the locked voice guide. +- Per-page copy locks at copy approval gate (Week 5). Each page's copy locks individually as it passes its approval gate; design final for that page can begin. +- Per-page design locks at design approval gate (Week 5-6). Each page's design locks individually; engineering for that page can begin. +- Code merges to main (Week 5-6, rolling). Branch protection prevents direct pushes; PRs merge after CODEOWNERS review and CI gates pass. + +--- + +## 4. Handoff specs + +- Audit to Direction (Friday Week 1). Audit findings document URL, summary of gaps and opportunities. Filed in Jira as a Confluence page link in the Direction phase Epic description. +- Direction to Identity (Friday Week 2). Direction artifact URL, axis positions documented, reference brand list, rejection list. Filed in Jira as Confluence page links in the Identity phase Epic description. +- Direction to Voice (Friday Week 2, parallel to Direction-to-Identity). Same artifacts; Voice phase work begins in parallel with Identity. +- Identity plus Voice to Copy (Mid-Week 5). Locked identity tokens (Figma library v2.0 URL), locked voice guide (Confluence URL), per-page scope (Jira tickets). Filed in Jira as Story descriptions per page. +- Identity plus Copy to Design (Per page, Week 5). Locked copy (Confluence URL with "approved" marker), locked identity tokens (Figma library v2.0 URL). Filed in Jira as the design-phase Story description per page. +- Design to Engineering (Per page, Week 5-6). Final design (Figma frame URL), exported asset library (cloud bucket URL), responsive notes (Figma annotations), motion specifications. Filed in Jira as the engineering-phase Story description per page. +- Engineering to QA (Per page, Week 6). Verified deployed-to-staging surface, QA evidence (Playwright run results URL, accessibility audit URL), deployment checklist URL. + +### Adjacent observation routing + +The team's triage queue is a Jira project labeled "Project triage". Filed observations route there without an assignee. Mira triages every Monday and Thursday at standup. Observation content includes: what was observed, why it might matter, link to the work that was happening when noticed, suggested triage priority. The agent uses the Atlassian MCP to file observations. + +--- + +## 5. Tool-stack implementation + +### Jira + +Issue type scheme: +- Epic: one per phase (Audit, Direction, Identity, Production-Voice, Production-Copy, Production-Design, Production-Engineering, Production-QA, Launch). +- Story: one per work item within a phase. +- Task: subtasks under stories. +- Bug: for issues filed during QA. + +Custom fields: +- Phase (single-select with the 8 phase names). +- Locked (checkbox). +- Approver (user picker). +- Gate Status (single-select with the 8 standard gates). + +Workflow scheme: 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) with workflow validators preventing premature transitions to Done without QA verification. + +Confluence space: +- Brief page (rebrand brief). +- Direction page (creative direction artifact). +- Audit findings page. +- Identity spec page (logo, color, typography, imagery). +- Voice guide page. +- Copy doc per page (top 8 pages). +- Orchestration plan page (this document, committed to the project space). + +MCP setup: +- Atlassian MCP configured with OAuth credentials (admin one-time setup). +- Initial Epic creation: 8 epics, one per phase, populated by the agent on Day 1. +- Initial Story creation per phase: agent populates from the orchestration plan. + +### Figma + +Library file structure: +- "Tokens" page: color, typography, spacing, motion. +- "Components" page: identity components (logo, badges, branded UI elements). +- "Patterns" page: page-level patterns (hero variants, card patterns, footer). +- "Page templates" page: top 8 page templates for the rebrand. +- "Working files" page: per-page design working files. + +Library publish discipline: +- v1.0 published at start of Week 3 (existing identity, used as baseline). +- v2.0 published at end of Week 4 (refreshed identity, locks at identity gate). +- Per-page working files reference v2.0 starting Week 5. + +### GitHub + +Repository: existing repo for the brand's website. + +Branch protection on main: +- Require PR reviews (1 reviewer minimum). +- Require status checks (lint, type-check, build, accessibility audit, Playwright run). +- Require linear history (squash merges only). + +CODEOWNERS: +- Frontend code: Dax. +- Design tokens: Karim. +- Copy markdown: Jess. + +PR template: +- Ticket reference (Closes RAMP-XXX or Refs RAMP-XXX). +- Summary. +- Test plan. +- Screenshots/GIFs for UI changes. +- QA evidence URL. + +GitHub MCP setup: +- GitHub MCP configured with the repo's PAT. +- Initial PR template committed via MCP. +- CODEOWNERS file committed via MCP. + +--- + +## 6. Automation and QA verification + +### Playwright test suite spec + +Critical flows to test: +- Homepage hero loads and renders. +- Reservation flow (the brand's primary conversion path) end-to-end through booking confirmation. +- Contact form submission (validation, submission, success state). +- Newsletter signup. +- Top-traffic landing pages render without console errors. + +Visual regression on top 8 pages: +- Homepage, About, Reservations, Locations, Menu, Press, Contact, Loyalty. + +Accessibility audit per page using axe-core or equivalent: +- WCAG AA contrast. +- Keyboard navigation reaching all interactive elements. +- Screen reader landmarks present and labeled. + +### Chrome MCP walkthrough scenarios + +For Loom-recorded brand owner reviews and ad-hoc human-readable QA: +- Reservation flow walkthrough with screenshots at each step. +- Brand consistency walkthrough (top 8 pages, evaluating typography and color consistency). +- Mobile responsive walkthrough (the brand's audience is heavily mobile). + +### Evidence trail policy + +- QA evidence (test results, screenshots, GIFs) attached to each ticket as comments. +- 90-day retention for engineering-related evidence. +- Indefinite retention for design final approvals (committed to Confluence with the design spec page). + +### Failure routing + +- Slack channel #project-rebrand-launch is the team's coordination channel. Blockers page Mira via Slack mention. +- P0 blockers (broken reservation flow): page Dax immediately via direct Slack mention. +- P1 blockers (broken page render): surface at next standup. +- P2-P3 blockers: file as adjacent observation in the triage queue. + +--- + +## 7. Risk register + +Cadence-specific risks and mitigations. + +### Risk 1: Brand owner availability for Loom reviews + +The brand owner is busy and may delay phase reviews, slipping the timeline. Mitigation: Mira schedules Loom reviews 1 week in advance with calendar holds. Backup reviewer for direction approval gate is the head of marketing on the brand owner's team (Mira identified this person at project kickoff). + +### Risk 2: Identity refresh expectations vs reality + +The brand owner may expect a more dramatic refresh than the audit recommends, OR may reject the refresh as too dramatic. Mitigation: Karim shares 3 directional moodboards at end of Week 1 to align expectations BEFORE Direction phase locks in. The moodboards are not the final identity; they're directional samples to confirm the team and the brand owner are pointing in the same direction. + +### Risk 3: Engineering surface area + +The website has 8 pages but also a custom CMS, a reservation integration, and an email pipeline. The 6-week timeline assumes only the page surface gets touched. Mitigation: Mira confirmed at project kickoff that CMS, reservations, and email pipeline are out of scope. Documented in the brief. If the brand owner requests adding any of these mid-flight, formal change request triggers timeline review. + +### Risk 4: Agent coordination overhead + +Claude Code participates in production tasks; Claude in Chrome runs QA gates. The agents access the Atlassian and GitHub MCPs. Risk: agent action and human action collide on the same ticket; human commits something the agent had also drafted. Mitigation: agents are not assigned tickets; they take tickets from the "Available for agent" queue (a Jira label). Humans take tickets from the "Available for human" queue. Mira moves tickets between queues at standup. + +### Risk 5: QA verification baseline drift + +Console error baseline is set at start of project. If a third-party script (analytics, heatmap, customer support chat) lands during the project and adds console errors, the baseline shifts. Mitigation: console error baseline is reset weekly during standup. Any new errors that appear get triaged immediately as either an accepted change to baseline (third-party expected) or a regression that needs fixing. + +--- + +## How to use this example + +This example is the format the orchestration plan output takes. Real outputs differ in specifics (different team, different timeline, different stack, different risks) but the structure is the same. The PM reads through, sets up the tools to match, and starts running the plan Tuesday. + +The discipline that makes this work: every section is specific. Generic plans fail. "QA gate must pass" is not a plan; "Playwright critical flows pass, console errors at baseline 0, accessibility floor WCAG AA, Lighthouse mobile at or above 85, visual regression on top 8 pages within tolerance" is a plan. diff --git a/skills/integration-orchestrator/references/gate-definitions.md b/skills/integration-orchestrator/references/gate-definitions.md new file mode 100644 index 0000000..74ea2ff --- /dev/null +++ b/skills/integration-orchestrator/references/gate-definitions.md @@ -0,0 +1,119 @@ +# Gate definitions + +The 8 standard gates. Each gate includes its trigger, approver, pass criteria, what's blocked until passing, what's already locked from prior gates, and the change-request protocol if the gate is failed or reopened later. + +A gate is the moment a phase transition gets approved. Gates work when their pass criteria are measurable. "Approved" is too vague; "client signed the artifact in writing or in a recorded review" is measurable. The orchestration plan specifies measurable criteria per gate. + +--- + +## 1. Brief approval gate + +Closes the Discovery phase (or Audit phase, on rebrand projects) and opens Direction. + +- Trigger. All Discovery tasks transition to Done. The brief artifact is drafted. +- Approver. Project owner (typically the client or the founder). For internal work, the senior stakeholder. +- Required to pass. The brief artifact is complete (audience, positioning, deliverables, constraints, success criteria all populated). Approver signed in writing OR a recorded review session captured agreement. The brief artifact is committed to its canonical location (Notion brief database row, Confluence page, or repo file). +- Blocks until passed. Direction phase work, identity phase work, voice phase work, copy work. +- Already locked. Nothing yet; this is the first gate. +- Change-request protocol. If the brief is reopened after this gate, the project re-enters Discovery briefly to assess what changed, then re-runs Direction starting from the updated brief. Identity, voice, copy, and design work that depends on the changed brief sections gets re-reviewed. + +--- + +## 2. Direction approval gate + +Closes Direction phase and opens Identity. + +- Trigger. Axis positions selected (tone, aesthetic, relationship, sensory). References curated. Rejection list documented. +- Approver. Project owner plus the design lead. +- Required to pass. All four axis positions confirmed in writing. Reference brands documented with one-line rationale each. Rejection list signed off (what the brief explicitly says no to). +- Blocks until passed. Identity phase production work. Voice production work. Any copy production. +- Already locked. The brief. +- Change-request protocol. If a direction axis is changed after this gate, identity work and voice work that depend on the changed axis get re-reviewed. Tone changes ripple to voice; aesthetic changes ripple to identity; relationship changes ripple to copy register; sensory changes ripple to motion and rhythm decisions. + +--- + +## 3. Identity approval gate + +Closes Identity phase. Opens production at full volume. + +- Trigger. Logo system, color tokens, typography selections, imagery direction documented and rendered. +- Approver. Project owner plus design lead. +- Required to pass. Logo lockup variants reviewed (typically 6 to 12). Selected variants documented with rationale. Color tokens specified as hex codes. Typography selections specified as named typefaces with weights. Imagery direction documented (style, palette, treatment). +- Blocks until passed. Design production at scale (component library, page designs). Engineering work that depends on design tokens. +- Already locked. Brief, direction. +- Change-request protocol. If identity tokens change after this gate, design files that reference the tokens get re-rendered. Engineering work that consumed the old tokens gets reviewed. Voice work is typically unaffected unless typography selection changes the implied tone register. + +--- + +## 4. Voice approval gate + +Closes voice production. Opens copy production at scale. + +- Trigger. Voice guide drafted. Tone-shift table populated. Vocabulary list compiled. Paired examples written. +- Approver. Project owner plus copy lead. +- Required to pass. Voice guide complete (attributes, tone shifts, vocabulary, grammar, paired examples). At least 3 paired examples per major content type (hero copy, body, microcopy). Voice signed off in writing. +- Blocks until passed. Copy production for shipping pages. +- Already locked. Brief, direction, identity (or identity in progress; voice can lock alongside identity if both phases overlap). +- Change-request protocol. If voice rules change after this gate, all copy that has been drafted against the old rules gets re-reviewed. The copy rework varies by scope: a vocabulary substitution is light; a tone-shift table change can mean rewriting from scratch. + +--- + +## 5. Copy approval gate + +Per-page or per-deliverable. Closes copy production for that page or deliverable. + +- Trigger. Copy drafted against the locked voice guide. Internal review complete. +- Approver. Project owner plus copy lead. For per-page copy, the page owner if different. +- Required to pass. Copy matches the voice guide (verifiable by running the voice-guide checklist). All sections complete. Microcopy populated. Calls-to-action consistent with the brief's success criteria. +- Blocks until passed. Design final for that page or deliverable. Engineering of the copy-dependent surface. +- Already locked. Brief, direction, identity, voice. +- Change-request protocol. Per-page copy changes after this gate trigger re-review of the design final for that page (because design length, hierarchy, and rhythm depend on copy length). Engineering work for that page may need to be revisited if the copy change affects layout. + +--- + +## 6. Design approval gate + +Per-page or per-deliverable. Closes design production for that page or deliverable. + +- Trigger. Design final rendered against locked copy and locked identity tokens. +- Approver. Design lead plus project owner. +- Required to pass. Design references the locked identity tokens (no off-token color, type, or spacing values). Copy is reflected exactly as approved (no copy edits hidden in the design). Responsive states designed. Empty states, loading states, error states accounted for. +- Blocks until passed. Engineering of the design-dependent surface. +- Already locked. Brief, direction, identity, voice, copy. +- Change-request protocol. Design changes after this gate trigger engineering re-review for the affected surface. The change-request protocol routes through the design lead to assess scope (token-level changes are light; component or layout changes are heavy). + +--- + +## 7. QA verification gate + +Per-surface. Closes engineering and verification, opens launch readiness for that surface. + +- Trigger. Ticket transitions to "QA" status (developer signaled engineering complete). +- Approver. Automated test suite, with human review on test failure or ambiguous result. +- Required to pass. Defined Playwright critical-flow test suite green. Console error count at or below baseline (specify the baseline per project; for a typical web app, 0 errors at hero load, 0 errors during critical flows). Accessibility floor maintained: WCAG AA contrast ratios on all text, keyboard navigation reaching all interactive elements, screen reader landmarks present and labeled. Performance budgets met (Lighthouse mobile score at or above project target, Core Web Vitals at or above project target). Visual regression on key pages within tolerance. +- Blocks until passed. Status transition to Done. Launch readiness for the affected surface. +- Already locked. Code merged to main, design tokens, copy, identity, voice, direction, brief. +- Change-request protocol. Failure routes the ticket to Blocked status (not back to In Progress). The blocker reason is documented in the ticket comment. If the failure surfaced something unrelated to the ticket's scope (e.g., a regression in a sibling page), an adjacent observation is filed in the project triage queue. The human is paged via the configured channel. The agent does NOT continue retrying autonomously. + +--- + +## 8. Launch readiness gate + +Closes the project (or the launch phase of a multi-phase project). + +- Trigger. All affected surfaces have passed the QA verification gate. +- Approver. Project owner plus the launch coordinator (typically the PM or the senior engineer on rotation). +- Required to pass. Deployment checklist complete (environment variables set, secrets rotated, third-party integrations live, monitoring active, alerting configured). Rollback plan documented (which command, who runs it, where logs go). Launch communications drafted (internal: who knows the launch is happening; external: any customer-facing announcement). On-call coverage assigned for the launch window. +- Blocks until passed. The actual production deploy. +- Already locked. Everything: brief, direction, identity, voice, copy, design, code, QA evidence. +- Change-request protocol. Launch readiness failure typically delays the launch rather than reopening upstream gates. If the failure is severe (a critical bug found in pre-launch QA), the affected surface returns to In Progress for fix, then re-runs through Engineering and QA verification before launch can proceed. + +--- + +## How gates compose + +Gates are not isolated. Each gate locks artifacts that downstream gates assume are stable. A QA verification failure that traces to a copy bug means the copy approval gate produced bad output, which traces back to either a voice rule that wasn't applied or a brief that wasn't reflected. The gate chain is the audit trail. + +When a gate is reopened, the change-request protocol cascades downstream. The orchestration plan specifies the protocol per gate so the team knows in advance what re-review work a change triggers. The cost of a change is visible at the moment it's requested, not discovered after the fact. + +The QA verification gate is the gate that does the most work for the team. It is the gate that prevents "Done" from being self-reported. Configure it carefully; trust it once configured. diff --git a/skills/integration-orchestrator/references/handoff-protocols.md b/skills/integration-orchestrator/references/handoff-protocols.md new file mode 100644 index 0000000..0fd39c5 --- /dev/null +++ b/skills/integration-orchestrator/references/handoff-protocols.md @@ -0,0 +1,143 @@ +# Handoff protocols + +A handoff is the moment work transfers between phases or skills. Without explicit handoff specs, the receiving phase opens a half-dozen Slack threads to find what they need. With them, the work moves cleanly because the receiving phase knows exactly what artifacts to expect, what's locked, and what's still open. + +This file covers the 7 standard handoffs plus an 8th cross-cutting handoff: the adjacent-observation routing. + +--- + +## 1. Discovery to Brief + +The first handoff. Discovery findings transfer to brief drafting. + +- What's transferred. Audience research notes (interview summaries, persona documents, audience-side observations). Positioning notes (competitive landscape, differentiation hypotheses). Reference materials gathered during discovery (brands, articles, examples that surfaced). +- What's locked. Nothing yet. Everything is still open. +- What stays open. All of it. Discovery is input, not decision. +- Common breakdown. Discovery findings get summarized too aggressively; the brief drafter loses the nuance. Mitigation: hand off the full notes plus a synthesis, not just the synthesis. +- Artifact specification. Discovery findings live in a Notion database, a Google Doc, or a folder of markdown files. The handoff includes a link plus a one-paragraph synthesis. +- Platform support. Notion: relation property from brief row to discovery findings. Jira: linked issue. Linear: project relationship. + +--- + +## 2. Brief to Identity + +After brief approval. The identity work begins against the locked brief. + +- What's transferred. Approved brief (audience, positioning, deliverables, constraints). Direction artifact (axis positions). Reference brand list. Rejection list. +- What's locked. Brief is locked. Direction is locked. Audience and positioning cannot be revisited without change request. +- What stays open. Everything inside the identity scope: logo system, color, typography, imagery direction, motion. The identity team picks within the constraints the brief and direction set. +- Common breakdown. The identity team interprets the rejection list loosely. A "no laurel mark" rejection becomes "well, our laurel is different". Mitigation: rejection-list adherence is a gate criterion at identity approval. +- Artifact specification. Brief lives in its canonical location (Notion brief row, Confluence page, or repo file). Direction artifact is a sibling document. Both URLs go in the identity-phase Epic or Project description. +- Platform support. Jira: Epic description with links. Linear: Project description with attached docs. Notion: relation properties. + +--- + +## 3. Brief to Voice + +In parallel with Brief-to-Identity. Voice work begins against the locked brief and direction. + +- What's transferred. Approved brief. Direction artifact (specifically the tone-axis position). Reference voice samples (other brands the team likes for their voice). +- What's locked. Brief, direction. +- What stays open. Voice attributes, tone-shift rules, vocabulary choices, grammar rules, paired examples. +- Common breakdown. Voice gets started without referencing the locked tone-axis position; the writer drafts in their natural voice rather than the project's. Mitigation: voice production opens with a tone-axis check ("the brief says Provocative; here is what Provocative implies for vocabulary, sentence shape, and rejection list"). +- Artifact specification. Tone-axis position from direction artifact. Reference voice samples as a Notion subpage or a markdown file with quoted samples. +- Platform support. Same as Brief-to-Identity. + +--- + +## 4. Identity plus Voice to Copy + +After identity approval and voice approval. Copy production begins. + +- What's transferred. Identity tokens (typography selections, color tokens, spacing). Voice guide (attributes, tone shifts, vocabulary, paired examples). Page or deliverable scope (which pages, which sections, what each section needs). +- What's locked. Brief, direction, identity tokens, voice rules. +- What stays open. Per-page copy choices within the locked voice. Calls-to-action language. Section ordering decisions where the design has not yet been finalized. +- Common breakdown. Copy is drafted for length without the typography in mind, and lands in design as either too long or too short for the rendered hero. Mitigation: copy production references the typography selection from the start; the writer drafts knowing which weight and size the copy will live in. +- Artifact specification. Identity tokens published in Figma library or in a tokens markdown file. Voice guide as a Notion page or markdown file. Page scope as a Jira/Linear ticket per page. +- Platform support. Figma library is the canonical token source. Jira/Linear ticket per page or section. + +--- + +## 5. Identity plus Copy to Design + +After copy approval per page. Design final begins for that page. + +- What's transferred. Locked copy (final approved text). Identity tokens (typography, color, spacing). Voice guide (for microcopy and any error or empty states the design generates). +- What's locked. Brief, direction, identity, voice, copy for the affected page. +- What stays open. Design layout decisions, responsive breakpoint behavior, motion design, empty/loading/error states. +- Common breakdown. Design starts before copy locks. Length, rhythm, and hierarchy get designed against placeholder text; when copy lands, the design has to be reworked. Mitigation: copy locks per page before design final starts. If parallel work is needed, design produces a wireframe with placeholder copy AND a flag noting "real copy pending; layout subject to revision". +- Artifact specification. Locked copy in the canonical copy doc with an explicit "approved" marker. Identity tokens in Figma library. Page scope from copy-phase ticket. +- Platform support. Figma frame per page, linked to ticket in Jira/Linear. + +--- + +## 6. Design to Engineering + +After design approval per page. Engineering builds the page. + +- What's transferred. Final design (Figma file URL). Tokens (referenced from Figma library). Asset library (images, icons, illustrations exported and named per convention). Component specifications (any new components designed). Responsive behavior notes. Motion specifications (entry, exit, hover, loading states). +- What's locked. Brief, direction, identity, voice, copy, design final. +- What stays open. Implementation choices (state management, framework patterns, accessibility implementation, performance optimization). Component naming if new components. +- Common breakdown. Asset exports happen ad-hoc as engineering needs them, leading to inconsistent file names, missing variants, and back-and-forth Slack messages. Mitigation: design phase exports a complete asset library (using the team's naming convention) before handoff. Engineering pulls from the library, does not request new exports during build unless missing. +- Artifact specification. Figma URL, exported asset folder (cloud bucket or repo path), responsive notes as Figma annotations or a sibling markdown doc. +- Platform support. Figma URL in the engineering ticket. Asset folder URL or path in the ticket. PR template references the design ticket. + +--- + +## 7. Engineering to Launch + +After QA verification per surface. The surface goes to launch. + +- What's transferred. Verified surface (deployed to staging, tested). QA evidence (Playwright run results, accessibility audit results, performance audit results, console error counts). Deployment checklist for this surface. Rollback plan. +- What's locked. Everything: brief, direction, identity, voice, copy, design, code merged to main, QA evidence. +- What stays open. Launch coordination (which surface launches first, monitoring during launch window, on-call coverage). +- Common breakdown. Launch happens before all surfaces have passed QA verification. Result: one surface launches with bugs, recoverable with rollback if monitoring catches it. Mitigation: launch readiness gate requires ALL surfaces to have passed QA verification, not just the most-prominent surface. +- Artifact specification. QA evidence linked to ticket (screenshots, GIFs, test result logs). Deployment checklist as a runbook document. Rollback plan as a sibling runbook document. +- Platform support. GitHub PR with QA artifact attachments or evidence URL. Linear or Jira ticket with the runbook URL. + +--- + +## 8. Adjacent observation handoff (cross-cutting) + +The handoff that fires when an agent or person, while working on Task X, notices something about Task Y or Surface Z that is not the current task but is contextually adjacent. + +### Examples + +- Working on copy for the homepage hero, the writer notices the footer copy is inconsistent with the new voice. Filing the footer inconsistency as an observation, not stopping the homepage work. +- Running QA on the pricing page, an agent notices the contact form on the about page has a console error. Filing the contact form error as an observation, not pausing the pricing-page QA. +- Updating the Figma design library, the designer notices a deprecated component is still being used in the dashboard mockups. Filing a usage-cleanup observation, not modifying the dashboard mockup. +- Reviewing a PR, an engineer notices a typo in a docstring in an unrelated file. Filing a typo observation, not blocking the PR review on it. + +### Why this handoff matters + +Without it, the team has two bad options. Option one: stop the current work and address the observation, derailing focus. Option two: ignore it, lose the context, never come back to it. The adjacent-observation handoff lets the current work proceed while preserving the finding for triage. + +### Routing + +The observation gets filed in a project triage queue, NOT directly assigned to anyone. The triage queue is reviewed on a regular cadence (typically daily standup or weekly grooming). The PM or tech lead triages the observation: discard if it's not relevant, file as a normal ticket if it is, attach to an existing ticket if it's a fragment of larger work. + +### Content of the observation + +Each filed observation includes: + +- What was observed. A specific factual statement (the footer says "Get in Touch" while the new voice would say "Reach out"). +- Why it might matter. A brief rationale (voice consistency, user-facing inconsistency, latent bug). +- Where it was noticed. A link to the work that was happening when the observation surfaced (the PR, the Figma frame, the Notion page). +- Suggested triage priority. The reporter's gut call (low / medium / high). The triager makes the actual call; the suggestion is just signal. + +### Platform support + +- Jira. A separate "triage" project or a labeled queue inside the main project. Observations get filed without an assignee; the triager assigns at triage time. +- Linear. A "Triage" inbox is built into Linear and works exactly for this purpose. +- Notion. A triage database; the assignee field stays empty until triage. +- GitHub. Observations filed as issues without an assignee; CODEOWNERS may auto-route the issue to the relevant team for triage. + +The orchestration plan specifies which platform's triage queue is the canonical one for the project (typically the same platform as the main work) and the triage cadence (daily standup or weekly grooming). Without those specifics, observations either pile up untriaged or scatter across channels and get lost. + +--- + +## How handoffs compose with gates + +A gate closes a phase. A handoff opens the next phase's work against the gate's locked output. The two patterns reinforce each other: gates make sure nothing premature ships; handoffs make sure the receiving work has what it needs to start. + +A failed gate triggers a handoff backward (rework the prior phase). A failed handoff (artifact missing, scope unclear) is itself often the symptom of a gate that didn't enforce its pass criteria. When a handoff goes wrong, audit the prior gate's criteria. diff --git a/skills/integration-orchestrator/references/platform-implementation.md b/skills/integration-orchestrator/references/platform-implementation.md new file mode 100644 index 0000000..f62ee1b --- /dev/null +++ b/skills/integration-orchestrator/references/platform-implementation.md @@ -0,0 +1,174 @@ +# Platform implementation + +How the orchestration plan implements in each platform. Per platform: workflow representation (how phases, gates, lock points, and handoffs map), MCP integration notes (what AI agents can do via the platform's MCP), and CLI alternatives (where the CLI is the better tool than MCP). + +For setup screenshots and additional team patterns, consult each platform's official documentation alongside this file. + +--- + +## Jira / Atlassian + +### Workflow representation + +- Phase representation. Each phase becomes an Epic. Stories or Tasks live within the Epic. Custom fields tag the Phase explicitly. +- Gate representation. Workflow status. The 5-status taxonomy (Todo / In Progress / Waiting / Blocked / Done) maps to Jira's workflow statuses, with workflow validators or transitions enforcing gate rules. A custom "Gate Status" field tracks gate state separately from issue status. +- Lock-point representation. Custom field "Locked" (boolean) on the parent artifact (Epic for phase locks, Story for per-page locks). Locked issues display a visible label so reviewers know not to make untracked changes. +- Handoff representation. Issue link types ("Blocks", "Is blocked by", "Relates to"). Linked Confluence page for the artifact (brief, direction, voice guide, copy doc). +- Concrete setup snippet. Issue type scheme: Epic, Story, Task, Subtask, Bug. Custom fields: Phase (single-select with phase names), Locked (checkbox), Approver (user picker), Gate Status (single-select with the 8 standard gates). Workflow scheme: 5-status taxonomy with validators preventing premature transitions. + +### MCP integration notes + +- Availability. Official remote MCP server, launched 2025. +- References. [Atlassian's Remote MCP Server announcement](https://www.atlassian.com/blog/announcements/remote-mcp-server) and [github.com/atlassian/atlassian-mcp-server](https://github.com/atlassian/atlassian-mcp-server). +- Capabilities. Jira issue CRUD, status transitions, comment posting, JQL queries, Confluence page operations (read, write, update). Authentication via OAuth or API token. +- What the orchestrator skill can populate via MCP. Initial epic structure from the orchestration plan (one epic per phase). Initial issue tree (stories per work item). Custom field values from the orchestration plan (Phase, Approver, Gate Status). Comments documenting handoffs and gate transitions. Confluence pages for the brief, direction artifact, voice guide, and orchestration plan itself. +- Practical limits. Workflow scheme creation typically requires admin-level UI setup; MCP is better at populating against an existing scheme than at configuring the scheme from scratch. Heavy Confluence content edits lose Atlassian Document Format (ADF) details through MCP roundtrips when the content is rich (tables, callouts, complex code blocks). For simple page content, MCP roundtrips work; for heavily-formatted content, edit in the UI or use the CLI. + +### CLI alternatives and when to use them + +- Atlassian official CLI (acli) plus community alternatives (jira-cli, etc.). +- When CLI is the better choice. + - Bulk operations across many tickets (200+ issues). MCP roundtrips become token-expensive at scale; CLI is more efficient. + - Heavy Confluence content edits where ADF formatting matters. CLI tools that parse and write ADF directly preserve formatting better than MCP roundtrips. + - Scripted reporting (export issues to CSV, generate burndown reports, run JQL across multiple projects). + - CI integration (running JQL in a CI step to validate that all blockers are resolved before deploy). +- Pattern note. Some teams mirror Jira and Confluence content as local markdown files in a `.atlassian/` folder, syncing periodically via CLI. This pattern trades simplicity for power. Document it as one viable approach for engineering-heavy teams; PMs will rarely need it. + +--- + +## Linear + +### Workflow representation + +- Phase representation. Each phase becomes a Project. Cycles (Linear's time-boxed sprints) sit within the project for week-by-week granularity. +- Gate representation. Project status workflow plus issue status workflow. Linear's status workflow customizes to the 5-status taxonomy. Labels mark gate state per issue (e.g., "gate:identity-approved", "gate:qa-pending"). +- Lock-point representation. Labels (e.g., "locked:identity-tokens", "locked:voice"). Locked issues stay visible in their project but cannot be reopened without an explicit label removal. +- Handoff representation. Project relationships (predecessor / successor projects), issue dependencies, and Linear's automatic mention parsing for cross-references. +- Concrete setup snippet. Project template per project type (new brand build, rebrand, etc.) with phases pre-populated as projects, cycles configured, label taxonomy defined. Status workflow customized to include Blocked as a first-class status (Linear ships with Backlog, Todo, In Progress, Done, Cancelled by default; add Waiting and Blocked). + +### MCP integration notes + +- Availability. Official, well-supported. +- Reference. [linear.app/docs/mcp](https://linear.app/docs/mcp). +- Capabilities. Issues, projects, cycles, teams, labels, comments, attachments. Full CRUD on most entities; webhooks for event-driven workflows. +- What the orchestrator skill can populate via MCP. Project setup with cycles. Label taxonomy from the orchestration plan. Initial issue population per phase. Project description and milestones. Status workflow customization. Initial assignee and reviewer assignments per the orchestration plan's review-by routing. +- Coverage note. Linear's MCP coverage is the most complete of the 5 platforms. For teams running a Linear-based stack with AI agents, this MCP is the recommended starting point. The agent can do almost everything programmatically. + +### CLI alternatives and when to use them + +- CLI status. No widely-adopted Linear CLI. The MCP coverage is sufficient that CLI is rarely needed. +- API direct calls remain an option for scripted setup if MCP isn't available in the runtime context. +- When the API is the better choice. Bulk import scripts when migrating from another platform. Scheduled reports run from CI. Webhook handlers for event-driven external integrations. + +--- + +## Notion + +### Workflow representation + +- Phase representation. Brief database with one row per project. Related databases for direction docs, identity specs, voice guides, copy decks. Each related database has its own rows; relation properties tie everything to the canonical brief. +- Gate representation. Status property on each artifact row. Phase view filters the database by status to surface what's open vs locked. +- Lock-point representation. A "Locked" checkbox or status property on each artifact row. Filtered views surface locked vs unlocked artifacts. +- Handoff representation. Relation properties between databases. The brief row relates to the direction row, which relates to the identity spec row, which relates to the voice guide row, etc. +- Concrete setup snippet. Brief database schema: Title, Status, Phase, Locked, Approver, Owner, Notes. Related databases: Direction, Identity, Voice, Copy, Design, QA Evidence. Relation properties tie each related row back to the brief. Dashboard view per phase. + +### MCP integration notes + +- Availability. Official. +- Reference. [developers.notion.com/guides/mcp/overview](https://developers.notion.com/guides/mcp/overview). +- Capabilities. Database queries, page CRUD, property updates, block-level reads, search. +- What the orchestrator skill can populate via MCP. Brief-as-database-row schema creation (with the property set from the orchestration plan). Relation property setup between briefs and project artifacts. Initial brief content population from the orchestration plan. Dashboard view configuration where the view config supports it (with caveats; some view configurations remain UI-only). +- Practical limits. Workspace-level permissions and team membership remain UI-driven; MCP is most useful AFTER initial workspace setup. Some view types (calendar views, certain board views with custom grouping) cannot be created via MCP and must be set up in the UI. + +### CLI alternatives and when to use them + +- Community CLIs. notion-cli and similar tools exist but are less mature than the MCP. +- When the CLI is the better choice. Exporting databases for backup. Bulk content migration from another tool. Scripted database schema changes (adding properties across hundreds of rows). +- For most teams. The MCP is sufficient. CLI tools become useful only for specialized operations the MCP can't handle. + +--- + +## Figma + +### Workflow representation + +- Phase representation. Library file with frame folders per phase: Discovery moodboards, Direction tokens, Identity components, Production frames. Frame-level review status surfaces in the Figma comments and frame metadata. +- Gate representation. Frame status (Ready for review / In review / Approved). Components versioned in the library; outdated components marked as deprecated rather than deleted (downstream files still reference them). +- Lock-point representation. Library publish state. Once a library version is published, dependent files reference that version. Token changes ship as a new library version, which downstream files explicitly opt into. +- Handoff representation. Frame URL plus exported assets. Engineering handoff uses Dev Mode for token export and component spec. +- Concrete setup snippet. Library file structure: top-level pages for "Tokens", "Components", "Patterns", "Page templates", "Working files". Within each, frame folders per phase. Frame-level review status set via Figma's standard comment-and-status workflow. Library publish discipline: identity tokens publish at the identity gate; the library version is the lock point. + +### MCP integration notes + +- Availability. Figma Dev Mode MCP exists but is dev-mode-focused (component inspection, code generation, design token export). +- Reference. Figma's [Dev Mode documentation](https://www.figma.com/dev-mode/). +- Capabilities (Dev Mode MCP). Component property reads. Design token export (color, typography, spacing). Frame inspection (layer tree, properties, constraints). Component variant queries. +- What the orchestrator skill can populate via MCP. Limited. Library structure recommendations and frame organization remain primarily manual setup. The MCP is more useful for downstream developer handoff than upstream design ops. +- Practical limits. Design library creation, frame organization, library-level permissions, and team membership are UI-driven. Treat the orchestrator skill's Figma recommendations as documentation for the design lead, not as automation targets. + +### CLI alternatives and when to use them + +- Figma API. Can be invoked via custom scripts for token export, asset download, and metadata queries. No first-party CLI for design ops. +- When the API is the better choice. Token export scripts that run in CI to update a design system repository. Asset download automation for engineering handoffs. Metadata reporting (audit how many frames are in review status across the library). +- For most cases. The design lead implements Figma orchestration manually following the skill's recommendations. Automation is layered in only when the project is large enough to warrant the engineering investment. + +--- + +## GitHub + +### Workflow representation + +- Phase representation. Issues for non-engineering tracking (when GitHub is the canonical platform; otherwise Jira/Linear lead). Branches per feature with naming convention `{type}/{ticket}-{slug}`. PRs for design and engineering review. +- Gate representation. Branch protection on `main`. PR review requirements. CODEOWNERS for review routing. GitHub Actions for CI gates (lint, test, build, deploy preview). +- Lock-point representation. Branch state. Once code is merged to main, it's locked unless a follow-up PR amends it. Tags mark release lock points. +- Handoff representation. PR description references the originating ticket. PR review by CODEOWNERS routes to the right reviewer. PR merge triggers ticket auto-transition (configured per platform combination). +- Concrete setup snippet. Branch protection: require PR reviews before merge, require status checks (CI), require linear history (rebase or squash, no merge commits). CODEOWNERS file routes PRs to the relevant team. PR template requires ticket reference, summary, test plan, screenshots/GIFs for UI changes. GitHub Actions workflow runs CI gates on every PR. + +### MCP integration notes + +- Availability. Official. +- Reference. [github.com/github/github-mcp-server](https://github.com/github/github-mcp-server). +- Capabilities. PR ops (create, comment, review, merge). Issue ops (create, comment, close, label). File content (read, write). Branch protection (read; configuration is mostly UI/API-driven). Repository search. Code search. Workflow runs (read). +- What the orchestrator skill can populate via MCP. PR template files. Issue templates. CONTRIBUTING.md and review-protocol docs. Initial issue tree from the orchestration plan when GitHub is the canonical work tracker. CODEOWNERS file. GitHub Actions workflow files committed to `.github/workflows/`. +- Practical limits. Branch protection rulesets are typically configured via GitHub UI or repository settings API (not MCP); the orchestrator skill's branch protection recommendations remain documentation rather than automation. Repository creation, team membership, and organization-level settings are UI-driven. + +### CLI alternatives and when to use them + +- gh CLI. The dominant tool for GitHub operations. Officially maintained, broadly adopted. +- When to prefer gh CLI over MCP. + - Bulk PR operations (merging 20 dependabot PRs in a single sweep). + - Scripted workflows (a deploy script that creates a release, tags, and updates a changelog). + - Repository setup automation (create a new repo, push initial commits, set up labels and branch protection). + - When token cost matters on heavy operations. The CLI is more efficient than MCP roundtrips for repetitive tasks. +- Hybrid pattern. Most production setups use both. MCP for navigation and orchestration ("show me open PRs assigned to me", "comment on PR #123 with this summary"); gh CLI for transactional and bulk operations ("create a PR from this branch with these reviewers", "merge these 10 dependabot PRs"). The two tools complement each other. + +--- + +## Cross-platform patterns + +### Code-to-ticket linkage + +The standard convention for linking PRs and commits back to tickets: + +- Branch naming. `{type}/{ticket}-{slug}`. Type is one of feat / fix / chore / docs / refactor. Examples: `feat/RAMP-123-homepage-hero-rewrite`, `fix/LIN-456-contact-form-validation`. Ticket prefix matches the platform (RAMP for the team's main project in Jira, LIN for Linear, etc.). +- PR descriptions. Include the ticket reference. Closes RAMP-123 for full work; Refs RAMP-123 for partial work. Many platforms auto-link the ticket when this format is used. +- Commit messages. Include the ref where relevant. Squash-merge workflows preserve the ref in the squash commit, which means the merged commit on main has the ticket trail. + +### Status synchronization + +When a PR merges, the linked ticket auto-transitions. Configure via the linked platform's automation: + +- Jira automation. "When PR merged, transition issue to Done" (with QA verification gate enforced upstream so this is safe). +- Linear's auto-transition. Linear-GitHub integration auto-moves issues based on PR state. +- GitHub Actions. A workflow that runs on PR merge and posts a comment to the linked Linear/Jira issue. Useful when the platform's native integration doesn't cover the team's exact transition rules. + +### Multi-platform stacks + +Common combinations: + +- Linear + GitHub. Most common for tech teams. Linear's MCP is mature; GitHub's MCP is mature. The two integrate well via Linear's GitHub integration plus PR/branch naming conventions. +- Jira + GitHub. Most common for enterprise. Atlassian remote MCP plus GitHub MCP cover the orchestration; workflow setup is more involved than Linear because Jira's workflow flexibility means more setup decisions. +- Notion + Linear + GitHub. PM-led with engineering sub-tracking. Notion holds the brief and creative artifacts; Linear holds the engineering work; GitHub holds the code. Notion-Linear linking is via relation property pointing to the Linear issue URL; Linear-GitHub linking is via Linear's native integration. +- Notion + Figma + GitHub. Creative-led with engineering handoff. Notion holds the brief; Figma holds the design; GitHub holds the code. This combination has the lightest engineering tooling and works for design-led projects with simple production paths. + +The orchestration plan specifies the canonical platform for each work type and the linkage convention between platforms. Without that specification, work scatters across platforms and links break. diff --git a/skills/integration-orchestrator/references/team-size-modulation.md b/skills/integration-orchestrator/references/team-size-modulation.md new file mode 100644 index 0000000..246ba2f --- /dev/null +++ b/skills/integration-orchestrator/references/team-size-modulation.md @@ -0,0 +1,65 @@ +# Team-size modulation + +A 2-person team and a 12-person team need different orchestration. The framework (phases, gates, lock points, handoffs) is the same; the cadence's review density, sync ceremony, and tool-stack adjustments scale with team size. + +This file covers four scales: solo, small (2-3), medium (4-7), large (8+). For each: review density, sync cadence, handoff formality, risk profile, tool-stack adjustments, and AI agent participation pattern. + +--- + +## Solo (1 person) + +Everything is the same person playing every role. The brief author, identity designer, voice writer, copy writer, design lead, and engineer are all you. + +- Review density. Self-review only. Per-phase self-review checklists replace formal gates. The risk is that nothing actually catches mistakes; the discipline is to step away from the work between drafting and reviewing (overnight is best, an afternoon walk is the minimum). +- Sync cadence. Daily plan, weekly review against the orchestration plan. Document the daily plan and the weekly review in a project state file (CLAUDE.md, AGENTS.md, or .agent/state.md). +- Handoff formality. Inline. Self-handoffs document themselves in the project state file rather than as separate artifacts. +- Risk profile. Phases blur together. Lock points get unfrozen without ceremony. The brief that was approved last week becomes "well, I had a better idea, let me just edit it" and downstream work drifts. +- Tool-stack adjustments. Skip Jira workflow validators, Linear cycle ceremony, formal review routing. Use the simplest tool the project needs (often Notion or markdown files in a repo). Resist setting up tooling beyond what's actually used; solo projects fail more often from over-tooling than from under-tooling. +- AI agent participation pattern. Heavy. Solo work benefits most from agent participation because the agent is the second pair of eyes that solo work otherwise lacks. The agent runs QA verification gates, reviews copy against the locked voice, runs accessibility audits, and surfaces patterns the solo person might miss. The orchestration plan output specifies which agent runs at which gate. + +--- + +## Small (2-3 people) + +Single reviewer per gate. Async handoffs are fine. Daily standup is sufficient for sync. + +- Review density. One reviewer per gate. The team picks a primary reviewer per phase based on expertise (design lead reviews identity gates, copy lead reviews voice and copy gates, the senior engineer reviews QA verification and launch readiness). +- Sync cadence. Daily 15-minute standup. Weekly 60-minute phase review. Async messaging in between. +- Handoff formality. Documented but inline (a Notion page comment, a Linear issue description, a Slack message in the project channel). The small team can rely on shared context that larger teams cannot. +- Risk profile. The single reviewer becomes a bottleneck. When the design lead is the only person who can pass the identity approval gate and they're on PTO, the project blocks. Mitigation: the orchestration plan specifies a backup reviewer per gate. +- Tool-stack adjustments. Light tool setup. Linear's default workflow is fine; Jira can run with a basic workflow scheme; Notion runs with basic database schemas. Don't set up complex automations until the team feels the lack of them. +- AI agent participation pattern. Moderate. Agents handle production tasks, QA verification, and adjacent observation filing. Humans handle reviews, gate approvals, and decisions that require taste or political judgment. The orchestration plan specifies which roles agents fill and which stay human. + +--- + +## Medium (4-7 people) + +Multiple reviewers, async sync points, weekly phase reviews. The team is large enough that shared context erodes; documentation matters more. + +- Review density. Two reviewers per gate (one primary, one secondary for cross-check). Reviewer rotation across phases prevents one person from becoming the bottleneck. +- Sync cadence. Daily standup. Weekly phase review. Bi-weekly cross-track sync if there are parallel tracks. Async messaging in between with explicit channels per phase. +- Handoff formality. Documented in the canonical platform (Jira issue, Linear project, Notion database row). Slack threads are fine for discussion but the canonical record lives in the work-tracking platform. +- Risk profile. Review density becomes the gating factor. Reviewers stack up at end of phase, leading to fatigue reviews and rubber-stamped approvals. Mitigation: within-phase mini-gates that flatten review demand. Instead of reviewing 8 deliverables on phase-end Friday, review 2 mid-week and 6 at phase-end. +- Tool-stack adjustments. Custom fields, labels, and automation start to matter. Set up workflow validators that prevent premature transitions. Set up custom views per role (designer view, engineer view, PM view) so each person sees only what's relevant to them. +- AI agent participation pattern. Agents handle QA verification gates, surface adjacent observations, and run reports (which tickets are stuck, which gates are open, which assignees are overloaded). Humans handle reviews and approvals. The agent's role expands from "do production work" to "monitor the orchestration plan and surface drift". + +--- + +## Large (8+ people) + +Formal phase reviews, dedicated PM for orchestration, multiple parallel tracks. Cross-track drift is the dominant risk. + +- Review density. Three or more reviewers per gate. Phase reviews become formal meetings with prepared agendas. Reviewer rotation is mandatory; the project cannot rely on any one person. +- Sync cadence. Daily standup per track. Weekly cross-track sync. Bi-weekly project-wide review. Monthly stakeholder review for projects spanning multiple months. +- Handoff formality. Strict. Every handoff specifies artifacts, locked items, and change-request protocols in writing. Async handoffs without artifact specification break large teams; the receiving track wastes a week trying to figure out what was actually handed off. +- Risk profile. Cross-track drift. Track A and Track B both interpret the brief differently; by week 3 the two tracks read as different brands. Mitigation: a dedicated brief-owner role whose job is to maintain the brief as canonical reference, plus cross-track sync ceremonies and explicit change-request protocols. Brief drift is a leading indicator; the brief-owner role exists to catch it before it becomes track drift. +- Tool-stack adjustments. Full workflow scheme with validators. Custom fields tracking phase, gate status, approver, locked status. Multiple boards or views per track. Automation rules for status synchronization across linked platforms (Jira-GitHub, Linear-GitHub). Reporting dashboards. +- AI agent participation pattern. Agents become orchestration monitors. The agent's role is to track phase status across tracks, surface drift, run cross-track sync prep (which tracks are on schedule, which are slipping), file adjacent observations across track boundaries, and run QA verification gates. The agent is most valuable at the cross-track surface where humans cannot easily hold all the context. + +--- + +## How to choose your scale's pattern + +Match the cadence to actual team size. The most common mistake is to use a small-team cadence on a medium-team project, which leads to the single-reviewer bottleneck, OR to use a large-team cadence on a small-team project, which leads to ceremony overhead that nothing earns. + +When the team scales mid-project (a 2-person small team grows to 5 people during production phase, for example), the orchestration plan should specify the transition: at what point does the cadence shift, what new reviewers come online, what additional ceremonies start. The plan's risk register should flag scaling moments as a known risk because cadence transitions are themselves a source of drift. diff --git a/skills/interactive-product-tour/SKILL.md b/skills/interactive-product-tour/SKILL.md new file mode 100644 index 0000000..59256aa --- /dev/null +++ b/skills/interactive-product-tour/SKILL.md @@ -0,0 +1,251 @@ +--- +name: interactive-product-tour +description: "Designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. Honest about tooltip-spam (visual noise that users develop blindness to), one-and-done (help invisible at the moment of need), and contextual-when-needed (surfaces help at the moment friction occurs) patterns. Triggers on product tour, in-product tooltip, contextual help, walkthrough, feature tour, hint system, in-app guidance, tour platform. Also triggers when feature adoption is low, when users miss key product capabilities, or when an in-product help system is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing in-product tours and contextual help. Distinguishes tooltip-spam (every button has a tour stop) from one-and-done (tour shows once, never seen again) from contextual-when-needed (surfaces help at the moment friction occurs)" +display_order: 8 +--- + +# Interactive Product Tour + +A senior product marketing director's playbook for designing in-product tours, tooltips, and contextual help that teach product capabilities without becoming friction. Trigger logic, tour architecture, contextual placement, completion tracking. The discipline of building help systems that surface at moments of need and disappear when not needed. + +Most product tours fail in one of two ways. They paint every button, link, and feature with "click for tour" hints until the visual noise is so great that users develop blindness to the dots. Or they show a single first-login tour the user skips or skims, after which the same help never re-surfaces when the user actually hits a moment of friction. Help that is invisible at the moment of need is help that does not exist. + +The tours that work do something different. They trigger when the user is at a moment of friction, not all the time. They surface contextual hints when the user enters a section they have not explored, clicks into a feature requiring setup, or returns after a long absence. The system knows what the user knows and surfaces help at the right moment. + +The voice is the senior product marketing director who has watched feature adoption double when tours were redesigned and watched it collapse when more tooltips were piled onto every surface. Practical, opinionated about the trigger logic that distinguishes useful help from visual noise, willing to call out when no in-product tour at all is the right answer. + +When to use this skill: scoping an in-product help system for the first time, auditing a tour system that produces engagement metrics with no adoption lift, designing the trigger logic that decides when help surfaces, or deciding which features warrant tours vs documentation. + +--- + +## What this skill covers + +This skill spans in-product tours, tooltips, and contextual help. The growth-tooling distinctions: + +- `onboarding-wizard-design` is the sequential first-run experience. This skill is contextual help WITHIN the product, surfacing across the lifecycle. +- `chatbot-flow-design` is conversational help. This skill is non-conversational tour and tooltip help. +- `interactive-product-tour` (this skill) is trigger logic, tour architecture, contextual placement, completion tracking, and the discipline of being absent until needed. +- `discovery-research-synthesis` is research that informs tour content. Input, not part of. +- `pm-spec-writing` is the spec for engineers building the tour. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams, agencies running activation work for SaaS clients. + +Out of scope: first-run wizards (covered by `onboarding-wizard-design`); conversational help (covered by `chatbot-flow-design`); the engineering implementation; specific Userpilot/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The tour decision: when tours earn vs when documentation suffices + +Before designing the tour system, decide whether tours are the right tool. + +Tours earn investment when: + +- The product has features users genuinely miss without prompting. Specific functionality buried in menus, advanced workflows that require sequence, integrations users do not know exist. +- The audience benefits from in-context guidance more than out-of-context documentation. Tours teach in the place the user will use the feature; docs require context-switching. +- The team can maintain tours as the product evolves. Tour content decays; without maintenance commitment, tours point to deprecated UI. +- The success metric is defined. Feature adoption, time-to-value for specific capabilities, reduction in support tickets for tour-covered features. + +Tours do NOT earn investment when: + +- The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. +- The audience prefers self-directed discovery. Some audiences resent in-product guidance and prefer to explore. +- The team cannot maintain tours alongside product changes. Stale tours are worse than no tours. +- The product changes frequently. Tour maintenance can exceed tour value if the product churns rapidly. + +The decision is not "should we have a tour system"; it is "is in-product tour the right tool for this product and audience." + +Detail in [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md). + +--- + +## Tooltip-spam vs one-and-done vs contextual-when-needed + +The keystone framing. + +Tooltip-spam. Every button, link, and feature has a "click for tour" hint or pulsing dot. Visual noise. Users develop blindness to the dots; the tour system fails as a teaching surface. Cost: the design effort produces help nobody perceives; the visual clutter degrades the product overall. + +One-and-done. A single tour shown on first login. Users skip or skim. The same tour never re-surfaces when the user actually hits a moment of friction. Cost: help that is invisible at the moment of need does not help. Feature adoption stays low; support tickets persist for features the tour covered. + +Contextual-when-needed. Tours and tooltips trigger when the user is at a moment of friction (entered a section they have not explored, clicked into a feature requiring setup, returned after a long absence, hit a feature flag's first activation). The system knows what the user knows and surfaces help at the right moment. Cost: trigger logic is meaningful work; payoff is help that compounds adoption over time. + +The litmus test. Watch a user encounter a feature for the first time. Does the help system surface useful guidance at that moment, or did it surface guidance at first-login that the user has long forgotten? If the former, contextual-when-needed. If the latter, one-and-done. If the help is competing with 14 other tooltip dots scattered across the page, tooltip-spam. + +--- + +## Trigger logic: event-based vs time-based vs state-based + +The mechanism that decides when help surfaces. + +Event-based triggers. Help appears in response to a user action. Clicked a feature for the first time, entered a new section, completed a flow. + +When to use. Default for most contextual help. The user did something; help responds. + +Time-based triggers. Help appears after time elapsed. Returned to the product after 30 days of absence; been on this page for 60 seconds without acting. + +When to use. Time can signal need (long absence; stuck on a page). Use sparingly; time alone is a noisy signal. + +State-based triggers. Help appears based on user state. New user vs power user; account size; feature usage history. + +When to use. When the help differs by user segment. State-based triggers personalize help. + +Combined triggers. Most production tour systems combine all three. Event-driven, with time and state modulating frequency and content. + +The discipline. The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. + +Detail in [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md). + +--- + +## Tour architecture: single tour vs branched vs library of micro-tours + +How help is organized. + +Single tour. One linear tour covering the product. Simple; rigid; rarely fits how users actually explore. + +Branched tour. Tour adapts based on user choices or path through the product. More relevant; more complex. + +Library of micro-tours. Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. Most flexible; most maintenance. + +The choice. Most modern systems use the micro-tour library approach. Single tours feel canned; branched tours are hard to maintain at scale; a library of contextual micro-tours matches how users actually explore. + +Detail in [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md). + +--- + +## Contextual placement: where help appears, how it dismisses + +The visual design of help. + +Placement patterns. + +- Tooltip on hover. Help appears next to the element on hover. Lightweight; familiar. +- Spotlight overlay. Element highlighted, help appears alongside. More prominent; more disruptive. +- Sidebar. Help appears in a side panel. Can persist while the user works. +- Inline. Help appears in the page flow. Non-disruptive; harder to dismiss. + +Dismissal mechanics. + +- Click X. Standard close. Always available. +- Click outside. Help dismisses if the user interacts with anything else. Implies non-modal help. +- Auto-dismiss. Help fades after a few seconds. Risky; users may not have read it. +- Persistent until acted on. Help stays until the user takes the suggested action. Powerful for guided flows; intrusive otherwise. + +Non-intrusion principle. Help should be findable when wanted, ignorable when not. Modal help that blocks the screen is intrusive; help that disappears too easily fails to teach. + +Detail in [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) and [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md). + +--- + +## Completion tracking and re-trigger logic + +Knowing what each user has seen, deciding when to show again. + +Per-user state tracking. + +- Which tours has the user completed? +- Which tours has the user dismissed? +- Which tours has the user seen but not completed? +- Time since last interaction. + +Re-trigger logic. + +- Completed tours: usually do not re-show. +- Dismissed tours: respect the dismissal; possibly re-show after a long delay if the feature becomes relevant again. +- Skipped tours: re-show at moments of relevance. +- Long-absent users: re-orient with abbreviated help. + +The over-trigger trap. Showing the same tour to users who have completed it. Trust degrades; users disable tours. + +The under-trigger trap. Tours never re-surfacing when the user hits the same friction again. Help fails at the moment of need. + +Detail in [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md). + +--- + +## Power-user vs new-user differentiation + +Different users need different help. + +The principle. Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference. + +Differentiation signals. + +- Feature usage history (has the user used this feature before?). +- Tenure (how long has the user been on the product?). +- Engagement frequency (active daily vs returning monthly). +- Self-reported skill level (rare; usually inferred). + +Differentiation patterns. + +- Power users see help only on new features. +- New users see help on the features matching their stage of exploration. +- Returning users see re-orientation help if their last session was long ago. + +The over-helping trap. Helping power users with features they mastered. Trust degrades. + +The under-helping trap. Treating all users as power users. New users miss critical help. + +Detail in [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-tour-failures.md`](references/common-tour-failures.md). + +- "Tours show but feature adoption does not improve." Help may be visually present but not contextually relevant. Audit trigger logic. +- "Users disable tours globally." The system is annoying users. Audit frequency, dismissal, and over-triggering. +- "First-login tour completion is 80 percent; feature adoption is unchanged." One-and-done pattern; tour content not retained at moment of need. +- "Tooltips appear everywhere; nobody clicks them." Tooltip-spam; rebalance to contextual triggers. +- "Tour content references features we deprecated 6 months ago." Maintenance lapse. +- "Power users complain about pop-ups for things they already know." No power-user differentiation. +- "Tours work on desktop, break on mobile." Mobile UX of help system not tested. +- "Some teams ship tours; others don't bother. Inconsistent." No tour governance; some teams build, others ignore. +- "Tours triggered correctly but users do not act on the suggestion." Help content unclear or call-to-action absent. + +--- + +## The framework: 12 considerations for product tour design + +When designing or auditing an in-product tour system, walk these 12 considerations. + +1. The tour decision. Are tours the right tool, or does documentation suffice? +2. Contextual-when-needed, not tooltip-spam or one-and-done. Help surfaces at moments of friction. +3. Trigger logic sound. Event-based primary, with time and state modulation. +4. Tour architecture matches usage. Library of micro-tours preferred for most products. +5. Contextual placement non-intrusive. Help findable when wanted, ignorable when not. +6. Dismissal mechanics honest. Standard close, click-outside dismiss, no auto-dismiss before reading. +7. Completion tracking instrumented. Per-user state, per-tour status. +8. Re-trigger logic respectful. Completed tours do not re-show; dismissed tours respected. +9. Power-user vs new-user differentiation. Help calibrated to user state. +10. Mobile parity. Help works on the devices the audience uses. +11. Maintenance discipline. Tours updated alongside product changes; quarterly audit. +12. Adoption as success metric. Not just tour completion; feature adoption is the metric that matters. + +The output of the framework is a tour system that earns the user's attention by being absent until needed, surfaces help at moments of relevance, and produces feature adoption. + +--- + +## Reference files + +- [`references/tour-decision-criteria.md`](references/tour-decision-criteria.md) - When tours earn the build vs when documentation suffices. +- [`references/trigger-logic-patterns.md`](references/trigger-logic-patterns.md) - Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. +- [`references/tour-architecture-patterns.md`](references/tour-architecture-patterns.md) - Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. +- [`references/contextual-placement-patterns.md`](references/contextual-placement-patterns.md) - Tooltip, spotlight, sidebar, inline. Placement and visual design. +- [`references/completion-tracking-and-re-trigger.md`](references/completion-tracking-and-re-trigger.md) - Per-user state, re-trigger logic, the over-trigger and under-trigger traps. +- [`references/power-user-vs-new-user-patterns.md`](references/power-user-vs-new-user-patterns.md) - Differentiation signals and patterns. The over-helping and under-helping traps. +- [`references/dismissal-and-non-intrusion-patterns.md`](references/dismissal-and-non-intrusion-patterns.md) - Dismissal mechanics. The non-intrusion principle. +- [`references/tour-anti-patterns.md`](references/tour-anti-patterns.md) - The patterns that look like tours but degrade the product. +- [`references/common-tour-failures.md`](references/common-tour-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: tours earn the user's attention by being absent until needed + +The tour systems that work as compounding assets are the ones the user does not perceive as a tour system. Help surfaces at the moment of friction; disappears when the friction passes; never piles up as visual noise. The user encounters a feature for the first time, sees a brief contextual hint, takes the suggested action, and moves on. The system did its job; the user did not have to think about the system. + +That is the bar. Below the bar are tooltip-spam (visual noise that users develop blindness to) and one-and-done (help invisible at the moment of need). Above the bar are contextual-when-needed systems where trigger logic, tour architecture, contextual placement, and re-trigger respect work together to make help feel ambient rather than imposed. + +The discipline is in the design choices. The decision to build a tour system at all, or rely on documentation. The trigger logic that decides when help surfaces. The architecture that organizes micro-tours by feature and workflow. The placement and dismissal that make help non-intrusive. The completion tracking that prevents re-showing what users already know. The power-user differentiation that respects expertise. The maintenance cadence that keeps tours in sync with the product. diff --git a/skills/interactive-product-tour/references/common-tour-failures.md b/skills/interactive-product-tour/references/common-tour-failures.md new file mode 100644 index 0000000..09a5d4d --- /dev/null +++ b/skills/interactive-product-tour/references/common-tour-failures.md @@ -0,0 +1,171 @@ +# Common tour failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Tours show but feature adoption does not improve." + +The diagnosis. Help may be visually present but not contextually relevant. Tour content may be unclear or call-to-action absent. + +The cure. Audit trigger logic (`references/trigger-logic-patterns.md`). Verify tours fire at moments of friction. Audit content; ensure tours have clear CTAs. + +--- + +## "Users disable tours globally." + +The diagnosis. The system is annoying users. Audit frequency, dismissal, over-triggering. + +The cure. Frequency caps (`references/dismissal-and-non-intrusion-patterns.md`). Per-user state tracking (`references/completion-tracking-and-re-trigger.md`). Audit cumulative exposure per session. + +--- + +## "First-login tour completion is 80 percent; feature adoption is unchanged." + +The diagnosis. One-and-done pattern. Tour content not retained at moment of need. + +The cure. Move from single first-login tour to library of contextual micro-tours. Detail in `references/tour-architecture-patterns.md`. + +--- + +## "Tooltips appear everywhere; nobody clicks them." + +The diagnosis. Tooltip-spam. Visual blindness has set in. + +The cure. Audit triggers. Remove tooltips that are not earning their place. Reserve hints for moments of friction. + +--- + +## "Tour content references features we deprecated 6 months ago." + +The diagnosis. Maintenance lapse. + +The cure. Quarterly tour audit. Tag tours by feature; deprecate tours when features deprecate. + +--- + +## "Power users complain about pop-ups for things they already know." + +The diagnosis. No power-user differentiation. + +The cure. Add feature-usage gating. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tours work on desktop, break on mobile." + +The diagnosis. Mobile UX of help system not tested. + +The cure. Mobile-first design and testing. Different placement patterns for mobile. + +--- + +## "Some teams ship tours; others don't bother. Inconsistent." + +The diagnosis. No tour governance. Some teams build tours, others ignore them. + +The cure. Tour ownership. Designate who maintains the system. Tour authoring guidelines. + +--- + +## "Tours triggered correctly but users do not act on the suggestion." + +The diagnosis. Help content unclear or call-to-action absent. + +The cure. Audit tour content. Each tour should have a clear, actionable CTA matched to the user's likely intent. + +--- + +## "Tour completion looks fine; adoption is mixed by feature." + +The diagnosis. Some tours work, others do not. Per-tour adoption tracking surfaces which. + +The cure. Per-tour adoption-lift measurement. Retire or redesign tours that do not produce adoption lift. + +--- + +## "We added more tours; user complaints went up." + +The diagnosis. Cumulative frequency overload. Each tour reasonable; total exposure too much. + +The cure. Per-session frequency caps. Audit cumulative exposure. + +--- + +## "Returning users miss new features we shipped during their absence." + +The diagnosis. No re-orientation help for long-absent users. + +The cure. Returning-user re-orientation pattern. Detail in `references/power-user-vs-new-user-patterns.md`. + +--- + +## "Tour analytics broke after the last release." + +The diagnosis. Instrumentation drift. + +The cure. Verify analytics after every release. Add to deployment smoke test. + +--- + +## "Tour fires but user is mid-task; they abandon." + +The diagnosis. Trigger logic does not respect ongoing tasks. + +The cure. Detect mid-task state; defer tour. Trigger at moments of natural pause. + +--- + +## "We A/B tested tour content; adoption did not move." + +The diagnosis. Content was not the issue. Could be trigger, audience, or feature design. + +The cure. Test variables that matter. Trigger logic, audience targeting, feature design itself. Sometimes the tour cannot save a bad feature. + +--- + +## "Tours are clear; adoption is good; users still file support tickets." + +The diagnosis. Tours covered the feature but not the edge cases. Documentation is needed for depth. + +The cure. Tours plus docs. Tours teach the common case; docs cover edge cases. + +--- + +## "Power users say tours feel patronizing." + +The diagnosis. Copy tone wrong; or tours fire on features power users have mastered. + +The cure. Match copy to brand voice (treat users as adults). Add power-user differentiation. + +--- + +## "Tour platform broke after last platform update." + +The diagnosis. Tour platform changes (Userpilot/Pendo/Appcues SDK updates) can break existing tours. + +The cure. Test after platform updates. Have a rollback plan. + +--- + +## The pattern across failures + +Most tour failures fall into one of three patterns. + +Pattern 1: The tour does not surface at the right moment. Tooltip-spam, one-and-done, over-trigger, under-trigger. The fix is trigger logic. + +Pattern 2: The tour does not match the audience or device. No power-user differentiation, mobile-broken, patronizing. The fix is matching to user state. + +Pattern 3: The tour decays. Stale references, broken triggers, deprecated features still tour-covered. The fix is maintenance. + +The metric pattern: tour failures often look fine on completion alone. The signal is in feature adoption, support ticket reduction, user retention. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (trigger, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md b/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md new file mode 100644 index 0000000..fd7a8d5 --- /dev/null +++ b/skills/interactive-product-tour/references/completion-tracking-and-re-trigger.md @@ -0,0 +1,203 @@ +# Completion tracking and re-trigger + +Per-user state, re-trigger logic, the over-trigger and under-trigger traps. + +Knowing what each user has seen, deciding when to show again. Done well, tours feel ambient; done poorly, tours either re-show endlessly or fail to re-surface when needed. + +--- + +## The state-aware principle + +The tour system should know what each user has seen, completed, dismissed, and ignored. Decisions about whether to show, re-show, or skip a tour should be based on this state. + +The win. A user who completed the advanced filtering tour does not see it again. A user who skipped it might see it again at a moment of more relevance. A user who dismissed all tours sees nothing. + +The fail. Users see the same tour every time they log in. Users who dismissed tours globally still get them. Users who would benefit from a re-shown tour at the right moment never see it again. + +The discipline. Track state per user per tour; use state to inform re-trigger logic. + +--- + +## Per-user state tracking + +What to track. + +Per tour, per user. + +- Has the user seen this tour? +- Did they complete it? +- Did they dismiss it without completing? +- When did they last interact with it? +- Did they take the suggested action after the tour? + +Globally per user. + +- Are tours globally enabled or disabled? +- What is their tenure on the product? +- What user state attributes apply (plan, role, segment)? + +Aggregate. + +- Tour completion rate. +- Tour dismissal rate. +- Action-taken-after-tour rate. + +The data informs both individual and system decisions. + +--- + +## Re-trigger logic + +When to re-show. + +Completed tours. + +- Default: do not re-show. The user got what they needed. +- Exception: re-show if the feature changed materially. The tour is no longer the same tour. + +Dismissed tours. + +- Respect the dismissal. +- If the feature becomes relevant again much later (60+ days, significant feature change), consider gentle re-surfacing with respect. + +Skipped tours (saw but did not complete). + +- Re-trigger at moments of more relevance. The user did not commit; help may land better contextually. +- After 2-3 skip events, treat like dismissed; respect the pattern. + +Ignored tours (saw but did not interact). + +- Treat similarly to skipped. +- Re-trigger at moments of higher friction. + +--- + +## The over-trigger trap + +Showing the same tour to users who have completed it. + +The pattern. No completion tracking; tours fire on every page load. + +The signal. Users complain about repeat tours; users disable tours globally; trust drops. + +The cost. The tour system loses credibility. Users who would have benefited from new tours dismiss them along with the over-triggered repeats. + +The cure. Track completion. Tours that have been completed do not re-fire (with rare exceptions for material feature changes). + +--- + +## The under-trigger trap + +Tours never re-surfacing when the user hits the same friction again. + +The pattern. First-login tours that show once and never come back. + +The signal. Users hit the same feature later; have forgotten the tour; ask support; the help failed at the moment of need. + +The cost. The tour system was decorative; the help did not compound adoption. + +The cure. Re-trigger logic at moments of need. Even completed tours can re-surface in abbreviated form when the user hits the relevant feature months later. + +--- + +## Re-trigger conditions + +Specific conditions that warrant re-triggering. + +Material feature change. The feature the tour covers has changed enough that the tour content is materially different. Re-show with "this feature has changed; here is what is new." + +Long absence. User returned after 60+ days; subset of tours can re-surface as re-orientation. + +Plan change. User upgraded plan; tours for previously-locked features become relevant. + +Role change. User's role changed (e.g., promoted to admin); admin-relevant tours become applicable. + +Time-based decay. Some tours benefit from periodic refreshers (rare; use carefully). + +The discipline. Each re-trigger condition should be deliberate, not default. + +--- + +## Frequency limits + +Even thoughtful re-triggers can over-fire. + +Per-tour frequency. + +- Default: never re-show after completion. +- Re-trigger conditions: maximum once per condition met. + +Per-session frequency. + +- Maximum tours per session (cumulative across all tours): often 1-3. +- Beyond that, defer additional tours to next session. + +Per-week frequency. + +- Some users encounter many features in a week; the system should not fire 20 tours. +- Cap weekly tour exposure to maintain attention. + +The discipline. Audit cumulative tour exposure per session and per week. Individual tour decisions are not enough. + +--- + +## Dismiss vs disable distinction + +Two different signals. + +Dismiss. User closed a specific tour. Tells the system "this tour is not for me right now." + +Disable. User turned off all tours via settings. Tells the system "I do not want any tours." + +Treatment. + +- Dismiss: respect for that tour; consider re-trigger at moments of higher relevance. +- Disable: respect globally; do not show any tours. + +The disable-respect failure. Some tour systems override the global disable for "important" tours. This breaks user trust. Disable should mean disable (compliance triggers excepted, with disclosure). + +--- + +## Tour analytics for completion + +Track what each tour produces. + +Per-tour metrics. + +- Trigger rate (how often does this tour fire?). +- Completion rate (of users who saw it, how many completed?). +- Dismissal rate (how many dismissed without completing?). +- Action-taken rate (how many took the suggested action after?). +- Adoption lift (do users who saw the tour adopt the feature at higher rates than those who did not?). + +The metrics inform whether the tour is earning its place. + +The adoption-lift question. If users who saw the tour adopt the feature at the same rate as users who did not, the tour is not adding value. Either redesign or retire. + +--- + +## Common completion-tracking failures + +No tracking. Tours fire repeatedly; users complain. + +Tracking exists but ignored. State stored but trigger logic does not use it; over-trigger persists. + +Stale state. User dismissed tour 6 months ago; product changed; tour does not re-show despite being newly relevant. + +Cross-device gaps. State tracked per device; user switches device and re-encounters every tour. + +Disable not respected. Global disable ignored for "important" tours; user trust collapses. + +No adoption-lift measurement. Tours track completion but not whether they produced adoption; weak tours persist. + +Re-trigger overzealous. Re-trigger conditions fire too liberally; users see tours they completed re-appear without justification. + +--- + +## Methodology-level choices that stay in the public skill + +The state-aware principle. Per-user state tracking. Re-trigger logic. The over-trigger and under-trigger traps. Re-trigger conditions. Frequency limits. Dismiss vs disable distinction. Tour analytics. Common failures. + +## Implementation choices that stay internal + +Specific tracking implementations. Specific re-trigger logic per tour. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/skills/interactive-product-tour/references/contextual-placement-patterns.md b/skills/interactive-product-tour/references/contextual-placement-patterns.md new file mode 100644 index 0000000..9887927 --- /dev/null +++ b/skills/interactive-product-tour/references/contextual-placement-patterns.md @@ -0,0 +1,245 @@ +# Contextual placement patterns + +Tooltip, spotlight, sidebar, inline. Placement and visual design. + +The placement decides whether help feels ambient or imposed. Done well, help is findable when wanted, ignorable when not. Done poorly, help blocks the user or disappears before they read it. + +--- + +## The non-imposition principle + +Help should be findable when wanted, ignorable when not. Help that demands the user's full attention is help that costs trust. + +The win. A tooltip appears next to a feature, visible but not blocking. The user reads if interested, dismisses or ignores if not. The interaction is brief and respectful. + +The fail. A modal overlay blocks the entire screen, demanding the user click to dismiss before continuing. The user loses momentum; resents the interruption. + +The discipline. Match placement intensity to help importance. Most help should be lightweight. + +--- + +## Pattern A: Tooltip on hover + +Help appears next to the element on hover. + +How it works. + +- User hovers over the element. +- Tooltip appears next to it. +- Tooltip dismisses when hover ends. + +Strengths. + +- Lightweight. +- Familiar pattern. +- Non-intrusive. + +Weaknesses. + +- Mouse-only by default; keyboard users may miss. +- Limited content (cannot fit much in a tooltip). +- Dismisses too easily for content the user needs to read. + +When to use. Brief hints, definitions, quick clarifications. Not for multi-step guidance. + +--- + +## Pattern B: Spotlight overlay + +Element highlighted; help appears alongside. + +How it works. + +- The relevant element is highlighted (often via dimmed surrounding area). +- A help card appears nearby explaining the element. +- User clicks "Got it" or similar to dismiss. + +Strengths. + +- More prominent; harder to miss. +- Can fit more content than tooltip. +- Good for feature-specific tours. + +Weaknesses. + +- More disruptive. +- Dimming the page can frustrate users who wanted to do something else. + +When to use. Feature-specific tours, the kind of help that warrants the user's full attention briefly. + +--- + +## Pattern C: Sidebar + +Help appears in a side panel. + +How it works. + +- Help opens in a panel (often right side of screen). +- User can read while the main content remains accessible. +- Panel persists until dismissed. + +Strengths. + +- Persistent reference; user can refer back. +- Does not block main content. +- Can fit substantial content. + +Weaknesses. + +- Takes screen space. +- May not work on mobile. + +When to use. When the help is reference material the user may want to consult while working. Multi-step guides where the user is doing the steps in the main content. + +--- + +## Pattern D: Inline + +Help appears in the page flow. + +How it works. + +- Help is embedded directly in the page content. +- Often appears as a banner, inline hint, or contextual section. +- User scrolls past or interacts with it. + +Strengths. + +- Non-disruptive. +- Always findable (does not appear and disappear). +- Works well on mobile. + +Weaknesses. + +- Can be missed entirely. +- Adds page length. + +When to use. Empty states, contextual hints that should always be visible, supplementary information that some users want. + +--- + +## Pattern E: Modal overlay + +Help blocks the screen until dismissed. + +How it works. + +- A full-screen or large modal appears. +- User must dismiss to continue. + +Strengths. + +- Highest visibility. +- Forces attention on critical messages. + +Weaknesses. + +- Most disruptive. +- Easily abused; produces annoyance. +- Should be reserved for critical messages. + +When to use. Compliance-critical messages, terms updates, data-loss warnings. Almost never for routine help. + +--- + +## Placement choice by content type + +What pattern fits what content. + +Brief hints (1 sentence): tooltip on hover. + +Feature explanations (2-3 sentences plus example): spotlight overlay. + +Multi-step guides (3-5 steps): spotlight overlay sequence or sidebar. + +Reference material (multiple paragraphs): sidebar. + +Empty states and contextual hints: inline. + +Compliance / critical messages: modal overlay. + +The match between content and placement is part of the design discipline. + +--- + +## Visual design discipline + +How help looks. + +Visual weight. + +- Tooltips: light, almost invisible until needed. +- Spotlights: medium; visible but not aggressive. +- Modals: heavy; demand attention. + +Brand consistency. + +- Help styling matches the product's design system. +- Tone matches brand voice. +- Colors should not feel "this is a tour"; they should feel like part of the product. + +Iconography. + +- Help often uses small icons (info, lightbulb) to signal "this is help." +- Icons should be consistent across help surfaces. + +--- + +## Animation discipline + +How help appears and disappears. + +Subtle animation. Fade in, slight slide. Reinforces transition without distracting. + +Aggressive animation. Bounce, attention-grabbing motion. Useful sparingly; abused, becomes annoyance. + +No animation. Instant appear/disappear. Snappy; some users prefer it. + +Prefers-reduced-motion. Respect user system preferences. No bouncing for users who configured reduced motion. + +--- + +## Mobile placement considerations + +Mobile changes everything. + +Tooltips. Hover does not exist on mobile; tooltips need touch alternative. Often replaced with tap-to-show. + +Spotlights. Spotlight overlays need to fit mobile screens. Smaller content; fewer steps. + +Sidebars. Often impossible on mobile; replaced with full-screen modals or omitted. + +Inline. Works well on mobile. Usually the safest mobile-first pattern. + +Modal overlays. Take over the screen on mobile; even more disruptive than on desktop. + +The mobile discipline. Test help on actual devices. Mobile help should be lighter and more inline-oriented. + +--- + +## Common placement failures + +Wrong pattern for content. Modal for a brief hint; tooltip for a multi-step guide. + +Visual weight wrong. Aggressive animation for routine help; invisible animation for critical messages. + +Mobile broken. Tooltips that do not work on touch; sidebars that take over the mobile screen. + +Brand-inconsistent. Help styled differently from the rest of the product; feels bolted on. + +Animation distracting. Bouncing tooltips that draw the eye constantly. + +No reduced-motion respect. Animations fire regardless of system preferences. + +Help blocks the action it is teaching. Spotlight overlays the very element the user needs to click. + +--- + +## Methodology-level choices that stay in the public skill + +The non-imposition principle. Patterns A through E. Placement choice by content type. Visual design discipline. Animation discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific placement designs for specific tours. Specific tooling. Specific brand styles. The team's mobile testing benchmarks. These vary by team and product. diff --git a/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md b/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md new file mode 100644 index 0000000..ea74d3c --- /dev/null +++ b/skills/interactive-product-tour/references/dismissal-and-non-intrusion-patterns.md @@ -0,0 +1,229 @@ +# Dismissal and non-intrusion patterns + +Dismissal mechanics. The non-intrusion principle. + +How tours close, how they respect the user's path, how they avoid becoming friction. The discipline that makes tours feel ambient rather than imposed. + +--- + +## The non-intrusion principle + +Help should be findable when wanted, ignorable when not. Tours that demand the user's full attention earn user resentment quickly. + +The win. A tooltip appears next to a feature. The user reads, dismisses, moves on. Two seconds total. The interaction was brief. + +The fail. A modal blocks the screen. The user has to read or dismiss before continuing. The interruption costs momentum and trust. + +The discipline. Match intensity to importance. Most tours should be light. + +--- + +## Dismissal patterns + +How tours close. + +Pattern A: Click X. + +How it works. A standard close button (often X or "Close") dismisses the tour. + +When to use. Default. Always available; users always know how to dismiss. + +Pattern B: Click outside. + +How it works. Tour dismisses if the user clicks anywhere outside the help element. + +When to use. For non-modal tooltips; lightweight help. + +Pattern C: Auto-dismiss. + +How it works. Tour fades after a few seconds of no interaction. + +When to use. Sparingly. Risky because users may not have read it. Best for very brief notifications. + +Pattern D: Persistent until acted on. + +How it works. Tour stays until the user takes the suggested action. + +When to use. For guided flows where the user is meant to perform the action. Discouraged for routine help (intrusive). + +Pattern E: Dismiss-and-don't-show-again. + +How it works. Dismissing offers an explicit "don't show me this again" option. + +When to use. For tours users may want to never see again (low-priority recurring tips). + +--- + +## Dismiss prominence + +How visible the dismiss is. + +Equal prominence. Dismiss and primary action have similar visual weight. + +Primary-prominent. Primary action ("Got it" or "Try it") is bold; dismiss is secondary. + +Hidden dismiss. Dismiss requires clicking outside or finding a small X. Discouraged; users feel trapped. + +The discipline. Dismiss should be findable in under 2 seconds without searching. + +--- + +## Click-outside dismissal + +When the user clicks elsewhere, what happens. + +Pattern: Dismiss fully. Tour closes; user continues with what they were doing. + +Pattern: Pause and resume. Tour pauses; if the user comes back, it resumes. Rarely the right choice; introduces unpredictability. + +Pattern: Block click. Tour stays; click outside is captured but does not pass through. Most intrusive; reserved for compliance. + +The discipline. Click-outside should usually dismiss. Users want to continue; let them. + +--- + +## Auto-dismiss design + +When help fades automatically. + +Time-based. Help disappears after N seconds. + +- 3-5 seconds: too short for anything but a single sentence. +- 8-12 seconds: reasonable for short help. +- 15+ seconds: probably too long; users have moved on. + +Action-based. Help disappears when the user takes the suggested action. + +- Useful for guided steps. +- Risk: user does something else; help disappears confusingly. + +Hover-based. Help disappears when hover ends. + +- Tooltip default. +- Brief by nature. + +The auto-dismiss risk. Users who needed the help may have been reading slowly; auto-dismiss takes the help away before they finish. + +The cure. Either give enough time, or let users explicitly dismiss. + +--- + +## Frequency caps for non-intrusion + +How many tours can fire in a session. + +Per-session caps. + +- Maximum tours per session: 1-3 typical. +- Beyond that, additional tours defer to next session. + +Per-page caps. + +- Maximum tours per page load: usually 1. +- Multiple tooltips on a page can stack; visual noise climbs. + +Per-day caps. + +- For users who use the product all day, daily caps prevent fatigue. + +The discipline. Cumulative exposure matters as much as individual tour quality. + +--- + +## Spacing and animation + +How tours appear and disappear. + +Subtle entry. Fade in; slight slide. Reinforces transition without distracting. + +Aggressive entry. Bounce, pulse, shake. Gets attention; abused, becomes annoyance. + +Subtle exit. Fade out; quick. + +The animation discipline. Subtle entries and exits. Save aggressive animation for rare attention-needed moments. + +--- + +## Spatial respect + +Where the help appears matters. + +Avoid blocking the action. Help should not cover the element it is teaching. + +Avoid blocking critical content. Help should not obscure the user's primary work area. + +Avoid covering navigation. Help that hides nav prevents the user from leaving. + +Allow scroll. If the user needs to scroll while help is visible, scroll should still work. + +--- + +## Help dismissal preserves user state + +When the user dismisses, what is preserved. + +Form data: preserved. Dismissing help should not reset form inputs. + +Page state: preserved. Dismissing help should not navigate away. + +User progress: preserved. Dismissing help should not undo work. + +The state-loss failure. Help dismissal that resets the page or loses inputs costs trust catastrophically. + +--- + +## Power-user dismissal patterns + +Power users want to dismiss faster. + +Keyboard dismissal. ESC closes help. Power users use keyboard. + +Click-anywhere-to-dismiss. Allows fast dismissal without targeting the X. + +Settings to disable globally. Allows opting out of all tours. + +The discipline. Power users should be able to dismiss in under a second. + +--- + +## New-user dismissal patterns + +New users may need more time. + +Persistent tooltips for guided flows. Help stays visible during the flow it is teaching. + +Linked help. Dismissing help leaves a way to find it again ("Need help? Check our guides"). + +Contextual reminders. Help re-surfaces if the user struggles with the same area later. + +The discipline. New users should not lose access to help permanently from a single dismissal. + +--- + +## Common dismissal failures + +Dismiss too prominent. User dismisses before reading; misses the help. + +Dismiss hidden. User cannot find the dismiss; feels trapped. + +Auto-dismiss too short. Help disappears before reading; user does not know what was there. + +Dismiss does not respect. Tour reappears after dismiss. + +Dismiss loses state. Form inputs reset; user loses work. + +No keyboard dismiss. Power users cannot dismiss quickly. + +Modal blocks until dismissed. User cannot continue without engaging. + +Help blocks the action. Spotlight covers the very element being taught. + +--- + +## Methodology-level choices that stay in the public skill + +The non-intrusion principle. Patterns A through E for dismissal. Dismiss prominence. Click-outside dismissal. Auto-dismiss design. Frequency caps. Spacing and animation. Spatial respect. State preservation on dismiss. Power-user vs new-user dismissal patterns. Common failures. + +## Implementation choices that stay internal + +Specific dismissal designs for specific tours. Specific animation timings. Specific frequency baselines. The team's tooling. These vary by team and product. diff --git a/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md b/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md new file mode 100644 index 0000000..646a365 --- /dev/null +++ b/skills/interactive-product-tour/references/power-user-vs-new-user-patterns.md @@ -0,0 +1,204 @@ +# Power-user vs new-user patterns + +Differentiation signals and patterns. The over-helping and under-helping traps. + +Different users need different help. The discipline is to know which user is which and tailor the help system to their state. + +--- + +## The state-respect principle + +Power users do not want tours on features they already use. New users need tours on features they are encountering for the first time. The help system should know the difference and respect both. + +The win. A power user encounters a newly-shipped feature; sees a brief tour. A new user encounters a feature for the first time; sees the same tour. A power user encounters a feature they have used 50 times; sees nothing. + +The fail. Both users see the same tour every time. Power users disable tours; new users miss critical help when they need it most. + +The discipline. Tour visibility should depend on user state, not user category alone. + +--- + +## Differentiation signals + +What lets the system know which user is which. + +Feature usage history. Has the user used this feature before? + +- Most reliable signal. +- Tracks per-feature, per-user state. +- Updates in real time as the user uses the feature. + +Tenure on the product. How long has the user been a customer? + +- Approximate signal; new accounts vs old accounts. +- Useful when feature usage data is missing. + +Engagement frequency. Daily active vs returning monthly. + +- Active users tend to know the product better. +- Returning users may need re-orientation. + +Plan or role. Free vs paid; admin vs end-user; user vs viewer. + +- Different roles use different feature sets. +- Plan changes can unlock new features. + +Self-reported skill level. Rare; usually inferred. + +- Some products ask during signup. +- Useful but unreliable; people self-assess inaccurately. + +The discipline. Combine signals. Single signals are noisy. + +--- + +## Differentiation patterns + +How to surface different help. + +Pattern A: Feature-usage gating. + +How it works. Each tour has a "show only if user has not used this feature" condition. Power users with usage history skip; new users see. + +When to use. Default for feature-specific tours. Most reliable. + +Pattern B: Tenure-based filtering. + +How it works. New users (under 7 days) see all relevant tours. Established users (over 30 days) see tours only for newly-shipped features. + +When to use. When feature usage data is incomplete or unavailable. + +Pattern C: Engagement-based modulation. + +How it works. Daily active users see fewer tours; returning monthly users may see re-orientation help. + +When to use. When engagement frequency predicts product knowledge. + +Pattern D: Role-based differentiation. + +How it works. Admins see admin-specific tours; end-users see end-user tours. + +When to use. When the product has materially different surfaces for different roles. + +Pattern E: Newly-shipped feature highlighting. + +How it works. New feature ships; tour fires for ALL users (power users and new users) because everyone is new to this feature. + +When to use. Feature launches. Power users benefit from the tour just as much as new users for this case. + +--- + +## The over-helping trap + +Helping power users with features they have mastered. + +The pattern. Tours fire regardless of user state; power users see tours they do not need. + +The signal. Power user complaints; tour disable rate climbs; trust degrades. + +The cost. Power users disable tours globally; the system loses access to them for genuinely new features. + +The cure. Add feature-usage gating. Respect tenure and engagement signals. + +--- + +## The under-helping trap + +Treating all users as power users. + +The pattern. Tours fire only on first-login or never. New users miss help when they need it. + +The signal. Feature adoption stays low among new users; support tickets persist for tour-covered features. + +The cost. New users churn or stay underactivated. + +The cure. Tours fire when users encounter features for the first time, regardless of how long they have been on the product. + +--- + +## Returning-user re-orientation + +Long-absent users may need re-orientation. + +The pattern. User has not logged in for 60+ days. On return, abbreviated re-orientation help surfaces. + +Design. + +- Brief (2-3 steps max). +- Highlights what changed in the user's absence. +- Easy to dismiss for users who do not need it. + +The over-helping risk. Users returning from a 1-week absence do not need re-orientation. Set the absence threshold appropriately. + +--- + +## Newly-shipped feature handling + +When a feature ships, the help system has new content. + +The pattern. A new tour ships with the feature. Trigger fires for all users (power and new alike) because everyone encounters this feature for the first time. + +Discipline. + +- Tag the tour as "new feature." +- Fire on first encounter regardless of user tenure. +- After most users have seen it (e.g., 80 percent of monthly active users), the tour can transition to standard new-user-only logic. + +Power-user respect. Even new feature tours should be brief. Power users will read what they need; do not slow them with five-step explanations. + +--- + +## Plan or role change handling + +User state can change. + +Plan upgrade. User moves from free to paid; new features become available; relevant tours become applicable. + +Role change. User promoted to admin; admin tours become applicable. + +The discipline. Re-evaluate tour eligibility on state change. Plan upgrade triggers a "you have new features available" re-orientation. + +--- + +## Inferred vs asked differentiation + +When to ask the user vs when to infer. + +Ask sparingly. Asking adds friction; users tire of being categorized. + +Infer when possible. Behavioral signals usually outperform self-report. + +When to ask. + +- Onboarding (use case, role). +- Major plan changes that affect tour eligibility. + +When not to ask. + +- After onboarding; let behavior speak. + +--- + +## Common power-user vs new-user failures + +No differentiation. All users see all tours; over-helping power users. + +Differentiation only by tenure. New accounts vs old; misses that some new accounts have power users (came from competitor) and some old accounts have casual users. + +No re-orientation for returning users. Users who left 90 days ago re-encounter as if first-time; they remember enough to skip re-orientation; but the help fails when they hit a changed feature. + +Newly-shipped features not flagged. Tour does not surface for power users who have used adjacent features; they miss the new capability. + +Plan upgrade not triggering re-evaluation. User upgrades; new features available; tours for those features do not surface. + +Inferring poorly. Inference logic mistakes user state; help is wrong for the user. + +--- + +## Methodology-level choices that stay in the public skill + +The state-respect principle. Differentiation signals (5 signals). Patterns A through E. The over-helping and under-helping traps. Returning-user re-orientation. Newly-shipped feature handling. Plan or role change handling. Inferred vs asked differentiation. Common failures. + +## Implementation choices that stay internal + +Specific differentiation rules for specific products. Specific signals weighted by team. The team's plan and role mapping. These vary by team and product. diff --git a/skills/interactive-product-tour/references/tour-anti-patterns.md b/skills/interactive-product-tour/references/tour-anti-patterns.md new file mode 100644 index 0000000..752725d --- /dev/null +++ b/skills/interactive-product-tour/references/tour-anti-patterns.md @@ -0,0 +1,224 @@ +# Tour anti-patterns + +The patterns that look like tours but degrade the product. Easy to ship; the cost shows up in feature adoption, user trust, and brand reputation. + +--- + +## The tooltip-spam tour + +The pattern. Every button, link, and feature has a "click for tour" hint or pulsing dot. + +The signal. Users develop blindness to the dots; click rates collapse; tour completion rates near zero. + +The cost. The visual clutter degrades the product; users learn to ignore all tooltips, including useful ones. + +The cure. Audit triggers. Reserve hints for moments of genuine friction. Detail in `references/trigger-logic-patterns.md`. + +--- + +## The one-and-done tour + +The pattern. A single first-login tour. Never re-surfaces. + +The signal. Users skip or skim; help unavailable at moments of later need. + +The cost. Feature adoption suffers; support tickets persist for tour-covered features. + +The cure. Library of micro-tours triggered contextually. Detail in `references/tour-architecture-patterns.md`. + +--- + +## The mega-tour + +The pattern. A single tour with 25 steps covering the whole product. + +The signal. High abandonment mid-tour; high skip rate; activation does not lift. + +The cost. Tutorial-overload pattern applied to tours. Users abandon; help fails. + +The cure. Break into micro-tours, each tied to a specific feature. + +--- + +## The over-trigger tour + +The pattern. Tour fires on every page load; no completion tracking. + +The signal. Repeat exposure; user complaints; tours globally disabled. + +The cost. Tour system loses credibility. + +The cure. Per-user state tracking. Completed tours do not re-fire. + +--- + +## The under-trigger tour + +The pattern. Tour fires only on first-login. Users hit the same friction later; help does not return. + +The signal. Specific features show low adoption among long-tenured users; help failed at the moment of need. + +The cost. The tour system was decorative for everyone after their first session. + +The cure. Re-trigger logic at moments of relevance, even for tours seen long ago. + +--- + +## The dismissive-of-disable tour + +The pattern. User disabled all tours globally; system fires tours anyway because they are deemed important. + +The signal. User trust collapses; explicit complaints. + +The cost. The tour system overrode the user's clear preference; trust does not recover quickly. + +The cure. Respect the global disable. Use compliance-only triggers for legally required messages, with clear disclosure. + +--- + +## The blocks-the-action tour + +The pattern. Spotlight overlay covers the element it is teaching; user cannot click through. + +The signal. User confusion; users dismiss and abandon the action they were about to take. + +The cost. The tour failed at its job; the user did not learn the feature because the tour blocked the feature. + +The cure. Spotlight placement that highlights without blocking. The user should be able to take the action while the help is visible. + +--- + +## The auto-dismiss-too-fast tour + +The pattern. Help fades after 3 seconds. + +The signal. Users complain about help disappearing before they read it. + +The cost. The help is technically present but functionally absent. + +The cure. Either longer auto-dismiss (8-12 seconds), or let users dismiss explicitly. + +--- + +## The validation-strict tour + +The pattern. Tour requires the user to take a specific action to proceed; the user takes a different valid path. + +The signal. Tour gets stuck; user abandons. + +The cost. Forced linearity penalizes users who explore. + +The cure. Tour either accepts multiple valid paths or dismisses if the user explores elsewhere. + +--- + +## The brand-inconsistent tour + +The pattern. Tour styling looks different from the rest of the product. Generic platform styling rather than brand-aligned. + +The signal. Users perceive the tour as bolted on; brand consistency suffers. + +The cost. The product feels less polished; tours feel like a separate system. + +The cure. Custom-styled tours matching the product's design system. + +--- + +## The mobile-broken tour + +The pattern. Tour designed for desktop; breaks on mobile. + +The signal. Mobile completion rates much lower; mobile-specific complaints. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. Detail in `references/contextual-placement-patterns.md` (mobile section). + +--- + +## The unmaintained tour + +The pattern. Tour built once; product evolved; tour content references deprecated features. + +The signal. Users hit broken steps; references that no longer apply. + +The cost. Trust degrades; users ignore tours expecting them to be wrong. + +The cure. Quarterly maintenance. Product changes trigger tour updates as part of the change. + +--- + +## The orphan-tour + +The pattern. Tour exists for a feature that was deprecated 6 months ago; nobody removed it. + +The signal. Tour fires; clicks lead to 404 or to a removed UI; users confused. + +The cost. The tour points to nothing; user trust degrades. + +The cure. Tour deprecation alongside feature deprecation. + +--- + +## The fake-engagement tour + +The pattern. Tour optimizes for click-through rate by making the action button huge and the dismiss tiny. + +The signal. Click-through rate looks high; downstream feature adoption does not match. + +The cost. Surface metrics look fine; real adoption does not improve. + +The cure. Track adoption as the metric; design honestly. Click-through alone is not enough. + +--- + +## The interrupting tour + +The pattern. Tour fires while the user is mid-task; takes over the screen. + +The signal. User abandonment spikes at the interruption; users complain. + +The cost. The tour cost the user a task completion. + +The cure. Tour triggers should respect ongoing tasks. Detect mid-task state; defer. + +--- + +## The patronizing-copy tour + +The pattern. Tour copy talks down to users. "Welcome! Let me show you around. Here's how to do something simple." + +The signal. Power users dismiss; new users feel patronized. + +The cost. Tone hurts trust. + +The cure. Match copy to brand voice. Treat users as adults. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active tour, looking for these anti-patterns. + +Audit questions per tour. + +- Is the tour triggered relevantly (anti-pattern check: tooltip-spam, over-trigger, under-trigger)? +- Does the tour respect dismissal (anti-pattern check: dismissive-of-disable)? +- Does the tour block the action it teaches (anti-pattern check: blocks-the-action)? +- Is auto-dismiss timed appropriately (anti-pattern check: auto-dismiss-too-fast)? +- Does the tour match the brand's design (anti-pattern check: brand-inconsistent)? +- Does the tour work on mobile (anti-pattern check: mobile-broken)? +- Is the tour current (anti-pattern check: unmaintained, orphan)? +- Is adoption tracked (anti-pattern check: fake-engagement)? + +The retire decision. Anti-pattern tours often warrant retirement or redesign. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/interactive-product-tour/references/tour-architecture-patterns.md b/skills/interactive-product-tour/references/tour-architecture-patterns.md new file mode 100644 index 0000000..9048eaf --- /dev/null +++ b/skills/interactive-product-tour/references/tour-architecture-patterns.md @@ -0,0 +1,225 @@ +# Tour architecture patterns + +Single tour vs branched vs library of micro-tours. The architecture that fits how users actually explore. + +The architecture is how help is organized at the system level. Bad architecture produces canned tours that nobody finishes; good architecture matches how users actually explore. + +--- + +## The exploration-fit principle + +The architecture should match how users actually move through the product. Linear architecture fits linear products; library architecture fits exploration. + +The win. A library of focused micro-tours, each tied to a specific feature, triggered contextually as users encounter features. Each tour is small (2-4 steps); each fires only at relevant moments. Users feel helped without feeling herded. + +The fail. A single linear tour covering 25 features in sequence. Users who care about feature 17 get nothing relevant in the first 16 steps; they skip everything; help fails. + +The discipline. Match architecture to exploration patterns; do not impose linearity on non-linear products. + +--- + +## Pattern A: Single tour + +One linear tour covering the product. + +How it works. + +- Tour starts at first-login or via a "Take the tour" prompt. +- Steps cover features in a defined order. +- User completes or skips entirely. + +Strengths. + +- Simple to design and maintain. +- Predictable for users. + +Weaknesses. + +- Linear; rarely fits how users explore. +- Can become tutorial-overload if comprehensive. +- One-and-done; rarely re-shown. + +When to use. Very simple products with linear flows. Rarely the right answer for production tour systems. + +--- + +## Pattern B: Branched tour + +Tour adapts based on user choices or path. + +How it works. + +- User selects role/use case at start. +- Subsequent steps adapt based on the selection. +- Different users effectively complete different tours. + +Strengths. + +- More relevant than single tour. +- Personalized. + +Weaknesses. + +- Complex to build and maintain. +- Hard to instrument cleanly. +- Still linear in execution. + +When to use. When the audience splits into 2-3 clear segments with different exploration paths. Use sparingly. + +--- + +## Pattern C: Library of micro-tours + +Dozens of small focused tours, each tied to a specific feature or workflow. Triggered contextually. + +How it works. + +- Many small tours (2-4 steps each). +- Each tour is tied to a specific feature, workflow, or moment. +- Trigger logic decides when each fires. +- Users see only the tours relevant to their current exploration. + +Strengths. + +- Matches how users actually explore. +- Each micro-tour is small enough to complete. +- Re-trigger logic can re-surface as features become relevant. +- Most flexible. + +Weaknesses. + +- Most maintenance. +- Trigger logic complexity. +- Requires per-tour completion tracking. + +When to use. Default for production tour systems. Most modern products benefit from this approach. + +--- + +## Pattern D: Hybrid + +Combining patterns. Often a brief opening tour plus a library of micro-tours for ongoing help. + +How it works. + +- First-login: brief 3-4 step orientation tour (single). +- Ongoing: library of micro-tours triggered contextually. + +Strengths. + +- Orientation for new users + ongoing help for everyone. +- Combines the simplicity of single tour for the moment of arrival with the flexibility of library for the ongoing relationship. + +Weaknesses. + +- Two systems to maintain. + +When to use. When new users genuinely benefit from an opening orientation AND ongoing contextual help is also valuable. + +--- + +## Architecture choice criteria + +Which pattern fits which product. + +Use single tour when: + +- Product is genuinely linear. +- Audience expects guided sequence. +- Maintenance capacity is limited. + +Use branched tour when: + +- Audience splits into 2-3 distinct segments. +- Each segment has a different linear path. + +Use library of micro-tours when: + +- Product has many features users explore non-linearly. +- Audience is segmented in many ways. +- Maintenance capacity supports many tours. + +Use hybrid when: + +- New-user orientation matters AND ongoing help also matters. + +The simplest architecture that fits the product is usually the best choice. + +--- + +## Micro-tour discipline + +Each micro-tour should be small. + +Size guideline. 2-4 steps per micro-tour. + +Why small. + +- Completable in under a minute. +- Easy to maintain. +- Targeted to a specific feature or moment. +- Less likely to be skipped. + +Anti-pattern. Micro-tours that grow into 8-10 steps lose their micro nature; they become single tours that happen to be triggered contextually. Re-scope. + +--- + +## Tour tagging and organization + +When you have a library, organize it. + +Tagging axes. + +- Feature (which feature the tour covers). +- Workflow (which user workflow the tour fits in). +- User type (new, power, returning). +- Plan (free, paid, enterprise). + +Why tagging matters. + +- Trigger logic can use tags to decide which tour fires. +- Maintenance can find tours by feature when the feature changes. +- Audit can identify orphan tours not tied to current features. + +--- + +## Tour deprecation + +When features change, tours need to retire or update. + +Retire when: + +- Feature was deprecated; tour points to nothing. +- Feature changed enough that tour content is wrong; redesign instead of patch. + +Update when: + +- Feature changed in details but tour structure still applies. + +The deprecation hygiene. Quarterly audit of tours against current product. Tours pointing to deprecated features get retired; tours that still apply but need refresh get updated. + +--- + +## Common architecture failures + +Single tour for non-linear product. Users skip; help fails. + +Branched tour with too many branches. Maintenance burden; quality degrades per branch. + +Library without tagging. Tours accumulate; nobody can find them; some are stale. + +Mega-tours. Micro-tours that grew to 10+ steps; lose their micro nature. + +Orphan tours. Tours pointing to features that no longer exist; not retired. + +Inconsistent micro-tour quality. Some tours polished, others slapdash; users notice. + +--- + +## Methodology-level choices that stay in the public skill + +The exploration-fit principle. Patterns A through D. Architecture choice criteria. Micro-tour discipline. Tour tagging and organization. Tour deprecation. Common failures. + +## Implementation choices that stay internal + +Specific architectures for specific products. Specific tooling for tour authoring and management. The team's tagging conventions. Specific quarterly audit calendars. These vary by team and product. diff --git a/skills/interactive-product-tour/references/tour-decision-criteria.md b/skills/interactive-product-tour/references/tour-decision-criteria.md new file mode 100644 index 0000000..5bdf154 --- /dev/null +++ b/skills/interactive-product-tour/references/tour-decision-criteria.md @@ -0,0 +1,154 @@ +# Tour decision criteria + +When tours earn the build vs when documentation suffices. + +A tour system is meaningful work. Trigger logic, tour architecture, contextual placement, completion tracking, ongoing maintenance. Tours earn this investment only when specific conditions are present. + +--- + +## When tours earn the build + +Five conditions that, when present, make tours a strong investment. + +The product has features users genuinely miss. Specific functionality buried in menus, advanced workflows requiring sequence, integrations users do not know exist. Without prompting, users do not find these features. + +The audience benefits from in-context guidance more than documentation. Tours teach in the place the user will use the feature; docs require context-switching. Some audiences prefer the immediacy of in-context help. + +The team can maintain tours. Tour content decays as the product evolves. Without maintenance commitment, tours point to deprecated UI; users hit broken steps. + +The success metric is defined. Feature adoption per tour-covered feature, time-to-value for specific capabilities, reduction in support tickets. Without the metric, evaluation is impossible. + +The product changes at a sustainable pace. Tours can keep up. Products that change weekly may have tour-maintenance burden exceeding tour value. + +When all five are present, tours are a strong investment. When two or fewer are present, documentation often serves better. + +--- + +## When tours do NOT earn the build + +Funnels where tours add complexity without value. + +The product's feature set is small enough that documentation suffices. A few tooltips on key features may be all that is needed. Building a full tour infrastructure is overkill. + +The audience prefers self-directed discovery. Some audiences resent in-product guidance. Developer tools, professional creative tools, specialist software often have audiences who want to explore on their own. + +The team cannot maintain tours. Stale tours are worse than no tours. Without commitment, tours decay into liability. + +The product changes too frequently. A product churning weekly may have tours that go stale within days of being shipped. The maintenance cost exceeds the tour benefit. + +The audience is small enough that direct outreach is more efficient. Onboarding calls, customer success engagement, and direct help may serve a small audience better than tour infrastructure. + +The honest assessment matters. Tours are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Documentation vs tours: the comparison + +Both teach features; they differ in delivery. + +Documentation strengths. + +- Stable; changes don't require tour updates. +- Searchable; users find what they need. +- Comprehensive; can cover edge cases. +- Accessible from outside the product (sharing, linking). + +Documentation weaknesses. + +- Requires context-switching from product to docs. +- Users may not know to consult docs. +- Static; cannot react to user state. + +Tour strengths. + +- In-context; help where the user will use the feature. +- Dynamic; can react to user state and behavior. +- Non-disruptive when designed well. + +Tour weaknesses. + +- Maintenance burden. +- Can become tooltip-spam if undisciplined. +- Less comprehensive than docs. + +The combined approach. Most production teams use both. Tours for the moments where in-context guidance matters; docs for depth and reference. + +--- + +## The opportunity-cost frame + +Tour systems are significant work. + +The build cost. Trigger logic infrastructure, tour authoring, instrumentation, integration with the product, design and copy. A meaningful tour system often takes 60-200 engineering hours plus design and copy per major tour. + +The maintenance cost. Quarterly review minimum; product changes trigger tour updates. 4-12 hours per active tour per quarter. + +The opportunity cost. What else could the team have built? Direct in-product improvements, better empty states, contextual prompts that do not require tour infrastructure. The tour system has to clear the bar of those alternatives. + +The decision frame. Tours earn investment when they produce more adoption lift than the alternatives. + +--- + +## Decision worked example + +A B2B SaaS analytics platform considering an in-product tour system. + +Conditions check. + +- Features users miss: yes. Advanced analysis modes, custom dashboard creation, integration setup all underused. +- In-context guidance benefits: yes. Users explore in-product; pulling them to docs breaks flow. +- Maintenance commitment: yes. Customer success team owns tours. +- Success metric defined: yes. Feature adoption per tour-covered feature within 30 days of first encounter. +- Product change pace: moderate. Major features ship monthly; minor changes weekly. Tour updates fit the cadence. + +Decision. Build the tour system. The conditions warrant it. + +Architecture. Library of micro-tours, each tied to a specific feature. Triggered contextually when users first encounter the feature. + +Maintenance commitment. CS team reviews quarterly; major product changes trigger tour updates as part of the change. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A developer-tool company considering in-product tours. + +Conditions check. + +- Features users miss: somewhat. Some advanced features underused, but the audience tends to find them through docs. +- In-context guidance benefits: weak. Developers strongly prefer docs and prefer not to be interrupted. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined. +- Product change pace: moderate. + +Decision. Do not build a full tour system. Invest in better docs, smarter empty states, and a few high-value contextual hints. The audience's preference for self-directed discovery argues against tour infrastructure. + +The decision was right-sized to the audience. + +--- + +## When to retire a tour system + +Tour systems can become wrong over time. + +Retire when: + +- Feature adoption (the tour's success metric) has declined consistently and refinements have not moved it. +- Users globally disable tours via settings. +- The product changes have outpaced maintenance; tours are stale. +- A redesigned product surface (better empty states, better contextual prompts) makes tours redundant. +- The team can no longer maintain tours. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant tours. The five conditions that argue against. Documentation vs tours comparison. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific tour decisions for specific products. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/interactive-product-tour/references/trigger-logic-patterns.md b/skills/interactive-product-tour/references/trigger-logic-patterns.md new file mode 100644 index 0000000..aa489aa --- /dev/null +++ b/skills/interactive-product-tour/references/trigger-logic-patterns.md @@ -0,0 +1,226 @@ +# Trigger logic patterns + +Event-based, time-based, state-based, combined triggers. The discipline that distinguishes useful triggers from noise. + +The trigger answers "when does this help surface and why." Decorative triggers (showing help when it is not needed) become tooltip-spam. Useful triggers surface help at moments of friction. + +--- + +## The relevance principle + +Trigger help when the user is at a moment of friction or genuine need. Do not trigger help when the user is moving through familiar territory. + +The win. A user clicks into a feature for the first time. The tour system recognizes this is the user's first encounter and surfaces a brief contextual hint. The user reads, takes the suggested action, moves on. + +The fail. Same user, same feature. The tour system has no first-encounter detection; it triggers on every page load. The user has dismissed the same tooltip 12 times; develops blindness to all tooltips. + +The discipline. Each trigger should answer "why this user, why now." + +--- + +## Pattern A: Event-based triggers + +Help appears in response to a user action. + +How it works. + +- The user performs an action (clicks a feature, enters a section, completes a flow). +- The trigger fires based on the event. +- Help appears contextually. + +Examples. + +- First click into a new section. +- Completed a flow for the first time. +- Hit a state where help would be useful (empty list, no data connected, no teammates invited). + +Strengths. + +- Most relevant; help responds to what the user just did. +- Naturally contextual. + +Weaknesses. + +- Requires per-event tracking. +- Can over-trigger if events are too granular. + +When to use. Default for most contextual help. Events drive the trigger. + +--- + +## Pattern B: Time-based triggers + +Help appears after time elapsed. + +How it works. + +- A timer starts when relevant condition is met. +- After a defined interval, help triggers. +- Time can be session time, time on page, time since last action, or time since last login. + +Examples. + +- User has been on a page for 60 seconds without acting (signals stuck). +- User returned after 30 days of absence (signals re-orientation needed). +- User has been a customer for 90 days (signals capacity for advanced features). + +Strengths. + +- Catches stuck users events alone might miss. +- Useful for re-engagement of long-absent users. + +Weaknesses. + +- Time alone is a noisy signal. +- "Stuck" might just be reading. +- Easy to misuse and produce annoyance. + +When to use. Sparingly. Time-based triggers should always combine with event or state signals. + +--- + +## Pattern C: State-based triggers + +Help appears based on user state. + +How it works. + +- The user has attributes (new vs power; small vs large account; specific role; specific plan). +- Trigger fires based on attribute match. + +Examples. + +- Power users see help only on newly-shipped features. +- Enterprise customers see different tour on workspace features than SMB. +- Users on free plan see different upgrade-related help than paid. + +Strengths. + +- Personalizes help to user segment. +- Avoids over-helping users who do not need it. + +Weaknesses. + +- Requires user-state infrastructure. +- State changes (plan upgrade, role change) need to update triggers. + +When to use. When help differs significantly by user segment. State modulates event triggers. + +--- + +## Pattern D: Combined triggers + +Most production tour systems combine event, time, and state. + +Example combined trigger. + +"Show tour for advanced filtering feature when: +- User clicks the filter icon for the first time (event). +- User has been on the platform more than 7 days (state, not too new). +- User is on a paid plan (state, feature is paid-only). +- User has not dismissed this specific tour before (state, respect prior dismissal)." + +The combination produces relevant triggers without false positives. + +The discipline. Trigger conditions accumulate. Each condition prevents over-triggering. + +--- + +## Trigger frequency limits + +Even relevant triggers can over-fire. + +Per-tour limits. + +- Once per user (most tours). +- Once per quarter (re-orientation tours). +- Once per session per page (low-priority hints). + +Per-session limits. + +- Cap total tour interruptions per session (e.g., max 2 tours per session). +- Cap total tooltip appearances per session. + +The cumulative-frequency problem. Each individual tour may be reasonable; the cumulative count across many tours can become noise. + +The discipline. Audit cumulative triggers per session, not just per tour. + +--- + +## Trigger disabling and respect + +Users may disable tours globally. + +The pattern. A settings option lets users disable all tours. + +The discipline. Respect the disable. No tour should override the global setting (compliance triggers may be exception). + +Re-engaging disabled users. + +- Do not auto-re-enable. +- Surface specific high-value features as one-time prompts that respect the disable. +- Trust that users who disabled know what they want. + +--- + +## Trigger logic and accessibility + +Triggers must work for users with assistive technology. + +Considerations. + +- Triggers should not assume mouse hover (keyboard users miss them). +- Triggers should not auto-fire to overwhelm screen readers. +- Triggers should respect prefers-reduced-motion. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Trigger logic testing + +Test triggers across user paths. + +Test cases. + +- New user encounters feature: trigger fires. +- Returning user encounters same feature: trigger does not re-fire (respects history). +- Power user encounters newly-shipped feature: trigger fires. +- User who dismissed a tour: dismissed tour does not re-fire. +- User who disabled tours globally: no tours fire. +- User on mobile vs desktop: triggers behave consistently. + +Production monitoring. + +- Track trigger fire rate per tour. +- Track tour completion rate per tour. +- Track unique users who saw each tour. +- Anomalies (sudden spike in triggers) often indicate logic issues. + +--- + +## Common trigger logic failures + +Over-triggering. Triggers fire on every page load; users develop blindness. + +Under-triggering. Triggers fire only on first-login; users miss help when they need it later. + +No state awareness. Power users see beginner tours; new users see tours for features they have not unlocked. + +No frequency limits. Each individual tour is fine; cumulative triggers per session are noise. + +Disabled users not respected. Tours fire despite global disable. + +Stale triggers. Triggers reference features deprecated 6 months ago. + +Untested edge cases. Specific user paths produce broken triggers; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through D (event, time, state, combined). Trigger frequency limits. Trigger disabling and respect. Accessibility considerations. Trigger testing. Common failures. + +## Implementation choices that stay internal + +Specific trigger configurations for specific tours. Specific tooling for trigger management. The team's testing protocols. Specific frequency baselines. These vary by team and product. diff --git a/skills/internationalization/SKILL.md b/skills/internationalization/SKILL.md new file mode 100644 index 0000000..01f91ab --- /dev/null +++ b/skills/internationalization/SKILL.md @@ -0,0 +1,278 @@ +--- +name: internationalization +description: "Plan and run a multi-language or multi-region site. Use this skill when adding new locales, choosing URL structure for languages (subfolders vs subdomains vs ccTLDs), implementing hreflang, planning translation workflow, handling currency and date formats, designing for RTL languages, or auditing a stalled internationalization rollout. Triggers on internationalization, i18n, localization, l10n, hreflang, multi-language, translation workflow, RTL, locale, ccTLD, subfolder vs subdomain, language switcher. Also triggers when international audiences underperform or translations are stale." +category: cross-cutting +catalog_summary: "Locale strategy, hreflang, translation workflow, RTL design" +display_order: 3 +--- + +# Internationalization + +Add languages and regions in a way that works for users, search engines, and the team maintaining the content. Stack-agnostic. + +--- + +## When to use + +- Adding the first non-English (or non-default) language +- Adding additional locales to an existing internationalized site +- Choosing URL structure for languages +- Implementing hreflang tags +- Designing translation workflow +- Handling currency, date, time, and number formats +- Designing or fixing layout for RTL languages +- Auditing an internationalization rollout that's underperforming + +## When NOT to use + +- Single-language site (use other skills) +- Domain strategy that's not language-driven (use `domain-strategy`) +- Content strategy independent of locale (use `content-strategy`) +- Marketing copy production (use `content-and-copy`) + +--- + +## Required inputs + +- The locales in scope (language + region, e.g., `en-US`, `de-DE`, `fr-CA`) +- Business reason per locale (priority, audience size) +- Existing site architecture +- Translation resources (in-house, agency, AI-assisted, community) +- Content volume and update frequency + +--- + +## The framework: 5 layers + +Internationalization touches everything. Five layers, each with their own decisions. + +### Layer 1: URL structure + +How locales are reflected in URLs. + +\| Pattern \| Example \| When \| +\|---\|---\|---\| +\| ccTLD \| example.de, example.fr \| Strong country focus, distinct legal entities, willing to maintain separate domains \| +\| Subdomain \| de.example.com, fr.example.com \| Logical separation, willing to host separately, common for large sites \| +\| Subfolder \| example.com/de/, example.com/fr/ \| SEO equity unified, simplest to manage, default for most \| +\| URL parameter \| example.com?lang=de \| Avoid; weak SEO signal \| + +For most sites: subfolder is the default. Subdomain or ccTLD only when there's a specific reason (legal, infrastructure, or brand). + +Within the chosen pattern, decide: +- Language only (`/de/`) or language plus region (`/de-de/`, `/de-at/`, `/de-ch/`)? +- Default locale: at the apex (`example.com`) or in a folder (`example.com/en/`)? + +The default-locale-at-apex pattern is common but causes hreflang complexity (the apex needs an `x-default` and the canonical for the default language). + +### Layer 2: Content structure + +How content is organized across locales. + +Pattern A: Mirror. Every page in every locale. The translation IS the page. Suitable for marketing sites with controlled content. + +Pattern B: Subset. Some content in all locales, some only in select locales. Common for product pages (only available products), blog (some posts translated), or regulatory differences. + +Pattern C: Local. Each locale has its own content largely independent of other locales. Common for media or community sites. + +Most marketing sites are A. Most large sites end up at B by necessity. C is for sites with strong regional editorial. + +The pattern affects: +- How content models are designed (does each piece have parent/translation relationships?) +- How translation is managed (workflow assumes the structure) +- How the team coordinates + +### Layer 3: hreflang and canonicals + +Telling search engines what's translated vs distinct. + +hreflang specifies the language and optional region for each version. + +```html +<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/page"> +<link rel="alternate" hreflang="en-GB" href="https://example.com/en-gb/page"> +<link rel="alternate" hreflang="de-DE" href="https://example.com/de-de/page"> +<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/page"> +``` + +Rules: +- Every page lists every translated equivalent (including itself) +- Pages must reciprocate (page A says page B is its German version; page B says page A is its English version) +- `x-default` is the fallback for users in unspecified regions +- Each page has its own canonical pointing to itself (not to the default language) + +hreflang can be in the HTML head, in HTTP headers, or in the XML sitemap. Sitemap is best for large sites; HTML head is fine for small. + +Canonicals: +- Self-referential per page +- Don't canonical the German page to the English page (search engines won't index the German page) + +### Layer 4: Translation workflow + +How content gets translated, kept fresh, and quality-controlled. + +Sources of translation: +- In-house translators (full-time staff) +- Translation agency (paid per word, professional) +- Community contributors (volunteer, variable quality, free) +- AI-assisted plus human review (cheap, fast, growing in quality) +- AI only (acceptable for some content, not for brand-critical) + +Workflow stages: + +1. Source content authored in the source language +2. Translation requested through a TMS (translation management system) or spreadsheet +3. Translation produced with translation memory (avoids retranslating reused phrases) +4. Review by a second translator or in-region staff +5. Localization beyond translation (currency, units, examples, cultural references) +6. Publishing in the destination locale +7. Update propagation when source content changes + +The TMS pays off above ~10K words of total content. Below that, spreadsheets and disciplined naming are fine. + +Update propagation is the hardest part. Source content changes. Translations go stale. Without a process, you end up with locales drifting from the source. + +### Layer 5: Locale-aware UX + +Beyond translation, the experience must adapt. + +Currency: display in the local currency where applicable. EUR for European locales, JPY for Japanese, etc. Don't show USD to French users for a French-locale page. + +Numbers: thousand separators and decimals differ. `1,000.50` in en-US is `1.000,50` in de-DE. + +Dates and times: format and order vary. `MM/DD/YYYY` in en-US, `DD/MM/YYYY` in en-GB, `YYYY-MM-DD` (ISO) is universal but unfamiliar to many. + +Names and addresses: field order and required components differ. Country-aware address forms. + +Phone numbers: E.164 international format universally; display formatting per locale. + +Units: metric vs imperial. Most of the world is metric; the US is imperial. Some products serve both. + +Right-to-left (RTL) languages: Arabic, Hebrew, Persian, Urdu. Layout flips: navigation moves right, text aligns right, icons that imply direction may flip too. CSS logical properties (`margin-inline-start` instead of `margin-left`) make this manageable. + +Language switcher: prominent but not intrusive. Show locale names in their own language ("Deutsch" not "German"). Persist the choice. Don't auto-redirect based on browser language without offering a way back. + +Cultural sensitivity: colors, imagery, examples, references that don't translate. Avoid hand gestures in product imagery. Avoid country-specific references unless localized. + +--- + +## Workflow + +### Step 1: Decide which locales + +Don't add languages just because you can. Each locale has ongoing maintenance cost. + +- Audience research: where are visitors and prospects? +- Business priority: which markets are growth targets? +- Content readiness: do you have the resources to maintain it? +- Legal: do regulations require localization (GDPR, accessibility laws)? + +### Step 2: Pick URL structure + +Subfolder for most. Document the choice and rationale. + +### Step 3: Pick content structure + +Mirror, subset, or local. Be honest about what's sustainable. + +### Step 4: Set up hreflang and canonicals + +Implement before launching the second locale, even if it's just one extra page. + +### Step 5: Set up translation workflow + +Pick a TMS or spreadsheet system. Document the workflow. Designate translators and reviewers. + +### Step 6: Localize beyond translation + +For each locale: +- Currency, numbers, dates, units +- Locale-specific images if needed +- Address forms +- Customer service hours and contact + +### Step 7: Implement language switcher + +- Prominent in the header or footer +- Shows the current locale clearly +- Lists all available locales in their own language +- Persists the choice (cookie or local storage) +- Doesn't auto-redirect based on browser; suggests instead + +### Step 8: Test + +- Each locale renders correctly +- hreflang links are valid (use a checker) +- Canonicals are self-referential per page +- Currency and dates are correct +- RTL layout is correct (for RTL locales) +- Language switcher works and persists +- Search-engine perspective: each locale is crawlable and indexable + +### Step 9: Launch and monitor + +Per locale: +- Indexing rate +- Traffic from intended geographies +- Engagement metrics in the locale +- Translation freshness (when did source content change without translation update?) + +### Step 10: Maintain + +- Translation update cadence (when source changes, when translations follow) +- Quarterly review of locale performance +- Sunset locales that aren't viable (better than maintaining a dead locale poorly) + +--- + +## Failure patterns + +Auto-redirect based on browser language. User is in Germany, prefers English. Site forces German. Frustrating. Suggest, don't redirect. + +Single canonical to default language. Search engines can't index the translations. Self-canonical per page. + +Reciprocal hreflang missing. German page lists English as its translation, English page doesn't list German. Search engines treat the relationship as unconfirmed. + +hreflang language without region when region matters. `hreflang="es"` is fine if there's one Spanish version. If you have es-ES (Spain) and es-MX (Mexico), use both with regions. + +Auto-translated content treated as final. Machine translation is an acceptable starting point. Human review is necessary for any user-facing content. + +Currency baked into copy. "$99/month" in body text breaks for European users. Use templated currency that adapts. + +Hardcoded date formats. "January 5, 2024" in code. Doesn't adapt. Use a date formatting library that respects locale. + +Field labels left in source language. Translated body, untranslated form labels. Inconsistent. Translate UI strings as part of localization. + +Untranslated error messages. User submits a form, gets an error in English on a French page. Frustrating. Translate UI states. + +Untranslated emails. Site is in French; transactional emails are English. Translate emails to match. + +Forgotten locales in CMS. Editors forget to update one locale. Drift. Use a TMS or workflow that surfaces drift. + +Locale switcher that doesn't work mid-flow. User is on the German checkout, switches to French, lands on French homepage. Try to land on the same page in the new locale. + +RTL layouts that don't actually flip. Margin and padding hardcoded for LTR. Use CSS logical properties. + +Sunset language without redirect. Discontinuing French; old French URLs 404. Redirect to the closest equivalent in another supported language. + +--- + +## Output format + +An internationalization plan includes: + +- Locale list: with priority and audience rationale +- URL structure: chosen pattern and reason +- Content structure: mirror, subset, or local +- hreflang plan: how it's implemented +- Translation workflow: sources, stages, tools +- Localization checklist: beyond translation (currency, dates, etc.) +- Language switcher design: position, behavior, persistence +- Test plan: what's verified per locale +- Maintenance plan: update cadence, drift detection + +--- + +## Reference files + +- [`references/locale-checklist.md`](references/locale-checklist.md): Per-locale checklist of everything that needs to adapt beyond translation, organized by category (URL, content, UX, format, legal). diff --git a/skills/internationalization/references/locale-checklist.md b/skills/internationalization/references/locale-checklist.md new file mode 100644 index 0000000..8bb3bd8 --- /dev/null +++ b/skills/internationalization/references/locale-checklist.md @@ -0,0 +1,233 @@ +# Locale Checklist + +A per-locale checklist of everything that needs to adapt beyond translation. Walk through this for each locale before launch, and revisit when adding new content. + +--- + +## URL and structure + +- [ ] Locale URL pattern chosen and consistent (subfolder, subdomain, or ccTLD) +- [ ] Locale code uses standard format (BCP 47: `en`, `en-US`, `de-DE`, `zh-Hant`) +- [ ] Default locale handling decided (apex vs folder) +- [ ] URL slugs translated where appropriate (e.g., `/products/` → `/produkte/` for German) +- [ ] Or URL slugs kept consistent across locales (acceptable for many sites; prioritizes consistency over native readability) + +--- + +## Search engine signals + +- [ ] hreflang tags present on every page, every locale +- [ ] hreflang reciprocity verified (page A links to B, B links to A) +- [ ] hreflang includes `x-default` pointing to the fallback +- [ ] Canonical tags self-reference (each locale page canonicals to itself) +- [ ] Sitemaps include all locales (one sitemap per locale or a combined sitemap) +- [ ] robots.txt allows all locale paths +- [ ] Schema.org `inLanguage` attribute on appropriate types + +--- + +## Translation completeness + +- [ ] Page content translated +- [ ] Page titles and meta descriptions translated +- [ ] Image alt text translated +- [ ] Form labels translated +- [ ] Form validation messages translated +- [ ] Error pages (404, 500) translated +- [ ] Success messages translated +- [ ] Email templates translated (transactional, marketing) +- [ ] PDF or downloadable assets translated (or alternate version provided) +- [ ] Help and FAQ content translated +- [ ] Legal pages translated (privacy, terms, cookies) + +--- + +## Currency and money + +- [ ] Currency displayed matches the locale (EUR for euro zone, GBP for UK, JPY for Japan, etc.) +- [ ] Currency symbol position correct ($1,000 vs 1.000 €) +- [ ] Decimal separator correct (1,000.50 vs 1.000,50 vs 1 000,50) +- [ ] Thousand separator correct (comma, period, space, or none) +- [ ] Pricing tables localized to native pricing (not direct conversion) +- [ ] Tax handling (inclusive vs exclusive) matches local convention + +--- + +## Numbers and units + +- [ ] Number format follows locale (1,234.56 vs 1.234,56) +- [ ] Negative numbers (-5 vs (5)) follow convention +- [ ] Percentages format correctly (5% vs 5 %) +- [ ] Measurement units match (km vs miles, kg vs lb, °C vs °F) +- [ ] Paper sizes if relevant (A4 vs Letter) + +--- + +## Dates and times + +- [ ] Date format matches (DD/MM/YYYY for most of Europe, MM/DD/YYYY for US, YYYY-MM-DD ISO) +- [ ] Day-of-week localization (Monday vs Lundi vs 月曜日) +- [ ] Month names localized +- [ ] First day of week (Monday in Europe, Sunday in US) +- [ ] Time format (12-hour with AM/PM vs 24-hour) +- [ ] Time zone display where relevant +- [ ] Relative time strings localized ("2 hours ago" → "il y a 2 heures") + +--- + +## Names and addresses + +- [ ] Name field structure matches (single name field for some cultures, given/family for others, family-first ordering for some Asian languages) +- [ ] Address form fields adapt to country + - US: street, city, state, ZIP + - UK: street, town, county, postcode + - Germany: street, postal code, city + - Japan: postal code, prefecture, city, ward, block, building +- [ ] Postal code validation per country +- [ ] State/region/prefecture/county field renamed appropriately +- [ ] Country dropdown ordered by region or alphabetical (avoid US-first if not US-centric audience) + +--- + +## Phone numbers + +- [ ] Country code defaulted appropriately +- [ ] E.164 format stored (+CCNNNNNNNNNN) +- [ ] Display format adapts to country +- [ ] Validation accepts international formats + +--- + +## Imagery and media + +- [ ] Images depict locally relevant people, places, products +- [ ] Avoided imagery that's offensive in the locale (gestures, symbols, color associations) +- [ ] Cultural references in screenshots/examples are appropriate +- [ ] Image text translated (text in images doesn't auto-translate) +- [ ] Video subtitles or dubbing in the locale language + +--- + +## Layout and direction + +- [ ] LTR/RTL handling correct for the script +- [ ] CSS logical properties used (`margin-inline-start` instead of `margin-left`) +- [ ] Icons that imply direction (arrows, chevrons) flip for RTL +- [ ] Numbers display LTR even within RTL text (per Unicode bidi algorithm) +- [ ] Tables and lists adjusted for direction + +--- + +## Typography + +- [ ] Fonts support the script (not all fonts cover Cyrillic, CJK, Arabic, etc.) +- [ ] Font sizes adjusted if needed (some scripts read smaller; CJK often needs slightly larger) +- [ ] Line height appropriate (CJK often needs more) +- [ ] Word breaking handled (no breaking in the middle of CJK characters; break opportunities for Thai) +- [ ] Quotation marks correct ("..." in English, „..." in German, «...» in French, 「...」 in Japanese) + +--- + +## Search and sort + +- [ ] Search handles diacritics ("café" matches "cafe" or doesn't, by design) +- [ ] Sort order respects locale (German sorts ä with a, Swedish sorts ä after z) +- [ ] Search results in the same locale as the user (don't show English results to French users) + +--- + +## Forms and inputs + +- [ ] Input methods supported (IMEs for CJK, etc.) +- [ ] Pasting from clipboard works with non-Latin characters +- [ ] Field validation accepts non-Latin characters where appropriate (names should accept any Unicode) +- [ ] Min/max length constraints work for the script (Japanese names are often shorter; Arabic/Hebrew names use different character counts) + +--- + +## Legal and compliance + +- [ ] Privacy policy adapted to local laws (GDPR for EU, LGPD for Brazil, CCPA for California, etc.) +- [ ] Cookie consent matches local requirements +- [ ] Terms of service in local language and acknowledging local law +- [ ] Required disclaimers present (consumer protection, financial services, healthcare, etc.) +- [ ] Tax handling per locale (display inclusive in EU, exclusive in US, etc.) +- [ ] Local payment methods supported where customer expectations require + +--- + +## Customer support and contact + +- [ ] Support hours displayed in local timezone +- [ ] Support contact options match (phone numbers, chat, email, varies by region) +- [ ] Office address (if shown) is appropriate for the locale +- [ ] Local language support team or clear "support in [language]" indication + +--- + +## Marketing and SEO + +- [ ] Keyword research done in the local language (not just translated keywords) +- [ ] Meta titles and descriptions are locally compelling, not just translated +- [ ] Open Graph tags adapted (translated, locale-appropriate images) +- [ ] Schema.org markup translated where text-based +- [ ] Local search engines considered (Baidu in China, Yandex in Russia) +- [ ] Backlink strategy adapted to local web (local directories, local press) + +--- + +## Testing per locale + +- [ ] Page renders correctly in all major browsers +- [ ] Page renders correctly on mobile +- [ ] All links work and stay within the locale (or correctly switch locale) +- [ ] Forms submit correctly +- [ ] Confirmation flows work end-to-end (form → email → next step) +- [ ] No untranslated strings (search HTML for source-language strings) +- [ ] No broken images +- [ ] No layout breakage from longer or shorter text (German is often longer than English; CJK often shorter; Arabic similar to English in length but different layout) +- [ ] Performance comparable to default locale + +--- + +## Language switcher + +- [ ] Switcher visible on every page +- [ ] Available locales shown in their own language +- [ ] Current locale clearly indicated +- [ ] Switcher preserves the current page (not just sends to homepage) +- [ ] Switcher persists user choice (cookie or local storage) +- [ ] Switcher doesn't auto-redirect on first visit (suggests, doesn't force) + +--- + +## Maintenance + +- [ ] Translation update workflow defined +- [ ] Drift detection in place (when source changes, translation needs update) +- [ ] Per-locale analytics set up +- [ ] Per-locale error monitoring +- [ ] Translation quality reviewed periodically +- [ ] Locale sunset criteria defined (when to retire a poorly-performing locale) + +--- + +## Per-locale metrics to watch + +\| Metric \| Target \| +\|---\|---\| +\| Page completion rate \| Comparable to default locale \| +\| Form completion rate \| Comparable to default locale \| +\| Bounce rate \| Comparable to default locale \| +\| Time on page \| Comparable to default locale \| +\| Conversion rate \| Comparable to default locale \| +\| Translation freshness \| Source content updates reflected within X days \| + +A locale persistently underperforming on user metrics may have: +- Translation quality issues +- Cultural mismatches in copy or imagery +- Missing local payment or contact options +- Slow performance from far hosting +- Unmet user expectations (US e-commerce conventions used in markets that prefer different patterns) + +Investigate before scaling investment. diff --git a/skills/journey-mapping/SKILL.md b/skills/journey-mapping/SKILL.md new file mode 100644 index 0000000..c65508e --- /dev/null +++ b/skills/journey-mapping/SKILL.md @@ -0,0 +1,244 @@ +--- +name: journey-mapping +description: "Build customer journey maps and service blueprints that visualize the end-to-end user experience including touchpoints, emotions, friction, and underlying systems. Use this skill whenever the user wants to map a customer journey, build a service blueprint, identify friction across an experience, align teams on the user experience, or visualize touchpoints and pain points. Triggers on customer journey, journey map, service blueprint, user journey, experience map, touchpoint analysis, friction map, journey audit, end-to-end experience, customer experience map. Also triggers when the team has departmental views of users but no shared map of what the experience actually feels like." +category: research +catalog_summary: "Customer journey maps, service blueprints, friction analysis" +display_order: 3 +--- + +# Journey Mapping + +Build journey maps and service blueprints that surface friction, align teams, and identify opportunities. Stack-agnostic. Tool-agnostic. + +This skill is for mapping the experience. For testing specific touchpoints, use `usability-testing`. For broader generative research, use `ux-research`. For analyzing conversion, use `cro-optimization`. + +--- + +## When to use + +- Departments have different mental models of the customer experience +- Customer experience feels disjointed across touchpoints +- Specific friction or drop-off points need diagnosis +- Strategic planning needs a shared view of the user +- Service design (front-stage and back-stage) needs alignment +- New product or feature needs to be designed in context of broader experience + +## When NOT to use + +- Testing a single touchpoint or page (use `usability-testing`) +- Generative research before journey mapping (use `ux-research`) +- Operational process mapping that doesn't involve users +- Funnel optimization (use `cro-optimization`) + +--- + +## Required inputs + +- Identified user persona or segment to map (one map per segment) +- Existing research and data about that segment +- Cross-functional access (you cannot map back-stage without ops/support/engineering input) +- Time and stakeholder commitment (a real journey map is a project, not an afternoon) + +--- + +## The framework: 3 deliverables + +### 1. Customer journey map + +The user-facing view of the experience. + +Structure (rows / lanes): + +- Phase. The major stages in the journey (e.g., Awareness, Consideration, Onboarding, Activation, Retention, Advocacy). Phases vary by product type. +- Steps. Specific things the user does within each phase. +- Touchpoints. Where the user interacts with the product, brand, or service (web, app, email, support, social, in-person). +- Goals. What the user is trying to accomplish at this step. +- Thoughts. What's going through their mind. +- Emotions. The emotional state (often visualized on a curve). +- Pain points. Where things go wrong, friction, frustration. +- Opportunities. Where the experience could improve. + +Format: + +Typically a horizontal timeline with vertical lanes for each row. Phases across the top, touchpoints, thoughts, emotions, etc. underneath. + +### 2. Service blueprint + +The back-stage view that supports the customer-facing experience. + +Adds these layers below the journey map: + +- Front-stage actions. What employees do that the user sees (sales calls, support chats, in-store interactions). +- Back-stage actions. What happens behind the scenes (order fulfillment, data processing, internal handoffs). +- Supporting processes. Systems, vendors, infrastructure (CRM, payment processors, fulfillment partners). +- Lines of visibility. The line between front-stage (visible to user) and back-stage (invisible). + +The service blueprint shows where customer-facing problems originate in back-stage failures (e.g., the user's "shipping is slow" experience traces to a vendor handoff issue). + +### 3. Synthesized opportunity map + +Output of the mapping work. + +Captures: + +- Top friction points. Where the experience consistently fails users. +- Untapped opportunities. Moments where the experience could surprise and delight. +- Disconnects. Where front-stage and back-stage are misaligned. +- Strategic gaps. Where competitors have something the brand lacks (or vice versa). +- Quick wins. Low-effort, high-impact improvements. +- Strategic bets. Higher-effort transformations. + +This is the deliverable that produces decisions. The journey map and service blueprint are inputs; the opportunity map is the output that drives action. + +--- + +## Common phases by product type + +### Most products + +``` +Awareness → Consideration → Decision → Onboarding → Active use → Renewal/Repurchase → Advocacy +``` + +### SaaS + +``` +Trigger → Discovery → Evaluation → Trial → Onboarding → Activation → Habit → Expansion → Renewal → Advocacy +``` + +### Ecommerce + +``` +Need recognition → Discovery → Research → Decision → Purchase → Wait/Anticipation → Receive → Use → Reorder/Recommend +``` + +### Service + +``` +Awareness → Inquiry → Quote → Decision → Service delivery → Resolution → Follow-up → Repeat business +``` + +### Healthcare / high-stakes purchases + +``` +Trigger → Research → Provider selection → Appointment → Treatment → Recovery → Follow-up → Long-term outcome +``` + +Phases are not mandatory. Start with the user's actual experience and let the phases emerge from the steps. + +--- + +## How to gather the inputs + +A good journey map combines multiple sources of truth. + +### From users + +- In-depth interviews. Walk users through their actual experience. Ask for specifics from a recent occurrence. +- Diary studies. Users log their experience over the duration of the journey. +- Surveys. Quantitative signal at scale; less depth. + +### From the business + +- Internal interviews. Sales, support, success, ops. They see the experience from different angles than product or design. +- Operational data. Funnel data, support ticket categories, NPS responses, churn reasons. +- System inventory. What touchpoints exist, what tools support them, what data flows where. + +### Cross-validate + +- The user's experience as they describe it +- The data the business has about their behavior +- The internal team's perception of the experience + +These three views often disagree. The disagreements are themselves findings. + +--- + +## Workflow + +1. Define scope. One persona, one journey, one timeframe. Trying to map all users in one map produces a mess. +2. Gather inputs. User interviews, internal interviews, operational data. Plan 2 to 4 weeks for inputs. +3. Draft the journey. Phases, steps, touchpoints. Get to a working draft fast; iterate. +4. Add the layers. Goals, thoughts, emotions, pain points. +5. Build the service blueprint. Front-stage, back-stage, supporting processes. +6. Identify opportunities. Use the friction points and disconnects. +7. Validate with users. Does this match their actual experience? Refine. +8. Workshop with stakeholders. Walk teams through the map. Ensure shared understanding. +9. Translate to action. Specific projects, owners, timelines. +10. Maintain. A journey map is a living document. Revisit annually or after major changes. + +--- + +## Failure patterns + +- Mapping without research. A journey map built from internal assumptions reflects assumptions, not users. +- One map for all users. The mid-market buyer and enterprise buyer have different journeys. Don't merge. +- No back-stage layer. The map shows symptoms, not causes. +- Beautiful map, no action. Investment in production value at the expense of decisions. +- Map as artifact, not tool. Filed in Figma, never re-opened. +- Ignoring emotional layer. The "what" without the "how it feels" misses the point of journey mapping. +- Vague pain points. "Frustrating onboarding" - what specifically? When? Why? +- Quick wins identified, never executed. Same as research findings that don't ship. +- Annual exercise without followup. Year-old journey map describes year-old user. + +--- + +## Output format + +Default outputs: + +1. Journey map (visual, typically Figma / FigJam / Miro, plus a markdown narrative version) +2. Service blueprint (visual, typically same tool) +3. Opportunity map (markdown, prioritized list) + +Markdown narrative version of journey map: + +```markdown +# [Persona] journey map + +## Phase 1: [Phase name] + +### Step: [Step name] +- Touchpoint: [Where this happens] +- Goal: [What the user wants here] +- Thoughts: [What they're thinking] +- Emotion: [State on the emotional curve] +- Pain points: [Friction] +- Opportunities: [Improvement potential] + +### Step: [Step name] +[Same structure] + +## Phase 2: [Phase name] +[Repeat] + +## Service blueprint additions + +### Phase 1 +- Front-stage actions: [What employees do user-visibly] +- Back-stage actions: [What happens behind the scenes] +- Supporting processes: [Systems involved] + +[Repeat per phase] + +## Opportunity map + +### Critical friction +1. [Specific issue, with evidence] +2. [Specific issue, with evidence] + +### Quick wins +1. [Specific opportunity, with effort/impact] + +### Strategic bets +1. [Specific opportunity, with effort/impact] + +### Cross-team disconnects +1. [Specific disconnect, with implication] +``` + +--- + +## Reference files + +- [`references/journey-map-template.md`](references/journey-map-template.md) - Fillable journey map and service blueprint template. diff --git a/skills/journey-mapping/references/journey-map-template.md b/skills/journey-mapping/references/journey-map-template.md new file mode 100644 index 0000000..372ea22 --- /dev/null +++ b/skills/journey-mapping/references/journey-map-template.md @@ -0,0 +1,317 @@ +# Journey Map Template + +Fillable journey map and service blueprint template. Customize phases to fit the specific product or service. + +--- + +## Map metadata + +Persona / segment mapped: [Specific persona. Not "users" - "First-time buyers in the 25-40 age range exploring B2B project management tools."] + +Time horizon mapped: [Pre-purchase to first 90 days? Full lifetime? Specific feature?] + +Map version: [X.Y] + +Last updated: [YYYY-MM-DD] + +Owner: [Person or team] + +Source data: [Interviews, surveys, support tickets, analytics. List with counts.] + +--- + +## Map structure + +\| Phase \| Step \| Touchpoint \| Goal \| Thoughts \| Emotion \| Pain points \| Opportunities \| +\|---\|---\|---\|---\|---\|---\|---\|---\| + +--- + +## Phase 1: [Phase name, e.g., Awareness] + +### Step 1.1: [Step name, e.g., Encounters problem] + +Touchpoint: [Where this happens. Could be offline. "Conversation with peer." Or online: "LinkedIn post."] + +Goal: [What the user is trying to accomplish at this step] + +Thoughts: +- "[Specific thought, ideally a real quote from research]" +- "[Specific thought]" +- "[Specific thought]" + +Emotion: [Emotional state, ideally from a defined set: confused, hopeful, frustrated, curious, anxious, confident, etc.] + +Emotional intensity: [1 to 5, for plotting on the emotional curve] + +Pain points: +- [Specific pain, with evidence] +- [Specific pain, with evidence] + +Opportunities: +- [Specific improvement opportunity] +- [Specific improvement opportunity] + +Time spent at this step: [Minutes / hours / days / weeks - average and range] + +--- + +### Step 1.2: [Step name] + +[Repeat structure] + +--- + +## Phase 2: [Phase name, e.g., Consideration] + +### Step 2.1: [Step name, e.g., Searches for solutions] + +Touchpoint: [e.g., Google search, then 4 to 6 vendor websites] + +Goal: [Build a shortlist of options that could fit] + +Thoughts: +- "[Quote]" +- "[Quote]" + +Emotion: [State] + +Emotional intensity: [1 to 5] + +Pain points: +- [Specific pain] +- [Specific pain] + +Opportunities: +- [Opportunity] + +Time spent: [Range] + +--- + +### Step 2.2: [Step name] + +[Repeat] + +--- + +## Phase 3: [Phase name, e.g., Decision] + +[Repeat structure] + +--- + +## [Continue with phases relevant to the journey...] + +--- + +## Emotional curve + +Plot the emotional intensity across the journey. The curve typically reveals the moments of highest joy and highest frustration. + +``` +Emotion +intensity + 5 │ + 4 │ ● + 3 │ ● ● ● + 2 │ ● ● ● ● + 1 │ ● ● + └────────────────────── + 1.1 2.1 3.1 4.1 + Phase / Step +``` + +[Document the emotional curve in your visual tool. Note the peaks (highest joy) and troughs (highest frustration). These are the most strategic points in the journey.] + +--- + +## Service blueprint layers + +For each phase, document the back-stage view. + +### Phase 1: [Phase name] + +Front-stage actions (employees in user view): +- [Action] +- [Action] + +Back-stage actions (employees behind the scenes): +- [Action] +- [Action] + +Supporting processes (systems, tools, vendors): +- [Process / system] +- [Process / system] + +Lines of visibility issues: +- [Where back-stage failures cause front-stage problems] + +--- + +### Phase 2: [Phase name] + +[Repeat] + +--- + +## Disconnects and gaps + +The most valuable findings often come from comparing layers. + +### Front-stage / back-stage disconnects + +\| Issue \| Front-stage symptom \| Back-stage cause \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +### Internal team perception vs user reality + +\| Internal belief \| User reality \| Gap \| +\|---\|---\|---\| +\| \| \| \| +\| \| \| \| + +### Touchpoint / message inconsistencies + +\| Touchpoint A says \| Touchpoint B says \| Confusion result \| +\|---\|---\|---\| +\| \| \| \| + +--- + +## Persona context (for reference) + +A reminder of who this map represents. + +Persona: [Name and one-line description] + +Demographics: +- Age range: +- Role / job: +- Company size or context: +- Geography: +- Tech savviness: + +Goals: +- [Primary goal] +- [Secondary goal] +- [Secondary goal] + +Frustrations: +- [Frustration] +- [Frustration] + +Behavior patterns: +- [Pattern] +- [Pattern] + +Quote that captures them: +> "[Quote from a research participant who exemplifies this persona]" + +--- + +## Data sources + +Document where the map's claims come from. Builds credibility and traceability. + +\| Claim \| Source \| Evidence \| +\|---\|---\|---\| +\| [Pain point at step 2.1] \| 8 of 10 interviews \| [Quote samples] \| +\| [Behavior at step 1.2] \| Analytics: 73% drop-off \| [Funnel data] \| +\| [Emotion at step 3.1] \| Survey, 45 responses \| [Score data] \| + +--- + +## Opportunity map + +The output that drives action. + +### Critical friction (fix soon) + +\| Friction \| Phase / step \| Evidence \| Recommended action \| Effort \| Owner \| +\|---\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| \| S/M/L \| \| +\| [Specific] \| \| \| \| S/M/L \| \| + +### Quick wins (low effort, meaningful impact) + +\| Opportunity \| Phase / step \| Recommended action \| Effort \| Impact \| +\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| S \| M \| + +### Strategic bets (high effort, transformative) + +\| Opportunity \| Phase / step \| Recommended action \| Effort \| Impact \| +\|---\|---\|---\|---\|---\| +\| [Specific] \| \| \| L \| H \| + +### Cross-team alignment opportunities + +[Issues that require multiple teams to coordinate, not single-team fixes.] + +- [Issue, teams involved, recommended approach] +- [Issue, teams involved, recommended approach] + +--- + +## Action plan + +Specific projects from the opportunity map. + +### Immediate (next 30 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Near-term (60 to 90 days) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +### Strategic (next 2 to 4 quarters) + +- [ ] [Action] - [Owner] +- [ ] [Action] - [Owner] + +--- + +## Re-mapping schedule + +Journey maps decay. Schedule re-mapping: + +- Triggering events: Major product launch, new persona segment, significant business model change, drop in NPS or retention +- Default cadence: Annual review, with light updates quarterly + +--- + +## Workshop outputs + +Use this map in stakeholder workshops. Capture outputs: + +Workshop 1: Validation +- Date: +- Attendees: +- Findings validated: +- Findings disputed: +- New findings surfaced: + +Workshop 2: Prioritization +- Date: +- Attendees: +- Top opportunities agreed: +- Decisions made: +- Open questions: + +--- + +## Companion artifacts + +Often produced alongside a journey map: + +- Persona document. Detailed persona that this journey map represents. +- Quote library. Direct user quotes organized by phase. Powerful in stakeholder presentations. +- Highlight reel video. 5 to 10 minute compilation of user moments mapped to journey phases. +- Service blueprint. Detailed back-stage map (this template includes a layer; a full blueprint deserves its own document). +- Opportunity backlog. All opportunities, scored and queued for execution. diff --git a/skills/jtbd-framing/SKILL.md b/skills/jtbd-framing/SKILL.md new file mode 100644 index 0000000..56313a8 --- /dev/null +++ b/skills/jtbd-framing/SKILL.md @@ -0,0 +1,260 @@ +--- +name: jtbd-framing +description: "The Jobs-to-be-Done framework as applied product methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity (discovery, prioritization, positioning) and where it becomes performative ritual (job-statement workshops that do not drive decisions, persona-theater disguised as JTBD). Triggers on jobs-to-be-done, JTBD, job statements, struggling moments, hire criteria, fire criteria, switch triggers, functional emotional social jobs, outcome-driven innovation. Also triggers when a team is over-relying on feature-request lists or persona archetypes that do not drive product decisions, when a positioning conversation needs the framing JTBD provides, or when discovery is producing outputs that do not connect to product strategy." +category: product +catalog_summary: "Jobs-to-be-Done framework. Job statements, struggling moments, hire/fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD earns its keep and where it becomes performative" +display_order: 11 +--- + +# Jobs-to-be-Done Framing + +A senior product leader's playbook for the Jobs-to-be-Done framework as applied methodology. Job statements, struggling moments, hire and fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD adds clarity and where it becomes performative ritual. + +JTBD has become one of the more cited and less practiced frameworks in product. Teams cite it in strategy docs, run job-statement workshops, produce wall-sized artifacts, and continue building from feature requests and persona archetypes the next quarter. The methodology gets the credit; the practice gets skipped. + +This skill is JTBD as applied product methodology. The framework's actual contribution: surfacing what users are trying to ACCOMPLISH (the job) rather than treating users as preference-aggregators (feature requests) or demographic archetypes (persona theater). When the framing is grounded in struggling moments and hire/fire criteria, it produces decisions; when it stops at the job-statement worksheet, it produces ritual. + +This skill is honest about both modes. JTBD genuinely earns its keep in discovery, prioritization, and positioning when applied with rigor. It becomes ceremony when teams treat job statements as deliverables rather than as analytical tools. + +The voice is the senior product leader who has used JTBD well and watched plenty of teams use it badly. Concrete, opinionated about what the framework actually contributes, willing to call out where it gets oversold. + +When to use this skill: applying JTBD to a discovery cycle, replacing persona-driven prioritization with job-driven prioritization, reframing positioning around what users hire the product to do, or auditing whether existing JTBD work in the org is driving decisions. + +--- + +## What this skill is for + +This skill spans JTBD as a framing technique within product work. The PM-skill distinction: + +- `discovery-research-synthesis` is broader synthesis discipline; JTBD is one framing technique within it. +- `jtbd-framing` (this skill) is the specific JTBD methodology, its strengths, and its failure modes. +- `pm-spec-writing` is downstream: specs reference jobs as input. +- `creative-direction` is positioning territory; JTBD informs positioning but does not replace creative direction. +- `roadmap-planning` is downstream: roadmap can be organized around jobs rather than features. + +The audience: senior PMs, product directors, product strategists, agencies running discovery and positioning work, in-house teams considering or already using JTBD. + +What is not in scope: other product strategy frameworks (Wardley mapping, North Star, OKRs); the broader synthesis discipline (`discovery-research-synthesis` covers it); the demographic-persona work that sometimes gets confused with JTBD. + +--- + +## Feature-request-list vs persona-theater vs job-framing + +The keystone framing. + +Feature-request-list. "Users want X, Y, Z." Treats users as preference-aggregators. The product team builds the most-requested features. Output: a product that satisfies stated preferences but misses what users were actually trying to accomplish. Users do not always know what would solve their problem; they describe symptoms, not solutions. Feature-list-driven products often improve incrementally without becoming meaningfully better. + +Persona-theater. Demographic personas with cute names. "Marketing Manager Maria, 35, urban, Pinterest user, drinks oat milk lattes." Decorative, not decision-driving. Persona characteristics rarely correlate with what the user needs from the product; demographic detail substitutes for behavioral insight. Personas in the wild often live as wall posters that nobody references in actual prioritization debates. + +Job-framing. Users hire products to do jobs. The job is what the user is trying to accomplish, not who the user is or what features they request. The framing surfaces struggling moments (when do users feel pulled toward an alternative); hire criteria (what makes them adopt a product); fire criteria (what makes them switch away). Output: product decisions grounded in user motivation rather than user description. + +The litmus test. Take a product decision the team is debating. Can JTBD ground the decision? "Should we build feature X?" Reframed: "What job would feature X help users do? What job is currently done badly that this addresses?" If the JTBD framing produces clearer arguments on both sides, the framing is earning its keep. If the JTBD framing just adds vocabulary without resolving the debate, the framing is ritual. + +--- + +## The job statement structure + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." + +Situation. The context, trigger, or moment when the job becomes active. Not a demographic; a moment. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck..." +- "When I get a customer escalation outside of business hours..." + +Motivation. What the user is trying to do in that situation. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage and respond without disrupting my evening too much..." + +Outcome. What success looks like; what the user is trying to achieve by doing the job. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." + +The structure forces specificity at all three levels. Vague situations, vague motivations, or vague outcomes produce job statements that drive nothing. + +Detail in [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md). + +--- + +## Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when the alternative tools they have feel inadequate, when they would actively prefer a different way of doing the job. + +The signal. Users describe friction in their current approach. They describe workarounds. They describe wishing they had something better. They describe specific moments when the current approach broke down. + +The methodology. Discovery interviews surface struggling moments through specific prompts: "Walk me through the last time you did X." "What was hardest about that?" "What would you have done differently if you could?" Specific recent moments produce richer data than abstracted descriptions of "how I usually do this." + +The pattern recognition. Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well in the market. + +The pitfall. Teams that interview without grounding in specific moments produce abstracted job descriptions that cannot drive decisions. "Users want to be more productive" is not a struggling moment; "I lost an hour on Tuesday assembling the board metrics from three different dashboards because none of them had the slice I needed" is. + +Detail in [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md). + +--- + +## Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground the framework in real decisions users make. + +Hire criteria. + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +Fire criteria. + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +Why hire/fire matters. + +- Hire criteria reveal what the product needs to be excellent at to win adoption. +- Fire criteria reveal what the product needs to maintain to retain users. +- The two are often different: features that win adoption are not always the features that prevent churn. + +The methodology. Customer interviews surface hire/fire through specific prompts: "What were you doing before you adopted X?" "What made you switch?" "If you switched away from X tomorrow, what would the trigger be?" Recent switch decisions are particularly rich; users remember the specific moment. + +Detail in [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md). + +--- + +## Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. + +Functional dimension. What the user is mechanically trying to accomplish. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." + +Emotional dimension. How the user feels (or wants to feel) doing the job. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." + +Social dimension. How the user wants to be perceived doing the job. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." + +Why three dimensions matter. + +- Products that win on functional alone often lose to alternatives that also serve emotional and social. +- Some product decisions hinge on emotional dimensions ("the user wants to feel in control"); functional analysis alone misses these. +- Social dimensions inform positioning more than functional descriptions do. + +The discipline. For each job statement, ask the three dimensions explicitly. Most early job statements are functional-only; the addition of emotional and social often reveals what the product actually needs to address. + +Detail in [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md). + +--- + +## Where JTBD adds clarity vs where it becomes ritual + +The honest framing. + +Where JTBD genuinely earns its keep. + +- Discovery. When research is grounded in struggling moments and hire/fire decisions, JTBD surfaces the user motivation that feature-list discovery misses. Discovery interviews structured around jobs produce richer data than ones structured around feature preferences. +- Prioritization. When the team is debating which work to prioritize, jobs ground the debate in what users are trying to accomplish. "Does this work help users do an important job better?" cuts through the politics of feature-request prioritization. +- Positioning. When marketing or sales is articulating what the product does, jobs frame the product as a way of accomplishing something the customer cares about, rather than as a feature list. + +Where JTBD becomes ritual. + +- Job-statement workshops as deliverables. The team runs a workshop, produces a wall of job statements, and never references the artifacts in subsequent decisions. The workshop became the deliverable; the analytical work did not happen. +- Job statements substituted for personas without analytical rigor. "We have JTBD now" but the team treats job statements as named characters (Job Bob, Job Alice) instead of as analytical tools. +- Mandatory JTBD for every product question. Every meeting starts with "what's the job?" Even when the question does not benefit from the framing. The methodology becomes a tax rather than a tool. +- JTBD as compliance. The org adopts JTBD because a leadership book or conference talk endorsed it; teams produce JTBD artifacts to show they are using the framework; nobody actually uses the framework to decide. + +The honest signal. If the team can show how a recent product decision was different because of JTBD analysis, the framework is earning its keep. If the team uses JTBD vocabulary but cannot trace decisions to JTBD analysis, the framework is ritual. + +--- + +## Applying JTBD to discovery, prioritization, positioning + +The three modes where JTBD genuinely contributes. + +Discovery. Structure interviews around recent struggling moments, hire decisions, and fire decisions. Gather job statements after the interviews from the data, not before. Cluster jobs across users. Name jobs from the clusters. Pair with `discovery-research-synthesis` for the broader synthesis discipline. + +Detail in [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md). + +Prioritization. When evaluating roadmap candidates, frame each candidate by the job(s) it addresses. Ask: which jobs is the product currently doing badly? Which candidates address those jobs vs adjacent or unrelated work? Pair with `roadmap-planning` for the broader prioritization discipline. + +Detail in [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md). + +Positioning. When articulating what the product is for, lead with the job rather than the features. "Help product teams synthesize discovery research into decisions" is a job framing; "AI-powered research synthesis with collaboration tools" is a feature framing. Pair with `creative-direction` and `brand-discovery` for the broader positioning work. + +Detail in [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md). + +- "We did the JTBD workshop but nothing changed in our roadmap." Job-statement workshop as deliverable; no analytical work after the workshop. +- "Our job statements all sound the same." Generic job statements; not grounded in specific struggling moments. Re-ground in interview data. +- "Our jobs read like feature requests." "When I am using product X, I want feature Y" is not a job; the job is what the user was trying to accomplish, independent of the product. +- "We have personas and jobs and they contradict each other." Personas are demographic; jobs are situational. They do not have to align; if they conflict, jobs usually carry more decision weight. +- "JTBD says we should build everything." Without prioritization across jobs, JTBD identifies many opportunities and does not pick. Pair with prioritization discipline. +- "We dropped JTBD because it became theater." Common; the recovery is JTBD as analytical tool, not JTBD as ritual. Use the framework where it earns its keep; do not force it everywhere. +- "Our job statements are functional only." Add emotional and social dimensions; many product decisions hinge on the latter two. +- "We cannot agree on the job." Often signals different segments with different jobs. Surface the segment differences. +- "Our marketing copy uses JTBD vocabulary but our product does not." Positioning-product gap; the marketing claim is not load-bearing in product decisions. + +--- + +## The framework: 12 considerations for JTBD framing + +When applying JTBD or auditing JTBD work, walk these 12 considerations. + +1. Job-framing, not feature-list or persona-theater. Users hire products to accomplish jobs. +2. Job statement structure: situation, motivation, outcome. Specific at all three levels. +3. Struggling moments ground the jobs. Specific recent moments, not abstractions. +4. Hire criteria identified. What makes users adopt the product over alternatives. +5. Fire criteria identified. What makes users switch away (or would). +6. Functional, emotional, social dimensions surfaced. All three; not functional only. +7. Jobs derived from data, not workshop output. Job statements emerge from interview data, not from whiteboard sessions. +8. JTBD applied where it earns its keep. Discovery, prioritization, positioning. Not as ritual. +9. Segment differences in jobs surfaced. When the same product is hired for different jobs by different segments. +10. Decisions traceable to JTBD analysis. Each major decision can be explained through the job framing. +11. JTBD vocabulary not substituted for analytical work. Vocabulary without analysis is ritual. +12. Honest assessment of where JTBD does not help. Some questions do not benefit from the framing; force-fitting produces ritual. + +The output of the framework is product decisions grounded in user motivation rather than user description, with the framing applied where it adds clarity and held back where it would become ritual. + +--- + +## Reference files + +- [`references/job-statement-structure-patterns.md`](references/job-statement-structure-patterns.md) - The situation/motivation/outcome structure with worked examples. Common structural failures (vague situations, motivation as feature request, outcome as feature output). +- [`references/identifying-struggling-moments.md`](references/identifying-struggling-moments.md) - Discovery prompts that surface struggling moments. Pattern recognition across users. The specific-moment vs abstraction distinction. +- [`references/hire-and-fire-criteria.md`](references/hire-and-fire-criteria.md) - Methodology for surfacing hire and fire criteria. Why the two are often different. Recent-switch interview discipline. +- [`references/functional-emotional-social-dimensions.md`](references/functional-emotional-social-dimensions.md) - Three dimensions per job. Why functional-only fails. Worked examples per dimension. Positioning implications of social dimension. +- [`references/applying-jtbd-to-discovery.md`](references/applying-jtbd-to-discovery.md) - Discovery interview structure around jobs. Job clustering. Naming jobs from data. Pair with discovery-research-synthesis. +- [`references/applying-jtbd-to-prioritization.md`](references/applying-jtbd-to-prioritization.md) - Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. Pair with roadmap-planning. +- [`references/applying-jtbd-to-positioning.md`](references/applying-jtbd-to-positioning.md) - Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pair with creative-direction. +- [`references/common-jtbd-failures.md`](references/common-jtbd-failures.md) - 9+ failure patterns with diagnoses and cures. The cross-cutting pattern: JTBD as ritual vs JTBD as analytical tool. + +--- + +## Closing: jobs over features + +The Jobs-to-be-Done framework is one of the most useful product methodologies available when applied with rigor, and one of the most performative when applied as ritual. The difference is in whether the framework drives decisions or decorates documentation. + +Jobs over features is a real shift in product thinking. Feature-list discovery treats users as preference-aggregators; persona archetypes treat users as demographic categories; job-framing treats users as people trying to accomplish things, where the product is one tool they hire (or fire) for the job. + +The teams that benefit from JTBD are the ones that take the analytical work seriously: grounding jobs in struggling moments, identifying hire and fire criteria, surfacing functional-emotional-social dimensions, deriving jobs from data, and applying the framing where it earns its keep. The teams that adopt JTBD vocabulary without the analytical work produce ritual. + +When in doubt about whether a JTBD application is real or ritual, ask: can a recent product decision be traced to the JTBD analysis, or did the JTBD work happen in parallel with decisions that were made on other grounds? If the former, JTBD is doing its work. If the latter, the framework is decoration. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-discovery.md b/skills/jtbd-framing/references/applying-jtbd-to-discovery.md new file mode 100644 index 0000000..cddb634 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-discovery.md @@ -0,0 +1,211 @@ +# Applying JTBD to discovery + +How JTBD shapes discovery interview structure, job clustering, and naming jobs from data. Pairs with `discovery-research-synthesis` for the broader synthesis discipline. + +JTBD's strongest contribution to discovery is structural: interviews grounded in struggling moments and hire/fire decisions produce richer data than interviews that ask about feature preferences or use cases. + +--- + +## Structuring discovery interviews around jobs + +The JTBD discovery interview structure differs from feature-elicitation interviews. + +Feature-elicitation interview pattern. + +- "What problems are you trying to solve?" +- "What features would help?" +- "What is your ideal product?" + +This structure produces user-prescribed solutions: feature requests, ideal-product fictions, and abstracted preferences. The data is hard to act on because users do not always know what would actually help. + +JTBD interview pattern. + +- "Walk me through the last time you did [task]. What happened? What was hardest?" +- "What were you doing before you adopted [current solution]? What made you switch?" +- "Tell me about a recent time when [task] went badly. What was different about that time?" +- "If you switched away from [current solution] tomorrow, what would the trigger be?" + +This structure grounds the data in specific moments and real decisions. Users describe their experience; the PM doing synthesis interprets what the experience implies. + +--- + +## Interview prompts that work + +Recent specific moments. + +- "Walk me through the most recent time you did [task]." +- "What was the last week when [task] cost you more time than usual?" +- "When was the last time [task] surprised you in a bad way?" + +Hire decision prompts. + +- "Tell me about the moment you decided to start using [product]." +- "What were you doing before? What made you switch?" +- "What alternatives did you consider? What ruled them out?" + +Fire decision prompts (for users who switched). + +- "Tell me about the moment you decided to switch away from [product]." +- "What was the alternative starting to look better? What tipped you?" +- "Looking back, why didn't you switch sooner?" + +Workaround prompts. + +- "What's something you do that takes longer than it should?" +- "What workarounds have you built?" +- "When was the last time you accepted a worse outcome because the better path was too painful?" + +--- + +## Interview prompts that fail + +Hypothetical prompts. + +- "What would your ideal product look like?" (produces fiction) +- "If you had a magic wand, what would you change?" (produces wishlist) +- "What features would you like?" (produces feature lists) + +Abstracted prompts. + +- "How do you usually do [task]?" (produces averaged descriptions) +- "What's your typical experience?" (loses the specifics) +- "What kind of user are you?" (produces self-categorization) + +Leading prompts. + +- "Don't you find [feature] frustrating?" (confirms the team's hypothesis) +- "Wouldn't it be great if [feature]?" (produces agreement, not data) + +--- + +## The interview length and depth + +JTBD interviews benefit from depth. Surface answers come quickly; deeper jobs surface in the second half of an interview. + +Typical structure. + +- Minutes 0-15: warm-up, general context, what the user does and how their work fits together. +- Minutes 15-45: the recent specific moments, walk-throughs, struggling moments. The richest data emerges here. +- Minutes 45-60: hire and fire decisions, alternatives considered, switch decisions. +- Minutes 60-75 (when warranted): emotional and social dimensions, how the user wants to be perceived doing the work. +- Minutes 75-90: closing prompts, what the user wishes was different, what they would have done differently. + +The depth payoff. Users open up after 30-40 minutes. The struggling moments they describe in the second half are usually richer than the first-half answers. Cutting interviews short at 45 minutes loses the depth. + +The 90-minute upper bound. Beyond 90 minutes, fatigue degrades data quality. Schedule for 90; complete in 60-75; leave room for the depth without forcing it. + +--- + +## Job clustering from interview data + +After interviews, jobs emerge through clustering (per the synthesis sequence in `discovery-research-synthesis`). + +The clustering work. + +- Tag struggling moments and hire/fire decisions across interviews. +- Cluster moments that share underlying jobs (the user was trying to accomplish the same thing). +- Each cluster becomes a candidate job. +- Name the job from the cluster, not from a pre-built list. + +Common clustering patterns. + +- Multiple users described the same kind of friction in similar contexts. The cluster becomes one job. +- Multiple users described different surface-level frictions but the same underlying motivation and outcome. The cluster reveals a job that surfaces differently across users. +- One user's described moment is unique. May be an edge case, may be a job worth surfacing as smaller-segment. + +--- + +## Naming jobs from data + +Jobs are named from the cluster, not from a pre-built taxonomy. + +The naming process. + +- Read the cluster's contributing moments. +- Identify the situation, motivation, and outcome that recurred. +- Write the job statement: "When [situation], I want to [motivation], so I can [outcome]." +- Test the statement against the source moments: does it capture what users were trying to accomplish? + +The iteration discipline. First-pass job statements are usually too narrow or too broad; refine through iteration. + +Worked example. A cluster of moments around quarterly board prep: + +- Multiple users described assembling data from multiple sources. +- Multiple described uncertainty about whether they had the right slice. +- Multiple described the time pressure and the disruption to other work. +- Multiple described wanting to walk into the board with confidence. + +First-pass job statement: "When preparing the board deck, I want to assemble data from multiple sources, so I can present numbers correctly." + +Second-pass refinement: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The second pass captures the situation more specifically (quarterly business reviews, not just any board deck), the motivation more specifically (coherent narrative I can defend, not just data assembly), and the outcome more specifically (answer questions confidently without grinding the night before, not just present numbers correctly). + +--- + +## How many jobs emerge from typical discovery + +Strong discovery cycles often surface 3-8 jobs across the research batch. + +Smaller numbers (1-2 jobs). May indicate the discovery scope was narrow (only one user task investigated) or the synthesis under-clustered. + +Mid numbers (3-8 jobs). Typical for substantive discovery cycles. Jobs cover the major user motivations the research surfaced. + +Larger numbers (10+ jobs). May indicate over-clustering (each cluster is small and the overall synthesis is fragmented) or genuine breadth (the research investigated multiple distinct user contexts). + +The discipline. Job count should reflect the underlying patterns the data reveals, not a target number. Force-fitting to 7 jobs because "that feels right" produces synthesis that does not match the data. + +--- + +## Pairing JTBD discovery with quantitative validation + +Qualitative job patterns often warrant quantitative validation. + +The pattern. + +- Job statement claims a specific frequency or severity ("users hit this friction in 40% of attempts"). +- Quantitative data validates: analytics shows configuration step abandonment rate; survey data confirms the segment proportion; product instrumentation captures the in-the-moment frequency. +- If validation confirms: the job statement is strongly supported. +- If validation contradicts: revise the job statement to reflect the data. + +Pair with `experiment-design` for rigorous validation methodology and `product-analytics-setup` for the instrumentation that makes validation possible. + +--- + +## When JTBD discovery does not fit + +Some discovery does not benefit from JTBD framing. + +Greenfield categories. When the product is a category-defining product, users may not have struggling moments because the alternative is not having the capability at all. JTBD framing is useful but may need to be supplemented with broader product strategy. + +Highly novel use cases. When users have not yet developed mental models for the use case (e.g., new technology categories), struggling moments may not exist because the activity itself does not exist. Discovery may need to focus on adjacent activities and what users would do if the new capability existed. + +Pure positioning research. When the discovery is about how to position an existing product, hire and fire criteria interviews are useful, but emotional and social dimensions of positioning matter as much as the JTBD-framed jobs. + +The discipline. JTBD is a tool, not a mandate. When the discovery question fits the framework, use it. When it does not fit cleanly, supplement with other discovery techniques. + +--- + +## Common JTBD-discovery failures + +Eliciting feature lists instead of jobs. Interview prompts ask "what features do you want" rather than "what are you trying to accomplish." Restructure prompts. + +Pre-built job taxonomy. Researchers arriving with named jobs and slotting interview data into them. Jobs should emerge from data; pre-built taxonomies confirm what the team already thinks. + +Skipping struggling moments. Interviews capture preferences and use-cases without grounding in specific friction events. Add struggling-moment prompts. + +Skipping hire/fire decisions. Interviews ask about current usage but not about adoption or switch decisions. Add hire and fire prompts. + +Job statements written from intuition rather than data. Researchers writing jobs based on what they think users are trying to do, without grounding in interview clusters. + +Force-fitting all data to JTBD. Some interview data does not fit the JTBD framing cleanly; the team forces it in anyway. Better: surface what JTBD captures and supplement with other framings for the rest. + +--- + +## Methodology-level choices that stay in the public skill + +The interview structure that grounds in jobs. Prompts that work and fail. Interview length and depth. Job clustering from interview data. Naming jobs from data. Typical job counts. Pairing with quantitative validation. When JTBD discovery does not fit. Common failures. + +## Implementation choices that stay internal + +Specific interview templates. Specific recording and tagging tools. Specific synthesis tooling for job clustering. Specific recruitment criteria. The team's own conventions for interview cadence and batch sizing. These vary by team. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-positioning.md b/skills/jtbd-framing/references/applying-jtbd-to-positioning.md new file mode 100644 index 0000000..8d40f19 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-positioning.md @@ -0,0 +1,201 @@ +# Applying JTBD to positioning + +Job-led positioning vs feature-led positioning. Lead with what the product helps users accomplish. Pairs with `creative-direction` and `brand-discovery` for the broader positioning work. + +JTBD's contribution to positioning is the lead message: positioning that names the job the product helps users accomplish creates affinity in ways feature lists do not. The functional, emotional, and social dimensions of jobs all inform positioning differently. + +--- + +## Job-led vs feature-led positioning + +The two positioning approaches. + +Feature-led positioning. + +- "AI-powered analytics with collaborative dashboards and integrations." +- "Cloud-native CRM with automation and reporting." +- "Project management software with timelines, kanban, and integrations." + +Characteristics: lists features; competes on feature comparison; gets compared head-to-head with alternatives that have similar feature lists; produces buyer behavior of feature-checklist evaluation. + +Job-led positioning. + +- "Help product teams synthesize discovery research into decisions." +- "The CRM your sales team will actually use because it stays out of their way." +- "Run the project, not the project management tool." + +Characteristics: names what the product helps users accomplish; competes on outcome rather than feature parity; produces buyer behavior of job-fit evaluation; harder to copy because the positioning is built on understanding the job. + +The trade-off. Feature-led positioning is easier to write and easier for buyers to evaluate. Job-led positioning is harder to write but produces stronger affinity and is more durable to feature-parity competition. + +--- + +## When job-led positioning works + +Job-led positioning works best when: + +- The product addresses a job that users currently do badly with alternatives. +- The job has emotional or social dimensions that the positioning can serve. +- The user can recognize themselves in the job description. +- The market category is mature enough that feature comparison is no longer differentiating. + +Job-led positioning is less effective when: + +- The product is a new category and users do not yet recognize the job. +- The product is a commodity where job-fit is similar across alternatives. +- The buyer is not the user, and the buyer evaluates on different criteria than job-fit. + +--- + +## The lead message structure + +The lead message is the first thing prospects encounter (homepage hero, ad headline, sales pitch opener). + +Job-led lead message structure. + +- "[Product/category] for [user trying to do job in situation], so [outcome]." +- "[Action verb describing the job] without [the friction users currently encounter]." +- "[Outcome the product produces] for [user in situation]." + +Worked examples. + +- "Help product teams synthesize discovery research into decisions, not deck performance." +- "Run quarterly business reviews without spending Sunday night reconciling spreadsheets." +- "Onboard new engineers without becoming their full-time guide." + +Each example names a job, an outcome, and either a contrast (without the friction) or a quality (the way the product accomplishes the job). + +--- + +## Functional, emotional, social in positioning + +Positioning leans on different dimensions of the job for different effects. + +Functional dimension in positioning. + +- "[Product] does [job]." Direct and informative; lower-affinity. +- Worked example: "Synthesize discovery research from interview transcripts and support tickets." + +Functional dimension positioning is useful for product details, not for lead messages. Lead messages on functional alone compete on feature comparison. + +Emotional dimension in positioning. + +- "[Product] lets you do [job] feeling [desired emotional state]." +- Worked example: "Run discovery cycles feeling in control, not buried in transcripts." + +Emotional dimension positioning creates affinity. Users recognize the emotional state they want and connect with positioning that names it. + +Social dimension in positioning. + +- "[Product] for [user identity]." +- Worked example: "For PMs who run discovery seriously." + +Social dimension positioning creates identity affinity. Users want to belong to the kind of users the positioning describes. This dimension is often the strongest for positioning because it is hardest to copy and creates the most durable affinity. + +The composition. Strong positioning often combines all three dimensions: a functional lead with emotional and social undertones. "Run discovery cycles for PMs who take synthesis seriously, without burying yourself in transcripts." Functional (run discovery cycles), social (PMs who take synthesis seriously), emotional contrast (without burying yourself in transcripts). + +--- + +## Avoiding job-positioning that misses + +Job-led positioning fails when the named job does not match the user's actual situation. + +The pattern. Marketing crafts a job-led message that sounds compelling but does not match how target users describe their work. Users do not recognize themselves; the positioning underperforms. + +Worked failure example. A productivity SaaS positions as "Eliminate the chaos in your day." + +The pattern. The job named (eliminating chaos) is too abstract; users describe specific frictions ("I cannot find the right meeting notes when I need them; I spend 20 minutes a day reconciling calendar conflicts; I miss commitments because tasks are scattered across tools"). The positioning is generic; users cannot recognize their specific situation. + +The cure. Ground positioning in specific job statements that emerged from user research. The positioning should sound like users describing their own work, not like marketing describing users. + +--- + +## Positioning testing for JTBD-led messages + +Job-led positioning benefits from user testing. + +The test. Show the positioning to target users. Ask: + +- "Does this describe your work?" +- "Would you keep reading this?" +- "What product would you expect to be behind this positioning?" + +What good responses look like. + +- "Yes, that's exactly what I do." (positive recognition) +- "I would want to see what this is." (interest signal) +- "It sounds like a [accurate product description]." (the positioning communicates accurately) + +What bad responses look like. + +- "I'm not sure this applies to me." (mismatch) +- "It sounds generic." (not specific enough to the job) +- "I expect this to be a [different product type]." (positioning misleads) + +The iteration. Positioning often improves through 2-3 rounds of testing and revision. The ground-truth from target users surfaces the gap between what marketing wrote and what users recognize. + +--- + +## Positioning across multiple jobs + +Many products serve multiple jobs. Positioning must decide whether to lead with one job or surface multiple. + +Lead-with-one approach. + +- Pick the most differentiating, most strategically important job. +- Lead with that job in the primary positioning. +- Surface other jobs in secondary positioning (feature pages, segment-specific pages). + +Worked example. A productivity SaaS that serves task management, team coordination, and reporting jobs: + +- Primary positioning leads with team coordination (the most strategic, most differentiating job). +- Feature pages address task management for users who land there. +- Reporting positioning lives on a dedicated page for evaluators looking specifically for that job. + +Lead-with-many approach. + +- The product genuinely serves several jobs equally; leading with one would mislead. +- Use a multi-job message: "[Product] for [job A], [job B], and [job C]." +- Risk: looks like a feature list dressed in job language. + +The discipline. Most products benefit from leading with one job and supplementing. Lead-with-many positioning often collapses into "do everything" messaging that creates no specific affinity. + +--- + +## Positioning for jobs vs positioning for users + +JTBD positioning leads with jobs; persona positioning leads with user identity. + +Job-led positioning. "Help product teams synthesize discovery research into decisions." + +Persona-led positioning. "For senior product managers at high-growth SaaS companies." + +The two can compose. Strong positioning often pairs job and identity: "Help senior PMs at high-growth SaaS companies synthesize discovery research into decisions." + +The discipline. Lead with the job (what the user is trying to do); add identity (who the user is) to create the affinity layer. Identity-only positioning is persona theater; job-only positioning may not create enough affinity. Job + identity is often the strongest form. + +--- + +## Common JTBD-positioning failures + +Job-led messages that are too abstract. "Eliminate the chaos in your day" is job-flavored but does not name a specific job. Replace with the specific job from research. + +Feature-led messages dressed in job language. "Use our analytics to make better decisions" is feature-led; "make better decisions" is too generic to be a job. + +Job-led positioning that does not match user vocabulary. Marketing wrote the positioning without grounding in user research; users do not recognize the language. + +Lead-with-many positioning that becomes "do everything." Multiple jobs surfaced equally; positioning loses specificity. + +Positioning ignores the social dimension. Strong positioning often leans on social dimension; positioning that omits it competes only on functional and emotional. + +Positioning not user-tested. Marketing crafts the positioning in isolation; target users have not validated that they recognize themselves in it. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led vs feature-led distinction. When job-led works and does not. The lead message structure. Functional, emotional, social in positioning. Avoiding job-positioning that misses. Positioning testing methodology. Positioning across multiple jobs. Job vs persona positioning. Common failures. + +## Implementation choices that stay internal + +Specific positioning frameworks the team uses. Specific copy templates. Specific A/B testing setups for positioning variants. Specific user-testing methodologies. The team's own conventions for primary vs secondary positioning. These vary by team and brand discipline. diff --git a/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md b/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md new file mode 100644 index 0000000..57c1a53 --- /dev/null +++ b/skills/jtbd-framing/references/applying-jtbd-to-prioritization.md @@ -0,0 +1,206 @@ +# Applying JTBD to prioritization + +Prioritizing roadmap candidates by jobs. Identifying which jobs are done badly. The framing that cuts through feature-list politics. + +JTBD's contribution to prioritization is grounding the debate in user motivation rather than feature requests or stakeholder volume. Pairs with `roadmap-planning` for the broader prioritization discipline. + +--- + +## The job-led prioritization frame + +Each roadmap candidate gets evaluated by the jobs it addresses. + +The questions. + +- Which jobs is the product currently doing badly? +- Which roadmap candidates address those jobs vs adjacent or unrelated work? +- Which jobs matter most to the product's strategy and user base? +- What is the cost of addressing each candidate vs the value of the job improvement? + +Why this frame works. + +- It grounds prioritization in what users are trying to accomplish, not in what features they happen to have requested. +- It cuts through stakeholder politics: a roadmap candidate's value is measured against jobs, not against who is requesting it. +- It makes "we should not build this" defensible: candidates that do not address a load-bearing job get deprioritized clearly. + +The compose-with-strategy discipline. Job-led prioritization is downstream of strategy. The team needs to know which jobs matter for the product's market position; not all jobs are equally strategic. Pair with broader strategy work for the upstream framing. + +--- + +## Identifying jobs the product does badly + +The starting point for job-led prioritization. + +The methodology. + +- For each major job the product is meant to serve, evaluate how well it currently does the job. +- Use multiple inputs: user research (struggling moments, fire criteria), support data (where users hit friction), competitive analysis (where alternatives are stronger), in-product analytics (where users abandon). +- Score or rank jobs by how well they are currently served. Jobs done badly are candidates for prioritization investment. + +Worked example. A team productivity SaaS evaluating four core jobs: + +- Job A (creating tasks): well-served. Low priority for new investment. +- Job B (collaborating on tasks across teams): partially served. Some friction; alternatives are stronger; users describe workarounds. +- Job C (reporting on team progress): poorly served. High struggling-moment frequency; users export to spreadsheets; competitive products do this better. +- Job D (integrating with external tools): partially served. Friction at scale; mid-size customers describe pain. + +The badly-served jobs (B, C, D) are candidates for prioritization. Job A is not a fertile area for new investment. + +--- + +## Mapping roadmap candidates to jobs + +Each roadmap candidate gets associated with the jobs it addresses. + +The mapping. + +- Roadmap candidate: "Build cross-team task assignment with permissions." + - Job addressed: Job B (collaborating across teams). + - Job impact: addresses the core friction users describe; closes the gap with stronger alternatives. + +- Roadmap candidate: "Add custom report builder." + - Job addressed: Job C (reporting on team progress). + - Job impact: enables the reporting users currently export to spreadsheets to do. + +- Roadmap candidate: "Build mobile app for task creation." + - Job addressed: Job A (creating tasks) on mobile context. + - Job impact: extends a well-served job to a context where it currently is not served. Useful but not addressing a struggling job. + +- Roadmap candidate: "Redesign sidebar navigation." + - Job addressed: unclear. Possibly across multiple jobs. + - Job impact: hard to evaluate without clarification on which job this serves. + +The fourth example signals a problem. Roadmap candidates that do not clearly address a specific job often get prioritized on internal preferences rather than user value. The job mapping forces clarity: what job does this candidate serve, and how badly is that job currently being done? + +--- + +## The "no job, no priority" discipline + +Roadmap candidates that do not clearly address a job tied to user motivation often should not be prioritized. + +The pattern. + +- Candidate: "Migrate to a new internal framework." + - Job addressed: none directly; serves engineering velocity. + - Disposition: may be valuable for engineering reasons; do not prioritize on user-job grounds. If the team values engineering velocity, prioritize it on that basis explicitly. + +- Candidate: "Add dark mode." + - Job addressed: weak (some users describe preference). + - Disposition: low job-priority unless dark mode addresses an emotional dimension of jobs the team is also addressing. + +- Candidate: "Improve admin permissions." + - Job addressed: depends on which segment is asking. For enterprise: addresses fire criteria around compliance. For small teams: weak job impact. + - Disposition: prioritize for the segment whose job it serves; do not generalize. + +The discipline. Surface the job each candidate addresses (or does not). Candidates that do not serve jobs may still be valuable but should be prioritized on different grounds. The candidates the team can defend on jobs are the ones with the clearest user-value case. + +--- + +## Prioritization across jobs + +Different jobs have different strategic weights. The roadmap should reflect the strategy. + +The questions. + +- Which jobs are most load-bearing for the product's market position? +- Which jobs are most differentiated from competitors? (Where addressing the job better produces lasting advantage.) +- Which jobs serve the segments the strategy is targeting? +- Which jobs are growing in importance based on market trends? + +Worked example. A team productivity SaaS in mid-market growth: + +- Job B (cross-team collaboration): high strategic weight. Mid-market customers grow into multi-team workflows; the product needs to scale with them. +- Job C (reporting): high strategic weight. Mid-market customers need reporting that small-team customers did not require. +- Job D (integration): medium strategic weight. Important for retention; less differentiating than B and C. +- Job A (task creation): low strategic weight for new investment. Already served; not where competitors are winning. + +The strategic weighting biases the roadmap: B and C get more capacity than D; D gets more than A. + +--- + +## The "what job is this serving" review for in-flight work + +Job-led prioritization applies to existing work, not just new candidates. + +The review. + +- Take in-flight roadmap items. +- For each, ask: what job is this serving? How well does the work address that job? +- Items that cannot articulate a clear job may be candidates for re-scoping or cancellation. + +The honest case. Many roadmap programs accumulate work that started for reasons unrelated to user jobs (engineering preference, executive request, "we said we would"). The job review surfaces these and creates space to reconsider. + +The kindness. The review is not aimed at blame; sometimes work was committed before the team had the JTBD framing. The cure is reconsidering, not punishing. + +--- + +## Avoiding the JTBD-prioritization-religion failure + +JTBD as prioritization framework can become rigid in ways that hurt the team. + +Patterns to avoid. + +- Mandatory job-mapping for every roadmap item, including small bug fixes. The framework becomes overhead for low-value items. +- Treating job-impact estimates as precise numbers. Job-impact is often qualitative; pretending precision misleads. +- Over-weighting JTBD to the exclusion of other prioritization inputs. Strategic, technical, and operational considerations matter alongside jobs. + +The discipline. Use JTBD where it adds clarity to prioritization debates. Do not force the framework where it adds overhead without value. + +--- + +## Worked prioritization example + +A quarterly roadmap review at a team productivity SaaS. + +Available capacity. 5 large initiatives. + +Candidates with job mapping. + +1. Cross-team task assignment with permissions (Job B; high impact; high strategic weight). +2. Custom report builder (Job C; high impact; high strategic weight). +3. Mobile app for task creation (Job A on mobile; medium impact; low strategic weight). +4. Sidebar redesign (no clear job; serves general usability). +5. Slack integration upgrade (Job D; medium impact; medium strategic weight). +6. Onboarding redesign (multiple jobs; high impact on hire criteria for new customers). +7. Admin role overhaul (Job D for enterprise; high impact for that segment; matches enterprise expansion strategy). +8. Migration to new search backend (technical; serves multiple jobs indirectly). + +Prioritization decision (5 of 8). + +- Cross-team task assignment (1): yes. Top job priority. +- Custom report builder (2): yes. Top job priority. +- Onboarding redesign (6): yes. High hire-criteria impact. +- Admin role overhaul (7): yes. Enterprise strategy alignment. +- Migration to new search backend (8): yes. Technical foundation; serves multiple jobs. + +Deferred. + +- Mobile app for task creation (3): Job A is well-served on desktop; mobile is convenient but not high-priority. +- Sidebar redesign (4): no clear job. Reconsider for next cycle if a specific job emerges. +- Slack integration upgrade (5): Job D is medium-priority; can wait a quarter. + +The defense. The decisions can be explained on jobs and strategy. Stakeholders who pushed for items that did not make the cut can hear a clear rationale. The cut items can be reconsidered next quarter against jobs at that point. + +--- + +## Common JTBD-prioritization failures + +Job-mapping all candidates without segmenting strategic weight. Jobs treated as equal; the team picks based on impact estimates that obscure which jobs actually matter for strategy. + +No job assigned to many candidates. The team treats job mapping as optional; non-mapped candidates get prioritized on volume of requests or stakeholder preference. + +Job-impact precision theater. Numerical scores for job impact (Job B: 8/10) when the underlying assessment is qualitative. Decisions look quantitative but are not. + +Forcing all decisions through JTBD. Some decisions (technical migrations, strategic bets) do not benefit from JTBD framing. Force-fitting produces bad decisions. + +JTBD as cover for predetermined prioritization. The team ranks items by JTBD theater after deciding what to prioritize on other grounds. The framework becomes documentation rather than decision input. + +--- + +## Methodology-level choices that stay in the public skill + +The job-led prioritization frame. Identifying jobs done badly. Mapping candidates to jobs. The "no job, no priority" discipline. Strategic weighting across jobs. The in-flight work review. Avoiding JTBD-religion. Worked prioritization example. Common failures. + +## Implementation choices that stay internal + +Specific roadmap-tracking tools. Specific scoring rubrics for job impact. Specific stakeholder-review formats. Specific job-strategic-weight reviews. The team's own conventions for prioritization meetings. These vary by team and tooling. diff --git a/skills/jtbd-framing/references/common-jtbd-failures.md b/skills/jtbd-framing/references/common-jtbd-failures.md new file mode 100644 index 0000000..a36a25e --- /dev/null +++ b/skills/jtbd-framing/references/common-jtbd-failures.md @@ -0,0 +1,166 @@ +# Common JTBD failures + +Nine-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most JTBD failures share a single root, which is treating JTBD vocabulary as a substitute for analytical work. + +--- + +## Failure 1: We did the JTBD workshop but nothing changed in our roadmap + +Symptom. A workshop was held. Job statements were produced. The wall has Post-its. The next quarter's roadmap looks the same as the prior quarter's. + +Diagnosis. Job-statement workshop as deliverable. The workshop became the artifact; the analytical work that should have followed never happened. + +Cure. Treat job statements as analytical input, not as workshop output. Re-evaluate roadmap candidates against the jobs. Apply the "no job, no priority" discipline. The roadmap should look different than it would have looked without the JTBD work; if it does not, the work is ritual. + +Prevention. Do not run JTBD workshops as standalone events. Pair the workshop with prioritization or positioning work that uses the job statements as input. Without downstream application, the workshop produces ritual. + +--- + +## Failure 2: Our job statements all sound the same + +Symptom. Multiple job statements share similar situations, motivations, or outcomes. They are hard to distinguish. + +Diagnosis. Generic job statements; not grounded in specific struggling moments. The statements were written from intuition rather than from interview data. + +Cure. Re-ground in interview data. Each job should be traceable to specific moments in specific interviews. Statements that cannot be traced are projections; rewrite from the ground up. + +Prevention. Job statements emerge from clustering, not from whiteboard sessions. The clustering work surfaces the distinctions; whiteboard sessions tend to produce homogeneous statements. + +--- + +## Failure 3: Our jobs read like feature requests + +Symptom. Job statements describe what users want from the product, not what users are trying to accomplish. + +Examples that fail. + +- "When using the dashboard, I want to see all my metrics on one screen." +- "When in the settings page, I want to configure permissions easily." + +The motivations and outcomes describe product features, not job-doing. + +Diagnosis. Product-bound job statements. The motivation is bound to the product; the outcome is feature output. + +Cure. Apply the product-independence test. The motivation should make sense without naming any specific product. If the user is "in the dashboard," they are using a product; the underlying job is what they are trying to accomplish that brought them to the dashboard. + +Prevention. During job-statement writing, check each statement: could this make sense if the user had no product to use? If no, rewrite the motivation and outcome to describe the underlying job. + +--- + +## Failure 4: We have personas and jobs and they contradict each other + +Symptom. The team has both demographic personas and JTBD job statements. Decisions get made differently depending on which framework the conversation invokes. + +Diagnosis. Personas are demographic; jobs are situational. They serve different purposes. Conflict often signals confusion about which framework drives which decisions. + +Cure. Decide the role of each framework. JTBD is usually better for product decisions (what to build, how to prioritize); demographic personas are sometimes useful for marketing audience targeting (who to advertise to). Use each where it adds clarity; do not require both for every decision. + +Prevention. When introducing JTBD, surface the relationship to existing personas. If personas are not driving decisions, consider deprecating them. If personas are useful for specific marketing work, keep them but separate from product decision-making. + +--- + +## Failure 5: JTBD says we should build everything + +Symptom. Job statements identify many job-improvement opportunities. The team cannot pick. The roadmap becomes a list of all the jobs to address. + +Diagnosis. Without prioritization across jobs, JTBD identifies opportunities but does not pick. The framework is doing its discovery work; it is not doing prioritization work. + +Cure. Pair JTBD with strategic weighting (which jobs matter most for the strategy?), capacity constraints (what can the team actually deliver?), and impact estimation (which job improvements move the needle most?). JTBD informs prioritization but does not replace prioritization frameworks. + +Prevention. When applying JTBD to roadmap prioritization, surface the strategic-weight question explicitly. Some jobs matter more than others; the team's strategy decides which ones. + +--- + +## Failure 6: We dropped JTBD because it became theater + +Symptom. The team adopted JTBD; produced workshop artifacts; never used them in decisions; and concluded JTBD does not work. + +Diagnosis. JTBD as ritual produced ritual. The framework was applied without the analytical work. + +Cure. Reintroduce JTBD as analytical tool, not as ritual. Apply where it earns its keep (discovery, prioritization, positioning). Skip the artifacts that decorate without informing decisions. Demonstrate the value through specific decisions JTBD informed. + +Prevention. When introducing JTBD, frame it as a tool for specific decisions, not as a methodology to be adopted org-wide. Start with one application (one discovery cycle, one prioritization debate) and show value before expanding. + +--- + +## Failure 7: Our job statements are functional only + +Symptom. Job statements describe mechanical tasks. The product strategy prioritizes functional features. The product wins on functional dimension and loses to alternatives on emotional and social. + +Diagnosis. Functional-only synthesis. The interview prompts and synthesis stayed at the functional dimension; emotional and social dimensions were not surfaced. + +Cure. Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing job statements. Re-evaluate strategy considering all three dimensions. + +Prevention. Interview structure should explicitly prompt for all three dimensions. Synthesis should surface all three. Single-dimension job statements are usually a sign that prompts or synthesis missed dimensions. + +--- + +## Failure 8: We cannot agree on the job + +Symptom. Different team members describe the user's job differently. The team debates the framing; the framing does not converge. + +Diagnosis. Often signals different segments with different jobs. The team is right that there is more than one job; they are wrong to think there should be one consensus job. + +Cure. Surface the segment differences. The same product may serve different jobs for different segments. Naming the segments and their distinct jobs resolves the disagreement and improves strategy. + +Prevention. When defining jobs, ask explicitly: do all target users share this job, or does it differ across segments? Often the answer is "differs"; surface the segments rather than forcing consensus. + +--- + +## Failure 9: Our marketing copy uses JTBD vocabulary but our product does not + +Symptom. Marketing positioning describes the job the product helps users accomplish. The product itself is built around feature-list thinking. Users adopt expecting one experience and encounter another. + +Diagnosis. Positioning-product gap. The marketing claim is not load-bearing in product decisions; product decisions are still made on feature-list grounds. + +Cure. Either align product decisions to the JTBD positioning (apply JTBD to prioritization), or revise the positioning to match what the product actually does. The mismatch erodes trust over time. + +Prevention. When introducing JTBD-led positioning, simultaneously apply JTBD to product strategy. Positioning that describes what the product is becoming should drive what the product becomes. + +--- + +## Failure 10: JTBD vocabulary substituted for analytical work + +Symptom. The team uses JTBD language ("the job," "struggling moment," "hire criteria") in conversations but cannot trace decisions to specific JTBD analyses. + +Diagnosis. Vocabulary without analysis is ritual. The framework provides language; the language does not produce decisions on its own. + +Cure. Audit recent decisions: which were grounded in JTBD analysis (specific job statements, specific hire/fire criteria, specific user research)? Which used JTBD vocabulary as decoration around decisions made on other grounds? Re-anchor in analytical work. + +Prevention. When the team uses JTBD vocabulary, surface the underlying analytical work explicitly. "What job is this serving?" should produce a specific job statement traceable to research, not a hand-wavy answer. + +--- + +## Failure 11: Force-fitting JTBD where it does not help + +Symptom. Every product question gets framed in JTBD. Even questions where the framing adds no clarity. + +Diagnosis. JTBD as mandate. The framework gets applied universally; tax for the team; signal-to-noise drops. + +Cure. Use JTBD where it earns its keep. Some questions (technical migrations, infrastructure decisions, urgent bug fixes) do not benefit from JTBD framing. Apply other frameworks where they fit better; apply JTBD where it fits. + +Prevention. Establish that JTBD is one tool among many. Frame the question first; then pick the framework. Do not start with the framework and look for questions to apply it to. + +--- + +## The cross-cutting pattern + +Most JTBD failures share a single root: treating JTBD vocabulary as a substitute for analytical work. + +The vocabulary is easy: "job," "struggling moment," "hire criteria," "fire criteria," "functional, emotional, social dimensions." Teams adopt the vocabulary and signal that they have adopted JTBD. + +The analytical work is hard: structured interviews, struggling-moment grounding, clustering across users, naming jobs from data, surfacing all three dimensions, applying the framework to specific decisions, validating that the analysis informs decisions. + +When the vocabulary is adopted without the analytical work, JTBD produces ritual. When the analytical work is done with discipline, JTBD produces decisions and the vocabulary is incidental. + +The fix for almost any JTBD failure starts with the same question: where is the analytical work happening, and what decisions is it informing? If the answers are clear, the framework is doing its job. If the answers are vague, the framework is ritual. + +--- + +## Methodology-level choices that stay in the public skill + +The eleven failure patterns with diagnoses and cures. The cross-cutting vocabulary-vs-analysis pattern. The discipline of using JTBD where it earns its keep. + +## Implementation choices that stay internal + +Specific JTBD-application audits. Specific reviewer training on failure detection. Specific tooling that surfaces JTBD ritual vs analytical use. The team's own conventions for catching ritual before it spreads. These vary by team. diff --git a/skills/jtbd-framing/references/functional-emotional-social-dimensions.md b/skills/jtbd-framing/references/functional-emotional-social-dimensions.md new file mode 100644 index 0000000..4460b0b --- /dev/null +++ b/skills/jtbd-framing/references/functional-emotional-social-dimensions.md @@ -0,0 +1,201 @@ +# Functional, emotional, and social dimensions of jobs + +Jobs have three dimensions. Strong JTBD work surfaces all three; weak work treats jobs as functional only. The omission of emotional and social dimensions is one of the most common JTBD failure modes. + +--- + +## The three dimensions + +### Functional + +What the user is mechanically trying to accomplish. + +Worked examples. + +- "Assemble the quarterly board deck." +- "Track team OKR progress." +- "Onboard a new engineer to the codebase." +- "Prepare a customer-facing announcement for a feature launch." +- "Reconcile vendor payments at month-end." + +Characteristics. + +- Describable in task language. +- Often the easiest dimension to surface in interviews. +- Often the dimension product teams default to. + +--- + +### Emotional + +How the user feels (or wants to feel) doing the job. + +Worked examples. + +- "Confident that the deck represents the team's actual progress, not a polished version." +- "In control of the OKR check-in cadence, not behind on it." +- "Helpful to the new engineer without becoming their full-time guide." +- "Comfortable that the announcement will not surprise anyone in a way that lands badly." +- "Confident that the reconciliation is correct without spending the whole week verifying." + +Characteristics. + +- Describes the user's internal experience. +- Often surfaces through how users describe what went well or badly. +- Distinguishes products that feel good to use from products that work mechanically but feel exhausting. + +--- + +### Social + +How the user wants to be perceived doing the job. + +Worked examples. + +- "Seen by the board as a competent leader who knows the numbers." +- "Seen by direct reports as someone who follows through on commitments." +- "Seen by the new engineer as a senior who invested in their onboarding." +- "Seen by customers as transparent and proactive, not evasive." +- "Seen by audit as someone whose work the team can trust without re-checking." + +Characteristics. + +- Describes how the user wants others to perceive their work. +- Often the most overlooked dimension. +- Drives positioning more than the other two dimensions. + +--- + +## Why three dimensions matter + +Products that win on functional alone often lose to alternatives that also serve emotional and social. + +Worked example. Two analytics tools serving the same functional job. + +- Tool A: technically thorough, full-featured, hard to learn, intimidating-feeling. Functional excellence; weak emotional dimension. +- Tool B: focused on the specific job, faster to confidence, feels manageable. Slightly less functional power; stronger emotional dimension. + +For users who could complete the job with either, Tool B often wins. The emotional dimension (feeling in control, confidence) tipped the decision even though Tool A's functional dimension was technically stronger. + +Worked example, social dimension. A board reporting tool serving CFOs. + +- Tool A: produces correct numbers; layout is utilitarian. +- Tool B: produces the same numbers; layout signals "this CFO knows their numbers" through design. + +The social dimension (how the CFO is perceived presenting from this tool) tips many decisions. Tool B is hired in part because it makes the CFO look good in front of the board. + +--- + +## Surfacing emotional and social dimensions in interviews + +Emotional and social dimensions often surface only when the interview prompts for them. + +Functional prompts. "Walk me through the task. What did you do?" + +Emotional prompts. "How did you feel doing this? What was the most stressful part? When did you feel relieved?" + +Social prompts. "Who else was watching this work? How did you want to come across to them? What did you do specifically because of how it would look?" + +The interview discipline. Surface all three dimensions; do not assume the functional dimension is the whole job. Many users will not volunteer emotional or social dimensions; the prompts surface them. + +--- + +## When functional alone is sufficient + +Some jobs are dominantly functional and the emotional/social dimensions are minor. + +Worked example. A backup utility that runs in the background. The functional dimension (data is backed up correctly) is the whole job; the user does not have an emotional relationship with the tool and is not perceived doing it. + +The discipline. Some products are appropriately functional-only. The team's job is to recognize when the dimensions matter and when they do not. Force-fitting emotional and social dimensions onto purely functional jobs produces false signal. + +--- + +## Functional-only failure mode + +The most common JTBD failure: surfacing only the functional dimension. + +The pattern. Job statements describe what the user is mechanically doing; the team prioritizes functional features; the product wins on functional excellence and loses on emotional and social. + +The cure. Re-interview a subset of users with emotional and social prompts. Add the dimensions to existing jobs. Re-evaluate strategy considering all three dimensions. + +The signal. Products that are technically excellent but lose to "lesser" alternatives often have an emotional or social dimension the strategy missed. Investigate. + +--- + +## Emotional dimension and product feel + +The emotional dimension shows up in product feel: the way using the product makes users feel. + +Examples of emotional dimensions in product design. + +- A complex configuration interface vs a guided wizard. Both can be functionally equivalent; the wizard often serves the emotional dimension of "feeling in control rather than overwhelmed." +- An error message that explains and offers recovery vs one that just reports the failure. Both can be technically accurate; the explaining one serves the emotional dimension of "feeling supported rather than stuck." +- A success state that celebrates the milestone vs one that proceeds silently. Both can be functionally complete; the celebrating one serves the emotional dimension of "feeling progress rather than grinding." + +The discipline. Product designers often instinctively address emotional dimensions; the JTBD work makes this explicit and prioritizable. Emotional dimension can be a deliberate strategy choice rather than a designer's intuition. + +--- + +## Social dimension and positioning + +The social dimension informs positioning more than the other dimensions. + +Examples of social dimensions in positioning. + +- "Used by senior engineers at companies that ship reliable software." (positions the user as a senior engineer at a reliable company.) +- "The board reporting tool CFOs at high-growth startups trust." (positions the CFO as someone who works for a high-growth startup.) +- "Built for product teams that ship every week." (positions the product manager as part of a high-velocity team.) + +Why social dimension is positioning-relevant. + +- Users want to be perceived as belonging to the kind of teams the positioning describes. +- Positioning that names the social dimension creates affinity; positioning that names only functional features competes on feature comparison. +- The social dimension is durable; functional dimensions can be matched, social dimensions are harder to copy. + +The discipline. Positioning work should explicitly identify the social dimension of the jobs the product serves. Positioning that ignores social dimension misses one of the strongest tools available. + +--- + +## Worked synthesis combining all three dimensions + +A job statement enriched with all three dimensions: + +Job: "When my team is rolling out a new feature and I need to communicate it to customers, I want to write a clear announcement that explains what changed and why it matters, so I can ship the rollout without flooding support with confusion." + +Functional dimension: Write the announcement, distribute it to customers, prepare support for incoming questions. + +Emotional dimension: Confident that the announcement will land well, not anxious that it will trigger a wave of confused tickets, in control of the rollout rather than reactive to its fallout. + +Social dimension: Seen by the team as someone who handles rollouts smoothly, seen by customers as a brand that communicates clearly about changes, seen by support team as someone whose announcements reduce their workload rather than create it. + +Product implications. A tool that helps with this job needs to: + +- Functionally: support drafting, distribution, and support-team coordination. +- Emotionally: provide confidence-inducing review (preview tools, sentiment checks, changelog patterns). +- Socially: produce announcements that carry the brand voice the user wants associated with their rollouts. + +The three-dimensional analysis surfaces product needs the functional analysis alone would miss. + +--- + +## Common dimension-related failures + +Functional-only synthesis. Job statements describe mechanical tasks; strategy prioritizes functional features; product loses on feel. + +Decorative emotional dimension. Adding "feels good" without specifying which emotional state the product should support. The dimension exists on paper but does not drive design decisions. + +Missing social dimension. Strategy and positioning work that ignores how users want to be perceived. Positioning ends up generic; product fails to create affinity. + +Force-fitting all three to every job. Some jobs are functional-dominant. Adding emotional and social dimensions where they do not matter produces noise. + +Treating dimensions as separate jobs. Functional, emotional, and social dimensions are aspects of the same job, not separate jobs. Treating them separately produces fragmented strategy. + +--- + +## Methodology-level choices that stay in the public skill + +The three dimensions and their characteristics. Worked examples per dimension. Interview prompts per dimension. The functional-only failure mode. Emotional dimension and product feel. Social dimension and positioning. Worked three-dimensional synthesis. Common failures. + +## Implementation choices that stay internal + +Specific interview prompt templates per dimension. Specific synthesis templates that capture all three. Specific design-review patterns that check for emotional dimension. Specific positioning frameworks that lead with social dimension. These vary by team and design practice. diff --git a/skills/jtbd-framing/references/hire-and-fire-criteria.md b/skills/jtbd-framing/references/hire-and-fire-criteria.md new file mode 100644 index 0000000..d3aee67 --- /dev/null +++ b/skills/jtbd-framing/references/hire-and-fire-criteria.md @@ -0,0 +1,189 @@ +# Hire and fire criteria + +Why users adopt a product (hire), why they switch away (fire). The two questions ground JTBD in real decisions users make. + +Hire and fire criteria are the JTBD methodology's most actionable contribution to product strategy. They surface what the product needs to be excellent at to win adoption (hire) and what the product needs to maintain to retain users (fire). The two are often different; products that win on hire criteria can lose on fire criteria. + +--- + +## Hire criteria + +What makes a user adopt a product. + +The components. + +- The struggling moment the user is trying to solve. +- The alternatives they considered or tried first. +- What made the chosen product the answer (vs the alternatives). +- The expected job output: what the user expected to accomplish with the product. + +Worked example. A PM user adopting a new analytics tool: + +- Struggling moment: "I was spending hours every week assembling product metrics from three different sources before standup, and I was always uncertain whether I had the right slice." +- Alternatives considered: "Continued the manual spreadsheet approach. Tried to extend the existing BI tool. Considered building an internal dashboard." +- Why this product won: "It connected to all three sources out of the box, the slice I needed was a 30-second config, and the team could share the same view." +- Expected job output: "I would walk into standup with the metrics ready, with no manual reconciliation work the night before." + +The discovery prompt. "Tell me about the moment you decided to start using [product]. What were you doing before? What made you switch?" + +--- + +## Fire criteria + +What makes a user switch away. + +The components. + +- The struggling moment that recurred even with the chosen product. +- The alternative that started looking better. +- What tipped the user from "considering switching" to "switching." +- The job output that the chosen product failed to deliver consistently. + +Worked example. A PM user switching away from an analytics tool: + +- Struggling moment: "Once we hit cross-source aggregations the basic config could not handle, I was back to manual workarounds." +- Alternative looking better: "A team I respect started using a different tool that handled cross-source natively." +- Tipping point: "When I had to rebuild a report three weeks in a row because the workaround broke whenever the source schemas changed." +- Failed job output: "The 30-second-config promise did not hold for the analyses that mattered most." + +The discovery prompt. "If you switched away from [product] tomorrow, what would the trigger be? What would the alternative need to do that [product] does not?" + +For users who have actually switched: "What was the moment you decided to switch away?" + +--- + +## Why hire and fire are often different + +Hire criteria reveal what the product needs to be excellent at to win adoption. Fire criteria reveal what the product needs to maintain to retain users. The asymmetry is consequential. + +Examples of the asymmetry. + +- A product that wins adoption with a fast onboarding (hire criterion) can lose users to depth limitations once they get past onboarding (fire criterion). The product needs both: fast onboarding AND depth that handles harder cases. +- A product that wins adoption with a single integration (hire criterion) can lose users when their tooling stack expands and the product does not keep up (fire criterion). The product needs both: a strong landing integration AND breadth as users grow. +- A product that wins adoption with a low price (hire criterion) can lose users when their budget expands and competitors offer more value at higher tiers (fire criterion). The product needs both: accessible entry AND value at higher tiers. + +The implication. Strategy work that focuses only on hire criteria builds for adoption. Strategy work that focuses only on fire criteria builds for retention. Mature strategy addresses both, often through different parts of the product or different lifecycle stages. + +--- + +## Recent-switch interview discipline + +Users who recently switched (in either direction) are particularly rich for JTBD interviews. + +Why recent switches matter. + +- The user remembers the specific moment of the switch decision; older switches get smoothed into abstractions. +- The user remembers the alternatives they considered, the criteria they used, the moment of tipping. +- The data is grounded in real decisions, not hypothetical preferences. + +The recruiting target. Users who switched in the last 30-90 days are the highest-value recruits for hire/fire interviews. Users who switched 6+ months ago provide weaker data. + +The interview structure. + +- Walk through the situation that prompted the switch consideration. +- Identify the alternatives evaluated. +- Surface the criteria the user used to evaluate. +- Identify the tipping moment. +- Compare expected vs realized outcomes after the switch. + +--- + +## Hire and fire across segments + +Different segments often have different hire and fire criteria. + +Worked example. A team productivity SaaS: + +- Small-team segment: hire criterion is "fast setup; works without admin"; fire criterion is "team grew and the product feels limiting." +- Mid-size segment: hire criterion is "supports our existing roles and permissions"; fire criterion is "missing reporting and audit features as we standardize." +- Enterprise segment: hire criterion is "compliance and security pass our review"; fire criterion is "vendor responsiveness during incidents." + +The discipline. Surface segment differences in hire and fire criteria explicitly. A product that wins on small-team hire criteria but loses on mid-size fire criteria has a known retention pattern that strategy must address. + +--- + +## The "why didn't you switch sooner" question + +A specific prompt that reveals the friction barrier to switching. + +The prompt. "Looking back, why didn't you switch sooner?" + +What it surfaces. + +- The switching cost the user had to overcome (data migration, team retraining, contract obligations). +- The alternatives that almost won earlier but did not (and why). +- The accumulated frustration that finally broke through the inertia. + +Why it matters. + +- High switching costs protect incumbents. Users tolerate friction longer when switching is expensive. +- The pattern of frustration accumulation reveals which fire criteria are load-bearing (the ones users finally cannot tolerate). +- The almost-won alternatives reveal what would have been compelling enough earlier. + +--- + +## Hire and fire criteria for non-switching users + +Not every user has switched. Some users are at the start of their relationship with the product; others have used it for years without considering alternatives. + +For new users: focus on hire criteria. The recent decision is the adoption decision; the fire criteria are hypothetical. + +For long-tenured users: focus on fire criteria. The hypothetical "what would make you switch" reveals the latent fire criteria even without a switch event. The product can use these to address fire risks before they become switch events. + +For users who tried and abandoned: rich data. They evaluated, found the product wanting, and stuck with the prior alternative. The reasons reveal both hire criteria the product failed and fire criteria for the alternative they kept. + +--- + +## Patterns across hire criteria + +Common patterns in hire criteria across product domains. + +Speed-to-value. Users hire products that get them to first value quickly. Long onboarding loses adoption races; fast onboarding wins. + +Specific job fit. Users hire products that look like they will solve the specific job. Generic products that "could be used for many things" lose to specific products that "solve this exact problem." + +Confidence in continuity. Users hire products they trust will be there in 2 years. Established products win on this; startups have to compensate with other criteria. + +Workflow continuity. Users hire products that fit their existing workflows. Products that demand workflow change face higher hire bars. + +Recommendation chain. Users hire products that someone they trust recommended. Word-of-mouth is often a stronger hire criterion than feature comparison. + +--- + +## Patterns across fire criteria + +Common patterns in fire criteria across product domains. + +Reliability degradation. Users fire products that become unreliable. A product that ships bugs faster than it ships fixes loses users. + +Scaling friction. Users fire products that get harder to use as they grow. The product that was great for 5 users may be painful at 50. + +Vendor responsiveness. Users fire products whose vendors stop responding. Support quality, account management, and incident response all matter. + +Pricing trajectory. Users fire products whose pricing escalates faster than the value they get. Enterprise tiers that gate basic functionality drive fire decisions. + +Competitive pressure. Users fire products when alternatives reach feature parity plus advantage. Products that stop innovating lose to products that overtake them. + +--- + +## Common hire-and-fire failures + +Asking only about hire. The team interviews about adoption decisions but never about switch decisions. The strategy biases toward adoption; retention concerns surface late. + +Asking only about fire. The team focuses on churn analysis without understanding hire criteria. New customer acquisition struggles because the team does not know what wins adoption. + +Treating hire and fire as the same. The team assumes the criteria match. Strategy ends up optimized for hire-with-no-fire-attention or vice versa. + +Hypothetical-only fire data. Long-tenured users describing what they "would" switch over. Useful but weaker than real-switch data. + +Ignoring segment differences. Hire and fire criteria collapsed across segments. Strategy that works for one segment fails for another. + +--- + +## Methodology-level choices that stay in the public skill + +The hire and fire criteria components. Why they are often different. The recent-switch interview discipline. Hire and fire across segments. The "why didn't you switch sooner" question. Hire and fire for non-switching users. Patterns across hire and fire criteria. Common failures. + +## Implementation choices that stay internal + +Specific interview templates for hire and fire interviews. Specific recruitment criteria for recent switchers. Specific synthesis tooling for hire and fire data. The team's own conventions for hire-fire balance in strategy work. These vary by team and research practice. diff --git a/skills/jtbd-framing/references/identifying-struggling-moments.md b/skills/jtbd-framing/references/identifying-struggling-moments.md new file mode 100644 index 0000000..a7e8590 --- /dev/null +++ b/skills/jtbd-framing/references/identifying-struggling-moments.md @@ -0,0 +1,176 @@ +# Identifying struggling moments + +Jobs become visible at struggling moments: when the user's current solution is failing them, when alternatives feel inadequate, when they would prefer a different way of doing the job. + +The struggling moment is the JTBD methodology's most direct contribution to discovery research. Most discovery interviews surface preferences and feature requests; well-structured JTBD interviews surface struggling moments, which produce richer data and clearer jobs. + +--- + +## What a struggling moment is + +A specific moment in time when: + +- The user encountered friction in trying to accomplish something. +- The current approach failed them or felt inadequate. +- They considered or wished for an alternative. +- They built a workaround or accepted suboptimal output. + +Strong struggling-moment examples. + +- "Last Tuesday I lost an hour assembling the board metrics from three different dashboards because none of them had the slice I needed. I ended up exporting CSVs and combining them manually, and then second-guessing whether I had pulled the right data." +- "When the customer escalation came in at 9pm, I was at dinner and tried to triage from my phone, but the support tool's mobile experience was unusable. I had to go back to my laptop and the whole evening was disrupted." +- "Last quarter I spent the whole onboarding week pair-programming with the new engineer because our docs assumed knowledge they did not have, and I could not point them anywhere that would work without me there." + +Each example names a specific time, a specific friction, and the workaround or impact. + +Weak struggling-moment examples. + +- "I wish dashboards were better." (general; not a moment) +- "It would be nice if the support tool was more mobile-friendly." (preference; not a friction-in-context) +- "Onboarding new engineers takes a lot of time." (abstracted; no specific moment) + +--- + +## Discovery prompts that surface struggling moments + +Specific prompts produce specific data. + +Prompts that work. + +- "Walk me through the last time you did [task]. What was hardest about it?" +- "What was the most recent time you wished you had a better way of doing [task]?" +- "When was the last time [task] went badly? What happened?" +- "Describe the last time you considered switching from [current tool] to something else. What triggered that?" +- "What's something you do that takes longer than it should? When was the last time it cost you?" + +The prompts share two characteristics: they ground in recent specific moments, and they invite the user to describe friction without pre-judging it. + +Prompts that fail. + +- "What features would you like to see?" (produces feature requests, not jobs) +- "How do you usually do [task]?" (produces abstracted descriptions, not moments) +- "Are you satisfied with [tool]?" (produces preferences, not behaviors) +- "What would your dream solution look like?" (produces fiction, not data) + +--- + +## The recency bias as a feature + +JTBD interviewing exploits recency. Recent moments are remembered with specifics; older moments get smoothed into abstractions. + +The methodology. Ask about the last time, the most recent occurrence, the situation that happened this week. Users can recall details from recent moments that they cannot recall from older ones. The details are where the job lives. + +The trade-off. Recent moments may not represent the dominant pattern; the most recent occurrence may be an outlier. The mitigation is interview volume: 8-15 interviews each grounded in recent moments produce a pattern; one interview grounded in one moment is one data point. + +--- + +## Pattern recognition across users + +Across many users, struggling moments cluster. The same kinds of friction recur. The clusters reveal the jobs that are not currently being done well. + +The clustering work. + +- Across interviews, struggling moments get tagged with what the user was trying to accomplish, what failed, what alternative they wished for. +- Tags cluster: multiple users describe the same kind of friction in similar contexts. +- Each cluster suggests a job: the underlying thing users were trying to do that the cluster's friction was blocking. + +Worked example. Across 12 interviews with PM users: + +- Multiple users describe assembling data from multiple dashboards before quarterly business reviews. +- Multiple describe building Excel exports because their dashboard tool does not produce the right slice. +- Multiple describe second-guessing whether the data they assembled is correct. +- Multiple describe the time pressure and disruption these workarounds create. + +The cluster suggests a job: "When preparing for quarterly business reviews, I want to assemble cross-source data into a coherent narrative I can defend, so I can answer the board's questions confidently without spending the night before reconciling spreadsheets." + +The job emerges from the moments; the moments came from the prompts. + +--- + +## Distinguishing struggling moments from venting + +Not every friction users describe is a struggling moment for product purposes. + +Struggling moments. + +- Specific friction that interferes with the user accomplishing something they care about. +- The friction is reproducible (other users encounter similar friction in similar contexts). +- The friction has a workaround or alternative the user has tried. + +Venting that is not a struggling moment. + +- General complaint without specific friction context ("everything is too slow"). +- Preference for cosmetic differences ("I do not like the color"). +- One-off issues with no pattern across users. + +The discipline. Tag specific friction; do not over-weight venting. The struggling moments that drive product decisions are the ones with reproducible context across users. + +--- + +## The "what would you have done differently" question + +A specific prompt that surfaces both struggling moments and the implicit alternative. + +The prompt. "If you could have done [task] any way you wanted, how would you have done it?" + +What it surfaces. + +- The user's mental model of the ideal approach. +- The gap between current tools and the user's mental model. +- Sometimes the alternative tools the user has used or considered. + +What it does not surface. + +- Always-correct product solutions. Users often describe alternatives that would not actually work; the value is in understanding their mental model, not adopting their proposed solution. + +The interpretation. The user's described "would have done differently" is informative about the gap, not prescriptive about the fix. Synthesis interprets the gap and proposes product responses; users do not directly produce the responses. + +--- + +## When users do not have struggling moments + +Sometimes the interview reveals that the user is not struggling with the area the team is researching. They have a workable approach; they would not change it; the friction the team thought existed does not exist for this user. + +The honest interpretation. The team's hypothesis about a job that needs better tooling may be wrong, or this user may not be in the target segment for the job, or the job may be done well enough by existing solutions that there is no struggle. + +The discipline. Surface this finding rather than discounting it. "Some users are not struggling here" is data; ignoring it because it does not match the team's hypothesis is confirmation bias. + +--- + +## Struggling moments by product type + +Different product domains surface different kinds of struggling moments. + +Tools that fit into existing workflows. Struggling moments are workflow disruptions: the moment the existing tool failed and the user had to switch to a workaround. + +Tools that change workflows. Struggling moments are transition points: the moment the user realized the old workflow was unsustainable and considered changing it. + +Consumer products. Struggling moments are often emotional: the moment the user felt frustrated, blocked, or in conflict with their own goals. + +B2B platforms. Struggling moments often involve coordination: the moment the user could not align with a colleague, customer, or vendor because the tooling did not support the coordination. + +The discipline. Tailor interview prompts to the kind of struggling moment most likely in the product domain; do not assume one prompt works for all domains. + +--- + +## Common struggling-moment failures + +Eliciting preferences instead of moments. "What features do you wish existed?" produces preferences. Reframe: "What's the last task that took longer than it should have?" + +Abstracting moments to patterns prematurely. Users describing "what I usually do" instead of specific recent moments. Bring them back to the last specific time. + +Ignoring countervailing data. Users who do not struggle in the researched area. Their data is signal; do not discard it. + +Treating venting as struggling moments. General complaint without specific context does not produce jobs. + +Over-relying on the "wish" question. Users describe ideal alternatives that do not necessarily reflect what would work; treat as gap-revealing data, not as product specs. + +--- + +## Methodology-level choices that stay in the public skill + +What a struggling moment is and is not. Discovery prompts that work and fail. The recency bias as a feature. Pattern recognition across users. Distinguishing struggling moments from venting. The "what would you have done differently" question. When users do not struggle. Domain-specific struggling moment patterns. Common failures. + +## Implementation choices that stay internal + +Specific interview templates and discussion guides. Specific recording and tagging conventions. Specific recruitment criteria for who the team interviews. The team's own conventions for interview length and structure. These vary by team and research practice. diff --git a/skills/jtbd-framing/references/job-statement-structure-patterns.md b/skills/jtbd-framing/references/job-statement-structure-patterns.md new file mode 100644 index 0000000..663b49a --- /dev/null +++ b/skills/jtbd-framing/references/job-statement-structure-patterns.md @@ -0,0 +1,198 @@ +# Job statement structure patterns + +The canonical structure: "When [situation], I want to [motivation], so I can [outcome]." Each level demands specificity. Vague levels produce job statements that drive nothing. + +--- + +## The three levels + +### Situation + +The context, trigger, or moment when the job becomes active. + +Strong situation patterns. + +- "When my team is rolling out a new feature and I need to communicate it to customers..." +- "When I am preparing the quarterly board deck the night before the meeting..." +- "When I get a customer escalation outside of business hours..." +- "When a new engineer joins my team mid-quarter..." + +Weak situation patterns. + +- "When I am at work..." (too broad) +- "As a marketing manager..." (demographic, not situational) +- "Whenever I need to communicate..." (lacks the specific trigger) + +Why specificity matters. Situations name the moment when the job activates. Different situations can produce different jobs even for the same user; collapsing situations together loses the patterns. + +--- + +### Motivation + +What the user is trying to do in that situation. + +Strong motivation patterns. + +- "...I want to write a clear announcement that explains what changed and why it matters..." +- "...I want to assemble revenue and engagement data into a coherent narrative..." +- "...I want to triage the escalation and respond without disrupting my evening too much..." +- "...I want to onboard the new engineer to our codebase without becoming their full-time guide..." + +Weak motivation patterns. + +- "...I want to do my job better..." (too vague) +- "...I want to use feature X..." (motivation is a feature, not a goal) +- "...I want to be more productive..." (universal; not actionable) + +Why specificity matters. Motivations name what the user is trying to accomplish in their own words. The motivation should describe the job the user is doing, not the product the user is using. "I want to use Slack to communicate" is not a motivation; "I want to coordinate with the team on the rollout" is. + +The product-independence test. A good motivation should make sense without naming any specific product. If the motivation is bound to the product, it has slid into feature framing. + +--- + +### Outcome + +What success looks like; what the user is trying to achieve by doing the job. + +Strong outcome patterns. + +- "...so I can ship the rollout without flooding support with confusion." +- "...so I can answer the board's likely questions before they ask them." +- "...so I can address the customer's concern while still being present at home." +- "...so the new engineer can ship their first PR within two weeks without depending on me for every question." + +Weak outcome patterns. + +- "...so I can succeed." (too vague) +- "...so I can use the feature." (outcome is feature use, not user goal) +- "...so I can be efficient." (universal; not specific) + +Why specificity matters. Outcomes name what success looks like in the user's terms. Different outcomes for the same situation+motivation can produce different jobs. The outcome anchors the job in the user's success criteria, not the product's metrics. + +--- + +## Worked examples across product domains + +### B2B SaaS for engineering teams + +- "When a production incident is detected and I am the on-call engineer, I want to identify the root cause and roll back if needed, so I can restore service before the SLO breach without escalating unnecessarily." + +### Consumer fitness app + +- "When I have 30 minutes between meetings and I want to use the time well, I want to do a workout that fits the time budget and uses the equipment I have at hand, so I can stay consistent without skipping when life gets busy." + +### Internal tools for finance teams + +- "When the month-end close is starting and I need to reconcile vendor payments, I want to identify discrepancies and document explanations, so the auditors can review without follow-up questions." + +### Creator-tools SaaS + +- "When I am editing a podcast episode the day before publication, I want to remove background noise and balance audio levels across speakers, so the episode sounds professional without spending another two hours on mastering." + +Each example specifies the moment, what the user is trying to do, and what success looks like. Each is product-independent at the motivation level: the user is trying to accomplish the job regardless of which tool they use. + +--- + +## Common structural failures + +### Vague situations + +Failure. "When I am at work..." + +Diagnosis. The situation does not name the trigger that activates the job. Most users are at work most of the time; the situation should name the specific moment. + +Cure. Re-ground in interview data. What was the user actually doing when this job became urgent? Use that moment. + +--- + +### Motivation as feature request + +Failure. "...I want to use the dashboard..." + +Diagnosis. Motivation is a feature, not a goal. The user does not want to use the dashboard; they want to accomplish something the dashboard supports. + +Cure. Ask the why-question. Why does the user want to use the dashboard? What are they trying to learn from it? The answer is the motivation. + +--- + +### Outcome as feature output + +Failure. "...so I can see the metrics." + +Diagnosis. Outcome is feature output, not user success. Seeing the metrics is intermediate; the user wants something the metrics enable. + +Cure. Ask another why. Why does the user want to see the metrics? What does seeing the metrics enable? The answer is the outcome. + +--- + +### Demographic as situation + +Failure. "As a marketing manager..." + +Diagnosis. Demographic, not situational. Different marketing managers in different moments have different jobs. + +Cure. Replace with the specific moment. "When the marketing manager is preparing the quarterly campaign retrospective..." + +--- + +### Universal as motivation or outcome + +Failure. "...I want to be more productive, so I can be efficient." + +Diagnosis. Universal language; could apply to any user, any job. Says nothing. + +Cure. Specificity at both motivation and outcome. What kind of productivity? What does productivity enable? The specifics are the job. + +--- + +## Multiple jobs per situation + +A single situation can produce multiple jobs. Different motivations or outcomes within the same situation are different jobs. + +Worked example. + +Situation: "When I am preparing the quarterly board deck..." + +Job A: "...I want to assemble revenue and engagement data into a coherent narrative, so I can answer the board's likely questions before they ask them." + +Job B: "...I want to flag the risks I want the board to engage with, so I can get their input on the calls I cannot make alone." + +Both jobs share the situation but have different motivations and outcomes. They may need different product responses. + +The discipline. Do not collapse multiple jobs into one because they share a situation. The motivation and outcome distinguish them. + +--- + +## Job statements vs alternatives in JTBD literature + +The "When... I want to... so I can..." format is the most widely used job statement structure. Other formats exist (outcome statements in outcome-driven innovation, struggle statements in switch interviews). They each name the same fundamental thing: the user's situation, motivation, and success criteria. + +This skill uses the When/I-want-to/So-I-can structure because it is the most teachable and the most consistently understood. Teams familiar with other JTBD lineages can translate; the underlying principles are the same. + +The structure-vs-substance discipline. The structure is a scaffold for analytical work. Job statements written in the right structure but without grounding in interview data are still ritual. Job statements written in slightly different structures but grounded in interview data and driving decisions are still jobs. + +--- + +## The job statement editing pass + +Strong JTBD work runs an editing pass focused on job-statement quality. + +Per job statement, the editing questions. + +1. Is the situation specific (a moment, not a demographic)? +2. Is the motivation product-independent and goal-directed? +3. Is the outcome the user's success criterion, not a feature output? +4. Is the statement specific enough that another team could distinguish it from related jobs? +5. Could the team use this job statement to evaluate a product decision? + +The editing investment. 1-2 hours per round of revisions on a typical job-statement set. The investment pays off in clarity for downstream applications (discovery, prioritization, positioning). + +--- + +## Methodology-level choices that stay in the public skill + +The three-level structure (situation, motivation, outcome). Strong vs weak patterns at each level. The product-independence test for motivation. Common structural failures and their cures. Multiple-jobs-per-situation discipline. The structure-vs-substance principle. The editing pass. + +## Implementation choices that stay internal + +Specific job-statement templates in the team's writing system. Specific document conventions for job-statement libraries. Specific A/B testing of statement variants in interview prompts. The team's own conventions for how many job statements per discovery cycle. These vary by team. diff --git a/skills/landing-page-copy/SKILL.md b/skills/landing-page-copy/SKILL.md new file mode 100644 index 0000000..cb3defd --- /dev/null +++ b/skills/landing-page-copy/SKILL.md @@ -0,0 +1,260 @@ +--- +name: landing-page-copy +description: "Write landing page copy with attention to the hero, value proposition, social proof, objection handling, and conversion-focused CTAs. Use this skill whenever the user wants to write a landing page, sales page, hero section, or any conversion-focused web copy. Triggers on landing page, sales page, hero copy, value proposition, headline, subheadline, hero section, CTA copy, conversion copy, opt-in page, squeeze page. Also triggers when the user has a marketing campaign or product launch needing dedicated conversion copy." +category: content +catalog_summary: "Landing pages, sales pages, hero-to-CTA flow" +display_order: 4 +--- + +# Landing Page Copy + +Write copy for pages with a single conversion goal: signup, purchase, demo request, download, lead capture. Stack-agnostic. + +This skill is narrower than `content-and-copy`. Landing pages exist to drive a specific action, not to inform broadly. + +--- + +## When to use + +- Writing a hero section for a homepage or product page +- Writing a sales page or long-form sales letter +- Drafting opt-in or lead-capture page copy +- Campaign-specific landing pages +- Pricing page copy +- Demo or signup CTAs + +## When NOT to use + +- Long-form blog content (use `content-and-copy`) +- Email sequences (use `email-sequences`) +- Brand voice definition (use `brand-voice`) +- Page design and layout decisions (use `design-standards`) + +--- + +## Required inputs + +- The product, service, or offer +- The target audience and the specific objection they bring +- The conversion goal (one specific action) +- Brand voice +- Existing customer language (testimonials, support tickets, sales calls) +- Any constraints (length, format, regulatory) + +If audience is unclear or objections are unknown, run `brand-discovery` or pull from sales call recordings before writing. + +--- + +## The framework: 7 sections + +A landing page does seven things in sequence. The structure can flex (combine, reorder, expand), but the elements stay constant. + +### 1. Hero + +The first 3 to 5 seconds. Decides whether the visitor stays. + +Three components: + +- Headline. The promise. Specific, outcome-focused, free of cliche. +- Subheadline. The mechanism. How you deliver the promise. +- Primary CTA. The action. One button, descriptive label. + +Strong hero patterns: + +- Outcome + audience + mechanism. "Ship features 3x faster, for engineering teams who hate meetings, with our async-first project tool." +- Pain reversal. "Stop losing customers to slow page loads." +- Surprising claim. "The note-taking app that gets used. We have data." +- Direct address. "You have 47 unread Slack messages. Here's what to do about it." + +Weak hero patterns: + +- Generic adjective stacking ("Powerful, intuitive, scalable") +- "Welcome to our platform" +- Brand-name-only headlines ("Acme: The Future of X") +- Vague benefits ("Streamline your workflow") + +### 2. Social proof (early) + +Within the first scroll, prove someone else trusts you. + +Forms: +- Customer logos (recognizable beats unknown) +- Quantitative trust signal ("Over 10,000 teams") +- One strong testimonial with name and role +- Press mentions (logos of where you've been featured) + +Placement: Right below the hero, before the visitor invests in reading more. + +### 3. Problem / promise + +Establish that you understand the visitor's situation. + +Pattern: +- 1 to 3 paragraphs naming the specific problem +- Use the visitor's language (mined from research, not your marketing language) +- Stop before you sell. Resonate first. + +Test: Read the problem section aloud. Does the target audience nod? If they don't, you don't understand them yet. + +### 4. Solution / mechanism + +How you solve the problem. The "what we actually do" section. + +Effective structure: +- One headline summarizing the solution +- 3 to 5 specific features or capabilities, each with a 1-2 sentence explanation +- Each feature framed as the benefit it produces, not the technical detail +- Visual support (screenshots, illustrations, video clips) + +Failure mode: Listing features without translating to outcomes. "Real-time collaboration" is a feature. "Edit together without copying-pasting from email" is the outcome. + +### 5. Proof and detail + +The expanded social proof and case studies section. + +Components: +- 1 to 3 detailed case studies (specific customer, specific outcome, specific numbers) +- Multiple testimonials with attribution +- Specific data points (usage stats, success metrics, growth) +- Awards, certifications, or third-party validation + +The deeper proof section is where committed visitors convert. Skim-readers won't make it here, but the ones who do are ready to buy. + +### 6. Objection handling + +Anticipate the reasons people say no. Address them directly. + +Common objection types: +- Price. "Is this worth it?" +- Time. "Will this take forever to set up?" +- Trust. "Will this actually work for my situation?" +- Risk. "What if I commit and it's wrong?" +- Comparison. "How is this different from [competitor]?" +- Implementation. "Can my team handle the change?" + +Handling formats: +- FAQ section. Structured, scannable. +- Comparison table. Vs. competitors or vs. alternatives. +- Risk reversal. Money-back guarantee, free trial, no-contract terms. +- Proof of effort needed. "Setup takes 5 minutes, not 5 weeks." + +### 7. Final CTA + +The closer. Re-state the offer. Re-state the action. + +Strong final CTAs: +- Repeat the primary CTA from the hero (consistency) +- Frame in terms of the visitor's situation ("Get your team set up in 5 minutes") +- Remove friction ("No credit card required") +- One action only (avoid offering 5 alternatives that paralyze decision) + +Avoid: +- Multiple CTAs competing for attention at the bottom +- New offers introduced only at the bottom (visitor is now confused) +- Long forms that ask for more information than needed for the action + +--- + +## The CTA itself + +Buttons matter. Treat the button copy as a whole-page-worth of attention. + +Strong CTA patterns: + +- Action + outcome. "Start your free trial," "Get my pricing," "Send me the guide" +- First-person. "Show me how" outperforms "Show you how" +- Specific. "Book a 15-minute demo" beats "Contact us" +- Low-friction. "Free trial, no credit card" reduces commitment cost + +Weak CTAs: +- "Submit" (functional but lifeless) +- "Click here" (no value statement) +- "Learn more" (vague; about what?) +- "Get started" (started doing what?) + +--- + +## Workflow + +1. Confirm the offer. What exactly is being offered? At what price (if any)? What does the visitor get? +2. Confirm the audience and objection. Specific segment. The specific worry they bring. +3. Mine the language. Customer testimonials, support tickets, sales calls. Use real customer phrases. +4. Draft the hero. Headline, subheadline, CTA. Test 5 to 10 variations. +5. Build the structure. All 7 sections in order. Sections can combine for shorter pages. +6. Draft sections. Section by section. Don't polish until the structure is sound. +7. Edit for friction. Remove every word that doesn't earn its place. Landing pages do not have words to spare. +8. Test the CTA. Read the page aloud. By the end, is the visitor's next action obvious? +9. Pre-publish: check links, spell-check, mobile preview, SEO basics if SEO is a goal. + +--- + +## Failure patterns + +- Hero that explains instead of sells. "We're an X for Y" is description. "Get X without Y" is sell. +- Feature lists with no outcomes. Features without benefits read as a spec sheet. +- Generic testimonials. "Great product!" is worth less than nothing. "We cut onboarding time from 2 weeks to 4 days" is gold. +- Multiple competing CTAs. Pick one primary action. Everything else is noise. +- Walls of text. Visitors scan. Use short paragraphs, bullet lists, and visual breakpoints. +- No social proof. Trust is the first hurdle. Without proof, the rest of the page does not earn the chance to be read. +- Mismatched headline and CTA. Hero promises X, CTA asks for Y. Visitor confused. +- Writing for everyone. "Our solution works for any business" appeals to no one. Specificity converts. +- Ignoring mobile. Most visitors are on mobile. Test the page at 375px first. + +--- + +## Output format + +Default output is a structured markdown document for the page, with each section labeled. The markdown is ready to import into the CMS or hand to design. + +Structure: + +```markdown +# [Page Title] + +## SECTION: Hero +- Headline: [text] +- Subheadline: [text] +- Primary CTA: [button text] +- Supporting cue: [optional, e.g., "No credit card required"] +- Hero visual notes: [if any] + +## SECTION: Social proof (early) +- Logo bar: [list customer/press logos] +- Trust statistic: [if any] + +## SECTION: Problem / promise +[2 to 3 paragraphs] + +## SECTION: Solution +- Headline: [text] +- Feature 1: [headline + description] +- Feature 2: [headline + description] +- Feature 3: [headline + description] + +## SECTION: Proof +- Case study 1: [customer, outcome, numbers] +- Testimonials: [list] +- Data points: [list] + +## SECTION: Objection handling +- FAQ: [questions and answers] +- OR Comparison table: [vs alternatives] +- OR Risk reversal: [guarantee, terms] + +## SECTION: Final CTA +- Headline: [text] +- Final CTA button: [text] +- Supporting cue: [optional] + +## Variants for testing +- [Alternate headlines] +- [Alternate CTAs] +- [Alternate proof framings] +``` + +--- + +## Reference files + +- [`references/hero-formulas.md`](references/hero-formulas.md) - Patterns and formulas for hero headlines. +- [`references/objection-library.md`](references/objection-library.md) - Common objections by category, with handling strategies. diff --git a/skills/landing-page-copy/references/hero-formulas.md b/skills/landing-page-copy/references/hero-formulas.md new file mode 100644 index 0000000..d14a980 --- /dev/null +++ b/skills/landing-page-copy/references/hero-formulas.md @@ -0,0 +1,230 @@ +# Hero Headline Formulas + +The hero headline is the most-read line on the page. It earns the rest of the read or it doesn't. + +These are not magic templates. They are starting points. Apply them, then make them sound like the brand. + +--- + +## Formula 1: Outcome + audience + mechanism + +Pattern: [Specific outcome] for [specific audience] with [specific mechanism] + +Examples: +- "Ship features 3x faster, for engineering teams who hate meetings, with async-first project management." +- "Cut payroll processing from days to minutes, for finance teams of 50+, with one connected system." +- "Build a remote team that doesn't burn out, for founders scaling past 20 people, with rituals that actually work." + +Strengths: Highly specific. Hard to confuse with a competitor. + +Weaknesses: Can become long and clunky. Not always elegant. + +When to use: Product is in a crowded category and needs to differentiate quickly. + +--- + +## Formula 2: Pain reversal + +Pattern: Stop [specific pain]. Start [specific outcome]. + +Examples: +- "Stop losing customers to slow checkout. Start converting at industry-leading speeds." +- "Stop digging through Slack threads. Start finding answers in seconds." +- "Stop guessing what your users want. Start knowing." + +Strengths: Direct. Names the visitor's current frustration. + +Weaknesses: Depends on the pain being widely felt. If the pain isn't recognized, the headline doesn't connect. + +When to use: The audience is actively frustrated by something specific. + +--- + +## Formula 3: Surprising claim + +Pattern: A specific claim that contradicts what the audience expects. + +Examples: +- "The note-taking app most people actually use." +- "Email outreach that doesn't feel like spam." +- "The CRM that sales reps don't try to escape from." + +Strengths: Pattern-breaks. Creates curiosity. + +Weaknesses: Must be defensible. A surprising claim with no proof feels like marketing puffery. + +When to use: You can back up the claim with evidence in the page below. + +--- + +## Formula 4: Direct address + +Pattern: Speak to a specific situation the visitor is in right now. + +Examples: +- "You have 47 unread Slack messages. Here's what to do." +- "Your team just lost three candidates this month. Here's why." +- "Your app crashed at 3 AM. We watched your monitoring system miss it." + +Strengths: Visitor recognizes themselves immediately. + +Weaknesses: Risk of feeling presumptuous if the situation is wrong. + +When to use: The audience is highly specific and the scenario is universal among them. + +--- + +## Formula 5: Question they're already asking + +Pattern: Pose the question the visitor came to find an answer to. + +Examples: +- "How much should you actually spend on Google Ads?" +- "Should you build it or buy it? Here's the framework." +- "Why does your team's productivity drop after lunch?" + +Strengths: Aligns with search intent. Strong for SEO landing pages. + +Weaknesses: Less common in product hero copy. Better for content-driven landing pages. + +When to use: The page answers a specific question the visitor brought. + +--- + +## Formula 6: Comparison (us vs. them) + +Pattern: [Our category] without the [familiar pain of the category]. + +Examples: +- "CRM software without the bloat." +- "Project management without the meetings." +- "Customer support without the tickets." + +Strengths: Defines you in opposition to known alternatives. + +Weaknesses: Lazy version becomes "X but better." Specific version requires you to actually deliver on the difference. + +When to use: The category has a well-known pain point you avoid. + +--- + +## Formula 7: Number + outcome + +Pattern: Specific number that quantifies the value. + +Examples: +- "Cut your churn in half within 90 days." +- "Onboard your team in 15 minutes, not 15 weeks." +- "Generate 200 hours of meeting transcripts per month." + +Strengths: Specific and credible. + +Weaknesses: The number must be defensible. Made-up numbers undermine trust. + +When to use: You have real data backing the claim. + +--- + +## Formula 8: First-person promise + +Pattern: "Get [specific thing]" or "Find [specific thing]" - speaking as if to a friend. + +Examples: +- "Get insurance quotes in 60 seconds. Compare 30 carriers." +- "Find a contractor your neighbors actually recommend." +- "Get back the 6 hours a week you spend on email." + +Strengths: Conversational. Low-friction. + +Weaknesses: Casual register may not fit every brand. + +When to use: Brand voice supports a conversational first-person register. + +--- + +## Subheadline patterns + +The subheadline supports the headline. It usually does one of three jobs: + +### Job 1: Mechanism +The subheadline explains how you deliver the headline's promise. + +> Headline: Ship features 3x faster. +> Subheadline: Our async workflow eliminates the meetings that slow your team down. + +### Job 2: Audience qualifier +The subheadline names the audience precisely. + +> Headline: The simplest way to manage your inventory. +> Subheadline: Built for ecommerce stores doing $1M to $10M in revenue. + +### Job 3: Specificity / proof +The subheadline adds the credible detail. + +> Headline: Stop losing leads. +> Subheadline: Top performers reduce response time from hours to minutes. We help you do the same. + +--- + +## What to avoid in hero copy + +### Generic adjective stacking + +Bad: "Powerful. Intuitive. Scalable." + +These adjectives apply to anything. They distinguish nothing. + +### Vague benefits + +Bad: "Streamline your workflow with our innovative platform." + +What workflow? What's innovative? What does the visitor actually do? + +### Brand-name-only headlines + +Bad: "Acme: The Future of Work." + +The visitor doesn't know what Acme is yet. The headline must tell them. + +### Cleverness over clarity + +Bad: "Where productivity meets possibility." + +Sounds nice. Means nothing. Visitors do not have time to decode poetry. + +### "Welcome to" openers + +Bad: "Welcome to the [Brand] platform." + +Treats the visitor as a guest rather than a person trying to solve a problem. Wastes the most important real estate on the page. + +--- + +## Testing hero headlines + +Don't ship the first headline you write. Generate 5 to 10 variations using different formulas. Read them aloud. Show them to people. Pick the one that: + +1. A target-audience reader recognizes themselves in +2. Differentiates from at least 3 specific competitors +3. Sets up the rest of the page (the rest of the page must deliver on the headline's promise) +4. Sounds like the brand (not generic marketing speak) +5. Survives the "why now" test (why does this matter to the visitor today) + +If a headline can't survive all five, generate more variations. + +--- + +## CTA patterns to pair with hero headlines + +The headline and CTA must rhyme. If they don't, the visitor's mental model breaks. + +\| Hero promise \| CTA pattern \| +\|---\|---\| +\| Get specific outcome \| "Get [the outcome]" \| +\| Save time / money \| "Save [the thing]" \| +\| See how it works \| "Watch demo" / "See it in action" \| +\| Try the product \| "Start free trial" / "Try it free" \| +\| Get information \| "Get the guide" / "Show me how" \| +\| Talk to a person \| "Book a call" / "Talk to sales" \| + +The CTA copy is part of the hero, not an afterthought. Treat it with the same care as the headline. diff --git a/skills/landing-page-copy/references/objection-library.md b/skills/landing-page-copy/references/objection-library.md new file mode 100644 index 0000000..23ae871 --- /dev/null +++ b/skills/landing-page-copy/references/objection-library.md @@ -0,0 +1,244 @@ +# Objection Library + +Common objections by category, with handling strategies. Use this to pressure-test landing page copy and to make sure each major objection is met somewhere on the page. + +If a landing page does not name and answer the audience's real objections, it will not convert no matter how strong the hero is. + +--- + +## How to use this library + +1. Identify your audience and the specific decision they are facing. +2. Walk this library and flag every objection that applies. +3. For each flagged objection, decide where on the page it gets handled (and whether it gets handled with copy, social proof, a guarantee, an FAQ, or a feature). +4. Pressure-test the page: read it as a skeptical reader. Are the flagged objections answered before the CTA? + +Most pages handle 5-8 objections. Pages that handle 0-2 read as too good to be true. Pages that handle 15+ feel defensive. + +--- + +## Category 1: trust + +The audience does not know if you are real, competent, or honest. + +### "I have never heard of you" + +- Symptom: Bounce rate high, low time on page. +- Handling: Logo bar of customers, press mentions, founder photo and one-line bio, "since [year]" line, recognizable case study, security badges if relevant. + +### "How do I know this works?" + +- Symptom: Visitors read the whole page but do not act. +- Handling: Specific case studies with real names and specific outcomes ("X reduced Y by Z%"). Demo or trial. Money-back guarantee. Free assessment. + +### "How do I know you will be around in a year?" + +- Symptom: Common in B2B with switching costs, regulated industries, long-term commitments. +- Handling: Funding announcements, customer count, years in business, prominent enterprise customers, industry awards or compliance attestations. + +### "Who is behind this?" + +- Symptom: Common in personal brands, consultancies, or expertise-based services. +- Handling: Founder photo, credentials, prior work, authentic origin story. + +--- + +## Category 2: fit + +The audience cannot tell if this is for them. + +### "Is this for someone like me?" + +- Symptom: General-audience visitors converting; specific-segment visitors bouncing. +- Handling: Audience-specific copy, role-based or industry-based pages, named segments in the hero ("for [role] at [company size]"), audience-specific case studies. + +### "Will this work for my situation?" + +- Symptom: Visitors get to features and bounce. +- Handling: Use case sections, conditional FAQ ("if you are X, here is how this works"), filterable case studies, decision tree or quiz. + +### "Is my problem big enough to need this?" + +- Symptom: SMB visitors looking at enterprise products, or vice versa. +- Handling: Plan or tier comparison, "right-sized for [size]" messaging, alternatives section ("if you have [smaller problem], try [lighter approach]"). + +### "I have already solved this with [alternative]" + +- Symptom: Visitors compare and leave. +- Handling: Comparison page, "vs [competitor]" page, "in addition to" framing, integrations section. + +--- + +## Category 3: complexity and time + +The audience worries this will be hard, slow, or distracting. + +### "How long will this take to set up?" + +- Symptom: Time-on-page high; conversion low. Common in dev tools, SaaS. +- Handling: "5 minutes to set up" messaging, video walkthrough showing real timing, testimonials from peers about onboarding, white-glove option. + +### "Will I have to migrate or change what I am doing?" + +- Symptom: Switching anxiety. Common in any tool replacement. +- Handling: Migration guides, importer features highlighted, "works alongside [current tool]" framing, migration assistance offered. + +### "Will my team need training?" + +- Symptom: Buyer is enthusiastic; champion is worried about adoption. +- Handling: Onboarding program, in-product training, role-based docs, video library, account manager for enterprise. + +### "Is this going to add to my plate?" + +- Symptom: Visitors are already overworked. Common pitch to operators, ICs. +- Handling: Time-saving framing with specific numbers ("saves 4 hours per week"), automation highlighted, replace-not-add positioning. + +--- + +## Category 4: cost + +The audience worries about price, value, or hidden costs. + +### "How much does this cost?" + +- Symptom: Anyone visiting the pricing page bounces. Conversion only on free trial. +- Handling: Transparent pricing on the marketing site (or "starts at" if pricing varies), no "request a quote" for low-tier pricing, ROI calculator. + +### "Is it worth the price?" + +- Symptom: Pricing page visited; nothing happens. +- Handling: Specific ROI examples ("customers see X return in Y months"), comparison to alternative ("instead of hiring a [role], you get [tool]"), free trial or money-back, value framing throughout. + +### "Are there hidden fees?" + +- Symptom: Visitors abandon at checkout or in sales calls when extras come up. +- Handling: "No setup fees" line, "no per-seat charges" if true, "all features included" if true, transparent pricing page with all variables surfaced. + +### "I do not have budget right now" + +- Symptom: Common in macro slowdowns. Visitors say "interesting, send info." +- Handling: Annual discount, smaller plan, free tier, ROI-led copy, ROI calculator, "self-funding within X months" claim if defensible. + +--- + +## Category 5: risk + +The audience fears what happens if this goes wrong. + +### "What if it does not work?" + +- Symptom: Visitors explore deeply but do not commit. +- Handling: Money-back guarantee, free trial, free pilot, money-back specifically tied to outcome ("if you do not see X, we refund"), case studies of customers who got results. + +### "What if my data is at risk?" + +- Symptom: Common in B2B, data tools, financial, healthcare. +- Handling: Security page linked from footer (and from sales-relevant pages), compliance badges (SOC 2, ISO 27001, GDPR, HIPAA), data-handling explainer, "your data is yours" framing. + +### "What if I am locked in?" + +- Symptom: Visitors ask about export, contracts, cancellation in sales calls. +- Handling: "Export your data anytime," "no long-term contract," "cancel any time," month-to-month option visible. + +### "What if my team will not adopt it?" + +- Symptom: Champion deals stall. +- Handling: Onboarding program, role-based pricing or trials, internal-rollout playbook, customer testimonials from peer companies on adoption. + +--- + +## Category 6: timing + +The audience does not see urgency. + +### "I will get to this later" + +- Symptom: Sign-ups but no follow-through. Long sales cycles. +- Handling: Cost-of-inaction framing ("each month you wait costs X"), time-bound offer (tasteful, real, not fake), seasonal hook if relevant, before-and-after framing showing time loss. + +### "I am evaluating multiple options" + +- Symptom: Pipeline takes 6+ months to close. +- Handling: Comparison page, evaluation guide ("how to evaluate [category]"), trial that gets the buyer hands-on quickly, customer references for direct calls. + +--- + +## Category 7: politics and process + +The audience cannot decide alone. + +### "I need to get my boss to approve this" + +- Symptom: Champion engagement high; deal stuck above champion's authority. +- Handling: Business case template, ROI calculator, exec one-pager, "make the case to [role]" content, customer references at peer companies (named role buying the same tool). + +### "I need legal/security/procurement to review" + +- Symptom: Long lag between handshake and contract signature. +- Handling: Security questionnaire pre-completed, MSA boilerplate available, vendor onboarding kit, named legal/security contact for buyer-side reviewers. + +### "I need to align with [other team]" + +- Symptom: Multi-stakeholder deals stall. +- Handling: Team-specific pages, team-specific demos, multi-stakeholder ROI framing, internal advocacy kit (slide deck, FAQ). + +--- + +## Category 8: emotional / status + +The audience worries about how they will look. + +### "What if this is the wrong call?" + +- Symptom: Decision-maker stalls. Common with high-visibility purchases. +- Handling: Peer customer testimonials ("[Title] at [Recognizable Company] said X"), industry analyst recognition, awards, money-back guarantee that limits downside. + +### "Will this make me look behind / ahead?" + +- Symptom: First-mover anxiety or laggard anxiety. Industry-specific. +- Handling: "Industry standard now" framing for laggards, "ahead of the curve" framing for first-movers, social proof from peer companies in either case. + +--- + +## How objection handling shows up on the page + +The library is the inventory. The page is where it lands. The most common placements: + +- Hero: answers the "is this for me" objection. +- Logo bar: answers "are you real." +- Feature sections: answer "does this do what I need." +- Use case sections: answer "will this work for my situation." +- Case study sections: answer "does this work." +- Comparison sections: answer "what about alternatives." +- Pricing section: answers "what does it cost." +- FAQ section: answers the long tail of objections. +- Guarantee / trial offer: answers "what if it does not work." +- Footer trust block: answers "is my data safe" via compliance badges. + +If an objection from your audience is not answered anywhere on the page, the page is incomplete. + +--- + +## Worked example + +Audience: Engineering manager at a series-B startup, 30-50 person engineering org, evaluating an observability tool to replace an in-house Grafana setup. + +Top 5 objections (filtered from the library): + +1. "How long will this take to set up?" (Category: complexity) +2. "Will I have to migrate?" (Category: complexity) +3. "What does this cost at our scale?" (Category: cost) +4. "What if my engineers do not adopt it?" (Category: risk + politics) +5. "What if our data is at risk?" (Category: risk) + +Page placements: + +\| Objection \| Where it gets handled \| +\|---\|---\| +\| Setup time \| Hero ("Live in 10 minutes" + 60-second product video) \| +\| Migration \| Migration section ("imports from Grafana automatically") + case study showing migration story \| +\| Cost at scale \| Pricing page with engineer-count slider, transparent monthly cost \| +\| Adoption \| Adoption section showing in-product onboarding, plus a customer quote ("80% of engineers logged in week one") \| +\| Data risk \| Footer trust block (SOC 2, ISO, GDPR) + a "your data" explainer linked from pricing \| + +Page is built around answering these five, in order, from hero to CTA. diff --git a/skills/launch-runbook/SKILL.md b/skills/launch-runbook/SKILL.md new file mode 100644 index 0000000..0fb3e62 --- /dev/null +++ b/skills/launch-runbook/SKILL.md @@ -0,0 +1,236 @@ +--- +name: launch-runbook +description: "Plan and execute a launch runbook covering pre-launch verification, go-live procedures, DNS cutover, post-launch monitoring, and rollback procedures. Use this skill whenever the user is preparing to launch a website or product, planning a DNS cutover, building a go-live checklist, or executing a launch day. Triggers on launch runbook, go-live, launch day, DNS cutover, deploy to production, site launch, product launch, cutover plan, launch checklist, deployment procedure. Also triggers when a launch is approaching and the team needs structured coordination, even if 'runbook' is not explicitly stated." +category: operations +catalog_summary: "Go-live runbook, DNS cutover, deploy day procedures" +display_order: 1 +--- + +# Launch Runbook + +Plan and execute the launch of a website, product, or major release. The runbook is the document everyone uses on launch day. Stack-agnostic. + +This skill is for the launch event. For pre-launch QA, use `qa-testing`. For post-launch incident handling, use `incident-response`. + +--- + +## When to use + +- Launching a new website or major redesign +- Migrating from one platform to another +- Releasing a major product or feature +- Coordinating cross-team launches +- Building a runbook for a recurring deploy + +## When NOT to use + +- Pre-launch testing (use `qa-testing`) +- Post-launch incident response (use `incident-response`) +- After-launch retrospective (use `after-action-report`) + +--- + +## Required inputs + +- The launch scope (what's being launched) +- The launch window (date, time, duration) +- The team (roles, on-call rotation) +- The rollback criteria (when to abort) +- The communication plan (who tells whom what, when) + +--- + +## The framework: 4 phases + +A launch has four phases. The runbook covers all four. + +### Phase 1: Pre-launch (T-30 days to T-1 hour) + +Verify everything is ready before the launch window. + +T-30 days: +- Final scope locked +- Cross-team commitments confirmed +- Pre-launch QA scheduled +- Comms plan drafted + +T-7 days: +- Pre-launch QA complete +- All critical and major issues resolved +- Performance baseline measured +- Rollback procedures documented and tested +- DNS TTL lowered (if DNS change is part of launch) + +T-1 day: +- Final go/no-go meeting +- Roles confirmed +- Communication channels set up +- Backup of current production state + +T-1 hour: +- Team assembled in shared communication channel +- Tools and access verified +- Final smoke test on staging + +### Phase 2: Cutover (T-0) + +The actual launch. Sequenced steps with owners and verifications. + +Standard cutover steps: + +1. Announce start to internal team +2. Enable maintenance mode (if applicable) +3. Run final database migrations (if applicable) +4. Deploy code to production +5. Verify deploy completed without errors +6. Run smoke tests on production +7. DNS cutover (if applicable) +8. Verify DNS propagation +9. Disable maintenance mode +10. Run full smoke tests on production +11. Announce launch to internal team +12. Begin monitoring window + +Each step has: +- Owner +- Pre-conditions +- Action +- Verification +- Time estimate +- Rollback procedure + +### Phase 3: Verification (T+0 to T+24 hours) + +Confirm the launch is healthy. + +Within first hour: +- Critical user flows working (checkout, signup, login) +- No spike in error rates +- Performance within expected ranges +- Analytics tracking firing +- Email and notifications working + +Within first 24 hours: +- No regression in key business metrics +- No accumulating error patterns +- Core Web Vitals stable +- Search Console showing no critical issues (if SEO-relevant) + +### Phase 4: Stabilization (T+24 hours to T+7 days) + +Monitor the long tail. + +- Track error rates day over day +- Track performance day over day +- Track key business metrics vs baseline +- Address any non-blocking issues identified +- Plan the AAR (after-action report) + +--- + +## Roles and responsibilities + +A launch has clear role assignments. Ambiguity here is the most common cause of launch chaos. + +\| Role \| Responsibility \| +\|---\|---\| +\| Launch lead \| Owns the runbook. Calls go/no-go. Calls rollback. \| +\| Deploy operator \| Executes the technical deploy steps. \| +\| QA lead \| Runs verification tests and confirms each milestone. \| +\| Comms lead \| Posts internal updates, manages external messaging. \| +\| On-call engineer \| Available for issues during and after launch. \| +\| Stakeholder rep \| Approves on behalf of business stakeholders. \| + +For small teams, one person may fill multiple roles. Each role's responsibilities should still be explicit. + +--- + +## Rollback criteria + +Define before the launch. Decisions are easier to make pre-emptively than under pressure. + +Automatic rollback triggers: +- Error rate exceeds X percent of normal +- Critical user flow (defined) is broken +- Database integrity issue +- Security vulnerability discovered post-deploy + +Discretionary rollback triggers: +- Performance degradation beyond Y percent +- Significant degradation in key business metric +- Customer-facing error patterns + +Decision authority: The launch lead calls rollback. Pre-define who acts as deputy if launch lead is unavailable. + +--- + +## Communication plan + +### Internal channels + +- Primary launch channel: Real-time chat for the launch team only +- Status channel: Broader internal updates +- War room: Optional video call for high-stakes launches + +### Update cadence during launch + +- Every 15 minutes during cutover +- Every hour during verification phase +- Daily during stabilization phase + +### External communication + +- Customer-facing announcement: Pre-drafted, scheduled to publish at confirmed-success milestone +- Status page: Updated proactively if any user impact +- Support team: Briefed in advance on what's launching, common questions, escalation path + +--- + +## Workflow + +1. Build the runbook 30 days out. Scope, sequence, roles, rollback criteria, comms plan. +2. Test the rollback procedure. Untested rollback is hope, not procedure. +3. Run a tabletop exercise. Walk through the runbook with the full team. Find gaps. +4. Lower DNS TTL 48 to 72 hours before launch (if DNS change is part of launch). +5. Day-of: Run the runbook step by step. Verify each step before moving to next. +6. Monitor. First hour, first day, first week. Document anything noteworthy. +7. Schedule the AAR within 1 to 2 weeks of launch. + +--- + +## Failure patterns + +- Runbook written by one person, not reviewed. Single perspective misses scenarios. +- No tested rollback. Discovering rollback is broken at the moment you need it. +- Vague step descriptions. "Deploy to production" without specifying which tool, which command, which environment. +- No verification step after each action. Errors propagate. +- Communication gaps. Team doesn't know launch is happening, or doesn't know it succeeded. +- Launching at end of day Friday. Or before a holiday. Reduce the time available to respond. +- Skipping pre-launch QA to hit a date. The bugs appear on launch day instead. +- Launch fatigue. Long launches without breaks lead to errors. Plan rest cycles for multi-day launches. +- No on-call for first 24 hours. Someone must be reachable. + +--- + +## Output format + +Default output: a markdown runbook at `launch-runbook-[project].md` plus supporting checklists. + +Structure: + +1. Launch metadata (what, when, who) +2. Roles and responsibilities +3. Pre-launch checklist (T-30, T-7, T-1, T-1hr) +4. Cutover sequence (numbered steps, owners, verifications) +5. Rollback procedure +6. Rollback criteria (automatic and discretionary) +7. Communication plan +8. Verification checklist (first hour, first day) +9. Stabilization plan (first week) +10. Contacts (escalation paths, on-call) + +--- + +## Reference files + +- [`references/runbook-template.md`](references/runbook-template.md) - Fillable runbook template with example cutover sequences. diff --git a/skills/launch-runbook/references/runbook-template.md b/skills/launch-runbook/references/runbook-template.md new file mode 100644 index 0000000..bd2a9c2 --- /dev/null +++ b/skills/launch-runbook/references/runbook-template.md @@ -0,0 +1,289 @@ +# Launch Runbook Template + +Fillable runbook for a launch. Copy this template, fill in specifics for your launch. + +--- + +## Launch metadata + +What's launching: [Specific scope. "New marketing site at example.com replacing the legacy site."] + +Launch date: [YYYY-MM-DD] + +Launch window start: [Time, timezone] + +Launch window end: [Time, timezone] + +Maintenance window required: [Yes / No, and if yes, expected duration] + +Launch lead: [Name + contact] + +Deputy launch lead: [Name + contact, in case primary is unavailable] + +--- + +## Roles + +\| Role \| Person \| Backup \| Contact \| +\|---\|---\|---\|---\| +\| Launch lead \| \| \| \| +\| Deploy operator \| \| \| \| +\| QA lead \| \| \| \| +\| Comms lead \| \| \| \| +\| On-call engineer (post-launch) \| \| \| \| +\| Stakeholder rep \| \| \| \| + +--- + +## Pre-launch checklist + +### T-30 days +- [ ] Final scope locked and signed off +- [ ] Cross-team commitments confirmed +- [ ] Pre-launch QA scheduled +- [ ] Communications plan drafted +- [ ] Rollback procedure documented + +### T-14 days +- [ ] Pre-launch QA in progress +- [ ] Performance baseline measured (current production) +- [ ] Critical and major issues triaged +- [ ] Internal launch announcement drafted + +### T-7 days +- [ ] All critical issues resolved +- [ ] All major issues resolved or accepted with mitigation +- [ ] Rollback procedure tested in staging +- [ ] DNS TTL lowered to 60 to 300 seconds (if DNS change is part of launch) +- [ ] Final go/no-go date confirmed + +### T-2 days +- [ ] Final go/no-go meeting held +- [ ] Decision: GO / NO-GO / DEFER +- [ ] All team members confirmed available for launch window +- [ ] Backup of current production state taken +- [ ] Customer support briefed on what's launching + +### T-1 day +- [ ] Final smoke test on staging passes +- [ ] Communication channels set up +- [ ] On-call rotation confirmed for first 24 hours +- [ ] Pre-drafted internal and external messaging ready + +### T-1 hour +- [ ] Team assembled in launch communication channel +- [ ] All required tools and access verified +- [ ] Final smoke test on staging passes +- [ ] Launch lead confirms GO + +--- + +## Cutover sequence + +For each step: +- Owner: Person executing +- Pre-condition: What must be true to start +- Action: What to do +- Verification: How to confirm success +- Estimated time: How long this should take +- Rollback: What to do if this step fails + +--- + +### Step 1: Announce start + +- Owner: Comms lead +- Pre-condition: Launch lead has confirmed GO +- Action: Post in internal status channel: "Starting launch of [scope] at [time]. Expected duration: [X minutes]." +- Verification: Message posted, key stakeholders confirmed they saw it +- Time: 2 minutes + +### Step 2: Enable maintenance mode + +- Owner: Deploy operator +- Pre-condition: Step 1 complete +- Action: [Specific command or action to enable maintenance mode] +- Verification: Visit production URL, confirm maintenance page is showing +- Time: 2 minutes +- Rollback: Disable maintenance mode + +### Step 3: Final database migrations + +- Owner: Deploy operator +- Pre-condition: Step 2 complete, database backup confirmed +- Action: [Specific migration command] +- Verification: Migration log shows success, schema verified +- Time: [estimate] +- Rollback: Restore from backup taken in T-2 + +### Step 4: Deploy code to production + +- Owner: Deploy operator +- Pre-condition: Step 3 complete +- Action: [Specific deploy command or CI trigger] +- Verification: Deploy log shows success, version endpoint returns new version +- Time: [estimate based on past deploys] +- Rollback: Re-deploy previous version + +### Step 5: Run smoke tests on production + +- Owner: QA lead +- Pre-condition: Step 4 complete +- Action: Run smoke test suite against production +- Verification: All smoke tests pass +- Time: [estimate] +- Rollback: If failures, evaluate severity. Critical failures = rollback to step 4. + +### Step 6: DNS cutover (if applicable) + +- Owner: Deploy operator +- Pre-condition: Step 5 passes +- Action: Update DNS records: [specific records and values] +- Verification: Use `dig` or DNS lookup tools to confirm new records propagating +- Time: Propagation up to 5 minutes (if TTL was lowered) up to 24+ hours (if not) +- Rollback: Revert DNS records to previous values + +### Step 7: Disable maintenance mode + +- Owner: Deploy operator +- Pre-condition: Step 6 verified +- Action: [Specific command to disable maintenance mode] +- Verification: Visit production URL, confirm new site loads +- Time: 2 minutes + +### Step 8: Full smoke test on production + +- Owner: QA lead +- Pre-condition: Step 7 complete +- Action: Run full smoke test suite (more comprehensive than step 5) +- Verification: All tests pass; critical user flows verified manually +- Time: [estimate] +- Rollback: If failures, evaluate. Critical failures = full rollback. + +### Step 9: Announce success + +- Owner: Comms lead +- Pre-condition: Step 8 passes +- Action: Post in internal status channel: "Launch complete. All checks pass." +- Verification: Confirmed by stakeholders +- Time: 2 minutes + +### Step 10: Begin monitoring window + +- Owner: On-call engineer +- Pre-condition: Step 9 complete +- Action: Begin elevated monitoring for first 60 minutes. Watch error rates, performance, key business metrics. +- Verification: Dashboards open, alerts armed +- Time: Continuous + +--- + +## Rollback procedure + +If rollback is called, execute these steps: + +1. Announce rollback in internal status channel +2. Re-enable maintenance mode (if applicable) +3. Revert DNS records to previous values (if changed) +4. Re-deploy previous code version +5. Restore database from backup (if migrations were destructive) +6. Verify previous version is functioning +7. Disable maintenance mode +8. Run smoke tests on rolled-back state +9. Announce rollback complete +10. Schedule post-mortem + +Estimated total rollback time: [Estimate, typically 15 to 60 minutes] + +Authority to call rollback: Launch lead (or deputy if launch lead unavailable) + +--- + +## Rollback criteria + +### Automatic rollback (no debate, just do it) +- [ ] Production error rate exceeds [X]% above baseline +- [ ] Critical user flow broken: [specify which flows] +- [ ] Database integrity issue detected +- [ ] Security vulnerability discovered + +### Discretionary rollback (launch lead's call) +- [ ] Performance degradation beyond [Y]% +- [ ] Significant degradation in [specific business metric] +- [ ] Customer-facing error pattern emerging + +--- + +## Communication plan + +### Internal updates during launch +- Cadence: Every 15 minutes during cutover +- Channel: [Specific Slack channel / Teams channel / etc.] +- Format: "[Time] - [Step name] - [Status: started / in progress / complete / blocked]" + +### Customer-facing announcement +- When: After step 9 (success announce internal) +- Where: [Specific channels: blog post, email, social, etc.] +- Pre-drafted: [Link to draft] +- Approver: [Name] + +### Status page updates +- Pre-launch: [Status set to "Maintenance scheduled"] +- During: [Status set to "Maintenance in progress"] +- Post-success: [Status set to "Operational"] +- If issues: [Status set to "Investigating" or "Identified"] + +### Support team brief +- Pre-launch brief covers: what's launching, what users may notice, common questions, escalation path +- During-launch updates posted to support channel + +--- + +## Verification checklist (first hour) + +- [ ] Homepage loads +- [ ] Critical user flow 1: [specify] - works +- [ ] Critical user flow 2: [specify] - works +- [ ] Critical user flow 3: [specify] - works +- [ ] Sign-up / sign-in - works +- [ ] Payment flow (if applicable) - works +- [ ] Email sending - works +- [ ] Analytics tracking firing +- [ ] Error rate within normal range +- [ ] Performance within normal range +- [ ] No security alerts triggered +- [ ] Search Console shows no critical issues (if SEO-relevant launch) + +--- + +## Verification checklist (first 24 hours) + +- [ ] No regression in key business metrics: [list specific metrics] +- [ ] Error rate stable +- [ ] Performance stable +- [ ] No accumulating error patterns +- [ ] Core Web Vitals stable +- [ ] Customer support volume within normal range + +--- + +## Contacts + +\| Role \| Name \| Phone \| Slack \| Email \| +\|---\|---\|---\|---\|---\| +\| Launch lead \| \| \| \| \| +\| Deputy lead \| \| \| \| \| +\| Engineering on-call \| \| \| \| \| +\| Database admin \| \| \| \| \| +\| DNS / infrastructure \| \| \| \| \| +\| Customer support lead \| \| \| \| \| +\| Executive sponsor \| \| \| \| \| + +--- + +## Post-launch + +- [ ] Schedule AAR within 1 to 2 weeks +- [ ] Document any deviations from runbook +- [ ] Capture metrics: rollback rate, time to launch, issues found, etc. +- [ ] File improvements to runbook for next launch diff --git a/skills/lead-magnet-design/SKILL.md b/skills/lead-magnet-design/SKILL.md new file mode 100644 index 0000000..29da923 --- /dev/null +++ b/skills/lead-magnet-design/SKILL.md @@ -0,0 +1,282 @@ +--- +name: lead-magnet-design +description: "Designing lead magnets that earn the email. The discipline of building gated content (ebooks, templates, checklists, swipe files, mini-courses, free tools) that delivers genuine standalone value while qualifying the lead and warming them for what comes next. Honest about thin-bait (overpromises, underdelivers), kitchen-sink-resource (everything, helps with nothing), and earned-value-magnet (delivers standalone value while qualifying the lead). Triggers on lead magnet, gated content, opt-in offer, ebook, checklist, template, swipe file, mini-course, free tool, content upgrade, freebie, opt-in, list-building offer. Also triggers when an audience is being asked for an email and the offer attached to that ask needs design discipline, when previous lead magnets converted but did not produce qualified leads, or when a lead magnet is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing gated content that earns the email. Distinguishes thin-bait (overpromises, underdelivers) from kitchen-sink-resource (everything, helps with nothing) from earned-value-magnet (delivers standalone value while qualifying the lead)" +display_order: 1 +--- + +# Lead Magnet Design + +A senior growth practitioner's playbook for designing lead magnets that earn the email. Templates, checklists, swipe files, mini-courses, free tools, ebooks. The discipline of building gated content that delivers genuine standalone value while qualifying the lead and warming them for the next conversation. + +Most lead magnets are bait. A vague headline, a thin PDF, an email gate, a follow-up sequence the reader resents. Conversion-rate metrics look fine because the form converted; the email list grows; and the unsubscribe rate climbs because the magnet was a transaction the reader regrets the moment they download. + +The lead magnets that work as compounding assets do something different. They deliver value the reader would have paid for if they had to. They qualify the lead by audience-fit, so the list that grows is the right list. They set up the next conversation honestly, so the follow-up sequence is a continuation rather than an apology. + +This skill is the parent-frame methodology for the growth tooling track. Calculators (`calculator-design`) and quizzes (`quiz-and-assessment-design`) are specific lead-magnet types covered as their own skills. This skill provides the methodology for deciding WHAT to build before deciding WHAT TYPE. + +The voice is the senior growth practitioner who has watched lead magnets earn long-term subscribers and watched them burn list trust within a single send. Practical, opinionated about format selection, willing to tell the reader when a lead magnet is the wrong investment for the goal. + +When to use this skill: scoping a lead magnet for the first time, auditing a lead magnet that converts but does not qualify, deciding which format fits a specific audience and offer, or designing the post-download sequence that turns the magnet into a relationship. + +--- + +## What this skill covers + +This skill spans lead magnet design as the parent discipline. The growth-tooling distinctions: + +- `lead-magnet-design` (this skill) is the parent-frame methodology. WHAT a magnet is, when to invest in one, which format fits, how to qualify the lead, how to set up the follow-up. +- `calculator-design` is one specific lead-magnet type with its own methodology (calculation transparency, tiered value, methodology disclosure). +- `quiz-and-assessment-design` is another specific lead-magnet type (scoring algorithms, result categorization, recommendation matching). +- `landing-page-copy` is the page-level discipline that wraps the magnet's offer. +- `content-distribution` is how the magnet reaches its audience. +- `content-strategy` is upstream: the topic decisions that earn investment in any one magnet. + +The audience: growth marketers, in-house product marketers, marketing teams, agencies running list-building work for clients, founders building their own funnels. + +Out of scope: long-form content marketing (covered by `content-strategy`); landing-page copy (covered by `landing-page-copy`); email sequence design at scale (covered by `email-sequences`); the specific tooling configurations that deliver the magnet (those stay implementation-side). + +--- + +## The lead magnet decision: when to build one, when not to + +Before designing the magnet, decide whether a magnet is the right investment. + +A lead magnet earns investment when: + +- The audience exists in volume but is not yet on the list. Traffic without conversion is the gap a magnet fills. +- The product or service has a long consideration cycle. The list builds the relationship across the consideration window. +- The audience has a specific, immediate problem that a focused resource can address. Magnets work when the gap they fill is concrete. +- The follow-up sequence has a real purpose. Without a sequence that turns subscribers into something (customers, community members, qualified leads), the magnet is list-building theater. + +A lead magnet does NOT earn investment when: + +- The audience would convert directly without a magnet. SaaS with a free trial, ecommerce with a discount code, or freemium with a low-friction signup may not need a magnet between the visitor and the product. +- The team cannot commit to the follow-up. A list without a sequence is a list that decays. +- The topic is too broad to focus a single resource. "Marketing" is not a magnet topic; "the welcome-email template that 4x'd our trial-to-paid rate" is. +- Sales calls or demos are the next step. If the goal is a booked call, design the call-booking flow, not the magnet. + +The decision is not "should we have a magnet"; it is "is the magnet the right next investment for this specific audience and goal." + +Detail in [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md). + +--- + +## Thin-bait vs kitchen-sink-resource vs earned-value-magnet + +The keystone framing. + +Thin-bait. "10 tips for X" PDFs that are 200 words of fluff behind an email gate. The headline overpromises; the contents underdeliver. The reader downloads, skims, deletes, and unsubscribes within a week. The conversion-rate metric looks fine; the list quality and brand trust both degrade. Cost: every subscriber acquired through thin-bait costs more than they appear to, because the unsubscribe rate, the reduced sender reputation, and the reduced list-trust each compound. + +Kitchen-sink-resource. 80-page "Ultimate Guide" containing everything anyone could want about the topic. Includes nothing the reader actually needs RIGHT NOW. Bookmarked, never read, eventually forgotten. Cost: the magnet does not produce the moment of "I needed this and got it," which is the moment the relationship starts. Subscribers stay on the list out of inertia; the relationship never deepens; future emails get ignored. + +Earned-value-magnet. Solves a specific, immediate problem the reader has. Genuine standalone value, the kind that would be worth paying for if it were not free. Qualifies the lead by audience-fit. Warms the reader for a specific related offer that follows. The reader downloads, uses the resource, gets the result, and remembers the brand as the source of that result. + +The litmus test. Hand the magnet to a non-subscriber in the target audience. Watch them use it. Does the resource produce the promised outcome inside the time the reader was willing to spend? If yes, the magnet is earned-value. If the reader downloads and never opens, the magnet is thin-bait or kitchen-sink-resource regardless of how the headline reads. + +--- + +## Format selection + +Magnets come in formats. Each format has strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +Templates. A starting artifact the reader fills in or adapts. Strong for audiences who need to produce a specific deliverable (a brief, a spec, a pitch deck, an email). Strong because the value is immediate and concrete. Weak when the template is too generic to feel custom. + +Checklists. A sequence of items to verify or complete. Strong for audiences executing a known process where the gap is comprehensiveness, not direction. Strong because the format signals "you can use this in 10 minutes." Weak when the checklist reads as marketing rather than as a working tool. + +Swipe files. A curated collection of examples (subject lines, headlines, ad copy, design references). Strong for audiences who learn from examples and need inspiration rather than instruction. Weak when the swipes are stale or unattributed. + +Mini-courses. A multi-part email or video sequence delivering structured learning. Strong for audiences willing to invest sequential attention; strong because the sequence creates multiple touchpoints. Weak when the course is filler or when each lesson does not stand on its own. + +Free tools (calculators, quizzes, generators). Interactive web tools that produce a result. Strong for audiences who want a personalized output rather than a generic resource. Strong because the interaction qualifies the lead by inputs. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Ebooks. Long-form treatment of a topic. Strong for audiences researching a complex decision; strong when the ebook reads as a definitive resource. Weak when used as a default format for topics that would have served the reader better as a checklist or template. + +Video series. Sequential video content delivered behind a gate. Strong for topics that benefit from demonstration; strong for audiences who learn from video. Weak when the production overhead exceeds the topic's value or when the audience does not consume video content at the time-of-magnet moment. + +The choice depends on the audience's preferred consumption mode, the topic's natural shape, and the production overhead the team can sustain. A great template often outperforms a mediocre ebook on the same topic. + +Detail in [`references/format-selection-patterns.md`](references/format-selection-patterns.md). + +--- + +## The "would they pay for this" test + +The single test that distinguishes earned-value from thin-bait. + +The question. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails this test is signaling that the value is below the threshold of "I would pay for this," which means the reader's time investment to download and consume it is at the edge of "worth it." + +The test is not perfect. Some valuable resources are hard to price (how much is a great checklist worth?). But the test catches the magnets that exist primarily to capture an email rather than to deliver value. + +Three failure modes the test catches. + +- The 5-page PDF that summarizes blog content. Free elsewhere; not pay-worthy. +- The "Ultimate Guide" that nobody finishes. Pay-worthy in theory; not delivered in usable form. +- The template that is so generic it adds no value over starting from scratch. Pay-worthy framing; thin in execution. + +The test the magnet should pass. + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +If the magnet passes the test, it earns the email. If it fails, redesign before launching. + +Detail in [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md). + +--- + +## Audience-fit qualification + +The magnet as filter, not just bait. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). + +Filter through the headline. The headline tells the wrong audience to opt out. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, and consumer-app PMs. The conversion rate from the visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +Filter through the topic. A magnet on a niche topic attracts a niche audience. Generic topics attract generic audiences who churn off the list. Specific topics attract specific audiences who stay. + +Filter through the format. A 60-minute video course filters out audiences who will not invest 60 minutes. A 2-page checklist filters in audiences who want quick wins. The format signals what the brand expects of the relationship. + +Filter through the offer adjacent to the magnet. The follow-up sequence often makes a soft offer for a related product or service. The magnet should be tightly enough scoped that the audience who downloads it is also the audience who would consider the adjacent offer. + +The filtering principle. A magnet that converts 50 percent of visitors but produces 5 percent qualified leads is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. Optimize for the qualified lead, not for the surface conversion rate. + +Detail in [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md). + +--- + +## Title and presentation discipline + +The magnet's title is the conversion lever and the qualification filter at the same time. + +Title patterns that work. + +- Specific outcome + specific audience. "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." +- Specific deliverable + specific situation. "The pricing one-pager for SaaS founders raising a seed round." +- Specific framework + specific problem. "The 4-question framework for deciding whether to fire a customer." +- Specific count + specific value. "23 onboarding emails, with the open and click rate for each." + +Title patterns to avoid. + +- "Ultimate Guide to X." Vague. Promises too much. Underdelivers reliably. +- "The Complete X Playbook." Same failure mode. Promises completeness; delivers volume. +- "Free [Topic] Resource." Generic. Tells the reader nothing about why this resource is the one to download. +- "10 Tips for Better X." Listicle framing signals thin content. + +Presentation discipline beyond the title. + +- The cover or preview image should reinforce the specificity. A clean type-driven cover often outperforms a cluttered one. +- The landing page (handled by `landing-page-copy`) should preview the magnet, not just describe it. +- The first page of the magnet should deliver value within the first read, not warm up with author bio and brand-positioning. + +Detail in [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md). + +--- + +## Delivery and follow-up sequence design + +The sequence is the magnet's second act. Without it, the magnet is one transaction; with it, the magnet starts a relationship. + +The delivery moment. The reader fills the form and expects the resource immediately. Delivery delay (manual review, scheduled send) breaks the moment. The first email should deliver the asset and confirm the next step. + +The first 7 days. The reader is most engaged in the days right after download. The sequence should make use of that window: a follow-up that helps them apply the resource, a related artifact that extends the value, a soft introduction to the brand and the next step. + +The medium-term. Days 8 to 30, the sequence transitions from "value-add" to "ongoing relationship." Newsletter signup, related-content rotation, or a soft offer for the adjacent product or service. + +The honest offer. When the sequence makes an offer, the offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course; the audience signal would be wasted. + +The opt-out. A reader who unsubscribes from the magnet sequence is not a failure; they are a clean filter. The list quality stays higher when the unfit subscribers leave on their own. + +Detail in [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md). + +--- + +## Format-specific quality gates + +Each format has quality gates specific to that format. A great template fails different tests than a great mini-course. + +Template gates. Does the reader produce a usable artifact in under 30 minutes? Are the prompts specific enough to feel custom? Is the template adaptable across the segment of the audience or rigidly bound to one situation? + +Checklist gates. Is each item actionable today? Does the checklist sequence reflect actual workflow order? Is the checklist scoped narrowly enough to feel comprehensive within scope? + +Swipe file gates. Are the swipes attributed (where possible)? Are they current (not 5 years stale)? Is the curation visible (the reader can see why each swipe is included)? + +Mini-course gates. Does each lesson deliver standalone value (not "you will learn the answer in lesson 4")? Is the cumulative time commitment honest in the title? Does the course end with a clear next step (not just "thanks for taking the course")? + +Calculator and quiz gates. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Ebook gates. Is the ebook navigable (table of contents, page numbers, summary boxes) such that a reader who does not finish still extracts value? Is the production quality consistent with the brand it represents? + +Video series gates. Is each video shot at a quality the brand can sustain? Is the audio consistently clear? Is the runtime honest in the listing? + +Each format's gates exist because thin-bait can hide in any format. The quality gates make hiding harder. + +Detail in [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md). + +- "Conversion rate is great, list quality is terrible." Thin-bait pattern; magnet attracts the wrong audience or fails to deliver the promised value. +- "We ship a magnet; nothing happens after." No follow-up sequence; the magnet is one transaction rather than the start of a relationship. +- "Our 80-page Ultimate Guide gets downloaded but never read." Kitchen-sink-resource; comprehensive in scope, useless in application. +- "We changed the format from PDF to webinar; conversion rate dropped." Format mismatched to audience; the audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. +- "The magnet works in paid traffic but not organic." The audience reaching the magnet through paid is different from the organic audience; the magnet may fit one but not the other. +- "Subscribers go cold after the first email." Sequence absent or poorly designed; the value evaporates after delivery. +- "We have 5 magnets; one converts well, the others are dead." Magnet portfolio not maintained; audiences move and topics decay; periodic audit missing. +- "The follow-up offer mismatches the magnet's audience." Magnet attracted one segment; offer pitches a different one; conversion to the offer near zero. +- "We cannot tell which traffic source produces qualified leads." Attribution missing or rolled up at the wrong level; lead-quality signal not connected back to source. +- "The team built three magnets last quarter; the team avoids talking about results." Magnets shipped without success metric definition; results ambiguous or quietly underwhelming. + +--- + +## The framework: 12 considerations for lead magnet design + +When designing or auditing a lead magnet, walk these 12 considerations. + +1. The magnet decision. Is a magnet the right investment for this audience and goal, or does the funnel work without one? +2. Earned-value, not thin-bait or kitchen-sink-resource. The magnet would be worth paying for; it solves a specific problem in usable form. +3. Format matched to audience and topic. The format reflects how the audience consumes content and how the topic naturally shapes. +4. The "would they pay for this" test. Pass before launching. +5. Audience-fit qualification. The magnet filters for the right audience, not just maximum conversion. +6. Title and presentation discipline. Specific, honest, signals what is inside. +7. Delivery in the moment. First email arrives immediately; the asset is in that email. +8. Follow-up sequence designed. The 30 days after download have a purpose, an arc, and a soft offer that matches the audience. +9. Format-specific quality gates passed. The format's specific tests verified before launch. +10. Lead quality measured, not just conversion rate. What percentage of subscribers fit the audience the magnet was designed for? +11. Attribution to source. The team can tell which source produced which leads at which quality. +12. Audit cadence. The magnet portfolio gets reviewed periodically; underperformers retired. + +The output of the framework is a lead magnet that earns the email by delivering real value, qualifies the audience by filtering at the headline and topic level, and starts a relationship through a sequence the team has actually designed. + +--- + +## Reference files + +- [`references/lead-magnet-decision-criteria.md`](references/lead-magnet-decision-criteria.md) - When a lead magnet is the right investment and when it is not. The conditions that make magnets worth the build. +- [`references/format-selection-patterns.md`](references/format-selection-patterns.md) - Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit, conversion baselines. +- [`references/would-they-pay-for-this-test.md`](references/would-they-pay-for-this-test.md) - The pricing thought experiment that distinguishes earned-value from thin-bait. Worked examples and failure modes. +- [`references/audience-fit-qualification.md`](references/audience-fit-qualification.md) - The magnet as filter. Filtering through headline, topic, format, and follow-up offer. +- [`references/title-and-presentation-discipline.md`](references/title-and-presentation-discipline.md) - Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. +- [`references/delivery-and-follow-up-sequences.md`](references/delivery-and-follow-up-sequences.md) - Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. +- [`references/format-specific-quality-gates.md`](references/format-specific-quality-gates.md) - Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. +- [`references/lead-magnet-anti-patterns.md`](references/lead-magnet-anti-patterns.md) - The patterns that look like lead magnets but do not behave like them. +- [`references/common-lead-magnet-failures.md`](references/common-lead-magnet-failures.md) - 10+ failure patterns with diagnoses and cures. + +--- + +## Closing: magnets earn the email when they earn the reader's afternoon + +The magnets that work as compounding assets are the ones the reader uses. Not downloads. Not bookmarks. Uses. The reader opens the resource, applies it, and gets a result they would have paid for if they had to. + +That is the bar. Below the bar is thin-bait (the resource is too thin to use) or kitchen-sink-resource (too much to consume). Above the bar is the relationship: the reader remembers the brand as the source of the result, opens the next email, and considers the offer when it comes. + +The discipline is in the design choices upstream of the form. The format matched to the audience and topic. The title that filters and earns. The pricing thought experiment that catches the thin magnets before launch. The follow-up sequence designed before the magnet ships, not after. The audit cadence that retires the magnets that stopped working. + +When in doubt, ask: would the audience pay for this if it were not free, and will the team commit to the sequence after the download? If yes to both, the magnet earns the email. If no to either, redesign or do not ship. diff --git a/skills/lead-magnet-design/references/audience-fit-qualification.md b/skills/lead-magnet-design/references/audience-fit-qualification.md new file mode 100644 index 0000000..7278886 --- /dev/null +++ b/skills/lead-magnet-design/references/audience-fit-qualification.md @@ -0,0 +1,171 @@ +# Audience-fit qualification + +The magnet as filter, not just bait. Filtering through headline, topic, format, and follow-up offer. + +A great magnet does two things at once. It delivers value (which earns the email). It also filters for the right audience (which earns the long-term relationship). The filtering is the difference between a list that grows and a list that grows in the right direction. + +--- + +## The filtering principle + +The magnet's job is not to maximize email captures. It is to maximize qualified email captures. + +A magnet that converts 50 percent of visitors but produces 5 percent qualified leads (visitors who match the audience the magnet was designed for) is worse than a magnet that converts 15 percent of visitors and produces 40 percent qualified leads. The qualified-lead-rate metric matters more than the surface conversion rate. + +The filtering happens at multiple points: the headline, the topic, the format, the landing-page copy, and the follow-up offer. Each is a filter that lets in the right audience and turns away the wrong one. + +--- + +## Filter through the headline + +The headline is the first filter. The right audience self-selects in; the wrong audience self-selects out. + +Specific outcome plus specific audience. "The 5-step framework for B2B SaaS pricing decisions" filters out ecommerce founders, freelancers, consumer-app PMs. The conversion rate from visiting traffic drops; the conversion rate from the right segment of that traffic is what compounds. + +Specific situation. "The pricing one-pager for SaaS founders raising a seed round" filters out everyone except SaaS founders raising a seed round. That is a tiny audience; the audience that converts is exactly the audience the brand wants. + +Specific deliverable. "The 23-email sequence we send to trial signups who go cold" filters in PMs, growth marketers, and founders running SaaS funnels. Filters out everyone else. + +The headline test. Read the headline. Who in the broader audience self-selects out? If the answer is "no one, anyone might want this," the headline is not filtering. Generic headlines attract generic audiences; specific headlines attract specific audiences. + +--- + +## Filter through the topic + +The topic itself filters before the headline polishes the message. + +Niche topics attract niche audiences. "Pricing for B2B SaaS founders raising a seed round" is a topic that filters by definition. The audience for this topic is small but precise. + +Generic topics attract generic audiences. "Marketing tips" attracts everyone, which means it attracts no one specifically. The list grows; the lead quality dilutes. + +The topic-segmentation question. What audience segment is this topic specifically valuable for? If the answer is "everyone," the topic is too broad. Narrow until the answer is "the segment we want to serve." + +Topic-narrowing examples. + +- Too broad: "Email marketing tips." +- Narrowed: "Welcome-email sequences for B2B SaaS trials." +- Narrowed further: "The 7-email welcome sequence for B2B SaaS trials in the 5-50 employee segment." + +Each narrowing reduces the addressable audience and increases the qualification of those who convert. + +--- + +## Filter through the format + +The format signals what the brand expects of the relationship. + +A 60-minute video course filters out audiences who will not invest 60 minutes. This is sometimes the right filter (for high-investment audiences) and sometimes the wrong one (for skim-and-apply practitioners). + +A 2-page checklist filters in audiences who want quick wins. This is often the right filter for practitioners executing known processes. + +A free tool with detailed inputs filters in audiences with concrete situations the tool addresses. The inputs themselves qualify the lead. + +An 80-page ebook filters in audiences researching a complex decision. Filters out audiences seeking quick artifacts. + +The format choice should match the audience the magnet is designed to attract. A mismatch (a 60-minute course for a skim audience, a 2-page checklist for an in-depth research audience) breaks the filter. + +--- + +## Filter through the landing-page copy + +The landing page is the magnet's marketing layer. It filters by amplifying the headline and topic signals. + +Audience-specific copy. "For SaaS founders" beats "For founders" beats "For everyone." Each audience-specific cue filters. + +Situation-specific copy. "If you are scaling from 100 to 1000 customers, here is the playbook." Filters by situation. + +Result-specific copy. "After implementing this template, our trial-to-paid rate moved from 8 percent to 14 percent." Filters by who cares about that result. + +Anti-filter copy. "This is for everyone in marketing." Generic. No filter. Attracts the wrong audience and dilutes the list. + +The landing page should sharpen the filter the headline and topic establish, not dilute it. + +--- + +## Filter through the follow-up offer + +The follow-up offer is the late-stage filter. The audience who downloads the magnet and then engages with the offer is the audience the program needs to compound. + +Offer-magnet alignment. A magnet on B2B onboarding should be followed by an offer relevant to B2B teams. A misalignment (a magnet on B2B onboarding followed by an offer for consumer-app courses) wastes the qualification the magnet did. + +Offer-audience alignment. The offer should fit the audience the magnet attracted. If the magnet attracted SaaS founders and the offer is for enterprise sales teams, the audience signal is wasted. + +Offer-stage alignment. A top-of-funnel magnet should be followed by an offer at the right consideration stage (not "buy now" 3 emails after download for a high-ticket product). + +The follow-up offer's conversion rate is the qualification metric that matters most. A list that engages with the offer is a list the magnet qualified well. + +--- + +## The qualified-lead metric + +Beyond conversion rate, qualified-lead rate is the metric the magnet's filter should be measured by. + +Definition. Of the subscribers acquired through the magnet, what percentage match the audience profile the magnet was designed for? + +Measurement methods. + +- Self-reported segment data. Capture audience-segment data on the form (company size, role, industry). Measure the percentage that match. +- Email engagement. Measure open and click rates on follow-up emails relevant to the target audience. Low engagement signals audience mismatch. +- Downstream conversion. Measure conversion to the next step (trial, demo, purchase). Low downstream conversion despite high upstream engagement signals audience mismatch. + +The qualified-lead-rate target. Programs vary, but 40-70 percent of subscribers matching the target audience is a reasonable bar for a well-filtered magnet. Below 30 percent suggests the filter is broken; above 70 percent suggests the filter may be too narrow (and the magnet may be missing audience the brand could serve). + +--- + +## When to widen the filter, when to narrow + +Filter-tuning is part of the magnet's lifecycle. + +Widen the filter when: + +- Conversion rate is healthy but the audience the brand serves is broader than the magnet captures. +- The qualified-lead rate is high (suggesting the filter could let in more without sacrificing quality). +- The team is launching a broader product or service that fits a wider audience. + +Narrow the filter when: + +- Lead quality is diluting (the magnet attracts subscribers who do not match the brand's offering). +- The follow-up sequence's engagement is low because the audience does not match the offers. +- The team is focusing on a specific segment and wants the magnet to filter for it. + +The discipline. Filter tuning is iterative. The magnet's headline, topic, and follow-up can be adjusted to widen or narrow the filter as the program evolves. + +--- + +## Common filter failures + +The headline does not filter. Generic title; attracts everyone; lead quality dilutes. + +The topic is too broad. "Marketing" rather than "B2B SaaS pricing." Generic topic; generic audience. + +The format is mismatched. A long-form video for a skim audience; the wrong audience self-selects. + +The landing page softens the filter. Audience-specific headline followed by generic landing-page copy that anyone could read; the filter weakens. + +The follow-up offer mismatches. Magnet attracts one audience; offer pitches a different one; downstream conversion drops. + +The team measures conversion rate but not lead quality. The surface metric looks fine; the real metric (qualified-lead rate) is unmeasured; the magnet looks like a success while the list quality degrades. + +The pattern across failures: the team optimizes for the easier metric (conversion rate) and loses the harder metric (qualified-lead rate). The discipline is to measure both and to tune for the lead quality the program needs. + +--- + +## The high-conversion-low-quality trap + +A magnet can convert at exceptional rates while producing terrible lead quality. The trap surfaces when the team celebrates the conversion rate and ignores the downstream signal. + +The pattern. A generic, broadly-appealing magnet ("Marketing Tips for 2026") converts at 25 percent. The list grows quickly. The follow-up sequence sees low engagement; the offers convert at near-zero rates; the unsubscribe rate is high. + +The diagnosis. The magnet attracted everyone, including audiences the brand cannot serve. The high conversion rate masked the low lead quality. + +The fix. Narrow the magnet's filter. The conversion rate will drop; the lead quality will rise; the program's compounding metric (qualified-lead growth) will improve. + +--- + +## Methodology-level choices that stay in the public skill + +The filtering principle. Filter through headline, topic, format, landing-page, and follow-up offer. The qualified-lead metric and how to measure it. When to widen and when to narrow. The high-conversion-low-quality trap. Common filter failures. + +## Implementation choices that stay internal + +Specific filter-tuning conventions for the team's audience. Specific qualified-lead-rate baselines for specific magnets. Specific segment-data capture methods on forms. Specific tooling for engagement and downstream-conversion measurement. These vary by team. diff --git a/skills/lead-magnet-design/references/common-lead-magnet-failures.md b/skills/lead-magnet-design/references/common-lead-magnet-failures.md new file mode 100644 index 0000000..30ea197 --- /dev/null +++ b/skills/lead-magnet-design/references/common-lead-magnet-failures.md @@ -0,0 +1,187 @@ +# Common lead magnet failures + +10+ failure patterns with diagnoses and cures. The patterns that surface as "the magnet underperformed" or "the list is not converting" or "we cannot tell if the magnet worked." + +--- + +## "Conversion rate is great, list quality is terrible." + +The diagnosis. Thin-bait pattern. The magnet attracts the wrong audience or fails to deliver promised value. Conversion-rate metric looks fine because the form converted; the lead quality metric (which is the metric that matters for downstream conversion) is poor. + +The cure. Apply the "would they pay for this" test (`references/would-they-pay-for-this-test.md`). Apply audience-fit qualification (`references/audience-fit-qualification.md`). Strengthen the magnet until it earns the email rather than baits it. + +--- + +## "We ship a magnet; nothing happens after." + +The diagnosis. No follow-up sequence. The magnet is one transaction rather than the start of a relationship. + +The cure. Design the sequence before shipping the magnet (`references/delivery-and-follow-up-sequences.md`). The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## "Our 80-page Ultimate Guide gets downloaded but never read." + +The diagnosis. Kitchen-sink-resource pattern. Comprehensive in scope, useless in application. The reader cannot consume the resource in the time they were willing to spend. + +The cure. Narrow the topic until the magnet addresses one specific problem in usable form. The 80-page guide often becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## "We changed the format from PDF to webinar; conversion rate dropped." + +The diagnosis. Format mismatched to audience. The audience would consume a PDF in 10 minutes but will not block 60 minutes for a webinar. + +The cure. Format selection (`references/format-selection-patterns.md`). Match the format to the audience's preferred consumption mode and the topic's natural shape. The format change might still be right (if the new format better serves a different segment) but the metric drop is signal. + +--- + +## "The magnet works in paid traffic but not organic." + +The diagnosis. The audience reaching the magnet through paid is different from the organic audience. The magnet may fit one but not the other. + +The cure. Understand the audience differences. Paid traffic often has different intent and different audience composition than organic. The magnet may need a separate version for each, or the magnet may need to be retitled to match the actual audience reaching it. + +--- + +## "Subscribers go cold after the first email." + +The diagnosis. Sequence absent or poorly designed. The value evaporates after delivery. + +The cure. Design the first-7-days arc to add value progressively (`references/delivery-and-follow-up-sequences.md`). Each email should add something the reader can use; the cumulative arc deepens the relationship. + +--- + +## "We have 5 magnets; one converts well, the others are dead." + +The diagnosis. Magnet portfolio not maintained. Audiences move and topics decay; the periodic audit is missing. + +The cure. Audit the portfolio (`references/lead-magnet-anti-patterns.md`, "How to detect anti-patterns in the portfolio"). Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## "The follow-up offer mismatches the magnet's audience." + +The diagnosis. Magnet attracted one segment; offer pitches a different one. The audience signal the magnet captured was wasted. + +The cure. Align the offer to the audience the magnet attracts (`references/delivery-and-follow-up-sequences.md`, "The offer-magnet alignment"). If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## "We cannot tell which traffic source produces qualified leads." + +The diagnosis. Attribution missing or rolled up at the wrong level. Lead-quality signal is not connected back to source. + +The cure. Capture source attribution at the form level. Measure lead quality (audience-fit, downstream conversion) per source. The diagnostic data informs which sources warrant further investment. + +--- + +## "The team built three magnets last quarter; the team avoids talking about results." + +The diagnosis. Magnets shipped without success metric definition. Results ambiguous or quietly underwhelming. + +The cure. Define the success metric before building (`references/lead-magnet-decision-criteria.md`, "The success metric is defined"). What does "the magnet worked" look like? Without the definition, evaluation is impossible and underperformers do not get retired. + +--- + +## "Downloads are high; trial signups are unchanged." + +The diagnosis. The magnet captures emails but does not move the downstream metric the team cares about. Either the magnet's audience does not match the trial-buying audience, or the sequence does not bridge to the offer. + +The cure. Trace the funnel from magnet download to trial signup. Identify the drop. The drop is often at the offer step (audience misalignment) or at the sequence step (no clear path from magnet to offer). + +--- + +## "The magnet got shared on social; we got 1000 subscribers; none converted." + +The diagnosis. The magnet's distribution outpaced its audience-fit. A viral magnet attracts an audience that does not match the brand's offer. + +The cure. This is a design tradeoff. Shareable magnets are great for reach but often produce diluted lead quality. Either accept the dilution and have a long path to qualification, or design the magnet to be less shareable but more audience-specific. + +--- + +## "We tried 12 different titles; conversion rate did not move." + +The diagnosis. Title testing without addressing the underlying audience-fit. The title is the surface; the audience-fit is the substance. If the substance is wrong, no title fixes it. + +The cure. Step back from title testing. Apply the audience-fit qualification (`references/audience-fit-qualification.md`). The title can amplify a strong audience-fit; it cannot create one. + +--- + +## "The magnet's references are stale and conversion is dropping." + +The diagnosis. Magnet decay. Screenshots, statistics, tooling references go out of date. The reader notices and engagement drops. + +The cure. Maintenance discipline (`references/lead-magnet-decision-criteria.md`, "When to retire a magnet"). Quarterly review for active magnets. Update or retire when references decay. + +--- + +## "We have a great magnet; the landing page does not convert." + +The diagnosis. The magnet is strong but the landing page (which is `landing-page-copy`'s domain) does not preview the value, frame the audience, or close the visitor. + +The cure. Apply landing-page-copy discipline. Show pages from inside the magnet. Frame the audience explicitly. Make the conversion action obvious and the friction minimal. + +--- + +## "The magnet got featured in [a major newsletter]; we lost the signal we built." + +The diagnosis. A traffic spike from a misaligned audience can dilute the qualified-lead-rate metric. The featured audience may not match the brand's offer. + +The cure. Distinguish "qualified subscriber" from "any subscriber" in the metric. The traffic spike grew the list; the qualified list grew less. The signal is intact; the metric needs disaggregation. + +--- + +## "We cannot keep the sequence content fresh." + +The diagnosis. The sequence's content needs ongoing maintenance. The team did not budget for it. + +The cure. Either reduce the sequence to evergreen content the team can sustain, or accept the maintenance cost as part of the magnet's true cost. Quarterly review of every active sequence (`references/delivery-and-follow-up-sequences.md`, "The maintenance discipline"). + +--- + +## "The magnet had great reviews; the lead-quality metric is mediocre." + +The diagnosis. Reviews are signal about the resource's quality. Lead quality is signal about the audience-fit. The two are different. A great resource for the wrong audience produces good reviews and mediocre lead quality. + +The cure. Audience-fit qualification (`references/audience-fit-qualification.md`). The magnet may need a tighter filter at the title and topic level, even if the resource itself is strong. + +--- + +## "We built a magnet for our PMM team's pet topic; nobody downloaded." + +The diagnosis. Vanity-magnet pattern. The topic was chosen for internal interest, not audience need. + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. + +--- + +## "The team ships magnets every quarter; conversion rate is the only metric we track." + +The diagnosis. Single-metric tracking misses lead quality, sequence engagement, downstream conversion, and retention. The conversion rate can look fine while the broader signal is weak. + +The cure. Multi-metric tracking. Conversion rate, qualified-lead rate, sequence engagement, downstream conversion, and unsubscribe rate together tell the story. Single-metric tracking misleads. + +--- + +## The pattern across failures + +Most lead magnet failures fall into one of three patterns. + +Pattern 1: The magnet does not deliver value. Thin-bait, kitchen-sink, undelivered-promise. The fix is to strengthen or kill the magnet. + +Pattern 2: The magnet attracts the wrong audience. Everyone-magnet, viral-but-misaligned, vanity-magnet. The fix is to tighten the filter or reframe the audience. + +Pattern 3: The relationship after the download fails. Orphan-magnet, sequence-too-short, misaligned-offer, follow-up-spam. The fix is to design the sequence with as much care as the magnet itself. + +The metric pattern: lead magnet failures often look fine on the conversion rate. The signal is in the lead quality, the sequence engagement, and the downstream conversion. Programs that track only the conversion rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, relationship). The principle that conversion rate alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md b/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md new file mode 100644 index 0000000..1354ac6 --- /dev/null +++ b/skills/lead-magnet-design/references/delivery-and-follow-up-sequences.md @@ -0,0 +1,188 @@ +# Delivery and follow-up sequences + +Delivery moment, first-7-days arc, medium-term sequence, honest offer, clean opt-out. The sequence is the magnet's second act; without it, the magnet is one transaction. + +A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams that build the magnet but skip the sequence capture emails that go cold. + +--- + +## The delivery moment + +The reader fills the form and expects the resource immediately. The first email confirms the moment. + +What the delivery email should do. + +- Deliver the asset directly (link, attachment, or in-line content). The reader did not opt in to wait. +- Confirm the audience-fit signal. Acknowledge what the reader is here for. +- Set up the next email. "I will send you [related artifact] tomorrow" creates a hook for the next touchpoint. +- Avoid friction. No double opt-in unless required by jurisdiction. No survey-before-asset. The reader gets the resource first. + +What the delivery email should NOT do. + +- Make an offer. The reader has not yet experienced the magnet's value; offering anything is premature. +- Bury the asset. The link or attachment should be near the top, not after three paragraphs of brand-positioning. +- Apologize for the email. "Thanks for downloading, here is your resource" without filler is honest. + +Delivery delay risk. Delays of more than 5 minutes break the moment. Manual review, scheduled sends, or batch processing all introduce delay. Automate the delivery to minimize lag. + +--- + +## The first 7 days arc + +The reader is most engaged in the days right after download. The sequence should make use of that window. + +Day 0: Delivery. Asset in hand. The reader can act on the magnet immediately. + +Day 1-2: Application help. A follow-up that helps the reader apply the resource. "The 3 things people miss when implementing the [magnet]" or "the worked example we use ourselves." Adds value to the magnet without yet pitching anything. + +Day 3-4: Adjacent value. A related artifact, case study, or insight that extends the magnet's value. Reinforces the brand as a source of useful resources. + +Day 5-7: Soft introduction to the brand. Who the team is, what they work on, what kinds of problems they solve. Soft framing of the next step (newsletter signup, related product, demo). + +The 7-day arc principle. Every email in the first 7 days should add value, not extract. The relationship is being built; extraction breaks the trust the magnet earned. + +--- + +## The medium-term sequence + +Days 8-30, the sequence transitions from "value-add" to "ongoing relationship." + +The transition options. + +- Newsletter signup. Move the subscriber to the regular newsletter cadence. The relationship continues at the brand's normal pace. +- Related-content rotation. A series of additional resources, case studies, or insights related to the magnet's topic. The subscriber stays engaged in the topic area. +- Soft offer for the adjacent product or service. A demo invitation, a trial signup, a case study of a similar customer. The offer matches the audience the magnet attracted. + +The honest offer principle. The offer should match the magnet's audience. A magnet on B2B onboarding should not pitch a consumer course. The audience signal would be wasted. + +The hard-sell trap. Some sequences pivot too early to hard selling, before the reader has had time to recognize the value. The early hard sell breaks trust. The discipline is to earn the right to pitch through demonstrated value first. + +--- + +## The offer-magnet alignment + +The offer that follows the magnet must match the audience the magnet attracted. + +Worked example: aligned offer. + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: SaaS founders, growth marketers, and PMs running SaaS funnels. +The offer: a B2B SaaS lifecycle email tool with a 14-day trial. + +The audience the magnet attracted is the audience the offer serves. The conversion to trial is high relative to baseline. + +Worked example: misaligned offer. + +The magnet: "The 7-email welcome sequence for B2B SaaS trials." +The audience attracted: as above. +The offer: a marketing analytics platform aimed at enterprise marketing teams. + +The audience the magnet attracted is not the audience the offer serves. The conversion to demo is near zero. The audience signal was wasted. + +The alignment discipline. Before designing the magnet, identify the offer the magnet's audience will be pitched. If the offer does not exist or does not match, redesign the magnet (or the offer) before shipping. + +--- + +## The clean opt-out + +A reader who unsubscribes from the magnet sequence is not a failure. They are a clean filter. + +The principle. The list quality stays higher when the unfit subscribers leave on their own. A subscriber who is not the right audience for the offer is a subscriber whose engagement will be low; their unsubscribe is signal, not loss. + +The mechanics. + +- Make unsubscribe easy. One-click is honest; multi-step is friction the brand pays for in trust. +- Do not interrogate on the way out. "We are sorry to see you go, please answer 3 questions" is friction. +- Acknowledge the unsubscribe gracefully. The reader was a subscriber; they should leave with the brand intact. + +The unsubscribe-as-feedback loop. High unsubscribe rates after specific emails signal that the email did not match the audience or the value proposition. The signal informs sequence revision. + +--- + +## Sequence cadence considerations + +How frequently to send. + +Day 0-7: daily or every-other-day is honest. The reader just downloaded; engagement is high; the sequence can use the window without feeling spammy. + +Day 8-30: 2-4 emails per week is reasonable. Frequency depends on the value being delivered; if each email adds value, higher frequency is sustained. + +Day 30+: settle into the brand's normal cadence. Newsletter weekly, monthly, or per-publication. Whatever the brand sustains. + +Cadence-too-frequent risk. Daily emails for 30+ days exhaust the reader. The unsubscribe rate climbs. + +Cadence-too-infrequent risk. Weekly cadence in the first 7 days lets the magnet's momentum fade. The reader downloads, applies, and forgets the brand. + +--- + +## Sequence-engagement measurement + +The sequence's metrics surface whether the magnet did its qualifying job. + +Open rates. The audience opens what is interesting to them. Low open rates after the first email signal audience mismatch or sequence-content mismatch. + +Click-through rates. Clicks signal interest in specific content or offers. Low click-through on the offer email signals offer-magnet misalignment. + +Conversion to next step. Trials, demos, purchases. The downstream metric that matters most. Low conversion despite high engagement signals offer mismatch or pricing-mismatch. + +Unsubscribe rates. A reasonable rate (2-5 percent over the first 30 days) is normal. Higher rates signal cadence mismatch or audience mismatch. + +The metrics together tell the story. The sequence either qualifies and converts the audience the magnet attracted, or it surfaces the mismatch the magnet missed. + +--- + +## When the sequence fails + +The sequence sends; engagement drops; conversion is low. The diagnosis often surfaces magnet-side failures. + +Diagnosis: the magnet attracted the wrong audience. The sequence's content is right for the audience the magnet was designed for, but the audience the magnet actually attracted is different. The fix is upstream: tighten the magnet's filter. + +Diagnosis: the offer is misaligned. The audience is right; the offer does not match. The fix is to change the offer (or the magnet, if the offer is fixed). + +Diagnosis: the sequence is too long or too frequent. Engagement starts strong and drops as fatigue sets in. The fix is to trim the sequence or space the emails. + +Diagnosis: the sequence's value drops off. The first emails added value; the later emails became repetitive or extractive. The fix is to redesign the later emails to continue adding value. + +Diagnosis: the sequence's tone shifted. The early emails were honest; the later emails became salesy. The fix is to restore the honest tone. + +The sequence is part of the magnet's design. Failures in the sequence often surface as conversion-rate or engagement metrics, but the fix is sometimes upstream in the magnet itself. + +--- + +## The maintenance discipline + +Sequences decay. Email links break, references go stale, offers change. + +The maintenance cadence. Quarterly review of every active sequence. Are links working? Are references current? Does the offer at the end still match the brand's current product or service? + +Stale-sequence risk. A subscriber who clicks a broken link or sees a reference to a discontinued product disengages immediately. The brand looks careless. + +The retire decision. Sequences for retired magnets should be retired. Subscribers acquired through the magnet should be moved to the appropriate ongoing sequence (newsletter or other). + +--- + +## Common sequence failures + +No sequence. The magnet ships; subscribers download; nothing follows. The list goes cold. + +Sequence too short. 2-3 emails and done. The relationship does not deepen. + +Sequence too long. 30+ emails over months. Subscribers fatigue. + +Sequence pivots to hard sell too early. The trust the magnet earned gets spent before the value has been demonstrated. + +Offer misaligned. Magnet attracts one audience; offer pitches another. + +Stale references. Links break; product names changed; case studies outdated. + +Cadence mismatch. Too frequent or too infrequent for the engagement the audience can sustain. + +--- + +## Methodology-level choices that stay in the public skill + +The delivery moment principles. The first-7-days arc. The medium-term transition. The offer-magnet alignment principle. The clean opt-out. Cadence considerations. Sequence-engagement measurement. Diagnostic patterns when the sequence fails. The maintenance discipline. + +## Implementation choices that stay internal + +Specific email copy for specific magnets. Specific sequence templates the team uses. Specific tooling for delivery automation, sequence platforms, and engagement measurement. The team's cadence baselines. Specific offer-design choices for specific products. These vary by team. diff --git a/skills/lead-magnet-design/references/format-selection-patterns.md b/skills/lead-magnet-design/references/format-selection-patterns.md new file mode 100644 index 0000000..97e7ce8 --- /dev/null +++ b/skills/lead-magnet-design/references/format-selection-patterns.md @@ -0,0 +1,245 @@ +# Format selection patterns + +Templates, checklists, swipe files, mini-courses, free tools, ebooks, video series. Per-format strengths, weaknesses, audience-fit signals, and conversion-rate baselines. Choosing the wrong format wastes the topic and the design effort. + +A great template often outperforms a mediocre ebook on the same topic. The format is half the design decision; the topic is the other half. + +--- + +## Templates + +A starting artifact the reader fills in or adapts. + +Strengths. + +- Immediate, concrete value. The reader produces a usable artifact in minutes. +- High perceived value because the artifact is practical. +- Strong audience signal: people who download templates are people who execute, not just consume. +- Sustainable production: a single template, well-designed, can serve thousands of downloads with minimal updating. + +Weaknesses. + +- Generic templates feel useless; the bar for "custom enough" is high. +- The format does not work when the deliverable is non-standardizable (the reader's context varies too much for a template to fit). +- Distribution can be tricky if the template requires specific tools (a Notion template is unusable to teams not on Notion). + +Audience-fit signals. + +- Strong fit: practitioners who produce specific deliverables (specs, briefs, plans, decks, sequences). +- Weak fit: strategic readers who want frameworks rather than artifacts. + +Conversion-rate baseline. Templates often convert 3-12 percent on landing pages with reasonable traffic-fit. The high end is for templates that signal exceptional specificity in the title. + +Production overhead. Moderate. A polished template often takes 8-20 hours including design, instructions, and worked example. + +--- + +## Checklists + +A sequence of items to verify or complete. + +Strengths. + +- Fast to consume, fast to apply. Reader gets value in 10-20 minutes. +- Format signals "you can use this today." +- Strong for processes where the gap is comprehensiveness rather than direction (the reader knows what to do; the checklist verifies they did not miss steps). + +Weaknesses. + +- Easy to make thin. A 12-item generic checklist reads as marketing rather than a working tool. +- Sequence matters; an unordered checklist on a process is less useful than the same items in workflow order. +- Limited topic range; checklists fit verification-style tasks, not strategy-style decisions. + +Audience-fit signals. + +- Strong fit: practitioners executing known processes who need verification (launch checklists, audit checklists, onboarding checklists). +- Weak fit: strategic decisions where each situation differs. + +Conversion-rate baseline. Strong checklists convert 5-15 percent. The format signals quick wins, which lifts conversion. + +Production overhead. Low to moderate. 4-12 hours including design and field-testing. + +--- + +## Swipe files + +A curated collection of examples (subject lines, headlines, ad copy, design references, email templates). + +Strengths. + +- High perceived value. The reader gets a body of work to study and adapt. +- Strong for audiences who learn from examples rather than instruction. +- Often shareable; readers tell peers about a strong swipe file. + +Weaknesses. + +- Requires curation discipline; a 200-item swipe file with no commentary is less useful than 30 swipes with curation notes. +- Decays faster than templates or frameworks; swipes go stale as conventions change. +- Attribution matters; uncredited swipes can be perceived as theft. + +Audience-fit signals. + +- Strong fit: copywriters, designers, marketers, and creators who need inspiration plus example. +- Weak fit: audiences seeking instruction or process. + +Conversion-rate baseline. Strong swipe files convert 4-12 percent. + +Production overhead. Moderate to high. 12-30 hours including curation, attribution, and commentary. + +--- + +## Mini-courses + +A multi-part email or video sequence delivering structured learning. + +Strengths. + +- Multiple touchpoints, which deepens the relationship. +- Sequential structure can take the reader from "novice" to "competent" on a topic. +- The course format can charge implicit time investment, which qualifies the lead as serious. + +Weaknesses. + +- Each lesson must stand on its own; "the answer is in lesson 4" loses the reader by lesson 2. +- Production overhead is significant. +- Completion rates are honestly low (often 10-30 percent finish), which limits the cumulative value delivered. + +Audience-fit signals. + +- Strong fit: audiences willing to invest sequential attention and seeking structured learning. +- Weak fit: audiences who want quick wins or specific artifacts. + +Conversion-rate baseline. 3-10 percent. Lower than templates or checklists because the perceived time commitment is higher. + +Production overhead. High. 30-100 hours for a 5-7 lesson course depending on format. + +--- + +## Free tools (calculators, quizzes, generators, configurators) + +Interactive web tools that produce a personalized result. + +Strengths. + +- Highest perceived value among magnet types when the tool genuinely helps. +- Personalization makes the result feel custom. +- Often shareable; results can drive earned traffic. +- Lead-quality signal embedded in the inputs (a calculator's inputs reveal the lead's situation). + +Weaknesses. + +- Build cost is significant; a quality tool is engineering work, not just copy. +- Maintenance is ongoing as inputs and methodology evolve. +- Easy to fall into vanity-tool patterns (inputs and outputs that do not produce a meaningful result). + +Audience-fit signals. + +- Strong fit: audiences with concrete decisions or calculations the tool can address. +- Weak fit: topics that do not naturally produce a personalized output. + +Conversion-rate baseline. Wide range, 5-25 percent depending on tool quality and audience-fit. + +Production overhead. High. 40-150+ hours for a polished tool. + +Detail in `calculator-design` and `quiz-and-assessment-design`. + +--- + +## Ebooks + +Long-form treatment of a topic. + +Strengths. + +- Comprehensive coverage when comprehensiveness matters. +- Authority signal; a well-produced ebook positions the brand as a definitive source. +- Bookmarkable; readers may return over time. + +Weaknesses. + +- Easy to default to ebook for topics that would have been better as a checklist or template. +- Completion rates are honestly low; many ebooks are downloaded and never read. +- Production overhead and design overhead are high. +- The format invites kitchen-sink-resource patterns ("we have to cover everything"). + +Audience-fit signals. + +- Strong fit: audiences researching a complex decision who want depth. +- Weak fit: practitioners who want immediate-use artifacts. + +Conversion-rate baseline. 2-8 percent. Lower than other formats because the perceived time investment to read is high and many readers know they will not finish. + +Production overhead. High. 40-120 hours for a 30-50 page ebook. + +--- + +## Video series + +Sequential video content delivered behind a gate. + +Strengths. + +- Strong for topics that benefit from demonstration (UI walkthroughs, design critique, code review). +- Personality and brand presence land more directly in video than in text. +- Audiences who prefer video learning are well-served. + +Weaknesses. + +- Production overhead is high; video quality has to match the brand it represents. +- Audiences who do not consume video at the moment of magnet delivery underuse the resource. +- Updates require re-recording, which is more expensive than updating text. + +Audience-fit signals. + +- Strong fit: audiences who consume video for learning and have time to watch. +- Weak fit: practitioners who want skim-and-apply content. + +Conversion-rate baseline. 3-9 percent. + +Production overhead. Very high. 50-200+ hours for a 4-6 video series at quality. + +--- + +## Hybrid formats + +Some magnets combine formats. A template plus a worked-example video. A checklist plus a 5-day email mini-course that walks through it. + +Strengths. + +- Multiple consumption modes serve broader audience preferences. +- The hybrid often outperforms either format alone. + +Weaknesses. + +- Production overhead compounds. +- Risk of confusing the reader about what they are getting. + +When hybrids work. When the second format genuinely extends the first. A template that includes a video walkthrough adds value; a template that includes a 60-page ebook the reader did not ask for adds bloat. + +--- + +## Format-decision frame + +When choosing the format for a specific topic and audience. + +Step 1: Audience consumption mode. How does this audience consume content? Do they read long-form? Skim PDFs? Watch video? Use templates? + +Step 2: Topic shape. Does the topic naturally produce an artifact (template), a verification (checklist), inspiration (swipe), instruction (course), a calculation (tool), depth (ebook), or demonstration (video)? + +Step 3: Production capacity. What can the team sustain? A great template the team can ship beats a mediocre ebook the team is straining to finish. + +Step 4: Conversion-rate target. Templates and checklists generally convert higher; ebooks and courses convert lower. The expected conversion rate informs the topic-volume calculation. + +Step 5: Maintenance overhead. Some formats decay faster than others. Swipes go stale; templates with software-specific instructions decay; videos with UI screenshots decay. Choose formats the team can maintain. + +The right format is the one that fits the topic, the audience, the team's capacity, and the maintenance reality. There is no universal best format; there is only the format that fits the situation. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format strengths, weaknesses, audience-fit signals, conversion-rate baselines, and production overhead. The hybrid format consideration. The format-decision frame. The principle that there is no universal best format. + +## Implementation choices that stay internal + +Specific format choices for specific topics in the team's catalog. Specific production benchmarks for the team's capacity. Specific tooling for each format. The team's audit baselines for conversion rate and lead quality. These vary by team, topic, and audience. diff --git a/skills/lead-magnet-design/references/format-specific-quality-gates.md b/skills/lead-magnet-design/references/format-specific-quality-gates.md new file mode 100644 index 0000000..b781609 --- /dev/null +++ b/skills/lead-magnet-design/references/format-specific-quality-gates.md @@ -0,0 +1,196 @@ +# Format-specific quality gates + +Per-format quality tests. Templates, checklists, swipes, mini-courses, ebooks, videos. Each format has gates specific to that format. A great template fails different tests than a great mini-course. + +The quality gates exist because thin-bait can hide in any format. The gates make hiding harder. Apply them before launch; if the magnet fails a gate, redesign before shipping. + +--- + +## Template gates + +A template earns the email when the reader produces a usable artifact in minimal time. + +Gate 1: Time-to-usable-artifact. Can the reader produce a usable artifact in under 30 minutes? If the template requires hours of customization to be useful, the format is failing. + +Gate 2: Specificity of prompts. Are the prompts specific enough to feel custom? "Insert your unique value proposition here" is too generic. "What is the specific outcome your customer needs in the first week" is specific enough to guide the reader. + +Gate 3: Adaptability across the segment. Is the template adaptable across the segment of the audience, or rigidly bound to one situation? A template for "B2B SaaS pricing one-pager" should work across multiple B2B SaaS situations; a template that only fits one company's exact circumstances is too rigid. + +Gate 4: Worked example included. Does the template include a worked example showing what a completed version looks like? Worked examples reduce the time-to-usable-artifact and signal that the template was real-tested. + +Gate 5: Tooling honesty. If the template requires specific tools (a Notion template, a Figma file, an Airtable base), is the tool dependency honestly disclosed in the title? Surprise dependencies frustrate readers who do not have the tool. + +--- + +## Checklist gates + +A checklist earns the email when each item is actionable today. + +Gate 1: Each item actionable today. No "consult your team about X" or "decide on the strategy for Y." Each item should be something the reader can verify or complete. + +Gate 2: Workflow order. Does the checklist sequence reflect actual workflow order? An out-of-order checklist forces the reader to mentally re-sort, which costs the speed advantage the format promised. + +Gate 3: Scope discipline. Is the checklist scoped narrowly enough to feel comprehensive within scope? "Pre-launch checklist for B2B SaaS" is narrower than "Pre-launch checklist for any product" and produces a tighter, more useful resource. + +Gate 4: Item count sanity. Strong checklists are usually 12-30 items. Fewer than 8 items often signals thin-bait; more than 50 often signals that the format should have been an ebook or playbook instead. + +Gate 5: Verification cues. Does each item include enough cue for the reader to know they actually verified it? "Email sequence tested in production" is verifiable; "Email sequence reviewed" is not. + +--- + +## Swipe file gates + +A swipe file earns the email when the swipes are real, attributed, and curated. + +Gate 1: Real swipes. The swipes should be examples actually used in the wild, not invented for the magnet. Real swipes have specificity that invented ones lack. + +Gate 2: Attribution where possible. Each swipe attributed to source where the source is public. Unattributed swipes can read as theft. + +Gate 3: Currency. Are the swipes current? Swipes from 5 years ago may have specific dating cues that signal staleness. Periodic refresh is part of the swipe-file discipline. + +Gate 4: Curation visible. Is the curation visible? The reader can see why each swipe is included? A 200-swipe dump with no commentary is less useful than 30 curated swipes with notes on why each was included. + +Gate 5: Categorization. Are the swipes categorized by use case (subject lines, headlines, ad copy, design references)? A flat list of unsorted swipes is harder to extract value from than a categorized collection. + +--- + +## Mini-course gates + +A mini-course earns the email when each lesson stands on its own and the cumulative arc adds up. + +Gate 1: Each lesson standalone. A reader who only completes lesson 1 should still extract value. "You will learn the answer in lesson 4" loses readers who do not make it to lesson 4. + +Gate 2: Cumulative time honesty. Is the total time commitment honestly disclosed in the title or landing page? "5-day course" should mean 5 days of meaningful engagement, not 5 days of one paragraph emails. + +Gate 3: Production consistency. Are all lessons at consistent production quality? Courses that decay in production quality across lessons signal that the team ran out of capacity. + +Gate 4: Clear next step at end. Does the course end with a clear next step (related product, related resource, ongoing community)? "Thanks for taking the course" without a next step is a missed opportunity. + +Gate 5: Completion tracking. Does the course include progress markers ("Lesson 3 of 5") so the reader knows where they are? Lack of progress markers correlates with low completion. + +Gate 6: Each lesson's central insight. Can the team articulate the central insight of each lesson in one sentence? Lessons without a central insight are filler. + +--- + +## Free tool gates + +Free tools (calculators, quizzes, generators) earn the email when the result is meaningful. + +Gate 1: Meaningful result. The output should help the reader make a decision or understand a situation. "Your score is 73" without interpretation is meaningless. Detail in `calculator-design` and `quiz-and-assessment-design`. + +Gate 2: Calculation transparency or methodology disclosure. Detail in `calculator-design`. + +Gate 3: Email-capture honesty. Detail in `calculator-design`. + +--- + +## Ebook gates + +An ebook earns the email when the resource produces value for readers who do not finish. + +Gate 1: Navigability. Table of contents, page numbers, summary boxes. A reader who jumps to chapter 3 should be able to extract value without reading 1 and 2. + +Gate 2: Production quality consistent with the brand. A poorly-produced ebook (typos, inconsistent formatting, low-resolution images) signals that the brand did not invest. The reader's expectation of the brand drops. + +Gate 3: Length honesty. Is the page count honestly disclosed? "30-page guide" should mean 30 pages of substance, not 30 pages including 12 of brand-positioning. + +Gate 4: Chapter summaries. Each chapter ends with a summary that lets a reader who skimmed extract the key insight. Summaries reduce the cost of skimming, which raises the value the reader gets even if they do not finish. + +Gate 5: First-chapter discipline. The first chapter should deliver value, not warm up. Author bio and brand-positioning belong in the appendix or the about-the-author note, not chapter 1. + +--- + +## Video series gates + +A video series earns the email when production quality and consumption shape match the audience. + +Gate 1: Production quality consistent. Audio clear, video stable, lighting reasonable. Production quality the brand can sustain across all videos. + +Gate 2: Runtime honesty. Total runtime disclosed honestly. "5-video series" with one video 30 seconds and another 45 minutes is dishonest. + +Gate 3: Audio-first viability. Many video viewers consume in audio-only contexts (commutes, exercise). Does the video work as audio? If the video has heavy on-screen reading required, the audio-only viewer loses the value. + +Gate 4: Transcripts available. A transcript reaches the audience that prefers reading and improves accessibility. + +Gate 5: Each video standalone. Same as the mini-course gate. A viewer who only watches video 1 should extract value. + +--- + +## Cross-format gates + +Some gates apply regardless of format. + +Gate A: The "would they pay for this" test. Detail in `references/would-they-pay-for-this-test.md`. + +Gate B: Audience-fit signal. Does the magnet attract the audience the brand serves? Detail in `references/audience-fit-qualification.md`. + +Gate C: Title-content alignment. Does the magnet deliver on the title's specific promise? Detail in `references/title-and-presentation-discipline.md`. + +Gate D: First-impression quality. Whatever the format, does the first impression (first page, first lesson, first calculator output) deliver something useful immediately? + +Gate E: Update cadence. Is the magnet updated when references go stale, screenshots change, or methodology evolves? Stale magnets degrade the brand. + +--- + +## When a magnet fails a gate + +The magnet fails a gate. Now what. + +Option 1: Fix the magnet. Add the worked example, narrow the scope, improve the production quality. Often the right answer. + +Option 2: Change the format. Sometimes the topic is wrong for the chosen format. A topic that fails ebook gates might pass checklist gates. + +Option 3: Do not ship. Some magnets should not exist. Killing the magnet at the gate stage is honest; shipping a failing magnet costs more than killing it. + +The team's response to gate failures is the discipline marker. Strong programs fix or kill at the gate; weak programs ship despite failed gates and accept the downstream cost. + +--- + +## The gate review process + +Gates are most useful when applied as a structured pre-launch review. + +The review. + +- Identify the format. +- List the gates for that format (plus the cross-format gates). +- For each gate, score pass / fail / marginal. +- Marginal gates warrant strengthening before launch. +- Failed gates require redesign before launch. + +Who reviews. + +- The magnet's author should self-review. +- A second person (outside the magnet's authoring team) should also review. Outside-in honesty catches what the authoring team rationalizes. + +Document the review. A short note on which gates passed and which were strengthened. Useful for future magnet design and team learning. + +--- + +## Common gate failures + +Templates. Generic prompts; no worked example; tool dependency hidden. + +Checklists. Items that are not actionable; out-of-workflow order; thin item count. + +Swipe files. Invented swipes; no attribution; uncategorized dump. + +Mini-courses. Lessons that depend on each other; production quality decays; no clear next step. + +Free tools. Vanity outputs without interpretation; misleading methodology; manipulative gates. + +Ebooks. Poor navigability; production quality below brand standard; length padded with brand-positioning. + +Video series. Inconsistent production; no transcripts; long runtime hidden. + +The pattern across formats: the gates surface the failures that conversion-rate metrics hide. A magnet can convert at high rates while failing the gates; the gate failures show up downstream as poor lead quality and poor sequence engagement. + +--- + +## Methodology-level choices that stay in the public skill + +Per-format quality gates with specific tests. Cross-format gates. The gate review process. The decision tree when a magnet fails a gate. Common gate failures. + +## Implementation choices that stay internal + +Specific gate-scoring conventions for the team. Specific review processes and reviewers. Specific worked-example libraries. Specific production-quality benchmarks. Specific update-cadence calendars. These vary by team. diff --git a/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md b/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md new file mode 100644 index 0000000..e2d1f8f --- /dev/null +++ b/skills/lead-magnet-design/references/lead-magnet-anti-patterns.md @@ -0,0 +1,197 @@ +# Lead magnet anti-patterns + +The patterns that look like lead magnets but do not behave like them. Anti-patterns are easy to ship and easy to celebrate; the cost shows up in lead quality, sequence engagement, and brand trust over time. + +--- + +## The thin-bait magnet + +The pattern. A vague-headline PDF that contains 200 words of fluff behind an email gate. + +The signal. Conversion-rate metric looks fine; unsubscribe rate after delivery is high; subsequent email open rates collapse. + +The cost. Every subscriber acquired through thin-bait costs more than they appear to. Reduced sender reputation, reduced list trust, and the brand reputation as a source of bait all compound. + +The cure. Apply the "would they pay for this" test before launch. Strengthen the resource until it would be worth paying for. If it cannot be strengthened, do not ship. + +--- + +## The kitchen-sink-resource magnet + +The pattern. An 80-page "Ultimate Guide" that covers everything anyone could want about the topic. Nothing the reader needs RIGHT NOW. + +The signal. Strong conversion rate (the title sounds comprehensive); low usage rate (the resource is too long to consume); no traceable downstream conversion. + +The cost. The magnet does not produce the moment of "I needed this and got it." The relationship never starts. Subscribers stay on the list out of inertia; future emails get ignored. + +The cure. Narrow the topic until the magnet addresses one specific problem. The 80-page guide becomes a 4-page checklist or a 12-page worked example. Conversion rate may drop; lead quality and downstream engagement rise. + +--- + +## The undelivered-promise magnet + +The pattern. A title that promises a specific outcome ("the framework that doubled our conversion rate") followed by a magnet that delivers something less specific ("here is general advice on conversion rate optimization"). + +The signal. Reader downloads, opens, encounters the gap, and unsubscribes (or stays subscribed but disengages). + +The cost. The brand becomes the source of the gap. Future titles by the same brand are less trusted; conversion rates on future magnets decay. + +The cure. Either deliver on the title's promise (which often requires strengthening the magnet) or revise the title to be honest about what the magnet contains. + +--- + +## The bait-and-switch magnet + +The pattern. The magnet promises one resource and delivers another. "Free template" that turns out to be a 10-email mini-course; "calculator" that turns out to be a contact-sales form. + +The signal. Reader engagement collapses; the brand earns "deceptive" descriptors in support tickets and social mentions. + +The cost. Trust damage that extends beyond the magnet. The brand becomes harder to trust on any future offering. + +The cure. Match the title to what the magnet actually delivers. If the team wants to deliver a mini-course, title the magnet as a mini-course. If the team wants to gate a sales form, do not call it a calculator. + +--- + +## The orphan-magnet (no sequence) + +The pattern. The magnet ships; subscribers download; nothing follows. No sequence, no offer, no relationship-building. + +The signal. List grows; engagement on subsequent emails (when they happen) is low; downstream conversion to anything is near zero. + +The cost. The list is a list of cold contacts. The brand has the email but not the relationship. + +The cure. Design the sequence before shipping the magnet. The 30 days after download should have a purpose, an arc, and a soft offer. + +--- + +## The misaligned-offer magnet + +The pattern. The magnet attracts one audience; the follow-up offer pitches a different one. Magnet on B2B onboarding; offer for consumer-app courses. + +The signal. Magnet conversion is fine; offer conversion is near zero; the audience signal the magnet captured was wasted. + +The cost. The team builds the magnet, runs the sequence, and gets no downstream conversion. The investment does not pay back. + +The cure. Align the offer to the audience the magnet attracts. If the offer cannot be changed, change the magnet to attract the offer's audience. + +--- + +## The dead-magnet portfolio + +The pattern. The team has shipped 12 magnets over 3 years. 3 still convert; 9 are dead but still on the site. Maintenance attention spreads thin; nothing is great. + +The signal. Aggregate conversion-rate metrics look fine; per-magnet metrics show 75 percent of the portfolio underperforming. + +The cost. Maintenance overhead on dead magnets; brand looks cluttered; team capacity diluted across underperformers. + +The cure. Audit the portfolio. Retire the dead magnets. Free capacity for the strong ones and for new magnets that earn investment. + +--- + +## The everyone-magnet + +The pattern. A magnet titled to attract "everyone in marketing" or "any founder." Generic by design. + +The signal. Conversion rate may be high; lead quality is low; downstream engagement is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly because the audience is not aligned to any specific offer. + +The cure. Narrow the magnet's audience. Specific magnets attract specific audiences who convert well to specific offers. The everyone-magnet is the wrong tool for any specific goal. + +--- + +## The vanity-magnet + +The pattern. A magnet built because the team wanted to ship a magnet, not because the audience needed one. The topic was chosen for "we should write about this" rather than "the audience would download this." + +The signal. Low conversion rate; few signs that the audience cares about the topic; the magnet collects dust. + +The cost. Sunk effort; team morale drop; the team learns that magnets do not work (when in fact this specific magnet did not work because the topic was wrong). + +The cure. Audience-research the topic before building. Confirm the topic matches a specific problem the audience is actively trying to solve. Vanity-magnets often fail at the topic-validation step. + +--- + +## The follow-up-spam magnet + +The pattern. The magnet ships; the sequence follows; the sequence is 30 emails over 14 days, all of them sales-driven. + +The signal. Strong unsubscribe rate; high spam-complaint rate; the brand earns "spammy" descriptors. + +The cost. Sender reputation damage that affects all future emails. The brand's email program degrades. + +The cure. Redesign the sequence to add value rather than extract it. Cadence should match the audience's tolerance; content should be honest. + +--- + +## The interrogation-form magnet + +The pattern. The form before the magnet asks for 12 fields (name, company, role, company size, current tools, biggest challenge, etc.) before delivering the resource. + +The signal. Conversion rate collapses; the audience self-selects out at the form. + +The cost. The magnet's reach drops dramatically. The team gets rich data on the few who convert; the team loses the broader audience the magnet could have served. + +The cure. Ask only for what is needed (often just an email). Capture additional data later in the sequence as the relationship deepens. + +--- + +## The hidden-cost magnet + +The pattern. The magnet promises a free resource; the resource includes upselling, integrated ads, or links to paid offerings on every page. + +The signal. Reader downloads expecting a resource; experiences the upsells as bait; engagement collapses. + +The cost. The magnet is perceived as commercial-disguised-as-resource. Trust damages. + +The cure. Keep the magnet substantive. Soft offers can appear at the end or in the follow-up sequence; the body of the magnet should deliver the promised value. + +--- + +## The unfindable-asset magnet + +The pattern. The magnet is delivered as a link to a Google Drive folder, a Notion page, or some other location that the reader has to navigate to find the actual asset. The asset is buried 2-3 clicks away. + +The signal. Reader downloads the email link; cannot find the asset; abandons. + +The cost. The download metric counts but the consumption metric collapses. The reader's experience is friction. + +The cure. Deliver the asset directly (attachment or in-line link). Click count from email to asset should be 1. + +--- + +## The team-pat-on-the-back magnet + +The pattern. The magnet is content the team wanted to make (a thought-leadership piece, a brand statement, a manifesto) gated behind a form. The audience may not specifically want it. + +The signal. Conversion rate underwhelms; the team rationalizes ("brand-building is hard to measure"); the magnet does not produce relationship signal. + +The cost. The team builds the wrong thing for the audience and learns the wrong lesson. + +The cure. Design magnets for the audience's needs, not for the team's preferences. Brand-building content can exist as ungated content; gated content should be magnet-shaped. + +--- + +## How to detect anti-patterns in the portfolio + +Audit cadence. Quarterly review of every active magnet, looking specifically for these anti-patterns. + +Audit questions per magnet. + +- Is the conversion rate consistent with the audience-fit, or is it suspiciously high (suggesting thin-bait or everyone-magnet)? +- Is the lead quality consistent with the audience the magnet was designed for, or is it diluted (suggesting weak filters)? +- Does the sequence's engagement match the magnet's promise, or is there a drop (suggesting an undelivered-promise or misaligned-offer)? +- Is the asset usable in the form delivered, or is it hard to find (suggesting unfindable-asset)? +- Does the magnet have a sequence at all, or is it orphaned? + +The retire decision. Anti-pattern magnets often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-magnet plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md b/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md new file mode 100644 index 0000000..9fd5b1f --- /dev/null +++ b/skills/lead-magnet-design/references/lead-magnet-decision-criteria.md @@ -0,0 +1,137 @@ +# Lead magnet decision criteria + +When a lead magnet is the right investment for the funnel and when it is not. The conditions that make magnets worth the build, and the funnels where the magnet is friction the audience does not need. + +A lead magnet is a long-lived asset. The build cost is upfront; the conversion lift compounds across visitors. But the long-lived asset only compounds if the audience and the goal warrant it. Magnets built without the conditions in place become dead PDFs in CMS folders. + +--- + +## When a magnet earns the build + +Five conditions that, when present, make a magnet a strong investment. + +Traffic exists but conversion is missing. The audience reaches the site (organic, paid, referral, social) but does not convert to the primary action (signup, purchase, demo). The magnet fills the gap between "interested enough to land" and "ready to commit." Without traffic, the magnet has no audience; without a conversion gap, the magnet adds friction. + +The consideration cycle is long. B2B SaaS, high-ticket services, and considered consumer purchases share the trait that buyers research over weeks or months before committing. The list-building motion lets the brand stay present across the consideration window. Short-cycle purchases (impulse ecommerce, low-stakes signups) often do not need a magnet between visitor and conversion. + +The audience has a specific, immediate problem the magnet can address. Generic problems do not focus a magnet. "Improve my marketing" is too broad; "the email sequence I send to trial signups who go cold" is specific enough to focus a checklist or template. The magnet lives or dies on specificity. + +The team can commit to the follow-up sequence. A magnet without a sequence is a list with decay. The sequence is where the relationship deepens, the offer surfaces, and the lead-quality signal gets used. Teams without sequence-building capacity should fix that before building the magnet. + +The success metric is defined. What does "the magnet works" look like? List growth at quality, lead-quality signal, conversion to the next step, downstream revenue attribution. Without a defined success metric, the magnet's results cannot be evaluated, and underperformers do not get retired. + +When all five are present, the magnet is a strong investment. When two or fewer are present, the magnet is probably the wrong tool. + +--- + +## When a magnet does NOT earn the build + +Funnels where the magnet adds friction the audience does not need. + +Frictionless conversion already exists. A SaaS with a 14-day free trial, no credit card required, may not need a magnet between the visitor and the trial. The magnet adds a step where the trial alone would convert. + +The next step is a sales call or demo. When the goal is a booked call, design the call-booking flow rather than a magnet that delays the call. The magnet might still serve a separate audience (top-of-funnel readers not ready for a call), but the primary funnel is the call. + +The audience is too small for list-building economics. Building, hosting, and maintaining a magnet (plus the sequence) costs ongoing time. For very small target audiences, direct outreach or a simpler conversion path may be more efficient. + +The team has no sequence capacity. If the team cannot design and maintain the post-download sequence, the magnet captures emails that decay into unsubscribes. The list grows on paper and shrinks in trust. + +No specific topic that focuses a magnet. When the topic is "we do everything," no single magnet focuses. The honest move is to narrow the audience first (which produces the topic that focuses) rather than build a generic magnet. + +The current funnel is already converting at a rate the magnet would not improve. If the visitor-to-customer rate is already strong, the magnet adds steps without lifting the outcome. + +The honest assessment matters more than the default. "Should we have a lead magnet" is not the question. "Is the magnet the right investment for this audience and goal" is. + +--- + +## The opportunity-cost frame + +A magnet's cost is not just the build. It is the build plus the maintenance plus the sequence plus the team attention diverted from other work. + +The build cost. Format selection, copy, design, asset production, landing page, form integration, delivery automation. A meaningful magnet often takes 20-80 hours from scoping to launch. + +The maintenance cost. Magnets decay. References go stale, screenshots get outdated, the topic moves on. Maintenance often runs 2-4 hours per quarter per active magnet. + +The sequence cost. The post-download sequence is itself a build. 5-12 emails, copy and integration. 10-30 hours upfront. + +The opportunity cost. What else could the team have built with that time? A funnel improvement, a content piece, a paid-traffic optimization, a product improvement. The magnet's success has to clear the bar of those alternatives. + +The decision frame. The magnet earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus sequence. + +--- + +## The audience precondition + +Without an audience, the magnet has no one to convert. + +The chicken-and-egg pattern. Teams sometimes build magnets to "drive traffic." That works only if the magnet itself is shareable enough to attract traffic (rare) or if the team has a separate plan to drive traffic to the magnet's landing page. + +The realistic frame. The magnet converts traffic that already exists. Driving traffic is a separate problem (covered by `content-distribution`, paid media, SEO, and partnerships). Build the magnet for the traffic that already lands; do not expect the magnet to do the traffic-driving work. + +The exception. Genuinely shareable magnets (free tools, viral calculators, definitive industry reports) can drive their own traffic. But these are the minority of magnets, and the design effort to reach shareability is significant. + +--- + +## The portfolio frame + +A team often has multiple magnets, not one. The portfolio earns more thought than any individual magnet. + +The audience-segmentation frame. Different magnets for different audience segments. The B2B SaaS founder magnet does not need to also serve the consumer marketer; segment-specific magnets often outperform generic ones. + +The funnel-stage frame. Magnets for top-of-funnel readers, magnets for middle-of-funnel evaluators, magnets for bottom-of-funnel near-buyers. Each stage has different value to deliver and different next-step offers. + +The maintenance frame. A portfolio of 4-6 active magnets is often more sustainable than 12 mediocre ones. Periodic audit retires the underperformers and frees capacity for the strong magnets. + +The cross-magnet promotion frame. The follow-up sequence from one magnet can promote another. Subscribers who downloaded the templates checklist may also want the pricing one-pager. + +The portfolio approach amplifies the value of each strong magnet and makes maintenance manageable. + +--- + +## The decision worked example + +A B2B SaaS targeting product managers at mid-market companies. + +Conditions check. + +- Traffic: 8000 monthly organic visitors, 1200 paid visitors. Yes. +- Consideration cycle: typical PM tool evaluation takes 6-12 weeks. Yes. +- Specific problem: PMs at mid-market companies struggle to define product metrics that the engineering team can instrument quickly. Yes. +- Sequence capacity: marketing team has built two prior sequences; capacity exists. Yes. +- Success metric: list growth at audience-fit (PMs at 50-500 person companies), conversion to product trial within 60 days. Yes. + +Decision. Build the magnet. The conditions warrant it. + +Format selection. Template plus worked example. The PM produces a usable artifact (the metric definition spec) inside 30 minutes. + +Sequence. 7-email arc over 21 days. Email 1 delivers the asset. Emails 2-4 deepen the value with related artifacts. Email 5 introduces the product as the next step. Emails 6-7 case study and offer. + +Audit cadence. Quarterly review of conversion rate, lead quality, sequence open and click rates, downstream trial conversion. + +The decision was not "should we have a magnet" but "given these conditions, this is the magnet to build." + +--- + +## When to retire a magnet + +Magnets decay. Retiring them is part of the discipline. + +Retire when: + +- Conversion rate has dropped below baseline for two consecutive quarters. +- The topic has shifted (the audience no longer cares about the problem the magnet solves). +- A newer magnet on the same topic is outperforming and the older one is cannibalizing. +- The follow-up sequence is no longer maintained and the leads go cold. +- The references and screenshots are stale and updating them costs more than retiring. + +The retiring discipline frees capacity. A portfolio of dead magnets costs maintenance attention without producing results. Honest retirement is part of the program. + +--- + +## Methodology-level choices that stay in the public skill + +The decision conditions for whether to build a magnet. The opportunity-cost frame. The audience precondition. The portfolio frame. The retirement discipline. The decision worked example. The honest "no" cases where a magnet adds friction. + +## Implementation choices that stay internal + +Specific magnet topics for specific audiences. The team's capacity benchmarks for build, maintenance, and sequence work. Specific tooling for landing pages, forms, delivery, and sequence. Specific success-metric definitions and baselines. The team's portfolio composition and audit calendar. These vary by team and audience. diff --git a/skills/lead-magnet-design/references/title-and-presentation-discipline.md b/skills/lead-magnet-design/references/title-and-presentation-discipline.md new file mode 100644 index 0000000..f3b990f --- /dev/null +++ b/skills/lead-magnet-design/references/title-and-presentation-discipline.md @@ -0,0 +1,190 @@ +# Title and presentation discipline + +Title patterns that work and patterns that fail. Cover, landing-page preview, first-page discipline. + +The magnet's title is the conversion lever and the qualification filter at the same time. Beyond the title, the cover, the landing-page preview, and the first page each carry signal about whether the resource will deliver. Get any of these wrong and the rest of the magnet's design effort is wasted. + +--- + +## Title patterns that work + +Specific, honest, signals what is inside. + +Specific outcome plus specific audience. "The B2B onboarding email sequence that 3x'd our 14-day activation rate (for SaaS founders)." + +What works: the specific outcome (3x'd, 14-day activation), the specific audience (SaaS founders), the specific deliverable (email sequence). The reader knows exactly what they get and can predict whether it applies. + +Specific deliverable plus specific situation. "The pricing one-pager for SaaS founders raising a seed round." + +What works: the artifact (pricing one-pager), the situation (raising a seed round). Niche by design; the audience that converts is exactly the audience the brand wants to engage. + +Specific framework plus specific problem. "The 4-question framework for deciding whether to fire a customer." + +What works: the framework's structure (4 questions), the specific decision (fire a customer). Promises a tool, not a treatise. + +Specific count plus specific value. "23 onboarding emails, with the open and click rate for each." + +What works: the count (signals scope), the value-add (real metrics, not just templates). The reader knows the resource includes evidence. + +Specific transformation. "The audit that took our trial-to-paid rate from 8 percent to 14 percent." + +What works: the before-state (8 percent), the after-state (14 percent), the mechanism (the audit). The reader can imagine running their own version. + +--- + +## Title patterns to avoid + +Vague, overpromising, or generic. These titles correlate with thin-bait and kitchen-sink-resource patterns. + +"Ultimate Guide to X." Vague. Promises completeness; underdelivers reliably. The "Ultimate" qualifier signals that the team did not narrow the topic. + +"The Complete X Playbook." Same failure mode. Promises volume; suggests the resource is big and unfocused. + +"Free X Resource." Generic. Tells the reader nothing about what makes this resource the one to download. The "free" framing implies the resource has to apologize for asking for the email. + +"10 Tips for Better X." Listicle framing signals thin content. "10 tips" is rarely a useful resource; "the 1 specific change that doubled our X" is. + +"X 101" or "Beginner's Guide to X." Targets a low-investment audience. The list that grows from these titles tends to convert poorly to anything beyond the magnet. + +"The Definitive X Resource." Self-aggrandizing. Definitive is the reader's judgment, not the marketer's claim. + +Vague verbs. "Master," "Unlock," "Transform." Without specificity about what or how, these are filler. + +--- + +## The honesty discipline in titles + +The title should not promise more than the magnet delivers. + +The check. Read the title. Then open the magnet. Does the magnet deliver on the title's specific promise? If yes, the title is honest. If the title overpromises, redesign the title (or strengthen the magnet) before launching. + +The consequence of dishonesty. Readers download, find the gap between title and content, and unsubscribe. Worse, they remember the brand as the source of the gap. The conversion-rate metric looks fine; the brand reputation degrades. + +The conservative title. A title that slightly under-promises and then delivers more is better than a title that overpromises and disappoints. + +--- + +## Cover and visual presentation + +The cover is the second visual the reader processes (after the landing page hero). It should reinforce the title's specificity. + +Strong cover patterns. + +- Type-driven covers. The title in clean, large type. Color-blocked. Reads at thumbnail size. +- Single-image covers. A specific image (a screenshot, a diagram, a person) that signals what the magnet contains. +- Brand-consistent covers. Visual style matches the brand the magnet represents. + +Weak cover patterns. + +- Stock-image covers. Generic stock photos signal generic content. +- Cluttered covers. Too many visual elements; the title gets lost. +- Off-brand covers. Cover that does not match the brand the reader saw on the landing page; signals inconsistency. + +The cover-as-thumbnail test. The cover will be displayed at thumbnail size in social shares, in landing-page previews, and in delivery emails. Does it read at thumbnail size? If not, redesign. + +--- + +## Landing-page preview + +The landing page (which is the `landing-page-copy` skill's domain) should preview the magnet, not just describe it. + +Strong preview patterns. + +- Show pages from inside. Screenshots of actual pages from the magnet. The reader sees the resource before they download. +- Show worked examples. A specific page from the template, the checklist, or the swipe file. Concreteness lifts conversion. +- Show the table of contents. For longer magnets, show what is inside. The reader can predict whether the resource will help. + +Weak preview patterns. + +- Stock-image hero only. The landing page shows nothing of the actual magnet. The reader has to trust the marketing without evidence. +- Generic descriptions. "Learn the framework that..." without showing the framework. +- Hidden contents. "You will learn..." without showing what learning looks like in the resource. + +The preview is the second-best evidence that the magnet delivers (the best evidence is post-download, but the preview is the pre-download proxy). Strong previews lift conversion and reduce post-download disappointment. + +--- + +## First-page discipline + +The first page of the magnet is what the reader sees on opening. It sets the expectation for the rest. + +The first page should deliver value within the first read. The reader has just downloaded; they are most engaged in the first 30 seconds. Use the first page to deliver the headline insight, the first checklist item, the template's first prompt, the calculator's first input. + +The first page should NOT. + +- Warm up with author bio. The reader did not download the magnet to read about the author. +- Spend space on brand-positioning. The reader knows whose brand they downloaded from; they want the value. +- Recap the marketing. The landing page already sold the magnet; the first page should deliver, not re-sell. +- Defer the value. "In Chapter 3, you will learn..." loses the reader who wanted the value now. + +The first-page test. Open the magnet. Does the first page deliver something useful? If yes, the first-page discipline holds. If no, redesign the first page to deliver value upfront. + +--- + +## Title-magnet alignment audit + +Periodically audit titles against the magnets they represent. Drift accumulates: titles get polished while magnets remain unchanged, and the gap between promise and delivery widens. + +The audit. + +- For each active magnet, read the title and open the magnet. +- Does the magnet deliver on the title's specific promise? +- If not, the gap is either a title that overpromises (fix the title) or a magnet that underdelivers (strengthen the magnet). + +The audit cadence. Quarterly is reasonable for active magnets. Drift detection is part of magnet portfolio maintenance. + +--- + +## Worked title revisions + +Original title: "Marketing Automation Guide." + +Failure: vague, generic, overpromises (which guide?). + +Revised title: "The 7-email re-engagement sequence we send to trial signups who go cold (with open and click rates)." + +What changed: specific deliverable (7-email sequence), specific situation (trial signups who go cold), specific evidence (open and click rates). + +Original title: "B2B Lead Generation Playbook." + +Failure: "Playbook" suggests volume without focus. "B2B Lead Generation" is too broad to focus a single resource. + +Revised title: "The cold-email template for B2B SaaS founders selling into mid-market product teams." + +What changed: specific format (template), specific audience (B2B SaaS founders), specific buyer (mid-market product teams). Niche by design. + +Original title: "The Complete Pricing Guide." + +Failure: "Complete" overpromises; "Pricing Guide" suggests volume; the guide will likely be a kitchen-sink-resource. + +Revised title: "The pricing one-pager template for SaaS founders raising a seed round." + +What changed: specific deliverable (one-pager template), specific situation (raising a seed round). Tight scope; usable immediately. + +The pattern: replace vague nouns and adjectives with specific deliverables, audiences, and situations. The revision often shrinks the addressable audience and improves the qualified-lead rate. + +--- + +## Common title and presentation failures + +Title overpromises. The reader downloads, opens, finds less than expected, and unsubscribes. + +Title is generic. Anyone could want this; no one specifically wants it. + +Cover signals stock content. Generic visual; reader's expectation drops before opening. + +Landing page hides the magnet. The reader has no evidence the resource will deliver; conversion suffers. + +First page warms up instead of delivering. Author bio, brand statement, table of contents. The reader's engagement drops. + +Drift between title and content. The title was strong at launch; the magnet has not been updated; the gap has widened over time. + +--- + +## Methodology-level choices that stay in the public skill + +Title patterns that work and fail. The honesty discipline. Cover and visual presentation patterns. Landing-page preview discipline. First-page discipline. The title-magnet alignment audit. Worked title revisions. Common failures. + +## Implementation choices that stay internal + +Specific titles for the team's magnets. Specific cover-design conventions and brand application. Specific landing-page templates and layout choices. Specific first-page templates and brand voice. The team's audit calendar and revision processes. These vary by team. diff --git a/skills/lead-magnet-design/references/would-they-pay-for-this-test.md b/skills/lead-magnet-design/references/would-they-pay-for-this-test.md new file mode 100644 index 0000000..3b1db15 --- /dev/null +++ b/skills/lead-magnet-design/references/would-they-pay-for-this-test.md @@ -0,0 +1,158 @@ +# The "would they pay for this" test + +The pricing thought experiment that distinguishes earned-value from thin-bait. A single test the magnet either passes or fails before launch. + +The question is simple. If the magnet were not free, would someone in the target audience actually pay for it? Not pay enterprise pricing, not pay for a course, but pay something (5 dollars, 25 dollars, 100 dollars) because the value is concrete enough to justify the cost? + +The honest answer matters. A magnet that fails the test is signaling that the value is below "I would pay for this," which means the reader's time investment to download and consume is at the edge of "worth it." The unsubscribe rate, the reduced trust, and the wasted email gate all follow from a failed test. + +--- + +## How to apply the test + +The test is a thought experiment, not a market study. Run it before the magnet ships. + +Step 1: Imagine a stranger in the target audience. Not the team's existing customer; not someone already on the list. A stranger who has not yet committed to the brand. + +Step 2: Imagine showing them the magnet (the actual content, not the marketing). Not the landing page; not the headline; the resource itself in the form they would receive it. + +Step 3: Ask: would this person, having seen this resource, pay something for it? A small amount, an honest amount. + +Step 4: Be specific about the price. Would they pay 5 dollars? 25 dollars? 100 dollars? The specific number forces an honest answer. + +The test fails when the honest answer is "no, they would not pay for this; they would expect it to be free or to come bundled with something else." The test passes when the honest answer is "yes, this is worth paying for, even at a small price, because the value is concrete." + +--- + +## What the test catches + +Three failure modes the test catches reliably. + +The 5-page PDF that summarizes blog content. Free elsewhere, available without a gate, worth 0 dollars in a paid context. Fails. + +The "Ultimate Guide" that nobody finishes. Pay-worthy in theory (comprehensive coverage), not delivered in usable form. The reader pays for the resource and never extracts the value because the resource is too long to consume. The test surfaces this when the team imagines whether the reader would actually use what they paid for. + +The template that is so generic it adds no value over starting from scratch. Pay-worthy framing (templates feel valuable), thin in execution (the template's content is "Insert your value here" 30 times). The test catches this when the team imagines the reader's reaction on opening the template. + +The test catches these failures because the question forces honesty about the resource's actual value rather than the resource's marketing claim. + +--- + +## What the test the magnet should pass looks like + +A magnet that passes is one where: + +- A reader in the target audience would pay for this resource because it produces a result they need. +- The resource is in a usable form (consumable in the time the reader is willing to spend, applicable to their specific situation). +- The resource is hard to find elsewhere or hard to assemble at the same quality. + +The first criterion is about value. The second is about usability. The third is about uniqueness or curation. A magnet that hits all three earns the email reliably. + +Worked example: A passing magnet. + +The B2B SaaS founder magnet "the welcome-email template that 4x'd our trial-to-paid rate." + +- Pay-worthy: a SaaS founder would pay 25-50 dollars for a template that demonstrably 4x'd a real trial-to-paid rate. The specificity (4x, real metric, real source) makes the payment plausible. +- Usable: 7 emails, copy-paste ready, with sender-side context for each. A founder can implement in 60 minutes. +- Unique: the specific template plus the specific result is not freely available elsewhere. + +The magnet passes. It is worth the email. + +Worked example: A failing magnet. + +The "Marketing Trends 2026" PDF. + +- Pay-worthy: a generic trends roundup is not worth paying for. Freely available analyses cover the same ground. The specificity is missing. +- Usable: a 30-page PDF of trend descriptions does not produce a result; it produces awareness, which the reader could have gotten elsewhere. +- Unique: marketing trend roundups are commoditized; this one is not differentiated. + +The magnet fails. It captures emails that decay because the resource did not earn the relationship. + +--- + +## When the test surfaces "almost passes" + +Sometimes the answer is "they might pay 5 dollars but not 25 dollars." This is signal, not failure. + +The action. Strengthen the resource until the answer becomes "yes, they would pay 25 dollars." This often means adding the specific worked example, the specific case study, or the specific tooling that makes the resource concretely useful. + +The risk of skipping. Shipping the "5 dollar" version saves time but produces conversion-rate metrics that look fine and lead-quality metrics that disappoint. The strengthened version costs more upfront and pays back in lead quality and downstream conversion. + +The test surfaces the gap between the magnet as built and the magnet at value-strong. The work to close the gap is often the difference between thin-bait and earned-value-magnet. + +--- + +## When the test surfaces "this should not be a magnet" + +Sometimes the honest answer is that the resource would not be paid for at any price. + +The action. Do not ship the magnet. Either redesign the resource until it would be paid for, or accept that the resource is content (not a magnet) and publish it ungated. + +The release valve. Not every piece of content has to be gated. Free, ungated content has its own value (SEO, distribution, brand). Forcing a gate onto thin content costs more than it adds. + +The test sometimes leads to "this should not be a magnet at all." That outcome is fine; it prevents shipping a thin-bait magnet that costs list trust. + +--- + +## When the test surfaces "this is so valuable we should sell it" + +Occasionally the honest answer is that the resource would be paid for at a meaningful price (200 dollars, 500 dollars). + +The decision. The team has a choice. Sell the resource (and use a different, more right-sized magnet for list-building) or use the high-value resource as the magnet (which signals exceptional generosity and often produces strong conversion at high lead quality). + +The high-value-as-magnet pattern. Some brands give away exceptionally valuable resources as magnets specifically to signal expertise and generosity. The conversion to paid offerings often increases because the magnet establishes credibility. + +The test surfaces this opportunity. The team's decision depends on the broader strategy. + +--- + +## The team-honesty discipline + +The test only works if the team answers honestly. Pressure to ship, sunk cost in production, attachment to the magnet's framing all bias the answer toward "yes." + +The discipline. + +- Have someone outside the magnet's authoring team apply the test. Outside-in honesty often catches what the authoring team rationalizes. +- Show the actual resource, not the marketing. The pretty landing page is not the test; the PDF or the template is. +- Be specific about the price. "Would they pay something" is too vague; "would they pay 25 dollars" forces specificity. +- Take the answer seriously. If the team applies the test and answers no, do not ship the magnet without redesign. + +The test's value is in the honesty it surfaces. A team that applies it and ignores the answer is worse off than a team that does not apply it at all. + +--- + +## What to do when the test fails + +The magnet fails the test. Now what. + +Option 1: Strengthen the magnet. Add the specific worked example, case study, tooling, or framework that brings the value to pay-worthy. This is often the right answer. + +Option 2: Redesign as a different format. The topic might not be magnet-shaped in the current format. A 30-page ebook on a topic might fail; a 2-page checklist on the same topic might pass. + +Option 3: Reframe the audience. The magnet's value depends on the audience. A magnet that fails for the broad audience might pass for a narrower segment that genuinely needs the resource. + +Option 4: Do not ship. Some magnets should not exist. Killing the magnet is honest; shipping a thin one costs more in list trust than killing it costs in sunk effort. + +The team's response to a failed test is the discipline marker. Strong programs redesign or kill; weak programs ship anyway. + +--- + +## Common test failure modes + +The team rationalizes the failure. "It is good enough; readers will appreciate it being free." This is the path to thin-bait. + +The team applies the test to the wrong audience. "Would a generalist marketer pay for this" when the magnet is for SaaS founders. The test must use the actual target audience. + +The team applies the test to the marketing, not the resource. The landing page sounds great; the resource is thin. The test surfaces this when applied to the actual content. + +The team skips the test under deadline pressure. The magnet ships, the metrics look fine, the unsubscribe rate quietly climbs. The test was the protection against this; skipping it costs trust. + +--- + +## Methodology-level choices that stay in the public skill + +The test as a thought experiment with specific steps. The failure modes the test catches. The criteria a passing magnet meets. The team-honesty discipline. The decision tree when the test fails. The test failure modes. + +## Implementation choices that stay internal + +Specific magnets the team has tested and the outcomes. Specific price-point conventions for the team's audience. The team's outside-team review process. Specific redesign patterns the team uses for failing magnets. These vary by team and audience. diff --git a/skills/logo-design/SKILL.md b/skills/logo-design/SKILL.md new file mode 100644 index 0000000..75d1e26 --- /dev/null +++ b/skills/logo-design/SKILL.md @@ -0,0 +1,206 @@ +--- +name: logo-design +description: "Generate logo variants for a brand, producing multiple production-grade marks across different architectures (wordmark, lockup, symbol-only, letterform-as-symbol, monogram) with rationale, application specs, and decision-ready presentation. Distinct from `brand-identity`, which produces the complete system (logo plus color, type, voice, applications). Goes deep on the logo specifically: typographic register, symbol approach, application-context discipline (16px favicon, embroidery, signage, motion), and production specs (SVG-ready, single-color, reverse). Triggers on logo design, design a logo, wordmark, monogram, lockup, mark variants, logo iterations, redesign or refine the logo, logo refresh, letterform-as-symbol, and exploring mark variants for an established brand. Does NOT fire for full brand identity (use `brand-identity`), positioning or strategy (use `brand-discovery`), project-wide creative direction (use `creative-direction`), or one-off illustration." +category: brand +catalog_summary: "Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol), with rationale and application specs" +display_order: 5 +--- + +# Logo Design + +A logo is a system of marks, not a single drawing. This skill produces multiple production-grade variants exploring different architectural approaches, each with rationale, application specs, and a clear position on what it signals and rejects. + +The output is decision material, not a finished logo. The brand owner selects from the variants and the skill produces production refinement on the chosen direction. + +--- + +## When to use + +- The brand has a name and tonal direction; the deliverable is logo work specifically +- Generating 6 to 12 variants for client review and selection +- Refining a wordmark to production: kerning, optical adjustments, weight selection +- Exploring symbol options to pair with an existing wordmark +- Designing a monogram from a longer name for use in constrained contexts +- Adapting an existing logo across application contexts (small-size, signage, motion, embroidery) +- The brand owner has reviewed a first round and wants iteration on a specific direction + +## When NOT to use + +- Use `brand-identity` instead when the deliverable is the complete identity system (logo plus color plus type plus voice plus applications). This skill is the logo-specific layer; brand-identity is the system layer. +- Use `brand-discovery` for brand positioning, audience, and voice work. A logo without strategy is a drawing. +- Use `creative-direction` for project-wide aesthetic direction. Creative direction calibrates many decisions; logo design produces specific marks. +- One-off illustration, icon, or pictogram work +- Designing brand patterns, textures, or supporting graphics +- Pure typographic exploration unrelated to a brand name + +--- + +## Required inputs + +- Brand name. Exact spelling. Capitalization and punctuation preferences if any. Whether the name has a category descriptor that travels with it (e.g., "Atlas Coffee" vs just "Atlas"). +- Industry or category. Legal firm, consumer goods, B2B SaaS, hospitality, etc. Category implies defaults that can be honored or broken. +- Audience. Who sees the logo, where, in what state of mind. The audience-side perception drives selection more than the founder-side aesthetic. +- Tonal direction. Where on the formal-to-casual axis. Where on the restrained-to-expressive axis. Where on the heritage-to-modern axis. +- Application contexts. Common set: web header, mobile app icon (28px), favicon (16 to 32px), business card, letterhead, email signature, social profile picture, signage (large format), embroidery patch (1.5 inch), single-color print, video motion lockup, merch (apparel, hats, totes). +- Reference logos liked, with a sentence each on what specifically resonates. The reference clarifies which architecture and register fit better than abstract description does. +- Reference logos disliked, with a sentence on what to avoid. Negative space sharpens positive selection. +- Hard constraints. Must include element X. Must avoid color Y due to industry conventions. Must reproduce in single color. Must work as a 16px favicon. Must survive embroidery. +- Optional: existing brand assets if the project is a refresh, not greenfield. Existing wordmark if the work is symbol-only. Existing color palette if it must remain locked. + +--- + +## The framework: 5 considerations for logo design + +A logo decision sits at the intersection of five considerations. Each one filters subsequent choices. + +### 1. Mark architecture + +What IS the logo, structurally? + +Architectures: + +- Wordmark only. The logo is the brand name set in a chosen typeface, possibly with custom letterforms. Stripe, Google, Pinterest. The discipline is letter-by-letter, with kerning, optical adjustments, sometimes a single distinguishing custom character. Strongest when the name is distinctive enough to own as type. +- Lockup (wordmark plus symbol). Standard architecture for most brands. The wordmark and symbol are positioned in a fixed relationship. Slack, Airbnb, Asana. Variants: symbol left of wordmark, symbol above wordmark, symbol right (rare). Each lockup may also have a stacked alternate for square contexts. +- Symbol only. The mark is a single symbol with no wordmark. Apple, Twitter, Target. Earned over decades through brand recognition. New brands rarely succeed with symbol-only as the primary mark, though most mature brands eventually develop a symbol-only fallback. +- Letterform-as-symbol. A single letter from the name (often the first) becomes the symbol. Beats by Dre's "b", McDonald's "M", Underscore's "_". Cleanest path to symbol when the wordmark is too long for a tight lockup or when the name has a letter that lends itself to visual play. +- Monogram. Multiple letters combined as a symbol. CN (Chanel), GG (Gucci), HBO, MN (a hypothetical Morgan Northrop monogram for an institutional financial firm). Common in legal, financial, hospitality, and heritage brands. Can read as initials or as ligature. + +How to choose: What does the brand need to do at small sizes? At 16px, most lockups fail. A favicon-grade mark needs either a strong symbol component or a letterform-as-symbol fallback. Lockups also need stacked alternates for square contexts (social profile pictures, app icons). A pure wordmark works only if the brand has another mark that can stand in at small sizes, often a letterform-as-symbol or monogram. + +A common production setup is: primary lockup for most contexts, monogram for square contexts, letterform-as-symbol for favicon and embroidery. All three derive from the same wordmark and share visual DNA. + +### 2. Typographic register + +If wordmark or lockup, what typographic family carries the type? + +Registers: + +- Geometric sans. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde. Built from circles and verticals. Reads modern, considered, often optimistic. Risks reading cold or generic-tech-startup if not warmed up by color, custom letterform, or context. +- Humanist sans. Gill Sans, Optima, Frutiger, Source Sans, Inter at higher optical sizes. Has serif-like calligraphic gestures without serifs. Reads professional but warm. Excellent neutral choice when the category demands restraint with personality. +- Neo-grotesque sans. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America. The modern professional default. Reads competent and contemporary. Risks reading generic if not paired with strong color or symbol. +- Transitional serif. Source Serif, Charter, Lyon, IBM Plex Serif. Modern serifs with high contrast and readability. Reads editorial, considered, intellectual. Good for legal, publishing, financial, editorial brands. +- Old-style serif. Garamond, Caslon, Sabon, Adobe Garamond. Classical serifs with low contrast and warm shapes. Reads heritage, traditional, institutional. Common in academic, legal, financial, and heritage brands. +- Slab serif. Sentinel, Adelle, Roboto Slab, Tisa. Heavy structural serifs. Reads strong, declarative, sometimes journalistic. Common in editorial and publishing. +- Display custom. A custom-drawn or heavily-modified typeface. Reads distinctive but expensive in time. Justified when the brand needs a wordmark no one else has and the budget supports drawing one. + +How to choose: What does the brand reject? Most categories have a default register. Legal firms default to old-style or transitional serif. Tech startups default to geometric or neo-grotesque sans. Choosing within the category default reads as competence; choosing outside reads as positioning. A boutique legal firm in geometric sans signals "modern, accessible". A SaaS startup in old-style serif signals "we take ourselves seriously". + +### 3. Symbol approach + +If the architecture includes a symbol (lockup, symbol-only, letterform-as-symbol), what KIND of symbol? + +Approaches: + +- Literal. The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. Fast recognition, low ambiguity. Risks reading as cliche if the depiction is generic. Saved by distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. +- Abstract gesture. The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity". Slower recognition, higher distinctiveness. Risks reading as arbitrary if the gesture is too abstract. Saved by clear formal logic and consistent visual vocabulary. +- Geometric reduction. The symbol is a formal abstraction with no specific referent. A hexagon, a triangle, a stack of horizontal lines, a circle bisected by a vertical. Reads modern and confident. Risks reading as identical to many other geometric-reduction marks. Saved by specific proportions, considered execution, and pairing with a distinctive wordmark. +- Letterform-derived. The symbol is built from the name's letterforms. The "M" of McDonald's, the "b" of Beats, a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. Strong wordmark-symbol coherence. Risks reading as wordmark-only if the letterform isn't emphasized enough. Saved by exaggerated character: the letter must read as both the letter AND the visual metaphor. +- Monogram. Multiple initials combined. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). Common in legal, financial, hospitality. Risks reading as old-fashioned if the type treatment is too conservative. Saved by modern execution within traditional architecture. + +How to choose: What does the brand name already do? Descriptive names (Atlas, Forge, Pulse, Anchor) invite literal symbols and letterform-as-symbol approaches. Abstract names (Stripe, Anthropic, Linear) demand abstract or geometric-reduction symbols. Heritage names (a founder's surname, a place name) often use monograms. The wrong approach disconnects symbol from name. + +### 4. Application context discipline + +A logo is not a single drawing. It must work in every context the brand touches. + +Contexts and their constraints: + +- 16px favicon. The most aggressive small-size test. Lockups usually fail here; the symbol or letterform-as-symbol carries. Plan a fallback mark for this context from the start. +- 28px app icon. Slightly more headroom than favicon. Still demands strong silhouette. Often uses the symbol or monogram, not the lockup. +- 1.5 inch embroidery patch. Limits color count (often 4 to 6 max), demands clean shapes without fine detail. Eliminates gradient and photographic elements. Tests the mark's reproducibility in a tactile medium. +- Single-color reproduction. Etching, foil stamp, single-color print, fax. All gradient and color-dependent decisions must collapse cleanly to one color. Test by converting the design to pure black on white. +- Reverse (light on dark). Many marks fail when reversed. Test on the brand's expected dark backgrounds early. Gradient marks particularly struggle here. +- Large-format signage. Requires sharp vector with no rasterization. Tests construction grid quality. Tests whether thin strokes survive scaling. +- Motion lockup. Tests whether the logo has natural entry and exit animation. Wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts. +- Social profile picture (square). Lockups need a stacked alternate or monogram fallback. Symbol-only works natively. +- Apparel embroidery (thread on fabric). Tighter constraints than patch embroidery. Fine letterforms and detail die here. The mark needs a chunky-friendly variant. +- Foil stamp on paper or leather. Single-color, no gradients, requires substantial line weight to survive the impression. + +The discipline: Every variant must pass the application-context test before it's a contender. Generate each variant, then mentally test each context. If a variant fails three or more contexts, it's not a primary mark; it might still serve as a secondary or display lockup but it isn't carrying the brand. Build a fallback hierarchy: primary lockup, secondary monogram, favicon-grade letterform-as-symbol. + +### 5. Restraint discipline + +Most logo failure happens through over-design. The discipline is subtractive. + +Tests: + +- Silhouette test. Squint at the logo. If you cannot identify it from silhouette alone (with type stripped), the silhouette is too generic. Apple, Nike, Twitter pass. Most generic SaaS marks fail. +- Distinctiveness test. Search Google Images for "[your category] logo". If your candidate looks identical to three or more existing logos, it's not distinctive enough. Especially watch out for geometric-reduction marks that have already been done a thousand times. +- Sketchability test. A 7-year-old draws the logo from memory after 30 seconds of looking. If they can't, it's too detailed to live in cultural memory. +- Single-color test. Strip all color. Does it still read? If no, color is doing too much work. +- Reproducibility test. Print at 1 inch on a black-and-white printer. Is it still recognizable? If no, the mark won't survive embroidery, foil stamps, or low-resolution applications. +- The two-second test. Show the logo to someone unfamiliar with the brand for two seconds. Ask what they remember. The features they recall are the ones doing real work; the rest is noise. + +The discipline doesn't reject all detail. It rejects detail that doesn't earn its place. Every visual element should pass the question "does this read at the smallest application size?". + +--- + +## Workflow + +1. Gather inputs. Required inputs above. If the user has reference logos, walk through what specifically resonates in each. The references calibrate which architecture and register actually fit. + +2. Establish primary architecture. Wordmark-only? Lockup? Letterform-as-symbol? Monogram? This is the foundational decision; everything else flows from it. For most new brands with a distinctive descriptive name, the right architecture is lockup with literal or letterform-derived symbol, plus a monogram fallback for square contexts. + +3. Generate typographic explorations. Produce 3 to 4 wordmark-only variants exploring different typographic registers. Each variant should be a complete, kerned, optically-adjusted wordmark. These serve as both standalone candidates and as the foundation for subsequent symbol pairing. + +4. Generate symbol explorations (if architecture includes a symbol). For each typographic exploration, generate 1 to 2 symbol pairings using different symbol approaches (literal, abstract gesture, letterform-derived, monogram). The symbol must visually agree with the wordmark's type weight, optical density, and tonal register. A heavy slab wordmark needs a chunky symbol; a hairline geometric wordmark needs a thin symbol. + +5. Test each variant against application contexts. For each candidate, walk through 16px favicon, 1.5 inch embroidery, single-color reproduction, square stacked alternate. Eliminate variants that fail more than two contexts. Document which contexts each variant excels in versus needs a fallback for. + +6. Pick top candidates for client review. Typically 6 to 12 final variants. Each variant must be visually distinct from the others. Variants that are too similar dilute the review and frustrate the client (they cannot tell why they should pick one over the other). + +7. Document each variant. Per-variant: descriptive name (e.g., "01, Light geometric wordmark, Avenir Next"), architecture, typography, symbol approach if applicable, color tokens, application notes, signals (what it communicates), rejects (what it explicitly is NOT). + +8. Provide production specs for the top 3 candidates. SVG-ready construction notes, color hex codes (primary plus single-color black plus single-color white plus reverse), sizing guidelines (minimum sizes per medium), motion entry and exit recommendation, embroidery and foil-stamp adaptations. + +9. Provide application mockups. Render each top candidate in 3 to 5 representative contexts: web header, business card, favicon at 16 and 32px, embroidery patch, signage. Mockups can be image-generated or schematic. The point is to show the client how the mark lives across contexts, not to deliver finished marketing material. + +10. Hand off. Output is decision material. The brand owner selects a direction. The skill (or a follow-up iteration) then produces production refinement on the chosen path: cleaner construction, refined kerning, color system finalization, application library. + +--- + +## Failure patterns + +- Designing for the founder's taste, not the audience's perception. The founder sees the logo every day; the audience sees it for 3 seconds in a bad mood. The audience-side test wins. +- Skipping the silhouette test. Logos that fail silhouette die at small sizes and in motion. Test early. +- Ignoring small-size legibility. A favicon test at 16px is the single most overlooked discipline. Most lockups fail here. Plan a fallback symbol or letterform-as-symbol mark from the start. +- Trying to depict everything the brand does. Logos can hold one idea, sometimes two. Three is too many. Symbols stuffed with multiple metaphors read as committee work. +- Picking a typeface for trend. Monoline geometric sans (Cabinet Grotesk, GT Pressura) read as "2024 startup" in a way that ages quickly. Pick for category-fit and longevity, not for design-trend currency. +- Over-customizing letterforms. Custom letterforms should solve a specific problem (a flat-bottomed "g" that conflicts with a descender, an "a" that breaks the rhythm, an "A" that becomes a mountain peak). Custom for novelty's sake reads as gimmicky. +- Lockups that fall apart at certain sizes. Test the lockup at 200%, 100%, 50%, 25%. If proportions break or elements clash at any size, the lockup needs adjustment. +- Color-dependent marks. A logo that requires color to be recognizable cannot survive single-color reproduction. Color is the last layer, not the foundation. +- Letterform-as-symbol marks that fail the silhouette test for the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. +- Reviewing too many similar variants. Showing a client 10 wordmark variants in different geometric sans typefaces dilutes the decision. Show 3 architectures, with 2 to 3 typographic options each. The client can see the architectural choice clearly. +- Skipping the embroidery test. Many brands eventually want a hat or a polo. A logo with fine detail or photographic gradients cannot be embroidered cleanly. Test before client signoff. + +--- + +## Output format + +Default output is a markdown spec with multiple variants, typically saved as `logo-variants.md` at the project root or in a `design/` subdirectory. The spec is paired with rendered images for each variant, saved alongside (typically in `design/logo-variants/`). + +Per-variant structure: + +1. Variant name. Descriptive identifier with index (e.g., "01, Light geometric wordmark, Avenir Next" or "07, Mountain peak A lockup, IBM Plex Sans"). +2. Architecture. Wordmark / Lockup / Symbol / Letterform-as-symbol / Monogram. +3. Typography. Specific typeface name and weight. Custom letterform notes if any. Tracking and kerning treatments. +4. Symbol description (if applicable). Approach (literal / abstract gesture / geometric reduction / letterform-derived / monogram) and visual description. Construction grid notes if relevant. +5. Color tokens. Hex codes for primary palette, single-color black version, single-color white version, reverse-on-dark treatment. +6. Application notes. Which contexts the variant excels in (e.g., "strong at large signage and letterhead") and which contexts need a fallback mark (e.g., "favicon falls back to letterform-as-symbol at 16px"). Embroidery adaptation notes if relevant. +7. Signals. What this variant communicates about the brand. The features it foregrounds. +8. Rejects. What this variant explicitly is NOT. The negative space the variant creates. +9. Mockups. Rendered in 3 to 5 application contexts. At minimum: web header, business card, favicon. Bonus: embroidery patch, large-format signage, social profile. + +The spec is decision material. The next step after delivery is selection plus production refinement on the chosen direction. + +--- + +## Reference files + +- [`references/architectures-explained.md`](references/architectures-explained.md). The 5 mark architectures with examples, when each fits, when each fails, and how to combine them in a primary plus fallback hierarchy. +- [`references/typographic-registers.md`](references/typographic-registers.md). The typographic registers with named typefaces, category-fit notes, and example brands per register. +- [`references/symbol-approaches.md`](references/symbol-approaches.md). The 5 symbol approaches with pattern examples, calibrating the agent's vocabulary for symbol generation. +- [`references/application-contexts.md`](references/application-contexts.md). The contexts every logo must pass, with constraint specs (favicon size, embroidery color count, single-color rules, motion entry recommendations). +- [`references/category-conventions.md`](references/category-conventions.md). A survey of common conventions across major brand categories, with defaults that work, conventions worth honoring, conventions worth breaking for positioning, and category-specific application contexts. +- [`references/example-variant-spec.md`](references/example-variant-spec.md). A complete example showing all nine per-variant fields filled in for a representative project. +- [`references/client-package.md`](references/client-package.md). The package format clients expect at delivery: file format matrix, variant matrix, folder structure, naming convention, documentation layer (usage guide plus brand colors plus license), delivery mechanisms, and the failure patterns that send the client back asking for a missing variant. diff --git a/skills/logo-design/references/application-contexts.md b/skills/logo-design/references/application-contexts.md new file mode 100644 index 0000000..a9cba88 --- /dev/null +++ b/skills/logo-design/references/application-contexts.md @@ -0,0 +1,312 @@ +# Application contexts + +A logo is not a single drawing. It is a system of marks that must work in every context the brand touches. Most logo failure happens because a designer optimized for one context (typically the web header at 200px wide) and never tested the others. This file expands the application contexts in [SKILL.md](../SKILL.md) with specific constraint specs, common failure modes, and mitigation patterns. Use it as the working checklist for every variant before declaring a candidate ready for review. + +The discipline is to design for the smallest, harshest application FIRST, then scale up. Most brand systems do the opposite: they design at the marketing scale and discover at production time that the mark cannot survive its smaller, harsher applications. + +--- + +## 16px favicon + +The most aggressive small-size test. The mark renders inside a 16x16 pixel grid (some browsers go to 32x32, but 16x16 is the historical baseline and still the test that reveals construction problems first). + +### Constraints + +- 16x16 pixels means roughly 4 to 6 distinguishable visual elements maximum +- No fine detail; lines under 2px disappear +- No gradients (gradients render as muddy color washes at this scale) +- No more than 3 to 4 colors before the rendering algorithm dithers +- Symbol or letterform must read at thumbnail scale, not as a logo + +### Failure modes + +- Lockups (wordmark plus symbol) almost always fail; the wordmark becomes illegible +- Fine letterform details (custom serifs, decorative crossbars) disappear +- Multi-color symbols dither into pixel noise +- Symbols with internal cutouts or fine negative space lose the cutout at 16px +- Geometric reductions with multiple primitives blur together + +### Mitigation patterns + +- Ship a dedicated 16x16 favicon-grade asset, not a downscaled version of the lockup +- Use a single element from the lockup (the symbol alone, the letterform-as-symbol, or the monogram) at favicon scale +- Test the favicon on actual browser tabs (Chrome, Safari, Firefox) at the operating system level; the rendering differs from a Photoshop preview +- If the favicon-grade asset cannot be derived from the lockup, the lockup itself is over-detailed; redesign the lockup so a clean 16x16 fallback exists + +--- + +## 28px app icon + +iOS, Android, and PWA app icons. Slightly more headroom than favicon (28x28 to 60x60 depending on rendering context) but still demanding strong silhouette. + +### Constraints + +- 28x28 to 60x60 pixels (varies by OS rendering context: notification badge, home screen, settings menu) +- Must work inside rounded-square or circle masks (iOS), rounded-square (Android) +- 4 to 8 distinguishable visual elements maximum +- Background color matters: app icons have visible bounds, so the mark either fills the icon background or sits inside a colored field +- No fine detail; lines under 3px disappear at the smallest rendering scales + +### Failure modes + +- Lockups fail at this scale almost as often as at favicon scale +- Symbols with thin strokes lose definition +- Multi-color symbols clash with the icon background fill +- Marks that depend on negative-space cutouts lose those cutouts +- Marks designed for a square ratio fail when rendered inside a circle mask + +### Mitigation patterns + +- Design the app icon as a separate asset, not a downscaled lockup +- Use the symbol or monogram, not the wordmark +- Pick a strong fill color that supports the symbol (not a generic white background) +- Test the app icon at every required size (29, 40, 60, 76, 80, 87, 120, 152, 167, 180, 1024 for iOS) and at every mask shape (rounded-square iOS, circle for some Android launchers) +- Ship a "monochrome" or "tinted" variant for iOS dark mode and tinted home screen modes (a single-color silhouette of the app icon) + +--- + +## 1.5 inch embroidery patch + +Tactile reproduction at small scale. Embroidered patches for hats, jackets, polos, and merchandise. The most demanding physical reproduction context. + +### Constraints + +- 1.5 inch diameter is the common patch size (some go to 2 or 2.5 inches) +- Color count: 4 to 6 maximum (each thread color is a separate setup cost) +- Minimum stroke weight: roughly 1mm (depends on the embroidery machine and thread weight) +- No gradients, no photographic elements, no fine textures +- Letterforms below 2mm tall do not embroider cleanly +- Sharp inside corners and acute angles fail under the needle path + +### Failure modes + +- Marks with more than 6 colors require expensive multi-step embroidery or get simplified by the embroiderer in ways the brand owner did not approve +- Fine letterforms (Garamond at small sizes, Helvetica Light) become muddy or fall apart +- Gradient marks fail entirely; the embroiderer either drops the gradient (changes the brand) or refuses the job +- Symbols with thin internal lines lose those lines under the thread weight +- Marks designed for screen do not anticipate the chunky construction embroidery requires + +### Mitigation patterns + +- Design an embroidery-grade variant of the mark from the start: simplified silhouette, chunky stroke weights, 4 colors maximum +- Test the variant against an actual embroidery sample (not a screen preview) before committing +- Pick a typeface for the wordmark that survives embroidery (slab serifs, heavy sans-serifs, custom thick letterforms work; thin sans-serifs and Garamond do not) +- For brands that anticipate substantial merchandise (apparel brands, hospitality brands, sports teams), build the embroidery-grade variant into the primary system, not as an afterthought + +--- + +## Single-color reproduction + +The mark must render in a single color, on any background, for any reproduction medium that does not support color. Etching, foil stamp, single-color print (offset or letterpress), faxed documents (still happens for legal and financial), engraving, screen printing limited to a single color. + +### Constraints + +- Pure black on white, pure white on black, or single ink color +- No gradients (must collapse to flat color) +- No color-dependent meaning (a symbol that means one thing in red and another in blue fails) +- No subtle color contrasts (a symbol with two shades of gray loses information when reduced to one color) + +### Failure modes + +- Color-dependent marks (the brand identity is the color, not the form) cannot be reproduced +- Gradients become muddy in single-color etching or foil +- Multiple-color symbols collapse to a single shape that does not read as the original +- Marks that rely on color-coded brand meaning (red = action, blue = trust) lose meaning +- Embossed or debossed reproductions test the construction grid; thin lines fail under embossment + +### Mitigation patterns + +- Test the design as a pure black-on-white silhouette early; if it does not read in monochrome, color is doing too much work +- Build a dedicated single-color version of the mark with stroke weights and proportions adjusted for monochrome reproduction +- Make sure the single-color version reads as the brand without color +- Pick application contexts that match the single-color variant (foil stamp on letterhead, engraved signage, etched glass, leather embossing, single-color print) + +--- + +## Reverse on dark + +The mark on a dark background. The brand's web header in dark mode. The signage at night. The product photography on a black field. The letterhead variant for black envelopes. Many marks fail when reversed because the negative space and stroke balance shift. + +### Constraints + +- Light strokes on dark background; the form is what is visible, not what is empty +- Gradient marks particularly struggle (the gradient direction may need to invert) +- Color contrast must remain readable (a brand color that works on white may disappear on black) +- Negative-space marks (where the brand identity is the empty space, like FedEx's hidden arrow) require careful inversion handling + +### Failure modes + +- Marks designed for light backgrounds invert into something that looks like a different mark +- Color contrast fails (yellow on black is fine; pale yellow on black is illegible) +- Thin strokes optimized for white-on-black render too heavy when inverted to black-on-white +- Symbols with internal cutouts work in one direction but not the other +- Brand color decisions made for one direction read wrong in the other + +### Mitigation patterns + +- Test every mark on dark backgrounds early in the process, not at production time +- Build dedicated reverse-on-dark variants where stroke weights or proportions are adjusted +- For marks that must work on both light and dark, design the construction grid so it is direction-neutral (Apple's apple, Nike's swoosh) +- For marks that cannot be neutral, ship two variants: light-on-dark and dark-on-light, with construction tuned for each + +--- + +## Large-format signage + +The mark at building scale. Storefront signage, lobby walls, conference signage, billboard, vehicle wrap. The opposite end of the scale spectrum from favicon. + +### Constraints + +- Sharp vector with no rasterization; print resolution must support 12+ feet output +- Construction grid integrity matters at every scale (proportional adjustments that work at 1 inch may not work at 12 feet) +- Thin strokes that survive at marketing scale may look anemic at signage scale +- Color reproduction differs (a brand color that prints clean on paper may print different on backlit acrylic, vinyl, or painted aluminum) +- Distance reading: the mark must read at street scale (50 to 200 feet) + +### Failure modes + +- Wordmarks with thin strokes look anemic at 12 feet +- Fine letterform details that read at marketing scale disappear at signage scale +- Color decisions based on screen rendering do not match the actual material (vinyl, paint, acrylic, illuminated channels) +- Lockups designed for desktop scale crowd or stretch when forced into signage's typical aspect ratios + +### Mitigation patterns + +- Test the mark at 8 to 12 feet wide as a printed mock-up before committing +- Build signage-grade variants where stroke weights are adjusted for distance reading +- Specify Pantone colors (not RGB or hex) for signage color reproduction +- For illuminated signage (channel letters, backlit acrylic), test the mark with the illumination direction the actual sign will use (front-lit, halo-lit, edge-lit each render differently) + +--- + +## Motion lockup + +The mark in animation. Brand entry sequences in video, app launches, motion identity. The mark is no longer static; it moves, scales, fades, transforms. + +### Constraints + +- The mark must have a natural entry and exit animation +- The construction must support stage-by-stage reveal (wordmarks reveal letter-by-letter; symbols rotate, scale, or assemble from parts) +- Frame rate: 30 to 60 fps for web, 24 fps for film +- Total animation duration: typically 1 to 3 seconds for brand entry; 0.5 to 1 second for app launch +- Easing curves must feel intentional, not generic + +### Failure modes + +- Marks with arbitrary construction have no natural animation; they snap into place rather than assembling +- Wordmarks animated with random letter entrance look generic; the entrance must follow the letterform construction +- Symbols animated with rotation or scale alone read as obvious; the animation should reveal something about the symbol's construction +- Animation duration too long becomes annoying; too short and the mark does not register + +### Mitigation patterns + +- Design the mark with animation in mind: the construction should suggest its own assembly +- Specify the motion direction: how does the mark enter, hold, and exit? +- Build a 1-second motion identity that works for app launch, video brand entry, and social media +- Test the motion at the actual deployment surface (app launch screen, social video, in-product brand entry) + +--- + +## Social profile picture (square) + +The mark in a square crop, usually inside a circle mask (Twitter, Instagram, LinkedIn, most social platforms). Lockups need a stacked alternate or symbol-only fallback. Symbol-only marks work natively. + +### Constraints + +- Square aspect ratio (often 400x400 to 800x800 pixels for social profile) +- Often rendered inside a circle mask, so the corners of the square are cropped +- Small enough size that fine detail disappears +- Must read in the user's notification feed at thumbnail scale (60-80 pixels) +- Color contrast against various background colors (light and dark mode platforms) + +### Failure modes + +- Horizontal lockups crop badly inside square; the wordmark loses its left and right edges +- Marks not designed for circle masking lose corners and read as cropped +- Detail that survives at 200x200 disappears at the 60-80 pixel notification feed scale +- Color choices that work on white backgrounds clash with the platform's darker UI + +### Mitigation patterns + +- Design a stacked alternate (symbol above wordmark, centered) for square contexts +- Use the symbol-only or monogram fallback for the social profile +- Test the mark inside a circle mask, not just inside a square +- Verify the mark reads at notification feed scale (60-80px), not just at the profile picture display scale (200-400px) + +--- + +## Apparel embroidery + +Thread on fabric, smaller scale than patch embroidery. Polo shirts, hats, beanies, t-shirts, aprons. The mark is embroidered directly into the fabric, often without a patch backing. + +### Constraints + +- Color count: 4 to 6 maximum (each thread color is a setup cost) +- Minimum stroke weight: 1.5mm to 2mm (heavier than patch embroidery because the fabric is the substrate) +- No gradients, no fine detail, no photographic elements +- Letterforms below 2.5mm tall do not embroider cleanly +- Fabric texture affects the read (cotton vs polyester vs wool render differently) +- The mark must survive washing (thread that bleeds or unravels on first wash is a quality failure) + +### Failure modes + +- Fine wordmark letterforms become muddy or fall apart +- Multi-color marks become expensive or get simplified without approval +- Marks with thin strokes do not survive washing cycles +- Marks not designed for fabric look pasted-on rather than embroidered + +### Mitigation patterns + +- Design a dedicated apparel-embroidery variant with chunky stroke weights and minimal color +- Specify thread colors (Madeira, Robison-Anton, or other professional embroidery thread brands) rather than CMYK or hex +- Test the variant on the actual fabric weight and color before committing +- Pick the variant of the mark that survives apparel embroidery (the symbol alone, the monogram, the simplified lockup) + +--- + +## Foil stamp on paper or leather + +Single-color metallic stamping. Business cards, letterhead, bound books, leather portfolios, signet rings, wax-seal-style stamps. The mark is impressed into the substrate with metallic foil. + +### Constraints + +- Single color (gold, silver, copper, black foil, etc.); no gradients +- Substantial line weight required (1mm+ minimum for gold or silver foil) +- No fine letterforms; thin serifs disappear under the foil impression +- The substrate matters (matte vs glossy paper, leather vs vellum); each renders differently +- The mark must read in metallic, not as a flat color + +### Failure modes + +- Thin letterforms disappear or look uneven under the foil +- Marks that depend on color contrast lose meaning in single-color metallic +- Heavy fills require more foil and may bleed at the edges +- Marks designed for screen rendering do not translate to the tactile, reflective surface of foil + +### Mitigation patterns + +- Design a foil-stamp variant with chunky stroke weights +- Specify foil color (PMS gold, silver, copper) and finish (matte vs glossy foil) +- Test the variant against the actual substrate (the brand's letterhead paper, the brand's leather portfolio cover) before committing +- Treat foil-stamp applications as a hierarchy decision: which mark goes here, given the constraints? + +--- + +## The discipline, restated + +Every variant under consideration must pass the application context test before it is a contender. The working checklist: + +1. 16px favicon. Does the mark survive at smallest scale? +2. 28px app icon. Does the mark work inside rounded-square or circle masks? +3. 1.5 inch embroidery patch. Can the mark be embroidered with 4-6 colors and chunky strokes? +4. Single-color reproduction. Does the mark read in pure black on white? +5. Reverse on dark. Does the mark hold up inverted on a dark background? +6. Large-format signage. Does the mark survive scaling to 12 feet? +7. Motion lockup. Does the mark have a natural entry and exit animation? +8. Social profile picture. Does the mark work inside a circle mask at 80px? +9. Apparel embroidery. Does the mark survive thread on fabric? +10. Foil stamp. Does the mark survive single-color metallic impression? + +If a candidate fails three or more of these, it is not a primary mark. It might still serve as a secondary or display lockup, but it is not carrying the brand. The brand needs a fallback hierarchy: primary lockup, secondary monogram or symbol-only, tertiary letterform-as-symbol or simplified mark for the harshest applications. + +The hierarchy is the system. The system is what makes the brand readable across every context the audience encounters. diff --git a/skills/logo-design/references/architectures-explained.md b/skills/logo-design/references/architectures-explained.md new file mode 100644 index 0000000..4eac4c8 --- /dev/null +++ b/skills/logo-design/references/architectures-explained.md @@ -0,0 +1,165 @@ +# Mark architectures explained + +The architectural decision is the foundational one. Every other choice (typographic register, symbol approach, application context discipline) flows from it. This file expands the five architectures listed in [SKILL.md](../SKILL.md) with reference brands, fit and failure modes, and a working pattern for combining them in a primary-plus-fallback hierarchy. + +--- + +## Wordmark only + +The logo is the brand name set in a chosen typeface, possibly with custom letterform interventions. No standalone symbol. The wordmark IS the mark. Stripe, Google, Pinterest, FedEx, eBay, Coca-Cola, Visa. + +The discipline is letter-by-letter. Kerning is not optional. Optical adjustments matter at every weight. A wordmark earns its place when the brand name is distinctive enough that the type alone carries identity. Stripe's wordmark uses a single-character optical adjustment on the lowercase "r" that makes the word read as a unit; without it, the word fragments visually. FedEx hides an arrow in the negative space between the "E" and the "x", a famous earned detail that the brand's audience finds and remembers. Google's wordmark redrew its own custom geometric sans (Product Sans) so the brand owns the wordmark's specific letterforms. + +Wordmark-only works hardest at small sizes. The full wordmark fails at favicon scale almost universally. A wordmark-only brand still needs a fallback mark for 16px contexts, embroidery, and stacked square applications, even if that fallback never appears in the primary lockup hierarchy. + +### When this fits + +- The name is short (4 to 8 letters works best; 9 to 12 is the upper edge) +- The name has at least one distinguishing letter or letter combination +- The brand has high enough recognition that the wordmark alone signals identity +- The category rewards type-led restraint (editorial, financial, professional services) +- There is room and willingness to pay for custom letterform work + +### When this fails + +- The name is long (10+ letters) and the wordmark cannot fit common contexts +- The category demands instant visual recognition (consumer goods at shelf, app icons) +- The wordmark's letterforms are generic and the brand cannot afford custom drawing +- The brand has no fallback mark for square contexts, social profiles, embroidery +- The wordmark looks identical to many other brands' wordmarks in the same category + +### Combining in a hierarchy + +Wordmark-only as the primary requires a separate symbol-grade asset for square and small contexts. The most common production setup pairs a wordmark with a letterform-as-symbol fallback. Pinterest does this: the wordmark is the primary, the "P" inside a circle is the avatar mark. Stripe does this with a custom geometric "S" for the favicon. The fallback shares visual DNA with the wordmark (same weight class, same custom letterform language) so the system reads as one mark with two surfaces. + +--- + +## Lockup (wordmark plus symbol) + +A wordmark and a symbol locked into a fixed relationship. Slack, Airbnb, Asana, Spotify, MasterCard. This is the default architecture for most brands because it covers the widest range of application contexts with the fewest fallbacks. + +Lockups have variants. Symbol-left-of-wordmark is most common (left-to-right reading languages naturally pull the eye to the symbol first, then the wordmark). Symbol-above-wordmark works when the symbol is tall and narrow or when the lockup must fit a vertically constrained space. Symbol-right-of-wordmark is rare and usually reserved for editorial or signature treatments. Each lockup also tends to have a stacked alternate (symbol above wordmark, centered) for square contexts and an isolated symbol-only fallback for the smallest applications. + +The construction discipline is geometric. The symbol's optical weight should match the wordmark's stroke weight. The space between symbol and wordmark should be tied to the wordmark's x-height or cap height (e.g., the gap equals one x-height of the wordmark). Slack's lockup uses a tightly proportioned hash symbol whose stroke matches the wordmark's stroke at every weight, and the gap is sized to the wordmark's x-height. Without this geometric discipline, lockups fall apart at scale: stretched at large sizes, crowded at small ones. + +### When this fits + +- The brand needs a symbol-grade asset alongside the wordmark +- The wordmark alone is not distinctive enough at small sizes +- The category benefits from a symbol's ability to travel beyond text contexts (apps, signage, branded merchandise) +- The brand will deploy both the symbol and the lockup in different contexts +- The brand has the budget for two finished assets (symbol and wordmark) instead of one + +### When this fails + +- The lockup falls apart at small sizes because the symbol carries detail that disappears +- Symbol and wordmark visually compete (different weight class, different optical density) +- The lockup has no stacked alternate for square contexts +- The brand uses the lockup at favicon scale, where the symbol-only or letterform-as-symbol fallback should carry +- The symbol is too literal or too abstract for the wordmark's tonal register + +### Combining in a hierarchy + +The most common production hierarchy: lockup primary, symbol-only fallback for square and small contexts (social profile, app icon, favicon at 24-32px), letterform-as-symbol or monogram for embroidery and 16px favicon. Slack ships exactly this: the lockup for marketing surfaces, the hash symbol alone for app icons, a simplified hash for favicon and embroidery. The hierarchy is one identity expressed across three asset grades. + +--- + +## Symbol only + +The mark is a symbol with no accompanying wordmark in the primary asset. Apple, Twitter (the bird era and the X era), Target, Nike's swoosh, Mercedes-Benz, Mastercard's circles. This is the highest-recognition tier and is almost never available to new brands. + +Symbol-only as the primary mark requires brand recognition the audience already holds. Apple did not start as symbol-only; the original Apple logo was a Newton-under-an-apple-tree illustration with the word "Apple Computer Co." beside it. The bitten apple symbol earned its standalone status across decades of advertising, product placement, and cultural ubiquity. New brands that try to launch as symbol-only typically fail to break through the recognition barrier and end up adding their wordmark back into the primary lockup. + +The exception is brands launching with massive marketing budgets that can purchase recognition directly. Some legacy financial and luxury brands (Mercedes-Benz, Mastercard) achieved symbol-only status by spending decades and billions on awareness. New brands attempting the same path almost always fail. + +### When this fits + +- The brand has decades of recognition and the symbol carries the brand alone +- The brand is in a category where symbols travel further than wordmarks (sports apparel, automotive, luxury goods) +- The symbol is distinctive enough that no other brand uses anything similar +- The brand has secondary contexts (signage, packaging, apparel) where wordmark space is not available +- The brand can afford the multi-decade investment in recognition + +### When this fails + +- The brand is new and lacks the recognition required for symbol-only to read as the brand +- The symbol is generic (a hexagon, a triangle, a circle) and could belong to thousands of other brands +- The brand has not invested in recognition through advertising or distribution +- Symbol-only is chosen as the primary because the wordmark is too long, when the real solution is a different architecture entirely +- The category demands wordmark presence (B2B SaaS, professional services, anything where the brand name needs to register before the symbol does) + +### Combining in a hierarchy + +Symbol-only is rarely the only asset. Even Apple ships a wordmark for legal contexts, contractual documents, marketing surfaces where the wordmark adds clarity. The hierarchy for symbol-only-primary brands is: symbol primary, wordmark for legal and contextual surfaces, lockup for select marketing applications. The symbol carries; the wordmark plays a supporting role. + +--- + +## Letterform-as-symbol + +A single letter from the brand name (often the first) is treated as the symbol. The letter is custom-drawn or aggressively styled to read as both letter and visual element. Beats by Dre's "b", McDonald's "M", Underscore's "_", a custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. + +The cleanest path to symbol when the full wordmark is too long for a tight lockup, when the name has a letter that lends itself to visual play, or when the brand wants the symbol and the wordmark to share construction. Beats's "b" inside a circle is the exact "b" weight and proportion as the rest of the wordmark; the symbol IS the same lettering language. McDonald's "M" reads as the golden arches and as the letter; both readings are simultaneous and reinforce each other. + +The discipline is the silhouette test on the underlying letter. If the letterform is over-styled and the silhouette no longer reads as the letter, the symbol fails one direction of its job. If the letterform is under-styled and reads as just a typed letter, the symbol fails the other direction. The custom letterform must do double duty. + +### When this fits + +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to read as one identity +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands +- The brand needs a small-size and embroidery-friendly fallback that derives from the wordmark + +### When this fails + +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it +- The brand uses the letterform-as-symbol at sizes where it is illegible + +### Combining in a hierarchy + +A common setup: lockup primary, letterform-as-symbol for square contexts and embroidery, full wordmark for legal and large-format contexts. Beats does this. The letterform-as-symbol is the favicon, the app icon, the embroidered patch on Beats apparel. The wordmark in lockup is the marketing primary. The hierarchy makes one identity across asset grades. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol is the initials, often with ligature treatment, tight kerning, geometric framing (ring, shield, diamond), or stacked composition. CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent). + +Common in legal, financial, hospitality, fashion, and heritage brands where institutional gravity is the positioning. A monogram says "we have a long name" and "we own the initials of that name". It also says "we are old enough that abbreviating is acceptable", which is a positioning move. + +Monograms come in three flavors. Pure ligature (the letters share strokes; CN and GG are ligatures). Stacked or geometrically framed (the letters sit inside a ring, shield, or diamond; HBO is framed; YSL is geometrically composed). Tight kerning with no framing (the letters are simply set together with optical adjustments; VW reads as initials without frame). + +### When this fits + +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit (M and N, C and N, V and W work; I and J or O and U are harder) +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +### When this fails + +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials +- The brand uses the monogram alone in contexts where the audience does not yet recognize the initials + +### Combining in a hierarchy + +The classic hierarchy is: full wordmark for marketing primary, monogram for square contexts (social profile, embroidery, foil stamp, signet, wax seal), lockup with both wordmark and monogram for transitional surfaces (letterhead, business card, signage). Chanel, Gucci, and most luxury houses ship exactly this. The monogram is the most-applied mark on physical goods (apparel, hardware, bottles), the wordmark is the most-applied mark on digital and marketing surfaces, and the lockup is reserved for specific institutional surfaces. + +--- + +## Putting it together: the three-asset working pattern + +For most brands, the working asset hierarchy is three marks: + +1. Primary lockup for marketing, web, packaging, signage. Wordmark plus symbol locked into a fixed relationship. +2. Stacked or square alternate for social profiles, app icons, square contexts. Same elements as the lockup but recomposed for square. +3. Small-grade fallback for favicon, embroidery, foil stamps. A single element (symbol-only, letterform-as-symbol, or monogram) that derives from the lockup. + +All three must share visual DNA. Same letterform language, same construction grid, same optical weight class. A brand whose three marks read as three different brands has a system problem, not a logo problem. The discipline is to design the small-grade fallback FIRST, before the lockup, so the constraints of the smallest application drive the construction of the largest. diff --git a/skills/logo-design/references/category-conventions.md b/skills/logo-design/references/category-conventions.md new file mode 100644 index 0000000..6533083 --- /dev/null +++ b/skills/logo-design/references/category-conventions.md @@ -0,0 +1,489 @@ +# Category conventions + +Every category has a default visual register the audience expects. Working inside the default signals competence; the brand reads as belonging. Working outside the default signals positioning; the brand reads as making a deliberate move. Both are legitimate. The trap is doing either by accident. + +This file surveys ten major brand categories at parity. For each: the defaults that work, the conventions worth honoring, the conventions worth breaking for positioning, the cliches to avoid, the application contexts unique to the category, and reference brands as visual shorthand. + +--- + +## 1. Legal firms + +The category is dominated by heritage positioning. White-shoe firms, century-old partnerships, names tied to founding partners' surnames. The audience reading the logo is general counsel, founders raising or selling, CFOs in industries where the wrong attorney is materially expensive. The buyer brings high stakes and trusts visual signals of institutional gravity. + +### Defaults that work + +- Old-style or transitional serif typography for the wordmark. Garamond, Caslon, Sabon, Source Serif. The serif reads as institutional and serious. +- Lockup with monogram OR wordmark with monogram fallback. The full firm name is often long (multiple partner surnames) so the monogram does heavy lifting in constrained contexts. +- Restrained color palette. Navy, deep charcoal, oxblood, deep forest green. No primary red, no bright blue, no anything that reads as casual. +- Single-color reproduction built into the system from day one (court filings reproduce in black on white, foil stamps on letterhead are common, embossed signage on lobby walls). + +### Conventions worth honoring + +- Heritage signaling through old-style serif type and monogram architecture +- Single-color reproducibility for court filings and formal documents +- Geometric framing (ring, shield) only in restrained executions; heavy ornament reads as fake heritage + +### Conventions worth breaking for positioning + +- Geometric sans for the wordmark signals "modern, accessible" (boutique firms, tech-adjacent practices, plaintiff-side firms) +- Lighter color palette signals approachability (firms competing for client comfort, not gravity) +- Asymmetric lockup signals contemporary execution (firms positioning against the traditional white-shoe model) + +### Common cliches to avoid + +- The Roman-pillar-as-justice. Pillars are exhausted. +- The scales-of-justice icon. Done thousands of times; signals nothing. +- The gavel. Cliche. +- The lady-Justice silhouette. Same. + +### Application contexts unique to the category + +- Court filings (single-color black on white at small scale) +- Embossed letterhead and business cards (the foil-stamp test is real) +- Lobby and conference room signage (engraved brass, etched glass) +- Email signatures with the firm wordmark and individual attorney name +- Billable-hours invoices (the wordmark must look reproducible at low quality) + +### Reference brands + +- Latham & Watkins (LW monogram in serif, conservative palette) +- Wachtell, Lipton, Rosen & Katz (full firm name as wordmark, no symbol; positioning as "we don't need a symbol") +- Skadden, Arps, Slate, Meagher & Flom (Skadden monogram, restrained sans) + +--- + +## 2. Consumer goods / CPG + +The category is dominated by retail competition. The mark must register at shelf distance (10 to 15 feet), at thumbnail scale (online product imagery), and at rapid scan speed (the shopper has 2 seconds per shelf section). Distinctiveness is survival. + +### Defaults that work + +- Custom display typography for the wordmark. The brand owns its letterforms because the wordmark is on every package. +- Lockup with literal symbol OR strong wordmark only. The symbol depicts what the brand is about; the wordmark carries the brand name. +- Bold color palettes. Bright colors register at distance. Restraint is the exception. +- Pattern systems that extend the brand identity onto packaging surfaces. + +### Conventions worth honoring + +- Distinctiveness at small scale (online product thumbnails, 80x80 pixels) +- Single-color or simplified versions for embossed packaging, foil stamps, hot-metal printing +- Color recognition: the brand color is the first signal on shelf, before the wordmark even reads + +### Conventions worth breaking for positioning + +- Restrained typography signals premium positioning (Method, Brandless, Aesop) +- Black-and-white-only signals minimalist or anti-CPG positioning +- Hand-drawn or organic letterforms signal craft or small-batch positioning + +### Common cliches to avoid + +- The swoosh-as-growth. Borrowed from Nike. +- The leaf-as-natural. Done thousands of times in wellness and organic. +- The dot-or-circle-as-modernity. The 2010s startup tier. +- The hand-drawn brushstroke under the wordmark. Saturated. + +### Application contexts unique to the category + +- Retail packaging at shelf scale +- Online product thumbnails (80x80 to 200x200 pixels) +- Print catalog imagery (offset print, sometimes single-color) +- In-store signage and end-cap displays +- Branded merchandise (hats, totes, t-shirts the brand sells) + +### Reference brands + +- Method (custom geometric sans, restrained palette, premium positioning in a category dominated by aggressive color) +- Hu Chocolate (hand-drawn wordmark, organic typography, craft positioning) +- Brandless (anti-brand brand: minimalist sans, monochrome, the wordmark IS the absence of conventional branding) + +--- + +## 3. B2B SaaS + +The category is dominated by visual interchangeability. Most B2B SaaS brands use neo-grotesque sans typography, geometric reduction symbols, and a primary color in the blue-to-purple range. The mark blurs into the category default unless the brand makes deliberate distinguishing choices. + +### Defaults that work + +- Neo-grotesque sans typography (Inter, Söhne, GT America, custom). The default register reads as competent and contemporary. +- Lockup with abstract or geometric-reduction symbol. The symbol carries small-size and app-icon contexts. +- Single-accent color palette. A primary brand color plus monochrome, no busy palette. +- Custom letterform in the wordmark to escape the interchangeable default. + +### Conventions worth honoring + +- Screen rendering optimization (the wordmark must read at every screen size and DPI) +- App icon construction (the symbol must work inside rounded-square and circle masks) +- Monochrome reproducibility (single-color and reverse-on-dark should both work) + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in SaaS; positions against the modern startup tier) +- Bright primary color (red, orange, yellow) signals energy in a category that defaults to blue and gray +- Custom display typography signals long-term brand investment in a category where most brands look interchangeable + +### Common cliches to avoid + +- The geometric hexagon. The most overused symbol in tech. +- The three-bars stacked horizontally. The 2018-2020 SaaS tier. +- The triangle pointing right. Done. +- The bisected circle. Same. +- The single-letter-inside-circle without distinctive letterform construction. + +### Application contexts unique to the category + +- App icons (iOS, Android, web app, browser extension) +- Marketing site at desktop scale +- Documentation site at small scale (favicon, header, footer) +- In-product brand display (loading screens, empty states, account avatars) +- Slack and email integration logos (small thumbnails) + +### Reference brands + +- Stripe (custom Sohne wordmark, abstract gesture symbol, restrained palette) +- Linear (Inter wordmark, geometric reduction symbol, signature single-color execution) +- Vercel (custom Geist wordmark, geometric reduction triangle, bold black-and-white) +- Notion (custom letterform with notebook reference) + +--- + +## 4. Hospitality (hotels, restaurants, resorts) + +The category sits between heritage luxury and contemporary craft. The audience experiences the brand across many surfaces simultaneously: building exteriors, interior signage, room key cards, menus, uniforms, towels, sheets, packaging. Multi-surface coherence is the discipline. + +### Defaults that work + +- Custom display typography OR transitional serif for the wordmark. The brand often becomes the visual identity of the property. +- Lockup with monogram fallback. The monogram appears on towels, sheets, room keys, embroidered uniforms. +- Restrained palette with a single signature color. The palette extends to interior design, materials, lighting. +- Embroidery-grade variant built into the system from day one. + +### Conventions worth honoring + +- Embroidery on uniforms, towels, robes, sheets (the monogram does this work) +- Foil-stamp on stationery, room key cards, room service menus +- Engraved or etched signage on building exteriors and interior wayfinding +- Restraint in palette (heritage hospitality avoids loud color) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "boutique, design-forward" (Ace Hotel, Standard Hotels) +- Bold color signals contemporary or playful positioning +- Asymmetric lockup signals contemporary execution +- Display custom typography signals investment in a unique brand identity + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in heritage hospitality. +- The shield-with-year-founded. Every craft beer label uses this. +- The crossed-keys (Hermes-derived). Done. +- The mountain-or-palm-tree literal symbol for resort properties. Done. + +### Application contexts unique to the category + +- Building exterior signage (channel letters, illuminated) +- Room key cards (foil stamp on plastic or paper) +- Towels, robes, sheets (embroidery) +- Glassware, china, silverware (etched, engraved) +- Stationery (letterhead, envelopes, business cards, foil stamp) +- Uniforms (embroidered name tags and lapel pins) +- Bag tags and luggage labels + +### Reference brands + +- Aman Resorts (restrained typographic identity, Asian-influenced design discipline) +- Soho House (custom display typography, monogram primary, modern member-club positioning) +- Ace Hotel (custom display typography, contemporary boutique positioning, regional variation across properties) + +--- + +## 5. Healthcare + +The category is dominated by trust signaling. The audience may be anxious, stressed, or grieving. The brand must read as competent and calm without reading as cold or clinical. Trust is built through restraint, not through aggressive visual claims. + +### Defaults that work + +- Humanist sans typography for the wordmark. The calligraphic warmth carries trust. +- Lockup with abstract gesture symbol. The symbol suggests care, balance, or healing without depicting it literally. +- Calm color palette. Blue, green, soft warm neutrals dominate. +- Plenty of whitespace in the brand system. Density reads as anxiety. + +### Conventions worth honoring + +- Accessibility floor: WCAG AA contrast ratios on every brand color combination +- Restrained palette: no aggressive red (reads as emergency or alarm) +- Avoid imagery that could be misread (a symbol that suggests a religious cross when the brand is secular, a symbol that suggests a specific medical specialty when the brand is generalist) + +### Conventions worth breaking for positioning + +- Modern geometric sans signals "tech-forward primary care" (One Medical, Forward) +- Warmer color palette (coral, peach, soft yellow) signals "we are not your old doctor's office" +- Custom display typography signals contemporary positioning (rare in legacy healthcare) + +### Common cliches to avoid + +- The medical cross. Trademark-protected by the Red Cross in some uses; otherwise generic. +- The caduceus (snakes around a staff). Misread by audiences as Hermes; not actually the medical symbol. +- The heartbeat-line. Saturated in fitness and healthcare. +- The blue-and-green gradient. The default healthcare palette to a fault. + +### Application contexts unique to the category + +- Wayfinding signage in clinics and hospitals +- Patient-facing materials (intake forms, appointment reminders, billing statements) +- Medical equipment branding (the wordmark on a screen, on a printed report) +- Insurance and billing communications (the wordmark on bills the patient hopes are accurate) +- Clinic uniforms and badges + +### Reference brands + +- One Medical (humanist sans wordmark, simplified circle symbol, restrained palette, primary care positioning) +- Forward (custom display typography, geometric reduction symbol, tech-forward primary care) +- Hims (custom geometric sans, single-color execution, modern men's health positioning) + +--- + +## 6. Financial services + +The category splits between heritage and fintech-modern. Heritage banks (Goldman Sachs, JPMorgan, Morgan Stanley) lean into old-style serif and institutional gravity. Fintech challengers (Ramp, Mercury, Stripe) lean into neo-grotesque sans and modern restraint. The split is itself a positioning decision. + +### Defaults that work + +- Old-style serif OR neo-grotesque sans (the heritage-vs-fintech axis) +- Lockup with monogram fallback (heritage) OR wordmark with abstract symbol (fintech) +- Restrained palette. Navy, gold, deep green for heritage. Black, white, single-accent for fintech. +- Single-color reproducibility built into the system (foil stamps, embossed checks, single-color regulatory documents) + +### Conventions worth honoring + +- Single-color reproducibility (foil stamps, regulatory filings, embossed checks) +- Trust signals through restraint and material quality (heavy paper, foil stamps) +- Color choice signals heritage (navy, gold, deep green) vs fintech (black, white, electric accent) + +### Conventions worth breaking for positioning + +- Modern geometric sans in heritage financial services signals "boutique, contemporary" (rare and high-stakes) +- Bright color in heritage financial services signals "we are not your father's bank" (high-risk positioning) +- Old-style serif in fintech signals "we take regulatory compliance seriously" (positions against fast-and-loose fintech) + +### Common cliches to avoid + +- The eagle-as-strength. Heritage cliche. +- The shield-as-security. Cliche across heritage and fintech. +- The bull-as-bullish. Wall Street cliche. +- The geometric chevron pointing up. Fintech cliche. +- The blue-and-gold gradient. Heritage default that reads as visually unconsidered. + +### Application contexts unique to the category + +- Embossed credit and debit cards (the mark is impressed, not printed) +- Regulatory filings and disclosures (single-color reproduction) +- Bank checks (single-color print, MICR-encoded routing numbers) +- Branch signage (channel letters, illuminated) +- ATM screens and branded interfaces + +### Reference brands + +- Goldman Sachs (old-style serif wordmark, restrained palette, heritage positioning) +- Ramp (custom Söhne wordmark, abstract symbol, modern restrained palette) +- Mercury (custom geometric sans, abstract gesture symbol, fintech positioning with restraint) + +--- + +## 7. Editorial / publishing + +The category is dominated by typography. The masthead IS the logo. Most editorial brands have no separate symbol; the wordmark in a specific custom serif IS the entire identity. The discipline is letterform and proportional refinement. + +### Defaults that work + +- Custom display typography OR old-style serif OR transitional serif for the wordmark +- Wordmark only OR wordmark with monogram fallback +- Black-on-white as the default reproduction (newsstand, print, digital header) +- Restrained palette (typically a single accent color, often the brand's signature) + +### Conventions worth honoring + +- Single-color reproducibility (every newspaper masthead must work in black on white at masthead scale) +- Custom letterform investment (the masthead is the brand's most-rendered asset) +- Typographic heritage (the masthead often references the publication's founding-era typography) + +### Conventions worth breaking for positioning + +- Geometric sans signals contemporary editorial (Vox, BuzzFeed, Vice attempted versions of this) +- Bold color signals contemporary positioning (rare in legacy editorial) +- Modern asymmetric layouts signal contemporary craft + +### Common cliches to avoid + +- The blackletter masthead. Saturated for newspapers; reads as German tabloid. +- The decorative initial cap drop. Editorial cliche. +- The pen-nib symbol for writing or journalism brands. Cliche. +- The book-and-ribbon. Cliche. + +### Application contexts unique to the category + +- Newsstand at street scale (the masthead must read at 50 to 100 feet) +- Print body and headline typography (the wordmark sits at the top of every printed page) +- Digital masthead at desktop and mobile scale +- Subscription and renewal direct mail (single-color print) +- Cover photography (the masthead overlays photographic backgrounds) + +### Reference brands + +- The Atlantic (custom transitional serif, restrained palette, editorial heritage) +- The New Yorker (custom Caslon-derived masthead, the mark is unmistakable) +- Cereal (custom display sans, considered minimalism, contemporary editorial) + +--- + +## 8. Tech / AI + +The category is dominated by abstract gesture and geometric reduction. Most AI and tech brands lean into one of two modes: either neo-grotesque sans with abstract gesture symbol (Anthropic's flower, OpenAI's geometric mark) or aggressive geometric reduction (every blockchain logo, every web3 brand). Visual fatigue in the category is real. + +### Defaults that work + +- Neo-grotesque sans OR custom geometric sans for the wordmark +- Lockup with abstract gesture or geometric reduction symbol +- Single-accent color palette. Often the brand's "signature color" plus monochrome. +- Construction grid discipline in the symbol + +### Conventions worth honoring + +- Screen rendering optimization (the brand lives on screens at every size) +- App icon construction (rounded-square and circle masks, every iOS/Android size) +- Monochrome and reverse-on-dark variants + +### Conventions worth breaking for positioning + +- Old-style serif signals "we take ourselves seriously" (rare in tech, signals against the dominant aesthetic) +- Hand-drawn or organic letterforms signal craft or human-centered positioning +- Bright primary color signals energy in a sea of muted palettes + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain. The most overused symbol in crypto. +- The neural-network-circles symbol for AI brands. Done thousands of times. +- The brain-with-circuit-traces. Cliche. +- The triangle-with-an-eye. Cliche. +- The default purple gradient. The 2018-2022 tech tier. + +### Application contexts unique to the category + +- Developer documentation sites (the wordmark sits in dense technical contexts) +- API and CLI integrations (the brand appears in terminal output, error messages, log lines) +- Loading screens and empty states in product +- Open-source repository profile pictures +- Conference talk slide branding + +### Reference brands + +- Anthropic (custom display typography, abstract gesture symbol, restrained palette) +- OpenAI (custom geometric mark, simple wordmark, monochrome execution) +- Hugging Face (custom emoji-as-symbol, distinctive in a category that doesn't usually allow it) + +--- + +## 9. Outdoor / lifestyle / apparel + +The category sits at the intersection of illustration, heritage, and embroidery. Many outdoor brands use illustration-driven marks with hand-drawn or vintage-inspired execution. The application context is frequently embroidered (apparel, hats, packs) so the mark must survive thread on fabric. + +### Defaults that work + +- Custom display typography OR slab serif for the wordmark +- Lockup with literal symbol depicting the brand's outdoor world (mountain, river, tree, animal silhouette) +- Heritage color palette. Earth tones, warm reds, deep greens, cream-and-coffee +- Embroidery-grade variant built into the primary system + +### Conventions worth honoring + +- Embroidery on apparel, hats, and packs (the mark must survive 4-6 colors on thread) +- Patch-friendly construction for hats and uniforms +- Hand-drawn or vintage-inspired execution that signals craft and authenticity +- Color palette referencing the brand's outdoor environment + +### Conventions worth breaking for positioning + +- Modern geometric sans signals contemporary outdoor (Topo Designs, Outdoor Voices) +- Bright color signals younger or athletic positioning +- Wordmark-only signals premium or design-led positioning (rare) + +### Common cliches to avoid + +- The bear silhouette. Saturated for outdoor and lifestyle. +- The mountain peak with a sun rising. Done. +- The compass rose. Saturated for travel and outdoor. +- The Pacific-Northwest cabin aesthetic. Saturated since 2015. +- The tent silhouette. Cliche. + +### Application contexts unique to the category + +- Apparel embroidery (hats, polos, jackets, packs) +- Patch embroidery (jackets, packs, vests) +- Heat-transfer printing on technical fabrics +- Hangtags and care labels on apparel +- Retail signage at small specialty stores + +### Reference brands + +- Patagonia (custom display typography, Fitz Roy mountain silhouette, signature gradient palette) +- REI (custom slab serif wordmark, the wedge symbol, outdoor heritage positioning) +- Filson (custom slab serif, monogram and shield treatments, heritage workwear positioning) +- Topo Designs (custom display typography, contemporary outdoor positioning, designed in Colorado) + +--- + +## 10. Fashion / luxury + +The category is dominated by monogram and ligature conventions. Most heritage luxury brands use monograms (Chanel CN, Gucci GG, Yves Saint Laurent YSL, Louis Vuitton LV). Modern accessible-luxury brands lean toward custom display typography (The Row, Aimé Leon Dore, Jacquemus). The split is the positioning question. + +### Defaults that work + +- Old-style serif OR custom display typography OR ligature monogram for the primary mark +- Lockup with monogram fallback OR wordmark with monogram on goods +- Restrained palette. Black, white, gold, and the brand's signature accent +- Embroidery-grade variant for apparel and accessories + +### Conventions worth honoring + +- Embroidery on apparel and accessories (the monogram does this work) +- Foil stamp and emboss on packaging (the wordmark or monogram impressed in metallic foil) +- Material quality (heavy paper, leather, metallic foil) +- Restraint in palette and ornamentation + +### Conventions worth breaking for positioning + +- Modern geometric sans signals accessible-luxury (The Row, Aimé Leon Dore lean restrained-modern) +- Bright color signals contemporary or playful luxury (rare and risky) +- Hand-drawn or expressive letterforms signal craft positioning + +### Common cliches to avoid + +- The crown-as-luxury. Saturated in fashion and hospitality. +- The decorative monogram with filigree. Reads as Renaissance Faire, not as Hermès. +- The shield-with-year-founded. Done. +- The gold-foil-with-Old-English-typeface. Cliche fake-heritage. + +### Application contexts unique to the category + +- Apparel embroidery (logos, monograms, signatures stitched into garments) +- Hardware embossing (buttons, rivets, zipper pulls, leather goods) +- Foil stamp on packaging (boxes, dust bags, ribbon) +- Engraved or etched hardware (jewelry, watches) +- Vellum and tissue paper printing (gift wrap, bag liners) +- Window displays at flagship stores + +### Reference brands + +- Chanel (CN monogram, no symbol beyond initials, the most institutionally consistent fashion brand) +- Gucci (GG monogram, custom display typography for the wordmark) +- The Row (custom display typography, restrained accessible-luxury positioning) +- Aimé Leon Dore (custom display typography, contemporary heritage positioning, restrained monogram on apparel) + +--- + +## How to use this file + +When designing for a category not your own, start with the defaults. They exist because they work. The audience reads them as competence. + +When designing for a category you want to position against, identify which convention you are breaking and why. The break should be deliberate and supported by the rest of the brand system. A boutique law firm in geometric sans signals modern positioning IF the rest of the brand (color, photography, voice, materials) also signals modern positioning. Breaking type without breaking the rest of the system reads as random. + +When designing without category context, the defaults are still the right starting point. Most brands sit inside a category. Most brands benefit from being recognizable inside that category before they push for distinctiveness. Distinctiveness without belonging reads as outsider; belonging without distinctiveness reads as forgettable. The discipline is to start with the category default and earn each departure. diff --git a/skills/logo-design/references/client-package.md b/skills/logo-design/references/client-package.md new file mode 100644 index 0000000..e41adf0 --- /dev/null +++ b/skills/logo-design/references/client-package.md @@ -0,0 +1,187 @@ +# Logo client package + +The package format clients expect when handing logo work back. The discipline here is doing the boring work upfront so the client never has to ask for "the SVG version" or "a small one for favicons" or "white-on-dark for the slide deck." + +## When this applies + +- Final delivery of logo work to a client (internal or external) +- Mid-project handoff where another team needs to start building against the mark +- Brand-refresh deliverables where existing applications need to update + +## When this does NOT apply + +- Concept presentation. Concept stage is for direction-setting, not delivery. Concept decks include 2-3 mark variations with rationale, not a full package. +- Style-guide level brand systems. The client package is the deliverable for the mark itself; a brand-style-guide is a separate concern covering color, type, voice, photography, motion. See the brand-style-guide skill. +- Individual application-specific exports. If the client needs a 2400x1260 LinkedIn cover image with the mark composed against a photo, that is a one-off design request, not a package update. + +## The package format + +### File formats (the matrix) + +Every variant ships in formats that cover the contexts the client will actually use: + +\| Format \| Use case \| Notes \| +\|---\|---\|---\| +\| SVG \| Web, scalable applications, modern email clients \| Primary delivery format. Vector. \| +\| AI or EPS \| Editable source for designers \| Source file. Layered if the mark has multiple components. \| +\| PDF \| Print, vector applications, archival \| Vector. Embedded fonts or outlined. \| +\| PNG (transparent) \| Web, slide decks, raster contexts where background is unknown \| Multiple sizes: 64, 128, 256, 512, 1024, 2048. \| +\| JPG \| Email signatures, contexts where transparency is not supported \| Solid background; usually white. Single size, 1024px wide. \| +\| ICO \| Favicon \| Multi-resolution: 16x16, 32x32, 48x48 packed into one file. \| +\| Apple touch icon (PNG) \| iOS home-screen bookmarks \| Single size, 180x180. \| + +The asymmetry matters. Vector formats (SVG, AI, PDF) are the source of truth; raster formats (PNG, JPG, ICO) are derived from the vector source at delivery time. Never deliver only raster; clients eventually need to scale up and they cannot. + +### Variant matrix + +The client gets every meaningful combination of the variant axes: + +Color treatment: +- Primary (full color, the canonical mark) +- Reverse (white on dark, for dark backgrounds) +- Mono black (single black, for grayscale or low-fidelity contexts) +- Mono white (single white, for full-bleed dark photography) +- Mono brand (single color in the brand color, for one-color print) + +Composition (where the mark has multiple lockups): +- Primary lockup (the canonical composition, usually horizontal) +- Stacked (vertical, for narrow contexts like favicons or app tiles) +- Symbol-only (when the wordmark is unavailable or unnecessary, like profile avatars) +- With tagline (where a tagline is part of the mark system) +- Without tagline + +The client gets every relevant combination. A simple wordmark might have 5 variants total (primary across 5 color treatments). A complex lockup with tagline plus symbol variants might have 30+. Either way: the matrix is exhaustive within the system, not arbitrary. + +### Folder structure + +Organized so the client can find what they need without thinking: + +``` +{brand-name}-logo-package/ +├── 01-primary/ +│ ├── primary-color.svg +│ ├── primary-color.ai +│ ├── primary-color.pdf +│ ├── primary-color-2048.png +│ ├── primary-color-1024.png +│ ├── primary-color-512.png +│ ├── primary-color-256.png +│ ├── primary-color-128.png +│ ├── primary-color-64.png +│ └── primary-color.jpg +├── 02-reverse/ +│ └── (same format set, white-on-dark) +├── 03-mono/ +│ ├── mono-black/ (full set) +│ ├── mono-white/ (full set) +│ └── mono-brand/ (full set) +├── 04-stacked/ +│ └── (same format set, vertical lockup) +├── 05-symbol/ +│ └── (symbol-only variants if applicable) +├── 06-favicon/ +│ ├── favicon.ico +│ ├── apple-touch-icon.png +│ ├── favicon-16.png +│ ├── favicon-32.png +│ └── favicon-48.png +├── 07-applications/ +│ ├── business-card-mockup.pdf +│ ├── letterhead-mockup.pdf +│ ├── email-signature.png +│ └── social-avatar.png +├── 08-documentation/ +│ ├── usage-guide.pdf +│ ├── brand-colors.pdf +│ └── license.pdf +└── README.md +``` + +Numbered prefixes ensure the client opens folders in the order that matches how they will use them. Documentation last because nobody reads it first; applications second-to-last because they are reference, not deliverable. + +### File naming convention + +Inside each folder, files follow this pattern: + +``` +{variant}-{color}-{size or context}.{ext} +``` + +Examples: +- `primary-color.svg` +- `primary-color-2048.png` +- `reverse-white.svg` +- `mono-black-1024.png` +- `stacked-color.pdf` +- `symbol-color.svg` + +Consistent naming means the client can guess a filename before looking. + +## The documentation layer + +Inside `08-documentation/`: + +### usage-guide.pdf + +Covers: +- Clear space: minimum padding around the mark, expressed as a multiple of a recurring element (often the x-height of the wordmark or the diameter of the symbol) +- Minimum size: smallest legible application, with explicit size for digital (px) and print (mm or in) +- Do's: contexts where the mark works +- Don'ts: stretching, recoloring outside the variant set, rotating, applying effects (drop shadow, gradient, embossed), placing on busy photography without sufficient contrast, replacing the typography in a wordmark +- Co-branding rules: how the mark composes with partner marks, including spacing and order + +A usage guide that just lists the variants is documentation theater. The do's-and-don'ts section is what protects the mark in the wild. + +### brand-colors.pdf + +Color values for every meaningful representation: +- Hex (web) +- RGB (digital) +- CMYK (print) +- Pantone (spot color print) +- HSL (where the brand has a programmatic color system) + +If the mark uses gradients, document the gradient stops and direction explicitly. Gradients vary in unpredictable ways across rendering engines; precise documentation is the only protection. + +### license.pdf + +Covers: +- Who owns the mark (usually the client) +- Who the designer is (for attribution, if required) +- Usage terms (typically: client has full and exclusive use; designer retains the right to display in portfolios) +- Modification rights (typically: client cannot modify without designer consent during a defined warranty period; after that, all rights to modify pass to the client) +- Successor terms (what happens if the client sells the brand or merges with another company) + +License documentation is the part most independent designers skip and most agencies overformat. The middle path is a 1-page document that names the parties, defines usage, and is signed. + +## Delivery mechanisms + +Three patterns, in increasing formality: + +ZIP archive over email. Smallest projects. The client gets a single `.zip`, downloads, expands, drops into their workspace. Works for packages under ~50 MB. Watch out for email size limits. + +Cloud storage link. Most common pattern. Drive, Dropbox, Box, OneDrive. Client gets a link, downloads at leisure, can re-share within their organization. Set link to view-only with download enabled. Set an expiration date if warranty terms are time-bound. + +Brand portal. Largest projects. Paid tools like Frontify, Brandfolder, Brandkit. The portal becomes the canonical source of truth; the client gets logins for stakeholders. Worth the cost when there are 10+ internal stakeholders downloading assets ad hoc, or when the brand system has dozens of marks (parent plus sub-brands). + +Match the mechanism to the client's actual workflow, not their stated preference. Clients will say they want a brand portal, then download the ZIP and never log in to the portal again. + +## Failure patterns + +Delivering only raster. PNG-only or JPG-only packages mean the client cannot scale up cleanly. Always include vector. If the work was done in raster (rare for logo work, but it happens), trace to vector before delivery. + +Delivering only the primary variant. A primary-mark-only package fails the moment the client needs to put the mark on a dark background or print it in one color. The variant matrix is the deliverable, not an optional extra. + +Delivering source files without a license document. Clients who paid for the work expect to own it. Source files (AI/EPS) without an explicit license create ambiguity that surfaces during acquisitions or partnerships. Always include the license PDF. + +Variant naming drift across the package. `Primary_Logo_Color.svg` in one folder and `primary-color.svg` in another means the client's tooling (CMS, design system) will not recognize the assets consistently. Pick a convention; apply it everywhere. + +Skipping the favicon. Almost every client will host a website. The website needs a favicon. Adding the favicon variant adds one folder; omitting it means the client comes back asking for it. + +Embedding fonts in the SVG without confirming licensing. SVG with embedded font glyphs is fine when the font is open-source. When the font is licensed (e.g., a Monotype or Adobe Fonts file), embedding the glyphs may violate the license. Outline the font in the SVG before delivery; the visual remains identical, and the licensing risk disappears. + +## What "done" looks like + +The client opens the ZIP (or the cloud link), sees a numbered folder structure, opens `01-primary/primary-color.svg`, and ships the mark to production within 5 minutes. + +If the client emails back asking "do you have a white version?" or "is there an SVG?" or "can you send the favicon?", the package was incomplete. diff --git a/skills/logo-design/references/example-variant-spec.md b/skills/logo-design/references/example-variant-spec.md new file mode 100644 index 0000000..111b6b2 --- /dev/null +++ b/skills/logo-design/references/example-variant-spec.md @@ -0,0 +1,100 @@ +# Example variant spec + +A fully populated single-variant spec for a fictitious brand, Atlas Coffee. Atlas is a hypothetical specialty coffee company sourcing single-origin beans from Latin American producers, roasting in small batches, retailing through a single flagship cafe and an online subscription. The brand brief calls for considered craft positioning, outdoor adjacency without literal outdoor imagery, warmth without rusticity. + +This file shows what one variant looks like when documented for client review. A complete deliverable contains 6 to 12 such variants. The agent uses this format as the per-variant template; the client uses it to evaluate, compare, and select. + +--- + +## Variant 07, Mountain peak A lockup, IBM Plex Sans + +### Architecture + +Lockup. The wordmark sits to the right of a custom letterform-as-symbol "A". The "A" reads as both the first letter of "Atlas" and as a stylized mountain peak. The lockup also has a stacked alternate (the "A" centered above the wordmark) for square contexts and a symbol-only fallback (the "A" alone) for favicon, embroidery, and stamping. + +### Typography + +- Wordmark typeface. IBM Plex Sans, Medium weight (500), tracking +5 (10 units, on a 1000-unit em). +- Custom letterform. The "A" is a custom drawing, not IBM Plex Sans. The crossbar is replaced with a single horizontal stroke at 38 percent height; the apex rises to a sharp peak; the legs are slightly splayed (8 degrees from vertical) to suggest mountain base width without exaggeration. The custom "A" replaces the typed "A" in the wordmark "Atlas Coffee" so the entire wordmark reads as a unit. +- Wordmark composition. "Atlas Coffee" set as one word, with a small visual gap between "Atlas" and "Coffee" (one half x-height of additional spacing) so the eye reads both words as parallel parts of the same name without forcing a hyphen or stacked composition. +- Optical adjustments. The "t" of "Atlas" is shortened by 4 units to balance against the rising "A" to its left. The "f" of "Coffee" has its terminal pulled inward by 3 units to prevent it from reading as an extra bar. + +### Symbol description + +The custom "A" is the symbol. The construction is built on a 4-unit grid: + +- Apex height: 4 units, sharp peak +- Crossbar: at 1.5 unit height, single horizontal stroke +- Leg width at base: 4 units, splayed 8 degrees from vertical +- Stroke weight: matches the wordmark's stroke weight at the chosen Medium weight (approximately 90 units on a 1000-unit em) + +The peak silhouette is ungenerous on the apex (sharp, not rounded). The crossbar is single-stroke (no double bars). The legs end with a flat foot, not a serif. At every scale, the silhouette reads first as a peak, then as the letter A. The double-reading test passes. + +### Color tokens + +- Primary. Warm charcoal `#2A2521`. The wordmark and the "A" symbol both use this color in standard reproduction. +- Accent. Rust `#B85C38`. The accent appears in marketing surfaces (web header backgrounds, packaging trim) but not in the lockup itself. +- Single-color black. `#000000`. For court filings is irrelevant; for embossed letterhead, foil stamp on paper, single-color print, fax (yes, still). The mark renders as pure black on white. +- Single-color white. `#FFFFFF`. For reverse-on-dark applications (web header in dark mode, signage at night, embossed on dark leather). +- Reverse-on-dark variant. White on a dark background; the symbol's negative space inversion is direction-neutral so the mark reads identically in either direction. + +### Application notes + +The variant excels at: +- Large-format signage. The peak silhouette reads at street scale; the wordmark holds at 8 to 12 feet wide. +- Retail packaging. The lockup at coffee bag scale (4 inches wide) is the natural size; the symbol carries the front, the wordmark anchors the side. +- Mug and ceramic stamping. The lockup with stacked alternate works on cylindrical surfaces. +- Embossed letterhead. The custom "A" embossed at the top, the wordmark printed below in standard color. +- Web header at desktop scale (200 to 400 pixels wide). The lockup reads cleanly at this size. + +The variant needs fallbacks at: +- 16 px favicon. The full lockup fails; the symbol-only "A" carries. +- 1.5 inch embroidery patch. The lockup is too wide; the symbol-only "A" with the wordmark stacked below in a chunky weight (e.g., IBM Plex Sans Bold) is the patch variant. +- App icon at 28 to 60 pixels. The symbol-only "A" inside a colored field (warm charcoal background, white "A") is the app icon variant. +- Square social profile. The stacked alternate (the "A" above the wordmark, centered) is the social profile variant. + +Embroidery adaptation: thread color matched to the warm charcoal primary (Madeira Polyneon `1842` is the closest match for the primary, with `1338` for the rust accent). The embroidery-grade variant of the symbol-only "A" requires a 3 unit minimum stroke weight scaled for 1.5 inch patch reproduction. + +### Signals + +- Considered craft. The wordmark's optical adjustments (shortened "t", pulled-in "f") signal that the brand has thought about every letterform, which signals that the brand thinks about every other detail. +- Outdoor / adventure adjacency without literal outdoor imagery. The mountain peak silhouette references outdoor without depicting a trail, a tree, or a campsite. The audience associates the brand with adventure-adjacent positioning without the brand becoming a Pacific-Northwest cliche. +- Warmth without rusticity. The warm charcoal primary and rust accent read as warm but considered. The palette avoids the heritage-coffee browns and the third-wave-minimalist whites; the in-between space signals contemporary craft. +- Single-origin discipline. The restrained execution (one symbol, one wordmark, one accent color) signals that the brand chooses few things deliberately. The same discipline appears in single-origin coffee sourcing. + +### Rejects + +- Not a typical coffee shop laurel mark. Atlas does not use a laurel wreath, a coffee bean, a coffee cup, or any direct depiction of coffee. The brand is about the experience and origin, not the commodity. +- Not a third-wave-minimalist wordmark with no symbol. Many specialty coffee brands have moved toward wordmark-only with no symbol. Atlas chooses a lockup because the brand wants a symbol-grade asset for embroidery, hardware stamping, and merchandise. +- Not a literal coffee bean. No bean, no berry, no plant in the symbol. The category cliche is rejected. +- Not a Pacific-Northwest-cabin aesthetic. No tree silhouette, no compass rose, no flannel-pattern background. The brand's outdoor adjacency is structural (peak silhouette in the letter), not stylistic. + +### Mockups + +The mockups would be rendered as image assets in a complete deliverable. Described in prose: + +1. Storefront signage at street scale. The lockup as channel letters above the cafe entrance, illuminated, mounted on stained wood paneling. The peak silhouette reads from across the street; the wordmark anchors the brand name as visitors approach. + +2. Retail bag at shelf scale. The 12 oz coffee bag with the lockup printed at 4 inches wide on the front, the wordmark-only with origin information on the side panel. The symbol's peak references the high-altitude growing regions where Atlas sources beans. + +3. Espresso cup at table scale. Double-walled glass cup with the symbol-only "A" stamped in warm charcoal at 1 inch tall on the cup wall. The lockup is on the saucer rim. The customer sees both marks during a 4-minute espresso experience. + +4. Embroidered apron. Black cotton apron with the symbol-only "A" embroidered in rust on the chest pocket. The wordmark is embroidered on the back at the lower hem, in warm charcoal thread, smaller scale. The aprons are durable goods that get washed weekly; the embroidery is built for that. + +5. Social profile picture as stacked mark. The stacked alternate (the "A" above the wordmark, centered, white on warm charcoal background) renders cleanly inside Twitter/Instagram circle masks at 80 to 400 pixel display sizes. + +--- + +## Notes for the agent reading this file + +This single-variant spec is one of typically 6 to 12 in a complete deliverable. The brand owner reads through all variants, marks preferences, asks questions, and selects 1 to 3 finalists for production refinement. + +The discipline in writing the spec: + +- Be specific. "IBM Plex Sans Medium with tracking +5" is specific. "Modern sans-serif" is not. +- Show the system. Each variant is a primary mark plus its fallbacks. Document the fallback hierarchy, not just the primary. +- Justify with signals and rejects. What does the variant communicate? What does it explicitly NOT communicate? The negative space in the rejects sharpens the positive selection. +- Render mockups, in image or in prose. The brand owner needs to see the mark in context to evaluate. A spec without mockups is half-finished. +- Prepare for production. The color tokens, embroidery thread color matches, foil stamp specifications, and minimum sizes are production information. The spec is the bridge from decision to manufacture. + +The output of this skill is decision material. The next step after delivery is selection. The step after that is production refinement on the chosen direction: cleaner construction, refined kerning, color system finalization, application library. diff --git a/skills/logo-design/references/symbol-approaches.md b/skills/logo-design/references/symbol-approaches.md new file mode 100644 index 0000000..a0a1027 --- /dev/null +++ b/skills/logo-design/references/symbol-approaches.md @@ -0,0 +1,266 @@ +# Symbol approaches + +A symbol is the part of the logo that does the most work outside of literacy. It travels where wordmarks cannot fit (favicon, embroidery, app icon, signet) and where wordmarks would not register (signage at distance, motion lockups, square contexts). The symbol approach is the question of WHAT KIND of symbol the brand needs. This file expands the five approaches in [SKILL.md](../SKILL.md) with reference brands, pattern vocabulary, decision criteria, and the cliches each approach has to escape. + +--- + +## Literal + +The symbol depicts the thing the brand name refers to. A mountain peak for an outdoor brand. A rocket for a rocket company. A leaf for a sustainable brand. A bicycle for a bicycle maker. A dog silhouette for a dog food brand. The mark and the meaning are tied together: see the mark, name the thing, recall the brand. + +Literal symbols deliver fast recognition and low ambiguity. The audience does not have to learn what the symbol means. They have to learn that THIS specific peak, rocket, leaf, or bird is THIS specific brand. That is a smaller cognitive load than abstract or geometric-reduction approaches require, which is why literal symbols often work for new brands without large marketing budgets. + +The risk is cliche. Every coffee shop has used a coffee bean. Every sustainable brand has used a leaf. Every fitness brand has used a flexed arm. Generic literal symbols disappear into the category background. The save is distinctive execution: the specific peak, drawn with conviction, in the brand's specific visual register. Patagonia's mountain peaks (the Fitz Roy silhouette) are literal but read as Patagonia because no other outdoor brand uses that specific silhouette in that specific gradient. The execution carries the distinctiveness; the symbol approach is just the starting point. + +### Reference examples + +- Apple's apple (literal but with the bite, which is the distinctive execution) +- Patagonia's Fitz Roy mountain silhouette (literal landscape, specific peak) +- Twitter's bird era (literal bird, specific Larry-the-bird construction) +- Shell's shell (literal scallop shell, custom construction now near-symbol-only) +- Burger King's burger (literal but stylized; the bun, patty, and bun stack render as a unit) + +### Pattern vocabulary + +- Single-object silhouettes (peak, rocket, leaf, bird, fish, tree, building) +- Stylized object reductions (the apple bite, the burger as stacked rectangle, the shell as fan) +- Object-plus-frame compositions (the mountain inside a circle, the tree inside a shield) +- Repeated-object patterns (multiple stylized peaks, paired forms) +- Object combined with letterform (the mountain silhouette that doubles as a letter, see Letterform-derived approach below) + +### Decision criteria + +Literal symbols fit when: +- The brand name is descriptive (Atlas, Forge, Pulse, Anchor) and depicting the thing the name refers to is a natural move +- The category benefits from fast recognition (consumer goods at shelf, retail signage at street scale) +- The brand wants to feel approachable rather than abstract or institutional +- The audience reads symbols faster than they read wordmarks (younger audiences, retail audiences, audiences in low-literacy contexts) + +Literal symbols fail when: +- The brand name is abstract (Stripe, Anthropic, Linear) and forcing a literal symbol creates a metaphor the name does not invite +- The category has been saturated with literal symbols (every wellness brand using a leaf) +- The literal symbol cliches the category (every blockchain logo using a literal chain) +- The brand needs to feel institutional or premium and the literal depiction reads as childlike + +### Common cliches to avoid + +- The leaf-as-natural for any sustainability, wellness, or organic brand. The leaf is exhausted. +- The swoosh-as-growth for any growth-stage brand. Borrowed from Nike but watered down. +- The mountain-as-aspiration for any wellness or productivity brand. The mountain has been climbed. +- The bullseye-as-precision for any analytics or targeting brand. Done. +- The shield-as-security for any security or finance brand. Shields are everywhere. + +The escape is specific execution. A brand that uses a leaf must draw a specific leaf with specific construction (the maple leaf with eight points, drawn at this specific angle, with this specific stroke weight) so the audience reads "this leaf" not "a leaf". + +--- + +## Abstract gesture + +The symbol suggests a quality without literal depiction. A rising arc for "growth". A pair of opposing forms for "balance". A continuous loop for "integrity" or "cycle". A spiral for "expansion". The symbol does not show the thing the brand does; it shows the quality the brand wants to be associated with. + +Abstract gesture marks read slower than literal marks but distinctively higher. The audience cannot name the thing in the symbol because there is no specific thing. Instead, the audience associates the symbol with the brand through repetition: see the symbol, recall the brand. Once associated, abstract gesture marks deliver more brand-specific recognition than literal marks because no other brand can use the same specific gesture. + +The risk is arbitrariness. A swoosh that suggests motion is fine. A swoosh that suggests motion AND innovation AND momentum AND speed is over-loaded. Abstract gesture marks work when the gesture is single, clear, and consistent. They fail when the gesture is multi-layered, when the symbol's construction does not visibly support the claimed gesture, or when the gesture is too abstract to register as anything at all. + +### Reference examples + +- Nike's swoosh (abstract gesture for motion, originally inspired by the wing of Nike, the Greek goddess of victory) +- Mastercard's circles (two overlapping circles, abstract gesture for connection or transaction) +- Audi's four rings (abstract gesture for the four merged companies, rendered geometrically) +- Adidas's three stripes (abstract gesture for ascension, originally a sports performance reference) +- The PBS logo (multiple human silhouettes implying community) + +### Pattern vocabulary + +- Arcs and curves (rising arc, descending arc, S-curve, spiral) +- Repeated forms (multiple stripes, multiple circles, multiple bars) +- Opposing forms (two halves meeting, mirrored shapes, yin-yang variants) +- Implied motion (lines that read as flow, shapes that suggest movement) +- Geometric primitives at scale (a single triangle, a single square, a single hexagon used as the gesture) + +### Decision criteria + +Abstract gesture fits when: +- The brand name is abstract and a literal symbol would feel forced +- The brand wants to claim a quality (motion, balance, growth, connection) without depicting it +- The category rewards distinctiveness over fast recognition (B2B, professional services, established mature brands) +- The brand has the recognition runway to teach the audience that this gesture means this brand + +Abstract gesture fails when: +- The brand is new and does not have the recognition to associate the gesture with the brand +- The gesture is borrowed from a saturated visual vocabulary (every fintech using a rising arc) +- The construction does not support the claim (a swoosh that does not actually swoop) +- The gesture is over-complicated and the audience cannot extract a single quality from it + +### Common cliches to avoid + +- The swoosh-as-growth for SaaS, fintech, or productivity brands. Swooshes are saturated. +- The geometric-hexagon-as-blockchain for crypto, web3, or distributed systems. Hexagons are the new dot-com blue. +- The three-bars-as-tech-startup for SaaS or developer tools. Three bars (or two, or four) are the most common geometric reduction in tech and now read as generic. +- The infinity-as-continuous for any "always-on" brand. Infinity loops are exhausted. +- The ascending-arc-as-progress for any analytics, growth, or financial services brand. Ascending arcs are the visual language of every dashboard ever. + +The escape is specific construction. A brand that uses a swoosh must draw a specific swoosh with specific weight, angle, and proportion so the gesture is identifiable as the brand's, not as a category default. + +--- + +## Geometric reduction + +The symbol is a formal abstraction with no specific referent. A hexagon. A triangle. A stack of horizontal lines. A circle bisected by a vertical. A square with a corner removed. The symbol is constructed from primitive geometric shapes with no narrative meaning attached. + +Geometric reduction reads modern and confident. The discipline of pure geometry signals "we made deliberate constructive choices". The risk is identical-to-everyone: thousands of brands use hexagons, triangles, circles, and squares. The reduction is so far from a specific narrative that the audience cannot distinguish one brand's geometric reduction from another's. + +The save is specific proportions, considered execution, and pairing with a distinctive wordmark. Microsoft's four-square mark is geometric reduction (four colored squares in a 2x2 grid) but works because the specific proportions, colors, and four-pane reference are unmistakably Microsoft. Pinterest's "P" inside a circle is geometric reduction but works because the specific letterform, the specific circle proportions, and the cultural recognition are Pinterest. Geometric reduction without distinctiveness in proportions or pairing reads as interchangeable. + +### Reference examples + +- Microsoft's four-square (four colored squares, the geometric reduction works because of color and arrangement) +- Adidas's three stripes (geometric reduction reading) (also abstract gesture, depending on read; the geometric reduction reading is three parallel diagonals) +- Mastercard's two circles (two overlapping geometric primitives) +- Audi's four rings (four overlapping circles) +- Various B2B SaaS marks (Linear's stacked horizontal bars, Slab's geometric construction) + +### Pattern vocabulary + +- Polygons (hexagon, octagon, triangle, square, diamond) +- Primitive intersections (overlapping circles, intersecting squares) +- Linear primitives (stacked bars, parallel lines, grids) +- Single primitives at scale (a single hexagon, a single triangle, a single square as the entire mark) +- Negative-space primitives (a hexagon defined by what surrounds it, a triangle defined by negative space) + +### Decision criteria + +Geometric reduction fits when: +- The brand has a budget for distinctive construction (the proportions and pairing must be specific enough to escape the category default) +- The brand wants to feel modern, technical, infrastructural +- The category rewards reduction over expression (B2B SaaS, infrastructure, fintech, distributed systems) +- The wordmark is distinctive enough that the geometric symbol can be quietly supportive rather than narratively loaded + +Geometric reduction fails when: +- The brand is new and the construction is generic +- The geometric primitive is the most common one in the category (every blockchain logo using a hexagon) +- The reduction is too far from any narrative the brand wants to tell +- The geometric symbol is not paired with a distinctive wordmark and the system reads as interchangeable + +### Common cliches to avoid + +- The geometric hexagon-as-blockchain for any crypto, web3, or distributed systems brand. Hexagons are the most overused geometric primitive in tech. +- The triangle-as-direction for any productivity, navigation, or strategy brand. Triangles point everywhere now. +- The square-as-foundation for any platform or infrastructure brand. Squares are the new shipping container. +- The stacked-three-bars-as-tech-startup for any SaaS brand. The three bars (or four) are the new dot-com gradient. +- The bisected-circle-as-balance for any wellness, productivity, or balance-claiming brand. Done. + +The escape is proportional specificity. A brand that uses a hexagon must use specific proportions (the regular hexagon vs the wide hexagon vs the tall hexagon, drawn at this specific angle, with this specific stroke or fill discipline) and pair it with a specific wordmark so the symbol is identifiable as the brand's specific reduction, not as a category default. + +--- + +## Letterform-derived + +The symbol is built from the name's letterforms. A custom letter, often the first, that doubles as a visual element. The "M" of McDonald's that reads as the golden arches and as a letter. The "b" of Beats inside a circle that reads as both a "b" and a stylized headphone. A custom "A" rendered as a mountain peak for a hypothetical Atlas Coffee. The Underscore brand's "_" that IS the symbol. + +Letterform-derived symbols deliver strong wordmark-symbol coherence. The wordmark and the symbol share construction language because they ARE the same construction language. The risk is that the letterform reads as just-a-typed-letter and adds nothing. The save is exaggerated character: the letter must read as both the letter AND the visual metaphor simultaneously. + +The discipline is the silhouette test on the underlying letter. An "A as mountain peak" must read as a mountain peak AND as the letter A. If it reads as only one or only the other, the metaphor isn't earning its place. The double-reading is what separates letterform-derived from wordmark-only or from literal symbols. + +### Reference examples + +- McDonald's "M" (the golden arches read as a letter and as the architectural arches of the original restaurant signage) +- Beats by Dre's "b" (the lowercase "b" inside a circle reads as a "b" and as a stylized headphone) +- Underscore's "_" (the underscore character IS the brand mark, read as a punctuation mark and as a structural element) +- The Hoover Dam's "H" (architectural lettering on signage that doubles as monumental ornament) + +### Pattern vocabulary + +- First-letter exaggeration (a custom "A", "B", "M", "S" that reads as both letter and shape) +- Letter-inside-frame (a letter inside a circle, square, or shield that reads as identity) +- Punctuation-as-symbol (an underscore, an asterisk, an ampersand used as the entire mark) +- Letter-as-object (a letter drawn so it doubles as a recognizable object: the M as arches, the A as a peak) +- Stacked or overlapping letterforms (one letter rendered on top of another, ligature-style) + +### Decision criteria + +Letterform-derived fits when: +- The brand name's first letter is visually rich (M, A, B, S, D often work; I, L, J, T are harder) +- The brand wants the symbol and the wordmark to share construction +- The brand has the budget for custom letterform drawing +- The category rewards type-led brands over symbol-led brands + +Letterform-derived fails when: +- The letterform reads as just a typed letter and adds nothing the wordmark wasn't already doing +- The styling overshoots and the letterform no longer reads as the letter +- The chosen letter is structurally weak (a thin stem, a complex curve, a confusing crossbar) +- The custom letterform fights the wordmark instead of complementing it + +### Common cliches to avoid + +- The "letter inside circle" as the universal letterform-derived solution. Beats works because the specific b-shape and the specific circle proportion are distinctive; copies of "letter inside circle" in B2B SaaS read as generic. +- The "letter with an angled corner" as a cheap attempt at distinctiveness. The angled corner does not read as a metaphor; it reads as decoration. +- The "letter with extreme styling" that no longer reads as the letter. If the styling is so heavy that the letterform fails the silhouette test, the metaphor is not earning its place. + +The escape is specific letterform decisions that produce a double reading. The "A as mountain peak" must work both ways. The "M as arches" must work both ways. The double reading is the only thing that justifies the custom drawing investment. + +--- + +## Monogram + +Multiple letters combined as a symbol. The symbol IS the initials, often with ligature treatment, tight kerning, or geometric framing (ring, shield, diamond). CN (Chanel), GG (Gucci), HBO, AC (a hypothetical Atlas Coffee monogram), VW (Volkswagen), YSL (Yves Saint Laurent), AOL. + +Monograms come in three flavors: +- Pure ligature. The letters share strokes; the two letters are drawn as one shape. CN and GG are ligatures. +- Geometrically framed. The letters sit inside a ring, shield, or diamond. HBO, with its rectangular framing. YSL, with its stacked geometric composition. +- Tight kerning, no framing. The letters are simply set together with optical adjustments and read as a unit. VW, with its overlapping V and W. AOL, set tight. + +Monograms signal institutional gravity. The audience reads "we have a long name" and "we own the initials of that name" and "we are old enough that abbreviating is acceptable". For brands wanting heritage, financial competence, hospitality polish, or luxury exclusivity, monograms are often the right architectural choice. + +### Reference examples + +- Chanel's CN (pure ligature, two letters share a counter) +- Gucci's GG (pure ligature, mirrored) +- HBO (geometrically framed inside a rectangle) +- YSL (stacked geometric composition, the three letters set as a tower) +- Volkswagen's VW (tight kerning, overlapping) + +### Pattern vocabulary + +- Ligature pairs (CN, GG, MN, AB, SR with shared counters or strokes) +- Stacked initials (the top letter above the bottom letter, often with a horizontal divider) +- Framed initials (letters inside a ring, shield, diamond, oval) +- Overlapping initials (the V and W of Volkswagen, the H and B of various heritage brands) +- Crowned or filigreed monograms (heritage luxury treatment with ornamental frame elements) + +### Decision criteria + +Monograms fit when: +- The brand has a long name (3+ words, or a single word longer than 10 letters) +- The brand operates in a category where institutional gravity is positioning (legal, financial, hospitality, luxury, academic) +- The initials are visually rich enough to read as a unit +- The brand has applications where the full wordmark cannot fit (embroidered apron, foil-stamped book, signet ring, wax seal) +- The brand wants positioning that signals tradition or heritage + +Monograms fail when: +- The initials clash visually (similar letterforms that fail to read as two distinct shapes) +- The category is allergic to monograms (consumer tech, modern startup tier, anything coded as anti-establishment) +- The monogram is over-framed (heavy ring, heavy shield, every ornamental flourish) until it reads as a fake-heritage logo template +- The monogram is under-styled and reads as just typed initials + +### Common cliches to avoid + +- The "monogram inside a heavy ring" for any brand wanting heritage. Heavy rings around initials read as fake-heritage logo template; rings work when they are restrained, geometrically specific, and earn their place. +- The "heritage shield with a year" for any brand wanting legacy. Founded-in-1923 shields look like every craft beer label. +- The "ornamental monogram with filigree" for any brand attempting traditional luxury. Heavy ornamentation reads as Renaissance Faire, not as Hermès. +- The "monogram with a serif crown" for any boutique heritage attempt. Crowns are exhausted. + +The escape is restrained execution. A monogram that earns its place uses specific letterform construction, specific kerning, and minimal framing. The discipline is what makes Chanel's CN read as Chanel and not as a costume version of Chanel. + +--- + +## How to choose, in summary + +Match the symbol approach to the brand name and the category positioning. + +- Descriptive names invite literal or letterform-derived symbols. Atlas, Forge, Pulse, Anchor, Falcon, Mountain. The name suggests something to depict. +- Abstract names demand abstract or geometric-reduction symbols. Stripe, Anthropic, Linear, Notion. The name does not point at anything specific, so the symbol cannot either. +- Heritage names default to monograms. A founder's surname, a place name, a multi-word firm. The monogram turns the long name into a positioning statement. +- Tech-modern names often default to geometric reduction. Anthropic's hex grid, OpenAI's flower, the universe of B2B SaaS marks built from primitives. The risk is interchangeability; the save is specific proportions and pairing. + +The wrong approach disconnects symbol from name. A literal peak on Stripe would read as a brand mistake. A geometric reduction on Atlas Coffee would feel cold. The approach is downstream of the name, the category, and the positioning intention. diff --git a/skills/logo-design/references/typographic-registers.md b/skills/logo-design/references/typographic-registers.md new file mode 100644 index 0000000..1d22e57 --- /dev/null +++ b/skills/logo-design/references/typographic-registers.md @@ -0,0 +1,263 @@ +# Typographic registers + +Type carries the wordmark. Type carries half the lockup. Type drives more of a logo's read than any other single decision because type is the voice of the brand, frozen. This file expands the seven registers listed in [SKILL.md](../SKILL.md) with named typefaces, category-fit notes, example brands, pairing guidance, and the failure mode each register tends toward. + +--- + +## Geometric sans + +Built from circles and verticals. Letterforms are constructed from primitive geometric shapes (circle, square, triangle) with consistent stroke weight and minimal optical adjustment. Futura, Avenir, Avenir Next, Cabinet Grotesk, ITC Avant Garde, Gotham, Proxima Nova. + +Geometric sans reads modern, considered, often optimistic. The discipline of the geometry signals "we made deliberate choices". Used well, it carries restraint. Used poorly, it reads as cold or interchangeable with every other modern startup. + +Futura was the original (1927, Paul Renner). Avenir is Adrian Frutiger's warmer, more humanist take on the same idea (1988). Avenir Next is the modern release with broader weights and language coverage. Cabinet Grotesk is a recent geometric sans that became a signature of the 2020-2023 startup wave (and now reads dated for that reason). Gotham (Tobias Frere-Jones) is the American-vernacular geometric sans, derived from New York signage; warmer than Futura, more grounded than Avenir. + +### Categories that default to geometric sans + +- Tech startups (the modern default; risk of looking like every other startup) +- Architecture and design firms (where the geometry signals craft) +- Modern hospitality (boutique hotels, restaurant groups built post-2010) +- Wellness and fitness brands at the considered end (not the energetic end) +- Real estate at the modern positioning end (urban, design-forward) + +### Example brands + +- Spotify (custom geometric sans, derived from Circular) +- Airbnb (Cereal, custom geometric sans by Dalton Maag) +- Headspace (Apercu Pro, geometric humanist sans) +- Nike's wordmark (custom Futura-derived) + +### Pairing notes + +Geometric sans pairs well with old-style serifs (the contrast between modern geometry and classical curves reads as intentional) and with slab serifs of similar weight class (both are structurally heavy, the contrast is in the silhouette). Avoid pairing geometric sans with neo-grotesque sans; the two registers are too close in feel and the pairing reads as indecisive. + +### Common pitfalls + +- The trend-chasing risk. Cabinet Grotesk became "2022-2023 startup typeface"; using it now codes the brand as late to a trend. +- The cold-tech risk. Pure geometric sans can feel emotionally distant. Warming requires color, custom letterform, or strong context. +- The interchangeability risk. Geometric sans wordmarks all start to look the same after a category saturates. Distinctiveness comes from custom letterforms or weight/proportion choices, not just typeface selection. + +--- + +## Humanist sans + +Has serif-like calligraphic gestures without serifs. The strokes vary in weight (subtle thick-thin contrast). The letterforms have movement, not just geometry. Gill Sans, Optima, Frutiger, Source Sans Pro, Inter at higher optical sizes, Hermann Zapf's Kabel, Jeremy Tankard's Bliss. + +Humanist sans reads professional but warm. The calligraphic origin gives the type a hand, where geometric sans has none. Excellent neutral choice when the category demands restraint with personality. Old enough to feel timeless; not old enough to feel dated. + +Gill Sans (Eric Gill, 1928) is the original British humanist sans, derived from Edward Johnston's London Underground typeface. Optima (Hermann Zapf, 1958) is the most calligraphic of the humanist sans, with strong thick-thin contrast that reads as sophisticated. Frutiger was designed for Charles de Gaulle airport signage in 1976 and has been the workhorse humanist sans for transit and wayfinding ever since. Source Sans Pro is Adobe's open-source humanist sans (Paul Hunt, 2012); Inter (Rasmus Andersson) crosses humanist and neo-grotesque registers depending on optical size. + +### Categories that default to humanist sans + +- Professional services (consulting, agencies, professional partnerships) +- Education and academic publishing +- Healthcare at the calm end (One Medical, Forward) +- Civic and institutional work (museums, libraries, public services) +- Editorial brands at the modern restrained end + +### Example brands + +- BBC (Gill Sans) +- BMW Group's corporate identity (custom humanist sans, derived from Helvetica with humanist warming) +- One Medical (FF Tisa Sans, humanist with slab adjacency) +- Various university identities (Penn, Stanford, MIT all use humanist or near-humanist marks) + +### Pairing notes + +Humanist sans pairs well with old-style serifs (the calligraphic origins of both registers complement each other) and with transitional serifs (humanist sans for body, transitional serif for display creates a coherent editorial system). Avoid pairing humanist sans with geometric sans; the calligraphic warmth of humanist clashes with the geometric coldness. + +### Common pitfalls + +- The "British civic" risk. Gill Sans is so coded as British civic that using it for a non-British brand can feel anachronistic. +- The dated risk for old humanist sans. Frutiger reads as 1990s transit unless deployed deliberately. Optima reads as 1970s pharmaceutical unless restored to its original sophistication. +- The lukewarm risk. Humanist sans is the safest choice; it can also be the most forgettable. Distinctiveness still requires custom letterform or strong color discipline. + +--- + +## Neo-grotesque sans + +The modern professional default. Helvetica, Inter, Aktiv Grotesk, Söhne, GT America, Univers, Akzidenz-Grotesk. Neo-grotesque is descended from 19th-century grotesque sans typefaces but rationalized for the modern era. Even stroke weight, closed apertures, neutral letterform construction. + +Neo-grotesque reads competent and contemporary. It is the typographic equivalent of a black t-shirt: tasteful, defensible, easy to specify. The trade-off is that everyone else is wearing the same black t-shirt. Without strong color, distinctive symbol, or considered execution, a neo-grotesque wordmark blends into the category default. + +Helvetica (Max Miedinger, 1957) is the prototype. Akzidenz-Grotesk preceded it (1898) but Helvetica became the dominant version. Söhne (Klim Type Foundry, 2019) is the modern revival of the neo-grotesque tradition, with sharper detailing and broader weights. GT America (Grilli Type) crosses American grotesque and Swiss neo-grotesque traditions. Inter (Rasmus Andersson, 2016) is the modern open-source workhorse, designed for screen rendering at every size. + +### Categories that default to neo-grotesque sans + +- B2B SaaS (the unmistakable default; nearly every modern SaaS brand uses Inter, Söhne, or a custom neo-grotesque) +- Modern financial services (Stripe, Mercury, Ramp all use neo-grotesque or near-neo-grotesque) +- Tech at scale (Apple's San Francisco is a neo-grotesque-influenced humanist; Google's Product Sans is neo-grotesque-influenced geometric) +- Modern professional services rejecting the humanist sans default +- Editorial brands at the contemporary end (Bloomberg, modern news brands) + +### Example brands + +- Stripe (custom Sohne Mono and Sohne Schmal) +- Ramp (Söhne) +- Linear (Inter) +- Vercel (Inter, then custom Geist) +- Notion (Söhne) + +### Pairing notes + +Neo-grotesque sans pairs well with serif typefaces of similar weight class (both transitional and old-style serifs work), creating a clean modern-classical contrast for editorial systems. Avoid pairing neo-grotesque with geometric sans or humanist sans; the registers are too close and the pairing reads as indecisive. Custom-drawn neo-grotesque (Söhne, Geist) pairs especially well with stencil display faces, slab serifs, or condensed display sans for brand-system contrast. + +### Common pitfalls + +- The interchangeability risk is highest in this register. Neo-grotesque B2B SaaS wordmarks blur together. The brand that uses neo-grotesque without custom letterforms or strong supporting elements risks becoming visually identical to its category. +- The Helvetica problem. Helvetica is so over-used and so neutral that it now reads as "we did not make a typographic decision". Modern alternatives (Inter, Söhne, GT America) carry similar discipline with more current detailing. +- The screen-versus-print problem. Some neo-grotesque cuts are optimized for screen and look thin at print sizes; others are optimized for print and look chunky at small screen sizes. Pick based on primary application. + +--- + +## Transitional serif + +Modern serifs with high contrast (thick stems, thin transitions, sharp brackets). Source Serif, Charter, Lyon, IBM Plex Serif, Mrs Eaves, Caslon Pro at smaller sizes. Transitional serif sits between old-style serif (low contrast, organic) and modern Didone serif (extreme contrast, geometric). + +Transitional serif reads editorial, considered, intellectual. It carries the long-form heritage of book typography while reading as contemporary. Excellent for legal, publishing, financial, and editorial brands that want serif gravity without the heritage signal of old-style serif. + +Source Serif (Frank Grießhammer, 2014) is Adobe's open-source transitional serif, designed for both print and screen. Charter (Matthew Carter, 1987) is the original screen-optimized transitional serif, designed for low-resolution rendering before high-DPI displays existed; still excellent. Lyon (Kai Bernau, Commercial Type) is the contemporary editorial transitional serif of choice, used by The New York Times Magazine and many editorial brands. IBM Plex Serif (Mike Abbink, IBM, 2017) is IBM's open-source corporate serif, deployed across IBM's global identity. + +### Categories that default to transitional serif + +- Modern legal firms wanting serif gravity without old-fashioned positioning +- Editorial brands and publications (NYT Magazine, The Atlantic in some treatments, Cereal magazine) +- Financial services at the considered end +- Academic publishing (university presses, scholarly journals) +- Modern luxury at the editorial end (not the heritage-luxury end) + +### Example brands + +- The Atlantic (custom transitional serif, derived from Mrs Eaves and Filosofia) +- Vox Media (Lyon) +- Apple's editorial type (custom New York, transitional serif) +- IBM's identity system (Plex Serif) + +### Pairing notes + +Transitional serif pairs well with neo-grotesque sans (the modern-classical contrast is clean and editorial) and with humanist sans (both share calligraphic origins). The classic pairing for editorial is transitional serif for headlines and body, neo-grotesque sans for captions and metadata. Avoid pairing transitional serif with old-style serif; the readers will register the contrast as a mistake rather than an intention unless the deployment is deliberate. + +### Common pitfalls + +- The "magazine logo" trap. Transitional serif is so coded as editorial that using it for non-editorial brands can feel like the brand is trying to wear an editorial costume. +- The screen-rendering problem. Transitional serif's thin strokes can break at small screen sizes if the typeface wasn't optimized for low-DPI rendering. Pick a screen-optimized cut (Charter, Source Serif, Plex Serif) or set the wordmark large enough that the thin strokes survive. +- The "trying too hard" risk. Transitional serif communicates considered restraint; over-styling (italic, weight contrast, custom ligatures) can flip the register to ornate and undermine the restraint signal. + +--- + +## Old-style serif + +Classical serifs with low contrast and warm, organic shapes. Garamond, Caslon, Sabon, Adobe Garamond, Bembo, Janson Text. The letterforms reference 16th-18th century book typography. Diagonal stress, bracketed serifs, gentle thick-thin variation. + +Old-style serif reads heritage, traditional, institutional. It carries weight that newer registers cannot. Used in legal firms whose history runs to a partner's name from 1923, in academic institutions that predate the country, in luxury brands whose claim is centuries-long craft. Used poorly, it reads as a fake heritage costume. + +Garamond (Claude Garamond, mid-1500s) is the prototype; Adobe Garamond (Robert Slimbach, 1989) is the most-deployed modern revival. Caslon (William Caslon, 1722) is the British equivalent, long called "the safe choice for legal documents". Sabon (Jan Tschichold, 1967) is a modernized Garamond designed for industrial typesetting. Bembo (Stanley Morison's revival of Aldus Manutius's 1495 type) is the Italian Renaissance reference. All four predate every other typeface in this file by centuries. + +### Categories that default to old-style serif + +- Legal firms with heritage positioning (white-shoe firms, partnerships founded before 1950) +- Academic institutions (universities, presses, scholarly journals) +- Heritage luxury brands (centuries-old jewelers, watchmakers, fashion houses) +- Editorial brands with literary positioning (literary magazines, book publishers) +- Whiskey, wine, and other categories where "we have been doing this for generations" is the marketing claim + +### Example brands + +- The Economist (custom Caslon-derived display) +- The New Yorker (custom Caslon-derived masthead and ITC New Baskerville for body) +- Most university press identities (Yale, Oxford, Princeton) +- Most heritage law firm identities (Wachtell, Cravath, Latham use serifs derived from this register) + +### Pairing notes + +Old-style serif pairs well with humanist sans (both share calligraphic origins) and with neo-grotesque sans for editorial systems wanting modern-classical contrast. Avoid pairing old-style serif with geometric sans; the registers fight each other (geometric coldness vs old-style warmth). Avoid pairing old-style serif with transitional serif; the contrast is too subtle to register as intentional. + +### Common pitfalls + +- The dated risk. Old-style serif used without deliberate restraint reads as old-fashioned, which can be the goal (heritage) or the failure (trying to look serious by using old-looking type). +- The thin-stroke screen problem. Old-style serif's hairline serifs and thin strokes can disappear at small screen sizes. Either pick a screen-optimized old-style cut (Adobe Garamond Pro, EB Garamond) or accept that the wordmark must be set large. +- The fake-heritage risk. Using Garamond on a brand founded last year reads as costume, not heritage. The audience is not fooled by typography alone; the rest of the brand system has to carry the heritage claim. + +--- + +## Slab serif + +Heavy structural serifs with strong thick-thin uniformity. The serifs are blocky, rectangular, often nearly equal in weight to the stems. Sentinel, Adelle, Roboto Slab, Tisa, Rockwell, Archer, Vitesse. The visual register is strong, declarative, sometimes journalistic. + +Slab serif reads strong, structural, declarative. It carries authority without the heritage baggage of old-style serif. Common in editorial work, sports brands, journalistic identities, and brands that want serif weight without the ornament of transitional or old-style serifs. + +Sentinel (Hoefler & Frere-Jones, 2009) is the modern editorial slab. Adelle (TypeTogether, 2009) is the screen-optimized slab serif of choice for digital editorial. Roboto Slab is Google's open-source slab. Rockwell (Frank Hinman Pierpont, 1934) is the British slab serif of railway and industrial heritage. Tisa (Mitja Miklavčič) is the modern slab with humanist warming, used in editorial systems. + +### Categories that default to slab serif + +- Editorial and publishing (when the brand wants more weight than transitional serif provides) +- Sports brands (the typographic equivalent of athletic gravity) +- Journalistic identities (some newspapers, news magazines) +- Industrial and engineering brands (the structural quality reads as "we make real things") +- Outdoor and adventure brands (Filson, Patagonia in some treatments, REI's wordmark) + +### Example brands + +- Mailchimp's wordmark (custom slab-derived script) +- The Wall Street Journal (in older treatments) +- Various sports league identities (NFL teams, college athletics) +- Filson's wordmark (custom slab serif) + +### Pairing notes + +Slab serif pairs well with neo-grotesque sans (the structural similarity reads as one design language at different ornament levels) and with geometric sans (both are constructed registers). Avoid pairing slab serif with old-style serif; the contrast between structural and organic serifs reads as system inconsistency. + +### Common pitfalls + +- The "newspaper from 1985" risk. Some slab serifs read as 1980s editorial unless paired with current typographic systems. +- The clunky risk. Slab serifs' structural weight can feel heavy at large sizes; the wordmark needs to be sized carefully so the slabs do not overpower the letterforms. +- The genre-trapping risk. Slab serifs are so coded for sports, journalism, or industrial that using them outside those categories can feel like the brand is borrowing the register's gravity rather than earning its own. + +--- + +## Display custom + +Custom-drawn or heavily-modified typeface designed specifically for the brand. Reads distinctive but expensive in time and budget. The wordmark uses letterforms that exist nowhere else. + +Custom display is the highest distinctiveness tier. Stripe's wordmark, Google's Product Sans, Pinterest's custom geometric, Spotify's Circular variant, Airbnb's Cereal. Each is a custom typeface drawn to solve a specific problem in the brand's wordmark or identity system. + +The justification is when the brand needs a wordmark no one else has and the budget supports drawing one. Custom display is rarely justified for new brands without significant marketing investment because the brand has not yet earned the recognition that makes the custom letterforms register as distinctive. For mature brands, custom display is the ceiling of typographic discipline. + +### Categories where custom display fits + +- Mature brands at scale where custom letterforms become a competitive moat +- Tech-led brands with budget for type design partnerships +- Heritage luxury brands whose wordmark must be unique (not Garamond plus a name) +- Editorial brands with recognizable masthead type (The New York Times, The New Yorker) +- Sports leagues and major sports brands + +### Example brands + +- Stripe (custom Sohne, then Söhne plus custom optical adjustments on the wordmark) +- Google (Product Sans, custom geometric) +- Spotify (Circular variant, then custom Spotify Mix) +- Airbnb (Cereal, custom geometric humanist by Dalton Maag) +- Pinterest (custom geometric for the wordmark) + +### Pairing notes + +Custom display is rarely paired in lockup; the custom typeface IS the wordmark. The pairing decision is which body and metadata typefaces support the custom display in larger system applications. The body typeface is typically chosen for legibility at small sizes (a screen-optimized neo-grotesque or humanist sans) rather than for visual harmony with the custom display. + +### Common pitfalls + +- The cost risk. Custom letterform drawing is expensive (5-figure to 6-figure engagements depending on scope). The investment must match the brand's recognition trajectory. +- The over-customization risk. Custom letterforms should solve specific problems, not announce themselves. The custom "g" that reads as cleverly drawn rather than as just-the-letter-g signals committee work. +- The aging risk. Custom display typefaces age with the era they were drawn in. The Spotify wordmark from the 2010s reads as 2010s; the brand has had to update the system multiple times. Plan for redrawing every 5-10 years. + +--- + +## How to choose, in summary + +The choice flows from category default and positioning intention. + +- In-category choice signals competence. Legal in old-style serif, SaaS in neo-grotesque sans, sports in slab serif. The audience reads "this brand understands the category". +- Out-of-category choice signals positioning. Legal in geometric sans signals "we are modern". SaaS in old-style serif signals "we take the work seriously". Outdoor in geometric sans signals "we are not your grandfather's outdoor brand". The shift is intentional and the rest of the brand system has to support it. +- Custom display is reserved for mature brands with recognition that earns the investment. +- Pairing logic combines the wordmark register with body and metadata registers to build the system. The pairing should read as one design intention, not as two competing ones. + +The wrong typographic register is not always obvious in isolation. It becomes obvious in deployment: the wordmark on the business card, the lockup at retail, the favicon at 16px. Test the chosen register against the brand's actual application contexts before committing. diff --git a/skills/long-form-content-frameworks/SKILL.md b/skills/long-form-content-frameworks/SKILL.md new file mode 100644 index 0000000..b80133a --- /dev/null +++ b/skills/long-form-content-frameworks/SKILL.md @@ -0,0 +1,311 @@ +--- +name: long-form-content-frameworks +description: "Patterns for individual long-form content pieces. Case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials. The structural disciplines that distinguish publication-quality long-form from bloggy-long padding or academic bloat. Different from pillar-content-architecture (which covers hub structure); this skill covers individual deep-dive pieces. Triggers on long-form content, case study writing, whitepaper, research report, definitive guide, ebook, manifesto, long-form tutorial, deep-dive article, anchor piece, foundational article, structural archetypes. Also triggers when a piece is over 3,000 words and the team is unsure how to structure it, when a long-form draft feels padded or saggy, or when a flagship asset needs the depth to actually earn the length." +category: content +catalog_summary: "Structural patterns for individual long-form pieces (case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials) that distinguish publication-quality work from bloggy-long padding or academic bloat" +display_order: 9 +--- + +# Long-Form Content Frameworks + +A senior editorial leader's playbook for individual long-form content pieces. The structural disciplines that distinguish publication-quality work from bloggy-long padding or academic bloat. + +Long-form is where most content programs lose their nerve or lose their way. Teams either stretch a 1,500-word post to 5,000 with filler (the bloggy-long failure mode), or they over-document the topic with no editorial spine (the academic-bloat failure mode). The pieces that earn their length are the ones where each section justifies its weight, the lede sets a thesis the body actually delivers, and the closing leaves the reader with something specific. + +This skill covers the individual long-form piece: the case study, the whitepaper, the research report, the manifesto, the ebook chapter or full ebook, the definitive guide, the long-form tutorial. Different from `pillar-content-architecture` (which covers HUB architecture: how a pillar plus cluster system fits together), this skill covers the long-form PIECE itself, regardless of whether it sits at the center of a hub or stands alone. + +The voice is the senior editorial leader who has shipped dozens of flagship long-form assets and watched plenty of others fail. Honest about which formats earn their length, which structural archetypes fit which problems, and where long-form most often goes wrong. + +When to use this skill: planning a flagship long-form piece, structuring a draft that feels saggy, reviewing a long-form piece that is technically correct but emotionally flat, or auditing a content library to find the long-form pieces that should have been blog posts. + +--- + +## What this skill is for + +This skill spans individual long-form content pieces. The content suite distinction: + +- `content-strategy` is program scope: what to produce across the program. +- `pillar-content-architecture` is HUB scope: pillar plus cluster as a topical hub system. +- `long-form-content-frameworks` (this skill) is PIECE scope for long-form: individual deep-dive pieces, standalone or as pillars. +- `content-and-copy` is execution scope at any length: writing the words. +- `content-brief-authoring` is per-piece brief scope at any length: the contract. +- `editorial-qa` is gate scope: pre-publish verification. +- `ai-content-collaboration` is workflow scope: how humans and AI compose. + +A pillar page IS often a long-form piece. The two skills compose: pillar-content-architecture decides the hub shape and which pieces sit where; this skill is how you structure the long-form pieces themselves so they earn the length they take up. + +The audience: editorial leads, content directors, in-house teams shipping flagship long-form, agencies producing whitepapers and research reports, anyone planning a piece that will run 3,000+ words and need to hold a reader to the end. + +What is not in scope: blog-post-length writing (covered by `content-and-copy`), the brief itself (covered by `content-brief-authoring`), the hub architecture around a long-form piece (covered by `pillar-content-architecture`), or the pre-publish QA pass (covered by `editorial-qa`). + +--- + +## Bloggy-long vs academic-bloat vs publication-quality + +The keystone framing. Two failure modes plus the discipline. + +Bloggy-long. A regular blog post stretched to 5,000 words via padding. Same structural shape as 1,500 words, just inflated: more transitional paragraphs, more "before we get into it," more recap sections, more bullet expansions of single ideas. The reader notices within 600 words and skims. Output: a piece that ranked because it was long, never gets read all the way through, never gets shared, never earns links because nobody finished it. + +Academic-bloat. Exhaustive coverage that loses the thread. 8,000 words where 4,500 would have served. Every adjacent topic surveyed; every definition restated; every caveat documented. Reader respects the effort and skims for the parts they need. Output: a "comprehensive" piece that nobody reads end-to-end, that does not change anyone's mind, that performs in search but underperforms in trust. + +Publication-quality. Structural depth that earns the length. Each section justifies its weight. The lede establishes a thesis the body delivers. The closing is specific. Reading flow varies in density, register, and rhythm so the piece sustains attention. The piece reads as the work of someone who had something specific to say and the discipline to say it well at length. + +The litmus test. Ask of any long-form draft: would cutting this section weaken the argument, or would it just make the piece shorter? If cutting strengthens it, the section was filler. The piece earns its length when each section is doing structural work the argument requires. + +--- + +## Long-form formats and when each fits + +Seven formats, each with a different structural shape and a different reader contract. + +Case study. A specific company, project, or initiative with quantified outcomes. Reader contract: "Show me what worked and why, with specifics." Length: 2,000 to 4,000 words typical. Structural archetype: usually problem-solution. The case-study tax: real numbers, real names, real specificity. Generic case studies signal nothing. + +Whitepaper. A position document on a substantive topic, typically with original analysis. Reader contract: "Take me through your reasoning on this question with the rigor I would expect from a serious source." Length: 3,000 to 8,000 words. Structural archetype: layered argument or comparative analysis. Often gated. The whitepaper tax: original synthesis, not survey of existing literature. + +Research report. Original primary research presented with methodology, findings, implications. Reader contract: "Show me the data, how you collected it, what it means." Length: 4,000 to 12,000 words. Structural archetype: taxonomic survey or comparative analysis. The research-report tax: actual primary research, not "we surveyed 300 marketers" with leading questions. + +Definitive guide. Comprehensive coverage of a topic for a specified audience. Reader contract: "Be the canonical resource on this." Length: 4,000 to 10,000 words. Structural archetype: taxonomic survey. The definitive-guide tax: actual comprehensiveness; gaps reveal that the guide is not actually definitive. + +Manifesto. A position paper on what the writer believes and why, often confrontational. Reader contract: "Tell me what you think and convince me." Length: 1,500 to 6,000 words. Structural archetype: layered argument or narrative arc. The manifesto tax: actual conviction, not diplomatic hedging. + +Ebook. Multi-chapter long-form, often a sequence of related pieces with introduction and conclusion. Reader contract: "Take me through a body of work." Length: 8,000 to 30,000+ words. Structural archetype: usually narrative arc across chapters. The ebook tax: each chapter earns its place; the table of contents is not padding. + +Long-form tutorial. Instructional content where the reader is following along. Reader contract: "Take me from where I am to where I want to be, step by step." Length: 3,000 to 8,000 words. Structural archetype: problem-solution with sequential steps. The long-form-tutorial tax: every step actually works; gaps in the sequence break the reader. + +Detail in [`references/format-decision-framework.md`](references/format-decision-framework.md). + +--- + +## Structural archetypes + +Five archetypes that fit different long-form problems. + +Problem-solution. State the problem with weight; develop why it matters; present the solution; show how it works; address objections. Fits case studies, long-form tutorials, manifestos with a clear opposition. Risk: feels formulaic if every piece uses it. + +Narrative arc. Beginning, middle, end. A protagonist (often the company, sometimes a person, sometimes the reader) faces a complication and resolves it. Fits ebooks, some case studies, longer manifestos. Risk: forced narrative on topics that are not actually stories. + +Layered argument. Position stated; layer 1 evidence; layer 2 evidence; counter-arguments addressed; synthesis. Fits whitepapers, manifestos, position pieces. Risk: feels academic if the layers do not build to a real synthesis. + +Taxonomic survey. A topic mapped into categories; each category explored; relationships among categories surfaced. Fits definitive guides, research reports surveying a landscape. Risk: feels like a list with subheads if the taxonomy is not actually load-bearing. + +Comparative analysis. Multiple options, frameworks, or positions compared along defined axes; tradeoffs surfaced; the writer's recommendation argued. Fits whitepapers, decision-guide research reports, technology comparisons. Risk: feels like a feature matrix if the analysis is shallow. + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. A whitepaper might be a layered argument with comparative-analysis sections. A definitive guide might be a taxonomic survey with problem-solution chapters. The archetype is the spine; variation prevents the piece feeling formulaic. + +Detail in [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md). + +--- + +## Section weight calibration + +How long sections should be relative to each other, varying by format. + +The general principle: section weights match how much load the section is bearing in the argument. Throat-clearing introductions get cut. Setup sections are short. Argument-bearing middle sections are longest. Closings are specific and tight. + +Whitepaper / research report typical weights. Introduction 8-12% (thesis stated, scope set). Methodology or framing 10-15% (how the analysis works). Body 60-70% (the actual argument or findings, divided into 3-5 weighted sections). Implications 10-15%. Closing 3-5%. + +Case study typical weights. Setup and context 15-20% (the company, the problem, why it mattered). Solution narrative 50-60% (what was done, in sequence). Outcomes 15-20% (quantified results, what worked, what did not). Reflection 5-10% (what the team would change). + +Manifesto typical weights. Position 5-10% (what is believed, stated early and clearly). Argument 70-80% (why, with the layers building intensity). Call 10-15% (what should change as a result). + +Definitive guide typical weights. Introduction 5-8% (what the guide covers, who it serves). Body across taxonomic sections 80-85% (each section roughly even). Closing and additional resources 7-10%. + +Long-form tutorial typical weights. Setup 10-15% (what the reader will achieve, what they need). Sequential steps 70-80% (each step its own subsection). Troubleshooting and edge cases 10-15%. + +The audit. If one section is more than 3x the length of another bearing similar argumentative load, the piece is structurally unbalanced. Either the long section needs to be split, or the short section needs to be deepened, or the imbalance reflects an actual content problem the writer has not surfaced. + +Detail in [`references/section-weight-calibration.md`](references/section-weight-calibration.md). + +--- + +## Lede patterns for long-form + +Long-form ledes do different work than blog-post ledes. + +A blog-post lede answers the user's likely query in the first 200 words. A long-form lede establishes a thesis the next 5,000 words will deliver, sets the reader's expectations for the piece's depth, and earns the reader's attention for the time investment ahead. + +Patterns that work. + +- The contested-claim opener. A surprising or contested position stated cleanly, then the rest of the piece argues for it. Fits manifestos, opinionated whitepapers. +- The problem-with-stakes opener. A problem stated with the stakes made tangible. Fits case studies, problem-solution pieces. +- The data-anomaly opener. A piece of data that does not fit the consensus, framed as the question the piece will answer. Fits research reports, analytical whitepapers. +- The scene opener. A specific moment, person, or scene that grounds the abstract topic. Fits narrative-arc pieces, magazine-style longform. +- The orientation opener. What this piece covers, who it is for, what reading it costs and pays. Fits definitive guides and tutorials where the reader's first question is "is this the right resource for me." + +Patterns that fail. + +- The throat-clear opener ("Content marketing has changed dramatically over the past decade. In this article, we will explore...") signals filler ahead. +- The dictionary-definition opener ("According to Merriam-Webster, X is defined as...") signals an unwillingness to commit a position. +- The history-of-the-topic opener (paragraphs of background before the argument starts) loses readers before the thesis lands. +- The "in this article we will discuss" tour opener flattens the piece into an outline before the writer has earned attention. + +The first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. Spending it on filler is the most common long-form failure. + +Detail in [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md). + +--- + +## Sustaining attention across 5,000+ words + +Long pieces that hold readers vary their density, register, and rhythm. Pieces that lose readers feel uniform: same paragraph length, same sentence rhythm, same density of claim, page after page. + +Density variation. Some sections argue tightly (claim, evidence, claim, evidence). Others reflect, illustrate, or breathe. The argument-tight sections earn the breathing sections; the breathing sections give readers room to absorb. + +Register variation. Most long-form pieces sustain a primary register (analytical, narrative, instructional) while occasionally shifting to a secondary register (anecdotal, reflective, declarative) for variation. A whitepaper that is purely analytical for 6,000 words exhausts the reader; a whitepaper with a mid-piece anecdote or a closing reflection lands harder. + +Rhythm variation. Sentence length variation matters more in long-form than short. Strings of 25-word sentences blur; strings of 8-word sentences fragment. The pattern that holds attention: medium sentences with occasional short punches and occasional layered longer constructions. + +Visual rhythm. Subheads, pull quotes, callouts, charts, illustrations break the page into navigable units. Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. The rhythm: visual element every 600-1,000 words on average, varied in type. + +Mid-piece micro-thesis. Around the 40-60% mark, restate the central claim with new framing. Long-form readers' attention naturally dips mid-piece; the mid-piece restatement reorients them and refreshes engagement. + +Detail in [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md). + +--- + +## Citations and source authority + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. + +Source hierarchy for long-form. + +- Primary research: original studies, datasets, interviews, the writer's own data work. Highest authority. +- Authoritative secondary sources: peer-reviewed papers, government data, established research firms, primary reporting from credible outlets. +- Industry-credible sources: vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners. +- Linked-aware secondary sources: reputable blogs and publications where the source is verifying claims, not just amplifying them. +- Avoid: citation laundering through other content marketing pieces, "studies show" claims with no link, anonymous "experts," reposts of reposts. + +Citation density. Long-form arguments need citations roughly proportional to claim density. A piece making 30 falsifiable claims needs 30 citations; a piece making 5 strong claims with extensive elaboration may need 5. The audit: every falsifiable claim is either cited or attributed to the writer's own analysis. + +Source freshness. Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. The "85% of marketers" stat from 2018 in a 2026 piece signals stale research. + +Inline vs endnote citations. Long-form on the web typically uses inline links to authoritative sources. For research-heavy pieces, endnote-style citations (numbered footnotes) signal academic rigor; for editorial whitepapers, inline links keep momentum. Either works; pick one and stay consistent within the piece. + +Detail in [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md). + +--- + +## Visualization and breakouts + +Long-form earns visual breakouts; blog posts often do not. The discipline is which breakouts earn their place. + +Visual element types. + +- Charts and graphs: data visualization that the prose alone cannot convey efficiently. +- Diagrams: relationships, flows, architectures, taxonomies that benefit from visual structure. +- Pull quotes: moments where a single sentence deserves visual weight. +- Sidebars: tangential but valuable context that does not fit the main thread. +- Tables: comparison data, structured reference material. +- Inline callouts: definitions, warnings, "if you only read one section" pointers. + +Earned-position rule. Each visual element earns its place by carrying argumentative load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. + +Production tax. Each visual element costs design time, accessibility work (alt text, screen-reader-friendly tables), and revision overhead when the underlying content changes. Long-form pieces with 25 charts each take meaningful production time to maintain. Plan visual count against production capacity, not against ideal-world maximalism. + +Anti-pattern: the stock-image header. Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. Either commission specific visual work (custom illustrations, branded data visualizations, scene photography) or skip the hero image. + +Detail in [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md). + +--- + +## Closing patterns + +Long-form pieces with strong closings get shared, get linked, and get remembered. Pieces with throat-clearing closings disappear after the last subhead. + +Closings that work. + +- The specific call. What should the reader do, decide, or change as a result of reading this. Concrete, not generic. +- The reframed thesis. The opening claim restated with the weight the body has now earned, often inverted or sharpened. +- The open question. The question this piece's findings raise but do not answer, framed as the next investigation. +- The personal reflection. The writer's stake in the topic surfaced briefly. Fits manifestos, opinionated long-form. +- The provocation. A challenge to the reader, the field, or the consensus. Fits manifestos. + +Closings that fail. + +- The recap closing ("In this piece we covered X, Y, Z") signals the writer ran out of energy. +- The "more research is needed" closing on every research report signals the writer did not commit a position. +- The throat-clear closing ("As we have seen, content is important and only getting more so") delivers no payload. +- The CTA-as-closing ("Book a demo") on a long-form piece breaks the editorial contract; if a CTA belongs, it sits below the closing, not as the closing. + +The audit. Ask of any long-form closing: does this leave the reader with something specific to do, decide, or think about, or does it just signal the piece is ending? If the latter, rewrite. + +Detail in [`references/closing-patterns.md`](references/closing-patterns.md). + +--- + +## Distribution implications for long-form + +Long-form's distribution shape differs from blog-post distribution. The format choices echo through how the piece reaches readers. + +Gated vs ungated. Whitepapers and research reports often gate behind a form to capture leads; ebooks frequently do; case studies sometimes do. The tradeoff: gating cuts reach by 70-90%; the gated audience is qualified but small. Manifestos and definitive guides typically stay ungated to maximize reach and link equity. The decision turns on whether the piece's primary value is reach (ungated) or qualified-lead capture (gated). + +Format choices. Long-form web page (HTML), downloadable PDF, mixed (web with PDF download option), interactive (web with embedded tools or visualizations). Web pages earn search traffic; PDFs earn email-shareable assets; mixed maximizes both. The production cost rises with format count. + +Syndication and excerpting. Long-form pieces lend themselves to chapter excerpts, summary blog posts, and email-newsletter serializations. Plan the excerpting at piece-design time so the chapters or sections are excerpt-ready. See `content-repurposing` for the cross-format adaptation discipline. + +Refresh schedule. Long-form pieces with research components need annual or quarterly refresh on the data; long-form pieces with timeless framings need lighter touch. See `content-refresh-system` for refresh prioritization. + +The decision sequence: format first, distribution shape second. A research report's distribution shape (often gated, often PDF, often paired with a webinar) follows from the format choice; trying to retrofit distribution onto a piece that was written for the wrong shape produces friction. + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-long-form-failures.md`](references/common-long-form-failures.md). + +- "We wrote 5,000 words and traffic is flat." Bloggy-long: stretched to length, no structural depth. Cut to 1,800 words or rewrite as publication-quality. +- "Our whitepaper looked authoritative but nobody finished it." Academic-bloat: comprehensive but not load-bearing. Cut sections that did not move the argument. +- "The lede took 800 words to get to the thesis." Throat-clearing opener; rewrite to land the position in the first 150-250 words. +- "Each section is the same length and rhythm." No section weight calibration; sections all bearing the same argumentative load suggests an undifferentiated piece. +- "The piece sags around the 60% mark." Standard mid-piece attention dip; add a mid-piece micro-thesis and rhythm variation. +- "The closing repeated the introduction." Recap closing; rewrite to a specific call, reframed thesis, or open question. +- "Citations are mostly other blog posts." Citation laundering; replace with primary or authoritative secondary sources. +- "We commissioned 12 charts, the team is exhausted, traffic is the same." Visual count exceeded production capacity and earned-position discipline; cut to charts that bear argumentative load. +- "The case study has no specifics." Generic case-study failure; the case-study tax is real numbers, real names, real specificity. Without those, the format does not work. +- "Our manifesto reads as diplomatic." Manifesto failure: the format demands conviction; if the writer cannot commit, write a different format. +- "The definitive guide has obvious gaps." Definitive-guide failure: the format requires actual comprehensiveness. Either fill the gaps or rename the piece. + +--- + +## The framework: 12 considerations for long-form content + +When planning or auditing a long-form piece, walk these 12 considerations. + +1. Format fits the work. Case study, whitepaper, research report, definitive guide, manifesto, ebook, or long-form tutorial. Format chosen for reader contract, not arbitrary length. +2. Structural archetype selected. Problem-solution, narrative arc, layered argument, taxonomic survey, or comparative analysis as the spine. +3. Lede earns the next 30 minutes. Thesis stated, stakes set, position committed within the first 150-250 words. +4. Section weights calibrated to argumentative load. No section 3x another bearing similar load; throat-clearing sections cut. +5. Density variation. Argument-tight sections balanced with reflective or illustrative sections. +6. Register variation. Primary register sustained with secondary-register moments for variation. +7. Rhythm variation. Sentence and paragraph length varies; visual breakouts every 600-1,000 words. +8. Mid-piece micro-thesis. Central claim restated around the 40-60% mark. +9. Citations match claim density. Falsifiable claims cited; primary or authoritative sources preferred; sources fresh. +10. Visual elements earn position. Each chart, diagram, sidebar carries load the prose alone cannot. +11. Closing is specific. Specific call, reframed thesis, open question, or provocation. Not recap. +12. Distribution shape matches format choice. Gating, format mix, syndication plan, refresh schedule planned at piece-design time. + +The output of the framework is a long-form piece that earns its length: every section justified, every page sustaining attention, every claim verifiable, every closing specific. + +--- + +## Reference files + +- [`references/format-decision-framework.md`](references/format-decision-framework.md) - When each long-form format fits. Reader contracts, length norms, structural archetype tendencies, format-specific taxes. +- [`references/structural-archetype-patterns.md`](references/structural-archetype-patterns.md) - Five archetypes (problem-solution, narrative arc, layered argument, taxonomic survey, comparative analysis) with worked examples and combination patterns. +- [`references/section-weight-calibration.md`](references/section-weight-calibration.md) - Typical weight ratios by format. Whitepaper, case study, manifesto, definitive guide, long-form tutorial profiles. The 3x audit. +- [`references/lede-patterns-for-long-form.md`](references/lede-patterns-for-long-form.md) - Five patterns that work, four that fail. The first-paragraph sales-pitch frame. +- [`references/attention-sustaining-techniques.md`](references/attention-sustaining-techniques.md) - Density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis discipline. +- [`references/citation-and-source-authority.md`](references/citation-and-source-authority.md) - Source hierarchy, citation density, freshness, inline vs endnote conventions, citation-laundering anti-pattern. +- [`references/breakouts-and-visualization.md`](references/breakouts-and-visualization.md) - Visual element types, earned-position rule, production-tax discipline, the stock-image-header anti-pattern. +- [`references/closing-patterns.md`](references/closing-patterns.md) - Five closings that work, four that fail. The specific-call, reframed-thesis, open-question, personal-reflection, provocation patterns. +- [`references/common-long-form-failures.md`](references/common-long-form-failures.md) - 11+ failure patterns with diagnoses, including bloggy-long, academic-bloat, throat-clearing leads, visual-count overruns, citation laundering, format-tax failures. + +--- + +## Closing: long-form earns its length or it does not + +Length is not a virtue. A 5,000-word piece is only worth more than a 1,500-word piece if those extra 3,500 words carry structural and argumentative load the shorter version could not. Most long-form content underperforms because the team chose length first and structural depth second. + +The discipline is the inversion. Decide what the piece needs to deliver, choose the format and archetype that fit, calibrate sections to actual argumentative load, and let the length follow. Pieces written that way earn their length and read as the work of someone who had something to say. Pieces written length-first read as filler, no matter how many subheads dress them up. + +When in doubt about whether a long-form piece is ready, ask: does each section justify its weight, does the lede earn the next 30 minutes, does the closing leave the reader with something specific, are claims cited, do visuals carry load, does the mid-piece micro-thesis refresh attention? If yes to all of those, the piece is publication-quality. If no to any, the gap is where the reader stops reading. diff --git a/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md b/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md new file mode 100644 index 0000000..90a251c --- /dev/null +++ b/skills/long-form-content-frameworks/references/attention-sustaining-techniques.md @@ -0,0 +1,129 @@ +# Attention-sustaining techniques + +How long-form pieces hold readers across 5,000+ words. The patterns that keep reader attention across the time investment, and the underlying observation: readers leave because pieces feel uniform. + +The pieces that lose readers in long-form are the ones that feel monotone. Same paragraph length, same sentence rhythm, same density of claim, page after page. Even competent writing reads as exhausting under that pattern. The pieces that hold readers vary their density, register, and rhythm so the reader's attention has somewhere to recover and somewhere to engage. + +--- + +## Density variation + +Long-form pieces should alternate between argument-tight sections and breathing sections. + +Argument-tight sections. Claim, evidence, claim, evidence. Specific, direct, intellectually demanding. The reader is doing work to follow the argument. + +Breathing sections. Reflection, illustration, anecdote, restatement. Lower density of new claims; higher density of integration with what was just argued. + +The pattern that holds. After an argument-tight section, a breathing section gives the reader room to absorb. After a breathing section, the reader returns to argument-tight work refreshed. Pieces that are argument-tight throughout exhaust readers; pieces that breathe throughout never feel substantive. + +The audit. For each section, characterize it as argument-tight or breathing. If the sequence is all argument-tight, the piece is dense and exhausting. If the sequence is all breathing, the piece is shallow despite its length. The mix is the discipline. + +--- + +## Register variation + +Most long-form pieces sustain a primary register while shifting briefly to secondary registers for variation. + +Primary registers. + +- Analytical: claim-evidence-implication, measured tone, distance from the topic. +- Narrative: scene-driven, character-driven, time-progressive. +- Instructional: do-this-then-this, addressed to the reader directly. +- Declarative: positions stated, opinions committed, weight on conviction. + +Secondary registers. Anecdotal moments inside an analytical piece. Reflective moments inside an instructional piece. A specific scene inside a declarative manifesto. A measured analytical section inside a narrative. + +The pattern that holds. A whitepaper sustained in analytical register for 6,000 words exhausts readers; the same whitepaper with a mid-piece anecdote and a closing reflection lands harder. A long-form tutorial sustained in instructional register for 5,000 words feels mechanical; the same tutorial with a brief reflective section on common failures and a personal note from the writer feels human. + +The discipline. Choose the primary register first; insert secondary-register moments at section transitions where the shift will refresh attention rather than disorient. + +--- + +## Rhythm variation + +Sentence and paragraph length variation matters more in long-form than in short. + +Sentence length. + +- Strings of 25-word sentences blur. The reader's eye glides over the text without the cognitive checkpoints short sentences create. +- Strings of 8-word sentences fragment. The text reads as choppy, and the reader's attention is interrupted constantly. +- The pattern that holds: medium sentences with occasional short punches and occasional layered longer constructions. + +Paragraph length. + +- Long paragraphs (8+ sentences) feel academic. Suitable for argument-tight sections; exhausting if sustained. +- Short paragraphs (1-2 sentences) feel staccato. Suitable for emphasis and for breaking dense passages; fragmenting if sustained. +- The pattern that holds: most paragraphs 3-5 sentences with occasional shorter ones for emphasis and occasional longer ones for layered argument. + +Heading rhythm. H2 every 600-1,200 words on average. H3 within H2 sections to break navigation. Headings that come at uniform intervals feel mechanical; headings that follow the actual structural breaks feel natural. + +The audit. Read the piece aloud. Does the rhythm vary, or does every sentence and paragraph land with the same beat? If the latter, the piece needs rhythm work even if every individual sentence is competent. + +--- + +## Visual rhythm + +Long-form pieces with no visual rhythm are walls of text; long-form pieces with too many breakouts feel like marketing collateral. + +The norm. A visual element every 600-1,000 words on average. Visual elements include subheads, pull quotes, callouts, charts, diagrams, sidebars, tables, and images. + +Variation in type. All-subheads-no-charts feels under-designed for the piece's length. All-charts-no-pull-quotes feels like a research dump. The visual rhythm should vary: a subhead, then 800 words of prose, then a chart, then 600 words of prose, then a pull quote, then 700 words of prose, then a callout, then 900 words and the next subhead. + +The earned-position rule. Each visual element earns its place by carrying load the prose alone cannot. Decorative charts that restate the prose visually weaken the piece; charts that surface a pattern the prose can only summarize strengthen it. See `breakouts-and-visualization.md` for the discipline. + +Mobile reading reality. Long-form on mobile gets read in landscape stretches. Subheads should be visible without scrolling on each major section transition; pull quotes should be visible early to preview the piece's depth; charts should be readable without horizontal scrolling. + +--- + +## Mid-piece micro-thesis + +Long-form readers' attention naturally dips around the 40-60% mark. Pieces that survive the dip have a structural move that refreshes engagement at that point. + +The micro-thesis pattern. Around the midpoint, restate the central claim with new framing. The restatement does three things at once: it reorients readers who have been following sections, it gives drifting readers a checkpoint to re-engage, and it sets up the second half of the piece. + +Worked example. A whitepaper opens with the claim "Most teams treating content marketing as a volume problem will continue to underperform." At the midpoint, after the structural argument and the first empirical layer, the writer restates: "The pattern across the data is consistent. The teams that broke the volume-first cycle did not produce more; they produced less, and committed harder to what they produced." The reader is reoriented; the second half of the piece can build on the restatement. + +Anti-pattern: the recap micro-thesis. Restating "as we have seen so far, content marketing is changing" is filler, not micro-thesis. The micro-thesis should add framing or sharpen the claim, not recap. + +Where the micro-thesis sits structurally. Often at the boundary between two body sections, especially the boundary between the first and second halves of a layered argument or the boundary between the third and fourth chapters of an ebook. + +--- + +## Combining the techniques + +A 6,000-word whitepaper using all five techniques. + +- Lede. Contested-claim opener, declarative register, short paragraphs for opening punch. +- Setup section. Analytical register, medium-density argument, 3-5 sentence paragraphs. +- First body section. Argument-tight density, analytical register sustained, longer paragraphs as the argument layers. +- Mid-piece micro-thesis. A short paragraph that restates the claim with new framing. Brief register shift to declarative. +- Second body section. Argument-tight density, but with a worked example inserted as a breathing pause. Worked example shifts briefly to narrative register. +- Counter-argument section. Argument-tight again, analytical register, with the counter-arguments engaged seriously. +- Synthesis. Density lower, register declarative, paragraphs short and emphatic. +- Closing. Declarative, short, specific. + +The piece reads as varied across its length even though it is a single sustained argument. + +--- + +## Common attention-loss patterns + +Patterns that show up when readers drop off mid-piece. + +The mid-piece sag. Around the 50% mark, the piece becomes harder to follow. Cause: no micro-thesis, no rhythm variation, the reader is exhausted from sustained argument-tight density. Cure: add micro-thesis at the section boundary nearest the midpoint; insert a breathing section. + +The wall-of-text section. A 1,500-word body section with no subheads, no visuals, no rhythm variation. Cause: the writer was deep in the argument and stopped attending to the reader. Cure: identify the natural sub-structure within the section, add subheads or visuals at the boundaries. + +The abstract drift. The piece's specifics decrease as it progresses. Concrete examples in the early sections; vague generalizations in the later sections. Cause: the writer ran low on specific examples; padded with abstraction. Cure: cut to the depth where specificity holds; better a shorter piece with sustained specificity than a longer piece that drifts abstract. + +The energy-decline closing. The closing reads as a writer who ran out of energy. Cause: writers fatigue before readers do. Cure: write the closing first or revise the closing last with fresh attention; the closing is too important to deliver tired. + +--- + +## Methodology-level choices that stay in the public skill + +The five techniques (density variation, register variation, rhythm variation, visual rhythm, mid-piece micro-thesis), the combining pattern, the common attention-loss patterns and their cures, the read-aloud audit. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags rhythm patterns. Specific reading-time analytics that detect mid-piece drop-off in the team's content. Specific paragraph-length analyzers in the team's writing tool. Specific A/B testing of structural variants. The team's own conventions for visual-element budgets per long-form piece. These vary by team, stack, and analytics setup. diff --git a/skills/long-form-content-frameworks/references/breakouts-and-visualization.md b/skills/long-form-content-frameworks/references/breakouts-and-visualization.md new file mode 100644 index 0000000..f361487 --- /dev/null +++ b/skills/long-form-content-frameworks/references/breakouts-and-visualization.md @@ -0,0 +1,147 @@ +# Breakouts and visualization + +Visual element types for long-form, the earned-position rule, the production-tax discipline, and the stock-image-header anti-pattern. The patterns that distinguish visual rhythm from visual clutter. + +Long-form earns visual breakouts; blog posts often do not. A 1,500-word blog post can carry one image; a 5,000-word whitepaper can carry six or eight visual elements before they feel like clutter. The discipline is not visual count but earned position: which visuals carry argumentative load, and which are decoration. + +--- + +## Visual element types + +Six categories, each with different work to do. + +Charts and graphs. Data visualization that conveys patterns the prose alone cannot convey efficiently. Line charts for time series, bar charts for comparisons, scatter plots for correlations, distributions for spread. The chart's value is showing the pattern; if the prose can summarize the pattern in one sentence and the chart adds nothing, the chart is decoration. + +Diagrams. Relationships, flows, architectures, taxonomies that benefit from visual structure. Process diagrams, system architectures, hierarchical relationships, decision trees. The diagram's value is making structure visible; topics with simple linear structure rarely need diagrams. + +Pull quotes. Moments where a single sentence deserves visual weight. Used sparingly for emphasis; one or two per long-form piece typical. The pull quote's value is signaling "this matters"; using pull quotes too often dilutes the signal. + +Sidebars. Tangential but valuable context that does not fit the main thread. Background detail, related concepts, optional deeper coverage. The sidebar's value is letting the main thread stay focused while preserving context for readers who want it. + +Tables. Comparison data, structured reference material. Side-by-side option comparisons, parameter listings, multi-axis evaluations. The table's value is making parallel data scannable; tables for non-parallel data are confusing. + +Inline callouts. Definitions, warnings, "if you only read one section" pointers. Short, focused, specific. The callout's value is interrupting flow for a specific purpose; callouts without specific purpose are decoration. + +--- + +## The earned-position rule + +Each visual element earns its place by carrying argumentative load the prose alone cannot. + +Earned visuals. + +- A chart that shows a pattern the prose can only summarize in vague terms ("increasing over time" becomes specific with the line chart). +- A diagram that makes a complex relationship instantly visible (a system architecture; a process flow with decision points). +- A pull quote that captures a position the writer wants to stand alone for emphasis. +- A sidebar with context that would derail the main thread if inline. +- A table that makes parallel comparison instant when the prose would require careful reading. + +Decorative visuals. + +- A chart that restates a number the prose just stated (the chart adds visual interest, not information). +- A diagram of a relationship the prose described in one sentence ("the marketing funnel" diagrammed, when the prose said "marketing has stages"). +- A pull quote of a sentence that did not deserve standalone weight. +- A sidebar with information that should have been cut entirely or integrated into the main thread. +- A table where the rows or columns are not actually parallel. +- A stock image at the top of the piece that signals only that the writer wanted a hero image. + +The audit. For each visual, ask: does cutting this visual lose information or capability that the prose alone cannot replace? If yes, the visual is earned. If no, the visual is decoration. + +--- + +## Production tax + +Visual elements cost more than writers often estimate. + +Per-visual costs. + +- Design time. Even simple charts require choices about color, scale, labeling, formatting. +- Accessibility work. Charts need alt text or alternative-format descriptions; tables need proper header markup; complex visuals need text equivalents. +- Revision overhead. When the data changes, the chart changes. When the framing changes, the diagram changes. Visual elements that go stale because they were not updated when the underlying content changed are worse than no visuals. +- Production review. Editors review prose; design or production review visuals. Pieces with many visuals need more review cycles. + +The capacity audit. Before committing to a visual count for a piece, check: does the team have the design capacity, the data-engineering capacity (for charts based on data), and the maintenance capacity to keep this number of visuals current? Pieces that ship with 12 visuals and decay because nobody updates them are worse than pieces that ship with 4 visuals that stay current. + +The MVP-visuals approach. Plan the minimum viable visual count: which visuals are load-bearing for the argument, which would be nice to have, which would be decoration. Ship the load-bearing ones. Add nice-to-haves only if capacity permits and the piece is genuinely long enough to need more visual rhythm. + +--- + +## The stock-image-header anti-pattern + +Generic stock imagery at the top of a long-form piece signals the writer did not commission visual work for the piece. + +The pattern. A whitepaper opens with a generic stock photo of "diverse business team meeting around laptop with charts." The image conveys nothing specific; readers tune it out within milliseconds. + +Why it fails. Long-form's value proposition includes signaling that the work is serious. Stock imagery undermines the signal: a serious piece would have commissioned specific visual work or skipped the hero image. Stock imagery says "we wanted a hero image and did not invest in one." + +The cure options. + +- Commission specific visual work. Custom illustration matched to the piece's argument. Branded data visualization based on the piece's findings. Scene photography directly related to the piece's case study. +- Skip the hero image entirely. Long-form pieces can open without a hero image; many of the strongest editorial pieces do. +- Use a content-specific opening visual. The first chart in the piece appears at the top, doing dual duty as hero image and load-bearing visual. + +The discipline. If the piece's hero image could be on any other piece on the same general topic, it is generic and should be cut or replaced. + +--- + +## Chart conventions for long-form + +Charts in long-form pieces have specific expectations. + +Title and caption. Every chart should have a title that describes what the chart shows and a caption that explains the source of the data. Charts without titles or captions read as decoration. + +Source attribution. The data behind the chart should be cited. "Source: 2024 Industry Survey, n=412, methodology in appendix" or similar. Charts without source attribution are unverifiable. + +Mobile readability. Charts should be readable on mobile without horizontal scrolling. Wide charts should be redesigned for mobile or marked as "view on desktop for full detail." Charts that are unreadable on mobile lose mobile readers. + +Color and contrast. Charts should pass accessibility contrast guidelines (WCAG AA minimum). Color-coded charts need either patterns or labels for readers with color-blindness. Charts that rely on color alone fail accessibility. + +Data integrity. Truncated y-axes that exaggerate effects, cherry-picked time ranges, and apples-to-oranges comparisons violate the implicit chart contract. Long-form readers who notice deceptive charts lose trust in the entire piece. + +--- + +## Diagram conventions for long-form + +Diagrams should make structure visible without becoming the main attraction. + +Simplicity. A diagram with 30 boxes and 50 arrows is a diagram nobody reads. Diagrams should be visually parse-able in seconds. Complex topics may need multiple simple diagrams rather than one comprehensive one. + +Labeling. Every box, arrow, and group should be labeled clearly. Diagrams with unlabeled elements assume the reader can infer the labels from context, which often fails. + +Reading order. Diagrams should have an obvious reading order (top to bottom, left to right, or numbered steps). Diagrams without obvious reading order leave readers uncertain how to traverse them. + +Mobile rendering. Wide diagrams that work on desktop become unreadable on mobile. Either redesign for mobile, accept that mobile readers will scroll, or split into multiple smaller diagrams. + +--- + +## Sidebar conventions + +Sidebars should be visually distinct from the main thread but not overwhelming. + +Length. Most sidebars run 100-300 words. Sidebars longer than 500 words probably should have been their own section in the main thread or their own piece. + +Visual treatment. Background color or border that distinguishes the sidebar from main prose. Different typography weight or font (where the design system supports it). + +Skip-readability. Sidebars should be skippable without losing the main argument. If the main argument depends on the sidebar's content, that content belongs in the main thread, not in a sidebar. + +--- + +## Pull-quote discipline + +Pull quotes should be earned moments, not decoration. + +Selection. A pull quote is a sentence the writer wants to stand alone for emphasis. It should be a sentence whose weight justifies the visual treatment. Generic sentences pulled into pull-quote treatment dilute the device. + +Frequency. One or two pull quotes per long-form piece is typical. Three or four can work for very long pieces (8,000+ words). More than that and the device loses meaning. + +Attribution within pull quotes. Pull quotes from interviews or external sources need attribution; pull quotes of the writer's own sentences do not need attribution but should still earn the visual weight. + +--- + +## Methodology-level choices that stay in the public skill + +The six visual element types and their work, the earned-position rule, the production-tax discipline, the stock-image-header anti-pattern, the chart conventions, the diagram conventions, the sidebar and pull-quote discipline, the MVP-visuals approach. + +## Implementation choices that stay internal + +Specific design tokens for charts in the team's brand system. Specific charting libraries the team uses. Specific accessibility-checking automation. Specific design-review workflow for visual elements. Specific custom-illustration commissioning processes. Specific stock-photo blocklist or sourcing guidelines. The team's own visual-budget conventions per format. These vary by team, design capacity, and tooling. diff --git a/skills/long-form-content-frameworks/references/citation-and-source-authority.md b/skills/long-form-content-frameworks/references/citation-and-source-authority.md new file mode 100644 index 0000000..5e961f6 --- /dev/null +++ b/skills/long-form-content-frameworks/references/citation-and-source-authority.md @@ -0,0 +1,130 @@ +# Citation and source authority + +Source hierarchy for long-form, citation density discipline, freshness norms, inline vs endnote conventions, and the citation-laundering anti-pattern. + +Long-form pieces cite more, and cite more authoritatively, than blog posts. The reader is investing 30+ minutes; the writer owes them claims they can verify. Pieces that fail at citation discipline read as if the writer wanted authority without paying the verification cost. + +--- + +## Source hierarchy + +Sources are not interchangeable. The same claim cited from a peer-reviewed paper carries different weight than the same claim cited from a vendor blog post. + +Tier 1: Primary research. Original studies, datasets, interviews, the writer's own data work. The writer is producing the data, not citing it. Highest authority. Pieces with primary research signal that the writer or team did the work. + +Tier 2: Authoritative secondary sources. Peer-reviewed papers, government data (BLS, Census, equivalent), established research firms (Gartner, Forrester, Pew, IDC, etc.), primary reporting from credible outlets. The writer is citing rigorous secondary work where the source's reputation does the verification work. + +Tier 3: Industry-credible sources. Vendor research with disclosed methodology, reputable trade publications, recognized expert practitioners with track records. The writer is citing sources that practitioners in the field would recognize as substantive even if they are not academically rigorous. + +Tier 4: Linked-aware secondary sources. Reputable blogs, publications, and commentary where the source is verifying claims rather than just amplifying them. The writer is citing sources that did some level of verification work, even if the source is a blog post rather than a study. + +Tier 5 and below: Avoid. Other content marketing pieces (citation laundering), "studies show" claims with no link, anonymous "experts," reposts of reposts, vendor marketing pages cited as research, AI-generated synthesis cited as primary source. + +The discipline. Long-form arguments should cite from tiers 1-3 wherever possible. Tier 4 is fine for color and context but should not bear primary argumentative load. Tier 5 sources signal the writer did not do the verification work. + +--- + +## Citation density + +Citations should be roughly proportional to claim density. + +A piece making 30 falsifiable claims. Roughly 30 citations or attributions to primary analysis. Each claim either points to a verifiable source or is identified as the writer's own analysis (in which case the analysis itself should be defended). + +A piece making 5 strong claims with extensive elaboration. May need only 5 citations if the elaboration is reasoning rather than fact-claim. Manifestos and position pieces often work this way: a small number of central claims, deeply argued, with citations supporting the claims rather than every elaboration. + +The audit. Mark every falsifiable claim in the piece. For each claim, check: is it cited, is it identified as the writer's own analysis, or is it floating? Floating claims are the failure mode. Either cite, attribute to the writer, or cut. + +The over-citation failure. Some long-form pieces cite every sentence as if academic rigor were the goal. The result reads as a literature review, not a piece of editorial writing. Citations should support the argument, not perform credibility theater. + +--- + +## Source freshness + +Statistics older than 3 years for fast-moving topics need refresh or explicit acknowledgment. + +Fast-moving topics. Technology, marketing tactics, AI capabilities, software stacks, social platforms. A 2018 stat in a 2026 piece on these topics signals stale research unless the writer is citing it specifically as historical context. + +Stable topics. Behavioral psychology research, structural economics, mathematical results, established scientific consensus. A 2015 stat on these topics may be perfectly current. + +The acknowledgment pattern. When citing older data on a fast-moving topic deliberately, acknowledge it: "A 2018 survey, the most recent rigorous data on the question, found..." The acknowledgment signals the writer knows the data is old and chose to cite it anyway, with reasoning. + +The hidden-stale-data failure. Citing a "2024 study" that turns out to be a 2024 republication of 2019 data. Verify primary publication date before citing. + +--- + +## Inline vs endnote citations + +Two conventions for how citations appear. + +Inline links. The cited source appears as a hyperlink within the prose. Reader clicks to verify. Common in editorial long-form, content marketing whitepapers, and most web-published research reports. + +- Strength: keeps reader momentum; the prose flows without numerical interruptions. +- Weakness: harder to verify without leaving the page; less academically formal. + +Endnote-style citations. Numbered footnotes at the end of the piece, with each citation numbered in the prose. Common in academic-influenced research reports, policy whitepapers, and some long-form published with print-style conventions. + +- Strength: signals academic rigor; preserves the citation list for verification. +- Weakness: interrupts reading flow; readers rarely follow endnotes in web reading. + +The convention rule. Pick one and stay consistent within the piece. Mixing conventions (some claims inline-linked, some endnoted) reads as inconsistent. The choice depends on audience expectations: B2B technical research often expects endnotes; editorial whitepapers usually expect inline. + +Hybrid: inline + bibliography. Inline links throughout the piece plus a "sources" or "further reading" section at the end. Common compromise. Works well when the piece has both casual references and core sources. + +--- + +## The citation-laundering anti-pattern + +Citing other content marketing pieces as authoritative when the cited piece itself does not have primary support. + +The pattern. Piece A claims X with a citation. Piece B cites A as the source for X. Piece C cites B. The original claim X may have been weak, made-up, or misinterpreted; each successive citation amplifies the appearance of authority without adding verification. + +How it happens. A writer searching for support for a claim finds another content marketing piece making the same claim and links to it. The writer feels they have cited a source. The source is itself unsourced or weakly sourced. The chain of laundering can run several pieces deep. + +The cure. When citing, follow the chain back. If the cited piece does not have primary or authoritative-secondary support, do not cite it. Either find a primary source, or remove the claim, or attribute it as the writer's own observation. + +Why it matters in long-form. The reader is investing time. Citation laundering produces pieces that read as authoritative because of citation count but fall apart under verification. Readers who verify discover the laundering; readers who do not develop a slow-decaying trust in the writer. + +--- + +## The own-analysis citation + +When the writer is making a claim from their own analysis rather than citing a source, the claim should be visibly the writer's analysis with the analytical work shown. + +The pattern. "Looking at the data across [scope], the pattern that emerges is X." The pattern claim is the writer's; the data is cited; the analytical work is described. + +The discipline. Own-analysis claims still need defensibility. The writer should be able to defend, if challenged: where the data came from, how the analysis was performed, what alternative interpretations were considered. + +The hidden-claim failure. Sentences that read as fact ("The reality is that programmatic SEO is dying") without acknowledgment that the claim is the writer's interpretation. If the claim is contested, frame it as the writer's view; if the claim is empirical, cite a source. The hidden middle (claim presented as fact when it is interpretation) is where readers lose trust. + +--- + +## Quote attribution + +Long-form pieces often include quotes from named experts, executives, or practitioners. + +Verification. Every quote should be from a real person who actually said the words attributed to them. Hallucinated quotes (especially in AI-assisted long-form) are an ethical failure regardless of whether the position is plausibly something the named person might say. See `editorial-qa`'s fact-accuracy reference for the discipline. + +Context. Quotes work best when the person's role is identified, the context of the statement is clear (interview, public statement, prior writing), and the quote earns its place by saying something specific. + +The throwaway-quote failure. A generic quote ("Content is king," John Smith, CEO) that does not advance the argument. If the quote does not say something specific the prose alone cannot convey, cut it. + +--- + +## Citation in research reports specifically + +Research reports have particularly strict citation expectations because they are claiming primary research authority. + +- Methodology disclosed. Sample size, recruitment method, dates, instrument design. Without these, the research is not verifiable. +- Sample limits acknowledged. What the sample does and does not represent. A sample of 300 marketers in B2B SaaS does not represent "marketers"; the report should not claim it does. +- Statistical limits acknowledged. Confidence intervals, margins of error, significance tests where applicable. Reports presenting cherry-picked data points without distribution context are weak research. +- Original data made available. Where possible, the underlying data should be shareable for verification. Reports that hide the data behind the headline findings invite skepticism. + +--- + +## Methodology-level choices that stay in the public skill + +The source hierarchy and tier definitions, the citation-density principle, the freshness rule and acknowledgment pattern, the inline-vs-endnote convention rule, the citation-laundering anti-pattern, the own-analysis discipline, the quote-attribution rules, the research-report citation expectations. + +## Implementation choices that stay internal + +Specific citation management tools the team uses. Specific bibliography generators integrated with the team's writing system. Specific link-checking automation that catches dead links and stale data. Specific data-publication conventions for research reports the team produces. The team's own internal source-tier classification when sources are ambiguous. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/closing-patterns.md b/skills/long-form-content-frameworks/references/closing-patterns.md new file mode 100644 index 0000000..34995e0 --- /dev/null +++ b/skills/long-form-content-frameworks/references/closing-patterns.md @@ -0,0 +1,161 @@ +# Closing patterns + +Five closings that work, four that fail, and the underlying frame: the closing is the writer's last opportunity to leave the reader with something specific. Closings that do not leave anything specific signal a writer who ran out of energy, and the piece is remembered accordingly. + +Long-form pieces with strong closings get shared, get linked, get remembered. Pieces with throat-clearing closings disappear after the last subhead. The closing is one of the most consequential 200-400 words of any long-form piece, and one of the easiest places for writers to under-invest. + +--- + +## The underlying frame + +The closing has three jobs at once. + +1. Resolve the piece. Whatever the lede promised, the closing delivers (or acknowledges what was not delivered). +2. Leave the reader with something specific. A specific call, a sharpened framing, a question to consider. The reader should be different at the closing than they were at the lede. +3. Earn the reader's attention for next time. The closing is the reader's last impression. Readers who finish a piece with a strong closing think of the writer as someone who delivers; readers who finish a piece with a weak closing think of the writer as someone who runs out of energy. + +Closings that do all three are memorable. Closings that do none are forgettable. Closings that do one or two are common and produce pieces that are technically complete but emotionally flat. + +--- + +## Pattern 1: The specific call + +Shape. What should the reader do, decide, or change as a result of reading this. Concrete, not generic. + +Fits. Most long-form pieces. Particularly strong for problem-solution archetype, manifestos, decision-guide research reports, long-form tutorials. + +Worked example. A 5,000-word whitepaper on content distribution closes: "If your team is producing content faster than you can distribute it, the bottleneck is not your production rate. It is your channel-fit decisions. Audit one piece you shipped in the last quarter against the channel-fit framework. Find the one channel where the audience-content match was strongest but the piece never reached that channel. That gap is where the next quarter's distribution work should focus." + +Why it works. The reader has a specific action. The action is grounded in the piece's framework, so the framework keeps working after the reading is over. + +The discipline. The call must be specific to the piece. Generic calls ("rethink your content strategy") signal that the writer did not commit to a specific recommendation. + +--- + +## Pattern 2: The reframed thesis + +Shape. The opening claim restated with the weight the body has now earned, often inverted, sharpened, or made more specific. + +Fits. Layered-argument pieces. Whitepapers. Manifestos. Pieces where the body's evidence justifies a stronger version of the opening claim. + +Worked example. A whitepaper that opens "Most teams treating content marketing as a volume problem will continue to underperform" closes: "The volume problem is not actually a content problem. It is a strategy problem the team has chosen to express through content. Teams that solve the strategy problem produce less content and more value; teams that try to solve the strategy problem with more content produce more content and less value. The path forward is not better content production. It is harder strategy decisions." + +Why it works. The reframed thesis lands the argument with weight the lede could not have carried. The body has done the work; the closing collects the payoff. + +The discipline. The reframing must be earned by the body. Pieces that restate the lede unchanged are recapping; pieces that restate it with sharpened framing the body justifies are doing the closing's work. + +--- + +## Pattern 3: The open question + +Shape. The question this piece's findings raise but do not answer, framed as the next investigation. + +Fits. Research reports. Analytical whitepapers. Pieces where the writer has gone as far as the available evidence allows but the topic continues. + +Worked example. A research report on AI search citation patterns closes: "The data is clear that statistics with named sources earn citations at 4x the rate of unsourced claims. The data does not tell us why. The hypothesis worth testing in the next research cycle: do AI engines weight named sources because they are training on a corpus that itself weights named sources, or because the engine providers have built explicit credibility-weighting into the retrieval logic? The answer matters because the answer changes how content programs should respond." + +Why it works. The reader is left with intellectual momentum. The piece does not pretend to have answered everything; it acknowledges what it did not answer and frames that as productive rather than as a limit. + +The discipline. The open question must be a real question, not a rhetorical one. "What does the future hold?" is rhetorical filler. "Is the citation pattern downstream of the training corpus or of explicit retrieval logic?" is a real question. + +--- + +## Pattern 4: The personal reflection + +Shape. The writer's stake in the topic surfaced briefly. What the writer thinks the piece illustrates beyond its specific argument. + +Fits. Manifestos. Opinionated long-form. Pieces where the writer has personal authority on the topic. Some case studies where the writer was personally involved. + +Worked example. A manifesto on content marketing's drift toward generic AI-assisted output closes: "I have been writing about content for a decade. The pattern that worries me is not that AI is involved; the pattern that worries me is that teams have stopped noticing when their content stopped sounding like them. The discipline this piece argues for is not anti-AI. It is pro-craft. The teams holding the line on craft will be readable in five years. The teams not holding the line will not be." + +Why it works. The personal stake adds weight to the argument. The writer's investment in the topic is the closing's payoff: the reader sees that the argument is not abstract for the writer. + +The discipline. The personal reflection must be earned by the writer's actual position. Personal reflections from writers without a real stake feel performed. + +--- + +## Pattern 5: The provocation + +Shape. A challenge to the reader, the field, or the consensus. Often paired with a refusal to soften the position. + +Fits. Manifestos. Position pieces. Long-form criticism. Pieces where the writer is staking out an unpopular or contested position deliberately. + +Worked example. A manifesto on programmatic SEO closes: "The teams that will survive the next three years of search-algorithm pressure are the ones that stop treating programmatic as a volume strategy and start treating it as a depth strategy. Most programmatic operations will not make this change. They will not survive. This piece is for the few that will." + +Why it works. The provocation establishes that the writer means it. The reader either accepts the provocation and reads the piece as a call to action, or rejects it and reads the piece as wrong; either response is engaged. The middle response (mild interest, no engagement) is what kills long-form's reach. + +The discipline. The provocation must be defensible. Provocations the body did not actually argue for read as posturing. Provocations the body argued for and the closing committed to with conviction read as serious. + +--- + +## Failure 1: The recap closing + +Shape. "In this piece, we covered X, Y, Z. As we have seen, content is important and only getting more so..." + +Why it fails. Signals the writer ran out of energy. Recap is what the table of contents does; the closing should add weight, not summarize. Readers who just spent 30 minutes reading do not need the recap; they need the writer to land the argument. + +The cure. Cut the recap. Replace with one of the five working patterns. The closing is not a tour through what the piece said; it is the writer's final position. + +--- + +## Failure 2: The "more research is needed" closing + +Shape. Most research reports default to "More research is needed in this area" as a closing. + +Why it fails. Signals the writer did not commit a position even when the data warranted one. "More research is needed" is the default closing of academic papers because academic papers have specific norms about hedging; editorial long-form does not have those norms, and the default reads as evasive. + +The cure. If the data does support a position, commit the position. If the data does not support a position, frame the closing as an open question (Pattern 3) rather than a generic call for more research. + +--- + +## Failure 3: The throat-clear closing + +Shape. "As we have seen, [topic] is important. Going forward, [generic platitude about the topic continuing to evolve]. Teams that [generic recommendation] will be best positioned to [generic outcome]." + +Why it fails. Delivers no payload. Every word could appear in any other piece on the same topic. The reader's response is "I read 5,000 words for this?" + +The cure. Strip the closing of every generic phrase. What is left is usually nothing; rewrite from scratch with one of the working patterns. + +--- + +## Failure 4: The CTA-as-closing + +Shape. The closing is "Book a demo with us today" or "Sign up for our newsletter" or "Download the full report." + +Why it fails. Breaks the editorial contract. Long-form readers who reached the closing have invested 30+ minutes in editorial content; pivoting to a sales call reads as bait-and-switch. Trust is damaged. + +The cure. If a CTA belongs in the piece, place it after the closing, visually distinct, framed as an offer rather than as the closing itself. The piece's editorial closing does its work first; the CTA appears afterward as a separate element. + +--- + +## The closing audit + +A short framework for auditing a draft closing. + +1. Does the closing leave the reader with something specific to do, decide, or think about? If not, rewrite. +2. Could this closing appear at the end of any other piece on this topic? If yes, the closing is generic. Rewrite to be specific to this piece. +3. Does the closing have approximate weight to the piece? A 5,000-word piece with a 50-word closing under-invests; a 1,500-word piece with a 600-word closing over-invests. +4. Read the closing aloud. Does it have energy? Closings that read as tired signal the writer was tired. The reader registers the energy. Rewrite when fresh. +5. Does the closing match one of the five working patterns? If it matches one of the failure patterns, rewrite using a working pattern. + +--- + +## When to write the closing first + +Some long-form writers write the closing first and write the body toward it. + +The argument for closing-first. Knowing where the piece lands clarifies what the body needs to argue. Writers who draft the body without knowing the closing often discover at the closing that the body did not actually support the planned closing, and have to rework substantial sections. + +The argument against closing-first. Some pieces' closings emerge from the body's argument; predetermining the closing constrains where the body can go. Research reports particularly may benefit from following the data and writing the closing once the analysis is complete. + +The middle path. Draft a target closing before writing the body. Revisit the target after the body draft. The target may stand, or the body may have produced a stronger closing than the target predicted. + +--- + +## Methodology-level choices that stay in the public skill + +The five working patterns and the four failure patterns, the underlying frame, the closing audit, the closing-first discussion, and the CTA-vs-editorial-closing distinction. + +## Implementation choices that stay internal + +Specific draft-review tooling that flags closing patterns. Specific style guides on closing length and weight in the team's editorial system. Specific A/B testing of closing variants for engagement metrics. Specific conventions for whether and where CTAs appear after closings. These vary by team, audience, and analytics setup. diff --git a/skills/long-form-content-frameworks/references/common-long-form-failures.md b/skills/long-form-content-frameworks/references/common-long-form-failures.md new file mode 100644 index 0000000..2310a3b --- /dev/null +++ b/skills/long-form-content-frameworks/references/common-long-form-failures.md @@ -0,0 +1,179 @@ +# Common long-form failures + +Eleven-plus failure patterns with diagnoses and cures. The patterns appear repeatedly across long-form drafts, regardless of topic, format, or writer experience. Diagnosing them early saves the rewrite work that catches them late. + +The pattern across most failures: writers reaching for length without doing the structural work that justifies it, and writers under-investing in the structural decisions that make long-form land. + +--- + +## Failure 1: Bloggy-long + +Symptom. A 5,000-word piece reads as a 1,500-word piece stretched. Padding paragraphs. Recap sections. "Before we get into it" preludes. Bullet expansions of single ideas. The reader notices within 600 words and skims. + +Diagnosis. The writer chose length first and structural depth second. The piece needed to be longer than 1,500 words for SEO or marketing reasons but did not have 5,000 words of substantive content. + +Cure. Two options. Cut to actual substantive length (often 1,800-2,500 words). Or expand the structural depth: add original analysis, primary research, case study specificity, or comparative dimensions that justify the length. + +Prevention. Choose length based on substantive content, not based on competitor length or SEO targets. SEO algorithms are getting better at detecting padded length; the strategy of "outranking by being longer" is increasingly counterproductive. + +--- + +## Failure 2: Academic-bloat + +Symptom. A 7,000-word whitepaper that is exhaustive but loses the thread. Every adjacent topic surveyed. Every definition restated. Every caveat documented. Reader respects the effort and skims for the parts they need. + +Diagnosis. The writer aimed for comprehensiveness rather than for argumentative load. The piece treats inclusion as the metric instead of treating each section's contribution as the metric. + +Cure. Apply the section-weight audit: which sections are actually load-bearing, which are surveying. Cut surveying sections that do not support specific claims in the load-bearing sections. Often takes 7,000 words to 4,500 with the argument intact. + +Prevention. Outline the argument before drafting. Each section should answer: what does this section contribute to the argument? If a section's answer is "comprehensive coverage" rather than a specific contribution, question whether the section earns its place. + +--- + +## Failure 3: Throat-clearing lede + +Symptom. The lede took 800 words to get to the thesis. Multiple paragraphs of "content marketing has changed dramatically" before the piece's actual claim appears. + +Diagnosis. The writer was warming up. Drafts often have throat-clearing ledes; finished pieces should not. + +Cure. Cut the first 400-700 words of the lede. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clearing draft. + +Prevention. After drafting, ask: where does the piece's specific argument actually start? Whatever appears before that point is throat-clearing and can usually be cut. + +--- + +## Failure 4: Even-section padding + +Symptom. All H2s come within 10% of each other in word count. Each section running 800-1,000 words regardless of its argumentative load. + +Diagnosis. The writer treated section length as a quota. Long sections were padded; short sections were either padded or not deepened. + +Cure. Identify which sections are actually load-bearing. Let them grow. Cut filler from non-load-bearing sections. + +Prevention. Plan section weights in the outline based on argumentative load, not on parallel structure. Allow 2x or 3x weight differences between sections doing different amounts of work. + +--- + +## Failure 5: Mid-piece sag + +Symptom. The piece sags around the 60% mark. Reader-attention analytics show drop-off at this point. + +Diagnosis. Standard mid-piece attention dip, untreated. No micro-thesis, no rhythm variation; the reader is exhausted from sustained density. + +Cure. Add a mid-piece micro-thesis at the section boundary nearest the midpoint. Insert a breathing section (anecdote, illustration, or reflective moment) into a stretch of argument-tight prose. Vary visual rhythm in the mid-piece section. + +Prevention. During outlining, mark the midpoint and plan the micro-thesis explicitly. During drafting, audit the middle third for rhythm variation. + +--- + +## Failure 6: Recap closing + +Symptom. The closing repeated the introduction. "In this piece we covered X, Y, Z. As we have seen, content is important..." + +Diagnosis. The writer ran out of energy. The closing was drafted last, in fatigue, and it shows. + +Cure. Rewrite the closing using one of the five working patterns: specific call, reframed thesis, open question, personal reflection, or provocation. + +Prevention. Write the closing first, or revise the closing last with fresh attention. Closings deserve disproportionate effort because they are disproportionately consequential. + +--- + +## Failure 7: Citation laundering + +Symptom. Citations are mostly other content marketing pieces rather than primary or authoritative-secondary sources. + +Diagnosis. The writer searched for support for claims and found other content marketing pieces making the same claims. Citing them feels like sourcing; it is not. + +Cure. Follow each citation chain back to the original. If the chain ends at a primary source, cite the primary source. If the chain ends at unsourced or weakly sourced content marketing, either find a primary source for the claim or cut the claim. + +Prevention. Default to Tier 1-3 sources (primary research, authoritative secondary, industry-credible). Only cite Tier 4 sources for color and context, never for argumentative load. + +--- + +## Failure 8: Visual-count overrun + +Symptom. The piece commissioned 12 charts. The team is exhausted from production. Six months later, charts are stale because nobody updated them. Traffic is the same as it would have been with 4 charts. + +Diagnosis. Visual count exceeded production capacity and earned-position discipline. + +Cure. Cut to the visuals that bear argumentative load the prose alone cannot. Update them on a maintainable cadence. Future pieces budget visuals against capacity rather than against ideal-world maximalism. + +Prevention. Apply the MVP-visuals approach: which visuals are load-bearing, which would be nice to have, which would be decoration. Ship the load-bearing ones first; add others only if capacity permits. + +--- + +## Failure 9: Generic case study + +Symptom. The case study has no specifics. "A leading enterprise SaaS company" rather than the company name. "Significant revenue growth" rather than the actual percentage. "Several months" rather than the timeline. + +Diagnosis. The case study format failed at its primary tax: specificity. Either the case was too confidential to share specifics, or the specifics were never gathered. + +Cure. Get specifics. Negotiate with the customer for what can be shared. If specifics genuinely cannot be shared, abandon the case study format and write a different format (general thought-leadership piece on the lessons learned, with the specific case relegated to background). + +Prevention. Do not commit to the case study format until specifics are confirmed shareable. Generic case studies fail the format and are less valuable than honest pieces about the lessons without claiming case-study authority. + +--- + +## Failure 10: Diplomatic manifesto + +Symptom. The manifesto reads as diplomatic. "Both sides have valid points." "The answer probably lies somewhere in the middle." Hedge stacking on positions that should be specific. + +Diagnosis. The writer chose the manifesto format but could not commit to the conviction the format requires. Often reflects organizational risk-aversion: the manifesto's bold framing was approved but its actual conviction was edited out. + +Cure. Either rewrite to commit a position (the format demands it), or change the format. A diplomatic position paper that is not pretending to be a manifesto is fine; a manifesto that hedges is broken. + +Prevention. Before committing to the manifesto format, confirm the writer (and the organization) actually has a contested position to argue. If hedging is required, write a different format. + +--- + +## Failure 11: Definitive guide with gaps + +Symptom. The "definitive" guide has obvious sub-topic gaps that the audience would notice. The piece claims comprehensiveness but does not deliver it. + +Diagnosis. The format implies coverage that the piece does not have. Either the gaps reflect topics the writer did not cover deliberately (and should have flagged), or the writer did not realize the gaps existed. + +Cure. Either fill the gaps or rename the piece. "The definitive guide to X" with gaps is broken; "A practitioner's guide to X" with the same content but without the comprehensiveness claim is fine. + +Prevention. Before claiming definitive-ness, audit against the audience's likely sub-topic expectations. Confirm coverage or change the framing. + +--- + +## Failure 12: Wrong archetype + +Symptom. The piece is fighting itself. The writer is trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. The reader senses the structural friction even when they cannot articulate it. + +Diagnosis. Archetype-format mismatch or archetype-topic mismatch. The writer chose an archetype that does not fit the work. + +Cure. Identify the natural archetype for the topic and the format. Restructure. This is often a substantial revision because the archetype is the spine; changing it changes how sections fit together. + +Prevention. Choose archetype before drafting. Confirm the archetype fits the format and the topic. Do not commit to draft until the archetype-format-topic combination is coherent. + +--- + +## Failure 13: Format-tax unpaid + +Symptom. The piece is published in a long-form format but does not pay the format's specific tax. A whitepaper without original synthesis. A research report without primary research. A long-form tutorial with broken steps. + +Diagnosis. The writer reached for the format's authority without paying the cost the format demands. + +Cure. Either pay the tax (do the original work the format requires) or change the format. A piece published in the wrong format reads as a category error to readers familiar with the format. + +Prevention. Confirm the format-tax is payable before committing to the format. Format choice is a downstream decision from "what work is the team prepared to do." + +--- + +## The cross-cutting pattern + +Most long-form failures share a single root: the writer chose length, format, or visual ambition first, and chose the structural and substantive depth second. The pieces that read as publication-quality are the ones where the inverse choice is made: substantive depth first, then length, format, and visual ambition follow from the depth. + +The fix for almost any long-form failure starts with the same audit: what is the piece actually doing, what is each section actually contributing, what does the format require, what does the topic need? When those questions get clear answers, the piece either earns its length or shrinks to a length that fits its substance. + +--- + +## Methodology-level choices that stay in the public skill + +The thirteen-plus failure patterns with diagnoses and cures, the cross-cutting pattern that connects most of them, the prevention discipline. + +## Implementation choices that stay internal + +Specific draft-review checklists the team uses. Specific failure-pattern detection in the team's editing tools. Specific reviewer training on the patterns. Specific case-study negotiation templates for getting customer specifics. The team's own conventions for archetype-format fit confirmation. These vary by team, format mix, and tooling. diff --git a/skills/long-form-content-frameworks/references/format-decision-framework.md b/skills/long-form-content-frameworks/references/format-decision-framework.md new file mode 100644 index 0000000..c624e14 --- /dev/null +++ b/skills/long-form-content-frameworks/references/format-decision-framework.md @@ -0,0 +1,139 @@ +# Format decision framework + +When each long-form format fits, what reader contract it implies, and the format-specific taxes that distinguish credible work from filler dressed in the format's clothes. + +Format selection is the first long-form decision. The wrong format produces predictable failure: a thinly-researched whitepaper reads as a blog post in formal clothing; a manifesto written diplomatically reads as a position paper that committed nothing. Each format has a reader contract. Failing the contract is what readers detect even when they cannot articulate why a piece is not landing. + +--- + +## Case study + +Reader contract. "Show me what worked, what did not, and the specifics that let me apply lessons to my own situation." + +Length norm. 2,000 to 4,000 words. Shorter feels like a marketing snippet; longer feels padded unless the case is unusually rich. + +Structural archetype tendency. Problem-solution, sometimes narrative arc. + +Format-specific tax. Specifics. Real company names (or, where confidential, well-disclosed anonymization with enough context to verify the case is real). Real numbers. Real timelines. Real failures alongside successes. Generic case studies that read like marketing collateral fail because the format's value proposition was specificity. + +Common failures. Anonymized to the point of meaninglessness ("a leading enterprise SaaS company saw 3x growth"); uncritical success narrative with no failures or surprises; missing methodology (what was measured, how, over what period); no reflection (what would the team change, what limits the lesson's applicability). + +When the format does not fit. When the case is too thin to support 2,000+ words of specificity, write a short customer story instead. When the case is so confidential that real numbers cannot be shared, the case study format is the wrong choice. + +--- + +## Whitepaper + +Reader contract. "Take me through your reasoning on this question with the rigor I would expect from a serious source. Make an argument I have not seen elsewhere." + +Length norm. 3,000 to 8,000 words. + +Structural archetype tendency. Layered argument or comparative analysis. + +Format-specific tax. Original synthesis. A whitepaper that surveys what other sources already said is not a whitepaper; it is a literature review. The whitepaper format implies the writer is contributing analysis, framing, or synthesis the reader cannot find elsewhere. + +Common failures. Survey of the field with no original argument; vendor-thinly-disguised pitch document; methodological hand-waving on the data the argument rests on; conclusion that hedges the position the introduction stated. + +When the format does not fit. When the writer does not have an original synthesis to contribute, write a different format. A survey-style "state of the industry" report is a research report, not a whitepaper. A vendor pitch is a pitch deck, not a whitepaper. Calling either a whitepaper to borrow the format's authority is the genre-mismatch failure mode. + +--- + +## Research report + +Reader contract. "Show me the data, how you collected it, what it means." + +Length norm. 4,000 to 12,000 words. Often longer when methodology and full data appendices are included. + +Structural archetype tendency. Taxonomic survey or comparative analysis. + +Format-specific tax. Actual primary research. Survey data with disclosed methodology, sample sizes, dates, and limits. Interview data with sample composition disclosed. Original quantitative work the writer did or commissioned. Citing other firms' research and calling the result a research report fails the contract. + +Common failures. "We surveyed 300 marketers" with leading questions and no methodology disclosure; cherry-picked data points presented without distribution or variance; methodology paragraph that gestures at rigor without delivering it; findings overstated relative to the sample's actual representativeness. + +When the format does not fit. When primary research budget is unavailable. Calling a literature synthesis a research report is genre fraud; write a whitepaper or a definitive guide instead. + +--- + +## Definitive guide + +Reader contract. "Be the canonical resource on this topic for the audience the piece names." + +Length norm. 4,000 to 10,000 words. + +Structural archetype tendency. Taxonomic survey. + +Format-specific tax. Actual comprehensiveness. A definitive guide that has obvious topic gaps fails the format. The audience the piece names matters: a definitive guide for senior practitioners and a definitive guide for newcomers are different pieces; trying to be definitive for both audiences usually fails both. + +Common failures. Comprehensive on the easy parts of the topic, thin on the hard parts; outdated when published because the format suggests timeless authority but the topic moves quickly; not actually definitive because key sub-topics are missing or treated as out-of-scope without justification. + +When the format does not fit. When the topic is too broad for a single piece to cover canonically (then write a hub: see `pillar-content-architecture`). When the topic is so specialized that "definitive" is a category of one and the format's value disappears. + +--- + +## Manifesto + +Reader contract. "Tell me what you believe, why, and convince me. Take a position I can argue with." + +Length norm. 1,500 to 6,000 words. + +Structural archetype tendency. Layered argument or narrative arc. + +Format-specific tax. Conviction. The manifesto format demands the writer commit a position with weight. Diplomatic hedging produces a piece that reads as a manifesto in form but a position paper in substance. Readers detect the gap. + +Common failures. "Both sides have valid points" framings that the manifesto format does not support; hedge-stacked claims ("typically", "generally", "often") on positions that should be specific; closing that walks back the opening's strength; fear of alienating audience segments producing a piece that alienates everyone by committing to nothing. + +When the format does not fit. When the writer does not actually have a contested position to argue. Calling a survey of consensus views a manifesto is a category error. Write a whitepaper or a position paper if hedging is required. + +--- + +## Ebook + +Reader contract. "Take me through a body of work as a sequence of related pieces." + +Length norm. 8,000 to 30,000+ words across multiple chapters. + +Structural archetype tendency. Narrative arc across chapters, with each chapter using its own archetype. + +Format-specific tax. Each chapter earns its place. A 12-chapter ebook with 3 chapters that should have been cut signals the format was reached for to add length, not because the work justified the format. Table of contents reading reveals the discipline: are the chapters distinct contributions, or is the ebook one argument padded into 12 pieces? + +Common failures. Repetitive chapters covering the same ground from slightly different angles; introduction and conclusion that are throat-clearing rather than load-bearing; missing connective tissue between chapters that leaves the reader uncertain how the chapters fit; no reason for the work to be an ebook rather than a long-form whitepaper. + +When the format does not fit. When the work fits in 6,000 words. Stretching a long-form whitepaper to ebook length usually weakens it. Write the long-form whitepaper. + +--- + +## Long-form tutorial + +Reader contract. "Take me from where I am to where I want to be, step by step, and make sure every step works." + +Length norm. 3,000 to 8,000 words. + +Structural archetype tendency. Problem-solution with sequential steps. + +Format-specific tax. Every step works. Long-form tutorials fail catastrophically when one step is broken: the reader stops there, cannot continue, and the rest of the tutorial is wasted. The tutorial-tax is verification that each step in the sequence delivers the result the next step assumes. + +Common failures. Skipped steps that were obvious to the writer but blocking to the reader; outdated steps that worked when written but no longer (especially common with tutorials referencing fast-moving tools); broken sequences where step 6 assumes a configuration step 4 did not actually create. + +When the format does not fit. When the topic does not have a clean sequential path. Branching tutorials where the path varies by reader context are usually better as a hub of shorter pieces (see `pillar-content-architecture`) than as one long-form tutorial trying to handle every branch. + +--- + +## The format-fit decision + +A short framework for choosing. + +1. What is the reader contract? What is the reader investing 30+ minutes to get? Specifics (case study)? Original analysis (whitepaper)? Original data (research report)? Comprehensive coverage (definitive guide)? Conviction (manifesto)? A body of work (ebook)? Sequential instruction (long-form tutorial)? +2. Can the team pay the format-specific tax? If the format demands specifics and the case is too confidential to share specifics, the format does not fit. If the format demands conviction and the writer wants to hedge, the format does not fit. +3. Is there an original contribution? Whitepapers, manifestos, and research reports particularly require original contribution. Definitive guides and tutorials can be valuable as comprehensive synthesis without original argument. +4. Does the audience expect this format? Some audiences expect whitepapers (B2B technical), some manifestos (founder-led brands), some research reports (analyst-influenced markets). Format choice signals genre-fit to the audience. +5. Is the production capacity available? Long-form tutorials with verified sequential steps cost meaningful verification time. Research reports cost primary-research budget. Format choice must match capacity, or the format-tax goes unpaid and the piece reads as the format-it-pretended-to-be. + +--- + +## Methodology-level choices that stay in the public skill + +The seven format definitions and their reader contracts. The format-specific taxes that distinguish credible work from filler dressed in the format. The decision framework that matches format to work. The genre-mismatch failure modes. The when-the-format-does-not-fit handling. + +## Implementation choices that stay internal + +Specific case study templates the team uses. Specific whitepaper layouts in the brand's design system. Specific research-report data presentation conventions matching the team's design tokens. Specific PDF production tooling. Specific gating workflow integrations with the team's marketing automation. Specific tutorial step-verification scripts that match the stack the tutorials cover. These vary by team, brand, and tooling; methodology applies regardless. diff --git a/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md b/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md new file mode 100644 index 0000000..0e357f1 --- /dev/null +++ b/skills/long-form-content-frameworks/references/lede-patterns-for-long-form.md @@ -0,0 +1,148 @@ +# Lede patterns for long-form + +Five patterns that work, four that fail, and the underlying frame: the first paragraph of a long-form piece is the writer's only sales pitch for the next 30+ minutes of the reader's attention. + +Long-form ledes do different work than blog-post ledes. A blog-post lede answers the user's likely query in the first 200 words for SEO. A long-form lede earns attention for the time investment ahead. Both can be true at once (an SEO-driven long-form piece needs to do both), but the long-form discipline is the harder of the two: the lede that answers a query in 200 words is not necessarily the lede that earns 30 minutes of reader attention. + +--- + +## The underlying frame + +Treat the first 150-250 words of a long-form piece as the writer's pitch to the reader. The reader is deciding, paragraph by paragraph, whether the time investment is going to be worth it. The lede has to: + +- Establish that the writer has something specific to say (not a survey). +- Set the thesis or central question the body will deliver. +- Earn enough attention to get the reader past the first H2. + +If the lede does not do these three things, readers leave at the first H2 boundary, before the body has a chance to deliver. + +--- + +## Pattern 1: The contested-claim opener + +Shape. A surprising or contested position stated cleanly, then the rest of the piece argues for it. + +Fits. Manifestos. Opinionated whitepapers. Position pieces. Long-form analysis where the writer has a specific view. + +Example shape. "Most teams treating content marketing as a volume problem will continue to underperform their budget through the end of the decade. The discipline that produces durable content programs is the one most teams skip: deciding what NOT to publish." + +Why it works. The reader's response is "wait, why?" The piece exists to answer that. The contested claim earns the reader's attention because the reader is now invested in seeing whether the argument holds. + +The discipline. The contested claim must actually be defensible across the piece. Lede claims that the body fails to support produce broken contracts; readers feel deceived. + +--- + +## Pattern 2: The problem-with-stakes opener + +Shape. A problem stated with the stakes made tangible. The reader sees themselves or their situation in the problem and wants the solution. + +Fits. Case studies. Problem-solution pieces. Long-form tutorials. Manifestos with a clear opposition. + +Example shape. "Three months after the migration, organic traffic was down 38%, the team had spent four hundred hours on the project, and nobody could explain where the loss was coming from. The migration had been planned for six months. Every checklist item had been completed. And the search-console graph was still pointing the wrong direction." + +Why it works. Stakes ground the abstract. The reader feels the problem before reading any solution, which earns attention for the solution that follows. + +The discipline. The stakes must be real, not invented for dramatic effect. Inflated stakes ("the future of marketing is at stake") read as filler. Specific stakes ("the migration cost $400K and three quarters of trust with the executive team") read as honest. + +--- + +## Pattern 3: The data-anomaly opener + +Shape. A piece of data that does not fit the consensus, framed as the question the piece will answer. + +Fits. Research reports. Analytical whitepapers. Evidence-driven long-form. + +Example shape. "The median programmatic SEO program in 2025 generated more than 80% of its traffic from fewer than 5% of its pages. The pattern held across e-commerce, B2B SaaS, marketplaces, and travel. This piece is about why." + +Why it works. The data point creates a specific question. The reader wants the answer. The body's job is to deliver the answer with the analytical depth the question deserves. + +The discipline. The data point must be load-bearing. If the body's argument does not actually flow from the opening data, the lede was decoration rather than scaffolding. + +--- + +## Pattern 4: The scene opener + +Shape. A specific moment, person, or scene that grounds the abstract topic. The reader enters the piece through a concrete situation, and the abstract argument follows. + +Fits. Narrative-arc pieces. Magazine-style longform. Pieces where human stakes are part of the argument. Some manifestos. + +Example shape. "On a Tuesday morning in September 2024, two engineers stood in front of a whiteboard covered in arrows and tried to explain to the new VP what the data pipeline actually did. The VP had been at the company three weeks. The whiteboard had been there four years. Neither of them could finish a sentence without contradicting the other." + +Why it works. Specific scenes hold attention. Readers complete narrative-arc pieces at higher rates than other archetypes; the scene opener uses that pull from the first paragraph. + +The discipline. The scene must connect to the piece's argument. Scene openers that are decorative ("imagine you are a marketer in 2026...") rather than load-bearing waste reader attention on prelude. + +--- + +## Pattern 5: The orientation opener + +Shape. What this piece covers, who it is for, what reading it costs and what it delivers. Orientation, not throat-clearing. + +Fits. Definitive guides. Long-form tutorials. Reference-type long-form where the reader's first question is "is this the right resource for me." + +Example shape. "This guide is for engineering leaders deciding whether to migrate from a service mesh to a sidecar-less alternative. It assumes familiarity with Kubernetes and basic mesh concepts. Reading it costs about 30 minutes. It will not cover the original arguments for adopting a mesh; that is a different question. It will cover the migration decision: when it makes sense, what to expect, what fails." + +Why it works. Reference-type readers self-select on relevance. The orientation opener saves the wrong reader's time and earns the right reader's attention. Pieces that the right reader does not finish often fail because the wrong readers came in and the right readers left. + +The discipline. The orientation must be honest. Guides that overpromise relevance ("for anyone interested in cloud infrastructure") draw wrong readers; guides that underpromise lose right readers. + +--- + +## Failure 1: The throat-clear opener + +Shape. "Content marketing has changed dramatically over the past decade. In this article, we will explore how to..." + +Why it fails. Filler signal. The reader knows the piece is about content marketing because of the title; restating it wastes attention. The "in this article we will explore" frame is a tour, not an argument; readers respond to arguments more than to tours. + +The cure. Cut the throat-clear paragraphs entirely. The piece's actual first sentence is usually the third or fourth paragraph of the throat-clear draft. + +--- + +## Failure 2: The dictionary-definition opener + +Shape. "According to Merriam-Webster, X is defined as..." + +Why it fails. Signals an unwillingness to commit a position. The reader assumes the writer does not have a specific framing of their own and is hiding behind the dictionary's framing. For long-form, this is fatal: long-form earns reader attention through specific framing. + +The cure. State the writer's framing. If the writer needs to disambiguate the term, do so in their own words after stating their position. + +--- + +## Failure 3: The history-of-the-topic opener + +Shape. Three or four paragraphs of background before the argument starts. + +Why it fails. Long-form readers tolerate background but only after they know why they should care. Front-loading background means the reader leaves before the thesis lands. The history-of-the-topic opener typically reflects the writer's research process leaking into the piece structure: the writer learned the history while researching, so they put it first, even though the reader does not need it first. + +The cure. Move history into the body where it supports specific claims. Lead with the thesis or the question the piece answers. + +--- + +## Failure 4: The "in this article we will discuss" tour opener + +Shape. "In this article, we will discuss A, then B, then C, then D, then conclude with E." + +Why it fails. Flattens the piece into an outline before the writer has earned attention. Tours signal a writer who is not confident the body will hold the reader, so they preview it. The preview itself is what loses the reader: outlines are less interesting than the argument they describe. + +The cure. Trust the body to deliver. If the piece needs a navigation aid, use a table of contents or jump links, not an opening tour. + +--- + +## The lede audit + +A short framework for auditing a draft lede. + +1. Does the first paragraph establish a specific position, problem, data point, scene, or orientation? If it does general throat-clearing instead, cut. +2. By the end of the first 250 words, has the thesis or central question of the piece been stated? If not, the lede is too long. +3. Does the lede earn the reader's next 30 minutes? Read the lede as a stranger to the topic. Would you keep reading? If you would skim, the lede is filler. +4. Does the body deliver on the lede's promise? Some failed ledes are technically fine but make promises the body does not keep. The audit happens after the body is drafted: does the lede's framing match what the piece actually argues? + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns and the four failures, the underlying frame, the lede audit, the format-tendency mapping, and the lede-body integrity discipline. + +## Implementation choices that stay internal + +Specific lede templates the team has built. Specific draft-review tooling that flags throat-clearing language patterns automatically. Specific A/B testing of lede variants against engagement metrics. The team's own conventions for lede-length norms within the bands. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/section-weight-calibration.md b/skills/long-form-content-frameworks/references/section-weight-calibration.md new file mode 100644 index 0000000..9a95f94 --- /dev/null +++ b/skills/long-form-content-frameworks/references/section-weight-calibration.md @@ -0,0 +1,128 @@ +# Section weight calibration + +How long sections should be relative to each other, varying by format. The audit pattern that catches structural imbalance, and the underlying principle that section weight should match argumentative load. + +Most long-form pieces fail at section weight before they fail at any other dimension. A 6,000-word whitepaper with seven sections of similar length signals that the writer treated each H2 as a quota rather than as an argument-bearing unit. The pieces that read as publication-quality are the ones where some sections breathe and others compress, where argumentative load is reflected in word count, and where filler sections were cut rather than evened out. + +--- + +## The underlying principle + +Section weight should match how much argumentative load the section is bearing. + +Throat-clearing introductions get cut or compressed. Setup sections that orient the reader without making the argument yet are short. Body sections that are doing the actual work of the piece are longest. Closings are specific and tight. When section weights deviate from this, the piece is either padded (sections doing too little for their length) or under-developed (sections doing too much for their length). + +The audit is straightforward. For each section, ask: what argumentative work is this section doing, and is the word count proportional to that work? Sections doing little work that take up much space are filler. Sections doing much work that take up little space are under-developed. + +--- + +## Whitepaper / research report typical weights + +For a 5,000-word whitepaper or research report. + +- Introduction. 8-12%. Roughly 400-600 words. Thesis stated, scope set, why the piece exists. +- Methodology or framing. 10-15%. Roughly 500-750 words. How the analysis works, what data the argument rests on, what the reader should know about how the writer arrived at the position. +- Body. 60-70%. Roughly 3,000-3,500 words. Divided into 3-5 weighted sections. The actual argument or findings. The largest body sections are the load-bearing ones; smaller body sections support or transition. +- Implications. 10-15%. Roughly 500-750 words. What the argument means for the reader's situation. +- Closing. 3-5%. Roughly 150-250 words. Specific call, reframed thesis, or open question. + +--- + +## Case study typical weights + +For a 3,000-word case study. + +- Setup and context. 15-20%. Roughly 450-600 words. The company, the problem, why the problem mattered, what was at stake. +- Solution narrative. 50-60%. Roughly 1,500-1,800 words. What the team did, in sequence, with the decision points that mattered. +- Outcomes. 15-20%. Roughly 450-600 words. Quantified results, what worked beyond expectations, what did not work as planned. +- Reflection. 5-10%. Roughly 150-300 words. What the team would change, what limits the case's applicability. + +The case-study weight discipline. The setup and the outcomes can be roughly even; the solution narrative is the longest section because it is doing the most work; the reflection is short because it is concentrated honest assessment. + +--- + +## Manifesto typical weights + +For a 3,500-word manifesto. + +- Position. 5-10%. Roughly 175-350 words. What is believed, stated early and clearly. Manifestos that bury the position lose readers before the argument starts. +- Argument. 70-80%. Roughly 2,450-2,800 words. Why, with the layers building intensity. The argument's later layers should be more intense, more specific, or more confrontational than the earlier layers; intensity that flattens loses momentum. +- Call. 10-15%. Roughly 350-525 words. What should change as a result of accepting the position, who should change it, what the writer asks of the reader. + +The manifesto weight discipline. Position is short and load-bearing. Argument is long and intensifies. Call is specific and demands action or position-taking from the reader. + +--- + +## Definitive guide typical weights + +For a 7,000-word definitive guide. + +- Introduction. 5-8%. Roughly 350-560 words. What the guide covers, who it serves, what reading it costs and pays. +- Body across taxonomic sections. 80-85%. Roughly 5,600-5,950 words. Each category in the taxonomy treated with parallel structure. The categories should be roughly even in length unless the taxonomy itself implies asymmetry (some categories are more important than others). +- Closing and additional resources. 7-10%. Roughly 490-700 words. Synthesis, recommendation about which categories matter most, pointers to next steps. + +The definitive-guide weight discipline. Most of the weight is in the body categories. The introduction is short because the guide's value is in the taxonomy treatment, not in extended setup. The closing's value is synthesis, not recap. + +--- + +## Long-form tutorial typical weights + +For a 5,000-word long-form tutorial. + +- Setup. 10-15%. Roughly 500-750 words. What the reader will achieve, what they need to start, what the success state looks like. +- Sequential steps. 70-80%. Roughly 3,500-4,000 words. Each step its own subsection. Steps doing more work get more words; trivial steps stay short. The temptation to even out step lengths produces tutorials that feel padded on simple steps and rushed on hard ones. +- Troubleshooting and edge cases. 10-15%. Roughly 500-750 words. What goes wrong, what to do about it, when the reader has likely diverged from the success path. + +The tutorial weight discipline. Steps are weighted by actual difficulty, not by parallel structure. The troubleshooting section is load-bearing because tutorials fail at the failure-points; documenting them is the difference between a tutorial that works and one that strands readers. + +--- + +## Ebook typical weights + +For a 20,000-word ebook with 8 chapters. + +- Introduction. 3-5%. Roughly 600-1,000 words. Why the ebook exists, who it serves, how the chapters fit together. +- Each chapter. 10-13%. Roughly 2,000-2,600 words per chapter. Chapter weights can vary; a load-bearing chapter at the center may run 3,500 words while a transitional chapter runs 1,500. The variation should reflect actual content load, not arbitrary balancing. +- Closing chapter or synthesis. 5-8%. Roughly 1,000-1,600 words. What the body of work amounts to. + +The ebook weight discipline. Chapter weights match chapter load; introduction and closing earn their place by doing connective work the body chapters cannot. + +--- + +## The 3x audit + +A practical heuristic for catching section-weight problems. + +Compare any two sections bearing similar argumentative load. If one is more than 3x the length of the other, the piece is structurally unbalanced. Three responses: + +1. Split the long section. If the long section is genuinely doing 3x the work, it is probably actually two or three sections that should be separated for the reader's navigation. +2. Deepen the short section. If the long section's length is correct, the short section is probably under-developed and the argument it is making is being skipped. +3. Acknowledge the imbalance. If the asymmetry reflects an actual content reality (one category in the taxonomy genuinely matters 3x as much as another), the piece can keep the imbalance but should signal it to the reader so the structure does not feel arbitrary. + +--- + +## Common section-weight failures + +Patterns that show up repeatedly in long-form drafts. + +Even-section padding. All H2s come out within 10% of each other in word count. Signal: writer is treating section length as a quota. Cure: identify which sections are actually load-bearing and let them grow while cutting the filler ones back. + +Front-loaded setup. Introduction is 25% of the piece. Signal: writer was not confident enough in the thesis to commit it early; spent the first quarter of the piece warming up. Cure: cut the introduction by half, lead with the thesis. + +Body imbalance. One body section is 50% of the piece while three others are 10% each. Signal: either the long section is actually multiple sections that should be separated, or the short sections are filler that should be cut. + +Missing closing. Closing is 1-2% of the piece. Signal: writer ran out of energy. Cure: rewrite the closing to actual proportional weight; specific call, reframed thesis, or open question. + +Throat-clearing across sections. Each section starts with 100-200 words of "as we discussed in the previous section" before getting to the section's actual work. Signal: writer is over-managing reader navigation. Cure: trust the reader; cut the recap paragraphs. + +Bullet inflation. A section's word count comes mostly from bulleted lists where each bullet is one expanded sentence. Signal: writer is using bullets to inflate length without doing the integration work. Cure: rewrite the bullets as prose if the integration matters; cut to a tighter list if the items are genuinely parallel. + +--- + +## Methodology-level choices that stay in the public skill + +The underlying principle (weight matches argumentative load), the format-specific weight profiles, the 3x audit, the common section-weight failure patterns and their cures. + +## Implementation choices that stay internal + +Specific word-count tracking tools the team uses to audit drafts. Specific outline templates with weight targets per section in the team's writing system. Specific reviewer dashboards that surface section-weight imbalance for editorial review. The team's own conventions for which formats run shorter or longer than the typical bands. These vary by team and tooling. diff --git a/skills/long-form-content-frameworks/references/structural-archetype-patterns.md b/skills/long-form-content-frameworks/references/structural-archetype-patterns.md new file mode 100644 index 0000000..1e56d54 --- /dev/null +++ b/skills/long-form-content-frameworks/references/structural-archetype-patterns.md @@ -0,0 +1,145 @@ +# Structural archetype patterns + +Five archetypes that fit different long-form problems, with worked examples and the patterns for combining archetypes within a single piece. + +The archetype is the spine of a long-form piece. It determines how the argument unfolds, how the reader's attention is structured, and which structural moves feel natural versus which would jar. Selecting the wrong archetype produces a piece that fights itself: the writer trying to argue layered evidence inside a narrative arc, or to survey a taxonomy inside a problem-solution shape. + +--- + +## Archetype 1: Problem-solution + +Shape. State the problem with weight. Develop why it matters and who is affected. Present the solution. Show how it works in detail. Address objections. Close with implications. + +Fits. Case studies. Long-form tutorials. Manifestos with a clear opposition. Pieces where the writer has a specific recommendation and a specific framing of what the recommendation answers. + +Worked example: a 3,500-word case study. + +- Setup: the company, the problem, why the problem mattered (15-20% of the piece). +- The solution narrative: what the team did, in sequence, with the decision points that mattered (50-60%). +- Outcomes: quantified results, what worked beyond expectations, what did not work as planned (15-20%). +- Reflection: what the team would change, what limits the case's applicability (5-10%). + +Strengths. Direct, action-oriented, satisfies readers looking for "show me how to solve this." Clear forward momentum prevents reader drift. + +Risks. Feels formulaic when overused (every case study reading the same shape). Tempts oversimplification: real situations rarely fit a clean problem-solution arc, and forcing them to flattens the case's interest. + +--- + +## Archetype 2: Narrative arc + +Shape. Beginning establishing characters and stakes. Middle developing complications. End resolving (or refusing to resolve) the central tension. Time progresses; events follow each other. + +Fits. Ebooks across chapters. Some case studies, particularly founder stories, transformation cases, multi-year initiatives. Magazine-style longform. Manifestos where the writer's own journey is part of the argument. + +Worked example: a 6,000-word transformation case study. + +- Opening: a specific scene that grounds the abstract topic (the Monday-morning meeting where the problem became inescapable). +- Rising action: the situation getting worse before it gets better, the failed attempts, the false starts. +- Turning point: the specific decision or insight that shifted the trajectory. +- Resolution: what the new state looks like, what the team learned, what is still in progress. +- Coda: the writer's broader observation about what the story illustrates. + +Strengths. Most engaging archetype for sustained attention. Readers complete narrative-arc pieces at higher rates than other archetypes. Memorable; readers tell other readers. + +Risks. Forced narrative on topics that are not stories. A whitepaper trying to be a narrative arc usually fails because the topic does not naturally have characters, complication, and resolution. The forcing is detectable. + +--- + +## Archetype 3: Layered argument + +Shape. Position stated. Layer 1 evidence supporting the position. Layer 2 evidence, often deeper or addressing a different aspect. Layer 3, often counter-arguments or caveats. Synthesis tying the layers together. + +Fits. Whitepapers. Manifestos. Position pieces. Analytical long-form. Pieces where the writer is making a case that requires building support across multiple distinct kinds of evidence. + +Worked example: a 5,000-word whitepaper. + +- Position: the central claim, stated cleanly in the first 200 words (10%). +- Layer 1: the structural argument (why the position follows from how the system works). 25%. +- Layer 2: the empirical argument (what data supports the position). 25%. +- Layer 3: counter-arguments engaged seriously and answered. 20%. +- Synthesis: what the layers together imply, including implications the position-statement alone did not surface. 15%. +- Closing: specific call or reframed thesis. 5%. + +Strengths. Rigorous, defensible, persuasive to skeptical readers. Readers engaging seriously with the position find their objections engaged in the counter-argument layer. + +Risks. Feels academic if the synthesis is weak. Layers that do not actually build to a synthesis read as three separate articles stacked. The audit: cut one layer; does the synthesis still work? If yes, that layer was filler. + +--- + +## Archetype 4: Taxonomic survey + +Shape. A topic mapped into categories. Each category explored. Relationships among categories surfaced. Sometimes a recommendation about which categories matter most, often a synthesis about what the taxonomy reveals. + +Fits. Definitive guides. Research reports surveying a landscape. Long-form tutorials covering a topic with parallel rather than sequential structure. Comparative pieces. + +Worked example: a 7,000-word definitive guide. + +- Introduction: what the guide covers, who it serves, what reading it costs and pays (5-8%). +- Taxonomy framing: how the topic divides, why these categories rather than other possible categories (8-12%). +- Category 1, 2, 3, 4 (etc.): each treated with parallel structure (definition, examples, when-it-fits, how-it-works) so readers can navigate. 70-75% across all categories. +- Synthesis: what the taxonomy reveals about the topic as a whole; which categories the writer thinks matter most and why. 7-10%. +- Closing: what to do with the taxonomy. 3-5%. + +Strengths. Reference-friendly. Readers come back to taxonomic surveys multiple times to look up specific categories. SEO-friendly because each category often answers a discrete query. + +Risks. Feels like a list with subheads if the taxonomy is not actually load-bearing. The audit: does the taxonomy reveal something that a list of items would not? If no, the piece is a list pretending to be a taxonomy. + +--- + +## Archetype 5: Comparative analysis + +Shape. Multiple options, frameworks, or positions. Defined axes of comparison. Each option scored or characterized along each axis. Tradeoffs surfaced. The writer's recommendation argued. + +Fits. Whitepapers comparing approaches. Decision-guide research reports. Technology comparisons. Evaluations. Pieces where the reader's question is "which of these should I choose." + +Worked example: a 4,500-word technology comparison. + +- Setup: the decision the reader is making, why it matters, who this comparison serves (8-10%). +- Comparison axes: the dimensions the writer chose to compare on, with justification for why these axes (5-8%). +- Each option treated along the axes: parallel structure so readers can compare at-a-glance. 50-60%. +- Tradeoff synthesis: what the comparison reveals about which option fits which context. 15-20%. +- Recommendation: the writer's view, with the conditions under which the recommendation holds. 8-10%. +- Closing: how to decide. 3-5%. + +Strengths. Decision-useful. Readers facing the decision the comparison addresses get clear input. Pairs well with comparison tables and side-by-side data. + +Risks. Feels like a feature matrix if the analysis is shallow. The axes matter: shallow axes (price, speed, ease) produce shallow analysis. Deep axes (failure modes under load, what the platform optimizes for, what the platform forces you to give up) produce useful comparison. + +--- + +## Combination patterns + +Most strong long-form pieces use one archetype as the spine and borrow from another for variation. + +Layered argument with comparative-analysis sections. A whitepaper arguing a position with a comparative-analysis section showing how the position handles edge cases that competing positions do not. + +Taxonomic survey with problem-solution chapters. A definitive guide where each category in the taxonomy includes a problem-solution treatment of how to apply it. + +Narrative arc with layered-argument moments. An ebook where the narrative carries the reader through a transformation while individual chapters argue for specific positions encountered along the way. + +Problem-solution with taxonomic-survey frame. A long-form tutorial that introduces a taxonomy of failure modes and then walks through the solution sequentially. + +Comparative analysis with case-study illustration. A whitepaper comparing approaches with a case study embedded for one of the approaches to ground the analysis. + +The discipline. One archetype as spine; another as variation. Pieces using three archetypes simultaneously fragment; pieces using one archetype rigidly feel formulaic. + +--- + +## Selecting the archetype + +A short framework. + +1. What is the reader's relationship to the question? "Tell me how" suggests problem-solution. "Tell me what happened" suggests narrative arc. "Convince me" suggests layered argument. "Map the landscape" suggests taxonomic survey. "Help me decide" suggests comparative analysis. +2. What does the topic naturally have? Topics with a clear protagonist, complication, and resolution naturally fit narrative arc. Topics with parallel categories naturally fit taxonomic survey. Topics with a contested position naturally fit layered argument or manifesto-flavored layered argument. +3. What does the format expect? Case studies expect problem-solution or narrative arc; whitepapers expect layered argument or comparative analysis; definitive guides expect taxonomic survey. Format-archetype mismatch is detectable to readers even when they cannot articulate it. +4. What is the writer's strength? Different writers have different archetype strengths. A writer who naturally argues should not force themselves into narrative-arc longform; a writer who naturally narrates should not force themselves into taxonomic surveys. Assign archetype to writer skill where possible. + +--- + +## Methodology-level choices that stay in the public skill + +The five archetype shapes, the worked examples, the combination patterns, the selection framework, the format-archetype fit tendencies, the writer-skill matching consideration. + +## Implementation choices that stay internal + +Specific archetype templates the team has built for repeat formats. Specific section-length scaffolds the team uses. Specific document templates per archetype in the team's writing tool. Specific archetype tagging in the team's content calendar so editorial mix can be reviewed. The decision rubric the team uses for archetype assignment when multiple writers are working on the same format. These are team-specific operationalizations of the methodology. diff --git a/skills/media-asset-management/SKILL.md b/skills/media-asset-management/SKILL.md new file mode 100644 index 0000000..85511d5 --- /dev/null +++ b/skills/media-asset-management/SKILL.md @@ -0,0 +1,305 @@ +--- +name: media-asset-management +description: "Plan and run a media pipeline for images, video, and downloadable assets. Use this skill when designing image storage and delivery, choosing formats (WebP, AVIF), setting up responsive images, picking a video host, organizing a brand asset library, or auditing a slow image pipeline. Triggers on image pipeline, asset library, DAM, image optimization, WebP, AVIF, responsive images, video hosting, image CDN, asset workflow, media management. Also triggers when images are slow, broken, or scattered across systems." +category: operations +catalog_summary: "Image pipelines, video hosting, asset libraries, format selection" +display_order: 9 +--- + +# Media Asset Management + +Design how images, video, and downloadable files get stored, processed, organized, and served. Stack-agnostic. The principles apply whether you're running a custom pipeline or using a hosted service. + +--- + +## When to use + +- Designing or redesigning the image and media pipeline +- Choosing a media CDN or image service +- Setting up responsive image delivery +- Planning a digital asset management (DAM) system +- Auditing media performance issues +- Picking video hosting and embedding strategy +- Setting up workflows for designers and writers to upload assets +- Migrating media from one platform to another + +## When NOT to use + +- Performance optimization beyond media (use `performance-optimization`) +- Brand identity or photography direction (use `brand-identity`, `art-direction`) +- Content production strategy (use `content-strategy`) +- Single-image optimization (covered in `performance-optimization`) + +--- + +## Required inputs + +- Current media inventory: where assets live, in what formats +- Volume: how many assets, how much storage, how much traffic +- Sources: who creates and uploads media (designers, writers, automated tools) +- Platforms: where media is consumed (web, email, app, partners) +- Performance baseline: current image sizes, load times +- Budget reality: hosted services have monthly costs + +--- + +## The framework: 4 stages + +The media pipeline has four stages. Each has its own decisions. + +### Stage 1: Source + +Where assets enter the system. + +Sources: +- Designers (Figma exports, Photoshop, Illustrator) +- Photographers (RAW or JPEG from camera) +- Stock photo libraries +- AI-generated images +- User-generated content (uploads) +- Automated systems (e.g., screenshots, generated thumbnails) + +At source, decide: +- File formats accepted (RAW, TIFF, PSD, AI vs delivered formats) +- Naming conventions +- Required metadata (alt text, captions, credits, rights) +- Maximum source resolution (high enough to derive any size; not so high it's wasteful) +- Where source files live (separate from delivered assets) + +Anti-pattern: sources and delivered assets in the same place. Hard to find masters. Hard to regenerate. Hard to audit usage. + +### Stage 2: Process + +Transforming source files into delivery formats. + +Processing decisions: +- Resize to standard sizes (e.g., a fixed set of widths: 320, 640, 960, 1280, 1920, 2560) +- Compress (lossy or lossless, with quality targets) +- Convert formats (JPEG, WebP, AVIF for raster; SVG for vector) +- Generate thumbnails and previews +- Strip metadata (EXIF, GPS) unless intentionally retained +- Color profile management (sRGB for web) + +Process options: +- Build-time: Static assets processed during deploy. Predictable, fast at runtime, hard to vary. +- On-demand: A service generates the right format/size when requested. Flexible, requires a processing layer. +- Hybrid: Static processed sizes plus on-demand for edge cases. + +For sites with many image variants and ongoing change, on-demand wins. For tightly controlled marketing sites, build-time can be simpler. + +### Stage 3: Deliver + +Getting assets to users efficiently. + +Delivery decisions: +- CDN: required for any non-trivial volume. Edge caching, global distribution. +- Format negotiation: serve AVIF to browsers that support it, WebP otherwise, JPEG as fallback. Use the `<picture>` element or content negotiation. +- Responsive images: `srcset` and `sizes` attributes so browsers pick the right size for the viewport. +- Lazy loading: `loading="lazy"` for below-the-fold images. +- Async decoding: `decoding="async"` for non-critical images. +- Width and height attributes: always set, prevents layout shift. + +Modern HTML pattern: + +```html +<img + src="/image-1280.jpg" + srcset="/image-640.jpg 640w, /image-960.jpg 960w, /image-1280.jpg 1280w, /image-1920.jpg 1920w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +Or for format negotiation: + +```html +<picture> + <source type="image/avif" srcset="/image.avif"> + <source type="image/webp" srcset="/image.webp"> + <img src="/image.jpg" alt="Descriptive alt text" width="1280" height="720"> +</picture> +``` + +### Stage 4: Manage + +Keeping the system organized and useful over time. + +Management decisions: +- Asset library or DAM (digital asset management): centralized place for the team to find assets +- Tagging and search +- Version control (designers updating an asset, old version still in use) +- Rights and licensing tracking +- Audit and cleanup (what's not used anymore?) +- Permissions (who can upload, edit, delete) + +A simple shared folder works at low scale. A real DAM is necessary above a few thousand assets or with multiple teams. + +--- + +## Format reference + +For typical web use: + +\| Format \| Use for \| Avoid for \| +\|---\|---\|---\| +\| AVIF \| Photographs, complex images. Best compression. \| Browser support edge cases (rare in 2026, ubiquitous now) \| +\| WebP \| Photographs, illustrations. Good compression. Wide support. \| Print, archival \| +\| JPEG \| Photographs (fallback). Universal support. \| Sharp-edged graphics, transparent backgrounds \| +\| PNG \| Sharp-edged graphics, transparent backgrounds, screenshots. Lossless. \| Photographs (file size) \| +\| SVG \| Logos, icons, simple illustrations. Scalable. \| Photographs, complex art \| +\| GIF \| Effectively obsolete. Use video formats for animation. \| Anything modern \| +\| MP4 (H.264) \| Video, universal support. \| Static content \| +\| WebM (VP9 / AV1) \| Video, better compression. \| Older browsers \| + +For most sites: serve AVIF/WebP for modern browsers, JPEG/PNG fallback. SVG for vector. MP4 for video. + +--- + +## Workflow + +### Step 1: Inventory + +What assets exist? Where? In what state? + +- Image count and total storage +- Average sizes (KB) per format +- Image-related performance metrics +- Number of pages with broken or missing images +- Source files vs delivered files + +### Step 2: Audit performance + +For a sample of pages: +- Image weight per page (target: under 500KB total for marketing pages) +- Number of image requests +- Are responsive images used? +- Are modern formats served? +- Is there layout shift from missing dimensions? + +Tools: Lighthouse, WebPageTest, your CDN's analytics. + +### Step 3: Pick the pipeline + +Three reasonable patterns: + +Pattern A: Static, build-time +- Assets in repo or storage bucket +- Build process generates sizes and formats +- Served via CDN +- Good for: static sites, low asset churn, tight performance control + +Pattern B: Image CDN with on-demand +- Source uploads to a bucket or service +- An image CDN (Cloudinary, imgix, Cloudflare Images, Bunny, etc.) processes on-demand via URL parameters +- Good for: mid-to-large sites, frequent asset changes, multiple variants + +Pattern C: Headless CMS with built-in image API +- CMS holds source assets +- CMS provides image API for resizing, format conversion +- Good for: content-heavy sites, non-technical content uploaders, when CMS is already chosen + +The patterns aren't mutually exclusive. Big sites often use Pattern A for design assets, Pattern B for content images. + +### Step 4: Define standards + +Document: +- Naming conventions +- Required metadata (alt text, attribution) +- Maximum source dimensions +- Minimum source dimensions per use case +- Approved formats +- File size targets + +Make these enforceable through tooling where possible (CI checks on file sizes, alt text required by CMS). + +### Step 5: Set up workflows + +For each source type: + +\| Source \| Workflow \| +\|---\|---\| +\| Designer \| Export from Figma, drop into bucket, automated processing handles the rest \| +\| Writer \| Upload through CMS, CMS prompts for alt text \| +\| Photographer \| RAW into source bucket, designer or automation creates web variants \| +\| User upload \| Pass through the image service, automatic moderation if applicable \| + +Document who does what. Workflows that aren't documented break. + +### Step 6: Build the asset library + +For all but the smallest sites: +- Centralized DAM or shared library +- Tag taxonomy (subject, style, brand, campaign, etc.) +- Search across tags and metadata +- Documented rights for each asset (stock license, custom commission, work-for-hire, etc.) +- Sunset workflow (rights expire, asset retires) + +### Step 7: Monitor and audit + +- Performance metrics on image-heavy pages +- Storage costs +- CDN costs +- Broken image alerts (404 on referenced media) +- Unused asset cleanup (storage costs accumulate) + +### Step 8: Document the pipeline + +A pipeline document covers: +- Diagram of source → process → deliver → manage +- Tools used at each stage +- Standards and naming conventions +- Workflows for common cases +- Escalation when something breaks + +--- + +## Failure patterns + +Source files in the delivery bucket. 50MB RAW files served to users. Fix: separate sources from delivered. + +Single image format for every browser. JPEG-only when AVIF could be 30-50% smaller. Use format negotiation. + +Missing width and height attributes. Causes layout shift, hurts CLS metric. Set always. + +Lazy loading hero images. Above-the-fold images shouldn't be lazy-loaded. Lazy below the fold. + +Eager loading everything. All images load on page load. Use `loading="lazy"` for below-fold. + +No responsive images. Mobile gets the desktop image. Wasteful, slow. Use `srcset` and `sizes`. + +One source resolution. Source is the delivery resolution. Can't generate retina or larger. Source should be 2-3x the largest delivered size. + +Stripping all metadata. Removes alt text, removes attribution. Strip GPS and personal EXIF; keep semantic metadata. + +Random naming. `IMG_4823.jpg`, `Screenshot 2024-03-15.png`. Hard to find later. Use a naming convention. + +No alt text. Accessibility failure, SEO failure. Make alt text required at upload. + +Storage growing unbounded. Old, unused assets pile up. Quarterly cleanup or automated lifecycle policies. + +One person knows the pipeline. When they're out, no one can fix issues or onboard new sources. Document. + +--- + +## Output format + +A media pipeline document includes: + +- Inventory: current asset count, formats, storage +- Pipeline diagram: source → process → deliver → manage with tools at each stage +- Format and size standards: what gets generated, when +- Naming and metadata conventions: with examples +- Workflows by source type: designer, writer, photographer, user +- Performance baseline and targets: weight per page, format adoption, etc. +- Asset library: tool, taxonomy, search, rights tracking +- Monitoring: performance, costs, broken assets +- Roadmap: improvements over the next 1-2 quarters + +--- + +## Reference files + +- [`references/responsive-image-patterns.md`](references/responsive-image-patterns.md): Copy-paste HTML patterns for common responsive image scenarios (hero, content, art-directed, format negotiation), with explanations. diff --git a/skills/media-asset-management/references/responsive-image-patterns.md b/skills/media-asset-management/references/responsive-image-patterns.md new file mode 100644 index 0000000..721f670 --- /dev/null +++ b/skills/media-asset-management/references/responsive-image-patterns.md @@ -0,0 +1,373 @@ +# Responsive Image Patterns + +Copy-paste HTML patterns for common image scenarios. Each pattern is annotated with what it does and when to use it. + +The principles work across stacks. The HTML is the same whether you're in Next.js, WordPress, Webflow, or vanilla HTML. + +--- + +## Pattern 1: Simple responsive image + +The default for most content images. Same image at different sizes. + +```html +<img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w, + /img/photo-1920.jpg 1920w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +``` + +What's happening: +- `src`: fallback for browsers that don't support srcset (rare today, still good practice) +- `srcset`: list of available sizes with their widths +- `sizes`: tells the browser how wide the image will display at different viewport widths +- `width`/`height`: prevents layout shift; the browser reserves space before the image loads +- `loading="lazy"`: delays loading until near the viewport +- `decoding="async"`: doesn't block rendering on this image +- `alt`: accessibility and SEO + +When to use: Most content images, blog post bodies, article illustrations. + +--- + +## Pattern 2: Hero image (above the fold) + +The hero image needs special handling because it's critical to first paint. + +```html +<img + src="/img/hero-1920.jpg" + srcset=" + /img/hero-640.jpg 640w, + /img/hero-960.jpg 960w, + /img/hero-1280.jpg 1280w, + /img/hero-1920.jpg 1920w, + /img/hero-2560.jpg 2560w + " + sizes="100vw" + width="1920" + height="1080" + fetchpriority="high" + decoding="async" + alt="Descriptive alt text"> +``` + +Differences from Pattern 1: +- No `loading="lazy"` (hero must load immediately) +- `fetchpriority="high"` (hint to load this first) +- Larger size options for full-width displays +- `sizes="100vw"` (image takes full viewport width) + +Optionally preload the hero in the document head: + +```html +<link + rel="preload" + as="image" + href="/img/hero-1280.jpg" + imagesrcset="/img/hero-640.jpg 640w, /img/hero-960.jpg 960w, /img/hero-1280.jpg 1280w, /img/hero-1920.jpg 1920w, /img/hero-2560.jpg 2560w" + imagesizes="100vw"> +``` + +This tells the browser to start the request before HTML parsing reaches the `<img>`. + +When to use: The single hero or banner at the top of a page. Don't preload more than one image; it competes with critical resources. + +--- + +## Pattern 3: Format negotiation + +Serve modern formats to browsers that support them, fall back to JPEG. + +```html +<picture> + <source + type="image/avif" + srcset=" + /img/photo-640.avif 640w, + /img/photo-960.avif 960w, + /img/photo-1280.avif 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <source + type="image/webp" + srcset=" + /img/photo-640.webp 640w, + /img/photo-960.webp 960w, + /img/photo-1280.webp 1280w + " + sizes="(max-width: 768px) 100vw, 50vw"> + <img + src="/img/photo-1280.jpg" + srcset=" + /img/photo-640.jpg 640w, + /img/photo-960.jpg 960w, + /img/photo-1280.jpg 1280w + " + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +What's happening: +- The browser tries each `<source>` in order +- The first one with a supported `type` is used +- The `<img>` is the fallback if no `<source>` matches +- The `<img>` also provides the alt text and dimensions for all formats + +When to use: Whenever your pipeline can produce multiple formats. AVIF is now well-supported; WebP is universal. JPEG is the safe fallback. + +Easier alternative: A modern image CDN can do format negotiation server-side based on the `Accept` header. The HTML stays as Pattern 1; the CDN serves the right format. Often the better approach. + +--- + +## Pattern 4: Art direction (different crops at different breakpoints) + +Sometimes you want a different image (not just a different size) on mobile vs desktop. + +```html +<picture> + <source + media="(max-width: 768px)" + srcset=" + /img/portrait-640.jpg 640w, + /img/portrait-960.jpg 960w + " + sizes="100vw"> + <source + media="(min-width: 769px)" + srcset=" + /img/landscape-1280.jpg 1280w, + /img/landscape-1920.jpg 1920w + " + sizes="100vw"> + <img + src="/img/landscape-1280.jpg" + width="1920" + height="1080" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> +</picture> +``` + +What's happening: +- On screens 768px wide or less, use the portrait crop +- On larger screens, use the landscape crop +- Different aspect ratios per device + +When to use: Marketing pages where the image composition matters at each breakpoint. Often for hero images of people or products. + +Caution: Set explicit dimensions to match each crop, or be careful about layout shift between crops. CSS aspect-ratio can help. + +--- + +## Pattern 5: Background images + +For decorative backgrounds set in CSS, use `image-set()` for responsive selection: + +```css +.hero { + background-image: image-set( + url('/img/hero-1280.jpg') 1x, + url('/img/hero-2560.jpg') 2x + ); +} +``` + +For format negotiation in CSS: + +```css +.hero { + background-image: image-set( + url('/img/hero.avif') type('image/avif'), + url('/img/hero.webp') type('image/webp'), + url('/img/hero.jpg') type('image/jpeg') + ); +} +``` + +Note: Background images are decorative. If the image carries meaning, it should be an `<img>` with alt text, not a CSS background. + +--- + +## Pattern 6: SVG (vectors) + +For logos, icons, simple illustrations: + +```html +<img + src="/img/logo.svg" + width="200" + height="40" + alt="Brand name"> +``` + +Or inline for icons (better for theming with CSS): + +```html +<svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true"> + <path d="..."/> +</svg> +``` + +Notes: +- SVG is resolution-independent. No `srcset` needed. +- For decorative icons, use `aria-hidden="true"`. For meaningful icons, provide a label. +- Inline SVG can be styled with CSS. Linked SVG cannot. + +--- + +## Pattern 7: Lazy-loaded video + +Treat video like a heavy image: + +```html +<video + width="1280" + height="720" + poster="/img/video-poster.jpg" + preload="metadata" + controls> + <source src="/video/clip.webm" type="video/webm"> + <source src="/video/clip.mp4" type="video/mp4"> + <track kind="captions" src="/video/clip-captions.vtt" srclang="en" label="English"> + Your browser does not support the video tag. +</video> +``` + +Notes: +- `poster`: image shown before play, sized to match video +- `preload="metadata"`: only loads enough to know duration, not the whole file +- `<track>`: captions for accessibility (always include for non-decorative video) +- Multiple `<source>`: browser picks the first supported format + +For autoplay video (decorative, no audio): + +```html +<video + autoplay + muted + loop + playsinline + poster="/img/poster.jpg" + preload="auto"> + <source src="/video/loop.mp4" type="video/mp4"> +</video> +``` + +`muted` and `playsinline` are required for autoplay on most browsers. Be cautious about autoplay; many users disable it or find it annoying. + +--- + +## Pattern 8: User-uploaded images + +For images uploaded by users (avatars, content), set defensive defaults: + +```html +<img + src="/uploads/avatar-medium.jpg" + width="200" + height="200" + loading="lazy" + decoding="async" + alt="" + onerror="this.style.display='none'"> +``` + +Notes: +- Process uploads through a moderation step before serving (especially for public sites) +- Generate consistent sizes (small, medium, large) +- Strip EXIF (GPS, etc.) for privacy +- Have a fallback (default avatar, broken image hidden) +- alt text from user-provided context where possible + +--- + +## Pattern 9: Image with caption + +Use `<figure>` for semantically grouped image and caption. + +```html +<figure> + <img + src="/img/photo-1280.jpg" + srcset="/img/photo-640.jpg 640w, /img/photo-960.jpg 960w, /img/photo-1280.jpg 1280w" + sizes="(max-width: 768px) 100vw, 50vw" + width="1280" + height="720" + loading="lazy" + decoding="async" + alt="Descriptive alt text"> + <figcaption>Caption visible to all users.</figcaption> +</figure> +``` + +Notes: +- alt text describes the image for users who can't see it +- caption provides context for everyone +- They serve different purposes; both are useful when there's a caption + +--- + +## Anti-patterns + +Lazy-loading the hero image. Above-the-fold images should load immediately. + +Missing width and height. Causes layout shift. Always set. + +Same image, different file extensions. `image.jpg` and `image.JPG` for the same content. Pick one convention. + +Tracking pixels masquerading as images. Use proper analytics, not 1x1 GIFs. + +Decorative images with descriptive alt text. A decorative pattern with `alt="ornamental swirl background"` is noise for screen readers. Use `alt=""` for purely decorative. + +Decorative images with no alt attribute at all. Screen readers may announce the filename. Use `alt=""` (empty, not missing). + +Inline base64 images for non-trivial sizes. Bloats HTML. Use a URL. + +Forgetting captions in non-English contexts. Captions and alt text need translation just like any other content. + +--- + +## Alt text guidelines + +- Decorative: `alt=""` (empty) +- Functional (e.g., a search button icon): describes the action: `alt="Search"` +- Informative: describes the content the user is missing: `alt="Hand holding a coffee cup at a wooden desk"` +- Complex (charts, infographics): brief alt + a fuller description in nearby text or `aria-describedby` + +Alt text should: +- Convey what the image conveys, not what it depicts +- Be concise (typically under 125 characters) +- Not start with "Image of" or "Picture of" (screen readers say that already) +- Include important text that's part of the image + +--- + +## Tooling notes + +Most modern frameworks have an `<Image>` component that wraps these patterns. Examples include Next.js Image, Astro Image, Nuxt Image. They handle: + +- Format negotiation automatically +- Responsive sizes +- Lazy loading defaults +- Width/height enforcement + +If you're using a framework with such a component, prefer it over hand-rolling the HTML. The framework version usually includes optimizations the hand-rolled version misses. + +If you're not using a framework, the patterns here are the right baseline. diff --git a/skills/monitoring-and-alerting/SKILL.md b/skills/monitoring-and-alerting/SKILL.md new file mode 100644 index 0000000..971d963 --- /dev/null +++ b/skills/monitoring-and-alerting/SKILL.md @@ -0,0 +1,256 @@ +--- +name: monitoring-and-alerting +description: "Design and run a monitoring system for a website or web app. Use this skill when setting up uptime checks, defining SLOs, configuring error tracking, choosing what to alert on, designing on-call rotations, or fixing alert fatigue. Triggers on monitoring, alerts, uptime, SLO, SLA, error rate, on-call, pager, alert fatigue, observability, dashboards, what should we monitor. Also triggers when an incident reveals a gap in monitoring." +category: operations +catalog_summary: "SLO design, uptime checks, alert routing, on-call rotations" +display_order: 5 +--- + +# Monitoring and Alerting + +Decide what to watch, what to alert on, and how to make sure the right person finds out when things break. + +--- + +## When to use + +- Setting up monitoring on a new site or service +- Defining SLOs (service level objectives) and error budgets +- Choosing which alerts page someone vs which go to a quiet channel +- Designing or fixing on-call rotation +- Diagnosing alert fatigue +- Filling monitoring gaps revealed by an incident +- Migrating monitoring vendors + +## When NOT to use + +- Responding to an active incident (use `incident-response`) +- Writing the post-mortem (use `after-action-report`) +- Designing analytics dashboards for product metrics (use `analytics-strategy`) +- Performance optimization itself (use `performance-optimization`) + +--- + +## Required inputs + +- The system you're monitoring (URLs, services, dependencies) +- Existing monitoring tools (uptime, errors, logs, APM) +- Business hours and team timezone(s) +- Who is on-call or available for incidents +- Existing SLOs or success metrics, if any + +--- + +## The framework: 4 layers + +Monitoring works in layers. Skip a layer and you'll miss a class of problems. + +### Layer 1: Availability + +Is the site up? The simplest, most important layer. + +- HTTP checks from multiple regions (every 1-5 minutes) +- DNS resolution checks +- Certificate expiration checks +- Status code checks (alert on 5xx, not just timeout) + +Threshold: any sustained downtime (more than 2 consecutive failed checks) pages. + +### Layer 2: Correctness + +The site is up, but is it serving the right thing? + +- Synthetic checks (a script that loads the homepage, clicks a button, validates expected text) +- Critical user journeys (signup, checkout, search) +- Content presence checks (homepage hasn't gone blank) +- API contract checks (response shape and key fields are present) + +Threshold: failures of critical-path synthetics page. Non-critical page-level synthetics alert during business hours only. + +### Layer 3: Performance + +The site is up and correct, but is it fast enough? + +- Core Web Vitals (LCP, INP, CLS) from real users (RUM) +- Synthetic performance (Lighthouse, WebPageTest, custom) +- API response times (p50, p95, p99) +- Database query times for slow queries +- Dependency response times (third-party APIs) + +Threshold: regressions from baseline (e.g., p95 doubled in 5 minutes). Don't alert on absolute thresholds without baselines. + +### Layer 4: Errors and anomalies + +The site is up, correct, and fast for most, but errors are happening. + +- Error rate (% of requests returning 5xx) +- Client-side error rate (uncaught JS exceptions) +- Log error volume (unexpected spikes) +- Anomaly detection (traffic falling off a cliff) +- Background job failures +- Queue depth + +Threshold: rate-based, not count-based. "Error rate above 1% for 5 minutes" beats "more than 100 errors per minute." + +--- + +## SLOs and error budgets + +A Service Level Objective is the target for reliability. Common form: "99.9% of homepage requests succeed in under 2 seconds, measured over 30 days." + +The components: +- The thing you're measuring (homepage requests) +- The success criterion (returns 2xx in under 2 seconds) +- The target (99.9% of them) +- The window (over 30 days) + +The error budget is the inverse: 0.1% of requests can fail. If you've used the whole budget, slow down on risky changes. + +### Picking SLOs + +Don't aim for 100%. Don't aim for "five nines" (99.999%) unless you really need it. Each nine costs an order of magnitude more. + +\| SLO \| Allowed downtime per month \| +\|---\|---\| +\| 99% \| 7 hours, 18 minutes \| +\| 99.9% \| 43 minutes \| +\| 99.95% \| 21 minutes \| +\| 99.99% \| 4 minutes, 22 seconds \| +\| 99.999% \| 26 seconds \| + +For most marketing sites, 99.9% is plenty. For SaaS, 99.95% is reasonable. Anything higher needs significant infrastructure investment. + +### Using error budgets + +When the budget is healthy, ship aggressively. When the budget is half-spent, slow down. When the budget is exhausted, freeze risky changes until reliability recovers. + +This is what makes SLOs useful: they create a feedback loop between reliability and velocity. + +--- + +## Workflow + +### Step 1: Inventory what's already monitored + +What tools are in place? What checks exist? What dashboards? What alerts? + +Many teams have a tangle of half-configured tools. The first job is the inventory. + +### Step 2: Map the system + +Draw the architecture. Front-end, back-end, database, third-party APIs, queues, workers. Each box is a candidate for monitoring. + +For each box, ask: +- What does "up" mean? +- What does "correct" mean? +- What does "fast" mean? +- What's the most common failure mode? + +### Step 3: Define the SLOs + +Pick 3-5 SLOs. They should be: +- Tied to user-visible behavior (not internal metrics) +- Achievable with current infrastructure +- Measured automatically +- Reviewed at least quarterly + +### Step 4: Set up checks across the 4 layers + +For each box, configure checks at each layer. Some boxes won't have all four; that's fine. + +\| Box \| Availability \| Correctness \| Performance \| Errors \| +\|---\|---\|---\|---\|---\| +\| Homepage \| HTTP check \| Synthetic \| LCP/INP \| JS errors \| +\| Login API \| HTTP check \| Synthetic flow \| p95 latency \| 5xx rate \| + +### Step 5: Decide what pages and what doesn't + +Three tiers: + +1. Page (wakes someone up): site down, critical flow broken, error rate spike, security incident. +2. Notify (during business hours): non-critical synthetic failure, performance regression, slow query, dependency degradation. +3. Log (no notification): anomalies for later review, low-priority warnings, info-level events. + +Anything in tier 1 must be: +- Actionable (the on-call can do something about it) +- Important (it represents real impact) +- Rare (less than 1-2 per week is the goal) + +If tier 1 alerts fire frequently, alert fatigue sets in. People stop responding. + +### Step 6: Configure routing + +Where do alerts go? + +- Tier 1: paging system (e.g., PagerDuty, Opsgenie). Direct to on-call. +- Tier 2: chat channel (Slack, Teams). Tagged with the area. +- Tier 3: dashboard or log only. + +Each tier should have a documented escalation path. If the on-call doesn't ack within 5-15 minutes, escalate. + +### Step 7: Build dashboards + +One dashboard per audience: + +- Real-time ops dashboard: current health, recent alerts, error rates, throughput +- SLO dashboard: SLO status and error budget consumption +- Per-service dashboards: detail for individual services or pages +- Executive dashboard: uptime over weeks/months, key business metrics + +Dashboards are different from alerts. Alerts say "look now." Dashboards say "here's what's happening." + +### Step 8: Run an alert audit + +Every quarter, audit: +- Which alerts fired? Were they actionable? +- Which alerts didn't fire when they should have? +- Are any alerts noisy (more than once a week, low actionability)? +- Are runbooks up to date? +- Have SLOs been met? Any consistently breached? + +Tune the system. Monitoring drifts without active maintenance. + +--- + +## Failure patterns + +Alert on cause, not symptom. "CPU is high" is a cause. "Users are slow" is a symptom. Alert on symptoms; investigate causes. + +Alert without a runbook. If the on-call doesn't know what to do, the alert is useless. Every paging alert needs a runbook (even a one-line one). + +No baselines for "normal." Alerting on "more than 100 errors per minute" sounds reasonable but a busy day might exceed that without anything being wrong. Use rate-based and anomaly-based alerts. + +Single-region monitoring. Your monitoring service in the same region as your site means you'll miss regional outages and you'll get woken up when monitoring itself has issues. + +Monitoring the monitoring. Or rather, not. If your alerting platform is down, who tells you? Most paging services offer their own status feeds. Subscribe. + +Too many tiers of severity. P0/P1/P2/P3/P4 with different SLAs becomes a sorting exercise. Three tiers (page, notify, log) is plenty. + +Synthetics that don't match reality. A synthetic that hits the homepage every minute tests "is the homepage up." It doesn't test "is the actual user flow working." Build synthetics for the journeys that matter. + +Static thresholds that never get tuned. Traffic grows, behavior changes, thresholds set last year are wrong. Review thresholds quarterly. + +On-call rotation with no handoffs. Each new on-call has to figure out the system. Document. Run weekly handoff meetings or async updates. + +Pager fatigue. If on-call is paged more than once or twice a week, something is wrong. Audit the alerts. Reduce, tune, or fix the underlying issues. + +--- + +## Output format + +A monitoring plan includes: + +- System map: what's being monitored +- SLOs: the 3-5 reliability targets +- Checks per layer: availability, correctness, performance, errors +- Alert tiering: what pages, what notifies, what logs +- Routing: where alerts go, escalation paths +- Dashboards: what audiences see +- Runbooks: linked from each paging alert +- Audit cadence: when this gets reviewed + +--- + +## Reference files + +- [`references/slo-design-guide.md`](references/slo-design-guide.md): Detailed walkthrough of writing SLOs, error budget policies, and common SLO mistakes for web services. diff --git a/skills/monitoring-and-alerting/references/slo-design-guide.md b/skills/monitoring-and-alerting/references/slo-design-guide.md new file mode 100644 index 0000000..1f5ec49 --- /dev/null +++ b/skills/monitoring-and-alerting/references/slo-design-guide.md @@ -0,0 +1,246 @@ +# SLO Design Guide + +A walkthrough for designing Service Level Objectives that are useful, achievable, and aligned to user experience. + +--- + +## What an SLO is and isn't + +A Service Level Objective is a target for reliability, expressed as a percentage of "good" events out of all events, measured over a specific time window. + +An SLO is: +- A reliability target the team commits to +- Measured automatically +- Tied to user-visible behavior +- Reviewed and adjusted over time + +An SLO is not: +- A guarantee (that's an SLA, which has contractual consequences) +- A goal to maximize (100% is the wrong target) +- A vanity metric (uptime alone tells you almost nothing) +- Permanent (revise as the system evolves) + +--- + +## The structure of a good SLO + +Every SLO has four components: + +1. The thing being measured (the SLI - Service Level Indicator) +2. The success criterion (what counts as "good") +3. The target (the percentage of events that should be "good") +4. The window (the time period over which to measure) + +Example: + +> "99.9% of homepage requests return a 2xx status code in under 2 seconds, measured over a rolling 30-day window." + +Breaking it down: +- SLI: latency and status of homepage requests +- Good event: 2xx response in under 2 seconds +- Target: 99.9% +- Window: rolling 30 days + +If the system serves 1 million homepage requests in 30 days, this SLO allows 1,000 bad events. That's the error budget. + +--- + +## Picking SLIs + +The SLI is what you measure. Pick SLIs that reflect what users actually experience. + +### Good SLI categories + +Availability: the proportion of valid requests that succeed. +- "% of HTTP requests that return non-5xx" +- "% of API calls that complete without error" + +Latency: the proportion of requests that complete fast enough. +- "% of homepage requests with TTFB under 600ms" +- "% of search queries returning results in under 1 second" + +Quality: the proportion of requests that produce correct results. +- "% of recommendations served from the personalized model (vs fallback)" +- "% of search queries returning at least one result" + +Freshness: the proportion of data that's fresh enough. +- "% of cached pages updated within the last 24 hours" +- "% of analytics data ingested within 15 minutes of event" + +Throughput: the proportion of time the system handles required load. +- "% of minutes during which queue depth was below 1000" + +### Bad SLI patterns + +CPU or memory utilization. These are causes of problems, not symptoms users feel. Don't make them SLIs. + +Number of incidents. Too coarse. One nasty incident can blow it for the whole window. + +Average response time. Averages hide tail latency. P95 or P99 is closer to user experience. + +Internal metrics that don't map to user impact. "Database replica lag." Useful to monitor. Not a great SLO unless it directly affects users. + +--- + +## Picking targets + +Target percentages have specific implications. Here's the practical math: + +\| Target \| Allowed bad time per 30 days \| Allowed bad events per million \| +\|---\|---\|---\| +\| 90% \| 3 days \| 100,000 \| +\| 99% \| 7 hours, 18 minutes \| 10,000 \| +\| 99.9% \| 43 minutes, 30 seconds \| 1,000 \| +\| 99.95% \| 21 minutes, 48 seconds \| 500 \| +\| 99.99% \| 4 minutes, 22 seconds \| 100 \| +\| 99.999% \| 26 seconds \| 10 \| + +Each "9" added is roughly 10x harder. Pick the lowest target that's acceptable to users. + +### How to pick + +1. Look at current performance. What's the system actually achieving? Use that as the floor. +2. Look at user expectations. What do users tolerate? For a marketing site, occasional slow pages are fine. For a payment system, they're not. +3. Look at competitive bar. What do similar services achieve? +4. Pick something achievable but slightly aspirational. If the current achievement is 99.5%, set the SLO at 99.7%. Don't jump to 99.99%. + +### Common mistakes + +Setting the SLO at 100%. Impossible. Wastes infrastructure. Creates false promises. + +Setting the SLO based on what marketing wants to advertise. If marketing says "99.99% uptime!" but engineering can't deliver, the SLO is fiction. + +Setting different SLOs for different teams without coordination. End-to-end user experience depends on all of them. If one team has a 99.9% SLO and another has 99%, the combined experience is worse than either. + +--- + +## Picking windows + +The window affects how SLOs feel. + +Calendar windows: "99.9% in March." Resets at month boundaries. Good for reporting, bad for operating (the budget can be exhausted on March 1 with nothing you can do until April). + +Rolling windows: "99.9% over the last 30 days." Always current. Better for operations because the budget continuously updates. + +Common windows: +- 7 days: too short, noise dominates +- 28-30 days (rolling): the sweet spot for most operations +- 90 days: better for SLAs and stability assessment, worse for fast feedback + +For most teams: 30-day rolling. + +--- + +## Error budgets + +The error budget is `1 - SLO`. If your SLO is 99.9%, your error budget is 0.1%. + +The budget is what allows for change. Every release, every config change, every dependency update consumes some budget. The budget exists so the team can ship. + +### Error budget policy + +A written policy that says what happens when the budget is at different levels. Example: + +\| Budget remaining \| What's allowed \| +\|---\|---\| +\| > 50% \| Normal operation. Ship features, run experiments. \| +\| 25-50% \| Caution. Postpone risky migrations. Prefer smaller releases. \| +\| 10-25% \| Slow down. Only ship reliability fixes and security patches. Defer feature releases. \| +\| < 10% \| Freeze. No non-urgent changes. Focus on reliability. \| + +This is the operationally useful part of SLOs. It connects reliability to product velocity in a measurable way. + +### Burning the budget + +If the budget burns at a rate of, say, 10% in an hour, that's a fast burn. Alert on fast burns: "we'll exhaust the budget in 4 hours at this rate." + +Slow burn alerts catch sustained low-grade issues. Fast burn alerts catch acute incidents. + +### Refilling the budget + +The budget refills as the rolling window moves forward. If today is the last day of a bad month, tomorrow the worst day rolls off and the budget recovers slightly. + +Don't "make up" budget by tightening the SLO temporarily. SLOs are user-facing commitments. Don't move them to make numbers look better. + +--- + +## Multi-tier SLOs + +For complex systems, one SLO isn't enough. Multi-tier SLOs cover different aspects. + +A typical web app might have: + +1. Availability SLO: 99.95% of requests return non-5xx. +2. Latency SLO: 99% of requests complete in under 1 second. +3. Critical flow SLO: 99.9% of checkout flows complete successfully. + +Each has its own error budget and policy. + +For products with multiple tiers of importance, you can also have different SLOs per tier: + +- Critical pages (homepage, checkout): 99.95% +- Standard pages (product, category): 99.9% +- Long-tail pages (search, archive): 99% + +This reflects user impact: a slow checkout matters more than a slow archive page. + +--- + +## Reviewing and revising SLOs + +SLOs aren't set-and-forget. Review: + +- Quarterly: is the SLO still right? Has the system or user expectation changed? +- After major incidents: did the SLO catch it? Should the SLO be tighter? +- After major launches: did the new feature change the math? +- Annually: big-picture review of all SLOs. + +Common revisions: +- Tightening (e.g., 99.9% → 99.95%) when the system has improved and the team can sustain it +- Loosening (e.g., 99.95% → 99.9%) when the previous target was too aggressive (rare, requires justification) +- Splitting an SLO into multiple (e.g., one combined SLO becomes separate availability and latency SLOs) +- Retiring SLOs that no longer reflect what matters + +--- + +## Example: a marketing site + +For a typical marketing site: + +\| SLO \| Target \| Window \| +\|---\|---\|---\| +\| Homepage availability (2xx response) \| 99.9% \| 30-day rolling \| +\| Homepage latency (TTFB < 800ms) \| 95% \| 30-day rolling \| +\| Form submission success \| 99.5% \| 30-day rolling \| +\| Critical-page availability (top 10 pages 2xx) \| 99.9% \| 30-day rolling \| + +Error budget policy: +- Above 50% budget: ship freely +- 10-50% budget: defer risky changes +- Below 10%: freeze non-essential changes + +This is a reasonable starting point. Tune based on actual operating history. + +--- + +## Example: a SaaS product + +For a SaaS product with paying customers: + +\| SLO \| Target \| Window \| +\|---\|---\|---\| +\| API availability (non-5xx) \| 99.95% \| 30-day rolling \| +\| API latency (p95 under 500ms) \| 99% \| 30-day rolling \| +\| Login success \| 99.99% \| 30-day rolling \| +\| Critical action success (e.g., save data) \| 99.95% \| 30-day rolling \| +\| Background job completion within 1 hour \| 99% \| 7-day rolling \| + +Error budget policy is stricter (paying customers have higher expectations). Below 25% budget triggers a slowdown; below 10% triggers a freeze with executive approval needed to override. + +--- + +## When you don't have an SLO yet + +Start small. Pick one SLO that maps to the most important user-facing behavior. Live with it for a quarter. Add more once the team is comfortable. + +Trying to roll out 10 SLOs at once usually fails. Trying to roll out 1 SLO and using it well usually succeeds. diff --git a/skills/multi-step-form-design/SKILL.md b/skills/multi-step-form-design/SKILL.md new file mode 100644 index 0000000..5e53791 --- /dev/null +++ b/skills/multi-step-form-design/SKILL.md @@ -0,0 +1,332 @@ +--- +name: multi-step-form-design +description: "Designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. Honest about kitchen-sink-single-page (overwhelms before the user starts), progress-theater (steps without genuine staging), and genuinely-staged (each step earns its own page) patterns. Triggers on multi-step form, multi-page form, form wizard, signup wizard, lead form, application form, intake form, configurator, onboarding form. Also triggers when a long form is converting poorly, when an audience is dropping off mid-form, or when a multi-step form is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing multi-step forms that respect cognitive load while maintaining completion intent. Distinguishes kitchen-sink-single-page (overwhelms) from progress-theater (steps without genuine staging) from genuinely-staged (each step earns its own page)" +display_order: 4 +--- + +# Multi-Step Form Design + +A senior growth practitioner's playbook for designing forms with multiple steps, progress indicators, conditional logic, and save-and-resume mechanics. The discipline of breaking complex data collection into stages that respect cognitive load while maintaining completion intent. + +Most multi-step forms are either kitchen-sink-single-pages dressed up as steps or arbitrary chunking that adds friction without adding clarity. The form looks more sophisticated; the completion rate does not move; the audience is no better served than before. + +The multi-step forms that work do something different. Each step represents a coherent unit of cognitive work the user can complete with confidence. Progress indicators reinforce momentum. Conditional logic responds to earlier answers and removes irrelevant fields. The form feels like a guided process, not an obstacle course. + +The voice is the senior growth practitioner who has watched multi-step forms convert at twice the single-page rate and watched them collapse to half. Practical, opinionated about when steps add value and when they add friction, willing to call out arbitrary chunking that does not earn its complexity. + +When to use this skill: scoping a multi-step form for the first time, auditing a long single-page form that converts poorly, deciding when to break a form into steps and when to keep it on one page, or designing the conditional logic that makes the form feel adaptive. + +--- + +## What this skill covers + +This skill spans multi-step form design across acquisition, onboarding, and intake contexts. The growth-tooling distinctions: + +- `lead-magnet-design` covers lead-magnet methodology; forms are one delivery surface for lead magnets but this skill is about the form itself. +- `landing-page-copy` is the page wrapping the form. This skill is the form itself. +- `accessibility-audit` covers accessibility deeply; forms have specific accessibility requirements; this skill references but does not replace accessibility-audit. +- `pm-spec-writing` is the spec for engineers building the form. This skill is about WHAT to build; pm-spec-writing is about communicating it. +- `multi-step-form-design` (this skill) is the form's structure, step architecture, progression, and validation. + +The audience: growth marketers, product marketers, marketing teams designing acquisition forms, in-house teams designing onboarding flows, agencies running form-based growth tooling for clients. + +Out of scope: form-builder platform configurations (those stay implementation-side); deep accessibility audits (covered by `accessibility-audit`); landing-page copy that wraps the form (covered by `landing-page-copy`). + +--- + +## The multi-step decision: when to break into steps vs keep single-page + +Before designing the steps, decide whether the form should be multi-step at all. + +Multi-step earns the build when: + +- The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. +- The fields naturally group into logical categories. Personal info, then situation, then preferences. Steps that reflect real groupings respect cognitive load. +- The audience benefits from progressive commitment. Each step builds investment; the user is more likely to complete after they have engaged with step 2 than they would have been if they had seen step 5's complexity upfront. +- Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page. + +Multi-step does NOT earn the build when: + +- The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. +- The fields do not group naturally. Arbitrary chunking is friction. +- The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. +- The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes; the maintenance overhead is real. + +The decision is not "should the form be multi-step"; it is "is multi-step the right structure for this specific data collection and audience." + +Detail in [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md). + +--- + +## Kitchen-sink-single-page vs progress-theater vs genuinely-staged + +The keystone framing. + +Kitchen-sink-single-page. 30 fields on one page. Overwhelms before the user even starts. Drop-off near 100 percent on anything beyond a contact form. The audience scrolls, sees the length, and leaves. Cost: the form's data collection scope is correct; the structure is wrong; nobody completes it. + +Progress-theater. The form is broken into 5 steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone. Step 4: company. Step 5: role." The progress bar exists; the staging logic does not. Cost: the form feels broken; users reach step 3 wondering why they did not just fill a single page; the completion rate may be slightly better than kitchen-sink but the audience perceives the format as gimmicky. + +Genuinely-staged. Each step represents a coherent unit of cognitive work. The user finishes a step and feels they accomplished something. Steps progress from low-friction to higher-commitment as intent compounds. Cost: the design effort upfront is significant; the maintenance is real; the conversion rate often outperforms both alternatives meaningfully. + +The litmus test. Ask a user who completed step 2 what they just did. Can they describe the unit of work as something coherent ("I gave you the basics about my company") or is the answer atomized ("I typed my company name in a field")? Coherent answers signal genuinely-staged; atomized answers signal progress-theater. + +--- + +## Step architecture: what belongs on each step + +The structure that makes steps coherent. + +The principle. Each step should represent a coherent unit of work from the user's perspective. + +Common step patterns. + +- Identity step. Who the user is. Name, email, basic role. Low-friction; opens the form. +- Context step. What the user's situation is. Company size, industry, current setup. Medium-friction; user shares context. +- Need step. What the user is trying to accomplish. Goals, challenges, priorities. Higher-friction; user articulates intent. +- Detail step. Specifics needed to act on the user's request. Budget, timeline, specific requirements. Highest-friction; saved for last. +- Confirmation step. Review and submit. Summarizes what the user provided. + +Step sequencing principle. Low-friction first; commitment compounds; high-friction at the end after the user has invested. + +Step coherence test. Can each step be described in one sentence as a unit of work? "Step 2: tell us about your company's situation" beats "Step 2: company name, size, industry, and revenue range." + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## Progress indicator design + +When to show progress, what to show, how it builds momentum. + +The principle. Progress indicators reinforce momentum and reduce uncertainty about how much is left. + +Progress indicator patterns. + +- Step counter. "Step 2 of 4." Simple, common, effective for short forms (3-6 steps). +- Progress bar. Visual fill showing percentage complete. Effective for forms with variable-length steps where step count alone is misleading. +- Step list. Named steps shown with the current one highlighted. Useful when the user benefits from seeing what comes next. +- No indicator. Sometimes appropriate for very short forms (2-3 steps) where the indicator overhead exceeds its value. + +Progress indicator failures. + +- Indicator that shifts mid-form. "Step 4 of 5" becomes "Step 4 of 7" because conditional logic added steps. The user feels misled. +- Indicator that hides remaining work. Showing "almost done" when 5 fields remain on the next step. +- Indicator that is decorative without being honest. Progress that looks fast but the next step is the longest one. + +Progress indicator discipline. The indicator must reflect the actual remaining work, not flatter the user. + +Detail in [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md). + +--- + +## Conditional logic + +Branching that responds to earlier answers. + +The principle. Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +Conditional logic patterns. + +- Show or hide fields based on previous answers. "If user selected 'enterprise,' show enterprise-specific fields." +- Skip entire steps. "If user does not have a current CRM, skip the 'CRM details' step." +- Adapt the language. "If user is in healthcare, use healthcare-specific terminology in subsequent fields." +- Adapt the destination. "If user selected 'integration question,' route to the integration team after submission." + +Conditional logic strengths. + +- Removes irrelevant friction. +- Makes the form feel adaptive and intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +Conditional logic risks. + +- Maintenance complexity grows quickly. +- Testing becomes harder (more paths through the form). +- Progress indicators must adapt or honestly disclose the variability. + +The simplicity preference. Add conditional logic only when it produces real value. Conditional logic for decoration adds maintenance without lift. + +Detail in [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md). + +--- + +## Save-and-resume mechanics + +When to offer save-and-resume, how to communicate trust. + +The principle. Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. + +When save-and-resume helps. + +- Forms that require document uploads or specific information (W-2, financial details, technical configurations). +- Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms). +- Forms where the user benefits from coming back to verify or update. + +When save-and-resume does not help. + +- Quick lead-capture forms (under 60 seconds to complete). +- Single-session forms where save-and-resume adds complexity without lift. + +Save-and-resume mechanics. + +- Email-link recovery. "Save your progress; we will email you a link to continue." The most common pattern. +- Account-based persistence. Forms that require account creation persist by default. +- Anonymous-session save. Browser-based save without identification. Lowest friction but limited to the same browser/device. + +Trust communication. Users hesitate to save partial sensitive information. The form should communicate clearly: what is saved, how long it persists, who can access it, how to resume. + +Detail in [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md). + +--- + +## Validation strategy + +Per-step vs end-only. + +Per-step validation. Each step's fields are validated before allowing progression. The user catches errors early. + +Strengths. + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +Weaknesses. + +- Can feel intrusive if validation is too strict on every keystroke. +- May block the user from progressing when they want to revise later. + +End-only validation. All validation runs at submission. + +Strengths. + +- User completes uninterrupted. +- Validation logic is simpler. + +Weaknesses. + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. + +The hybrid pattern. Required-field validation per step; full validation at end. The user gets immediate feedback on critical issues; nuanced validation runs at submission. + +Validation message discipline. + +- Helpful messages: "Phone number must include area code" beats "Invalid phone number." +- Inline placement: errors appear next to the field, not in a banner. +- Specific guidance: "Try a value between 1 and 1000" beats "Out of range." + +Detail in [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon, and how to fix it. + +Step-by-step drop-off tracking. Track the percentage of users who reach each step and the percentage who complete it. The diagnostic data informs which steps need redesign. + +Common drop-off points. + +- First field. User clicked into the form, looked at it, and left. Often signals the form is too long or the value of completing is not clear. +- Mid-form. User abandoned mid-process. Often signals fatigue, sensitive questions, or unclear progress. +- Final submission. User completed all fields but did not submit. Often signals submission anxiety, validation error fear, or unclear next-step. + +Remediation patterns. + +- First-field drop-off. Reduce form length; clarify the value of completing; add social proof or trust signals. +- Mid-form drop-off. Audit the specific step where drop-off concentrates; add progress indicator; reduce field count on that step; reword sensitive questions. +- Final-submission drop-off. Add a confirmation step; reduce final-step requirements; clarify what happens after submission. + +The instrumentation requirement. Without per-step tracking, drop-off remediation is guesswork. Set up tracking before the form launches. + +Detail in [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md). + +--- + +## Form anti-patterns + +Patterns that look like multi-step forms but degrade conversion. + +The kitchen-sink-single-page. 30 fields on one page. Detail in keystone framing. + +The progress-theater form. Steps without genuine staging. Detail in keystone framing. + +The arbitrary-chunking form. Each step has 1-2 fields; user wonders why this is multi-step. + +The hidden-length form. No progress indicator; user does not know how long the form is; abandonment climbs. + +The interrogation-form-with-steps. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The validation-strict form. Validation that rejects too aggressively, frustrating users with valid inputs. + +The mobile-broken form. Form works on desktop, breaks on mobile. + +The trust-broken form. Save-and-resume offered without clear trust communication; user does not save because they distrust persistence. + +The variable-step form. Conditional logic that changes the step count visibly; user feels misled about remaining work. + +Detail in [`references/form-anti-patterns.md`](references/form-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md). + +- "Form converts at 4 percent; we expected 12 percent." Likely too long, or the value of completing is not clear, or the form is mobile-broken. +- "Drop-off concentrates at step 3." Specific-step issue; audit step 3's field count, sensitivity, and clarity. +- "Mobile completion is half of desktop." Mobile design issue; audit form behavior on actual devices. +- "Validation rejects valid inputs." Validation strictness; relax the validation or improve the input formats accepted. +- "Users abandon at submission." Final-step anxiety; add confirmation, reduce final requirements, clarify next step. +- "Save-and-resume is offered but nobody uses it." Trust communication missing; users do not save because they distrust persistence. +- "We added conditional logic; the form feels confusing." Conditional logic complexity outweighs benefit; simplify. +- "We split the form into more steps; conversion did not change." Steps were not coherent; progress-theater pattern. +- "Progress indicator shifts mid-form." Conditional logic added steps unexpectedly; either fix the indicator or fix the conditional logic. + +--- + +## The framework: 12 considerations for multi-step form design + +When designing or auditing a multi-step form, walk these 12 considerations. + +1. The multi-step decision. Is multi-step the right structure for this data and audience, or would single-page serve? +2. Genuinely-staged, not kitchen-sink or progress-theater. Each step represents a coherent unit of work from the user's perspective. +3. Step architecture sound. Identity, context, need, detail, confirmation. Low-friction first; commitment compounds. +4. Progress indicator honest. Reflects actual remaining work; does not shift mid-form. +5. Conditional logic adds value. Removes irrelevant fields without adding maintenance overhead. +6. Save-and-resume mechanics fit the form. Offered when the form length warrants; trust clearly communicated. +7. Validation strategy matched to form. Per-step for required fields; end-only for nuanced validation. +8. Drop-off measurement instrumented. Per-step tracking from launch. +9. Mobile experience tested. Form works on the devices the audience uses. +10. Field count audited. Each field necessary; non-essential fields removed. +11. Final-step clear. Submission action obvious; what happens after submission communicated. +12. Maintenance discipline. Quarterly review of conversion, drop-off, validation, and conditional logic. + +The output of the framework is a multi-step form that respects cognitive load, maintains completion intent, and converts the audience into the action the form is designed to capture. + +--- + +## Reference files + +- [`references/multi-step-decision-criteria.md`](references/multi-step-decision-criteria.md) - When to break into steps vs keep single-page. The conditions that warrant the multi-step structure. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. +- [`references/progress-indicator-patterns.md`](references/progress-indicator-patterns.md) - Step counter, progress bar, step list. When each works. Indicator failures. +- [`references/conditional-logic-patterns.md`](references/conditional-logic-patterns.md) - Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. +- [`references/save-and-resume-mechanics.md`](references/save-and-resume-mechanics.md) - When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. +- [`references/validation-strategy-patterns.md`](references/validation-strategy-patterns.md) - Per-step vs end-only vs hybrid. Validation message discipline. +- [`references/drop-off-measurement-and-remediation.md`](references/drop-off-measurement-and-remediation.md) - Step-by-step tracking. Common drop-off points and remediation patterns. +- [`references/form-anti-patterns.md`](references/form-anti-patterns.md) - The patterns that look like multi-step forms but degrade conversion. +- [`references/common-multi-step-form-failures.md`](references/common-multi-step-form-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: multi-step forms earn completion when each step earns its place + +The multi-step forms that work as compounding assets are the ones the audience completes without resentment. Not because the form is short. Not because the steps are decorative. Because each step represented a coherent unit of cognitive work the user could complete with confidence, and the cumulative experience felt guided rather than obstructed. + +That is the bar. Below the bar are kitchen-sink-single-pages (overwhelm before the user starts) and progress-theater forms (decorative steps without coherence). Above the bar are genuinely-staged forms where the structure earns its complexity. + +The discipline is in the design choices upstream of the form. The decision to make the form multi-step (or not). The step architecture that makes each step coherent. The progress indicator that reflects honest progress. The conditional logic that removes friction without adding confusion. The validation that catches errors helpfully. The drop-off measurement that informs ongoing improvement. diff --git a/skills/multi-step-form-design/references/common-multi-step-form-failures.md b/skills/multi-step-form-design/references/common-multi-step-form-failures.md new file mode 100644 index 0000000..7281d88 --- /dev/null +++ b/skills/multi-step-form-design/references/common-multi-step-form-failures.md @@ -0,0 +1,187 @@ +# Common multi-step form failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "the form did not convert" or "audiences abandon mid-form" or "we cannot tell what is going wrong." + +--- + +## "Form converts at 4 percent; we expected 12 percent." + +The diagnosis. Likely one of: too long, value of completing not clear, mobile-broken, or the audience-fit is wrong. + +The cure. Audit the form length (`references/multi-step-decision-criteria.md`); audit the value proposition on the landing page (`landing-page-copy`); test on mobile devices; verify the audience matches the form's purpose. + +--- + +## "Drop-off concentrates at step 3." + +The diagnosis. Specific-step issue. Audit step 3's field count, sensitivity, and clarity. + +The cure. Per-step audit. Reduce field count if step 3 has too many; reword sensitive questions; clarify why step 3 is needed; consider whether step 3's content belongs there at all. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## "Mobile completion is half of desktop." + +The diagnosis. Mobile design issue. The form was designed for desktop and breaks on mobile. + +The cure. Mobile-first redesign. Touch-friendly inputs, single question per screen on long steps, sliders sized for thumb interaction, progress indicator visible without scroll. Test on actual devices. + +--- + +## "Validation rejects valid inputs." + +The diagnosis. Validation strictness. Rules are over-specified, rejecting inputs the system can handle. + +The cure. Audit validation rules (`references/validation-strategy-patterns.md`). Email with plus-signs, international phone formats, non-Latin names should all pass. + +--- + +## "Users abandon at submission." + +The diagnosis. Final-step anxiety. The CTA is unclear; the user does not know what happens; the final field requires information they did not have. + +The cure. Clarify the CTA ("Get my PDF" beats "Submit"). Add post-submission preview. Add a confirmation step. Move final-field demands earlier if the user needs time to gather info. + +--- + +## "Save-and-resume is offered but nobody uses it." + +The diagnosis. Trust communication missing. Users do not save because they distrust persistence. + +The cure. Trust copy alongside the save option. What is saved, how long, who can access. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## "We added conditional logic; the form feels confusing." + +The diagnosis. Conditional logic complexity outweighs benefit. Either too many rules or rules that change the user's experience visibly without explanation. + +The cure. Simplify the conditional logic. Remove rules that do not justify their value. Communicate variability if it remains. Detail in `references/conditional-logic-patterns.md`. + +--- + +## "We split the form into more steps; conversion did not change." + +The diagnosis. Steps were not coherent. Progress-theater pattern. Splitting fields without grouping them into meaningful units does not produce the multi-step benefit. + +The cure. Restructure into genuinely-staged steps. Each step should represent a coherent unit of cognitive work. Detail in `references/step-architecture-patterns.md`. + +--- + +## "Progress indicator shifts mid-form." + +The diagnosis. Conditional logic added or removed steps unexpectedly. + +The cure. Either fix the indicator to handle conditional steps honestly, or fix the conditional logic to not change step counts visibly. Detail in `references/progress-indicator-patterns.md`. + +--- + +## "We cannot tell where users abandon." + +The diagnosis. Instrumentation missing. No per-step tracking. + +The cure. Add per-step tracking before any further changes. Without data, remediation is guesswork. Detail in `references/drop-off-measurement-and-remediation.md` (instrumentation requirement). + +--- + +## "Conversion is fine; lead quality is poor." + +The diagnosis. The form is converting the wrong audience. Either the audience-fit on the landing page is broad, or the form does not filter for the audience the team needs. + +The cure. Tighten the audience-fit upstream. The form may need fewer fields (less interrogation) but more qualifying fields (audience-segmentation). Detail in `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Conversion was strong at launch; it has declined 30 percent over a year." + +The diagnosis. Form decay. Stale references, broken integrations, validation rules that no longer match reality. + +The cure. Quarterly maintenance audit. Update references, fix broken integrations, refresh validation rules. + +--- + +## "We A/B tested adding a progress indicator; conversion did not change." + +The diagnosis. Either the form was already short enough that an indicator was not needed, or the indicator was poorly designed (dishonest, hidden, or confusing). + +The cure. Audit the indicator's design. If the form is genuinely short (3-4 steps), the indicator may not lift conversion much. If the form is longer, the indicator should help; redesign if it is not. + +--- + +## "The form looks great in QA; users complain it is broken." + +The diagnosis. QA tested with the team's devices and browsers; users have different setups. + +The cure. Cross-browser, cross-device, cross-network testing. Consider real-world conditions (slow connections, older devices, accessibility tools). + +--- + +## "The form's submit button is gray; we cannot figure out why." + +The diagnosis. Validation logic is preventing submission but the error is not surfaced. Common cause: a hidden required field or a cross-field validation that fails silently. + +The cure. Surface all validation errors visibly. Submit button state should follow form state visibly; the user should see why submit is disabled. + +--- + +## "We added save-and-resume; nobody resumes." + +The diagnosis. Either users save but the recovery link does not arrive, or the resume experience is broken, or the form's value did not persist (the user's interest faded). + +The cure. Test the recovery email deliverability. Test the resume experience end-to-end. Consider whether save-and-resume is genuinely needed or whether it is decorative. + +--- + +## "Sales says the form-sourced leads are wrong type." + +The diagnosis. Audience-fit mismatch. The form is converting the wrong segment. + +The cure. Audit the form's qualifying fields and the landing page that drives traffic. Either tighten the audience filter at the landing page, or add qualifying fields to the form that route based on segment. + +--- + +## "We made the form shorter; submissions went up but lead quality went down." + +The diagnosis. The fields removed were qualifying fields. Conversion improved because friction dropped; quality dropped because the qualifying signal was lost. + +The cure. Decide whether quality or quantity matters more. Restore qualifying fields if quality matters; accept the lower quality if volume is the priority. Often the right answer is to restore some fields and accept some conversion impact. + +--- + +## "The form works on Chrome desktop; it crashes on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The form was tested on the team's primary platform. + +The cure. Cross-browser, cross-device testing. The audience uses what they use. + +--- + +## "We translated the form to Spanish; conversion is half what English is." + +The diagnosis. Translation quality, cultural mismatch, or audience-fit issue specific to the Spanish-speaking audience. Often a combination. + +The cure. Audit the translation quality (idiomatic vs literal). Audit cultural assumptions (date formats, phone formats, name conventions). Verify the audience matches. + +--- + +## The pattern across failures + +Most multi-step form failures fall into one of three patterns. + +Pattern 1: The form is the wrong structure. Kitchen-sink-single-page, progress-theater, arbitrary-chunking, hidden-length. The fix is structural. + +Pattern 2: The form does not match the audience or the device. Mobile-broken, validation-strict-against-international-inputs, audience-fit weak. The fix is matching the form to where the audience actually is. + +Pattern 3: The form decays. Stale references, broken integrations, drift in conditional logic, instrumentation drift. The fix is maintenance discipline. + +The metric pattern: form failures often look fine on submission count alone. The signal is in completion rate, drop-off per step, lead quality, and downstream conversion. Programs that track only submission counts keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (structure, audience-device match, decay). The principle that submission count alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/multi-step-form-design/references/conditional-logic-patterns.md b/skills/multi-step-form-design/references/conditional-logic-patterns.md new file mode 100644 index 0000000..c24901b --- /dev/null +++ b/skills/multi-step-form-design/references/conditional-logic-patterns.md @@ -0,0 +1,270 @@ +# Conditional logic patterns + +Show/hide fields, skip steps, adapt language. Strengths, risks, simplicity preference. + +Conditional logic responds to earlier answers and removes irrelevant fields. Done well, it makes the form feel adaptive and intelligent. Done poorly, it adds maintenance complexity without improving the user experience. + +--- + +## The relevance principle + +Show only fields that are relevant to the user's situation. Skip fields that do not apply. + +The principle's win. A user who answered "no, I do not have a CRM today" should not be asked "what CRM do you use today" three steps later. The conditional logic removes the friction. + +The principle's risk. Conditional logic adds maintenance complexity. Each branch has to be tested. Each branch can break. The simplicity preference: add conditional logic only when it produces real value. + +--- + +## Pattern A: Show or hide fields based on previous answers + +The most common conditional logic pattern. + +How it works. + +- A field appears or disappears based on the answer to an earlier question. +- "If user selected 'enterprise,' show enterprise-specific fields." +- "If user selected 'has current solution,' show 'current solution name' field." + +Example. + +Question: "Do you currently use a CRM?" +- Yes → show field "Which CRM do you use today?" +- No → hide that field; show "What is your current process for managing customer data?" + +The form adapts to the user's situation in real time. + +Strengths. + +- Removes irrelevant fields. +- Makes the form feel intelligent. +- Reduces drop-off because users do not abandon over fields that did not apply. + +Weaknesses. + +- Each branch needs testing. +- Late additions to the form can break conditional logic in unexpected ways. + +When to use. When showing all fields would be confusing or when irrelevant fields cause significant drop-off. + +--- + +## Pattern B: Skip entire steps + +Conditional logic at the step level. + +How it works. + +- Based on early answers, an entire step is skipped or included. +- "If user does not have a current CRM, skip the 'CRM details' step entirely." +- "If user is in healthcare, include the 'compliance requirements' step." + +Strengths. + +- Removes whole sections of irrelevant content. +- Form length adapts to the user. + +Weaknesses. + +- Progress indicators must adapt or honestly disclose variability. +- The user may notice the form's variability and feel confused. + +When to use. When entire categories of fields are irrelevant to some users (e.g., enterprise-only fields for non-enterprise users). + +--- + +## Pattern C: Adapt the language + +Conditional logic that changes terminology based on user context. + +How it works. + +- The form's wording adapts to the user's industry, role, or context. +- "If user is in healthcare, use 'patient' terminology in subsequent fields." +- "If user is technical, use technical terms; if non-technical, use plain language." + +Strengths. + +- Form feels personalized. +- Reduces cognitive load on the user (they see terminology that matches their context). + +Weaknesses. + +- Significantly more copy to maintain. +- Risk of inconsistent or awkward language. + +When to use. When the audience spans contexts where terminology genuinely differs (B2C vs B2B, technical vs non-technical, regulated vs unregulated industries). + +--- + +## Pattern D: Adapt the destination + +Conditional logic that affects what happens after submission. + +How it works. + +- Based on answers, the form routes to different teams or triggers different follow-ups. +- "If user selected 'integration question,' route to the integration team after submission." +- "If user selected 'enterprise,' trigger an enterprise-sales follow-up sequence." + +Strengths. + +- The user gets matched to the right team or sequence. +- Sales and support efficiency improve. + +Weaknesses. + +- Routing complexity grows; failure modes (wrong team, missed routing) increase. +- The user does not see the routing logic; mistakes are invisible to the user but visible in downstream impact. + +When to use. When the form serves multiple downstream paths and the routing materially affects the user's experience. + +--- + +## Pattern E: Branching forms + +Different paths through the form for different users. + +How it works. + +- Based on early answers, the user takes a different path entirely. +- "If user selects 'individual,' show the individual flow; if 'team,' show the team flow." + +Strengths. + +- Highly tailored experience. +- Each user only sees fields relevant to them. + +Weaknesses. + +- Significantly more complex to build and test. +- Hard to compare paths because users took different forms. +- Maintenance is hard. + +When to use. When the audience genuinely splits into distinct groups that need fundamentally different forms. Use sparingly. + +--- + +## The simplicity preference + +Add conditional logic only when it produces real value. + +The discipline. For each piece of conditional logic, ask: +- Does this remove genuine friction? +- Is the maintenance cost justified by the friction removed? +- Could a simpler approach (single-page with sectioned design) achieve the same goal? + +The over-conditional form. A form with 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively, the form is fragile and hard to maintain. + +The cure. Audit conditional logic periodically. Remove rules that do not justify their maintenance overhead. + +--- + +## Conditional logic and progress indicators + +The interaction matters. + +The challenge. A form with conditional steps may have variable total step count. The progress indicator must accommodate. + +Approaches. + +- Variable indicator. "Step 2 of 5-7" or "Step 2 (about halfway)." Communicates the variability. +- Range indicator. "Step 2 of about 5." Approximate but honest. +- Dynamic indicator. Updates as the user's answers determine the path. Risk of feeling unstable. +- Step-list indicator. Shows all possible steps; current step highlighted. Variability visible upfront. + +The discipline. Choose an approach that does not lie about progress. + +--- + +## Conditional logic testing + +Test every branch of conditional logic. + +The challenge. A form with 5 conditional rules has 32 possible paths through the form. Testing all paths is infeasible at scale; testing critical paths is the discipline. + +Critical paths. + +- The most common path (most frequent user type). +- Each conditional rule's branch (one path that triggers it, one that does not). +- Edge cases (combinations that could produce unexpected behavior). + +Testing methods. + +- Manual testing. Walk through critical paths. +- Automated testing. Programmatic tests for each branch. +- User testing. Watch users complete the form; surface confusion or paths that break. + +Production monitoring. Track which paths users take. Sudden shifts may indicate logic issues. + +--- + +## Conditional logic and analytics + +Track which conditional branches trigger. + +Why. Understanding which branches are common informs maintenance priorities. A branch nobody triggers may not be worth maintaining; a branch everyone triggers may not need to be conditional. + +The metric. Per-branch trigger rate. Per-branch conversion rate. + +The discipline. Periodically review the data. Retire conditional rules that do not pay off. + +--- + +## Conditional logic and form maintenance + +Conditional logic decays. + +What decays. + +- Rules that point to fields that have been renamed or removed. +- Rules that produce paths now unused as the audience shifts. +- Rules whose triggering questions have been reworded. + +Maintenance cadence. Quarterly audit alongside the broader form audit. + +The drift indicator. Bug reports about specific paths failing; analytics showing unexpected branching behavior; testing surfaces broken rules. + +--- + +## Common conditional logic failures + +Hidden complexity. Many rules silently affecting many fields; the form's behavior is hard to reason about. + +Unintended interactions. Two rules that work individually but conflict when combined. + +Stale rules. Rules that point to fields no longer in the form. + +Dead branches. Conditional paths nobody triggers; maintenance overhead with no payoff. + +Indicator-rule mismatch. Progress indicator that does not handle conditional step count. + +Untested edge cases. Unusual answer combinations that produce broken paths. + +Rule-driven layout shifts. Fields appearing and disappearing causing visual jumpiness. + +Over-conditional forms. 25+ rules across the form; the maintenance burden exceeds the friction-reduction value. + +--- + +## When NOT to use conditional logic + +Some situations work better without conditional logic. + +Short forms. Adding conditional logic to a 5-field form rarely justifies the complexity. + +Forms with stable audiences. When everyone takes roughly the same path, conditional logic adds variability without value. + +Forms in early stages. A new form benefits from simplicity before adding complexity. Launch simple; add conditional logic when data shows where it would help. + +Forms with high maintenance constraints. Teams that cannot maintain complex forms should default to simpler designs. + +--- + +## Methodology-level choices that stay in the public skill + +The relevance principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. The simplicity preference. Conditional logic and progress indicators. Conditional logic testing. Conditional logic and analytics. Maintenance considerations. Common failures. When NOT to use conditional logic. + +## Implementation choices that stay internal + +Specific conditional rules for specific forms. Specific tooling for rule implementation and testing. The team's audit calendars and rule-retirement processes. These vary by team. diff --git a/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md b/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md new file mode 100644 index 0000000..7f88000 --- /dev/null +++ b/skills/multi-step-form-design/references/drop-off-measurement-and-remediation.md @@ -0,0 +1,263 @@ +# Drop-off measurement and remediation + +Step-by-step tracking. Common drop-off points and remediation patterns. + +Drop-off is where the form fails. Measuring drop-off per step is the diagnostic that informs every other improvement. Without per-step tracking, drop-off remediation is guesswork. + +--- + +## The instrumentation requirement + +Set up per-step tracking before the form launches. + +The minimum tracking. + +- Step start. User landed on this step. +- Step completion. User completed this step (clicked Next). +- Step abandonment. User left without completing. + +The derived metrics. + +- Step completion rate. Of users who reached this step, what percentage completed it? +- Step drop-off rate. Of users who reached this step, what percentage abandoned at this step? +- Funnel completion rate. Of users who started the form, what percentage submitted? + +Why instrumentation matters. Drop-off remediation requires knowing where users abandon. Aggregate "the form converts at 8 percent" tells you something is wrong; per-step data tells you where. + +--- + +## Common drop-off points + +Three patterns recur across multi-step forms. + +First-field drop-off. User clicked into the form, looked at it, and left at the first field. + +Common causes. +- Form is too long; user saw the length and bounced. +- The value of completing is not clear; user does not know what they get. +- Form is mobile-broken; user could not interact. +- Form looks suspicious or untrustworthy. + +Mid-form drop-off. User abandoned partway through. + +Common causes. +- Fatigue; the form is too long and the user lost interest. +- Sensitive question they did not want to answer. +- Confusion about what is being asked. +- Loading delay or technical issue. +- The form's value did not justify the continued effort. + +Final-submission drop-off. User completed all fields but did not submit. + +Common causes. +- Submission anxiety; the user is not sure what happens next. +- Validation errors at submission lost them. +- The submission CTA is not clear. +- Final field requires information they did not have ready. + +--- + +## Remediation: first-field drop-off + +When users abandon at the first field. + +Diagnostic questions. + +- Is the form's value proposition clear at the start? +- Is the form length visible (creating bounce-on-length behavior)? +- Does the form work on mobile? +- Are trust signals present (privacy policy, security badges where appropriate)? + +Remediation patterns. + +- Clarify the value. "Get a personalized PDF in 5 minutes" beats "Fill out this form." +- Hide the length. Multi-step forms hide subsequent steps; the user does not see "this will take 20 minutes" upfront. +- Add social proof. "Trusted by 5000 teams" or "Used by [recognizable customer]" reduces hesitation. +- Add trust signals. Privacy assurance, security indicators, or testimonial near the form. +- Reduce form to single page. Sometimes the right answer is to revert from multi-step to single-page. + +The diagnostic test. A/B test variations. The treatment that improves first-field completion validates the diagnosis. + +--- + +## Remediation: mid-form drop-off + +When users abandon partway through. + +Diagnostic. + +- Which specific step has the highest drop-off? +- Are there sensitive questions on that step? +- How long does that step take to complete? +- Is the step's relevance clear? + +Remediation patterns. + +- Reduce field count on the high-drop-off step. Audit each field; remove non-essential fields. +- Reword sensitive questions. "How much do you spend on this today" beats "What is your annual budget?" Soft framing reduces abandonment. +- Add progress indicator if missing. Users abandon less when they know how much remains. +- Add encouragement at the high-drop-off step. "You are halfway there; just a few more questions to get your personalized result." +- Restructure the step architecture. If step 3 is a drop-off black hole, the architecture may be wrong; reconsider whether step 3's content belongs there at all. + +The diagnostic test. Watch real users complete the form (usability testing). The behavior often reveals the cause. + +--- + +## Remediation: final-submission drop-off + +When users complete fields but do not submit. + +Diagnostic. + +- Is the submission CTA clear? +- Does the user know what happens after submission? +- Are there validation errors at submission? +- Is the final field demanding information they did not have ready? + +Remediation patterns. + +- Clarify the submission CTA. "Get my personalized PDF" beats "Submit." The CTA should describe what the user gets. +- Add post-submission preview. "When you submit, we will email you within 5 minutes with..." sets expectations. +- Move final-field demands earlier. If the final field requires hard-to-find information, move it earlier so users gather it during the form. +- Add a confirmation step. A review-and-submit step where the user verifies their inputs reduces submission anxiety. +- Validation pre-submission. Surface errors before the user clicks Submit; do not let submission fail with surprise errors. + +--- + +## Tracking conditional-logic paths + +Multi-step forms with conditional logic have multiple paths through the form. + +Per-path tracking. + +- Tag each user's path through the form. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +Path-specific remediation. + +- A path that drops off at step 4 may need step-4 redesign for users on that path. +- A path that drops off rarely may not need attention. + +The instrumentation challenge. Conditional-logic paths multiply quickly. Track at the granularity that informs decisions, not at the granularity that overwhelms. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +Segment-level tracking. + +- Tag users by source, device, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +Common segment patterns. + +- Mobile users drop off more at long steps; desktop users push through. +- Paid-traffic users drop off earlier than organic; the audience-fit may be weaker. +- New visitors drop off more than returning visitors; trust matters. + +Remediation by segment. Sometimes the right answer is segment-specific. Mobile users may benefit from a shorter form variant; paid traffic may benefit from stronger trust signals. + +--- + +## Drop-off and time-of-completion + +Some drop-off correlates with how long the form takes. + +Time-to-complete tracking. + +- Average time per step. +- Total time across the form. +- Time-to-completion distribution. + +Patterns. + +- Forms taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Distribution skew (some users fast, some users slow) often signals usability issues that affect the slow users. + +Remediation by time. Forms taking too long should be shortened; steps taking too long should be split or simplified. + +--- + +## Drop-off audit cadence + +How often to audit drop-off data. + +Weekly review. For high-volume forms or recently launched forms. Catches regressions and informs rapid iteration. + +Monthly review. For stable forms. Tracks trends and surfaces gradual decay. + +Quarterly review. For all active forms as part of the broader form audit. + +Triggered review. When form structure changes, when traffic source shifts, or when conversion drops. Ad-hoc reviews catch specific issues. + +The cadence depends on traffic volume and the form's importance. High-traffic forms warrant more frequent attention. + +--- + +## A/B testing for drop-off remediation + +Test remediation hypotheses rather than guessing. + +The discipline. Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall conversion. + +Common test types. + +- Form length: shorter vs longer. +- Step count: fewer vs more steps. +- Field count: fewer vs more fields per step. +- Validation strictness: stricter vs looser. +- Progress indicator: present vs absent. +- Trust signals: present vs absent. + +Test discipline. + +- One treatment variable per test. +- Long enough to capture statistical significance. +- Measure both the targeted metric and downstream metrics. + +The data informs which remediation actually moves the metric. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +The signal. The wrong audience self-selecting out is honest filtering. A multi-step form that drops 60 percent of visitors but produces 5x the qualified leads vs a single-page form is doing its job. + +The discipline. Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream metrics (lead quality, conversion to next step) reveal which is happening. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. Sometimes the right answer is to accept higher drop-off in exchange for higher qualification. + +--- + +## Common measurement failures + +No instrumentation. Form launched without per-step tracking; drop-off data unavailable. + +Aggregate-only tracking. Conversion rate tracked but not step-by-step; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; field renames or step changes broke the tracking. + +Confounded data. Multiple changes deployed simultaneously; cannot attribute conversion change to any one change. + +Vanity metrics. Tracking number of starts without tracking completion; the high-volume forms look successful even when conversion is poor. + +Segment-blind tracking. Aggregate data hides segment-specific issues. + +Time-blind tracking. No data on time-to-complete; cannot diagnose fatigue-driven drop-off. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points (first-field, mid-form, final-submission) with diagnoses and remediation patterns. Tracking conditional-logic paths. Drop-off and audience segmentation. Drop-off and time-of-completion. Audit cadence. A/B testing for drop-off remediation. When drop-off is signal not failure. Common measurement failures. + +## Implementation choices that stay internal + +Specific drop-off baselines for specific forms. Specific tooling for tracking and analysis. Specific A/B test designs and treatments. The team's audit calendars. These vary by team and form. diff --git a/skills/multi-step-form-design/references/form-anti-patterns.md b/skills/multi-step-form-design/references/form-anti-patterns.md new file mode 100644 index 0000000..999e4c7 --- /dev/null +++ b/skills/multi-step-form-design/references/form-anti-patterns.md @@ -0,0 +1,224 @@ +# Form anti-patterns + +The patterns that look like multi-step forms but degrade conversion. Anti-patterns are easy to ship; the cost shows up in completion rates, lead quality, and brand reputation over time. + +--- + +## The kitchen-sink-single-page + +The pattern. 30 fields on one page. Overwhelms before the user starts. + +The signal. First-field drop-off near 100 percent on anything beyond a contact form. Users scroll, see the length, and leave. + +The cost. The form's data collection is correct; the structure is wrong; nobody completes it. + +The cure. Multi-step the form; group fields into coherent steps. Detail in `references/multi-step-decision-criteria.md` and `references/step-architecture-patterns.md`. + +--- + +## The progress-theater form + +The pattern. The form is broken into steps but the steps are arbitrary. "Step 1: name. Step 2: email. Step 3: phone." + +The signal. Completion rate marginally better than kitchen-sink; users feel the form is gimmicky; some abandon mid-form because each step feels pointless. + +The cost. The build effort produced a form that is no better than the alternative. The audience perceives the format as decorative. + +The cure. Restructure into genuinely-staged steps. Detail in `references/step-architecture-patterns.md`. + +--- + +## The arbitrary-chunking form + +The pattern. Each step has 1-2 fields; the user wonders why this is multi-step. + +The signal. Quick completions but high abandonment; the format adds friction without value. + +The cost. The user perceives the form as gimmicky; trust degrades. + +The cure. Either consolidate to single-page (if the form has only 4-6 fields) or expand the staging to coherent units (if the form has more fields that group naturally). + +--- + +## The hidden-length form + +The pattern. No progress indicator; the user does not know how long the form is. + +The signal. Mid-form drop-off climbs as users lose patience; abandonment correlates with time spent. + +The cost. Users who would have completed if they knew the length abandon out of uncertainty. + +The cure. Add an honest progress indicator. Detail in `references/progress-indicator-patterns.md`. + +--- + +## The interrogation-form-with-steps + +The pattern. 25 fields across 5 steps; the format is multi-step but the data collection is excessive. + +The signal. Drop-off at every step; cumulative completion rate is poor; the form earns "interrogation" reputation. + +The cost. The audience that completes is over-disclosed and may resent the friction; the audience that does not complete walks away with a negative impression. + +The cure. Audit the field set. Remove fields that are not necessary for the form's purpose. The right field count is often half what teams initially design. + +--- + +## The validation-strict form + +The pattern. Validation rejects valid inputs because the rules are over-specified. Email validation rejects plus-sign aliases; phone validation rejects international formats; name validation rejects non-Latin characters. + +The signal. Users with valid but unusual inputs abandon when validation fails. Reports of "the form would not let me submit." + +The cost. The form filters out valid users. The team perceives the form as working because submissions look clean; the team does not see the audience that could not get past validation. + +The cure. Audit validation rules against actual business requirements. Detail in `references/validation-strategy-patterns.md`. + +--- + +## The mobile-broken form + +The pattern. Form works on desktop; breaks on mobile. Sliders impossible to grab; dropdowns overflow; touch targets too small. + +The signal. Mobile completion drops to half of desktop or worse. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Test on actual devices, not just dev tools. + +--- + +## The trust-broken form + +The pattern. Save-and-resume offered without clear trust communication. Users do not save because they distrust persistence. + +The signal. Save-rate is low; users abandon mid-form rather than save. + +The cost. The save mechanism's investment produces no value; the audience that would have saved instead leaves permanently. + +The cure. Trust communication. What is saved, what is not, how long it persists, who can access it. Detail in `references/save-and-resume-mechanics.md`. + +--- + +## The variable-step form + +The pattern. Conditional logic that changes the step count visibly. "Step 4 of 5" becomes "Step 4 of 7" mid-form. + +The signal. Users feel misled; abandonment climbs at the moment the indicator shifts. + +The cost. Trust damage. The user trusted the indicator; the indicator lied. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). Detail in `references/progress-indicator-patterns.md`. + +--- + +## The submission-anxiety form + +The pattern. The submit button is unclear, or the user does not know what happens after submission, or the final step demands information they did not have ready. + +The signal. Final-submission drop-off is high; users completed all fields but did not submit. + +The cost. The form gets near-completion and loses the conversion at the last step. + +The cure. Clear submission CTA, explicit post-submission preview, optional confirmation step. Detail in `references/drop-off-measurement-and-remediation.md`. + +--- + +## The popup-interrupted form + +The pattern. The user is mid-form; a popup appears (newsletter signup, chat invitation, special offer). The user's flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about the interruption. + +The cost. The form's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Suppress popups during form completion. Save promotional content for after submission or for the next visit. + +--- + +## The reset-on-error form + +The pattern. The user submits; validation fails; the form resets, losing the user's inputs. + +The signal. Users who hit the error do not retry; they leave. + +The cost. The form treats errors punitively. Trust collapses. + +The cure. Preserve inputs on error. Show the error inline; let the user fix and resubmit without re-entering everything. + +--- + +## The slow-validation form + +The pattern. Real-time validation that lags. The user types; validation runs; the form feels sluggish. + +The signal. Users feel the form is slow; abandonment climbs at long-validation steps. + +The cost. The form's perceived performance damages the brand. + +The cure. Move validation to on-blur (when the user leaves the field) instead of on every keystroke. Reserve real-time validation for instant checks (format, character count). + +--- + +## The incompatible-with-autofill form + +The pattern. Form does not support browser autofill. The user has to type every field manually. + +The signal. Mobile completion is worse than desktop; users with password managers abandon. + +The cost. The form treats users as if autofill does not exist. Friction without justification. + +The cure. Support standard autofill attributes. Use semantic HTML input types. Test with browser autofill enabled. + +--- + +## The save-but-lose-on-resume form + +The pattern. Save-and-resume offered; user saves; resume returns the user to the start of the form, losing their progress. + +The signal. Resume rate is high (users click the recovery link) but completion rate from resume is low (users abandon when they see they have to redo work). + +The cost. The save mechanism's apparent value disappears at resume; trust collapses worse than if save had not been offered. + +The cure. Test the resume experience. Verify that resuming returns the user to their actual progress with inputs preserved. Detail in `references/save-and-resume-mechanics.md` (resume experience section). + +--- + +## The over-conditional form + +The pattern. 25 conditional rules across 8 fields. Each rule individually justifiable; cumulatively the form is fragile and hard to maintain. + +The signal. Bug reports about specific paths failing; testing surfaces broken rules; conditional logic decays unnoticed. + +The cost. Maintenance burden compounds. Form behavior becomes hard to reason about. + +The cure. Audit conditional logic. Remove rules that do not justify their maintenance overhead. Detail in `references/conditional-logic-patterns.md`. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active form, looking specifically for these anti-patterns. + +Audit questions per form. + +- Does the form have natural step groupings (anti-pattern check: progress-theater, arbitrary-chunking)? +- Is the progress indicator honest and stable (anti-pattern check: hidden-length, variable-step)? +- Does each field affect the form's outcome (anti-pattern check: interrogation-form)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Does the form work on mobile (anti-pattern check: mobile-broken)? +- Is save-and-resume tested end-to-end (anti-pattern check: save-but-lose-on-resume, trust-broken)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is conditional logic maintained (anti-pattern check: over-conditional)? + +The retire decision. Anti-pattern forms often warrant retirement or redesign. Maintaining broken forms costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement and redesign decisions. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/multi-step-form-design/references/multi-step-decision-criteria.md b/skills/multi-step-form-design/references/multi-step-decision-criteria.md new file mode 100644 index 0000000..92ced61 --- /dev/null +++ b/skills/multi-step-form-design/references/multi-step-decision-criteria.md @@ -0,0 +1,159 @@ +# Multi-step decision criteria + +When to break a form into steps vs keep it on a single page. The conditions that warrant the multi-step structure, and the funnels where multi-step adds friction without lift. + +A multi-step form is a meaningful build. Step architecture, progress indicators, conditional logic, validation, save-and-resume, drop-off instrumentation. The multi-step form earns this investment only when specific conditions are present. + +--- + +## When multi-step earns the build + +Five conditions that, when present, make multi-step the right structure. + +The form has more than 8-10 fields. Single-page forms beyond this point overwhelm the audience visually. The user scrolls, sees the length, and leaves. Multi-step breaks the visual length into manageable pieces. + +The fields naturally group into logical categories. Personal info, then situation, then preferences, then specifics. Steps that reflect real groupings respect cognitive load. Arbitrary chunking does not. + +The audience benefits from progressive commitment. Each step builds investment. The user is more likely to complete after engaging with step 2 than they would have been if they had seen step 5's complexity upfront. + +Different paths through the form make sense based on early answers. Conditional logic that adapts the form to the user is hard to do on a single page; multi-step makes the adaptation feel natural. + +The success metric warrants the build. Higher completion rate, lower drop-off, better lead quality, faster review for the receiving team. Without a defined success metric, the build is hard to justify. + +When all five are present, multi-step is a strong structure. When two or fewer are present, single-page often serves better. + +--- + +## When multi-step does NOT earn the build + +Funnels where multi-step is the wrong structure. + +The form has 4-6 fields. A single-page form is faster to complete and faster to maintain. Multi-step adds friction (step transitions, progress indicators, save-and-resume mechanics) without adding clarity. + +The fields do not group naturally. Arbitrary chunking is friction. "Step 1: name. Step 2: email. Step 3: phone." The user wonders why this is multi-step and the question itself signals friction. + +The audience expects speed. Quick contact forms, simple lead-capture forms, and high-intent CTAs often convert better as single-page. The multi-step format implies "this will take a while," which depresses high-intent users. + +The team cannot maintain the multi-step complexity. Multi-step forms have more failure modes (conditional logic bugs, progress indicator drift, validation issues across steps). The maintenance overhead is real; teams that cannot commit to it should choose single-page. + +The form is a follow-up to a hot conversation. A demo-request form right after a sales call should be quick. Multi-step here adds friction the audience is not ready for. + +The honest assessment matters more than the default. "Should the form be multi-step" is not the question. "Is multi-step the right structure for this specific data collection and audience" is. + +--- + +## The opportunity-cost frame + +A multi-step form is meaningful work. Account for the cost honestly. + +The build cost. Step architecture, progress indicators, conditional logic, save-and-resume, validation across steps, drop-off instrumentation. A meaningful multi-step form often takes 30-80 engineering hours plus design. + +The maintenance cost. Steps decay as the brand evolves; conditional logic bugs surface; progress indicators need updating. Quarterly review and maintenance run 2-6 hours per active form. + +The opportunity cost. What else could the team have built? A simpler form that converts adequately, a different growth-tooling investment, a content piece. The multi-step form's success has to clear the bar of those alternatives. + +The decision frame. The multi-step form earns investment when it produces more conversion than the single-page alternative, accounting for the full cost of build plus maintenance. + +--- + +## The grouping precondition + +Without natural field groupings, multi-step is arbitrary. + +The check. Can the fields be grouped into 3-5 coherent categories? Each category representing a unit of cognitive work the user can describe in one sentence? + +If yes, multi-step has natural step boundaries. + +If no (the fields do not group; the only structure is "first half" and "second half"), multi-step will feel arbitrary. Either restructure the data collection (some fields may not be needed) or choose single-page. + +Examples of natural groupings. + +- Identity (name, email, role) + Context (company size, industry, current setup) + Need (goal, challenge, timeline) + Confirmation. +- Personal info + Loan details + Property details + Financial verification + Submission (mortgage application). +- Account info + Use case + Plan selection + Payment + Confirmation (signup wizard). + +Examples of forced groupings. + +- Page 1 (name, email, phone) + Page 2 (company, role, source, industry, size). The page break is arbitrary; nothing groups these fields meaningfully. +- Page 1 (most fields) + Page 2 (one final field). The split is purely decorative. + +The discipline. If the team cannot articulate the unit of work each step represents, the steps are arbitrary; either rework the steps or use single-page. + +--- + +## The decision worked example + +A B2B SaaS company considering whether to make a "Talk to sales" form multi-step. + +Conditions check. + +- Field count: 12 fields (name, work email, company name, company size, industry, role, current solution, primary use case, timeline, budget range, source attribution, additional context). Above the 8-10 threshold; multi-step is on the table. +- Natural groupings: yes. Identity (name, email, role), company context (name, size, industry), current state (current solution, use case), buying intent (timeline, budget), additional (source, context). 5 natural groups. +- Progressive commitment: yes. The audience giving budget at the end after engaging with the early steps is more likely to give it than if asked upfront. +- Conditional logic value: yes. If the audience selects "evaluating" timeline, additional fields appear; if "active project," different additional fields appear. +- Success metric: defined. Conversion rate to submission, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo within 21 days. + +Decision. Build multi-step. The conditions warrant it. + +Step architecture. 5 steps: Identity, Company, Current State, Buying Intent, Submission Confirmation. + +Maintenance commitment. Quarterly audit of conversion, drop-off per step, and conditional logic. + +The decision was not "should we make this multi-step" but "given these conditions, this is the multi-step structure to build." + +--- + +## The single-page worked example + +The same B2B SaaS company considering whether to make a "Subscribe to newsletter" form multi-step. + +Conditions check. + +- Field count: 2 fields (email, name). Below the 8-10 threshold. +- Natural groupings: no. Two fields do not group. +- Progressive commitment: no. The audience subscribing benefits from speed. +- Conditional logic value: no. No branching needed. +- Success metric: simple conversion rate. + +Decision. Single-page. Multi-step would add friction without value. + +The decision was "what is the right structure" and the answer was single-page even though multi-step was nominally available. + +--- + +## The hybrid pattern + +Some forms work best with a "main" single-page form plus one optional follow-up step. + +The pattern. A short single-page form (3-5 fields) gets the user committed; an optional follow-up appears after submission for users who want personalization. + +When this works. When the primary action is fast (signup, lead-capture) but a richer follow-up benefits some users. + +When this does not work. When the follow-up has to be required for the primary action to be useful. + +The hybrid avoids both kitchen-sink-single-page and forced multi-step. It serves the speed-seeking audience and the depth-seeking audience separately. + +--- + +## When to retire a multi-step form (or convert to single-page) + +Multi-step forms can become wrong as the form evolves. + +Retire-or-convert when: + +- Field count has dropped below 6 over time as fields were removed. +- Conditional logic has been simplified out, leaving the steps with no real differentiation. +- Drop-off concentrates uniformly across steps, suggesting the staging is not working. +- A simpler single-page form might convert better. + +The conversion-to-single-page move. Sometimes the right answer is to revert. The multi-step format earned the build at one point; conditions changed; single-page is now better. Honest reversion is part of the discipline. + +--- + +## Methodology-level choices that stay in the public skill + +The conditions that warrant multi-step. The opportunity-cost frame. The grouping precondition. The decision worked example. The single-page worked example. The hybrid pattern. The retire-or-convert decision. + +## Implementation choices that stay internal + +Specific multi-step decisions for specific forms. The team's capacity benchmarks for build and maintenance. Specific tooling for form engineering. Specific success-metric definitions and baselines. These vary by team. diff --git a/skills/multi-step-form-design/references/progress-indicator-patterns.md b/skills/multi-step-form-design/references/progress-indicator-patterns.md new file mode 100644 index 0000000..2051213 --- /dev/null +++ b/skills/multi-step-form-design/references/progress-indicator-patterns.md @@ -0,0 +1,289 @@ +# Progress indicator patterns + +Step counter, progress bar, step list. When each works. Indicator failures. + +The progress indicator reinforces momentum and reduces uncertainty about how much is left. Bad indicators flatter or mislead; good indicators reflect honest progress. + +--- + +## The honesty principle + +The progress indicator must reflect actual remaining work. Indicators that flatter the user or hide remaining complexity break trust. + +The honest indicator. "Step 3 of 5" when there are exactly 5 steps and the user is on step 3. + +The dishonest indicator. + +- "Almost done" when 5 fields remain on the next step. +- Progress bar that fills to 80 percent when 50 percent of fields remain. +- Step counter that shifts from "5 of 7" to "5 of 9" because conditional logic added steps. + +The honesty discipline. Match the indicator to the actual work; do not flatter; communicate variability when it exists. + +--- + +## Pattern A: Step counter + +"Step 2 of 4." Simple, common, effective for short forms. + +How it works. + +- The current step number is shown. +- The total step count is shown. +- The format is consistent across the form. + +Strengths. + +- Easy to implement. +- Easy to understand. +- Compact. + +Weaknesses. + +- Does not reflect within-step progress. +- Misleading when step lengths vary significantly. +- Breaks if conditional logic changes the total step count. + +When to use. Forms with 3-6 steps where step lengths are roughly similar. + +--- + +## Pattern B: Progress bar + +Visual fill showing percentage complete. + +How it works. + +- A bar fills from left to right (or follows other visual progression). +- The fill represents percentage of fields completed (or percentage of weight in some weighted scheme). +- Optionally includes a percentage label. + +Strengths. + +- Reflects continuous progress. +- Handles variable-length steps better than step counter. +- Visually engaging. + +Weaknesses. + +- More complex to design and implement. +- Risk of dishonest fill (bar fills fast, last 10 percent represents most of the remaining work). + +When to use. Forms with variable step lengths or where the user benefits from continuous-progress signal. + +--- + +## Pattern C: Step list + +Named steps shown with the current one highlighted. + +How it works. + +- All step names visible (often in a sidebar or header). +- Current step highlighted. +- Completed steps marked (checkmark or different color). +- Future steps indicated. + +Strengths. + +- Shows the user the full form path. +- Reduces uncertainty about what is coming. +- Lets the user navigate back to specific steps. + +Weaknesses. + +- Takes more screen real estate. +- Can overwhelm if there are many steps. +- Forces the form to commit to step names upfront. + +When to use. Forms with 3-7 well-named steps where the user benefits from seeing the structure. + +--- + +## Pattern D: No indicator + +Sometimes appropriate for very short forms. + +When to use. + +- Forms with 2-3 steps where the indicator overhead exceeds its value. +- Forms where the user's expectation is "this is short" and the indicator would imply length. + +Risks. + +- Without indication, longer forms can feel endless. +- Users may abandon because they cannot predict the form's length. + +The discipline. No indicator is rarely the right answer for forms with more than 3 steps. + +--- + +## Pattern E: Hybrid + +Combining patterns. A step counter plus a progress bar; or a step list plus a percentage. + +Strengths. + +- Multiple signals reinforce each other. +- Different users benefit from different indicators. + +Weaknesses. + +- Visual complexity grows. +- Risk of redundant or conflicting signals. + +When to use. Long forms (5+ steps) where rich indication helps the user understand the form's shape. + +--- + +## Indicator failures + +Patterns that break trust. + +Failure 1: Indicator that shifts mid-form. + +The form starts as "Step 4 of 5"; conditional logic adds steps; the form is now "Step 4 of 7." The user feels misled. + +The cure. Either avoid conditional steps that change the count, or communicate the variability upfront ("This form has 5-7 steps depending on your answers"). + +Failure 2: Indicator that hides remaining work. + +"Almost done" when 5 fields remain on the next step. The user trusted the indicator and now feels betrayed. + +The cure. Calibrate the indicator to reflect remaining fields, not just remaining steps. + +Failure 3: Indicator that fills fast and slows down. + +Progress bar fills to 70 percent in the first 2 steps; the remaining 30 percent takes the next 5 steps. The user expects the form to end soon and is frustrated when it does not. + +The cure. Weight the progress bar by actual work, not just step count. If step 5 represents most of the remaining work, the bar should reflect that. + +Failure 4: Indicator with no current-step context. + +The progress bar shows 50 percent but the user does not know what the current step is about. Reduces orientation. + +The cure. Include both progress (where you are) and current-step name (what you are doing). + +Failure 5: Indicator that is decorative without being honest. + +Progress that looks fast but the next step is the longest one. The indicator misleads about pacing. + +The cure. Honest pacing. The indicator should reflect actual time-to-complete, not just step count. + +--- + +## Indicator placement + +Where the indicator lives on the page. + +Top placement. Above the form fields. Common; user sees it on every step. + +Sidebar placement. Alongside the form. Good for step-list patterns; takes more space. + +Bottom placement. Below the form fields. Less common; user has to scroll to see it on long steps. + +Sticky placement. Indicator stays visible as the user scrolls within a step. Useful for long steps. + +The choice depends on form length per step and visual hierarchy. Top placement is the safe default. + +--- + +## Indicator and mobile + +The indicator must work on mobile. + +Mobile-specific considerations. + +- Step counter: easy to mobile (small footprint). +- Progress bar: easy (full-width fits). +- Step list: harder; may need to collapse to step counter on mobile. +- Hybrid: simplify on mobile; do not stack multiple indicators. + +The mobile discipline. Ensure the indicator is visible without scrolling. Mobile users should see "Step 2 of 5" or the progress bar without searching for it. + +--- + +## Indicator messaging + +Optional language alongside the indicator. + +Encouragement messages. "Halfway there!" or "Almost done!" Can boost motivation; can also feel patronizing. + +Time estimates. "About 2 minutes left." Useful when honest; misleading when wrong. + +Step-name labels. "Step 2: Your Company." Useful when steps have meaningful names. + +The discipline. Encouragement and estimates should be honest. Patronizing or wrong messaging breaks trust faster than no messaging. + +--- + +## Indicator updating + +When the indicator updates. + +On step transition. The indicator updates as the user moves to the next step. Common pattern. + +On field completion. The indicator updates as fields within a step are filled. More granular; less common. + +Smooth animation. Subtle animation on transition reinforces progress. + +No animation. Instant update is fine; flashy animation can be distracting. + +--- + +## When indicators add no value + +Some forms work without indicators. + +Very short forms. 2-step forms often do not need indication. The user knows it is short. + +High-frequency forms. Forms the user fills repeatedly may not need indication after the first time. + +Single-action forms. A subscription form with email and submit does not need a progress indicator. + +The discipline. Default to including an indicator for multi-step forms. Skip only when the form is genuinely simple enough that the indicator adds noise. + +--- + +## Indicator audit + +Periodically audit the indicator. + +The audit. + +- Read the indicator on each step. Does it reflect honest progress? +- Test the form with conditional logic. Does the indicator handle the variability? +- Check mobile rendering. Does the indicator work on touch devices? +- Check accuracy. Does "almost done" actually mean almost done? + +The drift. Indicators decay as forms evolve. Steps get added; conditional logic gets added; the indicator falls out of sync. + +The cure. Quarterly audit alongside form audit. Update the indicator when the form structure changes. + +--- + +## Common indicator failures + +No indicator on a long form. User does not know how much remains; abandons. + +Indicator shifts mid-form. Conditional logic surprised the user. + +Dishonest pacing. Bar fills fast, work remains slow. + +Indicator without current-step context. Progress without orientation. + +Indicator overflowing on mobile. Step list designed for desktop; cramped on mobile. + +Patronizing language. "Almost done" repeatedly when the user is at step 2 of 6. + +Wrong time estimates. "About 1 minute left" when 5 minutes remain. + +--- + +## Methodology-level choices that stay in the public skill + +The honesty principle. Patterns A through E with strengths, weaknesses, and when-to-use guidance. Indicator failures (5 patterns). Indicator placement, mobile considerations, messaging, updating. When indicators add no value. Indicator audit. Common failures. + +## Implementation choices that stay internal + +Specific indicator designs for specific forms. Specific tooling for indicator implementation. Specific brand-voice messaging alongside indicators. The team's mobile testing benchmarks. These vary by team. diff --git a/skills/multi-step-form-design/references/save-and-resume-mechanics.md b/skills/multi-step-form-design/references/save-and-resume-mechanics.md new file mode 100644 index 0000000..dc1b7a3 --- /dev/null +++ b/skills/multi-step-form-design/references/save-and-resume-mechanics.md @@ -0,0 +1,267 @@ +# Save-and-resume mechanics + +When to offer save-and-resume. Email-link, account-based, anonymous-session patterns. Trust communication. + +Save-and-resume reduces drop-off for forms that take more than 5 minutes to complete or that require information the user may not have at hand. Done well, it earns the user's trust and recovers what would otherwise be lost completions. + +--- + +## When save-and-resume helps + +Three conditions that, when present, make save-and-resume valuable. + +Form length warrants it. Forms taking more than 5 minutes to complete benefit. Below 5 minutes, the user can usually push through; above, the cost of starting over is high. + +Information may not be at hand. Forms requiring documents, technical configurations, or specific data the user may need to gather. Save-and-resume lets the user collect the information and return. + +Multi-session use is expected. Forms that are part of multi-touchpoint workflows (loan applications, enrollment forms, complex onboarding). Save-and-resume is required, not optional. + +When all three are present, save-and-resume is a strong investment. When none are present, the mechanic adds complexity without lift. + +--- + +## When save-and-resume does not help + +Quick lead-capture forms. Under 60 seconds to complete. The save mechanic adds complexity; the audience does not need it. + +Single-session forms. Forms designed to be completed in one sitting. Save-and-resume can encourage abandonment ("I will come back later") that becomes permanent. + +Forms that require trust. Sensitive information may not be safe to persist; the user may not save because they distrust persistence. Adding save-and-resume without addressing trust degrades the form. + +Forms with strict expiration. Application deadlines or session timeouts may make save-and-resume confusing or counterproductive. + +--- + +## Pattern A: Email-link recovery + +The most common save-and-resume pattern. + +How it works. + +- The user clicks "Save and resume later." +- A form appears asking for an email address. +- The user enters email; a recovery link is sent. +- The user opens the email later, clicks the link, returns to the form with progress preserved. + +Strengths. + +- Familiar pattern; users understand it. +- Works across devices (user can save on desktop, resume on mobile). +- Simple to implement. + +Weaknesses. + +- Requires the user to give an email address before completing the form (which may itself be friction). +- Depends on email deliverability. +- Recovery link can expire or get lost. + +When to use. Default for most save-and-resume needs. The familiar UX reduces friction. + +--- + +## Pattern B: Account-based persistence + +Forms that require account creation persist by default. + +How it works. + +- The user creates an account at the start. +- Form progress saves automatically as the user completes fields. +- The user logs back in to resume. + +Strengths. + +- Persistence is automatic; user does not have to choose to save. +- Works across devices. +- Account integration may extend to other features beyond the form. + +Weaknesses. + +- Account creation is significant friction at the start. +- Adds engineering complexity. +- May not be appropriate for one-shot forms. + +When to use. Forms that are part of an account-based product or service where account creation is justified by ongoing use. + +--- + +## Pattern C: Anonymous-session save + +Browser-based save without identification. + +How it works. + +- Form progress saves to browser local storage as the user completes fields. +- The user returns to the same browser, picks up where they left off. + +Strengths. + +- Lowest friction; no email or account required. +- Automatic; user does not have to choose to save. + +Weaknesses. + +- Works only on the same browser/device. +- Lost if the user clears cookies or switches devices. +- Limited persistence (typically days, not weeks). + +When to use. Forms where the audience likely returns from the same device within a short window. Often used as a fallback or supplement to other patterns. + +--- + +## Pattern D: Hybrid + +Combining patterns. Anonymous-session save by default; email-link recovery as a backup. + +How it works. + +- Form auto-saves to browser as user completes. +- A "save and resume from any device" option offers email-link recovery. + +Strengths. + +- Lowest-friction default; user benefits even without explicit action. +- Cross-device option for users who want it. + +Weaknesses. + +- More complex to design and explain. +- Multiple save mechanisms can confuse the user. + +When to use. Forms with significant length where many users return same-device but some need cross-device. + +--- + +## Trust communication + +Users hesitate to save partial sensitive information. The form must communicate clearly. + +What to communicate. + +- What is saved. "Your answers so far will be saved." +- What is not saved. "We do not save passwords or payment information until submission." +- How long it persists. "Your progress will be available for 7 days." +- Who can access it. "Only you can access your saved progress through the link we email you." +- How to delete. "You can clear your saved progress by completing or abandoning the form." + +Trust copy patterns. + +- "We never share your saved information." +- "Your progress is encrypted at rest." +- "You control whether to come back." + +Trust copy that fails. + +- Generic privacy boilerplate. +- Long legal text the user will not read. +- Vague reassurances without specifics. + +The discipline. Trust copy should be specific, scannable, and honest. Generic privacy text does not earn trust. + +--- + +## When in the form to offer save-and-resume + +Timing matters. + +Pattern: Always available. A "Save and resume" link visible on every step. The user can save at any moment. + +Pattern: Triggered by inactivity. After 60-90 seconds of inactivity, prompt the user to save. Risk: the prompt feels intrusive. + +Pattern: Offered at logical breakpoints. Save prompts at the end of each step or at known long-pause points. Less intrusive than continuous availability. + +Pattern: Offered before high-friction steps. "The next step requires document uploads. You can save now and come back when you have your documents." + +The choice depends on form length and the audience's likely pause points. Always-available is the safe default for long forms. + +--- + +## Resume experience + +The user clicks the recovery link or logs in. What happens next. + +The principle. The resume experience should be uninterrupted. The user lands on the step they were on; their previous answers are preserved; they can continue without re-doing work. + +The resume page. + +- Welcome back message confirming the resume. +- Preserved progress visible (the user sees what they had done). +- Clear path to continue (button to proceed to current step). + +Resume failures. + +- The user lands at the start; previous answers lost. Trust collapses. +- The user lands at the right step but answers are wrong. Worse than starting over. +- The recovery link expires; the user is told their progress is gone. The save mechanism failed. + +The discipline. Test the resume experience as carefully as the form itself. A broken resume is worse than no save. + +--- + +## Save-and-resume measurement + +Track how many users save and resume. + +The metrics. + +- Save rate. What percentage of users who reach the save option choose to save? +- Resume rate. What percentage of users who saved actually resume? +- Resume-to-completion rate. What percentage of users who resumed complete the form? + +Diagnostic uses. + +- Low save rate: the option is not visible or trust is missing. +- Low resume rate: the recovery email failed or the user lost interest. +- Low resume-to-completion: the resume experience is broken or the form is too long. + +The decision. If save-and-resume is offered but rarely used, audit whether the offering is justified or whether the mechanic adds complexity without payoff. + +--- + +## Save-and-resume for sensitive information + +Some forms collect sensitive information. Save-and-resume requires extra care. + +The principle. Sensitive information may not be safe to persist. Audit what is saved and what is not. + +Common patterns. + +- Save non-sensitive only. Names, emails, situational information saved; passwords, SSNs, payment details not saved. +- Encrypt at rest. Saved data encrypted in storage; only retrievable through recovery flow. +- Limit persistence window. Sensitive forms may save only for 24-48 hours rather than 7+ days. + +Compliance considerations. + +- Some jurisdictions or regulations restrict what can be persisted. +- The form's save behavior should be reviewed against applicable compliance. +- Trust copy should disclose persistence honestly. + +The discipline. Sensitive forms warrant more conservative save behavior. The convenience of save-and-resume is not worth privacy or compliance risk. + +--- + +## Common save-and-resume failures + +Save offered without trust communication. Users do not save because they distrust persistence. + +Recovery link expires too quickly. User receives the link, intends to come back, finds the link expired by the time they do. + +Resume to wrong step. User clicks recovery link, lands at the start, has to redo everything. + +Saved answers corrupted. User resumes, answers are wrong or partial. + +Save mechanic decays. Storage backend changes; saved data becomes inaccessible. + +Multiple save mechanisms confuse. Anonymous-session and email-link both offered; user does not know which to use. + +Save offered on a form that does not need it. Quick form gets save mechanic; complexity without payoff. + +--- + +## Methodology-level choices that stay in the public skill + +When save-and-resume helps and does not. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Trust communication discipline. Timing of save offering. Resume experience. Measurement. Save-and-resume for sensitive information. Common failures. + +## Implementation choices that stay internal + +Specific save-and-resume implementations for specific forms. Specific persistence backends and expiration policies. Specific trust copy in brand voice. The team's compliance review processes. These vary by team. diff --git a/skills/multi-step-form-design/references/step-architecture-patterns.md b/skills/multi-step-form-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..de0e936 --- /dev/null +++ b/skills/multi-step-form-design/references/step-architecture-patterns.md @@ -0,0 +1,279 @@ +# Step architecture patterns + +What belongs on each step. Identity, context, need, detail, confirmation. Sequencing principles. + +The architecture is the structure that makes steps coherent. Bad architecture produces progress-theater (decorative steps); good architecture produces genuinely-staged forms (each step is a coherent unit of work). + +--- + +## The coherence principle + +Each step should represent a coherent unit of work from the user's perspective. + +The test. Can the user describe what they just did at the end of the step in one sentence? + +- Coherent: "I told you the basics about my company." +- Atomized: "I typed my company name in a field." + +Coherent answers signal genuinely-staged. Atomized answers signal progress-theater. + +The discipline. Each step should bundle related fields into a single cognitive unit. The user processes the step as a whole, not as 5 isolated fields. + +--- + +## Common step patterns + +Patterns that recur across acquisition, onboarding, and intake forms. + +Identity step. Who the user is. + +- Fields: name, email, role. +- Friction level: low. +- Position: opens the form. +- The user provides minimal commitment; the form earns the right to ask for more. + +Context step. What the user's situation is. + +- Fields: company size, industry, current setup, current tools. +- Friction level: medium. +- Position: after Identity, before Need. +- The user shares context that lets the form (or the receiving team) understand them. + +Need step. What the user is trying to accomplish. + +- Fields: goal, challenge, timeline, urgency. +- Friction level: medium-to-high. +- Position: middle of the form. +- The user articulates intent. This step often includes the highest-value fields for the receiving team. + +Detail step. Specifics needed to act on the user's request. + +- Fields: budget, specific requirements, constraints, integrations. +- Friction level: high. +- Position: late in the form. +- The user shares specifics. By this point, commitment is built; the user is more willing to share. + +Confirmation step. Review and submit. + +- Fields: review summary, submission action, optional final fields (preferences, follow-up). +- Friction level: low. +- Position: last. +- The user reviews what they provided and submits. + +--- + +## Sequencing principles + +The order of steps matters as much as the steps themselves. + +Principle 1: Low-friction first. The opening step should be easy to complete. The user invests their first 30-60 seconds in something simple; commitment compounds. + +Principle 2: Commitment compounds. Each step builds on the previous. The user who completed step 2 is more invested than they were before step 1; later steps can ask for more. + +Principle 3: High-friction at the end. The most demanding fields (budget, specific requirements, sensitive info) belong later. By that point, the user has invested enough to push through. + +Principle 4: Confirmation explicit. A final review-and-submit step lets the user verify their inputs. Reduces submission anxiety. + +Anti-pattern: high-friction first. Asking for budget in step 1 depresses completion. The user has not yet committed; the high-friction question feels premature. + +Anti-pattern: commitment-resetting. A late step that requires the user to make decisions they thought they had already made. The user feels their earlier work was wasted. + +--- + +## Step coherence test + +For each step, ask: can this step be described in one sentence as a unit of work? + +Coherent step examples. + +- "Step 1: tell us who you are." (Identity) +- "Step 2: tell us about your company." (Context) +- "Step 3: tell us what you are trying to accomplish." (Need) +- "Step 4: tell us the specifics so we can help." (Detail) +- "Step 5: review and submit." (Confirmation) + +Each step has a coherent description. The user can predict what is coming and feel they accomplished something at the end of each step. + +Incoherent step examples (progress-theater). + +- "Step 1: name and email." +- "Step 2: phone and company." +- "Step 3: role and industry." + +Each step is two fields. The fields are unrelated. The grouping is arbitrary. The user wonders why this is multi-step. + +--- + +## Field count per step + +How many fields per step is too many or too few. + +Too few. 1-2 fields per step often signals over-staging. The user wonders why this needed its own step. + +Right range. 3-7 fields per step. Enough to represent a coherent unit of work; few enough to complete in 30-60 seconds. + +Too many. 10+ fields per step starts to recreate the kitchen-sink-single-page problem within a step. Audit for non-essential fields. + +The variance. Some steps may have more fields than others; that is fine if each step's fields cohere. The Detail step often has more fields than the Identity step because it captures more specific information. + +--- + +## Step length variability + +Steps do not have to be the same length. + +The pattern. Identity step: 3 fields. Context step: 5 fields. Need step: 4 fields. Detail step: 7 fields. Confirmation step: 1 action. + +The variability is fine because each step represents a coherent unit. The user does not expect equal length; they expect coherence. + +The progress indicator implication. A step counter ("Step 2 of 5") may not reflect time-to-complete accurately when steps vary. A progress bar based on percentage of fields complete reflects the variability better. + +--- + +## Conditional step inclusion + +Some forms include or exclude steps based on earlier answers. + +The pattern. "If user has a current CRM, include the 'CRM details' step. If not, skip it." + +Strengths. + +- Removes irrelevant fields entirely. +- Makes the form feel adaptive. + +Risks. + +- Progress indicators must accommodate the variability honestly. +- The user may notice the variability and feel confused. + +The discipline. Use conditional steps when the variability genuinely benefits the user; communicate the dynamic nature in the progress indicator if it shifts. + +--- + +## Step transitions + +How the user moves from one step to the next. + +The forward transition. A clear "Next" or "Continue" button. Validation runs before the transition. + +The backward transition. A "Back" or "Previous" button. The user can return to earlier steps without losing later inputs. + +The skip transition. Some forms allow skipping optional steps. Use sparingly; skipping creates inconsistent paths. + +Transition friction. Each transition should feel snappy. Loading delays at transitions break the flow. + +Transition cues. Brief visual confirmation that the step changed (slide animation, fade transition). Helps the user understand the navigation. + +--- + +## Step naming + +Each step should have a clear name visible to the user. + +Strong step names. + +- "Tell us about you." +- "About your company." +- "What you are looking for." +- "The details." +- "Review and submit." + +Weak step names. + +- "Step 1," "Step 2," "Step 3." (Numbers without names; user does not know what each represents.) +- "Personal Info," "Company Info," "Other Info." (Generic; does not signal what the step is about.) +- "Contact," "Business," "Submission." (Truncated; does not warm the user.) + +The voice match. Step names should match the brand voice. Casual brands use casual names; serious brands use serious names. + +--- + +## Step architecture for specific use cases + +How the architecture varies by form purpose. + +Lead-capture form (5-8 fields). + +- Identity (name, email) +- Context (company, role) +- Need (use case, urgency) + +3 steps; the form moves quickly. + +Demo-request form (10-15 fields). + +- Identity (name, work email, role) +- Company (name, size, industry) +- Current state (current solution, key pain points) +- Buying intent (timeline, budget range) +- Confirmation + +5 steps; meaningful staging. + +Application form (20+ fields with documents). + +- Identity +- Eligibility (qualifying questions) +- Personal details +- Financial details +- Document upload +- Review +- Submit + +7+ steps; long form benefits significantly from staging. + +Onboarding wizard (configuration-driven). + +- Welcome +- Account setup +- Use-case selection +- Preferences +- Connect-your-tools +- Confirmation + +6 steps; each step represents a coherent setup unit. + +--- + +## Step architecture audit + +Periodically audit the step architecture. + +The audit. + +- Read each step's name. Does it represent a coherent unit? +- Read each step's fields. Do they cohere? +- Check field count per step. Within the 3-7 range? +- Check conversion per step. Are some steps disproportionately drop-off-heavy? + +The drift. Steps decay as the form evolves. New fields get added to the wrong step; steps become incoherent; field counts drift. + +The cure. Quarterly audit. Re-group fields into the right steps; remove non-essential fields; restructure if the original architecture no longer fits. + +--- + +## Common architecture failures + +Arbitrary chunking. Steps that group fields by visual length rather than coherence. + +Atomized steps. Each step has 1-2 fields; the user wonders why it is multi-step. + +Field-count overload. Some steps have 15+ fields; recreates the kitchen-sink problem within a step. + +High-friction-first. Budget or sensitive question in step 1; user is not committed enough to push through. + +Commitment-resetting steps. Late steps that require the user to make decisions they thought were already made. + +Generic step names. "Step 1, Step 2" without descriptive names; user cannot predict the form. + +No confirmation step. Form ends at the data-collection step; user is not given the chance to review. + +--- + +## Methodology-level choices that stay in the public skill + +The coherence principle. Common step patterns. Sequencing principles. The step-coherence test. Field count per step. Step length variability. Conditional step inclusion. Step transitions. Step naming. Step architecture for specific use cases. Step-architecture audit. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific forms. Specific step naming in brand voice. Specific tooling for step transitions and validation. The team's audit calendars. These vary by team and form. diff --git a/skills/multi-step-form-design/references/validation-strategy-patterns.md b/skills/multi-step-form-design/references/validation-strategy-patterns.md new file mode 100644 index 0000000..2c53366 --- /dev/null +++ b/skills/multi-step-form-design/references/validation-strategy-patterns.md @@ -0,0 +1,288 @@ +# Validation strategy patterns + +Per-step vs end-only vs hybrid. Validation message discipline. + +The validation strategy determines when errors are caught and how they are communicated. Done well, validation catches errors helpfully and protects the form from invalid submissions. Done poorly, validation rejects valid inputs or surfaces errors at the worst time. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. Errors caught too early feel intrusive; errors caught too late waste the user's investment. + +The win. A user enters an invalid email; inline validation catches it immediately; the user fixes it and continues. + +The fail (too early). A user is mid-typing an email; "must contain @" appears before they have finished typing. + +The fail (too late). A user completes 5 steps; submission fails because of a step-1 error they did not see flagged. + +The strategy choice depends on the form's length, the audience, and the validation complexity. + +--- + +## Pattern A: Per-step validation + +Each step's fields are validated before allowing progression to the next step. + +How it works. + +- The user completes the current step. +- Validation runs on all fields in the step. +- If errors exist, they are shown; the Next button does not advance. +- The user fixes errors and proceeds. + +Strengths. + +- Errors caught at the point of input. +- User does not invest in completing later steps only to discover an early error. +- Form feels responsive. + +Weaknesses. + +- Can feel intrusive if validation is too strict on every step transition. +- May block the user from progressing when they want to revise the field later. + +When to use. Default for most multi-step forms. Each step's data is validated as a coherent unit. + +--- + +## Pattern B: End-only validation + +All validation runs at submission. + +How it works. + +- The user completes all steps. +- Validation runs only when the user clicks Submit. +- All errors surface at once. + +Strengths. + +- User completes uninterrupted. +- Validation logic is simpler (one validation pass). + +Weaknesses. + +- User invests in entire form only to discover an early error. +- Errors at the end can lose the user. +- Errors that span multiple steps are confusing to surface. + +When to use. Rarely. Sometimes appropriate for very short forms where per-step validation overhead is not worth it. + +--- + +## Pattern C: Hybrid + +Required-field validation per step; full validation at end. + +How it works. + +- Per-step: critical errors (missing required fields, malformed email format) catch immediately. +- End: nuanced validation (cross-field consistency, business rules) catches at submission. + +Strengths. + +- Combines the responsiveness of per-step with the simplicity of end-only. +- The user gets immediate feedback on critical issues. +- Complex validation logic does not interrupt the flow. + +Weaknesses. + +- More complex to design (two validation tiers). +- Risk of inconsistent user experience if the tiers are not well-coordinated. + +When to use. When validation has both critical-immediate components (required fields, format checks) and nuanced-end components (cross-field rules, business logic). The default pattern for most multi-step forms with significant validation needs. + +--- + +## Pattern D: Real-time validation + +Validation runs as the user types or interacts with each field. + +How it works. + +- As the user types, validation runs on the field. +- Errors appear inline as soon as they are detectable. +- Some implementations validate on field blur (when the user leaves the field) rather than every keystroke. + +Strengths. + +- Earliest possible error detection. +- User sees the result of their input immediately. + +Weaknesses. + +- Can feel intrusive if validation appears before the user finishes typing. +- Real-time validation on complex rules can lag. +- Easy to surface errors prematurely. + +When to use. When the validation is simple enough to run instantly (format checks) and when the audience benefits from immediate feedback. Best practice: validate on blur rather than every keystroke. + +--- + +## Validation message discipline + +The error messages themselves matter. + +Helpful messages. + +- "Phone number must include area code" (specific guidance). +- "Try a value between 1 and 1000" (specific range). +- "Email must include @ and a domain" (specific format). +- "This field is required" (when blank). + +Unhelpful messages. + +- "Invalid input" (generic). +- "Error" (no information). +- "Out of range" (no range specified). +- "You must enter..." (scolding tone). + +Tone discipline. Messages should be helpful, not scolding. "Try a value between 1 and 1000" beats "You must enter a value between 1 and 1000." + +Specificity. "Phone number must be 10 digits" beats "Invalid phone number." Specific guidance lets the user fix the issue immediately. + +--- + +## Inline placement + +Where errors appear matters. + +Inline placement. Errors appear next to the field that triggered them. The user sees the error in context. + +Banner placement. Errors appear in a banner at the top of the step. Easy to miss; less helpful. + +Mixed placement. Some errors inline, some in a banner. Confusing. + +The discipline. Inline placement is the default. Banners can supplement (summarizing all errors on the step) but should not replace inline. + +--- + +## Validation timing + +When validation triggers. + +On blur. Validation runs when the user leaves the field. Default for most field types. + +On change. Validation runs as the user types. Useful for some real-time feedback (password strength, character count) but intrusive for most validation. + +On submit. Validation runs when the user clicks the Next or Submit button. Always required as the final check. + +The combination matters. Most fields work well with on-blur for individual validation plus on-submit for final check. + +--- + +## Cross-field validation + +Validation that depends on multiple fields. + +Examples. + +- "End date must be after start date." +- "Sum of allocations must equal 100 percent." +- "If selected 'enterprise,' company size must be above 200." + +The challenge. Cross-field validation does not fit per-field timing. The validation can only run when both fields have values. + +Approaches. + +- End-only validation for cross-field rules. The cross-field check runs at submission. +- End-of-step validation. The cross-field check runs when the step containing both fields is completed. +- Reactive cross-field validation. Each time either field changes, the cross-field check runs. + +The choice depends on the form's complexity and the user's likely workflow. + +--- + +## Validation strictness + +How aggressively to reject inputs. + +Too strict. Rejects valid inputs because the validation is over-specified. "Email format invalid" for an email with a plus-sign alias. + +Too loose. Accepts invalid inputs that fail at submission. The user finds out late. + +The right strictness. Match validation rules to actual business requirements. Do not reject inputs the system can handle; do not accept inputs the system will choke on. + +Common over-strictness mistakes. + +- Email validation that rejects plus-sign aliases. +- Phone validation that rejects international formats. +- Name validation that rejects non-Latin characters. +- Address validation that rejects valid international addresses. + +The discipline. Validation should reflect what the system actually requires, not what is stereotypical. + +--- + +## Validation and accessibility + +Validation must work for users with assistive technology. + +Screen reader announcements. Errors should be announced when they appear. ARIA live regions for inline errors; focus management for error summaries. + +Keyboard navigation. Users should be able to navigate to error messages with keyboard alone. + +Visual cues alongside text. Color-coding for errors should not be the only signal; text labels and icons help users who cannot perceive color. + +Detail in `accessibility-audit` for deeper accessibility coverage. + +--- + +## Validation and mobile + +Mobile validation has specific considerations. + +Touch-friendly error states. Error indicators should be visible without pinch-zoom. + +Inline placement on mobile. Errors appearing below or above the field; do not push critical content off-screen. + +Mobile keyboards. Use input types (email, tel, number) so mobile keyboards adapt; this also helps validation. + +Real-time validation latency. On mobile, real-time validation can lag and feel sluggish; default to on-blur for performance. + +--- + +## Validation testing + +Test validation across edge cases. + +Test cases to include. + +- Empty required fields. +- Format-invalid inputs (malformed emails, invalid phone numbers). +- Format-valid but business-invalid inputs (email without account, valid date in the past for a future-only field). +- Boundary inputs (minimum, maximum, just-outside). +- Special characters and international inputs. + +The discipline. Validation should pass valid inputs and reject invalid ones consistently. Test with realistic edge cases the audience will encounter. + +--- + +## Common validation failures + +Generic error messages. "Invalid input" without guidance. + +Over-strict validation. Rejecting valid inputs that fall outside narrow expectations. + +Late validation. Errors caught only at submission for issues that should have surfaced earlier. + +Banner-only error placement. User cannot see which field has the issue. + +Validation that rejects internationally. US-only formatting rules applied to international audiences. + +Inconsistent validation rules. Same field validated differently in different contexts. + +Validation without accessibility. Errors invisible to screen readers; color-only cues. + +Validation that interrupts typing. Real-time validation surfacing errors before the user finishes typing. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D with strengths, weaknesses, and when-to-use guidance. Validation message discipline (helpful vs unhelpful). Inline placement. Validation timing. Cross-field validation. Validation strictness. Validation and accessibility (cross-reference). Validation and mobile. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific forms. Specific tooling for validation implementation. Specific brand-voice error messages. The team's accessibility review processes. These vary by team. diff --git a/skills/okr-design/SKILL.md b/skills/okr-design/SKILL.md new file mode 100644 index 0000000..83f3ea1 --- /dev/null +++ b/skills/okr-design/SKILL.md @@ -0,0 +1,310 @@ +--- +name: okr-design +description: "OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the difference between sandbagged OKRs (always 100%) and aspirational OKRs (always 30%) and stretch OKRs (genuine ambition with quarterly accountability). Triggers on OKR design, OKR setting, key result design, OKR scoring, mid-quarter recalibration, OKR cascading, outcomes vs outputs, quarterly planning, goal setting. Also triggers when a team's OKRs are always hit and producing no learning, when OKRs are demoralizing because they were set as fantasy, or when the team uses OKR vocabulary but the practice has decayed." +category: product +catalog_summary: "OKR design discipline. Outcome statements, key results, scoring, mid-quarter recalibration. Distinguishes sandbagged OKRs (always hit, useless) from aspirational fantasy (impossible, demoralizing) from stretch OKRs (genuine ambition with quarterly accountability)" +display_order: 12 +--- + +# OKR Design + +A senior product leader's playbook for OKR design as actually shipped, not as conference-talk theory. Outcome statements that drive decisions, key results that measure the right thing, scoring discipline, mid-quarter recalibration, and the practical disciplines that distinguish OKRs from quarterly to-do lists or impossible-fantasy goal-setting. + +OKRs are accountability infrastructure. When designed well, they produce a quarterly rhythm of ambitious goal-setting, mid-quarter learning, end-of-quarter scoring, and adjustment for the next quarter. When designed badly, they become a tax on the team that produces no signal: sandbagged OKRs that always hit 100% (no ambition, no learning), aspirational fantasy OKRs that nobody can hit (demoralizing, ignored after week 2), or vague OKRs that the team scores generously regardless of outcome. + +This skill is OKR design as practical methodology. The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, key results that actually measure the outcome, scoring honestly even when uncomfortable, recalibrating mid-quarter when warranted, and using the OKR review cadence to drive learning rather than performance theater. + +The voice is the senior product leader who has run OKRs in healthy organizations and watched the practice decay in others. Concrete, opinionated about what actually works, willing to call out the failure modes that conference talks gloss over. + +When to use this skill: designing OKRs for the next quarter, auditing why current OKRs are not driving decisions, recalibrating an OKR practice that has decayed, or onboarding a team to OKRs that has never used them. + +--- + +## What this skill is for + +This skill spans OKR design and the operational rhythm around them. The PM-skill distinction: + +- `okr-design` (this skill) is outcomes (results to be achieved). +- `roadmap-planning` is outputs (features and initiatives sequenced). +- `feature-launch-playbook` is post-ship execution. +- `product-analytics-setup` is measurement infrastructure (the metrics that key results depend on). +- `experiment-design` is the discipline for testing whether specific initiatives produce outcomes. +- `discovery-research-synthesis` informs which outcomes to pursue. + +The audience: senior PMs, product directors, engineering leaders, executives setting org-wide OKRs, in-house teams operating in OKR-driven cultures. + +What is not in scope: the broader strategic planning that decides which outcomes matter (other strategy frameworks); the execution of specific initiatives toward OKRs (covered by roadmap-planning, pm-spec-writing, feature-launch-playbook); the analytics infrastructure (covered by product-analytics-setup, analytics-strategy). + +--- + +## Sandbagged vs aspirational-fantasy vs stretch + +The keystone framing. + +Sandbagged. OKRs designed to hit 100%. The key results target outcomes the team is already on track to deliver. End of quarter: 100% scores across the board. The team celebrates; nobody learns anything. Output: an OKR practice that produces no signal. The team has the same OKRs every quarter dressed in different vocabulary because nothing pushes them past where they would have gone anyway. + +Aspirational-fantasy. OKRs that nobody can hit. 1000% growth in 90 days. Demoralizing, performative, ignored after week 2. Teams that ship aspirational-fantasy OKRs typically discover by week 6 that no realistic effort path produces the targets; they disengage; the OKRs become decoration on the planning doc that nobody references. + +Stretch. Genuine ambition with quarterly accountability. Designed to hit 60-70% on average. Hits and misses both teach something. The 60% case ("we hit 60% of our key results") is informative about what the team can deliver in a quarter; the 100% case is rare and usually signals sandbagging in retrospect; the 30% case signals either fantasy or the team encountered something unexpected (which is also informative). + +The litmus test. Look at the team's last four quarters of OKRs. If the average score is 95%+, the OKRs are sandbagged. If the average is below 30%, they are fantasy. If the average is 50-75%, the design is in the stretch zone. Adjust upcoming OKRs to bring the practice into stretch territory. + +--- + +## Objective design + +Objectives are outcome statements. They name what the team is trying to achieve in the quarter. + +Strong objective characteristics. + +- Outcome-focused, not output-focused. "Improve activation for new sign-ups" is an outcome; "Ship the new onboarding flow" is an output. +- Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. +- Inspiring without being fantasy. The team should feel pulled toward the objective, not crushed by it. +- Few in number. Most teams should have 2-4 objectives per quarter; more than 5 dilutes focus. + +Worked examples. + +- "Improve activation for new sign-ups so that more reach the value-realization moment within the first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +Weak objective characteristics. + +- Output-disguised-as-outcome. "Ship the activation redesign" is an output; the objective should be the result the redesign is meant to produce. +- Too vague. "Improve user experience" is too broad to focus quarterly work. +- Too tactical. "Refactor the auth service" is a tactical decision, not a quarterly objective. +- Too many. 8 objectives produces no focus; the team works on too many things and excels at none. + +Detail in [`references/objective-design-patterns.md`](references/objective-design-patterns.md). + +--- + +## Key result design + +Key results measure progress toward the objective. They are the quantitative or testable indicators that show whether the objective is being achieved. + +Strong key result characteristics. + +- Measurable. There is a specific number or testable threshold. +- Outcome-aligned. Achieving the key result actually moves the objective forward. +- Within team influence. The team can affect the key result through their work. +- Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +Worked example. Objective: "Improve activation for new sign-ups." + +Strong key results: + +- "Increase the percentage of new sign-ups reaching the value-realization moment within their first week from 32% to 45%." +- "Reduce the median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on the onboarding flow (up from 64%)." + +Each key result is measurable, ties to activation, the team can influence it through onboarding redesign work, and is time-bounded to the quarter. + +Weak key results. + +- Vague: "Improve activation significantly." +- Output: "Ship 5 onboarding redesign initiatives." (counts work done, not outcomes produced.) +- Outside influence: "Increase total signups by 50%." (signups are mostly upstream of activation work.) +- Vanity: "Reach 1M users." (impressive number; not directly tied to activation outcome.) + +The 3-5 key results rule. Most objectives benefit from 3-5 key results. One key result is fragile (single measurement may not capture the outcome); 6+ key results dilute focus. + +Detail in [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md). + +--- + +## Cascading OKRs across the org + +When and how to cascade OKRs from leadership to teams. + +The trade-off. + +- Cascaded OKRs ensure team work aligns with company priorities. The product team's objective derives from the company's objective; the engineering team's objective derives from the product team's. +- Strict cascading produces top-down OKRs that miss bottom-up insight. The team closer to the work sometimes knows what to prioritize better than the layer above. +- Too-loose cascading produces team OKRs that do not connect to company priorities; teams optimize locally without contributing to org goals. + +The middle path. + +- Company-level OKRs set quarterly. Team-level OKRs set with reference to company OKRs but with team-level autonomy on how to contribute. +- Each team's OKRs explicitly identify which company OKRs they ladder up to. +- Some team OKRs may be team-specific (technical debt, infrastructure, experimentation infrastructure) without direct company-OKR ladders. Surface these explicitly so the team's full work is visible. + +When to cascade strictly. Early-stage companies aligning around a small number of company priorities. Times of strategic shift where the org needs to move in a coordinated direction. + +When to cascade loosely. Mature organizations with established team mandates. Cross-functional teams where strict cascading would over-constrain. + +The honest disclosure. Cascading is harder than conference talks suggest. Most orgs over-cascade in the first few cycles and learn to relax it; some never learn and produce OKRs that are increasingly performative as they propagate down. + +Detail in [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md). + +--- + +## Scoring discipline + +End-of-quarter scoring is where OKR practice succeeds or decays. + +The 0.0-1.0 scale. Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +The 60-70% target. Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. Higher average suggests sandbagging; lower suggests fantasy or unexpected disruption. + +Scoring honesty. + +- Score the actual outcome, not the effort. The team that worked hard but did not move the metric scores low; the team that got lucky and moved the metric without much effort scores high. The score reflects outcome. +- Do not round up. A key result at 0.55 is 0.55, not 0.6. Honest scoring produces honest signal. +- Acknowledge what changed mid-quarter. Some misses reflect priority shifts; surface those without using them as excuses. + +What 100% means. 100% scores warrant scrutiny. Either the OKR was sandbagged (under-set), the team had a great quarter (informative), or the team is rounding up. Investigate which. + +What 30% means. 30% scores warrant scrutiny. Either the OKR was fantasy (over-set), the team encountered unexpected disruption (informative), or the work was deprioritized mid-quarter (also informative). Investigate which. + +The compensation question. OKRs work best when not directly tied to compensation. When OKRs determine bonuses, sandbagging incentives become severe; teams set OKRs they know they can hit. Most healthy OKR cultures separate goal-setting from compensation. + +Detail in [`references/scoring-discipline.md`](references/scoring-discipline.md). + +--- + +## Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. + +The default. OKRs hold for the quarter. Teams adapt their tactics to the OKR; OKRs do not change to match what the team is doing. + +When to recalibrate. + +- Strategic shift. The company's strategy changed materially mid-quarter; OKRs that no longer reflect the strategy are no longer the right targets. +- Major external disruption. A market change, regulatory event, or significant outage warrants resetting the quarter's targets. +- Information that invalidates the OKR. The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +When NOT to recalibrate. + +- The team is not on track. OKRs that are missing should remain as set; the miss is the signal. +- The OKR is uncomfortable. Teams uncomfortable with stretch OKRs should not lower them mid-quarter to feel better. +- Easier OKRs would feel achievable. The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +The recalibration discipline. Recalibration should be rare (1-2 quarters out of 8). Frequent recalibration signals OKR design failure: either too aggressive or not strategically aligned. The recalibration itself should be transparent: surface what changed, why, and what the new targets are. + +Detail in [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md). + +--- + +## The OKR review cadence + +OKRs benefit from a structured review rhythm. + +Weekly check-ins. + +- Team reviews progress on each key result. 15-30 minutes. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Not for adjusting OKRs; for adjusting tactics to keep moving toward them. + +Mid-quarter review. + +- Roughly week 6 of the quarter. 60-90 minutes. +- Honest assessment of trajectory: which key results are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +End-of-quarter review. + +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +Quarterly retrospective. + +- Distinct from the scoring review. The retrospective examines the OKR practice itself: were the OKRs the right ones, did the cadence work, what should change. +- Often combined with the next-quarter OKR setting session. + +Detail in [`references/review-cadence-templates.md`](references/review-cadence-templates.md). + +--- + +## OKRs vs roadmap items vs metrics + +Three concepts often conflated. Each serves a different purpose. + +OKRs. Outcome targets for the quarter. "Improve activation for new sign-ups" is an OKR; "Increase first-week activation rate from 32% to 45%" is a key result. + +Roadmap items. Initiatives the team is building or doing. "Onboarding redesign" is a roadmap item. Roadmap items contribute to OKRs but are not the OKRs themselves. + +Metrics. Ongoing measurements the team tracks. "First-week activation rate" is a metric. Metrics inform key results (which are quarterly targets on metrics) and are tracked continuously regardless of whether the team has an OKR aimed at them. + +The relationship. + +- OKR: "Improve activation for new sign-ups." +- Key result: "First-week activation rate from 32% to 45%." +- Metric: "First-week activation rate" (tracked continuously). +- Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +Common conflations. + +- Treating roadmap items as OKRs. "Ship the onboarding redesign" as an OKR; the OKR should be the outcome the redesign is meant to produce. +- Treating every metric as needing an OKR. Some metrics matter for the team to track without setting quarterly targets on them. +- Treating OKRs as roadmap commitments. OKRs name outcomes; the team is committed to pursuing them but may shift tactics; treating OKRs as roadmap commitments locks in tactics that may need to change. + +Detail in [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-okr-failures.md`](references/common-okr-failures.md). + +- "Our OKRs are always 100% and produce no signal." Sandbagged. Set with stretch ambition; expect 60-70% scores. +- "Our OKRs are always 30% and demoralizing." Fantasy. Recalibrate to genuine stretch; investigate whether the targets are achievable in any realistic effort path. +- "Our key results measure work, not outcomes." Output-disguised-as-outcome. Rewrite key results to measure the result, not the work. +- "We have 12 OKRs and the team is working on 47 things." Too many OKRs; cap at 2-4 objectives, 3-5 KRs each. +- "Our OKRs are vague." Lack measurable targets; rewrite key results with specific numbers and thresholds. +- "Our cascading produces team OKRs that do not match team work." Strict cascading mismatched to team mandate; loosen cascading or change team mandate. +- "We never recalibrate even when the strategy shifts." Recalibration too tightly avoided; surface strategic-shift criteria and use them. +- "We recalibrate every quarter." Recalibration too easy; OKR design is failing; investigate. +- "Our weekly check-ins became status reports." Tactical-discussion missing; reform the check-in format. +- "Our scoring rounds up." Scoring discipline missing; commit to honest scoring. +- "OKRs and bonuses are tied; people sandbag." Predictable; decouple OKRs from compensation. + +--- + +## The framework: 12 considerations for OKR design + +When designing or auditing OKRs, walk these 12 considerations. + +1. Stretch, not sandbagged or fantasy. 60-70% average score target. +2. Objectives are outcomes, not outputs. What we are trying to achieve. +3. Few objectives, well-focused. 2-4 per team per quarter. +4. Key results are measurable. Specific numbers or testable thresholds. +5. Key results are outcome-aligned. Achieving them moves the objective forward. +6. Key results are within team influence. Not entirely dependent on external factors. +7. 3-5 key results per objective. Single key results are fragile; many dilute focus. +8. Cascading explicit but not over-constrained. Team OKRs ladder up but with autonomy on how. +9. Scoring honest, not rounded. 0.0-1.0 reflects actual outcomes. +10. Recalibration rare. OKRs hold absent strategic shift or major disruption. +11. Review cadence weekly + mid-quarter + end-of-quarter. Tactical, then strategic, then scoring. +12. OKRs separate from roadmap items and metrics. Each serves a different purpose. + +The output of the framework is OKRs that produce quarterly accountability infrastructure: ambitious goal-setting, mid-quarter learning, end-of-quarter scoring honest enough to inform the next quarter. + +--- + +## Reference files + +- [`references/objective-design-patterns.md`](references/objective-design-patterns.md) - Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. +- [`references/key-result-design-patterns.md`](references/key-result-design-patterns.md) - Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. +- [`references/cascading-okrs-decisions.md`](references/cascading-okrs-decisions.md) - When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. +- [`references/scoring-discipline.md`](references/scoring-discipline.md) - The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. +- [`references/mid-quarter-recalibration.md`](references/mid-quarter-recalibration.md) - When to recalibrate vs adapt tactics. Strategic shift vs uncomfortable OKRs. The recalibration discipline. +- [`references/review-cadence-templates.md`](references/review-cadence-templates.md) - Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. +- [`references/okrs-vs-roadmap-vs-metrics.md`](references/okrs-vs-roadmap-vs-metrics.md) - The three concepts and their relationships. Common conflations. The complete picture across all three. +- [`references/okr-anti-patterns.md`](references/okr-anti-patterns.md) - 8+ anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling. +- [`references/common-okr-failures.md`](references/common-okr-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: OKRs are accountability infrastructure + +OKRs at their best produce quarterly accountability that informs the org's strategic learning. The team commits to outcomes; works toward them; scores honestly; learns from the gap between target and outcome; designs the next quarter's OKRs better. + +OKRs at their worst produce ritual that consumes time without producing signal. Sandbagged OKRs that always hit. Fantasy OKRs that nobody can. Vague OKRs that score generously regardless of outcome. The vocabulary persists; the practice has decayed. + +The teams that benefit from OKRs are the ones that hold the discipline: outcomes over outputs, measurable key results, stretch ambition, scoring honesty, recalibration only when warranted, and the review cadence that drives learning rather than performance theater. + +When in doubt about whether an OKR practice is working, ask: do the OKRs drive decisions about what to prioritize, do the scores produce learning that informs the next quarter, are key results actually measuring outcomes the team can influence, is the average score in the 60-70% range that stretch OKRs target? If yes to all of those, the practice is real. If no to any, the gap is where the OKR work is failing to produce the accountability infrastructure it is meant to provide. diff --git a/skills/okr-design/references/cascading-okrs-decisions.md b/skills/okr-design/references/cascading-okrs-decisions.md new file mode 100644 index 0000000..9ce7eb6 --- /dev/null +++ b/skills/okr-design/references/cascading-okrs-decisions.md @@ -0,0 +1,187 @@ +# Cascading OKRs decisions + +When to cascade strictly vs loosely. The middle path. Cascading anti-patterns. The honest disclosure about cascading difficulty. + +Cascading is one of the most contested OKR practices. Conference talks describe clean ladders from company to team to individual; in practice, strict cascading produces over-constrained team OKRs, while loose cascading produces team work disconnected from company priorities. The middle path is harder than the talks suggest. + +--- + +## The trade-off + +Cascading exists on a spectrum. + +Strict cascading. + +- Company sets OKRs. +- Each function (product, engineering, sales) cascades to function-level OKRs. +- Each team cascades to team OKRs. +- Each individual cascades to personal OKRs. +- All ladders trace cleanly upward. + +Loose cascading. + +- Company sets OKRs. +- Teams set their own OKRs informed by company priorities but with autonomy on scope and contribution. +- Teams may set OKRs not directly tied to company OKRs (technical debt, team-specific work). +- Individual OKRs often skipped. + +The trade-off. + +- Strict produces alignment but over-constrains. Teams set OKRs they think leadership wants rather than OKRs they can credibly commit to. +- Loose produces autonomy but risks misalignment. Team work optimizes locally without contributing to org goals. + +--- + +## When to cascade strictly + +Early-stage companies aligning around small priorities. When the company has 2-3 critical priorities and everyone needs to focus on them, strict cascading enforces the focus. + +Times of strategic shift. When the company is changing direction (new market, new segment, new product line), strict cascading helps the org turn together. + +Crisis or focus periods. When the company faces a specific challenge requiring all hands, strict cascading ensures everyone is rowing the same direction. + +Common to these cases: strategic clarity is high, alignment is more valuable than autonomy, and the org has fewer concurrent priorities to balance. + +--- + +## When to cascade loosely + +Mature organizations with established mandates. Teams have clear scope; their OKRs naturally fit company priorities through team mandate; strict cascading adds overhead without value. + +Cross-functional teams where strict cascading would over-constrain. Teams that span functions cannot cleanly ladder to a single function-level OKR; loose cascading lets them pursue cross-functional outcomes. + +High-trust environments. Teams trusted to set their own OKRs and credibly commit to them; the org accepts the autonomy in exchange for the engagement and creativity it produces. + +Common to these cases: team mandates are clear, autonomy is more valuable than tight alignment, and the org tolerates some local optimization in exchange for team engagement. + +--- + +## The middle path + +Most healthy OKR cultures sit between strict and loose. + +The pattern. + +- Company sets 3-5 OKRs at the start of the quarter. +- Teams set OKRs that explicitly identify which company OKRs they ladder up to (when applicable). +- Teams have autonomy on how to contribute (which key results, which initiatives, what scope). +- Some team OKRs are team-specific (technical debt, infrastructure, experimentation foundations) without direct company ladders. Surface these explicitly. +- Individual OKRs are usually skipped; commitment is at the team level. + +The "explicit ladder when applicable" rule. Each team OKR either: + +- Explicitly identifies the company OKR it ladders to. +- Explicitly identifies that it is team-specific without a company ladder. + +Both are honest; the failure mode is implicit ambiguity where the team is not sure whether their OKR connects to anything. + +--- + +## Worked example: middle path + +Company OKRs for Q3: + +1. Improve net new ARR through enterprise segment growth. +2. Improve activation for self-serve sign-ups. +3. Reduce infrastructure costs through architecture optimization. + +Product team OKRs: + +- "Improve activation for new sign-ups" (ladders to company OKR 2). +- "Establish enterprise-readiness foundations" (ladders to company OKR 1). +- "Reduce technical debt in the activation funnel" (team-specific; does not ladder directly). + +Engineering team OKRs: + +- "Ship onboarding redesign by week 6" (ladders to company OKR 2 via product team OKR). +- "Migrate to new search architecture" (ladders to company OKR 3). +- "Strengthen test coverage in critical paths" (team-specific). + +Sales team OKRs: + +- "Close 8 enterprise deals in Q3" (ladders to company OKR 1). +- "Improve discovery-call to demo conversion from 24% to 35%" (ladders to company OKR 1). +- "Build the design partner program" (team-specific). + +The pattern. Most team OKRs ladder up; some are team-specific. Each ladder is explicit. Teams have autonomy on how they contribute (which KRs, which initiatives). + +--- + +## Cascading anti-patterns + +Strict cascading enforced top-down without team input. Team OKRs become wishlist receivers from leadership; commitment is shallow because the team did not author what they are committing to. + +Loose cascading without explicit ladders. Team OKRs are set without any visible connection to company priorities. Some team work happens to align; some does not. Leadership cannot tell what is contributing to company OKRs. + +Cascade theater. OKR documents include ladders that look connected but do not actually drive anything. The team's work shows up the same regardless of which company OKR they "ladder to." + +Over-cascading. Every team OKR is required to ladder to a company OKR. Teams contort their work to fit. Team-specific work (technical debt, infrastructure) gets dressed up as ladder work or gets de-prioritized despite being important. + +Personal OKRs as default. Individual OKRs cascaded down. Most OKR cultures find this produces overhead without proportional value; commitment at team level is usually sufficient. + +--- + +## Cascading and team mandate + +Teams whose OKRs do not naturally ladder to company priorities often have a team-mandate problem. + +The signal. A team consistently sets OKRs that are team-specific. None of their work ladders to company priorities. + +The interpretation. + +- Possibly the team's mandate does not match the company's current priorities. Either the mandate should change (broader scope, different focus) or the team's work is not strategically critical (consider deprioritizing or restructuring). +- Possibly the team's work is foundational and supports many company priorities indirectly (platform teams, infrastructure teams). Their OKRs may legitimately be team-specific. + +The audit. Annually, review whether team mandates match company strategy. Teams whose mandates have drifted from strategy benefit from explicit redirection. + +--- + +## Cascading frequency + +The cascading work happens at OKR-setting time (start of quarter) and is generally locked for the quarter. + +Quarterly cascading. Most common. Company OKRs set; teams cascade; quarter executes. + +Mid-quarter cascade revision. Rare. Strategic shift mid-quarter may warrant rewriting team OKRs. See `mid-quarter-recalibration.md`. + +The honest frequency. Most orgs over-cascade in the first few quarters of OKR adoption (treating cascading as a thing to perfect) and learn to relax it. Some orgs never relax and produce increasingly performative cascading. Recognize the pattern; loosen when it stops adding value. + +--- + +## Cascading and individual goals + +Individual goals are usually a separate practice from OKRs. + +Common patterns. + +- Team OKRs commit at team level; individual contributors work toward team OKRs without separate personal OKRs. +- Individual goals (career development, skill-building, role expectations) live in performance management, separate from OKRs. +- Some orgs do cascade to individual OKRs; most find this produces overhead without value and stop after a few cycles. + +The discipline. Be intentional about whether to cascade to individuals. The default should be "no, commit at team level"; individual cascading should be justified rather than assumed. + +--- + +## Common cascading failures + +Top-down enforced cascading. Teams receive OKRs from leadership; commitment is shallow. + +Implicit cascading. Team OKRs do not explicitly identify their ladders; alignment is ambiguous. + +Over-cascading. Every team OKR forced to ladder to company; team-specific work dressed up artificially. + +Cascade theater. Ladders documented but not driving anything. + +Personal-OKR overhead. Individual cascading without proportional value. + +Mandate-strategy drift. Teams with mandates disconnected from current strategy producing OKRs that ladder to nothing. + +--- + +## Methodology-level choices that stay in the public skill + +The cascading trade-off. When to cascade strictly and loosely. The middle path with explicit ladders. Worked example. Cascading anti-patterns. Team mandate considerations. Cascading frequency. Individual goals separation. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that visualize ladders. Specific cascade-review meeting formats. Specific role-based templates. The team's own conventions for surfacing team-specific OKRs. These vary by org and tooling. diff --git a/skills/okr-design/references/common-okr-failures.md b/skills/okr-design/references/common-okr-failures.md new file mode 100644 index 0000000..675ddb3 --- /dev/null +++ b/skills/okr-design/references/common-okr-failures.md @@ -0,0 +1,205 @@ +# Common OKR failures + +Eleven-plus failure patterns with diagnoses and cures. Cross-references the OKR anti-patterns reference; this file covers operational failures that arise during the OKR cycle. + +The cross-cutting pattern: most OKR failures share a single root, which is treating OKRs as ceremony rather than as accountability infrastructure. + +--- + +## Failure 1: Our OKRs are always 100% and produce no signal + +Symptom. End-of-quarter scoring shows the team hitting 95%+ on every KR. The OKR practice feels positive but does not produce learning. + +Diagnosis. Sandbagging. Targets set at or below the team's natural trajectory. The OKR practice has decayed into "what we know we can hit." + +Cure. Set targets above the historical trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The target should be meaningfully above that. + +Prevention. Track the average score over multiple quarters. Drift toward 0.85+ is a sandbagging signal; intervene before the practice fully decays. + +--- + +## Failure 2: Our OKRs are always 30% and demoralizing + +Symptom. End-of-quarter scoring shows the team consistently missing OKRs. Team disengages from OKRs by mid-quarter. + +Diagnosis. Aspirational fantasy. Targets have no realistic effort path. The OKR practice has decayed into "inspirational numbers nobody believes." + +Cure. Recalibrate to genuine stretch. Validate against the effort-path test: can the team identify specific initiatives that would produce the target? + +Prevention. During OKR setting, require effort-path reasoning. If the team cannot articulate what work would produce the target, the target is fantasy. + +--- + +## Failure 3: Our key results measure work, not outcomes + +Symptom. KRs read as roadmap items. "Ship X by Y." "Run Z interviews." + +Diagnosis. Output-disguised-as-outcome. The team is committing to work, not to results. + +Cure. Rewrite each output KR to measure the outcome the output is meant to produce. The output itself lives in the roadmap. + +Prevention. During KR drafting, apply the outcome test: is this measuring a result, or counting work? + +--- + +## Failure 4: We have 12 OKRs and the team is working on 47 things + +Symptom. Quarterly OKRs span many objectives and KRs; the team's work is scattered across many priorities. + +Diagnosis. OKR proliferation. Too many objectives produces no focus. + +Cure. Cap at 2-4 objectives, 3-5 KRs each. Surface deferred work explicitly so the team can see what they are choosing not to commit to. + +Prevention. Cap OKRs at the start of the cycle. Adding "just one more" OKR is a recurring pressure that should be resisted. + +--- + +## Failure 5: Our OKRs are vague + +Symptom. Objectives like "improve user experience" or KRs like "make activation better." Cannot be scored honestly. + +Diagnosis. Lack of measurable specificity. + +Cure. Rewrite KRs with specific numbers, baselines, and targets. "Increase first-week activation rate from 32% to 45%" instead of "improve activation." + +Prevention. During KR review, apply the specificity test: could two reasonable people disagree on whether this KR was hit at end of quarter? If yes, it is too vague. + +--- + +## Failure 6: Our cascading produces team OKRs that do not match team work + +Symptom. Team OKRs cascade to company OKRs but the team's actual capacity and mandate produce different work. + +Diagnosis. Strict cascading mismatched to team mandate. + +Cure. Loosen cascading; allow team-specific OKRs that do not directly ladder. Or change team mandate if it does not match strategy. + +Prevention. Use the middle path on cascading. Surface team-specific OKRs explicitly. + +--- + +## Failure 7: We never recalibrate even when the strategy shifts + +Symptom. The org's strategy changed mid-quarter. Team OKRs no longer reflect strategy. The team holds them anyway. + +Diagnosis. Recalibration too tightly avoided. + +Cure. Surface the strategic shift; recalibrate the affected OKRs explicitly. Document the trigger. + +Prevention. Make strategic-shift criteria for recalibration explicit. The team should know when recalibration is appropriate. + +--- + +## Failure 8: We recalibrate every quarter + +Symptom. OKRs get revised mid-quarter routinely. The team uses recalibration to soften uncomfortable OKRs. + +Diagnosis. Recalibration too easy. OKR design is failing or stretch ambition is being avoided. + +Cure. Hold OKRs absent the recalibration triggers (strategic shift, major disruption, invalidating information). Investigate why frequent recalibration is happening. + +Prevention. Track recalibration frequency. Drift toward "every quarter recalibrates" is a signal to intervene. + +--- + +## Failure 9: Our weekly check-ins became status reports + +Symptom. Weekly OKR check-ins lost their tactical decision focus; they became "here's what I did this week" updates. + +Diagnosis. Check-in format drift. The session is no longer producing tactical adjustments. + +Cure. Reform the format. Per KR: trajectory, blockers, planned work for the upcoming week. End with explicit commitments. + +Prevention. The team lead facilitates the check-in's tactical scope. Status reports happen elsewhere. + +--- + +## Failure 10: Our scoring rounds up + +Symptom. End-of-quarter scoring shows 0.85 average. Closer inspection shows scores were rounded up across most KRs. + +Diagnosis. Generous scoring. Honesty has decayed. + +Cure. Commit to honest scoring. A 0.55 KR scores 0.55, not 0.6. Document context; the context surfaces what produced the actual outcome regardless of the number. + +Prevention. Surface the rounding pattern explicitly. The team should know that rounding up is the failure mode. + +--- + +## Failure 11: OKRs and bonuses are tied; people sandbag + +Symptom. OKR scores directly determine bonuses. Targets set conservatively; scoring round up; stretch ambition gone. + +Diagnosis. Compensation coupling. + +Cure. Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs. + +Prevention. Establish from the start that OKRs are accountability infrastructure, not performance management. Compensation tied loosely or not at all. + +--- + +## Failure 12: OKRs were set but never referenced + +Symptom. OKRs documented at start of quarter. Mid-quarter prioritization debates ignore them. End-of-quarter scoring is generous because nobody tracked rigorously. + +Diagnosis. OKR theater. The practice produces overhead without value. + +Cure. Reform the cadence. Weekly check-ins reference OKRs explicitly. Mid-quarter review uses OKRs as the assessment lens. Scoring informs next quarter. + +Prevention. Tie OKRs to specific decisions. If OKRs are not load-bearing for prioritization, surface the disconnect and reform or abandon. + +--- + +## Failure 13: KRs depend on factors outside team influence + +Symptom. KRs miss because of external factors the team could not affect (market conditions, sales execution, infrastructure issues). The team cannot credibly own the KR. + +Diagnosis. KR design failure. Targets set on outcomes the team cannot meaningfully drive. + +Cure. Rewrite to focus on what the team can move. The team's contribution to a larger outcome may be the right KR, not the larger outcome itself. + +Prevention. During KR design, validate that the team can identify how their work moves the KR. + +--- + +## Failure 14: Cross-team OKRs produce coordination failures + +Symptom. Multiple teams have KRs aimed at the same outcome. Teams pursue independently; the outcome lags because nobody owns the integration. + +Diagnosis. Cross-team coordination missing. Either single ownership should have been assigned, or split KRs need stronger coordination. + +Cure. Establish single ownership for outcome OKRs that span multiple teams. Or use split-KR pattern where each team's KR is their specific contribution. + +Prevention. During OKR design, surface cross-team dependencies. Decide single-owner or split-KR explicitly. + +--- + +## Failure 15: OKRs are roadmap commitments to stakeholders + +Symptom. Stakeholders treat OKRs as commitments to specific work. Mid-quarter tactical adjustments feel like broken promises. + +Diagnosis. OKR-as-roadmap conflation. Stakeholders interpret outcomes as outputs. + +Cure. Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Both are visible; the OKR is the accountability; the roadmap is the team's current best guess at what work will produce the outcome. + +Prevention. When communicating OKRs to stakeholders, explicitly surface the distinction. Use different vocabulary. + +--- + +## The cross-cutting pattern + +Most OKR failures share a single root: treating OKRs as ceremony rather than as accountability infrastructure. + +Ceremony focuses on the appearance of OKR practice: documents produced, meetings held, scores generated. Accountability focuses on the work the practice is meant to support: stretch goal-setting, mid-quarter learning, end-of-quarter scoring honesty, next-quarter improvement. + +The fix for almost any OKR failure starts with the same question: what decision is this OKR practice supposed to inform? When the answer is clear, the practice becomes load-bearing. When the answer is "we should follow the OKR process," the practice becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-accountability pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/okr-design/references/key-result-design-patterns.md b/skills/okr-design/references/key-result-design-patterns.md new file mode 100644 index 0000000..8ad33d3 --- /dev/null +++ b/skills/okr-design/references/key-result-design-patterns.md @@ -0,0 +1,242 @@ +# Key result design patterns + +Measurable, outcome-aligned, within-influence, time-bounded characteristics. Strong vs weak key results. The 3-5 KR rule. Worked examples. + +Key results are where the OKR practice succeeds or fails operationally. Objectives can be inspiring without measurable; key results have to be measurable. Most OKR failure at the operational level shows up in the key result design. + +--- + +## The four characteristics of strong key results + +Measurable. A specific number, percentage, or testable threshold. + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." + +Outcome-aligned. Achieving the key result actually moves the objective forward. + +- For the activation objective, the key results above are aligned: they all measure aspects of activation. +- A key result like "ship the onboarding redesign" is not outcome-aligned; it measures the work, not the activation outcome. + +Within team influence. The team can affect the key result through their work. + +- "First-week activation rate" is influenced by onboarding design, welcome email content, in-product guidance. The team can affect it. +- "Total signups" depends primarily on marketing acquisition; the activation team's onboarding work affects it weakly. Not a strong key result for the activation team. + +Time-bounded. The measurement window is the quarter (or appropriate sub-window). + +- "Increase first-week activation rate from 32% to 45% by end of Q3." +- "Reach 80% completion rate by week 10 of the quarter." + +The four characteristics together produce key results the team can commit to credibly and measure honestly. + +--- + +## Strong key result examples by objective + +Objective: "Improve activation for new sign-ups so more reach value-realization in week one." + +Strong KRs: + +- "Increase first-week activation rate from 32% to 45%." +- "Reduce median time-to-first-value from 4.2 days to under 2 days." +- "Reach 80% completion rate on onboarding flow (up from 64%)." +- "Reduce signup-to-first-key-action time from 8 minutes to under 4 minutes." + +Each measures an aspect of activation. The team can influence each through their work. Each has a baseline and target. + +Objective: "Make support experience deflect predictable issues." + +Strong KRs: + +- "Reduce ticket volume on the top 3 deflection-eligible categories by 40%." +- "Increase self-service resolution rate from 22% to 38%." +- "Maintain CSAT at or above 4.4/5 (no degradation while deflecting)." + +The third KR matters: deflecting tickets without protecting CSAT could damage the experience; the KR keeps both in scope. + +Objective: "Establish enterprise-readiness foundations." + +Strong KRs: + +- "Pass SOC 2 Type II audit with zero high-severity findings." +- "Complete admin role and permissions overhaul; reach 95% of enterprise-prospect compliance checklist items." +- "Onboard 3 design partners from the enterprise segment to the alpha enterprise build." + +Each measures a foundation outcome the enterprise readiness depends on. + +--- + +## Weak key result examples + +Vague. + +- "Improve activation significantly." +- "Reduce ticket volume." + +No specific number; cannot be scored honestly. + +Output disguised as outcome. + +- "Ship 5 onboarding redesign initiatives." +- "Run 12 customer interviews." + +Counts work done, not outcomes produced. The team can hit these by doing work without producing the outcome the objective targets. + +Outside influence. + +- "Increase total signups by 50%." +- "Maintain market share." + +Total signups are upstream of activation work; market share depends on competitive dynamics largely outside the team's control. + +Vanity. + +- "Reach 1M users." +- "Reach 10K NPS responses." + +Impressive numbers; not directly tied to the outcome the objective targets. + +Single-data-point dependent. + +- "Have one customer reference our product publicly." + +Fragile; a single data point may not represent progress. + +--- + +## The 3-5 key results rule + +Most objectives benefit from 3-5 key results. + +Why not 1. Single key results are fragile. If the metric does not move for reasons outside the team's tactical choices, the team has no way to show progress on the objective. Multiple KRs triangulate. + +Why not 6+. Too many KRs dilute focus. The team scatters attention across many metrics; trade-offs across KRs become impossible because all are claimed as priority. + +The 3-5 sweet spot. + +- Enough KRs to triangulate the outcome. +- Few enough that the team can pay attention to each. +- Allows for KRs that protect against unintended degradation (e.g., deflect tickets while protecting CSAT). + +The KR composition. + +- 1-2 KRs measure the primary outcome. +- 1-2 KRs measure secondary aspects of the outcome. +- 0-1 KRs protect against unintended consequences. + +--- + +## Baseline and target setting + +Each KR needs a baseline and target. + +Baseline. The current value of the metric. Pulled from analytics or recent measurement; should be honest, not aspirational. + +Target. The value the team commits to reaching by end of quarter. + +Setting the target. + +- Stretch: target a value that requires real work to reach. Should hit 60-70% of the time on average across KRs. +- Not sandbagged: target should not be where the team would land without focused effort. +- Not fantasy: target should be reachable through realistic effort paths the team can identify. + +The historical-trajectory test. Look at the metric over the past 4 quarters. Where would the metric be at end of next quarter on its current trajectory? The target should be meaningfully above that trajectory; otherwise, the OKR is sandbagged. + +The effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, the target is fantasy. + +--- + +## Leading vs lagging key results + +Key results can measure leading indicators (early signals) or lagging indicators (final outcomes). + +Lagging. The outcome the team ultimately wants. "First-week activation rate" measures the activation outcome. + +Leading. Early signals that the lagging outcome will move. "Onboarding flow completion rate" leads first-week activation rate. + +The blend. + +- Some KRs measure leading indicators (so the team has signal early in the quarter). +- Some KRs measure lagging indicators (so the team is accountable to the actual outcome). +- A blend produces both early signal and end-of-quarter accountability. + +The lagging-only failure. OKRs that only measure lagging indicators produce no mid-quarter signal. The team cannot tell if they are on track until end of quarter. + +The leading-only failure. OKRs that only measure leading indicators produce no end-of-quarter accountability. Leading indicators can move without lagging indicators following. + +--- + +## When binary KRs are appropriate + +Most KRs are quantitative (a number to reach). Some are binary (a milestone to achieve). + +When binary works. + +- Audit-pass milestones: "Pass SOC 2 Type II with zero high-severity findings." +- Foundational milestones: "Complete admin role overhaul." +- Launch milestones: "Ship the activation redesign to all users." + +When binary fails. + +- Used for KRs that should be quantitative. "Successfully implement activation improvements" is binary disguised as outcome; should be quantitative. +- Used to dodge measurement. Binary KRs that are not actually milestones become "we did it" claims without underlying outcome verification. + +The discipline. Use binary KRs sparingly and only when the milestone genuinely is the outcome. Most outcome KRs benefit from quantitative measurement. + +--- + +## KRs across teams + +When multiple teams contribute to the same outcome, KRs need careful design. + +The split-KR pattern. Each team has KRs that contribute to the cross-team outcome. + +- Product team KR: "Increase first-week activation rate from 32% to 45%." +- Engineering team KR: "Ship onboarding redesign by week 6 of the quarter." +- Customer success team KR: "Reduce activation-related support ticket volume by 30%." + +Each team is accountable for its contribution; the cross-team outcome benefits from all. + +The single-owner pattern. One team owns the outcome KR; other teams support without explicit KRs on the same metric. + +- Product team owns the activation KR. +- Engineering and CS support without separate KRs. +- Cross-team coordination happens outside the OKR structure. + +The discipline. Pick a pattern. Hybrid approaches (sometimes shared KRs, sometimes single-owner) produce confusion about accountability. + +--- + +## Common KR design failures + +Output KRs. Counts of work shipped instead of outcomes produced. Cure: rewrite. + +Vague KRs. Lack measurable targets. Cure: specify number and threshold. + +Out-of-influence KRs. Depend on factors the team cannot affect. Cure: rewrite to what the team can move. + +Vanity KRs. Impressive numbers not tied to outcome. Cure: tie to the actual outcome. + +Too few KRs. Single KR fragility. Cure: 3-5 KRs per objective. + +Too many KRs. 6+ KRs dilute focus. Cure: cap at 5. + +No baseline. "Reach X" without naming current value. Cure: include baseline. + +Sandbagged targets. Targets at or below current trajectory. Cure: stretch beyond what the team would do without focus. + +Fantasy targets. Targets with no realistic effort path. Cure: validate against effort-path test. + +Lagging-only. No leading indicators. Cure: add leading-indicator KRs. + +--- + +## Methodology-level choices that stay in the public skill + +The four characteristics. Strong and weak KR examples. The 3-5 KR rule. Baseline and target setting. Leading vs lagging KRs. Binary KRs when appropriate. Cross-team KR patterns. Common failures. + +## Implementation choices that stay internal + +Specific KR templates. Specific metrics tooling and dashboards. Specific historical-trajectory analysis. Specific KR scorecards. The team's own conventions for KR wording. These vary by team and tooling. diff --git a/skills/okr-design/references/mid-quarter-recalibration.md b/skills/okr-design/references/mid-quarter-recalibration.md new file mode 100644 index 0000000..91b96a0 --- /dev/null +++ b/skills/okr-design/references/mid-quarter-recalibration.md @@ -0,0 +1,214 @@ +# Mid-quarter recalibration + +When OKRs should change vs when teams should adapt. Strategic shift vs uncomfortable OKRs. The recalibration discipline. + +The default is that OKRs hold for the quarter. Teams adapt their tactics; OKRs do not change to match what the team is doing. Recalibration is the exception, not the rule. Recalibrating frequently signals OKR design failure. + +--- + +## The default: OKRs hold + +OKRs are quarterly commitments. The team commits at the start of the quarter and works toward them through the quarter regardless of whether progress feels comfortable. + +Why holding matters. + +- OKRs are accountability infrastructure. Changing them mid-quarter weakens the accountability. +- Stretch OKRs are uncomfortable by design. The discomfort is the work. +- Teams that recalibrate when uncomfortable train themselves to recalibrate as a coping mechanism. + +Adapting tactics, not OKRs. + +- The OKR target stays. +- The team's tactics for reaching the target adapt as they learn what works. +- New initiatives may be launched; existing ones may be scrapped; the OKR remains the destination. + +--- + +## When to recalibrate + +Three conditions warrant recalibration. + +### Strategic shift + +The company's strategy changed materially mid-quarter. OKRs that no longer reflect the strategy are no longer the right targets. + +Examples. + +- The company pivoted to a new market segment; OKRs aimed at the prior segment are no longer strategic. +- A major acquisition or restructure changed the team's mandate. +- Leadership announced a new strategic priority that supersedes the quarter's OKRs. + +The handling. Recalibrate explicitly. Document what changed strategically and how OKRs are revised. Communicate to stakeholders so the recalibration is visible and intentional. + +### Major external disruption + +A market change, regulatory event, or significant outage warrants resetting the quarter's targets. + +Examples. + +- A major outage consumed weeks of engineering capacity that was meant for OKR work. +- Regulatory changes required compliance work that displaced planned OKRs. +- Market conditions shifted dramatically (recession, supply chain disruption) and the OKRs no longer reflect realistic ambition for the new conditions. + +The handling. Recalibrate explicitly. Surface the disruption and its impact. Set new targets that reflect the post-disruption reality. + +### Information that invalidates the OKR + +The team learned mid-quarter that the metric they were targeting does not actually represent the outcome. + +Examples. + +- Analytics work revealed that the activation metric the team was targeting is not the right measure of activation success; a better metric exists. +- Customer research revealed that the user segment the team was prioritizing is smaller or less important than expected. +- Technical investigation revealed that the planned approach to an OKR has fatal limitations that were not visible at planning time. + +The handling. Recalibrate explicitly. Document what was learned. Set new OKRs reflecting the new understanding. + +--- + +## When NOT to recalibrate + +Three patterns that look like recalibration triggers but are not. + +### The team is not on track + +OKRs that the team is missing should remain as set; the miss is the signal. + +Why. Stretch OKRs are designed to miss sometimes. Hitting 60-70% on average means roughly 30-40% of KRs miss the target. The miss is informative; lowering the target to match the trajectory eliminates the signal. + +The cure. Hold the OKR. Score honestly at end of quarter. Use the miss to inform next quarter's design. + +### The OKR is uncomfortable + +Teams uncomfortable with stretch OKRs sometimes want to recalibrate to feel better. + +Why. Stretch is uncomfortable by design. Teams that learn to lower OKRs when uncomfortable lose the stretch discipline; OKRs drift toward sandbagging quarter over quarter. + +The cure. Hold the OKR. Acknowledge the discomfort. Surface what the team would need to push toward the target. Use the discomfort productively rather than recalibrating it away. + +### Easier OKRs would feel achievable + +The temptation to swap hard OKRs for easy ones is sandbagging in slow motion. + +Why. Hard OKRs are the point. Swapping for easier ones removes the accountability infrastructure stretch OKRs provide. + +The cure. Hold the OKR. If the original was genuinely fantasy (no realistic effort path), recalibrate per the strategic-shift pattern. If the original was genuine stretch but uncomfortable, hold. + +--- + +## The recalibration discipline + +When recalibration is warranted, the discipline matters. + +Surface the trigger. What changed? Strategic shift, external disruption, or invalidating information. Be specific. + +Document the original target and the revised target. The history of recalibration is part of the OKR record. Future audits should be able to see what changed. + +Explain the new target. Why this revised target? What effort path produces it? How does it reflect the new reality? + +Communicate to stakeholders. Recalibration is visible. Stakeholders who expected the original target should know it changed and why. + +Score against the revised target at end of quarter. The recalibrated OKR is the OKR for scoring purposes. Do not score against the original. + +--- + +## Frequency of recalibration + +Recalibration should be rare. + +Healthy frequency. 1-2 quarters out of 8 may include recalibration on at least one OKR. Most quarters should have no recalibrations. + +Concerning frequency. Every quarter includes recalibration on some OKR. This signals either: + +- The OKR design is consistently aggressive (fantasy targets). +- The strategy is shifting too frequently (lack of strategic stability). +- The team has learned to recalibrate as a coping mechanism for stretch. + +The diagnosis. Frequent recalibration is a signal to investigate, not a feature to lean into. The investigation surfaces whether the issue is OKR design, strategic stability, or team behavior. + +--- + +## Recalibration as honest tool vs avoidance + +The line between honest recalibration and avoidance. + +Honest recalibration. + +- The trigger is specific and external (strategic shift, disruption, invalidating information). +- The revised target reflects the new reality, not the team's preference. +- The recalibration is documented and visible. + +Avoidance dressed as recalibration. + +- The trigger is vague ("things changed"). +- The revised target is conveniently achievable. +- The recalibration happens when the OKR is uncomfortable, not when external conditions warrant it. + +The honest test. If a stakeholder asked the team to defend the recalibration, could the team point to a specific external trigger? If the answer is "we just thought the target was too ambitious," the recalibration is avoidance. + +--- + +## Recalibration in the OKR system + +How recalibration affects the broader OKR practice. + +Trust effects. + +- Recalibration that is rare and well-justified preserves trust in OKRs. +- Recalibration that is frequent or poorly justified erodes trust; stakeholders learn to expect targets to slide. + +Org-wide signaling. + +- One team's recalibration affects how other teams perceive recalibration norms. +- Leaders that recalibrate strict targets signal to teams that recalibration is acceptable; teams take the cue. +- Leaders that hold targets even when uncomfortable signal that stretch is real; teams take that cue. + +The practice's calibration over time. Recalibration norms accumulate. Healthy practices stay disciplined; decaying practices loosen. The annual review of OKR practice should look at recalibration frequency as one signal of practice health. + +--- + +## Communicating recalibration + +When recalibration happens, communication matters. + +To the team. + +- Surface the trigger before the recalibration is decided. The team should understand what changed. +- Discuss the revised target before committing. The team should be able to commit credibly to the new target. +- Document the change in the OKR system. + +To stakeholders. + +- Notify stakeholders explicitly. Do not let recalibration appear as a quiet edit. +- Explain the trigger and the revised target. +- Invite questions; stakeholder concerns may surface issues with the recalibration that warrant further discussion. + +To the org. + +- Recalibration patterns inform org-wide OKR discussion. If multiple teams recalibrate in the same quarter, surface the pattern; the strategic clarity may be lacking. + +--- + +## Common recalibration failures + +Recalibration as the default. Teams routinely revise OKRs mid-quarter. The OKR system collapses into rolling targets that always reflect current state. + +Recalibration to avoid stretch discomfort. Teams revise when OKRs feel uncomfortable; targets drift toward sandbagging. + +Recalibration without trigger documentation. OKRs change without surfaced reason; the change becomes invisible to stakeholders. + +Refusal to recalibrate when warranted. Teams hold OKRs even when strategy genuinely shifted; quarter ends with OKRs disconnected from strategy. + +Recalibration to avoid scoring low. Teams revise targets in the last weeks of the quarter to make the score look better. Scoring loses honesty. + +Org-wide recalibration cascade. One team's recalibration triggers others; the whole quarter resets; the OKR system loses meaning. + +--- + +## Methodology-level choices that stay in the public skill + +The default-to-hold principle. When to recalibrate (strategic shift, major disruption, invalidating information). When not to recalibrate (uncomfortable, off-track, easier-feels-better). The recalibration discipline. Frequency norms. Honest vs avoidance recalibration. Communication. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools that capture recalibration history. Specific approval workflows for recalibration. The team's own conventions for recalibration communication. These vary by org. diff --git a/skills/okr-design/references/objective-design-patterns.md b/skills/okr-design/references/objective-design-patterns.md new file mode 100644 index 0000000..e1fc8fa --- /dev/null +++ b/skills/okr-design/references/objective-design-patterns.md @@ -0,0 +1,191 @@ +# Objective design patterns + +Outcome-vs-output distinction. Strong vs weak objective characteristics. Worked examples across domains. The few-objectives discipline. + +Objectives are the outcome statements that name what the team is trying to achieve in the quarter. Most OKR failure begins at the objective level: outputs disguised as outcomes, vague aspirations, or too many objectives diluting focus. Getting the objective right is upstream of everything else. + +--- + +## Outcome vs output + +The most consequential distinction. + +Output objectives. Describe work the team plans to do. + +- "Ship the activation redesign." +- "Migrate to the new auth service." +- "Run 12 customer interviews." + +Outcome objectives. Describe results the team is trying to achieve. + +- "Improve activation for new sign-ups so more reach value-realization in week one." +- "Establish auth foundations that support enterprise compliance review." +- "Build a research-grounded picture of how mid-market customers actually use the product." + +Why the distinction matters. Outputs can be shipped without producing outcomes. The activation redesign ships; activation rate stays the same. The auth migration completes; compliance review still fails. The interviews happen; the team cannot point to decisions that changed. + +The output-as-outcome failure. Output objectives shift the team's incentives toward shipping rather than achieving. The team optimizes for the work; the work gets done; the underlying goal goes unachieved. + +The cure. Each output objective gets rewritten to name the outcome the output is meant to produce. If the team cannot name the outcome, the output's value is unclear and may not warrant quarterly priority. + +--- + +## Strong objective characteristics + +Outcome-focused. Names the result, not the work. + +Specific to the quarter. Vague aspirations ("be more user-focused") do not focus quarterly work. The objective should be specific enough that the team knows when they have moved it forward. + +Inspiring without being fantasy. The team should feel pulled toward the objective. Fantasy demoralizes; sandbag bores. Stretch motivates. + +Few in number. 2-4 objectives per team per quarter. More dilutes focus; the team works on too many things and excels at none. + +Connected to strategy. Objectives ladder up to company-level priorities or to the team's strategic mandate. Disconnected objectives produce work that does not contribute to the org's direction. + +Within team influence. The team can affect the outcome through their work. Objectives entirely dependent on external factors are not the team's to commit to. + +--- + +## Weak objective characteristics + +Output-disguised-as-outcome. "Ship the redesign" is the work; the outcome should be the result the redesign produces. + +Too vague. "Improve user experience" is too broad to focus a quarter's work. What aspect of UX, in what part of the product, for which users? + +Too tactical. "Refactor the auth service" is a tactical decision the team makes within larger initiatives, not a quarterly objective. + +Too many. 8 objectives produces no focus. Each objective gets less attention; trade-offs become impossible because everything is priority. + +Disconnected from strategy. Objectives that do not ladder to company priorities or team mandate produce work that does not contribute. + +Outside team influence. "Total revenue grows 30%" may not be the product team's to commit to if revenue depends on sales execution, market conditions, and product work combined. + +--- + +## Worked objective examples by domain + +### B2B SaaS product team + +- "Improve activation for new sign-ups so that more reach the value-realization moment within their first week." +- "Make the support experience deflect predictable issues so the team can focus on harder cases." +- "Establish enterprise-readiness foundations so we can serve the segment we are targeting next year." + +### Consumer mobile app team + +- "Increase retention through the first month so users build habit before the typical churn window." +- "Improve performance and reliability so the experience matches the brand's reputation." + +### Internal platform team + +- "Reduce the time it takes engineering teams to ship a new service from days to under a day." +- "Eliminate the top three reasons engineering teams escalate to platform support." + +### Marketing-product team + +- "Convert more product trial users to paid by removing friction in the upgrade path." +- "Position the product clearly enough that prospects evaluating against alternatives understand the differentiation." + +Each objective is outcome-focused, specific to the quarter, and within the team's ability to influence. The work that produces these outcomes is multiple roadmap items; the OKR is the result, not the work. + +--- + +## The few-objectives discipline + +Most teams should have 2-4 objectives per quarter. The discipline produces focus. + +Why fewer is better. + +- Each objective gets serious attention. The team thinks about it weekly, makes trade-offs against it, surfaces blockers. +- Trade-offs are possible. With 3 objectives, the team can decide that work on objective A takes priority over work on objective C this week. With 12 objectives, all work claims priority. +- The team can credibly commit. 3 objectives are credible; 12 are not. + +Why more feels tempting. + +- Multiple stakeholders want their priorities reflected. Adding objectives feels like accommodating; capping objectives feels like saying no. +- The team sees many things they could pursue. Picking 3 means deferring others. +- Past quarters' OKRs sometimes accumulate; teams forget to retire objectives that no longer fit. + +The discipline. + +- Cap objectives. 4 is the upper bound for most teams. +- Surface what is being deferred. The objectives that did not make the cut get named explicitly; the team's choice to defer is transparent. +- Retire objectives quarter-over-quarter. Objectives are quarterly; they do not carry over by default. + +--- + +## Objectives across an org + +When the org has multiple teams, objectives should compose without overlap or contradiction. + +Cross-team coordination. + +- Objectives that depend on multiple teams should name the dependencies explicitly. The product team's objective may depend on engineering hiring; the engineering team's objective may depend on product prioritization. +- Objectives that conflict across teams need resolution before the quarter starts. Teams pulling in opposite directions waste capacity. + +Team mandate alignment. + +- Each team's objectives should fit the team's mandate. Product team objectives are product outcomes; engineering team objectives are engineering outcomes; design team objectives are design outcomes. +- Cross-functional outcomes (e.g., "improve activation") require multiple teams to commit. The lead team owns the OKR; the supporting teams commit dependencies in their own OKRs. + +--- + +## Objective writing process + +How objectives get drafted. + +Draft sources. + +- Strategy work that named the priorities for the quarter or year. +- Discovery synthesis that identified user-job priorities. +- Roadmap-planning work that surfaced major initiatives. +- Performance review that identified gaps from the prior quarter. + +Draft method. + +- Start from the outcome the team is trying to produce. +- Surface multiple draft phrasings. +- Test each: is this an outcome or an output? Is it specific enough? Is it within team influence? +- Iterate to a 2-4 objective set that the team can commit to and that ladders to strategy. + +Stakeholder review. + +- Draft objectives circulate to stakeholders before commit. Surfaces dependencies and conflicts. +- Stakeholder feedback informs revisions; the team owns the final commit. + +The commitment. Objectives published and visible to the org. The team is on the hook for them. + +--- + +## Objective revision through the quarter + +Objectives generally hold for the quarter. See `mid-quarter-recalibration.md` for when revision is appropriate. + +The default. Objectives stay; tactics adapt to keep moving toward them. + +The exception. Strategic shift, major external disruption, or invalidating information warrants revision. Rare. + +--- + +## Common objective design failures + +Output objectives. "Ship X" instead of "Achieve outcome Y through X." Cure: name the outcome. + +Vague objectives. "Improve experience" without specifying what or where. Cure: specificity. + +Too many objectives. 8+ per team per quarter. Cure: cap at 4. + +Tactical objectives. Specific implementation decisions framed as objectives. Cure: tactical decisions belong in roadmap items, not OKRs. + +Strategic-disconnect. Objectives that do not ladder to company or team priorities. Cure: explicit ladder before commit. + +Out-of-influence. Objectives entirely dependent on factors the team does not control. Cure: rewrite to focus on what the team can affect. + +--- + +## Methodology-level choices that stay in the public skill + +The outcome-vs-output distinction. Strong and weak objective characteristics. Worked examples across domains. The few-objectives discipline. Cross-team coordination. The drafting and review process. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools the team uses. Specific document templates for objectives. Specific stakeholder-review formats. The team's own conventions for objective wording within the principles. These vary by team and tooling. diff --git a/skills/okr-design/references/okr-anti-patterns.md b/skills/okr-design/references/okr-anti-patterns.md new file mode 100644 index 0000000..f70fe2f --- /dev/null +++ b/skills/okr-design/references/okr-anti-patterns.md @@ -0,0 +1,249 @@ +# OKR anti-patterns + +Eight-plus anti-patterns including OKR-as-roadmap, sandbagging, fantasy, vanity metrics, OKR theater, compensation coupling, and others. Each anti-pattern names a recurring failure mode that decays OKR practice over time. + +--- + +## Anti-pattern 1: OKR-as-roadmap + +The pattern. OKRs are written as a list of features the team plans to ship. + +Examples. + +- "Objective: Ship the activation redesign. KR: Activation redesign launched by week 8. KR: Welcome email v2 launched by week 4." + +Why it fails. + +- Outputs disguised as outcomes. The team is committing to work, not to results. +- The outcome the work is meant to produce goes unspecified; the team can ship the redesign without producing the activation outcome. +- OKRs become roadmap commitments to stakeholders; mid-quarter tactical changes feel like broken promises. + +The cure. Each OKR names the outcome the work is meant to produce. The work itself lives in the roadmap. + +--- + +## Anti-pattern 2: Sandbagging + +The pattern. OKRs designed to hit 100%. Targets at or below the team's current trajectory. + +How it manifests. + +- KR targets within 5% of current values. +- KR targets achievable on standard execution without focused effort. +- Average end-of-quarter scores at 95%+. +- Team consistently celebrates "hitting all our OKRs." + +Why it fails. + +- No stretch; no learning. The team did not commit to ambition; the OKR practice produced no signal beyond what the team would have done anyway. +- Sandbagging compounds. Teams that sandbag once learn that sandbagging is safe; subsequent quarters get worse. +- Stakeholder trust degrades. Stakeholders learn that "hitting OKRs" does not mean ambitious work was done. + +The cure. Set targets above the team's current trajectory. Use the historical-trajectory test: where would the metric land without focused effort? The OKR target should be meaningfully above that. + +--- + +## Anti-pattern 3: Aspirational fantasy + +The pattern. OKRs that nobody can hit. Targets with no realistic effort path. + +How it manifests. + +- KR targets at 5x or 10x current values without underlying capacity changes. +- Targets set for inspiration rather than commitment. +- Average end-of-quarter scores at 30% or below. +- Team disengages from OKRs by week 3-4 of the quarter. + +Why it fails. + +- Demoralizing. Teams cannot hit fantasy targets; the targets become decoration. +- Loss of meaning. When OKRs cannot be hit, scoring loses meaning; teams stop tracking. +- Compensation distortion. If OKRs are tied to compensation, fantasy targets create unfairness; teams cannot earn rewards regardless of effort. + +The cure. Validate against the effort-path test. Can the team identify specific initiatives that would produce the target? If yes, the target is reachable. If the team cannot identify any path, recalibrate. + +--- + +## Anti-pattern 4: Vanity metrics + +The pattern. KRs that measure impressive numbers not tied to the outcome. + +Examples. + +- "Reach 1M users." +- "Generate 10K leads." +- "Reach 500K social followers." + +Why it fails. + +- Numbers can be moved without producing the outcome the OKR was meant to address. +- Vanity targets often correlate with marketing or acquisition spend rather than with product outcomes. +- The team can hit vanity KRs while the underlying outcome (engagement, retention, revenue) does not improve. + +The cure. Each KR should connect to the outcome the OKR targets. If the connection is unclear, the KR is probably vanity. Replace with a KR that more directly measures the outcome. + +--- + +## Anti-pattern 5: OKR theater + +The pattern. OKRs are documented and presented but do not drive decisions. + +How it manifests. + +- OKRs are set at the start of the quarter and not referenced again until end of quarter. +- Mid-quarter prioritization decisions ignore OKRs. +- The team makes the same prioritization choices that they would have made without OKRs. +- OKR scores are produced at end of quarter but do not inform the next quarter's planning. + +Why it fails. + +- The OKR practice produces overhead without value. The team spends time on OKR ceremony without changing what they would have done. +- Stakeholder skepticism builds. Stakeholders learn that OKRs are not load-bearing. +- The practice decays further over time as the team rationalizes that the ceremony does not matter. + +The cure. Tie OKRs to specific decisions. Mid-quarter prioritization debates should reference OKRs. Roadmap items should map to OKRs. Scoring should inform the next quarter. If none of these happen, the OKR practice is theater; reform or abandon. + +--- + +## Anti-pattern 6: Compensation coupling + +The pattern. OKR scores directly determine bonuses or performance ratings. + +Why it fails. + +- Sandbagging incentives become severe. Teams set OKRs they know they can hit to protect their compensation. +- Honest scoring suffers. Teams round scores up to avoid compensation impact. +- Stretch ambition disappears. The OKR practice collapses to "what we are confident we can hit." +- Team trust in OKRs degrades; the practice becomes performance management theater. + +The cure. Decouple OKRs from compensation. Compensation flows through performance reviews informed by many inputs (manager assessment, peer feedback, role expectations); OKR scores may be one input but should not be dominant. + +The transition. Orgs that have coupled OKRs and compensation need explicit decoupling communication. Teams need to trust that scoring honestly will not affect bonuses; the trust takes 2-3 cycles to establish. + +--- + +## Anti-pattern 7: OKR proliferation + +The pattern. Teams set 8-12 OKRs per quarter. Every team member's work is reflected in some OKR. + +Why it fails. + +- Focus dilutes. The team works on too many things; trade-offs become impossible because everything is priority. +- Tracking burden grows. Weekly check-ins become status reports across too many KRs. +- Scoring becomes performative. Teams cannot honestly score 40+ KRs at end of quarter. + +The cure. Cap OKRs. 2-4 objectives per team; 3-5 KRs per objective. Surface what is not in OKRs as deferred work that the team is choosing not to commit to this quarter. + +--- + +## Anti-pattern 8: Cascade theater + +The pattern. OKR documents include cascading ladders that look connected but do not actually drive work. + +How it manifests. + +- Team OKRs claim ladders to company OKRs but the team's actual work would have happened regardless. +- Cascading documents look impressive but do not coordinate cross-team work. +- The cascade is performed for stakeholders rather than for execution. + +Why it fails. + +- Cascading work is overhead without value. +- Cross-team coordination does not actually happen through the cascade. +- Stakeholders learn that the cascade is theater. + +The cure. Make ladders explicit only when they genuinely connect. Loosen cascading where strict ladders produce theater. See `cascading-okrs-decisions.md` for the discipline. + +--- + +## Anti-pattern 9: Mid-quarter recalibration as default + +The pattern. OKRs get revised mid-quarter routinely. The team uses recalibration to soften OKRs that feel uncomfortable. + +Why it fails. + +- OKRs lose accountability. Teams learn that revising mid-quarter is acceptable; commitment loosens. +- Stretch ambition disappears. Discomfort triggers recalibration rather than effort. +- Targets drift toward sandbagging quarter over quarter. + +The cure. Hold OKRs absent strategic shift, major disruption, or invalidating information. See `mid-quarter-recalibration.md` for the discipline. + +--- + +## Anti-pattern 10: Output-only KRs + +The pattern. Key results count work shipped rather than measure outcomes produced. + +Examples. + +- "Ship 5 onboarding initiatives." +- "Run 12 customer interviews." +- "Publish 8 marketing pieces." + +Why it fails. + +- Counts work, not outcomes. The team can hit these by doing work without producing the outcome. +- Optimizes for shipping volume rather than impact. +- Loses the connection between work and result. + +The cure. For each output KR, identify the outcome the output is meant to produce. Replace the count with a measurement of the outcome. + +--- + +## Anti-pattern 11: KRs entirely outside team influence + +The pattern. KRs depend on factors the team cannot control. + +Examples. + +- "Total revenue grows 30%" (depends on sales execution and market conditions, not just product work). +- "Maintain market share" (depends on competitive dynamics). +- "Reach Series B" (depends on investor decisions outside the team). + +Why it fails. + +- The team cannot credibly commit. Effort does not produce predictable outcomes. +- Failure is not informative. Misses do not reveal what the team should have done differently. +- Demoralizing. Teams hit fail OKRs they had little ability to affect. + +The cure. Rewrite KRs to focus on what the team can move. Total revenue may not be the team's KR; the team's contribution to revenue (e.g., product-led acquisition rate) might be. + +--- + +## Anti-pattern 12: Generous scoring + +The pattern. End-of-quarter scoring rounds up systematically. + +How it manifests. + +- KRs at 0.55 score 0.6 or 0.7. +- KRs at 0.85 score 1.0. +- The team's average score is 0.85+ even when objective outcomes were mid-range. + +Why it fails. + +- Honest signal lost. Scoring no longer reflects outcomes. +- Sandbagging compounds. Teams learn that scoring high is rewarded; subsequent quarters drift further. +- Lessons get lost. Misses scored as hits do not inform improvement. + +The cure. Hold the discipline of honest scoring. Document context per score; the context surfaces what produced the actual outcome regardless of the number. + +--- + +## The cross-cutting pattern + +Most OKR anti-patterns share a single root: optimizing for the appearance of OKR success rather than for the underlying outcomes. + +Sandbagging optimizes for hitting 100%. Fantasy optimizes for inspirational targets. OKR theater optimizes for documentation. Compensation coupling optimizes for bonus protection. Generous scoring optimizes for end-of-quarter celebration. + +Each anti-pattern produces apparent OKR success while undermining the OKR practice's actual purpose. The fix in every case is the same: focus on the underlying outcomes the practice is meant to produce, not on the OKR ceremony itself. + +--- + +## Methodology-level choices that stay in the public skill + +The twelve anti-patterns with diagnoses and cures. The cross-cutting appearance-vs-outcome pattern. + +## Implementation choices that stay internal + +Specific anti-pattern detection in the team's tracking tools. Specific reviewer training. Specific intervention patterns when anti-patterns are detected. The team's own conventions for catching drift early. These vary by team. diff --git a/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md b/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md new file mode 100644 index 0000000..9f9514c --- /dev/null +++ b/skills/okr-design/references/okrs-vs-roadmap-vs-metrics.md @@ -0,0 +1,235 @@ +# OKRs vs roadmap vs metrics + +The three concepts and their relationships. Common conflations. The complete picture across all three. + +OKRs, roadmaps, and metrics are often conflated. Each serves a different purpose; conflating them produces confusion that decays each practice. Distinguishing them clarifies what each is for and how they compose. + +--- + +## OKRs + +Outcome targets for the quarter. + +Characteristics. + +- Quarterly time horizon. +- Outcome-focused. +- Stretch-ambition. +- Designed for accountability and learning, not for execution sequencing. + +Examples. + +- Objective: "Improve activation for new sign-ups." +- Key result: "Increase first-week activation rate from 32% to 45%." + +What OKRs are not. + +- A roadmap. OKRs do not specify which initiatives to ship. +- A metric. OKRs are quarterly targets on metrics; the metrics themselves are tracked continuously regardless of OKRs. +- A commitment to specific work. The team commits to pursuing the outcome; the tactics adapt. + +--- + +## Roadmap items + +Initiatives the team is building or doing. + +Characteristics. + +- Variable time horizon (weeks to months per initiative). +- Output-focused (the work being done). +- Sequenced by priority and dependency. +- Designed for execution coordination. + +Examples. + +- "Onboarding redesign." +- "Migrate to new auth service." +- "Build admin role overhaul." + +What roadmap items are not. + +- OKRs. Roadmap items are work; OKRs are outcomes. +- Metrics. Roadmap items contribute to moving metrics but are not metrics themselves. +- Permanent commitments. Items can be added, dropped, or re-prioritized as circumstances change. + +--- + +## Metrics + +Ongoing measurements the team tracks. + +Characteristics. + +- Continuous time horizon (always tracked). +- Quantitative, time-stamped, queryable. +- Designed for monitoring, learning, and OKR target-setting. + +Examples. + +- "First-week activation rate." +- "Median time-to-first-value." +- "Onboarding flow completion rate." + +What metrics are not. + +- OKRs. Metrics are continuous; OKRs are quarterly targets on metrics. +- Roadmap items. Metrics are measurements; roadmap items are work. +- Targets. Metrics are values; targets on metrics are KRs (or more generally, performance targets). + +--- + +## The relationship + +How the three compose. + +OKR: "Improve activation for new sign-ups." + +- Key result: "First-week activation rate from 32% to 45% by end of quarter." + - Underlying metric: "First-week activation rate" (tracked continuously). + - Roadmap items contributing: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +The composition. + +- OKR names the outcome. +- Key result quantifies the outcome with a metric and target. +- Metric is the underlying measurement. +- Roadmap items are the work the team does to move the metric. + +The flow. + +- Strategy informs OKRs. +- OKRs inform roadmap prioritization (which work moves which OKR). +- Roadmap items get executed. +- Metrics track the impact. +- Scoring at end of quarter assesses the OKR's actual outcome. + +--- + +## Common conflations + +### OKRs treated as roadmap commitments + +The pattern. "Ship the onboarding redesign" written as an OKR. + +The diagnosis. This is a roadmap item, not an OKR. The OKR is the outcome the redesign is meant to produce. + +The cure. Rewrite as outcome: "Improve activation through onboarding redesign that reaches first-week activation 45%." The redesign is the contributing work; the outcome is what the work is meant to produce. + +### Roadmap items treated as OKRs + +The pattern. Quarterly OKRs are a list of features the team plans to ship. + +The diagnosis. Output disguised as outcome. The team is committing to work, not to results. + +The cure. For each output OKR, identify the outcome the output is meant to produce. The OKR is the outcome; the output is roadmap work that contributes. + +### Every metric needing an OKR + +The pattern. The team feels every metric they track must have an OKR target. + +The diagnosis. Metrics serve monitoring purposes regardless of whether the team is currently driving them. Some metrics are leading indicators the team watches without driving; some are protective metrics the team watches to ensure they do not degrade. + +The cure. OKRs select which metrics the team is actively driving this quarter. Other metrics get tracked without OKR targets. + +### OKRs as roadmap commitments to stakeholders + +The pattern. Stakeholders ask "what are you committing to ship next quarter?" The team answers with OKRs. + +The diagnosis. The team is using OKRs as roadmap; stakeholders interpret them as roadmap commitments; mid-quarter tactical adjustments feel like broken promises. + +The cure. Distinguish between OKRs (outcomes the team commits to pursue) and roadmap (work the team plans to do). Stakeholders can see both; the OKR is what the team is accountable for; the roadmap is the team's current best guess at what work will produce the outcome. + +### Treating metrics as OKRs + +The pattern. "Maintain CSAT at 4.5" written as an OKR for a quarter when the team has no specific work aimed at CSAT. + +The diagnosis. This is metric monitoring, not an OKR. OKRs are stretch outcomes the team is actively pursuing; metric monitoring continues regardless. + +The cure. Track CSAT as a metric. Set an OKR if the team is actively driving CSAT improvement; otherwise, the metric is monitored without an OKR. + +--- + +## When the three diverge + +Sometimes OKRs, roadmap, and metrics tell different stories. + +The pattern. + +- OKR is on track (KR moving toward target). +- Roadmap items are shipping on schedule. +- A different metric the team tracks is degrading. + +The interpretation. The OKR work is succeeding at its target; an unintended consequence may be hurting another metric. The team must decide whether to address the unintended consequence within the quarter or to defer. + +The discipline. OKRs are the formal commitment; roadmap items contribute to OKRs; metrics monitor everything (including OKR targets and protective metrics). When the three diverge, the team has decisions to make. + +--- + +## Roadmap-OKR alignment + +How the roadmap maps to OKRs. + +The mapping. + +- Each roadmap item gets associated with the OKR(s) it contributes to. +- Items not associated with any OKR are either team-specific work (technical debt, tooling) or candidates for deferral. + +Worked example. + +- OKR: "Improve activation for new sign-ups." +- Contributing roadmap items: "Onboarding redesign," "Welcome email sequence revision," "Activation triage automation." + +- OKR: "Establish enterprise-readiness foundations." +- Contributing roadmap items: "Admin role overhaul," "SOC 2 audit preparation." + +- Team-specific roadmap items (no OKR ladder): "Migrate to new auth service" (foundational; supports many OKRs), "Strengthen test coverage in critical paths" (engineering health). + +The discipline. All roadmap items have either an OKR ladder or an explicit team-specific designation. Items with neither are candidates for deprioritization. + +--- + +## Metric coverage and OKR targets + +How metrics are selected and how OKR targets relate. + +Metric coverage. The team tracks metrics that: + +- Reflect strategic outcomes (input metrics for OKRs). +- Monitor protective concerns (metrics that should not degrade). +- Surface leading indicators of larger outcomes. +- Provide diagnostic signal for issues. + +OKR target selection. Each quarter, the team selects which metrics to set OKR targets on: + +- Metrics tied to the quarter's strategic priorities. +- Metrics where stretch progress is plausible and meaningful. +- Often a subset of the broader metric set. + +The remaining metrics. Tracked without OKR targets. Monitored for movement; surfaced if they shift unexpectedly. + +--- + +## Common failures across the three + +OKR-as-roadmap. Quarterly commitments written as features rather than outcomes. + +Roadmap-as-OKR. Roadmap items called OKRs; output disguised as outcome. + +Every-metric-as-OKR. OKRs proliferate to cover every tracked metric; focus diluted. + +OKR-without-roadmap-mapping. OKRs set without identifying which work will move them; teams miss the OKRs because no work is aimed at them. + +Roadmap-without-OKR-mapping. Work happens without explicit OKR connection; teams cannot tell what their work is contributing to. + +Metrics-without-OKR-distinction. All metrics treated as targets; team cannot prioritize. + +--- + +## Methodology-level choices that stay in the public skill + +The three concepts and their characteristics. The relationship and composition. Common conflations and cures. When the three diverge. Roadmap-OKR alignment. Metric coverage and OKR target selection. Common failures. + +## Implementation choices that stay internal + +Specific OKR-tracking tools. Specific roadmap tools. Specific metrics dashboards. Specific integration between OKR system and roadmap system. The team's own conventions for OKR-roadmap-metric documentation. These vary by team and tooling. diff --git a/skills/okr-design/references/review-cadence-templates.md b/skills/okr-design/references/review-cadence-templates.md new file mode 100644 index 0000000..8ca8934 --- /dev/null +++ b/skills/okr-design/references/review-cadence-templates.md @@ -0,0 +1,230 @@ +# Review cadence templates + +Weekly check-ins, mid-quarter review, end-of-quarter scoring, quarterly retrospective. Format and time investment per cadence. + +OKRs benefit from a structured review rhythm. The cadence produces accountability infrastructure: weekly tactical adjustment, mid-quarter strategic assessment, end-of-quarter scoring, and quarterly practice review. Teams that skip the cadence often watch OKRs decay into year-end reckoning that produces no learning. + +--- + +## Weekly check-ins + +The shortest, most frequent review. + +Format. + +- 15-30 minutes per team. +- Team reviews progress on each key result. +- Surfaces blockers, dependencies, signal that the trajectory is off. +- Decides tactical adjustments for the upcoming week. + +Structure. + +- Per KR: current value, trajectory, blockers, planned work for the upcoming week. +- Cross-OKR: any priority shifts, dependencies needing attention. +- Closing: commitments for the week. + +Purpose. + +- Tactical adjustment, not OKR adjustment. +- Surface blockers early so they can be addressed. +- Maintain focus on OKRs across the quarter (without weekly check-ins, OKRs get forgotten in the press of immediate work). + +What this is not for. + +- Adjusting the OKR or its targets. That is mid-quarter or end-of-quarter work. +- Status reports for stakeholders. Status reports may flow from the check-in but are a separate output. +- Detailed work review. The check-in is OKR-focused; other work happens elsewhere. + +Common failures. + +- Becoming status reports. The check-in turns into "here's what I did this week"; OKR-driven decisions get crowded out. Reform the format. +- Becoming OKR adjustment sessions. Teams uncomfortable with OKRs sometimes use weekly check-ins to soften them. Hold to tactical scope. +- Skipping when busy. Weeks where the check-in feels less urgent are exactly when discipline is needed. Skip rarely. + +--- + +## Mid-quarter review + +A longer, more strategic review. + +Format. + +- 60-90 minutes per team. +- Roughly week 6 of the quarter (mid-point). +- Honest assessment of trajectory: which KRs are on track, which are off. +- Decision point for any recalibration (rare; should not be the default outcome). +- Surface external dependencies that affect end-of-quarter outcomes. + +Structure. + +- Per OKR: current state vs target, trajectory analysis, on-track or off-track assessment. +- Cross-OKR: priority adjustments, capacity reallocations, blockers requiring escalation. +- Recalibration check: is any OKR a candidate for revision per the strategic-shift / disruption / invalidating-information criteria? (See `mid-quarter-recalibration.md`.) +- Closing: tactical decisions for the second half of the quarter. + +Purpose. + +- Strategic assessment of OKR progress. +- Course correction before end-of-quarter when there is still time. +- Surface OKRs that may need recalibration (with the discipline that recalibration should be rare). + +What this is not for. + +- Routine recalibration. Most mid-quarter reviews end with no recalibration; tactical adjustments are the typical output. +- Scoring. Scoring is end-of-quarter; mid-quarter assesses trajectory toward the score. +- Postmortem. Postmortems are for completed work; mid-quarter is for live work in progress. + +Common failures. + +- Becoming a recalibration session. Teams uncomfortable with stretch use mid-quarter review to lower OKRs. Hold to the rare-recalibration discipline. +- Becoming a status meeting. The session becomes a presentation rather than a decision-making review. Reform format to surface decisions. +- Skipping. Teams that skip mid-quarter review often discover at end of quarter that they could have course-corrected; the missed opportunity is the cost. + +--- + +## End-of-quarter scoring + +The OKR-cycle closing review. + +Format. + +- 60-90 minutes per team. +- Last week of the quarter. +- Score each key result honestly. +- Identify what produced the scores: tactical choices, external factors, OKR design decisions. +- Inform next-quarter OKR design with the lessons. + +Structure. + +- Per KR: actual outcome, score (0.0-1.0), context (what produced this score). +- Per objective: average KR score, context. +- Cross-OKR: average score across all OKRs (informs whether the quarter was stretch, sandbag, or fantasy). +- Lessons: what this quarter's scoring reveals about OKR design, team capacity, or strategic clarity. +- Closing: insights to carry into next quarter's OKR setting. + +Purpose. + +- Honest scoring of outcomes. +- Learning from the gap between target and outcome. +- Input to the next quarter's OKR design. + +What this is not for. + +- Compensation discussions. OKRs work best decoupled from compensation; scoring should not feel like a performance evaluation. +- Blame allocation. Misses are informative; the discussion is about what produced the gap, not who failed. +- Setting next quarter's OKRs. That is a separate session. + +Common failures. + +- Generous scoring. Scores rounded up; the team protects feelings; honest signal lost. Hold the discipline. +- Skipping context. Scores published without explanation of what produced them. Lessons get lost. +- Treating scores as performance. Compensation coupling produces sandbagging in subsequent quarters. +- Not informing next quarter. Scores reviewed but lessons do not influence the next OKR setting. The cycle does not learn. + +--- + +## Quarterly retrospective + +A separate review focused on the OKR practice itself. + +Format. + +- 60-90 minutes per team or org. +- After end-of-quarter scoring. +- Reviews the OKR practice, not the OKR outcomes. +- Often combined with the next-quarter OKR setting session. + +Structure. + +- What worked in this quarter's OKR practice (cadence, format, design)? +- What did not work? +- What should change in the next cycle? +- What patterns are emerging across multiple quarters? + +Purpose. + +- Improve the OKR practice itself. +- Surface decay or drift in OKR discipline. +- Inform process changes for the next cycle. + +What this is not for. + +- Scoring or recalibrating current OKRs. That is end-of-quarter work. +- Setting next quarter's OKRs. That is a separate session that uses the retrospective's inputs. + +Common patterns surfaced. + +- Sandbagging or fantasy drift. Average score patterns over multiple quarters reveal practice decay. +- Cadence breakdown. Weekly check-ins becoming status reports; mid-quarter reviews becoming recalibration sessions. +- Cascading misalignment. Teams setting OKRs that do not ladder; cross-team coordination failing. +- Compensation coupling. OKRs becoming performance theater because they are tied to bonuses. + +Common retrospective failures. + +- Skipping the retrospective. The OKR practice does not improve; decay accumulates. +- Conflating with next-quarter OKR setting. Both can happen in one session, but the retrospective lens (process review) should be distinct from the OKR design lens (setting). +- Producing recommendations without follow-through. Retrospectives surface improvements; the team must implement them in the next cycle for the retrospective to matter. + +--- + +## The cadence as a system + +The four cadences compose. + +The system. + +- Weekly check-ins maintain tactical focus and surface blockers. +- Mid-quarter review provides strategic assessment and rare recalibration opportunity. +- End-of-quarter scoring produces honest signal on outcomes. +- Quarterly retrospective improves the practice over time. + +The reinforcement. + +- Weekly check-ins make mid-quarter assessment honest (the team has been tracking trajectory all along). +- Mid-quarter review surfaces issues end-of-quarter scoring will face. +- End-of-quarter scoring informs the retrospective. +- The retrospective informs the next cycle's design. + +The skip risk. Teams that skip cadences often skip several. Weekly check-ins falter; mid-quarter review becomes ad-hoc; end-of-quarter scoring becomes generous because the team has not been tracking honestly all along; the retrospective never happens. + +--- + +## Cadence ownership + +Each cadence has a clear owner. + +Weekly check-ins. Owned by the team lead (manager, PM, engineering lead). Facilitates the meeting; ensures it stays tactical. + +Mid-quarter review. Owned by the team lead, often with cross-functional partners attending. Surfaces strategic decisions. + +End-of-quarter scoring. Owned by the team lead. Ensures honest scoring; documents context. + +Quarterly retrospective. Owned by the team lead or by a process-focused role (chief of staff, ops lead). Often facilitated by someone slightly outside the team to bring fresh perspective. + +Cross-team coordination. When multiple teams have OKRs that compose, coordination across teams happens at the cadence boundaries (typically mid-quarter review). + +--- + +## Common cadence failures + +Skipping cadences. Weekly check-ins falter; mid-quarter review becomes ad-hoc; the system breaks. + +Cadence merging. Mid-quarter review and end-of-quarter scoring combined into one session. Loses the distinct purposes. + +Status-report drift. Weekly check-ins become status reports; tactical decisions get displaced. + +Recalibration drift. Mid-quarter review becomes a recalibration session; OKRs lose accountability. + +Generous-scoring drift. End-of-quarter scoring rounds up; honest signal lost. + +Retrospective skipping. OKR practice does not improve; decay accumulates. + +--- + +## Methodology-level choices that stay in the public skill + +The four cadence formats. Time investment per cadence. Structure and purpose per cadence. The cadence-as-system reinforcement. Ownership. Common failures. + +## Implementation choices that stay internal + +Specific meeting templates. Specific OKR-tracking tools that support each cadence. Specific facilitation conventions. Specific cross-team coordination formats. The team's own conventions for cadence cadence (no pun intended). These vary by team and tooling. diff --git a/skills/okr-design/references/scoring-discipline.md b/skills/okr-design/references/scoring-discipline.md new file mode 100644 index 0000000..b51963d --- /dev/null +++ b/skills/okr-design/references/scoring-discipline.md @@ -0,0 +1,191 @@ +# Scoring discipline + +The 0.0-1.0 scale. The 60-70% target. Scoring honesty. What 100% and 30% mean. The compensation question. + +End-of-quarter scoring is where OKR practice succeeds or decays. Honest scoring produces signal: which OKRs the team hit, which they missed, what the gap reveals about the work. Dishonest scoring produces theater: 100% scores claimed regardless of outcome, generous rounding, partial credit for effort rather than outcome. + +--- + +## The 0.0-1.0 scale + +Each key result scores from 0.0 (no progress) to 1.0 (fully achieved). The objective scores as the average of its key results. + +Key result scoring examples. + +- KR: "Increase first-week activation rate from 32% to 45%." +- Outcome: rate reached 41%. +- Score: (41 - 32) / (45 - 32) = 9/13 = 0.69. + +- KR: "Reduce median time-to-first-value from 4.2 days to under 2 days." +- Outcome: reduced to 2.6 days. +- Score: (4.2 - 2.6) / (4.2 - 2.0) = 1.6/2.2 = 0.73. + +- KR: "Pass SOC 2 Type II audit with zero high-severity findings." +- Outcome: passed with zero high-severity findings. +- Score: 1.0 (binary KR; achieved). + +Objective scoring. Average of the key result scores. + +- Objective with 3 KRs scoring 0.69, 0.73, 1.0: objective scores (0.69 + 0.73 + 1.0) / 3 = 0.81. + +--- + +## The 60-70% target + +Stretch OKRs are designed so that the average score across the team's OKRs is 0.6-0.7. + +Why this target. + +- Average above 0.85 suggests sandbagging. The team set OKRs they were already on track to deliver. +- Average below 0.4 suggests fantasy. The team set OKRs that no realistic effort path would have produced. +- Average between 0.6-0.7 suggests stretch. The team committed to ambition and delivered most of it. + +The trajectory check. Track the team's average score over multiple quarters. Drift toward 0.85+ signals sandbagging is creeping in; drift toward 0.4 signals fantasy. The target zone is 0.55-0.75 over a multi-quarter window. + +Variance is normal. Some quarters will hit 0.8 average; some will hit 0.5. The variance reflects the genuine uncertainty in stretch OKRs. Programs that hit 0.65 every single quarter are usually managing scores rather than honestly scoring outcomes. + +--- + +## Scoring honesty + +Score the actual outcome, not the effort. A team that worked hard but did not move the metric scores low. A team that got lucky and moved the metric without much effort scores high. The score reflects outcome. + +Do not round up. A KR at 0.55 scores 0.55, not 0.6. Honest scoring produces honest signal. Rounding up across multiple KRs accumulates into systemic over-scoring. + +Acknowledge what changed. Some misses reflect mid-quarter priority shifts. Surface these without using them as excuses. "We deprioritized this in week 5 to address the security incident" is honest context; "we hit our priorities even though we missed this OKR" is hand-waving. + +Scoring sessions are honest, not adversarial. The scoring conversation is for capturing reality, not for blame. Honest low scores are fine; effort recognition happens elsewhere. + +--- + +## What 100% scores mean + +100% scores warrant scrutiny. + +Possibilities. + +- The OKR was sandbagged. The team set targets they were already on track to hit. +- The team had a great quarter. Sometimes hitting 100% reflects unusual progress; informative. +- The team is rounding up. The actual outcome was 0.85 but got rounded. +- Binary KRs that hit 1.0. A milestone-based KR that achieves the milestone is 1.0; this is not sandbagging. + +The investigation. + +- Compare the target to the historical trajectory. Was the target above what the metric would have done without focused effort? +- Compare the target to other teams setting similar OKRs. Was this target genuinely stretch? +- Look at the work the team did. Did the team push beyond their normal capacity, or did they hit the target on standard execution? + +The interpretation. Single-quarter 100% scores are not necessarily problematic. Repeated 100% scores across many KRs across multiple quarters are a sandbagging signal. The next OKR cycle should set targets above the prior quarter's actuals to prevent sandbagging compounding. + +--- + +## What 30% scores mean + +30% scores warrant scrutiny. + +Possibilities. + +- The OKR was fantasy. Targets had no realistic effort path; the team could not have hit them. +- Unexpected disruption. A market event, security incident, or priority shift consumed capacity that would have gone to the OKR. +- Mid-quarter deprioritization. The team chose to deprioritize this OKR for other work. +- Underperformance. The team did not execute well; the score reflects the execution gap. + +The investigation. + +- Was the target reachable? At setting time, could the team identify effort paths that would produce the target? +- What changed during the quarter that affected the trajectory? +- What did the team actually work on? Did effort match the OKR, or did effort go elsewhere? + +The interpretation. 30% scores are informative regardless of cause. Fantasy targets need recalibration in the next quarter. Disruption-driven misses inform what to plan around. Deprioritization-driven misses surface tension between OKRs and other work. Execution gaps surface team-capability or process issues. + +The non-recovery. Repeated 30% scores quarter after quarter signal that OKR design is failing. Either the org is consistently setting fantasy targets, or the team is consistently mismatched to its commitments. Investigate. + +--- + +## The compensation question + +OKRs work best when not directly tied to compensation. + +The problem with compensation-coupling. When OKRs determine bonuses or reviews, sandbagging incentives become severe. Teams set OKRs they know they can hit. The 60-70% target collapses to 95% target because nobody wants to risk their bonus on stretch. + +Why decoupling works. OKRs become genuine accountability infrastructure. The team can stretch without risking compensation. Honest scoring is safe. Misses produce learning rather than punishment. + +Compensation alternatives. + +- Compensation tied to overall performance (manager assessment, peer feedback, role expectations) rather than to OKR scores specifically. +- OKR scores inform performance review as one input among many, not as the dominant signal. +- Bonus structures based on company performance rather than team-OKR scores. + +The transition for orgs already coupled. Decoupling requires explicit communication. Teams need to trust that scoring honestly will not affect their bonuses. The transition can take 2-3 cycles before teams believe the decoupling is real. + +--- + +## Scoring formats + +How scoring sessions get run. + +The format. + +- Team meets at end of quarter (60-90 minutes). +- Each KR scored honestly. +- Each objective scored as the KR average. +- Discussion: what produced the scores, what worked, what did not. +- Output: published scores with brief context per OKR. + +The discussion content. + +- For high-scoring OKRs: was this stretch? What worked? What can be replicated? +- For low-scoring OKRs: what got in the way? What does the team need next quarter? +- For mid-scoring OKRs: where did the work land? What was the gap between target and actual? + +The output. Scores published to the team and stakeholders. Brief context per OKR. The published record informs the next quarter's setting and the org's broader OKR practice. + +--- + +## Scoring across multiple teams + +When multiple teams cascade to a company OKR, scoring composes. + +The composition. + +- Each team scores its KRs independently. +- The company OKR's score reflects the cumulative outcome (not the average of team scores). +- A company OKR can score high even if some contributing team OKRs scored low, depending on which contributions mattered most. + +Worked example. Company OKR: "Improve net new ARR through enterprise segment growth." + +- Sales team KR (close 8 enterprise deals): scored 0.85 (closed 7). +- Product team KR (enterprise-readiness foundations): scored 0.7 (achieved most foundations; SOC 2 in progress). +- Marketing team KR (enterprise-segment marketing campaigns): scored 0.5 (delayed launch). + +Company OKR score: depends on the actual ARR outcome, not the average of team scores. If ARR met the target despite the marketing delay (because sales over-delivered), the company OKR scores high. + +The discipline. Score outcomes, not averages of inputs. + +--- + +## Common scoring failures + +Rounding up. Systemic over-scoring through small individual rounds. + +Effort-based scoring. Scoring based on how hard the team worked rather than what was achieved. + +Compensation-coupled scoring. Sandbagging incentives produce 95%+ scores. + +Avoidance of low scores. Teams reluctant to score low; OKRs renamed or rewritten retroactively to avoid the miss. + +Aggregate-of-input scoring. Company OKR scored as average of team scores rather than as the actual outcome. + +Scoring without context. Scores published without the conditions that produced them. Lessons get lost. + +One-quarter-at-a-time view. Scoring evaluated only against the current quarter; trajectory over multiple quarters not surfaced. + +--- + +## Methodology-level choices that stay in the public skill + +The 0.0-1.0 scale and worked examples. The 60-70% target. Scoring honesty. What 100% and 30% scores mean. The compensation question. Scoring formats. Scoring across teams. Common scoring failures. + +## Implementation choices that stay internal + +Specific scoring tools and dashboards. Specific scoring-session facilitation formats. Specific compensation structures. The team's own conventions for context publishing. These vary by org. diff --git a/skills/onboarding-wizard-design/SKILL.md b/skills/onboarding-wizard-design/SKILL.md new file mode 100644 index 0000000..28ccaa7 --- /dev/null +++ b/skills/onboarding-wizard-design/SKILL.md @@ -0,0 +1,280 @@ +--- +name: onboarding-wizard-design +description: "Designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. Honest about tutorial-overload (dump everything upfront), skip-friendly-empty (skipped onboarding leads to abandoned product), and earned-progressive-disclosure (right things at the right moments) patterns. Triggers on onboarding wizard, product onboarding, first-run experience, signup flow, activation flow, FRX, time-to-value, ah-ha moment design. Also triggers when activation rates are low, when users skip onboarding and never return, when onboarding flows are being scoped for the first time, or when audience research shows users not finding key features." +category: growth-tooling +catalog_summary: "Designing first-run product onboarding wizards. Distinguishes tutorial-overload (dump everything upfront) from skip-friendly-empty (skipped onboarding leads to abandoned product) from earned-progressive-disclosure (right things at the right moments)" +display_order: 7 +--- + +# Onboarding Wizard Design + +A senior product marketing director's playbook for designing first-run product onboarding wizards that get users to the ah-ha moment without overwhelming them. Step architecture, progressive disclosure, escape hatches, completion incentives, drop-off measurement. The discipline of building an onboarding sequence the user actually completes. + +Most product onboarding wizards fail in one of two ways. They cram every feature into a 12-step intro the user has not earned the patience for. Or they offer a "skip onboarding" button so prominent that users skip into an empty product with no context, and then churn the next day because they never found the value. The activation rate is the metric that matters, and most wizards are optimizing for the wrong thing. + +The wizards that work do something different. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is balanced against staying engaged. The user reaches the ah-ha moment with a sense that the product respected their time. + +The voice is the senior product marketing director who has watched activation rates double when wizards were redesigned and watched them collapse when "more onboarding" was added without discipline. Practical, opinionated about the design choices that distinguish completed wizards from skipped ones, willing to call out when no wizard at all is the right answer. + +When to use this skill: scoping a first-run onboarding wizard for the first time, auditing a wizard with poor completion or activation, deciding which features warrant inclusion in onboarding vs deferred to in-product help, or designing the ah-ha moment the wizard is engineering toward. + +--- + +## What this skill covers + +This skill spans first-run product onboarding wizards. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access). This skill is post-signup product onboarding. Different phase, different audience state. +- `interactive-product-tour` is contextual help WITHIN the product, surfacing across the lifecycle. This skill is the sequential first-run experience. +- `chatbot-flow-design` is conversational help. This skill is non-conversational sequential setup. +- `onboarding-wizard-design` (this skill) is the post-signup wizard's structure, ah-ha moment design, progressive disclosure, skip mechanics, drop-off measurement. +- `pm-spec-writing` is the spec for engineers building the wizard. This skill is about WHAT to build; pm-spec-writing is about communicating it. + +The audience: product marketers, growth marketers, in-house product teams designing activation flows, agencies running activation work for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); in-product contextual tours (covered by `interactive-product-tour`); the engineering implementation; specific Userpilot/Userflow/Pendo/Appcues platform configurations (those stay implementation-side). + +--- + +## The wizard decision: when wizards earn vs when contextual help suffices + +Before designing the wizard, decide whether a wizard is the right tool. + +Wizards earn investment when: + +- The product has a meaningful setup step before value emerges. Connect a data source, invite a teammate, configure a workspace. Without setup, the product is empty; the wizard makes setup tractable. +- The ah-ha moment requires multiple actions in sequence. Single-action ah-ha moments (paste a URL, see a result) often work better with contextual prompts than with wizards. +- The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products. Some audiences (consumer, frictionless tools) reject wizard friction. +- The team can maintain the wizard. Wizards decay as the product evolves; without maintenance commitment, the wizard becomes a liability. + +Wizards do NOT earn investment when: + +- The product reaches value immediately. Single-input tools, simple consumer products. A wizard adds friction without lift. +- Contextual help would suffice. Tooltips, in-feature hints, and progressive in-product education sometimes serve better than upfront wizards. +- The audience expects no friction. Some audiences abandon at any wizard; meet them where they are. +- The team cannot maintain the wizard alongside product changes. Stale wizards point to deprecated features; users hit broken steps. + +The decision is not "should we have an onboarding wizard"; it is "is the wizard the right tool for this specific product and audience." + +Detail in [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md). + +--- + +## Tutorial-overload vs skip-friendly-empty vs earned-progressive-disclosure + +The keystone framing. + +Tutorial-overload. Every feature explained in a 12-step intro before the user has touched the product. Cognitive overload. Users skip if they can; abandon if they cannot. Cost: the wizard's design effort produces a sequence almost nobody completes; activation rate suffers because the user did not reach the value-giving moment. + +Skip-friendly-empty. "Skip onboarding" button at every step, so prominent that users always take it. Users skip; arrive at an empty product with no context; churn within hours. Cost: activation rate falls off a cliff because users never set up the basics that make the product functional. + +Earned-progressive-disclosure. Each step earns the user one step closer to value. The wizard surfaces the right thing at the right moment, not everything upfront. Skip exists but is friction-balanced against staying engaged (e.g., skip places the user in a partially-set-up state with clear callouts to complete setup later). Cost: design effort is significant; activation rate often climbs significantly as a result. + +The litmus test. Watch a new user complete (or skip) the wizard. Did they reach a moment where the product visibly demonstrated value within their first session? If yes, the wizard is earned-progressive-disclosure. If they completed every step but never reached value, tutorial-overload. If they skipped and never returned, skip-friendly-empty. + +--- + +## Step architecture: what belongs in each step, sequence logic + +The structure that makes wizards actually work. + +The principle. Each step should move the user one step closer to value. Steps that do not should be cut. + +Common step patterns. + +- Welcome and orientation. Quick context-setting, often skippable. Sets expectations for what the wizard will do. +- Identity and account context. Who are you, what's your role, what brought you here. Often used to personalize subsequent steps. +- Critical setup step. The one thing the product cannot work without (connect data source, invite teammates, set primary use case). This is often where wizards justify their existence. +- First-action step. Get the user to take a meaningful action that produces visible result. The ah-ha moment lives here or right after. +- Configuration deferral. Surface the things that can be set up later but are commonly needed; let the user defer with a clear path back. +- Confirmation and next steps. Recap what was set up; surface what to do next; route to in-product home. + +Step coherence test. Each step should answer: did this step move the user closer to value? Steps that exist for completeness or feature-pride should be cut. + +Detail in [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md). + +--- + +## The ah-ha moment design + +What the wizard is actually trying to engineer. + +The principle. The ah-ha moment is the moment the user feels "oh, this is what the product does for me." The wizard's structure should engineer toward that moment. + +Identifying the ah-ha moment. + +- It is the visible demonstration of value, not just feature explanation. +- It is action-tied, not knowledge-tied. The user did something and saw the result. +- It is single-shot. One clear moment, not a checklist of moments. +- It is honest. The user genuinely got value; not a contrived demo. + +Design implications. + +- The wizard's path should converge on the ah-ha moment. Steps that do not contribute should be deferred or cut. +- The ah-ah moment should appear within the user's first session, ideally within 5-10 minutes of signup. Longer time-to-value correlates with churn. +- The ah-ha moment differs by audience. The B2B admin's ah-ha moment differs from the end-user's. Wizards may need to differentiate. + +Common ah-ha moment patterns. + +- First successful query/output. The user ran something against their data and saw a useful result. +- First meaningful collaboration moment. The user shared something with a teammate and saw the response. +- First saved configuration. The user set up something they will return to. +- First value-demonstrating insight. The user saw a metric, recommendation, or pattern that surprised them. + +Detail in [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md). + +--- + +## Progressive disclosure patterns + +How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Pattern A: Default-heavy. Each step has smart defaults. The user can accept or override. Most users accept; advanced users override. Reduces cognitive load. + +Pattern B: Required-now, optional-later. Required fields surface in the wizard; optional configuration surfaces in-product after activation. The wizard stays focused. + +Pattern C: Expand-on-demand. Sections collapsed by default; the user expands if interested. Rare; works when the user has agency to explore. + +Pattern D: Branching. Different users see different steps based on earlier answers. Powerful but adds maintenance complexity. + +The discipline. Each piece of information shown in the wizard must justify its inclusion. Decorative information adds friction; surface it later. + +Detail in [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md). + +--- + +## Skip and resume mechanics + +When users skip, where they land. When they resume, what they see. + +The skip principle. Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +Skip patterns. + +- Soft skip with context. "Skip for now" deposits the user into a partially-set-up state with clear callouts to complete deferred setup. +- Skip-and-defer. Skipped steps are queued for later in-product prompts. +- Skip-with-warning. "Skipping setup will limit your experience to X. Continue?" Honest about consequences. +- No skip. For wizards that absolutely require completion (compliance forms, paid signups). Use sparingly. + +Resume patterns. + +- Auto-resume on next login. The user lands at the step they left. +- Manual resume from in-product entry. A persistent "Complete setup" surface that returns the user to the wizard. +- Soft resume. Wizard fades out as the user completes equivalent actions in-product naturally. + +The skip-friendly-empty failure. Skip is too prominent and consequence-free; the user lands in an unconfigured product and has no path back. Activation collapses. + +The cure. Skip is honest about consequences and offers a path back. The user who skips knows what they skipped. + +Detail in [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md). + +--- + +## Drop-off measurement and remediation + +Where users abandon the wizard, and how to fix it. + +Per-step instrumentation. Track step start, step completion, step abandonment for every step. The metrics inform every other improvement. + +Common drop-off patterns. + +- First-step drop-off. User landed on the wizard, looked at it, left. Often signals the wizard's value proposition is not clear or the audience expected no wizard. +- Mid-wizard drop-off. User abandoned mid-process. Audit the specific step; field count, sensitive info, unclear progress. +- Skip-everything drop-off. User skipped every available step. Either the wizard is not earning its time or the skip is too prominent. + +Remediation patterns. + +- First-step drop-off: clarify the wizard's purpose; reduce upfront fields; consider whether the wizard is needed at all. +- Mid-wizard drop-off: audit the high-drop step; reduce friction; reconsider whether that step belongs in the wizard. +- Skip-everything drop-off: rebalance skip prominence; consider whether the wizard should be replaced with contextual prompts. + +The instrumentation requirement. Without per-step tracking, drop-off remediation is guesswork. Set up tracking before launch. + +Detail in [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md). + +--- + +## Wizard variations by user type + +Different users may need different wizards. + +The admin vs end-user distinction. Admins set up the workspace; end-users start using it. Wizards aimed at both fail both. Differentiated wizards serve each. + +The technical vs non-technical distinction. Technical users skip explanations; non-technical users need them. The wizard's tone and depth should match. + +The size-of-team distinction. Solo founders have different setup needs than 50-person teams. Wizards may branch. + +Differentiation patterns. + +- Role-based branching. First step asks role; subsequent steps adapt. +- Use-case-based branching. First step asks use case; wizard tailors. +- Size-based branching. Solo, team, enterprise paths differ. + +The over-differentiated trap. Too many variants produce unmaintainable wizards. Most wizards work with 2-3 variants at most. + +Detail in [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md). + +- "Activation rate is low; completion rate is high." Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. +- "Skip rate is over 50 percent." Either the wizard is not earning its time or skip is too prominent. Audit both. +- "Users complete the wizard then abandon the product within 24 hours." Time-to-value too long; ah-ha moment not in first session. +- "Wizard works for new users; existing users hit broken steps." Wizard not maintained alongside product; deprecated features still in flow. +- "Different segments complete at very different rates." Audience-fit varies; consider role-based or use-case-based branching. +- "Mobile completion is half of desktop." Mobile UX of the wizard broken. +- "We added more onboarding steps; activation went down." Tutorial-overload pattern; more is not better. +- "Skip mechanics work but users do not return to complete setup." Skip-and-defer not working; in-product prompts to return are missing or ignored. +- "Wizard analytics broke after the last release." Instrumentation drift; track and refresh. + +--- + +## The framework: 12 considerations for onboarding wizard design + +When designing or auditing an onboarding wizard, walk these 12 considerations. + +1. The wizard decision. Is a wizard the right tool, or do contextual prompts suffice? +2. Earned-progressive-disclosure, not tutorial-overload or skip-friendly-empty. Each step earns one step closer to value. +3. Step architecture sound. Each step moves the user closer to value; non-contributing steps cut. +4. The ah-ha moment engineered. Single visible value moment, action-tied, in the first session. +5. Progressive disclosure applied. Show only what is needed now; defer the rest. +6. Skip mechanics honest. Skip exists but does not produce an empty product. +7. Resume mechanics work. Skipped users have a path back; instrumented for follow-through. +8. Drop-off measurement instrumented. Per-step tracking from launch. +9. User-type variations balanced. 2-3 variants max; over-differentiation avoided. +10. Mobile parity. Wizard works on the devices the audience uses. +11. Activation as success metric. Not just completion rate; the metric is post-wizard product engagement. +12. Maintenance discipline. Wizard updated alongside product changes; quarterly audit. + +The output of the framework is an onboarding wizard that gets users to the ah-ha moment, respects their time, and produces activation rates the team can defend. + +--- + +## Reference files + +- [`references/wizard-decision-criteria.md`](references/wizard-decision-criteria.md) - When wizards earn the build vs when contextual help suffices. +- [`references/step-architecture-patterns.md`](references/step-architecture-patterns.md) - What belongs in each step. Sequence logic. Step coherence test. +- [`references/ah-ha-moment-engineering.md`](references/ah-ha-moment-engineering.md) - Identifying the ah-ha moment; designing the wizard to converge on it. +- [`references/progressive-disclosure-patterns.md`](references/progressive-disclosure-patterns.md) - Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. +- [`references/skip-and-resume-mechanics.md`](references/skip-and-resume-mechanics.md) - Skip patterns and resume patterns. The skip-friendly-empty failure. +- [`references/drop-off-measurement-templates.md`](references/drop-off-measurement-templates.md) - Per-step instrumentation. Common drop-off patterns and remediation. +- [`references/user-type-variation-patterns.md`](references/user-type-variation-patterns.md) - Admin vs end-user, technical vs non-technical, size-based branching. +- [`references/wizard-anti-patterns.md`](references/wizard-anti-patterns.md) - The patterns that look like onboarding but degrade activation. +- [`references/common-onboarding-failures.md`](references/common-onboarding-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: wizards earn the user's first session + +The onboarding wizards that work as compounding assets are the ones that get the user to value within their first session. Not because the wizard had every feature explained. Not because the wizard was skipped quickly. Because the wizard engineered the ah-ha moment, respected the user's time, and surfaced the right thing at the right moment. + +That is the bar. Below the bar are tutorial-overload (everything upfront, nobody completes) and skip-friendly-empty (skip too prominent, nobody activates). Above the bar are earned-progressive-disclosure wizards where each step earns the user one step closer to value, skip is honest about consequences, and the activation metric reflects the wizard's actual job. + +The discipline is in the design choices. The decision to build a wizard at all, or defer to contextual help. The step architecture that converges on the ah-ha moment. The progressive disclosure that surfaces the right thing at the right moment. The skip mechanics that protect the user from an empty product. The drop-off instrumentation that informs ongoing improvement. The maintenance cadence that keeps the wizard in sync with the product it represents. + +When in doubt, ask: did the user reach the ah-ha moment in their first session, and did the wizard help or hinder that? If yes to the first and helped on the second, the wizard earned its build. If no to either, redesign. diff --git a/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md b/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md new file mode 100644 index 0000000..0ca8f3e --- /dev/null +++ b/skills/onboarding-wizard-design/references/ah-ha-moment-engineering.md @@ -0,0 +1,167 @@ +# Ah-ha moment engineering + +Identifying the ah-ha moment; designing the wizard to converge on it. The single visible moment when the user feels "oh, this is what the product does for me." + +The wizard's job is not completion. It is engineering the ah-ha moment within the user's first session. Without an identifiable ah-ha moment, the wizard has nothing to engineer toward; the result is a sequence that completes without producing activation. + +--- + +## The ah-ha principle + +The ah-ha moment is action-tied, single-shot, and visible. The user did something and saw the value the product promised. The wizard's structure should make that moment likely within the first session. + +The win. A new user finishes the wizard and immediately sees their first dashboard with their actual data, with a number that surprises them in a useful way. They get it. + +The fail. The user finishes the wizard with a tour of features but never sees the product produce something specifically for them. They completed the wizard; they did not activate. + +--- + +## Identifying the ah-ha moment + +The hardest design step is also the most upstream. + +Methods. + +- Customer research. Interview activated users (those who returned and engaged) about the moment they felt the product clicked. Patterns emerge. +- Usage analysis. Compare cohorts that activated vs cohorts that churned. What action did the activated cohort take that the churned cohort did not? +- Sales-call mining. Sales conversations often surface the moment prospects say "now I get it." That moment, in-product, is the ah-ha moment. + +Signals of a real ah-ha moment. + +- It is action-tied (the user did something), not knowledge-tied (the user learned something). +- It is single-shot (one specific moment), not a checklist of moments. +- It is visible (the user saw the result), not internal (the user felt understanding). +- It is honest (the user got real value), not contrived (a demo with fake data). + +If the team cannot articulate the ah-ha moment, that is the design problem to solve before building the wizard. + +--- + +## Common ah-ha moment patterns + +By product type. + +Analytics products. First successful query against the user's actual data. Not a demo dataset; their data, their result. + +Collaboration products. First meaningful interaction with a teammate. A shared comment, a delegated task, a thread that produces a decision. + +Content products. First saved item the user returns to. The content was useful enough to revisit. + +Tooling products. First completed task that would have taken longer without the tool. The time savings is visible. + +Marketplace products. First successful match. Buyer found a seller; seller got a lead. + +Configurator products. First saved configuration. The user committed to a setup they want to see again. + +The ah-ha moment varies by product. The discipline (action-tied, single-shot, visible, honest) holds. + +--- + +## Designing the wizard around the ah-ha moment + +The wizard's path should converge on the moment. + +Step 1: identify the prerequisites. What does the user need before the ah-ha moment can happen? Connect data, invite teammate, configure workspace. Those steps are mandatory. + +Step 2: identify the path. What sequence of actions leads to the moment? The wizard's steps mirror that sequence. + +Step 3: identify the friction. What can break the path? Missing inputs, ambiguous decisions, validation errors. The wizard should pre-empt or smooth those. + +Step 4: place the ah-ha moment intentionally. The moment should appear at step 3-5 of the wizard, not after a 10-step setup. Earlier is better; aim for the user's first session, ideally first 5-10 minutes. + +--- + +## Time-to-value as design constraint + +The shorter the time to ah-ha, the higher the activation rate. + +The benchmark. First session ah-ha moment correlates with strong activation. Multi-session ah-ha (user has to come back) correlates with moderate activation. Multi-day ah-ha (user has to wait or work for it) correlates with poor activation. + +The design implication. If the ah-ha moment naturally takes hours or days (e.g., AI training, audit results), the wizard needs an interim ah-ha, something visible the user can see in their first session that signals the eventual ah-ha is coming. + +Examples. + +- AI product where training takes 24 hours: interim ah-ha is "see how your data looks; we will message you when training is done." +- Audit product where results take 48 hours: interim ah-ha is "see what we are auditing; preview a partial result." + +The user's first session should produce something visible and meaningful, even if the full ah-ha comes later. + +--- + +## The ah-ha moment for different audiences + +Different users may need different moments. + +Admin vs end-user. The admin's ah-ha moment may be configuration-related ("the workspace is set up, the team can use it"). The end-user's ah-ha moment is in-product engagement ("I did the thing I came to do"). Wizards may differentiate. + +Technical vs non-technical. Technical users often want depth (see the API work, see the integration succeed). Non-technical users want outcome (see the result, no API). Different ah-ha moments. + +Solo vs team. Solo users often want individual productivity. Team users want collaboration moments. The wizard's path may differ. + +The discipline. Identify the ah-ha moment per relevant audience segment. Wizards may branch based on segment. + +--- + +## Anti-patterns in ah-ha moment design + +Tutorial-as-ah-ha. Treating "learned about the features" as activation. The user knows what the product does but has not seen it do something specifically for them. Knowledge-tied, not action-tied; not real activation. + +Demo-as-ah-ha. Showing a polished demo that does not use the user's data. The user sees what is possible but not what is true for them. Contrived; activation does not stick. + +Multi-moment ah-ha. Treating "see all features" as the moment. No single moment lands; the user feels they need to see everything before getting it. + +Delayed ah-ha. The ah-ha moment lands two sessions in. The user does not return for the second session. + +Theoretical ah-ha. "When users connect their data and run their first analysis, they will love it." Belief without evidence. Without research validating the moment, the wizard is built on theory. + +--- + +## Measuring ah-ha moment effectiveness + +Activation rate is the metric. Completion rate is leading indicator at best. + +Activation as the metric. Define activation explicitly (e.g., user returned within 7 days and engaged with feature X). Track it. + +Wizard completion as leading indicator. Useful but insufficient. A high completion rate with low activation rate signals the wizard's ah-ha moment is wrong. + +Time-to-activation. Hours from signup to activation. Shorter correlates with retention. + +Per-segment activation. Different segments may have different activation rates. Surfaces audience-fit issues. + +--- + +## Validating the ah-ha moment + +Once defined, validate. + +Cohort analysis. Compare cohorts that hit the moment vs cohorts that did not. Did hitting it correlate with retention? If not, the moment is wrong. + +User research. Interview users who hit the moment. Did they recognize it as the ah-ha moment, or just another step? + +A/B testing. Test wizard variations that converge on the moment vs variations that do not. Activation rate difference quantifies the moment's value. + +The discipline. The ah-ha moment is a hypothesis until validated. Treat it as such. + +--- + +## Common ah-ha moment failures + +No defined moment. Wizard built without identifying the moment; result is decorative. + +Wrong moment defined. Moment defined based on intuition; cohort analysis shows it does not predict retention. + +Moment too late. Moment lands after multiple sessions; users do not return. + +Moment requires too much work. Moment is real but the user has to do significant setup; drop-off before the moment. + +Moment varies wildly by segment. Single-moment design fails for an audience with different needs. + +--- + +## Methodology-level choices that stay in the public skill + +The ah-ha principle. Methods for identifying the moment. Common patterns by product type. Designing the wizard around the moment. Time-to-value as design constraint. Audience-specific moments. Anti-patterns. Measurement. Validation. Common failures. + +## Implementation choices that stay internal + +Specific ah-ha moments for specific products. Specific cohort definitions. Specific research methodologies. The team's research capacity. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/common-onboarding-failures.md b/skills/onboarding-wizard-design/references/common-onboarding-failures.md new file mode 100644 index 0000000..63b23a1 --- /dev/null +++ b/skills/onboarding-wizard-design/references/common-onboarding-failures.md @@ -0,0 +1,171 @@ +# Common onboarding failures + +9+ failure patterns with diagnoses and cures. The patterns that surface as "activation is low" or "users skip the wizard" or "we cannot tell if the wizard works." + +--- + +## "Activation rate is low; completion rate is high." + +The diagnosis. Wizard completed but did not engineer the ah-ha moment. Audit what users did after completing. + +The cure. Redesign around the ah-ha moment (`references/ah-ha-moment-engineering.md`). Define activation explicitly; verify the wizard produces it; cut steps that do not contribute. + +--- + +## "Skip rate is over 50 percent." + +The diagnosis. Either the wizard is not earning its time or skip is too prominent. Audit both. + +The cure. Audit step value (each step contribute to ah-ha?). Audit skip prominence (skip too easy?). Detail in `references/step-architecture-patterns.md` and `references/skip-and-resume-mechanics.md`. + +--- + +## "Users complete the wizard then abandon the product within 24 hours." + +The diagnosis. Time-to-value too long; ah-ha moment not in first session. + +The cure. Move the ah-ha moment earlier. If the moment naturally takes longer, design an interim ah-ha for the first session. + +--- + +## "Wizard works for new users; existing users hit broken steps." + +The diagnosis. Wizard not maintained alongside product; deprecated features still in flow. + +The cure. Maintenance discipline. Quarterly audit. Product changes trigger wizard updates as part of the change. + +--- + +## "Different segments complete at very different rates." + +The diagnosis. Audience-fit varies; consider role-based or use-case-based branching. + +The cure. Differentiate by segment where the differentiation produces materially different paths. Detail in `references/user-type-variation-patterns.md`. + +--- + +## "Mobile completion is half of desktop." + +The diagnosis. Mobile UX broken or compromised. + +The cure. Mobile-first design and testing. Test on actual devices. + +--- + +## "We added more onboarding steps; activation went down." + +The diagnosis. Tutorial-overload pattern; more is not better. + +The cure. Cut steps that do not contribute to the ah-ha moment. Defer feature explanations to in-product tours. + +--- + +## "Skip mechanics work but users do not return to complete setup." + +The diagnosis. Skip-and-defer not working; in-product prompts to return are missing or ignored. + +The cure. Audit prompt logic. Ensure prompts trigger at moments of relevance, with frequency limits, and route to the right setup flow. + +--- + +## "Wizard analytics broke after the last release." + +The diagnosis. Instrumentation drift; track and refresh. + +The cure. Verify analytics after every release. Add a smoke test to the deployment process. + +--- + +## "We A/B tested wizard length; conversion did not change." + +The diagnosis. Length alone may not be the issue. Could be step content, skip prominence, or the underlying ah-ha definition. + +The cure. Test variables that matter (skip prominence, ah-ha placement, step coherence). Length is one variable; isolate the right one. + +--- + +## "Activation looks good; retention is poor." + +The diagnosis. Activation metric may be wrong. Users hit a moment that does not predict retention. + +The cure. Validate the ah-ha moment with cohort analysis. Did users who hit it actually retain? If not, the moment is wrong. + +--- + +## "We cannot tell which step needs work." + +The diagnosis. Aggregate completion tracked but not per-step. + +The cure. Per-step instrumentation (`references/drop-off-measurement-templates.md`). + +--- + +## "Wizard worked great at launch; activation has declined." + +The diagnosis. Decay. Audience shifted; product evolved; references stale. + +The cure. Quarterly audit. Update what has decayed. + +--- + +## "Sales says the leads from signup are different than they used to be." + +The diagnosis. Audience composition shifted; the wizard's segmentation may be obsolete. + +The cure. Update branching or differentiation. Audit the audiences arriving and what they need. + +--- + +## "We built a wizard; the team thinks the bot would have been better." + +The diagnosis. Possibly. Different products warrant different activation tools. + +The cure. Validate. If the bot would serve better, test or migrate. The wizard format is not always the right tool. + +--- + +## "Power users complete the wizard then abandon." + +The diagnosis. Wizard does not respect power users' speed. They want to skip ahead. + +The cure. Add power-user paths. Skip should be available; advanced configuration should be findable post-wizard. + +--- + +## "We localized the wizard; activation in some locales dropped." + +The diagnosis. Translation quality, cultural mismatch, or audience-fit specific to the locale. + +The cure. Audit translation. Audit cultural assumptions. Verify audience-fit per locale. + +--- + +## "The wizard works on Chrome; it crashes on Safari mobile." + +The diagnosis. Browser/device-specific bugs. + +The cure. Cross-browser, cross-device testing. + +--- + +## The pattern across failures + +Most onboarding wizard failures fall into one of three patterns. + +Pattern 1: The wizard does not engineer the ah-ha moment. Tutorial-overload, decoration steps, demo-as-ah-ha, late ah-ha. The fix is to redefine and converge on the moment. + +Pattern 2: The wizard does not match the audience. Skip-friendly-empty, validation-strict, mobile-broken, segment mismatch. The fix is matching the wizard to where the audience actually is. + +Pattern 3: The wizard decays. Stale references, broken steps, analytics drift. The fix is maintenance discipline. + +The metric pattern: wizard failures often look fine on completion alone. The signal is in activation, retention, drop-off per step. Programs that track only completion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (ah-ha, audience-fit, decay). The principle that completion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md b/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md new file mode 100644 index 0000000..6012f5a --- /dev/null +++ b/skills/onboarding-wizard-design/references/drop-off-measurement-templates.md @@ -0,0 +1,230 @@ +# Drop-off measurement templates + +Per-step instrumentation. Common drop-off patterns and remediation. Without per-step tracking, drop-off remediation is guesswork. + +The metrics inform every other improvement. Set up tracking before the wizard launches. + +--- + +## The instrumentation requirement + +Track step start, step completion, step abandonment for every step. + +Minimum tracking. + +- Wizard start (user landed on step 1). +- Step start (user reached step N). +- Step completion (user finished step N, advanced to step N+1). +- Step abandonment (user left without completing). +- Wizard completion (user finished all steps, reached end). +- Skip events (per step where applicable). + +Derived metrics. + +- Step completion rate (users who reached step / users who completed it). +- Step skip rate (users who reached step / users who skipped). +- Funnel completion rate (started wizard / finished). +- Time per step. + +Without this data, every diagnostic is theoretical. + +--- + +## Common drop-off points + +Three patterns recur across onboarding wizards. + +First-step drop-off. User landed on the wizard, looked at it, left. + +Common causes. +- Wizard length visible upfront and intimidating. +- Value proposition unclear. +- Audience expected no wizard. +- Mobile UX broken. + +Mid-wizard drop-off. User abandoned mid-process. + +Common causes. +- Specific step too demanding (high field count, sensitive question, ambiguous input). +- Cumulative fatigue (wizard too long). +- Friction at validation or backend processing. +- Time pressure (user expected faster). + +Late-step drop-off. User completed most steps but abandoned near the end. + +Common causes. +- Final step requires information the user does not have. +- Wizard length felt longer than expected. +- Submission anxiety (user does not know what happens after). + +--- + +## Remediation patterns + +For each drop-off pattern. + +First-step drop-off. + +- Reduce visible upfront length (defer to multi-screen or progressive disclosure). +- Clarify value ("This 5-step setup connects your data and shows your first insight"). +- Reduce step-1 cognitive load (start with the easiest step). +- Test mobile experience. + +Mid-wizard drop-off. + +- Audit the high-drop step. Is it too demanding? Sensitive? Ambiguous? +- Reduce field count or split into multiple smaller steps. +- Add progress indicator if missing. +- Add reassurance copy if the step is sensitive. +- Reword ambiguous fields. + +Late-step drop-off. + +- Reduce final-step requirements (move some fields earlier). +- Add post-submission preview ("After this, we'll set up your dashboard"). +- Add explicit confirmation step before submission. + +--- + +## Drop-off and skip distinction + +Skip is intentional; drop-off is involuntary. Track them separately. + +Skip metrics. + +- Skip rate per step (users who reached step / users who skipped). +- Resume rate per skip (users who skipped step / users who returned to complete). +- Activation rate per skip (users who skipped specific steps and still activated). + +Drop-off metrics. + +- Abandonment rate per step (users who reached step / users who left without completing or skipping). +- Time-to-abandonment. +- Re-engagement rate (users who came back to retry the wizard). + +The diagnostic value. Skip suggests the user does not value this step right now. Drop-off suggests the wizard failed to engage the user. + +--- + +## Tracking conditional paths + +Wizards with branching logic have multiple paths. + +Per-path tracking. + +- Tag each user's path through the wizard. +- Measure completion rate per path. +- Identify paths that drop off disproportionately. + +Path-specific remediation. A path that drops off at step 4 may need step-4 redesign for users on that path. Other paths may not need attention. + +--- + +## Drop-off and audience segmentation + +Different audiences may drop off at different points. + +Segment-level tracking. + +- Tag users by source, device, role, or other relevant segment. +- Measure drop-off per segment. +- Identify segment-specific issues. + +Common segment patterns. + +- Mobile users drop off more on long steps. +- Paid-traffic users drop off earlier than organic. +- New users drop off more than returning visitors. + +Remediation by segment. Sometimes the right answer is segment-specific (e.g., shorter wizard variant for mobile). + +--- + +## Time-to-completion tracking + +How long the wizard takes. + +Total time distribution. Plot the time-to-complete distribution. Median, p25, p75, p95. + +Per-step time. Which steps take longest? Are they earning the time? + +Patterns. + +- Wizards taking more than 10 minutes typically see significant drop-off. +- Steps taking more than 2 minutes typically see step-level drop-off. +- Long-tail completers (p95) often signal usability issues. + +Remediation by time. Wizards or steps taking too long should be split or simplified. + +--- + +## A/B testing wizards + +Test changes rigorously. + +Test design. Hypothesize the cause of drop-off; design a treatment; A/B test treatment vs control; measure both step-level drop-off and overall activation. + +Common test types. + +- Wizard length (shorter vs longer). +- Step ordering (different sequences). +- Field count per step. +- Skip prominence. +- Help text presence/absence. +- Default-heavy vs required-now-optional-later. + +Test discipline. One variable at a time. Long enough to capture activation signal. Measure both wizard metrics and downstream activation. + +--- + +## When drop-off is signal, not failure + +Some drop-off is healthy. + +The signal. Wrong audience self-selecting out. A wizard that filters out audiences who would not activate anyway is doing its job. + +The discipline. Distinguish drop-off from unfit audience (good) from drop-off from fit audience (bad). The downstream activation metric reveals which. + +The decision. Optimize for completed-by-fit-audience, not for raw completion rate. + +--- + +## Wizard analytics dashboard + +What to surface. + +Per-step funnel. Start rate, completion rate, drop-off rate per step. + +Skip rates per step. Where skip is enabled. + +Time-to-completion distribution. With percentile breakdown. + +Activation rate per cohort. Wizard completers vs non-completers; activation by skip pattern. + +Trend over time. Have the metrics changed since the last release? + +--- + +## Common analytics failures + +No instrumentation. Wizard launched without tracking; quality is invisible. + +Aggregate-only tracking. Wizard completion tracked but not per-step; remediation requires guesswork. + +Instrumentation drift. Tracking implemented at launch; field renames or step changes broke the tracking. + +Skip and drop-off conflated. Cannot distinguish intentional skip from involuntary drop-off. + +Activation not tracked. Wizard metrics in isolation; cannot tell if completion correlates with activation. + +No segment-level data. Aggregate hides segment-specific issues. + +--- + +## Methodology-level choices that stay in the public skill + +The instrumentation requirement. Common drop-off points and causes. Remediation patterns. Drop-off vs skip distinction. Tracking conditional paths. Per-segment analytics. Time-to-completion. A/B testing. When drop-off is signal. Dashboard composition. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for specific wizards. Specific tooling. Specific A/B test designs. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md b/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md new file mode 100644 index 0000000..8b831d9 --- /dev/null +++ b/skills/onboarding-wizard-design/references/progressive-disclosure-patterns.md @@ -0,0 +1,238 @@ +# Progressive disclosure patterns + +Default-heavy, required-now-optional-later, expand-on-demand, branching patterns. How to surface only what is needed at each step. + +The principle. Show only the inputs, options, and information the user needs to complete the current step. Defer everything else to in-product help or later configuration. + +Wizards that try to show everything become tutorial-overload. Wizards that defer everything become skip-friendly-empty. Progressive disclosure is the discipline that surfaces what matters when it matters. + +--- + +## Pattern A: Default-heavy + +Each step has smart defaults; the user can accept or override. + +How it works. + +- Inputs come pre-filled with sensible defaults. +- The user reviews; accepts most; overrides where their context differs. +- Most users move through quickly; advanced users find the override controls. + +Strengths. + +- Reduces cognitive load. +- Faster completion. +- Users without strong preferences proceed; users with strong preferences customize. + +Weaknesses. + +- Defaults must be honest. Bias-flattering defaults erode trust. +- Defaults need maintenance as the product evolves. + +When to use. Default for most wizards. Smart defaults reduce friction without removing customization. + +--- + +## Pattern B: Required-now, optional-later + +Required fields surface in the wizard; optional configuration surfaces in-product after activation. + +How it works. + +- Each step has only required fields. +- Optional configuration appears as in-product prompts after the wizard. +- The wizard stays focused on minimum-viable activation. + +Strengths. + +- Shortest possible wizard. +- Optional configuration happens when the user has product context. +- Activation rate improves; configuration completeness rises. + +Weaknesses. + +- Requires in-product prompt infrastructure for the deferred configuration. +- Some users may never return to complete deferred setup. + +When to use. When the wizard has accumulated optional fields that bloat completion time. The strongest pattern for trimming bloated wizards. + +--- + +## Pattern C: Expand-on-demand + +Sections collapsed by default; the user expands if interested. + +How it works. + +- Step shows the minimal interface. +- An "advanced options" or "more details" toggle expands additional fields. +- Most users skip; advanced users explore. + +Strengths. + +- Surfaces depth without forcing it. +- Power users get what they need. + +Weaknesses. + +- Risk of hiding important fields the user does not realize they need. +- Adds visual complexity to the step. + +When to use. When some users genuinely need depth that most do not. Use sparingly; default-heavy plus required-now-optional-later usually serves better. + +--- + +## Pattern D: Branching + +Different users see different steps based on earlier answers. + +How it works. + +- Step 1 asks about role, use case, or context. +- Subsequent steps adapt based on the answer. +- Different users effectively complete different wizards. + +Strengths. + +- Each user sees only steps that apply to them. +- Wizard feels personalized. + +Weaknesses. + +- Significant maintenance complexity. +- Testing burden grows (more paths). +- Analytics must accommodate variable paths. + +When to use. When the audience genuinely splits into segments with materially different needs. 2-3 branches max; more becomes unmaintainable. + +--- + +## Pattern E: Hybrid + +Combining patterns. Default-heavy plus required-now-optional-later plus a single branch for major audience split. + +Strengths. + +- Reduces friction at multiple levels. +- Different users benefit from different mechanisms. + +Weaknesses. + +- Design and maintenance complexity. + +When to use. When the wizard's audience and content warrant the combination. Most production wizards land in some hybrid configuration. + +--- + +## What to surface vs defer + +The decision per field. + +Surface in the wizard. + +- Fields without which the product cannot work for the user. +- Fields that affect the ah-ha moment. +- Fields that branch downstream steps. +- Fields that personalize the immediate experience. + +Defer to in-product. + +- Fields that affect long-term configuration but not immediate value. +- Fields that benefit from product context (the user understands what they are configuring). +- Fields that are commonly skipped anyway; surface them at moments of relevance. + +The deferable test. For each wizard field, ask: would the user be better served setting this up after seeing the product, with relevant context? If yes, defer. + +--- + +## Default discipline + +Defaults are powerful. They must be honest. + +Honest defaults. + +- Defaults reflect the typical case for the audience. +- Defaults are sourced (from cohort data, common practice, or team judgment). +- Defaults can be overridden visibly. + +Bias-flattering defaults. + +- Defaults set to produce favorable signup metrics (cheap plan pre-selected, opt-in checked) without disclosure. +- Defaults that misrepresent the user's real choice. +- Defaults that change over time without user notice. + +The discipline. Defaults reduce friction; they should not extract data or commitment the user did not consent to. + +--- + +## Information density per step + +How much to show. + +Minimal density. Just the required fields plus a sentence of context. Shortest, fastest. + +Moderate density. Required fields plus brief explanation plus optional toggle. Balanced. + +Heavy density. Multiple sections, expandables, detailed help text. Most cognitive load. + +The right density depends on the audience and the step's complexity. Default to minimal; add density only when the step's complexity warrants it. + +--- + +## Help text discipline + +When to include explanatory text. + +Strong help patterns. + +- Inline tooltip on non-obvious fields. +- One-sentence explanation per step ("we use this to tailor your dashboard"). +- Examples for fields where the format is ambiguous. + +Weak help patterns. + +- Long help text on every field. +- Help text that is marketing rather than explanation. +- Help text that explains things the user already knows. + +The discipline. Help text earns its inclusion when it reduces friction. Help text for the sake of completeness adds clutter. + +--- + +## Mobile considerations + +Progressive disclosure on mobile. + +Mobile-first defaults. Default values matter more on mobile because typing is harder. + +Single question per screen. Mobile screens are small; multi-field steps cramp. + +Touch-friendly toggles. Expand/collapse must be touch-targetable. + +Minimal help text. Mobile users skim; long help text is dismissed. + +--- + +## Common progressive disclosure failures + +No defaults. Every field blank; the user does work the wizard could have done. + +Bias-flattering defaults. Defaults extract commitment the user did not consent to. + +Over-disclosed. Every field surfaced; tutorial-overload. + +Under-disclosed. Important fields hidden; the user finishes the wizard with a misconfigured product. + +Branching without need. Branches that do not produce materially different paths add complexity without benefit. + +Help text bloat. Every field has a paragraph of explanation; cognitive load climbs. + +--- + +## Methodology-level choices that stay in the public skill + +The five patterns (default-heavy, required-now-optional-later, expand-on-demand, branching, hybrid). Strengths, weaknesses, when-to-use guidance. What to surface vs defer. Default discipline. Information density. Help text discipline. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific wizards. Specific help copy in brand voice. Specific tooling for progressive disclosure. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md b/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md new file mode 100644 index 0000000..b41edba --- /dev/null +++ b/skills/onboarding-wizard-design/references/skip-and-resume-mechanics.md @@ -0,0 +1,205 @@ +# Skip and resume mechanics + +Skip patterns and resume patterns. The skip-friendly-empty failure. Honest skip, honest resume. + +When users skip, where they land. When they resume, what they see. Skip mechanics done well let users escape without abandoning; done poorly, they produce skip-friendly-empty wizards where users skip into a useless product and churn. + +--- + +## The skip principle + +Skip should never produce an empty product. If skipping is offered, the user must land in a state where they can still progress; the wizard's deferred steps must be retrievable. + +The win. A user clicks "Skip for now" on a setup step. The product places them in a partially-configured state with a clear callout: "Your workspace needs a connected data source to show insights. Set it up here when you're ready." The user understands; engages later. + +The fail (skip-friendly-empty). A user clicks "Skip" on every step. The product places them in an empty state with no context; the user does not know what to do; they leave and never return. + +The discipline. Skip exists, but skip is consequence-honest and recoverable. + +--- + +## Skip patterns + +Common patterns for offering skip. + +Pattern A: Soft skip with context. + +How it works. The skip option is available but explains what gets deferred. "Skip for now; we will remind you to connect your data source later." + +When to use. Most wizards. Honest about the consequence; provides a path back. + +Pattern B: Skip-and-defer. + +How it works. Skipped steps are queued for later in-product prompts. The wizard does not require completion; the prompts handle re-engagement. + +When to use. When the wizard would otherwise be too long; defer everything that can be deferred. + +Pattern C: Skip-with-warning. + +How it works. Skipping triggers an honest warning. "Skipping setup means you won't see [X] until you complete it. Continue?" + +When to use. When skipping has real consequences the user should know about. Use sparingly; warnings on every step desensitize. + +Pattern D: No skip. + +How it works. The step must be completed. No skip option. + +When to use. For wizards that absolutely require completion (compliance forms, paid signups, regulatory required steps). Use sparingly; users who cannot skip and cannot complete leave instead. + +--- + +## Skip prominence + +How visible the skip option is. + +Equal prominence. Skip and continue have similar visual weight. Honest about both options. Most common. + +Continue-prominent. Continue is the visual primary; skip is a secondary link. Encourages completion without forbidding skip. + +Skip-prominent. Skip is more visible than continue. Almost never the right choice; produces skip-friendly-empty. + +Hidden skip. Skip exists but is hidden behind a "more options" toggle. Discouraged; users cannot find escape if they need it. + +The discipline. Continue-prominent for important steps; equal prominence for most steps; never skip-prominent. + +--- + +## Skip-friendly-empty: the failure mode + +The pattern where skip is too prominent and consequence-free. + +The pattern. Every step has a "Skip" button as prominent as "Continue." Skip is consequence-free; users skip every step. + +The result. Users land in an empty product; they have no context; they leave. + +The cost. Activation rate falls off a cliff. The wizard's design effort produces an experience nobody actually completes. + +The cure. Rebalance skip prominence. Make consequences visible. Add resume mechanics so skipped steps can be completed later. + +--- + +## Resume patterns + +Where users land when they return. + +Auto-resume on next login. + +How it works. The user returns; the wizard automatically lands at the step they left. + +When to use. When wizard completion is genuinely required for product use. + +Manual resume from in-product entry. + +How it works. A persistent "Complete setup" surface in-product returns the user to the wizard. + +When to use. When the wizard is recommended but not required; users can engage with the product partially. + +Soft resume. + +How it works. The wizard fades out as the user completes equivalent actions in-product naturally. No explicit re-entry needed. + +When to use. When the in-product experience surfaces equivalent prompts; the wizard becomes redundant. + +No resume. + +How it works. Skipped steps are skipped permanently; the wizard runs once. + +When to use. Rarely. Most wizards benefit from some resume mechanism. + +--- + +## Skip-and-defer in-product prompt design + +The prompts that bring users back. + +Trigger logic. Prompts trigger based on user behavior, time elapsed, or context. "You have not connected a data source yet; here is how" appears when the user attempts to use a feature requiring data. + +Frequency limits. Prompts should not nag. One reminder per session is often enough; some prompts should appear once and dismiss permanently. + +Dismiss mechanics. "Don't show this again" is honest. Hidden dismiss options are hostile. + +Completion routing. When the user accepts the prompt, route to the right setup flow (often shorter than the original wizard step). + +--- + +## Skip mechanics by step type + +Different steps warrant different skip treatment. + +Critical setup steps (without which the product cannot work). Skip should be possible but consequence-warned. Resume mechanics aggressive. + +Optional configuration steps. Skip easy and consequence-free; resume mechanics gentle. + +Identity/personalization steps. Skip easy; the product can default; resume not necessary. + +Marketing/data-collection steps. Skip easy; the product does not need this; resume rarely warranted (skip is a clean signal of opt-out). + +The discipline. Skip prominence and resume aggressiveness should match the step's importance. + +--- + +## Resume measurement + +Track resume effectiveness. + +Skip rate per step. What percentage of users skip each step? + +Resume rate per step. What percentage of users who skipped a step later return to complete it? + +Activation rate per skip pattern. Do users who skipped step X activate at lower rates? + +Diagnostic uses. + +- High skip + low resume: wizard losing users who never come back. Audit consequences. +- High skip + high resume: skip-and-defer working. The wizard is producing graceful escapes. +- Low skip overall: wizard is engaging users; check completion and activation as next metrics. + +--- + +## Resume copy discipline + +What the resume prompt says. + +Helpful resume copy. + +- "Connect your data source to see insights. It takes 2 minutes." +- "You skipped inviting teammates earlier. Want to do that now?" +- "Almost done. Two steps left to finish setup." + +Unhelpful resume copy. + +- "You did not finish onboarding." +- "Complete setup." +- "You missed steps." + +The voice discipline. Resume copy should be helpful, not scolding. The user did not fail; they deferred. + +--- + +## Common skip-and-resume failures + +Skip too prominent. Users skip everything; activation collapses. + +No skip option. Users who need to escape leave entirely. + +Hidden skip. Users cannot find escape; frustration builds; they leave. + +No resume mechanism. Skipped users never return to complete; configuration stays incomplete. + +Aggressive resume prompts. Prompts every session; users dismiss permanently. + +Resume routes to wrong place. User accepts prompt; lands in unrelated flow. + +Resume copy scolds. User feels punished for skipping; trust degrades. + +Skip without consequence-disclosure. Users skip not knowing what they will miss; abandon when they discover. + +--- + +## Methodology-level choices that stay in the public skill + +The skip principle. Skip patterns (4 patterns). Skip prominence guidance. The skip-friendly-empty failure. Resume patterns (4 patterns). Skip-and-defer prompt design. Skip mechanics by step type. Resume measurement. Resume copy discipline. Common failures. + +## Implementation choices that stay internal + +Specific skip and resume implementations for specific wizards. Specific prompt copy in brand voice. Specific tooling for resume infrastructure. The team's resume measurement baselines. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/step-architecture-patterns.md b/skills/onboarding-wizard-design/references/step-architecture-patterns.md new file mode 100644 index 0000000..b610daf --- /dev/null +++ b/skills/onboarding-wizard-design/references/step-architecture-patterns.md @@ -0,0 +1,225 @@ +# Step architecture patterns + +What belongs in each step. Sequence logic. The step coherence test. + +The architecture is the structure that makes wizards work. Bad architecture produces decorative steps that do not move the user closer to value; good architecture converges on the ah-ha moment with discipline. + +--- + +## The convergence principle + +Each step should move the user one step closer to value. Steps that do not should be cut. + +The test. For each step, ask: did this step move the user toward the ah-ha moment? If no, cut it or defer it to in-product help. + +The discipline. Wizards accumulate steps over time as teams add "while we have them" requests (collect more data, surface more features, etc.). The discipline is to resist accumulation; the wizard's job is convergence, not feature pride. + +--- + +## Common step patterns + +Patterns that recur across product onboarding wizards. + +Welcome and orientation. + +- Purpose: set expectations for what the wizard will do. +- Skippable: usually yes, low cost. +- When to include: when the wizard's purpose is not obvious from context. +- When to skip: when the wizard's purpose is obvious; welcome adds friction without value. + +Identity and account context. + +- Purpose: capture who the user is, what brought them here. +- Required fields: minimal. Name and role are often enough. +- When to include: when subsequent steps adapt to identity. +- When to skip: when subsequent steps do not adapt; identity capture is just data collection. + +Critical setup step. + +- Purpose: the one thing the product cannot work without. +- Examples: connect data source, invite first teammate, set primary use case. +- This is often where wizards justify their existence. Without this step, the user lands in an empty product. + +First-action step. + +- Purpose: get the user to take a meaningful action that produces visible result. +- The ah-ha moment lives here or right after. +- Should be guided enough that success is likely; honest enough that the success is real. + +Configuration deferral. + +- Purpose: surface things that can be set up later but are commonly needed. +- Lets the user defer with a clear path back. +- Reduces wizard length without losing coverage. + +Confirmation and next steps. + +- Purpose: recap what was set up; surface what to do next; route to in-product home. +- Closes the wizard cleanly. +- Often skipped in design but useful for orientation. + +--- + +## Step sequencing principles + +The order matters as much as the steps themselves. + +Principle 1: Earn the patience. Open with low-friction steps; the user invests; deeper setup follows. Critical setup demanding effort works better at step 2-3 than step 1. + +Principle 2: Ah-ha moment by step 3-5. If the wizard runs longer than 5 steps before any visible value, drop-off climbs sharply. + +Principle 3: Deferable last. Steps that can be deferred should sit late in the wizard, where skip is least costly. + +Principle 4: Confirmation explicit. Close the wizard with a clear "you are done; here is what's next" step. Without it, users feel dropped. + +--- + +## Step coherence test + +For each step, can it be described in one sentence as a unit of work that contributes to the ah-ha moment? + +Coherent steps. + +- Step 1: tell us about your role so we can tailor what comes next. +- Step 2: connect your data source so we can show you something useful. +- Step 3: run your first query and see a result. +- Step 4: save the result so you can return to it. +- Step 5: optionally invite a teammate; otherwise, you are ready. + +Each step has clear purpose tied to value. + +Incoherent steps. + +- Step 1: name and email (already collected at signup; redundant). +- Step 2: tour of features (does not move toward action). +- Step 3: branding preferences (irrelevant to ah-ha moment). +- Step 4: marketing opt-in (data collection, not value). + +Steps without clear purpose should be cut or deferred. + +--- + +## Step count discipline + +How many steps is too many. + +Sweet spot. Most effective wizards run 3-7 steps. The user can predict completion time; the convergence is tight. + +Too few. 1-2 steps usually means the wizard format is overkill; contextual prompts often serve better. + +Too many. 10+ steps signals tutorial-overload. Drop-off climbs sharply; users skip when they can. + +The deferable test. For wizards exceeding 7 steps, audit each step. Which can be deferred to in-product? Often half can. + +--- + +## Field count per step + +Within each step, how many fields. + +3-5 fields per step. Sweet spot. Coherent unit; completable in 30-60 seconds. + +1-2 fields per step. Often signals over-staging. The user wonders why the field needed its own step. + +6+ fields per step. Recreates the kitchen-sink problem within a step. Audit; usually some fields can be cut or deferred. + +--- + +## Branching and conditional steps + +When wizards adapt based on earlier answers. + +The pattern. First step asks about role or use case; subsequent steps adapt. + +Strengths. The wizard feels relevant; users see only what applies to them. + +Weaknesses. Maintenance complexity; testing across paths. + +The discipline. Branch only when the variability genuinely benefits the user. Decorative branching adds cost without lift. + +--- + +## Step transitions + +How the user moves between steps. + +Forward transitions. Clear "Next" or "Continue" CTA. Validation runs before the transition. Snappy; no loading delays. + +Back transitions. "Back" or "Previous" available. Returning to earlier steps preserves answers. + +Skip transitions. Skip available but honest about consequences. Skip lands the user in a partially-set-up state with clear callouts to complete deferred setup. + +Loading state. When the wizard's step requires backend work (connecting data source, processing input), show progress. Silent loading kills momentum. + +--- + +## Step examples by product type + +How architecture varies by product. + +B2B SaaS analytics. + +- Welcome → role/use case → connect data source → first query → first saved view → invite team (deferable) → in-product home. + +7 steps; meaningful staging; ah-ha at step 5. + +Project management tool. + +- Welcome → workspace setup → first project → first task → invite team → in-product home. + +6 steps; ah-ha around step 4. + +Marketing automation. + +- Welcome → connect site → connect data source → first audience → first campaign → in-product home. + +6 steps; ah-ha at first audience visualization. + +Consumer note-taking. + +- Probably no wizard. Empty-state prompts and contextual hints serve better. + +The patterns vary. The discipline (each step earns its place; ah-ha moment by step 3-5) holds. + +--- + +## Step architecture maintenance + +Steps decay. Product changes mean wizard updates. + +Maintenance triggers. + +- Product feature added that the wizard should reference. +- Product feature deprecated that the wizard still references. +- Setup process changed; wizard steps no longer match. +- Audience composition shifted; old role-branching no longer fits. + +Maintenance cadence. Quarterly review minimum; product changes trigger updates as part of the change. + +--- + +## Common architecture failures + +Decorative steps. Steps that do not move toward value. + +Tutorial steps. Steps explaining features the user has not asked about. + +Front-loaded effort. High-friction step first; users abandon at step 1. + +Late ah-ha moment. Wizard runs 10 steps before visible value. + +Mandatory steps that should be deferable. Forces friction users would have accepted later. + +No confirmation step. User finishes the wizard, lands somewhere unclear. + +Step transitions sluggish. Loading delays kill momentum. + +--- + +## Methodology-level choices that stay in the public skill + +The convergence principle. Common step patterns. Sequencing principles. The step coherence test. Step count discipline. Field count per step. Branching considerations. Step transitions. Step examples by product type. Maintenance discipline. Common failures. + +## Implementation choices that stay internal + +Specific step architectures for specific products. Specific copy and tone. Specific tooling. Specific testing protocols. The team's audit calendar. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/user-type-variation-patterns.md b/skills/onboarding-wizard-design/references/user-type-variation-patterns.md new file mode 100644 index 0000000..d274a99 --- /dev/null +++ b/skills/onboarding-wizard-design/references/user-type-variation-patterns.md @@ -0,0 +1,199 @@ +# User type variation patterns + +Admin vs end-user, technical vs non-technical, size-based branching. When one wizard does not serve all users. + +Different users may need different wizards. The discipline is to differentiate where the audience genuinely splits, without producing unmaintainable proliferation. + +--- + +## The differentiation principle + +Differentiate where the audience genuinely splits into segments with materially different needs, language, or paths. Do not differentiate where one wizard serves all. + +The win. Admins set up the workspace; end-users start using it. A single wizard tries to serve both and fails both. Differentiated wizards serve each meaningfully. + +The fail. A team builds 5 wizard variants for 5 imagined personas. Maintenance burden compounds; the variants diverge over time; no variant is excellent. + +The discipline. Start with one wizard. Differentiate only when data shows segments with different needs and the differentiation produces meaningfully different paths. + +--- + +## Common differentiation axes + +Three axes recur. + +Admin vs end-user. + +- Admins set up the workspace, invite teammates, configure integrations. +- End-users start using what admins set up. +- Their first sessions look different; the ah-ha moments differ. + +Technical vs non-technical. + +- Technical users want depth (see the API, see the integration succeed, configure deeply). +- Non-technical users want outcome (see the result, no API). +- Tone, content, and step coverage differ. + +Size of team. + +- Solo founders configure for one. +- Small teams configure for collaboration. +- Enterprise teams have additional setup (SSO, governance, compliance). + +--- + +## Differentiation patterns + +How to implement. + +Pattern A: Role-based branching. + +How it works. First step asks role; subsequent steps adapt. + +When to use. When the role split is clear and produces different paths. + +Pattern B: Use-case-based branching. + +How it works. First step asks use case; wizard tailors to that use case. + +When to use. When the product serves multiple use cases that warrant different ah-ha moments. + +Pattern C: Size-based branching. + +How it works. First step asks team size; solo, team, enterprise paths differ. + +When to use. When the product has materially different setups for different scales. + +Pattern D: Inferred branching. + +How it works. Wizard uses signals (signup source, email domain, prior interaction) to infer the segment without asking. + +When to use. When asking would feel intrusive but the inference is reliable. + +Pattern E: No branching. + +How it works. Single wizard for all. + +When to use. Most products. Branching adds maintenance; only branch when the value is clear. + +--- + +## Admin vs end-user wizard design + +How they differ. + +Admin wizard. + +- Setup-heavy. Connect data, invite team, configure permissions. +- Ah-ha moment: "the workspace is ready; my team can use it." +- Often longer; admins accept guided setup. + +End-user wizard. + +- Action-light. Find the feature, take the first action, see the result. +- Ah-ha moment: "I did the thing I came to do." +- Often shorter; end-users want to start using. + +Cross-talk. Admins sometimes also become end-users in single-person teams. The wizard may need to detect and serve both modes. + +--- + +## Technical vs non-technical wizard design + +How they differ. + +Technical wizard. + +- API depth visible (configuration shown, integration tested). +- Tone: precise, terse, references documentation. +- Ah-ha moment: "the integration works; my data is flowing." + +Non-technical wizard. + +- Outcome visible (result shown, no API exposed). +- Tone: warm, supportive, hides technical complexity. +- Ah-ha moment: "I see the result the product promised." + +Cross-talk. Some users are technical for some products and not for others. The wizard may infer rather than ask. + +--- + +## Size-based wizard design + +How they differ. + +Solo founder wizard. + +- Single-user setup. +- Skip team-related steps. +- Ah-ha moment: individual productivity. + +Small team wizard. + +- Collaboration setup highlighted. +- Invite-team step prominent. +- Ah-ha moment: team coordination. + +Enterprise wizard. + +- SSO, governance, compliance setup. +- Often involves admin handoff to IT or security. +- Ah-ha moment: deployment-ready configuration. + +--- + +## When to combine vs separate + +Designing the matrix. + +Combine when: + +- The differentiation is small (1-2 different steps). +- Maintenance burden is the bigger concern. +- The audiences overlap significantly. + +Separate when: + +- The paths differ in 3+ steps. +- Tone and language differ significantly. +- Audience-fit is critical (B2B SaaS where different roles experience the product very differently). + +The 2-3 variants max rule. More than 3 wizard variants becomes unmaintainable. If 4+ variants seem necessary, reconsider whether the segmentation is too granular or whether different wizards should be different products. + +--- + +## Differentiation testing + +Verify the differentiation works. + +Cohort comparison. Compare activation rates across variants. Did differentiation help? + +Per-segment satisfaction. Survey users post-wizard. Does each segment feel served? + +Drop-off per variant. Are some variants dropping off more than others? Which steps? + +The data informs whether the differentiation earned its complexity. + +--- + +## Common differentiation failures + +Over-differentiation. Too many variants; maintenance burden; no variant is excellent. + +Under-differentiation. One wizard for distinct audiences; everyone feels poorly served. + +Wrong axis. Differentiated by an axis that does not predict need (e.g., gender when role would have been the right split). + +Inferred wrongly. Inference logic mistakes audience; users see wrong wizard. + +Stale differentiation. Audience composition shifted; old branching no longer fits. + +--- + +## Methodology-level choices that stay in the public skill + +The differentiation principle. Common differentiation axes. Patterns A through E. Admin vs end-user design. Technical vs non-technical design. Size-based design. Combine-vs-separate decision. Differentiation testing. Common failures. + +## Implementation choices that stay internal + +Specific wizard variants for specific products. Specific copy per variant in brand voice. Specific inference logic. The team's variant maintenance calendars. These vary by team and product. diff --git a/skills/onboarding-wizard-design/references/wizard-anti-patterns.md b/skills/onboarding-wizard-design/references/wizard-anti-patterns.md new file mode 100644 index 0000000..01f9cfc --- /dev/null +++ b/skills/onboarding-wizard-design/references/wizard-anti-patterns.md @@ -0,0 +1,212 @@ +# Wizard anti-patterns + +The patterns that look like onboarding but degrade activation. Anti-patterns are easy to ship; the cost shows up in activation rate, retention, and brand reputation over time. + +--- + +## The tutorial-overload wizard + +The pattern. Every feature explained in a 12-step intro before the user has touched the product. + +The signal. High skip rate; users abandon mid-wizard; activation rate poor. + +The cost. Design effort produces a sequence almost nobody completes. Users who do complete have not seen value; activation suffers. + +The cure. Prune steps to those that contribute to the ah-ha moment. Defer feature explanations to in-product tours and contextual help. + +--- + +## The skip-friendly-empty wizard + +The pattern. "Skip onboarding" button at every step, so prominent that users always take it. + +The signal. Skip rate near 100 percent; users land in unconfigured product; activation rate falls. + +The cost. The product appears empty to users who skipped; they do not know what to do; they leave. + +The cure. Rebalance skip prominence. Add consequence-honest skip warnings. Add resume mechanisms so skipped steps come back as in-product prompts. + +--- + +## The decoration-step wizard + +The pattern. Steps that exist for completeness or feature pride, not for value. + +The signal. Drop-off concentrates on specific steps users perceive as pointless; analytics shows steps users always skip. + +The cost. Wizard length without value; user perceives the wizard as bloated. + +The cure. Audit each step. Cut steps that do not contribute to the ah-ha moment. + +--- + +## The tutorial-as-ah-ha wizard + +The pattern. Treating "learned about features" as activation. Wizard ends; user has seen a tour; team treats this as success. + +The signal. High completion rate, low retention. Users completed the wizard but did not engage afterward. + +The cost. The wizard's success metric is wrong. Real activation never happens. + +The cure. Define the ah-ha moment as action-tied. Redesign the wizard to converge on the moment. + +--- + +## The demo-as-ah-ha wizard + +The pattern. The wizard ends with a polished demo using fake data. + +The signal. Users see what is possible; do not return because their actual data has not been touched. + +The cost. The wizard's value is contrived; activation does not stick because the value was hypothetical. + +The cure. Make the ah-ha moment real. Use the user's actual data. + +--- + +## The over-branched wizard + +The pattern. 5 wizard variants for 5 imagined personas. Maintenance burden compounds. + +The signal. Variants diverge over time; some break; activation per variant is uneven. + +The cost. Maintenance overhead high; quality of any one variant degrades. + +The cure. Reduce variants to 2-3 max. Combine variants where the differentiation does not produce materially different paths. + +--- + +## The under-branched wizard + +The pattern. One wizard for distinct audiences. Admins, end-users, technical, non-technical all see the same flow. + +The signal. Some segments activate well; others do not. Per-segment data shows the gap. + +The cost. The audiences underserved leave; the wizard's design effort produces good outcomes for one segment and bad for others. + +The cure. Differentiate where the audience genuinely splits. + +--- + +## The hidden-skip wizard + +The pattern. Skip exists but is hidden behind a "more options" toggle or appears only after the user struggles. + +The signal. Users who need to escape leave the product entirely instead of skipping. + +The cost. Forced friction loses users who would have engaged later if they had been allowed to defer. + +The cure. Make skip findable. Make consequences clear. Add resume. + +--- + +## The validation-strict wizard + +The pattern. Validation rejects valid inputs because rules are over-specified. + +The signal. Users with valid but unusual inputs cannot proceed; abandon. + +The cost. Filter loses real users. + +The cure. Audit validation. Email plus-aliases, international phone, non-Latin names should pass. + +--- + +## The mobile-broken wizard + +The pattern. Wizard works on desktop; breaks on mobile. + +The signal. Mobile completion half of desktop or worse. + +The cost. Mobile audience underserved; mobile is often majority of traffic. + +The cure. Mobile-first design and testing. + +--- + +## The unmaintained wizard + +The pattern. Wizard built once; product evolved; wizard not updated. + +The signal. Users hit broken steps; references to deprecated features; analytics drift. + +The cost. The wizard becomes liability; current users get worse experience than past users. + +The cure. Quarterly maintenance. Product changes trigger wizard updates as part of the change. + +--- + +## The interrogation-disguised-as-wizard + +The pattern. Wizard asks 12 fields, of which 5 affect product setup. The other 7 are sales-qualification or marketing data. + +The signal. Drop-off climbs at fields that feel like sales forms; users sense the manipulation. + +The cost. Filter loses users who would have engaged with a product-focused wizard. + +The cure. Audit fields. Remove or defer fields that do not contribute to product setup. Capture sales/marketing data later in the relationship. + +--- + +## The popup-interrupted wizard + +The pattern. User is mid-wizard; a popup appears (newsletter, chat, special offer); flow breaks. + +The signal. Drop-off spikes at the popup moment; users complain about interruption. + +The cost. Wizard's user experience hostile; brand earns annoying reputation. + +The cure. Suppress popups during wizard completion. Save promotional content for after. + +--- + +## The reset-on-error wizard + +The pattern. User submits; validation fails; wizard resets, losing user inputs. + +The signal. Users who hit error do not retry; they leave. + +The cost. The wizard treats errors punitively; trust collapses. + +The cure. Preserve inputs on error. Show error inline; let the user fix and resubmit. + +--- + +## The wizard-without-activation-metric + +The pattern. Wizard tracked by completion rate alone. Activation not measured. + +The signal. Completion looks fine; team cannot diagnose whether the wizard is producing engaged users. + +The cost. The wizard's success metric is wrong; bad wizards look good in dashboards. + +The cure. Define and track activation explicitly. Wizard completion is leading indicator at best. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active wizard, looking for these anti-patterns. + +Audit questions per wizard. + +- Does each step contribute to the ah-ha moment (anti-pattern check: tutorial-overload, decoration)? +- Is skip honest about consequences and recoverable (anti-pattern check: skip-friendly-empty, hidden-skip)? +- Does the wizard match the product's current state (anti-pattern check: unmaintained)? +- Is activation tracked (anti-pattern check: completion-only metrics)? +- Does the wizard work on mobile (anti-pattern check: mobile-broken)? +- Is validation calibrated to actual requirements (anti-pattern check: validation-strict)? +- Are inputs preserved on error (anti-pattern check: reset-on-error)? +- Is the audience segmentation right (anti-pattern check: over-branched, under-branched)? + +The retire decision. Anti-pattern wizards often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/onboarding-wizard-design/references/wizard-decision-criteria.md b/skills/onboarding-wizard-design/references/wizard-decision-criteria.md new file mode 100644 index 0000000..f1ec10b --- /dev/null +++ b/skills/onboarding-wizard-design/references/wizard-decision-criteria.md @@ -0,0 +1,133 @@ +# Wizard decision criteria + +When wizards earn the build vs when contextual help suffices. The conditions that warrant the wizard format, and the funnels where a wizard adds friction without lift. + +A wizard is meaningful work. Step architecture, ah-ha moment design, progressive disclosure, skip mechanics, drop-off instrumentation, ongoing maintenance. The wizard earns this investment only when specific conditions are present. + +--- + +## When wizards earn the build + +Five conditions that, when present, make a wizard a strong investment. + +The product has meaningful setup before value emerges. Connect a data source, invite a teammate, configure a workspace, choose a use case. Without setup, the product is empty; the wizard makes setup tractable. Products that work immediately on signup do not need this. + +The ah-ha moment requires multiple actions in sequence. Single-action ah-ah moments (paste a URL, see a result) often work better with contextual prompts. Multi-action ah-ha moments benefit from a guided sequence. + +The audience expects guided onboarding. B2B SaaS with technical setup, enterprise software, configurable products often work well with wizards. Some audiences (frictionless consumer tools) reject wizard friction regardless of product complexity. + +The team can maintain the wizard. Wizards decay as the product evolves; deprecated features still in flow break the experience. Without maintenance commitment, the wizard becomes a liability. + +The success metric is defined. Not just completion rate; activation rate (post-wizard product engagement) and time-to-value. Without the success metric, evaluation is impossible. + +When all five are present, the wizard is a strong investment. When two or fewer are present, contextual prompts often serve better. + +--- + +## When wizards do NOT earn the build + +Funnels where the wizard adds friction without lift. + +The product reaches value immediately. Single-input tools, simple consumer products, frictionless utilities. A wizard adds steps where the user could already see value. + +Contextual help would suffice. Tooltips, in-feature hints, progressive in-product education sometimes serve better than upfront wizards. The user explores naturally; help surfaces when needed. + +The audience expects no friction. Some audiences abandon at any wizard. Consumer-facing high-volume products, embedded tools, prosumer utilities. Meet the audience where they are. + +The team cannot maintain the wizard. Stale wizards point to deprecated features; users hit broken steps. Without maintenance capacity, no wizard is better than a stale one. + +The setup work is genuinely better in-product. Some setup is better done after the user understands the product. Wizards that try to set up something the user does not yet understand produce poor configuration. + +The honest assessment matters more than the default. "Should we have an onboarding wizard" is not the question. "Is the wizard the right tool for this product and audience" is. + +--- + +## The opportunity-cost frame + +A wizard is significant work. Account for it. + +The build cost. Step architecture, copy, design, instrumentation, integration with the product, maintenance scaffolding. A meaningful wizard often takes 40-150 engineering hours plus design and copy. + +The maintenance cost. Quarterly review minimum; product changes trigger wizard updates. 4-12 hours per active wizard per quarter. + +The opportunity cost. What else could the team have built? Direct in-product improvements, contextual help, documentation, a simpler activation funnel. The wizard's success has to clear the bar of those alternatives. + +The decision frame. The wizard earns investment when it produces more activation lift than the alternatives, accounting for build plus maintenance. + +--- + +## The ah-ha-moment precondition + +Without an identifiable ah-ha moment, the wizard has nothing to engineer toward. + +The check. Can the team articulate the single visible moment when the user feels "oh, this is what the product does for me"? + +If yes, the wizard can be designed to converge on that moment. If no, the team has not yet defined what activation means; the wizard cannot be designed coherently until that is settled. + +Defining the ah-ha moment is upstream of wizard design. Sometimes the right move is to spend time identifying the ah-ha moment first (often through customer research) before scoping the wizard. The wizard built without a defined ah-ha moment is the wizard that produces high completion and low activation. + +--- + +## The decision worked example + +A B2B SaaS analytics platform considering an onboarding wizard. + +Conditions check. + +- Meaningful setup before value: yes. Connect at least one data source. +- Ah-ha moment multi-action: yes. Connect data, run first query, see useful result. +- Audience expects guided onboarding: yes. Data analysts and data leaders generally accept guided setup. +- Maintenance commitment: yes. Activation team owns the wizard. +- Success metric defined: yes. Activation = ran at least one query within 7 days of signup. + +Decision. Build the wizard. The conditions warrant it. + +Step architecture. Welcome (skippable) → connect first data source → confirm connection → guided first query → see result (ah-ha moment) → invite teammates (deferable) → in-product home. + +Maintenance commitment. Activation team reviews quarterly; product changes trigger wizard updates. + +The decision was not "should we have a wizard" but "given these conditions, this is the wizard to build." + +--- + +## The decision worked example: when to choose differently + +A consumer note-taking app considering an onboarding wizard. + +Conditions check. + +- Meaningful setup: no. The user can start typing immediately. +- Ah-ha moment multi-action: no. The ah-ha moment is "I can save a note and find it later," reachable without setup. +- Audience expects guided onboarding: no. Consumer note-taking audiences resist friction. +- Maintenance commitment: yes (capacity exists). +- Success metric: defined (returned within 7 days). + +Decision. Do not build a wizard. Contextual prompts (sample notes, brief tooltip on first save, short empty-state prompts) serve better. + +The decision was "is this wizard right for this product" and the answer was no even though the team had capacity. + +--- + +## When to retire a wizard + +Wizards can become wrong even after being right initially. + +Retire when: + +- Activation rate has dropped below baseline for two consecutive quarters and refinements have not moved it. +- The product has changed enough that the wizard guides users toward deprecated paths. +- Customer research shows users skipping the wizard and activating fine without it. +- A redesigned in-product activation flow makes the wizard unnecessary. +- The team can no longer maintain the wizard. + +The retiring discipline frees capacity. Stale wizards are worse than no wizards. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant a wizard. The five conditions that argue against. The opportunity-cost frame. The ah-ha-moment precondition. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific wizard scope decisions for specific products. The team's capacity benchmarks. Specific tooling for wizard implementation and instrumentation. Specific success-metric baselines. These vary by team and product. diff --git a/skills/paid-media-strategy/SKILL.md b/skills/paid-media-strategy/SKILL.md new file mode 100644 index 0000000..2d0a67b --- /dev/null +++ b/skills/paid-media-strategy/SKILL.md @@ -0,0 +1,256 @@ +--- +name: paid-media-strategy +description: "A discipline for running paid media that does not light money on fire. Hypothesis writing for paid spend, channel selection, budget allocation, audience targeting, bid strategy, campaign types, what NOT to spend on, attribution reality, and the failure modes that produce expensive lessons. Triggers on paid media strategy, ad budget allocation, channel selection, paid media plan, audit my Google Ads, audit my Meta Ads, scale paid media, kill underperforming campaign, paid media hypothesis, ad spend strategy, attribution reality, performance marketing strategy. Also triggers when a team is asking how to scale paid media, or whether to add a new channel, or how to reallocate spend across channels." +category: marketing +catalog_summary: "Hypothesis to spend: channel selection, budget allocation, audience targeting, bid strategy, attribution reality, and the failure modes that burn agency-scale budgets" +display_order: 1 +--- + +# Paid Media Strategy + +A senior performance marketer's playbook for running paid media that produces real outcomes. + +The default state of paid media is wasted spend. Most accounts have campaigns running because they always have, audiences targeting because the rep suggested it, bid strategies on auto because manual is hard, creative not refreshed because there is no system. The cost compounds. A 20% efficiency gain on a $500K-per-year account is $100K back to the business. A 50% gain on a $5M-per-year account is $2.5M. + +This skill is the discipline that produces those gains. It assumes you have a paid media platform (Google Ads, Meta, LinkedIn, TikTok, or aggregators like Synter) connected. It assumes you have working analytics and conversion tracking. The hard part is the strategic discipline behind the spend, and that is what is here. + +When to use this skill: any time you are designing a paid media plan, evaluating whether to scale or kill a campaign, allocating budget across channels, or auditing an existing account. + +--- + +## What this skill is for + +This skill spans paid media strategy and operations. It does not cover ad creative production (use `ads-creative-development`), result interpretation in depth (use `ads-performance-analytics`), or platform-specific MCP tooling (consult each ad platform's official documentation for current MCP setup, auth, and example prompts). + +The audience is a performance marketer (in-house or agency), a growth lead allocating spend across channels, or a founder making early paid budget decisions. The voice is tactical. There is no "evaluate every option yourself with no opinion." Paid media decisions have shape, and a senior practitioner can map a situation to a defensible plan in an afternoon. + +--- + +## Hypothesis discipline for paid spend + +Most paid media failures start with a vague reason for spending. A real spend hypothesis has five parts: audience, offer, channel, outcome metric, and magnitude. Missing any of them and the campaign cannot be evaluated honestly. + +A bad reason: "We need to scale Google Ads spend." No audience, no outcome metric, no magnitude. Nothing is falsifiable. + +A good hypothesis: "Top-of-funnel SaaS prospects searching for project management tools convert from a free-trial CTA at 3.2% CAC under $80. Increasing Search budget from $40K to $80K per month should hold CAC under $80 and add roughly 500 trial signups based on Q3 search volume." + +That hypothesis names the audience (top-of-funnel SaaS prospects on PM-tool keywords), the offer (free trial), the channel (Google Search), the outcome metric (CAC, trial signups), and the magnitude (500 signups, CAC under $80). It is falsifiable: if CAC blows past $80 or signups come in below 250, the hypothesis is wrong and you pull back. + +Pre-commit the falsification rule. Decide before scale: at what CAC do we hold? At what CAC do we pull back? At what trial-signup count do we kill? Without pre-commit, every result becomes a debate. With pre-commit, the decision is mechanical. + +Primary metric is the one you are optimizing for (CAC, ROAS, CPL). Guardrails are the metrics you do not want to break (LTV, retention, brand search lift). Scaling the primary metric while breaking a guardrail is a Pyrrhic win. + +--- + +## Channel selection: when to use which platform + +Pick the channel where intent matches your offer. Run the wrong channel and your CAC reads as a channel problem when it is actually a fit problem. + +Google Search. High-intent demand capture. Best when you have a real product people search for and the query volume justifies the floor. Worst when category awareness is low and no one is searching. Predictable, expensive at scale, the highest floor of any channel. + +Google Performance Max. Automated multi-channel within the Google ecosystem. Best when you have a strong product feed (e-commerce) or want to lean into Google's automation. Worst when you need control over placements; PMax is a black box and disagreements with the algorithm cost money. + +Meta (Facebook plus Instagram). Broad-targeting demand creation. Best for visual products, lifestyle brands, B2C scale, and direct response with strong creative. Worst when targeting is too narrow (audiences saturate fast) or when the offer is high-consideration B2B. + +TikTok. Discovery-mode advertising. Best for native-feeling video creative, younger audiences, and brand awareness. Worst for direct response with high consideration cycles. Spark Ads (boosting organic posts) outperform pure paid creative. + +LinkedIn. B2B targeting precision. Best for high-LTV B2B with clear job-title targeting. Worst for low-AOV products; the floor is too high to be efficient. + +Reddit, Pinterest, Snapchat, X. Niche or supplementary. Best as scale-out channels after primary channels are working. Worst as starting points; spreading thin across niches before you have proven any channel is the most common waste pattern. + +YouTube (Google). Video at scale. Best for awareness or for B2C consideration. Underrated for B2B SaaS in some categories where the buyer-research path includes long-form video. + +The decision rule. Start with the channel where intent matches your offer. Search for high-intent demand capture. Meta or TikTok for demand creation. LinkedIn for B2B precision. Do not run all of them at once until you have proven any of them. Detail in [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md). + +--- + +## Budget allocation: brand vs performance, baseline vs test + +Four splits operate at the same time. Get them all right and the budget compounds. + +Brand vs performance. Brand keeps the demand pipeline filled (long term); performance captures it (short term). 70-30 to 80-20 performance-heavy is typical for most B2C. Brand-heavy splits fit high-consideration B2B where the buying cycle is months long and pipeline visibility matters more than week-over-week conversions. + +Baseline vs test. 70 to 80% of budget to channels, campaigns, and audiences that are working. 20 to 30% to systematic testing of new channels, new audiences, new creative. Without test budget, you stagnate. Without baseline budget, you have nothing to scale. + +Primary vs secondary channel. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the equal-split temptation; spreading across channels before any one is proven is the most expensive way to learn nothing. + +Daily vs lifetime budgets. Daily for ongoing campaigns where you want a stable spend floor. Lifetime for finite tests where the platform should pace itself across the test window. Lifetime budgets prevent runaway spend during testing. + +Budget pacing matters too. Front-load some weeks to test creative aggressively. Back-load others to capture seasonality (holiday, end-of-quarter, category-specific moments). Do not run flat; flat budgets miss the demand peaks. + +Detail and templates in [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md). + +--- + +## Audience targeting: prospecting vs retargeting vs exclusion + +Three audience types. Treat them as separate strategies. + +Prospecting. New people who have not heard of you. Lookalike audiences (Meta), in-market audiences (Google), interest stacks, lookalikes seeded from high-LTV customers. Largest budget share for growth-mode brands; this is where new demand comes from. + +Retargeting. People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC. Do not bid too aggressively or you train the platform to charge a premium for users who would have converted anyway. + +Exclusion. Current customers and recent converters kept out of prospecting and retargeting. Saves spend, keeps frequency low, prevents creative fatigue from people who are already paying you. + +Common mistakes. Prospecting too narrow (not enough audience for the platform to optimize). Retargeting too aggressive (cannibalizing organic conversions). No exclusions (paying to advertise to your own paying customers). Lookalikes off the wrong source (use top-LTV customers, not all customers). + +Detail in [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md). + +--- + +## Bid strategy: when each fits + +Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. + +Manual CPC or CPM. Full control, slow to scale. Useful for diagnostics and very early campaigns where you do not trust the platform's machine learning yet. + +Maximize Conversions. Platform optimizes for volume within budget; the platform decides CPC. Use when you want as many conversions as possible regardless of cost. Good early-stage strategy while you gather data. + +Target CPA (tCPA). Set a max CPA, platform delivers within. Use when CPA is the constraint and you have at least 30 conversions in the recent window for the platform to optimize against. + +Target ROAS (tROAS). Set a min ROAS, platform delivers above. Use when revenue per conversion varies and you care about value, not count. + +Maximum Conversion Value. Like maximize conversions but optimizes for total revenue, not count. Use when high-value conversions are the goal and you have the conversion-value data wired in. + +Enhanced CPC. Manual CPC with platform adjustments. Hybrid; rarely the right answer because it muddies the signal. + +The progression for new campaigns: start manual or maximize conversions to gather data, switch to tCPA or tROAS once you have 30+ conversions, revisit periodically. + +Common mistakes. Using tCPA before you have 30+ conversions (no data to optimize against). Setting tROAS too aggressively (platform throttles delivery). Switching strategies too often (each change resets the learning phase). Detail in [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md). + +--- + +## Campaign types + +For each major platform, the campaign types and when to use them. + +Google Ads. Search, Shopping, Performance Max, Display, Video (YouTube), Demand Gen, Discovery, App. Search for direct demand capture. PMax for catalog-driven e-commerce. Display for retargeting. Video for awareness or consideration. + +Meta. Sales, Leads, Engagement, Awareness, Traffic, App Promotion. Sales for direct response. Awareness for brand at scale. Leads for B2B with native lead forms. + +LinkedIn. Sponsored Content, Message Ads, Conversation Ads, Lead Gen Forms. Format types: Single Image, Carousel, Video. Lead Gen Forms convert hardest because they pre-fill from LinkedIn profile data. Message Ads have stigma in many B2B segments; use carefully. + +TikTok. In-Feed, TopView, Spark Ads, Branded Hashtag Challenge. Spark Ads (boost organic posts) outperform pure paid creative because they retain organic-feel signal. Use Spark when you have organic posts performing. + +Detail per platform in [`references/campaign-type-reference.md`](references/campaign-type-reference.md). + +--- + +## What NOT to spend on + +Direct list. Audit any account against these and you will usually find easy savings. + +- Branded keywords beyond defensive. When ranking number one organically, branded paid clicks cannibalize free traffic. Some defensive spend is fine to block competitor bidding. Aggressive bidding on your own brand is waste. +- Display network without targeting. Broad display drives garbage traffic. Use only for retargeting unless you have specific contextual targeting. +- Geographic markets you do not serve. Sounds obvious, fails 30% of accounts. Audit geo targeting quarterly. +- Hours you cannot service. For service businesses (legal, B2B, medical). Pause off-hours unless lead form clearly converts asynchronously. +- Devices that do not convert. If mobile converts at 1% and desktop at 5% with the same CPC, bid down mobile aggressively. +- Audiences who never convert. Pull last 90 days of converters, build exclusion lists for everyone else who repeatedly clicks but never converts. +- Creative that is tired. Frequency above 4 with declining CTR means refresh. Refusing to refresh because "it still works ok" is incremental loss. + +The pattern across these is the same. Default settings or accumulated cruft generate spend without producing outcomes. Audit, exclude, and reclaim. + +--- + +## Creative testing: within campaign vs across campaign + +Two modes. Different learning rates, different overhead. + +Within-campaign testing rotates 4 to 6 ad variations and lets the platform optimize delivery to top performers. Lower test risk because all variations live inside one campaign with one budget. Slower learning because the platform's optimization muddies the signal of which variation actually wins. + +Across-campaign testing runs entire campaign concepts (audience plus offer plus creative) against each other. Higher learning rate because each campaign has its own audience and budget. Higher setup overhead and harder to keep apples-to-apples. + +Cadence. Refresh top creative every 30 to 60 days at scale. Weekly for high-frequency campaigns. Keep the top one or two evergreen winners running and rotate others. + +The "winning creative is the floor" principle. Do not kill winners to test new ideas. Test alongside. The downside of running the proven winner is small; the downside of killing it for an unproven concept is large. + +--- + +## Frequency capping + +Ad fatigue is real. Same audience seeing the same creative eight times in a week tunes it out, or worse, develops negative associations. + +Typical caps. Three to four impressions per user per week for Awareness campaigns. Six to eight per week for Direct Response. Lower for B2B (one to two per week per LinkedIn target). Platform defaults are usually too high; set explicit caps. + +Rotation as alternative. If you have enough creative variants, rotate often enough that no individual creative hits fatigue threshold. Rotation plus capping is the strongest pattern for high-spend, long-running campaigns. + +--- + +## Attribution mismatch: platform-reported vs actual + +The trap. Platform-reported conversions are inflated by view-through attribution, generous click attribution windows, and platform self-attribution bias. + +Last-click in GA vs platform-reported. Google Ads typically reports 1.3 to 1.5x the conversions GA reports. The gap comes from multi-touch attribution differences and view-through that GA does not credit. + +iOS 14.5+ impact. Meta and other platforms underreport iOS conversions because of App Tracking Transparency. Modeled conversions try to fill the gap; they are imperfect. Treat iOS-heavy reporting with extra skepticism. + +View-through attribution. Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Useful for awareness; misleading for performance optimization. + +Cross-platform interference. Meta retargeting captures users who would have converted from Google Search anyway. Both platforms claim the conversion. You pay for the same conversion twice. + +The discipline. Single source of truth in your warehouse or analytics platform. Report against that for incrementality decisions. Use platform metrics for in-flight optimization only. The deeper interpretation work belongs in `ads-performance-analytics` (forthcoming); this skill names the trap so you do not optimize against the wrong number. + +Per-platform reporting quirks in [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md). + +--- + +## Common failures + +Twelve patterns recur across paid media work. The short version. Detail in [`references/common-failures.md`](references/common-failures.md). + +- "We are scaling but CAC went up." Saturation on the primary audience. Expand the audience or diversify the channel mix. +- "Conversions look fine in the platform, terrible in revenue." Attribution mismatch plus customer quality, not just count. The platform is selecting low-LTV converters because they are easier to find. +- "We A/B tested and one wins, but only by 5%." Within margin of platform noise. Not a real signal. +- "We turned off the underperforming campaign and conversions dropped overall." View-through or assist conversions you were not counting. Test with hold-out, not flat off. +- "Frequency hit 8 last week." Refresh creative. Do not blame the audience. +- "We are trying to scale Meta to $100K per day from $20K per day." That is not scaling, that is a 5x jump. Expect efficiency drop; phase the increase. +- "We tried LinkedIn for our B2C product." Wrong channel for the offer. Not a LinkedIn problem. +- "tROAS will not deliver." You set it too aggressive. Loosen the target or switch strategy. +- "We saw a click-through bump after the Super Bowl ad." That is brand effect on existing demand, not paid attribution. Read it as a brand signal. +- "Search Impression Share dropped." Either competition increased or budget is constrained. Check both before tuning bids. +- "PMax is hard to optimize." Yes. Treat PMax as a tested channel with constrained levers, not a place to fine-tune at the keyword level. +- "Lookalike performance dropped after we expanded to 5%." Wider lookalikes are looser; the floor is lower. Tighten back to 1 to 2% if CAC is the constraint. + +--- + +## The framework: 11 considerations for sustainable paid media + +When designing or auditing paid media, walk these 11 considerations. Skipping any of them is how teams burn budget at scale. + +1. Hypothesis. Audience, offer, channel, outcome metric, magnitude. Pre-commit the falsification rule. +2. Channel fit. Intent matches offer. Search for capture, Meta and TikTok for creation, LinkedIn for B2B precision. +3. Budget shape. Brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. +4. Audience strategy. Prospecting, retargeting, exclusion. Treated as separate strategies. +5. Bid strategy. Manual, max conversions, tCPA, tROAS, max conversion value. Matched to data state. +6. Campaign type. Right type for the platform and the goal. +7. What not to spend on. Branded beyond defensive, untargeted display, wrong geos, off-hours, low-converting devices, never-convert audiences, tired creative. +8. Creative testing. Within campaign and across campaign, plus refresh cadence. +9. Frequency capping. Explicit caps and creative rotation. +10. Attribution reality. Single source of truth, platform metrics for in-flight only. +11. Decision rule. Pre-committed scale up, hold, or pull back at known thresholds. + +The output of the framework is one of three answers. Scale (the hypothesis is confirmed at the magnitude needed to justify more spend). Hold (results are at the falsification line; gather more data before committing). Kill (the hypothesis is wrong or the campaign is no longer pulling its weight). + +--- + +## Reference files + +- [`references/channel-decision-matrix.md`](references/channel-decision-matrix.md) - Context-to-channel matrix with worked examples for the most common business contexts. +- [`references/budget-allocation-templates.md`](references/budget-allocation-templates.md) - Typical splits and pacing patterns: growth-mode, steady-state, brand-heavy, performance-heavy. +- [`references/audience-segmentation-patterns.md`](references/audience-segmentation-patterns.md) - Prospecting, retargeting, exclusion templates plus cross-platform reconciliation. +- [`references/bid-strategy-reference.md`](references/bid-strategy-reference.md) - Each strategy's fit, common mistakes, and migration paths as data accumulates. +- [`references/campaign-type-reference.md`](references/campaign-type-reference.md) - Per-platform campaign type guide with pitfalls. +- [`references/ads-platform-comparison.md`](references/ads-platform-comparison.md) - Platform reporting quirks, attribution differences, and the single-source-of-truth pattern. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, and prevention. + +--- + +## Closing: when in doubt, kill the campaign + +Most paid media decisions reduce to scale, hold, or kill. When the analysis is genuinely ambiguous, default to kill. + +The cost of a campaign that is not clearly working is real money flowing out the door every day. The cost of killing a marginal campaign is mostly just the inconvenience of restarting it later. Asymmetric risk. Default to kill. + +The follow-on rule is symmetric. When the hypothesis is clearly confirmed at the magnitude that matters, scale aggressively. The cost of slow-rolling a working campaign is opportunity cost; competitors compound on the same demand pool. Default to scale once the data justifies it. + +Marginal results are the trap. They invite more analysis, more meetings, more "let us give it another two weeks." Two weeks of marginal CAC is two weeks of lost money. Pre-commit the decision rule and execute it. diff --git a/skills/paid-media-strategy/references/ads-platform-comparison.md b/skills/paid-media-strategy/references/ads-platform-comparison.md new file mode 100644 index 0000000..3a181f8 --- /dev/null +++ b/skills/paid-media-strategy/references/ads-platform-comparison.md @@ -0,0 +1,106 @@ +# Ads platform comparison + +Per-platform reporting quirks, attribution differences, and the single-source-of-truth pattern. + +The platforms do not agree on what counts as a conversion or how long a click should attribute. Reading the platform's reported numbers as truth is the most expensive mistake in paid media. + +--- + +## Google Ads + +Default attribution model. Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on the platform's machine learning. Single touch attribution (last-click) is available but no longer the default. + +Conversion windows. Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA reports by default, which produces the typical 1.3 to 1.5x conversion overcount versus GA. + +Quirks to know. +- DDA gives partial credit to keywords that touched the path even if the user did not click. The reported conversion volume under DDA is higher than under last-click. +- Smart Bidding optimizes against the DDA-reported conversions, not GA-reported. Optimizing for one number while measuring against another produces drift. +- View-through attribution on Display and Video is opt-in; default is off. + +Reading the numbers. Compare Google Ads conversions against GA's "Google Ads" channel rather than against total GA conversions. The gap between the two is the attribution-model gap; treat with awareness. + +--- + +## Meta (Facebook + Instagram) + +Default attribution. 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only. + +Conversion windows. 7-day click is the standard. Wider windows are more generous to Meta; narrower windows are more conservative. + +iOS 14.5+ impact. App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated based on aggregated behavior) and Conversions API (server-side event tracking). Both help, neither fully restores pre-ATT visibility. + +Quirks to know. +- View-through attribution counts impressions even if the user did not click. Often half the reported conversions are view-through. Treat with skepticism for direct response. +- Modeled conversions are a meaningful share of iOS-reported conversions in 2025-2026. They are statistically estimated, not directly observed; do not trust them with the precision you would trust click-based conversions. +- Conversions API (CAPI) sends server-side events that complement pixel events. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. + +Reading the numbers. Disaggregate by attribution window in the Ads Manager (1-day click, 7-day click, 1-day view, 7-day view). The 1-day click number is the most conservative and the closest to incremental. + +--- + +## LinkedIn + +Default attribution. 30-day click and 7-day view-through. + +Conversion windows. Longer than B2C platforms because B2B buying cycles are longer. The 30-day click window matches the typical B2B consideration cycle for many categories. + +Quirks to know. +- LinkedIn's reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair with self-reported attribution surveys for B2B. +- Lead Gen Forms count form submissions as conversions; downstream lead qualification is on you to track. +- Demographic insights (job title, seniority, company size, industry) are unique to LinkedIn and uniquely valuable for B2B audience refinement. + +Reading the numbers. Lead Gen conversions are easy to overcount because form friction is low; some leads are accidental. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. + +--- + +## TikTok + +Default attribution. 7-day click and 1-day view-through (similar to Meta). + +Conversion windows. Adjustable. TikTok also supports a "video view" event that is unique to the platform. + +Quirks to know. +- Video-completion-based attribution: TikTok counts conversions even when the user did not click but watched the full video. This is real signal for awareness; it inflates direct-response numbers. +- iOS impact similar to Meta but less mature in the modeling. +- Spark Ads attribution is shared between paid and organic. The same view that drove a conversion shows up in both surfaces; be careful not to double-count when reconciling. + +Reading the numbers. Click-based conversions are the most reliable. Video-view-based conversions are real signal but should be reported separately. + +--- + +## Cross-platform interference + +Two platforms claiming the same conversion is the single most common attribution mistake. + +The classic case. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). GA might attribute it to organic if the brand search was not paid. Three different views of one conversion. + +The defense. A single source of truth in your warehouse or analytics platform. Multi-touch attribution at the warehouse level distributes credit fairly. Marketing-mix modeling (MMM) at the budget-allocation level cuts through the platform-self-attribution bias. + +--- + +## Single-source-of-truth pattern + +Three layers, each serving a different decision. + +Layer 1: platform metrics. Use for in-flight optimization only. Ad set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers. + +Layer 2: warehouse multi-touch attribution. Use for cross-platform comparison. Each conversion gets attributed across all platforms that touched the path. Common patterns: last-click, first-click, linear, position-based, time-decay, data-driven. Pick one and standardize across the team. + +Layer 3: marketing-mix modeling (MMM). Use for budget allocation across channels. MMM treats spend as an input and revenue as an output, modeling the contribution of each channel net of the others. The strongest defense against platform-self-attribution bias. + +The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly. + +--- + +## What the numbers mean in practice + +A typical mid-stage account has the following attribution gap pattern: + +- Google Ads reports: 1.3 to 1.5x what GA reports for "Google Ads" channel. +- Meta reports: 1.5 to 2.5x what GA reports for "Facebook" channel (more on iOS-heavy audiences). +- LinkedIn reports: roughly equal to GA for click-based conversions. +- TikTok reports: 1.5 to 3.0x what GA reports (high view-through component). + +If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform-self-attribution. + +The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word. diff --git a/skills/paid-media-strategy/references/audience-segmentation-patterns.md b/skills/paid-media-strategy/references/audience-segmentation-patterns.md new file mode 100644 index 0000000..9cedf2a --- /dev/null +++ b/skills/paid-media-strategy/references/audience-segmentation-patterns.md @@ -0,0 +1,87 @@ +# Audience segmentation patterns + +Three audience types treated as separate strategies: prospecting, retargeting, exclusion. Plus cross-platform reconciliation patterns and the most common anti-patterns. + +--- + +## Prospecting + +New people who have not engaged with your brand. The largest budget share for growth-mode brands. + +Lookalike audiences (Meta, TikTok). Seed from a high-quality source (top 10% LTV customers, paying customers from the last 90 days, repeat purchasers) and ask the platform for similar users. 1 to 2% lookalikes are tightest and convert best at lower volumes; 5 to 10% lookalikes are looser and scale to volume but convert at lower rates. Start narrow, expand only if the floor holds. + +In-market audiences (Google). Google's behavioral signals identify users actively researching a category. Pair with category-relevant keywords for capture, or use as broad targeting on Display, Video, and PMax. + +Interest stacks (Meta). Stack multiple interest groups within an ad set. The stack approach lets the algorithm find the overlap. Single interests are usually too narrow; flat lists of 30 interests are too broad. Aim for 5 to 10 related interests. + +Custom intent or affinity (Google). Build audiences from URL lists or keyword lists. Useful for niche categories where in-market is not a clean fit. + +Account lists (LinkedIn). Upload a target account list and target by company. Pair with job-title or seniority filters to narrow further. The strongest pattern for ABM-style B2B paid. + +The prospecting principle. Start with one well-defined audience that matches your hypothesis. Prove CAC. Then expand. Running five prospecting audiences in parallel before any one is proven is the most expensive way to learn nothing. + +--- + +## Retargeting + +People who engaged but did not convert. Smaller audience size, higher CTR, lower CAC if executed correctly. + +Window splits. Different windows have different conversion intents. Run three retargeting tiers with different creative. + +\| Window \| Audience intent \| Creative \| +\|---\|---\|---\| +\| 0 to 7 days \| Hot. Recent visitors. \| Direct conversion offer. Reinforce value prop. \| +\| 8 to 30 days \| Warm. Considered but did not convert. \| Address objections. Social proof. Comparison content. \| +\| 31 to 90 days \| Cool. Long consideration cycle or churned interest. \| Reactivate with new offers, new content, or value updates. \| + +Cart abandoner specific. If e-commerce, cart abandonment is its own retargeting tier. Window: 0 to 7 days. Creative: cart contents reminder, often with a small incentive (free shipping, 10% off). CTR and CAC are usually the strongest of any retargeting segment. + +Page-specific retargeting. Visitors to high-intent pages (pricing, demo request, product detail) are warmer than homepage visitors. Run page-specific retargeting at higher bids. + +The retargeting trap. Bidding too aggressively trains the platform to charge a premium for users who would have converted anyway. Cap retargeting CPM and CPC; the high CTR and conversion rate produce strong results without aggressive bids. + +--- + +## Exclusion + +The audiences you do not want paying for clicks from. Saves spend and keeps frequency low. + +Current customers. Users with active subscriptions, recent purchases, or active accounts. Exclude from prospecting and most retargeting. Exception: lapsed-cart-from-paying-customer retargeting, which can lift add-to-cart-to-purchase rates. + +Recent converters. Users who converted in the last 30 to 90 days. Exclude from prospecting. The platform will keep showing them ads otherwise, which produces frequency fatigue and zero new revenue. + +Failed-conversion audiences. Users who clicked repeatedly across a 60 to 90 day window without converting. Build an exclusion list from this segment. They have signaled they are not converting from paid; stop paying to show them ads. + +Employee lists. Upload employee email lists and exclude from all paid traffic. Employees clicking on company ads inflate spend and pollute attribution. + +Cross-platform exclusion. When running both Meta and Google, exclude Meta retargeting from Google retargeting (and vice versa). Two platforms hitting the same user with the same offer produces frequency fatigue and double-billing. + +--- + +## Cross-platform audience reconciliation + +When running multiple platforms, audience definitions should align so attribution comparisons are meaningful. + +The seed list problem. If Meta sees a customer file and Google sees a different customer file, the lookalike sources differ. Reconcile by uploading the same customer list to both, segmented identically (top 10% LTV, last 90 days, etc.). + +The retargeting overlap problem. A user who visited the site appears in both Meta retargeting and Google retargeting. Both platforms claim the conversion. Reconcile by running one retargeting platform at a time, or by setting platform-specific retargeting budgets that match the actual incremental contribution. + +The exclusion problem. A user who converts on Meta should be excluded from Google paid prospecting (and vice versa). Without cross-platform exclusion, you pay to advertise the same offer to the same user twice. Pipe conversions to a unified audience layer (CDP, warehouse, or audience-sync tool like Synter or Hightouch) and push exclusions back to each platform. + +--- + +## Anti-patterns + +Common mistakes that recur across accounts. + +Prospecting too narrow. Audience size below the platform's optimization minimum (Meta: roughly 1M users; Google: roughly 100K). The platform cannot optimize against signal that thin. Expand the audience until it has at least 1 to 5 million reachable users (Meta) or in-market scale (Google). + +Retargeting too aggressive. Bidding above the value of the incremental conversion. Half the retargeting "conversions" would have happened anyway from organic; if you bid for them at full attribution, you overpay. + +No exclusions. The most common audit finding. Current customers, recent converters, and employees all clicking on paid ads. + +Lookalike from the wrong source. Building a 5% lookalike from "all customers" (including low-LTV churners). The platform returns users similar to the average, not similar to your best. Always seed from top-LTV or paid-and-retained customers. + +Too many ad sets per campaign. Splitting one campaign into 10 ad sets fractures the data the platform needs to optimize. Consolidate into 2 to 4 ad sets per campaign with audience size sufficient for each to learn. + +Audience overlap across ad sets. Two ad sets in the same campaign targeting similar users compete with each other and inflate CPC. Audit overlap with the platform's overlap tool; consolidate ad sets that overlap above 30%. diff --git a/skills/paid-media-strategy/references/bid-strategy-reference.md b/skills/paid-media-strategy/references/bid-strategy-reference.md new file mode 100644 index 0000000..f2a4630 --- /dev/null +++ b/skills/paid-media-strategy/references/bid-strategy-reference.md @@ -0,0 +1,104 @@ +# Bid strategy reference + +Each major bid strategy with definition, fit criteria, common mistakes, and the migration path as data accumulates. + +The decision shape. Bid strategy depends on data state. New campaigns need a different strategy than mature ones. Switching too often resets the learning phase and wastes the data you just gathered. Pick the strategy that fits the current data state, run it long enough to gather signal, then promote. + +--- + +## Manual CPC or CPM + +Definition. Set a max cost per click or cost per thousand impressions. The platform charges no more than the cap. + +When to use. Diagnostics. Very early campaigns with no data history. Niche audiences where the platform's machine learning would over-broaden. Branded keyword campaigns where you want explicit cost control. + +When not to use. Most production campaigns at scale. Manual scales slowly because every adjustment requires a human decision; automated strategies optimize across thousands of micro-decisions per hour. + +Common mistakes. Setting CPC caps below the auction floor (the campaign delivers nothing). Switching from manual to automated too early before there is enough data for the automated strategy to optimize against. + +--- + +## Maximize Conversions + +Definition. Platform optimizes for conversion volume within the budget. The platform decides CPC. + +When to use. Early-stage campaigns where you want as many conversions as possible regardless of unit cost. Good for gathering the conversion data needed to graduate to tCPA later. Good for awareness or list-building campaigns where volume matters more than per-unit cost. + +When not to use. Once CAC is the binding constraint. Maximize Conversions does not respect CAC; it just optimizes for count. + +Common mistakes. Running Maximize Conversions for too long when CAC is creeping up. Set a cadence to evaluate the migration to tCPA once you have 30+ conversions in the recent window. + +--- + +## Target CPA (tCPA) + +Definition. Set a max CPA. Platform delivers conversions within the target. + +When to use. Once you have 30+ conversions in the recent 30 day window for the platform to optimize against. Use when CPA is the constraint and you have enough data for the platform's machine learning to converge. + +When not to use. Before you have enough conversion data. The platform cannot optimize tCPA without enough signal; it will either underdeliver or learn against noise. + +Common mistakes. Setting tCPA below the prior 30-day actual CPA (platform throttles delivery to almost zero). Setting tCPA too aggressive in a thin-data campaign (same effect; throttled delivery and no learning). Switching tCPA targets every week (each change resets the learning phase). Set the target reasonably (within 15% of recent actual) and let it run. + +--- + +## Target ROAS (tROAS) + +Definition. Set a min ROAS. Platform delivers conversions above the target. + +When to use. When revenue per conversion varies substantially (e-commerce with mixed AOV, marketplaces with mixed take rates). Once you have 50+ conversions and conversion-value tracking is wired in. + +When not to use. Before conversion-value tracking is reliable. Without conversion values, tROAS has nothing to optimize against and falls back to behavior similar to Maximize Conversions but with throttled delivery. + +Common mistakes. Setting tROAS too aggressively (platform delivers almost nothing). Not feeding accurate conversion values (the platform optimizes for the wrong number). Switching tROAS targets too often. + +--- + +## Maximum Conversion Value + +Definition. Like Maximize Conversions, but the platform optimizes for total conversion value rather than count. + +When to use. Same conditions as tROAS, but without a fixed target. Good when you want to maximize revenue within budget without specifying the per-unit ROAS floor. + +When not to use. Without conversion-value tracking. Without volume confidence; same as tROAS, the platform needs enough conversions to optimize against value. + +Common mistakes. Running without conversion values configured (the platform falls back to count). Treating it identically to Maximize Conversions; the value optimization changes which conversions the platform finds. + +--- + +## Enhanced CPC + +Definition. Manual CPC with platform adjustments based on conversion likelihood. + +When to use. Rarely. The hybrid muddies the signal. If you want manual control, run pure manual CPC. If you want automation, graduate to Maximize Conversions or tCPA. + +When not to use. Most situations. The hybrid is a transitional state from a previous platform default; modern campaigns should pick a clear strategy. + +Common mistakes. Treating Enhanced CPC as the safe default. It is neither full control nor full automation; the worst of both. + +--- + +## The migration path + +The progression for a new campaign as data accumulates. + +\| Data state \| Strategy \| Rationale \| +\|---\|---\|---\| +\| Day 1 to ~30 conversions \| Manual CPC or Maximize Conversions \| Gather data. Platform machine learning has nothing to optimize against yet. \| +\| 30 to 100 conversions \| Target CPA \| Platform has enough signal to optimize against a CPA target. Set within 15% of recent actual. \| +\| 100+ conversions, value tracking on \| Target ROAS or Max Conversion Value \| Optimize for revenue or ROAS rather than count. \| +\| Mature campaign at scale \| Whichever produces best CAC + ROAS \| Stay there. Switching strategies on a mature campaign restarts the learning phase. \| + +The migration cadence. Evaluate the migration after every 30 days or every 50% conversion volume increase, whichever comes first. Do not switch every week; the learning phase reset cost is real. + +--- + +## When to NOT switch strategy + +Three signals that suggest staying on the current strategy even when something else looks better. + +1. Recent change. If you switched strategy in the last 14 days, give it more time. The learning phase needs at least 2 weeks of consistent volume to converge. +2. Volatile conversion volume. If conversion volume is bouncing 50%+ week-over-week, the platform's optimization signal is noisy. Stabilize volume before switching. +3. Active creative test. If you are mid-test on creative or audience, do not also change bid strategy. One variable at a time. The bid strategy change muddies the creative test signal. + +The rule. Switch strategy when one variable is stable and the data state has clearly progressed. Avoid stacking changes; you cannot tell which change drove the result. diff --git a/skills/paid-media-strategy/references/budget-allocation-templates.md b/skills/paid-media-strategy/references/budget-allocation-templates.md new file mode 100644 index 0000000..9ff0017 --- /dev/null +++ b/skills/paid-media-strategy/references/budget-allocation-templates.md @@ -0,0 +1,107 @@ +# Budget allocation templates + +Four split patterns plus pacing guidance. Pick the template closest to your situation and adapt. + +The splits operate at the same time: brand vs performance, baseline vs test, primary vs secondary channel, daily vs lifetime. + +--- + +## Template 1: Growth-mode allocation + +For brands actively scaling with a working unit economic model. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Prospecting \| 70% \| New audience reach. Largest share because growth comes from new demand. \| +\| Retargeting \| 20% \| Engaged-but-not-converted users. Small audience, high CTR, low CAC. \| +\| Test \| 10% \| Systematic tests of new audiences, channels, or creative concepts. \| + +Plus brand-vs-performance: 25% brand, 75% performance for B2C. 50-50 for B2B with longer cycles. + +Plus channel: 60-70% to one primary channel that has proven its CAC, 25% to a secondary, 5-15% to scale-out experiments. + +--- + +## Template 2: Steady-state allocation + +For brands holding scale rather than aggressively pushing it. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Prospecting \| 50% \| Lower share because steady-state needs less new demand. \| +\| Retargeting \| 30% \| Higher share because the existing pipeline is the main flow. \| +\| Test \| 20% \| Higher share than growth-mode; steady-state is when systematic testing pays off. \| + +Plus brand-vs-performance: 40% brand, 60% performance. The brand share is higher than growth-mode because steady-state is about defending position. + +--- + +## Template 3: Brand-heavy allocation + +For categories where brand investment compounds (premium consumer, B2B with long consideration, regulated industries). + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Brand \| 60% \| Awareness, reach, video at scale. Long-term demand pipeline. \| +\| Performance \| 40% \| Search and retargeting on the demand the brand creates. \| + +Within performance, 60% prospecting and 40% retargeting is typical. Test budget comes out of the brand share. + +--- + +## Template 4: Performance-heavy allocation + +For DTC and direct-response B2C where the unit economics are tight and brand effects are slow to compound. + +\| Bucket \| Share \| Notes \| +\|---\|---\|---\| +\| Brand \| 20% \| Minimum viable awareness investment. Mostly content and organic. \| +\| Performance \| 80% \| Direct-response paid; CAC is the binding metric. \| + +Within performance, growth-mode splits apply: 70% prospecting, 20% retargeting, 10% test. + +--- + +## Pacing patterns + +Budgets that run flat through the month miss the demand peaks and overspend during the troughs. Three pacing patterns to layer onto the daily template. + +Front-load testing weeks. When launching a new creative concept or a new audience, front-load 60% of the test budget in the first 7 to 10 days. The platform learning phase needs concentrated signal; spreading too thin means slower convergence. + +Back-load seasonality. For categories with a seasonal peak (holiday, end-of-quarter, category-specific moments), shift 30 to 50% of monthly budget into the peak two-week window. Flat budgets through Q4 leave money on the table. + +Front-load for launch. For new campaigns with no historical data, front-load creative testing in week one. Accept lower efficiency in week one in exchange for picking the winning creative quickly. By week three the winning concept should be running at scale. + +Steady for evergreen. For mature campaigns hitting consistent CAC at scale, run flat daily. The platform's learning is stable; introducing pacing variance creates noise that reduces optimization quality. + +--- + +## Daily vs lifetime budgets + +Daily budget. Use for ongoing campaigns where you want a stable spend floor. The platform charges up to your daily cap regardless of opportunity, which is what you want for predictable production work. + +Lifetime budget. Use for finite tests where the platform should pace itself across a defined window. Lifetime budgets prevent runaway spend during testing; the platform optimizes pacing so the test ends on the planned date with the planned spend. + +Mistakes. Using daily for tests (the test runs forever or stops abruptly when budget is paused). Using lifetime for evergreen campaigns (the platform front-loads or back-loads in ways you do not want). + +--- + +## Channel split mistakes + +The most common channel-budget mistake is the equal split. Spreading $100K across four channels at $25K each produces four underperforming campaigns; one campaign at $80K plus three at $7K each produces one strong learning signal and three quick reads on whether the others are worth scaling. + +The principle. One channel does the heavy lifting (60 to 70% of budget). Others scale supplementally. Resist the temptation to be balanced. Balanced budgets across unproven channels is the most expensive way to learn nothing. + +The exception. After two channels are proven independently, splitting toward equal is fine because each channel has its own efficient scale. Before that point, concentrate. + +--- + +## Reallocation triggers + +Three signals that the current split needs to shift. + +1. Primary channel CAC drifted up by 25% over two weeks. The audience is saturating or competition increased. Shift some budget to the secondary channel and drop the primary's daily. +2. Test budget produced a new winner. A test channel or audience is hitting CAC equal to or better than baseline. Promote it to baseline at 15% of total budget; the previous baseline holds 55 to 60%. +3. Frequency exceeded threshold across the prospecting audience. The audience saw the creative more than the cap. Either rotate creative or expand the audience; if both are constrained, pull back budget. + +Reallocation cadence: monthly review minimum. Weekly during high-spend periods or active scale-up. diff --git a/skills/paid-media-strategy/references/campaign-type-reference.md b/skills/paid-media-strategy/references/campaign-type-reference.md new file mode 100644 index 0000000..2d3e007 --- /dev/null +++ b/skills/paid-media-strategy/references/campaign-type-reference.md @@ -0,0 +1,197 @@ +# Campaign type reference + +Per-platform campaign type guide. For each campaign type: what it is, when it fits, common pitfalls. + +--- + +## Google Ads + +### Search + +What it is. Text ads on Google search results pages, triggered by keyword auctions. + +When to use. Direct demand capture. Users searching for category, product, or competitor terms. + +Pitfalls. Branded over-spend (cannibalizing free traffic). Broad match on weak keywords (drives garbage clicks). Missing negative keyword lists (paying for irrelevant search terms). Audit search-term reports monthly and add negatives. + +### Shopping + +What it is. Product listing ads driven by your Google Merchant Center feed. + +When to use. E-commerce with a structured catalog. Comparison-shopping intent. + +Pitfalls. Bad feed quality (missing GTINs, weak titles, wrong categories). The feed is the bottleneck; clean it before scaling spend. + +### Performance Max (PMax) + +What it is. Automated multi-channel campaign that runs across Search, Shopping, Display, YouTube, Discover, and Gmail. The platform decides placement. + +When to use. E-commerce with a strong feed. When you want Google's automation to do the placement work. As a complement to Search, not a replacement. + +Pitfalls. Black box optimization makes manual tuning hard. Cannibalizes branded Search traffic; exclude branded queries via account-level negatives. Asset group quality drives results; weak creative produces weak results regardless of platform automation. + +### Display + +What it is. Banner and image ads on the Google Display Network (millions of partner sites). + +When to use. Retargeting (small audiences, defined intent). Specific contextual targeting where you trust the placement list. + +Pitfalls. Display without targeting drives garbage traffic. Default placements include low-quality sites that hurt brand. Use only for retargeting unless you have explicit placement controls. + +### Video (YouTube) + +What it is. Video ads on YouTube. Various formats (skippable, non-skippable, bumper, in-feed). + +When to use. Awareness at scale. B2C consideration. Underrated for B2B SaaS in some categories where buyer research includes long-form video. + +Pitfalls. Direct-response on Video rarely works as well as Meta video. Use for awareness or as an upper-funnel layer. Skippable ads with strong first-5-seconds work; non-skippable annoys. + +### Demand Gen + +What it is. Successor to Discovery ads. Visual ads across Discover, Gmail, YouTube Shorts, and YouTube in-feed. + +When to use. Visual-first products targeting users in discovery mode (not search mode). + +Pitfalls. Newer campaign type with less optimization history; results are more volatile than Search or Shopping. Treat as a tested channel. + +### Discovery + +What it is. Visual ads across Google's discovery surfaces. Being merged with Demand Gen. + +When to use. Largely deprecated in favor of Demand Gen. Migrate existing Discovery campaigns. + +### App + +What it is. Universal App Campaigns for app installs and engagement. + +When to use. App promotion. Mostly automated; you provide creative and budget. + +Pitfalls. Hard to optimize beyond budget and creative inputs. Track post-install events (subscription, retention) not just installs. + +--- + +## Meta (Facebook + Instagram) + +### Sales + +What it is. Campaigns optimized for conversions. The default for direct response. + +When to use. E-commerce, subscriptions, lead capture with measurable conversion events. + +Pitfalls. Wrong conversion event optimization (optimizing for "Add to Cart" when "Purchase" is what matters). Inadequate pixel setup (the conversion data feeding the algorithm is incomplete). + +### Leads + +What it is. Campaigns with native lead forms inside Facebook or Instagram. + +When to use. B2B with mid-funnel offers (whitepaper, demo request, newsletter signup). Native forms have lower friction than off-platform forms. + +Pitfalls. Lead quality is lower than off-platform forms (less friction, more accidental submissions). Build a CRM enrichment step to filter low-quality leads before passing to sales. + +### Engagement + +What it is. Optimizes for likes, comments, shares, page follows. + +When to use. Building an organic audience. Almost never as a primary objective for performance work. + +Pitfalls. Engagement does not predict conversion. Vanity metrics if used as a primary objective for revenue work. + +### Awareness + +What it is. Optimizes for reach and frequency. Brand-style budget. + +When to use. Brand at scale. New product launches. Competitor-conquest moments. + +Pitfalls. No conversion signal feeding the algorithm. Cannot evaluate against CAC. Use as a brand layer, not a performance layer. + +### Traffic + +What it is. Optimizes for clicks (link clicks or landing page views). + +When to use. Driving traffic to long-form content, blog posts, awareness pages where the user journey is multi-touch. + +Pitfalls. Click-optimized traffic does not predict conversion. The platform finds users likely to click, not users likely to convert. Only use for top-funnel content distribution. + +### App Promotion + +What it is. App install campaigns within Meta. + +When to use. App promotion specifically. Compare against Google App Campaigns. + +Pitfalls. iOS 14.5+ tracking restrictions impact attribution; modeled conversions fill the gap imperfectly. + +--- + +## LinkedIn + +### Sponsored Content + +What it is. Sponsored posts in the LinkedIn feed. + +When to use. B2B awareness and consideration. Native to the LinkedIn experience. + +Pitfalls. High floor (CPM 5 to 10x consumer platforms). Justify with B2B LTV; otherwise unprofitable. + +### Message Ads + +What it is. Direct messages delivered via LinkedIn InMail. + +When to use. High-intent B2B nudges where the message reads as a personal note. + +Pitfalls. Stigma in many segments. Treated as spam if the message reads generic. Personalize aggressively or skip. + +### Conversation Ads + +What it is. Multi-step interactive messages with branching CTAs. + +When to use. Mid-funnel B2B where multiple value propositions need to be tested in one experience. + +Pitfalls. Setup complexity. Many teams underuse the branching capability and run them as glorified Message Ads. + +### Lead Gen Forms + +What it is. Native lead forms pre-filled from LinkedIn profile data. + +When to use. Highest converting LinkedIn objective. Use whenever the offer is a lead capture (demo, whitepaper, content offer). + +Pitfalls. Lead quality varies by form length. Shorter forms get more leads; longer forms filter to higher quality. Iterate. + +### Format types + +Single image, carousel, video. Carousel often outperforms single image for product or feature explainers. Video performs best when shot LinkedIn-native with first-3-seconds hook and captions on by default. + +--- + +## TikTok + +### In-Feed + +What it is. Standard ads in the For You Page feed. + +When to use. Default TikTok format. Most direct-response and awareness work runs here. + +Pitfalls. Polished ad creative is rejected by the algorithm; native-feeling content wins. Iterate creative weekly to avoid fatigue. + +### TopView + +What it is. Premium first-impression placement when users open the app. + +When to use. Brand moments at scale. Product launches. + +Pitfalls. Expensive. Only justify with measurable brand lift or product launch impact. + +### Spark Ads + +What it is. Boost an existing organic post as an ad. Retains organic engagement and signal. + +When to use. Whenever you have organic posts performing. Spark Ads outperform pure paid creative because they retain the organic-feel signal. + +Pitfalls. Requires organic content to exist. If the brand has no organic presence, build one first. + +### Branded Hashtag Challenge + +What it is. Sponsored hashtag with branded content prompts. + +When to use. Major brand campaigns where user-generated participation matters. + +Pitfalls. Expensive. Hard to measure direct response. Best for brands with cultural-moment ambitions, not direct response. diff --git a/skills/paid-media-strategy/references/channel-decision-matrix.md b/skills/paid-media-strategy/references/channel-decision-matrix.md new file mode 100644 index 0000000..bf8ec6d --- /dev/null +++ b/skills/paid-media-strategy/references/channel-decision-matrix.md @@ -0,0 +1,56 @@ +# Channel decision matrix + +A context-to-channel map. The left column is the situation. The center columns are the recommended channels. The right column is reasoning and what NOT to start with. + +Read top to bottom and stop at the first row that matches your situation in three or more dimensions. Use the remaining rows as cross-checks. + +--- + +## The matrix + +\| Situation \| Primary channel \| Secondary channel \| Reasoning and what to avoid early \| +\|---\|---\|---\|---\| +\| Pre-PMF B2B SaaS \| LinkedIn (precision) or Google Search (intent) \| Content + organic; defer paid scale \| Avoid Meta and TikTok early; the audience is not on those platforms. Avoid PMax; you do not have the data state for it. \| +\| High-AOV B2B (>$5K LTV) \| LinkedIn Sponsored Content + Lead Gen Forms \| Google Search on category and intent terms \| LinkedIn floor is high but justified at this LTV. Avoid TikTok, Reddit, and broad Meta until the LinkedIn motion is repeating. \| +\| Low-AOV consumer product (<$50 LTV) \| Meta (Sales objective) \| TikTok (Spark Ads if organic exists) \| Avoid LinkedIn (floor too high). Avoid Search unless category-defining query volume exists. Watch payback period; low LTV with paid CAC is razor-thin. \| +\| DTC with strong visual brand \| Meta (Sales + Reels) \| TikTok In-Feed and Spark Ads \| Avoid LinkedIn. Avoid Display network. Visual-first creative is the moat; double down on the platforms that surface it. \| +\| Local services \| Google Search + Local Service Ads \| Meta with geo radius targeting \| Avoid TikTok and LinkedIn (wrong intent). Pause off-hours. Geo-radius is the most important targeting lever. \| +\| Enterprise SaaS (>$50K ACV) \| LinkedIn (job-title precision) \| Account-Based Marketing platforms + Google Search on category terms \| Avoid Meta and TikTok. Avoid broad Display. Pair with ABM on a target account list; audiences are too small for Meta lookalikes to work. \| +\| E-commerce with catalog \| Google Performance Max + Shopping \| Meta (Catalog Sales) \| Avoid Search-only spend; PMax includes Search and adds catalog placements. Avoid LinkedIn. Feed quality is the bottleneck; fix the feed before spending on PMax. \| +\| Subscription consumer \| Meta (Sales objective with subscriber LTV) \| Google Search on intent + brand terms \| Avoid LinkedIn. Watch retention; CAC paid back over multiple months means the unit economics window matters more than first-month CAC. \| +\| Marketplace (two-sided) \| Channel-by-side: Meta for consumer side, LinkedIn or Search for supplier side \| Reddit niche communities for the supplier side \| Run two separate strategies, not one unified plan. The two sides have different intent and need different channels. \| +\| Pre-launch waitlist \| Meta (Engagement or Lead) \| Reddit and TikTok organic + light paid \| Avoid Search; no one is searching for an unlaunched product. Avoid LinkedIn unless B2B. Cheap CPL but low intent; expect waitlist conversion under 20%. \| + +--- + +## Worked examples + +### Example 1: Series B B2B SaaS, $25K ACV, North American sales motion + +The team has a working sales motion and is scaling outbound. They want paid media to add inbound demand without killing CAC. + +Recommendation. LinkedIn Sponsored Content as the primary, plus Google Search on category and competitor terms as secondary. Run Lead Gen Forms within LinkedIn to capture demos. Avoid Meta and TikTok early; the buying committee is on LinkedIn and at the office. Budget split: 60% LinkedIn, 30% Search, 10% test (Reddit B2B subreddits, niche newsletters). Watch CAC against the $25K ACV and a 3:1 LTV-to-CAC target. + +### Example 2: DTC adaptogenic soda, $24 AOV, US-only + +The brand has strong visual identity and an organic TikTok presence with one viral post per month. They want to scale paid. + +Recommendation. Meta (Sales objective with Catalog) as the primary. TikTok Spark Ads on the existing organic posts as the secondary. Avoid LinkedIn entirely. Avoid Search unless brand search volume justifies defensive spend. Budget split: 60% Meta, 30% TikTok, 10% test (Pinterest for visual discovery). The viral organic posts are the asset; Spark Ads recycle them at scale. Watch payback period; $24 AOV with paid CAC is razor-thin. + +### Example 3: Local home services, three-state operating area + +The team operates plumbing services across three states. They want predictable lead flow. + +Recommendation. Google Search plus Local Service Ads as the primary. Meta with geo radius as the secondary for awareness in the operating area. Avoid LinkedIn and TikTok (wrong intent). Pause off-hours unless 24-hour service is a positioning angle. Budget split: 70% Search and LSAs, 20% Meta geo, 10% test (Nextdoor where available). The geo-radius lever is the most important; a 2% mistargeting rate compounds at scale. + +### Example 4: E-commerce, 2,000 SKU catalog, $80 AOV + +The brand has a working e-commerce operation and wants to scale paid media efficiently. + +Recommendation. Google Performance Max as the primary (it includes Search, Shopping, Display, YouTube, Discover all in one). Meta Catalog Sales as the secondary. Avoid LinkedIn. Avoid Search-only campaigns; PMax already includes Search. Feed quality is the bottleneck; clean the feed (titles, categories, attributes, GTINs) before spending on PMax. Budget split: 70% PMax, 25% Meta, 5% test. Audit the geo and device cuts inside PMax weekly until the algorithm stabilizes. + +### Example 5: Pre-PMF B2B SaaS, $300K ARR, founders selling + +The team is pre-PMF. The founders are still doing all sales. They want to test paid media without burning runway. + +Recommendation. Defer paid scale. Use small Search budget ($2K to $5K per month) on category terms to capture in-market intent. Use LinkedIn organic plus founder-led content as the primary growth motion until PMF is clearer. The signal you would get from paid spend at this stage is too noisy to act on; the budget is better spent on content and outbound. Revisit paid in 6 months if PMF signals firm up. diff --git a/skills/paid-media-strategy/references/common-failures.md b/skills/paid-media-strategy/references/common-failures.md new file mode 100644 index 0000000..c60f2a8 --- /dev/null +++ b/skills/paid-media-strategy/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across paid media accounts. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. Scaling but CAC went up + +Symptom. You doubled budget on the primary audience. Conversion volume rose less than 2x. CAC drifted up by 20 to 40%. + +Root cause. Audience saturation on the primary segment. The platform finds the easiest converters first; pushing more spend into the same audience produces diminishing returns at higher cost. + +Fix. Either expand the audience (broader lookalike, additional interests, geo expansion) or diversify across channels. Do not keep pushing the same audience harder; the marginal CAC will keep climbing. + +Prevention. Project the saturation curve before scaling. If a 1.5x spend increase doubled CAC over the prior 90 days, expect another 1.5x to push CAC past your threshold. Plan the diversification before the saturation. + +--- + +## 2. Conversions look fine in the platform, terrible in revenue + +Symptom. Platform reports stable conversion volume and CAC. Revenue per conversion or LTV is dropping. + +Root cause. Attribution mismatch plus customer-quality drift. The platform optimizes for finding "any conversion." The optimizer drifts toward lower-quality converters because they are easier to find. + +Fix. Switch from conversion-count optimization to conversion-value optimization (Maximum Conversion Value or tROAS). Feed accurate conversion values into the platform. Tighten audiences toward higher-LTV proxies. + +Prevention. Track LTV cohorts per channel monthly. If channel-LTV diverges from blended LTV by more than 15%, investigate the cohort quality before defending the channel. + +--- + +## 3. A/B test winner by 5% + +Symptom. Two variations tested. One wins by 5%. The team wants to ship the winner. + +Root cause. 5% is within typical platform noise. Across-campaign tests have higher variance than statistical lift implies. + +Fix. Re-run the test with more volume. Or run it longer. Or accept that the difference is not meaningful and pick the one that is easier to maintain (cheaper to produce, easier to refresh). + +Prevention. Set the minimum detectable effect (MDE) before testing. If the test cannot detect anything below 10%, do not act on a 5% difference. + +--- + +## 4. Turned off underperformer, total conversions dropped + +Symptom. A campaign was reading as underperforming. Pause it. Total account conversions drop more than the campaign's reported conversions would suggest. + +Root cause. View-through or assist conversions you were not counting in the campaign's CAC. The campaign was contributing upper-funnel exposure that drove conversions on other campaigns. + +Fix. Restart the campaign with a held-out portion of the audience to measure incrementality. Compare the held-out cohort against the exposed cohort over 30 days. + +Prevention. Run hold-out tests, not flat off-ons. The flat-off causes a discontinuity that is hard to attribute back to the right campaign. + +--- + +## 5. Frequency hit 8 last week + +Symptom. Frequency report shows 8 impressions per user last week. CTR is dropping. + +Root cause. Creative fatigue. Audience has seen the creative too many times. + +Fix. Refresh creative. Rotate in 3 to 5 new variations. Cap frequency explicitly at 4 to 6 per week. + +Prevention. Set explicit frequency caps at campaign launch. Track frequency weekly. Refresh creative on a 30 to 60 day cadence at scale, weekly for high-frequency campaigns. + +--- + +## 6. Trying to scale Meta from $20K to $100K per day + +Symptom. Aggressive scale plan. Budget multiplier is 5x in one move. + +Root cause. That is not scaling. That is a 5x jump that will crash through the audience at the new spend level. Expect efficiency drop of 30 to 50% in the first 14 days. + +Fix. Phase the increase. 25% per week is a typical safe pace. Larger jumps should pair with audience expansion or new channels to absorb the spend. + +Prevention. Plan the scale curve before starting. 5x in a month is fine if it is 4 weekly 1.4x increases. 5x in a single move is not fine. + +--- + +## 7. LinkedIn for a B2C product + +Symptom. Tested LinkedIn for a $40 AOV consumer product. CAC came in at $200. + +Root cause. Wrong channel for the offer. LinkedIn's floor is set for B2B economics; B2C does not justify it. + +Fix. Stop. Move budget to Meta, TikTok, or Search. + +Prevention. Match channel to offer at the strategy stage. Use the channel decision matrix. Do not try platforms because "we should be on LinkedIn"; be on LinkedIn only when the math supports it. + +--- + +## 8. tROAS will not deliver + +Symptom. Set tROAS at 4.0. Platform delivers almost no impressions. + +Root cause. tROAS target is too aggressive relative to recent performance. The platform throttles delivery to almost zero rather than deliver below the floor. + +Fix. Loosen the target to 110 to 115% of the prior 30-day actual ROAS. Let the platform learn at the new target, then incrementally tighten. + +Prevention. Set tROAS based on actual recent performance, not aspirational targets. Aspirational targets shut off delivery; pragmatic targets keep volume flowing while improving efficiency. + +--- + +## 9. Search Impression Share dropped + +Symptom. Search Impression Share fell from 70% to 50% over two weeks. Conversions held but you are missing volume. + +Root cause. Either competition increased (someone else is bidding more aggressively) or budget is constrained (you ran out of daily budget at peak hours). + +Fix. Check both. Compare auction-insight reports for new entrants. Check the time-of-day spend distribution; if budget runs out at noon, raise the daily cap. + +Prevention. Track Impression Share weekly. Set alerts on 10%+ week-over-week drops. The signal is leading; conversion drops typically follow within 2 to 3 weeks. + +--- + +## 10. PMax is hard to optimize + +Symptom. Performance Max is running. CAC is fine. You want to push it harder but cannot find levers. + +Root cause. PMax is by design a black box. The platform manages placements, audiences, and creative weighting. The levers you have are budget, asset groups, and exclusions. + +Fix. Treat PMax as a tested channel with constrained levers. Optimize via asset group quality (better creative, more variants), audience signals (Customer Match, in-market lists), and exclusions (branded queries, low-value SKUs). + +Prevention. Set expectations at launch. PMax is not a place to fine-tune at the keyword level. It is a place to feed strong inputs and let the platform optimize. + +--- + +## 11. Lookalike performance dropped after expansion + +Symptom. Expanded the lookalike from 1% to 5% to add volume. CAC drifted up. + +Root cause. Wider lookalikes are looser; the floor is lower. The expansion brought in users less similar to the seed. + +Fix. Tighten back to 1 to 2% if CAC is the constraint. Or split into two ad sets: the 1% as the workhorse and the 1 to 5% as a separate scale-out audience with its own budget. + +Prevention. When you need volume, expand horizontally (add a new audience type) rather than vertically (loosen the existing audience). The horizontal expansion preserves the working audience's CAC. + +--- + +## 12. Brand search lift after a Super Bowl-style ad + +Symptom. Brand search volume jumped after a brand campaign ran. Paid attribution did not credit it. + +Root cause. Brand effect on existing demand, surfaced in organic and branded paid search rather than the brand campaign's direct-attribution column. The platform's direct response metrics did not capture it. + +Fix. Track brand-search lift as a separate metric. Define a baseline brand-search rate before the campaign. Measure the lift during and after. + +Prevention. Plan brand campaigns with brand-search lift as a primary KPI, not direct response. Direct response measurement underrates brand campaigns; using it as the only success metric kills brand investment unfairly. + +--- + +## The pattern across all twelve + +Most paid media failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale CAC at the cost of LTV. Pause an underperformer at the cost of total volume. Expand the audience at the cost of the floor. Optimize one platform without checking incrementality. + +The fix at the meta level. Decide on the success metric (CAC, ROAS, LTV-adjusted) and the guardrails (volume, frequency, creative quality, customer-cohort quality) before scaling. Audit guardrails monthly. Pull back the moment a guardrail breaks, even if the success metric still looks fine. diff --git a/skills/performance-optimization/SKILL.md b/skills/performance-optimization/SKILL.md new file mode 100644 index 0000000..1bac7fb --- /dev/null +++ b/skills/performance-optimization/SKILL.md @@ -0,0 +1,274 @@ +--- +name: performance-optimization +description: "Diagnose and fix web performance issues including Core Web Vitals (LCP, INP, CLS), bundle size, asset optimization, render performance, and runtime efficiency. Use this skill whenever the user wants to improve page speed, fix Core Web Vitals, optimize assets, reduce bundle size, debug slow renders, or systematically improve a site's performance. Triggers on performance, page speed, Core Web Vitals, LCP, INP, CLS, FID, TTFB, bundle size, code splitting, image optimization, lazy loading, render blocking, slow page, performance audit, Lighthouse score. Also triggers when traffic or conversion is dropping due to perceived slowness." +category: development +catalog_summary: "Core Web Vitals, asset optimization, render performance" +display_order: 4 +--- + +# Performance Optimization + +Diagnose web performance issues and produce a remediation plan. Stack-agnostic. Anchored to Core Web Vitals and standard browser performance patterns. + +This skill goes deeper than the performance checks in `qa-testing` and `seo-technical`. Use this when performance itself is the goal. + +--- + +## When to use + +- Fixing Core Web Vitals (LCP, INP, CLS) +- Diagnosing slow page loads +- Reducing JavaScript bundle size +- Optimizing images, fonts, and other assets +- Fixing layout shift, render-blocking resources, jank +- Pre-launch performance verification +- Annual performance health check + +## When NOT to use + +- General QA after deploys (use `qa-testing`) +- Technical SEO including indexing and crawling (use `seo-technical`) +- Code review for general bugs (use `code-review-web`) + +--- + +## Required inputs + +- The site or page under audit +- Specific performance complaints if any +- Target metrics (Core Web Vitals thresholds, Lighthouse score, custom) +- Browser dev tools access +- Performance monitoring data if available (Real User Monitoring, lab data) + +--- + +## The framework: Core Web Vitals + +Three metrics carry most of the weight for both user experience and SEO: + +### LCP (Largest Contentful Paint) + +What it measures: Time until the largest visible content element finishes rendering. + +Targets: +- Good: under 2.5 seconds +- Needs improvement: 2.5 to 4.0 seconds +- Poor: over 4.0 seconds + +Common causes of poor LCP: +- Slow server response time (TTFB over 800ms) +- Render-blocking JavaScript or CSS +- Large unoptimized images for the LCP element +- Late-loading fonts that delay text render +- Client-side rendering of the LCP element + +Common fixes: +- Server-render the LCP element (no client-side render) +- Optimize the LCP image (right format, right size, preloaded) +- Reduce render-blocking resources (defer non-critical CSS and JS) +- Use modern image formats (WebP, AVIF) +- Specify image dimensions to skip layout pass + +### INP (Interaction to Next Paint) + +What it measures: Responsiveness to user interactions. Replaces FID as the standard interactivity metric. + +Targets: +- Good: under 200ms +- Needs improvement: 200 to 500ms +- Poor: over 500ms + +Common causes of poor INP: +- Long-running JavaScript blocking the main thread +- Heavy event handlers +- Excessive React/framework re-renders +- Synchronous operations in event handlers +- Large DOM with expensive layouts + +Common fixes: +- Break long tasks into chunks (`scheduler.yield()` or `setTimeout`) +- Memoize expensive computations +- Debounce or throttle high-frequency event handlers (scroll, mousemove, input) +- Avoid synchronous storage or DOM operations in handlers +- Reduce DOM size (under 1500 elements ideal) +- Use CSS over JS for animations where possible + +### CLS (Cumulative Layout Shift) + +What it measures: How much the page jumps around as it loads. Unexpected layout shifts hurt usability. + +Targets: +- Good: under 0.1 +- Needs improvement: 0.1 to 0.25 +- Poor: over 0.25 + +Common causes of poor CLS: +- Images without explicit dimensions +- Ads, embeds, iframes that load late +- Dynamically injected content above existing content +- Web fonts causing FOIT/FOUT (flash of invisible/unstyled text) +- CSS that depends on JS-loaded data + +Common fixes: +- Always specify `width` and `height` (or `aspect-ratio`) on images and videos +- Reserve space for ads and embeds before they load +- Use `font-display: optional` or `font-display: swap` thoughtfully +- Avoid injecting content above the fold after initial render +- Preload critical fonts + +--- + +## Beyond Core Web Vitals + +### Time to First Byte (TTFB) + +The server response time. Bad TTFB makes everything else worse. + +Targets: under 800ms ideal. + +Common causes: +- Slow database queries on the request path +- N+1 query patterns +- Missing caching +- Server geographic distance from users (no CDN) +- Cold starts on serverless + +Fixes: +- Cache database queries +- Use a CDN for static and cacheable dynamic content +- Optimize critical-path queries +- Pre-render where possible (SSG, ISR) +- Edge functions for low-latency dynamic content + +### Bundle size + +JavaScript shipped to the browser. + +Targets: +- Initial JS under 170KB compressed for typical pages +- Lazy-loaded chunks under 100KB compressed each + +Common causes of bloat: +- Importing entire libraries when only one function is used +- Bundling polyfills for modern browsers +- Including dev-only code in production +- Duplicate dependencies (multiple versions of the same library) +- Large client-side state (Redux store snapshots, etc.) + +Fixes: +- Tree-shake imports (`import { fn } from 'lib'` not `import lib from 'lib'`) +- Code-split per route +- Lazy-load below-the-fold components +- Audit dependencies; replace heavy ones (e.g., moment.js → date-fns or native Intl) +- Build-time bundle analyzer to spot bloat +- Dynamic imports for rarely-used features + +### Image optimization + +Images are typically 60 to 80 percent of page weight. + +Best practices: +- Modern formats: WebP everywhere supported, AVIF where supported +- Responsive images: `srcset` for different viewport sizes +- Lazy loading: `loading="lazy"` for below-the-fold +- Explicit dimensions: prevents CLS +- Right size: don't ship 4000px images for 800px display +- LCP image: preload, never lazy-load + +### Font loading + +Web fonts often delay text render and cause CLS. + +Best practices: +- Self-host fonts (avoid third-party blocking) +- Preload critical fonts (`<link rel="preload" as="font">`) +- Use `font-display: swap` for non-critical fonts +- Subset fonts to remove unused glyphs +- Use variable fonts where possible +- Provide system-font fallback that visually matches + +### Third-party scripts + +Third parties (analytics, ads, chat widgets) often dominate performance budgets. + +Audit each: +- Is it required? +- Can it load after page interaction (defer)? +- Can it run from a worker (off main thread)? +- Is the third party itself fast? +- Are there lighter-weight alternatives? + +A common pattern: 50 percent of performance issues come from third-party scripts. + +--- + +## Workflow + +1. Establish a baseline. Lighthouse scan, WebPageTest run, or Real User Monitoring data. Capture current Core Web Vitals. +2. Identify the worst offender. LCP, INP, or CLS - which is failing? Focus there first. +3. Diagnose specifically. Browser dev tools (Performance tab, Network tab, Coverage tab). Identify the actual cause of the metric failure. +4. Plan fixes. Per identified issue, plan a specific change. Estimate impact and effort. +5. Implement. One fix at a time where possible. Easier to measure impact. +6. Re-measure. After each major fix, re-run Lighthouse and check Real User Monitoring. +7. Iterate. Performance is rarely solved in one pass. Plan for ongoing monitoring and fixes. + +--- + +## Tools + +Lab tools (run on demand): +- Lighthouse (built into Chrome DevTools) +- PageSpeed Insights (online) +- WebPageTest (online, more configurable) +- Browser Performance tab (deep flame graph analysis) + +Field tools (real user data): +- Chrome User Experience Report (CrUX) - public data for any site +- Real User Monitoring (RUM) - your own users (DataDog, New Relic, custom, etc.) +- Search Console Core Web Vitals report + +Lab tools are useful for diagnosis. Field tools are the source of truth for what users actually experience. + +--- + +## Failure patterns + +- Optimizing without measuring. Performance theater without baseline metrics. Always measure first. +- Optimizing the wrong metric. A great Lighthouse score with bad real-user metrics means your test conditions don't match users. +- Over-optimizing. Spending weeks shaving 10ms off TTFB while CLS is 0.4. Fix the worst offender first. +- Lighthouse-driven optimization only. Lighthouse runs in idealized conditions. Always check field data. +- Single-page optimization. Performance regressions creep in across the codebase. Build performance budgets and CI checks. +- Treating every byte as equal. A render-blocking 100KB script is worse than a deferred 500KB script. +- Bundle size obsession. Bundle size matters, but execution time matters more. A small bundle that takes 5 seconds to parse is worse than a larger bundle that runs fast. +- Ignoring third parties. "It's the analytics tag, not us." Third parties run on your domain in your users' eyes. Own them. + +--- + +## Output format + +Default output is a performance report at `performance-audit.md`. + +Structure: +1. Executive summary +2. Methodology (tools, conditions, sample pages) +3. Current state (Core Web Vitals, Lighthouse scores, RUM data) +4. Critical issues (Core Web Vitals failures) +5. Important issues (sub-optimal but not failing) +6. Polish (further-than-required wins) +7. Remediation roadmap (sequenced) +8. Performance budget recommendations +9. Monitoring plan + +For complex audits, include: +- Per-page Lighthouse exports +- Bundle analysis output +- Network waterfall screenshots +- Specific code snippets to change + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Full performance audit report template. +- [`references/optimization-checklist.md`](references/optimization-checklist.md) - Quick-reference checklist of common optimizations by priority. +- [`references/optimization-playbook.md`](references/optimization-playbook.md) - Symptom-to-fix playbook for the common Core Web Vitals problems (LCP, INP, CLS). diff --git a/skills/performance-optimization/references/audit-template.md b/skills/performance-optimization/references/audit-template.md new file mode 100644 index 0000000..a4b256a --- /dev/null +++ b/skills/performance-optimization/references/audit-template.md @@ -0,0 +1,203 @@ +# Performance Audit Report + +A fillable template for documenting a web performance audit. Fill every section. Empty sections signal an incomplete audit. + +The output is the report. The report is what the team acts on. Weak reports produce no fixes. + +--- + +## Audit metadata + +Site / app: [Name and URL] +Pages audited: [List the specific URLs, not "the site"] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Devices and conditions tested: +- Mobile: [Device class, network throttling] +- Desktop: [Network throttling] +- Geographies: [If multi-region tested] +Tools used: [Lighthouse, WebPageTest, Chrome DevTools, real-user data source, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall state of performance. +2. Whether the site passes Core Web Vitals at the 75th percentile. +3. The single biggest issue and what it costs. +4. The recommended next move. +5. Estimated effort and impact for the top fix. + +> [Summary] + +--- + +## Core Web Vitals scorecard + +Use field data (CrUX, RUM) where available. Lab data (Lighthouse) is a fallback and a diagnostic, not a final verdict. + +\| Metric \| Target (good) \| Mobile p75 \| Desktop p75 \| Status \| +\|---\|---\|---\|---\|---\| +\| LCP (Largest Contentful Paint) \| < 2.5s \| \| \| Pass / Needs work / Fail \| +\| INP (Interaction to Next Paint) \| < 200ms \| \| \| Pass / Needs work / Fail \| +\| CLS (Cumulative Layout Shift) \| < 0.1 \| \| \| Pass / Needs work / Fail \| +\| TTFB (Time to First Byte) \| < 800ms \| \| \| Pass / Needs work / Fail \| +\| FCP (First Contentful Paint) \| < 1.8s \| \| \| Pass / Needs work / Fail \| + +### Trend + +- [ ] Improving over the past 28 days +- [ ] Stable +- [ ] Regressing + +### Field data source + +[CrUX history, Search Console, Sentry, RUM tool. Note the date range and traffic volume that the data covers.] + +--- + +## Page-level findings + +For each audited page, fill out: + +### Page: [URL or template name] + +Type: [Marketing / product / app shell / API-driven] +Traffic share: [Rough % of site traffic] +Field metrics (if available): +- LCP p75: +- INP p75: +- CLS p75: + +#### Lab metrics (Lighthouse mobile, slow 4G) + +- Performance score: +- LCP: +- INP (or TBT as proxy): +- CLS: +- Total page weight: +- Total requests: +- JS payload (parsed): + +#### Top issues on this page + +\| # \| Issue \| Impact metric \| Severity \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| LCP / INP / CLS / TTFB \| High / Med / Low \| S / M / L \| +\| 2 \| \| \| \| \| +\| 3 \| \| \| \| \| + +(Repeat the page block for each audited page.) + +--- + +## Cross-cutting findings + +Issues that affect many pages or the whole site. Often higher leverage than per-page fixes. + +### Asset pipeline + +- [ ] Images served in modern formats (WebP, AVIF)? +- [ ] Images served at appropriate sizes (responsive `srcset`)? +- [ ] Critical above-the-fold images preloaded? +- [ ] Below-the-fold images lazy-loaded? +- [ ] Video uses `preload="none"` or poster image until interaction? +- [ ] Fonts subsetted, woff2, `font-display: swap` (or `optional` for stable layout)? +- [ ] Self-hosted vs third-party fonts considered? + +### JavaScript + +- [ ] Bundle size budget defined? +- [ ] Code splitting per route? +- [ ] Third-party scripts inventoried, justified, and budgeted? +- [ ] Unused JavaScript flagged (Coverage tab in DevTools)? +- [ ] Long tasks (>50ms) inventoried? + +### CSS + +- [ ] Render-blocking CSS minimized? +- [ ] Critical CSS inlined for above-the-fold? +- [ ] Unused CSS flagged? + +### Server / network + +- [ ] HTTPS, HTTP/2 or HTTP/3 enabled? +- [ ] Compression (Brotli or gzip) enabled for text assets? +- [ ] Cache headers correct for static assets (long max-age, immutable)? +- [ ] CDN in front of origin? +- [ ] Origin response time (TTFB) measured and acceptable? + +### Layout stability + +- [ ] Images and embeds have explicit `width` and `height` (or `aspect-ratio`)? +- [ ] No layout shift from late-loading fonts? +- [ ] No layout shift from injected ads or banners? + +### Interactivity + +- [ ] Main-thread blocking under 200ms p75? +- [ ] Heavy listeners debounced or moved off main thread? +- [ ] Hydration cost measured (for SSR / partially hydrated frameworks)? + +### Third-party scripts + +\| Vendor \| Purpose \| Bytes \| Main-thread cost \| Necessary? \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| + +--- + +## Recommendations + +Prioritized action list. Each item is concrete, owned, and sized. + +### Now (this week) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Next (this sprint or month) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Later (this quarter or beyond) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| + +--- + +## Monitoring and re-test plan + +- Re-test cadence: [When will the audit be re-run?] +- Field data tracking: [Where will Core Web Vitals be tracked over time? CrUX dashboard, RUM tool, Search Console.] +- Performance budget: [Define and link the budget. Example: LCP under 2.0s p75 mobile, JS payload under 200KB compressed per route.] +- Alert thresholds: [When does someone get paged?] +- Owner of ongoing performance: [Person or team] + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- Lab tests run: [Tool, settings, run count] +- Field data window: [Date range, traffic volume] +- Throttling profile: [Slow 4G, Fast 3G, etc.] +- Geographies tested: [List] +- Caveats: [Anything that limits the audit's confidence, e.g., no field data, low traffic, single-page sample] diff --git a/skills/performance-optimization/references/optimization-checklist.md b/skills/performance-optimization/references/optimization-checklist.md new file mode 100644 index 0000000..3c53a5a --- /dev/null +++ b/skills/performance-optimization/references/optimization-checklist.md @@ -0,0 +1,138 @@ +# Performance Optimization Checklist + +Quick-reference checklist of common performance optimizations, ordered by typical impact-per-effort. Use it as a triage list, not a script. Skip what does not apply. + +For symptom-to-fix walkthroughs, see `optimization-playbook.md`. For a structured audit report, see `audit-template.md`. + +--- + +## P0: blocks Core Web Vitals at the 75th percentile + +These optimizations almost always pay back. If a site is failing CWV, start here. + +### Images + +- [ ] LCP image is preloaded with `<link rel="preload" as="image" fetchpriority="high">` +- [ ] LCP image is NOT lazy-loaded +- [ ] Images use modern formats (WebP, AVIF) with fallback +- [ ] Images use responsive `srcset` with appropriately sized variants +- [ ] All `<img>` and `<video>` tags have explicit `width` and `height` (or `aspect-ratio` CSS) +- [ ] Below-the-fold images use `loading="lazy"` +- [ ] Decorative images use `decoding="async"` + +### Fonts + +- [ ] Web fonts use `font-display: swap` (or `optional` for layout stability) +- [ ] Font files are woff2 and subsetted to actual glyphs used +- [ ] Critical font files are preloaded +- [ ] Preconnect to font origin if hosted off-domain + +### JavaScript on the critical path + +- [ ] No render-blocking scripts in `<head>` (use `defer` or `async` or move to `<body>` end) +- [ ] Heavy third-party scripts (chat widgets, A/B test tools, analytics) are deferred until interaction or after load +- [ ] Bundle size budget enforced per route +- [ ] Code split per route or feature +- [ ] Unused JavaScript removed (Coverage tab in DevTools) + +### Layout stability + +- [ ] No content insertion above the fold after initial render (banners, ads, popups) +- [ ] Skeleton states or placeholders prevent layout shift on async content +- [ ] Avoid `@font-face` with no fallback chain +- [ ] Avoid web fonts that change metrics significantly between fallback and loaded state (use `size-adjust` and `ascent-override`) + +--- + +## P1: significant gains, moderate effort + +### Server and network + +- [ ] HTTP/2 or HTTP/3 enabled +- [ ] Brotli compression enabled (or gzip if Brotli unavailable) +- [ ] Cache headers correct for static assets: long `max-age` and `immutable` for hashed files +- [ ] CDN in front of origin for static assets (and dynamic where applicable) +- [ ] Origin response time (TTFB) under 800ms at p75 +- [ ] DNS prefetch and preconnect for critical third-party origins + +### Rendering strategy + +- [ ] Above-the-fold content is server-rendered (or static) where possible +- [ ] Critical CSS inlined for above-the-fold +- [ ] Non-critical CSS loaded asynchronously +- [ ] Partial / progressive hydration considered for heavy SPA pages + +### Resource loading + +- [ ] `<link rel="preload">` used for critical assets only (overuse hurts) +- [ ] `<link rel="modulepreload">` used for ESM critical chunks +- [ ] Resource hints (`prefetch`, `prerender`) used for likely next pages on key flows + +### Long tasks + +- [ ] Main-thread tasks over 50ms identified and broken up (`scheduler.yield()`, `requestIdleCallback`, web workers) +- [ ] Hydration cost measured for SSR sites; large components hydrated lazily + +--- + +## P2: smaller gains, useful in aggregate + +### Images and media + +- [ ] Hero video uses `preload="none"` or poster image until interaction +- [ ] Animated GIFs replaced with looped video (smaller, smoother) +- [ ] SVGs optimized (SVGO) and inlined where small +- [ ] Image delivery service (Cloudinary, ImgIX, native CDN image transform) used for on-the-fly resizing + +### Third-party scripts + +- [ ] Each third-party script audited: necessary, budgeted, and optimized +- [ ] Tag manager rules audited; remove unfired or duplicate tags +- [ ] Self-host third parties where licensing allows and origin caching helps + +### CSS + +- [ ] Unused CSS removed +- [ ] CSS specificity audited; avoid expensive selectors (deeply nested, universal) +- [ ] `will-change` and `transform`/`opacity` animations preferred over animating layout properties + +### JavaScript + +- [ ] Tree shaking confirmed working (check final bundle for dead code) +- [ ] Polyfills served only to browsers that need them (differential serving, `module/nomodule` pattern) +- [ ] Date / time / number formatting uses `Intl` instead of large libraries +- [ ] Heavy utility libraries replaced with smaller alternatives or native code where reasonable + +--- + +## P3: polish + +- [ ] Service worker caches critical assets for repeat visits +- [ ] Speculation Rules API used for likely next-page prerender +- [ ] HTTP early hints (103) used for critical preloads +- [ ] Server timing headers exposed for diagnostic visibility +- [ ] Real user monitoring (RUM) feeds CWV dashboard + +--- + +## Anti-patterns to remove + +These appear often, hurt always, and warrant a same-day fix. + +- [ ] Lazy-loaded LCP image +- [ ] Render-blocking analytics or tag manager in `<head>` without `async` +- [ ] Multiple competing fonts (more than 2 families or more than 4 weights) +- [ ] CSS-in-JS that ships runtime style generation to the client without static extraction +- [ ] Hero image larger than its rendered size by more than 2x +- [ ] Synchronous third-party scripts above any user-visible content +- [ ] Layout-shifting cookie banner or consent modal +- [ ] Background images that are CSS-loaded above the fold (preload friendlier as `<img>`) + +--- + +## How to use this checklist + +1. Run a Lighthouse + CrUX read of the 3-5 most important pages. +2. Walk this checklist top to bottom for each page. Mark passes, gaps, and not-applicable. +3. Triage gaps into the audit report (`audit-template.md`) under Now / Next / Later. +4. Re-test after each fix lands. Performance is a moving average, not a snapshot. diff --git a/skills/performance-optimization/references/optimization-playbook.md b/skills/performance-optimization/references/optimization-playbook.md new file mode 100644 index 0000000..b0419cf --- /dev/null +++ b/skills/performance-optimization/references/optimization-playbook.md @@ -0,0 +1,300 @@ +# Optimization Playbook + +A step-by-step playbook for common performance problems. Pick the symptom, follow the steps. + +--- + +## Symptom: LCP failing (>2.5s) + +The largest content element on the page takes too long to paint. + +### Step 1: Identify the LCP element + +In Chrome DevTools Performance panel: +1. Record a page load +2. Find the LCP marker +3. Note which element is the LCP (usually a hero image or large heading) + +### Step 2: Optimize that specific element + +If LCP element is an image: +- Use modern format (WebP, AVIF) +- Serve appropriately sized version (don't ship a 4000px image to a 800px container) +- Preload it: `<link rel="preload" as="image" href="hero.webp" fetchpriority="high">` +- Avoid lazy-loading the LCP image (use eager loading) +- Use `fetchpriority="high"` on the image element + +If LCP element is text/heading: +- Ensure web fonts don't block rendering (`font-display: swap`) +- Inline critical CSS for the heading section +- Preconnect to font origin: `<link rel="preconnect" href="https://fonts.example.com">` + +If LCP is loading slowly because the page is slow overall: +- See "Symptom: TTFB slow" below +- Reduce render-blocking resources +- Reduce total payload before LCP element + +### Step 3: Measure + +Re-test in Lighthouse and DevTools. Verify LCP under 2.5s on a slow connection (Slow 4G simulation in DevTools). + +--- + +## Symptom: INP failing (>200ms) + +Interactions feel sluggish. The page takes too long to respond to user input. + +### Step 1: Find the slow interactions + +In Chrome DevTools Performance panel: +1. Record while clicking, typing, or interacting +2. Look for long tasks (orange bars >50ms) following input events +3. Identify the function calls that take the longest + +### Step 2: Reduce the work + +For event handlers: +- Move heavy work out of the synchronous path +- Use `setTimeout` or `requestIdleCallback` to yield to the main thread +- Debounce or throttle frequent events (scroll, mouse move, resize) + +For component re-renders (React, Vue, etc.): +- Memoize expensive computations +- Avoid creating new objects/arrays/functions in render that get passed as props +- Use virtualization for large lists (react-window, virtua, or framework equivalent) +- Profile to find which components re-render and why + +For startup hydration (SSR/SSG frameworks): +- Defer hydration of non-critical components +- Use island architecture or partial hydration where supported +- Code-split aggressively below-the-fold + +### Step 3: Verify + +INP should be under 200ms at the 75th percentile of real user data. + +--- + +## Symptom: CLS failing (>0.1) + +Content jumps around as the page loads. + +### Step 1: Identify the shifts + +In Chrome DevTools: +1. Open Performance Insights or Performance panel +2. Look for "Layout Shifts" markers +3. Click each to see what shifted + +### Step 2: Reserve space for dynamic content + +Common offenders and fixes: + +- Images without dimensions. Add `width` and `height` attributes (or `aspect-ratio` CSS). +- Late-loading ads or embeds. Reserve a fixed-size container. +- Web fonts swapping. Use `font-display: optional` or size-adjust descriptors. +- Skeleton loaders that don't match final size. Match dimensions exactly. +- Animations triggering layout. Animate only `transform` and `opacity`. +- Insertion of content above existing content. Reserve space or insert below. + +### Step 3: Verify + +Run Lighthouse. Real-user CLS at 75th percentile should be under 0.1. + +--- + +## Symptom: TTFB slow (>800ms) + +Server takes too long to respond. + +### Step 1: Check the server response + +Use WebPageTest or `curl -w "@curl-format.txt" -s -o /dev/null https://example.com` to measure just TTFB. + +### Step 2: Identify the bottleneck + +Common causes: + +- No caching at the edge. Add a CDN. Set Cache-Control headers correctly. +- Slow database queries. Run EXPLAIN on slow queries. Add indexes. Eliminate N+1 patterns. +- Slow third-party API calls in the render path. Defer to client or precompute. +- Heavy server-side rendering. Profile the SSR work. Memoize what's repeated. +- Cold starts (serverless). Provisioned concurrency or warming pings. + +### Step 3: Verify + +TTFB under 600ms at the 75th percentile is the target. Under 200ms is excellent. + +--- + +## Symptom: Bundle size too large + +JavaScript payload bloating the page. + +### Step 1: Audit the bundle + +Run a bundle analyzer (Webpack Bundle Analyzer, source-map-explorer, etc.). Sort by size. + +### Step 2: Identify the offenders + +Common bloat sources: + +- Unused dependencies. Tree-shaking missing or broken. +- Whole-library imports. `import { debounce } from 'lodash'` pulls all lodash. Use `import debounce from 'lodash/debounce'`. +- Polyfills shipped to modern browsers. Use differential serving. +- Source maps in production bundle. Should be separate files, not inline. +- Moment.js, Lodash, jQuery. Often replaceable with smaller alternatives or native APIs. +- Multiple versions of the same library. Check `npm ls [library]`. Dedupe. + +### Step 3: Reduce + +- Replace heavy libraries with lighter alternatives (date-fns or dayjs instead of moment, native fetch instead of axios) +- Code-split routes +- Code-split heavy components (modals, charts, editors) +- Use dynamic imports for below-the-fold features + +### Step 4: Set a budget + +In your build config or CI, fail builds that exceed the budget. + +--- + +## Symptom: Image-heavy page loads slowly + +### Step 1: Audit images + +- Count images on the page +- Note current sizes and formats +- Note which are above-the-fold (eagerly loaded) vs below (should be lazy) + +### Step 2: Optimize each + +Format: +- Photos: WebP or AVIF (with JPEG fallback) +- Graphics: SVG or PNG (with WebP fallback) +- Animations: video (MP4/WebM) instead of GIF for size + +Sizing: +- Generate multiple sizes via `srcset` +- Use `sizes` attribute to tell the browser the rendered size + +```html +<img + src="hero-800.webp" + srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1600.webp 1600w" + sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1600px" + width="1600" + height="900" + alt="Description" + loading="eager" + fetchpriority="high" +/> +``` + +For below-the-fold: +- `loading="lazy"` +- Without `fetchpriority` + +Compression: +- Use a build-time image pipeline (sharp, imagemin) to compress automatically +- Quality 75-85 is usually invisible to users while halving file size + +--- + +## Symptom: Web fonts blocking text + +### Step 1: Audit font loading + +In DevTools Network tab, filter by font. Note: +- File size +- When they load relative to first paint +- Whether text is invisible or fallback during load + +### Step 2: Optimize + +- Use `font-display: swap` to show fallback text immediately +- Subset fonts to only the characters needed (Latin only is much smaller than full Unicode) +- Self-host critical fonts instead of CDN where possible +- Preload critical fonts: + ```html + <link rel="preload" href="/fonts/regular.woff2" as="font" type="font/woff2" crossorigin> + ``` +- Use `size-adjust`, `ascent-override`, `descent-override` in `@font-face` to match metrics with fallback fonts (reduces CLS) + +--- + +## Symptom: Third-party scripts dragging performance + +### Step 1: Inventory third-parties + +In DevTools Network tab, list all third-party domains. For each: +- Size +- Blocking or non-blocking? +- Necessary? + +### Step 2: Decide on each + +For every third-party script, ask: does the business value justify the performance cost? + +Common offenders: +- Heavy analytics (audit if all pixels are necessary; consider server-side tagging) +- Customer support chat widgets (load on user intent, not on page load) +- A/B testing tools (defer non-critical experiments) +- Multiple ad networks (consolidate) +- Tag managers loading hundreds of tags + +Fixes: +- Remove unused tags +- Defer non-critical scripts (`async` or `defer`) +- Self-host where licensing allows (avoids extra DNS lookup) +- Load chat widgets on user interaction, not on page load +- Consolidate analytics where possible + +### Step 3: Set a third-party budget + +Number of third-party domains, total third-party JS payload. Block-add for new third-parties without explicit performance review. + +--- + +## Performance budget template + +Set hard limits in your CI to prevent regression: + +```yaml +budget: + - resourceSizes: + - resourceType: total + budget: 500 # kilobytes + - resourceType: script + budget: 200 + - resourceType: image + budget: 200 + - resourceType: stylesheet + budget: 50 + - resourceType: font + budget: 100 + - resourceType: third-party + budget: 100 + - timings: + - metric: largest-contentful-paint + budget: 2500 # milliseconds + - metric: cumulative-layout-shift + budget: 0.1 + - metric: total-blocking-time + budget: 200 +``` + +Tools like Lighthouse CI, Calibre, or SpeedCurve can enforce these budgets in CI. + +--- + +## When to call it done + +A page is "performance optimized" when: + +1. Real-user Core Web Vitals at 75th percentile pass thresholds +2. Lighthouse performance score >90 on representative pages +3. Performance budgets enforced in CI +4. Periodic re-audit scheduled (quarterly minimum) + +Performance is not a one-time project. New code adds weight. New features add complexity. Plan for ongoing maintenance. diff --git a/skills/pillar-content-architecture/SKILL.md b/skills/pillar-content-architecture/SKILL.md new file mode 100644 index 0000000..a0bf78d --- /dev/null +++ b/skills/pillar-content-architecture/SKILL.md @@ -0,0 +1,260 @@ +--- +name: pillar-content-architecture +description: "How to design a content hub that earns topical authority. Pillar topic selection, cluster planning, internal linking architecture, URL structure, pillar and cluster page anatomy, topical authority signals for SEO and AEO/GEO, and the maintenance discipline that distinguishes intentional hubs from accidental orphans. Triggers on pillar content, content hub, topic cluster, topical authority, content architecture, hub and spoke, pillar page, cluster page, content silo, internal linking strategy. Also triggers when a content set is not ranking despite individual piece quality, when a pillar was launched without a cluster, or when content has accumulated without an architecture." +category: content +catalog_summary: "Hub-level content architecture: pillar topic selection, cluster planning, internal linking, URL structure, pillar and cluster page anatomy, topical authority signals, refresh discipline" +display_order: 1 +--- + +# Pillar Content Architecture + +A senior content architect's playbook for designing content hubs that earn topical authority. + +Most content programs accumulate accidentally. Pieces ship one at a time, internal linking happens (or does not) in editing, similar topics get covered by multiple pieces with no coordination, and six months later the team has a content set that looks like a sitemap but feels like a yard sale. Search engines see disconnected pages; AI engines see scattered citations; readers cannot tell which piece is the entry point and which is the reference. + +This skill is the discipline of intentional hub architecture. It assumes you have decided which topic areas to invest in (see `content-strategy`) and have keyword data (see `seo-keyword`). It does not write any individual piece (see `content-brief-authoring` for per-piece work and `content-and-copy` for execution). What it does is design the structure: which topic gets a pillar, which subtopics get cluster pieces, how the pieces link to each other, where they live in the URL hierarchy, and what topical authority signals the architecture is engineered to produce. + +When to use this skill: launching a new content hub, restructuring an existing content set into a hub, deciding whether a piece should be a pillar or a cluster, or auditing why a content area is not ranking despite individual piece quality. + +--- + +## What this skill is for + +This skill spans hub-level content architecture. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: multiple topic pillars, editorial calendar, governance, formats. Decides what topic areas to invest in across a quarter or year. +- `seo-keyword` is upstream-input: keyword research that surfaces candidate pillar topics with volume, difficulty, and intent data. +- This skill is hub-scope: one pillar plus its cluster, the architecture that ties them together. The structural decisions, not the per-piece content. +- `content-brief-authoring` is per-piece scope: brief for one content artifact. Each cluster piece (and the pillar itself) gets briefed via that skill. +- `content-and-copy` is execution scope: writing the piece itself. +- `seo-content-gap-audit` is audit-side: finds missing pieces in an existing content set after the fact. This skill prevents the gaps; that skill catches the ones that emerge. + +The clean composition: `content-strategy` decides which topics, `seo-keyword` surfaces opportunities, this skill designs the hub, `content-brief-authoring` briefs each piece, `content-and-copy` writes each piece, `seo-content-gap-audit` later catches what slipped. Six skills, sequential. + +The audience: SEO content strategists, content architects, in-house teams designing content hubs, agencies running topical authority programs. The voice is senior content architect to junior content marketer. Concrete, opinionated, honest about what makes a hub earn authority versus decorate the sitemap. + +--- + +## Pillar vs cluster vs orphan content + +The keystone distinction. Three categories of content in any program. + +Pillar. Comprehensive piece covering a major topic area. 2,500 to 5,000 words plus. Anchors the topical authority claim for the topic. Receives links from cluster pieces; links out to cluster pieces selectively, not as a footer dump. The pillar is the entry point for the topic and the reference the cluster orbits. + +Cluster. Narrower piece covering a specific facet of the pillar topic. 800 to 2,000 words. Links up to pillar; may link sideways to other clusters in the same hub when a connection is natural. Each cluster answers one specific question within the pillar's scope. + +Orphan. Piece that does not connect to a pillar or cluster. May rank or convert on its own merits, but does not compound into topical authority. Some orphans are fine by design (release-note pages, customer stories, one-off campaigns); most orphans are accidents. + +The pathology. Most content programs are 80% orphans, 15% accidental clusters, 5% accidental pillars. The discipline is moving toward 70% intentional clusters, 20% intentional pillars, 10% standalone-by-design. Same total content volume; different architectural outcome. + +The reading model. Search engines and AI engines both read internal-link graphs to infer topical authority. A pillar with 12 well-linked cluster pieces signals depth on a topic. 12 orphans on the same topic signal scattered, less-authoritative coverage. The architecture is the signal. + +Detail and decision tree in [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md). + +--- + +## Topic selection for pillar pages + +Not every topic deserves a pillar. The five-criterion selection framework: + +1. Search volume justifies the investment. Pillar topic has enough monthly volume to support a 3,000 to 5,000-word effort plus 8 to 15 cluster pieces. Sub-100 monthly searches usually does not. +2. Topic has natural facets. You can identify 8 to 15 distinct subtopics that could each be their own piece. If you can only think of 3, it is probably a cluster, not a pillar. +3. Commercial relevance. The topic connects to your business model. A pillar without commercial signal is content marketing for content marketing's sake. +4. Competitive feasibility. Top 10 SERP for the pillar keyword is achievable. If the SERP is dominated by Wikipedia, government sites, and Fortune 500 brands, your pillar will rank position 47 no matter how good it is. +5. Editorial commitment. The team will maintain the pillar (refresh annually, add new clusters, update statistics). Pillars are not ship-and-forget; they are 5-year commitments. + +The "everything is a pillar" anti-pattern. Teams call any 3,000-word piece a pillar. Length does not make a pillar. The architecture does. Pillar is the role a piece plays in the hub structure, not the word count. + +Detail in [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md). + +--- + +## Cluster planning + +Once a pillar is selected, plan its cluster: + +1. Cluster size. Typically 8 to 15 pieces for a strong hub. Below 5 reads thin; above 25 becomes unmanageable; sweet spot is 10 to 12. +2. Cluster facets. Each cluster piece covers one facet of the pillar topic. Facets are surfaced from keyword research (long-tail variations of pillar keyword), "people also ask" data, sub-headings in top-ranking pillar pages on the SERP, competitor cluster maps, and first-party customer questions (sales calls, support tickets). +3. No facet duplication. Two cluster pieces should not target overlapping queries. If they do, consolidate to one piece. +4. Cluster heterogeneity. Clusters should cover the topic from multiple angles (definition, how-to, comparison, examples, common mistakes, costs, alternatives, case studies) rather than 12 variations of "what is X." +5. Sequence. Ship pillar first (or alongside the first 3 to 5 clusters). The link graph will not form without the pillar in place; clusters that link to a non-existent pillar are orphans-in-waiting. + +Detail in [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md). + +--- + +## Internal linking architecture + +The hub's internal-link graph is what actually produces topical authority signals. The architecture has three directions: + +Pillar to cluster (top-down). Pillar links out to each cluster piece via contextual anchors, typically once per cluster from within the pillar's body. Do not bury cluster links in a "related reading" footer; weave them into the relevant section of the pillar where the reader's curiosity peaks. + +Cluster to pillar (bottom-up). Every cluster piece links up to the pillar at least once, typically in the first 200 words and again in the closing section. Bottom-up is the discipline that makes the pillar compound; without it the pillar is just a long article. + +Cluster to cluster (lateral). Selective lateral linking when one cluster naturally references another. Do not force lateral links; an "everyone links to everyone" cluster is messy and dilutes anchor text relevance. + +Anchor text discipline. Vary the anchor text. "Click here" is dead; exact-match keyword stuffing is dead; descriptive natural-language anchors are alive. The brief for each piece (see `content-brief-authoring`) specifies anchor text per outbound link. + +The "linking inventory" pattern. Maintain a sheet (or database row, or dbt model) tracking every link in the hub, who links to whom, and the anchor text used. Audit quarterly to catch broken links, anchor-text drift, and missing connections that should exist. + +Detail in [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md). + +--- + +## URL structure and information architecture + +URL patterns matter for both crawl clarity and reader navigation. Decision factors: + +Subfolder vs subdomain. Subfolder is the default (`example.com/hub-topic/cluster-piece`) for SEO consolidation; both pillar and cluster live on the same domain authority. Subdomain is appropriate only for genuinely distinct properties (`docs.example.com`, `community.example.com`). + +Hub URL pattern. `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. Avoid `/blog/cluster-piece/` if the goal is hub authority; the URL itself signals topical grouping to crawlers and readers. + +Slug conventions. Short, descriptive, keyword-aware but not stuffed. `/seo-content-strategy/keyword-research-for-pillars/` not `/the-ultimate-guide-to-seo-content-strategy-keyword-research-for-pillar-pages-2026/`. + +Breadcrumbs. Surface the hub structure in breadcrumb navigation. Helps readers see where they are; helps crawlers see the hierarchy. + +The "/blog/ trap." Teams put pillar and clusters under `/blog/` because that is where the CMS folder is. This works structurally but loses the URL signal that says "these pieces belong together as a topical hub." + +Detail in [`references/url-structure-patterns.md`](references/url-structure-patterns.md). + +--- + +## Pillar page anatomy + +A pillar page does specific work. The standard sections: + +- Hero. Defines the topic, signals scope ("The complete guide to X for Y audience"), establishes authority quickly. +- TL;DR or executive summary. 150 to 250 words at the top. AI engines often cite this section verbatim. Treat it as the citation-ready summary, not as a marketing intro. +- Comprehensive body. Covers the topic's major facets, with internal-link callouts to cluster pieces for deep dives. The body is not a comprehensive treatment of every facet; it is a guided tour with depth links. +- Use cases or examples. Anchor the abstract topic to concrete instances. +- Common mistakes / FAQ. AI-citation friendly section with structured Q&A. Pair with FAQ schema markup. +- Closing or next steps. Directs reader into the cluster (which piece to read next based on intent). +- Schema markup. Article or HowTo schema depending on intent; FAQPage schema for the FAQ section. + +Pillar length. 3,000 to 5,000 words is the typical range. Pillar quality is comprehensiveness AND depth, not just word count. A 6,000-word pillar that covers 3 facets is worse than a 4,000-word pillar that covers 12 facets. + +Detail in [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md). + +--- + +## Cluster piece anatomy + +Cluster pieces have a different shape: + +- Hero. Focused on one specific question or task, not broad. +- Pillar callout. Link up to pillar in the first 200 words. Typical phrasing: "This piece covers X. For the broader context on Y, see our guide to [pillar topic]." +- Focused body. Answers the specific question with depth, but does not expand into adjacent facets (those have their own cluster pieces). +- Lateral callouts (selective). When relevant, link to 1 or 2 sibling cluster pieces. +- Closing. Link back to pillar OR to the next logical cluster piece in a reader journey. + +Cluster length. 800 to 2,000 words typical. A cluster piece longer than 2,500 words is probably a mini-pillar that should either get promoted to its own pillar or be split into two cluster pieces. + +Detail in [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md). + +--- + +## Topical authority signals + +Signals that make hub architecture compound into authority. The two-engine view: pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +SEO signals: + +- Internal-link graph density on the topic (PageRank flow within the hub) +- Comprehensive entity coverage across pillar plus clusters (mentioned entities, statistics, citations) +- URL structure clarity +- Breadcrumb hierarchy +- Schema markup (Article, HowTo, FAQPage as appropriate) +- E-E-A-T signals: author credentials, expertise demonstrated, trust signals on every piece + +AEO and GEO signals: + +- Answer-paragraph format directly under H2 headings (40 to 60 words, citation-ready) +- TL;DR section on pillars (highly citable; AI engines extract it verbatim) +- FAQ schema (still cited heavily by AI engines including Perplexity and ChatGPT) +- Specific statistics with cited sources +- Named experts and named methods (entities AI engines weight heavily for citation) +- Distinctive POV that AI engines can attribute to your brand + +The two-engine optimization is complementary, not competing. Both reward depth, structure, and entity coverage. The hub architecture creates more surface area for both signal types than scattered orphan content can. + +Detail in [`references/topical-authority-signals.md`](references/topical-authority-signals.md) and the `seo-aeo-geo` skill for AEO/GEO strategy at the program level. + +--- + +## Maintenance and refresh patterns + +Hubs decay if not maintained. The discipline: + +- Annual pillar refresh. Every 12 months, audit the pillar against current SERP, update statistics, add new sections for emerged facets, prune sections that no longer matter, refresh internal-link callouts to cluster pieces (since the cluster has likely grown). +- Cluster refresh as triggered. Clusters refresh when keyword performance drops, when a new sub-topic emerges, or when a cluster's links go stale. +- Cluster expansion. Add new cluster pieces as the topic surfaces new facets. A hub at year 1 might have 8 clusters; year 3 could have 18. +- Cluster pruning. Kill cluster pieces that fail to rank or get cited after 12 months. Redirect to the most-relevant remaining cluster or to the pillar. Pruning is not failure; it is hygiene. +- Hub lifecycle. Hubs themselves have a lifespan. After 5 to 7 years, even mature hubs may need wholesale restructuring as the topic landscape shifts. + +The "set and forget" failure. Hub launches, ranks, drives traffic for 2 years, then decays without anyone noticing because nobody owns the hub long-term. Hub ownership is durable: single owner across 3 to 5 year horizons, not "the team that launched it." + +Detail in [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pillar-failures.md`](references/common-pillar-failures.md). + +- "We have 80 blog posts but no rankings." Orphan content; no hub architecture. +- "Our 8,000-word pillar does not rank." Comprehensive but no cluster support; pillar without a hub is just a long article. +- "We launched the pillar, never built the cluster." Architecture half-built signals nothing. +- "Cluster pieces do not link to the pillar." Top-down link graph but no bottom-up; the pillar does not compound. +- "Two cluster pieces target the same keyword." Self-cannibalization; consolidate. +- "Pillar URL is /blog/the-ultimate-guide-to..." Losing the URL hub signal. +- "Our pillar is 12 sections of 'what is X'." Facet homogeneity; covers one angle 12 ways. +- "We cannot tell which piece to refresh first." No maintenance ownership; no signals being tracked. +- "Pillar ranks but does not get cited by AI engines." Missing AEO/GEO signals (no TL;DR, no answer paragraphs, no FAQ schema). +- "Hub launched 3 years ago; nobody owns it now." Lifecycle ownership gap. +- "We have 25 clusters and it is chaos." Over-built; sweet spot was 12. + +--- + +## The framework: 12 considerations for hub architecture + +When designing or auditing a content hub, walk these 12 considerations. + +1. Topic earns the pillar. Search volume, facet count, commercial relevance, competitive feasibility, editorial commitment. +2. Cluster size targets 10 to 12. Sweet spot, not the maximum. +3. Facet heterogeneity. Definition, how-to, comparison, examples, mistakes, costs, alternatives. Not 12 variations of "what is X." +4. No facet duplication. Clusters cover distinct queries; consolidate when they overlap. +5. Pillar to cluster to pillar link graph. Top-down plus bottom-up plus selective lateral. +6. Anchor text discipline. Varied, descriptive, natural-language. No stuffing, no "click here." +7. URL structure signals the hub. `/topic/` not `/blog/`. +8. Pillar anatomy includes TL;DR and FAQ. Citation-ready sections for AI engines. +9. Cluster anatomy links UP to pillar early. First 200 words and closing. +10. AEO/GEO and SEO together. Two-engine optimization, complementary not competing. +11. Annual pillar refresh plus triggered cluster refresh. Maintenance is part of the architecture. +12. Hub ownership is durable. Single owner across 3 to 5 year horizons; not "the team that launched it." + +The output of the framework is an architecture document the team can reference at every stage: pillar selected, cluster planned, links specified, URLs chosen, page anatomies templated, refresh cadence set, owner named. + +--- + +## Reference files + +- [`references/pillar-cluster-decision.md`](references/pillar-cluster-decision.md) - Pillar vs cluster vs orphan decision tree with worked examples and the "everything is a pillar" anti-pattern. +- [`references/topic-selection-criteria.md`](references/topic-selection-criteria.md) - Five-criterion framework expanded with B2B SaaS, ecommerce, services, and media examples. +- [`references/cluster-planning-patterns.md`](references/cluster-planning-patterns.md) - Facet sourcing methods, sequencing patterns, heterogeneity check. +- [`references/internal-linking-architecture.md`](references/internal-linking-architecture.md) - Top-down, bottom-up, lateral patterns; anchor text discipline; linking inventory; quarterly audit checklist. +- [`references/url-structure-patterns.md`](references/url-structure-patterns.md) - Subfolder vs subdomain decision; slug conventions; breadcrumbs; the /blog/ trap. +- [`references/pillar-page-anatomy.md`](references/pillar-page-anatomy.md) - Section-by-section anatomy; TL;DR placement; FAQ schema; internal-link callouts; schema choices; length calibration. +- [`references/cluster-piece-anatomy.md`](references/cluster-piece-anatomy.md) - Focused-question framing; pillar callout placement; lateral linking judgment. +- [`references/topical-authority-signals.md`](references/topical-authority-signals.md) - SEO and AEO/GEO signals at hub level; two-engine optimization framing. +- [`references/content-refresh-patterns.md`](references/content-refresh-patterns.md) - Annual pillar refresh; triggered cluster refresh; cluster expansion and pruning; hub lifecycle. +- [`references/common-pillar-failures.md`](references/common-pillar-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: architecture is the moat + +Comprehensive content can be replicated. Authoritative sources can be cited. Individual pieces can be matched in quality by competitors with similar resources. What is harder to replicate is the compounding of an intentional hub built and maintained over years: the link graph, the entity coverage, the maintenance discipline, the topical depth signals that build over a 3 to 5 year horizon. + +That is the moat. Architecture is the only part of content marketing that compounds reliably; everything else is execution that can be matched. + +When in doubt about whether a hub is ready, ask: is the pillar selected against the five criteria, are the 10 to 12 clusters planned with facet heterogeneity, is the link graph specified top-down and bottom-up, is the URL structure clean, is the pillar anatomy templated with TL;DR and FAQ, is the refresh cadence set, and is the durable owner named? If yes to all of those, ship the hub plan and let the per-piece briefs and writers work. diff --git a/skills/pillar-content-architecture/references/cluster-piece-anatomy.md b/skills/pillar-content-architecture/references/cluster-piece-anatomy.md new file mode 100644 index 0000000..85ca692 --- /dev/null +++ b/skills/pillar-content-architecture/references/cluster-piece-anatomy.md @@ -0,0 +1,120 @@ +# Cluster piece anatomy + +Focused-question framing. Pillar callout placement. Lateral linking judgment. + +--- + +## The shape of a cluster piece + +A cluster piece is not a mini-pillar. Different shape, different work. + +### Hero (first 100 to 150 words) + +Focused on one specific question or task. The hero does not introduce the broader topic; the pillar does that. The hero introduces the cluster piece's specific facet. + +- Title. Includes the cluster's primary keyword. Often question-form ("What is a feature flag kill switch?") or task-form ("How to design a feature flag kill switch"). +- Subhead. One sentence promising the specific answer. + +### Pillar callout (within first 200 words) + +The bottom-up link to the pillar. Required. + +Pattern. "This piece covers feature flag kill switches in depth. For the broader context on rollout strategies that include kill switches as one safety mechanism, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +Why required. The pillar callout is the structural signal that this cluster belongs to the hub. Without it, the piece reads as a standalone article and the hub does not compound. + +Why early. Crawlers and AI engines weight links higher when they appear near the top of the page. The first 200 words is the citation-prime real estate; the pillar callout there has more impact than the same callout in the closing. + +### Focused body (the bulk of the cluster) + +Answers the specific question with depth. Does not expand into adjacent facets. + +The discipline. When the writer notices an interesting tangent into an adjacent facet, they note it as a candidate for another cluster piece and stay on topic. The cluster piece does one thing well; expansion belongs in a different piece. + +Section structure. 4 to 6 H2 sections covering the cluster's question from different angles. Each H2 has a featured-snippet-bait answer paragraph (40 to 60 words) followed by 200 to 400 words of development. + +### Lateral callouts (selective) + +When the cluster's body naturally references a sibling cluster, link to it. + +Pattern. A cluster on percentage rollouts naturally references kill switches in the section on "what happens when the rollout shows problems." A 1-sentence aside with a contextual link to the kill switches cluster. + +Frequency. 0 to 3 lateral links per cluster piece. Some clusters need none; some clusters at the topic's center connect to several siblings. + +Anti-pattern. Forced lateral linking. If the connection is not natural to the body's flow, the link is decorative and dilutes anchor signal. + +### Closing + +Two equally valid closing patterns. + +Pattern A: link back to pillar. "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns." + +Pattern B: link to next cluster in a journey. "If you have your kill switches designed and want to think about progressive rollouts, read our [percentage rollout guide](/feature-flag-rollout/percentage-rollouts/) next." + +The choice. Pattern A is the safe default; it reinforces the pillar and works for most cluster pieces. Pattern B is appropriate when the cluster has a clear "next step" in a reader journey (foundational concept → next concept). + +--- + +## Length calibration + +800 to 2,000 words is the typical cluster range. Calibrate to: + +- The SERP for the cluster's specific keyword. Top 10 word counts tell you the band. +- The cluster's place in the hub. Foundational clusters (definitions, intros) often run shorter; advanced clusters (deep how-tos, comparisons) often run longer. + +The 2,500-word cluster trap. A cluster piece longer than 2,500 words is probably a mini-pillar. Two diagnostic questions: + +1. Does it cover 2+ distinct facets? If yes, split into two cluster pieces. +2. Does it have 8+ H2 sections? If yes, it is structurally a pillar; either promote it (with cluster support) or trim. + +The 600-word cluster trap. A cluster piece shorter than 800 words is often too thin to rank for its target keyword. Either: + +- Expand to 1,000+ words with deeper coverage of the question. +- Merge with a sibling cluster if the topic does not have enough depth. +- Demote to a non-hub blog post if the piece is just a brief observation. + +--- + +## Featured snippet bait at H2 level + +Cluster pieces benefit from featured-snippet-bait answer paragraphs at every H2, not just at the top. + +Pattern. + +> ## What is a feature flag kill switch? +> +> A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. + +The 40 to 60 word answer paragraph is self-contained and citation-ready. AI engines extract these paragraphs as the canonical answers. + +Frequency. Every H2 should have a snippet-bait paragraph. The pattern repeats throughout the piece; it is a structural discipline. + +--- + +## Schema markup for clusters + +Cluster pieces typically use Article schema (or HowTo if the cluster is a step-by-step guide). FAQPage schema applies if the cluster has a real FAQ section. + +BreadcrumbList schema is required for cluster pieces; it tells crawlers the cluster is part of the hub. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +--- + +## When the cluster piece is also useful as a standalone + +Some cluster pieces will rank for queries unrelated to the pillar's topic. A cluster on "kill switches" might also rank for queries about software safety patterns generally. + +The decision: keep the cluster piece in the hub even when it ranks for non-hub queries. The pillar callout costs nothing for the standalone-query reader; the hub-traffic reader benefits from the link. Both audiences are served. + +The exception: when the cluster piece's standalone ranking dominates and the pillar context is misleading to the standalone-query reader, consider splitting into two pieces. Rare; usually the pillar callout works fine for both audiences. diff --git a/skills/pillar-content-architecture/references/cluster-planning-patterns.md b/skills/pillar-content-architecture/references/cluster-planning-patterns.md new file mode 100644 index 0000000..ba1195e --- /dev/null +++ b/skills/pillar-content-architecture/references/cluster-planning-patterns.md @@ -0,0 +1,108 @@ +# Cluster planning patterns + +Facet sourcing methods, sequencing patterns, heterogeneity check. + +--- + +## Facet sourcing methods + +A pillar's cluster is built from 8 to 15 facets. Source them deliberately rather than from the writer's imagination. + +### Method 1: keyword research expansion + +Start with the pillar keyword. Pull the long-tail variations from keyword tools (Ahrefs, Semrush, GSC, dataForSEO). Filter by intent: each cluster facet should have its own SERP intent and dominant format. Variations that share intent with the pillar are not separate facets; they belong inside the pillar itself. + +### Method 2: "people also ask" extraction + +Pull the PAA box for the pillar keyword and 3 to 5 supporting keywords. Each unique question is a candidate cluster facet. PAA is the cleanest signal of what readers actually ask in this topic space. + +### Method 3: top-ranking competitor outline mining + +Pull the top 5 SERP results for the pillar keyword. Extract H2 sections from each. Cluster the H2s across the 5 competitors; sections that appear in 3+ competitors are facets the topic objectively requires. Sections unique to 1 or 2 competitors may be differentiation opportunities. + +### Method 4: first-party customer questions + +Sales calls, support tickets, customer success notes, sales enablement Q&A. The questions customers actually ask are facets the pillar needs to address even if SERP signal is weak. First-party questions also produce differentiation: questions your customers ask but that competitor content does not address. + +### Method 5: Frase or AirOps SERP analysis + +Frase's entity gap analysis and AirOps' workflow builder both run versions of methods 1 to 3 in software. The output is a candidate facet list with SERP coverage scores. Use the tool output as the starting point; refine with first-party questions (method 4) for differentiation. + +--- + +## Sequencing patterns + +How to ship the hub over time. + +### Pattern A: pillar first, cluster follows + +Ship the pillar as a 3,000 to 5,000 word piece. Over the next 6 to 12 weeks, ship 1 to 2 cluster pieces per week. By month 3, the hub has the pillar plus 8 to 12 clusters and starts compounding. + +When this works. Strong editorial team that can ship a pillar quickly. The pillar drives initial rankings; clusters fill in topical depth as they ship. + +The risk. Pillar ranks for 6 weeks before the cluster is complete; AI engines see a thin hub and may not return to crawl when clusters land. Mitigated by including cluster placeholders in the pillar with "coming soon" or by pre-publishing cluster stubs. + +### Pattern B: pillar plus first 5 clusters concurrent + +Ship the pillar and the first 5 clusters within the same 4-week window. The hub launches with the link graph already partially formed; rankings start with depth signals already in place. + +When this works. Larger team or agency support. The launch produces a more credible hub on day 1. + +The cost. Higher up-front investment. The first 5 clusters lock the team's editorial capacity for the launch window. + +### Pattern C: prove with 3 clusters, then commit to pillar + +Ship 3 cluster pieces under a planned-but-not-yet-shipped pillar slot. Measure performance over 8 to 12 weeks. If the clusters draw traffic and the topic shows commercial signal, commit to the pillar. If not, pivot to a different pillar topic without the sunk cost. + +When this works. Uncertain topic where the commercial signal needs validation before the pillar investment. Common in agencies running pillars for clients without strong upfront conviction. + +The discipline. The 3 clusters must be writeable as standalones during the validation window; they cannot reference the pillar by name yet because it does not exist. Once the pillar ships, retrofit the cluster pieces with pillar callouts and bottom-up links. + +--- + +## Heterogeneity check + +A cluster passes heterogeneity if its facets cover the topic from multiple distinct angles. The check: + +Categorize each facet by primary angle: + +- Definition (what is X) +- How-to (how to do X) +- Comparison (X vs Y) +- Examples (5 examples of X, X case studies) +- Mistakes (common X mistakes) +- Costs (how much X costs, X pricing models) +- Alternatives (alternatives to X) +- Best-of (best X tools, top X providers) +- Use cases (when to use X) +- Niche variants (X for [specific audience]) +- Foundational (related concept Y that supports X) +- Advanced (advanced X techniques) + +The rule. A 12-cluster hub should have facets across 6+ distinct angles. If 10 of 12 are "how-to," the cluster is homogeneous and the pillar will look like a how-to series rather than a topical authority hub. + +The fix. When facet brainstorming over-indexes on one angle, deliberately add 2 to 3 facets from different angles. The "5 examples of X" cluster piece is often the most under-served angle; teams forget to add concrete-example pieces and over-invest in abstract how-tos. + +--- + +## No facet duplication + +Two cluster pieces should not target overlapping queries. The check: + +- For each cluster piece, list the 3 to 5 keywords it would target. +- For each pair of cluster pieces, check whether their keyword lists overlap by more than 30%. +- Overlapping clusters compete for the same SERP and self-cannibalize. Consolidate to one piece. + +The most common duplication. "What is X" and "X explained" and "X definition" are the same facet. Pick one slug and one focus; do not split the foundational definition across three pieces. + +--- + +## When the cluster is too big + +A planned cluster with 25+ pieces is over-built. The hub becomes unmanageable: maintenance burden too high, link graph too dense to audit, reader navigation confusing. + +Fix 1. Split into two pillars under a parent pillar. The original pillar covers the broadest topic; sub-pillars cover major sub-territories with their own clusters. Three-level hierarchy is rare but valid for very broad topics. + +Fix 2. Trim to the 12 most-impactful facets. Rank facets by combined search volume + commercial relevance + heterogeneity contribution; keep the top 12; archive the rest as future-cluster candidates. + +The 12-cluster sweet spot is empirical. Below 8, the hub looks thin; above 15, maintenance overhead kicks in; 10 to 12 is the band where most healthy hubs sit. diff --git a/skills/pillar-content-architecture/references/common-pillar-failures.md b/skills/pillar-content-architecture/references/common-pillar-failures.md new file mode 100644 index 0000000..9ec094c --- /dev/null +++ b/skills/pillar-content-architecture/references/common-pillar-failures.md @@ -0,0 +1,150 @@ +# Common pillar failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +--- + +## "We have 80 blog posts but no rankings" + +Symptom. The team has been publishing for 2+ years; 80 pieces shipped; organic traffic is flat or declining. + +Diagnosis. Orphan content; no hub architecture. 80 disconnected pieces produce no topical authority signal regardless of individual quality. + +Fix. Audit the 80 pieces. Group by topic. For each major topic group, identify or build a pillar; refactor the existing pieces into clusters by adding pillar callouts and bottom-up links. Some pieces will not fit and become standalone-by-design; some will need consolidation. + +The expected outcome: 4 to 6 hubs, each with a pillar plus 8 to 12 clusters; 15 to 20 standalones; the rest pruned. See `pillar-cluster-decision.md`. + +--- + +## "Our 8,000-word pillar does not rank" + +Symptom. Team invested in a long, comprehensive pillar; 6 months in, position 23 on the primary keyword. + +Diagnosis. Comprehensive but no cluster support; the pillar is a long article without a hub. Length without architectural support does not signal authority. + +Fix. Build the cluster. Plan 10 to 12 cluster pieces under the pillar; ship 3 to 5 in the next 8 weeks; complete the cluster within 6 months. Update the pillar with internal-link callouts to each cluster as they ship. See `cluster-planning-patterns.md`. + +The expected outcome: ranking improves over 3 to 6 months as the cluster matures. The pillar that did not rank standalone will rank as the hub forms. + +--- + +## "We launched the pillar, never built the cluster" + +Symptom. Pillar shipped 8 months ago; team's editorial focus shifted; the planned cluster never landed. Pillar has 2 supporting pieces shipped haphazardly. + +Diagnosis. Architecture half-built. The 2 supporting pieces are functioning as orphans because the hub is not formed; the pillar gets minimal compounding. + +Fix. Either commit to completing the cluster (8 to 10 more pieces over 4 to 6 months) or prune the hub. Half-built hubs are worse than no hub; commit or unwind. If completing, prioritize facets the team can ship within 12 weeks. + +--- + +## "Cluster pieces do not link to the pillar" + +Symptom. Hub has pillar plus 12 clusters; pillar links to all clusters; only 4 of 12 clusters link back to the pillar. + +Diagnosis. Top-down link graph but no bottom-up. The pillar does not compound. Cluster pieces have not been required to include pillar callouts. + +Fix. Audit each cluster; add pillar callouts in the first 200 words and the closing of any cluster that lacks them. Update the brief template to require both pillar callouts on every future cluster piece. See `internal-linking-architecture.md`. + +--- + +## "Two cluster pieces target the same keyword" + +Symptom. Cluster includes "what is a feature flag" and "feature flags explained." Both rank position 8 to 12 alternately; neither breaks into the top 5. + +Diagnosis. Self-cannibalization. Two pieces competing for the same SERP; PageRank splits across two URLs; neither piece gets enough authority to rank top 5. + +Fix. Consolidate. Pick the stronger piece (higher current rank, more inbound links, longer URL history). 301 redirect the weaker piece to the stronger one. Merge any unique content from the weaker into the stronger. Update the linking inventory. + +--- + +## "Pillar URL is /blog/the-ultimate-guide-to..." + +Symptom. The pillar lives at `/blog/the-ultimate-guide-to-feature-flag-rollout-strategies/` because the CMS routes everything under `/blog/`. + +Diagnosis. Losing the URL hub signal. Crawlers cannot infer hub topology from the URL; readers cannot tell from the URL that this is a pillar. + +Fix. Migrate to `/feature-flag-rollout/` for the pillar; cluster pieces to `/feature-flag-rollout/[slug]/`. 301 redirect old URLs. Take a short-term ranking hit; gain long-term hub-signal clarity. See `url-structure-patterns.md`. + +The migration is not always worth it. If the pillar is small or the brand's overall content investment is modest, the cost may exceed the benefit. Score against the hub's commercial value. + +--- + +## "Our pillar is 12 sections of 'what is X'" + +Symptom. Pillar covers the topic comprehensively in length but every H2 is a definitional question. "What is X." "What does X do." "What are the parts of X." 12 variations of the same angle. + +Diagnosis. Facet homogeneity. The pillar covers one angle 12 ways instead of 12 distinct angles. + +Fix. Rewrite the pillar's outline using the heterogeneity check (definition, how-to, comparison, examples, mistakes, costs, alternatives, etc.). Replace 8 of the 12 definitional sections with sections covering different angles. See `cluster-planning-patterns.md`. + +--- + +## "We cannot tell which piece to refresh first" + +Symptom. Hub has 14 pieces; team knows refresh is needed; cannot prioritize where to start. + +Diagnosis. No maintenance ownership; no signals being tracked. Without per-piece performance data, refresh prioritization is guesswork. + +Fix. Assign a hub owner (see `content-refresh-patterns.md`). Track 4 metrics per piece: organic traffic, primary-keyword rank, AI citation count if measurable, last-updated date. Prioritize refresh on pieces with declining traffic, slipping ranks, or oldest update dates. The metrics make the prioritization mechanical. + +--- + +## "Pillar ranks but does not get cited by AI engines" + +Symptom. Pillar ranks position 4 on Google; brand mention rate from Profound is unchanged after the pillar shipped. + +Diagnosis. Missing AEO/GEO signals. Pillar may have no TL;DR, no answer paragraphs under H2s, no FAQ schema, vague statistics, no named experts. + +Fix. Audit the pillar against the AEO/GEO signals checklist (see `topical-authority-signals.md`). Add a 150 to 250 word TL;DR at the top. Add 40 to 60 word answer paragraphs under each H2. Mark FAQ section with FAQPage schema. Replace vague statistics with specific numbers and cited sources. Add named experts where the topic supports them. + +The AEO/GEO refresh is faster than the SEO refresh; expect citation improvement within 4 to 8 weeks of changes propagating. + +--- + +## "Hub launched 3 years ago; nobody owns it now" + +Symptom. Hub built by a content lead who left 18 months ago. No formal owner since. Performance has degraded; nobody noticed. + +Diagnosis. Lifecycle ownership gap. The "set and forget" failure mode. + +Fix. Assign a new owner. Allocate 1 to 2 weeks of editorial time for an emergency refresh: re-validate the SERP, update statistics, prune dead sections, refresh internal links. Set the annual refresh cadence going forward; track ownership renewal in the hub's planning doc. See `content-refresh-patterns.md`. + +Some hubs at this stage are unrecoverable. If the SERP has shifted enough that the original architecture no longer fits, restructure rather than refresh; treat as a year-5+ lifecycle event. + +--- + +## "We have 25 clusters and it is chaos" + +Symptom. Hub started at 12 clusters; expanded over 3 years to 25; the linking inventory is unmanageable; new pieces tangle with old pieces; readers cannot find what they need. + +Diagnosis. Over-built. The cluster expanded beyond the manageable sweet spot. + +Fix. Prune. Apply the cluster pruning criteria (see `content-refresh-patterns.md`): clusters that have not ranked in top 30 after 12 months, clusters with zero search volume, clusters that duplicate other clusters. Aim to trim back to 12 to 15 active clusters; archive the rest with redirects. + +Alternative: split into two pillars under a parent topic. Rare; valid only for genuinely broad topics. + +--- + +## "We did all the SEO work but the AI engines do not cite us" + +Symptom. Pillar ranks well; clusters rank well; brand mention rate from Profound is flat. AI engines cite competitors instead. + +Diagnosis. Could be either: + +- The hub is structurally fine for SEO but missing AEO/GEO signals (see "pillar ranks but does not get cited" above). +- The hub is missing distinctive POV. AI engines preferentially cite content with attributable claims; content that reads as SEO consensus does not get cited even when it ranks. + +Fix. Audit each pillar and high-traffic cluster for distinctive claims. Add at least one strong POV per piece: a position the team is willing to defend, a recommendation that is not "it depends," a specific claim with named experts and statistics behind it. Bland comprehensive content does not get cited; opinionated comprehensive content does. + +--- + +## "We have a hub but conversions are flat" + +Symptom. Hub drives traffic, ranks well, gets cited; trial signups attributable to the hub are flat. + +Diagnosis. Topical authority is working; commercial conversion is not. The hub's content does not connect cleanly to the buyer journey. + +Fix. Audit the pillar and clusters for commercial CTAs. Each cluster should have a clear next step that is NOT just "read another cluster." Trial signup, demo request, content download, newsletter subscription. The hub is producing the audience; the conversion path needs separate design work. + +This failure is outside this skill's scope to fully solve; pair with `landing-page-copy` for conversion-focused next-step pages and `content-strategy` for funnel-aware content planning. diff --git a/skills/pillar-content-architecture/references/content-refresh-patterns.md b/skills/pillar-content-architecture/references/content-refresh-patterns.md new file mode 100644 index 0000000..3517077 --- /dev/null +++ b/skills/pillar-content-architecture/references/content-refresh-patterns.md @@ -0,0 +1,164 @@ +# Content refresh patterns + +Annual pillar refresh checklist. Triggered cluster refresh signals. Cluster expansion patterns. Cluster pruning criteria. Hub lifecycle (5 to 7 year horizon). + +--- + +## Why refresh matters + +Hubs decay. Statistics go stale; SERPs shift; new facets emerge; existing pieces drift from current best practice. A hub that ranks at year 1 often falls to position 12 by year 3 if nobody refreshes it. + +The discipline is built into the architecture: refresh is not an afterthought; it is a budgeted activity. + +--- + +## Annual pillar refresh checklist + +Run every 12 months on each pillar. Allocate 1 to 2 weeks of editorial time per pillar. + +### Step 1: re-validate the SERP + +Pull the current SERP top 10 for the pillar's primary keyword. Compare to the last refresh's top 10. + +- Are new competitors in the top 10? What are they covering that you are not? +- Have existing competitors updated their pillars? What new sections did they add? +- Has the SERP intent shifted (e.g., from informational to commercial-investigation)? + +### Step 2: update statistics + +Find every numeric claim in the pillar. Verify each is still accurate; replace stale numbers with current ones; cite the new source. + +Common stale numbers. Industry statistics that were "as of 2023" and now are 2 years old. Pricing references that have shifted. Tool capabilities that have evolved. + +### Step 3: add new sections for emerged facets + +Did the topic surface new facets in the last 12 months? Add H2 sections covering them. Each new section should be 300 to 500 words; if it grows beyond 700, promote it to a new cluster piece and reduce the pillar section to a callout. + +### Step 4: prune sections that no longer matter + +Did old sections become irrelevant? Maybe a tool you covered shut down; maybe a method you described was deprecated. Cut or significantly trim those sections. Pillar bloat from un-pruned content is the most common pillar-decay symptom. + +### Step 5: refresh internal-link callouts to clusters + +The cluster has likely grown since last refresh. Add callouts to any new cluster pieces that did not exist before. Verify all existing callouts still link to live cluster URLs. + +### Step 6: update the TL;DR + +The TL;DR captures the pillar's argument as of the refresh date. Revise to reflect any structural changes: new facets, removed sections, shifted POV. + +### Step 7: bump the last-updated date + +Set the publish-modified date to the refresh completion date. The freshness signal matters; do not skip it. + +### Step 8: re-submit to search engines + +Submit the updated pillar URL to Google Search Console for re-crawl. Some teams also ping AI engine indexing endpoints (Perplexity, Bing for Copilot) where available. + +--- + +## Triggered cluster refresh signals + +Clusters do not need annual refresh; they need triggered refresh when specific signals appear. + +### Trigger 1: keyword performance drops + +The cluster's primary keyword falls 5+ positions in 30 days. The drop is the signal; pull the SERP, identify what is now ranking ahead, and update the cluster to compete. + +### Trigger 2: new sub-topic emerges + +Within the cluster's facet, a new sub-topic appeared (new tool launched, new technique published, new regulation issued). Update the cluster to reference the new sub-topic. + +### Trigger 3: cluster's links go stale + +The quarterly link audit (see `internal-linking-architecture.md`) finds broken outbound links from the cluster. Update the cluster with new links. + +### Trigger 4: AI citation drops + +The cluster was being cited by AI engines and the citation count drops. Check whether content drifted, whether new entities should be added, whether the answer paragraphs need tightening. AI citation drops are slower-moving than ranking drops; act on month-over-month trends, not week-over-week. + +### Trigger 5: customer feedback surfaces a gap + +A sales rep, support agent, or customer success manager flags that the cluster does not cover a question customers actually ask. Add the section. + +--- + +## Cluster expansion patterns + +A hub at year 1 might have 8 clusters. Year 3 could have 18. Expansion happens deliberately, not opportunistically. + +### When to expand + +- A new facet emerges and customer questions confirm demand. +- Competitor analysis shows a facet your hub does not cover. +- Keyword research surfaces new long-tail variations with traffic. +- AI citation patterns show queries your hub does not address. + +### When not to expand + +- Tempting facet but no customer demand. Adds maintenance burden without driving traffic. +- Facet already covered by another piece on the site outside the hub. Either move that piece into the hub or update its links. +- Facet is too narrow (sub-100 monthly searches with no commercial signal). Add as a section to an existing cluster, not as its own cluster. + +### Expansion cap + +Max 20 clusters per pillar. Above that, the hub becomes unmanageable. If the topic genuinely supports 25+ facets, split into two pillars under a parent topic (rare; valid for very broad topics). + +--- + +## Cluster pruning criteria + +Some clusters should die. Pruning is hygiene, not failure. + +### Prune when + +- Cluster has not ranked in top 30 after 12 months despite refresh attempts. +- Cluster's keyword has gone to zero search volume. +- Cluster duplicates another cluster (consolidate). +- Cluster covers a tool, technique, or topic that no longer exists. + +### How to prune + +- 301 redirect the URL to the most-relevant remaining cluster, or to the pillar. +- Remove links from the pillar and other clusters to the pruned URL. +- Update the linking inventory. + +### What not to do + +- Do not delete the URL without redirecting; 404s waste any acquired authority. +- Do not redirect to the homepage; redirect to the most topically-relevant alternative. + +--- + +## Hub lifecycle (5 to 7 year horizon) + +Hubs themselves have lifespans. After 5 to 7 years, the topic landscape often shifts enough that wholesale restructuring becomes appropriate. + +### Signs the hub needs restructuring (vs annual refresh) + +- The pillar's primary keyword has shifted intent (the SERP is now showing a different content type). +- Competitors have rebuilt their hubs around a different angle that better matches current reader needs. +- The cluster has grown unwieldy (25+ pieces) and the topical organization no longer makes sense. +- AI citation patterns suggest readers are asking questions the original hub structure cannot answer. + +### Restructuring approach + +- Treat the restructuring as a new hub launch. Plan the new pillar and cluster shape first. +- 301 redirect old pillar and cluster URLs to new equivalents where possible. +- Archive content that does not fit the new structure rather than force-fitting. +- Communicate the change in a release-note-style post linked from both old and new URLs during the transition. + +The 5-to-7 year cycle is empirical. Some hubs last longer (foundational topics like "what is SEO"); some need restructuring sooner (fast-moving topics like "AI search"). Ownership tracks the lifecycle; the durable hub owner is the one who decides when to restructure. + +--- + +## Maintenance ownership + +The pillar owner is named and durable. Common patterns: + +- Single editor. One person owns the hub for a 12-month commitment. Renewed annually. +- Editor + SEO partner. Editor owns content; SEO partner owns rankings and link audits. +- Cross-functional team. Editor, SEO, product marketing rotate quarterly reviews. Works for large teams; falls apart in small teams (rotation diffuses ownership). + +The "set and forget" failure mode happens when ownership dissolves. The team that launched the hub disbanded, was reorganized, or moved on; nobody picks up maintenance. Six quarters later, the hub has decayed and recovery costs more than the original launch. + +The fix. Assign a durable owner before the hub launches. Renew the assignment annually. Track the owner's continued ownership in the hub's planning doc; surface in quarterly reviews. diff --git a/skills/pillar-content-architecture/references/internal-linking-architecture.md b/skills/pillar-content-architecture/references/internal-linking-architecture.md new file mode 100644 index 0000000..805f61f --- /dev/null +++ b/skills/pillar-content-architecture/references/internal-linking-architecture.md @@ -0,0 +1,100 @@ +# Internal linking architecture + +Top-down, bottom-up, lateral linking patterns. Anchor text discipline. The linking inventory pattern. Quarterly link audit checklist. + +--- + +## The three link directions + +A hub's link graph has three directions; all three need discipline. + +### Top-down: pillar to cluster + +The pillar links out to each cluster piece via contextual anchors woven into the pillar's body. The reader is reading the section on, for example, "kill switches"; that section includes a contextual link to the cluster piece on kill switches. + +Pattern. "Most rollouts include a kill switch as a final safety net. For the full pattern including code-level implementations, see [our guide on kill switch design](/feature-flag-rollout/kill-switches/)." + +Anti-pattern. A "Related reading" footer at the bottom of the pillar listing 12 cluster links. Footer links pass less topical signal and read as decorative; contextual body links read as load-bearing. + +Frequency. One link per cluster from within the pillar. Two links to the same cluster from the pillar is fine if the cluster covers two distinct sections; three links to the same cluster suggests the pillar should reference the cluster more selectively. + +### Bottom-up: cluster to pillar + +Every cluster piece links up to the pillar at least twice. First in the introduction (within the first 200 words); second in the closing. + +Pattern in introduction. "This piece covers kill switches in feature flag rollouts. For the broader context on rollout strategies, see our guide to [feature flag rollout strategies](/feature-flag-rollout/)." + +Pattern in closing. "Kill switches are one part of a complete rollout strategy. Continue reading our [feature flag rollout strategies guide](/feature-flag-rollout/) for the rest of the patterns, or jump to [percentage rollouts](/feature-flag-rollout/percentage-rollouts/)." + +Why two. First link tells crawlers and readers the topical context immediately. Second link captures readers who got value from the cluster piece and want to dig deeper into the hub. + +### Lateral: cluster to cluster + +Selective. When one cluster piece naturally references another, link with descriptive anchor text. Do not force lateral links. + +Pattern. A cluster on "percentage rollouts" naturally references "kill switches" when discussing what to do if the rollout shows problems. The lateral link is contextual; the reader is at a moment where the related cluster is actually useful. + +Anti-pattern. Every cluster piece links to every other cluster piece. The link graph becomes complete-graph-shaped; anchor text relevance dilutes; PageRank flow is undirected and weaker. + +Frequency. 1 to 3 lateral links per cluster piece is typical. Some clusters need zero lateral links; some clusters that sit at the center of a topic naturally connect to 5 sibling clusters. + +--- + +## Anchor text discipline + +Anchor text is the signal that tells search engines what the linked-to page is about. The discipline: + +Vary the anchor text. Do not link to the pillar with the exact same phrase every time. Use the pillar's primary keyword, secondary keywords, and natural-language phrases that describe the linked page. + +Descriptive natural-language anchors. "See our guide to feature flag rollout strategies" beats "click here to read more." The anchor text should make sense if it is the only thing the reader reads. + +No over-optimization. Do not stuff every link with exact-match keywords. Anchor text that varies naturally is what a real authority cluster looks like; uniform exact-match anchors signal manipulation to ranking systems. + +Brand-mention anchors. Sometimes the right anchor is the brand name or product name when linking to a product page. "RampStack's experimentation skill" is a brand anchor; "experimentation skills documentation" is a descriptive anchor. Mix both. + +Common dead anchors. "Click here," "this article," "read more," "more info." All dead. They pass minimal topical signal and waste the link's potential. + +--- + +## The linking inventory pattern + +Maintain an inventory of every link in the hub. The format depends on the team's tooling. + +Spreadsheet. Columns: source page slug, target page slug, anchor text, link section (intro / body / closing / sidebar), link direction (top-down / bottom-up / lateral / external). + +Notion database. Same columns as relations, queryable per page or per direction. + +dbt model with content metadata. For warehouse-native content tracking; the link graph becomes a queryable table that compounds with other content metrics (rank, citation count, conversion). + +CMS audit fields. Some CMSs (Contentful, Sanity, custom WordPress) allow per-page metadata fields. Track outbound links per piece; aggregate at the hub level. + +The inventory enables the quarterly audit; without it, the audit becomes a manual scan that misses things. + +--- + +## Quarterly link audit checklist + +Run every 90 days. Catches the failures that compound silently. + +1. Broken outbound links. Crawl every cluster piece for 404s on outbound links. Common cause: cluster piece was renamed or moved without redirect. +2. Missing bottom-up links. Every cluster should link to the pillar in intro and closing. Audit checks both. +3. Missing top-down links. Pillar should link to every cluster from within the body. Audit checks each cluster has at least one body link from the pillar. +4. Anchor text drift. Same anchor text used by 5+ links to the same target reads as over-optimized. Vary by editing 2 to 3 of them. +5. Dead anchors. "Click here" or "read more" anchors that crept in during writing. Replace with descriptive anchors. +6. Lateral over-linking. Cluster pieces linking to 5+ siblings reads as complete-graph noise. Trim to 2 to 3 most-relevant siblings. +7. Orphan clusters. Cluster piece that no other piece links to (besides the pillar). The pillar's top-down link is required; ideally 1 to 2 sibling lateral links also exist. +8. Stale references. Cluster pieces that reference statistics, products, or pages that no longer exist. Update the references; refresh the piece if the underlying topic shifted. +9. New cluster integration. When a new cluster piece ships, audit confirms it received its top-down link from the pillar AND its bottom-up plus lateral links. New clusters often miss the inbound updates that would prevent orphan status. +10. Anchor diversity. Pull the inventory; group anchor texts by target page. If 8 of 10 links to a page use the same anchor, edit 3 to 5 to vary. + +The audit takes 1 to 3 hours per hub. The cost is real but smaller than the cost of letting the link graph decay. + +--- + +## When the link graph is too dense + +Some teams over-link. Every cluster piece has 8 outbound contextual links plus 5 lateral plus 3 external. The reader is bombarded; the anchor text relevance dilutes. + +Heuristic. A cluster piece with more than 6 outbound internal links per 1,000 words is over-linked. Trim to the 4 to 6 highest-relevance links. + +The trim improves both reader experience and PageRank concentration. Each remaining link gets more weight; the link graph becomes more legible to crawlers. diff --git a/skills/pillar-content-architecture/references/pillar-cluster-decision.md b/skills/pillar-content-architecture/references/pillar-cluster-decision.md new file mode 100644 index 0000000..a5fe670 --- /dev/null +++ b/skills/pillar-content-architecture/references/pillar-cluster-decision.md @@ -0,0 +1,98 @@ +# Pillar vs cluster vs orphan decision + +The decision tree, worked examples, and the "everything is a pillar" anti-pattern. + +--- + +## The decision tree + +When a new piece is being planned, walk these questions in order. + +Question 1. Does this topic have 8 to 15 distinct facets that could each be a separate piece? + +- Yes: this might be a pillar. Continue to question 2. +- No: this is not a pillar. Continue to question 4 to test cluster fit. + +Question 2. Is the topic competitive enough to require comprehensive coverage to rank? + +- Yes (top 10 SERP shows long-form pillars from authoritative sources): pillar candidate confirmed. Continue to question 3. +- No (top 10 SERP shows short articles or tools): the topic does not need a pillar. A cluster piece probably suffices. + +Question 3. Is the team committed to maintaining this pillar for 3 to 5 years (annual refresh, cluster expansion, ownership)? + +- Yes: ship as pillar. Plan the cluster. +- No: do not start. A pillar without maintenance is worse than no pillar; it ranks for a year, then decays. + +Question 4. Is there an existing pillar this piece could connect to as a cluster? + +- Yes: ship as cluster. Specify the pillar callout and the bottom-up link in the brief. +- No: continue to question 5. + +Question 5. Is this piece intentionally standalone (release note, customer story, one-off campaign, executive announcement)? + +- Yes: ship as standalone. Standalone-by-design is fine. +- No: this is an accidental orphan. Either build the pillar first, or postpone the piece until a pillar exists, or rescope the piece to fit an existing pillar's cluster. + +--- + +## Worked examples + +### Example 1: "Feature flag rollout strategies" + +A B2B SaaS team is planning a piece on feature flag rollout strategies. + +- 8 to 15 facets? Yes: percentage rollout, ring deployment, canary, blue-green, kill switches, automatic rollbacks, rollout per cohort, rollout by geography, rollout by plan tier, etc. ✓ +- Competitive SERP? Top 10 are long-form articles from LaunchDarkly, Statsig, Optimizely. Pillar candidate confirmed. ✓ +- 3 to 5 year commitment? The team plans to expand the cluster as new patterns emerge. ✓ + +Decision: pillar. Plan 10 to 12 cluster pieces around it. + +### Example 2: "How to set up a Statsig experiment" + +The same team is planning a how-to on Statsig experiment setup. + +- 8 to 15 facets? No. The topic is one task with maybe 5 sub-steps. ✗ +- Existing pillar to connect to? Yes: the team has an "experimentation" pillar. + +Decision: cluster. Pillar callout to "experimentation" pillar; link up in first 200 words and closing. + +### Example 3: "Q3 2026 product release notes" + +The marketing team is planning a quarterly release-notes post. + +- 8 to 15 facets? No. ✗ +- Existing pillar to connect to? Not a topical fit; release notes are a different content type. +- Standalone-by-design? Yes; release notes serve customers tracking the product, not topical authority. + +Decision: standalone. Do not force into a hub; serve the customer tracking purpose. + +### Example 4: "What is a feature flag?" + +A piece on the basic definition. + +- 8 to 15 facets? No. The topic is one definition. ✗ +- Existing pillar to connect to? Yes: the "feature flag rollout strategies" pillar from example 1 needs a "what is a feature flag" cluster piece for the foundational facet. + +Decision: cluster under the feature flag rollout pillar. The pillar gets the cluster it needs; the piece gets the topical context it needs. + +--- + +## The "everything is a pillar" anti-pattern + +The symptom. Every 3,000-word piece on the team's site is called a pillar. The marketing team uses the word loosely; the SEO team uses it strictly; nobody agrees on what makes a pillar. + +The diagnosis. Length is being treated as the pillar criterion. Length does not make a pillar. The architectural role does. A 3,000-word piece with no cluster supporting it is a long article, not a pillar. A 1,500-word piece with 12 cluster pieces linking up to it is closer to a pillar than the 3,000-word standalone, even though the word counts are reversed. + +The fix. Use the word "pillar" precisely. Pillar is a piece that anchors a hub. If there is no hub, there is no pillar. Long articles that are not anchoring hubs are just long articles, and that is fine; they do not need to be promoted to "pillar" to justify the investment. + +The diagnostic question. "What pieces link up to this pillar?" If the answer is "none yet" or "we are planning to add some," the pillar is not yet a pillar. It is a planned pillar that becomes a real pillar when the cluster ships. + +--- + +## When the decision is hard + +The "almost a cluster" case. A piece is 1,800 words, covers a specific facet of an existing pillar, and would link up to the pillar. Sounds like a cluster. But the piece also stands alone for non-hub queries. Decision: ship as cluster. The pillar callout is cheap; the topical compounding is real. The "standalone-by-design" exception is for pieces that have a different purpose (release notes, customer stories), not for pieces that happen to be readable alone. + +The "almost a pillar" case. A piece is 3,500 words, covers a topic with 6 facets (not 8 to 15), and the SERP for the topic is moderately competitive. Decision: ship as a long cluster piece under a broader pillar, or postpone until the topic surfaces more facets. Forcing 3,500 words into a 6-facet topic creates the "pillar with 12 sections of 'what is X'" failure mode. + +The "we already have 5 standalone pieces on this topic" case. No pillar exists; 5 orphans cover related facets. Decision: build the pillar, then refactor the 5 orphans into clusters by adding pillar callouts and bottom-up links. The hub is being created from existing content rather than from scratch; this is faster than starting over and works well when the orphans are already decent. diff --git a/skills/pillar-content-architecture/references/pillar-page-anatomy.md b/skills/pillar-content-architecture/references/pillar-page-anatomy.md new file mode 100644 index 0000000..c3ba778 --- /dev/null +++ b/skills/pillar-content-architecture/references/pillar-page-anatomy.md @@ -0,0 +1,144 @@ +# Pillar page anatomy + +Section-by-section anatomy. TL;DR placement and length. FAQ schema. Internal-link callout placement. Schema markup choices. Length calibration. + +--- + +## Section-by-section structure + +A pillar page does specific work across a recognizable set of sections. + +### Hero (first 200 words) + +Defines the topic, signals scope, establishes authority quickly. + +- Title. Includes the primary keyword. Reads as comprehensive ("The complete guide to feature flag rollout strategies"). +- Subhead. One sentence promising specific value to a specific audience. +- Author / publish / update line. Author name with link to bio (E-E-A-T signal); last-updated date (freshness signal). + +### TL;DR or executive summary (150 to 250 words) + +The most important section for AI citation. AI engines extract this verbatim and use it as the canonical answer when users ask the topic question. + +What goes in. A self-contained summary of the pillar's argument. Read alone, it answers the topic. Read in context, it sets up the comprehensive body. + +What does not go in. Marketing fluff. Throat-clearing meta-commentary that announces what the page is about to do instead of doing it. Cut it. + +Format. Either a single dense paragraph (150 to 250 words) or 5 to 7 bullet points. Both work; bullets often extract more cleanly to AI engines. + +### Table of contents + +Auto-generated from H2 and H3 structure. Anchors to each section. Helps readers scan; helps crawlers see structure. + +### Comprehensive body (the bulk of the pillar) + +12 to 20 H2 sections covering the topic's major facets. The body is a guided tour with depth links, not a comprehensive treatment of every facet. + +Per H2 section. + +- Featured snippet bait. A 40 to 60 word answer paragraph immediately following the H2 question. AI engines often quote this as the citation. +- Body of the section. 200 to 600 words developing the answer with examples, formulas, edge cases. +- Cluster link callout. When the section maps to a cluster piece, link to the cluster contextually within the body. "For the full pattern including [specific facet], see our [cluster piece guide]." + +### Use cases or examples + +Anchor the abstract topic to concrete instances. 3 to 5 worked examples. Each example named, scoped, and referenced in the body. + +### Common mistakes / FAQ + +Structured Q&A. Each Q is a real question; each A is a 40 to 80 word answer. + +Pair with FAQPage schema. Mark the Q&A section with FAQPage structured data. AI engines (Perplexity especially) cite FAQPage content heavily. + +Anti-pattern. "Frequently asked questions" that nobody actually asks. The FAQ should source from real customer questions, sales-call transcripts, support tickets. Fabricated FAQs are obvious to readers and to AI engines. + +### Closing or next steps + +Directs the reader into the cluster. "If you are starting fresh, read [intro cluster piece]. If you have rollouts running and need to harden them, read [advanced cluster piece]." + +The closing is also where the second bottom-up pillar reinforcement lands for cluster pieces; for the pillar itself, the closing names the next-best clusters by reader intent. + +--- + +## TL;DR placement and length + +Place immediately after the hero, before the table of contents. The reader sees TL;DR within the first scroll. AI engines scrape from the top of the page; TL;DR placed early gets prioritized. + +150 words minimum. Below 150, the TL;DR is too thin to serve as a citation candidate. + +250 words maximum. Above 250, the TL;DR loses its punch and starts duplicating the body. + +Self-contained. A reader who reads only the TL;DR should walk away with the topic's core. No throat-clearing or hedging; the TL;DR IS the answer. + +--- + +## FAQ schema + +The FAQ section gets FAQPage schema. The format: + +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is a feature flag kill switch?", + "acceptedAnswer": { + "@type": "Answer", + "text": "A feature flag kill switch is a one-toggle mechanism that disables a feature instantly across all users. It exists as the final safety net when a rollout shows critical problems and per-user gradual rollback is too slow. Kill switches are configured at deploy time and remain available throughout the feature's lifecycle." + } + } + ] +} +``` + +Common mistake. FAQPage schema on questions that are not real FAQs. Schema markup that misrepresents page content can trigger manual penalties; mark only genuine FAQ sections. + +--- + +## Internal-link callout placement + +The pillar links to cluster pieces from within the body, not from a "related reading" footer. + +Pattern. Inside the H2 section that maps to a cluster, place one contextual link to the cluster piece. Position the link at the moment in the section where the reader's curiosity peaks: typically after the section has set up the question and before the answer goes deep. + +Example. In the H2 "What is a kill switch?" section, after the 40 to 60 word answer paragraph, link to the cluster piece on kill switches with the phrase "For the full pattern including code-level implementations, see our [kill switch design guide]." + +Frequency. One link per cluster from the pillar. Two if the cluster maps to two distinct sections of the pillar. Avoid more than two; the second link is the reinforcement, not a third or fourth. + +--- + +## Schema markup choices + +The pillar's primary schema depends on intent. + +Article schema. Default for most pillars. Marks the page as long-form editorial content. + +HowTo schema. When the pillar is a step-by-step guide ("how to launch a feature flag rollout"). HowTo gives Google more structured data to render in SERPs. + +FAQPage schema. Always pair with the FAQ section, not the pillar overall. + +BreadcrumbList schema. Always include for hub navigation context. + +Author schema. Embed Person schema for the author with credentials, bio link, and same-as references to LinkedIn or X. E-E-A-T signal. + +--- + +## Length calibration + +3,000 to 5,000 words is the typical pillar range. Calibrate to the SERP, not to a quota. + +SERP top 10 average word count tells you the band. Pull the top 10; tag word counts; aim for the top 3 average. If the top 3 average 4,200 words, your pillar should target 4,000 to 4,500. + +The depth-vs-length tradeoff. Pillar quality is comprehensiveness AND depth, not just length. A 6,000-word pillar that covers 3 facets in massive depth is worse than a 4,000-word pillar that covers 12 facets at appropriate depth. Length without breadth is not a pillar; it is a long article. + +The cluster offload. Each cluster piece reduces the depth required in the pillar's corresponding section. If kill switches has its own cluster piece, the pillar's kill-switches section can be 300 words pointing to the cluster, not 1,200 words duplicating the cluster. The cluster offload is what keeps the pillar at the right length. + +--- + +## Updates and freshness signals + +The pillar's "last updated" date is a freshness signal. Update it whenever you make material changes (statistics refreshed, new section added, cluster expanded). Do not update it for cosmetic edits; spurious freshness signals are noticed by ranking systems. + +The annual pillar refresh (see `content-refresh-patterns.md`) is the discipline that produces honest freshness signals. diff --git a/skills/pillar-content-architecture/references/topic-selection-criteria.md b/skills/pillar-content-architecture/references/topic-selection-criteria.md new file mode 100644 index 0000000..f5505a5 --- /dev/null +++ b/skills/pillar-content-architecture/references/topic-selection-criteria.md @@ -0,0 +1,104 @@ +# Topic selection criteria + +The five-criterion framework for pillar topic selection, with worked examples across business types. + +--- + +## The five criteria + +A topic earns pillar status only when all five hold. Failing one is a hard signal to stop. + +### 1. Search volume justifies the investment + +The pillar will cost 3 to 6 weeks of editorial effort and 8 to 15 cluster pieces. The topic needs enough monthly search demand to repay the investment over a 3 to 5 year horizon. + +Heuristic. Pillar topic with combined volume across the keyword cluster of 1,000+ monthly searches usually justifies a pillar. Below 500 combined monthly searches, the topic is probably a single cluster piece under a broader pillar, not its own pillar. + +Exception. High-commercial-value topics with low volume (enterprise B2B SaaS niches, expensive professional services) can justify pillars at lower volumes because each ranking visit is worth more. + +### 2. Topic has natural facets + +A pillar covers a topic with internal structure. The team should be able to brainstorm 8 to 15 distinct subtopics, each capable of being a standalone cluster piece. + +The test. Spend 30 minutes listing facets. If the list reaches 12 organically, the topic has the structure. If the list stalls at 5, the topic is a cluster, not a pillar. + +Common false positive. Listing 12 keyword variations of "what is X" is not 12 facets. It is one facet (definition) said 12 ways. True facets are dimensionally different (definition, how-to, comparison, mistakes, costs, alternatives, examples, case studies). + +### 3. Commercial relevance + +The topic connects to the business model. A pillar without commercial signal is content marketing for content marketing's sake. + +The test. Can you draw a line from "reader lands on this pillar" to "reader becomes customer or contributor of customer-related signal"? If yes, the topic is commercially relevant. If the line requires three hops and a leap of faith, the topic is too far from the business. + +### 4. Competitive feasibility + +Top 10 SERP for the pillar keyword is achievable for the brand at its current authority. If the SERP is dominated by Wikipedia, government sites, and global household-name brands, your pillar will rank position 47 no matter how good it is. + +The test. Pull the SERP top 10. Tag each result by domain authority and commercial profile. If the top 10 are all DR 80+ household names and your brand is DR 35, do not start the pillar. Either pick a less-competitive long-tail variant or build authority on adjacent topics first. + +### 5. Editorial commitment + +The team will maintain the pillar for 3 to 5 years: annual refresh, cluster expansion, ownership through team changes. + +The test. Name the durable owner. If the owner is "the marketing team" instead of a specific person with a 12-month commitment, the pillar will not get maintained. Pillars without owners decay; the decay is invisible until the traffic drop is unrecoverable. + +--- + +## Worked example: B2B SaaS + +The brand is a feature-flag platform competitor (DR 45). Considering a pillar on "feature flag rollout strategies." + +- Volume: 2,400 combined monthly searches across the cluster. ✓ +- Facets: 14 listed (rollout strategies, naming conventions, lifecycle, governance, kill switches, technical debt, multi-environment, A/B testing integration, etc.). ✓ +- Commercial: pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes LaunchDarkly (DR 78), Statsig (DR 65), and several DR 60+ blogs. Tight but not impossible at DR 45 with strong cluster support. ✓ (with effort) +- Commitment: PM and content lead jointly own; renewal review every 12 months. ✓ + +Decision: pillar candidate. Plan a 12-cluster hub. + +--- + +## Worked example: ecommerce + +A direct-to-consumer skincare brand (DR 38). Considering a pillar on "retinol routine for beginners." + +- Volume: 8,500 combined monthly searches. ✓ +- Facets: 11 listed (intro, how to start, percentages, frequency, side effects, sun pairing, age considerations, mixing with other actives, sensitive-skin variant, pregnancy considerations, troubleshooting). ✓ +- Commercial: high; pillar visitors are exactly the buyer audience. ✓ +- Competitive: top 10 includes The Ordinary blog, Paula's Choice, Reddit threads, dermatology sites. Mixed authority; achievable at DR 38 with cluster depth and original photography. ✓ +- Commitment: brand educator owns; refresh every 12 months. ✓ + +Decision: pillar. Plan a 10 to 12 cluster hub. + +--- + +## Worked example: services business + +A regional accounting firm (DR 28). Considering a pillar on "small business tax preparation." + +- Volume: 1,200 combined monthly searches. ✓ +- Facets: 12 listed (deductions, quarterly estimates, software comparison, when to hire vs DIY, common mistakes, audit risk, retirement contributions, payroll tax, sales tax, state-specific notes, multi-state operations, business structure choice). ✓ +- Commercial: very high; readers are local prospective clients. ✓ +- Competitive: top 10 includes Intuit, H&R Block, IRS itself, AICPA. Hard at DR 28. ✗ + +Decision: do not pursue this pillar. Instead, scope to a niche the brand can win: "small business tax preparation in [city]" with a pillar focused on the local-business audience and local SEO signals where DR matters less. + +--- + +## Worked example: media or publishing + +A career-focused publication (DR 55). Considering a pillar on "remote work productivity." + +- Volume: high. ✓ +- Facets: easily 15+. ✓ +- Commercial: ad-driven; pillar traffic monetizes through display and email signups. Indirect but real. ✓ +- Competitive: top 10 is moderately authoritative; achievable. ✓ +- Commitment: senior editor owns. ✓ + +Decision: pillar. Note the commercial-signal pattern is different from B2B SaaS or ecommerce; the funnel is impressions to audience growth rather than impressions to qualified lead. Same architecture, different success metrics. + +--- + +## When to walk away + +If three or more criteria fail, walk away from the pillar idea. If exactly one criterion fails (usually competitive feasibility), see whether a long-tail variant of the topic resolves the failed criterion. The "long-tail variant pivot" is the most common save: instead of "feature flags" (DR 78 incumbents), pick "feature flags for [niche]" (DR 50 incumbents) where the brand can compete. diff --git a/skills/pillar-content-architecture/references/topical-authority-signals.md b/skills/pillar-content-architecture/references/topical-authority-signals.md new file mode 100644 index 0000000..547a43d --- /dev/null +++ b/skills/pillar-content-architecture/references/topical-authority-signals.md @@ -0,0 +1,126 @@ +# Topical authority signals + +SEO and AEO/GEO signals at the hub level. Two-engine optimization framing. + +--- + +## Why hubs produce stronger signals than orphans + +Search engines and AI engines both read internal-link graphs and content patterns to infer topical authority. A hub with 12 connected pieces produces signals an orphan set cannot match: + +- Density of internal links on the topic. PageRank flows within the hub; pages reinforce each other. +- Comprehensive entity coverage across pieces. The hub mentions more named tools, methods, experts, and statistics than any single piece could. +- Repeated topical signal at scale. Multiple pieces with overlapping topical vocabulary, distinct facets, consistent structure. +- Crawl-rate compounding. Search engines crawl high-link-density clusters more frequently; AI engines re-index hubs more aggressively. + +Same total content volume; different architectural outcome. 12 orphans on the same topic produce scattered, weaker signals than a 12-piece hub. + +--- + +## SEO signals at the hub level + +### Internal-link graph density + +Google's PageRank algorithm flows authority through internal links. A pillar with 12 cluster pieces linking back to it concentrates PageRank on the pillar; the pillar in turn passes authority to clusters via top-down links. The graph shape compounds. + +Heuristic. Compare PageRank on a pillar before and after the cluster ships. Most teams see ranking improvements on the pillar within 3 to 6 months as the cluster matures. + +### Comprehensive entity coverage + +The hub mentions more named entities than any single page could: tools, methods, experts, datasets, frameworks. Search engines extract entity graphs at crawl time; comprehensive coverage signals topical depth. + +The discipline. Each piece in the hub mentions the topic's required entities (entities the SERP top 10 share) and the gap entities (entities only 1 or 2 SERP results mention). The hub-level entity graph is the union across all pieces. + +### URL structure clarity + +The `/topic/cluster-piece/` pattern signals topical grouping. Crawlers follow the URL hierarchy and infer the hub structure even before parsing internal links. + +### Breadcrumb hierarchy + +BreadcrumbList schema tells crawlers the hub structure explicitly. Some SERPs surface breadcrumb URLs as rich-result enhancements. + +### Schema markup at scale + +Article, HowTo, FAQPage, BreadcrumbList schema across the hub. Each schema type passes additional structured data to crawlers. The hub is structured for extraction in a way that orphan content rarely is. + +### E-E-A-T signals + +Experience, Expertise, Authoritativeness, Trustworthiness. Google's quality framework. Hub-level E-E-A-T comes from: + +- Author credentials displayed on every piece (with Person schema) +- Expertise demonstrated through depth and accuracy +- Authoritativeness signaled by entity coverage and citations +- Trustworthiness signaled by clear authorship, last-updated dates, and corrections to prior work when relevant + +E-E-A-T is not a discrete signal; it is the aggregate of many small signals. Hubs accumulate E-E-A-T faster than orphans because the signals compound across pieces. + +--- + +## AEO and GEO signals at the hub level + +AI engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Mode) cite content based on different patterns than traditional search ranking. Hubs serve AI engines as well as search engines if the right signals are present. + +### Answer-paragraph format under H2 headings + +40 to 60 word self-contained answers immediately following H2 questions. AI engines extract these as citation candidates. The pattern repeats across pillar and clusters; the hub becomes a structured set of citation-ready answers. + +### TL;DR section on pillars + +The pillar's TL;DR (150 to 250 words) is the most-cited section by AI engines. Place it at the top, make it self-contained, write it as the canonical summary. + +### FAQPage schema + +AI engines (Perplexity especially) heavily cite FAQPage-marked content. Pair every pillar's FAQ section with FAQPage schema. Cluster pieces with genuine FAQs also benefit. + +### Specific statistics with cited sources + +"23% of feature flag rollouts include a kill switch (Feature Flag Survey 2025, n=412)" cites better than "many feature flag rollouts include a kill switch." Specific numbers with sources are higher-citation signals; vague qualifiers are lower-citation. + +### Named experts and named methods + +"As Adam Kalai noted in the original CUPED paper" cites better than "experts have shown." Named attribution earns citation; anonymous attribution does not. The hub should mention 5+ named experts or methods across pillar and clusters. + +### Distinctive POV + +AI engines preferentially cite content with a clear, attributable position. "Kill switches should be the first safety mechanism designed, not the last" is a POV. "Kill switches are important" is not. The hub's POV is the brand's editorial position; consistency across pieces reinforces attribution. + +--- + +## The two-engine optimization + +Pillars and clusters serve search engines and answer engines together, not as competing optimizations. + +Both reward depth. Search engines reward comprehensive treatment of a topic. AI engines reward citation-ready depth. Same content; different extraction. + +Both reward structure. Search engines parse heading hierarchy for ranking. AI engines parse heading hierarchy for citation extraction. Same structure; different use. + +Both reward entity coverage. Search engines use entities for topical relevance. AI engines use entities for retrieval and citation. Same entities; different scoring. + +Both reward freshness. Search engines reward recent updates. AI engines re-index recently-updated content more aggressively. Same updates; different cadence. + +The implication. Optimizing for AEO/GEO does not trade off against SEO. The hub architecture that earns search rankings is the same architecture that earns AI citations. Teams that treat them as separate optimizations under-invest in both. + +--- + +## Measuring topical authority signals + +Hub-level metrics worth tracking: + +Search-side: + +- Aggregate organic traffic to all pieces in the hub +- Average position for the pillar's primary keyword +- Number of cluster pieces ranking in top 10 for their target keywords +- Internal-link count per cluster piece (from inventory) +- Crawl frequency (Google Search Console) + +AI-side: + +- Brand mention rate from Profound, Frase, AirOps, or similar tools +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude) +- Top-cited pieces (which clusters get cited most often) +- AI crawler hit frequency (server logs, Profound Agent Analytics) + +The hub-level dashboard composes these metrics. Tracking at the hub level (not per piece) is what surfaces architecture-level patterns: which clusters drive traffic, which clusters drive citations, which clusters are dead weight. + +See the `seo-aeo-geo` skill for AEO/GEO program-level strategy. diff --git a/skills/pillar-content-architecture/references/url-structure-patterns.md b/skills/pillar-content-architecture/references/url-structure-patterns.md new file mode 100644 index 0000000..1b498c0 --- /dev/null +++ b/skills/pillar-content-architecture/references/url-structure-patterns.md @@ -0,0 +1,105 @@ +# URL structure patterns + +Subfolder vs subdomain decision, slug conventions, breadcrumbs, the /blog/ trap. + +--- + +## Subfolder vs subdomain + +The default for hubs is subfolder. Subdomain has narrow valid use cases. + +Subfolder pattern. `example.com/feature-flag-rollout/` for the pillar; `example.com/feature-flag-rollout/kill-switches/` for cluster pieces. Both pillar and cluster live on the same domain authority; PageRank flow is consolidated; the hub compounds within the brand's existing SEO equity. + +Subdomain pattern. `docs.example.com`, `community.example.com`, `support.example.com`. Used when the property is genuinely distinct (different audience, different content type, different team ownership). Subdomains receive less of the parent domain's authority signal in most analyses; do not split a hub across subdomains without a strong reason. + +Decision rule. Pillar plus cluster always on the same subdomain as the rest of the marketing content. If the brand's marketing content lives at `example.com`, the hub lives at `example.com/[hub]/`. Splitting the hub onto a subdomain treats the hub as a separate property, which is almost never correct. + +--- + +## Hub URL pattern + +The pattern: `/hub-topic/` for the pillar, `/hub-topic/cluster-piece/` for clusters. + +Why this pattern. The URL itself signals topical grouping. Crawlers see the path structure and infer that pages under `/feature-flag-rollout/` belong to a topical hub. Readers see the breadcrumb in the URL and know where they are. + +The /blog/ alternative. `/blog/feature-flag-rollout/` and `/blog/kill-switches/`. This works structurally; the pieces still rank. But the hub signal is weaker because the URL groups by content type (blog) rather than by topic. Two unrelated blog posts share the `/blog/` path; nothing in the URL says "kill-switches is part of the feature-flag-rollout hub." + +The fix when migrating off /blog/. Change the URL pattern via 301 redirects from old to new. Lose some short-term ranking equity during the redirect; gain long-term hub-signal clarity. The migration is worth it for major hubs; not worth it for smaller content sets. + +--- + +## Slug conventions + +Short, descriptive, keyword-aware but not stuffed. + +Good: `/feature-flag-rollout/kill-switches/` + +Bad: `/feature-flag-rollout/the-ultimate-guide-to-implementing-kill-switches-in-feature-flag-rollouts-2026/` + +Why short. Long slugs read as keyword-stuffed and break in social shares, email previews, and conversational mentions. Search engines do not need every keyword in the URL; they parse the page content. + +Why descriptive. The slug should make sense as a standalone string. `/feature-flag-rollout/kill-switches/` is self-describing; `/post-1247/` is not. + +Keyword-aware. Include the primary keyword for the cluster piece. Do not include the supporting cluster keywords (those go in the page content, not the URL). + +Date-free. Avoid dates in slugs (`/2026-rollout-guide/`). Dated slugs anchor the piece in time; refreshing the piece in 2027 is awkward. Pieces with date-relevant content (annual reports, year-in-review) are exceptions. + +Hyphens, not underscores. Search engines treat hyphens as word separators; underscores as part of one word. `kill-switches` reads as two words; `kill_switches` reads as one. + +Lowercase. Mixed-case URLs cause case-sensitivity confusion across servers and create duplicate-content issues. + +--- + +## Breadcrumb structure + +Breadcrumbs surface the hub structure in the page UI and the page schema. The pattern: + +`Home > Hub topic > Cluster piece` + +In the UI, breadcrumbs typically render as a small horizontal nav above the title. In schema, BreadcrumbList markup tells crawlers the path. + +Why breadcrumbs help. Readers see they are in a hub and can navigate up. Crawlers parse the BreadcrumbList schema and reinforce the hub hierarchy. Some SERPs also surface breadcrumb URLs in rich results. + +Breadcrumb anti-pattern. Breadcrumbs that show URL segments instead of human-readable labels. `Home > /feature-flag-rollout > /kill-switches` is the wrong format. Use the hub's display name and the cluster piece's title, not the URL slug. + +Schema example. + +```json +{ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": [ + { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" }, + { "@type": "ListItem", "position": 2, "name": "Feature flag rollout", "item": "https://example.com/feature-flag-rollout/" }, + { "@type": "ListItem", "position": 3, "name": "Kill switches" } + ] +} +``` + +The third item omits "item" because breadcrumbs typically do not link to the current page. + +--- + +## The /blog/ trap + +The symptom. The team's content all lives at `/blog/[slug]/` because that is how the CMS is configured. Pillar and cluster live alongside unrelated blog posts in the same flat URL space. + +The diagnosis. The CMS folder defaulted to `/blog/`. Nobody changed it because changing CMS routing is non-trivial. Hub structure exists in the editorial team's head but not in the URL. + +The cost. Hub signal is weakened; PageRank flow is less topically concentrated; readers cannot tell from the URL that a piece is part of a hub. + +The fix. Change CMS routing to support topic-based subfolders. Migration via 301 redirects from old `/blog/` URLs to new `/[hub]/` URLs. Take a short-term ranking hit during redirect; gain long-term hub authority. + +The "do not migrate" exception. If the existing `/blog/` URL structure is generating significant traffic and the hub investment is small, the migration may not pay back. Score the migration cost against the hub's commercial value; migrate only when the hub justifies it. + +--- + +## Multilingual or multi-region URL patterns + +Hubs that span languages or regions add another structural decision. The two main patterns: + +Subfolder per locale. `example.com/en/[hub]/`, `example.com/de/[hub]/`. Cleanest for SEO consolidation; clearest for crawlers. + +ccTLD per region. `example.de/[hub]/`, `example.fr/[hub]/`. Stronger for regional ranking but splits domain authority. + +The decision usually depends on the brand's existing internationalization choice; the hub follows the existing pattern. Do not use the hub launch as the moment to switch internationalization strategies. diff --git a/skills/pm-spec-writing/SKILL.md b/skills/pm-spec-writing/SKILL.md new file mode 100644 index 0000000..abb72ad --- /dev/null +++ b/skills/pm-spec-writing/SKILL.md @@ -0,0 +1,226 @@ +--- +name: pm-spec-writing +description: "Translate ideas, feature requests, or vague concepts into specific, actionable dev briefs. Use this skill whenever the user has an idea they want to build, a feature to spec out, a bug to file, a project to scope, or needs to convert a half-formed idea into a clear implementation brief. Triggers on I want to add, we should build, can we make, what is the plan for, how do we implement, dev brief, feature spec, PRD, user story, acceptance criteria, scope this, prioritize. Also triggers when the user has a list of things they want to build and needs help converting them into well-formed tasks." +category: product +catalog_summary: "PRDs, user stories, acceptance criteria, dev briefs" +display_order: 1 +--- + +# PM Spec Writing + +Take an idea (often vague) and turn it into a specification a developer or AI agent can actually build from. Stack-agnostic. Works for new features, bug fixes, content changes, or infrastructure work. + +--- + +## When to use + +- Translating an idea into a buildable feature spec +- Writing a PRD or product requirement document +- Filing a bug report that someone else can act on +- Scoping a project before kickoff +- Prioritizing a backlog of feature requests +- Writing acceptance criteria for an existing feature +- Breaking a large initiative into shippable increments + +## When NOT to use + +- Quarterly or annual planning across multiple initiatives (use `roadmap-planning`) +- Code review or debugging existing code (use `code-review-web`) +- Design decisions for a feature already specced (use `design-standards`) +- User research to validate an idea (use `ux-research`) + +--- + +## Required inputs + +- The idea, request, or problem being addressed +- The audience or user affected +- Any existing constraints (stack, deadlines, dependencies) +- The success metric (how will you know it worked?) + +If the idea is vague, the workflow's first step is clarification. Do not write specs around vagueness. + +--- + +## The framework: 4 phases + +Every PM workflow follows the same arc. The phases are universal even if the specific outputs vary. + +### Phase 1: Clarify the idea + +Before any spec, answer four questions. If any answer is "I don't know," go back to the user. + +1. What user problem does this solve? Not "what does it do." The problem comes first; the feature is the proposed solution. +2. Who specifically benefits? Be precise. "Users" is not specific. "First-time visitors who don't convert" is. +3. What is the success metric? How will you know it worked? Pick one primary metric. +4. Why now? What changed that makes this the right time to build it? If "nothing changed," it might not be the right time. + +### Phase 2: Scope by impact and effort + +Plot every candidate idea on the impact/effort grid: + +``` +HIGH IMPACT / LOW EFFORT Ship immediately + Examples: copy fixes, contrast fixes, meta tags, + broken links, missing alt text, redirects + +HIGH IMPACT / HIGH EFFORT Plan and batch + Examples: new page type, new feature, schema overhaul, + major redesign, new integration + +LOW IMPACT / LOW EFFORT Nice-to-have batch + Examples: tooltip improvements, minor copy polish, + cosmetic UX touches + +LOW IMPACT / HIGH EFFORT Skip or defer indefinitely + Examples: rebuilding what already works, exotic + edge case features, premature optimization +``` + +This is not a perfect framework. Some "low impact" things are mandatory (compliance, accessibility, security). Note exceptions. + +### Phase 3: Write the spec + +Three formats based on the type of work. + +#### Format A: Feature spec (for new features) + +``` +TITLE: [Specific, action-oriented] + +PROBLEM +[1-2 sentences. The user problem and current state.] + +USERS +[Who specifically benefits. Be precise about the user segment.] + +PROPOSAL +[1 paragraph. The proposed solution. Stay at the conceptual level.] + +USER STORIES +- As a [user type], I want to [action], so that [outcome] +- As a [user type], I want to [action], so that [outcome] + +ACCEPTANCE CRITERIA +- Given [context], when [action], then [expected outcome] +- Given [context], when [action], then [expected outcome] + +OUT OF SCOPE +[What this spec explicitly does NOT cover. Important for scope control.] + +DEPENDENCIES +[Other systems, APIs, designs, content needed before this can ship.] + +SUCCESS METRIC +[The one primary metric that tells us this worked. With current baseline if known.] + +ESTIMATED EFFORT +[Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (sprints)] + +PRIORITY +[P0 launch blocker / P1 next sprint / P2 within quarter / P3 backlog] +``` + +#### Format B: Dev brief (for handing to a developer or AI agent) + +For tactical, ready-to-build work. Lighter than a full spec. + +``` +CONTEXT: [1-2 sentences explaining why this matters] + +TASK: [Specific files, exact changes needed] + +CONSTRAINTS: [What must NOT change, what to preserve] + +VERIFY: [Exact steps to confirm the work is done correctly] +``` + +The verify section is the most-skipped and most-important. Without it, "done" means whatever the implementer thinks done means. + +#### Format C: Bug report + +``` +URL or context: [Where it happens] + +Symptom: [What the user sees or experiences] + +Expected: [What should happen instead] + +Steps to reproduce: +1. [Specific step] +2. [Specific step] +3. [Specific step] + +Hypothesis: [Likely root cause if known] + +Files to investigate: [Likely files involved if known] + +Priority: + P0 - blocking critical user flow, ship immediately + P1 - degrades UX significantly, fix this sprint + P2 - minor issue, fix when convenient + P3 - nice-to-have improvement + +Browser/device: [If reproducibility might be browser-specific] +``` + +### Phase 4: Sequence and ship + +Specs without sequencing become dust on a shelf. + +For a single feature: identify the smallest shippable increment. What is the smallest version that delivers user value? Ship that first. Then iterate. + +For a backlog: order by dependencies first, then by priority, then by impact/effort. The order matters more than the priority labels. + +--- + +## Workflow + +1. Clarify. If the idea is vague, ask the four phase-1 questions before proceeding. +2. Scope. Plot the work on the impact/effort grid. +3. Pick the right format. Feature spec for new features, dev brief for tactical work, bug report for defects. +4. Write the spec. Use the template format. Fill in every section. Empty sections are flags. +5. Define done. Verify steps must be unambiguous. "Test it" is not a verify step. +6. Get buy-in. Walk through the spec with whoever will build it before they start. +7. Sequence. Identify the smallest shippable increment. + +--- + +## Failure patterns + +- Specs that describe solutions before problems. Always start with the user problem. The solution is downstream. +- Specs without a success metric. Without a metric, you cannot tell if the feature worked. +- Acceptance criteria that are not testable. "User experience is improved" is not testable. "User completes signup in under 60 seconds" is. +- Specs that include the "how" instead of the "what." Implementation details belong in the dev brief, not the spec. The spec is the desired outcome. +- No "out of scope" section. Without explicit boundaries, scope creeps. +- Bug reports without reproduction steps. Cannot be acted on. Always include steps. +- Verify steps that are vague. "Make sure it works." Useless. Must be specific actions with observable outcomes. +- Skipping the smallest-shippable-increment exercise. Leads to 6-month projects that should have been 2-week experiments. + +--- + +## Output format + +Output is one of three formats based on work type, all in markdown: + +- `spec-[feature-name].md` for feature specs +- `brief-[task-name].md` for dev briefs +- `bug-[summary].md` for bug reports + +For larger initiatives, group related specs in a folder: +``` +specs/ + initiative-name/ + spec-feature-1.md + spec-feature-2.md + brief-task-1.md + README.md (overview and sequencing) +``` + +--- + +## Reference files + +- [`references/feature-spec-template.md`](references/feature-spec-template.md) - Full feature spec template. +- [`references/dev-brief-template.md`](references/dev-brief-template.md) - Compact dev brief template for tactical work. +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Beyond impact/effort: RICE, weighted scoring, MoSCoW. diff --git a/skills/pm-spec-writing/references/dev-brief-template.md b/skills/pm-spec-writing/references/dev-brief-template.md new file mode 100644 index 0000000..289ffef --- /dev/null +++ b/skills/pm-spec-writing/references/dev-brief-template.md @@ -0,0 +1,207 @@ +# Dev Brief Template + +A dev brief is the lightweight version of a spec. Used for tactical work that does not need a full PRD: bug fixes, copy changes, small feature additions, infrastructure tweaks. + +The brief is structured to be handed directly to a developer or AI agent. They should be able to act on it without follow-up questions. + +--- + +## Template + +``` +TASK: [One-sentence summary of what to do] + +CONTEXT +[1 to 2 sentences. Why this matters. What problem it solves.] + +WHAT TO DO +[Specific changes. List the exact files (if known), the exact behavior to change, the exact copy to update. Be unambiguous.] + +CONSTRAINTS +[What must NOT change. What to preserve. What's out of bounds.] + +VERIFY +[Exact steps to confirm the work is done correctly. Each step should produce an observable outcome that proves the change worked.] + +DEPENDENCIES +[Anything that must be done first, or that this depends on.] + +PRIORITY +[P0 / P1 / P2 / P3 with one-line reason] + +ESTIMATED TIME +[Minutes or hours - not days. If it would take days, write a feature spec instead.] +``` + +--- + +## Example: Bug fix brief + +``` +TASK: Fix the broken submit button on the contact form + +CONTEXT +Users reported that the contact form submit button does not respond on mobile Safari. +This is blocking lead capture from a major traffic source. + +WHAT TO DO +- Investigate components/forms/ContactForm.tsx +- Check the onClick handler and form submission logic +- The issue is likely related to a recent change to the button onClick handler; + check git log for the most recent commit touching this component +- Fix so submit fires on tap as well as click + +CONSTRAINTS +- Do not change any other forms in the codebase +- Do not modify the form validation logic +- Preserve the existing visual design of the button + +VERIFY +1. Open contact form on mobile Safari (or device-mode in browser) +2. Fill required fields with valid data +3. Tap submit button +4. Confirm form submits and success message displays +5. Repeat on Chrome and Firefox to ensure no regression +6. Check browser console for errors after submit + +DEPENDENCIES +None. Self-contained fix. + +PRIORITY +P1 - blocking lead capture from primary traffic source + +ESTIMATED TIME +30 to 60 minutes +``` + +--- + +## Example: Copy change brief + +``` +TASK: Update homepage hero copy to match new positioning + +CONTEXT +The marketing team has finalized the new positioning statement. +The current hero copy is from the previous brand iteration and needs updating. + +WHAT TO DO +File: pages/index.tsx (or app/page.tsx in App Router) + +Change the hero H1 from: + "The all-in-one platform for modern teams" +To: + "Move work forward without moving the meeting" + +Change the hero subheadline from: + "Streamline your workflow with our innovative collaboration suite" +To: + "Async-first project management for distributed teams that ship." + +Change the primary CTA button text from: + "Get started" +To: + "Start free trial" + +CONSTRAINTS +- Do not change the hero image +- Do not change the secondary CTA +- Preserve all existing styling and component structure + +VERIFY +1. Reload the homepage in a browser +2. Confirm new H1, subheadline, and CTA text display correctly +3. Confirm visual layout is unchanged (no new layout shifts) +4. Confirm responsive behavior on 375px viewport +5. Run a Lighthouse pass to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P1 - aligned with brand launch on [date] + +ESTIMATED TIME +15 to 30 minutes +``` + +--- + +## Example: Small feature brief + +``` +TASK: Add an estimated reading time to blog post pages + +CONTEXT +Users have asked for an indication of how long a post takes to read. +Improves perceived value and helps users decide whether to start reading. + +WHAT TO DO +- Calculate reading time as word count / 200 words per minute, rounded up +- Display below the post title, alongside the publish date +- Format: "5 min read" (with the minute count appropriate to length) +- Apply to all blog post pages (single post template) + +Suggested implementation: +- Compute server-side from the post body content +- Add to the post component's metadata section +- Style consistently with the existing publish date + +CONSTRAINTS +- Must work for posts of any length (test 1 minute to 30+ minute posts) +- Must not affect SEO (e.g., no JS-rendering for crawlers) +- Must not regress page load performance + +VERIFY +1. Open 3 different blog posts of varying length +2. Confirm reading time displays correctly for each +3. Verify the calculation is right (count words manually for a short post) +4. Check the rendered HTML to confirm the value is server-rendered, not JS +5. Confirm visual styling matches the publish date treatment +6. Run Lighthouse to confirm no performance regression + +DEPENDENCIES +None. + +PRIORITY +P2 - nice user enhancement, no urgency + +ESTIMATED TIME +1 to 2 hours including QA +``` + +--- + +## What makes a good brief + +Context answers "why am I doing this?" Without it, the implementer cannot make good judgment calls. + +What to do is specific. Names files when known. Quotes exact copy when copy is changing. Describes desired behavior unambiguously. + +Constraints prevent scope creep. Especially for AI agents who tend to "improve" things outside the task. + +Verify is the most-skipped section and the most important. Each verify step must be: +- Observable (you can see whether it passed or failed) +- Specific (no "make sure it works") +- Sufficient (if all verify steps pass, the work is genuinely done) + +Dependencies prevent the implementer from starting work that's blocked. + +Priority sets expectations on order. + +Estimated time sets expectations on effort. Briefs are for work measured in minutes to a few hours. Days-long work should be a feature spec. + +--- + +## When NOT to use a dev brief + +If the work has any of the following, write a feature spec instead: + +- Multiple stakeholders need to weigh in +- The user-facing behavior needs design review +- The change affects multiple parts of the system +- The estimate exceeds 1 day of work +- The success metric is non-obvious +- The work cannot be verified by a few specific steps + +A dev brief is for "do this exact thing." A feature spec is for "build this product capability." diff --git a/skills/pm-spec-writing/references/feature-spec-template.md b/skills/pm-spec-writing/references/feature-spec-template.md new file mode 100644 index 0000000..48c4447 --- /dev/null +++ b/skills/pm-spec-writing/references/feature-spec-template.md @@ -0,0 +1,192 @@ +# Feature Spec: [Feature Name] + +Author: [Name] +Date: [YYYY-MM-DD] +Status: [Draft / In Review / Approved / In Development / Shipped] +Target ship: [Date or sprint] + +--- + +## TL;DR + +[2 to 3 sentences. What this is, who it's for, why it matters. If a stakeholder reads only this section, they should understand the proposal.] + +--- + +## Problem + +[1 to 2 paragraphs. The user problem. The current state and why it's inadequate. Include data if available (analytics, support tickets, user research quotes).] + +### Evidence + +- [Specific data point or research finding] +- [Specific data point or research finding] +- [Specific data point or research finding] + +--- + +## Users + +Primary user: [Specific user segment that benefits most] + +Use cases: +1. [Specific scenario where this user encounters the problem] +2. [Specific scenario] +3. [Specific scenario] + +Secondary users: [Other segments affected] + +Anti-users: [Segments this feature is NOT for; helps prevent scope creep] + +--- + +## Proposal + +[1 paragraph at the conceptual level. The solution, not the implementation. Stay at "what" not "how".] + +### How it works (high level) + +[3 to 5 bullets describing the user experience flow. Still high level; not implementation details.] + +1. [User action] +2. [System response] +3. [User action] +4. [System response] + +--- + +## User stories + +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. +- As a [user type], I want to [action], so that [outcome]. + +--- + +## Acceptance criteria + +The feature ships when ALL of these are true. + +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Given [context], when [action], then [expected outcome] +- [ ] Given [context], when [action], then [expected outcome] +- [ ] [Additional criteria] +- [ ] [Additional criteria] + +Each criterion must be observable and testable. If you cannot verify it with a specific check, rewrite it. + +--- + +## Out of scope + +[Explicit boundaries. What this spec does NOT cover. Critical for scope control.] + +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] +- [Thing explicitly not included, with reason] + +--- + +## Dependencies + +### Required before development can start +- [ ] [Design completed and approved] +- [ ] [API contracts defined] +- [ ] [Content delivered] +- [ ] [Legal/compliance review if applicable] + +### External systems or services +- [System or service]: [What we depend on] +- [System or service]: [What we depend on] + +### Team dependencies +- Design: [What's needed and who owns it] +- Engineering: [Specific resources and timeline] +- Content: [If applicable] +- Marketing: [If launch-related] + +--- + +## Success metric + +Primary metric: [The one metric that tells us this worked] + +Current baseline: [If known] + +Target: [What success looks like quantitatively] + +Measurement window: [When and for how long we measure] + +Secondary metrics (signals to watch): +- [Metric] - [why it matters] +- [Metric] - [why it matters] + +Negative signals (what would tell us this hurt): +- [Metric] - [threshold for concern] +- [Metric] - [threshold for concern] + +--- + +## Estimated effort + +Size: [Small (hours) / Medium (1-3 days) / Large (1-2 weeks) / XL (multiple sprints)] + +Breakdown: +- Design: [hours/days] +- Frontend: [hours/days] +- Backend: [hours/days] +- QA: [hours/days] +- Content: [hours/days] +- Total: [estimated] + +--- + +## Priority + +P0 Launch blocker - must ship before [event/launch] +P1 Next sprint - high impact, addressable now +P2 Within quarter - valuable but not urgent +P3 Backlog - nice-to-have, no commitment + +This spec: [P0 / P1 / P2 / P3] + +Reasoning: [Why this priority] + +--- + +## Open questions + +[Things that need to be decided before development can start, or before the feature can ship.] + +- [ ] [Question] - Owner: [Who decides] - Decision needed by: [Date] +- [ ] [Question] - Owner: [Who decides] - Decision needed by: [Date] + +--- + +## Risks and mitigations + +\| Risk \| Likelihood \| Impact \| Mitigation \| +\|---\|---\|---\|---\| +\| [Risk description] \| High/Med/Low \| High/Med/Low \| [How we'll mitigate] \| +\| [Risk description] \| \| \| \| + +--- + +## Smallest shippable increment + +MVP: What is the simplest version that delivers user value? + +[Description of the MVP. Shippable in 1 to 2 weeks for most features. If you can't describe an MVP that fits, the feature is too big and should be split.] + +Future iterations (NOT in MVP, may come later): +- [Iteration 1] +- [Iteration 2] +- [Iteration 3] + +--- + +## Changelog + +\| Date \| Author \| Change \| +\|---\|---\|---\| +\| YYYY-MM-DD \| [Name] \| Initial draft \| diff --git a/skills/pm-spec-writing/references/prioritization-frameworks.md b/skills/pm-spec-writing/references/prioritization-frameworks.md new file mode 100644 index 0000000..0fb7f3d --- /dev/null +++ b/skills/pm-spec-writing/references/prioritization-frameworks.md @@ -0,0 +1,219 @@ +# Prioritization Frameworks + +Beyond the simple impact/effort grid, there are several frameworks for prioritizing work. Each is useful in different situations. None is universally correct. + +--- + +## Impact / Effort matrix + +The simplest and most common. + +How it works: plot every candidate on a 2x2 grid. + +``` + Low Effort High Effort + +High Impact Quick wins Major projects + (Ship now) (Plan and batch) + +Low Impact Backlog batch Skip or defer + (When time allows) (Reconsider) +``` + +Strengths: Fast. Forces blunt judgment. Useful for triage. + +Weaknesses: Subjective. "Impact" and "effort" are estimates that get inflated. + +When to use: Triage of a long list. Initial sorting. + +--- + +## RICE + +A weighted scoring method that produces a numeric priority score. + +How it works: + +``` +RICE Score = (Reach × Impact × Confidence) / Effort +``` + +- Reach: How many users this affects per period (e.g., per quarter). Use real numbers. +- Impact: The per-user impact, scored on a fixed scale: + - 3 = Massive (transformative) + - 2 = High (significant lift) + - 1 = Medium (modest lift) + - 0.5 = Low (minor lift) + - 0.25 = Minimal (barely noticeable) +- Confidence: How certain you are of the reach and impact estimates, as a percentage. + - 100% = high confidence (data-backed) + - 80% = medium confidence (some evidence) + - 50% = low confidence (mostly intuition) +- Effort: Person-months (or person-weeks for smaller work). + +Example: + +A new onboarding flow: +- Reach: 5,000 new users per quarter +- Impact: 1 (modest improvement to activation) +- Confidence: 80% +- Effort: 2 person-months + +RICE = (5000 × 1 × 0.8) / 2 = 2,000 + +A bug fix on a rarely-used page: +- Reach: 50 users per quarter +- Impact: 2 (significant for those affected) +- Confidence: 100% +- Effort: 0.25 person-months + +RICE = (50 × 2 × 1) / 0.25 = 400 + +The onboarding flow scores higher. + +Strengths: Numeric. Forces explicit estimates. Surfaces the math behind judgment. + +Weaknesses: Garbage-in-garbage-out. Reach and impact estimates can be wildly wrong. + +When to use: Comparing across many candidate features. When stakeholders disagree on priority. + +--- + +## MoSCoW + +Categorical, used for release scoping. + +How it works: every item is one of four: + +- Must have - non-negotiable for this release +- Should have - important but not critical +- Could have - nice if time allows +- Won't have - explicitly out of scope (this release) + +Example for a redesign launch: + +- Must: New navigation, mobile responsive, all P0 pages migrated +- Should: New blog template, updated forms +- Could: New illustrations on lower-traffic pages +- Won't: Internationalization (deferred to phase 2) + +Strengths: Clear scope boundaries. Forces explicit "won't have" decisions, which prevent scope creep. + +Weaknesses: Not a framework for relative priority within categories. + +When to use: Defining the scope of a release. Cutting features when timeline pressure hits. + +--- + +## Cost of Delay / Weighted Shortest Job First + +A framework from lean product development. Optimizes for delivering value sooner. + +How it works: + +``` +Priority = Cost of Delay / Job Duration +``` + +- Cost of Delay: What is the cost (in revenue, risk, customer impact) of NOT doing this for one more period? +- Job Duration: How long will this take? + +The work with the highest "Cost of Delay per unit time" gets done first. + +Example: + +A revenue-impacting bug: +- Cost of Delay: $5,000 per week of lost conversions +- Duration: 1 week +- Priority score: 5,000 + +A large feature: +- Cost of Delay: $20,000 per week of unrealized revenue +- Duration: 12 weeks +- Priority score: 1,667 + +Even though the feature has higher absolute cost of delay, the bug ships first because it delivers value faster. + +Strengths: Captures urgency. Useful for revenue-sensitive decisions. + +Weaknesses: Cost of Delay is hard to estimate. + +When to use: Operational backlogs. Revenue-sensitive features. + +--- + +## Value vs Effort with strategic alignment + +A 3-axis variant for when strategic fit matters more than raw impact. + +How it works: score each candidate on: + +- Value (1 to 5) +- Effort (1 to 5, inverted - 5 means low effort) +- Strategic fit (1 to 5) + +Composite score: Value + Effort + Strategic fit. + +Candidates with the highest composite score win. + +Strengths: Captures that some valuable work is wrong for the company right now. + +Weaknesses: Three axes is more complex than most teams can sustain. + +When to use: When the team is being pulled toward locally-valuable work that does not advance the strategy. + +--- + +## The "next thing" framework + +The simplest, for solo founders or very small teams. + +How it works: ask one question: + +> "What is the single most important thing I could ship in the next two weeks?" + +Ship it. Then ask the question again. + +Strengths: Maximum focus. Avoids analysis paralysis. + +Weaknesses: Misses opportunities to batch related work. Susceptible to recency bias. + +When to use: Solo work. When the backlog is short. When velocity matters more than precision. + +--- + +## Choosing a framework + +\| Situation \| Framework \| +\|---\|---\| +\| Long backlog, need triage \| Impact / Effort matrix \| +\| Comparing features for the next quarter \| RICE \| +\| Defining a release scope \| MoSCoW \| +\| Revenue-sensitive operations work \| Cost of Delay / WSJF \| +\| Strategic misalignment risk \| Value + Effort + Strategic fit \| +\| Solo founder, weekly cadence \| "Next thing" \| + +The frameworks are tools. The output is a prioritized list. If the list is helpful and team agrees, the framework worked. If it's not, try another framework or revisit the inputs. + +--- + +## Common pitfalls + +- Framework theater. Spending more time on the framework than the work. Pick one. Move on. +- Estimate inflation. Engineers underestimate effort by 2x. PMs overestimate impact by 3x. Calibrate over time. +- Static prioritization. A one-time sort that never gets revisited. Re-prioritize at least monthly. +- Ignoring sunk cost dynamics. Just because you've worked on something for 3 months does not mean it deserves to ship. Cut your losses if the priority math no longer works. +- Optimizing the wrong metric. A framework's output is only as good as the metric you're optimizing for. Make sure that metric is correct. +- Treating the score as truth. A RICE score is a directional signal, not a verdict. Use judgment alongside the math. + +--- + +## Recommended default + +For most teams, the default is: + +1. Impact / Effort matrix for triage and backlog grooming +2. RICE for comparing feature candidates within a quarter +3. MoSCoW for release scoping when timeline is fixed + +That covers 90 percent of prioritization decisions a typical product team faces. diff --git a/skills/product-analytics-setup/SKILL.md b/skills/product-analytics-setup/SKILL.md new file mode 100644 index 0000000..926677a --- /dev/null +++ b/skills/product-analytics-setup/SKILL.md @@ -0,0 +1,308 @@ +--- +name: product-analytics-setup +description: "How to actually instrument product analytics correctly. Event taxonomy, property design, naming conventions, schema versioning, identity stitching, funnel design, retention cohorts, North Star metric selection, dashboard hygiene, instrumentation debt, and the failure modes that produce data nobody trusts. Triggers on product analytics setup, event taxonomy, tracking plan, instrumentation, schema versioning, North Star metric, retention cohorts, funnel design, naming conventions, instrument new feature, audit existing analytics, dashboard reconciliation, instrumentation debt, Mixpanel setup, Amplitude setup, PostHog setup, warehouse-native analytics. Also triggers when the team has data but cannot trust it, or when designing instrumentation for a new feature, or when auditing an existing setup that has drifted." +category: product +catalog_summary: "Instrument product analytics correctly: event taxonomy, properties, naming conventions, schema versioning, funnels, retention cohorts, North Star selection, and the instrumentation debt that compounds without discipline" +display_order: 8 +--- + +# Product Analytics Setup + +A senior PM and analyst's playbook for instrumenting product analytics correctly the first time. + +Most product analytics setups are some combination of inherited mistakes, dashboard sprawl, and events nobody trusts. The team launches a new feature; instrumentation gets bolted on under deadline pressure; naming drifts; properties are inconsistent; six months later nobody can answer simple questions because the answer depends on which event you trust. + +This skill is the discipline that prevents that. It assumes you have answered the strategic questions about what to measure (see `analytics-strategy`). It assumes you have a tool connected (Mixpanel, Heap, PostHog, Amplitude, or warehouse-native via BigQuery, Snowflake, or dbt). The hard part is the systematic execution: naming conventions, property design, schema versioning, funnel construction, cohort definitions, retention measurement. + +When to use this skill: setting up product analytics from scratch, auditing an existing instrumentation, fixing a "we have data but cannot trust it" problem, or designing instrumentation for a new feature. + +--- + +## What this skill is for + +This skill spans instrumentation execution. It does not cover measurement strategy (use `analytics-strategy`), experimentation result interpretation (use `experimentation-analytics`), paid media analytics (use `ads-performance-analytics`), or platform decisions (use `experimentation-platform-orchestrator`). Pair this skill with the relevant integrations microsite for your specific tool. + +The clean distinction from analytics-strategy. That skill (Growth category) is strategic: what to measure and why, KPI hierarchy, dashboard architecture, attribution models. This skill (Product category) is execution: how to actually instrument the product correctly. The two compose. Read analytics-strategy first to decide what matters; read this skill to instrument it. + +--- + +## The instrumentation hierarchy + +The mental model. Every analytics setup is a stack of layers. Each layer depends on the one below it being correct. + +- Events are the atomic facts: `user_signed_up`, `checkout_completed`, `feature_x_used`. +- Properties describe events: who, what, where, when, with what context. +- Identities map events to people: `anonymous_id`, `user_id`, `account_id`. +- Cohorts are filters across events: "users acquired via paid in March." +- Funnels are sequences of events: signup, then activated, then first paid action. +- Retention measures repeat behavior: signups still active at week N. + +You cannot construct higher levels without correct lower levels. Garbage events produce garbage funnels. The discipline is bottom-up. Most "we have data but cannot trust it" problems trace back to the bottom two layers. + +--- + +## Event taxonomy design + +Three rules for event design. + +1. Past tense, action-oriented. `checkout_completed`, not `checkout_complete` or `completing_checkout`. Past tense reads as "this happened" rather than as a state. +2. Object-action format. Noun then verb. `video_played`, `form_submitted`, `email_opened`. Reading the event name aloud should describe what happened. +3. Granular but not redundant. Track distinct user actions, not button clicks. Fire `checkout_completed` once at the moment of completion, not `submit_button_clicked` plus `checkout_completed`. UI events are noise; semantic events are signal. + +The verbs vs states trap. + +- Verbs ARE events. `checkout_completed`, `subscription_canceled`, `account_upgraded`. +- States are NOT events; they are properties. `user_status: active` is a property on the user, not an event. Setting state via events ("status_changed_to_active") is a code smell that produces double-counting. + +How many events to design. Thirty to fifty events is the sweet spot for a typical SaaS product. Below twenty means under-instrumented; above one hundred almost always means tracking UI noise or duplicating events in different formats. + +Detail and a canonical event spec in [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md). + +--- + +## Property design: event-level vs user-level + +Two property types, treated separately. + +Event-level properties describe THIS event. The `checkout_completed` event has properties like `cart_value`, `item_count`, `payment_method`, `discount_code`. They live on the event payload and are immutable once fired. + +User-level properties describe the USER over time. `subscription_tier`, `lifetime_value`, `acquisition_channel`. Set them once on the user profile; the analytics tool joins them onto every event the user fires. They update over time as the user changes. + +The trap. Putting user-level properties on every event. Do not track `subscription_tier` on every event payload; set it once on the user profile and rely on the join. Putting it on the event creates payload bloat, schema drift when the value changes, and reporting confusion when a user upgrades mid-session. + +Data type discipline. + +- Strings for enums: status, tier, channel, region. Enumerable values where the set is bounded. +- Numbers only for actual numbers: count, value, duration, score. Never use strings for numeric data ("free trial day 7" should be `trial_day: 7`). +- Booleans for actual booleans: `is_admin`, `has_trial`, `is_new_user`. Two values; nothing else. +- Timestamps in ISO 8601, always. Always. The number of bugs caused by inconsistent date formats is uncountable. +- Arrays rarely. An array property is usually a sign you should split into multiple events with one item per event. + +Worked example in [`references/property-design-patterns.md`](references/property-design-patterns.md) showing right and wrong design for a `product_viewed` event. + +--- + +## Naming conventions + +Pick ONE convention and enforce it. Three conventions worth picking. + +- snake_case for events and properties: `user_signed_up`, `cart_value`. Most platforms default to this; pushback is rarely worth it. +- Object-action format for events: `user_signed_up`, `video_played`. Reading the name should describe what happened. +- Verb-noun for user properties (or just nouns): `subscription_tier`, `is_admin`, `last_active_at`. + +What NOT to do. + +- Mixed case across events. `user_signedUp`, `User Signed Up`, `userSignedUp` all coexisting in the same project. Pick one and migrate. +- Spaces in event or property names. "Sign Up Completed" breaks every URL-encoding scenario and confuses every tool. +- Inconsistent verbs. `user_signed_up` plus `completedCheckout` plus `VIEW_PRODUCT` in the same project means nobody can predict an event name without looking it up. +- Brand names in event names. `mailchimp_email_opened` ages badly when you switch to Customer.io. + +The naming convention reference file provides a complete style guide. Cite it in your team's data contract. + +Detail in [`references/naming-convention-reference.md`](references/naming-convention-reference.md). + +--- + +## Schema versioning + +Schema changes are inevitable. The pattern. + +Additive changes are safe. New event, new property on an existing event, new value in an enum. Just ship. Existing dashboards continue to work. + +Breaking changes require migration. Renamed event, removed property, changed property type, narrowed enum. These break dashboards downstream; the migration plan is part of the change. + +Versioning patterns. + +- Append `_v2` to events when semantics change. `checkout_completed_v2` fires alongside `checkout_completed` during a transition. +- Keep old events firing during the transition (90 days is typical). Both versions fire; analytics queries gradually migrate to v2. +- Migrate dashboards to v2 before retiring v1. Then deprecate v1 explicitly with a documentation note. + +The data contract idea. + +- Document the canonical schema in code: TypeScript interface, JSON Schema, or Protobuf definition. +- Code review every schema change. Schema is product, not afterthought. +- CI lint rejects schema violations before they hit production. The deploy that adds an event with the wrong type fails the build. + +Detail in [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md). + +--- + +## Funnel design + +Funnels measure progression through a sequence. Four rules. + +1. Order matters. A then B then C is a different funnel from B then A then C. The platform will compute different conversion rates depending on order. +2. Time windows matter. Most funnels use a 1 to 30 day window from the first event. Document the window explicitly; "users who completed signup AND activated" is meaningless without "within 14 days." +3. Drop-off interpretation is hard. Eighty percent of users dropping at step 2 might be the funnel design (audience is wrong), might be the audience (timing is wrong), or might be the product (genuine drop-off). Investigate before declaring. +4. The anchor event pattern. Every funnel starts with a high-intent action: signup, trial start, key feature use. Not a vanity event like `page_view` or `session_start`. Vanity-event-anchored funnels show 99% drop-off and tell you nothing. + +Common funnel mistakes. + +- Funnels that include events firing automatically. `session_started` happens for every visit; using it as a step inflates the denominator and makes the rest of the funnel meaningless. +- Funnels too long (10+ steps). Break into two or three shorter funnels. A 10-step funnel produces near-zero end-to-end conversion that is hard to interpret. +- Funnels with the same event in multiple positions. The platform handles this poorly; the analyst handles it worse. +- Mixing different time windows in one funnel. "Users who signed up within 7 days AND converted within 30 days" is two different cohort definitions glued together. + +Common funnel shapes and time-window guidance in [`references/funnel-design-templates.md`](references/funnel-design-templates.md). + +--- + +## Cohort definitions + +A cohort is a group of users sharing an attribute or behavior. Useful patterns. + +- Acquisition cohorts. Users acquired in month X. The standard for retention analysis. +- Behavioral cohorts. Users who completed action Y. Useful for activation analysis ("users who sent first message in week 1"). +- Property cohorts. Users with `subscription_tier: pro`. Useful for segment-level analysis. +- Combined cohorts. Signup in March AND completed onboarding AND in EU. The most common in real analytics work. + +Cohort discipline. + +- Define cohorts in code (or in your tool's saved-cohort feature) so they are reusable. +- Version them when criteria change. Compare apples-to-apples. +- Do not compare a 30-day-old cohort to a 365-day-old cohort on retention; the older cohort has had more time to retain by definition. + +Detail in [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md). + +--- + +## Retention measurement + +Retention is repeat behavior over time. Three flavors. + +- N-day retention. Did user X come back on day 7, day 14, day 30 specifically. High noise on any single day; useful for short-cycle products. +- Bracket retention. Did user X come back at any point during the week 7 to 13 window. More stable than N-day; reads cleaner on retention curves. +- Unbounded (rolling) retention. Did user X come back any time after signup. Useful for longer-cycle products where weekly cadence is misleading. + +For most SaaS products, bracket retention is the right default. Day-7 is high-noise; week-2 (bracket) is more stable. Day-1 retention is almost always over-indexed to onboarding effects rather than product-market-fit signal. + +Retention curve interpretation. + +- Steep early drop, then plateau. The product has core users; the rest churn fast. Typical for most SaaS products. +- Gradual decay across weeks with no plateau. No one is sticking. Usually a value-prop or onboarding problem; the product is not delivering recurring value. +- Flat line at low percentage. A power-user product with a small but engaged base. Not a problem; just a different shape. + +Detail in [`references/retention-measurement-patterns.md`](references/retention-measurement-patterns.md). + +--- + +## North Star and supporting metrics + +North Star metric (NSM) selection rules. + +- Reflects user value, not company value alone. +- Captures the core action that, if it grows, the business grows. +- Measurable consistently across time. +- Hard to game. + +Bad NSMs. Signups (vanity; many signups never activate). Revenue (lagging; not action-oriented; varies by mix). DAU (only useful for engagement-driven products; misleads on monthly-cadence products). + +Better NSMs. Weekly active editors (Figma). Nights booked (Airbnb). Messages sent per day (Slack). Products created per workspace per week (Linear). Each names a user-value action that maps to business growth. + +Supporting metrics framework. + +- One NSM. +- Three to five input metrics that drive the NSM. For "weekly active editors" these might be: signups per week, signup-to-active conversion rate, week-over-week active retention. +- Five to ten health metrics that warn of problems. Monthly churn rate, account-level concentration, support ticket volume. + +Detail and product-type-specific examples in [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md). + +--- + +## The trustable dashboard principle + +A dashboard is trustable when four things are true. + +1. Each metric has a clear definition documented inline. Not "active users" but "users who fired any event in the last 7 days, deduplicated by user_id, excluding employees." +2. Each metric has a known data source. Not "from the warehouse" but "from `fct_orders`, last 30 days, joined to `dim_customers`." +3. Each metric has known caveats. Modeled iOS conversions excluded. Internal employees excluded. Test users in QA accounts excluded. +4. Each metric is reproducible. The same query, run tomorrow, produces the same number for the same time period. + +The stale dashboard failure mode. A dashboard built two years ago is still in use. The underlying schema changed; the dashboard's query points at columns that no longer exist or now mean something different. The team makes decisions on broken numbers and does not realize until something breaks loudly. + +Prevention. Every dashboard has an owner, a refresh cadence, and a quarterly audit. Dashboards without an owner get deprecated. Dashboards that have not been refreshed in 90 days get deprecated. The half-life of a dashboard is shorter than the half-life of the product. + +--- + +## Instrumentation debt + +The compounding cost of cutting corners. + +- New feature ships without instrumentation: 1 hour saved. +- Six months later: nobody can answer "is feature X working?" +- Cost to retroactively instrument: 20 hours (re-deploy, backfill, validate). +- Cost in lost decisions during the gap: untrackable but real. Decisions get made on intuition rather than data; sometimes the intuition is wrong. + +Instrumentation debt is real and compounds like technical debt. The discipline. + +- Every PR for new functionality includes instrumentation. The PR template asks "what events does this fire?" and rejects the PR if the answer is none. +- Quarterly schema audits. Identify orphan events (firing but not used in any dashboard or query) and deprecate them. Identify gaps (features without events) and fill them. +- "If we cannot measure it, we do not ship it" with explicit exceptions for genuinely experimental features where the cost of instrumentation exceeds the value of the data. + +Detail in [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md). + +--- + +## Common failure modes + +Twelve patterns recur across product analytics setups. The short version. + +- "We have data but cannot trust it." Naming and schema drift. Fix is a schema audit plus naming convention enforcement. +- "Our funnel says 80% drop-off but real conversion is fine." Wrong anchor event or wrong window. Fix the funnel definition. +- "Retention curve is flat at 5%." Often not a problem. Power-user products genuinely have small engaged bases. Compare against business reality before treating as a fix-it. +- "Mixpanel says 1000 conversions, warehouse says 800." Attribution plus identity stitching mismatch. Reconcile against warehouse for canonical numbers. +- "Dashboards take 30 seconds to load." Over-broad queries, unindexed properties, or schema bloat. Profile and refactor. +- "Everyone has their own definition of MAU." No canonical metric document. Ship one; force everyone to use the same definition. +- "We track every button click." UI noise. Audit and remove events that are not used by any dashboard or query. +- "Our event names changed three times." No versioning. Migrate to a versioning pattern; freeze further renames. +- "Analytics tool says iOS users converted 3% but warehouse says 5%." iOS Intelligent Tracking Prevention plus modeled conversions. Treat platform iOS data with extra skepticism. +- "We cannot answer simple questions." Under-instrumented or wrong abstraction layer. Audit the events list against the questions the team is asking; fill the gaps. +- "Two analysts compute different MAU." Different identity stitching. Pick one canonical identity layer and make everyone query from it. +- "Numbers are different than last quarter for no reason." Underlying schema changed without versioning. The dashboard quietly broke; nobody noticed until the gap got large. + +Detail in [`references/common-failures.md`](references/common-failures.md). + +--- + +## The framework: 12 considerations for trustable product analytics + +When designing or auditing product analytics, walk these 12 considerations. Skipping any of them is how the team ends up with data nobody trusts. + +1. Event taxonomy. Past tense, object-action, granular but not redundant. Verbs are events; states are properties. +2. Property design. Event-level vs user-level. Type discipline. ISO 8601 timestamps everywhere. +3. Naming conventions. Pick one and enforce it. snake_case wins by default. +4. Schema versioning. Additive vs breaking. `_v2` suffix during transitions. Data contract in code. +5. Identity stitching. Anonymous to authenticated, cross-device, cross-tool. One canonical identity layer. +6. Funnel design. Anchor on high-intent events. Document time windows. No auto-firing events as steps. +7. Cohort definitions. Reusable, versioned, apples-to-apples. Defined in code or saved in the tool. +8. Retention measurement. Bracket over N-day for stability. Compare cohorts at matched ages. +9. North Star. Captures user value. Hard to game. One NSM, three to five inputs, five to ten health metrics. +10. Dashboard hygiene. Definitions, sources, owners, refresh cadence. Stale dashboards get deprecated. +11. Instrumentation debt. Every PR includes instrumentation. Quarterly audits. +12. Single source of truth. Warehouse for board metrics. Tool for in-flight optimization. Reconcile when they disagree. + +The output of the framework is a tracking plan. A list of events with their properties, the canonical user identity, the named cohorts, the named funnels, the retention measurement choice, the named NSM, the dashboard owners. The plan lives in code and gets reviewed like any other product spec. + +--- + +## Reference files + +- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Canonical event spec for typical SaaS: account, user, activation, engagement, conversion, retention events with required properties. +- [`references/property-design-patterns.md`](references/property-design-patterns.md) - Event-level vs user-level patterns. Type discipline. Worked example: `product_viewed` right vs wrong. +- [`references/naming-convention-reference.md`](references/naming-convention-reference.md) - Complete style guide. snake_case, past tense, object-action. Boolean prefixes. Money in cents. Timestamps with `_at` suffix. Do/don't side-by-side. +- [`references/schema-versioning-patterns.md`](references/schema-versioning-patterns.md) - Additive vs breaking changes. `_v2` suffix pattern. Data contract in TypeScript. CI lint patterns. +- [`references/funnel-design-templates.md`](references/funnel-design-templates.md) - Activation, conversion, engagement, feature adoption funnels. Time windows, anchor events, drop-off interpretation. +- [`references/cohort-definition-patterns.md`](references/cohort-definition-patterns.md) - Acquisition, behavioral, property, combined cohorts. SQL examples plus tool-specific examples. +- [`references/north-star-metric-selection.md`](references/north-star-metric-selection.md) - NSM rules with examples by product type. Anti-patterns. Migration patterns when changing NSM. +- [`references/instrumentation-audit-checklist.md`](references/instrumentation-audit-checklist.md) - Quarterly audit playbook: schema review, volume sanity checks, dashboard freshness, owner audit, deprecation candidates. +- [`references/common-failures.md`](references/common-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention. + +--- + +## Closing: when in doubt, instrument less + +Most product analytics setups are over-instrumented, not under-instrumented. Tracking every button click produces noise that drowns the signal. The discipline of saying "we do not need to track that" is harder than "let us track that just in case." Default to less. + +The data you do not have can be added later. The data you over-collected costs you forever, in dashboard performance, in schema complexity, in signal-to-noise. The team that ships with thirty well-designed events and a small set of named cohorts outperforms the team that ships with two hundred events and no cohort discipline. + +When the team disagrees on whether to add an event, the question is not "could this be useful?" but "what specific decision will this event inform, and is the decision worth the instrumentation cost?" If the answer is "we might want to know" the answer to the question is no. diff --git a/skills/product-analytics-setup/references/cohort-definition-patterns.md b/skills/product-analytics-setup/references/cohort-definition-patterns.md new file mode 100644 index 0000000..1dc8ca5 --- /dev/null +++ b/skills/product-analytics-setup/references/cohort-definition-patterns.md @@ -0,0 +1,202 @@ +# Cohort definition patterns + +Four cohort patterns: acquisition, behavioral, property, combined. With SQL examples for warehouse-native and tool-specific examples for Mixpanel, Amplitude, and PostHog. + +--- + +## Pattern 1: acquisition cohort + +Users acquired in a specific time window. The standard for retention analysis. + +### Definition + +```sql +-- Warehouse-native (BigQuery / Snowflake / Postgres) +SELECT user_id +FROM dim_users +WHERE first_seen_at >= '2026-04-01' + AND first_seen_at < '2026-05-01'; +``` + +### Tool-specific + +Mixpanel. Cohort builder, condition: "First time the user did `user_signed_up` was between April 1 and April 30, 2026." + +Amplitude. User segment, condition: "First event date between April 1 and April 30, 2026." + +PostHog. Cohort, condition: "Person property `first_seen` is between April 1 and April 30, 2026." + +### Use cases + +- Retention analysis. Compare retention curves across acquisition cohorts to detect product or onboarding regressions. +- Onboarding A/B test results. The treatment cohort and control cohort are both acquisition cohorts. +- Cohort revenue tracking. How much did April's signups generate over the next 12 months? + +### Common mistakes + +- Comparing cohorts at different ages. A 30-day-old cohort has lower retention than a 90-day-old cohort by definition. +- Using "user created" vs "first event" inconsistently. Pick one and document it. + +--- + +## Pattern 2: behavioral cohort + +Users who completed a specific action. The standard for activation and engagement analysis. + +### Definition + +```sql +-- Users who fired first_value_action_completed within 14 days of signup +SELECT u.user_id +FROM dim_users u +JOIN fct_events e ON e.user_id = u.user_id +WHERE e.event_name = 'first_value_action_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '14 days'; +``` + +### Tool-specific + +Mixpanel. Cohort builder, condition: "User did `first_value_action_completed` at least once where event time was within 14 days of `user_signed_up`." + +Amplitude. Behavioral cohort, "Performed event `first_value_action_completed` within 14 days after first event." + +PostHog. Cohort, condition: "Person performed event `first_value_action_completed` and the event happened within 14 days of person creation." + +### Use cases + +- Activation funnel: activated users vs non-activated users. +- Feature adopters: users who used feature X. How does their retention compare to non-adopters? +- Power users: users who fired a specific high-value event 5 or more times. + +### Common mistakes + +- Using behavioral cohorts for retention without a time anchor. "Users who completed onboarding" includes users from January and users from October; their retention curves are at different ages. +- Confusing "users who ever did X" with "users who did X recently." Specify the time window. + +--- + +## Pattern 3: property cohort + +Users with a specific property value. The standard for segment-level analysis. + +### Definition + +```sql +SELECT user_id +FROM dim_users +WHERE subscription_tier = 'pro' + AND region = 'us' + AND is_admin = false; +``` + +### Tool-specific + +Mixpanel. Cohort, condition: "User properties: `subscription_tier = pro` AND `region = us`." + +Amplitude. User segment, condition: "User properties match: `subscription_tier = pro` AND `region = us`." + +PostHog. Cohort, condition: "Person properties: `subscription_tier = pro` AND `region = us`." + +### Use cases + +- Segment performance: how does the Pro tier behave differently from the Free tier? +- Geographic analysis: do EU users convert at a different rate than US users? +- Role-based analysis: do admins use the product differently than members? + +### Common mistakes + +- Using event-level properties as if they were user-level. "Users who fired any event with `cart_value > 100`" returns events, not users; use a behavioral cohort for "users who fired a high-value event." +- Snapshot vs current property values. "Users who were Pro in March" vs "users who are Pro now" are different cohorts; some platforms default to current values without warning. + +--- + +## Pattern 4: combined cohort + +Combinations of the above. The most common in real analytics work. + +### Definition + +```sql +-- Users who signed up in March, completed onboarding within 7 days, +-- are in EU, and are on the Pro tier +SELECT u.user_id +FROM dim_users u +WHERE u.first_seen_at >= '2026-03-01' + AND u.first_seen_at < '2026-04-01' + AND u.region = 'eu' + AND u.subscription_tier = 'pro' + AND EXISTS ( + SELECT 1 FROM fct_events e + WHERE e.user_id = u.user_id + AND e.event_name = 'onboarding_completed' + AND e.event_timestamp <= u.first_seen_at + INTERVAL '7 days' + ); +``` + +### Tool-specific + +All three platforms support combined cohorts via boolean composition (AND, OR, NOT). The composition gets unwieldy past 4 or 5 conditions; consider whether the cohort is genuinely useful or whether the team is over-segmenting. + +### Use cases + +- Activation analysis by acquisition channel: "Paid Meta users who signed up in March and activated within 7 days." +- Quality cohorts: "Pro tier users acquired via organic search who reached aha_moment within 14 days." +- Test cohorts: "Treatment group users who completed the onboarding A/B test within 7 days." + +### Common mistakes + +- Cohorts so narrow that the population is too small for analysis. A cohort of 50 users has high variance on every metric. +- Combining conditions that contradict each other. "Pro tier free users" returns nothing. +- Forgetting to time-box. A combined cohort without acquisition or behavioral time bounds drifts as users join and leave. + +--- + +## Cohort discipline + +Three rules that apply across all four patterns. + +### Rule 1: define cohorts in code (or saved in the tool) + +Re-querying the same cohort definition by hand each time produces inconsistencies. Define the cohort once; reuse the definition across analyses. + +In SQL: a `WITH` clause or a saved view. + +```sql +WITH march_cohort AS ( + SELECT user_id + FROM dim_users + WHERE first_seen_at >= '2026-03-01' + AND first_seen_at < '2026-04-01' +) +SELECT COUNT() FROM march_cohort; +``` + +In analytics tools: saved cohorts. Every analysis references the saved cohort by name. + +### Rule 2: version when criteria change + +A cohort definition that evolves over time produces non-comparable results. If you change the activation definition, the new cohort is a different cohort. + +Pattern. Append `_v2` to the cohort name when criteria change. Keep the old definition queryable for historical comparison. + +### Rule 3: compare apples-to-apples + +Two cohorts compared at different ages produce misleading conclusions. Always compare at matched ages. + +If comparing March cohort retention against November cohort retention, both should be measured at the same number of days post-acquisition. November cohort at 30 days vs March cohort at 60 days is not a fair comparison. + +--- + +## When to introduce a cohort + +The team has a question that filters on a user attribute or behavior. The question repeats across analyses. The team is computing the same filter 5+ times by hand. + +That is the trigger. Define the cohort once; reuse it. + +--- + +## When to deprecate a cohort + +The cohort has not been queried in 90 days. The cohort criteria no longer match a real product question (e.g., the feature it tracked was deprecated). The team has built a more precise replacement cohort. + +Stale cohorts in the analytics tool produce dropdown clutter and tempt analysts to use them when newer cohorts are appropriate. Deprecate explicitly. diff --git a/skills/product-analytics-setup/references/common-failures.md b/skills/product-analytics-setup/references/common-failures.md new file mode 100644 index 0000000..9e5fa5e --- /dev/null +++ b/skills/product-analytics-setup/references/common-failures.md @@ -0,0 +1,155 @@ +# Common failures + +Twelve patterns that recur across product analytics setups. For each: name, symptom, root cause, fix, prevention. + +--- + +## 1. We have data but cannot trust it + +Symptom.* The team has years of events. Two analysts run the same query and get different numbers. Stakeholders ask for "the real number" and the answer is "it depends." + +Root cause. Naming and schema drift over time. Same event name has slightly different semantics in different code paths. Properties have inconsistent types or values. + +Fix. Schema audit. Identify the canonical events; deprecate the duplicates and aliases. Standardize property types. Document the canonical definitions. + +Prevention. Schema in code (TypeScript interface or JSON Schema). CI lint that rejects schema violations. Naming convention enforcement. + +--- + +## 2. Funnel says 80% drop-off but real conversion is fine + +Symptom. The activation funnel shows 20% conversion. The team knows from revenue numbers that real activation is 60%. + +Root cause. Wrong anchor event (using a too-broad event like `page_view` as the start) or wrong time window (asking for activation within 24 hours when the real cycle is 14 days). + +Fix. Audit the funnel definition. Anchor on a high-intent event (signup, trial start). Set the time window to match the actual activation cycle. + +Prevention. Document the funnel anchor and window in the funnel definition itself, not implicit in dashboard text. Review funnels at each quarterly audit. + +--- + +## 3. Retention curve is flat at 5% + +Symptom. Retention curve drops fast then plateaus at 5%. The team panics; only 5% of users are active. + +Root cause. Not always a problem. Some products are power-user products with small but engaged bases (developer tools, niche B2B software). The 5% may be the natural shape. + +Fix. Compare against business reality. If 5% retention with strong unit economics, the curve is healthy. If 5% retention and the business model assumes 20% retention, then it is a problem and the cohort needs investigation. + +Prevention. Set retention targets based on business model assumptions, not industry benchmarks. The right retention for a niche tool is different from the right retention for a consumer app. + +--- + +## 4. Mixpanel says 1000 conversions, warehouse says 800 + +Symptom. Two systems report different conversion counts for the same event. + +Root cause. Identity stitching mismatch. Mixpanel may stitch anonymous-to-authenticated differently than the warehouse. Server-side and client-side fires of the same event may not deduplicate correctly. Time-window differences (Mixpanel using event time, warehouse using ingest time). + +Fix. Pick one source as canonical (warehouse for board metrics, tool for in-flight). Reconcile the gap by understanding the cause. Document the expected gap so stakeholders are not surprised. + +Prevention. Identity stitching pattern documented and consistent. Server-side and client-side firing for the same event handled with explicit deduplication. Use a single time field consistently. + +--- + +## 5. Dashboards take 30 seconds to load + +Symptom. The team's main dashboard takes 30+ seconds to refresh. Reviewing a metric becomes a coffee break. + +Root cause. Over-broad queries (scanning years of data for a 30-day metric). Unindexed properties used as filters. Schema bloat from too many events or too many properties on each event. + +Fix. Profile the slow queries. Add date filters. Index the filter properties. Pre-aggregate metrics into a daily summary table; query the summary, not the raw events. + +Prevention. Set query budgets per dashboard (target: under 5 seconds). Audit performance during the quarterly audit. Cap the data volume per query. + +--- + +## 6. Everyone has their own definition of MAU + +Symptom. Three people compute MAU; three different numbers. + +Root cause. No canonical definition. One person counts unique user_ids firing any event. Another counts users who fired a specific qualifying event. Another counts authenticated users only. + +Fix. Write a canonical metric document. "MAU is unique user_ids firing any event in the last 30 days, deduplicated, excluding employee accounts (employees identified by email domain) and excluding test accounts (account_type = 'test')." Force everyone to use this definition. + +Prevention. Canonical metric document maintained as living documentation. Every dashboard's metric definitions reference the canonical document. Disagreements get resolved by updating the document, not by recomputing on the fly. + +--- + +## 7. We track every button click + +Symptom. The event list has 800 events. Many are individual button clicks. Dashboards are slow; analyses produce noise. + +Root cause. Tracking UI events (clicks, hovers, page views) rather than semantic events (created, completed, shared). Each button gets its own event "for completeness." + +Fix. Audit the event list. Deprecate UI events. Replace with semantic events that capture user intent. + +Prevention. Naming convention enforcement (verbs are events; UI states are properties). Code review on new events asks "is this a semantic event or a UI event?" UI events get rejected unless there is a specific use case. + +--- + +## 8. Our event names changed three times + +Symptom. `signup_complete`, then `signupCompleted`, then `user_signed_up`. Dashboards reference all three; nobody knows which is current. + +Root cause. No versioning. Each rename happened without coordination, leaving old events in the warehouse and old queries in the dashboards. + +Fix. Migrate to a single canonical version. Use the `_v2` pattern if semantics changed. Deprecate old versions explicitly. Update all dashboards. + +Prevention. Versioning pattern in the schema documentation. Schema review on every PR that adds or modifies an event. CI lint on event names. + +--- + +## 9. Analytics tool says iOS users converted 3% but warehouse says 5% + +Symptom. iOS conversion rate looks bad in the analytics tool but fine in the warehouse. + +Root cause. iOS Intelligent Tracking Prevention (ITP) blocks third-party cookies, breaking attribution for iOS users. The analytics tool models the missing data; the warehouse uses server-side conversion tracking that is unaffected. + +Fix. Treat iOS analytics-tool data with extra skepticism. Use the warehouse for canonical iOS metrics. Set up server-side event tracking (Conversions API for Meta, server-side GA4) where possible. + +Prevention. Document the iOS measurement gap. Pair every iOS-specific metric with a note on the data source. + +--- + +## 10. We cannot answer simple questions + +Symptom. Stakeholder asks: "How many users came back this week?" Three days of analyst time later, still no clean answer. + +Root cause. Under-instrumented or wrong abstraction layer. The events list does not include the right event. The user identity layer does not stitch correctly. The cohort definition is too narrow or too broad. + +Fix. Audit the event list against the questions the team actually asks. Fill gaps with new events; fix identity stitching; create canonical cohorts for the most common questions. + +Prevention. Quarterly review of the question backlog. Map questions to events; identify gaps. Fill gaps proactively, not after the question goes unanswered. + +--- + +## 11. Two analysts compute different MAU on the same data + +Symptom. Same query, same data, different numbers. The discrepancy is not because of a definition disagreement; it is because the queries silently return different rows. + +Root cause. Different identity stitching layers. One query uses user_id; another uses anonymous_id with stitching applied at query time. Edge cases (users who logged out and back in, users on multiple devices) get counted differently. + +Fix. Pick one canonical identity layer. Build a `dim_users` table in the warehouse that resolves identity once. Force all queries to join through this table. + +Prevention. Identity-stitching pattern documented. New queries use the canonical table. Code review rejects queries that bypass the layer. + +--- + +## 12. Numbers different than last quarter for no reason + +Symptom. A dashboard's metrics shifted between Q1 and Q2 by 30%. No product change, no instrumentation change... or so it seems. + +Root cause. Underlying schema changed without versioning. An event was renamed; the dashboard's query points at the old name and now silently returns nothing or returns a different cohort. Often discovered weeks after the fact. + +Fix. Audit the dashboard's query against the current schema. Update to current event names. Check for similar drift in other dashboards. + +Prevention. Versioning pattern enforced. CI lint catches event renames before they ship. Quarterly dashboard audit catches drift early. + +--- + +## The pattern across all twelve + +Most product analytics failures share one root cause: cutting corners during instrumentation produces compounded debt that surfaces months later as untrustworthy data. The team that ships without a tracking plan saves an hour at instrumentation time and pays 20+ hours at audit time. + +The fix at the meta level. Treat instrumentation as a first-class engineering concern. Schema in code. Naming convention enforced. Quarterly audits. Single source of truth for canonical metrics. Instrumentation debt is real; the discipline of paying it down regularly is the only thing that keeps the data trustworthy. diff --git a/skills/product-analytics-setup/references/event-taxonomy-template.md b/skills/product-analytics-setup/references/event-taxonomy-template.md new file mode 100644 index 0000000..86bb1df --- /dev/null +++ b/skills/product-analytics-setup/references/event-taxonomy-template.md @@ -0,0 +1,114 @@ +# Event taxonomy template + +A canonical event spec for typical SaaS. Six event categories with the events that belong in each, when they fire, who fires them (client or server), required properties, and common pitfalls. + +The principle. Thirty to fifty events covers most SaaS products. Below twenty is under-instrumented; above one hundred is usually UI noise. The categories below are the durable shape; the specific event names map to your product. + +--- + +## Account events + +Account-level lifecycle. Server-side firing typical because billing is server-side. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `account_created` \| A new account (workspace, organization) is provisioned. \| `account_id`, `plan_tier`, `seat_count` \| Distinct from `user_signed_up` (a user can join an existing account). \| +\| `account_upgraded` \| The account moves to a higher plan tier. \| `account_id`, `from_tier`, `to_tier`, `change_reason` \| Fires server-side from the billing webhook. \| +\| `account_downgraded` \| The account moves to a lower plan tier. \| `account_id`, `from_tier`, `to_tier`, `change_reason` \| Same source as upgrade. \| +\| `account_canceled` \| The account cancels and stops renewing. \| `account_id`, `cancellation_reason`, `final_term_end_at` \| Cancellation reason is critical; capture it from the cancellation flow. \| +\| `seat_added` \| A new seat is provisioned on the account. \| `account_id`, `seat_count_after`, `added_by_user_id` \| Useful for net-revenue-retention analysis. \| +\| `seat_removed` \| A seat is released from the account. \| `account_id`, `seat_count_after`, `removed_by_user_id`, `removal_reason` \| \| + +Common pitfall. Firing account events client-side from the admin UI. The admin's browser may not be open during the cancellation; server-side from the billing webhook is the right source. + +--- + +## User events + +User-level lifecycle. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `user_signed_up` \| A user creates an account or joins an existing account. \| `user_id`, `account_id`, `signup_source`, `referrer_source` \| Distinct from `account_created`; one account, many users. \| +\| `user_invited` \| An existing user invites a new user. \| `inviter_user_id`, `invited_email`, `account_id`, `invitation_role` \| The invitation event; `user_signed_up` fires later when the invite is accepted. \| +\| `user_role_changed` \| A user's role within the account changes. \| `user_id`, `account_id`, `from_role`, `to_role`, `changed_by_user_id` \| \| +\| `user_logged_in` \| A user authenticates after a logged-out state. \| `user_id`, `auth_method`, `device_type` \| Different from session start. Logged-in across multiple sessions. \| +\| `user_logged_out` \| A user explicitly signs out. \| `user_id`, `logout_reason` \| Often missed; explicit signout vs session timeout. \| +\| `user_deactivated` \| A user's account is deactivated. \| `user_id`, `account_id`, `deactivation_reason` \| Soft delete pattern. \| + +--- + +## Activation events + +The first-value moment. Critical for activation analysis. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `onboarding_step_completed` \| The user completes a step in the onboarding flow. \| `user_id`, `step_name`, `step_number`, `time_in_step_s` \| Step name is canonical; do not change it without versioning. \| +\| `onboarding_completed` \| The user finishes all onboarding steps. \| `user_id`, `total_time_s`, `steps_completed_count` \| Distinct from activation; onboarding completion does not equal activation. \| +\| `first_value_action_completed` \| The user does the thing that delivers product value for the first time. \| `user_id`, `action_name`, `time_since_signup_s` \| Define this carefully per product. For Slack, first message sent. For Figma, first frame created. \| +\| `aha_moment_reached` \| The user crosses the activation threshold. \| `user_id`, `threshold_metric`, `threshold_value` \| Tied to the activation definition (e.g., "5 messages in week 1"). \| + +--- + +## Engagement events + +Recurring product use. The bulk of event volume. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `feature_x_used` \| The user invokes feature X. Replace x with the actual feature name. \| `user_id`, `feature_name`, `entry_point` \| Granularity guidance: one event per feature, not one event per button. \| +\| `content_y_created` \| The user creates a new asset (document, project, message, etc.). \| `user_id`, `content_type`, `content_id`, `creation_source` \| \| +\| `content_y_edited` \| The user modifies an existing asset. \| `user_id`, `content_type`, `content_id`, `edit_type` \| High volume; consider sampling if storage is a concern. \| +\| `content_y_shared` \| The user shares an asset externally. \| `user_id`, `content_type`, `content_id`, `share_method`, `recipient_count` \| Sharing is often the strongest engagement signal. \| +\| `search_executed` \| The user runs an in-product search. \| `user_id`, `query_length`, `result_count`, `clicked_result_position` \| Capture click-through rates. \| + +--- + +## Conversion events + +Money moves. Server-side firing required. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `trial_started` \| The user starts a free trial. \| `user_id`, `account_id`, `trial_plan`, `trial_length_days` \| Server-side from the billing system. \| +\| `trial_converted` \| The trial converts to paid. \| `user_id`, `account_id`, `from_plan`, `to_plan`, `mrr_added` \| Server-side. The MRR property feeds revenue analysis. \| +\| `trial_expired_no_conversion` \| The trial ends without converting. \| `user_id`, `account_id`, `trial_plan`, `usage_during_trial` \| Useful for win-back campaigns. \| +\| `subscription_purchased` \| A subscription begins (any path). \| `user_id`, `account_id`, `plan_tier`, `mrr_added`, `purchase_source` \| Includes trial conversions and direct purchases. \| +\| `subscription_renewed` \| A subscription renews for the next term. \| `account_id`, `plan_tier`, `mrr_at_renewal` \| \| +\| `payment_failed` \| A payment attempt fails. \| `account_id`, `failure_reason`, `attempt_number` \| Critical for involuntary churn analysis. \| + +--- + +## Retention events + +Repeat behavior markers. Useful for retention curve construction. + +\| Event \| Fires when \| Required properties \| Notes \| +\|---\|---\|---\|---\| +\| `weekly_active_marker` \| The user fires any qualifying event in a given week. \| `user_id`, `week_of_year`, `qualifying_event_count` \| Some teams compute this in the warehouse rather than fire it as an event; either pattern works. \| +\| `returned_after_n_days` \| The user returns after N days of inactivity. \| `user_id`, `inactive_days_count`, `last_active_at` \| Useful for resurrection-flow analytics. \| + +--- + +## Property requirements across all events + +Every event payload should include: + +- `user_id` (or `anonymous_id` for pre-auth events) +- `account_id` (where applicable; for B2B SaaS especially) +- `timestamp` (ISO 8601, server-stamped) +- `device_type` and `platform` (mobile, web, desktop) +- `app_version` (for change-tracking) +- `session_id` (for path analysis) + +Some platforms inject these automatically. Verify; do not assume. + +--- + +## Common pitfalls in event taxonomy + +- Tracking page views as the primary engagement signal. Page views are noise. Track semantic events (created, edited, shared) instead. +- Treating onboarding completion as activation. Many users complete onboarding without ever returning. Define activation as a recurring-value action, not as flow completion. +- Inconsistent fire timing across the funnel. Some events fire client-side, some server-side. Reconcile by picking one source per event and documenting it. +- Adding new events without checking existing ones. Six months in, the event list has three versions of "subscription started." Audit before adding. diff --git a/skills/product-analytics-setup/references/funnel-design-templates.md b/skills/product-analytics-setup/references/funnel-design-templates.md new file mode 100644 index 0000000..f7b110a --- /dev/null +++ b/skills/product-analytics-setup/references/funnel-design-templates.md @@ -0,0 +1,174 @@ +# Funnel design templates + +Common funnel shapes with anchor events, time windows, and drop-off interpretation guidance. + +The principle. Every funnel measures progression through a sequence. The shape of the funnel must match the shape of the user behavior; mismatch produces conversion rates that are uninterpretable. + +--- + +## Activation funnel + +Signup to first value. The most important funnel for product-led growth. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `user_signed_up` \| The anchor. High intent. \| +\| 2 \| `onboarding_started` \| The user begins the guided onboarding. \| +\| 3 \| `onboarding_completed` \| The user finishes onboarding. Note: this is not activation. \| +\| 4 \| `first_value_action_completed` \| The user does the action that delivers product value. THIS is activation. \| +\| 5 \| `aha_moment_reached` \| Optional. The threshold beyond which retention curves stabilize. \| + +### Time window + +7 to 14 days from signup. Longer windows include users who activated after a long delay; shorter windows undercount slow adopters. + +### Anchor selection + +`user_signed_up` is the standard anchor. Avoid `landing_page_viewed` (too noisy) and `email_collected` (too low-intent). + +### Drop-off interpretation + +- 70%+ drop between signup and onboarding_started: the post-signup experience is the problem. Often a friction issue (email verification, account setup steps). +- 30%+ drop between onboarding_completed and first_value_action_completed: onboarding is teaching the wrong thing. Users complete the tour but do not understand the product. +- High drop at first_value_action_completed: the value action is too hard or too far from the user's natural path. Move it earlier in the experience. + +--- + +## Conversion funnel + +Trial to paid. The most important funnel for SaaS subscription businesses. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `trial_started` \| The anchor. High intent and ready to evaluate. \| +\| 2 \| `aha_moment_reached` \| The user experiences product value. Critical predictor of conversion. \| +\| 3 \| `paywall_viewed` \| The user sees the upgrade prompt. \| +\| 4 \| `checkout_started` \| The user begins the payment flow. \| +\| 5 \| `subscription_purchased` \| The conversion. \| + +### Time window + +The trial length plus a 7-day grace period. A 14-day trial uses a 21-day funnel window. Shorter windows undercount last-day conversions. + +### Anchor selection + +`trial_started` is the standard anchor. Funnels that start at signup (rather than trial start) include users who never engaged with the trial; the conversion rate looks lower than it actually is for engaged users. + +### Drop-off interpretation + +- High drop between aha_moment_reached and paywall_viewed: users got value but the paywall did not appear (timing issue) or did not feel relevant. Audit the paywall trigger logic. +- High drop between paywall_viewed and checkout_started: pricing or feature gating is the friction. Often a positioning issue rather than a UX issue. +- High drop between checkout_started and subscription_purchased: payment flow friction. UX audit the checkout pages; check failed-payment rates. + +--- + +## Engagement funnel + +Visit to action. Useful for understanding session-level conversion. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `feature_x_landing_page_viewed` \| The anchor. Specific intent (feature page, not homepage). \| +\| 2 \| `feature_x_used` \| The user performs the core action. \| +\| 3 \| `feature_x_completed_workflow` \| The user finishes the workflow. \| +\| 4 \| `content_y_shared` or similar high-intent action \| Optional. Strongest engagement signal. \| + +### Time window + +Single session, typically 30 to 60 minutes from the first event. + +### Anchor selection + +A feature-specific landing or entry point. Avoid `homepage_viewed` (too broad) and `session_started` (auto-firing, not intent). + +### Drop-off interpretation + +- High drop from landing to use: the page promises something the feature does not deliver, or the activation friction is too high. +- High drop from use to workflow completion: the workflow has too many steps, or a specific step has UX issues. + +--- + +## Feature adoption funnel + +Awareness to repeat use. Tracks how a feature spreads through the user base. + +### Standard shape + +\| Step \| Event \| Notes \| +\|---\|---\|---\| +\| 1 \| `feature_x_announced_to_user` \| The anchor. The user saw a notification, prompt, or in-app message about feature X. \| +\| 2 \| `feature_x_first_used` \| The user tried feature X for the first time. \| +\| 3 \| `feature_x_used_in_week_2` \| The user used feature X again in a different week. \| +\| 4 \| `feature_x_used_in_week_4` \| Sustained adoption. \| + +### Time window + +4 weeks from announcement. + +### Anchor selection + +The announcement event is the right anchor for measuring rollout effectiveness. For organic discovery (no announcement), use `feature_x_first_used` as the anchor and measure the feature's reach as a denominator. + +### Drop-off interpretation + +- High drop from announcement to first use: the announcement was missed, the announcement was unclear, or the feature was not relevant to the audience. Audit by user segment. +- High drop from first use to repeat use in week 2: the feature did not deliver value on first use. Either the use case was wrong (user tried it for the wrong thing) or the value-prop is weak. +- Adoption stalls at 5% of the user base: the feature is for a niche; this may be expected. Compare against the projected target audience size. + +--- + +## Common funnel design mistakes + +### Mistake 1: vanity-event anchor + +Using `homepage_viewed` or `session_started` as the anchor. The denominator is huge; the conversion rate is tiny; the funnel says nothing about user behavior. + +Fix. Anchor on a high-intent action: signup, trial_started, feature-specific page view. + +### Mistake 2: too long + +Ten or more steps. The end-to-end conversion rate is near zero; the funnel is hard to interpret; small numerator changes look like dramatic shifts. + +Fix. Break into 2 or 3 shorter funnels. An activation funnel plus a conversion funnel beats one 10-step funnel. + +### Mistake 3: auto-firing events as steps + +Including `session_started`, `app_opened`, or any event that fires automatically. The denominator is the entire user base; the meaning of conversion rates is muddled. + +Fix. Use only intentional, semantic events as funnel steps. + +### Mistake 4: same event in multiple positions + +Using `feature_used` at step 2 and step 5. The platform double-counts; the analyst gets confused. + +Fix. Distinguish via different events (`feature_first_used` vs `feature_used_in_week_2`) or via a property filter. + +### Mistake 5: mixed time windows + +The funnel definition allows step 2 within 7 days but step 4 within 30 days. The math becomes interpretable only by the analyst who built it; everyone else gets it wrong. + +Fix. One time window for the entire funnel. Document it explicitly. + +### Mistake 6: forgetting the cohort + +Running the funnel against "all users ever" rather than a specific acquisition cohort. The cohort matters; January users behave differently from November users. + +Fix. Always specify the cohort. "Users who signed up in March, evaluated against the activation funnel within 14 days." + +--- + +## Comparing funnels across cohorts + +The strongest analytical use of funnels is comparing how the funnel performs across cohorts. + +- This month's signup cohort vs last month's: is the funnel stable, or are recent users dropping more? +- Paid acquisition cohort vs organic: are paid users converting at the same rate, or are paid users worse-quality? +- Mobile vs web: is the experience parity issue real? + +Always compare cohorts at matched ages. A 30-day-old cohort vs a 60-day-old cohort has different conversion rates by definition. diff --git a/skills/product-analytics-setup/references/instrumentation-audit-checklist.md b/skills/product-analytics-setup/references/instrumentation-audit-checklist.md new file mode 100644 index 0000000..b481bff --- /dev/null +++ b/skills/product-analytics-setup/references/instrumentation-audit-checklist.md @@ -0,0 +1,119 @@ +# Instrumentation audit checklist + +The quarterly playbook for keeping product analytics trustworthy. Five categories: schema, volume, dashboard freshness, ownership, deprecation. + +The principle. Instrumentation decays without active maintenance. Quarterly audits catch decay early; without them, the team ends up with the "we have data but cannot trust it" problem. + +--- + +## 1. Schema review + +Goal. Ensure the event taxonomy and property schema match the canonical contract. + +Steps. + +- Pull the event list from the analytics tool. Mixpanel: Lexicon. Amplitude: Govern. PostHog: Data Management. Or directly from the warehouse if warehouse-native. +- Compare against the schema definition in code. Every event in the tool should appear in the schema; every event in the schema should appear in the tool. +- Flag drift. Events firing without a schema entry. Schema entries with no events firing in the last 90 days. Property type mismatches between schema and observed values. +- Audit naming. Events that do not match the naming convention (snake_case, past tense, object-action). Property names with inconsistent casing or typo variants. +- Action items. For each drift item, decide: fix the schema, fix the tracking code, or deprecate the event. Document the decision. + +Cadence. Quarterly. More frequently if the team is shipping rapidly. + +--- + +## 2. Volume sanity check + +Goal. Confirm event volumes match expectations. + +Steps. + +- Pull weekly event counts for the last 90 days. Group by event name. +- Identify volume anomalies. Sudden drops (deployment broke instrumentation). Sudden spikes (a new code path is firing the event excessively or a bot is hitting the endpoint). Events whose volume drifts steadily down (the feature behind them was deprecated; instrumentation should follow). +- Check ratios. If `signup_started` fires 10x more than `signup_completed`, signup completion is broken or the events fire under different conditions than expected. If `checkout_started` fires more than `add_to_cart`, the events are misordered or one fires automatically. +- Compare against business reality. The dashboard says 50,000 weekly signups; the warehouse says 38,000 paying customers were acquired in the same period. The gap is fine if the business is in trial mode; alarming if the gap should be smaller. +- Action items. For each anomaly, identify the cause. Either the instrumentation is broken (fix it), the business changed (update expectations), or the event semantics drifted (version it). + +Cadence. Quarterly minimum. Real-time alerts on the highest-volume events for major deviations. + +--- + +## 3. Dashboard freshness review + +Goal. Identify dashboards that have rotted. + +Steps. + +- Pull the dashboard inventory from the analytics tool or BI platform. +- Check last-viewed dates. Dashboards not viewed in the last 90 days are candidates for deprecation. Dashboards not viewed in the last 180 days are almost always stale. +- Check last-edited dates. A dashboard last edited 18 months ago whose underlying schema changed is silently broken. Audit whether the dashboard's metrics still compute correctly. +- Check ownership. Every dashboard should have a named owner. Dashboards with no owner or with an owner who has left the company need reassignment or deprecation. +- Spot-check key metrics. Pick 5 to 10 dashboards. Compute the same metric directly from the warehouse. Compare. Drift over 5% needs investigation. +- Action items. Reassign orphan dashboards. Deprecate stale dashboards. Fix or rewrite dashboards that have drifted from underlying truth. + +Cadence. Quarterly. + +--- + +## 4. Owner assignment audit + +Goal. Every event, dashboard, cohort, and saved query has a named owner who can answer questions about it. + +Steps. + +- Pull the ownership map for events, dashboards, cohorts, saved queries. Most analytics tools support tagging or property fields for owner. +- Identify orphans. Items with no owner. Items whose owner has left the company. +- Reassign. For each orphan, assign a new owner or deprecate. Owner means "the person who can explain why this exists and what depends on it." It is not a vanity tag. +- Document the chain of custody. If the original owner left and the new owner is unfamiliar with the history, write down what you know. +- Action items. Update the ownership tags. Notify owners of items they are now responsible for. Set up a review cycle (every 6 months minimum) for owners to confirm or release ownership. + +Cadence. Quarterly minimum. Whenever someone leaves the team, immediately for their owned items. + +--- + +## 5. Deprecation candidates + +Goal. Identify and remove instrumentation, cohorts, and dashboards that no longer serve a purpose. + +Steps. + +- Identify candidate events. Events whose volume is below 10 per week. Events not referenced in any active dashboard or query in the last 90 days. Events that are duplicate or near-duplicate of other events. +- Identify candidate cohorts and saved queries. Items not used in the last 90 days. Items whose source data is now stale. +- Identify candidate dashboards. Already covered in step 3; gather candidates here. +- Soft deprecation. Tag items as deprecated; remove from default views. Wait 30 days. If anyone notices, reverse the deprecation; if nobody notices, hard delete. +- Communicate. Post the deprecation list to the data channel. Anyone with a use case has 14 days to push back. +- Action items. Soft deprecate. Wait. Hard delete on the next audit if no objections. + +Cadence. Quarterly. Hard deletion happens at the next audit, not the same one. + +--- + +## The audit deliverable + +Each quarterly audit produces a written report with five sections matching the steps above. The report includes. + +- What changed since the last audit. Events added, removed, renamed. Schema migrations completed. +- Drift identified. Events firing without schema entries. Property type mismatches. Volume anomalies. +- Decisions made. What was fixed, what was deprecated, what was deferred. +- Open items. Drift not yet resolved. Pending decisions. Owners reassigned but not yet confirmed. +- Forward planning. Schema changes anticipated next quarter. Dashboards likely to be migrated. Events likely to be deprecated. + +The report goes to the data team and the eng leads. It does not need to go to the entire company; the value is in the discipline of writing it. + +--- + +## When to skip an audit + +Never. The cost of skipping a quarter compounds. The team that audits twice a year ends up doing 3x the work each audit; the team that audits quarterly maintains a steady state. + +The exception. A team in a 30-day sprint to launch a major product version may defer one audit by 4 to 6 weeks. After that, the audit is overdue and the discipline is at risk. + +--- + +## What the audit is not + +Three things to avoid. + +- Not a witch hunt. The audit identifies drift, not blame. Many drift items are produced by good-faith engineering decisions that did not include the analytics-debt cost. +- Not perfectionism. Some drift is acceptable. Aim for 95% clean, not 100%. Spending the audit cycle chasing the last 5% leaves real problems unaddressed. +- Not silent. The audit produces a deliverable. Without the deliverable, the audit happened in someone's head; it does not transfer to the next quarter or the next team. diff --git a/skills/product-analytics-setup/references/naming-convention-reference.md b/skills/product-analytics-setup/references/naming-convention-reference.md new file mode 100644 index 0000000..c4572a7 --- /dev/null +++ b/skills/product-analytics-setup/references/naming-convention-reference.md @@ -0,0 +1,125 @@ +# Naming convention reference + +A complete style guide. Pick one convention; enforce it via CI lint. + +--- + +## The canonical conventions + +snake_case for events and properties. `user_signed_up`, `cart_value`, `trial_day`. + +Past tense, action-oriented for events. `checkout_completed`, not `complete_checkout` or `completing_checkout`. + +Object-action format for events. Noun then verb. `video_played`, `form_submitted`, `email_opened`. + +Boolean prefix for boolean properties. `is_`, `has_`, `can_`. `is_admin`, `has_trial`, `can_invite`. + +Counting suffix for count properties. `_count` or `_total`. `seat_count`, `total_purchases`, `signup_count`. + +Money in smallest unit with currency named. `price_cents` not `price` (and currency on `currency` property). + +Timestamp suffix for date-time properties. `_at` for absolute timestamps. `created_at`, `last_active_at`. `_s` or `_ms` for durations. `time_since_signup_s`. + +Period suffix for relative-time properties. `_days`, `_weeks`. `inactive_days_count`, `trial_length_days`. + +--- + +## Do and don't + +\| Don't \| Do \| Why \| +\|---\|---\|---\| +\| `Sign Up Completed` \| `signup_completed` \| snake_case, no spaces. URL-safe. \| +\| `userSignedUp` \| `user_signed_up` \| snake_case wins by default; consistent across the platform. \| +\| `signup` (event) \| `user_signed_up` \| Past tense, object-action. Reads as "this happened." \| +\| `complete_checkout` \| `checkout_completed` \| Past tense for events. \| +\| `completing_checkout` \| `checkout_completed` \| Past tense, not progressive. \| +\| `Sign Up` \| `signup` or `signed_up` \| Pick one form for the same concept. Document it. \| +\| `price: "$19.99"` \| `price_cents: 1999` plus `currency: "USD"` \| Money in smallest unit. Currency separate. \| +\| `quantity: "5"` \| `quantity: 5` \| Numbers as numbers, not strings. \| +\| `is_premium: "yes"` \| `is_premium: true` \| Booleans as booleans. \| +\| `viewed: 1` \| `is_viewed: true` \| If it is yes/no, it is boolean, not 0/1. \| +\| `created: "5/5/2026"` \| `created_at: "2026-05-05T14:30:00Z"` \| ISO 8601, always. UTC. \| +\| `tags: "a,b,c"` \| `tag_list: ["a", "b", "c"]` \| Arrays for bounded lists, not delimiter-strings. \| +\| `signup_source` (one event) plus `source` (another event) \| `signup_source` plus `referral_source` \| Disambiguate when the same name means different things. \| +\| `User Signed Up` (event), `signupCompleted` (event), `SIGN_UP` (event) \| `user_signed_up` (event), `signup_completed` (event) \| Pick one casing, stick to it. \| +\| `mailchimp_email_opened` \| `email_opened` plus `provider: "mailchimp"` property \| Brand-neutral event names; vendor as a property. \| +\| `feature_x_clicked` \| `feature_x_used` \| Track usage, not button clicks. UI events are noise. \| + +--- + +## Boolean property prefixes + +The prefix should make the property read as a yes-or-no question. + +- `is_admin` reads as "is admin?" Yes or no. +- `has_trial` reads as "has trial?" Yes or no. +- `can_invite` reads as "can invite?" Yes or no. +- `should_notify` reads as "should notify?" Yes or no. + +What NOT to do. + +- `admin: true`. Reads as "admin is true." Awkward in queries. +- `premium: 1`. Reads as a count, not a yes-or-no. +- `trial: "yes"`. String, not boolean. + +--- + +## Time, date, and duration suffixes + +\| Suffix \| Meaning \| Example \| +\|---\|---\|---\| +\| `_at` \| Absolute timestamp (ISO 8601 UTC) \| `created_at`, `last_active_at`, `event_timestamp` \| +\| `_s` \| Duration in seconds \| `time_in_step_s`, `session_duration_s` \| +\| `_ms` \| Duration in milliseconds \| `response_time_ms` \| +\| `_days` \| Duration in days (integer) \| `inactive_days_count`, `trial_length_days` \| +\| `_weeks` \| Duration in weeks (integer) \| `weeks_since_signup` \| +\| `_months` \| Duration in months (integer) \| `months_active` \| + +Mixing units across the schema produces bugs. Pick one unit per concept and document it. + +--- + +## Money + +Two rules. + +1. Smallest unit, integer. `price_cents`, `mrr_cents`, `total_revenue_cents`. Float arithmetic on money produces rounding errors. +2. Currency named separately. `currency: "USD"`. Do not assume USD; international users break the assumption. + +When the smallest unit varies (yen has no decimals; bitcoin has 8), pick a precision and document it. The integer math discipline still applies. + +--- + +## Identifiers + +Three identifier patterns. + +- Stable IDs are immutable. `user_id`, `account_id`, `product_id`. Use UUIDs or a system-generated identifier. +- Human-readable names are mutable. `product_name`, `account_name`. Useful for reporting; never use as a join key. +- Display IDs are user-visible. `invoice_number`, `order_number`. Often distinct from the database primary key. + +Always include a stable ID in event payloads. Optionally include the human-readable name for reporting convenience. + +--- + +## What NOT to encode in event names + +Three categories of detail belong on properties, not in event names. + +1. State or status. Not `user_active`, `user_inactive`. Use `user_signed_in` (event) plus `status` (user property). +2. Variant or treatment. Not `signup_variant_a`. Use `user_signed_up` (event) plus `experiment_variant` (property). +3. Source or channel. Not `signup_from_facebook`. Use `user_signed_up` (event) plus `acquisition_channel: "facebook"` (property). + +The principle. Event names answer "what happened?" Properties answer "with what context?" + +--- + +## Enforcement + +A naming convention without enforcement decays. Two patterns. + +CI lint. A schema definition (TypeScript interface, JSON Schema) plus a CI step that rejects events whose payload does not match. The lint catches new violations before they hit production. + +Code review checklist. PRs that add or modify events include a snippet showing the event name, properties, and types. The reviewer compares against the naming convention reference and the existing taxonomy. + +Without enforcement, the convention becomes documentation that nobody reads. With enforcement, it becomes a constraint that the codebase respects. diff --git a/skills/product-analytics-setup/references/north-star-metric-selection.md b/skills/product-analytics-setup/references/north-star-metric-selection.md new file mode 100644 index 0000000..979ffe8 --- /dev/null +++ b/skills/product-analytics-setup/references/north-star-metric-selection.md @@ -0,0 +1,159 @@ +# North Star metric selection + +Rules for picking a North Star metric (NSM), examples by product type, anti-patterns, and migration patterns when changing NSM. + +The principle. The NSM is the single number the team optimizes against. Picking the wrong number focuses the team on the wrong work for as long as the team uses it. + +--- + +## NSM selection rules + +A trustworthy NSM passes four tests. + +1. Reflects user value, not company value alone. Revenue is company value; the NSM should track an action that delivers user value. Revenue can be the trailing measure; the NSM is the leading driver. +2. Captures the core action that, if it grows, the business grows. The NSM should be cause-correlated with revenue growth, retention, and any other business goal. If you double the NSM and the business does not improve, the NSM is wrong. +3. Measurable consistently across time. The definition should not drift. If the NSM definition changes every quarter, year-over-year comparison is impossible. +4. Hard to game. The team should not be able to grow the NSM via shortcuts that do not deliver user value. A gameable NSM produces local maxima that the team optimizes toward at the expense of the actual mission. + +--- + +## Examples by product type + +### Engagement-driven products + +The product creates ongoing value through repeated use. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Slack \| Messages sent in workspaces of 3+ active users per week \| Captures recurring value; harder to game than DAU; size threshold filters out trial-only users. \| +\| Figma \| Weekly active editors \| The action that delivers value (creating in Figma); active editors filters out viewers who do not get full product value. \| +\| Notion \| Weekly content blocks created per workspace \| Captures the core verb (creating); per-workspace normalizes for team size variance. \| +\| Linear \| Weekly issues created per workspace \| The product use case is project tracking; issues created is the load-bearing action. \| + +### Transaction-driven products + +The product makes money on each transaction. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Airbnb \| Nights booked (not bookings) \| Nights captures the value delivered to hosts and guests; bookings count is gameable via short stays. \| +\| Uber \| Rides completed (not requests) \| Completion includes the driver-side fulfillment; requests alone misses the supply-side metric. \| +\| Etsy \| GMV per active buyer \| GMV per buyer is more stable than total GMV; it tracks user value rather than top-line growth alone. \| + +### Conversion-driven products (SaaS subscription) + +The product is sold via subscription; the NSM tracks recurring engagement that drives renewal. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| HubSpot \| Activated workspaces (defined as workspaces using 3+ products) \| Multi-product use is the activation signal that drives expansion revenue. \| +\| Stripe (developer-side) \| Production payments processed per merchant per week \| Captures the core transaction; per-merchant per-week filters for active integrations. \| +\| Calendly \| Meetings booked via Calendly per user per week \| The exact value delivered (meetings booked) and the recurring cadence. \| + +### Content-driven products (media, publishing) + +The product delivers value through content consumption. + +\| Product \| NSM \| Why it works \| +\|---\|---\|---\| +\| Spotify \| Hours listened per active user \| Hours captures depth of engagement; per active user normalizes for catalog growth. \| +\| YouTube (creator-side) \| Watch time per video per audience cohort \| Watch time is the core metric that drives ads and creator earnings. \| +\| Substack (writer-side) \| Paid subscribers added per month \| The action that converts to revenue; not just total subscribers (which is lagging). \| + +--- + +## Anti-patterns + +Six NSMs that consistently produce the wrong incentives. + +### Bad NSM 1: signups + +Captures top-of-funnel volume, not value. A team optimizing for signups loosens activation criteria and chases low-quality acquisition channels. The NSM grows; the business does not. + +### Bad NSM 2: revenue + +Lagging, not action-oriented. The team can optimize against revenue only by changing pricing or sales tactics. Revenue is the trailing outcome; the NSM should be the leading action that produces revenue. + +### Bad NSM 3: DAU (daily active users) + +Useful for engagement-driven products with a daily cadence. Misleading for products with a longer cadence (weekly, monthly). DAU on a B2B SaaS often shows an unhealthy daily ritual the product does not actually need. + +### Bad NSM 4: page views or sessions + +Captures traffic, not value. A team optimizing for page views or sessions loosens content quality and adds engagement loops that do not deliver user value. + +### Bad NSM 5: feature usage + +The team optimizes for "feature X used" by promoting feature X aggressively. The feature usage grows; the underlying user value may not. NSM should capture cross-cutting value, not feature-specific use. + +### Bad NSM 6: reviews or NPS + +Captures sentiment, not value. NPS is useful as a health metric but a poor NSM because it is heavily influenced by survey design and customer-service interactions, neither of which the product team controls directly. + +--- + +## Supporting metrics framework + +The NSM does not stand alone. Around it lives a framework of input metrics and health metrics. + +### One NSM + +The single number the team optimizes against. + +### Three to five input metrics + +The metrics that drive the NSM. If the input metrics improve, the NSM should follow. + +For "weekly active editors" (Figma's NSM): +- Signups per week (the top of the funnel) +- Signup-to-active conversion rate (the activation step) +- Week-over-week active retention (the repeat-use step) + +For "messages sent in workspaces of 3+ active users per week" (Slack's NSM): +- Workspaces created per week +- Workspaces reaching 3+ active members +- Messages per active workspace per week + +The team's roadmap should map every initiative to one or more input metrics. + +### Five to ten health metrics + +Metrics that warn of problems. They should not regress while the NSM grows. + +- Monthly churn rate +- Account-level concentration (is growth coming from one big customer?) +- Support ticket volume per active user +- Latency or error rate +- Activation rate (signup-to-NSM-action) + +If any health metric regresses while the NSM grows, the team should investigate before declaring success. + +--- + +## Migration patterns when changing NSM + +The NSM should change rarely. When it does, the migration is high-risk. + +### Pattern 1: phased migration + +Run both NSMs in parallel for a quarter. Track team behavior; document where the new NSM produces different incentives. Decide based on real evidence, not speculation. + +### Pattern 2: shadow mode first + +The new NSM is tracked privately by the data team. The team continues to optimize against the old NSM. After 90 days, the data team reports on the divergence. Public switch happens only if the new NSM clearly aligns better with business outcomes. + +### Pattern 3: replace plus reinforce + +The new NSM replaces the old. The old metric becomes a health metric (still tracked, no longer the primary target). Over the next 6 months, ensure the old metric does not regress while the new NSM grows. + +--- + +## When to refuse to change the NSM + +Three signs that a proposed NSM change is wrong. + +1. The change is reactive to a single quarter's bad numbers. "Our NSM went down so we should change the NSM" is not a reason to change the NSM. +2. The proposed new NSM is gameable. A new NSM that the team can grow without delivering user value is worse than the existing NSM, even if the old one is imperfect. +3. The change has no concrete decision the team will make differently. If switching from old NSM to new NSM does not change which initiatives the team prioritizes, the change is theater. + +The NSM should be stable for years. Change it when the business model changes substantively or when the existing NSM is producing demonstrably wrong incentives. diff --git a/skills/product-analytics-setup/references/property-design-patterns.md b/skills/product-analytics-setup/references/property-design-patterns.md new file mode 100644 index 0000000..7c75d02 --- /dev/null +++ b/skills/product-analytics-setup/references/property-design-patterns.md @@ -0,0 +1,168 @@ +# Property design patterns + +Event-level vs user-level properties, with type discipline and a worked example. + +The principle. Event-level properties describe a specific event. User-level properties describe a user across all events. Mixing them up creates payload bloat, schema drift, and reporting confusion. + +--- + +## Event-level vs user-level + +Event-level properties belong on the event payload. They describe the specific event, snapshot at the moment it fires. + +- `cart_value` on `checkout_completed` +- `item_count` on `checkout_completed` +- `payment_method` on `checkout_completed` +- `discount_code` on `checkout_completed` +- `referrer_source` on `user_signed_up` + +User-level properties belong on the user profile. They describe the user over time. Set them once; the analytics tool joins them onto every event the user fires. + +- `subscription_tier` +- `acquisition_channel` +- `lifetime_value` +- `account_role` +- `is_admin` +- `last_active_at` + +The trap. Putting user-level properties on every event payload. Three problems. + +1. Payload bloat. Every event carries the same `subscription_tier` value. Multiplied across millions of events, the storage and bandwidth cost is real. +2. Schema drift when the value changes. A user upgrades mid-session. Some events have `subscription_tier: free`; later events have `subscription_tier: pro`. Reporting becomes ambiguous about which value to use. +3. Reporting confusion. Analyst writes "WHERE subscription_tier = 'pro'" thinking they are filtering users. The query actually filters events, returning a different cohort. + +The fix. Set user-level properties on the user profile via the platform's identify/track-user API. Let the analytics tool perform the join. + +--- + +## Type discipline + +Property types matter. The analytics tool will accept any value, but the reporting breaks when types are inconsistent. + +Strings for enumerable values. + +- `status`, `tier`, `channel`, `region`, `category` +- Bounded sets. Document the allowed values in the schema. +- Wrong: storing numbers as strings. `quantity: "5"` breaks every numeric aggregation. + +Numbers for actual numbers. + +- `count`, `value`, `duration_s`, `score` +- Cents (or smallest unit) for money. Never floats. `price_cents: 1999`, not `price: 19.99`. +- Wrong: `trial_day: "day 7"`. Use `trial_day: 7`. + +Booleans for actual booleans. + +- `is_admin`, `has_trial`, `is_new_user` +- Two values: `true` and `false`. Nothing else. Not "yes"/"no", not 1/0, not strings. +- Prefix discipline: `is_`, `has_`, `can_`. Reading the property name should suggest a yes/no question. + +Timestamps in ISO 8601, always. + +- `created_at`, `last_active_at`, `event_timestamp` +- Format: `2026-05-05T14:30:00Z` (UTC, with the Z suffix). +- Wrong: Unix timestamps as strings, locale-specific formats, or any other variant. ISO 8601 across the entire schema. +- Suffix discipline: `_at` for timestamps, `_s` or `_ms` for durations. + +Arrays rarely. + +- An array property usually means you should split into multiple events with one item per event. +- Example: instead of `cart.items: [item_a, item_b, item_c]` on `checkout_completed`, fire one `item_purchased` event per item plus one `checkout_completed` event with the item count. +- Exception: small bounded arrays where the use case is clear (e.g., `tag_list: ["urgent", "billing"]`). + +--- + +## Worked example: product_viewed event + +A `product_viewed` event fires when a user views a product detail page in an e-commerce app. + +### Wrong design + +```json +{ + "event": "Product Viewed", + "user_id": "u_12345", + "product": "Premium Hoodie", + "price": "$49.99", + "category": "Apparel", + "user_subscription_tier": "Premium", + "user_lifetime_purchases": 8, + "user_acquisition_source": "Meta", + "is_premium_user": "true", + "viewed_at": "5/5/2026 2:30 PM", + "tags": "summer, hoodie, sale" +} +``` + +Problems. + +- Event name uses spaces and mixed case. `Product Viewed` should be `product_viewed`. +- `price` is a money string with currency symbol. Should be `price_cents: 4999`. +- User-level properties on the event: `user_subscription_tier`, `user_lifetime_purchases`, `user_acquisition_source`, `is_premium_user`. These belong on the user profile. +- `is_premium_user` is a string `"true"`, not a boolean. +- `viewed_at` is a locale-specific date format. Should be ISO 8601: `2026-05-05T14:30:00Z`. +- `tags` is a comma-delimited string. Should be an array of strings, or split into separate events. +- `product` is the human-readable name; lacks the stable identifier. Should include `product_id`. + +### Right design + +User profile (set via `identify`): + +```json +{ + "user_id": "u_12345", + "subscription_tier": "premium", + "lifetime_purchase_count": 8, + "acquisition_channel": "meta", + "is_premium": true, + "last_active_at": "2026-05-05T14:30:00Z" +} +``` + +Event payload (`product_viewed`): + +```json +{ + "event": "product_viewed", + "user_id": "u_12345", + "product_id": "p_premium_hoodie_v2", + "product_name": "Premium Hoodie", + "price_cents": 4999, + "currency": "USD", + "category": "apparel", + "tag_list": ["summer", "hoodie", "sale"], + "viewed_at": "2026-05-05T14:30:00Z" +} +``` + +Differences. + +- Event name is `snake_case`. +- Money in cents with currency named. +- User-level properties live on the user profile, not the event. The analytics tool joins them. +- Boolean is an actual boolean. +- Timestamp is ISO 8601 UTC. +- Tags are a bounded array (acceptable here because the use case is faceted filtering). +- Stable identifier (`product_id`) included alongside the human-readable name. + +--- + +## When to put a property on every event + +A small set of properties should appear on every event regardless of category. + +- `app_version` and `platform` (web, ios, android, desktop) +- `device_type` and `device_id` +- `session_id` +- `experiment_assignments` if the user is in active experiments + +These are technically event-level (they describe the context of the event) but they are required across every event for path analysis and segmentation. + +--- + +## Common property design mistakes + +- Property names that are also event names. `signup` as a property and `signup` as an event creates queries that depend on context. Disambiguate. +- Free-text properties for things that should be enums. "Where did you hear about us?" with free-text answers produces 47 unique values that map to 5 actual channels. Force the enum at collection time. +- Storing PII in properties. Email addresses, full names, phone numbers should not be in event properties. Use a hashed identifier and look up PII separately. +- Reusing property names across events with different meanings. `source` on `user_signed_up` means acquisition source. `source` on `email_opened` means email campaign source. Same name, different meaning, breaks queries. diff --git a/skills/product-analytics-setup/references/schema-versioning-patterns.md b/skills/product-analytics-setup/references/schema-versioning-patterns.md new file mode 100644 index 0000000..cd610a4 --- /dev/null +++ b/skills/product-analytics-setup/references/schema-versioning-patterns.md @@ -0,0 +1,167 @@ +# Schema versioning patterns + +Schema changes are inevitable. The discipline is distinguishing safe changes from breaking ones, then versioning the breaking ones. + +--- + +## Additive vs breaking changes + +Additive changes are safe. They preserve existing dashboards and queries. + +- New event. `feature_y_used` ships alongside existing events. Old dashboards continue to work. +- New property on an existing event. `checkout_completed` gains a `discount_code` property. Old dashboards ignore it; new dashboards can use it. +- New value in an enum. The `acquisition_channel` enum gains `"tiktok"`. Old dashboards may filter incorrectly if they hard-code values; usually low-risk. + +Breaking changes require migration. + +- Renamed event. `signup_complete` becomes `user_signed_up`. Every dashboard, query, and saved cohort referencing the old name breaks. +- Removed property. `cart_value_cents` is removed because it was redundant with `total_value_cents`. Queries referencing the removed property fail. +- Changed property type. `price` was a string; now it is a number. Existing queries cast or compare differently. +- Narrowed enum. `acquisition_channel` previously had `"organic"` and `"paid"`; the new schema removes `"organic"` and replaces it with `"organic_search"` and `"organic_social"`. Old queries break. +- Changed semantics. The same event name now fires under different conditions. The dashboard reading "weekly active users" silently gets a different number. + +The rule. If old code or old queries continue to work after the change, it is additive. Otherwise, it is breaking. + +--- + +## The `_v2` suffix pattern + +Versioning in the event name makes the change visible at every layer. + +``` +checkout_completed <- v1, fires alongside v2 during transition +checkout_completed_v2 <- new semantics, new schema +``` + +The transition. + +1. Phase 1: ship v2 alongside v1. Both events fire. Dashboards continue to read v1. New queries can use v2. +2. Phase 2: migrate dashboards. Update every saved query, dashboard tile, and downstream consumer to read v2. Document each migration. +3. Phase 3: deprecate v1. Stop firing v1. Mark it deprecated in the schema. Remove from event tracking instrumentation. +4. Phase 4: cleanup. Six months after deprecation, remove v1 from any historical reference documentation. Existing v1 data in the warehouse stays for historical analysis but is not used in current dashboards. + +Typical transition window. 90 days from v2 ship to v1 deprecation. Longer if the team is small or the dashboard inventory is large. + +--- + +## The data contract idea + +The canonical schema lives in code, not in the analytics tool. + +### TypeScript interface + +```typescript +// schema/events.ts + +export interface CheckoutCompletedEvent { + event: "checkout_completed"; + user_id: string; + account_id: string; + cart_value_cents: number; + currency: string; + item_count: number; + payment_method: "card" \| "paypal" \| "apple_pay" \| "google_pay"; + discount_code?: string; + event_timestamp: string; // ISO 8601 UTC +} + +export interface UserSignedUpEvent { + event: "user_signed_up"; + user_id: string; + account_id: string; + signup_source: "homepage" \| "pricing_page" \| "blog" \| "invite" \| "other"; + referrer_source: string \| null; + event_timestamp: string; +} + +export type AnalyticsEvent = + \| CheckoutCompletedEvent + \| UserSignedUpEvent; + // ... etc. +``` + +The interface is the contract. TypeScript catches type mismatches at compile time. The CI pipeline runs the type check. + +### JSON Schema + +For non-TypeScript projects, JSON Schema serves the same role. + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "checkout_completed", + "type": "object", + "required": ["event", "user_id", "account_id", "cart_value_cents", "currency", "item_count", "payment_method", "event_timestamp"], + "properties": { + "event": { "const": "checkout_completed" }, + "user_id": { "type": "string" }, + "account_id": { "type": "string" }, + "cart_value_cents": { "type": "integer", "minimum": 0 }, + "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, + "item_count": { "type": "integer", "minimum": 1 }, + "payment_method": { "enum": ["card", "paypal", "apple_pay", "google_pay"] }, + "discount_code": { "type": "string" }, + "event_timestamp": { "type": "string", "format": "date-time" } + } +} +``` + +A CI step validates events against the schema before they ship. + +--- + +## CI lint patterns + +Three lint rules catch most schema drift. + +1. Type validation. Every event payload validates against its declared type. Failed validations fail the build. +2. Naming convention check. Event names match snake_case. Property names match snake_case. Boolean properties have `is_`, `has_`, or `can_` prefix. +3. Forbidden-event check. Removed or deprecated events do not appear in the codebase. The deploy that adds a deprecated event back fails. + +Implementation. A pre-commit hook plus a GitHub Actions workflow plus a runtime sampling check (random 1% of events validated against the schema in production; failures alert). + +--- + +## Migration patterns for breaking changes + +Three common migration patterns. + +### Pattern 1: rename + +The event name changes. The semantics are the same. + +1. Ship v2 with the new name; old name continues to fire. +2. Migrate dashboards, queries, saved cohorts. +3. Deprecate v1. + +### Pattern 2: split + +One event splits into two or more events with narrower meanings. + +1. Ship the new events; the old event continues to fire alongside. +2. Update tracking code to fire the appropriate new event instead of the old one. +3. Migrate dashboards. +4. Deprecate the old event. + +Example. `subscription_changed` splits into `subscription_upgraded` and `subscription_downgraded`. Both new events provide more analytical power than the old single event. + +### Pattern 3: merge + +Two events merge into one event with a discriminating property. + +1. Ship the new event with the discriminating property. +2. Update tracking code to fire the new event with the appropriate property value. +3. Migrate dashboards (often: queries that filtered on event name now filter on property value). +4. Deprecate the old events. + +Example. `signup_via_facebook` and `signup_via_google` merge into `user_signed_up` with `auth_method: "facebook" \| "google"`. + +--- + +## Common schema versioning mistakes + +- Renaming events without versioning. The dashboards break overnight; the team blames the analytics tool. +- Skipping the transition period. v2 ships and v1 stops firing the same day. Historical analysis of v1 data is fine, but in-flight queries break. +- Versioning everything pre-emptively. `event_v3_v2` is overkill. Version when semantics change, not at every iteration. +- Letting the analytics tool be the schema source of truth. The tool's "events you have ever fired" list is a graveyard, not a contract. Maintain the schema in code; export to the tool. +- No CI enforcement. The discipline becomes an etiquette that decays as the team grows. Enforcement is the only thing that scales. diff --git a/skills/product-configurator-design/SKILL.md b/skills/product-configurator-design/SKILL.md new file mode 100644 index 0000000..593b80c --- /dev/null +++ b/skills/product-configurator-design/SKILL.md @@ -0,0 +1,289 @@ +--- +name: product-configurator-design +description: "Designing build-your-own product configurators (Tesla-style, custom-pricing, plan-builders) with constraint logic, real-time pricing, validation, and save-and-share mechanics. Honest about infinite-options (decision paralysis), canned-bundles-only (no real customization), and guided-configuration (smart defaults plus meaningful constraints plus escape hatches) patterns. Triggers on configurator design, build-your-own, custom configuration, plan builder, product customizer, configuration tool. Also triggers when users abandon mid-configuration, when configurator conversion is poor, or when a configurator is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing interactive product configurators. Distinguishes infinite-options (decision paralysis from too many options) from canned-bundles-only (no real customization) from guided-configuration (smart defaults plus meaningful constraints plus escape hatches)" +display_order: 12 +--- + +# Product Configurator Design + +A senior product marketing director's playbook for designing build-your-own product configurators. Tesla-style vehicle configurators, custom-pricing builders, plan-builders, product customizers. Constraint logic, real-time pricing, validation, save-and-share mechanics. The discipline of building a configurator that produces configurations users actually commit to. + +Most configurators fail in one of two ways. They expose every parameter at full granularity (47 toggles, 12 sliders) and produce decision paralysis; users abandon halfway through. Or they pretend to be configurators but are actually three pre-built bundles labeled "Custom"; the configurator framing was marketing while the product is bundles. + +The configurators that work do something different. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations and surface why; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Users feel guided rather than overwhelmed. + +The voice is the senior product marketing director who has watched configurators double conversion when redesigned with smart defaults and watched them collapse when "more options" were added without constraint logic. Practical, opinionated about the constraints that protect users from themselves, willing to call out when canned bundles are the right answer. + +When to use this skill: scoping a build-your-own configurator for the first time, auditing a configurator with high abandonment, designing the constraint logic that prevents invalid combinations, or deciding which parameters earn exposure vs which should default. + +--- + +## What this skill covers + +This skill spans build-your-own product configurators. The growth-tooling distinctions: + +- `calculator-design` is calculators that give a number from inputs. This skill builds a product configuration with multiple decisions. +- `comparison-tool-design` is comparing known options. This skill builds a custom option. +- `multi-step-form-design` is data capture. This skill is configuration design. +- `product-configurator-design` (this skill) is constraint logic, real-time pricing, validation, save-and-share, and configurator-to-cart handoff. +- `pm-spec-writing` is the spec for engineers building the configurator. + +The audience: product marketers, growth marketers, ecommerce teams, B2B teams shipping configurable products, agencies running configurator work for clients. + +Out of scope: calculator design (covered by `calculator-design`); comparison tools (covered by `comparison-tool-design`); the engineering implementation; specific configurator-platform configurations (those stay implementation-side). + +--- + +## The configurator decision: when configurators earn investment vs when bundles suffice + +Before designing the configurator, decide whether a configurator is the right answer. + +Configurators earn investment when: + +- The product has genuinely customizable parameters that affect outcome and cost. +- The audience values customization beyond what bundles offer. +- The team can support the configuration logic (validation, pricing, fulfillment). +- The combinatorial space is meaningful but constrained (not literally infinite). + +Configurators do NOT earn investment when: + +- The product is essentially bundles. Calling them "configurations" is marketing, not product. +- The audience does not value customization. Some audiences want to choose from curated options, not build. +- The combinatorial space is so large that no audience can navigate it. +- Customization produces invalid combinations the team cannot prevent. +- A simpler comparison or selection tool would serve. + +The decision is not "should we have a configurator"; it is "is the configurator the right tool for this product and audience." + +Detail in [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md). + +--- + +## Infinite-options vs canned-bundles-only vs guided-configuration + +The keystone framing. + +Infinite-options. Every parameter exposed at full granularity. 47 toggle switches and 12 sliders. Decision paralysis. Users abandon halfway through; few complete a configuration. Cost: design effort produces a configurator nobody completes; conversion suffers. + +Canned-bundles-only. "Configurator" that is actually three pre-built bundles labeled Basic/Pro/Enterprise. No real customization. The configurator framing was marketing; the product is bundles. Cost: audience that came expecting customization feels deceived; conversion suffers because expectations did not match reality. + +Guided-configuration. Smart defaults that produce a sensible starting configuration; meaningful constraints that prevent invalid combinations; escape hatches into deeper customization for users who want it; real-time pricing that responds to choices. Cost: design effort upfront is significant; conversion typically improves meaningfully because users complete configurations they commit to. + +The litmus test. Hand the configurator to a stranger in the target audience. Do they reach a configuration they would actually buy in under 5 minutes without expert help? If yes, guided-configuration. If they paralyze at the options, infinite-options. If they only see bundles, canned-bundles-only. + +--- + +## Default-configuration design + +The starting point. + +The principle. The configurator opens with a sensible default configuration. The user adjusts from there. + +Default selection. + +- The configuration most audiences would choose. +- Reflects audience research (sales-call mining, prior configurations). +- Inferable from referrer, query, or stated preference. + +Default presentation. + +- Default visible immediately; user sees a complete configuration with price. +- Adjust controls obvious; user knows what is changeable. +- Reset-to-default available; users who experiment can return. + +The blank-canvas trap. Configurator opens empty; user must build from scratch. Decision paralysis at the start. + +The cure. Default-heavy. The user adjusts; never builds from zero. + +Detail in [`references/default-configuration-design.md`](references/default-configuration-design.md). + +--- + +## Constraint logic + +Preventing invalid combinations; surfacing why. + +The principle. The configurator should not let users build invalid configurations (combinations that cannot ship, cannot be priced, or do not work together). When constraints engage, the configurator surfaces why. + +Constraint patterns. + +- Hard constraints. "Option A and Option B are incompatible." Configurator prevents the combination; explains why. +- Soft constraints. "Combining Option A with Option C is unusual but possible." Configurator allows; warns. +- Implication constraints. "Selecting Option A requires Option D." Configurator auto-includes D; explains. +- Capacity constraints. "This configuration exceeds shipping capacity." Configurator caps; explains. + +Constraint communication. + +- Why this constraint engaged. +- What user can do (different option, contact for custom). +- No friction-only blocking; always offer a path. + +The over-constrained trap. Too many constraints; user feels boxed in. + +The under-constrained trap. User builds configuration that fails at checkout or fulfillment. + +Detail in [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md). + +--- + +## Real-time pricing and impact display + +Pricing that responds to choices. + +The principle. Price updates as the user adjusts. The user sees the cost impact of each choice immediately. + +Strong pricing display. + +- Total price prominent and updated in real time. +- Per-choice impact visible ("Adds $X" or "Saves $X"). +- Breakdown available ("How is this priced"). +- Currency and locale appropriate. + +Weak pricing display. + +- Price hidden until the end. +- Per-choice impact invisible; user does not know what each option costs. +- Breakdown not available; total is opaque. + +The price-shock trap. User configures heavily; reaches checkout; sees a price they did not expect; abandons. + +The cure. Price visible throughout. No surprises at checkout. + +Detail in [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md). + +--- + +## Validation and error patterns + +When the configurator catches invalid input. + +The principle. Validation should be helpful, not punitive. + +Validation patterns. + +- Inline validation. Error appears next to the invalid choice. +- Pre-emptive validation. Constraint logic prevents the error from being possible. +- Final validation. Pre-checkout review surfaces any remaining issues. + +Error communication. + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +The validation-strict trap. Validation rejects valid edge-case inputs. + +The validation-loose trap. Configurator accepts inputs that fail downstream. + +Detail in [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md). + +--- + +## Save-and-share mechanics + +Configurations users return to or send to others. + +The principle. Configurators that serve real decision-making produce configurations users want to save and share. + +Save patterns. + +- Email-link save. User enters email; configuration link emailed. +- Account-based save. Logged-in users save automatically. +- Anonymous-session save. Browser-based persistence. + +Share patterns. + +- Shareable URL. Configuration encoded in URL; share via any channel. +- Embed code. Configuration embeddable on other sites or in proposals. +- Email share. Direct email-to-recipient with configuration. + +Why save-and-share matters. + +- Multi-decision purchases require deliberation. +- B2B configurations often need stakeholder review. +- Returning users continue rather than restart. + +Detail in [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md). + +--- + +## Configurator-to-cart handoff + +When the user commits. + +The principle. Handoff from configurator to cart should preserve the configuration entirely. + +Handoff patterns. + +- Configuration becomes the cart item. +- Cart shows the configuration summary. +- Edit-from-cart returns to configurator with state preserved. + +The handoff failure. Configuration partially preserved; cart shows a generic SKU; user cannot tell if their custom build is reflected. + +The cure. Handoff loop closed. Configuration visible in cart; price matches; edits possible. + +Detail in [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-configurator-failures.md`](references/common-configurator-failures.md). + +- "Users abandon halfway through configuration." Likely infinite-options pattern; too many decisions. +- "Configurator generates valid-looking configs that fail at fulfillment." Under-constrained; constraint logic missing. +- "Users complain about price surprises at checkout." Pricing not real-time or hidden until end. +- "Sales says many users contact for help configuring." Configurator too complex for audience; defaults wrong. +- "Users save configurations but do not return." Save mechanism works but follow-up missing. +- "Configurator works on desktop, breaks on mobile." Mobile UX broken. +- "Audience completes but conversion to purchase is low." Configurator works; commitment friction at handoff. +- "We added more options; abandonment climbed." Crossed the cognitive-load threshold. +- "Constraint engaged but user did not understand why." Communication broken; users feel arbitrarily blocked. + +--- + +## The framework: 12 considerations for configurator design + +When designing or auditing a configurator, walk these 12 considerations. + +1. The configurator decision. Is configurator the right tool, or do bundles serve? +2. Guided-configuration, not infinite-options or canned-bundles-only. Smart defaults plus meaningful constraints plus escape hatches. +3. Default configuration sensible. User adjusts from default; does not build from zero. +4. Constraint logic prevents invalid combinations. Hard, soft, implication, capacity constraints. +5. Constraint communication clear. Why constraint engaged; what user can do. +6. Real-time pricing visible. Price updates with choices; breakdown available. +7. Validation helpful. Inline; specific; offers paths. +8. Save-and-share works. Multi-session; shareable; B2B-friendly. +9. Configurator-to-cart handoff preserves state. Cart shows configuration. +10. Mobile parity. Configurator works on the devices the audience uses. +11. Conversion as success metric. Not just completion rate; downstream purchase. +12. Maintenance discipline. Configurations updated as product changes; quarterly audit. + +The output of the framework is a configurator that earns the configuration that ships, with constraint logic, pricing, and handoff working together to produce commitments users keep. + +--- + +## Reference files + +- [`references/configurator-decision-criteria.md`](references/configurator-decision-criteria.md) - When configurators earn the build vs when bundles serve. +- [`references/default-configuration-design.md`](references/default-configuration-design.md) - The starting point. Default selection and presentation. +- [`references/constraint-logic-patterns.md`](references/constraint-logic-patterns.md) - Hard, soft, implication, capacity constraints. Communication patterns. +- [`references/real-time-pricing-patterns.md`](references/real-time-pricing-patterns.md) - Price updates with choices. Breakdown and impact display. +- [`references/validation-and-error-patterns.md`](references/validation-and-error-patterns.md) - Helpful validation. Inline, pre-emptive, final. +- [`references/save-and-share-mechanics.md`](references/save-and-share-mechanics.md) - Email-link, account, anonymous, shareable URL, embed. +- [`references/configurator-to-cart-handoff.md`](references/configurator-to-cart-handoff.md) - Handoff that preserves configuration; cart visibility; edit-from-cart. +- [`references/configurator-anti-patterns.md`](references/configurator-anti-patterns.md) - The patterns that look like configurators but degrade conversion. +- [`references/common-configurator-failures.md`](references/common-configurator-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: configurators earn investment when they earn the configuration that ships + +The configurators that work as compounding assets are the ones that produce configurations users commit to. Not 50-cell decision matrices. Not bundles dressed as configurators. Configurations the user built, priced, validated, saved, and bought. + +That is the bar. Below the bar are infinite-options (decision paralysis; users abandon) and canned-bundles-only (configurator framing without real customization; users feel deceived). Above the bar are guided-configuration tools where smart defaults, meaningful constraints, real-time pricing, validation, and save-and-share work together to produce commitments. + +The discipline is in the design choices. The decision to build a configurator at all. The default configuration that opens the experience. The constraint logic that protects users from invalid combinations. The pricing that updates with choices. The validation that helps without punishing. The save-and-share that supports multi-decision purchases. The cart handoff that preserves the configuration. The maintenance that keeps the configurator in sync with the product it represents. diff --git a/skills/product-configurator-design/references/common-configurator-failures.md b/skills/product-configurator-design/references/common-configurator-failures.md new file mode 100644 index 0000000..2e5c19c --- /dev/null +++ b/skills/product-configurator-design/references/common-configurator-failures.md @@ -0,0 +1,179 @@ +# Common configurator failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Users abandon halfway through configuration." + +The diagnosis. Likely infinite-options pattern; too many decisions. + +The cure. Smart defaults; reduce option count; escape hatches into deeper customization. + +--- + +## "Configurator generates valid-looking configs that fail at fulfillment." + +The diagnosis. Under-constrained; constraint logic missing. + +The cure. Add constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## "Users complain about price surprises at checkout." + +The diagnosis. Pricing not real-time or hidden until end. + +The cure. Real-time pricing throughout. Detail in `references/real-time-pricing-patterns.md`. + +--- + +## "Sales says many users contact for help configuring." + +The diagnosis. Configurator too complex for audience; defaults wrong. + +The cure. Audit defaults; reduce option exposure; consider canned bundles for simple cases. + +--- + +## "Users save configurations but do not return." + +The diagnosis. Save mechanism works but follow-up missing. + +The cure. Reminder email after save; nudge before configuration expires. + +--- + +## "Configurator works on desktop, breaks on mobile." + +The diagnosis. Mobile UX broken. + +The cure. Mobile-first design and testing. + +--- + +## "Audience completes but conversion to purchase is low." + +The diagnosis. Configurator works; commitment friction at handoff. + +The cure. Audit cart handoff; ensure configuration preserved; reduce checkout friction. + +--- + +## "We added more options; abandonment climbed." + +The diagnosis. Crossed cognitive-load threshold. + +The cure. Cut options; surface fewer; defer complexity behind escape hatches. + +--- + +## "Constraint engaged but user did not understand why." + +The diagnosis. Communication broken. + +The cure. Constraint copy specific; explains why; offers paths. + +--- + +## "Configurations frequently differ from cart." + +The diagnosis. Handoff broken. + +The cure. Test cart handoff. Configuration ID system; single pricing source. + +--- + +## "Sales says enterprise customers want full configurations sales-led." + +The diagnosis. Enterprise audience wants white-glove; configurator self-serve does not match expectation. + +The cure. Enterprise path: configurator surfaces "Talk to sales for custom" for above-threshold configurations. + +--- + +## "We A/B tested adding more options; conversion went down." + +The diagnosis. Crossed the threshold. + +The cure. More is not always better. Maintain option discipline. + +--- + +## "Returning users see different prices than they saved." + +The diagnosis. Pricing shifted; configurator silently updated. + +The cure. Honest about price changes on resume. + +--- + +## "Mobile configuration completion is half of desktop." + +The diagnosis. Mobile UX significantly worse. + +The cure. Mobile-first redesign; reduce option exposure on mobile. + +--- + +## "Validation rejects valid international inputs." + +The diagnosis. Validation too strict. + +The cure. Audit validation rules; allow international formats. + +--- + +## "Some configurations work; others fail post-checkout." + +The diagnosis. Constraint logic incomplete; some invalid combinations slip through. + +The cure. Audit constraints. Add missing rules. + +--- + +## "Configurator's average configuration is more expensive than baseline." + +The diagnosis. May not be a problem (real customization adds cost) or may be (default biased toward expensive). + +The cure. Audit defaults. Defaults should reflect typical use, not flatter revenue. + +--- + +## "Sales pipeline shrunk after configurator launch; people self-serve." + +The diagnosis. Configurator absorbed the audience that would have called. + +The cure. This may be intentional (cost reduction) or unintentional (loss of complex deals). Decide if the shift is desired. + +--- + +## "Configurator launched; analytics broke." + +The diagnosis. Instrumentation missed. + +The cure. Verify analytics post-launch. Per-step instrumentation for diagnostic. + +--- + +## The pattern across failures + +Most configurator failures fall into one of three patterns. + +Pattern 1: Cognitive overload. Infinite-options, too many decisions, no defaults. The fix is guided-configuration. + +Pattern 2: Trust damage. Hidden pricing, price drift, unclear constraints, lost state. The fix is transparency. + +Pattern 3: Handoff failures. Cart loses configuration; checkout disappears it. The fix is loop closure. + +The metric pattern: configurator failures often look fine on engagement. Signal is in completion rate, conversion to purchase, downstream order accuracy. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (cognitive overload, trust damage, handoff). The principle that engagement alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-anti-patterns.md b/skills/product-configurator-design/references/configurator-anti-patterns.md new file mode 100644 index 0000000..d31b61b --- /dev/null +++ b/skills/product-configurator-design/references/configurator-anti-patterns.md @@ -0,0 +1,193 @@ +# Configurator anti-patterns + +The patterns that look like configurators but degrade conversion. Easy to ship; the cost shows up in completion rates, downstream conversion, and brand trust. + +--- + +## The infinite-options configurator + +The pattern. Every parameter exposed at full granularity. + +The signal. Decision paralysis; high abandonment. + +The cure. Smart defaults; meaningful constraints; escape hatches into deeper customization. + +--- + +## The canned-bundles-only configurator + +The pattern. Three pre-built bundles labeled "Custom." + +The signal. Audience expecting customization feels deceived. + +The cure. Real configuration logic; or honest bundle framing. + +--- + +## The blank-canvas configurator + +The pattern. Configurator opens empty; user must build from scratch. + +The signal. First-step abandonment. + +The cure. Default-heavy. Open with sensible default. + +--- + +## The hidden-pricing configurator + +The pattern. Price not visible until checkout. + +The signal. Users abandon at checkout when total surprises. + +The cure. Real-time pricing throughout. + +--- + +## The under-constrained configurator + +The pattern. User can build invalid configurations that fail downstream. + +The signal. Sales gets calls about failed orders. + +The cure. Constraint logic. Detail in `references/constraint-logic-patterns.md`. + +--- + +## The over-constrained configurator + +The pattern. Too many constraints; user feels boxed in. + +The signal. User abandons; sales gets calls for "custom" configurations. + +The cure. Reduce constraints to genuine requirements; offer custom path for edge cases. + +--- + +## The unclear-constraint configurator + +The pattern. Constraint engages without explanation. + +The signal. Users confused; bounce rate climbs. + +The cure. Constraint communication. Why constraint engaged; what user can do. + +--- + +## The lose-state-on-error configurator + +The pattern. Validation engages; configuration resets. + +The signal. Users abandon at first error. + +The cure. Preserve state; errors local. + +--- + +## The mobile-broken configurator + +The pattern. Configurator works on desktop; breaks on mobile. + +The signal. Mobile completion much lower than desktop. + +The cure. Mobile-first design. + +--- + +## The lost-on-cart configurator + +The pattern. Cart shows generic SKU; configuration not visible. + +The signal. Users edit; configurator restarts; abandonment. + +The cure. Cart presentation preserves configuration. + +--- + +## The price-drift configurator + +The pattern. Configurator shows one price; cart shows another. + +The signal. Users feel deceived. + +The cure. Single source of truth for pricing. + +--- + +## The save-mechanism-broken configurator + +The pattern. User saves; recovery link broken; configuration lost. + +The signal. Users complain; abandonment increases on long configurations. + +The cure. Test save mechanism end-to-end. + +--- + +## The validation-strict configurator + +The pattern. Validation rejects valid edge-case inputs. + +The signal. Users with valid inputs cannot proceed. + +The cure. Audit validation; allow international, plus-aliased, non-Latin inputs. + +--- + +## The unmaintained configurator + +The pattern. Product changed; configurator did not. + +The signal. Configurator references deprecated options; pricing wrong. + +The cure. Quarterly maintenance; product changes trigger configurator updates. + +--- + +## The aggressive-pricing-anchoring configurator + +The pattern. Strikethrough prices that were never charged; "$X for a limited time" perpetually. + +The signal. Sophisticated audiences notice; trust collapses. + +The cure. Honest anchoring; real discounts only. + +--- + +## The orphan-configuration configurator + +The pattern. Configurations save; user returns; configuration valid but pricing changed silently. + +The signal. Users surprised at price difference. + +The cure. Honest about price changes on resume. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review. + +Audit questions per configurator. + +- Is default sensible (anti-pattern check: blank-canvas)? +- Are constraints calibrated (anti-pattern check: over-constrained, under-constrained, unclear)? +- Is pricing visible and consistent (anti-pattern check: hidden-pricing, price-drift)? +- Does state preserve on error (anti-pattern check: lose-state-on-error)? +- Does mobile work (anti-pattern check: mobile-broken)? +- Does cart preserve configuration (anti-pattern check: lost-on-cart)? +- Is validation calibrated (anti-pattern check: validation-strict)? +- Is configurator current (anti-pattern check: unmaintained)? +- Are saved configurations honest about price changes (anti-pattern check: orphan-configuration)? + +The retire decision. Configurators failing multiple checks warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-decision-criteria.md b/skills/product-configurator-design/references/configurator-decision-criteria.md new file mode 100644 index 0000000..60185a6 --- /dev/null +++ b/skills/product-configurator-design/references/configurator-decision-criteria.md @@ -0,0 +1,129 @@ +# Configurator decision criteria + +When configurators earn the build vs when bundles serve. + +A configurator is meaningful work. Constraint logic, real-time pricing, validation, save-and-share, cart handoff, ongoing maintenance. The configurator earns this investment only when specific conditions are present. + +--- + +## When configurators earn the build + +Five conditions that, when present, make a configurator a strong investment. + +The product has genuinely customizable parameters that affect outcome and cost. Not just cosmetic options; real parameters that change what the user gets. + +The audience values customization beyond what bundles offer. Some audiences want choice; others prefer curated bundles. + +The team can support the configuration logic. Validation, pricing, fulfillment for variable configurations. + +The combinatorial space is meaningful but constrained. Not literally infinite; not so small that bundles would suffice. + +The success metric is defined. Configuration completion rate, configuration-to-purchase rate, average configuration price. + +When all five are present, a configurator is strong investment. When two or fewer are present, bundles often serve better. + +--- + +## When configurators do NOT earn the build + +Funnels where configurators add complexity without lift. + +The product is essentially bundles. Calling them configurations is marketing. + +The audience prefers curated options. Some audiences resent customization friction. + +The combinatorial space is too large. No audience can navigate. + +Customization produces invalid combinations. Team cannot prevent; users hit failures. + +A simpler tool would serve. Comparison, calculator, or selection tool. + +The honest assessment matters. Configurators are sometimes the wrong tool. + +--- + +## Configurators vs bundles + +When each fits. + +Bundles strengths. Simple; clear; no decision paralysis. Easy to maintain. + +Bundles weaknesses. Audiences that need customization underserved. + +Configurators strengths. Match real customer needs; capture revenue from edge cases. + +Configurators weaknesses. Build cost; complexity. + +The combined approach. Some products offer bundles AND a configurator for users who want custom. + +--- + +## The opportunity-cost frame + +Configurators are significant work. + +Build cost. Constraint logic, pricing engine, save-and-share, validation, cart integration. 60-200 engineering hours typical. + +Maintenance cost. Product changes trigger configurator updates. 4-12 hours per quarter. + +Opportunity cost. Better bundles, comparison tool, calculator. The configurator has to clear those alternatives. + +The decision frame. Configurators earn investment when they produce more revenue than bundle-only or alternative formats. + +--- + +## Decision worked example + +A B2B SaaS with seat-based + add-on pricing. + +Conditions check. + +- Genuinely customizable: yes (seats, add-ons, integrations). +- Audience values customization: yes; team size and add-ons vary. +- Team can support: yes. +- Combinatorial space: meaningful but constrained. +- Success metric: defined. + +Decision. Build the configurator. + +The decision was deliberate. + +--- + +## Decision worked example: when bundles serve + +A consumer SaaS with three plans. + +Conditions check. + +- Genuinely customizable: no; plans are bundles. +- Audience values customization: no; users pick plans. +- Combinatorial space: trivial. + +Decision. Bundles. No configurator needed. + +The decision was right-sized. + +--- + +## When to retire a configurator + +Configurators can become wrong over time. + +Retire when: + +- Conversion declined and refinements have not moved it. +- Most users default-and-purchase; customization unused. +- Product changed; configurator no longer matches. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions for configurators. The five against. Configurators vs bundles. Opportunity-cost frame. Decision worked examples. The retire decision. + +## Implementation choices that stay internal + +Specific configurator decisions for specific products. Capacity benchmarks. Tooling. These vary by team. diff --git a/skills/product-configurator-design/references/configurator-to-cart-handoff.md b/skills/product-configurator-design/references/configurator-to-cart-handoff.md new file mode 100644 index 0000000..36bbf43 --- /dev/null +++ b/skills/product-configurator-design/references/configurator-to-cart-handoff.md @@ -0,0 +1,159 @@ +# Configurator-to-cart handoff + +Handoff that preserves configuration; cart visibility; edit-from-cart. + +When the user commits, the handoff to cart determines whether the commitment sticks. Done well, handoff preserves the configuration; done poorly, the cart shows generic SKUs and the user feels their custom build was lost. + +--- + +## The preserve-the-build principle + +The configuration becomes the cart item. The cart shows the configuration. Editing returns to the configurator with state preserved. + +The win. User finishes configuration; clicks add to cart; cart shows the custom configuration with breakdown and price; user can edit, returning to configurator with all choices preserved. + +The fail. User finishes; clicks add to cart; cart shows "Custom Product - $X" with no detail. User cannot tell if their build is reflected. + +The discipline. Handoff loop closed. + +--- + +## Cart presentation + +How the configuration appears in cart. + +Configuration summary. Key choices listed (not all; not none). + +Price breakdown. Subtotal matches configurator's price. + +Edit link. Clear path back to configurator with state preserved. + +Visual. If configurator shows visual configuration, cart shows it too (or summary image). + +--- + +## Edit-from-cart + +When user wants to change. + +Pattern. Cart includes "Edit configuration" link. + +Behavior. + +- Click; return to configurator. +- All choices loaded. +- Adjust; commit; cart updates. + +The lose-state-on-edit failure. User clicks edit; configurator restarts; previous choices lost. + +The cure. State preserved through the handoff loop. + +--- + +## Multi-item handoff + +When the user configures multiple items. + +Pattern. Each configuration becomes a separate cart item with its own summary. + +Edit each independently. User can edit one without affecting others. + +--- + +## B2B configurator-to-quote + +When the configurator generates a quote rather than direct cart. + +Pattern. Configuration generates a quote; quote can be shared, approved, then converted to order. + +Strengths. B2B workflows often require approval. + +The discipline. Quote includes everything the configuration includes; conversion to order preserves. + +--- + +## Handoff to checkout + +After cart, checkout. + +The principle. Configuration details flow through checkout. Confirmation email reflects the configuration. + +The drop-config-at-checkout failure. Configuration disappears at checkout; user cannot verify. + +The cure. Configuration visible throughout the funnel. + +--- + +## Configuration ID + +The technical bridge. + +Pattern. Each configuration gets an ID. Cart, checkout, fulfillment all reference the ID. + +Strengths. Stable reference. + +Weaknesses. Requires backend infrastructure. + +--- + +## Pricing consistency + +Prices match across configurator, cart, checkout. + +The principle. No price drift between stages. + +The drift failure. Configurator shows $X; cart shows $Y; user feels deceived. + +Causes. Caching, currency conversion, tax estimation, discount expiration. + +The cure. Single source of truth for pricing; all stages query. + +--- + +## Save-and-share-to-cart + +When users return from saved configurations. + +Pattern. Saved configuration link opens configurator with state; user can add to cart from there. + +The discipline. Save mechanism integrates with cart workflow. + +--- + +## Mobile cart handoff + +On mobile, the handoff transition matters. + +Considerations. + +- Cart visible without horizontal scroll. +- Edit returns work on mobile. +- Configuration summary readable. + +--- + +## Common handoff failures + +Cart shows generic SKU. User cannot verify configuration. + +Edit restarts configurator. Previous choices lost. + +Pricing drifts between stages. User confused. + +Configuration disappears at checkout. Cannot verify. + +Multi-item handoff broken. Configurations conflict in cart. + +B2B quote misses details. Quote does not match configuration. + +Confirmation email lacks configuration. User cannot verify post-purchase. + +--- + +## Methodology-level choices that stay in the public skill + +The preserve-the-build principle. Cart presentation. Edit-from-cart. Multi-item handoff. B2B configurator-to-quote. Handoff to checkout. Configuration ID. Pricing consistency. Save-and-share-to-cart. Mobile considerations. Common failures. + +## Implementation choices that stay internal + +Specific cart implementations for specific configurators. Specific configuration-ID systems. Specific backend integrations. These vary by team. diff --git a/skills/product-configurator-design/references/constraint-logic-patterns.md b/skills/product-configurator-design/references/constraint-logic-patterns.md new file mode 100644 index 0000000..809e52b --- /dev/null +++ b/skills/product-configurator-design/references/constraint-logic-patterns.md @@ -0,0 +1,173 @@ +# Constraint logic patterns + +Hard, soft, implication, capacity constraints. Communication patterns. + +Constraints prevent invalid configurations. Done well, they protect users from errors and surface why; done poorly, they feel arbitrary or fail to prevent invalid configurations. + +--- + +## The protect-and-explain principle + +Constraints should prevent invalid configurations and explain why when they engage. + +The win. User selects Option A. System recognizes A is incompatible with currently-selected Option B. Inline message: "Option A and Option B are incompatible. Choose A or B." User adjusts; understands. + +The fail. User builds configuration. Submits. Backend rejects. User confused; no path forward. + +The discipline. Constraints engage at choice-time; explain why; offer paths. + +--- + +## Pattern A: Hard constraints + +Combinations that cannot exist. + +How it works. + +- Two options incompatible; configurator prevents both selected. +- User selects A; B becomes unavailable (greyed; with explanation). +- Or vice versa. + +Strengths. Prevents invalid configurations. + +Weaknesses. Can frustrate users who do not understand the constraint. + +When to use. Genuinely incompatible options. + +--- + +## Pattern B: Soft constraints + +Combinations that are unusual but possible. + +How it works. + +- User selects unusual combination. +- System warns: "This combination is unusual. Most teams choose [alternative]." +- User can proceed. + +Strengths. Respects user agency; provides guidance. + +Weaknesses. Some users will ignore warning; downstream issues. + +When to use. Combinations that work but are uncommon. + +--- + +## Pattern C: Implication constraints + +When choosing one option requires another. + +How it works. + +- User selects A. +- System auto-selects required B (or surfaces it for selection). +- Explains: "Selecting A requires B because [reason]." + +Strengths. Prevents missing-dependency errors. + +Weaknesses. Implication chains can grow complex. + +When to use. When dependencies are clear and predictable. + +--- + +## Pattern D: Capacity constraints + +Configuration exceeds product or fulfillment capacity. + +How it works. + +- User configures heavily; reaches capacity ceiling. +- System caps; explains: "Max [X] supported per configuration." +- Offers contact for custom. + +Strengths. Prevents impossible configurations. + +Weaknesses. Can frustrate enterprise audiences; offer contact for custom. + +When to use. Hard product limits. + +--- + +## Pattern E: Combinatorial constraints + +When multiple choices interact in complex ways. + +How it works. + +- Configurator evaluates the full configuration after each change. +- Constraints engage based on combinations, not individual options. +- Surface conflicts as they emerge. + +Strengths. Handles complex products. + +Weaknesses. Maintenance complexity. + +When to use. Products with genuine combinatorial constraints. + +--- + +## Constraint communication + +How constraints surface. + +Inline. Message next to the constrained choice. + +Modal. Full-screen explanation for major constraints. + +Toast. Brief notification for minor. + +The discipline. Match intensity to constraint importance. + +--- + +## Constraint copy + +What the message says. + +Strong copy. "Option A and Option B are incompatible because [specific reason]. Choose A or B." + +Weak copy. "Invalid configuration." + +The discipline. Specific; explanatory; offers paths. + +--- + +## Constraint maintenance + +Constraints decay. + +What decays. + +- Constraints from old product variants. +- Constraints inherited from deprecated options. +- New options not yet constrained. + +Maintenance cadence. Quarterly review with product changes. + +--- + +## Common constraint failures + +Over-constrained. Too many constraints; user feels boxed in. + +Under-constrained. User builds invalid configuration; fails downstream. + +Constraint without explanation. User confused by arbitrary blocking. + +Stale constraints. Inherited from old product. + +Constraint surface inappropriate. Modal for minor; toast for major. + +No path offered. Constraint blocks; user has no alternative. + +--- + +## Methodology-level choices that stay in the public skill + +The protect-and-explain principle. Patterns A through E. Constraint communication. Constraint copy. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific constraints for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/default-configuration-design.md b/skills/product-configurator-design/references/default-configuration-design.md new file mode 100644 index 0000000..aee99bf --- /dev/null +++ b/skills/product-configurator-design/references/default-configuration-design.md @@ -0,0 +1,109 @@ +# Default-configuration design + +The starting point. Default selection and presentation. + +The configurator opens with a default configuration. Done well, the default makes the user feel guided rather than overwhelmed; done poorly, the user faces a blank canvas and abandons. + +--- + +## The default-heavy principle + +Configurators should open with a sensible default, not a blank canvas. + +The win. User opens the configurator; sees a complete configuration with price; can adjust from there. + +The fail. User opens the configurator; sees empty fields and 0 fields completed. Decision paralysis. + +The discipline. Default-heavy; user adjusts from default; never builds from zero. + +--- + +## Default selection + +Which configuration is the default. + +Common-case default. The configuration most audiences would choose. Reflects audience research. + +Inferred default. Based on referrer, query, or stated preference. + +Audience-segment default. Different defaults for different segments (small vs enterprise). + +The most-popular default. Use what most users actually pick. + +--- + +## Default presentation + +How the default appears. + +Visible immediately. User sees a complete configuration with price. + +Adjust controls obvious. User knows what is changeable. + +Reset-to-default available. Users who experiment can return to default. + +Summary-and-detail. Default shown as summary with expandable detail. + +--- + +## The blank-canvas trap + +When configurators open empty. + +The pattern. Empty fields; user must build from scratch. + +The signal. High first-step abandonment. + +The cost. Users abandon before reaching ah-ha moment of seeing a configuration. + +The cure. Default-heavy. Open with a complete configuration. + +--- + +## Default updating + +Defaults decay. + +What decays. + +- Most-popular configuration shifts. +- Audience composition changes. +- Product changes invalidate defaults. + +Maintenance cadence. Quarterly review. + +--- + +## Default-by-segment + +Different audiences may warrant different defaults. + +Pattern. Detect or ask about audience; default adapts. + +Detection. Referrer, query, stated input, or inferred from context. + +The discipline. Audience-fit defaults serve better than one-size-fits-all. + +--- + +## Common default failures + +Blank canvas. No default; user paralyzes. + +Wrong default. Most users adjust away; default does not match audience. + +Stale default. Reflects old product or pricing. + +Default obscures customization. User does not realize options exist. + +Default biased toward expensive. Default flatters revenue, not user fit. + +--- + +## Methodology-level choices that stay in the public skill + +The default-heavy principle. Default selection. Default presentation. The blank-canvas trap. Default updating. Default-by-segment. Common failures. + +## Implementation choices that stay internal + +Specific defaults for specific configurators. Specific detection logic. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/real-time-pricing-patterns.md b/skills/product-configurator-design/references/real-time-pricing-patterns.md new file mode 100644 index 0000000..b562309 --- /dev/null +++ b/skills/product-configurator-design/references/real-time-pricing-patterns.md @@ -0,0 +1,157 @@ +# Real-time pricing patterns + +Price updates with choices. Breakdown and impact display. + +Pricing that responds to choices. Done well, users see cost impact immediately; done poorly, price-shock at checkout drives abandonment. + +--- + +## The no-surprises principle + +Price visible throughout the configuration. No surprises at checkout. + +The win. Total price visible at top of configurator. Updates as user adjusts. Per-choice impact visible ("Adds $X"). Breakdown available. + +The fail. Price hidden until checkout. User configures heavily. Sees price; abandons. + +The discipline. Price visible; breakdown available; surprises eliminated. + +--- + +## Total price display + +How the total appears. + +Prominent placement. Top or top-right of configurator. + +Real-time updates. Updates immediately as user changes choices. + +Currency and locale. Match the user's locale. + +Period. Per-month, per-year, one-time. Match the product's pricing model. + +--- + +## Per-choice impact + +Showing what each option costs. + +Inline impact. "+$X/month" next to the option. + +Strikethrough for upgrades. Old price strikethrough; new price highlighted. + +Free options labeled. "Free" or "Included" explicit. + +The discipline. User can see the cost of each choice without computing. + +--- + +## Pricing breakdown + +How the total breaks down. + +Expandable breakdown. "How is this priced" toggle reveals detail. + +Categorized breakdown. Base + add-ons + fees. + +Subscription vs one-time. Recurring vs one-time costs distinguished. + +The discipline. Breakdown available on demand; not forced. + +--- + +## Annual vs monthly + +Subscription periods. + +Toggle visible. User can switch between annual and monthly. + +Discount disclosed. "Save X% with annual billing." + +Both totals shown. Annual total and monthly equivalent. + +--- + +## Hidden cost surfacing + +Costs that often hide. + +Setup fees. Disclosed at configuration; not at checkout. + +Implementation costs. If applicable, visible. + +Per-user vs flat. Mode disclosed. + +Overage pricing. What happens beyond capacity, disclosed. + +The hidden-cost trap. Costs surfaced only at checkout; user feels deceived. + +--- + +## Tax and shipping + +Where applicable. + +Tax estimate. Approximate tax visible if jurisdiction can be inferred. + +Shipping estimate. Approximate shipping visible if applicable. + +Final calculation at checkout. Estimate at configurator; final at checkout. + +The discipline. Estimates clearly labeled; final disclosed. + +--- + +## Price comparison anchoring + +Showing alternative configurations. + +Comparison anchoring. "If you upgrade to X, the price increases to Y." + +Bundle anchoring. "Equivalent bundle is Z." + +Use carefully. Anchoring can manipulate; honesty matters. + +--- + +## Pricing maintenance + +Pricing decays. + +What decays. + +- Pricing levels from old pricing models. +- Currency conversions stale. +- Discount terms expired. + +Maintenance cadence. When pricing changes, configurator pricing updates as part of the change. + +--- + +## Common pricing failures + +Hidden pricing. Total not visible until checkout. + +Per-choice impact hidden. User does not know what each choice costs. + +Surprise fees. Setup, implementation costs hidden until checkout. + +Stale pricing. Reflects old prices. + +Tax surprise. Tax not estimated; user surprised at checkout. + +Currency wrong. Local user sees wrong currency. + +No annual-vs-monthly toggle. User locked into one period. + +False discount anchoring. Strikethrough prices that were never charged. + +--- + +## Methodology-level choices that stay in the public skill + +The no-surprises principle. Total price display. Per-choice impact. Pricing breakdown. Annual vs monthly. Hidden cost surfacing. Tax and shipping. Price comparison anchoring. Pricing maintenance. Common failures. + +## Implementation choices that stay internal + +Specific pricing displays for specific configurators. Specific currency and tax logic. Specific tooling. These vary by team. diff --git a/skills/product-configurator-design/references/save-and-share-mechanics.md b/skills/product-configurator-design/references/save-and-share-mechanics.md new file mode 100644 index 0000000..5ca6010 --- /dev/null +++ b/skills/product-configurator-design/references/save-and-share-mechanics.md @@ -0,0 +1,218 @@ +# Save-and-share mechanics + +Email-link, account, anonymous, shareable URL, embed. + +Configurations users return to or send to others. Multi-decision purchases require deliberation; B2B configurations often need stakeholder review. Save-and-share supports these workflows. + +--- + +## The deliberation-friendly principle + +Configurators that serve real decision-making produce configurations users want to save and share. + +The win. User configures complex purchase. Saves via email-link. Shares with stakeholders. Returns days later. Configuration intact; price unchanged; ready to buy. + +The fail. User configures; cannot save; loses work between sessions; abandons. + +The discipline. Save mechanisms support multi-session and multi-stakeholder workflows. + +--- + +## Pattern A: Email-link save + +User enters email; link emailed. + +How it works. + +- "Save and resume later" CTA. +- User enters email. +- Link emailed; user clicks to return. + +Strengths. No account required; cross-device. + +Weaknesses. Email deliverability; link expiration. + +When to use. Default for non-authenticated configurators. + +--- + +## Pattern B: Account-based save + +Logged-in users save automatically. + +How it works. + +- User logs in. +- Configurations save to account. +- User returns; finds saved configurations. + +Strengths. Multi-configuration management. + +Weaknesses. Account creation friction. + +When to use. When configurator is part of a logged-in product. + +--- + +## Pattern C: Anonymous-session save + +Browser-based persistence. + +How it works. + +- Configuration saved to browser local storage. +- User returns same browser; configuration restored. + +Strengths. Lowest friction. + +Weaknesses. Lost on browser change; limited persistence. + +When to use. As supplement to other patterns. + +--- + +## Pattern D: Shareable URL + +Configuration encoded in URL. + +How it works. + +- Configurator encodes the configuration in URL parameters. +- User shares URL; recipient opens; sees same configuration. + +Strengths. Easy sharing across channels. + +Weaknesses. URL length; pricing may shift over time. + +When to use. Shareable configurations; B2B stakeholder review. + +--- + +## Pattern E: Embed code + +Configuration embeddable on other sites. + +How it works. + +- Configurator generates embed code. +- User pastes into other sites or proposals. + +Strengths. Used in B2B proposals. + +Weaknesses. Cross-site complexity. + +When to use. B2B sales contexts. + +--- + +## Pattern F: Hybrid + +Combining patterns. Common for production configurators. + +Common combination. Email-link save + shareable URL + anonymous-session backup. + +Strengths. Multiple paths. + +Weaknesses. Complexity. + +--- + +## Save trust communication + +Users hesitate to save partial sensitive configurations. + +What to communicate. + +- What is saved. +- How long it persists. +- Who can access it. +- How to delete. + +The discipline. Trust communication explicit; not buried in privacy policy. + +--- + +## Resume experience + +When user returns. + +The principle. Resume should be uninterrupted. + +The pattern. + +- User clicks recovery link or logs in. +- Lands at the configuration; rest preserved. +- Continues without re-doing. + +Resume failures. + +- Configuration partially preserved; values lost. +- Pricing changed; user surprised. +- Constraint logic shifted; configuration now invalid. + +The discipline. Resume preserves; communicate any changes (e.g., "Pricing has updated since you last visited"). + +--- + +## Pricing on resume + +When prices change between save and resume. + +Honest pattern. Show the saved configuration with original price; surface "Pricing has changed; updated price is X" with explanation. + +Dishonest pattern. Silently update price; user does not notice. + +The discipline. Honesty about price changes. + +--- + +## Sharing privacy + +Shared configurations may include sensitive info. + +Considerations. + +- What is in the URL/embed. +- Who can see it. +- How long links are valid. + +The discipline. Sharing respects user privacy; sensitive details may need account-based sharing rather than URL. + +--- + +## Save-and-share analytics + +Track usage. + +Metrics. + +- Save rate. +- Resume rate per saved configuration. +- Share rate. +- Configurations completed via save-and-share path. + +--- + +## Common save-and-share failures + +No save mechanism. Users lose work; abandon. + +Save mechanism brittle. Links expire; account access broken. + +Resume loses state. User lands at start; loses work. + +Pricing surprise on resume. Silent price update. + +Sharing exposes sensitive info. Embedded URLs share more than intended. + +Save trust missing. Users do not save because they distrust persistence. + +--- + +## Methodology-level choices that stay in the public skill + +The deliberation-friendly principle. Patterns A through F. Save trust communication. Resume experience. Pricing on resume. Sharing privacy. Analytics. Common failures. + +## Implementation choices that stay internal + +Specific save mechanisms for specific configurators. Specific tooling for URL encoding and embed generation. Privacy review processes. These vary by team. diff --git a/skills/product-configurator-design/references/validation-and-error-patterns.md b/skills/product-configurator-design/references/validation-and-error-patterns.md new file mode 100644 index 0000000..7375621 --- /dev/null +++ b/skills/product-configurator-design/references/validation-and-error-patterns.md @@ -0,0 +1,191 @@ +# Validation and error patterns + +Helpful validation. Inline, pre-emptive, final. + +Validation catches invalid input. Done well, validation is helpful and inline; done poorly, validation is punitive or arrives only at submission. + +--- + +## The catch-helpful principle + +Validation should catch errors at the point where helping the user is most efficient. + +The win. User selects an option that requires another. Inline validation surfaces immediately; explains; auto-corrects or guides. + +The fail. User configures complete configuration. Submits. Validation runs at backend. User sees error; loses momentum. + +The discipline. Validation timing matters; specific, helpful messages matter; preserve user inputs on error. + +--- + +## Pattern A: Inline validation + +Validation runs as the user makes choices. + +How it works. + +- User selects an option. +- System validates against the rest of the configuration. +- If invalid, message appears next to the choice. + +Strengths. Errors caught at point of input. + +Weaknesses. Real-time validation can lag; intrusive if too aggressive. + +When to use. Default for most configurators. + +--- + +## Pattern B: Pre-emptive validation + +Constraints prevent invalid choices from being selectable. + +How it works. + +- Options that would create conflicts are disabled with explanation. +- User cannot select the invalid option. + +Strengths. Errors prevented; user does not encounter them. + +Weaknesses. Some users want to see the option even if disabled. + +When to use. When the constraint is hard and explanation is clear. + +--- + +## Pattern C: Final validation + +Validation runs at submission. + +How it works. + +- User completes configuration. +- Submit; system runs full validation. +- Errors surfaced at this stage. + +Strengths. Catches errors that span multiple fields. + +Weaknesses. Late; user invested in completing. + +When to use. As supplement to inline validation; not primary. + +--- + +## Pattern D: Hybrid + +Combining patterns. + +Common combination. Pre-emptive for hard constraints; inline for soft validation; final as backup. + +Strengths. Multiple safety nets. + +Weaknesses. Complexity. + +When to use. Production configurators with multiple constraint types. + +--- + +## Validation message discipline + +What the message says. + +Strong messages. + +- Specific to the issue. +- Explains why. +- Offers a path (alternative option, contact for custom). + +Examples. + +- "Option A requires Option B; we have selected B for you." +- "Option C is incompatible with Option D. Choose one or contact us for custom." +- "Quantity exceeds 1000; for larger quantities contact our team." + +Weak messages. + +- "Invalid configuration." +- "Error." +- "Please correct the issues." + +The discipline. Specific, helpful, offers paths. + +--- + +## Validation strictness + +How aggressively to validate. + +Too strict. Rejects valid inputs at edge cases. Frustrates users. + +Too loose. Accepts invalid inputs that fail downstream. + +The right strictness. Validation matches actual product constraints. + +--- + +## Preserve inputs on error + +What happens when validation engages. + +The principle. Errors should not lose user inputs. + +The pattern. Error appears; rest of configuration preserved; user adjusts the specific issue. + +The reset-on-error failure. Form resets entirely on error. User loses all work; abandons. + +The cure. Errors are local; configuration state preserved. + +--- + +## Mobile validation + +Validation on mobile. + +Mobile considerations. + +- Inline messages must fit mobile screens. +- Auto-correct should work with touch. +- Error states must be visible without zoom. + +The mobile discipline. Test validation on actual devices. + +--- + +## Validation testing + +Test validation across cases. + +Test cases. + +- Valid configurations: pass through. +- Invalid configurations (each constraint type): caught with helpful message. +- Edge cases (boundary values, unusual combinations): handled. +- Mobile: works on touch. + +--- + +## Common validation failures + +Late validation. Errors caught only at submission. + +Generic error messages. No guidance. + +Strict validation rejects valid inputs. Edge cases lost. + +Loose validation accepts invalid. Fails downstream. + +Reset-on-error. User loses work. + +Validation interrupts typing. Real-time validation too eager. + +Mobile-broken validation. Errors invisible or off-screen. + +--- + +## Methodology-level choices that stay in the public skill + +The catch-helpful principle. Patterns A through D. Validation message discipline. Validation strictness. Preserve inputs on error. Mobile validation. Validation testing. Common failures. + +## Implementation choices that stay internal + +Specific validation rules for specific configurators. Specific copy. Specific tooling. These vary by team. diff --git a/skills/programmatic-seo/SKILL.md b/skills/programmatic-seo/SKILL.md new file mode 100644 index 0000000..124d85f --- /dev/null +++ b/skills/programmatic-seo/SKILL.md @@ -0,0 +1,279 @@ +--- +name: programmatic-seo +description: "How to design and run a programmatic SEO program that produces durable traffic instead of penalty-bait. Data source identification, template design, schema patterns, quality control at scale, internal linking architecture, crawl budget management, AEO/GEO for programmatic pages, refresh discipline, and the make-or-break question of whether pSEO is the right answer for your program at all. Triggers on programmatic SEO, pSEO, scaled content, page generation, template SEO, location pages, comparison pages, directory site, listing site, scaled landing pages, programmatic content. Also triggers when a content set is not ranking, has been hit by an algorithm update, or when a team is considering pSEO as a growth lever." +category: content +catalog_summary: "Designing pSEO programs that work: data sources, template design, quality control at scale, internal linking, crawl budget, AEO/GEO patterns, refresh discipline, and when pSEO is and is not the right answer" +display_order: 6 +--- + +# Programmatic SEO + +A senior SEO strategist's playbook for designing and running programmatic SEO programs that produce durable traffic instead of penalty-bait. + +Programmatic SEO has a complicated reputation. Sites like Zillow, Airbnb, TripAdvisor, Indeed, and Yelp have built billion-dollar traffic engines on pSEO. Other sites have built pSEO programs that got hit by Google's helpful-content updates and lost 80% of their traffic in a week. The difference is rarely the technique; it is the underlying data quality and the quality control discipline at scale. + +This skill is the playbook for getting that distinction right. It assumes you have decided what keyword space to target (see `seo-keyword`) and how the broader content program is shaped (see `content-strategy`). It does not write individual editorial pieces (see `content-and-copy` for that) and does not architect editorial topic hubs (see `pillar-content-architecture` for that). What it does is teach the discipline of generating high-volume pages programmatically from structured data sources without producing thin content, duplicate content, or scale-without-substance pages that get penalized. + +When to use this skill: deciding whether pSEO is a fit for the program at all (the most important question), designing a new pSEO system, auditing an existing pSEO set that is not ranking or has been hit by an algorithm update, or building quality-control discipline for a pSEO program that grew faster than its quality processes. + +--- + +## What this skill is for + +This skill spans scaled-content programs from data source through quality control. It composes with five sister and adjacent skills, and the distinction between them is what keeps each one sharp. + +- `content-strategy` is program-scope: editorial pillars, calendar, governance. Decides whether pSEO fits the program at all. +- `pillar-content-architecture` is hub-scope: one topic with 10 to 15 intentional editorial pieces. Editorial in nature. +- `content-brief-authoring` is per-piece scope: brief for one editorial artifact. +- `content-and-copy` is execution scope: writing individual editorial pieces. +- This skill is scaled scope: 100s to 100,000s of pages generated programmatically from structured data sources, each targeting a long-tail query. + +The clean reading order: `content-strategy` decides whether pSEO is a fit, `seo-keyword` surfaces the long-tail keyword space, this skill designs the pSEO system, `editorial-qa` (forthcoming) provides the QA discipline for sampled quality control across the set. `content-and-copy` and `content-brief-authoring` are not in the loop for pSEO at scale; those skills are for editorial pieces, not data-driven generated pages. + +The audience: SEO content strategists, content engineers, agencies running pSEO programs, in-house teams considering pSEO as a growth lever. The voice is senior SEO strategist to junior PM or marketer. Specific, opinionated, honest. The reputation problem is not pSEO; it is pSEO without underlying value. + +--- + +## When pSEO is the right answer + +The keystone question. pSEO works when all of the following are true. + +1. Real underlying data. A genuine structured data source with depth: 10+ fields per record, ideally 20+, with first-party data, expert-curated data, or licensed datasets. Not just scraped data or AI-generated facts dressed as structured records. + +2. Long-tail query volume justifies the effort. The queries the program would target have meaningful aggregate volume even if individual queries are small. Real estate "homes for sale in {neighborhood}" works at scale. "Blue widget reviews 2026" generated for every adjective times widget combination does not, because the queries are not actually searched. + +3. User intent is queryable. The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +4. Update cadence aligns with query volatility. Real estate listings update daily and the data refresh aligns. "Best [thing] for [year]" pages get stale annually and need a refresh discipline budgeted in. + +5. Quality control is operationally feasible. The team has the capacity to sample-audit the set, fix failures, and maintain quality as the set grows. Not aspirationally; budgeted in headcount. + +pSEO does NOT work when: + +- The underlying data is shallow (3 to 5 fields, mostly AI-generated, no first-party signal) +- The query volume is illusory (long-tail keywords nobody actually searches) +- User intent requires narrative or judgment that data cannot supply +- Quality control is not budgeted (write a bunch of pages, ignore them) +- The program is scaling AI-generated thin pages without unique data + +The honest framing. Most teams that ask "should we do pSEO?" should hear "probably not, unless the underlying data is unique or first-party expertise makes the pages actually useful." The reputation problem is not the technique; it is the technique applied without underlying value. + +Detail in [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md). + +--- + +## Data source identification + +The data source is the pSEO program. Common sources with different defensibility profiles. + +First-party data. Customer transactions, content database, user-generated content. Defensible because nobody else has it. Examples: Glassdoor's employee reviews, Yelp's user ratings, TripAdvisor's traveler reviews. + +Licensed datasets. Industry databases, regulatory data, government datasets, licensed third-party feeds. Defensible by license terms and integration depth. Examples: Zillow's MLS partnerships, real estate brokerage feeds, sports statistics licenses. + +Aggregated public data. Scraped, cleaned, enriched. Judgment call on legality (often gray area depending on robots.txt, terms of service, jurisdictional rules). Defensibility depends on the cleaning and enrichment work. Easy to copy if the cleaning is shallow. + +Expert-curated content. The dataset is built by hiring experts to populate it. Slow, high-quality, defensible. Examples: Wirecutter's product testing, expert-reviewed medical content, curated editorial databases. + +Synthesized data. Combining multiple sources into a unique view. "Neighborhoods times schools times prices" combining three datasets into a comparison view. Defensibility comes from the synthesis logic and the ongoing maintenance of multi-source pipelines. + +The "moat" question. Would a competitor be able to replicate the data source? If yes, the pSEO program has no defensibility; anyone can copy. If no, the data source becomes a moat that compounds. Zillow's MLS partnerships, Glassdoor's employee reviews, Crunchbase's funding data, are moats. "Scraped Wikipedia plus AI rewrite" is not. + +Detail in [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md). + +--- + +## Template design + +The template is the structure that data fills. Design principles. + +Above-the-fold answer. The user's specific question answered in the first 200 words of the rendered page, structured for both human reading and AI extraction. The answer is what gets cited; the rest is supporting depth. + +Variable density. The template accommodates records with sparse fields (some have 5 data points, others have 50) without looking broken. Sparse pages need fallback patterns; dense pages need progressive disclosure to avoid overwhelming. + +Heading hierarchy that reflects data. H2s and H3s map to data sections (overview, details, comparisons, related). The heading structure is not decorative; it tells crawlers and AI engines what the page covers. + +Schema markup as part of template. Structured data (JSON-LD, microdata, or RDFa depending on the stack) embedded in the template renders machine-readable signals at scale across the entire set. Without schema, the set is invisible to the structured-data extraction layer search and answer engines run. + +Internal linking placeholders. The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. 5 to 15 internal links per page is typical for a well-linked set. + +Distinctive value per page. Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. If the page is just a re-pivot of the parent's data, the page is filler. + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. If a randomly sampled page is thin, the entire set is thin. + +Detail in [`references/template-design-patterns.md`](references/template-design-patterns.md). + +--- + +## Schema design + +The data shape that drives the template. Design principles. + +Field count signals depth. 5 fields per record is thin. 15 to 20 is competent. 30+ is deep. The field count is not a vanity metric; it determines what the template can render at depth versus what falls back to filler. + +Required vs optional fields. Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. A page with 3 of 30 optional fields populated should not ship; a page with 25 of 30 should. + +Computed fields. Derived from source data. Average price per square foot computed from listings adds depth without requiring more source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +Cross-record fields. Fields that reference other records in the set enable internal linking and comparison. The "5 most similar neighborhoods" field on every neighborhood page powers the sibling-link section without manual curation. + +Update frequency tags. Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). Without tagging, refresh becomes "audit everything" instead of "refresh the volatile fields." + +The "schema-as-product" principle. The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. Versioned, reviewed, documented, breaking-change-aware. + +Detail in [`references/schema-design-patterns.md`](references/schema-design-patterns.md). + +--- + +## Quality control at scale + +Auditing all 100,000 pages individually is infeasible. The discipline. + +Sampling strategy. Random sample 50 to 200 pages per audit cycle, balanced across data shape (sparse, dense, recent, old, popular categories, niche categories). The sample is not "the latest 50 pages"; it is a stratified sample that exposes problems specific to particular data shapes. + +Automated checks. Heading structure, schema validity, internal link count, word count thresholds, duplicate-content checks, broken-link checks. Run on every page on a cadence; surface failures as a queue. + +Manual review checklist. For sampled pages, check the top-200-word answer quality, check whether the page would satisfy the user's query, check whether the page reads as distinctive versus templated. The manual review is the layer automated checks miss. + +Failure thresholds. If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. The threshold is not negotiable; without it, quality drift compounds invisibly until the algorithm update reveals it. + +Cohort tracking. Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. Cohort tracking is the pSEO equivalent of the experimentation team's drift detection. + +The team budget question. A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. If that is not budgeted, the program will decay. The set will look fine on launch and degrade over 6 to 12 months as data drifts, templates ship without QC, and the gap between the QC plan and the actual cadence widens. + +Detail in [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md). + +--- + +## Internal linking across the set + +pSEO sets need intentional internal linking architecture to compound. + +Hub pages. Parent-level pages (e.g., "homes for sale in Denver") that link to all child pages (specific neighborhoods). Hub pages are linked from main navigation; they are the entry point for the set's traffic. + +Sibling linking. Each page links to 5 to 15 related sibling pages: similar neighborhoods, similar price ranges, similar features. Sibling links are computed from cross-record fields in the schema; they are not manual curation at scale. + +Reverse-direction linking. Child pages link up to hub; sibling links go both directions. The graph is bidirectional; PageRank flows both ways. + +Anchor text variation. Avoid every page using the same anchor text. Vary by record characteristic (the record name, a descriptive phrase, the parent category). Uniform anchor text at scale signals manipulation to ranking systems. + +Crawl-friendly architecture. Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +The PageRank flow principle. Internal linking is what makes pSEO sets compound. A well-linked set distributes ranking signal across all pages; a poorly-linked set has hub pages ranking and child pages orphaned. The link architecture is half the program; the data is the other half. + +Detail in [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md). + +--- + +## Crawl budget management + +Search engines have crawl budgets. Large pSEO sets can exhaust them. + +Sitemap segmentation. Split sitemaps by category or recency so crawlers prioritize active pages. A single sitemap with 100,000 entries is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each, organized by category or last-update. + +Noindex on thin pages. Pages with insufficient data should noindex rather than ship as bait. The discipline: pages that fail the schema's required-field threshold do not get a public URL; they sit in the system as drafts until their data populates. + +Canonical handling. Comparison pages (X vs Y) often have inverse pages (Y vs X). Canonicalize to one. Comparison-pivot duplicates without canonicalization split ranking signal. + +Crawl rate signals. Monitor Google Search Console crawl stats. If crawl rate is plateauing while page count grows, the set is hitting budget limits. The fix is not "publish more pages"; it is "noindex thin pages and improve internal linking so crawlers prioritize better." + +Pruning criteria. Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. Pruning is hygiene, not failure. A 100,000-page set with 60% earning traffic is healthier than the same set with 40% earning traffic plus 60% dead weight crawlers waste budget on. + +Detail in [`references/crawl-budget-management.md`](references/crawl-budget-management.md). + +--- + +## AEO and GEO for programmatic pages + +Answer engines treat programmatic pages differently from editorial pages. + +Direct-answer extraction. AI engines extract the top-200-word answer; templates that lead with the answer get cited. The opening of the page is the citation candidate; everything after it is supporting depth. + +Structured data signals. JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. Programmatic pages with minimal schema lose to programmatic pages with deep schema even when the underlying data is similar. + +Citation patterns. AI engines tend to cite programmatic data pages for factual queries (prices, statistics, comparisons, factual details) and editorial pages for analytical queries (why, how, what should I think). Design templates to fit the factual-query lane; do not try to make programmatic pages compete for analytical queries that editorial content owns. + +Quality crackdown sensitivity. AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. The pSEO penalty risk has migrated to AI surfaces; the same quality-at-scale discipline applies, with less tolerance. + +The "two-engine optimization" framing applies. pSEO pages should serve both search engines and answer engines. Most pSEO programs were designed pre-AEO and need template updates for the new surface: stronger top-200-word answers, deeper schema markup, FAQPage schema where the page contains FAQ structure. + +Detail in [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md). + +--- + +## Refresh and maintenance at scale + +pSEO sets decay if not maintained. + +Data refresh cadence. Quarterly minimum for most datasets. Daily or weekly for time-sensitive data (real estate listings, prices, availability, current statistics). The refresh cadence is set when the program launches; retrofitting is expensive. + +Template version migration. When the template improves, all existing pages need migration. Cohort-by-cohort migration with monitoring beats big-bang migration. Each cohort gets the new template, sits for 30 days under monitoring, then the next cohort migrates. + +Pruning lifecycle. Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. The 24-month checkpoint is the standard cutoff; some categories warrant earlier or later pruning. + +Set-level refresh. Occasionally the entire set's template needs a refresh as user expectations evolve, AI engine signals shift, or category conventions change. Set-level refreshes are 6-month projects, not weekend cleanups. + +Detail in [`references/refresh-at-scale.md`](references/refresh-at-scale.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-pseo-failures.md`](references/common-pseo-failures.md). + +- "We generated 50,000 pages and got penalized." Thin content, scaled too fast, no QC discipline. +- "We have 10,000 pages but only 200 rank." Internal linking architecture missing; child pages are orphans. +- "Crawl rate plateaued." Crawl budget exhausted; noindex thin pages and improve sitemap segmentation. +- "Pages look identical." Template lacks variable density; data is too sparse to differentiate. +- "We cannot update the templates without 10,000 manual fixes." Template versioning was not designed for scale. +- "Our quality control is whoever has time." No sampling discipline, no thresholds, no ownership. +- "AI engines do not cite our pages." Top-200-word answer was not designed; structured data is thin. +- "We are at 100,000 pages and engagement is dropping." The set has outgrown its data depth. +- "Competitors copied our pages." The data source was not a moat. +- "Refresh is overwhelming." Cadence was not designed for scale; templates are not migration-friendly. +- "Our pSEO drives traffic but no conversions." Query intent does not match buyer intent; reconsider whether pSEO was the right channel for the program goal. + +--- + +## The framework: 12 considerations for programmatic SEO + +When designing or auditing a programmatic SEO program, walk these 12 considerations. + +1. Right answer for the program. pSEO needs real underlying data, queryable intent, and quality-control budget. Default to no if any is missing. +2. Data source as moat. Replicable data is not defensible; first-party, licensed, expert-curated, or synthesized data is. +3. Schema depth. 15+ fields per record minimum; 30+ for competitive depth. +4. Template variable density. Accommodates sparse and dense records gracefully. +5. Above-the-fold answer. First 200 words answer the user's specific query. +6. Schema markup at scale. Structured data on every page; this is the AEO/GEO signal. +7. Internal linking architecture. Hub-and-spoke plus sibling linking, no orphans. +8. Quality control sampling. 50 to 200 pages per audit, balanced across data shape. +9. Failure thresholds. 5% sample failure halts generation until template or data fixes ship. +10. Crawl budget discipline. Sitemap segmentation, noindex on thin pages, canonicalization on duplicates. +11. Refresh cadence. Quarterly minimum data refresh; cohort-by-cohort template migration. +12. Pruning lifecycle. Pages that fail to earn traffic in 12 to 24 months get noindexed or removed. + +The output of the framework is a pSEO design document the team can reference at every stage: data source named, schema versioned, template specified, QC discipline budgeted, internal linking architecture mapped, refresh cadence set. + +--- + +## Reference files + +- [`references/when-pseo-works-decision.md`](references/when-pseo-works-decision.md) - Five-criterion decision framework with worked examples of yes, no, and maybe. +- [`references/data-source-identification-patterns.md`](references/data-source-identification-patterns.md) - First-party, licensed, public, expert-curated, synthesized; defensibility analysis. +- [`references/template-design-patterns.md`](references/template-design-patterns.md) - Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. +- [`references/schema-design-patterns.md`](references/schema-design-patterns.md) - Field count, computed fields, cross-record fields, update tags, schema-as-product. +- [`references/quality-control-at-scale.md`](references/quality-control-at-scale.md) - Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. +- [`references/internal-linking-at-scale.md`](references/internal-linking-at-scale.md) - Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. +- [`references/crawl-budget-management.md`](references/crawl-budget-management.md) - Sitemap segmentation, noindex patterns, canonicalization, crawl rate monitoring, pruning criteria. +- [`references/aeo-geo-for-programmatic-pages.md`](references/aeo-geo-for-programmatic-pages.md) - Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. +- [`references/refresh-at-scale.md`](references/refresh-at-scale.md) - Data refresh cadence, template versioning, cohort migration, pruning lifecycle. +- [`references/common-pseo-failures.md`](references/common-pseo-failures.md) - Eleven-plus failure patterns with diagnoses and fixes. + +--- + +## Closing: quality at scale or not at all + +The only durable pSEO programs are the ones that hold quality at scale. The temptation to scale quantity at the cost of quality has produced the entire bad reputation pSEO carries. Sites that resist that temptation, that maintain real data depth, real quality control, real refresh discipline, keep producing meaningful traffic for years. Sites that do not get penalized within months of an algorithm update. + +The discipline is not optional and it is not free. Budget for it before generating the first page, or do not start at all. + +When in doubt about whether a pSEO program is ready, ask: is the data source actually unique, is the schema deep, does the template lead with the answer, is the internal linking architecture mapped, is QC budgeted in headcount, is the refresh cadence set? If yes to all of those, ship the design document and let the engineering work begin. If no to any of them, fix the gap before any pages generate. diff --git a/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md b/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md new file mode 100644 index 0000000..2300287 --- /dev/null +++ b/skills/programmatic-seo/references/aeo-geo-for-programmatic-pages.md @@ -0,0 +1,106 @@ +# AEO and GEO for programmatic pages + +Direct-answer extraction, structured data signals, citation patterns, two-engine optimization. + +Answer engines treat programmatic pages differently from editorial pages. The differences shape how pSEO templates should be designed for the AI search era. + +--- + +## Direct-answer extraction + +AI engines extract the top-200-word answer; templates that lead with the answer get cited. + +The pattern. The opening of the page is the citation candidate. AI engines pull from the first answer-shaped paragraph, FAQPage schema entries, and structured-data fields. Everything after the opening is supporting depth that justifies the citation but is rarely cited directly. + +Template implication. The first 200 rendered words must answer the user's specific query in a self-contained way. A page about "homes for sale in Denver under $500k" should answer that exact query in the opening: count of listings, average price, top neighborhoods, with structured data backing each claim. + +Anti-pattern. Welcome paragraphs, navigation hints, "below you will find" filler. These dilute the citation candidate and reduce the page's AI-engine pull. + +Snippet-bait paragraphs at H2 level. Beyond the top-200-word answer, each H2 should have a 40 to 60 word snippet-bait paragraph. AI engines often quote multiple snippet-bait paragraphs as multi-paragraph citations. + +--- + +## Structured data signals + +JSON-LD with comprehensive schema is read by AI engines as authority signal at scale. + +The "thin schema" penalty. Programmatic pages with minimal schema (just the basic Article or Product type, with required fields only) lose to programmatic pages with deep schema (complete schema graph, optional fields populated, cross-entity references). The underlying data may be similar; the schema markup is what AI engines see. + +Schema patterns that signal quality at scale. + +- Type-appropriate schema. Product for product pages, LocalBusiness for location pages, Article for editorial pages, FAQPage for FAQ sections, BreadcrumbList for navigation context. +- Cross-entity references. Schema entries that reference other entities in the dataset (relatedProduct, parentOrganization, hasPart) signal a connected knowledge graph rather than isolated pages. +- Aggregate schema. Reviews, ratings, statistics presented as structured aggregateRating, aggregateOffer, aggregateProperty fields. +- FAQPage schema on FAQ sections. AI engines (Perplexity especially) cite FAQPage-marked content heavily; programmatic pages that include FAQ sections should mark them. + +Schema validation. Run schema validation on every page; failures produce silent invisibility in AI surfaces. The validation is automated and gates publish. + +--- + +## Citation patterns + +AI engines cite programmatic data pages and editorial pages for different query types. + +Factual-query lane. AI engines tend to cite programmatic data pages for factual queries: prices, statistics, comparisons, factual details, specifications, locations, ratings. The page renders the fact as structured data; the AI engine cites the structured data as the answer. + +Analytical-query lane. AI engines tend to cite editorial pages for analytical queries: why, how, what should I think, recommendations with reasoning, opinions, judgments. Programmatic pages cannot compete in this lane; the data does not supply the analysis the user wants. + +Implication for pSEO design. Design templates to fit the factual-query lane. Do not try to make programmatic pages compete for analytical queries that editorial content owns. The two lanes coexist; pSEO is one half of a two-lane content strategy. + +The "hybrid page" pattern. Some pSEO programs add an editorial layer to programmatic pages (per-page expert commentary, AI-summarized analysis with human review). Hybrid pages can compete in both lanes when the editorial layer is genuinely substantive. Without substantive editorial layer, hybrid pages read as factual pages with filler attached and lose in both lanes. + +--- + +## Quality crackdown sensitivity + +AI engines have their own quality signals beyond search engines. Thin programmatic content gets deprioritized faster in AI surfaces than in traditional search. + +The migration of penalty risk. Pre-AI search era, thin pSEO sets could rank for 12 to 24 months before quality crackdowns hit. AI engines apply quality signals more aggressively. Thin pSEO sets in 2026 lose AI citations within 3 to 6 months even when traditional search rankings are still holding. + +Signals AI engines use beyond traditional search signals. + +- Distinctiveness. Pages that read as templated boilerplate get deprioritized. Pages that surface page-specific data prominently get cited. +- Source credibility. Pages with named authors, expert credentials, and citation chains get cited preferentially. Anonymous pSEO pages with no attribution lose to attributed pages. +- Citation traceability. Pages that cite their underlying data sources (with links to the source) get treated as authoritative. Pages that present facts without sourcing get treated as unreliable. +- Freshness. Pages with recent update dates get cited preferentially for time-sensitive queries. Stale pages lose AI citations even when traditional search rankings hold. + +The implication. pSEO programs designed pre-AEO need template updates: stronger above-the-fold answers, deeper schema markup, FAQPage schema on FAQ sections, source citations on factual claims, named authorship where the program supports it. + +--- + +## Two-engine optimization + +pSEO pages should serve both search engines and answer engines. + +Both engines reward depth. Search engines reward comprehensive coverage; AI engines reward citation-ready depth. Same content, different extraction. + +Both engines reward structure. Search engines parse heading hierarchy for ranking; AI engines parse heading hierarchy for citation extraction. Same structure, different use. + +Both engines reward freshness. Search engines reward recent updates; AI engines re-index recently updated content more aggressively. Same updates, different cadence. + +The two-engine implication. Designing for AEO does not trade off against SEO. The template improvements that earn AI citations (top-200-word answers, FAQPage schema, named authorship, source citations) also earn search rankings. Teams that treat AEO and SEO as separate optimizations under-invest in both. + +--- + +## Set-level reputation signals + +Beyond individual page signals, AI engines apply set-level reputation. The set's overall quality affects each page's citation likelihood. + +Domain-level reputation. A domain with a substantive editorial content layer plus a high-quality pSEO set ranks both layers more strongly than a domain with only pSEO. The editorial layer establishes the domain's expertise; the pSEO layer benefits. + +Set-level signal compounds. A 10,000-page pSEO set with 90% high-quality pages and 10% thin gets the entire set treated as high-quality. The same set with 60% high-quality pages and 40% thin gets the entire set deprioritized. The bad pages drag the good ones down. + +The implication. Set-level QC discipline (covered in `quality-control-at-scale.md`) is also AEO discipline. Holding the quality threshold across the set protects the set's AI-citation reputation, not just its search ranking. + +--- + +## Measurement + +Hub-level AEO/GEO metrics worth tracking on the pSEO set: + +- Brand mention rate from AI search visibility tools (Profound, Frase visibility tracking, AirOps AEO data) +- Citation share by engine (ChatGPT, Perplexity, Gemini, Claude, Google AI Mode) on the set's target queries +- Top-cited pages within the set (which template patterns get cited most) +- AI crawler hit frequency from server logs (GPTBot, PerplexityBot, ClaudeBot) + +Track at the set level, not just per page. Aggregate trends surface patterns that per-page tracking misses. diff --git a/skills/programmatic-seo/references/common-pseo-failures.md b/skills/programmatic-seo/references/common-pseo-failures.md new file mode 100644 index 0000000..175bb9b --- /dev/null +++ b/skills/programmatic-seo/references/common-pseo-failures.md @@ -0,0 +1,161 @@ +# Common pSEO failures + +Eleven-plus failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable. + +The pattern across most failures: pSEO programs that ship without one of the five readiness criteria (real data, queryable intent, sufficient volume, refresh cadence, QC budget) and assume the gap will close later. The gap rarely closes; the failure compounds. + +--- + +## "We generated 50,000 pages and got penalized" + +Symptom. Algorithm update lands; the set loses 60 to 90% of its traffic in days. + +Diagnosis. Thin content scaled too fast without QC discipline. The set was generating filler pages, sometimes from AI-summarized public data, sometimes from sparse first-party data with bolt-on AI text. The algorithm update detected the scale-without-substance pattern. + +Fix. Halt new generation. Run a triage audit: which pages have substantive data backing them, which are filler. Noindex the filler. The remaining pages may recover ranking once the set's quality signal improves; the filler ones will not. Sometimes the right call is removing the entire pSEO surface and rebuilding from a higher-quality data source. + +Prevention. The five-criterion check (`when-pseo-works-decision.md`) before launch. The QC discipline (`quality-control-at-scale.md`) before scaling. + +--- + +## "We have 10,000 pages but only 200 rank" + +Symptom. Pages exist in the set; few of them rank for their target queries. + +Diagnosis. Internal linking architecture missing or incomplete. Hub pages rank because they receive site-wide navigation links. Child pages do not rank because they have no in-page link votes; they are partial orphans reachable only via sitemap. + +Fix. Build the link graph. Add sibling-link slots to the template. Compute cross-record similarity to populate sibling links. Backfill the link graph across the existing set. Audit for orphans; surface them in the QC queue (`internal-linking-at-scale.md`). + +--- + +## "Crawl rate plateaued" + +Symptom. Page count grows; pages crawled per day stays flat or declines. + +Diagnosis. Crawl budget exhaustion. The set has more pages than the search engine's crawl budget supports. + +Fix. Noindex thin pages. Segment sitemaps. Improve internal linking so crawlers prioritize substantive pages. Reduce server response time. Prune the dead-page tail. Detail in `crawl-budget-management.md`. + +The wrong fix: publishing more pages to "catch up" on traffic targets. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## "Pages look identical" + +Symptom. Random sampling of pages from the set finds them indistinguishable in substance, only different in identifiers. + +Diagnosis. Template lacks variable density, or the data is too sparse to differentiate. The template renders the same boilerplate for every record because the records do not actually differ on the dimensions the template surfaces. + +Fix. Two paths. + +- If the template is the problem (the data has variation but the template hides it): redesign the template to surface distinctive fields prominently. Move the differentiating data above the fold; demote the boilerplate. +- If the data is the problem (the records genuinely lack distinctive fields): the schema is too thin. Either deepen the schema with more source data, or accept that the program does not justify pSEO and pivot to editorial content. + +--- + +## "We cannot update the templates without 10,000 manual fixes" + +Symptom. A template change requires manually editing every existing page. + +Diagnosis. Template versioning was not designed for scale. Pages were generated as static output rather than as renders from the schema; updating the template now requires updating each rendered page. + +Fix. Architectural rebuild. Pages need to be re-rendered from the schema each time the template changes. The schema is the source of truth; the rendered pages are the output. Without this discipline, every template change becomes a per-page migration project. + +Prevention. Design pages as renders from data, not as static artifacts. The specific stack choice (build-time generation that re-runs on template change, server rendering with template version in the cache key, hybrid approaches) varies by team; the methodology principle is the same. + +--- + +## "Our quality control is whoever has time" + +Symptom. No regular QC cadence. Sample audits happen sporadically when someone notices a problem. + +Diagnosis. No sampling discipline, no thresholds, no ownership. The QC was assumed to be everyone's job, which means it is nobody's job. + +Fix. Assign a QC owner. Set the sampling cadence (monthly minimum for active programs). Codify the failure threshold (5% sample failure halts new generation). Track cohort metrics. Detail in `quality-control-at-scale.md`. + +--- + +## "AI engines do not cite our pages" + +Symptom. Traditional search rankings are stable; brand mention rate from AI search visibility tools is flat or declining. + +Diagnosis. Multiple possible causes. + +- The top-200-word answer was not designed; pages start with welcome paragraphs instead of answers. +- Schema markup is thin; AI engines see the pages as low-authority. +- FAQPage schema is missing on FAQ sections. +- Source citations are missing on factual claims. +- The pages read as templated boilerplate rather than as distinctive answers. + +Fix. Audit the template against the AEO/GEO patterns (`aeo-geo-for-programmatic-pages.md`). Update the template; migrate cohorts; monitor citation count by cohort to confirm the fix earned gains. + +--- + +## "We are at 100,000 pages and engagement is dropping" + +Symptom. Traffic continues but bounce rate climbs, time-on-page falls, conversion rate decays. + +Diagnosis. The set has outgrown its data depth. Early pages were the highest-data-quality records; later pages were lower-quality data backfilled to grow the set. Users are landing on pages that do not satisfy their query. + +Fix. Reverse the growth and prune. The set should be smaller and higher-quality, not larger and lower-quality. Identify the data-quality threshold below which pages do not satisfy queries; noindex pages below the threshold; let the set's average quality recover. + +Prevention. The required-field threshold in the schema enforces a quality floor. Pages that fail the threshold should not have shipped in the first place. + +--- + +## "Competitors copied our pages" + +Symptom. A competitor launched a similar pSEO set; the brand's traffic share is shrinking. + +Diagnosis. The data source was not a moat. The pSEO pages were replicable. + +Fix. Two paths. + +- Deepen the data source. First-party data accumulation, expert curation investment, licensed-feed integration that competitors cannot match. The defensibility comes from the data, not from the pSEO build. +- Pivot. If the data cannot be deepened, the program does not have a long-term moat. Consolidate the strongest pages, prune the rest, redirect the team to higher-defensibility work. + +Prevention. The defensibility test (`data-source-identification-patterns.md`) before launch. If competitors could replicate the data source within 6 months at reasonable cost, do not launch the program. + +--- + +## "Refresh is overwhelming" + +Symptom. Quarterly refresh cycles are missed or partially completed; data drifts; pages get stale. + +Diagnosis. Refresh cadence was not designed for scale. The team thought "we will refresh quarterly" but the actual work to refresh 10,000 to 100,000 pages exceeds the team's quarterly capacity. + +Fix. Automate the volatile-field refresh through data pipelines (mostly hands-off after pipeline build). Reduce slow-changing-field refresh frequency to annual on most fields. Cohort-migrate the template refresh rather than big-bang. Detail in `refresh-at-scale.md`. + +If the work still exceeds capacity after these fixes, the set is too large for the team's resources. Prune to a sustainable size. + +--- + +## "Our pSEO drives traffic but no conversions" + +Symptom. Traffic from pSEO pages is high; signups, sales, or engagement on the funnel goal are flat or low. + +Diagnosis. Query intent does not match buyer intent. The pSEO pages are answering informational queries; the buyer the program needs to capture is searching with different intent. + +Fix. Audit the queries the pSEO traffic is coming from. If the queries are not in the buyer's funnel, the program is producing non-converting traffic regardless of how well the pages are optimized. The fix is not "add more CTAs to pSEO pages"; the fix is recognizing that pSEO was not the right channel for the program's conversion goal. + +The reconsider-pSEO moment. If the program's metric is conversions and the pSEO traffic does not convert, pSEO is the wrong tool. Editorial content with stronger buyer-intent alignment, paid acquisition with conversion tracking, or product-led growth surfaces may be the better fit. + +--- + +## "Our QC discipline drifted over time" + +Symptom. The program launched with strong QC. Months in, the cadence slipped, the threshold became aspirational rather than enforced, the cohort tracking went unread. + +Diagnosis. QC ownership rotated, accountability dispersed, the metric dashboard stopped being reviewed. The pattern is the same as the "set and forget" failure for editorial pillar maintenance. + +Fix. Assign a durable QC owner with quarterly accountability. Reinstate the cadence. Audit the set for the drift that accumulated; fix or noindex pages that ship below the threshold. + +Prevention. The QC owner is named in the program's planning doc and renewed annually. The dashboard that tracks cohort metrics has an actual owner who reviews it monthly. The threshold is treated as enforced, not aspirational. + +--- + +## The pattern across all failures + +Most pSEO failures are designed-in. They were predictable from the program's launch shape. The five-criterion check, the schema-as-product principle, the QC budget, the refresh cadence, the link architecture: each one shipped or did not at design time. The set's eventual success or decay was largely determined before the first page generated. + +The discipline is upstream. Hold the line at design time; the operational discipline at scale becomes manageable. Skip the design discipline; the program produces filler at scale and gets penalized. diff --git a/skills/programmatic-seo/references/crawl-budget-management.md b/skills/programmatic-seo/references/crawl-budget-management.md new file mode 100644 index 0000000..8d28d56 --- /dev/null +++ b/skills/programmatic-seo/references/crawl-budget-management.md @@ -0,0 +1,115 @@ +# Crawl budget management + +Sitemap segmentation, noindex on thin pages, canonicalization on duplicates, crawl rate monitoring, pruning criteria. + +Search engines have crawl budgets. Large pSEO sets can exhaust them. Crawl budget management is the discipline that keeps the set crawlable as it scales past 10,000+ pages. + +--- + +## Sitemap segmentation + +A 100,000-page sitemap is harder for crawlers to process than 10 segmented sitemaps with 10,000 entries each. + +Segmentation by category. One sitemap per top-level category. Crawlers prioritize sitemaps differently; segmentation helps the crawler prioritize active categories over dormant ones. + +Segmentation by recency. A "recent" sitemap surfaces pages generated in the last 30 days. Crawlers find new content faster; existing content remains crawlable through category sitemaps. + +Segmentation by update frequency. A "frequently-updated" sitemap surfaces pages whose volatile fields refresh weekly or daily. Crawlers re-crawl these pages on a tighter cadence. + +Sitemap index. A parent sitemap-of-sitemaps points to all segmented sitemaps. The index is what gets submitted to Search Console; the segments handle the actual page lists. + +Sitemap size limits. 50,000 URLs per sitemap is the hard limit. 10,000 to 25,000 per segmented sitemap is the typical practical size; smaller is fine for niche categories, larger is fine for high-volume categories. + +--- + +## Noindex on thin pages + +Pages with insufficient data should noindex rather than ship as bait. + +The discipline. Pages that fail the schema's required-field threshold do not get a public URL. They sit in the system as drafts until their data populates. + +Why noindex matters. Thin pages drag down the entire set's quality signal. Search engines and AI engines both apply set-level quality scoring; a set with 10,000 thin pages and 90,000 substantive pages scores worse than a set with just the 90,000 substantive pages, even though the absolute page count is lower. + +Noindex implementation patterns. + +- The thin pages render with a `noindex` meta tag in the head. +- The thin pages are excluded from the sitemap. +- The thin pages are not linked from any other page in the set. + +The "we'll fix it later" trap. Teams ship thin pages with `index, follow` and plan to backfill data later. The data backfill rarely happens; the thin pages accumulate; the set's quality signal degrades over time. + +--- + +## Canonical handling + +Comparison pages and other pivot patterns produce duplicate-content risks. + +The X-vs-Y pattern. A page comparing X to Y often has an inverse page comparing Y to X. The two pages cover the same content from different orderings. Canonicalize one to the other. + +Canonical decision. Pick the canonical based on search volume, alphabetical order, or category hierarchy. The choice itself matters less than picking one consistently. + +Other pivot patterns. + +- Filter pivots. "Homes in Denver under $500k" and "Homes under $500k in Denver" should canonicalize to one. +- Sort pivots. "Top hotels in Paris by rating" and "Top hotels in Paris by price" might be distinct enough to live separately, or might canonicalize depending on the user-intent overlap. +- Date pivots. "Best [thing] for 2025" and "Best [thing] for 2026" usually live separately because the content genuinely differs by year; canonicalization would lose the time-relevance signal. + +The discipline. Canonical decisions are designed at template time, not retroactively. The template either generates canonical-pair URLs (and chooses one as canonical from the start) or it does not generate the duplicate at all. + +--- + +## Crawl rate monitoring + +Search engines publish crawl statistics. Monitor them. + +Google Search Console crawl stats. Pages crawled per day, average response time, crawl request distribution by category. Monitor monthly; investigate drops or plateaus. + +Crawl rate plateauing while page count grows. The set is hitting crawl budget limits. The fix is not "publish more pages." The fix is: + +- Noindex thin pages to remove low-value crawl targets +- Improve internal linking so crawlers prioritize the substantive pages +- Segment sitemaps so the crawler can prioritize active categories +- Reduce server response time so crawlers can crawl more in the same budget + +Crawl rate dropping unexpectedly. Investigate. Common causes: server errors that the crawler is encountering, robots.txt changes that excluded important paths, sitemap submissions that broke, large-scale URL pattern changes without redirects. + +--- + +## Pruning criteria + +Pages that fail to attract clicks or impressions for 6+ months should noindex or 410. + +The 6-month checkpoint. A page that has been in the set for 6+ months and has earned zero impressions in Search Console is dead weight. The fix is not "wait longer." + +Pruning options. + +- Noindex. The page stays accessible to direct visitors but is removed from the search index. Reversible if the page later starts earning impressions. +- 410 Gone. The page is removed entirely; the URL returns 410. Permanent; appropriate for genuinely obsolete content. +- 301 Redirect. The page redirects to a more-relevant alternative. Appropriate when the user's intent for the dead page can be served by an alternative page that still exists. + +The 12-month and 24-month checkpoints. Pages that have not earned traffic by month 12 should be reviewed for noindex or removal; pages that have not earned traffic by month 24 should be removed unless there is a specific strategic reason to keep them. + +Why pruning matters. Dead pages waste crawl budget. Crawlers visit them, find nothing useful, and the set's average quality signal degrades. Pruning concentrates the set's PageRank on the pages that earn traffic. + +--- + +## When the set is too large for the budget + +Symptoms: + +- Crawl rate is permanently below the page count's natural crawl demand +- New pages take weeks or months to get indexed +- Existing pages drop out of the index unexpectedly +- The site's overall ranking is degrading despite the set being substantively unchanged + +The diagnosis is usually crawl budget exhaustion. The fix is set reduction (prune to the substantive pages), set restructuring (split into multiple subdomains or sites if appropriate), or technical optimization (server response time, sitemap discipline). + +The temptation is to publish more pages to "catch up" with traffic targets. The temptation is wrong. More pages without crawl budget produces more dead weight, not more traffic. + +--- + +## Methodology vs implementation + +The principles above are methodology: which pages to noindex, when to canonicalize, how to segment sitemaps, how to read crawl stats. + +The specific implementation (the framework's noindex meta tag pattern, the sitemap generation library, the canonical link helpers, the deployment-time crawl-test integration) is stack-specific. Each team implements crawl budget management within their own stack's tooling; the methodology applies regardless of the implementation choice. diff --git a/skills/programmatic-seo/references/data-source-identification-patterns.md b/skills/programmatic-seo/references/data-source-identification-patterns.md new file mode 100644 index 0000000..e6fa193 --- /dev/null +++ b/skills/programmatic-seo/references/data-source-identification-patterns.md @@ -0,0 +1,104 @@ +# Data source identification patterns + +First-party, licensed, public, expert-curated, synthesized. Defensibility analysis for each pattern. + +The data source IS the pSEO program. A weak data source produces a weak set regardless of template quality, internal linking, or QC discipline. A strong data source produces durable traffic that compounds across years. + +--- + +## Pattern 1: first-party data + +Data the team owns because the business produced it. + +Sources. Customer transactions, content database, user-generated content, support ticket history, internal product analytics, sales call records, customer feedback databases. + +Defensibility. Maximum. Nobody else has the data. A competitor would have to build the same business and accumulate the same usage history to replicate. + +Examples. Glassdoor's employee reviews (built by getting employees to submit). Yelp's restaurant ratings (built by getting users to rate). TripAdvisor's traveler reviews (built by getting travelers to write). Reddit's discussion threads (built by getting users to post). + +Watchouts. Privacy and terms-of-service compliance. User-generated content used for pSEO needs explicit consent in the original collection terms; retrofitting consent is not legal in most jurisdictions. PII in pSEO pages is a separate liability. + +The "moat compounds over time" effect. First-party data sources get stronger as the business runs longer. A 10-year-old review database is more defensible than a 2-year-old one with the same volume because the time-series depth itself becomes valuable. + +--- + +## Pattern 2: licensed datasets + +Data acquired through commercial licensing. + +Sources. Industry databases (real estate MLS, automotive VIN databases, sports statistics feeds), regulatory data (SEC filings, government statistics), third-party content licenses (medical content, legal precedent). + +Defensibility. Medium to high. Defensibility depends on license exclusivity and integration depth. An exclusive license is a moat; a non-exclusive license that anyone can also buy is not. + +Examples. Zillow's MLS partnerships (licensed feeds with depth integration). Sportradar customers building stats sites. Bloomberg Terminal customers building financial content. Real estate brokerages with regional MLS access. + +Watchouts. License costs scale with usage; the unit economics need to work at scale. License terms typically restrict redistribution, which can complicate pSEO scaling (the data can power the pSEO pages but cannot be exported as a downloadable dataset). + +--- + +## Pattern 3: aggregated public data + +Data scraped, cleaned, enriched from public sources. + +Sources. Open government data, public web pages, academic research, public APIs. + +Defensibility. Low to medium. Anyone can scrape the same sources; the defensibility comes from the cleaning and enrichment work. If the cleaning is shallow, the defensibility is none. + +Examples. Sites built on government statistics (census data, BLS data). Sites built on academic research summaries. Sites built on public company filings (EDGAR data plus enrichment). + +Watchouts. Legality is jurisdictional and often gray. robots.txt compliance, terms-of-service review, copyright considerations, anti-circumvention rules in some jurisdictions. The legal review is mandatory, not optional, even when the data is "public." + +The "scraped Wikipedia plus AI rewrite" anti-pattern. The lowest-effort form of this category. The data is not really enriched (AI rewrite of public encyclopedia entries adds no defensible value). The pSEO sets built on this pattern are the ones that get penalized first when algorithm updates run. + +--- + +## Pattern 4: expert-curated content + +Data produced by hired experts who populate the dataset by hand. + +Sources. Expert-written reviews, expert-curated lists, professionally-tested products, professionally-evaluated services, professional translations. + +Defensibility. High. The defensibility is in the curation cost. A competitor would have to hire and pay the same experts for the same time to replicate. + +Examples. Wirecutter's product testing (experts test products in lab conditions). Consumer Reports' product reviews. Edmunds' car reviews. Specialty publications with paid expert contributors. + +Watchouts. Slow to build. The set scales at the speed of expert capacity, not at the speed of automated generation. Budget reflects the headcount, not the engineering effort. + +The combination pattern. Expert-curated content often combines with structured data (the expert reviews a car; the dataset captures the expert's score plus structured specifications) to produce pages with both narrative depth and queryable structure. + +--- + +## Pattern 5: synthesized data + +Data produced by combining multiple sources into a unique view. + +Sources. Multi-source pipelines that produce derived analyses unavailable from any single source. + +Defensibility. Medium to high. Defensibility comes from the synthesis logic and the ongoing pipeline maintenance. + +Examples. "Neighborhoods times schools times prices" combining three datasets into a comparison view. "Companies times salaries times employee reviews" combining three sources into a candidate-decision view. Aggregator pages that show "best X for Y use case" combining multiple product databases with use-case classification. + +Watchouts. The synthesis logic is the moat, not the underlying sources. Changes to source schemas break the pipelines. The pSEO program inherits the operational fragility of multi-source pipelines. + +--- + +## The defensibility test + +For each candidate data source, walk this question: would a competitor be able to replicate this source within 6 months at reasonable cost? + +- Yes, easily. No moat. Pursue editorial content instead, or invest in expert curation to build a moat. +- Yes, with effort. Partial moat. The first-mover advantage matters; ship before competitors. +- No, requires major investment. Real moat. pSEO compounds. +- No, requires assets the competitor cannot acquire. Strongest moat. The pSEO program becomes a long-term competitive advantage. + +--- + +## Combining patterns + +The strongest pSEO programs combine multiple patterns. + +- First-party data plus licensed data (Glassdoor: user reviews plus salary licenses) +- Licensed data plus expert curation (Wirecutter: licensed product databases plus expert testing) +- First-party data plus synthesized data (Yelp: user ratings synthesized with location data and external attributes) + +Single-pattern programs are simpler to ship but easier to replicate. Multi-pattern programs are harder to build and harder to copy. diff --git a/skills/programmatic-seo/references/internal-linking-at-scale.md b/skills/programmatic-seo/references/internal-linking-at-scale.md new file mode 100644 index 0000000..6c4d441 --- /dev/null +++ b/skills/programmatic-seo/references/internal-linking-at-scale.md @@ -0,0 +1,116 @@ +# Internal linking at scale + +Hub-and-spoke, sibling linking, anchor text variation, orphan prevention. + +The internal-link graph is half the program; the data is the other half. A well-linked pSEO set distributes ranking signal across all pages and compounds. A poorly-linked set has hub pages ranking and child pages orphaned. + +--- + +## Hub-and-spoke architecture + +The standard pSEO link topology. + +Hub pages. Parent-level pages that aggregate the children. "Homes for sale in Denver" is a hub for the neighborhoods; "Software engineer salaries" is a hub for the company-specific salary pages; "Hotels in [city]" is a hub for individual hotel pages. + +Hub-level discipline. + +- Hub pages are linked from main site navigation, not just from sitemaps. Crawlers reach hubs first and traverse to children from there. +- Hub pages link to all children in the category. The hub's body or a paginated listing exposes the full set. +- Hub pages are not just link aggregators; they have their own content (category overview, comparison tables, top-of-category aggregates) that earns ranking on its own. + +Spoke pages. The individual records. Each spoke links up to the hub and laterally to siblings. + +--- + +## Sibling linking + +Each page links to 5 to 15 related sibling pages. + +The pattern. The sibling-link section of the template renders 5 to 15 related records computed from cross-record fields in the schema. Most-similar-by-attribute, similar-price-range, similar-features, geographic neighbors. + +Why sibling linking matters. Without it, the link graph is a star (hub to spokes only). PageRank concentrates at the hub; spokes get minimal flow. With sibling linking, the graph is dense; PageRank distributes across the set. + +Bidirectional linking. Sibling links go both directions. If A links to B as a sibling, B should link to A. Asymmetric sibling linking creates ranking dead ends. + +Avoiding the "everyone links to everyone" trap. Every page linking to every other page is a complete graph; anchor text relevance dilutes; the link graph reads as algorithmic rather than semantically meaningful. The 5 to 15 sibling-link cap keeps each page's outbound graph navigable and signal-dense. + +--- + +## Reverse-direction (bottom-up) linking + +Spoke pages link UP to hub. + +The first-200-words pattern. The spoke page's introduction includes a contextual link up to the hub: "This page covers [specific record]. For the broader [category] overview, see [hub page]." + +The closing pattern. The spoke page's closing includes a link back to the hub or to the next-most-relevant sibling, giving readers a navigation path back to broader content. + +Why bottom-up matters. Without it, the hub does not compound. The spokes inherit traffic from their long-tail queries; without bottom-up links, that traffic does not flow back to lift the hub. + +--- + +## Anchor text variation + +Avoid every page using the same anchor text. + +The principle. Anchor text is the signal that tells search engines what the linked-to page is about. Identical anchor text across thousands of links to the same page reads as manipulation; varied anchor text reads as natural authority. + +Variation patterns for pSEO. + +- Record-name variation. "View [neighborhood name]" / "[neighborhood name] homes for sale" / "Browse [neighborhood name] listings" / "[neighborhood name] guide" used across different siblings linking to the same record. +- Descriptive variation. Anchor text that describes the linked page's distinctive attribute. "Affordable [neighborhood]" / "Top-rated [neighborhood]" / "Family-friendly [neighborhood]" computed from the target record's attributes. +- Context-driven variation. The anchor text shifts based on what the linking page is about. A page about prices uses price-relevant anchor text; a page about schools uses school-relevant anchor text. + +Anti-pattern. Every sibling link uses "[Record name]" as the anchor. Easy to ship at scale, signals manipulation, dilutes the page's anchor profile. + +--- + +## Crawl-friendly architecture + +Hub pages are linked from main navigation. Child pages are reachable via hub or via segmented sitemaps. No orphan child pages. + +Sitemap segmentation. A pSEO set with 50,000 child pages does not put all 50,000 in a single sitemap. Segment by category, by recency, by data freshness. Crawlers process segmented sitemaps more reliably. + +Sitemap-only access is not enough. A child page only reachable via sitemap, with no other page linking to it, is a partial orphan. Crawlers may visit it; the page will struggle to compound ranking signal because no in-page link votes for it. + +The orphan check. Pages with zero inbound internal links besides the sitemap are orphans. Audit quarterly; surface in QC. The fix: add the page to the hub's listing, add it to sibling sets it should belong to, expose it through breadcrumb navigation. + +--- + +## The PageRank flow principle + +Internal linking is what makes pSEO sets compound. + +The pattern that compounds. Hub linked from main nav (high PageRank concentration). Hub links to all children (PageRank distributes). Children link laterally to siblings (PageRank circulates within the set). Children link back up to hub (PageRank reinforces). + +The pattern that does not compound. Hub linked from main nav. Hub links to children. Children do not link to siblings, do not link back to hub. PageRank flows hub-to-child but does not circulate; child pages slowly accumulate independent ranking signal but never compound. + +The auditable signal. Average internal-links-in per page. The set's average should be 8 to 20 inbound internal links per page. Below 5, the set is under-linked and orphans dominate. Above 30, the set is link-dense and anchor signal dilutes. + +--- + +## Linking inventory + +Maintain an inventory of every internal link in the pSEO set. + +Inventory format. A queryable dataset (typically a database table or analytics schema) tracking source page, target page, anchor text, link slot (breadcrumb / hub / sibling / related-record / related-content), link direction, last-validated date. + +Why inventory matters. + +- Quarterly audits run queries against the inventory: orphan check, sibling symmetry check, anchor diversity check, broken-link check. +- Template changes that affect linking (slot adjustments, anchor pattern changes) can be analyzed against the inventory before shipping. +- Pruning decisions reference the inventory: "if we noindex these 200 pages, what siblings lose links and need their slots refilled?" + +The "no inventory" failure. Without inventory, audits become "crawl the site each time," which is slow and produces inconsistent results. The inventory turns audit into a query operation. + +--- + +## When linking architecture is broken + +Symptoms: + +- Hub pages rank, child pages do not (under-linked spokes; add sibling linking) +- Specific category cluster does not rank as well as siblings (the category's internal links are sparse; investigate) +- Crawl rate plateaus while page count grows (link graph cannot absorb new pages; sitemap and link slots need restructuring) +- Algorithm update hits child pages disproportionately (children read as orphans without hub-and-spoke reinforcement) + +The fix is rarely "more pages." The fix is usually "better link graph through the existing pages." Internal linking is the structural multiplier. diff --git a/skills/programmatic-seo/references/quality-control-at-scale.md b/skills/programmatic-seo/references/quality-control-at-scale.md new file mode 100644 index 0000000..c108409 --- /dev/null +++ b/skills/programmatic-seo/references/quality-control-at-scale.md @@ -0,0 +1,126 @@ +# Quality control at scale + +Sampling strategy, automated checks, manual review checklist, failure thresholds, cohort tracking. The discipline that distinguishes durable pSEO from penalty-bait. + +Auditing all 100,000 pages individually is infeasible. Quality control at scale is sampling discipline plus automated checks plus failure thresholds plus cohort tracking. Without it, pSEO sets degrade silently until algorithm updates expose the rot. + +--- + +## Sampling strategy + +Random sample 50 to 200 pages per audit cycle, balanced across data shape. + +Stratified sampling. Not "the latest 50 pages" or "the top-traffic 50 pages." A stratified sample exposes problems specific to particular data shapes. + +Stratification dimensions: + +- Sparse vs dense data. Sample some records with minimum-required fields; sample some with most-fields-populated. +- Recent vs old. Sample some pages generated in the last 30 days; sample some generated 12+ months ago. +- Popular vs niche categories. Sample some pages from high-traffic parent categories; sample some from low-traffic ones. +- Different cohort versions. If the template has shipped revisions, sample some pages from each cohort. + +Sample size by set size. + +- Set under 1,000 pages: sample 50 pages per cycle. +- Set 1,000 to 10,000 pages: sample 100 pages per cycle. +- Set 10,000 to 100,000 pages: sample 150 pages per cycle. +- Set 100,000+ pages: sample 200 pages per cycle. + +Cycle frequency. Monthly for active sets (new pages generating, data refreshing). Quarterly for stable sets (mature programs in maintenance mode). + +--- + +## Automated checks + +Run on every page on a cadence; surface failures as a queue. + +Heading-structure check. Validates H1 exists once, H2s are in order, no orphan H3s, no H2-H3-H4 cascades that nobody scrolls. + +Schema-validity check. Validates JSON-LD against the page's intended schema type; flags missing required fields, type mismatches, malformed structured data. + +Internal-link-count check. Flags pages with fewer than 10 internal links (under-linked) or more than 50 (link-dense, anchor-signal-diluting). + +Word-count threshold check. Flags pages below the template's minimum (typically 300 to 500 words depending on category). Pages below the threshold either need data backfill or should sit as drafts. + +Duplicate-content check. Hash similarity across the set; flags pages with >80% content overlap with another page in the set. Common cause: comparison pages where X-vs-Y duplicates Y-vs-X without canonicalization. + +Broken-link check. Crawl outbound and internal links; flag 404s and 5xx responses. Ages quickly without the check; cluster pieces that linked to deleted records become orphan-link generators. + +Schema-population-rate check. For each optional schema field, the percentage of pages that populate it. Flag fields with population rates below 50%; these usually need either to be required, dropped, or backfilled. + +--- + +## Manual review checklist + +For sampled pages, the human review covers what automation misses. + +Above-the-fold answer quality. Read the first 200 words. Does it answer the user's likely query? Is the language specific to this record or templated boilerplate? + +Distinctive vs templated. Compare the page to two siblings. Could you tell them apart on substance, not just on the names? If they read identically, the template lacks variable density or the data is too sparse to differentiate. + +Citation-readiness. Would an AI engine cite this page for the user's query? Specifically: is there a self-contained answer paragraph, are statistics with sources present, is FAQPage or Article schema marked correctly? + +User-intent satisfaction. If a real user landed on this page from the target SERP, would they stay or bounce? Bounce-shaped pages are the failure mode; staying-shaped pages are the goal. + +Off-brand or off-tone signals. Does the page read consistently with the brand voice? Templated pSEO tends to drift toward generic neutral voice; the brand voice should still be present. + +--- + +## Failure thresholds + +If more than 5% of sampled pages fail the manual review, halt new generation and fix the template or data before scaling further. + +The 5% threshold. Empirical. Programs that hold under 5% sample failure tend to maintain quality at scale; programs that drift above 5% tend to compound the failure into algorithm-update territory. + +What "halt" means. New page generation stops. The template or data fix is shipped. The next sample audit confirms the fix improved the failure rate before generation resumes. + +Why halt instead of "fix as you go." Continuing to generate while quality degrades produces more pages that need to be fixed retroactively. Halting prevents the problem from compounding. + +The threshold is not negotiable. "Just ship the next batch and we'll fix later" is the failure mode. The pattern produces pSEO sets that look fine at month 6 and get penalized at month 18. + +--- + +## Cohort tracking + +Pages generated in one period rank differently from pages generated in another? That signals a template change or data quality drift; investigate. + +Cohort cuts. Pages from a given month, pages from a given template version, pages from a given data-source version. Track ranking, click-through rate, citation count (from AEO measurement), and engagement metrics by cohort. + +Drift signals. + +- Cohort A pages rank top 10; cohort B pages rank position 30. Template or data changed between cohorts; identify the change. +- Cohort A pages get cited; cohort B pages do not. Template's above-the-fold answer changed shape; cohort B may have lost the citation pattern. +- Cohort A pages have stable engagement; cohort B pages have decaying engagement. Cohort B may have a data freshness problem. + +Why cohorts matter. Aggregate metrics hide problems. The set's overall rank looks fine if 80% of pages are stable and 20% are decaying. Cohort tracking surfaces the decaying 20% specifically; aggregate tracking misses it. + +--- + +## Team budget + +A 10,000-page pSEO set requires roughly 0.5 to 1.0 FTE of ongoing quality control discipline. A 100,000-page set requires 2 to 4 FTE. + +Where the headcount goes. + +- Sample audit cycles (monthly to quarterly) +- Automated check failure queue triage +- Manual review of sampled pages +- Template or data fixes when failures surface +- Cohort tracking analysis and investigation +- Refresh cycle execution (volatile-field refresh, template-version migration) + +The "we'll get to QC later" failure. Programs that ship without QC headcount budgeted typically degrade within 6 to 12 months. The set looks fine on launch day; the data drifts, the template ships untracked changes, the cohort gap widens, and by month 12 the algorithm update finds the rot. + +The discipline. Budget the QC headcount before generating the first page. If the budget cannot absorb 0.5+ FTE for ongoing QC, the program's scope is too large; reduce scope until QC fits. + +--- + +## When QC reveals the program is broken + +Sometimes the QC discipline reveals that the underlying program is wrong, not just that individual pages need fixes. Signals: + +- 30%+ of sampled pages fail the manual review (data is too thin to support the template) +- Failures cluster around a specific category (the dataset has a hole in that category; pSEO is generating pages from missing data) +- Cohort decay is universal (the underlying competitive dynamics have shifted; the program's value proposition is decaying) + +The right response is not "fix individual pages." The right response is to revisit the program's design: data depth, template scope, cohort coverage. Sometimes the answer is to prune the program back to its strong segments and walk away from the weak ones. The sunk cost is real but smaller than the cost of continuing to generate filler. diff --git a/skills/programmatic-seo/references/refresh-at-scale.md b/skills/programmatic-seo/references/refresh-at-scale.md new file mode 100644 index 0000000..a402ea8 --- /dev/null +++ b/skills/programmatic-seo/references/refresh-at-scale.md @@ -0,0 +1,100 @@ +# Refresh at scale + +Data refresh cadence, template versioning, cohort migration, pruning lifecycle. + +pSEO sets decay if not maintained. Refresh discipline is built into the program at design time; retrofitting refresh on a 50,000-page set that was not designed for it costs more than building it from the start. + +--- + +## Data refresh cadence + +Match the refresh cadence to the data's volatility and the query's freshness reward. + +Volatile fields. Daily to weekly refresh. Real estate listings, current prices, current availability, recent reviews, current ratings. The data feed updates daily; the pages update daily; the search and AI surfaces see fresh data. + +Slow-changing fields. Quarterly refresh. Population statistics, business categories, attribute classifications, neighborhood demographics. The data updates seasonally or annually; the refresh cycle aligns. + +Static fields. No refresh required. Geographic coordinates, founding years, fixed attributes. Set at record creation; tracked in the schema's update-tag system. + +Mixed-cadence pages. Most pSEO pages are mixed: some volatile fields, some slow-changing, some static. The refresh pipeline updates each field on its own cadence; the page renders the latest data on each request (or rebuilds when fields change). + +The "refresh cadence wasn't designed in" failure. A program ships with annual refresh as the plan. Six months in, the volatile fields are stale (prices moved, listings expired). The fix is expensive: retrofit a daily pipeline for fields that should have had one from launch. + +--- + +## Template version migration + +When the template improves, all existing pages need migration. + +Why templates ship revisions. AEO patterns evolve, SERP intent shifts, schema requirements update, brand voice tightens. Templates from 18 months ago may need significant updates to compete in the current search and AI environment. + +Cohort-by-cohort migration. Migrate one cohort at a time, monitor, then migrate the next. The cohort might be a category, a generation period, a data-density tier. The cohort approach surfaces problems specific to particular page shapes before they spread across the entire set. + +Big-bang migration. Migrate all pages at once. Higher risk; if the new template has a regression, the entire set degrades simultaneously. Sometimes the right call when the migration is small or the team can roll back fast; usually the wrong call for large changes. + +Migration monitoring. Each cohort post-migration is monitored for 30 days minimum: ranking changes, citation count changes, click-through rate changes, engagement metric changes. Negative trends pause the migration and surface the regression before it propagates. + +Rollback discipline. The template migration ships with a rollback path. If a cohort's metrics degrade post-migration, the cohort rolls back to the previous template while the regression is investigated. Without rollback discipline, a bad migration produces permanent damage. + +--- + +## Cohort migration patterns + +Three common patterns. + +Category-based cohort migration. Migrate one parent category at a time. Real estate: migrate Denver pages first, monitor 30 days, then migrate Seattle. The advantage: category-level metrics are clean; investigation is scoped. + +Generation-period cohort migration. Migrate the oldest cohort first (pages generated in year 1), then the next, then the next. The advantage: oldest pages have the most accumulated decay; migrating them first improves the set's average quality fastest. + +Data-density cohort migration. Migrate the dense-data pages first (most fields populated), then the medium, then the sparse. The advantage: dense pages have the most upside from template improvements; sparse pages may need data backfill before template migration earns gains. + +The right pattern depends on the migration's intent. AEO-focused migrations often prefer dense-data first. Algorithm-update recovery migrations often prefer category-based. Maintenance migrations often prefer generation-period. + +--- + +## Pruning lifecycle + +Pages generated 2+ years ago that have not earned traffic should be evaluated for noindex or removal. + +The 24-month checkpoint. Standard cutoff. A page that has been indexed for 24+ months and has earned zero impressions in Search Console is dead weight. Pruning options: noindex, 410, or 301 redirect to a more-relevant alternative. + +Earlier pruning for some categories. Time-sensitive pages (annual "best of [year]" pages, event-specific pages, deal-specific pages) prune earlier. A "best of 2024" page generated in 2024 should be archived or pruned by mid-2026; the freshness signal has decayed. + +Later pruning for stable categories. Some categories support evergreen pages that earn traffic for decades. Geographic pages (neighborhoods, cities), historical reference pages, foundational definitional pages. The 24-month checkpoint is too aggressive for these; review case-by-case. + +Pruning is hygiene, not failure. Pruning a page that did not earn traffic is not abandoning the program; it is removing dead weight that drags the set's quality signal down. The set is healthier with 40,000 traffic-earning pages than with the same 40,000 plus 60,000 dead pages. + +--- + +## Set-level refresh + +Occasionally the entire set's template needs a refresh. + +Triggers for set-level refresh. + +- AEO patterns shifted significantly (the entire set needs better above-the-fold answers, FAQPage schema, or source citations) +- The dataset's underlying source changed schema (the new data exposes fields the old template did not render) +- User expectations evolved (the category's accepted page shape shifted; the set's pages now read as dated) +- An algorithm update affected the set disproportionately (the set's design needs to adapt to the new ranking signals) + +Set-level refresh is a 6-month project. Plan accordingly. The work includes template redesign, cohort-by-cohort migration, post-migration monitoring, and pruning of pages that the new template cannot improve. Underestimating the duration is the most common mistake. + +The "do not refresh and let the set decay" anti-pattern. Some teams treat the initial pSEO build as ship-and-forget. The set ranks for 12 to 18 months, then declines as competitors with refreshed sets pass it. The decline accelerates when an algorithm update finds the set's accumulated drift. Refresh is part of the program's ongoing cost; teams that do not budget for it should not start the program. + +--- + +## Refresh budget + +The ongoing refresh cost in headcount. + +Volatile-field refresh. Mostly automated (data pipelines pull new data into the schema). 0.1 to 0.5 FTE for pipeline maintenance and exception handling. + +Slow-changing-field refresh. Quarterly cycles. 0.2 to 0.5 FTE during cycles; lower between cycles. + +Template version migration. Project-based when migrations ship. 1 to 3 FTE for the duration of the migration; varies by set size and migration scope. + +Pruning lifecycle. Quarterly review of dead pages. 0.1 to 0.3 FTE. + +Total ongoing refresh budget. A 10,000-page set: roughly 0.5 FTE steady state plus migration projects when they ship. A 100,000-page set: 1 to 2 FTE steady state plus larger migration projects. + +The refresh budget is in addition to the QC budget. Programs that under-budget either degrade; programs that budget both produce durable traffic for years. diff --git a/skills/programmatic-seo/references/schema-design-patterns.md b/skills/programmatic-seo/references/schema-design-patterns.md new file mode 100644 index 0000000..563400f --- /dev/null +++ b/skills/programmatic-seo/references/schema-design-patterns.md @@ -0,0 +1,114 @@ +# Schema design patterns + +Field count, computed fields, cross-record fields, update tags, schema-as-product. The data shape that drives the template. + +The schema design here is the methodology layer: what shape the data takes, what fields earn their keep, what derivations add depth. Specific framework type signatures, ORM bindings, and database column choices are stack-specific implementation that varies by team. + +--- + +## Field count signals depth + +5 fields per record is thin. 15 to 20 is competent. 30+ is deep. + +Why field count matters. Field count determines what the template can render at depth versus what falls back to filler. A record with 5 fields can produce a 200-word page; a record with 30 fields can produce a 1,500-word page that reads as substantive across multiple sections. + +The "thin schema" failure mode. Teams design with 5 to 10 fields, ship, find pages reading as thin, then try to bolt on additional fields after the fact. Bolt-on fields rarely populate consistently across the existing dataset; the result is a half-thin set with a thin tail and a thicker head. + +The "too-many-fields" trap. 50+ fields per record where most are sparsely populated. The schema looks deep on paper but most fields are empty for most records. The template either renders empty sections (looks broken) or hides them (back to thin pages). Better to design 25 fields with 90% population than 50 fields with 30% population. + +--- + +## Required vs optional fields + +Which fields must populate for a page to ship; templates need graceful degradation for optional gaps. + +Required field discipline. Define a minimum field-count threshold below which a record does not get a public page. The threshold ships in the schema validation; pages that fail validation sit as drafts until their data populates. + +Optional field handling. Each optional field has a render rule: if populated, render this section; if empty, hide this section or substitute a computed default. The render rules are part of the template, not afterthoughts. + +The discipline. A page with 25 of 30 optional fields populated is fine. A page with 3 of 30 should not ship; it produces filler content that drags the entire set's quality signal down. + +--- + +## Computed fields + +Derived from source data. Computed fields are the pSEO equivalent of the writer adding analysis: the data does the analysis once, every page benefits. + +Common computed-field patterns. + +- Aggregations. "Average price per square foot" computed from listing data; "median rating" computed from review data. +- Derived classifications. "Price tier" computed from price percentiles; "freshness tier" computed from data age. +- Comparisons. "Price vs neighborhood average" computed from the record's price and the parent category's average; "rating vs category average." +- Trends. "Price trend over 12 months" computed from time-series source data; "review-volume trend" from review-date stamps. +- Rankings. "Top 10 percent by [field]" computed across the set; "ranked by [field] within [category]." + +Why computed fields earn their keep. Each computed field adds a section to the template without requiring more source-data collection. The pipeline does the work; the template renders the result. This is how 15-field source data produces 30-field rendered pages. + +--- + +## Cross-record fields + +Fields that reference OTHER records in the set. Enable internal linking and comparison without manual curation. + +Common cross-record patterns. + +- Most similar records. "5 most similar neighborhoods" computed by attribute distance. +- Parent and child references. "Parent category" and "list of child records" computed from the hierarchy. +- Sibling-comparison aggregates. "Average price across sibling neighborhoods" computed across the parent's children. +- Recommended-related. "Users who viewed X also viewed Y" computed from analytics data (when first-party analytics is available). + +How they power linking. The sibling-link slot in the template renders from the "most similar records" cross-record field. Without this field, sibling linking becomes manual curation at scale, which is infeasible. + +--- + +## Update frequency tags + +Which fields are static (geographic features, founding date) versus which need refresh tracking (current pricing, availability, current statistics). + +Tag categories. + +- Static. Set at record creation; rarely changes (geographic coordinates, neighborhood name, founding year). +- Slow-changing. Updates quarterly to annually (population statistics, business categories, attribute classifications). +- Volatile. Updates daily to weekly (current price, current availability, current rating, recent reviews). +- Real-time. Updates within minutes (live availability, dynamic pricing). Only relevant when the underlying data feed supports it. + +Why tagging matters. Without tags, refresh becomes "audit everything every cycle," which does not scale. With tags, refresh becomes "refresh volatile fields daily, slow-changing fields quarterly, static fields never," which scales. + +--- + +## Schema-as-product principle + +The schema that drives pSEO IS the product surface. Treat it with the same rigor as a database schema for a customer-facing application. + +Schema versioning. Major schema changes (renaming required fields, restructuring nested objects, changing field types) bump a version. Minor changes (adding optional fields, adding computed fields) do not. All schema changes are reviewed; breaking changes require migration plans. + +Schema documentation. Every field has a description, a source (where the data comes from), an update tag, a population rate (what percentage of records have this field), and example values. Documentation lives alongside the schema; it is not a separate doc that drifts. + +Schema review. Before adding fields or changing field types, the schema change goes through review with stakeholders who depend on the schema (template authors, QC reviewers, analytics consumers). Schema changes affect downstream rendering; review catches breakage before it ships. + +Schema testing. Validation rules ship as automated tests. Required fields, type constraints, value-range constraints, cross-field consistency checks. The tests run on every record in the dataset on a cadence; failures surface in the QC queue. + +--- + +## When the schema is wrong + +The schema is wrong when: + +- Required-field threshold produces too few publishable pages (relax the threshold or fix the data pipeline) +- Required-field threshold produces too many shallow pages (raise the threshold; let thin records sit as drafts) +- Optional fields are sparsely populated, dragging the average page quality down (drop them and refocus on dense fields) +- Computed fields are not actually used by the template (cut them; reduce schema bloat) +- Cross-record fields produce poor sibling matches (revise the similarity algorithm; the sibling-link section is doing real work for users) +- Update tags are wrong (refresh cadence is missing or over-shooting; recalibrate) + +The schema is iterated, not designed once. The "schema-as-product" principle makes that iteration safe by enforcing review and migration discipline; without it, every schema change risks breaking the template. + +--- + +## Methodology-level choices that stay in the public skill + +Field-count thresholds, computed-field patterns, cross-record patterns, update-tag categories, the schema-as-product principle. + +## Implementation choices that stay internal + +The specific schema language (TypeScript type definitions, dbt YAML, Sanity schema config, Prisma schema, etc.). The specific ORM or query layer. The specific validation framework. The specific deployment pipeline for schema migrations. These vary by stack. diff --git a/skills/programmatic-seo/references/template-design-patterns.md b/skills/programmatic-seo/references/template-design-patterns.md new file mode 100644 index 0000000..e56000d --- /dev/null +++ b/skills/programmatic-seo/references/template-design-patterns.md @@ -0,0 +1,104 @@ +# Template design patterns + +Variable density, above-the-fold answer, heading hierarchy, schema integration, link slots. + +The template is the structure that data fills. Templates are designed at the methodology level here; specific framework implementations (rendering, slot composition, build-time generation versus on-demand rendering) are stack-specific and belong in internal team documentation. + +--- + +## Above-the-fold answer + +The first 200 words of the rendered page answer the user's specific query. + +Why. Search engines and AI engines both extract the top of the page disproportionately. Featured snippets pull from the first answer-shaped paragraph. AI engines extract the first 200 words as the canonical citation. The reader who lands on the page from a SERP decides within 5 seconds whether to stay; the answer needs to be visible. + +The pattern. Lead with the structured answer to the specific query: the price, the rating, the count, the comparison, the location, the recommendation. Follow with supporting details that justify or expand the answer. The opening is not a marketing introduction; it is the answer paragraph. + +Anti-pattern. "Welcome to our [page type] page. Below you will find information about [topic]." This intro reads as filler to crawlers and humans. Cut it; lead with the answer. + +--- + +## Variable density + +The template accommodates records with sparse fields and dense records gracefully. + +Sparse-record handling. Some records will have fewer fields populated. The template needs fallback patterns: hide sections that depend on missing fields, substitute computed defaults, surface "limited data available" rather than rendering empty headings. + +Dense-record handling. Some records will have many fields. The template needs progressive disclosure: collapse less-essential sections behind expandable headings, paginate long lists, prioritize the most-queried fields above the fold. + +The shape principle. Two pages from the same template can differ significantly in length and depth based on data density without either looking broken. A page with 20% of optional fields populated should still feel competent; a page with 95% should not feel overstuffed. + +--- + +## Heading hierarchy reflects data + +H2s and H3s map to data sections, not to template decoration. + +The pattern. The H2 set is the same across all pages in the template, but the content under each H2 reflects each page's specific data. "Overview," "Details," "Comparisons," "Related" might be the H2 set; what populates each varies per page. + +Snippet-bait paragraphs at H2 level. Each H2 has a 40 to 60 word answer paragraph immediately following it that summarizes that section's specific content. AI engines often quote these as multi-paragraph citations. + +Anti-pattern. Every page has a different H2 set because the template branches on data. The inconsistency confuses crawlers; the heading structure should be predictable across the set. + +--- + +## Schema markup as part of template + +Structured data renders machine-readable signals at scale. + +The principle. Pick the schema type that matches the page's content (Product, Article, LocalBusiness, FAQPage, BreadcrumbList, etc.). Embed the schema in the template; populate from the same data that renders the visible page. The schema is generated, not hand-written; the template ensures every page has it. + +Validation discipline. Run schema validation as an automated check on every generated page. Schema errors produce silent failures in search and AI surfaces; the validation catches them before publish. + +Schema field coverage. Populate every relevant schema field, not just the required ones. Optional schema fields (aggregateRating, additionalProperty, areaServed, etc.) signal depth at scale even when individual fields are not visibly rendered. + +--- + +## Internal linking placeholders + +The template includes link slots for related-record cross-references, parent-category links, and sibling-record links. + +Standard slot patterns. + +- Breadcrumb slot. Path from home to current record. 3 to 4 levels typical. +- Parent-category slot. Link up to the hub page for the record's category. +- Sibling slot. 5 to 15 related sibling records. Computed from cross-record fields in the schema. +- Related-record slot. 3 to 5 records related across categories (different parent, similar attributes). +- Related-content slot. Editorial content related to the record (blog posts, guides, comparison editorials). + +Total internal links per page. 15 to 30 typical for a well-linked pSEO page. Below 10, the page is under-linked; above 50, the page reads as link-dense and dilutes anchor signal. + +--- + +## Distinctive value per page + +Each generated page must offer something the user could not get by going up to the parent or sideways to a sibling. + +The test. Generate three sample pages from the template using different records. Read all three. Can you tell them apart on substance, not just on the names? If the pages are interchangeable in everything but identifiers, the template is not generating distinct value. + +The fix. Surface the distinctive fields prominently. The fields that vary most across the set are the ones that justify the page's existence; those should be in the above-the-fold answer and in the H2 structure, not buried as "additional details." + +--- + +## Quality bar: the random-sample test + +The template's quality bar. A randomly sampled page from the set, viewed in isolation, should answer the user's likely query competently. + +The test sequence. + +1. Pick 5 random records from the dataset. +2. Render them through the template. +3. Read each page as if you arrived from a search results page. +4. Score each page on three dimensions: does it answer the query, is the depth competitive with editorial content for the same query, would you trust this page as a source. + +If any of the 5 fails, the template needs work before scaling. The 5-page sample is the minimum viable QC; the cohort tracking discipline scales it across the program's lifetime. + +--- + +## Methodology-level design choices that stay in the public skill + +The principles above. Field-count heuristics, slot patterns, hierarchy choices, validation discipline, sample-test discipline. + +## Implementation choices that stay internal + +The framework rendering choice (build-time generation, server rendering, hybrid), the specific component composition pattern, the specific data-fetching layer, the deployment topology, the cache-invalidation strategy. These vary by stack and team and should not be prescribed at the methodology level. diff --git a/skills/programmatic-seo/references/when-pseo-works-decision.md b/skills/programmatic-seo/references/when-pseo-works-decision.md new file mode 100644 index 0000000..269fb79 --- /dev/null +++ b/skills/programmatic-seo/references/when-pseo-works-decision.md @@ -0,0 +1,107 @@ +# When pSEO works decision + +The five-criterion framework for deciding whether programmatic SEO is the right answer, with worked examples across business types. + +The default answer is no. Most teams asking "should we do pSEO?" should hear "probably not." pSEO works only when all five criteria are met; failing any one is a hard signal to pursue editorial content or paid acquisition instead. + +--- + +## The five criteria + +### 1. Real underlying data + +A genuine structured data source with depth. 10+ fields per record, ideally 20+. First-party data, licensed datasets, expert-curated content, or synthesized multi-source data. Not scraped Wikipedia plus AI rewrite. + +The test. Could a competent reader extract genuine value from a single page in the set without reading any other page? If yes, the data is real. If no, the page is filler dressed as pSEO. + +### 2. Long-tail query volume justifies the effort + +The queries the program targets have meaningful aggregate volume. Individual queries can be small (10 to 100 monthly searches each) as long as the aggregate across the set is large. + +The test. Pull the top 20 candidate queries from keyword research. Sum their volumes. If the aggregate is below 5,000 monthly searches, pSEO probably does not justify the build. If above 50,000, the volume case is strong. + +The illusion to watch for. Long-tail keywords that look reasonable in keyword tools but are not actually searched by humans. Permutation keywords (every adjective times every noun) often have keyword-tool volume because the tools generate the data; the queries themselves are dead. + +### 3. User intent is queryable + +The user's question can be answered through structured data presented well. Not through narrative explanation, judgment, or analysis the data cannot supply. + +Queryable intent examples. "Homes for sale in [neighborhood]" answered by listing data. "Software engineer salary at [company]" answered by salary data. "Restaurants near [landmark]" answered by location and rating data. + +Non-queryable intent examples. "Should I buy a house in [neighborhood]" requires personal financial judgment. "Why is Y better than X" requires editorial argumentation. "How do I choose [thing]" requires guidance. + +If the intent requires narrative, choose editorial. If the intent requires data presented well, choose pSEO. + +### 4. Update cadence aligns with query volatility + +Real estate listings update daily; the data feed updates daily; pSEO refresh aligns with the volatility. "Best [thing] for [year]" pages get stale annually; the refresh cadence is annual. + +The test. Match the data's update frequency to the query's volatility. If the data is static (geographic features, founding dates) and the queries are stable, low maintenance. If the data shifts daily and the queries reward freshness, daily refresh. + +The trap. Underestimating refresh effort at design time. A team designs for "annual refresh" because that feels reasonable, ships 50,000 pages, and discovers the refresh requires 2 FTE for 6 weeks every year. The cadence was real; the resourcing was not. + +### 5. Quality control is operationally feasible + +Headcount is budgeted to sample-audit the set, fix failures, and maintain quality. Not aspirationally; in actual hours allocated. + +The rule of thumb. A 10,000-page set requires roughly 0.5 to 1.0 FTE of ongoing quality control. A 100,000-page set requires 2 to 4 FTE. If the budget cannot absorb the QC headcount, the program will degrade within 12 months of launch. + +--- + +## Worked examples + +### Example 1: real estate listings (yes) + +A regional brokerage considering pSEO for "homes for sale in [neighborhood]" pages. + +- Real underlying data: yes. MLS feeds with 30+ fields per listing. +- Long-tail volume: yes. Each neighborhood query has 50 to 500 monthly searches; aggregate across 200 neighborhoods is significant. +- Queryable intent: yes. Buyers want listings. +- Update cadence: data updates hourly; pSEO refresh aligns daily; manageable. +- QC feasible: yes; the brokerage already has data ops headcount. + +Decision: yes. This is the canonical pSEO use case. + +### Example 2: SaaS comparison pages (maybe) + +A B2B SaaS considering "X vs Y" pages for every competitor combination. + +- Real underlying data: judgment call. If the comparison data is licensed (G2 reviews, feature databases) or first-party (the team's actual evaluation), yes. If the data is "scraped competitor websites plus AI summary," no. +- Long-tail volume: yes for major competitors; thin for niche ones. +- Queryable intent: yes for "X vs Y," but readers often want narrative judgment ("which is better for my use case") that data alone cannot supply. +- Update cadence: feature databases drift; quarterly refresh required. +- QC feasible: depends on team size. + +Decision: maybe, leaning yes if the team commits to combining structured comparison data with brief editorial analysis per page. Pure-data comparison pages tend to underperform pages that include the analytical layer. + +### Example 3: AI-generated city guides (no) + +A travel content site considering "things to do in [city]" pSEO across 5,000 cities. + +- Real underlying data: no. The plan is "AI-generate the content from public sources." Anyone can replicate. +- Long-tail volume: yes for major cities; thin for small ones. +- Queryable intent: yes, but the queries reward editorial depth (curation, recommendations, taste). +- Update cadence: events change weekly; the AI-generated approach cannot match. +- QC feasible: no; "AI-generate 5,000 pages" is the plan because QC was not budgeted. + +Decision: no. This is the pattern that produces penalty-bait. Either invest in real expert-curated data or pursue editorial content for the highest-volume cities only. + +### Example 4: enterprise B2B pricing pages (no) + +An enterprise B2B SaaS considering "pricing for [industry] companies" pSEO across 50 industries. + +- Real underlying data: no. Pricing for enterprise SaaS is typically negotiated; there is no structured data feed to render. +- Long-tail volume: yes for some industries. +- Queryable intent: no. Buyers want a sales conversation, not a price table. +- Update cadence: not relevant. +- QC feasible: not relevant. + +Decision: no. The intent is not queryable. Editorial content explaining the buying process plus a sales-led conversion path is the right approach, not pSEO. + +--- + +## When two of five criteria fail, walk away + +If two or more criteria fail, walk away from the pSEO idea. The temptation is to start anyway and "improve as you go," but pSEO programs that launch with weak foundations rarely recover. The data depth, the QC budget, and the refresh cadence are designed in or they are missing forever. + +If exactly one criterion fails, see whether a smaller scope resolves the failure. "5,000 pages across all cities" failing on data depth might become "500 pages across major cities with expert-curated depth" that succeeds on all five criteria. diff --git a/skills/qa-testing/SKILL.md b/skills/qa-testing/SKILL.md new file mode 100644 index 0000000..22a57a5 --- /dev/null +++ b/skills/qa-testing/SKILL.md @@ -0,0 +1,294 @@ +--- +name: qa-testing +description: "Run QA testing on a page, feature, or full site at one of three depth tiers (smoke, standard, full). Use this skill whenever the user asks to test a page, audit a site, check for bugs, verify a deploy, run a QA sweep, or review accessibility, performance, or SEO basics. Triggers on test, QA, audit, verify, check, is it working, does it look right, broken, 404, image not loading, post-deploy check, regression test. Also triggers proactively after any significant code change or new page launch where verification matters." +category: qa +catalog_summary: "Pre-launch QA, regression testing, cross-browser checks" +display_order: 1 +--- + +# QA Testing + +Verify that a page, feature, or site is working before declaring it shipped. Stack-agnostic. Console-snippet driven for speed. + +This skill is faster than `accessibility-audit` (which goes deeper on WCAG) and `performance-optimization` (which goes deeper on Core Web Vitals). Use this skill for general QA. Use the specialists for deep audits. + +--- + +## When to use + +- After every deploy (smoke test) +- After launching a new page or feature (standard audit) +- Before a major release (full release matrix) +- Investigating a "something looks off" report +- Pre-launch verification of a site or section + +## When NOT to use + +- Deep accessibility compliance work (use `accessibility-audit`) +- Deep performance investigation (use `performance-optimization`) +- Code review or debugging (use `code-review-web`) +- Initial site setup or technical SEO baseline (use `seo-technical`) + +--- + +## Required inputs + +- The page URL or site under test +- The tier of QA needed (smoke, standard, or full) +- Browser dev tools access +- Any specific concerns to check beyond the standard tier + +--- + +## The framework: 3 tiers + +QA scales with the stakes. Pick the tier that matches the context. + +\| Tier \| When to run \| Time \| Coverage \| +\|---\|---\|---\|---\| +\| Smoke \| After every deploy \| 2 minutes \| Critical signals only \| +\| Standard \| New page or feature \| 10 minutes \| On-page basics, accessibility, structure \| +\| Full \| Major release, pre-launch \| 30+ minutes \| Comprehensive across all dimensions \| + +### Tier 1: Smoke test + +The 2-minute "did the deploy break anything obvious?" check. Run after every deploy. + +Console snippet (paste in browser dev tools): + +```javascript +const smoke = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + h1Count: document.querySelectorAll('h1').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { try { return JSON.parse(s.innerText)['@type'] } catch(e) { return 'invalid' } }), + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete \|\| i.naturalWidth === 0).length, +}; +console.log(JSON.stringify(smoke, null, 2)); +``` + +Pass criteria: +- Title exists and is 30 to 60 characters +- Canonical points at the production domain (never staging or preview URLs) +- Exactly one H1 +- Zero missing alts +- Zero broken images +- Schema includes the expected types for the page + +If any of these fail, do not proceed with deeper testing until the smoke issue is fixed. + +### Tier 2: Standard page audit + +The 10-minute new-page-or-feature audit. Covers the on-page basics plus accessibility and structure. + +Console snippet: + +```javascript +const audit = { + title: document.title, + titleLen: document.title.length, + canonical: document.querySelector('link[rel="canonical"]')?.href, + metaDesc: document.querySelector('meta[name="description"]')?.content, + metaDescLen: document.querySelector('meta[name="description"]')?.content?.length, + ogImage: document.querySelector('meta[property="og:image"]')?.content, + ogTitle: document.querySelector('meta[property="og:title"]')?.content, + twitterCard: document.querySelector('meta[name="twitter:card"]')?.content, + h1Count: document.querySelectorAll('h1').length, + h1Text: document.querySelector('h1')?.innerText, + h2Count: document.querySelectorAll('h2').length, + h2s: [...document.querySelectorAll('h2')].map(h => h.innerText.trim().slice(0, 60)), + totalImages: document.querySelectorAll('img').length, + missingAlts: [...document.querySelectorAll('img')].filter(i => !i.alt).length, + brokenImages: [...document.querySelectorAll('img')].filter(i => !i.complete \|\| i.naturalWidth === 0).length, + externalLinksWithoutNoopener: [...document.querySelectorAll('a[target="_blank"]')] + .filter(a => !a.rel?.includes('noopener')).length, + schema: [...document.querySelectorAll('script[type="application/ld+json"]')] + .map(s => { + try { + const d = JSON.parse(s.innerText); + return d['@graph'] ? d['@graph'].map(x => x['@type']) : d['@type']; + } catch(e) { return 'invalid' } + }), + hasSkipLink: !!document.querySelector('a[href^="#"]:first-of-type'), + pageLanguage: document.documentElement.lang \|\| 'NOT SET', + hasFavicon: !!document.querySelector('link[rel="icon"]'), +}; +console.log(JSON.stringify(audit, null, 2)); +``` + +Pass criteria* (in addition to smoke): +- Meta description: 120 to 160 characters +- og:image, og:title, twitter:card present +- H2s present and descriptive +- All external links with `target="_blank"` have `rel="noopener"` +- Page language declared (`lang` attribute on `<html>`) +- Favicon present + +### Tier 3: Full release matrix + +The 30-minute pre-launch check. Cover all dimensions. + +\| Dimension \| Pass criteria \| +\|---\|---\| +\| Smoke and standard \| All pass \| +\| Accessibility (basic) \| Run browser audit tool (e.g., Lighthouse), score above 90 \| +\| Performance (basic) \| Lighthouse Performance score above 80, LCP under 2.5s, CLS under 0.1 \| +\| Mobile responsiveness \| Tested at 375px, 768px, 1024px, 1440px \| +\| Cross-browser \| Tested in Chrome, Safari, Firefox (and Edge if relevant audience) \| +\| Forms \| All forms submit successfully and validate correctly \| +\| Internal links \| No broken internal links (sample 20 random) \| +\| External links \| All return 200 (sample 10) \| +\| Sitemap \| Returns 200, lists canonical URLs only \| +\| robots.txt \| Allows production crawlers, blocks staging if applicable \| +\| Security headers \| HSTS, X-Frame-Options, X-Content-Type-Options present \| +\| HTTPS \| All resources load over HTTPS, no mixed content \| +\| 404 handling \| 404 pages return HTTP 404 (not soft 200) \| +\| Schema validation \| All schema validates in Rich Results Test \| +\| Analytics \| Events fire as expected on key user actions \| +\| Cache behavior \| Cache headers appropriate for page type \| + +For headers, run: + +```javascript +fetch(window.location.origin, { method: 'HEAD' }) + .then(r => { + const headers = {}; + for (const [k, v] of r.headers.entries()) headers[k] = v; + console.log(JSON.stringify(headers, null, 2)); + }); +``` + +Look for: `strict-transport-security`, `x-frame-options`, `x-content-type-options`. + +--- + +## Specific QA snippets + +### Image audit + +```javascript +const imgs = [...document.querySelectorAll('img')].map(i => ({ + src: i.src.split('/').pop().split('?')[0].slice(0, 60), + alt: i.alt \|\| 'MISSING', + width: i.naturalWidth, + height: i.naturalHeight, + loaded: i.complete && i.naturalWidth > 0, +})); +console.table(imgs); +console.log({ + total: imgs.length, + broken: imgs.filter(i => !i.loaded).length, + noAlt: imgs.filter(i => i.alt === 'MISSING').length, +}); +``` + +### Heading hierarchy check + +```javascript +const headings = [...document.querySelectorAll('h1, h2, h3, h4, h5, h6')].map(h => ({ + level: parseInt(h.tagName[1]), + text: h.innerText.trim().slice(0, 80), +})); +console.table(headings); + +// Check for skipped levels +const levels = headings.map(h => h.level); +let skipped = false; +for (let i = 1; i < levels.length; i++) { + if (levels[i] > levels[i-1] + 1) { + console.warn(`Skipped from H${levels[i-1]} to H${levels[i]}: "${headings[i].text}"`); + skipped = true; + } +} +if (!skipped) console.log('No skipped heading levels'); +``` + +### Contrast spot-check + +```javascript +function contrast(bg, fg) { + function lum(hex) { + return [hex.slice(1,3), hex.slice(3,5), hex.slice(5,7)] + .map(h => parseInt(h, 16) / 255) + .map(v => v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4)) + .reduce((a, v, i) => a + v * [0.2126, 0.7152, 0.0722][i], 0); + } + const [l1, l2] = [lum(bg), lum(fg)]; + const r = ((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2); + return r + ':1 ' + (parseFloat(r) >= 4.5 ? 'PASS body' : parseFloat(r) >= 3 ? 'PASS large only' : 'FAIL'); +} + +// Examples +contrast('#FFFFFF', '#4B5563'); // body color check +contrast('#FFFFFF', '#9CA3AF'); // verify gray choices +``` + +### Form audit (per form) + +```javascript +[...document.querySelectorAll('form')].forEach((form, i) => { + const fields = [...form.querySelectorAll('input, select, textarea')].map(field => ({ + type: field.type \|\| field.tagName.toLowerCase(), + name: field.name, + hasLabel: !!form.querySelector(`label[for="${field.id}"]`) \|\| !!field.closest('label'), + required: field.required, + })); + console.log(`Form ${i + 1}:`); + console.table(fields); +}); +``` + +### External link audit + +```javascript +const externalLinks = [...document.querySelectorAll('a[href^="http"]')] + .filter(a => !a.href.includes(window.location.host)); +const issues = externalLinks.filter(a => + a.target === '_blank' && (!a.rel?.includes('noopener') \|\| !a.rel?.includes('noreferrer')) +); +if (issues.length) { + console.warn(`${issues.length} external links missing noopener/noreferrer:`); + issues.forEach(a => console.warn(a.href)); +} else { + console.log(`All ${externalLinks.length} external links properly attributed`); +} +``` + +--- + +## Workflow + +1. Pick the tier. Smoke for routine deploys. Standard for new work. Full for releases. +2. Run the snippet. Paste the appropriate console snippet, review output. +3. Note failures. Each failure either gets fixed before ship or filed as a known issue. +4. For Standard tier, add: visual review at 375px, 768px, 1440px. Test the primary user flow. +5. For Full tier, add: cross-browser testing, Lighthouse audit, schema validation, security headers, 404 handling. +6. Document. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md) for full audits. + +--- + +## Failure patterns + +- Skipping smoke tests on "small" deploys. Half of broken-production incidents start with a deploy that "looked safe." +- Running snippets but not reading the output. The console snippet is a tool. The judgment is reading what it returns. +- Visual-only QA. Eyeballing a page misses missing alt text, broken schema, missing canonical. Always run the snippet. +- Single-browser testing. Mobile Safari and Chrome differ enough to surprise you. Test at least Chrome and Safari. +- No mobile QA. The 375px viewport is where most users live. Test there or get burned later. +- Pass-fail with no remediation. A failed QA must produce a fix or a known-issue ticket. Failed QA that ships unfixed is process theater. + +--- + +## Output format + +For smoke tests: console output is the report. + +For standard and full audits: a markdown report at `qa-report-[date].md`. Use the template in [`references/qa-report-template.md`](references/qa-report-template.md). + +--- + +## Reference files + +- [`references/qa-report-template.md`](references/qa-report-template.md) - Markdown report template for standard and full audits. diff --git a/skills/qa-testing/references/qa-report-template.md b/skills/qa-testing/references/qa-report-template.md new file mode 100644 index 0000000..91b7bdd --- /dev/null +++ b/skills/qa-testing/references/qa-report-template.md @@ -0,0 +1,200 @@ +# QA Report: [Page or Site URL] + +Date: [YYYY-MM-DD] +Tier: [Smoke / Standard / Full] +Tester: [Name] +Browser(s): [List] +Device(s): [Desktop, mobile device, viewport width] + +--- + +## Summary + +Overall: [Pass / Pass with minor issues / Fail] + +[1 to 3 sentences. The headline finding. What works, what's broken, what to do.] + +Critical issues found: [N] +Important issues found: [N] +Minor issues found: [N] + +--- + +## Smoke check + +\| Check \| Pass \| Notes \| +\|---\|---\|---\| +\| Title tag present and 30-60 chars \| ☐ \| \| +\| Canonical = production URL \| ☐ \| \| +\| Exactly one H1 \| ☐ \| \| +\| Zero missing image alts \| ☐ \| \| +\| Zero broken images \| ☐ \| \| +\| Schema present and valid \| ☐ \| \| + +--- + +## Standard audit (if applicable) + +### Meta tags +\| Field \| Value \| Pass \| +\|---\|---\|---\| +\| Title \| \| ☐ \| +\| Title length \| \| ☐ \| +\| Meta description \| \| ☐ \| +\| Meta description length \| \| ☐ \| +\| og:image \| \| ☐ \| +\| og:title \| \| ☐ \| +\| twitter:card \| \| ☐ \| + +### Structure +\| Check \| Result \| Pass \| +\|---\|---\|---\| +\| H1 text \| \| ☐ \| +\| H2 count \| \| ☐ \| +\| Skipped heading levels \| \| ☐ \| +\| Page language declared \| \| ☐ \| +\| Favicon present \| \| ☐ \| + +### Images +\| Check \| Count \| +\|---\|---\| +\| Total images \| \| +\| Broken images \| \| +\| Missing alt text \| \| + +### Links +\| Check \| Count \| +\|---\|---\| +\| External links \| \| +\| External missing `noopener` \| \| + +### Schema +[List schema types found and any validation issues] + +--- + +## Full release matrix (if applicable) + +### Accessibility +- [ ] Lighthouse Accessibility score above 90 (actual: __) +- [ ] No skipped heading levels +- [ ] All form fields have labels +- [ ] Skip link present +- [ ] Page operable by keyboard alone +- [ ] Focus indicators visible + +### Performance +- [ ] Lighthouse Performance score above 80 (actual: __) +- [ ] LCP under 2.5s (actual: __) +- [ ] CLS under 0.1 (actual: __) +- [ ] INP under 200ms (actual: __) + +### Mobile responsiveness +- [ ] 375px viewport: layout intact, no horizontal scroll +- [ ] 768px viewport: layout adapts cleanly +- [ ] 1024px viewport: desktop variant works +- [ ] 1440px viewport: max-width holds, no awkward stretch +- [ ] Tap targets minimum 44px + +### Cross-browser +- [ ] Chrome: tested +- [ ] Safari: tested +- [ ] Firefox: tested +- [ ] Edge: tested (if relevant audience) +- [ ] Mobile Safari: tested +- [ ] Mobile Chrome: tested + +### Forms +- [ ] All forms submit successfully +- [ ] Validation works as expected +- [ ] Error states display clearly +- [ ] Success states display clearly + +### Links +- [ ] No broken internal links (sample of 20 tested) +- [ ] No broken external links (sample of 10 tested) + +### Site infrastructure +- [ ] Sitemap returns 200 and lists canonical URLs +- [ ] robots.txt correct (allows production, blocks staging) +- [ ] HTTPS on all resources, no mixed content +- [ ] HSTS header present +- [ ] X-Frame-Options header present +- [ ] X-Content-Type-Options header present + +### 404 handling +- [ ] 404 pages return HTTP 404 (not 200) +- [ ] 404 page provides helpful navigation + +### Schema +- [ ] All schema validates in Rich Results Test +- [ ] Required properties filled +- [ ] No mixed signals (canonical vs sitemap vs internal links) + +### Analytics +- [ ] Page view fires correctly +- [ ] Key events fire on user actions +- [ ] No PII in event parameters + +### Cache behavior +- [ ] Cache headers appropriate for page type +- [ ] No stale content displayed +- [ ] Cache invalidation works after content updates + +--- + +## Critical issues + +[Things that block ship.] + +### 1. [Issue title] +- Where: [URL or component] +- What: [What's broken] +- Impact: [Who is affected] +- Fix: [Specific remediation] + +### 2. [Issue title] +[Same structure] + +--- + +## Important issues + +[Things that should be fixed but might not block ship.] + +### 1. [Issue title] +- Where: +- What: +- Impact: +- Fix: + +--- + +## Minor issues + +[Polish items.] + +- [Issue] +- [Issue] +- [Issue] + +--- + +## Recommendations + +[Suggestions beyond fixing the identified issues.] + +- [Recommendation] +- [Recommendation] + +--- + +## Sign-off + +- [ ] All critical issues resolved +- [ ] Important issues resolved or have known-issue tickets +- [ ] Minor issues acknowledged + +Approved for ship: [Yes / No / Conditional] +Approved by: [Name] +Date: [YYYY-MM-DD] diff --git a/skills/quiz-and-assessment-design/SKILL.md b/skills/quiz-and-assessment-design/SKILL.md new file mode 100644 index 0000000..d364cea --- /dev/null +++ b/skills/quiz-and-assessment-design/SKILL.md @@ -0,0 +1,283 @@ +--- +name: quiz-and-assessment-design +description: "Designing quizzes, personality assessments, and recommendation tools that segment users into actionable categories rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping, lead capture integration. Honest about clickbait-quiz (engagement only), vanity-result (entertaining, not useful), and actionable-segmentation (genuine categorization that drives next-step recommendations) patterns. Triggers on quiz, assessment, personality test, recommendation tool, scorecard, diagnostic, fit evaluator, what-type-of-X-are-you, persona quiz. Also triggers when an audience needs a categorization-driven lead magnet, when a vanity quiz is producing engagement but no qualified leads, or when an assessment is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing quizzes and assessments that produce actionable segmentation. Distinguishes clickbait-quiz (engagement only) from vanity-result (entertaining, not useful) from actionable-segmentation (genuine categorization that drives next-step recommendations)" +display_order: 3 +--- + +# Quiz and Assessment Design + +A senior growth practitioner's playbook for designing quizzes and assessments that produce actionable segmentation rather than generating clicks for clicks' sake. Question architecture, scoring algorithms, result categorization, recommendation mapping. The discipline of building a quiz the audience actually uses to make a decision. + +Most quizzes on the web are clickbait. "What kind of pizza are you?" energy applied to brand-building, with results that flatter the taker but drive no specific next step. The quiz captures emails because the format implies fun; the leads are unqualified because the result told them nothing they could act on. + +The quizzes that work as compounding assets do something different. They categorize the taker into a defined segment with a specific recommendation matched to that segment. The taker comes away knowing what to do next, not just what they are. The brand becomes the source of the recommendation the audience acted on. + +This skill is one of the specific lead-magnet types covered as its own skill. The parent-frame methodology lives in `lead-magnet-design`; the quiz-specific methodology (scoring algorithms, result categorization, recommendation matching) lives here. + +The voice is the senior growth practitioner who has watched quizzes earn long-term subscribers and watched them produce engagement metrics with no downstream impact. Practical, opinionated about the difference between fun-quiz and decision-quiz, willing to call out when a quiz is the wrong format for the goal. + +When to use this skill: scoping a quiz or assessment for the first time, auditing a quiz that produces engagement but no qualified leads, designing the result categories that drive specific recommendations, or deciding which inputs warrant the lead-capture step. + +--- + +## What this skill covers + +This skill spans quiz and assessment design as one specific lead-magnet type. The growth-tooling distinctions: + +- `lead-magnet-design` is the parent-frame methodology. Quizzes are one specific lead-magnet type. +- `calculator-design` is a sister tool type. Calculators give numbers; quizzes give categories. The methodology differs. +- `quiz-and-assessment-design` (this skill) is quiz-specific methodology (question architecture, scoring algorithms, result categorization, recommendation matching). +- `discovery-research-synthesis` is customer-research synthesis (this skill is user-facing assessment, not internal research). +- `landing-page-copy` is the quiz landing page (downstream of quiz design). + +The audience: growth marketers, product marketers, content marketers, agencies running quiz-based growth tooling for clients. + +Out of scope: lead-magnet design at the parent-frame level (covered by `lead-magnet-design`); calculator design (covered by `calculator-design`); landing-page copy (covered by `landing-page-copy`); the engineering implementation of the quiz (handed off via `pm-spec-writing`). + +--- + +## The quiz/assessment decision: when this format earns investment + +Before designing the quiz, decide whether a quiz is the right tool for the audience and the goal. + +Quizzes earn investment when: + +- The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. +- The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation; 30 questions stops being a quiz and becomes a survey. +- The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation does not justify the format; the segment-recommendation mapping is the value. +- The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage; audiences who do not (technical buyers, enterprise) often see quizzes as gimmicks. + +Quizzes do NOT earn investment when: + +- The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. +- The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. +- The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. +- The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional; the format choice has to fit the audience. + +The decision is not "should we have a quiz"; it is "is the quiz the right next investment for this specific audience and decision." + +Detail in [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md). + +--- + +## Clickbait-quiz vs vanity-result vs actionable-segmentation + +The keystone framing. + +Clickbait-quiz. "What kind of pizza are you?" energy. Generates engagement (shares, comments, brief virality), segments nothing useful. Fun but not strategic. Cost: the engagement metric looks fine; the leads have no qualification signal because the quiz did not reveal anything actionable about them. + +Vanity-result. Elaborate-feeling result that flatters the taker but does not drive any specific next step. "You are an INTJ visionary entrepreneur" with a description that reads like horoscope, no actionable follow-up. Cost: the taker enjoyed the result, did not act on it, did not return. The quiz produced a moment of attention, not a relationship. + +Actionable-segmentation. Result places the taker into a defined category with a specific recommendation matched to that category. The result tells them what to DO next, not just what they ARE. The category and the recommendation are the value; the taker comes away with a next step. + +The litmus test. After taking the quiz, can a stranger in the target audience name the next thing they should do? Can they describe the recommendation matched to their result? If yes, the quiz is actionable-segmentation. If they got a flattering description with no clear next step, the quiz is vanity-result. If they got entertainment with no segmentation, the quiz is clickbait. + +--- + +## Question architecture + +The questions are the mechanism that produces the segmentation. Bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +Question count. Most effective quizzes use 5-10 questions. Fewer than 5 rarely produces meaningful segmentation; more than 12 stops feeling like a quiz and starts feeling like an interrogation. + +Question types. + +- Multiple-choice (single-select). The most common. Each option maps to a segment or scoring weight. +- Multiple-select. Useful when multiple attributes apply. Care needed; multi-select complicates scoring. +- Slider or scale. "On a scale of 1-5, how often do you..." Useful for intensity questions; less useful for categorical segmentation. +- Yes/no. Useful for binary qualifying questions; rarely produces nuanced segmentation alone. +- Free text. Avoid in quizzes. Free text breaks the scoring flow and adds friction. + +Question ordering. Start with engaging, low-friction questions. Save more revealing or sensitive questions for later when commitment has built. Demographic or qualifying questions belong at the end, not the start. + +Question phrasing. + +- Plain language. Avoid jargon. +- Specific situations the audience recognizes. +- Avoid leading questions ("How much do you struggle with X" presumes struggle). +- Avoid double-barreled questions ("How much do you value speed AND simplicity" mixes two dimensions). + +Question-segment mapping. Each question should contribute to the segmentation in a defined way. Questions that do not affect the result are filler; remove them. + +Detail in [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md). + +--- + +## Scoring algorithms + +The math that turns answers into a segment. + +Pattern A: Direct mapping. Each answer corresponds directly to a segment. The dominant answer choice determines the result. Simple, transparent, easy to explain. + +Pattern B: Weighted scoring. Each answer adds points to one or more segments. The highest-scoring segment wins. Allows for nuance; one answer can contribute to multiple segments. + +Pattern C: Multi-dimensional. The quiz produces scores across multiple axes (e.g., introvert/extrovert AND analytical/intuitive). The result combines the scores into a 2D or 3D segment. Common in personality assessments. + +Pattern D: Branching logic. The next question depends on the previous answer. Allows for adaptive questioning; complicates scoring. + +Choice criteria. + +- Direct mapping when the segments are well-defined and the questions clearly distinguish them. +- Weighted scoring when nuance matters and most answers contribute to multiple segments. +- Multi-dimensional when the segmentation is genuinely multi-axis (personality, fit-evaluation). +- Branching when later questions make sense only in the context of earlier answers. + +Scoring transparency. Some quizzes show the score during or after the quiz; others present only the segment. The choice depends on whether the score is meaningful to the user. Personality assessments benefit from showing dimensions; recommendation quizzes often do not. + +Detail in [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md). + +--- + +## Result categorization + +How many segments, named how, distinguishable from each other. + +Segment count. Most quizzes work well with 4-8 result categories. Fewer than 4 makes the categorization feel coarse; more than 8 makes individual segments feel under-developed. + +Segment naming. + +- Memorable. The taker should be able to describe their segment to a friend. +- Specific. "The Strategic Planner" beats "Type 3." +- Honest. Names should not flatter universally; some segments are more flattering than others, which is honest segmentation. +- Brand-voice consistent. The names should sound like the brand the quiz represents. + +Segment distinguishability. Each segment should be meaningfully different. If two segments have similar descriptions and similar recommendations, the segmentation is fake. + +Segment balance. The quiz should not always route 80 percent of takers to one segment. Balanced segmentation (each segment receives a meaningful share of takers) signals that the questions actually distinguish. + +Detail in [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md). + +--- + +## Result-to-recommendation mapping + +The action attached to each category. This is where the quiz earns its conversion. + +The principle. Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +Mapping examples. + +- B2B SaaS quiz: "Which CRM tier fits your team" maps each segment to a recommended plan. +- Content quiz: "What kind of marketer are you" maps each segment to a different content series matched to that maturity level. +- Onboarding quiz: "What is your readiness for X" maps each segment to a different onboarding path or resource. + +The recommendation has to be real. The brand should actually offer the recommended next step; the recommendation should match the segment specifically; the recommendation should be valuable to the segment. + +Mapping discipline. + +- Each segment has a distinct recommendation. No two segments share the same next step. +- Each recommendation is actionable. The taker can act on it without additional research. +- Each recommendation is valuable to that specific segment. Generic recommendations for one segment do not earn the segmentation. +- The recommendation is delivered in context of the result. Not buried 3 emails later. + +The vanity-result failure. Result describes the segment without a recommendation. "You are a Strategic Planner" with a description but no next step. The taker enjoys the segment, does nothing. + +The actionable-segmentation win. Result describes the segment, then says: "Strategic Planners benefit most from [specific resource or product or path]. Here is the next step." The taker has a specific action. + +Detail in [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md). + +--- + +## Lead capture integration + +When and where to ask for the email, with what value-add. + +The principle. Capture the email in exchange for the personalized result delivery, not in exchange for seeing the result at all. + +Pattern A: Email after questions, before result. "Enter your email to see your personalized result." Common; works when the perceived value of the result is high. Risk: lead-trap pattern if the result was already calculated and is being held hostage. + +Pattern B: Email after result, for personalized delivery. "See your result here. Want a PDF with personalized recommendations matched to your segment? Enter your email." Honest; the result is free, the additional value justifies the email. + +Pattern C: Email integrated with optional features. "See your result. Save this scenario, get notified when new content for your segment is available, or download a personalized resource." Gradual opt-in; less aggressive. + +The value-add at lead capture. What the user gets for their email matters. A personalized PDF report, a follow-up email series matched to their segment, a curated resource list specific to their result. Generic delivery (just sending the same result by email) does not justify the gate. + +Conversion vs lead quality. Pattern A converts higher; Pattern B and C produce higher lead quality. Pattern choice depends on what the program optimizes for. + +Detail in [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md). + +--- + +## Quiz anti-patterns + +Patterns that look like quizzes but degrade trust. + +The clickbait-quiz. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you" with 4 personality types and no recommendations. + +The vanity-result quiz. Flattering descriptions for every segment; no honest segmentation; no specific recommendations. + +The forced-result quiz. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The interrogation-quiz. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The leading-question quiz. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The black-box quiz. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The no-recommendation quiz. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The mismatched-recommendation quiz. Recommendation does not match the segment. Audience that catches the mismatch loses trust. + +Detail in [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-quiz-failures.md`](references/common-quiz-failures.md). + +- "Quiz gets shared widely; lead quality is poor." Clickbait pattern; the audience taking and sharing is not the audience the brand serves. +- "Engagement is high; downstream conversion is near zero." Vanity-result pattern; takers enjoyed the segment but had no next step. +- "Most takers route to the same segment." Question architecture not distinguishing; algorithm needs review. +- "Drop-off mid-quiz is high." Too many questions; or questions feel uncomfortable; or the value of finishing is not clear. +- "Segments feel similar." Distinguishability problem; segments need more divergent descriptions and recommendations. +- "Recommendations feel generic." Mapping problem; each segment needs a specific recommendation, not a default. +- "We cannot tell which segment converts best downstream." Attribution missing; segments need tracking through the funnel. +- "Audience comments that the result was wrong." Either question or scoring problem; the segments do not match audience self-perception. + +--- + +## The framework: 12 considerations for quiz and assessment design + +When designing or auditing a quiz, walk these 12 considerations. + +1. The quiz decision. Is a quiz the right format for this audience and decision, or would a comparison table or assessment-as-content serve better? +2. Actionable-segmentation, not clickbait or vanity. The result places the taker into a category with a specific recommendation. +3. Question architecture sound. 5-12 questions; each contributes to segmentation; phrased plainly without leading. +4. Scoring algorithm fits the segmentation. Direct mapping, weighted scoring, multi-dimensional, or branching as appropriate. +5. Result categories distinguishable and balanced. 4-8 segments; each meaningfully different; each receives a meaningful share of takers. +6. Segment naming memorable and brand-consistent. Names the taker can describe to a friend. +7. Recommendations specific to each segment. No two segments share the same recommendation; each recommendation is valuable to that segment. +8. Lead capture honest. Email exchange for personalized delivery, not for seeing the result. +9. Result delivery in context. Recommendation appears with the result, not buried 3 emails later. +10. Drop-off measured. Question-by-question drop-off tracked; questions that lose audience flagged for review. +11. Lead quality measured by segment. Downstream conversion tracked per segment; some segments may be more valuable than others. +12. Audit cadence. Periodic review of segment balance, recommendation alignment, and conversion-by-segment. + +The output of the framework is a quiz that segments the audience meaningfully, produces specific recommendations, and converts the segments into action. + +--- + +## Reference files + +- [`references/quiz-investment-criteria.md`](references/quiz-investment-criteria.md) - When a quiz is the right tool for the audience and goal, and when a comparison table or other format would serve. +- [`references/question-architecture-patterns.md`](references/question-architecture-patterns.md) - Question count, types, ordering, phrasing, and segment mapping discipline. +- [`references/scoring-algorithm-patterns.md`](references/scoring-algorithm-patterns.md) - Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. +- [`references/result-categorization-patterns.md`](references/result-categorization-patterns.md) - Segment count, naming, distinguishability, balance. +- [`references/result-to-recommendation-mapping.md`](references/result-to-recommendation-mapping.md) - The action attached to each category. Mapping discipline and worked examples. +- [`references/lead-capture-integration-patterns.md`](references/lead-capture-integration-patterns.md) - When and where to ask for the email. Pattern choices and tradeoffs. +- [`references/quiz-anti-patterns.md`](references/quiz-anti-patterns.md) - The patterns that look like quizzes but degrade trust. +- [`references/clickbait-vs-actionable-distinctions.md`](references/clickbait-vs-actionable-distinctions.md) - Detailed treatment of the keystone framing with worked examples and counter-examples. +- [`references/common-quiz-failures.md`](references/common-quiz-failures.md) - 8+ failure patterns with diagnoses and cures. + +--- + +## Closing: quizzes earn engagement when they earn the next step + +The quizzes that work as compounding assets are the ones the audience acts on. Not shares. Not engagement metrics. Action. The taker runs the quiz, gets a segment with a matched recommendation, and does the recommendation. + +That is the bar. Below the bar are clickbait-quizzes (engagement without action) and vanity-results (flattery without action). Above the bar are actionable-segmentation tools that produce specific next steps the taker actually takes. + +The discipline is in the design choices. The questions that genuinely distinguish segments. The scoring algorithm that maps answers to meaningful categories. The recommendations that match each segment specifically. The result-delivery that surfaces the recommendation in context, not 3 emails later. diff --git a/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md b/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md new file mode 100644 index 0000000..43f8d87 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/clickbait-vs-actionable-distinctions.md @@ -0,0 +1,192 @@ +# Clickbait vs actionable distinctions + +Detailed treatment of the keystone framing with worked examples and counter-examples. The single distinction that separates quizzes that compound credibility from quizzes that produce engagement without action. + +--- + +## The three-state framing + +Three states a quiz can land in. Only one of them produces compounding value. + +State 1: Clickbait. The quiz exists primarily to generate engagement. "What kind of pizza are you?" energy. The result is fun but means nothing. No segmentation that maps to a decision. No recommendation. Engagement metrics look healthy; downstream metrics are zero. + +State 2: Vanity-result. The quiz produces a result that feels meaningful but does not drive action. "You are an INTJ visionary entrepreneur." The taker reads the description, may share it, does not act on it. The result is descriptive without being prescriptive. + +State 3: Actionable-segmentation. The quiz produces a result that includes a specific recommendation matched to that segment. The taker can act immediately on the recommendation. The result is both descriptive (this is who you are) and prescriptive (this is what to do next). + +The states are not always obvious from the outside. A quiz can look polished and still be vanity-result; a quiz can look simple and still be actionable-segmentation. The distinction is in the design, not the surface. + +--- + +## What separates the states + +The three differences that separate actionable-segmentation from the others. + +Difference 1: The result includes a recommendation. + +- Clickbait: result is a label or description. "You are a 'Strategic Visionary'." +- Vanity: result is an elaborate description. "You are a 'Strategic Visionary': big-picture thinker, comfortable with ambiguity, drawn to long-term impact..." +- Actionable: result is a description plus a recommendation. "You are a 'Strategic Visionary'. The next step that fits this profile: [specific resource, product, or path]." + +Difference 2: The recommendation is specific to the segment. + +- Clickbait: no recommendation, so the question does not apply. +- Vanity: every segment may get a similar generic next step ("read our blog"); the recommendation is decorative. +- Actionable: each segment gets a distinct recommendation matched to that segment specifically. + +Difference 3: The recommendation is actionable today. + +- Clickbait: no recommendation. +- Vanity: recommendation is aspirational ("consider whether you might be ready for X someday"). +- Actionable: recommendation is concrete and immediate ("start your trial here," "book a 30-minute call here," "download the playbook here"). + +The pattern. Clickbait has no recommendation. Vanity has decorative recommendation. Actionable has specific, matched, concrete recommendation. + +--- + +## Worked example: the same topic in three states + +A quiz on "what kind of marketer are you" treated three ways. + +Clickbait version. + +- 5 questions about content preferences and personality. +- Result: "You are 'The Storyteller'." Description: "Storytellers love narrative and connect deeply with their audience." +- Action: share the result. + +The taker enjoys the result, may share it, learns nothing actionable. The quiz produces engagement; the brand earns no qualified leads. + +Vanity-result version. + +- 8 questions about marketing approach, content, audience interaction. +- Result: "You are 'The Storyteller': a marketer who values narrative, audience connection, and emotional resonance. Storytellers thrive in brands that prioritize voice and depth..." +- Action: 3 paragraphs of description; soft CTA at the bottom: "Want more? Subscribe to our newsletter." + +The taker reads the elaborate description; may subscribe to the newsletter; does not take a specific action that converts. The quiz produces a moment of attention; the brand earns subscribers but no qualified leads. + +Actionable-segmentation version. + +- 7 questions about marketing approach, content, audience interaction, current tools, current challenges. +- Result: "You are 'The Storyteller'. Storytellers benefit most from our 4-part 'Brand Voice Workshop' series. Here is the first lesson; the next 3 arrive over the following week. Or, if you prefer, start with our 'Brand Voice Audit Template' [direct download]." +- Action: clear next step with two options matched to the segment's likely preference (sequence or self-serve). + +The taker gets a matched recommendation. The taker who wants the sequence opts in; the taker who wants the template downloads. Either way, action is taken; the brand earns a qualified lead. + +The same topic, three quizzes, three different outcomes. The actionable version compounds value; the others do not. + +--- + +## How to evaluate which state a quiz is in + +Diagnostic questions to apply to any quiz. + +Question 1: Does the result include a specific recommendation? + +- No: the quiz is clickbait or vanity. +- Yes: continue. + +Question 2: Does each segment have a distinct recommendation, or do all segments share the same recommendation? + +- All same: the quiz is forced-result; segmentation is decorative. +- Distinct: continue. + +Question 3: Is the recommendation actionable today? + +- No (aspirational, vague, "consider"): the quiz is vanity. +- Yes (specific link, button, or action): the quiz is actionable-segmentation. + +Question 4: Does the recommendation match the segment specifically (not a generic offer)? + +- No: the quiz is vanity with decorative recommendations. +- Yes: the quiz is actionable-segmentation. + +When all four questions get the right answer, the quiz is actionable-segmentation. When any fails, the quiz is somewhere between clickbait and vanity. + +--- + +## The compounding-value mechanism + +Why actionable-segmentation compounds and the others do not. + +Actionable-segmentation compounds. + +- The taker acts on the recommendation; the brand becomes the source of the action. +- The taker sees results from the action; the brand earns credit. +- The taker returns or refers; the brand's reach grows. +- The brand's recommendations become trusted; future quizzes earn more conversion. + +Clickbait does not compound. + +- The taker engages; the engagement does not convert. +- The brand's quiz is one of many forgotten amusements. +- No relationship deepens; no credibility builds. + +Vanity does not compound. + +- The taker enjoys; the enjoyment does not convert. +- The brand's quiz is one of many flattering distractions. +- The newsletter subscription (if any) decays without engagement. + +The compounding effect is the difference between quizzes that earn ongoing investment and quizzes that get retired. + +--- + +## Why teams build clickbait and vanity quizzes + +The patterns are easy to ship. Understanding why teams default to them helps teams choose actionable-segmentation instead. + +Reason 1: Engagement metrics are easier to measure. Conversion rate to email, share counts, time on page are all available immediately. Downstream conversion takes weeks or months to measure. Teams optimize what they measure. + +Reason 2: Designing recommendations is hard. Each segment needs a matched recommendation; the brand has to have the recommendations to give. Designing the segment-recommendation mapping is more work than designing the quiz alone. + +Reason 3: Templates default to clickbait. Many quiz-platform templates are designed for engagement, not for segmentation-driven action. Using a template often produces clickbait by default. + +Reason 4: The vanity-result feels safer. Flattering descriptions feel safer than honest segmentation; teams worry about "telling someone they are not a fit." Honest segmentation is harder but produces more trust. + +Reason 5: Short-term thinking. Engagement is immediate; downstream conversion is delayed. Teams optimizing for the next quarter default to engagement. + +The cure. Track downstream conversion as the primary metric. Build the recommendation portfolio before designing the quiz. Avoid templates that default to engagement. Practice honest segmentation. + +--- + +## Counter-example: when engagement is the goal + +Some quizzes are intentionally engagement-driven, and that is fine. + +The legitimate engagement-quiz. A consumer brand running a viral quiz to drive social shares and brand awareness. The goal is reach, not lead-capture. The quiz is intentionally entertainment. + +The pattern. Light, fun, shareable. No email gate. Result is shareable. Brand association is the value. + +Why this is fine. The brand has chosen reach as the metric. The quiz delivers on that goal. The quiz is not pretending to be something it is not. + +The discipline. Be honest about the goal. If the goal is engagement, do not pretend the quiz is for lead-capture; do not include a half-hearted email gate that produces neither real engagement nor real leads. + +The clickbait pattern fails when teams pretend it is something else. When teams own the engagement goal and design for it explicitly, the quiz can serve that goal well. + +--- + +## Common patterns by industry + +How clickbait, vanity, and actionable-segmentation play differently across industries. + +Consumer brands. Consumer brands often run engagement-quizzes successfully when the brand-association goal is the value. Lead-capture quizzes are harder; consumer audiences resist email gates more. + +B2B SaaS. B2B SaaS audiences expect actionable-segmentation. Clickbait and vanity are read as unprofessional. Actionable quizzes that route to specific plans or resources work well. + +Education and creators. Mixed. Some audiences engage with personality-style quizzes; some want practical assessment. The audience the brand serves determines which works. + +Enterprise. Enterprise audiences usually skip quizzes entirely. When they engage, only actionable-segmentation works; clickbait or vanity is read as unserious. + +Ecommerce. Recommendation quizzes ("which of our products fits you") work well as actionable-segmentation when the product portfolio supports it. + +The discipline. Match the quiz pattern to the audience expectation. Audiences that expect actionable-segmentation will reject anything else; audiences that engage with personality quizzes will not be converted by overly-formal segmentation. + +--- + +## Methodology-level choices that stay in the public skill + +The three-state framing. The three differences that separate actionable-segmentation from clickbait and vanity. The diagnostic questions. The compounding-value mechanism. Why teams default to clickbait and vanity. The counter-example for legitimate engagement-quizzes. Industry patterns. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. Specific recommendation portfolios. Specific tracking for downstream conversion per pattern. The team's measurement framework for engagement vs action. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/common-quiz-failures.md b/skills/quiz-and-assessment-design/references/common-quiz-failures.md new file mode 100644 index 0000000..a350ba8 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/common-quiz-failures.md @@ -0,0 +1,187 @@ +# Common quiz failures + +8+ failure patterns with diagnoses and cures. The patterns that surface as "the quiz did not produce qualified leads" or "engagement is high but nothing converts" or "we cannot tell if the quiz worked." + +--- + +## "Quiz gets shared widely; lead quality is poor." + +The diagnosis. Clickbait pattern. The audience taking and sharing is not the audience the brand serves; the quiz attracts engagement from a broader audience than the brand's target. + +The cure. Tighten the quiz's audience-fit. Specific titles, specific topics, specific recommendations matched to the brand's actual buyers. Detail in `references/quiz-investment-criteria.md` (recommendation-portfolio precondition) and `lead-magnet-design`'s audience-fit qualification. + +--- + +## "Engagement is high; downstream conversion is near zero." + +The diagnosis. Vanity-result pattern. Takers enjoyed the segment but had no next step. The quiz produced moments of attention without action. + +The cure. Add specific recommendations to each segment. Detail in `references/result-to-recommendation-mapping.md`. Each result page must include a clear next step. + +--- + +## "Most takers route to the same segment." + +The diagnosis. Question architecture not distinguishing. Either the questions do not actually capture differentiating signals, or the scoring algorithm biases toward one segment. + +The cure. Audit the question-segment mapping (`references/question-architecture-patterns.md`). Ensure each question contributes meaningfully to multiple segments. Audit the scoring weights for unintended bias. + +--- + +## "Drop-off mid-quiz is high." + +The diagnosis. Too many questions, or questions feel uncomfortable, or the value of finishing is not clear. + +The cure. Reduce question count if over 12. Audit questions for those that feel sensitive or repetitive. Add a progress indicator and a teaser of the result ("almost done; see your result next") to reduce late-stage drop-off. + +--- + +## "Segments feel similar." + +The diagnosis. Distinguishability problem. Either over-segmentation (more segments than the questions can support) or weak descriptions that do not differentiate. + +The cure. Reduce segment count to what the questions can distinguish (`references/result-categorization-patterns.md`). Strengthen the descriptions to make each segment meaningfully different. + +--- + +## "Recommendations feel generic." + +The diagnosis. Mapping problem. Each segment needs a specific recommendation, not a default. + +The cure. Audit the segment-to-recommendation mapping (`references/result-to-recommendation-mapping.md`). Verify each segment has a distinct, valuable, actionable recommendation. + +--- + +## "We cannot tell which segment converts best downstream." + +The diagnosis. Attribution missing. Segments need tracking through the funnel. + +The cure. Tag leads by segment at capture. Track downstream conversion per segment. The data informs which segments warrant continued investment and which segments may need different recommendations. + +--- + +## "Audience comments that the result was wrong." + +The diagnosis. Either question or scoring problem. The segments do not match audience self-perception. + +The cure. Persona testing. Have personas representing each segment take the quiz; verify each persona reaches the intended segment. Adjust questions or scoring weights to align. + +--- + +## "The quiz earns 5000 takers; the email list grows by 200." + +The diagnosis. Either the result is not perceived as valuable enough to opt in for additional value (Pattern B failure), or the email gate is for the result itself with no value-add (lead-trap risk). + +The cure. Design a substantive value-add for the email opt-in (PDF, sequence, resource). Make the value-add visible at the result. Detail in `references/lead-capture-integration-patterns.md`. + +--- + +## "We added a quiz; our other lead magnets stopped converting." + +The diagnosis. Cannibalization. The quiz absorbed the audience that previously converted via other magnets. + +The cure. This may not be a failure. If the quiz-sourced leads are higher quality than the previous magnets, the cannibalization is portfolio improvement. If not, the quiz may have replaced a working magnet with a worse one; audit and decide. + +--- + +## "Sales says quiz-sourced leads are low-fit." + +The diagnosis. Either the audience-fit at the quiz is wrong (the quiz attracts non-target audiences) or the recommendation-mapping routes audiences to wrong products. + +The cure. First, audit the audience-fit. If the quiz is attracting the wrong audience, tighten the targeting (title, topic, distribution channels). Second, audit the recommendation-mapping. If the audience-fit is right but the recommendation is wrong, fix the mapping. + +--- + +## "The quiz looks great; nobody completes it." + +The diagnosis. Either the topic does not engage the audience (audience-fit weak) or the question count is too high (drop-off too early). + +The cure. First, validate the topic with audience research. If the topic is right, audit the question count and question phrasing. + +--- + +## "Engagement was great at launch; conversion has dropped 40 percent over a year." + +The diagnosis. Decay. Recommendations have shifted; segments have evolved; references are stale. + +The cure. Audit and refresh. Update recommendations to match current portfolio; verify segments still describe the audience accurately; refresh any stale references in question phrasing or result descriptions. + +--- + +## "We made the quiz shorter; conversion went up but downstream conversion went down." + +The diagnosis. Question removal removed differentiating signals. The quiz now produces engagement faster but the segmentation is weaker. + +The cure. Restore the questions that contributed to segmentation. Speed-of-completion is a metric; segmentation quality is a separate metric. Optimize for the right one. + +--- + +## "The result page is fine; the email follow-up sequence converts terribly." + +The diagnosis. Sequence does not match the segment. Either the sequence is generic across segments, or the sequence does not deepen the matched recommendation. + +The cure. Design segment-specific sequences (or at least segment-specific opening emails). The sequence should extend the result's recommendation, not start over with generic content. + +--- + +## "We tried branching logic; the quiz felt confusing." + +The diagnosis. Branching added complexity without value. Different takers got different question sets; comparison across takers became hard. + +The cure. Revert to linear quiz unless branching is genuinely warranted. The simplicity often produces better outcomes. + +--- + +## "The quiz works on Chrome; it breaks on Safari mobile." + +The diagnosis. Browser/device-specific bugs. The quiz was tested on the team's primary platform; the audience's actual devices were not covered. + +The cure. Cross-browser, cross-device testing. The audience uses what they use; the quiz has to work there. + +--- + +## "The recommendation links to a product we discontinued." + +The diagnosis. Maintenance lapse. The quiz's recommendation drifted out of sync with the brand's actual offering. + +The cure. Set a maintenance trigger: when products are discontinued or pricing changes, the quiz updates are part of the change. Quarterly review at minimum. + +--- + +## "Audiences take the quiz multiple times to get different results." + +The diagnosis. This is fine, often. Audiences exploring the segmentation may take it multiple times to understand how the algorithm works. Track unique users vs total completions. + +The action. Make sure the algorithm is stable enough that repeated takes with consistent answers produce consistent results. Inconsistency at this level signals algorithm issues. + +--- + +## "The quiz produces good leads; the sales team does not follow up." + +The diagnosis. Sequence or routing missing. Quiz-sourced leads should be tagged, routed to sales, and prioritized appropriately. + +The cure. Design the post-conversion flow. Calculator-sourced leads should be tagged with their segment, routed to the appropriate sales rep, and the sales rep should know which segment the lead represents. + +--- + +## The pattern across failures + +Most quiz failures fall into one of three patterns. + +Pattern 1: The quiz does not deliver actionable segmentation. Clickbait, vanity-result, no-recommendation, mismatched-recommendation. The fix is to add or correct the recommendations. + +Pattern 2: The quiz does not match the audience. Audience-fit weak, topic-audience mismatch, format-audience mismatch (e.g., quizzes for enterprise audiences who reject the format). The fix is to align the quiz to the audience the brand serves. + +Pattern 3: The quiz decays. Recommendations point to retired products; segments no longer describe the audience; references are stale. The fix is maintenance discipline. + +The metric pattern: quiz failures often look fine on engagement metrics. The signal is in lead quality, downstream conversion, and audience self-recognition. Programs that track only engagement keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (delivery, audience-fit, decay). The principle that engagement alone is insufficient as a success metric. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered and the lessons learned. Specific multi-metric dashboards the team uses. Specific cures the team applies. The team's audit and retirement processes. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md b/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md new file mode 100644 index 0000000..d10544c --- /dev/null +++ b/skills/quiz-and-assessment-design/references/lead-capture-integration-patterns.md @@ -0,0 +1,240 @@ +# Lead capture integration patterns + +When and where to ask for the email. Pattern choices and tradeoffs. The decision that affects both conversion and lead quality. + +The lead-capture integration is where the quiz earns its email. Done well, the audience opts in for personalized value; done poorly, the quiz becomes a lead-trap that the audience resents. + +--- + +## The capture-honest principle + +Capture the email in exchange for personalized result delivery, not in exchange for seeing the result at all. + +The honest pattern. The taker completes the quiz; the result is shown; an offer is made for additional value (PDF, follow-up sequence, saved scenario) that requires the email. + +The dishonest pattern. The taker completes the quiz; the result is calculated but hidden; the email is required to reveal it. This is the lead-trap pattern (described in `calculator-design`'s email-capture-decision-tree but applies equally to quizzes). + +--- + +## Pattern A: Email after questions, before result + +The taker completes the quiz; before the result is shown, an email gate appears. + +How it works. + +- The taker answers all questions. +- A form appears: "Enter your email to see your personalized result." +- The taker enters email; the result is shown. + +Strengths. + +- Highest conversion to email opt-in. +- Common pattern; audiences are familiar. + +Weaknesses. + +- Lead-trap pattern. The audience that recognizes the manipulation feels resentment. +- Lead quality is lower; some takers enter throwaway emails. +- Downstream conversion suffers because some leads are unqualified or actively annoyed. + +When to use. When the quiz is genuinely entertainment-driven and the audience expects the format (consumer brands sometimes work here). For B2B and considered purchases, this pattern often degrades trust. + +--- + +## Pattern B: Email after result, for personalized delivery + +The result is shown; an offer is made for personalized PDF or follow-up. + +How it works. + +- The taker answers all questions. +- The result is shown immediately, including segment description and matched recommendation. +- Below or alongside the result, an offer: "Want this as a PDF you can share?" or "Want a personalized 5-day sequence with deeper resources for your segment?" +- The taker who wants the additional value enters email. + +Strengths. + +- Honest. The audience gets what they came for. +- Lead quality is higher; takers who opt in are signaling real interest. +- Trust is preserved; audience that does not opt in still leaves with positive brand association. + +Weaknesses. + +- Lower conversion rate to email than Pattern A. +- Requires designing additional value (PDF, sequence) that justifies the email. + +When to use. Default pattern for B2B and considered purchases. The honest exchange compounds trust over time. + +--- + +## Pattern C: Email integrated with optional features + +The result is shown; multiple optional opt-ins are offered. + +How it works. + +- The taker answers all questions. +- The result is shown. +- Multiple opt-in options appear, each with distinct value: "Save this scenario for later," "Get notified when new content for your segment is available," "Download a personalized resource." +- The taker chooses which (if any) to opt into. + +Strengths. + +- Most flexibility for the audience. +- Allows different audience segments to engage at different levels. +- Lead quality is high because each opt-in is for specific value. + +Weaknesses. + +- More complex to design and implement. +- Multiple options can dilute conversion ("paradox of choice"). +- Requires the brand to actually deliver on each opt-in. + +When to use. When the quiz has multiple legitimate value-add follow-ups and the audience benefits from choice. + +--- + +## Pattern D: Progressive opt-in across the quiz + +Email is captured early but only used after the quiz completes. + +How it works. + +- The quiz starts with optional email entry ("get a personalized PDF report when you finish"). +- Takers can enter email upfront or skip. +- The quiz proceeds; the result is shown for everyone. +- Takers who entered email get the PDF; others see the result and an opt-in offer. + +Strengths. + +- Captures highly committed takers early. +- Does not gate the result. +- Provides a soft opt-in path for less-committed takers. + +Weaknesses. + +- Asking for email upfront can depress quiz starts. +- Two-path design (email-given vs not-given) adds complexity. + +When to use. When the audience benefits from setting expectations upfront and when the brand can deliver value differently to opted-in vs walk-up takers. + +--- + +## The value-add at lead capture + +What the user gets for their email matters as much as when the email is asked. + +Strong value-adds. + +- A personalized PDF report matched to the segment. +- A follow-up email series that deepens the segment-matched content. +- A curated resource list specific to the result. +- Notifications about new resources, products, or events relevant to the segment. + +Weak value-adds. + +- Just sending the same result by email (no value-add over what is on screen). +- A generic newsletter signup (not personalized to the result). +- A "join our community" offer with no clear value. + +The discipline. The value-add should be substantively better than what the audience saw on screen. If it is not, the email gate is not justified. + +--- + +## Conversion vs lead quality + +The patterns trade off these two metrics. + +Conversion-optimized. Pattern A captures the most emails but produces lower lead quality. Suitable when the goal is volume or when the audience is highly aligned (every taker is a target lead). + +Quality-optimized. Pattern B and C capture fewer emails but produce higher lead quality. Suitable when the goal is downstream conversion or when the audience is mixed (only some takers are target leads). + +The choice. Depends on what the program optimizes for. Brands optimizing for downstream revenue often choose Pattern B or C. Brands optimizing for list growth may default to Pattern A. + +The trap. Optimizing for conversion at the expense of lead quality is short-term thinking. The conversion metric looks fine; the downstream metrics suffer; the program quietly underperforms. + +--- + +## The "no email needed" alternative + +Some quizzes do not capture email at all. + +When this works. When the quiz's purpose is brand-building, SEO, or audience-engagement rather than lead-capture. The quiz's existence and shareability are the value; the email is incidental. + +The pattern. The taker takes the quiz; the result is shown; share buttons are prominent; no email gate. + +Why it can work. Some brands earn more from a widely-shared quiz than from a gated quiz that captures fewer emails. The brand association is the value. + +When it fails. When the program needs leads and the no-gate design produces nothing for the funnel. + +--- + +## Lead-capture form design + +The form itself matters. + +Field count. Email only is the strong default. Each additional field reduces conversion. + +Field justification. If additional fields are required (name for personalization, company for B2B sales context), justify them inline. "We use your name to personalize your follow-up" is honest; uncontextualized fields feel like sales-form padding. + +Form placement. Inline with the result is honest; popup that interrupts the result viewing is hostile. + +CTA copy. "Get my personalized PDF" beats "Submit." Specific value statement beats generic action. + +Loading state. After submission, show progress and confirm receipt. "Sending your PDF now... check your inbox in 2 minutes." + +--- + +## Post-capture experience + +What happens after the email is captured. + +Immediate delivery. The promised PDF, sequence, or resource arrives within minutes. Delays break trust. + +Confirmation message. On the result page or in the email, confirm what was sent and what to expect next. + +Sequence integration. If a follow-up sequence was offered, the first email arrives within 24 hours. The sequence delivers the promised cadence. + +Opt-out clarity. Easy unsubscribe from the start. Audiences that find unsubscribe friction lose trust permanently. + +--- + +## Capture-pattern testing + +Test pattern choice with real metrics. + +Test design. A/B test Pattern A vs Pattern B with the same quiz. Measure both conversion to email and downstream conversion (trial signup, demo request, purchase). + +The metric that matters. Downstream conversion per visitor, not conversion to email. A pattern that captures fewer emails but produces more downstream conversion is the better pattern. + +Test duration. Long enough to capture downstream signal (often 30-60 days minimum, depending on consideration cycle). + +--- + +## Common capture failures + +Lead-trap pattern. Result hidden behind email; downstream conversion drops; trust degrades. + +Email gate without value. Email required for the same content; gate is not justified; conversion drops. + +Too many fields. Form asks for name, company, role, phone in addition to email; conversion plummets. + +Generic CTA copy. "Submit" rather than "Get my personalized PDF"; conversion suffers. + +Popup that interrupts. Result loads; popup appears; user's flow breaks. + +Slow delivery. PDF arrives 30 minutes later; trust drops. + +No confirmation. User submits, sees no acknowledgment, wonders if it worked. + +Hard unsubscribe. Multi-step or hidden unsubscribe; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The capture-honest principle. Pattern A through D with strengths, weaknesses, and when-to-use guidance. The value-add at lead capture. The conversion-vs-quality tradeoff. The no-email-needed alternative. Lead-capture form design. Post-capture experience. Capture-pattern testing. Common failures. + +## Implementation choices that stay internal + +Specific capture pattern choices for specific quizzes. Specific PDF templates and sequence designs. Specific form copy and CTAs in brand voice. The team's downstream-conversion benchmarks. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/question-architecture-patterns.md b/skills/quiz-and-assessment-design/references/question-architecture-patterns.md new file mode 100644 index 0000000..8fca5ba --- /dev/null +++ b/skills/quiz-and-assessment-design/references/question-architecture-patterns.md @@ -0,0 +1,212 @@ +# Question architecture patterns + +Question count, types, ordering, phrasing, and segment mapping discipline. The questions are the mechanism that produces the segmentation; bad questions produce bad segmentation regardless of how clever the scoring algorithm is. + +--- + +## Question count + +Most effective quizzes use 5-10 questions. + +Fewer than 5 questions. Rarely produces meaningful segmentation. The taker reaches the result quickly, but the result feels arbitrary because too few signals were captured. Useful only for very simple categorizations (binary or 3-segment outcomes). + +5-7 questions. The sweet spot for most quizzes. Enough to produce nuanced segmentation; few enough that the audience completes without fatigue. + +8-12 questions. Acceptable when the segmentation is genuinely multi-dimensional or when the audience has high commitment. Watch drop-off carefully; the last few questions are where audiences abandon. + +13+ questions. Stops feeling like a quiz; starts feeling like a survey. Drop-off rises sharply. If the segmentation truly needs this many questions, consider whether quiz is the right format. + +--- + +## Question types + +Choose the type that fits the variable being captured. + +Multiple-choice (single-select). The most common quiz question type. Each option maps to a segment or scoring weight. + +When to use: when the answer space is well-defined and mutually exclusive. +When to avoid: when the audience genuinely could choose multiple answers; forcing single-select frustrates the taker. + +Multiple-select. Useful when multiple attributes apply to the taker. + +When to use: when the answer space includes overlapping options ("which features matter most" with multiple selections). +When to avoid: when scoring complexity outweighs the value; multi-select complicates segmentation. + +Slider or scale. "On a scale of 1-5, how often do you..." Useful for intensity questions. + +When to use: when the variable is continuous (frequency, importance, satisfaction). +When to avoid: when the categorization is genuinely categorical; sliders force false continuity. + +Yes/no. Useful for binary qualifying questions. + +When to use: as part of a broader question set when one binary attribute matters (does the team use a CRM today, yes or no). +When to avoid: as the primary question type; quizzes built only on yes/no questions feel coarse. + +Free text. Avoid in quizzes. Free text breaks the scoring flow and adds friction. The few quizzes that genuinely need free text often work better as forms or assessments. + +--- + +## Question ordering + +The order matters as much as the questions themselves. + +Open with engaging, low-friction questions. "What kind of role best describes you?" or "What size is your team?" These warm up the taker and build commitment. + +Mid-quiz: substantive segmentation questions. The questions that most influence the segmentation belong in the middle. The taker has invested enough to commit; you have not yet exhausted their patience. + +Late-quiz: more revealing or sensitive questions. "How effective is your current process?" or "What is your biggest challenge?" These questions benefit from the trust built earlier. + +End: qualifying questions, if needed. Demographic data, company-size confirmation, or contact-channel preferences. These belong at the end, not the start. Asking demographic questions first signals "this is a sales form" and depresses completion. + +--- + +## Question phrasing + +Plain language. No jargon. No leading. + +Plain language. Avoid technical terms the audience may not know. If the quiz is for SaaS founders, "ARR" is fine; if it is for general business owners, "annual revenue" is clearer. + +Specific situations. Frame questions around situations the audience recognizes. "When you onboard a new customer, do you..." beats "What is your customer-onboarding maturity." + +Avoid leading questions. Phrasing that pushes toward a specific answer biases the result. + +- Leading: "How much do you struggle with X?" (presumes struggle) +- Honest: "How would you describe your experience with X?" + +Avoid double-barreled questions. Questions that mix two dimensions confuse scoring. + +- Double-barreled: "How much do you value speed AND simplicity?" +- Cleaned up: split into two questions if both dimensions matter. + +Avoid "all of the above" or "none of the above" defaults. These options are escape valves that produce uninterpretable answers. + +--- + +## Question-segment mapping + +Each question should contribute to the segmentation in a defined way. + +The principle. For each question, document which answer choices map to which segments and with what weight. + +Example: "What size is your team?" + +- 1-5 employees → segment "Solo or small" (+3 to that segment) +- 6-25 employees → segment "Growing team" (+3) +- 26-100 employees → segment "Mid-market" (+3) +- 101+ employees → segment "Enterprise" (+3) + +Example: "What is your sales process maturity?" + +- "Founder-led, no defined process" → "Solo or small" (+2), "Growing team" (+1) +- "Some defined steps, owner driven" → "Growing team" (+2), "Mid-market" (+1) +- "Defined sales playbook, multiple reps" → "Mid-market" (+2), "Enterprise" (+1) +- "Multi-stage enterprise sales process" → "Enterprise" (+3) + +The mapping is explicit. Each question contributes specific weight to specific segments. The mapping should be documented so future maintenance can verify it. + +Filler questions. Questions that do not affect the segmentation are filler. They add friction without adding value. Audit and remove. + +--- + +## Question count vs segmentation depth + +The relationship between question count and segmentation accuracy. + +Few questions, broad segments. A 5-question quiz produces 4-5 segments reliably; trying to produce 10 segments from 5 questions makes each segment poorly distinguished. + +More questions, narrower segments. An 8-question quiz can produce 6-8 segments with enough distinction. + +The over-segmentation trap. Too many segments produced from too few questions creates segments that are not really different. The audience that lands in different segments gets similar recommendations; the segmentation is fake. + +The right ratio. Roughly 1.5-2 questions per segment is a useful baseline. 5-7 segments from 8-12 questions; 4-5 segments from 5-7 questions. + +--- + +## Conditional questions and branching + +Whether to ask different questions based on earlier answers. + +Branching when it helps. Later questions make sense only in the context of earlier ones. "If you have a CRM today, which one?" is a useful follow-up to "Do you use a CRM today?" + +Branching when it hurts. When branching adds complexity without value, when the branching makes the quiz feel different for different takers in confusing ways, when the scoring becomes hard to reason about. + +The simplicity preference. Linear quizzes (everyone gets the same questions in the same order) are easier to maintain, easier to test, and easier for the audience to predict. Use branching only when the value justifies the complexity. + +--- + +## Drop-off considerations + +Where audiences abandon, and why. + +The first question. Some takers click into the quiz and leave at question 1. Often the question or the format made them realize this is not for them. This is fine; honest filtering. + +Mid-quiz (questions 4-7). Drop-off here usually signals fatigue or discomfort. Audit the questions; are they too long, too sensitive, too repetitive? + +Late-quiz (final questions). Drop-off here often signals that the user got bored or the value of finishing was not clear. A progress indicator and a teaser of the result ("almost done; see your result next") can reduce late-stage drop-off. + +Question-by-question tracking. Tracking drop-off per question is the diagnostic. Questions with disproportionate drop-off warrant review. + +--- + +## Mobile question design + +Most quiz takers are on mobile. The question UX has to work there. + +Mobile-specific considerations. + +- Touch-friendly answer options (minimum 44x44 pixel touch targets). +- Single question per screen on mobile (multi-question screens cramp). +- Progress indicator visible without scroll. +- Answer options large enough to tap accurately; spacing prevents accidental taps. +- Sliders sized for thumb interaction. + +Mobile testing. Test the quiz on actual devices. Real-device behavior often differs from browser dev-tools simulation. + +--- + +## Question-mapping audit + +Periodically audit the question-segment mapping. + +The audit. For each segment, verify that the questions actually produce that segment for takers who should get it. Run the quiz with personas representing each segment; confirm each persona reaches the right result. + +The audit cadence. When the recommendation portfolio changes, when the audience composition shifts, or at least quarterly. + +Drift indicators. + +- One segment now receives 70+ percent of takers. +- Another segment receives less than 5 percent. +- Specific personas reach the wrong segment when audited. +- Audience comments that the result was wrong. + +These signals warrant question or scoring revision. + +--- + +## Common question architecture failures + +Too many questions. 15+ questions feels like a survey; drop-off climbs. + +Filler questions. Questions that do not affect segmentation; audit and remove. + +Leading questions. Phrasing that biases the answer. + +Double-barreled questions. Two dimensions in one question; scoring becomes ambiguous. + +Demographic questions first. Signals "sales form"; depresses completion. + +Vague answer options. "Sometimes" vs "often" without anchors; the taker cannot calibrate. + +Inconsistent question types. Mixing 5-point sliders with yes/no without coherent rationale; the rhythm breaks. + +Mobile-broken questions. Sliders that do not work on touch; answer options that overflow. + +--- + +## Methodology-level choices that stay in the public skill + +Question count, types, ordering, phrasing. Question-segment mapping discipline. Question count vs segmentation depth. Conditional questions and branching. Drop-off considerations. Mobile question design. Question-mapping audit. Common failures. + +## Implementation choices that stay internal + +Specific question sets for specific quizzes. Specific scoring weights and segment mappings. Specific tooling for quiz engineering and analytics. The team's drop-off benchmarks and audit calendars. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md b/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md new file mode 100644 index 0000000..533a111 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/quiz-anti-patterns.md @@ -0,0 +1,223 @@ +# Quiz anti-patterns + +The patterns that look like quizzes but degrade trust. Anti-patterns are easy to ship; the cost shows up in lead quality, downstream conversion, and brand reputation over time. + +--- + +## The clickbait-quiz + +The pattern. Engagement-driven framing with no actionable segmentation. "What kind of marketer are you?" with 4 personality types and no recommendations. + +The signal. Engagement metrics are high (shares, completions); downstream metrics are flat. The quiz is fun; it does not produce qualified leads or conversions. + +The cost. The build cost is wasted on entertainment that does not compound business value. The brand earns "fun but not useful" association. + +The cure. Add actionable segmentation. Each segment maps to a specific recommendation matched to that segment. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The vanity-result quiz + +The pattern. Flattering descriptions for every segment. No honest characterization. No specific recommendations. + +The signal. Takers enjoy the result; do not act on it; do not return. The quiz produces a moment of attention without a relationship. + +The cost. The audience associates the brand with horoscope-style content. The quiz does not differentiate the brand from competitors offering similar entertainment. + +The cure. Honest segmentation. Some segments are more flattering than others; honest descriptions produce respect; recommendations that match each segment specifically produce action. + +--- + +## The forced-result quiz + +The pattern. Every taker routes to the same recommendation regardless of answers. The segmentation is decorative; the recommendation was predetermined. + +The signal. Sales team or product team notices that quiz-sourced leads all look the same; the segmentation is not differentiating. + +The cost. The quiz misleads the audience. Takers who answered honestly believing they would get a matched recommendation get a generic one; trust degrades. + +The cure. Real segmentation that produces real different recommendations per segment. If the brand only has one recommendation, do not use a quiz format; use a clear landing page. + +--- + +## The interrogation-quiz + +The pattern. 25 questions that feel like a survey rather than a quiz. The audience drops off mid-quiz. + +The signal. High drop-off rate, especially at questions 8-15. Few takers reach the result. + +The cost. The build effort produces a quiz few people complete. The audience that drops off remembers the brand as the source of the long form they abandoned. + +The cure. Reduce question count. 5-12 questions is the working range. Audit questions for those that do not affect segmentation; remove them. + +--- + +## The leading-question quiz + +The pattern. Questions phrased to push the taker toward a specific result. "Don't you sometimes wish you had..." is leading. + +The signal. The result distribution is biased; takers report that the result felt predetermined; analytical audiences notice the leading. + +The cost. The audience that catches the leading loses trust. The result is artificially produced rather than reflecting the taker's actual situation. + +The cure. Plain phrasing without bias. "How would you describe your experience with X?" beats "How much do you struggle with X?" + +--- + +## The black-box quiz + +The pattern. No explanation of how the result was determined. The taker gets a label with no insight into why. + +The signal. Audience comments asking how the result was calculated; some takers question whether the result is real or random. + +The cost. The quiz feels arbitrary. Even when the segmentation is real, the audience cannot verify; trust suffers. + +The cure. Some transparency about the methodology. "Your result reflects your answers to questions 2, 4, and 6" or a brief explanation of what the segments represent. + +--- + +## The no-recommendation quiz + +The pattern. Result categories exist; no next step is offered. The quiz produces awareness of the segment without action. + +The signal. Strong engagement; near-zero downstream conversion; the quiz captures a moment without converting it. + +The cost. The brand has the audience's attention and does nothing with it. The quiz produces brand impression without business impact. + +The cure. Every result page must include a specific next step. Detail in `references/result-to-recommendation-mapping.md`. + +--- + +## The mismatched-recommendation quiz + +The pattern. The recommendation does not match the segment. A taker classified as "enterprise" gets a "starter plan" recommendation, or vice versa. + +The signal. Sales team feedback that quiz-sourced leads do not match the recommended product. Audience feedback that the recommendation felt wrong. + +The cost. Trust damage. The taker who notices the mismatch feels misled; the brand earns "doesn't get me" reputation. + +The cure. Audit the segment-to-recommendation mapping. Verify each segment's recommendation actually fits. + +--- + +## The over-segmentation quiz + +The pattern. 12+ segments produced from 5 questions. Most segments end up similar; segmentation is fake. + +The signal. Segments that read the same; segments that get the same recommendation; segments that receive less than 3 percent of takers each. + +The cost. Design and copy effort wasted on segments that do not really exist. The audience that lands in similar segments cannot tell them apart. + +The cure. Reduce segment count to what the questions can actually distinguish. 4-7 segments from 5-7 questions; 6-8 segments from 8-10 questions. + +--- + +## The under-segmentation quiz + +The pattern. 2 segments that could have been a yes/no question. The quiz format is over-engineering. + +The signal. The audience completes the quiz quickly; the result feels obvious; the quiz adds friction without adding value. + +The cost. Build effort wasted on a quiz that did not need to be a quiz. The audience that recognizes the over-engineering questions the brand's judgment. + +The cure. Either expand the segmentation to justify the format or replace the quiz with a simpler tool (yes/no qualifier, comparison table). + +--- + +## The lead-trap quiz + +The pattern. The result is calculated but hidden behind an email gate. The taker enters 8 fields, hits Calculate, sees "enter your email to see your result." + +The signal. Email-form conversion is high; downstream conversion is low; audience that recognizes the pattern bounces immediately. + +The cost. Lead quality suffers. The brand earns "lead-trap" reputation. Detail in `references/lead-capture-integration-patterns.md`. + +The cure. Show the result freely; gate the additional value (PDF, follow-up sequence) instead. + +--- + +## The cookie-cutter quiz + +The pattern. The quiz looks and behaves like every other quiz from a template platform. Generic UI, generic question style, generic result format. + +The signal. The quiz does not differentiate; the audience does not associate it specifically with the brand. + +The cost. The quiz becomes commodity. The brand's investment does not compound credibility because the tool does not stand out. + +The cure. Custom design that reflects the brand. Question phrasing in brand voice. Result presentation that feels distinct. + +--- + +## The mobile-broken quiz + +The pattern. Quiz works on desktop; breaks on mobile. Answer options that overflow; sliders impossible to grab; result hidden below the fold. + +The signal. High mobile bounce rate; mobile completion drops below desktop. + +The cost. The mobile audience either bounces or has a worse experience that misrepresents the brand. Mobile is often the majority of traffic. + +The cure. Mobile-first design and testing. Detail in `references/question-architecture-patterns.md` (mobile section). + +--- + +## The popup-interrupted quiz + +The pattern. The result loads; the user starts reading; a popup appears asking for email or offering a different magnet. + +The signal. Bounce rate spikes at the result moment; users complain about the interruption. + +The cost. The quiz's user experience is hostile. The brand earns "annoying" reputation. + +The cure. Offers in context with the result, not as popups that interrupt. + +--- + +## The orphan-quiz + +The pattern. The quiz exists; no follow-up sequence; no integration with the broader funnel. Takers complete; nothing happens. + +The signal. Email captures sit on a list with no engagement; downstream conversion is near zero. + +The cost. The lead-capture work was for nothing. The brand has emails but no relationship. + +The cure. Design the post-quiz sequence as part of the quiz design (similar to the lead-magnet sequence discipline in `lead-magnet-design`). + +--- + +## The everyone-quiz + +The pattern. Quiz designed to appeal to "everyone." Generic segments; generic recommendations. + +The signal. Conversion may be high; lead quality is low; downstream conversion is mixed because the audience is too broad to serve coherently. + +The cost. List grows fast; sequence engagement underwhelms; offers convert poorly. + +The cure. Narrow the audience the quiz serves. Specific quizzes for specific segments produce specific recommendations that convert. + +--- + +## How to detect anti-patterns in a portfolio + +Audit cadence. Quarterly review of every active quiz, looking specifically for these anti-patterns. + +Audit questions per quiz. + +- Does each segment have a specific, distinct recommendation (anti-pattern check: forced-result, mismatched-recommendation)? +- Is segment distribution balanced across takers (anti-pattern check: over-segmentation, under-segmentation)? +- Is drop-off concentrated at specific questions (anti-pattern check: interrogation, leading questions)? +- Does the result page include a clear next step (anti-pattern check: no-recommendation, vanity-result)? +- Is the result accessible without email gate (anti-pattern check: lead-trap)? +- Does the quiz feel branded or templated (anti-pattern check: cookie-cutter)? +- Does the quiz work on mobile (anti-pattern check: mobile-broken)? + +The retire decision. Anti-pattern quizzes often warrant retirement. Maintaining them costs more than the diminishing returns they produce. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched to anti-patterns. The audit cadence and audit questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions and successor-quiz plans. The team's audit calendar and reviewer list. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md b/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md new file mode 100644 index 0000000..11cf765 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/quiz-investment-criteria.md @@ -0,0 +1,145 @@ +# Quiz investment criteria + +When a quiz is the right tool for the audience and the goal, and when a comparison table or other format would serve. The conditions that warrant the quiz format. + +A quiz is a meaningful build. Question architecture, scoring algorithm, result categorization, recommendation mapping, lead-capture integration. The quiz earns this investment only when specific conditions are present. + +--- + +## When a quiz earns the build + +Five conditions that, when present, make a quiz a strong investment. + +The audience faces a decision that benefits from categorization. "Which of our products fits my situation," "what is my readiness for X," "what type of Y am I." The categorization has to map to a real next step. + +The categorization can be derived from a small number of questions. 5-12 questions can produce meaningful segmentation. If the categorization needs 30+ questions, the format is closer to a survey or assessment than a quiz; the audience drop-off makes the format wrong. + +The brand has a portfolio of recommendations that match the segments. A quiz that produces 5 segments and only one recommendation is decorative; the segment-recommendation mapping is the value. + +The result format suits the audience. Audiences who enjoy quizzes (consumers, B2B mid-market, certain creator audiences) engage well. Audiences who do not (technical buyers, enterprise sales) often see quizzes as gimmicks. + +The success metric is defined. Lead volume from the quiz, lead quality by segment, downstream conversion per segment, the audience acting on the recommendation. Without the success metric defined, evaluation is impossible. + +When all five are present, the quiz is a strong investment. When two or fewer are present, a different format (comparison table, worked example, calculator) often serves better. + +--- + +## When a quiz does NOT earn the build + +Funnels where the quiz is the wrong tool. + +The categorization is trivial. "What plan is right for you" with two plans does not need a quiz; a comparison table works. Quizzes earn investment when the categorization is non-trivial. + +The categorization is irrelevant to the next step. A personality quiz with no product-recommendation tie-in entertains but does not convert. The categorization needs to map to action. + +The brand has no varied recommendations. A quiz with one outcome is bait; the segmentation is decorative. Without a portfolio of segment-matched recommendations, the quiz cannot deliver the actionable-segmentation value. + +The audience disrespects quizzes in this context. Enterprise buyers often see quizzes as unprofessional. Technical decision-makers often skip quizzes in favor of direct documentation. The format choice has to fit the audience the brand wants to serve. + +The team cannot maintain the quiz. Quizzes decay as recommendations change, segments evolve, and audience preferences shift. Without maintenance commitment, the quiz becomes stale. + +The audience would convert without the quiz. When the funnel is already producing the conversion the quiz would serve, the quiz adds friction without lift. + +The honest assessment matters more than the default. "Should we have a quiz" is not the question. "Is the quiz the right investment for this audience and decision" is. + +--- + +## The opportunity-cost frame + +A quiz is a meaningful build. Account for the cost honestly. + +The build cost. Question design, scoring algorithm, result categorization, recommendation mapping, UI design, mobile responsiveness, integration. A meaningful quiz often takes 30-100 engineering hours plus design, copy, and content for the recommendations. + +The maintenance cost. Recommendations change; segments evolve; question phrasing decays. Quarterly review and updates run 3-8 hours per active quiz. + +The recommendation portfolio cost. Each segment needs a matched recommendation. Building or curating those recommendations is itself work. + +The opportunity cost. What else could the team have built? A funnel improvement, a content piece, a paid-traffic optimization. The quiz's success has to clear the bar of those alternatives. + +The decision frame. The quiz earns investment when it produces more lift than the alternatives, accounting for the full cost of build plus maintenance plus recommendation portfolio. + +--- + +## The recommendation-portfolio precondition + +Without a portfolio of segment-matched recommendations, the quiz cannot deliver actionable segmentation. + +The check. For the segmentation the quiz will produce, does the brand have a distinct, valuable recommendation for each segment? + +If yes, the quiz can deliver actionable segmentation. The takers get matched to a recommendation that fits their result. + +If no (the brand has one product, one resource, one recommendation regardless of segment), the quiz becomes vanity. The segmentation is decorative; the recommendation was predetermined. + +How to assess the recommendation portfolio. + +- Does the brand have multiple products, services, or content paths that fit different audience segments? +- Can the brand articulate which recommendation fits which segment specifically? +- Are the recommendations valuable enough to that segment to justify the quiz? + +If yes to most of these, the recommendation portfolio supports the quiz. If no, the quiz is the wrong format until the portfolio exists. + +--- + +## The decision worked example + +A B2B SaaS company considering a "What CRM fits your team" quiz. + +Conditions check. + +- Decision benefits from categorization: yes. Prospects evaluate CRMs based on team size, use case, sales process maturity, integration needs. The categorization is non-trivial. +- Small number of questions sufficient: yes. 6-8 questions can capture team size, use case, sales process, integration needs. +- Recommendation portfolio: yes. The brand offers 3 plan tiers plus 2 industry-specific configurations. Each segment can map to a distinct recommendation. +- Audience-fit for quiz format: yes. B2B mid-market PMs and sales leads engage with quizzes when the recommendation is genuinely useful. +- Success metric: yes. Lead volume from the quiz, lead quality (audience-fit at SaaS companies above 25 employees), downstream conversion to demo or trial within 60 days. + +Decision. Build the quiz. The conditions warrant it. + +Result categorization. 5 segments: "Solo founder just starting," "Growing team without CRM," "Mid-market with multiple sales reps," "Enterprise with complex sales cycles," "Integration-heavy team." + +Recommendation per segment. Each segment maps to a specific plan and onboarding path. The segment description explains why that recommendation fits. + +Lead capture. Email after result for personalized PDF showing the recommendation, alternative options considered, and case study from a similar customer. + +The decision was not "should we have a quiz" but "given these conditions, this is the quiz to build." + +--- + +## When to choose a different format + +The quiz is the wrong tool. What works. + +Comparison table. When the choice is between 2-4 well-defined options with clear distinguishing features, a comparison table often serves better. The audience compares directly without going through questions. + +Worked-example resource. When the audience benefits from seeing how others in their situation chose, a 2-page worked-example resource often serves better than a quiz. The audience identifies which example matches them. + +Calculator. When the decision benefits from a calculation rather than a categorization, a calculator serves better. Detail in `calculator-design`. + +Direct documentation. When the audience prefers self-directed research, a clear documentation page about which option fits which situation often serves better than a quiz. + +The pattern. Many "we need a quiz" intuitions are actually "we need a clear way to communicate which option fits which audience." Often the simpler format works as well or better, at lower build cost. + +--- + +## When to retire a quiz + +Quizzes decay. Retiring them is part of the discipline. + +Retire when: + +- Lead volume has dropped below baseline for two consecutive quarters. +- The recommendation portfolio has shifted enough that the quiz routes to outdated recommendations. +- One segment now receives 80 percent of takers, suggesting the question architecture no longer distinguishes. +- A newer tool or magnet on the same topic is outperforming. +- The maintenance cost exceeds the lead value. + +The retiring discipline frees capacity. Stale quizzes route audience to outdated recommendations and damage trust. + +--- + +## Methodology-level choices that stay in the public skill + +The investment conditions for whether to build a quiz. The opportunity-cost frame. The recommendation-portfolio precondition. The decision worked example. When to choose a different format. The retirement discipline. + +## Implementation choices that stay internal + +Specific quiz topics for specific audiences. The team's capacity benchmarks for build, maintenance, and recommendation curation. Specific tooling for quiz engineering and integration. Specific recommendation portfolios per segment. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/result-categorization-patterns.md b/skills/quiz-and-assessment-design/references/result-categorization-patterns.md new file mode 100644 index 0000000..f9e74d7 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/result-categorization-patterns.md @@ -0,0 +1,233 @@ +# Result categorization patterns + +Segment count, naming, distinguishability, balance. The shape of the result categories that the quiz produces. + +The categorization is the quiz's segmentation product. Bad categorization produces results that feel arbitrary or that fail to help the audience act. Good categorization produces results the audience recognizes and uses. + +--- + +## Segment count + +Most quizzes work well with 4-8 result categories. + +Fewer than 4 segments. The categorization feels coarse. Two-segment quizzes (e.g., "is this for you, yes or no") rarely earn the quiz format; a comparison or qualifying form serves better. + +4-6 segments. The sweet spot for most quizzes. Enough segments to feel nuanced; few enough that each gets adequate development. + +7-8 segments. Acceptable when the segmentation is genuinely multi-dimensional. Each segment needs a distinct description, distinct recommendation, and clear distinguishability. + +9+ segments. Often a sign of over-segmentation. Many segments end up similar in description and recommendation; the segmentation becomes fake. + +--- + +## Segment naming + +Memorable. Specific. Honest. Brand-voice consistent. + +Memorable. The taker should be able to describe their segment to a friend. "The Strategic Planner" is memorable; "Type 3" is not. + +Specific. Names should distinguish the segment from others. + +- Specific: "The Hands-On Builder" (vs "Type B") +- Specific: "Solo founder just starting" (vs "Beginner") +- Specific: "Mid-market operator with multiple sales reps" (vs "Mid-tier user") + +Honest. Names should not flatter universally. Some segments are more flattering than others; honest segmentation reflects this. + +- Honest: "Just exploring" alongside "Already executing" alongside "Mature operator." Each describes a real position. +- Dishonest: every segment named with a flattering descriptor regardless of where the taker actually is. + +Brand-voice consistent. The names should sound like the brand the quiz represents. A serious brand uses serious names; a playful brand can use playful names. Consistency matters. + +--- + +## Segment distinguishability + +Each segment should be meaningfully different from the others. + +The test. Read the descriptions of two adjacent segments. Are they meaningfully different in: +- Who the segment describes? +- What the segment's situation is? +- What the segment's recommendation is? + +If yes, the segments are distinguished. If no (the descriptions are similar, the recommendations overlap), the segmentation is fake. + +The fake-segmentation pattern. A quiz produces 5 segments, but segments 2, 3, and 4 are described in similar terms with similar recommendations. The audience that lands in different segments gets indistinguishable results; the segmentation is decorative. + +The cure. Either reduce the segment count (if the segmentation does not support 5 segments, do not pretend it does) or strengthen the distinctions (rewrite descriptions and recommendations so each segment is distinct). + +--- + +## Segment balance + +Each segment should receive a meaningful share of takers. + +Balanced segmentation. Each segment receives roughly 10-30 percent of takers (depending on segment count). The audience is genuinely distributed across segments. + +Imbalanced segmentation. One segment receives 70+ percent of takers; another receives less than 5 percent. The segmentation is not working; the questions do not distinguish meaningfully. + +Why balance matters. + +- Imbalance signals the segmentation is broken. +- The unused segments waste design and copy effort. +- The dominant segment becomes a default that does not really categorize anyone. + +The cure. Audit the question architecture (`references/question-architecture-patterns.md`). Often the questions do not produce balanced segmentation because they bias toward one segment. Adjust questions or weights to produce more even distribution. + +The exception. Some quizzes intentionally produce imbalanced segmentation because the audience genuinely skews. A "what is your team size" quiz may produce 60 percent "small team" because the audience is mostly small teams. Honest imbalance reflecting real audience composition is fine; imbalance from broken questions is not. + +--- + +## Segment description + +What appears at the result, beyond the segment name. + +The description should include: + +- A 2-3 sentence summary of the segment (who they are, what their situation is). +- Specific characteristics the audience will recognize. +- The matched recommendation (what to do next). +- Optional: case study or worked example of someone in this segment. + +Example segment description. + +``` +Segment: "The Mid-Market Operator" + +You are running a sales team of 5-25 people across multiple +products or regions. You have a defined sales process but +inconsistent execution; some reps follow it, others freelance. +Your top priority is unifying the team's process without +slowing your fastest performers. + +Recommendation: Our Growth plan with the multi-region +playbook configuration. We have a 30-day onboarding path +for teams in your situation. + +[Link to PDF: see how 3 mid-market operators implemented +this and the results] +``` + +The description is specific. The recommendation is matched. The next step is clear. + +Description antipatterns. + +- Generic descriptions that could fit multiple segments. +- Flattering descriptions with no honest characterization. +- Descriptions that describe but do not recommend. +- Recommendations that are the same across segments. + +--- + +## Segment naming patterns + +Common patterns and their tradeoffs. + +Pattern A: Role-based names. "The Strategic Planner," "The Hands-On Builder." Useful when segments correspond to functional roles. + +Pattern B: Maturity-based names. "Just Starting," "Growing," "Mature." Useful when segments correspond to stages of development. + +Pattern C: Style-based names. "The Optimizer," "The Connector," "The Visionary." Common in personality assessments. Risk of feeling horoscope-like. + +Pattern D: Situation-based names. "Solo founder pre-launch," "Mid-market operator with multi-region team." Useful when segments correspond to specific situations the audience recognizes. + +Pattern E: Outcome-based names. "Cost-focused buyer," "Time-saver-focused buyer." Useful when segments correspond to what the buyer is optimizing for. + +The pattern choice depends on the quiz's purpose and the audience the brand serves. The discipline is that whatever pattern is chosen, names should be specific and honest. + +--- + +## Result-page composition + +What the result page contains beyond the segment description. + +The standard structure. + +- The segment name and key visual. +- The segment description (2-3 sentences). +- The matched recommendation. +- The clear next step (CTA: download PDF, talk to team, explore product). +- Optional: comparison to other segments (so the taker sees the full picture). +- Optional: share button (if the quiz is shareable). + +The clear-next-step principle. Every result page must include a specific next step. Without it, the quiz produces awareness without action. + +The optional comparison. Showing the other segments lets the taker see the full segmentation. Useful when the audience benefits from understanding where they sit; less useful when the segments would distract from the matched recommendation. + +--- + +## Result-page mobile design + +The result page must work on mobile. + +Mobile considerations. + +- Segment name and recommendation visible without scroll. +- Visual elements sized for mobile screens. +- CTA button large and prominent. +- Share buttons functional on mobile platforms. + +Common mobile failures. + +- Result hidden below the fold; user does not know it loaded. +- Recommendation buried after a long scroll. +- CTA button tiny or hard to tap. + +--- + +## Segment maintenance + +Segments decay along with the quiz. + +What decays. + +- Segment descriptions that no longer match the audience composition. +- Recommendations that point to retired products or content. +- Brand voice that has shifted. + +Maintenance cadence. Quarterly review of segment descriptions and recommendations. Update as the recommendation portfolio evolves. + +The retire-segment decision. A segment that receives less than 3 percent of takers consistently may not warrant maintenance. Either restructure the segmentation to merge underused segments or accept that the segmentation has segments that exist but are rarely produced. + +--- + +## The segmentation-recommendation alignment audit + +Periodically verify that each segment's recommendation still matches. + +The audit. For each segment: +- Does the recommendation still exist (not pointing to a retired product)? +- Does the recommendation still match the segment's situation? +- Does the recommendation deliver value to that specific segment? + +The drift. Recommendations decay. Products are retired, content is updated, the brand evolves. Audit cadence catches the drift. + +--- + +## Common categorization failures + +Too few segments. Categorization feels coarse; quiz earns no segmentation value. + +Too many segments. Over-segmentation; segments end up similar; categorization feels fake. + +Generic segment names. Names that could apply to multiple segments; not memorable. + +Flattering-everyone descriptions. No honest segmentation; all segments feel positive. + +Indistinguishable segments. Two segments that read the same; categorization is decorative. + +Imbalanced distribution. One segment dominates; segmentation is broken. + +Result without recommendation. Description but no next step; quiz produces awareness without action. + +Recommendations all the same. Different segments routed to the same product or path; segmentation is decorative. + +--- + +## Methodology-level choices that stay in the public skill + +Segment count guidance. Naming patterns and discipline (memorable, specific, honest, brand-voice consistent). Distinguishability test. Balance principle. Segment description structure. Naming patterns A through E. Result-page composition. Mobile design. Segment maintenance. Segmentation-recommendation alignment audit. Common failures. + +## Implementation choices that stay internal + +Specific segment names for specific quizzes. Specific descriptions in brand voice. Specific recommendations matched to segments. Specific result-page layouts. The team's audit calendars. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md b/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md new file mode 100644 index 0000000..e94131f --- /dev/null +++ b/skills/quiz-and-assessment-design/references/result-to-recommendation-mapping.md @@ -0,0 +1,255 @@ +# Result-to-recommendation mapping + +The action attached to each category. Mapping discipline and worked examples. The recommendation is what the taker does next; without it, the quiz produces awareness without action. + +The mapping is where the quiz earns its conversion. A great segmentation produces nothing if each segment lacks a matched, actionable recommendation. + +--- + +## The mapping principle + +Each segment maps to a specific recommendation. The recommendation is what the taker does next. + +The principle's three requirements. + +- The recommendation is real (the brand actually offers the recommended next step). +- The recommendation matches the segment specifically (no two segments share the same recommendation). +- The recommendation is valuable to that specific segment (not a generic offer applied to everyone). + +Quizzes that hit all three produce action. Quizzes that miss any of the three produce vanity-result patterns. + +--- + +## What a recommendation can be + +The next step the taker should take. Many forms. + +Product or service. "Solo founders benefit most from our Starter plan with the founder-led onboarding path." The recommendation is a specific tier or configuration matched to the segment. + +Content or resource. "Mid-market operators benefit most from our 30-day playbook for unifying multi-rep teams." The recommendation is a specific resource matched to the segment. + +Conversation or consultation. "Enterprise buyers benefit most from a 30-minute conversation with our team." The recommendation is a specific human touchpoint. + +Path or sequence. "Creators just starting benefit most from our 4-part onboarding sequence." The recommendation is a structured next experience. + +Configuration or setup. "Teams using Salesforce benefit most from our integration setup wizard." The recommendation is a specific technical configuration. + +The form depends on the brand's offerings and the segment's situation. The discipline is that the recommendation is specific, not generic. + +--- + +## The mapping discipline + +Each segment-to-recommendation mapping should pass these tests. + +Test 1: Does the recommendation actually exist? The brand currently offers it; it is not aspirational or in development. + +Test 2: Does the recommendation match the segment specifically? Other segments would not benefit from this recommendation as much; the matching is real. + +Test 3: Does the recommendation deliver value to this segment? The segment that gets this recommendation can act on it and benefit from it. + +Test 4: Is the recommendation deliverable? The brand can provide what is being recommended in the timeframe and form the taker expects. + +Test 5: Does the recommendation include a clear action? The taker knows what to do (click here, start here, talk to someone, download this). + +When all five pass, the mapping is honest. When any fails, the mapping is decorative or misleading. + +--- + +## Worked example: B2B SaaS pricing quiz + +A SaaS platform offering 4 plan tiers with industry-specific configurations. + +Segments and recommendations. + +Segment 1: "Solo founder just starting" +- Description: 1-person team, exploring options, pre-revenue or early revenue. +- Recommendation: Starter plan ($X / month) with the founder-led onboarding path. Free for first 30 days; no credit card required. +- Action: "Start your 30-day trial." Direct link to signup pre-filled with the recommended plan. + +Segment 2: "Growing team without CRM" +- Description: 2-15 people, no CRM today, sales process is informal but starting to need structure. +- Recommendation: Growth plan ($Y / month) with the team-onboarding path. 30-day setup support included. +- Action: "Talk to our team about your setup." Calendar booking link. + +Segment 3: "Mid-market with multiple reps" +- Description: 16-100 people, multiple sales reps, defined process but inconsistent execution. +- Recommendation: Business plan ($Z / month) with multi-rep configuration and 60-day implementation support. +- Action: "Get a custom demo." Form for demo request. + +Segment 4: "Enterprise with complex sales cycles" +- Description: 100+ people, multi-stage sales process, integration-heavy environment. +- Recommendation: Enterprise plan (custom pricing) with dedicated implementation manager. +- Action: "Talk to enterprise sales." Direct line to enterprise contact. + +Segment 5: "Integration-heavy team" +- Description: Any size, but the primary need is integrating with their existing tool stack. +- Recommendation: Any plan plus the integration setup wizard. Detailed integration documentation linked. +- Action: "Explore our integrations." Integration catalog page. + +Each segment maps to a distinct, specific recommendation. Each recommendation includes a clear action. + +--- + +## Worked example: content-marketing quiz + +A content-marketing brand offering multiple content paths. + +Segments and recommendations. + +Segment 1: "Just starting in content" +- Recommendation: 4-part email course covering content fundamentals. +- Action: "Get the 4-part course." Signup form. + +Segment 2: "Producing content but inconsistent results" +- Recommendation: Content audit template + worked-example case study. +- Action: "Download the audit template." Direct download. + +Segment 3: "Scaling a content team" +- Recommendation: Team-management playbook + interview with a content director. +- Action: "Read the playbook." Resource page with playbook and interview. + +Segment 4: "Optimizing for distribution" +- Recommendation: Distribution-strategy framework + 5 worked examples. +- Action: "Read the framework." Resource page. + +Each segment routes to a distinct content path matched to where the audience is. + +--- + +## Worked example: readiness-assessment quiz + +A consultancy offering readiness assessments before engagement. + +Segments and recommendations. + +Segment 1: "Not yet ready" +- Description: Foundation work needed before the consultancy's offering would help. +- Recommendation: Self-serve resources for foundation work. Honest acknowledgment that engagement is not warranted yet. +- Action: "Explore the foundation library." Free resources. + +Segment 2: "Ready for assessment" +- Description: Foundation in place; specific gaps need addressing. +- Recommendation: 60-minute assessment call to identify specific engagement scope. +- Action: "Book the assessment call." Calendar link. + +Segment 3: "Ready for full engagement" +- Description: Foundation in place; clear gaps; ready to engage. +- Recommendation: Direct engagement conversation. +- Action: "Talk to our partner." Direct contact. + +Segment 4: "Ongoing support" +- Description: Already engaged, looking for continued partnership. +- Recommendation: Continuity-engagement options. +- Action: "Discuss your next phase." Direct contact. + +The honest segmentation includes a "not yet ready" segment. This is honest and earns trust; not every taker should be sold to immediately. + +--- + +## The "not for you" segment + +Honest segmentation sometimes includes a segment that is not the brand's audience. + +The pattern. A segment for takers who are not a fit. The recommendation acknowledges the lack of fit and offers something useful (a referral, a different brand's resource, a self-serve path). + +Why it works. + +- The taker who would have churned anyway leaves with respect for the brand. +- The brand earns "honest" reputation that compounds across audience segments. +- The unfit taker may refer fit takers later. + +The dishonest alternative. Pretending every taker is a fit; routing everyone to a sales contact regardless of segment. Audiences that catch the dishonesty disengage. + +--- + +## Recommendation freshness + +Recommendations decay; the mapping needs maintenance. + +What decays. + +- Recommendations pointing to retired products. +- Recommendations referencing outdated pricing or features. +- Recommendations linking to broken pages or moved resources. +- Recommendations that no longer match the brand's strategic priorities. + +Maintenance cadence. Quarterly review of every active recommendation. Update or replace as the brand's portfolio evolves. + +The drift indicator. Sales-team feedback that quiz-sourced leads are landing on the wrong recommendation. The mapping has drifted; refresh. + +--- + +## Recommendation testing + +Test the recommendations as part of quiz launch and updates. + +Click-through testing. What percentage of takers in each segment click the recommendation's CTA? Low click-through suggests the recommendation does not feel matched. + +Conversion testing. What percentage of takers in each segment complete the recommended action (sign up, book a call, download the resource)? Low conversion suggests the recommendation does not deliver expected value. + +Feedback testing. Direct user feedback ("does this recommendation feel right for you?"). Useful for early validation; rarely scalable. + +--- + +## The recommendation-as-CTA discipline + +The recommendation is also the call to action. + +The pattern. The recommendation includes a specific button or link that takes the taker to the next step. + +Specific CTAs. + +- "Start your 30-day trial" (specific action, specific timeframe). +- "Book a 30-minute assessment call" (specific format, specific duration). +- "Download the audit template" (specific deliverable). + +Generic CTAs to avoid. + +- "Learn more" (about what?). +- "Get started" (started doing what?). +- "Click here" (no value statement). + +The recommendation deserves a specific CTA matched to the action. + +--- + +## Multi-recommendation results + +Some quizzes produce multiple recommendations per segment. + +The pattern. The result includes a primary recommendation and one or more secondary recommendations. + +When this works. When the segment genuinely benefits from multiple paths (e.g., "you can start with X, or if you have specific need Y, consider Z instead"). + +When this fails. When multiple recommendations dilute the call to action; the taker does not know which to choose. + +The discipline. Default to one primary recommendation. Add secondary recommendations only when the segment genuinely benefits from a choice. + +--- + +## Common mapping failures + +Same recommendation across segments. Different segments route to the same product or path; segmentation is decorative. + +Generic recommendations. "Talk to our team" for every segment without segment-specific framing. + +Aspirational recommendations. Recommendations for products or services not yet available; the taker tries the action and hits dead ends. + +Mismatched recommendations. Recommendation does not match the segment's situation; takers feel unheard. + +Buried recommendations. Recommendation appears 3 emails after the result rather than in the result itself. + +No clear CTA. Recommendation describes what to do without providing the link or button to do it. + +No "not for you" segment. Every taker routed toward sales; the audience that does not fit is treated as fitting; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The mapping principle and three requirements. Forms a recommendation can take. The mapping discipline (5 tests). Worked examples across quiz types. The "not for you" segment. Recommendation freshness. Recommendation testing. Recommendation-as-CTA discipline. Multi-recommendation results. Common failures. + +## Implementation choices that stay internal + +Specific segment-to-recommendation mappings for specific quizzes. Specific recommendation copy and CTAs in brand voice. Specific tracking for click-through and conversion per recommendation. The team's quarterly mapping audit calendar. These vary by team. diff --git a/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md b/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md new file mode 100644 index 0000000..31c9328 --- /dev/null +++ b/skills/quiz-and-assessment-design/references/scoring-algorithm-patterns.md @@ -0,0 +1,284 @@ +# Scoring algorithm patterns + +Direct mapping, weighted scoring, multi-dimensional, branching. Choice criteria and tradeoffs. The math that turns answers into a segment. + +The scoring algorithm is the bridge from question answers to result categorization. The right algorithm produces meaningful segments; the wrong algorithm produces results that do not match audience self-perception. + +--- + +## Pattern A: Direct mapping + +Each answer corresponds directly to a segment. The dominant answer choice determines the result. + +How it works. + +- Each question's answer choices map to specific segments. +- Each answer adds 1 point (or fixed weight) to its corresponding segment. +- The segment with the most points wins. + +Example. + +Question: "What size is your team?" +- 1-5 → "Solo" (+1) +- 6-25 → "Growing" (+1) +- 26-100 → "Mid-market" (+1) +- 100+ → "Enterprise" (+1) + +After all questions, the segment with the highest count wins. + +Strengths. + +- Simple, transparent, easy to explain. +- Easy to maintain (changes are obvious in their effect). +- The scoring logic can be displayed to the audience without confusion. + +Weaknesses. + +- Limited nuance; one answer cannot contribute to multiple segments meaningfully. +- Risk of ties when multiple segments score equally. + +When to use. When segments are well-defined and questions clearly distinguish them. The default starting point for many quizzes. + +--- + +## Pattern B: Weighted scoring + +Each answer adds points (with weights) to one or more segments. The highest-scoring segment wins. + +How it works. + +- Each question's answer choices add weighted points to one or more segments. +- An answer might add 3 points to segment A and 1 point to segment B. +- After all questions, the segment with the highest total score wins. + +Example. + +Question: "What is your sales process maturity?" +- "Founder-led, no defined process" → "Solo" (+3), "Growing" (+1) +- "Some defined steps" → "Growing" (+3), "Mid-market" (+1) +- "Defined sales playbook" → "Mid-market" (+3), "Enterprise" (+1) +- "Multi-stage enterprise process" → "Enterprise" (+4) + +This question is more central to segmentation, so its weights are higher. + +Strengths. + +- Allows nuance; one answer can contribute to multiple segments. +- Different questions can have different importance through their weights. +- Reduces tie likelihood by spreading weights. + +Weaknesses. + +- Less transparent (audience cannot easily reverse-engineer the result). +- More complex to maintain (changes to weights have non-obvious effects). +- Easy to bias accidentally if weights are not audited. + +When to use. When segmentation needs nuance, when some questions are more important than others, when the segmentation is multi-attribute. + +--- + +## Pattern C: Multi-dimensional + +The quiz produces scores across multiple axes. The result combines the scores into a 2D or 3D segment. + +How it works. + +- The quiz captures scores across 2-3 distinct dimensions (e.g., introvert/extrovert AND analytical/intuitive). +- The result is determined by the position on each dimension (introvert + analytical = one quadrant; extrovert + intuitive = another). +- Common in personality assessments, fit-evaluations, and any segmentation that is genuinely multi-axis. + +Example. + +A 2-dimensional quiz might score: +- Dimension 1: technical depth (low to high) +- Dimension 2: collaboration preference (solo to team) + +Result quadrants: +- High technical, solo → "Solo specialist" +- High technical, team → "Team specialist" +- Low technical, solo → "Solo generalist" +- Low technical, team → "Team generalist" + +Strengths. + +- Captures genuine multi-dimensional segmentation. +- Produces results that feel nuanced and accurate. +- Allows for richer recommendations matched to the dimensional combination. + +Weaknesses. + +- Significantly more complex than single-axis scoring. +- Larger result-set to design and maintain (4 quadrants from 2 dimensions; 8 from 3 dimensions). +- Harder for the audience to predict their result before taking. + +When to use. When segmentation is genuinely multi-axis (personality, fit-evaluation, learning style, decision-making style). + +--- + +## Pattern D: Branching logic + +The next question depends on the previous answer. Allows for adaptive questioning. + +How it works. + +- The quiz starts with a few common questions. +- Based on early answers, the quiz routes to different question sets. +- Different paths through the quiz produce different results. + +Example. + +Question 1: "Do you currently use a CRM?" +- Yes → branch A (questions about current CRM, satisfaction, gaps) +- No → branch B (questions about why not, what would change, current process) + +The two branches produce different question sets that map to different segments. + +Strengths. + +- Adaptive; questions feel relevant to the taker. +- Can produce highly specific segmentation. +- Reduces irrelevant questions for any one taker. + +Weaknesses. + +- Significantly more complex to build and test. +- Harder to compare segments because not all takers answered the same questions. +- Maintenance is harder; changes to one branch can affect overall scoring. + +When to use. When later questions make sense only in the context of earlier ones, when the audience genuinely needs different questions based on their initial situation. + +--- + +## Choice criteria + +Which pattern fits which quiz. + +Use direct mapping when: + +- Segments are well-defined and clearly distinguished. +- Each question maps cleanly to one segment. +- Transparency matters (audience benefits from being able to reason about their result). + +Use weighted scoring when: + +- Segmentation needs nuance. +- Some questions are more central to segmentation than others. +- Most answers contribute to multiple segments meaningfully. + +Use multi-dimensional when: + +- Segmentation is genuinely multi-axis. +- The audience expects a richly textured result (personality assessments, learning styles). +- Each dimension can be measured by a coherent subset of questions. + +Use branching when: + +- Later questions depend on earlier context. +- The audience genuinely splits into distinct groups that need different question sets. +- The maintenance complexity is justified by the segmentation value. + +The simplest pattern that produces the right segmentation is usually the best choice. Complexity has cost; only spend it where it produces value. + +--- + +## Tie-breaking + +What happens when two segments score equally. + +Pattern A: First-tied-segment wins. The segment that reached the top score first (in the order segments are evaluated) wins. Simple but can introduce bias if the order is not deliberate. + +Pattern B: Tie-breaker question. A specific question whose answer breaks the tie. Useful when ties are common. + +Pattern C: Combined-segment result. A result for the tie itself ("You are between segment A and segment B"). Useful when the tie is genuinely meaningful. + +Pattern D: Re-prompt or randomize. Ask one more clarifying question to break the tie. Adds friction but produces a definitive result. + +The choice. Depends on how often ties occur and how meaningful the distinction between tied segments is. If ties are rare and the segments are similar, Pattern A is fine. If ties are common and the segments differ significantly, Pattern B or C is warranted. + +--- + +## Edge-case handling + +What happens at the boundaries of the scoring. + +The all-segments-zero edge case. A taker answers in a way that gives zero points to every segment. Rare but possible. Default to the most common segment, or surface a "we could not categorize you" message that prompts re-engagement. + +The very-high-single-segment edge case. A taker scores extremely high on one segment, far above any other. Often signals strong segmentation; the result is reliable. + +The all-segments-equal edge case. A taker scores equally across all segments. Often signals the questions did not distinguish; the result is unreliable. May warrant a different question set or a different recommendation flow. + +The contradictory-answers edge case. A taker's answers contradict each other in ways the scoring did not anticipate. Often surfaces in audit; the question set may need clarification. + +--- + +## Scoring transparency to the user + +Whether to show the score during or after the quiz. + +Show the score. When the dimensions or score are themselves meaningful to the user (personality assessments often benefit from showing dimensional scores). + +Hide the score. When the score is implementation detail and the segment is the meaningful output (most recommendation quizzes hide the score). + +Hybrid. Show segment + a brief explanation of how it was determined. "Your result is X. The questions that most influenced this were Y and Z." + +The choice depends on whether the score helps the user understand or distract from the result. + +--- + +## Algorithm decay + +Scoring algorithms decay along with quizzes. + +What decays. + +- Question weights that no longer reflect the segmentation reality. +- Segments that have shifted in audience composition. +- Edge cases that have become more common. + +Maintenance cadence. Quarterly review of the scoring algorithm. Audit a sample of takers to confirm results match expectations. + +Drift indicators. + +- One segment receiving 70+ percent of takers. +- Audience comments that the result feels wrong. +- Sales-team feedback that quiz-sourced leads are misclassified. + +--- + +## Algorithm testing + +Test the scoring algorithm before launch and after changes. + +Persona testing. Create personas representing each intended segment. Take the quiz as each persona; verify each persona reaches the intended segment. + +Edge-case testing. Try answer combinations that should produce ties, contradictions, or boundary conditions. Verify the algorithm handles them gracefully. + +Volume testing. Run the quiz with synthetic data simulating expected audience composition. Verify segment distribution matches expectations. + +Production monitoring. Track segment distribution over time. Sudden shifts may indicate question or scoring issues. + +--- + +## Common scoring failures + +Algorithm too simple for the segmentation. Direct mapping when weighted scoring is needed; segments end up poorly distinguished. + +Algorithm too complex for the segmentation. Multi-dimensional when single-axis would have served; complexity without value. + +Hidden bias in weights. Weights that systematically favor one segment regardless of true audience composition. + +Tie-breaking arbitrary. Ties resolved in inconsistent or biased ways. + +No production monitoring. Algorithm drifts unnoticed; segment distribution becomes skewed. + +Scoring not documented. Future maintainers cannot reason about the algorithm; changes break in unexpected ways. + +--- + +## Methodology-level choices that stay in the public skill + +The four scoring patterns with how-it-works, strengths, weaknesses, and when-to-use guidance. Choice criteria. Tie-breaking patterns. Edge-case handling. Scoring transparency. Algorithm decay and maintenance. Algorithm testing. Common failures. + +## Implementation choices that stay internal + +Specific scoring algorithms for specific quizzes. Specific weights and segment mappings. Specific testing personas. Specific tooling for algorithm implementation and monitoring. These vary by team. diff --git a/skills/roadmap-planning/SKILL.md b/skills/roadmap-planning/SKILL.md new file mode 100644 index 0000000..ba9cc5e --- /dev/null +++ b/skills/roadmap-planning/SKILL.md @@ -0,0 +1,228 @@ +--- +name: roadmap-planning +description: "Build a multi-quarter roadmap from a backlog of ideas, requests, and ongoing initiatives. Use this skill when planning the next quarter, sequencing dependent work, balancing build vs improve vs maintain, or making the case for what NOT to do. Triggers on roadmap, quarterly planning, what should we build next, sequencing, prioritization, OKR planning, capacity planning, what's on the roadmap, plan the year, what to ship next quarter. Also triggers when stakeholders are pulling in different directions and the team needs a defensible plan." +category: product +catalog_summary: "Quarterly planning, prioritization, dependency mapping" +display_order: 2 +--- + +# Roadmap Planning + +Take a pile of ideas, requests, and ongoing work. Produce a defensible plan for what to ship, when, and why. The output is a roadmap document plus the prioritization work that made it credible. + +--- + +## When to use + +- Planning the next quarter or the next year +- Sequencing work where some items depend on others +- Balancing new builds, improvements, and maintenance +- Saying no (or "not yet") to specific requests with a defensible reason +- Aligning a team around a single shared plan +- Communicating the plan to stakeholders outside the team +- Replanning after a strategy shift, a missed quarter, or new constraints + +## When NOT to use + +- Specifying a single feature for development (use `pm-spec-writing`) +- Validating whether the idea is worth building (use `ux-research`) +- Designing the feature itself (use `design-standards`) +- Writing the launch plan for a single initiative (use `launch-runbook`) +- Reviewing what shipped vs what was promised (use `after-action-report`) + +--- + +## Required inputs + +- The team's strategy or top-level goals (1 to 5 OKRs, themes, or pillars) +- The backlog: every candidate item, with at least a one-sentence description +- The team's capacity (people × time) +- Known constraints (deadlines, dependencies, hiring, budget) +- The planning horizon (a quarter, two quarters, a year) + +If the strategy is missing, the roadmap will be a list of features, not a plan. Push back and get the strategy first. A roadmap without strategy is just a queue. + +--- + +## The framework: 5 layers + +Roadmaps fail at five different layers. A roadmap is only as good as its weakest one. + +### Layer 1: Themes (the WHY) + +Top-level groupings tied to strategy. Every theme answers: "If we do nothing else this period, this is the outcome we want." + +Good themes are: +- Outcome-shaped, not feature-shaped ("Reduce time-to-first-value" beats "Build onboarding") +- Limited (3 to 5 max) +- Defensible (you can explain why this and not something else) +- Measurable (each maps to one or two metrics) + +Bad themes look like a junk drawer: "Improvements," "Tech debt," "Misc." If it can't be defended in one sentence, it isn't a theme. + +### Layer 2: Initiatives (the WHAT) + +Multi-week or multi-month efforts that ladder up to a theme. Each initiative is bigger than a feature but smaller than a theme. Initiatives have: + +- A clear outcome (the metric or result it should produce) +- A rough size (S / M / L / XL) +- A confidence rating (how sure are we this is the right initiative?) +- A dependency map (what has to happen first) + +Initiatives are where stakeholders push hard. Resist the urge to commit to dates here. Commit to outcomes and rough sizes. + +### Layer 3: Sequencing (the WHEN) + +The order things happen. Sequencing is constrained by: + +- Dependencies (X must finish before Y can start) +- Capacity (the team can do N things at once) +- Calendar reality (Q4 has fewer working days, certain teams have hiring gaps) +- Strategic windows (some launches need to land before a season, conference, or competitive moment) + +Build the sequence after the prioritization. Putting things in time-order before deciding what matters produces a plan optimized for calendar fit, not impact. + +### Layer 4: Capacity reality (the HOW MUCH) + +Most roadmaps fail here. The plan looks good on paper but assumes 100% of every person's time on roadmap work. Real capacity is much lower. + +Default capacity assumptions: + +- Engineers: 60-70% of time on roadmap initiatives. The rest is meetings, reviews, on-call, support, interviews, debugging, ramp-up. +- Designers: 50-60%. Same reasons plus more cross-team support. +- PMs: 40-50%. The rest is planning, comms, stakeholder management, async writing. +- New hires: assume 50% of full capacity for the first quarter, 75% for the second, 100% from Q3 on. +- On-call rotations, leave, holidays: subtract before sizing. + +If the math says the plan needs 100% of the team, the plan is wrong. Cut. + +### Layer 5: Trade-off communication (the WHY NOT) + +Every roadmap has a "Not now" list as important as the "Doing" list. The "Not now" is what makes the plan defensible. + +Include: +- The top requests you considered and rejected +- The reason for each rejection (not the right time, not the right size, conflicts with theme, lower expected impact) +- The condition that would make it move into "Doing" (a metric, a date, a finished prerequisite) + +Stakeholders pushing for cut items can argue against the rejection criteria, not the omission. That's a productive argument. + +--- + +## Workflow + +### Step 1: Anchor the strategy + +Before touching the backlog, write down 3 to 5 themes. If the team's OKRs or strategy doc gives you these, copy them. If not, draft them and validate with the people who own strategy. + +If the strategy is missing or vague, stop. Producing a roadmap against an unclear strategy is worse than producing nothing. Surface the gap. + +### Step 2: Catalog the backlog + +Every candidate gets: +- Name (one phrase) +- Theme it ladders up to (or "no theme" - flag for later) +- Source (request, OKR, retro, customer feedback, leadership ask, technical need) +- Rough size (S / M / L / XL) +- Owner or proposed owner +- Status (idea, validated, scoped, ready) + +Items with "no theme" are warning flags. Either the theme list is incomplete, or the item should be cut. + +### Step 3: Prioritize within each theme + +Inside each theme, rank the initiatives. Use one prioritization framework consistently. Common ones: + +- RICE (Reach × Impact × Confidence ÷ Effort): good for feature-heavy roadmaps +- MoSCoW (Must / Should / Could / Won't): good for fixed-deadline projects +- Kano (Threshold / Performance / Excitement): good for product investment decisions +- Cost of delay: good when timing matters more than effort +- Strategic alignment + impact: good for executive-facing roadmaps + +The framework matters less than the consistency. Pick one. Use it the same way for every initiative. Document the math. + +See [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) for the full breakdown. + +### Step 4: Build the dependency map + +For every "Doing" initiative, list what must happen first: +- Other initiatives +- Hiring +- External dependencies (vendor delivery, partner readiness) +- Research or validation work +- Infrastructure or platform readiness + +Visualize as a graph or a Gantt-style sequence. Items with no dependencies can start immediately. Items with multiple unmet dependencies are warning flags. + +### Step 5: Lay out the sequence + +Now place initiatives in time. Use the dependency map. Use the capacity math. Match initiatives to people who can actually do them. + +Default cadence: month-by-month for one quarter, quarter-by-quarter beyond that. Weekly is too granular for most roadmaps. Half-year buckets are too vague to commit to. + +### Step 6: Validate with the team + +Before sharing externally, validate with the people doing the work: +- Are the size estimates realistic? +- Are the dependencies correctly mapped? +- Are the capacity assumptions accurate? +- Is anyone overcommitted? + +If the team says the plan is impossible, the plan is impossible. Adjust. Going to leadership with a plan the team disagrees with is how trust gets broken. + +### Step 7: Write the "Not now" list + +For every "Doing" item, name what got cut to make room. Document why. Document the trigger that would move it to "Doing" later. + +### Step 8: Communicate + +Different audiences need different views: + +- Team: detailed sequence, owners, dependencies, sizes +- Cross-functional partners: themes, initiatives, rough timing, what they need to provide +- Leadership: themes, expected outcomes, key initiatives, top trade-offs +- Public or customer-facing: themes, no specific dates, "what to expect" + +The same roadmap should produce all four. If it can't, the roadmap is incomplete. + +--- + +## Failure patterns + +A list of features instead of a plan. Themes are missing. The roadmap is a backlog with months attached. Fix: start over from strategy. + +Date-driven thinking. "What can we ship by end of Q2?" instead of "What is the most important thing to do in Q2?" Dates are constraints, not goals. + +Capacity fantasy. The plan adds up to 100% of every person's time. No room for support, interrupts, planning, or unknown unknowns. Roadmap dies in week three. + +Stakeholder pressure overrides strategy. A loud customer or executive request gets prioritized because they pushed hard, not because it ladders up. The "Not now" list saves you here. + +Missing dependencies. Initiative B depends on initiative A, but A is scheduled later. Or A depends on a hire that hasn't happened. The plan looks fine until execution starts. + +Too far out. Specific commitments six months out create promises the team can't keep. Use ranges or themes for far horizons, specifics for near horizons. + +One framework for every level. RICE for the whole roadmap including platform work, infra, and exploration. RICE is great for features, weak for foundational work. Use different lenses for different initiative types. + +No "Not now." Stakeholders rediscover their cut requests every two weeks because there's no record of why they were cut. Document once, point to it forever. + +--- + +## Output format + +The roadmap document includes: + +- Strategy summary (1 page or section): themes, why these themes, how they ladder to top-level goals +- The plan (the visual): a quarter-by-quarter or month-by-month view, color-coded by theme +- Initiative briefs (one per initiative): outcome, size, owner, dependencies, success metric +- Capacity model: who is doing what, with utilization math +- Trade-offs and "Not now": top items considered and rejected, with reasons +- Risks and assumptions: what could derail the plan +- Update cadence: when the roadmap will be revisited (monthly is typical) + +The roadmap is a living document. Plan to revisit it monthly. Replan it formally each quarter. Do not treat it as a contract. + +--- + +## Reference files + +- [`references/prioritization-frameworks.md`](references/prioritization-frameworks.md) - Detailed breakdown of RICE, MoSCoW, Kano, Cost of Delay, and Strategic Alignment frameworks. When to use each, how to apply them, common mistakes. diff --git a/skills/roadmap-planning/references/prioritization-frameworks.md b/skills/roadmap-planning/references/prioritization-frameworks.md new file mode 100644 index 0000000..fead81c --- /dev/null +++ b/skills/roadmap-planning/references/prioritization-frameworks.md @@ -0,0 +1,192 @@ +# Prioritization Frameworks + +Five frameworks for prioritizing work. Each suits different problems. Pick one per planning cycle. Use it consistently. + +--- + +## RICE + +Best for: feature-heavy roadmaps where features are roughly comparable in shape. + +### The math + +``` +RICE Score = (Reach × Impact × Confidence) ÷ Effort +``` + +- Reach: how many people will this affect in a fixed period (e.g., users per quarter). Use real numbers, not relative scores. +- Impact: how much will it affect each person? Use a fixed scale: 3 (massive), 2 (high), 1 (medium), 0.5 (low), 0.25 (minimal). +- Confidence: how sure are you in the estimates? 100% (high), 80% (medium), 50% (low). Below 50%, you don't know enough to score. +- Effort: total person-months to deliver. Be honest. Include design, dev, QA, launch. + +Higher score = higher priority. + +### Where it shines + +Comparing many similarly-shaped feature ideas. Forces conversation about the inputs (Reach, Impact, Confidence) instead of a gut "I think this is more important." + +### Where it fails + +- Foundational work (infra, platform, refactors). Reach and Impact don't apply cleanly. +- Strategic bets where Confidence is low but the upside is huge. RICE punishes low-confidence work. +- "Cost of inaction" items (security, compliance). These often score badly but must ship. + +### Common mistakes + +- Inventing Reach numbers without a basis. If you don't have data, your Reach is a guess wrapped in math. +- Effort estimates that come from PMs, not engineers. Effort is always the engineer's call. +- Treating Impact as a continuous variable. The scale is fixed for a reason - so it's comparable. +- Re-scoring each cycle without checking what shipped last cycle and what its actual Reach × Impact turned out to be. + +--- + +## MoSCoW + +Best for: fixed-deadline projects where you have to decide what's in scope and what isn't. + +### The buckets + +- Must have: without these, the project fails. Non-negotiable for launch. +- Should have: important but not deal-breaking. Plan to include unless capacity tightens. +- Could have: nice to include if there's room. First to be cut. +- Won't have (this time): explicitly out of scope. Documented to prevent drift. + +### Where it shines + +Deadline-driven launches. New site builds. Migrations. Anything with a fixed go-live date. + +### Where it fails + +- Open-ended product work without a hard deadline. Everything tends to drift to "Must have." +- Long-running platforms. The buckets don't help sequence multi-quarter work. + +### Common mistakes + +- "Must have" creeping. By the end of planning, 80% of items are Must. Hard rule: "Must have" should be 30-50% of items, never more. +- No "Won't have." The "Won't have" list is the discipline. Without it, scope grows. +- Ambiguous lines between Must and Should. Define each explicitly. "If we ship without X, will the product work?" If yes, X is Should, not Must. + +--- + +## Kano + +Best for: product investment decisions about feature investment vs polish vs new bets. + +### The categories + +- Threshold features: users expect them. Their absence causes dissatisfaction. Their presence is barely noticed. (Examples: a working login. Email password reset.) +- Performance features: users notice them and value them linearly. More is better. (Examples: speed, search relevance, design quality.) +- Excitement features: users don't expect them. Their presence is delight. Their absence is unnoticed. (Examples: a clever zero state, an unexpected automation.) + +### How to use + +Audit the product. Categorize every feature. Decide where to invest: + +- Threshold features must be present and working. Underinvestment is a tax on everything else. +- Performance features should get sustained investment. They are how the product stays competitive. +- Excitement features are the differentiation budget. Spend selectively, expect them to age into Performance and eventually Threshold. + +### Where it shines + +Product strategy conversations. "Should we polish what we have or ship something new?" Kano answers it: are the Thresholds shipped? Then Performance. Then Excitement. + +### Where it fails + +- Doesn't help with sequencing among features in the same category. +- The categories shift over time. Today's Excitement is tomorrow's Threshold. + +### Common mistakes + +- Treating Excitement as the most valuable category. It's not. Threshold gaps will sink you faster than missing Excitement features. +- Confusing Excitement with novelty. Many "innovative" features are just Performance features in disguise. + +--- + +## Cost of Delay + +Best for: portfolios where timing matters more than effort, especially under capacity constraints. + +### The math + +``` +Cost of Delay per Week = Value Lost Per Week the Item Doesn't Ship +``` + +For each candidate, estimate: if we delay this by one week, what does it cost in revenue, retention, market position, or risk? + +Then divide by effort: + +``` +Cost of Delay Divided by Duration (CD3) = Cost of Delay per Week ÷ Duration in Weeks +``` + +The highest CD3 ships first. + +### Where it shines + +Sequencing inside a constrained team. Surfaces items where every week of delay matters (compliance deadlines, seasonal launches, competitive responses). + +### Where it fails + +- Estimating Cost of Delay is hard. Many items have qualitative cost ("brand damage," "team morale") that resists numerical estimates. +- Bias toward urgent over important. Recurring time-sensitive items (deadlines, customer escalations) keep beating strategic work. + +### Common mistakes + +- Treating all delays as having the same cost shape. Some items have flat cost (delay a week or a year, same outcome). Others have step changes (miss a deadline, lose 80% of the value). +- Ignoring the cost of NOT delaying (opportunity cost from working on this instead of something else). + +--- + +## Strategic Alignment + Impact + +Best for: executive-facing roadmaps and any planning where the question is "should we do this at all?" + +### The matrix + +A 2×2 grid: Strategic Alignment (low/high) on one axis, Impact (low/high) on the other. + +- High alignment / High impact: ship now. Resource heavily. +- High alignment / Low impact: ship if cheap. Question if expensive. +- Low alignment / High impact: dangerous. Either redefine strategy or cut. Items here drag the team away from the plan. +- Low alignment / Low impact: cut. Always. + +### Where it shines + +Cutting noise from the backlog. The bottom-right quadrant (Low/Low) is where most of the noise lives, and the matrix makes it obvious. + +Communicating with leadership. "This is high impact but not aligned" is a defensible reason to deprioritize. + +### Where it fails + +- Doesn't sequence within quadrants. Inside "High/High," you still need a tiebreaker. +- "Strategic alignment" is judgment, not math. Different people will plot the same item differently. + +### Common mistakes + +- Plotting everything as High/High to avoid the conversation. The matrix is only useful if there's a Low quadrant. +- Treating Strategic Alignment as fixed. Strategy changes. Re-plot every cycle. + +--- + +## Picking a framework + +\| If your team is... \| Use \| +\|---\|---\| +\| Building features for a product, comparable in shape \| RICE \| +\| Launching against a fixed deadline \| MoSCoW \| +\| Deciding investment levels across product areas \| Kano \| +\| Sequencing under capacity constraints with timing-sensitive items \| Cost of Delay \| +\| Cutting noise and aligning with leadership \| Strategic Alignment + Impact \| + +You can use more than one in a single planning cycle, but apply each consistently within its scope. Don't switch frameworks halfway through to justify a pre-decided answer. + +--- + +## The meta-rule + +Every framework has known weaknesses. Every framework can be gamed by stakeholders who learn how the math works. + +The frameworks are conversation tools, not decision tools. Their value is forcing the team to articulate inputs (reach, impact, alignment, urgency) instead of arguing about outputs. + +A good roadmap can be defended without the framework. The framework is the work, not the result. diff --git a/skills/scheduler-and-booking-design/SKILL.md b/skills/scheduler-and-booking-design/SKILL.md new file mode 100644 index 0000000..1057df6 --- /dev/null +++ b/skills/scheduler-and-booking-design/SKILL.md @@ -0,0 +1,273 @@ +--- +name: scheduler-and-booking-design +description: "Designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic Calendly link. Availability logic, qualification gating, prep automation, follow-up sequencing. Honest about any-time-friction (no qualification, just a booking link), interrogation-gate (so much qualification it scares users off), and qualified-fast-path (just enough qualification to set up the call well) patterns. Triggers on scheduler design, meeting booking, demo scheduling, sales call scheduling, calendar tool, booking page, qualification flow. Also triggers when sales team complains about cold demos, when booking conversion is poor, or when scheduler is being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing schedulers and booking flows. Distinguishes any-time-friction (no qualification, just a booking link) from interrogation-gate (so much qualification it scares users off) from qualified-fast-path (just enough qualification to set up the call well)" +display_order: 10 +--- + +# Scheduler and Booking Design + +A senior growth practitioner's playbook for designing meeting schedulers and booking experiences that qualify leads, set up calls well, and convert at higher rates than a generic booking link. Availability logic, qualification gating, prep automation, follow-up sequencing. The discipline of building a scheduler that earns the booking by earning a better call. + +Most schedulers fail in one of two ways. Generic booking links produce cold demos where reps know nothing about the person they are about to talk to. Conversion stays at the rate of unqualified raw demos. Or qualification forms with 12 fields scare users off before they can book; drop-off at the form approaches 90 percent; only the leads who happen to survive the form actually convert. + +The schedulers that work do something different. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads route differently), prep automation that briefs the rep before the call. The booking is honest about who the audience is; the call is set up to succeed. + +The voice is the senior growth practitioner who has watched schedulers double demo conversion when redesigned and watched them collapse when more qualification was added. Practical, opinionated about which fields earn their place, willing to call out when the booking flow is the wrong tool. + +When to use this skill: scoping a scheduler for the first time, auditing a booking flow with poor conversion or poor downstream call quality, designing the qualification gate that produces context without producing friction, or deciding routing logic that matches leads to the right reps. + +--- + +## What this skill covers + +This skill spans meeting schedulers and booking experiences across acquisition and sales contexts. The growth-tooling distinctions: + +- `multi-step-form-design` is pre-signup data capture (forms before the user has access to anything). This skill is meeting-booking specifically; qualification fields exist but the goal is the call, not the data. +- `funnel-flow-architecture` is broader funnel architecture. This skill is the scheduler specifically. +- `lead-magnet-design` is different commitment level. Magnets earn an email; bookings earn time. +- `scheduler-and-booking-design` (this skill) is the qualification, availability, routing, prep automation, and follow-up sequencing for meetings. +- `pm-spec-writing` is the spec for engineers building the scheduler. + +The audience: growth marketers, product marketers, marketing operations leads, sales operations leads, agencies running booking optimization for SaaS clients. + +Out of scope: pre-signup forms (covered by `multi-step-form-design`); broader funnel orchestration (covered by `funnel-flow-architecture`); the engineering implementation; specific Calendly/Cal.com/Chili Piper/SavvyCal platform configurations (those stay implementation-side). + +--- + +## The booking-flow decision: scheduler vs forms vs sales-pipeline tools + +Before designing the scheduler, decide whether a scheduler is the right tool. + +Schedulers earn investment when: + +- The conversion goal is a meeting (demo, sales call, consultation). Email-only conversions do not need a scheduler. +- The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. +- The team has enough sales or success capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. +- The team can support qualification logic and routing. Without these, a generic booking link is the result. + +Schedulers do NOT earn investment when: + +- The conversion goal is a download or signup. Use forms or magnet flows. +- The audience volume is too low for routing logic. A handful of bookings per month does not need infrastructure. +- The team's capacity is variable and routing cannot reflect that. Scheduling without capacity awareness produces no-shows on both sides. +- A simpler contact form would serve the same purpose. + +The decision is not "should we have a scheduler"; it is "is the scheduler the right next investment for this audience and goal." + +Detail in [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md). + +--- + +## Any-time-friction vs interrogation-gate vs qualified-fast-path + +The keystone framing. + +Any-time-friction. Generic booking link with no qualification, no context capture. Reps show up to calls cold; they spend the first 10 minutes asking the same qualification questions the form should have captured. Conversion stays at the rate of unqualified raw demos. Cost: sales capacity used inefficiently; high-fit leads get the same experience as low-fit leads; downstream conversion suffers. + +Interrogation-gate. Qualification form with 12 fields before the user can book. Drop-off at the form approaches 90 percent. The qualification works for the leads who survive but the system loses everyone else. Cost: high-fit leads who would have converted abandon at the form; conversion rate is poor even though the post-form leads are well-qualified. + +Qualified-fast-path. Just enough qualification to set up the call well (3-5 strategic fields), context-aware availability (high-fit leads see senior reps; low-fit leads see SDRs or are routed to async), prep automation that briefs the rep before the call. Cost: design effort upfront is significant; conversion plus downstream call quality both improve meaningfully. + +The litmus test. Does the rep arrive at the call already knowing the prospect's situation? Did the prospect feel respected by the booking experience? If yes to both, qualified-fast-path. If the rep starts cold, any-time-friction. If the prospect dropped at the form, interrogation-gate. + +--- + +## Qualification field design + +Which fields earn their place; which create friction. + +The principle. Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +Strong qualification fields. + +- Company size or team size. Routes to the right rep tier; enables enterprise vs SMB tracking. +- Use case or primary goal. Lets the rep prepare for the conversation that matches. +- Current solution or stack. Tells the rep where the prospect is starting. +- Timeline or urgency. Routes to active-pipeline vs nurture. +- Role or job function. Lets the rep tailor framing. + +Weak qualification fields. + +- Phone number (often unnecessary if email and meeting time are captured). +- Generic comments box (free-text; rarely informs prep). +- Marketing data not used in the call (industry codes, lead-source detail). +- Demographic data unrelated to the call (gender, age). + +The five-field rule. Most production schedulers work well with 3-5 qualification fields. More than 5 starts producing interrogation-gate dynamics. Less than 3 does not give the rep useful prep context. + +Detail in [`references/qualification-field-design.md`](references/qualification-field-design.md). + +--- + +## Availability logic + +Round-robin, weighted by fit, calendar integration. + +Pattern A: Pure round-robin. Bookings cycle through available reps in order. + +When to use. Simple distribution; small teams. + +Strengths. Even distribution; simple logic. + +Weaknesses. Does not match high-fit leads to senior reps; does not load-balance based on capacity. + +Pattern B: Weighted round-robin. Bookings cycle but weighted by rep performance, capacity, or specialty. + +When to use. Teams with rep specialization; teams where capacity differs. + +Pattern C: Fit-based routing. High-fit leads (large company, high urgency) route to senior reps; lower-fit leads route to SDRs or async resources. + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +Pattern D: Hybrid. Combines patterns. Fit-based routing for top tier; round-robin within tier. + +When to use. Most production teams. + +The match-to-rep discipline. The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +Detail in [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md). + +--- + +## Routing patterns + +Different reps for different lead types. + +By company size. SMB to SDRs, mid-market to AEs, enterprise to senior AEs. + +By use case. Different specialists for different product use cases. + +By geography. Different reps for different time zones or regions. + +By language. Native-language reps for non-English-primary leads. + +By account ownership (B2B). If the lead's company is already a customer or prospect of an AE, route to that AE. + +The unrouted lead. Some leads do not fit obvious routing. Default rule needed: round-robin or specific catchall. + +Detail in [`references/routing-patterns.md`](references/routing-patterns.md). + +--- + +## Prep automation + +Briefing the rep before the call. + +The principle. The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused. + +Prep automation patterns. + +- CRM enrichment. Qualification data populates the CRM record; rep sees it in their pre-call review. +- Calendar invite enrichment. Qualification data appears in the meeting invite description; rep sees it on their calendar. +- Slack or email brief. Pre-call brief sent to the rep with synthesized prospect info. +- Account research. Qualification data triggers automated research (company size verification, recent news). + +Strong prep automation. The rep arrives at the call already knowing: who the prospect is, what they are trying to accomplish, what they are using today, when they need a solution. + +Weak prep automation. The rep has the qualification data but it is buried in a CRM field nobody opens. The rep starts the call cold despite the data. + +Detail in [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md). + +--- + +## Confirmation and reminder sequences + +The communications around the booking. + +Booking confirmation. Sent immediately after booking. Confirms time; restates context; sets expectations. + +Pre-meeting reminder. Sent 24 hours and/or 1 hour before. Reduces no-shows. + +Post-meeting follow-up. Sent within hours of the call. Recap; next steps; resources. + +Reschedule and no-show flows. Different flows for different outcomes. + +The reminder discipline. Reminders are useful; over-reminding is friction. Two reminders (24-hour and 1-hour) is typical. + +Detail in [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md). + +--- + +## Reschedule and no-show handling + +What happens when meetings do not go to plan. + +Reschedule patterns. + +- Easy self-serve reschedule (no friction). +- Reschedule preserves qualification data. +- Reschedule notifies the rep proactively. + +No-show patterns. + +- Auto-detect (rep reports no-show; or system detects unattended meeting). +- Follow-up to the prospect (gentle; not punitive). +- Re-engagement sequence (one or two attempts to rebook). +- Eventual deactivation (do not pursue forever). + +The respect-the-no principle. Prospects who no-show twice often do not want the meeting. Multiple aggressive reschedule attempts feel like pressure. + +Detail in [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md). + +- "Booking conversion is high; demo conversion to sale is low." Qualification too thin; cold demos do not convert. +- "Booking conversion is low; demo conversion to sale is high." Interrogation-gate; qualification scares off would-be buyers. +- "Sales says many bookings come from wrong-fit leads." Routing logic not connecting qualification to rep tier. +- "No-show rate is over 30 percent." Reminder sequence broken; or commitment friction at booking too low. +- "Reps complain they get no context before calls." Prep automation broken; data captured but not delivered to rep. +- "Calendar integration breaks every few weeks." Brittle integration; or rep calendar permissions changing. +- "Mobile booking conversion is half of desktop." Mobile UX issue. +- "Booking link gets shared by reps; routing logic bypassed." Generic link in use alongside structured flow; bypass undermines routing. +- "Round-robin produces uneven workload." Reps with different capacity treated equally. + +--- + +## The framework: 12 considerations for scheduler and booking design + +When designing or auditing a scheduler, walk these 12 considerations. + +1. The booking-flow decision. Is a scheduler the right tool, or a form / sales-pipeline tool? +2. Qualified-fast-path, not any-time-friction or interrogation-gate. Just enough qualification to set up the call well. +3. Qualification fields earn their place. 3-5 fields; each routes or preps. +4. Availability logic matches team structure. Round-robin, weighted, fit-based, or hybrid. +5. Routing connects qualification to rep tier. High-fit leads to senior reps. +6. Prep automation delivers data to reps. CRM enrichment, calendar invite, Slack brief. +7. Confirmation and reminders reduce no-shows. 24-hour and 1-hour typical. +8. Reschedule is friction-low. Self-serve; preserves data. +9. No-show flow honest. Re-engagement attempts limited; respect non-response. +10. Mobile parity. Booking works on the devices the audience uses. +11. Conversion to sale as success metric. Not just booking rate; downstream call-to-sale conversion. +12. Maintenance discipline. Routing rules updated as team changes; quarterly audit. + +The output of the framework is a scheduler that earns the booking by earning a better call, with conversion that compounds because the calls themselves are better. + +--- + +## Reference files + +- [`references/scheduler-decision-criteria.md`](references/scheduler-decision-criteria.md) - When schedulers earn the build vs when forms or sales-pipeline tools serve. +- [`references/qualification-field-design.md`](references/qualification-field-design.md) - Strong and weak qualification fields. The five-field rule. +- [`references/availability-logic-patterns.md`](references/availability-logic-patterns.md) - Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. +- [`references/routing-patterns.md`](references/routing-patterns.md) - By size, use case, geography, language, account ownership. Unrouted-lead default. +- [`references/prep-automation-patterns.md`](references/prep-automation-patterns.md) - CRM enrichment, calendar invite, Slack brief, account research. +- [`references/reminder-sequence-patterns.md`](references/reminder-sequence-patterns.md) - Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. +- [`references/reschedule-and-no-show-handling.md`](references/reschedule-and-no-show-handling.md) - Reschedule patterns, no-show patterns, respect-the-no principle. +- [`references/scheduler-anti-patterns.md`](references/scheduler-anti-patterns.md) - The patterns that look like schedulers but degrade conversion. +- [`references/common-scheduler-failures.md`](references/common-scheduler-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: schedulers earn the booking when they earn the better call + +The schedulers that work as compounding assets are the ones that produce better calls. Not just more bookings. Calls where the rep arrives prepared; the prospect feels respected; the conversation moves faster because qualification was already done. Conversion compounds because the calls themselves convert better. + +That is the bar. Below the bar are any-time-friction (cold demos, conversion suffers) and interrogation-gate (90 percent abandon at the form). Above the bar are qualified-fast-path schedulers where qualification, availability, routing, prep automation, and follow-up sequencing combine into a system that earns the booking and the call. + +The discipline is in the design choices. The decision to use a scheduler at all. The qualification fields that earn their place. The availability logic that matches lead to rep. The routing that respects rep tier and capacity. The prep automation that delivers context to reps before the call. The reminder cadence that reduces no-shows without becoming spam. The reschedule and no-show handling that respects the prospect. diff --git a/skills/scheduler-and-booking-design/references/availability-logic-patterns.md b/skills/scheduler-and-booking-design/references/availability-logic-patterns.md new file mode 100644 index 0000000..a2c9192 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/availability-logic-patterns.md @@ -0,0 +1,272 @@ +# Availability logic patterns + +Round-robin, weighted, fit-based, hybrid. Match-to-rep discipline. + +How the scheduler decides which rep gets which booking. Done well, availability logic distributes load while matching high-fit leads to senior reps; done poorly, leads land on the wrong reps and conversion suffers. + +--- + +## The match-to-rep principle + +The qualification fields feed routing logic. Routing fails if qualification does not capture routing-relevant data. + +The win. A high-fit enterprise lead (large company, urgent timeline) sees availability for senior AEs. Low-fit lead (small team, exploring) sees availability for SDRs. Each lead gets the right call. + +The fail. Same scheduler with pure round-robin. Enterprise lead lands on an SDR; SDR is unprepared; conversion drops. + +The discipline. Routing is not separate from qualification; the two are coupled. + +--- + +## Pattern A: Pure round-robin + +Bookings cycle through available reps in order. + +How it works. + +- Available reps in the queue. +- Each booking goes to the next rep. +- Cycle continues. + +Strengths. + +- Even distribution. +- Simple logic. +- Easy to explain to the team. + +Weaknesses. + +- Does not match high-fit leads to senior reps. +- Does not load-balance based on capacity. +- Does not account for rep specialization. + +When to use. Small teams; reps are interchangeable; volume is low. + +--- + +## Pattern B: Weighted round-robin + +Bookings cycle but weighted by rep performance, capacity, or specialty. + +How it works. + +- Each rep has a weight (performance score, capacity, etc.). +- Distribution skews toward higher-weighted reps. +- Still distributes; just unevenly. + +Strengths. + +- Higher-performing reps get more bookings. +- Capacity differences accommodated. + +Weaknesses. + +- Lower-performing reps get fewer learning opportunities. +- Weighting must be maintained. + +When to use. Teams with significant rep performance differences; teams where capacity differs. + +--- + +## Pattern C: Fit-based routing + +High-fit leads route to senior reps; lower-fit leads route to SDRs or async resources. + +How it works. + +- Qualification fields determine fit score. +- High-fit leads see availability for senior reps only. +- Lower-fit leads see availability for SDRs. + +Strengths. + +- Senior reps focus on high-value conversations. +- SDRs handle qualification and nurture. +- Resource allocation matches lead value. + +Weaknesses. + +- Requires clear fit signals from qualification. +- May produce uneven workload (senior reps light, SDRs heavy). + +When to use. Teams with multi-tier sales motion; clear fit signals captured. + +--- + +## Pattern D: Specialty-based routing + +Bookings route to reps with specific expertise. + +How it works. + +- Qualification captures use case or industry. +- Bookings route to the rep with matching specialty. + +Strengths. + +- Rep is genuinely prepared for the specific conversation. +- Higher conversion when specialty matches. + +Weaknesses. + +- Specialist reps can become bottlenecks. +- Requires per-rep specialty tagging. + +When to use. Products with multiple distinct use cases or verticals. + +--- + +## Pattern E: Account-ownership routing (B2B) + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +How it works. + +- Qualification or domain matching detects existing-account leads. +- Bookings route to the AE who owns the account. +- Override default routing. + +Strengths. + +- Account owner has context. +- Avoids confusion of multiple reps on the same account. + +Weaknesses. + +- Requires CRM integration to detect ownership. +- Account ownership must be current. + +When to use. B2B teams with account-ownership models. + +--- + +## Pattern F: Hybrid + +Combining patterns. Most production teams use hybrid. + +Common combinations. + +- Account-ownership routing first (existing accounts to AEs). +- Then fit-based routing (high-fit new leads to senior AEs). +- Then specialty-based routing within tier. +- Then round-robin within remaining pool. + +Strengths. + +- Handles common cases. +- Routes lead to best-matched rep. + +Weaknesses. + +- More complex to maintain. +- More edge cases to handle. + +When to use. Mature production teams with multi-tier sales motion. + +--- + +## Calendar integration + +How availability connects to actual calendars. + +Direct calendar integration. Scheduler reads rep calendars; shows actual availability. + +Strengths. No double-booking; reflects reality. + +Weaknesses. Requires calendar permissions; integration brittle. + +Office hours definition. Reps define availability windows; scheduler shows those. + +Strengths. Simpler integration; no calendar permissions needed. + +Weaknesses. Manual maintenance; reps may forget to update. + +Hybrid. Scheduler uses office hours plus calendar busy/free for fine-grain. + +Strengths. Resilient to integration issues. + +Weaknesses. More complex. + +--- + +## Buffer time + +Time between meetings. + +Why it matters. Back-to-back meetings produce rushed reps and late starts. Buffer protects rep effectiveness. + +Common buffers. 10-15 minutes between meetings. + +The discipline. Buffer should be in the calendar logic, not optional. + +--- + +## Capacity caps + +How many meetings per day per rep. + +Why caps matter. Reps booked solid produce poor calls; quality drops; conversion suffers. + +Common caps. 3-5 demos per day per rep typical for B2B SaaS. + +The discipline. Caps respect rep effectiveness, not just calendar availability. + +--- + +## Time zone handling + +The scheduler shows availability in the prospect's time zone. + +The principle. Display in prospect's time zone; reps see in their own. + +Common patterns. + +- Auto-detect from browser; show prospect that detection. +- Allow manual override. +- Display rep's time zone for clarity ("PT" badge). + +Anti-pattern. Showing all times in rep's time zone; prospect has to convert mentally. + +--- + +## Out-of-office and holiday handling + +Real life intervenes. + +Patterns. + +- Calendar integration handles vacation as busy time. +- Manual office-hours updates handle planned absences. +- Holiday calendars block company-wide closures. + +The discipline. Out-of-office should be respected automatically; otherwise no-shows happen. + +--- + +## Common availability failures + +Pure round-robin for tiered teams. High-fit leads land on junior reps. + +No capacity caps. Reps overbooked; quality drops. + +No buffer. Meetings run late; reps are stressed. + +Time zone confusion. Prospect sees rep's time zone; bookings happen at wrong times. + +Stale rep weights. Weighted round-robin uses last-quarter performance; recent changes ignored. + +Specialty routing without specialty data. Specialty-based routing requires per-rep tagging; missing tags route incorrectly. + +Account-ownership not detected. Existing-account lead bounces around between reps. + +Calendar integration broken. Double-bookings happen; trust degrades. + +--- + +## Methodology-level choices that stay in the public skill + +The match-to-rep principle. Patterns A through F (round-robin, weighted, fit-based, specialty, account-ownership, hybrid). Calendar integration. Buffer time. Capacity caps. Time zone handling. Out-of-office and holiday handling. Common failures. + +## Implementation choices that stay internal + +Specific routing logic for specific teams. Specific weights and caps. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/common-scheduler-failures.md b/skills/scheduler-and-booking-design/references/common-scheduler-failures.md new file mode 100644 index 0000000..be02c42 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/common-scheduler-failures.md @@ -0,0 +1,179 @@ +# Common scheduler failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Booking conversion is high; demo conversion to sale is low." + +The diagnosis. Qualification too thin; cold demos do not convert. + +The cure. Add 3-5 strategic qualification fields. Detail in `references/qualification-field-design.md`. + +--- + +## "Booking conversion is low; demo conversion to sale is high." + +The diagnosis. Interrogation-gate; qualification scares off would-be buyers. + +The cure. Cut qualification to 3-5 fields. Defer non-essential questions to in-call. + +--- + +## "Sales says many bookings come from wrong-fit leads." + +The diagnosis. Routing logic not connecting qualification to rep tier. + +The cure. Add fit-based routing. Detail in `references/routing-patterns.md`. + +--- + +## "No-show rate is over 30 percent." + +The diagnosis. Reminder sequence broken; or commitment friction at booking too low. + +The cure. Audit reminder cadence. Strengthen pre-meeting communications. Detail in `references/reminder-sequence-patterns.md`. + +--- + +## "Reps complain they get no context before calls." + +The diagnosis. Prep automation broken; data captured but not delivered. + +The cure. CRM enrichment, calendar invite enrichment, Slack brief. Detail in `references/prep-automation-patterns.md`. + +--- + +## "Calendar integration breaks every few weeks." + +The diagnosis. Brittle integration; or rep calendar permissions changing. + +The cure. Monitor integration; fix permissions; have a manual fallback for downtime. + +--- + +## "Mobile booking conversion is half of desktop." + +The diagnosis. Mobile UX issue. + +The cure. Mobile-first design and testing. + +--- + +## "Booking link gets shared by reps; routing logic bypassed." + +The diagnosis. Generic link in use alongside structured flow. + +The cure. Disable generic links. Train reps; provide rep-specific structured links if needed. + +--- + +## "Round-robin produces uneven workload." + +The diagnosis. Reps with different capacity treated equally. + +The cure. Weighted round-robin or capacity-aware routing. + +--- + +## "Time zone errors cause no-shows." + +The diagnosis. Time zone display unclear or auto-detection wrong. + +The cure. Display time zone clearly at booking and in invites. Auto-detect prospect time zone; allow override. + +--- + +## "Reps reschedule manually frequently." + +The diagnosis. Routing produces wrong-fit bookings; reps fix manually. + +The cure. Audit routing logic; fix the source of the wrong-fit bookings. + +--- + +## "Conversion was strong; quality dropped after sales team change." + +The diagnosis. New rep tier or specialization mix; routing not updated. + +The cure. Routing rules updated as team changes. Quarterly review. + +--- + +## "We added more qualification fields; conversion dropped." + +The diagnosis. Crossed the five-field threshold. + +The cure. Cut back. Five-field rule from `references/qualification-field-design.md`. + +--- + +## "Some segments convert; others do not." + +The diagnosis. Single scheduler treats all segments the same. + +The cure. Per-segment qualification or routing. Different segments may need different schedulers. + +--- + +## "Schedulers work for direct traffic; partner-sourced leads convert poorly." + +The diagnosis. Partner-sourced leads have different fit profile; routing or qualification not adapted. + +The cure. Source-based routing. Partner leads may need different rep tier or different prep. + +--- + +## "We tried different reminder cadences; no-shows did not move." + +The diagnosis. No-show may not be reminder-driven. Could be commitment friction at booking, time zone errors, or audience mismatch. + +The cure. Test other variables. Audit booking commitment level, time zone clarity, audience-fit. + +--- + +## "Sales says enterprise prospects skip the scheduler and email instead." + +The diagnosis. Enterprise audiences sometimes want personal contact rather than self-serve booking. + +The cure. Offer a "talk to sales" alternative for enterprise leads. Hybrid approach. + +--- + +## "Conversion dropped after we updated the booking flow." + +The diagnosis. Specific change introduced friction. + +The cure. Compare metrics pre- and post-change. Roll back if necessary; isolate the issue. + +--- + +## "Reschedule flow loses qualification data." + +The diagnosis. Reschedule treated as new booking; data not preserved. + +The cure. Reschedule preserves qualification. Detail in `references/reschedule-and-no-show-handling.md`. + +--- + +## The pattern across failures + +Most scheduler failures fall into one of three patterns. + +Pattern 1: Qualification miscalibrated. Any-time-friction, interrogation-gate, or wrong fields. The fix is calibrating qualification to the team's needs. + +Pattern 2: Routing or prep miscalibrated. Wrong-rep-tier, no-prep-automation, broken integrations. The fix is connecting qualification to rep workflow. + +Pattern 3: Communication miscalibrated. Aggressive reminders, brittle no-show flows, missing reschedule paths. The fix is gentle, useful communication. + +The metric pattern: scheduler failures often look fine on booking conversion alone. The signal is in demo-to-sale conversion, no-show rates, rep prep quality. Programs that track only booking rate keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (qualification, routing/prep, communication). The principle that booking rate alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/prep-automation-patterns.md b/skills/scheduler-and-booking-design/references/prep-automation-patterns.md new file mode 100644 index 0000000..fe9f876 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/prep-automation-patterns.md @@ -0,0 +1,247 @@ +# Prep automation patterns + +CRM enrichment, calendar invite, Slack brief, account research. + +The qualification data should reach the rep in a useful form before the call. Without prep automation, the data sits unused and the rep starts the call cold despite the data being captured. + +--- + +## The data-reaches-rep principle + +Prep automation closes the loop between qualification capture and rep readiness. + +The win. Prospect books; qualification data populates the CRM record, appears in the calendar invite, and triggers a brief Slack message to the rep with synthesized prep notes. The rep arrives at the call already knowing the prospect's situation. + +The fail. Qualification data captured; sits in a database; rep does not see it until they search for it. Most reps do not search; they start the call cold. + +The discipline. Capture qualification AND deliver it to the rep where they will see it. + +--- + +## Pattern A: CRM enrichment + +Qualification data populates the CRM record. + +How it works. + +- Booking submission writes to CRM (Salesforce, HubSpot, etc.). +- Fields populate the lead/contact record. +- Rep sees the data when they review the lead. + +Strengths. + +- Single source of truth. +- Fits existing rep workflow (reps already check CRM). + +Weaknesses. + +- Reps may not check CRM before every call. +- CRM custom fields require setup. + +When to use. Default; baseline for any prep automation. + +--- + +## Pattern B: Calendar invite enrichment + +Qualification data appears in the meeting invite description. + +How it works. + +- When the meeting is created, the invite description includes the qualification data. +- Rep sees it on their calendar; visible at-a-glance. + +Strengths. + +- Rep cannot miss it; calendar is the moment of action. +- Works regardless of CRM access. + +Weaknesses. + +- Calendar invite descriptions can be long; reps may not read fully. +- Updates after booking do not appear in the invite. + +When to use. Strong complement to CRM enrichment. + +--- + +## Pattern C: Slack or email brief + +Pre-call brief sent to the rep with synthesized prospect info. + +How it works. + +- Booking triggers a Slack message or email to the rep. +- Brief includes qualification data plus context (account history, company info, prior interactions). +- Often delivered hours or a day before the call. + +Strengths. + +- Active delivery; rep receives it without searching. +- Can include synthesized context (CRM history, news, prior touches). + +Weaknesses. + +- Slack noise can dilute brief; reps may scroll past. +- Email may sit unread. + +When to use. When the team's workflow includes Slack or email-driven prep. + +--- + +## Pattern D: Account research + +Qualification data triggers automated research. + +How it works. + +- Booking triggers automated lookup (company size verification via Clearbit/ZoomInfo, recent news search, social media check). +- Research results appended to CRM or prep brief. + +Strengths. + +- Rep gets richer context than qualification alone provides. +- Catches data prospects did not provide. + +Weaknesses. + +- Research tools cost. +- Can miss for small companies or international. + +When to use. Enterprise sales motion; high-value calls warrant research investment. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production teams use multiple. + +Common combination. + +- CRM enrichment as baseline. +- Calendar invite enrichment for at-a-glance visibility. +- Slack brief 24 hours before the call for richer prep. +- Account research for high-fit leads. + +The hybrid produces multiple touchpoints; rep sees prep data wherever they happen to look first. + +--- + +## What to include in prep automation + +The fields that matter to the rep. + +Standard inclusions. + +- Prospect name and role. +- Company name and size. +- Use case or primary goal. +- Current solution. +- Timeline or urgency. +- Source (paid, organic, referral). + +Sometimes useful. + +- Company industry and recent news. +- Prior interactions with the brand. +- LinkedIn profile link. +- Account history (existing customer, prior trial). + +Avoid in prep. + +- Free-text fields the prospect filled with noise. +- Marketing data not relevant to the call (UTM details, lead source granularity). +- Personal data not needed for the call. + +--- + +## Prep timing + +When the brief reaches the rep. + +At-booking. Brief delivered immediately after booking. Rep can prepare any time. + +Day-before. Brief delivered 24 hours before. Forces prep into the rep's workflow. + +Hour-before. Brief delivered 1 hour before. Last-minute prep; useful for back-to-back calls. + +The combined approach. Most teams use at-booking (CRM record) plus day-before (Slack) plus calendar visibility throughout. + +--- + +## Prep brief copy + +What the brief says. + +Strong brief copy. + +- "Sarah Lee, Director of Marketing at [Company], 200-500 employees, evaluating analytics tools to replace [current solution] within 60 days." + +What works. Specific; structured; gives rep enough to prepare. + +Weak brief copy. + +- "New booking from Sarah Lee." + +What fails. No context; rep starts cold despite the data being captured upstream. + +The discipline. Brief should be specific enough that the rep arrives ready. + +--- + +## Prep automation testing + +Verify the loop works. + +Test cases. + +- Booking happens; CRM record created; data populates. +- Booking happens; calendar invite shows the qualification data. +- Booking happens; Slack brief arrives at the right time. +- Edge case: prospect updates booking; prep updates accordingly. + +Production monitoring. If reps consistently arrive at calls cold, prep automation is broken somewhere. + +--- + +## Privacy and consent + +Prep automation involves handling user data. + +The principle. Data captured at booking flows to internal systems for prep. The prospect has implicitly consented to internal use through the booking. + +Limits. + +- Data should not flow to systems unrelated to the booking purpose. +- Account research should respect privacy norms. +- GDPR and other regulations apply. + +--- + +## Common prep automation failures + +No automation. Data captured; reps do not see it. + +CRM enrichment without rep CRM use. Data is in CRM; reps do not check CRM before calls. + +Slack brief lost in noise. Prep brief among 50 other Slack messages; rep misses. + +Calendar invite truncated. Invite description too long; reps see only opening. + +Stale account research. Research data from months ago. + +Brief copy generic. Brief contains data but not synthesized context. + +Updates after booking not propagated. Prospect updates info; prep stays old. + +No testing. Prep loop broken; nobody noticed. + +--- + +## Methodology-level choices that stay in the public skill + +The data-reaches-rep principle. Patterns A through E (CRM, calendar, Slack, research, hybrid). What to include in prep. Prep timing. Prep brief copy discipline. Prep automation testing. Privacy and consent. Common failures. + +## Implementation choices that stay internal + +Specific prep configurations for specific teams. Specific Slack templates and CRM custom fields. Specific research tooling. The team's privacy review processes. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/qualification-field-design.md b/skills/scheduler-and-booking-design/references/qualification-field-design.md new file mode 100644 index 0000000..ea83e3c --- /dev/null +++ b/skills/scheduler-and-booking-design/references/qualification-field-design.md @@ -0,0 +1,221 @@ +# Qualification field design + +Strong and weak qualification fields. The five-field rule. + +The fields decide the booking flow's friction and the call's quality. Done well, qualification produces context for the call without scaring off prospects; done poorly, it produces interrogation-gate dynamics. + +--- + +## The earns-its-place principle + +Each qualification field should serve one of two purposes: route the booking to the right rep, or give the rep enough context to skip the qualification phase of the call. Fields serving neither purpose are friction. + +The win. Four fields: company size, role, primary use case, timeline. Each routes or preps. Conversion is high; rep prep is concrete. + +The fail. Twelve fields including industry code, employee count range, marketing source, lead-source detail, gender. Most do not affect routing or prep; conversion drops 70 percent. + +The discipline. Audit each field. Cut fields that do not earn placement. + +--- + +## Strong qualification fields + +Patterns that earn placement. + +Company size or team size. + +Why it works. Routes to the right rep tier (SMB vs mid-market vs enterprise); enables segment tracking; concrete signal of fit. + +Format. Dropdown with bands ("1-10," "11-50," "51-200," "201-1000," "1000+"). + +Use case or primary goal. + +Why it works. Lets the rep prepare for the conversation that matches. + +Format. Dropdown with 5-7 use cases; or short open text if use cases are not enumerable. + +Current solution or stack. + +Why it works. Tells the rep where the prospect is starting; informs migration vs greenfield framing. + +Format. Dropdown of common alternatives plus "other" with text field. + +Timeline or urgency. + +Why it works. Routes to active-pipeline vs nurture; signals urgency to the rep. + +Format. Dropdown ("Within 30 days," "1-3 months," "3-6 months," "Just exploring"). + +Role or job function. + +Why it works. Lets the rep tailor framing; routes to specialist reps if role-aligned. + +Format. Dropdown of common roles; "Other" field for unusual cases. + +--- + +## Weak qualification fields + +Patterns that fail. + +Phone number. + +Why it fails. Often unnecessary if email and meeting time are captured. Reps can request phone in the call. Phone field adds friction without value for the booking itself. + +When to include. If the call is by phone (not video), phone is necessary. + +Generic comments box. + +Why it fails. Free-text rarely informs prep. Most prospects skip; some over-share; few provide useful context. + +When to include. Sparingly; if structured fields cannot capture the necessary context. + +Marketing data not used in the call. + +Why it fails. Industry codes, lead-source detail, etc. add friction without affecting the call's quality. + +When to include. Capture later (post-meeting follow-up form, CRM enrichment) rather than at the booking. + +Demographic data unrelated to the call. + +Why it fails. Gender, age, etc. rarely inform a B2B sales conversation. + +When to include. Almost never. Only if regulatory or product-specific reasons require. + +--- + +## The five-field rule + +Most production schedulers work well with 3-5 qualification fields. + +Why 3-5. + +- 3 fields is the minimum for useful qualification. +- 5 fields is the threshold beyond which drop-off climbs. +- Production data across many SaaS products supports this range. + +Exceptions. + +- Some enterprise sales contexts warrant 5-7 fields because the audience expects qualification. +- Some highly specialized products warrant fewer fields (1-2) because conversion volume matters more. + +The over-five trap. Each additional field beyond 5 reduces conversion meaningfully. The marginal value of field 6 rarely justifies the conversion cost. + +--- + +## Field ordering + +Within the form, the order matters. + +Open with low-friction. Identity fields (name, email) first. Familiar; easy. + +Build to value. Use-case or goal fields next. The prospect engages with what the call will be about. + +Save commitment for later. Timeline or budget fields late. The prospect has invested; harder ask is acceptable. + +End with optional. Comments or "anything else?" at the end if included. The prospect can leave or skip. + +--- + +## Field formats + +How each field captures input. + +Dropdowns. Best for categorical fields. Constrains responses; easy to route on. + +Text fields. For free-form fields (name, email, sometimes use case). + +Sliders. Rarely useful in qualification. + +Yes/No toggles. For binary qualifying questions (e.g., "Do you currently use a CRM?"). + +Conditional fields. Some fields appear based on earlier answers. Use sparingly; complexity adds maintenance. + +--- + +## Field validation + +What to validate. + +Email format. Standard validation; respect plus-aliases and international domains. + +Required vs optional. Mark explicitly. + +Length and character. Don't reject international names or non-Latin characters. + +The validation-strict failure. Validation that rejects valid inputs (international phone formats, plus-sign emails) loses real prospects. + +--- + +## Inferred vs asked fields + +What to ask vs what to infer. + +Ask sparingly. Each field is friction. + +Infer when possible. + +- Lead source: from URL parameters or referrer. +- Company info: from email domain. +- Geography: from IP or browser. +- Timezone: from browser. + +The discipline. If the system can infer a value reliably, do not ask. + +--- + +## Field-level analytics + +Track per-field drop-off. + +Per-field completion rate. Where in the form do prospects abandon? + +Diagnostic uses. + +- Specific field with high abandonment: friction at that field. +- Field rarely completed even by survivors: often signals the field can be cut. +- Specific segment abandons specific fields: segment-specific friction. + +The data informs which fields earn their place over time. + +--- + +## Field maintenance + +Fields decay. + +What decays. + +- Dropdowns with options that no longer match audience. +- Fields the rep team stopped using for prep. +- Fields whose routing logic changed without update. + +Maintenance cadence. Quarterly review of each field. Are reps using the data? Is routing connecting field-to-tier? + +--- + +## Common field failures + +Too many fields. Drop-off at the form. + +Fields not used. Captured but reps do not prep with them. + +Wrong field types. Free text where dropdown would route better. + +Validation too strict. Loses valid prospects. + +No analytics. Cannot tell which fields are working. + +Stale field options. Dropdowns no longer match audience. + +Fields asked that could be inferred. Friction without need. + +--- + +## Methodology-level choices that stay in the public skill + +The earns-its-place principle. Strong qualification fields (5 patterns). Weak qualification fields (4 patterns). The five-field rule. Field ordering. Field formats. Field validation. Inferred vs asked. Field-level analytics. Field maintenance. Common failures. + +## Implementation choices that stay internal + +Specific fields for specific schedulers. Specific dropdown options. Specific tooling for inference. The team's audit calendar. These vary by team and product. diff --git a/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md b/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md new file mode 100644 index 0000000..05b3b4d --- /dev/null +++ b/skills/scheduler-and-booking-design/references/reminder-sequence-patterns.md @@ -0,0 +1,256 @@ +# Reminder sequence patterns + +Confirmation, 24-hour, 1-hour, post-meeting. Frequency discipline. + +The communications around the booking. Done well, reminders reduce no-shows without becoming spam; done poorly, reminders are either insufficient (no-shows climb) or excessive (prospect resents). + +--- + +## The reduce-no-shows-without-spam principle + +Reminders matter; their volume should be calibrated. + +The win. Confirmation immediately after booking; one reminder 24 hours before; one reminder 1 hour before. Three communications total. No-show rate drops; prospects feel reminded but not nagged. + +The fail. Confirmation; 5-day reminder; 2-day reminder; 1-day reminder; 1-hour reminder; 15-minute reminder. Six communications. Prospects mute the channel; no-shows persist for users who muted. + +The discipline. Reminders earn their place; cumulative volume should be capped. + +--- + +## Pattern A: Booking confirmation + +Sent immediately after booking. + +What it includes. + +- Confirmed time and meeting type. +- Calendar invite attached. +- Brief restate of expectations (e.g., "Looking forward to learning about your X"). +- Reschedule and cancel links. + +Strengths. + +- Immediate; reduces buyer's remorse. +- Sets expectations. +- Provides reschedule path. + +Weaknesses. + +- One-touch communication. + +When to use. Always. + +--- + +## Pattern B: Pre-meeting reminder + +Sent 24 hours and/or 1 hour before. + +24-hour reminder. + +- Useful for users who book days in advance. +- Lets them prepare or reschedule with notice. + +1-hour reminder. + +- Useful for last-minute prep. +- Catches calendar drift. + +Both useful or one only? + +- Most production teams use both. +- For very short booking windows (same-day), 1-hour is enough. +- For longer-lead bookings, 24-hour matters. + +--- + +## Pattern C: Post-meeting follow-up + +Sent within hours of the call. + +What it includes. + +- Brief recap. +- Action items (rep's commitments). +- Resources mentioned in the call. +- Next-step CTA (next meeting, document, trial). + +Strengths. + +- Captures momentum from the call. +- Documents commitments. + +Weaknesses. + +- Requires rep to populate after the call (or rep-side tooling to auto-generate). + +When to use. Sales conversations where next steps matter. + +--- + +## Pattern D: Reschedule prompts + +When the prospect cannot make the meeting. + +What it includes. + +- Easy reschedule link. +- Brief check-in copy ("Need to reschedule? No problem."). + +Strengths. + +- Reduces no-shows; users reschedule rather than ghost. + +Weaknesses. + +- Some users use this to reschedule indefinitely. + +When to use. Always available; not aggressive. + +--- + +## Pattern E: No-show follow-up + +When the prospect does not attend. + +What it includes. + +- Acknowledgment of missed meeting. +- Reschedule link. +- Brief context-restatement. + +Tone. Gentle, not punitive. The prospect may have had a real reason. + +The respect-the-no-show principle. After 1-2 reschedule attempts, accept that the prospect is not engaging. + +--- + +## Reminder timing + +When each communication fires. + +Common cadence. + +- T+0: Confirmation immediately after booking. +- T-24h: Reminder 24 hours before. +- T-1h: Reminder 1 hour before. +- T+15m: Late-arrival check (sometimes). +- T+24h: Post-meeting follow-up. + +The discipline. Each communication earns its place. Drop the ones that do not. + +--- + +## Channel choice + +Which channels to use. + +Email. Default. Reliable; familiar. + +SMS. Higher attention; more friction. Use selectively for high-value bookings. + +In-app notification. If the booking is for a logged-in user, in-app reminders work. + +Slack or Teams. For B2B internal-team meetings. + +The cumulative discipline. Multiple channels for the same reminder is excessive. Pick one channel per reminder. + +--- + +## Reminder copy + +What the reminders say. + +Strong reminder copy. + +- "Looking forward to our call tomorrow at 2 PM PT. Here's what we'll cover: [agenda]." +- "Reminder: 1 hour until our call. Join here: [link]." +- "Thanks for the call today. Here's what we discussed: [recap]." + +What works. Specific; useful; brief. + +Weak reminder copy. + +- "Don't forget your meeting!" +- "Your meeting is in 1 hour." +- "Did you know..." + +What fails. Generic; no value-add; just a notification. + +--- + +## Reminder personalization + +How much to personalize. + +Default personalization. Name; meeting time; rep name. + +Strong personalization. Brief context tied to qualification ("Looking forward to discussing your [use case] situation"). + +Over-personalization. Long personalized paragraphs that read as marketing. + +The discipline. Personalize where it adds value; do not pad with personalization for its own sake. + +--- + +## Reminder analytics + +Track effectiveness. + +Metrics. + +- Open rate per reminder. +- Reschedule rate per reminder. +- No-show rate (cumulative across cadence). +- Cancellation rate. + +Diagnostic uses. + +- Low open rate: subject line weak or channel wrong. +- High reschedule rate after specific reminder: that reminder triggers reconsideration. +- High no-show despite reminders: friction at the meeting itself, not the reminder. + +--- + +## Reminder maintenance + +Reminders decay. + +What decays. + +- Templates with stale rep names or roles. +- Calendar links that broke after platform changes. +- Channel preferences that no longer fit audience. + +Maintenance cadence. Quarterly review of reminder templates and channels. + +--- + +## Common reminder failures + +Too many reminders. Cumulative volume is spam; users mute. + +Too few reminders. No-show rate climbs. + +Generic copy. No value; users dismiss. + +Wrong channel. SMS for an audience that prefers email. + +Stale templates. Rep names from former employees; broken calendar links. + +No post-meeting follow-up. Conversation momentum lost. + +Aggressive no-show follow-up. Multiple reminder attempts after a no-show; respect non-response. + +Personalization padding. Long personalized text that reads as marketing. + +--- + +## Methodology-level choices that stay in the public skill + +The reduce-no-shows-without-spam principle. Patterns A through E (confirmation, pre-meeting, post-meeting, reschedule, no-show). Reminder timing. Channel choice. Reminder copy discipline. Reminder personalization. Reminder analytics. Reminder maintenance. Common failures. + +## Implementation choices that stay internal + +Specific reminder cadences for specific teams. Specific copy in brand voice. Specific channel choices. The team's no-show baselines. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md b/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md new file mode 100644 index 0000000..081a420 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/reschedule-and-no-show-handling.md @@ -0,0 +1,241 @@ +# Reschedule and no-show handling + +Reschedule patterns, no-show patterns, respect-the-no principle. + +What happens when meetings do not go to plan. Done well, reschedule and no-show handling protect the relationship and capture re-engagement; done poorly, they punish the prospect for ordinary life events. + +--- + +## The respect-the-no principle + +Prospects who reschedule or no-show often have real reasons. Handling should be gentle, not punitive. + +The win. Prospect no-shows; gentle follow-up offers easy reschedule. Prospect reschedules once; offered again at a new convenient time. After two no-shows, the system stops aggressive pursuit and routes to nurture. + +The fail. Prospect no-shows; system fires three reminder emails over two days; phone call follows; prospect feels harassed. + +The discipline. Acknowledge that life intervenes; offer a path back; do not pressure. + +--- + +## Reschedule patterns + +When prospects need to change the meeting. + +Pattern A: Self-serve reschedule. + +How it works. The booking confirmation includes a reschedule link. Prospect clicks; sees new availability; selects new slot. + +Strengths. No friction; respect for the prospect's time. + +Weaknesses. Some abuse possible (repeated reschedules). + +When to use. Default for most schedulers. + +Pattern B: Reschedule preserves qualification data. + +How it works. Reschedule keeps all the qualification info; rep does not lose context. + +Strengths. Reschedule does not cost prep work. + +Weaknesses. None significant. + +When to use. Always. + +Pattern C: Reschedule notifies the rep. + +How it works. When prospect reschedules, rep gets notified. Original calendar slot freed up. + +Strengths. Rep can use the freed slot. + +Weaknesses. None. + +When to use. Always. + +Pattern D: Reschedule limits. + +How it works. After N reschedules, the system flags the booking for review or routes to nurture. + +Strengths. Prevents abuse. + +Weaknesses. Risks alienating prospects with legitimate scheduling difficulty. + +When to use. Sparingly; usually 3+ reschedules before flagging. + +--- + +## No-show patterns + +When prospects do not attend. + +Detection. + +- Rep reports no-show after the meeting time. +- System detects unattended meeting (if integrated with video platform). +- Manual reports from CS or sales ops. + +Pattern A: Single follow-up. + +How it works. Within 4-24 hours of the no-show, send a single gentle email offering reschedule. + +Strengths. Catches genuine forgetfulness. + +Weaknesses. Single touch may not catch users on vacation. + +When to use. Default. + +Pattern B: Two-touch follow-up. + +How it works. First email immediate. Second email 3-5 days later if no response. + +Strengths. Catches prospects who were genuinely busy. + +Weaknesses. Risks feeling persistent. + +When to use. Higher-value bookings where multi-touch is justified. + +Pattern C: Sales-led recovery. + +How it works. For high-value no-shows, sales rep reaches out personally. + +Strengths. Most engaging; can recover the relationship. + +Weaknesses. Expensive; only viable for high-value accounts. + +When to use. Enterprise no-shows or accounts with strategic value. + +Pattern D: Async route. + +How it works. Send the no-show prospect resources or content rather than another booking attempt. Re-engagement deferred. + +Strengths. Respects the no-show as a signal. + +Weaknesses. May lose prospects who would have rebooked. + +When to use. After 1-2 unsuccessful reschedule attempts. + +--- + +## Reschedule cadence + +How often to retry. + +Single reschedule attempt: offer once; respect non-response. + +Multiple attempts: at most 2 attempts spaced 3-7 days apart. Stop after that. + +No reschedule attempts: for bookings flagged as low-fit; route to nurture. + +The discipline. Each reschedule attempt earns its place. Cumulative attempts become harassment. + +--- + +## When to abandon reschedule + +Some no-shows should be respected as final. + +Signals to stop. + +- Prospect explicitly asked to stop contact. +- Multiple no-shows from same prospect. +- No response to 2 reschedule attempts. +- Email bounced or unsubscribed. + +The respect-the-pattern principle. Multiple no-shows often signal the prospect's needs changed. Continuing pursuit damages the brand. + +--- + +## No-show flow design + +The full sequence. + +T+0 (no-show happens). + +- Rep marks no-show in CRM. +- Free the calendar slot. + +T+4-24h (first follow-up). + +- Email: "Sorry we missed you. Want to reschedule? [Link]." + +T+3-5d (second follow-up if needed). + +- Email: "We're still interested in connecting if your schedule changed. Here's the reschedule link." + +T+10d (final attempt or async route). + +- Send relevant content; surface re-engagement option without pressure. + +T+30d+. + +- Treat as nurture; pursue through other channels (email newsletter, content). + +The cadence respects multiple touchpoints without becoming aggressive. + +--- + +## No-show analytics + +Track patterns. + +Per-segment no-show rate. + +- Different sources, sizes, or use cases may no-show at different rates. + +Per-rep no-show rate. + +- Some reps may correlate with higher no-shows (timing, time zone, prep gaps). + +Reschedule conversion rate. + +- Of rescheduled bookings, what percentage attend. + +Diagnostic uses. + +- High overall no-show: reminder sequence weak or commitment friction at booking too low. +- Specific segment no-shows more: that segment may need different cadence. +- Specific rep no-shows more: their availability or prep may be off. + +--- + +## Time zone and travel mistakes + +Common reasons for no-shows that are not the prospect's fault. + +Prevention. + +- Display time zone clearly at booking. +- Calendar invites include time zone. +- Reminders include time zone. + +The cure for time zone mistakes. Quick reschedule; do not penalize. + +--- + +## Common reschedule and no-show failures + +Aggressive recovery. Multiple touches over short periods; harassment. + +Reschedule limits too tight. Genuine prospects flagged after 2 reschedules; lost. + +Reschedule loses qualification data. Rep loses context on reschedule. + +No reschedule path. Prospect cannot reschedule; ghosts instead. + +No-show no follow-up. Prospect's missed meeting is just lost; could have rebooked. + +Punitive copy. No-show follow-up shames the prospect. + +Time zone confusion. Prospect missed because of time zone error; system blames the prospect. + +Stale reschedule links. Link works at booking; broken later. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-no principle. Reschedule patterns A through D. No-show patterns A through D. Reschedule cadence. When to abandon. No-show flow design. No-show analytics. Time zone considerations. Common failures. + +## Implementation choices that stay internal + +Specific reschedule limits for specific teams. Specific follow-up cadences. Specific copy in brand voice. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/routing-patterns.md b/skills/scheduler-and-booking-design/references/routing-patterns.md new file mode 100644 index 0000000..fe64b71 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/routing-patterns.md @@ -0,0 +1,235 @@ +# Routing patterns + +By size, use case, geography, language, account ownership. Unrouted-lead default. + +The specific routing rules that translate qualification answers into rep assignments. Done well, routing matches lead to rep cleanly; done poorly, leads bounce around or land on wrong reps. + +--- + +## Routing-by-company-size + +The most common routing axis. + +Pattern. + +- 1-50 employees: SDR or self-serve. +- 51-500 employees: AE. +- 501-2000 employees: senior AE. +- 2000+ employees: enterprise AE. + +Why it works. Different sizes have different sales motions; rep tier should match. + +Failure modes. + +- Size bands set years ago; team scaled; bands no longer right. +- Size data missing or stale. +- Solo founders with backed companies appear "small" but warrant senior treatment. + +--- + +## Routing-by-use-case + +Different specialists for different product use cases. + +Pattern. + +- Use case A: rep with A specialty. +- Use case B: rep with B specialty. +- General use case: any AE. + +Why it works. Specialists arrive with deeper context; conversion higher. + +Failure modes. + +- Specialist becomes bottleneck. +- New use cases without assigned specialist. +- Use case overlap; multiple specialists could fit. + +--- + +## Routing-by-geography + +Different reps for different regions or time zones. + +Pattern. + +- Americas: US-based AEs. +- EMEA: European AEs. +- APAC: APAC AEs. + +Why it works. Time zone alignment; cultural fit; language fit. + +Failure modes. + +- Insufficient coverage in some regions. +- Cross-region accounts confuse routing. +- Geography data missing or wrong. + +--- + +## Routing-by-language + +Native-language reps for non-English-primary leads. + +Pattern. + +- English-primary: US/UK AEs. +- Spanish-primary: Spanish-speaking AEs. +- Etc. + +Why it works. Native-language conversation produces better calls. + +Failure modes. + +- Incomplete language coverage. +- Multi-language leads bounce. +- Language inferred wrong from email or location. + +--- + +## Routing-by-account-ownership + +If the lead's company is already in pipeline or a customer, route to the owning AE. + +Pattern. + +- Detect domain match against CRM. +- If match, route to AE who owns the account. +- If no match, default routing. + +Why it works. Account owner has context; avoids confusion. + +Failure modes. + +- Domain detection misses subsidiaries or aliases. +- Account ownership stale (former AE). +- New lead from existing account but for unrelated use case. + +--- + +## Routing-by-source + +Different reps for different lead sources (paid, organic, partner, referral). + +Pattern. + +- Partner-sourced leads: partner-channel AE. +- Paid-sourced leads: marketing-aligned AEs. +- Organic-sourced: general AEs. + +Why it works. Different sources signal different commitment; specialists handle differently. + +Failure modes. + +- Source data missing or attribution wrong. +- Paid traffic includes high-fit leads who would have come organically. + +--- + +## Routing-by-tier + +Combining size, use case, and other signals into a tier score. + +Pattern. + +- Lead score 80-100: senior AE. +- Lead score 50-79: AE. +- Lead score 0-49: SDR or async. + +Why it works. Single score combines multiple signals. + +Failure modes. + +- Score model out of date. +- Score thresholds wrong for current capacity. +- Score data incomplete; defaults dominate. + +--- + +## The unrouted-lead default + +Some leads do not fit obvious routing. + +Patterns for default. + +- Round-robin among all available reps. Simple. +- Catchall AE. One rep gets all unrouted leads. +- Async or self-serve. Lead goes to a self-serve resource if no obvious rep. + +The discipline. Default rule should be explicit. Unrouted leads should not silently fail or bounce. + +--- + +## Routing transparency + +Prospect-side vs rep-side visibility. + +Prospect-side. Generally, prospects do not see routing logic. They see a calendar with available times. + +Rep-side. Reps should see why they were assigned (lead score, fit signals). Helps with prep. + +Anti-pattern. Routing happens silently; rep does not know what made this lead route to them. + +--- + +## Routing changes and team transitions + +When the team changes, routing must follow. + +Common transitions. + +- Rep leaves; their accounts and routing reassign. +- New rep hires; routing weights adjust. +- Tier restructure (rep promoted from SDR to AE). +- Specialty changes. + +The maintenance discipline. Routing rules update as team changes. Stale routing can route leads to absent reps. + +--- + +## Routing analytics + +Track routing effectiveness. + +Metrics. + +- Per-rep booking volume. +- Per-rep conversion (booking-to-sale). +- Per-route conversion (route x → sale rate). +- Routing override rate (manual reassignments). + +Diagnostic uses. + +- Per-rep volume uneven without reason: routing logic skewing. +- Per-route conversion uneven: routing matching wrong. +- High override rate: routing logic not capturing real fit. + +--- + +## Common routing failures + +Routing data missing. Qualification did not capture; routing defaults dominate. + +Stale routing rules. Team changed; rules did not. + +Stale rep weights. Performance scores from quarters ago. + +Account-ownership detection wrong. Subsidiary leads route to unfit AE. + +Specialty routing without specialty data. Specialty-based routing requires tagging; tags miss. + +Default rule unclear. Unrouted leads silently fail. + +Routing override frequent. Reps reassign manually; routing logic does not match reality. + +Round-robin for tiered team. High-fit leads land on junior reps. + +--- + +## Methodology-level choices that stay in the public skill + +Routing patterns by size, use case, geography, language, account ownership, source, tier. The unrouted-lead default. Routing transparency. Team transitions. Routing analytics. Common failures. + +## Implementation choices that stay internal + +Specific routing rules for specific teams. Specific size bands and tier thresholds. Specific tooling. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md b/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md new file mode 100644 index 0000000..6b3c225 --- /dev/null +++ b/skills/scheduler-and-booking-design/references/scheduler-anti-patterns.md @@ -0,0 +1,209 @@ +# Scheduler anti-patterns + +The patterns that look like schedulers but degrade conversion. Anti-patterns are easy to ship; the cost shows up in booking conversion, downstream call quality, and brand reputation. + +--- + +## The any-time-friction scheduler + +The pattern. Generic booking link with no qualification. + +The signal. Reps show up cold; downstream demo-to-sale conversion poor. + +The cost. Sales capacity used inefficiently; call quality suffers. + +The cure. Add 3-5 qualification fields; route to right rep tier; deliver prep to reps. + +--- + +## The interrogation-gate scheduler + +The pattern. 12-field qualification form before booking. + +The signal. 90 percent drop-off at the form. + +The cost. Lose conversions from would-be buyers; only the most committed survive the form. + +The cure. Cut to 3-5 fields; defer additional questions to in-call or post-meeting. + +--- + +## The wrong-rep-tier scheduler + +The pattern. Round-robin routing for tiered team. + +The signal. Enterprise leads land on SDRs; SDRs unprepared; conversion drops. + +The cost. High-value leads get junior reps; senior reps underutilized. + +The cure. Fit-based routing tied to qualification. + +--- + +## The no-prep-automation scheduler + +The pattern. Qualification captured but not delivered to reps. + +The signal. Reps start calls cold despite qualification data existing. + +The cost. Qualification work wasted; cold-call dynamics return. + +The cure. CRM enrichment, calendar invite enrichment, Slack briefs. + +--- + +## The no-buffer scheduler + +The pattern. Back-to-back meetings without buffer time. + +The signal. Reps run late; calls feel rushed; quality drops. + +The cost. Reps stressed; calls poorer; conversion suffers. + +The cure. 10-15 minute buffer between meetings. + +--- + +## The no-capacity-cap scheduler + +The pattern. Reps booked solid all day every day. + +The signal. Quality drops; rep burnout. + +The cost. Calls that book are lower quality; reps eventually leave. + +The cure. Cap meetings per day per rep (3-5 typical). + +--- + +## The time-zone-confused scheduler + +The pattern. Times shown in rep's time zone; prospect has to convert mentally. + +The signal. Wrong-time bookings; no-shows from time zone errors. + +The cost. Prospects miss meetings; assume their fault. + +The cure. Auto-detect prospect time zone; display explicitly. + +--- + +## The aggressive-reminder scheduler + +The pattern. Multiple reminders per booking (5+ touchpoints). + +The signal. Prospects mute or unsubscribe; reminder effectiveness drops. + +The cost. Reminders trained to be ignored; no-shows persist. + +The cure. Two reminders typical (24-hour, 1-hour). Cap cumulative volume. + +--- + +## The aggressive-no-show-recovery scheduler + +The pattern. Multiple reschedule attempts over short period. + +The signal. Brand earns harassment reputation; recovery rate drops. + +The cure. One-to-two reschedule attempts max; respect non-response. + +--- + +## The aggressive-cancellation-prevention scheduler + +The pattern. Cancellation requires multi-step or contact with sales. + +The signal. Public complaints; trust damage. + +The cost. Reputation harm; sometimes regulatory issues. + +The cure. Self-serve cancellation; one click. + +--- + +## The unmaintained scheduler + +The pattern. Routing rules from years ago; team changed; rules did not. + +The signal. Leads route to absent reps; bookings sit unread. + +The cure. Quarterly maintenance. Team transitions trigger routing updates. + +--- + +## The mobile-broken scheduler + +The pattern. Booking flow works on desktop; breaks on mobile. + +The signal. Mobile conversion half of desktop. + +The cost. Mobile audience underserved. + +The cure. Mobile-first design and testing. + +--- + +## The double-booking scheduler + +The pattern. Calendar integration broken; multiple bookings for same time. + +The signal. Reps and prospects both arrive; one waits or leaves. + +The cost. Rep frustration; prospect confusion; brand damage. + +The cure. Calendar integration tested. Buffer time. Conflict detection. + +--- + +## The shared-link bypass scheduler + +The pattern. Reps share generic booking links alongside structured flow. + +The signal. Routing logic bypassed; cold demos return. + +The cost. Investment in qualification and routing partially undone. + +The cure. Disable generic links. Train reps to use structured links. + +--- + +## The integration-brittle scheduler + +The pattern. Calendar, CRM, or video integration breaks frequently. + +The signal. Reps complain about manual workarounds. + +The cost. Operational friction; data inconsistency. + +The cure. Stable integrations; monitoring; rollback plans. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of scheduler portfolio. + +Audit questions. + +- Is qualification calibrated (anti-pattern check: any-time-friction, interrogation-gate)? +- Does routing match team tier (anti-pattern check: wrong-rep-tier)? +- Does prep automation deliver (anti-pattern check: no-prep-automation)? +- Is calendar logic sound (anti-pattern check: no-buffer, no-capacity-cap, double-booking)? +- Are reminders calibrated (anti-pattern check: aggressive-reminder)? +- Is no-show recovery respectful (anti-pattern check: aggressive-no-show-recovery)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does the system work on mobile (anti-pattern check: mobile-broken)? +- Are integrations stable (anti-pattern check: integration-brittle)? + +The retire decision. Anti-pattern schedulers warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing. Cures matched. Audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and lessons learned. Specific portfolio audit results. The team's audit calendar. These vary by team. diff --git a/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md b/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md new file mode 100644 index 0000000..62327fe --- /dev/null +++ b/skills/scheduler-and-booking-design/references/scheduler-decision-criteria.md @@ -0,0 +1,175 @@ +# Scheduler decision criteria + +When schedulers earn the build vs when forms or sales-pipeline tools serve. + +A scheduler is meaningful work. Qualification logic, availability rules, routing, prep automation, follow-up sequences, ongoing maintenance. The scheduler earns this investment only when specific conditions are present. + +--- + +## When schedulers earn the build + +Five conditions that, when present, make a scheduler a strong investment. + +The conversion goal is a meeting. Demo, sales call, consultation. Email-only or trial-signup conversions do not need a scheduler. + +The audience is willing to commit time. Schedulers ask for a calendar slot; not all audiences are ready for that. Top-of-funnel awareness audiences are usually not ready; consideration-stage audiences often are. + +The team has enough capacity to handle scheduled meetings. Without capacity, scheduled meetings produce wait times that erode conversion. Reps booked solid for two weeks lose conversions to faster competitors. + +The team can support qualification logic and routing. Without these, a generic booking link is the result. Generic booking links produce cold demos. + +The success metric is defined. Booking conversion, demo-to-sale conversion, no-show rate, call quality (often measured via rep self-reports). Without the success metric, evaluation is impossible. + +When all five are present, a scheduler is strong investment. When two or fewer are present, simpler tools (contact forms, sales pipeline outreach) often serve better. + +--- + +## When schedulers do NOT earn the build + +Funnels where the scheduler is the wrong tool. + +The conversion goal is a download or signup. Use forms (covered by `multi-step-form-design`) or magnet flows (covered by `lead-magnet-design`). + +The audience volume is too low. A handful of bookings per month does not need routing infrastructure; a contact form may serve better. + +The team's capacity is variable and routing cannot reflect it. Scheduling without capacity awareness produces booked-too-tight or booked-too-loose patterns; both fail. + +A simpler contact form would serve. Inbound leads where sales does outbound contact may not need a scheduler; the prospect just provides info; the rep reaches out. + +The audience prefers async communication. Some audiences (technical buyers, asynchronous teams) prefer email or document exchange to scheduled calls. + +The honest assessment matters. Schedulers are sometimes the wrong tool even when the team has capacity to build them. + +--- + +## Schedulers vs forms + +Both capture lead info; they differ in commitment. + +Form strengths. + +- Lower commitment from the prospect. +- Higher top-of-funnel volume. +- Suitable for any conversion type (download, demo request, contact). + +Form weaknesses. + +- No automatic time commitment. +- Requires sales follow-up to schedule. +- Wait time between form submission and meeting. + +Scheduler strengths. + +- Time committed at booking; no scheduling delay. +- Higher prospect commitment signal. +- Direct conversion to a calendar slot. + +Scheduler weaknesses. + +- Higher friction; not all prospects ready. +- Requires capacity to handle bookings. +- Routing complexity. + +The choice. When the conversion is a meeting and the audience is consideration-stage, scheduler. When the conversion is more open or the audience is awareness-stage, form. + +--- + +## Schedulers vs sales-pipeline tools + +For B2B sales, alternatives exist. + +Sales pipeline strengths. + +- Sales-led; rep makes contact on their schedule. +- Can prioritize based on fit before reaching out. + +Sales pipeline weaknesses. + +- Slower response. +- Higher acquisition cost per booking. + +Scheduler advantages. + +- Self-serve; faster response. +- Lower acquisition cost. + +The combined approach. Many production teams use both: scheduler for self-serve high-intent leads; sales pipeline for outbound and complex deals. + +--- + +## The opportunity-cost frame + +A scheduler is significant work. Account for it. + +The build cost. Qualification logic, availability rules, routing, prep automation, reminder sequences, integration with CRM and calendar, mobile responsiveness. A meaningful scheduler often takes 40-150 engineering hours plus operational setup. + +The maintenance cost. Routing rules update as team changes; integrations need maintenance. Quarterly review and updates run 4-8 hours. + +The opportunity cost. What else could the team have built? A simpler contact form, a better sales-led process, direct outreach. The scheduler has to clear the bar of those alternatives. + +The decision frame. Scheduler earns investment when it produces more meeting volume at acceptable quality than alternatives. + +--- + +## Decision worked example + +A B2B SaaS with 50 demo requests per week. + +Conditions check. + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes (mid-market audience). +- Team capacity: yes; 4 reps with capacity for 12-15 demos per week each. +- Qualification and routing supported: yes; reps differ by industry vertical. +- Success metric defined: booking conversion, demo-to-trial within 14 days. + +Decision. Build the scheduler. The conditions warrant it. + +Architecture. 4-field qualification (size, role, use case, timeline); fit-based routing (enterprise to senior AE, mid-market to AE, SMB to SDR); CRM enrichment and Slack brief for prep automation. + +Maintenance commitment. Quarterly review; team-change updates as part of onboarding. + +The decision was deliberate, not default. + +--- + +## Decision worked example: when to choose differently + +A consumer-facing financial advisory company with 5 inbound consultations per week. + +Conditions check. + +- Conversion goal is a meeting: yes. +- Audience willing to commit time: yes. +- Team capacity: yes (3 advisors). +- Qualification and routing supported: not really; advisors are interchangeable. +- Volume justifies scheduler infrastructure: low. + +Decision. Do not build a custom scheduler. Use a generic booking link with a brief 2-field qualification form. The volume does not justify routing infrastructure; the simplicity is fine. + +The decision was right-sized. + +--- + +## When to retire a scheduler + +Schedulers can become wrong over time. + +Retire-or-redesign when: + +- Conversion has dropped below baseline consistently and refinements have not moved it. +- Team structure changed; routing logic no longer fits. +- Volume changed; infrastructure no longer matches need. +- Integration with CRM or calendar has broken repeatedly. + +The retire-or-redesign discipline frees capacity. + +--- + +## Methodology-level choices that stay in the public skill + +The five conditions that warrant schedulers. The five conditions that argue against. Schedulers vs forms. Schedulers vs sales-pipeline tools. The opportunity-cost frame. Decision worked examples (yes and no). The retire decision. + +## Implementation choices that stay internal + +Specific scheduler decisions for specific teams. The team's capacity benchmarks. Specific tooling. Specific success-metric baselines. These vary by team and product. diff --git a/skills/security-baseline/SKILL.md b/skills/security-baseline/SKILL.md new file mode 100644 index 0000000..bd3f1ec --- /dev/null +++ b/skills/security-baseline/SKILL.md @@ -0,0 +1,296 @@ +--- +name: security-baseline +description: "Establish a security baseline for a website or web app. Use this skill when configuring HTTPS and TLS, setting security headers, planning secrets management, evaluating CSP policies, doing a basic security audit, or hardening a site before launch. Triggers on security headers, HTTPS, TLS, CSP, content security policy, HSTS, secrets management, vulnerability scan, security audit, harden, OWASP, security baseline. Also triggers when a security review is required for compliance or before going live." +category: operations +catalog_summary: "HTTPS, security headers, CSP, secrets management, vulnerability scans" +display_order: 7 +--- + +# Security Baseline + +Establish the security floor for any production website or web app. Stack-agnostic. Covers the things that should be in place before public launch and verified periodically after. + +--- + +## When to use + +- Pre-launch security review +- Setting up a new site or environment +- Periodic security audit (quarterly recommended) +- Onboarding a new vendor or third-party integration +- Responding to a security finding or report +- Hardening after an incident + +## When NOT to use + +- Active incident response (use `incident-response`) +- Code-level security review (use `code-review-web`) +- Email-specific authentication (SPF/DKIM/DMARC) (use `email-deliverability`) +- DNS-level security (CAA, DNSSEC) (use `domain-strategy`) +- Performance-related security (DDoS protection sizing) (use `performance-optimization`) + +--- + +## Required inputs + +- The site or app in scope (URLs, environments) +- The hosting platform and CDN +- Authentication method (if any) +- Third-party scripts and integrations +- Compliance context (PCI, SOC2, GDPR, etc., if applicable) +- Existing security tooling + +--- + +## The framework: 6 layers + +Security is layered. Each layer addresses a different attack surface. + +### Layer 1: Transport security + +How data moves from server to client. + +- HTTPS everywhere. No HTTP variants serving content. +- TLS 1.2 minimum, TLS 1.3 preferred. Disable TLS 1.0 and 1.1. +- HSTS (Strict-Transport-Security) header set, with `includeSubDomains` and `preload` for high-confidence sites. +- Strong cipher suites only. Modern browsers handle this if you pick a modern config from your provider. +- Certificates from a trusted CA, monitored for expiration. + +### Layer 2: Response headers + +What the browser is told about your site. + +\| Header \| Purpose \| Default value \| +\|---\|---\|---\| +\| `Strict-Transport-Security` \| Force HTTPS \| `max-age=31536000; includeSubDomains` \| +\| `Content-Security-Policy` \| Restrict resource loading \| Site-specific \| +\| `X-Content-Type-Options` \| Prevent MIME sniffing \| `nosniff` \| +\| `X-Frame-Options` \| Clickjacking protection \| `DENY` or `SAMEORIGIN` \| +\| `Referrer-Policy` \| Control referrer info \| `strict-origin-when-cross-origin` \| +\| `Permissions-Policy` \| Control browser features \| Site-specific (camera, mic, etc.) \| +\| `Cross-Origin-Opener-Policy` \| Process isolation \| `same-origin` (where compatible) \| +\| `Cross-Origin-Embedder-Policy` \| Cross-origin restrictions \| `require-corp` (where applicable) \| + +CSP deserves its own attention. See the framework section below. + +### Layer 3: Authentication and authorization + +How users prove who they are and what they can do. + +- Strong password requirements (length over complexity rules; allow long passphrases) +- Account lockout or rate limiting on login +- 2FA available, required for admin accounts +- Session tokens: short-lived, secure, HttpOnly cookies +- Logout invalidates tokens server-side, not just client-side +- Password reset flows that don't reveal account existence +- Authorization checked on every request (don't rely on UI hiding) + +### Layer 4: Input handling + +How untrusted input is processed. + +- Validate on the server (client validation is UX, not security) +- Parameterized queries for any database access (no string concatenation into SQL) +- Output encoding by context (HTML, JS, URL, CSS) +- File upload restrictions (type, size, location, scanning) +- Rate limiting on endpoints that could be abused +- CSRF tokens on state-changing requests + +### Layer 5: Secrets management + +Where credentials and keys live. + +- No secrets in code, config files in repos, or environment variables baked into images +- Secrets in a dedicated secrets manager +- Different secrets per environment (no shared dev/prod secrets) +- Rotation schedule documented and followed +- Audit log of secret access +- Limited blast radius (each service has its own credentials, scoped narrowly) + +### Layer 6: Operational security + +How the team operates. + +- Access controls reviewed quarterly (offboard immediately on departure) +- 2FA enforced on every admin account (hosting, DNS, registrar, code host, deploy tools) +- Audit logs enabled and reviewed +- Vulnerability scanning (dependencies, containers, infrastructure) +- Patch cadence defined +- Incident response runbook exists (see `incident-response`) +- Backups exist and are tested (see `backup-and-disaster-recovery`) +- Security contact published (security.txt at /.well-known/security.txt) + +--- + +## Content Security Policy + +CSP is the most powerful response header and the most often misconfigured. Worth its own treatment. + +### What CSP does + +CSP tells the browser which sources are allowed for various resource types: scripts, styles, images, frames, connections, etc. A strict CSP prevents most XSS attacks even when input handling has bugs. + +### Two flavors + +Strict CSP (recommended): uses `nonce-` or `hash-` based source allowlists. Inline scripts must be explicitly allowed via nonce. + +``` +Content-Security-Policy: script-src 'self' 'nonce-{random}' 'strict-dynamic'; object-src 'none'; base-uri 'self'; +``` + +Allowlist CSP (legacy): lists allowed domains. Easier to set up, much weaker. + +``` +Content-Security-Policy: script-src 'self' https://trusted.com; ... +``` + +Strict CSP requires application changes (every inline script needs a nonce). The investment pays off. + +### Roll out CSP gradually + +1. Start with `Content-Security-Policy-Report-Only` to log violations without blocking. +2. Set up a violation report endpoint. +3. Watch for legitimate violations (third-party scripts, inline handlers). +4. Tune the policy. +5. Switch to enforcing mode once violations are mostly false positives. +6. Continue monitoring violation reports for new issues. + +### Common CSP mistakes + +- `unsafe-inline` in script-src. Defeats most of CSP's value. +- `unsafe-eval` in script-src. Often required by older libraries; refactor or replace. +- Wildcard sources (``). Defeats the policy. +- Allowing CDNs that host arbitrary user content. Attackers can upload scripts to the CDN. +- Not restricting `frame-ancestors`. Use this for clickjacking defense (more flexible than `X-Frame-Options`). + +--- + +## Workflow + +### Step 1: Run a baseline scan + +Use a free scanner: securityheaders.com, observatory.mozilla.org. Get a current grade. This is the floor. + +### Step 2: Inventory the surface + +- Domains and subdomains in scope +- Public endpoints (forms, APIs) +- Authentication entry points +- Admin interfaces +- Third-party integrations and their permissions + +### Step 3: Audit each layer + +Walk the 6 layers. For each, document: +- What's in place +- What's missing +- Risk level (high, medium, low) + +### Step 4: Prioritize + +High risk, easy fixes go first: +- HSTS not set +- Default headers missing +- Admin without 2FA +- Old TLS versions enabled + +Medium risk, medium fixes next: +- CSP rollout +- Input validation gaps +- Secret management improvements + +Low risk, nice-to-haves last: +- Permissions-Policy refinements +- Optional headers (Cross-Origin- family) + +### Step 5: Implement and verify + +For each fix: +- Make the change +- Test in a non-production environment +- Verify with a scanner +- Roll out +- Re-verify in production + +### Step 6: Set up monitoring + +- Certificate expiration alerts +- CSP violation reporting +- Failed login monitoring +- Unusual admin activity alerts +- Dependency vulnerability alerts (Dependabot, Snyk, or equivalent) + +### Step 7: Document the baseline + +Write a security baseline document. It says what's expected on every site: +- Required headers +- Required configurations +- Required practices + +New sites get audited against this. Existing sites get re-audited periodically. + +### Step 8: Schedule review + +Quarterly is the floor. Add reviews after major changes or incidents. + +--- + +## Common compliance touchpoints + +Not legal advice. Surfaces where security baseline meets compliance requirements: + +- PCI DSS (if handling payment cards): much more involved than baseline. The baseline is a starting point, not sufficient. +- SOC 2: baseline aligns with most CC controls (CC6 series). Documented baseline plus evidence of execution is the audit ask. +- GDPR / privacy regs: baseline supports security obligations (Article 32). Privacy is broader than security. +- HIPAA, HITRUST, FedRAMP: baseline is necessary, far from sufficient. Get specialized help. + +When compliance applies, the baseline is necessary but not the full answer. + +--- + +## Failure patterns + +HSTS without `includeSubDomains`. Attacker tricks browser into HTTP on a subdomain you haven't HTTPS'd yet. + +HSTS preload without commitment. Once preloaded, removing it takes weeks. Don't preload until HTTPS is solid across all subdomains forever. + +CSP with `unsafe-inline`. Defeats most of CSP. Either go strict (nonce-based) or accept that CSP is providing limited protection. + +Default headers missing. `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` are easy and free. Set them. + +Admin without 2FA. The single most common high-impact vulnerability across small teams. Fix today. + +Secrets in environment variables baked into images. Anyone with image access has the secrets. Use a runtime secret manager. + +No security.txt. Researchers find issues; they need somewhere to report. Publish a security.txt at /.well-known/security.txt. + +Old TLS versions enabled. Disable TLS 1.0 and 1.1. Most providers offer this as a checkbox. + +CDN allowing arbitrary inline scripts via misconfigured CSP. The CDN proxies user content; attackers leverage that. Audit the CSP against actual loaded resources. + +No incident response plan. When (not if) something happens, no runbook = chaos. See `incident-response`. + +Vulnerability scanning without remediation. Reports pile up. The scan is theater unless someone fixes findings. + +Penetration test ignored. Pen test report sits on a shelf. Test results without remediation are worse than no test. + +--- + +## Output format + +A security baseline document includes: + +- Inventory: what's in scope +- Layer-by-layer status: what's in place, what's missing +- Required headers: with values, applied per environment +- Required configurations: TLS, secrets, auth +- Required operational practices: access reviews, patch cadence, audit logging +- Findings: prioritized list of gaps +- Remediation plan: owners, dates +- Re-audit cadence: when this is reviewed next + +--- + +## Reference files + +- [`references/headers-checklist.md`](references/headers-checklist.md): A copy-paste checklist of recommended security headers with example values, organized by tier of importance. diff --git a/skills/security-baseline/references/headers-checklist.md b/skills/security-baseline/references/headers-checklist.md new file mode 100644 index 0000000..3a847f9 --- /dev/null +++ b/skills/security-baseline/references/headers-checklist.md @@ -0,0 +1,311 @@ +# Security Headers Checklist + +Copy-paste reference for HTTP response headers that improve security. Organized by tier of importance. + +Test current headers with: securityheaders.com or observatory.mozilla.org. + +--- + +## Tier 1: Set on every site, no excuse + +These are simple to deploy, low risk of breaking things, and material security improvements. + +### Strict-Transport-Security (HSTS) + +Forces browsers to use HTTPS for all future requests to this domain. + +``` +Strict-Transport-Security: max-age=31536000; includeSubDomains +``` + +- `max-age`: lifetime in seconds (31536000 = 1 year, recommended for stable HTTPS deployments) +- `includeSubDomains`: applies to all subdomains. Only enable when every subdomain serves HTTPS reliably. +- `preload`: optional. Enables inclusion in browser preload lists. Once enabled, removal takes weeks. Only add when committed. + +Common mistake: Setting `includeSubDomains` before all subdomains are HTTPS-ready. Internal staging or admin subdomains break. + +--- + +### X-Content-Type-Options + +Prevents browsers from MIME-sniffing the content type, which can lead to confusion attacks. + +``` +X-Content-Type-Options: nosniff +``` + +No nuance. Set it everywhere. + +--- + +### X-Frame-Options + +Prevents your site from being framed by other sites (clickjacking defense). + +``` +X-Frame-Options: DENY +``` + +Use `SAMEORIGIN` instead if your own site uses iframes of itself. + +`X-Frame-Options` is largely superseded by CSP's `frame-ancestors`, but setting both is fine for backward compatibility with older browsers. + +--- + +### Referrer-Policy + +Controls how much information is sent in the Referer header on outbound links and resource loads. + +``` +Referrer-Policy: strict-origin-when-cross-origin +``` + +This sends full URL on same-origin requests, only the origin on cross-origin HTTPS-to-HTTPS, and nothing on HTTPS-to-HTTP downgrades. + +For privacy-sensitive sites: + +``` +Referrer-Policy: no-referrer +``` + +--- + +## Tier 2: Material security improvements, requires planning + +These add real protection but may require code changes or rollout planning. + +### Content-Security-Policy + +The most powerful header. Prevents most XSS attacks even when input handling has bugs. + +Strict CSP (recommended for new sites): + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' 'nonce-{random}' 'strict-dynamic'; + style-src 'self' 'nonce-{random}'; + img-src 'self' data: https:; + font-src 'self'; + connect-src 'self'; + frame-ancestors 'none'; + base-uri 'self'; + form-action 'self'; + object-src 'none'; + upgrade-insecure-requests; +``` + +Notes: +- `nonce-{random}` is replaced per request with a fresh random token, included on legitimate inline scripts. +- `'strict-dynamic'` allows scripts loaded by trusted scripts (recursive trust). Most modern apps need this. +- `frame-ancestors 'none'` is the modern equivalent of `X-Frame-Options: DENY` and is more flexible. +- `object-src 'none'` blocks Flash and similar (still useful even though Flash is dead). +- `base-uri 'self'` prevents base tag hijacking. + +Allowlist CSP (if you can't do strict): + +``` +Content-Security-Policy: + default-src 'self'; + script-src 'self' https://trusted-cdn.com; + style-src 'self' 'unsafe-inline'; + img-src 'self' data: https:; + ... +``` + +This is weaker than strict CSP. Plan to migrate to strict. + +Roll out via Report-Only first: + +``` +Content-Security-Policy-Report-Only: ...; report-uri /csp-violation-report +``` + +Watch reports, tune, then switch to enforcing. + +--- + +### Permissions-Policy + +Controls which browser features (camera, microphone, geolocation, etc.) can be used. + +Conservative default: + +``` +Permissions-Policy: + accelerometer=(), + camera=(), + geolocation=(), + gyroscope=(), + magnetometer=(), + microphone=(), + payment=(), + usb=(), + interest-cohort=() +``` + +This denies all listed features by default. Allow specific ones if needed: + +``` +Permissions-Policy: camera=(self), geolocation=(self "https://maps.example.com") +``` + +`interest-cohort=()` opts the site out of FLoC and similar third-party tracking. + +--- + +## Tier 3: Newer, useful in specific contexts + +These provide additional isolation and protection. Some require more careful integration. + +### Cross-Origin-Opener-Policy (COOP) + +Isolates your site's window from cross-origin windows. Defends against cross-origin attacks like Spectre. + +``` +Cross-Origin-Opener-Policy: same-origin +``` + +May break some popup-based OAuth flows. Test carefully. + +--- + +### Cross-Origin-Embedder-Policy (COEP) + +Required for `SharedArrayBuffer` and high-resolution timers. Restricts what can be loaded. + +``` +Cross-Origin-Embedder-Policy: require-corp +``` + +Means every cross-origin resource you load must explicitly opt in via `Cross-Origin-Resource-Policy: cross-origin`. + +Often impractical for sites with many third-party resources. Use `credentialless` as a softer option: + +``` +Cross-Origin-Embedder-Policy: credentialless +``` + +--- + +### Cross-Origin-Resource-Policy (CORP) + +For your own resources (images, scripts, styles), declares who can include them. + +``` +Cross-Origin-Resource-Policy: same-origin +``` + +For resources you want others to be able to embed (a public CDN, a sharing widget): + +``` +Cross-Origin-Resource-Policy: cross-origin +``` + +--- + +### Reporting-Endpoints + +Modern way to specify where violation reports go (replaces the older `report-uri`). + +``` +Reporting-Endpoints: csp-endpoint="https://example.com/csp", default="https://example.com/reports" +Content-Security-Policy: ...; report-to csp-endpoint +``` + +--- + +## Headers to remove or set carefully + +### Server + +The `Server` header reveals what server software is running. + +``` +Server: nginx/1.18.0 +``` + +Reveals software and version. Helps attackers target known vulnerabilities. Set to a generic value or remove: + +``` +Server: web +``` + +(Or remove entirely if your stack allows.) + +--- + +### X-Powered-By + +Reveals the framework or language. + +``` +X-Powered-By: Express +X-Powered-By: PHP/8.0 +``` + +Same issue as `Server`. Remove. + +--- + +### X-AspNet-Version, X-AspNetMvc-Version + +Same. Remove. + +--- + +## What to skip + +These are deprecated, not useful, or actively harmful: + +- `X-XSS-Protection`: deprecated. Modern browsers ignore it. Use CSP instead. +- `Public-Key-Pins` (HPKP): removed from browsers. Don't bother. +- `Expect-CT`: deprecated. Certificate Transparency is enforced automatically. +- `Feature-Policy`: replaced by `Permissions-Policy`. Use the latter. + +--- + +## Quick reference table + +\| Header \| Tier \| Default value \| +\|---\|---\|---\| +\| `Strict-Transport-Security` \| 1 \| `max-age=31536000; includeSubDomains` \| +\| `X-Content-Type-Options` \| 1 \| `nosniff` \| +\| `X-Frame-Options` \| 1 \| `DENY` (or `SAMEORIGIN`) \| +\| `Referrer-Policy` \| 1 \| `strict-origin-when-cross-origin` \| +\| `Content-Security-Policy` \| 2 \| Site-specific (see strict CSP example) \| +\| `Permissions-Policy` \| 2 \| Site-specific (deny by default) \| +\| `Cross-Origin-Opener-Policy` \| 3 \| `same-origin` \| +\| `Cross-Origin-Embedder-Policy` \| 3 \| `require-corp` or `credentialless` \| +\| `Cross-Origin-Resource-Policy` \| 3 \| `same-origin` (resources), `cross-origin` (public) \| +\| `Server` \| Remove \| Set generic or remove \| +\| `X-Powered-By` \| Remove \| Remove \| + +--- + +## Verification + +After deploying, verify: + +```bash +curl -I https://example.com +``` + +Look for the headers in the response. + +Test grade: securityheaders.com gives a letter grade. Aim for A or A+. + +--- + +## Setting headers by stack + +Where you set these depends on the stack. Common locations: + +- Reverse proxy (Nginx, Caddy, HAProxy): in the proxy config +- CDN (Cloudflare, Fastly, Akamai): in the CDN's response header rules +- Application (Express, Django, Rails, etc.): middleware or filter +- Hosting platform (Vercel, Netlify, Cloudflare Pages): platform-specific config file (e.g., `vercel.json`, `_headers`) + +Setting at the edge (CDN or proxy) is preferred when possible: applies to every response without depending on application code. + +For dynamic values (like the CSP nonce), the header has to be set per-request from the application. diff --git a/skills/seo-aeo-geo/SKILL.md b/skills/seo-aeo-geo/SKILL.md new file mode 100644 index 0000000..c60a7b4 --- /dev/null +++ b/skills/seo-aeo-geo/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-aeo-geo +description: "Optimize content and site structure for AI-driven search experiences including AI overviews, large language model citations, generative answer engines, and AI assistants. Use this skill whenever the user wants to optimize for AI search, get cited by language models, appear in AI overviews, build llms.txt, structure content for AI extraction, or future-proof their SEO for the shift from blue links to AI answers. Triggers on AEO, GEO, AI search, AI SEO, AI overview, generative search, LLM optimization, llms.txt, AI citation, ChatGPT search, Perplexity, Gemini, Claude search, AI assistant optimization, answer engine. Also triggers when the user expresses concern about AI eating their organic traffic or wants to understand how to remain visible as search shifts." +category: seo-foundation +catalog_summary: "AI search optimization, llms.txt, extraction-friendly content" +display_order: 7 +--- + +# AEO and GEO + +Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO). Make content discoverable, extractable, and citable by AI search experiences. + +This skill encodes principles. AI search products evolve fast. The principles age slower than the products. + +--- + +## When to use + +- Optimizing content for AI overviews and generative answer engines +- Building or updating llms.txt +- Structuring content so AI assistants can extract and cite it correctly +- Future-proofing a site as search shifts from blue links to AI answers +- Auditing whether existing content is AI-friendly +- Adding signals that help AI assistants identify the site as a trustworthy source + +## When NOT to use + +- Traditional on-page or technical SEO (use `seo-onpage` or `seo-technical`) +- Keyword research (use `seo-keyword`) +- Off-page authority and link building (use `seo-offpage`) + +This skill stacks on top of those. Strong AEO/GEO requires strong fundamental SEO underneath. + +--- + +## Required inputs + +- The site or page to optimize +- The topic area or query types AI should cite the site for +- Access to inspect rendered HTML and structured data + +--- + +## The framework: 5 layers + +AI search visibility comes from five stacked layers. Each layer compounds. + +### 1. Extractable content structure + +AI systems extract facts and pull citations from content. Make extraction easy. + +- Direct answers. Open major sections with a definitive 1 to 3 sentence answer to the question that section addresses. AI extracts the first answer it sees. +- Question-headers. Use H2s and H3s phrased as questions when natural. Mirrors how people prompt AI. +- Atomic facts. When stating a fact, state it once, clearly, with the supporting context next to it. AI struggles when claims are spread across paragraphs. +- Tables and lists. AI parses these reliably. Use them for comparisons, specs, steps, and data. +- Definitions early. When introducing a concept, define it inline. Do not assume the reader (or AI) saw a definition three pages ago. +- Numbered steps. For procedural content, number every step. Avoid prose disguised as instructions. + +### 2. Citation worthiness + +AI cites sources it considers authoritative. Earn that consideration. + +- Original data. Surveys, studies, proprietary research, internal benchmarks. AI prefers primary sources over restatements. +- Specific numbers. "Roughly 40 percent" beats "many." Specific stats with sources beat round-number generalizations. +- Named experts. Author bios with credentials, links to professional profiles, schema-marked-up Person entities. +- Date stamps. Publication date AND last-updated date, both visible AND in schema. AI heavily weights recency for time-sensitive queries. +- Methodology disclosure. When stating a finding, briefly note how it was reached. AI rewards transparency. +- Citations of other sources. Linking to authoritative sources you used builds reciprocal credibility. + +### 3. Structured data depth + +Schema is how you speak machine-readable language. AI assistants parse it heavily. + +- Schema.org types appropriate to content (Article, FAQPage, HowTo, Recipe, Product, Organization, Person, LocalBusiness, etc.) +- Required AND recommended properties filled in (most sites only fill required, leaving signal on the table) +- Person schema for authors, with `sameAs` links to verifiable profiles +- Organization schema on the homepage with logo, contact, social links +- FAQPage schema for content with genuine question-answer pairs +- HowTo schema for procedural content +- BreadcrumbList schema site-wide +- Validates in Schema.org Validator AND Rich Results Test (some properties differ) + +### 4. AI-readable accessibility + +Beyond traditional SEO, AI tools need access patterns of their own. + +- llms.txt at the site root. A markdown file at `/llms.txt` describing the site's content, key URLs, and what topics the site covers. See [`references/llms-txt-guide.md`](references/llms-txt-guide.md). +- llms-full.txt (optional) - a complete content dump for AI training and context, if the site permits it. +- robots.txt allowing AI crawlers. Decide explicitly which AI crawlers to allow (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, etc.) or disallow. Do not block by default if visibility matters. +- Clean HTML semantics. Semantic tags (`article`, `section`, `nav`, `main`) help AI parse structure. +- Avoid client-side-only rendering for critical content. Many AI crawlers render less reliably than Googlebot. + +### 5. Real-world entity signals + +AI builds knowledge graphs and prefers entities with multiple consistent signals. + +- Wikipedia entry if the brand or person qualifies for notability (do not force this; it requires genuine notability) +- Wikidata entry for the entity, with consistent properties +- Consistent NAP (Name, Address, Phone) across all citations +- Brand mentions across multiple authoritative sources. AI cross-references entity claims across the open web. +- Social profile schema linking owned profiles via `sameAs` properties +- Reviews and reputation signals. Aggregate ratings on Google Business, Trustpilot, industry-specific review sites where applicable + +--- + +## Workflow + +1. Audit current state. Run the 5-layer framework against the existing site. Score each. +2. Identify the priority queries. What questions should AI cite this site for? List 10 to 20. +3. Test current AI visibility. Query each of the major AI products (those relevant to the audience) with the priority questions. Note which sources they cite. +4. Identify gaps. Is the site cited? On which queries? Why does it lose to the cited sources? +5. Layer-by-layer plan. + - Fix extractable structure on top 20 priority pages + - Add citation-worthy signals (original data, expert authorship, methodology) + - Deepen schema implementation + - Build/update llms.txt + - Strengthen entity signals +6. Implement and re-test. AI products update frequently. Re-test priority queries quarterly. + +--- + +## Failure patterns + +- Treating AEO/GEO as separate from SEO. Strong fundamental SEO is a prerequisite. AI cites pages, not magic. +- Stuffing FAQ schema on pages that have no genuine FAQs. Search engines and AI alike penalize manufactured FAQ blocks. +- Hiding key content behind heavy JavaScript. AI crawlers render less reliably. Server-render or pre-render critical content. +- Optimizing for one AI product only. Different products use different ranking and citation logic. Optimize for the principles, not for one product's quirks. +- Ignoring entity strength. Content alone, with no real-world entity signals, will not get cited reliably for branded or expertise-related queries. +- Treating llms.txt as a magic bullet. It helps, but it is one of many signals. +- Static optimization. AI products evolve faster than search algorithms historically did. Re-audit at least quarterly. + +--- + +## Output format + +Default output is a markdown plan at `aeo-geo-strategy.md`. Structure: + +1. Current AI visibility audit (which queries cite the site, which do not) +2. 5-layer scorecard +3. Priority queries (the 10 to 20 the site should be cited for) +4. Layer-by-layer remediation plan +5. Implementation roadmap +6. Re-test schedule (quarterly) + +--- + +## Reference files + +- [`references/llms-txt-guide.md`](references/llms-txt-guide.md) - How to write a useful llms.txt, with examples. +- [`references/extraction-friendly-patterns.md`](references/extraction-friendly-patterns.md) - Content patterns that AI extracts cleanly, with before/after examples. diff --git a/skills/seo-aeo-geo/references/extraction-friendly-patterns.md b/skills/seo-aeo-geo/references/extraction-friendly-patterns.md new file mode 100644 index 0000000..2906fb1 --- /dev/null +++ b/skills/seo-aeo-geo/references/extraction-friendly-patterns.md @@ -0,0 +1,266 @@ +# Extraction-Friendly Patterns + +Content patterns that AI search experiences extract cleanly, with before-and-after examples. The goal is not to write for AI exclusively. The goal is to write so a human reader gets the answer fast and an AI extractor gets it fast too. The two overlap more than people think. + +--- + +## The principle + +AI extractors and skim-readers want the same thing: the answer first, the supporting context second. Content that buries the answer behind preamble loses both audiences. + +Three structural moves do most of the work: + +1. Lead with the answer. First sentence of the section answers the section's question. +2. Use semantic structure. Headings name the question. Lists separate items. Tables compare options. Code blocks contain code. +3. Be self-contained. Each section should make sense without depending on the section above. + +Everything below is an application of these three moves. + +--- + +## Pattern 1: question-led headings + +Headings phrased as the question the user actually asks. + +### Bad + +> ## Onboarding optimization + +### Better + +> ## How long should employee onboarding take? + +The question form does three jobs at once: it matches likely search queries, it tells the reader what they will learn, and it tells the AI extractor what answer follows. + +--- + +## Pattern 2: answer-first paragraph + +The first sentence answers the question. Subsequent sentences provide context, caveats, and depth. + +### Bad + +> ## How long should employee onboarding take? +> +> Onboarding has many definitions across organizations. Some companies define onboarding as the first day, some as the first week, and others as the entire ramp-up period. There is no industry consensus, and the question depends on many factors. With that said, most modern companies aim for a structured program lasting somewhere between 30 and 90 days. + +### Better + +> ## How long should employee onboarding take? +> +> Most structured onboarding programs run 30 to 90 days, with 90 being the most common. The exact length depends on role complexity, company size, and how much time managers can dedicate. The first week typically covers logistics and culture; the first month adds shadowing and small projects; the second and third months ramp the new hire into full ownership. + +The "Better" version puts the extractable answer in the first sentence. The follow-up adds context without burying the lead. + +--- + +## Pattern 3: definitions in inverse pyramid + +Define the term in one sentence, then expand. + +### Bad + +> ## What is a service blueprint? +> +> A service blueprint is a versatile tool used by many designers and product teams. Originally developed in the 1980s by G. Lynn Shostack at Bankers Trust, it has since been adopted across industries from healthcare to retail. Service blueprints help teams visualize the relationships between people, processes, and physical evidence in a service experience. + +### Better + +> ## What is a service blueprint? +> +> A service blueprint is a diagram that maps every step of a service experience, both what the customer sees and what happens behind the scenes. It typically uses lanes for the customer journey, frontstage actions, backstage actions, and supporting systems. Originally developed by G. Lynn Shostack in the 1980s, it is now standard in service design, healthcare workflow design, and operations planning. + +The first sentence is a complete, extractable definition. AI assistants quoting your page will quote this sentence. Search snippets will lift it. + +--- + +## Pattern 4: numbered lists for sequenced steps + +Sequenced procedures go in numbered lists. Not in prose. + +### Bad + +> To deploy with the CLI, first you'll want to run npm install. Once that completes, run npm run build to generate the production bundle, then npm run deploy to push to your environment. After that, verify the deployment by checking the status endpoint. + +### Better + +> ## How to deploy with the CLI +> +> 1. Install dependencies: `npm install` +> 2. Build the production bundle: `npm run build` +> 3. Deploy to your environment: `npm run deploy` +> 4. Verify the deployment by checking the status endpoint. + +The numbered list extracts cleanly into "how-to" snippets, FAQ-style answers, and HowTo schema. The prose version forces the extractor (human or AI) to do the work of parsing the steps. + +--- + +## Pattern 5: bullet lists for parallel items + +Parallel items go in bullets. Especially "what is included" or "options" lists. + +### Bad + +> Our enterprise tier includes single sign-on, audit logs, advanced role-based access controls, dedicated support, and custom data retention policies. + +### Better + +> ## What is included in the enterprise tier +> +> - Single sign-on (SSO) +> - Audit logs +> - Advanced role-based access controls +> - Dedicated support +> - Custom data retention policies + +The bullet form is extractable. An AI assistant asked "what does the enterprise tier include" can quote this list verbatim. + +--- + +## Pattern 6: tables for comparisons + +When comparing 2+ options across 2+ criteria, use a table. AI extractors handle tables well; prose comparisons get garbled. + +### Bad + +> The free plan supports up to 3 projects and 5 team members, with email support only. The pro plan extends this to 25 projects and 25 team members, adds priority support, and includes the API. The enterprise plan removes all limits, adds SSO, audit logs, and a dedicated success manager. + +### Better + +> \| Feature \| Free \| Pro \| Enterprise \| +> \|---\|---\|---\|---\| +> \| Projects \| 3 \| 25 \| Unlimited \| +> \| Team members \| 5 \| 25 \| Unlimited \| +> \| Support \| Email \| Priority \| Dedicated CSM \| +> \| API access \| - \| ✓ \| ✓ \| +> \| SSO \| - \| - \| ✓ \| +> \| Audit logs \| - \| - \| ✓ \| + +--- + +## Pattern 7: explicit Q&A blocks + +For pages where the user is asking a direct question (FAQs, help docs, glossaries), use explicit Q&A formatting. + +### Pattern + +> Q: [The question phrased as the user would ask it] +> +> A: [Direct answer in 1-3 sentences. Optional supporting paragraph after.] + +This is what FAQ schema lifts directly. AI extractors recognize the pattern and treat it as a discrete answerable unit. + +--- + +## Pattern 8: self-contained sections + +Each section under an H2 should make sense if read in isolation. AI extractors often pull a single section as the answer to a query. If the section depends on context from earlier sections, the answer it surfaces will be incomplete or wrong. + +### Bad + +> ## Setup +> +> Use the same approach we discussed in the previous section, but with the production endpoint instead of staging. + +### Better + +> ## Setup for production +> +> Run the deploy command against the production endpoint: +> +> ```bash +> npm run deploy --target=production +> ``` +> +> The production endpoint requires the `PROD_API_KEY` environment variable. See "Environment variables" for setup. + +The "Better" version stands alone. A reader (or AI assistant) landing here from search gets a complete answer. + +--- + +## Pattern 9: explicit data and units + +State numbers, ranges, and units explicitly. Vague modifiers ("a lot," "fast," "some users") do not extract. + +### Bad + +> Our customers see a major improvement in conversion after switching. + +### Better + +> On average, our customers see a 23% lift in conversion within the first 30 days after switching, based on data from 412 customers measured between January and March 2025. + +The "Better" version has extractable specifics: the metric, the magnitude, the time window, the sample size, and the date range. Trustworthy AI assistants prefer extracting specifics. + +--- + +## Pattern 10: structured author and date metadata + +For any content that depends on currency or expertise, expose the metadata visibly and in schema. + +- Author byline with a real name and a credential or one-line bio. +- Publish date and last updated date in human-readable form. +- Reviewer if the content is reviewed by an SME. +- Article schema with `author`, `datePublished`, `dateModified`, and (where applicable) `reviewedBy`. + +AI search uses author and date signals as part of trustworthiness scoring. + +--- + +## Pattern 11: explicit topic boundaries + +Tell the reader (and the extractor) what the page is and is not about. + +### Pattern + +> ## What this guide covers +> +> This guide covers backup strategies for Postgres databases on managed services (AWS RDS, GCP Cloud SQL, Supabase). It does not cover self-hosted Postgres tuning, backup of file storage, or disaster recovery testing. +> +> If you are self-hosting Postgres, see [other guide]. If you are designing DR drills, see [other guide]. + +This pattern protects against AI summaries that conflate your scope with adjacent topics. + +--- + +## Pattern 12: predictable summary blocks + +Sections like "Summary," "Key takeaways," "TL;DR" at the top or bottom of an article extract well. Keep them tight: 3-7 bullets, one short sentence each. + +### Pattern + +> ## Key takeaways +> +> - Aim for 30-90 day onboarding, with 90 being the most common. +> - First week: logistics and culture. First month: shadowing and small projects. Months 2-3: full ramp. +> - The single highest-impact factor is manager time, not program design. +> - Track time-to-productivity, not arbitrary onboarding completion. + +A summary block doubles as the AI snippet, the social card excerpt, and the email digest line. + +--- + +## What to avoid + +These patterns hurt extraction: + +- Walls of text without headings. The reader and the extractor both lose place. +- Inline references that depend on prior sections. "As mentioned above" is invisible to a snippet. +- Vague modifiers in place of numbers. "Many users," "several studies," "a long time." +- Jargon without definition. AI assistants will define it incorrectly if you do not. +- Marketing fluff in lead sentences. "Discover the powerful possibilities of..." extracts as gibberish. +- PDFs and images for content that should be text. Tables and key data trapped in images cannot be extracted. +- Iframe-embedded content. AI assistants do not consistently follow iframes. + +--- + +## How to test + +After writing a page, simulate extraction: + +1. Read only the H1 and the first sentence under each H2. Does the page still make sense? +2. Read only the bullet lists, tables, and Q&A blocks. Do they answer the obvious questions? +3. Ask an LLM (in a fresh context) the questions your page answers. Does it pull useful, accurate snippets from your page? +4. Check Google's "People also ask" for your topic. Does your page answer those exact questions? + +If a test fails, the structure needs more semantic markup, not more words. diff --git a/skills/seo-aeo-geo/references/llms-txt-guide.md b/skills/seo-aeo-geo/references/llms-txt-guide.md new file mode 100644 index 0000000..5360369 --- /dev/null +++ b/skills/seo-aeo-geo/references/llms-txt-guide.md @@ -0,0 +1,227 @@ +# llms.txt Guide + +`llms.txt` is a markdown file at the root of a domain (e.g., `example.com/llms.txt`) that helps AI systems understand what the site is, what it covers, and which URLs are most valuable. + +It is the AI-era equivalent of `robots.txt` plus a sitemap, written in plain language for language models. + +This guide walks through how to write a useful one. + +--- + +## What llms.txt is for + +- Tell AI assistants what the site is and what it covers +- Point AI to the most valuable URLs for citation +- Provide structured context that helps AI summarize and cite the site accurately +- Reduce the chance of AI hallucinating about your brand or content + +What it is NOT: + +- A ranking signal (yet, possibly ever) +- A guarantee of citation +- A replacement for sitemap.xml or robots.txt +- A way to block AI crawlers (use robots.txt for that) + +--- + +## The format + +llms.txt is a markdown file with a specific structure: + +```markdown +# [Site or Brand Name] + +> [One-sentence description of what the site is and who it serves] + +[1 to 3 paragraphs of context. Who runs the site, what topics it covers, what makes it credible, what audience it serves. Plain language.] + +## [Section 1 - typically content categories or product lines] + +- [Title](URL): [One-line description] +- [Title](URL): [One-line description] + +## [Section 2] + +- [Title](URL): [One-line description] + +## Optional + +[Less critical resources.] +``` + +Section headers are flexible. Use whatever organization fits the site's content. + +--- + +## Example: a simple content site + +```markdown +# Example Knowledge Base + +> A free guide library on [topic area] for [audience]. + +We publish in-depth guides, comparisons, and how-tos on [topic area]. Content is written by [credentials of authors] and updated [frequency]. Our methodology is documented at /methodology. + +## Core guides + +- [The Complete Guide to X](https://example.com/complete-guide-x): A 5,000-word reference covering fundamentals through advanced topics. +- [How to Choose Y](https://example.com/how-to-choose-y): Decision framework with comparison tables and worked examples. +- [The Beginner's Guide to Z](https://example.com/beginner-z): A 30-minute primer for someone new to the topic. + +## Comparisons + +- [A vs B](https://example.com/a-vs-b): Head-to-head feature, pricing, and use case comparison. +- [Top 10 [Category]](https://example.com/top-10): Ranked list with selection criteria. + +## Tools + +- [Calculator](https://example.com/calculator): Free interactive tool for [purpose]. +- [Templates](https://example.com/templates): Downloadable templates with examples. + +## About + +- [About us](https://example.com/about) +- [Methodology](https://example.com/methodology) +- [Editorial standards](https://example.com/editorial-standards) +``` + +--- + +## Example: a SaaS product site + +```markdown +# ProductName + +> [Product category] for [target audience]. [Core value proposition in one phrase]. + +ProductName is built and operated by a team of [size and background]. We serve [audience description]. The product is used by [scale, e.g., "over 10,000 teams" or "from solo founders to Fortune 500 companies"]. + +## Product + +- [How it works](https://example.com/product): Overview of core functionality and architecture. +- [Pricing](https://example.com/pricing): Transparent pricing tiers and what each includes. +- [Integrations](https://example.com/integrations): Third-party tools we connect with. + +## Documentation + +- [Getting started](https://docs.example.com/getting-started): 15-minute setup guide. +- [API reference](https://docs.example.com/api): Complete API documentation. +- [Best practices](https://docs.example.com/best-practices): How successful customers use the product. + +## Resources + +- [Customer stories](https://example.com/customers): How specific customers achieved specific outcomes. +- [Blog](https://example.com/blog): Engineering posts, product updates, and industry analysis. +- [Changelog](https://example.com/changelog): Recent product changes. + +## Trust + +- [Security](https://example.com/security): SOC 2, encryption, compliance. +- [Privacy policy](https://example.com/privacy) +- [Terms of service](https://example.com/terms) +``` + +--- + +## What to include + +A good llms.txt is curated, not exhaustive. Include: + +- Cornerstone content. Your 10 to 30 best, most authoritative pieces. +- Decision-support pages. Comparisons, calculators, frameworks. +- Authority signals. Methodology, editorial standards, about pages. +- Trust signals. Security, privacy, compliance, certification pages. +- Recency cues. A changelog or "latest" link if you publish frequently. + +What to leave out: + +- Every URL on the site (use sitemap.xml for that) +- Marketing fluff with no informational substance +- Pages that exist primarily for SEO (low-quality programmatic content, doorway pages) +- Internal admin URLs + +--- + +## What to write in the description + +The opening description (under the title, prefixed by `>`) is what AI extracts when asked "what is [site]?" Make it count. + +Bad description: +> A leading provider of innovative solutions in the digital space. + +Good description: +> A free guide library on home renovation for first-time buyers, with calculators and template contracts. + +The good description names: what it is (guide library), what topic (home renovation), who it serves (first-time buyers), and what's unique (calculators and templates). + +--- + +## Length and depth + +- Title and one-sentence description: required +- Context paragraphs: 1 to 3 paragraphs, 100 to 400 words total +- Sections: 3 to 8 sections is typical +- URLs per section: 3 to 10 is the sweet spot +- Total file length: 500 to 2000 words for most sites + +A 50-word llms.txt is too thin to be useful. A 5000-word llms.txt buries the signal. + +--- + +## Updating + +- Update llms.txt when you launch a major new content category, product, or section +- Re-review at least quarterly +- Remove dead links (broken URLs in llms.txt actively damage credibility with AI) +- Keep the description fresh as the site evolves + +--- + +## llms-full.txt (the optional sibling) + +Some sites also publish `llms-full.txt`, which contains the full text content of the linked pages concatenated into one file. This is more aggressive: it offers AI systems the entire content for context. + +Reasons to publish it: + +- You want maximum AI context, including verbatim content +- Your content is freely licensed or you accept it being used for AI training +- Your content is short enough that the file is manageable (under 10MB, ideally under 5MB) + +Reasons NOT to publish it: + +- You sell or gate content (e.g., paid courses, premium reports) +- Your terms of service disallow AI training on your content +- File size would exceed reasonable limits + +If you do publish it, link to it from llms.txt: + +```markdown +## Full content + +- [Full content dump](https://example.com/llms-full.txt): The complete content of all linked pages. +``` + +--- + +## Common mistakes + +- Auto-generating llms.txt from sitemap.xml. Defeats the purpose. The point is editorial curation. +- Treating it as a sitemap. Sitemap is for crawlers. llms.txt is for AI context. +- Stuffing it with thin content. Every URL listed should be content you would proudly cite if a human asked. +- Forgetting to update it. A 2-year-old llms.txt makes you look abandoned. +- Hosting it at a non-root path. It belongs at `/llms.txt` (root of the domain), not `/docs/llms.txt`. +- Returning HTML instead of plain text. Serve as `text/markdown` or `text/plain`, not as a rendered HTML page. + +--- + +## Verification + +After publishing: + +- [ ] File is at `https://yourdomain.com/llms.txt` (root) +- [ ] File serves with content type `text/markdown` or `text/plain` +- [ ] All linked URLs return 200 +- [ ] All linked URLs use the canonical URL form (no redirects) +- [ ] File is referenced (or at least not blocked) in robots.txt +- [ ] File renders cleanly in a plain text viewer +- [ ] Description and section headings accurately describe the site diff --git a/skills/seo-audit-orchestration/SKILL.md b/skills/seo-audit-orchestration/SKILL.md new file mode 100644 index 0000000..92c3e96 --- /dev/null +++ b/skills/seo-audit-orchestration/SKILL.md @@ -0,0 +1,182 @@ +--- +name: seo-audit-orchestration +description: "Master orchestrator for a full SEO audit suite powered by the Ahrefs MCP. Use this skill when running a comprehensive SEO audit, scoping a quarterly health check, doing pre-acquisition SEO due diligence, or post-migration verification. Triggers on full SEO audit, comprehensive SEO review, SEO health check, audit my site, SEO due diligence, audit suite, comprehensive audit, end-to-end SEO. Also triggers when a stakeholder wants the complete picture rather than a single-dimension audit." +category: seo-audit-suite +catalog_summary: "Master orchestrator: sequences the suite, produces a rollup report" +display_order: 1 +--- + +# SEO Audit Orchestration + +Run a complete SEO audit by sequencing the sibling audit skills in a defined order. Stack-agnostic. Assumes the Ahrefs MCP is connected. Produces a single rollup report that synthesizes findings across backlinks, keywords, content, traffic, technical health, and rankings. + +--- + +## When to use + +- Running a full SEO audit (quarterly, biannual, annual) +- Pre-acquisition SEO due diligence +- Post-migration verification (after content move, replatform, or domain change) +- Onboarding a new client or new property +- Building a baseline before a major SEO investment +- Diagnosing chronic underperformance + +## When NOT to use + +- Single-dimension audits (use the specific child skill: `seo-onpage`, `seo-backlink-audit`, etc.) +- Investigating a specific traffic drop (use `seo-traffic-diagnosis`) +- Tactical questions like "which keywords should we target" (use `seo-keyword-gap-audit`) +- Routine monitoring (use `seo-rank-tracking`) + +--- + +## Required inputs + +- The site or properties in scope +- Target market and primary languages +- Competitor set (3-5 properties) +- Goal of the audit (baseline, due diligence, fix plan, growth roadmap) +- Time and reporting constraints +- Confirmation that the Ahrefs MCP is connected and the workspace has access to the target property + +--- + +## The framework: 6 phases of an end-to-end audit + +A complete audit moves through six phases in order. Skipping phases produces gaps. Reordering them produces rework. + +### Phase 1: Scope and baseline + +Define the audit before running it. + +- What is in scope (subdomains, paths, languages) +- What is out of scope +- Goal of the audit (baseline, fix plan, growth roadmap, due diligence) +- Stakeholders and their priorities +- Reporting format and length expectations + +Output: a 1-page audit charter. + +### Phase 2: Data gather + +Pull the raw data from Ahrefs and any companion sources. + +Required pulls: + +- Site Explorer: organic keywords, organic traffic, top pages, top countries, referring domains, backlinks, anchor text profile +- Site Audit: full crawl results +- Keywords Explorer: target keyword universe and competitor keyword overlap +- Content Explorer: top performing content in target topics +- Rank Tracker: current tracked positions if set up + +Companion pulls (not Ahrefs-native): + +- Search Console: query and page data, coverage issues +- Analytics: traffic, conversions, segment by source +- Server logs (if available): bot crawl behavior + +Document data freshness for every pull. Stale data yields wrong conclusions. + +### Phase 3: Run the sub-audits + +Run each child audit. Each produces its own findings doc. + +\| Sub-audit \| Skill \| What it produces \| +\| --- \| --- \| --- \| +\| Site health \| `seo-site-health-audit` \| Prioritized technical fix backlog \| +\| Backlinks \| `seo-backlink-audit` \| Profile health, toxic list, reclamation list \| +\| Keywords \| `seo-keyword-gap-audit` \| Prioritized opportunity list \| +\| Content \| `seo-content-gap-audit` \| Create/update/merge roadmap \| +\| Page-level \| `seo-onpage` \| Per-page audit on top pages \| +\| AI search \| `seo-aeo-geo` \| AI search readiness gaps \| + +The child skills do the analysis. This skill sequences them and integrates the outputs. + +### Phase 4: Synthesize + +Combine findings into themes. A list of 200 issues is not an audit. A list of 5-7 themes is. + +Themes typically emerge in categories like: + +- Technical foundation gaps that cap upside +- Content depth gaps in priority topics +- Backlink profile concentration risks +- Keyword opportunities the site is leaving on the table +- Cannibalization or thin coverage +- AI search readiness + +Each theme should answer: what is happening, why it matters, what is the size of prize, what is the fix. + +### Phase 5: Prioritize + +Rank the themes. Use a simple impact/effort matrix. + +- Quick wins: high impact, low effort. Do now. +- Strategic plays: high impact, high effort. Plan and resource. +- Maintenance: low impact, low effort. Backlog. +- Avoid: low impact, high effort. Drop. + +Tie each theme to a measurable target (organic clicks, ranked keywords in target band, conversions from organic). + +### Phase 6: Deliver + +Produce the rollup report. See [`references/audit-rollup-template.md`](references/audit-rollup-template.md). + +Structure: + +- Executive summary (1 page) +- Themes and recommendations (5-7 themes, 1 page each) +- Sub-audit findings (linked or appended) +- Roadmap (next 90 days) + +Walk stakeholders through it. Get commitment to the next 90 days of work. + +--- + +## Workflow + +1. Charter the audit. 1-page scope, goal, stakeholders, format. +2. Confirm Ahrefs MCP access. Verify the workspace has the target property and recent data. +3. Pull all data. Run the gather list in phase 2. Document freshness. +4. Run each sub-audit. Use the child skills. Each produces its own findings doc. +5. Synthesize themes. 5-7 themes max. Each ties to an impact and a fix. +6. Prioritize. Impact/effort matrix. Quick wins surface to the top. +7. Draft the rollup. Use the template. Executive summary first. +8. Review with the team. Pressure-test conclusions before stakeholder readout. +9. Deliver. Walk stakeholders through. Get commitment to next 90 days. +10. Schedule the next one. Audits decay. Rerun on a cadence. + +--- + +## Failure patterns + +- Audit without a goal. Produces a 60-page document nobody reads. Charter the audit first. +- All findings, no themes. A list of 200 issues is data, not an audit. Synthesize into themes. +- Skipping the sub-audits. Running one big audit instead of six focused ones produces shallow analysis everywhere. +- No prioritization. "Here are 47 things to fix" gets nothing fixed. Rank them. +- Stale data. Ahrefs index updates on a delay. Note freshness. Do not draw conclusions from week-old movement. +- Tool worship. Ahrefs is one source. Search Console, analytics, and logs add ground truth. Triangulate. +- Audit-to-audit drift. Running every audit differently makes trends impossible to spot. Standardize the structure. +- No 90-day roadmap. Without a plan after the audit, the audit is shelfware. +- Solo audit. Audits done alone miss context. Pull in the people who own the work. + +--- + +## Output format + +A rollup audit report with: + +1. Executive summary (1 page). +2. Audit charter (scope, goal, methodology). +3. Themes and recommendations (5-7 themes, each with what, why, size of prize, fix). +4. Sub-audit appendix (linked outputs from each child skill). +5. 90-day roadmap (sequenced work with owners and targets). +6. Methodology notes (data sources, pull dates, caveats). + +Total length: 15-30 pages including appendices. Executive summary readable in 5 minutes. + +--- + +## Reference files + +- [`references/audit-rollup-template.md`](references/audit-rollup-template.md) - Template for the rollup report including executive summary, theme structure, and roadmap format. diff --git a/skills/seo-audit-orchestration/references/audit-rollup-template.md b/skills/seo-audit-orchestration/references/audit-rollup-template.md new file mode 100644 index 0000000..2343b76 --- /dev/null +++ b/skills/seo-audit-orchestration/references/audit-rollup-template.md @@ -0,0 +1,236 @@ +# Audit rollup template + +A template for the final SEO audit deliverable. Adapt sections to fit the audit goal and stakeholder appetite. + +--- + +## Document structure + +``` +1. Executive summary (1 page) +2. Audit charter (1 page) +3. Themes and recommendations (5-7 themes, 1 page each) +4. 90-day roadmap (1-2 pages) +5. Sub-audit appendix (linked or attached) +6. Methodology notes (1 page) +``` + +Total: 15-30 pages. Executive summary always readable in 5 minutes. + +--- + +## 1. Executive summary template + +``` +# [Property] SEO Audit + +Audit date: [date] +Period covered: [date range] +Auditor: [name or team] + +## Headline + +[One sentence. The state of SEO at this property.] + +## Top 3 themes + +1. [Theme name]. [One sentence. Why it matters.] +2. [Theme name]. [One sentence. Why it matters.] +3. [Theme name]. [One sentence. Why it matters.] + +## Top 3 quick wins + +1. [Action]. Estimated impact: [target metric movement]. Effort: [size]. +2. [Action]. Estimated impact: [target metric movement]. Effort: [size]. +3. [Action]. Estimated impact: [target metric movement]. Effort: [size]. + +## Recommended next 90 days + +[3-5 bullets describing the proposed plan.] + +## What is going well + +[2-4 bullets. Avoid an audit that reads as 100% negative.] +``` + +--- + +## 2. Audit charter template + +``` +## Scope + +- Properties in scope: [list] +- Languages: [list] +- Subdomains: [list] +- Out of scope: [list] + +## Goal + +[Baseline / fix plan / growth roadmap / due diligence] + +## Stakeholders + +\| Name \| Role \| Priority \| +\| --- \| --- \| --- \| +\| [name] \| [role] \| [their main concern] \| + +## Methodology + +- Data sources: [Ahrefs, Search Console, Analytics, logs] +- Pull dates: [dates] +- Sub-audits run: [list] + +## Limitations + +[Anything that limits confidence: data gaps, access restrictions, time constraints.] +``` + +--- + +## 3. Theme template + +Use one page per theme. 5-7 themes total. + +``` +## Theme [N]: [Name] + +What is happening + +[2-3 sentences describing the pattern.] + +Why it matters + +[2-3 sentences linking the pattern to a business outcome.] + +Size of prize + +[Quantified opportunity. E.g., "+12,000 monthly clicks" or "+$80k annual revenue at current conversion."] + +Evidence + +- [Data point with source] +- [Data point with source] +- [Data point with source] + +Recommendation + +[The proposed fix or action. 1 paragraph.] + +Effort and timeline + +[Effort: S/M/L. Timeline: weeks or sprints. Dependencies: list.] + +Owners + +[Who needs to do what.] +``` + +--- + +## 4. 90-day roadmap template + +Sequence the work. Tie to themes. Assign owners. + +``` +## Days 1-30 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Days 31-60 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Days 61-90 + +\| Action \| Theme \| Owner \| Effort \| Target \| +\| --- \| --- \| --- \| --- \| --- \| +\| [Action] \| [Theme #] \| [Name] \| [S/M/L] \| [Metric target] \| + +## Review cadence + +[Weekly, biweekly, monthly. Who attends. What is reviewed.] +``` + +--- + +## 5. Sub-audit appendix + +Link or attach the output from each child skill: + +- Site health audit: [link or attachment] +- Backlink audit: [link or attachment] +- Keyword gap audit: [link or attachment] +- Content gap audit: [link or attachment] +- Page-level audits (top pages): [link or attachment] +- AI search readiness: [link or attachment] + +Do not paste full sub-audits into the rollup. Reference them. Stakeholders who want detail can drill in. + +--- + +## 6. Methodology notes + +``` +## Data sources and freshness + +\| Source \| Pull date \| Coverage \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Ahrefs Site Explorer \| [date] \| [scope] \| [caveats] \| +\| Ahrefs Site Audit \| [date] \| [scope] \| [caveats] \| +\| Search Console \| [date range] \| [scope] \| [caveats] \| +\| Analytics \| [date range] \| [scope] \| [caveats] \| + +## Caveats + +- Ahrefs metrics are estimates, not ground truth. +- Search Console data is sampled and capped. +- Analytics may have tagging gaps. +- Server log data was [available / unavailable] for this audit. + +## Repeatability + +To rerun this audit: + +- [Steps to reproduce data pulls] +- [Saved Ahrefs reports or filters] +- [Companion data pull instructions] +``` + +--- + +## Style guidance + +- Lead with the "so what." Stakeholders skim. +- Quantify wherever possible. Vague impact claims get ignored. +- Pair every problem with a proposed fix. Audits without recommendations are reports. +- Keep technical jargon out of the executive summary. +- Use tables and bullets. Avoid wall-of-text. + +--- + +## Common length targets by audit type + +\| Audit type \| Total length \| Executive summary \| Themes \| +\| --- \| --- \| --- \| --- \| +\| Quarterly health check \| 10-15 pages \| 1 page \| 3-4 themes \| +\| Full annual audit \| 25-40 pages \| 1-2 pages \| 5-7 themes \| +\| Pre-acquisition due diligence \| 30-50 pages \| 2 pages \| 6-10 themes \| +\| Post-migration verification \| 10-20 pages \| 1 page \| 3-5 themes \| + +--- + +## Pre-delivery checklist + +- [ ] Executive summary readable in 5 minutes +- [ ] Every theme tied to a quantified impact +- [ ] Every recommendation tied to an owner +- [ ] Quick wins called out separately +- [ ] 90-day roadmap is sequenced and resourced +- [ ] Methodology and caveats are documented +- [ ] Internal review completed before stakeholder readout +- [ ] Next audit date scheduled diff --git a/skills/seo-backlink-audit/SKILL.md b/skills/seo-backlink-audit/SKILL.md new file mode 100644 index 0000000..31e223d --- /dev/null +++ b/skills/seo-backlink-audit/SKILL.md @@ -0,0 +1,166 @@ +--- +name: seo-backlink-audit +description: "Audit a backlink profile using Ahrefs MCP data: profile health, anchor text distribution, toxic link identification, lost link reclamation, and gap analysis against competitors. Use this skill when reviewing backlink health, scoping a disavow project, recovering from a manual action, planning link building, or doing M&A due diligence on a property's link equity. Triggers on backlink audit, link profile, toxic links, disavow, anchor text analysis, lost links, link reclamation, referring domains, link gap. Also triggers when traffic decline correlates with link loss or when an unnatural link warning appears in Search Console." +category: seo-audit-suite +catalog_summary: "Profile health, anchor mix, toxic links, reclamation, gap analysis" +display_order: 2 +--- + +# SEO Backlink Audit + +Audit a backlink profile using data pulled from the Ahrefs MCP. Stack-agnostic. Produces a profile health assessment, a toxic link list (if needed), a reclamation list, and a gap analysis against competitors. + +--- + +## When to use + +- Periodic backlink health check (quarterly or biannual) +- Recovering from a Google manual action or unnatural link warning +- Scoping a disavow file +- Pre-acquisition due diligence on link equity +- Planning a link building campaign (need a baseline) +- Investigating ranking drops correlated with link loss +- Recovering lost links after a migration or replatform + +## When NOT to use + +- Building new links (use `seo-offpage`) +- General SEO audits (use `seo-audit-orchestration`) +- Keyword opportunity analysis (use `seo-keyword-gap-audit`) +- Technical issues unrelated to links (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Target property (root domain, subdomain, or URL prefix) +- Competitor set (3-5 properties with comparable strategies) +- Time window (typically last 12-24 months) +- Confirmation Ahrefs MCP is connected and has access to the property +- Search Console manual action status (if any) +- Recent SEO history (migrations, link campaigns, penalties) + +--- + +## The framework: 5 dimensions of a backlink profile + +A profile is healthy when all five dimensions are healthy. Issues in any one can cap rankings or invite penalties. + +### Dimension 1: Referring domain quality + +Volume of links matters less than the quality and relevance of the linking domains. + +Pull from Ahrefs: + +- Total referring domains (current and trended) +- Domain Rating distribution (DR bands) +- Topical relevance of linking domains +- Geographic distribution (where appropriate) +- Domain age and trust signals + +Healthy signal: a long tail of relevant, established domains. Concentration in any single source is a risk. + +### Dimension 2: Link velocity + +How fast links are gained or lost. + +Pull from Ahrefs: + +- New referring domains per month (trended 12-24 months) +- Lost referring domains per month +- Net change + +Healthy signal: steady positive growth. Sudden spikes suggest paid campaigns or negative SEO. Sudden drops correlate with redirect mistakes, content removal, or the linking sites going down. + +### Dimension 3: Anchor text distribution + +The mix of anchor types tells search engines what the property is about and whether the profile looks natural. + +Categories to map: + +- Branded (the brand name) +- Naked URL +- Generic ("click here", "this page") +- Exact-match keyword +- Partial-match keyword +- Image (alt text or none) + +Healthy signal: branded and naked URL anchors dominate. Exact-match keyword anchors are a small minority. Heavy exact-match concentration triggers spam filters. + +### Dimension 4: Link types + +Not all links are equal. + +Categories: + +- Dofollow versus nofollow +- Editorial versus directory or comment +- In-content versus footer or sidebar +- Sponsored or UGC tagged +- Redirect chains +- Lost links recoverable via outreach + +Healthy signal: editorial in-content dofollow links from relevant sites dominate. + +### Dimension 5: Competitive gap + +What links do peers have that you do not? + +Pull from Ahrefs: + +- Domains linking to 2+ competitors but not the target +- Domains linking to 1 competitor with high relevance to the target +- Top performing competitor pages by referring domain count + +Healthy signal: the gap is shrinking over time. A widening gap is a strategic risk. + +--- + +## Workflow + +1. Charter the audit. Goal, scope, time window, competitor set. +2. Pull baseline data. Referring domains, anchor text, link types, lost links, competitor overlap. +3. Map the profile across 5 dimensions. One section per dimension. +4. Identify red flags. Velocity spikes, anchor concentration, low-DR concentration, suspect TLDs, repeated footprints. +5. Build the toxic list (if needed). Use the criteria in [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md). +6. Build the reclamation list. Lost links worth recovering via outreach. +7. Build the gap list. Domains linking to peers, prioritized by relevance. +8. Synthesize. Profile health verdict, top 3 risks, top 3 opportunities. +9. Recommend. Disavow (rare), reclamation outreach, link building targets, monitoring cadence. +10. Document and hand off. Outputs feed `seo-offpage` and `seo-audit-orchestration`. + +--- + +## Failure patterns + +- Disavow happy. Most profiles do not need a disavow. Disavowing legitimate links damages rankings. Use it only after a manual action or clear algorithmic signals. +- Counting links instead of evaluating them. A profile with 10,000 referring domains can be weaker than one with 200 high-quality editorial links. +- Ignoring lost links. Recovering a lost link is faster and cheaper than building a new one. +- No competitor benchmark. Profile health is relative. A "low" backlink count for a tier-1 competitor is a "great" count for a niche site. +- Anchor text panic. A high exact-match percentage in absolute terms is fine for niche sites where the brand and keyword overlap. Investigate before disavowing. +- One-time audit. Profile health drifts. Audit on a cadence (quarterly minimum for active properties). +- Treating Ahrefs as ground truth. Ahrefs sees most links but not all. Triangulate with Search Console for completeness. +- Over-indexing on Domain Rating. DR is a relative metric, not a quality signal. A DR-30 niche site can be more valuable than a DR-80 generalist. + +--- + +## Output format + +A backlink audit document with: + +1. Executive summary. Profile health verdict and top risks. +2. Profile snapshot. Key metrics: referring domains, DR distribution, anchor mix, velocity. +3. 5-dimension analysis. One section per dimension with findings. +4. Toxic link list. If needed. Disavow file ready format. +5. Reclamation list. Lost links worth recovering, with contact paths. +6. Gap list. Top 50 domains linking to competitors but not target. +7. Recommendations. Disavow (Y/N), reclamation outreach plan, link building targets. +8. Methodology. Data sources, pull dates, criteria used. + +Length: 8-15 pages depending on profile complexity. + +--- + +## Reference files + +- [`references/toxic-link-criteria.md`](references/toxic-link-criteria.md) - Decision framework for classifying a link as toxic, including the disavow file format and threshold guidance. diff --git a/skills/seo-backlink-audit/references/toxic-link-criteria.md b/skills/seo-backlink-audit/references/toxic-link-criteria.md new file mode 100644 index 0000000..8e26d42 --- /dev/null +++ b/skills/seo-backlink-audit/references/toxic-link-criteria.md @@ -0,0 +1,182 @@ +# Toxic link criteria + +A decision framework for classifying a backlink as toxic and worth disavowing. Bias the framework toward keeping links unless the case is clear. Disavowing legitimate links damages rankings. + +--- + +## The disavow bar + +Disavow when one or more of the following is true: + +1. The site has been hit with an algorithmic devaluation that correlates with link-based signals. +2. The site has received a manual action citing unnatural links. +3. There is clear evidence of a negative SEO attack with low-quality links pointed at the property. +4. Pre-acquisition due diligence on a property reveals a known toxic profile. + +Outside these cases, the default is to leave links alone. Google has stated repeatedly that they ignore most low-quality links automatically. + +--- + +## Per-link signals (any one is concerning, multiple is decisive) + +### Site-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Site is in a known link network \| High \| +\| Site exists primarily to host links \| High \| +\| Site has thin or auto-generated content \| High \| +\| Site is on a suspect TLD pattern (mass registered) \| Medium \| +\| Site has no organic traffic per Ahrefs estimates \| Medium \| +\| Site is in an irrelevant language or geography \| Medium \| +\| Site has been deindexed or penalized \| High \| +\| Site is parked or for sale \| High \| +\| Site has a footprint shared with many other suspect sites \| High \| + +### Page-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Page is a low-effort link page or directory \| Medium \| +\| Page has a high outbound link count with no editorial logic \| Medium \| +\| Page is hidden from the site's main navigation \| Medium \| +\| Page is in a foreign language with no relevance \| Medium \| +\| Page has been hacked or is serving malware \| High \| + +### Link-level signals + +\| Signal \| Severity \| +\| --- \| --- \| +\| Anchor text is exact-match commercial and unnatural in context \| High \| +\| Link is in a footer with hundreds of others \| Medium \| +\| Link is part of a sitewide footer link \| Medium \| +\| Link is in a comment with promotional text \| Low \| +\| Link is paid without disclosure \| High \| + +--- + +## Deciding by domain versus by URL + +Disavow at the domain level when: + +- The entire site is suspect. +- Multiple pages from the same site link to you. +- You expect the site to keep adding links. + +Disavow at the URL level when: + +- Only one specific page is suspect on an otherwise legitimate site. +- The site has editorial credibility but a single contributor placed the link. + +Default to domain-level disavow when in doubt. URL-level disavows are fragile: the site can move the content and the disavow no longer applies. + +--- + +## Outreach before disavow + +Disavow is a last resort. Before disavowing, attempt outreach for high-value but problematic links: + +1. Find a contact (whois, contact page, social). +2. Send a polite link removal request. +3. Wait 14 days. +4. Send a follow-up. +5. If no response after 30 days, disavow. + +Document outreach attempts. If a manual action review is needed later, Google requires evidence of cleanup effort beyond just a disavow file. + +--- + +## Disavow file format + +The disavow file is a plain text file submitted to Google Search Console. + +Format: + +``` +# Disavow file for [property] +# Last updated: [date] +# Submitted: [date or pending] + +# Section 1: Domain-level disavows + +domain:lowqualitysite-example.com +domain:linkfarm-example.net +domain:hackedsite-example.org + +# Section 2: URL-level disavows + +https://otherwiselegitimate-example.com/sponsored-post-page + +# Section 3: Notes for future me + +# - Disavowed lowqualitysite-example.com after manual action 2024-03 +# - Reviewed quarterly +``` + +Rules: + +- One entry per line +- `domain:` prefix for domain-level +- Full URL for URL-level +- Lines starting with `#` are comments and ignored +- File must be UTF-8 plain text +- Maximum 100,000 lines or 2 MB + +--- + +## Bulk classification heuristic + +When auditing thousands of referring domains, use this triage: + +### Round 1: filter obvious keepers + +Mark as KEEP without further review: + +- Domain Rating above a relevance-appropriate threshold and topical match +- Known media, government, education domains +- Linking from a page with organic traffic + +Skip these. They are not toxic. + +### Round 2: filter obvious toxics + +Mark as TOXIC for further review: + +- Domain Rating zero with no organic traffic +- TLDs in known spam patterns +- Domains matching known link network footprints +- Sites that link to thousands of unrelated properties + +### Round 3: review the middle + +The remaining domains need manual review. Apply the per-link signal table above. + +Expected breakdown for a healthy profile: 80%+ keep, 5-15% review, under 5% toxic. If toxic exceeds 20%, the profile has structural problems beyond a disavow. + +--- + +## After disavow + +- Submit the file in Search Console. +- Document submission date in your audit log. +- Wait 4-8 weeks before evaluating impact. +- Recrawl can take longer for larger sites. +- Do not submit revised disavows weekly. Submit, wait, evaluate. + +If a manual action was the trigger, file a reconsideration request with: + +- Summary of the cleanup effort +- Evidence of outreach attempts +- The submitted disavow file +- An honest acknowledgment of the cause + +--- + +## Common mistakes + +- Disavowing low-traffic links indiscriminately. Most have no negative effect. Disavowing them can lose minor positive equity. +- Disavowing competitor links by accident. Double-check the file before submission. +- Forgetting that disavow is reversible. Resubmit a file without the entry to remove a disavow. Test cautiously. +- Treating disavow as a recurring task. It is not. Audit and submit when needed. Otherwise leave it alone. +- Disavowing without documenting why. Six months later you will not remember which entries were intentional. +- Using disavow as a substitute for outreach. For high-value links, removal is better than disavow. diff --git a/skills/seo-competitor/SKILL.md b/skills/seo-competitor/SKILL.md new file mode 100644 index 0000000..39e585d --- /dev/null +++ b/skills/seo-competitor/SKILL.md @@ -0,0 +1,137 @@ +--- +name: seo-competitor +description: "Run a competitive SEO analysis comparing the user's site to chosen competitors across SERP overlap, content depth, backlink profiles, technical posture, and brand presence. Use this skill whenever the user wants to analyze competitors, find content gaps, identify backlink opportunities, understand why competitors outrank them, or benchmark against the rest of their category. Triggers on competitor analysis, competitive analysis, SERP analysis, content gap, backlink gap, why is X ranking, who is winning the SERP, beat my competitor, benchmark, market positioning. Also triggers when planning a content strategy and the question 'what are competitors doing' is implicit." +category: seo-foundation +catalog_summary: "SERP overlap, content gaps, backlink gaps, technical comparison" +display_order: 4 +--- + +# SEO Competitor Analysis + +Compare a site to its competitors and find the gaps worth closing. Stack-agnostic. Tool-friendly but tool-optional. + +--- + +## When to use + +- Identifying which competitors to study +- Finding content gaps (topics they cover, you do not) +- Finding backlink gaps (sites linking to them, not you) +- Understanding why a specific competitor outranks the user +- Benchmarking authority, technical posture, and content depth + +## When NOT to use + +- Single-page optimization (use `seo-onpage`) +- Initial keyword research with no competitors yet identified (use `seo-keyword` first to find them) +- Auditing one's own existing content (use `seo-content-audit`) + +--- + +## Required inputs + +- The user's site +- 3 to 5 named competitors (or the topic area, if competitors are not yet identified) +- Access to a keyword tool, a backlink tool, and any crawler + +If competitors are unknown, start by listing the top 10 ranking domains for the user's top 10 priority keywords. Pick the 3 to 5 that appear most often. + +Where competitor traffic estimation is the input you need (relative scale, channel mix, audience overlap), Similarweb MCP is the strongest source. Pair with Ahrefs (for backlink and keyword overlap) and Semrush (for SERP feature presence and SEO-PR overlap). Each platform gives a different cut of the same competitive landscape; using them together produces sharper signal than any one alone. + +--- + +## The framework: 5 angles + +Competitor analysis covers five angles. Run all five for a full picture, or pick two or three for a focused investigation. + +### 1. SERP overlap +Where do you and the competitor compete head-to-head? + +- For each priority keyword, who ranks in the top 10? +- For each top-10 ranking, what page type wins (article, product, comparison, video)? +- Are there SERP features (featured snippet, AI overview, video, image pack) one party holds and the other does not? +- Which queries do competitors rank for that the user does not? (the content gap) + +### 2. Content depth +What does their winning content look like? + +- Word count and structure of their top-ranking pages +- Information types they include (data tables, original research, video, calculators, downloadable assets) +- Update frequency on key pages (last modified date, change history) +- Internal linking patterns (do their winning pages link to commercial pages?) +- Topical breadth (how many related topics do they cover?) + +### 3. Backlink profile +Where does their authority come from? + +- Total referring domains +- Domain rating (or equivalent authority metric) +- Top 50 referring pages by traffic value +- Backlink types (editorial, directory, partner, paid, spam) +- Link velocity (gaining or losing referring domains over time) +- Pages on their site attracting the most links (these are their "linkable assets") + +### 4. Technical posture +How clean is their technical foundation? + +- Core Web Vitals (LCP, INP, CLS) +- Mobile usability +- Schema implementation (which types, on which page types) +- Site architecture and internal linking density +- Crawl efficiency (are they wasting crawl budget?) +- HTTPS, security headers +- llms.txt and AI search readiness + +### 5. Brand and entity strength +How well-known are they outside organic search? + +- Branded search volume (how many people search their name?) +- Entity recognition in knowledge graph (do they have a Wikipedia page, knowledge panel, structured data feeding entity status?) +- Mention frequency in their topic area (PR coverage, podcast appearances, citations) +- Social signals (followers, engagement, share rates) +- Reviews and reputation + +--- + +## Workflow + +1. Confirm the competitors. Either named, or derive from SERP overlap on top 10 priority keywords. +2. Pick the angles. Run all 5 for a full audit, or 2 to 3 for a focused dive. +3. Pull the data. Keyword tool exports, backlink tool exports, manual SERP inspection, technical crawl. +4. Score each angle. Where does the user lead? Where do they trail? +5. Identify gaps. Specific content gaps, specific backlink gaps, specific technical gaps. +6. Prioritize. Which gaps are highest leverage to close? (Big traffic potential, achievable effort, strategic fit.) +7. Write the report. Use the template in [`references/competitive-audit-template.md`](references/competitive-audit-template.md). + +--- + +## Failure patterns + +- Picking the wrong competitors. A site that outranks you on one keyword but operates a different business is not a competitor. Pick by SERP overlap and audience overlap, not by who you think you compete with. +- Treating "more content" as the takeaway. They are not winning because they have 500 articles. They are winning because of specific content + links + UX. Find the actual lever. +- Copying their pages verbatim. Diminishing returns. Beat them by being more useful, not by paraphrasing them. +- Ignoring brand strength. A weaker site with a stronger brand wins on branded queries you cannot touch with content alone. +- Static analysis. Re-run the analysis at least annually. Competitor strategies shift. + +--- + +## Output format + +Default output is a markdown report at `competitive-analysis.md` plus accompanying spreadsheets for the keyword and backlink data. + +Structure: +1. Executive summary (3 to 5 critical findings) +2. Competitor profiles (one per competitor, brief) +3. SERP overlap analysis +4. Content gap analysis +5. Backlink gap analysis +6. Technical comparison +7. Brand and entity comparison +8. Prioritized gap-closing roadmap + +--- + +## Reference files + +- [`references/competitive-audit-template.md`](references/competitive-audit-template.md) - Fillable competitive audit template. +- [`references/content-gap-method.md`](references/content-gap-method.md) - Detailed methodology for finding content gaps with example. diff --git a/skills/seo-competitor/references/competitive-audit-template.md b/skills/seo-competitor/references/competitive-audit-template.md new file mode 100644 index 0000000..556d013 --- /dev/null +++ b/skills/seo-competitor/references/competitive-audit-template.md @@ -0,0 +1,160 @@ +# Competitive SEO Analysis: [Your Site] vs Competitors + +Date: [YYYY-MM-DD] +Site under audit: [URL] +Competitors analyzed: [List] +Analyst: [Name] + +--- + +## Executive summary + +[3 to 5 critical findings. Lead with the most important. What is the single biggest gap to close, and what is the single biggest strength to defend?] + +Top 3 priorities: +1. [Priority] +2. [Priority] +3. [Priority] + +--- + +## Competitor profiles + +### Competitor 1: [Name] +- Domain rating: [X] +- Estimated organic traffic: [X / month] +- Total referring domains: [X] +- Top 3 ranking categories: [What they win on] +- Why they matter: [1 to 2 sentences] +- Their key advantage over us: [1 sentence] + +### Competitor 2: [Name] +[Same structure] + +### Competitor 3: [Name] +[Same structure] + +--- + +## SERP overlap analysis + +Keywords where we both rank top 10: [N] +Keywords where they rank, we don't: [N] +Keywords where we rank, they don't: [N] +Keywords where they hold a SERP feature we don't: [N] + +### Head-to-head wins +[Top 10 keywords where we currently rank above them] + +\| Keyword \| Our rank \| Their rank \| Volume \| +\|---\|---\|---\|---\| +\| \| \| \| \| + +### Head-to-head losses +[Top 10 keywords where they rank above us] + +\| Keyword \| Our rank \| Their rank \| Volume \| Likely reason they win \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +### Their territory (we don't rank) +[Top 20 keywords they rank for that we don't, ranked by traffic potential] + +\| Keyword \| Their rank \| Volume \| Difficulty \| Strategic fit for us \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| + +--- + +## Content gap analysis + +[Topics or page types they cover that we don't, organized by theme.] + +### Theme 1: [e.g., "How-to guides for beginners"] +- Their coverage: [X pages, including these top performers...] +- Our coverage: [None / weak / partial] +- Estimated traffic value if closed: [X visits/month] +- Recommended action: [Produce / partial coverage / skip] + +### Theme 2: [e.g., "Comparison content"] +[Same structure] + +--- + +## Backlink gap analysis + +Their referring domains we don't have: [N] +Their unique referring domains (in our category): [N] + +### Top 10 backlink opportunities +[Domains linking to multiple competitors but not us. These are the highest-probability outreach targets.] + +\| Domain \| Domain rating \| Links to (competitors) \| Why they link to them \| +\|---\|---\|---\|---\| +\| \| \| \| \| + +### Their linkable assets +[Pages on competitor sites that attract the most backlinks. These are the asset types we could replicate.] + +\| URL \| Referring domains \| Asset type \| +\|---\|---\|---\| +\| \| \| \| + +--- + +## Technical comparison + +\| Dimension \| Us \| Comp 1 \| Comp 2 \| Comp 3 \| +\|---\|---\|---\|---\|---\| +\| LCP (mobile) \| \| \| \| \| +\| INP (mobile) \| \| \| \| \| +\| CLS (mobile) \| \| \| \| \| +\| Mobile-friendly \| \| \| \| \| +\| HTTPS / HSTS \| \| \| \| \| +\| Schema types \| \| \| \| \| +\| Sitemap quality \| \| \| \| \| +\| llms.txt present \| \| \| \| \| +\| Internal links per page (avg) \| \| \| \| \| + +Key takeaways: [Where are we ahead, where are we behind?] + +--- + +## Brand and entity comparison + +\| Dimension \| Us \| Comp 1 \| Comp 2 \| Comp 3 \| +\|---\|---\|---\|---\|---\| +\| Branded search volume \| \| \| \| \| +\| Wikipedia entity \| \| \| \| \| +\| Knowledge panel \| \| \| \| \| +\| Editorial mentions / month \| \| \| \| \| +\| Social following \| \| \| \| \| +\| Reviews aggregate \| \| \| \| \| + +--- + +## Prioritized gap-closing roadmap + +[Sequenced list of actions, with effort and expected impact.] + +### Quarter 1 +1. [Action] - [effort] - [expected impact] +2. [Action] - [effort] - [expected impact] + +### Quarter 2 +1. [Action] + +### Quarter 3+ +[Strategic plays that take longer to execute.] + +--- + +## What we should defend + +Areas where we currently lead and need to maintain: + +- [Strength] +- [Strength] +- [Strength] + +A defensive strategy is as important as a gap-closing one. diff --git a/skills/seo-competitor/references/content-gap-method.md b/skills/seo-competitor/references/content-gap-method.md new file mode 100644 index 0000000..f7f0083 --- /dev/null +++ b/skills/seo-competitor/references/content-gap-method.md @@ -0,0 +1,225 @@ +# Content Gap Method + +A detailed methodology for finding content gaps between your site and competitors. The output is a prioritized list of topics or queries the competition ranks for and you do not, ranked by opportunity. + +This is the methodology. For the orchestrated version that runs against the Ahrefs MCP, use `seo-content-gap-audit`. + +--- + +## What a content gap is (and is not) + +A content gap is a query or topic where: + +- One or more competitors rank in the top 10 +- You do not rank in the top 100 (or rank weakly) +- The query is plausibly something your audience cares about +- You could credibly produce content that addresses it + +A content gap is not: + +- Every keyword a competitor ranks for. Many of those will not match your audience. +- Branded queries for the competitor. You will never rank for "[CompetitorName] login" and should not try. +- Queries with unwinnable SERPs (dominated by Reddit, video, or marketplace listings) unless you have an unusual asset. + +--- + +## Step 1: define the competitor set + +Three categories of competitors. Include all three. + +### Direct competitors + +Same product, same audience. Found in your "industry," your sales process, your churn data. + +### Search competitors + +Whoever ranks for the queries you care about. Often surprising. Often includes industry publications, aggregators, and adjacent SaaS tools you do not consider competition commercially. + +To find search competitors: + +1. Pull your top 20 priority queries. +2. Note the top 10 ranking domains for each. +3. Aggregate. Domains that appear 5+ times are search competitors, even if they are not direct. + +### Aspirational competitors + +Brands that own the topic-area you want to own. Often larger or older. Useful for surfacing topics, less useful for direct comparison. + +Build a final set of 5-10 competitors. More than that gets noisy. + +--- + +## Step 2: pull keyword data + +For each competitor, pull the queries they rank for in the top 10 (or top 20 for completeness). + +Filter out: + +- Branded queries containing the competitor name +- Queries with monthly volume below your relevance threshold (commonly 50-100, lower for niche industries) +- Queries with no clear commercial or informational intent (typos, location-specific irrelevant queries, etc.) +- Queries with parent topic that does not apply to your business + +Tools: Ahrefs Site Explorer (Organic keywords), Semrush Organic Research, or DataForSEO equivalents. + +--- + +## Step 3: build the gap matrix + +Cross-reference all competitors against your site. + +\| Query \| Competitor 1 position \| Competitor 2 position \| Competitor 3 position \| Your position \| Monthly volume \| Difficulty \| +\|---\|---\|---\|---\|---\|---\|---\| +\| query a \| 3 \| 7 \| - \| 45 \| 1,200 \| 32 \| +\| query b \| 5 \| 4 \| 8 \| not ranking \| 800 \| 28 \| +\| query c \| 1 \| - \| 5 \| 12 \| 500 \| 41 \| + +Three categories emerge: + +- Pure gaps: competitors rank, you do not. Highest opportunity. Filter for queries where 2+ competitors rank. +- Weak coverage: you rank but poorly (positions 11-50). Often the fastest wins. +- Saturated topics: you and 1+ competitors all rank well. Defensive territory; opportunity to leapfrog. + +Focus the next steps on Pure gaps and Weak coverage. + +--- + +## Step 4: cluster by topic + +Raw query lists are unmanageable. Cluster by topic so you can plan content, not chase individual keywords. + +### Method + +Group queries that share intent and can be answered by the same piece of content. + +- "best crm for startups," "top crm small business," "crm software comparison" - one cluster, one comparison piece. +- "how to choose a crm," "crm buying guide" - same cluster. +- "what is a crm," "crm definition" - separate cluster (top-of-funnel, glossary or pillar lead-in). + +A cluster is one piece of content (or a closely-related set: pillar + spokes). + +### Output + +\| Cluster \| Sample queries \| Total monthly volume \| Avg difficulty \| Recommended format \| Lead competitor \| +\|---\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| \| +\| \| \| \| \| \| \| + +--- + +## Step 5: assess each cluster + +For each cluster, answer: + +### Audience fit + +Does this cluster match your audience? If you sell to enterprise but the cluster is dominated by SMB intent ("free crm for solopreneurs"), score it low. + +### SERP analysis + +Open the SERP for the highest-volume query in the cluster. Note: + +- Result types: organic blue links, video, AI overview, featured snippet, local pack, shopping. Some SERPs leave little real estate for new entrants. +- Result formats: what kind of pages rank? Blog posts, comparison pages, product pages, free tools, video? +- Domain mix: dominated by big publishers (HubSpot, Forbes), niche players, Reddit, or peer companies? +- SERP volatility: has the top 10 been stable, or churning? + +### Effort estimate + +How long would it take to produce content competitive with what is ranking? Be honest. Some clusters need a 4,000-word definitive guide with original research. Others need a 1,200-word how-to. + +### Scoring + +Combine into a simple opportunity score per cluster. Example: + +``` +Opportunity = (Volume × Audience Fit × SERP Winnability) / Effort +``` + +Where: + +- Volume: total monthly volume across cluster +- Audience Fit: 1 (poor), 2 (decent), 3 (perfect match) +- SERP Winnability: 1 (saturated, big domains), 2 (mixed), 3 (gettable) +- Effort: hours of writing, research, asset creation + +This is not a precise formula. Use it to rank clusters, then sanity-check the top of the list against editorial judgment. + +--- + +## Step 6: produce the gap report + +A typical output deliverable: + +### Section 1: executive summary + +- Top 10 clusters ranked by opportunity score +- Estimated total monthly traffic potential if you captured the average competitor position +- Estimated effort (in hours or pieces of content) to address the top 10 + +### Section 2: cluster details + +For each top cluster: + +- Cluster name and theme +- Sample queries with volume and difficulty +- SERP analysis snapshot +- Lead competitor's content URL with a one-line note on what makes it strong +- Recommended content format and length +- Recommended hook or angle +- Estimated effort +- Why we should rank: the unique asset, perspective, or data we can bring + +### Section 3: clusters to skip + +Clusters that surfaced but should not be pursued, with the reason. (Audience mismatch, SERP unwinnable, etc.) Documenting skips prevents re-litigation. + +### Section 4: next steps + +- Hand-off to `content-strategy` for editorial planning +- Production sequencing (which cluster ships first) +- Measurement: how will you track whether the gap is closing + +--- + +## Worked example + +Site: B2B project management tool, 50-person company, target audience is engineering leads at series-B SaaS startups. + +Competitors (5): +1. Linear (direct, peer) +2. Jira (direct, incumbent) +3. Notion (adjacent, encroaching) +4. Asana (direct, larger) +5. Height (direct, peer) + +### Gap matrix excerpt + +\| Cluster \| Sample queries \| Volume \| Difficulty \| Lead competitor \| Audience fit \| SERP winnable \| Effort \| Opportunity \| +\|---\|---\|---\|---\|---\|---\|---\|---\|---\| +\| "linear vs jira" \| 5,400 \| 38 \| linear.app \| High \| Mixed \| Med \| High \| +\| "engineering project management" \| 2,100 \| 42 \| linear.app \| High \| Big domains \| Med \| High \| +\| "agile sprint planning" \| 14,000 \| 55 \| atlassian.com \| Med \| Saturated by Atlassian \| High \| Low \| +\| "github issue templates" \| 3,200 \| 28 \| github.com \| High \| Owned by github.com \| Med \| Skip \| + +### Recommendations + +- Pursue: "linear vs jira" cluster (5 related comparison queries, 7,200 combined monthly volume, mid-effort, audience-perfect). Format: comparison page anchored by an internal POV piece. +- Pursue: "engineering project management" cluster (broader topic, 4 related queries, requires a pillar piece + 3 spokes). Format: pillar guide + spokes. +- Skip: "agile sprint planning." Atlassian owns this with deep, mature content; effort to compete is too high vs opportunity. +- Skip: "github issue templates." github.com itself ranks #1; even strong content will not displace. + +### Next steps + +- Hand the two pursued clusters to content-strategy for editorial sequencing. +- Track positions weekly for the cluster's primary queries. +- Re-run the gap analysis quarterly to spot new gaps as competitors publish. + +--- + +## When to re-run + +- Quarterly as a routine. +- After a major competitor launch (new product page, big content push, redesign). +- After a search algorithm update (especially core updates that reshuffle SERPs). +- When entering a new audience segment (segment-specific competitors emerge). diff --git a/skills/seo-content-audit/SKILL.md b/skills/seo-content-audit/SKILL.md new file mode 100644 index 0000000..36ecee8 --- /dev/null +++ b/skills/seo-content-audit/SKILL.md @@ -0,0 +1,193 @@ +--- +name: seo-content-audit +description: "Audit existing content across a site to decide what to keep, update, merge, redirect, or delete. Use this skill whenever the user wants to audit existing content, fix content decay, resolve keyword cannibalization, prune underperforming pages, prioritize content updates, or apply a keep/update/merge/redirect/delete framework to a content library. Triggers on content audit, content decay, content refresh, cannibalization, keyword cannibalization, prune content, delete pages, redirect old pages, content inventory, what to keep, what to update, content scorecard, evergreen refresh. Also triggers when traffic is dropping site-wide and the cause might be content quality, even if 'audit' is not said explicitly." +category: seo-foundation +catalog_summary: "Keep/update/merge/redirect/delete decisions across a site" +display_order: 6 +--- + +# Content Audit + +Inventory existing content, score it, and decide for each piece: keep, update, merge, redirect, or delete. Stack-agnostic. Works on blogs, marketing sites, knowledge bases, and product content. + +--- + +## When to use + +- Inheriting a content library you did not create +- Diagnosing site-wide traffic decline +- Resolving cannibalization (two pages competing for the same query) +- Pre-migration cleanup +- Annual or semi-annual content health check +- Pruning before a redesign or replatform + +## When NOT to use + +- Optimizing a single page (use `seo-onpage`) +- Planning new content (use `seo-keyword`) +- Comparing your content to competitors (use `seo-competitor`) +- Site-level technical issues (use `seo-technical`) + +--- + +## Required inputs + +- The site URL and access to crawl it (or a complete URL list) +- Search console access (or a 12-month export) +- Analytics access (sessions, conversions, engagement) +- A backlink tool (to identify pages with referring domains worth preserving) + +--- + +## The framework: 5 actions + +For every content piece, the audit produces one of five decisions. + +### 1. Keep +The page performs well, has clear intent, and needs no changes. + +Signals: +- Top 10 ranking for its primary query +- Consistent traffic with no decay +- Healthy engagement (above-site-average time on page or interaction rate) +- Up-to-date information + +### 2. Update +The page has potential but is underperforming due to fixable issues. + +Signals: +- Page 2 ranking for high-value queries (rank 11 to 30) +- Traffic decay over the last 6 to 12 months +- Information gone stale +- Title or meta need rewriting for CTR +- Thin content that could expand to match competitor depth +- Missing schema or other technical hygiene + +### 3. Merge +Two or more pages target overlapping queries and should consolidate. + +Signals: +- Cannibalization (multiple pages ranking for the same query, none ranking well) +- Significant content overlap between pages +- Combined, they would outperform either alone +- Both have backlinks worth preserving + +### 4. Redirect +The page has no future but has assets (links, equity) worth preserving. + +Signals: +- No traffic, no rankings +- Holds backlinks (especially editorial ones) +- A relevant target page exists that would benefit from the equity +- Topic is still relevant but this specific page is not + +### 5. Delete (and let return 404 or 410) +The page has no future and no assets worth preserving. + +Signals: +- No traffic, no rankings, no backlinks +- Content is outdated and not worth updating +- Topic is no longer relevant +- Even thin or spam content from a previous era + +Note: In most cases, return 410 (gone) for intentionally deleted content. 410 is processed faster than 404 and signals the deletion was deliberate. + +--- + +## Scoring inputs + +Pull these for every URL before deciding: + +\| Metric \| Source \| Threshold for "low" \| +\|---\|---\|---\| +\| Sessions (last 90 days) \| Analytics \| <10/month \| +\| Organic traffic (last 90 days) \| Search console or analytics \| <5/month \| +\| Average position for top query \| Search console \| >30 \| +\| Impressions (last 90 days) \| Search console \| <100/month \| +\| Click-through rate \| Search console \| <1% (when impressions exist) \| +\| Referring domains \| Backlink tool \| 0 \| +\| Engagement (avg time on page) \| Analytics \| <30 seconds \| +\| Last meaningful update \| Manual / git \| >24 months \| +\| Word count \| Crawler \| <300 (for articles) \| +\| Internal links in \| Crawler \| 0 \| + +A page can survive low scores on a few metrics. A page that fails on most is a delete or redirect candidate. + +--- + +## Decision matrix + +A simplified decision tree: + +``` +Has traffic? ─── Yes ──── Recent decay? ─── Yes ── UPDATE + │ │ + │ └── No ─── KEEP + │ + └── No ──── Has backlinks? ─── Yes ── Has relevant target? ─── Yes ── REDIRECT + │ │ + │ └── No ─── UPDATE (rebuild) + │ + └── No ──── Cannibalizing another page? ─── Yes ── MERGE + │ + └── No ─── DELETE (410) +``` + +For overlapping pages, "merge" usually wins over "delete" because it preserves both link equity and any topical authority. + +--- + +## Workflow + +1. Inventory. Pull a complete URL list from the crawl, sitemap, and search console (some indexed pages may not be in the sitemap). +2. Pull the metrics. Sessions, organic, search console rank/CTR, backlinks, last-modified date, word count. +3. Score each URL. Use the framework. Mark a decision: Keep / Update / Merge / Redirect / Delete. +4. Identify cannibalization clusters. Group URLs targeting the same query. Decide which becomes the canonical, what to merge, what to redirect. +5. Sequence the work. Do redirects and deletes in batches. Plan updates by priority (highest-traffic-recovery potential first). +6. Implement. With change tracking. Re-crawl after each batch to confirm no broken redirect chains. +7. Measure. Track aggregate organic traffic 30, 60, 90 days post-audit. + +--- + +## Failure patterns + +- Deleting pages with backlinks. Always check referring domains before deleting. A redirect preserves equity at near-zero cost. +- Updating pages that should be merged. Two thin pages updated to medium pages still cannibalize. Merge first. +- Merging without preserving the better URL. Pick the merge target by which URL has stronger signals (older URL, more backlinks, better URL slug, currently better ranking), not which one has more content. +- Mass-deleting low-traffic pages. Some have value: fresh pages still ramping, niche pages serving a specific audience, evergreen pages with seasonal traffic. Do not bulk-delete by sessions alone. +- Over-aggressive pruning of "old" content. Date alone is not a delete signal. Topic relevance and intent quality are. +- No post-audit measurement. Without measurement, you cannot tell if the audit worked. + +--- + +## Output format + +Default output: a spreadsheet with one row per URL, plus a summary markdown report. + +Spreadsheet columns: +- URL +- Page type (article, product, category, etc.) +- Sessions (90d), organic clicks (90d), impressions (90d), avg position +- Referring domains +- Word count +- Last modified +- Decision (keep / update / merge / redirect / delete) +- Merge target / redirect target (if applicable) +- Priority (1-5) +- Notes + +Summary report: +1. Inventory totals (URLs by decision) +2. Cannibalization clusters identified +3. Top 20 update priorities +4. Redirect map (CSV) +5. Delete list +6. Implementation roadmap (sequenced by priority) +7. Measurement plan + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Spreadsheet column definitions and report template. +- [`references/cannibalization-resolution.md`](references/cannibalization-resolution.md) - Detailed methodology for resolving cannibalization clusters. diff --git a/skills/seo-content-audit/references/audit-template.md b/skills/seo-content-audit/references/audit-template.md new file mode 100644 index 0000000..246de40 --- /dev/null +++ b/skills/seo-content-audit/references/audit-template.md @@ -0,0 +1,223 @@ +# Content Audit Template + +Spreadsheet column definitions and report template for a site-wide content audit. The output is a per-URL decision (keep / update / merge / redirect / delete) plus a summary report for stakeholders. + +--- + +## What this audit produces + +- A spreadsheet (one row per URL) with all signals and the final decision +- A report that summarizes the decisions, the rationale, and the next-step backlog +- A roll-up of expected SEO impact and effort + +--- + +## Required spreadsheet columns + +Every row is one URL. Every column below is required. + +\| Column \| Type \| Source \| Description \| +\|---\|---\|---\|---\| +\| URL \| Text \| Crawl \| Full URL \| +\| Title tag \| Text \| Crawl \| Current `<title>` \| +\| H1 \| Text \| Crawl \| Current H1 \| +\| Word count \| Number \| Crawl \| Body text words \| +\| Publish date \| Date \| CMS / inferred \| Original publish date \| +\| Last updated \| Date \| CMS \| Most recent meaningful update \| +\| Page type \| Pick list \| Manual / patterned URL \| Article / product / category / landing / utility / legal / etc. \| +\| Topic cluster \| Pick list \| Manual \| Which topic cluster (from content strategy) \| +\| Primary query target \| Text \| Manual / GSC top query \| The query the page should rank for \| +\| Sessions (last 90d) \| Number \| Analytics \| Organic sessions \| +\| Conversions (last 90d) \| Number \| Analytics \| Goal completions attributable to this URL \| +\| Top ranking position \| Number \| GSC / rank tracker \| Best position achieved in last 90d \| +\| Average position \| Number \| GSC \| Average position in last 90d \| +\| Impressions (last 90d) \| Number \| GSC \| \| +\| CTR (last 90d) \| Number \| GSC \| \| +\| Backlinks (referring domains) \| Number \| Backlink tool \| \| +\| Internal inlinks \| Number \| Crawl \| Number of internal pages linking to this URL \| +\| Last meaningful traffic \| Date \| Analytics \| Most recent month with traffic above threshold \| +\| Decision \| Pick list \| Manual \| Keep / Update / Merge / Redirect / Delete \| +\| Reasoning \| Text \| Manual \| One sentence per decision \| +\| Action notes \| Text \| Manual \| What needs to happen if Update or Merge \| +\| Owner \| Person \| Manual \| Who executes \| +\| Target completion \| Date \| Manual \| When the action ships \| +\| Status \| Pick list \| Manual \| Backlog / In progress / Shipped / Verified \| + +--- + +## Optional but recommended columns + +\| Column \| Description \| +\|---\|---\| +\| Cannibalization risk \| Other URLs ranking for the same primary query. See `cannibalization-resolution.md`. \| +\| Schema present \| Yes / No / Type \| +\| Has index tag \| Indexable / noindex \| +\| Status code \| 200 / 301 / 404 etc. (catches accidental noindex or broken pages) \| +\| Time on page \| From analytics; rough engagement signal \| +\| Bounce rate or scroll depth \| From analytics \| +\| Current canonical \| Self / other URL \| +\| Image count \| Helps identify thin pages \| +\| Outbound external links \| \| +\| Topic authority signal \| Original research, expert author, structured comparison, etc. - subjective but useful \| + +--- + +## The 5 decision types + +### Keep + +Page is performing or recently published. No action needed. Track for future audits. + +Default for: +- Top 20% of pages by sessions +- Pages within 3 months of publish (too early to judge) +- Cornerstone pages with strong rankings or backlinks + +### Update + +Page is on the right topic but has decayed (rankings down, content stale, broken links, missing schema). + +Action: add to the editorial backlog with a specific update brief. Common updates: refresh examples and dates, expand thin sections, add new H2s for related queries surfacing in GSC, improve title and meta, add schema, update screenshots and links. + +### Merge + +Two or more pages cover the same intent and split signals. Combine into one stronger page. + +Action: pick the canonical winner (usually the one with more backlinks and more search visibility), redirect the loser(s) to the winner, fold the loser's unique content into the winner. + +### Redirect + +Page no longer relevant but has equity (backlinks, traffic, internal links) worth preserving. + +Action: 301 redirect to the closest topical match. If no match exists, redirect to the parent category or topic hub. Avoid blanket redirects to homepage (Google often treats them as soft 404s). + +### Delete + +Page has no traffic, no rankings, no backlinks, no internal links pointing to it, and no strategic role. + +Action: return 410 Gone (preferred) or 404 if 410 is not supported. Update sitemap. Remove internal links pointing to the deleted page. + +### Decision tree + +``` +Page is performing well? +├── Yes → Keep +└── No → Page is on a relevant topic? + ├── Yes → Page is the only one on this topic? + │ ├── Yes → Update (refresh and expand) + │ └── No → Merge (consolidate into stronger version) + └── No → Page has equity (backlinks, internal links)? + ├── Yes → Redirect to closest topical match + └── No → Delete (410 Gone) +``` + +--- + +## Triage thresholds + +The audit looks at hundreds or thousands of URLs. Triage thresholds let you focus. + +### Performing (default Keep) + +- 100+ organic sessions in last 90 days, OR +- 1+ conversions in last 90 days, OR +- 10+ referring domains, OR +- Average position 1-10 for primary query + +### Decaying (default Update or Merge) + +- 5-100 sessions in last 90 days +- Average position 11-50 +- Last meaningful traffic 6-24 months ago + +### Dormant (default Redirect or Delete) + +- 0-5 sessions in last 90 days +- Average position 51+ +- Last meaningful traffic 24+ months ago + +These are starting points. Adjust to your site's volume. + +--- + +## Cannibalization check + +For each primary query target, group URLs targeting the same query. If 2+ URLs target the same query: + +- One ranking, one not: the non-ranking one is a Merge or Redirect candidate. +- Both ranking but neither in top 5: classic split-signal case. Merge into one definitive page. +- One ranking strong, one ranking weak: the weak one is a Merge candidate. + +For deeper diagnosis and resolution patterns, see `cannibalization-resolution.md`. + +--- + +## Report template + +The audit produces a stakeholder-readable report. + +### Section 1: executive summary + +- Total URLs audited +- Decisions: Keep / Update / Merge / Redirect / Delete (with counts and percentages) +- Estimated SEO impact: traffic preserved, traffic potential unlocked, traffic risk if action delayed +- Estimated effort: hours of writing, engineering URL work, design work + +### Section 2: decisions by topic cluster + +Per cluster: how many pages, decisions, top action items. + +### Section 3: top opportunities + +The 10-20 highest-leverage actions (typically Updates and Merges that protect strong rankings or unlock obvious wins). + +### Section 4: risks if no action + +What happens if the team does not act. Common: continued ranking decay, cannibalization that suppresses both URLs, technical risk (crawl budget), content sprawl that confuses readers. + +### Section 5: backlog and sequencing + +Prioritized backlog with owners and target dates. Sequence so that: + +- Redirects ship first (they are mechanical and preserve equity) +- Merges ship second (combine before refreshing) +- Updates ship third (work on what remains) +- Deletes happen last (after all redirects and merges that depend on those URLs are in) + +--- + +## Pre-audit checklist + +Before running the audit: + +- [ ] Analytics access granted (GA4 or equivalent) +- [ ] Search Console access granted +- [ ] Crawl tool ready (Screaming Frog, Sitebulb, or hosted equivalent) +- [ ] Backlink data source identified (Ahrefs, Semrush, GSC limited data) +- [ ] Topic clusters defined (from content strategy) +- [ ] Threshold values agreed (sessions, position, age) +- [ ] Decision authority confirmed (who can approve Delete and Merge actions) +- [ ] Implementation owner confirmed (who runs the post-decision work) + +--- + +## Post-audit verification + +After the actions ship: + +- [ ] Verify all redirects resolve correctly (no chains, no loops) +- [ ] Verify all 410/404 pages return correct status +- [ ] Update sitemap to remove deleted URLs and reflect canonical changes +- [ ] Resubmit sitemap in Search Console +- [ ] Monitor the merged URLs for ranking confirmation (typically 2-8 weeks) +- [ ] Re-run a slim audit at 90 days to confirm decay was halted + +--- + +## Sign-off + +Audit produced by: [Name, date] +Decisions approved by: [Name, role, date] +Implementation owner: [Name, date] + +Next audit scheduled: [Date - typically annual or after major content investment] diff --git a/skills/seo-content-audit/references/cannibalization-resolution.md b/skills/seo-content-audit/references/cannibalization-resolution.md new file mode 100644 index 0000000..e4ad239 --- /dev/null +++ b/skills/seo-content-audit/references/cannibalization-resolution.md @@ -0,0 +1,148 @@ +# Cannibalization Resolution + +When two or more pages on the same site compete for the same query, all of them lose. Search engines either pick the wrong one to rank, split the ranking signal across both, or rotate between them unpredictably. + +This reference walks through how to identify and resolve cannibalization. + +--- + +## How to identify cannibalization + +You have cannibalization when: + +- Two or more URLs from your site appear in the top 50 for the same query +- A query has multiple URLs ranking and rotating across the top 30 over time (search console shows this as inconsistent) +- A new page appears for a query and the previously-ranking page drops sharply +- Two URLs on the same site share the same primary intent and substantial content overlap + +How to find it: + +1. Export search console queries with multiple ranking URLs +2. Look for queries where the same site appears more than once in the data +3. Check rank stability: if a query bounces between URLs week to week, that is the signal +4. Internal: search your own site (`site:yourdomain.com "exact query"`) and see how many results appear + +--- + +## Resolution decision tree + +For each cannibalization cluster, you have four options. + +``` +Same intent? ─── Yes ──── Substantial content overlap? ─── Yes ── MERGE + │ + └── No ── Different angles, same intent? ─── DIFFERENTIATE + │ + └── No ──── Confirm intent classification, may not be cannibalization +``` + +### Option 1: Merge + +Combine the pages into one canonical page. Use this when: +- Both pages serve the same intent +- Content overlaps substantially +- Combined, the page would be stronger than either alone + +Steps: +1. Pick the merge target. Best signals win: highest-ranking URL, most backlinks, older URL, cleaner URL slug. +2. Pull the unique content from the loser pages, integrate into the winner. +3. 301 redirect the loser URLs to the winner. +4. Update internal links pointing at loser URLs to point at the winner. +5. Submit the winner URL for re-crawling. +6. Monitor rankings for 30 to 60 days. + +### Option 2: Differentiate + +Keep both pages, but reposition each to target distinct sub-intents. Use this when: +- The pages serve genuinely different queries that just look similar +- Both have meaningful traffic and rankings that are worth preserving +- The category supports nuanced sub-topics + +Steps: +1. Identify the distinct intent each page should target (e.g., "best running shoes" vs "best running shoes for beginners") +2. Rewrite titles, meta, H1, and intros to reinforce the distinct intent +3. Update internal links to use distinct anchor text +4. Cross-link the two pages so each acknowledges the other +5. Update any sitemap or hub page that lists them + +### Option 3: Redirect + +Pick a winner, kill the rest. Use this when: +- One page is clearly stronger +- The losers have no unique content worth preserving +- There is no benefit to maintaining multiple pages + +Steps: +1. Pick the winner using the same criteria as merge. +2. 301 redirect the losers to the winner. +3. Pull any unique content from the losers and integrate into the winner if useful. +4. Update internal links. + +### Option 4: Noindex the secondary page + +Keep both pages, but tell search engines to only consider one for ranking. Use this when: +- One page has a strong UX or business reason to exist (e.g., a product variant page) +- It does not need to rank, but does need to exist +- Merging would damage UX + +Steps: +1. Add `<meta name="robots" content="noindex, follow">` to the secondary page +2. Confirm the canonical of the secondary page points at itself (not the primary), since canonical and noindex serve different purposes +3. Verify in search console after a week that the noindex took effect +4. Maintain the user-facing functionality of the page + +--- + +## Picking the merge winner + +When you have to choose which URL becomes canonical, use this prioritized scoring: + +1. Current ranking position. If one URL is on page 1 and the other on page 3, keep page 1. +2. Backlinks. Highest count of referring domains usually wins. +3. URL quality. Cleaner slug, fewer parameters, shorter, descriptive. +4. Internal links in. More inbound internal links signals existing site structure. +5. Page age. Older URLs often have accumulated trust signals. +6. Content quality. If all else is tied, pick the one with better content (or the one easier to expand). + +Do not pick by recency of publication or "I just wrote it." Search engines reward signals that have accumulated over time. + +--- + +## Common cannibalization patterns + +### Pattern 1: Old article + new article on same topic + +Common in evergreen sites. Resolution: merge, with the older URL as canonical (preserves backlinks and age signals). + +### Pattern 2: Category page + product page targeting same query + +Resolution: differentiate. Category page targets the broad query ("running shoes"). Product pages target product-specific queries ("[brand] [model] running shoes"). + +### Pattern 3: Blog post + landing page + +Resolution: differentiate aggressively or merge. Blog post targets informational intent. Landing page targets commercial intent. If they keep cannibalizing, the keyword is fundamentally one-intent and one of them needs to retire. + +### Pattern 4: Multiple "best X" listicles for slight variants + +E.g., "best running shoes," "best running shoes for women," "best running shoes for marathons." Resolution: maintain a clear hub-and-spoke structure. The hub page targets the broad query. Spoke pages target specific variants. Cross-link. + +### Pattern 5: Geographic variants + +E.g., "best plumber" vs "best plumber in Denver." Resolution: differentiate by geo modifier in title, H1, content. Use schema (LocalBusiness) for the geo-specific pages. + +--- + +## Verification after resolution + +For 60 days post-resolution, monitor: + +- Rank for the canonical URL on the target query (should stabilize and improve) +- Rank for the merged/redirected URLs (should drop out, which is expected) +- Aggregate impressions and clicks for the cluster (should rise as ranking signals consolidate) +- Internal links pointing at deprecated URLs (should be zero after cleanup) + +If the canonical URL does not improve in rank within 60 days, recheck: + +- Did the redirects fire correctly? (Test 5 random old URLs) +- Are there still other pages on the site competing for the same query? +- Is the canonical URL strong enough on its own to rank? (Compare to top-ranking competitors) diff --git a/skills/seo-content-gap-audit/SKILL.md b/skills/seo-content-gap-audit/SKILL.md new file mode 100644 index 0000000..f7fcf21 --- /dev/null +++ b/skills/seo-content-gap-audit/SKILL.md @@ -0,0 +1,159 @@ +--- +name: seo-content-gap-audit +description: "Audit content gaps and decay using Ahrefs MCP data: missing topics, thin coverage, outdated content, and decaying pages. Use this skill when planning a content roadmap, refreshing a stale catalog, building topical authority, or identifying which existing pages need update versus replacement. Triggers on content gap, content audit, content refresh, content roadmap, decaying content, content decay, topical authority, what topics should we cover, where is competitor content stronger. Also triggers when organic traffic is flat despite consistent publishing." +category: seo-audit-suite +catalog_summary: "Missing topics, thin coverage, outdated content, decay diagnosis" +display_order: 4 +--- + +# SEO Content Gap Audit + +Find content gaps and decay using Ahrefs MCP data. Stack-agnostic. Produces a roadmap of create, update, merge, and prune actions across the existing content catalog and identified topic gaps. + +--- + +## When to use + +- Planning the next quarter or half of content investment +- Refreshing a stale or underperforming content catalog +- Building topical authority in a target space +- Identifying decaying pages before they tank traffic +- Audit prep before a major site redesign or migration +- Diagnosing why content investment is not driving organic growth + +## When NOT to use + +- Pure keyword research (use `seo-keyword`) +- Competitor keyword gap (use `seo-keyword-gap-audit`) +- Single-page optimization (use `seo-onpage`) +- Pure prune-and-redirect decisions (use `seo-content-audit`) +- New site planning with no existing content (use `content-strategy`) + +--- + +## Required inputs + +- Target property and content scope +- Competitor set (3-5 properties with comparable content depth) +- Target topics or pillars (if defined) +- Existing content inventory with URLs, primary topics, publish dates +- Performance data (organic clicks per page, ranked keywords per page) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: 4 categories of content opportunity + +Every content opportunity falls into one of four categories. Different categories need different actions. + +Content gap analysis is sharper with multiple data sources. Ahrefs surfaces keyword and topic gaps (the primary backend below). Similarweb surfaces traffic-driving page-level gaps (which of a competitor's pages earn meaningful traffic, not just rankings). Semrush surfaces SERP-feature gaps (where competitors win answer boxes, knowledge panels, People Also Ask placements). The three platforms often disagree on individual data points; that disagreement is itself a useful signal. + +### Category 1: Missing topics + +Topics with traffic potential where the property has no relevant page at all. Competitors often rank in the top 10. The fix: create new content. + +Pulled from: + +- Ahrefs Content Explorer (top performing content in target topics) +- Competitor top pages (Ahrefs Site Explorer) +- Keyword gap audit output (clustered into topics) + +### Category 2: Thin coverage + +Topics where the property has a page but it is too shallow, narrow, or single-keyword to compete with topical hubs. Competitor pages cover the topic across multiple subtopics. The fix: deepen the existing page or expand into a topic cluster. + +Pulled from: + +- Pages ranking on page 2-3 for target keywords +- Pages with low organic click share relative to ranked keyword volume +- Pages where competitors have longer or broader equivalents + +### Category 3: Outdated content + +Pages that ranked well historically but have lost ground due to staleness. Information is dated, examples are old, the SERP intent has shifted. The fix: refresh with current information and re-promote. + +Pulled from: + +- Pages with declining organic clicks over the last 6-12 months +- Pages with publish dates over 18 months old +- Pages with ranked keywords slipping in position + +### Category 4: Decaying content + +Pages that have lost traffic for reasons not obviously about staleness: SERP feature changes, competitor publishing, intent shifts, internal linking dilution. The fix: diagnose why, then refresh, merge, or redirect. + +Pulled from: + +- Pages with sharp recent traffic drops +- Pages where SERP composition has shifted (more video, more featured snippets, AI overviews) +- Pages that compete with newer pages on the same site (cannibalization) + +--- + +## Workflow + +1. Charter the audit. Scope (whole site or section), goal, time window for performance data. +2. Pull the inventory. Every URL, with publish date, primary topic, organic clicks, ranked keywords. +3. Pull competitor coverage. Top pages and content clusters from each competitor. +4. Classify each existing page. Healthy / thin / outdated / decaying / off-topic. +5. Identify missing topics. Cross-reference competitor top pages and keyword gap output. +6. Score each opportunity. See [`references/content-decision-matrix.md`](references/content-decision-matrix.md). +7. Cluster. Group related missing topics into pillar concepts. +8. Decide actions. Create / update / merge / redirect / prune for each opportunity. +9. Sequence the roadmap. Quarter by quarter, with effort estimates and traffic forecasts. +10. Hand off. Output feeds `content-strategy`, `content-and-copy`, and `seo-onpage`. + +--- + +## The action decision matrix + +For each piece of existing content or proposed new content, decide one action. + +\| Signal \| Action \| +\| --- \| --- \| +\| Strong page, healthy traffic, current information \| Keep. Defend with internal linking and refresh on schedule. \| +\| Page exists, ranking on page 2-3, content is thin vs SERP \| Update. Deepen, restructure, broaden. \| +\| Page exists, traffic declining, content is dated \| Refresh. Update facts, examples, year references, screenshots. \| +\| Page exists, low or zero traffic, low ranking, no improvement path \| Prune or merge. Redirect to a stronger relative if one exists. \| +\| Multiple pages on overlapping topics \| Merge into one canonical page. Redirect the others. \| +\| Topic missing entirely, competitor coverage strong \| Create new page or pillar. \| +\| Topic missing, but competitors do not rank well either \| Validate intent before investing. Could be an opportunity or could be a dead end. \| +\| Page is off-topic for the property \| Redirect to most relevant page or remove from sitemap. \| + +--- + +## Failure patterns + +- All-create, no-update bias. Teams default to creating new content. Updates and merges often outperform new pieces by a wide margin and at lower cost. +- Treating publish date as currency. A 5-year-old page can outrank a 1-month-old page if it is better. Stop deleting old content reflexively. +- Cannibalization blind spots. Two pages on overlapping topics dilute each other. Audit for it explicitly. +- No effort estimates. A roadmap without effort sizes cannot be sequenced realistically. +- No traffic forecast. A roadmap without forecasted impact loses funding fights. Forecast even with wide confidence bands. +- Refreshing without re-promotion. A refreshed page needs a re-crawl signal: update sitemap, internal links, distribution. +- Ignoring intent shift. Some keywords have shifted from informational to transactional or to AI-answer-dominated. Recognize when the SERP is no longer addressable by the existing format. +- Confusing decay with seasonality. A 30% click drop in summer for a back-to-school topic is not decay. Compare year-over-year, not month-over-month. +- Auditing in isolation from the keyword gap. The two audits feed each other. Run them adjacent. + +--- + +## Output format + +A content gap audit document with: + +1. Executive summary. Top 3 themes, content health verdict, recommended quarterly investment split. +2. Content inventory snapshot. Counts by health classification. +3. Missing topics. Prioritized list with cluster mapping and traffic forecast. +4. Thin coverage. Pages to deepen, with recommendation for each. +5. Outdated content. Pages to refresh, with refresh scope. +6. Decaying content. Pages to diagnose and act on, with hypothesis for each. +7. Cannibalization findings. Page pairs to merge. +8. Action roadmap. Quarter by quarter, with effort and forecast. +9. Methodology. Data sources, classification criteria, caveats. + +Length: 8-15 pages plus an attached inventory spreadsheet. + +--- + +## Reference files + +- [`references/content-decision-matrix.md`](references/content-decision-matrix.md) - Detailed decision tree for classifying pages and choosing the create/update/merge/prune action, with worked examples. diff --git a/skills/seo-content-gap-audit/references/content-decision-matrix.md b/skills/seo-content-gap-audit/references/content-decision-matrix.md new file mode 100644 index 0000000..65f3685 --- /dev/null +++ b/skills/seo-content-gap-audit/references/content-decision-matrix.md @@ -0,0 +1,177 @@ +# Content decision matrix + +A decision tree for classifying every page in a content audit and picking the right action. Use it after pulling the inventory and performance data. + +--- + +## The 6 actions + +Every page gets exactly one of these: + +1. Keep. Page is healthy. Defend it. +2. Refresh. Update facts, examples, screenshots, year references. +3. Update. Deeper rework. New sections, restructured argument, expanded scope. +4. Merge. Combine with another page. Redirect the loser. +5. Redirect. Page has no path forward. Redirect to closest relative. +6. Prune. Remove from sitemap, return 410 or noindex. + +--- + +## The decision tree + +Follow the tree top to bottom. The first match wins. + +### Step 1: Is the page on-topic for the property? + +If no: redirect to the most relevant page. If no relative exists, prune. + +### Step 2: Is the page duplicative of another page on the same site? + +If yes: merge. Pick the stronger of the two as the canonical, redirect the other. See "Merge selection criteria" below. + +### Step 3: Has traffic declined sharply over the last 6-12 months? + +Define "sharp": a drop of 40% or more, sustained for 3+ months, not explainable by seasonality. + +If yes: investigate. Likely actions are refresh, update, or redirect depending on root cause. See "Decay diagnosis" below. + +### Step 4: Is the page over 18 months old with stale specifics? + +Stale specifics include: outdated year references, old screenshots, dated examples, products no longer available, statistics from old reports. + +If yes: refresh. Keep the structure. Replace the stale parts. + +### Step 5: Is the page ranking on page 2-3 for relevant terms? + +Page 2-3 means positions 11-30 for keywords with meaningful volume. + +If yes: update. The page has potential. It needs more depth, better structure, or broader scope to break into top 10. + +### Step 6: Is the page getting steady traffic but the content is shallow vs the SERP? + +Shallow means: shorter than the top 3 SERP results, missing subtopics they cover, or single-keyword focused while they cover a topic cluster. + +If yes: update. The page is winning despite being thin. Make it stronger before competitors push it down. + +### Step 7: Is the page getting low traffic with no growth trend? + +Low traffic: under 50 organic clicks per month for an established page (over 12 months old). + +If yes and no clear path to improvement: prune or redirect. Do not waste effort trying to rescue every page. + +### Step 8: Default + +If none of the above, the page is healthy. Keep. Schedule a routine refresh on a 12-18 month cadence. + +--- + +## Merge selection criteria + +When two pages cover overlapping topics, decide which becomes canonical. + +Pick the page with: + +1. Stronger backlink profile (Ahrefs Site Explorer) +2. More ranked keywords with meaningful volume +3. Better URL (cleaner, more descriptive, shorter) +4. Higher current position for the head term + +If the pages have different strengths, often the right move is to keep the better URL and migrate the better content into it. + +Always: + +- 301 redirect the loser to the winner +- Update internal links to point at the canonical +- Notify Search Console (resubmit sitemap) +- Wait 4-8 weeks before evaluating impact + +--- + +## Decay diagnosis + +Sharp traffic decline can have multiple root causes. Diagnose before deciding action. + +### Possible causes and their signatures + +\| Cause \| Signature \| Action \| +\| --- \| --- \| --- \| +\| SERP feature steal (featured snippet, PAA, AI overview) \| Position stable, click-through rate fell \| Refresh + restructure for snippet capture, or accept the new normal \| +\| Competitor published better content \| Position fell, SERP composition includes new domain \| Update to match or exceed competitor depth \| +\| Intent shifted (informational to transactional, etc.) \| SERP composition is now a different content type (e.g., now product pages dominate) \| Re-evaluate format, or pivot URL purpose \| +\| Internal cannibalization \| A newer page on same site now ranks for the same term \| Merge or differentiate \| +\| Site-wide ranking decline \| Multiple pages lost position simultaneously \| Likely site-wide issue, see `seo-traffic-diagnosis` \| +\| Content went stale \| Year references and stats are outdated \| Refresh \| +\| Algorithm update \| Decline correlates with a known update date \| Audit content quality and E-E-A-T \| +\| Lost backlinks \| Referring domain count fell \| See `seo-backlink-audit` for reclamation \| +\| Migration aftermath \| Decline started immediately after a migration \| Audit redirect chains and structural changes \| + +Always confirm the cause before acting. Wrong diagnosis equals wrong fix. + +--- + +## Worked examples + +### Example 1: keep + +Page: pillar guide on a core topic, 2 years old, top 3 ranking, steady traffic, 800+ clicks/month, content is current. + +Decision: keep. Schedule routine refresh in 6 months. + +### Example 2: refresh + +Page: how-to guide, 3 years old, position 6-8, traffic flat for 12 months, screenshots show old UI, references "in 2023". + +Decision: refresh. Update screenshots, year references, and any tool versions. Re-promote internally. + +### Example 3: update + +Page: 1,200 word article on a category topic, position 14 for the head term, low CTR, top 3 results are 3,000+ word topic hubs covering 8-10 subtopics. + +Decision: update. Expand to cover the missing subtopics. Restructure for skim. Add internal links from related pages. + +### Example 4: merge + +Pages: two articles on closely overlapping topics, both ranking somewhere between positions 8-15 for related terms, splitting traffic. + +Decision: merge. Pick the page with stronger backlinks as canonical. Migrate the unique content from the other. 301 redirect the loser. Update internal links. + +### Example 5: redirect + +Page: outdated tutorial for a tool no longer in use, no organic traffic, no ranked keywords, off-topic for current site direction. + +Decision: redirect to closest relevant page. If none, prune (410 or noindex). + +### Example 6: prune + +Page: thin tag archive with under 5 items, no organic traffic, no internal links, indexed only because of CMS defaults. + +Decision: prune. Noindex via meta tag or remove from sitemap. Add to robots disallow if appropriate. + +--- + +## Effort and traffic forecast cheat sheet + +For sequencing the roadmap, use these rough estimates: + +\| Action \| Typical effort per page \| Traffic impact timeline \| +\| --- \| --- \| --- \| +\| Keep \| 0 (or routine refresh in 6-12 months) \| None \| +\| Refresh \| 2-4 hours \| 30-60 days to see ranking impact \| +\| Update \| 6-16 hours \| 60-120 days \| +\| Merge \| 4-8 hours per pair \| 60-120 days \| +\| Redirect \| 30 min \| Immediate (no ranking impact) \| +\| Prune \| 30 min \| Immediate (positive if it removes thin content drag) \| +\| Create new \| 12-30 hours \| 90-180 days for new pages to gain traction \| + +Updates and merges typically deliver more traffic per hour invested than new content. Most teams underweight them. + +--- + +## Common mistakes + +- Pruning aggressively without verifying low value. Some low-traffic pages have backlinks, internal link equity, or seasonal traffic. Audit these before pruning. +- Refreshing pages that need updates. A surface refresh on a thin page does not move rankings. Match the action to the root cause. +- Updating pages that need merges. Two competing pages on the same topic will keep splitting traffic. Merge first, then optimize. +- Skipping internal link audit. Updates and refreshes underperform without renewed internal links pointing to them. +- Optimizing pages with intent mismatch. If the SERP is now product pages and the page is an article, no amount of editing fixes that. Either pivot the page type or redirect. +- Forgetting to notify Search Console. Resubmit sitemap after major content moves to accelerate recrawl. diff --git a/skills/seo-keyword-gap-audit/SKILL.md b/skills/seo-keyword-gap-audit/SKILL.md new file mode 100644 index 0000000..ac38d93 --- /dev/null +++ b/skills/seo-keyword-gap-audit/SKILL.md @@ -0,0 +1,161 @@ +--- +name: seo-keyword-gap-audit +description: "Find keywords competitors rank for that the target property does not, and prioritize them by opportunity. Uses Ahrefs MCP for keyword and competitor data. Use this skill when planning content investment, identifying quick wins, building a content calendar against a competitor set, or scoping a market entry. Triggers on keyword gap, content gap, competitor keywords, opportunity keywords, what should we target, where are competitors winning, keyword opportunity. Also triggers when planning content for a new market or after losing organic share to a specific competitor." +category: seo-audit-suite +catalog_summary: "Competitor keyword gaps with opportunity scoring and clustering" +display_order: 3 +--- + +# SEO Keyword Gap Audit + +Find keyword opportunities by comparing the target property's organic footprint against a competitor set, using Ahrefs MCP data. Stack-agnostic. Produces a prioritized list of keywords to target with new or improved content. + +--- + +## When to use + +- Planning content investment for the next quarter +- Identifying quick-win keywords for fast organic gains +- Scoping market entry into a new vertical +- Refreshing a stale content strategy +- Diagnosing why a competitor is gaining organic share +- Pre-acquisition due diligence on growth ceiling + +## When NOT to use + +- Pure keyword discovery without a competitor frame (use `seo-keyword`) +- Single-page optimization (use `seo-onpage`) +- Content audit on existing pages (use `seo-content-audit`) +- Topic and pillar planning (use `content-strategy`) + +--- + +## Required inputs + +- Target property +- Competitor set (3-5 properties with overlapping intent and audience) +- Target market and language +- Business priorities (which segments matter most) +- Existing content inventory (URLs and primary topics) +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: the gap matrix + +A keyword can fall into one of four cells based on whether the target ranks and whether competitors rank. + +\| \| Target ranks \| Target does not rank \| +\| --- \| --- \| --- \| +\| Competitors rank \| Shared territory (defend and grow) \| Pure gap (the opportunity) \| +\| Competitors do not rank \| Unique territory (asset to protect) \| Untouched (validate before investing) \| + +The audit focuses primarily on the "pure gap" cell. The other cells get secondary treatment. + +### Pure gap (top focus) + +Keywords where one or more competitors rank in the top 10 and the target does not rank at all or ranks past page 3. These are the primary opportunities. + +### Shared territory + +Keywords where both target and competitors rank. Useful for defending position and finding pages to push from page 2 to page 1. + +### Unique territory + +Keywords where the target ranks and no competitor does. These are differentiators. Audit to confirm they are actually valuable (not just irrelevant terms). + +### Untouched + +Keywords no one in the set ranks for. Could be opportunity or could be irrelevant. Validate intent before investing. + +--- + +## Opportunity scoring + +Not every gap keyword is worth pursuing. Score each candidate. + +### Scoring dimensions + +\| Dimension \| What it measures \| Weight \| +\| --- \| --- \| --- \| +\| Search volume \| Estimated monthly searches in target market \| 20% \| +\| Business relevance \| How close to a money topic for the target \| 30% \| +\| Difficulty \| How hard to rank (Ahrefs KD or proxy) \| 15% \| +\| Intent match \| Whether target can satisfy the dominant intent \| 20% \| +\| Position potential \| Realistic top 3 reach within 6 months \| 15% \| + +Weights adjust based on goal. For quick wins, weight position potential and difficulty higher. For strategic territory, weight business relevance and volume higher. + +### Opportunity score formula + +``` +score = (volume_normalized * 0.2) + + (relevance_score * 0.3) + + (difficulty_inverted * 0.15) + + (intent_match * 0.2) + + (position_potential * 0.15) +``` + +Where each input is normalized to 0-100. The result is a 0-100 score. + +### Banding for action + +\| Score \| Action \| +\| --- \| --- \| +\| 80-100 \| Top priority. Plan content this quarter. \| +\| 60-79 \| Strong priority. Plan within 6 months. \| +\| 40-59 \| Watch list. Revisit if competitive landscape shifts. \| +\| Below 40 \| Park or drop. \| + +--- + +## Workflow + +1. Define the competitor set. 3-5 properties. Confirm they share intent and audience. +2. Pull keyword data. For each property: organic keywords, top pages, traffic estimates. +3. Build the gap matrix. Label each keyword with which property ranks where. +4. Filter to the pure gap cell. Strip out the other cells for now. +5. Validate intent. For each keyword, confirm the SERP intent matches what the target can produce. +6. Score by opportunity. Use the formula. See [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md). +7. Cluster. Group related keywords into topics. One topic, one piece of content. +8. Map to existing content. Some gap keywords are addressable by updating an existing page rather than creating new. +9. Sequence. Build the prioritized list with action (create / update / merge / new pillar). +10. Hand off. Output feeds `content-strategy` and `seo-onpage`. + +--- + +## Failure patterns + +- Wrong competitor set. Choosing competitors by brand recognition rather than SERP overlap produces gap lists that are not actually competitive. Pick competitors that fight you in the SERPs. +- Volume worship. High-volume gap keywords are often unrealistic. A 50-volume keyword you can rank for beats a 5,000-volume keyword you cannot. +- Ignoring intent. A gap keyword where the SERP is dominated by tools or marketplaces is not addressable by an article. Match content type to intent. +- Skipping clustering. Targeting individual keywords instead of topics produces thin content that loses to topical hubs. +- Over-relying on Ahrefs KD. Difficulty scores are heuristics. Look at the actual SERP. If it is dominated by Forbes and Wikipedia, KD is misleadingly low. +- No business filter. A high-volume gap with zero buyer intent is a vanity opportunity. Filter for relevance. +- One-shot audits. Gap closes and reopens as competitors publish. Rerun on a cadence. +- Forgetting unique territory. Defending what you uniquely rank for can be more valuable than chasing gaps. Audit both directions. +- Single-language audits in multi-market sites. Run separate gap audits per market. Patterns differ. + +--- + +## Output format + +A keyword gap audit document with: + +1. Executive summary. Top 3 themes and top 10 priority keywords. +2. Competitor set. Who, why selected, SERP overlap evidence. +3. The gap matrix. Counts and patterns across the four cells. +4. Pure gap analysis. The opportunity list, scored and banded. +5. Topic clusters. Groups of related keywords mapped to content concepts. +6. Action map. Create / update / merge decisions per cluster. +7. Quick wins. Top 5-10 highest-confidence opportunities. +8. Strategic plays. High-impact, longer-horizon investments. +9. Methodology. Data sources, scoring weights, caveats. + +Length: 6-15 pages plus an attached opportunity spreadsheet. + +--- + +## Reference files + +- [`references/opportunity-scoring-rubric.md`](references/opportunity-scoring-rubric.md) - Scoring rubric with normalization rules, formula, and worked examples. diff --git a/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md b/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md new file mode 100644 index 0000000..3b9af2a --- /dev/null +++ b/skills/seo-keyword-gap-audit/references/opportunity-scoring-rubric.md @@ -0,0 +1,233 @@ +# Opportunity scoring rubric + +A scoring framework for ranking keyword gap opportunities. The score combines five normalized inputs into a single 0-100 ranking. Use it to convert a long gap list into a prioritized roadmap. + +--- + +## The 5 inputs + +### 1. Search volume (weight: 20%) + +Monthly search volume in the target market. + +Normalize on a log scale because volume is heavily skewed: + +\| Volume range \| Normalized score (0-100) \| +\| --- \| --- \| +\| 0-100 \| 20 \| +\| 100-500 \| 40 \| +\| 500-2,000 \| 60 \| +\| 2,000-10,000 \| 80 \| +\| 10,000+ \| 100 \| + +Use Ahrefs Keywords Explorer for the volume figure. Confirm the country setting matches the target market. + +### 2. Business relevance (weight: 30%) + +How close is this keyword to a revenue or conversion topic? + +Score on intent stage: + +\| Stage \| Normalized score \| Examples \| +\| --- \| --- \| --- \| +\| Direct purchase intent \| 100 \| "buy [product] online", "[product] price" \| +\| Comparison and evaluation \| 80 \| "best [product] for [use case]", "[product A] vs [product B]" \| +\| Problem-aware research \| 60 \| "how to [solve problem]", "what is [problem]" \| +\| Top-of-funnel education \| 40 \| "[broad topic] guide", "[topic] meaning" \| +\| Tangentially related \| 20 \| Adjacent topic with weak conversion path \| +\| Off-topic \| 0 \| Drop \| + +Adjust based on business model. SaaS values evaluation-stage highly. Ecommerce values direct purchase highly. Media values volume across all stages. + +### 3. Difficulty (weight: 15%) + +How hard is it to rank in the top 10? Use Ahrefs Keyword Difficulty as the starting input, but verify against the actual SERP. + +Invert the score. Lower difficulty equals higher opportunity: + +\| KD score \| Inverted normalized score \| +\| --- \| --- \| +\| 0-10 \| 100 \| +\| 11-30 \| 80 \| +\| 31-50 \| 60 \| +\| 51-70 \| 40 \| +\| 71-100 \| 20 \| + +Override KD if the SERP visibly contradicts it. A KD-15 SERP dominated by Forbes, Reddit, and Wikipedia is harder than a KD-40 SERP of niche bloggers. + +### 4. Intent match (weight: 20%) + +Can the target produce content that matches the dominant SERP intent? + +Look at the top 10 results and classify what they are: + +\| SERP type \| Match score for an article \| Match score for a tool \| Match score for a product page \| +\| --- \| --- \| --- \| --- \| +\| Articles dominate \| 100 \| 20 \| 0 \| +\| Tools or calculators dominate \| 20 \| 100 \| 0 \| +\| Product pages dominate \| 0 \| 0 \| 100 \| +\| Marketplaces dominate \| 20 \| 40 \| 60 \| +\| Video dominates \| 40 \| 60 \| 0 \| +\| Mixed (no dominant type) \| 60 \| 60 \| 60 \| + +If the target cannot produce the matching content type, drop the keyword regardless of other scores. + +### 5. Position potential (weight: 15%) + +Realistic top 3 reach within 6 months given current site authority. + +Estimate based on: + +- Current ranking position (if any) +- Domain Rating relative to the SERP +- Content depth required +- Topical authority in this space + +\| Current position \| DR vs SERP avg \| Position potential score \| +\| --- \| --- \| --- \| +\| Top 3 already \| Any \| Skip (defend, do not gap-target) \| +\| Position 4-10 \| At or above \| 100 \| +\| Position 11-20 \| At or above \| 80 \| +\| Position 11-20 \| Below \| 60 \| +\| Position 21+ \| At or above \| 50 \| +\| Not ranking \| Above SERP avg \| 60 \| +\| Not ranking \| At SERP avg \| 40 \| +\| Not ranking \| Below SERP avg \| 20 \| + +--- + +## The formula + +``` +score = (volume_normalized * 0.20) + + (relevance_score * 0.30) + + (difficulty_inverted * 0.15) + + (intent_match * 0.20) + + (position_potential * 0.15) +``` + +Score ranges 0-100. Apply the action banding: + +\| Score \| Action \| Typical timeline \| +\| --- \| --- \| --- \| +\| 80-100 \| Top priority. Plan content this quarter. \| 0-90 days \| +\| 60-79 \| Strong priority. Plan within 6 months. \| 90-180 days \| +\| 40-59 \| Watch list. Revisit on landscape shift. \| Quarterly review \| +\| Below 40 \| Park or drop. \| Annual review \| + +--- + +## Worked example 1: high-priority gap + +Keyword: "[mid-funnel evaluation phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 1,800/month \| 60 \| +\| Relevance \| Comparison stage \| 80 \| +\| Difficulty \| KD 25, SERP confirms accessible \| 80 \| +\| Intent \| Articles dominate, target produces articles \| 100 \| +\| Position \| Currently position 14, DR above SERP avg \| 80 \| + +``` +score = (60 * 0.20) + (80 * 0.30) + (80 * 0.15) + (100 * 0.20) + (80 * 0.15) + = 12 + 24 + 12 + 20 + 12 + = 80 +``` + +Band: top priority. Plan this quarter. + +--- + +## Worked example 2: borderline opportunity + +Keyword: "[broader top-of-funnel phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 9,500/month \| 80 \| +\| Relevance \| Top-of-funnel education \| 40 \| +\| Difficulty \| KD 55 with Forbes in top 3 \| 30 (override) \| +\| Intent \| Mixed SERP, target produces articles \| 60 \| +\| Position \| Not ranking, DR below SERP avg \| 20 \| + +``` +score = (80 * 0.20) + (40 * 0.30) + (30 * 0.15) + (60 * 0.20) + (20 * 0.15) + = 16 + 12 + 4.5 + 12 + 3 + = 47.5 +``` + +Band: watch list. Revisit if domain authority grows or if priority shifts. + +--- + +## Worked example 3: drop + +Keyword: "[high-volume but off-topic phrase]" + +\| Input \| Raw \| Normalized \| +\| --- \| --- \| --- \| +\| Volume \| 22,000/month \| 100 \| +\| Relevance \| Tangentially related \| 20 \| +\| Difficulty \| KD 65 \| 30 \| +\| Intent \| Marketplaces dominate, target produces articles \| 20 \| +\| Position \| Not ranking, DR well below SERP avg \| 20 \| + +``` +score = (100 * 0.20) + (20 * 0.30) + (30 * 0.15) + (20 * 0.20) + (20 * 0.15) + = 20 + 6 + 4.5 + 4 + 3 + = 37.5 +``` + +Band: drop. High volume is not enough. + +--- + +## Adjusting weights for goal + +Default weights work for general opportunity audits. For specific goals: + +### Quick wins focus + +- Volume: 15% +- Relevance: 25% +- Difficulty: 25% +- Intent: 20% +- Position: 15% + +### Strategic territory focus + +- Volume: 25% +- Relevance: 35% +- Difficulty: 10% +- Intent: 20% +- Position: 10% + +### Defensive (protect rankings) + +Reuse the formula but apply to "shared territory" cell. Position potential weights higher. + +--- + +## Clustering after scoring + +After scoring individual keywords, cluster them. Targeting clusters beats targeting one-off keywords. + +Cluster rules: + +- Same dominant intent +- Overlapping SERP results (top 5 results match for 60%+ of the cluster) +- Naturally addressable by one piece of content + +Apply the highest score in the cluster as the cluster's score for prioritization. + +--- + +## Common mistakes when scoring + +- Trusting volume estimates blindly. Ahrefs estimates have wide confidence intervals at low volumes. A "50/month" keyword may be 5 or 200. +- Treating KD as ground truth. Always look at the SERP. KD is a heuristic, not a verdict. +- Scoring before intent matching. A keyword with mismatched intent scores high on paper but cannot rank for the target. Filter intent first. +- One-time scoring. Re-score quarterly. SERPs evolve. Competitor moves change difficulty. +- No business filter. A high score on a topic with zero conversion path is not an opportunity. Add a sanity check on relevance. +- Optimizing for the formula, not the goal. The score informs the call. The goal makes the call. diff --git a/skills/seo-keyword/SKILL.md b/skills/seo-keyword/SKILL.md new file mode 100644 index 0000000..f635e1f --- /dev/null +++ b/skills/seo-keyword/SKILL.md @@ -0,0 +1,163 @@ +--- +name: seo-keyword +description: "Run keyword research, classify by search intent, cluster into topical groups, and prioritize for content production. Use this skill whenever the user asks to do keyword research, find target keywords, identify ranking opportunities, classify search intent, build a topical map, or plan a content strategy around what people search for. Triggers on keyword research, keyword strategy, search intent, keyword clustering, topic clusters, keyword difficulty, search volume, ranking opportunity, content gap, what should I write about, target keyword, primary keyword, secondary keyword, long-tail. Also triggers when planning a content calendar or new site without keywords yet defined." +category: seo-foundation +catalog_summary: "Discovery, intent classification, clustering, prioritization" +display_order: 3 +--- + +# Keyword Research + +Find the queries worth ranking for, classify them by intent, cluster them into topics, and prioritize what to produce. Stack-agnostic. Tool-agnostic (works with any keyword tool). + +--- + +## When to use + +- Starting a new site or content section +- Planning a content calendar +- Looking for ranking opportunities on an existing site +- Understanding search intent before writing +- Building topic clusters for internal linking +- Identifying content gaps vs competitors + +## When NOT to use + +- Optimizing a single page where the target query is already known (use `seo-onpage`) +- Comparing your site to a competitor across many dimensions (use `seo-competitor`) +- Auditing existing content for performance (use `seo-content-audit`) + +--- + +## Required inputs + +- The site or topic area +- The target audience and what they need +- A keyword tool (Ahrefs, Semrush, Moz, Google Keyword Planner, or similar) OR access to search console for an existing site +- Optional: 3 to 5 known competitors to seed the research + +If no tool is available, the skill still works using SERP inspection and search console data alone, but the volume estimates will be rough. + +--- + +## The framework: 4 stages + +### Stage 1: Discover + +Cast a wide net. Sources: + +- Seed terms from the brief or the user's vocabulary +- Competitor keywords (any keyword tool will export these) +- Search console queries for an existing site (find the page-1 and page-2 queries) +- Related searches and "People also ask" in actual SERPs +- Customer language (support tickets, sales calls, reviews) +- Forum and community language (Reddit, niche forums, Stack Overflow) + +Goal: 200 to 500 candidate keywords for a typical content sprint. More if planning a year of content. + +### Stage 2: Classify by intent + +Every keyword maps to one of four intents. Get this right or the rest is noise. + +\| Intent \| Signal \| Page type that wins \| +\|---\|---\|---\| +\| Informational \| "how to," "what is," "why," "best way to" \| Article, guide, tutorial \| +\| Navigational \| brand or product name + modifier \| Brand homepage, product page \| +\| Commercial \| "best," "review," "vs," "comparison," "alternatives" \| Listicle, comparison, review \| +\| Transactional \| "buy," "price," "deal," "near me," "for sale" \| Product page, category page \| + +A keyword tool's volume tells you the demand. The SERP tells you the intent. When in doubt, look at what's actually ranking. If page 1 is articles, the query is informational. If page 1 is product pages, it's transactional. + +Hybrid intents exist. "Best running shoes" is commercial-investigational. "Best running shoes under $100" is the same intent narrowed by a budget filter. Treat hybrids as their dominant intent and note the modifier. + +### Stage 3: Cluster + +Group keywords that should target the same page (or topic cluster). + +Two clustering approaches: + +Approach A: SERP overlap. If two keywords share at least 3 of the top 10 results, they target the same page. This is mechanical and reliable. + +Approach B: Topical relevance. Group keywords by the underlying topic, not just word overlap. "How to start a podcast" and "podcast equipment for beginners" are the same topic, different facets. + +Use both. A typical cluster has: +- 1 primary keyword (highest volume, broadest intent) +- 5 to 15 secondary keywords (variations and long-tails) +- 1 page that targets them all + +### Stage 4: Prioritize + +For each cluster, score on three dimensions: + +Opportunity (1 to 5): +- Volume (raw search demand) +- Click potential (some queries answer themselves in the SERP, lowering CTR) +- Conversion potential (does this query attract buyers or browsers?) + +Difficulty (1 to 5): +- Domain authority of top results +- Backlink count of top results +- Content depth and freshness of top results +- Whether the SERP has features (featured snippets, AI overview, video carousel) that compete with organic + +Strategic fit (1 to 5): +- Does it serve our audience? +- Does it support our positioning? +- Does it link to commercial pages naturally? + +Priority score = Opportunity + Strategic fit - Difficulty. + +Rank the clusters. Top 20 percent get produced first. + +--- + +## Workflow + +1. Define the scope. What site, what topic area, what audience. +2. Run discovery. Pull seeds, competitor exports, search console data, SERP inspections. Aim for 200 to 500 candidates. +3. Deduplicate and clean. Remove obvious junk, brand misspellings, irrelevant terms. +4. Classify by intent. Mark each keyword. +5. Cluster. Group into topical clusters. Aim for 20 to 50 clusters. +6. Score each cluster on opportunity, difficulty, and strategic fit. +7. Prioritize. Rank by composite score. Identify the top 10 to 20 clusters to produce first. +8. Output. Use the template in [`references/keyword-research-template.md`](references/keyword-research-template.md). + +--- + +## Failure patterns + +- Chasing volume without intent. A 10,000-volume informational keyword does not drive purchases. Match query to commercial outcome. +- Targeting impossibly competitive keywords. New sites cannot rank for "credit cards." Find the underserved long-tail variant. +- Ignoring search console. Existing sites already rank for queries they did not target. These are the easiest wins. +- Treating clusters as one-keyword-per-page. A page can target 10 to 30 related keywords. One-keyword-per-page leads to thin, cannibalized content. +- Ignoring SERP features. A query with a featured snippet, AI overview, and a video carousel above the organic results may not be worth pursuing. +- Static keyword research. Search demand shifts. Refresh the research at least annually for evergreen sites, quarterly for fast-moving topics. + +--- + +## Output format + +Default output: a spreadsheet (CSV or sheet) with one row per keyword and one row per cluster, plus a markdown summary with the top 10 to 20 clusters detailed. + +Recommended columns for the keyword sheet: + +\| Column \| Source \| +\|---\|---\| +\| Keyword \| Discovery \| +\| Volume \| Tool \| +\| Difficulty \| Tool \| +\| Intent \| Manual classification \| +\| SERP features \| Manual or tool \| +\| Cluster \| Stage 3 \| +\| Cluster role (primary/secondary) \| Stage 3 \| +\| Opportunity score \| Stage 4 \| +\| Strategic fit \| Stage 4 \| +\| Priority \| Composite \| +\| Notes \| Free text \| + +--- + +## Reference files + +- [`references/keyword-research-template.md`](references/keyword-research-template.md) - Spreadsheet column definitions and a markdown summary template. +- [`references/intent-classification-guide.md`](references/intent-classification-guide.md) - Detailed examples of each of the four intent categories. diff --git a/skills/seo-keyword/references/intent-classification-guide.md b/skills/seo-keyword/references/intent-classification-guide.md new file mode 100644 index 0000000..0b145f2 --- /dev/null +++ b/skills/seo-keyword/references/intent-classification-guide.md @@ -0,0 +1,246 @@ +# Intent Classification Guide + +Detailed examples of each of the four search intent categories. Use this to tag every keyword in research with its intent before deciding what content (if any) to build. + +Intent classification is the most important and most-skipped step in keyword research. Tools surface volume and difficulty. They do not tell you whether the searcher wants to learn, compare, navigate, or buy. Without intent, you produce content that ranks for words but converts nothing. + +--- + +## The four intents + +\| Intent \| The searcher wants to \| Right content \| Right CTA \| +\|---\|---\|---\|---\| +\| Informational \| Learn something \| Article, guide, video \| Subscribe, related content \| +\| Navigational \| Reach a specific destination \| Branded page, login, location \| Direct link \| +\| Commercial investigation \| Compare options before buying \| Comparison, review, list, buyer's guide \| Demo, trial, deeper guide \| +\| Transactional \| Take an action (buy, sign up, download) \| Product page, pricing, signup, checkout \| Buy / sign up / download \| + +The same root word can fall into multiple intents depending on modifier. "Crm" alone is ambiguous. "What is a crm" is informational. "Salesforce login" is navigational. "Best crm for startups" is commercial investigation. "Buy salesforce" is transactional. + +--- + +## Informational intent + +The searcher wants to understand, learn, or solve a problem. + +### Signals + +- Question words: what, why, how, when, where, who +- "Guide," "tutorial," "examples," "definition," "explained" +- Topic-only queries with no commercial modifier ("dmarc records," "css grid") +- "How to" + a task + +### Examples + +\| Query \| Intent depth \| Notes \| +\|---\|---\|---\| +\| "what is a service blueprint" \| Top-of-funnel learning \| Definition piece \| +\| "how to write a creative brief" \| How-to \| Step-by-step guide \| +\| "service blueprint examples" \| Mid-funnel learning \| Examples gallery \| +\| "service blueprint vs customer journey map" \| Comparison-flavored learning \| Overlaps with commercial; treat as info if no products in result \| +\| "why is css grid useful" \| Conceptual \| Explainer with code examples \| +\| "history of bauhaus design" \| Background \| Editorial / long-form \| +\| "node js error eaddrinuse" \| Troubleshooting \| Specific fix article \| + +### What to publish + +Long-form articles, guides, glossary entries, video tutorials, original research. Content that earns subscribers, social shares, and backlinks. Not where conversion happens; where awareness builds. + +### CTA approach + +Soft. "Subscribe to the newsletter," "read the related guide," "join the community." A pricing CTA at the end of an informational piece reads as a bait-and-switch. + +### Failure mode + +Producing informational content with hard sales CTAs because someone metric'd it as "low conversion." Informational content's job is awareness and authority. Measure it on assists, brand recall, and downstream conversions, not last-click. + +--- + +## Navigational intent + +The searcher knows what they want and is using search to get there. + +### Signals + +- Brand names ("HubSpot," "Notion") +- Brand + modifier ("HubSpot login," "Notion pricing," "Salesforce careers") +- Product names ("MacBook Pro M4," "Tesla Model Y") +- Domain-style queries ("github.com," "facebook") + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "linear" \| Linear's homepage \| +\| "linear login" \| Linear's login page \| +\| "salesforce careers" \| Salesforce's careers page \| +\| "amazon prime" \| Amazon Prime's page \| +\| "github status" \| GitHub's status page \| + +### What to publish + +For your own brand: own the navigational queries. The homepage, login page, status page, careers page, contact page, pricing page should rank #1 for branded variants. + +For other brands' navigational queries: do not pursue. You will not rank, you should not try, and even if you did, the user does not want you. + +The exception: comparison queries ("Linear alternatives," "vs Linear") are not navigational; they are commercial investigation. See below. + +### CTA approach + +Whatever the destination expects. Login page → login form. Pricing page → buy or trial. Careers page → application. + +### Failure mode + +Treating "alternatives to" queries as navigational. They are not. They are commercial investigation, and a comparison page is the right format. + +--- + +## Commercial investigation intent + +The searcher is in the buying process but not ready to buy. They are comparing, reading reviews, building a shortlist. + +### Signals + +- "Best [category]" ("best crm for small business") +- "Top [category]" ("top hosting providers") +- "[Category] comparison" ("crm comparison") +- "[Brand] vs [brand]" ("notion vs obsidian") +- "[Brand] alternatives" ("alternatives to mailchimp") +- "[Brand] review" ("notion review") +- "[Category] for [audience]" ("crm for startups") +- "Cheap / affordable / free [category]" +- "Buyer's guide for [category]" + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "best email marketing tool" \| A ranked list of options \| +\| "mailchimp vs convertkit" \| A direct comparison \| +\| "alternatives to mailchimp" \| A shortlist of competitors with pros and cons \| +\| "convertkit review" \| Honest assessment from a third party (or the brand's own page if positioning) \| +\| "crm for solo consultants" \| Curated shortlist for a niche \| +\| "free project management software" \| Filtered list with feature notes \| + +### What to publish + +- For your category (high traffic, broad): "best of" lists, ranked comparisons, buyer's guides. Honest about tradeoffs. Include yourself if relevant; do not lie about ranking. +- For your brand vs others: comparison pages on your own domain ("[YourBrand] vs [Competitor]"). These are the highest-converting content type after pricing pages. +- For your category by use case: segment-specific landing pages ("CRM for solo consultants," "CRM for series-A startups"). Use case + CTA. + +### CTA approach + +Stronger than informational, lighter than transactional. "Try [product] free," "see how it compares," "book a demo," "download the buyer's guide." Multiple CTAs are OK because the visitor's progress is uncertain. + +### Failure mode + +Writing a "best of" list that is transparently a sales pitch for your product. Readers and Google can both spot this. Honest comparison pages, even when they include you, perform far better than disguised brochures. + +--- + +## Transactional intent + +The searcher wants to act now. Buy, sign up, download, contact, get a quote. + +### Signals + +- "Buy," "purchase," "order" +- "Sign up," "create account" +- "Download" +- "Get a quote," "request a demo," "contact sales" +- Brand + transactional modifier ("buy [product]," "[product] coupon," "[product] discount") +- "[Product] near me" (local-transactional) +- "[Product] free trial" + +### Examples + +\| Query \| What the searcher wants \| +\|---\|---\| +\| "buy iphone 16 pro" \| Purchase, fast \| +\| "salesforce free trial" \| Trial signup \| +\| "download notion mac" \| Direct download \| +\| "request a demo hubspot" \| Demo form \| +\| "plumber near me" \| A plumber to call \| +\| "amazon prime sign up" \| Amazon Prime signup flow \| + +### What to publish + +Product pages, pricing pages, signup pages, checkout flows, contact pages. Make the transactional path frictionless. Strong CTAs above the fold. Trust signals near the action. + +### CTA approach + +The CTA is the page. One primary action, sized and placed so the user cannot miss it. Secondary actions allowed if they protect the primary (e.g., "talk to sales" alongside "start free trial" for enterprise vs SMB). + +### Failure mode + +Burying the transactional action behind marketing copy. The user came to act. Get out of the way. + +--- + +## Mixed and ambiguous intent + +Many queries do not fit cleanly. Use the SERP to disambiguate. + +### Method + +Open the query in incognito. Look at the top 10 results. + +- All articles? Informational. +- All branded landing pages? Navigational or transactional. +- Mix of comparison pages, "best of" lists, and product pages? Commercial investigation. +- Mix of articles and product pages? Mixed - the safer bet is to produce both kinds of content. + +### Example: "crm software" + +Could be informational ("what is CRM software"), commercial investigation ("which CRM should I pick"), or transactional ("crm software to buy now"). The SERP shows: a definition (HubSpot's), a "best of" list (multiple), several product pages, and a Wikipedia entry. Mixed intent leaning commercial investigation. + +The right play: produce a comparison page that opens with a one-paragraph definition. Catches both intents. + +--- + +## Intent shifts across the funnel + +The same audience moves through intents. + +\| Stage \| Example query \| Intent \| Right content \| +\|---\|---\|---\|---\| +\| Aware of problem \| "team is missing deadlines" \| Informational \| Article on missed-deadline diagnosis \| +\| Aware of category \| "project management software" \| Informational + commercial \| Pillar guide \| +\| Comparing options \| "linear vs jira" \| Commercial investigation \| Comparison page \| +\| Ready to commit \| "linear pricing" \| Transactional \| Pricing page \| +\| Already a customer \| "linear keyboard shortcuts" \| Informational \| Help docs \| + +Build coverage across the funnel for your category. A site that only addresses transactional intent has nothing to rank for at the top of funnel and loses the audience to category-defining publishers. + +--- + +## Tagging in research + +When pulling keyword research, tag every row. + +\| Query \| Volume \| Difficulty \| Intent \| Notes \| +\|---\|---\|---\|---\|---\| +\| "service blueprint" \| 8,100 \| 32 \| Informational \| Definition + examples piece \| +\| "service blueprint vs customer journey" \| 1,200 \| 28 \| Commercial investigation \| Comparison piece \| +\| "service blueprint template" \| 2,400 \| 25 \| Informational + transactional \| Template page with download CTA \| +\| "service blueprint software" \| 880 \| 41 \| Commercial investigation \| Buyer's guide \| + +The intent tag drives the format and the CTA. Without it, content drifts into whatever the writer felt like producing. + +--- + +## Decision rule + +Once intent is tagged: + +- Informational: publish if the topic supports authority-building and the SERP is winnable. Skip if the SERP is dominated by big publishers and you have no asset. +- Navigational (your brand): make sure you own it. If not, fix. +- Navigational (someone else's brand): skip. +- Commercial investigation: publish if you compete in the category. These convert. +- Transactional: make sure your product / pricing / signup pages rank for the obvious branded transactional queries. Optimize them aggressively. + +--- + +## When intent surprises you + +Sometimes a query you assumed was one intent reveals as another. Trust the SERP over your assumption. The SERP reflects what Google has learned about searcher behavior at scale, which is more reliable than your guess. diff --git a/skills/seo-keyword/references/keyword-research-template.md b/skills/seo-keyword/references/keyword-research-template.md new file mode 100644 index 0000000..b701650 --- /dev/null +++ b/skills/seo-keyword/references/keyword-research-template.md @@ -0,0 +1,115 @@ +# Keyword Research: [Site or Topic Area] + +Date: [YYYY-MM-DD] +Scope: [What this research covers] +Audience: [Who we are writing for] +Tools used: [Which keyword tools were used] + +--- + +## Summary + +Total keywords analyzed: [N] +Clusters identified: [N] +Priority clusters (top 20%): [N] + +[2 to 3 sentence overview. The headline themes, the surprising finds, the strategic priorities.] + +--- + +## Top priority clusters + +The following clusters scored highest on opportunity, strategic fit, and reasonable difficulty. Produce these first. + +### Cluster 1: [Cluster name] +- Primary keyword: [keyword] (volume: X, difficulty: Y) +- Intent: [Informational / Commercial / Transactional / Navigational] +- Recommended page type: [Article / guide / comparison / product page / category] +- Secondary keywords: [list 5 to 15] +- Suggested URL: [/proposed-slug] +- Estimated effort: [Hours or days] +- Why this cluster: [1 to 2 sentences on strategic fit] + +### Cluster 2: [Cluster name] +- Primary keyword: +- Intent: +- Recommended page type: +- Secondary keywords: +- Suggested URL: +- Estimated effort: +- Why this cluster: + +[Continue for top 10 to 20 clusters.] + +--- + +## Full keyword sheet + +[Link to or attach the spreadsheet.] + +Columns: +1. Keyword +2. Volume +3. Difficulty +4. Intent (I/N/C/T) +5. SERP features (featured snippet, AI overview, PAA, video, image, local pack) +6. Cluster +7. Cluster role (primary / secondary / long-tail) +8. Opportunity score (1-5) +9. Strategic fit (1-5) +10. Priority (composite) +11. Notes + +--- + +## Topic map + +A visual or hierarchical view of how the clusters relate. This becomes the basis for internal linking and information architecture. + +``` +[Top-level topic] + ├── [Cluster A] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + ├── [Cluster B] + │ ├── Primary: [keyword] + │ └── Subtopics: [keywords] + └── [Cluster C] + └── ... +``` + +--- + +## Quick wins + +Existing pages that already rank on page 2 or low page 1 for high-value keywords. Optimizing these is faster than producing new content. + +\| URL \| Current rank \| Target query \| Volume \| Recommended action \| +\|---\|---\|---\|---\|---\| +\| \| \| \| \| \| +\| \| \| \| \| \| + +(Pull from search console: queries with average position 5 to 20 and impressions over 100/month.) + +--- + +## Deferred clusters + +Clusters that did not make the priority cut and why. + +\| Cluster \| Reason \| +\|---\|---\| +\| [Cluster name] \| Too competitive for current authority \| +\| [Cluster name] \| Low commercial value \| +\| [Cluster name] \| Audience mismatch \| +\| [Cluster name] \| Better suited for paid acquisition \| + +--- + +## Refresh schedule + +This research should be revisited: +- Quarterly for fast-moving topics (tech, news, trends, finance) +- Annually for evergreen topics +- After any major SERP feature change (e.g., AI overviews appearing on key queries) +- After authority increases that unlock harder keywords (e.g., domain rating going up by 10+ points) diff --git a/skills/seo-offpage/SKILL.md b/skills/seo-offpage/SKILL.md new file mode 100644 index 0000000..fc103e6 --- /dev/null +++ b/skills/seo-offpage/SKILL.md @@ -0,0 +1,168 @@ +--- +name: seo-offpage +description: "Plan and execute off-page SEO including link building, digital PR, brand mentions, citation building, and external authority signals. Use this skill whenever the user wants to build backlinks, plan a digital PR campaign, list local citations, run guest post outreach, develop linkable assets, recover lost links, or audit a backlink profile for risk. Triggers on link building, backlinks, digital PR, brand mentions, citation building, guest post, outreach, linkable asset, broken link building, HARO, podcast outreach, off-page SEO, anchor text, link velocity, toxic backlinks, disavow. Also triggers when the user is trying to grow domain authority or earn coverage." +category: seo-foundation +catalog_summary: "Link building, digital PR, citations, linkable assets" +display_order: 5 +--- + +# Off-Page SEO + +Build the external signals that earn rankings: backlinks, brand mentions, citations, and trusted sources pointing back to the site. Stack-agnostic. + +--- + +## When to use + +- Planning a link-building strategy +- Running digital PR or earned-media campaigns +- Building citations for a local business +- Developing linkable assets (research, tools, calculators) +- Recovering lost backlinks after a migration or audit +- Auditing a backlink profile for spam or toxicity +- Pitching guest posts, podcast appearances, or expert quotes + +## When NOT to use + +- On-site optimization (use `seo-onpage` or `seo-technical`) +- Keyword research and content planning (use `seo-keyword`) +- Competitor backlink research alone (start with `seo-competitor`, then return here for outreach planning) +- Paid link buying (this skill does not endorse or facilitate that) + +--- + +## Required inputs + +- The site or brand getting the links +- The audience and category +- A backlink tool (Ahrefs, Semrush, Moz, Majestic, or similar) for prospecting and monitoring +- A target outcome (rank for X, build authority in Y, recover from Z) + +--- + +## The framework: 4 strategies + +Off-page work splits into four strategy types. Most programs blend them. Pick the mix that fits your phase. + +### 1. Earned media +Links and mentions you earn through coverage, journalism, or contribution. + +- Digital PR (data-driven studies, original research, surveys) +- Expert quotes (HARO, journalist platforms, expert request services) +- Podcast appearances (relevant shows in your category) +- Speaking engagements and conference content +- Newsworthy product launches or company milestones + +Strength: Highest authority, hardest to replicate. +Cost: Time-intensive, often requires PR or content budget. +Volume: Low to medium per quarter. + +### 2. Owned assets +Linkable assets on your own site that attract links passively over time. + +- Original research and reports +- Free tools, calculators, and generators +- Comprehensive guides (the kind that become "the X resource for Y") +- Visualizations and interactive content +- Templates and frameworks +- Industry data trackers (regularly updated benchmarks) + +Strength: Compounds over time. Each link points at an evergreen asset. +Cost: Upfront content investment. +Volume: Slow to start, accelerates as the asset earns mentions. + +### 3. Partnerships and relationships +Links earned through real business relationships. + +- Customer case studies (where they link back) +- Partner programs and integrations +- Co-marketing campaigns +- Industry association memberships +- Speaker and expert contributor relationships +- Affiliate and referral programs + +Strength: Trustworthy, contextually relevant. +Cost: Time to develop relationships. +Volume: Medium and consistent. + +### 4. Citations and listings +Local and category-specific listings that establish entity legitimacy. + +- Google Business Profile (for local businesses) +- Bing Places, Apple Maps Connect +- Industry directories (review-quality only, skip spam directories) +- Niche association directories +- Wikipedia entry (where the brand qualifies for notability) +- Wikidata entry +- Trade publications and category indexes + +Strength: Foundational for local and entity SEO. +Cost: Low to medium, mostly setup time. +Volume: One-time foundation, occasional refresh. + +--- + +## Workflow + +1. Audit the current profile. + - Total referring domains + - Domain rating trend + - Top referring pages by traffic value + - Anchor text distribution (over-optimized exact-match anchors are a risk) + - Toxic links (spam directories, link farms, irrelevant categories) + - Lost links (referring domains that disappeared) + +2. Define the goal. "Rank top 3 for X by Q4" requires a different tactic mix than "build category authority." + +3. Pick the strategy mix. Allocate effort across the 4 strategies. A new site typically goes 70/20/10/0 (assets/citations/partnerships/earned) for the first year. An established site can lean more toward earned media. + +4. Build the prospecting list. + - For earned media: relevant journalists, podcast hosts, publication beats + - For owned assets: identify what assets to build based on what gets linked in your category + - For partnerships: list 50 to 100 potential partner sites + - For citations: standard list per category, plus niche directories + +5. Outreach. Personalized, value-first. Generic templated pitches damage the brand more than they help. + +6. Track and measure. + - Referring domains gained per month + - Domain rating trend + - Anchor text mix (avoid over-optimization) + - Pages on the site attracting links + - Lost link recovery rate + +7. Audit and disavow. Quarterly review for toxic links. Disavow only when there is real evidence of harm (manual penalty notice, sudden drop after spam attack). Most sites should not need to disavow. + +--- + +## Failure patterns + +- Volume over quality. 100 directory submissions help less than 5 editorial links from category-relevant sites. +- Buying links. Risk of manual penalties is real. Cost-adjusted, the ROI rarely works out. +- Over-optimized anchor text. If 40 percent of your inbound anchors are "best running shoes," it looks engineered. Aim for natural distribution: brand, naked URL, generic, partial-match, exact-match (in roughly that order of frequency). +- Generic outreach templates. "Dear [first name], I love your blog about [topic]" gets archived in seconds. Personalize or do not send. +- Ignoring lost links. A 5 percent monthly loss in referring domains compounds. Build a recovery workflow. +- Treating disavow as a routine cleanup tool. Disavow is for confirmed spam attacks or penalty recovery, not preemptive hygiene. +- Working off-page before the site is worth linking to. A poorly-designed, thin-content site will not convert outreach. Fix on-site first. + +--- + +## Output format + +Default output is a markdown plan at `offpage-strategy.md` plus tracking spreadsheets for prospects and outreach. + +Structure: +1. Current backlink profile summary +2. Goal and target metrics +3. Strategy mix (allocation across the 4 types) +4. Q1, Q2, Q3, Q4 tactical plan +5. Prospecting lists (in spreadsheets) +6. Outreach templates (personalized, never generic) +7. Tracking and measurement plan + +--- + +## Reference files + +- [`references/outreach-templates.md`](references/outreach-templates.md) - Templates for guest posting, expert quotes, broken-link outreach, podcast pitches. +- [`references/linkable-assets-guide.md`](references/linkable-assets-guide.md) - Categories of linkable assets with examples and effort estimates. diff --git a/skills/seo-offpage/references/linkable-assets-guide.md b/skills/seo-offpage/references/linkable-assets-guide.md new file mode 100644 index 0000000..ed9c7d7 --- /dev/null +++ b/skills/seo-offpage/references/linkable-assets-guide.md @@ -0,0 +1,353 @@ +# Linkable Assets Guide + +Categories of linkable assets, with examples and effort estimates. A linkable asset is content (or a tool, or a dataset) that other sites have a reason to link to. Without a linkable asset, link building is begging. With one, it is offering value. + +--- + +## What makes an asset linkable + +A linkable asset has at least one of these properties: + +- It is the only place to find this thing. Original data, original tool, original framework. +- It is the best place to find this thing. Most comprehensive, most current, most carefully built. +- It saves the linker time. A reusable resource the linker would otherwise have to build or explain. +- It carries authority. Survey from a recognized brand, published research, expert-authored. +- It is current. Updated more recently than alternatives, with the year visible. + +Pages that fail all five are not linkable. They might be useful, but they are not assets that earn links. + +--- + +## Category 1: original research + +Surveys, studies, or data analyses you ran and nobody else has. + +### Examples + +- Annual industry survey (e.g., "State of [category] 2026") +- Benchmark report from your own product data ("the average [metric] across 1,000 companies using us") +- Trend analysis from public data sources you cleaned and synthesized +- Salary or compensation report for your industry +- Pricing transparency report ("what [category] really costs") + +### Effort + +- Low end: 40-80 hours (existing data, in-house analysis, single-author write-up) +- High end: 200-400 hours (custom survey, n=1,000+, design and PR investment) + +### Link earning rate + +Highest of any category, when done well. A defensible original research asset can earn 100+ referring domains over its life. + +### When to invest + +If you have unique access to data (your product's data, your customer base, your industry network) and you can update annually, this is the highest-leverage asset category. + +### When to skip + +If the data is shallow, the sample is small, or the analysis is obviously self-serving, the asset will be ignored or worse, criticized publicly. + +--- + +## Category 2: free tools + +Calculators, validators, generators, viewers - small interactive utilities that solve a specific problem. + +### Examples + +- Calculators (mortgage, ROI, paycheck, conversion rate) +- Validators (HTML, schema markup, robots.txt, regex) +- Generators (favicon, color palette, password, lorem ipsum, og image) +- Converters (currency, units, file format) +- Viewers (JSON, EXIF, certificate) + +### Effort + +- Low end: 20-40 hours (single-purpose calculator, basic UI) +- High end: 200+ hours (rich tool with saved state, account integration, PWA, accessibility-perfect) + +### Link earning rate + +High and durable. Tools earn links steadily for years if they remain useful and current. + +### When to invest + +When the problem is recurring, you can build something cleaner than what exists, and the tool naturally surfaces your product as the next step (e.g., a "how much will this site weigh" tool from a perf optimization vendor). + +### When to skip + +When the space is saturated with free tools that already work well. A new "color picker" is unlikely to displace the entrenched ones. + +--- + +## Category 3: definitive guides + +Long-form, exhaustive coverage of a topic that becomes the reference everyone links to. + +### Examples + +- "The complete guide to DMARC" +- "The HTTP status code reference" +- "Web performance metrics explained" +- "The 2026 GDPR compliance checklist" +- "All the CSS units, with examples" + +### Effort + +- Low end: 40-80 hours +- High end: 200+ hours, plus annual maintenance + +### Link earning rate + +High when the topic has natural inbound demand and the asset is genuinely the best version. Lower when 5+ competitor guides already exist. + +### When to invest + +When you can credibly produce something better than the current best (more comprehensive, more current, better organized, better examples, better visuals). When the topic supports your business strategically. + +### When to skip + +When the topic is dominated by an evergreen entrenched guide (Wikipedia-level reference, MDN, NN/g) that you cannot displace. + +--- + +## Category 4: visual / interactive assets + +Infographics, interactive explainers, micro-sites built around a single concept. + +### Examples + +- Interactive timelines +- Animated explainers ("how does HTTPS work") +- Map-based visualizations +- Comparison interactive ("the size of every JavaScript framework") +- Single-purpose explainer micro-sites (e.g., "supply chain visualizer") + +### Effort + +- Low end: 40-80 hours (static infographic, simple interactive) +- High end: 400+ hours (complex interactive, custom illustration, browser-based simulation) + +### Link earning rate + +High when the visual is genuinely useful and shareable. Often peaks early and decays unless the topic has lasting interest. + +### When to invest + +When visual treatment unlocks something prose cannot show. When the topic has strong visual storytelling potential. When you have design capacity to do it well. + +### When to skip + +When the same value can be delivered as a normal article. Visual treatment is not a substitute for substance; it is a multiplier on substance that already exists. + +--- + +## Category 5: templates and frameworks + +Reusable structures the audience can copy, adapt, and use. + +### Examples + +- Project plan templates +- Notion / Airtable templates with download +- Email outreach templates +- Pitch deck templates +- Resume / CV templates +- Code starter templates (CodeSandbox, Stackblitz, GitHub repos) +- Frameworks ("the SPADE framework for decisions") + +### Effort + +- Low end: 8-20 hours per template +- High end: 40-80 hours for a polished template suite + +### Link earning rate + +Moderate. Templates earn references in roundups and resource lists. Less likely to earn high-authority editorial links. + +### When to invest + +When the template solves a frequent problem in your audience's work and naturally connects to your product. + +### When to skip + +When the template space is crowded with free, polished alternatives. + +--- + +## Category 6: glossaries and reference indexes + +Comprehensive, well-organized indexes of terms, codes, status messages, error codes, etc. + +### Examples + +- "All HTTP status codes with examples" +- "Glossary of marketing terms" +- "Every accessibility WCAG criterion explained" +- "The full list of CSS pseudo-classes" + +### Effort + +- Low end: 40-80 hours +- High end: 200+ hours, plus continuous updates + +### Link earning rate + +Moderate to high. Reference assets earn links steadily as authors writing on related topics need a place to link the term. + +### When to invest + +When you have the patience to be exhaustive and the topic supports it. + +### When to skip + +When canonical references already exist and dominate (MDN, W3C, official docs). + +--- + +## Category 7: industry rankings and lists + +Annual or continuous lists ranking companies, products, or trends in a category. + +### Examples + +- "The 100 fastest-growing [category] companies" +- "The 50 best [job role] to follow" +- "[Industry] state-of-the-art software comparison" + +### Effort + +- Low end: 60-100 hours +- High end: 200+ hours with PR + +### Link earning rate + +Moderate to high. Ranked companies link to the list as a credibility signal. Higher rankings earn more links. + +### When to invest + +When you have the credibility to be the ranker (your audience trusts your judgment in the category). + +### When to skip + +When you would be ranking yourself or competitors with no objectivity. + +--- + +## Category 8: events and community assets + +Conferences, summits, awards, communities you sponsor or run. + +### Examples + +- Industry conference recap and highlight reels +- Annual awards +- Slack / Discord community +- Recurring meetup +- Podcast + +### Effort + +- High. Events and communities require continuous investment, not one-time. + +### Link earning rate + +Moderate. Earns links from participants, partners, press coverage. + +### When to invest + +When the audience-building flywheel is part of your strategy and you can sustain investment for 2+ years. + +### When to skip + +When the team cannot commit to sustained investment. + +--- + +## Category 9: opinionated takes and POVs + +Strong, well-argued positions on industry questions. Not lists, not data; arguments. + +### Examples + +- "Why we stopped using [framework]" +- "The case against [common practice]" +- "[Industry standard] is wrong, and here is why" +- Manifestos + +### Effort + +- Low. A great POV piece can be 1,500-3,000 words and 10-30 hours. + +### Link earning rate + +Highly variable. A POV that hits a nerve in the industry can earn 50+ links in a week. Most POVs earn nothing. + +### When to invest + +When the author has standing to take the position credibly (track record, role, prior writing). When the POV is genuinely held and well-defended. + +### When to skip + +When the POV is contrarian for the sake of being contrarian. Bad-faith hot takes earn ire and short-term traffic, not durable links. + +--- + +## How to pick + +Score candidates against four dimensions: + +\| Dimension \| Weight \| Score 1-5 \| +\|---\|---\|---\| +\| Strategic fit \| 30% \| Does it serve a topic cluster you want to own? \| +\| Defensibility \| 25% \| Can you build something competitors will not easily match? \| +\| Effort \| 25% \| What does it cost to ship and maintain? (Lower effort = higher score) \| +\| Audience pull \| 20% \| Will the right people link to it? \| + +Build the highest-scoring candidate first. Ship one asset all the way through promotion before starting the next. Two well-promoted assets beat ten orphaned ones. + +--- + +## Promotion plan (a separate but linked task) + +A linkable asset that nobody knows about earns no links. The promotion plan must exist before the build starts. + +Typical promotion plan elements: + +- 5-10 pre-launch outreach contacts (industry voices, friendly press, peer companies who would benefit) +- Coordinated social, email, and content launch +- Explicit "ask" templates for outreach (no link begging; offer the asset as relevant, let the linker decide) +- Follow-up content that references the asset for the next 3-6 months +- Ongoing maintenance plan (annual update for research, evergreen updates for tools) + +Without a promotion plan, even great assets sit unlinked. + +--- + +## Common failure modes + +- Asset is too thin. Calling a 600-word article a "definitive guide" earns no respect. +- Asset is dated. "2022 industry report" still on the site in 2026. Looks abandoned. +- No promotion plan. Built, shipped, never told anyone. +- Self-serving disguised as research. Survey questions written to produce a result that flatters your product. +- Tool that breaks. Calculator with stale data, validator that misses common cases. Returns negative trust. +- Asset that offers no follow-up. Visitor arrives, uses it, leaves. No reason to subscribe, register, or convert. + +--- + +## Rough effort vs durable links matrix + +\| Category \| Effort \| Typical referring domains over asset's life \| +\|---\|---\|---\| +\| Free tool (single-purpose) \| 30 hours \| 40-200 \| +\| Free tool (rich) \| 200 hours \| 100-1,000 \| +\| Original research (annual) \| 100 hours \| 50-500 per edition \| +\| Definitive guide \| 80 hours \| 30-300 \| +\| Visual / interactive \| 80 hours \| 30-200 \| +\| Templates suite \| 40 hours \| 10-100 \| +\| Glossary / reference index \| 80 hours \| 50-300 \| +\| Industry ranking (annual) \| 100 hours \| 50-300 per edition \| +\| Community / event \| 1,000+ hours \| 100-1,000 \| +\| POV piece \| 20 hours \| 0-200 (high variance) \| + +These are rough ranges from typical SaaS and content-led businesses. Industry, audience size, and promotion quality all shift them substantially. diff --git a/skills/seo-offpage/references/outreach-templates.md b/skills/seo-offpage/references/outreach-templates.md new file mode 100644 index 0000000..4db4f4b --- /dev/null +++ b/skills/seo-offpage/references/outreach-templates.md @@ -0,0 +1,213 @@ +# Outreach Templates + +Templates for the most common off-page outreach scenarios. Personalize every send. The templates are scaffolding, not ready-to-fire copy. + +A few rules across all templates: + +- Subject lines under 60 characters +- First line never says "I love your blog" or any variant +- One specific reference to their actual work (not a generic compliment) +- One clear ask +- One reason it benefits them, not you +- Sign with a real name and link to a real profile +- Plain text, no formatting, no images, no tracking pixels + +--- + +## Guest post pitch + +Subject: [Topic] for [their site name]? + +Hi [first name], + +I just read your piece on [specific article, published Date] and noticed [specific observation about an angle they did not cover, or a question their piece raised but did not answer]. + +I write about [your topic area] and I think the gap there could become a strong follow-up. Working title: "[Specific working title]." It would cover: + +- [Specific point 1] +- [Specific point 2] +- [Specific point 3] + +I can have a draft to you in two weeks. Recent samples of my writing: +- [URL 1] +- [URL 2] + +If this is not a fit, no worries. Let me know either way. + +Thanks, +[Name] +[Title and where you write] + +--- + +## Expert quote / source pitch + +Subject: Expert source on [topic] for your [piece type] + +Hi [first name], + +I saw your request for sources on [topic] via [HARO / Twitter / their site]. + +Quick credentials: [one sentence on why you're qualified - title, years, specific work]. Happy to provide a quote, full interview, or background on: + +- [Specific angle 1] +- [Specific angle 2] +- [Specific angle 3] + +Available for a quick reply via email today, or a call this week. + +[Name] +[Title] +[Profile / portfolio link] + +--- + +## Broken link outreach + +Subject: Broken link on your [page topic] page + +Hi [first name], + +I was reading your [page name] page (great resource) and noticed the link to [specific old URL] is broken - the destination returns a 404. + +I run [your site] and we have a piece on the same topic that might be a relevant replacement: [your URL]. It covers [specific overlap with what the broken link was for]. + +No pressure either way. Just wanted to flag the broken link. + +[Name] + +--- + +## Podcast pitch + +Subject: [Specific topic angle] for [show name]? + +Hi [first name], + +I have been listening to [show name] for [time period]. The recent episode with [guest name] on [topic] resonated because [specific reason]. + +I would love to come on and talk about [specific topic angle]. Why this is a fit for your audience: + +- [Specific angle 1] +- [Specific angle 2] +- [What I bring that other guests have not covered] + +Past appearances: +- [Show name] - [topic] - [link] +- [Show name] - [topic] - [link] + +If the topic resonates, I can send a one-page brief with sample questions. + +[Name] +[Title] +[Headshot / bio link] + +--- + +## Resource page link request + +Subject: Resource for your [page topic] roundup + +Hi [first name], + +Your [page name] page is one of the better roundups I have seen on [topic]. I noticed it includes [example resource they list]. + +I run [site] and recently published [your URL], which covers [specific angle]. A few reasons it might earn a spot in the list: + +- [Differentiator 1: e.g., original data, more detail, recently updated] +- [Differentiator 2] + +If it is a fit, I would be grateful for the inclusion. If not, completely understood. + +[Name] + +--- + +## Linkable asset announcement + +Subject: New [asset type] on [topic] + +Hi [first name], + +We just published [asset type, e.g., "an interactive calculator", "a 50-source benchmark study", "a free template"] on [topic]: [URL]. + +The reason I am sending it your way: [specific reason this person or publication would care - their audience overlap, a stated interest, a recent piece they wrote]. + +Three things that make it different from existing resources: +1. [Specific differentiator] +2. [Specific differentiator] +3. [Specific differentiator] + +If it is useful for your readers, I would love a mention. Either way, I would value your read of it. + +[Name] + +--- + +## Citation / mention reclamation + +When your brand is mentioned online but not linked to. + +Subject: Quick note on the [piece] you published + +Hi [first name], + +Thanks for mentioning [your brand] in your [piece title, with link]. Genuinely appreciated. + +Quick request: would you be open to linking the mention back to [your URL]? Helps your readers find us, and helps us track the reach of the piece. + +No worries if it is not your editorial standard to add links retroactively. + +Thanks, +[Name] + +--- + +## Partnership pitch (low-key) + +Subject: [Brand] x [their brand]? + +Hi [first name], + +I run [your brand]. We share an audience with [their brand] - both serving [audience description]. + +A few low-effort ways we could collaborate: + +1. [Specific idea: e.g., cross-promote in newsletters, swap quotes for content, co-host a webinar] +2. [Specific idea] +3. [Specific idea] + +If any resonate, I would love a 20-minute call to figure out the simplest version we could ship in 30 days. + +[Name] +[Title] +[Site] + +--- + +## Universal don'ts + +- Do not start with "Hope you are doing well." +- Do not call yourself a "fellow [profession]" unless you actually know them. +- Do not say "I'll keep this brief" and then write 600 words. +- Do not attach files in cold outreach. +- Do not follow up more than twice. Three+ follow-ups damage reputation. +- Do not use subject lines like "Quick question" or "Re: [topic]" if it is not actually a reply. +- Do not include phrases like "value-add," "synergy," or "leverage." +- Do not pitch yourself as the expert in their field. They are. + +--- + +## Personalization checklist + +Before sending any outreach: + +- [ ] Used their first name correctly (spelled right) +- [ ] Referenced specific recent work of theirs (not from 5 years ago) +- [ ] Stated the ask clearly in the first 3 lines +- [ ] Gave them a reason to say yes that benefits them +- [ ] Plain text, no HTML, no images, no tracking pixel +- [ ] Subject line under 60 characters and not deceptive +- [ ] Signature includes real credentials and a way to verify the sender + +If any are missing, do not send. diff --git a/skills/seo-onpage/SKILL.md b/skills/seo-onpage/SKILL.md new file mode 100644 index 0000000..ae226fe --- /dev/null +++ b/skills/seo-onpage/SKILL.md @@ -0,0 +1,150 @@ +--- +name: seo-onpage +description: "Run a comprehensive on-page SEO audit or optimization pass covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, URL hygiene, and on-page schema. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review header structure, check internal linking, improve a single URL's search performance, or write SEO-friendly copy. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization, optimize this page, SEO this page. Also triggers for any single-page review where ranking, click-through, or relevance signal quality is the goal, even if the user does not say 'SEO' explicitly." +category: seo-foundation +catalog_summary: "Single-page audits and optimization across 8 dimensions" +display_order: 1 +--- + +# On-Page SEO + +Optimize a single page for search relevance, click-through, and crawler comprehension. Stack-agnostic. Works on any CMS, framework, or static site. + +--- + +## When to use + +- Auditing or optimizing a single page (homepage, product page, article, landing page) +- Writing or reviewing title tags and meta descriptions +- Fixing header structure or content hierarchy +- Reviewing internal links from or to a page +- Improving a page's CTR from search results + +## When NOT to use + +- Site-wide crawl, indexing, or speed issues (use `seo-technical`) +- Keyword research or intent mapping (use `seo-keyword`) +- Competitor SERP analysis (use `seo-competitor`) +- Auditing many pages at once for prune/merge decisions (use `seo-content-audit`) + +--- + +## Required inputs + +- The page URL or the draft content if pre-launch +- The primary target query (one phrase the page should rank for) +- The page's role in the site (commercial, informational, navigational) + +If the target query is unknown, run `seo-keyword` first or ask the user to name one. + +--- + +## The framework: 8 dimensions + +A complete on-page audit covers eight dimensions. Score each as Pass, Needs work, or Fail. Note the specific fix. + +### 1. Title tag +- One unique title per URL across the site +- Roughly 50 to 60 characters (longer gets truncated in SERPs) +- Primary query near the front +- Brand at the end if it earns inclusion +- Distinct from the H1 (often very similar, but should not be identical word-for-word) + +### 2. Meta description +- One unique description per URL +- Roughly 150 to 160 characters +- Restates the value proposition, not the title +- Includes a soft CTA where natural +- Treats the description as ad copy that earns the click + +### 3. Header structure +- Exactly one H1 per page +- H1 contains or paraphrases the primary query +- H2 sections cover the major sub-topics +- H3+ used only when an H2 has genuine sub-points +- No skipped levels (no H2 followed by H4) +- Headers describe sections accurately enough that a reader could navigate by them alone + +### 4. Body content +- Opens with the primary user intent answered in the first paragraph +- Covers the topic comprehensively (define your competition's depth, then match or exceed it) +- Includes related entities and supporting concepts naturally +- Avoids keyword stuffing (write for the reader, not the bot) +- Reading level matches the audience (run a readability check) +- Paragraphs short enough to scan on mobile (3 to 5 lines) + +### 5. Internal links +- At least 2 to 3 outbound internal links to closely related pages +- At least 2 to 3 inbound internal links from related pages +- Anchor text is descriptive, not "click here" or "learn more" +- Links to canonical URLs, not redirects +- No broken internal links + +### 6. Images and media +- Every meaningful image has descriptive alt text (skip alt for purely decorative images) +- File names are descriptive ("blue-running-shoe.jpg" not "IMG_4032.jpg") +- Modern format used where supported (WebP, AVIF) +- Lazy loading on below-the-fold images +- Width and height attributes set to prevent layout shift + +### 7. URL slug +- Lowercase, hyphen-separated +- Includes the primary query naturally (no stuffing) +- Short (under 60 characters where possible) +- No dates unless the page is genuinely time-bound +- No session IDs, tracking parameters, or random hashes +- Matches the site's URL pattern conventions + +### 8. On-page schema +- Appropriate Schema.org type for the content (Article, Product, FAQPage, HowTo, Recipe, etc.) +- Required properties filled (review Schema.org docs for the type) +- Validates in Google's Rich Results Test or equivalent +- Matches what is visible on the page (do not lie to crawlers) +- Author and publisher schema linked correctly for content pages + +--- + +## Workflow + +1. Confirm the target query. If unclear, ask. Do not optimize without one. +2. Render the page. View it as a user would. Read the content top to bottom. +3. View the rendered HTML. Inspect the actual served markup, not just the visual page. Check `<title>`, `<meta>`, headers, and schema in the source. +4. Run the 8-dimension framework. Score each, note specific fixes. +5. Prioritize. Group fixes into Critical (broken or missing), Important (suboptimal), and Nice-to-have (polish). +6. Write the report. Use the template in [`references/audit-template.md`](references/audit-template.md). +7. Offer to draft fixes. If the user wants, draft the new title, meta, headers, or copy directly. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Make it more SEO." Vague. Ask for the target query and what's broken first. +- "Add the keyword 5 times in the body." Keyword density is not a real ranking signal. Prioritize relevance and topical depth instead. +- Optimizing a page that is not crawlable or indexable. Check `seo-technical` first. No on-page work helps a noindexed page. +- Optimizing a page with no clear user intent. A page that does not serve a real query will not rank no matter how well-tagged it is. +- Targeting the same query as another page on the site. This is cannibalization. Use `seo-content-audit` to decide which page should rank. + +--- + +## Output format + +Default output is a markdown audit at `seo-audit-[page-slug].md` in the project root. Structure: + +1. Page summary (URL, target query, role) +2. Score across 8 dimensions +3. Critical fixes +4. Important fixes +5. Nice-to-have polish +6. Drafted replacements (if requested) + +Keep audits under 1500 words. If a page needs more detail, link to deeper appendices. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable audit template, copy and use. +- [`references/onpage-checklist.md`](references/onpage-checklist.md) - Quick-reference checklist for the 8 dimensions. +- [`references/title-and-meta-patterns.md`](references/title-and-meta-patterns.md) - Patterns for writing strong titles and meta descriptions. diff --git a/skills/seo-onpage/references/audit-template.md b/skills/seo-onpage/references/audit-template.md new file mode 100644 index 0000000..ab15d58 --- /dev/null +++ b/skills/seo-onpage/references/audit-template.md @@ -0,0 +1,112 @@ +# On-Page SEO Audit: [Page URL] + +Target query: [The primary phrase this page should rank for] +Page role: [Commercial / Informational / Navigational] +Audit date: [YYYY-MM-DD] +Auditor: [Name] + +--- + +## Summary + +[2 to 3 sentence overview. What's working, what's broken, what to fix first.] + +Overall score: [Pass / Needs work / Fail] + +\| Dimension \| Score \| One-line note \| +\|---\|---\|---\| +\| Title tag \| \| \| +\| Meta description \| \| \| +\| Header structure \| \| \| +\| Body content \| \| \| +\| Internal links \| \| \| +\| Images and media \| \| \| +\| URL slug \| \| \| +\| On-page schema \| \| \| + +--- + +## Critical fixes + +[Things that are broken, missing, or actively hurting the page.] + +### 1. [Fix name] +- Current: [What it is now] +- Problem: [Why it's broken] +- Fix: [Specific replacement] + +### 2. [Fix name] +- Current: +- Problem: +- Fix: + +--- + +## Important fixes + +[Things that are suboptimal but not broken.] + +### 1. [Fix name] +- Current: +- Problem: +- Fix: + +--- + +## Nice-to-have polish + +[Things that would lift the page from good to great.] + +- [Item] +- [Item] + +--- + +## Drafted replacements + +### Title tag +> Current: [exact current title] +> Proposed: [exact proposed title, with character count] + +### Meta description +> Current: [exact current meta] +> Proposed: [exact proposed meta, with character count] + +### H1 +> Current: [exact current H1] +> Proposed: [exact proposed H1] + +### Header outline +``` +H1: [proposed H1] + H2: [proposed section title] + H3: [if needed] + H2: [proposed section title] + H2: [proposed section title] +``` + +### URL (only if changing) +> Current: [current URL] +> Proposed: [proposed URL] +> Redirect required: Yes / No + +--- + +## Implementation notes + +[Any stack-specific considerations, deploy gotchas, or order-of-operations notes.] + +- [Note] +- [Note] + +--- + +## Verify after deploy + +- [ ] Rendered title in SERP preview tool matches proposed +- [ ] Rendered meta description matches proposed +- [ ] H1 visible and matches proposed +- [ ] Schema validates in Rich Results Test +- [ ] Internal links resolve, no broken anchors +- [ ] Images load with correct alt text +- [ ] If URL changed: 301 redirect in place, old URL no longer in sitemap diff --git a/skills/seo-onpage/references/onpage-checklist.md b/skills/seo-onpage/references/onpage-checklist.md new file mode 100644 index 0000000..283cf3e --- /dev/null +++ b/skills/seo-onpage/references/onpage-checklist.md @@ -0,0 +1,90 @@ +# On-Page SEO Checklist + +A condensed checklist for the 8 dimensions. Use as a pre-publish gate or a quick audit pass. + +--- + +## Title tag + +- [ ] Unique across the site +- [ ] 50 to 60 characters +- [ ] Primary query near the front +- [ ] Brand at end (only if it earns inclusion) +- [ ] Not identical to H1 +- [ ] Reads as a compelling search snippet, not a list of keywords + +## Meta description + +- [ ] Unique across the site +- [ ] 150 to 160 characters +- [ ] Restates value, does not repeat title verbatim +- [ ] Includes a soft CTA where natural +- [ ] No keyword stuffing +- [ ] Treats it as ad copy + +## Header structure + +- [ ] Exactly one H1 +- [ ] H1 contains or paraphrases primary query +- [ ] H2s cover the major sub-topics +- [ ] No skipped levels (H2 to H4 with no H3) +- [ ] Headers describe the section accurately +- [ ] A reader could navigate by headers alone + +## Body content + +- [ ] First paragraph answers the primary user intent directly +- [ ] Topical depth matches or exceeds top-ranking competitors +- [ ] Related entities and concepts appear naturally +- [ ] No keyword stuffing +- [ ] Reading level matches the audience +- [ ] Paragraphs are mobile-scannable (3 to 5 lines) +- [ ] Includes original perspective or proprietary data where possible + +## Internal links + +- [ ] At least 2 to 3 outbound internal links to related pages +- [ ] At least 2 to 3 inbound internal links from related pages +- [ ] Anchor text is descriptive +- [ ] Links to canonical URLs (no redirects) +- [ ] No broken internal links + +## Images and media + +- [ ] Every meaningful image has descriptive alt text +- [ ] Decorative images use empty alt (`alt=""`) +- [ ] File names are descriptive +- [ ] Modern format used (WebP or AVIF) +- [ ] Lazy loading on below-the-fold images +- [ ] Width and height attributes set +- [ ] Captions where they aid comprehension + +## URL slug + +- [ ] Lowercase, hyphen-separated +- [ ] Includes primary query naturally +- [ ] Under 60 characters where possible +- [ ] No dates unless time-bound +- [ ] No tracking parameters +- [ ] Matches site URL conventions + +## On-page schema + +- [ ] Appropriate Schema.org type +- [ ] Required properties filled +- [ ] Validates in Rich Results Test +- [ ] Matches what is visible on the page +- [ ] Author and publisher schema linked for content pages +- [ ] BreadcrumbList schema for nested pages + +--- + +## Quick wins (fastest to implement, biggest typical impact) + +1. Rewrite title tag for CTR +2. Rewrite meta description for CTR +3. Fix any missing or duplicate H1 +4. Add 2 to 3 internal links from existing related pages +5. Add alt text to images that lack it + +If a page is underperforming and you only have 30 minutes, run those five. diff --git a/skills/seo-onpage/references/title-and-meta-patterns.md b/skills/seo-onpage/references/title-and-meta-patterns.md new file mode 100644 index 0000000..71d1dd1 --- /dev/null +++ b/skills/seo-onpage/references/title-and-meta-patterns.md @@ -0,0 +1,306 @@ +# Title and Meta Patterns + +Patterns for writing strong title tags and meta descriptions. The title tag and meta description are the two most-edited and most-impactful elements in on-page SEO. They are also the two most often left as defaults. + +--- + +## Title tag patterns + +### The job of the title tag + +- Tell Google what the page is about (ranking signal) +- Tell the human what the page is about (CTR signal) +- Distinguish from other pages on the same site (uniqueness signal) +- Earn the click against 9 other titles in the SERP + +A title that does all four wins on rankings AND clicks. A title that does only the first ranks but earns no clicks. A title that does only the last earns clicks but ranks badly. + +### Length + +- 50-60 characters is the safe range for most desktop and mobile SERPs. +- Longer titles get truncated (Google appends "..."). +- Truncation is not catastrophic if the most important words are in the first 50 characters. + +### Character priority + +The most important word (typically the primary query target) goes near the front. Secondary words and brand go at the end. + +``` +[Primary query target] \| [Modifier or value prop] \| [Brand] +``` + +Examples: + +\| Bad \| Better \| +\|---\|---\| +\| "Welcome to Acme - your trusted partner in widgets since 1995" \| "Widgets for industrial use - Acme" \| +\| "Acme Inc. - Best widgets - Buy online" \| "Industrial widgets - free shipping - Acme" \| +\| "About us" \| "About Acme - 25 years building industrial widgets" \| + +### Patterns by page type + +#### Homepage + +``` +[Brand]: [One-line value prop] +``` + +Examples: +- "Notion: the all-in-one workspace for your notes and tasks" +- "Linear: built for modern software teams" +- "Acme Hardware: industrial widgets for builders" + +#### Category page + +``` +[Category name] - [Modifier or differentiator] \| [Brand] +``` + +Examples: +- "Industrial widgets - in stock, free shipping \| Acme" +- "Project management software for engineers \| Linear" +- "Recipes by region - 1,000+ tested recipes \| RecipeCo" + +#### Product / detail page + +``` +[Product name] - [Key benefit or spec] \| [Brand] +``` + +Examples: +- "10mm steel widget - 50 lb capacity \| Acme" +- "Linear Free - up to 10 users, unlimited issues \| Linear" +- "Mediterranean lentil soup recipe \| RecipeCo" + +#### Article / blog post + +``` +[Headline that promises value] - [Brand] +``` + +Examples: +- "How to choose an industrial widget supplier - Acme" +- "Linear vs Jira: 5 differences that actually matter - Linear" +- "Why your meta descriptions are getting rewritten - Search Engine Journal" + +The blog title is usually the H1 + brand. If the H1 is long, shorten for the title. + +#### Comparison / vs page + +``` +[Brand A] vs [Brand B]: [Differentiating angle] \| [Your brand] +``` + +Examples: +- "Linear vs Jira: speed, opinions, and team size \| Linear" +- "MongoDB vs PostgreSQL: when to pick which \| Engineering Blog" + +#### Pricing page + +``` +[Brand] pricing - [What is included] \| [Brand] +``` + +Examples: +- "Linear pricing - free forever for small teams \| Linear" +- "Pricing - simple, transparent, no surprises \| Acme" + +#### Geographic / location page + +``` +[Service] in [City], [State] \| [Brand] +``` + +Examples: +- "Plumbing services in Austin, TX \| Smith Plumbing" +- "Coworking in Brooklyn - day passes and memberships \| WorkSpace" + +--- + +## Title rules and anti-patterns + +### Do + +- Put the primary query near the front +- Include brand at the end +- Use a separator that the SERP renders cleanly (`\|`, `-`, `:`) +- Be specific (numbers, modifiers, segments earn attention) +- Match the H1 in spirit, not word-for-word + +### Do not + +- Repeat the primary query multiple times ("Widgets, industrial widgets, buy widgets - Widgets.com") +- Start with the brand on every page (homepage is the exception) +- Use ALL CAPS for emphasis +- Use clickbait phrasing that mismatches the page content +- Pad with filler words ("Welcome to," "Find the best," "Looking for") +- Append "Home" / "Default" / "Untitled" +- Leave it as the CMS default + +--- + +## Meta description patterns + +### The job of the meta description + +- Earn the click in the SERP +- Set expectations for what the page delivers +- Reinforce the primary query (Google bolds matched terms) + +The meta description is not a ranking signal directly. It is a CTR signal, which feeds back into ranking via behavioral signals. + +### Length + +- 140-160 characters. Longer gets truncated on most devices. +- Mobile truncates earlier than desktop. Front-load the value. + +### Structure + +Three moves in 1-3 sentences: + +1. Promise the value. What does the reader get if they click? +2. Justify it. Why is this credible? (Numbers, recency, specificity, authority.) +3. Cue the action. What should they expect to do or learn? + +Not every meta description does all three. The strongest do. + +### Examples + +\| Bad \| Better \| +\|---\|---\| +\| "Welcome to our blog where we write about widgets." \| "How to pick the right industrial widget for your project. 10 specs that matter, with a comparison chart." \| +\| "Acme Inc. is a leading provider of widgets and other products." \| "Industrial widgets in 50+ sizes. Free shipping over $100. Same-day dispatch from Austin, TX." \| +\| "Click here to learn more about our pricing." \| "Linear pricing: free forever for teams up to 10. Pro is $8/user/month. No setup fee. See plans and limits." \| + +--- + +## Meta description patterns by page type + +### Homepage + +``` +[What the brand does, one sentence]. [The audience or use case]. [The differentiator or social proof]. +``` + +Example: "Modern issue tracking for software teams. Built for speed. Used by 5,000+ teams from startups to enterprise." + +### Category page + +``` +[What the category contains]. [The selection or differentiator]. [Trust or shipping signal]. +``` + +Example: "Industrial widgets in 50+ sizes from 10mm to 200mm. Free shipping over $100. In stock and ready to ship from Austin." + +### Product / detail page + +``` +[Product, with key spec]. [Use case]. [Trust signal or guarantee]. +``` + +Example: "10mm steel widget rated to 50 lb. Built for industrial assembly lines. 5-year warranty, free returns." + +### Article / blog post + +``` +[The promise of the article in one sentence]. [The substance or evidence]. [Optional: who it is for]. +``` + +Example: "How to choose between Linear and Jira: 5 specific differences in workflow, speed, and pricing. With screenshots and benchmarks. For engineering managers comparing the two." + +### Pricing page + +``` +[The headline pricing]. [What is included]. [Anti-friction language]. +``` + +Example: "Linear is free forever for teams up to 10. Pro plan starts at $8/user/month. No setup fee, cancel anytime." + +--- + +## Meta description rules + +### Do + +- Front-load the value +- Use the primary query naturally (Google bolds it) +- Include numbers, specifics, and proof points +- Match the page's actual content +- Write for humans (it is a sales line, not a ranking line) + +### Do not + +- Pad with marketing-speak ("revolutionary," "industry-leading") +- Repeat the title verbatim +- End mid-sentence +- Stuff keywords (Google will rewrite the description if it looks unnatural) +- Leave the CMS default +- Use the same description on multiple pages + +--- + +## When Google rewrites your meta description + +Google rewrites meta descriptions when it thinks its rewrite will earn more clicks. Common triggers: + +- The description does not match the query +- The description is too short, too generic, or stuffed +- The page content has clearly different value from the description +- The page is matched against a long-tail query the description does not address + +To avoid rewrites: + +- Match the description to the page's actual content +- Make sure the primary query appears naturally in the description +- Keep the description specific and current + +If Google rewrites your description and the rewrite is wrong (low CTR, misleading), tighten the description and consider adding `name="description"` plus alternative phrasings via `<meta property="og:description">` for parity. + +--- + +## CTR optimization tips (beyond pattern) + +- Numbers earn attention. "5 ways," "100+ examples," "in 10 minutes." +- Year in title for evergreen-but-current content. "(2026)" earns clicks in fast-moving categories. Update annually. +- Brackets and parens are click-bait when overused, useful when accurate. "[Free Template]," "(2026 update)." +- Question titles work for some intents. "How do I [task]?" earns clicks for how-to. +- Comparison titles are click magnets. "X vs Y: [angle]." +- Promise-and-deliver framing. Title promises a specific value; the page delivers it. + +--- + +## Title and description audit shortcut + +For any page, ask: + +1. Does the title contain the primary query in the first 30 characters? +2. Is the title under 60 characters? +3. Is the title unique on the site? +4. Does the meta description promise value, justify it, and read as a human-written sentence? +5. Is the meta description under 160 characters? +6. Has Google rewritten the description? (Check Search Console performance report.) + +If 4 of 6 are "no," the title or description is the highest-leverage fix on the page. + +--- + +## A/B testing titles and descriptions + +For high-traffic pages, A/B test alternates. Tools that support this: native CMS tools, edge workers, dedicated SEO testing platforms. + +Test one variable at a time (title length, vs comparison hook vs question form, etc.). Run for 2-4 weeks per variant. Measure CTR and downstream conversion, not just rank position. + +--- + +## Snippet appearance is not just title and description + +What the SERP shows can include: + +- The title and description (this guide) +- Sitelinks (Google-auto, can be encouraged via clean IA) +- Rich results from schema (recipe, FAQ, product, review) +- Breadcrumbs (improves CTR, requires breadcrumb schema) +- Author and date (article schema) +- Featured snippets (a separate optimization layer) + +Title and description are the foundation. Schema and sitelinks are leverage on top. diff --git a/skills/seo-rank-tracking/SKILL.md b/skills/seo-rank-tracking/SKILL.md new file mode 100644 index 0000000..c1cb198 --- /dev/null +++ b/skills/seo-rank-tracking/SKILL.md @@ -0,0 +1,250 @@ +--- +name: seo-rank-tracking +description: "Set up and run rank tracking using Ahrefs MCP: pick the right keywords to track, segment them by purpose, set baselines, and define alert thresholds. Use this skill when starting a new tracking project, baselining for a campaign, choosing what to monitor, or building a rank reporting cadence. Triggers on rank tracking, keyword tracking, monitor rankings, track positions, what should we track, ranking dashboard, baseline rankings, alert thresholds. Also triggers when a stakeholder wants weekly or monthly ranking visibility." +category: seo-audit-suite +catalog_summary: "Setup, baseline, segmentation, alerting, dashboarding" +display_order: 7 +--- + +# SEO Rank Tracking + +Set up and run an ongoing rank tracking program using Ahrefs MCP data. Stack-agnostic. Produces a tracked keyword set, segmentation, baseline, alert thresholds, and a review cadence. + +--- + +## When to use + +- Starting rank tracking for a new property or section +- Baselining before a campaign, content launch, or major site change +- Deciding what keywords are worth tracking +- Setting up a ranking dashboard for stakeholders +- Establishing alert thresholds for ranking drops +- Reviewing whether the current tracked set is still meaningful + +## When NOT to use + +- Keyword discovery (use `seo-keyword`) +- Competitor keyword analysis (use `seo-keyword-gap-audit`) +- Diagnosing a ranking change that already happened (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) + +--- + +## Required inputs + +- Target property +- Target market and language +- Business priorities (which segments matter) +- Existing ranked keywords (Ahrefs Site Explorer) +- Stakeholder reporting cadence (weekly, monthly, quarterly) +- Confirmation Ahrefs MCP and Rank Tracker access + +--- + +## The framework: tracking taxonomy + +A good tracked keyword set has structure. Random keyword lists produce noisy dashboards. Segmented keyword sets produce signal. + +Group every tracked keyword into one of four buckets. + +### Bucket 1: Brand keywords + +Queries containing the brand name (and major variants and misspellings). + +Why track: + +- Detect brand visibility issues +- Catch competitors bidding on the brand +- Spot reputation problems early + +Volume in this bucket: typically 10-30 keywords for most brands. + +Healthy signal: position 1 for all variants. Anything else is investigate-worthy. + +### Bucket 2: Money keywords + +Queries that drive (or should drive) revenue: high-intent transactional and evaluation-stage queries directly tied to the business model. + +Why track: + +- These are the keywords that pay the bills +- Movement here directly affects revenue +- Stakeholders care most about these + +Volume in this bucket: 30-100 keywords for most properties. More for ecommerce. + +Healthy signal: top 3-5 positions. Watch for position drift in either direction. + +### Bucket 3: Opportunity keywords + +Queries the property is currently ranking on page 2-3 (positions 11-30) with potential to break into top 10. + +Why track: + +- These are the active growth bets +- Movement reflects whether content investment is working +- Quick wins typically come from this bucket + +Volume in this bucket: 50-200 keywords typically. + +Healthy signal: trending toward page 1 over a 90-day window. + +### Bucket 4: Competitor benchmark keywords + +A representative sample of head and torso queries shared with the competitor set, used to track relative position over time. + +Why track: + +- Measure share of voice +- Spot competitor gains in real time +- Provide industry context for movement + +Volume in this bucket: 50-150 keywords. + +Healthy signal: relative position improving or holding within a defined competitive band. + +--- + +## Selection criteria + +### Brand bucket + +- Brand name (exact) +- Brand name + product or service +- Brand name common misspellings +- Brand name + "review", "vs", "alternative" +- Brand-owned product names if relevant + +### Money bucket + +- Top 20 ranked keywords by traffic value (Ahrefs Site Explorer) +- Top transactional queries from Search Console with non-trivial impressions +- Conversion-driving queries identified in analytics +- Strategic head terms from `seo-keyword-gap-audit` output + +Quality over volume. 50 well-chosen money keywords beats 500 noisy ones. + +### Opportunity bucket + +- All keywords currently ranking positions 11-30 with monthly volume above a relevance-appropriate threshold +- Queries with rising impression volume in Search Console +- Output from the keyword gap audit's quick wins list + +Refresh this bucket quarterly. Opportunity is a moving target. + +### Competitor benchmark bucket + +- Keywords where 3+ competitors rank in top 20 +- Mix of head, torso, and informational queries +- Sized to represent the broader category + +This bucket is for relative comparison, not absolute targeting. + +--- + +## Segmentation beyond buckets + +Tag every tracked keyword on additional dimensions for filtering: + +\| Tag \| Purpose \| +\| --- \| --- \| +\| Topic or pillar \| Group by editorial theme \| +\| Funnel stage \| TOFU, MOFU, BOFU \| +\| Content type expected \| Article, product page, calculator, etc. \| +\| Page mapped \| Which URL is targeting this query \| +\| Country and language \| For multi-market sites \| +\| Device \| Desktop, mobile \| +\| SERP feature presence \| Featured snippet, AI overview, video, etc. \| + +Tagging up front pays off when filtering reports later. + +--- + +## Baselines + +Capture the starting state on day one. + +For each keyword, record: + +- Current position +- Current SERP composition (top 10 domains, dominant content type, SERP features present) +- Current click-through rate at that position (from Search Console if available) +- Date of baseline + +Baselines are the reference for measuring future movement. Without one, every dashboard is just current state. + +--- + +## Alert thresholds + +Not every position change deserves attention. Set thresholds that filter noise. + +### Default thresholds + +\| Bucket \| Alert if \| +\| --- \| --- \| +\| Brand \| Position drops below 1 for any tracked variant \| +\| Money \| Position drops by 5+ places, or out of top 10 \| +\| Opportunity \| Position rises into top 10 (positive alert), or drops past 30 \| +\| Competitor benchmark \| Aggregate share-of-voice changes by 10%+ \| + +Adjust thresholds based on volatility of the niche. High-competition spaces need looser thresholds to reduce false alarms. + +### Alert routing + +- Brand alerts: notify SEO lead and brand manager immediately +- Money alerts: notify SEO lead within a daily digest +- Opportunity alerts: weekly summary +- Competitor alerts: monthly summary + +--- + +## Workflow + +1. Define scope. Target property, market, language, stakeholders. +2. Pull starting data. Existing ranked keywords, Search Console queries, competitor overlap. +3. Build the tracked set. 4 buckets, 200-500 total keywords for most properties. +4. Segment with tags. Topic, funnel stage, page mapped, etc. +5. Configure tracking. Set up Ahrefs Rank Tracker projects with tags and locations. +6. Capture baseline. Day-one positions and SERP composition. +7. Define alert thresholds. By bucket. Wire to notification system. +8. Build the dashboard. See [`references/dashboard-template.md`](references/dashboard-template.md). +9. Set the cadence. Weekly review of money + brand. Monthly review of all. Quarterly rebuild of opportunity bucket. +10. Iterate. Drop dead keywords. Add new ones. Recalibrate thresholds based on noise. + +--- + +## Failure patterns + +- Tracking too many keywords. A 5,000-keyword tracker is unreadable. Pick fewer, watch closer. +- Tracking too few. A 30-keyword tracker misses the picture. Most properties need 200-500. +- No segmentation. Untagged tracked keywords produce dashboards that cannot be filtered. +- No baseline. Without day-one snapshots, "did the campaign work" becomes unanswerable. +- Alert fatigue. Loose thresholds produce too many alerts. Stakeholders stop reading. Tighten. +- Set and forget. Tracked keyword sets need quarterly review. Opportunity moves. Money keywords shift. +- Conflating position with traffic. A position-1 keyword with no clicks is worse than a position-5 keyword with steady traffic. Layer in CTR and clicks data. +- Single-device tracking on a mobile-dominant business. Track the device that matches the audience. +- Tracking aggregate position only. Aggregate position averages can hide important movement in specific buckets. Always show by bucket. +- Reporting absolute position without context. "We are position 4" means nothing. "Up from position 11 over 60 days" means something. + +--- + +## Output format + +A rank tracking setup document with: + +1. Tracking charter. Property, scope, stakeholders, cadence. +2. Tracked keyword set. All keywords with bucket and tag assignments. +3. Baseline snapshot. Position, SERP composition, CTR per keyword. +4. Alert configuration. Thresholds by bucket, routing. +5. Dashboard layout. What charts, what filters, what is visible. +6. Review cadence. Weekly, monthly, quarterly responsibilities. +7. Methodology notes. Country and device settings, refresh frequency, data caveats. + +Plus a recurring rank report at the chosen cadence (typically weekly or monthly). + +--- + +## Reference files + +- [`references/dashboard-template.md`](references/dashboard-template.md) - Template for the rank tracking dashboard layout, including the recurring report structure for weekly and monthly cadences. diff --git a/skills/seo-rank-tracking/references/dashboard-template.md b/skills/seo-rank-tracking/references/dashboard-template.md new file mode 100644 index 0000000..f3ec228 --- /dev/null +++ b/skills/seo-rank-tracking/references/dashboard-template.md @@ -0,0 +1,273 @@ +# Rank tracking dashboard template + +A template for the rank tracking dashboard and the recurring weekly and monthly rank reports. + +--- + +## Dashboard layout principle + +The dashboard should answer three questions in order: + +1. Are we okay? (brand and money buckets) +2. Are we growing? (opportunity bucket) +3. How do we compare? (competitor benchmark bucket) + +Anything that does not serve those three questions is clutter. + +--- + +## Section 1: Brand health (top of dashboard) + +Single panel. Status indicator. Should be glanceable. + +Display: + +- Position 1 status across all brand variants (count: e.g., "27 of 30 variants at position 1") +- Any brand variant not at position 1, listed below the status + +Alert color coding: + +- Green: all brand variants at position 1 +- Yellow: 1-3 variants below position 1 +- Red: 4+ variants below position 1, or any branded query showing competitor in top 3 + +--- + +## Section 2: Money keyword health + +The keystone section. Show: + +### Headline metric + +- Average position across all money keywords (current vs 30 days ago vs 90 days ago) +- Count of money keywords in top 3, top 10, top 20, beyond + +### Movement table + +Top 10 movers (positive and negative) over the chosen window: + +\| Keyword \| Bucket \| Current position \| Change \| Page mapped \| +\| --- \| --- \| --- \| --- \| --- \| +\| [keyword] \| Money \| 4 \| +6 \| /products/[slug] \| + +### Distribution chart + +Stacked bar showing how many money keywords are at each position band: + +- Top 3 +- Positions 4-10 +- Positions 11-20 +- Positions 21-50 +- Beyond 50 or unranked + +Track this distribution over time. Improving SEO shifts the distribution upward. + +--- + +## Section 3: Opportunity progress + +The growth section. + +### Headline metric + +- Count of opportunity keywords that broke into top 10 over the chosen window +- Count that fell out of opportunity range (past 30 or to top 10) +- Net opportunity bucket size (with quarterly refresh) + +### Top breakthroughs + +Keywords that crossed from positions 11-30 into top 10: + +\| Keyword \| Previous position \| Current position \| Page mapped \| Likely cause \| +\| --- \| --- \| --- \| --- \| --- \| +\| [keyword] \| 14 \| 7 \| /guides/[slug] \| Refresh shipped 30 days ago \| + +### Top regressions + +Keywords moving the wrong way: + +\| Keyword \| Previous position \| Current position \| Page mapped \| Likely cause \| +\| --- \| --- \| --- \| --- \| --- \| + +--- + +## Section 4: Competitor benchmark + +### Share of voice + +Aggregate position-weighted share of voice across the benchmark keyword set: + +\| Property \| SOV (current) \| SOV (90 days ago) \| Change \| +\| --- \| --- \| --- \| --- \| +\| [Target] \| 18% \| 14% \| +4 \| +\| [Competitor A] \| 22% \| 23% \| -1 \| +\| [Competitor B] \| 15% \| 16% \| -1 \| +\| [Competitor C] \| 12% \| 10% \| +2 \| + +### Head-to-head + +For top 20 strategic head terms, show position for target and each competitor side by side. + +--- + +## Section 5: SERP feature awareness + +Dashboard should call attention to SERP composition changes. + +Track: + +- Featured snippets owned by target (count, change) +- AI overviews appearing on target's tracked queries (count, change) +- Featured snippets owned by competitors on tracked queries +- New SERP feature types appearing (video carousels, image packs, etc.) + +A position-1 ranking that loses its featured snippet can lose 30%+ clicks while position stays the same. + +--- + +## Section 6: Filters + +The dashboard must be filterable by: + +- Bucket (brand, money, opportunity, benchmark) +- Topic or pillar tag +- Funnel stage tag +- Country and language +- Device +- Page mapped (URL) + +Filters let stakeholders drill from "the dashboard" to "my section". + +--- + +## Weekly report template + +The weekly report is for the SEO team and immediate stakeholders. + +``` +# Weekly rank report: [property] +Week of: [date range] +Prepared: [date] + +## Brand health + +[Green/Yellow/Red indicator] +[1-2 sentences. Anything not at position 1.] + +## Money keyword movement + +- Average position: [N] (vs [N] last week, [N] 90 days ago) +- Top 3 count: [N] (vs [N] last week) +- Top 10 count: [N] (vs [N] last week) + +### Notable gainers + +\| Keyword \| Previous \| Current \| Change \| +\| --- \| --- \| --- \| --- \| + +### Notable decliners + +\| Keyword \| Previous \| Current \| Change \| +\| --- \| --- \| --- \| --- \| + +## Opportunity progress + +- Breakthroughs to top 10: [N] +- Regressions out of opportunity range: [N] + +## Alerts triggered this week + +\| Date \| Keyword \| Bucket \| Alert \| Action taken \| +\| --- \| --- \| --- \| --- \| --- \| + +## Hypothesis or call-out + +[1-2 sentences on the most interesting movement and what it suggests.] +``` + +Length: 1 page. Readable in 3 minutes. + +--- + +## Monthly report template + +The monthly report is for broader stakeholders. Add narrative. + +``` +# Monthly rank report: [property] +Month: [month] +Prepared: [date] + +## Headline + +[1 paragraph. State of organic visibility.] + +## Brand and money keywords + +- Brand health: [status, with any concerns] +- Money keyword distribution: [chart description, key shifts] +- Notable wins: [bullet list] +- Notable concerns: [bullet list] + +## Opportunity progress + +- Breakthroughs to top 10 this month: [N] +- Quarterly target progress: [N of target N] +- Top opportunities watched + +## Competitive landscape + +- Share of voice: [target % vs competitor set] +- Notable competitor movement +- New SERP features observed + +## Themes for the month + +[3-5 themes from the data. Each is 1 paragraph.] + +## Recommendations for next month + +[Specific actions with owners and expected outcomes.] + +## Methodology + +- Tracking set: [N] keywords across [N] buckets +- Country: [list] +- Device: [list] +- Last refresh: [date] +- Data caveats: [list] +``` + +Length: 4-8 pages. + +--- + +## Quarterly rebuild + +Every 90 days, audit the tracked set itself. + +### Rebuild checklist + +- [ ] Brand bucket: any new product names, brand variants, or PR-driven query patterns? +- [ ] Money bucket: any keywords no longer aligned with current product or content focus? +- [ ] Money bucket: any new high-value queries identified by analytics or Search Console? +- [ ] Opportunity bucket: rebuild from current page 2-3 rankings; remove keywords that broke into top 10 (move to money) or fell past 30 (drop) +- [ ] Benchmark bucket: still representative of competitive landscape? +- [ ] Tags: any new pillars or topics that need tagging? +- [ ] Alert thresholds: too noisy? too quiet? recalibrate +- [ ] Reporting cadence: still useful at this frequency? + +Document the rebuild in a short changelog so historical comparisons remain interpretable. + +--- + +## Common dashboard pitfalls + +- Single big number. "Average position" alone hides bucket-level signal. +- No trend lines. Current state without trend is half the picture. +- No segmentation visible. A dashboard that cannot be filtered cannot answer follow-up questions. +- Showing every keyword. Stakeholders cannot read 500 rows. Show distributions and movers. +- Hiding SERP features. Feature changes cause invisible click drops. Always show them. +- Showing only target, not competitors. Movement is meaningless without context. +- Static data. A rank dashboard updated monthly is too slow for fast-moving niches. Match refresh to volatility. +- No annotations. Mark deploy dates, content launches, and known algorithm updates on charts so movement has context. diff --git a/skills/seo-site-health-audit/SKILL.md b/skills/seo-site-health-audit/SKILL.md new file mode 100644 index 0000000..a47c414 --- /dev/null +++ b/skills/seo-site-health-audit/SKILL.md @@ -0,0 +1,184 @@ +--- +name: seo-site-health-audit +description: "Triage technical SEO findings from Ahrefs Site Audit (and similar crawlers) by SEO impact, not just severity. Use this skill when reviewing crawl results, prioritizing technical fixes, scoping a technical SEO sprint, or after running any site-wide crawl. Triggers on site audit results, technical fix list, crawl errors, technical SEO triage, prioritize technical issues, what should we fix first, broken links, redirect chains. Also triggers when a long list of crawler issues is creating decision paralysis." +category: seo-audit-suite +catalog_summary: "Triage Ahrefs Site Audit findings by SEO impact, not severity" +display_order: 6 +--- + +# SEO Site Health Audit + +Triage technical SEO findings from Ahrefs Site Audit (or any equivalent crawler) by impact on rankings and traffic, not by raw issue count or severity label. Stack-agnostic. Produces a prioritized backlog of fixes mapped to business impact. + +--- + +## When to use + +- After running an Ahrefs Site Audit or other site-wide crawl +- Reviewing a long list of technical issues and needing to prioritize +- Scoping a technical SEO sprint +- Pre-launch or post-migration technical verification +- Quarterly technical health check +- When developer time is limited and you must pick the highest-leverage fixes + +## When NOT to use + +- Running the crawl itself (use the crawler tool directly) +- Diagnosing specific traffic drops (use `seo-traffic-diagnosis`) +- Single-page audits (use `seo-onpage`) +- Pure technical strategy or schema design (use `seo-technical`) + +--- + +## Required inputs + +- Crawl results from Ahrefs Site Audit (or equivalent) +- Search Console coverage and Core Web Vitals data +- Property's organic traffic profile (which pages drive traffic) +- Stakeholder time and developer capacity available +- Confirmation Ahrefs MCP is connected + +--- + +## The framework: triage by SEO impact, not severity + +Crawlers label issues "critical", "warning", "notice". These labels are useful but not sufficient. Two issues both labeled "critical" can have wildly different actual impact on the property. + +Triage on three axes. + +### Axis 1: Page-level traffic impact + +Does the issue affect a page that drives meaningful organic traffic, or one that does not? + +A "critical" issue on a tag archive with zero traffic is lower priority than a "warning" on a top-10-traffic landing page. + +Tier the affected URLs: + +- Tier 1: Top 10% of pages by organic traffic +- Tier 2: Pages that rank but do not yet drive significant traffic (page 2-3 results) +- Tier 3: Pages that exist but do not rank meaningfully + +A fix on Tier 1 is worth 10x a fix on Tier 3 in most cases. + +### Axis 2: Mechanism of impact + +Does the issue actually move rankings or traffic? Some "critical" issues are aesthetic or theoretical. + +Categories of real impact: + +\| Mechanism \| Examples \| +\| --- \| --- \| +\| Indexability \| Accidental noindex, robots.txt blocks, canonical errors, X-Robots-Tag \| +\| Crawlability \| Crawl traps, infinite redirects, 5xx errors, slow server response \| +\| Renderability \| JS errors blocking critical content, blocked resources \| +\| Core Web Vitals \| LCP, INP, CLS in the poor band \| +\| Structured data \| Errors on rich-result-eligible pages (not warnings) \| +\| Internal link integrity \| 404s on internally linked URLs, broken canonicals \| +\| Hreflang \| Errors on multilingual deployments \| + +Categories of low or theoretical impact: + +\| Type \| Why it is lower priority \| +\| --- \| --- \| +\| Title tag length warnings \| Not a ranking factor in itself \| +\| Meta description length \| Not a ranking factor \| +\| H1 absence on low-traffic pages \| Marginal impact \| +\| Alt text missing on decorative images \| Accessibility issue, low SEO impact \| +\| Schema warnings (not errors) \| Often best-practice nudges, not ranking issues \| + +Fix the high-mechanism categories first. + +### Axis 3: Effort + +Some issues are 5-minute fixes. Some are multi-sprint projects. + +- S (small): Configuration change, single template edit, sitemap regeneration +- M (medium): Theme or component change, redirect map work, template-level fixes +- L (large): Architecture change, re-platform, framework migration, schema overhaul + +--- + +## The triage matrix + +Combine the three axes into a priority score. + +\| Tier \| Mechanism \| Effort \| Priority \| +\| --- \| --- \| --- \| --- \| +\| Tier 1 \| High mechanism \| S \| P0 (do this week) \| +\| Tier 1 \| High mechanism \| M \| P1 (do this sprint) \| +\| Tier 1 \| High mechanism \| L \| P2 (plan as project) \| +\| Tier 1 \| Low mechanism \| S \| P3 (batch when convenient) \| +\| Tier 1 \| Low mechanism \| M-L \| Park unless evidence emerges \| +\| Tier 2 \| High mechanism \| S \| P1 \| +\| Tier 2 \| High mechanism \| M-L \| P2 \| +\| Tier 3 \| High mechanism \| S \| P3 \| +\| Tier 3 \| Anything else \| Anything \| Park \| + +P0-P1 work earns the team's attention. P2 goes on the roadmap. P3 batches into routine maintenance. Park is honest about deprioritization. + +--- + +## Workflow + +1. Pull the crawl results. Ahrefs Site Audit + Search Console + Core Web Vitals. +2. Tier the URLs. Use organic traffic data. Tag every affected URL as Tier 1, 2, or 3. +3. Categorize each issue by mechanism. High or low impact mechanism. +4. Estimate effort per fix type. Group similar fixes into one effort estimate. +5. Apply the triage matrix. Assign P0-P3 or Park. +6. Cluster the fixes. Group fixes that share an effort: one template change can resolve hundreds of issues. +7. Build the backlog. P0 first, P1 next, etc. Add fix descriptions, owners, expected impact. +8. Add measurement. What metric will confirm the fix worked? Define before shipping. +9. Hand off. Output feeds the development backlog and `seo-audit-orchestration`. +10. Re-crawl after fixes. Confirm resolution. Update the backlog. + +--- + +## High-leverage clusters worth looking for + +These patterns commonly produce outsized impact when fixed: + +- Wholesale redirect chain cleanup. One sitemap update plus internal link updates can resolve thousands of "redirect chain" issues at once. +- Accidental noindex on a template. A single line of code change can re-index hundreds or thousands of pages. +- Sitemap freshness pipeline. A broken sitemap regeneration job affects every issue that depends on Search Console seeing the right URLs. +- Canonical inconsistencies on faceted navigation. A template-level canonical fix can resolve duplicate content issues across an entire ecommerce category tree. +- Robots.txt restored. A reverted production robots.txt can recover a sitewide drop in days. +- Hreflang block fix. One template change resolves hreflang issues across the whole multilingual site. +- Image optimization at the asset pipeline. Fixing the build process resolves thousands of individual asset issues. + +When you spot one of these, prioritize even if individual issues look small. The cluster impact is large. + +--- + +## Failure patterns + +- Severity worship. Treating every "critical" label as truly critical. Many are not. Triage by mechanism and traffic impact. +- Counting issues. Reporting "we fixed 1,200 issues" without showing traffic or ranking impact wastes engineering credibility. +- Skipping the tiering. Fixing 100 Tier-3 issues before 5 Tier-1 issues is busy work. +- Single-issue fixes. Most issues come in clusters. Fixing one redirect chain when 800 share the same root cause is the wrong unit of work. +- No re-crawl. "Fixed" without verification leaves doubt. Always re-crawl after major fixes. +- Ignoring Search Console. Ahrefs sees what its crawler finds. Search Console reflects what Google actually sees and indexes. Use both. +- Treating Core Web Vitals like a checklist. CWV is field data, not lab data. Optimize for real-user experience, not synthetic scores. +- Fixing low-mechanism issues for show. A clean technical report with no traffic gain helps no one. +- Not measuring. Define the metric that proves the fix worked before fixing. + +--- + +## Output format + +A site health triage document with: + +1. Summary. Total issues, top 3 fix clusters, expected impact. +2. URL tiering. How URLs were classified and counts per tier. +3. Issue categorization. Counts by mechanism category, by tier, by priority band. +4. Prioritized backlog. P0-P3 ordered. Each item has: issue, affected URLs, fix description, effort, expected impact, owner. +5. Fix clusters. Groups of issues that share a fix. Highest leverage at the top. +6. Measurement plan. Per fix or cluster, what proves it worked. +7. Methodology. Crawler used, date, scope, caveats. + +Length: 5-12 pages plus a backlog spreadsheet. + +--- + +## Reference files + +- [`references/issue-impact-table.md`](references/issue-impact-table.md) - Mapping table of common crawler issues to mechanism impact and typical fix effort, plus the triage matrix in detailed form. diff --git a/skills/seo-site-health-audit/references/issue-impact-table.md b/skills/seo-site-health-audit/references/issue-impact-table.md new file mode 100644 index 0000000..672e1b0 --- /dev/null +++ b/skills/seo-site-health-audit/references/issue-impact-table.md @@ -0,0 +1,190 @@ +# Issue impact table + +A reference table mapping common crawler-reported issues to their actual SEO impact mechanism and typical fix effort. Use it to triage Ahrefs Site Audit (or any equivalent) findings without treating every "critical" label as equally important. + +--- + +## How to use + +For each issue type from the crawler: + +1. Look up the mechanism and effort here. +2. Combine with URL tier (Tier 1 = top 10% by traffic) using the triage matrix. +3. Assign priority band P0-P3 or Park. + +Mechanism tiers: + +- HIGH: Direct effect on indexing, rankings, or Core Web Vitals. +- MEDIUM: Indirect effect via crawl, equity flow, or user signals. +- LOW: Best practice nudge or cosmetic. Real impact is usually marginal. + +--- + +## Indexability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Page returns noindex on indexed URL \| HIGH \| S \| Template fix usually resolves at scale \| +\| Robots.txt blocks important URLs \| HIGH \| S \| One file edit \| +\| X-Robots-Tag header set to noindex \| HIGH \| S-M \| Often a CDN or hosting config \| +\| Canonical points to non-canonical URL \| HIGH \| M \| Often template-level \| +\| Canonical points to redirect \| HIGH \| S \| Update canonical to final URL \| +\| Self-canonical missing on important page \| MEDIUM \| S \| Add to template \| +\| URL not in sitemap but indexed \| MEDIUM \| S \| Regenerate sitemap \| +\| URL in sitemap but noindexed \| HIGH \| S \| Decide indexability, fix one or the other \| + +--- + +## Crawlability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| 5xx errors on URLs \| HIGH \| M-L \| Investigate hosting and app errors \| +\| 4xx errors on internally linked URLs \| HIGH \| M \| Fix links or add redirects \| +\| Redirect chain (3+ hops) \| MEDIUM \| M \| Update final destination in links \| +\| Redirect loop \| HIGH \| S \| Fix immediately \| +\| Slow time to first byte \| MEDIUM \| M-L \| Hosting, caching, or app changes \| +\| Crawl trap (infinite parameter combinations) \| HIGH \| M \| Robots disallow patterns or canonical \| +\| Orphan page (indexed but no internal links) \| MEDIUM \| S-M \| Add internal links or noindex \| +\| Excessive redirects in sitemap \| MEDIUM \| S \| Update sitemap to final URLs \| +\| 301 used where 302 intended (or vice versa) \| LOW-MEDIUM \| S \| Audit and fix per case \| + +--- + +## Renderability issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Critical content rendered only via JS (with crawler issues) \| HIGH \| L \| Server render, prerender, or hybrid \| +\| Blocked CSS or JS resources \| MEDIUM \| S \| Allow in robots.txt \| +\| Excessive client-side dependencies for above-fold content \| MEDIUM \| M-L \| Code splitting and SSR \| +\| Render mismatch (HTML differs from rendered DOM in important ways) \| HIGH \| M-L \| Investigate framework rendering \| + +--- + +## Core Web Vitals (field data) + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| LCP > 4 seconds (poor band) on Tier 1 pages \| HIGH \| M-L \| Image optimization, caching, render path \| +\| LCP 2.5-4 seconds (needs improvement) \| MEDIUM \| M \| Lower priority but still worth fixing \| +\| INP > 500ms (poor band) \| HIGH \| M-L \| JS optimization, hydration deferral \| +\| CLS > 0.25 (poor band) \| HIGH \| S-M \| Reserve space for images, ads, embeds \| +\| CLS 0.1-0.25 \| LOW-MEDIUM \| S \| Often quick wins \| + +CWV thresholds are based on the 75th percentile of real-user data per URL group. + +--- + +## Structured data issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Schema error blocking rich result eligibility \| HIGH \| S-M \| Fix the offending field \| +\| Schema warning (recommended field missing) \| LOW \| S \| Optional improvement \| +\| Wrong schema type for content \| MEDIUM \| S \| Replace with correct type \| +\| Schema markup but content does not match \| HIGH \| M \| Either fix schema or fix content (Google penalizes mismatch) \| +\| Duplicate schema across multiple types \| LOW-MEDIUM \| S \| Clean up duplicates \| + +Pages eligible for rich results (FAQ, How-to, Recipe, Product, etc.) deserve high priority. Schema on pages without rich result eligibility is lower priority. + +--- + +## Internal link integrity + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Internal link to 404 \| MEDIUM \| S \| Update or remove link \| +\| Internal link to redirect \| LOW \| S \| Update to final URL when batching \| +\| Internal link with empty anchor \| LOW \| S \| Add descriptive anchor \| +\| Page receiving zero internal links (orphan) \| MEDIUM \| S-M \| Add links or reassess if page should exist \| +\| Important page with very few internal links \| MEDIUM \| S \| Identify and add link points \| +\| Footer or sitewide internal link to broken URL \| MEDIUM \| S \| High visibility, fix quickly \| + +--- + +## Hreflang (multilingual sites) + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing return tag (hreflang reciprocity) \| HIGH \| M \| Template fix often resolves at scale \| +\| Hreflang points to redirected URL \| MEDIUM \| S \| Update to final URL \| +\| Hreflang points to noindexed URL \| HIGH \| S \| Decide indexability or remove hreflang \| +\| Hreflang language code malformed \| HIGH \| S \| Use ISO 639-1 + ISO 3166-1 alpha-2 \| +\| Mixing x-default and specific tags incorrectly \| MEDIUM \| S \| Audit pattern across site \| + +Multilingual sites with broken hreflang often see the wrong locale rank in the wrong market. Real ranking impact. + +--- + +## On-page elements + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing title tag \| MEDIUM \| S \| Add via template \| +\| Duplicate title tag across many pages \| MEDIUM \| S-M \| Template fix or unique-by-default \| +\| Missing meta description \| LOW \| S \| Affects CTR, not ranking \| +\| Duplicate meta descriptions \| LOW \| S \| Affects CTR, not ranking \| +\| Missing H1 on Tier 1 page \| MEDIUM \| S \| Add to template \| +\| Missing H1 on Tier 3 page \| LOW \| S \| Park unless trivial to fix \| +\| Multiple H1s \| LOW \| S \| Modern HTML allows; rarely a real issue \| +\| Title or H1 that does not match content topic \| MEDIUM \| S \| Audit content and update \| + +--- + +## Image issues + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Missing alt text on content images \| LOW (SEO), HIGH (accessibility) \| S \| Important for accessibility regardless \| +\| Missing alt text on decorative images \| LOW \| S \| Use empty alt="" \| +\| Image weight (large file size) on Tier 1 page \| HIGH \| M \| Asset pipeline fix at scale \| +\| Image format not modern (no WebP/AVIF) \| MEDIUM \| M \| Pipeline change \| +\| Image lazy loading missing \| MEDIUM \| S \| Add `loading="lazy"` to off-screen images \| +\| Hero image lazy loaded \| MEDIUM \| S \| Should be `loading="eager"` for LCP \| + +--- + +## Security and trust + +\| Issue \| Mechanism \| Typical effort \| Notes \| +\| --- \| --- \| --- \| --- \| +\| Mixed content (HTTPS page loading HTTP resources) \| MEDIUM \| S \| Update resource URLs \| +\| Expired or misconfigured SSL \| HIGH \| S \| Fix immediately \| +\| HSTS missing \| LOW \| S \| Best practice \| +\| Internal links use HTTP, page is HTTPS \| LOW \| S \| Update links to relative or HTTPS \| + +--- + +## Cluster opportunities + +When you see multiple issues from the same root cause, treat as one fix: + +\| Cluster signal \| Single fix \| +\| --- \| --- \| +\| Hundreds of "redirect chain" warnings \| Update internal links and sitemap to final URLs \| +\| Sitewide "missing canonical" \| Add canonical to base template \| +\| Mass "noindex on indexable URL" \| Audit template-level meta tag \| +\| Many "page not in sitemap" \| Regenerate sitemap from canonical URL list \| +\| Many slow LCP pages with same image pattern \| Optimize image pipeline once \| +\| Many hreflang errors with same pattern \| Template-level hreflang fix \| +\| Many H1 issues on archive pages \| Theme or template change \| + +Always look for clusters before fixing one-off. Cluster fixes are 10-100x more efficient. + +--- + +## Park or skip + +These rarely deserve dedicated work even when flagged: + +- Title tag length warnings (within reason; only fix if truncation visibly hurts CTR on a Tier 1 page) +- Meta description length warnings (same logic) +- "URL contains uppercase" if redirects already handle it +- "URL contains underscore" if URLs are stable and ranking +- Trailing slash inconsistency if redirects handle it +- Schema warnings (not errors) on pages with no rich result eligibility +- HTML validation issues that do not affect rendering or indexing +- Old browser-specific issues (IE-era) + +Park them. Document why. Move on. diff --git a/skills/seo-technical/SKILL.md b/skills/seo-technical/SKILL.md new file mode 100644 index 0000000..ef9c358 --- /dev/null +++ b/skills/seo-technical/SKILL.md @@ -0,0 +1,154 @@ +--- +name: seo-technical +description: "Run a comprehensive technical SEO audit covering crawlability, indexability, rendering, site architecture, structured data, page experience, security, and internationalization. Use this skill whenever the user asks about technical SEO, crawl issues, indexing problems, sitemaps, robots.txt, canonical tags, schema markup, page speed, Core Web Vitals, hreflang, redirects, or site-wide search performance. Triggers on technical SEO, site audit, crawlability, indexability, sitemap, robots.txt, canonical, redirect chain, schema, JSON-LD, Core Web Vitals, page speed, hreflang, mobile usability, HTTPS, security headers, render-blocking, JavaScript SEO. Also triggers when a site has indexing problems, traffic drops, or migration concerns, even if 'technical SEO' is not said explicitly." +category: seo-foundation +catalog_summary: "Crawlability, indexability, rendering, schema, page experience" +display_order: 2 +--- + +# Technical SEO + +Audit and fix the layer beneath the content: how search engines crawl, render, index, and trust a site. Stack-agnostic. + +--- + +## When to use + +- Site-wide audit before or after a migration +- Investigating indexing or ranking drops +- Setting up SEO foundations on a new site +- Auditing Core Web Vitals or page experience signals +- Fixing crawl waste, redirect chains, or canonical issues +- Setting up multilingual or multi-regional sites + +## When NOT to use + +- Single-page on-page optimization (use `seo-onpage`) +- Keyword strategy or content planning (use `seo-keyword`) +- Competitor backlink or SERP analysis (use `seo-competitor`) +- Pure performance optimization without SEO context (use `performance-optimization`) + +--- + +## Required inputs + +- The site URL or staging URL +- Access to (at minimum) view the rendered HTML, robots.txt, and sitemap +- Ideally: search console access, server logs, and a crawler + +If the site is large (10K+ URLs), confirm whether the audit is a full crawl or a sample. + +--- + +## The framework: 6 layers + +Technical SEO has six layers, stacked. A failure in a lower layer breaks everything above it. + +### 1. Crawlability +Can search engines access the URLs? + +- robots.txt does not block important paths +- No accidental `noindex` on indexable pages +- No accidental `disallow` patterns blocking CSS or JS (rendering breaks) +- Sitemap is present, returns 200, and lists canonical URLs only +- Sitemap is referenced in robots.txt +- No infinite spaces (faceted nav generating endless URLs) +- Crawl budget is not wasted on low-value URLs + +### 2. Indexability +Of crawlable URLs, which should be indexed? + +- One canonical URL per piece of content (no duplicates) +- Canonical tags self-reference on canonical pages +- `noindex` on staging, search results, filter pages, thank-you pages, internal admin +- No mixed signals (canonical pointing one way, sitemap another, internal links a third) +- Pagination handled correctly (rel=next/prev is deprecated, but consistent canonicals matter) +- Parameter handling deliberate (UTM, session IDs, sort orders) + +### 3. Rendering +Does the rendered HTML match what crawlers see? + +- Critical content visible without JavaScript (or properly server-rendered) +- For SPAs: confirm Googlebot sees the rendered content (test with the URL Inspection tool) +- No cloaking (showing different content to bots vs users) +- Lazy-loaded content has proper loading attributes +- Hydration errors do not strip content from the rendered DOM + +### 4. Site architecture +Is the site structured for both users and crawlers? + +- Clear URL hierarchy that mirrors site structure +- Important pages reachable in 3 clicks or fewer from the homepage +- Internal linking distributes authority logically +- Breadcrumb navigation present and marked up with schema +- No orphan pages (pages with no internal links) +- No redirect chains (one redirect max) +- No 4xx errors on internally-linked URLs + +### 5. Structured data and signals +Does the site speak crawler language? + +- Schema.org markup on appropriate page types +- JSON-LD format (preferred over microdata) +- Validates in the Rich Results Test +- Organization or LocalBusiness schema on the homepage or about page +- BreadcrumbList schema on nested pages +- Author and publisher schema linked correctly on content pages +- llms.txt present at the root (for AI crawlers, see `seo-aeo-geo`) + +### 6. Page experience and security +Does the site meet the page experience baseline? + +- HTTPS on all pages, no mixed content +- HSTS header set +- Core Web Vitals pass (LCP, INP, CLS within thresholds) +- Mobile-friendly (responsive, no horizontal scroll, tap targets sized correctly) +- No intrusive interstitials on mobile +- Stable URL structure (no random URL changes between deploys) +- 404 pages return 404, not 200 with "page not found" content (soft 404) + +--- + +## Workflow + +1. Define scope. Whole site, a subfolder, a migration check, or a specific issue. +2. Confirm access. What can you actually see (HTML, robots, sitemap, search console, server logs, staging)? +3. Crawl. Use a crawler to enumerate URLs and statuses. Sample if the site is huge. +4. Run the 6-layer framework. Score each, note specific issues with example URLs. +5. Cross-reference. Search console for what's actually indexed. Compare to sitemap and crawl output. +6. Prioritize. Critical (blocks indexing or causes traffic loss), Important (suboptimal), Nice-to-have (polish). +7. Write the report. Use the template in [`references/audit-template.md`](references/audit-template.md). + +--- + +## Failure patterns + +- Optimizing rankings on a page that is `noindex`. Always check indexability before content work. +- Adding sitemaps without fixing canonical issues. A sitemap of duplicate URLs is worse than no sitemap. +- Blocking crawlers from CSS or JS. Breaks Google's rendering. Common in over-aggressive robots.txt files. +- Over-relying on canonical tags. Canonicals are hints, not directives. Use redirects when content actually moved. +- Migrating without a redirect map. Single biggest cause of post-migration traffic loss. +- Treating Core Web Vitals as the only ranking signal. Page experience matters but does not override relevance. + +--- + +## Output format + +Default output is a markdown audit at `seo-technical-audit.md`. Structure: + +1. Scope and methodology +2. Executive summary (3 to 5 critical findings) +3. 6-layer score +4. Critical issues (with example URLs) +5. Important issues +6. Nice-to-have polish +7. Implementation roadmap (sequenced) + +For migrations, include a redirect map as a CSV alongside the report. + +--- + +## Reference files + +- [`references/audit-template.md`](references/audit-template.md) - Fillable technical SEO audit template. +- [`references/migration-checklist.md`](references/migration-checklist.md) - Pre and post-migration checklist (covers the highest-risk scenario). diff --git a/skills/seo-technical/references/audit-template.md b/skills/seo-technical/references/audit-template.md new file mode 100644 index 0000000..a424d3f --- /dev/null +++ b/skills/seo-technical/references/audit-template.md @@ -0,0 +1,321 @@ +# Technical SEO Audit Template + +Fillable template for a technical SEO audit. The audit covers crawlability, indexability, rendering, schema, page experience, and site architecture. + +The output is a stakeholder-readable report plus a prioritized backlog. For migration scenarios specifically, also use `migration-checklist.md`. + +--- + +## Audit metadata + +Site: [Domain] +Pages audited: [Sample size and selection method] +Audit date: [YYYY-MM-DD] +Auditor: [Name] +Tools used: [Crawler, GSC, log analyzer, Lighthouse, schema validator, etc.] + +--- + +## Executive summary + +Three to five sentences. Anyone reading only this section should know: + +1. The overall technical state. +2. The single biggest blocker. +3. The estimated traffic at risk if technical issues persist. +4. The recommended next move. +5. Estimated effort for the top fix. + +> [Summary] + +--- + +## 1. Crawlability + +Can search engines crawl the site? + +### Robots.txt + +- [ ] File exists at `/robots.txt` +- [ ] File is syntactically valid (test in GSC) +- [ ] Critical sections of the site are not accidentally disallowed +- [ ] Specific user agents are not blocked (`Googlebot`, `Bingbot`) +- [ ] Sitemap location is declared (`Sitemap: https://example.com/sitemap.xml`) + +### XML sitemap(s) + +- [ ] Sitemap exists and is reachable +- [ ] Sitemap is referenced in robots.txt +- [ ] Sitemap is submitted in Search Console +- [ ] Sitemap contains only canonical, indexable URLs +- [ ] Sitemap is updated automatically when content changes +- [ ] Sitemap is split if over 50,000 URLs or 50MB +- [ ] `lastmod` reflects the actual last meaningful update (not the build date) + +### Internal linking + +- [ ] No important pages are orphaned (zero internal inlinks) +- [ ] Crawl-discoverable from the homepage within 4 clicks +- [ ] No internal links go to redirected URLs +- [ ] No internal links go to broken URLs (404) +- [ ] Anchor text is descriptive (avoid "click here," "read more") +- [ ] No `nofollow` or `noindex` on important internal pages + +### Crawl budget + +- [ ] Log analysis confirms Googlebot reaches the important sections regularly +- [ ] No crawl traps (calendar pages, infinite faceted nav, session ID parameters) +- [ ] Faceted nav uses `noindex,follow` or controlled parameter handling +- [ ] No duplicate URLs from URL parameter variations (UTMs, tracking, sort orders) +- [ ] Pagination handled with `rel="next"` and `rel="prev"` or paginated URL structure (no infinite scroll for important content) + +--- + +## 2. Indexability + +Can search engines index the site? + +### Index status + +- [ ] GSC "Indexed" count matches expected (production URL count) +- [ ] GSC "Not indexed" reasons are reviewed and addressed +- [ ] "Discovered - currently not indexed" pages are not high-value (or are addressed) +- [ ] "Crawled - currently not indexed" pages are not high-value (or are addressed) + +### Index directives + +- [ ] No `<meta name="robots" content="noindex">` on important pages +- [ ] No `X-Robots-Tag: noindex` HTTP header on important pages +- [ ] Staging or dev environments are noindexed (and not bypassable) +- [ ] Login pages, internal search results, and tag archives are noindex (or otherwise low-priority) + +### Canonicalization + +- [ ] Every page has a `rel="canonical"` tag +- [ ] Self-canonical URLs match the actual URL (no http/https mismatch, no trailing slash mismatch) +- [ ] Cross-canonical references point to indexable, live URLs +- [ ] Pagination uses self-canonicals (not pointing to page 1) +- [ ] No conflicting signals (canonical to URL A, redirect to URL B) + +### Status codes + +- [ ] 200 for live pages +- [ ] 301 for permanently moved pages +- [ ] 302 used only for genuinely temporary redirects +- [ ] 404 for genuinely missing pages (with helpful 404 page) +- [ ] 410 for intentionally removed pages +- [ ] 5xx errors investigated and resolved + +### Redirect chains + +- [ ] No redirect chains over 1 hop (A → B is fine; A → B → C → D is not) +- [ ] No redirect loops +- [ ] HTTPS redirect from HTTP is single-hop +- [ ] Trailing-slash redirect is single-hop + +--- + +## 3. Rendering + +Can search engines render JavaScript-dependent content? + +### Rendering strategy + +- [ ] Critical content is in the initial HTML response (server-rendered or static) +- [ ] If JS-rendered, "fetch as Google" via URL Inspection in GSC shows full content +- [ ] No reliance on user interaction to load primary content (no "click to load article") + +### Specific rendering risks + +- [ ] No JS-rendered title tags or meta descriptions (these often fail to be picked up) +- [ ] No JS-injected canonical tags +- [ ] Lazy-loaded images use native `loading="lazy"` or proper IntersectionObserver implementation +- [ ] Lazy-loaded content above the fold is not lazy-loaded +- [ ] CSS is not blocking critical content rendering + +### JavaScript SEO sanity check + +- [ ] Disable JS in DevTools and reload key pages. Critical content should still appear. +- [ ] Use the URL Inspection tool in GSC and view the rendered HTML. Compare to user-rendered version. + +--- + +## 4. Schema and structured data + +- [ ] Pages have appropriate schema (Article, Product, Organization, BreadcrumbList, FAQ, HowTo, Recipe, etc.) +- [ ] Schema validates in Google's Rich Results Test +- [ ] Schema validates in Schema.org validator +- [ ] No schema violations in GSC enhancement reports +- [ ] BreadcrumbList schema implemented (often-overlooked CTR boost) +- [ ] Organization schema on the homepage +- [ ] WebSite schema with SearchAction (enables sitelinks search box) +- [ ] No schema for content not visible on the page + +--- + +## 5. Page experience + +### Core Web Vitals + +Field data preferred (CrUX, RUM). Lab data is a fallback diagnostic. + +\| Metric \| Target \| Mobile p75 \| Desktop p75 \| Status \| +\|---\|---\|---\|---\|---\| +\| LCP \| < 2.5s \| \| \| \| +\| INP \| < 200ms \| \| \| \| +\| CLS \| < 0.1 \| \| \| \| + +For detailed performance audit, see `performance-optimization` skill. + +### HTTPS + +- [ ] Entire site served over HTTPS +- [ ] No mixed content warnings +- [ ] HSTS header set +- [ ] Certificate valid and not approaching expiry + +### Mobile + +- [ ] Responsive (single URL, single HTML, CSS adapts) +- [ ] Mobile usability passes in GSC +- [ ] No tap targets too close together +- [ ] Viewport meta tag set + +### Safe browsing + +- [ ] No security warnings in GSC +- [ ] No malware or phishing flags + +--- + +## 6. International SEO + +If the site is multilingual or multi-region: + +- [ ] `hreflang` tags present and correct on every locale alternate +- [ ] `hreflang` includes self-reference +- [ ] `x-default` set for language picker fallback +- [ ] Language and region codes follow ISO standards +- [ ] No hreflang errors in GSC International Targeting report +- [ ] URL structure follows a consistent pattern (subdir / subdomain / ccTLD) + +--- + +## 7. Site architecture and URLs + +### URL hygiene + +- [ ] URLs are lowercase +- [ ] URLs use hyphens, not underscores or spaces +- [ ] URLs are short and descriptive +- [ ] No session IDs or tracking parameters in canonical URLs +- [ ] URL structure reflects content hierarchy (category → subcategory → page) + +### Trailing slash + +- [ ] Consistent trailing slash policy (with or without) +- [ ] One version redirects to the other (no duplicates) + +### Subdomains vs subdirectories + +- [ ] Strategic decision documented (subdir typically pools authority better; subdomain better for separate sites) +- [ ] `www` and non-`www` consolidated via 301 + +--- + +## 8. Search Console hygiene + +- [ ] Both `https://www` and `https://` (and `http://` versions) verified as separate properties +- [ ] Domain property verified (the recommended approach) +- [ ] Sitemap submitted and showing "Success" +- [ ] No critical issues in Coverage report +- [ ] No manual actions or security issues +- [ ] Crawl stats reviewed (sudden drops or spikes investigated) + +--- + +## 9. Log file analysis (advanced) + +For larger sites, server logs reveal what crawlers actually do, vs what the site allows. + +- [ ] Top crawled pages match top-priority pages +- [ ] Googlebot does not waste crawl on noindex / parameter / faceted URLs +- [ ] No orphaned pages getting crawler traffic +- [ ] No 5xx errors served to Googlebot + +--- + +## Findings summary + +\| Severity \| Issue \| Pages affected \| Recommended fix \| Effort \| +\|---\|---\|---\|---\|---\| +\| P0 (blocking) \| \| \| \| \| +\| P1 (high) \| \| \| \| \| +\| P2 (medium) \| \| \| \| \| +\| P3 (low) \| \| \| \| \| + +### Severity definitions + +- P0: Critical content cannot be crawled or indexed; major technical errors causing exclusion from search. +- P1: Significant indexability or rendering issues affecting traffic; broken canonicals; large redirect chains. +- P2: Suboptimal but not blocking; missing schema, suboptimal sitemap, partial CWV failures. +- P3: Polish; minor inefficiencies, documentation gaps. + +--- + +## Recommendations + +### Now (this week) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Next (this sprint or month) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| +\| 2 \| \| \| \| \| + +### Later (this quarter) + +\| # \| Recommendation \| Owner \| Estimated impact \| Effort \| +\|---\|---\|---\|---\|---\| +\| 1 \| \| \| \| \| + +--- + +## Monitoring after fixes ship + +- [ ] GSC Coverage report rechecked weekly until stable +- [ ] Position tracking for top queries to confirm no regression +- [ ] Log analysis re-run 2-4 weeks after fixes ship +- [ ] CWV field data tracked for affected page templates +- [ ] Set alerts for: 5xx errors, sudden index drops, certificate expiry + +--- + +## Open questions + +- [ ] [Question] +- [ ] [Question] + +--- + +## Appendix: methodology + +- Crawl tool config: [tool, depth, render mode, user agent] +- Sample selection: [How URLs were selected for deep review] +- Field data window: [Date range] +- Caveats: [What this audit did not cover] + +--- + +## Sign-off + +Audit conducted by: [Name, date] +Reviewed with: [Stakeholders] +Implementation owner: [Name] +Re-audit scheduled: [Date] diff --git a/skills/seo-technical/references/migration-checklist.md b/skills/seo-technical/references/migration-checklist.md new file mode 100644 index 0000000..c812907 --- /dev/null +++ b/skills/seo-technical/references/migration-checklist.md @@ -0,0 +1,118 @@ +# Migration Checklist + +A site migration (domain change, platform change, URL restructure, HTTPS move) is the single highest-risk SEO event. Follow this checklist to avoid the typical 30 to 70 percent traffic loss most migrations cause. + +--- + +## Pre-migration (T minus 30 days) + +### Document the current state +- [ ] Crawl the entire current site, save URL list +- [ ] Export top 1000 organic landing pages from search console (last 12 months) +- [ ] Export top 1000 organic queries from search console +- [ ] Note current rankings for the top 50 commercial queries +- [ ] Save current XML sitemap +- [ ] Save current robots.txt +- [ ] Document current schema implementation +- [ ] Screenshot current SERP appearance for top 10 queries + +### Plan the new structure +- [ ] Map every old URL to its new URL (redirect map) +- [ ] Confirm every important URL has a destination (no orphan redirects) +- [ ] Decide on canonical URL structure (trailing slash, www vs non-www, http to https) +- [ ] Plan handling of parameter URLs (UTM, sort, filter) +- [ ] Plan handling of pagination +- [ ] Plan internal linking structure (avoid relying on redirects) + +### Build and stage +- [ ] Set staging environment to `noindex` +- [ ] Block staging from search engines via robots.txt and HTTP auth +- [ ] Build redirect logic for the redirect map +- [ ] Implement the new sitemap +- [ ] Implement schema on all page types +- [ ] Verify Core Web Vitals on staging +- [ ] Test mobile usability on staging +- [ ] Test HTTPS configuration (HSTS, no mixed content) + +--- + +## Migration day + +### Just before cutover +- [ ] Final crawl of the production site (baseline for comparison) +- [ ] Final export of indexed URL list from search console +- [ ] Confirm DNS TTLs lowered if changing hosts (24 to 48 hours prior) +- [ ] Backup the current site fully +- [ ] Communicate the migration window to stakeholders + +### During cutover +- [ ] Deploy the new site +- [ ] Confirm 301 redirects firing for old URLs (test 20 random samples) +- [ ] Remove `noindex` from new site +- [ ] Update robots.txt on new site (allow crawling) +- [ ] Submit new sitemap in search console +- [ ] Submit change of address (if domain changed) +- [ ] Update canonical references on the new site + +### Within 24 hours of cutover +- [ ] Crawl the new site, compare to baseline +- [ ] Spot-check 50 redirected URLs end-to-end +- [ ] Verify search console shows the new sitemap as processed +- [ ] Check for unexpected 4xx or 5xx errors in server logs +- [ ] Submit top 20 priority URLs for re-indexing + +--- + +## Post-migration (T plus 1 to 30 days) + +### Week 1 +- [ ] Daily check on indexed page count in search console +- [ ] Daily check on crawl errors +- [ ] Daily check on average position for top 50 queries +- [ ] Verify no traffic anomalies in analytics +- [ ] Fix any redirect loops or chains identified in logs + +### Week 2 to 4 +- [ ] Verify all old URLs redirecting to new URLs (full crawl) +- [ ] Verify no redirect chains (max one hop) +- [ ] Verify schema validates on key page types +- [ ] Check Core Web Vitals trend (any regressions vs pre-migration) +- [ ] Update external backlinks where feasible (highest-value links first) +- [ ] Check social media platforms display new URLs correctly + +### Month 2 +- [ ] Compare organic traffic to pre-migration baseline +- [ ] Compare keyword rankings to pre-migration baseline +- [ ] Note any pages that lost rankings, investigate +- [ ] Begin pruning redirect rules for URLs that no longer receive traffic (after 90 days minimum) + +--- + +## Common migration failures (and how to prevent each) + +\| Failure \| Prevention \| +\|---\|---\| +\| Old URLs returning 404 \| Comprehensive redirect map, tested before cutover \| +\| Redirect chains (2+ hops) \| Direct redirect old → new, never old → middle → new \| +\| Lost rankings on key pages \| Same content, same intent, same internal linking on new pages \| +\| Crawl waste from old parameters \| Clean URL structure, parameter handling rules \| +\| Mixed HTTPS and HTTP content \| Audit all asset URLs, force HTTPS via HSTS \| +\| Search console disconnect \| Verify both old and new properties, submit change of address \| +\| Sitemap mismatch \| New sitemap lists new canonical URLs only, no legacy URLs \| +\| Hreflang breaks (international sites) \| Map hreflang to new URLs, preserve language pair relationships \| + +--- + +## Recovery if traffic drops + +If organic traffic drops more than 20 percent within 14 days: + +1. Verify all critical URLs return 200 or 301 (no 404 or 500) +2. Verify search console is processing the new sitemap +3. Spot-check top 50 lost-traffic URLs for content parity (does the new page actually answer the same query?) +4. Check robots.txt and meta robots for accidental noindex +5. Check for hreflang errors if international +6. Submit affected URLs for re-indexing manually +7. Audit internal linking - are key pages still well-linked? + +Most migration drops recover within 60 to 90 days IF the redirect map is complete and the content is preserved. If not recovering by day 90, the issue is structural and needs deeper investigation. diff --git a/skills/seo-traffic-diagnosis/SKILL.md b/skills/seo-traffic-diagnosis/SKILL.md new file mode 100644 index 0000000..cd5c87b --- /dev/null +++ b/skills/seo-traffic-diagnosis/SKILL.md @@ -0,0 +1,180 @@ +--- +name: seo-traffic-diagnosis +description: "Diagnose organic traffic changes (drops, stalls, or unexpected wins) using Ahrefs MCP plus Search Console data. Use this skill when traffic suddenly dropped, has been flat despite investment, after an algorithm update, after a migration or deploy, or when a competitor seems to be taking share. Triggers on traffic dropped, traffic decline, traffic stalled, organic decline, lost rankings, why is traffic down, algorithm update, post-migration traffic loss, traffic diagnosis. Also triggers when stakeholders are panicking about analytics." +category: seo-audit-suite +catalog_summary: "Diagnose drops, stalls, or wins via 5-layer root cause analysis" +display_order: 5 +--- + +# SEO Traffic Diagnosis + +Diagnose why organic traffic moved (down, flat, or unexpectedly up) using Ahrefs MCP combined with Search Console and analytics data. Stack-agnostic. Produces a root-cause diagnosis and an action plan. + +--- + +## When to use + +- Organic traffic dropped sharply +- Organic traffic has been flat for months despite content investment +- After a known Google algorithm update +- After a migration, replatform, or domain change +- After a deploy that touched routing, redirects, or rendering +- When a competitor is visibly taking organic share +- When a single page dropped from a ranked position +- When stakeholders need an explanation, fast + +## When NOT to use + +- Routine performance reporting (use `analytics-strategy`) +- Pre-emptive content planning (use `seo-content-gap-audit`) +- Backlink-only investigations (use `seo-backlink-audit`) +- Technical issue triage outside of traffic concerns (use `seo-site-health-audit`) + +--- + +## Required inputs + +- Description of the symptom (what changed, when, magnitude) +- Date the change started (best estimate) +- Recent SEO history: deploys, migrations, content changes, link campaigns +- Access to Ahrefs MCP, Search Console, and analytics +- Confirmation the change is real (not a tracking artifact) + +--- + +## The framework: 5 layers of diagnosis + +A traffic change has one or more root causes. Move through the layers in order. Stop when you have enough evidence. + +### Layer 1: Confirm the change is real + +Before diagnosing, rule out: + +- Tracking gaps (analytics outages, tag manager issues) +- Bot traffic changes +- Reporting comparison errors (different date ranges, wrong segment) +- Seasonality (compare year-over-year, not just month-over-month) +- Holiday or weekday effects + +Cross-check Search Console clicks against analytics organic sessions. Significant divergence often points to a tracking issue, not a real traffic change. + +### Layer 2: Localize the change + +Where is the change happening? + +Segment by: + +- Country and language +- Device (mobile, desktop, tablet) +- Page or section (homepage, blog, product, category) +- Query type (branded vs non-branded) +- Landing page + +A change in one segment requires different diagnosis than a change everywhere. + +\| Pattern \| Likely cause \| +\| --- \| --- \| +\| One country dropped \| Local algorithm update, hreflang issue, geo redirect issue \| +\| Mobile dropped, desktop flat \| Mobile usability or page speed regression \| +\| One section dropped \| Topical algorithm update or section-specific quality issue \| +\| Branded queries dropped \| Brand-level issue: site outage, reputation, manual action \| +\| Non-branded dropped \| Algorithmic ranking issue \| +\| Single page dropped \| Page-level issue: content, technical, or competitive \| +\| Sitewide dropped \| Sitewide issue: penalty, technical, migration, or algorithm \| + +### Layer 3: Page-level analysis + +For affected pages, audit: + +- Position changes per ranked keyword (Ahrefs Rank Tracker history) +- SERP composition changes (more ads, AI overviews, featured snippets, video) +- Click-through rate changes +- Index status (Search Console coverage) +- Crawl errors and accessibility +- Recent content changes +- Internal link changes +- Backlink changes (lost links, redirect chains) + +A page can lose traffic without losing rank if SERP composition changed. + +### Layer 4: Technical analysis + +Did anything break technically? + +Check: + +- Robots.txt changes +- Canonical tag changes +- Meta robots changes (accidental noindex) +- Redirect chains and loops +- Render issues (especially for JS-heavy frameworks) +- Site speed regressions +- Hreflang errors +- Sitemap freshness +- HTTP status codes (4xx, 5xx spikes) +- Server log evidence of crawl behavior changes + +Recent deploys are the prime suspect. Compare deploy dates to traffic change dates. + +### Layer 5: External analysis + +If layers 1-4 do not explain the change, look outward. + +- Algorithm update calendar (cross-reference timing) +- Competitor moves (new content, new SERP features they captured) +- Industry trend (declining search demand for the topic) +- Manual action (Search Console security and manual actions) +- Negative SEO (sudden link velocity changes) + +External-factor diagnosis benefits from competitive context: did your traffic drop while competitors held steady (suggests an algorithm-specific issue), or did the entire vertical lose ground (suggests a user-behavior shift)? Similarweb shows competitor traffic trends; Ahrefs shows competitor SERP movement; pairing both surfaces whether the issue is yours alone or the category's. + +--- + +## Workflow + +1. Confirm the symptom. Get exact dates, magnitude, segment if known. +2. Validate the data. Layer 1 checks. Rule out tracking and seasonality. +3. Localize. Layer 2. Segment until the pattern is clear. +4. Page-level dive. Layer 3 on the most affected pages. +5. Technical check. Layer 4. Recent deploys, robots, canonicals, redirects. +6. External check. Layer 5. Algorithm updates, competitors, industry. +7. Build the hypothesis. State the cause as a single sentence. +8. Validate the hypothesis. Find the evidence that confirms or refutes it. See [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md). +9. Action plan. Specific fixes mapped to specific evidence. +10. Communicate. Write up the diagnosis. Stakeholders want clarity, not exhaustive analysis. + +--- + +## Failure patterns + +- Jumping to algorithm update. "It must be the algorithm" is the lazy answer. Eliminate technical and page-level causes first. +- Solving the wrong problem. A drop diagnosed as "content quality" when the real cause was an accidental noindex on a deploy. Validate the hypothesis before fixing. +- No baseline for "normal." Without a baseline, every fluctuation looks alarming. Establish what normal noise looks like before reacting. +- Treating one page as the site. Site-wide and page-level diagnoses are different. Confirm scope first. +- Ignoring branded vs non-branded. A drop in branded queries means a brand-level problem. A drop in non-branded means an SEO problem. Different teams own them. +- Comparing wrong date ranges. Comparing 28 days to the previous 28 days during a holiday distorts the picture. Use year-over-year for seasonal businesses. +- Stopping at correlation. A deploy and a drop on the same day is a strong correlation, not proof. Find the mechanism. +- Single-source diagnosis. Ahrefs sees position. Search Console sees clicks and queries. Analytics sees behavior. Logs see crawl. Use them together. +- Premature reassurance. Telling stakeholders "it is just an algorithm update, will recover" without evidence sets up a worse conversation later. + +--- + +## Output format + +A diagnosis document with: + +1. Summary. What changed, when, magnitude, root cause in one paragraph. +2. The symptom. Charts and segment breakdowns. +3. Layer-by-layer findings. What each layer ruled in or out. +4. Root cause hypothesis. Single statement with evidence. +5. Action plan. Ordered fixes with owners and timelines. +6. Recovery forecast. Realistic expectations on timeline and ceiling. +7. Monitoring plan. What to watch for confirmation of recovery. + +Length: 4-10 pages. Stakeholders read this fast. + +--- + +## Reference files + +- [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md) - Layer-by-layer diagnostic checklist with the specific data to pull at each layer and how to interpret each signal. diff --git a/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md b/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md new file mode 100644 index 0000000..2895ed3 --- /dev/null +++ b/skills/seo-traffic-diagnosis/references/diagnosis-checklist.md @@ -0,0 +1,209 @@ +# Diagnosis checklist + +A layer-by-layer checklist for diagnosing organic traffic changes. Use it after the symptom is confirmed real and you need to narrow root cause. + +--- + +## Layer 1: Confirm the change is real + +### Pulls + +- Search Console clicks and impressions (last 90 days, day-by-day) +- Analytics organic sessions (matching window) +- Year-over-year same-period comparison +- Bot or crawler traffic if filterable + +### Checks + +- [ ] Date range comparison is apples to apples +- [ ] No tracking outage in analytics during the window +- [ ] No tag manager deploys during the window +- [ ] Search Console clicks and analytics organic sessions move together (within 10-20%) +- [ ] Year-over-year shows the same pattern (rules out seasonality) +- [ ] No major holiday or industry event explains the change + +If clicks and sessions diverge significantly: the issue may be tracking, not traffic. +If year-over-year shows the same pattern: the change is seasonal, not anomalous. + +--- + +## Layer 2: Localize the change + +### Pulls + +- Search Console: clicks segmented by country, device, query type, page +- Analytics: organic sessions segmented by landing page, country, device + +### Checks for each segment + +- [ ] One country dropped, others stable: local algorithm or geo issue +- [ ] One device dropped, others stable: device-specific issue +- [ ] One section dropped, others stable: section-specific quality or technical issue +- [ ] Branded queries dropped: brand-level issue +- [ ] Non-branded dropped: SEO ranking issue +- [ ] Single page dropped: page-level issue +- [ ] Everything dropped: sitewide issue + +### Decision + +Pick the dominant pattern. Carry the most affected segment into Layer 3. + +--- + +## Layer 3: Page-level analysis + +For each affected page or page cluster: + +### Pulls + +- Ahrefs: ranked keywords with current and historical positions +- Ahrefs: SERP overview for top 5-10 ranked keywords (current and from before the drop) +- Search Console: queries, impressions, clicks, position, CTR for each affected page +- Analytics: landing page sessions, conversion rate, bounce rate +- Index status in Search Console +- Recent edits to the page (CMS history) +- Internal links pointing to the page (Ahrefs Site Explorer) +- Backlinks to the page (Ahrefs) + +### Checks + +- [ ] Did position drop, or did position stay flat with CTR drop? +- [ ] Did the SERP composition change (new AI overviews, featured snippet steal, more ads, more video)? +- [ ] Are click-through rates lower than benchmarks for the position? +- [ ] Has the page been recently edited (intentionally or accidentally)? +- [ ] Has the page lost backlinks? +- [ ] Have internal links to the page decreased? +- [ ] Is the page indexed? + +### Interpretation + +\| Pattern \| Cause \| +\| --- \| --- \| +\| Position fell, SERP same \| Quality, freshness, or competitor improved \| +\| Position stable, CTR fell \| SERP feature change (snippet, AI overview, ads) \| +\| Position fell, SERP added new strong domain \| Competitor took share \| +\| Position fell after a CMS edit \| Recent edit broke something \| +\| Page deindexed \| Technical issue (robots, canonical, noindex) \| +\| Backlinks fell \| Link-based ranking signal decline \| +\| Internal links fell \| Internal link equity dilution \| + +--- + +## Layer 4: Technical analysis + +### Pulls + +- Robots.txt (current and historical via web archive if needed) +- Canonical tag check on affected pages +- Meta robots tag check on affected pages +- Redirect map for any URL changes +- HTTP status codes for affected URLs +- Sitemap freshness +- Hreflang implementation (multilingual sites) +- Server logs (Googlebot crawl behavior) +- Recent deploy log +- Recent infrastructure changes (CDN, DNS, hosting) + +### Checks + +- [ ] Robots.txt has not blocked anything new +- [ ] No accidental `noindex` on affected pages +- [ ] No accidental canonical to a different URL +- [ ] Redirects resolve in 1 hop with 301 status +- [ ] No 4xx or 5xx spikes for affected URLs +- [ ] Sitemap includes affected URLs and is current +- [ ] Hreflang is reciprocal and points to live URLs (multilingual) +- [ ] Googlebot is crawling at normal rates +- [ ] No deploy date matches the traffic drop date + +### Common technical regressions + +\| Symptom \| Likely cause \| +\| --- \| --- \| +\| Sudden full-site drop after a deploy \| Robots.txt blocked everything, accidental sitewide noindex, or routing broke \| +\| Pages return 404 or 410 \| URL structure changed, redirects missing \| +\| Pages return 5xx \| Server or hosting issue, possible CDN misconfiguration \| +\| Render mismatch \| JS rendering broke for crawlers (especially with framework upgrades) \| +\| Hreflang broken \| Cross-country traffic falls but other markets shift \| +\| Mass canonical change \| Pages canonicalized to wrong URLs after redesign \| + +--- + +## Layer 5: External analysis + +### Pulls + +- Algorithm update calendar (cross-reference traffic change date) +- Ahrefs SERP overview for affected keywords (looking for new ranking domains) +- Ahrefs competitor traffic estimates (their gain may be your loss) +- Search Console security and manual actions +- Backlink velocity changes (sudden gains or losses) +- News or industry trend search interest + +### Checks + +- [ ] No manual action notice in Search Console +- [ ] Drop date does not align with a known algorithm update +- [ ] No competitor has visibly taken share on affected keywords +- [ ] Industry-wide search demand for the topic has not shifted +- [ ] No spike in suspicious backlinks (negative SEO signal) +- [ ] No negative news or PR event affecting the brand + +### If layers 1-4 are clean + +- Drop on a known update date is likely algorithmic. Audit content quality and E-E-A-T signals. Recovery often takes the next update cycle. +- Drop with new dominant SERP domain is likely a competitive shift. Audit their content and update yours. +- Drop with industry-wide demand decline is not your fault. Manage stakeholder expectations. + +--- + +## Hypothesis statement template + +After working through the layers, state the hypothesis as a single sentence: + +``` +[Property] lost [magnitude] organic traffic starting [date] +because [root cause], +evidenced by [specific data points], +and recovery requires [specific actions] +with an expected timeline of [duration]. +``` + +Examples: + +> Site organic clicks dropped 35% starting March 12 because a deploy on March 11 added an accidental `noindex` meta tag sitewide, evidenced by Search Console coverage going from 2,400 indexed pages to 180 in 14 days, and recovery requires removing the noindex tag and resubmitting the sitemap with an expected timeline of 4-8 weeks. + +> Blog section organic clicks dropped 22% starting August 8 because Google rolled out a core update on that date that emphasizes E-E-A-T signals our author bylines lacked, evidenced by position drops on informational queries while transactional queries held, and recovery requires adding author E-E-A-T signals and improving content depth with an expected timeline of 1-2 update cycles (3-6 months). + +--- + +## When the diagnosis is unclear + +Sometimes the data points in multiple directions. In that case: + +1. State the top 2 hypotheses with evidence for each. +2. Recommend the lowest-risk action that helps in either case. +3. Identify the data that would distinguish the hypotheses. +4. Propose a monitoring plan to gather that data. + +Avoid forcing a clean conclusion when the evidence does not support one. Stakeholders prefer honest uncertainty to confident-but-wrong. + +--- + +## Communication template + +When delivering the diagnosis to stakeholders: + +``` +What happened: [1 sentence] + +Why it happened: [1 sentence] + +What we are doing: [3-5 specific actions] + +When to expect recovery: [timeline with confidence level] + +What to watch for: [leading indicators of recovery or further decline] +``` + +Stakeholders rarely want the layer-by-layer detail. They want clarity, accountability, and timeline. Keep the full diagnosis as an appendix. diff --git a/skills/skill-creation-walkthrough/SKILL.md b/skills/skill-creation-walkthrough/SKILL.md new file mode 100644 index 0000000..7683255 --- /dev/null +++ b/skills/skill-creation-walkthrough/SKILL.md @@ -0,0 +1,261 @@ +--- +name: skill-creation-walkthrough +description: Step-by-step guide for creating your own Claude Skills, from deciding whether a skill is the right tool to writing the SKILL.md file, structuring reference material, and making it trigger reliably. Use when you want to package a workflow, framework, or repeated task into a reusable Skill, when an existing skill is not triggering or not loading the right context, when you are auditing a skill that is underperforming, or when you want to publish a skill for others. Also triggers when someone asks "how do I make a skill" or "what makes a good skill". Useful for individuals, teams, and anyone publishing skills publicly. +category: process-and-team +catalog_summary: "The meta-skill: how to write your own custom skills" +display_order: 5 +--- + +A walkthrough for designing, writing, and maintaining your own Claude Skills. Covers when a skill is the right shape for your problem, how to write a description that actually triggers, how to structure SKILL.md and references, and how to test and iterate. + +## When to use + +- You catch yourself writing the same prompt or instructions repeatedly. +- You want to package a workflow or framework for reuse. +- An existing skill of yours is not triggering when it should. +- You are publishing skills for others to use. +- You want to teach Claude a domain-specific way of working. +- You are reviewing a skill someone wrote and need a quality bar. + +## When NOT to use + +- For one-off prompts (just write the prompt). +- For information that should live in system context, not progressive disclosure. +- For changing Claude's general behavior across all conversations (use Claude.ai settings or system prompts, not skills). +- For replacing tool calls (skills are instructions, not tools). + +## Required inputs + +- The task or workflow you want to encode. +- The audience: who will trigger this skill, in what kind of conversation. +- Existing artifacts: prompts you have used, docs you have written, examples of good output. + +## The framework: how skills work + +A Skill is a folder with a `SKILL.md` file. The SKILL.md has YAML frontmatter (name and description) and a body with instructions. It can also include reference files, scripts, or templates that get loaded when needed. + +The key property: progressive disclosure. Claude does not read every skill on every turn. The skill description lives in the system prompt. The SKILL.md body and references load only when the skill is triggered. This is what lets a user have hundreds of skills without polluting context. + +What this means for you: + +- The description is everything for triggering. Get it right or the skill never loads. +- The SKILL.md body is for the workflow itself. +- The references are for content that does not need to be in every invocation: long checklists, templates, examples, deep reference material. + +## Workflow + +### Phase 1: Decide if a skill is the right shape + +Not everything should be a skill. Run this test: + +\| Sign it should be a skill \| Sign it should not be \| +\| --- \| --- \| +\| You repeat the same workflow 5+ times. \| You used it once. \| +\| The output benefits from a consistent structure. \| Each output is bespoke. \| +\| The task has a clear trigger (a question shape, a file type, a domain). \| The task is part of every conversation already. \| +\| The instructions exceed 200 words. \| A one-line system instruction would do. \| +\| Templates or reference material would help. \| Pure prose is enough. \| +\| Other people might benefit from the same workflow. \| Only relevant to your single project. \| + +If most of your answers are in the left column, build a skill. Otherwise, use a saved prompt or a system instruction. + +### Phase 2: Define the trigger + +Before writing anything, ask: when should this skill load? + +Be concrete. Write down the exact phrases or situations that should trigger it. Examples: + +- "When the user asks for a creative brief, kickoff doc, or project brief." +- "When the user uploads a CSV and wants tabular analysis." +- "When the user asks 'how do I rank for X', 'should I add schema', or anything SEO-related." +- "When the user mentions they want to pick a vendor or compare tools." + +The trigger is your description's job. If you cannot articulate the trigger crisply, the skill will not load reliably. + +### Phase 3: Write the description + +This is the most important sentence (or two) in your skill. The description is what Claude sees in the system prompt to decide whether to load the skill. + +Good descriptions have 4 parts: + +1. What it does (one sentence, action-oriented). +2. When to use it (the trigger phrases or situations). +3. Edge cases with "Also triggers when..." (catches less obvious situations). +4. Useful for... (audience or use cases, helps disambiguation). + +Bad description: + +> "Helps with SEO." + +Why it fails: vague, no trigger phrases, will not fire when the user actually needs it. + +Good description: + +> "Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, asks 'why is this page not ranking', or shares a URL and asks what is wrong with it. Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits." + +Why it works: specific actions, multiple trigger phrases, edge cases, audience clarity. + +### Phase 4: Structure the SKILL.md body + +A consistent structure makes skills readable, maintainable, and AI-friendly. The pattern below works for most skills: + +``` +--- +name: [your-skill-name] +description: [your description] +--- + +[One-sentence purpose statement] + +## When to use +[Bulleted list of trigger situations] + +## When NOT to use +[Bulleted list, ideally redirecting to sibling skills] + +## Required inputs +[What Claude needs from the user to run this skill] + +## The framework +[The durable IP: the model, the steps, the dimensions, the layers] + +## Workflow +[Numbered steps Claude follows] + +## Failure patterns +[Common mistakes to avoid or push back on] + +## Output format +[What the deliverable looks like] + +## Reference files +[List of files in the references/ folder with descriptions] +``` + +Not every skill needs every section. Some skills are pure how-to and skip "framework". Some skills are heavy on examples and add an "Examples" section. Use the structure as a starting point, adapt as needed. + +### Phase 5: Add references for what does not belong in SKILL.md + +References are the second tier of progressive disclosure. They load when Claude reads them, not by default. + +Use references for: + +- Long checklists (a 100-item audit checklist). +- Templates with worked examples. +- Detailed playbooks for specific scenarios. +- Reference material like spec links, glossaries, decision tables. +- Anything over 100 lines that not every invocation needs. + +Each reference should be standalone. A reader (or Claude) should be able to use it without reading the SKILL.md first, given the context the skill provides. + +Naming patterns that work: + +- `references/[noun]-template.md` for templates. +- `references/[noun]-checklist.md` for checklists. +- `references/[noun]-playbook.md` for end-to-end runbooks. +- `references/example-[scenario].md` for worked examples. + +Reference your reference files from the SKILL.md "Reference files" section with a one-line description of each. + +### Phase 6: Test and iterate + +Skills do not work the first time. Plan to iterate. + +Testing checklist: + +- [ ] Trigger test: in a fresh conversation, write the trigger phrase. Does the skill load? If not, the description is too narrow or wrong. +- [ ] Edge case test: write something that should trigger via the "Also triggers when..." clause. Does it fire? +- [ ] False positive test: write something close but not actually relevant. Does the skill avoid loading? If it always loads, your description is too broad. +- [ ] Output test: run the skill on a real task. Is the output what you expected? +- [ ] Length test: is the SKILL.md staying under 250 lines? Are references under 400 lines? If not, split or trim. + +After testing, common fixes: + +- Skill not triggering → broaden the description, add explicit phrases, add "Also triggers when..." +- Skill triggering too often → narrow the description, add "Do not trigger when...", be more specific about audience. +- Output is generic → add a clearer framework or workflow with more specifics. +- Reference is overwhelming → split into multiple references, keep each focused. + +## Deep dive: description anatomy + +The description is hard to get right. Here is the formula in detail. + +### Sentence 1: What it does + +Lead with the verb. Be specific. + +- Good: "Audit on-page SEO." +- Bad: "Help with SEO things." + +### Sentence 2: When to use it + +State the primary triggers. Use phrases users would actually say. + +- Good: "Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks 'why is this page not ranking'." +- Bad: "Use for SEO improvements." + +### Sentence 3: "Also triggers when..." + +Catch the secondary triggers and edge cases. + +- Good: "Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup." +- Bad: (omitted) + +### Sentence 4: Useful for... + +Explain audience or scope to help with disambiguation. + +- Good: "Useful for both individual page reviews and small-batch audits." +- Bad: (omitted) + +If your skill description is one sentence, it is probably not specific enough. + +## Deep dive: worked example + +Imagine you keep writing technical post-mortem documents and want to skill-ify it. + +Step 1: Decide it's a skill. You write 5+ post-mortems a year, output benefits from consistency, others on the team would use it. Yes, build a skill. + +Step 2: Trigger. "When the user wants to write a post-mortem, retrospective, or after-action report. When an incident has happened and we are reviewing what went wrong." + +Step 3: Description. + +> "Write a structured post-mortem after an incident, outage, or significant project failure. Use when the user mentions post-mortem, retrospective, after-action report, RCA, or asks 'why did this go wrong' after an incident. Also triggers when the user wants to capture lessons learned from a launch, project miss, or incident debrief. Useful for technical incidents, project retros, and team learning reviews." + +Step 4: SKILL.md body. Use the standard structure. Required inputs (timeline, impact, contributors). The framework (Five Whys, contributing factors, action items). Workflow (gather facts, draft, review, distribute). Failure patterns (blame, vague action items, no follow-up). + +Step 5: References. A `post-mortem-template.md` with the document structure and a `facilitator-checklist.md` for running the post-mortem meeting. + +Step 6: Test. Trigger on "we had an outage yesterday, can you help me write the post-mortem?" Should fire. Trigger on "what is a post-mortem?" Should probably also fire. Trigger on "let's review the quarter". Should not fire (this is a different kind of retro). + +You iterate until the triggers fire correctly, then ship. + +## Failure patterns + +- Description too narrow. The skill never fires because your description requires exact phrases the user does not say. +- Description too broad. The skill fires constantly, including for unrelated tasks. +- No trigger phrases. The description describes what the skill does but not when to load it. Triggering is unreliable. +- SKILL.md too long. A 1,000-line SKILL.md defeats the purpose of progressive disclosure. Split into references. +- References that duplicate SKILL.md. If a reference repeats what the body says, prune one. +- No "When NOT to use". Skills that overlap with sibling skills get loaded ambiguously. Cross-reference siblings explicitly. +- No examples. A framework without a worked example is hard to apply. Include at least one in the reference material. +- Optimizing for one example. A skill written around your single use case fails at adjacent ones. Generalize. +- No iteration. Shipping a skill once and never revisiting it. Skills decay. Audit yearly. +- Branding or product-specific assumptions in a public skill. Skills meant to be general should not hardcode your stack. Public skills teach methodology (frameworks, decision criteria, taxonomies, anti-patterns); implementation specifics (specific page architectures, type definitions, component code, framework-specific patterns) belong in internal playbooks. See [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md) for the full discipline and the user-outcome reasons it matters. + +## Output format + +When using this skill to create another skill, deliver: + +1. Trigger analysis: a short list of phrases and situations that should fire the skill. +2. Description draft: the 2-4 sentence description for the YAML frontmatter. +3. SKILL.md body: the full body of the skill, following the standard structure. +4. Reference plan: a list of reference files to create with one-line descriptions. +5. First reference file: at least one reference written end to end as a starting point. +6. Test plan: 3-5 test prompts that should trigger the skill, plus 2-3 that should not. + +## Reference files + +- [`references/skill-template.md`](references/skill-template.md): A blank SKILL.md template with annotated section guidance, ready to copy and fill in. +- [`references/description-cookbook.md`](references/description-cookbook.md): A library of description patterns with worked examples for common skill types (audits, templates, frameworks, walkthroughs). +- [`references/methodology-vs-implementation.md`](references/methodology-vs-implementation.md): What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. The audit pattern and the authoring checklist for keeping skills methodology-pure. diff --git a/skills/skill-creation-walkthrough/references/description-cookbook.md b/skills/skill-creation-walkthrough/references/description-cookbook.md new file mode 100644 index 0000000..ff3ba60 --- /dev/null +++ b/skills/skill-creation-walkthrough/references/description-cookbook.md @@ -0,0 +1,214 @@ +# Description cookbook + +The skill description is the single most important sentence (or paragraph) in your skill. It is what Claude sees in the system prompt to decide whether to load the rest of the skill. If the description is wrong, the skill never fires when it should, or fires when it should not. + +This cookbook gives you description patterns for common skill types, each with a worked example. + +## The 4-part formula + +A reliable description has 4 parts: + +1. Action: what the skill does (verb-led, specific). +2. Primary triggers: when to use it (the obvious cases). +3. Edge cases: secondary triggers introduced with "Also triggers when...". +4. Audience or scope: who this serves, introduced with "Useful for...". + +Not every skill needs all four parts. Most benefit from at least three. + +## Pattern 1: The audit skill + +For skills that evaluate something against a rubric. + +### Template + +``` +[Verb] [the thing] for [purpose]. Use when the user asks for [a concrete request], wants to [common task], or asks "[likely user phrasing]". Also triggers when the user mentions [related concepts] or shares [input that implies the audit]. Useful for [scope: one-off vs ongoing, individual vs batch]. +``` + +### Worked example + +``` +Audit on-page SEO of a single URL or a small set of pages. Use when the user asks for a page audit, wants to optimize titles and meta descriptions, or asks "why is this page not ranking". Also triggers when the user mentions Core Web Vitals, internal linking, or schema markup. Useful for both individual page reviews and small-batch audits. +``` + +Why this works: + +- "Audit" is a clear verb. +- The "on a single URL or a small set of pages" sets scope, which prevents this from competing with bulk audit skills. +- Three primary triggers in different phrasings. +- "Also triggers when..." catches secondary signals. +- "Useful for..." narrows the use case. + +## Pattern 2: The template or generator skill + +For skills that produce a structured artifact. + +### Template + +``` +Generate [the artifact] following [methodology or structure]. Use when the user asks to write [artifact name], needs [related deliverable], or describes [the work this artifact captures]. Also triggers when the user has [precondition] and is preparing to [downstream action]. Useful for [audience or use case]. +``` + +### Worked example + +``` +Generate a creative brief that aligns stakeholders before a project starts. Use when the user asks to write a brief, kickoff doc, or project brief, or describes a project that has a goal but no shared context document. Also triggers when the user is starting design or development work without an agreed scope. Useful for individual project briefs and recurring brief templates. +``` + +Why this works: + +- "Generate" is the verb. +- "That aligns stakeholders before a project starts" tells Claude the context. +- Multiple ways the user might phrase the request. +- The "also triggers" catches the upstream signal (no shared context yet). + +## Pattern 3: The framework or methodology skill + +For skills that teach or apply a way of thinking. + +### Template + +``` +Apply [framework name or shape] to [the problem]. Use when the user is [the situation], asks "[likely question]", or needs to think through [the kind of decision]. Also triggers when [secondary condition]. Useful for [scope]. +``` + +### Worked example + +``` +Apply the Diataxis framework to documentation problems: separate tutorials, how-to guides, references, and explanations. Use when the user is reorganizing docs, asks "where should I put this", or has docs that try to do too much at once. Also triggers when the user is starting a fresh docs site and needs a content structure. Useful for both internal and external documentation. +``` + +Why this works: + +- Names the framework explicitly. +- Concrete trigger phrases. +- "Has docs that try to do too much at once" is a specific symptom that maps to this framework. + +## Pattern 4: The walkthrough or playbook skill + +For skills that take the user through a multi-step process. + +### Template + +``` +Walk through [the process] step by step. Use when the user is [the situation], asks how to [the goal], or needs a structured approach to [complex task]. Also triggers when [edge case]. Useful for [first-time vs repeat use, individuals vs teams]. +``` + +### Worked example + +``` +Walk through a domain migration step by step, including DNS, redirects, content mapping, and post-launch validation. Use when the user is moving content between platforms, changing domains, or restructuring URLs at scale. Also triggers when the user mentions hreflang updates, sitemap regeneration, or 301 redirect maps. Useful for both small migrations (a few hundred URLs) and large ones (tens of thousands). +``` + +Why this works: + +- "Step by step" sets expectation. +- Names the components ("DNS, redirects, content mapping, and post-launch validation") so users with one of these in mind still trigger correctly. +- Scale guidance in "useful for" helps with disambiguation. + +## Pattern 5: The decision or evaluation skill + +For skills that help the user pick between options. + +### Template + +``` +Compare [option type] and recommend [outcome]. Use when the user is choosing between [options], asks "[option A] vs [option B]", or needs to decide [the question]. Also triggers when [renewal/replacement/scaling situation]. Useful for [scope]. +``` + +### Worked example + +``` +Compare vendors and recommend a pick for a specific job. Use when the user is choosing between SaaS tools, asks "X vs Y", or needs to evaluate options before signing a contract. Also triggers when an existing vendor is up for renewal or being replaced. Useful for both small SaaS decisions and large infrastructure choices. +``` + +Why this works: + +- "Compare and recommend" frames the action. +- Multiple trigger phrasings. +- "Also triggers when..." catches the renewal/replacement situation that often forces a decision. + +## Pattern 6: The diagnostic or troubleshooting skill + +For skills that help find what is wrong. + +### Template + +``` +Diagnose [the problem class] and propose fixes. Use when the user reports [symptom], asks "why is [thing] [bad state]", or shares [evidence of the problem]. Also triggers when [related signal]. Useful for [scope of diagnosis]. +``` + +### Worked example + +``` +Diagnose slow page performance and propose specific fixes. Use when the user reports slow load times, asks "why is my site slow", or shares a Core Web Vitals report. Also triggers when the user mentions Lighthouse scores, LCP, INP, or CLS issues. Useful for both individual page diagnosis and site-wide performance reviews. +``` + +Why this works: + +- "Diagnose and propose fixes" is the action. +- Catches the user's likely phrasing ("why is my site slow"). +- Catches technical phrasings (Core Web Vitals report, Lighthouse, specific metric names). + +## Pattern 7: The strategy or planning skill + +For skills that produce a plan or strategy. + +### Template + +``` +Design [the plan or strategy] for [outcome]. Use when the user is [the situation], asks for a [plan / strategy / roadmap], or needs to align [stakeholders or work] around [the goal]. Also triggers when [precondition or constraint]. Useful for [scope]. +``` + +### Worked example + +``` +Design a content strategy that supports a specific business goal. Use when the user is starting a content program, asks for an editorial plan, or needs to align content production with marketing or SEO objectives. Also triggers when the user mentions topical authority, content calendar, or pillar pages. Useful for both new programs and reboots of stalled ones. +``` + +Why this works: + +- "Design a content strategy that supports a specific business goal" sets the action and the constraint. +- Catches both fresh starts and reboots in "useful for". + +## Anti-patterns: descriptions that fail + +### "Helps with X" + +Too vague. No triggers. Will fire constantly or never. + +### "When the user wants help with technical SEO and on-page SEO and off-page SEO" + +Too broad. Should be split into multiple skills or narrowed. + +### "Use when the user mentions XYZ" + +Too narrow. Real users will not always use the exact phrase. + +### "Comprehensive guide to [topic]" + +Marketing copy, not a trigger. Does not tell Claude when to load. + +### "[no description, just a name]" + +The skill never loads except by accident. + +## How to test a description + +Before publishing: + +1. Write down 5 prompts that should trigger the skill. +2. Write down 3 prompts that should not. +3. In a fresh conversation with the skill installed, try each prompt. +4. Check whether the skill loaded. +5. Adjust the description until trigger and non-trigger prompts behave correctly. + +If a should-trigger prompt does not fire, broaden the description: add the phrasing the user used, add an "also triggers" clause. + +If a should-not-trigger prompt fires, narrow the description: add scope boundaries, name the sibling skill the user actually wants, or add a "Do not trigger when..." clause if needed (most skill descriptions do not need this, but it is available). + +## Final tip: match the user's vocabulary + +Users do not say "perform an SEO audit". They say "can you check my page" or "is my site optimized". Your description should anticipate the user's vocabulary, not yours. + +If your description is full of expert jargon and the user is a beginner, the skill will not fire. Use the words your audience actually says. Use jargon as a backup, not the lead. diff --git a/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md b/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md new file mode 100644 index 0000000..55c6f4f --- /dev/null +++ b/skills/skill-creation-walkthrough/references/methodology-vs-implementation.md @@ -0,0 +1,96 @@ +# Methodology vs implementation + +What belongs in a public skill, what stays internal, and the user-outcome reasons the discipline matters. + +A public skill is methodology, not implementation. Skills teach the framework, the decision criteria, the taxonomies, the anti-patterns. They do not teach the specific page architecture, type definitions, image generation script structure, or stack-specific patterns that any one team uses to ship polished delivery. + +This is not gatekeeping. It is user-aligned. Methodology produces work that is distinctive to each team's stack and judgment. Cookie-cutter implementation produces homogenized output that looks identical across users. Stack-agnosticism makes the catalog actually portable. Implementation specificity makes it useless to teams on different stacks. + +--- + +## What belongs in a public skill (methodology layer) + +- Conceptual frameworks (architectures, registers, taxonomies, classifications) +- Decision criteria (when to choose X versus Y, with the tradeoffs surfaced) +- Anti-patterns and common failure modes +- The shape of artifacts the skill produces, described in generic terms (a markdown brief with these sections; a JSON object with these fields; a design spec with these decisions documented), not as type signatures bound to a specific framework +- Voice and style guidance for the work +- Workflow descriptions at the methodology level (the sequence of decisions and handoffs, not the platform commands) +- General principles applicable across stacks +- Worked examples with fictional or anonymized actors that demonstrate the framework concretely without prescribing a specific tooling stack + +The 12-consideration framework pattern (or 5-pillar, 4-axis, etc.) lives here. Frameworks are durable; they survive stack migrations and team transitions because they teach judgment, not code. + +--- + +## What does not belong in a public skill (implementation layer) + +- Specific Next.js, React, Vue, Svelte, or other framework-specific page architectures +- TypeScript or other type definitions optimized for a specific application's data shapes +- Component patterns with stack-specific code (JSX, template syntax, framework directives) +- Image generation script structures matching a specific implementation +- Application-context CSS-rendered mockup component code +- Theme integration patterns tied to specific design tokens (brand-color names, spacing scales, font tokens that exist only in one team's design system) +- Tailwind class strings or other utility-CSS specifics that prescribe one stack's idioms +- Schema markup component shapes that match one team's component library +- Vercel, Netlify, or specific deployment patterns + +If a section of a skill cannot be applied by a reader on a different stack, it does not belong in the public skill. It belongs in an internal playbook, a productized client deliverable, or a stack-specific reference implementation maintained separately. + +--- + +## Why the line matters + +Three principles, each user-outcome framed. + +### 1. Methodology produces distinctive work + +A skill that teaches "five logo architectures" leaves the user to choose, design, and execute the architecture that fits their brand. A skill that teaches "render this Next.js component with these Tailwind classes" produces work that looks identical across every user who runs the skill. Cookie-cutter implementation homogenizes; methodology requires the user to engage with why, which produces work distinctive to each team's context. + +The user outcome that matters: did the skill help the user produce work that is theirs, or did it produce work that signals "I ran a skill"? + +### 2. Stack-agnosticism is real value + +A skill that mandates a specific Next.js component is useless to teams on Astro, vanilla HTML, Figma-only workflows, WordPress, Shopify, or anywhere off the prescribed stack. Methodology applies across all of them. + +The catalog gets used by people writing in plain markdown, working in Notion, building on a static site generator, running in WordPress, or shipping in something that did not exist when the skill was written. Methodology survives all of those. Stack-coupled implementation does not. + +### 3. The catalog compounds because skills are durable + +Skills last across stack changes, framework migrations, and team transitions because they teach judgment, not code. A skill that hardcodes the framework du jour decays as the framework changes. A skill that teaches the framework-agnostic principle the framework was implementing keeps working when teams migrate to the next framework. + +Implementation-leaking skills decay as their implementations become outdated. Methodology-pure skills compound across years. + +--- + +## The audit pattern + +The catalog is audited periodically for methodology versus implementation drift. The first formal audit (May 2026) reviewed 18 flagship skills against the criteria in this reference and found zero implementation-leakage findings; the discipline had been held by instinct from the catalog's earliest skills onward. Future audits will land as the catalog grows past current size. + +Findings shape the discipline. Recently shipped skills tend to carry the discipline more cleanly than the earliest ones, which reflects the maturation any catalog goes through. The principle is not "perfection from day one"; it is "audit, learn, codify, hold the line going forward." + +--- + +## How to apply this when authoring new skills + +A short checklist for skill authors: + +1. Before writing, identify the methodology versus implementation boundary explicitly. What part of this skill teaches a framework that applies across stacks? What part teaches your specific stack's implementation? The framework part goes in the public skill; the implementation part stays internal. +2. When tempted to include specific code, ask: is this teaching the framework, or is this teaching my stack? If it teaches the framework using your stack as one illustration, keep it; if it teaches your stack using the framework as scaffolding, move it. +3. When referring to tooling, prefer general categories ("a feature flag platform," "a data warehouse," "a CMS with structured content models") over specific products. Name specific products when the category needs concretization, and name multiple alternatives so readers see the category rather than locking into one vendor. +4. Cross-references to specific tools or services should be sparse. Each cross-reference should earn its inclusion through methodology relevance, not marketing value. If a cross-reference exists primarily to drive traffic, it is not earning its keep in a methodology skill. +5. Run the audit checklist before merge. Any specific code? Any type signatures matching your application? Any framework-specific patterns? If yes, move to internal playbook. + +--- + +## What stays internal + +Implementation specifics live somewhere; they just do not live in the public skill. Common locations: + +- Internal playbooks in private repositories +- Internal documentation in team wikis or knowledge bases +- Productized client deliverables produced by combining methodology plus playbook plus judgment +- Stack-specific reference implementations maintained as separate properties +- Onboarding materials for team members joining the implementation work + +The principle: anyone reading the public skill should be able to produce quality methodology-driven work on their own stack. Teams that want polished productized delivery in a specific stack do that work themselves, build their own internal playbooks, or engage practitioners who specialize in that delivery. The public skill is the upstream input; the implementation is the downstream work, owned by whoever is doing it. diff --git a/skills/skill-creation-walkthrough/references/skill-template.md b/skills/skill-creation-walkthrough/references/skill-template.md new file mode 100644 index 0000000..eb5f92f --- /dev/null +++ b/skills/skill-creation-walkthrough/references/skill-template.md @@ -0,0 +1,153 @@ +# Skill template + +A blank SKILL.md template with annotated guidance. Copy this, fill it in, and you have a skill that fits the pattern. + +## How to use this template + +1. Copy the YAML and structure below into a new file at `your-skill-name/SKILL.md`. +2. Replace the placeholder text in `[brackets]`. +3. Delete sections you do not need (most skills do not need every section). +4. Read the annotations to understand what each section is doing. +5. Test the skill on a real task. Iterate. + +## The template + +``` +--- +name: [your-skill-name] +description: [2-4 sentences. What the skill does. When to use it. "Also triggers when..." for edge cases. "Useful for..." for audience clarity.] +--- + +[One-sentence purpose statement. What this skill exists to do.] + +## When to use + +- [Trigger situation 1] +- [Trigger situation 2] +- [Trigger situation 3] +- [Trigger situation 4] + +## When NOT to use + +- [Situation that looks similar but should use a different skill] +- [Situation that is out of scope for this skill] +- [Sibling skill cross-reference: "For X, use the [other-skill] skill."] + +## Required inputs + +- [Information Claude needs from the user before it can do good work] +- [Or context Claude needs to gather] +- [Or files, links, or examples needed] + +## The framework + +[The durable IP. The model, dimensions, layers, principles that make this skill different from a freeform response. This is where the skill earns its keep.] + +[Format options: numbered list of layers, table of dimensions, hierarchy of concepts. Pick what fits the content.] + +## Workflow + +1. [First step Claude takes] +2. [Second step] +3. [Third step] +4. [...] +5. [Final step or output] + +## Failure patterns + +- [Common mistake]: [Why it happens, how to avoid]. +- [Common mistake]: [Why it happens, how to avoid]. +- [Common mistake]: [Why it happens, how to avoid]. + +## Output format + +Deliverables from this skill: + +1. [Artifact 1]: [What it is]. +2. [Artifact 2]: [What it is]. +3. [Artifact 3]: [What it is]. + +[Optional: notes on format, length, or delivery mechanism.] + +## Reference files + +- `references/[name].md`: [One-line description of what is in this reference]. +- `references/[name].md`: [One-line description]. +``` + +## Annotations: what each section is for + +### YAML frontmatter + +The `name` should match the folder name and use lowercase hyphens. The `description` is the most important field in the entire skill. It is what Claude sees in the system prompt to decide whether to load the skill body. Be specific about triggers. + +### Purpose statement (one sentence) + +This is the elevator pitch. A reader should know what the skill does after this one sentence. If you cannot summarize it in a sentence, the skill may be doing too much. + +### When to use + +Be concrete. List the actual situations where the skill should fire. These map to the trigger phrases in the description but in more detail. + +### When NOT to use + +Just as important as "when to use". This is where you redirect to sibling skills and prevent overlap. Without this section, related skills compete and Claude makes ambiguous choices. + +### Required inputs + +What does Claude need before it can do good work with this skill? Sometimes this is information ("the URL to audit"). Sometimes it is context ("the user's audience"). Listing it explicitly helps Claude ask the right question if it is missing. + +### The framework + +This is the durable IP. The thing that makes your skill better than a generic LLM response on the topic. A model, a set of dimensions, a hierarchy, a checklist of layers. + +If you cannot articulate the framework, the skill may be more about output structure than methodology. That is fine. Skip this section. + +### Workflow + +The numbered steps Claude follows when running the skill. Should be repeatable across different invocations. If the steps differ wildly per use case, you may need multiple skills or a more abstract framework. + +### Failure patterns + +What goes wrong in practice. This section is what makes a skill feel earned. It signals "we have done this many times and these are the mistakes". Specific failure patterns are more useful than abstract ones. + +### Output format + +What the deliverable looks like. Not "good output" - actually structured and named. This is what Claude produces at the end. + +### Reference files + +The list of `references/` files with brief descriptions. Each reference should be standalone and useful even if read out of order. + +## Sizing guidance + +\| Component \| Target \| Hard limit \| +\| --- \| --- \| --- \| +\| Description \| 2-4 sentences \| 1 paragraph \| +\| SKILL.md total \| Under 250 lines \| 500 lines \| +\| Single reference file \| Under 400 lines \| 800 lines \| +\| Number of references \| 1-3 \| 5 \| + +If you are over the targets, split or trim. Skills get heavier and more brittle as they grow. + +## Naming conventions + +- Skill folder: `lowercase-hyphenated` +- SKILL.md: always exactly `SKILL.md` (case-sensitive) +- References: `references/[name].md` +- Templates: `[noun]-template.md` +- Checklists: `[noun]-checklist.md` +- Playbooks: `[noun]-playbook.md` +- Examples: `example-[scenario].md` + +## Common adaptations + +Not every skill needs the standard structure. Examples of valid adaptations: + +- Pure how-to skill: skip the "framework" section, lead with workflow. +- Pure template skill: skip framework and workflow, focus on the structure of the output. +- Audit skill: heavy on the framework (the dimensions to score), lighter on workflow. +- Walkthrough skill: numbered phases as the spine, no separate framework section. +- Decision skill: heavy on options and tradeoffs, lighter on workflow. + +The structure exists to make sure you cover the right ground. If a section does not earn its place, drop it. But know what you are dropping and why. diff --git a/skills/stakeholder-communication/SKILL.md b/skills/stakeholder-communication/SKILL.md new file mode 100644 index 0000000..f5a1950 --- /dev/null +++ b/skills/stakeholder-communication/SKILL.md @@ -0,0 +1,360 @@ +--- +name: stakeholder-communication +description: "Communicate effectively with stakeholders across functions and seniority levels. Use this skill when writing status updates, preparing executive reviews, sharing technical decisions with non-technical audiences, managing up, communicating bad news, or designing the communication cadence for a project. Triggers on stakeholder update, status report, executive summary, exec review, manage up, communicate bad news, project comms, status meeting, weekly update. Also triggers when a project is going off track and the team needs to communicate it." +category: process-and-team +catalog_summary: "Status updates, exec readouts, project communications" +display_order: 1 +--- + +# Stakeholder Communication + +Get the right information to the right people at the right time, in a form they can act on. Stack-agnostic. Applies to any team operating with cross-functional stakeholders. + +--- + +## When to use + +- Writing weekly or monthly status updates +- Preparing for an executive review or board update +- Sharing a technical decision with a non-technical audience +- Communicating a delay, miss, or quality problem +- Asking for help, resources, or decisions +- Managing up to a manager or sponsor +- Designing the communication cadence for a project +- Drafting an internal announcement + +## When NOT to use + +- Customer-facing communication (use marketing/support skills) +- Public comms or press (different framework, different stakes) +- Incident communication during an active incident (use `incident-response`) +- Internal documentation that isn't time-sensitive (use `documentation-strategy`) +- Specific delivery formats (slide deck design, email tone) - this skill is about content and structure + +--- + +## Required inputs + +- The audience (who specifically, what's their context, what do they care about) +- The purpose (inform, decide, escalate, ask, celebrate) +- The substance (what's actually happening) +- The medium (email, doc, meeting, slide, chat) +- Time constraints (when do they need this) + +--- + +## The framework: 5 questions + +Before any stakeholder communication, answer: + +### Question 1: Who is the audience? + +Specifically. "Leadership" is too vague. The CFO and the VP of Engineering have different concerns. + +For each named audience: +- What do they care about? (revenue, risk, quality, velocity, costs, customers) +- What do they already know? (background you can skip) +- What's their level of detail tolerance? (executives want headlines; ICs want details) +- What action do you want from them? (acknowledgment, decision, help, no action) + +### Question 2: What's the headline? + +If they read only one sentence, what should they take away? + +The headline goes first. Always. The narrative supports it; the data confirms it. + +This is the biggest gap in most stakeholder communication: people start with context and build to a conclusion. Stakeholders want the conclusion first. + +### Question 3: What's the so-what? + +Stakeholders ask "and?" implicitly. Answer it explicitly. + +- "We hit 80% of the milestone." → so what? +- "We hit 80% of the milestone, which puts the launch one week behind plan." → that's the so-what. + +The so-what makes the information actionable. + +### Question 4: What do you want? + +Communications generally have one of these requests: + +- Inform: no action needed. Just keeping them in the loop. +- Decide: a decision is needed; here are the options and recommendation. +- Escalate: something is stuck; we need help. +- Ask: a specific request (resource, introduction, review). +- Celebrate: a win to share; no action needed but morale matters. + +State which. Don't bury the request. + +### Question 5: What format? + +- Async written (doc, email): rich content, decision trail, easy to reference +- Sync written (chat, ticket comment): quick exchange, conversational +- Sync spoken (meeting, call): nuance, debate, alignment +- Mixed (doc + meeting): the doc is read in advance; meeting is decision + +For most updates: async written. Save sync time for actual discussion. + +--- + +## The structure: the inverted pyramid + +Stakeholder communication reads like a news article, not an essay. + +``` +Headline (one sentence) + +The "so what" and the request (one paragraph) + +Status / progress (the body) + +Risks and asks (what we need) + +Detail / appendix (what curious readers want) +``` + +Cut from the bottom. If your update gets shortened, the top survives. + +--- + +## Update templates + +### Weekly project update + +``` +Project: [Name] +Status: [On track / At risk / Off track] +Headline: [One-sentence summary] + +This week: +- [Specific accomplishment] +- [Specific accomplishment] +- [Specific accomplishment] + +Next week: +- [Specific plan] +- [Specific plan] + +Risks / blockers: +- [Risk + what we're doing about it / what we need] + +Metrics: +- [Metric: value vs target] +- [Metric: value vs target] +``` + +The status indicator (on track / at risk / off track) is essential. Stakeholders scan for it. + +### Executive review + +``` +Headline: [The summary, one sentence] + +Key points: +1. [Point with one supporting sentence] +2. [Point with one supporting sentence] +3. [Point with one supporting sentence] + +Decisions needed: +- [Decision A: options and recommendation] +- [Decision B: options and recommendation] + +Asks: +- [Specific request] + +Detail: [Linked doc or appendix] +``` + +Executives skim. They click into detail when interested. + +### Bad news + +The hardest update to write well. + +``` +Headline: [The bad news, plainly stated] + +What happened: +[Specific facts, no euphemisms] + +Impact: +[Who's affected, how much, by when] + +What we're doing: +[Specific actions and owners] + +What we need: +[Specific asks, if any] + +Timeline: +[When the next update will land] +``` + +Don't soften the headline. Soft headlines on bad news erode trust faster than the news itself. + +### Decision request + +``` +Decision: [What needs to be decided] + +Context: [The minimum needed to understand] + +Options: +1. [Option A: description, pros, cons] +2. [Option B: description, pros, cons] +3. [Option C: description, pros, cons] + +Recommendation: [Option X, because...] + +Need by: [Date] +Decision rights: [Who decides] +``` + +Recommendation matters. Not making one is putting the work back on the decider. + +--- + +## Tone and register + +### Across audiences + +\| Audience \| Tone \| Detail \| Length \| +\|---\|---\|---\|---\| +\| Direct manager \| Candid, briefer \| Mid \| Medium \| +\| Skip-level / VP \| Polished, sharper \| Low \| Short \| +\| Cross-functional peer \| Collaborative, specific \| Mid-high \| Medium \| +\| Executive / board \| Headlines, confident \| Low (with detail available) \| Short \| +\| Team / IC stakeholders \| Detailed, direct \| High \| Long \| + +### What to avoid + +- Hedging when confident. "I think maybe we might be able to..." Just say what you mean. +- Confidence when uncertain. "Definitely launching Friday" when there's risk. Calibrate. +- Jargon for non-technical audiences. Replace with plain language. +- Burying the lede. Headline first. +- Implicit asks. State explicitly what you want. +- Status updates that are 90% activity, 10% outcome. Focus on outcomes; activity is supporting evidence. + +--- + +## Workflow + +### Step 1: Define the audience and purpose + +Before writing, answer Q1-Q5 above. Often this clarifies the message before any drafting. + +### Step 2: Draft the headline + +One sentence. The takeaway. If you can't write the headline, you don't know yet what you're communicating. + +### Step 3: Write inverted pyramid + +Headline, so-what, body, asks, detail. + +### Step 4: Cut + +A first draft is usually 30-50% too long. + +- Cut activities that don't have outcomes +- Cut adjectives (great, awesome, excellent, exciting) +- Cut filler (just, really, very, actually) +- Cut hedging (kind of, sort of, somewhat) when confident +- Cut sentences that don't add information + +### Step 5: Verify the request + +Reread. Is the ask clear? Is it specific? Is the deadline named? + +### Step 6: Check the audience + +Imagine the recipient reading. Will they understand the headline? Have you skipped context they need? Have you given context they don't need? + +### Step 7: Send and follow up + +After sending: +- Did the right people see it? Acknowledge the right channel. +- Did they understand? Watch for confused replies; address them. +- Did they act? Follow up on stale asks. + +--- + +## Cadence design + +Different audiences need different cadences. + +### High-frequency (weekly or more) + +- Direct team, manager, sponsor +- Active project stakeholders +- People making day-to-day decisions + +### Medium-frequency (biweekly to monthly) + +- Skip-level +- Cross-functional partners +- Adjacent teams +- Strategic stakeholders + +### Low-frequency (quarterly) + +- Executive review +- Board update +- Wider organization +- External stakeholders (where relevant) + +The right cadence is what's needed, not what fills the calendar. Update people when there's something new; don't manufacture updates. + +--- + +## Failure patterns + +Long preamble before the point. Three paragraphs of context, then the one sentence that mattered. Lead with the point. + +Status: yellow. Same status three weeks in a row. Yellow with no change is red. Be honest about progress. + +Update without a clear ask. "We're working on it." OK, what do you want? If nothing, say "no action needed." + +Sandwiching bad news in good news. "We've done X and Y, and unfortunately Z is delayed, but we've also done W." The bad news gets lost. Lead with it if it's the headline. + +Walls of text. Too long, unread. Cut to the structure. + +Activity vs outcome. "Met with team. Reviewed plan. Updated tickets." So what? "Cut scope to hit launch date" is an outcome. + +Different update for every audience. Maintaining 5 versions doubles work. Have one core update; tailor the framing. + +Status update that's actually a request. Buries an ask in a wall of status. Pull the ask out. Make it visible. + +Optimistic projections. "We'll be back on track next week." Then we're not. Then again. Trust erodes. Be honest about the path. + +No follow-up on asks. Asked for a decision; didn't get one; moved on. Now the project is stuck. Follow up. + +Communicating bad news only when forced to. Stakeholders find out from someone else, or from a missed deadline. Lose trust. Communicate proactively. + +Performative comms for the audience of one. Every update reads like a sales pitch to the boss. Stakeholders see through it. Be direct. + +No comms when no news. Silence is worse than "no change this week." Set expectations on cadence and stick to it. + +--- + +## Output format + +A communication plan for a project includes: + +- Stakeholder map: named people, their interests, their decision rights +- Cadence: what updates go to whom, how often +- Templates: standardized formats for repeated updates +- Escalation paths: who to involve when something's at risk +- Decision log: running record of decisions made, by whom, why + +For individual communications: + +- Headline: the takeaway +- Body: the supporting structure +- Ask: the request, explicitly +- Distribution: who gets it, in what form + +--- + +## Reference files + +- [`references/update-templates.md`](references/update-templates.md): Ready-to-use templates for the most common stakeholder communications, with annotated examples. diff --git a/skills/stakeholder-communication/references/update-templates.md b/skills/stakeholder-communication/references/update-templates.md new file mode 100644 index 0000000..70d88d4 --- /dev/null +++ b/skills/stakeholder-communication/references/update-templates.md @@ -0,0 +1,452 @@ +# Update Templates + +Ready-to-use templates for the most common stakeholder communications. Annotated with what each section is doing. + +Adapt to your house style. The structure matters more than the exact wording. + +--- + +## Template 1: Weekly project status + +For internal teams, manager, sponsor. Sent same day each week. + +``` +Subject: [Project] weekly update: [date] + +Status: On track + +We're on plan to ship [milestone] by [date]. + +This week: +- Shipped [specific outcome] +- Started [specific work], [N]% complete +- Decision: chose [option] for [problem] + +Next week: +- Complete [specific work] +- Begin [specific work] +- Review: [decision needed by sponsor] + +Risks: +- [Risk]: [what we're doing about it] + +Asks: +- [Specific ask, if any] + +Detail: [link to project doc] +``` + +Annotations: +- Status indicator (On track / At risk / Off track) is the first thing readers scan +- "This week" is outcomes, not activities +- "Next week" is specific commitments, not vague intentions +- Risks have plans attached +- Asks are explicit and called out + +--- + +## Template 2: At-risk update + +When the project is no longer comfortably on track. + +``` +Subject: [Project] update: at risk for [milestone] + +Status: At risk + +The [milestone] target of [date] is at risk because [specific reason]. + +What's happening: +- [Fact 1] +- [Fact 2] +- [Fact 3] + +Impact: +- If we miss by a week: [specific impact] +- If we miss by a month: [specific impact] + +What we're doing: +- [Action 1] (owner: [name], by: [date]) +- [Action 2] (owner: [name], by: [date]) + +What we need from you: +- [Specific decision or help] + +Next update: [date] +``` + +Annotations: +- Doesn't pretend to be on track +- Names the specific cause +- Quantifies the impact +- Has a plan with owners and dates +- Has a clear ask +- Sets expectations for next update + +--- + +## Template 3: Off-track / missed milestone + +When the milestone has been missed or will be. + +``` +Subject: [Project] off track: [milestone] will miss [date] + +Status: Off track + +We will miss the [date] milestone for [specific reason]. Revised target: [new date]. + +What happened: +[2-3 sentences of what specifically caused the miss. Direct, no euphemisms.] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we're doing: +- [Action 1] +- [Action 2] + +Lessons we're applying: +- [Lesson learned] + +What we need: +- [Specific ask, if any] + +Next milestone: [date for the next checkpoint] +``` + +Annotations: +- States the miss in the headline +- Names cause without scapegoating +- Quantifies impact +- Has a plan +- Includes lessons (shows learning, builds trust) +- Sets the next checkpoint + +--- + +## Template 4: Decision request + +When you need a decision from a stakeholder. + +``` +Subject: Decision needed: [decision] by [date] + +The decision: [What needs to be decided] + +Context (60 seconds): +[The minimum needed for someone to understand. Include only what's relevant.] + +Options: + +Option A: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option B: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Option C: [Name] +- What: [Description] +- Pros: [List] +- Cons: [List] +- Cost / time: [Specific] + +Recommendation: Option [X], because [reason]. + +Need by: [Date] + +Detail: [Link to fuller analysis] +``` + +Annotations: +- The decision is named at the top +- Context is bounded (60 seconds) +- Options are parallel in structure +- Recommendation is explicit +- Deadline is named + +--- + +## Template 5: Executive review + +For exec audiences: monthly, quarterly, or per major milestone. + +``` +Subject: [Initiative] exec review: [date] + +Headline: [One-sentence summary of the state of things] + +Key points: + +1. [Point 1 with one supporting sentence] +2. [Point 2 with one supporting sentence] +3. [Point 3 with one supporting sentence] + +Metrics: + +\| Metric \| Target \| Actual \| Trend \| +\|---\|---\|---\|---\| +\| [Metric 1] \| [Target] \| [Actual] \| ↑/↓/→ \| +\| [Metric 2] \| [Target] \| [Actual] \| ↑/↓/→ \| +\| [Metric 3] \| [Target] \| [Actual] \| ↑/↓/→ \| + +Decisions needed: +- [Decision 1: brief context, options summary, recommendation] +- [Decision 2: brief context, options summary, recommendation] + +Risks: +- [Top risk and mitigation] + +Asks: +- [Specific ask] + +Detail: [Link to fuller documentation] +``` + +Annotations: +- Executives skim. Headline carries the load. +- 3 key points (not 7) +- Metrics in table form, with trend +- Decisions called out, with recommendations +- Detail is linked, not inlined +- One page max for the email body + +--- + +## Template 6: Launch announcement (internal) + +For announcing something shipped. + +``` +Subject: Launched: [Thing] + +We've launched [Thing]. + +What it is: +[1-2 sentences of plain description. What it does, who it's for.] + +Why it matters: +[1-2 sentences of impact. What problem it solves, what changes.] + +How to learn more: +- [Link to docs / demo / page] +- [Contact for questions] + +Thanks to: +[The team that did the work, by name] +``` + +Annotations: +- Short and clear +- Includes the why (not just the what) +- Acknowledges the team + +--- + +## Template 7: Asking for help + +When you need expertise, time, or introduction from a colleague. + +``` +Subject: [Specific ask]: [N] minutes + +Hi [Name], + +I'm working on [brief context, one sentence]. I'd value your help with [specific ask]. + +What I need: +- [Specific item 1] +- [Specific item 2] + +What I've already tried: +- [Approach 1, outcome] +- [Approach 2, outcome] + +Time I'm asking for: [N minutes / specific session / specific deliverable] +Need by: [Date or "no rush"] + +If you're not the right person, who would you suggest? + +Thanks, +[Name] +``` + +Annotations: +- Subject is specific +- Specific ask, not vague +- Shows you've tried (respect for their time) +- States time required +- Provides an out (suggest someone else) + +--- + +## Template 8: Update for skip-level / VP + +For your manager's manager. Shorter, sharper than direct-manager update. + +``` +Subject: [Initiative]: quick update + +[Initiative] is [on track / at risk] for [milestone]. + +Highlights: +- [Outcome 1] +- [Outcome 2] +- [Decision: what was decided] + +What's coming: +- [Next big milestone] + +Risks I'm watching: +- [Top risk] + +I'll come to you for: [specific upcoming need] + +Detail: [link] +``` + +Annotations: +- Half the length of a manager update +- Emphasizes outcomes, not activities +- "I'll come to you for" sets expectations on when you'll need them +- Detail is linked, not inlined + +--- + +## Template 9: Quarterly business review (QBR) + +Cross-functional, leadership audience. Substantive. + +``` +Subject: [Function/team] QBR: Q[N] + +Quarter at a glance: + +[3-sentence narrative summarizing the quarter] + +Goals vs results: + +\| Goal \| Target \| Result \| Status \| +\|---\|---\|---\|---\| +\| [Goal 1] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| +\| [Goal 2] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| +\| [Goal 3] \| [Target] \| [Result] \| ✅ / 🟡 / ❌ \| + +Wins this quarter: +- [Specific win 1] +- [Specific win 2] +- [Specific win 3] + +What didn't go as planned: +- [Specific miss 1: what happened, what we learned] +- [Specific miss 2: what happened, what we learned] + +Next quarter: +- [Top priority 1] +- [Top priority 2] +- [Top priority 3] + +Risks and asks: +- [Risk and what we're doing] +- [Ask if any] + +Headcount / budget changes: +[If relevant, brief] +``` + +Annotations: +- Narrative summary up front +- Goals table with clear pass/fail +- Wins AND misses (honest) +- Forward-looking section +- Asks are explicit + +--- + +## Template 10: Bad news, broader audience + +For when something significant has gone wrong and a wider audience needs to know. + +``` +Subject: [Plain description of what happened] + +[1 sentence: what happened, in plain language] + +What happened: +[2-4 sentences of specific facts. No euphemisms.] + +Who's affected: +- [Specific group 1] +- [Specific group 2] + +Impact: +- [Specific impact 1] +- [Specific impact 2] + +What we've done so far: +- [Action 1] +- [Action 2] + +What's next: +- [Action and timeline] +- [Action and timeline] + +If you have questions: +[Contact and channel] + +[Sign-off from named accountable person, with their role] +``` + +Annotations: +- Plain subject. No spin. +- Facts before reassurance +- Impact stated, not hedged +- Forward path is clear +- Named accountable person at the bottom +- Channel for questions + +--- + +## What to avoid in any template + +Vague status indicators. "Things are going well" is not status. On track / at risk / off track is. + +Activity dumps. "We met. We reviewed. We updated." Stakeholders care about what changed, not what you did. + +Hedge words on certainty. "We should probably maybe be on track." If you know, say it. If you don't, say what you don't know. + +Buried asks. Asks at the bottom in a paragraph go unread. Pull them out. Bold them. Make them findable. + +Different units in different sections. "5 days" in one place, "by next Tuesday" in another. Pick a convention and stick with it. + +Acronyms not understood by the audience. Especially across functions. Spell out on first use. + +No links. Detail in the email forces everyone to read the same wall of text. Link the detail. Let people choose. + +Missing accountable owner. Who owns each next step? If the answer is "the team," nothing happens. Name people. + +Inconsistent cadence. Update Monday, then nothing for three weeks, then a wall on a Friday. Set cadence. Hold it. + +--- + +## Customizing for your context + +The templates above are starting points. Customize for: +- Your organization's tone (formal vs casual) +- Your stakeholders' preferences (some want bullets, some want narrative) +- Your medium (email vs doc vs slide) +- Your project's complexity (more or less detail in the body) + +Whatever you customize, keep: +- Headline first +- Status indicator visible +- Asks explicit +- Owners and dates named +- Consistent structure across updates (so readers can scan reliably) diff --git a/skills/team-onboarding-playbook/SKILL.md b/skills/team-onboarding-playbook/SKILL.md new file mode 100644 index 0000000..180e5c4 --- /dev/null +++ b/skills/team-onboarding-playbook/SKILL.md @@ -0,0 +1,189 @@ +--- +name: team-onboarding-playbook +description: Design a structured onboarding experience that gets new team members productive in 30, 60, and 90 days. Use when a new hire is joining, when contractors or agency partners need to ramp up, when an existing team is restructuring and members are switching focus, or when current onboarding feels chaotic and slow. Also triggers when one person owns all the tribal knowledge and you need to capture it, when you keep losing people in their first 90 days, or when a new project has many fresh members joining at once. Useful for engineering, design, product, marketing, and operations roles. +category: process-and-team +catalog_summary: "30-60-90 onboarding plans for new hires and contractors" +display_order: 4 +--- + +A repeatable framework for building an onboarding playbook that ramps new team members predictably without burning out the people training them. + +## When to use + +- A new hire is joining and you do not have a written onboarding plan. +- An existing onboarding process is informal and inconsistent. +- A team is growing fast and onboarding is the bottleneck. +- A contractor or agency partner needs to ramp up quickly. +- A team member is leaving and their knowledge needs capturing. +- Onboarding currently takes too long and you want to reduce it. + +## When NOT to use + +- For ongoing performance management (different problem). +- For training on a specific technology (use targeted docs and tutorials). +- For documentation strategy in general (use `documentation-strategy`). +- For role definition or hiring (different upstream problem). + +## Required inputs + +- The role: what the person will do, what success looks like at 90 days. +- Existing artifacts: docs, runbooks, codebases, design files. +- The team: who will mentor, who will pair, who answers what kind of question. +- Tools and access: what accounts and systems the new person needs. +- Time budget: how much time team members can invest in onboarding. + +## The framework + +A good onboarding plan operates on 4 layers. Build all four. + +### Layer 1: Belonging (Day 1 to Week 1) + +The first week is mostly about belonging, not productivity. Get this right and everything else accelerates. + +- Welcome message before they start. +- Workspace and accounts ready before day 1. No "we will get to that". +- A buddy or onboarding partner assigned (someone other than the manager). +- Day 1 schedule that is not 8 hours of meetings, but is also not zero meetings. +- Introductions to the people they will work with regularly. +- A first-week rhythm: daily check-in with manager or buddy. + +### Layer 2: Context (Week 1 to Week 4) + +The next phase is context. The new person needs to understand the system before they can change it. + +- The product or business: what we do, who we serve, why we exist. +- The team: who owns what, how decisions get made. +- The technical or operational landscape: the architecture diagram, the main tools, the key files. +- The recent past: major decisions, recent launches, current priorities. +- Active projects: what is in flight and how it fits. + +A reading list is part of this. Keep it short. Annotated. Curated. + +### Layer 3: Contribution (Week 2 to Week 6) + +By week 2 or 3, the new person should be making real contributions. Not because they are fully ramped, but because contribution is how ramping happens. + +- A first task that is small, scoped, and shippable in week 2. +- Pairing or shadowing on a real piece of work in week 3. +- Independent ownership of a small project by week 4 or 5. +- Code review, design critique, or equivalent peer feedback from the start. + +The first task matters. Pick something that touches the main systems but cannot break anything important. Something that ships gives confidence and visibility. + +### Layer 4: Mastery (Month 2 to Month 3) + +By the end of 90 days, the new person should be a full member of the team. + +- Owning a project end to end. +- On-call or on-rotation if the team has one. +- Contributing to roadmap discussions, not just executing them. +- Mentoring or supporting the next new hire. + +90 days is a checkpoint, not a finish line. Document what worked and what was missing for the next person. + +## The 30/60/90 plan + +Every onboarding plan should have explicit milestones at 30, 60, and 90 days. + +### 30 days + +- Workspace, tools, and access fully set up. +- Has met every team member. +- Understands the product, the team, and the recent context. +- Has shipped or contributed to at least one real piece of work. +- Has a clear picture of their first major project or area. + +### 60 days + +- Owns a project or area independently. +- Knows where to find answers without asking every time. +- Has formed working relationships beyond the immediate team. +- Has made at least one meaningful improvement to a process, doc, or codebase. + +### 90 days + +- Fully productive in the role. +- Participating in roadmap and planning discussions. +- Capable of training the next new hire on parts of the system. +- Comfortable raising concerns and pushing back. + +If someone is significantly behind these markers at the 30/60/90 checkpoints, address it directly. Either the plan is wrong, the support is wrong, or the role fit is wrong. Hoping it resolves itself does not work. + +## The role-specific overlay + +The framework above applies to every role. The specifics differ. + +### Engineering + +- Day 1: dev environment running, first commit (a docs fix or trivial change). +- Week 1: read the architecture doc, read the main service code paths. +- Week 2: ship a small bug fix or refactor. +- Week 4: own a feature or component. +- Month 2: on-call shadow, then on-call. + +### Design + +- Day 1: design tools set up, design system access, brand guidelines reviewed. +- Week 1: studio crit and design review participation. +- Week 2: own a small surface (a setting page, an empty state). +- Week 4: lead a design review for a feature in flight. +- Month 2: own a feature design end to end. + +### Product + +- Day 1: read the strategy doc, the roadmap, and the latest 3 PRDs. +- Week 1: shadow customer calls, attend support sync, join standup of all relevant teams. +- Week 2: write a discovery doc or competitive analysis. +- Week 4: own a feature spec. +- Month 2: own a roadmap area. + +### Marketing or content + +- Day 1: brand voice doc, recent campaigns, top performing content. +- Week 1: customer research artifacts and persona docs. +- Week 2: ship a small piece of content (a social post, a blog edit). +- Week 4: own a content piece end to end. +- Month 2: own a campaign or channel. + +Adapt to your role and stack. The shape stays the same. + +## Workflow + +1. Start the playbook before the new person arrives. Do not write it on day 1. +2. Pre-stage accounts, hardware, and access. This is the most common day-1 failure point. +3. Assign a buddy. Tell the buddy what is expected of them. +4. Send the welcome message and the day-1 schedule before they start. +5. Run the first week with a focus on belonging and context, not output. +6. Check in daily for the first week, weekly for the first month. +7. Run formal 30/60/90 check-ins with explicit milestones. +8. After 90 days, do a retrospective: what worked, what was missing. +9. Update the playbook based on the retrospective. Onboarding is a living doc. + +## Failure patterns + +- No plan. Day 1 with no schedule, no laptop, no accounts. Sets a tone. +- Drinking from a firehose. 8 hours of meetings on day 1. People remember nothing. +- No real work for too long. Three weeks of "reading docs" is demoralizing. Ship something small early. +- All buddy, no manager. Buddies are great but cannot evaluate or advocate. Manager is still on the hook. +- Tribal knowledge as gating. "Just ask Sara if you have questions" works until Sara is on vacation. Document the answers Sara keeps giving. +- No 30/60/90 milestones. Onboarding "ends" when someone seems busy. That is not a milestone. +- Generic plan for every role. Engineering and marketing have different first-week needs. Use the role overlay. +- No retrospective. The same gaps catch every new hire because nobody updated the playbook. +- Buddy with no time. Assigning a buddy who is also drowning is a recipe for poor onboarding and burnout. Protect their time. +- Skipping the customer or product context. Engineers who do not know who the customer is build the wrong things. Marketers who do not know how the product works write thin copy. + +## Output format + +Deliverables: + +1. Pre-day-1 checklist: accounts, hardware, access, buddy assignment, welcome message. +2. Day-1 schedule: meeting list, intros, first deliverable. +3. First-week reading list: 5-10 curated, annotated docs. +4. 30/60/90 milestones: the explicit checkpoints for this role. +5. Buddy guide: what is expected of the onboarding partner. +6. Manager check-in cadence: scheduled 1:1s and milestone reviews. +7. Retrospective template: to fill out at 90 days for next-time improvement. + +## Reference files + +- [`references/onboarding-checklist.md`](references/onboarding-checklist.md): A day-by-day, week-by-week checklist for the first 30 days, with role-specific variants and a 30/60/90 review template. diff --git a/skills/team-onboarding-playbook/references/onboarding-checklist.md b/skills/team-onboarding-playbook/references/onboarding-checklist.md new file mode 100644 index 0000000..c82acb7 --- /dev/null +++ b/skills/team-onboarding-playbook/references/onboarding-checklist.md @@ -0,0 +1,214 @@ +# Onboarding checklist + +A day-by-day, week-by-week checklist for the first 30 days. Adapt the role-specific items to fit your team. + +## Before day 1 (1 week ahead) + +Manager prep: + +- [ ] Confirm start date and any logistics (remote, hybrid, in-office). +- [ ] Assign onboarding buddy. Brief them on expectations. +- [ ] Order hardware. Confirm delivery before start date. +- [ ] Create accounts: email, chat, source control, design tools, project management, calendar, password manager. +- [ ] Add to relevant team channels and meeting invites. +- [ ] Block manager calendar for daily check-ins in week 1. +- [ ] Send welcome email to new hire 3-5 days before start. Include: day-1 logistics, what to expect, where to be, what to bring. +- [ ] Notify the team via channel: who is starting, when, what role. +- [ ] Prep first task. Something small, scoped, shippable in week 1 or 2. + +## Day 1 + +Morning: + +- [ ] Welcome from manager (30 min, not 90 min). +- [ ] Tour of tools, accounts, and where things live. +- [ ] Lunch with buddy or team (whatever is normal for your team). + +Afternoon: + +- [ ] Read the welcome doc or onboarding hub. +- [ ] Set up local environment. Buddy or buddy-channel available for help. +- [ ] First commit, design upload, doc edit, or equivalent. Trivial. Just to validate the workflow. + +End of day: + +- [ ] 15-minute check-in with manager. How did it go. + +## Week 1 + +Goals: belonging and basic context. Not productivity. + +- [ ] Daily 15-minute check-in with manager. +- [ ] 1:1 with buddy at least twice. +- [ ] Read the curated reading list (5-10 docs, no more). +- [ ] Meet with 5-7 people they will work with. 30 minutes each. Casual. +- [ ] Attend team standup and one team meeting (without obligation to contribute). +- [ ] Submit at least one trivial fix or improvement (typo, doc clarification, small refactor). +- [ ] Set up time tracking, expense, or admin systems if your org uses them. +- [ ] Confirm hardware, software, and access are all working. + +End of week 1: + +- [ ] Manager check-in: what is unclear, what felt wrong, what is missing. + +## Week 2 + +Goals: contributing to real work, even in a small way. + +- [ ] Pair with a teammate on a real task. Half day to a full day. +- [ ] Take ownership of the first small task. Should be shippable in 3-5 days. +- [ ] Attend customer call, support sync, or equivalent customer touchpoint. +- [ ] Read the recent decision log or major PRDs from the last 3 months. +- [ ] First contribution to standups: what they are working on. + +End of week 2: + +- [ ] Manager check-in: how is the first task going. What is blocking. What feels overwhelming. + +## Week 3 + +Goals: independent ownership starts. + +- [ ] Ship the first small task. +- [ ] Take on a slightly larger task. 1-2 weeks of work. +- [ ] Participate in code review, design critique, or equivalent. +- [ ] Meet with 3-5 cross-functional partners (PM ↔ Eng, Design ↔ PM, etc.). +- [ ] Begin to recognize patterns: "this is the third time someone asked X, where is that documented?" + +End of week 3: + +- [ ] Buddy check-in: how is the experience. What is the new hire stuck on that they will not raise to the manager. + +## Week 4 / 30-day mark + +Goals: validate the ramp is on track. + +- [ ] Complete the first medium-sized project or be visibly in flight. +- [ ] Have a working mental model of the product, team, and stack. +- [ ] Have at least one improvement filed (a doc fix, process suggestion, automation). +- [ ] Manager 30-day review (see template below). + +## 30-day review + +Manager runs this with the new hire, in 1:1, around day 30. + +``` +30-day review for [name] + +What is going well: +- [Two or three things] + +What is unclear or hard: +- [Two or three things] + +What I have shipped or contributed to: +- [List] + +What I want to be doing more of: +- [List] + +What I want help with: +- [List] + +Manager observations: +- [What you have noticed] + +Action items: +- [Specific things to address before 60-day mark] +``` + +The output of the 30-day review is honest signal. If the new hire is behind, the manager addresses the cause, not the symptom. If they are ahead, accelerate. + +## 60-day milestones + +By day 60: + +- [ ] Owning a project or area independently. +- [ ] Asking targeted questions, not "how does anything work" questions. +- [ ] Has working relationships outside the immediate team. +- [ ] Has been on customer or user calls if applicable. +- [ ] Has flagged at least one process improvement. +- [ ] 60-day review complete. + +## 90-day milestones + +By day 90: + +- [ ] Fully productive in the role at expected level. +- [ ] Participating in planning and roadmap discussions. +- [ ] On call or on rotation if the team has one. +- [ ] Capable of teaching parts of the system to a peer. +- [ ] Has identified gaps in onboarding from their perspective. +- [ ] 90-day review and onboarding retrospective complete. + +## 90-day onboarding retrospective + +Run this with the new hire at the end of 90 days. Capture the answers. Update the playbook. + +``` +What was great about your onboarding: +- [List] + +What was confusing or hard: +- [List] + +What was missing: +- [List] + +What you would have liked on day 1: +- [List] + +What you would change for the next person: +- [List] + +What you wish you had known earlier: +- [List] +``` + +The output of this retro feeds the next version of the playbook. Without this loop, every new hire faces the same gaps. + +## Role-specific first tasks + +Examples of good first tasks (shippable in week 1-2): + +### Engineering + +- Fix a small bug from the bug tracker (not customer-blocking, but real). +- Add a missing test or improve a flaky one. +- Update a deprecated API call in one place. +- Improve a developer doc that has been out of date. + +### Design + +- Audit a small part of the product against the design system. +- Design an empty state, error state, or settings sub-page. +- Update an outdated illustration or asset. +- Document a component that is in production but not in the design system. + +### Product + +- Write a competitive analysis on one feature area. +- Document a customer pain point heard in support. +- Update a stale PRD with current state. +- Write a one-pager on a roadmap item that needs sharper framing. + +### Marketing / Content + +- Edit and update a stale blog post. +- Audit recent campaign performance and write a 1-page summary. +- Repurpose an existing piece of content into a new format. +- Write a short customer quote roundup or testimonial summary. + +The pattern: real, scoped, ships in days, low risk, builds context. + +## What "fully ramped" looks like + +A new hire is fully ramped when: + +- They no longer ask "how does this work" but "why was it built this way". +- They contribute to direction, not just execution. +- They identify gaps and fill them without being asked. +- They mentor or assist the next new hire. +- They push back on things that do not make sense. + +This usually lands somewhere between 90 and 180 days, depending on the role and the system's complexity. Track it. If 180 days passes and the person is still not at this bar, dig into why. diff --git a/skills/upgrade-flow-design/SKILL.md b/skills/upgrade-flow-design/SKILL.md new file mode 100644 index 0000000..da26f0f --- /dev/null +++ b/skills/upgrade-flow-design/SKILL.md @@ -0,0 +1,309 @@ +--- +name: upgrade-flow-design +description: "Designing free-to-paid conversion flows for SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. Honest about paywall-everywhere (gates everything aggressively), free-forever-trap (no upgrade path surfaces), and value-triggered-upgrade (paywall surfaces at moments of demonstrated value) patterns. Triggers on upgrade flow, paywall, free-to-paid, freemium conversion, trial conversion, plan upgrade, subscription upgrade, win-back flow, churn prevention. Also triggers when free-to-paid conversion is low, when paywalls are blocking the wrong moments, or when upgrade flows are being scoped for the first time." +category: growth-tooling +catalog_summary: "Designing free-to-paid conversion flows. Distinguishes paywall-everywhere (gates everything aggressively) from free-forever-trap (no upgrade path surfaces) from value-triggered-upgrade (paywall surfaces at moments of demonstrated value)" +display_order: 9 +--- + +# Upgrade Flow Design + +A senior product marketing director's playbook for designing free-to-paid conversion flows in SaaS products. Trigger moments, paywall design, value demonstration, upsell vs downsell, win-back flows, churn prevention. The discipline of asking for the upgrade at the moment the user has a reason to say yes. + +Most upgrade flows fail in one of two ways. They block meaningful product use behind paywalls so aggressively that users churn before reaching the moment that would justify paying. Or they offer a generous free tier with no upgrade path that ever surfaces; users get everything they need; conversion stays at single-digit percentages indefinitely. + +The upgrade flows that work do something different. They surface paywalls at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next; the user is positioned to say yes because the value is fresh. + +The voice is the senior product marketing director who has watched conversion rates double when paywalls were re-timed and watched them collapse when more aggressive paywalls were added. Practical, opinionated about the moments that earn the upgrade ask, willing to call out when the product's free tier is too generous to convert. + +When to use this skill: scoping a free-to-paid conversion flow for the first time, auditing paywalls that block conversion or never surface, designing the trigger moments that earn upgrade asks, or deciding plan structure that supports upgrades over time. + +--- + +## What this skill covers + +This skill spans free-to-paid conversion flows in SaaS products. The growth-tooling distinctions: + +- `lead-magnet-design` is top-of-funnel email capture. This skill is free-to-paid conversion in-product. +- `funnel-flow-architecture` is the cross-tool funnel architecture. This skill is the upgrade flow specifically. +- `upgrade-flow-design` (this skill) is trigger-moment design, paywall presentation, plan structure, win-back, churn prevention. +- `landing-page-copy` is pricing-page copy; lives downstream of this skill's plan-structure decisions. +- `pm-spec-writing` is the spec for engineers building the upgrade flow. + +The audience: product marketers, growth marketers, in-house product teams, agencies running SaaS conversion work for clients. + +Out of scope: cross-funnel architecture (covered by `funnel-flow-architecture`); pricing-page copy (covered by `landing-page-copy`); the engineering implementation; specific Stripe/Chargebee/Recurly/Paddle billing-platform configurations (those stay implementation-side). + +--- + +## The free-tier decision: freemium vs free-trial vs no-free + +Before designing the upgrade flow, decide the free-tier structure. + +Freemium (free-forever tier). + +- Users use the product indefinitely without paying. +- Paid tier offers more value (capacity, features, support). +- Conversion typically 2-5 percent; volume compensates. + +When it works: products with strong network effects, or where free users provide product value (data, content, virality). + +Free-trial (time-limited). + +- Users get full or near-full product for a defined period. +- After trial, must pay to continue. +- Conversion typically 10-25 percent of trial signups. + +When it works: products where the value is clear quickly; audiences willing to commit time before paying. + +Reverse trial. + +- Users start on paid plan; auto-downgrade to free after period. +- Less common; mixes signals; can produce surprise churn. + +No-free (paid-only). + +- No free tier; users pay to start. +- Conversion is from prospects rather than free users. +- Conversion rates depend on sales motion, not in-product upgrade flows. + +When it works: enterprise products, high-touch sales, products where free would dilute brand or capacity. + +The decision is upstream of upgrade flow design. Different free-tier structures warrant different upgrade flows. + +Detail in [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md). + +--- + +## Paywall-everywhere vs free-forever-trap vs value-triggered-upgrade + +The keystone framing. + +Paywall-everywhere. Paywall blocks meaningful product use. Free tier exists but is too constrained to demonstrate value. Users churn before reaching the moment that would justify paying. Cost: users who would have paid after seeing value never reach that moment; conversion suffers despite aggressive paywalling. + +Free-forever-trap. Generous free tier with no upgrade path that ever surfaces. Users get everything they need; never see why they would pay. Conversion rate stays at single-digit percentages indefinitely. Cost: the team has built a product users like for free; revenue does not follow because the upgrade ask never lands. + +Value-triggered-upgrade. Paywall surfaces at moments where the user has demonstrably gotten value. The user has hit a usage threshold, completed a flow, or otherwise demonstrated they are getting the product's promise. The upgrade ask is honest about what they get next. Cost: design effort upfront is significant; conversion typically meaningfully higher than either alternative. + +The litmus test. After a user encounters the upgrade flow, can they articulate why they should pay? "Because I just hit my limit on this feature I have used 200 times" is value-triggered. "Because the product told me to pay before letting me use it" is paywall-everywhere. "I have not seen an upgrade ask" is free-forever-trap. + +--- + +## Trigger-moment design: where paywalls earn their interruption + +The single most consequential decision in upgrade flow design. + +The principle. Paywalls surface at moments where the user has demonstrated they are getting the product's value. The interruption is justified because the user has a reason to say yes. + +Strong trigger moments. + +- Usage threshold reached. User has used a feature N times; further use requires paid plan. Honest because they are clearly getting value. +- Capacity limit hit. User has reached free-tier capacity; upgrade unlocks more. Predictable; expected. +- Advanced feature attempted. User clicked into a feature that requires paid plan. Interest is fresh. +- Workflow completed successfully. User has seen value through a completed action; upgrade ask connects that value to recurring access. +- Team-collaboration moment. User wants to invite teammates; team capabilities require paid plan. +- Time-trial ending. Trial-based products surface upgrade as trial nears end. + +Weak trigger moments. + +- First-login. User has not yet seen value; upgrade ask is premature. +- Random in-product placement. Paywall on the dashboard with no specific trigger; users dismiss. +- Every-page banner. Persistent upgrade banner across all surfaces; users develop blindness. + +The discipline. Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +Detail in [`references/trigger-moment-design.md`](references/trigger-moment-design.md). + +--- + +## Paywall presentation: modal vs banner vs inline + +How the paywall surfaces. + +Pattern A: Modal paywall. Full-screen overlay blocks the action; user must upgrade or dismiss. + +When to use. Capacity limits, feature gates the user has hit. The interruption is warranted by the trigger. + +Pattern B: Banner paywall. Persistent banner at top of page suggesting upgrade. + +When to use. Soft prompts; awareness without interruption. Risk of becoming visual noise. + +Pattern C: Inline paywall. Upgrade ask embedded in the surface where the trigger occurred. + +When to use. Contextual prompts that integrate with the workflow. + +Pattern D: Toast or notification. Brief paywall surfaced as a notification. + +When to use. Soft prompts; low-priority upgrade asks. + +Choice criteria. + +- The trigger's strength determines the presentation's intensity. +- Strong triggers (capacity hit, feature gate) warrant modal. +- Soft triggers (general awareness) warrant inline or toast. + +Copy and value-prop discipline. + +- The paywall copy should connect to what the user just did. +- "You have used [feature] 50 times. Upgrade to remove the limit and unlock [related capabilities]." matches the trigger. +- "Upgrade for more features" is generic and weak. + +Detail in [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md). + +--- + +## Upsell vs downsell logic + +When the user does not accept the primary upgrade. + +Upsell. User is on basic plan; ask them to upgrade to higher tier. + +Cross-sell. User is paying; offer add-ons or related products. + +Downsell. User declined the higher tier; offer a smaller commitment (smaller plan, monthly vs annual, basic vs full feature set). + +The downsell discipline. Some users will not upgrade to the proposed tier but will upgrade to something. Downsell captures revenue otherwise lost. + +Examples. + +- User declined Pro upgrade; offer Starter plan as a path to begin paying. +- User declined annual plan; offer monthly with explicit cost difference disclosed. +- User declined full team plan; offer single-seat upgrade. + +Anti-pattern. Aggressive downsell that makes the user feel manipulated. Honest framing: "If Pro is more than you need, here is something that fits." + +Detail in [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md). + +--- + +## Win-back flow design + +Lapsed users, downgrades, partial-churn. + +Win-back triggers. + +- User has not logged in for 30/60/90 days. +- User downgraded plan. +- User canceled but did not delete account. +- User churned and signed up again later. + +Win-back patterns. + +- Email-based. Outreach with renewed value-prop, sometimes with discount or trial extension. +- In-product upon return. When the lapsed user returns, surface re-engagement help and (if appropriate) an upgrade-back ask. +- Personal outreach. For high-value lapsed users, sales or customer success conversation. + +Discount discipline. + +- Discounts to win back can create reverse-incentive (user churns to get discount). +- Discount sparingly; emphasize new value first. + +Detail in [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md). + +--- + +## Churn prevention upstream of upgrade + +The best upgrade flow is the one the user does not need because they did not churn. + +Upstream churn signals. + +- Declining engagement; sessions per week dropping. +- Last login distant. +- Support ticket pattern (frustration signals). +- Plan downgrade interest signals. + +Prevention patterns. + +- Engagement re-orientation. Surface help when engagement drops. +- Outreach. Customer success contact for high-value accounts at risk. +- Friction reduction. Audit the reasons users disengage; fix the friction. + +The prevention-vs-recovery economics. Preventing churn is much cheaper than winning back churned users. Invest upstream. + +Detail in [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md). + +--- + +## Plan structure: tier count, feature gating, pricing-page design + +The plans that the upgrade flow leads to. + +Tier count. + +- 2-tier (Free + Paid): simple; clear upgrade path; works for many products. +- 3-tier (Starter + Pro + Enterprise): broader audience; harder to design. +- 4+ tier: rarely better; complexity confuses users. + +Feature gating. + +- Capacity-based. Free tier limited by use volume; paid unlocks more. +- Feature-based. Free tier missing specific features; paid unlocks them. +- Hybrid. Both capacity and features differ. + +Discipline. Each tier should have a clear "this is for [X audience] because of [Y]." Tiers without clear audience-fit produce weak conversions. + +Pricing-page design. The pricing page is downstream of plan structure but lives close to upgrade flow. Detail in `landing-page-copy` for pricing-page copy specifically. + +Detail in [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md). + +- "Conversion rate is low; users churn before reaching upgrade." Paywall-everywhere; gates blocking value demonstration. +- "Conversion rate is single-digit; free users use the product for years." Free-forever-trap; no upgrade path surfaces. +- "Paywall fires; users dismiss; conversion does not lift." Trigger moments wrong; paywall not connected to demonstrated value. +- "Users hit paywall and churn." Wrong moment; paywall blocks before value is fresh. +- "Upgrade rate looks fine; downgrade rate is high." Plan structure wrong; users upgrade then realize they did not need the higher tier. +- "Win-back attempts have low conversion." Re-engagement timing wrong, or value-prop unchanged from what failed initially. +- "Annual plans not converting; monthly plans dominate." Annual value-prop weak; or commitment friction too high. +- "Sales says many leads come from churned users coming back." Win-back working but the previous churn was avoidable; audit upstream. +- "Conversion did not change after we redesigned the paywall." Paywall design was not the problem; trigger or plan structure may be. + +--- + +## The framework: 12 considerations for upgrade flow design + +When designing or auditing an upgrade flow, walk these 12 considerations. + +1. The free-tier decision. Freemium, free-trial, reverse trial, or no-free. +2. Value-triggered-upgrade, not paywall-everywhere or free-forever-trap. Paywalls at moments of demonstrated value. +3. Trigger-moment design sound. Paywalls connect to specific user-demonstrated value. +4. Paywall presentation matches trigger intensity. Strong triggers warrant modal; soft triggers inline. +5. Copy connects to the trigger. Specific value-prop tied to what the user just did. +6. Upsell, cross-sell, downsell logic. When primary upgrade is declined, secondary paths exist. +7. Win-back flows designed. Lapsed users have a clear re-engagement path. +8. Churn prevention upstream. Upstream signals trigger prevention; downstream upgrade flow is one of multiple defenses. +9. Plan structure clear. Tier count appropriate; each tier has clear audience-fit. +10. Pricing-page coordinates with upgrade flow. Plan structure decisions reflected on the pricing page. +11. Conversion as success metric. Not just paywall display; downstream conversion to paid. +12. Maintenance discipline. Plans, paywalls, win-back flows updated alongside product and pricing changes. + +The output of the framework is an upgrade flow that earns the user's "yes" by asking at the moment the user has a reason to say yes, with plan structure that fits the audience the product serves. + +--- + +## Reference files + +- [`references/free-tier-decision-criteria.md`](references/free-tier-decision-criteria.md) - Freemium, free-trial, reverse trial, no-free. Choice criteria. +- [`references/trigger-moment-design.md`](references/trigger-moment-design.md) - Where paywalls earn their interruption. Strong vs weak trigger moments. +- [`references/paywall-presentation-patterns.md`](references/paywall-presentation-patterns.md) - Modal, banner, inline, toast. Copy and value-prop discipline. +- [`references/upsell-vs-downsell-logic.md`](references/upsell-vs-downsell-logic.md) - When primary upgrade is declined, secondary paths. +- [`references/win-back-flow-patterns.md`](references/win-back-flow-patterns.md) - Lapsed users, downgrades, partial-churn re-engagement. +- [`references/churn-prevention-upstream.md`](references/churn-prevention-upstream.md) - Preventing churn before the upgrade flow is needed. +- [`references/plan-structure-patterns.md`](references/plan-structure-patterns.md) - Tier count, feature gating, audience-fit per tier. +- [`references/upgrade-flow-anti-patterns.md`](references/upgrade-flow-anti-patterns.md) - The patterns that look like upgrade flows but degrade trust. +- [`references/common-upgrade-failures.md`](references/common-upgrade-failures.md) - 9+ failure patterns with diagnoses and cures. + +--- + +## Closing: upgrade flows earn revenue when they earn the user's yes + +The upgrade flows that compound revenue are the ones that ask at the moment the user has a reason to say yes. Not because the paywall blocked them. Not because the upgrade prompt happened to appear. Because the user just did something that demonstrated value, and the upgrade ask connected that value to continued or expanded access. + +That is the bar. Below the bar are paywall-everywhere (gates before value, conversion suffers) and free-forever-trap (no upgrade path, conversion never starts). Above the bar are value-triggered-upgrade flows where trigger-moment design, paywall presentation, plan structure, win-back, and churn prevention work together to convert the right users at the right moments. + +The discipline is in the design choices. The free-tier decision (freemium, trial, paid-only) sets the funnel shape. Trigger-moment design decides when paywalls earn their interruption. Paywall presentation decides how the ask lands. Plan structure decides what the user is upgrading to. Win-back and churn prevention catch the cases that escaped the primary upgrade flow. diff --git a/skills/upgrade-flow-design/references/churn-prevention-upstream.md b/skills/upgrade-flow-design/references/churn-prevention-upstream.md new file mode 100644 index 0000000..d20876e --- /dev/null +++ b/skills/upgrade-flow-design/references/churn-prevention-upstream.md @@ -0,0 +1,250 @@ +# Churn prevention upstream + +Preventing churn before the upgrade flow is needed. + +The best upgrade flow is the one the user does not need because they did not churn. Investing upstream of churn produces more revenue than recovering churned users. + +--- + +## The prevention-vs-recovery economics + +Preventing churn is much cheaper than winning back churned users. + +The math. Cost of preventing one churn (engagement program, support intervention, friction reduction): X. Cost of winning back one churned user (outreach, discount, re-acquisition): often 3-10X. + +The implication. Programs that detect churn risk early and intervene save more revenue than win-back programs that activate only after churn. + +The discipline. Build upstream signals; intervene before churn happens. + +--- + +## Upstream churn signals + +What predicts churn. + +Engagement decline. + +- Sessions per week dropping over 4-week period. +- Time-in-product per session declining. +- Feature usage breadth narrowing. + +Engagement gap. + +- Last login distant. +- Specific feature stopped being used. +- Days since last meaningful action. + +Support pattern. + +- Support tickets indicating frustration. +- Multiple unresolved issues. +- Tone shift in support conversations. + +Plan-related signals. + +- Asked about cancellation. +- Researched competitors (sometimes detectable through partner data). +- Downgrade interest. + +Team-level signals (B2B). + +- Champion left the company. +- Team reduced seats internally. +- Decision-maker became unresponsive. + +The signals combine. Single signals are noisy; combinations predict more reliably. + +--- + +## Detection systems + +How to know which users are at risk. + +Engagement scoring. Composite score based on usage signals; threshold for at-risk classification. + +Health scores. Often used by customer success teams; combines product engagement, support pattern, contract data. + +Predictive models. Statistical or ML models that predict churn probability per user. + +Manual flags. Account managers flag accounts they sense are at risk. + +The discipline. Detection should be operationalized; signals should fire alerts to teams who can act. + +--- + +## Intervention patterns + +What to do when at-risk users surface. + +Pattern A: Engagement re-orientation. + +How it works. In-product help surfaces when engagement drops. Re-orients the user to value. + +When to use. Soft signals; users who may have forgotten what the product does for them. + +Pattern B: Outreach. + +How it works. Customer success or sales reaches out to at-risk accounts. + +When to use. High-value accounts; B2B contexts where personal touch matters. + +Pattern C: Friction reduction. + +How it works. Audit reasons users disengage; fix the friction. Often product changes rather than outreach. + +When to use. When patterns of disengagement reveal product issues. + +Pattern D: Educational re-engagement. + +How it works. Send the user content (case study, advanced feature explanation) that re-anchors value. + +When to use. Soft re-engagement; cheap to scale. + +Pattern E: Plan adjustment. + +How it works. If usage shows the user is over-paying, suggest a downgrade. Counterintuitive but builds trust. + +When to use. When the user is genuinely on the wrong plan; saves the relationship. + +--- + +## The engagement-re-orientation pattern + +In-product help that surfaces when engagement drops. + +Implementation. + +- Trigger fires when engagement signal drops below threshold. +- In-product surface shows: "It looks like you have not used [specific feature] in a while. Here is how others use it." +- Optional brief tour or case study. + +Strengths. + +- Cheap. +- Scalable. +- Often catches users who simply forgot. + +Weaknesses. + +- May feel intrusive. +- Cannot address all reasons for disengagement. + +--- + +## The customer success outreach pattern + +Personal contact for high-value accounts. + +Implementation. + +- Health score crosses at-risk threshold. +- Account manager or CS lead reaches out. +- Conversation: what is happening, what would help, can we address. + +Strengths. + +- Highest engagement potential. +- Surfaces real reasons. +- Builds relationship. + +Weaknesses. + +- Expensive. +- Only viable for accounts above revenue threshold. + +--- + +## The friction-reduction pattern + +Fixing the underlying reason rather than just intervening per user. + +Implementation. + +- Audit common reasons for disengagement. +- Identify product changes that would address. +- Ship the changes. + +Strengths. + +- Compounds across all users. +- Often the highest-impact intervention. + +Weaknesses. + +- Slower; requires product team prioritization. +- Some friction reasons cannot be product-fixed (audience-fit issues). + +--- + +## The educational-re-engagement pattern + +Send content that re-anchors value. + +Implementation. + +- Email or in-product content showing case studies, advanced features, or use cases. +- Targeted to the user's profile. + +Strengths. + +- Cheap and scalable. +- Educates without demanding immediate action. + +Weaknesses. + +- Lower engagement than personal outreach. +- May feel like marketing. + +--- + +## When intervention has limits + +Not all churn can be prevented. + +Genuinely unfit users. Some users signed up but are not the right audience. Their churn is appropriate. + +Genuinely changed needs. User changed jobs; product no longer relevant. Cannot be retained. + +Genuinely better alternatives. Competitor genuinely better fit. Recovery may not be appropriate. + +The honest assessment. Recognizing unpreventable churn is part of the discipline. Intervention should focus on preventable churn. + +--- + +## Churn prevention vs upgrade flow + +Different problems; complementary disciplines. + +Churn prevention. Keeps users engaged; avoids churn. + +Upgrade flow. Converts engaged users to paid (or higher paid). + +The interaction. Strong churn prevention produces engaged users; engaged users are the audience for upgrade flow. Programs running both produce more revenue than either alone. + +--- + +## Common prevention failures + +No detection. Churn happens; nobody flagged it; recovery is the only option. + +Detection without intervention. Signals fire but nobody acts. + +Intervention timing wrong. Action too late; user already disengaged emotionally. + +Generic intervention. Same outreach to all at-risk users; no segmentation. + +Discount-led intervention. Lead with discount instead of value; trains discount-seeking behavior. + +Prevention misses fixable friction. Patterns of disengagement reveal product issues; team focuses on per-user intervention instead. + +No measurement. Cannot tell if prevention reduces churn rate. + +--- + +## Methodology-level choices that stay in the public skill + +The prevention-vs-recovery economics. Upstream churn signals (5 categories). Detection systems. Intervention patterns A through E. When intervention has limits. Churn prevention vs upgrade flow interaction. Common failures. + +## Implementation choices that stay internal + +Specific signals and thresholds for specific products. Specific health-score formulas. Specific intervention copy and protocols. The team's CS staffing model. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/common-upgrade-failures.md b/skills/upgrade-flow-design/references/common-upgrade-failures.md new file mode 100644 index 0000000..bdc5116 --- /dev/null +++ b/skills/upgrade-flow-design/references/common-upgrade-failures.md @@ -0,0 +1,179 @@ +# Common upgrade failures + +9+ failure patterns with diagnoses and cures. + +--- + +## "Conversion rate is low; users churn before reaching upgrade." + +The diagnosis. Paywall-everywhere; gates blocking value demonstration. + +The cure. Loosen free tier. Surface paywalls at moments of demonstrated value. Detail in `references/trigger-moment-design.md`. + +--- + +## "Conversion rate is single-digit; free users use the product for years." + +The diagnosis. Free-forever-trap; no upgrade path surfaces. + +The cure. Add value-triggered paywalls. Connect upgrade asks to demonstrated value. + +--- + +## "Paywall fires; users dismiss; conversion does not lift." + +The diagnosis. Trigger moments wrong; paywall not connected to demonstrated value. + +The cure. Audit trigger logic. Each paywall should answer "what value did the user just demonstrate?" + +--- + +## "Users hit paywall and churn." + +The diagnosis. Wrong moment; paywall blocks before value is fresh. + +The cure. Move paywalls to moments of demonstrated value, not pre-value moments. + +--- + +## "Upgrade rate looks fine; downgrade rate is high." + +The diagnosis. Plan structure wrong; users upgrade then realize they did not need the higher tier. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit. Detail in `references/plan-structure-patterns.md`. + +--- + +## "Win-back attempts have low conversion." + +The diagnosis. Re-engagement timing wrong, or value-prop unchanged from what failed initially. + +The cure. Lead with value-prop change. Avoid discount-only win-back. Detail in `references/win-back-flow-patterns.md`. + +--- + +## "Annual plans not converting; monthly plans dominate." + +The diagnosis. Annual value-prop weak; or commitment friction too high. + +The cure. Strengthen annual value (better discount, additional features). Reduce commitment friction (easier mid-year cancellation, prorated refunds). + +--- + +## "Sales says many leads come from churned users coming back." + +The diagnosis. Win-back working but the previous churn was avoidable; audit upstream. + +The cure. Invest in churn prevention upstream. Detail in `references/churn-prevention-upstream.md`. + +--- + +## "Conversion did not change after we redesigned the paywall." + +The diagnosis. Paywall design was not the problem; trigger or plan structure may be. + +The cure. Test variables that matter. Trigger moment, plan structure, value-prop copy. Paywall presentation alone often does not move the needle. + +--- + +## "Upgrade flow works for new users; existing users do not upgrade." + +The diagnosis. Triggers designed for new-user behavior; existing users do not hit them. + +The cure. Segment trigger logic. Existing users may need different triggers (feature-launch upgrades, capacity-growth upgrades). + +--- + +## "Conversion increased but new customer churn climbed." + +The diagnosis. Paywall too aggressive; converting users who do not see value. + +The cure. Audit conversion-to-retention correlation. Aggressive conversion may produce buyer's remorse. + +--- + +## "Users complain about hidden charges after upgrade." + +The diagnosis. Pricing not transparent; users surprised by total cost. + +The cure. Surface all costs upfront. Annual price, monthly price, taxes if applicable. Hidden costs damage trust. + +--- + +## "Cancellation rate spikes 3 months after upgrade." + +The diagnosis. Upgrade was made but value did not materialize; users gave it 3 months and left. + +The cure. Post-upgrade welcome and onboarding. Surface paid features; help users access value of paid plan. + +--- + +## "Different audience segments convert at different rates; we cannot tell why." + +The diagnosis. Per-segment data not tracked. + +The cure. Per-segment conversion analytics. Different segments may need different upgrade flows. + +--- + +## "Win-back outreach has unsubscribe rate climbing." + +The diagnosis. Outreach too frequent or generic. + +The cure. Segment outreach. Respect non-response. Reduce frequency. + +--- + +## "We A/B tested annual vs monthly default; result was wash." + +The diagnosis. Default may not have been the issue; price-anchoring or commitment friction may be. + +The cure. Test different variables. Price level, discount magnitude, presentation order. + +--- + +## "Sales-led upgrades convert at higher rate than self-serve." + +The diagnosis. Self-serve flow misses something that sales touches address. + +The cure. Audit what sales does that the flow does not. Often: clarifies value, addresses objections, customizes recommendation. + +--- + +## "We added more upsell prompts; existing customer churn went up." + +The diagnosis. Prompt fatigue. Existing customers feel squeezed. + +The cure. Frequency limits on upsell. Less is often more. + +--- + +## "Conversion drops at the credit-card-entry step." + +The diagnosis. Form friction or trust signals missing. + +The cure. Optimize the credit-card form. Add trust signals (security badges, refund policy). Reduce required fields. + +--- + +## The pattern across failures + +Most upgrade flow failures fall into one of three patterns. + +Pattern 1: Paywalls at wrong moments. Paywall-everywhere, premature, unconnected, free-forever-trap. The fix is to align paywalls with demonstrated value. + +Pattern 2: Plan structure misaligned. Plan-paralysis, plan-mismatch, post-upgrade-empty. The fix is clearer tier audiences and post-upgrade experience. + +Pattern 3: Trust damage. Bait-and-switch, hidden-price, aggressive-downsell, hard-to-cancel. The fix is transparency and respect for the user. + +The metric pattern: upgrade flow failures often look fine on conversion alone. The signal is in retention post-upgrade, churn rate, win-back conversion. Programs that track only conversion keep shipping the same patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of failure patterns with diagnoses and cures. The pattern across failures (paywall timing, plan structure, trust). The principle that conversion alone is insufficient. + +## Implementation choices that stay internal + +Specific failure cases the team has encountered. Specific multi-metric dashboards. Specific cures. The team's audit and retirement processes. These vary by team. diff --git a/skills/upgrade-flow-design/references/free-tier-decision-criteria.md b/skills/upgrade-flow-design/references/free-tier-decision-criteria.md new file mode 100644 index 0000000..6111ee4 --- /dev/null +++ b/skills/upgrade-flow-design/references/free-tier-decision-criteria.md @@ -0,0 +1,253 @@ +# Free-tier decision criteria + +Freemium, free-trial, reverse trial, no-free. Choice criteria. + +The free-tier decision is upstream of upgrade flow design. The structure determines what the upgrade flow looks like, which trigger moments matter, and what conversion rates are achievable. + +--- + +## The free-tier decision matters + +Different free-tier structures warrant different upgrade flows. + +The win. A SaaS product chooses freemium because users provide product value (data, virality, network). Upgrade flow surfaces capacity-based paywalls. Conversion is 3 percent but volume produces meaningful revenue. + +The fail. Same product chooses free-trial without realizing user value matters more than time-bound trial. Trial ends; users churn rather than convert; the product loses the network effect users were providing for free. + +The decision is strategic; downstream design choices follow from it. + +--- + +## Pattern A: Freemium (free-forever tier) + +Users use the product indefinitely without paying. + +How it works. + +- Free tier offers core value with constraints (capacity limits, feature limits). +- Paid tier removes constraints or unlocks more. +- Users may stay free forever; conversion happens when they hit constraints they value enough to pay around. + +Conversion baseline. 2-5 percent typical for B2B SaaS; varies widely. + +Strengths. + +- Volume. +- Network effects from free users. +- Users provide product value (data, content, virality). +- Lower acquisition cost. + +Weaknesses. + +- Most users do not convert. +- Free-tier capacity costs. +- Plan-design pressure to gate the right things. + +When to use. Products with strong network effects, or where free users genuinely contribute to product value. + +--- + +## Pattern B: Free-trial (time-limited) + +Users get full or near-full product for a defined period. + +How it works. + +- Trial period (7-30 days typical). +- After trial, must pay to continue. +- Often credit-card-required at start (with auto-charge) or credit-card-not-required (with explicit conversion at end). + +Conversion baseline. 10-25 percent of trial signups; higher with credit-card-required. + +Strengths. + +- Strong commitment from users who start. +- Clear conversion deadline. +- Revenue arrives quickly post-trial. + +Weaknesses. + +- Friction at signup if credit card required. +- Users churn if trial ends before they reach value. +- Trial extension dynamics can become a negotiation. + +When to use. Products where value is clear within the trial period; audiences willing to commit time before paying. + +--- + +## Pattern C: Reverse trial + +Users start on paid plan; auto-downgrade to free after period. + +How it works. + +- Signup grants paid features for a defined period. +- After period, auto-downgrades to free tier. +- Users who want continued paid features upgrade. + +Conversion baseline. Moderate; mixes signals. + +Strengths. + +- Users see paid features; familiarity may drive conversion. +- Easier to start than credit-card-required trial. + +Weaknesses. + +- Surprise when downgrade hits. +- Some users dislike the loss-aversion framing. +- Less common; users may not know what to expect. + +When to use. When the team has tested both freemium and free-trial and reverse-trial outperforms; specific product-audience fits. + +--- + +## Pattern D: No-free (paid-only) + +No free tier; users pay to start. + +How it works. + +- Sales conversation or demo; user signs contract or starts subscription. +- No self-serve free path. + +Strengths. + +- Higher revenue per signup. +- Clearer signal of intent. +- No free-tier capacity costs. + +Weaknesses. + +- Lower top-of-funnel volume. +- Higher acquisition cost. +- Sales-motion dependent. + +When to use. Enterprise products, high-touch sales, products where free would dilute brand or capacity. + +--- + +## Pattern E: Hybrid + +Combining patterns. Most production products mix. + +Common combinations. + +- Freemium with free-trial of paid tier (free forever; trial of higher tier for free users). +- Free-trial with credit-card-not-required for self-serve, plus paid-only for enterprise. +- Reverse-trial for new users, freemium for users who downgrade at end of reverse-trial. + +The hybrid challenge. More complexity; more paths to maintain. Justify complexity with conversion data. + +--- + +## Choice criteria + +How to decide. + +Use freemium when: + +- Network effects matter; free users contribute value. +- Audience expects free; paid-only would limit reach. +- Conversion rate at scale produces meaningful revenue. + +Use free-trial when: + +- Value is clear within a trial period. +- Audience willing to commit time before paying. +- Conversion economics favor higher rate over higher volume. + +Use reverse-trial when: + +- Both freemium and free-trial have been tested and reverse-trial outperforms. +- Audience signal-strength is high (paid features get used). + +Use no-free when: + +- Audience is enterprise or high-touch. +- Product capacity costs prohibit freemium. +- Sales motion is the dominant funnel. + +Use hybrid when: + +- Different audience segments warrant different free structures. +- Data justifies the complexity. + +--- + +## Free-tier capacity design + +For freemium, the capacity decision. + +The principle. Free tier offers enough capacity to demonstrate value; not enough to replace paid tier. + +Capacity dimensions. + +- Use volume. Number of items, queries, exports per month. +- Capacity. Storage, seats, integrations. +- Feature set. Specific features paid only. +- Support level. Self-serve only on free; live support on paid. +- Branding. Free tier shows brand; paid removes. + +Design discipline. Free tier should let users hit the ah-ha moment; paid tier should be necessary for sustained or scaled use. Too generous: users do not convert. Too constrained: users do not reach ah-ha. + +--- + +## Trial period length + +For free-trial, how long. + +Common periods. + +- 7 days. Aggressive; works when ah-ha moment is clear and quick. +- 14 days. Common B2B; balances time-to-value with urgency. +- 30 days. Generous; works for products with longer evaluation cycles. +- 60+ days. Rare; usually reflects enterprise sales cycles. + +Decision factors. + +- Time-to-value of the product. +- Audience evaluation cycle. +- Conversion rate by trial length (test if uncertain). + +--- + +## Free-tier maintenance + +Free-tier structures decay. + +What decays. + +- Capacity limits set years ago no longer match current product capability. +- Features moved between tiers without comprehensive update. +- Audience composition shifted; old free-tier no longer fits. + +Maintenance cadence. Quarterly review of free-tier structure alongside pricing review. + +The decay-driven redesign. When refinements have not moved conversion, the free-tier structure may need redesign. + +--- + +## Common free-tier failures + +Free-tier too generous. Users get everything they need; conversion never starts. + +Free-tier too constrained. Users do not reach value; churn before conversion. + +Trial too short. Users do not reach ah-ha moment; trial ends with low conversion. + +Trial too long. Conversion incentive weak; users defer decision. + +Wrong free-tier structure for audience. Freemium chosen for enterprise audience that wanted no-free; adoption suffers. + +No maintenance. Free-tier static; conversion declines as product evolves. + +--- + +## Methodology-level choices that stay in the public skill + +The free-tier decision matters principle. Patterns A through E. Choice criteria. Free-tier capacity design. Trial period length. Maintenance considerations. Common failures. + +## Implementation choices that stay internal + +Specific free-tier structures for specific products. Specific capacity limits. Specific trial lengths. The team's pricing review calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/paywall-presentation-patterns.md b/skills/upgrade-flow-design/references/paywall-presentation-patterns.md new file mode 100644 index 0000000..a08b9ea --- /dev/null +++ b/skills/upgrade-flow-design/references/paywall-presentation-patterns.md @@ -0,0 +1,293 @@ +# Paywall presentation patterns + +Modal, banner, inline, toast. Copy and value-prop discipline. + +How the paywall surfaces. Done well, the presentation matches the trigger's intensity; done poorly, presentation fights the trigger and conversion suffers. + +--- + +## The presentation-matches-trigger principle + +Strong triggers warrant prominent presentation; soft triggers warrant subtle presentation. + +The win. A user hits a capacity limit; a modal surfaces explaining the limit and offering upgrade. The modal is justified because the trigger is hard (the user cannot continue without resolving). The user accepts the interruption. + +The fail. Same user, soft trigger (general awareness moment). A modal surfaces the same way. The interruption is not justified by the trigger; user resents. + +The discipline. Match presentation intensity to trigger strength. + +--- + +## Pattern A: Modal paywall + +Full-screen overlay blocks the action. + +How it works. + +- Modal overlay appears. +- User must engage (upgrade) or dismiss to continue. +- Often blocks the action that triggered it. + +Strengths. + +- Highest visibility. +- Clear demand for attention. +- Works for hard triggers (capacity hit, feature gate). + +Weaknesses. + +- Most disruptive. +- Easily abused; produces annoyance. + +When to use. Hard triggers where the user cannot proceed without resolution. + +--- + +## Pattern B: Banner paywall + +Persistent banner at top of page. + +How it works. + +- Banner remains visible across pages. +- Often dismissable for the session. +- Soft prompt; does not block action. + +Strengths. + +- Persistent awareness without blocking. +- Reaches users who have not hit hard triggers. + +Weaknesses. + +- Visual noise; users develop blindness. +- Cumulative exposure can feel like spam. + +When to use. Awareness campaigns. Use sparingly; persistent banners abused become noise. + +--- + +## Pattern C: Inline paywall + +Upgrade ask embedded in the surface where the trigger occurred. + +How it works. + +- Paywall content appears within the workflow. +- User reads in context; can act or scroll past. +- No overlay; no modal. + +Strengths. + +- Contextual; integrated with the workflow. +- Non-disruptive. +- Respectful of user momentum. + +Weaknesses. + +- Easier to miss. +- May not produce conversion if too easy to ignore. + +When to use. Soft triggers; awareness without interruption. + +--- + +## Pattern D: Toast or notification + +Brief paywall surfaced as a notification. + +How it works. + +- Small notification appears (often corner of screen). +- Auto-dismisses after time or on click. +- Brief content. + +Strengths. + +- Lightest weight. +- Easy to dismiss. + +Weaknesses. + +- Easy to miss entirely. +- Limited content. + +When to use. Soft prompts; low-priority awareness. + +--- + +## Pattern E: Hybrid + +Combining patterns. + +Common combinations. + +- Modal for hard triggers + inline for soft triggers. +- Banner for awareness + modal at hard trigger moments. +- Inline for in-feature prompts + modal at capacity limits. + +The hybrid discipline. Each presentation has a clear role; users do not see overlapping or competing paywalls. + +--- + +## Choice criteria + +Which presentation fits which trigger. + +Use modal when: + +- Trigger is hard (cannot proceed without resolution). +- Capacity limit reached. +- Feature gate hit. + +Use inline when: + +- Trigger is contextual but soft. +- User can continue without resolving. +- Workflow integration is the priority. + +Use banner when: + +- Awareness campaign across pages. +- Soft prompt for users who have not hit hard triggers. + +Use toast when: + +- Low-priority awareness. +- Brief acknowledgment. + +The simplest pattern that matches the trigger is usually right. Most upgrade flows benefit from inline + occasional modal. + +--- + +## Copy and value-prop discipline + +What the paywall says. + +The principle. Paywall copy should connect to what the user just did and what they get next. + +Strong copy patterns. + +- "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [advanced capabilities]." +- "You have hit your free tier's [capacity]. Upgrade to expand to [paid capacity]." +- "Inviting teammates requires our [team plan]. Upgrade to invite up to [number] teammates." + +What works: specific connection to user action; specific value of upgrade. + +Weak copy patterns. + +- "Upgrade for more features." (Generic; no connection.) +- "Get the full experience." (Vague; no specifics.) +- "Don't miss out." (FOMO without value.) + +What fails: no connection to user behavior; no specific value-prop. + +--- + +## Plan presentation in paywalls + +Showing the upgrade options. + +Single-plan paywall. One upgrade option presented. Simple; clear. + +When to use. When the upgrade is unambiguous (capacity hit; one obvious path). + +Multi-plan paywall. Two or three upgrade options presented (e.g., Pro vs Enterprise). + +When to use. When multiple plans could fit; let the user choose. + +Presentation discipline. + +- Highlight the recommended plan. +- Make pricing clear. +- Make value differences clear. + +Anti-pattern. Showing 5 plans in a paywall. Decision paralysis; user does not choose. + +--- + +## Pricing presentation + +How prices appear. + +Per-month vs per-year. Default to the user's likely commitment level; offer the alternative. + +Price anchoring. Show what the upgrade saves vs equivalent value (use carefully; can feel manipulative). + +Currency and locale. Match the user's locale. + +Discounts. Surface honest discounts (annual discount, promotion). Avoid fake urgency. + +--- + +## Action design + +The buttons and CTAs. + +Primary CTA. "Upgrade to Pro" with specific plan name. Bold; visible. + +Secondary CTA. "Maybe later" or "See plans." Allows decline without forcing. + +No third option. Two paths (upgrade or decline) preferred. Three or more paths confuse. + +The decline-respect principle. "Maybe later" should respect the decline. The same paywall should not re-fire immediately. + +--- + +## Paywall as opportunity to communicate value + +Even when the user declines, the paywall is a touchpoint. + +The principle. Paywall copy explains what paid offers in concrete terms. Even users who decline understand more about the paid plan than they did before. + +Why this matters. Future trigger moments find users with more context. The decline today may convert next month because the value is now understood. + +--- + +## Paywall analytics + +Track the paywall's performance. + +Metrics. + +- Display rate (how often does it surface?). +- Click rate (how many engage with upgrade button?). +- Conversion rate (of clicks, how many complete upgrade?). +- Decline rate (how many dismiss?). +- Re-show rate per declined paywall. + +Diagnostic uses. + +- High display, low click: copy or value-prop weak. +- High click, low conversion: friction in upgrade flow downstream. +- High decline rate: trigger may be wrong, or copy unclear. + +--- + +## Common presentation failures + +Wrong presentation for trigger. Modal on soft trigger; inline on hard trigger. + +Generic copy. Paywall does not connect to user behavior. + +Plan paralysis. Too many options in the paywall. + +Hidden price. User has to dig to find the cost. + +Decline ignored. Same paywall re-fires immediately after dismiss. + +Cumulative exposure. User sees too many paywalls per session. + +Mobile-broken paywall. Modal on mobile blocks all interaction. + +Loading delay. Paywall takes time to appear; user has moved on. + +--- + +## Methodology-level choices that stay in the public skill + +The presentation-matches-trigger principle. Patterns A through E. Choice criteria. Copy and value-prop discipline. Plan presentation. Pricing presentation. Action design. Paywall as value communication. Paywall analytics. Common failures. + +## Implementation choices that stay internal + +Specific paywall designs for specific products. Specific copy in brand voice. Specific tooling. The team's analytics dashboards. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/plan-structure-patterns.md b/skills/upgrade-flow-design/references/plan-structure-patterns.md new file mode 100644 index 0000000..da29b03 --- /dev/null +++ b/skills/upgrade-flow-design/references/plan-structure-patterns.md @@ -0,0 +1,240 @@ +# Plan structure patterns + +Tier count, feature gating, audience-fit per tier. + +The plans the upgrade flow leads to. Done well, plan structure makes upgrade decisions clear; done poorly, plan structure produces decision paralysis or upgrade-then-downgrade churn. + +--- + +## The clear-tier-fit principle + +Each tier should have a clear "this is for [audience] because of [reason]." Tiers without clear audience-fit produce weak conversions. + +The win. A SaaS analytics product has 3 tiers. Starter ("solo analysts and small teams"), Growth ("10-50 person analytics teams"), Enterprise ("complex analytics needs at scale"). Each tier maps to a specific audience; users self-select by recognizing themselves. + +The fail. Same product has 3 tiers labeled Bronze, Silver, Gold with feature checkmarks. Audiences cannot tell which is for them; many pick the wrong tier; downgrade rates climb. + +The discipline. Each tier has clear audience-fit articulated. + +--- + +## Tier count + +How many tiers. + +2-tier (Free + Paid). + +How it works. Free for some users, paid for everyone else. + +Strengths. Simple; clear upgrade path. + +Weaknesses. Cannot capture enterprise-tier revenue; cannot serve segmented audiences differently. + +When to use. Single-audience products; products with limited feature differentiation. + +3-tier (Starter + Pro + Enterprise). + +How it works. Three plans serving three audiences. + +Strengths. Captures entry-level, mid-market, and enterprise. Industry-standard. + +Weaknesses. Requires clear audience differentiation; can create decision paralysis if audiences are not clear. + +When to use. Most B2B SaaS products. Default for products with diverse audiences. + +4+ tier. + +How it works. Four or more plans. + +Strengths. Highly granular; serves many audiences. + +Weaknesses. Decision paralysis; users cannot tell which tier fits. + +When to use. Rarely. Most products do better with 3 tiers and add-ons rather than 4+ tiers. + +The simplest tier count that fits the audience is usually best. + +--- + +## Feature gating patterns + +How features differ between tiers. + +Pattern A: Capacity-based gating. + +How it works. All tiers have most features; tiers differ in volume (seats, queries, storage). + +Strengths. Clear upgrade trigger when capacity hit. Easy to understand. + +Weaknesses. Encourages users to optimize against limits. + +When to use. Products where capacity is the key cost driver. + +Pattern B: Feature-based gating. + +How it works. Lower tiers missing specific features; higher tiers unlock them. + +Strengths. Clear value differentiation between tiers. + +Weaknesses. Feature gating can feel arbitrary; users may want one paid feature but not the rest. + +When to use. Products with clearly tiered feature sets (basic vs advanced vs enterprise). + +Pattern C: Hybrid gating. + +How it works. Both capacity and features differ between tiers. + +Strengths. Most flexibility; serves diverse audiences. + +Weaknesses. More complex to communicate; feature comparison tables get long. + +When to use. Default for production B2B SaaS; most products benefit from hybrid. + +Pattern D: Service-based gating. + +How it works. Tiers differ in service level (support, onboarding, SLA). + +Strengths. Aligns with enterprise expectations. + +Weaknesses. Service costs scale with tier. + +When to use. Often for top tier (Enterprise); rarely the only differentiation. + +--- + +## Plan naming + +What to call the plans. + +Audience-named plans. "For solo creators," "For growing teams," "For enterprise." + +Strengths. Self-selecting; users know which fits. + +Weaknesses. Audience names age; "for startups" can feel limiting. + +Tier-named plans. "Starter," "Pro," "Enterprise" or "Basic," "Pro," "Premium." + +Strengths. Industry-standard; users recognize. + +Weaknesses. Generic; does not differentiate from competitors. + +Outcome-named plans. "Build," "Grow," "Scale." + +Strengths. Aspirational; aligns with user goals. + +Weaknesses. Vague; users may not know which outcome describes them. + +The discipline. Names should be specific enough that users self-select correctly. + +--- + +## Pricing structure + +How prices map to tiers. + +Per-seat. Cost scales with team size. + +When to use. Team collaboration products. + +Per-feature. Cost scales with feature set. + +When to use. Modular products. + +Per-usage. Cost scales with use volume. + +When to use. Capacity-driven products. + +Flat per-tier. Each tier has fixed price regardless of usage. + +When to use. Predictable-budget audiences (often enterprise). + +Hybrid pricing. Combinations of the above. + +When to use. Most production products use hybrid (per-seat with usage caps; flat tier with feature differences). + +--- + +## Annual vs monthly + +Commitment options. + +Monthly. Lower commitment; higher friction at cancellation; users can leave easily. + +Annual. Higher commitment; usually discounted; reduces churn but requires upfront payment. + +Both offered. Most products offer both; annual discount incentivizes commitment. + +Discipline. Discount on annual should reflect real value to the company (lower churn, predictable revenue) rather than arbitrary marketing percent-off. + +--- + +## Plan transition design + +How users move between plans. + +Free to paid. First commitment. Smooth experience matters most. + +Tier upgrade (within paid). From Pro to Enterprise. Often involves billing transition. + +Downgrade (within paid). From Enterprise to Pro. Should be friction-low to maintain trust; aggressive downgrade prevention damages trust. + +Cancellation to free. Some products auto-downgrade on cancellation; others fully cancel. Each has tradeoffs. + +The transitions should be smooth. Friction at transition damages trust. + +--- + +## Pricing-page coordination + +Plan structure decisions reflect on the pricing page. + +The principle. Plan structure decisions made for the upgrade flow appear on the pricing page. Users should see consistent information. + +The integration. Pricing-page copy (covered by `landing-page-copy`) implements the plan structure decisions made here. The two skills coordinate. + +--- + +## Plan maintenance + +Plans decay. + +What decays. + +- Capacity limits set years ago no longer match product capability. +- Features moved between tiers over time without comprehensive update. +- Pricing levels no longer match market. +- Tier audiences shifted. + +Maintenance cadence. Annual review at minimum; major product or market changes trigger more frequent. + +The decay-driven redesign. When plan structure no longer reflects reality, redesign rather than patch. + +--- + +## Common plan structure failures + +Too many tiers. Decision paralysis; users pick wrong tier. + +Tiers without clear audience-fit. Generic names without differentiation. + +Misaligned pricing. Prices that do not reflect value differences between tiers. + +Feature gating arbitrary. Features gated based on what is easy rather than what audiences need. + +No annual discount. Users default to monthly; cumulative revenue lower. + +Aggressive downgrade prevention. Users want to downgrade; friction damages trust. + +Plans not updated. Pricing or tiers from years ago no longer fit current product or market. + +Pricing-page mismatched. Plans on the page differ from plans in the upgrade flow. + +--- + +## Methodology-level choices that stay in the public skill + +The clear-tier-fit principle. Tier count guidance. Feature gating patterns A through D. Plan naming patterns. Pricing structure patterns. Annual vs monthly. Plan transition design. Pricing-page coordination. Plan maintenance. Common failures. + +## Implementation choices that stay internal + +Specific plans for specific products. Specific feature gating decisions. Specific pricing levels. Specific naming conventions. The team's pricing review calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/trigger-moment-design.md b/skills/upgrade-flow-design/references/trigger-moment-design.md new file mode 100644 index 0000000..7b4af5d --- /dev/null +++ b/skills/upgrade-flow-design/references/trigger-moment-design.md @@ -0,0 +1,217 @@ +# Trigger-moment design + +Where paywalls earn their interruption. Strong vs weak trigger moments. + +The single most consequential decision in upgrade flow design. Paywalls surface at moments where the user has demonstrated they are getting value. Get this wrong and conversion suffers regardless of paywall design quality. + +--- + +## The earned-interruption principle + +Each paywall should answer: what value did the user just demonstrate, and how does the paid plan extend that value? + +The win. User has used a feature 50 times. Hits the 50th-use limit. Paywall surfaces: "You have used [feature] 50 times this month. Upgrade to remove the limit and unlock [related advanced capabilities]." The trigger is fresh; the value is demonstrated; the user is positioned to say yes. + +The fail. Same user. Paywall surfaces on first login: "Upgrade for more features." User has not yet demonstrated value; the upgrade ask is premature; user dismisses. + +The discipline. Paywalls earn their interruption by connecting to recent demonstrated value. + +--- + +## Strong trigger moments + +Patterns that recur across products. + +Usage threshold reached. + +How it works. User has used a feature N times in a period. Further use requires paid plan. + +Why it works. The user clearly values the feature. The threshold is predictable; the paywall is honest about the constraint. + +Capacity limit hit. + +How it works. User reached free-tier capacity (storage, seats, queries). Upgrade unlocks more. + +Why it works. User encountered an unambiguous block. The block is part of the free-tier promise; the upgrade is the resolution. + +Advanced feature attempted. + +How it works. User clicked into a feature that requires paid plan. + +Why it works. Interest is fresh; the user wanted this specific feature. Upgrade ask connects to the specific interest. + +Workflow completed successfully. + +How it works. User completed an action that produced visible value (saved view, exported result, completed flow). Upgrade ask connects continuing or expanding that value to paid plan. + +Why it works. Value is fresh; user just experienced what the product does. Upgrade frames continuation. + +Team-collaboration moment. + +How it works. User wants to invite teammates; team capabilities require paid plan. + +Why it works. The collaboration intent is concrete; team capabilities are a clear value extension. + +Time-trial ending. + +How it works. Trial-based products surface upgrade as trial nears end. + +Why it works. Predictable; user expected it; the conversion conversation is timely. + +Multi-session usage. + +How it works. User has returned multiple times; engagement signal strong; soft upgrade prompt. + +Why it works. The user has demonstrated commitment through return; soft prompt fits. + +--- + +## Weak trigger moments + +Patterns that fail. + +First-login paywall. + +The pattern. Upgrade ask on first login. + +Why it fails. User has not yet seen value; the ask is premature. + +Random in-product placement. + +The pattern. Persistent paywall on the dashboard with no specific trigger. + +Why it fails. Not connected to user behavior; users develop blindness. + +Every-page banner. + +The pattern. Persistent upgrade banner across all surfaces. + +Why it fails. Visual noise; users learn to ignore. + +Paywall on the action the user expected free. + +The pattern. User believed a feature was free (because of marketing or onboarding); paywall surfaces when they try to use it. + +Why it fails. Trust damage. The user feels deceived. + +Paywall on irrelevant moments. + +The pattern. Paywall surfaces during user actions unrelated to the paid feature. + +Why it fails. Confusing; user does not connect the ask to anything. + +Paywall right after an error. + +The pattern. User just had a bad experience; immediately gets an upgrade ask. + +Why it fails. Tone-deaf; trust degrades. + +--- + +## Trigger moment design discipline + +Designing each trigger. + +Step 1: Identify the demonstrated value. What did the user just do that demonstrates value? + +Step 2: Identify the connection to paid. How does the paid plan extend or continue that value? + +Step 3: Time the ask. When in the user's flow does the ask land cleanly without breaking momentum? + +Step 4: Match presentation to importance. Strong triggers warrant modal; soft triggers inline. + +Step 5: Plan the response paths. What if user accepts? Declines? Asks for info? Each path designed. + +The output is a trigger moment that the user perceives as fair. + +--- + +## Trigger frequency + +How often paywalls fire. + +Per-trigger. A specific trigger should not fire repeatedly. Once it has fired and been declined, give space before re-asking. + +Cumulative session frequency. Total paywall exposures per session capped (often 1-2). Beyond that, additional triggers defer. + +Per-week. For users who use the product frequently, weekly cap prevents fatigue. + +The over-trigger trap. Each individual trigger looks reasonable; cumulative exposure is annoying. + +--- + +## Personalized trigger logic + +Different users may warrant different triggers. + +Power-user vs new-user. Power users may have different trigger thresholds; new users may need more time. + +Plan tier. Free users see free-to-paid triggers; paid users see paid-to-higher-paid triggers. + +Engagement frequency. Daily active vs returning monthly may warrant different timing. + +The discipline. Personalize where data justifies; do not over-segment. + +--- + +## Trigger testing + +Test triggers before launching. + +Test cases. + +- New user encounters trigger: appropriate timing? +- Returning user encounters trigger: re-fire respect? +- Power user encounters trigger: relevant? +- User who declined trigger encounters again: respectful? + +Production monitoring. + +- Per-trigger fire rate. +- Per-trigger conversion rate. +- Decline rate per trigger. +- Cumulative session exposure. + +The data informs which triggers earn their place and which should be retired. + +--- + +## Trigger maintenance + +Triggers decay. + +What decays. + +- Thresholds set years ago no longer match current usage patterns. +- Features the trigger references have changed or been deprecated. +- Audience composition shifted; old triggers no longer fit. + +Maintenance cadence. Quarterly review. Triggers that fire too often, too rarely, or with low conversion warrant attention. + +--- + +## Common trigger-moment failures + +Premature triggers. Asking before value is demonstrated. + +Unconnected triggers. Paywall not tied to the user's recent action. + +Over-frequent triggers. Cumulative exposure becomes noise. + +Stale triggers. Threshold values set long ago no longer match usage. + +Mistimed triggers. Right concept, wrong moment in the user's flow. + +Triggers right after errors. Tone-deaf placement after frustration. + +Triggers that violate free-tier promise. Asking the user to pay for something they were told was free. + +--- + +## Methodology-level choices that stay in the public skill + +The earned-interruption principle. Strong trigger moments (7 patterns). Weak trigger moments (6 patterns). Trigger moment design discipline. Trigger frequency. Personalized trigger logic. Trigger testing. Maintenance. Common failures. + +## Implementation choices that stay internal + +Specific triggers for specific products. Specific thresholds. Specific tooling. The team's audit calendar. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md b/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md new file mode 100644 index 0000000..3c9cb48 --- /dev/null +++ b/skills/upgrade-flow-design/references/upgrade-flow-anti-patterns.md @@ -0,0 +1,212 @@ +# Upgrade flow anti-patterns + +The patterns that look like upgrade flows but degrade trust. Easy to ship; the cost shows up in conversion, retention, and brand reputation. + +--- + +## The paywall-everywhere flow + +The pattern. Paywall blocks meaningful product use; free tier too constrained. + +The signal. Users churn before reaching value; conversion stays low despite aggressive paywalling. + +The cost. Users who would have paid after seeing value never reach it. + +The cure. Loosen the free tier; surface paywalls at moments of demonstrated value. + +--- + +## The free-forever-trap flow + +The pattern. Generous free tier; no upgrade path surfaces. + +The signal. Conversion stays at single-digit indefinitely. + +The cost. Product is loved free; revenue does not follow. + +The cure. Add value-triggered paywalls. Connect upgrade to demonstrated value. + +--- + +## The premature-paywall flow + +The pattern. Paywall on first login or before value is demonstrated. + +The signal. High dismiss rate; conversion does not lift. + +The cost. Users associate the brand with hard-sell early; some leave entirely. + +The cure. Move paywalls to moments of demonstrated value. + +--- + +## The unconnected-paywall flow + +The pattern. Paywall not connected to user behavior; appears at random or on every page. + +The signal. Visual noise; users develop blindness. + +The cost. Cumulative exposure becomes spam; trust degrades. + +The cure. Tie each paywall to specific user-demonstrated value. + +--- + +## The plan-paralysis flow + +The pattern. 5+ tiers presented in upgrade flow; users cannot decide. + +The signal. Click rate on plans is even across tiers; conversion does not match interest. + +The cost. Decision paralysis prevents conversion. + +The cure. Reduce tier count to 3. Recommend a default plan based on user signals. + +--- + +## The hidden-price flow + +The pattern. Prices buried; users have to dig to find them. + +The signal. Users abandon at the price-discovery step. + +The cost. Friction at the moment of decision; users leave. + +The cure. Surface prices clearly. Hidden pricing damages trust. + +--- + +## The decline-ignored flow + +The pattern. User dismisses paywall; same paywall fires immediately. + +The signal. Users disable tours globally; complain about persistent paywalls. + +The cost. Trust degrades; users may churn from the friction itself. + +The cure. Respect declines. Wait substantial time before re-asking. + +--- + +## The aggressive-downsell flow + +The pattern. User declines primary; multiple decline-and-counter rounds; user feels pressured. + +The signal. Users associate the brand with manipulation. + +The cost. Even users who eventually convert leave with negative impressions. + +The cure. One downsell at most. Respect the second decline. + +--- + +## The bait-and-switch flow + +The pattern. User believed feature was free (because of marketing); paywall surfaces when they try to use it. + +The signal. Users complain about deception; trust collapses. + +The cost. Long-term brand damage. + +The cure. Marketing and product align on what is free. No surprise paywalls on advertised-as-free features. + +--- + +## The discount-led-win-back flow + +The pattern. Win-back discount-only; no value-prop change. + +The signal. Re-engaged users churn again; users learn to lapse for discounts. + +The cost. Reverse incentive; lapse rate rises strategically. + +The cure. Lead with value-prop change; discount sparingly. + +--- + +## The aggressive-cancellation-prevention flow + +The pattern. User wants to cancel; flow makes cancellation hard (multi-step, hidden, support-only). + +The signal. Users complain publicly; brand earns "hard to cancel" reputation. + +The cost. Long-term trust damage; sometimes regulatory issue. + +The cure. Cancellation should be as easy as signup. Friction at exit damages reputation. + +--- + +## The plan-mismatch flow + +The pattern. Tier audiences not clearly differentiated; users pick wrong plan. + +The signal. Upgrade rate looks fine; downgrade rate climbs as users realize they picked wrong. + +The cost. Churn through dissatisfaction. + +The cure. Clarify tier audiences. Each plan should have specific audience-fit visible. + +--- + +## The post-upgrade-empty flow + +The pattern. User upgrades; nothing changes immediately. New features unlocked but not surfaced. + +The signal. Upgraded users do not engage with paid features they paid for. + +The cost. Buyer's remorse; downgrade rate climbs. + +The cure. Post-upgrade welcome; surface what changed; help users access new features immediately. + +--- + +## The aggressive-upsell flow + +The pattern. Customers paying already; upsell asks fire constantly. + +The signal. Customer fatigue; cross-sell rate drops over time. + +The cost. Existing customer relationship damaged. + +The cure. Frequency limits on upsell. Cross-sell at moments of relevance, not constantly. + +--- + +## The win-back-spam flow + +The pattern. Lapsed users get win-back outreach repeatedly without segmentation. + +The signal. Unsubscribe rate climbs; brand earns spammy reputation. + +The cost. Loses users who might have returned with better outreach. + +The cure. Segment win-back; respect non-response; abandon after reasonable attempts. + +--- + +## How to detect anti-patterns + +Audit cadence. Quarterly review of upgrade flows. + +Audit questions per flow. + +- Are paywalls connected to demonstrated value (anti-pattern check: paywall-everywhere, premature, unconnected)? +- Is decline respected (anti-pattern check: decline-ignored, aggressive-downsell)? +- Is plan structure clear (anti-pattern check: plan-paralysis, plan-mismatch)? +- Is pricing visible (anti-pattern check: hidden-price)? +- Is cancellation easy (anti-pattern check: aggressive-cancellation-prevention)? +- Does post-upgrade experience deliver (anti-pattern check: post-upgrade-empty)? +- Is win-back honest (anti-pattern check: discount-led, win-back-spam)? +- Is marketing-product alignment maintained (anti-pattern check: bait-and-switch)? + +The retire decision. Anti-pattern flows often warrant redesign or retirement. + +--- + +## Methodology-level choices that stay in the public skill + +The catalog of anti-patterns. Signal-pattern-cost framing for each. Cures matched. The audit cadence and questions. The retire decision. + +## Implementation choices that stay internal + +Specific anti-patterns the team has shipped historically and the lessons learned. Specific portfolio audit results. Specific retirement decisions. The team's audit calendar. These vary by team. diff --git a/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md b/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md new file mode 100644 index 0000000..f5497ed --- /dev/null +++ b/skills/upgrade-flow-design/references/upsell-vs-downsell-logic.md @@ -0,0 +1,214 @@ +# Upsell vs downsell logic + +When the user does not accept the primary upgrade. Secondary paths. + +Not every user accepts the proposed upgrade. The discipline is to capture revenue from users who would pay something but not the proposed amount, while respecting users who genuinely do not want to upgrade. + +--- + +## The secondary-path principle + +When the primary upgrade is declined, secondary options may capture revenue otherwise lost. + +The win. User is offered Pro plan ($X/month). Declines. System offers Starter plan ($X/3/month). User accepts Starter. Some revenue beats no revenue. + +The fail. User declines Pro; sees no other path; remains free; revenue is zero. + +The discipline. Design secondary paths thoughtfully; do not aggressive-downsell into manipulation. + +--- + +## Pattern A: Upsell + +User on basic plan; ask them to upgrade to higher tier. + +How it works. + +- Trigger fires when user demonstrates value of higher-tier features. +- Upgrade flow surfaces with the higher plan. + +Strengths. + +- Higher revenue per converted user. +- Aligned with demonstrated value. + +Weaknesses. + +- User may not need the higher tier; conversion can be poor. + +When to use. When the user has hit limits or used features that the higher tier addresses. + +--- + +## Pattern B: Cross-sell + +User is paying; offer add-ons or related products. + +How it works. + +- Trigger fires when user shows interest in adjacent capabilities. +- Cross-sell surfaces complementary product or add-on. + +Strengths. + +- Expands revenue from existing customer. +- Often easier than acquiring new customers. + +Weaknesses. + +- Risks fatigue if cross-sells are too frequent. +- Users may feel they are being squeezed. + +When to use. When add-ons or related products genuinely fit the customer's profile. + +--- + +## Pattern C: Downsell + +User declined the higher tier; offer a smaller commitment. + +How it works. + +- User dismisses upgrade. +- Secondary paywall offers a lower-tier plan, monthly instead of annual, or smaller seat count. + +Strengths. + +- Captures revenue from users not ready for the primary plan. +- Establishes paying relationship that may upgrade later. + +Weaknesses. + +- Aggressive downsell feels manipulative. +- Users may downgrade to the lowest option even when they would have paid more. + +When to use. When the primary plan is decline-prone; downsell catches users who would pay something. + +--- + +## Pattern D: Annual-vs-monthly downsell + +User declined annual; offer monthly. + +How it works. + +- Annual plan offered first (with discount). +- Decline; monthly offered as backup. + +Strengths. + +- Some users avoid annual commitment but accept monthly. +- Captures revenue from commitment-averse users. + +Weaknesses. + +- Cumulative revenue lower. +- Can train users to expect monthly when annual was the goal. + +When to use. When annual is the desired commitment but conversion suffers from upfront cost. + +--- + +## Pattern E: Seat-count downsell + +User declined full team plan; offer single-seat upgrade. + +How it works. + +- Team plan offered first. +- Decline; single-seat upgrade offered. + +When to use. When the user's situation suggests they would value paid features for themselves but cannot commit team-wide yet. + +--- + +## Downsell discipline + +When downsell crosses into manipulation. + +Honest framing. "If Pro is more than you need, here is something that fits your team size." + +Manipulative framing. Aggressive flow that pressures the user. Multiple decline-and-counter rounds. Hidden costs. Switching plan terms after acceptance. + +The discipline. Downsell respects the decline; offers an alternative; does not pressure. + +--- + +## When NOT to downsell + +Some declines should be respected. + +The user explicitly does not want any plan. Continued upgrade asks become harassment. + +The user has signaled disengagement. Aggressive downsell on a disengaged user accelerates churn. + +The user is on a free tier that fits. Forcing an upgrade where the user is happy on free degrades trust. + +The user is in a bad moment. After an error, support ticket, or negative experience, downsell is tone-deaf. + +--- + +## Sequencing upsell, cross-sell, downsell + +In a typical flow. + +Step 1: Primary upgrade ask (matched to trigger). +Step 2 (if declined): Downsell (smaller commitment alternative). +Step 3 (if declined): Soft acknowledgment ("No problem; here is the link to plans whenever you are ready."). +Step 4 (later): Cross-sell (when the user has continued use signals). + +The flow respects each decline before re-engaging at a later moment. + +--- + +## Frequency limits across upsell/downsell + +How often these surface. + +Within session. Once primary + once downsell + soft acknowledgment. No more. + +Across sessions. Wait days or weeks before re-ask. The user's circumstances may have changed. + +Per quarter. Major upgrade pushes per quarter at most. + +--- + +## Conversion economics of upsell vs downsell + +Different patterns have different revenue dynamics. + +Upsell. Higher revenue per converted user. Lower conversion rate. + +Cross-sell. Adds revenue per existing customer. Conversion depends on fit. + +Downsell. Lower revenue per converted user. Higher conversion rate. Captures users who would otherwise stay free. + +The math question. Total revenue = (upsell rate × upsell revenue) + (downsell rate × downsell revenue) + (free-to-paid rate × paid revenue). Optimize the sum. + +--- + +## Common upsell/downsell failures + +Aggressive downsell rounds. Multiple decline-and-counter loops; user feels manipulated. + +Downsell that breaks the upsell. Users learn to decline upsell to get downsell discount. + +No downsell. Users decline primary; revenue is zero. + +Cross-sell fatigue. Customers see too many cross-sells; resent. + +Wrong sequencing. Cross-sell before user has paid first plan. + +No frequency limits. Cumulative upgrade asks become spam. + +Tone-deaf timing. Downsell after a customer support escalation. + +--- + +## Methodology-level choices that stay in the public skill + +The secondary-path principle. Patterns A through E (upsell, cross-sell, downsell, annual-vs-monthly, seat-count). Downsell discipline. When NOT to downsell. Sequencing logic. Frequency limits. Conversion economics. Common failures. + +## Implementation choices that stay internal + +Specific upsell, cross-sell, downsell flows for specific products. Specific copy. Specific tooling. The team's revenue economics modeling. These vary by team and product. diff --git a/skills/upgrade-flow-design/references/win-back-flow-patterns.md b/skills/upgrade-flow-design/references/win-back-flow-patterns.md new file mode 100644 index 0000000..80eb6ab --- /dev/null +++ b/skills/upgrade-flow-design/references/win-back-flow-patterns.md @@ -0,0 +1,240 @@ +# Win-back flow patterns + +Lapsed users, downgrades, partial-churn re-engagement. + +When users disengage, downgrade, or churn, win-back flows attempt to bring them back. Done well, win-back captures revenue from users who left due to specific (often fixable) reasons; done poorly, win-back becomes spam that confirms the user's decision to leave. + +--- + +## The respect-the-decline principle + +Users who left often left for reasons. Win-back should be honest about the reasons and offer something genuinely changed, not just a discount. + +The win. A user lapsed 60 days ago. Win-back email surfaces with: "Since you last logged in, we shipped [specific feature you mentioned wanting]. Want to try it?" The user returns; the value-prop is fresh. + +The fail. Same user. Win-back email surfaces with: "We miss you! Come back for 20 percent off." The user dismisses; the discount feels like manipulation; the previous problems remain. + +The discipline. Win-back is most effective when something has changed (new feature, fixed problem) the user would value. + +--- + +## Win-back triggers + +When to fire. + +User has not logged in for 30 days. Soft trigger; light re-engagement. + +User has not logged in for 60-90 days. Moderate trigger; more substantive re-engagement. + +User has not logged in for 6+ months. Aggressive trigger; usually the last attempt before treating as fully churned. + +User downgraded plan. Trigger surfaces post-downgrade; win-back attempts to retain the higher tier. + +User canceled but did not delete account. Soft trigger; re-engage before full churn. + +User churned and signed up again. Different trigger; usually treat as new signup with prior context. + +The triggers vary by product and audience. + +--- + +## Pattern A: Email-based win-back + +Outreach with renewed value-prop. + +How it works. + +- Email sent to lapsed user. +- Content focuses on what has changed since they left. +- May include discount or trial extension. + +Email design discipline. + +- Subject line concrete; not generic "we miss you." +- Body specific to what has changed. +- One clear CTA back to product. +- Easy unsubscribe; respect users who do not want re-engagement. + +Strengths. + +- Cheap; can scale. +- Reaches users outside the product. + +Weaknesses. + +- Easy to feel like spam. +- Email deliverability for lapsed users is harder. + +When to use. Default for lapsed-user re-engagement. + +--- + +## Pattern B: In-product upon return + +When a lapsed user returns, surface re-engagement help. + +How it works. + +- User logs in after long absence. +- In-product surfaces re-orientation and (if appropriate) upgrade-back ask. + +Design. + +- Welcome-back banner with what has changed. +- Brief tour of new features added during absence. +- Soft upgrade-back if user downgraded. + +Strengths. + +- The user has already returned; engagement is fresh. +- Can be specific to the user's prior usage. + +Weaknesses. + +- Misses users who do not return on their own. + +When to use. When email or other re-engagement has produced a return. + +--- + +## Pattern C: Personal outreach + +For high-value lapsed users, sales or customer success conversation. + +How it works. + +- Customer success or sales reach out directly. +- Often via email or call. +- Conversation about what changed for the user; what would bring them back. + +Strengths. + +- Highest engagement potential. +- Surfaces real reasons; can address them. + +Weaknesses. + +- Expensive; only viable for high-value accounts. +- Risk of harassment if not done well. + +When to use. Enterprise lapsed accounts, high-revenue lapsed customers, accounts with strategic value. + +--- + +## Pattern D: Offer-based win-back + +Discount or trial extension as primary motivator. + +How it works. + +- Offer (e.g., 30 percent off, 3 months free, extended trial) presented to lapsed user. +- Limited time; explicit terms. + +Strengths. + +- Can move users who left for cost reasons. +- Easy to implement. + +Weaknesses. + +- Can train users to lapse intentionally to get discounts. +- Discount alone does not address why they left. + +When to use. Sparingly. Combine with value-prop changes; do not lead with discount alone. + +The discount-as-only-strategy failure. Discounts to win back can create reverse incentives. If users learn that lapsing gets them discounts, lapse rate climbs strategically. + +--- + +## Win-back sequence design + +A multi-touch win-back rather than single email. + +Typical sequence. + +- Day 30: light re-engagement (what's new). +- Day 60: more substantive (specific feature; case study). +- Day 90: explicit win-back offer (if appropriate). +- Day 120: final outreach; respect non-response. +- Beyond Day 120: treat as fully churned. + +The sequence respects the user's silence; multiple touches at different intensities. + +--- + +## When to abandon win-back + +Some users genuinely do not want to come back. Respect that. + +Signals to stop. + +- User unsubscribed from emails. +- User explicitly stated they do not want contact. +- Multiple win-back attempts produced no response. +- User left for reasons unfixable by the product (changed jobs, changed needs). + +The respect-the-no principle. Continuing win-back after clear no signals is harassment. + +--- + +## Discount discipline in win-back + +When discounts make sense. + +Use discount when: + +- The user explicitly stated cost was a factor. +- The product's price has not changed but the user's situation has. +- A time-limited promotion is genuinely available. + +Avoid discount when: + +- The user left for non-cost reasons (poor experience, missing features). +- The discount would train lapse-for-discount behavior. +- The discount cannibalizes existing customer revenue. + +--- + +## Win-back analytics + +Track effectiveness. + +Metrics. + +- Re-engagement rate (lapsed users who returned after win-back outreach). +- Conversion rate (returned users who paid or upgraded back). +- Retention of returned users (do they stay or lapse again?). + +Diagnostic uses. + +- Low re-engagement: outreach not relevant or not delivered. +- High re-engagement, low conversion: returns happen but value-prop weak. +- Returns lapse again quickly: underlying issue not fixed. + +--- + +## Common win-back failures + +Generic outreach. "We miss you" with no specifics; user dismisses. + +Discount-only strategy. Discount without value-prop change; trains lapse-for-discount. + +Frequency overload. Too many win-back attempts; harassment. + +No segmentation. Same outreach to all lapsed users regardless of why they left. + +Ignoring unsubscribes. Outreach continues despite explicit no. + +No measurement. Cannot tell if win-back works. + +Returns-lapse-again. Win-back succeeds short-term; underlying issue persists; user lapses again. + +--- + +## Methodology-level choices that stay in the public skill + +The respect-the-decline principle. Win-back triggers. Patterns A through D (email, in-product, personal, offer-based). Win-back sequence design. When to abandon. Discount discipline. Win-back analytics. Common failures. + +## Implementation choices that stay internal + +Specific win-back sequences for specific products. Specific outreach copy in brand voice. Specific discount levels. The team's segment-specific approaches. These vary by team and product. diff --git a/skills/usability-testing/SKILL.md b/skills/usability-testing/SKILL.md new file mode 100644 index 0000000..26f0a9e --- /dev/null +++ b/skills/usability-testing/SKILL.md @@ -0,0 +1,238 @@ +--- +name: usability-testing +description: "Plan and run usability tests on existing or prototype designs including test design, task scripts, moderation, observation, and findings synthesis. Use this skill whenever the user wants to test usability, run a moderated test, run an unmoderated test, validate a design, find usability issues, or improve task completion. Triggers on usability test, usability testing, moderated test, unmoderated test, task script, think aloud, prototype testing, user testing, design validation, task completion. Also triggers when the user has built something and wants to know if real users can use it before shipping." +category: research +catalog_summary: "Test design, moderation, findings reports" +display_order: 2 +--- + +# Usability Testing + +Plan and run tests that find usability problems before users hit them in production. Stack-agnostic. Tool-agnostic. + +This skill is for testing existing designs or prototypes. For broader discovery research, use `ux-research`. For conversion testing in production, use `cro-optimization`. + +--- + +## When to use + +- Before launching a new flow or major redesign +- After a redesign to verify it doesn't introduce new problems +- When analytics show drop-off but you don't know why +- When customer support tickets pattern around specific UI areas +- Pre-launch user validation +- Comparing two design directions + +## When NOT to use + +- Discovery / generative research (use `ux-research`) +- Live conversion optimization (use `cro-optimization`) +- Mapping the broader experience (use `journey-mapping`) +- Pure quantitative measurement (use `analytics-strategy`) + +--- + +## Required inputs + +- The design or prototype to test (functional or near-functional) +- Specific tasks users would do +- The audience (who should be tested) +- Testing infrastructure (moderated tool, unmoderated tool, in-person setup) + +--- + +## The framework: 5 phases + +### 1. Define what to test + +Don't test the whole product. Test specific tasks. + +Task selection criteria: + +- The task represents a real user goal (not "click around and explore") +- The task has a clear start and end +- The task is achievable in 2 to 10 minutes +- The task is one of: most common, most strategic, most problematic + +Examples of testable tasks: + +> "You want to find a contractor near you who can install a fence. Show me how you'd do that on this site." + +> "You're a first-time visitor. You want to understand if this product fits your needs. Walk me through how you'd evaluate it." + +> "Your team needs a new tool to manage projects. Use this site to figure out which plan is right for a 12-person team." + +Task framing rules: + +- State the user goal, not the system action ("find a place to stay" not "click the search button") +- Provide context (why are you doing this?) +- Don't reveal the path +- Don't use product terminology in the task framing + +### 2. Choose moderated or unmoderated + +Moderated (live, with researcher): + +- Researcher observes and probes in real time +- Best for early-stage prototypes, complex tasks, novel concepts +- Higher cost, smaller sample (5 to 8 participants typical) +- Catches surprises and probe deeper + +Unmoderated (recorded, asynchronous): + +- Participant completes alone, often via tool (UserTesting, Maze, Lookback) +- Best for stable designs, simple tasks, larger sample +- Lower cost, larger sample (15 to 30 participants typical) +- Catches patterns at scale, less depth per session + +For most teams: moderated for early/critical decisions, unmoderated for ongoing validation. + +### 3. Recruit + +Target audience - not just convenience. + +Recruit criteria: + +- Match real users (target audience, not just "anyone") +- Mix of experience levels with the product (new and existing if applicable) +- Mix of relevant device types (mobile, desktop, tablet if relevant) +- Exclude friends, family, employees + +Sample size: + +- Moderated: 5 to 8 participants (Nielsen's "5 users find 85% of usability issues" for the most common segment) +- Unmoderated: 15 to 30 participants (more participants compensate for less probing) +- Multi-segment testing: 5 to 8 per segment + +### 4. Run the test + +Pre-task setup: + +- Confirm recording works +- Brief participant (purpose, anonymity, recording, "no wrong answers") +- Get verbal consent +- Have participant share screen if remote + +Moderated session structure: + +1. Warm-up (2 to 3 min). Easy questions to put participant at ease. +2. Pre-test questions (3 to 5 min). Background context, current behavior with similar products. +3. Task 1 (5 to 10 min). Describe task. Have participant attempt while thinking aloud. +4. Post-task questions (1 to 2 min). What was easy/hard? Anything confusing? +5. Repeat for tasks 2, 3, 4 (typically 3 to 5 tasks per 60-minute session). +6. Overall debrief (5 to 10 min). General reactions, comparisons to alternatives, anything else. +7. Close (2 min). + +Moderation principles: + +- Encourage think-aloud ("What's going through your mind?") +- Don't help unless they're truly stuck (and even then, only after a long pause) +- Don't lead ("Are you looking for the menu?" - bad) +- Note where they hesitate, scroll, or backtrack +- Note their language vs the product's language +- Note emotional reactions + +Anti-patterns: + +- Talking too much (researcher should talk maybe 20% of the time) +- Defending the design when participants struggle +- Helping prematurely +- Asking participants to predict their future behavior +- Treating participant suggestions as features ("Users want X" - test demand for X separately) + +### 5. Synthesize and report + +Patterns across participants are signal. Single-participant complaints are weaker (but worth investigating). + +Synthesis steps: + +1. Issue inventory. Every issue observed, with which participant, which task, severity. +2. Cluster. Issues that are the same root problem. +3. Severity. + - Critical: Blocks task completion. Most users hit this. + - Major: Significantly slows task. Many users hit this. + - Minor: Friction. Some users hit this. Workaround exists. + - Cosmetic: Polish. Doesn't affect task. +4. Recommendations. For each issue, propose specific fixes. +5. Prioritize. By severity and effort. + +Report structure: + +```markdown +# Usability Test: [Design / flow] + +## Summary +[2 to 3 paragraphs covering: what was tested, headline findings, top 3 priorities] + +## Method +[Moderated/unmoderated, sample size, audience, dates, tasks] + +## Critical findings +[Each with description, frequency, supporting evidence (quotes/clips), recommendation] + +## Major findings +[Same structure] + +## Minor findings +[Brief] + +## Cosmetic findings +[Briefest] + +## What worked well +[Calibration: capture successes too] + +## Recommendations +[Prioritized list with effort estimates] + +## Next steps +[Test re-run schedule, design iteration plan] +``` + +--- + +## Workflow + +1. Define the goals. What decisions hinge on this? What tasks matter most? +2. Design tasks. 3 to 5 specific, realistic, goal-framed tasks. +3. Choose moderated vs unmoderated. Match to stage and depth needed. +4. Recruit. Specific to audience. +5. Pilot. 1 to 2 sessions before main batch. Refine tasks if needed. +6. Run. Follow the protocol. Stay disciplined. +7. Synthesize during, not just after. Patterns emerge by session 4 or 5. +8. Report. Multiple formats - written report + highlight clips. +9. Track fixes. Every critical issue should have an owner and date. +10. Re-test after fixes. Verify the fix worked, didn't introduce new issues. + +--- + +## Failure patterns + +- Testing the whole product instead of specific tasks. Vague results. +- Tasks that reveal the path. ("Click the menu and find...") +- Friends and family as participants. Biased, not representative. +- Researcher leading the participant. Findings reflect the researcher. +- Defending the design when participants struggle. Misses real issues. +- Helping too quickly. Participant doesn't experience the friction. +- Treating participant suggestions as features. Users solve their problem; product team designs the solution. +- One participant = data point. A single strong opinion isn't a finding. +- Skipping severity scoring. All findings treated equally; team can't prioritize. +- Reports no one reads. Highlight clips and live walkthroughs work better than 80-page decks. +- Testing once, never re-testing. Fixes that introduce new problems go undetected. + +--- + +## Output format + +Default outputs: + +1. Test plan (before testing) - `usability-test-plan-[topic].md` +2. Task script (per session) - `usability-tasks-[topic].md` +3. Findings report (after synthesis) - `usability-findings-[topic].md` +4. Highlight clips (separately produced) + +--- + +## Reference files + +- [`references/task-script-patterns.md`](references/task-script-patterns.md) - Task framing patterns by common product type, with good and bad examples. diff --git a/skills/usability-testing/references/task-script-patterns.md b/skills/usability-testing/references/task-script-patterns.md new file mode 100644 index 0000000..bcc0cd7 --- /dev/null +++ b/skills/usability-testing/references/task-script-patterns.md @@ -0,0 +1,315 @@ +# Task Script Patterns + +Patterns for writing usability test tasks that produce real findings rather than scripted compliance. Includes good and bad examples by common product type. + +--- + +## Universal task framing rules + +### Rule 1: State the user goal, not the system action + +\| Bad (system action) \| Good (user goal) \| +\|---\|---\| +\| "Click the search button at the top." \| "Find a place to stay in Lisbon for a weekend." \| +\| "Open the settings menu and change your password." \| "You think someone else might know your password. Update it." \| +\| "Add this product to your cart." \| "You want to buy this jacket. Walk me through purchasing it." \| + +The system-action version reveals the path. Findings tell you whether the participant could follow instructions, not whether they could use the product. + +### Rule 2: Provide motivating context + +\| Bare task \| Better with context \| +\|---\|---\| +\| "Find a hotel in Paris." \| "You're planning a 3-day trip to Paris next month for your anniversary. Find a hotel that fits." \| +\| "Sign up for an account." \| "You decided this looks promising and want to try it. Get started." \| + +Context shapes how participants approach the task. Without it, they make their own assumptions, often differently from each other. + +### Rule 3: Avoid product terminology + +\| Bad (uses our terms) \| Good (uses user's terms) \| +\|---\|---\| +\| "Create a workspace." \| "Set this up so your team can collaborate." \| +\| "Find an experience." \| "Find an activity to do this Saturday." \| + +If the participant doesn't already know the product's terminology, using it in the task gives them the answer. + +### Rule 4: Don't reveal the path + +\| Bad (path revealed) \| Good (open) \| +\|---\|---\| +\| "Use the filters to narrow the results to under $100." \| "Find something within your budget of $100." \| +\| "Click on the FAQ section to find the return policy." \| "Find out if you can return this if it doesn't fit." \| + +If the path is in the task, you're not testing whether the participant can find the path. + +### Rule 5: Make it specific + +\| Bad (vague) \| Good (specific) \| +\|---\|---\| +\| "Try out the product." \| "Find out if this product would work for tracking your team's meetings." \| +\| "Look around." \| "Walk me through how you'd evaluate whether this is right for you." \| + +Vague tasks produce vague findings. Specific tasks produce actionable findings. + +--- + +## Common pre-test framing + +Use a script for the opening so it's consistent across sessions. + +### Standard opener + +> "Thanks again for joining. As I mentioned, we're testing a [website / app / prototype]. The point is to learn from your experience, not to test you. There are no right or wrong ways to do anything. If you get confused or stuck, that's information for us, not a problem with you. +> +> A few things to know: +> 1. I'll ask you to do some tasks. As you go, please think out loud. Tell me what you're looking at, what you're thinking, what you expect to happen, what's confusing. +> 2. I won't be able to help much during the tasks. The whole point is to see how you'd use this without help. After each task, we'll talk about what was easy and what wasn't. +> 3. We're recording this session for our own notes. The recording stays internal. Sound good? +> +> Any questions before we start?" + +### Pre-task framing + +> "OK, here's the first task. Take your time, think out loud, and there's no rush. +> +> [Read the task aloud, slowly. Send it in chat if remote so they can refer back.] +> +> Go ahead and start whenever you're ready." + +### Mid-task probes (use sparingly) + +When participant is silent for a while: +> "What are you thinking?" + +When participant pauses on something: +> "What's going through your mind right now?" + +When participant takes an unexpected action: +> "What did you expect to happen there?" + +### When participant gets truly stuck + +Wait at least 30 seconds before intervening. Real frustration is signal. + +> "Take a moment. What would you typically do at a point like this?" + +Or: + +> "Is there anything you'd want to do that you're not seeing a way to do?" + +If they're still stuck after another 30 seconds, you can offer a hint: "What might happen if you scrolled?" But this is a last resort. The struggle is the data. + +### Post-task probes + +> "On a scale of 1 to 5, how easy or hard was that?" + +> "What was hardest?" + +> "What was easiest?" + +> "If you could change one thing about how that worked, what would it be?" + +### Closing + +> "Thanks for working through these tasks. Two last questions: +> +> Overall, what's your impression? +> +> If you imagine using this regularly, what would make it work for you? What might keep you from using it? +> +> Anything else you want to mention before we wrap?" + +--- + +## Task patterns by product type + +### Ecommerce + +#### Browse and discovery + +> "You're looking for a gift for a friend who loves cooking. They've been getting into making bread. You have a budget of about $75. Find something that might work." + +[Tests: navigation, search, filtering, product browsing] + +#### Specific product purchase + +> "You've decided to buy [specific product]. Walk me through purchasing it. Stop just before you'd actually enter your payment info." + +[Tests: cart flow, checkout flow, friction points] + +#### Comparison + +> "You're trying to decide between two of these products. Use the site to figure out which one is better for your needs." + +[Tests: comparison features, product pages, decision support] + +#### Returns + +> "You bought something from this store last month. It doesn't fit. Find out how to return it." + +[Tests: help center, account flows, post-purchase support] + +--- + +### SaaS / B2B + +#### Self-service evaluation + +> "You're a [role] at a 30-person company. Your team needs better [tool category]. Use this site to figure out if this is the right fit, and if so, what plan to pick." + +[Tests: positioning, value prop, pricing, evaluation flow] + +#### Onboarding (post-signup) + +> "You just signed up for an account. Walk me through what you'd do next. Try to get to the point where the product would be useful for you." + +[Tests: onboarding, time-to-value, activation friction] + +#### First key task + +> "You're new to this product. Try to [specific key action: create your first project, set up an integration, invite a teammate]. Think out loud as you go." + +[Tests: feature discovery, task completion] + +#### Existing-user task + +> "You're an experienced user of this product. You need to [specific advanced task]. Show me how you'd do that." + +[Tests: depth of features, expert workflows] + +--- + +### Marketplaces + +#### Buyer side: discovery + +> "You need someone to [service]. Find a few options that look good to you." + +[Tests: search, filters, listing pages] + +#### Buyer side: deciding + +> "You've narrowed it down to a few options. Pick the one you'd actually book and walk me through what you'd do next." + +[Tests: details pages, social proof, booking flow] + +#### Seller side: setup + +> "You [run a business / offer a service]. You're considering listing it here. Use this site to figure out how to get started." + +[Tests: onboarding, value prop for the supply side] + +#### Seller side: ongoing + +> "You're an existing seller. You want to [check on inquiries / update your availability / respond to a review]. Show me how you'd do that." + +[Tests: account management, dashboard] + +--- + +### Content / publisher + +#### Reading flow + +> "Read [specific article / topic that interests you]. As you go, tell me what's working or not working about the experience." + +[Tests: readability, page experience, ads, related content] + +#### Discovery + +> "Spend a few minutes exploring this site. Find articles that interest you. Tell me how you decide what to click." + +[Tests: navigation, recommendations, browse paths] + +#### Subscribe + +> "You've decided you want to read more from this publication. Sign up for whatever you think makes sense." + +[Tests: paywall flow, subscription page, account setup] + +--- + +### Mobile app + +#### Initial impression + +> "You just downloaded this app. Open it and start using it. Tell me what you do, what you expect." + +[Tests: app onboarding, initial value] + +#### Specific feature + +> "You want to [specific feature use]. Show me how you'd do that." + +[Tests: feature discovery, mobile-specific patterns] + +#### Push / notification flow + +> "Your phone just buzzed with a notification from this app. Show me what you'd do." + +[Tests: notification design, deep links, post-notification flow] + +--- + +## Task script common pitfalls + +### Pitfall 1: Multiple tasks in one + +> "Sign up, create a project, and invite a teammate." + +This is three tasks. Run as three separate tasks so you can score and analyze each. + +### Pitfall 2: Tasks that aren't realistic + +> "Imagine you're an enterprise CFO evaluating procurement tools." + +If the participant is not a CFO, they're roleplaying. Findings tell you about roleplay, not real CFO behavior. Recruit real CFOs or pick a different task. + +### Pitfall 3: Tasks the participant has already done + +> "Sign up for an account." +> +> Participant: "I already have one." + +Either log them out for the test, or change the task to first-time-user-feeling tasks. + +### Pitfall 4: Tasks tied to specific data the participant doesn't have + +> "Update your billing address." +> +> Participant: "I don't have an account on this site." + +Provide a test account with realistic data, or pick tasks that work for first-time users. + +### Pitfall 5: Asking about future behavior as a task + +> "Tell me what you'd pay for this." + +Hypothetical questions are weak signal. Test actual behavior (do they get to the pricing page? where do they hesitate?) and ask post-task what they'd be willing to pay if useful. + +--- + +## Severity scoring rubric + +Use after testing to score each issue. + +\| Severity \| Definition \| Example \| +\|---\|---\|---\| +\| Critical \| Most users cannot complete the task. Hard blocker. \| "5 of 6 participants gave up trying to find pricing." \| +\| Major \| Most users complete the task, but with significant struggle. \| "4 of 6 participants needed multiple tries to find the search." \| +\| Minor \| Some users hit friction. Most complete the task fine. \| "2 of 6 participants paused on the form, but all completed." \| +\| Cosmetic \| Polish issue. No effect on task completion. \| "Multiple participants noted a typo." \| + +Critical and Major issues block ship. Minor issues prioritize on cost/benefit. Cosmetic gets fixed in normal iteration. + +--- + +## Reporting tips + +- Lead with the most surprising finding, not the easiest fix +- Include at least one quote per major finding (specifics persuade) +- Include video clips for critical findings (no document beats seeing it) +- For each finding, include both the issue and the recommended fix +- Sort by severity, not by section of the product +- Make it scannable. Stakeholders skim. diff --git a/skills/user-feedback-aggregation/SKILL.md b/skills/user-feedback-aggregation/SKILL.md new file mode 100644 index 0000000..0336049 --- /dev/null +++ b/skills/user-feedback-aggregation/SKILL.md @@ -0,0 +1,302 @@ +--- +name: user-feedback-aggregation +description: "Collecting and synthesizing user feedback across channels (support tickets, NPS, in-app feedback, sales calls, social mentions, customer councils) into a continuous signal that informs product decisions. The triage discipline that distinguishes loudest-voice (whoever complains most wins) from averaged-noise (every signal weighted equally) from triaged-synthesis (signal weighted by source quality, frequency, and decision relevance). Triggers on user feedback, customer feedback aggregation, NPS, support ticket analysis, customer councils, feedback synthesis, voice of customer, feedback triage, in-app feedback. Also triggers when feedback channels overflow with volume that does not produce decisions, when the loudest-voice problem is steering roadmap, or when continuous feedback streams need synthesis discipline." +category: research +catalog_summary: "Collecting and synthesizing user feedback across channels into continuous decision signal. Triage discipline that distinguishes loudest-voice (whoever complains most) from averaged-noise (every signal weighted equally) from triaged-synthesis (weighted by source quality and decision relevance)" +display_order: 5 +--- + +# User Feedback Aggregation + +A senior product leader's playbook for collecting and synthesizing user feedback across channels into continuous decision signal. Support tickets, NPS surveys, in-app feedback, sales calls, social mentions, customer councils, all aggregated into a triaged synthesis the team can actually act on. + +Most product programs accumulate feedback they do not use. Channels overflow with submissions; CSAT and NPS scores get reported in monthly updates; customer council meetings produce notes that nobody references. The loudest voices steer roadmap because they are easiest to hear; quieter signal that matters more goes unaddressed. + +This skill is the triage discipline that turns continuous feedback streams into continuous decision signal. Each channel surfaces different signal at different reliability. Each signal type warrants different weight in different decisions. The team that aggregates feedback well makes better decisions; the team that drowns in feedback makes the same decisions they would have made without the feedback. + +Different from `discovery-research-synthesis`, which covers one-off research projects (a defined batch of artifacts, a defined synthesis output). This skill covers the always-on streams: feedback that arrives every day, every week, every month, and that the team must continuously triage and synthesize. + +The voice is the senior product leader who has watched feedback aggregation work and watched it fail. Concrete, opinionated about which channels matter for which decisions, willing to call out where loudest-voice or averaged-noise patterns produce bad outcomes. + +When to use this skill: building a feedback aggregation system, auditing a feedback program that is producing volume without decisions, deciding which feedback channels matter for the program, or designing the synthesis cadence for ongoing feedback streams. + +--- + +## What this skill is for + +This skill spans continuous user-feedback aggregation. The PM-skill distinction: + +- `discovery-research-synthesis` is one-off discovery research. Defined batch, defined output. +- `user-feedback-aggregation` (this skill) is ongoing feedback streams. Always-on channels needing continuous synthesis. +- `beta-program-management` covers feedback specific to beta participants. This skill spans all users continuously. +- `ux-research` is structured research projects. This skill is unsolicited feedback. +- `pm-spec-writing` is downstream: specs use feedback aggregation as input. +- `roadmap-planning` is downstream: roadmap uses feedback patterns as input. + +The audience: senior PMs, product directors, customer success and support managers running feedback programs, in-house teams aggregating feedback across many channels. + +What is not in scope: structured discovery research (covered by `discovery-research-synthesis`); beta-specific feedback (covered by `beta-program-management`); commissioned research projects (covered by `ux-research`). + +--- + +## Loudest-voice vs averaged-noise vs triaged-synthesis + +The keystone framing. + +Loudest-voice. Whoever complains the most gets their feature. Vocal minorities steer roadmap. Silent majority's needs go unaddressed. The squeaky-wheel anti-pattern. Cost: the program optimizes for the loudest customer, not for the broader customer base; quieter customers leave for products that addressed their needs. + +Averaged-noise. Every signal weighted equally. 1 enterprise customer's feedback = 1 trial user's feedback = 1 angry social mention. Volume aggregates without weighting; noise drowns signal. Cost: the team cannot tell which feedback matters; decisions get made on aggregate sentiment that does not reflect the customers who matter most for the strategy. + +Triaged-synthesis. Signal weighted by source quality, frequency, and decision relevance. Different feedback types have different weights for different decisions. The team that does this well makes decisions grounded in the signal that matters; the team that does it badly defaults to loudest-voice or averaged-noise. + +The litmus test. Pick a recent product decision. Can the team explain why specific feedback signals weighted into the decision the way they did? If yes, the aggregation is triaged. If the answer is "we heard a lot about this from customers," without specificity about which customers in which contexts, the aggregation is loudest-voice or averaged-noise. + +--- + +## Feedback channels and what each surfaces + +Six common channels. Each surfaces different signal at different reliability. + +Support tickets. What users hit when things break or confuse them. High volume, high signal-on-friction, biased toward users willing to contact support. + +NPS surveys. Aggregate sentiment toward the product or specific features. Periodic, quantitative-with-comments, bias toward respondents who feel strongly (positive or negative). + +In-app feedback. Friction at the moment users encounter it. Contextualized to specific product moments; volume varies; quality varies. + +Sales calls. Pre-purchase prospect perspective. Objections, competitive mentions, gaps between marketing and what sales leads with. Bias toward prospects, not existing customers. + +Social mentions. Public commentary about the product. Real-time but biased toward customers willing to post publicly; often skews negative or hyper-positive. + +Customer councils. Curated panels of customers in structured forums. High-quality feedback from selected customers; bias depends on selection. + +Each channel has strengths and weaknesses. Strong feedback aggregation triangulates across channels rather than relying on one. + +Detail in [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md). + +--- + +## Channel-source weighting + +The discipline that distinguishes triaged-synthesis from averaged-noise. + +The principle. Different sources warrant different weights in different decisions. + +Worked example. A decision about whether to prioritize an enterprise admin feature. + +- Sales call data showing enterprise prospects asking for the feature: high weight (the decision is about enterprise; the source matches). +- Support ticket data from enterprise customers: high weight (existing enterprise customers' friction is directly relevant). +- NPS data from small-team customers: low weight (the feature is not for them; their satisfaction is not load-bearing for the decision). +- Social mentions: variable weight (signal depends on who is mentioning; enterprise practitioners on LinkedIn carry more weight than anonymous trial users on social). + +The discipline. For each decision, identify which sources matter most. Weight accordingly. Volume from low-weight sources should not override signal from high-weight sources. + +The averaged-noise failure. Decisions made on aggregate volume regardless of source. The enterprise admin feature gets deprioritized because more total feedback came from small-team customers who do not need it; enterprise customers churn because their needs went unaddressed. + +Detail in [`references/channel-source-weighting.md`](references/channel-source-weighting.md). + +--- + +## Categorization and tagging discipline at scale + +How feedback gets organized when it arrives at high volume. + +The taxonomy. + +- Feature area or product surface (where in the product the feedback applies). +- Issue type (bug, friction, feature request, positive signal, edge case). +- User segment (who is providing the feedback). +- Severity or urgency (how blocking is it for the user). +- Source channel (where the feedback came from). + +The discipline. + +- Tags emerge from feedback patterns, not from a pre-built taxonomy. +- Tags get refined over time as patterns clarify. +- Multiple tags per feedback item; do not force single-category. +- Periodic taxonomy review surfaces categories that need to merge or split. + +The volume challenge. A program receiving 500-2000 feedback items per week needs aggregation tooling that supports tagging at scale. Manual tagging at scale burns out the team; AI-assisted tagging with human review on patterns is often the practical middle path. + +Detail in [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md). + +--- + +## Frequency vs intensity + +Two dimensions of feedback signal. + +Frequency. How often the same feedback recurs. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +Intensity. How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive, or describe satisfaction as transformative. +- Low-intensity feedback: minor friction or mild satisfaction. + +The matrix. + +- High-frequency, high-intensity: top priority. Many users hit this; it matters to them. +- High-frequency, low-intensity: papercuts. Address in batches; individual items are minor but cumulatively erode experience. +- Low-frequency, high-intensity: the affected users are deeply impacted but few. Often segment-specific. +- Low-frequency, low-intensity: noise. Capture; do not action individually. + +The discipline. Triage assigns each piece of feedback a frequency-intensity assessment. The combination informs prioritization weight. + +Detail in [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md). + +--- + +## From feedback to product decision + +The synthesis loop that turns aggregated feedback into roadmap input. + +The loop. + +- Feedback arrives across channels. +- Triage categorizes and weights. +- Periodic synthesis (weekly, monthly, quarterly) surfaces patterns. +- Patterns inform roadmap discussions, spec drafts, prioritization debates. +- Decisions reference specific feedback patterns as input. + +The cadences. + +- Daily: critical feedback (security, data loss, broken core flows) handled immediately. +- Weekly: team review of recent patterns. Adjusts current-quarter execution. +- Monthly: synthesis review. Surfaces trending patterns; informs next-quarter roadmap. +- Quarterly: strategic synthesis. Patterns over the quarter inform strategic planning. + +The discipline. Feedback aggregation has cadence. Without cadence, feedback accumulates without producing decisions. + +Detail in [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md). + +--- + +## Closing the loop with users + +When feedback shapes product, telling users matters. + +The practice. + +- When feedback drives a change, communicate to the users who provided that feedback. +- "We heard from many of you that X was painful; we shipped Y this week to address it. Thanks for the feedback that informed this work." +- Communication can be public (release notes, blog posts) or targeted (email to users who opened tickets on the issue). + +Why it matters. + +- Users who see their feedback acted on engage more in the future. +- The closed loop signals that the team is listening, which strengthens the relationship. +- Users without feedback follow-through stop providing feedback over time. + +The risk of over-promising. Promising changes that do not ship erodes trust faster than not promising. Communicate what shipped, not what might ship. + +Detail in [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md). + +--- + +## Detecting drift in feedback patterns over time + +What changes in feedback signal over time can reveal. + +Drift patterns. + +- Increasing feedback volume in a category: either the issue is worsening, the user base is growing, or awareness of the channel is increasing. Investigate the cause. +- New patterns emerging: previously-rare feedback becomes more common. Often signals product or market change. +- Patterns disappearing: feedback that used to be common stops. The issue may be resolved, or users may have given up reporting it. +- Sentiment shifts: NPS or CSAT trending differently than before. Often signals broader experience changes. + +The investigation discipline. Drift signals warrant investigation. Why did the volume increase? Why did this pattern emerge? The root cause often informs product decisions more than the surface signal. + +Detail in [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md). + +--- + +## Feedback aggregation tooling considerations + +Tooling choices without endorsing specific products. + +Tooling categories. + +- Customer feedback platforms (aggregate across multiple sources, support tagging, surface patterns). +- Support ticket systems with analytics layers. +- NPS or survey platforms with response aggregation. +- Customer relationship management systems with feedback fields. +- Custom dashboards combining feedback signal with usage analytics. + +The criteria for tooling selection. + +- Does it support multi-channel aggregation, or is it single-channel? +- Does it support tagging at scale? +- Does it surface patterns, or is it just storage? +- Does it integrate with the team's other systems (roadmap, ticketing, communication)? +- Does it scale with program volume? + +The build-vs-buy tension. Many programs end up with a mix: dedicated tooling for some channels, custom dashboards for cross-channel synthesis. Pure single-tool solutions often miss the multi-channel pattern detection. + +Detail in [`references/tooling-considerations.md`](references/tooling-considerations.md). + +--- + +## Common failure modes + +Rapid-fire. Diagnoses in [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md). + +- "Loudest customers steer the roadmap." Loudest-voice pattern; vocal minorities dominate; silent majority underaddressed. +- "We have lots of feedback but no decisions." Aggregation without synthesis; no triage cadence. +- "Our channels overflow; we cannot keep up." Aggregation without weighting or tooling that scales. +- "Different teams cite different feedback for the same decision." Channel-source weighting absent; teams reach for whatever feedback supports their position. +- "Customer council meetings produce notes nobody references." Council without synthesis loop; the meeting is the deliverable. +- "NPS is reported monthly but does not inform decisions." NPS as compliance metric, not as decision input. +- "Feedback we shipped against did not move sentiment." Wrong feedback prioritized; the loud feedback was not the most consequential. +- "Users gave feedback once and never returned." Closed-loop missing; users feel ignored. +- "We tagged everything but cannot find patterns." Taxonomy too granular or too noisy; periodic taxonomy review missing. +- "Drift in feedback caught us by surprise." Drift detection missing; the team did not investigate trending patterns until they became problems. +- "Sales call data and support ticket data tell different stories." Cross-channel synthesis missing; each channel's signal stays in its own silo. + +--- + +## The framework: 12 considerations for feedback aggregation + +When designing or auditing a feedback aggregation system, walk these 12 considerations. + +1. Triaged-synthesis, not loudest-voice or averaged-noise. Signal weighted by source, frequency, decision relevance. +2. Channel taxonomy known. Support, NPS, in-app, sales, social, councils. What each surfaces. +3. Channel-source weighting per decision. Different decisions weight channels differently. +4. Categorization and tagging at scale. Taxonomy that emerges from data; tooling that supports volume. +5. Frequency-intensity matrix. Each feedback item assessed on both dimensions. +6. Synthesis cadence. Daily critical, weekly patterns, monthly review, quarterly strategic. +7. Cross-channel triangulation. Patterns that appear across channels are stronger. +8. Closing the loop with users. When feedback drives change, communicate. +9. Drift detection. Patterns over time reveal changes. +10. Tooling that scales. Multi-channel aggregation, pattern surfacing, integration. +11. Specific feedback informs specific decisions. Decisions traceable to specific signals. +12. Honest assessment of source bias. Each channel's bias acknowledged in synthesis. + +The output of the framework is feedback aggregation that produces decision-grade signal continuously, scales with program volume, and treats users well enough that they keep providing feedback over time. + +--- + +## Reference files + +- [`references/channel-types-and-what-each-surfaces.md`](references/channel-types-and-what-each-surfaces.md) - Six common channels with strengths, weaknesses, biases, and synthesis implications. +- [`references/channel-source-weighting.md`](references/channel-source-weighting.md) - Decision-relative weighting. Worked examples of how channels weight differently for different decisions. +- [`references/categorization-and-tagging-at-scale.md`](references/categorization-and-tagging-at-scale.md) - Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. +- [`references/frequency-vs-intensity.md`](references/frequency-vs-intensity.md) - The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. +- [`references/from-feedback-to-product-decision.md`](references/from-feedback-to-product-decision.md) - The synthesis loop. Cadences. The discipline of decisions traceable to feedback. +- [`references/closing-the-loop-with-users.md`](references/closing-the-loop-with-users.md) - When and how to communicate feedback-driven changes. The over-promising risk. +- [`references/detecting-drift-in-feedback.md`](references/detecting-drift-in-feedback.md) - Drift patterns. Investigation discipline. Drift as early signal of change. +- [`references/tooling-considerations.md`](references/tooling-considerations.md) - Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. +- [`references/common-feedback-aggregation-failures.md`](references/common-feedback-aggregation-failures.md) - 11+ failure patterns with diagnoses and cures. + +--- + +## Closing: feedback as continuous signal, not periodic survey + +The teams that make good product decisions over time are the ones that aggregate feedback continuously and synthesize it into decision input. Not as compliance with a feedback-collection mandate; not as monthly NPS reporting; not as ad-hoc reactions to whoever complains loudest. As a continuous discipline that surfaces what users are actually experiencing, weighted appropriately, synthesized for the decisions the team is actually making. + +Feedback aggregation done well is invisible: the team makes better decisions, but the feedback work itself does not feel heroic. Feedback aggregation done badly is loud: channels overflow, NPS gets reported, customer councils produce decks, and decisions still get made on gut feel because the feedback work did not produce decision input. + +The discipline is in the triage. Each channel weighted by what it reveals. Each piece of feedback assessed on frequency and intensity. Patterns surfaced through synthesis. Decisions traceable to specific feedback. The closed loop with users that keeps feedback flowing. + +When in doubt about whether a feedback program is working, ask: can the team trace recent decisions to specific feedback patterns, are channels weighted differently for different decisions, is the synthesis cadence producing input the team uses, are users seeing their feedback acted on? If yes to all of those, the program is real. If no to any, the gap is where the feedback work is failing to convert into decisions. diff --git a/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md b/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md new file mode 100644 index 0000000..5faac7a --- /dev/null +++ b/skills/user-feedback-aggregation/references/categorization-and-tagging-at-scale.md @@ -0,0 +1,213 @@ +# Categorization and tagging at scale + +Taxonomy that emerges from data. Tooling at volume. Periodic taxonomy review. + +How feedback gets organized when it arrives at high volume. The discipline that prevents the "we tagged everything but cannot find patterns" failure. + +--- + +## The taxonomy dimensions + +Each feedback item gets tagged across multiple dimensions. + +Feature area or product surface. Where in the product the feedback applies. Examples: onboarding, dashboard, billing, integrations, mobile app. + +Issue type. Bug, friction, feature request, positive signal, edge case. + +User segment. Who is providing the feedback. Examples: free tier, pro tier, enterprise, trial, churned. + +Severity or urgency. How blocking is the issue. Examples: critical (blocks core flow), high (significant friction), medium (workaround exists), low (minor). + +Source channel. Where the feedback came from. Examples: support ticket, NPS comment, in-app widget, sales call, social mention, customer council. + +Date or time period. When the feedback was submitted. Useful for drift detection. + +Most programs use 3-6 of these dimensions. More dimensions produce richer queries; more dimensions also increase tagging burden. + +--- + +## Tags emerge from data, not from a pre-built taxonomy + +The same principle as discovery research synthesis (see `discovery-research-synthesis`). + +The pattern. Tags emerge from feedback patterns. Initial tagging captures what users actually said; the taxonomy builds up from the data. + +The anti-pattern. Pre-built taxonomies that force feedback into categories. Patterns the taxonomy did not anticipate get missed; categories that do not match the data get used anyway. + +Why emergent tagging matters. + +- Users describe issues in their own language; pre-built categories often miss the actual issues. +- New product features generate new categories; emergent tagging adapts. +- Issues evolve over time; emergent tagging captures the evolution. + +The transition. Programs starting feedback aggregation often need a starting taxonomy to begin with. The starting taxonomy is provisional; it gets refined as feedback accumulates and patterns clarify. + +--- + +## Multiple tags per feedback item + +Most feedback items deserve multiple tags. + +The pattern. A single feedback item often touches multiple feature areas, issue types, or context dimensions. + +Worked example. Support ticket: "I'm an enterprise admin trying to set up SSO for the team and the configuration step keeps timing out." + +Tags: + +- Feature area: SSO configuration, admin settings. +- Issue type: bug (timeout) + friction (configuration is hard). +- User segment: enterprise. +- Severity: high (blocks core enterprise setup). +- Source channel: support ticket. + +Multiple tags capture the feedback's full context. Single-tag forcing loses information. + +--- + +## Tagging at volume + +Programs receiving 500-2000+ feedback items per week need tooling support. + +Tooling approaches. + +- Manual tagging. Each item tagged by a human. Highest quality; lowest scale. Works for low-volume programs (under 100 items per week). +- AI-assisted tagging. AI suggests tags; humans review and adjust. Scales better; quality depends on the AI's training and the team's review discipline. +- Automated tagging. AI tags without human review. Scales highest; quality is lowest because no one validates. +- Hybrid. Manual tagging for high-priority items (enterprise feedback, critical issues), AI-assisted for the bulk. + +The recommended pattern for most programs. AI-assisted tagging with human review on patterns. The AI handles bulk classification; humans review aggregate patterns and validate that the categorization is producing useful signal. + +The volume calibration. + +- Under 100 items/week: manual tagging is feasible and preferred. +- 100-500 items/week: AI-assisted with sample review. +- 500+ items/week: AI-assisted with pattern review; manual handling reserved for high-priority items. + +--- + +## Tag quality vs tag granularity + +Two competing pressures. + +Granularity helps. More specific tags surface more specific patterns. "Onboarding configuration step 3 friction" is more useful than "onboarding friction." + +Granularity also harms. More specific tags fragment data. If 10 different tags split what should be one pattern, the pattern is invisible. + +The middle path. + +- Start with moderate granularity. +- Refine over time. Tags that consistently co-occur may need to merge; tags that combine distinct patterns may need to split. +- Periodic taxonomy review (see below) catches granularity issues. + +--- + +## Periodic taxonomy review + +Quarterly or bi-annual review of the taxonomy. + +The questions. + +- Are there tags that consistently co-occur and could merge? +- Are there tags that contain multiple distinct patterns and should split? +- Are there new patterns that need new tags? +- Are there tags that no longer apply (deprecated features, resolved issues)? +- Is the taxonomy too granular (fragmenting patterns) or too coarse (hiding patterns)? + +The output. A revised taxonomy. Old tags may get retired; new tags may get added; some tags may get renamed. + +The discipline. Without periodic review, taxonomies decay. Old tags accumulate; new patterns get tagged into wrong categories; the taxonomy stops surfacing useful patterns. + +The frequency. Quarterly works for most programs. Annual works for stable programs with low product change rate. Bi-annual works as a middle path. + +--- + +## Tag conflicts and resolution + +Sometimes feedback could be tagged in multiple ways. + +Resolution approaches. + +- Multi-tagging. When in doubt, apply multiple tags. Captures the ambiguity rather than forcing a choice. +- Convention. Document conventions for ambiguous cases. "Friction with the dashboard's filter functionality" gets tagged "dashboard" + "filtering" + "friction" rather than choosing. +- Reviewer judgment. Train reviewers (human or AI) on conventions. Ambiguous cases get reviewed for consistency. + +The cost of inconsistent tagging. Patterns become invisible because the same kind of feedback gets tagged differently. The "we tagged everything but cannot find patterns" failure often traces to inconsistent tagging. + +--- + +## Tag distribution as signal + +The distribution of tags across feedback can be informative beyond individual tags. + +Examples. + +- Spike in volume on a specific tag: trending issue or feature area in flux. +- Decline in volume on a tag: issue resolved or users gave up reporting. +- Co-occurrence patterns: tags that consistently appear together suggest related issues. +- Segment-specific tag distributions: enterprise vs free-tier feedback patterns differ. + +The dashboard view. Most feedback aggregation tooling supports tag-distribution dashboards. The dashboards surface patterns the team would not see in individual feedback items. + +--- + +## Tagging discipline at the channel level + +Different channels need different tagging conventions. + +Support tickets. Often pre-tagged by the support system (issue type, product area). Augment with feedback-specific tags. + +NPS comments. Lighter tagging. Often just sentiment + topic area. Open-ended comments are mined for patterns; not every comment needs comprehensive tagging. + +In-app feedback. Auto-tagged by context (which page, which feature). Augment with issue-type and severity. + +Sales calls. Often summarized rather than tagged at the moment level. Summaries get tagged. + +Social mentions. Auto-classified by sentiment and topic; manual review for high-impact mentions. + +Customer council notes. Manually tagged after each council session. Higher tagging investment because volume is low and signal is high. + +--- + +## Cross-channel tag consistency + +Tags should mean the same thing across channels. + +The risk. "Onboarding friction" in support tickets means something slightly different than "onboarding friction" in NPS comments because the channels surface different aspects. + +The mitigation. + +- Document tag definitions explicitly. "Onboarding friction" includes X, Y, Z signals. +- Periodic cross-channel calibration. Review tagged samples from each channel to ensure consistency. +- Channel-specific sub-tags where appropriate. "Onboarding-friction-support" vs "Onboarding-friction-nps" if the distinction matters. + +The honest framing. Cross-channel tag consistency is hard. Strong programs work toward it; perfect consistency is rare. + +--- + +## Common tagging failures + +Pre-built taxonomy forced. Patterns the taxonomy did not anticipate get missed. + +Single-tag forcing. Multi-dimensional feedback gets reduced to one tag; information lost. + +Inconsistent tagging. The same kind of feedback gets tagged differently across reviewers or time periods. + +Tag bloat. Too granular; patterns fragment across many tags. + +Tag coarseness. Too broad; distinct patterns hide within the same tag. + +No taxonomy review. Tags decay over time without periodic review. + +Volume overwhelms tagging. High-volume programs without tooling support; tagging falls behind; old feedback never gets tagged. + +Tag-without-purpose. Tagging happens because it is supposed to; nobody uses the tags for synthesis. + +--- + +## Methodology-level choices that stay in the public skill + +The taxonomy dimensions. Emergent tagging. Multi-tag discipline. Tagging at volume (manual, AI-assisted, automated, hybrid). Tag quality vs granularity tradeoffs. Periodic taxonomy review. Tag conflict resolution. Tag distribution as signal. Channel-specific tagging. Cross-channel consistency. Common failures. + +## Implementation choices that stay internal + +Specific tagging tools and AI models. Specific tag definition documents. Specific reviewer training. Specific dashboard configurations. The team's own conventions for tagging within the principles. These vary by team. diff --git a/skills/user-feedback-aggregation/references/channel-source-weighting.md b/skills/user-feedback-aggregation/references/channel-source-weighting.md new file mode 100644 index 0000000..aac3763 --- /dev/null +++ b/skills/user-feedback-aggregation/references/channel-source-weighting.md @@ -0,0 +1,216 @@ +# Channel-source weighting + +Decision-relative weighting. Worked examples of how channels weight differently for different decisions. + +The discipline that distinguishes triaged-synthesis from averaged-noise. Different sources warrant different weights for different decisions; treating all sources as equal produces decisions made on aggregate volume rather than on signal that matters. + +--- + +## The weighting principle + +Each piece of feedback has a source. The source's weight in a decision depends on how relevant the source is to that decision. + +Worked principle. A piece of feedback from an enterprise customer has different weight than a piece of feedback from a trial user when the decision is about enterprise pricing. The enterprise customer's feedback is high-weight; the trial user's feedback is low-weight (they are not the audience for the decision). + +The same piece of feedback from a trial user has different weight when the decision is about trial conversion. Now the trial user is the audience; their feedback is high-weight. + +The weighting is decision-relative, not source-absolute. + +--- + +## Worked examples of channel weighting + +### Decision: Should we prioritize the enterprise admin role overhaul this quarter? + +Audience for the decision. Existing enterprise customers and enterprise prospects. + +Channel weights for this decision. + +- Sales call data with enterprise prospects: high weight. They directly inform the decision. +- Support ticket data from enterprise customers: high weight. Existing enterprise friction is directly relevant. +- Customer council data from enterprise members: high weight. Curated enterprise perspective. +- NPS data from enterprise customers: moderate weight. Aggregate signal but not specific to admin features. +- NPS data from small-team customers: low weight. Different segment; admin features not relevant. +- Social mentions: variable weight. Enterprise practitioners' posts higher than anonymous trial accounts. +- In-app feedback from small-team users: low weight. Different segment. + +The decision weighs enterprise sources heavily. Volume from non-enterprise sources should not displace enterprise signal. + +### Decision: Should we redesign the onboarding flow for new free-tier signups? + +Audience for the decision. Free-tier new signups. + +Channel weights for this decision. + +- Support tickets from free-tier users in their first week: high weight. Direct friction signal. +- In-app feedback from free-tier users during onboarding: high weight. Moment-of friction. +- NPS data from free-tier users: moderate weight. Aggregate sentiment. +- Sales call data: low weight. Sales calls are usually with prospects, not free signups; pre-decision conversation differs from post-signup experience. +- Customer council data: low weight. Councils usually have established customers, not new signups. +- Support tickets from long-tenured customers: low weight. Their onboarding friction was a year ago; current onboarding may differ. + +The decision weighs new-signup sources heavily. Long-tenured customer feedback is informative for other decisions but not this one. + +### Decision: Should we launch a new pricing tier? + +Audience for the decision. Both prospects and existing customers (existing customers may move tiers; prospects' tier choice affects acquisition). + +Channel weights for this decision. + +- Sales call data on pricing conversations: high weight. Prospects' pricing perception is critical. +- Support tickets about pricing or upgrade requests: high weight. Existing customer pricing pain points. +- Customer council discussion on pricing: high weight. Strategic discussion with curated customers. +- NPS data with pricing comments: moderate weight. Some signal but not decision-specific. +- Social mentions about pricing: moderate weight. Public perception affects acquisition. +- In-app feedback unrelated to pricing: low weight. Off-topic for this decision. + +Multiple high-weight channels because the decision spans audiences. + +### Decision: Should we invest in social mention monitoring as a primary channel? + +Audience for the decision. Strategic question about feedback aggregation infrastructure. + +Channel weights for this decision. + +- Past examples of social signal driving decisions: high weight. Direct evidence. +- Past examples where social signal misled (vocal minority, anonymous accounts): high weight as counter-evidence. +- Other companies' published patterns on social signal: moderate weight. Indicative but not specific. +- Internal team intuition about social signal: low weight unless backed by data. + +The decision weighs evidence of past signal-driven decisions heavily. + +--- + +## The averaged-noise failure + +When sources are weighted equally regardless of decision relevance. + +The pattern. + +- The team aggregates all feedback equally. +- Volume from any source counts the same. +- The most-feedback issue gets prioritized regardless of source. + +Why it fails. + +- Decisions get made on aggregate volume rather than on signal that matters for that decision. +- Decisions that should be enterprise-driven get displaced by volume from segments that do not matter for that decision. +- The team optimizes for the squeaky-wheel signal because it is loudest in the aggregate. + +Worked failure. The team is deciding whether to prioritize enterprise admin features. NPS and in-app feedback show low priority for this area (because most respondents are small-team users who do not need enterprise admin). Sales calls and enterprise support tickets clearly indicate the priority. The team aggregates volume, sees more total feedback against enterprise admin priority, and deprioritizes. Enterprise customers churn. + +The cure. Weight by decision relevance. Enterprise channels weight high for enterprise decisions; small-team feedback should not displace enterprise signal on enterprise decisions. + +--- + +## The loudest-voice failure + +When the most vocal source dominates regardless of representativeness. + +The pattern. + +- A small number of customers complain frequently and loudly. +- Their feedback dominates synthesis because they generate the most volume. +- Their preferences shape the roadmap. + +Why it fails. + +- Vocal minorities do not represent the broader user base. +- Silent majority's needs go unaddressed. +- The roadmap optimizes for the customers most likely to complain rather than the customers most strategic for the business. + +The cure. Weight by source quality and representativeness, not by volume. A complaint repeated 50 times by one user is not 50x the signal of one complaint by 50 distinct users. + +--- + +## How to set weights + +In practice, weighting is qualitative. Quantitative scoring schemes often produce false precision. + +The discipline. + +- For each decision, identify the audience (who the decision serves). +- Identify which channels surface signal from that audience. +- Identify which channels do not (and why their feedback is less relevant for this decision). +- In synthesis, give high-weight channel signal more attention than low-weight channel signal. + +Quantitative weighting risks. + +- Scoring systems (this channel = 3x weight; that channel = 1x) often produce false precision. +- Decisions made on weighted scores rather than on judgment can miss qualitative nuances. +- The discipline is qualitative judgment informed by source-relevance, not arithmetic. + +The honest framing. Weighting is a judgment call. The synthesis names the weighting choices explicitly: "We weighted enterprise channel signal heavily here because the decision is about enterprise priorities." Readers can disagree with the weighting; disagreement is productive. + +--- + +## Source bias acknowledgment + +Each source has biases that affect its signal. + +Sources skew toward. + +- Support: users willing to contact support; tend toward problem-reporting. +- NPS: users with strong opinions; middle-ground underrepresented. +- In-app feedback: users who interact with widgets; specific segments may dominate. +- Sales calls: prospects, not existing customers; pre-purchase context. +- Social: users who post publicly; enthusiasts and angry voices. +- Councils: curated members; specific selection criteria. + +The synthesis discipline. When weighting, acknowledge the bias. "Support tickets show high friction in this area" should be paired with "noting the support-channel bias toward users who contact support." The acknowledgment makes synthesis more honest and readers more informed. + +--- + +## Multi-channel triangulation as weighting + +When patterns appear across multiple channels, weighting becomes easier. + +Strong cross-channel signal. Same pattern in support, NPS, in-app, and sales. The cross-channel pattern survives any single channel's bias. + +Single-channel signal. Pattern in only one channel. Weighting depends on channel reliability for the decision; treat with more caution. + +Conflicting cross-channel signal. Different channels disagree. Investigate the source of the conflict; the disagreement often reveals segment differences or context-specific patterns. + +The discipline. Cross-channel triangulation is a form of weighting: patterns that survive multiple channels' biases are more reliable signal. + +--- + +## Weighting in tooling + +Some feedback aggregation tools support explicit weighting (priority scores, segment-specific dashboards). + +Tooling support. + +- Tagging by source channel and segment. +- Filtering and grouping by tag combinations. +- Dashboards that show signal per segment or channel. + +The tooling principle. Tooling supports weighting; the weighting judgment still belongs to humans. Tools that automate weighting away from human judgment risk false precision. + +The build-vs-buy tension. Many programs end up with custom dashboards or filtering that supports their specific weighting. Generic tooling rarely supports the program's specific decision-relative weighting needs out of the box. + +--- + +## Common weighting failures + +No weighting. All sources treated equally. Averaged-noise pattern. + +Static weighting. Same weights regardless of decision. Misses that different decisions need different weights. + +Quantitative false precision. Scoring systems that produce decisions without judgment. + +Volume as proxy for weight. Loudest-voice pattern; whoever generates most feedback wins. + +Bias acknowledgment skipped. Synthesis claims stronger signal than the channel's bias warrants. + +Single-channel reliance. Decisions made on one channel's signal without triangulation. + +--- + +## Methodology-level choices that stay in the public skill + +The decision-relative weighting principle. Worked weighting examples for different decisions. The averaged-noise and loudest-voice failures. How to set weights. Source bias acknowledgment. Multi-channel triangulation. Weighting in tooling. Common failures. + +## Implementation choices that stay internal + +Specific weighting conventions for specific decision types. Specific tooling that supports weighting. Specific dashboard configurations. The team's own conventions for naming weighting choices in synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md b/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md new file mode 100644 index 0000000..c2c0ec3 --- /dev/null +++ b/skills/user-feedback-aggregation/references/channel-types-and-what-each-surfaces.md @@ -0,0 +1,263 @@ +# Channel types and what each surfaces + +Six common feedback channels with strengths, weaknesses, biases, and synthesis implications. Each channel surfaces different signal at different reliability; strong aggregation triangulates across channels. + +--- + +## Channel 1: Support tickets + +What users hit when things break or confuse them. + +What support surfaces. + +- Functional friction (where the product breaks down for users). +- Documentation gaps (questions users ask repeatedly). +- Feature requests that arrive in the form of complaints. +- Edge case failures. +- Confusion about intended behavior vs actual behavior. + +Strengths. + +- High volume; signal accumulates from many users. +- Grounded in specific user contexts (the user was trying to do something specific). +- Captures friction users actually encountered, not friction they speculated about. + +Weaknesses. + +- Bias toward users willing to contact support. Users who silently leave the product do not appear here. +- Bias toward fixable issues. Users who struggle but figure it out (or give up) without contacting support are invisible. +- Sentiment skew: users contact support when frustrated; positive experience is underrepresented. + +Synthesis implications. + +- Support volume on a feature area is a strong signal of friction; absence of volume is weak signal of satisfaction. +- Pattern-detection across tickets reveals systemic issues better than individual tickets. +- Combine with usage analytics: a feature with high support volume and low usage suggests broken value; high support volume and high usage suggests meaningful friction in something users still want. + +--- + +## Channel 2: NPS surveys + +Aggregate sentiment toward the product or specific features. + +What NPS surfaces. + +- Aggregate sentiment trend lines. +- Distribution between promoters, passives, and detractors. +- Open-ended comments (often the most useful part). +- Sentiment differences across segments. + +Strengths. + +- Quantitative signal that aggregates across many users. +- Trends over time reveal whether sentiment is improving or degrading. +- Open-ended comments provide qualitative depth. +- Industry-standard metric makes benchmarking possible. + +Weaknesses. + +- Response bias. Users with strong opinions (positive or negative) respond at higher rates than users in the middle. +- Cultural and segment biases in scoring (some segments score lower on average than others for cultural reasons). +- The 0-10 scale loses granularity; many decisions need more than promoter/passive/detractor categorization. +- Surveys on specific features can have small sample sizes that produce noisy signal. + +Synthesis implications. + +- NPS as a single number is less useful than NPS distribution and trend. +- Open-ended comments are often the highest-value section; mine them for patterns. +- Segment-specific NPS is more actionable than aggregate NPS. +- Single-quarter NPS shifts can be noise; multi-quarter trends are more reliable signal. + +--- + +## Channel 3: In-app feedback + +Friction at the moment users encounter it. + +What in-app feedback surfaces. + +- Contextual friction (the user was at a specific moment in the product when they submitted). +- Ratings or sentiment scoped to specific features or flows. +- Quick observations users would not bother to file as a ticket. + +Strengths. + +- Captures the moment. Friction is fresh; context is automatic (the system knows where the user was). +- Lower friction submission than support tickets; surfaces issues users would not formally report. +- Volume varies; some products see high in-app feedback, others minimal. + +Weaknesses. + +- Bias toward users who interact with the feedback widget. Some segments use it heavily; others rarely. +- Quality varies. Quick submissions are often shallow. +- Volume can overwhelm if the widget triggers too aggressively. + +Synthesis implications. + +- In-app feedback is best for detecting moment-specific friction. +- Pair with usage analytics: where users submit feedback in the product is informative. +- Filter by submission length and pattern; one-word submissions ("frustrating!") are weak signal compared to specific submissions ("I expected the export to include the filters I had applied; it did not"). + +--- + +## Channel 4: Sales calls + +Pre-purchase prospect perspective. + +What sales calls surface. + +- Objections prospects raise (what makes the sale hard). +- Pricing-conversation patterns and price sensitivity by segment. +- Competitive mentions (which competitors are top-of-mind, what differentiation prospects ask about). +- The gap between marketing positioning and what sales actually leads with. +- Prospect vocabulary for describing their situation (often different from internal product language). + +Strengths. + +- Prospect view of the product before they have invested in it. Reveals what attracts and what blocks adoption. +- Competitive intelligence in the form of comparisons prospects make. +- Hire criteria signal (why prospects would choose the product). + +Weaknesses. + +- Bias toward prospects, not existing customers. Existing-customer experience differs. +- Sales-team interpretation can color how calls are tagged. +- Stage selection matters: early-stage discovery calls reveal different things than late-stage closing calls. + +Synthesis implications. + +- Sales call data informs positioning, pricing, and adoption-hire-criteria decisions. +- Combine with existing-customer feedback to understand the full lifecycle. +- Lost-deal analysis (specifically, calls with prospects who did not buy) is a separate research mode that surfaces what the product would need to win. + +--- + +## Channel 5: Social mentions + +Public commentary about the product. + +What social mentions surface. + +- Public sentiment in real time. +- Comparison to competitors (often more honest than survey responses). +- Use cases and use contexts the team did not anticipate. +- Reputation signals (how the product is perceived in the broader market). + +Strengths. + +- Real-time signal. +- Public visibility means the team can respond to issues that affect brand reputation. +- Captures users who post publicly but would not file feedback through formal channels. + +Weaknesses. + +- Bias toward users willing to post publicly. Often skews toward enthusiasts (positive) or angry (negative); middle-ground users are quiet. +- Volume can overwhelm; signal-to-noise ratio is low. +- Anonymous accounts complicate weighting (who is this person? are they a real customer?). +- Platform algorithms shape what is visible; the visible signal is not the full signal. + +Synthesis implications. + +- Social signal is one input, rarely a primary driver. Triangulate with other channels. +- Track reputational themes (what the product is known for in the broader market). +- Respond to specific issues that affect brand reputation; do not use social as the primary feedback prioritization channel. + +--- + +## Channel 6: Customer councils + +Curated panels of customers in structured forums. + +What customer councils surface. + +- Curated customer perspective on strategic questions. +- Deep discussion that reveals motivations and priorities. +- Cross-customer patterns (council members compare notes; the team sees what they share). +- Long-term relationship signal (council members commit time and engagement). + +Strengths. + +- High-quality feedback from selected customers. +- Structured forum makes discussion deeper than ad-hoc feedback. +- Council members often become advocates and references. + +Weaknesses. + +- Bias depends on selection. A council selected for size, role, or vocal customers will skew accordingly. +- Council members are often outliers (engaged, willing to commit time); their perspective may not represent broader users. +- Small sample size (usually 5-30 members); patterns from one council are weak signal. +- Cost: councils require curation, scheduling, and ongoing relationship management. + +Synthesis implications. + +- Council feedback is valuable but limited; do not treat as representative of the full user base. +- Use councils for strategic discussions, not for tactical prioritization. +- Council patterns can be a leading indicator of broader user patterns; validate with other channels. + +--- + +## Channels not covered here + +Some feedback channels are out of scope for this skill but worth naming. + +Beta participants. Covered by `beta-program-management`. Beta feedback is bounded to the beta period; this skill covers ongoing streams. + +Discovery research interviews. Covered by `discovery-research-synthesis`. One-off research projects, not always-on streams. + +App store reviews. A specific channel for consumer products. Similar dynamics to social mentions: public, biased toward strong opinions, real-time but volume-heavy. + +Customer success quarterly business reviews. Often produce structured customer feedback; can be treated as a council-like channel for top customers. + +Internal employee feedback. Sometimes valuable (employees are users of internal tools, or use the product alongside customers); always biased toward internal context. + +--- + +## Cross-channel triangulation + +Patterns that appear across channels are stronger than patterns from a single channel. + +Worked example. A feature area showing: + +- Support tickets: increasing volume in this area. +- NPS comments: this area mentioned negatively in detractor comments. +- In-app feedback: friction submissions in this area. +- Sales calls: prospects asking about this area as a comparison point against competitors. + +The cross-channel pattern is stronger than any single-channel signal. The feature area is a load-bearing issue across multiple lenses. + +Worked counter-example. A loud single-channel signal: + +- Social mentions: vocal complaints about a feature. +- Support tickets: minimal volume on the same feature. +- NPS: feature not flagged in detractor comments. +- Sales calls: feature not raised by prospects. + +The cross-channel pattern shows the social signal is loud but not load-bearing. Loud-on-one-channel-only is often vocal-minority signal. + +--- + +## Channel reliability calibration + +Different channels have different reliability for different kinds of decisions. + +Functional friction decisions. Support tickets and in-app feedback are most reliable. NPS is moderate. Social and sales are less reliable. + +Adoption hire-criteria decisions. Sales calls are most reliable. Support tickets and in-app feedback are less reliable (existing-customer bias). + +Positioning decisions. Sales calls and social mentions are most reliable (prospect/public perception). NPS and councils are moderate. + +Strategic prioritization. Customer councils and NPS trends are useful inputs. Support tickets indicate friction but not strategic priority. + +Reputation decisions. Social mentions are direct signal. Support and NPS are indirect. + +The discipline. For each decision, identify which channels are most reliable. Weight accordingly. + +--- + +## Methodology-level choices that stay in the public skill + +The six channel types with strengths, weaknesses, biases, and synthesis implications. Channels not covered. Cross-channel triangulation. Channel reliability calibration for different decision types. + +## Implementation choices that stay internal + +Specific tooling per channel. Specific tagging schemas. Specific integration patterns across channels. The team's own conventions for channel coverage. These vary by team and tooling. diff --git a/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md b/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md new file mode 100644 index 0000000..5c70fb4 --- /dev/null +++ b/skills/user-feedback-aggregation/references/closing-the-loop-with-users.md @@ -0,0 +1,246 @@ +# Closing the loop with users + +When and how to communicate feedback-driven changes. The over-promising risk. + +Closing the loop is the practice of telling users when their feedback drove a product change. Done well, it strengthens the feedback relationship; users see their input matter. Done badly, it over-promises or appears performative; trust erodes. + +--- + +## Why closing the loop matters + +Users who provide feedback are doing the team a favor. The cost is their time and attention. The return on their investment is, in part, seeing their input acted on. + +What happens when the loop is open. + +- Users provide feedback. +- The team uses it (or does not). +- Users do not know what happened. +- Engagement decays. Why provide feedback if it does not seem to matter? + +What happens when the loop is closed. + +- Users provide feedback. +- The team uses it (or explains why not). +- Users see their input matter. +- Engagement strengthens. Future feedback flows. + +--- + +## What gets communicated + +Three categories of communication. + +Changes shipped. "We shipped X this week. Many of you reported Y was painful; X addresses that." + +- Specific, actionable, ties to specific feedback. +- Best when the team can quantify the change ("Step 3 deferral; activation rate increased from 32% to 41% in the first month"). + +Changes coming. "We are working on X for Q3. Several of you have asked about this; here is the timeline." + +- Specific timeline. +- Honest about uncertainty if applicable. +- Risk: over-promising. Communicating coming changes that do not ship erodes trust. + +Decisions to defer or decline. "We have heard feedback about X; we are choosing not to prioritize it because Y. Here is the reasoning." + +- Honest about the deferral. +- Explains the reasoning. +- Treats users as capable of understanding tradeoffs. + +The third category is rarely done; it is the most credibility-building. Teams that explain why something was not prioritized earn more trust than teams that promise everything. + +--- + +## Communication channels + +How to close the loop. + +Public channels. + +- Release notes. Standard post-launch communication. Includes feedback context where relevant. +- Blog posts or changelog. Longer-form for major changes. Names the feedback patterns that drove the work. +- Public roadmap. Shows what is coming; signals that user feedback informs prioritization. + +Targeted channels. + +- Email to users who reported the issue. "You reported X; we shipped Y to address it." Personalized; high impact for specific users. +- In-app notification at the moment of relevance. When the user encounters the changed flow, an in-product banner: "We changed this based on feedback like yours; here is what is different." +- Customer success outreach. For high-value or high-engagement users, direct outreach is appropriate. + +Community channels. + +- Beta or community forums. Where applicable, communicate to the engaged community. +- Social media. For high-visibility changes; risk of public attention if poorly communicated. + +The channel should match the audience and the change. High-impact public changes warrant public communication; targeted changes warrant targeted communication. + +--- + +## Frequency and timing + +When to close the loop. + +Immediately after shipping. Most effective. The change is fresh; users remember providing feedback. + +Periodic recap (monthly or quarterly). "Here are the changes we shipped this quarter, and the feedback patterns that motivated them." + +- Useful for changes that did not warrant individual announcement. +- Builds an aggregate sense that feedback is shaping the product. + +Before shipping (preview). "We are about to ship X; here is what to expect." + +- Heads-up for users who will encounter the change. +- Risk: pre-launch announcements that get delayed; users wonder when the change is coming. + +The frequency calibration. Avoid silence (users feel ignored). Avoid over-communication (users tune out). Calibrate to the change cadence and audience attention. + +--- + +## The over-promising risk + +Communicating future changes that do not ship erodes trust. + +The pattern. + +- The team announces "we are working on X" with a timeline. +- The work gets deprioritized, delayed, or canceled. +- Users who counted on the change feel deceived or ignored. + +Why it happens. + +- Marketing or stakeholder pressure to share roadmap information. +- The team's own optimism about timelines. +- Failure to communicate when plans change. + +The cure. + +- Communicate shipped changes with confidence. +- Communicate coming changes with appropriate hedging ("we are exploring this," "we are planning this for next quarter"). +- Communicate plan changes when they happen, not silently. + +The honest framing. Promising "X will ship in Q3" is high-risk; promising "X is on our radar; we are evaluating priority" is honest. The first looks more confident; the second is more credible over time. + +--- + +## Communication for declined or deferred feedback + +When the team decides not to prioritize requested changes. + +The pattern. + +- User provides feedback requesting a change. +- The team evaluates and decides not to prioritize. +- The team communicates the decision. + +Strong communication. + +- "Several of you have asked about [feature]. We have evaluated and are choosing not to prioritize it this year because [reason]. Here are alternatives or workarounds that may help in the meantime." +- "We hear the feedback about [issue]. We are choosing not to address this for now because [tradeoff]. We are open to reconsidering if the pattern strengthens." + +Why it builds trust. + +- Acknowledges the feedback was heard. +- Explains the reasoning. +- Treats the user as capable of understanding tradeoffs. + +The risk of avoiding. + +- Silence. The user wonders if the feedback was heard. +- "Maybe in the future." Vague commitments that do not commit. +- "We will consider it." Performative. + +The decline communication is rare in practice but disproportionately valuable. + +--- + +## Communication for high-volume feedback + +When many users have provided similar feedback. + +The pattern. + +- A specific change addresses widely-reported feedback. +- The team has many users to potentially notify. + +Approaches. + +- Public announcement referencing the feedback pattern. "Many of you reported X; we shipped Y." +- Targeted email to users who reported the issue (using support ticket history, NPS comments, etc.). +- In-product notification at the moment of relevance. + +The capacity calibration. Targeted communication is high-effort; public communication scales. Most programs combine: public announcement for visibility, targeted communication for highest-impact users. + +--- + +## Personal vs aggregate + +Sometimes the closing-the-loop communication is to a specific user; sometimes it is aggregate. + +Personal. + +- "John, you reported X two months ago. We shipped Y this week to address it. Thanks for the feedback that informed this work." +- Direct email or in-app message. +- High impact for the specific user; low cost; very high relationship value. + +Aggregate. + +- "Many of you have asked about X; we shipped Y this week." +- Public announcement; reaches many users. +- Lower per-user impact but scales. + +The discipline. Personal communication for high-impact users (long-tenured customers, design partners, council members). Aggregate for broader changes. + +--- + +## When closing the loop fails + +Common failures. + +Silence. The most common failure. Users provide feedback; the team uses it (or does not); users never know what happened. Engagement decays. + +Generic acknowledgment. "Thanks for the feedback! We will look into it." Standard auto-reply that everyone gets. Feels performative; closes the loop technically but not meaningfully. + +Over-promising. "We will ship this in Q3." The team misses the date or cancels; users feel deceived. + +Late communication. Changes shipped months ago; communication never happens; users stopped using the product. + +Vague communication. "We have heard your feedback and are working on improvements." No specifics; users cannot tell what was actually changed. + +No deferral communication. Changes the team decided not to prioritize go uncommunicated. Users keep wondering or assume the feedback was ignored. + +Communication only on shipping. Successes communicated; failures and deferrals never. Trust erodes when users notice the asymmetry. + +--- + +## Closing the loop and feedback volume + +Programs that close the loop well often see feedback volume increase over time. Users who saw their input matter contribute more. + +The virtuous cycle. + +- Feedback closes the loop. +- Users see their input matter. +- Engagement strengthens. +- Feedback volume and quality increase. +- The team has more signal to act on. + +The vicious cycle. + +- Feedback aggregation happens in silos. +- Closing the loop does not happen. +- Users feel ignored. +- Engagement decays. +- Feedback volume and quality decrease. +- The team has less signal. + +The discipline. Closing the loop is an investment in the future of the feedback program. + +--- + +## Methodology-level choices that stay in the public skill + +Why closing the loop matters. What gets communicated. Communication channels. Frequency and timing. The over-promising risk. Communication for declined or deferred feedback. Communication for high-volume feedback. Personal vs aggregate. Common failures. The virtuous and vicious cycle. + +## Implementation choices that stay internal + +Specific email templates for closing-the-loop communication. Specific automation that triggers communication. Specific in-product notification systems. The team's own conventions for personal vs aggregate. These vary by team. diff --git a/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md b/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md new file mode 100644 index 0000000..c16ce67 --- /dev/null +++ b/skills/user-feedback-aggregation/references/common-feedback-aggregation-failures.md @@ -0,0 +1,193 @@ +# Common feedback aggregation failures + +Eleven-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most feedback aggregation failures share a single root, which is treating feedback aggregation as collection rather than as decision input. + +--- + +## Failure 1: Loudest customers steer the roadmap + +Symptom. A small number of vocal customers dominate roadmap discussions. Quieter customers' needs go unaddressed. The product evolves to serve the loudest, not the broadest. + +Diagnosis. Loudest-voice pattern. Volume from vocal users mistaken for broad signal. + +Cure. Apply channel-source weighting. Distinguish between distinct-user signal and per-user volume. Triangulate across channels to validate that loud signal represents broad pattern. + +Prevention. Synthesis names the source distribution explicitly. "This pattern came from 50 distinct users across 3 channels" is different from "this pattern came from 5 users with 200 tickets." + +--- + +## Failure 2: We have lots of feedback but no decisions + +Symptom. Feedback channels overflow. Tagging happens. Dashboards exist. Decisions get made on intuition rather than on the feedback signal. + +Diagnosis. Aggregation without synthesis. The triage cadence is missing or broken; feedback is collected without being turned into decision input. + +Cure. Establish the synthesis cadence (weekly, monthly, quarterly). Each cadence produces output the team uses for decisions. + +Prevention. Synthesis ownership explicit. Whoever owns synthesis is accountable for the loop's continuity. + +--- + +## Failure 3: Our channels overflow; we cannot keep up + +Symptom. Feedback volume exceeds the team's capacity to triage, tag, and synthesize. Old feedback never gets reviewed; new feedback piles up. + +Diagnosis. Capacity mismatch. Either tooling does not scale, or the team is under-staffed for the volume, or both. + +Cure. Scale tooling: AI-assisted tagging, aggregated channels, automated pattern surfacing. Or reduce capture: not every channel needs to be aggregated. + +Prevention. Match tooling and capacity to expected volume. Plan for growth; the volume that is comfortable today often is not in 6 months. + +--- + +## Failure 4: Different teams cite different feedback for the same decision + +Symptom. Engineering team cites one feedback pattern; product team cites another; sales team cites a third. The teams reach for whatever feedback supports their position. + +Diagnosis. Channel-source weighting absent. Each team uses the channel that is most accessible to them, regardless of decision relevance. + +Cure. Establish weighting per decision. The synthesis surfaces what the relevant channels say, weighted appropriately. Teams use the synthesis rather than going to channels independently. + +Prevention. Centralize synthesis ownership. The synthesis owner produces the canonical view; teams reference it rather than producing parallel interpretations. + +--- + +## Failure 5: Customer council meetings produce notes nobody references + +Symptom. Customer council convenes regularly. Notes are taken. Decks summarize. The notes get filed; no roadmap discussions reference them. + +Diagnosis. Council without synthesis loop. The meeting is the deliverable; the analytical follow-through is missing. + +Cure. Apply the synthesis loop to council inputs. Each council meeting produces specific actionable input that feeds product decisions. + +Prevention. Treat council inputs as part of the broader feedback aggregation, not as a separate stream that produces ceremonial outputs. + +--- + +## Failure 6: NPS is reported monthly but does not inform decisions + +Symptom. NPS scores get reported in monthly business reviews. The number is part of compliance reporting. It does not inform product decisions. + +Diagnosis. NPS as compliance metric. The number gets tracked; the underlying signal does not. + +Cure. Mine NPS comments for patterns. Segment NPS by user segment. Use NPS trends as drift signal. The number itself is less informative than the underlying signal. + +Prevention. NPS reporting includes the qualitative signal alongside the quantitative score. Decisions reference what NPS comments revealed, not just the score. + +--- + +## Failure 7: Feedback we shipped against did not move sentiment + +Symptom. Major feature shipped to address feedback. Post-launch sentiment did not improve. The team is confused. + +Diagnosis. Wrong feedback prioritized. The loud feedback was not the most consequential; the patterns the team addressed were not the patterns that drove sentiment. + +Cure. Re-examine the synthesis that motivated the work. Was the pattern strong across channels, or was it loud in one channel? Was the segment broad or narrow? Was the change the right response to the pattern? + +Prevention. Strong synthesis grounds prioritization in cross-channel patterns and frequency-intensity assessment. Single-channel signals get treated cautiously. + +--- + +## Failure 8: Users gave feedback once and never returned + +Symptom. Users submit feedback through channels. They never engage again. Repeat feedback rates are low. + +Diagnosis. Closed-loop missing. Users feel ignored after providing feedback. + +Cure. Establish closing-the-loop communication. Tell users when their feedback drove change. Personal communication for high-impact users; aggregate for broader changes. + +Prevention. Closing the loop is part of the feedback workflow, not an afterthought. Decisions to ship include closing-the-loop communication as a step. + +--- + +## Failure 9: We tagged everything but cannot find patterns + +Symptom. Tagging happens systematically. The team applies tags to most feedback items. But synthesis cannot identify clear patterns. + +Diagnosis. Taxonomy too granular, too coarse, or noisy. Periodic taxonomy review missing. + +Cure. Run a taxonomy review. Merge tags that fragment patterns; split tags that hide distinct issues; deprecate tags that no longer apply. + +Prevention. Quarterly or bi-annual taxonomy review. The taxonomy evolves with the program. + +--- + +## Failure 10: Drift in feedback caught us by surprise + +Symptom. A feedback category grew significantly over weeks or months. The team discovered the change only when it became a problem. + +Diagnosis. Drift detection missing. The team did not investigate trending patterns until they became urgent. + +Cure. Establish drift detection: trend dashboards, threshold alerts, periodic trend review. + +Prevention. Weekly quick scans for sharp drift. Monthly systematic review of category trends. Tooling that surfaces changes automatically. + +--- + +## Failure 11: Sales call data and support ticket data tell different stories + +Symptom. Sales suggests one priority; support suggests another. Both teams have data; the data conflicts. + +Diagnosis. Cross-channel synthesis missing. Each channel's signal stays in its own silo. + +Cure. Run cross-channel synthesis. Compare what sales calls reveal (prospect view) to what support tickets reveal (existing customer view). Often the conflict surfaces meaningful differences (different segments, different lifecycle stages); sometimes it surfaces inconsistency that warrants investigation. + +Prevention. Synthesis includes cross-channel triangulation. Conflicts get surfaced and resolved or acknowledged. + +--- + +## Failure 12: Feedback aggregation as compliance + +Symptom. Feedback collection happens because customers expect it or because leadership mandates it. The collection is performative; the synthesis is minimal. + +Diagnosis. Feedback aggregation treated as ceremony rather than as decision input. + +Cure. Tie feedback aggregation to specific decisions. The synthesis informs roadmap; decisions reference patterns. If the team cannot trace decisions to feedback, the program is compliance, not aggregation. + +Prevention. Feedback program goals are explicit and tied to decisions. The program's success is measured by whether decisions reference its synthesis, not by whether feedback was collected. + +--- + +## Failure 13: Synthesis that does not surface patterns + +Symptom. Monthly or quarterly synthesis happens. The output is descriptive but does not surface patterns or inform decisions. + +Diagnosis. Synthesis writing is documentation rather than analytical work. The patterns are not extracted; the implications are not drawn. + +Cure. Apply discovery-research-synthesis discipline to feedback synthesis. Patterns named with conviction; implications drawn; decisions informed. + +Prevention. Synthesis ownership includes analytical responsibility, not just documentation responsibility. + +--- + +## Failure 14: Tooling-led process + +Symptom. The team's process follows what the tooling supports. Capabilities the tooling does not support do not happen. + +Diagnosis. Tooling drives the process rather than the process driving tooling selection. + +Cure. Step back. Define what the team needs the feedback aggregation to produce. Evaluate tooling against those needs. + +Prevention. Tooling decisions are downstream of process design. The team designs the process, then selects or builds tooling that supports it. + +--- + +## The cross-cutting pattern + +Most feedback aggregation failures share a single root: treating feedback aggregation as collection rather than as decision input. + +Collection focuses on capturing feedback: channels integrated, items tagged, dashboards built, scores reported. Output: a record that feedback was collected. + +Decision input focuses on what the feedback informs: which decisions, what signal will inform them, what synthesis surfaces patterns the team needs. Output: decisions traceable to feedback patterns. + +The fix for almost any feedback aggregation failure starts with the same question: what specifically is this feedback program supposed to inform, and is the synthesis loop producing that input? When the answer is clear, the program becomes load-bearing. When the answer is "we should be aggregating feedback," the program becomes ceremony. + +--- + +## Methodology-level choices that stay in the public skill + +The fourteen failure patterns with diagnoses and cures. The cross-cutting collection-vs-decision-input pattern. + +## Implementation choices that stay internal + +Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team. diff --git a/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md b/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md new file mode 100644 index 0000000..cff4b6c --- /dev/null +++ b/skills/user-feedback-aggregation/references/detecting-drift-in-feedback.md @@ -0,0 +1,236 @@ +# Detecting drift in feedback + +Drift patterns. Investigation discipline. Drift as early signal of change. + +Feedback signal changes over time. Volume in a category increases or decreases; new patterns emerge; old patterns disappear; sentiment shifts. The team that detects drift early often catches issues before they compound; the team that does not detect drift often discovers problems after they are large. + +--- + +## The drift patterns + +Common ways feedback signal changes over time. + +### Increasing volume in a category + +Signal. Feedback volume in a specific area is rising over weeks or months. + +Possible causes. + +- The issue is worsening. +- The user base is growing (more total volume across all categories). +- Awareness of the channel is increasing (more users finding the feedback channel). +- Recent product changes introduced or amplified an issue. + +The investigation. Look at the cause: + +- Is the percentage of total feedback in this category increasing? (If yes, this category is growing relative to others; the issue is real, not just user-base growth.) +- Did recent product changes affect this area? (Often the cause when volume increases sharply.) +- Are users describing similar issues in different ways? (Could be one underlying issue surfacing through multiple feedback styles.) + +### Decreasing volume in a category + +Signal. Feedback volume in a specific area is declining over weeks or months. + +Possible causes. + +- The issue was resolved. +- Users gave up reporting (resignation rather than satisfaction). +- The user base shifted (fewer users in the affected segment). +- Channel access changed (users stopped using the feedback channel for this category). + +The investigation. Decreasing volume can be good or bad: + +- If a fix shipped and volume dropped: fix worked. +- If no fix shipped but volume dropped: investigate. Are users churning? Are they working around the issue silently? + +### New patterns emerging + +Signal. Feedback that was rare or non-existent starts appearing more frequently. + +Possible causes. + +- Recent product changes introduced new patterns. +- Market conditions changed (new competitors, new user expectations). +- User base expansion brought new use cases. +- Existing users developed new workflows. + +The investigation. Investigate the cause; new patterns often inform roadmap decisions. + +### Patterns disappearing + +Signal. Feedback patterns that used to be common stop appearing. + +Possible causes. + +- Product changes addressed the issue. +- Users migrated away from the affected workflows. +- The user base shifted. + +The investigation. Validate that the disappearance reflects resolution, not silent abandonment. + +### Sentiment shifts + +Signal. Aggregate sentiment (NPS, CSAT, in-app rating) trends differently than before. + +Possible causes. + +- Specific changes affected sentiment. +- External factors (market conditions, competitor actions, news cycles). +- User base composition changed. +- Cumulative experience changes that the team did not flag individually. + +The investigation. Sentiment shifts warrant root-cause analysis; both improvements and degradations are informative. + +--- + +## The drift detection cadence + +When the team checks for drift. + +Weekly: quick scans for sharp drift in critical categories. Sharp increases in support volume on specific issues, sudden NPS drops, viral social mentions. + +Monthly: systematic review of category-level trends. Compare the past month to prior months. Identify categories with significant increases or decreases. + +Quarterly: strategic drift review. Long-term trends, sentiment shifts, emerging patterns. Pairs with quarterly strategic synthesis. + +Annually: taxonomy and aggregate drift. Are tag categories still appropriate? Has the user base composition changed? Long-term sentiment trends. + +--- + +## Tooling for drift detection + +What infrastructure helps catch drift. + +Trend dashboards. Time-series views of feedback volume per category. Visual surfacing of changes. + +Threshold alerts. Automated alerts when a category's volume changes significantly (e.g., 50%+ increase week-over-week). + +Sentiment tracking. NPS or CSAT trends over time, segmented by user segment and product area. + +Cross-channel views. Aggregate trends across channels surface patterns that single-channel views miss. + +Period comparisons. Compare current period to prior periods (this month vs last month, this quarter vs same quarter last year). + +The tooling supports detection; humans interpret. + +--- + +## Investigation discipline + +When drift is detected, what to investigate. + +The questions. + +- What changed in the product or in the user base that could explain the drift? +- Is the drift persistent or a temporary spike? +- Is the drift segment-specific or universal? +- Is the drift correlated with other signals (churn, engagement, support volume)? +- What is the underlying cause vs the surface signal? + +The investigation methodology. + +- Pull a sample of feedback from the drifting category. +- Compare it to feedback in the same category from before the drift started. +- Identify what changed: language, contexts, severity, user segments. +- Map to product changes or external events that could explain. +- Form a hypothesis; test it through additional investigation. + +--- + +## Drift as early signal + +Drift often signals issues before they become large. + +The leading-indicator pattern. + +- A category's volume starts increasing. +- The team investigates and identifies the cause. +- The cause is addressed before it affects more users. + +Without drift detection, the same issue might compound for months before the team notices. + +Worked example. + +- Support tickets in the "configuration step 3" category increase 30% in two weeks. +- Investigation reveals: a recent change to the configuration form introduced a confusing default. +- The change is reverted or fixed within a week. +- Without drift detection, the issue might have continued for months, affecting many more users. + +--- + +## Drift in segments + +Drift can be segment-specific. + +The pattern. Aggregate metrics look stable; segment-specific metrics show drift. + +Worked example. Aggregate NPS is stable. Enterprise NPS is dropping; small-team NPS is improving. The aggregate hides the segment-specific drift. + +The investigation. Segment-level views surface patterns the aggregate hides. Enterprise drift may indicate a specific issue with enterprise features or experience that aggregate metrics miss. + +The discipline. Drift detection should include segment views, not just aggregate views. + +--- + +## Drift in cross-channel patterns + +Sometimes drift appears across channels even when individual channels look stable. + +The pattern. Each channel shows mild changes; the cross-channel aggregate shows a stronger pattern. + +Worked example. Support tickets in onboarding category up 15%. NPS comments mentioning onboarding up 10%. In-app feedback in onboarding up 20%. No single channel signals an emergency; the cross-channel aggregate suggests a real issue. + +The investigation. Cross-channel drift detection requires unified views or manual cross-channel review. + +--- + +## False-positive drift + +Not every change is real drift. + +Common false positives. + +- Seasonal patterns: support volume drops over holidays; NPS dips during certain campaigns. +- One-off events: a viral social mention spikes social signal but does not represent persistent change. +- Product launches: short-term volume spikes around new features, then normalize. +- Channel changes: a new feedback channel launches; volume in that channel grows from zero, not because the underlying issue grew. + +The investigation discipline. Before declaring drift, validate that the change is persistent and not explained by known factors. + +--- + +## Drift acknowledgment in synthesis + +Drift signals get surfaced in monthly and quarterly synthesis. + +The pattern. Synthesis documents include a drift section: what is changing, what may explain it, what action (if any) is recommended. + +The honest framing. Some drift gets acknowledged but not actioned (low-priority categories, edge cases). Some drift drives investigation. Some drift drives roadmap decisions. The synthesis names the disposition for each drift signal. + +--- + +## Common drift detection failures + +No detection. Aggregate volume is the only metric tracked; trends invisible. + +Aggregate only. Segment-specific drift hidden by aggregate stability. + +Single-channel only. Cross-channel patterns missed. + +Late detection. Drift caught after it has compounded for months. + +False positives treated as real drift. Seasonal patterns or one-off events trigger investigation that wastes time. + +Real drift treated as false positive. The team dismisses signals as noise; underlying issues compound. + +Investigation without follow-through. Drift detected; team investigates; finds cause; does not act. The detection was performative. + +--- + +## Methodology-level choices that stay in the public skill + +The drift patterns (increasing/decreasing volume, new/disappearing patterns, sentiment shifts). The drift detection cadence. Tooling for drift detection. Investigation discipline. Drift as early signal. Drift in segments. Drift in cross-channel patterns. False-positive drift. Drift acknowledgment in synthesis. Common failures. + +## Implementation choices that stay internal + +Specific dashboards for drift detection. Specific threshold settings for alerts. Specific seasonality models. Specific segment-view configurations. The team's own conventions for drift acknowledgment in synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/frequency-vs-intensity.md b/skills/user-feedback-aggregation/references/frequency-vs-intensity.md new file mode 100644 index 0000000..3f96062 --- /dev/null +++ b/skills/user-feedback-aggregation/references/frequency-vs-intensity.md @@ -0,0 +1,231 @@ +# Frequency vs intensity + +The two dimensions of feedback signal. The four-quadrant matrix and prioritization implications. + +Feedback signal varies along two dimensions: how often the same feedback recurs (frequency) and how strongly users feel about it (intensity). The combination produces a matrix that informs prioritization. + +--- + +## The two dimensions + +Frequency. How often the same feedback recurs across users. + +- High-frequency feedback: many users describe the same issue. Suggests broad applicability. +- Low-frequency feedback: rare or unique observations. Suggests narrow applicability or edge cases. + +Intensity. How strongly the user feels. + +- High-intensity feedback: users describe the issue as severely disruptive ("I cannot use the product because of this"), or describe satisfaction as transformative ("This feature changed how my team works"). +- Low-intensity feedback: minor friction ("Slightly annoying") or mild satisfaction ("It's fine"). + +The two dimensions are independent. High frequency does not imply high intensity; high intensity does not imply high frequency. + +--- + +## The four-quadrant matrix + +### Quadrant 1: High frequency, high intensity + +Top priority. Many users hit this; it matters to them. + +Examples. + +- A bug that affects core flow for many users. +- A friction point users describe as "I almost canceled because of this." +- A feature gap that users repeatedly cite as a competitive disadvantage. + +The disposition. Address quickly. The combination of broad impact and high stakes warrants priority investment. + +### Quadrant 2: High frequency, low intensity + +Papercuts. Many users hit this but it is minor. + +Examples. + +- A confusing button label that users figure out within seconds. +- A slight delay in a flow that users tolerate. +- A small visual inconsistency. + +The disposition. Address in batches. Individual papercuts are minor; cumulatively they erode experience. Periodic "papercut sprints" address many at once. + +The risk of ignoring papercuts. Papercuts compound. Users who tolerate one papercut leave when they accumulate. The cumulative experience is worse than the sum of individual papercuts. + +### Quadrant 3: Low frequency, high intensity + +Affected users deeply impacted but few. Often segment-specific. + +Examples. + +- A bug that affects users in a specific configuration that 5% of customers use, but for those users it is blocking. +- A feature gap that prevents enterprise customers from passing compliance review. +- An accessibility issue that excludes a specific user group entirely. + +The disposition. Depends on segment importance and reversibility. + +- If the affected segment is strategically important: high priority. +- If the affected segment is marginal: lower priority but documented. +- If the issue is a complete blocker for the affected users (cannot use the product at all): often warrants urgency regardless of segment size. + +### Quadrant 4: Low frequency, low intensity + +Noise. Capture; do not action individually. + +Examples. + +- One-off observations from users with unusual contexts. +- Minor preferences that one user mentions. +- Edge cases nobody else encounters. + +The disposition. Note in the system. Do not invest action on individual items. Aggregate sometimes reveals patterns; the noise can become signal if patterns emerge. + +--- + +## Frequency assessment + +How to assess frequency. + +Quantitative signals. + +- Number of distinct users reporting the same issue across channels. +- Volume of feedback items in the relevant tag or category. +- Trend over time: is the frequency increasing or stable? + +Cautions. + +- Volume can reflect channel bias rather than actual frequency. A loud single user generating 50 tickets is not high-frequency feedback (50x). +- Channel coverage matters. If a feedback channel only reaches a subset of users, frequency in that channel does not reflect frequency across all users. + +The cross-channel triangulation. Issues that show up across multiple channels are higher-frequency than issues that appear in one channel only. + +--- + +## Intensity assessment + +How to assess intensity. + +Verbal signals. + +- Strong language: "I cannot use this," "This is unacceptable," "I love this," "This changed my workflow." +- Specific impact descriptions: "I lost 3 hours," "This made my quarterly review possible," "I missed a deadline." +- Workaround intensity: heavy workarounds suggest high-intensity friction; light workarounds suggest low-intensity. + +Behavioral signals. + +- Churn correlation: users with feedback in a category churn at higher rates. +- Engagement correlation: users with positive feedback in a category engage more. +- Escalation patterns: users escalating to higher support tiers or to executive contacts signal high intensity. + +Cautions. + +- Some users naturally use stronger language than others. +- Cultural differences affect verbal intensity. +- Triangulate verbal and behavioral signals. + +--- + +## The matrix in practice + +Worked example: a feedback aggregation review for a product team's quarterly planning. + +Top-of-list items (high frequency, high intensity). + +- Onboarding configuration step 3 abandonment (broad signal across support, NPS comments, in-app feedback; users describe it as "I almost gave up"). +- Mobile app stability issues (frequent mobile crashes; users describe them as blocking). +- Enterprise admin role limitations (consistent across enterprise sales calls and support tickets; described as compliance blockers). + +Papercut batch (high frequency, low intensity). + +- Inconsistent button labeling across the product. +- Slow page transitions in the dashboard. +- Filter resets when navigating between views. +- Date format inconsistencies. + +Strategic-decision items (low frequency, high intensity). + +- Specific accessibility issues affecting screen reader users. +- Compliance gaps for healthcare-segment customers (small segment but blocking for them). +- Bug affecting users in specific timezone configurations (5% of users, but blocking). + +Noise-watch (low frequency, low intensity). + +- Various individual feature requests with no aggregate pattern. +- Cosmetic preferences mentioned by single users. + +The team's quarterly planning weights the four quadrants differently: + +- Top-of-list: included in the next quarter's roadmap. +- Papercut batch: scheduled for a dedicated sprint. +- Strategic decisions: discussed at strategy review for prioritization. +- Noise-watch: captured but not actioned. + +--- + +## When the matrix is misapplied + +Common matrix misuses. + +Volume as proxy for frequency. Loudest-voice users generate volume that does not reflect distinct-user frequency. + +Intensity assessed only verbally. Some users complain loudly about minor issues; some users underreport severe ones. Triangulate verbal and behavioral signals. + +Quadrant 4 dismissed too quickly. Some apparent noise is early-signal of patterns that will grow. Periodic review of low-frequency items catches emerging patterns. + +Quadrant 3 generalized to quadrant 1. Strategic-segment issues weighted as if they affected all users. Or marginal-segment issues weighted as if they were strategic. + +Frequency-only or intensity-only prioritization. Looking at one dimension misses the matrix. + +--- + +## Frequency over time + +Frequency dimensions can shift over time. + +Increasing frequency. Issue is worsening, user base is growing, or reporting awareness is increasing. Investigate the cause. + +Decreasing frequency. Issue is resolving, users are giving up reporting, or the user base shifted. The decreasing frequency may not mean problem solved. + +Stable frequency. Issue is recurring at consistent rate. May indicate steady-state or chronic issue. + +The drift detection (see `detecting-drift-in-feedback.md`) covers temporal changes in feedback signal. + +--- + +## Intensity at scale + +Intensity assessments at high feedback volume. + +The challenge. Reading every piece of feedback to assess intensity is impractical at high volume. + +The approach. + +- Sample-based intensity assessment. Read a sample; characterize the intensity distribution. +- Behavioral signal as proxy. Churn rates, escalation patterns, support-tier escalations. +- AI-assisted intensity classification. AI flags high-intensity feedback for human review. + +The discipline. Even at high volume, the team should be able to identify high-intensity feedback and weight it appropriately. + +--- + +## Common frequency-intensity failures + +Loudest-voice as high-frequency. A few loud users generate volume; the team mistakes volume for frequency. + +Intensity ignored. Volume drives prioritization; intensity is not assessed; quadrant 1 and quadrant 2 get treated similarly. + +Frequency ignored. A single emotional submission gets prioritized as if it were broad-pattern signal. + +Papercuts ignored as "low priority." Cumulative papercut impact erodes experience; treating each papercut as too minor to address misses the cumulative effect. + +Strategic-segment issues underweighted. Quadrant 3 treated as quadrant 4 because the affected segment is small. + +Noise treated as signal. Quadrant 4 items that are genuinely one-off get actioned as if they were broad patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The two dimensions (frequency and intensity). The four-quadrant matrix with worked dispositions. Frequency assessment. Intensity assessment. The matrix in practice. When the matrix is misapplied. Frequency over time. Intensity at scale. Common failures. + +## Implementation choices that stay internal + +Specific tooling for frequency tracking. Specific intensity classification (manual or AI-assisted). Specific dashboard views by quadrant. The team's own conventions for matrix application in prioritization. These vary by team. diff --git a/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md b/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md new file mode 100644 index 0000000..3f911df --- /dev/null +++ b/skills/user-feedback-aggregation/references/from-feedback-to-product-decision.md @@ -0,0 +1,225 @@ +# From feedback to product decision + +The synthesis loop. Cadences. The discipline of decisions traceable to feedback. + +Feedback aggregation produces value when it informs decisions. Without the synthesis loop that turns aggregated feedback into decision input, the program produces volume without action. + +--- + +## The synthesis loop + +The cycle that turns continuous feedback into continuous decisions. + +The stages. + +1. Feedback arrives across channels. +2. Triage categorizes and weights. +3. Periodic synthesis surfaces patterns. +4. Patterns inform roadmap discussions, spec drafts, prioritization debates. +5. Decisions reference specific feedback patterns as input. +6. Decisions ship; the loop continues with new feedback informed by the changes. + +The discipline. The loop is continuous. Feedback aggregation is not a one-time research project; it is a steady-state discipline. + +--- + +## The cadences + +Feedback synthesis benefits from multiple cadences operating in parallel. + +Daily: critical issues. + +- Critical feedback (security incidents, data loss, broken core flows) handled immediately. +- The triage system surfaces critical items for immediate attention. +- Response within hours to a day. + +Weekly: pattern review. + +- Team review of recent feedback patterns. +- Categorization, tagging, and pattern identification. +- Adjusts current-quarter execution where patterns suggest changes. +- 1-2 hours per week typical. + +Monthly: synthesis review. + +- Surfaces trending patterns over the past month. +- Identifies what to escalate to roadmap discussions. +- Compares current month patterns to prior months (drift detection). +- 2-4 hours per month. + +Quarterly: strategic synthesis. + +- Patterns over the quarter inform strategic planning and next-quarter roadmap. +- Customer council inputs and other longer-cadence channels integrated. +- Pairs with the team's broader strategic planning. +- A multi-day effort within the quarter's planning cycle. + +The cadences compose. Critical issues do not wait for weekly review; weekly review captures patterns that monthly review aggregates; monthly synthesis informs quarterly strategic decisions. + +--- + +## The synthesis output + +What each cadence produces. + +Daily/critical: specific incidents handled, no formal output beyond the response. + +Weekly: internal team notes on emerging patterns. May include a short summary email or dashboard update. + +Monthly: a synthesis document covering the month's patterns. Surfaces what is emerging, what is stable, what has resolved. Roadmap discussions reference this document. + +Quarterly: a strategic synthesis document. Trends over the quarter, recommendations for next quarter, strategic implications. Senior product leadership reviews this. + +The output gets richer at longer cadences. Daily and weekly are tactical; monthly and quarterly are strategic. + +--- + +## Decisions traceable to feedback + +The discipline that distinguishes triaged-synthesis from feedback ceremony. + +The pattern. Each major product decision can be traced to specific feedback patterns. The team can articulate: "We decided to prioritize X because feedback showed Y pattern across Z channels." + +The anti-pattern. Decisions get made on intuition or politics. Feedback aggregation happens in parallel but does not inform the decisions. The team uses general impressions ("we hear a lot about this from customers") rather than specific patterns. + +The discipline. + +- Roadmap items reference the feedback patterns that motivated them. +- Prioritization debates reference specific signal weight. +- Spec drafts include feedback context for the design decisions. +- Stakeholder communication explains decisions in terms of feedback patterns. + +The audit. For recent decisions, can the team trace each to specific feedback signals? If yes, the program is informing decisions. If the answer is "we generally know what customers want," the program is feedback theater. + +--- + +## Roadmap input from feedback + +How feedback aggregation informs roadmap planning. + +The roadmap inputs. + +- High-frequency-high-intensity patterns (quadrant 1 from the frequency-intensity matrix). +- Strategic-segment patterns (quadrant 3 from segments that matter for strategy). +- Cross-channel patterns that have validated across multiple sources. +- Drift signals that suggest emerging issues. + +The roadmap-output mapping. Roadmap candidates get characterized by which feedback patterns they address. + +- Candidate: "Onboarding redesign." Feedback motivation: configuration step 3 abandonment pattern across support, NPS, in-app feedback. +- Candidate: "Enterprise admin overhaul." Feedback motivation: enterprise sales-call objections + enterprise customer support patterns. + +The mapping makes the roadmap defensible: each item has a feedback-grounded reason. + +The "no feedback signal, no priority" discipline. Candidates that lack feedback grounding may still be valuable but should be defensible on other grounds (technical foundation, strategic bet). Candidates without any defensible grounding should be deprioritized. + +Pair with `roadmap-planning` for the broader prioritization discipline. + +--- + +## Spec input from feedback + +How feedback aggregation informs spec writing. + +The pattern. Specs reference feedback context for design decisions. + +Worked example. A spec for an onboarding redesign: + +- Background: feedback shows 40% of new signups abandon at configuration step 3. Cross-channel pattern (support tickets, in-app feedback, NPS comments). +- User stories: grounded in the specific feedback patterns. "As a new signup, I want to defer credit-card configuration until after I have seen the value, so I do not need my card on hand at signup." +- Design decisions: tied to the feedback. "Step 3 deferral chosen because feedback specifically cites credit-card-not-on-hand as the abandonment cause; alternative approaches that do not address this would not move the metric." + +The spec is grounded in feedback rather than in intuition. + +Pair with `pm-spec-writing` for the broader spec discipline. + +--- + +## Stakeholder communication from feedback + +How feedback aggregation informs stakeholder discussions. + +The pattern. Decisions presented to stakeholders are explained in terms of feedback patterns. + +Strong stakeholder communication. + +- "We are prioritizing the onboarding redesign because feedback across support, NPS, and in-app surveys consistently shows 40%+ abandonment at configuration step 3, with users citing credit-card friction as the cause." +- "We are deferring the dashboard expansion because feedback signal is mixed: enterprise customers want it; small-team customers do not need it; the strategic priority for this quarter is small-team activation." + +Weak stakeholder communication. + +- "We have heard a lot of feedback about onboarding." +- "Customers want this feature." + +The strong version is defensible; readers can engage substantively. The weak version is hand-waving. + +--- + +## Closing the synthesis loop + +After decisions ship, feedback responds. + +The post-decision feedback. + +- Did the change reduce the feedback patterns that motivated it? +- Did new patterns emerge as a result? +- Did the change introduce new friction in adjacent areas? + +The discipline. Track post-decision feedback to validate that the decision worked. Decisions that ship without post-decision feedback tracking lose the loop's learning value. + +--- + +## Cadence drift + +When the synthesis cadence breaks down. + +Common drift patterns. + +- Critical issues handled but no weekly pattern review. Tactical signal lost. +- Weekly review happens but does not aggregate to monthly synthesis. Patterns over time invisible. +- Monthly synthesis happens but does not inform quarterly planning. Strategic input missing. +- Quarterly strategic synthesis happens but the team does not act on it. Synthesis ceremony. + +The signal. When decisions stop being traceable to feedback, the cadence has drifted. The fix is restoring the cadence rather than blaming the team. + +--- + +## Synthesis ownership + +Who owns the synthesis loop. + +Common ownership patterns. + +- A dedicated feedback program owner (often a senior PM, product ops, or customer-success-product liaison). +- The product team's PM rotates through synthesis duties. +- A customer feedback team that synthesizes and feeds product teams. + +The discipline. Whoever owns synthesis is accountable for the loop's continuity. Without explicit ownership, synthesis falls to whoever has time, which often means it does not happen. + +--- + +## Common decision-loop failures + +Synthesis without decisions. Patterns surfaced; team does not use them. Documentation theater. + +Decisions without synthesis grounding. Team makes decisions on intuition; feedback aggregation happens in parallel but does not inform. + +Cadence breakdown. Daily critical handled; weekly and monthly synthesis fall behind. Loop loses continuity. + +No post-decision tracking. Decisions ship; feedback response not tracked; learning lost. + +Synthesis ownership missing. No clear owner; synthesis falls between roles. + +Synthesis output not actionable. Documents produced but framed in ways that do not inform decisions. Dense, generic, or unfocused. + +Stakeholder communication still hand-waving. Synthesis happens internally but stakeholder communication does not reference the patterns. + +--- + +## Methodology-level choices that stay in the public skill + +The synthesis loop. The cadences (daily, weekly, monthly, quarterly). The synthesis output per cadence. Decisions traceable to feedback. Roadmap input. Spec input. Stakeholder communication. Closing the loop after decisions ship. Cadence drift. Synthesis ownership. Common failures. + +## Implementation choices that stay internal + +Specific tooling for synthesis production. Specific document templates per cadence. Specific reviewer workflows. Specific dashboard configurations. The team's own conventions for owning synthesis. These vary by team. diff --git a/skills/user-feedback-aggregation/references/tooling-considerations.md b/skills/user-feedback-aggregation/references/tooling-considerations.md new file mode 100644 index 0000000..5669fc4 --- /dev/null +++ b/skills/user-feedback-aggregation/references/tooling-considerations.md @@ -0,0 +1,247 @@ +# Tooling considerations + +Tooling categories without specific endorsements. Criteria for selection. Build-vs-buy tension. + +Feedback aggregation tooling shapes what the program can do. The right tooling supports multi-channel aggregation, tagging at scale, pattern surfacing, and integration with adjacent systems. The wrong tooling produces silos, manual labor, and synthesis bottlenecks. + +This skill is platform-agnostic; specific products are not endorsed. The categories below describe what kinds of tooling exist; the team's actual product choices depend on stack, budget, and program shape. + +--- + +## Tooling categories + +Several categories of tooling support feedback aggregation. + +### Customer feedback platforms + +What they do. Aggregate feedback from multiple sources. Support tagging and categorization. Surface patterns through dashboards and analytics. + +Strengths. + +- Multi-channel support (often integrate with support, NPS, in-app, and other sources). +- Built-in tagging and pattern detection. +- Often include AI-assisted categorization. + +Weaknesses. + +- Pre-built taxonomies may not fit team-specific needs. +- Vendor-locked: switching costs grow over time. +- Coverage varies by vendor; some channels may not integrate. + +### Support ticket systems with analytics + +What they do. Track support tickets with tagging, routing, and reporting. Often the primary support channel. + +Strengths. + +- Native to support workflows. +- Strong tagging and routing for support-specific work. +- Analytics on support-team metrics. + +Weaknesses. + +- Often single-channel (support only). +- Cross-channel synthesis requires additional tooling or custom integration. + +### NPS or survey platforms + +What they do. Distribute surveys, collect responses, track sentiment trends. + +Strengths. + +- Specialized for survey distribution and response collection. +- Built-in NPS or CSAT methodology. +- Trend tracking over time. + +Weaknesses. + +- Single-modality (surveys only). +- Limited integration with other feedback sources. + +### Customer relationship management (CRM) systems + +What they do. Manage customer relationships, contact history, deal pipelines, customer feedback fields. + +Strengths. + +- Rich customer context (segment, deal stage, account history). +- Integration with sales workflows. + +Weaknesses. + +- Feedback aggregation is often a side feature, not a core function. +- Cross-channel feedback synthesis requires additional configuration. + +### Custom dashboards combining feedback signal with usage analytics + +What they do. Custom-built views combining feedback data with product analytics. + +Strengths. + +- Tailored to the team's specific needs. +- Cross-channel synthesis built-in to the design. +- Combines feedback patterns with behavioral signals. + +Weaknesses. + +- Build cost and ongoing maintenance. +- Skill requirements: data engineering or analytics expertise. + +--- + +## The criteria for tooling selection + +What to evaluate when choosing tooling. + +Multi-channel aggregation. Does it integrate with the channels the team uses? Or does it cover one channel only? + +Tagging at scale. Does it support the tagging volume the program needs? Manual tagging at low volume; AI-assisted at high volume. + +Pattern surfacing. Does it surface patterns, or is it just storage? Some tools store feedback without making it analyzable. + +Integration with other systems. Does it connect to roadmap tools, ticketing systems, communication channels? Isolated tools produce silos. + +Scaling. Does it scale with program volume? Tools that work at 100 items/week may break at 1000 items/week. + +Cost. License or build cost vs the value produced. Expensive tooling that fits is sometimes worth it; cheaper tooling that does not fit is often more expensive in practice. + +Team skill match. Does the team have skills to use the tool effectively? Sophisticated tools that the team cannot operate produce value that does not get realized. + +--- + +## The build-vs-buy tension + +Most programs end up with a mix. + +The reasons to buy. + +- Faster setup. Off-the-shelf tools work immediately. +- Specialized expertise. Vendors have built tooling for many programs. +- Standard features that the team would not build themselves. + +The reasons to build. + +- Cross-channel synthesis often requires custom work that off-the-shelf tools do not support. +- Team-specific tagging schemas and dashboards. +- Integration with the team's specific stack. + +The hybrid pattern. + +- Off-the-shelf tools for primary channels (support ticketing, NPS surveys). +- Custom dashboards for cross-channel synthesis. +- Custom integration to bring data together. + +The hybrid is more common than pure build-or-pure-buy in practice. + +--- + +## Volume considerations + +Different volume tiers warrant different tooling approaches. + +Low volume (under 100 items/week). + +- Manual tagging is feasible. +- Off-the-shelf tools usually sufficient. +- Custom build often overkill. + +Mid volume (100-1000 items/week). + +- AI-assisted tagging often worth the investment. +- Multi-channel aggregation tools earn their keep. +- Custom dashboards often add value. + +High volume (1000+ items/week). + +- Heavy AI-assisted or automated tagging. +- Custom infrastructure for cross-channel synthesis. +- Team capacity becomes the bottleneck; tooling must reduce manual work substantially. + +Very high volume (10,000+ items/week). + +- Often requires custom data engineering. +- Sampling and aggregation strategies replace per-item review. +- Tooling investment is substantial. + +--- + +## Integration considerations + +Feedback aggregation rarely lives alone. + +Common integrations. + +- Roadmap tools. Feedback patterns feed roadmap candidates. Tools that integrate (or are linked through workflows) reduce manual transfer. +- Spec writing. Feedback context for spec drafts. +- Communication channels. Slack or email for surfacing patterns to the team. +- Customer success systems. Closing the loop with users; account-level feedback views. +- Product analytics. Cross-reference feedback with usage patterns. + +The integration discipline. Tooling that integrates produces value compound across the systems. Isolated tooling produces silos that the team must manually bridge. + +--- + +## AI-assisted feedback work + +AI plays an increasing role in feedback aggregation. + +Common AI uses. + +- Automatic categorization and tagging. +- Sentiment classification. +- Pattern surfacing across feedback items. +- Summary generation for synthesis documents. +- Anomaly detection for drift identification. + +The discipline. + +- AI suggestions get human review at pattern-level. +- Critical decisions remain human-driven; AI accelerates the work. +- AI's biases (overfitting to training data, surface-level patterns) get checked through human pattern review. + +The honest framing. AI does not replace human synthesis; it supports it. Programs that automate synthesis entirely produce volume without judgment; programs that integrate AI with human review produce signal at scale. + +See `ai-content-collaboration` for the broader workflow discipline that applies to AI-assisted feedback work. + +--- + +## Privacy and data considerations + +Feedback often contains user information. + +Considerations. + +- User consent for feedback use beyond the immediate channel. +- Anonymization where appropriate (especially for sensitive feedback). +- Data retention policies. +- Compliance with regulations (GDPR, CCPA, industry-specific). + +The discipline. Tooling choices include data handling considerations. Vendors with poor data practices can create compliance issues regardless of tool capability. + +--- + +## Common tooling failures + +Single-channel reliance. Tooling supports only one channel; cross-channel synthesis impossible without additional work. + +Overly generic tools. Pre-built taxonomies and dashboards do not match team needs. + +Custom build that consumes capacity. Building feedback infrastructure absorbs PM and engineering capacity that should produce product. + +Volume mismatch. Tools that fit current volume break when the program scales. + +Integration neglected. Feedback tooling isolated from roadmap, spec, customer success systems. + +AI without review. Automated categorization without human pattern review produces patterns the team cannot trust. + +Tooling-led process. The tool drives the process rather than the process driving tool selection. The team adopts a tool's workflow rather than designing for their needs. + +--- + +## Methodology-level choices that stay in the public skill + +The tooling categories. The criteria for selection. The build-vs-buy tension. Volume considerations. Integration considerations. AI-assisted feedback work. Privacy and data considerations. Common failures. + +## Implementation choices that stay internal + +Specific tooling vendor selections. Specific integration configurations. Specific dashboard designs. Specific data pipelines. The team's own conventions for tool evaluation. These vary by team, stack, and program shape. diff --git a/skills/ux-research/SKILL.md b/skills/ux-research/SKILL.md new file mode 100644 index 0000000..2de3cb2 --- /dev/null +++ b/skills/ux-research/SKILL.md @@ -0,0 +1,252 @@ +--- +name: ux-research +description: "Plan and execute user research including research planning, recruiting, interview design, qualitative synthesis, and translating findings into product decisions. Use this skill whenever the user wants to plan user research, design interviews, recruit participants, conduct discovery, run formative research, or synthesize qualitative findings. Triggers on user research, UX research, user interviews, discovery research, generative research, formative research, qualitative research, user insights, research synthesis, recruitment, interview guide, jobs to be done. Also triggers when product decisions are being made without user input and the user wants to fix that." +category: research +catalog_summary: "Research planning, user interviews, qualitative synthesis" +display_order: 1 +--- + +# UX Research + +Plan and execute user research that produces decisions, not just decks. Stack-agnostic. Tool-agnostic. + +This skill is for generative and discovery research. For testing existing designs, use `usability-testing`. For mapping the full customer experience, use `journey-mapping`. + +--- + +## When to use + +- Starting a new product or major feature without sufficient user understanding +- Diagnosing why something isn't working without clear data signals +- Generating new opportunity hypotheses +- Validating a strategic direction before significant investment +- Building empathy across a team that's drifted from users +- Translating "we should talk to users" intent into a real plan + +## When NOT to use + +- Testing a specific design or prototype (use `usability-testing`) +- Mapping the full journey of an existing experience (use `journey-mapping`) +- Quantitative measurement (use `analytics-strategy`) +- Conversion testing (use `cro-optimization`) + +--- + +## Required inputs + +- The research question(s) - what you need to answer +- Stakeholder buy-in (who needs the findings, what decisions hinge on them) +- Access to users (current customers, prospects, lapsed users, target segments) +- Timeline and budget +- Any prior research to build on + +--- + +## The framework: 6 phases + +### 1. Frame the question + +Bad questions produce bad research. Spend disproportionate time on framing. + +Good research questions: +- Specific (not "How do users feel about our product?") +- Open-ended (not "Do users like feature X?") +- Decision-relevant (the answer changes what gets built) +- Researchable (can be answered through user contact, not just analysis) + +Examples: + +\| Weak question \| Better question \| +\|---\|---\| +\| "Do users like our onboarding?" \| "Where in onboarding do new users feel uncertain about whether to continue?" \| +\| "What features should we build?" \| "What unmet needs do current users have when [specific job]?" \| +\| "Why is conversion low?" \| "What's the user mental model when they reach the pricing page, and where does it diverge from our intent?" \| + +### 2. Choose the method + +The method follows the question. + +Generative methods (what's true?): + +- In-depth interviews. 60 minutes, 5 to 15 participants. Best for understanding context, motivation, mental models. +- Contextual inquiry. Observe users in their environment doing their work. Best for workflow understanding. +- Diary studies. Participants log their experience over days/weeks. Best for behaviors that don't manifest in a single session. +- Field research. Spend time where users live/work. Best for cultural and contextual understanding. +- Surveys (qualitative-heavy). When you need broad signal with open-ended responses. + +Validation methods (is this hypothesis right?): + +- Concept testing. Show a description, mockup, or prototype. Get reactions. +- Card sorts. Validate information architecture. +- Tree tests. Validate findability without visual design influence. + +(For testing usability of working designs, see `usability-testing`.) + +### 3. Recruit + +The recruit makes or breaks the research. + +Recruit criteria: + +- Match the audience the research targets (not "anyone willing") +- Mix of behaviors (active users, lapsed users, never-users) +- Mix of demographics where relevant +- Excludes friends, family, employees (biased) +- Excludes professional research participants if possible (different population) + +Recruit channels: + +- In-product recruiting (intercept current users) +- Email outreach to user segments +- Recruiting platforms (UserInterviews, Respondent, etc.) +- Customer support team referrals +- Field intercept for in-person + +Incentive: Pay participants. Standard rates: $50 to $150 for 60 minutes, more for executives or specialized professions. + +Recruit volume: Plan for 20 to 30 percent no-show. Recruit 7 to schedule 5. + +### 4. Conduct + +The interview or session itself. + +Pre-interview: + +- Send confirmation 24 hours and 1 hour before +- Test recording setup (audio quality is non-negotiable) +- Prepare interview guide (see template) +- Have a notetaker if possible (frees the interviewer to focus) + +During the interview: + +- Record video and audio (with consent) +- Open with rapport-building, not the research questions +- Use open-ended questions ("Tell me about the last time...") +- Use silence (let participants fill it; don't rush to the next question) +- Ask "why" but not too many times in a row (becomes interrogation) +- Ask for specifics and examples ("Can you walk me through what you did?") +- Probe contradictions gently ("Earlier you said X, now you're saying Y; help me understand") +- Watch for moments of emotion (often signal something important) +- Don't sell or convince - this is listening, not pitching + +Anti-patterns: + +- Leading questions ("Don't you find this confusing?") +- Hypothetical questions ("Would you use a feature that...?") - poor predictor of behavior +- Multiple questions at once +- Interrupting +- Filling silence +- Interviewing your hypothesis (only asking questions that confirm what you already think) + +### 5. Synthesize + +Notes don't become insights automatically. + +The synthesis process: + +1. Capture observations. From recordings, notes, transcripts. Each observation is a single data point: a quote, a behavior, an emotion, a moment. +2. Affinity mapping. Cluster observations into themes. Physical sticky notes or digital equivalents. +3. Find patterns. Themes that appear across multiple participants are signal. One-off observations are interesting but weaker. +4. Identify insights. An insight is more than a theme. It's a non-obvious finding that explains a why or implies a so what. +5. Test the insight against the data. If the insight only fits some interviews, it's a hypothesis, not an insight. +6. Distinguish signal from noise. A belief that 1 of 8 participants holds may be noise. A belief 6 of 8 hold is signal. + +Heuristics for strong insights: + +- They surprise the team (insights you already knew aren't insights) +- They explain a "why" the team has been guessing about +- They imply specific actions (so what?) +- They hold up across multiple data points +- They can be stated in one or two sentences + +### 6. Communicate + +Findings die in slide decks. Plan distribution. + +Outputs that work: + +- Top-line insights document. 5 to 10 insights, clearly stated, with supporting quotes. +- Highlight reels. Edited 5 to 10 minute video of key participant moments. More persuasive than any document. +- In-room workshops. Walk stakeholders through the synthesis themselves. They internalize when they participate. +- Per-stakeholder briefs. Different audiences need different framings. CEO wants strategic implications. Designers want pain points. Engineers want use cases. + +Outputs that fail: + +- 80-slide decks that get skimmed +- Reports that no one reads past the executive summary +- Verbose narrative summaries +- Insights that sit in a doc no one re-opens + +--- + +## Workflow + +1. Frame the research question. With stakeholders. Multiple iterations. +2. Pick the method. Match to the question. +3. Plan logistics. Timeline, budget, recruit, tools, team. +4. Recruit. Start early. Slow recruits delay everything. +5. Pilot. Run 1 to 2 sessions before the main batch. Refine the guide. +6. Conduct. Stay disciplined to the guide while staying open to surprises. +7. Synthesize. Don't wait until all sessions are done; start mid-way. +8. Communicate. Multiple formats. Multiple audiences. +9. Track impact. Did decisions change because of the research? If not, the research failed regardless of quality. + +--- + +## Failure patterns + +- Research without a decision. Findings have no home. Effort wasted. +- Vague research questions. Bad questions produce uninterpretable answers. +- Recruiting "anyone willing." Sample doesn't match audience. +- Over-recruiting professional participants. Pattern-matched answers, not real users. +- Leading questions in the guide. Findings reflect the researcher, not the user. +- Skipping synthesis. Notes alone aren't insights. +- Insights that confirm the team's existing beliefs. Suspect those especially. +- Findings that never ship. Research findings that don't change product decisions are decoration. +- Single research project for years of decisions. Research has a shelf life. Refresh. +- Research as one-time project. Continuous discovery beats episodic research. + +--- + +## Output format + +Default outputs: + +1. Research plan (before research starts) - `research-plan-[topic].md` +2. Interview guide - `interview-guide-[topic].md` +3. Findings doc (after synthesis) - `research-findings-[topic].md` +4. Highlight reel (video, separately produced) + +Findings document structure: + +```markdown +# [Topic] research findings + +## Question we set out to answer +[Specific question] + +## Method +[Approach, sample size, dates] + +## Top insights +1. [Insight, stated in one sentence] + - Supporting evidence: [Quotes, behaviors] + - Implication: [What this means for product/strategy] +2. [Insight 2] + ... + +## Themes (less prominent than top insights, still worth noting) +[List] + +## Outliers worth investigating +[Single-participant observations that may be signal in disguise] + +## Recommended next steps +[Specific actions] +``` + +--- + +## Reference files + +- [`references/interview-guide-template.md`](references/interview-guide-template.md) - Structured interview guide template with example openings, probes, and closes. diff --git a/skills/ux-research/references/interview-guide-template.md b/skills/ux-research/references/interview-guide-template.md new file mode 100644 index 0000000..88fcb00 --- /dev/null +++ b/skills/ux-research/references/interview-guide-template.md @@ -0,0 +1,241 @@ +# Interview Guide Template + +A structured template for in-depth research interviews. Customize the sections to your topic. Length: typically 60 to 75 minutes. + +--- + +## Pre-interview prep + +Participant info: +- Name: +- Role / context: +- How they were recruited: +- Anything noteworthy from screener: + +Research question being answered: [The specific question this interview is helping answer] + +Top 3 things I'm trying to learn: +1. +2. +3. + +Hypotheses I'm holding loosely: +- [What I think I'll find. Naming this helps me notice when I confirm vs disconfirm it.] + +Recording setup: +- [ ] Audio recorder tested +- [ ] Video recorder (if applicable) tested +- [ ] Notetaker confirmed (or not present) +- [ ] Consent form sent + +--- + +## Section 1: Welcome and rapport (5 to 10 minutes) + +Goal: Put the participant at ease. Start collecting context. + +### Opening + +> "Thanks so much for joining today. As I mentioned, we're [purpose: studying how people do X / learning about Y / etc.]. There are no right or wrong answers; I'm here to learn from your experience. +> +> Before we start, do you have any questions? +> +> A few practical notes: I'll be recording so I can focus on listening rather than note-taking. The recording stays internal and is used only for our research. I'll never quote you by name without permission. You can ask me to stop the recording any time. Sound good? +> +> Great. Let's start with something easy." + +### Easy opener + +> "Tell me a little about yourself. What's your role, what does a typical [day / week / project] look like?" + +[Listen for context: industry, role, scale, constraints. Take notes on anything you want to come back to.] + +--- + +## Section 2: Context (10 to 15 minutes) + +Goal: Understand the world the participant lives in. Establish the context that shapes their decisions and behavior. + +### Probes (pick 3 to 5 that fit your topic) + +> "Walk me through how you handle [task] today, from start to finish." + +> "What's the last time you [specific behavior or event]? Tell me about that." + +> "Who else is involved when you [activity]? What's their role?" + +> "What tools do you use? Why those specifically?" + +> "What's typical, and what's unusual about how you approach this?" + +> "Where does your [organization / team] stand on [topic]? Any constraints I should understand?" + +### Listening notes + +- Look for specific examples, not generalities. "I've never been frustrated by X" is less reliable than "Tell me about the last time X frustrated you." +- Watch for emotional tone: where do they perk up, get quiet, or shift body language? +- Note any language they use that's different from how the team frames things. + +--- + +## Section 3: The core question (20 to 30 minutes) + +Goal: Address the heart of the research. + +### Sample probes for common research goals + +#### If exploring problems / unmet needs + +> "Tell me about the last time you had to [specific situation related to research]." + +> "What was hardest about that?" + +> "What did you try? What worked, what didn't?" + +> "If you had a magic wand and could change one thing about how this works, what would it be?" + +> "When you think about [topic], what frustrates you most?" + +#### If exploring mental models + +> "How would you explain [concept] to someone who's never heard of it?" + +> "When you hear [term we use], what comes to mind?" + +> "Can you draw or sketch how you think about [process]?" + +> "What's the goal when you [action]? What does success look like?" + +#### If exploring evaluation behavior + +> "Walk me through the last time you decided to [action]. How did you decide?" + +> "What were you comparing? How did you compare them?" + +> "What information would have helped you decide?" + +> "What made you confident in your decision? What made you nervous?" + +#### If exploring product or feature use + +> "Tell me about a time you used [product / feature]. Why? What happened?" + +> "When does [product] work well for you? When does it fall short?" + +> "What's the first thing you do when you open [product]?" + +> "What would have to be true for you to [action: recommend, expand use, switch]?" + +### Probe library (use as needed) + +> "Tell me more about that." + +> "What was that like for you?" + +> "Why does that matter to you?" + +> "Give me an example." + +> "Help me understand what you mean by [term]." + +> "Earlier you said X, now you're saying Y. Help me understand." + +> "What were you thinking at that moment?" + +> "What did you do next?" + +### Things to avoid + +- Leading questions ("Don't you think it would be better if...?") +- Hypothetical questions about future behavior ("Would you pay for...?") +- Multi-part questions +- Filling silence too quickly +- Defending the product +- Selling the product +- Asking "why" more than 2 to 3 times in a row (becomes interrogation) + +--- + +## Section 4: Reactions to specific stimuli (optional, 10 to 15 minutes) + +Goal: Get specific reactions to a concept, prototype, message, or design. Skip if research is purely generative. + +> "I'd love to show you something we're thinking about. There are no wrong reactions - whatever comes up for you is helpful. Take a look [share screen / show prototype / read description]." + +[Wait. Don't fill the silence.] + +> "What's your initial reaction?" + +> "What questions does this raise?" + +> "If you saw this in [context], what would you do next?" + +> "What's confusing or unclear?" + +> "Is there anything that doesn't fit your situation?" + +[Be especially alert to confused expressions, silences, and "I'm not sure what this is for." These are signal.] + +--- + +## Section 5: Wrap-up (5 to 10 minutes) + +Goal: Capture anything missed. Leave the participant feeling good about the experience. + +### Catch-all questions + +> "Is there anything I should have asked but didn't?" + +> "Is there anything you'd want me to know about this topic that didn't come up?" + +> "If you could give one piece of advice to the team building this, what would it be?" + +### Closing + +> "This was incredibly helpful. Thank you for the time and the candor. The [incentive] should arrive [timeline]. If you think of anything else after we hang up, my email is [email]; happy to hear from you. +> +> Last question: would it be okay if I reached out for follow-up research? I won't bombard you, but if something specific comes up and your perspective would be helpful, I'd love to be able to ask." + +--- + +## Post-interview (within 1 hour) + +While memory is fresh: + +- [ ] Write down 3 to 5 most surprising or vivid moments +- [ ] Note any quotes worth coming back to +- [ ] Note any new questions raised by this interview that should change subsequent ones +- [ ] Add to the running synthesis (don't wait to start synthesis until all interviews are done) + +--- + +## Common interview pitfalls and recoveries + +\| Pitfall \| Recovery \| +\|---\|---\| +\| Participant gives short, surface answers \| "Tell me more about that." Or wait silently. Often produces depth. \| +\| Participant goes far off-topic \| "That's interesting. Let me bring us back to [topic]." \| +\| You realize the question was leading \| "Let me ask that differently. What's been your experience with [topic], in your own words?" \| +\| Participant asks what you're working on \| "I want to hear your unbiased thoughts first. Happy to share more at the end." \| +\| Participant tries to give you the "right" answer \| "Honestly, the more frank you can be, including frustrations or criticisms, the more valuable for us." \| +\| You realize you're 20 minutes over \| Wrap promptly. Ask the most important remaining question. End on time. \| +\| Participant has emotional reaction \| Pause. Acknowledge. "That sounds like it was really frustrating. Take your time." Don't rush past. \| + +--- + +## Customization notes + +This template is a scaffold. Adapt: + +- The sections to fit the topic +- The number and type of probes +- The amount of time per section +- Whether to include stimuli (Section 4) + +What stays constant: + +- Open with rapport, not the research question +- Use specific recent examples, not abstract opinions +- Use silence +- Don't lead +- Wrap on time, with grace diff --git a/skills/vendor-evaluation/SKILL.md b/skills/vendor-evaluation/SKILL.md new file mode 100644 index 0000000..03b9d4c --- /dev/null +++ b/skills/vendor-evaluation/SKILL.md @@ -0,0 +1,280 @@ +--- +name: vendor-evaluation +description: "Evaluate, select, and contract with vendors and SaaS tools. Use this skill when comparing alternatives, running an RFP, scoring vendors against criteria, negotiating contracts, planning a switch, or assessing a vendor's risk. Triggers on vendor evaluation, RFP, vendor selection, build vs buy, SaaS evaluation, vendor scorecard, vendor comparison, contract negotiation, vendor switch, procurement. Also triggers when a renewal is coming up or when a tool isn't meeting expectations." +category: process-and-team +catalog_summary: "Tool and vendor selection using a structured rubric" +display_order: 3 +--- + +# Vendor Evaluation + +Pick the right tool or service, negotiate fair terms, and avoid the lock-in traps. Stack-agnostic. Applies to SaaS, infrastructure providers, agencies, and any external dependency. + +--- + +## When to use + +- Selecting a tool or vendor for a new need +- Evaluating alternatives to a current vendor +- Build vs buy analysis +- Renewal coming up: should we stay or switch? +- Running a formal RFP or RFI +- Comparing finalists in a vendor selection +- Negotiating a contract +- Assessing vendor risk (financial, security, dependency) + +## When NOT to use + +- General cost reduction (use `cost-optimization`) +- Specific contract legal terms (those go to legal) +- Performance issues with an existing vendor (try fixing before switching) +- Hiring an agency for a one-off project (lighter framework needed) + +--- + +## Required inputs + +- The need (what problem are you solving, what would success look like) +- Constraints (budget, timeline, integration requirements) +- Stakeholders (users, IT, security, finance, legal) +- Existing context (what's already used, what's been tried) +- Compliance requirements + +--- + +## The framework: 5 phases + +A structured vendor evaluation. Skip phases at your peril. + +### Phase 1: Define the need + +Before looking at vendors, define what you actually need. + +- What problem are you solving? +- What's the user / use case? +- What does "success" look like in 6 months? In 2 years? +- What's the budget (range, not just ceiling)? +- What's the timeline? +- Are there must-have integrations or constraints? + +The temptation: skip this and start demoing. Vendors are happy to show off; you end up choosing what looks shiny rather than what fits. + +### Phase 2: Build vs buy + +Before evaluating vendors, decide whether you should build instead. + +Build when: +- It's core to the business (differentiating) +- The need is so specific no vendor matches +- The economics work at your scale +- You have the team to maintain it +- Vendor lock-in would be unacceptable + +Buy when: +- It's table stakes (not differentiating) +- The need is well-served by existing products +- The economics favor it +- The team should focus elsewhere +- The vendor's specialization beats your generalism + +Most teams over-build. The rule of thumb: buy unless there's a strong reason to build. Then question even that strong reason. + +### Phase 3: Generate the shortlist + +Cast a wider net than feels comfortable, then narrow. + +Sources: +- Internal team's existing knowledge +- Industry analyst reports (Gartner, Forrester, etc.) +- Peer recommendations (other companies similar to yours) +- Reviews (G2, Capterra; with caveats about review quality) +- Adjacent vendors you already use (often have the feature you need) +- Open-source alternatives + +Cast wide first. Aim for 5-8 candidates. Then narrow to 2-4 finalists for deep evaluation. + +### Phase 4: Score the finalists + +Use a scorecard. Without one, you'll be swayed by demo theatrics or who has the friendliest sales rep. + +Scorecard dimensions (weight by your situation): + +Functional fit (40%): Does it do what you need? Edge cases handled? UX quality. Workflow fit. + +Technical fit (15%): Integration with your stack. API quality and completeness. Data export and portability. Performance at your scale. Self-hosted, hybrid, or SaaS-only. + +Operational fit (10%): Onboarding effort. Training and adoption. Documentation quality. Support quality (test by submitting a ticket). SLAs. + +Security and compliance (10%): SOC 2, ISO 27001, HIPAA, etc., as applicable. Data residency. Encryption at rest and in transit. Access controls and audit logs. Penetration test results (ask). Subprocessors. + +Vendor health (10%): Years in business. Funding and runway (or revenue if private). Customer base size and similar customers. Public references. Roadmap visibility. + +Cost (10%): License or subscription cost. Implementation and onboarding cost. Training cost. Integration cost. Opportunity cost (in-house resource time). Switching cost (in case of failure). + +Lock-in risk (5%): Data export quality. Standard formats vs proprietary. Migration paths to alternatives. Open standards alignment. Contract escape clauses. + +Score each finalist 1-5 on each dimension. Multiply by weight. Sum. + +The score isn't gospel. It surfaces the tradeoffs. + +### Phase 5: Negotiate + +Most enterprise contracts are negotiable. Most aren't negotiated. + +What's negotiable: +- Price (multi-year, volume, prepayment, end-of-quarter timing) +- Terms (payment schedule, renewal terms) +- Success commitments (training, onboarding, support) +- SLAs (uptime, response time, credits) +- Termination clauses (auto-renewal, notice period, data export) +- Liability caps and indemnity (legal will care about these) +- Subprocessors and data handling (security/legal cares) + +Common negotiation moves: +- Multi-year discount (3-year for a 15-30% discount is common) +- Volume tiers (commit to higher usage for a per-unit discount) +- Annual prepayment for a discount +- Free or discounted onboarding +- Pilot pricing (trial period at reduced rate) +- "Most favored customer" clauses (if your size warrants) + +What to avoid: +- Multi-year lock with no escape clause for material breach +- Auto-renewal with short notice window (under 60 days; want longer) +- "All right, no further negotiation" stance from the start +- Signing without legal review + +--- + +## Workflow + +### Step 1: Define the need + +Write a one-page brief: what we need, why, success criteria, constraints, stakeholders. + +### Step 2: Build vs buy + +Honestly answer the build/buy question. Document the rationale. + +### Step 3: Generate shortlist + +Wider net first, narrowed via desk research: +- Read summaries +- Skim reviews +- Look at customer logos +- Skim docs +- Skim API specs + +Eliminate obvious misfits. Land on 2-4 finalists. + +### Step 4: Run demos and trials + +For each finalist: +- Demo with the use case (don't take their default demo; bring yours) +- Trial period if possible +- Reference calls with similar customers +- Pilot with real data if feasible + +Don't be charmed by the polished demo. Try it with your real workflow. + +### Step 5: Run security and compliance review + +Critical for any vendor handling sensitive data: +- Request SOC 2 / ISO 27001 reports +- Review their security questionnaire (most have one ready) +- Verify data handling matches your requirements +- Identify subprocessors + +This can take weeks for enterprise vendors. Start early. + +### Step 6: Score + +Apply the scorecard. Do this collaboratively with stakeholders. + +The scoring conversation matters more than the final number. It surfaces disagreement (one person scored UX 5, another scored 2: why?). + +### Step 7: Negotiate + +With the apparent winner: +- Open negotiation by asking for terms (not just price) +- Be willing to walk +- Run negotiations with #2 in parallel where appropriate (gives you leverage) + +### Step 8: Plan the rollout + +Contract signing is the start, not the end. Plan: +- Onboarding owner +- Training plan +- Migration plan if replacing an incumbent +- Success criteria at 30, 90, 180 days +- Renewal calendar + +### Step 9: Document + +Record: +- The decision and the rationale +- Alternatives considered +- Scorecard results +- Negotiated terms +- Renewal date and notice deadlines +- Owner of the relationship + +This is gold for the next renewal or the next similar evaluation. + +--- + +## Failure patterns + +Skipping the needs definition. Demoing first. Buying what's shiny. Realizing 6 months in that the actual need wasn't met. + +Single-source decisions. Talking to one vendor; deciding. No comparison. Probably overpaying or under-fitting. + +Charisma-driven decisions. Buying based on the sales rep's likability. The product is what you'll use for years; the rep won't be there. + +Reference calls that the vendor curated. Of course their references love them. Find references the vendor didn't suggest. + +Glossing over security. Security review skipped because of timeline pressure. Then a breach. Slow down or accept the risk explicitly. + +Demos that don't match the use case. Their default demo, not yours. Always do a use-case demo. + +Trial that doesn't simulate real usage. A trial with synthetic data tells you the product works in synthetic conditions. Use real (or close to real) data. + +Negotiating only on price. Terms, SLAs, and exit clauses matter more for long-term satisfaction than 5% price. + +Auto-renewal without notice tracking. Renewal happens; rate goes up 15%. No one was watching. Track renewals; review with notice. + +Lock-in without exit plan. Tightly integrating into a vendor's proprietary surface. When you want to leave, you can't. Plan exit at the start. + +Multi-year contract for an unproven vendor. Save the multi-year for vendors you trust. New vendor: shorter term, evaluate after. + +No internal champion. Tool selected; no one drives adoption. Tool sits unused. Identify the champion before signing. + +Negotiating after a verbal commitment. "Yes, we want to buy" means they have less reason to negotiate. Keep options open until terms are settled. + +Ignoring red flags in security review. Vendor's security responses are evasive or incomplete. Treat as a no. + +Comparing apples to oranges. Vendors price differently (per user, per usage, flat). Build a comparable cost model at your scale. + +--- + +## Output format + +A vendor evaluation document includes: + +- Need brief: problem, success criteria, constraints +- Build vs buy decision: with rationale +- Shortlist: 2-4 finalists with brief description +- Scorecard: filled out per finalist +- Demo and trial notes: what was learned +- Security and compliance summary: findings per finalist +- Reference call notes: what customers said +- Recommendation: which vendor, with rationale +- Negotiated terms: what was agreed +- Rollout plan: onboarding, training, migration +- Renewal calendar: with notice deadline + +--- + +## Reference files + +- [`references/evaluation-rubric.md`](references/evaluation-rubric.md) - Scoring template with weighted dimensions, 1-5 scale criteria for each dimension, and a worked vendor-comparison example. diff --git a/skills/vendor-evaluation/references/evaluation-rubric.md b/skills/vendor-evaluation/references/evaluation-rubric.md new file mode 100644 index 0000000..6689c2f --- /dev/null +++ b/skills/vendor-evaluation/references/evaluation-rubric.md @@ -0,0 +1,178 @@ +# Evaluation rubric + +A scoring template for vendor evaluations. Adapt the dimensions, weights, and scale to fit the decision. + +## The rubric structure + +Score each candidate on each dimension using a 1-5 scale. Multiply by the dimension's weight. Sum for a total. + +Numbers do not make the decision. They make differences visible. Use the totals to challenge your gut, not replace it. + +## Dimensions and what to score + +### Functional fit (typical weight: 25%) + +How well does the product do the specific job? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Does the job exactly. Built for this use case. \| +\| 4 \| Does the job with minor configuration. \| +\| 3 \| Does the job with workarounds or extensions. \| +\| 2 \| Partial fit. Significant gaps. \| +\| 1 \| Wrong tool for the job. \| + +Evaluation method: trial the product on real (or representative) data. + +### Total cost (typical weight: 20%) + +Three-year total cost of ownership, including hidden fees and scaling. + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Cost is well below alternatives. Pricing is predictable. No hidden fees. \| +\| 4 \| Cost is competitive. Pricing scales gracefully. \| +\| 3 \| Cost is fair. Some scaling concerns. \| +\| 2 \| Cost is high or scaling is punitive. \| +\| 1 \| Cost is prohibitive or pricing is opaque. \| + +Evaluation method: project cost at 1x, 5x, and 10x current usage. Read the pricing page line by line. Ask sales for a custom quote at projected scale. + +### Reliability (typical weight: 15%) + +How often does it work? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Strong SLA, public status page, low historical incidents. \| +\| 4 \| Reasonable SLA, transparent status, infrequent incidents. \| +\| 3 \| Standard SLA, some visibility, occasional issues. \| +\| 2 \| Weak SLA, limited visibility, frequent issues. \| +\| 1 \| No SLA, no status page, customer reports of unreliability. \| + +Evaluation method: read the SLA, browse status page history for 90 days, search for outage reports. + +### Integrations and ecosystem (typical weight: 15%) + +How well does it fit your stack and what is the exit story? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Native integrations to your stack, comprehensive API, easy data export. \| +\| 4 \| Most integrations exist or are easy to build. Clean export path. \| +\| 3 \| Some integrations, partial API, exportable with effort. \| +\| 2 \| Limited integrations, weak API, hard to export. \| +\| 1 \| Closed ecosystem, no API, vendor lock-in. \| + +Evaluation method: list the integrations you need. Check each. Test the export. + +### Operational fit (typical weight: 10%) + +How easy is it to run? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Self-service, well-documented, low ongoing burden. \| +\| 4 \| Mostly self-service. Support responds when needed. \| +\| 3 \| Requires some hand-holding from vendor. \| +\| 2 \| Requires significant ops effort or vendor intervention. \| +\| 1 \| Black box that needs constant management. \| + +Evaluation method: read the docs, send a test support question, ask "who would own this internally" and gauge the answer. + +### Vendor durability (typical weight: 10%) + +Will they be around in 3 years? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Profitable, established, deep customer base, growing. \| +\| 4 \| Well-funded, growing, healthy customer base. \| +\| 3 \| Stable but uncertain. Some risk signals. \| +\| 2 \| Layoffs, leadership turnover, customer churn signals. \| +\| 1 \| Likely to be acquired, shut down, or pivot. \| + +Evaluation method: company news search, LinkedIn for headcount trends, customer review sites for sentiment. + +### Support quality (typical weight: 5%) + +What happens when something goes wrong? + +\| Score \| Meaning \| +\| --- \| --- \| +\| 5 \| Fast, technical, available 24/7 if needed. \| +\| 4 \| Reliable, knowledgeable, business-hours coverage. \| +\| 3 \| Adequate. Sometimes slow. \| +\| 2 \| Slow, scripted, escalation needed for real issues. \| +\| 1 \| Unreachable or unhelpful. \| + +Evaluation method: send a real technical question during the trial. Time the response. Read the answer. + +## Worked example: picking an email service provider + +Job statement: "Send 200K transactional emails per month, 50K marketing emails per month, with deliverability above 98%, webhook delivery confirmation, and integration with our CRM." + +### Weighted scores + +\| Dimension \| Weight \| Vendor A \| Vendor B \| Vendor C \| +\| --- \| --- \| --- \| --- \| --- \| +\| Functional fit \| 25% \| 5 (1.25) \| 4 (1.00) \| 5 (1.25) \| +\| Total cost \| 20% \| 3 (0.60) \| 4 (0.80) \| 2 (0.40) \| +\| Reliability \| 15% \| 5 (0.75) \| 4 (0.60) \| 5 (0.75) \| +\| Integrations \| 15% \| 4 (0.60) \| 3 (0.45) \| 5 (0.75) \| +\| Operational fit \| 10% \| 4 (0.40) \| 5 (0.50) \| 3 (0.30) \| +\| Vendor durability \| 10% \| 5 (0.50) \| 3 (0.30) \| 5 (0.50) \| +\| Support quality \| 5% \| 4 (0.20) \| 4 (0.20) \| 5 (0.25) \| +\| Total \| 100% \| 4.30 \| 3.85 \| 4.20 \| + +### What the numbers say + +Vendor A and Vendor C are close. The difference comes down to cost (B and A both better than C) vs integrations (C better than A and B). + +### What the numbers do not say + +The numbers do not capture: + +- A's pricing has a cliff at 500K monthly emails. We project crossing that within 18 months. +- C has best-in-class deliverability for our specific industry. +- B is rumored to be in acquisition talks. + +The numbers narrow the field to A and C. The qualitative read picks one. In this hypothetical: Vendor C wins on the strength of deliverability and ecosystem fit, despite being more expensive, because deliverability is the actual job and cost is recoverable. + +### What the decision memo looks like + +``` +Vendor: C +Reasoning: +- Best functional fit on deliverability and webhook reliability. +- Strongest ecosystem and exit story. +- Higher cost is justified by ROI from deliverability lift. +- A was a strong second; we will revisit if C disappoints in + year 1. + +Decision date: [date] +Reviewer: [person] +Next review: [date + 12 months] +Contract terms: +- 1-year commit, with option to extend +- Termination notice: 60 days +- Data export confirmed working in trial +``` + +## Adapting the rubric + +Different decisions weight dimensions differently. Some examples: + +- Hosting decision: reliability and operational fit weighted higher. +- CMS decision: functional fit and integrations weighted higher. +- Analytics decision: vendor durability and integrations weighted higher (you keep data here for years). +- Payment processor decision: reliability, support quality, and vendor durability weighted higher. + +Adjust weights before scoring. If you adjust after, you are rationalizing. + +## How to use the rubric without lying to yourself + +- Score independently first if multiple stakeholders are evaluating. Compare scores. Discuss the differences. +- Sleep on the scores before deciding. +- If the math points to a vendor your gut hates, find out why. Either the rubric is missing a dimension or your gut is wrong. Both happen. +- Document the score, the weights, and the qualitative notes. Store with the contract. diff --git a/skills/vertical-site-conventions/SKILL.md b/skills/vertical-site-conventions/SKILL.md new file mode 100644 index 0000000..b9f6e22 --- /dev/null +++ b/skills/vertical-site-conventions/SKILL.md @@ -0,0 +1,213 @@ +--- +name: vertical-site-conventions +description: "Compose pages and sites that read as their vertical: ecommerce-catalog storefronts that look like storefronts, hospitality-food sites that look like restaurants, b2b-manufacturer sites that look industrial. Use this skill whenever the user wants to build a site that looks like the vertical it serves, fix a build that reads as generic or off-vertical, build to an experience bar produced by competitor-experience-audit, or compose pages with the merchandising, density, and layout conventions a credible site in the category is expected to carry. Triggers on vertical conventions, storefront layout, ecommerce layout, retail conventions, merchandising layout, category page composition, site composition, build to the experience bar, make it look like the vertical, off-vertical, looks generic, build conventions for a vertical, site grammar. Also triggers when a build that is technically clean reads wrong for its category, and the cause is composition, not visual taste." +category: design +catalog_summary: "Vertical page and site composition built to the experience bar" +display_order: 4 +--- + +# Vertical Site Conventions + +Compose pages and whole sites to the layout, density, and merchandising conventions that make a build read as a credible member of its vertical. Stack-agnostic. Works on any framework that can express server-rendered pages and component composition. + +This skill owns vertical-level composition: which modules go where, how dense the page is, how much of the catalog or offering is surfaced, and which paths the navigation serves. It routes the day-to-day visual decisions to `design-standards`, the aesthetic register to `creative-direction`, the site-structure modeling to `information-architecture`, and the component implementation to `frontend-component-build`. It does not duplicate any of them; it composes their outputs into a vertical-correct site. + +It is the build-side counterpart to `competitor-experience-audit`. The audit measures the field on seven dimensions; this skill builds to those same seven, dimension by dimension. The two are deliberately structured as two sides of one standard so an experience bar produced by the audit maps one-to-one onto what this skill builds. + +--- + +## When to use + +- Building a new site in a vertical you have not built in before +- Fixing a build that reads as generic or off-vertical even though it is technically clean (the SEO, accessibility, and component implementation are correct, but the page does not read like its category) +- Building to an experience bar produced by `competitor-experience-audit` (the audit-fed path is the intended use) +- Adding the merchandising, density, and navigation conventions a site in this category is expected to carry +- Building a showcase or demo where the build must read as its vertical, not as a generic SaaS landing page + +## When NOT to use + +- Day-to-day visual decisions on a known build (use `design-standards`) +- Defining the brand register or aesthetic from scratch (use `creative-direction`, `brand-archetype-system`, `brand-discovery`) +- Building one component well (use `frontend-component-build`) +- Modeling site structure and navigation hierarchy from scratch (use `information-architecture`) +- Building a formal design system or token system (use `design-system`) +- Auditing the competitive field for what conventions exist (use `competitor-experience-audit`; this skill consumes that audit's output, it does not produce it) + +--- + +## Required inputs + +- The site shape the build is for, from the controlled list: `ecommerce-catalog`, `inventory-listing`, `directory-marketplace`, `local-service-booking`, `subscription-app`, `hospitality-food`, `institution-mission`, `b2b-manufacturer`, `ecommerce-standout`, `hospitality-experience`. +- An experience bar from `competitor-experience-audit` (the cross-site patterns and gaps for the vertical). If absent, the skill falls back to the per-shape default conventions in the references; the audit-fed path is stronger and is the intended use. +- The brand register and aesthetic decisions (from `creative-direction` or already settled). This skill does not redefine them. +- The framework or technical context the build will use (the skill is stack-agnostic but the consumer needs to know). + +If the site shape is unclear, ask. Building to the wrong shape's conventions produces a build that reads off-vertical, which is the exact failure this skill exists to prevent. + +--- + +## The framework: build to the seven dimensions + +The framework mirrors the seven dimensions `competitor-experience-audit` measures. Each is expressed here as build guidance (what to do) rather than audit questions (what to observe). Run them in order; the synthesis in dimension 7 is the composition checklist that catches what the earlier six missed. + +### 1. Build the primary task as the dominant, earliest element + +The visitor arrives with a primary job. The leaders in the vertical lead with that job; off-vertical builds bury it behind marketing copy or competing CTAs. + +- Identify the vertical's primary task from the experience bar or the per-shape reference. (Ecommerce-catalog: a fitment, search, or category-entry interaction. Hospitality-food: a menu or reservation entry. Inventory-listing: a search-and-filter. Local-service-booking: a "book now" or service-picker.) +- Give that task the largest, earliest interactive treatment in the hero. +- Demote competing CTAs. The hero gets one primary action; secondary actions live below the fold or in the chrome. +- Reach the core task without scrolling on the device class the vertical's visitors use. +- For commercial pages, sticky a compact version of the primary task to the chrome so it stays reachable on scroll. + +If the primary task cannot be the hero (a constraint from a stakeholder, a regulated vertical), surface the closest equivalent and document the compromise. Do not silently push the primary task below the fold. + +### 2. Build to the vertical's layout register and density + +Most off-vertical builds default to a generic SaaS-airy landing page. Retail and catalog verticals are denser; editorial verticals are calmer; hospitality is image-led. Build to the field's density, not to a default. + +- Identify the register from the experience bar or the per-shape reference (storefront-dense, editorial-calm, marketing-airy, image-led). +- Match the field's content-per-viewport: a catalog vertical surfaces more modules above the fold than a SaaS landing page. +- Choose the module count above the fold deliberately. State the count in the build notes. +- Route the actual color, type, and aesthetic choice to `creative-direction` and `design-standards`. This skill owns the density and module-count decision, not the visual register itself. + +Composition decision lives here. Visual register lives there. Do not redefine either; route to the right skill. + +### 3. Build the merchandising and category surface the vertical uses + +How much of the catalog or offering is surfaced at once, and in what shape, is a per-vertical decision the build must own. + +- Surface the catalog the way the vertical does: how many category, collection, or entry-point modules appear before scroll. +- Signal depth the way the vertical signals it: mega-menu hover, grid of category cards, faceted-search side rail, breadcrumb-driven hierarchy. Pick one and commit; do not stack three. +- Choose flat (one tier visible) or hierarchical (parent plus child categories shown together) per the vertical's convention. +- Use icon / image / text / hybrid category presentation per the vertical. + +Cross-reference `information-architecture` for the structural modeling of the nav tree. This skill owns the compositional surface; that skill owns the structural model. + +### 4. Build both the know-what-I-want and the browse path the vertical expects + +Verticals differ on which path is primary. A catalog vertical needs both search and category browse, with search often primary. A hospitality-food site rarely needs search but always needs a menu and a reservation entry. Build to the paths the field actually offers, in the prominence the field gives them. + +- List the paths the experience bar names (by category, by brand, by attribute, by vehicle, by location, by occasion, by audience). +- Score each path as primary, secondary, or absent per the vertical. +- Build the primary paths into the hero or primary nav. Build the secondary paths into the chrome or below the fold. Drop the paths the field does not use. +- Search input prominence is a per-vertical decision: header-primary, secondary in a side rail, or absent. Match the field. + +Route the structural nav modeling to `information-architecture`; route the search UX patterns to that skill or to the project's existing search component. This skill owns which paths exist and how prominent each is. + +### 5. Build the brand posture consistently across the page + +The brand register is set by `creative-direction` and `brand-archetype-system`. This skill does not redefine it. But composition decides whether the posture holds across the page or only in the hero. + +- Carry the brand register from the hero into the nav, the cards, the empty states, the trust signals, and the footer. A premium-utilitarian register that disappears below the hero is a composition failure, not a brand failure. +- Apply the voice consistently in headings, microcopy, CTAs, and empty states. Do not let the empty states default to generic copy. +- Hold the imagery posture across the page: a vertical that uses studio product photography in the hero does not switch to abstract illustration in the trust section. + +Route the actual register choice and the voice attributes to `creative-direction` and `brand-voice`. Own the consistency requirement here. + +### 6. Build the trust and conversion signals the vertical requires + +Each vertical has a different set of trust signals it is expected to carry. A build that ships without them reads as not-yet-credible. Build them in. + +- Identify the required signals from the experience bar or the per-shape reference. (Ecommerce-catalog: reviews, guarantees, pricing transparency, stock signals, fitment confirmation, shipping promises. Hospitality-food: hours, location, reservation availability, menu price range. B2b-manufacturer: certifications, customer logos, spec sheets. Local-service-booking: licensing, insurance, service-area, response time.) +- Surface them where the field surfaces them. Reviews near the buying action; service-area in the hero; certifications in the chrome. +- Honor the functional-vs-demo line for showcase builds: real where touchable (real reviews if they exist, real cart state), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment). + +### 7. Run the synthesis as a composition checklist + +The seventh dimension is the synthesis: the specific conventions a credible build in this vertical must have, named explicitly. Run this as a pre-ship checklist before declaring the composition done. + +- Pull the conventions from the experience bar's dimension 7, or from the per-shape reference's recurring-conventions section. +- For each, confirm the build does it. Mark each item present, absent, or routed elsewhere (with a link to the routing decision). +- If three or more conventions are absent, the build is off-vertical. Go back to the earlier dimensions; this is not a polish-pass fix. +- If one or two are absent, name the reason: deliberate positioning (the wedge the build is exploiting from the audit's gaps section), constraint (stakeholder, technical), or oversight (fix before ship). + +The synthesis is what catches builds that pass dimensions 1 through 6 individually but compose into something off-vertical anyway. Run it. + +--- + +## How the skill consumes an experience bar + +When `competitor-experience-audit` has run for the vertical, its output is the input to this skill. The audit's seven dimensions map directly onto this skill's seven, in order. Concretely: + +- The audit's `Primary-task prominence` pattern names what to build in this skill's dimension 1. +- The audit's `Layout register and density` pattern names the density target for dimension 2. +- The audit's `Merchandising and category surface` pattern names the surface shape for dimension 3. +- The audit's `Primary navigation and search paths` pattern names the path inventory for dimension 4. +- The audit's `Brand register and conviction` pattern names the register `creative-direction` should be working from, which this skill carries across the page in dimension 5. +- The audit's `Trust and conversion signals` pattern names the required signals for dimension 6. +- The audit's `Recurring vertical conventions` are the checklist for dimension 7. +- The audit's `Gaps` section names the positioning opportunity the build can exploit as its wedge. + +If no audit has been run, fall back to the per-shape reference files in `references/`. The default conventions there are derived from observable cross-site patterns and are honest, but a vertical-specific audit is stronger and is the intended path. + +--- + +## Stays in its lane (load-bearing) + +This skill owns one thing: vertical-level page and site composition. It routes everything else, and that routing discipline is what keeps it useful and what keeps the catalog clean. + +- Visual tokens, color, type, contrast, spacing scale: route to `design-standards`. +- Aesthetic register, archetype, voice attributes: route to `creative-direction` and `brand-archetype-system`. +- Site structure, nav hierarchy, URL design: route to `information-architecture`. +- Component API, states, accessibility implementation: route to `frontend-component-build`. +- Formal design system, token library, component documentation: route to `design-system`. +- The audit that produces the experience bar: route to `competitor-experience-audit`. +- On-page SEO and accessibility audits: route to `seo-onpage` and `accessibility-audit`. + +If a build decision sits inside one of those skills, do not restate the standard here. Link to the skill and let it own its territory. + +--- + +## Workflow + +1. Confirm the site shape and the experience bar. Site shape from the controlled list. Experience bar from `competitor-experience-audit` if run; the per-shape reference otherwise. +2. Run dimensions 1 through 6 in order. For each, name the build decision and which other skill it routes to (for the parts that route elsewhere). +3. Run dimension 7 as a checklist. Confirm every recurring convention from the vertical is present, absent for a stated reason, or routed elsewhere. +4. Write the composition notes. Use the template in [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md). The notes are what `frontend-component-build` and `design-standards` read as the spec to implement against. +5. Hand off to the implementation skills. This skill's output is composition decisions, not finished components. The build is done when those decisions have been implemented through `frontend-component-build`, `design-standards`, and the project's component library. + +--- + +## Failure patterns + +When you spot one of these, push back before delivering. + +- "Make it look modern." Vague. Ask which vertical, which experience bar, which conventions. "Modern" without a vertical produces the generic SaaS-airy build this skill exists to prevent. +- Building to a generic / SaaS-airy default when the vertical wants a denser storefront. Retail and catalog verticals surface more per viewport than a marketing page. If the build looks calm and roomy, check the density against the field. +- Burying the primary task. A hero stuffed with marketing copy and three competing CTAs is the most common off-vertical failure. Dimension 1 is not optional. +- Redefining aesthetic vocabulary instead of routing to `creative-direction`. This skill does not coin new register names or invent new voice attributes. If the question is what posture the brand takes, that is `creative-direction`'s call. +- Treating the experience bar as optional when it is available. If `competitor-experience-audit` has run for the vertical, the bar is the spec. Building to the per-shape default while ignoring the audit's bar is half a build. +- Producing a template instead of building to the field's actual conventions. Per-shape references are starting points, not finished templates. They name the patterns the field shares; the build still has to land them in this brand and this brief. +- Skipping dimension 7. A build that passes dimensions 1 through 6 individually can still compose off-vertical. The synthesis check is the one that catches it. +- Calling implementation detail "composition". Button radius, font size, color contrast are `design-standards` decisions. Module count, primary-task prominence, category-surface depth are this skill's decisions. Do not bleed across the line. + +--- + +## Output format + +Default output is a markdown set of composition notes at `composition-[site-shape]-[brand-slug].md` in the project root. Structure: + +1. The site shape and the experience bar consulted (or "no audit available; per-shape reference used") +2. Dimension-by-dimension build decisions (1 through 6) +3. The synthesis checklist (dimension 7), each convention marked present / absent / routed +4. The wedge (which gap from the audit's gaps section this build is exploiting, if any) +5. The hand-off list: what `frontend-component-build`, `design-standards`, and `creative-direction` need from these notes to implement + +Keep notes under 1500 words. The notes are a spec for the implementation skills; if they need more detail, that is a sign one of those skills should own the deeper specification. + +--- + +## Reference files + +- [`references/shape-conventions-checklist.md`](references/shape-conventions-checklist.md) - The per-dimension build checklist applied as a pre-ship review. Mirror of the audit's dimension checklist on the build side. +- [`references/shape-ecommerce-catalog.md`](references/shape-ecommerce-catalog.md) - Default conventions for the ecommerce-catalog shape (first test case; auto-parts and similar dense storefronts). +- [`references/shape-inventory-listing.md`](references/shape-inventory-listing.md) - Stub; fill when the first inventory-listing demo is built. +- [`references/shape-directory-marketplace.md`](references/shape-directory-marketplace.md) - Stub. +- [`references/shape-local-service-booking.md`](references/shape-local-service-booking.md) - Stub. +- [`references/shape-subscription-app.md`](references/shape-subscription-app.md) - Stub. +- [`references/shape-hospitality-food.md`](references/shape-hospitality-food.md) - Stub. +- [`references/shape-institution-mission.md`](references/shape-institution-mission.md) - Stub. +- [`references/shape-b2b-manufacturer.md`](references/shape-b2b-manufacturer.md) - Stub. +- [`references/shape-ecommerce-standout.md`](references/shape-ecommerce-standout.md) - Stub. +- [`references/shape-hospitality-experience.md`](references/shape-hospitality-experience.md) - Stub. diff --git a/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md b/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md new file mode 100644 index 0000000..5b9abf4 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-b2b-manufacturer.md @@ -0,0 +1,120 @@ +# Shape: b2b-manufacturer + +Industrial manufacturers, robotics, machine tools, components, OEMs, industrial integrators. The reader arrives as a buying engineer, a procurement specialist, an operations leader, or an industrial integrator, wanting specs, applied examples with named metrics, certifications, and a short path to an engineer-not-a-sales-rep. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (robotics, machine tools, semiconductor equipment, industrial sensors), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: see the products with specs visible, see the applied examples with named metrics, and request a demo or working session with an application engineer. The B2B-manufacturer conversion is a sales conversation, not a transactional add-to-cart; the page is a credibility document and a routing tool. + +Build conventions: +- The demo / contact action is in the chrome on every page AND in the hero AND at the end of each product detail page. Three placements, one form. +- The form is short. Six fields at most (name, company, work email, role, product of interest, problem statement). Long forms signal funnel-thinking; the field's leaders treat the first call as a working session, not a qualification step. +- Specs are surfaced in HTML, not in a PDF gated behind a marketing form. PDF datasheets exist for downloading after the page has done its job, not as the only path to the spec. +- The site does not invent dollar figures for products that are quote-based. Quote-based products carry "request a quote" or "talk to engineering," not "$ X." + +## 2. Layout register and density + +Register: technical-considered. Denser than a SaaS marketing page; less dense than an ecommerce catalog. Photography is industrial: factory floor, product close-up on a clean concrete surface, single subject. Cinematic, restrained, not Instagram. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: a single-subject hero photograph of a product (or a representative product), a declarative one-line manifesto or capability statement, the demo CTA, AND a product-or-application strip. A B2B-manufacturer hero that leads with a marketing slogan and no product visible reads as a brochure, not equipment. +- The hero photograph is industrial, not lifestyle. Equipment on the factory floor or in studio; no humans in lab coats unless they are doing real work. +- Whitespace is engineered, not generous. The page is a working document. Editorial-airy layouts read as off-vertical; catalog-dense layouts read as wrong too. A considered mid-density grid is the convention. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be cinematic-premium (anode-ev style: drivetrain-as-design), technical-considered (edge-devtools style: spec-as-page), institutional-professional (counsel-law style: certification-led), or rugged-utilitarian (forge-fitness style: equipment-as-tool); not flowery or expressive. + +## 3. Product surface + +Conventions: +- A product listing page carries each product line with a name, a tagline (one declarative sentence), three to six headline specs, a product image, and a link to the detail page. +- A product detail page carries: full spec table (payload, reach, repeatability, latency, IP rating, safety standards, integration interfaces), the blurb, a primary product image plus at least one secondary image (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot), the certifications applicable to this product, the applications that use it, a demo CTA wired to this product, integration-interface section (OPC UA, EtherNet/IP, REST API, etc.). +- Specs are an HTML table, not an image of a table from a PDF. Crawlers and screen readers read it; copy-paste works. +- Product imagery is real, single-subject, industrial-product photography. Premium register matching the brand (factory-floor or studio backdrop, controlled lighting, the machine as the subject). Spec tables alone read as a brochure-with-numbers; a buyer needs to see the machine. Specs remain the spine of the page; imagery supports the specs, it does not replace them. +- Certifications are carried at the product level on the detail page, not buried on About. A buyer screening for "must be ISO 10218 certified" should see the certification on the product page in under three seconds. +- Quote-based pricing is named openly. "Quote-based"; "Talk to engineering"; "Configurations vary by integration." A blank price field signals "this is hidden from me" rather than "this is configured to your line." +- Product imagery is honest-demo where the build is a showcase: unbranded equipment, no fabricated competitor logos, no real-world manufacturer brand marks, no baked-in pricing or spec text in the image (specs live in HTML). Industrial-product image generation is prone to hallucinating brand badges and control-panel writing; the image-pipeline gate's brand-name and fabricated-logo checks are load-bearing here. + +## 4. Applications surface (the case studies) + +Conventions: +- An applications page with named industries and named metrics. Battery cell assembly, warehouse throughput, precision machining, automotive sub-assembly. Each application named with the cycle time, the throughput change, the payback period, the first-pass yield, the operator-hours saved. +- Genericized marketing prose ("a global leader in X partnered with us") is the field's miss; the convention is to name the metric even if the customer is anonymized. "Throughput up 38%. Scrap rate down 22%. Cycle time per module under nine seconds." Pattern-level facts are credible; vague success language is not. +- Each application links to or references the products it uses, so a reader who arrived via Products can cross-walk to Applications and back. +- For showcase or demo builds, the functional-vs-demo line: pattern-level facts are acceptable but should be labeled as such in the workup; the build should not imply a real anonymized customer when one does not exist. + +## 5. Company, certifications, and engineering posture + +Conventions: +- A Company page with founding year, headquarters, certifications, plain-language about the engineering posture. Not a brand story. +- Certifications baseline at the company level (ISO 9001, ISO 10218, UL, AS9100, IEC 61508, etc.) and at the product level on each detail page. Buyers screen for these; making them findable is a credibility move. +- Made-in-X is named openly if relevant (made in Pittsburgh, designed in Munich, assembled in Taiwan). Country of design and country of manufacture are different and both are surfaceable. +- Founding team, depth of bench, customer count, plant size are facts a buyer's committee asks for; the page should answer them without forcing a sales conversation first. +- The engineering posture (what the company believes about how to build equipment) is a real thing to name. "The factory is the test bench" or "every product runs on our own line before it ships" is the kind of plain claim that does the work brand-essay generic copy fails to do. + +## 6. JSON-LD and structured data + +Conventions: +- Organization schema at the layout level: name, description, url, logo, founding date, address. +- Product schema on each product detail page: name, description, category, brand, manufacturer, sku, identifier. +- Where pricing is quote-based, omit the price field rather than fake one. Structured-data validators flag missing price; the buyer reads quote-based as honest. +- BreadcrumbList on every page beneath the home. + +## 7. Demo / contact flow + +Conventions: +- The demo form is on-site, six fields, no third-party gating. Form mounts the same component everywhere. +- The form does not require a phone number to submit; phone is optional. +- The "what happens next" copy is honest. "An application engineer reaches out within one business day to schedule a working session" is the field's leader posture. "A representative will be in touch shortly" is the field's miss. +- Phone-as-fallback: a visible phone number for buyers who would rather call. +- For procurement-led conversations, a separate "Request a quote" path that asks for the line spec (units per year, integration constraints, certifications required) is conventional; for a single-build demo, the demo form covers both. + +## 8. Trust and conversion signals + +Signals this shape carries: +- Specs visible, in HTML, on every product page. +- Applications named with named metrics. +- Certifications surfaced at the product level. +- Plain company facts (founding, headquarters, plant size, deployment geography). +- Engineering-posture statement that names what the company believes. +- Optional but conventional: a named-publication pull-quote or analyst quote ("X named Volta to the top tier"). Logo walls are the field's miss; one named pull-quote is the convention. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction, real spec tables), honestly demo where it needs a backend (clearly labeled demo request modal, no fake CRM entry, no fake customer logos). + +## 9. Recurring vertical conventions (the synthesis) + +A credible B2B-manufacturer site, against the field of leaders, carries eleven conventions: + +1. A single-subject industrial hero photograph above the fold at a 1280x800 desktop viewport, with a declarative one-line manifesto and the demo CTA. +2. (Density-bearing) Specs surfaced as an HTML table per product, not gated behind a PDF. +3. A product listing page with each product line, its tagline, three to six headline specs, and a product image visible per line. +4. A product detail page with full spec table, certifications at the product level, applied applications, and a demo CTA wired to the product. +5. (Density-bearing) An applications page with named industries and named metrics (cycle time, throughput change, payback period, first-pass yield); no genericized "global leader in X" prose. +6. A Company page with founding year, headquarters, certifications, and an engineering-posture statement that names what the company believes. +7. JSON-LD Organization at the layout level; Product schema on each product detail page (with the primary and secondary image URLs populated under image). +8. (Density-bearing) A demo / contact form that is on-site, six fields, no third-party gating; the demo flow lives within the site's visual contract. +9. Honest "what happens next" copy on the demo path; phone-as-fallback visible. +10. Where pricing is quote-based, no fake dollar figures; the page names the quote-based posture openly. +11. (Density-bearing, new) Real product imagery on the product surface. Each product detail page carries a primary product image plus at least one secondary (a different angle, a close detail of a critical sub-system, or an in-context-on-a-line shot). Product listing cards lead with a product image above the spec table, not specs alone. Premium / industrial / single-subject register, honest-demo where the build is a showcase (no fabricated brand marks or pricing baked into the imagery). Spec tables remain the spine of the page; imagery supports the specs, it does not replace them. + +Threshold and density-bearing items. A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 5, 8, and 11 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a brochure, a lead-gen funnel, or a half-built equipment site instead of a credibility document. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of the density-bearing four will make the build read off-vertical regardless of how many other conventions it hits. Treat the density-bearing items as non-skippable. + +Why convention 11 needed to be added separately. The first b2b-manufacturer build (Volta Robotics) carried conventions 1 through 10 cleanly: spec tables in HTML, named-metric applications, six-field on-site demo form, certifications at the product level, JSON-LD Product schema. It passed the checklist and still read thin against a premium-industrial buyer's eye: one hero image, then spec-only product cards on the lineup and spec-only detail pages. A premium capital-equipment buyer expects to see the machine, multiple angles, in-context on a line. The model flagged it, the human confirmed it. A spec-led build can be checklist-correct and still register as a brochure-with-numbers rather than equipment. Convention 11 closes that gap: the product surface carries real product imagery as a chrome-level convention, not a polish extra; the spec table is the spine and the imagery is the evidence the spine describes a real machine. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Specs are the page. Most competitors gate specs behind a marketing form for a PDF download. A build that surfaces the full spec table in HTML on every product page owns the "we are not afraid of comparison" position. +- Named metrics on the applications page. Most competitors write applications in genericized marketing prose. A build that names cycle time, throughput change, and payback period (even with the customer anonymized) owns the "we ship outcomes, not narratives" position. +- Engineer-facing demo flow. Most competitors route demo requests through marketing-gated long forms with MQL scoring. A build that runs a six-field on-site form and connects to an application engineer (not a sales rep) owns the "first call is a working session" position. +- Certifications at the product level. Most competitors mention certifications on About. A build that carries the applicable certifications on each product detail page owns the "we screen the way your committee does" position. +- Engineering-posture statement. Most competitors write a brand story. A build that names a plain engineering belief ("the factory is the test bench"; "every product runs on our own line before it ships") owns the "we mean what we say" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-conventions-checklist.md b/skills/vertical-site-conventions/references/shape-conventions-checklist.md new file mode 100644 index 0000000..17b57ae --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-conventions-checklist.md @@ -0,0 +1,97 @@ +# Vertical Site Conventions Checklist + +Run this checklist as the composition pre-ship review. It mirrors the seven dimensions `competitor-experience-audit` measures, on the build side. Mark each item present, absent for a stated reason, or routed elsewhere (with a link). + +Three or more absences across the seven dimensions means the build is off-vertical and needs composition work, not a polish pass. + +--- + +## 1. Primary-task prominence + +- [ ] The vertical's primary task is named (from the experience bar or per-shape reference). +- [ ] The primary task is the largest, earliest interactive element in the hero. +- [ ] No competing CTA is louder than the primary task in the hero. +- [ ] The primary task is reachable without scroll on the device class the vertical's visitors use. +- [ ] A compact version of the primary task is sticky to the chrome on scroll (for commercial pages). +- [ ] If the primary task is not the hero, the compromise is documented and the closest equivalent is surfaced. + +## 2. Layout register and density + +- [ ] The vertical's register is named (storefront-dense, editorial-calm, marketing-airy, image-led). +- [ ] The module count above the fold is decided deliberately, not by default, and matches the field's content-per-viewport. +- [ ] The visual register (color, type, aesthetic) is routed to `creative-direction` and `design-standards`, not redefined here. +- [ ] The page does not default to a generic SaaS-airy layout when the field uses a denser register. + +## 3. Merchandising and category surface + +- [ ] The number of category, collection, or entry-point modules above the fold matches the field. +- [ ] The depth signaling pattern is chosen and committed to (mega-menu, grid, faceted side rail, breadcrumb hierarchy). Not stacked. +- [ ] Flat or hierarchical category presentation matches the vertical. +- [ ] Category presentation style (icon, image, text, hybrid) matches the field. +- [ ] The nav tree structural modeling is routed to `information-architecture`, not redefined here. + +## 4. Navigation and search paths + +- [ ] The paths the field offers are inventoried (by category, brand, attribute, vehicle, location, occasion, audience). +- [ ] Each path is scored primary, secondary, or absent against the vertical. +- [ ] Primary paths land in the hero or primary nav; secondary paths land in chrome or below the fold. +- [ ] Search input prominence matches the vertical (header-primary, secondary side-rail, or absent). +- [ ] Paths the field does not use are not surfaced (do not invent paths the vertical does not carry). + +## 5. Brand register and conviction + +- [ ] The brand register is set by `creative-direction` and `brand-archetype-system`, not by this skill. +- [ ] The register carries from the hero into the nav, cards, empty states, trust signals, and footer. +- [ ] Voice is applied consistently in headings, microcopy, CTAs, and empty states. Empty states do not fall back to generic copy. +- [ ] Imagery posture is consistent across the page (no switch from studio photography to abstract illustration mid-page without a reason). + +## 6. Trust and conversion signals + +- [ ] The vertical's required signals are inventoried from the experience bar or per-shape reference. +- [ ] Each required signal is built into the page where the field places it (reviews near the buying action, service-area in the hero, certifications in the chrome, etc.). +- [ ] For showcase or demo builds, the functional-vs-demo line is honored: real where touchable, honestly demo where it needs a backend (clearly labeled demo modals, no fake payment, no real account creation). + +## 7. The synthesis: recurring vertical conventions + +Pull the conventions from the experience bar's dimension 7 (or the per-shape reference's "recurring conventions" section). For each: + +- [ ] Convention 1: __________________ , [present / absent (reason) / routed to ____] +- [ ] Convention 2: +- [ ] Convention 3: +- [ ] Convention 4: +- [ ] Convention 5: +- [ ] Convention 6: +- [ ] Convention 7: +- [ ] Convention 8: +- [ ] Convention 9: +- [ ] Convention 10: +- [ ] (Add rows as needed for the vertical's full convention list.) + +Density-bearing items. Some conventions are density-bearing: their absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. For the ecommerce-catalog shape, conventions 2 (category surface band above the fold at 1280x800), 9 (a promotional or deal surface near the top), and 10 (an inventory or catalog-depth signal a first-time visitor sees) are the density-bearing trio. Each shape's per-shape reference names its own density-bearing items. + +Mark the density-bearing items explicitly in the list above. Missing any one density-bearing item is sufficient to fail the synthesis on its own, regardless of how many other conventions hit. This rule comes from a real build hitting 6 of 8 conventions in an earlier (pre-density-bearing) form of this reference and still reading off-vertical because the density-bearing items it missed were the load-bearing ones. + +Threshold: a build hitting 8 of 10 (or the equivalent ratio for shapes with a different convention count) is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more conventions, OR any density-bearing item, is off-vertical and needs composition work, not a polish pass. Go back to dimensions 1 through 6. + +--- + +## The wedge + +If the experience bar named a recurring gap across the field, the build can exploit it as positioning. State which gap is being exploited and how the build addresses it. + +- Gap exploited: [from the audit's gaps section] +- How the build addresses it: +- What that buys the build: + +If the build is not exploiting a gap, that is fine; the build hits the experience bar and competes on execution. Say so explicitly. + +--- + +## Hand-off list + +- [ ] `frontend-component-build`: the components the build needs and the states each must support. +- [ ] `design-standards`: the tokens, contrast, and spacing the composition assumes. +- [ ] `creative-direction`: the register and voice the composition carries. +- [ ] `information-architecture`: the nav tree and URL structure the composition expects. + +The hand-off list is what makes this skill's output a real spec for the implementation skills, not a wish list. Each item should be specific enough that the implementation skill can read it and start. diff --git a/skills/vertical-site-conventions/references/shape-directory-marketplace.md b/skills/vertical-site-conventions/references/shape-directory-marketplace.md new file mode 100644 index 0000000..50a1acd --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-directory-marketplace.md @@ -0,0 +1,19 @@ +# Shape: directory-marketplace + +Service-provider directories, home services marketplaces, freelance / contractor matching. The reader arrives wanting to find a provider for a need they can name. + +## Status + +Stub. Fill when the first directory-marketplace demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: describe the need (service, location, urgency) and surface ranked providers. Often a wizard pattern (service picker, then ZIP, then refine). +- Layout register: trust-led and service-led. Photos of providers, ratings, and quoted response time carry the page. +- Merchandising: the provider list is the merchandising. Hero often carries a service-picker plus a band of top categories. +- Paths: by service category primary; by location primary; by provider (named) secondary. +- Brand register: marketplace-neutral or strongly opinionated (premium-curated vs widest-net). Cross-reference `creative-direction`. +- Trust signals: verified, licensed, insured, response time, ratings with review count, dispute resolution promise. +- Synthesis (provisional): service picker as the first interaction, location capture early, provider ratings with substantive review counts, response-time signal, clarity on what is curated vs open. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md b/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md new file mode 100644 index 0000000..fae3e57 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-ecommerce-catalog.md @@ -0,0 +1,119 @@ +# Shape: ecommerce-catalog + +Dense catalog storefronts. Auto-parts, hardware, industrial supply, mass-merchant retail. The reader arrives with a part to find or a category to browse. The build leads with the path that gets them to the part. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (auto-parts, hardware, tooling), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: the path to a part. For verticals where compatibility matters (auto-parts, electronics), this is a fitment / compatibility selector. For undifferentiated catalogs (hardware, office supply), this is a search input. For mass merchants, this is category-entry-grid. + +Build conventions: +- The primary task is the largest, earliest interactive element. Not a sidebar widget; not a modal triggered by a marketing CTA. +- Competing CTAs (newsletter, account, brand pitch) live below the fold or in the chrome. +- The primary task is sticky to the chrome on scroll. A visitor mid-page who realizes the fitment is wrong can change it without scrolling back to the hero. +- For fitment-led verticals: setting the vehicle / compatibility once carries to every subsequent page. The selection is the global context, surfaced visibly. + +## 2. Layout register and density + +Register: storefront-dense. Not editorial; not marketing-airy. The page is a working surface, not a brand brochure. + +Build conventions: +- More than four modules above the fold on desktop is normal for this shape. Two-module heros are off-vertical. +- Above the fold at a 1280x800 desktop viewport (not "the first or second viewport"; the assertion is hard) the page carries: the primary task, the category surface band, AND at least one merchandising or trust signal. A category band that requires any scroll to reach reads as airy and off-vertical for this shape; a real build verifies this against a rendered capture, not in prose. +- Whitespace is functional, not generous. The leaders in this shape are dense; an airy build reads as not-a-real-store. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be utilitarian, premium-utilitarian, or technical; not flowery or expressive. + +## 3. Merchandising and category surface + +Conventions: +- A category surface band sits above the fold at a 1280x800 desktop viewport. Eight to twelve category entry points is typical for a wide catalog; four to six for a focused one. ("First or second viewport" is too loose; a real build hit that and still read airy because the band slipped below the fold.) +- Depth signaling is one of: mega-menu hover (broad catalogs), grid of category cards on the home (narrow catalogs), faceted-search side rail on category pages. Pick one; do not stack. +- Category cards carry an icon, an image, or a tight text-only treatment. Hybrid icon-plus-text reads as catalog; image-only reads as marketing. +- Hierarchical surface (parent plus child categories) is conventional for broad catalogs. Flat surface fits focused catalogs. +- A promotional or deal surface lives near the top: a deal-of-the-week strip, a promo band, a featured-offer row. The field carries it to signal "this is an active store with offers." Its absence reads as brochure-like rather than storefront-like. The promo can be a single strip with one or two offers; it does not have to be a full module. +- An inventory or catalog-depth signal appears somewhere a first-time visitor will see it: a part count, "12,000+ parts in stock," a category-count figure, or a near-equivalent that establishes the catalog has real depth. The field carries it as a credibility move; its absence reads as a thin or demo catalog. The figure can be approximate, can be in the hero, the trust band, or the chrome. +- Featured / promoted collections appear below the category surface, not above; categories carry the navigation load. (The promotional surface above is distinct from featured collections; one is a deal band, the other is a curation grid.) + +## 4. Navigation and search paths + +Paths the shape carries: +- By category: primary. Always present. +- By search: primary. Always present, in the header. +- By brand or manufacturer: secondary to primary for broad catalogs (often a band in the chrome or a top-level page). +- By attribute (price, size, color, condition): primary on category pages via the faceted side rail. +- By vehicle / compatibility / fitment: primary for compatibility-led verticals; absent for undifferentiated catalogs. +- Newsletter, account, cart: chrome-level secondary affordances. + +Build conventions: +- Search input is in the header, not in a side panel. Visible width meaningful (not collapsed to an icon). +- Faceted filtering on the listing page is conventional; flat lists are off-vertical for broad catalogs. +- Sort options (price asc, price desc, name, relevance) are visible on the listing. +- Search and category browse coexist; one is not gated behind the other. + +## 5. Brand register and conviction + +Typical postures: utilitarian, premium-utilitarian, technical, value-led. Cross-reference `creative-direction` and `brand-archetype-system` for the controlled vocabulary; do not invent new register names here. + +Build conventions (consistency, not register choice): +- The register carries into the empty states, the cart, the demo modals, and the trust signals. A premium-utilitarian register that dissolves into generic copy below the fold is a composition failure. +- Voice consistency in headings, microcopy, CTAs, and empty states. +- Product imagery posture is consistent: studio product photography across listing and detail; lifestyle imagery in the hero or category headers, if used at all. + +## 6. Trust and conversion signals + +Signals this shape carries: +- Reviews / ratings: average plus count on listing cards and at the top of the detail page. If reviews are absent, surface an alternative (warranty, return policy, brand reputation). +- Pricing transparency: price visible on the listing card; total cost (price plus shipping plus tax) surfaced before checkout, not after. +- Stock signals: in stock, low stock, lead time, backorder. Surfaced on the listing and detail. +- Fitment / compatibility confirmation: required for fitment-led verticals. The confirmation badge ("confirmed to fit your {vehicle}") on the detail page is conventional. +- Shipping promises: free over $X, same-day, two-day. Surfaced in the chrome or hero. +- Return policy: linked from the cart and the detail page. The exact text is in `terms` or `returns`. +- Brand or store badges: certifications, "X years in business", authorized-dealer, where relevant. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real cart state, real fitment filtering), honestly demo where it needs a backend (clearly labeled demo checkout modal, no fake payment, no real account creation). + +## 7. Recurring vertical conventions (the synthesis) + +A credible ecommerce-catalog storefront, against the field of leaders, carries eleven conventions: + +1. A primary task that owns the hero (fitment, search, or category-grid; not a brand pitch). +2. (Density-bearing) A category surface band above the fold at a 1280x800 desktop viewport, not buried in a menu and not requiring scroll to reach. +3. Working faceted filtering on category pages. +4. A persistent global context indicator if the vertical is fitment-led (the confirmed vehicle, the selected compatibility, the active filter set). +5. Visible price on every listing card, with no "click to reveal". +6. Reviews or an explicit substitute (warranty, return policy) near the buying action. +7. A working cart with real client-side state across pages. +8. A clearly labeled checkout flow (real in production; honestly demo in showcase builds). +9. (Density-bearing) A promotional or deal surface near the top: a deal-of-the-week strip, a promo band, or a featured-offer row. +10. (Density-bearing) An inventory or catalog-depth signal a first-time visitor will see (a part count, an SKU total, a category count, or a near-equivalent). +11. (Density-bearing, new) Section count and merchandising volume at the field's level, not at a token-row level. A credible storefront carries roughly thirteen-plus distinct merchandising surfaces top-to-bottom on the home (desktop and mobile each, mobile typically taller), three SKU rails carrying twelve-plus product cards in total, a multi-card deals grid of four-to-eight distinct deal cards (not a single thin promo strip), a category grid of eight-plus photographic tiles, a four-to-six-cell services and trust band, twenty-five-plus distinct images on the home, and a five-to-seven-column footer. A build that hits conventions 2, 9, and 10 with one four-card rail and a five-tile category band passes the presence-check and still reads thin against the field; the bar is volume, not presence. + +Threshold and density-bearing items. A build hitting 9 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 9, 10, and 11 are the density-bearing ones, the items whose absence makes a checklist-passing build still read airy or brochure-like instead of storefront-dense. A build can miss a nice-to-have (a strong substitute for reviews, for example) and still read as the vertical; missing any of the density-bearing four is the failure mode the auto-parts builds exposed across multiple iterations. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +Why convention 11 needed to be added separately. Before this entry, a build could carry the category band, the promo strip, and the inventory signal (conventions 2, 9, 10) and still read thin, because the prior conventions named which sections, never how many or how full. A category band with five tiles passed convention 2; a promo strip with one offer passed convention 9; a part-count badge passed convention 10. The build read storefront-correct on the checklist and read SaaS-airy in a rendered comparison against the field. Convention 11 closes that gap: the bar is the field's actual volume, observed top-to-bottom on a rendered home page, not a presence-check that any single token instance satisfies. + +--- + +## Capture-path note (audit infrastructure) + +The named field leaders in heavily-defended verticals (auto-parts is one) sit behind CDN/WAF bot-mitigation layers that block Fork A rendered capture even with realistic User-Agent strings. In a render-and-match attempt against the four leading parts retailers, all four were intercepted (Cloudflare, Akamai 403, DataDome interstitial, network-idle timeout) and Fork A returned zero homepage content. A synthesis pass on zero captured content silently falls back to training-knowledge abstraction, which is the exact failure mode this shape was added to defend against. + +The lesson, recorded as audit-infrastructure guidance for this shape: in bot-walled verticals, the realistic capture path is screenshot ingestion (a human takes desktop and mobile screenshots of each leader and drops them at a known path; the audit reads the PNGs with vision and produces the section-and-density target from observed evidence). Render-and-match through Fork A alone is not a reliable capture path for this shape. The audit script's selection of capture path should treat Fork A as the default and fall back to screenshot ingestion when zero or trivial content is returned; absent that fallback, the audit silently degrades to abstraction and the build it informs reads thin. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Fitment-first as the entire navigation pattern. Most catalogs treat fitment as a sidebar widget. A build that makes fitment the primary, persistent, single-source-of-truth navigation owns the "wrong-fit return is impossible" position. +- Pricing transparency to the dollar. Most catalogs hide total cost until checkout. A build that surfaces shipping plus tax on the listing card owns the "no surprises" position. +- Honest stock and lead-time signals. Most catalogs use "low stock" theatrically. A build that names actual lead time owns the "we tell you when it ships, not what we want you to feel" position. +- Real reviews vs review theater. Most catalogs surface 4.7-star aggregates that no one trusts. A build that surfaces verified-buyer reviews with the bad ones visible owns the trust position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-ecommerce-standout.md b/skills/vertical-site-conventions/references/shape-ecommerce-standout.md new file mode 100644 index 0000000..d1d528d --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-ecommerce-standout.md @@ -0,0 +1,19 @@ +# Shape: ecommerce-standout + +Single-product or narrow-line ecommerce where the brand and the object carry the page. Premium boots, designer goods, single-product subscriptions, expressive consumer brands. The reader arrives because of the brand, not because of a category need. + +## Status + +Stub. Fill when the first ecommerce-standout demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: see the product (image-led), see the story (brand-led), buy. Hero often carries large product photography or a brand statement. +- Layout register: expressive or premium-considered. The opposite of a dense catalog; air and image carry the load. +- Merchandising: one product line, surfaced as a few SKUs or one product with options. The product story is the merchandising; spec lists are short. +- Paths: by SKU or by product secondary (the catalog is small); by story / about primary; press or recognition often surfaced; size / fit guides important. +- Brand register: expressive-maximalist or premium-considered. Cross-reference `creative-direction`; this shape is where strong register choices land. +- Trust signals: materials, where-made, founder story, press, reviews focused on quality and longevity, return policy generous and visible. +- Synthesis (provisional): large product photography in the hero, brand story or founding line surfaced early, size / fit / materials guide reachable, press logos if they exist, reviews emphasizing quality and longevity (not quantity), generous and clearly stated return policy. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-hospitality-experience.md b/skills/vertical-site-conventions/references/shape-hospitality-experience.md new file mode 100644 index 0000000..bdf348c --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-hospitality-experience.md @@ -0,0 +1,19 @@ +# Shape: hospitality-experience + +Tours, balloon rides, escape rooms, adventure outfitters, immersive experiences. The reader arrives wanting to understand what the experience is, see real photos, and book. + +## Status + +Stub. Fill when the first hospitality-experience demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: book a date and time. The hero CTA is "book" or "check availability"; secondary is "what to expect" for first-timers. +- Layout register: image-led, atmosphere-heavy. The hero is the experience itself, in photography or video. +- Merchandising: experiences as packages with dates, durations, and prices. What-to-expect content carries the trust load. +- Paths: by experience or package primary; by date / availability primary; private events or group secondary. +- Brand register: expressive, premium-considered, or warm-considered. Often regionally-anchored (place-led brand). +- Trust signals: what-to-expect, what-to-bring, age and accessibility constraints, cancellation policy, weather policy (for outdoor experiences), safety briefing, real customer photos, recent reviews on a trusted platform. +- Synthesis (provisional): book or check-availability in the hero, what-to-expect content surfaced before the booking choice, constraints (age, accessibility, weather) clearly stated, cancellation and weather policies visible, recent real photography and reviews, no stock imagery that does not match the actual experience. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-hospitality-food.md b/skills/vertical-site-conventions/references/shape-hospitality-food.md new file mode 100644 index 0000000..d1b76d1 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-hospitality-food.md @@ -0,0 +1,115 @@ +# Shape: hospitality-food + +Restaurants, cafés, bakeries, food halls, ghost kitchens with a storefront. The reader arrives wanting to know if they want to eat there: what the food is, what it costs, when the place is open, whether they can get a table. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (fine dining, neighborhood restaurant, café, bakery), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: see the menu. The reservation action is the secondary primary task. For walk-in-only restaurants and cafés, the menu and the hours-and-address pair are the primary tasks; for reservation-led restaurants, the menu and the reservation flow share the lead. + +Build conventions: +- The menu is reachable in one click from the home page. A site that buries the menu behind a PDF link, behind a modal, or below the fold without a clear cue is off-vertical. The menu is the page, not a download. +- The reservation action is the largest CTA in the chrome (after the menu link). For walk-in-only shops, the equivalent is "where we are" and "when we open." +- The reservation flow is on-site, not punted to a third-party widget iframe. A widget that breaks the site's visual contract dissolves the room's identity at the moment the visitor is closest to deciding. +- The site's primary task is the same component everywhere. One reservation modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +Register: image-led, atmospheric. Less dense than a catalog; more density than a marketing page; more atmosphere than a service-booking page. The page should feel like the room. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: an edge-to-edge dish or room photograph, the restaurant name and one-line identity, AND the reservation CTA. A hospitality-food hero without a real photograph reads as a marketing template. +- The hero photograph is a single subject (one dish, one corner of the room, one moment of service), not a collage. Tiled grids of every dish lose focus; stock food imagery loses identity; single-subject photography on a confident background is the convention. +- Whitespace is generous and atmospheric. The dish gets to breathe. Catalog-dense layouts are off-vertical for this shape unless the vertical is a fast-casual chain. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be editorial-restrained (fine dining), warm-neighborhood (everyday), industrial-bright (fast-casual), or playful-soft (bakery, café); not corporate-flat. + +## 3. The menu + +Conventions: +- A menu page, not a PDF, with each item carrying a name, a description, and a price visible per item. Hiding prices is off-vertical; it tells the visitor the shop is luxury-pretense rather than confidence. +- Items are grouped by course (starters, mains, sides, desserts, drinks). For tasting menus, the courses are the structure. For diner-style menus, the categories are functional. +- Item descriptions are written, not enumerated. Two or three short sentences per item. Adjective stacks ("savory, hearty, comforting") read as marketing; ingredient-and-method copy ("twenty-four-hour bone broth, brisket, eye round") reads as the kitchen. +- Signature dishes carry a small visible mark (badge, label) so the visitor knows what to order. Hiding the signature inside the list misses the assist. +- Allergen notes are surfaced (peanut, shellfish, gluten) where the kitchen's handling requires it. Generic "ask your server" copy is acceptable but less confident than naming the handling. + +## 4. Chef, provenance, and story + +Conventions: +- A short chef-perspective or chef-partner passage is conventional, on the home page or the about page. Two short paragraphs at most; first-person, ingredient-literate, no marketing register. +- Provenance content (where the ingredients come from, who farms what, who supplies the seafood) carries the hospitality wedge for restaurants whose positioning leans on it. For places where it does not, this is absent. +- Staff bios beyond the chef are absent in fine dining and present in neighborhood restaurants and cafés (named baristas, pastry chefs, line cooks). Match the register of the shop. +- The story is not a brand history; it is a kitchen perspective. Brands tell origin stories; restaurants tell what they care about. + +## 5. Reservations flow + +Conventions: +- The form asks: name, party size, date, time, email, allergies and notes. Nothing more at this stage; not an account, not a password, not marketing consent. +- Confirmation is honest. Real production: email confirmation within the hour, sometimes within minutes. Demo build: clearly labeled demo-only, no fake confirmation copy. +- Cancellation, late, and allergy policies are visible on the reservation page, not hidden in terms or buried in confirmation email. +- Walk-in policy is named openly if relevant ("walk-ins welcome at the bar", "no walk-ins"). +- Phone-as-fallback: a visible phone number for visitors who would rather call. Restaurant customers vary; the field's best builds carry both. + +## 6. Address, hours, and visit info + +Conventions: +- Address visible in the chrome on every page. Hours visible at minimum in the footer; the home page should carry "open tonight" or the day's hours above the fold. +- Hours that vary (brunch on Sundays, late on weekends, closed Mondays) are listed line-by-line, not summarized. +- Transit and parking notes belong on a Visit page; they are a trust signal for visitors planning to travel to the restaurant. +- Accessibility notes (step-free entrance, accessible restroom, dress code, noise level) are conventional on the Visit page and rare in the field; their presence reads as care. +- A live map embed is optional; a static "find us" image plus a deep link to the visitor's preferred map app works as well and avoids the embed's accessibility and performance overhead. + +## 7. Press, reviews, and aggregate trust + +Conventions: +- One named-publication pull-quote is the conventional press treatment, not a logo wall. A short, specific quote that names what the restaurant is good at carries more credibility than five logos. +- Aggregate ratings (Google, Yelp, Resy) are present in the chrome or near the reservation action, not in a logo grid. Numbers plus counts; not stars alone. +- Awards (Michelin, James Beard, regional press) are listed plain text in the chrome or on About, not in a badge wall. +- For demo or showcase builds, the functional-vs-demo line: a placeholder press quote is acceptable but should be labeled as such in the workup, not implied to be a real publication. + +## 8. Trust and conversion signals + +Signals this shape carries: +- The dish photograph itself, edge-to-edge, dramatic light, single subject. +- The chef's-perspective passage that does the work of branding. +- Plain-language menu descriptions with prices. +- Open cancellation, late, and allergy policies on the reservation page. +- Visible address and hours. +- Aggregate ratings near the reservation action. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo reservation modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible hospitality-food site, against the field of leaders, carries ten conventions: + +1. An edge-to-edge hero photograph of a single dish, room, or moment, above the fold at a 1280x800 desktop viewport. +2. (Density-bearing) A menu page, not a PDF, with name, description, and price visible per item, reachable in one click from the home. +3. Item descriptions in ingredient-and-method voice, not adjective stacks; signature dishes marked. +4. A reservation action that is on-site, not a third-party widget iframe, available from the chrome on every page. +5. (Density-bearing) A short chef-perspective or chef-partner passage, first-person, two short paragraphs at most. The story of the kitchen, not a brand history. +6. Address and hours visible above the fold; full hours line-by-line on the home or visit page. +7. JSON-LD Restaurant with hasMenu, servesCuisine, acceptsReservations, openingHoursSpecification, and aggregateRating. +8. Cancellation, late, and allergy policies stated openly on the reservation page. +9. (Density-bearing) One named-publication press pull-quote OR a visible aggregate rating (count plus number), placed near the reservation CTA. Not a logo wall. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +Threshold and density-bearing items. A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 1, 5, and 9 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a template instead of the room. A build can miss a nice-to-have (the phone-as-fallback, for example) and still read as the vertical; missing any of conventions 1, 5, or 9 will make the build read as a marketing page about food rather than a restaurant. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- The menu is the page. Most competitors hide the menu behind a PDF or a modal. A build that surfaces the menu in plain HTML with ingredient-literate descriptions owns the "we know what we cook" position. +- On-site reservations. Most competitors punt to a third-party reservation widget. A build that keeps the reservation flow visually within the site's identity owns the "the room is the experience" position. +- Single-subject photography. Most competitors either tile every dish or use stock food imagery. A build that leads with edge-to-edge single-subject photography on a confident background owns the "this is the dish" position. +- Chef's-perspective voice. Most competitors write in marketing register (adjective stacks, brand voice). A build that writes the menu in the chef's voice (ingredient, method, restraint) owns the "we are not selling you, we are cooking for you" position. +- Provenance literacy. Most competitors gesture vaguely at "local, seasonal." A build that names the farmer, the supplier, the cut, owns the "we know where the food came from" position. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-institution-mission.md b/skills/vertical-site-conventions/references/shape-institution-mission.md new file mode 100644 index 0000000..b5c9e03 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-institution-mission.md @@ -0,0 +1,19 @@ +# Shape: institution-mission + +Nonprofits, museums, foundations, public-interest organizations. The reader arrives wanting to understand what the institution does and decide whether to give, attend, volunteer, or read further. + +## Status + +Stub. Fill when the first institution-mission demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: depends on the moment. Donate during a campaign; visit / attend for an institution with a physical presence; sign up or read for a research or advocacy group. The hero CTA matches the institution's primary ask. +- Layout register: editorial-considered. More text than a catalog, less than a long-form publication. Trust load is heavy; expressive maximalism is rare in this shape. +- Merchandising: the cause or mission is the merchandising. Programs, impact, and recent work carry the page. +- Paths: by program primary; by impact / outcomes primary for established institutions; news / press / blog secondary; financials / 990 secondary but conventional for nonprofits. +- Brand register: institutional, considered, mission-led. Premium-considered for arts and culture; restrained-authoritative for advocacy. +- Trust signals: mission statement, board / leadership, financial transparency (for nonprofits, the 990 or audit), accreditations, named donors or partners, recent impact numbers with sources. +- Synthesis (provisional): mission statement above the fold, a clear primary ask (donate, attend, sign up), program or impact surface, leadership and governance reachable from the chrome, financial transparency linked (for nonprofits), no over-emotive imagery that reads as manipulative. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-inventory-listing.md b/skills/vertical-site-conventions/references/shape-inventory-listing.md new file mode 100644 index 0000000..ca1fa7f --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-inventory-listing.md @@ -0,0 +1,19 @@ +# Shape: inventory-listing + +Used-car lots, real estate, equipment rental, marketplace listings. The reader arrives wanting to filter a finite inventory down to the right item. + +## Status + +Stub. Fill when the first inventory-listing demo is built, or when a `competitor-experience-audit` for an inventory-listing vertical has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: filtered search with high-fidelity facets (price range, location, condition, year, make, model, beds, square feet). Search and faceted filtering are co-primary. +- Layout register: dense, but more grid-led than catalog-led. Each listing carries multiple attributes that need room to read. +- Merchandising: the listing is the merchandising. Hero carries a search-and-filter entry plus a few featured items. +- Paths: search-and-filter primary; saved-search and favorites secondary (account-gated); browse-by-attribute primary on category pages. +- Brand register: transactional, trust-led. Premium-led for high-ticket inventory (real estate, luxury cars). +- Trust signals: verified seller, listing freshness, photos count, condition reports, response time. +- Synthesis (provisional): persistent filter chip row, listing freshness indicators, photo count signal, save-this-listing affordance, contact-the-seller path. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/skills/vertical-site-conventions/references/shape-local-service-booking.md b/skills/vertical-site-conventions/references/shape-local-service-booking.md new file mode 100644 index 0000000..2628de6 --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-local-service-booking.md @@ -0,0 +1,125 @@ +# Shape: local-service-booking + +Barber shops, salons, gyms, BJJ schools, dental practices, repair shops, dog groomers. The reader arrives wanting to book a time, see prices, or confirm the place exists. + +This file is a default set of composition conventions for the shape. When `competitor-experience-audit` has been run for the specific vertical (barbershops, dentists, repair shops), the audit's experience bar overrides these defaults. Use these when no audit has been run, or as a sanity check on an audit's output. + +--- + +## 1. Primary-task prominence + +Primary task: book an appointment. For unbookable services (drop-in only), the primary task is to call or to confirm hours. The booking action is the largest CTA on the page; everything else competes for second place. + +Build conventions: +- The book-now action is in the chrome (persistent on every page) AND in the hero, not one or the other. +- A first-time visitor who arrived to book should reach a booking surface in one click from the home page. A flow that requires "services then pick then book" is one click too many. +- For services where the picked practitioner matters (barber, stylist, trainer, dentist), the booking action surfaces the practitioner choice before the time choice. For services where practitioner does not matter (oil change, dog wash), it does not. +- The booking action is the same component everywhere on the site so a visitor cannot get lost. One booking modal, one form, surfaced from every CTA. + +## 2. Layout register and density + +Register: image-led-warm. Less dense than a catalog; more dense than a marketing page. The page should feel like a room the visitor wants to be in. + +Build conventions: +- Above the fold at a 1280x800 desktop viewport, the page carries: the booking CTA, an interior photograph of the space, AND a trust signal (years, license, review average, or named practitioners). A booking page without a photograph of the room reads as a third-party scheduler iframe, not a shop. +- A hero image of the space (or a close-up of the craft) is conventional and load-bearing. Stock or generic imagery reads as "any salon"; the shop's specific room reads as the shop. +- Whitespace is generous but purposeful. Editorial-airy is off-vertical; the visitor needs to see the menu and book without scrolling far. +- Route color, type, and aesthetic to `creative-direction` and `design-standards`. This shape's register can be warm-classic, considered-premium, institutional-professional (medical, legal), or rugged-craft; not corporate-flat or marketing-flashy. + +## 3. Service menu and pricing + +Conventions: +- A service menu with duration and price visible per item lives above the fold at a 1280x800 desktop viewport, OR is one click from the home page and clearly signposted. Hiding prices behind a phone call is off-vertical for the field's modern bar; it tells the visitor the shop is friction-tolerant. +- Service descriptions are plain language, not marketing. Two sentences max per service. +- Service categories (haircut, shave, beard, package) are grouped, not flat-listed, for shops with more than five services. +- Packages (cut-and-shave, cut-and-color) are surfaced as their own line items with their own price, not as "add $X to the base service". +- For services where duration varies (skin fade vs classic cut), the longer duration is named honestly; the shop blocks the chair for the time the cut takes. + +## 4. Trust block and identity + +Signals this shape carries above the fold: +- Years in business ("Est. 2014", "11 years on Walnut Street"). +- License or certification, where the vertical has one (master barber license, dental board, state cosmetology, ASE certification for repair shops). +- Review average plus count (not just the stars; the count is the credibility). +- Address visible, not buried in a footer-only treatment. +- Hours visible, not buried in a footer-only treatment. A visitor planning a drop-in needs to know if the shop is open right now. +- For practitioner-driven shops: the practitioners' names and faces. Anonymous "our team" copy reads as franchise; named, photographed practitioners read as shop. + +Build conventions: +- The trust block is aggregated, not scattered. Years in one footer line, reviews on a separate widget, hours on a separate page is the field's miss; pulling them into a single above-the-fold block is the field's lever. +- JSON-LD `LocalBusiness` (or the more specific subtype: `HairSalon`, `BarberShop`, `Dentist`, `AutoRepair`) carries address, hours, telephone, and aggregateRating in structured form. Most competitors ship none. + +## 5. Practitioner roster + +Conventions for practitioner-driven shops (barber, stylist, trainer, dentist): +- A roster with faces above the booking CTA is the conversion lever the field leaves on the table. Most competitors gate the practitioner choice inside the booking flow; surfacing it before the booking choice removes a decision point. +- Each practitioner card carries: name, face, years of experience, specialties (one to three short tags). +- Bio length is one or two sentences, plain language. Long bios read as profile pages, not a roster. +- For non-practitioner-driven shops (drop-in repair, walk-in clinic), this section is absent or replaced by a "what makes this shop different" block. + +## 6. Booking flow specifics + +Conventions: +- The booking surface is a modal or a single-page form, not a multi-step wizard. Local-service appointments are not enterprise sales. +- The form asks: name, service, practitioner (if applicable), preferred date, preferred time window, notes. It does not ask for an account, a password, or marketing consent at this stage. +- Confirmation is honest. Real production: SMS or email within the hour. Demo build: clearly labeled demo-only, no fake confirmation copy ("you're booked!" with no booking). +- Cancellation policy, late policy, and payment policy are visible on the booking page, not hidden in terms. +- Phone-as-fallback: a visible phone number for visitors who would rather call. Local-service customers vary in digital comfort; the field's best builds carry both. + +## 7. Navigation paths + +Paths the shape carries: +- Services (menu, prices, durations): primary. +- Book: primary, persistent. +- Visit (address, hours, directions, parking, accessibility): primary. +- About / story / team: secondary. +- Newsletter, account, cart: absent or chrome-level afterthought. Local-service shops are not subscription products. + +Build conventions: +- Hours and address are in the chrome (footer at minimum) on every page. +- Accessibility info (step-free entrance, adjustable chairs, accessible restroom, quieter hours) sits on the Visit page; competitors rarely carry it and it is a real differentiator. + +## 8. Trust and conversion signals + +Signals this shape carries: +- Reviews / ratings: average plus count, surfaced above the fold. A four-and-up rating without a count reads as theater. +- Years in business: visible in the chrome or hero. Local shops earn trust over time and the field rewards saying so. +- License or certification number: visible, on the Visit or About page if not in the chrome. +- Plain-language service descriptions: no upcharge surprises. +- Cancellation and late policies stated openly. Generous grace windows read as confident; harsh ones read as defensive. +- Quieter hours / accessibility / language spoken: trust signals the field rarely carries; presence reads as care. + +For showcase or demo builds, the functional-vs-demo line: real where touchable (real form state, real validation, real interaction), honestly demo where it needs a backend (clearly labeled demo booking modal, no fake confirmation, no fake account creation). + +## 9. Recurring vertical conventions (the synthesis) + +A credible local-service-booking site, against the field of leaders, carries ten conventions: + +1. A book-now action that owns the hero and persists in the chrome on every page. +2. (Density-bearing) An interior or craft photograph of the specific shop above the fold at a 1280x800 desktop viewport, not stock or generic. +3. A service menu with duration and price visible per item, one click from the home page at most. +4. (Density-bearing) A trust block aggregated above the fold: years in business, license or certification, review average plus count. Not scattered across footer and about page. +5. For practitioner-driven shops: a roster with faces and specialties above the booking CTA. +6. Address and hours in the chrome (footer at minimum) on every page. +7. JSON-LD LocalBusiness (or vertical-specific subtype) with address, hours, telephone, and aggregateRating. +8. A booking flow that is a single-page form or modal, not a multi-step wizard; asks for name, service, time, and nothing more at this stage. +9. (Density-bearing) A cancellation, late, and payment policy stated openly on the booking page, not hidden in terms. +10. A phone-as-fallback path: a visible phone number for visitors who would rather call. + +Threshold and density-bearing items. A build hitting 8 or more of these is at the experience bar for the shape; the wedge is what the build does beyond that. A build missing 3 or more is off-vertical and needs composition work, not a polish pass. + +Conventions 2, 4, and 9 are the density-bearing ones, the items whose absence makes a checklist-passing build still read as a third-party scheduler iframe or a franchise template instead of a specific shop with a specific room. A build can miss a nice-to-have (the practitioner roster for a drop-in shop, for example) and still read as the vertical; missing any of conventions 2, 4, or 9 makes the build read as anyone's shop. Treat the density-bearing items as non-skippable: if any one is missing, the build will read off-vertical regardless of how many other conventions it hits. + +--- + +## Common positioning wedges in this shape + +From the gaps the audited fields tend to share: + +- Booking-first composition. Most competitors bury the booking action below the fold or behind a third-party scheduler iframe that breaks the visual contract. A build that makes the booking action the largest element on every page, with the shop's identity intact, owns the "we want you to book" position. +- Roster-before-booking. Most competitors gate the practitioner choice inside the booking flow. A build that surfaces a small, photographed roster above the booking CTA owns the "you pick the chair, then the time" position. +- Honest service menu. Most competitors hide prices behind a phone call or list services without durations. A build that posts duration and price for every service owns the "no surprises" position. +- Specific-room photography. Most competitors use stock or generic salon imagery. A build that leads with the shop's actual room owns the "this is the place" position. +- Aggregated trust above the fold. Most competitors scatter the trust signals (years, license, reviews) across the chrome and about page. A build that pulls them into a single above-the-fold block owns the "we are real, we are local, we are licensed" position before the visitor scrolls. + +Pick one wedge per build. Two wedges dilute the positioning; zero wedges hits the bar without a reason to remember. diff --git a/skills/vertical-site-conventions/references/shape-subscription-app.md b/skills/vertical-site-conventions/references/shape-subscription-app.md new file mode 100644 index 0000000..2e3919a --- /dev/null +++ b/skills/vertical-site-conventions/references/shape-subscription-app.md @@ -0,0 +1,19 @@ +# Shape: subscription-app + +Weather apps, productivity tools, news readers, fitness trackers, language learning. The reader arrives wanting to understand the app and decide whether to install or subscribe. + +## Status + +Stub. Fill when the first subscription-app demo is built, or when a `competitor-experience-audit` for one has produced an experience bar. + +## Provisional conventions (until filled from a real audit) + +- Primary task: install (App Store / Play Store buttons) or start trial. The download or trial CTA is the hero. +- Layout register: marketing-led with strong product imagery (device frames, screen captures). Editorial-airy is common. +- Merchandising: features as a vertical scroll of capability sections; not a catalog grid. +- Paths: by feature primary (scroll); pricing secondary (navigable but not first); blog / support tertiary. +- Brand register: wide range. Consumer apps lean expressive or playful; productivity leans considered or technical. +- Trust signals: App Store rating, install count, press logos, customer testimonials, screenshots that read as the actual product. +- Synthesis (provisional): install CTAs (real store buttons) in the hero and chrome, feature-by-feature scroll with real product imagery, pricing surfaced clearly with the free / paid line drawn, App Store rating and review count surfaced, no fake screenshots. + +Until this shape is built into a demo, treat the above as observation defaults to verify against an audit, not as ship-ready conventions. diff --git a/tools/check_workflow_drift.py b/tools/check_workflow_drift.py new file mode 100644 index 0000000..3d1d366 --- /dev/null +++ b/tools/check_workflow_drift.py @@ -0,0 +1,84 @@ +#!/usr/bin/env python3 +"""Drift check: every skill slug a workflow binds must exist in SKILLS.lock. + +The authoring contract binds skills by SLUG on each phase's `Skills:` line +(the Run block then invokes those same slugs in prose). This check reads those +lines, extracts the bound slugs, and asserts each is a real skill in +SKILLS.lock. It is the operate-time twin of the catalog's authoring-time +verification: a workflow that names a skill the catalog does not have would +silently fail to run, so the reference is caught here instead. + +Two bare words appear on `Skills:` lines as authoring markers rather than +slugs: `none` (a phase that is deliberately a human judgment stop) and +`routing` (a phase that routes to other workflows). They are listed explicitly +so a genuine typo is still caught rather than waved through. + +Usage: + python tools/check_workflow_drift.py # exit 1 on any unknown slug +""" +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +WORKFLOWS_DIR = ROOT / "workflows" +LOCK_PATH = ROOT / "SKILLS.lock" + +SKILLS_LINE = re.compile(r"^Skills:\s(.)$", re.MULTILINE) +SLUG_SHAPE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)$") + +# Bare words used on Skills: lines as authoring markers, not skill slugs. +NON_SKILL_MARKERS = {"none", "routing"} + + +def bound_slugs(text: str): + """Yield the skill slugs a workflow file binds on its Skills: lines.""" + for m in SKILLS_LINE.finditer(text): + value = m.group(1) + # The slug list ends at the first parenthetical note or semicolon. + for cut in ("(", ";"): + idx = value.find(cut) + if idx != -1: + value = value[:idx] + for token in value.split(","): + token = token.strip() + if not token or " " in token: + continue + yield token + + +def main() -> int: + if not LOCK_PATH.exists(): + print("SKILLS.lock is missing; cannot run the drift check.") + return 1 + known = set(json.loads(LOCK_PATH.read_text(encoding="utf-8")).keys()) + + checked = set() + unknown = [] + for path in sorted(WORKFLOWS_DIR.glob(".md")): + text = path.read_text(encoding="utf-8") + for token in bound_slugs(text): + if token in NON_SKILL_MARKERS: + continue + if not SLUG_SHAPE.match(token): + unknown.append((path.name, token, "not slug-shaped")) + continue + checked.add(token) + if token not in known: + unknown.append((path.name, token, "not in SKILLS.lock")) + + print(f"Checked {len(checked)} distinct slugs against SKILLS.lock:") + for slug in sorted(checked): + print(f" {slug}") + if unknown: + print("\nDRIFT:") + for name, token, why in unknown: + print(f" {name}: '{token}' {why}") + return 1 + print("\nNo drift: every bound slug exists in SKILLS.lock.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/gen_skills_lock.py b/tools/gen_skills_lock.py new file mode 100644 index 0000000..543198e --- /dev/null +++ b/tools/gen_skills_lock.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Generate or verify SKILLS.lock, a checksum manifest of every skill file. + +Usage: + python tools/gen_skills_lock.py # write SKILLS.lock + python tools/gen_skills_lock.py --check # verify, exit 1 on drift +""" +import hashlib +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +SKILLS_DIR = ROOT / "skills" +LOCK_PATH = ROOT / "SKILLS.lock" + + +def sha256(path: Path) -> str: + h = hashlib.sha256() + h.update(path.read_bytes()) + return h.hexdigest() + + +def build_manifest() -> dict: + manifest = {} + for skill_dir in sorted(p for p in SKILLS_DIR.iterdir() if p.is_dir()): + files = {} + for f in sorted(skill_dir.rglob("")): + if f.is_file(): + rel = f.relative_to(skill_dir).as_posix() + files[rel] = sha256(f) + manifest[skill_dir.name] = files + return manifest + + +def main() -> int: + manifest = build_manifest() + serialized = json.dumps(manifest, indent=2, sort_keys=True) + "\n" + if "--check" in sys.argv: + if not LOCK_PATH.exists(): + print("SKILLS.lock is missing. Run tools/gen_skills_lock.py.") + return 1 + if LOCK_PATH.read_text() != serialized: + print("SKILLS.lock is out of date. Regenerate and commit it.") + return 1 + print("SKILLS.lock is current.") + return 0 + LOCK_PATH.write_text(serialized) + print(f"Wrote SKILLS.lock with {len(manifest)} skills.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/gen_workflows_lock.py b/tools/gen_workflows_lock.py new file mode 100644 index 0000000..122cb20 --- /dev/null +++ b/tools/gen_workflows_lock.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +"""Generate or verify WORKFLOWS.lock, the canonical manifest of workflow files. + +A workflow file is any Markdown file in workflows/ whose opening fenced block +declares both a slug and a status. The tier docs (README.md, CONNECTORS.md, +AGREEMENT-LOG.md) have no such block and are skipped. WORKFLOWS.lock is the +count source for the tier; no count is hand-typed anywhere. + +Usage: + python tools/gen_workflows_lock.py # write WORKFLOWS.lock + python tools/gen_workflows_lock.py --check # verify, exit 1 on drift +""" +import hashlib +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +WORKFLOWS_DIR = ROOT / "workflows" +LOCK_PATH = ROOT / "WORKFLOWS.lock" + +FENCE = re.compile(r"```(.?)```", re.DOTALL) +SLUG = re.compile(r"^slug:\s(\S+)\s$", re.MULTILINE) +STATUS = re.compile(r"^status:\s(\S+)\s$", re.MULTILINE) + + +def sha256(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def parse_workflow(path: Path): + """Return (slug, status) if the file is a workflow, else None.""" + text = path.read_text(encoding="utf-8") + fence = FENCE.search(text) + if not fence: + return None + block = fence.group(1) + slug = SLUG.search(block) + status = STATUS.search(block) + if not slug or not status: + return None + return slug.group(1), status.group(1) + + +def build_manifest() -> dict: + manifest = {} + for path in sorted(WORKFLOWS_DIR.glob(".md")): + parsed = parse_workflow(path) + if parsed is None: + continue + slug, status = parsed + if slug != path.stem: + raise SystemExit( + f"{path.name}: declared slug '{slug}' does not match filename stem " + f"'{path.stem}'. Fix one so the manifest key is unambiguous." + ) + manifest[slug] = { + "file": path.name, + "sha256": sha256(path.read_bytes()), + "status": status, + } + return manifest + + +def main() -> int: + manifest = build_manifest() + serialized = json.dumps(manifest, indent=2, sort_keys=True) + "\n" + # Compare and write as bytes with LF newlines so the lock is byte-stable + # across platforms; text mode on Windows would emit CRLF and break --check + # on a Linux runner. + payload = serialized.encode("utf-8") + if "--check" in sys.argv: + if not LOCK_PATH.exists(): + print("WORKFLOWS.lock is missing. Run tools/gen_workflows_lock.py.") + return 1 + if LOCK_PATH.read_bytes() != payload: + print("WORKFLOWS.lock is out of date. Regenerate and commit it.") + return 1 + print(f"WORKFLOWS.lock is current ({len(manifest)} workflows).") + return 0 + LOCK_PATH.write_bytes(payload) + print(f"Wrote WORKFLOWS.lock with {len(manifest)} workflows.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/scan_skills.py b/tools/scan_skills.py new file mode 100644 index 0000000..c3f3d3d --- /dev/null +++ b/tools/scan_skills.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +"""Heuristic safety scan for skill files. Flags known-risky patterns. + +Usage: + python tools/scan_skills.py [path ...] # scans given files, or all skills + +Prints findings. Exit code is always 0; this is advisory, not a gate. +Promote to a blocking check only after baselining against the full catalog. +""" +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +SKILLS_DIR = ROOT / "skills" +SCRIPT_SUFFIXES = {".py", ".js", ".ts", ".mjs", ".cjs", ".sh", ".bash"} + +SCRIPT_RULES = [ + ("HIGH", "shell or subprocess execution", + re.compile(r"\b(subprocess\|os\.system\|child_process\|spawn\|popen)\b\|" + r"\b(bash\|sh)\s+-c\b")), + ("HIGH", "dynamic code execution", re.compile(r"\b(eval\|exec)\s\(")), + ("HIGH", "environment or secret access", + re.compile(r"os\.environ\|process\.env\|getenv\|id_rsa\|" + r"\.aws/credentials\|ANTHROPIC_API_KEY")), + ("HIGH", "network egress", + re.compile(r"\b(curl\|wget)\b\|requests\.\|urllib\|httpx\|fetch\(\|axios\|" + r"socket\.")), +] +MARKDOWN_RULES = [ + ("MEDIUM", "instruction override / injection phrasing", + re.compile(r"ignore (the \|all )?(previous\|prior\|above)\|" + r"disregard (the \|your )?(instructions\|system)\|exfiltrat", + re.IGNORECASE)), + ("MEDIUM", "references agent memory or config files", + re.compile(r"\b(MEMORY\.md\|SOUL\.md\|CLAUDE\.md)\b\|~/\.claude\|" + r"\.claude/settings", re.IGNORECASE)), + ("LOW", "instructs running shell on activation", + re.compile(r"run (this )?(command\|script\|shell)\|execute the following", + re.IGNORECASE)), +] + + +def targets(args): + if args: + return [Path(a) for a in args if Path(a).is_file()] + return [p for p in SKILLS_DIR.rglob("") if p.is_file()] + + +def scan_file(path): + findings = [] + try: + text = path.read_text(errors="ignore") + except OSError: + return findings + rules = SCRIPT_RULES if path.suffix in SCRIPT_SUFFIXES else MARKDOWN_RULES + for severity, label, pattern in rules: + for m in pattern.finditer(text): + line = text[: m.start()].count("\n") + 1 + findings.append((severity, label, str(path), line)) + return findings + + +def main(): + all_findings = [] + for path in targets(sys.argv[1:]): + all_findings.extend(scan_file(path)) + if not all_findings: + print("No findings.") + return 0 + for severity, label, path, line in sorted(all_findings): + print(f"[{severity}] {path}:{line} {label}") + print(f"\n{len(all_findings)} finding(s). Advisory only. Review in context.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/workflows/AGREEMENT-LOG.md b/workflows/AGREEMENT-LOG.md new file mode 100644 index 0000000..6c97420 --- /dev/null +++ b/workflows/AGREEMENT-LOG.md @@ -0,0 +1,82 @@ +# Agreement log: the schema spec + +The agreement log records what an engine proposed, what its guardrail said, what a human decided, and whether the two agreed. It is the substrate the autonomy doctrine reads: agreement rates per lane earn a gate class its auto-pass, and post-merge regressions revoke it. Autonomy Review reads this log; Incident Response and Lane Demotion reads its `post_merge_outcome`; nothing else mutates it. + +This file is the public schema, generalized from the krine agreement-rate table (migration 0007). The schema is what you get. The instance, its write path, the designation allowlist, and every promotion decision are operated, not published. A reader who implements this schema gets their own log; they do not get ours. + +The agreement log has no connector class, by design. It is operated substrate, not a connectable capability (see CONNECTORS.md). Workflow files that touch it split their done-when conditions into a public gate and an operated-log note, so a stranger running the workflow never depends on infrastructure that is not published. + +## Reference schema (migration 0007, quoted with types) + +The canonical source is the krine agreement-rate migration. Its columns and types, quoted as the reference: + +```sql +create type human_verdict_kind as enum ('merge', 'reject', 'revise'); +create type agreement_kind as enum ('true_pass', 'false_pass', 'true_fail', 'false_fail'); + +create table agreements ( + id uuid primary key default gen_random_uuid(), + project_id uuid references projects(id) on delete cascade, + decision_id text not null, + pr_id text, + lane text not null, + risk_tier text not null, + agent_id text not null, + guardrail_verdict text not null, -- pass or fail + guardrail_confidence numeric, -- graded score; null for deterministic checks + guardrail_checks jsonb, -- which checks fired and their results, plus the proposal pointer + human_verdict human_verdict_kind, -- merge \| reject \| revise; filled after human review + human_reason text, -- the rationale; filled after human review + proposal_to_merge_diff jsonb, -- the proposal-to-merge diff or a pointer; filled after merge + human_review_latency numeric, -- seconds from PR open to human verdict + agreement agreement_kind, -- authored after human review + post_merge_outcome text, -- null at merge, filled later by continuous verification + created_at timestamptz not null default now() +); +``` + +## The public spec + +The public schema carries the fields a reader implementing this tier needs. It converges with the reference above rather than restating it from memory. + +Retained from 0007 as-is: + +\| Field \| Type \| Meaning \| +\|---\|---\|---\| +\| agreement \| enum: true_pass, false_pass, true_fail, false_fail \| the four-way agreement value, authored (see below), never derived from the verdict pair \| +\| lane \| text, not null \| the autonomy lane, e.g. content_roadmap. Per-lane agreement rates are the unit the promotion thresholds apply to; without lane, false-pass-among-passes cannot be computed per lane \| +\| risk_tier \| text \| the risk classification; per-tier thresholds govern promotion, and Tier 3 is permanently excluded \| +\| guardrail_confidence \| numeric, nullable \| the graded score; null for purely deterministic checks. The confidence-cutoff promotion for graded lanes is impossible without it \| +\| guardrail_checks \| jsonb \| which checks fired and their results, and the pointer to the proposal \| +\| human_verdict \| enum: merge, reject, revise (+ waive, added below) \| what happened to the work; a separate axis from agreement, and neither maps from the other \| +\| human_reason \| text \| the rationale, filled after human review; required on revise and waive in this tier \| +\| proposal_to_merge_diff \| jsonb \| the proposal-to-merge diff or a pointer to it; the primary correction signal, and the cold-start recovery reads merged-versus-rejected diffs \| +\| post_merge_outcome \| text \| null at merge, filled later by continuous verification; the second ground truth that demotion and the hardened rung read \| + +Added for this tier: + +\| Field \| Type \| Meaning \| +\|---\|---\|---\| +\| property \| text, designation-guarded \| the showcase property the row belongs to; the publish path enforces the allowlist against it \| +\| workflow_slug \| text \| which workflow produced the proposal \| +\| phase \| text \| which phase of that workflow \| +\| artifact_ref \| text \| pointer to the held artifact the row is about \| +\| waive \| value on human_verdict \| a fourth human verdict alongside merge, reject, revise \| + +## Agreement is authored, never derived + +Agreement is AUTHORED by the human who saw the diff, never derived from the verdict pair. A guardrail pass that a human overrides to revise is a false_pass, and no naive rule produces that mapping; the human writes it. The verdict axis (what happened to the work) and the agreement axis (whether the guardrail was right) are independent, and neither is computed from the other. + +Waive rows carry an authored agreement value plus a required `human_reason`, are excluded from false-pass and false-fail rate computations, and report as their own line in Autonomy Review. Waives stay visible without contaminating the promotion thresholds: a gate waived because it was too strict, and a risk waived because it was knowingly accepted, are both recorded and both kept out of the rates that earn a lane its autonomy. + +## The designation guard + +The publish path refuses any public row whose `property` is not on the maintained showcase allowlist. The guard sits at the write boundary, not only in authoring convention: a row for a non-designated property can never become public output, and its property name can never appear in published material. The allowlist is data, maintained in one place, not a per-row judgment. + +## Open versus operated + +The schema is public. The instance, the write path, the allowlist, and every promotion decision are operated. A reader who implements this schema gets their own log; they do not get ours. Forking the repo yields the gates and this spec, and a reader's own log if they build one; it does not yield RampStack's rows. + +## Storage + +One append-only table in an operational Postgres store. Autonomy Review reads it, Incident Response and Lane Demotion reads `post_merge_outcome`, and nothing else mutates it. Do not add a second table until there is a second writer. diff --git a/workflows/CONNECTORS.md b/workflows/CONNECTORS.md new file mode 100644 index 0000000..b035b50 --- /dev/null +++ b/workflows/CONNECTORS.md @@ -0,0 +1,23 @@ +# Connector capability classes + +Workflows in this tier declare the data access they need as capability CLASSES, never vendors. Your MCP server or integration binds the class; the workflow stays valid when your stack changes. + +Rules, in force across every workflow: +- Read-only is the default. The only write mode is write-held: the action creates a draft or a held change that a human promotes. Publishing, merging, and platform actions are never agent actions under template status. +- Every warehouse capability carries mandatory query bounds: a date range pushed down as a partition filter on every call. A call without bounds is rejected, not silently run. +- Credentials live in environment, never in workflow files, tool output, or error messages. + +\| Class \| Access \| What it serves \| Binding today \| +\|---\|---\|---\|---\| +\| warehouse.query \| read \| the metric warehouse all tracks read \| managed warehouse MCP servers exist for the major warehouses; a thin domain layer encoding your query-correctness rules remains yours to build \| +\| search-performance.read \| read \| search console class data \| the bulk export lands this in the warehouse natively; direct-API access is a thin layer to build \| +\| analytics.read \| read \| product/web analytics events \| an official analytics MCP exists for the common stack; native warehouse export is the reference path \| +\| cms.draft \| write-held \| content pipeline drafts \| your CMS's draft state via its API; no universal server, a small adapter \| +\| repo.change \| write-held \| code and config changes as held draft PRs \| native to the code host \| +\| crawl.read \| read \| live-page fetches for verification gates \| plain HTTPS; no server needed \| +\| experiment.read \| read \| experiment results and assignments \| per-vendor adapter \| +\| revenue.read \| read \| commerce/affiliate revenue events, reconciled against the warehouse \| per-platform adapter \| + +Deliberate absences: there is no index-submit class and no analytics-config-write class. Submitting sitemaps, requesting indexing, and changing analytics settings are state-changing human actions. + +The agreement log has NO connector class, deliberately. It is operated substrate, not a connectable capability: the schema is public (AGREEMENT-LOG.md), the instance and its write path are not. Workflow files that touch it carry a public-gate versus operated-log split in their done-when conditions. diff --git a/workflows/GETTING-STARTED.md b/workflows/GETTING-STARTED.md new file mode 100644 index 0000000..f712dae --- /dev/null +++ b/workflows/GETTING-STARTED.md @@ -0,0 +1,12 @@ +# Running a workflow + +Each workflow in this directory is a runnable procedure, not an essay. The shape is identical across all of them: + +1. Install the catalog once: /plugin marketplace add rampstackco/claude-skills +2. Open the workflow file. Check "when to use / when not to use" first; half the value of the tier is the routing between workflows. +3. Work the prerequisites checklist. If it names a data export, enable it before anything else; the exports named here do not backfill. +4. Run the phases in order. Each phase names the skills it invokes, the input it consumes, a Run block you copy and adapt, the output artifact it produces, and a binary done-when. Phases marked as declared gaps carry their procedure inline; the capability-class line tells you what to substitute if you are off-catalog. +5. Respect the lanes. Divergent phases end at a human decision. Gate phases report and never fix. Nothing in any workflow publishes, merges, or changes platform state on its own. +6. Record what happened. The minimum record is the per-phase artifacts and the human's merge note. The full schema, if you want to implement the operated version, is AGREEMENT-LOG.md. + +Statuses are honest and defined in the README: everything starts as a template, and a workflow is validated only when it has been executed as written on a real property with a linked run record. You can watch that happen in this repo's history. diff --git a/workflows/README.md b/workflows/README.md new file mode 100644 index 0000000..505f48d --- /dev/null +++ b/workflows/README.md @@ -0,0 +1,67 @@ +# Forward-deployed workflows + +Operating workflows for forward-deployed roles running the engines inside a real company's pipeline and data stack. The skills catalog covers building a site once; this tier covers operating a deployed content and growth pipeline continuously. Same authoring contract, extended with role, status, connectors, and autonomy. + +New here? Start with GETTING-STARTED.md. + +Install the catalog these workflows invoke: + +``` +/plugin marketplace add rampstackco/claude-skills +``` + +## Tracks + +Three tracks run the pipeline, and a cross-track pair spans them: + +- Forward-deployed engineer (FDE): stands the pipeline up and keeps its data and deploys honest. +- Forward-deployed marketer (FDM): runs the content and experimentation loop through prove gates. +- Forward-deployed analyst (FDA): owns the numbers, the attribution, and the diagnosis loops. +- Cross-track: Incident Response and Lane Demotion, and Autonomy Review. These operate over every track, one on the event of a regression and one on a periodic cadence. + +## The status ladder + +The ladder is this tier's spine. A workflow's status says what has actually happened to it, not how good the document reads. + +- template: designed, not executed as written. +- validated: executed as written, by the engines, on a showcase-designated property, with a PUBLIC linked run record; manual runs the workflow merely describes do not count. +- hardened: validated plus failure modes documented from real incidents; explicitly the home of demotion and post_merge_outcome regression data, so hardened is earned by surviving events, not by prose. + +Every shipped file below enters at template. Content Pipeline with Prove Gates is the first to flip: Run 1 executed it end to end on a designated property, so its status is validated with the run record linked, the evidence landing before the claim. + +## The merge doctrine + +Checks report and fail, engines propose and stop, a human merges; autonomy is earned per lane under the published doctrine, never asserted. + +## The set + +WORKFLOWS.lock is the canonical manifest and the source for any count. The table is the list. Shipped files link, and with this wave every file is shipped, so no row remains defined and publishing. + +\| Workflow \| Track \| Status \| +\|---\|---\|---\| +\| [Post-Deploy Live Verification](post-deploy-live-verification.md) \| FDE \| template \| +\| [Data Surface Integrity](data-surface-integrity.md) \| FDE \| template \| +\| [Migration with Verification](migration-with-verification.md) \| FDE \| template \| +\| [CI Prove-Gate Wiring](ci-prove-gate-wiring.md) \| FDE \| template \| +\| [Warehouse Data Plane Standup](warehouse-data-plane-standup.md) \| FDE \| template \| +\| [Content Pipeline with Prove Gates](content-pipeline-prove-gates.md) \| FDM \| validated \| +\| [Corpus Integrity and Correction](corpus-integrity-and-correction.md) \| FDM \| template \| +\| [Link Graph and Metadata Parity Audit](link-graph-and-metadata-parity-audit.md) \| FDM \| template \| +\| [Regulated-Content Compliance Gate](regulated-content-compliance-gate.md) \| FDM \| template \| +\| [Experiment Loop with Pre-Registered Gates](experiment-loop-with-pre-registered-gates.md) \| FDM \| template \| +\| [Traffic-Drop Triage](traffic-drop-triage.md) \| FDA \| template \| +\| [Conversion-by-Source Diagnosis](conversion-by-source-diagnosis.md) \| FDA \| template \| +\| [Revenue Tracking Integrity](revenue-tracking-integrity.md) \| FDA \| template \| +\| [Incident Response and Lane Demotion](incident-response-and-lane-demotion.md) \| cross \| template \| +\| [Autonomy Review](autonomy-review.md) \| cross \| template \| + +## Roadmap: named, not launched + +- AI-Surface Visibility Baseline (FDM): fails connector readiness honestly; ships when citation-measurement has real runs. +- Attribution and Outcome Reporting (FDA): fails honest usability at template status; ships when the agreement log has real cross-property rows and post_merge_outcome data. +- Forward-deployed product manager track (FDPM): named to hold the track; not launched, and carried with the same visible not-launched treatment so it cannot read as an empty shipped track. + +## The docs in this tier + +- CONNECTORS.md: the capability classes every workflow declares, the deliberate absences, and the operated-substrate boundary. +- AGREEMENT-LOG.md: the public schema for the agreement log the operated deployment writes, generalized from the canonical agreement-rate table. diff --git a/workflows/autonomy-review.md b/workflows/autonomy-review.md new file mode 100644 index 0000000..3c0ab68 --- /dev/null +++ b/workflows/autonomy-review.md @@ -0,0 +1,156 @@ +# Autonomy Review + +``` +name: Autonomy Review +slug: autonomy-review +tier: forward-deployed (operations) +role: cross +status: template +score: 43 (demand 3, pain 4, differentiation 5, usability 4, connectors 4) +intent: the periodic ceremony over the agreement log: per-lane agreement rates, + which gate classes have earned auto-pass under the tier's thresholds, and + which divergences mean a rubric constant needs tuning +when to use: on a cadence or at a row threshold, once the agreement log holds enough + rows per lane to evaluate +when not to use: executing a revocation when a promoted lane regresses (Incident Response + and Lane Demotion); defining the schema (AGREEMENT-LOG.md is the spec, + this file is its consumer) +gap note: the agreement-log math is RampStack's and has no catalog skill by design; + every analytic phase is inline procedure with no nearest-miss anchor. It + is written to run against any log that implements AGREEMENT-LOG.md. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter # only if an outcome join is needed + - capability: repo.change + access: write-held # only Phase 5's rubric-tuning follow-ups +``` + +The agreement log has no connector class, deliberately. It is operated substrate, not a connectable capability (see CONNECTORS.md): the schema is public (AGREEMENT-LOG.md), the instance and its write path are not. This ceremony reads the operated log and proposes; it never gains a write path to the log, and the promotion it licenses is an operated decision, not a published capability. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- An agreement log implementing the AGREEMENT-LOG.md schema, with enough rows per lane to evaluate; the minimum sample below is a real gate, not a formality. +- The tier's per-lane thresholds and, for graded lanes, the `guardrail_confidence` cutoff, recorded and version-controlled. +- The published merge-authority doctrine (the three layers: access mode, gate auto-pass, merge authority), so a promotion proposal is measured against a written rule. + +## Phases + +### Phase 1: Assemble the window · lane: convergent (Tholo) + +Skills: none; the agreement-log math is a DECLARED GAP with no catalog anchor, procedure inline +Capability class: autonomy.window-assembly (declared catalog gap; no nearest-miss, the log math is RampStack's) +Input: the agreement log for the review window (a log implementing AGREEMENT-LOG.md) +Run: + + Read the agreement log for the window and group rows by lane. Per lane, + compute the four-way agreement rates over true_pass, false_pass, true_fail, + and false_fail, and the row count. Pull the waived rows (human_verdict = + waive) out first: they carry an authored agreement value plus a required + human_reason, are excluded from false-pass and false-fail rate computations, + and report as their own line. Agreement is the authored value on each row, + never derived from the verdict pair; read it, do not recompute it. Present the + per-lane window with the waived line kept separate from the rates, and + evaluate no promotion yet. + +Output artifact: the per-lane window (four-way agreement rates, row counts, the waived line reported separately) +Done when (public gate): every lane in the window has its four-way rates and row count, and waived rows are reported on their own line outside the rates +Operated-layer note: the window is read from the operated log instance; the schema and the four-way agreement values are public (AGREEMENT-LOG.md), and a reader runs this against their own log while RampStack's rows stay operated +Fails look like: folding waived rows into the rates. A waive is a recorded human override, not a guardrail miss, and counting it as a false_pass or false_fail poisons the exact number promotion depends on. + +### Phase 2: Threshold evaluation per lane · lane: gate (Basano) + +Skills: none; the promotion math is a DECLARED GAP with no catalog anchor, procedure inline +Capability class: autonomy.threshold-eval (declared catalog gap; no nearest-miss) +Input: the per-lane window; the tier's per-lane thresholds and the `guardrail_confidence` cutoff +Run: + + For each lane, evaluate three conditions against the written rule and report a + pass or fail on each, changing nothing. One: the false-pass-among-passes rate + is at or below the lane's tier threshold. Two: the lane's row count meets the + minimum sample, because a lane under sample is not evaluable and "insufficient + sample" is a verdict, not a delay. Three, for graded lanes only: the lane's + guardrail_confidence clears the confidence cutoff. A lane earns eligibility + for auto-pass only when every applicable condition holds. Report the per-lane + evaluation with the numbers; this gate reports and decides nothing. + +Output artifact: the per-lane eligibility evaluation (each condition, pass or fail, with the numbers) +Done when: every evaluable lane has a verdict on the threshold, the minimum sample, and (for graded lanes) the confidence cutoff, and under-sample lanes are marked not-evaluable +Fails look like: a ceremony on insufficient sample. A lane declared eligible on five rows has measured noise, and the promotion it licenses regresses on the first real week. + +### Phase 3: The ceiling · lane: gate (Basano) + +Skills: none; the ceiling is doctrine, procedure inline +Capability class: autonomy.ceiling-check (declared catalog gap; no nearest-miss) +Input: the per-lane eligibility evaluation +Run: + + Apply the ceiling before any proposal is written. Tier-3 judgment and boundary + gates (honesty and disclosure lines, the open-versus-operated boundary, + positioning, naming, and the meta-decision of when any lane graduates) are + PERMANENTLY ineligible: they never earn auto-pass and never earn merge + authority, at any status, on any sample. The ceremony that licenses a + graduation is itself a Tier-3 act, so it can never license its own class. + Strike every Tier-3 lane from the eligible set regardless of its rates, and + record that the strike is structural, not a close call. Report the eligible + set after the ceiling. + +Output artifact: the eligible set with every Tier-3 lane struck, and each strike recorded as permanent +Done when: no Tier-3 lane remains in the eligible set, and the graduation meta-decision is marked as itself Tier 3 and ineligible +Fails look like: a lane graduating the ceremony's own class. The moment the review licenses the authority that licenses reviews, the ceiling is gone and the ladder is a pricing page with extra steps. + +### Phase 4: Promotion, demotion, and tuning proposals · lane: divergent (human) + +Skills: none; the decision is deliberately human +Input: the eligible set after the ceiling; the divergences the window surfaced +Run: a person decides. For each eligible lane, the human decides whether to + promote it (grant gate auto-pass, or merge authority, per the doctrine's + layers) with the evidence attached; whether a lane's divergences mean a rubric + constant needs tuning rather than a promotion; and whether any lane should be + demoted. Promotion is licensed here and nowhere else, and it stays revocable. + The decision and its evidence are recorded. +Output artifact: the recorded decisions (promote, tune, demote, or hold) per lane, with evidence +Done when: every eligible lane has a recorded human decision with its evidence, or is explicitly held for more sample +Operated-layer note: in an operated deployment each decision is a Tier-3 act recorded against the lane in the agreement log; the licensing, the log instance, and the promotion are operated, and a reader running this against their own log makes their own decisions (AGREEMENT-LOG.md, open versus operated) +Fails look like: the ceremony drifting into a rubber stamp. If every review promotes and none tunes or demotes, the ceremony has stopped reviewing, and its own agreement rate, its proposals against what the evidence supported, is the number that catches it. + +### Phase 5: Rubric-tuning follow-ups · lane: convergent (Tholo) + +Skills: none; rubric constants are config, the change is procedure inline +Capability class: rubric.tune (write-held) +Input: the tuning decisions from Phase 4 +Run: + + For each tuning decision, prepare the rubric-constant change as a held change + (repo.change): the constant, its old and new value, and the divergence + evidence that motivated it. Nothing auto-applies; a human merges the tuning + the way any other held change is merged. Record the follow-up against the lane + so the next window can tell whether the tuning moved the agreement rate. + +Output artifact: held rubric-tuning changes, each tied to its lane and its motivating divergence +Done when: every Phase 4 tuning decision is a held change with its evidence, and nothing has auto-applied +Fails look like: tuning a constant to make a lane pass. A threshold moved to promote a lane it was blocking is the promotion wearing a disguise, and the divergence evidence is what keeps the tuning honest. + +## Failure modes + +- Ceremonies on insufficient sample: a lane declared eligible on too few rows (Phase 2's failure); insufficient sample is a verdict, not a delay. +- Counting waives in the rates: a recorded human override contaminating the false-pass or false-fail computation (Phase 1's failure). +- The ceremony as rubber stamp: a review that only ever promotes, its own agreement rate reviewable (Phase 4's failure). +- Promotion without the demotion counterpart wired: granting autonomy with no revocation path is the asymmetry the doctrine forbids; Incident Response and Lane Demotion must exist and be armed before any lane graduates. +- Licensing the ceiling's own class: a Tier-3 graduation (Phase 3's failure). +- Tuning to pass: moving a constant to promote a lane it was blocking (Phase 5's failure). + +## Worked example + +Pending. Populates when this ceremony is first run against the agreement log at a row threshold rather than a date; a small number of real rows exist today and the cadence adds more. Status flips to validated when that run record links here. + +## Boundaries + +- Incident Response and Lane Demotion executes the revocation this ceremony's promotions promise: it demotes a lane when a promoted lane's post_merge_outcome regresses, and no lane should graduate here until that counterpart is armed. +- AGREEMENT-LOG.md is the schema this ceremony consumes; that file is the spec and this workflow is its reader, and every column, verdict, and rule this file uses is defined there. diff --git a/workflows/ci-prove-gate-wiring.md b/workflows/ci-prove-gate-wiring.md new file mode 100644 index 0000000..7f9491f --- /dev/null +++ b/workflows/ci-prove-gate-wiring.md @@ -0,0 +1,162 @@ +# CI Prove-Gate Wiring + +``` +name: CI Prove-Gate Wiring +slug: ci-prove-gate-wiring +tier: forward-deployed (operations) +role: fde +status: template +score: 45 (demand 4, pain 4, differentiation 4, usability 4, connectors 5) +intent: install prove skills as required status checks so a failing verdict + blocks a merge the way a failing test does +when to use: a repo where prove checks exist but run advisory, and a merge can pass + without them +when not to use: pre-publish content-claim checking (that is Content Pipeline with Prove + Gates, Phase 3); verifying production after a merge (Post-Deploy Live + Verification); one-off local linting +gap note: the CI-inventory and gate-implementation cores are DECLARED CATALOG + GAPS; those phases are inline procedure with qa-testing and seo-technical + as the nearest anchors. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: repo.change + access: write-held # the wiring and every gate fix land as held PRs + - capability: crawl.read + access: read # only if a gate fetches built output to check it +``` + +Everything this workflow changes lands held: the gate wiring and any fix a gate surfaces are proposed as PRs a human merges. Making the checks required and enabling branch protection are platform actions a person performs (Phase 5). + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A repo with CI you can add status checks to, and the permission to make a check required. +- The prove checks you intend to gate on, already runnable against the repo by hand. +- A build command that produces the artifact production serves; a dev-flag build is a different artifact. +- Branch protection you can configure, or the access to request it. + +## Phases + +### Phase 1: Inventory the pipeline and the gate candidates · lane: convergent (Tholo) + +Skills: qa-testing (nearest anchor; the CI-inventory core is a DECLARED GAP, procedure inline) +Capability class: ci.inventory (declared catalog gap; nearest-miss qa-testing) +Input: the repo, its CI configuration, and the list of prove checks that could become gates +Run: + + Invoke qa-testing's checklist discipline against the current pipeline. + Enumerate: what CI runs today and on which events, which checks are advisory + versus blocking, and which prove checks are run by hand but not wired. For + each candidate gate record what it needs to run (a build artifact, a route + list, a data source) and whether it reads source or built output. Produce the + inventory; propose nothing yet. + +Output artifact: the gate-candidate inventory (each candidate, its inputs, source-versus-built, current advisory or blocking state) +Done when: every candidate has its inputs and current state recorded, including the checks that already block +Fails look like: inventorying the CI config and missing the by-hand checks. The gate a team runs manually and trusts is the one worth wiring, and it never appears in the YAML. + +### Phase 2: Define the gate set and the report contract · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the gate-candidate inventory +Run: + + Propose the gate set: which candidates become required checks, and for each, + the report contract every gate emits, one line per finding: file, check, + expected, found. The contract is report-only by construction, so a gate states + a pass or fail verdict with evidence and changes nothing. Rank candidates by + blocking value against false-positive cost. Present the proposed set and the + contract, and stop for the human. + +Output artifact: the proposed gate set and the per-finding report contract +Done when: a human has approved the gate set and the report contract, or returned them with changes +Operated-layer note: in an operated deployment the proposed set and the human's approval or edits land as an agreement-log row; the divergence between proposed and approved is the calibration signal (see AGREEMENT-LOG.md) +Fails look like: a gate contract that lets a check fix and pass. The moment a gate rewrites the thing it judges, its green means nothing, because it is grading its own homework. + +### Phase 3: Implement the checks against built output · lane: convergent (Tholo) + +Skills: qa-testing, seo-technical (nearest anchors; the gate-implementation core is a DECLARED GAP, procedure inline) +Capability class: ci.gate-implement (declared catalog gap; nearest-miss qa-testing, seo-technical) +Input: the approved gate set; the production-equivalent build command +Run: + + Invoke qa-testing and seo-technical as the check frameworks, and implement + each approved gate to run against the BUILT output with production-equivalent + flags, not the dev server and not source. Each gate emits the Phase 2 report + contract and exits non-zero on any fail. Wire them to run on the pull-request + event against the branch build. Land the wiring as a held PR; merge nothing. + +Output artifact: the gate implementations and their CI wiring, as a held PR that emits the report contract +Done when: each gate runs on the pull-request event against the built output and emits the report contract, in a held PR +Fails look like: asserting against a dev-flag build. A gate that passes on the dev server while the real build serves something else has verified a machine no user visits. + +### Phase 4: Deliberate-failure demonstration · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; procedure inline) +Capability class: ci.gate-prove (declared catalog gap; nearest-miss qa-testing) +Input: the wired gates from Phase 3 +Run: + + Invoke qa-testing's adversarial discipline. For each gate, seed a known-bad + input it must catch (a missing title, a broken internal link, a failing prove + check), run the pipeline, and capture the red: the gate failing and blocking, + with its report contract naming the seeded fault. Then revert the seed and + capture the green. Retain both as the gate's evidence. Report only; the seed + is reverted, never merged. + +Output artifact: per-gate failure evidence (the seeded fault, the captured red with its report, the reverted green) +Done when: every gate has a captured red on its seeded fault and a captured green after revert +Fails look like: shipping a gate no one has seen fail. A gate that has only ever passed is indistinguishable from a gate that checks nothing, and the difference surfaces the day it should have caught something. + +### Phase 5: Install as required checks and branch protection · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the proven gates and their evidence +Run: a person sets the gates as REQUIRED status checks and enables branch + protection so a failing verdict blocks a merge the way a failing test does. + These are platform state changes (repository settings and protection rules), + and they stay human. The person records which gates were made required and on + which branches. +Output artifact: the required-check and branch-protection configuration, recorded against the gate set +Done when: the named gates are required on the protected branches and a failing gate blocks the merge, confirmed by the human +Fails look like: gates that run but are not required. An advisory gate is a suggestion, and a pipeline under deadline merges past suggestions. + +### Phase 6: Drift watch · lane: convergent (Tholo) + +Skills: qa-testing, seo-technical (nearest anchors; procedure inline) +Capability class: ci.gate-drift (declared catalog gap; nearest-miss qa-testing, seo-technical) +Input: the installed gates; the canon each gate encodes (the prove checks, the report contract, the route list) +Run: + + Invoke qa-testing and seo-technical to re-verify each gate when its canon + moves: a gate that encodes a check's rules is re-proven (a Phase 4 rerun) when + that check updates, and a gate reading a route list is re-checked when routes + change. Flag any gate whose canon moved without a re-proof as stale. Land + re-proofs and updates as held changes. + +Output artifact: a drift record per gate (the canon version proven against, the last re-proof) and held updates for any stale gate +Done when: every gate names the canon version it was last proven against, and no gate is enforcing against moved canon unproven +Fails look like: a gate frozen against last quarter's rules. It still passes and still blocks, and it is now enforcing a standard the team no longer holds. + +## Failure modes + +- Gate theater: gates that never fail. The Phase 4 deliberate-failure demonstration is the antidote; a gate with no captured red is not installed. +- Hooks tripping on pre-existing debt: a gate that fails on unrelated legacy files in every PR gets bypassed, and a bypassed gate is a pipeline defect. Scope gates to the staged or changed set. +- Gates that fix instead of report: any gate that mutates what it judges. Report-only is the contract; a self-fixing gate grades its own work. +- Dev-flag assertion: gating against a non-production build, so the gate verifies an artifact production never serves. +- Advisory installation: wiring gates but never making them required (Phase 5's failure); a gate that does not block is documentation. +- Stale canon: gates enforcing rules that have since moved (Phase 6's failure). + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is installing this tier's prove gates as required status checks on an outdoor-sports content property, with the seeded-failure evidence retained per gate. Status flips to validated when that run record links here. + +## Boundaries + +- Post-Deploy Live Verification begins where these gates end: CI runs against the build, that workflow runs against the world, and a green pipeline is not a verified deploy. +- Content Pipeline with Prove Gates owns the content pre-publish gate (its Phase 3); this workflow is the wiring that makes any such gate a required, report-only, non-bypassable check. +- Warehouse Data Plane Standup stands up the bounded data access a data-reading gate would query; a gate needing warehouse access consumes that contract. diff --git a/workflows/content-pipeline-prove-gates.md b/workflows/content-pipeline-prove-gates.md new file mode 100644 index 0000000..534b6bc --- /dev/null +++ b/workflows/content-pipeline-prove-gates.md @@ -0,0 +1,171 @@ +# Content Pipeline with Prove Gates + +``` +name: Content Pipeline with Prove Gates +slug: content-pipeline-prove-gates +tier: forward-deployed (operations) +role: fdm +status: validated +run record: run-records/content-pipeline-prove-gates-run-1.md +score: 49 (demand 5, pain 4, differentiation 5, usability 4, connectors 4) +intent: run a content function as a delivery pipeline where every piece ships + through verification gates and a human merge +when to use: a content property with real traffic stakes, where volume is + agent-produced and trust cannot be +when not to use: one-off content tasks (use the build-time Content Production module); + site builds (use the Website Launch Pipeline); paid-media content + (off-catalog) +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: cms.draft # for CMS-published properties + access: write-held + - capability: repo.change # for git-published properties + access: write-held + - capability: crawl.read + access: read +``` + +One of cms.draft or repo.change is required, matching how the property publishes. Write-held means every draft lands held; nothing in this workflow publishes on its own. The agreement log referenced below is operated substrate with no connector class; see the operated-layer notes. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A demand source the ranking can read: a search-performance export, keyword data, or query logs. If using warehouse exports, enable them before anything else; they do not backfill. +- A publishable target with a draft-and-hold mechanism (CMS drafts or PRs). +- A claims-and-style standard file (STANDARDS.md or equivalent): voice rules, phrase rules, sourcing requirements. +- A route list or sitemap the link checks can resolve against. + +## Phases + +### Phase 1: Rank the backlog from demand · lane: divergent (Krine) + +Skills: seo-keyword, seo-keyword-gap-audit, content-strategy +Capability class: demand.rank (substitute equivalents if off-catalog) +Input: the demand source (search-performance data, keyword exports) plus whatever outcome history exists; the current content inventory +Run: + + Invoke seo-keyword and seo-keyword-gap-audit against the demand data, and + content-strategy against the property's positioning. Rank the candidate + topics with named, auditable criteria (demand volume tiers, intent fit to + the property's priority pages, difficulty). Emit the top items as a ranked + queue with the evidence attached to each: the demand numbers, the intent + read, and why it outranks its neighbors. Do not pick the winner; present + the ranking and stop. + +Output artifact: a ranked brief queue with per-item evidence (the stop package) +Done when: a human selects the go item from the ranking +Operated-layer note: in an operated deployment, the ranking and the human's selection land as an agreement-log row (ranked-choice payload); the divergence between engine order and human pick is the calibration signal +Fails look like: ranking by raw volume alone. Volume without intent fit sends the pipeline chasing traffic the property cannot convert or hold; the criteria exist to be argued with, which requires them to be named + +### Phase 2: Produce the held draft · lane: convergent (Tholo) + +Skills: content-brief-authoring, brand-voice, long-form-content-frameworks, seo-onpage +Capability class: content.draft (write-held) +Input: the selected brief from Phase 1; STANDARDS.md +Run: + + Invoke content-brief-authoring to expand the selected item into a full + brief, then draft against it using long-form-content-frameworks for + structure, brand-voice for voice, and seo-onpage for title, headers, meta, + and internal links. Every factual claim carries its source or derivation + inline. Land the result as a held draft (CMS draft or draft PR). Do not + publish, schedule, or merge. + +Output artifact: a held draft with sources inline, plus the brief it was written against +Done when: the draft exists in held state and nothing has published +Fails look like: the draft publishing directly because the target's draft mechanism was skipped. Write-held is the seam; a pipeline that can publish in this phase is a different and more dangerous machine + +### Phase 3: Pre-publish gate · lane: gate (Basano) + +Skills: editorial-qa, seo-onpage, seo-technical +Capability class: content.pre-publish-gate (substitute equivalents if off-catalog) +Input: the held draft from Phase 2 plus STANDARDS.md +Run: + + Invoke editorial-qa, seo-onpage, and seo-technical against the attached + draft. Using those skills' frameworks, check: every factual claim has a + source or derivation; style and phrase rules in STANDARDS.md pass; title, + meta description, and structured data are present and consistent; every + internal link resolves against the site's route list. Output a pass/fail + verdict per check with evidence. Do not fix anything; report only. + +Output artifact: a prove report (verdict per check, evidence attached), attached to the held draft +Done when (public gate): every check passes, or a failure is waived in writing with a recorded rationale attached to the held draft +Operated-layer note: in an operated deployment, the verdict and any waiver land as an agreement-log row; this is operated substrate, not part of the public package +Fails look like: the gate passing on a claim citing a source that does not contain the number (source-shape checking, not source-presence checking) + +### Phase 4: Human review and merge · lane: divergent (human, structural) + +Skills: none; this phase is the point +Input: the held draft and its prove report +Run: a person reviews the draft the way they would review a contractor's work, reads the prove report, and merges or publishes, or sends it back with notes +Output artifact: the published piece, or a revision note back to Phase 2 +Done when: a human has merged, published, or rejected; the pipeline never advances this phase on its own +Operated-layer note: the human verdict (merge, reject, revise, waive) and, on revise, what changed between proposal and merge, land in the agreement log; the proposal-to-merge diff is the pipeline's primary correction signal +Fails look like: rubber-stamping. If every draft merges untouched for weeks, either the pipeline has earned trust (the operated agreement record would show it) or the review has stopped happening; at template status, assume the second + +### Phase 5: Post-publish live audit · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; the live-verification core is a DECLARED GAP, procedure inline) +Capability class: deploy.live-verify (declared catalog gap; nearest-miss qa-testing) +Input: the production URL of the published piece; the approved draft from Phase 4 +Run: + + Fetch the live production URL (not a preview, not a staging domain, not a + cached copy). Verify: the rendered content matches what was approved at + merge; the canonical URL is self-referencing; title, meta description, + social-share metadata, and structured data are present on the live render + and match the approved values; every internal link on the live page + resolves. If the property fronts a CDN or uses incremental rendering, + confirm the render is current by checking a value known to have changed at + publish. Report verdict per check with the live evidence. + +Output artifact: a live-audit report tied to the production URL +Done when: every check passes against the live render, or the discrepancy is filed as a defect with the live evidence attached +Fails look like: verifying the preview. Merged is not live; a published piece can serve a stale render or the wrong metadata while the preview looks perfect, and only the production URL is ground truth + +### Phase 6: Outcomes and the refresh trigger · lane: convergent (Tholo) + +Skills: seo-rank-tracking, seo-content-audit, content-refresh-system +Capability class: outcomes.read + content.decay-detect +Input: search-performance and warehouse data for the published corpus, on a cadence (weekly or monthly) +Run: + + Invoke seo-rank-tracking against the published pieces' target queries and + seo-content-audit plus content-refresh-system against the corpus on the + set cadence. Flag pieces whose demand, position, or freshness has decayed + past the refresh thresholds. Emit decay flags as candidate items INTO the + Phase 1 ranking, carrying their evidence, where they compete with new + topics on the same criteria. + +Output artifact: outcome records per piece; decay flags entering the Phase 1 queue +Done when: outcomes are queryable for the next ranking cycle and decay candidates are in the queue +Fails look like: refresh running as its own separate pipeline. Decay is a demand source, not a second loop; the moment refreshes bypass the ranking, the pipeline has two front doors and the criteria govern only one of them + +## Failure modes + +- Gate theater: prove reports that always pass. A gate that never fails is either gating nothing or the drafts are being pre-sanitized to it; check by seeding a known-bad claim quarterly and confirming the gate catches it. +- Source-shape blindness: claims citing real sources that do not contain the claimed number (Phase 3's inline failure, the most common one in practice). +- Preview verification: Phase 5 run against anything but the production URL. +- Volume chasing: Phase 1 criteria quietly reduced to demand volume. +- Silent refresh edits: Phase 6 refreshes that change published claims without a visible note; corrections are visible or they are not corrections (see Corpus Integrity and Correction for the correction-note pattern). +- Write-held erosion: any phase acquiring publish or merge authority. At template status the human merge is absolute; graduation exists only under the operated autonomy doctrine, per lane, revocably, and never for judgment-tier gates. + +## Worked example + +Run 1 executed this workflow as written on bowhuntamerica.com: a demand-ranked how-to entered at Phase 1 and exited Phase 5 with a passing live audit, six pre-publish gates with no waiver, and a zero-diff human merge. The full run record, including the vantage finding Phase 5 surfaced and resolved, is linked from the front matter. + +## Boundaries + +- The build-time Content Production module owns one-off content tasks; this workflow owns the continuous loop. Each points here. +- Corpus Integrity and Correction owns claim-truth across the published corpus and the correction-note pattern; Phase 6 hands decayed or wrong claims to it rather than editing silently. +- Post-Deploy Live Verification owns the general deploy-verification procedure; Phase 5 is its content-shaped instance and shares its declared gap. diff --git a/workflows/conversion-by-source-diagnosis.md b/workflows/conversion-by-source-diagnosis.md new file mode 100644 index 0000000..377473f --- /dev/null +++ b/workflows/conversion-by-source-diagnosis.md @@ -0,0 +1,160 @@ +# Conversion-by-Source Diagnosis + +``` +name: Conversion-by-Source Diagnosis +slug: conversion-by-source-diagnosis +tier: forward-deployed (operations) +role: fda +status: template +score: 49 (demand 5, pain 5, differentiation 3, usability 4, connectors 5) +intent: find the conversion divergences worth money in the analytics export, + verify they are behavior rather than measurement, and emit a ranked + hypothesis list a human picks from +when to use: traffic is stable but the outcome number is not, or nobody has looked + at conversion by segment in a quarter +when not to use: traffic itself dropped (Traffic-Drop Triage); running the tests this + workflow proposes (Experiment Loop with Pre-Registered Gates); + verifying the tracking pipeline end to end (Revenue Tracking + Integrity) +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: analytics.read + access: read + - capability: search-performance.read + access: read # intent context for landing pages + - capability: crawl.read + access: read # measurement checks on live pages +``` + +Fully read-only. This workflow diagnoses and ranks; it changes nothing. Its output routes to the Experiment Loop or to held fixes owned elsewhere. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- Conversion events landing in the warehouse or analytics store with source attribution (the native analytics export into the warehouse is the reference setup; enable exports before anything else, they do not backfill). +- A defined conversion event set and, where it exists, a value per event; if value is unknown, the ranking uses volume and says so. +- Enough history for a stable baseline per segment (thin segments produce loud noise; the workflow flags them rather than ranking them). + +## Phases + +### Phase 1: Frame the funnel and the baseline · lane: convergent (Tholo) + +Skills: analytics-strategy, product-analytics-setup +Capability class: conversion.frame (substitute equivalents if off-catalog) +Input: the conversion event definitions; the analytics export in the warehouse +Run: + + Invoke analytics-strategy to state, in writing: which events count as + conversions here, what a source is (source/medium granularity), which + segments matter (landing page template, device, country, intent class), + and the baseline window. Invoke product-analytics-setup to confirm the + events named actually exist in the export with the fields the analysis + needs. Produce the frame document. No analysis yet. + +Output artifact: the frame (events, segments, baseline window, known value per event or the stated absence) +Done when: the frame names every dimension the sweep will cut by, and each named event is confirmed present in the data +Fails look like: framing after looking. A frame written once the divergences are visible quietly becomes a justification for them; the frame comes first so the sweep cannot be steered + +### Phase 2: The divergence sweep · lane: convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; the divergence-detection core is a DECLARED GAP, procedure inline) +Capability class: conversion.divergence-detect (declared catalog gap) +Input: the frame; bounded warehouse queries per the frame's window +Run: + + Compute conversion rate by source x landing template x device against + the baseline, with volume attached to every cell. Surface the divergences + worth money, in three shapes: segments converting well below their peers + at meaningful volume (the fix candidates), sources whose conversion + quality shifted against their own history (the quality drifts), and pages + that earn traffic but not outcomes, cross-read with search-performance + intent data (the rank-without-reward set). Flag thin cells as + not-rankable instead of ranking their noise. Attach the numbers to every + finding. + +Output artifact: the divergence table (finding, segment, magnitude, volume, baseline) +Done when: every finding carries its numbers and thin cells are marked not-rankable +Fails look like: averaging across segments, the same failure that breaks traffic triage. A flat blended conversion rate can hide one template at half its peers; the cuts in the frame exist so the blend cannot + +### Phase 3: Measurement gate · lane: gate (Basano) + +Skills: product-analytics-setup (anchor; procedure inline) +Capability class: measurement.verify (declared catalog gap) +Input: the divergence table; the live pages of affected segments (crawl.read) +Run: + + Before any divergence is treated as behavior, test it as measurement. + Per finding, check: consent-flow differences by source or geography + (a consent-heavy source under-reports conversions, not visitors); + attribution parameters surviving the landing path (redirects and + canonicalization strip params); cross-domain or app boundaries in the + converting path; event firing verified on the live affected templates; + and whether the divergence's start date aligns with a tracking or + consent deploy rather than a demand or content change. Verdict per + finding: BEHAVIOR, MEASUREMENT, or MIXED, with evidence. Report only. + +Output artifact: the divergence table, annotated with measurement verdicts +Done when: every finding carries a verdict; MEASUREMENT findings route to a tracking fix, not an optimization +Fails look like: optimizing a consent artifact. A quarter spent lifting a segment whose conversions were merely unmeasured is the expensive version of this failure, and it is common + +### Phase 4: Hypothesis ranking · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the BEHAVIOR and MIXED findings +Run: + + For each finding, state the hypothesis as mechanism, not aspiration: + what specifically about the page, offer, or match to intent would + explain the gap, and what change would test it. Rank by expected value + where value is known (volume x conversion delta x value per event) and + by volume-weighted delta where it is not, saying which basis each rank + uses. Present the ranked list with evidence. Recommend the top + candidates for testing; decide nothing. Stop for the human. + +Output artifact: the ranked hypothesis list (mechanism, evidence, expected-value basis) +Done when: a human selects which hypotheses proceed +Operated-layer note: in an operated deployment the ranking and the human's selection land as an agreement-log row; hypothesis hit-rate over time, fed back from experiment verdicts, is what calibrates this lane +Fails look like: aspiration hypotheses ("improve the CTA") with no mechanism. A hypothesis that does not say why the gap exists cannot be falsified by a test, and the experiment it produces measures nothing + +### Phase 5: Route the winners · lane: convergent (Tholo) + +Skills: routing; the work lives in the owning workflows +Input: the human-selected hypotheses +Run: + + Testable hypotheses route to the Experiment Loop with Pre-Registered + Gates, carrying their mechanism, expected effect size, and the segment + definition (the loop's pre-registration consumes exactly these). + Findings that are defects rather than hypotheses (a broken form, a + measurement fix) route as held changes to their owners. Record the + routing so experiment verdicts flow back against the original finding. + +Output artifact: routed work items, each tied to its finding and hypothesis +Done when: every selected hypothesis is in the experiment queue or routed as a held fix, with the return path recorded +Fails look like: the diagnosis running its own tests. The moment this workflow ships a variant, pre-registration is retrofitted to a change already believed in, and the experiment gate is theater + +## Failure modes + +- Segment blending (Phase 2's inline failure). +- Measurement artifacts optimized as behavior (Phase 3's inline failure, the expensive one). +- Expected-value theater: invented per-event values lending false precision to the ranking; the basis is stated or the rank is volume-weighted, never silently guessed. +- Thin-cell confidence: ranking noise from segments too small to trust; not-rankable is a verdict, not an apology. +- Mechanism-free hypotheses (Phase 4's inline failure). +- Self-testing (Phase 5's inline failure). + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property with conversion events; the intended first substrate is a designated property whose outbound pick-click events serve as the conversion set. Status flips to validated when that run record links here. + +## Boundaries + +- Experiment Loop with Pre-Registered Gates owns everything from pre-registration through verdict; this workflow supplies its intake and consumes its verdicts as calibration. +- Revenue Tracking Integrity owns the money path end to end on a schedule; Phase 3 here is a per-finding spot check, not that audit. +- Traffic-Drop Triage owns falling traffic; this workflow assumes traffic is roughly stable and the outcome is the question. diff --git a/workflows/corpus-integrity-and-correction.md b/workflows/corpus-integrity-and-correction.md new file mode 100644 index 0000000..1b58f26 --- /dev/null +++ b/workflows/corpus-integrity-and-correction.md @@ -0,0 +1,166 @@ +# Corpus Integrity and Correction + +``` +name: Corpus Integrity and Correction +slug: corpus-integrity-and-correction +tier: forward-deployed (operations) +role: fdm +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: keep a published corpus true over time: detect stale and wrong claims, + enforce derived counters, and correct visibly instead of silently +when to use: any property whose published pages carry claims, numbers, or dated + facts that age; any property where the same fact appears on more + than one page +when not to use: pre-publish checking of a new draft (Content Pipeline, Phase 3); + refreshing a decayed piece for demand reasons (Content Pipeline, + Phase 6); live data feeds like rates or prices (Data Surface + Integrity owns machine-rendered series; this workflow owns + authored claims) +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read # traffic-weights the triage + - capability: cms.draft # or repo.change, matching how the property publishes + access: write-held +``` + +Read-only until Phase 4; corrections land held, a human merges. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A crawlable corpus (the live site) and, for git-published properties, the content source tree. +- The property's canonical data sources for checkable claims (the statistics pages, standards bodies, or datasets its content cites). +- A decision, made once and recorded, of what counts as a visible correction on this property (the correction-note format and where it renders). + +## Phases + +### Phase 1: Claim inventory · lane: convergent (Tholo) + +Skills: seo-content-audit, editorial-qa +Capability class: corpus.claim-extract (substitute equivalents if off-catalog) +Input: the live corpus (crawl.read), plus the content source tree where one exists +Run: + + Invoke seo-content-audit across the corpus and editorial-qa's claim + framework per page. Extract every checkable claim: numbers, dates, + prices, counts, superlatives, cited facts, and every claim that names a + source. Classify each: DERIVED (rendered from a data source), RELAYED + (typed from a source at authoring time), or DATED (true as of a stated + date). Include claims living in titles, meta descriptions, and structured + data; body copy is the smallest part of the register. Emit the claim + register: claim, page(s), class, source if stated, last-verified date + if known. + +Output artifact: the claim register +Done when: the register covers the corpus including metadata surfaces, and every claim carries a class +Fails look like: inventorying body copy only. Claims rot fastest in the surfaces nobody rereads: meta descriptions, schema fields, comparison tables, and footer boilerplate + +### Phase 2: Truth check · lane: gate (Basano) + +Skills: editorial-qa, seo-content-audit (nearest anchors; the derived-counter and stale-claim detection cores are DECLARED GAPS, procedure inline) +Capability class: corpus.truth-check (declared catalog gap; nearest-miss editorial-qa) +Input: the claim register; the property's canonical sources +Run: + + For every RELAYED and DATED claim: check the source still exists, still + says what the page says, and whether the value has changed or the series + has been discontinued. For every count or total that a canonical source + could supply (a catalog size, an item count, an integration count): flag + any hand-typed literal as a defect regardless of whether it is currently + correct, because a correct literal is one release away from a wrong one. + For every fact appearing on more than one page: check the surfaces agree, + and flag any fact with two values or two sources as a defect even when + one of them is right. Output the discrepancy report with severity: + WRONG-NOW, STALE-BUT-WAS-RIGHT, HAND-TYPED-DERIVABLE, TWO-SURFACE-SPLIT, + UNVERIFIABLE (source gone). Verdict per claim, evidence attached. Do not + fix anything; report only. + +Output artifact: the discrepancy report +Done when: every register entry has a verdict, including the clean ones +Fails look like: source-presence checking. A claim citing a live source that no longer contains the claimed value passes a lazy check and fails a reader; the check is against the source's current content, not its existence + +### Phase 3: Triage and the correction plan · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the discrepancy report; search-performance data for the affected pages +Run: + + Rank the defects by reader harm: traffic-weight the affected pages + (search-performance.read), weight claims readers act on (money, safety, + how-to steps) above color, and mark each defect's correction class: + SILENT-SAFE (typos, formatting, broken links) or VISIBLE-CORRECTION + (any claim a reader may have relied on). Present the ranked plan and + stop for the human. + +Output artifact: a ranked correction plan with per-item correction class +Done when: a human approves the plan, including the correction classes +Operated-layer note: in an operated deployment the ranking and the human's approval or reordering land as an agreement-log row +Fails look like: severity by ease of fix. The cheap fixes migrate to the top because they close fast; the ranking's job is to hold reader harm above operator convenience + +### Phase 4: Corrections as held changes · lane: convergent (Tholo) + +Skills: editorial-qa, brand-voice +Capability class: content.correct (write-held) +Input: the approved plan; the property's correction-note format +Run: + + For each VISIBLE-CORRECTION item: fix the claim at its SOURCE (if the + value should derive, wire the derivation rather than retyping the number; + if the fact appears on several pages, fix the one source of truth and the + copies with it), and add the correction note in the property's format, + stating what was wrong, what it now says, and when it was corrected. + Original publish dates stay untouched. Removed claims are noted as + removed, not vanished. SILENT-SAFE items fix without notes. Everything + lands held: CMS drafts or a draft change, never a direct publish. + +Output artifact: held corrections, each tied to its plan item; correction notes in place +Done when: every approved item has a held change and nothing has published +Fails look like: silent edits to relied-upon claims. A correction a reader cannot see is indistinguishable from hoping nobody noticed, and on the day someone diffs the archive, it reads exactly that way + +### Phase 5: Verify live and install the guard · lane: gate (Basano) + +Skills: qa-testing (nearest anchor; live verification shares the deploy.live-verify DECLARED GAP) +Input: the production URLs of corrected pages, post-merge +Run: + + After the human merges: fetch each corrected page's production URL and + verify the correction renders, the note renders where the format says it + should, and the corrected value matches the source. Then install the + guard: the Phase 1-2 pass recurs on a set cadence (quarterly fits most + corpora), and the property's authoring rule is recorded: every new + published number is derived or explicitly inventoried at publish time, + which is what keeps the next pass small. + +Output artifact: live verification per correction; the standing cadence and authoring rule, recorded +Done when: every merged correction is verified on its production URL and the cadence is scheduled +Fails look like: counting the fix as done at merge. Merged is not live; a correction that renders on the preview and not on production has corrected nothing + +## Failure modes + +- Silent edits (Phase 4's inline failure, and the workflow's reason to exist). +- Fixing copies instead of sources: retyping the right number on four pages plants the next two-surface split. +- Source-presence checking (Phase 2's inline failure). +- Severity by ease (Phase 3's inline failure). +- Metadata blindness: claims in meta descriptions, schema, and OG fields skipping the register. +- One-shot integrity: running this once and never installing the cadence; a corpus is only as honest as its most recent pass. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property. The pattern generalizes a real count-and-copy reconciliation on rampstack.co (hand-typed counts replaced with derived values, a listed-count mismatch corrected, a paragraph-length meta rebuilt from a derived count); the visible correction-note pattern additionally generalizes production incidents on an unnamed property. Status flips to validated when a run record links here. + +## Boundaries + +- Content Pipeline Phase 6 hands decayed or wrong claims here rather than editing silently; Phase 3 of the pipeline prevents new debt, this workflow retires existing debt. +- Data Surface Integrity owns machine-rendered data series (rates, prices, live stats) and their freshness guards; this workflow owns authored claims about the world. +- Regulated-Content Compliance Gate owns disclosure and claim rules at publish time in regulated verticals; corrections to regulated content route through both. diff --git a/workflows/data-surface-integrity.md b/workflows/data-surface-integrity.md new file mode 100644 index 0000000..80563f8 --- /dev/null +++ b/workflows/data-surface-integrity.md @@ -0,0 +1,162 @@ +# Data Surface Integrity + +``` +name: Data Surface Integrity +slug: data-surface-integrity +tier: forward-deployed (operations) +role: fde +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: keep machine-rendered data series honest: per-series freshness guards, + two-surface consistency from one source, honest degradation, and + discontinued-series retirement +when to use: any property that renders live or periodic data series (rates, prices, + counts, stats) a reader is expected to trust +when not to use: authored claims about the world (Corpus Integrity and Correction); + whether a surface is current at all after a deploy (Post-Deploy Live + Verification) +validation note: gated on a designated data surface existing or the allowlist expanding; + neither designated property renders external data series today +gap note: the freshness-guard and consistency cores are DECLARED CATALOG GAPS with + monitoring-and-alerting and seo-technical as the nearest anchors; those + phases are inline procedure. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only Phase 5's retirement changes +``` + +Read-only until Phase 5; retirement changes land held, a human merges. Nothing in the audit acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The property's machine-rendered data series and the source each renders from (the warehouse tables or feeds behind them). +- The live surfaces that render each series (crawl.read), including metadata and any narration that cites the series. +- The per-series cadence each source actually updates on. +- A place to record the discontinued-series registry and the correction-note format (the same format Corpus Integrity and Correction uses). + +## Phases + +### Phase 1: Series inventory · lane: convergent (Tholo) + +Skills: monitoring-and-alerting (nearest anchor; the series-inventory core is a DECLARED GAP, procedure inline) +Capability class: data.series-inventory (declared catalog gap; nearest-miss monitoring-and-alerting) +Input: the property's data sources; the live surfaces (crawl.read) +Run: + + Invoke monitoring-and-alerting's series discipline. Inventory every + machine-rendered series ONE series at a time: its source, the cadence that + source actually updates on, and every surface that consumes it (tiles, tables, + metadata, and any narration that cites it). Key the inventory by series, never + by dataset, because a dataset holds many series on different cadences. Produce + the per-series inventory; guard nothing yet. + +Output artifact: the per-series inventory (each series: source, real cadence, every consuming surface) +Done when: every machine-rendered series is inventoried by series with its source, cadence, and consuming surfaces, including metadata and narration +Fails look like: inventorying by dataset. A dataset marked fresh can carry one series that froze months ago, and a dataset-level view never sees the frozen series inside it. + +### Phase 2: Guard audit · lane: gate (Basano) + +Skills: monitoring-and-alerting (nearest anchor; the freshness-guard core is a DECLARED GAP, procedure inline) +Capability class: data.freshness-guard (declared catalog gap; nearest-miss monitoring-and-alerting) +Input: the per-series inventory +Run: + + Invoke monitoring-and-alerting's threshold discipline as a gate. Per series, + check three guards and change nothing. Freshness: a per-series staleness + threshold exists and fires when the series exceeds its own cadence, never a + dataset-wide threshold. Discontinued registry: a series that stopped updating + is registered as discontinued, not silently served stale. Honest degradation: + when a series is stale or degraded, the surface renders honestly, showing the + as-of date and suppressing the trend arrows and deltas a frozen value cannot + support. Report a verdict per series per guard with the rendered evidence. + +Output artifact: the guard report (per series: freshness threshold, discontinued registration, honest degradation, each with a verdict) +Done when: every series has a verdict on its per-series freshness threshold, its discontinued status, and its degradation rendering +Fails look like: a trend arrow on a degraded series. An up arrow drawn from a value that stopped updating tells the reader the number is rising when it is only frozen, which is worse than showing nothing. + +### Phase 3: Two-surface consistency · lane: gate (Basano) + +Skills: seo-technical, qa-testing (nearest anchors; the consistency build-test core is a DECLARED GAP, procedure inline) +Capability class: data.two-surface-consistency (declared catalog gap; nearest-miss seo-technical, qa-testing) +Input: the per-series inventory (series rendered on more than one surface) +Run: + + Invoke seo-technical and qa-testing. For any value that appears on two or more + surfaces, prove it renders from ONE source module, and back that proof with a + build test that fails if the two surfaces ever derive the value independently. + Check the caches too: two surfaces reading one module in code can still + diverge when their cache lifetimes differ, so the test covers served output, + not only source. Report consistency per shared value with the build-test + evidence. + +Output artifact: the consistency report (each shared value: single-source proof, the build test, the cache-lifetime check) +Done when: every value on two or more surfaces is proven single-source with a build test, or the divergence is flagged with evidence +Fails look like: one source in code, two lifetimes in cache. Two surfaces importing the same module look consistent in review and serve different numbers in production because one cache outlived the other. + +### Phase 4: Cadence-copy alignment · lane: gate (Basano) + +Skills: editorial-qa, monitoring-and-alerting (nearest anchors; the cadence-claim core is a DECLARED GAP, procedure inline) +Capability class: data.cadence-alignment (declared catalog gap; nearest-miss editorial-qa, monitoring-and-alerting) +Input: the per-series inventory; the surface copy that claims an update frequency +Run: + + Invoke editorial-qa to find the copy and monitoring-and-alerting to check the + mechanism. Wherever a surface states its own update frequency ("updated + daily", "live rates", "refreshed weekly"), verify the series behind it + actually updates on that cadence. A page promising daily data over a series + that updates monthly is a false claim the reader cannot see is false. Report + each cadence claim against its series' real cadence with a verdict. Report + only. + +Output artifact: the cadence-alignment report (each stated frequency, the series' real cadence, a verdict) +Done when: every surface claim about its own update frequency has a verdict against the series' real cadence +Fails look like: trusting the copy. "Updated daily" is a claim like any other, and a series that refreshes monthly behind it is a dated claim that rots the moment the copy ships. + +### Phase 5: Retirement protocol · lane: convergent (Tholo) + +Skills: editorial-qa, brand-voice +Capability class: data.series-retirement (write-held) +Input: the discontinued series from Phase 2; the property's correction-note format +Run: + + Invoke editorial-qa and brand-voice for the retirement, the same correction + discipline Corpus Integrity and Correction uses. For each discontinued series: + remove it from current renders (the tile, the table, the metadata), and add a + visible correction note anywhere the corpus narrates the series, stating that + it is discontinued and as of when. The narration is retired with the tile, not + left behind to describe a number that no longer renders. Everything lands + held; a human merges. + +Output artifact: held retirement changes per discontinued series (removed from renders, correction note on any narration) +Done when: every discontinued series is removed from current renders and its narration carries a visible correction note, all as held changes +Fails look like: retiring the tile but not the narration. The number disappears from the dashboard while a paragraph elsewhere still explains what it means and where it is heading, describing a series that no longer exists. + +## Failure modes + +- Dataset-level guards (Phase 1 and Phase 2's failure): a frozen series hiding inside a fresh dataset. +- Trend arrows on degraded series (Phase 2's failure): an arrow drawn from a value that stopped moving. +- One source in code, two lifetimes in cache (Phase 3's failure): two surfaces diverging past a shared module because their caches expire differently. +- Retiring the tile but not the narration (Phase 5's failure): the render gone, the prose still describing it. +- Cadence copy outrunning the mechanism (Phase 4's failure): a stated update frequency the series never meets. +- Guards written once and never re-run: a series added after the audit renders unguarded, so the guard set is only as complete as its last inventory. + +## Worked example + +Pending. Populates when this workflow is executed as written on a designated property that renders live data series; neither designated property renders external data series today, so it is gated on such a surface existing or the allowlist expanding. The freshness and degradation patterns generalize production incidents on an unnamed property (a series serving a frozen value behind a live trend arrow); that origin informs the guards but is not validation evidence. + +## Boundaries + +- Corpus Integrity and Correction owns authored claims about the world; this workflow owns machine-rendered data series, and Phase 5's retirement uses that workflow's correction-note pattern for any narration of a discontinued series. +- Post-Deploy Live Verification owns whether a surface is current at all after a deploy; this workflow owns whether the series it renders stay fresh, consistent, and honestly degraded between deploys. +- Warehouse Data Plane Standup stands up the bounded warehouse access and the sensing layer this workflow's guards read through. diff --git a/workflows/experiment-loop-with-pre-registered-gates.md b/workflows/experiment-loop-with-pre-registered-gates.md new file mode 100644 index 0000000..946da7a --- /dev/null +++ b/workflows/experiment-loop-with-pre-registered-gates.md @@ -0,0 +1,171 @@ +# Experiment Loop with Pre-Registered Gates + +``` +name: Experiment Loop with Pre-Registered Gates +slug: experiment-loop-with-pre-registered-gates +tier: forward-deployed (operations) +role: fdm +status: template +score: 43 (demand 4, pain 4, differentiation 3, usability 4, connectors 5) +intent: Basano on the test design: the stopping rule, MDE, and sample-size math + pre-registered before any variant ships, the SEO safety of variants gated, + and the verdict computed only against the pre-registered rule +when to use: a mechanism hypothesis worth a controlled test on a property with enough + traffic to power it +when not to use: finding the hypothesis in the first place (Conversion-by-Source Diagnosis); + a defect fix rather than a test (the ordinary held-fix flow) +validation note: gated on adequate traffic on a designated property; it holds at template + until a designated property has the traffic and a mechanism to test +``` + +## Connectors + +``` +connectors: + - capability: experiment.read + access: read + - capability: analytics.read + access: read + - capability: crawl.read + access: read # variant SEO-safety checks on the built variant + - capability: repo.change + access: write-held # the variant and its config land as held changes +``` + +The variant and its config land held; a human allocates traffic and launches. Traffic allocation is never an agent action. The verdict is computed against the pre-registered rule and nothing else. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A hypothesis from Conversion-by-Source Diagnosis (mechanism, expected effect, segment), or an equivalent stated the same way. +- Enough traffic in the target segment to power a test; if the segment cannot reach the sample the math requires, the honest outcome is not to run. +- The experiment platform (experiment.read) and the analytics that will measure the primary metric. +- A person who allocates traffic and launches; the workflow never does. + +## Phases + +### Phase 1: Intake · lane: convergent (Tholo) + +Skills: analytics-strategy +Capability class: experiment.intake (substitute equivalents if off-catalog) +Input: the hypothesis from Conversion-by-Source Diagnosis (mechanism, expected effect, segment) +Run: + + Invoke analytics-strategy to frame the incoming hypothesis as a testable spec: + the mechanism it claims (what about the page or offer would move the metric, + and why), the expected effect size, the primary metric it would move, and the + exact segment. A hypothesis that arrives as an aspiration rather than a + mechanism goes back to Conversion-by-Source Diagnosis; this workflow tests + mechanisms, not hopes. Produce the framed spec. + +Output artifact: the framed experiment spec (mechanism, expected effect size, primary metric, segment) +Done when: the hypothesis is framed as a mechanism with an expected effect size, a primary metric, and a segment, or returned to Conversion-by-Source Diagnosis as too vague to test +Fails look like: testing an aspiration. "Improve the CTA" names no mechanism and predicts no effect, so whatever the test does, nothing is learned; the spec has to say why the gap exists before a test can falsify it. + +### Phase 2: Pre-registration · lane: gate (Basano) + +Skills: experiment-design, experimentation-analytics +Capability class: experiment.pre-registration (substitute equivalents if off-catalog) +Input: the framed experiment spec; the segment's available traffic +Run: + + Invoke experiment-design and experimentation-analytics to pre-register the + test BEFORE anything ships: the stopping rule, the minimum detectable effect, + the sample-size math the MDE and the segment's traffic imply, the primary + metric, and the window. Write them down and freeze them. If the segment cannot + reach the required sample in a reasonable window, the pre-registration verdict + is "insufficient n, do not run", which is a respectable and final outcome, not + a delay. Report the pre-registration, or the not-run verdict, with the math. + +Output artifact: the frozen pre-registration (stopping rule, MDE, sample size, primary metric, window), or the "insufficient n, do not run" verdict with its math +Done when: the test is pre-registered with all five fields frozen, or it is declared underpowered and not run, with the sample-size math shown either way +Fails look like: shipping first and pre-registering after. A stopping rule and a metric written once the variant is believed in are fitted to the hope, and the test becomes a search for a number that agrees with it. + +### Phase 3: Variant SEO-safety gate · lane: gate (Basano) + +Skills: seo-technical +Capability class: experiment.seo-safety (substitute equivalents if off-catalog) +Input: the built variant (crawl.read); the pre-registration +Run: + + Invoke seo-technical against the built variant. Check that the variant is safe + to serve to search: no cloaking risk (the variant does not show crawlers and + users materially different content in a way search treats as deceptive), + canonical consistency across the variant and the control, and no layout-shift + or core-vitals regression the variant introduces. Report a verdict per check + with the evidence. Report only. + +Output artifact: the SEO-safety report (cloaking, canonical consistency, layout-shift, each with a verdict) +Done when: the variant carries a verdict on cloaking risk, canonical consistency, and layout-shift, all clear or the risk flagged +Fails look like: an experiment that wins by getting deindexed. A variant that trims the content search ranked for can lift the on-page metric while the page quietly falls out of the results, and the test would call that a win. + +### Phase 4: Launch as a held config change · lane: divergent (human) + +Skills: none; the launch and the traffic allocation are deliberately human +Input: the pre-registration and the passing SEO-safety report +Run: the variant and its experiment config land as a HELD change (repo.change). + A person allocates traffic and launches the test; traffic allocation is never + an agent action, because it is a live change to what real users see. The human + launches against the frozen pre-registration, allocating exactly the design + the math called for, and records the launch. +Output artifact: the launched experiment, recorded against its pre-registration, with the variant and config as held changes a human merged +Done when: the experiment is launched by a human at the pre-registered allocation, with the config held and merged by a person +Fails look like: an agent turning traffic on. Allocating traffic is a production act on real users, and it stays with a person the same way merging and deploying do. + +### Phase 5: The verdict · lane: gate (Basano) + +Skills: experimentation-analytics +Capability class: experiment.verdict (substitute equivalents if off-catalog) +Input: the running experiment's results; the frozen pre-registration +Run: + + Invoke experimentation-analytics to compute the verdict ONLY against the + pre-registered rule, at the pre-registered point. The stopping rule decides + when the test ends; interim looks are not stopping decisions, and a result + that looks significant early is not a verdict until the pre-registered point. + The primary metric is the one pre-registered, not whichever moved. Report the + verdict (win, loss, or inconclusive) against the pre-registered rule, with the + numbers. Report only. + +Output artifact: the verdict against the pre-registered rule (win, loss, or inconclusive) with the numbers at the pre-registered point +Done when: the verdict is computed at the pre-registered point against the pre-registered primary metric and stopping rule, with the numbers attached +Fails look like: peeking, then stopping on a good look. Checking the test daily and stopping the day it crosses significance turns noise into a false win, because the more often you look, the more often chance alone crosses the line. + +### Phase 6: Closeout · lane: convergent (Tholo) + +Skills: experimentation-analytics +Capability class: experiment.closeout (substitute equivalents if off-catalog) +Input: the verdict; the original hypothesis and its Conversion-by-Source finding +Run: + + Invoke experimentation-analytics to close the loop. Route the verdict and the + hypothesis outcome back to Conversion-by-Source Diagnosis as calibration: a + hypothesis that won, lost, or came back inconclusive updates that workflow's + hit-rate, which is what makes its next ranking better. If a winning variant is + to consolidate into the live page, it re-enters the SEO-safety check on the + consolidated version before it ships through the ordinary held-fix flow; the + experiment never publishes itself. Record the closeout. + +Output artifact: the routed verdict and hypothesis outcome to Conversion-by-Source Diagnosis, and the consolidation path (with its SEO-safety re-check) recorded where a variant won +Done when (public gate): the verdict and hypothesis outcome are recorded and routed to Conversion-by-Source Diagnosis, and any winning variant is queued for the ordinary held-fix flow with an SEO-safety re-check, not published from here +Operated-layer note: in an operated deployment the pre-registration, the verdict, and their agreement land as an agreement-log row; the verdict-versus-pre-registration agreement is what calibrates this lane (AGREEMENT-LOG.md) +Fails look like: shipping the winner without re-checking the consolidated version. A variant proven safe in isolation can regress SEO once it is merged into the real page with the rest of the layout, and the win does not carry a waiver for that. + +## Failure modes + +- Peeking (Phase 5's failure): interim looks becoming stopping decisions, which manufactures false wins. +- Post-hoc metric switching: reporting whichever metric moved instead of the pre-registered primary. +- Retrofitted pre-registration (Phase 2's failure): registering the rule after the variant is believed in. +- Shipping the winner without the SEO-safety re-check on the consolidated version (Phase 6's failure). +- Underpowered tests run anyway: ignoring the "insufficient n, do not run" verdict and running a test that cannot detect the effect; not-rankable is a verdict here too. +- An agent allocating traffic (Phase 4's failure): a production act on real users that stays human. + +## Worked example + +Pending. Populates when this workflow is executed as written on a designated property with adequate traffic to power a test; it holds at template until a designated property has both the traffic and a mechanism hypothesis to run. Status flips to validated when a run record links here. + +## Boundaries + +- Conversion-by-Source Diagnosis supplies this workflow's intake (its ranked hypotheses) and consumes its verdicts as calibration; the two form the diagnose-then-test loop, and neither runs the other's step. +- Revenue Tracking Integrity underwrites the measurement this workflow trusts: a verdict computed over a money path that does not survive redirects or consent is a verdict over noise. +- Content Pipeline with Prove Gates owns the publish path; a winning variant consolidates through the ordinary held-fix flow with an SEO-safety re-check, and the experiment never self-selects into publishing. diff --git a/workflows/incident-response-and-lane-demotion.md b/workflows/incident-response-and-lane-demotion.md new file mode 100644 index 0000000..23c9e59 --- /dev/null +++ b/workflows/incident-response-and-lane-demotion.md @@ -0,0 +1,176 @@ +# Incident Response and Lane Demotion + +``` +name: Incident Response and Lane Demotion +slug: incident-response-and-lane-demotion +tier: forward-deployed (operations) +role: cross +status: template +score: 49 (demand 4, pain 5, differentiation 5, usability 4, connectors 4) +intent: the event-driven counterpart to Autonomy Review: when a promoted lane's + post_merge_outcome regresses, demote the lane to human-gated first, then + roll back, then audit the false-pass row +when to use: a promoted lane shows a post-merge regression, a known suspect rather + than a mystery +when not to use: a traffic drop with no known cause (Traffic-Drop Triage); an ordinary + defect on a lane that was never promoted (the normal held-fix flow) +gap note: the attribution and false-pass-audit cores are DECLARED CATALOG GAPS with + incident-response as the nearest anchor; those phases are inline procedure. + It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: repo.change + access: write-held # the rollback and any fix land as held changes +``` + +The rollback and the fix land held; a human merges them through the now human-gated lane. The demotion itself and the agreement-log rows are operated actions on the operated instance; this workflow never promotes or re-promotes a lane. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A running autonomy program with at least one promoted lane and the agreement log behind it (AGREEMENT-LOG.md); with no promoted lane, Phase 2 routes elsewhere and this workflow does not apply. +- The `post_merge_outcome` signal source: the monitoring and verification outputs that populate it. +- The lane's `post_merge_outcome` budget, the regression threshold that makes a demotion mandatory. +- The rollback mechanism for the lane's changes. + +## Phases + +### Phase 1: Detection intake · lane: convergent (Tholo) + +Skills: incident-response, launch-runbook +Capability class: incident.intake (substitute equivalents if off-catalog) +Input: the `post_merge_outcome` signals for the window; the monitoring and verification outputs +Run: + + Invoke incident-response and launch-runbook to classify the intake. Enumerate + what counts as a lane-attributable regression: the post_merge_outcome signal + classes (a verification failure that recurs on a promoted lane's deploys, a + monitored metric crossing its regression budget) as distinct from ordinary + noise. For each signal, record the lane it points at, the merges in the + window, and the post_merge_outcome evidence. Produce the intake; attribute + nothing to a promoted lane yet. + +Output artifact: the intake record (each signal, its candidate lane, the window's merges, the post_merge_outcome evidence) +Done when: every regression signal in the window is recorded with its candidate lane and its post_merge_outcome evidence +Fails look like: treating every wobble as an incident. A metric breathing inside its normal band is not a regression, and an intake that flags noise trains the team to demote on nothing. + +### Phase 2: Attribution · lane: gate (Basano) + +Skills: incident-response (nearest anchor; the lane-attribution core is a DECLARED GAP, procedure inline) +Capability class: incident.attribution (declared catalog gap; nearest-miss incident-response) +Input: the intake record +Run: + + Invoke incident-response's attribution discipline as a gate. For each signal, + answer one question with evidence: is this regression attributable to a + PROMOTED lane's merge? Read the agreement log for the lane's recent merges and + their proposal_to_merge_diff, and line the regression up against a specific + promoted-lane merge. If the lane was never promoted (gate auto-pass and merge + authority never granted), this workflow does not apply: route a mystery drop + to Traffic-Drop Triage and an ordinary defect to the normal held-fix flow, and + say which. Report attribution per signal: a promoted-lane regression with the + merge named, or routed elsewhere with the destination named. + +Output artifact: the attribution verdict per signal (promoted-lane regression with the merge identified, or routed elsewhere) +Done when: every signal is either attributed to a specific promoted-lane merge with evidence, or routed to Traffic-Drop Triage or the normal defect flow with the destination named +Operated-layer note: the attribution reads the operated agreement log's rows and proposal_to_merge_diff for the lane; the schema is public (AGREEMENT-LOG.md), the instance and its rows are operated +Fails look like: blaming the gate before the evidence lands. Attributing a regression to a promoted lane without lining it up against a specific merge demotes a lane for a coincidence while the real cause keeps running. + +### Phase 3: Demote first · lane: divergent (human) + +Skills: none; the demotion is a deliberate human act +Input: the attribution verdict for a confirmed promoted-lane regression +Run: before any fix is written, a person returns the lane to human-gated. The + lane stops auto-passing and stops holding merge authority at once, so it + cannot merge again while it is being debugged. This is the ordinary first + move, not a punishment: a promoted lane that regressed has lost the evidence + that earned it, and it gets that evidence back the ordinary way, by re-earning + it. Record the demotion and its reason. +Output artifact: the lane returned to human-gated, with the demotion and its reason recorded +Done when: the lane is human-gated and cannot auto-pass or auto-merge, confirmed before any fix is written +Operated-layer note: in an operated deployment the demotion is recorded as an agreement-log action against the lane, with the regression as its reason; the demotion of the operated lane is an operated act (AGREEMENT-LOG.md) +Fails look like: fixing before demoting. While the fix is being written the lane is still promoted and still merging, so the machine that produced the regression keeps producing, and the incident grows a second head. + +### Phase 4: Roll back and fix as held changes · lane: convergent (Tholo) + +Skills: incident-response (nearest anchor; procedure inline) +Capability class: incident.rollback (write-held) +Input: the demoted lane; the attributed merge +Run: + + Invoke incident-response's rollback discipline. Roll back the attributed merge, + or land the corrective fix, as a HELD change (repo.change) a human merges + through the now human-gated lane. Verify the change against the + post_merge_outcome signal that detected the regression: it closes only when + that signal clears. Nothing here re-promotes the lane; the change merges + through the human gate the way every change on this lane now does. + +Output artifact: the held rollback or fix, tied to the attributed merge, with the post_merge_outcome signal it must clear +Done when: the rollback or fix is a held change and the regression signal has cleared against it, with the lane still human-gated +Fails look like: closing the incident on the merge instead of on the signal. The change meant to fix the regression is verified by re-running the post_merge_outcome check that caught it, not by the fact that a PR merged. + +### Phase 5: The false-pass audit · lane: gate (Basano) + +Skills: incident-response (nearest anchor; the false-pass-audit core is a DECLARED GAP, procedure inline) +Capability class: incident.false-pass-audit (declared catalog gap; nearest-miss incident-response) +Input: the agreement log row for the regressed merge; the gate that passed it +Run: + + Invoke incident-response's post-incident discipline as a gate. Find the + agreement-log row where the guardrail passed the merge that regressed: it is a + false_pass, and the audit asks what the gate misses STRUCTURALLY, not who + erred. Name the class of fault the gate could not see, and turn it into a + specific gate improvement (a new check, a tightened threshold) so the same + miss cannot re-promote a lane later. Report the audit with the false_pass row + and the proposed gate improvement. + +Output artifact: the false-pass audit (the false_pass row, the structural gap named, the proposed gate improvement) +Done when (public gate): the structural gap is named and a specific gate improvement is proposed as a held change +Operated-layer note: the audited row is the operated log's false_pass for the regressed merge; the schema and the four-way agreement values are public (AGREEMENT-LOG.md), the row is operated +Fails look like: demotion without the audit. A lane demoted and fixed but never audited leaves the gate that missed the fault unchanged, and the same miss re-promotes the same class of regression next quarter. + +### Phase 6: Re-promotion path · lane: convergent (Tholo) + +Skills: none; the re-promotion rule is doctrine, procedure inline +Capability class: incident.re-promotion (procedure inline) +Input: the demoted lane; the gate improvement from Phase 5 +Run: + + State the re-promotion path and record it; do not walk it here. Re-promotion + is never automatic. The lane re-earns gate auto-pass and merge authority the + ordinary way, under Autonomy Review's thresholds, over a RESET window that + starts after the fix and the gate improvement land, so the rows that regressed + do not count toward the lane's recovery. Record the reset window's start and + the conditions the lane must meet, and hand the lane to Autonomy Review. + +Output artifact: the recorded reset window (its start, the thresholds the lane must re-earn) handed to Autonomy Review +Done when: the reset window is recorded with its start and re-earning conditions, and the lane is handed to Autonomy Review rather than re-promoted here +Fails look like: quietly re-promoting the lane once the fix lands. A lane restored to autonomy without re-earning it under a reset window has learned nothing, and the demotion was theater. + +## Failure modes + +- Fixing before demoting (Phase 3's failure): the lane keeps merging while you debug it. +- Blaming the gate on noise: attributing a regression to a promoted lane before lining it up against a specific merge (Phase 2's failure); attribution rigor comes before demotion. +- Demotion without the false-pass audit (Phase 5's failure): the same miss re-promotes later. +- Automatic or quiet re-promotion (Phase 6's failure): the lane restored without re-earning under a reset window. +- Treating demotion as shameful: demotion is the system working, the ordinary first move, and a tone that makes it an emergency makes teams avoid promoting at all. +- Closing on the merge, not the signal (Phase 4's failure): the fix verified by a merged PR rather than a cleared post_merge_outcome. + +## Worked example + +Pending. Populates when a promoted lane first regresses and this workflow demotes it; no lane is promoted today, so this stays template until the autonomy program has a lane to demote. Status flips to validated when that run record links here. + +## Boundaries + +- Traffic-Drop Triage owns the mystery drop with no known suspect; this workflow owns the regression with a known suspect, a promoted lane's own merge, and Phase 2 routes to that workflow when no promoted lane is attributable. +- Autonomy Review owns promotion; this workflow owns the revocation that promotion promised, and the two are a pair: no lane graduates there until this is armed here. +- AGREEMENT-LOG.md is the schema whose post_merge_outcome this workflow reads and whose false_pass row it audits; that file defines the columns and the four-way agreement values this workflow uses. diff --git a/workflows/link-graph-and-metadata-parity-audit.md b/workflows/link-graph-and-metadata-parity-audit.md new file mode 100644 index 0000000..0f4e33a --- /dev/null +++ b/workflows/link-graph-and-metadata-parity-audit.md @@ -0,0 +1,131 @@ +# Link Graph and Metadata Parity Audit + +``` +name: Link Graph and Metadata Parity Audit +slug: link-graph-and-metadata-parity-audit +tier: forward-deployed (operations) +role: fdm +status: template +score: 45 (demand 5, pain 3, differentiation 3, usability 5, connectors 5) +intent: audit a site's link graph and per-route share metadata: find orphans and + dead ends, and hold every route to unique, self-referencing metadata +when to use: a site large enough that routes get orphaned or inherit the homepage's + metadata by default; a periodic structural pass +when not to use: per-deploy verification of the routes a change touched (Post-Deploy Live + Verification); whether a claim is true (Corpus Integrity and Correction) +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only in Phase 4, and only as held changes +``` + +Read-only until Phase 4; fixes land held, a human merges. Nothing in the audit acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The production site, crawlable, and the route registry or sitemap to reconcile the crawl against. +- The templates behind the routes, for fixes that belong at the template rather than the page. +- The list of money or conversion surfaces the graph is expected to feed. + +## Phases + +### Phase 1: Build the link graph · lane: convergent (Tholo) + +Skills: seo-technical, seo-site-health-audit +Capability class: linkgraph.build (substitute equivalents if off-catalog) +Input: the live site (crawl.read) and the route registry or sitemap +Run: + + Invoke seo-technical and seo-site-health-audit against a crawl of the live + site, reconciled with the route registry or sitemap. Build the directed link + graph: every route a node, every internal link an edge, with each route's + templates and its share metadata (title, description, canonical, OG, Twitter) + attached. Reconcile crawl against registry so that routes which exist but are + unlinked, and links that point at routes which do not exist, are both visible. + Produce the graph; judge nothing yet. + +Output artifact: the link graph (routes, edges, per-route metadata) reconciled against the route registry +Done when: every registry route is a node and every internal link is an edge, with crawl-versus-registry discrepancies marked +Fails look like: crawling the preview. A staging crawl maps a link graph no user traverses, and the orphan on production is the page staging linked fine. + +### Phase 2: Orphan and dead-end detection · lane: gate (Basano) + +Skills: seo-site-health-audit +Capability class: linkgraph.orphan-detect (substitute equivalents if off-catalog) +Input: the link graph +Run: + + Invoke seo-site-health-audit against the graph and flag two classes, fixing + nothing. Orphans: routes with zero inbound internal links, reachable only by + direct URL. Dead ends toward outcomes: routes with zero outbound links to the + money or conversion surfaces they should feed. Weight each by the route's + value (traffic or commercial intent) so the ranking holds business harm above + raw count. Report each with its graph evidence: the node, its inbound and + outbound degree, and the path that is missing. + +Output artifact: the orphan-and-dead-end report (each flagged route, its degrees, the missing path, its weight) +Done when: every route with zero inbound, or zero outbound to an outcome surface, is flagged with evidence, including the clean high-value routes confirmed reachable +Fails look like: counting orphans without weighting them. A thousand orphaned tag pages and one orphaned money page are not the same finding, and an unweighted list buries the one that pays. + +### Phase 3: Metadata parity per route · lane: gate (Basano) + +Skills: seo-onpage, seo-technical +Capability class: metadata.parity (substitute equivalents if off-catalog) +Input: the link graph's per-route metadata +Run: + + Invoke seo-onpage and seo-technical against every route's metadata. Check: + title and description are unique per route, not the homepage's defaults; OG + and Twitter tags are per-route, not the site-wide fallback; the canonical is + self-referencing; and no title template is doubling its suffix (the + "Page \| Site \| Site" class). Verdict per route per check, with the rendered + metadata as evidence. Report only. + +Output artifact: the metadata-parity report (verdict per route per check, rendered metadata attached) +Done when: every route carries a verdict for uniqueness, per-route OG and Twitter, self-canonical, and suffix dedup +Fails look like: checking presence, not uniqueness. Every page carrying the homepage's OG image passes a presence check and fails a reader who sees the same card for forty different links. + +### Phase 4: Triage and held fixes · lane: divergent (Krine) then convergent (Tholo) + +Skills: seo-onpage, seo-technical +Capability class: metadata.correct (write-held) +Input: the orphan-and-dead-end report and the metadata-parity report +Run: + + Invoke seo-onpage and seo-technical to rank the findings by value-weighted + harm and present the plan for a human to approve (the divergent stop). On + approval, use those skills to fix at the TEMPLATE, not the page: a doubled + suffix or a fallback-OG defect is one + template change that clears every route it governs, and a per-page patch + plants the next drift. Orphans are fixed by adding the missing inbound links + at their source. Everything lands held: a draft change, never a direct push. + +Output artifact: a ranked plan, then held fixes at the template level, each tied to its finding +Done when (public gate): a human has approved the plan, and every approved fix is a held change with nothing published +Operated-layer note: in an operated deployment the ranking and the human's approval or reordering land as an agreement-log row (see AGREEMENT-LOG.md) +Fails look like: fixing template symptoms per page. Retyping the right title on forty routes leaves the template that mis-set them in place, and the forty-first route ships wrong next week. + +## Failure modes + +- Presence-not-uniqueness checking (Phase 3's failure): every page sharing the homepage OG passes a presence check. +- Crawling the preview (Phase 1's failure): a link graph no user traverses. +- Per-page template fixes (Phase 4's failure): treating a template defect one route at a time. +- Unweighted orphan lists: a money page and a tag page counted the same. +- Registry-crawl blindness: trusting one source, so a route that exists but is unlinked, or a link to a route that does not exist, never surfaces. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; a full-graph pass on rampstack.co is schedulable as written in the near term. Status flips to validated when that run record links here. + +## Boundaries + +- Corpus Integrity and Correction owns whether a claim is true; this workflow owns whether the structure around it (links, canonicals, share metadata) is sound. +- Post-Deploy Live Verification owns the per-deploy check of the routes a change touched; this is the periodic full-graph pass across every route. +- Content Pipeline with Prove Gates checks a single draft's metadata and links at publish (its Phase 3); this audits the whole graph after the fact. diff --git a/workflows/migration-with-verification.md b/workflows/migration-with-verification.md new file mode 100644 index 0000000..ca91b0c --- /dev/null +++ b/workflows/migration-with-verification.md @@ -0,0 +1,175 @@ +# Migration with Verification + +``` +name: Migration with Verification +slug: migration-with-verification +tier: forward-deployed (operations) +role: fde +status: template +score: 47 (demand 4, pain 5, differentiation 4, usability 4, connectors 4) +intent: migrate a property with the redirect map gated for completeness, old and + new parity proven, cutover staged behind a human, and recovery watched + against baselines pre-registered before the flip +when to use: moving a property to a new domain, platform, or URL structure, where old + URLs carry traffic and rankings worth keeping +when not to use: verifying a single deploy on an unchanged property (Post-Deploy Live + Verification); a traffic drop with no known cause (Traffic-Drop Triage) +validation note: gated on a real migration of a designated property; none is planned, so + it holds at template until such a migration occurs +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read # both the old and the new property + - capability: search-performance.read + access: read # the pre-cutover baselines + - capability: repo.change + access: write-held # the redirect map and any fix land as held changes +``` + +Read-only until the held redirect map and fixes. The cutover itself, the DNS and platform actions, is a human phase; nothing here flips a property. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- Crawl access to both the old property and the new one. +- The complete list of old URLs, from the old sitemap, the crawl, and the search-performance export together, because any one alone misses pages. +- Search-performance history for the old property, to pre-register baselines before cutover. +- The cutover runbook's platform access (DNS, hosting), held by the human who performs it. + +## Phases + +### Phase 1: Inventory and pre-register the baselines · lane: convergent (Tholo) + +Skills: content-migration, seo-technical +Capability class: migration.baseline (substitute equivalents if off-catalog) +Input: the old property (crawl.read), its search-performance history, the new property's planned structure +Run: + + Invoke content-migration to inventory the old property and seo-technical to + read its structure. Build the complete old-URL list as the union of the + sitemap, the crawl, and the search-performance export, because any single + source misses pages. Then PRE-REGISTER the baselines before cutover: the + traffic and ranking levels per key segment, and the recovery metric (which + segment, back to what level, measured over what window) written down now, + while the old property is still live. Produce the inventory and the + pre-registered baseline record. + +Output artifact: the complete old-URL inventory and the pre-registered baseline record (traffic, rankings, the recovery metric), dated before cutover +Done when: every old URL is inventoried from the three sources unioned, and the baselines and recovery metric are recorded before any cutover step +Fails look like: baselines chosen after cutover. A recovery metric written once traffic has moved is fitted to whatever happened and will always find recovery; the baseline means something only if it predates the flip. + +### Phase 2: Redirect-map completeness gate · lane: gate (Basano) + +Skills: content-migration +Capability class: migration.redirect-completeness (substitute equivalents if off-catalog) +Input: the complete old-URL inventory; the new property's URL structure +Run: + + Invoke content-migration against the old-URL inventory. For EVERY old URL, not + a sample, assign one of three dispositions: a 301 to a specific new URL, + gone-with-intent (a 410 or an intentional removal with the reason recorded), + or explicitly dropped with a written rationale. The gate is completeness: an + old URL with no disposition is a fail, and the map is not done until the + uncovered count is zero. Report the map with its coverage and every + disposition's evidence. This gate reports and fixes nothing. + +Output artifact: the redirect map (every old URL, its disposition, the rationale for drops) with a zero-uncovered coverage report +Done when: every old URL in the inventory carries a disposition, the uncovered count is zero, and each drop has a recorded rationale +Fails look like: a sampled map. A redirect map spot-checked instead of completed passes review and drops the long tail, and the long tail is where the accumulated ranking equity quietly lived. + +### Phase 3: Parity audit, old versus new · lane: gate (Basano) + +Skills: seo-technical, seo-onpage +Capability class: migration.parity-audit (substitute equivalents if off-catalog) +Input: the old and new properties (crawl.read); the redirect map +Run: + + Invoke seo-technical and seo-onpage against matched old and new URLs. For each + mapped pair, check parity: title and meta, the canonical target, structured + data, the presence of the content the old page ranked for, and the + internal-link graph around it. Flag any new page that lost metadata, changed a + canonical away from itself, dropped structured data, or is missing content its + old counterpart carried. Report parity per pair with the evidence. Report only. + +Output artifact: the parity report (each mapped pair, per-check verdict, the evidence) +Done when: every mapped pair has a parity verdict across metadata, canonical, structured data, content presence, and internal links +Fails look like: parity by URL existence. A new URL that returns 200 can still have lost the title, the schema, and half the body the old one ranked for, and a check that stops at "the page exists" certifies a page that will not hold the ranking. + +### Phase 4: Staged cutover · lane: divergent (human) + +Skills: launch-runbook +Capability class: migration.cutover (write-held runbook; the actions are human) +Input: the passing redirect map and parity report +Run: + + Invoke launch-runbook to author the staged cutover runbook: the ordered DNS + and platform steps, each stage with a checkpoint that must pass before the + next. Then a person performs the cutover per the runbook; DNS and platform + changes are production state changes and stay human. The human records which + stage was executed when, and holds at any checkpoint that fails rather than + proceeding. + +Output artifact: the staged cutover runbook, and the human's record of each stage executed with its checkpoint result +Done when: the cutover stages are executed per the runbook with each checkpoint recorded, or the cutover is held at a failed checkpoint +Fails look like: a big-bang cutover with no checkpoints. Flipping everything at once removes the one thing staging buys, the chance to catch a broken stage before the next one lands on top of it. + +### Phase 5: Post-cutover verification · lane: gate (Basano) + +Skills: none; the engine is the Post-Deploy Live Verification workflow, executed as written +Capability class: deploy.live-verify (delegated to Post-Deploy Live Verification) +Input: the new property; the redirect map +Run: + + Run Post-Deploy Live Verification as written against the new property's touched + and blast-radius routes. Do not restate its procedure here: it owns the + discriminator value, the build-identity read, and the two-fetch production + discipline, and this phase inherits all of it. Then add the migration-specific + check: verify the redirect map fires on the live property, the highest-traffic + and the gone-with-intent URLs first, each old URL landing on its mapped target + with the right status code. Report the live-verification verdict and the + redirect verdicts together. + +Output artifact: the Post-Deploy Live Verification closure for the new property plus the live redirect verdicts from the map +Done when: Post-Deploy Live Verification closes VERIFIED on the new property and the mapped redirects fire live with the right status codes, or the discrepancies are filed with their evidence +Fails look like: declaring the migration done at the DNS flip. DNS resolving is not the property migrated; the redirects, the parity, and the live render are, and only production fetches prove them. + +### Phase 6: Monitoring window against the pre-registered baselines · lane: gate (Basano) + +Skills: seo-rank-tracking, seo-traffic-diagnosis +Capability class: migration.monitor (substitute equivalents if off-catalog) +Input: the pre-registered baseline record; the new property's search-performance and ranking data on a cadence +Run: + + Invoke seo-rank-tracking and seo-traffic-diagnosis against the new property on + a fixed cadence through the monitoring window. Measure the affected segments + against the baselines pre-registered in Phase 1, and report the trajectory. + Declare the migration recovered only when the pre-registered recovery metric + holds across its pre-registered window, not on the first good week. If the + trajectory contradicts the baseline, the migration has a regression and it + routes out of this workflow. + +Output artifact: monitoring reports on cadence, and a closure record when the pre-registered recovery condition holds +Done when: the pre-registered recovery condition holds across its window and the closure is recorded, or the window breaks baseline and the regression is routed to Traffic-Drop Triage +Fails look like: closing on the first good week. Migration traffic is noisy in the weeks after cutover, and a recovery declared on one datapoint reopens a month later as a mystery with the trail already cold. + +## Failure modes + +- The redirect map sampled instead of complete (Phase 2's failure): the long tail dropped, and with it the accumulated equity. +- Baselines chosen after cutover (Phase 1's failure): a recovery metric fitted to what happened always finds recovery. +- Declaring success at the DNS flip (Phase 5's failure): cutover is not migration; the redirects, the parity, and the live render are. +- The old property's cache serving past cutover: after the flip, some request paths keep serving the old property's cached render for a while, so a page can look migrated on one fetch and stale on another. Verification covers cookie-less vantages and does not stop at the first clean fetch; a clean read from one path is a sample, not the verdict. This is the split-serving class at its worst possible moment, when two properties are briefly both answering. +- Parity by URL existence (Phase 3's failure): a 200 that lost the title, the schema, and half the body. +- A big-bang cutover (Phase 4's failure): no checkpoint to catch a broken stage before the next lands on it. + +## Worked example + +Pending. Populates when this workflow is executed as written on a real migration of a designated property; none is planned, so it holds at template until such a migration occurs. The split-serving pattern in the failure modes generalizes production incidents on an unnamed property, where a render persisted on one request path after a change while another path served current data; that lesson informs Phase 5's vantage discipline but is not validation evidence. Status flips to validated when a run record links here. + +## Boundaries + +- Post-Deploy Live Verification is Phase 5's engine: this workflow runs it as written against the new property and adds the redirect checks, rather than restating its procedure. +- Traffic-Drop Triage takes over when the monitoring window breaks baseline: a post-cutover regression that contradicts the pre-registered recovery metric is a diagnosable drop, and that workflow owns the diagnosis. diff --git a/workflows/post-deploy-live-verification.md b/workflows/post-deploy-live-verification.md new file mode 100644 index 0000000..2d8ed29 --- /dev/null +++ b/workflows/post-deploy-live-verification.md @@ -0,0 +1,160 @@ +# Post-Deploy Live Verification + +``` +name: Post-Deploy Live Verification +slug: post-deploy-live-verification +tier: forward-deployed (operations) +role: fde +status: template +score: 53 (demand 5, pain 5, differentiation 4, usability 5, connectors 5) +intent: merged-is-not-live as a procedure: prove that what production serves + is what was approved, on every route that matters, before the change + is called done +when to use: after every merge that changes anything a user or crawler sees; as + the standing final step of any pipeline that ships +when not to use: pre-merge checking (that is CI Prove-Gate Wiring's territory); + content-claim truth (Corpus Integrity and Correction); a live + regression from an already-promoted lane (Incident Response and + Lane Demotion, which this workflow's failures feed) +gap note: this workflow's core is the tier's largest DECLARED CATALOG GAP; + most phases are inline procedure with qa-testing and seo-technical + as the nearest anchors. It is written to be runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only for fixes the verification surfaces +``` + +Verification is read-only. Fixes it surfaces land held; deploy-platform actions (promoting, purging, redeploying) are human actions on the platform, outside these connectors by design. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The production domain, and the list of routes the change touched plus the routes that share templates or data with them. +- A way to read which build produced a served page (a deployment id, build hash, or asset fingerprint in the rendered HTML; every modern host embeds one). +- The approved state: the merged content, metadata, and values the pages are supposed to show. + +## Phases + +### Phase 1: Capture the expected state · lane: convergent (Tholo) + +Skills: qa-testing (nearest anchor; procedure inline) +Capability class: deploy.expected-state (declared catalog gap) +Input: the merged change; the route list +Run: + + From the merged change, record what production should now show, per + route: the content values that changed, titles and meta descriptions, + canonical URLs, structured data, and at least one DISCRIMINATOR VALUE + per route: something this deploy changed that the previous build could + not be showing (new copy, a new derived count, a version string). Add + the blast-radius routes: pages sharing the template, layout, nav, or + data source with the changed ones, because deploys regress neighbors. + Record the newest deployment or build identifier the platform reports. + +Output artifact: the expected-state sheet (route, expected values, discriminator value, expected build id) +Done when: every touched and blast-radius route has expected values and a discriminator +Fails look like: verifying only the changed route. The route you edited is the one you will look at anyway; the regression ships on the sibling route nobody listed + +### Phase 2: Production fetch and identity check · lane: gate (Basano) + +Skills: qa-testing, seo-technical (anchors; procedure inline) +Capability class: deploy.live-verify (declared catalog gap) +Input: the expected-state sheet +Run: + + Fetch each route's PRODUCTION URL: not a preview, not a staging domain, + not localhost, and not a browser with a warm cache. For each route, + record: the discriminator value present or absent; the build identifier + the served page embeds; title, meta description, canonical, social-share + metadata, and structured data against expected; and status codes on the + route and its internal links. Fetch twice with a short gap; a CDN can + serve different edges different builds, and one fetch is a sample, not + a verdict. Report per route: VERIFIED (discriminator present, build id + current, values match), STALE (old build id or missing discriminator), + or WRONG (current build, unexpected values). + +Output artifact: the live report (verdict, evidence, build id per route, both fetches) +Done when: every route on the sheet has a verdict from production fetches +Fails look like: trusting the deploy dashboard. The platform saying the deployment succeeded is a claim about the build, not about what a given route serves; tool-reported success is not verified state, and only the rendered production URL is ground truth + +### Phase 3: Discriminate the failure class · lane: convergent (Tholo) + +Skills: none; this is the decision table (procedure inline; the discriminator pattern generalizes production incidents on an unnamed property) +Capability class: deploy.failure-discriminate (declared catalog gap) +Input: the live report, when any route is STALE or WRONG +Run: + + Apply the decision table. ALL routes stale on the same old build id: + the deploy never promoted; the fix is platform-side promotion, not code. + SOME routes current and SOME stale: route-level cache or incremental + render staleness; the stale HTML was generated under the old build and + is being served past the new deploy; the fix is a targeted purge or + revalidation of those routes, and if a purged route goes stale again, + its background regeneration is failing and the platform's function logs + for that route are the next read. Routes CURRENT but WRONG: the defect + merged; the fix is code, as a held change. State which class the + evidence supports and what evidence would distinguish it further if + ambiguous. + +Output artifact: the failure-class finding with its evidence +Done when: every non-verified route has a named failure class or a named ambiguity with the next check specified +Fails look like: purge-and-hope. Purging a cache without knowing whether the deploy promoted treats two different diseases with one drug; when it happens to work, nothing was learned, and when it does not, the next hour is spent purging harder + +### Phase 4: Route the fix · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the failure-class finding +Run: promotion, purge, revalidation, and redeploy are performed by a person + on the platform (these are production state changes, and they stay + human). Code defects land as held changes (repo.change) for normal + review. The human records what action was taken and against which + failure class. +Output artifact: the action taken, recorded against the finding +Done when: the action for every non-verified route is taken or explicitly deferred +Operated-layer note: in an operated deployment the finding and the action land as an agreement-log row; a promoted lane whose deploys repeatedly land STALE is exactly the post_merge_outcome signal Incident Response and Lane Demotion consumes +Fails look like: the verification performing the platform action itself. The read side of this workflow can be trusted precisely because it cannot touch what it measures + +### Phase 5: Re-verify and close · lane: gate (Basano) + +Skills: qa-testing (anchor; procedure inline) +Capability class: deploy.live-verify (declared catalog gap) +Input: the expected-state sheet; the actions taken +Run: + + Re-run Phase 2 on every route that was not VERIFIED, same discipline: + production URL, discriminator, build id, two fetches. The change closes + only when every route on the sheet reads VERIFIED. Record the closure + with the final build id per route. If this workflow runs as a pipeline's + standing final step (it should), the closure record is the pipeline's + definition of done. + +Output artifact: the closure record (all routes VERIFIED, final build ids, timestamps) +Done when: all routes VERIFIED on production, and the closure record exists +Fails look like: closing at merge, or closing on the first good fetch after a purge. Done is a property of what production serves, held across both fetches, on every route on the sheet + +## Failure modes + +- Preview verification: any fetch that is not the production URL proves nothing about production. +- Single-fetch verdicts: CDN edges disagree; two fetches minimum, and disagreement between them is itself a finding. +- Dashboard trust: deploy success and served state are different facts (Phase 2's inline failure). +- Sibling blindness: verifying only the edited route (Phase 1's inline failure). +- Purge-and-hope (Phase 3's inline failure). +- Missing discriminator: without a value only the new build can show, a stale page that happens to look right passes; the discriminator is what makes VERIFIED falsifiable. +- Merge-time closure: the change is done when production says so, not when the repo does. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property. The verification core generalizes real post-merge passes on rampstack.co (rendered-state checks, cross-link verification, build-identity reads across two merges in one day); the failure-class decision table additionally generalizes production incidents on an unnamed property, including a route serving a twelve-day-old render while its sibling served current data. Status flips to validated when a run record links here. + +## Boundaries + +- CI Prove-Gate Wiring owns pre-merge gates; this workflow begins where CI ends, because CI runs against the build and this runs against the world. +- Incident Response and Lane Demotion consumes this workflow's repeated failures on promoted lanes; a STALE that recurs is an incident, not a verification note. +- Content Pipeline Phase 5 and Corpus Integrity Phase 5 are this workflow's content-shaped instances; they share the declared gap and the doctrine. diff --git a/workflows/regulated-content-compliance-gate.md b/workflows/regulated-content-compliance-gate.md new file mode 100644 index 0000000..4bb7981 --- /dev/null +++ b/workflows/regulated-content-compliance-gate.md @@ -0,0 +1,128 @@ +# Regulated-Content Compliance Gate + +``` +name: Regulated-Content Compliance Gate +slug: regulated-content-compliance-gate +tier: forward-deployed (operations) +role: fdm +status: template +score: 45 (demand 3, pain 5, differentiation 4, usability 4, connectors 5) +intent: a YMYL pre-publish gate that runs inside the content pipeline for regulated + properties: required disclosures present and placed, every regulated claim + sourced to a citable authority, and prohibited-claim patterns absent +when to use: a regulated or YMYL property (finance, health, legal, and the like) where a + published claim carries real-world consequence +when not to use: an unregulated property (Content Pipeline Phase 3's ordinary gate is + enough); correcting already-published regulated content (Corpus Integrity + and Correction, under both workflows' rules) +gap note: the placement-verification core is a DECLARED CATALOG GAP with seo-technical + as the nearest anchor; that phase is inline procedure. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read # placement verification on the built page +``` + +This gate is read-only: it reads the content pipeline's held drafts and the built page, and reports. A failing gate blocks the merge; it never edits the draft. Waivers are human decisions by the register owner. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The property's regulatory context: the disclosure requirements, the list of citable authorities, and the prohibited-claim patterns for its vertical. +- A register owner: the human accountable for the compliance register and its waivers. +- The content pipeline's held drafts as input; this gate runs inside Content Pipeline Phase 3 for regulated properties. +- A production-equivalent build, because placement is verified on the rendered page. + +## Phases + +### Phase 1: The compliance register · lane: divergent (human) + +Skills: none; the register is written to the property's regulatory requirements and owned by a human +Capability class: compliance.register (human-owned) +Input: the property's regulatory context; the register owner +Run: the register owner writes the compliance register once and approves it: + the disclosure requirements and where each must be placed, the list of + citable authorities a regulated claim may be sourced to, the prohibited-claim + patterns, and the placement rules. The register is the standard every draft + is gated against, so it is authored and human-approved before the gate runs, + not derived per draft. It is versioned, and it carries a review cadence + against its own regulatory sources. +Output artifact: the approved compliance register (disclosures and placements, the authority list, prohibited patterns, the review cadence) +Done when: the register owner has approved the register and its review cadence, and it is versioned +Fails look like: a register derived per draft. A standard invented fresh for each piece is not a standard, and it drifts to whatever the current draft happens to satisfy. + +### Phase 2: The compliance gate · lane: gate (Basano) + +Skills: evidence-based-reviews, editorial-qa +Capability class: compliance.gate (substitute equivalents if off-catalog) +Input: a held draft from Content Pipeline Phase 3; the approved register +Run: + + Invoke evidence-based-reviews and editorial-qa against the held draft, gated + on the register. Check three things and change nothing. Disclosures: every + required disclosure is present. Claims: every regulated claim is sourced to a + specific authority ON THE REGISTER'S LIST, which is authority-list checking, + not source-presence checking; a claim citing some source that is not a listed + authority fails, even though a source is present. Prohibited patterns: none of + the register's prohibited-claim patterns appear. Report a verdict per check + with the evidence. Report only; this gate blocks a merge, it does not edit the + draft. + +Output artifact: the compliance verdict per check (disclosures, authority-sourced claims, prohibited patterns), evidence attached +Done when: the draft carries a verdict on disclosures present, every regulated claim authority-sourced, and prohibited patterns absent +Fails look like: source-presence instead of authority-list checking. A claim with a citation attached passes a lazy check and fails the register when the citation is a blog rather than a listed authority; the presence of a source is not the same as sourcing to an authority. + +### Phase 3: Placement verification on the built page · lane: gate (Basano) + +Skills: seo-technical (nearest anchor; the placement-verification core is a DECLARED GAP, procedure inline) +Capability class: compliance.placement-verify (declared catalog gap; nearest-miss seo-technical) +Input: the built page (crawl.read); the register's placement rules +Run: + + Invoke seo-technical against the BUILT page, not the source. For each required + disclosure, verify it renders where the register's placement rule requires: a + disclosure that exists in the source but renders below the fold, inside a + collapsed element, or on a path the reader does not take, fails placement even + though it is present. Report placement per disclosure against its rule, with + the rendered evidence. Report only. + +Output artifact: the placement report (each disclosure, its required placement, its rendered placement, a verdict) +Done when: every required disclosure has a placement verdict against the register's rule, checked on the built render +Fails look like: verifying placement in the source. A disclosure in the markup that a collapsed accordion hides at render is present to a grep and absent to a reader, and the reader is who the rule protects. + +### Phase 4: Waiver protocol · lane: divergent (human) + +Skills: none; a waiver is the register owner's decision +Input: a compliance failure the team proposes to waive +Run: only the register owner may waive a compliance failure, and a waiver is + never routine. The owner records what was waived, the specific rule, and the + rationale, and the waiver is scoped to the one draft, not the standard. + Repeated waivers of the same rule are a signal that the register is wrong or + the process is, and they surface for review rather than accumulating silently. +Output artifact: the recorded waiver (the rule, the draft, the register owner's rationale), or the confirmation that no waiver was granted +Done when (public gate): every compliance failure is either fixed and re-gated, or waived in writing by the register owner with a recorded rationale +Operated-layer note: in an operated deployment a waiver lands as an agreement-log row with human_verdict = waive and a required human_reason, excluded from the false-pass and false-fail rate computations and reported on its own line (AGREEMENT-LOG.md) +Fails look like: routine waivers. A waiver any reviewer can grant, or one that passes without the register owner and a rationale, turns the gate into a formality the pipeline learns to wave through. + +## Failure modes + +- Source-presence instead of authority-list checking (Phase 2's failure): a citation present but not to a listed authority. +- Disclosure present but mis-placed (Phase 3's failure): rendered below the fold or inside a collapsed element. +- The register going stale against changed rules: a regulatory requirement moves and the register does not; the Phase 1 review cadence on the register itself is the guard. +- Treating this gate as Content Pipeline Phase 3: it is additive, an extra gate for regulated properties, never a replacement for that phase's ordinary pre-publish gate. +- Routine waivers (Phase 4's failure): waivers granted without the register owner, or so often they stop meaning anything. +- Gating the draft but not the built page: passing on source presence and never checking the render is how a compliant draft ships as a non-compliant page. + +## Worked example + +Pending. Populates when this workflow is executed as written on regulated content reaching a designated property; no designated property carries regulated content today, so it holds at template until such content exists on one. Status flips to validated when a run record links here. + +## Boundaries + +- This gate runs INSIDE Content Pipeline with Prove Gates, Phase 3, for regulated properties: it is additive to that phase's ordinary gate, never a substitute, and a regulated draft passes both. +- Corpus Integrity and Correction owns corrections to already-published regulated content; a correction to a regulated claim runs under both this workflow's authority-list rule and that workflow's visible-correction pattern. diff --git a/workflows/revenue-tracking-integrity.md b/workflows/revenue-tracking-integrity.md new file mode 100644 index 0000000..9ae34bf --- /dev/null +++ b/workflows/revenue-tracking-integrity.md @@ -0,0 +1,163 @@ +# Revenue Tracking Integrity + +``` +name: Revenue Tracking Integrity +slug: revenue-tracking-integrity +tier: forward-deployed (operations) +role: fda +status: template +score: 47 (demand 4, pain 5, differentiation 5, usability 3, connectors 4) +intent: a scheduled prove pass over the money path: params surviving redirects, + consent not zeroing attribution, platform and warehouse reconciled, and + monetized links live +when to use: any property that earns through tracked links or events, on a schedule +when not to use: diagnosing a conversion divergence on stable traffic (Conversion-by-Source + Diagnosis); a falling-traffic mystery (Traffic-Drop Triage) +gap note: the money-path map, the consent matrix, and the reconciliation cores are + DECLARED CATALOG GAPS; those phases are inline procedure with + product-analytics-setup as the nearest anchor. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: crawl.read + access: read + - capability: analytics.read + access: read + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: revenue.read + access: read +``` + +Fully read-only until Phase 5, and Phase 5 only ever produces held changes and a schedule. Platform and merchant changes stay human; nothing in the audit acts on the money path. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- The list of monetized link and event classes the property runs (affiliate links, checkout events, lead events). +- Read access to the platform that reports revenue or clicks, and to the analytics and warehouse stores the events land in. +- Enough accrued revenue or click data for a reconciliation window to be meaningful. +- The attribution parameter set: which parameters must survive the redirect chain. + +## Phases + +### Phase 1: Map the money path · lane: convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; the money-path-mapping core is a DECLARED GAP, procedure inline) +Capability class: revenue.path-map (declared catalog gap; nearest-miss product-analytics-setup) +Input: the site (crawl.read), the platform records (revenue.read), and the event definitions +Run: + + Invoke product-analytics-setup's instrumentation discipline. Enumerate every + monetized link and event CLASS, not instance: each affiliate or outbound money + link type, its full redirect chain, the attribution parameters it must carry, + the event it fires, and the platform record that event should become. Map each + class end to end, from the on-page link to the reconciled revenue row. Produce + the money-path map; test nothing yet. + +Output artifact: the money-path map (each class: link, redirect chain, required params, event, platform record) +Done when: every monetized class is mapped from on-page link to platform record, with its required attribution parameters named +Fails look like: mapping link instances instead of classes. Ten thousand affiliate links share a handful of classes, and a map keyed to instances misses the class-wide break while drowning in duplicates. + +### Phase 2: Liveness and parameter survival · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.liveness-check (declared catalog gap; nearest-miss product-analytics-setup) +Input: the money-path map +Run: + + Invoke product-analytics-setup's verification discipline as a gate. Per link + class, fetch a live instance (crawl.read), follow the full redirect chain to + its destination, and assert two things: the link resolves to a live endpoint + (no dead redirect, no parking page, no 404 at the merchant), and the required + attribution parameters arrive intact at the end of the chain, not stripped by + a redirect hop or a canonicalization. Test every class, including the ones + that look fine. Report liveness and parameter survival per class with the + chain as evidence. Report only. + +Output artifact: a liveness-and-survival report per class (resolves live, params arrived, the chain) +Done when: every link class has a liveness verdict and a parameter-survival verdict with its redirect chain recorded +Fails look like: testing one link and trusting the class. One affiliate link resolving does not prove the class resolves, and the broken subset earns nothing while the test stays green. + +### Phase 3: Consent-state matrix · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; the consent-matrix core is a DECLARED GAP, procedure inline) +Capability class: measurement.consent-matrix (declared catalog gap; nearest-miss product-analytics-setup) +Input: the money-path map; the property's consent states +Run: + + Invoke product-analytics-setup's measurement discipline. Build the matrix: + each money event against each consent state the property can be in (granted, + denied, not-yet-decided, and any regional variant). For each cell, confirm + whether the event fires and whether attribution survives. The failure this + catches: a consent state that silently zeroes attribution, so revenue is + earned but recorded as unattributed or not at all. Report the matrix with the + fired-and-attributed verdict per cell. Report only. + +Output artifact: the consent matrix (event by consent state, fired and attributed verdict per cell) +Done when: every money event has a verdict under every consent state the property supports +Fails look like: testing only the granted state. Consent-denied and undecided states are where attribution quietly zeroes, and a matrix that skips them certifies a path that loses money in the states most users are actually in. + +### Phase 4: Reconciliation · lane: gate (Basano) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.reconcile (declared catalog gap; nearest-miss product-analytics-setup) +Input: the platform-reported events and revenue (revenue.read); the warehouse-landed events (warehouse.query, bounded) +Run: + + Invoke product-analytics-setup's reconciliation discipline as a gate. For a + bounded window, pull platform-reported events and revenue and the + warehouse-landed equivalents, and reconcile them within a stated tolerance, + per source, not only in total. Flag any per-source row that drifts past + tolerance even when the totals happen to match, because offsetting errors hide + in the total. Every warehouse query carries its date range as a partition + filter. Report the reconciliation per source with the variance. Report only. + +Output artifact: the reconciliation report (platform versus warehouse per source, variance, tolerance verdict) +Done when: every source is reconciled within tolerance for the window, or the per-source variance is flagged with evidence +Fails look like: reconciling totals while per-source rows drift. A matching grand total made of two offsetting errors reads as healthy and is two broken sources wearing a coincidence. + +### Phase 5: Findings triage, held fixes, and the standing cadence · lane: divergent (Krine) then convergent (Tholo) + +Skills: product-analytics-setup (nearest anchor; procedure inline) +Capability class: revenue.correct (write-held) +Input: the liveness, consent, and reconciliation reports +Run: + + Invoke product-analytics-setup to rank the findings by revenue at risk and + present the plan for a human to approve (the divergent stop). On approval, + land fixes held: a dead link class routed to its owner, a consent-zeroing path + routed to a measurement fix, a reconciliation drift routed to the + instrumentation. Then set the standing cadence: this pass recurs on a schedule + (monthly fits most money paths), so a dead class is caught by the pass, not by + a quarter of missing revenue. Nothing here publishes; platform and merchant + changes stay human. + +Output artifact: a ranked plan, held fixes tied to findings, and the recorded recurring cadence +Done when (public gate): a human has approved the plan, every approved fix is held, and the recurring cadence is scheduled +Operated-layer note: in an operated deployment the ranking and the human's approval land as an agreement-log row (see AGREEMENT-LOG.md) +Fails look like: running this once. A money path is only as sound as its last pass, and the dead link that appears the week after a one-time audit earns nothing until someone notices the gap in the revenue. + +## Failure modes + +- Instance-not-class testing (Phase 2's failure): one link checked, the class assumed. +- Granted-only consent testing (Phase 3's failure): the states where attribution zeroes go unchecked. +- Total-level reconciliation (Phase 4's failure): per-source drift hidden by a matching total. +- One-shot auditing (Phase 5's failure): a dead monetized link discovered by its revenue's absence months later. +- Unbounded reconciliation queries: a warehouse pull with no partition filter, a cost incident on the money path. +- Parameter survival assumed from presence: a parameter present on the link but stripped mid-chain, so the click lands unattributed. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is a prove pass over the affiliate money path on an outdoor-sports content property once its first affiliate data accrues. Status flips to validated when that run record links here. + +## Boundaries + +- Conversion-by-Source Diagnosis assumes this path passes: its Phase 3 is a per-finding spot-check of measurement, and this is the scheduled end-to-end audit of the money path. +- Experiment Loop with Pre-Registered Gates (design v2, publishing later) reads verdicts only as trustworthy as this path; a revenue experiment on a broken money path measures noise. +- Warehouse Data Plane Standup wires the bounded warehouse access this workflow's reconciliation reads through. diff --git a/workflows/run-records/content-pipeline-prove-gates-run-1.md b/workflows/run-records/content-pipeline-prove-gates-run-1.md new file mode 100644 index 0000000..c51d708 --- /dev/null +++ b/workflows/run-records/content-pipeline-prove-gates-run-1.md @@ -0,0 +1,73 @@ +# Content Pipeline with Prove Gates: run record 1, draw length + +This is the validation run record for the "Content Pipeline with Prove Gates" workflow, executed as written on this property (an outdoor-sports content site). One piece moves through the pipeline: the draw-length how-to. Phases 1 to 5 run as written; Phase 6 accrues on cadence and is out of scope for this record. Each phase below is one artifact. + +## Phase 1: Rank the backlog from demand (already complete, cited here) + +- Go item: "how to measure draw length", the first how-to piece. +- Ranking evidence: demand overturned a rangefinder-first assumption. Draw length at roughly 1,200 monthly US searches outranked the how-to candidates it competed with (arrow spine about 1,000; sights about 450; rangefinder how-tos about 10). Write order follows demand; the rangefinder spokes ride as support for the priority money guide rather than leading. +- Difficulty and intent: the property relaunched ranking for nothing, so attainable difficulty (low across this map) was weighted over raw volume; the full ranking method, per-cluster demand numbers, and their capture citations are in docs/research/keyword-content-map.md. The SERP shows calculator intent and no strong article competitor, so the piece supports the existing draw-length calculator tool and the beginner-bow money guide. +- Recorded sequencing decision: draw length first. It is the fit number the beginner path leans on and the piece that feeds the arrows and bows guides, so it earns the front of the queue. +- NeuronWriter brief: briefs/how-to-measure-draw-length-2026-07-08.md (keyword "how to measure draw length", roughly 684-word target, twelve advisory terms, the reader questions, and the competitor set). Coverage against those terms is advisory and never a merge gate. +- The ranking was not re-run for this record; this phase cites the completed selection and stops. + +## Phase 2: Produce the held draft (write-held) + +- Held draft: PR #33 (draft), branch feat/content-draw-length. Nothing published, scheduled, or merged. +- Piece: content/articles/how-to-measure-draw-length.mdx. HowTo schema variant; four real-step H2s that read into the HowTo JSON-LD as steps; the AMO-standard definition and the arrow-length relation as H3 explainers; every factual claim carries its source or derivation inline; internal links to the draw-length calculator, the beginner compound bow guide, and the hunting arrows guide. Body length 680 words, inside the brief's 650 to 800 target. +- Written against: briefs/how-to-measure-draw-length-2026-07-08.md. + +## Phase 3: Pre-publish gate (report only, nothing fixed inside the gate) + +Prove report, verdict per check. The validator is the content-contract check that runs at build time plus the type and lint passes; the rendered audit is the built page inspected on a local production build. + +\| Check \| Verdict \| Evidence \| +\|---\|---\|---\| +\| Content contract (frontmatter, schema, no picks) \| PASS \| build compiled; required article fields present (title, standfirst, excerpt, author, date); schema is "howto"; no picks apparatus on an article \| +\| Types and lint \| PASS \| tsc noEmit clean; eslint reports no errors \| +\| Every factual claim has a source or derivation inline \| PASS \| the wingspan-over-2.5 formula is named as the archery wingspan method; the nock-to-grip-pivot plus 1.75 inch definition is attributed to the AMO and ATA standard; the typical 26 to 31 inch range and the 28 to 29 inch adult-male average are stated as derivations from that method and from where stock bows center their adjustment; the half-inch confirmation tolerance matches the calculator's own stated basis. No unsourced statistic appears. \| +\| Style and phrase rules (STANDARDS: CLAUDE.md and docs/brand/voice.md) \| PASS \| zero em or en dashes; zero banned phrases; no "not just" construction (grep of the file) \| +\| Title, meta description, structured data present and consistent \| PASS \| rendered title is the piece title suffixed with the site name; the meta description is the standfirst; the HowTo JSON-LD is present with four HowToSteps matching the four H2 steps in order, alongside a BreadcrumbList filed under the Articles hub; the canonical is self-referencing \| +\| Every internal link resolves against the route list \| PASS \| /tools/draw-length-calculator, /guides/best-compound-bow-for-beginners, /guides/best-hunting-arrows, and /how-we-test each return 200 on the built site, as does the article's own route \| + +Gate verdict: all checks pass, no waiver required. Nothing was fixed inside the gate; the draft was authored to the standard in Phase 2. + +## Phase 4: Human review and merge + +- Reviewer: Andy Dunn, the mergedBy on PR #33 +- Verdict: merge (human-verdict vocabulary: merge / reject / revise / waive) +- What changed (proposal to merge): Merged untouched. No revisions between the proposed held draft and the merge; no proposal-to-merge diff. The article content committed once (6389a70); the only later commits on the branch were run-record docs (692cb7e, 110c73e), not content edits. +- Merged at: 2026-07-10T01:41:15Z (UTC), squash-merge, merge commit f4395716 onto main + +## Phase 5: Post-publish live audit (post-merge, on the human's go) + +Run the live audit against the production URL https://bowhuntamerica.com/articles/how-to-measure-draw-length after merge and deploy. Verify per check against the live render, not a preview, staging domain, or cached copy: the rendered content matches what was approved at merge; the canonical is self-referencing; title, meta description, social-share metadata, and the HowTo structured data are present on the live render and match the approved values; every internal link on the live page resolves; and the render is current, confirmed against a value known to have changed at publish. Record the verdict per check and the deployment id. + +- Deployment id: current prerender of the article route; render ETag 52f1e233b9f8c2d1b3c977959aa29d8e, OpenGraph image asset fingerprint e531b1656856773d (content-derived, host-agnostic). +- Live-audit verdict per check: + +\| Check \| Verdict \| Evidence \| +\|---\|---\|---\| +\| Rendered content matches what was approved at merge \| PASS \| the wingspan method, the AMO and ATA definition, the half-inch confirmation tolerance, the typical 26 to 31 inch range and the 28 to 29 inch adult-male average, and the nock-to-grip references all render on the live page, matching the Phase 2 draft \| +\| Canonical is self-referencing \| PASS \| the rendered canonical points to the article's own URL, https://bowhuntamerica.com/articles/how-to-measure-draw-length \| +\| Title, meta description, social-share metadata, and structured data present and consistent \| PASS \| rendered title is the piece title suffixed with the site name; the meta description is the standfirst; OpenGraph title, description, and image and the Twitter summary_large_image card, title, and description are present; the HowTo JSON-LD carries four HowToSteps matching the four H2 steps, alongside a BreadcrumbList; the values match the approved article \| +\| Every internal link on the live page resolves \| PASS \| all fourteen internal links on the live render return 200, including /tools/draw-length-calculator, /guides/best-compound-bow-for-beginners, /guides/best-hunting-arrows, /how-we-test, and the article's own route \| +\| Render is current (a value known to have changed at publish) \| PASS \| the article route serves the full new content that did not exist pre-publish; the page carries the current build's index, follow directive rather than the pre-launch noindex; the render is a current prerender (the ETag and OpenGraph asset fingerprint above) \| + +Auto-appearance checks: + +\| Check \| Verdict \| Evidence \| +\|---\|---\|---\| +\| The articles hub lists the piece \| PASS \| /articles renders the draw-length article's link and title \| +\| The homepage latest row carries it \| PASS \| the homepage links /articles/how-to-measure-draw-length in its latest row \| +\| The start-here draw-length link resolves \| PASS \| the homepage start-here strip's draw-length entry links /tools/draw-length-calculator, which returns 200 \| + +A finding surfaced during this phase, recorded plainly. The audit's external fetch vantage returned a stale pre-launch render of the homepage, an indexing-directive mismatch included, while the article routes served the current build. The failure-class discrimination ran on that signal: production was confirmed healthy from direct vantages, the browser source and a cookie-less fetch from a clean path, both of which return the current build with index, follow, the Articles and Tools nav, and the draw-length piece in the latest row. The stale copies were attributed to an intermediary fetch cache on an external fetch path rather than to a production regression, so the audit exercised the vantage-and-staleness branch of its decision table on a real signal and closed with the production-healthy conclusion and its evidence. + +## Phase 6: Outcomes and the refresh trigger (not part of this record) + +Outcomes accrue on a cadence and decay flags re-enter the Phase 1 ranking. Out of scope for this run record. + +--- + +Run status: Phases 1 to 5 are complete. The pre-publish gate passed with no waiver, the draft merged unchanged with no proposal-to-merge diff, and the post-publish live audit passes against the production URL with every check green and the three auto-appearance checks confirmed. This is the completed validation record for the Content Pipeline with Prove Gates workflow: the run record that links from the workflow file to flip its status from template to validated. Phase 6 accrues on cadence and is out of scope for this record. diff --git a/workflows/traffic-drop-triage.md b/workflows/traffic-drop-triage.md new file mode 100644 index 0000000..2ce7bfb --- /dev/null +++ b/workflows/traffic-drop-triage.md @@ -0,0 +1,193 @@ +# Traffic-Drop Triage + +``` +name: Traffic-Drop Triage +slug: traffic-drop-triage +tier: forward-deployed (operations) +role: fda +status: template +score: 51 (demand 5, pain 5, differentiation 4, usability 4, connectors 4) +intent: diagnose an organic traffic drop with a disciplined decision tree, + evidence per branch, before anyone acts on it +when to use: organic traffic is down and the team is about to do something about it +when not to use: routine performance review (use Conversion-by-Source Diagnosis); + a known deploy broke something (use Incident Response and Lane + Demotion); paid traffic changes (off-catalog) +validation note: gated on a showcase-designated property experiencing a diagnosable + drop; the pattern generalizes a real production diagnosis on an + unnamed property +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: analytics.read + access: read + - capability: crawl.read + access: read + - capability: repo.change + access: write-held # only if Phase 4 routes to a technical fix +``` + +This workflow is read-only until Phase 4, and Phase 4 only ever produces held changes. Nothing in the triage acts on production. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- At least one demand-side data source (search-performance export) AND one behavior-side source (analytics events), because the single most valuable discriminator in the tree is whether they disagree. +- Enough history to compute a baseline: the same period last year if seasonality is plausible, or at minimum several stable weeks pre-drop. +- The deploy log or release history for the drop window. + +## Phases + +### Phase 1: Pin the drop · lane: convergent (Tholo) + +Skills: seo-traffic-diagnosis +Capability class: traffic.baseline (substitute equivalents if off-catalog) +Input: search-performance and analytics data spanning the drop and the baseline window +Run: + + Invoke seo-traffic-diagnosis against the traffic data. Establish, with + numbers: when the drop started (day precision), its magnitude vs the + pre-drop baseline, and its shape across segments: which page templates, + which query classes, which devices, which countries, which traffic + sources. Do not explain the drop yet. Produce the drop profile only. + +Output artifact: a drop profile (start date, magnitude, segment breakdown) +Done when: the profile states when, how much, and where, each with a number +Fails look like: averaging over segments. A sitewide average of minus 30 percent can be one template at minus 90 and everything else flat, and those are different diagnoses; the segment breakdown is the whole point of this phase + +### Phase 2: Run the branches · lane: gate (Basano) + +Five branches, every one checked, none acted on. Each produces evidence for or against; skipping a branch because another already looks guilty is the failure this phase exists to prevent. + +Branch A, tracking breakage.* +Skills: product-analytics-setup (nearest anchor; the breakage-detection core is a DECLARED GAP, procedure inline) +Run: + + Cross-check the two data sources for the drop window: if search-performance + impressions and clicks are steady while analytics sessions dropped, the + traffic did not fall, the measurement did. Check: the analytics tag present + and firing on affected templates (crawl.read the live pages), consent-flow + changes in the window, filter or property configuration changes, and + whether the drop starts at a deploy boundary rather than a demand boundary. + +Branch B, technical regression. +Skills: seo-site-health-audit, seo-technical +Run: + + Invoke seo-site-health-audit and seo-technical against the affected + segments. Check: robots directives and noindex on affected templates, + canonical correctness, status codes and redirect chains, sitemap presence, + render-blocking or hydration failures on the live pages, and whether any + of these changed at a deploy inside the drop window. + +Branch C, algorithm-update timing. +Skills: seo-traffic-diagnosis +Run: + + Compare the drop start date against the published update timeline. Check + the drop's shape against the update class: sitewide vs template-scoped vs + query-class-scoped losses point at different update types. Timing + correlation alone is not a diagnosis; require shape agreement too. + +Branch D, seasonality and demand shift. +Skills: seo-keyword +Capability class: demand.trend +Run: + + Query the warehouse for the same period in prior years (bounded date + ranges). Invoke seo-keyword against the affected query classes: did the + demand itself fall? A drop that tracks the category's demand curve is not + a site problem, and treating it as one wastes a quarter. + +Branch E, SERP displacement. +Skills: seo-rank-tracking, seo-competitor +Run: + + Invoke seo-rank-tracking on the affected queries: are positions held or + lost? Positions held with clicks down points at SERP-feature displacement + (check the affected queries' current result layout). Positions lost points + at a competitor or a relevance change; invoke seo-competitor to identify + who took them and with what. + +Output artifact: a branch evidence table: five branches, evidence for, evidence against, per-branch confidence +Done when: all five branches have evidence recorded, including the branches that came back clean +Fails look like: stopping at the first guilty-looking branch. Real drops are frequently compound (an update lands the same week a consent banner breaks measurement), and a one-branch diagnosis on a compound drop fixes half the problem while the other half compounds + +### Phase 3: Diagnosis · lane: divergent (Krine) + +Skills: none; this is the judgment stop +Input: the drop profile and the branch evidence table +Run: + + Rank the candidate causes by evidence strength, stating per-branch + confidence and explicitly noting compound possibilities. Present the + ranked diagnosis with the evidence attached. Recommend nothing yet. + Stop for the human. + +Output artifact: a ranked diagnosis with per-cause confidence and the compound read +Done when: a human has confirmed the diagnosis or sent specific branches back for deeper evidence +Operated-layer note: in an operated deployment, the engine's ranked diagnosis and the human's confirmation or override land as an agreement-log row; diagnosis agreement over time is what earns this lane trust +Fails look like: the diagnosis arriving pre-merged with the treatment. The moment the diagnosis says "and therefore we should," the human is reviewing a plan, not a finding, and anchoring does the rest + +### Phase 4: Route the response · lane: convergent (Tholo) + +Skills: routing per diagnosis; the responses live in their owning workflows +Input: the confirmed diagnosis +Run: + + Route each confirmed cause to its owner: technical regression -> a held + change (repo.change) with the specific fix; tracking breakage -> a held + fix to the measurement path, plus an annotation on the drop window so + the record shows measurement loss, not traffic loss; update-class losses + -> the content-quality program (Corpus Integrity and Correction, Content + Pipeline refresh triggers), never a quick technical counterattack; + demand decline -> a strategy note, not a fix; SERP displacement -> + targeted format or coverage work through the Content Pipeline. Every + response lands held; nothing merges from inside the triage. + +Output artifact: held changes and routed work items, each tied to its diagnosed cause +Done when: every confirmed cause has a routed response or an explicit decision to accept it +Fails look like: fixing inside the triage. The triage's authority is diagnostic; the moment it merges its own fixes, the diagnosis and the treatment share an author and the verification story collapses + +### Phase 5: Recovery watch · lane: gate (Basano) + +Skills: seo-rank-tracking, seo-traffic-diagnosis +Input: the pre-registered recovery metric (set it now, before watching: which segment, back to what level, measured how) +Run: + + On a fixed cadence, measure the affected segments against the + pre-registered recovery metric and the pre-drop baseline. Report + trajectory per diagnosed cause. Declare recovery only when the + pre-registered condition holds across the pre-registered window, not + on the first good week. + +Output artifact: recovery reports on cadence; a closure record when the pre-registered condition holds +Done when: recovery is declared against the pre-registered condition, or the diagnosis is reopened because the trajectory contradicts it +Fails look like: victory on one good week. Traffic is noisy; a recovery declared on a single datapoint reopens as a mystery a month later, now with the trail cold + +## Failure modes + +- First-plausible-branch tunnel vision (Phase 2's inline failure; the discipline is that clean branches get recorded too). +- Measurement loss recorded as traffic loss: the record must say which it was, or every future baseline is quietly wrong. +- Timing-only update attribution: correlation with an update date without shape agreement is a coin flip wearing a citation. +- Treatment anchoring: diagnosis and recommendation delivered as one artifact (Phase 3's inline failure). +- Unpre-registered recovery: the metric chosen after watching begins always finds recovery. +- Compound drops resolved as single causes: fix half, and the remaining half now looks like the fix failed. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property experiencing a diagnosable drop. The decision tree generalizes a real production diagnosis (a mass deindexation timed to a core update, root-caused to content quality rather than technical failure, on an unnamed property); that incident informs the branches but is not validation evidence. + +## Boundaries + +- Incident Response and Lane Demotion owns drops caused by the pipeline's own promoted changes (a post-merge regression is an incident with a known suspect, not a mystery). +- Conversion-by-Source Diagnosis owns conversion problems on stable traffic; this workflow owns the traffic itself. +- Corpus Integrity and Correction and the Content Pipeline own the content-quality responses this workflow routes to; the triage never edits content. diff --git a/workflows/warehouse-data-plane-standup.md b/workflows/warehouse-data-plane-standup.md new file mode 100644 index 0000000..c4d7e6c --- /dev/null +++ b/workflows/warehouse-data-plane-standup.md @@ -0,0 +1,176 @@ +# Warehouse Data Plane Standup + +``` +name: Warehouse Data Plane Standup +slug: warehouse-data-plane-standup +tier: forward-deployed (operations) +role: fde +status: template +score: 43 (demand 4, pain 4, differentiation 3, usability 4, connectors 5) +intent: stand up the data plane the tier reads from: exports first, two stores, + read-only bounded access, cost governance, and an always-on sensing layer +when to use: day zero of a forward-deployed engagement, before any workflow that + reads metrics +when not to use: a stack whose warehouse, exports, and governance already exist (start + with the workflow that needs the data); a one-off query (this is the + standing plane, not a query) +validation note: the occasion is the search-console bulk-export and warehouse enablement + session on a showcase-designated property, already on the critical path +gap note: the two-store standup, the access-wiring, and the verification cores are + DECLARED CATALOG GAPS; those phases are inline procedure with + data-warehouse-experimentation as the nearest anchor. It is written to be + runnable anyway. +``` + +## Connectors + +``` +connectors: + - capability: warehouse.query + access: read + bounds: every query carries a date range pushed down as a partition filter + - capability: search-performance.read + access: read + - capability: analytics.read + access: read +``` + +This workflow stands up read-only access and wires no write path. Enabling the exports and provisioning the stores are platform actions a person performs; the engines never gain a write tool on this plane. + +## Prerequisites + +- Claude with the catalog installed: `/plugin marketplace add rampstackco/claude-skills` +- A warehouse you can create datasets in, with a billing project. +- Admin access to the search-console and analytics properties whose exports you will enable. +- An operational store separate from the warehouse, or the ability to provision one. +- The access controls to grant a scoped, read-only service identity. + +## Phases + +### Phase 1: Enable the exports · lane: divergent (human) + +Skills: none; the actions here are deliberately human +Input: the list of properties in scope; the search-console and analytics accounts +Run: a person enables the search-console bulk export and the analytics + warehouse export (the native daily-table exports) on every property in + scope, and records the enablement date per property. This is the one + time-sensitive action in the standup: the exports do not backfill, so the + history starts the day the export is enabled and the clock only runs + forward. Turn them on before any other step. +Output artifact: the exports enabled per property, with the enablement date recorded +Done when: every in-scope property has both exports enabled with a recorded start date, confirmed in the source consoles +Fails look like: doing this last. Every day the exports are off is a day of history that will never exist, and no later step can recover it. + +### Phase 2: Separate the two stores · lane: convergent (Tholo) + +Skills: data-warehouse-experimentation (nearest anchor; the two-store standup core is a DECLARED GAP, procedure inline) +Capability class: warehouse.standup (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the enabled exports; the provisioned warehouse and operational store +Run: + + Invoke data-warehouse-experimentation's warehouse-shape discipline. Stand up + two stores with one boundary rule: the metric warehouse holds metric history + (the export tables and their derivations), the operational store holds run + records, decisions, and the agreement log. Pick the warehouse region once and + match it across both exports, because it cannot be changed later without a + migration. Nothing that answers "what did the engines and humans decide" goes + in the warehouse; nothing that answers "what happened to the numbers" goes in + the operational store. Record the boundary as written policy. + +Output artifact: the two stores stood up, the region fixed, and the store-boundary policy recorded +Done when: both stores exist, the region matches across exports, and the boundary policy names which data lives where +Fails look like: one store doing both jobs. A single store for metrics and decisions couples query cost to operational writes and loses the separation the whole plane depends on. + +### Phase 3: Wire read-only access with mandatory bounds · lane: convergent (Tholo) + +Skills: data-warehouse-experimentation (nearest anchor; the access-wiring core is a DECLARED GAP, procedure inline) +Capability class: warehouse.mcp-wire (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the metric warehouse; the identity and access controls +Run: + + Invoke data-warehouse-experimentation's access discipline. Wire the engines' + read path through a read-only interface (a managed warehouse MCP server plus a + thin domain layer) under a scoped service identity with dataset-scoped read + and deny-by-default elsewhere. Encode the query-correctness rules the raw + tools lack: the mandatory date range pushed down as a partition filter on + every call, and any source-specific offset (search-console positions are + zero-based, so average position is computed with the offset). A call without a + date range is rejected, not run. No write tool is present on this path. + +Output artifact: the read-only access layer, the scoped identity, and the bounds-and-offset rules encoded in the domain layer +Done when: every warehouse call goes through the bounded read path, an unbounded call is rejected, and the identity carries no write scope +Fails look like: bounds enforced by convention instead of code. A partition filter that is supposed to be there is absent on the one query written under deadline, and that is the query that scans the full history. + +### Phase 4: Cost and quota governance · lane: gate (Basano) + +Skills: data-warehouse-experimentation (nearest anchor; procedure inline) +Capability class: warehouse.cost-governance (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the wired access layer; the warehouse's billing and quota controls +Run: + + Invoke data-warehouse-experimentation's cost discipline as a gate. Issue an + unbounded query and confirm it is rejected; issue a bounded query and confirm + it scans only the requested partitions. Set a budget alert and a quota ceiling + on the billing project. Report the enforcement result and the alert + configuration per source. Change nothing about the access layer here; report + what holds and what does not. + +Output artifact: a governance report (bounds-rejection confirmed, partition scan confirmed, budget alert and quota set) +Done when: an unbounded query is confirmed rejected, a bounded query is confirmed to scan only its partitions, and a budget alert exists +Fails look like: an unbounded scan reaching the warehouse. It is a cost incident waiting for a cron job, and it bills for the whole history every time it runs. + +### Phase 5: Stand up the sensing layer · lane: convergent (Tholo) + +Skills: monitoring-and-alerting, analytics-strategy +Capability class: sensing.standup (substitute equivalents if off-catalog) +Input: the metric warehouse with at least one series accruing +Run: + + Invoke monitoring-and-alerting to define the sensing layer and analytics-strategy + to decide what is worth sensing. Per series, set a freshness threshold and a + movement threshold sized to that series' own cadence, a cadence check that + fires when an expected update is late, and an anomaly flag on a schedule. Each + threshold is derived from the series' own history, never copied from another + series. Emit the sensing definitions and the schedule; the layer flags and + never acts. + +Output artifact: the sensing definitions per series (freshness, movement, cadence, anomaly) and the schedule +Done when: every live series has thresholds derived from its own history and a scheduled check, and the layer only flags +Fails look like: thresholds copied between series of different cadences. A daily series' movement band applied to a weekly one alarms on every normal week and trains the team to ignore it. + +### Phase 6: Verification pass · lane: gate (Basano) + +Skills: data-warehouse-experimentation (nearest anchor; procedure inline) +Capability class: warehouse.verify (declared catalog gap; nearest-miss data-warehouse-experimentation) +Input: the wired plane; one known query per source +Run: + + Invoke data-warehouse-experimentation's verification discipline as a gate. + Round-trip one bounded query per source through the read path: a + search-console query, an analytics query, and a warehouse derivation, each + with a date range, each returning the expected shape against a value known by + hand. Confirm the position offset is applied where it should be. Report pass + or fail per source with the returned evidence. Report only. + +Output artifact: a verification report (one bounded round-trip per source, expected-versus-returned, offset confirmed) +Done when: each source returns the expected shape through the bounded path, or the discrepancy is filed with its evidence +Fails look like: verifying the warehouse holds data without verifying the read path returns it correctly. The tables can be perfect while the domain layer drops the offset, and every downstream number inherits the error. + +## Failure modes + +- Exports enabled last: history that never exists (Phase 1's failure, the load-bearing one). +- One store, both jobs: metric history and operational decisions in a single store, coupling cost to writes and losing the boundary. +- Unbounded scans: a warehouse call with no partition filter (Phase 4's failure), a cost incident waiting for a cron job. +- Copied sensing thresholds: bands moved between series of different cadences (Phase 5's failure), which alarms on normal variation. +- Region drift: exports landing in mismatched regions, which forces a migration to join them. +- Read path unverified: trusting the tables without proving the domain layer returns them with the offsets applied. + +## Worked example + +Pending. Populates when this workflow is executed as written on a showcase-designated property; the scheduled occasion is the search-console bulk-export and warehouse enablement session on an outdoor-sports content property, already on the critical path. Status flips to validated when that run record links here. + +## Boundaries + +- Data Surface Integrity (design v2, publishing later) consumes the series this workflow stands up; this owns the plane, that owns the freshness and consistency of what renders from it. +- Conversion-by-Source Diagnosis and Revenue Tracking Integrity read through the bounded access this workflow wires; each states its own warehouse bounds and inherits them here. +- Content Pipeline with Prove Gates ranks from the demand data this plane serves; the export enablement here is the prerequisite its demand source assumes.

`, `


Pulse · music streaming Sound that moves with you. Playful / Expressive Maximalist / Companion / Resonant See Pulse demo example →	Forge · boutique fitness Show up. Get hammered. Provocative / Expressive Maximalist / Coach / Resonant See Forge demo example →

Bloom · adaptogenic soda Soda that loves you back. Playful / Expressive Maximalist / Companion / Resonant See Bloom demo example →	Observatory Editorial · observability tool An open-source tool that respects engineer time. Conversational / Editorial Restrained / Peer / Considered See Observatory demo example →